@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/README.md +104 -7
- package/dist/cli-omni-template.d.ts +2 -2
- package/dist/cli-omni-template.js +2 -2
- package/dist/index.d.ts +68 -10
- package/dist/index.js +321 -43
- package/dist/speech-metadata.d.ts +5 -0
- package/dist/speech-metadata.js +37 -0
- package/dist/speech-text.d.ts +18 -0
- package/dist/speech-text.js +75 -0
- package/package.json +1 -1
- package/src/cli-omni-template.ts +2 -2
- package/src/index.ts +335 -41
- package/src/speech-metadata.ts +33 -0
- package/src/speech-text.ts +71 -0
package/dist/index.js
CHANGED
|
@@ -1,11 +1,5 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
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
|
|
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 (
|
|
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
|
-
//
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
748
|
+
this.sendOrdered(omniAudioFrame(bytes));
|
|
589
749
|
return;
|
|
590
750
|
}
|
|
591
|
-
//
|
|
592
|
-
//
|
|
593
|
-
this.
|
|
594
|
-
|
|
595
|
-
|
|
596
|
-
|
|
597
|
-
|
|
598
|
-
|
|
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
|
-
/**
|
|
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.
|
|
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.
|
|
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.
|
|
814
|
+
this.sendOrdered(omniControlFrame(payload));
|
|
620
815
|
}
|
|
621
816
|
/** Close the session. */
|
|
622
817
|
close(code = WSCloseCode.Normal, reason = "") {
|
|
623
|
-
|
|
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
|
|
656
|
-
const
|
|
657
|
-
|
|
658
|
-
|
|
659
|
-
|
|
660
|
-
|
|
661
|
-
|
|
662
|
-
|
|
663
|
-
|
|
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,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;
|