@rio-pay/sdk 0.0.0-stage → 0.0.1-alpha.2

package/dist/lib/payments-solana.d.ts

@@ -0,0 +1,58 @@
+import type { PaymentOption } from "./payments-options";
+import type { TxOutcome } from "./payments";
+export interface StdAccount {
+    address: string;
+    publicKey?: Uint8Array;
+    chains?: readonly string[];
+}
+export interface StdWallet {
+    name: string;
+    chains: readonly string[];
+    accounts: readonly StdAccount[];
+    features: Record<string, unknown>;
+}
+export interface SolanaSession {
+    wallet: StdWallet;
+    account: StdAccount;
+    /** The base58 public key: what the service calls `buyer`. */
+    address: string;
+}
+export interface WalletRegistry {
+    get(): StdWallet[];
+    on(fn: () => void): () => void;
+}
+type EventTargetLike = Pick<EventTarget, "addEventListener" | "dispatchEvent">;
+/**
+ * Discovers Wallet Standard wallets. Wallets that loaded first announce themselves on
+ * `wallet-standard:register-wallet`; ones that load later wait for our `wallet-standard:app-ready`.
+ */
+export declare function createWalletRegistry(target: EventTargetLike): WalletRegistry;
+/** One registry per page. Null on the server. */
+export declare function getWalletRegistry(): WalletRegistry | null;
+/** A wallet that can connect and sign-and-send a Solana transaction. */
+export declare function isSolanaWallet(w: StdWallet): boolean;
+/** Solana-capable wallets; the one the buyer used last (`preferred`) first. */
+export declare function solanaWallets(registry: WalletRegistry | null, preferred?: string): StdWallet[];
+/** Connects `wallet`. `silent` only reuses an existing approval (no popup) and resolves null if there is none. */
+export declare function connectSolana(wallet: StdWallet, opts?: {
+    silent?: boolean;
+}): Promise<SolanaSession | null>;
+export declare function base58Encode(bytes: Uint8Array): string;
+export declare function bytesToBase64(bytes: Uint8Array): string;
+export declare function base64ToBytes(b64: string): Uint8Array;
+/** Hands the service-built transaction to the wallet to sign and send; returns the base58 signature. */
+export declare function signAndSendSolana(session: SolanaSession, transactionBase64: string, cluster: string): Promise<string>;
+/** Has the wallet sign, not send, a service-built transaction whose fee the service pays; returns it base64 for the service to send. */
+export declare function signSolana(session: SolanaSession, transactionBase64: string, cluster: string): Promise<string>;
+/** USDC (summed over the buyer's token accounts for the mint) and SOL in base units, through the option's RPC endpoints. */
+export declare function readSolanaBalances(option: PaymentOption, address: string): Promise<{
+    usdc: bigint;
+    native: bigint | null;
+}>;
+/** Polls until the signature is confirmed. A failed read is retried; `unknown` when it does not show in time or the wait is cancelled. */
+export declare function waitForSolanaSignature(rpcUrls: string[], signature: string, opts?: {
+    intervalMs?: number;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}): Promise<TxOutcome>;
+export {};

package/dist/lib/payments-sse.d.ts

@@ -0,0 +1,26 @@
+export interface SseFrame {
+    readonly event: string;
+    readonly data: string;
+}
+export interface SseState {
+    /** Text received but not yet terminated by a line ending. */
+    readonly pending: string;
+    readonly event: string;
+    /** `data:` lines of the frame being built; empty means no `data` field has been seen. */
+    readonly data: readonly string[];
+    readonly started: boolean;
+}
+export declare const SSE_START: SseState;
+/**
+ * Feeds one decoded chunk to the parser and returns the frames it completed plus the state to carry on with.
+ * A frame is delivered only once its blank line has arrived: input that ends mid-frame never yields a partial one.
+ */
+export declare function parseSse(state: SseState, chunk: string): {
+    state: SseState;
+    frames: SseFrame[];
+};
+/**
+ * Reads `body` to its end, calling `onFrame` for each complete frame. Resolves when the stream ends or `signal`
+ * aborts (the stream is cancelled); rejects if the underlying read fails.
+ */
+export declare function readSse(body: ReadableStream<Uint8Array>, onFrame: (f: SseFrame) => void, signal?: AbortSignal): Promise<void>;

package/dist/lib/payments-wallet.d.ts

