@goscribe/server 1.0.7 → 1.0.9

package/PODCAST_FRONTEND_SPEC.md

@@ -0,0 +1,595 @@
+# Podcast Frontend Integration Specification
+
+## Overview
+This document outlines the frontend requirements for integrating with the podcast functionality, including real-time updates via Pusher, UI components, and user interactions.
+
+## User Prompt Field
+The `userPrompt` field is the primary input for podcast generation. Users provide a prompt describing:
+- The topic they want the podcast to cover
+- Specific questions they want answered
+- The type of content they're looking for
+- Any particular angle or perspective they want
+
+Examples of user prompts:
+- "Create a podcast about the history of artificial intelligence"
+- "Explain quantum computing in simple terms for beginners"
+- "Discuss the impact of social media on mental health"
+- "Create a podcast episode about sustainable living practices"
+
+The AI will use this prompt to generate complete podcast content, including all segments, scripts, and structure.
+
+## Audio Joining Functionality
+The podcast system now generates both individual segment audio files and a complete joined episode audio file:
+
+### Individual Segments
+- Each segment is generated as a separate audio file
+- Useful for segment-by-segment playback and editing
+- Allows users to jump to specific parts of the episode
+
+### Full Episode Audio
+- All segments are joined into a single continuous audio file
+- Provides a seamless listening experience
+- Useful for traditional podcast playback
+- Stored as a separate file with its own signed URL
+
+### Audio Joining Process
+1. After all individual segments are generated
+2. Audio buffers are concatenated in the correct order
+3. The joined audio is uploaded to cloud storage
+4. A signed URL is generated for the full episode
+5. Both individual segments and full episode remain available
+
+## Real-Time Events (Pusher)
+
+### Event Channels
+All podcast events are broadcast on the channel: `workspace_{workspaceId}`
+
+### Event Types
+
+#### 1. Podcast Generation Events
+```typescript
+// Generation Start
+{
+  event: 'workspace_{workspaceId}_podcast_generation_start',
+  data: {
+    title: string
+  }
+}
+
+// Structure Complete
+{
+  event: 'workspace_{workspaceId}_podcast_structure_complete',
+  data: {
+    segmentsCount: number
+  }
+}
+
+// Audio Generation Start
+{
+  event: 'workspace_{workspaceId}_podcast_audio_generation_start',
+  data: {
+    totalSegments: number
+  }
+}
+
+// Segment Progress
+{
+  event: 'workspace_{workspaceId}_podcast_segment_progress',
+  data: {
+    currentSegment: number,
+    totalSegments: number,
+    segmentTitle: string
+  }
+}
+
+// Audio Generation Complete
+{
+  event: 'workspace_{workspaceId}_podcast_audio_generation_complete',
+  data: {
+    totalSegments: number,
+    totalDuration: number
+  }
+}
+
+// Audio Joining Start
+{
+  event: 'workspace_{workspaceId}_podcast_audio_joining_start',
+  data: {
+    totalSegments: number
+  }
+}
+
+// Audio Joining Complete
+{
+  event: 'workspace_{workspaceId}_podcast_audio_joining_complete',
+  data: {
+    fullEpisodeObjectKey: string
+  }
+}
+
+// Audio Joining Error
+{
+  event: 'workspace_{workspaceId}_podcast_audio_joining_error',
+  data: {
+    error: string
+  }
+}
+
+// Summary Complete
+{
+  event: 'workspace_{workspaceId}_podcast_summary_complete',
+  data: {
+    summaryGenerated: boolean
+  }
+}
+
+// Generation Complete
+{
+  event: 'workspace_{workspaceId}_podcast_ended',
+  data: {
+    artifactId: string,
+    title: string,
+    status: 'completed'
+  }
+}
+```
+
+#### 2. Segment Regeneration Events
+```typescript
+// Regeneration Start
+{
+  event: 'workspace_{workspaceId}_podcast_segment_regeneration_start',
+  data: {
+    segmentId: string,
+    segmentTitle: string
+  }
+}
+
+// Regeneration Complete
+{
+  event: 'workspace_{workspaceId}_podcast_segment_regeneration_complete',
+  data: {
+    segmentId: string,
+    segmentTitle: string,
+    duration: number
+  }
+}
+
+// Full Episode Regeneration Start (after segment update)
+{
+  event: 'workspace_{workspaceId}_podcast_full_episode_regeneration_start',
+  data: {
+    reason: 'segment_updated'
+  }
+}
+
+// Full Episode Regeneration Complete
+{
+  event: 'workspace_{workspaceId}_podcast_full_episode_regeneration_complete',
+  data: {
+    fullEpisodeObjectKey: string
+  }
+}
+
+// Full Episode Regeneration Error
+{
+  event: 'workspace_{workspaceId}_podcast_full_episode_regeneration_error',
+  data: {
+    error: string
+  }
+}
+```
+
+#### 3. Episode Deletion Events
+```typescript
+// Deletion Start
+{
+  event: 'workspace_{workspaceId}_podcast_deletion_start',
+  data: {
+    episodeId: string,
+    episodeTitle: string
+  }
+}
+
+// Deletion Complete
+{
+  event: 'workspace_{workspaceId}_podcast_deletion_complete',
+  data: {
+    episodeId: string,
+    episodeTitle: string
+  }
+}
+```
+
+#### 4. Error Events
+```typescript
+// General Error
+{
+  event: 'workspace_{workspaceId}_podcast_error',
+  data: {
+    error: string,
+    analysisType: 'podcast',
+    timestamp: string
+  }
+}
+
+// Segment Error
+{
+  event: 'workspace_{workspaceId}_podcast_segment_error',
+  data: {
+    segmentIndex: number,
+    error: string
+  }
+}
+
+// Summary Error
+{
+  event: 'workspace_{workspaceId}_podcast_summary_error',
+  data: {
+    error: string
+  }
+}
+```
+
+## UI Components
+
+### 1. Podcast Generation Form
+```typescript
+interface PodcastGenerationForm {
+  title: string;
+  description?: string;
+  userPrompt: string;
+  voice: 'alloy' | 'echo' | 'fable' | 'onyx' | 'nova' | 'shimmer';
+  speed: number; // 0.25 - 4.0
+  generateIntro: boolean;
+  generateOutro: boolean;
+  segmentByTopics: boolean;
+}
+```
+
+**Required Fields:**
+- Title (required)
+- User Prompt (required) - The topic, question, or request for the podcast
+- Voice (default: 'nova')
+- Speed (default: 1.0)
+
+**Optional Fields:**
+- Description
+- Generate Intro (default: true)
+- Generate Outro (default: true)
+- Segment by Topics (default: true)
+
+### 2. Podcast List View
+```typescript
+interface PodcastEpisode {
+  id: string;
+  title: string;
+  description?: string;
+  metadata: {
+    totalDuration: number;
+    voice: string;
+    speed: number;
+    segments: PodcastSegment[];
+    fullEpisodeObjectKey?: string; // Reference to the full joined episode audio
+    summary: {
+      executiveSummary: string;
+      learningObjectives: string[];
+      keyConcepts: string[];
+      followUpActions: string[];
+      targetAudience: string;
+      prerequisites: string[];
+      tags: string[];
+    };
+    generatedAt: string;
+  };
+  segments: {
+    id: string;
+    title: string;
+    audioUrl?: string;
+    objectKey?: string;
+    startTime: number;
+    duration: number;
+    order: number;
+  }[];
+  fullEpisodeUrl?: string; // Signed URL for the full episode
+  createdAt: string;
+  updatedAt: string;
+}
+```
+
+### 3. Podcast Player Component
+```typescript
+interface PodcastPlayer {
+  currentSegment: number;
+  isPlaying: boolean;
+  currentTime: number;
+  duration: number;
+  segments: PodcastSegment[];
+  onSegmentChange: (segmentId: string) => void;
+  onPlayPause: () => void;
+  onSeek: (time: number) => void;
+}
+```
+
+### 4. Segment Editor
+```typescript
+interface SegmentEditor {
+  segmentId: string;
+  title: string;
+  content: string;
+  keyPoints: string[];
+  order: number;
+  onSave: (segment: Partial<PodcastSegment>) => void;
+  onRegenerate: (newContent?: string) => void;
+}
+```
+
+## API Endpoints
+
+### 1. List Episodes
+```typescript
+// GET /trpc/podcast.listEpisodes
+{
+  input: {
+    workspaceId: string;
+  }
+}
+```
+
+### 2. Get Episode
+```typescript
+// GET /trpc/podcast.getEpisode
+{
+  input: {
+    episodeId: string;
+  }
+}
+```
+
+### 3. Generate Episode
+```typescript
+// POST /trpc/podcast.generateEpisode
+{
+  input: {
+    workspaceId: string;
+    podcastData: PodcastGenerationForm;
+  }
+}
+```
+
+### 4. Get Episode Schema
+```typescript
+// GET /trpc/podcast.getEpisodeSchema
+{
+  input: {
+    episodeId: string;
+  }
+}
+```
+
+### 5. Update Episode
+```typescript
+// POST /trpc/podcast.updateEpisode
+{
+  input: {
+    episodeId: string;
+    title?: string;
+    description?: string;
+  }
+}
+```
+
+### 6. Delete Episode
+```typescript
+// POST /trpc/podcast.deleteEpisode
+{
+  input: {
+    episodeId: string;
+  }
+}
+```
+
+### 7. Get Available Voices
+```typescript
+// GET /trpc/podcast.getAvailableVoices
+// No input required
+```
+
+### 8. Get Signed URLs
+```typescript
+// GET /trpc/podcast.getSignedUrls
+{
+  input: {
+    episodeId: string;
+  }
+}
+```
+
+### 9. Get Full Episode URL
+```typescript
+// GET /trpc/podcast.getFullEpisodeUrl
+{
+  input: {
+    episodeId: string;
+  }
+}
+```
+
+### 10. Regenerate Segment
+```typescript
+// POST /trpc/podcast.regenerateSegment
+{
+  input: {
+    episodeId: string;
+    segmentId: string;
+    newContent?: string; // Optional: new content for the segment
+    voice?: 'alloy' | 'echo' | 'fable' | 'onyx' | 'nova' | 'shimmer';
+    speed?: number; // 0.25 - 4.0
+  }
+}
+```
+
+## User Experience Flow
+
+### 1. Podcast Generation
+1. User fills out podcast generation form with:
+   - Title for the podcast
+   - User prompt describing the topic, question, or request
+   - Optional description
+   - Voice and speed preferences
+   - Generation options (intro, outro, segmentation)
+2. Submit form → show loading state
+3. Listen for real-time progress updates:
+   - Generation start
+   - Structure complete (AI creates episode content from prompt)
+   - Audio generation start
+   - Segment progress (update progress bar)
+   - Audio generation complete
+   - Audio joining start (combining segments into full episode)
+   - Audio joining complete
+   - Summary complete
+   - Generation complete
+4. Redirect to podcast player or show success message
+
+### 2. Podcast Playback
+1. Load episode data
+2. Get fresh signed URLs for audio segments
+3. Initialize audio player with segments
+4. Handle segment navigation
+5. Update progress indicators
+
+### 3. Segment Management
+1. Display segments in list/grid view
+2. Allow editing segment content
+3. Provide regenerate option for individual segments
+4. Show regeneration progress:
+   - Segment regeneration start
+   - Segment regeneration complete
+   - Full episode regeneration start (to sync all segments)
+   - Full episode regeneration complete
+5. Update audio URLs after regeneration (both individual segments and full episode)
+
+### 4. Episode Management
+1. List all episodes with metadata
+2. Allow editing episode title/description
+3. Provide delete option with confirmation
+4. Show deletion progress
+
+## Error Handling
+
+### 1. Generation Errors
+- Display error message with retry option
+- Show which step failed
+- Provide fallback options
+
+### 2. Audio Loading Errors
+- Retry loading audio files
+- Show placeholder for failed segments
+- Provide manual refresh option
+
+### 3. Network Errors
+- Implement retry logic
+- Show offline indicators
+- Cache episode data when possible
+
+## Loading States
+
+### 1. Generation Progress
+```typescript
+interface GenerationProgress {
+  stage: 'structuring' | 'generating_audio' | 'creating_summary' | 'complete';
+  currentSegment?: number;
+  totalSegments?: number;
+  progress: number; // 0-100
+}
+```
+
+### 2. Segment Regeneration
+```typescript
+interface SegmentRegeneration {
+  segmentId: string;
+  status: 'pending' | 'generating' | 'complete' | 'error';
+  progress?: number;
+}
+```
+
+## Accessibility Requirements
+
+### 1. Audio Controls
+- Keyboard navigation for play/pause
+- Screen reader support for progress
+- Volume controls with labels
+
+### 2. Form Accessibility
+- Proper form labels
+- Error message associations
+- Required field indicators
+
+### 3. Navigation
+- Skip links for main content
+- Focus management
+- ARIA labels for interactive elements
+
+## Performance Considerations
+
+### 1. Audio Loading
+- Lazy load audio segments
+- Preload next segment
+- Implement audio caching
+
+### 2. Real-time Updates
+- Debounce frequent updates
+- Batch UI updates
+- Optimize re-renders
+
+### 3. Data Management
+- Implement pagination for episode lists
+- Cache episode metadata
+- Optimize image/audio loading
+
+## Testing Requirements
+
+### 1. Unit Tests
+- Component rendering
+- Event handling
+- Form validation
+
+### 2. Integration Tests
+- API interactions
+- Real-time event handling
+- Audio playback
+
+### 3. E2E Tests
+- Complete podcast generation flow
+- Playback functionality
+- Error scenarios
+
+## Browser Support
+
+### Required
+- Chrome 90+
+- Firefox 88+
+- Safari 14+
+- Edge 90+
+
+### Audio Support
+- Web Audio API
+- Media Source Extensions (for streaming)
+- AudioContext support
+
+## Security Considerations
+
+### 1. Audio URLs
+- Signed URLs expire after 24 hours
+- Implement URL refresh logic
+- Handle expired URL errors
+
+### 2. User Permissions
+- Verify workspace ownership
+- Validate episode access
+- Sanitize user inputs
+
+### 3. Content Security
+- Validate audio file types
+- Implement file size limits
+- Sanitize episode metadata

