@goscribe/server 1.0.10 → 1.1.0

package/PODCAST_FRONTEND_SPEC.md

@@ -1,595 +0,0 @@
-# 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

@@ -1,18 +0,0 @@
-## 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

@@ -1,26 +0,0 @@
-## 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

@@ -1,47 +0,0 @@
-## 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).