@@ -0,0 +1,80 @@
+import type { PaymentOption } from "./payments-options";
+import { type AddChainParams, type AuthorizationBody, type TxOutcome, type TypedDataPayload } from "./payments";
+export interface Eip1193Provider {
+    request(args: {
+        method: string;
+        params?: unknown[] | object;
+    }): Promise<unknown>;
+}
+/** A short, non-sensitive name for the wallet (remembered as a preference only). */
+export declare function walletName(p: Eip1193Provider): string;
+/** The injected provider; with several wallets installed, prefers the one the buyer used last. */
+export declare function getInjectedProvider(preferred?: string): Eip1193Provider | null;
+/** One installed wallet the buyer can pick. `icon` is a data: image the wallet itself announced, or null. */
+export interface WalletInfo {
+    id: string;
+    name: string;
+    icon: string | null;
+    provider: Eip1193Provider;
+}
+/** Validates one `eip6963:announceProvider` event detail. Icons that are not data: images are dropped (never fetched). */
+export declare function parseAnnouncement(detail: unknown): WalletInfo | null;
+/**
+ * Lists the wallets the buyer has installed, with no dependency: EIP-6963 announcements first, and the plain
+ * `window.ethereum` (or its `providers` array) when nothing announced within `timeoutMs`. `onChange` gets the
+ * whole current list every time it changes; the returned function stops listening.
+ */
+export declare function watchWallets(onChange: (wallets: WalletInfo[]) => void, opts?: {
+    target?: EventTarget;
+    legacy?: () => Eip1193Provider[];
+    timeoutMs?: number;
+}): () => void;
+/** Asks the wallet to let the buyer pick another account for this site; falls back to a plain connect. */
+export declare function requestAccountSwitch(provider: Eip1193Provider): Promise<string>;
+/** Accounts the site is already authorized for. Never opens a popup. */
+export declare function getAuthorizedAccount(provider: Eip1193Provider): Promise<string | null>;
+export declare function currentChainId(provider: Eip1193Provider): Promise<number | null>;
+/** The buyer's USDC balance in base units, read from the wallet's current chain via eth_call. */
+export declare function readUsdcBalance(provider: Eip1193Provider, usdc: string, account: string): Promise<bigint>;
+/** Native (gas) balance in base units from the wallet's current chain. */
+export declare function readNativeBalance(provider: Eip1193Provider, account: string): Promise<bigint>;
+/**
+ * Read-only balances for an EVM option through its public RPC endpoints (no chain switch, no wallet
+ * prompt). USDC must be readable; the native balance is best effort (null when it could not be read).
+ */
+export declare function readEvmBalancesRpc(option: PaymentOption, account: string): Promise<{
+    usdc: bigint;
+    native: bigint | null;
+}>;
+export declare function connectWallet(provider: Eip1193Provider): Promise<string>;
+/**
+ * Switch to `chainId` (a no-op if already there); if the wallet doesn't know the chain (4902), add it with `addChain`
+ * and switch to it (EIP-3085: adding a chain need not select it). Then checks the wallet really is on `chainId`, so no
+ * balance is read and nothing is sent on another chain; throws when it is not (shown as a wrong network).
+ */
+export declare function ensureChain(provider: Eip1193Provider, chainId: number, addChain?: AddChainParams | null): Promise<void>;
+export declare function signAuthorization(provider: Eip1193Provider, account: string, typedData: TypedDataPayload): Promise<AuthorizationBody>;
+/**
+ * Polls for the receipt. A failed read is retried (a flaky node is not a failed payment); `unknown` when none shows
+ * within the timeout or the wait is cancelled.
+ */
+export declare function waitForReceipt(provider: Eip1193Provider, hash: string, opts?: {
+    intervalMs?: number;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}): Promise<TxOutcome>;
+/**
+ * Sends each tx in order, waiting for each one's receipt before the next (an approval must land before the payment
+ * that spends it), and returns the last tx's hash as soon as the wallet hands it back. From then on the payment may
+ * land whatever a node says next, so its receipt is the caller's to follow, never a reason to send it again.
+ */
+export declare function sendTransactions(provider: Eip1193Provider, from: string, txs: {
+    description: string;
+    to: string;
+    data: string;
+    value: string;
+}[], hooks?: {
+    onStep?: (index: number, description: string) => void;
+    signal?: AbortSignal;
+    intervalMs?: number;
+}): Promise<string>;

