@craftedxp/sdk-node 0.12.0 → 0.15.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -58,7 +58,7 @@ client.callTokens.revoke(tokenId)
58
58
  ```ts
59
59
  client.me.get() // the org behind the sk_
60
60
 
61
- client.agents.create({ name, systemPrompt, ... }) // CRUD on agents
61
+ client.agents.create({ type, name, systemPrompt, ... }) // CRUD on agents (type required)
62
62
  client.agents.list({ limit, cursor })
63
63
  client.agents.get(agentId)
64
64
  client.agents.update(agentId, patch)
@@ -88,6 +88,26 @@ client.rooms.transcript(roomId, { cursor, limit })
88
88
  client.rooms.end(roomId)
89
89
  ```
90
90
 
91
+ ## Agent types
92
+
93
+ Every agent has a `type` set at creation and **immutable** thereafter (changing
94
+ what an agent does means creating a new one). It gates which routes accept the
95
+ agent:
96
+
97
+ | `type` | Does | Use with |
98
+ | ------------ | --------------------------------------------------------- | ------------------------------------------------- |
99
+ | `assistant` | 1:1 voice + text chat + learning mode (LLM + STT + TTS) | `@craftedxp/voice-js/assistant`, text chat, calls |
100
+ | `room` | Hosts LiveKit rooms; per-speaker transcription + analysis | `client.rooms.*`, `@craftedxp/voice-js/room` |
101
+ | `transcribe` | 1:1 dictation, STT-only (agent never speaks) | `@craftedxp/voice-js/transcribe` |
102
+
103
+ ```ts
104
+ await client.agents.create({ type: 'assistant', name: 'Concierge', systemPrompt: '…' })
105
+ ```
106
+
107
+ `type` is omitted from `AgentUpdateInput` — `agents.update` cannot change it.
108
+ The legacy `canHostRooms` / `transcribeOnly` boolean flags are **removed**;
109
+ sending them is a 400. Use `type: 'room'` / `type: 'transcribe'` instead.
110
+
91
111
  ## Multi-party video rooms
92
112
 
93
113
  Provision a hosted room from your backend; share the single returned link;
@@ -96,14 +116,17 @@ participants join with **video** in the browser via `@craftedxp/voice-js`
96
116
  per speaker — the human-to-human video call works regardless.
97
117
 
