@genesis-tech/genesispay-seller 0.8.0

package/dist/payment-gate.js

@@ -0,0 +1,106 @@
+import { PAYMENT_REQUIRED_HEADER, PAYMENT_RESPONSE_HEADER, PAYMENT_SIGNATURE_HEADER, buildPaymentRequiredPayload, decodePaymentSignatureHeader, encodePaymentRequiredHeader, encodeSettlementResponseHeader, validatePaymentSignatureAgainstRequirement, } from "@genesis-tech/genesispay-protocol";
+import { getAddress, isAddress } from "viem";
+import { resolvePaymentGateNetwork } from "./networks.js";
+import { parseUsdcAmountToMinorUnits } from "./usdc-amount.js";
+export function createPaymentGate(config) {
+    const network = resolvePaymentGateNetwork(config.network ?? "base-sepolia");
+    const amountUsdcMinor = parseUsdcAmountToMinorUnits(config.amountUsdc);
+    const payTo = normalizePayToAddress(config.payTo);
+    const description = config.description ?? "Payment required";
+    function buildPayload(resource) {
+        return buildPaymentRequiredPayload({
+            amount: config.amountUsdc.trim(),
+            amountUsdcMinor,
+            asset: "USDC",
+            assetAddress: network.usdcAddress,
+            chainId: network.chainId,
+            network: network.network,
+            destination: payTo,
+            description,
+            resource,
+            mimeType: config.mimeType,
+            maxTimeoutSeconds: config.maxTimeoutSeconds,
+            extra: config.eip712Domain,
+        });
+    }
+    function resolveResource(request) {
+        if (config.resource) {
+            return config.resource;
+        }
+        const url = new URL(request.url);
+        return `${url.origin}${url.pathname}`;
+    }
+    return {
+        requirementFor(resource) {
+            return buildPayload(resource).accepts[0];
+        },
+        wrap(handler, options) {
+            if (typeof options?.verifySettlement !== "function") {
+                throw new Error("gate.wrap requires a verifySettlement hook — use peerPaySettlement({ facilitatorBaseUrl, apiKey }) or provide your own.");
+            }
+            return async (request, ...args) => {
+                const payload = buildPayload(resolveResource(request));
+                const paymentSignatureHeader = request.headers.get(PAYMENT_SIGNATURE_HEADER);
+                if (!paymentSignatureHeader?.trim()) {
+                    return paymentRequiredResponse(payload);
+                }
+                let payment;
+                try {
+                    payment = decodePaymentSignatureHeader(paymentSignatureHeader);
+                }
+                catch (error) {
+                    return paymentRequiredResponse(payload, describeError(error));
+                }
+                const requirement = payload.accepts[0];
+                const mismatch = validatePaymentSignatureAgainstRequirement(payment, requirement);
+                if (mismatch) {
+                    return paymentRequiredResponse(payload, mismatch);
+                }
+                const verification = await options.verifySettlement({
+                    request,
+                    paymentSignatureHeader,
+                    payment,
+                    requirement,
+                });
+                if (!verification.ok) {
+                    return paymentRequiredResponse(payload, verification.errorReason, verification.settlement);
+                }
+                const response = await handler(request, ...args);
+                return withSettlementHeader(response, verification.settlement);
+            };
+        },
+    };
+}
+function paymentRequiredResponse(payload, errorReason, settlement) {
+    const body = errorReason
+        ? { ...payload, error: errorReason }
+        : payload;
+    const headers = new Headers({
+        "Content-Type": "application/json",
+        "Cache-Control": "no-store",
+        [PAYMENT_REQUIRED_HEADER]: encodePaymentRequiredHeader(body),
+    });
+    if (settlement) {
+        headers.set(PAYMENT_RESPONSE_HEADER, encodeSettlementResponseHeader(settlement));
+    }
+    return new Response(JSON.stringify(body), { status: 402, headers });
+}
+function withSettlementHeader(response, settlement) {
+    const headers = new Headers(response.headers);
+    headers.set(PAYMENT_RESPONSE_HEADER, encodeSettlementResponseHeader(settlement));
+    return new Response(response.body, {
+        status: response.status,
+        statusText: response.statusText,
+        headers,
+    });
+}
+function normalizePayToAddress(payTo) {
+    if (typeof payTo !== "string" || !isAddress(payTo.trim())) {
+        throw new Error(`Invalid payTo address "${String(payTo)}": expected an EVM address like 0x1234....`);
+    }
+    return getAddress(payTo.trim());
+}
+function describeError(error) {
+    return error instanceof Error ? error.message : "Malformed PAYMENT-SIGNATURE header.";
+}
+//# sourceMappingURL=payment-gate.js.map

