@tuppence/node 0.0.0-stage → 0.1.0

package/dist/http.d.ts

@@ -0,0 +1,71 @@
+export declare const VERSION = "0.1.0";
+export declare const DEFAULT_API_VERSION = "2026-09-20";
+export type ClientOptions = {
+    /** Default: `TUPPENCE_API_URL` from the environment, else `https://api.tuppence.ai`. */
+    baseUrl?: string;
+    /** Pin the API version; default: the version your account is pinned to. */
+    apiVersion?: string;
+    /** Retries after the first attempt, for network errors, 409 in-flight, 429 and 5xx. Default 2. */
+    maxRetries?: number;
+    /** Per attempt. Default 30 000 ms. */
+    timeoutMs?: number;
+    /** Bring your own `fetch` (tests, proxies). Default: the global one (Node 18+). */
+    fetch?: typeof fetch;
+    /**
+     * Tuppence sometimes says something about a request that succeeded — today, that a payment is
+     * small enough that prepaid credit would cost less (`small_payment`). Each code is passed on
+     * ONCE per client, to `console.warn` unless you handle it yourself. `onNotice: () => {}`
+     * silences them.
+     */
+    onNotice?: (notice: {
+        code: string;
+        message: string;
+    }) => void;
+    /**
+     * Tuppence Connect: act as this connected account (`acct_…`) on every request — sent as the
+     * `Tuppence-Account` header. `tuppence.as("acct_…")` makes such a client from yours; a
+     * request's own `tuppenceAccount` wins.
+     */
+    tuppenceAccount?: string;
+};
+export type RequestOptions = {
+    /**
+     * Makes a POST safe to retry: the API does it once, however often it is sent. The SDK sets a
+     * fresh one per call — and reuses it across that call's own retries — unless you pass one.
+     */
+    idempotencyKey?: string;
+    /** Override the client's API version for this request. */
+    apiVersion?: string;
+    maxRetries?: number;
+    timeoutMs?: number;
+    /**
+     * Tuppence Connect: make this request as one of your connected accounts (`acct_…`), with your
+     * own key. Sent as the `Tuppence-Account` header — never in the path or the body.
+     */
+    tuppenceAccount?: string;
+};
+/**
+ * A body already encoded — the multipart of `files.create` — sent as these exact bytes on every
+ * attempt: a retry must be the same request, down to the boundary, or its key would not match.
+ */
+export declare class EncodedBody {
+    readonly bytes: Uint8Array<ArrayBuffer>;
+    readonly contentType: string;
+    constructor(bytes: Uint8Array<ArrayBuffer>, contentType: string);
+}
+type Query = Record<string, string | number | boolean | undefined | null>;
+export declare class HttpClient {
+    private readonly apiKey;
+    private readonly options;
+    private readonly baseUrl;
+    private readonly fetch;
+    constructor(apiKey: string, options?: ClientOptions);
+    request<T>(method: "GET" | "POST" | "DELETE", path: string, { body, query, ...options }?: RequestOptions & {
+        body?: unknown;
+        query?: Query;
+    }): Promise<T>;
+    private readonly noticed;
+    /** `code; message` — said once per code, and never twice for the same kind of request. */
+    private notice;
+}
+export {};

package/dist/http.js