98
118
  ```ts
99
- // Backend — the agent must be allowed to host rooms. Enable it from code
100
- // (since 0.10.1) instead of the dashboard:
101
- await client.agents.update(agentId, { canHostRooms: true, roomMode: 'notes-only' })
102
- // (you can also pass canHostRooms/roomMode to `agents.create`.)
119
+ // Backend — create a room-type agent (immutable; can't be flipped later).
120
+ const agent = await client.agents.create({
121
+ type: 'room',
122
+ name: 'Notetaker',
123
+ systemPrompt: 'take notes',
124
+ roomMode: 'notes-only',
125
+ })
103
126
 
104
127
  // Mint a room. Returns ONE shared joinToken + a joinUrl; the raw token is
105
128
  // returned once and never stored.
106
- const room = await client.rooms.create({ agentId, durationMin: 30 })
129
+ const room = await client.rooms.create({ agentId: agent.agentId, durationMin: 30 })
107
130
  // → { roomId, status: 'provisioning', joinToken, joinUrl, expiresAt }
108
131
 
109
132
  // Hand `roomId` + `joinToken` to the browser. There, with @craftedxp/voice-js:
@@ -121,18 +144,82 @@ await client.rooms.end(room.roomId)
121
144
  A complete, runnable consumer app (backend + browser video UI) lives in
122
145
  [`examples/video-call`](../../examples/video-call).
123
146
 
124
- ### Transcribe-only agents
147
+ ### Transcribe agents
148
+
149
+ Create an agent with `type: 'transcribe'` for one that **listens but never
150
+ speaks** — no TTS/LLM, no greeting; user turns stream back as `transcript`
151
+ data-messages over the existing call/WebRTC transport. Useful for note-taking /
152
+ dictation surfaces that reuse the agent + call-mint plumbing but want the agent
153
+ silent. Pair it with `@craftedxp/voice-js/transcribe` on the client.
154
+
155
+ ```ts
156
+ await client.agents.create({ type: 'transcribe', name: 'Scribe', systemPrompt: 'n/a' })
157
+ ```
158
+
159
+ ## Spaces (durable multi-party meeting spaces)
160
+
161
+ A **space** is a stable join code in front of the rooms subsystem: create it once,
162
+ share the code, and N participants each join with their own identity. Use this when
163
+ you want a reusable, schedulable meeting link rather than a one-shot room.
164
+
165
+ ```ts
166
+ import { PlatformClient, buildJoinUrl } from '@craftedxp/sdk-node'
167
+
168
+ const platform = new PlatformClient({ apiKey: process.env.VOISSIA_SK_KEY! })
169
+
170
+ // 1. Create a space (the agent must be type 'room').
171
+ const space = await platform.spaces.create({ agentId: 'agt_room' })
172
+
173
+ // 2. Build the participant link on YOUR domain (white-label — never a voissia
174
+ // URL). Default 'query' style matches how <VoiceRoom/> reads ?code=.
175
+ const joinUrl = buildJoinUrl(space, { baseUrl: 'https://app.yourdomain.com/room' })
176
+ // → https://app.yourdomain.com/room?code=abc-defg-hij
177
+ // path style: buildJoinUrl(space, { baseUrl: '…/room', style: 'path' }) → …/room/abc-defg-hij
178
+ // (also available as platform.spaces.joinUrl(space, { baseUrl }))
179
+
180
+ // 3. Manage the space.
181
+ await platform.spaces.get(space.spaceId)
182
+ await platform.spaces.list() // → { data: SpaceView[] }
183
+ await platform.spaces.update(space.spaceId, { notesEnabled: false })
184
+ await platform.spaces.delete(space.spaceId)
185
+ ```
186
+
187
+ The public join exchange (a participant redeeming the code for a token) and host
188
+ controls / recording are client- and host-side — see `@craftedxp/voice-room-react`.
125
189
 
126
- Set `transcribeOnly: true` (on `agents.create` or `agents.update`, since 0.10.1)
127
- for an agent that **listens but never speaks** — no TTS/LLM, no greeting; user
128
- turns stream back as `transcript` data-messages over the existing call/WebRTC
129
- transport. Useful for note-taking / dictation surfaces that reuse the agent +
130
- call-mint plumbing but want the agent silent.
190
+ ## Pre-generated speech
191
+
192
+ Synthesise agent audio ahead of time same voice as a live call, stored
193
+ behind a signed URL for one-way content (briefings, reminders, countdowns).
131
194
 
132
195
  ```ts
133
- await client.agents.create({ name: 'Scribe', systemPrompt: 'n/a', transcribeOnly: true })
196
+ // Batch path: enqueue at T-30 min, receive `speech.ready` via webhook.
197
+ const job = await client.speech.enqueue({
198
+ agentId: 'agt_…',
199
+ context: { goals: ['run 5k'], weather: 'sunny, 18°C' },
200
+ instructions: '60–90 seconds, upbeat, finish by handing over to the live conversation',
201
+ idempotencyKey: `${deviceId}:${alarmId}:${yyyymmdd}`,
202
+ userTags: ['premium'],
203
+ ttlSeconds: 6 * 3600,
204
+ metadata: { deviceId, alarmId },
205
+ })
206
+ // Note: if `idempotencyKey` matches an existing *ready* asset, the server
207
+ // short-circuits the queue hop and `enqueue` resolves with that SpeechAsset
208
+ // (status 200) instead of a SpeechJob (status 202) — check `.status`.
209
+
210
+ // Sync path for short clips / dev: resolves with the ready asset.
211
+ try {
212
+ const asset = await client.speech.synthesize({ agentId: 'agt_…', text: 'Good morning!' })
213
+ console.log(asset.url, asset.durationMs)
214
+ } catch (err) {
215
+ if (err instanceof PlatformError && err.code === 'accepted') {
216
+ const job = err.body as SpeechJob // server handed off to the queue
217
+ }
218
+ }
134
219
  ```
135
220
 
221
+ Webhooks: `speech.ready` (`data: SpeechAsset`) and `speech.failed` (`data: SpeechJob`). Subscribe them on the agent's webhook like any other event. `format: 'ogg'` is reserved (400 today); `sampleRate` 24k/48k are upsampled from the provider's 16 kHz.
222
+
136
223
  ## Webhook signature verification
137
224
 
138
225
  ```ts