package/dist/payment-gate.js.map

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

package/dist/peerpay-settlement.d.ts

@@ -0,0 +1,27 @@
+import type { VerifySettlement } from "./payment-gate.js";
+/**
+ * Default GenesisPay app base URL — the public "development" facilitator. Used
+ * when `facilitatorBaseUrl` is omitted so integrators don't have to configure a
+ * URL in dev. Set `facilitatorBaseUrl` explicitly for production.
+ */
+export declare const DEFAULT_FACILITATOR_BASE_URL = "https://peerpay-app-development.up.railway.app";
+export type PeerPaySettlementOptions = {
+    /**
+     * Base URL of the GenesisPay app, e.g. "https://genesispay.example". Defaults to
+     * the public development facilitator (DEFAULT_FACILITATOR_BASE_URL) when
+     * omitted; set it explicitly in production.
+     */
+    facilitatorBaseUrl?: string;
+    /** GenesisPay seller API key ("pp_sk_..."). */
+    apiKey: string;
+    /** Override for testing; defaults to global fetch. */
+    fetchFn?: typeof fetch;
+};
+/**
+ * Built-in settlement hook that forwards the PAYMENT-SIGNATURE payload to the
+ * GenesisPay facilitator (`POST /api/v1/facilitator/settle`). GenesisPay broadcasts
+ * the EIP-3009 authorization on-chain (or verifies a payer-provided txHash)
+ * and verifies the USDC transfer before reporting success.
+ */
+export declare function peerPaySettlement(options: PeerPaySettlementOptions): VerifySettlement;
+//# sourceMappingURL=peerpay-settlement.d.ts.map

package/dist/peerpay-settlement.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"peerpay-settlement.d.ts","sourceRoot":"","sources":["../src/peerpay-settlement.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAGV,gBAAgB,EACjB,MAAM,mBAAmB,CAAC;AAE3B;;;;GAIG;AACH,eAAO,MAAM,4BAA4B,mDACS,CAAC;AAEnD,MAAM,MAAM,wBAAwB,GAAG;IACrC;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,+CAA+C;IAC/C,MAAM,EAAE,MAAM,CAAC;IACf,sDAAsD;IACtD,OAAO,CAAC,EAAE,OAAO,KAAK,CAAC;CACxB,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,wBAAwB,GAChC,gBAAgB,CA6DlB"}

package/dist/peerpay-settlement.js

