@peable.to/sdk 0.1.1 → 0.2.0

package/dist/cjs/browser/mount.js

@@ -3,8 +3,9 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PeableCheckout = void 0;
+exports.PeableCheckout = exports.PeableRailUnsupportedError = void 0;
 exports.deriveIntentId = deriveIntentId;
+exports.payDeepLinkFor = payDeepLinkFor;
 exports.buildPayDeepLink = buildPayDeepLink;
 exports.isMobileUserAgent = isMobileUserAgent;
 exports.createEmitter = createEmitter;
@@ -60,6 +61,47 @@ function deriveIntentId(clientSecret, intentId) {
 /** The `peable://pay` deep-link scheme + host — mirrors `PAYMENT_REQUEST_PREFIX`
  * in the wallet's `packages/frontend/src/pay/payment-request.ts`. */
 const PAYMENT_REQUEST_PREFIX = 'peable://pay';
+/**
+ * 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.
+ */
+class PeableRailUnsupportedError extends errors_1.PeableError {
+    constructor(rail) {
+        // Extends `PeableError`, not `Error`: the widget reports everything through
+        // its `error` event, whose payload type is `PeableError`, and a bare `Error`
+        // would arrive there only after being flattened into a `PeableApiError`
+        // that a caller cannot tell apart from a network failure.
+        // `invalid_request_error`, because that is what it is: the caller asked
+        // this widget for a surface the intent does not have. Nothing went wrong
+        // upstream and retrying cannot help.
+        super('invalid_request_error', `the '${rail}' rail has no wallet deep link; it is not a chain payment`);
+        this.name = 'PeableRailUnsupportedError';
+        Object.setPrototypeOf(this, PeableRailUnsupportedError.prototype);
+    }
+}
+exports.PeableRailUnsupportedError = PeableRailUnsupportedError;
+/**
+ * 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.
+ */
+function payDeepLinkFor(intent) {
+    if (intent.rail !== 'faircoin' || intent.address === null || intent.network === null) {
+        throw new PeableRailUnsupportedError(intent.rail);
+    }
+    return buildPayDeepLink({
+        intentId: intent.id,
+        clientSecret: intent.clientSecret,
+        address: intent.address,
+        amount: intent.amount,
+        network: intent.network,
+    });
+}
 /**
  * Build an `peable://pay?...` deep link. Param names AND percent-encoding
  * must match the wallet's parser byte-for-byte
@@ -251,13 +293,18 @@ function mount(target, opts) {
     button.addEventListener('click', () => {
         if (!latestIntent)
             return; // initial snapshot hasn't loaded yet
-        const deepLink = buildPayDeepLink({
-            intentId,
-            clientSecret,
-            address: latestIntent.address,
-            amount: latestIntent.amount,
-            network: latestIntent.network,
-        });
+        // A card intent has no wallet to deep-link into. `error` rather than a
+        // throw into an event handler nobody is listening to: this widget's whole
+        // contract is that a host page learns what happened through `on(...)`, and
+        // an uncaught exception here would leave the button silently dead.
+        let deepLink;
+        try {
+            deepLink = payDeepLinkFor(latestIntent);
+        }
+        catch (err) {
+            emitter.emit('error', toPeableError(err));
+            return;
+        }
         if (isMobileUserAgent(navigator.userAgent)) {
             window.location.href = deepLink;
         }

package/dist/cjs/browser/payerClient.js

@@ -4,7 +4,7 @@ exports.createPeableCheckout = createPeableCheckout;
 // The payer-side REST+socket client core — the "./checkout" entry's payer
 // capability (Fase 2 SDK plan, Task 5). Mirrors the wallet's
 // `gateway-client.ts`/`gateway-socket.ts` but standalone: no
-// `@oxyhq/services`/`@oxyhq/core` — this is a third-party browser bundle, so
+// `@oxy.so/services`/`@oxy.so/core` — this is a third-party browser bundle, so
 // it talks to the Gateway over bare `fetch` + `socket.io-client`.
 //
 // Holds NO service token and NO private key — only a public `client_secret`,
@@ -65,6 +65,25 @@ function createPeableCheckout(opts = {}) {
             throw (0, errors_1.errorFromResponse)(response.status, body);
         return body;
     }
+    async function getClientAction(id, clientSecret) {
+        let response;
+        try {
+            response = await fetch(`${baseUrl}/v1/payment_intents/${encodeURIComponent(id)}/client_action`, {
+                method: 'POST',
+                // The HEADER, never a query param, for the same reason the snapshot
+                // read uses one: a capability token in a URL lands in every access
+                // log between here and the gateway.
+                headers: { 'X-Peable-Client-Secret': clientSecret },
+            });
+        }
+        catch (cause) {
+            throw new errors_1.PeableApiError(`Failed to reach the Peable Gateway at ${baseUrl}: ${cause instanceof Error ? cause.message : String(cause)}`);
+        }
+        const body = await readJsonBody(response);
+        if (!response.ok)
+            throw (0, errors_1.errorFromResponse)(response.status, body);
+        return body;
+    }
     /**
      * Opens its OWN socket per call (never a shared/module-level connection —
      * this SDK has no session to key a singleton off) and connects with NO
@@ -74,7 +93,7 @@ function createPeableCheckout(opts = {}) {
      * the real authorization check — it requires this intent's `client_secret`
      * — so nothing here needs an Oxy session.
      */
-    async function subscribe(id, clientSecret, onUpdate) {
+    async function subscribe(id, clientSecret, onUpdate, onConnectionChange) {
         const socket = (0, socket_io_client_1.io)(baseUrl, {
             transports: ['websocket'],
         });
@@ -105,6 +124,22 @@ function createPeableCheckout(opts = {}) {
             }
         };
         socket.on('intent.updated', listener);
+        // A drop AFTER this point used to be invisible to the caller. `subscribe`
+        // had already resolved, so a `.catch` on it could not fire again, and the
+        // reconnect below restores DELIVERY but replays nothing — socket.io has no
+        // buffer for frames emitted while the socket was gone. A payment that
+        // settled during a thirty-second blip therefore never reached the page, and
+        // the payer watched a snapshot that would never update again.
+        //
+        // Reported rather than handled here: the SDK cannot know what a host wants
+        // to do about it. The hosted checkout turns REST polling on and re-reads
+        // the intent before turning it off again.
+        let closedByUs = false;
+        const onDisconnect = () => {
+            if (!closedByUs)
+                onConnectionChange?.('lost');
+        };
+        socket.on('disconnect', onDisconnect);
         // socket.io-client's default reconnection restores the TRANSPORT, but the
         // server spins up a fresh Socket with no room membership — so every
         // reconnect (mobile network blip, backgrounded tab, LB cycle) must re-run
@@ -115,21 +150,36 @@ function createPeableCheckout(opts = {}) {
         // the user reopening the screen. `reconnect` is a Manager-level event
         // (`socket.io`, not `socket` itself) in socket.io-client.
         const onReconnect = () => {
-            void socket.emitWithAck('subscribe', { intentId: id, clientSecret }).catch(() => {
-                // Fire-and-forget: `onUpdate` has no error channel to surface a
-                // failed resubscribe (e.g. the intent expired between drop and
-                // reconnect) — socket.io keeps retrying the transport regardless, so
-                // there is nothing actionable to do with this rejection here.
+            void socket
+                .emitWithAck('subscribe', { intentId: id, clientSecret })
+                .then((ack) => {
+                // `'live'` only once the ROOM is rejoined, never on the transport
+                // alone: a socket that is connected and in no room delivers nothing,
+                // and telling the host it is live there would have them stand their
+                // fallback down into permanent silence.
+                if (ack.ok)
+                    onConnectionChange?.('live');
+            })
+                .catch(() => {
+                // The subscription is gone for good (the intent expired between drop
+                // and reconnect, say). Staying `lost` is the honest report: socket.io
+                // keeps retrying the transport, but nothing will arrive on it.
             });
         };
         socket.io.on('reconnect', onReconnect);
         return {
             unsubscribe() {
+                // Set BEFORE `disconnect()`: a deliberate close fires `disconnect` like
+                // any other, and reporting `'lost'` there would have a host spin up a
+                // fallback for a subscription it just tore down — on an unmounting
+                // component, at that.
+                closedByUs = true;
                 socket.off('intent.updated', listener);
+                socket.off('disconnect', onDisconnect);
                 socket.io.off('reconnect', onReconnect);
                 socket.disconnect();
             },
         };
     }
-    return { getPaymentIntent, subscribe, submitTx };
+    return { getPaymentIntent, subscribe, submitTx, getClientAction };
 }

package/dist/cjs/checkout.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PeableCheckout = exports.createPeableCheckout = void 0;
+exports.PeableRailUnsupportedError = exports.buildPayDeepLink = exports.payDeepLinkFor = exports.PeableCheckout = exports.createPeableCheckout = void 0;
 // Browser entry (`@peable.to/sdk/checkout`) — the anonymous payer-side client
 // core (Task 5) plus the embeddable pay-button widget (Task 6). Deliberately
 // imports nothing from `./core/*` beyond `core/errors.ts` (a pure
@@ -15,3 +15,11 @@ var payerClient_1 = require("./browser/payerClient");
 Object.defineProperty(exports, "createPeableCheckout", { enumerable: true, get: function () { return payerClient_1.createPeableCheckout; } });
 var mount_1 = require("./browser/mount");
 Object.defineProperty(exports, "PeableCheckout", { enumerable: true, get: function () { return mount_1.PeableCheckout; } });
+// The rail-aware deep-link builder and its refusal. Exported because
+// `packages/checkout` renders its own pay button over the payer client core
+// and must make the same decision this widget makes — one definition of "which
+// intents have a wallet deep link", not two.
+var mount_2 = require("./browser/mount");
+Object.defineProperty(exports, "payDeepLinkFor", { enumerable: true, get: function () { return mount_2.payDeepLinkFor; } });
+Object.defineProperty(exports, "buildPayDeepLink", { enumerable: true, get: function () { return mount_2.buildPayDeepLink; } });
+Object.defineProperty(exports, "PeableRailUnsupportedError", { enumerable: true, get: function () { return mount_2.PeableRailUnsupportedError; } });

package/dist/cjs/core/client.js

@@ -63,10 +63,31 @@ function createRestClient(config, tokenProvider, deps = {}) {
         // The Gateway echoes a date-based `Peable-Version` response header
         // (Stripe parity). No SDK behavior depends on it yet, so it is
         // deliberately not read here — nothing to do with it today.
-        const body = await readJsonBody(response);
+        let body;
+        try {
+            body = await readJsonBody(response);
+        }
+        catch {
+            // Headers can arrive before the connection fails during body consumption.
+            // Preserve the known status, but do not infer whether a mutation committed
+            // or retry it automatically. Recovery keeps the caller's original key.
+            throw new errors_1.PeableApiError('The Peable Gateway response body could not be read; remote outcome is unknown', {
+                statusCode: response.status,
+                code: 'invalid_response',
+            });
+        }
         if (!response.ok) {
             throw (0, errors_1.errorFromResponse)(response.status, body);
         }
+        // Only explicit No Content can satisfy a void response. A missing or
+        // malformed JSON success is indeterminate, not a typed resource. Do not
+        // retry a mutation automatically: callers retain the original intent key.
+        if (body === undefined && response.status !== 204) {
+            throw new errors_1.PeableApiError('The Peable Gateway returned an invalid JSON response', {
+                statusCode: response.status,
+                code: 'invalid_response',
+            });
+        }
         return body;
     }
     return {

package/dist/cjs/core/errors.js

@@ -78,7 +78,7 @@ function isFlatGatewayErrorBody(body) {
  * 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/cjs/core/serviceToken.js

@@ -1,7 +1,7 @@
 "use strict";
 // Mints a short-lived Oxy service token from an `ApplicationCredential`
 // (`{publicKey, secret}`) by presenting it to oxy-api's `POST
-// /auth/service-token` — the exact mechanism `oxyClient.serviceAuth()`
+// /auth/service-token` — the exact mechanism `oxy.middleware.service()`
 // validates at the Gateway. Caches the token until near expiry and re-mints
 // reactively when `RestClient` sees a 401 (see `client.ts`).
 Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/index.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.WEBHOOK_SIGNATURE_HEADER = exports.PeableSignatureVerificationError = exports.PeableApiError = exports.PeablePermissionError = exports.PeableInvalidRequestError = exports.PeableAuthenticationError = exports.PeableError = exports.DEFAULT_OXY_API_URL = exports.DEFAULT_GATEWAY_BASE_URL = exports.Peable = void 0;
+const billing_1 = require("./resources/billing");
 // Server entry (`@peable.to/sdk`) — the merchant-authed SDK. Configured with a
 // confidential `ApplicationCredential` (`{publicKey, secret}`); mints and
 // caches an Oxy service token, and exposes Stripe-ergonomics resource
@@ -15,15 +16,41 @@ const paymentIntents_1 = require("./resources/paymentIntents");
 const paymentLinks_1 = require("./resources/paymentLinks");
 const checkoutSessions_1 = require("./resources/checkoutSessions");
 const webhooks_1 = require("./resources/webhooks");
+const connectedAccounts_1 = require("./resources/connectedAccounts");
+const merchants_1 = require("./resources/merchants");
+const refunds_1 = require("./resources/refunds");
+const transfers_1 = require("./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.
+ */
 class Peable {
     constructor(config) {
         const resolved = (0, config_1.resolveConfig)(config);
         const tokenProvider = (0, serviceToken_1.createServiceTokenProvider)(config);
         const client = (0, client_1.createRestClient)({ baseURL: resolved.baseURL }, tokenProvider);
+        this.billing = new billing_1.BillingResource(client);
         this.paymentIntents = new paymentIntents_1.PaymentIntentsResource(client);
         this.paymentLinks = new paymentLinks_1.PaymentLinksResource(client);
         this.checkout = new checkoutSessions_1.CheckoutResource(client);
         this.webhooks = new webhooks_1.WebhooksResource();
+        this.merchants = new merchants_1.MerchantsResource(client);
+        this.connectedAccounts = new connectedAccounts_1.ConnectedAccountsResource(client);
+        this.refunds = new refunds_1.RefundsResource(client);
+        this.transfers = new transfers_1.TransfersResource(client);
+        this.disputes = new merchants_1.DisputesResource(client);
     }
 }
 exports.Peable = Peable;

package/dist/cjs/resources/billing.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BillingResource = void 0;
+/** Recurring billing is separate from one-off checkout and marketplace transfers. */
+class BillingResource {
+    constructor(client) {
+        this.client = client;
+    }
+    ensureCustomer(params, options) {
+        return this.client.request('POST', '/v1/billing/customers', { body: params, idempotencyKey: options.idempotencyKey });
+    }
+    createCheckoutSession(params, options) {
+        return this.client.request('POST', '/v1/billing/checkout_sessions', { body: params, idempotencyKey: options.idempotencyKey });
+    }
+    createPortalSession(params, options) {
+        return this.client.request('POST', '/v1/billing/portal_sessions', { body: params, idempotencyKey: options.idempotencyKey });
+    }
+    retrieveSubscription(ref) {
+        return this.client.request('GET', `/v1/billing/subscriptions/${encodeURIComponent(ref)}`);
+    }
+    cancelAtPeriodEnd(ref, options) {
+        return this.client.request('POST', `/v1/billing/subscriptions/${encodeURIComponent(ref)}/cancel_at_period_end`, { body: {}, idempotencyKey: options.idempotencyKey });
+    }
+}
+exports.BillingResource = BillingResource;

package/dist/cjs/resources/checkoutSessions.js

@@ -5,9 +5,10 @@ class CheckoutSessionsResource {
     constructor(client) {
         this.client = client;
     }
-    create(params) {
+    create(params, options = {}) {
         return this.client.request('POST', '/v1/checkout_sessions', {
             body: params,
+            ...(options.idempotencyKey === undefined ? {} : { idempotencyKey: options.idempotencyKey }),
         });
     }
     retrieve(id) {

package/dist/cjs/resources/connectedAccounts.js

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConnectedAccountsResource = void 0;
+class ConnectedAccountsResource {
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * 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) {
+        return this.client.request('POST', '/v1/connected_accounts', {
+            body: params,
+        });
+    }
+    list(params = {}) {
+        return this.client.request('GET', '/v1/connected_accounts', {
+            query: { limit: params.limit, starting_after: params.starting_after },
+        });
+    }
+    retrieve(accountId) {
+        return this.client.request('GET', `/v1/connected_accounts/${encodeURIComponent(accountId)}`);
+    }
+    /**
+     * 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) {
+        return this.client.request('GET', `/v1/connected_accounts/by_ref/${encodeURIComponent(externalRef)}`);
+    }
+    /**
+     * 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) {
+        return this.client.request('POST', `/v1/connected_accounts/${encodeURIComponent(accountId)}/refresh`);
+    }
+    /**
+     * 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, params) {
+        return this.client.request('POST', `/v1/connected_accounts/${encodeURIComponent(accountId)}/account_links`, { body: params });
+    }
+}
+exports.ConnectedAccountsResource = ConnectedAccountsResource;

package/dist/cjs/resources/merchants.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DisputesResource = exports.MerchantsResource = void 0;
+class MerchantsResource {
+    constructor(client) {
+        this.client = client;
+    }
+    register(params = {}) {
+        return this.client.request('POST', '/v1/merchants', { body: params });
+    }
+    retrieve() {
+        return this.client.request('GET', '/v1/merchants/me');
+    }
+    update(params) {
+        return this.client.request('PATCH', '/v1/merchants/me', { body: params });
+    }
+}
+exports.MerchantsResource = MerchantsResource;
+/**
+ * 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.
+ */
+class DisputesResource {
+    constructor(client) {
+        this.client = client;
+    }
+    listForPaymentIntent(paymentIntentId) {
+        return this.client.request('GET', `/v1/payment_intents/${encodeURIComponent(paymentIntentId)}/disputes`);
+    }
+    /**
+     * 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, evidence) {
+        return this.client.request('POST', `/v1/disputes/${encodeURIComponent(disputeId)}/evidence`, { body: evidence });
+    }
+}
+exports.DisputesResource = DisputesResource;

package/dist/cjs/resources/paymentIntents.js

@@ -23,8 +23,36 @@ class PaymentIntentsResource {
             },
         });
     }
+    /**
+     * 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) {
         return this.client.request('POST', `/v1/payment_intents/${encodeURIComponent(id)}/reject`);
     }
+    /**
+     * 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) {
+        return this.client.request('POST', `/v1/payment_intents/${encodeURIComponent(id)}/client_action`);
+    }
 }
 exports.PaymentIntentsResource = PaymentIntentsResource;

package/dist/cjs/resources/refunds.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RefundsResource = void 0;
+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) {
+        return this.client.request('POST', '/v1/refunds', { body: params });
+    }
+    /**
+     * 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`);
+    }
+}
+exports.RefundsResource = RefundsResource;

package/dist/cjs/resources/transfers.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TransfersResource = void 0;
+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) {
+        return this.client.request('POST', '/v1/transfers', { body: params });
+    }
+    /**
+     * 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`);
+    }
+}
+exports.TransfersResource = TransfersResource;