@pyai/sdk 0.2.0 → 0.2.2

package/src/cli.ts

@@ -1,18 +1,19 @@
 #!/usr/bin/env node
 /**
- * pyai — CLI for the PyAI API: proves your key, the endpoint, and audio in one
+ * 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 smoke [--tolerate-upstream]    run models+voices+speak and report PASS/FAIL
+ *                                       (--tolerate-upstream: transient 5xx/429 → WARN, not 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.
+ * Zero deps, uses the bundled SDK.
  */
 
 import { writeFile } from "node:fs/promises";
@@ -64,11 +65,12 @@ function fail(msg: string): never {
   process.exit(1);
 }
 
-const USAGE = `pyai — PyAI API CLI
+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 smoke [--tolerate-upstream]        run a key/endpoint/audio smoke test
+                                          (--tolerate-upstream: transient 5xx/429 warn, don't fail)
   pyai models                             list models
   pyai voices [--gender g] [--region r]   list voices
   pyai speak --text T [--voice V] [--out f.wav]
@@ -116,16 +118,53 @@ async function cmdTranscribe(flags: Flags): Promise<void> {
   out(`job ${job.job_id} still running after polling; check later.`);
 }
 
+// Transient upstream conditions: a momentary engine/capacity blip or network
+// hiccup, NOT a key/scope/contract problem. 5xx = engine unhealthy (e.g. Speak
+// "503 service_unavailable"), 429 = rate/capacity, a non-PyAIError = network.
+// These self-heal; the others (401/403/404/400) are real and must fail loudly.
+const TRANSIENT_STATUSES = new Set([429, 500, 502, 503, 504]);
+function isTransient(err: unknown): boolean {
+  if (err instanceof PyAIError) return TRANSIENT_STATUSES.has(err.status);
+  return true; // network / timeout / unknown, worth a retry, never a hard fail on its own
+}
+
+/** Retry `fn` on transient upstream errors with exponential backoff. Real
+ * (non-transient) errors throw immediately, we never paper over a bad key. */
+async function withRetry<T>(fn: () => Promise<T>, attempts = 4, baseMs = 800): Promise<T> {
+  let lastErr: unknown;
+  for (let i = 0; i < attempts; i++) {
+    try {
+      return await fn();
+    } catch (err) {
+      lastErr = err;
+      if (!isTransient(err) || i === attempts - 1) throw err;
+      await new Promise((r) => setTimeout(r, baseMs * 2 ** i));
+    }
+  }
+  throw lastErr;
+}
+
 /** 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 }> = [];
+  // CI/ops opt-in: a transient upstream blip (engine warming, a brief 503,
+  // rate-limit) should not red the build, it isn't the commit's fault. With this
+  // on, such failures are reported as WARN (exit 0); real key/scope/contract
+  // failures still FAIL (exit 1). Off by default so a developer running `pyai
+  // smoke` gets the strict, honest answer.
+  const tolerateUpstream = flags["tolerate-upstream"] === true || process.env.PYAI_SMOKE_TOLERATE_UPSTREAM === "1";
+  // Retry tuning is env-overridable (tests drive it fast; default rides brief blips).
+  const retryAttempts = Number(process.env.PYAI_SMOKE_RETRY_ATTEMPTS ?? 4);
+  const retryBaseMs = Number(process.env.PYAI_SMOKE_RETRY_BASE_MS ?? 800);
+  type Status = "PASS" | "WARN" | "FAIL";
+  const checks: Array<{ name: string; status: Status; detail: string }> = [];
   const run = async (name: string, fn: () => Promise<string>) => {
     try {
-      checks.push({ name, ok: true, detail: await fn() });
+      checks.push({ name, status: "PASS", detail: await withRetry(fn, retryAttempts, retryBaseMs) });
     } catch (err) {
-      const detail = err instanceof PyAIError ? `${err.status} ${err.code ?? ""} ${err.message}` : (err as Error).message;
-      checks.push({ name, ok: false, detail });
+      const detail = err instanceof PyAIError ? `${err.status} ${err.code ?? ""} ${err.message}`.trim() : (err as Error).message;
+      const status: Status = isTransient(err) && tolerateUpstream ? "WARN" : "FAIL";
+      checks.push({ name, status, detail });
     }
   };
 
@@ -142,10 +181,19 @@ async function cmdSmoke(flags: Flags): Promise<void> {
     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);
+  for (const c of checks) out(`${c.status}  ${c.name}, ${c.detail}`);
+  const failed = checks.filter((c) => c.status === "FAIL");
+  const warned = checks.filter((c) => c.status === "WARN");
+  // GitHub Actions annotation: a tolerated blip is still surfaced in the run UI.
+  for (const c of warned) out(`::warning title=PyAI smoke transient::${c.name}: ${c.detail}`);
+  if (failed.length === 0 && warned.length === 0) {
+    out("\nAll checks passed. Your key, the endpoint, and audio synthesis work.");
+  } else if (failed.length === 0) {
+    out(`\n${warned.length} transient upstream issue(s) tolerated (self-healing engine blip), not failing the build.`);
+  } else {
+    out("\nSome checks failed (see above).");
+    process.exit(1);
+  }
 }
 
 /** Turn an error into an actionable, code-first remediation hint. */
@@ -153,35 +201,35 @@ 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).";
+      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.";
+      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.";
+      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.";
+      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.";
+      return "Per-key monthly budget hit, raise the budget in the console.";
     case "insufficient_quota":
-      return "Plan quota exhausted — upgrade your plan.";
+      return "Plan quota exhausted, upgrade your plan.";
     case "rate_limit_exceeded":
-      return "Rate limited — back off and retry (honor Retry-After).";
+      return "Rate limited, back off and retry (honor Retry-After).";
     case "concurrency_limit_exceeded":
-      return "Too many concurrent sessions — retry shortly.";
+      return "Too many concurrent sessions, retry shortly.";
     case "daily_cap_exceeded":
-      return "Daily cap reached — wait until it resets.";
+      return "Daily cap reached, wait until it resets.";
     default:
       break;
   }
   switch (err.status) {
     case 401:
-      return "Invalid or missing key — check PYAI_API_KEY.";
+      return "Invalid or missing key, check PYAI_API_KEY.";
     case 403:
-      return "Forbidden — the key likely lacks the required scope.";
+      return "Forbidden, the key likely lacks the required scope.";
     case 404:
-      return "Not found — check PYAI_BASE_URL and the route.";
+      return "Not found, check PYAI_BASE_URL and the route.";
     case 429:
-      return "Rate/concurrency limited — back off and retry.";
+      return "Rate/concurrency limited, back off and retry.";
     default:
       return err.message;
   }
@@ -210,7 +258,7 @@ async function cmdDoctor(flags: Flags): Promise<void> {
   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.
+  // "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 : [];
@@ -245,14 +293,14 @@ async function cmdDoctor(flags: Flags): Promise<void> {
   });
 
   for (const c of checks) {
-    out(`${c.status.padEnd(4)}  ${c.name}  — ${c.detail}`);
+    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.`);
+    out(`\nDiagnosis: ${failed.length} check(s) failed, see the remediation hints above.`);
     process.exit(1);
   }
 }