@peable.to/sdk 0.1.1 → 0.2.0

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/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,31 @@ export declare class PaymentIntentsResource {
     create(params: CreatePaymentIntentParams, options: CreatePaymentIntentOptions): Promise<PaymentIntent>;
     retrieve(id: string): Promise<PaymentIntent>;
     list(params?: PaymentIntentListParams): Promise<PaymentIntentList>;
+    /**
+     * 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): 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>;
 }

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

@@ -0,0 +1,75 @@
+import type { Refund, Settlement } from '@peable.to/shared-types';
+import type { RestClient } from '../core/client';
+/**
+ * Sending money back to a payer.
+ *
+ * The one operation on this API whose duplicate is unrecoverable: a payer sent
+ * their money twice has no reason to report it, and nothing reverses the second
+ * automatically. `externalRef` — your own refund id — is what every path here
+ * converges on, and unlike a header key you cannot lose it.
+ */
+export interface CreateRefundParams {
+    /** The `pi_…` being refunded. */
+    paymentIntentId: string;
+    /** YOUR id for this refund. The idempotency. */
+    externalRef: string;
+    /** Minor units, as a canonical integer string. Zero is refused. */
+    amount: string;
+}
+export interface RefundList {
+    object: 'list';
+    data: Refund[];
+    /**
+     * What can still go back, in minor units.
+     *
+     * Offered because otherwise every integrator computes it by summing the list
+     * — and the ones who forget that a `pending` or `failed` refund moved no
+     * money compute it wrong, in the direction that refuses a legitimate refund.
+     * It reserves PENDING refunds, which is what stops two concurrent ones
+     * between them exceeding the payment.
+     */
+    remainingRefundable: string;
+}
+export declare class RefundsResource {
+    private readonly client;
+    constructor(client: RestClient);
+    /**
+     * 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: CreateRefundParams): Promise<Refund>;
+    /**
+     * 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: string): Promise<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: string): Promise<RefundList>;
+}

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

@@ -0,0 +1,73 @@
+import type { Transfer, TransferWithReversal } from '@peable.to/shared-types';
+import type { RestClient } from '../core/client';
+/**
+ * Settling a seller out of a funded payment, and taking it back.
+ *
+ * Two rules govern this whole surface and neither is negotiable:
+ *
+ * 1. **The amount comes from you.** Peable does not compute a marketplace's
+ *    split and must never learn its fee schedule; it records that a stated
+ *    amount was moved. A gateway that computed the split would be a second
+ *    definition of it.
+ * 2. **Your own id is the idempotency.** `externalRef` is your order id, and
+ *    unlike a header key you cannot lose it — a retried settlement converges on
+ *    it rather than paying a seller twice.
+ */
+export interface CreateTransferParams {
+    /** The `pi_…` this settles out of. Must be a SETTLED payment. */
+    paymentIntentId: string;
+    /** Name the seller by exactly one of these. */
+    connectedAccountId?: string;
+    connectedAccountRef?: string;
+    /** YOUR id for what this settles. The idempotency, and it is durable. */
+    externalRef: string;
+    /** Minor units, as a canonical integer string. In the payment's currency. */
+    amount: string;
+}
+export interface ReverseTransferParams {
+    amount: string;
+    /**
+     * YOUR id for THIS reversal — required, one way or the other.
+     *
+     * Supply it here, or as `options.idempotencyKey`, which the gateway accepts
+     * as the same identity. It cannot be omitted, and an AMOUNT IS NOT AN
+     * IDENTITY: two reversals of one settlement for the same amount are two
+     * distinct operations, and a gateway that keyed them by amount would answer
+     * the first one to the second request — leaving a seller holding money that
+     * had been taken back, with nothing recording that it was asked for.
+     */
+    externalRef?: string;
+}
+export interface TransferList {
+    object: 'list';
+    data: Transfer[];
+}
+export declare class TransfersResource {
+    private readonly client;
+    constructor(client: RestClient);
+    /**
+     * 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: CreateTransferParams): Promise<Transfer>;
+    /**
+     * 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: string, params: ReverseTransferParams, options?: {
+        idempotencyKey?: string;
+    }): Promise<TransferWithReversal>;
+    /** What one payment settled — the reconciliation read. */
+    listForPaymentIntent(paymentIntentId: string): Promise<TransferList>;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peable.to/sdk",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Peable SDK — a Stripe-ergonomics TypeScript client over the Peable Gateway REST + realtime contract. Server entry (`@peable.to/sdk`) mints Oxy service tokens from an ApplicationCredential and exposes paymentIntents/paymentLinks/checkout.sessions/webhooks; browser entry (`@peable.to/sdk/checkout`) is the anonymous payer-side client core.",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -71,7 +71,7 @@
     "prepublishOnly": "bun run clean && bun run build"
   },
   "dependencies": {
-    "@peable.to/shared-types": "workspace:^",
+    "@peable.to/shared-types": "^0.3.0",
     "qrcode-generator": "^2.0.4",
     "socket.io-client": "^4.8.3"
   },