realtime-avatar 0.27.5 → 0.28.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
@@ -198,6 +198,51 @@ Two facts follow from that picture and drive everything else:
198
198
 
199
199
  ---
200
200
 
201
+ ## Custom voice (webhook)
202
+
203
+ Speak a call in your own voice. Each sentence she is about to say is POSTed, signed, to an
204
+ endpoint your server hosts, and the audio it streams back is what she says, lip-synced, in
205
+ `avatar` and `voice` mode alike:
206
+
207
+ ```ts
208
+ const call = await rta.startCall({
209
+ avatarId,
210
+ voiceWebhook: { url: "https://api.example.com/voice", secret: process.env.VOICE_WEBHOOK_SECRET!, voiceId: "narrator" },
211
+ });
212
+ ```
213
+
214
+ ```ts
215
+ // POST https://api.example.com/voice
216
+ import { verifyVoiceWebhook } from "realtime-avatar";
217
+
218
+ const raw = Buffer.from(await request.arrayBuffer()); // the RAW bytes, as for transcripts
219
+ const { text, voice_id, output } = await verifyVoiceWebhook(raw, request.headers, process.env.VOICE_WEBHOOK_SECRET!);
220
+ return new Response(await myTts(text, voice_id), { headers: { "content-type": "audio/pcm;rate=24000" } });
221
+ ```
222
+
223
+ - `voiceWebhook` is `{ url, secret, voiceId?, language?, sampleRate?, timeoutMs? }`, derived from
224
+ the platform's `voice_webhook`. It carries a secret, so only the server entries send it; it
225
+ replaces `voice`, and a mint with both is refused with `422`. The URL must be https.
226
+ - Reply `200` with audio, streamed as soon as you have it. `timeoutMs` (default 5000) bounds the
227
+ first audio byte of each attempt and every later gap between chunks. `audio/pcm` (alias
228
+ `audio/raw`) is raw signed 16-bit little-endian mono at `output.sample_rate` (default 24000), or
229
+ name the rate with `audio/pcm;rate=…`; no other raw type is accepted. OpenAI's
230
+ `response_format: "pcm"` is exactly 24 kHz `audio/pcm`. A 2xx with no body (a `204`,
231
+ `Content-Length: 0`, or an empty first chunk) is `voice_webhook_empty_audio`.
232
+ - `verifyVoiceWebhook` throws `RealtimeAvatarWebhookError` with a `code` (`missing_signature`,
233
+ `bad_signature`, `stale_timestamp`, `invalid_body`).
234
+ - A `401` or `403` from your endpoint ends the call. A timeout, an unreachable endpoint, or a
235
+ `408`, `429` or 5xx is retried once, only before any audio has arrived, as a new POST with a new
236
+ `request_id`. Any other failure, or a retry that fails too, drops the rest of that reply: the
237
+ sentences after it are not POSTed, and the next reply tries again. Repeated failures end the
238
+ call with a fatal error carrying the last failure's code.
239
+ - In the client, `onVoiceError` on `useRealtimeSession` and `AvatarCall` fires with
240
+ `{ code, message, status?, fatal, requestId? }`, and `voiceError` holds the last one of this
241
+ call. `fatal` means the call is ending; `onEnded` follows with `failed`.
242
+
243
+ Working endpoints: `apps/quickstart/nextjs-app-router/app/api/voice/route.ts` and `POST /api/voice`
244
+ in `apps/quickstart/python-fastapi/main.py`.
245
+
201
246
  ## Input source on room messages
202
247
 
203
248
  On React and React Native, `session.sendTurn(text)` automatically observes text.
@@ -249,7 +294,7 @@ against its deployed OpenAPI, then run `npm run check`.** Do not hand-edit the g
249
294
 
250
295
  ```ts
251
296
  // calls
252
- rta.startCall({ avatarId, mode?, instructions?, context?, maxSeconds?, video?, recording?, connectionHistory?, contentPolicy?, transcript?, metadata?, llm? })
297
+ rta.startCall({ avatarId, mode?, instructions?, context?, maxSeconds?, video?, recording?, connectionHistory?, contentPolicy?, transcript?, metadata?, llm?, voiceWebhook? })
253
298
  rta.endCall(sessionId, { reason? }) // free an abandoned call's slot; idempotent, never throws
254
299
  rta.leaveQueue(queueTicketId, { reason? }) // give up a queued call's place in line; idempotent, never throws
255
300
 
@@ -287,6 +332,7 @@ rta.iterateSessions({ from, to }) // the same, paging handled
287
332
 
288
333
  // webhooks
289
334
  verifyTranscript(rawBytes, headers, secret)
335
+ verifyVoiceWebhook(rawBytes, headers, secret) // one sentence to speak, typed; see "Custom voice (webhook)"
290
336
  ```
