@pyai/sdk 0.12.0 → 0.14.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.
Files changed (48) hide show
  1. package/CLI.schema.json +2 -1
  2. package/README.md +58 -6
  3. package/dist/cli-omni-template.d.ts +2 -2
  4. package/dist/cli-omni-template.js +2 -2
  5. package/dist/cli-web-auth.d.ts +2 -0
  6. package/dist/cli-web-auth.js +2 -0
  7. package/dist/cli.js +2 -2
  8. package/dist/dialer/appServer.d.ts +4 -0
  9. package/dist/dialer/appServer.js +84 -4
  10. package/dist/dialer/dialerElement.js +28 -6
  11. package/dist/dialer/dialingQueue.d.ts +33 -10
  12. package/dist/dialer/dialingQueue.js +124 -41
  13. package/dist/dialer/fileMeetingIntelligenceJournal.d.ts +14 -0
  14. package/dist/dialer/fileMeetingIntelligenceJournal.js +147 -0
  15. package/dist/dialer/index.d.ts +1 -0
  16. package/dist/dialer/index.js +1 -0
  17. package/dist/dialer/indexedDbJournal.d.ts +9 -0
  18. package/dist/dialer/indexedDbJournal.js +62 -1
  19. package/dist/dialer/managedDialer.d.ts +40 -2
  20. package/dist/dialer/managedDialer.js +137 -10
  21. package/dist/dialer/meetingIntelligence.d.ts +28 -0
  22. package/dist/dialer/meetingIntelligence.js +3 -0
  23. package/dist/dialer/meetingIntelligenceElement.d.ts +21 -0
  24. package/dist/dialer/meetingIntelligenceElement.js +112 -0
  25. package/dist/dialer/serverBroker.js +19 -2
  26. package/dist/dialer/serverMeetingIntelligence.d.ts +60 -0
  27. package/dist/dialer/serverMeetingIntelligence.js +207 -0
  28. package/dist/index.d.ts +40 -0
  29. package/dist/index.js +24 -0
  30. package/package.json +9 -1
  31. package/src/cli-omni-template.ts +2 -2
  32. package/src/cli-web-auth.ts +3 -0
  33. package/src/cli.ts +2 -2
  34. package/src/dialer/MEETING_INTELLIGENCE.md +76 -0
  35. package/src/dialer/app/app.html +3 -3
  36. package/src/dialer/app/app.js +45 -16
  37. package/src/dialer/appServer.ts +63 -5
  38. package/src/dialer/dialerElement.ts +24 -5
  39. package/src/dialer/dialingQueue.ts +108 -45
  40. package/src/dialer/fileMeetingIntelligenceJournal.ts +77 -0
  41. package/src/dialer/index.ts +2 -0
  42. package/src/dialer/indexedDbJournal.ts +58 -1
  43. package/src/dialer/managedDialer.ts +115 -9
  44. package/src/dialer/meetingIntelligence.ts +21 -0
  45. package/src/dialer/meetingIntelligenceElement.ts +65 -0
  46. package/src/dialer/serverBroker.ts +17 -2
  47. package/src/dialer/serverMeetingIntelligence.ts +148 -0
  48. package/src/index.ts +37 -1
