paykit-bd 0.1.0

package/dist/client-Y9603twG.d.ts

@@ -0,0 +1,475 @@
+import { T as TokenStore, L as Logger, R as RawWebhookRequest, W as WebhookEvent, P as PaymentProvider, C as CreatePaymentInput, a as CreatedPayment, b as Payment, c as RefundInput, d as Refund } from './token-store-C8IMMLPJ.js';
+
+type BkashEnvironment = "sandbox" | "live";
+/**
+ * Hosts are the published tokenized-checkout endpoints, confirmed against the
+ * sandbox. If bKash issued you a different host during onboarding, set
+ * `baseUrl` and it wins over `environment`.
+ */
+declare const BKASH_HOSTS: Record<BkashEnvironment, string>;
+/** The version segment the checkout and agreement endpoints sit under. */
+declare const BKASH_API_VERSION = "v1.2.0-beta";
+/**
+ * bKash mode codes. They select what `/tokenized/checkout/create` actually does,
+ * and getting one wrong is the most common integration bug.
+ */
+declare const BKASH_MODE: {
+    /** Create an agreement — no money moves, you get an agreementID back. */
+    readonly CREATE_AGREEMENT: "0000";
+    /** Charge an existing agreement. Customer confirms with a PIN only. */
+    readonly AGREEMENT_PAYMENT: "0001";
+    /** One-off payment, no agreement. Customer is redirected to bKash. */
+    readonly ONE_OFF_PAYMENT: "0011";
+};
+type BkashMode = (typeof BKASH_MODE)[keyof typeof BKASH_MODE];
+interface BkashConfig {
+    /** Picks the base URL. Ignored when `baseUrl` is set. */
+    environment?: BkashEnvironment;
+    /** Host origin override, e.g. `https://tokenized.sandbox.bka.sh`. No trailing path. */
+    baseUrl?: string;
+    username: string;
+    password: string;
+    appKey: string;
+    appSecret: string;
+    /** Default redirect target after the customer approves, fails or cancels. */
+    callbackUrl?: string;
+    /**
+     * Where tokens live between calls. Defaults to an in-process store, which is
+     * only safe for a single instance — see {@link TokenStore}.
+     */
+    tokenStore?: TokenStore;
+    /**
+     * Namespaces the stored token. Change it if one process serves more than one
+     * bKash merchant account. Defaults to a hash of the app key.
+     */
+    tokenKey?: string;
+    /**
+     * Refresh the token this long before it actually expires. bKash suggests the
+     * 50th–55th minute of a 60-minute token; default is 10 minutes of headroom.
+     */
+    refreshSkewMs?: number;
+    /**
+     * Hard ceiling on token acquisitions per rolling hour. bKash blocks the
+     * merchant for an hour past two refreshes, so the default leaves no slack.
+     * Raise it only if bKash has told you your limit differs.
+     */
+    maxRefreshesPerHour?: number;
+    /** Per-request timeout in ms. Default 30000. */
+    timeoutMs?: number;
+    /** Pin the SNS topic your IPN messages arrive on. Strongly recommended. */
+    webhookTopicArn?: string;
+    logger?: Logger;
+}
+interface ResolvedBkashConfig extends Required<Omit<BkashConfig, "logger" | "tokenStore" | "callbackUrl" | "webhookTopicArn" | "baseUrl">> {
+    origin: string;
+    callbackUrl?: string;
+    webhookTopicArn?: string;
+}
+/** Full URLs for every endpoint, derived from one origin. */
+declare function endpoints(origin: string): {
+    grantToken: string;
+    refreshToken: string;
+    /** Serves agreement creation and both payment modes; `mode` decides which. */
+    create: string;
+    /** Finalises whatever `create` started, agreement or payment. */
+    execute: string;
+    queryPayment: string;
+    queryAgreement: string;
+    cancelAgreement: string;
+    refund: string;
+    refundStatus: string;
+    /** Pre-v2 refund, still provisioned for some merchants. */
+    legacyRefund: string;
+};
+declare function resolveConfig(config: BkashConfig): ResolvedBkashConfig;
+/**
+ * Build a config from process.env. Reads BKASH_ENV, BKASH_USERNAME,
+ * BKASH_PASSWORD, BKASH_APP_KEY, BKASH_APP_SECRET, BKASH_BASE_URL,
+ * BKASH_CALLBACK_URL and BKASH_WEBHOOK_TOPIC_ARN.
+ */
+declare function configFromEnv(env?: Record<string, string | undefined>): BkashConfig;
+
+/** bKash spells these lower-case on the wire. */
+type BkashIntent = "sale" | "authorization";
+/** bKash's own wire shapes. Field names are theirs, including the inconsistent ones. */
+interface GrantTokenResponse {
+    statusCode?: string;
+    statusMessage?: string;
+    token_type?: string;
+    id_token?: string;
+    refresh_token?: string;
+    expires_in?: number;
+}
+interface AgreementResponse {
+    statusCode?: string;
+    statusMessage?: string;
+    errorCode?: string;
+    errorMessage?: string;
+    paymentID?: string;
+    bkashURL?: string;
+    callbackURL?: string;
+    successCallbackURL?: string;
+    failureCallbackURL?: string;
+    cancelledCallbackURL?: string;
+    agreementID?: string;
+    agreementStatus?: string;
+    agreementCreateTime?: string;
+    agreementExecuteTime?: string;
+    payerReference?: string;
+    customerMsisdn?: string;
+}
+interface CreatePaymentRequest {
+    mode: BkashMode;
+    payerReference: string;
+    callbackURL: string;
+    amount: string;
+    currency: "BDT";
+    intent: BkashIntent;
+    merchantInvoiceNumber?: string;
+    /** Required for mode 0001 — the agreement being charged. */
+    agreementID?: string;
+    /** Aggregator / sub-merchant identifier, where bKash has issued one. */
+    merchantAssociationInfo?: string;
+}
+interface CreatePaymentResponse {
+    statusCode?: string;
+    statusMessage?: string;
+    errorCode?: string;
+    errorMessage?: string;
+    paymentID?: string;
+    /** Absent for mode 0001: an agreement payment needs no redirect. */
+    bkashURL?: string;
+    callbackURL?: string;
+    successCallbackURL?: string;
+    failureCallbackURL?: string;
+    cancelledCallbackURL?: string;
+    amount?: string;
+    intent?: string;
+    currency?: string;
+    agreementID?: string;
+    paymentCreateTime?: string;
+    transactionStatus?: string;
+    merchantInvoiceNumber?: string;
+}
+interface ExecutePaymentResponse {
+    statusCode?: string;
+    statusMessage?: string;
+    errorCode?: string;
+    errorMessage?: string;
+    paymentID?: string;
+    agreementID?: string;
+    payerReference?: string;
+    customerMsisdn?: string;
+    /** The financial transaction id. Only present once the payment completed. */
+    trxID?: string;
+    amount?: string;
+    transactionStatus?: string;
+    paymentExecuteTime?: string;
+    currency?: string;
+    intent?: string;
+    merchantInvoiceNumber?: string;
+}
+/**
+ * Query Payment. Note `merchantInvoice` — the query endpoint drops the `Number`
+ * suffix that create and execute both use. Confirmed against sandbox.
+ */
+interface QueryPaymentResponse {
+    statusCode?: string;
+    statusMessage?: string;
+    errorCode?: string;
+    errorMessage?: string;
+    paymentID?: string;
+    mode?: string;
+    paymentCreateTime?: string;
+    paymentExecuteTime?: string;
+    amount?: string;
+    currency?: string;
+    intent?: string;
+    merchantInvoice?: string;
+    merchantInvoiceNumber?: string;
+    trxID?: string;
+    transactionStatus?: string;
+    verificationStatus?: string;
+    /** Undocumented, but returned: what is still refundable on this payment. */
+    maxRefundableAmount?: string;
+    payerReference?: string;
+    customerMsisdn?: string;
+    agreementID?: string;
+    agreementStatus?: string;
+    agreementCreateTime?: string;
+    agreementExecuteTime?: string;
+}
+interface RefundRequest {
+    /** Lower-case `d` on the v2 API, unlike every other endpoint's `paymentID`. */
+    paymentId: string;
+    trxId: string;
+    refundAmount: string;
+    /**
+     * Mandatory in practice, though the docs read as though it were optional.
+     * Omit `sku` or `reason` and the v2 refund API rejects the call at its schema
+     * layer with `{"message": "Invalid request body"}` — no code, no field name,
+     * nothing to debug from. Verified against the sandbox: the identical request
+     * succeeds once both are present.
+     */
+    sku: string;
+    reason: string;
+}
+interface RefundResponse {
+    originalTrxId?: string;
+    refundTrxId?: string;
+    refundTransactionStatus?: string;
+    originalTrxAmount?: string;
+    refundAmount?: string;
+    currency?: string;
+    completedTime?: string;
+    sku?: string;
+    reason?: string;
+    /** v2 error envelope. */
+    internalCode?: string;
+    externalCode?: string;
+    errorMessageEn?: string;
+    errorMessageBn?: string;
+}
+interface RefundStatusResponse {
+    originalTrxId?: string;
+    originalTrxAmount?: string;
+    originalTrxCompletedTime?: string;
+    refundTransactions?: Array<{
+        refundTrxId?: string;
+        refundTransactionStatus?: string;
+        refundAmount?: string;
+        completedTime?: string;
+    }>;
+    internalCode?: string;
+    externalCode?: string;
+    errorMessageEn?: string;
+    errorMessageBn?: string;
+}
+/**
+ * The query string bKash appends when it redirects the customer back to your
+ * callback URL. `status` is the only field worth branching on, and none of it
+ * is trustworthy on its own — always confirm with executePayment or getPayment.
+ */
+interface BkashCallbackQuery {
+    paymentID?: string;
+    status?: "success" | "failure" | "cancel" | string;
+    /** Present from v1.2.0-beta. Opaque; bKash publishes no verification scheme. */
+    signature?: string;
+    apiVersion?: string;
+    product?: string;
+}
+
+interface SnsEnvelope {
+    Type?: string;
+    MessageId?: string;
+    TopicArn?: string;
+    Subject?: string;
+    Message?: string;
+    Timestamp?: string;
+    SignatureVersion?: string;
+    Signature?: string;
+    SigningCertURL?: string;
+    SubscribeURL?: string;
+    Token?: string;
+    UnsubscribeURL?: string;
+}
+/** The JSON string inside `Message` for a payment notification. */
+interface BkashIpnMessage {
+    dateTime?: string;
+    debitMSISDN?: string;
+    creditOrganizationName?: string;
+    creditShortCode?: string;
+    trxID?: string;
+    transactionStatus?: string;
+    transactionType?: string;
+    amount?: string;
+    currency?: string;
+    transactionReference?: string;
+    merchantInvoiceNumber?: string;
+    /** Coupon-funded payments carry three extra fields. */
+    couponAmount?: string;
+    merchantShareAmount?: string;
+    saleAmount?: string;
+}
+/** bKash's numeric transactionType codes, as published with the IPN docs. */
+declare const BKASH_TRANSACTION_TYPES: Record<string, string>;
+interface WebhookVerifierOptions {
+    /**
+     * Accept messages only from these SNS topic ARNs. Leave unset and any topic
+     * with a valid Amazon signature is accepted — which includes topics belonging
+     * to someone else's merchant account. Pin it: the ARN is in the TopicArn field
+     * of the first message you receive.
+     */
+    topicArn?: string | string[];
+    /**
+     * Reject messages older than this. Unset by default, because SNS legitimately
+     * retries for days and a tight window silently drops real payments. Make the
+     * handler idempotent on `eventId` instead.
+     */
+    maxAgeMs?: number;
+    /** How long a fetched signing certificate is reused. Default 24h. */
+    certCacheMs?: number;
+    logger?: Logger;
+    /** Injected in tests. Defaults to `fetch`. */
+    fetchImpl?: typeof fetch;
+}
+declare class BkashWebhookVerifier {
+    #private;
+    constructor(options?: WebhookVerifierOptions);
+    /**
+     * Verify an inbound request and normalise it.
+     *
+     * `request.body` must be the raw bytes as received. A body that has been
+     * parsed and re-serialised will not match the signature.
+     */
+    verify(request: RawWebhookRequest): Promise<WebhookEvent>;
+    /**
+     * Confirm an SNS subscription by visiting its SubscribeURL.
+     *
+     * Deliberately not automatic: it is an outbound call that switches on real
+     * payment traffic, so your handler decides when to make it. Verify the
+     * message first — this method re-checks the URL host but assumes the
+     * signature was already proven.
+     */
+    confirmSubscription(envelope: SnsEnvelope): Promise<void>;
+    /** Parse an already-verified envelope's inner payment message. */
+    static parseMessage(envelope: SnsEnvelope): BkashIpnMessage | null;
+}
+/**
+ * The exact byte sequence SNS signed: each present field as `name\nvalue\n`, in
+ * this order. Field order and the choice of fields are part of the signature —
+ * changing either makes every message fail to verify.
+ */
+declare function canonicalString(envelope: SnsEnvelope): string;
+/** Reject any URL that is not an Amazon SNS certificate or confirmation endpoint. */
+declare function assertSnsUrl(rawUrl: string, field: string): URL;
+
+interface BkashClientOptions {
+    tokenStore?: TokenStore;
+    logger?: Logger;
+    webhook?: Omit<WebhookVerifierOptions, "logger">;
+}
+interface CreateAgreementInput {
+    /** The customer's wallet number. Pre-fills the bKash entry screen. */
+    payerReference: string;
+    callbackUrl?: string;
+}
+interface AgreementHandle {
+    paymentId: string;
+    /** Send the customer here to enter their wallet number and OTP. */
+    redirectUrl: string | null;
+    status: string;
+    raw: AgreementResponse;
+}
+interface Agreement {
+    agreementId: string;
+    paymentId?: string;
+    customerMsisdn?: string;
+    payerReference?: string;
+    status: string;
+    createdAt?: Date;
+    executedAt?: Date;
+    raw: AgreementResponse;
+}
+/**
+ * bKash tokenized checkout.
+ *
+ * Implements {@link PaymentProvider}, plus the agreement operations that have no
+ * equivalent at other gateways.
+ *
+ * ```ts
+ * const bkash = new BkashClient(configFromEnv());
+ * const payment = await bkash.createPayment({ amount: "500", reference: "ORD-1" });
+ * // send the customer to payment.redirectUrl, then when they come back:
+ * const settled = await bkash.executePayment(payment.paymentId);
+ * ```
+ */
+declare class BkashClient implements PaymentProvider {
+    #private;
+    readonly id = "bkash";
+    constructor(config: BkashConfig, options?: BkashClientOptions);
+    /** Which environment and host this client is pointed at. */
+    get environment(): {
+        environment: string;
+        origin: string;
+    };
+    /** Token budget for the current rolling hour. */
+    tokenBudget(): Promise<{
+        refreshesUsed: number;
+        refreshesAllowed: number;
+        acquisitionsUsed: number;
+    }>;
+    /**
+     * Force a token refresh, spending one unit of the hourly budget. Normal use
+     * should leave this alone and let the client renew when it needs to; it is
+     * here so the refresh path can be exercised deliberately.
+     */
+    refreshToken(): Promise<string>;
+    /**
+     * Step 1 of 2. Start an agreement so this customer can later pay with a PIN
+     * alone. Send them to `redirectUrl`, then call {@link executeAgreement}.
+     */
+    createAgreement(input: CreateAgreementInput): Promise<AgreementHandle>;
+    /**
+     * Step 2 of 2. Call once the customer returns to your callback URL. The
+     * `agreementID` it returns is what you store against the customer — it is the
+     * whole point of the flow and bKash will not hand it to you again.
+     */
+    executeAgreement(paymentId: string): Promise<Agreement>;
+    getAgreement(agreementId: string): Promise<Agreement>;
+    /** Ends the agreement. The customer must go through the OTP flow again after this. */
+    cancelAgreement(agreementId: string): Promise<Agreement>;
+    /**
+     * Start a payment.
+     *
+     * Passing `extra.agreementID` charges an existing agreement (mode 0001) and
+     * returns no `redirectUrl` — the customer confirms with a PIN in the bKash
+     * app. Without it this is a one-off payment (mode 0011) and the customer must
+     * be sent to `redirectUrl`.
+     */
+    createPayment(input: CreatePaymentInput): Promise<CreatedPayment>;
+    /**
+     * Finalise a payment after the customer approves it. Valid exactly once per
+     * payment id.
+     *
+     * If bKash answers that the payment was already executed, this reads the real
+     * outcome with {@link getPayment} instead of throwing — that response means
+     * the money moved, and the caller wants the result, not an error.
+     */
+    executePayment(paymentId: string): Promise<Payment>;
+    /** Read current state. Safe to call as often as you like — this is the recovery path. */
+    getPayment(paymentId: string): Promise<Payment>;
+    /** How much of this payment can still be refunded, per bKash. */
+    getRefundableAmount(paymentId: string): Promise<string | null>;
+    /**
+     * Refund all or part of a completed payment.
+     *
+     * The v2 API allows up to ten partial refunds per transaction, within 60 days.
+     * Omit `amount` for a full refund, which is read from bKash's own
+     * `maxRefundableAmount` rather than assumed.
+     */
+    refund(input: RefundInput): Promise<Refund>;
+    /** Every refund recorded against one transaction. */
+    getRefunds(input: {
+        paymentId: string;
+        transactionId: string;
+    }): Promise<{
+        originalTransactionId: string;
+        originalAmount: string;
+        refunds: Refund[];
+        raw: RefundStatusResponse;
+    }>;
+    /** Verify an inbound IPN message and normalise it. Throws if it is not genuine. */
+    verifyWebhook(request: RawWebhookRequest): Promise<WebhookEvent>;
+    get webhooks(): BkashWebhookVerifier;
+    /**
+     * Read the query string bKash appends when it redirects a customer back.
+     *
+     * Nothing here is proof of payment — it is a URL the customer's own browser
+     * followed and could have edited. Always confirm with {@link executePayment}
+     * or {@link getPayment} before releasing an order.
+     */
+    static parseCallback(input: string | URL | URLSearchParams | Record<string, string>): BkashCallbackQuery;
+}
+
+export { type Agreement as A, BkashClient as B, type CreateAgreementInput as C, type ExecutePaymentResponse as E, type GrantTokenResponse as G, type QueryPaymentResponse as Q, type ResolvedBkashConfig as R, type SnsEnvelope as S, type WebhookVerifierOptions as W, BkashWebhookVerifier as a, type AgreementHandle as b, type AgreementResponse as c, BKASH_API_VERSION as d, BKASH_HOSTS as e, BKASH_MODE as f, BKASH_TRANSACTION_TYPES as g, type BkashCallbackQuery as h, type BkashClientOptions as i, type BkashConfig as j, type BkashEnvironment as k, type BkashIntent as l, type BkashIpnMessage as m, type BkashMode as n, type CreatePaymentRequest as o, type CreatePaymentResponse as p, type RefundRequest as q, type RefundResponse as r, type RefundStatusResponse as s, assertSnsUrl as t, canonicalString as u, configFromEnv as v, endpoints as w, resolveConfig as x };

