@peable.to/sdk 0.1.1 → 0.2.1

package/dist/esm/resources/refunds.js

@@ -0,0 +1,50 @@
+export class RefundsResource {
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * Refund part or all of a payment.
+     *
+     * **`status` is the refund's own lifecycle and it is not always
+     * `succeeded`.** A provider can report a refund `pending` — and a bank can
+     * reject one days later, which arrives as an event and moves the row to
+     * `failed`. Treating the creation as completion is how a merchant's books
+     * come to say money went back that is still with them.
+     *
+     * `paymentStatus` on the response is where the PAYMENT stands after it, so a
+     * caller does not need a second read whose answer can move on before it
+     * arrives.
+     */
+    create(params, options = {}) {
+        return this.client.request('POST', '/v1/refunds', { body: params, idempotencyKey: options.idempotencyKey });
+    }
+    /**
+     * What this payment actually came to — gross, fee, net.
+     *
+     * On this resource because it is the same question you ask in the same
+     * breath: how much of this money is really mine.
+     *
+     * **A missing figure is `null` with a `status`, never `0`.** `unknown` means
+     * there is nothing to read — an uncaptured payment, a FairCoin one, a
+     * provider that could not be reached — and treating it as zero is how a
+     * reconciliation silently gains money that was never there.
+     *
+     * It reports what the provider took. It does NOT say which entity bears that
+     * cost: a fee paid by the operator of a Peable deployment is not
+     * automatically your expense, and that is a commercial question this API does
+     * not answer.
+     */
+    settlement(paymentIntentId) {
+        return this.client.request('GET', `/v1/payment_intents/${encodeURIComponent(paymentIntentId)}/settlement`);
+    }
+    /**
+     * Every refund against one payment, including ones made OUTSIDE Peable.
+     *
+     * A refund issued from the acquirer's dashboard, or created by the network
+     * resolving a dispute, is imported with `origin: 'provider'` and no
+     * `externalRef` — the merchant did not make it and has no id for it.
+     */
+    listForPaymentIntent(paymentIntentId) {
+        return this.client.request('GET', `/v1/payment_intents/${encodeURIComponent(paymentIntentId)}/refunds`);
+    }
+}

package/dist/esm/resources/transfers.js

@@ -0,0 +1,45 @@
+export class TransfersResource {
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * Settle one seller.
+     *
+     * Answers 201 for a new settlement and 200 for an order already settled,
+     * which is the distinction to act on after a timeout: "did I just pay this
+     * seller a second time" is a question with a real answer.
+     *
+     * Refused when the payment cannot fund it — the total settled out of one
+     * payment may not exceed what that payment brought in, because the overflow
+     * would come from the platform's general balance, which is other merchants'
+     * money in flight.
+     */
+    create(params, options = {}) {
+        return this.client.request('POST', '/v1/transfers', { body: params, idempotencyKey: options.idempotencyKey });
+    }
+    /**
+     * Take some or all of a settlement back.
+     *
+     * The response carries the transfer AND the reversal leg, so a caller can
+     * tell which operation it is reading: `amountReversed` on the transfer is the
+     * provider's CUMULATIVE figure, while `reversal` is this one.
+     */
+    reverse(transferId, params, options = {}) {
+        if (params.externalRef === undefined && options.idempotencyKey === undefined) {
+            // Refused HERE rather than at the gateway, because the failure it
+            // prevents is silent: without an identity a retry is a second reversal,
+            // and a seller loses the amount twice with nothing saying so.
+            throw new TypeError('a reversal needs an identity: pass externalRef, or options.idempotencyKey');
+        }
+        return this.client.request('POST', `/v1/transfers/${encodeURIComponent(transferId)}/reversals`, {
+            body: params,
+            ...(options.idempotencyKey === undefined
+                ? {}
+                : { idempotencyKey: options.idempotencyKey }),
+        });
+    }
+    /** What one payment settled — the reconciliation read. */
+    listForPaymentIntent(paymentIntentId) {
+        return this.client.request('GET', `/v1/payment_intents/${encodeURIComponent(paymentIntentId)}/transfers`);
+    }
+}

package/dist/types/browser/mount.d.ts

