@goscribe/server 1.6.0 → 1.7.0

package/dist/src/lib/ai/inference-backend/mocks.js

@@ -0,0 +1,133 @@
+export function mockStudyGuide() {
+    return `# Mock Study Guide
+
+## Overview
+This is a mock study guide generated for testing purposes.
+
+## Key Concepts
+1. **Concept A**: Mock concept derived from uploaded materials
+2. **Concept B**: Another mock concept with explanations
+3. **Concept C**: A third concept with examples
+
+## Summary
+Mock study guide for local development when \`DONT_TEST_INFERENCE=true\`.`;
+}
+export function mockFlashcards(numQuestions, difficulty) {
+    return Array.from({ length: numQuestions }, (_, i) => ({
+        id: `mock-flashcard-${i + 1}`,
+        question: `Mock question ${i + 1}: What is the main concept covered in this material?`,
+        answer: `Mock answer ${i + 1}: Sample answer based on uploaded content.`,
+        difficulty,
+        category: `Mock Category ${(i % 3) + 1}`,
+    }));
+}
+export function mockWorksheet(numQuestions, difficulty, options) {
+    const mode = options?.mode ?? 'practice';
+    const isQuiz = mode === 'quiz';
+    return {
+        title: isQuiz ? `Mock Quiz - ${difficulty}` : `Mock Worksheet - ${difficulty} Level`,
+        description: 'Mock generated content',
+        difficulty,
+        estimatedTime: `${numQuestions * 2} min`,
+        problems: Array.from({ length: numQuestions }, (_, i) => {
+            if (isQuiz) {
+                return {
+                    question: `Mock MCQ ${i + 1}: What is 2+2?`,
+                    answer: '1',
+                    type: 'MULTIPLE_CHOICE',
+                    options: ['3', '4', '5', '6'],
+                    mark_scheme: {
+                        points: [{ point: 1, requirements: 'Select correct option' }],
+                        totalPoints: 1,
+                    },
+                };
+            }
+            return {
+                question: `Mock question ${i + 1}: Explain a concept.`,
+                answer: 'Mock answer',
+                type: 'TEXT',
+                options: [],
+                mark_scheme: {
+                    points: [{ point: 1, requirements: 'Clear explanation' }],
+                    totalPoints: 1,
+                },
+            };
+        }),
+    };
+}
+export function mockProcessFile(fileType) {
+    const mockPageCount = fileType === 'pdf' ? 15 : 1;
+    return {
+        status: 'success',
+        textContent: `Mock extracted text content from ${fileType} file.`,
+        imageDescriptions: Array.from({ length: mockPageCount }, (_, i) => ({
+            page: i + 1,
+            description: `Page ${i + 1} contains educational content with diagrams and text.`,
+            hasVisualContent: true,
+        })),
+        comprehensiveDescription: `DOCUMENT SUMMARY (${mockPageCount} ${mockPageCount === 1 ? 'page' : 'pages'})\n\nTEXT CONTENT:\nMock extracted text content...`,
+        pageCount: mockPageCount,
+    };
+}
+export function mockPodcastStructure(title, speakers) {
+    const voiceId = speakers[0]?.id || 'mock-voice-1';
+    return {
+        success: true,
+        structure: {
+            episodeTitle: `${title} - AI Generated Episode`,
+            totalEstimatedDuration: '15 minutes',
+            segments: [
+                {
+                    title: 'Welcome & Introduction',
+                    content: "HOST: Welcome to today's episode!\nGUEST: Thanks for having me!\nHOST: Let's dive into the topic.",
+                    speaker: 'dialogue',
+                    voiceId,
+                    keyPoints: ['Introduction', 'What to expect'],
+                    estimatedDuration: '3 minutes',
+                    order: 1,
+                },
+                {
+                    title: 'Main Discussion',
+                    content: 'This is the main content section where we explore the key concepts in detail.',
+                    speaker: 'host',
+                    voiceId,
+                    keyPoints: ['Key concept 1', 'Key concept 2'],
+                    estimatedDuration: '8 minutes',
+                    order: 2,
+                },
+                {
+                    title: 'Conclusion & Takeaways',
+                    content: "HOST: Let's wrap up what we've learned today.\nGUEST: The main takeaway is...\nHOST: Thanks for joining us!",
+                    speaker: 'dialogue',
+                    voiceId,
+                    keyPoints: ['Summary', 'Next steps'],
+                    estimatedDuration: '4 minutes',
+                    order: 3,
+                },
+            ],
+        },
+    };
+}
+export function mockPodcastAudio(user, sessionId, podcastId, segmentIndex, text) {
+    const isDialogue = text.includes('HOST:') || text.includes('GUEST:');
+    return {
+        success: true,
+        segmentIndex,
+        objectKey: `${user}/${sessionId}/podcasts/${podcastId}/segment_${segmentIndex}.mp3`,
+        duration: 45 + Math.floor(Math.random() * 30),
+        type: isDialogue ? 'dialogue' : 'monologue',
+        ...(isDialogue ? { partCount: 4 } : {}),
+    };
+}
+export function mockStudyGuideSegmentation() {
+    return [
+        { hint: 'Overview', content: 'Mock segment 1 content' },
+        { hint: 'Key concepts', content: 'Mock segment 2 content' },
+    ];
+}
+export function mockSegmentSummaryValidation() {
+    return {
+        valid: true,
+        feedback: 'Mock validation feedback for local development.',
+    };
+}

