Study/server/services/content.ts
Elijah c595e0ff2c
All checks were successful
Verify and publish V2 container / build-and-push (push) Successful in 1m0s
Third revision: web search, MCP sign-in, exams, intelligent UI, clarifying questions
- Built-in Parallel web search (keyless; optional sign-in for higher limits and research)
  with its own settings page; OAuth sign-in (RFC 9728/8414/7591, PKCE, RFC 8707) for any
  MCP server, with token refresh and pre-registered client support
- Friendly tool steps (icon, name, status; details on click) and ids stripped from results;
  per-chat tool switches; taller thinking box
- Exams within classes: exam tabs, scoped lists, uploads, imports and Generate; exam-only
  material for generation; class setting for what the groups are called
- Assistant can ask clarifying questions in an inline form before generating
- OpenUI blocks (charts, questions, flashcards, inputs) in assistant, Explain and share chats
- Explain beside the quiz on wide screens, grounded in the cited source pages
- Quiz results: percentage ring coloured by score band, rainbow at 100
- Share links: assistant button like the owner's, hidden during quizzes; documents readable
  in the browser
- Live draft and library updates over server-sent events

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-15 20:30:00 -07:00

523 lines
16 KiB
TypeScript

/**
* Classes, folders, quizzes, questions, decks, cards and notes.
* Used by the HTTP routes, the importer and the AI tools, so every write path
* shares one set of validation and ordering rules.
*/
import { z } from 'zod';
import {
CLASS_COLORS,
cardInputSchema,
questionInputSchema,
type Card,
type Difficulty,
type DraftCard,
type DraftQuestion,
type Option,
type Question,
type QuestionType,
} from '../../shared/content.ts';
import type { DB } from '../db.ts';
import { notFound } from '../http.ts';
import { newId, now, parseJson } from '../util.ts';
/* ------------------------------ row types ------------------------------ */
export interface ClassRow {
id: string;
name: string;
code: string;
description: string;
color: string;
archived: number;
sort_order: number;
group_label: string;
created_at: number;
updated_at: number;
}
export interface FolderRow {
id: string;
class_id: string;
name: string;
sort_order: number;
created_at: number;
updated_at: number;
}
export interface QuizRow {
id: string;
class_id: string;
folder_id: string | null;
title: string;
description: string;
sort_order: number;
created_at: number;
updated_at: number;
}
export interface QuestionRow {
id: string;
quiz_id: string;
type: QuestionType;
stem: string;
options: string;
rationale: string;
topic: string;
difficulty: Difficulty;
tags: string;
sort_order: number;
created_at: number;
updated_at: number;
}
export interface DeckRow extends QuizRow {}
export interface CardRow {
id: string;
deck_id: string;
front: string;
back: string;
hint: string;
tags: string;
sort_order: number;
suspended: number;
state: number;
due: number | null;
stability: number;
difficulty: number;
scheduled_days: number;
learning_steps: number;
reps: number;
lapses: number;
last_review: number | null;
introduced_at: number | null;
created_at: number;
updated_at: number;
}
export interface NoteRow {
id: string;
class_id: string;
folder_id: string | null;
title: string;
content: string;
kind: string;
source: string;
sort_order: number;
created_at: number;
updated_at: number;
}
/* ------------------------------ mappers ------------------------------ */
export const mapClass = (r: ClassRow) => ({
id: r.id,
name: r.name,
/** What the class calls its groups: Exam (default), Unit, Module… */
groupLabel: r.group_label || 'Exam',
code: r.code,
description: r.description,
color: r.color,
archived: Boolean(r.archived),
sortOrder: r.sort_order,
createdAt: r.created_at,
updatedAt: r.updated_at,
});
export type ClassDto = ReturnType<typeof mapClass>;
export const mapFolder = (r: FolderRow) => ({ id: r.id, classId: r.class_id, name: r.name, sortOrder: r.sort_order });
export const mapQuiz = (r: QuizRow) => ({
id: r.id,
classId: r.class_id,
folderId: r.folder_id,
title: r.title,
description: r.description,
createdAt: r.created_at,
updatedAt: r.updated_at,
});
export const mapDeck = mapQuiz;
export function mapQuestion(r: QuestionRow): Question {
return {
id: r.id,
quizId: r.quiz_id,
type: r.type,
stem: r.stem,
options: parseJson<Option[]>(r.options, []).map((o) => ({ id: o.id, text: o.text, correct: Boolean(o.correct), why: o.why ?? '' })),
rationale: r.rationale,
topic: r.topic,
difficulty: r.difficulty,
tags: parseJson<string[]>(r.tags, []),
sortOrder: r.sort_order,
createdAt: r.created_at,
updatedAt: r.updated_at,
};
}
export function mapCard(r: CardRow): Card {
return {
id: r.id,
deckId: r.deck_id,
front: r.front,
back: r.back,
hint: r.hint,
tags: parseJson<string[]>(r.tags, []),
sortOrder: r.sort_order,
suspended: Boolean(r.suspended),
state: r.state,
due: r.due,
stability: r.stability,
difficulty: r.difficulty,
scheduledDays: r.scheduled_days,
reps: r.reps,
lapses: r.lapses,
lastReview: r.last_review,
createdAt: r.created_at,
updatedAt: r.updated_at,
};
}
export const mapNote = (r: NoteRow) => ({
id: r.id,
classId: r.class_id,
folderId: r.folder_id,
title: r.title,
content: r.content,
kind: r.kind,
source: parseJson<Record<string, unknown>>(r.source, {}),
createdAt: r.created_at,
updatedAt: r.updated_at,
});
/* ------------------------------ lookups ------------------------------ */
export function getClass(db: DB, id: string): ClassRow {
const row = db.get<ClassRow>('SELECT * FROM classes WHERE id = ?', id);
if (!row) throw notFound('Class');
return row;
}
export function getFolder(db: DB, id: string): FolderRow {
const row = db.get<FolderRow>('SELECT * FROM folders WHERE id = ?', id);
if (!row) throw notFound('Folder');
return row;
}
export function getQuiz(db: DB, id: string): QuizRow {
const row = db.get<QuizRow>('SELECT * FROM quizzes WHERE id = ?', id);
if (!row) throw notFound('Quiz');
return row;
}
export function getDeck(db: DB, id: string): DeckRow {
const row = db.get<DeckRow>('SELECT * FROM decks WHERE id = ?', id);
if (!row) throw notFound('Deck');
return row;
}
export function getNote(db: DB, id: string): NoteRow {
const row = db.get<NoteRow>('SELECT * FROM notes WHERE id = ?', id);
if (!row) throw notFound('Note');
return row;
}
export function listQuestions(db: DB, quizId: string): Question[] {
return db.all<QuestionRow>('SELECT * FROM questions WHERE quiz_id = ? ORDER BY sort_order, created_at', quizId).map(mapQuestion);
}
export function listCards(db: DB, deckId: string): Card[] {
return db.all<CardRow>('SELECT * FROM cards WHERE deck_id = ? ORDER BY sort_order, created_at', deckId).map(mapCard);
}
/** Resolves and validates a folder id against a class; returns null for "no folder". */
export function resolveFolder(db: DB, classId: string, folderId: string | null | undefined): string | null {
if (!folderId) return null;
const folder = db.get<FolderRow>('SELECT * FROM folders WHERE id = ?', folderId);
return folder && folder.class_id === classId ? folder.id : null;
}
function nextSort(db: DB, table: string, where: string, value: string): number {
const row = db.get<{ m: number | null }>(`SELECT MAX(sort_order) AS m FROM ${table} WHERE ${where} = ?`, value);
return (row?.m ?? -1) + 1;
}
const touch = (db: DB, table: 'quizzes' | 'decks' | 'classes', id: string) => db.run(`UPDATE ${table} SET updated_at = ? WHERE id = ?`, now(), id);
/* ------------------------------ classes + folders ------------------------------ */
export const classInputSchema = z.object({
name: z.string().trim().min(1, 'Name is required').max(120),
code: z.string().trim().max(40).optional().default(''),
description: z.string().max(2000).optional().default(''),
color: z.enum(CLASS_COLORS).optional(),
groupLabel: z.string().trim().min(1).max(24).optional(),
});
export function createClass(db: DB, input: z.input<typeof classInputSchema>): ClassRow {
const data = classInputSchema.parse(input);
const id = newId();
const at = now();
const count = db.get<{ n: number }>('SELECT COUNT(*) AS n FROM classes')?.n ?? 0;
const color = data.color ?? CLASS_COLORS[count % CLASS_COLORS.length];
db.run(
'INSERT INTO classes (id, name, code, description, color, group_label, sort_order, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)',
id,
data.name,
data.code,
data.description,
color,
data.groupLabel ?? 'Exam',
count,
at,
at,
);
return getClass(db, id);
}
export function createFolder(db: DB, classId: string, name: string): FolderRow {
getClass(db, classId);
const id = newId();
const at = now();
db.run(
'INSERT INTO folders (id, class_id, name, sort_order, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?)',
id,
classId,
name.trim().slice(0, 120) || 'Untitled folder',
nextSort(db, 'folders', 'class_id', classId),
at,
at,
);
return getFolder(db, id);
}
/* ------------------------------ quizzes + questions ------------------------------ */
type ParsedQuestion = z.output<typeof questionInputSchema>;
function optionsJson(q: ParsedQuestion, keep?: Option[]): string {
const used = new Set<string>();
const options: Option[] = q.options.map((o) => {
let id = o.id && !used.has(o.id) ? o.id : undefined;
// Keep option ids stable across edits when the text is unchanged, so old attempts still line up.
if (!id && keep) id = keep.find((k) => k.text === o.text && !used.has(k.id))?.id;
if (!id) id = newId().slice(0, 8);
used.add(id);
return { id, text: o.text, correct: o.correct, why: o.why ?? '' };
});
return JSON.stringify(options);
}
export function insertQuestions(db: DB, quizId: string, inputs: unknown[], atIndex?: number): Question[] {
const parsed = inputs.map((q) => questionInputSchema.parse(q));
const at = now();
const ids: string[] = [];
db.tx(() => {
let sort = nextSort(db, 'questions', 'quiz_id', quizId);
if (atIndex !== undefined) {
const ordered = db.all<{ id: string }>('SELECT id FROM questions WHERE quiz_id = ? ORDER BY sort_order, created_at', quizId);
const insertAt = Math.max(0, Math.min(atIndex, ordered.length));
ordered.forEach((row, i) => db.run('UPDATE questions SET sort_order = ? WHERE id = ?', i < insertAt ? i : i + parsed.length, row.id));
sort = insertAt;
}
for (const q of parsed) {
const id = newId();
ids.push(id);
db.run(
'INSERT INTO questions (id, quiz_id, type, stem, options, rationale, topic, difficulty, tags, sort_order, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)',
id,
quizId,
q.type,
q.stem,
optionsJson(q),
q.rationale,
q.topic,
q.difficulty,
JSON.stringify(q.tags),
sort,
at,
at,
);
sort += 1;
}
touch(db, 'quizzes', quizId);
});
const all = listQuestions(db, quizId);
return ids.map((id) => all.find((q) => q.id === id)!);
}
export function updateQuestion(db: DB, id: string, input: unknown): Question {
const existing = db.get<QuestionRow>('SELECT * FROM questions WHERE id = ?', id);
if (!existing) throw notFound('Question');
const q = questionInputSchema.parse(input);
db.run(
'UPDATE questions SET type = ?, stem = ?, options = ?, rationale = ?, topic = ?, difficulty = ?, tags = ?, updated_at = ? WHERE id = ?',
q.type,
q.stem,
optionsJson(q, mapQuestion(existing).options),
q.rationale,
q.topic,
q.difficulty,
JSON.stringify(q.tags),
now(),
id,
);
touch(db, 'quizzes', existing.quiz_id);
return mapQuestion(db.get<QuestionRow>('SELECT * FROM questions WHERE id = ?', id)!);
}
export function createQuiz(
db: DB,
input: { classId: string; folderId?: string | null; title: string; description?: string; questions?: unknown[] },
): QuizRow {
getClass(db, input.classId);
const id = newId();
const at = now();
db.tx(() => {
db.run(
'INSERT INTO quizzes (id, class_id, folder_id, title, description, sort_order, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?)',
id,
input.classId,
resolveFolder(db, input.classId, input.folderId),
input.title.trim(),
input.description ?? '',
nextSort(db, 'quizzes', 'class_id', input.classId),
at,
at,
);
if (input.questions?.length) insertQuestions(db, id, input.questions);
});
return getQuiz(db, id);
}
export function duplicateQuiz(db: DB, id: string, target?: { classId?: string; folderId?: string | null; title?: string }): QuizRow {
const quiz = getQuiz(db, id);
const questions = listQuestions(db, id);
const classId = target?.classId ?? quiz.class_id;
return createQuiz(db, {
classId,
folderId: target?.folderId !== undefined ? target.folderId : classId === quiz.class_id ? quiz.folder_id : null,
title: target?.title ?? `${quiz.title} (copy)`,
description: quiz.description,
questions: questions.map((q) => ({
type: q.type,
stem: q.stem,
options: q.options.map((o) => ({ text: o.text, correct: o.correct, why: o.why })),
rationale: q.rationale,
topic: q.topic,
difficulty: q.difficulty,
tags: q.tags,
})),
});
}
/* ------------------------------ decks + cards ------------------------------ */
export function insertCards(db: DB, deckId: string, inputs: unknown[]): Card[] {
const parsed = inputs.map((c) => cardInputSchema.parse(c));
const at = now();
const ids: string[] = [];
db.tx(() => {
let sort = nextSort(db, 'cards', 'deck_id', deckId);
for (const c of parsed) {
const id = newId();
ids.push(id);
db.run(
'INSERT INTO cards (id, deck_id, front, back, hint, tags, sort_order, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)',
id,
deckId,
c.front,
c.back,
c.hint,
JSON.stringify(c.tags),
sort,
at,
at,
);
sort += 1;
}
touch(db, 'decks', deckId);
});
const all = listCards(db, deckId);
return ids.map((id) => all.find((c) => c.id === id)!);
}
export function updateCard(db: DB, id: string, input: unknown): Card {
const existing = db.get<CardRow>('SELECT * FROM cards WHERE id = ?', id);
if (!existing) throw notFound('Card');
const c = cardInputSchema.parse(input);
db.run('UPDATE cards SET front = ?, back = ?, hint = ?, tags = ?, updated_at = ? WHERE id = ?', c.front, c.back, c.hint, JSON.stringify(c.tags), now(), id);
touch(db, 'decks', existing.deck_id);
return mapCard(db.get<CardRow>('SELECT * FROM cards WHERE id = ?', id)!);
}
export function createDeck(
db: DB,
input: { classId: string; folderId?: string | null; title: string; description?: string; cards?: unknown[] },
): DeckRow {
getClass(db, input.classId);
const id = newId();
const at = now();
db.tx(() => {
db.run(
'INSERT INTO decks (id, class_id, folder_id, title, description, sort_order, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?)',
id,
input.classId,
resolveFolder(db, input.classId, input.folderId),
input.title.trim(),
input.description ?? '',
nextSort(db, 'decks', 'class_id', input.classId),
at,
at,
);
if (input.cards?.length) insertCards(db, id, input.cards);
});
return getDeck(db, id);
}
export function duplicateDeck(db: DB, id: string, target?: { classId?: string; folderId?: string | null; title?: string }): DeckRow {
const deck = getDeck(db, id);
const cards = listCards(db, id);
const classId = target?.classId ?? deck.class_id;
return createDeck(db, {
classId,
folderId: target?.folderId !== undefined ? target.folderId : classId === deck.class_id ? deck.folder_id : null,
title: target?.title ?? `${deck.title} (copy)`,
description: deck.description,
cards: cards.map((c) => ({ front: c.front, back: c.back, hint: c.hint, tags: c.tags })),
});
}
/* ------------------------------ notes ------------------------------ */
export function createNote(
db: DB,
input: { classId: string; folderId?: string | null; title: string; content?: string; kind?: string; source?: unknown },
): NoteRow {
getClass(db, input.classId);
const id = newId();
const at = now();
db.run(
'INSERT INTO notes (id, class_id, folder_id, title, content, kind, source, sort_order, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)',
id,
input.classId,
resolveFolder(db, input.classId, input.folderId),
input.title.trim().slice(0, 200) || 'Untitled note',
input.content ?? '',
input.kind ?? 'note',
JSON.stringify(input.source ?? {}),
nextSort(db, 'notes', 'class_id', input.classId),
at,
at,
);
return getNote(db, id);
}
/* ------------------------------ draft conversion ------------------------------ */
/** Turns a (validated) draft question into a strict question input, folding the citation into the rationale. */
export function draftQuestionToInput(q: DraftQuestion) {
const source = q.source?.trim();
const rationale = source && !q.rationale.includes(source) ? `${q.rationale.trim()}\n\n*Source: ${source}*`.trim() : q.rationale;
return {
type: q.type,
stem: q.stem,
options: q.options.map((o) => ({ text: o.text, correct: o.correct, why: o.why ?? '' })),
rationale,
topic: (q.topic ?? '').slice(0, 80),
difficulty: q.difficulty ?? 'medium',
tags: (q.tags ?? []).map((t) => t.slice(0, 40)).filter(Boolean).slice(0, 12),
};
}
export function draftCardToInput(c: DraftCard) {
return { front: c.front, back: c.back, hint: c.hint ?? '', tags: (c.tags ?? []).map((t) => t.slice(0, 40)).filter(Boolean).slice(0, 12) };
}