package/dist/errors-CleuZfqT.d.cts

@@ -0,0 +1,103 @@
+/**
+ * Every error this library throws is a PaykitError, so a caller can write one
+ * catch block and still tell a declined payment apart from a dead socket.
+ *
+ * `instanceof` is answered from a brand rather than from the prototype chain,
+ * and that is deliberate. This package ships several entry points — `paykit-bd`,
+ * `paykit-bd/bkash`, `paykit-bd/bkash/next` — and each is a separate bundle
+ * carrying its own copy of these classes. A plain `instanceof` compares class
+ * identity, so an error thrown by the bkash client would *not* match the class
+ * imported from the root entry. It would fail silently, which in a payment
+ * library means a customer's declined PIN handled as an unknown error. The
+ * brand also holds when two versions of this package end up installed at once,
+ * or across a worker boundary, where plain `instanceof` fails for the same
+ * reason.
+ */
+declare const BRANDS: unique symbol;
+declare abstract class PaykitError extends Error {
+    static [Symbol.hasInstance]: (value: unknown) => boolean;
+    /** Class lineage, innermost last. Read `instanceof` instead of this. */
+    readonly [BRANDS]: readonly string[];
+    /** Gateway this came from — `"bkash"`, or `"paykit"` for local failures. */
+    readonly provider: string;
+    /** Stable machine-readable code. Gateway codes are passed through verbatim. */
+    readonly code: string;
+    /** True when retrying the identical request could plausibly succeed. */
+    readonly retryable: boolean;
+    /** Untouched gateway response body, for logging. */
+    readonly raw: unknown;
+    protected constructor(message: string, opts: {
+        provider: string;
+        code: string;
+        retryable?: boolean;
+        raw?: unknown;
+        cause?: unknown;
+    }, brands?: readonly string[]);
+    toJSON(): Record<string, unknown>;
+}
+/** The gateway answered, and the answer was an error. `code` is its own code. */
+declare class ProviderError extends PaykitError {
+    static [Symbol.hasInstance]: (value: unknown) => boolean;
+    constructor(message: string, opts: {
+        provider: string;
+        code: string;
+        retryable?: boolean;
+        raw?: unknown;
+        cause?: unknown;
+    }, brands?: readonly string[]);
+}
+/** The request never produced a usable answer: DNS, TLS, timeout, 5xx, bad JSON. */
+declare class NetworkError extends PaykitError {
+    static [Symbol.hasInstance]: (value: unknown) => boolean;
+    /** HTTP status, when there was one. */
+    readonly status?: number;
+    constructor(message: string, opts: {
+        provider: string;
+        code?: string;
+        status?: number;
+        raw?: unknown;
+        cause?: unknown;
+    });
+}
+/** Something is wrong with how the client was constructed or configured. */
+declare class ConfigError extends PaykitError {
+    static [Symbol.hasInstance]: (value: unknown) => boolean;
+    constructor(message: string, opts?: {
+        provider?: string;
+        code?: string;
+    });
+}
+/**
+ * An inbound webhook did not prove it came from the gateway. Never treat the
+ * payload as real after this — it is an unauthenticated stranger's JSON.
+ */
+declare class WebhookVerificationError extends PaykitError {
+    static [Symbol.hasInstance]: (value: unknown) => boolean;
+    constructor(message: string, opts: {
+        provider: string;
+        code?: string;
+        raw?: unknown;
+        cause?: unknown;
+    });
+}
+/**
+ * A local guard stopped a call before it left the process — the refresh-token
+ * budget being the one that matters in practice.
+ */
+declare class RateLimitError extends PaykitError {
+    static [Symbol.hasInstance]: (value: unknown) => boolean;
+    /** Epoch ms when the guard will let the call through. */
+    readonly retryAt?: number;
+    constructor(message: string, opts: {
+        provider: string;
+        code?: string;
+        retryAt?: number;
+    });
+}
+/**
+ * Brand an error class defined outside this module, so a gateway's own error
+ * type takes part in the same `instanceof` scheme.
+ */
+declare function brandCheckFor(tag: string): (value: unknown) => boolean;
+
+export { ConfigError as C, NetworkError as N, ProviderError as P, RateLimitError as R, WebhookVerificationError as W, PaykitError as a, brandCheckFor as b };