package/dist/src/lib/ai/inference-backend/types.d.ts

@@ -0,0 +1,44 @@
+export interface AISession {
+    id: string;
+    workspaceId: string;
+    status: 'initialized' | 'processing' | 'ready' | 'error';
+    files: string[];
+    instructionText?: string;
+    createdAt: Date;
+    updatedAt: Date;
+}
+export interface ProcessFileResult {
+    status: 'success' | 'error';
+    textContent: string | null;
+    imageDescriptions: Array<{
+        page: number;
+        description: string;
+        hasVisualContent: boolean;
+    }>;
+    comprehensiveDescription: string | null;
+    pageCount: number;
+    error?: string;
+}
+export interface PodcastSpeaker {
+    id: string;
+    role: string;
+    name?: string;
+}
+export interface WorksheetGenerationOptions {
+    mode?: 'practice' | 'quiz';
+    mcqRatio?: number;
+    questionTypes?: string[];
+    prompt?: string;
+    ragContext?: string;
+}
+export interface BackendGenerationOptions {
+    ragContext?: string;
+}
+export interface StudyGuideSegment {
+    hint: string;
+    content: string;
+}
+export interface SegmentSummaryValidation {
+    valid: boolean;
+    feedback: string;
+}

package/dist/src/lib/ai/inference-backend/types.js

@@ -0,0 +1 @@
+export {};

package/dist/src/lib/ai/json-parse.d.ts

@@ -0,0 +1,2 @@
+export declare function extractJson(content: string): Record<string, unknown> | null;
+export declare function parseJsonField<T>(value: unknown, field: string): T;

package/dist/src/lib/ai/json-parse.js

@@ -0,0 +1,34 @@
+export function extractJson(content) {
+    const fencedMatch = content.match(/```json\s*([\s\S]*?)```/i);
+    if (fencedMatch?.[1]) {
+        try {
+            return JSON.parse(fencedMatch[1]);
+        }
+        catch {
+            // fall through
+        }
+    }
+    const objectMatch = content.match(/\{[\s\S]*\}/);
+    if (objectMatch?.[0]) {
+        try {
+            return JSON.parse(objectMatch[0]);
+        }
+        catch {
+            return null;
+        }
+    }
+    return null;
+}
+export function parseJsonField(value, field) {
+    if (typeof value === 'string') {
+        return JSON.parse(value);
+    }
+    if (value && typeof value === 'object' && field in value) {
+        const nested = value[field];
+        if (typeof nested === 'string') {
+            return JSON.parse(nested);
+        }
+        return nested;
+    }
+    throw new Error(`Expected JSON field "${field}" in AI response`);
+}

package/dist/src/lib/ai/llm-client.d.ts