package/dist/lib/payments.d.ts

@@ -0,0 +1,348 @@
+export type ChargeStatus = "created" | "payment_pending" | "funded" | "settled" | "underpaid" | "expired";
+export type Confirmation = "pending" | "provisional" | "final";
+export interface AddChainParams {
+    chainId: string;
+    chainName: string;
+    nativeCurrency: {
+        name: string;
+        symbol: string;
+        decimals: number;
+    };
+    rpcUrls: string[];
+    blockExplorerUrls?: string[];
+}
+/** The fields the widget reads from the service's Charge object (see toChargeView). */
+export interface ChargeView {
+    status: ChargeStatus;
+    confirmed: boolean;
+    confirmation: Confirmation;
+    funded_amount?: string | null;
+}
+/** The created charge. Your HTTP create route returns exactly this object as its JSON body; the widget validates it (`parseCreatedCharge`). */
+export interface CreatedCharge {
+    chargeId: string;
+    clientSecret: string;
+    serviceUrl: string;
+    amount: string;
+    chain: {
+        id: number;
+        name: string;
+        usdc: string;
+        add_chain: AddChainParams | null;
+    };
+    chargeAddress: string;
+    status: ChargeStatus;
+    confirmed: boolean;
+    confirmation: Confirmation;
+    expiresAt: string | null;
+}
+/**
+ * What the `createCharge` callback resolves to (not an HTTP body): `postCreateCharge` or your own code builds it from your route's
+ * response, where success is the flat `CreatedCharge` JSON and failure is an error status with
+ * `{ error, code? }`. `status` is the HTTP status to surface (409 = this order already has a charge, or the
+ * amount differs from the existing one). `error` and `code` are for your `onError` handler only: the buyer
+ * never sees them.
+ */
+export type ChargeCreateResult = {
+    ok: true;
+    charge: CreatedCharge;
+} | {
+    ok: false;
+    status: number;
+    error: string;
+    code?: string;
+};
+/** Host route response for the status poll. Authoritative for the host. */
+export interface PlatformChargeStatus {
+    chargeId: string;
+    orderId: string | null;
+    status: ChargeStatus;
+    confirmed: boolean;
+    confirmation: Confirmation;
+    collectedAmount: string | null;
+    tags?: string[];
+}
+export interface TypedDataPayload {
+    domain: Record<string, unknown>;
+    types: Record<string, {
+        name: string;
+        type: string;
+    }[]>;
+    primaryType: string;
+    message: Record<string, unknown>;
+}
+export declare function formatUsdc(base: string | bigint): string;
+export declare function shortAddress(a: string): string;
+export declare function toHexChainId(id: number): string;
+export declare function toHexValue(value: string | undefined): string;
+/**
+ * eth_signTypedData_v4 takes a JSON string whose `types` includes EIP712Domain.
+ * The vendor omits it, so derive it from the domain's own fields. Integer
+ * message values stay as decimal strings, which wallets accept.
+ */
+export declare function buildSignTypedDataJson(td: TypedDataPayload): string;
+/**
+ * What a sent transaction came to, as far as the wallet's (or a public) node can tell. `unknown` is not a failure: the
+ * transaction may still land, so a payment in that state is never offered to the buyer to send again.
+ */
+export type TxOutcome = "confirmed" | "failed" | "unknown";
+export interface AuthorizationBody {
+    from: string;
+    value: string;
+    validAfter: string;
+    validBefore: string;
+    nonce: string;
+    signature: string;
+}
+export declare function buildAuthorizationBody(td: TypedDataPayload, fallbackFrom: string, signature: string): AuthorizationBody;
+/** Reads `confirmed` / `confirmation` from a service or host object. */
+export declare function normalizeConfirmation(raw: Record<string, unknown>): {
+    confirmed: boolean;
+    confirmation: Confirmation;
+};
+/** Narrows a service Charge JSON (GET /v1/charges/:id or an SSE frame) to what the widget reads. */
+export declare function toChargeView(raw: unknown): ChargeView | null;
+/** Validates the host's create-charge response; null if any load-bearing field is missing or the service URL is unsafe. */
+export declare function parseCreatedCharge(raw: unknown): CreatedCharge | null;
+export declare function parsePlatformStatus(raw: unknown): PlatformChargeStatus | null;
+/** URL the widget polls for the host's authoritative status, or null when the host disabled polling (`statusUrl={null}`). */
+export declare function platformStatusUrl(chargeId: string, statusUrl: ((chargeId: string) => string) | null): string | null;
+/**
+ * Resolve a caller-supplied return URL against `origin` and keep it only if it
+ * stays on that origin (http/https). The widget uses it before rendering a link;
+ * a host route can use it before forwarding a return URL to the service.
+ */
+export declare function sameOriginReturnUrl(returnUrl: unknown, origin: string): string | null;
+/**
+ * Every user-facing string. `{name}` placeholders are filled by `fill`. Override any subset via the `copy` prop.
+ * Network names are never copy: they come from the service as data and appear only on the token chip.
+ */
+export interface CheckoutCopy {
+    trigger: string;
+    title: string;
+    /** Header when the host names the merchant: `{merchant}` is filled in. */
+    titleFor: string;
+    close: string;
+    done: string;
+    amountDue: string;
+    payWith: string;
+    chooseUsdc: string;
+    connectWallet: string;
+    connectingWallet: string;
+    pay: string;
+    opening: string;
+    confirm: string;
+    confirmTx: string;
+    confirming: string;
+    paid: string;
+    preparing: string;
+    walletName: string;
+    balanceLabel: string;
+    gasLabel: string;
+    lowGas: string;
+    notEnough: string;
+    checking: string;
+    noUsdc: string;
+    insufficientAll: string;
+    checkAgain: string;
+    payAnotherWay: string;
+    back: string;
+    tryAgain: string;
+    startNew: string;
+    details: string;
+    rejected: string;
+    rejectedConnect: string;
+    rejectedPick: string;
+    noWallet: string;
+    noWalletMobile: string;
+    noWalletForOption: string;
+    openInWalletApp: string;
+    wrongNetwork: string;
+    insufficient: string;
+    noGas: string;
+    walletBusy: string;
+    txFailed: string;
+    network: string;
+    service: string;
+    unknown: string;
+    expired: string;
+    createFailed: string;
+    /** The order changed after its charge was made (a 409 from your route). */
+    conflict: string;
+    slow: string;
+    /** Final confirmation headline. */
+    received: string;
+    /** Headline while the payment is accepted but final settlement is still pending. */
+    receivedProvisional: string;
+    finalizing: string;
+    receiptLabel: string;
+    returnToStore: string;
+    stagesLabel: string;
+    stageWallet: string;
+    stageSent: string;
+    stageConfirmed: string;
+    /** Shown with the address: `{amount}` is filled in; covers an exchange deducting its fee. */
+    manualIntro: string;
+    /** Above the address: `{network}` is the network to choose when withdrawing (its chip's name, service data). */
+    manualWarning: string;
+    /** The checkbox that reveals the address: `{network}` as in `manualWarning`. */
+    manualConfirm: string;
+    manualWaiting: string;
+    /** For a buyer whose exchange cannot send on the network: `{network}` as in `manualWarning`. Withdraw to their own wallet and pay with it here. */
+    manualOwnWallet: string;
+    copyAddress: string;
+    copied: string;
+    openInWallet: string;
+    partial: string;
+    confirmNamed: string;
+    confirmTxNamed: string;
+    openingNamed: string;
+    sending: string;
+    notEnoughUsdc: string;
+    needsGas: string;
+    needsGasReason: string;
+    needsOtherWallet: string;
+    couldntCheck: string;
+    balanceUpdated: string;
+    walletMenu: string;
+    copyWalletAddress: string;
+    switchWallet: string;
+    disconnect: string;
+    chooseWallet: string;
+    lastUsed: string;
+    closeConfirm: string;
+    closeAnyway: string;
+    stay: string;
+    pauseBalances: string;
+    openInPhantom: string;
+    /** Decorator label for another token: `{symbol}` is filled in. */
+    balanceLabelFor: string;
+    /** What the buyer pays in their own token: `{amount}` is "0.0004 ETH". */
+    youPay: string;
+    youPayChecking: string;
+    youPayUpdating: string;
+    /** `{minutes}` is filled in. */
+    youPayTakes: string;
+    optionUnavailable: string;
+    optionUnavailableReason: string;
+    /** Button text when the wallet holds too little of the chosen token: `{symbol}` is filled in. */
+    notEnoughToken: string;
+    priceChanged: string;
+}
+export declare const DEFAULT_COPY: CheckoutCopy;
+export declare function fill(template: string, vars?: Record<string, string | number>): string;
+export declare function resolveCopy(overrides?: Partial<CheckoutCopy>): CheckoutCopy;
+/** "$0.05", "$12.50", "$1,234.56": USDC base units shown as dollars. */
+export declare function formatUsd(base: string | bigint): string;
+/** "base-sepolia" -> "Base Sepolia". Fallback label when the service sends no display name. */
+export declare function prettyChainName(name: string): string;
+/** "ch_01HXABCDEF12" -> "#ABCDEF12": short, human-quotable; the full id stays in Details. */
+export declare function shortReceiptId(chargeId: string): string;
+export declare function isAddress(a: unknown): a is string;
+/** Deep link that reopens `href` inside the MetaMask mobile browser; null for non-http(s) hrefs. */
+export declare function walletDeepLink(href: string): string | null;
+/**
+ * Phantom's documented "browse" deeplink (https://docs.phantom.com/phantom-deeplinks/other-methods/browse):
+ * `https://phantom.com/ul/browse/<url>?ref=<ref>`, both URL-encoded; `ref` is the requesting app's URL.
+ */
+export declare function phantomBrowseLink(href: string): string | null;
+export declare function isMobileUserAgent(ua: string): boolean;
+/** `balanceOf(address)` calldata. */
+export declare function encodeBalanceOf(account: string): string;
+export declare function parseHexUint(hex: unknown): bigint;
+export declare function amountRemaining(amount: string, funded: string | null | undefined): bigint;
+export type ProblemKind = "rejected" | "no_wallet" | "wrong_network" | "wallet_busy" | "insufficient" | "no_gas" | "tx_failed" | "expired" | "conflict" | "network" | "service" | "unknown";
+export interface Problem {
+    kind: ProblemKind;
+    message: string;
+    /** Controlled technical detail for support, shown collapsed: only an HTTP status and an allowlisted code. */
+    detail?: string;
+    /** Untrusted text from a host, the service or a wallet. Never rendered; reaches the host through `onError` only. */
+    cause?: string;
+    /** Present for `insufficient`. */
+    balance?: string;
+    needed?: string;
+}
+/** Thrown by the payment flow for a failure that already knows its buyer-facing problem. */
+export declare class PaymentProblem extends Error {
+    problem: Problem;
+    constructor(problem: Problem);
+}
+export interface ErrorContext {
+    /** The pay step that was running when the error happened. */
+    step?: PayStep;
+    copy?: CheckoutCopy;
+}
+/** The only fields a buyer may see under "Show details": an HTTP status and a code from a fixed list, never free text. */
+export declare function safeDetail(parts: {
+    status?: unknown;
+    code?: unknown;
+}): string | undefined;
+/** Maps a failed create-charge result to controlled copy by status and code; the host's `error` text goes to `cause` only. */
+export declare function mapCreateFailure(r: {
+    status: number;
+    error?: string;
+    code?: string;
+}, copy?: CheckoutCopy): Problem;
+/** Turns any wallet/provider/service error into one controlled message plus a collapsed detail of controlled fields; the raw text goes to `cause` (host only). */
+export declare function mapError(e: unknown, ctx?: ErrorContext): Problem;
+/** True when a raw error means the charge/authorization can no longer be used and a fresh one should be made. */
+export declare function isExpiredError(e: unknown): boolean;
+/** True when the service refused because another payment of this charge is already on its way (this tab's earlier try, or another tab's). */
+export declare function isPaymentInFlight(e: unknown): boolean;
+export type PayStep = "idle" | "connecting" | "switching" | "checking" | "signing" | "submitting" | "processing" | "paid";
+export interface PayState {
+    step: PayStep;
+    problem: Problem | null;
+}
+export type PayEvent = {
+    type: "start";
+} | {
+    type: "step";
+    step: Exclude<PayStep, "idle" | "processing" | "paid">;
+} | {
+    type: "submitted";
+} | {
+    type: "failed";
+    problem: Problem;
+} | {
+    type: "paid";
+} | {
+    type: "reset";
+};
+export declare const INITIAL_PAY_STATE: PayState;
+export declare function isBusy(step: PayStep): boolean;
+/** Steps only move forward while a payment is in flight; a failure always returns to idle with the problem. */
+export declare function payReducer(state: PayState, ev: PayEvent): PayState;
+export type StageState = "done" | "active" | "pending";
+export interface Stage {
+    key: "wallet" | "sent" | "confirmed";
+    state: StageState;
+}
+/**
+ * The three buyer-visible stages for a pay step: 1 wallet signature, 2 on-chain receipt,
+ * 3 confirmation from the host's status route. Preparation (connect, switch, balance check) all sit under stage 1.
+ */
+export declare function deriveStages(step: PayStep): Stage[];
+/**
+ * Text for the exact step, used by the live region, the busy button and the store-page trigger.
+ * `wallet` is the connected wallet's name when it is known ("your wallet" is the fallback).
+ */
+export declare function primaryLabel(step: PayStep, amountText: string, copy?: CheckoutCopy, wallet?: string | null): string;
+/** "Confirm in MetaMask (1 of 2)" / "Confirm in your wallet (1 of 2)". */
+export declare function confirmTxLabel(copy: CheckoutCopy, tx: {
+    i: number;
+    total: number;
+}, wallet?: string | null): string;
+/** Header text: "Pay" or "Pay {merchant}" when the host names the store. */
+export declare function headerTitle(copy: CheckoutCopy, merchantName?: string | null): string;
+/** Coarse state surfaced through `onStatusChange`. */
+export type CheckoutState = "loading" | "ready" | "connecting" | "confirming" | "processing" | "paid" | "settled" | "problem" | "failed";
+export interface Prefs {
+    wallet?: string;
+}
+type StorageLike = Pick<Storage, "getItem" | "setItem">;
+/** Never throws: storage may be blocked. Only a wallet name is ever stored. */
+export declare function loadPrefs(storage?: StorageLike | null): Prefs;
+export declare function savePrefs(patch: Prefs, storage?: StorageLike | null): void;
+export {};