@@ -0,0 +1,100 @@
+import { parseSettlementResponsePayload } from "@genesis-tech/genesispay-protocol";
+/**
+ * Default GenesisPay app base URL — the public "development" facilitator. Used
+ * when `facilitatorBaseUrl` is omitted so integrators don't have to configure a
+ * URL in dev. Set `facilitatorBaseUrl` explicitly for production.
+ */
+export const DEFAULT_FACILITATOR_BASE_URL = "https://peerpay-app-development.up.railway.app";
+/**
+ * Built-in settlement hook that forwards the PAYMENT-SIGNATURE payload to the
+ * GenesisPay facilitator (`POST /api/v1/facilitator/settle`). GenesisPay broadcasts
+ * the EIP-3009 authorization on-chain (or verifies a payer-provided txHash)
+ * and verifies the USDC transfer before reporting success.
+ */
+export function peerPaySettlement(options) {
+    const settleUrl = buildSettleUrl(options.facilitatorBaseUrl?.trim() || DEFAULT_FACILITATOR_BASE_URL);
+    const apiKey = options.apiKey?.trim();
+    if (!apiKey) {
+        throw new Error("peerPaySettlement requires a GenesisPay seller API key (pp_sk_...).");
+    }
+    const fetchFn = options.fetchFn ?? fetch;
+    return async (context) => {
+        const { requirement } = context;
+        let response;
+        try {
+            response = await fetchFn(settleUrl, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    Authorization: `Bearer ${apiKey}`,
+                },
+                body: JSON.stringify({
+                    paymentSignature: context.paymentSignatureHeader,
+                    requirement: {
+                        resource: requirement.resource,
+                        network: requirement.network,
+                        chainId: requirement.chainId,
+                        assetAddress: requirement.assetAddress,
+                        amountUsdcMinor: requirement.maxAmountRequired,
+                        payTo: requirement.payTo,
+                        description: requirement.description || undefined,
+                    },
+                }),
+            });
+        }
+        catch (error) {
+            return {
+                ok: false,
+                errorReason: `Failed to reach the GenesisPay facilitator: ${describeError(error)}`,
+            };
+        }
+        const body = await readJsonBody(response);
+        const settlement = tryParseSettlement(body);
+        if (response.ok && settlement?.success) {
+            return { ok: true, settlement };
+        }
+        return {
+            ok: false,
+            errorReason: settlement?.errorReason ??
+                readErrorMessage(body) ??
+                `GenesisPay facilitator settlement failed with status ${response.status}.`,
+            ...(settlement ? { settlement } : {}),
+        };
+    };
+}
+function buildSettleUrl(facilitatorBaseUrl) {
+    const trimmed = facilitatorBaseUrl?.trim().replace(/\/+$/, "");
+    if (!trimmed || !/^https?:\/\//.test(trimmed)) {
+        throw new Error(`Invalid facilitatorBaseUrl "${String(facilitatorBaseUrl)}": expected an http(s) URL like "https://genesispay.example".`);
+    }
+    return `${trimmed}/api/v1/facilitator/settle`;
+}
+async function readJsonBody(response) {
+    try {
+        return await response.json();
+    }
+    catch {
+        return undefined;
+    }
+}
+function tryParseSettlement(body) {
+    try {
+        return parseSettlementResponsePayload(body);
+    }
+    catch {
+        return undefined;
+    }
+}
+function readErrorMessage(body) {
+    if (typeof body === "object" &&
+        body !== null &&
+        "error" in body &&
+        typeof body.error === "string") {
+        return body.error;
+    }
+    return undefined;
+}
+function describeError(error) {
+    return error instanceof Error ? error.message : "unknown error";
+}
+//# sourceMappingURL=peerpay-settlement.js.map

package/dist/peerpay-settlement.js.map

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

package/dist/plans.d.ts

