@pyai/sdk 0.1.2 → 0.2.1

package/src/cli.ts

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