@pyai/sdk 0.1.0

package/README.md

@@ -0,0 +1,114 @@
+# @pyai/sdk
+
+Official TypeScript/JavaScript SDK for the [PyAI API](https://api.pyai.com) —
+Hear (speech-to-text), Speak (text-to-speech + cloning), Cue (turn detection +
+KB context), and Omni (realtime voice agents). Zero dependencies; runs in the
+browser and Node 18+.
+
+The contract is `https://api.pyai.com/openapi.json`. This SDK wraps it
+ergonomically with typed errors, automatic retries, and a realtime helper.
+
+## Install
+
+```bash
+npm install @pyai/sdk
+```
+
+## Quickstart
+
+```ts
+import PyAI from "@pyai/sdk";
+
+const pyai = new PyAI({ apiKey: process.env.PYAI_API_KEY! });
+
+// Text-to-speech
+const audio = await pyai.audio.speech({ input: "Hello from PyAI.", voice: "stock_sarah_style2" });
+await Bun.write?.("hello.wav", audio); // or fs.writeFile in Node
+
+// Text-to-speech, streamed — start playing/forwarding at the first chunk
+// (tens of ms) instead of waiting for the whole clip. Use mp3 for smooth
+// progressive playback.
+const stream = await pyai.audio.speechStream({ input: "Hello from PyAI.", voice: "stock_sarah_style2", response_format: "mp3" });
+for await (const chunk of stream) writeToSpeakerOrResponse(chunk);
+
+// Voices
+const { data: voices } = await pyai.voices.list({ gender: "female" });
+
+// Async transcription (safe retry with an idempotency key)
+const job = await pyai.transcriptionJobs.create(
+  { audio_url: "https://example.com/call.wav", diarize: true },
+  { idempotencyKey: crypto.randomUUID() },
+);
+const done = await pyai.transcriptionJobs.get(job.job_id);
+```
+
+## Realtime (Omni)
+
+Keys travel as a WebSocket subprotocol so this works in the browser:
+
+```ts
+const ws = pyai.connectRealtime({ product: "omni", agentId: "agent_123" });
+ws.addEventListener("message", (e) => console.log(e.data));
+
+// Or build the pieces yourself for a custom WS library:
+const url = pyai.realtimeURL({ product: "omni", agentId: "agent_123" });
+const proto = pyai.realtimeSubprotocol();
+```
+
+> Omni uses the native `wss://api.pyai.com/v1/omni` surface. `connectRealtime`
+> targets it by default (`product: "omni"`); `product: "flow"` uses
+> `/v1/realtime`. The older `/v2/omni/chat` URL is deprecated but still works.
+
+## Errors
+
+Failures throw `PyAIError` with a stable `code` (branch on it, not the message):
+
+```ts
+import { PyAIError } from "@pyai/sdk";
+
+try {
+  await pyai.audio.speech({ input: "hi" });
+} catch (err) {
+  if (err instanceof PyAIError && err.code === "credit_exhausted") {
+    // out of prepaid credit — add credit or use a sandbox key
+  }
+}
+```
+
+Common codes: `unauthorized`, `forbidden`, `credit_exhausted`,
+`rate_limit_exceeded`, `concurrency_limit_exceeded`, `idempotency_conflict`.
+`429`/`5xx` are retried automatically (honoring `Retry-After`); tune with
+`new PyAI({ apiKey, maxRetries })`.
+
+## CLI (`pyai`)
+
+Installing the package also provides a `pyai` command — a smoke tester that
+proves your key, the endpoint, and audio synthesis in one shot:
+
+```bash
+export PYAI_API_KEY=pyai_test_...
+npx pyai smoke
+# PASS  models.list  — 12 models
+# PASS  voices.list  — 38 voices
+# PASS  audio.speech — 45210 bytes of audio
+# All checks passed. Your key, the endpoint, and audio synthesis work.
+```
+
+Other commands:
+
+```bash
+pyai models
+pyai voices --gender female --region en_us
+pyai speak --text "Hello" --voice stock_sarah_style2 --out hello.wav
+pyai transcribe --url https://example.com/call.wav --diarize --poll
+```
+
+Auth comes from `PYAI_API_KEY` / `PYAI_BASE_URL` (or `--api-key` / `--base-url`).
+
+## Develop
+
+```bash
+npm install
+npm test         # node --test, fetch injected (no network)
+npm run build    # emits dist/ (incl. the pyai CLI bin)
+```

package/dist/cli.d.ts

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+/**
+ * pyai — CLI smoke tester for the PyAI API: proves your key, the endpoint,
+ * and audio synthesis in one command.
+ *
+ * Commands:
+ *   pyai smoke                          run models+voices+speak and report PASS/FAIL
+ *   pyai models                         list models
+ *   pyai voices [--gender g --region r] list voices
+ *   pyai speak --text T [--voice V] [--out f.wav]
+ *   pyai transcribe --url U [--diarize] [--poll]
+ *
+ * Auth: PYAI_API_KEY env (or --api-key). Base URL: PYAI_BASE_URL (or --base-url).
+ * Zero deps — uses the bundled SDK.
+ */
+export {};

package/dist/cli.js

@@ -0,0 +1,165 @@
+#!/usr/bin/env node
+/**
+ * pyai — CLI smoke tester for the PyAI API: proves your key, the endpoint,
+ * and audio synthesis in one command.
+ *
+ * Commands:
+ *   pyai smoke                          run models+voices+speak and report PASS/FAIL
+ *   pyai models                         list models
+ *   pyai voices [--gender g --region r] list voices
+ *   pyai speak --text T [--voice V] [--out f.wav]
+ *   pyai transcribe --url U [--diarize] [--poll]
+ *
+ * Auth: PYAI_API_KEY env (or --api-key). Base URL: PYAI_BASE_URL (or --base-url).
+ * Zero deps — uses the bundled SDK.
+ */
+import { writeFile } from "node:fs/promises";
+import PyAI, { PyAIError } from "./index.js";
+function parseArgs(argv) {
+    const flags = { _: [] };
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a.startsWith("--")) {
+            const key = a.slice(2);
+            const next = argv[i + 1];
+            if (next === undefined || next.startsWith("--")) {
+                flags[key] = true;
+            }
+            else {
+                flags[key] = next;
+                i++;
+            }
+        }
+        else {
+            flags._.push(a);
+        }
+    }
+    return flags;
+}
+function flag(flags, key) {
+    const v = flags[key];
+    return typeof v === "string" ? v : undefined;
+}
+function client(flags) {
+    const apiKey = flag(flags, "api-key") ?? process.env.PYAI_API_KEY;
+    if (!apiKey) {
+        fail("No API key. Set PYAI_API_KEY or pass --api-key pyai_test_...");
+    }
+    return new PyAI({ apiKey: apiKey, baseURL: flag(flags, "base-url") ?? process.env.PYAI_BASE_URL });
+}
+function out(msg) {
+    process.stdout.write(`${msg}\n`);
+}
+function fail(msg) {
+    process.stderr.write(`pyai: ${msg}\n`);
+    process.exit(1);
+}
+const USAGE = `pyai — PyAI API CLI
+
+Usage:
+  pyai smoke                              run a key/endpoint/audio smoke test
+  pyai models                             list models
+  pyai voices [--gender g] [--region r]   list voices
+  pyai speak --text T [--voice V] [--out f.wav]
+  pyai transcribe --url U [--diarize] [--poll]
+
+Auth: PYAI_API_KEY (or --api-key). Base: PYAI_BASE_URL (or --base-url).`;
+async function cmdModels(flags) {
+    const pyai = client(flags);
+    const res = await pyai.models.list();
+    out(JSON.stringify(res, null, 2));
+}
+async function cmdVoices(flags) {
+    const pyai = client(flags);
+    const res = await pyai.voices.list({ gender: flag(flags, "gender"), region: flag(flags, "region") });
+    out(JSON.stringify(res, null, 2));
+}
+async function cmdSpeak(flags) {
+    const pyai = client(flags);
+    const text = flag(flags, "text");
+    if (!text)
+        fail("speak requires --text");
+    const audio = await pyai.audio.speech({ input: text, voice: flag(flags, "voice") });
+    const outPath = flag(flags, "out") ?? "pyai-speak.wav";
+    await writeFile(outPath, Buffer.from(audio));
+    out(`wrote ${Buffer.from(audio).byteLength} bytes -> ${outPath}`);
+}
+async function cmdTranscribe(flags) {
+    const pyai = client(flags);
+    const url = flag(flags, "url");
+    if (!url)
+        fail("transcribe requires --url (an https audio URL)");
+    const job = await pyai.transcriptionJobs.create({ audio_url: url, diarize: flags.diarize === true });
+    out(`job ${job.job_id} (${job.status})`);
+    if (flags.poll !== true)
+        return;
+    for (let i = 0; i < 60; i++) {
+        await new Promise((r) => setTimeout(r, 2000));
+        const j = await pyai.transcriptionJobs.get(job.job_id);
+        if (j.status === "completed" || j.status === "failed" || j.status === "cancelled") {
+            out(JSON.stringify(j, null, 2));
+            return;
+        }
+    }
+    out(`job ${job.job_id} still running after polling; check later.`);
+}
+/** The headline: prove key + endpoint + audio in one command. */
+async function cmdSmoke(flags) {
+    const pyai = client(flags);
+    const checks = [];
+    const run = async (name, fn) => {
+        try {
+            checks.push({ name, ok: true, detail: await fn() });
+        }
+        catch (err) {
+            const detail = err instanceof PyAIError ? `${err.status} ${err.code ?? ""} ${err.message}` : err.message;
+            checks.push({ name, ok: false, detail });
+        }
+    };
+    await run("models.list", async () => {
+        const r = await pyai.models.list();
+        return `${r.data.length} models`;
+    });
+    await run("voices.list", async () => {
+        const r = await pyai.voices.list();
+        return `${r.data.length} voices`;
+    });
+    await run("audio.speech", async () => {
+        const audio = await pyai.audio.speech({ input: "PyAI smoke test." });
+        return `${Buffer.from(audio).byteLength} bytes of audio`;
+    });
+    for (const c of checks)
+        out(`${c.ok ? "PASS" : "FAIL"}  ${c.name}  — ${c.detail}`);
+    const allOk = checks.every((c) => c.ok);
+    out(allOk ? "\nAll checks passed. Your key, the endpoint, and audio synthesis work." : "\nSome checks failed (see above).");
+    if (!allOk)
+        process.exit(1);
+}
+async function main() {
+    const flags = parseArgs(process.argv.slice(2));
+    const cmd = flags._[0];
+    switch (cmd) {
+        case "smoke":
+            return cmdSmoke(flags);
+        case "models":
+            return cmdModels(flags);
+        case "voices":
+            return cmdVoices(flags);
+        case "speak":
+            return cmdSpeak(flags);
+        case "transcribe":
+            return cmdTranscribe(flags);
+        case "help":
+        case undefined:
+            out(USAGE);
+            return;
+        default:
+            fail(`unknown command: ${cmd}\n\n${USAGE}`);
+    }
+}
+main().catch((err) => {
+    if (err instanceof PyAIError) {
+        fail(`API error ${err.status}${err.code ? ` (${err.code})` : ""}: ${err.message}`);
+    }
+    fail(err.message);
+});