@@ -0,0 +1,68 @@
+import { type PeerPayRequest } from "./resource.js";
+export type SubscriptionPlanStatus = "active" | "archived";
+export type SubscriptionPlan = {
+    /** Internal id. Address a plan by `publicId` — that is what the routes take. */
+    id: string;
+    publicId: string;
+    title: string;
+    description: string | null;
+    asset: "USDC" | "EURC";
+    /** Decimal amount charged per period, e.g. "9.00". */
+    amountPerPeriod: string;
+    /** Same amount in 6-decimal minor units, as a string (no precision loss). */
+    amountPerPeriodMinor: string;
+    periodDays: number;
+    /**
+     * How many periods of allowance the customer approves up front. The mandate's
+     * total allowance is `amountPerPeriodMinor * prepaidCycles`; when it runs out
+     * the customer signs again.
+     */
+    prepaidCycles: number;
+    capPerChargeMinor: string;
+    allowanceMinor: string;
+    destinationWallet: string;
+    chainId: number;
+    status: SubscriptionPlanStatus;
+    /**
+     * The hosted subscribe flow (`/subscribe/:publicId`) — send the customer
+     * here. This is the whole reason to call the API rather than build the URL
+     * yourself: the host depends on the deployment the key points at.
+     */
+    checkoutUrl: string;
+    createdAt: string;
+    archivedAt: string | null;
+};
+export type PlanCreateInput = {
+    title: string;
+    /** Decimal amount per period, e.g. "9" or "9.00". */
+    amountPerPeriod: string;
+    /** Billing period in whole days, e.g. 30. */
+    periodDays: number;
+    description?: string;
+    /** Periods of allowance collected in one signature. Server default applies. */
+    prepaidCycles?: number;
+    /** Defaults to the account's receiving wallet. */
+    destinationWallet?: string;
+    /** Defaults to USDC. */
+    asset?: "USDC" | "EURC";
+};
+export interface PlansResource {
+    create(input: PlanCreateInput): Promise<SubscriptionPlan>;
+    list(): Promise<SubscriptionPlan[]>;
+    retrieve(publicId: string): Promise<SubscriptionPlan>;
+    /**
+     * Stops the hosted page from taking new subscribers. Mandates already signed
+     * from this plan keep billing until the payer revokes them — archiving is not
+     * a cancellation. Archiving twice is a no-op that returns the same plan.
+     */
+    archive(publicId: string): Promise<SubscriptionPlan>;
+}
+export declare function createPlansResource(request: PeerPayRequest, 
+/**
+ * Applies the client's `expectedPayTo` pin to the wallet the server froze
+ * onto the plan. A plan's destination is where every future renewal settles,
+ * so it is exactly the value the pin exists to guard.
+ */
+assertPinnedDestination?: (wallet: unknown, what: string) => void): PlansResource;
+export declare function toSubscriptionPlan(raw: Record<string, unknown>): SubscriptionPlan;
+//# sourceMappingURL=plans.d.ts.map

package/dist/plans.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plans.d.ts","sourceRoot":"","sources":["../src/plans.ts"],"names":[],"mappings":"AASA,OAAO,EAOL,KAAK,cAAc,EACpB,MAAM,eAAe,CAAC;AAEvB,MAAM,MAAM,sBAAsB,GAAG,QAAQ,GAAG,UAAU,CAAC;AAE3D,MAAM,MAAM,gBAAgB,GAAG;IAC7B,gFAAgF;IAChF,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;IACvB,sDAAsD;IACtD,eAAe,EAAE,MAAM,CAAC;IACxB,6EAA6E;IAC7E,oBAAoB,EAAE,MAAM,CAAC;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,aAAa,EAAE,MAAM,CAAC;IACtB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,cAAc,EAAE,MAAM,CAAC;IACvB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,sBAAsB,CAAC;IAC/B;;;;OAIG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,qDAAqD;IACrD,eAAe,EAAE,MAAM,CAAC;IACxB,6CAA6C;IAC7C,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,+EAA+E;IAC/E,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,kDAAkD;IAClD,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,wBAAwB;IACxB,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CACzB,CAAC;AAEF,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAC1D,IAAI,IAAI,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAAC;IACpC,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;IACtD;;;;OAIG;IACH,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;CACtD;AAED,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,cAAc;AACvB;;;;GAIG;AACH,uBAAuB,GAAE,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,KAAK,IAAe,GAC1E,aAAa,CAwEf;AA6BD,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,gBAAgB,CAwBjF"}

package/dist/plans.js

