@genesis-tech/genesispay-seller 0.8.0

package/dist/webhooks.d.ts

@@ -0,0 +1,277 @@
+/**
+ * Every event type this SDK version knows. Mirrors the server's
+ * `WebhookEventType` (`src/features/sellers/webhooks.ts`) — the drift alarm is
+ * `src/features/sellers/webhook-signature-contract.test.ts`, which fails when
+ * the server grows a type this list does not have.
+ *
+ * Exported as a runtime array (not only as a type) so a handler can ask
+ * `isKnownPeerPayEventType(event.type)` before it decides what to do.
+ */
+export declare const PEERPAY_EVENT_TYPES: readonly ["payment.confirmed", "link.paid", "agent_payment.pending_approval", "agent_payment.settled", "mandate.active", "mandate.charged", "mandate.charge_failed", "mandate.revoked", "subscription.renewed", "subscription.past_due"];
+/** Union of the event types this SDK version knows. */
+export type PeerPayEventType = (typeof PEERPAY_EVENT_TYPES)[number];
+/** True when `type` is an event type this SDK version knows about. */
+export declare function isKnownPeerPayEventType(type: string): type is PeerPayEventType;
+/** Shared envelope; `type`/`data` are pinned per event by the union below. */
+type PeerPayEventEnvelope<TType extends string, TData> = {
+    /** Stable across delivery retries — the idempotency key to dedupe on. */
+    id: string;
+    type: TType;
+    createdAt: string;
+    data: TData;
+};
+/**
+ * `data` of `payment.confirmed` / `link.paid`. Mirrors the server's
+ * `PaymentWebhookEventPayload`; amounts stay strings (minor units are `bigint`
+ * on the server and would lose precision as a JSON number).
+ */
+export type PeerPayPaymentEventData = {
+    link: {
+        publicId: string;
+        title: string;
+        /**
+         * The currency `amount` is denominated in. Read it before you book the
+         * money: a EURC link settles in euros, and nothing else in this payload
+         * says so.
+         *
+         * **Optional on purpose, unlike every other field here.** The payload is
+         * not re-validated at runtime — `constructEvent` checks the signature and
+         * the envelope, then hands the body over — and a delivery enqueued before
+         * this field existed is stored and *retried* verbatim, so it can still
+         * arrive without one. There is no safe default to fill in: guessing
+         * `"USDC"` on a euro payment is the exact confusion this field was added to
+         * remove. Treat an absent asset as "cannot book this yet" — ack the
+         * delivery, alert, resolve the link through `checkout.retrieve`.
+         */
+        asset?: "USDC" | "EURC";
+        /**
+         * Decimal amount in `asset` — euros on a EURC link, dollars on a USDC one.
+         * A delivery that predates this field omits it, but unlike `asset` it has a
+         * safe fallback: `amount ?? amountUsdc`, which always carried the identical
+         * value. That is why this one is typed as present and `asset` is not.
+         *
+         * The two are emitted by the same code path, so a delivery missing one is
+         * missing the other and the `asset` guard fires first — the fallback is
+         * belt-and-braces, not the main line of defence. Keep them emitted together
+         * if you ever change that path.
+         */
+        amount: string;
+        amountUsdcMinor: string;
+        /**
+         * @deprecated Same value as `amount`. The name is wrong on a EURC link —
+         * it carries euros there — which is why `amount` replaced it. Still sent on
+         * every delivery; removed no earlier than 1.0.
+         */
+        amountUsdc: string;
+        linkType: "single" | "reusable";
+        /** Correlation data set at link creation, echoed verbatim. */
+        metadata: Record<string, string> | null;
+        clientReferenceId: string | null;
+    };
+    attempt: {
+        id: string;
+        /** `null` for simulated payments — there is no transaction to link to. */
+        txHash: string | null;
+        /**
+         * The chain `txHash` is on. Today every settlement reports `8453`/`84532`
+         * (Base mainnet/Sepolia) — but do **not** hard-code that as the whole set.
+         * Match the chain you expect and treat anything else as unrecognized rather
+         * than as test money; a bare `chainId !== 8453` test inverts on the first
+         * chain that is added.
+         *
+         * Read it *with* the hash and never separately: the same hash string
+         * resolves to nothing on the wrong chain, and a testnet settlement is
+         * otherwise indistinguishable from a mainnet one.
+         *
+         * It sits here rather than on `link` because the two can differ: a
+         * settlement broadcast by a provider lands on the chain that provider uses,
+         * which is not necessarily the chain the link was created for.
+         *
+         * `null` when there is no hash to resolve, or the provider named no chain.
+         * Optional — a delivery enqueued before this field existed is retried
+         * verbatim and arrives without it. **Do not default it.** Note the polarity
+         * trap: `undefined !== 8453` is true, so the natural `if (chainId !== 8453)`
+         * check reads a *missing* chain as testnet, and the mirror check reads it as
+         * mainnet. Branch on presence first.
+         */
+        chainId?: number | null;
+        payerWallet: string | null;
+        createdAt: string;
+        confirmedAt: string | null;
+        /**
+         * `true` when no funds moved — a test-mode `simulate-payment` attempt.
+         * `false` for a real settlement, including on testnet and in provider
+         * sandboxes: this is the fabricated-payment axis, not the environment axis.
+         */
+        simulated: boolean;
+        /**
+         * The gross the link is priced at, in minor units of `link.asset` (=
+         * `link.amountUsdcMinor`). Additive with the fee triplet below; older
+         * deliveries enqueued before these fields existed arrive without them, so
+         * treat them as optional and do not default `feeCollected` (MR-804).
+         */
+        amountMinor?: string;
+        /** Platform fee snapshot in minor units of `link.asset`. */
+        feeMinor?: string;
+        /**
+         * `amountMinor − feeMinor` — what the seller nets IF the fee is collected
+         * on-chain. Do not book it unconditionally: the seller's actual on-chain
+         * credit is `feeCollected ? netMinor : amountMinor`. A record-only leg
+         * (`feeCollected: false`) credited the seller the full `amountMinor` — the
+         * fee is a receivable that did not move at settlement.
+         */
+        netMinor?: string;
+        /**
+         * Whether the fee actually moved to the treasury on-chain. `false` on a
+         * record-only leg (single-auth checkout, agent, EUR, or a pending
+         * receivable) is correct, not a bug. Do not infer it from the presence of
+         * `feeTxHash` alone; read this flag — it is the switch for what the seller
+         * was credited: `feeCollected ? netMinor : amountMinor`.
+         */
+        feeCollected?: boolean;
+        /** The fee leg's tx hash; `null` unless the fee was collected on-chain. */
+        feeTxHash?: string | null;
+    };
+    occurredAt: string;
+};
+/** `data` of the mandate/subscription events; mirrors `buildMandateWebhookPayload`. */
+export type PeerPayMandateEventData = {
+    mandate: {
+        id: string;
+        kind: string;
+        status: string;
+        payerWallet: string;
+        /**
+         * Which plan the subscription belongs to — without it a `mandate.active`
+         * handler knows *that* someone subscribed but not *to what*. `null` for
+         * mandates proposed directly rather than through a plan checkout. Like
+         * every field here it mirrors the current server payload and is not
+         * re-validated at runtime, so read it as `?? null` if you also accept
+         * deliveries from a deployment that predates the field.
+         */
+        subscriptionPlanId: string | null;
+        asset: string;
+        allowanceMinor: string;
+        capPerChargeMinor: string;
+        spentMinor: string;
+        amountPerPeriodMinor: string | null;
+        periodDays: number | null;
+        nextChargeAt: string | null;
+    };
+    charge: {
+        id: string;
+        kind: string;
+        amountMinor: string;
+        status: string;
+        txHash: string | null;
+        /**
+         * The platform fee in minor units of the mandate's `asset` (MR-104). The
+         * seller receives `amountMinor − feeMinor` once the fee is collected.
+         *
+         * Optional like every field added after launch: `webhook_deliveries` rows
+         * are replayed verbatim, so a delivery enqueued before this field existed
+         * arrives without it. Read it as `?? null`.
+         */
+        feeMinor?: string;
+        /**
+         * Whether the fee was collected on-chain (MR-1008/MR-1009). `true` only
+         * when the fee leg's transfer confirmed; `false` on every record-only leg
+         * (a deployment not collecting on the mandate leg, or a still-pending
+         * receivable) — and that `false` is the honest state, not an error. Do NOT
+         * default a missing value to `false`: absent means the delivery predates the
+         * field, not that nothing was collected.
+         */
+        feeCollected?: boolean;
+        /** The fee leg's tx hash; `null` unless the fee was collected on-chain. */
+        feeTxHash?: string | null;
+        resourceUrl: string | null;
+        failureReason: string | null;
+    } | null;
+    occurredAt: string;
+};
+export type PeerPayPaymentEvent = PeerPayEventEnvelope<"payment.confirmed" | "link.paid", PeerPayPaymentEventData>;
+export type PeerPayMandateEvent = PeerPayEventEnvelope<"mandate.active" | "mandate.charged" | "mandate.charge_failed" | "mandate.revoked" | "subscription.renewed" | "subscription.past_due", PeerPayMandateEventData>;
+/**
+ * Agent-payment events are reserved on the server but have no emitter yet, so
+ * their payload is deliberately left open rather than invented here.
+ */
+export type PeerPayAgentPaymentEvent = PeerPayEventEnvelope<"agent_payment.pending_approval" | "agent_payment.settled", Record<string, unknown>>;
+/**
+ * An event type this SDK version does not know — a newer server talking to an
+ * older SDK. It is a *valid* event: `constructEvent` verifies and returns it
+ * like any other (see `PeerPayAnyEvent`), it never throws on the type.
+ */
+export type PeerPayUnknownEvent = PeerPayEventEnvelope<string, Record<string, unknown>>;
+/**
+ * Verified webhook delivery, discriminated on `type`:
+ *
+ * ```ts
+ * if (event.type === "payment.confirmed") {
+ *   event.data.attempt.txHash; // typed, no cast
+ * }
+ * ```
+ *
+ * **Why this union has no `{ type: string & {} }` member.** TypeScript only
+ * narrows on a discriminant whose type is a literal in *every* constituent: add
+ * one member with a plain `string` type and `event.type === "payment.confirmed"`
+ * stops narrowing `data` for all the others too — the exact regression R1 sets
+ * out to fix. Forward compatibility therefore lives at runtime (an unknown type
+ * is verified and returned, never rejected) plus in `PeerPayAnyEvent` /
+ * `PeerPayUnknownEvent` for handlers that want to model the open world:
+ *
+ * ```ts
+ * const any: PeerPayAnyEvent = event;            // widens, no cast needed
+ * if (!isKnownPeerPayEventType(any.type)) return new Response("ok"); // ack & ignore
+ * ```
+ */
+export type PeerPayEvent = PeerPayPaymentEvent | PeerPayMandateEvent | PeerPayAgentPaymentEvent;
+/**
+ * Open-world view of a delivery: every known event widens to it, and it is the
+ * honest type for an event whose `type` this SDK version does not know.
+ */
+export type PeerPayAnyEvent = PeerPayEvent | PeerPayUnknownEvent;
+/**
+ * Thrown for every rejection path: malformed/missing header, missing `t`/`v1`,
+ * timestamp outside the tolerance window, signature mismatch, non-JSON body.
+ * Messages never contain the secret or the expected signature.
+ */
+export declare class PeerPaySignatureVerificationError extends Error {
+    constructor(message: string);
+}
+export type ConstructEventOptions = {
+    /** Replay window in seconds, applied in both directions. Default 300. */
+    toleranceSeconds?: number;
+    /** Injectable clock (epoch milliseconds); defaults to `Date.now()`. */
+    nowMs?: number;
+};
+/**
+ * Verifies a GenesisPay webhook delivery and returns the parsed event.
+ *
+ * Pass the **raw** request body exactly as received — never a re-serialized
+ * `JSON.parse` + `JSON.stringify` round trip, which changes the bytes and
+ * invalidates the signature. Parsing happens only after verification succeeds.
+ *
+ * An event type this SDK version does not know is **not** a failure: the
+ * delivery is verified and returned unchanged, so a server that adds a new
+ * event type can never turn a customer's webhook route into a 400. Only the
+ * signature and the envelope (`id`, `type`, `createdAt`, object `data`) can
+ * reject a delivery. Widen to `PeerPayAnyEvent` and use
+ * `isKnownPeerPayEventType()` if you want to handle that case explicitly.
+ *
+ * @throws {PeerPaySignatureVerificationError} on any verification failure.
+ *
+ * @example
+ * ```ts
+ * const event = await constructEvent(
+ *   await request.text(),
+ *   request.headers.get("peerpay-signature") ?? "",
+ *   process.env.PEERPAY_WEBHOOK_SECRET!,
+ * );
+ * if (event.type === "payment.confirmed") {
+ *   fulfil(event.data.link.clientReferenceId, event.data.attempt.txHash);
+ * }
+ * ```
+ */
+export declare function constructEvent(rawBody: string | Uint8Array, signatureHeader: string, secret: string, opts?: ConstructEventOptions): Promise<PeerPayEvent>;
+export {};
+//# sourceMappingURL=webhooks.d.ts.map

