Study/server/routes/data.ts
Elijah 5fef59b07b
All checks were successful
Verify and publish V2 container / build-and-push (push) Successful in 30s
Remove the V1 database importer
The /api/import/v1 endpoint, server/services/v1import.ts and its test are
gone; Settings already restores full V2 backups in that place. MIGRATION.md
now covers V1 JSON exports and running the old importer from history
(7125dec), plus moving data between V2 installs.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-16 12:35:51 -07:00

287 lines
15 KiB
TypeScript

import fs from 'node:fs';
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, LLM_INSTRUCTIONS } from '../../shared/importer.ts';
import { badRequest, HttpError, idParam, readBody, type AppContext } from '../http.ts';
import { appSettingsSchema, deleteSetting, getAppSettings, getSetting, 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, resetTemplate, templateInputSchema, updateTemplate } from '../services/templates.ts';
import { restoreFullBackup } from '../services/restore.ts';
import { sessionHash } from '../auth.ts';
import { slugify } from '../util.ts';
export const APP_VERSION = '2.0.0';
/** The largest full backup that can be restored through the app. */
const RESTORE_MAX_BYTES = 20 * 1024 ** 3;
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 });
});
/* ------------------------------ instructions for outside chatbots ------------------------------ */
r.get('/llm-instructions', (c) =>
c.json({
quiz: getSetting<string | null>(db, 'llm.quiz', null) ?? LLM_INSTRUCTIONS.quiz,
deck: getSetting<string | null>(db, 'llm.deck', null) ?? LLM_INSTRUCTIONS.deck,
customized: { quiz: getSetting<string | null>(db, 'llm.quiz', null) !== null, deck: getSetting<string | null>(db, 'llm.deck', null) !== null },
builtin: LLM_INSTRUCTIONS,
}),
);
/** Saves an edited copy; `text: null` goes back to the built-in wording. */
r.put('/llm-instructions', async (c) => {
const body = await readBody(c, z.object({ kind: z.enum(['quiz', 'deck']), text: z.string().trim().min(20).max(20000).nullable() }));
if (body.text === null) deleteSetting(db, `llm.${body.kind}`);
else setSetting(db, `llm.${body.kind}`, body.text);
return c.json({ ok: true });
});
/* ------------------------------ 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);
});
/**
* Restores a full backup zip (from "Download backup"): the database with every setting, and the
* uploaded files. The zip is the raw request body, streamed to disk. See services/restore.ts.
*/
r.post('/backup/restore', async (c) => {
const max = RESTORE_MAX_BYTES;
const declared = Number(c.req.header('content-length') ?? 0);
if (declared > max) throw new HttpError(413, 'too_large', 'The backup is larger than this server accepts.');
const body = c.req.raw.body;
if (!body) throw badRequest('Choose a backup zip');
const tmp = path.join(app.config.dataDir, `.restore-upload-${Date.now()}.zip`);
try {
let size = 0;
const out = fs.createWriteStream(tmp);
try {
for await (const chunk of body as unknown as AsyncIterable<Uint8Array>) {
size += chunk.length;
if (size > max) throw new HttpError(413, 'too_large', 'The backup is larger than this server accepts.');
if (!out.write(chunk)) await new Promise((r) => out.once('drain', r));
}
} finally {
await new Promise<void>((resolve, reject) => out.end((err?: Error | null) => (err ? reject(err) : resolve())));
}
if (size < 22) throw badRequest('Choose a backup zip');
const head = Buffer.alloc(4);
const fd = fs.openSync(tmp, 'r');
fs.readSync(fd, head, 0, 4, 0);
fs.closeSync(fd);
if (head.readUInt32LE(0) !== 0x04034b50) throw badRequest('That file is not a zip. Choose a file made with "Download backup".');
return c.json({ summary: await restoreFullBackup(app, tmp, { sessionHash: sessionHash(c) }) });
} 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.post('/templates/:id/reset', (c) => c.json({ template: resetTemplate(db, idParam(c)) }));
r.delete('/templates/:id', (c) => {
deleteTemplate(db, idParam(c));
return c.json({ ok: true });
});
return r;
}