@goscribe/server 1.0.8 → 1.0.10

package/AUTH_FRONTEND_SPEC.md

@@ -0,0 +1,21 @@
+## Auth Frontend Spec
+
+### Endpoints (tRPC)
+- **auth.signup**: `{ name: string; email: string; password: string }` → `{ id: string; email: string; name: string }`
+- **auth.login**: `{ email: string; password: string }` → `{ id: string; email: string; name: string; image?: string | null; token: string }` (also sets `auth_token` cookie)
+- **auth.getSession**: `void` → `{ user: { id: string; email: string; name: string; image?: string | null } }`
+- **auth.logout**: `void` → `{ success: true }` (clears `auth_token` cookie)
+
+### Cookie & Token
+- On login, server sets `auth_token` cookie (HTTP-only). Value is HMAC of base64 user id with `AUTH_SECRET`.
+- Cookie attributes:
+  - `httpOnly: true`
+  - `secure: true` in production
+  - `sameSite: 'none'` in production, `'lax'` in dev
+  - `domain: 'server-w8mz.onrender.com'` in production
+  - `maxAge: 30 days`
+
+### UX Notes
+- After `auth.login`, rely on cookie for session; also keep returned `token` if needed for client-side display.
+- Call `auth.getSession` on app bootstrap; if it throws, redirect to login.
+- On `auth.logout`, clear local user state immediately (optimistic) and navigate to login.

package/CHAT_FRONTEND_SPEC.md

