smoltalk 0.4.0 → 0.4.2

package/dist/smolError.js

@@ -1,30 +1,155 @@
+/**
+ * Base error type for all smoltalk failures. Carries a curated, safe-to-log
+ * snapshot of the HTTP response on `status` / `headers` / `retryAfterMs` /
+ * `requestId`.
+ *
+ * **Security note on `cause`:** the raw provider error is attached at `cause`
+ * as a non-enumerable property (using the ES2022 `Error` `{ cause }` option),
+ * so `JSON.stringify(err)` and most error serializers (Sentry, pino, Bunyan)
+ * will NOT walk it. The custom `toJSON()` below similarly omits both `cause`
+ * and `stack`. The provider error can still contain `authorization` headers,
+ * cookies, and echoed prompt bodies — direct access (`err.cause`) and Node's
+ * native `console.error` chain still work, so handle deliberately.
+ */
 export class SmolError extends Error {
-    constructor(message) {
+    /** HTTP status code from the provider response, when available. */
+    status;
+    /**
+     * Curated, safe-to-log subset of the provider response headers. For the full,
+     * unredacted set (including any session cookies the provider sent), reach for
+     * the raw provider error on `cause` — but note that `cause` is non-enumerable
+     * specifically to keep it out of casual logging.
+     */
+    headers;
+    /**
+     * Suggested wait before retrying, in milliseconds, parsed from the
+     * `retry-after-ms` / `retry-after` response headers (when available).
+     * Always non-negative and capped at a sane ceiling (see `httpError.ts`).
+     */
+    retryAfterMs;
+    /** Provider request id (`x-request-id` / `request-id`), useful for support tickets. */
+    requestId;
+    constructor(message, options = {}) {
         super(message);
         this.name = "SmolTalkError";
+        this.status = options.status;
+        this.headers = options.headers;
+        this.retryAfterMs = options.retryAfterMs;
+        this.requestId = options.requestId;
+        if (options.cause !== undefined) {
+            // Explicit non-enumerable install. A plain `this.cause = options.cause`
+            // would create an *enumerable* own property — `JSON.stringify(err)` and
+            // structured loggers (`logger.error({ err })`) would then walk `cause`
+            // and re-leak the raw provider error (including the unredacted
+            // `set-cookie` / `authorization` headers the allowlist stripped from
+            // `headers`). This restores the behavior the spec intends for
+            // `new Error(msg, { cause })`: `cause` is the escape hatch, not the
+            // default-serialized field.
+            Object.defineProperty(this, "cause", {
+                value: options.cause,
+                enumerable: false,
+                writable: true,
+                configurable: true,
+            });
+        }
+    }
+    /**
+     * Custom JSON serializer. Returns only the curated/safe fields — never
+     * `cause` or `stack`, both of which can leak secrets (auth headers in
+     * `cause`, file system paths and source snippets in `stack`).
+     */
+    toJSON() {
+        return {
+            name: this.name,
+            message: this.message,
+            status: this.status,
+            headers: this.headers,
+            retryAfterMs: this.retryAfterMs,
+            requestId: this.requestId,
+        };
+    }
+    /**
+     * Custom Node.js inspect. Node's default error formatter walks `cause` and
+     * prints it even when the property is non-enumerable, which would re-leak
+     * the raw provider error through `console.error(err)` / `util.inspect(err)`.
+     * Override that path to show a placeholder; callers who want the full chain
+     * can still reach for `err.cause` explicitly.
+     */
+    [Symbol.for("nodejs.util.inspect.custom")]() {
+        const fields = [`${this.name}: ${this.message}`];
+        if (this.status !== undefined)
+            fields.push(`status: ${this.status}`);
+        if (this.requestId !== undefined)
+            fields.push(`requestId: ${JSON.stringify(this.requestId)}`);
+        if (this.retryAfterMs !== undefined)
+            fields.push(`retryAfterMs: ${this.retryAfterMs}`);
+        if (this.headers !== undefined)
+            fields.push(`headers: ${JSON.stringify(this.headers)}`);
+        if (this.cause !== undefined)
+            fields.push("cause: [hidden — access err.cause directly]");
+        return fields.join("\n  ");
     }
 }
 export class SmolStructuredOutputError extends SmolError {
-    constructor(message) {
-        super(message);
+    constructor(message, options = {}) {
+        super(message, options);
         this.name = "SmolStructuredOutputError";
     }
 }
 export class SmolTimeoutError extends SmolError {
-    constructor(message) {
-        super(message);
+    constructor(message, options = {}) {
+        super(message, options);
         this.name = "SmolTimeoutError";
     }
 }
 export class SmolContentPolicyError extends SmolError {
-    constructor(message) {
-        super(message);
+    constructor(message, options = {}) {
+        super(message, options);
         this.name = "SmolContentPolicyError";
     }
 }
 export class SmolContextWindowExceededError extends SmolError {
-    constructor(message) {
-        super(message);
+    constructor(message, options = {}) {
+        super(message, options);
         this.name = "SmolContextWindowExceededError";
     }
 }
+/** Rate limited (HTTP 429). Inspect `retryAfterMs` to back off. */
+export class SmolRateLimitError extends SmolError {
+    constructor(message, options = {}) {
+        super(message, options);
+        this.name = "SmolRateLimitError";
+    }
+}
+/** Provider temporarily overloaded/unavailable (HTTP 503, or Anthropic's 529). */
+export class SmolOverloadedError extends SmolError {
+    constructor(message, options = {}) {
+        super(message, options);
+        this.name = "SmolOverloadedError";
+    }
+}
+/** Authentication or permission failure (HTTP 401/403). */
+export class SmolAuthError extends SmolError {
+    constructor(message, options = {}) {
+        super(message, options);
+        this.name = "SmolAuthError";
+    }
+}
+/**
+ * Pick the most specific SmolError subclass for an HTTP status code, so retry
+ * code can `instanceof`-dispatch instead of sniffing magic status numbers.
+ * Falls back to the base `SmolError` for unclassified statuses.
+ */
+export function smolErrorForStatus(message, options = {}) {
+    const status = options.status;
+    if (status === 429) {
+        return new SmolRateLimitError(message, options);
+    }
+    if (status === 503 || status === 529) {
+        return new SmolOverloadedError(message, options);
+    }
+    if (status === 401 || status === 403) {
+        return new SmolAuthError(message, options);
+    }
+    return new SmolError(message, options);
+}

package/dist/util/httpError.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Best-effort extraction of HTTP status and headers from a provider SDK error.
+ *
+ * Each provider SDK shapes its errors slightly differently:
+ * - OpenAI / Anthropic: `status` (number) + `headers` (web `Headers`)
+ * - Google Gemini (`@google/genai`): `status` (number), no headers
+ * - Ollama: `status_code` (number), no headers
+ */
+export interface HttpErrorFields {
+    status?: number;
+    /** Allowlisted, safe-to-log subset of response headers (see `ALLOWED_HEADERS`). */
+    headers?: Record<string, string>;
+    /**
+     * Suggested wait before retrying, in milliseconds, parsed from the
+     * `retry-after-ms` / `retry-after` response headers. Only ever populated for
+     * OpenAI/Anthropic — Google and Ollama errors carry no headers to parse.
+     * Always non-negative and capped at `MAX_RETRY_AFTER_MS`.
+     */
+    retryAfterMs?: number;
+    /** Provider request id (`x-request-id` / `request-id`), useful for support tickets. */
+    requestId?: string;
+}
+export declare function extractHttpErrorFields(error: unknown): HttpErrorFields;

package/dist/util/httpError.js

@@ -0,0 +1,237 @@
+/**
+ * Explicit allowlist (not denylist, not prefix-wildcard). smoltalk can be
+ * pointed at proxies (LiteLLM, OpenRouter) that re-emit upstream headers
+ * verbatim, and some APIs echo credentials back on errors — a denylist would
+ * pass `authorization`, `x-api-key`, forwarded `llm_provider-*` headers, etc.
+ * (cf. Traefik GHSA-p6hg-qh38-555r). A prefix wildcard like `x-ratelimit-*`
+ * is safer than a denylist but still risks absorbing a future
+ * `x-ratelimit-organization` style header that carries an identifier or
+ * secret. Capture only known-safe headers with diagnostic value; the raw
+ * provider error is reachable on `SmolError.cause` (non-enumerable) as the
+ * escape hatch for callers that explicitly opt in.
+ */
+const ALLOWED_HEADERS = new Set([
+    // Retry hints
+    "retry-after",
+    "retry-after-ms",
+    // Request correlation
+    "request-id",
+    "x-request-id",
+    // Diagnostic
+    "content-type",
+    // OpenAI rate-limit family (exhaustive as of writing — new headers added
+    // by providers must be added explicitly here).
+    "x-ratelimit-limit-requests",
+    "x-ratelimit-limit-tokens",
+    "x-ratelimit-remaining-requests",
+    "x-ratelimit-remaining-tokens",
+    "x-ratelimit-reset-requests",
+    "x-ratelimit-reset-tokens",
+    // Anthropic rate-limit family
+    "anthropic-ratelimit-requests-limit",
+    "anthropic-ratelimit-requests-remaining",
+    "anthropic-ratelimit-requests-reset",
+    "anthropic-ratelimit-tokens-limit",
+    "anthropic-ratelimit-tokens-remaining",
+    "anthropic-ratelimit-tokens-reset",
+    "anthropic-ratelimit-input-tokens-limit",
+    "anthropic-ratelimit-input-tokens-remaining",
+    "anthropic-ratelimit-input-tokens-reset",
+    "anthropic-ratelimit-output-tokens-limit",
+    "anthropic-ratelimit-output-tokens-remaining",
+    "anthropic-ratelimit-output-tokens-reset",
+]);
+function isAllowedHeader(name) {
+    return ALLOWED_HEADERS.has(name.toLowerCase());
+}
+/**
+ * Upper bound on `retryAfterMs`. Anything longer is almost certainly a
+ * misparsed HTTP-date or a hostile/buggy proxy injecting a far-future value
+ * (e.g. `Sat, 01 Jan 9999 …`). 5 minutes is well beyond any sane provider
+ * rate-limit window — callers that wanted to wait longer would have given
+ * up by then anyway.
+ */
+const MAX_RETRY_AFTER_MS = 5 * 60 * 1000;
+function clampRetryAfter(ms) {
+    return Math.min(MAX_RETRY_AFTER_MS, Math.max(0, Math.round(ms)));
+}
+/**
+ * Read a property without letting a throwing accessor break the whole
+ * extraction. Some error shapes (especially JSON-parsed bodies that bubble
+ * up as errors) can carry getters that throw or have side effects.
+ */
+function safeGet(obj, key) {
+    try {
+        return obj[key];
+    }
+    catch {
+        return undefined;
+    }
+}
+export function extractHttpErrorFields(error) {
+    const fields = {};
+    if (!error || typeof error !== "object") {
+        return fields;
+    }
+    const err = error;
+    const status = safeGet(err, "status") ??
+        safeGet(err, "statusCode") ??
+        safeGet(err, "status_code");
+    if (typeof status === "number") {
+        fields.status = status;
+    }
+    const headers = normalizeHeaders(safeGet(err, "headers"));
+    if (headers) {
+        fields.headers = headers;
+        const retryAfterMs = parseRetryAfterMs(headers);
+        if (retryAfterMs !== undefined) {
+            fields.retryAfterMs = retryAfterMs;
+        }
+    }
+    const requestId = extractRequestId(err, headers);
+    if (requestId !== undefined) {
+        fields.requestId = requestId;
+    }
+    return fields;
+}
+function extractRequestId(err, headers) {
+    // The OpenAI/Anthropic SDK errors carry a parsed request id directly.
+    // NOTE: providers may embed account/org identifiers in request ids (e.g.
+    // OpenAI's `req_<orghash>_<reqhash>`). These are loggable but not entirely
+    // opaque — keep that in mind when forwarding to third-party telemetry.
+    const requestID = safeGet(err, "requestID");
+    if (typeof requestID === "string") {
+        return requestID;
+    }
+    const request_id = safeGet(err, "request_id");
+    if (typeof request_id === "string") {
+        return request_id;
+    }
+    if (headers) {
+        return (headerValue(headers, "x-request-id") ?? headerValue(headers, "request-id"));
+    }
+    return undefined;
+}
+function normalizeHeaders(raw) {
+    if (!raw || typeof raw !== "object") {
+        return undefined;
+    }
+    const out = {};
+    // Web `Headers` (used by the OpenAI/Anthropic SDKs) is iterable via forEach.
+    // We always lowercase the stored key so downstream `headers["x-request-id"]`
+    // lookups work regardless of the provider's original casing.
+    try {
+        if (typeof raw.forEach === "function") {
+            raw.forEach((value, key) => {
+                if (isAllowedHeader(key)) {
+                    out[key.toLowerCase()] = value;
+                }
+            });
+        }
+        else {
+            // Fall back to a plain object of header key/value pairs.
+            for (const [key, value] of Object.entries(raw)) {
+                if (typeof value === "string" && isAllowedHeader(key)) {
+                    out[key.toLowerCase()] = value;
+                }
+            }
+        }
+    }
+    catch {
+        // A malformed Headers-shaped object with a throwing iterator — give up
+        // on header capture rather than poisoning the entire extraction.
+        return undefined;
+    }
+    return Object.keys(out).length > 0 ? out : undefined;
+}
+/**
+ * Parse a retry delay (in milliseconds) from the response headers, mirroring
+ * the logic the OpenAI and Anthropic SDKs use:
+ * 1. `retry-after-ms` (non-standard, ms precision) takes precedence.
+ * 2. Otherwise `retry-after` (RFC 9110): either delta-seconds or an HTTP-date.
+ *
+ * Always returns a non-negative value capped at `MAX_RETRY_AFTER_MS`.
+ */
+function parseRetryAfterMs(headers) {
+    // `retry-after-ms` (non-standard, OpenAI-specific) is always purely numeric;
+    // try whole-value first, then first-of-list, then give up.
+    const msRaw = headerValue(headers, "retry-after-ms");
+    const ms = numericHeader(msRaw) ?? numericHeader(firstNumericToken(msRaw));
+    if (ms !== undefined) {
+        return clampRetryAfter(ms);
+    }
+    const retryAfter = headerValue(headers, "retry-after");
+    if (retryAfter !== undefined) {
+        // 1. Try the whole value as a delta-seconds number ("30", "-3600").
+        const seconds = numericHeader(retryAfter);
+        if (seconds !== undefined) {
+            return clampRetryAfter(seconds * 1000);
+        }
+        // 2. Comma-separated numeric list? Take the first token if numeric.
+        //    NOTE: HTTP-dates contain commas ("Sat, 01 Jan ..."), so we only
+        //    take the first token when it parses as a pure number — otherwise
+        //    we'd mangle a perfectly good HTTP-date into "Sat".
+        const firstNumeric = numericHeader(firstNumericToken(retryAfter));
+        if (firstNumeric !== undefined) {
+            return clampRetryAfter(firstNumeric * 1000);
+        }
+        // 3. Otherwise treat as RFC 9110 HTTP-date.
+        const dateMs = Date.parse(retryAfter) - Date.now();
+        if (!Number.isNaN(dateMs)) {
+            return clampRetryAfter(dateMs);
+        }
+    }
+    return undefined;
+}
+/**
+ * Returns the first comma-separated token of `value` only if it parses as a
+ * number. Returns undefined for non-numeric first tokens (notably HTTP-dates
+ * like `"Sat, 01 Jan 2026 ..."`) so the caller can fall back to date parsing.
+ */
+function firstNumericToken(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    const first = value.split(",")[0];
+    if (first === undefined) {
+        return undefined;
+    }
+    const trimmed = first.trim();
+    if (trimmed === "" || Number.isNaN(Number(trimmed))) {
+        return undefined;
+    }
+    return trimmed;
+}
+/**
+ * Strict numeric parse — unlike `parseFloat`, this rejects values with trailing
+ * junk (`"5xyz"`, `"30abc"`) instead of silently accepting a prefix.
+ */
+function numericHeader(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    const trimmed = value.trim();
+    if (trimmed === "") {
+        return undefined;
+    }
+    const parsed = Number(trimmed);
+    if (Number.isNaN(parsed)) {
+        return undefined;
+    }
+    return parsed;
+}
+function headerValue(headers, name) {
+    // Keys are stored lowercased by `normalizeHeaders`, so a direct lookup is
+    // sufficient. Keep a case-insensitive fallback for defense in depth in case
+    // a caller hands us a non-normalized object.
+    const lower = name.toLowerCase();
+    if (lower in headers) {
+        return headers[lower];
+    }
+    for (const [key, value] of Object.entries(headers)) {
+        if (key.toLowerCase() === lower) {
+            return value;
+        }
+    }
+    return undefined;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "smoltalk",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "A common interface for LLM APIs",
   "homepage": "https://github.com/egonSchiele/smoltalk",
   "files": [