Add HTTP routes, app wiring, V1 migration, backups, templates and API tests

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
This commit is contained in:
Elijah 2026-11-11 08:22:47 -07:00
parent 3e74ecd843
commit eae109c166
11 changed files with 2085 additions and 1 deletions

271
server/routes/ai.ts Normal file
View file

@ -0,0 +1,271 @@
import { Hono, type Context } from 'hono';
import { streamSSE } from 'hono/streaming';
import { z } from 'zod';
import { assistantRequestSchema, displayMessages, listConversations, resolveAction, runAssistantTurn, type AssistantEvent } from '../ai/assistant.ts';
import {
cancelGeneration,
createDraft,
discardDraft,
draftSaveSchema,
generateRequestSchema,
getDraft,
improveRequestSchema,
listDrafts,
saveDraft,
startGeneration,
startImprove,
updateDraftPayload,
} from '../ai/generate.ts';
import { CATALOG_UPDATED, listAdapterMeta } from '../ai/providers/index.ts';
import {
addManualModel,
aiStatus,
deleteModel,
deleteProvider,
discoverModels,
getTaskSettings,
listModels,
listProviders,
manualModelSchema,
modelPatchSchema,
patchModel,
providerInputSchema,
runChat,
saveProvider,
saveTaskSettings,
TASK_INFO,
testProvider,
usageSummary,
} from '../ai/service.ts';
import { AIError } from '../ai/types.ts';
import { badRequest, idParam, notFound, readBody, type AppContext } from '../http.ts';
type Emit<T> = (event: T) => void;
/** Server-sent events with ordered writes, keep-alive pings and abort propagation. */
function sse<T extends { type: string }>(c: Context, run: (emit: Emit<T>, signal: AbortSignal) => Promise<void>) {
c.header('X-Accel-Buffering', 'no');
c.header('Cache-Control', 'no-cache, no-transform');
return streamSSE(c, async (stream) => {
const controller = new AbortController();
stream.onAbort(() => controller.abort());
let chain: Promise<unknown> = Promise.resolve();
const emit = (event: T | { type: 'ping' }) => {
chain = chain.then(() => stream.writeSSE({ data: JSON.stringify(event) })).catch(() => undefined);
};
const ping = setInterval(() => emit({ type: 'ping' }), 15_000);
try {
await run(emit, controller.signal);
} finally {
clearInterval(ping);
await chain;
}
});
}
const contentDraftSchema = z.discriminatedUnion('kind', [
z.object({
kind: z.literal('quiz'),
title: z.string().max(200),
description: z.string().max(4000).optional().default(''),
questions: z
.array(
z.object({
type: z.enum(['single', 'multi']),
stem: z.string().max(20000),
options: z.array(z.object({ text: z.string().max(4000), correct: z.boolean(), why: z.string().max(20000).optional() })).max(12),
rationale: z.string().max(20000).optional().default(''),
topic: z.string().max(80).optional().default(''),
difficulty: z.enum(['easy', 'medium', 'hard']).optional().default('medium'),
tags: z.array(z.string().max(40)).max(12).optional().default([]),
source: z.string().max(300).optional(),
}),
)
.max(1000),
}),
z.object({
kind: z.literal('deck'),
title: z.string().max(200),
description: z.string().max(4000).optional().default(''),
cards: z.array(z.object({ front: z.string().max(20000), back: z.string().max(20000), hint: z.string().max(20000).optional(), tags: z.array(z.string().max(40)).max(12).optional().default([]) })).max(5000),
}),
z.object({ kind: z.literal('note'), title: z.string().max(200), content: z.string().max(400000) }),
]);
const EXPLAIN_SYSTEM = `You are a patient nursing instructor helping a student while they study. Explain clearly and briefly (aim for under 200 words unless asked for more).
Use Markdown. Lead with the key idea, explain the reasoning, and connect it to patient care. If answer choices are given, say why the correct one is right and, in a line each, why the others are wrong. Do not restate the whole question.`;
export function aiRoutes(app: AppContext): Hono {
const { db } = app;
const r = new Hono();
/* ------------------------------ configuration ------------------------------ */
r.get('/ai/meta', (c) => c.json({ adapters: listAdapterMeta(), tasks: TASK_INFO, catalogUpdated: CATALOG_UPDATED }));
r.get('/ai/status', (c) => c.json(aiStatus(app)));
r.get('/ai/providers', (c) => c.json({ providers: listProviders(app) }));
r.post('/ai/providers', async (c) => c.json({ provider: saveProvider(app, null, await readBody(c, providerInputSchema)) }, 201));
r.patch('/ai/providers/:id', async (c) => c.json({ provider: saveProvider(app, idParam(c), await readBody(c, providerInputSchema)) }));
r.delete('/ai/providers/:id', (c) => {
deleteProvider(app, idParam(c));
return c.json({ ok: true });
});
r.post('/ai/providers/:id/test', async (c) => c.json({ result: await testProvider(app, idParam(c)) }));
r.post('/ai/providers/:id/discover', async (c) => {
const result = await discoverModels(app, idParam(c));
return c.json({ ...result, models: listModels(db) });
});
r.get('/ai/models', (c) => c.json({ models: listModels(db) }));
r.post('/ai/models', async (c) => c.json({ model: addManualModel(app, await readBody(c, manualModelSchema)) }, 201));
r.patch('/ai/models/:id', async (c) => c.json({ model: patchModel(db, idParam(c), await readBody(c, modelPatchSchema)) }));
r.delete('/ai/models/:id', (c) => {
deleteModel(db, idParam(c));
return c.json({ ok: true });
});
r.get('/ai/tasks', (c) => c.json({ tasks: getTaskSettings(db) }));
r.put('/ai/tasks', async (c) => c.json({ tasks: saveTaskSettings(db, await c.req.json().catch(() => ({}))) }));
r.get('/ai/usage', (c) => c.json(usageSummary(db, Math.min(Math.max(Number(c.req.query('days') ?? 30) || 30, 1), 365))));
/* ------------------------------ generation + drafts ------------------------------ */
r.post('/ai/generate', async (c) => {
const body = await readBody(c, generateRequestSchema);
const { draftId } = startGeneration(app, body);
return c.json({ draftId }, 202);
});
r.post('/ai/improve', async (c) => {
const body = await readBody(c, improveRequestSchema);
const { draftId } = startImprove(app, body);
return c.json({ draftId }, 202);
});
r.get('/drafts', (c) => c.json({ drafts: listDrafts(db) }));
/** A blank or pre-filled draft, used by the import preview so imports and AI output share one review screen. */
r.post('/drafts', async (c) => {
const body = await readBody(c, z.object({ payload: contentDraftSchema, classId: z.string().nullish(), folderId: z.string().nullish() }));
const id = createDraft(db, { kind: body.payload.kind, classId: body.classId ?? null, folderId: body.folderId ?? null, title: body.payload.title, payload: body.payload as never, meta: { origin: 'import' } });
return c.json({ draft: getDraft(db, id) }, 201);
});
r.get('/drafts/:id', (c) => c.json({ draft: getDraft(db, idParam(c)) }));
r.put('/drafts/:id', async (c) => {
const body = await readBody(c, z.object({ payload: contentDraftSchema, classId: z.string().nullish(), folderId: z.string().nullish() }));
return c.json({ draft: updateDraftPayload(db, idParam(c), body.payload as never, { classId: body.classId, folderId: body.folderId }) });
});
r.post('/drafts/:id/save', async (c) => {
const body = await readBody(c, draftSaveSchema);
return c.json({ saved: saveDraft(app, idParam(c), body) });
});
r.post('/drafts/:id/cancel', (c) => {
cancelGeneration(idParam(c));
return c.json({ ok: true });
});
r.delete('/drafts/:id', (c) => {
discardDraft(db, idParam(c));
return c.json({ ok: true });
});
/* ------------------------------ assistant ------------------------------ */
r.post('/ai/chat', async (c) => {
const body = await readBody(c, assistantRequestSchema);
return sse<AssistantEvent>(c, async (emit, signal) => {
try {
await runAssistantTurn(app, body, emit, signal);
} catch (err) {
// Failures before the turn starts (no model configured, bad input) still reach the client as an event.
const ai = err instanceof AIError ? err : null;
if (!ai) app.log('error', 'Assistant request failed', err);
emit({ type: 'error', code: ai?.code ?? 'server', message: ai?.message ?? 'The assistant could not start.', detail: ai?.providerMessage });
emit({ type: 'done', conversationId: body.conversationId ?? '', title: '' });
}
});
});
r.get('/ai/conversations', (c) => c.json({ conversations: listConversations(db) }));
r.get('/ai/conversations/:id', (c) => {
const id = idParam(c);
const row = db.get<{ id: string; title: string; class_id: string | null }>('SELECT id, title, class_id FROM conversations WHERE id = ?', id);
if (!row) throw notFound('Conversation');
return c.json({ conversation: { id: row.id, title: row.title, classId: row.class_id }, messages: displayMessages(db, id) });
});
r.delete('/ai/conversations/:id', (c) => {
const { changes } = db.run('DELETE FROM conversations WHERE id = ?', idParam(c));
if (!changes) throw notFound('Conversation');
return c.json({ ok: true });
});
r.post('/ai/actions/:id', async (c) => {
const body = await readBody(c, z.object({ confirm: z.boolean() }));
return c.json(resolveAction(app, idParam(c), body.confirm));
});
/* ------------------------------ inline explanations ------------------------------ */
const explainSchema = z.discriminatedUnion('kind', [
z.object({
kind: z.literal('question'),
stem: z.string().max(20000),
options: z.array(z.object({ text: z.string().max(4000), correct: z.boolean() })).max(12),
selected: z.array(z.string().max(4000)).max(12).optional(),
rationale: z.string().max(20000).optional(),
ask: z.string().max(2000).optional(),
}),
z.object({ kind: z.literal('card'), front: z.string().max(20000), back: z.string().max(20000), ask: z.string().max(2000).optional() }),
z.object({ kind: z.literal('text'), text: z.string().max(40000), ask: z.string().max(2000).optional() }),
]);
r.post('/ai/explain', async (c) => {
const body = await readBody(c, explainSchema);
let prompt: string;
if (body.kind === 'question') {
prompt = [
`Question:\n${body.stem}`,
`Choices:\n${body.options.map((o) => `- ${o.text}${o.correct ? ' (correct)' : ''}`).join('\n')}`,
body.selected?.length ? `The student chose: ${body.selected.join('; ')}` : '',
body.rationale ? `Existing rationale:\n${body.rationale}` : '',
body.ask ? `The student asks: ${body.ask}` : 'Explain this question so it finally makes sense. If the student chose wrongly, address the misunderstanding behind their choice.',
]
.filter(Boolean)
.join('\n\n');
} else if (body.kind === 'card') {
prompt = `Flashcard front:\n${body.front}\n\nFlashcard back:\n${body.back}\n\n${body.ask ? `The student asks: ${body.ask}` : 'Explain this card in more depth and give one way to remember it.'}`;
} else {
prompt = `${body.text}\n\n${body.ask ? `The student asks: ${body.ask}` : 'Explain this passage in simpler terms and point out what is most important to remember.'}`;
}
if (!prompt.trim()) throw badRequest('Nothing to explain');
return sse<{ type: 'text'; delta: string } | { type: 'error'; message: string; code: string } | { type: 'done' }>(c, async (emit, signal) => {
try {
await runChat(app, {
task: 'quick',
purpose: 'explanation',
system: EXPLAIN_SYSTEM,
messages: [{ role: 'user', content: [{ type: 'text', text: prompt }] }],
maxOutputTokens: 1500,
signal,
onEvent: (e) => {
if (e.type === 'text') emit({ type: 'text', delta: e.delta });
},
});
} catch (err) {
const ai = err instanceof AIError ? err : null;
if (ai?.code !== 'aborted') emit({ type: 'error', code: ai?.code ?? 'server', message: ai?.message ?? 'The explanation could not be generated.' });
}
emit({ type: 'done' });
});
});
return r;
}

