@rewloy/node 0.1.0

package/dist/generated/types.js

@@ -0,0 +1,3 @@
+// Generated by scripts/generate.ts from the Rewloy OpenAPI document
+// (openapi/openapi.json, API 1.0.0). Do not edit: run `npm run generate`.
+export {};

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @rewloy/node — the official Node.js and TypeScript library for the Rewloy API.
+ *
+ * ```ts
+ * import { Rewloy } from '@rewloy/node';
+ * const rewloy = new Rewloy({ apiKey: process.env.REWLOY_API_KEY! });
+ * ```
+ */
+export { Rewloy, DEFAULT_BASE_URL } from './client.js';
+export type { RewloyOptions } from './client.js';
+export { RewloyError, RateLimitError, RewloyConnectionError, RewloyTimeoutError } from './errors.js';
+export type { RewloyErrorInit } from './errors.js';
+export { EventStream, SseParser } from './sse.js';
+export type { ServerSentEvent } from './sse.js';
+export { verifyWebhook, signWebhook, WebhookSignatureError } from './webhooks.js';
+export type { WebhookEvent, PassEventData, VerifyWebhookOptions, SignWebhookOptions, WebhookSignatureReason } from './webhooks.js';
+export { OPERATIONS, ERROR_TITLES, API_VERSION } from './generated/operations.js';
+export type { ApiResponse, AuthKind, HttpMethod, OperationMeta, Page, RequestOptions, ResponseKind, StreamOptions } from './types.js';
+export type * from './generated/types.js';
+export { VERSION } from './version.js';
+import { Rewloy } from './client.js';
+export default Rewloy;

package/dist/index.js

@@ -0,0 +1,16 @@
+/**
+ * @rewloy/node — the official Node.js and TypeScript library for the Rewloy API.
+ *
+ * ```ts
+ * import { Rewloy } from '@rewloy/node';
+ * const rewloy = new Rewloy({ apiKey: process.env.REWLOY_API_KEY! });
+ * ```
+ */
+export { Rewloy, DEFAULT_BASE_URL } from "./client.js";
+export { RewloyError, RateLimitError, RewloyConnectionError, RewloyTimeoutError } from "./errors.js";
+export { EventStream, SseParser } from "./sse.js";
+export { verifyWebhook, signWebhook, WebhookSignatureError } from "./webhooks.js";
+export { OPERATIONS, ERROR_TITLES, API_VERSION } from "./generated/operations.js";
+export { VERSION } from "./version.js";
+import { Rewloy } from "./client.js";
+export default Rewloy;