@@ -194,6 +281,12 @@ for await (const call of client.calls.listAll({ agentId })) {
194
281
  - Browser-side use. This SDK assumes a server-side environment with native `fetch`. The `sk_` API key must never reach a browser.
195
282
  - Phone numbers, outbound dialling. Telephony is on the platform roadmap; the SDK will surface it when the server endpoints land.
196
283
 
284
+ ## Changelog
285
+
286
+ - **Unreleased** _(forward-looking)_ — `isPersonal?: boolean` on `Agent` and `AgentCreateInput` (and so on `AgentUpdateInput`). Assistant-only: when `true`, the learning tools (`remember_fact`, `add_correction`, `add_skill_hint`) are live on every `ct_`-token call rather than only on `mode=learning`. Server-side field — no runtime change in this package.
287
+ - **0.15.0** — `client.speech` namespace (`synthesize` / `enqueue` / `get` / `list` / `delete`) for pre-generated agent audio (`POST /v1/speech`), plus `speech.ready` / `speech.failed` webhook event types and the `accepted` error code (`synthesize` → 202 handoff). Requires server ≥ the 2026-08 speech release.
288
+ - **0.14.0** — `client.spaces` namespace (create / get / list / update / delete) for durable multi-party spaces, plus the standalone `buildJoinUrl(spaceOrCode, { baseUrl, style? })` helper for white-label participant links. No server changes — the `/v1/spaces` endpoints already existed.
289
+
197
290
  ## Migration from `@voxline/node@0.1.0`
198
291
 
199
292
  `@voxline/node` was a pre-launch internal name. This package replaces it under the `@craftedxp` org. API surface is unchanged except for the Phase 12 additions (`context` / `metadata` / `contactId` on `callTokens.mint`).
package/dist/index.d.mts CHANGED
@@ -31,6 +31,16 @@ type TtsProvider = 'pockettts' | 'cartesia' | 'fish-audio' | 'gemini' | 'kokoro'
31
31
  type SttProvider = 'deepgram';
32
32
  type LlmProvider = 'gemini' | 'openai' | 'anthropic';
33
33
  type EndpointingMode = 'smart' | 'simple';
34
+ /**
35
+ * Agent kind. Set at creation and immutable thereafter — changing what an
36
+ * agent does means creating a new one. Gates which routes accept the agent:
37
+ * - `assistant` — 1:1 voice + text chat + learning mode (LLM + STT + TTS)
38
+ * - `room` — hosts LiveKit rooms; per-speaker transcription + analysis
39
+ * - `transcribe` — 1:1 dictation, STT-only (the agent never speaks)
40
+ *
41
+ * Replaces the legacy `canHostRooms` / `transcribeOnly` boolean flags.
42
+ */
43
+ type AgentType = 'assistant' | 'room' | 'transcribe';
34
44
  interface AgentVoice {
35
45
  provider: TtsProvider;
36
46
  voiceId?: string;
@@ -109,6 +119,8 @@ interface AgentRecording {
109
119
  interface Agent {
110
120
  agentId: string;
111
121
  orgId: string;
122
+ /** Agent kind — see {@link AgentType}. Immutable after creation. */
123
+ type: AgentType;
112
124
  name: string;
113
125
  systemPrompt: string;
114
126
  /**
@@ -119,6 +131,8 @@ interface Agent {
119
131
  * caller speaks first.
120
132
  */
121
133
  agentSpeaksFirst?: boolean;
134
+ /** Personal assistant (`assistant` agents only) — the learning tools are live on every `ct_`-token call, not just `mode=learning`. */
135
+ isPersonal?: boolean;
122
136
  voice: AgentVoice;
123
137
  transcriber: AgentTranscriber;
124
138
  model: AgentModel;
@@ -151,19 +165,22 @@ interface Agent {
151
165
  * right gateway.
152
166
  */
153
167
  transport?: 'ws' | 'webrtc';
154
- /** Whether this agent may host multi-party video rooms. */
155
- canHostRooms?: boolean;
156
- /** Room operating mode (`'notes-only'` today). */
168
+ /** Room operating mode (`'notes-only'` today). Only set on `type: 'room'` agents. */
157
169
  roomMode?: 'notes-only';
158
- /** Transcribe-only mode — the agent listens but never speaks. */
159
- transcribeOnly?: boolean;
160
170
  createdAt: number;
161
171
  updatedAt: number;
162
172
  }
163
173
  interface AgentCreateInput {
174
+ /**
175
+ * Agent kind — see {@link AgentType}. Required and immutable: it cannot be
176
+ * changed via {@link AgentUpdateInput} (it is omitted from that type).
177
+ */
178
+ type: AgentType;
164
179
  name: string;
165
180
  systemPrompt: string;
166
181
  agentSpeaksFirst?: boolean;
182
+ /** Personal assistant (`assistant` agents only) — the learning tools are live on every `ct_`-token call, not just `mode=learning`. */
183
+ isPersonal?: boolean;
167
184
  voice?: AgentVoice;
168
185
  transcriber?: AgentTranscriber;
169
186
  model?: AgentModel;
@@ -185,26 +202,18 @@ interface AgentCreateInput {
185
202
  */
186
203
  avatarUrl?: string;
187
204
  /**
188
- * Let this agent host multi-party video rooms. Off by default. Required
189
- * (`true`) before `client.rooms.create({ agentId })` will accept the agent.
190
- */
191
- canHostRooms?: boolean;
192
- /**
193
- * Room operating mode. Today only `'notes-only'` exists — the agent listens
194
- * and takes structured notes without speaking. A literal union so future
195
- * modes can be added without breaking the wire.
205
+ * Room operating mode. Only valid on `type: 'room'` agents. Today only
206
+ * `'notes-only'` exists the agent listens and takes structured notes
207
+ * without speaking. A literal union so future modes can be added without
208
+ * breaking the wire.
196
209
  */
197
210
  roomMode?: 'notes-only';
198
- /**
199
- * Transcribe-only mode. When `true`, the agent listens but never speaks: no
200
- * TTS/LLM, no greeting, idle nudges suppressed, user turns are not routed
201
- * through the LLM — an STT-only loop that streams `transcript` data-messages
202
- * back to the caller. `voice` stays required by the schema (defaults apply)
203
- * but is never read at runtime.
204
- */
205
- transcribeOnly?: boolean;
206
211
  }
207
- type AgentUpdateInput = Partial<AgentCreateInput>;
212
+ /**
213
+ * Patch shape for `agents.update`. `type` is immutable, so it is omitted
214
+ * here — to change an agent's kind, create a new agent.
215
+ */
216
+ type AgentUpdateInput = Partial<Omit<AgentCreateInput, 'type'>>;
208
217
  /**
209
218
  * Trimmed agent shape returned by the consumer catalog
210
219
  * (`GET /v1/orgs/:orgId/agents`). Operator-only fields like
@@ -390,9 +399,9 @@ interface CallTokenMintInput {
390
399
  initiatedBy?: 'user' | 'agent';
391
400
  /**
392
401
  * Session channel selector. `voice` (default) routes to WS/WebRTC audio;
393
- * `text` routes to HTTP+SSE chat via the `chats` resource. Rejected at
394
- * mint when the agent has `transcribeOnly: true` or when `mode: 'learning'`
395
- * is supplied.
402
+ * `text` routes to HTTP+SSE chat via the `chats` resource. `text` requires
403
+ * a `type: 'assistant'` agent; non-assistant agents are rejected at mint
404
+ * (`wrong_agent_type`), as is `mode: 'learning'` on a non-assistant agent.
396
405
  */
397
406
  channel?: 'voice' | 'text';
398
407
  /**
@@ -437,7 +446,7 @@ interface CallTokenSummary {
437
446
  revoked: boolean;
438
447
  allowedOrigins?: string[];
439
448
  }
440
- type PlatformEventName = 'call.started' | 'call.ended' | 'transcript.updated' | 'call.summary.ready' | 'tool.call.requested' | 'tool.call.completed' | 'tool.call.failed' | 'credits.low';
449
+ type PlatformEventName = 'call.started' | 'call.ended' | 'transcript.updated' | 'call.summary.ready' | 'tool.call.requested' | 'tool.call.completed' | 'tool.call.failed' | 'credits.low' | 'speech.ready' | 'speech.failed';
441
450
  interface WebhookConfig {
442
451
  webhookId: string;
443
452
  orgId: string;
@@ -491,6 +500,17 @@ interface CreateRoomInput {
491
500
  agentId: string;
492
501
  /** 1..240 — enforced by the server. */
493
502
  durationMin: number;
503
+ /**
504
+ * Document references forwarded to the room analyzer. Each `docId` is an
505
+ * analysis document (`adoc_…`) uploaded via `POST /v1/analysis-docs` (NOT a
506
+ * knowledge-base file), tagged with an optional semantic role (e.g. `'jd'`,
507
+ * `'cv'`); the worker loads the full text and injects it into the analyzer.
508
+ * Omit when the room agent uses its default analysis behaviour.
509
+ */
510
+ analysisContext?: Array<{
511
+ docId: string;
512
+ role?: string;
513
+ }>;
494
514
  }
495
515
  interface CreateRoomResponse {
496
516
  roomId: string;
@@ -553,6 +573,24 @@ interface ListUtterancesResponse {
553
573
  utterances: UtteranceWire[];
554
574
  nextCursor: string | null;
555
575
  }
576
+ interface AnalysisWire {
577
+ analysisId: string;
578
+ participantId: string;
579
+ label: string;
580
+ score?: number;
581
+ note?: string;
582
+ createdAt: string;
583
+ /**
584
+ * Which producer emitted this result: `'summary'` | `'rated_dimensions'` |
585
+ * `'suggested_questions'`. Set by the worker on every result it produces;
586
+ * absent only on legacy analysis entries written before producers existed.
587
+ */
588
+ producer?: string;
589
+ }
590
+ interface ListAnalysisResponse {
591
+ analysis: AnalysisWire[];
592
+ nextCursor: string | null;
593
+ }
556
594
  /** Returned by host-action endpoints (`/end` and friends) — 202 + eventId so
557
595
  * callers can correlate the async system-message broadcast that follows. */
558
596
  interface RoomEventAck {
@@ -589,6 +627,105 @@ type ChatEvent = {
589
627
  code: string;
590
628
  message: string;
591
629
  };
630
+ type SpaceKind = 'audio' | 'video';
631
+ type RecordingMode = 'off' | 'host-source' | 'composite';
632
+ interface RecordingConfig {
633
+ mode: RecordingMode;
634
+ maxMinutesPerSession?: number;
635
+ audioOnly?: boolean;
636
+ }
637
+ /** The redacted space shape the server returns (`toSpaceView`). */
638
+ interface SpaceView {
639
+ spaceId: string;
640
+ agentId: string;
641
+ /** Stable human-friendly join code, e.g. `abc-defg-hij`. */
642
+ code: string;
643
+ kind: SpaceKind;
644
+ notesEnabled: boolean;
645
+ lobbyEnabled: boolean;
646
+ recording: RecordingConfig;
647
+ active: boolean;
648
+ currentSessionId: string | null;
649
+ sessionCount: number;
650
+ createdAt: string;
651
+ updatedAt: string;
652
+ }
653
+ interface CreateSpaceInput {
654
+ agentId: string;
655
+ /** Defaults to `video` server-side. */
656
+ kind?: SpaceKind;
657
+ /** Defaults to `true` server-side. */
658
+ notesEnabled?: boolean;
659
+ /** Defaults to `false` server-side. */
660
+ lobbyEnabled?: boolean;
661
+ recording?: RecordingConfig;
662
+ }
663
+ /** At least one field is required — the server rejects an empty patch. */
664
+ interface SpacePatch {
665
+ notesEnabled?: boolean;
666
+ lobbyEnabled?: boolean;
667
+ active?: boolean;
668
+ recording?: RecordingConfig;
669
+ }
670
+ interface ListSpacesResponse {
671
+ data: SpaceView[];
672
+ }
673
+ interface SpeechSynthesizeInput {
674
+ agentId: string;
675
+ text?: string;
676
+ context?: Record<string, unknown>;
677
+ instructions?: string;
678
+ format?: 'mp3' | 'wav' | 'ogg';
679
+ sampleRate?: 16000 | 24000 | 48000;
680
+ idempotencyKey?: string;
681
+ userTags?: string[];
682
+ ttlSeconds?: number;
683
+ metadata?: Record<string, string>;
684
+ }
685
+ interface SpeechAsset {
686
+ id: string;
687
+ status: 'ready';
688
+ url: string;
689
+ expiresAt: string;
690
+ durationMs: number;
691
+ bytes: number;
692
+ format: 'mp3' | 'wav' | 'ogg';
693
+ sampleRate: number;
694
+ text: string;
695
+ agentId: string;
696
+ idempotencyKey?: string;
697
+ metadata?: Record<string, string>;
698
+ createdAt: string;
699
+ }
700
+ interface SpeechJob {
701
+ id: string;
702
+ status: 'queued' | 'processing' | 'failed';
703
+ error?: {
704
+ code: string;
705
+ message: string;
706
+ };
707
+ idempotencyKey?: string;
708
+ metadata?: Record<string, string>;
709
+ createdAt: string;
710
+ }
711
+ interface SpeechListInput {
712
+ idempotencyKeyPrefix?: string;
713
+ status?: 'queued' | 'processing' | 'ready' | 'failed';
714
+ limit?: number;
715
+ cursor?: string;
716
+ }
717
+ interface SpeechReadyEvent {
718
+ event: 'speech.ready';
719
+ timestamp: string;
720
+ orgId: string;
721
+ data: SpeechAsset;
722
+ }
723
+ interface SpeechFailedEvent {
724
+ event: 'speech.failed';
725
+ timestamp: string;
726
+ orgId: string;
727
+ data: SpeechJob;
728
+ }
592
729
 
593
730
  declare const createMeResource: (http: HttpClient) => {
594
731
  get: () => Promise<MeResponse>;
@@ -730,10 +867,38 @@ declare const createRoomsResource: (http: HttpClient) => {
730
867
  list: (filters?: RoomListFilters) => Promise<ListRoomsResponse>;
731
868
  get: (roomId: string) => Promise<RoomDoc>;
732
869
  transcript: (roomId: string, opts?: RoomTranscriptOptions) => Promise<ListUtterancesResponse>;
870
+ analysis: (roomId: string, opts?: RoomTranscriptOptions) => Promise<ListAnalysisResponse>;
733
871
  end: (roomId: string) => Promise<RoomEventAck>;
734
872
  };
735
873
  type RoomsResource = ReturnType<typeof createRoomsResource>;
736
874
 
875
+ type JoinUrlStyle = 'query' | 'path';
876
+ interface BuildJoinUrlOptions {
877
+ /** Required — the developer's own page that renders <VoiceRoom/>. Absolute URL. */
878
+ baseUrl: string;
879
+ /** 'query' (default) → ?code=… · 'path' → /… */
880
+ style?: JoinUrlStyle;
881
+ }
882
+ /**
883
+ * Build a participant join URL on the DEVELOPER's domain from a space (or a
884
+ * raw code). White-label: the returned URL never points at a voissia origin —
885
+ * `baseUrl` is required and supplied by the caller.
886
+ *
887
+ * The default `query` style appends `?code=<code>`, matching how
888
+ * `<VoiceRoom/>` (and the example app) read the code from the URL.
889
+ */
890
+ declare const buildJoinUrl: (spaceOrCode: SpaceView | string, opts: BuildJoinUrlOptions) => string;
891
+
892
+ declare const createSpacesResource: (http: HttpClient) => {
893
+ create: (input: CreateSpaceInput) => Promise<SpaceView>;
894
+ get: (spaceId: string) => Promise<SpaceView>;
895
+ list: () => Promise<ListSpacesResponse>;
896
+ update: (spaceId: string, patch: SpacePatch) => Promise<SpaceView>;
897
+ delete: (spaceId: string) => Promise<void>;
898
+ joinUrl: (spaceOrCode: SpaceView | string, opts: BuildJoinUrlOptions) => string;
899
+ };
900
+ type SpacesResource = ReturnType<typeof createSpacesResource>;
901
+
737
902
  interface StartChatInput {
738
903
  agentId: string;
739
904
  text?: string;
@@ -759,6 +924,32 @@ declare const createChatsResource: (http: HttpClient, callToken: string) => {
759
924
  };
760
925
  type ChatsResource = ReturnType<typeof createChatsResource>;
761
926
 
927
+ declare const createSpeechResource: (http: HttpClient) => {
928
+ /**
929
+ * Synchronous. Resolves with the ready asset. Throws PlatformError
930
+ * code 'accepted' (status 202, `body` = SpeechJob) when the server hands
931
+ * the job to the queue instead — poll `get(job.id)` or wait for the
932
+ * `speech.ready` webhook.
933
+ */
934
+ synthesize: (input: SpeechSynthesizeInput) => Promise<SpeechAsset>;
935
+ /**
936
+ * Asynchronous. Normally returns a queued/processing SpeechJob —
937
+ * completion arrives via the `speech.ready` / `speech.failed` webhook or
938
+ * a later `get(job.id)`. Exception: when `idempotencyKey` matches an
939
+ * existing *ready* asset, the server short-circuits the queue hop and
940
+ * responds 200 with that SpeechAsset directly instead of 202.
941
+ */
942
+ enqueue: (input: SpeechSynthesizeInput) => Promise<SpeechJob | SpeechAsset>;
943
+ get: (id: string) => Promise<SpeechAsset | SpeechJob>;
944
+ list: (input?: SpeechListInput) => Promise<{
945
+ items: Array<SpeechAsset | SpeechJob>;
946
+ cursor?: string;
947
+ }>;
948
+ /** Idempotent. Deleting a ready asset invalidates its URL immediately. */
949
+ delete: (id: string) => Promise<void>;
950
+ };
951
+ type SpeechResource = ReturnType<typeof createSpeechResource>;
952
+
762
953
  interface PlatformClientOptions {
763
954
  apiKey: string;
764
955
  baseUrl?: string;
@@ -777,6 +968,8 @@ declare class PlatformClient {
777
968
  readonly webhooks: WebhooksResource;
778
969
  readonly orgs: OrgsResource;
779
970
  readonly rooms: RoomsResource;
971
+ readonly spaces: SpacesResource;
972
+ readonly speech: SpeechResource;
780
973
  private readonly _http;
781
974
  constructor(options: PlatformClientOptions);
782
975
  /**
@@ -791,7 +984,7 @@ declare class PlatformClient {
791
984
  chatsFor(callToken: string): ChatsResource;
792
985
  }
793
986
 
794
- type ApiErrorCode = 'unauthorized' | 'forbidden' | 'not_found' | 'bad_request' | 'conflict' | 'rate_limited' | 'payment_required' | 'internal_error' | 'unknown';
987
+ type ApiErrorCode = 'unauthorized' | 'forbidden' | 'not_found' | 'bad_request' | 'conflict' | 'rate_limited' | 'payment_required' | 'internal_error' | 'accepted' | 'service_unavailable' | 'unknown';
795
988
  declare class PlatformError extends Error {
796
989
  readonly code: ApiErrorCode;
797
990
  readonly status: number;
@@ -811,4 +1004,4 @@ declare class PlatformError extends Error {
811
1004
 
812
1005
  declare const verifyWebhookSignature: (rawBody: Buffer | string, signatureHeader: string, secret: string) => boolean;
813
1006
 
814
- export { type Agent, type AgentCreateInput, type AgentEndpointing, type AgentHttpTool, type AgentModel, type AgentRecording, type AgentTool, type AgentTranscriber, type AgentUpdateInput, type AgentVoice, type AgentWebhooksResource, type AgentsResource, type ApiErrorCode, type CallListFilters, type CallRecord, type CallRecordingUrlResponse, type CallStatus, type CallSummary, type CallTokenMintInput, type CallTokenMintResult, type CallTokenSummary, type CallTokensResource, type CallsResource, type CatalogAgent, type CatalogListInput, type Chat, type ChatEvent, type ChatsResource, type CostBreakdown, type CreateRoomInput, type CreateRoomResponse, type CreditsResource, type EndReason, type EndpointingMode, type GuestRole, type KnowledgeBase, type KnowledgeBaseFile, type KnowledgeBasesResource, type LedgerEntry, type ListRoomsResponse, type ListUtterancesResponse, type LlmProvider, type MeResource, type MeResponse, type OrgsResource, PlatformClient, type PlatformClientOptions, PlatformError, type PlatformEventName, type RecordingMeta, type RoomDoc, type RoomEndReason, type RoomEventAck, type RoomListFilters, type RoomMetricsWire, type RoomStatus, type RoomTranscriptOptions, type RoomsResource, type StartChatInput, type SttProvider, type TranscriptTurn, type TtsProvider, type UtteranceWire, type WebhookConfig, type WebhookCreateInput, type WebhookDelivery, type WebhookUpdateInput, type WebhooksResource, type WorkerStatus, verifyWebhookSignature };
1007
+ export { type Agent, type AgentCreateInput, type AgentEndpointing, type AgentHttpTool, type AgentModel, type AgentRecording, type AgentTool, type AgentTranscriber, type AgentType, type AgentUpdateInput, type AgentVoice, type AgentWebhooksResource, type AgentsResource, type AnalysisWire, type ApiErrorCode, type BuildJoinUrlOptions, type CallListFilters, type CallRecord, type CallRecordingUrlResponse, type CallStatus, type CallSummary, type CallTokenMintInput, type CallTokenMintResult, type CallTokenSummary, type CallTokensResource, type CallsResource, type CatalogAgent, type CatalogListInput, type Chat, type ChatEvent, type ChatsResource, type CostBreakdown, type CreateRoomInput, type CreateRoomResponse, type CreateSpaceInput, type CreditsResource, type EndReason, type EndpointingMode, type GuestRole, type JoinUrlStyle, type KnowledgeBase, type KnowledgeBaseFile, type KnowledgeBasesResource, type LedgerEntry, type ListAnalysisResponse, type ListRoomsResponse, type ListSpacesResponse, type ListUtterancesResponse, type LlmProvider, type MeResource, type MeResponse, type OrgsResource, PlatformClient, type PlatformClientOptions, PlatformError, type PlatformEventName, type RecordingConfig, type RecordingMeta, type RecordingMode, type RoomDoc, type RoomEndReason, type RoomEventAck, type RoomListFilters, type RoomMetricsWire, type RoomStatus, type RoomTranscriptOptions, type RoomsResource, type SpaceKind, type SpacePatch, type SpaceView, type SpacesResource, type SpeechAsset, type SpeechFailedEvent, type SpeechJob, type SpeechListInput, type SpeechReadyEvent, type SpeechResource, type SpeechSynthesizeInput, type StartChatInput, type SttProvider, type TranscriptTurn, type TtsProvider, type UtteranceWire, type WebhookConfig, type WebhookCreateInput, type WebhookDelivery, type WebhookUpdateInput, type WebhooksResource, type WorkerStatus, buildJoinUrl, verifyWebhookSignature };