@pyai/sdk 0.4.0 → 0.6.0

package/README.md

@@ -99,6 +99,12 @@ Live `0x02` transcript bodies are plain UTF-8 caller-text deltas, not JSON.
 Coalesce successive deltas for the current caller turn. Bounded direct JSON
 bodies remain accepted for older bridges.
 
+Since version 0.5.1, the engine's four-field assistant synthesis advisory on
+`0x03` also reaches `onTranscript` with `role: "assistant"`, `final: true`,
+and `mode: "replace"`.
+This is text submitted for synthesis; it does not prove that playback completed.
+Caller transcripts continue to require the `0x02` carrier.
+
 `rate` configures caller input. A `rate: 16000` session still receives 24 kHz
 agent audio; `rate: 8000` receives 8 kHz. Read `hello.audio_out` before playback.
 Omni has no commit frame—keep streaming silence during caller pauses.
@@ -330,33 +336,30 @@ Common codes: `unauthorized`, `forbidden`, `credit_exhausted`,
 
 ## CLI (`pyai`)
 
-Installing the package also provides a `pyai` command. `pyai doctor` runs a
-deeper diagnosis, it introspects your key/scopes via `GET /v1/me` (skipped
-gracefully if the route isn't deployed yet), checks endpoint liveness, runs a
-Speak→Hear round-trip, and prints remediation hints for any failure:
+The package provides a `pyai` executable for engineers, CI, and coding agents.
+Install version 0.5.0 with `npm install -g @pyai/sdk@0.5.0`, then use
+`pyai login` for browser sign-in. Environment API keys work for unattended
+automation.
 
 ```bash
-export PYAI_API_KEY=pyai_test_...
-npx pyai doctor
-# PASS  key (/v1/me), env=test; 3 scope(s): hear:transcribe, speak:synthesize, hear:stream
-# PASS  models.list, 12 models
-# PASS  voices.list, 38 voices
-# PASS  speak→hear round-trip, synth 45210 bytes → "the quick brown fox…"
-# Diagnosis: healthy. Key, endpoint, and a Speak→Hear round-trip all work.
-
-npx pyai smoke   # lighter: models + voices + speak
+pyai speak "Your appointment is confirmed." -o confirmation.wav
+pyai hear confirmation.wav --text-only
+pyai login -p work
+pyai whoami -j
+pyai schema agents create -j
+pyai agents create --data @agent.json --dry-run -j
+pyai recipes speak
+pyai init voice-project --template agent
 ```
 
-Other commands:
-
-```bash
-pyai models
-pyai voices --gender female --region en_us
-pyai speak --text "Hello" --voice stock_emma_en_gb --out hello.wav
-pyai transcribe --url https://example.com/call.wav --diarize --poll
-```
+The [detailed CLI handbook](./CLI.md) covers installation, profiles, speech,
+transcription, Dub submission through download, Cast, resource configuration,
+JSON and stdin contracts, exit codes, and troubleshooting. For coding agents,
+use the [raw integration guide](https://pyai.com/cli-agent-guide.md) and live
+[OpenAPI contract](https://api.pyai.com/openapi.json).
 
-Auth comes from `PYAI_API_KEY` / `PYAI_BASE_URL` (or `--api-key` / `--base-url`).
+`pyai doctor` checks the key, catalogs, and a Speak-to-Hear round trip;
+`pyai smoke` checks catalogs and synthesis. Both make real API calls.
 
 ## Develop
 

package/dist/cli-config.d.ts

@@ -0,0 +1,47 @@
+export declare const DEFAULT_BASE_URL = "https://api.pyai.com";
+export declare class CliConfigError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export interface CliProfile {
+    api_key?: string;
+    base_url?: string;
+}
+export interface CliConfig {
+    version: 1;
+    active_profile: string | null;
+    profiles: Record<string, CliProfile>;
+}
+export interface ResolvedConfig {
+    apiKey?: string;
+    baseURL: string;
+    profile: string;
+    /** Provenance of the API key. The base URL is resolved independently. */
+    source: "explicit" | "environment" | "profile" | "none";
+}
+export interface ProfileSummary {
+    name: string;
+    active: boolean;
+    base_url: string;
+    has_api_key: boolean;
+}
+/** Keys are opaque: validation only ensures a bounded, header-safe value. */
+export declare function validateApiKey(input: string): string;
+/** The SDK adds /v1, so accept both documented API base URL forms. */
+export declare function normalizeBaseURL(input: string): string;
+export declare function validateProfileName(name: string): string;
+/** Raw configuration is for internal use; use listProfiles for display. */
+export declare function readConfig(): Promise<CliConfig>;
+/** Merge supplied fields and make this the active profile. */
+export declare function saveProfile(name: string, fields: CliProfile): Promise<void>;
+export declare function removeProfile(name: string): Promise<void>;
+export declare function useProfile(name: string): Promise<void>;
+export declare function resolveConfig(options?: {
+    apiKey?: string;
+    baseURL?: string;
+    profile?: string;
+    allowMissingProfile?: boolean;
+    ignoreApiKey?: boolean;
+}): Promise<ResolvedConfig>;
+/** Never reveal a key, including its prefix or suffix, in profile listings. */
+export declare function listProfiles(): Promise<ProfileSummary[]>;

package/dist/cli-config.js

@@ -0,0 +1,265 @@
+import { constants } from "node:fs";
+import { chmod, lstat, mkdir, open, rename, unlink } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+export const DEFAULT_BASE_URL = "https://api.pyai.com";
+export class CliConfigError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "CliConfigError";
+        this.code = code;
+    }
+}
+/** Keys are opaque: validation only ensures a bounded, header-safe value. */
+export function validateApiKey(input) {
+    if (typeof input !== "string" || input.length === 0 || input.length > 512 || /[\s\p{Cc}]/u.test(input)) {
+        throw new CliConfigError("invalid_api_key", "API keys must contain 1–512 characters without whitespace or control characters.");
+    }
+    return input;
+}
+/** The SDK adds /v1, so accept both documented API base URL forms. */
+export function normalizeBaseURL(input) {
+    const invalid = () => new CliConfigError("invalid_base_url", "Base URL must use HTTPS (or HTTP on localhost), without credentials, a query, or a fragment.");
+    if (typeof input !== "string" || !/^https?:\/\//i.test(input) || /[\s\p{Cc}?#]/u.test(input))
+        throw invalid();
+    let url;
+    try {
+        url = new URL(input);
+    }
+    catch {
+        throw invalid();
+    }
+    const authority = input.slice(input.indexOf("://") + 3).split("/")[0];
+    if (url.username || url.password || authority.includes("@"))
+        throw invalid();
+    const hostname = url.hostname.toLowerCase();
+    const loopback = hostname === "localhost" || hostname === "localhost." || hostname === "[::1]" || /^127\.\d+\.\d+\.\d+$/.test(hostname);
+    if (url.protocol !== "https:" && !(url.protocol === "http:" && loopback))
+        throw invalid();
+    const path = url.pathname.replace(/\/+$/, "").replace(/\/v1$/, "").replace(/\/+$/, "");
+    return `${url.origin}${path}`;
+}
+export function validateProfileName(name) {
+    if (typeof name !== "string" || !/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,63}$/.test(name)) {
+        throw new CliConfigError("invalid_profile", "Profile names must be 1–64 letters, numbers, dots, underscores, or hyphens, starting with a letter or number.");
+    }
+    return name;
+}
+function configDirectory() {
+    if (process.env.PYAI_CONFIG_DIR)
+        return resolve(process.env.PYAI_CONFIG_DIR);
+    return join(process.env.XDG_CONFIG_HOME || join(homedir(), ".config"), "pyai");
+}
+function emptyConfig() {
+    return { version: 1, active_profile: null, profiles: {} };
+}
+function hasCode(error, code) {
+    return typeof error === "object" && error !== null && "code" in error && error.code === code;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function invalidConfig() {
+    return new CliConfigError("config_invalid", "PyAI config.json is invalid or uses an unsupported version. Fix it or move it aside before retrying.");
+}
+function parseConfig(text) {
+    try {
+        const parsed = JSON.parse(text);
+        if (!isRecord(parsed) || parsed.version !== 1 || !isRecord(parsed.profiles))
+            throw invalidConfig();
+        if (parsed.active_profile !== null && typeof parsed.active_profile !== "string")
+            throw invalidConfig();
+        const profiles = {};
+        for (const [name, value] of Object.entries(parsed.profiles)) {
+            validateProfileName(name);
+            if (!isRecord(value) || Object.keys(value).some((key) => key !== "api_key" && key !== "base_url"))
+                throw invalidConfig();
+            const profile = {};
+            if ("api_key" in value)
+                profile.api_key = validateApiKey(value.api_key);
+            if ("base_url" in value)
+                profile.base_url = normalizeBaseURL(value.base_url);
+            profiles[name] = profile;
+        }
+        if (parsed.active_profile !== null) {
+            validateProfileName(parsed.active_profile);
+            if (!Object.hasOwn(profiles, parsed.active_profile))
+                throw invalidConfig();
+        }
+        return { version: 1, active_profile: parsed.active_profile, profiles };
+    }
+    catch {
+        // Never include JSON parser errors: they can contain the credential itself.
+        throw invalidConfig();
+    }
+}
+function verifyOwner(uid) {
+    if (typeof process.getuid === "function" && uid !== process.getuid()) {
+        throw new CliConfigError("config_unsafe", "PyAI configuration must be owned by the current user.");
+    }
+}
+async function inspectDirectory(directory) {
+    try {
+        const stat = await lstat(directory);
+        if (!stat.isDirectory() || stat.isSymbolicLink()) {
+            throw new CliConfigError("config_unsafe", "PyAI configuration directory must be a real directory, not a symbolic link.");
+        }
+        verifyOwner(stat.uid);
+        return true;
+    }
+    catch (error) {
+        if (hasCode(error, "ENOENT"))
+            return false;
+        throw error;
+    }
+}
+async function readConfigAt(directory) {
+    let file;
+    try {
+        if (!(await inspectDirectory(directory)))
+            return emptyConfig();
+        const path = join(directory, "config.json");
+        const stat = await lstat(path);
+        if (!stat.isFile() || stat.isSymbolicLink()) {
+            throw new CliConfigError("config_unsafe", "PyAI config.json must be a regular file, not a symbolic link.");
+        }
+        file = await open(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+        const openedStat = await file.stat();
+        verifyOwner(openedStat.uid);
+        if (!openedStat.isFile() || openedStat.size > 1024 * 1024)
+            throw invalidConfig();
+        return parseConfig(await file.readFile("utf8"));
+    }
+    catch (error) {
+        if (hasCode(error, "ENOENT"))
+            return emptyConfig();
+        if (error instanceof CliConfigError)
+            throw error;
+        throw new CliConfigError("config_read_failed", "Unable to read PyAI config.json. Check the configuration directory and file permissions.");
+    }
+    finally {
+        await file?.close();
+    }
+}
+/** Raw configuration is for internal use; use listProfiles for display. */
+export async function readConfig() {
+    return readConfigAt(configDirectory());
+}
+async function writeConfigAt(directory, config) {
+    const temporary = join(directory, `.config-${randomUUID()}.tmp`);
+    let file;
+    try {
+        file = await open(temporary, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY, 0o600);
+        await file.writeFile(`${JSON.stringify(config, null, 2)}\n`, "utf8");
+        await file.sync();
+        await file.close();
+        file = undefined;
+        await rename(temporary, join(directory, "config.json"));
+    }
+    finally {
+        await file?.close();
+        await unlink(temporary).catch((error) => {
+            if (!hasCode(error, "ENOENT"))
+                throw error;
+        });
+    }
+}
+async function updateConfig(update) {
+    const directory = configDirectory();
+    const lockPath = join(directory, "config.json.lock");
+    let lock;
+    try {
+        await mkdir(directory, { recursive: true, mode: 0o700 });
+        await inspectDirectory(directory);
+        await chmod(directory, 0o700);
+        // Every writer holds an exclusive lock across read, modification, and rename.
+        // A crashed writer leaves a visible lock instead of risking lost updates.
+        const deadline = Date.now() + 5000;
+        while (!lock) {
+            try {
+                lock = await open(lockPath, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY, 0o600);
+            }
+            catch (error) {
+                if (!hasCode(error, "EEXIST"))
+                    throw error;
+                if (Date.now() >= deadline) {
+                    throw new CliConfigError("config_busy", "PyAI configuration is locked by another process. Retry shortly; remove config.json.lock only if no PyAI configuration command is running.");
+                }
+                await new Promise((resolve) => setTimeout(resolve, 25));
+            }
+        }
+        const config = await readConfigAt(directory);
+        update(config);
+        await writeConfigAt(directory, config);
+    }
+    catch (error) {
+        if (error instanceof CliConfigError)
+            throw error;
+        throw new CliConfigError("config_write_failed", "Unable to save PyAI configuration. Check the configuration directory and file permissions.");
+    }
+    finally {
+        if (lock) {
+            await lock.close();
+            await unlink(lockPath);
+        }
+    }
+}
+/** Merge supplied fields and make this the active profile. */
+export async function saveProfile(name, fields) {
+    validateProfileName(name);
+    const normalized = {};
+    if (fields.api_key !== undefined)
+        normalized.api_key = validateApiKey(fields.api_key);
+    if (fields.base_url !== undefined)
+        normalized.base_url = normalizeBaseURL(fields.base_url);
+    await updateConfig((config) => {
+        const previous = Object.hasOwn(config.profiles, name) ? config.profiles[name] : undefined;
+        config.profiles[name] = { ...previous, ...normalized };
+        config.active_profile = name;
+    });
+}
+export async function removeProfile(name) {
+    validateProfileName(name);
+    await updateConfig((config) => {
+        if (!Object.hasOwn(config.profiles, name))
+            throw new CliConfigError("profile_not_found", "The selected PyAI profile does not exist. Use auth login to create it.");
+        delete config.profiles[name];
+        if (config.active_profile === name) {
+            config.active_profile = Object.hasOwn(config.profiles, "default") ? "default" : Object.keys(config.profiles).sort()[0] ?? null;
+        }
+    });
+}
+export async function useProfile(name) {
+    validateProfileName(name);
+    await updateConfig((config) => {
+        if (!Object.hasOwn(config.profiles, name))
+            throw new CliConfigError("profile_not_found", "The selected PyAI profile does not exist. Use auth login to create it.");
+        config.active_profile = name;
+    });
+}
+export async function resolveConfig(options = {}) {
+    const config = await readConfig();
+    const selected = options.profile ?? (process.env.PYAI_PROFILE || undefined);
+    const profile = validateProfileName(selected ?? config.active_profile ?? "default");
+    const stored = Object.hasOwn(config.profiles, profile) ? config.profiles[profile] : undefined;
+    if (selected !== undefined && !stored && !options.allowMissingProfile) {
+        throw new CliConfigError("profile_not_found", "The selected PyAI profile does not exist. Use auth login to create it.");
+    }
+    const environmentKey = process.env.PYAI_API_KEY || undefined;
+    const apiKey = options.ignoreApiKey ? undefined : options.apiKey ?? environmentKey ?? stored?.api_key;
+    const baseURL = normalizeBaseURL(options.baseURL ?? (process.env.PYAI_BASE_URL || undefined) ?? stored?.base_url ?? DEFAULT_BASE_URL);
+    const source = options.ignoreApiKey ? "none" : options.apiKey !== undefined ? "explicit" : environmentKey !== undefined ? "environment" : stored?.api_key !== undefined ? "profile" : "none";
+    return { ...(apiKey !== undefined ? { apiKey: validateApiKey(apiKey) } : {}), baseURL, profile, source };
+}
+/** Never reveal a key, including its prefix or suffix, in profile listings. */
+export async function listProfiles() {
+    const config = await readConfig();
+    return Object.keys(config.profiles).sort().map((name) => ({
+        name,
+        active: config.active_profile === name,
+        base_url: config.profiles[name].base_url ?? DEFAULT_BASE_URL,
+        has_api_key: config.profiles[name].api_key !== undefined,
+    }));
+}

package/dist/cli-dx.d.ts

@@ -0,0 +1,12 @@
+/** Offline discovery and copyable workflows; recipes never execute commands. */
+export declare const aliases: Record<string, string>;
+export declare const shortFlags: Record<string, string>;
+export interface Recipe {
+    name: string;
+    title: string;
+    description: string;
+    commands: string[];
+    notes: string[];
+    docs_url: string;
+}
+export declare const recipes: Recipe[];

package/dist/cli-dx.js

@@ -0,0 +1,38 @@
+/** Offline discovery and copyable workflows; recipes never execute commands. */
+export const aliases = Object.assign(Object.create(null), {
+    login: "auth login", logout: "auth logout", whoami: "auth status", use: "profiles use",
+    say: "speak", hear: "transcribe",
+});
+export const shortFlags = Object.assign(Object.create(null), {
+    "-h": "--help", "-v": "--version", "-o": "--out", "-f": "--file",
+    "-t": "--text", "-p": "--profile", "-j": "--json",
+});
+export const recipes = [
+    { name: "calling", title: "Set up a managed phone Agent", description: "Inspect numbers, bind a profile, and retrieve call artifacts through the public API.",
+        commands: ["pyai whoami --json", "pyai numbers list --json", "pyai numbers search --country US --limit 5 --json", "pyai agents list --json", "pyai numbers bind NUMBER_ID --data @binding.json --dry-run --json", "pyai calls create --data @call.json --idempotency-key CALL_REQUEST_KEY --dry-run --json", "pyai calls get RETURNED_CALL_ID --json", "pyai omni get OMNI_CALL_ID --json"],
+        notes: ["Replace all placeholder IDs with returned values. binding.json is {agent_id: RETURNED_AGENT_ID}; call.json requires from_number_id, to, agent_id and use_case from live OpenAPI.", "Remove --dry-run for authorized changes. numbers buy and calls create require --confirm and --idempotency-key. Calls reach real destinations; sandbox keys do not grant telephony permissions.", "Requires telephony:manage; session artifacts require omni:read. Preserve artifacts.omni_call_id. Read the decision tree for purchase, polling, recording, and inbound-call steps.", "Use calls wait ID --wait-timeout 120 --poll-interval 3 --json for bounded waiting. dispatch_unknown requires inspection, never automatic redial."] },
+    { name: "omni", title: "Build a realtime conversation with the SDK", description: "Use the official SDK for binary framing, subprotocol auth, and typed events.",
+        commands: ["pyai schema --openapi --json", "pyai init voice-demo --template typescript", "pyai voices --json"],
+        notes: ["The starter supplies Hear/Speak examples. Add realtime through pyai.omni.connect({ rate, configure }); see the linked decision tree's SDK pattern.", "Wait for configured before non-silent input. Stream paced digital silence during pauses. Read hello.audio_out and clear queued playback on barge_in/flush.", "Browser code uses an ephemeral token minted by omni.createSession on your server. Never put live keys in browser code or URLs.", "Machine framing contract: https://api.pyai.com/omni-frames.json. For an existing Twilio number use @pyai/twilio and the official twilio-omni-voice-agent example."] },
+    { name: "auth", title: "Sign in and check access", description: "Save a named profile and inspect the current credential.",
+        commands: ["pyai login --profile work", "pyai whoami --profile work --json", "pyai use work"],
+        notes: ["Browser login requires the CLI login API and console deployment. Use --no-browser on remote terminals.", "For unattended runs, supply PYAI_API_KEY through the environment. Environment values override saved profiles."] },
+    { name: "speak", title: "Turn text into audio", description: "Speak a line, narrate a text file, or pipe text from another command.",
+        commands: ['pyai speak "Hello from PyAI" -o hello.wav', "pyai speak --text-file script.txt -o narration.wav", 'printf "Build complete.\\n" | pyai speak -o build.wav'],
+        notes: ["Files must have a new output name unless you pass --force. Default output is pyai-speak.wav.", "Use pyai voices --json to choose a current voice; add --voice ID."] },
+    { name: "transcribe", title: "Get a transcript", description: "Print just the words or retain structured output for automation.",
+        commands: ["pyai hear call.wav --text-only > transcript.txt", "pyai transcribe call.wav --json > transcript.json", 'pyai transcribe "https://example.com/call.wav" --wait --text-only'],
+        notes: ["Replace the example URL with a reachable audio URL. Hosted audio uses an asynchronous job.", "--text-only requires --wait for URLs; large offloaded results retain a job reference instead of following an external URL with credentials."] },
+    { name: "dub", title: "Dub audio in one command", description: "Submit a Dub job, wait for completion, and download the audio.",
+        commands: ["pyai request GET /healthz/dub --json", "pyai dub original.wav --from en --to hi -o dubbed.wav --wait-timeout 600"],
+        notes: ["Check the live health response for available input and output languages before choosing them. Requires dub:render.", "On a timeout, resume with pyai dub wait JOB_ID and pyai dub audio JOB_ID -o dubbed.wav; do not resubmit the source."] },
+    { name: "agent", title: "Start a project for a coding agent", description: "Create local context and request examples without a network call.",
+        commands: ["pyai init voice-demo --template agent", "pyai schema agents create --json", "pyai agents create --data @voice-demo/agent.json --dry-run --json"],
+        notes: ["The destination directory must be new. The starter writes no credentials and installs no dependencies.", "Read the generated PYAI.md first. Fetch live OpenAPI before adding fields or endpoints; remove --dry-run only when ready to create the profile."] },
+    { name: "inspect", title: "Discover before you call", description: "Inspect commands offline and fetch the current API contract.",
+        commands: ["pyai schema speak --json", "pyai schema agents --json", "pyai schema --openapi --json > openapi.json", "pyai request GET /v1/me --json"],
+        notes: ["Local schema and recipes work without credentials. Live OpenAPI needs a network connection but no API key.", "The CLI manages Agent profiles; use the SDK or WebSocket API for a live Omni audio session."] },
+    { name: "ci", title: "Use PyAI in a build", description: "Check access and produce an audio artifact with machine-readable output.",
+        commands: ["pyai whoami --json", 'pyai speak "Your build is ready" -o build.wav --json', "pyai doctor --json"],
+        notes: ["Set PYAI_API_KEY through the CI secret store; do not put it in source or shell arguments.", "doctor synthesizes and transcribes a sample, which consumes usage. Use whoami for an authentication-only check.", "Install the CLI with npm install -g @pyai/sdk@0.6.0 and pin that version in repeatable builds."] },
+].map(recipe => ({ ...recipe, docs_url: "https://pyai.com/agents/speech-calling.md" }));

package/dist/cli-http.d.ts

@@ -0,0 +1,38 @@
+/** HTTP transport for the CLI. SDK request behavior remains independent. */
+export declare class CliError extends Error {
+    readonly code: string;
+    readonly exitCode: number;
+    readonly details?: Record<string, unknown>;
+    constructor(code: string, message: string, exitCode?: number, details?: Record<string, unknown>);
+}
+export interface CliHttpOptions {
+    baseURL: string;
+    apiKey?: string;
+    timeoutMs?: number;
+    maxRetries?: number;
+}
+export interface CliRequestOptions {
+    json?: unknown;
+    body?: BodyInit;
+    headers?: Record<string, string>;
+    auth?: boolean;
+    timeoutMs?: number;
+}
+export declare class CliHttp {
+    private readonly baseURL;
+    private readonly apiKey?;
+    private readonly timeoutMs;
+    private readonly maxRetries;
+    constructor(options: CliHttpOptions);
+    request(method: string, path: string, options?: CliRequestOptions): Promise<Response>;
+    json(method: string, path: string, options?: CliRequestOptions): Promise<any>;
+    /** Validate previews through the same URL rules used by live requests. */
+    validatePath(path: string): string;
+    private redact;
+    private url;
+    private transportError;
+    private apiError;
+    /** Preserve the request deadline after headers, including paused or stalled downloads. */
+    private stream;
+    private execute;
+}