@@ -0,0 +1,127 @@
+// `peerpay.plans.*` — subscription plans over `/api/v1/plans`.
+//
+// A plan is the recurring sibling of a checkout link: it describes an amount
+// per period and exposes a hosted `checkoutUrl` the customer signs a mandate
+// on. Everything is scoped to the key's own account, so a plan owned by someone
+// else answers 404 (PeerPayNotFoundError) rather than 403 — the API is no
+// plan-enumeration oracle, and the SDK does not paper over that.
+import { PeerPayConfigError } from "./errors.js";
+import { asRecord, optionalString, requiredString, toAmountString, toCount, oneOf, } from "./resource.js";
+export function createPlansResource(request, 
+/**
+ * Applies the client's `expectedPayTo` pin to the wallet the server froze
+ * onto the plan. A plan's destination is where every future renewal settles,
+ * so it is exactly the value the pin exists to guard.
+ */
+assertPinnedDestination = () => { }) {
+    return {
+        create: async (input) => {
+            const body = await request({
+                method: "POST",
+                path: "/api/v1/plans",
+                operation: "POST /api/v1/plans",
+                action: "create a subscription plan",
+                body: {
+                    title: input.title,
+                    amountPerPeriod: input.amountPerPeriod,
+                    periodDays: input.periodDays,
+                    ...(input.description ? { description: input.description } : {}),
+                    ...(input.prepaidCycles === undefined
+                        ? {}
+                        : { prepaidCycles: input.prepaidCycles }),
+                    ...(input.destinationWallet
+                        ? { destinationWallet: input.destinationWallet }
+                        : {}),
+                    ...(input.asset ? { asset: input.asset } : {}),
+                },
+            });
+            const plan = requirePlan(body, "POST /api/v1/plans");
+            assertPinnedDestination(plan.destinationWallet, "subscription plan");
+            return plan;
+        },
+        list: async () => {
+            const body = await request({
+                path: "/api/v1/plans",
+                operation: "GET /api/v1/plans",
+                action: "list subscription plans",
+            });
+            const plans = asRecord(body)?.plans;
+            if (!Array.isArray(plans)) {
+                // A list endpoint that answers 200 without a list is a broken contract,
+                // not an old backend. Returning [] here would hide it as "no plans yet".
+                throw new PeerPayConfigError(`GenesisPay GET /api/v1/plans returned no plans array: ${JSON.stringify(body)}`);
+            }
+            // Individual entries stay tolerant: one unusable row must not lose the rest.
+            return plans
+                .map(asRecord)
+                .filter((raw) => raw !== null)
+                .filter((raw) => typeof raw.publicId === "string" && raw.publicId.length > 0)
+                .map(toSubscriptionPlan);
+        },
+        retrieve: async (publicId) => {
+            const id = requirePublicId(publicId, "plans.retrieve");
+            const body = await request({
+                path: `/api/v1/plans/${encodeURIComponent(id)}`,
+                operation: `GET /api/v1/plans/${id}`,
+                action: `retrieve subscription plan "${id}"`,
+                notFoundMessage: notFoundMessage(id),
+            });
+            return requirePlan(body, `GET /api/v1/plans/${id}`);
+        },
+        archive: async (publicId) => {
+            const id = requirePublicId(publicId, "plans.archive");
+            const body = await request({
+                method: "POST",
+                path: `/api/v1/plans/${encodeURIComponent(id)}/archive`,
+                operation: `POST /api/v1/plans/${id}/archive`,
+                action: `archive subscription plan "${id}"`,
+                notFoundMessage: notFoundMessage(id),
+            });
+            return requirePlan(body, `POST /api/v1/plans/${id}/archive`);
+        },
+    };
+}
+function notFoundMessage(id) {
+    return (`No GenesisPay subscription plan with publicId "${id}". Check the id and that ` +
+        `it belongs to the account this API key authenticates.`);
+}
+function requirePublicId(publicId, method) {
+    const id = publicId?.trim();
+    if (!id) {
+        throw new PeerPayConfigError(`${method}(publicId) requires the publicId returned by plans.create().`);
+    }
+    return id;
+}
+function requirePlan(body, operation) {
+    const raw = asRecord(asRecord(body)?.plan);
+    if (!raw || typeof raw.publicId !== "string" || !raw.publicId) {
+        throw new PeerPayConfigError(`GenesisPay ${operation} returned no plan: ${JSON.stringify(body)}`);
+    }
+    return toSubscriptionPlan(raw);
+}
+export function toSubscriptionPlan(raw) {
+    return {
+        id: requiredString(raw.id),
+        publicId: requiredString(raw.publicId),
+        title: requiredString(raw.title),
+        description: optionalString(raw.description),
+        asset: oneOf(raw.asset, ["USDC", "EURC"], "USDC"),
+        amountPerPeriod: toAmountString(raw.amountPerPeriod),
+        amountPerPeriodMinor: toAmountString(raw.amountPerPeriodMinor),
+        periodDays: toCount(raw.periodDays),
+        prepaidCycles: toCount(raw.prepaidCycles),
+        capPerChargeMinor: toAmountString(raw.capPerChargeMinor),
+        allowanceMinor: toAmountString(raw.allowanceMinor),
+        destinationWallet: requiredString(raw.destinationWallet),
+        chainId: toCount(raw.chainId),
+        // Degrade to "archived", not "active": a status this SDK version does not
+        // know (a future "paused", "deleted", …) must not read as "keep sending
+        // customers to this checkoutUrl". Mirrors mandate status degrading to the
+        // inert `pending_permit`.
+        status: oneOf(raw.status, ["active", "archived"], "archived"),
+        checkoutUrl: requiredString(raw.checkoutUrl),
+        createdAt: requiredString(raw.createdAt),
+        archivedAt: optionalString(raw.archivedAt),
+    };
+}
+//# sourceMappingURL=plans.js.map