package/dist/webhooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhooks.d.ts","sourceRoot":"","sources":["../src/webhooks.ts"],"names":[],"mappings":"AAYA;;;;;;;;GAQG;AACH,eAAO,MAAM,mBAAmB,0OAWtB,CAAC;AAEX,uDAAuD;AACvD,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEpE,sEAAsE;AACtE,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,IAAI,gBAAgB,CAE9E;AAED,8EAA8E;AAC9E,KAAK,oBAAoB,CAAC,KAAK,SAAS,MAAM,EAAE,KAAK,IAAI;IACvD,yEAAyE;IACzE,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,KAAK,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,KAAK,CAAC;CACb,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,uBAAuB,GAAG;IACpC,IAAI,EAAE;QACJ,QAAQ,EAAE,MAAM,CAAC;QACjB,KAAK,EAAE,MAAM,CAAC;QACd;;;;;;;;;;;;;WAaG;QACH,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;QACxB;;;;;;;;;;WAUG;QACH,MAAM,EAAE,MAAM,CAAC;QACf,eAAe,EAAE,MAAM,CAAC;QACxB;;;;WAIG;QACH,UAAU,EAAE,MAAM,CAAC;QACnB,QAAQ,EAAE,QAAQ,GAAG,UAAU,CAAC;QAChC,8DAA8D;QAC9D,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC;QACxC,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;KAClC,CAAC;IACF,OAAO,EAAE;QACP,EAAE,EAAE,MAAM,CAAC;QACX,0EAA0E;QAC1E,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;QACtB;;;;;;;;;;;;;;;;;;;;;WAqBG;QACH,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QACxB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;QAC3B,SAAS,EAAE,MAAM,CAAC;QAClB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;QAC3B;;;;WAIG;QACH,SAAS,EAAE,OAAO,CAAC;QACnB;;;;;WAKG;QACH,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,4DAA4D;QAC5D,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB;;;;;;WAMG;QACH,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB;;;;;;WAMG;QACH,YAAY,CAAC,EAAE,OAAO,CAAC;QACvB,2EAA2E;QAC3E,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;KAC3B,CAAC;IACF,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,uFAAuF;AACvF,MAAM,MAAM,uBAAuB,GAAG;IACpC,OAAO,EAAE;QACP,EAAE,EAAE,MAAM,CAAC;QACX,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,MAAM,CAAC;QACf,WAAW,EAAE,MAAM,CAAC;QACpB;;;;;;;WAOG;QACH,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;QAClC,KAAK,EAAE,MAAM,CAAC;QACd,cAAc,EAAE,MAAM,CAAC;QACvB,iBAAiB,EAAE,MAAM,CAAC;QAC1B,UAAU,EAAE,MAAM,CAAC;QACnB,oBAAoB,EAAE,MAAM,GAAG,IAAI,CAAC;QACpC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;QAC1B,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;KAC7B,CAAC;IACF,MAAM,EAAE;QACN,EAAE,EAAE,MAAM,CAAC;QACX,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,EAAE,MAAM,CAAC;QACpB,MAAM,EAAE,MAAM,CAAC;QACf,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;QACtB;;;;;;;WAOG;QACH,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB;;;;;;;WAOG;QACH,YAAY,CAAC,EAAE,OAAO,CAAC;QACvB,2EAA2E;QAC3E,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAC1B,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;QAC3B,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;KAC9B,GAAG,IAAI,CAAC;IACT,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG,oBAAoB,CACpD,mBAAmB,GAAG,WAAW,EACjC,uBAAuB,CACxB,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG,oBAAoB,CAClD,gBAAgB,GAChB,iBAAiB,GACjB,uBAAuB,GACvB,iBAAiB,GACjB,sBAAsB,GACtB,uBAAuB,EACzB,uBAAuB,CACxB,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,wBAAwB,GAAG,oBAAoB,CACzD,gCAAgC,GAAG,uBAAuB,EAC1D,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CACxB,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,mBAAmB,GAAG,oBAAoB,CACpD,MAAM,EACN,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CACxB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,MAAM,YAAY,GACpB,mBAAmB,GACnB,mBAAmB,GACnB,wBAAwB,CAAC;AAE7B;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG,YAAY,GAAG,mBAAmB,CAAC;AAEjE;;;;GAIG;AACH,qBAAa,iCAAkC,SAAQ,KAAK;gBAC9C,OAAO,EAAE,MAAM;CAI5B;AAED,MAAM,MAAM,qBAAqB,GAAG;IAClC,yEAAyE;IACzE,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,uEAAuE;IACvE,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAwIF;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAsB,cAAc,CAClC,OAAO,EAAE,MAAM,GAAG,UAAU,EAC5B,eAAe,EAAE,MAAM,EACvB,MAAM,EAAE,MAAM,EACd,IAAI,GAAE,qBAA0B,GAC/B,OAAO,CAAC,YAAY,CAAC,CA0FvB"}