291
337
 
292
338
  ### Session page validation
@@ -342,7 +388,7 @@ Server — these hold your API key:
342
388
 
343
389
  | Import | What it is |
344
390
  | --- | --- |
345
- | `realtime-avatar` | `RealtimeAvatar`, `isQueued`, `verifyTranscript`, the two error classes |
391
+ | `realtime-avatar` | `RealtimeAvatar`, `isQueued`, `verifyTranscript`, `verifyVoiceWebhook`, the three error classes |
346
392
  | `realtime-avatar/server` | The same client with no route adapters — 18.8 KB |
347
393
  | `realtime-avatar/nextjs` | `createRealtimeAvatarRoute` — App Router `{ GET, POST }` |
348
394
  | `realtime-avatar/hono` | `realtimeAvatarHono` — Hono, Workers, Bun, Deno |
@@ -1,4 +1,4 @@
1
- import { sessionModeSchema, liveKitSessionReleaseReasonSchema, RealtimeAvatar, ROUTE_TIMEOUT_MS, isQueued, RealtimeAvatarHttpError, RealtimeAvatarError } from './chunk-6E3SZH35.js';
1
+ import { sessionModeSchema, liveKitSessionReleaseReasonSchema, RealtimeAvatar, ROUTE_TIMEOUT_MS, isQueued, RealtimeAvatarHttpError, RealtimeAvatarError } from './chunk-V7A4NRKC.js';
2
2
  import { z } from 'zod';
3
3
 
4
4
  // ../http-client/src/generated/error-semantics.ts
@@ -34,6 +34,7 @@ var ERROR_SEMANTICS = {
34
34
  "service_warming": { statuses: [503], message: "Realtime Avatar is warming up. Try again in a moment.", retryable: true },
35
35
  "avatar_not_ready": { statuses: [409], message: "This avatar is still being built \u2014 it is usually ready within a minute. Try again then.", retryable: true },
36
36
  "clip_library_not_ready": { statuses: [409], message: "This avatar's motion clips are still rendering. Try again in a minute.", retryable: true },
37
+ "avatar_not_callable": { statuses: [409], message: "This avatar only hosts a live stream and cannot take calls. Choose another avatar.", retryable: false },
37
38
  "recording_unsupported": { statuses: [501], message: "Session recording is not enabled for this deployment.", retryable: false },
38
39
  "recording_requires_new_room": { statuses: [422], message: "Recording requires a new session room. Start a fresh session to record it.", retryable: false },
39
40
  "recording_unavailable": { statuses: [503], message: "Session recording is temporarily unavailable. Try again in a moment.", retryable: true }
@@ -8,6 +8,14 @@ var RealtimeAvatarError = class extends Error {
8
8
  this.name = "RealtimeAvatarError";
9
9
  }
10
10
  };
11
+ var RealtimeAvatarWebhookError = class extends RealtimeAvatarError {
12
+ code;
13
+ constructor(code, message, options) {
14
+ super(message, options);
15
+ this.name = "RealtimeAvatarWebhookError";
16
+ this.code = code;
17
+ }
18
+ };
11
19
  function isRequestId(value) {
12
20
  return typeof value === "string" && /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/i.test(value);
13
21
  }
@@ -336,6 +344,20 @@ function transcriptionToWire(input) {
336
344
  }
337
345
  var schema03 = z.enum(["minor-sexual-content-v1", "safe-content-v1"]);
338
346
  var contentPolicySchema = schema03;
347
+ var schema04 = z.literal("voice_error");
348
+ var schema111 = z.enum(["voice_webhook_url_not_allowed", "voice_webhook_unauthorized", "voice_webhook_unreachable", "voice_webhook_timeout", "voice_webhook_http_error", "voice_webhook_unsupported_audio", "voice_webhook_empty_audio"]);
349
+ var schema28 = z.string();
350
+ var schema33 = z.int().min(-9007199254740991).max(9007199254740991);
351
+ var schema43 = z.boolean();
352
+ var schema52 = z.object({
353
+ "kind": schema04,
354
+ "code": schema111,
355
+ "message": schema28,
356
+ "status": schema33.optional(),
357
+ "fatal": schema43,
358
+ "request_id": schema28.optional()
359
+ });
360
+ var voiceErrorFrameSchema = schema52;
339
361
 
340
362
  // ../client/src/wire.ts
341
363
  var DEFAULT_AVATAR_ID = "maria";
@@ -627,13 +649,15 @@ var clipAckFrameSchema = z.object({
627
649
  accepted: z.boolean(),
628
650
  reason: z.string().max(64)
629
651
  }).strip();
