@pyai/sdk 0.4.0 → 0.6.0

package/dist/index.d.ts

@@ -134,8 +134,19 @@ export interface SpeechParams {
      */
     temperature?: number;
 }
-export interface CreateJobParams {
+export type CreateJobParams = CreateJobOptions & ({
     audio_url: string;
+    gpt_live?: never;
+} | {
+    gpt_live: {
+        session_id: string;
+    };
+    audio_url?: never;
+});
+export interface CreateJobOptions {
+    /** Requires Trace entitlement; incompatible with channel/diarize. */
+    trace?: boolean;
+    rule_pack?: Record<string, unknown>;
     model?: string;
     diarize?: boolean;
     channel?: boolean;
@@ -535,6 +546,8 @@ export declare const OmniEvent: {
     readonly Hello: "hello";
     /** Ack for your `configure` frame (echoes the resolved `voice_id`). */
     readonly Configured: "configured";
+    /** Served voice capabilities changed, for example after synthesis fallback. */
+    readonly VoiceCapabilities: "voice_capabilities";
     /** Session is live; includes the resolved agent + audio caps. */
     readonly SessionStarted: "session_started";
     /** Turn boundary (user/assistant speaking). */
@@ -1085,16 +1098,21 @@ export interface AmdCall extends AmdCallSummary {
 }
 /**
  * A mid-call AMD decision event pushed on the stream (and to the per-call
- * TwiML `webhook`). Carries the coarse routing class; the machine subtype
- * (`voicemail`/`ivr`/`screening`/`music`) is on the stored call record
- * (`AmdCall`) and the `amd.call.completed` webhook instead.
+ * TwiML `webhook`). Carries the routing class and an optional machine subtype.
+ * Stored `AmdCall` records fold the subtype into `answered_by`.
  */
 export interface AmdDecisionEvent {
     event?: "amd";
     call_id?: string;
     answered_by?: AmdWireAnsweredBy;
     answered_by_twilio?: string | null;
+    subtype?: string;
+    /** A human or automated answering party was identified. */
+    party_detected?: boolean;
+    /** Classification events return false; detection does not establish recording readiness. */
+    voicemail_ready?: boolean;
     confidence?: number | null;
+    /** Processed inbound audio through the decision, not time since carrier answer. */
     decision_ms?: number | null;
     reason?: string | null;
     [k: string]: unknown;

package/dist/index.js

@@ -286,6 +286,8 @@ export const OmniEvent = {
     Hello: "hello",
     /** Ack for your `configure` frame (echoes the resolved `voice_id`). */
     Configured: "configured",
+    /** Served voice capabilities changed, for example after synthesis fallback. */
+    VoiceCapabilities: "voice_capabilities",
     /** Session is live; includes the resolved agent + audio caps. */
     SessionStarted: "session_started",
     /** Turn boundary (user/assistant speaking). */
@@ -495,6 +497,17 @@ export class OmniConnection {
                 try {
                     const parsed = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes.subarray(1)));
                     if (parsed?.event === OmniEvent.Transcript) {
+                        // The deployed engine also sends this bounded synthesis-input
+                        // advisory. It is not caller ASR or proof that speech was played.
+                        const keys = Object.keys(parsed);
+                        const text = omniTranscriptText(parsed.text);
+                        if (parsed.role === "assistant" && parsed.final === true && text?.trim()
+                            && keys.length === 4
+                            && keys.every((key) => ["event", "role", "text", "final"].includes(key))) {
+                            this.opts.onEvent?.(parsed);
+                            this.opts.onTranscript?.({ event: "transcript", role: "assistant", text, final: true, mode: "replace" });
+                            return;
+                        }
                         this.opts.onError?.(new Error("Omni transcript events must use a binary 0x02 frame"));
                         return;
                     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pyai/sdk",
-  "version": "0.4.0",
+  "version": "0.6.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",
@@ -17,7 +17,10 @@
   "files": [
     "dist",
     "src",
-    "README.md"
+    "README.md",
+    "CLI.md",
+    "CLI.schema.json",
+    "AGENT_GUIDE.md"
   ],
   "repository": {
     "type": "git",
@@ -28,6 +31,8 @@
   "bugs": "https://github.com/atomsai/pyai-platform-backend/issues",
   "author": "PyAI",
   "scripts": {
+    "gen:cli-assets": "node scripts/generate-cli-assets.mjs",
+    "check:cli-assets": "node scripts/generate-cli-assets.mjs --check",
     "build": "tsc -p tsconfig.build.json",
     "test": "node --test test/**/*.test.ts",
     "typecheck": "tsc --noEmit"

package/src/cli-config.ts

@@ -0,0 +1,283 @@
+import { constants } from "node:fs";
+import { chmod, lstat, mkdir, open, rename, unlink, type FileHandle } 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 {
+  readonly code: string;
+
+  constructor(code: string, message: string) {
+    super(message);
+    this.name = "CliConfigError";
+    this.code = code;
+  }
+}
+
+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 function validateApiKey(input: string): string {
+  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: string): string {
+  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: 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: string): string {
+  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(): string {
+  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(): CliConfig {
+  return { version: 1, active_profile: null, profiles: {} };
+}
+
+function hasCode(error: unknown, code: string): boolean {
+  return typeof error === "object" && error !== null && "code" in error && error.code === code;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function invalidConfig(): CliConfigError {
+  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: string): CliConfig {
+  try {
+    const parsed: unknown = 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: Record<string, CliProfile> = {};
+    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: CliProfile = {};
+      if ("api_key" in value) profile.api_key = validateApiKey(value.api_key as string);
+      if ("base_url" in value) profile.base_url = normalizeBaseURL(value.base_url as string);
+      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: number): void {
+  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: string): Promise<boolean> {
+  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: string): Promise<CliConfig> {
+  let file: FileHandle | undefined;
+  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(): Promise<CliConfig> {
+  return readConfigAt(configDirectory());
+}
+
+async function writeConfigAt(directory: string, config: CliConfig): Promise<void> {
+  const temporary = join(directory, `.config-${randomUUID()}.tmp`);
+  let file: FileHandle | undefined;
+  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: unknown) => {
+      if (!hasCode(error, "ENOENT")) throw error;
+    });
+  }
+}
+
+async function updateConfig(update: (config: CliConfig) => void): Promise<void> {
+  const directory = configDirectory();
+  const lockPath = join(directory, "config.json.lock");
+  let lock: FileHandle | undefined;
+  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: string, fields: CliProfile): Promise<void> {
+  validateProfileName(name);
+  const normalized: CliProfile = {};
+  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: string): Promise<void> {
+  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: string): Promise<void> {
+  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: { apiKey?: string; baseURL?: string; profile?: string; allowMissingProfile?: boolean; ignoreApiKey?: boolean } = {}): Promise<ResolvedConfig> {
+  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(): Promise<ProfileSummary[]> {
+  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/src/cli-dx.ts

@@ -0,0 +1,39 @@
+/** Offline discovery and copyable workflows; recipes never execute commands. */
+export const aliases: Record<string, string> = Object.assign(Object.create(null), {
+  login: "auth login", logout: "auth logout", whoami: "auth status", use: "profiles use",
+  say: "speak", hear: "transcribe",
+});
+export const shortFlags: Record<string, string> = Object.assign(Object.create(null), {
+  "-h": "--help", "-v": "--version", "-o": "--out", "-f": "--file",
+  "-t": "--text", "-p": "--profile", "-j": "--json",
+});
+export interface Recipe { name: string; title: string; description: string; commands: string[]; notes: string[]; docs_url: string }
+export const recipes: Recipe[] = [
+  { 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" }));