@pyai/sdk 0.1.1 → 0.2.0

package/dist/index.js

@@ -21,6 +21,150 @@ export class PyAIError extends Error {
         this.requestId = requestId;
     }
 }
+/**
+ * The runtime list of accepted `audio.speech` formats (mirrors {@link SpeechFormat}),
+ * for building dropdowns / validating input before a request. Branch on the
+ * named values; the order matches the contract doc.
+ */
+export const SPEECH_FORMATS = ["wav", "mp3", "opus", "aac", "flac", "pcm", "g711_ulaw", "g711_alaw"];
+/** Sample rates (Hz) the server accepts for `audio.speech` (`g711_*` is always 8 kHz). */
+export const SPEECH_SAMPLE_RATES = [8000, 16000, 24000, 48000];
+/* ------------------------------------------------------------------------- *
+ * Stable enums — mirror the server so callers branch on named constants, not
+ * magic strings, and a contract change surfaces in one place. These are plain
+ * `as const` objects (not TS `enum`s) so the source still runs directly under
+ * Node's type-stripping and stays tree-shakeable.
+ * ------------------------------------------------------------------------- */
+/** Frame `type`s emitted by the Hear streaming-STT WebSocket. */
+export const HearFrameType = {
+    /** Eager live hypothesis for the current utterance. */
+    Partial: "partial",
+    /** Partial whose prefix has stabilized (won't be revised). */
+    PartialStable: "partial_stable",
+    /** Stable transcript at end-of-utterance (endpoint or commit). */
+    SpeechFinal: "speech_final",
+    /** Corrected, full-context transcript following `speech_final`. */
+    Final: "final",
+    /** Server-side fault frame. */
+    Error: "error",
+};
+/** WebSocket close codes used across the PyAI realtime/streaming surfaces. */
+export const WSCloseCode = {
+    /** Normal closure. */
+    Normal: 1000,
+    /** Auth/policy: bad key, missing scope, or revoked token. */
+    PolicyViolation: 1008,
+    /** Engine/internal error. */
+    InternalError: 1011,
+    /** Over the concurrency cap (PyAI-specific; mirrors HTTP 429). */
+    OverCapacity: 4429,
+};
+/**
+ * Stable, machine-readable error `code`s (the documented contract). Branch on
+ * these. The set is treated as open — `PyAIError.code` stays `string` — so a
+ * new server code never breaks the build, but the known ones are named here.
+ */
+export const ErrorCode = {
+    Unauthorized: "unauthorized",
+    Forbidden: "forbidden",
+    OriginNotAllowed: "origin_not_allowed",
+    InvalidAgentId: "invalid_agent_id",
+    CreditExhausted: "credit_exhausted",
+    KeyBudgetExceeded: "key_budget_exceeded",
+    InsufficientQuota: "insufficient_quota",
+    RateLimitExceeded: "rate_limit_exceeded",
+    ConcurrencyLimitExceeded: "concurrency_limit_exceeded",
+    DailyCapExceeded: "daily_cap_exceeded",
+    IdempotencyConflict: "idempotency_conflict",
+    NotFound: "not_found",
+    NumberInUse: "number_in_use",
+};
+/**
+ * A live Hear streaming-STT session. Hides the frame protocol: stream audio
+ * with {@link HearStream.sendAudio}, get `onPartial`/`onFinal`/`onError`
+ * callbacks, force-finalize with {@link HearStream.commit}, and flush+close
+ * with {@link HearStream.close}. Construct via `pyai.audio.transcriptions.stream()`.
+ */
+export class HearStream {
+    ws;
+    opts;
+    closed = false;
+    constructor(url, subprotocol, opts) {
+        this.opts = opts;
+        const WS = opts.webSocket ?? globalThis.WebSocket;
+        if (!WS) {
+            throw new Error("No global WebSocket available; pass options.webSocket (e.g. the `ws` package) to transcriptions.stream()");
+        }
+        this.ws = new WS(url, [subprotocol]);
+        this.ws.onopen = () => {
+            if (opts.grounding) {
+                try {
+                    this.ws.send(JSON.stringify({ type: "config", grounding: true }));
+                }
+                catch {
+                    /* surfaced via onerror */
+                }
+            }
+            opts.onOpen?.();
+        };
+        this.ws.onmessage = (ev) => this.handleMessage(ev.data);
+        this.ws.onerror = (ev) => opts.onError?.(ev instanceof Error ? ev : new Error("WebSocket error"));
+        this.ws.onclose = (ev) => {
+            this.closed = true;
+            opts.onClose?.(ev.code, ev.reason);
+        };
+    }
+    handleMessage(data) {
+        // Hear emits JSON text frames; ignore any unexpected binary.
+        if (typeof data !== "string")
+            return;
+        let frame;
+        try {
+            frame = JSON.parse(data);
+        }
+        catch {
+            this.opts.onError?.(new Error(`Unparseable Hear frame: ${data.slice(0, 120)}`));
+            return;
+        }
+        switch (frame.type) {
+            case HearFrameType.Partial:
+            case HearFrameType.PartialStable:
+                this.opts.onPartial?.(frame);
+                break;
+            case HearFrameType.SpeechFinal:
+            case HearFrameType.Final:
+                this.opts.onFinal?.(frame);
+                break;
+            case HearFrameType.Error:
+                this.opts.onError?.(frame);
+                break;
+            default:
+                // Unknown/forward-compatible frame — ignore.
+                break;
+        }
+    }
+    /** Send a chunk of audio (PCM16 or opus per `encoding`). */
+    sendAudio(chunk) {
+        this.ws.send(chunk);
+    }
+    /** Force-finalize the current utterance (e.g. on VAD end-of-turn). */
+    commit() {
+        this.ws.send(JSON.stringify({ type: "commit" }));
+    }
+    /** Close the socket; the server flushes a final for any buffered audio. */
+    close(code = WSCloseCode.Normal, reason = "") {
+        if (!this.closed)
+            this.ws.close(code, reason);
+    }
+    /** The underlying socket (escape hatch for advanced use). */
+    get socket() {
+        return this.ws;
+    }
+    /** Current WebSocket readyState. */
+    get readyState() {
+        return this.ws.readyState;
+    }
+}
 const RETRYABLE = new Set([429, 500, 502, 503, 504]);
 export class PyAI {
     apiKey;
@@ -74,6 +218,25 @@ export class PyAI {
         const res = await this.request(path, { headers: this.authHeaders() });
         return (await res.json());
     }
+    async postJson(path, payload, extraHeaders = {}) {
+        const res = await this.request(path, {
+            method: "POST",
+            headers: this.authHeaders({ "Content-Type": "application/json", ...extraHeaders }),
+            body: JSON.stringify(payload),
+        });
+        return (await res.json());
+    }
+    async putJson(path, payload) {
+        const res = await this.request(path, {
+            method: "PUT",
+            headers: this.authHeaders({ "Content-Type": "application/json" }),
+            body: JSON.stringify(payload),
+        });
+        return (await res.json());
+    }
+    deleteReq(path) {
+        return this.request(path, { method: "DELETE", headers: this.authHeaders() });
+    }
     // --- models -------------------------------------------------------------
     models = {
         list: () => this.getJson("/v1/models"),
@@ -126,6 +289,14 @@ export class PyAI {
                 const form = new FormData();
                 form.set("file", params.file, params.filename ?? "audio.wav");
                 form.set("model", params.model ?? "pyai-hear");
+                if (params.language)
+                    form.set("language", params.language);
+                if (params.response_format)
+                    form.set("response_format", params.response_format);
+                if (params.seed !== undefined)
+                    form.set("seed", String(params.seed));
+                if (params.temperature !== undefined)
+                    form.set("temperature", String(params.temperature));
                 const res = await this.request("/v1/audio/transcriptions", {
                     method: "POST",
                     headers: this.authHeaders(),
@@ -133,6 +304,13 @@ export class PyAI {
                 });
                 return (await res.json());
             },
+            /**
+             * Open a live streaming-STT WebSocket (Hear). Hides the frame protocol
+             * behind `onPartial`/`onFinal`/`onError`; stream audio with `sendAudio`,
+             * force-finalize with `commit()`, flush+close with `close()`. Set
+             * `grounding: true` for Cue (turn detection + KB context).
+             */
+            stream: (opts = {}) => new HearStream(this.hearStreamURL(opts), this.realtimeSubprotocol(), opts),
         },
     };
     // --- async transcription jobs ------------------------------------------
@@ -159,6 +337,179 @@ export class PyAI {
             return this.getJson(`/v1/transcription/jobs${qs ? `?${qs}` : ""}`);
         },
     };