@@ -0,0 +1,7 @@
+import type { ChatCompletion } from 'openai/resources/chat/completions';
+import type { ChatMessage, CompleteOptions } from './types.js';
+export declare function complete(messages: ChatMessage[], options?: CompleteOptions): Promise<ChatCompletion>;
+export declare function completeText(messages: ChatMessage[], options?: CompleteOptions): Promise<string>;
+export declare function streamComplete(messages: ChatMessage[], onDelta: (delta: string) => void | Promise<void>, options?: CompleteOptions): Promise<string>;
+/** @deprecated Use `complete()` from the ai module instead. */
+export default complete;

package/dist/src/lib/ai/llm-client.js

@@ -0,0 +1,36 @@
+import OpenAI from 'openai';
+import { aiConfig } from './config.js';
+const client = new OpenAI({
+    apiKey: aiConfig.llm.apiKey,
+    baseURL: aiConfig.llm.baseUrl,
+});
+export async function complete(messages, options = {}) {
+    return client.chat.completions.create({
+        model: options.model ?? aiConfig.llm.model,
+        messages,
+        ...(options.temperature !== undefined ? { temperature: options.temperature } : {}),
+    });
+}
+export async function completeText(messages, options = {}) {
+    const response = await complete(messages, options);
+    return response.choices?.[0]?.message?.content ?? '';
+}
+export async function streamComplete(messages, onDelta, options = {}) {
+    const stream = await client.chat.completions.create({
+        model: options.model ?? aiConfig.llm.model,
+        messages,
+        stream: true,
+        ...(options.temperature !== undefined ? { temperature: options.temperature } : {}),
+    });
+    let content = '';
+    for await (const chunk of stream) {
+        const delta = chunk.choices?.[0]?.delta?.content ?? '';
+        if (!delta)
+            continue;
+        content += delta;
+        await onDelta(delta);
+    }
+    return content;
+}
+/** @deprecated Use `complete()` from the ai module instead. */
+export default complete;

package/dist/src/lib/ai/mock.d.ts

@@ -0,0 +1,2 @@
+export declare function isAiMockMode(): boolean;
+export declare function mockDelay(): Promise<void>;

package/dist/src/lib/ai/mock.js

@@ -0,0 +1,10 @@
+import { aiConfig } from './config.js';
+export function isAiMockMode() {
+    return aiConfig.inferenceBackend.mockEnabled;
+}
+export async function mockDelay() {
+    const delay = aiConfig.inferenceBackend.mockDelayMs;
+    if (delay > 0) {
+        await new Promise((resolve) => setTimeout(resolve, delay));
+    }
+}

package/dist/src/lib/ai/types.d.ts

@@ -0,0 +1,9 @@
+export type ChatRole = 'system' | 'user' | 'assistant';
+export interface ChatMessage {
+    role: ChatRole;
+    content: string;
+}
+export interface CompleteOptions {
+    model?: string;
+    temperature?: number;
+}

package/dist/src/lib/ai/types.js

@@ -0,0 +1 @@
+export {};

package/dist/src/lib/auth.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Authentication utilities for custom HMAC-based cookie verification.
+ *
+ * This module provides secure authentication using HMAC-SHA256 signatures
+ * to verify user identity through signed cookies.
+ *
+ * @fileoverview Custom authentication system with HMAC cookie verification
+ * @author Scribe Team
+ * @version 1.0.0
+ */
+/**
+ * Represents the result of successful authentication verification.
+ */
+export interface AuthResult {
+    /** The authenticated user's unique identifier */
+    userId: string;
+}
+/**
+ * Verifies a custom HMAC-signed authentication cookie.
+ *
+ * The cookie format is: `base64(userId).hex(hmacSHA256(base64(userId), secret))`
+ *
+ * @param cookieValue - The raw cookie value to verify, or undefined if no cookie exists
+ * @returns Authentication result with userId if valid, null if invalid or missing
+ *
+ * @example
+ * ```typescript
+ * const result = verifyCustomAuthCookie("dXNlcjEyMw.abc123def456...");
+ * if (result) {
+ *   console.log(`Authenticated user: ${result.userId}`);
+ * }
+ * ```
+ *
+ * @throws {Error} Never throws - returns null for all error conditions
+ */
+export declare function verifyCustomAuthCookie(cookieValue: string | undefined): AuthResult | null;

package/dist/src/lib/auth.js