249
server/routes/data.ts Normal file
View file

@ -0,0 +1,249 @@
import fs from 'node:fs';
import os from 'node:os';
import path from 'node:path';
import { Hono } from 'hono';
import { bodyLimit } from 'hono/body-limit';
import { z } from 'zod';
import { questionToDraft, validateDraft, type ContentDraft } from '../../shared/content.ts';
import { draftsFromValue } from '../../shared/importer.ts';
import { badRequest, HttpError, idParam, readBody, type AppContext } from '../http.ts';
import { appSettingsSchema, getAppSettings, setSetting } from '../settings.ts';
import { createSnapshot, exportBundle, fullBackupStream, listBackups } from '../services/backup.ts';
import { createClass, createDeck, createFolder, createNote, createQuiz, draftCardToInput, draftQuestionToInput, getClass, getDeck, getQuiz, listCards, listQuestions } from '../services/content.ts';
import { createTemplate, deleteTemplate, listTemplates, templateInputSchema, updateTemplate } from '../services/templates.ts';
import { importV1 } from '../services/v1import.ts';
import { slugify } from '../util.ts';
export const APP_VERSION = '2.0.0';
function dirSize(dir: string): number {
try {
return fs.readdirSync(dir).reduce((n, f) => {
const st = fs.statSync(path.join(dir, f));
return n + (st.isFile() ? st.size : 0);
}, 0);
} catch {
return 0;
}
}
/** Creates library items from reviewed drafts. Used by the importer and by bundle restore. */
function createFromDraft(app: AppContext, draft: ContentDraft, classId: string, folderId: string | null): { kind: string; id: string; title: string } {
const { db } = app;
if (draft.kind === 'quiz') {
const quiz = createQuiz(db, { classId, folderId, title: draft.title.trim() || 'Imported quiz', description: draft.description ?? '', questions: draft.questions.map(draftQuestionToInput) });
return { kind: 'quiz', id: quiz.id, title: quiz.title };
}
if (draft.kind === 'deck') {
const deck = createDeck(db, { classId, folderId, title: draft.title.trim() || 'Imported deck', description: draft.description ?? '', cards: draft.cards.map(draftCardToInput) });
return { kind: 'deck', id: deck.id, title: deck.title };
}
const note = createNote(db, { classId, folderId, title: draft.title.trim() || 'Imported note', content: draft.content });
return { kind: 'note', id: note.id, title: note.title };
}
export function dataRoutes(app: AppContext): Hono {
const { db } = app;
const r = new Hono();
/* ------------------------------ settings ------------------------------ */
r.get('/settings', (c) => {
const count = (table: string) => db.get<{ n: number }>(`SELECT COUNT(*) AS n FROM ${table}`)?.n ?? 0;
let dbSize = 0;
try {
dbSize = fs.statSync(app.config.dbPath).size;
} catch {
/* in-memory */
}
return c.json({
settings: getAppSettings(db, app.config.timezone),
system: {
version: APP_VERSION,
node: process.version,
dataDir: app.config.dataDir,
databaseBytes: dbSize,
uploadBytes: dirSize(app.config.uploadsDir) + dirSize(app.config.mediaDir),
maxUploadMb: Math.round(app.config.maxUploadBytes / 1048576),
counts: { classes: count('classes'), quizzes: count('quizzes'), questions: count('questions'), decks: count('decks'), cards: count('cards'), documents: count('documents'), notes: count('notes') },
timezones: typeof Intl.supportedValuesOf === 'function' ? Intl.supportedValuesOf('timeZone') : [],
},
});
});
r.put('/settings', async (c) => {
const patch = await readBody(c, appSettingsSchema.partial());
if (patch.timezone) {
try {
new Intl.DateTimeFormat('en-US', { timeZone: patch.timezone });
} catch {
throw badRequest('Unknown timezone');
}
}
const next = { ...getAppSettings(db, app.config.timezone), ...patch };
setSetting(db, 'app', next);
return c.json({ settings: next });
});
/* ------------------------------ import ------------------------------ */
r.post('/import', bodyLimit({ maxSize: 30 * 1024 * 1024 }), async (c) => {
const body = await readBody(c, z.object({ classId: z.string(), folderId: z.string().nullish(), items: z.array(z.unknown()).min(1).max(200) }));
getClass(db, body.classId);
const drafts: ContentDraft[] = [];
body.items.forEach((raw, i) => {
const parsed = draftsFromValue(raw).items[0];
if (!parsed) throw new HttpError(422, 'validation', `Item ${i + 1} is not a quiz, deck or note`);
const errors = validateDraft(parsed).filter((x) => x.level === 'error');
if (errors.length > 0) {
const first = errors[0];
const where = first.index !== undefined ? `${parsed.kind === 'quiz' ? 'question' : 'card'} ${first.index + 1}` : first.field ?? 'item';
throw new HttpError(422, 'validation', `"${parsed.title || `Item ${i + 1}`}", ${where}: ${first.message}`, { item: i, issues: errors });
}
drafts.push(parsed);
});
const created = db.tx(() => drafts.map((d) => createFromDraft(app, d, body.classId, body.folderId ?? null)));
return c.json({ created }, 201);
});
/** Restores a JSON bundle produced by "Export everything": recreates classes, folders and their contents. */
r.post('/import/bundle', bodyLimit({ maxSize: 100 * 1024 * 1024 }), async (c) => {
const body = (await c.req.json().catch(() => {
throw badRequest('The file is not valid JSON');
})) as Record<string, unknown>;
const classes = Array.isArray(body.classes) ? (body.classes as Record<string, unknown>[]) : null;
if (!classes) throw badRequest('This file is not a Study Desk bundle. Use "Import" inside a class for single quizzes and decks.');
const existing = new Set(db.all<{ name: string }>('SELECT name FROM classes').map((x) => x.name.toLowerCase()));
const summary = { classes: 0, quizzes: 0, decks: 0, notes: 0, skipped: [] as string[] };
db.tx(() => {
for (const raw of classes) {
let name = String(raw.name ?? 'Imported class').trim().slice(0, 110) || 'Imported class';
if (existing.has(name.toLowerCase())) name = `${name} (imported)`;
existing.add(name.toLowerCase());
const color = typeof raw.color === 'string' ? raw.color : undefined;
const cls = createClass(db, { name, code: String(raw.code ?? '').slice(0, 40), description: String(raw.description ?? '').slice(0, 2000), color: color as never });
summary.classes += 1;
const folders = new Map<string, string>();
for (const f of Array.isArray(raw.folders) ? raw.folders : []) {
const fname = String(typeof f === 'string' ? f : (f as Record<string, unknown>)?.name ?? '').trim();
if (fname) folders.set(fname, createFolder(db, cls.id, fname).id);
}
for (const key of ['quizzes', 'decks', 'notes'] as const) {
for (const item of Array.isArray(raw[key]) ? (raw[key] as Record<string, unknown>[]) : []) {
const kind = key === 'quizzes' ? 'quiz' : key === 'decks' ? 'deck' : 'note';
const draft = draftsFromValue({ ...item, kind }).items[0];
const title = String(item?.title ?? 'Untitled');
if (!draft) {
summary.skipped.push(`${title} (unreadable)`);
continue;
}
// Drop invalid entries rather than failing a whole restore; report what was left out.
if (draft.kind === 'quiz') {
const before = draft.questions.length;
draft.questions = draft.questions.filter((q) => !validateDraft({ ...draft, questions: [q] }).some((x) => x.level === 'error' && x.index !== undefined));
if (draft.questions.length < before) summary.skipped.push(`${before - draft.questions.length} invalid question(s) in "${title}"`);
} else if (draft.kind === 'deck') {
const before = draft.cards.length;
draft.cards = draft.cards.filter((card) => card.front?.trim() && card.back?.trim());
if (draft.cards.length < before) summary.skipped.push(`${before - draft.cards.length} empty card(s) in "${title}"`);
}
const folderId = typeof item.folder === 'string' ? (folders.get(item.folder) ?? null) : null;
createFromDraft(app, draft, cls.id, folderId);
summary[key] += 1;
}
}
}
});
return c.json({ summary }, 201);
});
/** Migration from a V1 database file. `?preview=1` only reports what would be imported. */
r.post('/import/v1', bodyLimit({ maxSize: 500 * 1024 * 1024 }), async (c) => {
const form = await c.req.parseBody().catch(() => {
throw badRequest('Upload could not be read');
});
const file = form.file;
if (!file || typeof file === 'string') throw badRequest('Choose your V1 study.db file');
const bytes = new Uint8Array(await file.arrayBuffer());
if (new TextDecoder().decode(bytes.subarray(0, 15)) !== 'SQLite format 3') throw badRequest('That file is not a SQLite database.');
const tmp = path.join(os.tmpdir(), `studydesk-v1-${Date.now()}-${Math.random().toString(36).slice(2)}.db`);
fs.writeFileSync(tmp, bytes);
try {
const preview = c.req.query('preview') === '1';
if (!preview) createSnapshot(app, 'pre-v1-import');
return c.json({ preview, summary: importV1(app, tmp, { dryRun: preview }) });
} finally {
fs.rmSync(tmp, { force: true });
}
});
/* ------------------------------ export + backup ------------------------------ */
r.get('/export/all', (c) => {
c.header('Content-Disposition', `attachment; filename="studydesk-export-${new Date().toISOString().slice(0, 10)}.json"`);
return c.json(exportBundle(app));
});
r.get('/export/class/:id', (c) => {
const cls = getClass(db, idParam(c));
c.header('Content-Disposition', `attachment; filename="${slugify(cls.name)}.class.json"`);
return c.json(exportBundle(app, cls.id));
});
r.get('/backup/download', () => {
const { stream, filename } = fullBackupStream(app);
return new Response(stream, { headers: { 'Content-Type': 'application/zip', 'Content-Disposition': `attachment; filename="${filename}"`, 'Cache-Control': 'no-store' } });
});
r.get('/backups', (c) => c.json({ backups: listBackups(app), directory: app.config.backupsDir }));
r.post('/backups', (c) => c.json({ backup: createSnapshot(app) }, 201));
r.get('/backups/:name', (c) => {
const name = path.basename(c.req.param('name'));
const file = path.join(app.config.backupsDir, name);
if (!name.endsWith('.db') || !fs.existsSync(file)) throw new HttpError(404, 'not_found', 'Backup not found');
return new Response(fs.readFileSync(file), { headers: { 'Content-Type': 'application/octet-stream', 'Content-Disposition': `attachment; filename="${name}"`, 'Cache-Control': 'no-store' } });
});
/* ------------------------------ templates ------------------------------ */
r.get('/templates', (c) => c.json({ templates: listTemplates(db, c.req.query('kind') || undefined) }));
r.post('/templates', async (c) => c.json({ template: createTemplate(db, await readBody(c, templateInputSchema)) }, 201));
/** Saves an existing quiz or deck as a reusable template. */
r.post('/templates/from', async (c) => {
const body = await readBody(c, z.object({ kind: z.enum(['quiz', 'deck']), id: z.string(), name: z.string().trim().min(1).max(120).optional() }));
if (body.kind === 'quiz') {
const quiz = getQuiz(db, body.id);
return c.json({ template: createTemplate(db, { kind: 'quiz', name: body.name ?? quiz.title, description: quiz.description.slice(0, 1000), payload: { title: quiz.title, description: quiz.description, questions: listQuestions(db, quiz.id).map(questionToDraft) } }) }, 201);
}
const deck = getDeck(db, body.id);
return c.json(
{ template: createTemplate(db, { kind: 'deck', name: body.name ?? deck.title, description: deck.description.slice(0, 1000), payload: { title: deck.title, description: deck.description, cards: listCards(db, deck.id).map((x) => ({ front: x.front, back: x.back, hint: x.hint, tags: x.tags })) } }) },
201,
);
});
/** Creates a new quiz or deck from a content template. */
r.post('/templates/:id/use', async (c) => {
const body = await readBody(c, z.object({ classId: z.string(), folderId: z.string().nullish(), title: z.string().trim().max(200).optional() }));
const tpl = listTemplates(db).find((t) => t.id === idParam(c));
if (!tpl || tpl.kind === 'generation') throw new HttpError(404, 'not_found', 'Template not found');
const draft = draftsFromValue({ ...tpl.payload, kind: tpl.kind, title: body.title || tpl.payload.title || tpl.name }).items[0];
if (!draft) throw badRequest('This template is empty');
return c.json({ created: createFromDraft(app, draft, body.classId, body.folderId ?? null) }, 201);
});
r.patch('/templates/:id', async (c) => {
const body = await readBody(c, z.object({ name: z.string().max(120).optional(), description: z.string().max(1000).optional(), payload: z.record(z.string(), z.unknown()).optional() }));
return c.json({ template: updateTemplate(db, idParam(c), body) });
});
r.delete('/templates/:id', (c) => {
deleteTemplate(db, idParam(c));
return c.json({ ok: true });
});
return r;
}