+    // --- key introspection --------------------------------------------------
+    /**
+     * Introspect the calling key: scopes, environment, and limits. Useful for a
+     * preflight/doctor check. (New route; older deployments may 404 — handle it.)
+     */
+    me = () => this.getJson("/v1/me");
+    // --- voice clones -------------------------------------------------------
+    clones = {
+        /** List the org's cloned voices. */
+        list: () => this.getJson("/v1/voice/clones"),
+        /** Enroll a custom voice from reference audio (>= ~10s). Scope `voice:clone`. */
+        create: async (params) => {
+            const form = new FormData();
+            form.set("name", params.name);
+            form.set("file", params.file, params.filename ?? "sample.wav");
+            const res = await this.request("/v1/voice/clones", { method: "POST", headers: this.authHeaders(), body: form });
+            return (await res.json());
+        },
+        /**
+         * Fetch a single cloned voice by id. The API exposes no GET-by-id for
+         * clones, so this filters `list()` client-side and throws a 404 `PyAIError`
+         * when the id isn't found.
+         */
+        get: async (id) => {
+            const { data } = await this.clones.list();
+            const match = data.find((v) => v.id === id);
+            if (!match)
+                throw new PyAIError(404, `No cloned voice ${id}`, ErrorCode.NotFound);
+            return match;
+        },
+        /** Delete a cloned voice (tenant-isolated). Scope `voice:clone`. */
+        delete: async (id) => {
+            await this.deleteReq(`/v1/voice/clones/${encodeURIComponent(id)}`);
+        },
+    };
+    // --- telephony (managed numbers) ---------------------------------------
+    telephony = {
+        numbers: {
+            /** Search the carrier's available US local numbers. */
+            available: (params = {}) => {
+                const q = new URLSearchParams();
+                if (params.areaCode)
+                    q.set("area_code", params.areaCode);
+                if (params.contains)
+                    q.set("contains", params.contains);
+                if (params.limit !== undefined)
+                    q.set("limit", String(params.limit));
+                const qs = q.toString();
+                return this.getJson(`/v1/telephony/available${qs ? `?${qs}` : ""}`);
+            },
+            /** List the org's managed numbers (active only unless `includeReleased`). */
+            list: (params = {}) => {
+                const qs = params.includeReleased ? "?include_released=true" : "";
+                return this.getJson(`/v1/telephony/numbers${qs}`);
+            },
+            /** Provision (buy) a specific available number, optionally bound to an agent. */
+            buy: (params) => this.postJson("/v1/telephony/numbers", params),
+            /** Route a number to an agent (`agentId: null` to unassign). */
+            assign: (id, agentId) => this.postJson(`/v1/telephony/numbers/${encodeURIComponent(id)}/assign`, { agent_id: agentId }),
+            /** Release a number back to the carrier (idempotent). */
+            release: async (id) => {
+                const res = await this.deleteReq(`/v1/telephony/numbers/${encodeURIComponent(id)}`);
+                return (await res.json());
+            },
+        },
+    };
+    // --- trace (compliance) -------------------------------------------------
+    trace = {
+        interactions: {
+            /** List scanned interactions (scorecards), newest first. Scope `trace:read`. */
+            list: (params = {}) => {
+                const q = new URLSearchParams();
+                if (params.verdict)
+                    q.set("verdict", params.verdict);
+                if (params.agentId)
+                    q.set("agent_id", params.agentId);
+                if (params.limit !== undefined)
+                    q.set("limit", String(params.limit));
+                if (params.cursor)
+                    q.set("cursor", params.cursor);
+                const qs = q.toString();
+                return this.getJson(`/v1/trace/interactions${qs ? `?${qs}` : ""}`);
+            },
+            /** The full per-call evidence view (findings, redactions, audit hash). */
+            get: (id) => this.getJson(`/v1/trace/interactions/${encodeURIComponent(id)}`),
+        },
+        violations: {
+            /** Drill-down of every fired Tier-0 rule across scorecards. Scope `trace:read`. */
+            list: (params = {}) => {
+                const q = new URLSearchParams();
+                if (params.ruleId)
+                    q.set("rule_id", params.ruleId);
+                if (params.severity)
+                    q.set("severity", params.severity);
+                if (params.interactionId)
+                    q.set("interaction_id", params.interactionId);
+                if (params.limit !== undefined)
+                    q.set("limit", String(params.limit));
+                if (params.cursor)
+                    q.set("cursor", params.cursor);
+                const qs = q.toString();
+                return this.getJson(`/v1/trace/violations${qs ? `?${qs}` : ""}`);
+            },
+        },
+        findings: {
+            /** List Tier-2 (async semantic) findings — advisory, non-blocking. Scope `trace:read`. */
+            list: (params = {}) => {
+                const q = new URLSearchParams();
+                if (params.checkId)
+                    q.set("check_id", params.checkId);
+                if (params.action)
+                    q.set("action", params.action);
+                if (params.severity)
+                    q.set("severity", params.severity);
+                if (params.interactionId)
+                    q.set("interaction_id", params.interactionId);
+                if (params.limit !== undefined)
+                    q.set("limit", String(params.limit));
+                if (params.cursor)
+                    q.set("cursor", params.cursor);
+                const qs = q.toString();
+                return this.getJson(`/v1/trace/findings${qs ? `?${qs}` : ""}`);
+            },
+        },
+        config: {
+            /** Read per-agent Trace config (omit `agentId` for the org default). Scope `trace:configure`. */
+            get: (agentId) => this.getJson(`/v1/trace/config${agentId ? `?agent_id=${encodeURIComponent(agentId)}` : ""}`),
+            /** Upsert per-agent Trace config. Scope `trace:configure`. */
+            set: (input) => this.putJson("/v1/trace/config", input),
+        },
+        rulePacks: {
+            /** List built-in + custom rule packs. Scope `trace:configure`. */
+            list: () => this.getJson("/v1/trace/rule-packs"),
+            /** Upload a custom rule pack (Trace DSL). Scope `trace:configure`. */
+            create: (spec) => this.postJson("/v1/trace/rule-packs", spec),
+            /** Resolve a rule pack by id (latest active, or pin `version`). */
+            get: (id, version) => this.getJson(`/v1/trace/rule-packs/${encodeURIComponent(id)}${version ? `?version=${encodeURIComponent(version)}` : ""}`),
+        },
+        /** Compliance exposure summary over a trailing window. Scope `trace:read`. */
+        exposure: (windowDays) => this.getJson(`/v1/trace/exposure${windowDays !== undefined ? `?window_days=${windowDays}` : ""}`),
+        /**
+         * Convenience: the per-call operational timeline (eval scorecard-v1). A thin
+         * wrapper over `interactions.get(id)` that returns the `timeline` array, or
+         * `[]` when the engine hasn't emitted one yet (forward-compatible). Scope
+         * `trace:read`.
+         */
+        callTimeline: async (id) => {
+            const detail = await this.trace.interactions.get(id);
+            return detail.timeline ?? [];
+        },
+    };
+    // --- recap (conversation intelligence) --------------------------------
+    recap = {
+        config: {
+            get: () => this.getJson("/v1/recap/config"),
+            set: (input) => this.putJson("/v1/recap/config", input),
+        },
+        calls: {
+            list: (params = {}) => {
+                const q = new URLSearchParams();
+                if (params.limit !== undefined)
+                    q.set("limit", String(params.limit));
+                if (params.cursor)
+                    q.set("cursor", params.cursor);
+                if (params.status)
+                    q.set("status", params.status);
+                const qs = q.toString();
+                return this.getJson(`/v1/recap/calls${qs ? `?${qs}` : ""}`);
+            },
+            get: (callId) => this.getJson(`/v1/recap/calls/${encodeURIComponent(callId)}`),
+            trigger: (callId, input) => this.postJson(`/v1/recap/calls/${encodeURIComponent(callId)}`, input),
+        },
+    };
     // --- realtime (WebSocket) ----------------------------------------------
     /** Build the realtime WebSocket URL for the chosen product. */
     realtimeURL(opts = {}) {
@@ -184,6 +535,23 @@ export class PyAI {
     realtimeSubprotocol() {
         return `pyai-key.${this.apiKey}`;
     }
+    /** Build the Hear streaming-STT WebSocket URL (`/v1/audio/transcriptions/stream`). */
+    hearStreamURL(opts = {}) {
+        const wsBase = this.baseURL.replace(/^http/, "ws");
+        const q = new URLSearchParams(opts.query ?? {});
+        if (opts.model)
+            q.set("model", opts.model);
+        if (opts.language)
+            q.set("language", opts.language);
+        if (opts.sampleRate !== undefined)
+            q.set("sample_rate", String(opts.sampleRate));
+        if (opts.encoding)
+            q.set("encoding", opts.encoding);
+        if (opts.interimResults !== undefined)
+            q.set("interim_results", String(opts.interimResults));
+        const qs = q.toString();
+        return `${wsBase}/v1/audio/transcriptions/stream${qs ? `?${qs}` : ""}`;
+    }
     /**
      * Open a realtime WebSocket. Uses the global WebSocket (browser, Node 22+).
      * The key travels as a subprotocol so it works from the browser without

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pyai/sdk",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Official TypeScript/JavaScript SDK for PyAI — speech-to-text (Hear), text-to-speech (Speak), realtime voice agents (Omni), and call compliance (Trace).",
   "type": "module",
   "main": "dist/index.js",

package/src/cli.ts

@@ -1,9 +1,10 @@
 #!/usr/bin/env node
 /**
- * pyai — CLI smoke tester for the PyAI API: proves your key, the endpoint,
- * and audio synthesis in one command.
+ * pyai — CLI for the PyAI API: proves your key, the endpoint, and audio in one
+ * command (`smoke`) or runs a deeper diagnosis with remediation hints (`doctor`).
  *
  * Commands:
+ *   pyai doctor                         diagnose key/scopes + endpoint + Speak→Hear round-trip
  *   pyai smoke                          run models+voices+speak and report PASS/FAIL
  *   pyai models                         list models
  *   pyai voices [--gender g --region r] list voices
@@ -66,6 +67,7 @@ function fail(msg: string): never {
 const USAGE = `pyai — PyAI API CLI
 
 Usage:
+  pyai doctor                             diagnose key/scopes + endpoint + Speak→Hear round-trip
   pyai smoke                              run a key/endpoint/audio smoke test
   pyai models                             list models
   pyai voices [--gender g] [--region r]   list voices
@@ -146,10 +148,121 @@ async function cmdSmoke(flags: Flags): Promise<void> {
   if (!allOk) process.exit(1);
 }
 
+/** Turn an error into an actionable, code-first remediation hint. */
+function remediation(err: unknown): string {
+  if (!(err instanceof PyAIError)) return (err as Error)?.message ?? String(err);
+  switch (err.code) {
+    case "unauthorized":
+      return "Invalid or missing key — check PYAI_API_KEY (a pyai_test_ or pyai_live_ key).";
+    case "forbidden":
+      return "Key is missing a required scope — add it to the key in the console.";
+    case "origin_not_allowed":
+      return "Publishable token origin not allow-listed — fix the allowed origins.";
+    case "credit_exhausted":
+      return "Out of prepaid credit — add credit, or use a pyai_test_ sandbox key.";
+    case "key_budget_exceeded":
+      return "Per-key monthly budget hit — raise the budget in the console.";
+    case "insufficient_quota":
+      return "Plan quota exhausted — upgrade your plan.";
+    case "rate_limit_exceeded":
+      return "Rate limited — back off and retry (honor Retry-After).";
+    case "concurrency_limit_exceeded":
+      return "Too many concurrent sessions — retry shortly.";
+    case "daily_cap_exceeded":
+      return "Daily cap reached — wait until it resets.";
+    default:
+      break;
+  }
+  switch (err.status) {
+    case 401:
+      return "Invalid or missing key — check PYAI_API_KEY.";
+    case 403:
+      return "Forbidden — the key likely lacks the required scope.";
+    case 404:
+      return "Not found — check PYAI_BASE_URL and the route.";
+    case 429:
+      return "Rate/concurrency limited — back off and retry.";
+    default:
+      return err.message;
+  }
+}
+
+interface DoctorCheck {
+  name: string;
+  status: "PASS" | "FAIL" | "SKIP";
+  detail: string;
+  hint?: string;
+}
+
+async function doctorCheck(checks: DoctorCheck[], name: string, fn: () => Promise<string>): Promise<void> {
+  try {
+    checks.push({ name, status: "PASS", detail: await fn() });
+  } catch (err) {
+    const detail =
+      err instanceof PyAIError ? `${err.status} ${err.code ?? ""} ${err.message}`.trim() : (err as Error).message;
+    checks.push({ name, status: "FAIL", detail, hint: remediation(err) });
+  }
+}
+
+/** Deeper than smoke: key/scopes, endpoint liveness, and a Speak→Hear round-trip. */
+async function cmdDoctor(flags: Flags): Promise<void> {
+  const pyai = client(flags);
+  const checks: DoctorCheck[] = [];
+
+  // (a) Key validity + scopes via GET /v1/me. The route is new, so a 404 means
+  // "not deployed here yet" — skip it rather than failing the whole doctor.
+  try {
+    const me = await pyai.me();
+    const scopes = Array.isArray(me.scopes) ? me.scopes : [];
+    const env = me.environment ?? me.env ?? "unknown";
+    checks.push({
+      name: "key (/v1/me)",
+      status: "PASS",
+      detail: `env=${env}; ${scopes.length} scope(s)${scopes.length ? `: ${scopes.join(", ")}` : ""}`,
+    });
+  } catch (err) {
+    if (err instanceof PyAIError && err.status === 404) {
+      checks.push({ name: "key (/v1/me)", status: "SKIP", detail: "introspection route not on this deployment" });
+    } else {
+      const detail = err instanceof PyAIError ? `${err.status} ${err.code ?? ""}`.trim() : (err as Error).message;
+      checks.push({ name: "key (/v1/me)", status: "FAIL", detail, hint: remediation(err) });
+    }
+  }
+
+  // (b) Endpoint liveness.
+  await doctorCheck(checks, "models.list", async () => `${(await pyai.models.list()).data.length} models`);
+  await doctorCheck(checks, "voices.list", async () => `${(await pyai.voices.list()).data.length} voices`);
+
+  // (c) Speak -> Hear round-trip: synthesize a sentence, then transcribe it.
+  await doctorCheck(checks, "speak→hear round-trip", async () => {
+    const audio = await pyai.audio.speech({ input: "The quick brown fox jumps over the lazy dog." });
+    const bytes = Buffer.from(audio).byteLength;
+    const blob = new Blob([audio], { type: "audio/wav" });
+    const tr = await pyai.audio.transcriptions.create({ file: blob, filename: "doctor.wav" });
+    const text = (tr.text ?? "").trim();
+    if (!text) throw new Error(`synthesized ${bytes} bytes but transcription came back empty`);
+    return `synth ${bytes} bytes → "${text.length > 60 ? `${text.slice(0, 60)}…` : text}"`;
+  });
+
+  for (const c of checks) {
+    out(`${c.status.padEnd(4)}  ${c.name}  — ${c.detail}`);
+    if (c.hint) out(`        ↳ ${c.hint}`);
+  }
+  const failed = checks.filter((c) => c.status === "FAIL");
+  if (failed.length === 0) {
+    out("\nDiagnosis: healthy. Key, endpoint, and a Speak→Hear round-trip all work.");
+  } else {
+    out(`\nDiagnosis: ${failed.length} check(s) failed — see the remediation hints above.`);
+    process.exit(1);
+  }
+}
+
 async function main(): Promise<void> {
   const flags = parseArgs(process.argv.slice(2));
   const cmd = (flags._ as string[])[0];
   switch (cmd) {
+    case "doctor":
+      return cmdDoctor(flags);
     case "smoke":
       return cmdSmoke(flags);
     case "models":