package/dist/webhooks.js

@@ -0,0 +1,223 @@
+// Webhook signature verification for GenesisPay deliveries.
+//
+// The server signs every delivery in `src/features/sellers/webhooks.ts`:
+//
+//   PEERPAY-SIGNATURE: t=<unix-seconds>,v1=<hex>
+//   v1 = HMAC_SHA256(secret, `${t}.${rawBody}`)
+//
+// Deliberately implemented on WebCrypto (`globalThis.crypto.subtle`) rather
+// than `node:crypto` so the SDK also runs on Edge runtimes, Cloudflare Workers
+// and Bun. That is why `constructEvent` is async — a conscious deviation from
+// Stripe's synchronous `constructEvent`.
+/**
+ * Every event type this SDK version knows. Mirrors the server's
+ * `WebhookEventType` (`src/features/sellers/webhooks.ts`) — the drift alarm is
+ * `src/features/sellers/webhook-signature-contract.test.ts`, which fails when
+ * the server grows a type this list does not have.
+ *
+ * Exported as a runtime array (not only as a type) so a handler can ask
+ * `isKnownPeerPayEventType(event.type)` before it decides what to do.
+ */
+export const PEERPAY_EVENT_TYPES = [
+    "payment.confirmed",
+    "link.paid",
+    "agent_payment.pending_approval",
+    "agent_payment.settled",
+    "mandate.active",
+    "mandate.charged",
+    "mandate.charge_failed",
+    "mandate.revoked",
+    "subscription.renewed",
+    "subscription.past_due",
+];
+/** True when `type` is an event type this SDK version knows about. */
+export function isKnownPeerPayEventType(type) {
+    return PEERPAY_EVENT_TYPES.includes(type);
+}
+/**
+ * Thrown for every rejection path: malformed/missing header, missing `t`/`v1`,
+ * timestamp outside the tolerance window, signature mismatch, non-JSON body.
+ * Messages never contain the secret or the expected signature.
+ */
+export class PeerPaySignatureVerificationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "PeerPaySignatureVerificationError";
+    }
+}
+const DEFAULT_TOLERANCE_SECONDS = 300;
+const SIGNATURE_HEADER_NAME = "PEERPAY-SIGNATURE";
+const textEncoder = new TextEncoder();
+const textDecoder = new TextDecoder("utf-8", { fatal: false });
+/**
+ * Parses `t=…,v1=…` tolerantly: any order, surrounding whitespace, and
+ * repeated `v1=` values (secret rotation — one match is enough).
+ */
+function parseSignatureHeader(header) {
+    let timestampRaw;
+    const signatures = [];
+    for (const rawPart of header.split(",")) {
+        const part = rawPart.trim();
+        if (part.length === 0)
+            continue;
+        const separator = part.indexOf("=");
+        if (separator <= 0) {
+            throw new PeerPaySignatureVerificationError(`Malformed ${SIGNATURE_HEADER_NAME} header: expected comma-separated key=value pairs.`);
+        }
+        const key = part.slice(0, separator).trim();
+        const value = part.slice(separator + 1).trim();
+        if (key === "t") {
+            // A second `t=` would make the signed payload ambiguous.
+            if (timestampRaw !== undefined) {
+                throw new PeerPaySignatureVerificationError(`Malformed ${SIGNATURE_HEADER_NAME} header: duplicate "t" value.`);
+            }
+            timestampRaw = value;
+        }
+        else if (key === "v1") {
+            if (value.length > 0)
+                signatures.push(value);
+        }
+        // Unknown keys (future scheme versions) are ignored on purpose.
+    }
+    if (timestampRaw === undefined || timestampRaw.length === 0) {
+        throw new PeerPaySignatureVerificationError(`Missing "t" in ${SIGNATURE_HEADER_NAME} header.`);
+    }
+    if (!/^\d+$/.test(timestampRaw)) {
+        throw new PeerPaySignatureVerificationError(`Invalid "t" in ${SIGNATURE_HEADER_NAME} header: expected unix seconds.`);
+    }
+    const timestampSeconds = Number(timestampRaw);
+    if (!Number.isSafeInteger(timestampSeconds)) {
+        throw new PeerPaySignatureVerificationError(`Invalid "t" in ${SIGNATURE_HEADER_NAME} header: expected unix seconds.`);
+    }
+    if (signatures.length === 0) {
+        throw new PeerPaySignatureVerificationError(`Missing "v1" in ${SIGNATURE_HEADER_NAME} header.`);
+    }
+    return { timestampSeconds, signatures };
+}
+function getSubtleCrypto() {
+    const subtle = globalThis.crypto?.subtle;
+    if (!subtle) {
+        throw new PeerPaySignatureVerificationError("WebCrypto (globalThis.crypto.subtle) is unavailable in this runtime; webhook verification requires it.");
+    }
+    return subtle;
+}
+async function computeExpectedSignature(secret, signedPayload) {
+    const subtle = getSubtleCrypto();
+    const key = await subtle.importKey("raw", textEncoder.encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+    const signature = await subtle.sign("HMAC", key, textEncoder.encode(signedPayload));
+    return toHex(new Uint8Array(signature));
+}
+function toHex(bytes) {
+    let hex = "";
+    for (const byte of bytes) {
+        hex += byte.toString(16).padStart(2, "0");
+    }
+    return hex;
+}
+/**
+ * Constant-time string comparison. Length is checked first (lengths are not
+ * secret), then every byte is folded into an XOR accumulator — no early return
+ * and no `===` on the hex strings, so timing does not leak the position of the
+ * first differing byte.
+ */
+function timingSafeEqualStrings(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < a.length; i += 1) {
+        diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+    }
+    return diff === 0;
+}
+function decodeRawBody(rawBody) {
+    if (typeof rawBody === "string")
+        return rawBody;
+    return textDecoder.decode(rawBody);
+}
+/**
+ * Verifies a GenesisPay webhook delivery and returns the parsed event.
+ *
+ * Pass the **raw** request body exactly as received — never a re-serialized
+ * `JSON.parse` + `JSON.stringify` round trip, which changes the bytes and
+ * invalidates the signature. Parsing happens only after verification succeeds.
+ *
+ * An event type this SDK version does not know is **not** a failure: the
+ * delivery is verified and returned unchanged, so a server that adds a new
+ * event type can never turn a customer's webhook route into a 400. Only the
+ * signature and the envelope (`id`, `type`, `createdAt`, object `data`) can
+ * reject a delivery. Widen to `PeerPayAnyEvent` and use
+ * `isKnownPeerPayEventType()` if you want to handle that case explicitly.
+ *
+ * @throws {PeerPaySignatureVerificationError} on any verification failure.
+ *
+ * @example
+ * ```ts
+ * const event = await constructEvent(
+ *   await request.text(),
+ *   request.headers.get("peerpay-signature") ?? "",
+ *   process.env.PEERPAY_WEBHOOK_SECRET!,
+ * );
+ * if (event.type === "payment.confirmed") {
+ *   fulfil(event.data.link.clientReferenceId, event.data.attempt.txHash);
+ * }
+ * ```
+ */
+export async function constructEvent(rawBody, signatureHeader, secret, opts = {}) {
+    if (typeof signatureHeader !== "string" || signatureHeader.trim().length === 0) {
+        throw new PeerPaySignatureVerificationError(`Missing ${SIGNATURE_HEADER_NAME} header.`);
+    }
+    if (typeof secret !== "string" || secret.length === 0) {
+        throw new PeerPaySignatureVerificationError("Missing webhook signing secret.");
+    }
+    const toleranceSeconds = opts.toleranceSeconds ?? DEFAULT_TOLERANCE_SECONDS;
+    if (!Number.isFinite(toleranceSeconds) || toleranceSeconds < 0) {
+        throw new PeerPaySignatureVerificationError("Invalid toleranceSeconds: expected a non-negative number.");
+    }
+    const { timestampSeconds, signatures } = parseSignatureHeader(signatureHeader);
+    const nowMs = opts.nowMs ?? Date.now();
+    const nowSeconds = Math.floor(nowMs / 1_000);
+    const skewSeconds = Math.abs(nowSeconds - timestampSeconds);
+    if (skewSeconds > toleranceSeconds) {
+        // Rejects future timestamps too — a clock-skewed or replayed delivery.
+        throw new PeerPaySignatureVerificationError(`Webhook timestamp is outside the tolerance window of ${toleranceSeconds}s (off by ${skewSeconds}s).`);
+    }
+    const body = decodeRawBody(rawBody);
+    const expected = await computeExpectedSignature(secret, `${timestampSeconds}.${body}`);
+    let matched = false;
+    for (const candidate of signatures) {
+        // No early break: every candidate is compared so the work does not depend
+        // on which one matches.
+        matched = timingSafeEqualStrings(expected, candidate.toLowerCase()) || matched;
+    }
+    if (!matched) {
+        throw new PeerPaySignatureVerificationError("Webhook signature mismatch: the payload does not match the signing secret.");
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(body);
+    }
+    catch {
+        throw new PeerPaySignatureVerificationError("Webhook body is not valid JSON.");
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new PeerPaySignatureVerificationError("Webhook body is not a JSON object.");
+    }
+    // The envelope is asserted rather than cast. `id` in particular is the
+    // documented idempotency key — it is stable across delivery retries, so an
+    // integrator deduping on it would silently process a payment twice if it
+    // arrived as undefined. A signed body that does not carry the envelope means
+    // the sender is not the GenesisPay we know, so failing here is correct.
+    const envelope = parsed;
+    for (const field of ["id", "type", "createdAt"]) {
+        if (typeof envelope[field] !== "string" || envelope[field] === "") {
+            throw new PeerPaySignatureVerificationError(`Webhook body is missing a string "${field}" field.`);
+        }
+    }
+    if (typeof envelope.data !== "object" ||
+        envelope.data === null ||
+        Array.isArray(envelope.data)) {
+        throw new PeerPaySignatureVerificationError('Webhook body is missing an object "data" field.');
+    }
+    return parsed;
+}
+//# sourceMappingURL=webhooks.js.map

package/dist/webhooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhooks.js","sourceRoot":"","sources":["../src/webhooks.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@genesis-tech/genesispay-seller",
+  "version": "0.8.0",
+  "description": "Framework-agnostic x402 payment gate for sellers, powered by GenesisPay.",
+  "license": "MIT",
+  "author": "GenesisTech",
+  "homepage": "https://github.com/GenesisTechAT/genesispay-js/tree/main/packages/seller-sdk#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/GenesisTechAT/genesispay-js.git",
+    "directory": "packages/seller-sdk"
+  },
+  "bugs": {
+    "url": "https://github.com/GenesisTechAT/genesispay-js/issues"
+  },
+  "keywords": [
+    "x402",
+    "http-402",
+    "payments",
+    "usdc",
+    "stablecoin",
+    "base",
+    "paywall",
+    "api-monetization",
+    "payment-gate"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20.9.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.test.*",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@genesis-tech/genesispay-protocol": "^0.1.0",
+    "viem": "^2.48.11"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  }
+}