@yougrowai/node 0.1.0 → 0.3.0

package/dist/index.d.ts

@@ -1,89 +1,189 @@
 /**
- * @yougrowai/node — send your product's user events to YouGrow lifecycle journeys.
+ * @yougrowai/node — keep your users' state in YouGrow lifecycle journeys (API v2).
  *
  *   const yg = new YouGrow({ keyId: process.env.YOUGROW_KEY_ID!, secret: process.env.YOUGROW_SECRET! });
- *   yg.identify({ userId: user.id, traits: { email: user.email }, consent: { basis: "soft_opt_in" } });
- *   yg.track({ userId: user.id, event: "user.signed_up" });
- *   await yg.flush();
+ *   await yg.users.update(user.id, { email: user.email, signedUpAt: user.createdAt.toISOString(), consent: "soft_opt_in" });
  *
- * Server-side only (the secret signs every request). Messages are batched (≤100
- * per request) and retried with backoff on network errors, 429 and 5xx. Every
- * message carries a messageId, so a retried or duplicated send is harmless.
+ * Server-side only: the secret authenticates every request (HTTP Basic). Each
+ * method resolves once its request is done (a batch's, one per 100 users), with
+ * nothing queued or sent in the background, so it's safe in serverless
+ * functions. A request is abandoned after `timeoutMs` and retried with capped,
+ * jittered backoff on network errors, timeouts, 429 and 5xx; any other error
+ * status throws a YouGrowError straight away.
  */
-export { HEADERS, sign, type Direction } from "./signing.js";
 export type ConsentBasis = "consent" | "soft_opt_in" | "corporate_subscriber" | "none";