package/dist/plans.js.map

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

package/dist/resource.d.ts

@@ -0,0 +1,47 @@
+export type PeerPayRequestOptions = {
+    /** Defaults to GET. */
+    method?: "GET" | "POST" | "PATCH";
+    /** Path starting with "/", already percent-encoded. */
+    path: string;
+    /** JSON request body. Omit entirely for a GET (no content-type is sent). */
+    body?: unknown;
+    /** Additional non-secret request headers, e.g. Idempotency-Key. */
+    headers?: Record<string, string>;
+    /** Label used in error messages, e.g. `POST /api/v1/plans`. */
+    operation: string;
+    /** Replaces the generic 404 text — a 404 usually needs case-specific wording. */
+    notFoundMessage?: string;
+    /**
+     * Next step for the caller, appended to the message. A function receives the
+     * HTTP status so one call site can give, say, a 403 its own guidance without
+     * hand-rolling an error class next to the shared mapper.
+     */
+    hint?: string | ((status: number) => string | undefined);
+    /**
+     * Filled into "Failed to reach GenesisPay to <action>" when the transport itself
+     * fails (DNS, connection refused, abort) — there is no response to map then.
+     */
+    action: string;
+};
+/** The client's bound request function, as a resource module sees it. */
+export type PeerPayRequest = (options: PeerPayRequestOptions) => Promise<unknown>;
+/** A non-null, non-array object, or null — the shape a mapper can read fields off. */
+export declare function asRecord(value: unknown): Record<string, unknown> | null;
+export declare function optionalString(value: unknown): string | null;
+export declare function requiredString(value: unknown): string;
+/** Flat `Record<string, string>`; anything else (array, nested object) → null. */
+export declare function optionalMetadata(value: unknown): Record<string, string> | null;
+export declare function oneOf<T extends string>(value: unknown, allowed: readonly T[], fallback: T): T;
+export declare function toCount(value: unknown): number;
+/** Like `toCount`, but a missing/unusable value stays `null` rather than 0. */
+export declare function optionalCount(value: unknown): number | null;
+/**
+ * Money crosses the wire as a decimal or minor-unit *string* so no precision is
+ * lost. A number is accepted and stringified anyway (a hand-rolled proxy or an
+ * older serializer may send one); anything else becomes "" rather than a
+ * plausible-looking wrong amount.
+ */
+export declare function toAmountString(value: unknown): string;
+/** Same as `toAmountString`, but keeps "not set" distinguishable from "zero". */
+export declare function optionalAmountString(value: unknown): string | null;
+//# sourceMappingURL=resource.d.ts.map

