@goscribe/server 1.5.0 → 1.7.0

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

@@ -0,0 +1,28 @@
+import type { MarkScheme, UserMarkScheme } from '../../../types/index.js';
+import type { AISession, PodcastSpeaker, ProcessFileResult, StudyGuideSegment, WorksheetGenerationOptions, BackendGenerationOptions } from './types.js';
+export declare class InferenceBackendClient {
+    private sessions;
+    private get uploadUrl();
+    private postCommand;
+    private buildForm;
+    private withRag;
+    initSession(workspaceId: string, user: string): Promise<AISession>;
+    processFile(sessionId: string, _user: string, fileUrl: string, fileType: 'image' | 'pdf', maxPages?: number): Promise<ProcessFileResult>;
+    generateStudyGuide(sessionId: string, user: string, opts?: BackendGenerationOptions): Promise<string>;
+    generateFlashcardQuestions(sessionId: string, user: string, numQuestions: number, difficulty: 'easy' | 'medium' | 'hard', prompt?: string, opts?: BackendGenerationOptions): Promise<string>;
+    generateWorksheetQuestions(sessionId: string, user: string, numQuestions: number, difficulty: 'EASY' | 'MEDIUM' | 'HARD', options?: WorksheetGenerationOptions): Promise<string>;
+    checkWorksheetQuestions(sessionId: string, user: string, question: string, answer: string, markScheme: MarkScheme): Promise<UserMarkScheme>;
+    generatePodcastStructure(sessionId: string, user: string, title: string, description: string, prompt: string, speakers: PodcastSpeaker[]): Promise<any>;
+    generatePodcastAudioFromText(sessionId: string, user: string, podcastId: string, segmentIndex: number, text: string, speakers: PodcastSpeaker[], voiceId?: string): Promise<any>;
+    generatePodcastImage(sessionId: string, user: string, summary: string): Promise<string>;
+    segmentStudyGuide(sessionId: string, user: string, studyGuide: string): Promise<StudyGuideSegment[]>;
+    validateSegmentSummary(sessionId: string, user: string, segmentContent: string, studentResponse: string, studyGuide: string): Promise<{
+        valid: boolean;
+        feedback: string;
+    }>;
+    getSession(sessionId: string): AISession | undefined;
+    getSessionsByUserAndWorkspace(_userId: string, workspaceId: string): AISession[];
+    deleteSession(sessionId: string): boolean;
+    checkHealth(): Promise<boolean>;
+}
+export declare const inferenceBackend: InferenceBackendClient;

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

