@pyai/sdk 0.16.0 → 0.18.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/CLI.md +20 -0
- package/CLI.schema.json +2 -1
- package/README.md +3 -3
- package/dist/cli-omni-template.d.ts +2 -2
- package/dist/cli-omni-template.js +2 -2
- package/dist/cli.js +10 -8
- package/dist/dialer/appServer.d.ts +11 -1
- package/dist/dialer/appServer.js +224 -28
- package/dist/dialer/dialerElement.d.ts +2 -0
- package/dist/dialer/dialerElement.js +13 -4
- package/dist/dialer/dialingQueue.d.ts +3 -0
- package/dist/dialer/dialingQueue.js +63 -47
- package/dist/dialer/indexedDbJournal.d.ts +2 -0
- package/dist/dialer/indexedDbJournal.js +8 -0
- package/dist/dialer/managedDialer.d.ts +2 -1
- package/dist/dialer/managedDialer.js +7 -3
- package/dist/dialer/presentation.d.ts +19 -0
- package/dist/dialer/presentation.js +37 -0
- package/dist/dialer/serverBroker.js +10 -5
- package/dist/index.d.ts +188 -6
- package/dist/index.js +28 -3
- package/package.json +1 -1
- package/src/cli-omni-template.ts +2 -2
- package/src/cli.ts +9 -7
- package/src/dialer/app/app.css +6 -1
- package/src/dialer/app/app.html +4 -4
- package/src/dialer/app/app.js +92 -12
- package/src/dialer/app/incoming.js +107 -0
- package/src/dialer/appServer.ts +159 -27
- package/src/dialer/dialerElement.ts +14 -4
- package/src/dialer/dialingQueue.ts +51 -35
- package/src/dialer/indexedDbJournal.ts +6 -1
- package/src/dialer/managedDialer.ts +8 -4
- package/src/dialer/presentation.ts +38 -0
- package/src/dialer/serverBroker.ts +9 -4
- package/src/index.ts +114 -8
|
@@ -84,8 +84,10 @@ export class IndexedDbDialerJournal {
|
|
|
84
84
|
/** Queue progress lives separately from call capabilities. Revision checks stop
|
|
85
85
|
* stale tabs from replacing or advancing another tab's saved contact list. */
|
|
86
86
|
export class IndexedDbDialingQueueJournal {
|
|
87
|
+
name;
|
|
87
88
|
database;
|
|
88
89
|
constructor(name = "pyai-dialing-queue") {
|
|
90
|
+
this.name = name;
|
|
89
91
|
this.database = new Promise((resolve, reject) => {
|
|
90
92
|
const request = indexedDB.open(name, 1);
|
|
91
93
|
request.onupgradeneeded = () => { request.result.createObjectStore("queues", { keyPath: "scope" }); };
|
|
@@ -94,6 +96,12 @@ export class IndexedDbDialingQueueJournal {
|
|
|
94
96
|
request.onblocked = () => reject(new Error("Close the older dialer tab to open queue storage."));
|
|
95
97
|
});
|
|
96
98
|
}
|
|
99
|
+
async runExclusive(scope, action) {
|
|
100
|
+
const locks = globalThis.navigator?.locks;
|
|
101
|
+
if (!locks)
|
|
102
|
+
throw new Error("This browser cannot safely recover a saved calling queue.");
|
|
103
|
+
return await locks.request(JSON.stringify(["pyai-dialing-queue", this.name, scope]), action);
|
|
104
|
+
}
|
|
97
105
|
async read(scope) {
|
|
98
106
|
const db = await this.database;
|
|
99
107
|
return new Promise((resolve, reject) => {
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import type { TelephonyBrowserSession, TelephonyBrowserSessionCreate, TelephonyCall } from "../index.ts";
|
|
1
|
+
import type { TelephonyBrowserSession, TelephonyBrowserSessionCreate, TelephonyCall, TelephonyCallControl } from "../index.ts";
|
|
2
2
|
/** Implement on your server using PyAI's telephony client. The browser receives
|
|
3
3
|
* a single-call capability, never an organization key or carrier credential. */
|
|
4
4
|
export interface DialerBroker {
|
|
@@ -6,6 +6,7 @@ export interface DialerBroker {
|
|
|
6
6
|
get(callId: string): Promise<TelephonyCall>;
|
|
7
7
|
hangup(callId: string): Promise<TelephonyCall>;
|
|
8
8
|
setHold?(callId: string, held: boolean, key: string): Promise<TelephonyCall>;
|
|
9
|
+
sendDtmf?(callId: string, digits: string, key: string): Promise<TelephonyCallControl>;
|
|
9
10
|
transfers?: {
|
|
10
11
|
create(callId: string, input: {
|
|
11
12
|
to: string;
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
const terminal = (call) => ["completed", "failed", "canceled"].includes(call.status);
|
|
2
2
|
/** A durable handoff keeps its original room after the browser goes away. */
|
|
3
|
-
export const dialerCallHandedOff = (call) => call.transfer_enabled === true && Boolean(call.transfers?.some(transfer => transfer.status === "completed" || transfer.mode === "cold" &&
|
|
3
|
+
export const dialerCallHandedOff = (call) => call.transfer_enabled === true && Boolean(call.transfers?.some(transfer => transfer.status === "completed" || transfer.mode === "cold" && transfer.status === "completing"));
|
|
4
4
|
/** One immutable workspace/user scope per instance. Setup and stop retain the
|
|
5
5
|
* original intent through lost acknowledgments, reloads and audio failures. */
|
|
6
6
|
export class ManagedDialer {
|
|
@@ -60,7 +60,9 @@ export class ManagedDialer {
|
|
|
60
60
|
}
|
|
61
61
|
async restore() {
|
|
62
62
|
return this.exclusive(async () => {
|
|
63
|
-
|
|
63
|
+
// Queue recovery may have waited for another tab to save an admission
|
|
64
|
+
// after this instance first loaded an empty journal.
|
|
65
|
+
if (this.initialized && this.intent)
|
|
64
66
|
return;
|
|
65
67
|
const saved = await this.journal.read(this.scope);
|
|
66
68
|
if (saved && saved.scope !== this.scope)
|
|
@@ -291,8 +293,10 @@ export class ManagedDialer {
|
|
|
291
293
|
const transfer = this.snapshot.call?.transfers?.find(item => item.id === this.intent.transfer.id);
|
|
292
294
|
if (command === "complete" && transfer?.status !== "ready")
|
|
293
295
|
throw new Error("Wait until the transfer target has joined.");
|
|
294
|
-
if (this.intent.transfer.mode !== "warm")
|
|
296
|
+
if (this.intent.transfer.mode !== "warm" && command === "complete")
|
|
295
297
|
throw new Error("Cold transfers complete automatically.");
|
|
298
|
+
if (command === "cancel" && ["completing", "completed"].includes(transfer?.status ?? ""))
|
|
299
|
+
throw new Error("The handoff has started. Check its status instead of canceling it.");
|
|
296
300
|
if (this.intent.transfer.command && this.intent.transfer.command !== command)
|
|
297
301
|
throw new Error("Recover the saved transfer command first.");
|
|
298
302
|
const next = structuredClone(this.intent);
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
/** Presentation metadata only. No credentials, network origins or calling policy. */
|
|
2
|
+
export interface DialerPresentation {
|
|
3
|
+
name: string;
|
|
4
|
+
white_label: boolean;
|
|
5
|
+
primary_color: string;
|
|
6
|
+
logo_png: string | null;
|
|
7
|
+
layout: "compact" | "comfortable";
|
|
8
|
+
features: {
|
|
9
|
+
calls: boolean;
|
|
10
|
+
incoming: boolean;
|
|
11
|
+
meetings: boolean;
|
|
12
|
+
power_queue: boolean;
|
|
13
|
+
};
|
|
14
|
+
}
|
|
15
|
+
export type DialerPresentationInput = Partial<Omit<DialerPresentation, "features">> & {
|
|
16
|
+
features?: Partial<DialerPresentation["features"]>;
|
|
17
|
+
};
|
|
18
|
+
export declare const defaultPresentation: DialerPresentation;
|
|
19
|
+
export declare function validatePresentation(value: unknown, defaults?: DialerPresentation): DialerPresentation;
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
const featureNames = ["calls", "incoming", "meetings", "power_queue"];
|
|
2
|
+
export const defaultPresentation = {
|
|
3
|
+
name: "PyAI Phone", white_label: false, primary_color: "#5C4DE4", logo_png: null,
|
|
4
|
+
layout: "compact", features: { calls: true, incoming: true, meetings: true, power_queue: true },
|
|
5
|
+
};
|
|
6
|
+
const record = (value) => !!value && typeof value === "object" && !Array.isArray(value);
|
|
7
|
+
export function validatePresentation(value, defaults = defaultPresentation) {
|
|
8
|
+
if (!record(value) || Object.keys(value).some(key => !["name", "white_label", "primary_color", "logo_png", "layout", "features"].includes(key)))
|
|
9
|
+
throw Error("Use only the app appearance settings.");
|
|
10
|
+
const result = { ...defaults, ...value, features: { ...defaults.features } };
|
|
11
|
+
if (typeof result.name !== "string" || !result.name.trim() || result.name.trim().length > 60 || /[\x00-\x1f\x7f]/.test(result.name))
|
|
12
|
+
throw Error("Use an app name of 1–60 characters.");
|
|
13
|
+
result.name = result.name.trim();
|
|
14
|
+
if (result.white_label && result.name === "PyAI Phone")
|
|
15
|
+
result.name = "Phone";
|
|
16
|
+
if (typeof result.white_label !== "boolean" || typeof result.primary_color !== "string" || !/^#[0-9a-f]{6}$/i.test(result.primary_color) || !["compact", "comfortable"].includes(result.layout))
|
|
17
|
+
throw Error("Choose a valid app color, layout and branding setting.");
|
|
18
|
+
result.primary_color = result.primary_color.toUpperCase();
|
|
19
|
+
if (result.logo_png !== null) {
|
|
20
|
+
if (typeof result.logo_png !== "string" || !/^data:image\/png;base64,[A-Za-z0-9+/]+={0,2}$/.test(result.logo_png))
|
|
21
|
+
throw Error("Choose a PNG logo, not a URL or an SVG.");
|
|
22
|
+
const encoded = result.logo_png.slice(22), bytes = Buffer.from(encoded, "base64");
|
|
23
|
+
if (bytes.length > 8192 || bytes.length < 33 || bytes.toString("base64") !== encoded || !bytes.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10])) || bytes.toString("ascii", 12, 16) !== "IHDR" || bytes.readUInt32BE(8) !== 13 || bytes.readUInt32BE(16) < 1 || bytes.readUInt32BE(20) < 1 || bytes.readUInt32BE(16) > 512 || bytes.readUInt32BE(20) > 512)
|
|
24
|
+
throw Error("Choose a PNG logo up to 8 KB and 512×512 pixels.");
|
|
25
|
+
}
|
|
26
|
+
if (value.features !== undefined) {
|
|
27
|
+
if (!record(value.features) || Object.keys(value.features).some(key => !featureNames.includes(key)))
|
|
28
|
+
throw Error("Choose only the supported app sections.");
|
|
29
|
+
for (const key of featureNames)
|
|
30
|
+
if (key in value.features) {
|
|
31
|
+
if (typeof value.features[key] !== "boolean")
|
|
32
|
+
throw Error("App section visibility must be on or off.");
|
|
33
|
+
result.features[key] = value.features[key];
|
|
34
|
+
}
|
|
35
|
+
}
|
|
36
|
+
return result;
|
|
37
|
+
}
|
|
@@ -1,6 +1,5 @@
|
|
|
1
1
|
/** Server-only broker. Never import this module into a browser bundle. */
|
|
2
2
|
import { createHash } from "node:crypto";
|
|
3
|
-
import { dialerCallHandedOff } from "./managedDialer.js";
|
|
4
3
|
export function createServerDialerBroker(sdk, authenticatedUserId) {
|
|
5
4
|
if (!authenticatedUserId.trim())
|
|
6
5
|
throw new Error("An authenticated user is required.");
|
|
@@ -20,10 +19,9 @@ export function createServerDialerBroker(sdk, authenticatedUserId) {
|
|
|
20
19
|
},
|
|
21
20
|
get: ownedCall,
|
|
22
21
|
async hangup(id) {
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
return sdk.telephony.calls.hangup(id);
|
|
22
|
+
await ownedCall(id);
|
|
23
|
+
// The provider rechecks handoff ownership in the stop CAS, after this read.
|
|
24
|
+
return sdk.telephony.calls.hangup(id, { user_id: authenticatedUserId });
|
|
27
25
|
},
|
|
28
26
|
async setHold(id, held, key) {
|
|
29
27
|
await ownedCall(id);
|
|
@@ -32,6 +30,13 @@ export function createServerDialerBroker(sdk, authenticatedUserId) {
|
|
|
32
30
|
const scopedKey = "dialer-hold:" + createHash("sha256").update(authenticatedUserId).update("\0").update(id).update("\0").update(key).digest("hex");
|
|
33
31
|
return sdk.telephony.calls.setHold(id, { held, user_id: authenticatedUserId }, { idempotencyKey: scopedKey });
|
|
34
32
|
},
|
|
33
|
+
async sendDtmf(id, digits, key) {
|
|
34
|
+
await ownedCall(id);
|
|
35
|
+
if (!key || key.length > 255 || /[\r\n]/.test(key))
|
|
36
|
+
throw new Error("A valid keypad retry key is required.");
|
|
37
|
+
const scopedKey = "dialer-keypad:" + createHash("sha256").update(authenticatedUserId).update("\0").update(id).update("\0").update(key).digest("hex");
|
|
38
|
+
return sdk.telephony.calls.sendDtmf(id, { digits, user_id: authenticatedUserId }, { idempotencyKey: scopedKey });
|
|
39
|
+
},
|
|
35
40
|
transfers: {
|
|
36
41
|
async create(id, input, key) {
|
|
37
42
|
await ownedCall(id);
|
package/dist/index.d.ts
CHANGED
|
@@ -105,7 +105,8 @@ export interface SpeechParams {
|
|
|
105
105
|
voice?: string;
|
|
106
106
|
model?: SpeakModel;
|
|
107
107
|
/**
|
|
108
|
-
* Delivery mode.
|
|
108
|
+
* Delivery mode. `speech` defaults to false; `speechStream` always uses true.
|
|
109
|
+
* The API itself defaults to true and every catalog voice accepts
|
|
109
110
|
* both values. Set false when you want one complete buffered body with a
|
|
110
111
|
* `Content-Length`. A voice whose serving fleet has no streaming lane is
|
|
111
112
|
* rendered buffered either way and says so with `x-pyai-stream: buffered`.
|
|
@@ -154,6 +155,10 @@ export type CreateJobParams = CreateJobOptions & ({
|
|
|
154
155
|
audio_url?: never;
|
|
155
156
|
});
|
|
156
157
|
export interface CreateJobOptions {
|
|
158
|
+
/** Spoken-language hint for every audio chunk; omit for automatic detection. */
|
|
159
|
+
transcription_language?: string;
|
|
160
|
+
/** Original script (default), or Roman letters preserving the spoken language; no translation. */
|
|
161
|
+
output_script?: "original" | "latin";
|
|
157
162
|
/** Requires Trace entitlement; incompatible with channel/diarize. */
|
|
158
163
|
trace?: boolean;
|
|
159
164
|
rule_pack?: Record<string, unknown>;
|
|
@@ -431,7 +436,7 @@ export interface HearStreamOptions {
|
|
|
431
436
|
/** Streaming STT model. Server default `pyai-hear`. */
|
|
432
437
|
model?: string;
|
|
433
438
|
/** Omit or use auto for automatic detection; an explicit code pins recognition. */
|
|
434
|
-
language?: "auto" | "en" | "es" | "fr" | "de" | "hi" | "it" | "pt" | "nl" | "zh" | "yue" | "ar" | "id" | "ko" | "th" | "vi" | "ja" | "tr" | "ms" | "sv" | "da" | "fi" | "pl" | "cs" | "fil" | "fa" | "el" | "hu" | "mk" | "ro";
|
|
439
|
+
language?: "auto" | "en" | "es" | "fr" | "de" | "hi" | "it" | "pt" | "nl" | "zh" | "yue" | "ar" | "id" | "ko" | "th" | "vi" | "ja" | "tr" | "ms" | "sv" | "da" | "fi" | "pl" | "cs" | "fil" | "fa" | "el" | "hu" | "mk" | "ro" | "ru";
|
|
435
440
|
/** Input PCM sample rate in Hz. Default 16000 server-side. */
|
|
436
441
|
sampleRate?: number;
|
|
437
442
|
/** Audio frame encoding. Default "pcm16". */
|
|
@@ -860,6 +865,15 @@ export interface TelephonyCall {
|
|
|
860
865
|
held?: boolean;
|
|
861
866
|
hold_pending?: boolean;
|
|
862
867
|
transfers?: TelephonyTransfer[];
|
|
868
|
+
forwarding?: {
|
|
869
|
+
to: string | null;
|
|
870
|
+
status: "waiting" | "claimed" | "unknown" | "acknowledged" | "canceled";
|
|
871
|
+
menu?: {
|
|
872
|
+
kind: "keypad";
|
|
873
|
+
status: "pending" | "selected" | "rejected";
|
|
874
|
+
choice_id: string | null;
|
|
875
|
+
};
|
|
876
|
+
};
|
|
863
877
|
user_id?: string;
|
|
864
878
|
client_reference: string | null;
|
|
865
879
|
stop_requested: boolean;
|
|
@@ -907,6 +921,13 @@ export interface TelephonyCallCapabilities {
|
|
|
907
921
|
};
|
|
908
922
|
revalidation_required: true;
|
|
909
923
|
}
|
|
924
|
+
export interface TelephonyCallControl {
|
|
925
|
+
object: "telephony.call_control";
|
|
926
|
+
id: string;
|
|
927
|
+
call_id: string;
|
|
928
|
+
action: "send_dtmf";
|
|
929
|
+
status: "acknowledged" | "unknown" | "rejected";
|
|
930
|
+
}
|
|
910
931
|
export interface TelephonyCallCreate {
|
|
911
932
|
from_number_id: string;
|
|
912
933
|
to: string;
|
|
@@ -958,6 +979,15 @@ export interface TelephonyAvailableNumber {
|
|
|
958
979
|
region?: string | null;
|
|
959
980
|
capabilities?: TelephonyCapabilities;
|
|
960
981
|
monthly_cost_cents?: number;
|
|
982
|
+
/** Bind purchase to the exact account/market inventory result. */
|
|
983
|
+
inventory_reference?: string;
|
|
984
|
+
}
|
|
985
|
+
export interface TelephonyNumberInventory extends ListResponse<TelephonyAvailableNumber> {
|
|
986
|
+
provisioning?: {
|
|
987
|
+
mode: "automated" | "assisted";
|
|
988
|
+
capability: string;
|
|
989
|
+
message: string;
|
|
990
|
+
};
|
|
961
991
|
}
|
|
962
992
|
export interface TelephonyNumber {
|
|
963
993
|
object?: "telephony.number";
|
|
@@ -980,7 +1010,7 @@ export interface TelephonyNumberOrder {
|
|
|
980
1010
|
id: string;
|
|
981
1011
|
status: "pending" | "unknown" | "completed" | "failed" | "released";
|
|
982
1012
|
phone_number: string;
|
|
983
|
-
country: "AU";
|
|
1013
|
+
country: "AU" | "US" | "CA";
|
|
984
1014
|
project_id: string;
|
|
985
1015
|
retry_after_seconds: number;
|
|
986
1016
|
message: string;
|
|
@@ -989,12 +1019,129 @@ export interface TelephonyNumberOrder {
|
|
|
989
1019
|
}
|
|
990
1020
|
export interface TelephonyNumberPurchase {
|
|
991
1021
|
phone_number: string;
|
|
1022
|
+
country?: "US" | "CA" | "IN" | "AU";
|
|
1023
|
+
inventory_reference?: string;
|
|
992
1024
|
agent_id?: string | null;
|
|
993
1025
|
provisioning_mode?: "automated" | "adopt_preowned";
|
|
994
1026
|
project_id?: string;
|
|
995
1027
|
compliance_case_id?: string;
|
|
996
1028
|
max_monthly_cost_cents?: number;
|
|
997
1029
|
}
|
|
1030
|
+
export interface TelephonyDesktopEndpoint {
|
|
1031
|
+
object: 'telephony.desktop_endpoint';
|
|
1032
|
+
id: string;
|
|
1033
|
+
project_id: string;
|
|
1034
|
+
user_id: string;
|
|
1035
|
+
actor_type: 'application';
|
|
1036
|
+
label: string;
|
|
1037
|
+
registered: boolean;
|
|
1038
|
+
available: boolean;
|
|
1039
|
+
number_id: string;
|
|
1040
|
+
status: 'active' | 'revoked';
|
|
1041
|
+
}
|
|
1042
|
+
export interface TelephonyDesktopEnrollment {
|
|
1043
|
+
object: 'telephony.desktop_enrollment';
|
|
1044
|
+
version: 1;
|
|
1045
|
+
endpoint_id: string;
|
|
1046
|
+
enrollment_token: string;
|
|
1047
|
+
expires_at: number;
|
|
1048
|
+
redeem_path: string;
|
|
1049
|
+
}
|
|
1050
|
+
export interface TelephonyDesktopCredentials {
|
|
1051
|
+
endpoint_id: string;
|
|
1052
|
+
org_id: string;
|
|
1053
|
+
project_id: string;
|
|
1054
|
+
user_id: string;
|
|
1055
|
+
label: string;
|
|
1056
|
+
refresh_token: string;
|
|
1057
|
+
refresh_expires_at: number;
|
|
1058
|
+
access_token: string;
|
|
1059
|
+
expires_at: number;
|
|
1060
|
+
presence_token: string;
|
|
1061
|
+
heartbeat_interval_seconds: 15;
|
|
1062
|
+
}
|
|
1063
|
+
export interface TelephonyInboundRingGroup {
|
|
1064
|
+
mode: 'simultaneous' | 'desktop_first';
|
|
1065
|
+
desktop_endpoint_ids: [string];
|
|
1066
|
+
external_to: string;
|
|
1067
|
+
desktop_timeout_seconds: number;
|
|
1068
|
+
ring_timeout_seconds: number;
|
|
1069
|
+
on_no_answer: 'hangup';
|
|
1070
|
+
max_duration_seconds: number;
|
|
1071
|
+
recording: boolean;
|
|
1072
|
+
}
|
|
1073
|
+
export interface TelephonyInboundCapabilities {
|
|
1074
|
+
object: 'telephony.inbound_capabilities';
|
|
1075
|
+
number_id: string;
|
|
1076
|
+
binding_version: number;
|
|
1077
|
+
ring_group: {
|
|
1078
|
+
supported: boolean;
|
|
1079
|
+
modes: Array<'simultaneous' | 'desktop_first'>;
|
|
1080
|
+
max_desktop_endpoints: 1;
|
|
1081
|
+
on_no_answer: ['hangup'];
|
|
1082
|
+
desktop_registration_required: true;
|
|
1083
|
+
};
|
|
1084
|
+
}
|
|
1085
|
+
export interface TelephonyInboundBinding {
|
|
1086
|
+
object: "telephony.inbound_binding";
|
|
1087
|
+
number_id: string;
|
|
1088
|
+
version: number;
|
|
1089
|
+
enabled: boolean;
|
|
1090
|
+
project_id?: string;
|
|
1091
|
+
agent_id?: string;
|
|
1092
|
+
agent_release_id?: string;
|
|
1093
|
+
agent_profile_sha256?: string;
|
|
1094
|
+
admission_mode?: "client" | "platform";
|
|
1095
|
+
forward?: TelephonyInboundForward | null;
|
|
1096
|
+
ring_group?: TelephonyInboundRingGroup | null;
|
|
1097
|
+
carrier_operation?: {
|
|
1098
|
+
id: string;
|
|
1099
|
+
phase: "pending" | "unknown" | "active" | "rollback_pending" | "rolled_back";
|
|
1100
|
+
action: "activate" | "rollback";
|
|
1101
|
+
};
|
|
1102
|
+
}
|
|
1103
|
+
export interface TelephonyInboundMenu {
|
|
1104
|
+
/** Saved single-digit spoken menu before forwarding. */
|
|
1105
|
+
kind: "keypad";
|
|
1106
|
+
prompt: string;
|
|
1107
|
+
choices: Array<{
|
|
1108
|
+
id: string;
|
|
1109
|
+
key: string;
|
|
1110
|
+
to: string;
|
|
1111
|
+
}>;
|
|
1112
|
+
timeout_seconds: number;
|
|
1113
|
+
/** null hangs up; otherwise the ID of one saved choice. */
|
|
1114
|
+
timeout_choice_id: string | null;
|
|
1115
|
+
}
|
|
1116
|
+
export type TelephonyInboundForward = {
|
|
1117
|
+
max_duration_seconds: number;
|
|
1118
|
+
recording: boolean;
|
|
1119
|
+
} & ({
|
|
1120
|
+
to: string;
|
|
1121
|
+
menu?: never;
|
|
1122
|
+
} | {
|
|
1123
|
+
to?: never;
|
|
1124
|
+
menu: TelephonyInboundMenu;
|
|
1125
|
+
});
|
|
1126
|
+
export type TelephonyInboundBindingUpdate = {
|
|
1127
|
+
expected_version: number;
|
|
1128
|
+
activate_carrier_route?: boolean;
|
|
1129
|
+
rollback_carrier_route?: boolean;
|
|
1130
|
+
/** Persist the original operation ID; recover it instead of inventing a new one. */
|
|
1131
|
+
carrier_operation_id?: string;
|
|
1132
|
+
} & ({
|
|
1133
|
+
enabled: false;
|
|
1134
|
+
} | {
|
|
1135
|
+
enabled: true;
|
|
1136
|
+
project_id: string;
|
|
1137
|
+
agent_id: string;
|
|
1138
|
+
agent_release_id: string;
|
|
1139
|
+
agent_profile_sha256: string;
|
|
1140
|
+
admission_mode?: "client" | "platform";
|
|
1141
|
+
agent_knowledge_receipt?: Record<string, unknown>;
|
|
1142
|
+
forward?: TelephonyInboundForward | null;
|
|
1143
|
+
ring_group?: TelephonyInboundRingGroup | null;
|
|
1144
|
+
});
|
|
998
1145
|
export type TraceVerdict = "PASS" | "WARN" | "FAIL";
|
|
999
1146
|
export type TraceSeverity = "low" | "medium" | "high" | "critical";
|
|
1000
1147
|
export interface TraceInteraction {
|
|
@@ -1442,7 +1589,7 @@ export declare class PyAI {
|
|
|
1442
1589
|
}>;
|
|
1443
1590
|
};
|
|
1444
1591
|
audio: {
|
|
1445
|
-
/** Text-to-speech. Returns
|
|
1592
|
+
/** Text-to-speech. Returns complete audio bytes (default WAV, stream:false). */
|
|
1446
1593
|
speech: (params: SpeechParams) => Promise<ArrayBuffer>;
|
|
1447
1594
|
/**
|
|
1448
1595
|
* Text-to-speech, streamed. Resolves as soon as the response headers arrive
|
|
@@ -1498,6 +1645,10 @@ export declare class PyAI {
|
|
|
1498
1645
|
filename: string;
|
|
1499
1646
|
call_id?: string;
|
|
1500
1647
|
diarize?: boolean;
|
|
1648
|
+
channel?: boolean;
|
|
1649
|
+
transcription_language?: string;
|
|
1650
|
+
output_script?: "original" | "latin";
|
|
1651
|
+
webhook_url?: string;
|
|
1501
1652
|
output_formats?: Array<"json" | "srt" | "vtt">;
|
|
1502
1653
|
}, opts: {
|
|
1503
1654
|
idempotencyKey: string;
|
|
@@ -1535,6 +1686,22 @@ export declare class PyAI {
|
|
|
1535
1686
|
};
|
|
1536
1687
|
telephony: {
|
|
1537
1688
|
/** Server-side methods. Keep the PyAI key in your backend. */
|
|
1689
|
+
desktopEndpoints: {
|
|
1690
|
+
list: (input?: {
|
|
1691
|
+
number_id?: string;
|
|
1692
|
+
}) => Promise<ListResponse<TelephonyDesktopEndpoint>>;
|
|
1693
|
+
create: (input: {
|
|
1694
|
+
number_id: string;
|
|
1695
|
+
user_id: string;
|
|
1696
|
+
client_reference: string;
|
|
1697
|
+
label: string;
|
|
1698
|
+
}) => Promise<TelephonyDesktopEndpoint>;
|
|
1699
|
+
enroll: (id: string, input: {
|
|
1700
|
+
user_id: string;
|
|
1701
|
+
}, options: {
|
|
1702
|
+
idempotencyKey: string;
|
|
1703
|
+
}) => Promise<TelephonyDesktopEnrollment>;
|
|
1704
|
+
};
|
|
1538
1705
|
calls: {
|
|
1539
1706
|
create: (input: TelephonyCallCreate, options: {
|
|
1540
1707
|
idempotencyKey: string;
|
|
@@ -1551,7 +1718,9 @@ export declare class PyAI {
|
|
|
1551
1718
|
next_cursor: string | null;
|
|
1552
1719
|
}>;
|
|
1553
1720
|
/** Durable stop intent; use get() until a terminal status is confirmed. */
|
|
1554
|
-
hangup: (id: string
|
|
1721
|
+
hangup: (id: string, input?: {
|
|
1722
|
+
user_id: string;
|
|
1723
|
+
}) => Promise<TelephonyCall>;
|
|
1555
1724
|
decideAdmission: (id: string, input: {
|
|
1556
1725
|
decision: "accept" | "reject";
|
|
1557
1726
|
client_reference: string;
|
|
@@ -1568,6 +1737,14 @@ export declare class PyAI {
|
|
|
1568
1737
|
}, options: {
|
|
1569
1738
|
idempotencyKey: string;
|
|
1570
1739
|
}) => Promise<TelephonyCall>;
|
|
1740
|
+
/** Server-side keypad command for an owned switch call. Reuse the same key
|
|
1741
|
+
* after an unknown result; never store keypad digits in a browser journal. */
|
|
1742
|
+
sendDtmf: (id: string, input: {
|
|
1743
|
+
digits: string;
|
|
1744
|
+
user_id: string;
|
|
1745
|
+
}, options: {
|
|
1746
|
+
idempotencyKey: string;
|
|
1747
|
+
}) => Promise<TelephonyCallControl>;
|
|
1571
1748
|
transfers: {
|
|
1572
1749
|
/** Persist the key and target before requesting a consultation. */
|
|
1573
1750
|
create: (id: string, input: {
|
|
@@ -1594,7 +1771,7 @@ export declare class PyAI {
|
|
|
1594
1771
|
areaCode?: string;
|
|
1595
1772
|
contains?: string;
|
|
1596
1773
|
limit?: number;
|
|
1597
|
-
}) => Promise<
|
|
1774
|
+
}) => Promise<TelephonyNumberInventory>;
|
|
1598
1775
|
/** List the org's managed numbers (active only unless `includeReleased`). */
|
|
1599
1776
|
list: (params?: {
|
|
1600
1777
|
includeReleased?: boolean;
|
|
@@ -1605,6 +1782,11 @@ export declare class PyAI {
|
|
|
1605
1782
|
}) => Promise<TelephonyNumber | TelephonyNumberOrder>;
|
|
1606
1783
|
/** Route a number to an agent (`agentId: null` to unassign). */
|
|
1607
1784
|
assign: (id: string, agentId: string | null) => Promise<TelephonyNumber>;
|
|
1785
|
+
getInboundCapabilities: (id: string) => Promise<TelephonyInboundCapabilities>;
|
|
1786
|
+
getInboundBinding: (id: string) => Promise<TelephonyInboundBinding>;
|
|
1787
|
+
/** Save the profile and stable operation first; after uncertainty read the
|
|
1788
|
+
* binding before explicitly recovering that same operation. */
|
|
1789
|
+
setInboundBinding: (id: string, input: TelephonyInboundBindingUpdate) => Promise<TelephonyInboundBinding>;
|
|
1608
1790
|
/** Release a number back to the carrier (idempotent). */
|
|
1609
1791
|
release: (id: string) => Promise<TelephonyNumber>;
|
|
1610
1792
|
};
|
package/dist/index.js
CHANGED
|
@@ -1029,13 +1029,13 @@ export class PyAI {
|
|
|
1029
1029
|
};
|
|
1030
1030
|
// --- audio --------------------------------------------------------------
|
|
1031
1031
|
audio = {
|
|
1032
|
-
/** Text-to-speech. Returns
|
|
1032
|
+
/** Text-to-speech. Returns complete audio bytes (default WAV, stream:false). */
|
|
1033
1033
|
speech: async (params) => {
|
|
1034
1034
|
assertActiveSpeechParams(params);
|
|
1035
1035
|
const res = await this.request("/v1/audio/speech", {
|
|
1036
1036
|
method: "POST",
|
|
1037
1037
|
headers: this.authHeaders({ "Content-Type": "application/json" }),
|
|
1038
|
-
body: JSON.stringify({ model: "pyai-speak", ...params }),
|
|
1038
|
+
body: JSON.stringify({ model: "pyai-speak", ...params, stream: params.stream ?? false }),
|
|
1039
1039
|
});
|
|
1040
1040
|
await validateSpeechResponse(res, params);
|
|
1041
1041
|
return res.arrayBuffer();
|
|
@@ -1123,6 +1123,14 @@ export class PyAI {
|
|
|
1123
1123
|
form.set("call_id", params.call_id);
|
|
1124
1124
|
if (params.diarize !== undefined)
|
|
1125
1125
|
form.set("diarize", String(params.diarize));
|
|
1126
|
+
if (params.channel !== undefined)
|
|
1127
|
+
form.set("channel", String(params.channel));
|
|
1128
|
+
if (params.transcription_language)
|
|
1129
|
+
form.set("transcription_language", params.transcription_language);
|
|
1130
|
+
if (params.output_script)
|
|
1131
|
+
form.set("output_script", params.output_script);
|
|
1132
|
+
if (params.webhook_url)
|
|
1133
|
+
form.set("webhook_url", params.webhook_url);
|
|
1126
1134
|
if (params.output_formats)
|
|
1127
1135
|
form.set("output_formats", params.output_formats.join(","));
|
|
1128
1136
|
form.set("audio", params.file, params.filename);
|
|
@@ -1180,6 +1188,11 @@ export class PyAI {
|
|
|
1180
1188
|
// --- telephony (managed numbers) ---------------------------------------
|
|
1181
1189
|
telephony = {
|
|
1182
1190
|
/** Server-side methods. Keep the PyAI key in your backend. */
|
|
1191
|
+
desktopEndpoints: {
|
|
1192
|
+
list: (input = {}) => this.getJson('/v1/telephony/desktop-endpoints' + (input.number_id ? '?' + new URLSearchParams({ number_id: input.number_id }) : '')),
|
|
1193
|
+
create: (input) => this.postJson('/v1/telephony/desktop-endpoints', input),
|
|
1194
|
+
enroll: (id, input, options) => this.postJson(`/v1/telephony/desktop-endpoints/${encodeURIComponent(id)}/enrollment`, input, telephonyIdempotencyHeader(options.idempotencyKey)),
|
|
1195
|
+
},
|
|
1183
1196
|
calls: {
|
|
1184
1197
|
create: (input, options) => this.postJson("/v1/telephony/calls", input, telephonyIdempotencyHeader(options.idempotencyKey)),
|
|
1185
1198
|
get: (id) => this.getJson(`/v1/telephony/calls/${encodeURIComponent(id)}`),
|
|
@@ -1193,12 +1206,19 @@ export class PyAI {
|
|
|
1193
1206
|
return this.getJson(`/v1/telephony/calls${query.size ? `?${query}` : ""}`);
|
|
1194
1207
|
},
|
|
1195
1208
|
/** Durable stop intent; use get() until a terminal status is confirmed. */
|
|
1196
|
-
hangup: (id) => this.postJson(`/v1/telephony/calls/${encodeURIComponent(id)}/hangup`, {}),
|
|
1209
|
+
hangup: (id, input) => this.postJson(`/v1/telephony/calls/${encodeURIComponent(id)}/hangup`, input ?? {}),
|
|
1197
1210
|
decideAdmission: (id, input) => this.postJson(`/v1/telephony/calls/${encodeURIComponent(id)}/admission`, input),
|
|
1198
1211
|
recording: (id, options = {}) => this.request(`/v1/telephony/calls/${encodeURIComponent(id)}/recording`, { headers: this.authHeaders(options.range ? { Range: options.range } : {}) }),
|
|
1199
1212
|
deleteRecording: async (id) => { await this.deleteReq(`/v1/telephony/calls/${encodeURIComponent(id)}/recording`); },
|
|
1200
1213
|
/** The same durable key recovers an uncertain hold command without repeating it. */
|
|
1201
1214
|
setHold: (id, input, options) => this.postJson(`/v1/telephony/calls/${encodeURIComponent(id)}/hold`, input, telephonyIdempotencyHeader(options.idempotencyKey)),
|
|
1215
|
+
/** Server-side keypad command for an owned switch call. Reuse the same key
|
|
1216
|
+
* after an unknown result; never store keypad digits in a browser journal. */
|
|
1217
|
+
sendDtmf: (id, input, options) => {
|
|
1218
|
+
if (!/^[0-9A-D*#]{1,32}$/.test(input.digits))
|
|
1219
|
+
throw new Error("Use 1–32 keypad digits (0–9, *, #, A–D).");
|
|
1220
|
+
return this.postJson(`/v1/telephony/calls/${encodeURIComponent(id)}/dtmf`, input, telephonyIdempotencyHeader(options.idempotencyKey));
|
|
1221
|
+
},
|
|
1202
1222
|
transfers: {
|
|
1203
1223
|
/** Persist the key and target before requesting a consultation. */
|
|
1204
1224
|
create: (id, input, options) => this.postJson(`/v1/telephony/calls/${encodeURIComponent(id)}/transfers`, input, telephonyIdempotencyHeader(options.idempotencyKey)),
|
|
@@ -1234,6 +1254,11 @@ export class PyAI {
|
|
|
1234
1254
|
buy: (params, options) => this.postJson("/v1/telephony/numbers", params, telephonyIdempotencyHeader(options.idempotencyKey)),
|
|
1235
1255
|
/** Route a number to an agent (`agentId: null` to unassign). */
|
|
1236
1256
|
assign: (id, agentId) => this.postJson(`/v1/telephony/numbers/${encodeURIComponent(id)}/assign`, { agent_id: agentId }),
|
|
1257
|
+
getInboundCapabilities: (id) => this.getJson(`/v1/telephony/numbers/${encodeURIComponent(id)}/inbound-capabilities`),
|
|
1258
|
+
getInboundBinding: (id) => this.getJson(`/v1/telephony/numbers/${encodeURIComponent(id)}/inbound-binding`),
|
|
1259
|
+
/** Save the profile and stable operation first; after uncertainty read the
|
|
1260
|
+
* binding before explicitly recovering that same operation. */
|
|
1261
|
+
setInboundBinding: (id, input) => this.putJson(`/v1/telephony/numbers/${encodeURIComponent(id)}/inbound-binding`, input),
|
|
1237
1262
|
/** Release a number back to the carrier (idempotent). */
|
|
1238
1263
|
release: async (id) => {
|
|
1239
1264
|
const res = await this.deleteReq(`/v1/telephony/numbers/${encodeURIComponent(id)}`);
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@pyai/sdk",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.18.0",
|
|
4
4
|
"description": "Official TypeScript/JavaScript SDK for PyAI, speech-to-text (Hear), text-to-speech (Speak), realtime voice agents (Omni), and call compliance (Trace).",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "dist/index.js",
|
package/src/cli-omni-template.ts
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
// Generated by scripts/generate-omni-starter.mjs; edit examples/omni-starter instead.
|
|
2
2
|
export const omniTemplate = Object.freeze({
|
|
3
|
-
"README.md": "# Runnable Omni starter\n\nRequires Node 20.19+ and ESM. Node 20 uses the included `ws` transport;\nNode 22 also works. The separate MCP server requires Node 22+.\nThis server-side example uses a synthetic read-only office-hours tool. Read\n`PYAI.md` when generating the project through the CLI.\n\n<!-- omni-install:start -->\n```sh\nnpm install @pyai/sdk@0.
|
|
4
|
-
"package.json": "{\n \"name\": \"pyai-omni-starter\",\n \"version\": \"0.0.0\",\n \"private\": true,\n \"type\": \"module\",\n \"engines\": {\n \"node\": \">=20.19.0\"\n },\n \"scripts\": {\n \"start\": \"node main.mjs\"\n },\n \"dependencies\": {\n \"@pyai/sdk\": \"0.
|
|
3
|
+
"README.md": "# Runnable Omni starter\n\nRequires Node 20.19+ and ESM. Node 20 uses the included `ws` transport;\nNode 22 also works. The separate MCP server requires Node 22+.\nThis server-side example uses a synthetic read-only office-hours tool. Read\n`PYAI.md` when generating the project through the CLI.\n\n<!-- omni-install:start -->\n```sh\nnpm install @pyai/sdk@0.18.0\nnpx pyai init voice-demo --template omni\ncd voice-demo\nnpm install\n```\n\nInitialization is offline; installing dependencies and running `main.mjs` are\nseparate steps. For an existing checkout of this example, run `npm install`\nin its directory instead.\n<!-- omni-install:end -->\n\nInject `PYAI_API_KEY` through your secret manager or shell environment. Do not\npaste a real key into source, a prompt, or shell history. `.env.example` documents\nthe variable; this program does not load `.env` or saved CLI profiles.\n\nPrepare a 24 kHz PCM16 mono WAV, at most 20 seconds, saying “Please look up the\noffice opening time.” Then run:\n\n```sh\nnode main.mjs caller.wav\n```\n\nRunning the program explicitly opens one bounded Omni session and uploads its\ncaptured reply to Hear. Both consume your key's allowed usage. Automatic retries\nare disabled. No managed number is bought and no phone call is placed.\n\n`session.mjs` waits for configuration and the greeting to drain, sends exactly\none paced input stream (caller PCM or silence), returns the read tool's result,\nand captures output using the rate from `hello.audio_out`. Never run a separate\nsilence timer alongside caller audio. `timing.mjs` is generated from the existing\nOmni evaluation harness's timing utilities.\n\nThe new private `omni-run-*` folder contains `session.wav`, `reply.wav`, and\n`report.json`. The report separates received audio, an office-hours answer\nrecovered by Hear from captured audio, and physical playback (not tested).\nThe office-hours check accepts formatting such as `opens@9a.m`, `9 a.m.` and\n`nine in the morning` in a complete affirmative opening-time sentence. Wrong\ntimes, negation, conflicting or truncated text remain unverified. This is a\nconservative check for the example fact, not a general answer-quality score.\nA synthesis transcript is advisory; it is not evidence that speech arrived.\nThis starter does not negotiate playback receipts. Capture ends after the\nsimulated queue drains and two seconds of quiet, a bounded capture heuristic.\nListen to the saved file when qualifying actual sound quality or completeness.\n\nTo exercise interruption, supply a second WAV saying “Stop speaking now”:\n\n```sh\nnode main.mjs caller.wav interruption.wav\n```\n\nThe second clip starts while reply audio is queued. `onBargeIn` clears that\nsimulated queue, and capture observes at least five seconds after that clip ends.\nAn interrupted answer can correctly fail the full-answer check;\ninspect the separate interruption evidence. This is not a physical speaker test.\nFor a real playback adapter, cancel both queued and currently playing audio.\nReplace the example lookup with authorized application data before product use.\n\nOn a session error, the program exits with JSON containing a recognized machine\n`code` (for example `media_dead` or `invalid_configure`). Unknown server codes\nbecome `unrecognized_server_error`; transport or decoding errors without a\nrecognized transport code become `transport_or_protocol_error`. Raw error text,\ncall IDs and unknown code values are omitted. No automatic retry is attempted;\ninspect the code and your authorized diagnostics before deciding to retry.\n",
|
|
4
|
+
"package.json": "{\n \"name\": \"pyai-omni-starter\",\n \"version\": \"0.0.0\",\n \"private\": true,\n \"type\": \"module\",\n \"engines\": {\n \"node\": \">=20.19.0\"\n },\n \"scripts\": {\n \"start\": \"node main.mjs\"\n },\n \"dependencies\": {\n \"@pyai/sdk\": \"0.18.0\",\n \"ws\": \"^8.18.3\"\n }\n}\n",
|
|
5
5
|
"timing.mjs": "// Monotonic capture timing. Arrival time is distinct from queued playback:\n// a single packet may contain seconds of audio and must finish before settling.\nexport const FRAME_MS = 20;\nexport const REALTIME_GAP_LIMIT_MS = 100;\n// Interruption tests need an observation window after caller transmission,\n// even when an earlier cue/response already finished. These are test bounds,\n// not an inferred engine reply-end or a naturalness threshold.\nexport const INTERRUPTION_OBSERVATION = Object.freeze({\n minimumAfterCallerStreamMs: 5000, quietMs: 2000, maximumAfterCallerStreamMs: 25000,\n});\n\n/** Approximate audible bounds; this is energy detection, not a speech/VAD claim. */\nexport function audibleBounds(pcm, rate, rmsFloor = 160) {\n const window = Math.max(1, Math.round(rate / 100)); // 10 ms windows\n let first = null;\n let last = null;\n for (let off = 0; off < pcm.length; off += window) {\n const end = Math.min(pcm.length, off + window);\n let energy = 0;\n for (let i = off; i < end; i++) energy += pcm[i] * pcm[i];\n if (Math.sqrt(energy / (end - off)) >= rmsFloor) {\n first ??= off;\n last = end;\n }\n }\n return { first, last };\n}\n\nexport function newAudioCapture(started) {\n return {\n started, firstPacketAt: null, lastPacketAt: null,\n firstAudioAt: null, lastAudioAt: null, playbackEndAt: null,\n samples: 0, pcm: [], turnBeginAt: null, eouMs: null,\n latestTurnBeginAt: null, postTurnBeginFirstPacketAt: null,\n postTurnBeginFirstAudioAt: null, lastAssistantTranscriptAt: null, lastCallerTranscriptAt: null,\n callerTranscriptEvents: [], assistantTranscriptEvents: [],\n turnBegins: [], unheardCancellations: [], unheardSupersededTurns: [], tools: [], toolResults: [], kb: null, events: [],\n };\n}\n\nexport function recordTurnBegin(ctx, at, turn, origin = 0) {\n const prior = ctx.turnBegins.at(-1);\n const cancellation = ctx.unheardCancellations.at(-1);\n if (prior && cancellation && !cancellation.admitted\n && cancellation.turn === prior.turn && cancellation.turnBeginIndex === ctx.turnBegins.length - 1\n && Number.isSafeInteger(turn) && turn > prior.turn && at > cancellation.at\n && ctx.samples === 0 && ctx.assistantTranscriptEvents.length === 0\n && ctx.tools.length === 0 && ctx.toolResults.length === 0) {\n cancellation.admitted = true;\n ctx.unheardSupersededTurns.push({ turn: prior.turn, beginAtMs: prior.atMs,\n cancelledAtMs: cancellation.atMs, cancellationEventIndex: cancellation.eventIndex,\n replacementTurn: turn, outputPacketsBeforeReplacement: 0 });\n }\n ctx.turnBeginAt ??= at;\n ctx.latestTurnBeginAt = at;\n // Earlier PCM can be a listening cue. A new reply is still pending even\n // when that cue has already finished playing; retain all of its PCM.\n ctx.postTurnBeginFirstPacketAt = null;\n ctx.postTurnBeginFirstAudioAt = null;\n ctx.turnBegins.push({ atMs: Math.round(at - origin), turn: turn ?? null });\n}\n\nexport function recordUnheardCancellation(ctx, event, at, origin, eventIndex) {\n const prior = ctx.turnBegins.at(-1);\n if (event.event !== \"flush\" || event.reason !== \"turn_merge\"\n || !Number.isSafeInteger(event.cancelled_turn) || event.cancelled_turn <= 0\n || prior?.turn !== event.cancelled_turn || at < ctx.latestTurnBeginAt\n || ctx.samples !== 0 || ctx.assistantTranscriptEvents.length\n || ctx.tools.length || ctx.toolResults.length\n || ctx.unheardCancellations.some(c => c.turnBeginIndex === ctx.turnBegins.length - 1)) return;\n ctx.unheardCancellations.push({ turn: event.cancelled_turn, at,\n atMs: Math.round(at - origin), eventIndex, turnBeginIndex: ctx.turnBegins.length - 1,\n admitted: false });\n}\n\nexport function recordAudio(ctx, pcm, at, rate) {\n if (!(pcm instanceof Int16Array) || !pcm.length) return null;\n const copy = pcm.slice(); // Some transports reuse callback buffers.\n const playbackAt = Math.max(at, ctx.playbackEndAt ?? at);\n const endAt = playbackAt + (copy.length / rate) * 1000;\n const bounds = audibleBounds(copy, rate);\n ctx.firstPacketAt ??= at;\n ctx.lastPacketAt = at;\n ctx.playbackEndAt = endAt;\n const afterTurnBegin = ctx.latestTurnBeginAt != null && at >= ctx.latestTurnBeginAt;\n if (afterTurnBegin) ctx.postTurnBeginFirstPacketAt ??= at;\n if (bounds.first != null) {\n ctx.firstAudioAt ??= playbackAt + (bounds.first / rate) * 1000;\n ctx.lastAudioAt = playbackAt + (bounds.last / rate) * 1000;\n if (afterTurnBegin) ctx.postTurnBeginFirstAudioAt ??= playbackAt + (bounds.first / rate) * 1000;\n }\n ctx.samples += copy.length;\n ctx.pcm.push(copy);\n return { playbackAt, endAt, pcm: copy };\n}\n\n/** Preserve negative gaps: they are overlaps, never missing measurements. */\nexport function captureTiming(ctx, caller, origin = 0) {\n const relative = (at) => at == null ? null : Math.round(at - origin);\n const gap = (at) => at == null || caller.speechOffsetAt == null\n ? null : Math.round(at - caller.speechOffsetAt);\n return {\n ttfbMs: gap(ctx.firstAudioAt),\n anyAudioTtfbMs: gap(ctx.firstAudioAt),\n postTurnBeginTtfbMs: gap(ctx.postTurnBeginFirstAudioAt),\n turnMs: gap(ctx.lastAudioAt),\n packetTtfbMs: gap(ctx.firstPacketAt),\n callerStartMs: relative(caller.startedAt),\n callerSpeechOnsetMs: relative(caller.speechOnsetAt),\n callerSpeechOffsetMs: relative(caller.speechOffsetAt),\n callerStreamEndMs: relative(caller.streamEndAt),\n agentFirstPacketMs: relative(ctx.firstPacketAt),\n agentLastPacketMs: relative(ctx.lastPacketAt),\n agentSpeechOnsetMs: relative(ctx.firstAudioAt),\n agentSpeechOffsetMs: relative(ctx.lastAudioAt),\n agentPlaybackEndMs: relative(ctx.playbackEndAt),\n latestTurnBeginMs: relative(ctx.latestTurnBeginAt),\n postTurnBeginFirstPacketMs: relative(ctx.postTurnBeginFirstPacketAt),\n postTurnBeginSpeechOnsetMs: relative(ctx.postTurnBeginFirstAudioAt),\n lastAssistantTranscriptMs: relative(ctx.lastAssistantTranscriptAt),\n callerMaxFrameGapMs: Math.round(caller.maxFrameGapMs ?? 0),\n method: \"client-monotonic-queued-playback-energy-bounds\",\n };\n}\n\nexport async function streamPcmRealtime(omni, pcm, rate, clock, onFrame = () => {}) {\n const frameSize = Math.max(1, Math.round((rate * FRAME_MS) / 1000));\n const bounds = audibleBounds(pcm, rate);\n const startedAt = clock.now();\n let speechOnsetAt = null;\n let speechOffsetAt = null;\n let previousFrameEnd = startedAt;\n let maxFrameGapMs = 0;\n for (let off = 0; off < pcm.length; off += frameSize) {\n const frame = pcm.subarray(off, Math.min(off + frameSize, pcm.length));\n const at = clock.now();\n maxFrameGapMs = Math.max(maxFrameGapMs, at - previousFrameEnd);\n const durationMs = (frame.length / rate) * 1000;\n omni.sendAudio(frame);\n onFrame(frame, at);\n if (bounds.first != null && bounds.first >= off && bounds.first < off + frame.length) {\n speechOnsetAt = at + ((bounds.first - off) / rate) * 1000;\n }\n if (bounds.last != null && bounds.last > off && bounds.last <= off + frame.length) {\n speechOffsetAt = at + ((bounds.last - off) / rate) * 1000;\n }\n previousFrameEnd = at + durationMs;\n // Pace from the actual send. Never burst late frames to \"catch up\".\n await clock.sleep(Math.max(0, previousFrameEnd - clock.now()));\n }\n return { startedAt, speechOnsetAt, speechOffsetAt,\n streamEndAt: clock.now(), maxFrameGapMs };\n}\n\nexport async function streamSilenceWhile(omni, rate, shouldContinue, clock, onFrame = () => {}) {\n const silence = new Int16Array(Math.max(1, Math.round((rate * FRAME_MS) / 1000)));\n while (shouldContinue()) {\n const at = clock.now();\n omni.sendAudio(silence);\n onFrame(silence, at);\n await clock.sleep(FRAME_MS);\n }\n}\n\nexport async function waitForAgentSettle(getCtx, clock, opts = {}) {\n const started = clock.now();\n const observation = opts.callerStreamEndAt != null;\n if (observation && (!Number.isFinite(opts.callerStreamEndAt)\n || opts.callerStreamEndAt < 0 || opts.callerStreamEndAt > started)) {\n throw new Error(\"Invalid caller observation boundary\");\n }\n const timeoutMs = observation ? INTERRUPTION_OBSERVATION.maximumAfterCallerStreamMs : opts.timeoutMs ?? 25000;\n const settleMs = observation ? INTERRUPTION_OBSERVATION.quietMs : opts.settleMs ?? 2000;\n const deadlineAt = (observation ? opts.callerStreamEndAt : started) + timeoutMs;\n const minimumAt = observation ? opts.callerStreamEndAt + INTERRUPTION_OBSERVATION.minimumAfterCallerStreamMs : -Infinity;\n while (true) {\n const ctx = getCtx();\n const at = clock.now();\n if (opts.isClosed?.()) return { reason: \"closed\", at };\n if (observation && at >= deadlineAt) return { reason: \"timeout\", at };\n const hasResponseAudio = !opts.requireTurnBegin || (ctx.latestTurnBeginAt != null\n && ctx.postTurnBeginFirstAudioAt != null);\n // Synthesis text is progress, not a completion event. It can arrive after\n // early/final audio, so extend the quiet floor without demanding another\n // packet after every advisory. The protocol still has no reply-end marker.\n const activityEnd = Math.max(ctx.playbackEndAt ?? -Infinity,\n ctx.latestTurnBeginAt ?? -Infinity, ctx.lastAssistantTranscriptAt ?? -Infinity,\n observation ? ctx.lastCallerTranscriptAt ?? -Infinity : -Infinity);\n // Do not demand a new post-caller turn_begin: an earlier turn can be\n // coalesced and speak later. This records a bounded quiet observation;\n // downstream response-timing checks can impose a stricter begin boundary.\n if (ctx.firstPacketAt != null && hasResponseAudio && at >= minimumAt && at >= activityEnd + settleMs) {\n return { reason: \"settled\", at };\n }\n if (opts.allowEmpty && ctx.firstPacketAt == null && at >= minimumAt && at - started >= (opts.emptyWaitMs ?? 800)) {\n return { reason: \"empty\", at };\n }\n if (at - started >= timeoutMs) return { reason: \"timeout\", at };\n await clock.sleep(observation ? Math.min(20, deadlineAt - at) : 20);\n }\n}\n\nexport async function withTimeout(promise, ms, message, clock) {\n let timer;\n try {\n return await Promise.race([\n promise,\n new Promise((_, reject) => {\n timer = clock.setTimeout(() => reject(new Error(message)), ms);\n }),\n ]);\n } finally {\n clock.clearTimeout(timer);\n }\n}\n",
|
|
6
6
|
"main.mjs": "import PyAI from \"@pyai/sdk\";\nimport WebSocket from \"ws\"; // Explicit transport makes this work on Node 20 too.\nimport { readFile, writeFile, mkdtemp } from \"node:fs/promises\";\nimport { join } from \"node:path\";\nimport { runSession } from \"./session.mjs\";\nimport { readWav, writeWav, assessAnswer } from \"./audio.mjs\";\n\nasync function main() {\n const [callerPath, interruptionPath, extra] = process.argv.slice(2);\n if (!callerPath || extra) throw new Error(\"Usage: node main.mjs caller.wav [interruption.wav]\");\n if (!process.env.PYAI_API_KEY) throw new Error(\"Inject PYAI_API_KEY through your environment first\");\n const caller = readWav(await readFile(callerPath));\n const interruption = interruptionPath ? readWav(await readFile(interruptionPath)) : undefined;\n const pyai = new PyAI({ apiKey: process.env.PYAI_API_KEY, maxRetries: 0,\n fetch: (url, options) => fetch(url, { ...options, signal: AbortSignal.timeout(30000) }),\n });\n const { report, audio, replyAudio } = await runSession({ pyai, webSocket: WebSocket, caller, interruption });\n const directory = await mkdtemp(join(process.cwd(), \"omni-run-\"));\n const save = (name, data) => writeFile(join(directory, name), data, { mode: 0o600, flag: \"wx\" });\n await save(\"session.wav\", writeWav(audio, report.output_rate ?? 24000));\n const reply = writeWav(replyAudio, report.output_rate ?? 24000);\n await save(\"reply.wav\", reply);\n // Hear the captured bytes, rather than trusting synthesis-advisory text.\n let capturedTranscript = \"\";\n if (report.reply_audio_bytes) {\n try {\n const heard = await pyai.audio.transcriptions.create({ file: new File([reply], \"reply.wav\", { type: \"audio/wav\" }), model: \"pyai-hear\" });\n capturedTranscript = heard.text;\n } catch { report.hear_error = \"Captured audio saved; Hear verification failed\"; }\n }\n const result = { ...report, captured_transcript: capturedTranscript, evidence: assessAnswer(report, capturedTranscript) };\n await save(\"report.json\", JSON.stringify(result, null, 2) + \"\\n\");\n console.log(JSON.stringify({ directory, ...result }, null, 2));\n if (result.evidence.captured_answer !== \"verified_by_hear\" || (interruption && result.evidence.interruption !== \"simulated_queue_cleared\")) process.exitCode = 1;\n}\n\nmain().catch(error => {\n const message = String(error.message).replaceAll(process.env.PYAI_API_KEY || \"\\0\", \"[REDACTED]\");\n console.error(JSON.stringify({ error: message, ...(error.omni_code ? { code: error.omni_code } : {}) })); process.exitCode = 1;\n});\n",
|
|
7
7
|
"session.mjs": "import { newAudioCapture, recordAudio, recordTurnBegin, streamPcmRealtime, INTERRUPTION_OBSERVATION } from \"./timing.mjs\";\n\nexport const realClock = {\n now: () => performance.now(),\n sleep: ms => new Promise(resolve => setTimeout(resolve, ms)),\n};\n\n// Only recognized machine codes may leave the example. Error messages, call\n// IDs and arbitrary code values can contain credentials or customer content.\nconst publicErrorCodes = new Set([\n \"invalid_configure\", \"unsupported_tool_transport\", \"tool_configuration_locked\",\n \"media_dead\", \"unauthorized\", \"insufficient_scope\", \"rate_limit_exceeded\",\n \"concurrency_limit_exceeded\", \"daily_cap_exceeded\", \"credit_exhausted\",\n]);\nconst transportErrorCodes = new Set([\"ECONNRESET\", \"ECONNREFUSED\", \"ETIMEDOUT\", \"ENOTFOUND\", \"EAI_AGAIN\"]);\nexport function omniFailure(error) {\n const code = error instanceof Error\n ? (transportErrorCodes.has(error.code) ? error.code : \"transport_or_protocol_error\")\n : (publicErrorCodes.has(error?.code) ? error.code : \"unrecognized_server_error\");\n return Object.assign(new Error(`Omni failed (${code}); no automatic retry was attempted`), { omni_code: code });\n}\n\n/** One bounded, server-side example. Its playback queue is simulated. */\nexport async function runSession({ pyai, webSocket, caller, interruption, clock = realClock, timeoutMs = 60000 }) {\n const rate = 24000, frameSize = 480, silence = new Int16Array(frameSize);\n if (!(caller instanceof Int16Array) || !caller.length || caller.length > rate * 20) throw new Error(\"Provide 1–20 seconds of caller PCM16 at 24 kHz\");\n if (interruption && (!(interruption instanceof Int16Array) || !interruption.length || interruption.length > rate * 20)) throw new Error(\"Invalid interruption PCM\");\n const started = clock.now(), all = newAudioCapture(started), reply = newAudioCapture(started);\n const report = { input_rate: rate, output_rate: null, playback_sink: \"simulated\", tool_calls: 0, tool_executions: 0, duplicate_tool_calls: 0, flushes_after_interruption: 0, cleared_queue_ms: 0, interruption_requested: !!interruption, caller_started_ms: null, interruption_started_ms: null, advisory_transcripts: [], end_reason: \"timeout\" };\n let session, configuredAt = null, closed = false, failure = null, phase = \"greeting\", offset = 0, queueEnd = started, interruptionSent = false, inputEndAt = started;\n const handled = new Set();\n const fail = message => { failure ??= new Error(message); };\n try {\n session = pyai.omni.connect({\n webSocket, rate,\n configure: {\n voice_id: \"stock_amos_en_us\", language: \"en\", greeting: \"Hello. How can I help?\",\n persona: \"When asked about office hours, call lookup_office_hours. Never guess. After the result, say one short sentence giving its opening_time.\",\n tools: [{ name: \"lookup_office_hours\", description: \"Read the synthetic example office opening time.\", side_effect: \"read\", parameters: { type: \"object\", properties: {}, required: [], additionalProperties: false } }],\n },\n onHello: frame => {\n const match = /^pcm16@(8000|24000)$/.exec(frame.audio_out ?? \"\");\n if (!match) return fail(\"Unsupported Omni output format\");\n report.output_rate = Number(match[1]);\n },\n onConfigured: () => { configuredAt ??= clock.now(); },\n onAudio: chunk => {\n if (!report.output_rate) return fail(\"Audio arrived before its output format\");\n const bytes = chunk instanceof ArrayBuffer ? new Uint8Array(chunk) : new Uint8Array(chunk.buffer, chunk.byteOffset, chunk.byteLength);\n if (bytes.byteLength % 2) return fail(\"Invalid PCM16 output\");\n const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);\n const pcm = Int16Array.from({ length: bytes.length / 2 }, (_, i) => view.getInt16(i * 2, true));\n const now = clock.now();\n recordAudio(all, pcm, now, report.output_rate);\n queueEnd = Math.max(now, queueEnd) + pcm.length / report.output_rate * 1000;\n if (report.tool_executions) recordAudio(reply, pcm, now, report.output_rate);\n },\n onEvent: frame => {\n if (frame.event === \"turn_begin\") recordTurnBegin(all, clock.now(), frame.turn);\n },\n onTranscript: frame => {\n // An assistant advisory is progress; never treat it as received speech.\n if (report.advisory_transcripts.length < 100) report.advisory_transcripts.push({ role: frame.role, text: frame.text });\n if (frame.role === \"assistant\") all.lastAssistantTranscriptAt = clock.now();\n },\n onToolCall: frame => {\n report.tool_calls++;\n if (handled.has(frame.call_id)) { report.duplicate_tool_calls++; return; }\n handled.add(frame.call_id);\n if (frame.name !== \"lookup_office_hours\") { session.toolResult(frame.call_id, { error: \"Unknown example tool\" }); return; }\n // Replace this read-only fixture with your authorized data lookup.\n report.tool_executions++;\n session.toolResult(frame.call_id, { result: { opening_time: \"9 a.m.\", source: \"synthetic example office\" } });\n },\n onBargeIn: () => {\n const now = clock.now(), queued = Math.max(0, queueEnd - now);\n if (report.interruption_started_ms != null) { report.flushes_after_interruption++; report.cleared_queue_ms += queued; }\n // A real speaker adapter must cancel scheduled and currently playing audio.\n queueEnd = now; all.playbackEndAt = now; reply.playbackEndAt = now;\n },\n onError: error => { failure ??= omniFailure(error); },\n onClose: () => { closed = true; },\n });\n while (clock.now() - started < timeoutMs) {\n if (failure) throw failure;\n if (closed) { report.end_reason = \"closed\"; break; }\n const now = clock.now();\n if (configuredAt == null || !report.output_rate) {\n if (now - started >= 10000) throw new Error(\"Omni connection/configuration timed out\");\n await clock.sleep(20); continue;\n }\n const quietAt = Math.max(queueEnd, all.lastPacketAt ?? now, all.lastAssistantTranscriptAt ?? 0, inputEndAt);\n if (phase === \"greeting\") {\n if (all.firstPacketAt != null && now - configuredAt >= 2000 && now >= quietAt + 800) {\n phase = \"caller\"; report.caller_started_ms = now - started;\n } else if (now - configuredAt > 15000) throw new Error(\"Greeting did not drain within 15 seconds\");\n }\n if (phase === \"reply\" && interruption && !interruptionSent && reply.samples && queueEnd - now >= 200) {\n phase = \"interruption\"; offset = 0; interruptionSent = true; report.interruption_started_ms = now - started;\n }\n const observationEnd = inputEndAt + (interruptionSent ? INTERRUPTION_OBSERVATION.minimumAfterCallerStreamMs : 0);\n if (phase === \"reply\" && reply.samples && now >= quietAt + 2000 && now >= observationEnd && (!interruption || interruptionSent)) {\n report.end_reason = \"quiet_window\"; break;\n }\n // Exactly one producer: each 20 ms slot contains caller PCM OR silence.\n let pcm = silence;\n if (phase === \"caller\" || phase === \"interruption\") {\n const source = phase === \"caller\" ? caller : interruption;\n pcm = source.subarray(offset, offset + frameSize); offset += pcm.length;\n if (offset >= source.length) {\n inputEndAt = now + pcm.length / rate * 1000;\n report[phase === \"caller\" ? \"caller_completed_ms\" : \"interruption_completed_ms\"] = inputEndAt - started;\n phase = \"reply\"; offset = 0;\n }\n }\n await streamPcmRealtime(session, pcm, rate, clock);\n }\n report.audio_bytes = all.samples * 2;\n report.reply_audio_bytes = reply.samples * 2;\n report.elapsed_ms = Math.round(clock.now() - started);\n return { report, audio: all.pcm, replyAudio: reply.pcm };\n } finally { session?.close(); }\n}\n",
|