@forumulate/sdk 0.4.0 → 0.7.0

package/dist/http.js

@@ -0,0 +1,200 @@
+"use strict";
+/**
+ * The one place a request leaves the SDK: headers, body encoding, retries,
+ * response decoding and the error type. Every surface — the positional
+ * helpers, `typed()`, `request(operationId)` and the generated namespaces —
+ * goes through `send`, so a retry or a header rule cannot apply to one door
+ * and not another.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ForumulateError = exports.SDK_VERSION = void 0;
+exports.retryDelayMs = retryDelayMs;
+exports.send = send;
+/** Kept in step with package.json by `coverage.test.ts`. */
+exports.SDK_VERSION = '0.7.0';
+/**
+ * Thrown for any non-2xx API response, and for a network failure that
+ * outlived its retries (`status: 0`, `code: 'network.error'`). Mirrors the
+ * API's error envelope.
+ */
+class ForumulateError extends Error {
+    status;
+    code;
+    details;
+    requestId;
+    retryAfter;
+    body;
+    headers;
+    constructor(status, code, message, init = {}) {
+        super(message, init.cause === undefined ? undefined : { cause: init.cause });
+        this.status = status;
+        this.code = code;
+        this.name = 'ForumulateError';
+        this.details = init.details;
+        this.requestId = init.requestId;
+        this.retryAfter = init.retryAfter;
+        this.body = init.body;
+        this.headers = init.headers;
+    }
+}
+exports.ForumulateError = ForumulateError;
+/** 408, 429 and the gateway family. A 500 is not here: the API means it ("retrying will not help"). */
+const RETRY_STATUS = new Set([408, 429, 502, 503, 504]);
+const SAFE_METHODS = new Set(['GET', 'HEAD', 'OPTIONS', 'PUT', 'DELETE']);
+/** A Retry-After longer than this is a "come back later", not a retry; surface it. */
+const MAX_RETRY_AFTER_MS = 60_000;
+const hasHeader = (h, name) => Object.keys(h).some((k) => k.toLowerCase() === name.toLowerCase());
+const isRawBody = (b) => (typeof FormData !== 'undefined' && b instanceof FormData) ||
+    (typeof Blob !== 'undefined' && b instanceof Blob) ||
+    (typeof URLSearchParams !== 'undefined' && b instanceof URLSearchParams) ||
+    (typeof ReadableStream !== 'undefined' && b instanceof ReadableStream) ||
+    b instanceof ArrayBuffer ||
+    ArrayBuffer.isView(b);
+function newIdempotencyKey() {
+    const c = globalThis.crypto;
+    if (c?.randomUUID)
+        return c.randomUUID();
+    return 'sdk-' + Date.now().toString(36) + '-' + Math.random().toString(36).slice(2, 12);
+}
+/**
+ * How long to wait before retry number `attempt` (0-based), or `null` to stop.
+ *
+ * `Retry-After` wins when present — seconds or an HTTP date — because the
+ * API sends it on purpose (a 429's window, a 503's batch interruption). Without
+ * it: exponential from 0.5s, capped at 8s, with jitter so a fleet of clients
+ * that failed together does not retry together.
+ */
+function retryDelayMs(attempt, retryAfter, now = Date.now()) {
+    if (retryAfter != null && retryAfter.trim() !== '') {
+        const secs = Number(retryAfter);
+        const ms = Number.isFinite(secs) ? secs * 1000 : Date.parse(retryAfter) - now;
+        if (Number.isFinite(ms))
+            return ms > MAX_RETRY_AFTER_MS ? null : Math.max(0, ms);
+    }
+    return Math.min(500 * 2 ** attempt, 8000) * (1 - Math.random() * 0.25);
+}
+function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted)
+            return reject(signal.reason);
+        const t = setTimeout(resolve, ms);
+        signal?.addEventListener?.('abort', () => {
+            clearTimeout(t);
+            reject(signal.reason);
+        }, { once: true });
+    });
+}
+function buildUrl(base, path, query) {
+    const url = new URL(base + path);
+    for (const [k, v] of Object.entries(query ?? {})) {
+        if (v === undefined || v === null)
+            continue;
+        // Lists are comma-joined: `include=sections,body` is how the API reads them.
+        url.searchParams.set(k, Array.isArray(v) ? v.join(',') : String(v));
+    }
+    return url.toString();
+}
+async function decode(res, init) {
+    if (init.raw || init.kind === 'binary')
+        return res;
+    const text = await res.text();
+    if (init.kind === 'text')
+        return text;
+    if (!text)
+        return undefined;
+    const type = res.headers?.get?.('content-type') ?? '';
+    // No content type (a test double, an odd proxy) is read as JSON, as it always was.
+    if (!type || /json/i.test(type))
+        return JSON.parse(text);
+    return text;
+}
+async function toError(res) {
+    let body;
+    try {
+        const text = await res.text();
+        body = text ? JSON.parse(text) : undefined;
+    }
+    catch {
+        /* non-JSON body (an edge block page) */
+    }
+    const env = (body ?? {});
+    const after = res.headers?.get?.('retry-after');
+    const retryAfter = after != null && Number.isFinite(Number(after)) ? Number(after) : undefined;
+    return new ForumulateError(res.status, env.error?.code ?? 'error', env.error?.message ?? res.statusText, {
+        details: env.error?.details,
+        requestId: env.requestId ?? res.headers?.get?.('x-request-id') ?? undefined,
+        retryAfter,
+        body,
+        headers: res.headers,
+    });
+}
+async function send(t, init) {
+    const method = init.method.toUpperCase();
+    const url = buildUrl(t.baseUrl, init.path, init.query);
+    /*
+     * Ours first, the caller's last, so a per-request header wins.
+     *
+     * `Idempotency-Key` has to be per-REQUEST (a key reused across two
+     * different writes is worse than none), and `Forumulate-Version` is
+     * naturally per-client — so both layers exist and the narrower one
+     * overrides. `Content-Type` is set before the caller's so a multipart or
+     * ndjson body can correct it rather than be forced to JSON.
+     */
+    const headers = { ...t.headers };
+    if (t.token)
+        headers.Authorization = `Bearer ${t.token}`;
+    const raw = init.body !== undefined && isRawBody(init.body);
+    if (init.body !== undefined && !raw)
+        headers['Content-Type'] = 'application/json';
+    if (init.version &&
+        !hasHeader(headers, 'forumulate-version') &&
+        !hasHeader(init.headers ?? {}, 'forumulate-version')) {
+        headers['Forumulate-Version'] = init.version;
+    }
+    Object.assign(headers, init.headers ?? {});
+    if (init.idempotencyKey)
+        headers['Idempotency-Key'] = init.idempotencyKey;
+    else if (t.autoIdempotencyKey &&
+        (method === 'POST' || method === 'PATCH') &&
+        !hasHeader(headers, 'idempotency-key')) {
+        // Generated ONCE per call, so every retry of this call carries the same key.
+        headers['Idempotency-Key'] = newIdempotencyKey();
+    }
+    const retryable = SAFE_METHODS.has(method) || hasHeader(headers, 'idempotency-key');
+    const maxRetries = retryable ? Math.max(0, init.maxRetries ?? t.maxRetries) : 0;
+    const body = init.body === undefined ? undefined : raw ? init.body : JSON.stringify(init.body);
+    for (let attempt = 0;; attempt++) {
+        let res;
+        try {
+            res = await t.fetch(url, {
+                method,
+                headers,
+                credentials: t.credentials ? 'include' : 'same-origin',
+                body,
+                signal: init.signal,
+            });
+        }
+        catch (err) {
+            if (err?.name === 'AbortError' || init.signal?.aborted)
+                throw err;
+            const wait = attempt < maxRetries ? retryDelayMs(attempt, null) : null;
+            if (wait === null) {
+                throw new ForumulateError(0, 'network.error', err?.message ?? 'Network request failed', { cause: err });
+            }
+            await sleep(wait, init.signal);
+            continue;
+        }
+        if (res.ok)
+            return (await decode(res, init));
+        if (attempt < maxRetries && RETRY_STATUS.has(res.status)) {
+            const wait = retryDelayMs(attempt, res.headers?.get?.('retry-after'));
+            if (wait !== null) {
+                await res.text?.().catch(() => undefined);
+                await sleep(wait, init.signal);
+                continue;
+            }
+        }
+        throw await toError(res);
+    }
+}
+//# sourceMappingURL=http.js.map