package/dist/resource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource.d.ts","sourceRoot":"","sources":["../src/resource.ts"],"names":[],"mappings":"AAeA,MAAM,MAAM,qBAAqB,GAAG;IAClC,uBAAuB;IACvB,MAAM,CAAC,EAAE,KAAK,GAAG,MAAM,GAAG,OAAO,CAAC;IAClC,uDAAuD;IACvD,IAAI,EAAE,MAAM,CAAC;IACb,4EAA4E;IAC5E,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,mEAAmE;IACnE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,+DAA+D;IAC/D,SAAS,EAAE,MAAM,CAAC;IAClB,iFAAiF;IACjF,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,MAAM,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC,CAAC;IACzD;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,yEAAyE;AACzE,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,EAAE,qBAAqB,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;AAElF,sFAAsF;AACtF,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAGvE;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAE5D;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAErD;AAED,kFAAkF;AAClF,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAM9E;AAED,wBAAgB,KAAK,CAAC,CAAC,SAAS,MAAM,EACpC,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,SAAS,CAAC,EAAE,EACrB,QAAQ,EAAE,CAAC,GACV,CAAC,CAIH;AAED,wBAAgB,OAAO,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAG9C;AAED,+EAA+E;AAC/E,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAI3D;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAIrD;AAED,iFAAiF;AACjF,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAIlE"}

package/dist/resource.js

@@ -0,0 +1,71 @@
+// What every GenesisPay resource module (checkout, plans, mandates) is built on:
+// one HTTP seam and one set of tolerant wire mappers.
+//
+// The seam exists so a resource module never touches `fetch`, the API key or
+// the base URL — the client owns those and hands down a bound `PeerPayRequest`.
+// That keeps the error mapping in exactly one place (`throwForErrorResponse`,
+// see ./errors.ts): a resource that built its own request could quietly grow a
+// second, divergent notion of what a 422 means.
+//
+// The mappers are deliberately forgiving. Every field arrives as `unknown`
+// because an older backend — one that predates a column this SDK version knows
+// about — must never be able to crash a caller's poll loop or webhook handler.
+// Missing or wrong-typed values degrade to null/0/"" or a named default; they
+// never throw.
+/** A non-null, non-array object, or null — the shape a mapper can read fields off. */
+export function asRecord(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return null;
+    return value;
+}
+export function optionalString(value) {
+    return typeof value === "string" && value.length > 0 ? value : null;
+}
+export function requiredString(value) {
+    return typeof value === "string" ? value : "";
+}
+/** Flat `Record<string, string>`; anything else (array, nested object) → null. */
+export function optionalMetadata(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return null;
+    const entries = Object.entries(value).filter((entry) => typeof entry[1] === "string");
+    return entries.length > 0 ? Object.fromEntries(entries) : null;
+}
+export function oneOf(value, allowed, fallback) {
+    return typeof value === "string" && allowed.includes(value)
+        ? value
+        : fallback;
+}
+export function toCount(value) {
+    const parsed = typeof value === "number" ? value : Number(value);
+    return Number.isFinite(parsed) ? parsed : 0;
+}
+/** Like `toCount`, but a missing/unusable value stays `null` rather than 0. */
+export function optionalCount(value) {
+    if (value === null || value === undefined || value === "")
+        return null;
+    const parsed = typeof value === "number" ? value : Number(value);
+    return Number.isFinite(parsed) ? parsed : null;
+}
+/**
+ * Money crosses the wire as a decimal or minor-unit *string* so no precision is
+ * lost. A number is accepted and stringified anyway (a hand-rolled proxy or an
+ * older serializer may send one); anything else becomes "" rather than a
+ * plausible-looking wrong amount.
+ */
+export function toAmountString(value) {
+    if (typeof value === "string")
+        return value;
+    if (typeof value === "number" && Number.isFinite(value))
+        return String(value);
+    return "";
+}
+/** Same as `toAmountString`, but keeps "not set" distinguishable from "zero". */
+export function optionalAmountString(value) {
+    if (typeof value === "string")
+        return value.length > 0 ? value : null;
+    if (typeof value === "number" && Number.isFinite(value))
+        return String(value);
+    return null;
+}
+//# sourceMappingURL=resource.js.map