package/dist/lib/rio-client.d.ts

@@ -0,0 +1,48 @@
+import type { CreatedCharge, PlatformChargeStatus } from "./payments";
+export interface RioClientOptions {
+    /** A secret API key (`sk_…`), from the dashboard's Developers page. Keep it on your server. */
+    apiKey: string;
+    /** The API base URL from the dashboard. Default: the `RIO_SERVICE_URL` environment variable, where there is one. */
+    serviceUrl?: string;
+    /** A custom `fetch`. Default: the global `fetch`, looked up at call time. */
+    fetch?: typeof fetch;
+}
+export interface CreateChargeInput {
+    /** USDC base units, as a string: `"12500000"` is $12.50. Decide it on your server, never from the browser. */
+    amount: string;
+    /** Your order id. */
+    externalRef: string;
+    /** Your storefront's web origin. A browser can only use the charge from there. Leave it out for a charge only a server handles. */
+    origin?: string;
+    merchantId?: string;
+    returnUrl?: string;
+    expiresInSeconds?: number;
+    requireConfirmation?: "provisional" | "final";
+    /** Settlement speed: `"standard"` (the default, no fee) or `"fast"`. */
+    speed?: "standard" | "fast";
+    /** Labels for filtering and reporting (at most 10, lowercase `[a-z0-9][a-z0-9:_./-]{0,63}`). */
+    tags?: readonly string[];
+    /** Private values to keep with the charge (strings, numbers or booleans, never nested). Returned to you, never to the buyer. */
+    metadata?: Readonly<Record<string, string | number | boolean>>;
+}
+export interface CreateChargeOptions {
+    /** Default: the order id, so a retried request returns the same charge instead of making another. */
+    idempotencyKey?: string;
+}
+/** Why a call failed. `status` is the HTTP status, or 0 when the service could not be reached. */
+export declare class RioError extends Error {
+    readonly status: number;
+    readonly code: string;
+    constructor(status: number, code: string, message: string);
+}
+/** A client for your server's side of the API. Make one with `createRioClient`. */
+export interface RioClient {
+    readonly charges: {
+        /** Creates the order's charge and returns it as the checkout widget takes it: your route can `Response.json(charge)`. A retry of the same order returns the same charge with a replacement client secret. */
+        readonly create: (input: CreateChargeInput, options?: CreateChargeOptions) => Promise<CreatedCharge>;
+        /** A charge's status, in the shape the widget's status poll takes: your status route can `Response.json(status)`. */
+        readonly retrieve: (id: string) => Promise<PlatformChargeStatus>;
+    };
+}
+/** Makes a client: `createRioClient({ apiKey })`. Throws a `TypeError` for a missing key or an unusable service URL. */
+export declare function createRioClient(options: RioClientOptions): RioClient;