652
+ var voiceErrorFrameSchema2 = voiceErrorFrameSchema.extend({ code: z.string().min(1) });
630
653
  z.discriminatedUnion("kind", [
631
654
  sessionClockFrameSchema,
632
655
  endingFrameSchema,
633
656
  closingTurnDoneFrameSchema,
634
657
  endedFrameSchema,
635
658
  behaviorStateFrameSchema,
636
- clipAckFrameSchema
659
+ clipAckFrameSchema,
660
+ voiceErrorFrameSchema2
637
661
  ]);
638
662
  var liveKitCapacitySnapshotSchema = z.object({
639
663
  // Placement identity + per-worker session ceiling. These are always present on the
@@ -672,91 +696,157 @@ var liveKitSessionReleaseReasonSchema = z.enum([
672
696
  "manual",
673
697
  "idle_timeout"
674
698
  ]);
675
- var schema04 = z.string().min(8).max(80);
676
- var schema111 = z.enum(["eou", "llm", "tts", "decision", "hold", "e2e"]);
677
- var schema28 = z.literal("interrupt_stop");
678
- var schema33 = z.union([schema111, schema28]);
679
- var schema43 = z.int().max(9007199254740991).gt(0);
680
- var schema52 = z.number().min(0);
699
+ var schema05 = z.url().regex(new RegExp("^https:\\/\\/")).max(500);
700
+ var schema112 = z.string().min(16).max(200);
701
+ var schema29 = z.string().min(1).max(200);
702
+ var schema34 = z.string().min(2).max(35);
703
+ var schema44 = z.literal([8e3, 16e3, 22050, 24e3, 44100, 48e3]);
704
+ var schema53 = z.int().min(1e3).max(15e3);
681
705
  var schema62 = z.strictObject({
682
- "count": schema43,
683
- "max": schema52,
684
- "p50": schema52,
685
- "p90": schema52
706
+ "url": schema05,
707
+ "secret": schema112,
708
+ "voice_id": schema29.optional(),
709
+ "language": schema34.optional(),
710
+ "sample_rate": schema44.optional(),
711
+ "timeout_ms": schema53.optional()
712
+ });
713
+ var schema72 = z.literal("voice.synthesize");
714
+ var schema82 = z.literal(1);
715
+ var schema92 = z.string().min(1).max(200);
716
+ var schema102 = z.string();
717
+ var schema113 = z.string().min(1).max(5e3);
718
+ var schema122 = z.string();
719
+ var schema132 = z.null();
720
+ var schema142 = z.union([schema122, schema132]);
721
+ var schema152 = z.string();
722
+ var schema162 = z.union([schema152, schema132]);
723
+ var schema172 = z.literal("pcm_s16le");
724
+ var schema182 = z.literal([8e3, 16e3, 22050, 24e3, 44100, 48e3]);
725
+ var schema192 = z.object({
726
+ "encoding": schema172,
727
+ "sample_rate": schema182,
728
+ "channels": schema82
729
+ });
730
+ var schema202 = z.string().min(1).max(64);
731
+ var schema212 = z.string().max(200);
732
+ var schema222 = z.record(schema202, schema212).refine((value) => Object.keys(value).length <= 16, { message: "Too many keys: at most 16" });
733
+ var schema232 = z.object({
734
+ "type": schema72,
735
+ "version": schema82,
736
+ "request_id": schema92,
737
+ "session_id": schema102,
738
+ "text": schema113,
739
+ "voice_id": schema142,
740
+ "language": schema162,
741
+ "output": schema192,
742
+ "client_metadata": schema222
743
+ });
744
+ var voiceWebhookWireSchema = schema62;
745
+ var voiceWebhookOptionsSchema = z.strictObject({
746
+ url: voiceWebhookWireSchema.shape.url,
747
+ secret: voiceWebhookWireSchema.shape.secret,
748
+ voiceId: voiceWebhookWireSchema.shape.voice_id,
749
+ language: voiceWebhookWireSchema.shape.language,
750
+ sampleRate: voiceWebhookWireSchema.shape.sample_rate,
751
+ timeoutMs: voiceWebhookWireSchema.shape.timeout_ms
752
+ });
753
+ function voiceWebhookToWire(input) {
754
+ const options = voiceWebhookOptionsSchema.parse(input);
755
+ return {
756
+ url: options.url,
757
+ secret: options.secret,
758
+ ...options.voiceId !== void 0 ? { voice_id: options.voiceId } : {},
759
+ ...options.language !== void 0 ? { language: options.language } : {},
760
+ ...options.sampleRate !== void 0 ? { sample_rate: options.sampleRate } : {},
761
+ ...options.timeoutMs !== void 0 ? { timeout_ms: options.timeoutMs } : {}
762
+ };
763
+ }
764
+ var voiceWebhookRequestSchema = schema232;
765
+ var schema06 = z.string().min(8).max(80);
766
+ var schema114 = z.enum(["eou", "llm", "tts", "decision", "hold", "e2e"]);
767
+ var schema210 = z.literal("interrupt_stop");
768
+ var schema35 = z.union([schema114, schema210]);
769
+ var schema45 = z.int().max(9007199254740991).gt(0);
770
+ var schema54 = z.number().min(0);
771
+ var schema63 = z.strictObject({
772
+ "count": schema45,
773
+ "max": schema54,
774
+ "p50": schema54,
775
+ "p90": schema54
686
776
  });
687
- var schema72 = z.partialRecord(schema33, schema62);
688
- var schema82 = z.literal("available");
689
- var schema92 = z.literal("dialogue");
690
- var schema102 = z.string().regex(new RegExp("^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d))|(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?)$"));
691
- var schema112 = z.null();
692
- var schema122 = z.union([schema102, schema112]);
693
- var schema132 = z.int().min(0).max(9007199254740991);
694
- var schema142 = z.strictObject({
695
- "first_at": schema122,
696
- "last_at": schema122,
697
- "lines": schema132
777
+ var schema73 = z.partialRecord(schema35, schema63);
778
+ var schema83 = z.literal("available");
779
+ var schema93 = z.literal("dialogue");
780
+ var schema103 = z.string().regex(new RegExp("^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d))|(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?)$"));
781
+ var schema115 = z.null();
782
+ var schema123 = z.union([schema103, schema115]);
783
+ var schema133 = z.int().min(0).max(9007199254740991);
784
+ var schema143 = z.strictObject({
785
+ "first_at": schema123,
786
+ "last_at": schema123,
787
+ "lines": schema133
698
788
  });
699
- var schema152 = z.strictObject({
700
- "latency_ms": schema72,
701
- "status": schema82,
702
- "sourceRole": schema92,
703
- "coverage": schema142
789
+ var schema153 = z.strictObject({
790
+ "latency_ms": schema73,
791
+ "status": schema83,
792
+ "sourceRole": schema93,
793
+ "coverage": schema143
704
794
  });
705
- var schema162 = z.literal("unavailable");
706
- var schema172 = z.enum(["not_closed", "unconfigured", "missing", "invalid", "oversized", "unscorable", "no_measured_latency", "timeout", "aborted", "storage_unavailable"]);
707
- var schema182 = z.strictObject({
708
- "status": schema162,
709
- "reason": schema172
795
+ var schema163 = z.literal("unavailable");
796
+ var schema173 = z.enum(["not_closed", "unconfigured", "missing", "invalid", "oversized", "unscorable", "no_measured_latency", "timeout", "aborted", "storage_unavailable"]);
797
+ var schema183 = z.strictObject({
798
+ "status": schema163,
799
+ "reason": schema173
710
800
  });
711
- var schema192 = z.union([schema152, schema182]);
712
- var schema202 = z.string().min(1).max(200);
713
- var schema212 = z.union([schema202, schema112]);
714
- var schema222 = z.string().regex(new RegExp("^[0-9a-f]{40}$"));
715
- var schema232 = z.union([schema222, schema112]);
801
+ var schema193 = z.union([schema153, schema183]);
802
+ var schema203 = z.string().min(1).max(200);
803
+ var schema213 = z.union([schema203, schema115]);
804
+ var schema223 = z.string().regex(new RegExp("^[0-9a-f]{40}$"));
805
+ var schema233 = z.union([schema223, schema115]);
716
806
  var schema242 = z.literal("cloudflare-worker-version");
717
807
  var schema252 = z.literal("authenticated-worker-heartbeat");
718
- var schema262 = z.union([schema252, schema112]);
808
+ var schema262 = z.union([schema252, schema115]);
719
809
  var schema272 = z.string().min(1).max(160);
720
- var schema282 = z.union([schema272, schema112]);
721
- var schema29 = z.union([schema132, schema112]);
810
+ var schema282 = z.union([schema272, schema115]);
811
+ var schema292 = z.union([schema133, schema115]);
722
812
  var schema30 = z.iso.datetime({ offset: true }).regex(new RegExp("^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"));
723
- var schema31 = z.union([schema30, schema112]);
813
+ var schema31 = z.union([schema30, schema115]);
724
814
  var schema322 = z.strictObject({
725
815
  "deploymentSource": schema242,
726
816
  "workerSource": schema262,
727
817
  "workerId": schema282,
728
- "podStartedAtMs": schema29,
818
+ "podStartedAtMs": schema292,
729
819
  "workerObservedAt": schema31
730
820
  });
731
821
  var schema332 = z.strictObject({
732
- "deploymentId": schema212,
733
- "workerRevision": schema232,
822
+ "deploymentId": schema213,
823
+ "workerRevision": schema233,
734
824
  "provenance": schema322
735
825
  });
736
- var schema34 = z.string();
737
- var schema35 = z.union([schema34, schema112]);
826
+ var schema342 = z.string();
827
+ var schema352 = z.union([schema342, schema115]);
738
828
  var schema36 = z.enum(["reserved", "started", "released", "failed"]);
739
- var schema37 = z.union([schema52, schema112]);
829
+ var schema37 = z.union([schema54, schema115]);
740
830
  var schema38 = z.custom((value) => typeof value === "object" && value !== null && !Array.isArray(value));
741
831
  var schema39 = z.strictObject({
742
- "sessionId": schema04,
743
- "speechDiagnostics": schema192.optional(),
832
+ "sessionId": schema06,
833
+ "speechDiagnostics": schema193.optional(),
744
834
  "releaseIdentity": schema332.optional(),
745
- "avatarId": schema35,
746
- "avatarName": schema35,
835
+ "avatarId": schema352,
836
+ "avatarName": schema352,
747
837
  "status": schema36,
748
- "startedAt": schema35,
749
- "endedAt": schema35,
838
+ "startedAt": schema352,
839
+ "endedAt": schema352,
750
840
  "activeSeconds": schema37,
751
- "billedCreditMicros": schema29,
841
+ "billedCreditMicros": schema292,
752
842
  "metadata": schema38,
753
- "createdAt": schema34
843
+ "createdAt": schema342
754
844
  });
755
845
  var schema40 = z.array(schema39);
756
846
  var schema41 = z.iso.datetime({ offset: true }).regex(new RegExp("^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"));
757
847
  var schema422 = z.strictObject({
758
848
  "data": schema40,
759
- "nextCursor": schema35,
849
+ "nextCursor": schema352,
760
850
  "from": schema41,
761
851
  "to": schema41
762
852
  });
@@ -768,7 +858,7 @@ function toSessionsPage(page) {
768
858
 
769
859
  // ../http-client/src/client.ts
770
860
  var DEFAULT_BASE_URL = "https://realtimeavatar.ai/api/v1";
771
- var SDK_VERSION = "0.27.5";
861
+ var SDK_VERSION = "0.28.0";
772
862
  var RealtimeAvatar = class {
773
863
  #apiKey;
774
864
  #baseUrl;
@@ -816,6 +906,7 @@ var RealtimeAvatar = class {
816
906
  }
817
907
  if (options.maxSeconds !== void 0) body.max_session_seconds = Math.floor(options.maxSeconds);
818
908
  if (options.voice !== void 0) body.voice = options.voice;
909
+ if (options.voiceWebhook !== void 0) body.voice_webhook = voiceWebhookToWire(options.voiceWebhook);
819
910
  if (options.metadata !== void 0) body.client_metadata = options.metadata;
820
911
  if (options.recording !== void 0) body.recording = recordingModeSchema.parse(options.recording);
821
912
  if (options.connectionHistory !== void 0) body.connection_history = options.connectionHistory;
@@ -1368,13 +1459,35 @@ function isStream(body) {
1368
1459
 
1369
1460
  // ../http-client/src/webhook.ts
1370
1461
  async function verifyTranscript(rawBody, headers, secret, options = {}) {
1462
+ const text = await verifiedBody("transcript webhook", rawBody, headers, secret, options);
1463
+ return JSON.parse(text);
1464
+ }
1465
+ async function verifyVoiceWebhook(rawBody, headers, secret, options = {}) {
1466
+ const text = await verifiedBody("voice webhook", rawBody, headers, secret, options);
1467
+ let decoded;
1468
+ try {
1469
+ decoded = JSON.parse(text);
1470
+ } catch (cause) {
1471
+ throw new RealtimeAvatarWebhookError("invalid_body", "voice webhook body is not JSON", { cause });
1472
+ }
1473
+ const parsed = voiceWebhookRequestSchema.safeParse(decoded);
1474
+ if (!parsed.success) {
1475
+ throw new RealtimeAvatarWebhookError("invalid_body", "voice webhook body does not match the voice.synthesize contract", {
1476
+ cause: parsed.error
1477
+ });
1478
+ }
1479
+ return parsed.data;
1480
+ }
1481
+ async function verifiedBody(label, rawBody, headers, secret, options) {
1371
1482
  const get = (name) => headers instanceof Headers ? headers.get(name) ?? void 0 : headers[name];
1372
1483
  const signature = get("x-rta-signature");
1373
1484
  const timestamp = get("x-rta-timestamp");
1374
- if (!signature || !timestamp) throw new Error("missing x-rta-signature / x-rta-timestamp");
1485
+ if (!signature || !timestamp) {
1486
+ throw new RealtimeAvatarWebhookError("missing_signature", "missing x-rta-signature / x-rta-timestamp");
1487
+ }
1375
1488
  const skew = Math.abs(Date.now() / 1e3 - Number(timestamp));
1376
1489
  if (!Number.isFinite(skew) || skew > (options.toleranceSeconds ?? 300)) {
1377
- throw new Error("transcript webhook timestamp is outside the replay window");
1490
+ throw new RealtimeAvatarWebhookError("stale_timestamp", `${label} timestamp is outside the replay window`);
1378
1491
  }
1379
1492
  const text = typeof rawBody === "string" ? rawBody : new TextDecoder().decode(rawBody);
1380
1493
  const key = await crypto.subtle.importKey(
@@ -1386,8 +1499,10 @@ async function verifyTranscript(rawBody, headers, secret, options = {}) {
1386
1499
  );
1387
1500
  const mac = await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(`${timestamp}.${text}`));
1388
1501
  const expected = `v1=${[...new Uint8Array(mac)].map((b) => b.toString(16).padStart(2, "0")).join("")}`;
1389
- if (!timingSafeEqual(expected, signature)) throw new Error("transcript webhook signature mismatch");
1390
- return JSON.parse(text);
1502
+ if (!timingSafeEqual(expected, signature)) {
1503
+ throw new RealtimeAvatarWebhookError("bad_signature", `${label} signature mismatch`);
1504
+ }
1505
+ return text;
1391
1506
  }
1392
1507
  function timingSafeEqual(a, b) {
1393
1508
  if (a.length !== b.length) return false;
@@ -1401,4 +1516,4 @@ function isQueued(result) {
1401
1516
  return "queued" in result;
1402
1517
  }
1403
1518
 
1404
- export { ROUTE_TIMEOUT_MS, RealtimeAvatar, RealtimeAvatarError, RealtimeAvatarHttpError, clipLibraryDeclarationSchema, isQueued, listRecordingsResponseSchema, liveKitSessionReleaseReasonSchema, recordingAccessResponseSchema, recordingArtifactSchema, recordingModeSchema, sessionModeSchema, verifyTranscript };
1519
+ export { ROUTE_TIMEOUT_MS, RealtimeAvatar, RealtimeAvatarError, RealtimeAvatarHttpError, RealtimeAvatarWebhookError, clipLibraryDeclarationSchema, isQueued, listRecordingsResponseSchema, liveKitSessionReleaseReasonSchema, recordingAccessResponseSchema, recordingArtifactSchema, recordingModeSchema, sessionModeSchema, verifyTranscript, verifyVoiceWebhook };
package/dist/express.d.ts CHANGED
@@ -1,5 +1,5 @@
1
- import { P as ProxyConfig } from './types-B1IR4EaJ.js';
2
- import './types-C8X50QT9.js';
1
+ import { P as ProxyConfig } from './types-Bli1UeP0.js';
2
+ import './types-yiemDkm0.js';
3
3
  import 'zod';
4
4
 
5
5
  type Expressish = {
package/dist/express.js CHANGED
@@ -1,5 +1,5 @@
1
- import { createProxyHandler } from './chunk-IJHM44YT.js';
2
- import './chunk-6E3SZH35.js';
1
+ import { createProxyHandler } from './chunk-K3VC6BF7.js';
2
+ import './chunk-V7A4NRKC.js';
3
3
  import './chunk-MCIXU6XP.js';
4
4
 
5
5
  // ../proxy/src/express.ts
package/dist/hono.d.ts CHANGED
@@ -1,5 +1,5 @@
1
- import { P as ProxyConfig } from './types-B1IR4EaJ.js';
2
- import './types-C8X50QT9.js';
1
+ import { P as ProxyConfig } from './types-Bli1UeP0.js';
2
+ import './types-yiemDkm0.js';
3
3
  import 'zod';
4
4
 
5
5
  /**
package/dist/hono.js CHANGED
@@ -1,5 +1,5 @@
1
- import { createProxyHandler } from './chunk-IJHM44YT.js';
2
- import './chunk-6E3SZH35.js';
1
+ import { createProxyHandler } from './chunk-K3VC6BF7.js';
2
+ import './chunk-V7A4NRKC.js';
3
3
  import './chunk-MCIXU6XP.js';
4
4
 
5
5
  // ../proxy/src/hono.ts
package/dist/index.d.ts CHANGED
@@ -1,5 +1,5 @@
1
- import { a as CallPolicy, C as CallMode, S as StartCallResult, E as EndCallOptions, A as Avatar, b as AvatarUpdate, c as AvatarSourceSwap, d as ClipLibraryDeclaration, e as ClipLibraryUpdate, L as LoopRedirect, f as ClipLibrary, g as AssetKind, h as Asset, i as ListSessionsOptions, U as UsageSessionPage, j as UsageSession, k as ListRecordingsQuery, l as ListRecordingsResponse, R as RecordingArtifact, m as RecordingAccessResponse, n as CreditBalance, T as TranscriptPayload } from './types-C8X50QT9.js';
2
- export { o as AvatarClip, p as CallConnection, q as CallQueued, r as ClipDeclaration, s as ClipLibraryPlan, t as ClipSource, u as ContextMessage, v as EndCallReason, w as ExternalLlm, x as RecordingArtifactStatus, y as RecordingMode, V as VideoPolicy, z as isQueued, B as listRecordingsResponseSchema, D as recordingAccessResponseSchema, F as recordingArtifactSchema, G as recordingModeSchema } from './types-C8X50QT9.js';
1
+ import { a as CallPolicy, C as CallMode, S as StartCallResult, E as EndCallOptions, A as Avatar, b as AvatarUpdate, c as AvatarSourceSwap, d as ClipLibraryDeclaration, e as ClipLibraryUpdate, L as LoopRedirect, f as ClipLibrary, g as AssetKind, h as Asset, i as ListSessionsOptions, U as UsageSessionPage, j as UsageSession, k as ListRecordingsQuery, l as ListRecordingsResponse, R as RecordingArtifact, m as RecordingAccessResponse, n as CreditBalance, T as TranscriptPayload, V as VoiceWebhookRequest } from './types-yiemDkm0.js';
2
+ export { o as AvatarClip, p as CallConnection, q as CallQueued, r as ClipDeclaration, s as ClipLibraryPlan, t as ClipSource, u as ContextMessage, v as EndCallReason, w as ExternalLlm, x as RecordingArtifactStatus, y as RecordingMode, z as VideoPolicy, B as VoiceWebhook, D as VoiceWebhookErrorCode, F as isQueued, G as listRecordingsResponseSchema, H as recordingAccessResponseSchema, I as recordingArtifactSchema, J as recordingModeSchema } from './types-yiemDkm0.js';
3
3
  import { ConnectionHistoryResponse } from './connection-history.js';
4
4
  import { z } from 'zod';
5
5
 
@@ -308,6 +308,19 @@ declare class RealtimeAvatarError extends Error {
308
308
  cause?: unknown;
309
309
  });
310
310
  }
311
+ /** Why `verifyTranscript` or `verifyVoiceWebhook` refused a request. Answer each with a 4xx. */
312
+ type WebhookVerificationErrorCode = "missing_signature" | "bad_signature" | "stale_timestamp" | "invalid_body";
313
+ /**
314
+ * A webhook request that did not verify. `code` says why: the signature headers are absent, the
315
+ * signature does not match the raw body, the timestamp is outside the replay window, or a
316
+ * correctly signed body is not the contract.
317
+ */
318
+ declare class RealtimeAvatarWebhookError extends RealtimeAvatarError {
319
+ readonly code: WebhookVerificationErrorCode;
320
+ constructor(code: WebhookVerificationErrorCode, message: string, options?: {
321
+ cause?: unknown;
322
+ });
323
+ }
311
324
  /**
312
325
  * A non-2xx from the API.
313
326
  *
@@ -352,6 +365,10 @@ declare class RealtimeAvatarHttpError extends RealtimeAvatarError {
352
365
  get isBilling(): boolean;
353
366
  }
354
367
 
368
+ type WebhookHeaders = Headers | Record<string, string | undefined>;
369
+ type VerifyOptions = {
370
+ toleranceSeconds?: number;
371
+ };
355
372
  /**
356
373
  * Verify a transcript webhook.
357
374
  *
@@ -363,9 +380,22 @@ declare class RealtimeAvatarHttpError extends RealtimeAvatarError {
363
380
  * const transcript = await verifyTranscript(raw, request.headers, process.env.TRANSCRIPT_SECRET!);
364
381
  * ```
365
382
  */
366
- declare function verifyTranscript(rawBody: Uint8Array | string, headers: Headers | Record<string, string | undefined>, secret: string, options?: {
367
- toleranceSeconds?: number;
368
- }): Promise<TranscriptPayload>;
383
+ declare function verifyTranscript(rawBody: Uint8Array | string, headers: WebhookHeaders, secret: string, options?: VerifyOptions): Promise<TranscriptPayload>;
384
+ /**
385
+ * Verify one `voice.synthesize` request from a call minted with `voiceWebhook`, and return it
386
+ * typed. Same signature scheme and the same rule as {@link verifyTranscript}: pass the RAW bytes.
387
+ *
388
+ * Throws {@link RealtimeAvatarWebhookError}. Answer a signature or timestamp refusal with 401 and
389
+ * `invalid_body` with 400. The worker ends the call on a 401 or 403, because a secret that does not
390
+ * match will not match on the next sentence either.
391
+ *
392
+ * ```ts
393
+ * const raw = Buffer.from(await request.arrayBuffer());
394
+ * const { text, output } = await verifyVoiceWebhook(raw, request.headers, process.env.VOICE_SECRET!);
395
+ * // reply 200, Content-Type audio/pcm: s16le mono at output.sample_rate, streamed
396
+ * ```
397
+ */
398
+ declare function verifyVoiceWebhook(rawBody: Uint8Array | string, headers: WebhookHeaders, secret: string, options?: VerifyOptions): Promise<VoiceWebhookRequest>;
369
399
 
370
400
  declare const clipLibraryDeclarationSchema: z.ZodObject<{
371
401
  idle: z.ZodOptional<z.ZodObject<{
@@ -393,4 +423,4 @@ declare const clipLibraryDeclarationSchema: z.ZodObject<{
393
423
  }, z.core.$strict>>>>;
394
424
  }, z.core.$strict>;
395
425
 
396
- export { Asset, AssetKind, Avatar, AvatarSourceSwap, AvatarUpdate, CallMode, CallPolicy, ClipLibrary, ClipLibraryDeclaration, ClipLibraryUpdate, CreditBalance, EndCallOptions, ListRecordingsQuery, ListRecordingsResponse, ListSessionsOptions, LoopRedirect, RealtimeAvatar, RealtimeAvatarError, RealtimeAvatarHttpError, type RealtimeAvatarOptions, RecordingAccessResponse, RecordingArtifact, type StartCallOptions, StartCallResult, TranscriptPayload, UsageSession, UsageSessionPage, clipLibraryDeclarationSchema, verifyTranscript };
426
+ export { Asset, AssetKind, Avatar, AvatarSourceSwap, AvatarUpdate, CallMode, CallPolicy, ClipLibrary, ClipLibraryDeclaration, ClipLibraryUpdate, CreditBalance, EndCallOptions, ListRecordingsQuery, ListRecordingsResponse, ListSessionsOptions, LoopRedirect, RealtimeAvatar, RealtimeAvatarError, RealtimeAvatarHttpError, type RealtimeAvatarOptions, RealtimeAvatarWebhookError, RecordingAccessResponse, RecordingArtifact, type StartCallOptions, StartCallResult, TranscriptPayload, UsageSession, UsageSessionPage, VoiceWebhookRequest, type WebhookVerificationErrorCode, clipLibraryDeclarationSchema, verifyTranscript, verifyVoiceWebhook };
package/dist/index.js CHANGED
@@ -1,2 +1,2 @@
1
- export { RealtimeAvatar, RealtimeAvatarError, RealtimeAvatarHttpError, clipLibraryDeclarationSchema, isQueued, listRecordingsResponseSchema, recordingAccessResponseSchema, recordingArtifactSchema, recordingModeSchema, verifyTranscript } from './chunk-6E3SZH35.js';
1
+ export { RealtimeAvatar, RealtimeAvatarError, RealtimeAvatarHttpError, RealtimeAvatarWebhookError, clipLibraryDeclarationSchema, isQueued, listRecordingsResponseSchema, recordingAccessResponseSchema, recordingArtifactSchema, recordingModeSchema, verifyTranscript, verifyVoiceWebhook } from './chunk-V7A4NRKC.js';
2
2
  import './chunk-MCIXU6XP.js';
package/dist/nextjs.d.ts CHANGED
@@ -1,5 +1,5 @@
1
- import { P as ProxyConfig } from './types-B1IR4EaJ.js';
2
- import './types-C8X50QT9.js';
1
+ import { P as ProxyConfig } from './types-Bli1UeP0.js';
2
+ import './types-yiemDkm0.js';
3
3
  import 'zod';
4
4
 
5
5
  /**
package/dist/nextjs.js CHANGED
@@ -1,5 +1,5 @@
1
- import { createProxyHandler } from './chunk-IJHM44YT.js';
2
- import './chunk-6E3SZH35.js';
1
+ import { createProxyHandler } from './chunk-K3VC6BF7.js';
2
+ import './chunk-V7A4NRKC.js';
3
3
  import './chunk-MCIXU6XP.js';
4
4
 
5
5
  // ../proxy/src/nextjs.ts