package/dist/index.d.ts

@@ -0,0 +1,146 @@
+/**
+ * @pyai/sdk — official TypeScript/JavaScript client for the PyAI API.
+ *
+ * Thin, dependency-free wrapper over the public OpenAI-compatible surface at
+ * https://api.pyai.com (contract: https://api.pyai.com/openapi.json). Runs in
+ * the browser and Node 22+ (uses global fetch + WebSocket). Keys are opaque —
+ * never parsed.
+ */
+export interface PyAIOptions {
+    /** A pyai_live_ or pyai_test_ key. */
+    apiKey: string;
+    /** Defaults to https://api.pyai.com. */
+    baseURL?: string;
+    /** Injectable for tests / custom transports. Defaults to global fetch. */
+    fetch?: typeof fetch;
+    /** Retries on 429 + 5xx (honors Retry-After). Default 2. */
+    maxRetries?: number;
+}
+/** Stable, machine-readable error. Branch on `code`, not `message`. */
+export declare class PyAIError extends Error {
+    readonly status: number;
+    readonly code: string | undefined;
+    readonly type: string | undefined;
+    readonly requestId: string | undefined;
+    constructor(status: number, message: string, code?: string, type?: string, requestId?: string);
+}
+export interface Voice {
+    id: string;
+    name?: string;
+    gender?: string;
+    region?: string;
+    [k: string]: unknown;
+}
+export interface ListResponse<T> {
+    object: "list";
+    data: T[];
+    has_more?: boolean;
+    next_cursor?: string | null;
+}
+export interface TranscriptionJob {
+    job_id: string;
+    status: "queued" | "running" | "completed" | "failed" | "cancelled";
+    created_at: number;
+    updated_at: number;
+    result?: unknown;
+    result_url?: string;
+    error?: string;
+}
+export interface SpeechParams {
+    input: string;
+    voice?: string;
+    model?: string;
+    response_format?: "wav" | "mp3" | "opus" | "aac" | "flac" | "pcm";
+    /**
+     * Output sample rate in Hz (8000-48000). Omit for the native 24 kHz. Most
+     * useful with `response_format: "pcm"` (raw 16-bit mono samples), e.g. set
+     * `8000`/`16000` for telephony pipelines.
+     */
+    sample_rate?: number;
+    speed?: number;
+}
+export interface CreateJobParams {
+    audio_url: string;
+    model?: string;
+    diarize?: boolean;
+    channel?: boolean;
+    numerals?: boolean;
+    output_formats?: Array<"json" | "srt" | "vtt">;
+    webhook_url?: string;
+}
+export interface RealtimeOptions {
+    /** "omni" (agentic, needs agentId) or "flow" (voice duplex). Default "omni". */
+    product?: "omni" | "flow";
+    /** Required for omni: the agent to drive. */
+    agentId?: string;
+    /** Extra query params (e.g. format, rate). */
+    query?: Record<string, string>;
+}
+export declare class PyAI {
+    private readonly apiKey;
+    private readonly baseURL;
+    private readonly fetchImpl;
+    private readonly maxRetries;
+    constructor(opts: PyAIOptions);
+    private authHeaders;
+    private request;
+    private toError;
+    private getJson;
+    models: {
+        list: () => Promise<ListResponse<{
+            id: string;
+        }>>;
+    };
+    voices: {
+        list: (params?: {
+            gender?: string;
+            region?: string;
+        }) => Promise<ListResponse<Voice>>;
+        get: (id: string) => Promise<Voice>;
+    };
+    audio: {
+        /** Text-to-speech. Returns the raw audio bytes (default WAV). */
+        speech: (params: SpeechParams) => Promise<ArrayBuffer>;
+        /**
+         * Text-to-speech, streamed. Resolves as soon as the response headers arrive
+         * with the body as a `ReadableStream` of audio bytes, so you can start
+         * playback or forward the audio at the first chunk (the engine's
+         * time-to-first-byte is tens of ms) instead of buffering the whole clip.
+         * Use `mp3` for the smoothest progressive playback. Returns an async
+         * iterable of Uint8Array chunks.
+         */
+        speechStream: (params: SpeechParams) => Promise<ReadableStream<Uint8Array>>;
+        /** Synchronous speech-to-text (multipart upload). */
+        transcriptions: {
+            create: (params: {
+                file: Blob;
+                filename?: string;
+                model?: string;
+            }) => Promise<{
+                text: string;
+                [k: string]: unknown;
+            }>;
+        };
+    };
+    transcriptionJobs: {
+        create: (params: CreateJobParams, opts?: {
+            idempotencyKey?: string;
+        }) => Promise<TranscriptionJob>;
+        get: (jobId: string) => Promise<TranscriptionJob>;
+        list: (params?: {
+            limit?: number;
+            cursor?: string;
+        }) => Promise<ListResponse<TranscriptionJob>>;
+    };
+    /** Build the realtime WebSocket URL for the chosen product. */
+    realtimeURL(opts?: RealtimeOptions): string;
+    /** The subprotocol that carries the key on a WS upgrade (browser-safe auth). */
+    realtimeSubprotocol(): string;
+    /**
+     * Open a realtime WebSocket. Uses the global WebSocket (browser, Node 22+).
+     * The key travels as a subprotocol so it works from the browser without
+     * custom headers.
+     */
+    connectRealtime(opts?: RealtimeOptions): WebSocket;
+}
+export default PyAI;