@@ -0,0 +1,474 @@
+# Chat Frontend Integration Specification
+
+## Overview
+This document outlines the frontend requirements for integrating with the chat functionality, including real-time messaging, channel management, and user interactions.
+
+## Real-Time Events (Pusher)
+
+### Event Channels
+Chat events are broadcast on different channels:
+- Channel events: `workspace_{workspaceId}` 
+- Message events: `{channelId}` (the channelId itself is used as the channel name)
+
+### Event Types
+
+#### 1. Channel Management Events
+```typescript
+// New Channel Created
+{
+  event: '{workspaceId}_new_channel',
+  data: {
+    channelId: string,
+    workspaceId: string,
+    name: string,
+    createdAt: string
+  }
+}
+
+// Channel Edited
+{
+  event: '{workspaceId}_edit_channel',
+  data: {
+    channelId: string,
+    workspaceId: string,
+    name: string
+  }
+}
+
+// Channel Removed
+{
+  event: '{workspaceId}_remove_channel',
+  data: {
+    channelId: string,
+    deletedAt: string
+  }
+}
+```
+
+#### 2. Message Events
+```typescript
+// New Message Posted
+{
+  event: '{channelId}_new_message',
+  data: {
+    chatId: string,
+    channelId: string,
+    userId: string,
+    message: string,
+    createdAt: string
+  }
+}
+
+// Message Edited
+{
+  event: '{channelId}_edit_message',
+  data: {
+    chatId: string,
+    channelId: string,
+    userId: string,
+    message: string,
+    updatedAt: string
+  }
+}
+
+// Message Deleted
+{
+  event: '{channelId}_delete_message',
+  data: {
+    chatId: string,
+    channelId: string,
+    userId: string,
+    deletedAt: string
+  }
+}
+```
+
+## Data Types
+
+### Channel
+```typescript
+interface Channel {
+  id: string;
+  workspaceId: string;
+  name: string;
+  createdAt: string;
+  updatedAt: string;
+  chats?: ChatMessage[]; // Includes user information for each message
+}
+```
+
+### Chat Message
+```typescript
+interface ChatMessage {
+  id: string;
+  channelId: string;
+  userId: string;
+  message: string;
+  createdAt: string;
+  updatedAt: string;
+  user: {
+    id: string;
+    name: string;
+    image?: string;
+  };
+}
+```
+
+### User Information
+All messages include user information with:
+- `id`: User ID
+- `name`: User display name
+- `image`: User avatar (optional)
+
+## API Endpoints
+
+### 1. Get Channels
+```typescript
+// GET /trpc/chat.getChannels
+{
+  input: {
+    workspaceId: string;
+  }
+}
+// Returns all channels for a workspace with messages and user info
+// Creates "General" channel if no channels exist
+```
+
+### 2. Get Channel
+```typescript
+// GET /trpc/chat.getChannel
+{
+  input: {
+    workspaceId?: string;
+    channelId?: string;
+  }
+}
+// Returns specific channel with messages and user info
+// Creates "General" channel if workspaceId provided and no channelId
+```
+
+### 3. Create Channel
+```typescript
+// POST /trpc/chat.createChannel
+{
+  input: {
+    workspaceId: string;
+    name: string;
+  }
+}
+// Creates new channel and returns with messages and user info
+```
+
+### 4. Edit Channel
+```typescript
+// POST /trpc/chat.editChannel
+{
+  input: {
+    workspaceId: string;
+    channelId: string;
+    name: string;
+  }
+}
+// Updates channel name and returns with messages and user info
+```
+
+### 5. Remove Channel
+```typescript
+// POST /trpc/chat.removeChannel
+{
+  input: {
+    workspaceId: string;
+    channelId: string;
+  }
+}
+// Deletes channel and returns { success: true }
+```
+
+### 6. Post Message
+```typescript
+// POST /trpc/chat.postMessage
+{
+  input: {
+    channelId: string;
+    message: string;
+  }
+}
+// Creates new message and returns with user info
+```
+
+### 7. Edit Message
+```typescript
+// POST /trpc/chat.editMessage
+{
+  input: {
+    chatId: string;
+    message: string;
+  }
+}
+// Updates message and returns with user info
+// Only allows editing own messages
+```
+
+### 8. Delete Message
+```typescript
+// POST /trpc/chat.deleteMessage
+{
+  input: {
+    chatId: string;
+  }
+}
+// Deletes message and returns { success: true }
+// Only allows deleting own messages
+```
+
+## UI Components
+
+### 1. Channel List Component
+```typescript
+interface ChannelList {
+  channels: Channel[];
+  currentChannelId?: string;
+  onChannelSelect: (channelId: string) => void;
+  onCreateChannel: (name: string) => void;
+  onEditChannel: (channelId: string, name: string) => void;
+  onDeleteChannel: (channelId: string) => void;
+}
+```
+
+### 2. Chat Interface Component
+```typescript
+interface ChatInterface {
+  channelId: string;
+  messages: ChatMessage[];
+  currentUserId: string;
+  onSendMessage: (message: string) => void;
+  onEditMessage: (chatId: string, message: string) => void;
+  onDeleteMessage: (chatId: string) => void;
+  isLoading: boolean;
+}
+```
+
+### 3. Message Component
+```typescript
+interface MessageComponent {
+  message: ChatMessage;
+  isOwnMessage: boolean;
+  onEdit: (chatId: string, newMessage: string) => void;
+  onDelete: (chatId: string) => void;
+}
+```
+
+## User Experience Flow
+
+### 1. Channel Management
+1. User opens workspace
+2. Load all channels using `getChannels` endpoint
+3. System automatically creates "General" channel if no channels exist
+4. User can create new channels
+5. User can edit channel names
+6. User can delete channels (with confirmation)
+7. Real-time updates when channels are created/edited/deleted
+
+### 2. Messaging Flow
+1. User selects a channel
+2. Load existing messages for the channel (includes user info)
+3. User types and sends message
+4. Message appears immediately (optimistic update)
+5. Real-time notification to other users
+6. Handle message editing and deletion
+7. Show user names and avatars for all messages
+
+### 3. Message Management
+1. User can edit their own messages only
+2. User can delete their own messages only
+3. Real-time updates for message changes
+4. Proper error handling for unauthorized actions
+
+## Real-Time Implementation
+
+### PusherService Methods
+The chat system uses two different PusherService methods:
+- `emitTaskComplete(workspaceId, event, data)` - For channel management events
+- `emitChannelEvent(channelId, event, data)` - For message events (channel-specific)
+
+### 1. Initial Channel Loading
+```typescript
+// Load all channels for a workspace
+const channels = await trpc.chat.getChannels.query({ 
+  workspaceId: workspaceId 
+});
+
+// This will automatically create a "General" channel if none exist
+// All channels include messages with user information
+```
+
+### 2. Channel Events (Workspace Channel)
+```typescript
+// Subscribe to workspace channel events
+const workspaceChannel = pusher.subscribe(`workspace_${workspaceId}`);
+
+workspaceChannel.bind(`${workspaceId}_new_channel`, (data) => {
+  // Add new channel to list
+  setChannels(prev => [...prev, data]);
+});
+
+workspaceChannel.bind(`${workspaceId}_edit_channel`, (data) => {
+  // Update channel name in list
+  setChannels(prev => prev.map(ch => 
+    ch.id === data.channelId ? { ...ch, name: data.name } : ch
+  ));
+});
+
+workspaceChannel.bind(`${workspaceId}_remove_channel`, (data) => {
+  // Remove channel from list
+  setChannels(prev => prev.filter(ch => ch.id !== data.channelId));
+});
+```
+
+### 3. Message Events (Channel-Specific)
+```typescript
+// Subscribe to message events for specific channel
+const messageChannel = pusher.subscribe(channelId);
+
+messageChannel.bind(`${channelId}_new_message`, (data) => {
+  // Add new message to chat
+  setMessages(prev => [...prev, data]);
+});
+
+messageChannel.bind(`${channelId}_edit_message`, (data) => {
+  // Update message in chat
+  setMessages(prev => prev.map(msg => 
+    msg.id === data.chatId ? { ...msg, message: data.message, updatedAt: data.updatedAt } : msg
+  ));
+});
+
+messageChannel.bind(`${channelId}_delete_message`, (data) => {
+  // Remove message from chat
+  setMessages(prev => prev.filter(msg => msg.id !== data.chatId));
+});
+```
+
+## Error Handling
+
+### 1. Channel Errors
+- Channel not found
+- Unauthorized to edit/delete channel
+- Duplicate channel names
+
+### 2. Message Errors
+- Message not found
+- Unauthorized to edit/delete message (only own messages)
+- Message too long
+- Rate limiting
+
+### 3. Network Errors
+- Connection lost
+- Retry logic for failed operations
+- Offline indicators
+
+## Loading States
+
+### 1. Channel Loading
+```typescript
+interface ChannelLoadingState {
+  isLoading: boolean;
+  error?: string;
+  channels: Channel[];
+}
+```
+
+### 2. Message Loading
+```typescript
+interface MessageLoadingState {
+  isLoading: boolean;
+  isSending: boolean;
+  error?: string;
+  messages: ChatMessage[];
+}
+```
+
+## Security & Authorization
+
+### 1. Message Ownership
+- Users can only edit their own messages
+- Users can only delete their own messages
+- Proper validation on server side
+
+### 2. Channel Access
+- Users can only access channels in their workspaces
+- Proper workspace membership validation
+
+### 3. Input Validation
+- Message content validation
+- Channel name validation
+- Rate limiting for message sending
+
+## Performance Considerations
+
+### 1. Message Loading
+- All messages include user info (no additional queries needed)
+- Efficient database queries with includes
+- Proper indexing on channelId and userId
+
+### 2. Real-time Updates
+- Separate channels for workspace and message events
+- Efficient event routing
+- Optimized payload sizes
+
+### 3. Memory Management
+- Clean up Pusher subscriptions when switching channels
+- Limit message history in memory
+- Garbage collection for old messages
+
+## Testing Requirements
+
+### 1. Unit Tests
+- Component rendering with user info
+- Message formatting and display
+- Channel management logic
+
+### 2. Integration Tests
+- API interactions with user data
+- Real-time event handling
+- Authorization scenarios
+
+### 3. E2E Tests
+- Complete messaging flow with user attribution
+- Channel management
+- Real-time synchronization
+
+## Browser Support
+
+### Required
+- Chrome 90+
+- Firefox 88+
+- Safari 14+
+- Edge 90+
+
+### Real-time Support
+- WebSocket support
+- Pusher client compatibility
+- EventSource fallback
+
+## Future Enhancements
+
+### 1. Advanced Features
+- Message reactions
+- File attachments
+- Voice messages
+- Message threading
+- Read receipts
+
+### 2. UI Improvements
+- Typing indicators
+- Message search
+- Message pinning
+- Channel categories
+- Dark mode support
+
+### 3. Performance Optimizations
+- Message pagination
+- Virtual scrolling
+- Offline support
+- Background sync
+- Push notifications