package/dist/lib/webhook.d.ts

@@ -0,0 +1,32 @@
+export declare const SIGNATURE_HEADER = "Payments-Signature";
+/** How far a signed timestamp may be from the verifier's clock, either way. */
+export declare const DEFAULT_TOLERANCE_SECONDS = 300;
+export type SignWebhookInput = {
+    readonly secret: string;
+    /** Unix seconds. */
+    readonly timestamp: number;
+    /** The exact body string that will be sent. */
+    readonly body: string;
+};
+/** Build a header value the way the service does. Useful in your own tests; the service signs real events. */
+export declare function signWebhook({ secret, timestamp, body }: SignWebhookInput): Promise<string>;
+export type VerifyWebhookInput = {
+    /** The endpoint's signing secret (`whsec_...`). */
+    readonly secret: string;
+    /** The `Payments-Signature` header value. */
+    readonly header: string;
+    /** The RAW request body, exactly as received. Not `JSON.stringify(JSON.parse(raw))`: re-serializing changes the bytes. */
+    readonly body: string;
+    /** Default 300. */
+    readonly toleranceSeconds?: number;
+    /** The verifier's clock in ms since the epoch; default `Date.now()`. For tests. */
+    readonly now?: number;
+};
+/**
+ * True when the header is well formed, its timestamp is within tolerance of `now`, and at least one `v1` value is
+ * the HMAC of `"<t>.<body>"` under `secret` (several `v1` values appear during a secret rotation). Never throws on
+ * bad input: a malformed or forged header is just `false`. The comparison is constant time (`crypto.subtle.verify`).
+ *
+ * Delivery is at-least-once: also dedupe on the event `id`.
+ */
+export declare function verifyWebhook({ secret, header, body, toleranceSeconds, now, }: VerifyWebhookInput): Promise<boolean>;