package/dist/index.js

@@ -0,0 +1,199 @@
+/**
+ * @pyai/sdk — official TypeScript/JavaScript client for the PyAI API.
+ *
+ * Thin, dependency-free wrapper over the public OpenAI-compatible surface at
+ * https://api.pyai.com (contract: https://api.pyai.com/openapi.json). Runs in
+ * the browser and Node 22+ (uses global fetch + WebSocket). Keys are opaque —
+ * never parsed.
+ */
+/** Stable, machine-readable error. Branch on `code`, not `message`. */
+export class PyAIError extends Error {
+    status;
+    code;
+    type;
+    requestId;
+    constructor(status, message, code, type, requestId) {
+        super(message);
+        this.name = "PyAIError";
+        this.status = status;
+        this.code = code;
+        this.type = type;
+        this.requestId = requestId;
+    }
+}
+const RETRYABLE = new Set([429, 500, 502, 503, 504]);
+export class PyAI {
+    apiKey;
+    baseURL;
+    fetchImpl;
+    maxRetries;
+    constructor(opts) {
+        if (!opts.apiKey)
+            throw new Error("apiKey is required");
+        this.apiKey = opts.apiKey;
+        this.baseURL = (opts.baseURL ?? "https://api.pyai.com").replace(/\/$/, "");
+        this.fetchImpl = opts.fetch ?? globalThis.fetch;
+        this.maxRetries = opts.maxRetries ?? 2;
+        if (!this.fetchImpl)
+            throw new Error("No fetch implementation available; pass opts.fetch");
+    }
+    // --- transport ----------------------------------------------------------
+    authHeaders(extra = {}) {
+        return { Authorization: `Bearer ${this.apiKey}`, ...extra };
+    }
+    async request(path, init, attempt = 0) {
+        const res = await this.fetchImpl(`${this.baseURL}${path}`, init);
+        if (res.ok)
+            return res;
+        if (RETRYABLE.has(res.status) && attempt < this.maxRetries) {
+            const retryAfter = Number(res.headers.get("retry-after"));
+            const delayMs = Number.isFinite(retryAfter) && retryAfter > 0 ? retryAfter * 1000 : 2 ** attempt * 250;
+            await new Promise((r) => setTimeout(r, delayMs));
+            return this.request(path, init, attempt + 1);
+        }
+        throw await this.toError(res);
+    }
+    async toError(res) {
+        const requestId = res.headers.get("x-request-id") ?? undefined;
+        let body;
+        try {
+            body = await res.json();
+        }
+        catch {
+            return new PyAIError(res.status, `HTTP ${res.status}`, undefined, undefined, requestId);
+        }
+        const b = body;
+        if (b.error) {
+            return new PyAIError(res.status, b.error.message ?? `HTTP ${res.status}`, b.error.code, b.error.type, requestId);
+        }
+        // RFC 7807 problem (control-plane): code is the last segment of `type`.
+        const code = typeof b.type === "string" ? b.type.split("/").pop() : undefined;
+        return new PyAIError(res.status, b.detail ?? b.title ?? `HTTP ${res.status}`, code, undefined, b.request_id ?? requestId);
+    }
+    async getJson(path) {
+        const res = await this.request(path, { headers: this.authHeaders() });
+        return (await res.json());
+    }
+    // --- models -------------------------------------------------------------
+    models = {
+        list: () => this.getJson("/v1/models"),
+    };
+    // --- voices -------------------------------------------------------------
+    voices = {
+        list: (params = {}) => {
+            const q = new URLSearchParams();
+            if (params.gender)
+                q.set("gender", params.gender);
+            if (params.region)
+                q.set("region", params.region);
+            const qs = q.toString();
+            return this.getJson(`/v1/voices${qs ? `?${qs}` : ""}`);
+        },
+        get: (id) => this.getJson(`/v1/voices/${encodeURIComponent(id)}`),
+    };
+    // --- audio --------------------------------------------------------------
+    audio = {
+        /** Text-to-speech. Returns the raw audio bytes (default WAV). */
+        speech: async (params) => {
+            const res = await this.request("/v1/audio/speech", {
+                method: "POST",
+                headers: this.authHeaders({ "Content-Type": "application/json" }),
+                body: JSON.stringify({ model: "pyai-voice", ...params }),
+            });
+            return res.arrayBuffer();
+        },
+        /**
+         * Text-to-speech, streamed. Resolves as soon as the response headers arrive
+         * with the body as a `ReadableStream` of audio bytes, so you can start
+         * playback or forward the audio at the first chunk (the engine's
+         * time-to-first-byte is tens of ms) instead of buffering the whole clip.
+         * Use `mp3` for the smoothest progressive playback. Returns an async
+         * iterable of Uint8Array chunks.
+         */
+        speechStream: async (params) => {
+            const res = await this.request("/v1/audio/speech", {
+                method: "POST",
+                headers: this.authHeaders({ "Content-Type": "application/json" }),
+                body: JSON.stringify({ model: "pyai-voice", ...params }),
+            });
+            if (!res.body)
+                throw new PyAIError(res.status, "Response had no body to stream");
+            return res.body;
+        },
+        /** Synchronous speech-to-text (multipart upload). */
+        transcriptions: {
+            create: async (params) => {
+                const form = new FormData();
+                form.set("file", params.file, params.filename ?? "audio.wav");
+                form.set("model", params.model ?? "pyai-hear");
+                const res = await this.request("/v1/audio/transcriptions", {
+                    method: "POST",
+                    headers: this.authHeaders(),
+                    body: form,
+                });
+                return (await res.json());
+            },
+        },
+    };
+    // --- async transcription jobs ------------------------------------------
+    transcriptionJobs = {
+        create: async (params, opts = {}) => {
+            const headers = this.authHeaders({ "Content-Type": "application/json" });
+            if (opts.idempotencyKey)
+                headers["Idempotency-Key"] = opts.idempotencyKey;
+            const res = await this.request("/v1/transcription/jobs", {
+                method: "POST",
+                headers,
+                body: JSON.stringify(params),
+            });
+            return (await res.json());
+        },
+        get: (jobId) => this.getJson(`/v1/transcription/jobs/${encodeURIComponent(jobId)}`),
+        list: (params = {}) => {
+            const q = new URLSearchParams();
+            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/transcription/jobs${qs ? `?${qs}` : ""}`);
+        },
+    };
+    // --- realtime (WebSocket) ----------------------------------------------
+    /** Build the realtime WebSocket URL for the chosen product. */
+    realtimeURL(opts = {}) {
+        const wsBase = this.baseURL.replace(/^http/, "ws");
+        const q = new URLSearchParams(opts.query ?? {});
+        if ((opts.product ?? "omni") === "omni") {
+            // Omni's native realtime surface is /v1/omni. agentId is an opaque label
+            // authorized by the key's org. format/rate are load-bearing on the
+            // connect URL, so default to browser-grade PCM16/24kHz.
+            if (opts.agentId)
+                q.set("agent_id", opts.agentId);
+            if (!q.has("format"))
+                q.set("format", "pcm16");
+            if (!q.has("rate"))
+                q.set("rate", "24000");
+            const qs = q.toString();
+            return `${wsBase}/v1/omni${qs ? `?${qs}` : ""}`;
+        }
+        q.set("model", "pyai-flow-realtime");
+        return `${wsBase}/v1/realtime?${q.toString()}`;
+    }
+    /** The subprotocol that carries the key on a WS upgrade (browser-safe auth). */
+    realtimeSubprotocol() {
+        return `pyai-key.${this.apiKey}`;
+    }
+    /**
+     * Open a realtime WebSocket. Uses the global WebSocket (browser, Node 22+).
+     * The key travels as a subprotocol so it works from the browser without
+     * custom headers.
+     */
+    connectRealtime(opts = {}) {
+        const WS = globalThis.WebSocket;
+        if (!WS)
+            throw new Error("No global WebSocket; use realtimeURL()/realtimeSubprotocol() with a WS library");
+        return new WS(this.realtimeURL(opts), [this.realtimeSubprotocol()]);
+    }
+}
+export default PyAI;

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@pyai/sdk",
+  "version": "0.1.0",
+  "description": "Official TypeScript/JavaScript SDK for the PyAI API (Hear, Speak, Cue, Omni).",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "pyai": "dist/cli.js"
+  },
+  "files": ["dist", "src", "README.md"],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/atomsai/pyai-platform-backend.git",
+    "directory": "sdk/typescript"
+  },
+  "homepage": "https://pyai.com",
+  "bugs": "https://github.com/atomsai/pyai-platform-backend/issues",
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "node --test test/**/*.test.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": ["pyai", "voice-ai", "tts", "stt", "speech", "openai-compatible"],
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,177 @@
+#!/usr/bin/env node
+/**
+ * pyai — CLI smoke tester for the PyAI API: proves your key, the endpoint,
+ * and audio synthesis in one command.
+ *
+ * Commands:
+ *   pyai smoke                          run models+voices+speak and report PASS/FAIL
+ *   pyai models                         list models
+ *   pyai voices [--gender g --region r] list voices
+ *   pyai speak --text T [--voice V] [--out f.wav]
+ *   pyai transcribe --url U [--diarize] [--poll]
+ *
+ * Auth: PYAI_API_KEY env (or --api-key). Base URL: PYAI_BASE_URL (or --base-url).
+ * Zero deps — uses the bundled SDK.
+ */
+
+import { writeFile } from "node:fs/promises";
+import PyAI, { PyAIError } from "./index.ts";
+
+interface Flags {
+  _: string[];
+  [k: string]: string | boolean | string[];
+}
+
+function parseArgs(argv: string[]): Flags {
+  const flags: Flags = { _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]!;
+    if (a.startsWith("--")) {
+      const key = a.slice(2);
+      const next = argv[i + 1];
+      if (next === undefined || next.startsWith("--")) {
+        flags[key] = true;
+      } else {
+        flags[key] = next;
+        i++;
+      }
+    } else {
+      (flags._ as string[]).push(a);
+    }
+  }
+  return flags;
+}
+
+function flag(flags: Flags, key: string): string | undefined {
+  const v = flags[key];
+  return typeof v === "string" ? v : undefined;
+}
+
+function client(flags: Flags): PyAI {
+  const apiKey = flag(flags, "api-key") ?? process.env.PYAI_API_KEY;
+  if (!apiKey) {
+    fail("No API key. Set PYAI_API_KEY or pass --api-key pyai_test_...");
+  }
+  return new PyAI({ apiKey: apiKey!, baseURL: flag(flags, "base-url") ?? process.env.PYAI_BASE_URL });
+}
+
+function out(msg: string): void {
+  process.stdout.write(`${msg}\n`);
+}
+function fail(msg: string): never {
+  process.stderr.write(`pyai: ${msg}\n`);
+  process.exit(1);
+}
+
+const USAGE = `pyai — PyAI API CLI
+
+Usage:
+  pyai smoke                              run a key/endpoint/audio smoke test
+  pyai models                             list models
+  pyai voices [--gender g] [--region r]   list voices
+  pyai speak --text T [--voice V] [--out f.wav]
+  pyai transcribe --url U [--diarize] [--poll]
+
+Auth: PYAI_API_KEY (or --api-key). Base: PYAI_BASE_URL (or --base-url).`;
+
+async function cmdModels(flags: Flags): Promise<void> {
+  const pyai = client(flags);
+  const res = await pyai.models.list();
+  out(JSON.stringify(res, null, 2));
+}
+
+async function cmdVoices(flags: Flags): Promise<void> {
+  const pyai = client(flags);
+  const res = await pyai.voices.list({ gender: flag(flags, "gender"), region: flag(flags, "region") });
+  out(JSON.stringify(res, null, 2));
+}
+
+async function cmdSpeak(flags: Flags): Promise<void> {
+  const pyai = client(flags);
+  const text = flag(flags, "text");
+  if (!text) fail("speak requires --text");
+  const audio = await pyai.audio.speech({ input: text!, voice: flag(flags, "voice") });
+  const outPath = flag(flags, "out") ?? "pyai-speak.wav";
+  await writeFile(outPath, Buffer.from(audio));
+  out(`wrote ${Buffer.from(audio).byteLength} bytes -> ${outPath}`);
+}
+
+async function cmdTranscribe(flags: Flags): Promise<void> {
+  const pyai = client(flags);
+  const url = flag(flags, "url");
+  if (!url) fail("transcribe requires --url (an https audio URL)");
+  const job = await pyai.transcriptionJobs.create({ audio_url: url!, diarize: flags.diarize === true });
+  out(`job ${job.job_id} (${job.status})`);
+  if (flags.poll !== true) return;
+  for (let i = 0; i < 60; i++) {
+    await new Promise((r) => setTimeout(r, 2000));
+    const j = await pyai.transcriptionJobs.get(job.job_id);
+    if (j.status === "completed" || j.status === "failed" || j.status === "cancelled") {
+      out(JSON.stringify(j, null, 2));
+      return;
+    }
+  }
+  out(`job ${job.job_id} still running after polling; check later.`);
+}
+
+/** The headline: prove key + endpoint + audio in one command. */
+async function cmdSmoke(flags: Flags): Promise<void> {
+  const pyai = client(flags);
+  const checks: Array<{ name: string; ok: boolean; detail: string }> = [];
+  const run = async (name: string, fn: () => Promise<string>) => {
+    try {
+      checks.push({ name, ok: true, detail: await fn() });
+    } catch (err) {
+      const detail = err instanceof PyAIError ? `${err.status} ${err.code ?? ""} ${err.message}` : (err as Error).message;
+      checks.push({ name, ok: false, detail });
+    }
+  };
+
+  await run("models.list", async () => {
+    const r = await pyai.models.list();
+    return `${r.data.length} models`;
+  });
+  await run("voices.list", async () => {
+    const r = await pyai.voices.list();
+    return `${r.data.length} voices`;
+  });
+  await run("audio.speech", async () => {
+    const audio = await pyai.audio.speech({ input: "PyAI smoke test." });
+    return `${Buffer.from(audio).byteLength} bytes of audio`;
+  });
+
+  for (const c of checks) out(`${c.ok ? "PASS" : "FAIL"}  ${c.name}  — ${c.detail}`);
+  const allOk = checks.every((c) => c.ok);
+  out(allOk ? "\nAll checks passed. Your key, the endpoint, and audio synthesis work." : "\nSome checks failed (see above).");
+  if (!allOk) process.exit(1);
+}
+
+async function main(): Promise<void> {
+  const flags = parseArgs(process.argv.slice(2));
+  const cmd = (flags._ as string[])[0];
+  switch (cmd) {
+    case "smoke":
+      return cmdSmoke(flags);
+    case "models":
+      return cmdModels(flags);
+    case "voices":
+      return cmdVoices(flags);
+    case "speak":
+      return cmdSpeak(flags);
+    case "transcribe":
+      return cmdTranscribe(flags);
+    case "help":
+    case undefined:
+      out(USAGE);
+      return;
+    default:
+      fail(`unknown command: ${cmd}\n\n${USAGE}`);
+  }
+}
+
+main().catch((err) => {
+  if (err instanceof PyAIError) {
+    fail(`API error ${err.status}${err.code ? ` (${err.code})` : ""}: ${err.message}`);
+  }
+  fail((err as Error).message);
+});

package/src/index.ts

@@ -0,0 +1,287 @@
+/**
+ * @pyai/sdk — official TypeScript/JavaScript client for the PyAI API.
+ *
+ * Thin, dependency-free wrapper over the public OpenAI-compatible surface at
+ * https://api.pyai.com (contract: https://api.pyai.com/openapi.json). Runs in
+ * the browser and Node 22+ (uses global fetch + WebSocket). Keys are opaque —
+ * never parsed.
+ */
+
+export interface PyAIOptions {
+  /** A pyai_live_ or pyai_test_ key. */
+  apiKey: string;
+  /** Defaults to https://api.pyai.com. */
+  baseURL?: string;
+  /** Injectable for tests / custom transports. Defaults to global fetch. */
+  fetch?: typeof fetch;
+  /** Retries on 429 + 5xx (honors Retry-After). Default 2. */
+  maxRetries?: number;
+}
+
+/** Stable, machine-readable error. Branch on `code`, not `message`. */
+export class PyAIError extends Error {
+  readonly status: number;
+  readonly code: string | undefined;
+  readonly type: string | undefined;
+  readonly requestId: string | undefined;
+  constructor(status: number, message: string, code?: string, type?: string, requestId?: string) {
+    super(message);
+    this.name = "PyAIError";
+    this.status = status;
+    this.code = code;
+    this.type = type;
+    this.requestId = requestId;
+  }
+}
+
+export interface Voice {
+  id: string;
+  name?: string;
+  gender?: string;
+  region?: string;
+  [k: string]: unknown;
+}
+
+export interface ListResponse<T> {
+  object: "list";
+  data: T[];
+  has_more?: boolean;
+  next_cursor?: string | null;
+}
+
+export interface TranscriptionJob {
+  job_id: string;
+  status: "queued" | "running" | "completed" | "failed" | "cancelled";
+  created_at: number;
+  updated_at: number;
+  result?: unknown;
+  result_url?: string;
+  error?: string;
+}
+
+export interface SpeechParams {
+  input: string;
+  voice?: string;
+  model?: string;
+  response_format?: "wav" | "mp3" | "opus" | "aac" | "flac" | "pcm";
+  /**
+   * Output sample rate in Hz (8000-48000). Omit for the native 24 kHz. Most
+   * useful with `response_format: "pcm"` (raw 16-bit mono samples), e.g. set
+   * `8000`/`16000` for telephony pipelines.
+   */
+  sample_rate?: number;
+  speed?: number;
+}
+
+export interface CreateJobParams {
+  audio_url: string;
+  model?: string;
+  diarize?: boolean;
+  channel?: boolean;
+  numerals?: boolean;
+  output_formats?: Array<"json" | "srt" | "vtt">;
+  webhook_url?: string;
+}
+
+export interface RealtimeOptions {
+  /** "omni" (agentic, needs agentId) or "flow" (voice duplex). Default "omni". */
+  product?: "omni" | "flow";
+  /** Required for omni: the agent to drive. */
+  agentId?: string;
+  /** Extra query params (e.g. format, rate). */
+  query?: Record<string, string>;
+}
+
+const RETRYABLE = new Set([429, 500, 502, 503, 504]);
+
+export class PyAI {
+  private readonly apiKey: string;
+  private readonly baseURL: string;
+  private readonly fetchImpl: typeof fetch;
+  private readonly maxRetries: number;
+
+  constructor(opts: PyAIOptions) {
+    if (!opts.apiKey) throw new Error("apiKey is required");
+    this.apiKey = opts.apiKey;
+    this.baseURL = (opts.baseURL ?? "https://api.pyai.com").replace(/\/$/, "");
+    this.fetchImpl = opts.fetch ?? globalThis.fetch;
+    this.maxRetries = opts.maxRetries ?? 2;
+    if (!this.fetchImpl) throw new Error("No fetch implementation available; pass opts.fetch");
+  }
+
+  // --- transport ----------------------------------------------------------
+
+  private authHeaders(extra: Record<string, string> = {}): Record<string, string> {
+    return { Authorization: `Bearer ${this.apiKey}`, ...extra };
+  }
+
+  private async request(path: string, init: RequestInit, attempt = 0): Promise<Response> {
+    const res = await this.fetchImpl(`${this.baseURL}${path}`, init);
+    if (res.ok) return res;
+    if (RETRYABLE.has(res.status) && attempt < this.maxRetries) {
+      const retryAfter = Number(res.headers.get("retry-after"));
+      const delayMs = Number.isFinite(retryAfter) && retryAfter > 0 ? retryAfter * 1000 : 2 ** attempt * 250;
+      await new Promise((r) => setTimeout(r, delayMs));
+      return this.request(path, init, attempt + 1);
+    }
+    throw await this.toError(res);
+  }
+
+  private async toError(res: Response): Promise<PyAIError> {
+    const requestId = res.headers.get("x-request-id") ?? undefined;
+    let body: unknown;
+    try {
+      body = await res.json();
+    } catch {
+      return new PyAIError(res.status, `HTTP ${res.status}`, undefined, undefined, requestId);
+    }
+    const b = body as {
+      error?: { message?: string; code?: string; type?: string };
+      title?: string;
+      detail?: string;
+      type?: string;
+      request_id?: string;
+    };
+    if (b.error) {
+      return new PyAIError(res.status, b.error.message ?? `HTTP ${res.status}`, b.error.code, b.error.type, requestId);
+    }
+    // RFC 7807 problem (control-plane): code is the last segment of `type`.
+    const code = typeof b.type === "string" ? b.type.split("/").pop() : undefined;
+    return new PyAIError(res.status, b.detail ?? b.title ?? `HTTP ${res.status}`, code, undefined, b.request_id ?? requestId);
+  }
+
+  private async getJson<T>(path: string): Promise<T> {
+    const res = await this.request(path, { headers: this.authHeaders() });
+    return (await res.json()) as T;
+  }
+
+  // --- models -------------------------------------------------------------
+
+  models = {
+    list: (): Promise<ListResponse<{ id: string }>> => this.getJson("/v1/models"),
+  };
+
+  // --- voices -------------------------------------------------------------
+
+  voices = {
+    list: (params: { gender?: string; region?: string } = {}): Promise<ListResponse<Voice>> => {
+      const q = new URLSearchParams();
+      if (params.gender) q.set("gender", params.gender);
+      if (params.region) q.set("region", params.region);
+      const qs = q.toString();
+      return this.getJson(`/v1/voices${qs ? `?${qs}` : ""}`);
+    },
+    get: (id: string): Promise<Voice> => this.getJson(`/v1/voices/${encodeURIComponent(id)}`),
+  };
+
+  // --- audio --------------------------------------------------------------
+
+  audio = {
+    /** Text-to-speech. Returns the raw audio bytes (default WAV). */
+    speech: async (params: SpeechParams): Promise<ArrayBuffer> => {
+      const res = await this.request("/v1/audio/speech", {
+        method: "POST",
+        headers: this.authHeaders({ "Content-Type": "application/json" }),
+        body: JSON.stringify({ model: "pyai-voice", ...params }),
+      });
+      return res.arrayBuffer();
+    },
+    /**
+     * Text-to-speech, streamed. Resolves as soon as the response headers arrive
+     * with the body as a `ReadableStream` of audio bytes, so you can start
+     * playback or forward the audio at the first chunk (the engine's
+     * time-to-first-byte is tens of ms) instead of buffering the whole clip.
+     * Use `mp3` for the smoothest progressive playback. Returns an async
+     * iterable of Uint8Array chunks.
+     */
+    speechStream: async (params: SpeechParams): Promise<ReadableStream<Uint8Array>> => {
+      const res = await this.request("/v1/audio/speech", {
+        method: "POST",
+        headers: this.authHeaders({ "Content-Type": "application/json" }),
+        body: JSON.stringify({ model: "pyai-voice", ...params }),
+      });
+      if (!res.body) throw new PyAIError(res.status, "Response had no body to stream");
+      return res.body as ReadableStream<Uint8Array>;
+    },
+    /** Synchronous speech-to-text (multipart upload). */
+    transcriptions: {
+      create: async (params: {
+        file: Blob;
+        filename?: string;
+        model?: string;
+      }): Promise<{ text: string; [k: string]: unknown }> => {
+        const form = new FormData();
+        form.set("file", params.file, params.filename ?? "audio.wav");
+        form.set("model", params.model ?? "pyai-hear");
+        const res = await this.request("/v1/audio/transcriptions", {
+          method: "POST",
+          headers: this.authHeaders(),
+          body: form,
+        });
+        return (await res.json()) as { text: string };
+      },
+    },
+  };
+
+  // --- async transcription jobs ------------------------------------------
+
+  transcriptionJobs = {
+    create: async (params: CreateJobParams, opts: { idempotencyKey?: string } = {}): Promise<TranscriptionJob> => {
+      const headers = this.authHeaders({ "Content-Type": "application/json" });
+      if (opts.idempotencyKey) headers["Idempotency-Key"] = opts.idempotencyKey;
+      const res = await this.request("/v1/transcription/jobs", {
+        method: "POST",
+        headers,
+        body: JSON.stringify(params),
+      });
+      return (await res.json()) as TranscriptionJob;
+    },
+    get: (jobId: string): Promise<TranscriptionJob> =>
+      this.getJson(`/v1/transcription/jobs/${encodeURIComponent(jobId)}`),
+    list: (params: { limit?: number; cursor?: string } = {}): Promise<ListResponse<TranscriptionJob>> => {
+      const q = new URLSearchParams();
+      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/transcription/jobs${qs ? `?${qs}` : ""}`);
+    },
+  };
+
+  // --- realtime (WebSocket) ----------------------------------------------
+
+  /** Build the realtime WebSocket URL for the chosen product. */
+  realtimeURL(opts: RealtimeOptions = {}): string {
+    const wsBase = this.baseURL.replace(/^http/, "ws");
+    const q = new URLSearchParams(opts.query ?? {});
+    if ((opts.product ?? "omni") === "omni") {
+      // Omni's native realtime surface is /v1/omni. agentId is an opaque label
+      // authorized by the key's org. format/rate are load-bearing on the
+      // connect URL, so default to browser-grade PCM16/24kHz.
+      if (opts.agentId) q.set("agent_id", opts.agentId);
+      if (!q.has("format")) q.set("format", "pcm16");
+      if (!q.has("rate")) q.set("rate", "24000");
+      const qs = q.toString();
+      return `${wsBase}/v1/omni${qs ? `?${qs}` : ""}`;
+    }
+    q.set("model", "pyai-flow-realtime");
+    return `${wsBase}/v1/realtime?${q.toString()}`;
+  }
+
+  /** The subprotocol that carries the key on a WS upgrade (browser-safe auth). */
+  realtimeSubprotocol(): string {
+    return `pyai-key.${this.apiKey}`;
+  }
+
+  /**
+   * Open a realtime WebSocket. Uses the global WebSocket (browser, Node 22+).
+   * The key travels as a subprotocol so it works from the browser without
+   * custom headers.
+   */
+  connectRealtime(opts: RealtimeOptions = {}): WebSocket {
+    const WS = (globalThis as { WebSocket?: typeof WebSocket }).WebSocket;
+    if (!WS) throw new Error("No global WebSocket; use realtimeURL()/realtimeSubprotocol() with a WS library");
+    return new WS(this.realtimeURL(opts), [this.realtimeSubprotocol()]);
+  }
+}
+
+export default PyAI;