package/dist/resource.js.map

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

package/dist/usdc-amount.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Parses a human-readable decimal USDC amount ("0.10") into integer minor
+ * units (6 decimals) as a bigint. Rejects anything that is not a positive
+ * amount with at most 6 decimal places.
+ */
+export declare function parseUsdcAmountToMinorUnits(amount: string): bigint;
+//# sourceMappingURL=usdc-amount.d.ts.map

package/dist/usdc-amount.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usdc-amount.d.ts","sourceRoot":"","sources":["../src/usdc-amount.ts"],"names":[],"mappings":"AAGA;;;;GAIG;AACH,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAmBlE"}

package/dist/usdc-amount.js

@@ -0,0 +1,21 @@
+const USDC_DECIMALS = 6;
+const USDC_AMOUNT_PATTERN = /^\d+(?:\.\d{1,6})?$/;
+/**
+ * Parses a human-readable decimal USDC amount ("0.10") into integer minor
+ * units (6 decimals) as a bigint. Rejects anything that is not a positive
+ * amount with at most 6 decimal places.
+ */
+export function parseUsdcAmountToMinorUnits(amount) {
+    const normalizedAmount = amount.trim();
+    if (!USDC_AMOUNT_PATTERN.test(normalizedAmount)) {
+        throw new Error(`Invalid USDC amount "${amount}": use a positive decimal with up to 6 decimals, e.g. "0.10".`);
+    }
+    const [wholePart, fractionalPart = ""] = normalizedAmount.split(".");
+    const minorUnits = BigInt(wholePart) * BigInt(10 ** USDC_DECIMALS) +
+        BigInt(fractionalPart.padEnd(USDC_DECIMALS, "0"));
+    if (minorUnits <= 0n) {
+        throw new Error("USDC amount must be greater than zero.");
+    }
+    return minorUnits;
+}
+//# sourceMappingURL=usdc-amount.js.map

package/dist/usdc-amount.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usdc-amount.js","sourceRoot":"","sources":["../src/usdc-amount.ts"],"names":[],"mappings":"AAAA,MAAM,aAAa,GAAG,CAAC,CAAC;AACxB,MAAM,mBAAmB,GAAG,qBAAqB,CAAC;AAElD;;;;GAIG;AACH,MAAM,UAAU,2BAA2B,CAAC,MAAc;IACxD,MAAM,gBAAgB,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC;IAEvC,IAAI,CAAC,mBAAmB,CAAC,IAAI,CAAC,gBAAgB,CAAC,EAAE,CAAC;QAChD,MAAM,IAAI,KAAK,CACb,wBAAwB,MAAM,+DAA+D,CAC9F,CAAC;IACJ,CAAC;IAED,MAAM,CAAC,SAAS,EAAE,cAAc,GAAG,EAAE,CAAC,GAAG,gBAAgB,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACrE,MAAM,UAAU,GACd,MAAM,CAAC,SAAS,CAAC,GAAG,MAAM,CAAC,EAAE,IAAI,aAAa,CAAC;QAC/C,MAAM,CAAC,cAAc,CAAC,MAAM,CAAC,aAAa,EAAE,GAAG,CAAC,CAAC,CAAC;IAEpD,IAAI,UAAU,IAAI,EAAE,EAAE,CAAC;QACrB,MAAM,IAAI,KAAK,CAAC,wCAAwC,CAAC,CAAC;IAC5D,CAAC;IAED,OAAO,UAAU,CAAC;AACpB,CAAC"}