package/STUDYGUIDE_FRONTEND_SPEC.md

@@ -0,0 +1,18 @@
+## Study Guide Frontend Spec
+
+### Endpoints (tRPC)
+- **studyguide.get**: `{ workspaceId: string }` → `{ artifactId: string; title: string; latestVersion: { id: string; content: string; data?: Record<string, unknown> | null; version: number; createdById?: string | null; createdAt: Date } | null }`
+- **studyguide.edit**: `{ workspaceId: string; studyGuideId?: string; content: string; data?: Record<string, unknown>; title?: string }` → `{ artifactId: string; version: { id: string; version: number } }`
+
+### Behavior
+- `get` will create a default study guide (Editor.js starter block) if none exists.
+- `edit` creates a new artifact version and optionally renames the artifact.
+
+### Types (simplified)
+- **StudyGuideArtifact**: `{ id: string; workspaceId: string; type: 'STUDY_GUIDE'; title: string }`
+- **StudyGuideVersion**: `{ id: string; artifactId: string; content: string; data?: Record<string, unknown> | null; version: number; createdById?: string | null; createdAt: Date }`
+
+### UX Notes
+- Store Editor.js document JSON in `content`.
+- On save, call `studyguide.edit` (debounce to avoid excessive versions).
+- Handle null `latestVersion` gracefully (should be rare due to auto-create).