package/dist/sse.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Server-sent events (`text/event-stream`), as the HTML standard parses them
+ * (https://html.spec.whatwg.org/multipage/server-sent-events.html), and the
+ * stream the client opens on `liveFeed` and `holderCardEvents`.
+ *
+ * The API's streams start with `retry: 5000`, send `: hb` every 25 seconds
+ * and events as `event: <type>` + `data: <text>`; they carry no `id:` today.
+ */
+/** One event of a stream. */
+export interface ServerSentEvent {
+    /** The type: the `event:` field, `message` when the event had none. */
+    event: string;
+    /** The `data:` lines, joined with "\n". */
+    data: string;
+    /** The last event ID: the latest `id:` field the stream has sent ("" if none). */
+    id: string;
+}
+/**
+ * The standard's parser, fed text in pieces of any size: a line, an event or
+ * a CRLF may be split anywhere between two pieces.
+ */
+export declare class SseParser {
+    #private;
+    /** The reconnection time the stream asked for (`retry:`), in milliseconds. */
+    retry: number | undefined;
+    /**
+     * The last event ID: set from the `id:` buffer at every blank line, kept from
+     * one event to the next, as the standard says.
+     */
+    lastEventId: string;
+    constructor(lastEventId?: string);
+    /** Feeds decoded text; returns the events it completed. */
+    push(text: string): ServerSentEvent[];
+    /** The stream ended: an event without its blank line is dropped, as the standard says. */
+    end(): void;
+}
+/** @internal How a stream asks the client for a connection. */
+export interface StreamSource {
+    operation: string;
+    /** Opens one connection: resolves with the answer once its headers are in. */
+    connect(lastEventId: string, controller: AbortController): Promise<Response>;
+    signal: AbortSignal | undefined;
+    reconnect: boolean;
+    idleTimeoutMs: number;
+    sleep(ms: number, signal?: AbortSignal): Promise<void>;
+}
+/**
+ * A live stream of server-sent events: iterate it with `for await`. It ends
+ * when the signal aborts, on `break`, on `close()`, or with a
+ * {@link RewloyError} that a reconnection cannot fix; with `reconnect: false`
+ * also when the connection ends.
+ */
+export declare class EventStream implements AsyncIterable<ServerSentEvent> {
+    #private;
+    /** The last event ID seen; sent as `Last-Event-ID` when reconnecting. */
+    lastEventId: string;
+    /** The wait before reconnecting, in milliseconds: the server's `retry:` once it sent one. */
+    retryMs: number;
+    /** `x-request-id` of the current connection. */
+    requestId: string | null;
+    /** `Rewloy-Mode` of the current connection (see `ApiResponse.mode`). */
+    mode: string | null;
+    /** @internal Use `client.stream()` or the operation's method. */
+    constructor(source: StreamSource);
+    [Symbol.asyncIterator](): AsyncGenerator<ServerSentEvent, void, undefined>;
+    /** Closes the connection and ends the iteration. */
+    close(): void;
+}

package/dist/sse.js

@@ -0,0 +1,251 @@
+/**
+ * Server-sent events (`text/event-stream`), as the HTML standard parses them
+ * (https://html.spec.whatwg.org/multipage/server-sent-events.html), and the
+ * stream the client opens on `liveFeed` and `holderCardEvents`.
+ *
+ * The API's streams start with `retry: 5000`, send `: hb` every 25 seconds
+ * and events as `event: <type>` + `data: <text>`; they carry no `id:` today.
+ */
+import { RewloyConnectionError, RewloyError, RewloyTimeoutError } from "./errors.js";
+/**
+ * The standard's parser, fed text in pieces of any size: a line, an event or
+ * a CRLF may be split anywhere between two pieces.
+ */
+export class SseParser {
+    /** The reconnection time the stream asked for (`retry:`), in milliseconds. */
+    retry = undefined;
+    /**
+     * The last event ID: set from the `id:` buffer at every blank line, kept from
+     * one event to the next, as the standard says.
+     */
+    lastEventId;
+    #id;
+    #line = '';
+    #data = '';
+    #event = '';
+    #afterCR = false;
+    #started = false;
+    constructor(lastEventId = '') {
+        this.lastEventId = lastEventId;
+        this.#id = lastEventId;
+    }
+    /** Feeds decoded text; returns the events it completed. */
+    push(text) {
+        const out = [];
+        let i = 0;
+        if (!this.#started && text.length) {
+            this.#started = true;
+            if (text.charCodeAt(0) === 0xfeff)
+                i = 1;
+        }
+        // A CR ended the previous piece: an LF right after it belongs to the same line ending.
+        if (this.#afterCR && i < text.length) {
+            if (text[i] === '\n')
+                i++;
+            this.#afterCR = false;
+        }
+        while (i < text.length) {
+            let j = i;
+            while (j < text.length && text[j] !== '\n' && text[j] !== '\r')
+                j++;
+            if (j === text.length) {
+                this.#line += text.slice(i);
+                break;
+            }
+            const line = this.#line + text.slice(i, j);
+            this.#line = '';
+            if (text[j] === '\r') {
+                if (j + 1 < text.length) {
+                    if (text[j + 1] === '\n')
+                        j++;
+                }
+                else
+                    this.#afterCR = true;
+            }
+            i = j + 1;
+            this.#take(line, out);
+        }
+        return out;
+    }
+    /** The stream ended: an event without its blank line is dropped, as the standard says. */
+    end() {
+        this.#line = '';
+        this.#data = '';
+        this.#event = '';
+        this.#afterCR = false;
+    }
+    #take(line, out) {
+        if (line === '') {
+            this.lastEventId = this.#id;
+            if (this.#data === '') {
+                this.#event = '';
+                return;
+            }
+            out.push({ event: this.#event || 'message', data: this.#data.endsWith('\n') ? this.#data.slice(0, -1) : this.#data, id: this.lastEventId });
+            this.#data = '';
+            this.#event = '';
+            return;
+        }
+        if (line.startsWith(':'))
+            return;
+        const colon = line.indexOf(':');
+        const field = colon === -1 ? line : line.slice(0, colon);
+        let value = colon === -1 ? '' : line.slice(colon + 1);
+        if (value.startsWith(' '))
+            value = value.slice(1);
+        switch (field) {
+            case 'event':
+                this.#event = value;
+                break;
+            case 'data':
+                this.#data += `${value}\n`;
+                break;
+            case 'id':
+                if (!value.includes('\0'))
+                    this.#id = value;
+                break;
+            case 'retry':
+                if (/^[0-9]+$/.test(value))
+                    this.retry = Number.parseInt(value, 10);
+                break;
+            default: break;
+        }
+    }
+}
+const DEFAULT_RETRY_MS = 3000;
+const MAX_RECONNECT_MS = 30_000;
+/** Errors a new connection may fix. */
+function transient(err) {
+    if (err instanceof RewloyConnectionError)
+        return true;
+    return err instanceof RewloyError && (err.status === 429 || err.status === 502 || err.status === 503 || err.status === 504 || (err.status >= 520 && err.status <= 524));
+}
+/**
+ * A live stream of server-sent events: iterate it with `for await`. It ends
+ * when the signal aborts, on `break`, on `close()`, or with a
+ * {@link RewloyError} that a reconnection cannot fix; with `reconnect: false`
+ * also when the connection ends.
+ */
+export class EventStream {
+    /** The last event ID seen; sent as `Last-Event-ID` when reconnecting. */
+    lastEventId = '';
+    /** The wait before reconnecting, in milliseconds: the server's `retry:` once it sent one. */
+    retryMs = DEFAULT_RETRY_MS;
+    /** `x-request-id` of the current connection. */
+    requestId = null;
+    /** `Rewloy-Mode` of the current connection (see `ApiResponse.mode`). */
+    mode = null;
+    #source;
+    #close = new AbortController();
+    /** Aborts on `close()` and on the caller's signal. */
+    #stop;
+    #iterator = null;
+    /** @internal Use `client.stream()` or the operation's method. */
+    constructor(source) {
+        this.#source = source;
+        this.#stop = source.signal ? AbortSignal.any([source.signal, this.#close.signal]) : this.#close.signal;
+    }
+    [Symbol.asyncIterator]() {
+        this.#iterator ??= this.#run();
+        return this.#iterator;
+    }
+    /** Closes the connection and ends the iteration. */
+    close() {
+        this.#close.abort();
+    }
+    #stopped() {
+        return this.#stop.aborted;
+    }
+    /** Waits before a reconnection; false when the stream was stopped meanwhile. */
+    async #wait(ms) {
+        try {
+            await this.#source.sleep(ms, this.#stop);
+        }
+        catch {
+            return false;
+        }
+        return !this.#stopped();
+    }
+    async *#run() {
+        const s = this.#source;
+        let failures = 0;
+        while (!this.#stopped()) {
+            const controller = new AbortController();
+            const onStop = () => controller.abort();
+            this.#stop.addEventListener('abort', onStop, { once: true });
+            let res;
+            try {
+                res = await s.connect(this.lastEventId, controller);
+            }
+            catch (err) {
+                this.#stop.removeEventListener('abort', onStop);
+                if (this.#stopped())
+                    return;
+                if (!s.reconnect || !transient(err))
+                    throw err;
+                failures++;
+                if (!(await this.#wait(Math.max(this.retryMs, Math.min(MAX_RECONNECT_MS, 1000 * 2 ** failures)))))
+                    return;
+                continue;
+            }
+            this.requestId = res.headers.get('x-request-id');
+            this.mode = res.headers.get('rewloy-mode');
+            const parser = new SseParser(this.lastEventId);
+            const decoder = new TextDecoder();
+            let idle;
+            let silent = false;
+            const arm = () => {
+                if (!(s.idleTimeoutMs > 0 && s.idleTimeoutMs < 2 ** 31))
+                    return;
+                clearTimeout(idle);
+                idle = setTimeout(() => { silent = true; controller.abort(); }, s.idleTimeoutMs);
+            };
+            let dropped = null;
+            try {
+                if (!res.body)
+                    throw new TypeError('the answer has no body');
+                const reader = res.body.getReader();
+                arm();
+                for (;;) {
+                    const { done, value } = await reader.read();
+                    const text = done ? decoder.decode() : decoder.decode(value, { stream: true });
+                    if (!done)
+                        arm();
+                    for (const event of parser.push(text)) {
+                        this.lastEventId = event.id;
+                        failures = 0;
+                        yield event;
+                    }
+                    this.lastEventId = parser.lastEventId;
+                    if (parser.retry !== undefined)
+                        this.retryMs = parser.retry;
+                    if (done)
+                        break;
+                }
+                parser.end();
+            }
+            catch (err) {
+                if (this.#stopped())
+                    return;
+                dropped = silent
+                    ? new RewloyTimeoutError({ detail: `no data for ${String(s.idleTimeoutMs)} ms`, operation: s.operation, requestId: this.requestId })
+                    : new RewloyConnectionError({ detail: err instanceof Error ? err.message : String(err), operation: s.operation, requestId: this.requestId, cause: err });
+            }
+            finally {
+                clearTimeout(idle);
+                controller.abort();
+                this.#stop.removeEventListener('abort', onStop);
+            }
+            if (!s.reconnect) {
+                if (dropped)
+                    throw dropped;
+                return;
+            }
+            if (dropped)
+                failures++;
+            const delay = dropped ? Math.max(this.retryMs, Math.min(MAX_RECONNECT_MS, 1000 * 2 ** failures)) : this.retryMs;
+            if (!(await this.#wait(delay)))
+                return;
+        }
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Hand-written types shared by the client and the generated code
+ * (src/generated/), which imports them.
+ */
+import type { PageMeta } from './generated/types.js';
+/**
+ * A credential kind of the Rewloy API, as the OpenAPI document's
+ * `x-credentials` names them:
+ *   - `key`: an API key (`rwk_…`);
+ *   - `staff`: a staff session (`rws_…`);
+ *   - `holder`: a card holder's session (`rwh_…`);
+ *   - `public`: no credential.
+ */
+export type AuthKind = 'key' | 'staff' | 'holder' | 'public';
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+/**
+ * How a successful answer is read:
+ *   - `json`: the `{ data }` envelope (with `meta` on paged lists);
+ *   - `none`: 204, no body;
+ *   - `blob`: a file (image, CSV, pass), returned as a `Blob`;
+ *   - `raw-json`: JSON without the envelope (the OpenAPI document itself);
+ *   - `stream`: server-sent events.
+ */
+export type ResponseKind = 'json' | 'none' | 'blob' | 'raw-json' | 'stream';
+/** One row of the metadata table (`OPERATIONS`): what the client needs to call an operation. */
+export interface OperationMeta {
+    readonly method: HttpMethod;
+    /** The path with `{name}` placeholders, `/v1` included. */
+    readonly path: string;
+    /** The credential kinds the operation accepts. */
+    readonly auth: readonly AuthKind[];
+    /** Takes the `Rewloy-Merchant` header (staff sessions with seats in several businesses). */
+    readonly merchant: boolean;
+    /** Takes an `Idempotency-Key` header: `required`, `optional`, or not at all. */
+    readonly idempotency: 'required' | 'optional' | null;
+    /** Has a JSON request body. */
+    readonly body: boolean;
+    readonly response: ResponseKind;
+    /** A paged list: `page`/`limit` in, `meta` out. */
+    readonly paged: boolean;
+    /** Answers with server-sent events. */
+    readonly stream: boolean;
+    /**
+     * Marked for removal. `sunset` is the last day it works (YYYY-MM-DD) and `use`
+     * the operation that replaces it, when the document says so.
+     */
+    readonly deprecated: {
+        readonly sunset: string | null;
+        readonly use: string | null;
+    } | null;
+}
+/** Options every call takes. */
+export interface RequestOptions {
+    /** Cancels the call (and any retry still waiting). The promise rejects with the signal's reason. */
+    signal?: AbortSignal | undefined;
+    /**
+     * Time allowed for one attempt, in milliseconds: until the whole answer has
+     * arrived (for a stream: until its headers have). Overrides the client's.
+     */
+    timeoutMs?: number | undefined;
+    /** Retries after the first attempt. Overrides the client's. */
+    maxRetries?: number | undefined;
+}
+/** Options of a server-sent event stream (`Rewloy.stream`). */
+export interface StreamOptions {
+    /**
+     * Reconnect when the connection drops or the server ends the stream, as a
+     * browser's `EventSource` does: after the server's `retry:` delay, with
+     * `Last-Event-ID` once an event carried an id. Errors that a reconnection
+     * cannot fix (401, 403, 404…) end the stream with a `RewloyError`.
+     * Default `true`.
+     */
+    reconnect?: boolean | undefined;
+    /**
+     * Treat the connection as dead after this many milliseconds without a byte
+     * (the API sends a heartbeat every 25 seconds). `0` turns the check off.
+     * Default 60000.
+     */
+    idleTimeoutMs?: number | undefined;
+}
+/** One page of a paged list, as the API answers it. */
+export interface Page<T> {
+    data: T[];
+    meta: PageMeta;
+}
+/** The whole answer to a call (`Rewloy.request`). */
+export interface ApiResponse<T> {
+    /** What `data` held (a `Blob` for files, `undefined` for 204). */
+    data: T;
+    /** Paging, on paged lists. */
+    meta: PageMeta | undefined;
+    /** The HTTP status: 200, 201, 202 or 204. Some operations answer 200 when they found what they would have created. */
+    status: number;
+    headers: Headers;
+    /** `x-request-id`: quote it to Rewloy support. */
+    requestId: string | null;
+    /**
+     * `Rewloy-Mode`: which mode answered (`test` for test keys, once the platform
+     * has test mode); `null` when the answer does not say.
+     */
+    mode: string | null;
+    /** `Idempotent-Replayed: true`: the API replayed the first answer to this `Idempotency-Key`. */
+    replayed: boolean;
+}

package/dist/types.js

@@ -0,0 +1,5 @@
+/**
+ * Hand-written types shared by the client and the generated code
+ * (src/generated/), which imports them.
+ */
+export {};

package/dist/version.d.ts

@@ -0,0 +1,2 @@
+/** This library's version (package.json's; test/client.test.ts keeps them equal). */
+export declare const VERSION = "0.1.0";

package/dist/version.js

@@ -0,0 +1,2 @@
+/** This library's version (package.json's; test/client.test.ts keeps them equal). */
+export const VERSION = '0.1.0';

package/dist/webhooks.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Webhook signatures, exactly as the platform signs a delivery:
+ *
+ *   Rewloy-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256(secret, "<t>.<raw body>")>
+ *
+ * The key is the whole secret as shown once when the webhook was created
+ * (`whsec_…`, prefix included); the message is the timestamp, a dot and the
+ * body's bytes as they arrived. Each delivery attempt is signed anew, so a
+ * retry carries a fresh `t`.
+ *
+ * Every delivery also carries `Rewloy-Event` (the event type, as `type` in the
+ * body) and `Rewloy-Delivery` (the delivery's id: the same on every retry of
+ * one delivery; deliveries are at least once, so skip an id already handled).
+ */
+/** What a webhook's `data` holds for the `pass.*` events (only business facts, never contact details). */
+export interface PassEventData {
+    /** What happened on the card: `join`, `earn`, `redeem`, `spend`, `visit_credit`, `load`, `void`… */
+    kind: string;
+    /** The card's serial number, XXXX-XXXX-XXXX. */
+    card: string | null;
+    program_id: string | null;
+    location_id: string | null;
+    customer_id: string | null;
+    /** What `delta` counts: `stamp`, `point`, `try_minor` (kuruş)… */
+    unit?: string;
+    delta?: number;
+    reward?: unknown;
+    use?: unknown;
+    reason?: string;
+    [key: string]: unknown;
+}
+/**
+ * A webhook delivery's body. Read the person behind `customer_id` from the
+ * API; new event types may appear, so keep a default branch.
+ */
+export type WebhookEvent = {
+    /** The event's id. */
+    id: string;
+    type: 'pass.issued' | 'pass.activity' | 'pass.voided';
+    created_at: string;
+    data: PassEventData;
+} | {
+    /** The panel's or `testWebhook`'s test delivery: no event behind it. */
+    id?: undefined;
+    type: 'webhook.test';
+    created_at: string;
+    data: {
+        message: string;
+    };
+};
+/** Why a delivery was refused. */
+export type WebhookSignatureReason = 'missing' | 'malformed' | 'expired' | 'mismatch' | 'payload';
+/** The delivery is not a genuine one: answer it with 400 and do not act on it. */
+export declare class WebhookSignatureError extends Error {
+    readonly reason: WebhookSignatureReason;
+    constructor(reason: WebhookSignatureReason, message: string);
+}
+export interface VerifyWebhookOptions {
+    /**
+     * The body exactly as it arrived: a string or the raw bytes. Not a parsed
+     * object: JSON parsing and re-serializing changes the bytes the signature
+     * covers (in Express use `express.raw({ type: 'application/json' })`).
+     */
+    payload: string | Uint8Array | ArrayBuffer;
+    /** The `Rewloy-Signature` header. */
+    header: string | readonly string[] | null | undefined;
+    /** The webhook's secret (`whsec_…`); several while you move from one webhook to another. */
+    secret: string | readonly string[];
+    /** How far `t` may be from now, in seconds. Default 300. */
+    toleranceSeconds?: number | undefined;
+    /** The current time: a `Date`, or Unix time in seconds (the unit of `t`). For tests. */
+    now?: Date | number | undefined;
+}
+/**
+ * Checks a delivery's `Rewloy-Signature` and returns its parsed body.
+ * Throws {@link WebhookSignatureError} when the header is missing or
+ * malformed, `t` is further than `toleranceSeconds` from now, or no `v1`
+ * matches; the comparison takes constant time.
+ */
+export declare function verifyWebhook<T = WebhookEvent>(options: VerifyWebhookOptions): T;
+export interface SignWebhookOptions {
+    payload: string | Uint8Array | ArrayBuffer;
+    secret: string;
+    /** Unix time in seconds; default now. */
+    timestamp?: number | undefined;
+}
+/**
+ * The `Rewloy-Signature` header the platform would send for this body: for
+ * testing your own webhook handler.
+ */
+export declare function signWebhook(options: SignWebhookOptions): string;

package/dist/webhooks.js

@@ -0,0 +1,98 @@
+/**
+ * Webhook signatures, exactly as the platform signs a delivery:
+ *
+ *   Rewloy-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256(secret, "<t>.<raw body>")>
+ *
+ * The key is the whole secret as shown once when the webhook was created
+ * (`whsec_…`, prefix included); the message is the timestamp, a dot and the
+ * body's bytes as they arrived. Each delivery attempt is signed anew, so a
+ * retry carries a fresh `t`.
+ *
+ * Every delivery also carries `Rewloy-Event` (the event type, as `type` in the
+ * body) and `Rewloy-Delivery` (the delivery's id: the same on every retry of
+ * one delivery; deliveries are at least once, so skip an id already handled).
+ */
+import { createHmac, timingSafeEqual } from 'node:crypto';
+/** The delivery is not a genuine one: answer it with 400 and do not act on it. */
+export class WebhookSignatureError extends Error {
+    reason;
+    constructor(reason, message) {
+        super(message);
+        this.reason = reason;
+    }
+}
+Object.defineProperty(WebhookSignatureError.prototype, 'name', { value: 'WebhookSignatureError', writable: true, configurable: true });
+const V1 = /^[0-9a-f]{64}$/i;
+function bytesOf(payload) {
+    if (typeof payload === 'string')
+        return Buffer.from(payload, 'utf8');
+    if (payload instanceof ArrayBuffer)
+        return Buffer.from(payload);
+    if (ArrayBuffer.isView(payload))
+        return Buffer.from(payload.buffer, payload.byteOffset, payload.byteLength);
+    throw new TypeError('verifyWebhook: `payload` must be the raw body (a string or bytes), not a parsed object');
+}
+function signature(secret, t, body) {
+    return createHmac('sha256', secret).update(`${t}.`).update(body).digest();
+}
+/**
+ * Checks a delivery's `Rewloy-Signature` and returns its parsed body.
+ * Throws {@link WebhookSignatureError} when the header is missing or
+ * malformed, `t` is further than `toleranceSeconds` from now, or no `v1`
+ * matches; the comparison takes constant time.
+ */
+export function verifyWebhook(options) {
+    const { header, toleranceSeconds = 300 } = options;
+    const body = bytesOf(options.payload);
+    const secrets = (typeof options.secret === 'string' ? [options.secret] : [...options.secret]).filter((s) => s !== '');
+    if (!secrets.length)
+        throw new TypeError('verifyWebhook: `secret` is empty');
+    const value = typeof header === 'string' ? header : Array.isArray(header) ? header.join(',') : '';
+    if (!value.trim())
+        throw new WebhookSignatureError('missing', 'No Rewloy-Signature header');
+    let t;
+    const candidates = [];
+    for (const part of value.split(',')) {
+        const eq = part.indexOf('=');
+        if (eq === -1)
+            continue;
+        const k = part.slice(0, eq).trim();
+        const v = part.slice(eq + 1).trim();
+        if (k === 't' && t === undefined)
+            t = v;
+        else if (k === 'v1' && V1.test(v))
+            candidates.push(Buffer.from(v, 'hex'));
+    }
+    if (t === undefined || !/^\d+$/.test(t) || !candidates.length) {
+        throw new WebhookSignatureError('malformed', 'Rewloy-Signature is not "t=<unix seconds>,v1=<hex>"');
+    }
+    const now = options.now === undefined ? Date.now() / 1000 : options.now instanceof Date ? options.now.getTime() / 1000 : options.now;
+    if (Math.abs(now - Number(t)) > toleranceSeconds) {
+        throw new WebhookSignatureError('expired', `The signature's time (t=${t}) is more than ${String(toleranceSeconds)} seconds from now`);
+    }
+    let match = false;
+    for (const secret of secrets) {
+        const expected = signature(secret, t, body);
+        for (const candidate of candidates) {
+            // Every pair is compared, in constant time, whether or not one matched already.
+            if (timingSafeEqual(candidate, expected))
+                match = true;
+        }
+    }
+    if (!match)
+        throw new WebhookSignatureError('mismatch', 'No v1 signature matches the body and the secret');
+    try {
+        return JSON.parse(body.toString('utf8'));
+    }
+    catch {
+        throw new WebhookSignatureError('payload', 'The signed body is not JSON');
+    }
+}
+/**
+ * The `Rewloy-Signature` header the platform would send for this body: for
+ * testing your own webhook handler.
+ */
+export function signWebhook(options) {
+    const t = String(Math.floor(options.timestamp ?? Date.now() / 1000));
+    return `t=${t},v1=${signature(options.secret, t, bytesOf(options.payload)).toString('hex')}`;
+}