@pyai/sdk 0.4.0 → 0.6.0

package/src/cli-http.ts

@@ -0,0 +1,280 @@
+/** HTTP transport for the CLI. SDK request behavior remains independent. */
+
+export class CliError extends Error {
+  readonly code: string;
+  readonly exitCode: number;
+  readonly details?: Record<string, unknown>;
+
+  constructor(code: string, message: string, exitCode = 1, details?: Record<string, unknown>) {
+    super(message);
+    this.name = "CliError";
+    this.code = code;
+    this.exitCode = exitCode;
+    this.details = details;
+  }
+}
+
+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;
+}
+
+function record(value: unknown): Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+    ? value as Record<string, unknown> : {};
+}
+
+function string(value: unknown): string | undefined {
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+function timeout(value: number): number {
+  if (!Number.isFinite(value) || value <= 0 || value > 2_147_483_647) {
+    throw new CliError("invalid_timeout", "Request timeout must be a positive number of milliseconds (at most 2147483647).", 2);
+  }
+  return value;
+}
+
+function retryDelay(header: string | null, attempt: number): number {
+  if (header !== null) {
+    const seconds = Number(header);
+    if (header.trim() !== "" && Number.isFinite(seconds) && seconds >= 0) return seconds * 1000;
+    const date = Date.parse(header);
+    if (Number.isFinite(date)) return Math.max(0, date - Date.now());
+  }
+  return Math.min(200 * 2 ** attempt, 2000);
+}
+
+function pause(ms: number, signal: AbortSignal): Promise<void> {
+  return new Promise((resolve, reject) => {
+    if (signal.aborted) { reject(signal.reason); return; }
+    const finish = () => { signal.removeEventListener("abort", abort); resolve(); };
+    const timer = setTimeout(finish, ms);
+    const abort = () => { clearTimeout(timer); signal.removeEventListener("abort", abort); reject(signal.reason); };
+    signal.addEventListener("abort", abort, { once: true });
+  });
+}
+
+export class CliHttp {
+  private readonly baseURL: URL;
+  private readonly apiKey?: string;
+  private readonly timeoutMs: number;
+  private readonly maxRetries: number;
+
+  constructor(options: CliHttpOptions) {
+    try { this.baseURL = new URL(options.baseURL); }
+    catch { throw new CliError("invalid_base_url", "API base URL must be an absolute HTTP or HTTPS URL.", 2); }
+    if (!["http:", "https:"].includes(this.baseURL.protocol) || this.baseURL.username || this.baseURL.password
+      || this.baseURL.search || this.baseURL.hash) {
+      throw new CliError("invalid_base_url", "API base URL must use HTTP or HTTPS without credentials, a query, or a fragment.", 2);
+    }
+    this.apiKey = options.apiKey;
+    this.timeoutMs = timeout(options.timeoutMs ?? 30_000);
+    this.maxRetries = options.maxRetries ?? 2;
+    if (!Number.isSafeInteger(this.maxRetries) || this.maxRetries < 0) {
+      throw new CliError("invalid_retries", "Maximum retries must be a non-negative integer.", 2);
+    }
+  }
+
+  request(method: string, path: string, options: CliRequestOptions = {}): Promise<Response> {
+    return this.execute(method, path, options, false) as Promise<Response>;
+  }
+
+  json(method: string, path: string, options: CliRequestOptions = {}): Promise<any> {
+    return this.execute(method, path, options, true);
+  }
+
+  /** Validate previews through the same URL rules used by live requests. */
+  validatePath(path: string): string {
+    return this.url(path).toString();
+  }
+
+  private redact(value: string): string {
+    let result = value;
+    if (this.apiKey) {
+      result = result.split(this.apiKey).join("[REDACTED]");
+      result = result.split(encodeURIComponent(this.apiKey)).join("[REDACTED]");
+    }
+    return result.replace(/\bBearer\s+[^\s"',;<>]+/gi, "Bearer [REDACTED]")
+      .replace(/\bpyai_(?:test|live)_[A-Za-z0-9._~-]+/g, "[REDACTED]");
+  }
+
+  private url(path: string): URL {
+    if (!/^\/(?![\/\\])/.test(path) || /[\\\u0000-\u0020\u007f#]/.test(path)) {
+      throw new CliError("invalid_path", "API path must begin with a single / and contain no backslashes, whitespace, or fragment.", 2);
+    }
+    if (path.split("?", 1)[0]!.split("/").some((segment) => [".", ".."].includes(segment.replace(/%2e/gi, ".")))) {
+      throw new CliError("invalid_path", "API path must not contain . or .. traversal segments.", 2);
+    }
+    const url = new URL(this.baseURL.toString().replace(/\/+$/, "") + path);
+    if (url.origin !== this.baseURL.origin || url.username || url.password) {
+      throw new CliError("invalid_path", "API path must remain on the configured API origin.", 2);
+    }
+    for (const name of url.searchParams.keys()) {
+      if (name.toLowerCase() === "api_key") {
+        throw new CliError("unsafe_query", "Pass API keys through authentication, never through a URL query.", 2);
+      }
+    }
+    return url;
+  }
+
+  private transportError(error: unknown, signal: AbortSignal): CliError {
+    if (signal.aborted && signal.reason instanceof CliError) return signal.reason;
+    if (error instanceof CliError) return error;
+    const message = error instanceof Error ? error.message : "Connection failed.";
+    return new CliError("network_error", this.redact(`Network request failed: ${message}`), 4);
+  }
+
+  private async apiError(response: Response): Promise<CliError> {
+    const text = await response.text();
+    let payload: Record<string, unknown> = {};
+    try { payload = record(JSON.parse(text)); } catch { /* Non-JSON gateways still expose their HTTP status. */ }
+    const nested = record(payload.error);
+    const problemType = string(payload.type);
+    const problemCode = problemType?.match(/^https?:\/\/[^/]+\/problems\/([^/?#]+)$/)?.[1];
+    const fallbackCode = response.status === 401 ? "unauthorized" : response.status === 403 ? "forbidden" : `http_${response.status}`;
+    const code = this.redact(string(nested.code) ?? string(payload.code) ?? problemCode ?? fallbackCode);
+    const message = this.redact(string(nested.message) ?? string(payload.detail) ?? string(payload.message)
+      ?? string(payload.title) ?? `API request failed (HTTP ${response.status}).`);
+    const details: Record<string, unknown> = { status: response.status };
+    const requestId = response.headers.get("x-request-id") ?? response.headers.get("request-id")
+      ?? string(payload.request_id) ?? string(nested.request_id);
+    const retryAfter = response.headers.get("retry-after") ?? string(payload.retry_after);
+    if (requestId) details.request_id = this.redact(requestId);
+    if (retryAfter !== undefined && retryAfter !== null) details.retry_after = this.redact(retryAfter);
+    if (string(nested.type)) details.type = this.redact(nested.type as string);
+    if (typeof nested.param === "string") details.param = this.redact(nested.param);
+    return new CliError(code, message, response.status === 401 || response.status === 403 ? 3 : 1, details);
+  }
+
+  /** Preserve the request deadline after headers, including paused or stalled downloads. */
+  private stream(response: Response, abort: AbortController, cleanup: () => void): Response {
+    if (!response.body) { cleanup(); return response; }
+    const reader = response.body.getReader();
+    let finished = false;
+    let stop: () => void;
+    const finish = () => {
+      finished = true;
+      abort.signal.removeEventListener("abort", stop);
+      cleanup();
+    };
+    const body = new ReadableStream<Uint8Array>({
+      start: (controller) => {
+        stop = () => {
+          if (finished) return;
+          finish();
+          controller.error(this.transportError(abort.signal.reason, abort.signal));
+          void reader.cancel().catch(() => {});
+        };
+        abort.signal.addEventListener("abort", stop, { once: true });
+        if (abort.signal.aborted) stop();
+      },
+      pull: async (controller) => {
+        try {
+          const result = await reader.read();
+          if (finished) return;
+          if (result.done) { finish(); controller.close(); }
+          else controller.enqueue(result.value);
+        } catch (error) {
+          if (finished) return;
+          finish();
+          controller.error(this.transportError(error, abort.signal));
+        }
+      },
+      cancel: async (reason) => {
+        finish();
+        abort.abort();
+        await reader.cancel(reason).catch(() => {});
+      },
+    });
+    const result = new Response(body, { status: response.status, statusText: response.statusText, headers: response.headers });
+    Object.defineProperties(result, {
+      url: { value: response.url }, redirected: { value: response.redirected }, type: { value: response.type },
+    });
+    return result;
+  }
+
+  private async execute(method: string, path: string, options: CliRequestOptions, readJson: boolean): Promise<unknown> {
+    const url = this.url(path);
+    method = method.toUpperCase();
+    if (!/^[A-Z]+$/.test(method) || ["CONNECT", "TRACE", "TRACK"].includes(method)) {
+      throw new CliError("invalid_method", "Unsupported HTTP method.", 2);
+    }
+    if (options.auth !== false && !this.apiKey) {
+      throw new CliError("missing_api_key", "No API key. Set PYAI_API_KEY, configure a profile, or pass --api-key.", 3);
+    }
+    if (options.json !== undefined && options.body !== undefined) {
+      throw new CliError("invalid_body", "Provide either a JSON body or a raw body, not both.", 2);
+    }
+    let headers: Headers;
+    let body: BodyInit | undefined;
+    try {
+      headers = new Headers(options.headers);
+      headers.delete("authorization");
+      headers.delete("x-api-key");
+      if (options.auth !== false) headers.set("authorization", `Bearer ${this.apiKey}`);
+      body = options.json === undefined ? options.body : JSON.stringify(options.json);
+      if (options.json !== undefined) headers.set("content-type", "application/json");
+    } catch { throw new CliError("invalid_request", "Request headers or JSON body are invalid.", 2); }
+    if ((method === "GET" || method === "HEAD") && body !== undefined) {
+      throw new CliError("invalid_body", `${method} requests cannot have a body.`, 2);
+    }
+    const duration = timeout(options.timeoutMs ?? this.timeoutMs);
+    const deadline = Date.now() + duration;
+    const abort = new AbortController();
+    const timedOut = () => new CliError("timeout", `Request timed out after ${duration} ms.`, 4);
+    const timer = setTimeout(() => abort.abort(timedOut()), duration);
+    const cleanup = () => clearTimeout(timer);
+    const retries = method === "GET" || method === "HEAD" ? this.maxRetries : 0;
+    let streaming = false;
+    try {
+      for (let attempt = 0; ; attempt++) {
+        if (Date.now() >= deadline) throw timedOut();
+        let delay = retryDelay(null, attempt);
+        try {
+          const response = await fetch(url, { method, headers, body, signal: abort.signal, redirect: "manual" });
+          if (response.status >= 300 && response.status < 400) {
+            await response.body?.cancel();
+            throw new CliError("redirect_refused", "API redirects are refused. Configure the final API base URL directly.", 1, { status: response.status });
+          }
+          if ((response.status === 429 || response.status >= 500) && attempt < retries) {
+            delay = retryDelay(response.headers.get("retry-after"), attempt);
+            await response.body?.cancel();
+          } else {
+            if (!response.ok) throw await this.apiError(response);
+            if (readJson) {
+              const text = await response.text();
+              if (!text.trim()) return null;
+              try { return JSON.parse(text); }
+              catch { throw new CliError("invalid_response", "API returned an invalid JSON response.", 1, { status: response.status }); }
+            }
+            const result = this.stream(response, abort, cleanup);
+            streaming = response.body !== null;
+            return result;
+          }
+        } catch (error) {
+          const failure = this.transportError(error, abort.signal);
+          if (abort.signal.aborted || failure.code !== "network_error" || failure.exitCode !== 4 || attempt >= retries) throw failure;
+        }
+        const remaining = Math.max(0, deadline - Date.now());
+        const retryExceedsDeadline = delay >= remaining;
+        await pause(Math.min(delay, remaining), abort.signal);
+        // A clipped wait is terminal even if its timer runs before abort.
+        // Otherwise the next request can ignore Retry-After at the deadline.
+        if (retryExceedsDeadline) throw timedOut();
+      }
+    } finally {
+      if (!streaming) cleanup();
+    }
+  }
+}