@genesis-tech/genesispay-seller 0.8.0

package/dist/client.d.ts

@@ -0,0 +1,275 @@
+import type { MandatesResource } from "./mandates.js";
+import type { CustomersResource } from "./customers.js";
+import type { InvoicesResource } from "./invoices.js";
+import type { VerifySettlement } from "./payment-gate.js";
+import type { PlansResource } from "./plans.js";
+import type { PaymentGateNetwork } from "./networks.js";
+import type { ConstructEventOptions, PeerPayEvent } from "./webhooks.js";
+/**
+ * The legacy `PeerPay` client — a Stripe-like entry point that owns the seller key and
+ * resolves everything else (payout wallet, network, base URL) from it. The key
+ * prefix decides the mode: `pp_sk_test_…` / legacy `pp_sk_…` → test,
+ * `pp_sk_live_…` → live. See docs/archive/SELLER_SDK_DX_SPEC.md.
+ */
+export type PeerPayKeyMode = "test" | "live";
+export type PeerPayClientOptions = {
+    /** pp_sk_test_… | pp_sk_live_… | legacy pp_sk_… — the only required field. */
+    apiKey: string;
+    /** Overrides the mode→URL default (self-host / staging). Must be https (http only for localhost). */
+    baseUrl?: string;
+    /** Injectable fetch for tests. Defaults to the global fetch. */
+    fetchFn?: typeof fetch;
+    /** Seller-config cache TTL. Default 5 min. */
+    configTtlMs?: number;
+    /** Optional local pin on the resolved payout wallet; recommended for live keys. */
+    expectedPayTo?: string;
+};
+export type SellerConfig = {
+    id: string;
+    mode: PeerPayKeyMode;
+    payTo: string | null;
+    hasPayTo: boolean;
+    network: {
+        networkName: PaymentGateNetwork;
+        chainId: number;
+        usdcAddress: string;
+        asset: "USDC";
+    };
+};
+/**
+ * The amount half of {@link CheckoutCreateInput}, as a union so that **one of
+ * the two names is always required at compile time** — `amountUsdc` was a
+ * required property before 0.6.0, and losing that to two optional fields would
+ * have turned a type error into a runtime one.
+ */
+export type CheckoutAmountInput = {
+    /**
+     * Decimal amount **in `asset`** — `"5.00"`, at most 6 decimals, always a
+     * string (a float would lose minor units). Hosted checkout links settle
+     * in USDC during the beta, so the amount is in dollars.
+     *
+     * Passing the deprecated `amountUsdc` alongside it is allowed only when
+     * both are the same amount; two different values throw
+     * `PeerPayValidationError` before the request.
+     */
+    amount: string;
+    /** @deprecated Use `amount` alone. */
+    amountUsdc?: string;
+} | {
+    amount?: string;
+    /**
+     * @deprecated Renamed to `amount` in 0.6.0. The name claimed a currency
+     * the value did not always have. Still accepted, and still sent on the wire for backends older than
+     * 0.6.0 — but new code should set `amount`.
+     */
+    amountUsdc: string;
+};
+export type CheckoutCreateInput = CheckoutAmountInput & {
+    title: string;
+    description?: string;
+    linkType?: "single" | "reusable";
+    destinationWallet?: string;
+    /**
+     * Hosted checkout links settle in USDC during the beta. Omit this field in
+     * new integrations; it is kept only to make the invariant explicit in the
+     * request type.
+     */
+    asset?: "USDC";
+    /** Free-form correlation data; echoed back in webhooks and `checkout.retrieve()`. */
+    metadata?: Record<string, string>;
+    /** The merchant's own reference (Stripe: client_reference_id). */
+    clientReferenceId?: string;
+    /** Where the payer returns after a successful payment (https). */
+    returnUrl?: string;
+    /** Where the payer returns when they cancel (https). */
+    cancelUrl?: string;
+};
+export type CheckoutLink = {
+    publicId: string;
+    payUrl: string;
+    /** Decimal amount in `asset`, as the server normalized it (e.g. `"5.00"`). */
+    amount: string;
+    /** @deprecated Same value as {@link CheckoutLink.amount}; see the input field. */
+    amountUsdc: string;
+    /**
+     * The currency `amount` is denominated in. Echoed back on create so a EURC
+     * link can be confirmed as one without a second round-trip.
+     */
+    asset: "USDC" | "EURC";
+    title: string;
+    metadata: Record<string, string> | null;
+    clientReferenceId: string | null;
+    returnUrl: string | null;
+    cancelUrl: string | null;
+};
+/** Lifecycle of a single payment attempt on a link, as the server reports it. */
+export type CheckoutAttemptStatus = "pending" | "submitted" | "confirmed" | "failed" | "expired";
+/**
+ * One payment attempt against a checkout link — the receipt data (`txHash`,
+ * `payerWallet`) that `paid === true` alone cannot give you.
+ *
+ * A `reusable` link accumulates attempts; the newest comes first. `txHash` is
+ * null while an attempt is still pending, and stays null for attempts created
+ * by the test-mode `simulate-payment` endpoint (no transaction exists).
+ */
+export type CheckoutAttempt = {
+    id: string;
+    status: CheckoutAttemptStatus;
+    txHash: string | null;
+    payerWallet: string | null;
+    createdAt: string;
+    confirmedAt: string | null;
+    failureReason: string | null;
+    /**
+     * True when no funds moved — an attempt created by
+     * `checkout.simulatePayment`. Note that such an attempt also has
+     * `txHash: null` — but so does a pending real one, which is why this flag
+     * exists rather than inferring it.
+     *
+     * `false` for a real settlement, including on testnet and in provider
+     * sandboxes: this is the fabricated-payment axis, not the environment axis.
+     *
+     * Defaults to `false` against a backend that does not report it.
+     */
+    simulated: boolean;
+};
+export type CheckoutSession = CheckoutLink & {
+    description: string | null;
+    linkType: "single" | "reusable";
+    status: "active" | "paid" | "archived";
+    destinationWallet: string;
+    chainId: number;
+    /**
+     * true as soon as at least one payment is confirmed — the value to poll on.
+     *
+     * For a `reusable` link this answers "has this link ever been paid", not "has
+     * this buyer paid": `confirmedPaymentCount` only grows, so `paid` stays true
+     * from the first payment onward. Per-buyer fulfilment on a reusable link needs
+     * a webhook, or `confirmedPaymentCount` tracked as a delta.
+     */
+    paid: boolean;
+    confirmedPaymentCount: number;
+    createdAt: string;
+    /**
+     * Payment attempts for this link, newest first — empty when the server does
+     * not report them (older backend) or when nobody has tried to pay yet.
+     */
+    attempts: CheckoutAttempt[];
+};
+export type SimulatePaymentOptions = {
+    /**
+     * Payer address recorded on the simulated attempt. Defaults to a deliberately
+     * synthetic server-side placeholder, so nobody mistakes a simulated payment
+     * for a real payer in a dashboard or an export.
+     */
+    payerWallet?: string;
+};
+export type GateConfig = {
+    amountUsdc: string;
+    description?: string;
+    resource?: string;
+    mimeType?: string;
+    maxTimeoutSeconds?: number;
+};
+type GateHandler<Args extends unknown[]> = (request: Request, ...args: Args) => Response | Promise<Response>;
+export interface ResolvingGate {
+    wrap<Args extends unknown[]>(handler: GateHandler<Args>, opts?: {
+        verifySettlement?: VerifySettlement;
+    }): (request: Request, ...args: Args) => Promise<Response>;
+    /** Warm the seller-config cache (and surface auth/wallet errors) before traffic. */
+    prime(): Promise<void>;
+}
+export { PeerPayConfigError, PeerPayNetworkSafetyError, PeerPayNotFoundError, PeerPayRateLimitError, PeerPayValidationError, type PeerPayValidationIssue, } from "./errors.js";
+export declare class PeerPay {
+    readonly mode: PeerPayKeyMode;
+    readonly baseUrl: string;
+    readonly checkout: {
+        create(input: CheckoutCreateInput): Promise<CheckoutLink>;
+        retrieve(publicId: string): Promise<CheckoutSession>;
+        /**
+         * Test mode only: records a confirmed payment on one of your links without
+         * any money moving, and fires the real `payment.confirmed` (plus
+         * `link.paid` for a single-use link) webhooks — the point being that you can
+         * exercise your webhook handler end to end.
+         *
+         * The resulting attempt carries `simulated: true` and `txHash: null`; there
+         * is no transaction, and a made-up hash would be a lie in a field other
+         * systems point a block explorer at.
+         */
+        simulatePayment(publicId: string, opts?: SimulatePaymentOptions): Promise<CheckoutSession>;
+    };
+    /** Subscription plans and their hosted `checkoutUrl` — see ./plans.ts. */
+    readonly plans: PlansResource;
+    /** Reusable billing contacts for one-off invoices. */
+    readonly customers: CustomersResource;
+    /** Draft, finalize, deliver, and collect one-off invoices. */
+    readonly invoices: InvoicesResource;
+    /**
+     * Payment mandates: bounded, revocable spending approvals a payer signs once.
+     *
+     * There is no `mandates.activate` on purpose — activation carries the
+     * *payer's* signature, is authorized by their wallet rather than by this API
+     * key, and therefore belongs in the payer-facing frontend. See the module
+     * comment in ./mandates.ts.
+     */
+    readonly mandates: MandatesResource;
+    /**
+     * Webhook signature verification. Also exported as the free function
+     * `constructEvent` — a webhook route rarely has a client instance in scope,
+     * and verification needs the endpoint secret rather than the API key.
+     */
+    readonly webhooks: {
+        constructEvent(rawBody: string | Uint8Array, signatureHeader: string, secret: string, opts?: ConstructEventOptions): Promise<PeerPayEvent>;
+    };
+    private readonly apiKey;
+    private readonly fetchFn;
+    private readonly configTtlMs;
+    private readonly expectedPayTo?;
+    private cache?;
+    private inflight?;
+    /**
+     * The single authenticated-JSON seam every resource goes through. Bound as a
+     * field so it can be handed to `./plans.ts` / `./mandates.ts` without leaking
+     * the key, the base URL or `fetch` into them.
+     */
+    private readonly request;
+    constructor(options: PeerPayClientOptions);
+    /**
+     * Resolve (and cache) the seller config from the key. Single-flight so a
+     * cold-start burst shares one request; failures are never cached (the memo is
+     * cleared on rejection so the next call retries).
+     */
+    retrieveSeller(opts?: {
+        forceRefresh?: boolean;
+    }): Promise<SellerConfig>;
+    gate(config: GateConfig): ResolvingGate;
+    private fetchSeller;
+    private assertSafe;
+    /**
+     * Applies the `expectedPayTo` pin to a destination the server just froze onto
+     * a newly created object.
+     *
+     * Checking it in `assertSafe` alone was not enough: that only covers the
+     * `/api/v1/seller` config lookup, while a checkout link and a subscription
+     * plan each record their own `destinationWallet` at creation. Those are the
+     * addresses money actually moves to — a pin that does not cover them is not
+     * the guarantee the option advertises.
+     */
+    private assertPinnedDestination;
+    /**
+     * One authenticated JSON round-trip, with the error mapping every method
+     * shares. A transport failure (no response at all) is the only case handled
+     * here rather than in `throwForErrorResponse`, because there is no status to
+     * map — it is always a config/connectivity problem.
+     */
+    private performRequest;
+    private createCheckout;
+    /**
+     * Fetch the current state of a checkout link. `paid` is the field to poll on;
+     * an unknown publicId raises `PeerPayNotFoundError`, never a config error.
+     */
+    private retrieveCheckout;
+    /** Test-mode only — see the doc on `checkout.simulatePayment`. */
+    private simulateCheckoutPayment;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

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