@@ -0,0 +1,134 @@
+import { ConnectionError, TuppenceError } from "./errors.js";
+export const VERSION = "0.1.0";
+export const DEFAULT_API_VERSION = "2026-09-20";
+/**
+ * A body already encoded — the multipart of `files.create` — sent as these exact bytes on every
+ * attempt: a retry must be the same request, down to the boundary, or its key would not match.
+ */
+export class EncodedBody {
+    bytes;
+    contentType;
+    constructor(bytes, contentType) {
+        this.bytes = bytes;
+        this.contentType = contentType;
+    }
+}
+const RETRY_BASE_MS = 500;
+const RETRY_MAX_MS = 8_000;
+/** Full-jitter exponential backoff (AWS): the retries of many clients do not arrive together. */
+const backoff = (attempt) => Math.random() * Math.min(RETRY_MAX_MS, RETRY_BASE_MS * 2 ** attempt);
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+export class HttpClient {
+    apiKey;
+    options;
+    baseUrl;
+    fetch;
+    constructor(apiKey, options = {}) {
+        this.apiKey = apiKey;
+        this.options = options;
+        if (!apiKey || typeof apiKey !== "string") {
+            throw new TypeError("new Tuppence(apiKey): an API key (sk_test_… or sk_live_…) is required.");
+        }
+        // `TUPPENCE_API_URL`: point code you did not write (a docs example) at a test API.
+        this.baseUrl = (options.baseUrl ??
+            globalThis.process?.env?.TUPPENCE_API_URL ??
+            "https://api.tuppence.ai").replace(/\/+$/, "");
+        const fetcher = options.fetch ?? globalThis.fetch;
+        if (!fetcher)
+            throw new TypeError("fetch is not available: use Node 18+ or pass options.fetch.");
+        this.fetch = fetcher;
+    }
+    async request(method, path, { body, query, ...options } = {}) {
+        const url = new URL(`${this.baseUrl}${path}`);
+        for (const [key, value] of Object.entries(query ?? {})) {
+            if (value !== undefined && value !== null)
+                url.searchParams.set(key, String(value));
+        }
+        const headers = {
+            Authorization: `Bearer ${this.apiKey}`,
+            Accept: "application/json",
+            "User-Agent": `tuppence-node/${VERSION}`,
+        };
+        const version = options.apiVersion ?? this.options.apiVersion;
+        if (version)
+            headers["Tuppence-Version"] = version;
+        const account = options.tuppenceAccount ?? this.options.tuppenceAccount;
+        if (account)
+            headers["Tuppence-Account"] = account;
+        const encoded = body instanceof EncodedBody ? body : undefined;
+        if (encoded)
+            headers["Content-Type"] = encoded.contentType;
+        else if (body !== undefined)
+            headers["Content-Type"] = "application/json";
+        // One key per CALL, reused by every retry of it — that is what makes a retry safe.
+        if (method === "POST")
+            headers["Idempotency-Key"] = options.idempotencyKey ?? crypto.randomUUID();
+        const retries = options.maxRetries ?? this.options.maxRetries ?? 2;
+        const timeoutMs = options.timeoutMs ?? this.options.timeoutMs ?? 30_000;
+        for (let attempt = 0;; attempt += 1) {
+            let response;
+            try {
+                response = await this.fetch(url, {
+                    method,
+                    headers,
+                    body: encoded ? encoded.bytes : body === undefined ? undefined : JSON.stringify(body),
+                    signal: AbortSignal.timeout(timeoutMs),
+                });
+            }
+            catch (error) {
+                if (attempt < retries) {
+                    await sleep(backoff(attempt));
+                    continue;
+                }
+                const timedOut = error.name === "TimeoutError";
+                throw new ConnectionError(timedOut
+                    ? `No answer from Tuppence within ${timeoutMs} ms (${retries + 1} attempts).`
+                    : `Could not reach Tuppence (${retries + 1} attempts): ${error.message}`, error);
+            }
+            if (response.ok) {
+                this.notice(response.headers.get("tuppence-notice"));
+                return (response.status === 204 ? undefined : await response.json());
+            }
+            const text = await response.text();
+            let error;
+            try {
+                error = JSON.parse(text).error ?? { message: text };
+            }
+            catch {
+                error = { message: text || `HTTP ${response.status}` };
+            }
+            error.request_id ??= response.headers.get("request-id") ?? undefined;
+            if (attempt < retries && retryable(response.status, error)) {
+                const after = Number(response.headers.get("retry-after"));
+                await sleep(Number.isFinite(after) && after > 0
+                    ? Math.min(after * 1_000, RETRY_MAX_MS)
+                    : backoff(attempt));
+                continue;
+            }
+            throw TuppenceError.from(error, response.status);
+        }
+    }
+    noticed = new Set();
+    /** `code; message` — said once per code, and never twice for the same kind of request. */
+    notice(header) {
+        if (!header)
+            return;
+        const [code = "", ...rest] = header.split(";");
+        const message = rest.join(";").trim();
+        if (!code || this.noticed.has(code))
+            return;
+        this.noticed.add(code);
+        const handler = this.options.onNotice;
+        if (handler)
+            handler({ code, message });
+        else
+            console.warn(`Tuppence: ${message || code}`);
+    }
+}
+/**
+ * What is worth trying again: the server's own trouble, a rate limit, and a duplicate that is
+ * still in flight. Never a 4xx that the same request would get again.
+ */
+function retryable(status, error) {
+    return (status >= 500 || status === 429 || (status === 409 && error.code === "idempotency_in_progress"));
+}