@@ -0,0 +1,117 @@
+/**
+ * Authentication utilities for custom HMAC-based cookie verification.
+ *
+ * This module provides secure authentication using HMAC-SHA256 signatures
+ * to verify user identity through signed cookies.
+ *
+ * @fileoverview Custom authentication system with HMAC cookie verification
+ * @author Scribe Team
+ * @version 1.0.0
+ */
+import crypto from "node:crypto";
+/**
+ * Verifies a custom HMAC-signed authentication cookie.
+ *
+ * The cookie format is: `base64(userId).hex(hmacSHA256(base64(userId), secret))`
+ *
+ * @param cookieValue - The raw cookie value to verify, or undefined if no cookie exists
+ * @returns Authentication result with userId if valid, null if invalid or missing
+ *
+ * @example
+ * ```typescript
+ * const result = verifyCustomAuthCookie("dXNlcjEyMw.abc123def456...");
+ * if (result) {
+ *   console.log(`Authenticated user: ${result.userId}`);
+ * }
+ * ```
+ *
+ * @throws {Error} Never throws - returns null for all error conditions
+ */
+export function verifyCustomAuthCookie(cookieValue) {
+    // Early return for missing cookie
+    if (!cookieValue) {
+        return null;
+    }
+    // Get authentication secret from environment
+    const secret = process.env.AUTH_SECRET;
+    if (!secret) {
+        return null;
+    }
+    // Parse cookie format: base64UserId.signatureHex
+    const parts = cookieValue.split(".");
+    if (parts.length !== 2) {
+        return null;
+    }
+    const [base64UserId, signatureHex] = parts;
+    // Decode the user ID from base64url encoding
+    const userId = decodeBase64UrlUserId(base64UserId);
+    if (!userId) {
+        return null;
+    }
+    // Verify the HMAC signature
+    const isValidSignature = verifyHmacSignature(base64UserId, signatureHex, secret);
+    if (!isValidSignature) {
+        return null;
+    }
+    return { userId };
+}
+/**
+ * Decodes a base64url-encoded user ID string.
+ *
+ * @param base64UserId - The base64url-encoded user ID
+ * @returns The decoded user ID string, or null if decoding fails
+ *
+ * @private
+ */
+function decodeBase64UrlUserId(base64UserId) {
+    try {
+        const buffer = Buffer.from(base64UserId, "base64url");
+        return buffer.toString("utf8");
+    }
+    catch (error) {
+        return null;
+    }
+}
+/**
+ * Verifies an HMAC-SHA256 signature against the expected value.
+ *
+ * @param data - The data that was signed (base64url-encoded user ID)
+ * @param signatureHex - The hex-encoded signature to verify
+ * @param secret - The secret key used for signing
+ * @returns True if the signature is valid, false otherwise
+ *
+ * @private
+ */
+function verifyHmacSignature(data, signatureHex, secret) {
+    const hmac = crypto.createHmac("sha256", secret);
+    hmac.update(data);
+    const expectedSignature = hmac.digest("hex");
+    return timingSafeEqualHex(signatureHex, expectedSignature);
+}
+/**
+ * Performs a timing-safe comparison of two hex-encoded strings.
+ *
+ * This function prevents timing attacks by ensuring the comparison
+ * takes the same amount of time regardless of where the strings differ.
+ *
+ * @param a - First hex string to compare
+ * @param b - Second hex string to compare
+ * @returns True if the strings are equal, false otherwise
+ *
+ * @private
+ */
+function timingSafeEqualHex(a, b) {
+    try {
+        const bufferA = Buffer.from(a, "hex");
+        const bufferB = Buffer.from(b, "hex");
+        // Length check prevents timing attacks on different-length inputs
+        if (bufferA.length !== bufferB.length) {
+            return false;
+        }
+        return crypto.timingSafeEqual(bufferA, bufferB);
+    }
+    catch {
+        // Return false for any parsing errors
+        return false;
+    }
+}

package/dist/src/lib/chunking.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Approximate text chunker for RAG indexing.
+ *
+ * Splits a long document into overlapping windows aimed at a target token
+ * count. We don't have a tokenizer dependency, so we approximate using
+ * `chars / 4` (a rule of thumb that matches GPT-style BPE within ~10-20%).
+ * Chunk boundaries snap to paragraph / sentence breaks when possible so we
+ * don't slice mid-thought.
+ */
+export interface ChunkOptions {
+    targetTokens?: number;
+    overlapTokens?: number;
+}
+export interface Chunk {
+    index: number;
+    content: string;
+    approxTokens: number;
+}
+export declare function chunkText(text: string, opts?: ChunkOptions): Chunk[];