@@ -0,0 +1,148 @@
1
+ /** Server-only. Bind one broker to a trusted org/user and an existing project
2
+ * key. Never fall back to an operator/parent key or change that key's grants. */
3
+ import { createHash } from "node:crypto";
4
+ import type { MeResponse, PyAI, RecapCall, TranscriptionJob } from "../index.ts";
5
+ import type { MeetingIntelligenceBroker, MeetingIntelligenceView } from "./meetingIntelligence.ts";
6
+
7
+ export interface MeetingIntelligenceApi {
8
+ me(): Promise<MeResponse>;
9
+ recapEnabled(): Promise<boolean>;
10
+ upload(audio: Blob, filename: string, callId: string, key: string): Promise<TranscriptionJob>;
11
+ job(id: string): Promise<TranscriptionJob>;
12
+ recap(id: string): Promise<RecapCall | null>;
13
+ cancel(id: string): Promise<TranscriptionJob>;
14
+ }
15
+ export class MeetingApiError extends Error {
16
+ readonly status: number;
17
+ constructor(status: number) { super(`PyAI meeting request failed (${status}).`); this.status = status; }
18
+ }
19
+ /** Uses only public routes. Keyed multipart requires the durable job retry contract; no public bucket,
20
+ * arbitrary result_url fetch, or browser-held key is involved. */
21
+ export function createPyaiMeetingApi(options: { apiKey: string; baseURL?: string; fetch?: typeof fetch; timeoutMs?: number }): MeetingIntelligenceApi {
22
+ const base = new URL(options.baseURL ?? "https://api.pyai.com");
23
+ if ((base.protocol !== "https:" && !(base.protocol === "http:" && ["127.0.0.1", "[::1]"].includes(base.hostname))) || base.username || base.password || base.search || base.hash || base.pathname !== "/") throw new Error("Use a trusted HTTPS API origin.");
24
+ if (!options.apiKey || /[\r\n]/.test(options.apiKey)) throw new Error("An existing project key is required.");
25
+ const timeout = options.timeoutMs ?? 20000;
26
+ if (!Number.isInteger(timeout) || timeout < 1 || timeout > 60000) throw new Error("Meeting requests require a deadline of 1–60000 ms.");
27
+ const request = async <T>(path: string, method = "GET", input?: unknown, key?: string): Promise<T> => {
28
+ const response = await (options.fetch ?? fetch)(new URL(path, base), { method, redirect: "error", signal: AbortSignal.timeout(timeout),
29
+ headers: { Authorization: `Bearer ${options.apiKey}`, ...(input !== undefined && !(input instanceof FormData) ? { "content-type": "application/json" } : {}), ...(key ? { "Idempotency-Key": key } : {}) },
30
+ ...(input !== undefined ? { body: input instanceof FormData ? input : JSON.stringify(input) } : {}) });
31
+ if (!response.ok) { await response.body?.cancel(); throw new MeetingApiError(response.status); }
32
+ // Avoid unbounded or attacker-selected artifact downloads. Recap supplies
33
+ // retained transcript text even when Hear returns only a signed result URL.
34
+ const reader = response.body?.getReader(); if (!reader) throw new Error("PyAI returned an empty response.");
35
+ const chunks: Uint8Array[] = []; let bytes = 0;
36
+ try { while (true) { const chunk = await reader.read(); if (chunk.done) break; bytes += chunk.value.length; if (bytes > 4 * 1024 * 1024) throw new Error("Meeting response exceeds 4 MiB."); chunks.push(chunk.value); } }
37
+ finally { await reader.cancel(); }
38
+ return JSON.parse(Buffer.concat(chunks).toString("utf8")) as T;
39
+ };
40
+ return { me: () => request("/v1/me"), recapEnabled: async () => (await request<{ enabled?: boolean }>("/v1/recap/config")).enabled === true,
41
+ upload: (audio, filename, callId, key) => { const form = new FormData(); form.set("call_id", callId); form.set("diarize", "true"); form.set("output_formats", "json"); form.set("audio", audio, filename); return request("/v1/transcription/jobs", "POST", form, key); },
42
+ job: id => request(`/v1/transcription/jobs/${encodeURIComponent(id)}`), cancel: id => request(`/v1/transcription/jobs/${encodeURIComponent(id)}`, "DELETE"),
43
+ recap: async id => { try { return await request(`/v1/recap/calls/${encodeURIComponent(id)}`); } catch (error) { if (error instanceof MeetingApiError && error.status === 404) return null; throw error; } } };
44
+ }
45
+ export interface MeetingIntelligenceEntry {
46
+ key: string; recordingId: string; owner: string; digest: string; mimeType: string; bytes: number;
47
+ createdAt: number; expiresAt: number; jobId: string | null;
48
+ state: MeetingIntelligenceView["state"]; transcript: string | null; notes: string | null;
49
+ actionItems: MeetingIntelligenceView["actionItems"]; error: string | null;
50
+ }
51
+ /** Host-owned persistent store. run must serialize across ALL host instances,
52
+ * including erase vs submit/get. Save must durably commit before resolving.
53
+ * Reuse the host's existing ownership journal/transaction facility. */
54
+ export interface MeetingIntelligenceJournal {
55
+ run<T>(key: string, action: () => Promise<T>): Promise<T>;
56
+ get(key: string): Promise<MeetingIntelligenceEntry | null>;
57
+ save(entry: MeetingIntelligenceEntry): Promise<void>;
58
+ }
59
+ const hash = (...values: string[]) => createHash("sha256").update(JSON.stringify(values)).digest("hex");
60
+ const view = (entry: MeetingIntelligenceEntry): MeetingIntelligenceView => ({ recordingId: entry.recordingId, state: entry.state, transcript: entry.transcript, notes: entry.notes, actionItems: structuredClone(entry.actionItems), error: entry.error });
61
+ export function createServerMeetingIntelligence(options: {
62
+ api: MeetingIntelligenceApi; orgId: string; projectId: string; userId: string; keyId: string;
63
+ journal: MeetingIntelligenceJournal;
64
+ now?: () => number; maxBytes?: number; retentionMs?: number;
65
+ }): MeetingIntelligenceBroker {
66
+ const { api, journal } = options, now = options.now ?? Date.now;
67
+ const maxBytes = options.maxBytes ?? 128 * 1024 * 1024, retention = options.retentionMs ?? 24 * 3600000;
68
+ if (![options.orgId, options.projectId, options.userId, options.keyId].every(value => value.trim()) || !Number.isSafeInteger(maxBytes) || maxBytes < 1 || maxBytes > 256 * 1024 * 1024 || !Number.isSafeInteger(retention) || retention < 60000 || retention > 7 * 24 * 3600000) throw new Error("Trusted identity and bounded private recording retention are required.");
69
+ const owner = hash(options.orgId, options.projectId, options.userId);
70
+ const identity = (id: string) => { if (!/^[A-Za-z0-9_-]{1,200}$/.test(id)) throw new Error("Invalid recording ID."); return "meeting_" + hash(owner, id); };
71
+ const owned = async (key: string) => { const entry = await journal.get(key); if (!entry || entry.owner !== owner || entry.key !== key) throw new Error("No meeting in this workspace."); return entry; };
72
+ const availability = async () => {
73
+ const me = await api.me();
74
+ if (me.org_id !== options.orgId || me.project_id !== options.projectId || me.key_id !== options.keyId) throw new Error("The selected PyAI project identity changed. Select the original project.");
75
+ const required = ["hear:transcribe", "transcribe:jobs", "recap:read", "recap:configure"];
76
+ const missing = required.filter(scope => !me.scopes?.includes(scope));
77
+ if (missing.length) return { available: false, reason: `Select a project permitted to transcribe and summarize meetings. Missing scopes: ${missing.join(", ")}. Managed calling access alone does not include this feature.` };
78
+ if (!await api.recapEnabled()) return { available: false, reason: "Enable Recap through your workspace's normal settings before sending meeting audio." };
79
+ return { available: true, reason: null };
80
+ };
81
+ const requireAvailable = async () => { const result = await availability(); if (!result.available) throw new Error(result.reason!); };
82
+ const refresh = async (entry: MeetingIntelligenceEntry) => {
83
+ if (entry.state === "removed") return view(entry);
84
+ if (now() >= entry.expiresAt) {
85
+ entry.state = "removed"; entry.transcript = null; entry.notes = null; entry.actionItems = []; entry.error = "Private meeting retention expired. PyAI results and Recap follow workspace retention.";
86
+ await journal.save(entry); if (entry.jobId) await api.cancel(entry.jobId); return view(entry);
87
+ }
88
+ if (!entry.jobId) return view(entry);
89
+ const job = await api.job(entry.jobId);
90
+ if (job.job_id !== entry.jobId) throw new Error("PyAI returned a different meeting job.");
91
+ if (["failed", "cancelled"].includes(job.status)) { entry.state = "failed"; entry.error = "Transcription did not complete. Saved audio remains available locally; review the job before starting another submission."; await journal.save(entry); return view(entry); }
92
+ if (job.status !== "completed") { entry.state = "transcribing"; await journal.save(entry); return view(entry); }
93
+ const result = job.result as { text?: unknown } | undefined;
94
+ if (typeof result?.text === "string") entry.transcript = result.text;
95
+ entry.state = "summarizing"; await journal.save(entry);
96
+ const recap = await api.recap(entry.key);
97
+ if (recap && recap.call_id !== entry.key) throw new Error("PyAI returned a different meeting summary.");
98
+ if (recap?.status === "failed") { entry.state = "failed"; entry.error = "The transcript is ready but Recap failed. Review the existing summary job; audio is not submitted again."; }
99
+ if (recap?.status === "complete") {
100
+ entry.transcript ??= recap.transcript?.utterances.map(item => item.text).join("\n") ?? null;
101
+ entry.notes = recap.record?.summary ?? recap.record?.tldr ?? null;
102
+ entry.actionItems = structuredClone(recap.record?.action_items ?? []); entry.state = "complete"; entry.error = null;
103
+ }
104
+ await journal.save(entry); return view(entry);
105
+ };
106
+ return { availability,
107
+ async submit(id, audio, noticeAccepted) {
108
+ if (noticeAccepted !== true) throw new Error("Accept the upload and retention notice before sending audio.");
109
+ if (!audio.size || audio.size > maxBytes || !/^audio\/(webm|mp4|wav|x-wav|mpeg|ogg)(?:;|$)/i.test(audio.type)) throw new Error("Choose a supported saved audio recording within the workspace size limit.");
110
+ const key = identity(id); await requireAvailable();
111
+ const digest = createHash("sha256").update(new Uint8Array(await audio.arrayBuffer())).digest("hex");
112
+ return journal.run(key, async () => {
113
+ let entry = await journal.get(key);
114
+ if (entry && (entry.owner !== owner || entry.digest !== digest || entry.mimeType !== audio.type || entry.bytes !== audio.size)) throw new Error("This recording ID already belongs to different audio. Recover the original submission.");
115
+ if (entry?.state === "removed") throw new Error("This meeting was removed. It cannot be resubmitted with the same ID.");
116
+ if (!entry) { entry = { key, recordingId: id, owner, digest, mimeType: audio.type, bytes: audio.size, createdAt: now(), expiresAt: now() + retention, jobId: null, state: "submitting", transcript: null, notes: null, actionItems: [], error: null }; await journal.save(entry); }
117
+ if (now() >= entry.expiresAt || entry.jobId) return refresh(entry);
118
+ // Persist the same content identity before POST. A lost response is
119
+ // recovered with the SAME durable JSON/multipart job retry key.
120
+ const extension = ({ "audio/webm": "webm", "audio/mp4": "m4a", "audio/wav": "wav", "audio/x-wav": "wav", "audio/mpeg": "mp3", "audio/ogg": "ogg" } as Record<string, string>)[audio.type.split(";")[0]!.toLowerCase()]!;
121
+ const job = await api.upload(audio, `meeting.${extension}`, key, key);
122
+ entry.jobId = job.job_id; entry.state = "transcribing"; await journal.save(entry); return refresh(entry);
123
+ });
124
+ },
125
+ async get(id) { const key = identity(id); await requireAvailable(); return journal.run(key, async () => refresh(await owned(key))); },
126
+ async remove(id) {
127
+ const key = identity(id); return journal.run(key, async () => {
128
+ const entry = await owned(key); entry.state = "removed"; entry.transcript = null; entry.notes = null; entry.actionItems = []; entry.error = "Cached notes removed. PyAI uploaded audio may remain for up to 7 days and results up to 30 days; Recap follows workspace retention. Cancellation is not erasure.";
129
+ await journal.save(entry);
130
+ // Erase never submits or replays audio. If the initial POST outcome was
131
+ // unknown we cannot invent its job ID or claim it was cancelled.
132
+ if (!entry.jobId) entry.error = "Cached notes removed. The earlier submission outcome is unknown; a PyAI job may remain under workspace retention. Uploaded audio may remain for up to 7 days and results up to 30 days.";
133
+ await journal.save(entry);
134
+ if (entry.jobId) await api.cancel(entry.jobId);
135
+ return view(entry);
136
+ });
137
+ },
138
+ };
139
+ }
140
+
141
+ /** Reuses the host's already selected SDK instance and its normal transport.
142
+ * The SDK never exposes the key to the renderer. */
143
+ export function createSdkMeetingApi(sdk: PyAI): MeetingIntelligenceApi {
144
+ return { me: () => sdk.me(), recapEnabled: async () => (await sdk.recap.config.get()).enabled === true,
145
+ upload: (audio, filename, callId, key) => sdk.transcriptionJobs.upload({ file: audio, filename, call_id: callId, diarize: true, output_formats: ["json"] }, { idempotencyKey: key }),
146
+ job: id => sdk.transcriptionJobs.get(id), cancel: id => sdk.transcriptionJobs.cancel(id),
147
+ recap: async id => { try { return await sdk.recap.calls.get(id); } catch (error) { if ((error as { status?: number }).status === 404) return null; throw error; } } };
148
+ }
package/src/index.ts CHANGED
@@ -235,6 +235,8 @@ export interface AgentConfig {
235
235
  name?: string;
236
236
  /** Saved instructions: 8,000 Unicode characters by default; 32,000 on commitment plans. */
237
237
  persona_system_prompt?: string | null;
238
+ /** Separate setup rules, writable only by explicitly enrolled server credentials. */
239
+ platform_guidance?: string | null;
238
240
  /** False restricts retrieval to explicit agent bindings, including none. Default true. */
239
241
  inherit_org_knowledgebases?: boolean;
240
242
  greeting?: string | null;
@@ -951,6 +953,8 @@ export interface OmniConfigure {
951
953
  voice_id?: string;
952
954
  /** System prompt / role + instructions for the agent. */
953
955
  persona?: string;
956
+ /** Separate bounded platform guidance, applied before customer instructions. */
957
+ role_scaffold?: string;
954
958
  /** Customer-hosted URL the engine calls per turn for grounding. */
955
959
  kb_endpoint?: string;
956
960
  /** Bearer the engine presents to `kb_endpoint`. */
@@ -1458,6 +1462,7 @@ export class OmniConnection {
1458
1462
 
1459
1463
  /** Shape of `GET /v1/me`. Fields are best-effort / forward-compatible. */
1460
1464
  export interface MeResponse {
1465
+ project_id?: string;
1461
1466
  object?: string;
1462
1467
  key_id?: string;
1463
1468
  org_id?: string;
@@ -1495,6 +1500,8 @@ export interface TelephonyCall {
1495
1500
  from_number_id: string | null;
1496
1501
  agent_id: string | null;
1497
1502
  call_type?: "human";
1503
+ transfer_enabled?: boolean;
1504
+ transfers?: TelephonyTransfer[];
1498
1505
  user_id?: string;
1499
1506
  client_reference: string | null;
1500
1507
  stop_requested: boolean;
@@ -1505,6 +1512,12 @@ export interface TelephonyCall {
1505
1512
  [key: string]: unknown;
1506
1513
  }
1507
1514
  export type TelephonyUseCase = "transactional" | "support" | "sales" | "collections" | "survey";
1515
+ export interface TelephonyTransfer {
1516
+ id: string;
1517
+ mode: "warm" | "cold";
1518
+ status: "holding" | "dialing" | "ready" | "completing" | "canceling" | "completed" | "canceled" | "failed";
1519
+ to: string | null;
1520
+ }
1508
1521
  export interface TelephonyCallCreate {
1509
1522
  from_number_id: string;
1510
1523
  to: string;
@@ -1524,7 +1537,7 @@ export type TelephonyBrowserSessionCreate = {
1524
1537
  recording: boolean;
1525
1538
  use_case?: TelephonyUseCase;
1526
1539
  max_duration_seconds?: number;
1527
- } & ({ to: string; destinations?: never } | { to?: never; destinations: string[] });
1540
+ } & ({ to: string; destinations?: never; transfer_enabled?: boolean } | { to?: never; destinations: string[]; transfer_enabled?: false });
1528
1541
  export interface TelephonyBrowserSession {
1529
1542
  object: "telephony.browser_session";
1530
1543
  id: string;
@@ -2312,6 +2325,20 @@ export class PyAI {
2312
2325
  });
2313
2326
  return (await res.json()) as TranscriptionJob;
2314
2327
  },
2328
+ /** Upload a recording with a durable retry key. Requires the current
2329
+ * keyed multipart job contract; never change the key after an unknown ACK. */
2330
+ upload: async (params: { file: Blob; filename: string; call_id?: string; diarize?: boolean; output_formats?: Array<"json" | "srt" | "vtt"> }, opts: { idempotencyKey: string }): Promise<TranscriptionJob> => {
2331
+ if (!opts.idempotencyKey || opts.idempotencyKey.length > 255 || /[\r\n]/.test(opts.idempotencyKey)) throw new Error("A valid recording retry key is required.");
2332
+ const form = new FormData();
2333
+ if (params.call_id) form.set("call_id", params.call_id);
2334
+ if (params.diarize !== undefined) form.set("diarize", String(params.diarize));
2335
+ if (params.output_formats) form.set("output_formats", params.output_formats.join(","));
2336
+ form.set("audio", params.file, params.filename);
2337
+ const response = await this.request("/v1/transcription/jobs", { method: "POST", headers: this.authHeaders({ "Idempotency-Key": opts.idempotencyKey }), body: form });
2338
+ return await response.json() as TranscriptionJob;
2339
+ },
2340
+ /** Cancels queued/running work; existing cloud retention still applies. */
2341
+ cancel: async (jobId: string): Promise<TranscriptionJob> => { const response = await this.request(`/v1/transcription/jobs/${encodeURIComponent(jobId)}`, { method: "DELETE", headers: this.authHeaders() }); return await response.json() as TranscriptionJob; },
2315
2342
  get: (jobId: string): Promise<TranscriptionJob> =>
2316
2343
  this.getJson(`/v1/transcription/jobs/${encodeURIComponent(jobId)}`),
2317
2344
  list: (params: { limit?: number; cursor?: string } = {}): Promise<ListResponse<TranscriptionJob>> => {
@@ -2381,6 +2408,15 @@ export class PyAI {
2381
2408
  recording: (id: string, options: { range?: string } = {}): Promise<Response> =>
2382
2409
  this.request(`/v1/telephony/calls/${encodeURIComponent(id)}/recording`, { headers: this.authHeaders(options.range ? { Range: options.range } : {}) }),
2383
2410
  deleteRecording: async (id: string): Promise<void> => { await this.deleteReq(`/v1/telephony/calls/${encodeURIComponent(id)}/recording`); },
2411
+ transfers: {
2412
+ /** Persist the key and target before requesting a consultation. */
2413
+ create: (id: string, input: { to: string; mode: "warm" | "cold"; user_id: string }, options: { idempotencyKey: string }): Promise<TelephonyCall> =>
2414
+ this.postJson(`/v1/telephony/calls/${encodeURIComponent(id)}/transfers`, input, telephonyIdempotencyHeader(options.idempotencyKey)),
2415
+ complete: (id: string, transferId: string, userId: string): Promise<TelephonyCall> =>
2416
+ this.postJson(`/v1/telephony/calls/${encodeURIComponent(id)}/transfers/${encodeURIComponent(transferId)}/complete`, { user_id: userId }),
2417
+ cancel: (id: string, transferId: string, userId: string): Promise<TelephonyCall> =>
2418
+ this.postJson(`/v1/telephony/calls/${encodeURIComponent(id)}/transfers/${encodeURIComponent(transferId)}/cancel`, { user_id: userId }),
2419
+ },
2384
2420
  },
2385
2421
  browserSessions: {
2386
2422
  /** Persist input and key on your server; retries recover the original session. */