@pyai/sdk 0.7.2 → 0.9.1

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/dist/index.js CHANGED
@@ -1,11 +1,5 @@
1
- /**
2
- * @pyai/sdk, official TypeScript/JavaScript client for the PyAI API.
3
- *
4
- * Thin, dependency-free wrapper over the public OpenAI-compatible surface at
5
- * https://api.pyai.com (contract: https://api.pyai.com/openapi.json). Runs in
6
- * the browser and Node 18+ for REST. Realtime needs an injected WebSocket
7
- * on Node 20; Node 22+ provides a global WebSocket. Keys are opaque, never parsed.
8
- */
1
+ import { validateSpeechResponse } from "./speech-metadata.js";
2
+ export { formatSpeechText } from "./speech-text.js";
9
3
  /** Stable, machine-readable error. Branch on `code`, not `message`. */
10
4
  export class PyAIError extends Error {
11
5
  status;
@@ -325,8 +319,10 @@ function omniTranscriptRole(value) {
325
319
  return "assistant";
326
320
  return null;
327
321
  }
328
- /** Normalize the live UTF-8 `0x02` text body and bounded legacy JSON bodies. */
329
- export function normalizeOmniTranscriptBody(bytes) {
322
+ /** Normalize native caller text, or explicitly selected bounded legacy JSON. */
323
+ export function normalizeOmniTranscriptBody(bytes, format = "text") {
324
+ if (format !== "text" && format !== "legacy-json")
325
+ return null;
330
326
  if (bytes.byteLength === 0 || bytes.byteLength > OMNI_TRANSCRIPT_MAX_BYTES)
331
327
  return null;
332
328
  let decoded;
@@ -338,13 +334,13 @@ export function normalizeOmniTranscriptBody(bytes) {
338
334
  }
339
335
  // The serving engine's canonical payload is plain UTF-8 caller text, not
340
336
  // JSON. Each frame is a delta for the current caller turn.
341
- if (!decoded.trimStart().startsWith("{")) {
337
+ if (format === "text") {
342
338
  const text = omniTranscriptText(decoded);
343
339
  return text
344
340
  ? { event: "transcript", role: "user", text, final: false, mode: "delta" }
345
341
  : null;
346
342
  }
347
- // Keep accepting a bounded direct object for older bridges and recordings.
343
+ // Older bridges/recordings must explicitly select their JSON encoding.
348
344
  let value;
349
345
  try {
350
346
  value = JSON.parse(decoded);
@@ -429,19 +425,43 @@ export class OmniConnection {
429
425
  ws;
430
426
  opts;
431
427
  closed = false;
428
+ playbackEnabled = false;
429
+ audioReady = false;
430
+ inputRate;
431
+ outputRate;
432
+ playbackEpoch = 0;
433
+ playbackSegment;
434
+ awaitingResume = false;
435
+ resumeTimer;
432
436
  /** Serializes async Blob reads in {@link sendAudio} so frames stay ordered. */
433
437
  blobTail = Promise.resolve();
438
+ outboundQueued = 0;
434
439
  /** Serializes inbound Blob decoding so browser frames stay ordered. */
435
440
  inboundTail = Promise.resolve();
441
+ inboundQueued = 0;
436
442
  constructor(url, subprotocol, opts) {
437
443
  this.opts = opts;
444
+ const query = new URL(url).searchParams;
445
+ this.inputRate = Number(query.get("rate") ?? 24000);
446
+ if (![8000, 16000, 24000].includes(this.inputRate) || (query.get("format") ?? "pcm16") !== "pcm16") {
447
+ throw new TypeError("Omni requires PCM16 mono input at 8000, 16000 or 24000 Hz");
448
+ }
449
+ this.outputRate = this.inputRate === 8000 ? 8000 : 24000;
450
+ this.awaitingResume = new URL(url).searchParams.has("resume_token");
451
+ const resumeTimeout = opts.resumeTimeoutMs ?? 5000;
452
+ if (!Number.isFinite(resumeTimeout) || resumeTimeout <= 0 || resumeTimeout > 30_000) {
453
+ throw new Error("resumeTimeoutMs must be greater than zero and at most 30000");
454
+ }
438
455
  const WS = opts.webSocket ?? globalThis.WebSocket;
439
456
  if (!WS) {
440
457
  throw new Error("No global WebSocket available; pass options.webSocket (e.g. the `ws` package) to omni.connect()");
441
458
  }
442
459
  this.ws = new WS(url, [REALTIME_SUBPROTOCOL_MARKER, subprotocol]);
460
+ if (this.awaitingResume) {
461
+ this.resumeTimer = setTimeout(() => this.rejectResume("Resume acknowledgement timed out"), resumeTimeout);
462
+ }
443
463
  this.ws.onopen = () => {
444
- if (opts.configure) {
464
+ if (opts.configure && !this.awaitingResume) {
445
465
  try {
446
466
  this.configure(opts.configure);
447
467
  }
@@ -455,8 +475,10 @@ export class OmniConnection {
455
475
  const reportDecodeError = (error) => {
456
476
  opts.onError?.(error instanceof Error ? error : new Error("Could not decode Omni frame"));
457
477
  };
458
- if (typeof Blob !== "undefined" && ev.data instanceof Blob) {
459
- this.inboundTail = this.inboundTail.then(() => this.handleMessage(ev.data)).catch(reportDecodeError);
478
+ if ((typeof Blob !== "undefined" && ev.data instanceof Blob) || this.inboundQueued > 0) {
479
+ this.inboundQueued++;
480
+ this.inboundTail = this.inboundTail.then(() => this.handleMessage(ev.data))
481
+ .catch(reportDecodeError).finally(() => { this.inboundQueued--; });
460
482
  }
461
483
  else {
462
484
  void this.handleMessage(ev.data).catch(reportDecodeError);
@@ -464,11 +486,65 @@ export class OmniConnection {
464
486
  };
465
487
  this.ws.onerror = (ev) => opts.onError?.(ev instanceof Error ? ev : new Error("WebSocket error"));
466
488
  this.ws.onclose = (ev) => {
489
+ clearTimeout(this.resumeTimer);
467
490
  this.closed = true;
468
491
  opts.onClose?.(ev.code, ev.reason);
469
492
  };
470
493
  }
494
+ rejectResume(message) {
495
+ if (this.closed)
496
+ return;
497
+ this.close(4000, "resume_failed");
498
+ this.opts.onError?.(new PyAIError(0, message, "resume_failed"));
499
+ }
500
+ assertSendable() {
501
+ if (this.closed)
502
+ throw new Error("Omni connection is closed");
503
+ if (this.awaitingResume)
504
+ throw new Error("Wait for a confirmed session resume before sending");
505
+ }
506
+ failAudioContract(message) {
507
+ this.audioReady = false;
508
+ this.playbackEnabled = false;
509
+ this.playbackEpoch++;
510
+ this.playbackSegment = undefined;
511
+ try {
512
+ this.opts.onBargeIn?.({ event: "flush", reason: "audio_format_mismatch" });
513
+ }
514
+ finally {
515
+ this.close(4002, "audio_format_mismatch");
516
+ this.opts.onError?.(new Error(message));
517
+ }
518
+ }
519
+ validateAudioControl(frame) {
520
+ if (!["hello", "configured", "audio_segment_start"].includes(frame.event))
521
+ return true;
522
+ let valid = frame.event === "hello" || this.audioReady;
523
+ const expected = {
524
+ format: "pcm16", audio_format: "pcm16", audio_out_format: "pcm16",
525
+ sample_rate: this.outputRate, audio_out_sample_rate: this.outputRate,
526
+ channels: 1, audio_channels: 1, audio_out_channels: 1,
527
+ audio_in: `pcm16@${this.inputRate}`, audio_out: `pcm16@${this.outputRate}`,
528
+ };
529
+ for (const [key, value] of Object.entries(expected)) {
530
+ if (key in frame && frame[key] !== value)
531
+ valid = false;
532
+ }
533
+ if (frame.event === "hello" && frame.audio_out !== expected.audio_out)
534
+ valid = false;
535
+ if (frame.event === "audio_segment_start" && frame.sample_rate !== this.outputRate)
536
+ valid = false;
537
+ if (!valid) {
538
+ this.failAudioContract("Omni audio declaration does not match the negotiated PCM16 mono format");
539
+ return false;
540
+ }
541
+ if (frame.event === "hello")
542
+ this.audioReady = true;
543
+ return true;
544
+ }
471
545
  async handleMessage(data) {
546
+ if (this.closed)
547
+ return;
472
548
  // Server → client binary frames are TYPE-TAGGED by their first byte:
473
549
  // 0x01 = agent audio (PCM16) · 0x02 = transcript UTF-8 · 0x03 = control JSON.
474
550
  // (Treating every binary frame as audio, the old behavior, plays the
@@ -481,13 +557,47 @@ export class OmniConnection {
481
557
  this.opts.onError?.(new Error("Unsupported Omni binary frame"));
482
558
  return;
483
559
  }
560
+ if (this.closed)
561
+ return;
484
562
  const tag = bytes[0];
563
+ if (this.awaitingResume && tag !== 0x03)
564
+ return;
485
565
  if (tag === 0x01) {
486
- this.opts.onAudio?.(bytes.slice(1)); // copy → aligned PCM16
566
+ if (!this.audioReady || (bytes.length - 1) % 2) {
567
+ this.failAudioContract("Omni audio requires a valid hello and whole PCM16 samples");
568
+ return;
569
+ }
570
+ const audio = bytes.slice(1); // copy → aligned PCM16
571
+ const segment = this.playbackSegment;
572
+ let playback;
573
+ if (this.playbackEnabled && segment && bytes.length > 1) {
574
+ const startSample = segment.samples;
575
+ segment.samples += (bytes.length - 1) / 2;
576
+ const endSample = segment.samples;
577
+ const pending = { end: endSample, played: false };
578
+ segment.chunks.set(startSample, pending);
579
+ playback = { replyId: segment.replyId, segmentId: segment.segmentId,
580
+ sampleRate: segment.sampleRate, endSample,
581
+ played: () => {
582
+ if (pending.played || this.closed || segment.epoch !== this.playbackEpoch)
583
+ return;
584
+ pending.played = true;
585
+ const before = segment.confirmed;
586
+ let next = segment.chunks.get(segment.confirmed);
587
+ while (next?.played) {
588
+ segment.chunks.delete(segment.confirmed);
589
+ segment.confirmed = next.end;
590
+ next = segment.chunks.get(segment.confirmed);
591
+ }
592
+ if (segment.confirmed > before)
593
+ this.playbackProgress(segment.replyId, segment.segmentId, segment.confirmed);
594
+ } };
595
+ }
596
+ this.opts.onAudio?.(audio, playback);
487
597
  return;
488
598
  }
489
599
  if (tag === 0x02) {
490
- const transcript = normalizeOmniTranscriptBody(bytes.subarray(1));
600
+ const transcript = normalizeOmniTranscriptBody(bytes.subarray(1), this.opts.transcriptFormat);
491
601
  if (transcript)
492
602
  this.dispatchFrame(transcript);
493
603
  else
@@ -497,6 +607,8 @@ export class OmniConnection {
497
607
  if (tag === 0x03) {
498
608
  try {
499
609
  const parsed = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes.subarray(1)));
610
+ if (this.awaitingResume && parsed?.event !== OmniEvent.Hello && parsed?.event !== OmniEvent.SessionStarted && parsed?.event !== OmniEvent.Error)
611
+ return;
500
612
  if (parsed?.event === OmniEvent.Transcript) {
501
613
  // The deployed engine also sends this bounded synthesis-input
502
614
  // advisory. It is not caller ASR or proof that speech was played.
@@ -531,6 +643,50 @@ export class OmniConnection {
531
643
  this.opts.onError?.(new Error("Omni server control frame is missing its event key"));
532
644
  return;
533
645
  }
646
+ if (this.closed)
647
+ return;
648
+ if (!this.validateAudioControl(frame))
649
+ return;
650
+ if (this.awaitingResume) {
651
+ if (eventName === OmniEvent.SessionStarted) {
652
+ if (frame.resumed !== true) {
653
+ this.rejectResume("The server could not restore the previous conversation");
654
+ return;
655
+ }
656
+ clearTimeout(this.resumeTimer);
657
+ this.awaitingResume = false;
658
+ if (this.opts.configure)
659
+ this.configure(this.opts.configure);
660
+ }
661
+ else if (eventName !== OmniEvent.Hello && eventName !== OmniEvent.Error) {
662
+ return;
663
+ }
664
+ }
665
+ if (eventName === "configured")
666
+ this.playbackEnabled = frame.playback_ack === true;
667
+ if (eventName === "audio_segment_start" && this.playbackEnabled) {
668
+ if (typeof frame.reply_id !== "string" || !/^[a-f0-9]{32}$/.test(frame.reply_id)
669
+ || typeof frame.segment_id !== "string" || !/^[1-9][0-9]{0,5}$/.test(frame.segment_id)
670
+ || (frame.sample_rate !== 8000 && frame.sample_rate !== 24000)) {
671
+ this.failAudioContract("Invalid Omni playback segment");
672
+ return;
673
+ }
674
+ this.playbackSegment = { replyId: frame.reply_id, segmentId: frame.segment_id,
675
+ sampleRate: frame.sample_rate, samples: 0, confirmed: 0, epoch: this.playbackEpoch, chunks: new Map() };
676
+ }
677
+ else if (eventName === "audio_segment_done"
678
+ && this.playbackSegment?.replyId === frame.reply_id
679
+ && this.playbackSegment?.segmentId === frame.segment_id) {
680
+ this.playbackSegment = undefined;
681
+ }
682
+ else if (eventName === "flush" || eventName === "barge_in"
683
+ || eventName === "reply_interrupted" || eventName === "reply_failed") {
684
+ this.playbackEpoch++;
685
+ this.playbackSegment = undefined;
686
+ }
687
+ if (["reply_generation_done", "reply_playback_done", "reply_interrupted", "reply_failed"].includes(eventName)) {
688
+ this.opts.onReplyState?.(frame);
689
+ }
534
690
  this.opts.onEvent?.(frame);
535
691
  switch (eventName) {
536
692
  case OmniEvent.Hello:
@@ -550,6 +706,8 @@ export class OmniConnection {
550
706
  break;
551
707
  case OmniEvent.BargeIn:
552
708
  case OmniEvent.Flush:
709
+ case "reply_interrupted":
710
+ case "reply_failed":
553
711
  this.opts.onBargeIn?.(frame);
554
712
  break;
555
713
  case OmniEvent.ToolCall:
@@ -572,10 +730,11 @@ export class OmniConnection {
572
730
  * `{"event":"configure"}` is acked but silently dropped by the engine.)
573
731
  */
574
732
  configure(cfg) {
733
+ this.assertSendable();
575
734
  const payload = { ...cfg };
576
735
  delete payload.type;
577
736
  delete payload.event;
578
- this.ws.send(omniControlFrame({ type: "configure", ...payload }));
737
+ this.sendOrdered(omniControlFrame({ type: "configure", ...payload }));
579
738
  }
580
739
  /**
581
740
  * Stream a chunk of caller audio (PCM16 LE mono at the negotiated rate) as a
@@ -583,27 +742,62 @@ export class OmniConnection {
583
742
  * default branch, so an untagged chunk is dropped with no error.
584
743
  */
585
744
  sendAudio(chunk) {
745
+ this.assertSendable();
586
746
  const bytes = omniToBytes(chunk);
587
747
  if (bytes) {
588
- this.ws.send(omniAudioFrame(bytes));
748
+ this.sendOrdered(omniAudioFrame(bytes));
589
749
  return;
590
750
  }
591
- // A Blob can only be read asynchronously; queue behind the previous read so
592
- // frames still reach the engine in call order.
593
- this.blobTail = this.blobTail
594
- .then(async () => {
595
- const buf = await chunk.arrayBuffer();
596
- this.ws.send(omniAudioFrame(new Uint8Array(buf)));
597
- })
598
- .catch((err) => this.opts.onError?.(err instanceof Error ? err : new Error(String(err))));
751
+ // Reserve order before reading a Blob: later audio and controls must not
752
+ // overtake it. Closing still cancels queued work rather than replaying it.
753
+ this.queueOutbound(async () => omniAudioFrame(new Uint8Array(await chunk.arrayBuffer())));
754
+ }
755
+ queueOutbound(frame) {
756
+ this.outboundQueued++;
757
+ this.blobTail = this.blobTail.then(async () => {
758
+ this.assertSendable();
759
+ const data = await frame();
760
+ this.assertSendable();
761
+ this.ws.send(data);
762
+ }).catch((error) => {
763
+ this.opts.onError?.(error instanceof Error ? error : new Error(String(error)));
764
+ }).finally(() => { this.outboundQueued--; });
765
+ }
766
+ sendOrdered(data) {
767
+ if (this.outboundQueued)
768
+ this.queueOutbound(() => data);
769
+ else
770
+ this.ws.send(data);
599
771
  }
600
- /** Send DTMF digits as a `{"type":"dtmf"}` control frame. */
772
+ /** Report samples actually rendered by the player in one reply segment.
773
+ * Receiving or scheduling bytes is not playback. Stale receipts are ignored
774
+ * server-side; this never changes completed tool actions. */
775
+ playbackProgress(replyId, segmentId, playedSamples) {
776
+ this.assertSendable();
777
+ if (!this.playbackEnabled)
778
+ throw new Error("Playback acknowledgments were not negotiated");
779
+ if (!/^[a-f0-9]{32}$/.test(replyId) || !/^[1-9][0-9]{0,5}$/.test(segmentId)
780
+ || !Number.isSafeInteger(playedSamples) || playedSamples < 0) {
781
+ throw new TypeError("Invalid playback progress");
782
+ }
783
+ this.sendOrdered(omniControlFrame({ type: "playback_progress", reply_id: replyId,
784
+ segment_id: segmentId, played_samples: playedSamples }));
785
+ }
786
+ /** Send a nonempty DTMF sequence as ordered single-key control frames.
787
+ * Valid keys are 0–9, *, # and A–D; lowercase a–d are normalized. */
601
788
  sendDtmf(digits) {
602
- this.ws.send(omniControlFrame({ type: "dtmf", digits }));
789
+ this.assertSendable();
790
+ if (typeof digits !== "string" || digits.length === 0 || /[^0-9*#A-Da-d]/.test(digits)) {
791
+ throw new TypeError("Invalid DTMF sequence");
792
+ }
793
+ for (const digit of digits.toUpperCase()) {
794
+ this.sendOrdered(omniControlFrame({ type: "dtmf", digit }));
795
+ }
603
796
  }
604
797
  /** Reply to a client-loop {@link OmniEvent.ToolCall}. */
605
798
  toolResult(callId, payload) {
606
- this.ws.send(omniControlFrame({ type: "tool_result", call_id: callId, ...payload }));
799
+ this.assertSendable();
800
+ this.sendOrdered(omniControlFrame({ type: "tool_result", call_id: callId, ...payload }));
607
801
  }
608
802
  /**
609
803
  * Send an arbitrary control frame for forward-compat control types the SDK
@@ -611,17 +805,21 @@ export class OmniConnection {
611
805
  * never `event`.
612
806
  */
613
807
  send(frame) {
808
+ this.assertSendable();
614
809
  if (typeof frame.type !== "string" || !frame.type) {
615
810
  throw new TypeError("Omni client control frames must have a non-empty type key");
616
811
  }
617
812
  const payload = { ...frame };
618
813
  delete payload.event;
619
- this.ws.send(omniControlFrame(payload));
814
+ this.sendOrdered(omniControlFrame(payload));
620
815
  }
621
816
  /** Close the session. */
622
817
  close(code = WSCloseCode.Normal, reason = "") {
623
- if (!this.closed)
818
+ clearTimeout(this.resumeTimer);
819
+ if (!this.closed) {
820
+ this.closed = true;
624
821
  this.ws.close(code, reason);
822
+ }
625
823
  }
626
824
  /** The underlying socket (escape hatch for advanced use). */
627
825
  get socket() {
@@ -633,11 +831,46 @@ export class OmniConnection {
633
831
  }
634
832
  }
635
833
  const RETRYABLE = new Set([429, 500, 502, 503, 504]);
834
+ // Only transport codes known to be transient; do not retry TLS, URL or DNS
835
+ // configuration errors. Browsers often hide the cause: those propagate intact.
836
+ const TRANSIENT_TRANSPORT = new Set(["ECONNRESET", "ECONNREFUSED", "EPIPE", "ETIMEDOUT", "EAI_AGAIN", "UND_ERR_SOCKET", "UND_ERR_CONNECT_TIMEOUT", "UND_ERR_HEADERS_TIMEOUT", "UND_ERR_BODY_TIMEOUT"]);
837
+ function transientTransport(error) {
838
+ const seen = new Set();
839
+ while (error && typeof error === "object" && !seen.has(error)) {
840
+ seen.add(error);
841
+ const value = error;
842
+ if (value.name === "AbortError" || value.name === "TimeoutError")
843
+ return false;
844
+ if (value.code && TRANSIENT_TRANSPORT.has(value.code))
845
+ return true;
846
+ error = value.cause;
847
+ }
848
+ return false;
849
+ }
850
+ function retryDelay(header, attempt) {
851
+ const jitter = Math.random() * Math.min(2 ** attempt * 250, 2000);
852
+ if (header === null)
853
+ return jitter;
854
+ const seconds = /^\d+(?:\.\d+)?$/.test(header.trim()) ? Number(header) : NaN;
855
+ const delay = Number.isFinite(seconds) ? seconds * 1000 : Date.parse(header) - Date.now();
856
+ return Number.isFinite(delay) ? Math.max(0, delay) + jitter : jitter;
857
+ }
858
+ function retryPause(ms, signal) {
859
+ return new Promise((resolve, reject) => {
860
+ const cancel = () => { clearTimeout(timer); signal?.removeEventListener("abort", cancel); reject(signal?.reason); };
861
+ const timer = setTimeout(() => { signal?.removeEventListener("abort", cancel); resolve(); }, ms);
862
+ signal?.addEventListener("abort", cancel, { once: true });
863
+ if (signal?.aborted)
864
+ cancel();
865
+ });
866
+ }
636
867
  export class PyAI {
637
868
  apiKey;
638
869
  baseURL;
639
870
  fetchImpl;
640
871
  maxRetries;
872
+ retryWindowMs;
873
+ signal;
641
874
  constructor(opts) {
642
875
  if (!opts.apiKey)
643
876
  throw new Error("apiKey is required");
@@ -645,6 +878,12 @@ export class PyAI {
645
878
  this.baseURL = (opts.baseURL ?? "https://api.pyai.com").replace(/\/$/, "");
646
879
  this.fetchImpl = opts.fetch ?? globalThis.fetch;
647
880
  this.maxRetries = opts.maxRetries ?? 2;
881
+ this.retryWindowMs = opts.retryWindowMs ?? 10_000;
882
+ this.signal = opts.signal;
883
+ if (!Number.isSafeInteger(this.maxRetries) || this.maxRetries < 0)
884
+ throw new Error("maxRetries must be a non-negative integer");
885
+ if (!Number.isFinite(this.retryWindowMs) || this.retryWindowMs < 0)
886
+ throw new Error("retryWindowMs must be finite and non-negative");
648
887
  if (!this.fetchImpl)
649
888
  throw new Error("No fetch implementation available; pass opts.fetch");
650
889
  }
@@ -652,25 +891,57 @@ export class PyAI {
652
891
  authHeaders(extra = {}) {
653
892
  return { Authorization: `Bearer ${this.apiKey}`, ...extra };
654
893
  }
655
- async request(path, init, attempt = 0) {
656
- const res = await this.fetchImpl(`${this.baseURL}${path}`, init);
657
- if (res.ok)
658
- return res;
659
- if (RETRYABLE.has(res.status) && attempt < this.maxRetries) {
660
- const retryAfter = Number(res.headers.get("retry-after"));
661
- const delayMs = Number.isFinite(retryAfter) && retryAfter > 0 ? retryAfter * 1000 : 2 ** attempt * 250;
662
- await new Promise((r) => setTimeout(r, delayMs));
663
- return this.request(path, init, attempt + 1);
894
+ async request(path, init) {
895
+ const signal = init.signal ?? this.signal;
896
+ const safe = ["GET", "HEAD"].includes((init.method ?? "GET").toUpperCase());
897
+ const deadline = performance.now() + this.retryWindowMs;
898
+ for (let attempt = 0;; attempt++) {
899
+ signal?.throwIfAborted();
900
+ let res;
901
+ let failure;
902
+ try {
903
+ res = await this.fetchImpl(`${this.baseURL}${path}`, { ...init, signal });
904
+ }
905
+ catch (error) {
906
+ // Preserve the original exception and cause; an arbitrary TypeError may
907
+ // be a programming/CORS/configuration error, not a transient connection.
908
+ if (signal?.aborted || !transientTransport(error))
909
+ throw error;
910
+ failure = error;
911
+ }
912
+ if (res?.ok)
913
+ return res;
914
+ if (!safe || attempt >= this.maxRetries || (res && !RETRYABLE.has(res.status))) {
915
+ if (res)
916
+ throw await this.toError(res, signal);
917
+ throw failure;
918
+ }
919
+ const delay = retryDelay(res?.headers.get("retry-after") ?? null, attempt);
920
+ if (performance.now() + delay >= deadline) {
921
+ if (res)
922
+ throw await this.toError(res, signal);
923
+ throw failure;
924
+ }
925
+ // Dispose the failed response before waiting/reusing its connection.
926
+ if (res?.body)
927
+ await res.body.cancel().catch(() => { });
928
+ await retryPause(delay, signal);
929
+ if (performance.now() >= deadline) {
930
+ if (res)
931
+ throw new PyAIError(res.status, `HTTP ${res.status}`, undefined, undefined, res.headers.get("x-request-id") ?? undefined);
932
+ throw failure;
933
+ }
664
934
  }
665
- throw await this.toError(res);
666
935
  }
667
- async toError(res) {
936
+ async toError(res, signal) {
668
937
  const requestId = res.headers.get("x-request-id") ?? undefined;
669
938
  let body;
670
939
  try {
671
940
  body = await res.json();
941
+ signal?.throwIfAborted();
672
942
  }
673
943
  catch {
944
+ signal?.throwIfAborted();
674
945
  return new PyAIError(res.status, `HTTP ${res.status}`, undefined, undefined, requestId);
675
946
  }
676
947
  const b = body;
@@ -761,6 +1032,7 @@ export class PyAI {
761
1032
  headers: this.authHeaders({ "Content-Type": "application/json" }),
762
1033
  body: JSON.stringify({ model: "pyai-speak", ...params }),
763
1034
  });
1035
+ await validateSpeechResponse(res, params);
764
1036
  return res.arrayBuffer();
765
1037
  },
766
1038
  /**
@@ -778,6 +1050,7 @@ export class PyAI {
778
1050
  headers: this.authHeaders({ "Content-Type": "application/json" }),
779
1051
  body: JSON.stringify({ model: "pyai-speak", ...params, stream: true }),
780
1052
  });
1053
+ await validateSpeechResponse(res, params);
781
1054
  if (!res.body)
782
1055
  throw new PyAIError(res.status, "Response had no body to stream");
783
1056
  return res.body;
@@ -1081,6 +1354,11 @@ export class PyAI {
1081
1354
  */
1082
1355
  connect: (opts = {}) => {
1083
1356
  const query = { ...(opts.query ?? {}) };
1357
+ if (opts.resumeToken !== undefined) {
1358
+ if (!opts.resumeToken.trim())
1359
+ throw new Error("resumeToken must not be empty");
1360
+ query.resume_token = opts.resumeToken;
1361
+ }
1084
1362
  if (opts.format)
1085
1363
  query.format = opts.format;
1086
1364
  if (opts.rate)
@@ -0,0 +1,5 @@
1
+ /** Validate only explicitly requested PCM; keep opaque container APIs unchanged. */
2
+ export declare function validateSpeechResponse(response: Response, params: {
3
+ response_format?: string;
4
+ sample_rate?: number;
5
+ }): Promise<void>;
@@ -0,0 +1,37 @@
1
+ /** Validate only explicitly requested PCM; keep opaque container APIs unchanged. */
2
+ export async function validateSpeechResponse(response, params) {
3
+ if (params.response_format !== "pcm")
4
+ return;
5
+ const rate = params.sample_rate ?? 24000;
6
+ const parts = (response.headers.get("Content-Type") ?? "").split(";");
7
+ const mediaType = parts.shift()?.trim().toLowerCase();
8
+ const values = new Map();
9
+ let malformed = false;
10
+ for (const part of parts) {
11
+ const match = /^\s*([^=\s]+)\s*=\s*(?:"([^"\\]*)"|([^\s";]+))\s*$/.exec(part);
12
+ if (!match) {
13
+ malformed = true;
14
+ continue;
15
+ }
16
+ const name = match[1].toLowerCase();
17
+ values.set(name, [...(values.get(name) ?? []), match[2] ?? match[3]]);
18
+ }
19
+ const rates = values.get("rate") ?? [];
20
+ const channels = values.get("channels") ?? [];
21
+ const expected = {
22
+ "X-PyAI-Audio-Encoding": "pcm_s16le",
23
+ "X-PyAI-Audio-Sample-Rate": String(rate),
24
+ "X-PyAI-Audio-Channels": "1",
25
+ };
26
+ if (malformed || !Number.isInteger(rate) || rate < 8000 || rate > 48000
27
+ || mediaType !== "audio/pcm" || rates.length !== 1 || rates[0] !== String(rate)
28
+ || (channels.length > 0 && (channels.length !== 1 || channels[0] !== "1"))
29
+ || Object.entries(expected).some(([key, value]) => response.headers.has(key) && response.headers.get(key) !== value)) {
30
+ // A response body owns the fetch connection even before any audio is read.
31
+ try {
32
+ await response.body?.cancel();
33
+ }
34
+ catch { /* Preserve the metadata error. */ }
35
+ throw new Error("Speak PCM response metadata must match requested mono PCM16 sample rate");
36
+ }
37
+ }
@@ -0,0 +1,18 @@
1
+ /** Explicit English speech formatting. Plain strings are never rewritten. */
2
+ export type SpeechTextPart = string | {
3
+ type: "currency";
4
+ value: string;
5
+ currency: "USD" | "GBP" | "EUR";
6
+ } | {
7
+ type: "date";
8
+ value: string;
9
+ locale: "en-US" | "en-GB";
10
+ } | {
11
+ type: "phone" | "digits";
12
+ value: string;
13
+ };
14
+ /** Join literal text and explicitly typed English fields for Speak input or Cast text.
15
+ * Supply spaces and punctuation in literal parts. This does not infer field types,
16
+ * validate phone reachability, or guarantee how a voice will pronounce the output.
17
+ */
18
+ export declare function formatSpeechText(parts: readonly SpeechTextPart[]): string;