package/dist/src/lib/chunking.js

@@ -0,0 +1,47 @@
+const CHARS_PER_TOKEN = 4;
+export function chunkText(text, opts = {}) {
+    const targetTokens = opts.targetTokens ?? 500;
+    const overlapTokens = opts.overlapTokens ?? 60;
+    const targetChars = targetTokens * CHARS_PER_TOKEN;
+    const overlapChars = overlapTokens * CHARS_PER_TOKEN;
+    const cleaned = text.replace(/\r\n/g, '\n').replace(/[ \t]+/g, ' ').trim();
+    if (!cleaned)
+        return [];
+    const chunks = [];
+    let cursor = 0;
+    let index = 0;
+    while (cursor < cleaned.length) {
+        const hardEnd = Math.min(cleaned.length, cursor + targetChars);
+        let end = hardEnd;
+        if (hardEnd < cleaned.length) {
+            // Prefer a paragraph break, then a sentence break, then a space.
+            const window = cleaned.slice(cursor, hardEnd);
+            const lastPara = window.lastIndexOf('\n\n');
+            const lastSentence = Math.max(window.lastIndexOf('. '), window.lastIndexOf('! '), window.lastIndexOf('? '), window.lastIndexOf('.\n'));
+            const lastSpace = window.lastIndexOf(' ');
+            const minBreak = Math.floor(targetChars * 0.5);
+            if (lastPara >= minBreak) {
+                end = cursor + lastPara + 2;
+            }
+            else if (lastSentence >= minBreak) {
+                end = cursor + lastSentence + 2;
+            }
+            else if (lastSpace >= minBreak) {
+                end = cursor + lastSpace + 1;
+            }
+        }
+        const piece = cleaned.slice(cursor, end).trim();
+        if (piece) {
+            chunks.push({
+                index,
+                content: piece,
+                approxTokens: Math.max(1, Math.round(piece.length / CHARS_PER_TOKEN)),
+            });
+            index += 1;
+        }
+        if (end >= cleaned.length)
+            break;
+        cursor = Math.max(end - overlapChars, cursor + 1);
+    }
+    return chunks;
+}

package/dist/src/lib/constants.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Shared constants for artifact types.
+ * Mirrors the Prisma ArtifactType enum to avoid direct type imports
+ * in contexts where Prisma client types may not be available.
+ */
+export declare const ArtifactType: {
+    readonly STUDY_GUIDE: "STUDY_GUIDE";
+    readonly FLASHCARD_SET: "FLASHCARD_SET";
+    readonly WORKSHEET: "WORKSHEET";
+    readonly MEETING_SUMMARY: "MEETING_SUMMARY";
+    readonly PODCAST_EPISODE: "PODCAST_EPISODE";
+};
+export type ArtifactTypeValue = (typeof ArtifactType)[keyof typeof ArtifactType];

package/dist/src/lib/constants.js

@@ -0,0 +1,12 @@
+/**
+ * Shared constants for artifact types.
+ * Mirrors the Prisma ArtifactType enum to avoid direct type imports
+ * in contexts where Prisma client types may not be available.
+ */
+export const ArtifactType = {
+    STUDY_GUIDE: 'STUDY_GUIDE',
+    FLASHCARD_SET: 'FLASHCARD_SET',
+    WORKSHEET: 'WORKSHEET',
+    MEETING_SUMMARY: 'MEETING_SUMMARY',
+    PODCAST_EPISODE: 'PODCAST_EPISODE',
+};

package/dist/src/lib/curated-kb-seed.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Curated AP & IB knowledge bases seeded on server startup.
+ * Each entry uses a stable slug in `meta` so the client can pick icons/colors.
+ */
+export interface CuratedKbSeed {
+    slug: string;
+    name: string;
+    description: string;
+    category: 'AP' | 'IB';
+    subject: string;
+}
+export declare const CURATED_KB_SEEDS: CuratedKbSeed[];