package/DATABASE_SETUP.md

@@ -0,0 +1,165 @@
+# 🗄️ Database Setup Guide
+
+## 📋 Overview
+This guide covers the database configuration for the Scribe server, including Prisma setup, environment variables, and troubleshooting common connection issues.
+
+---
+
+## 🔧 Environment Variables Required
+
+### Core Database Configuration
+```bash
+# Pooled connection (for runtime queries)
+DATABASE_URL="postgresql://<db_user>:<db_password>@aws-1-ap-southeast-1.pooler.supabase.com:5432/postgres?sslmode=require"
+
+# Direct connection (for migrations and schema operations)
+DIRECT_URL="postgresql://<db_user>:<db_password>@db.<project-ref>.supabase.co:5432/postgres?sslmode=require"
+```
+
+### 🔍 Where to Find These Values
+1. Go to your Supabase project dashboard
+2. Navigate to **Settings** → **Database**
+3. Copy the connection strings from:
+   - **Connection pooling** → `DATABASE_URL`
+   - **Direct connection** → `DIRECT_URL`
+
+---
+
+## 🚀 Quick Setup Steps
+
+### 1. Set Environment Variables
+```bash
+# Option A: Export for current session
+export DATABASE_URL="your_pooled_connection_string"
+export DIRECT_URL="your_direct_connection_string"
+
+# Option B: Add to .env file
+echo "DATABASE_URL=your_pooled_connection_string" >> .env
+echo "DIRECT_URL=your_direct_connection_string" >> .env
+```
+
+### 2. Generate Prisma Client
+```bash
+npm run build
+```
+
+### 3. Run Migrations (if needed)
+```bash
+npx prisma migrate deploy
+```
+
+### 4. Seed Database (optional)
+```bash
+npm run seed
+```
+
+---
+
+## 🏗️ Database Schema Overview
+
+### Core Models
+- **User** - Authentication and user management
+- **Workspace** - Project containers with folders
+- **Channel** - Chat channels within workspaces
+- **Chat** - Individual chat messages
+- **Artifact** - AI-generated content (study guides, flashcards, etc.)
+- **FileAsset** - User uploads and attachments
+
+### Key Relationships
+```
+User → Workspaces → Channels → Chats
+User → Artifacts → Versions/Questions/Flashcards
+Workspace → FileAssets
+```
+
+---
+
+## 🐛 Troubleshooting
+
+### ❌ "Tenant or user not found" Error
+
+**Cause:** Incorrect database credentials or connection string format
+
+**Solutions:**
+1. **Verify credentials** in Supabase dashboard
+2. **Check connection string format:**
+   ```bash
+   # ✅ Correct format
+   postgresql://user:password@host:port/database?sslmode=require
+   
+   # ❌ Common mistakes
+   postgresql://user:password@host:port/database  # Missing sslmode
+   postgresql://user:password@host:port          # Missing database name
+   ```
+
+3. **Ensure proper URL encoding** for special characters in passwords
+4. **Use direct connection** for migrations (not pooled)
+
+### ❌ Migration Failures
+
+**Cause:** Using pooled connection for schema operations
+
+**Solution:** Always use `DIRECT_URL` for migrations
+```bash
+# ✅ Correct
+DIRECT_URL="postgresql://user:pass@db.project.supabase.co:5432/postgres?sslmode=require"
+
+# ❌ Wrong
+DIRECT_URL="postgresql://user:pass@aws-1-ap-southeast-1.pooler.supabase.com:5432/postgres?sslmode=require"
+```
+
+### ❌ Connection Timeouts
+
+**Solutions:**
+1. Check Supabase project status
+2. Verify network connectivity
+3. Ensure SSL mode is set to `require`
+4. Check if IP is whitelisted (if using IP restrictions)
+
+---
+
+## 📊 Database Operations
+
+### Available Scripts
+```bash
+# Development
+npm run dev          # Start development server
+
+# Database
+npm run build        # Generate Prisma client + build
+npm run seed         # Populate with sample data
+npx prisma studio    # Open database browser
+npx prisma migrate dev    # Create and apply migrations
+npx prisma migrate deploy # Apply existing migrations
+```
+
+### Sample Data
+The seed script creates:
+- Demo user (`demo@example.com`)
+- Sample workspace with artifacts
+- Worksheet with mixed question types
+- Flashcard set
+- Study guide with versions
+
+---
+
+## 🔐 Security Notes
+
+- **Never commit** `.env` files to version control
+- **Use environment-specific** connection strings
+- **Enable SSL** (`sslmode=require`) for all connections
+- **Rotate credentials** regularly
+- **Use connection pooling** for production workloads
+
+---
+
+## 📚 Additional Resources
+
+- [Prisma Documentation](https://www.prisma.io/docs)
+- [Supabase Database Guide](https://supabase.com/docs/guides/database)
+- [PostgreSQL Connection Strings](https://www.postgresql.org/docs/current/libpq-connect.html)
+
+---
+
+*Last updated: $(date)*
+

package/MEETINGSUMMARY_FRONTEND_SPEC.md

@@ -0,0 +1,28 @@
+## Meeting Summary Frontend Spec
+
+Note: The `meetingsummary` router is currently commented out. This spec outlines the intended API based on the commented code and typical flows, so the frontend contract is ready when implementation resumes.
+
+### Proposed Endpoints (tRPC)
+- **meetingsummary.listSummaries**: `{ workspaceId: string }` → `Artifact[]` (type: `MEETING_SUMMARY`, latest version included)
+- **meetingsummary.getSummary**: `{ summaryId: string }` → `Artifact & { versions: Version[] }`
+- **meetingsummary.uploadFile**: `{ workspaceId: string; fileName: string; fileBuffer: string /* base64 */; mimeType: string; title?: string }` → `{ id: string; title: string; summary: SummaryData; transcript: string }`
+- **meetingsummary.processSchema**: `{ workspaceId: string; meetingData: MeetingSchema }` → `{ id: string; title: string; summary: SummaryData; originalData: MeetingSchema }`
+- **meetingsummary.updateSummary**: `{ summaryId: string; title?: string; content?: string }` → `Artifact`
+- **meetingsummary.deleteSummary**: `{ summaryId: string }` → `true`
+- **meetingsummary.getVersions**: `{ summaryId: string }` → `Version[]`
+
+### Types (simplified)
+- **Artifact**: `{ id; workspaceId; type: 'MEETING_SUMMARY'; title; content?; createdAt; updatedAt }`
+- **Version**: `{ id; artifactId; version: number; content: string; createdAt }`
+- **MeetingSchema**: `{ title: string; participants: string[]; date: string; duration?: string; agenda?: string[]; transcript?: string; notes?: string }`
+- **SummaryData**: `{ keyPoints: string[]; actionItems: string[]; decisions: string[]; nextSteps: string[]; insights?: string[]; summary: string }`
+
+### Upload Flow (when implemented)
+1. Validate file type (mp3/mp4/wav/m4a).
+2. Upload base64 file; backend transcribes (Whisper) then summarizes (GPT), stores artifact + version.
+3. Return summary JSON and transcript.
+
+### UX Notes
+- Show parsing progress and handle large files.
+- Provide manual schema entry as fallback (processSchema).
+- Keep version history for edits; show latest version by default.