package/dist/errors-CleuZfqT.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Every error this library throws is a PaykitError, so a caller can write one
+ * catch block and still tell a declined payment apart from a dead socket.
+ *
+ * `instanceof` is answered from a brand rather than from the prototype chain,
+ * and that is deliberate. This package ships several entry points — `paykit-bd`,
+ * `paykit-bd/bkash`, `paykit-bd/bkash/next` — and each is a separate bundle
+ * carrying its own copy of these classes. A plain `instanceof` compares class
+ * identity, so an error thrown by the bkash client would *not* match the class
+ * imported from the root entry. It would fail silently, which in a payment
+ * library means a customer's declined PIN handled as an unknown error. The
+ * brand also holds when two versions of this package end up installed at once,
+ * or across a worker boundary, where plain `instanceof` fails for the same
+ * reason.
+ */
+declare const BRANDS: unique symbol;
+declare abstract class PaykitError extends Error {
+    static [Symbol.hasInstance]: (value: unknown) => boolean;
+    /** Class lineage, innermost last. Read `instanceof` instead of this. */
+    readonly [BRANDS]: readonly string[];
+    /** Gateway this came from — `"bkash"`, or `"paykit"` for local failures. */
+    readonly provider: string;
+    /** Stable machine-readable code. Gateway codes are passed through verbatim. */
+    readonly code: string;
+    /** True when retrying the identical request could plausibly succeed. */
+    readonly retryable: boolean;
+    /** Untouched gateway response body, for logging. */
+    readonly raw: unknown;
+    protected constructor(message: string, opts: {
+        provider: string;
+        code: string;
+        retryable?: boolean;
+        raw?: unknown;
+        cause?: unknown;
+    }, brands?: readonly string[]);
+    toJSON(): Record<string, unknown>;
+}
+/** The gateway answered, and the answer was an error. `code` is its own code. */
+declare class ProviderError extends PaykitError {
+    static [Symbol.hasInstance]: (value: unknown) => boolean;
+    constructor(message: string, opts: {
+        provider: string;
+        code: string;
+        retryable?: boolean;
+        raw?: unknown;
+        cause?: unknown;
+    }, brands?: readonly string[]);
+}
+/** The request never produced a usable answer: DNS, TLS, timeout, 5xx, bad JSON. */
+declare class NetworkError extends PaykitError {
+    static [Symbol.hasInstance]: (value: unknown) => boolean;
+    /** HTTP status, when there was one. */
+    readonly status?: number;
+    constructor(message: string, opts: {
+        provider: string;
+        code?: string;
+        status?: number;
+        raw?: unknown;
+        cause?: unknown;
+    });
+}
+/** Something is wrong with how the client was constructed or configured. */
+declare class ConfigError extends PaykitError {
+    static [Symbol.hasInstance]: (value: unknown) => boolean;
+    constructor(message: string, opts?: {
+        provider?: string;
+        code?: string;
+    });
+}
+/**
+ * An inbound webhook did not prove it came from the gateway. Never treat the
+ * payload as real after this — it is an unauthenticated stranger's JSON.
+ */
+declare class WebhookVerificationError extends PaykitError {
+    static [Symbol.hasInstance]: (value: unknown) => boolean;
+    constructor(message: string, opts: {
+        provider: string;
+        code?: string;
+        raw?: unknown;
+        cause?: unknown;
+    });
+}
+/**
+ * A local guard stopped a call before it left the process — the refresh-token
+ * budget being the one that matters in practice.
+ */
+declare class RateLimitError extends PaykitError {
+    static [Symbol.hasInstance]: (value: unknown) => boolean;
+    /** Epoch ms when the guard will let the call through. */
+    readonly retryAt?: number;
+    constructor(message: string, opts: {
+        provider: string;
+        code?: string;
+        retryAt?: number;
+    });
+}
+/**
+ * Brand an error class defined outside this module, so a gateway's own error
+ * type takes part in the same `instanceof` scheme.
+ */
+declare function brandCheckFor(tag: string): (value: unknown) => boolean;
+
+export { ConfigError as C, NetworkError as N, ProviderError as P, RateLimitError as R, WebhookVerificationError as W, PaykitError as a, brandCheckFor as b };