@caitdesk/client 0.5.0 → 0.5.1

package/README.md

@@ -51,7 +51,7 @@ const client = new CaitDeskClient({
 
 // Subscribe to an event's broadcast
 await client.subscribe('event-id', {
-  onCaption: (text, seq) => console.log('Caption:', text),
+  onCaption: (text, seq, meta) => console.log('Caption:', text, meta?.latency),
   onStatus: (status) => console.log('Event status:', status),
   onViewerCount: (count) => console.log('Viewers:', count),
   onError: (err) => console.error('Error:', err.message),
@@ -116,17 +116,6 @@ client.startEvent(eventId: string): Promise<{ success: boolean }>
 client.stopEvent(eventId: string): Promise<{ success: boolean }>
 ```
 
-### Standalone Functions
-
-#### `checkEvent(apiUrl, eventId, fetchFn?)`
-
-Public endpoint — no API key required. Returns `{ exists: boolean; joinable: boolean }`. Useful for validating an event ID before attempting a WebSocket connection. On network errors, returns `{ exists: false, joinable: false }`.
-
-- `getMe()` — returns the authenticated user's info
-- `getEvents()` — returns events assigned to you as captioner (scheduled and live only)
-- `startEvent(eventId)` — start an event via REST (scheduled → live). Requires `captioner:control` scope
-- `stopEvent(eventId)` — stop an event via REST (live → ended). Requires `captioner:control` scope
-
 #### Connection
 
 ```ts
@@ -176,7 +165,7 @@ client.unsubscribe(): void
 
 ```ts
 await client.subscribe(eventId, {
-  onCaption: (text, seq) => console.log('Caption:', text),
+  onCaption: (text, seq, meta) => console.log('Caption:', text, meta?.latency),
   onStatus: (status) => console.log('Event status:', status),
   onViewerCount: (count) => console.log('Viewers:', count),
   onError: (err) => console.error('Error:', err.message),
@@ -190,6 +179,12 @@ client.unsubscribe();
 
 The captioner connection (`connect`/`disconnect`) and broadcast subscription (`subscribe`/`unsubscribe`) are fully independent and can run simultaneously.
 
+### Standalone Functions
+
+#### `checkEvent(apiUrl, eventId, fetchFn?)`
+
+Public endpoint — no API key required. Returns `{ exists: boolean; joinable: boolean }`. Useful for validating an event ID before attempting a WebSocket connection. On network errors, returns `{ exists: false, joinable: false }`.
+
 ### Configuration
 
 ```ts
@@ -232,15 +227,33 @@ interface User { id: string; email: string; name: string | null }
 interface Event { id: string; organizationId: string; title: string; description: string | null; scheduledStart: string; scheduledEnd: string | null; status: string; clientName: string | null }
 interface CaptionAck { type: 'ack'; timestamp: number; seq: number }
 interface ControlAck { type: 'ack'; action: string }
-interface ServerError { type: 'error'; code: string; message: string; details?: Record<string, unknown> }
+interface ServerError { type: 'error'; code: ErrorCodeValue; message: string; details?: Record<string, unknown> }
 interface SlotDetail { position?: number; activeSince?: string }
 ```
 
+#### Utility types
+
+```ts
+type ConnectionStatus = 'disconnected' | 'connecting' | 'connected' | 'reconnecting'
+type SlotStatus = 'unknown' | 'active' | 'waiting'
+type ControlActionValue = (typeof CONTROL_ACTION)[keyof typeof CONTROL_ACTION]
+type ErrorCodeValue = (typeof ERROR_CODE)[keyof typeof ERROR_CODE]
+interface EventCheckResult { exists: boolean; joinable: boolean }
+```
+
 #### Broadcast types
 
+```ts
+interface BroadcastCaptionMessage { type: 'caption'; eventId: string; seq: number; text: string; ts?: number; lineTs?: number[] }
+interface BroadcastStatusMessage { type: 'status'; eventId: string; status: string; scheduledStart?: string }
+interface BroadcastViewerCountMessage { type: 'viewers'; eventId: string; count: number }
+interface BroadcastEventEndedMessage { type: 'event_ended'; eventId: string; message: string }
+type BroadcastMessage = BroadcastCaptionMessage | BroadcastStatusMessage | BroadcastViewerCountMessage | BroadcastEventEndedMessage | ServerError
+```
+
 ```ts
 interface SubscribeConfig {
-  onCaption?: (text: string, seq: number) => void;
+  onCaption?: (text: string, seq: number, meta?: { ts?: number; lineTs?: number[]; latency?: number }) => void;
   onStatus?: (status: string, detail?: { scheduledStart?: string }) => void;
   onViewerCount?: (count: number) => void;
   onError?: (error: ServerError) => void;
@@ -251,7 +264,7 @@ interface SubscribeConfig {
 
 | Callback         | When it fires                                           |
 | ---------------- | ------------------------------------------------------- |
-| `onCaption`      | New caption text received (full text state + seq)       |
+| `onCaption`      | New caption text received (full text state + seq + optional meta with `ts`, `lineTs`, `latency`) |
 | `onStatus`       | Event status changes (waiting/live/ended)               |
 | `onViewerCount`  | Viewer count updates                                    |
 | `onError`        | Server sends an error message                           |
@@ -261,10 +274,18 @@ interface SubscribeConfig {
 ### Constants
 
 ```ts
-import { EVENT_STATUS, ERROR_CODE, RATE_LIMITS, CONNECTION_DEFAULTS } from '@caitdesk/client';
+import { EVENT_STATUS, ERROR_CODE, RATE_LIMITS, CONNECTION_DEFAULTS, SESSION_ACTION, CONTROL_ACTION, WS_CLOSE_CODE } from '@caitdesk/client';
 ```
 
-- `EVENT_STATUS` — event status values (`DRAFT`, `SCHEDULED`, `LIVE`, `ENDED`, `ARCHIVED`, `CANCELLED`)
+| Constant | Description |
+|----------|-------------|
+| `EVENT_STATUS` | Event status values (`DRAFT`, `SCHEDULED`, `LIVE`, `ENDED`, `ARCHIVED`, `CANCELLED`) |
+| `ERROR_CODE` | Error codes from the API and gateway (auth, validation, WebSocket, rate limiting) |
+| `RATE_LIMITS` | Gateway-enforced limits (max message rate, text lengths, timestamp drift) |
+| `CONNECTION_DEFAULTS` | Reconnect timing (initial delay, max delay, multiplier, request timeout) |
+| `SESSION_ACTION` | Slot management actions (`SLOT_GRANTED`, `SLOT_OCCUPIED`, `SLOT_REQUESTED`, `SLOT_REQUEST_CANCELLED`, `SLOT_RELEASE`) |
+| `CONTROL_ACTION` | Event control actions (`START`, `STOP`, `PAUSE`, `RESUME`) |
+| `WS_CLOSE_CODE` | WebSocket close codes with special meaning (`NORMAL`, `AUTH_FAILED`, `SLOT_FULL`) |
 
 ## API Key Scopes
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@caitdesk/client",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "type": "module",
   "description": "Official TypeScript client for the CaitDesk captioner API",
   "exports": {
@@ -26,5 +26,22 @@
   },
   "devDependencies": {
     "typescript": "^5.7.2"
-  }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "Proprietary",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/caitdesk/caitdesk",
+    "directory": "packages/caitdesk-client"
+  },
+  "keywords": [
+    "caitdesk",
+    "captions",
+    "captioner",
+    "client",
+    "websocket",
+    "real-time"
+  ]
 }