-export type TraitValue = string | number | boolean | null;
+/**
+ * Any subset of a user's state, as a JSON Merge Patch (RFC 7396): fields sent
+ * replace YouGrow's, fields left out stay, `null` clears, and `steps`, `facts`
+ * and `traits` merge key by key. Timestamps are ISO 8601 with a zone, e.g.
+ * `new Date().toISOString()`.
+ */
+export interface UserPatch {
+    email?: string | null;
+    firstName?: string | null;
+    lastName?: string | null;
+    /** An IANA time zone, e.g. "Europe/London". */
+    timezone?: string | null;
+    /** A BCP 47 locale, e.g. "en-GB". */
+    locale?: string | null;
+    /** When the account was created. Starts sign-up journeys while inside their window. */
+    signedUpAt?: string;
+    /** The legal basis for marketing email. */
+    consent?: ConsentBasis | null;
+    /** false = the person opted out of lifecycle email in your product. */
+    subscribed?: boolean;
+    /** Never email this person, in any journey (staff, test accounts, invited teammates). */
+    excluded?: {
+        reason: string;
+    } | null;
+    /** Onboarding step id → when it was done (null: not done). */
+    steps?: Record<string, string | null>;
+    /** Fact id → its latest value (null removes it). */
+    facts?: Record<string, number | string | boolean | null>;
+    /** Anything else journeys branch on (null removes a key). */
+    traits?: Record<string, string | number | boolean | null>;
+    /** When you read this state. A write older than the stored one is ignored. */
+    updatedAt?: string;
+}
+/** A user's state as YouGrow holds it. */
+export interface UserState {
+    userId: string;
+    email: string | null;
+    firstName: string | null;
+    lastName: string | null;
+    timezone: string | null;
+    locale: string | null;
+    signedUpAt: string | null;
+    consent: ConsentBasis | null;
+    subscribed: boolean;
+    excluded: {
+        reason: string;
+    } | null;
+    steps: Record<string, string>;
+    facts: Record<string, string | number | boolean>;
+    traits: Record<string, string | number | boolean>;
+    updatedAt: string | null;
+}
+/** `users.get` adds what YouGrow decided: journeys and opt-outs. */
+export interface UserView extends UserState {
+    enrolments: Array<{
+        journeyId: string;
+        status: string;
+        mode: string;
+        enrolledAt: string;
+    }>;
+    /** Unsubscribes made in YouGrow's emails. They hold until the person lifts them; the API can't. */
+    optOuts: Array<{
+        scope: "all" | "category";
+        category: string | null;
+        at: string | null;
+    }>;
+}
+/** Why a write was ignored: older than the stored state, or than the user's deletion. */
+export type SkipReason = "stale_write" | "deleted_later";
+export type PatchResponse = {
+    applied: true;
+    user: UserState;
+} | {
+    applied: false;
+    reason: SkipReason;
+    storedUpdatedAt?: string | null;
+    user?: UserState;
+};
+/** What was wrong with one field, e.g. `{ path: "traits.plan", message: "…" }`. */
+export interface FieldError {
+    path: string;
+    message: string;
+}
+/** One user in `users.batch`: their id plus a patch. */
+export interface BatchItem extends UserPatch {
+    userId: string;
+}
+export interface BatchResponse {
+    applied: number;
+    ignored: number;
+    failed: number;
+    /** Only the ignored and failed items; applied ones are counted. `index` is the item's position in your array. */
+    results: Array<{
+        index: number;
+        userId: string | null;
+        status: "ignored" | "failed";
+        reason: string;
+        fields?: FieldError[];
+    }>;
+}
+export interface EventResult {
+    recorded: boolean;
+    duplicate: boolean;
+}
 export interface YouGrowOptions {
+    /** Your connection's key id (`ygk_…`). */
     keyId: string;
+    /** Its secret (`ygs_…`). Server-side only. */
     secret: string;
-    /** Ingest URL. Defaults to https://yougrow.ai/api/v1/events. */
-    endpoint?: string;
-    /** Flush automatically once this many messages are queued (max 100). */
-    flushAt?: number;
-    /** Flush automatically this long after the first queued message. 0 = manual only. */
-    flushIntervalMs?: number;
-    /** Retries per batch for network errors, 429 and 5xx. */
+    /**
+     * YouGrow's origin, e.g. from YOUGROW_ORIGIN. Defaults to https://yougrow.ai;
+     * set it when you're connected to another YouGrow instance (staging, self-hosted).
+     */
+    origin?: string;
+    /** Abandon a request after this long (default 10000); it's retried like a network error. */
+    timeoutMs?: number;
+    /** Retries per request for network errors, timeouts, 429 and 5xx (default 3). */
     maxRetries?: number;
+    /** Longest wait between retries (default 5000), even when Retry-After asks for more. */
+    maxRetryWaitMs?: number;
     /** Custom fetch (tests, proxies). */
     fetch?: typeof fetch;
-    /** Called when a background flush fails. */
-    onError?: (err: Error) => void;
 }
