type ChatMessage = {
  content: string  // text only
}

type ChatMessage = {
  id: string
  roomId: string
  senderId: string
  senderKind: 'human' | 'ai'
  senderName: string
  content: string
  attachments: Attachment[]
  createdAt: Date
}

type Attachment = {
  id: string
  type: 'image' | 'voice' | 'video'
  url: string
  thumbnailUrl?: string  // for video
  duration?: number      // for voice/video
  mimeType: string
  size: number
}

// Image attachment
class ImageAttachmentDto {
  id: string
  url: string
  width: number
  height: number
  mimeType: string
}

// Voice attachment
class VoiceAttachmentDto {
  id: string
  url: string
  duration: number  // seconds
  mimeType: string
  waveformUrl?: string
}

// Video attachment
class VideoAttachmentDto {
  id: string
  url: string
  thumbnailUrl: string
  duration: number
  mimeType: string
}

// apps/nestjs/src/storage/r2.service.ts
export class R2Service {
  async uploadImage(roomId: string, userId: string, file: Buffer): Promise<string>
  async uploadVoice(roomId: string, userId: string, file: Buffer): Promise<string>
  async getSignedUploadUrl(roomId: string, userId: string, contentType: string): Promise<string>
  async getSignedDownloadUrl(key: string): Promise<string>
}

// apps/nestjs/src/storage/stream.service.ts
export class StreamService {
  async createDirectUploadUrl(): Promise<{ uid: string; uploadUrl: string }>
  async getVideoUrl(uid: string): Promise<string>
  async getThumbnailUrl(uid: string): Promise<string>
}

// Client sends
{ type: 'message.send', content: 'Hello', requestId: '123' }

// Server broadcasts
{ type: 'message.created', message: { id, content, ... } }

// Client sends
{
  type: 'message.send',
  content: 'Check out this!',
  attachments: [{ type: 'image', uploadId: 'upload_123' }],
  requestId: '123'
}

// Server broadcasts
{
  type: 'message.created',
  message: {
    id,
    content: 'Check out this!',
    attachments: [{ id, type: 'image', url: 'https://...', ... }]
  }
}

// Server -> Client
{ type: 'upload.progress', uploadId: 'upload_123', progress: 50 }
{ type: 'upload.complete', uploadId: 'upload_123', attachment: {...} }
{ type: 'upload.error', uploadId: 'upload_123', error: 'File too large' }

// useConvexGroupChat - add attachment support
sendMessage(content: string, attachments?: AttachmentUpload[])

// useVickyChat - add image attachment support
sendMessage(content: string, imageUrl?: string)

const vickyAgent = new Agent({
  instructions: `
    You can see images that users share.
    Describe what you see when relevant.
  `,
  model: anthropic(process.env.MASTRA_MODEL, {
    multimodal: true  // Enable vision
  })
})

apps/nestjs/src/
├── chat/
│   ├── dto/
│   │   ├── chat.dto.ts          # Extended with attachments
│   │   └── attachment.dto.ts     # New: Attachment DTOs
│   ├── entities/
│   │   └── chat.entities.ts     # Extended ChatMessage
│   ├── realtime/
│   │   └── chat-realtime.gateway.ts  # Handle attachments
│   └── services/
│       └── chat.service.ts       # Save attachments
├── media/
│   ├── media.module.ts
│   ├── media.controller.ts       # Upload URL endpoints
│   ├── r2.service.ts            # R2 operations
│   └── stream.service.ts         # Cloudflare Stream
└── storage/
    └── storage.service.ts       # Unified storage interface

# R2
R2_ACCOUNT_ID=
R2_ACCESS_KEY_ID=
R2_SECRET_ACCESS_KEY=
R2_BUCKET_NAME=

# Cloudflare Stream
CLOUDFLARE_ACCOUNT_ID=
CLOUDFLARE_API_TOKEN=

# Create room
curl -X POST /v1/chat/rooms ...

# Get signed upload URL
curl -X POST /v1/media/upload-url \
  -H "x-user-id: user_alice" \
  -d '{ "roomId": "room_123", "contentType": "image/jpeg" }'

# Upload message with attachment
curl -X POST /v1/chat/rooms/:roomId/messages \
  -d '{ "content": "Look at this!", "attachments": [{ "id": "att_1", "type": "image", "url": "https://..." }] }'

// Send message with attachment
socket.emit('message.send', {
  content: 'Check out this photo',
  attachments: [{ id: 'att_1', type: 'image', url: 'https://r2.nous.../img.jpg' }],
  requestId: '123'
})

// Receive with attachment
socket.on('message.created', (data) => {
  console.log(data.message.attachments)
})