174
server/routes/documents.ts Normal file
View file

@ -0,0 +1,174 @@
import fs from 'node:fs';
import path from 'node:path';
import crypto from 'node:crypto';
import { Hono } from 'hono';
import { bodyLimit } from 'hono/body-limit';
import { z } from 'zod';
import { titleSchema } from '../../shared/content.ts';
import { badRequest, HttpError, idParam, readBody, type AppContext } from '../http.ts';
import { getClass, mapClass, resolveFolder } from '../services/content.ts';
import { deleteDocument, documentPath, enqueue, getDocument, ingestUpload, listChunks, mapDocument, sourceLabel } from '../services/documents.ts';
import { now } from '../util.ts';
import { shareFor } from './library.ts';
const IMAGE_TYPES: Record<string, { ext: string; test: (b: Uint8Array) => boolean }> = {
'image/png': { ext: 'png', test: (b) => b[0] === 0x89 && b[1] === 0x50 && b[2] === 0x4e && b[3] === 0x47 },
'image/jpeg': { ext: 'jpg', test: (b) => b[0] === 0xff && b[1] === 0xd8 && b[2] === 0xff },
'image/gif': { ext: 'gif', test: (b) => b[0] === 0x47 && b[1] === 0x49 && b[2] === 0x46 },
'image/webp': { ext: 'webp', test: (b) => b[0] === 0x52 && b[1] === 0x49 && b[8] === 0x57 && b[9] === 0x45 },
};
export function documentRoutes(app: AppContext): Hono {
const { db } = app;
const r = new Hono();
const uploadLimit = bodyLimit({
maxSize: app.config.maxUploadBytes + 1024 * 1024,
onError: () => {
throw new HttpError(413, 'too_large', `That file is larger than the ${Math.round(app.config.maxUploadBytes / 1048576)} MB upload limit.`);
},
});
r.post('/documents', uploadLimit, async (c) => {
const form = await c.req.parseBody({ all: true }).catch(() => {
throw badRequest('Upload could not be read');
});
const classId = typeof form.classId === 'string' ? form.classId : '';
const folderId = typeof form.folderId === 'string' && form.folderId ? form.folderId : null;
const raw = form.file ?? form.files;
const files = (Array.isArray(raw) ? raw : [raw]).filter((f): f is File => typeof f === 'object' && f !== null && 'arrayBuffer' in f);
if (!classId) throw badRequest('classId is required');
if (files.length === 0) throw badRequest('Choose a file to upload');
const created = [];
for (const file of files) {
const bytes = new Uint8Array(await file.arrayBuffer());
created.push(mapDocument(ingestUpload(app, { classId, folderId, filename: file.name || 'upload', mime: file.type || undefined, bytes })));
}
return c.json({ documents: created }, 201);
});
/** Pasted notes become a Markdown document, so they are searchable and usable by AI like any upload. */
r.post('/documents/text', async (c) => {
const body = await readBody(c, z.object({ classId: z.string(), folderId: z.string().nullish(), title: titleSchema, text: z.string().trim().min(1).max(2_000_000) }));
const doc = ingestUpload(app, {
classId: body.classId,
folderId: body.folderId,
filename: `${body.title.replace(/[^\w\- ]+/g, '').trim().slice(0, 80) || 'notes'}.md`,
mime: 'text/markdown',
bytes: new TextEncoder().encode(body.text),
title: body.title,
});
return c.json({ document: mapDocument(doc) }, 201);
});
r.get('/documents/:id', (c) => {
const doc = getDocument(db, idParam(c));
const outline = db
.all<{ seq: number; heading: string; page_start: number | null }>(`SELECT MIN(seq) AS seq, heading, MIN(page_start) AS page_start FROM chunks WHERE document_id = ? AND heading != '' GROUP BY heading ORDER BY seq LIMIT 200`, doc.id)
.map((o) => ({ seq: o.seq, heading: o.heading, page: o.page_start }));
return c.json({ document: mapDocument(doc), class: mapClass(getClass(db, doc.class_id)), outline, share: shareFor(app, 'document', doc.id) });
});
r.get('/documents/:id/chunks', (c) => {
const doc = getDocument(db, idParam(c));
const offset = Math.max(0, Number(c.req.query('offset') ?? 0) || 0);
const limit = Math.min(100, Math.max(1, Number(c.req.query('limit') ?? 40) || 40));
const chunks = listChunks(db, doc.id, offset, limit);
return c.json({
chunks: chunks.map((ch) => ({ id: ch.id, seq: ch.seq, text: ch.text, heading: ch.heading, pageStart: ch.pageStart, pageEnd: ch.pageEnd, label: sourceLabel(ch) })),
total: doc.chunk_count,
nextOffset: chunks.length === limit && offset + limit < doc.chunk_count ? offset + limit : null,
});
});
r.get('/documents/:id/status', (c) => {
const doc = getDocument(db, idParam(c));
return c.json({ document: mapDocument(doc) });
});
r.get('/documents/:id/file', (c) => {
const doc = getDocument(db, idParam(c));
const file = documentPath(app, doc);
if (!fs.existsSync(file)) throw new HttpError(404, 'not_found', 'The original file is missing from storage');
const inline = doc.kind === 'pdf' || doc.kind === 'image';
const download = c.req.query('download') === '1';
return new Response(fs.readFileSync(file), {
headers: {
'Content-Type': inline ? doc.mime : 'application/octet-stream',
'Content-Disposition': `${inline && !download ? 'inline' : 'attachment'}; filename*=UTF-8''${encodeURIComponent(doc.filename)}`,
'X-Content-Type-Options': 'nosniff',
// Uploaded files are untrusted. PDFs and images are served with their verified type (sniffing off);
// everything else is forced to download.
...(inline ? {} : { 'Content-Security-Policy': "default-src 'none'; sandbox" }),
'Cache-Control': 'private, max-age=3600',
},
});
});
r.patch('/documents/:id', async (c) => {
const doc = getDocument(db, idParam(c));
const body = await readBody(c, z.object({ title: titleSchema.optional(), folderId: z.string().nullish() }));
db.run(
'UPDATE documents SET title = ?, folder_id = ?, updated_at = ? WHERE id = ?',
body.title ?? doc.title,
body.folderId === undefined ? doc.folder_id : resolveFolder(db, doc.class_id, body.folderId),
now(),
doc.id,
);
return c.json({ document: mapDocument(getDocument(db, doc.id)) });
});
r.post('/documents/:id/reprocess', async (c) => {
const doc = getDocument(db, idParam(c));
const body = (await c.req.json().catch(() => ({}))) as { ocr?: unknown };
db.run(`UPDATE documents SET status = 'pending', error = '', progress = 0, updated_at = ? WHERE id = ?`, now(), doc.id);
enqueue(app, doc.id, { ocr: body.ocr === true });
return c.json({ document: mapDocument(getDocument(db, doc.id)) });
});
r.delete('/documents/:id', (c) => {
deleteDocument(app, idParam(c));
return c.json({ ok: true });
});
/* ------------------------------ images embedded in questions, cards and notes ------------------------------ */
r.post('/media', bodyLimit({ maxSize: 12 * 1024 * 1024 }), async (c) => {
const form = await c.req.parseBody().catch(() => {
throw badRequest('Upload could not be read');
});
const file = form.file;
if (!file || typeof file === 'string') throw badRequest('Choose an image');
const bytes = new Uint8Array(await file.arrayBuffer());
if (bytes.length > 10 * 1024 * 1024) throw new HttpError(413, 'too_large', 'Images can be up to 10 MB.');
// Trust the bytes, not the declared type. SVG is deliberately not accepted (it can carry script).
const match = Object.entries(IMAGE_TYPES).find(([, t]) => t.test(bytes));
if (!match) throw new HttpError(415, 'unsupported_type', 'Use a PNG, JPEG, GIF or WebP image.');
const [mime, { ext }] = match;
const id = `${crypto.randomBytes(16).toString('base64url')}.${ext}`;
fs.writeFileSync(path.join(app.config.mediaDir, id), bytes);
db.run('INSERT INTO media (id, filename, mime, size, created_at) VALUES (?, ?, ?, ?, ?)', id, (file.name || 'image').slice(0, 200), mime, bytes.length, now());
return c.json({ url: `/media/${id}`, markdown: `![${(file.name || 'image').replace(/[[\]]/g, '')}](/media/${id})` }, 201);
});
return r;
}
/**
* Public image route. Images are addressed by an unguessable 128-bit name, which is what lets
* a shared quiz show its pictures to visitors without exposing anything else.
*/
export function mediaRoute(app: AppContext): Hono {
const r = new Hono();
r.get('/:name', (c) => {
const name = c.req.param('name');
if (!/^[A-Za-z0-9_-]{16,40}\.(png|jpg|gif|webp)$/.test(name)) throw new HttpError(404, 'not_found', 'Not found');
const row = app.db.get<{ mime: string }>('SELECT mime FROM media WHERE id = ?', name);
const file = path.join(app.config.mediaDir, name);
if (!row || !fs.existsSync(file)) throw new HttpError(404, 'not_found', 'Not found');
return new Response(fs.readFileSync(file), {
headers: { 'Content-Type': row.mime, 'Cache-Control': 'public, max-age=31536000, immutable', 'X-Content-Type-Options': 'nosniff', 'Content-Security-Policy': "default-src 'none'; sandbox" },
});
});
return r;
}

View file

@ -249,7 +249,7 @@ export function publicRoutes(app: AppContext): Hono {
'Content-Type': doc.mime || 'application/octet-stream',
'Content-Disposition': `${inline ? 'inline' : 'attachment'}; filename*=UTF-8''${encodeURIComponent(doc.filename)}`,
'X-Content-Type-Options': 'nosniff',
'Content-Security-Policy': "default-src 'none'; style-src 'unsafe-inline'; sandbox",
...(inline ? {} : { 'Content-Security-Policy': "default-src 'none'; sandbox" }),
'Cache-Control': 'private, no-store',
'X-Robots-Tag': 'noindex, nofollow',
},