@vxil/sdk 0.3.0 → 0.4.0

package/dist/qs.d.ts

@@ -0,0 +1,15 @@
+/** A single query value: strings go verbatim, numbers/booleans stringify
+ *  (`0` → `"0"`, `true` → `"true"`), an array joins with `,` (an empty array is
+ *  omitted, like `undefined`). `undefined`/`null` entries are omitted. */
+export type QsScalar = string | number | boolean;
+export type QsValue = QsScalar | ReadonlyArray<QsScalar> | undefined | null;
+/** Percent-encode one key or value the way the application/x-www-form-urlencoded
+ *  serializer does: `encodeURIComponent`, then `!'()~` percent-encoded and
+ *  space as `+`. Exported for reuse; every query the client sends goes through
+ *  it. */
+export declare function formEncode(s: string): string;
+/** Build a query SUFFIX from a key → value bag: `''` when no entry survives,
+ *  else `?k=v&k2=v2` in insertion order. Omits `undefined`/`null` (and empty
+ *  arrays); stringifies numbers and booleans; joins arrays with `,`. Pure, no
+ *  globals — works on every JS engine, React Native's Hermes included. */
+export declare function qs(params: Record<string, QsValue>): string;

package/dist/qs.js

@@ -0,0 +1,48 @@
+// Query-string builder — the SDK's replacement for the WHATWG `URLSearchParams`
+// at every call site (F7-44, the React-Native-clean SDK).
+//
+// WHY (implementation note; `//` comments never reach the shipped .d.ts):
+// React Native supplies its own URLSearchParams polyfill, and up to RN 0.79
+// (Expo SDK ≤ 53) that polyfill is a stub — `set`/`get`/`has`/`delete` THROW
+// "URLSearchParams.set is not implemented" and there is no `size` getter — so
+// the previous `qs.set(...)` / `qs.size ? … : ''` pattern threw (or silently
+// dropped every parameter) on every list call under Hermes. The citation and a
+// faithful runtime replica of that polyfill live in hermes.smoke.test.ts. This
+// module uses only `encodeURIComponent` + string ops, which every JS engine has.
+//
+// The bytes are IDENTICAL to what `new URLSearchParams(...).toString()` produced
+// (application/x-www-form-urlencoded: space → `+`, `!'()~` percent-encoded),
+// so nothing on the wire changes — qs.test.ts pins that against Node's real
+// URLSearchParams.
+/** Percent-encode one key or value the way the application/x-www-form-urlencoded
+ *  serializer does: `encodeURIComponent`, then `!'()~` percent-encoded and
+ *  space as `+`. Exported for reuse; every query the client sends goes through
+ *  it. */
+export function formEncode(s) {
+    return encodeURIComponent(s)
+        .replace(/[!'()~]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`)
+        .replace(/%20/g, '+');
+}
+/** Build a query SUFFIX from a key → value bag: `''` when no entry survives,
+ *  else `?k=v&k2=v2` in insertion order. Omits `undefined`/`null` (and empty
+ *  arrays); stringifies numbers and booleans; joins arrays with `,`. Pure, no
+ *  globals — works on every JS engine, React Native's Hermes included. */
+export function qs(params) {
+    let out = '';
+    for (const key of Object.keys(params)) {
+        const v = params[key];
+        if (v === undefined || v === null)
+            continue;
+        let s;
+        if (Array.isArray(v)) {
+            if (v.length === 0)
+                continue;
+            s = v.map(String).join(',');
+        }
+        else {
+            s = String(v);
+        }
+        out += `${out ? '&' : '?'}${formEncode(key)}=${formEncode(s)}`;
+    }
+    return out;
+}

package/dist/retry.d.ts

@@ -0,0 +1,47 @@
+import type { VxilHooks, VxilRetryOptions } from './index.js';
+export declare const DEFAULT_RETRY_ON: ReadonlyArray<number>;
+export declare const DEFAULT_BACKOFF_MS = 250;
+export declare const DEFAULT_MAX_BACKOFF_MS = 10000;
+/** Parse a `Retry-After` header into SECONDS (a non-negative number), or
+ *  `undefined` when absent/unparseable. Accepts delta-seconds (`30`, `1.5`)
+ *  and an HTTP-date (`Wed, 21 Oct 2026 07:28:00 GMT`, measured from `nowMs`,
+ *  floored at 0). */
+export declare function parseRetryAfter(value: string | null | undefined, nowMs?: number): number | undefined;
+/** The retry gate: GET/HEAD/PUT/DELETE/OPTIONS are idempotent by definition; a
+ *  POST only when it carries a non-empty `Idempotency-Key` (any header case);
+ *  PATCH and a bare POST never. */
+export declare function isIdempotentRequest(method: string, headers: Record<string, string>): boolean;
+/** Exponential backoff with equal jitter: `min(max, base·2^(attempt−1))`
+ *  scaled into `[½, 1]` by `random()` (inject `() => 1` for a deterministic
+ *  schedule). `attempt` is the attempt that just failed (1-based). */
+export declare function backoffDelayMs(attempt: number, backoffMs: number, maxBackoffMs: number, random?: () => number): number;
+export interface TransportInit {
+    method: string;
+    headers: Record<string, string>;
+    body?: string;
+}
+export interface TransportResult {
+    response: Response;
+    /** The body, fully read (so a retried attempt never leaks a stream and a
+     *  `timeoutMs` covers the body too). */
+    text: string;
+}
+export interface TransportOptions {
+    fetch: typeof fetch;
+    retry?: VxilRetryOptions;
+    timeoutMs?: number;
+    hooks?: VxilHooks;
+    /** Builds the error thrown when an attempt exceeds `timeoutMs` (index.ts
+     *  supplies a `VxilError` so callers catch one error class). */
+    timeoutError: (timeoutMs: number) => Error;
+    sleep?: (ms: number) => Promise<void>;
+    random?: () => number;
+    now?: () => number;
+}
+export interface Transport {
+    send(url: string, init: TransportInit): Promise<TransportResult>;
+}
+/** Build the transport the client routes every request through. With none of
+ *  `retry` / `timeoutMs` / `hooks` set this is one `fetch` + `text()` — the
+ *  pre-seam behaviour, byte for byte. */
+export declare function createTransport(opts: TransportOptions): Transport;

package/dist/retry.js

@@ -0,0 +1,156 @@
+// The request seam: retry + timeout + hooks around the ONE `fetch` every SDK
+// request goes through (parity P1 #9), and the `Retry-After` parser
+// `VxilError.retryAfter` shares (F7-44). DEFAULT OFF — with no `retry`,
+// `timeoutMs` or `hooks` option the transport is a single `fetch` + `text()`,
+// exactly what `call()` did before.
+//
+// Uses only `fetch`, `AbortController`, `setTimeout` and `Date` — all present
+// in Node ≥ 18, browsers, edge runtimes and React Native.
+// ─── the shared pieces ───────────────────────────────────────────────────────
+export const DEFAULT_RETRY_ON = [429, 502, 503, 504];
+export const DEFAULT_BACKOFF_MS = 250;
+export const DEFAULT_MAX_BACKOFF_MS = 10_000;
+/** Parse a `Retry-After` header into SECONDS (a non-negative number), or
+ *  `undefined` when absent/unparseable. Accepts delta-seconds (`30`, `1.5`)
+ *  and an HTTP-date (`Wed, 21 Oct 2026 07:28:00 GMT`, measured from `nowMs`,
+ *  floored at 0). */
+export function parseRetryAfter(value, nowMs = Date.now()) {
+    if (value === null || value === undefined)
+        return undefined;
+    const v = value.trim();
+    if (v === '')
+        return undefined;
+    if (/^\d+(\.\d+)?$/.test(v))
+        return Number(v);
+    const at = Date.parse(v);
+    if (Number.isNaN(at))
+        return undefined;
+    return Math.max(0, (at - nowMs) / 1000);
+}
+/** The retry gate: GET/HEAD/PUT/DELETE/OPTIONS are idempotent by definition; a
+ *  POST only when it carries a non-empty `Idempotency-Key` (any header case);
+ *  PATCH and a bare POST never. */
+export function isIdempotentRequest(method, headers) {
+    const m = method.toUpperCase();
+    if (m === 'GET' || m === 'HEAD' || m === 'PUT' || m === 'DELETE' || m === 'OPTIONS')
+        return true;
+    if (m !== 'POST')
+        return false;
+    return Object.keys(headers).some((k) => k.toLowerCase() === 'idempotency-key' && headers[k] !== '');
+}
+/** Exponential backoff with equal jitter: `min(max, base·2^(attempt−1))`
+ *  scaled into `[½, 1]` by `random()` (inject `() => 1` for a deterministic
+ *  schedule). `attempt` is the attempt that just failed (1-based). */
+export function backoffDelayMs(attempt, backoffMs, maxBackoffMs, random = Math.random) {
+    const capped = Math.min(maxBackoffMs, backoffMs * 2 ** Math.max(0, attempt - 1));
+    return Math.round(capped / 2 + (capped / 2) * random());
+}
+/** Headers a hook never sees and can never set. */
+const CREDENTIAL_HEADERS = new Set(['authorization', 'x-vxil-end-user']);
+function describeRequest(method, url, headers, attempt) {
+    const visible = {};
+    for (const k of Object.keys(headers)) {
+        if (!CREDENTIAL_HEADERS.has(k.toLowerCase()))
+            visible[k] = headers[k];
+    }
+    return Object.freeze({ method, url, headers: Object.freeze(visible), attempt });
+}
+const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/** One attempt: `fetch` + read the body, under an optional per-attempt
+ *  timeout. On timeout the controller aborts the fetch (and its body stream),
+ *  so nothing keeps running after the error is thrown; the timer is always
+ *  cleared. */
+async function attemptOnce(fetchImpl, url, init, timeoutMs, timeoutError) {
+    if (!timeoutMs) {
+        const response = await fetchImpl(url, init);
+        return { response, text: await response.text() };
+    }
+    const controller = new AbortController();
+    let timedOut = false;
+    const timer = setTimeout(() => {
+        timedOut = true;
+        controller.abort();
+    }, timeoutMs);
+    try {
+        const response = await fetchImpl(url, { ...init, signal: controller.signal });
+        const text = await response.text();
+        return { response, text };
+    }
+    catch (e) {
+        if (timedOut)
+            throw timeoutError(timeoutMs);
+        throw e;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** Build the transport the client routes every request through. With none of
+ *  `retry` / `timeoutMs` / `hooks` set this is one `fetch` + `text()` — the
+ *  pre-seam behaviour, byte for byte. */
+export function createTransport(opts) {
+    const attempts = Math.max(0, Math.floor(opts.retry?.attempts ?? 0));
+    const retryOn = new Set(opts.retry?.retryOn ?? DEFAULT_RETRY_ON);
+    const backoffMs = opts.retry?.backoffMs ?? DEFAULT_BACKOFF_MS;
+    const maxBackoffMs = opts.retry?.maxBackoffMs ?? DEFAULT_MAX_BACKOFF_MS;
+    const respectRetryAfter = opts.retry?.respectRetryAfter ?? true;
+    const retryOnNetworkError = opts.retry?.retryOnNetworkError ?? true;
+    const timeoutMs = opts.timeoutMs && opts.timeoutMs > 0 ? opts.timeoutMs : undefined;
+    const hooks = opts.hooks ?? {};
+    const sleep = opts.sleep ?? defaultSleep;
+    const random = opts.random ?? Math.random;
+    const now = opts.now ?? Date.now;
+    if (timeoutMs !== undefined && typeof AbortController !== 'function') {
+        throw new Error('@vxil/sdk: `timeoutMs` needs a runtime with AbortController');
+    }
+    return {
+        async send(url, init) {
+            const idempotent = isIdempotentRequest(init.method, init.headers);
+            for (let attempt = 1;; attempt++) {
+                const headers = { ...init.headers };
+                const request = describeRequest(init.method, url, headers, attempt);
+                const extra = await hooks.beforeRequest?.(request);
+                if (extra) {
+                    for (const k of Object.keys(extra)) {
+                        if (!CREDENTIAL_HEADERS.has(k.toLowerCase()))
+                            headers[k] = extra[k];
+                    }
+                }
+                const canRetry = attempt <= attempts && idempotent;
+                const started = now();
+                let result;
+                let failure;
+                try {
+                    result = await attemptOnce(opts.fetch, url, { ...init, headers }, timeoutMs, opts.timeoutError);
+                }
+                catch (e) {
+                    failure = e;
+                }
+                if (result) {
+                    await hooks.afterResponse?.({ request, response: result.response, durationMs: now() - started });
+                    const status = result.response.status;
+                    if (!(canRetry && retryOn.has(status)))
+                        return result;
+                    const retryAfter = respectRetryAfter
+                        ? parseRetryAfter(result.response.headers.get('retry-after'), now())
+                        : undefined;
+                    const delayMs = retryAfter !== undefined
+                        ? Math.round(retryAfter * 1000)
+                        : backoffDelayMs(attempt, backoffMs, maxBackoffMs, random);
+                    // Never wait longer than the cap — and never retry EARLIER than the
+                    // server asked: a Retry-After beyond the cap ends the loop instead.
+                    if (delayMs > maxBackoffMs)
+                        return result;
+                    await hooks.onRetry?.({ request, delayMs, status });
+                    await sleep(delayMs);
+                    continue;
+                }
+                if (!(canRetry && retryOnNetworkError))
+                    throw failure;
+                const delayMs = backoffDelayMs(attempt, backoffMs, maxBackoffMs, random);
+                await hooks.onRetry?.({ request, delayMs, error: failure });
+                await sleep(delayMs);
+            }
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vxil/sdk",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "private": false,
   "type": "module",
   "description": "Typed client for the Vxil REST API (notifications, auth, jobs, files, cms, comments, webhooks, realtime, orgs, rate-limits).",