package/WORKSHEETS_FRONTEND_SPEC.md

@@ -0,0 +1,26 @@
+## Worksheets Frontend Spec
+
+### Endpoints (tRPC)
+- **worksheets.list**: `{ workspaceId: string }` → `Worksheet[]` (latest version included, questions merged with user progress)
+- **worksheets.create**: `{ workspaceId: string; title: string; description?: string; difficulty?: 'EASY'|'MEDIUM'|'HARD'; estimatedTime?: string; problems?: { question: string; answer: string; type?: QuestionType; options?: string[] }[] }` → `Worksheet & { questions: Question[] }`
+- **worksheets.get**: `{ worksheetId: string }` → `Worksheet & { questions: Question[] }` (questions merged with progress)
+- **worksheets.createWorksheetQuestion**: `{ worksheetId: string; prompt: string; answer?: string; type?: QuestionType; difficulty?: Difficulty; order?: number; meta?: Record<string, unknown> }` → `Question`
+- **worksheets.updateWorksheetQuestion**: `{ worksheetQuestionId: string; prompt?: string; answer?: string; type?: QuestionType; difficulty?: Difficulty; order?: number; meta?: Record<string, unknown> }` → `Question`
+- **worksheets.deleteWorksheetQuestion**: `{ worksheetQuestionId: string }` → `true`
+- **worksheets.updateProblemStatus**: `{ problemId: string; completed: boolean; answer?: string }` → `WorksheetQuestionProgress`
+- **worksheets.getProgress**: `{ worksheetId: string }` → `WorksheetQuestionProgress[]`
+- **worksheets.update**: `{ id: string; title?: string; description?: string; difficulty?: Difficulty; estimatedTime?: string; problems?: { id?: string; question: string; answer: string; type?: QuestionType; options?: string[] }[] }` → `Worksheet & { questions: Question[] }`
+- **worksheets.delete**: `{ id: string }` → `true`
+
+### Types (simplified)
+- **Worksheet**: `{ id: string; workspaceId: string; type: 'WORKSHEET'; title: string; description?: string | null; difficulty?: 'EASY'|'MEDIUM'|'HARD' | null; estimatedTime?: string | null; createdAt: Date; updatedAt: Date }`
+- **Question**: `{ id: string; artifactId: string; prompt: string; answer?: string | null; type: QuestionType; difficulty: Difficulty; order: number; meta?: { options?: string[]; completed?: boolean; userAnswer?: string | null; completedAt?: string | Date | null } }`
+- **QuestionType**: `'MULTIPLE_CHOICE'|'TEXT'|'NUMERIC'|'TRUE_FALSE'|'MATCHING'|'FILL_IN_THE_BLANK'`
+- **Difficulty**: `'EASY'|'MEDIUM'|'HARD'`
+- **WorksheetQuestionProgress**: `{ id: string; worksheetQuestionId: string; userId: string; completed: boolean; userAnswer?: string | null; completedAt?: Date | null; attempts: number }`
+
+### UX Notes
+- When listing or fetching a worksheet, question `meta` already contains per-user progress fields.
+- For multiple-choice, render `meta.options` if present.
+- Use optimistic UI for creating/updating/deleting questions.
+- Respect ordering via `order`.