-export interface IdentifyInput {
-    userId: string;
-    traits?: Record<string, TraitValue>;
-    consent?: {
-        basis: ConsentBasis;
-        source?: string;
-    };
-    timestamp?: Date | string;
-    messageId?: string;
+export interface BatchOptions {
+    /** Don't log the console.warn line about failed items. */
+    quiet?: boolean;
+    /** Throw a YouGrowBatchError, carrying the result, if any item failed. Every item is still sent. */
+    throwOnItemError?: boolean;
 }
-export interface TrackInput {
-    userId: string;
-    event: string;
+export interface TrackOptions {
     properties?: Record<string, unknown>;
-    traits?: Record<string, TraitValue>;
-    timestamp?: Date | string;
-    messageId?: string;
+    /** When it happened (ISO 8601 with a zone). */
+    occurredAt?: string;
+    /** The same key is recorded once. Defaults to a random key per call, so the SDK's own retries never count twice. */
+    idempotencyKey?: string;
 }
-export interface IngestResult {
-    accepted: number;
-    duplicates: number;
-    rejected: Array<{
-        index: number;
-        messageId: string | null;
-        reason: string;
-    }>;
+export interface UsersApi {
+    /** Merge a patch into one user's state; creates the user if YouGrow hasn't seen them. */
+    update(userId: string, patch: UserPatch): Promise<PatchResponse>;
+    /**
+     * Patch any number of users, 100 per request, one request after another. One
+     * bad item never fails the rest: the result lists the ignored and failed ones,
+     * and failures are logged in one console.warn line (see BatchOptions).
+     */
+    batch(items: readonly BatchItem[], opts?: BatchOptions): Promise<BatchResponse>;
+    /** The user's state, journeys and opt-outs, or null if YouGrow doesn't know them. */
+    get(userId: string): Promise<UserView | null>;
+    /** Erase the user and their history. Safe to repeat, and for users YouGrow never saw. */
+    delete(userId: string): Promise<void>;
+}
+export interface EventsApi {
+    /** Record a milestone, e.g. "report.exported". Optional: journeys run on state. */
+    track(userId: string, event: string, opts?: TrackOptions): Promise<EventResult>;
 }
+/** The API refused a request, or still failed (429, 5xx) after the retries. */
 export declare class YouGrowError extends Error {
     readonly status: number;
     readonly body?: unknown | undefined;
+    /** The API's error code (`invalid`, `unauthorized`, `rate_limited`…), or `http_<status>` when the body has none. */
+    readonly code: string;
+    /** For a 400: which fields were wrong, and why. */
+    readonly fields?: FieldError[];
     constructor(message: string, status: number, body?: unknown | undefined);
 }
+/** From `users.batch` with `throwOnItemError`: some items failed. The rest were applied; `result` says which. */
+export declare class YouGrowBatchError extends Error {
+    readonly result: BatchResponse;
+    constructor(message: string, result: BatchResponse);
+}
 export declare class YouGrow {
-    private readonly keyId;
-    private readonly secret;
-    private readonly endpoint;
-    private readonly flushAt;
-    private readonly flushIntervalMs;
-    private readonly maxRetries;
-    private readonly fetchImpl;
-    private readonly onError?;
-    private queue;
-    private timer;
+    #private;
+    readonly users: UsersApi;
+    readonly events: EventsApi;
     constructor(opts: YouGrowOptions);
-    /** Who the user is: email, name, timezone, plan… plus the consent basis. Returns the messageId. */
-    identify(input: IdentifyInput): string;
-    /** Something the user did. Returns the messageId. */
-    track(input: TrackInput): string;
-    /** Shorthand for the reserved `onboarding.step_completed` event. */
-    stepCompleted(userId: string, step: string, timestamp?: Date | string): string;
-    /** Send everything queued. Resolves with one result per request. */
-    flush(): Promise<IngestResult[]>;
-    /** Flush and stop the background timer (call on shutdown). */
-    close(): Promise<IngestResult[]>;
-    private enqueue;
-    private clearTimer;
-    private send;
 }

package/dist/index.js

@@ -1,156 +1,240 @@
 import { randomUUID } from "node:crypto";
-import { HEADERS, sign } from "./signing.js";
-/**
- * @yougrowai/node — send your product's user events to YouGrow lifecycle journeys.
- *
- *   const yg = new YouGrow({ keyId: process.env.YOUGROW_KEY_ID!, secret: process.env.YOUGROW_SECRET! });
- *   yg.identify({ userId: user.id, traits: { email: user.email }, consent: { basis: "soft_opt_in" } });
- *   yg.track({ userId: user.id, event: "user.signed_up" });
- *   await yg.flush();
- *
- * Server-side only (the secret signs every request). Messages are batched (≤100
- * per request) and retried with backoff on network errors, 429 and 5xx. Every
- * message carries a messageId, so a retried or duplicated send is harmless.
- */
-export { HEADERS, sign } from "./signing.js";
+import { isSecureOrigin, originOf } from "./origin.js";
+const USERS_PATH = "/api/v2/users";
+/** The API's limits: users per batch request, and bytes per request body. */
 const MAX_BATCH = 100;
+const MAX_BODY_BYTES = 512 * 1024;
+const BATCH_ENVELOPE_BYTES = '{"users":[]}'.length;
+const MAX_USER_ID = 256;
+/** The longest delay a Node timer accepts. */
+const MAX_TIMER_MS = 2_147_483_647;
+/** The API refused a request, or still failed (429, 5xx) after the retries. */
 export class YouGrowError extends Error {
     status;
     body;
+    /** The API's error code (`invalid`, `unauthorized`, `rate_limited`…), or `http_<status>` when the body has none. */
+    code;
+    /** For a 400: which fields were wrong, and why. */
+    fields;
     constructor(message, status, body) {
         super(message);
         this.status = status;
         this.body = body;
         this.name = "YouGrowError";
+        const b = asRecord(body);
+        this.code = typeof b?.error === "string" ? b.error : `http_${status}`;
+        if (Array.isArray(b?.fields))
+            this.fields = b.fields;
+    }
+}
+/** From `users.batch` with `throwOnItemError`: some items failed. The rest were applied; `result` says which. */
+export class YouGrowBatchError extends Error {
+    result;
+    constructor(message, result) {
+        super(message);
+        this.result = result;
+        this.name = "YouGrowBatchError";
     }
 }
 export class YouGrow {
-    keyId;
-    secret;
-    endpoint;
-    flushAt;
-    flushIntervalMs;
-    maxRetries;
-    fetchImpl;
-    onError;
-    queue = [];
-    timer = null;
+    users;
+    events;
+    #origin;
+    /** Private (#), so logging the client never prints the credentials. */
+    #authorization;
+    #timeoutMs;
+    #maxRetries;
+    #maxRetryWaitMs;
+    #fetch;
     constructor(opts) {
         if (!opts.keyId || !opts.secret)
             throw new Error("YouGrow: keyId and secret are required");
-        this.keyId = opts.keyId;
-        this.secret = opts.secret;
-        this.endpoint = opts.endpoint ?? "https://yougrow.ai/api/v1/events";
-        this.flushAt = Math.min(Math.max(opts.flushAt ?? 20, 1), MAX_BATCH);
-        this.flushIntervalMs = opts.flushIntervalMs ?? 5000;
-        this.maxRetries = opts.maxRetries ?? 3;
-        this.fetchImpl = opts.fetch ?? fetch;
-        this.onError = opts.onError;
-    }
-    /** Who the user is: email, name, timezone, plan… plus the consent basis. Returns the messageId. */
-    identify(input) {
-        return this.enqueue({
-            type: "identify",
-            messageId: input.messageId ?? randomUUID(),
-            userId: input.userId,
-            timestamp: iso(input.timestamp),
-            traits: input.traits ?? {},
-            ...(input.consent ? { consent: input.consent } : {}),
-        });
-    }
-    /** Something the user did. Returns the messageId. */
-    track(input) {
-        return this.enqueue({
-            type: "track",
-            messageId: input.messageId ?? randomUUID(),
-            userId: input.userId,
-            timestamp: iso(input.timestamp),
-            event: input.event,
-            properties: input.properties ?? {},
-            ...(input.traits ? { traits: input.traits } : {}),
-        });
-    }
-    /** Shorthand for the reserved `onboarding.step_completed` event. */
-    stepCompleted(userId, step, timestamp) {
-        return this.track({ userId, event: "onboarding.step_completed", properties: { step }, timestamp });
-    }
-    /** Send everything queued. Resolves with one result per request. */
-    async flush() {
-        this.clearTimer();
-        const results = [];
-        while (this.queue.length > 0) {
-            const batch = this.queue.splice(0, MAX_BATCH);
-            results.push(await this.send(batch));
-        }
-        return results;
-    }
-    /** Flush and stop the background timer (call on shutdown). */
-    async close() {
-        return this.flush();
+        this.#origin = originOf(opts.origin);
+        if (!isSecureOrigin(this.#origin))
+            throw new Error("YouGrow: origin must be https, e.g. https://yougrow.ai");
+        this.#authorization = `Basic ${Buffer.from(`${opts.keyId}:${opts.secret}`, "utf8").toString("base64")}`;
+        this.#timeoutMs = whole(opts.timeoutMs, 10_000, 1, MAX_TIMER_MS);
+        this.#maxRetries = whole(opts.maxRetries, 3, 0, Number.MAX_SAFE_INTEGER);
+        this.#maxRetryWaitMs = whole(opts.maxRetryWaitMs, 5_000, 0, MAX_TIMER_MS);
+        this.#fetch = opts.fetch ?? globalThis.fetch;
+        this.users = {
+            update: async (userId, patch) => (await this.#send("PATCH", userPath(userId), JSON.stringify(patch))),
+            batch: (items, batchOpts) => this.#patchMany(items, batchOpts),
+            get: async (userId) => {
+                try {
+                    return (await this.#send("GET", userPath(userId)));
+                }
+                catch (err) {
+                    // Only the API's own "no such user": a 404 from anything else (e.g. a wrong origin) still throws.
+                    if (err instanceof YouGrowError && err.status === 404 && err.code === "not_found")
+                        return null;
+                    throw err;
+                }
+            },
+            delete: async (userId) => {
+                await this.#send("DELETE", userPath(userId));
+            },
+        };
+        this.events = {
+            track: async (userId, event, options = {}) => {
+                const path = `${userPath(userId)}/events`;
+                const { properties, occurredAt } = options;
+                // One key for every attempt, so a retry is never recorded twice.
+                const body = { event, properties, occurredAt, idempotencyKey: options.idempotencyKey ?? randomUUID() };
+                return (await this.#send("POST", path, JSON.stringify(body)));
+            },
+        };
     }
-    enqueue(msg) {
-        this.queue.push(msg);
-        if (this.queue.length >= this.flushAt) {
-            void this.flush().catch((err) => this.onError?.(err));
+    async #patchMany(items, opts = {}) {
+        if (!Array.isArray(items))
+            throw new TypeError("YouGrow: users.batch takes an array of { userId, ...patch }");
+        const total = { applied: 0, ignored: 0, failed: 0, results: [] };
+        for (const chunk of chunks(items)) {
+            if (chunk.bytes > MAX_BODY_BYTES) {
+                // One item bigger than any request may be: it can't be valid, so it fails here.
+                const userId = asRecord(items[chunk.start])?.userId;
+                total.failed += 1;
+                total.results.push({ index: chunk.start, userId: typeof userId === "string" ? userId : null, status: "failed", reason: "body_too_large" });
+                continue;
+            }
+            const r = (await this.#send("POST", `${USERS_PATH}/batch`, `{"users":[${chunk.json.join(",")}]}`));
+            total.applied += r.applied;
+            total.ignored += r.ignored;
+            total.failed += r.failed;
+            for (const item of r.results)
+                total.results.push({ ...item, index: chunk.start + item.index });
         }
-        else if (this.flushIntervalMs > 0 && !this.timer) {
-            this.timer = setTimeout(() => {
-                this.timer = null;
-                void this.flush().catch((err) => this.onError?.(err));
-            }, this.flushIntervalMs);
-            this.timer.unref?.();
+        if (total.failed > 0) {
+            const summary = failureSummary(total, items.length);
+            if (opts.throwOnItemError)
+                throw new YouGrowBatchError(`YouGrow ${summary}`, total);
+            if (!opts.quiet)
+                console.warn(`[@yougrowai/node] ${summary}`);
         }
-        return msg.messageId;
+        return total;
     }
-    clearTimer() {
-        if (this.timer)
-            clearTimeout(this.timer);
-        this.timer = null;
-    }
-    async send(batch) {
-        const body = JSON.stringify({ batch });
+    /**
+     * One request, retried on network errors, timeouts, 429 and 5xx. Resolves
+     * with the JSON body (none for DELETE); an error status throws a YouGrowError.
+     */
+    async #send(method, path, body) {
+        const headers = { authorization: this.#authorization, accept: "application/json" };
+        if (body !== undefined)
+            headers["content-type"] = "application/json";
+        const doFetch = this.#fetch; // called unbound: some fetch implementations refuse another `this`
         for (let attempt = 0;; attempt += 1) {
-            // Sign every attempt afresh: the timestamp must stay inside the 5-minute window.
-            const ts = Math.floor(Date.now() / 1000);
             let res;
+            let text;
             try {
-                res = await this.fetchImpl(this.endpoint, {
-                    method: "POST",
-                    headers: {
-                        "content-type": "application/json",
-                        [HEADERS.keyId]: this.keyId,
-                        [HEADERS.timestamp]: String(ts),
-                        [HEADERS.signature]: sign(this.secret, "events", ts, body),
-                    },
-                    body,
-                });
+                res = await doFetch(`${this.#origin}${path}`, { method, headers, body, signal: AbortSignal.timeout(this.#timeoutMs) });
+                text = await res.text(); // under the same deadline
             }
             catch (err) {
-                if (attempt >= this.maxRetries)
+                // Network error or timeout.
+                if (attempt >= this.#maxRetries)
                     throw err;
-                await backoff(attempt);
+                await sleep(this.#retryWait(attempt));
                 continue;
             }
-            if (res.status === 202 || res.ok)
-                return (await res.json());
-            const retryable = res.status === 429 || res.status >= 500;
-            if (!retryable || attempt >= this.maxRetries) {
-                const data = await res.json().catch(() => undefined);
-                const code = data?.error ?? `http_${res.status}`;
-                throw new YouGrowError(`YouGrow ingest failed: ${code}`, res.status, data);
+            const data = parseJson(text);
+            if (res.ok) {
+                if (method !== "DELETE" && !asRecord(data)) {
+                    throw new YouGrowError(`YouGrow API ${res.status}: the response isn't JSON (is origin right?)`, res.status);
+                }
+                return data;
             }
-            await backoff(attempt, res.headers.get("retry-after"));
+            if ((res.status === 429 || res.status >= 500) && attempt < this.#maxRetries) {
+                await sleep(this.#retryWait(attempt, res.headers.get("retry-after")));
+                continue;
+            }
+            throw apiError(res.status, data);
         }
     }
+    /** Retry-After (seconds) if given, else exponential backoff with full jitter; never over maxRetryWaitMs. */
+    #retryWait(attempt, retryAfter) {
+        const seconds = retryAfter?.trim();
+        if (seconds && /^\d+$/.test(seconds))
+            return Math.min(Number(seconds) * 1000, this.#maxRetryWaitMs);
+        return Math.random() * Math.min(500 * 2 ** attempt, this.#maxRetryWaitMs);
+    }
+}
+/** `/api/v2/users/{userId}`, refusing an id the API can't take before anything is sent. */
+function userPath(userId) {
+    const problem = userIdProblem(userId);
+    if (problem)
+        throw new TypeError(`YouGrow: userId ${problem}`);
+    return `${USERS_PATH}/${encodeURIComponent(userId)}`;
+}
+function userIdProblem(userId) {
+    if (typeof userId !== "string")
+        return "must be a string";
+    if (userId.length === 0)
+        return "is empty";
+    if (userId.length > MAX_USER_ID)
+        return `is over ${MAX_USER_ID} characters`;
+    // "batch" is a route; "." and ".." vanish from a URL path.
+    if (userId === "batch" || userId === "." || userId === "..")
+        return `can't be "${userId}"`;
+    return null;
+}
+/**
+ * Consecutive runs of batch items, one request each: at most 100 users and
+ * 512 KB of body. A run over the limit is a single item too big to send.
+ */
+function* chunks(items) {
+    let chunk = { start: 0, json: [], bytes: BATCH_ENVELOPE_BYTES };
+    for (let i = 0; i < items.length; i += 1) {
+        const json = JSON.stringify(items[i]) ?? "null";
+        const size = Buffer.byteLength(json, "utf8");
+        // + 1 for the comma before it.
+        if (chunk.json.length === MAX_BATCH || (chunk.json.length > 0 && chunk.bytes + 1 + size > MAX_BODY_BYTES)) {
+            yield chunk;
+            chunk = { start: i, json: [], bytes: BATCH_ENVELOPE_BYTES };
+        }
+        chunk.bytes += (chunk.json.length > 0 ? 1 : 0) + size;
+        chunk.json.push(json);
+    }
+    if (chunk.json.length > 0)
+        yield chunk;
+}
+/** e.g. "users.batch: 2 of 250 users failed (u3: invalid, u17: invalid)". Ids and reasons only, never the data. */
+function failureSummary(r, count) {
+    const failed = r.results.filter((x) => x.status === "failed");
+    const shown = failed.slice(0, 3).map((x) => `${x.userId ?? `item ${x.index}`}: ${x.reason}`);
+    if (failed.length > 3)
+        shown.push(`+${failed.length - 3} more`);
+    return `users.batch: ${r.failed} of ${count} users failed${shown.length > 0 ? ` (${shown.join(", ")})` : ""}`;
+}
+/** e.g. "YouGrow API 400 invalid: traits.plan: …". */
+function apiError(status, body) {
+    const b = asRecord(body);
+    const fields = Array.isArray(b?.fields) ? b.fields : [];
+    let detail = fields
+        .slice(0, 3)
+        .map((f) => `${f.path}: ${f.message}`)
+        .join("; ");
+    if (fields.length > 3)
+        detail += `; +${fields.length - 3} more`;
+    if (!detail && typeof b?.message === "string")
+        detail = b.message;
+    const code = typeof b?.error === "string" ? ` ${b.error}` : "";
+    return new YouGrowError(`YouGrow API ${status}${code}${detail ? `: ${detail}` : ""}`, status, body);
+}
+function asRecord(v) {
+    return v !== null && typeof v === "object" && !Array.isArray(v) ? v : undefined;
+}
+function parseJson(text) {
+    try {
+        return text ? JSON.parse(text) : undefined;
+    }
+    catch {
+        return undefined;
+    }
 }
-function iso(t) {
-    if (t === undefined)
-        return new Date().toISOString();
-    return typeof t === "string" ? t : t.toISOString();
+/** A whole number in [min, max] from an option; unset or not a number means the default. */
+function whole(value, fallback, min, max) {
+    return typeof value === "number" && Number.isFinite(value) ? Math.min(Math.max(Math.floor(value), min), max) : fallback;
 }
-/** Exponential backoff with full jitter; honours Retry-After (seconds). */
-function backoff(attempt, retryAfter) {
-    const hinted = retryAfter && /^\d+$/.test(retryAfter) ? Number(retryAfter) * 1000 : 0;
-    const ms = hinted || Math.random() * Math.min(500 * 2 ** attempt, 10_000);
+function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }

package/dist/jwt.d.ts

@@ -8,7 +8,7 @@
  *   dir  "context" | "webhook"
  *   iat / exp   at most 5 minutes apart
  *   jti  unique per request
- *   body_sha256  base64url SHA-256 of the exact raw body
+ *   body_sha256  base64url SHA-256 of the exact raw body (the bytes as received)
  *
  * Signature first, then every claim. Pinned by test/vectors.json.
  */
@@ -48,6 +48,7 @@ export declare function verifyJwt(input: {
     issuer: string;
     audience: string;
     direction: RequestDirection;
-    rawBody: string;
+    /** The bytes as received; a string is hashed as UTF-8. */
+    rawBody: string | Uint8Array;
     nowMs?: number;
 }): JwtResult;

package/dist/jwt.js

@@ -67,7 +67,8 @@ export function verifyJwt(input) {
         return { ok: false, reason: "expired" };
     if (nowSec < c.iat - LEEWAY_SEC)
         return { ok: false, reason: "not_yet_valid" };
-    const hash = createHash("sha256").update(input.rawBody, "utf8").digest("base64url");
+    const bytes = typeof input.rawBody === "string" ? Buffer.from(input.rawBody, "utf8") : input.rawBody;
+    const hash = createHash("sha256").update(bytes).digest("base64url");
     if (c.body_sha256 !== hash)
         return { ok: false, reason: "body_mismatch" };
     return { ok: true, claims: c };