@@ -0,0 +1,301 @@
+import { TRPCError } from '@trpc/server';
+import { getInferenceBackendUploadUrl, aiConfig, tryGetInferenceBackendUploadUrl } from '../config.js';
+import { isAiMockMode, mockDelay } from '../mock.js';
+import { parseJsonField } from '../json-parse.js';
+import { withRetry } from '../../retry.js';
+import { logger } from '../../logger.js';
+import { mockFlashcards, mockPodcastAudio, mockPodcastStructure, mockProcessFile, mockSegmentSummaryValidation, mockStudyGuide, mockStudyGuideSegmentation, mockWorksheet, } from './mocks.js';
+export class InferenceBackendClient {
+    constructor() {
+        this.sessions = new Map();
+    }
+    get uploadUrl() {
+        return getInferenceBackendUploadUrl();
+    }
+    async postCommand(formData, options) {
+        const { label, timeoutMs = 300000, retries = 3 } = options;
+        return withRetry(async () => {
+            const controller = new AbortController();
+            const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+            try {
+                const response = await fetch(this.uploadUrl, {
+                    method: 'POST',
+                    body: formData,
+                    signal: controller.signal,
+                });
+                clearTimeout(timeoutId);
+                if (!response.ok) {
+                    const errorText = await response.text().catch(() => '');
+                    throw new Error(`AI backend error (${response.status}): ${errorText || response.statusText}`);
+                }
+                return (await response.json());
+            }
+            catch (error) {
+                clearTimeout(timeoutId);
+                throw error;
+            }
+        }, { maxRetries: retries, timeoutMs, label });
+    }
+    buildForm(command, fields = {}) {
+        const formData = new FormData();
+        formData.append('command', command);
+        for (const [key, value] of Object.entries(fields)) {
+            formData.append(key, value);
+        }
+        return formData;
+    }
+    withRag(fields, opts) {
+        if (opts?.ragContext?.trim()) {
+            return { ...fields, rag_context: opts.ragContext.trim() };
+        }
+        return fields;
+    }
+    async initSession(workspaceId, user) {
+        await mockDelay();
+        const sessionId = workspaceId;
+        if (isAiMockMode()) {
+            logger.info(`[ai] mock initSession workspace=${workspaceId}`);
+            const session = {
+                id: sessionId,
+                workspaceId,
+                status: 'initialized',
+                files: [],
+                createdAt: new Date(),
+                updatedAt: new Date(),
+            };
+            this.sessions.set(sessionId, session);
+            return session;
+        }
+        const result = await this.postCommand(this.buildForm('init_session', { session: sessionId, user }), { label: 'initSession' });
+        if (!result.message) {
+            throw new TRPCError({
+                code: 'INTERNAL_SERVER_ERROR',
+                message: 'AI backend returned no session message',
+            });
+        }
+        const session = {
+            id: sessionId,
+            workspaceId,
+            status: 'initialized',
+            files: [],
+            createdAt: new Date(),
+            updatedAt: new Date(),
+        };
+        this.sessions.set(sessionId, session);
+        return session;
+    }
+    async processFile(sessionId, _user, fileUrl, fileType, maxPages) {
+        await mockDelay();
+        if (isAiMockMode()) {
+            logger.info(`[ai] mock processFile session=${sessionId} type=${fileType}`);
+            return mockProcessFile(fileType);
+        }
+        const fields = { fileUrl, fileType };
+        if (maxPages)
+            fields.maxPages = maxPages.toString();
+        try {
+            const result = await this.postCommand(this.buildForm('process_file', fields), { label: 'processFile' });
+            if (result.status === 'error') {
+                throw new Error(result.error || 'File processing failed');
+            }
+            return result;
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : 'Unknown error';
+            logger.error(`[ai] processFile failed: ${message}`);
+            return {
+                status: 'error',
+                textContent: null,
+                imageDescriptions: [],
+                comprehensiveDescription: null,
+                pageCount: 0,
+                error: message,
+            };
+        }
+    }
+    async generateStudyGuide(sessionId, user, opts) {
+        await mockDelay();
+        if (isAiMockMode()) {
+            logger.info(`[ai] mock generateStudyGuide session=${sessionId}`);
+            return mockStudyGuide();
+        }
+        const result = await this.postCommand(this.buildForm('generate_study_guide', this.withRag({ session: sessionId, user }, opts)), { label: 'generateStudyGuide' });
+        if (!result.markdown) {
+            throw new Error('AI backend returned empty study guide');
+        }
+        return result.markdown;
+    }
+    async generateFlashcardQuestions(sessionId, user, numQuestions, difficulty, prompt, opts) {
+        await mockDelay();
+        if (isAiMockMode()) {
+            logger.info(`[ai] mock generateFlashcardQuestions session=${sessionId}`);
+            return JSON.stringify(mockFlashcards(numQuestions, difficulty));
+        }
+        const fields = {
+            session: sessionId,
+            user,
+            num_questions: numQuestions.toString(),
+            difficulty,
+        };
+        if (prompt)
+            fields.prompt = prompt;
+        const result = await this.postCommand(this.buildForm('generate_flashcard_questions', this.withRag(fields, opts)), { label: 'generateFlashcardQuestions' });
+        const parsed = JSON.parse(result.flashcards);
+        if (Array.isArray(parsed))
+            return JSON.stringify(parsed);
+        return JSON.stringify(parsed.flashcards ?? []);
+    }
+    async generateWorksheetQuestions(sessionId, user, numQuestions, difficulty, options) {
+        await mockDelay();
+        if (isAiMockMode()) {
+            logger.info(`[ai] mock generateWorksheetQuestions session=${sessionId}`);
+            return JSON.stringify(mockWorksheet(numQuestions, difficulty, options));
+        }
+        const fields = {
+            session: sessionId,
+            user,
+            num_questions: numQuestions.toString(),
+            difficulty,
+            mode: options?.mode ?? 'practice',
+        };
+        if (options?.mcqRatio !== undefined) {
+            fields.mcq_ratio = String(options.mcqRatio);
+        }
+        if (options?.questionTypes?.length) {
+            fields.question_types = JSON.stringify(options.questionTypes);
+        }
+        if (options?.prompt) {
+            fields.worksheet_prompt = options.prompt;
+        }
+        const result = await this.postCommand(this.buildForm('generate_worksheet_questions', this.withRag(fields, { ragContext: options?.ragContext })), { label: 'generateWorksheetQuestions' });
+        return result.worksheet;
+    }
+    async checkWorksheetQuestions(sessionId, user, question, answer, markScheme) {
+        const result = await this.postCommand(this.buildForm('mark_worksheet_questions', {
+            session: sessionId,
+            user,
+            question,
+            answer,
+            mark_scheme: JSON.stringify(markScheme),
+        }), { label: 'checkWorksheetQuestions', retries: 2 });
+        return parseJsonField(result.marking, 'marking');
+    }
+    async generatePodcastStructure(sessionId, user, title, description, prompt, speakers) {
+        await mockDelay();
+        if (isAiMockMode()) {
+            logger.info(`[ai] mock generatePodcastStructure session=${sessionId}`);
+            return mockPodcastStructure(title, speakers);
+        }
+        try {
+            return await this.postCommand(this.buildForm('generate_podcast_structure', {
+                user,
+                session: sessionId,
+                title,
+                description,
+                prompt,
+                speakers: JSON.stringify(speakers),
+            }), { label: 'generatePodcastStructure' });
+        }
+        catch (error) {
+            throw new TRPCError({
+                code: 'INTERNAL_SERVER_ERROR',
+                message: `Failed to generate podcast structure: ${error instanceof Error ? error.message : 'Unknown error'}`,
+            });
+        }
+    }
+    async generatePodcastAudioFromText(sessionId, user, podcastId, segmentIndex, text, speakers, voiceId) {
+        await mockDelay();
+        if (isAiMockMode()) {
+            logger.info(`[ai] mock generatePodcastAudio session=${sessionId}`);
+            return mockPodcastAudio(user, sessionId, podcastId, segmentIndex, text);
+        }
+        const fields = {
+            user,
+            session: sessionId,
+            podcast_id: podcastId,
+            segment_index: segmentIndex.toString(),
+            text,
+            speakers: JSON.stringify(speakers),
+        };
+        if (voiceId)
+            fields.voice_id = voiceId;
+        try {
+            return await this.postCommand(this.buildForm('generate_podcast_audio_from_text', fields), { label: 'generatePodcastAudioFromText' });
+        }
+        catch (error) {
+            throw new TRPCError({
+                code: 'INTERNAL_SERVER_ERROR',
+                message: `Failed to generate podcast audio: ${error instanceof Error ? error.message : 'Unknown error'}`,
+            });
+        }
+    }
+    async generatePodcastImage(sessionId, user, summary) {
+        const result = await this.postCommand(this.buildForm('generate_podcast_image', {
+            session: sessionId,
+            user,
+            summary,
+        }), { label: 'generatePodcastImage' });
+        return result.image_key;
+    }
+    async segmentStudyGuide(sessionId, user, studyGuide) {
+        if (isAiMockMode()) {
+            return mockStudyGuideSegmentation();
+        }
+        const result = await this.postCommand(this.buildForm('generate_study_guide_segmentation', {
+            session: sessionId,
+            user,
+            study_guide: studyGuide,
+        }), { label: 'segmentStudyGuide' });
+        return result.segmentation;
+    }
+    async validateSegmentSummary(sessionId, user, segmentContent, studentResponse, studyGuide) {
+        if (isAiMockMode()) {
+            return mockSegmentSummaryValidation();
+        }
+        const result = await this.postCommand(this.buildForm('validate_segment_summary', {
+            session: sessionId,
+            user,
+            segment_content: segmentContent,
+            student_response: studentResponse,
+            study_guide: studyGuide,
+        }), { label: 'validateSegmentSummary' });
+        return result.feedback;
+    }
+    getSession(sessionId) {
+        return this.sessions.get(sessionId);
+    }
+    getSessionsByUserAndWorkspace(_userId, workspaceId) {
+        return Array.from(this.sessions.values()).filter((session) => session.workspaceId === workspaceId);
+    }
+    deleteSession(sessionId) {
+        return this.sessions.delete(sessionId);
+    }
+    async checkHealth() {
+        await mockDelay();
+        if (isAiMockMode()) {
+            logger.info('[ai] mock health check');
+            return true;
+        }
+        const uploadUrl = tryGetInferenceBackendUploadUrl();
+        if (!uploadUrl)
+            return false;
+        try {
+            const response = await fetch(uploadUrl, {
+                method: 'POST',
+                body: new FormData(),
+            });
+            return response.ok;
+        }
+        catch (error) {
+            logger.error('[ai] health check failed', error);
+            return false;
+        }
+    }
+}
+export const inferenceBackend = new InferenceBackendClient();
+if (aiConfig.inferenceBackend.url) {
+    logger.info(`[ai] inference backend: ${aiConfig.inferenceBackend.url}`);
+}
+if (isAiMockMode()) {
+    logger.info('[ai] mock mode enabled (DONT_TEST_INFERENCE=true)');
+}

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

@@ -0,0 +1,12 @@
+import type { ProcessFileResult, PodcastSpeaker, StudyGuideSegment, WorksheetGenerationOptions } from './types.js';
+export declare function mockStudyGuide(): string;
+export declare function mockFlashcards(numQuestions: number, difficulty: 'easy' | 'medium' | 'hard'): unknown[];
+export declare function mockWorksheet(numQuestions: number, difficulty: 'EASY' | 'MEDIUM' | 'HARD', options?: WorksheetGenerationOptions): object;
+export declare function mockProcessFile(fileType: 'image' | 'pdf'): ProcessFileResult;
+export declare function mockPodcastStructure(title: string, speakers: PodcastSpeaker[]): object;
+export declare function mockPodcastAudio(user: string, sessionId: string, podcastId: string, segmentIndex: number, text: string): object;
+export declare function mockStudyGuideSegmentation(): StudyGuideSegment[];
+export declare function mockSegmentSummaryValidation(): {
+    valid: boolean;
+    feedback: string;
+};

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;