@@ -14,11 +14,33 @@ export declare function deriveIntentId(clientSecret: string, intentId?: string):
 export interface PayDeepLinkParams {
     intentId: string;
     clientSecret: string;
+    /**
+     * The intent's watch-only receive address. FairCoin rail only — this link is
+     * a chain payment request and there is nothing to put here for a card.
+     */
     address: string;
     /** Base-unit integer string (m⊜) — `PaymentIntent['amount']`'s own shape. */
     amount: string;
-    network: PaymentIntent['network'];
+    network: NonNullable<PaymentIntent['network']>;
 }
+/**
+ * Thrown when a deep link is asked for on an intent that has no chain payment
+ * behind it.
+ *
+ * `address` and `network` became nullable when the card rail landed (gateway
+ * ADR 0001 D6), and the tempting fix was a `?? ''` at the call site. That would
+ * mint `peable://pay?...&address=&network=` — a link the wallet's parser
+ * accepts structurally and which sends a payer to an empty address. Failing
+ * here is the only safe direction.
+ */
+export declare class PeableRailUnsupportedError extends PeableError {
+    constructor(rail: string);
+}
+/**
+ * Build the deep link for an intent, refusing any intent that is not a chain
+ * payment. The narrowing is what lets `buildPayDeepLink` keep non-null fields.
+ */
+export declare function payDeepLinkFor(intent: PaymentIntent): string;
 /**
  * Build an `peable://pay?...` deep link. Param names AND percent-encoding
  * must match the wallet's parser byte-for-byte

package/dist/types/browser/payerClient.d.ts

@@ -1,4 +1,38 @@
 import type { PaymentIntent } from '@peable.to/shared-types';
+/**
+ * Whether updates are actually arriving.
+ *
+ * `'live'` means the socket is connected AND rejoined to this intent's room —
+ * both, because a connected socket in no room delivers nothing and is
+ * indistinguishable from a quiet payment.
+ *
+ * `'lost'` is a report, not a recovery: socket.io keeps retrying the transport
+ * on its own, but it replays NOTHING, so anything emitted during the gap is
+ * gone. A host that wants those updates has to re-read the intent when `'live'`
+ * comes back.
+ */
+export type RealtimeConnectionState = 'live' | 'lost';
+/**
+ * What the payer's client has to do next — the RESUME capability.
+ *
+ * The payment-intent DTO deliberately carries no confirmation credential, so a
+ * payer who refreshed the page, came back from an SCA challenge in a new tab,
+ * or returned the next day had nothing to pay WITH. This is the one call that
+ * hands one out, bounded to a single payment the caller has proven they may
+ * pay.
+ *
+ * `value` is opaque and provider-specific; `publishableKey` is the provider's
+ * public key, served here rather than compiled into a checkout bundle — that
+ * page is deployed once and serves whichever gateway it is pointed at, so a
+ * baked-in key would be the wrong mode the first time a test deployment used
+ * the same page.
+ */
+export interface PeableClientAction {
+    readonly object: 'client_action';
+    readonly kind: 'client_secret' | 'redirect';
+    readonly value: string;
+    readonly publishableKey?: string;
+}
 export interface PeableCheckoutClient {
     /**
      * `GET /v1/payment_intents/:id` — the initial REST snapshot. Sends
@@ -6,12 +40,32 @@ export interface PeableCheckoutClient {
      * param, so the capability token never lands in server/CDN access logs.
      */
     getPaymentIntent(id: string, clientSecret: string): Promise<PaymentIntent>;
-    /** Realtime status stream over the Gateway's socket contract, filtered to this intent. */
-    subscribe(id: string, clientSecret: string, onUpdate: (intent: PaymentIntent) => void): Promise<{
+    /**
+     * Realtime status stream over the Gateway's socket contract, filtered to this
+     * intent.
+     *
+     * `onConnectionChange` is optional and additive: it reports drops and
+     * recoveries AFTER this promise resolves, which nothing could observe before.
+     * A caller that omits it behaves exactly as it did.
+     */
+    subscribe(id: string, clientSecret: string, onUpdate: (intent: PaymentIntent) => void, onConnectionChange?: (state: RealtimeConnectionState) => void): Promise<{
         unsubscribe(): void;
     }>;
     /** `POST /v1/payment_intents/:id/submit_tx` — report a broadcast txid. */
     submitTx(id: string, clientSecret: string, txid: string): Promise<PaymentIntent>;
+    /**
+     * `POST /v1/payment_intents/:id/client_action` — what to pay WITH.
+     *
+     * A POST, and not a field on `getPaymentIntent`, because the answer is a
+     * credential: a GET response is cacheable by anything in front of it and its
+     * path lands in access logs, while `getPaymentIntent` is the call a checkout
+     * page POLLS.
+     *
+     * @throws {PeableInvalidRequestError} when the payment can no longer be paid
+     *   — a settled, expired or rejected payment has no next step, and a page
+     *   handed one would render a card form over a finished payment.
+     */
+    getClientAction(id: string, clientSecret: string): Promise<PeableClientAction>;
 }
 export interface CreatePeableCheckoutOptions {
     /** Gateway base URL. Default `https://api.peable.to`. */

package/dist/types/checkout.d.ts

@@ -1,2 +1,3 @@
-export { createPeableCheckout, type CreatePeableCheckoutOptions, type PeableCheckoutClient, } from './browser/payerClient';
+export { createPeableCheckout, type CreatePeableCheckoutOptions, type PeableCheckoutClient, type PeableClientAction, type RealtimeConnectionState, } from './browser/payerClient';
 export { PeableCheckout, type PeableCheckoutMountOptions, type PeableCheckoutInstance, type PeableCheckoutEventMap, } from './browser/mount';
+export { payDeepLinkFor, buildPayDeepLink, type PayDeepLinkParams, PeableRailUnsupportedError, } from './browser/mount';

package/dist/types/core/client.d.ts

@@ -11,6 +11,7 @@ export interface RestClient {
 export interface RestClientConfig {
     /** Gateway base URL, already stripped of a trailing slash. */
     baseURL: string;
+    requestTimeoutMs?: number;
 }
 export declare function createRestClient(config: RestClientConfig, tokenProvider: ServiceTokenProvider, deps?: {
     fetch?: typeof fetch;

package/dist/types/core/config.d.ts

@@ -13,6 +13,8 @@ export interface PeableConfig {
     baseURL?: string;
     /** oxy-api host used to mint the service token. Default `https://api.oxy.so`. */
     oxyApiUrl?: string;
+    /** Optional deadline per HTTP attempt, including body consumption. */
+    requestTimeoutMs?: number;
 }
 /** `PeableConfig` with every optional field defaulted and normalized. */
 export interface ResolvedPeableConfig {
@@ -20,7 +22,9 @@ export interface ResolvedPeableConfig {
     secret: string;
     baseURL: string;
     oxyApiUrl: string;
+    requestTimeoutMs?: number;
 }
+export declare function resolveRequestTimeout(value: number | undefined): number | undefined;
 /**
  * Validate and normalize an `PeableConfig`. Throws a plain `Error` for a
  * missing `publicKey`/`secret` — a programmer error caught at construction

package/dist/types/core/errors.d.ts

@@ -5,7 +5,7 @@ export interface PeableErrorDetails {
     /**
      * The raw upstream discriminator: `error.type` from the Gateway's own
      * `{ error: { type, message } }` envelope, or the flat `error` code string
-     * from `@oxyhq/core`'s auth middleware (`{ error: 'INVALID_TOKEN', ... }`)
+     * from `@oxy.so/core`'s auth middleware (`{ error: 'INVALID_TOKEN', ... }`)
      * — see `errorFromResponse`'s doc comment for why both shapes exist.
      */
     code?: string;
@@ -39,7 +39,7 @@ export declare class PeableSignatureVerificationError extends PeableError {
  * request was rejected:
  * - The Gateway's own route handlers use the Stripe-style nested envelope
  *   `{ error: { type, message } }` (`lib/http.ts`'s `sendError`).
- * - `@oxyhq/core`'s Express auth middleware (`oxyClient.serviceAuth()` /
+ * - `@oxy.so/core`'s Express auth middleware (`oxy.middleware.service()` /
  *   `requireScope()` — rejecting a missing/expired/insufficiently-scoped
  *   service token BEFORE a route handler ever runs) and oxy-api's own
  *   `ApiError.toJSON()` use a FLAT envelope: `{ error: <CODE_STRING>,

package/dist/types/index.d.ts

@@ -1,13 +1,47 @@
+import { BillingResource } from './resources/billing';
+export type { BillingRequestOptions } from './resources/billing';
+export type { BillingCustomer, BillingHostedSession, BillingSubscription, CreateBillingCheckoutParams, CreateBillingPortalParams, EnsureBillingCustomerParams } from '@peable.to/shared-types';
 import { type PeableConfig } from './core/config';
 import { PaymentIntentsResource } from './resources/paymentIntents';
 import { PaymentLinksResource } from './resources/paymentLinks';
 import { CheckoutResource } from './resources/checkoutSessions';
 import { WebhooksResource } from './resources/webhooks';
+import { ConnectedAccountsResource } from './resources/connectedAccounts';
+import { DisputesResource, MerchantsResource } from './resources/merchants';
+import { RefundsResource } from './resources/refunds';
+import { TransfersResource } from './resources/transfers';
+/**
+ * The merchant-authed client.
+ *
+ * ## Why the namespaces below are not optional extras
+ *
+ * This class published four: intents, links, checkout and webhooks. The gateway
+ * has always served merchants, connected accounts, refunds, transfers and
+ * disputes as well — so every integrator reaching those wrote their own HTTP
+ * client and their own partial types for responses this package already knew.
+ * Mercaria did exactly that. Two descriptions of one wire format, in two
+ * repositories, with nothing comparing them: a field renamed in the gateway is
+ * a runtime failure over there, found by a settlement that does not happen.
+ *
+ * An SDK that covers less than the API it wraps does not reduce surface, it
+ * relocates it.
+ */
 export declare class Peable {
+    readonly billing: BillingResource;
     readonly paymentIntents: PaymentIntentsResource;
     readonly paymentLinks: PaymentLinksResource;
     readonly checkout: CheckoutResource;
     readonly webhooks: WebhooksResource;
+    /** The merchant this credential speaks for. Resolved from the credential. */
+    readonly merchants: MerchantsResource;
+    /** Sellers a marketplace onboards, and their readiness. */
+    readonly connectedAccounts: ConnectedAccountsResource;
+    /** Money going back to a payer. */
+    readonly refunds: RefundsResource;
+    /** Money going out to a seller, and coming back from one. */
+    readonly transfers: TransfersResource;
+    /** Read-only: the network initiates these. */
+    readonly disputes: DisputesResource;
     constructor(config: PeableConfig);
 }
 export type { PeableConfig, ResolvedPeableConfig } from './core/config';
@@ -16,7 +50,12 @@ export { PeableError, PeableAuthenticationError, PeableInvalidRequestError, Peab
 export type { PeableErrorType, PeableErrorDetails } from './core/errors';
 export type { RestClient, RestClientRequestOptions } from './core/client';
 export type { ServiceTokenProvider } from './core/serviceToken';
-export type { CreatePaymentIntentOptions, PaymentIntentListParams, PaymentIntentList, } from './resources/paymentIntents';
+export type { CreateCheckoutSessionOptions } from './resources/checkoutSessions';
+export type { CreatePaymentIntentOptions, PaymentIntentClientAction, PaymentIntentListParams, PaymentIntentList, } from './resources/paymentIntents';
+export type { AccountLink, AccountLinkParams, ConnectedAccountList, ConnectedAccountListParams, CreateConnectedAccountParams, } from './resources/connectedAccounts';
+export type { DisputeEvidenceParams, DisputeList, RegisterMerchantParams, UpdateMerchantParams, } from './resources/merchants';
+export type { CreateRefundParams, RefundList } from './resources/refunds';
+export type { CreateTransferParams, ReverseTransferParams, TransferList, } from './resources/transfers';
 export type { PaymentLinkListParams, PaymentLinkList, UpdatePaymentLinkParams, } from './resources/paymentLinks';
 export { WEBHOOK_SIGNATURE_HEADER } from './resources/webhooks';
 export type { ConstructEventOptions } from './resources/webhooks';

package/dist/types/resources/billing.d.ts

@@ -0,0 +1,15 @@
+import type { BillingCustomer, BillingHostedSession, BillingSubscription, CreateBillingCheckoutParams, CreateBillingPortalParams, EnsureBillingCustomerParams } from '@peable.to/shared-types';
+import type { RestClient } from '../core/client';
+export interface BillingRequestOptions {
+    idempotencyKey: string;
+}
+/** Recurring billing is separate from one-off checkout and marketplace transfers. */
+export declare class BillingResource {
+    private readonly client;
+    constructor(client: RestClient);
+    ensureCustomer(params: EnsureBillingCustomerParams, options: BillingRequestOptions): Promise<BillingCustomer>;
+    createCheckoutSession(params: CreateBillingCheckoutParams, options: BillingRequestOptions): Promise<BillingHostedSession>;
+    createPortalSession(params: CreateBillingPortalParams, options: BillingRequestOptions): Promise<BillingHostedSession>;
+    retrieveSubscription(ref: string): Promise<BillingSubscription>;
+    cancelAtPeriodEnd(ref: string, options: BillingRequestOptions): Promise<BillingSubscription>;
+}

package/dist/types/resources/checkoutSessions.d.ts

@@ -1,9 +1,23 @@
 import type { CheckoutSession, CreateCheckoutSessionParams } from '@peable.to/shared-types';
 import type { RestClient } from '../core/client';
+export interface CreateCheckoutSessionOptions {
+    /**
+     * Sent as `Idempotency-Key`. A create that timed out does not tell the caller
+     * whether the session exists; retrying with the SAME key returns the session
+     * that create made (HTTP 200) instead of minting a second one and a second
+     * payment intent, and the same key with different parameters is refused with
+     * a 409 (`PeableInvalidRequestError`). Use one stable key per order, not one
+     * per attempt.
+     *
+     * Optional, because the gateway has never required it on this route — but an
+     * integration without it can create two live checkouts for one order.
+     */
+    idempotencyKey?: string;
+}
 export declare class CheckoutSessionsResource {
     private readonly client;
     constructor(client: RestClient);
-    create(params: CreateCheckoutSessionParams): Promise<CheckoutSession>;
+    create(params: CreateCheckoutSessionParams, options?: CreateCheckoutSessionOptions): Promise<CheckoutSession>;
     retrieve(id: string): Promise<CheckoutSession>;
 }
 /** `peable.checkout.sessions.*` — a thin namespace wrapper so the public API

package/dist/types/resources/connectedAccounts.d.ts

@@ -0,0 +1,84 @@
+import type { ConnectedAccount } from '@peable.to/shared-types';
+import type { RestClient } from '../core/client';
+/**
+ * Sellers a marketplace onboards through Peable.
+ *
+ * The provider's own account id is not on any of these shapes, and never will
+ * be (ADR 0001 D3): a merchant integrates against Peable and does not learn
+ * which acquirer sits behind their seller, because the day that changes should
+ * be a Peable deploy and not a merchant migration.
+ *
+ * Every account is addressed by the merchant's OWN reference as well as by its
+ * `ca_…`. That is deliberate and it is what makes recovery possible: a create
+ * whose response never arrived leaves the merchant without the `ca_…` and still
+ * holding the reference they chose.
+ */
+export interface CreateConnectedAccountParams {
+    /** The merchant's own id for this seller. The idempotency, and durable. */
+    externalRef: string;
+    /** ISO 3166-1 alpha-2. Case-insensitive; the gateway upper-cases it. */
+    country: string;
+    businessType: 'individual' | 'company';
+}
+export interface ConnectedAccountListParams {
+    limit?: number;
+    /** A `ca_…` from a previous page — the gateway resolves it, scoped to you. */
+    starting_after?: string;
+}
+export interface ConnectedAccountList {
+    object: 'list';
+    data: ConnectedAccount[];
+    has_more: boolean;
+}
+export interface AccountLinkParams {
+    /** Where the provider sends a seller whose link expired mid-flow. */
+    refreshUrl: string;
+    returnUrl: string;
+}
+export interface AccountLink {
+    object: 'account_link';
+    url: string;
+    expiresAt: string;
+}
+export declare class ConnectedAccountsResource {
+    private readonly client;
+    constructor(client: RestClient);
+    /**
+     * Open the account for a seller, or return the one they already have.
+     *
+     * Converges rather than erroring, because the underlying object CANNOT BE
+     * DELETED: opening two for one seller leaves them with two forever, one of
+     * which nobody uses and which keeps generating requirement emails.
+     */
+    create(params: CreateConnectedAccountParams): Promise<ConnectedAccount>;
+    list(params?: ConnectedAccountListParams): Promise<ConnectedAccountList>;
+    retrieve(accountId: string): Promise<ConnectedAccount>;
+    /**
+     * By the merchant's OWN reference.
+     *
+     * The recovery read: a merchant who lost the `ca_…` — a create whose response
+     * never arrived — still has the reference they chose, and this is what makes
+     * finding the account possible without a list scan.
+     */
+    retrieveByRef(externalRef: string): Promise<ConnectedAccount>;
+    /**
+     * Re-read this account from the provider now.
+     *
+     * Rarely needed: readiness arrives on its own through the gateway's event
+     * drain and a backstop sweep. This is for a seller staring at a dashboard who
+     * has just finished onboarding.
+     */
+    refresh(accountId: string): Promise<ConnectedAccount>;
+    /**
+     * A hosted onboarding link.
+     *
+     * SINGLE-USE and short-lived at the provider, so it is minted on demand and
+     * must never be stored, emailed or put in a chat message — a stored link is
+     * one that has already expired by the time anyone follows it, and the failure
+     * looks like the seller's fault.
+     *
+     * A visit to `returnUrl` proves NOTHING about verification. Read the account
+     * back, or wait for the readiness event.
+     */
+    createAccountLink(accountId: string, params: AccountLinkParams): Promise<AccountLink>;
+}

package/dist/types/resources/merchants.d.ts

@@ -0,0 +1,113 @@
+import type { Dispute, DisputeEvidence, Merchant } from '@peable.to/shared-types';
+import type { RestClient } from '../core/client';
+/**
+ * The merchant this credential speaks for, and the disputes raised against it.
+ *
+ * ## One merchant per application PER ENVIRONMENT
+ *
+ * There is no merchant id in any of these calls. The gateway resolves the
+ * merchant from the credential — its Oxy application AND that credential's
+ * environment — so a development credential and a production one address
+ * different merchants and cannot be made to address each other's.
+ *
+ * ## The FairCoin half is optional
+ *
+ * `network` and `xpub` are two halves of ONE capability and are supplied
+ * together or not at all. A merchant that only takes cards registers with
+ * neither; supplying a watch-only key for a chain they never intend to use
+ * would mean custodying a real key or, worse, registering a fixture that
+ * silently makes their receive addresses underivable by their own wallet.
+ *
+ * Peable never accepts a PRIVATE extended key. The gateway derives a child from
+ * whatever it is given and refuses anything that can spend — that refusal is
+ * the non-custody firewall, not a validation nicety.
+ */
+export interface RegisterMerchantParams {
+    /** Both, or neither. Omit both for a card-only merchant. */
+    network?: 'mainnet' | 'testnet';
+    /** A WATCH-ONLY account extended public key. An `xprv` is refused. */
+    xpub?: string;
+    webhookUrl?: string;
+    webhookSecret?: string;
+    requiredConfirmations?: number;
+    displayName?: string;
+    /** A bare Oxy file id, never a URL. */
+    avatarFileId?: string;
+    description?: string;
+}
+/**
+ * `null` CLEARS a field; omitting it leaves it alone.
+ *
+ * The distinction is by `undefined` rather than by falsiness, so a webhook URL
+ * can be removed rather than only replaced.
+ */
+export interface UpdateMerchantParams {
+    webhookUrl?: string | null;
+    webhookSecret?: string | null;
+    requiredConfirmations?: number;
+    displayName?: string | null;
+    avatarFileId?: string | null;
+    description?: string | null;
+}
+export interface DisputeList {
+    object: 'list';
+    data: Dispute[];
+}
+export declare class MerchantsResource {
+    private readonly client;
+    constructor(client: RestClient);
+    register(params?: RegisterMerchantParams): Promise<Merchant>;
+    retrieve(): Promise<Merchant>;
+    update(params: UpdateMerchantParams): Promise<Merchant>;
+}
+/**
+ * Evidence — TEXT only, in the gateway's field names.
+ *
+ * Every field is your own words or your own record. They are forwarded to the
+ * card network and **never stored by Peable**: they carry a customer's name,
+ * their email, a billing address and correspondence, and the gateway keeps none
+ * of that. What it records is THAT you responded and when.
+ *
+ * FILE attachments are not supported. They need the acquirer's upload API and a
+ * policy for the bytes on the way through; offering half of it would let you
+ * submit — finally — a defence missing the receipt it rests on.
+ *
+ * An unknown key is REFUSED rather than dropped, so a misspelled field is a 422
+ * now instead of a missing argument discovered when the dispute is decided.
+ */
+/**
+ * The evidence set, re-exported from the wire contract rather than restated.
+ *
+ * It was written out here as well as in the gateway's provider port, its route
+ * schema and its Stripe adapter — four copies of one list. A field added to
+ * three of them is a field you send, the gateway accepts, and the network never
+ * sees; you would find out when the dispute is decided against you.
+ */
+export type DisputeEvidenceParams = DisputeEvidence;
+/**
+ * Disputes: read them, and answer one.
+ *
+ * A dispute is initiated by the card NETWORK, not by you, so there is nothing
+ * to create — the only write is a response. This surface was read-only for a
+ * while, because the gateway had no way to deliver evidence and a route that
+ * accepted it and did nothing would have been worse than none: you would have
+ * believed you had responded.
+ */
+export declare class DisputesResource {
+    private readonly client;
+    constructor(client: RestClient);
+    listForPaymentIntent(paymentIntentId: string): Promise<DisputeList>;
+    /**
+     * Answer a dispute. **One shot.**
+     *
+     * Submitting is one-way at the card network, so this cannot be revised and a
+     * second call does not send a second response — it answers 200 with the
+     * dispute as it stands. Send everything you have the first time.
+     *
+     * Refused (409) when the dispute is already answered, already decided, or
+     * past `evidenceDueAt`. That last one is checked by the gateway rather than
+     * by the acquirer, so you learn it was the clock and not your request — a
+     * late response is the one failure here that no retry fixes.
+     */
+    submitEvidence(disputeId: string, evidence: DisputeEvidenceParams): Promise<Dispute>;
+}

package/dist/types/resources/paymentIntents.d.ts

@@ -10,6 +10,24 @@ export interface PaymentIntentList {
     data: PaymentIntent[];
     has_more: boolean;
 }
+/**
+ * The payer's next step, as the gateway reports it.
+ *
+ * `value` is opaque and provider-specific — a confirmation credential or a
+ * redirect target. Do not store it, do not log it, and do not put it in a URL:
+ * it is a capability over the payment at the acquirer, and it is read live from
+ * the provider precisely so nothing here has to keep one.
+ *
+ * `publishableKey` is the provider's PUBLIC key, served here rather than
+ * configured in the client, so a page that talks to more than one deployment
+ * cannot mount a live card form over a test payment.
+ */
+export interface PaymentIntentClientAction {
+    object: 'client_action';
+    kind: 'client_secret' | 'redirect';
+    value: string;
+    publishableKey?: string;
+}
 export interface CreatePaymentIntentOptions {
     /**
      * Required — the Gateway mandates the `Idempotency-Key` header on
@@ -25,5 +43,33 @@ export declare class PaymentIntentsResource {
     create(params: CreatePaymentIntentParams, options: CreatePaymentIntentOptions): Promise<PaymentIntent>;
     retrieve(id: string): Promise<PaymentIntent>;
     list(params?: PaymentIntentListParams): Promise<PaymentIntentList>;
-    reject(id: string): Promise<PaymentIntent>;
+    /**
+     * Reject a payment the payer has not completed.
+     *
+     * The gateway CANCELS it at the provider before it announces anything, so
+     * this can lose a race and say so: a 409 means the payer confirmed first and
+     * the payment is settled, and a 502 means the provider could not be reached
+     * and nothing was decided. Neither is a failure of the request — both are
+     * facts about a payment that is still live.
+     */
+    reject(id: string, options?: {
+        idempotencyKey?: string;
+    }): Promise<PaymentIntent>;
+    /**
+     * What the PAYER's client has to do next — the resume operation.
+     *
+     * The payment-intent shape carries no confirmation credential, because a
+     * credential on that shape would be handed out by every list and every
+     * re-read. This is the bounded way to get one: a single payment, named
+     * explicitly, for a caller who has proven they may pay it.
+     *
+     * Call it to resume an unpaid checkout rather than creating a second payment
+     * — which is what a buyer returning the next day would otherwise produce, and
+     * an idempotency key that has aged out at the provider will not prevent.
+     *
+     * @throws {PeableInvalidRequestError} (409) when the payment can no longer be
+     *   paid, so a surface handed this can never render a card form over a
+     *   settled payment.
+     */
+    clientAction(id: string): Promise<PaymentIntentClientAction>;
 }