package/WORKSPACE_FRONTEND_SPEC.md

@@ -0,0 +1,47 @@
+## Workspace Frontend Spec
+
+### Endpoints (tRPC)
+- **workspace.list**: `{ parentId?: string }` → `{ workspaces: Workspace[], folders: Folder[] }`
+- **workspace.create**: `{ name: string; description?: string; parentId?: string }` → `Workspace`
+- **workspace.createFolder**: `{ name: string; parentId?: string }` → `Folder`
+- **workspace.get**: `{ id: string }` → `Workspace & { artifacts: Artifact[]; folder?: Folder; uploads: FileAsset[] }`
+- **workspace.share**: `{ id: string }` → `{ shareLink: string } | void`
+- **workspace.join**: `{ shareLink: string }` → `{ id; title; description; ownerId; createdAt; updatedAt }`
+- **workspace.update**: `{ id: string; name?: string; description?: string }` → `Workspace`
+- **workspace.delete**: `{ id: string }` → `true`
+- **workspace.getFolderInformation**: `{ id: string }` → `{ folder: Folder; parents: Folder[] }`
+- **workspace.uploadFiles**: `{ id: string; files: { filename: string; contentType: string; size: number }[] }` → `{ fileId: string; uploadUrl: string }[]`
+- **workspace.deleteFiles**: `{ id: string; fileId: string[] }` → `true`
+- **workspace.uploadAndAnalyzeMedia**: `{ workspaceId: string; file: { filename: string; contentType: string; size: number; content: string /* base64 */ }; generateStudyGuide?: boolean; generateFlashcards?: boolean; generateWorksheet?: boolean }` → `{ filename: string; artifacts: { studyGuide: Artifact | null; flashcards: Artifact | null; worksheet: Artifact | null } }`
+- **workspace.search**: `{ query: string; limit?: number }` → `Workspace[]`
+
+### Types (simplified)
+- **Workspace**: `{ id: string; title: string; description?: string | null; ownerId: string; folderId?: string | null; createdAt: Date; updatedAt: Date; shareLink?: string | null }`
+- **Folder**: `{ id: string; name: string; ownerId: string; parentId?: string | null; createdAt: Date; updatedAt: Date }`
+- **Artifact**: `{ id: string; workspaceId: string; type: string; title: string; createdById?: string | null; createdAt: Date; updatedAt: Date }`
+- **FileAsset**: `{ id: string; userId: string; workspaceId: string; name: string; mimeType: string; size: number; bucket?: string | null; objectKey?: string | null }`
+
+### File Upload Flow
+1. Call `workspace.uploadFiles` to get write-signed URLs.
+2. PUT file bytes to each `uploadUrl` with correct `Content-Type`.
+3. Optionally refresh via `workspace.get` to see uploads.
+
+### Media Analysis Flow
+1. Call `workspace.uploadAndAnalyzeMedia` with base64 content and desired generation flags.
+2. Subscribe to Pusher `workspace_{workspaceId}` for progress events.
+3. On completion, fetch artifacts via `studyguide`, `worksheets`, and flashcards routers.
+
+### Real-Time Events (Pusher)
+- **Channel**: `workspace_{workspaceId}`
+- **Events** (examples):
+  - `{workspaceId}_file_analysis_start`, `{workspaceId}_file_analysis_complete`
+  - `{workspaceId}_study_guide_load_start`, `{workspaceId}_study_guide_info`
+  - `{workspaceId}_flash_card_load_start`, `{workspaceId}_flash_card_info`
+  - `{workspaceId}_worksheet_load_start`, `{workspaceId}_worksheet_info`
+  - `{workspaceId}_analysis_cleanup_start`, `{workspaceId}_analysis_cleanup_complete`
+  - Overall: `{workspaceId}_analysis_ended`
+
+### UX Notes
+- Empty state: show create workspace/folder actions.
+- Uploads: show progress per file; deletions from GCS are best-effort.
+- Search: debounce input; pass `limit` (default 20).

package/dist/context.d.ts

@@ -4,6 +4,6 @@ export declare function createContext({ req, res }: CreateExpressContextOptions)
     session: any;
     req: import("express").Request<import("express-serve-static-core").ParamsDictionary, any, any, import("qs").ParsedQs, Record<string, any>>;
     res: import("express").Response<any, Record<string, any>>;
-    cookies: any;
+    cookies: Record<string, string | undefined>;
 }>;
 export type Context = Awaited<ReturnType<typeof createContext>>;