@peable.to/sdk 0.1.1 → 0.2.1

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

@@ -0,0 +1,77 @@
+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, options?: {
+        idempotencyKey?: string;
+    }): 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,75 @@
+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, options?: {
+        idempotencyKey?: string;
+    }): 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.1",
   "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"
   },