@pyai/sdk 0.3.1 → 0.5.0

package/dist/cli-http.js

@@ -0,0 +1,286 @@
+/** HTTP transport for the CLI. SDK request behavior remains independent. */
+export class CliError extends Error {
+    code;
+    exitCode;
+    details;
+    constructor(code, message, exitCode = 1, details) {
+        super(message);
+        this.name = "CliError";
+        this.code = code;
+        this.exitCode = exitCode;
+        this.details = details;
+    }
+}
+function record(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        ? value : {};
+}
+function string(value) {
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+function timeout(value) {
+    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, attempt) {
+    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, signal) {
+    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 {
+    baseURL;
+    apiKey;
+    timeoutMs;
+    maxRetries;
+    constructor(options) {
+        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, path, options = {}) {
+        return this.execute(method, path, options, false);
+    }
+    json(method, path, options = {}) {
+        return this.execute(method, path, options, true);
+    }
+    /** Validate previews through the same URL rules used by live requests. */
+    validatePath(path) {
+        return this.url(path).toString();
+    }
+    redact(value) {
+        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]");
+    }
+    url(path) {
+        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;
+    }
+    transportError(error, signal) {
+        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);
+    }
+    async apiError(response) {
+        const text = await response.text();
+        let payload = {};
+        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 = { 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);
+        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. */
+    stream(response, abort, cleanup) {
+        if (!response.body) {
+            cleanup();
+            return response;
+        }
+        const reader = response.body.getReader();
+        let finished = false;
+        let stop;
+        const finish = () => {
+            finished = true;
+            abort.signal.removeEventListener("abort", stop);
+            cleanup();
+        };
+        const body = new ReadableStream({
+            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;
+    }
+    async execute(method, path, options, readJson) {
+        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;
+        let body;
+        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 timer = setTimeout(() => abort.abort(new CliError("timeout", `Request timed out after ${duration} ms.`, 4)), duration);
+        const cleanup = () => clearTimeout(timer);
+        const retries = method === "GET" || method === "HEAD" ? this.maxRetries : 0;
+        let streaming = false;
+        try {
+            for (let attempt = 0;; attempt++) {
+                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;
+                }
+                await pause(Math.min(delay, Math.max(0, deadline - Date.now())), abort.signal);
+            }
+        }
+        finally {
+            if (!streaming)
+                cleanup();
+        }
+    }
+}

package/dist/cli-init.d.ts

@@ -0,0 +1,27 @@
+export type CliTemplate = "agent" | "typescript" | "python";
+export interface CliTemplateManifest {
+    id: CliTemplate;
+    description: string;
+    files: readonly string[];
+}
+export interface ScaffoldOptions {
+    directory: string;
+    template?: CliTemplate;
+    dryRun?: boolean;
+    cwd?: string;
+}
+export interface ScaffoldResult {
+    directory: string;
+    template: CliTemplate;
+    files: string[];
+    created: boolean;
+    next_steps: string[];
+}
+export declare class CliInitError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/** Offline discovery; file contents are static and never include local credentials. */
+export declare const CLI_TEMPLATES: readonly CliTemplateManifest[];
+/** Create a new project only. Never authenticates, installs packages, or runs a shell. */
+export declare function scaffoldProject(options: ScaffoldOptions): Promise<ScaffoldResult>;