package/dist/server.d.ts

@@ -0,0 +1,2 @@
+export { DEFAULT_TOLERANCE_SECONDS, SIGNATURE_HEADER, signWebhook, verifyWebhook } from "./lib/webhook";
+export type { SignWebhookInput, VerifyWebhookInput } from "./lib/webhook";

package/dist/server.js

@@ -0,0 +1 @@
+var f="Payments-Signature",p=300,i=new TextEncoder,u=(t)=>crypto.subtle.importKey("raw",i.encode(t),{name:"HMAC",hash:"SHA-256"},!1,["sign","verify"]),m=(t)=>[...new Uint8Array(t)].map((r)=>r.toString(16).padStart(2,"0")).join("");function d(t){if(!/^[0-9a-fA-F]{64}$/.test(t))return null;let r=new Uint8Array(new ArrayBuffer(32));return r.set(t.match(/../g).map((n)=>parseInt(n,16))),r}function g(t){let r=t.split(",").map((e)=>{let s=e.indexOf("=");return s<0?null:[e.slice(0,s).trim(),e.slice(s+1).trim()]}),n=r.filter((e)=>e?.[0]==="t");if(n.length!==1||!/^\d+$/.test(n[0][1]))return null;let o=Number(n[0][1]);if(!Number.isSafeInteger(o))return null;let a=r.flatMap((e)=>e?.[0]==="v1"&&e[1]?[e[1]]:[]);return a.length?{timestamp:o,signatures:a}:null}async function b({secret:t,timestamp:r,body:n}){let o=await crypto.subtle.sign("HMAC",await u(t),i.encode(`${r}.${n}`));return`t=${r},v1=${m(o)}`}async function A({secret:t,header:r,body:n,toleranceSeconds:o=300,now:a=Date.now()}){if(!t)return!1;let e=g(r);if(!e)return!1;if(Math.abs(a/1000-e.timestamp)>o)return!1;let s=await u(t),c=i.encode(`${e.timestamp}.${n}`);return(await Promise.all(e.signatures.map((y)=>{let l=d(y);return l?crypto.subtle.verify("HMAC",s,l,c):!1}))).some(Boolean)}export{p as DEFAULT_TOLERANCE_SECONDS,f as SIGNATURE_HEADER,b as signWebhook,A as verifyWebhook};