@avvio/payments 0.1.0 → 0.5.0

package/index.d.ts

@@ -35,7 +35,6 @@ export type PayoutFailureCode =
   | 'authorization_not_completed'
   | 'returned_by_bank'
   | 'execution_failed'
-  | 'canceled_by_platform'
   | 'unknown';
 
 /** Informational only. Never branch integration behaviour on it. */
@@ -55,6 +54,12 @@ export interface Payout {
    * wallet. Absent on routings that settle on acceptance, so its presence is
    * the signal — call `getFunding()`.
    */
+  /**
+   * Waiting on YOU to fund it, right now. Call `getFunding(payoutId)`, send the
+   * money, then `confirmFunding`. Absent once it is on its way, and absent
+   * entirely where accepting the payout already paid it — so its presence is
+   * the instruction, not a flag to interpret.
+   */
   requiresFunding?: boolean;
   /** When this payout last changed. Your `updatedSince` watermark. */
   updatedAt?: string;
@@ -68,6 +73,12 @@ export interface Payout {
   sourceAmount: Money | null;
   destinationAmount: Money | null;
   destinationAccountId: string | null;
+  /**
+   * Already inside `sourceAmount` (deducted from the send, not added on top).
+   * The same value the event `data` carries. Null means the rail has not
+   * disclosed it, which is not zero.
+   */
+  fee: Money | null;
   rate: string | null;
   reference: string | null;
   endUser: EndUser | null;
@@ -92,14 +103,31 @@ export interface CorridorField {
   title: string;
   type: string;
   pattern?: string;
+  /**
+   * A check the server applies beyond `pattern`, present only on fields that
+   * have one. `clabe`: the Mexican CLABE check digit (digit 18 over digits
+   * 1-17, weights 3,7,1 repeating, each product mod 10, then (10 - sum mod 10)
+   * mod 10). A value that matches `pattern` but fails this is refused with
+   * `400 VALIDATION_ERROR`.
+   */
+  checksum?: 'clabe';
   required: boolean;
   description?: string;
+  options?: { value: unknown; label: string }[];
 }
 
 export interface Corridor {
   currency: string;
+  /** Only when the routing publishes one; the sandbox does not. Key on `currency`. */
+  country?: string;
   fields: CorridorField[];
-  limits?: { min: string; max: string };
+  limits?: { min?: string; max?: string };
+  /**
+   * Always `null` today: settlement windows and cutoffs are not published per
+   * corridor yet. `Payout.expectedSettlementAt` carries what the network
+   * reports for one payout.
+   */
+  settlement: null;
 }
 
 export interface BeneficiaryMethod {
@@ -117,6 +145,9 @@ export interface Beneficiary {
   name: string;
   email?: string;
   country?: string;
+  /** Both are settable through `updateBeneficiary`, and both come back here. */
+  type?: 'individual' | 'business';
+  phone?: string | null;
   externalId?: string;
   endUserId?: string | null;
   paymentMethods: BeneficiaryMethod[];
@@ -144,6 +175,7 @@ export type PayoutsErrorType =
   | 'UNAUTHORIZED'
   | 'FORBIDDEN'
   | 'NOT_FOUND'
+  | 'ROUTE_NOT_FOUND'
   | 'RATE_LIMITED'
   | 'BAD_REQUEST'
   | 'PROVIDER_REJECTED'
@@ -155,8 +187,32 @@ export type PayoutsErrorType =
   | 'CONFLICT'
   | 'ACCOUNT_BLOCKED'
   | 'INSUFFICIENT_BALANCE'
+  | 'CRYPTO_PAYOUTS_DISABLED'
+  | 'WALLET_NOT_PROVISIONED'
   | 'ORDERS_TEMPORARILY_UNAVAILABLE'
+  | 'PAYOUT_ACCOUNT_PROVIDER_UNAVAILABLE'
+  // Controls on API payouts. Neither is retried into success by the caller:
+  // a cap is split or raised, a refusal is final.
+  | 'PAYOUT_LIMIT_EXCEEDED'
+  | 'PAYOUT_REFUSED'
+  // Quote-accept and payout links, when the organization has an approval
+  // threshold or a velocity cap: only `POST /payouts` enforces them.
+  | 'USE_POST_PAYOUTS'
   | 'INTERNAL'
+  | 'PAYOUT_OUTCOME_UNKNOWN'
+  | 'PAYOUT_LINKS_UNAVAILABLE'
+  // PARKED request-signing error types:
+  // | 'SIGNATURE_CHALLENGE'
+  // | 'SIGNATURE_CHALLENGE_EXPIRED'
+  // | 'SIGNATURE_REQUIRED'
+  // | 'SIGNATURE_INVALID'
+  // | 'SIGNATURE_REPLAYED'
+  // | 'SIGNATURE_TIMESTAMP_SKEW'
+  // | 'SIGNATURE_TIMESTAMP_INVALID'
+  // | 'PUBLIC_KEY_INVALID'
+  // | 'KEY_RETIRED'
+  | 'KEY_EXPIRED'
+  | 'KEY_IP_NOT_ALLOWED'
   // Idempotency
   | 'IDEMPOTENCY_KEY_REQUIRED'
   | 'IDEMPOTENCY_KEY_INVALID'
@@ -168,11 +224,23 @@ export type PayoutsErrorType =
   | 'DESTINATION_ACCOUNT_NOT_FOUND'
   | 'RATE_DRIFT_EXCEEDED'
   | 'QUOTE_UNVERIFIABLE'
+  | 'QUOTE_NOT_POSITIVE'
   | 'EXACT_OUTPUT_UNSUPPORTED'
   | 'PAYOUT_NOT_CANCELABLE'
+  // Asking where to send funds for a payout that settles from your balance.
+  // `requiresFunding` on the payout is the branch, and this means that branch
+  // is wrong, so retrying never helps.
+  | 'FUNDING_NOT_APPLICABLE'
   | 'INSUFFICIENT_SCOPE'
   | 'INDICATIVE_PRICING_UNAVAILABLE'
   | 'PAYOUT_LINK_UNUSABLE'
+  // Batch payouts
+  | 'BATCH_NOT_FOUND'
+  | 'PAYOUT_BATCH_NOT_CONFIRMABLE'
+  | 'PAYOUT_BATCH_AWAITING_APPROVAL'
+  | 'PAYOUT_BATCH_NOT_CANCELABLE'
+  | 'PAYOUT_BATCH_DUPLICATE_REFERENCE'
+  | 'MASS_PAYOUTS_DISABLED'
   // Raised by this client, with no HTTP response behind them. `TIMEOUT` is the
   // important one: it is an UNKNOWN outcome, not a failure, and the payout may
   // exist. `CORRIDOR_UNAVAILABLE` is raised here too, and is in the table.
@@ -198,7 +266,9 @@ export declare class PayoutsError extends Error {
 }
 
 export interface PayoutsClientOptions {
-  /** Server-side only. Never ship to a browser or a mobile app. */
+  // PARKED request-signing option:
+  // privateKeyPem?: string;
+  /** Complete bearer credential: `avvio_live_*` or `avvio_test_*`. */
   apiKey?: string;
   orgId?: string;
   baseUrl?: string;
@@ -206,8 +276,30 @@ export interface PayoutsClientOptions {
 }
 
 export interface PayoutArgs {
+  /**
+   * How much. Read as what you SEND, unless `amountLeg` says otherwise — in
+   * which case it is what the beneficiary RECEIVES, in their currency.
+   */
   amount: string;
   destinationAccountId: string;
+  /**
+   * Which side of the payout `amount` describes.
+   *
+   * `'source'` (the default) takes every fee out of what you sent, so the
+   * beneficiary gets less than the figure you named.
+   *
+   * `'destination'` pays them that figure exactly, in THEIR currency, and adds
+   * the fees to your debit instead.
+   *
+   * `'source_net'` keeps the figure in YOUR currency and means it the same way
+   * — "send them $200 worth". We convert at the market rate from `quote()` and
+   * lock that, so the fees land on your debit rather than on what they receive.
+   *
+   * The two locking modes need `capabilities.exactOutput` on the corridors
+   * call; elsewhere they are refused with `EXACT_OUTPUT_UNSUPPORTED` rather
+   * than silently pricing the other side.
+   */
+  amountLeg?: 'source' | 'destination' | 'source_net';
   /**
    * What you told the payer they would receive. The send is REFUSED if the
    * binding quote drifts past `maxRateDrift` from it. Without this you send at
@@ -247,10 +339,104 @@ export interface PayoutArgs {
    */
   allowDuplicate?: boolean;
   reference?: string;
+  /** From `listPaymentReasons()`. Validated whenever sent; will be required for INR/GHS/CNY/BRL from a dated future release. */
   purposeOfPayment?: string;
   endUser?: EndUser;
 }
 
+/**
+ * The batch lifecycle. A batch tracks CREATION, not settlement: `completed`
+ * means every line either became a payout or was refused — read the `counts`.
+ */
+export type PayoutBatchStatus =
+  | 'received'
+  | 'validating'
+  | 'awaiting_confirmation'
+  | 'creating'
+  | 'completed'
+  | 'canceled'
+  | 'failed'
+  | (string & {});
+
+export type PayoutBatchItemStatus =
+  | 'received'
+  | 'invalid'
+  | 'validated'
+  | 'creating'
+  | 'created'
+  | 'create_failed'
+  | 'canceled'
+  /**
+   * Outcome unknown (the process died mid-create). NEVER auto-retried —
+   * contact support with the batchId rather than resubmitting the line.
+   */
+  | 'requires_review'
+  | (string & {});
+
+export interface PayoutBatch {
+  batchId: string;
+  /** Your own run id, echoed back. */
+  externalReferenceId: string | null;
+  status: PayoutBatchStatus;
+  autoCommit: boolean;
+  /** Lines by status. The values sum to the number of lines submitted. */
+  counts: Record<PayoutBatchItemStatus, number>;
+  /** Present only when `status` is `failed` — the run-level reason. */
+  error?: unknown;
+  /**
+   * Advisory. What the valid lines will draw from your balance, set when
+   * validation finishes; null while validation runs and when any line locks
+   * the destination side. Compare against `getBalance()` BEFORE confirming.
+   */
+  estimatedSourceTotal: string | null;
+  createdAt: string;
+  updatedAt: string;
+  completedAt: string | null;
+}
+
+export interface PayoutBatchItem {
+  /** Zero-based position in the `items` array you submitted. */
+  index: number;
+  status: PayoutBatchItemStatus;
+  /** The line you submitted, echoed back verbatim — join on content. */
+  instruction: unknown;
+  /** Present on `invalid` and `create_failed` lines. */
+  errors?: { code: string; message: string }[];
+  /** Present once `created` — the payout to track from here on. */
+  payoutId?: string;
+}
+
+export interface PayoutBatchArgs {
+  /**
+   * 1–1,000 payout instructions, each exactly a `POST /payouts` body (the
+   * WIRE shape — `expectDestination`, `maxDriftBps` — not the Node-only
+   * `PayoutArgs` conveniences, which are translated by `payout()` alone).
+   */
+  items: unknown[];
+  /**
+   * Your own run id (a payroll file name, a cycle). Required, and unique per
+   * organization: a second batch with the same id is refused with
+   * `PAYOUT_BATCH_DUPLICATE_REFERENCE` naming the original, so a submit job
+   * that re-runs the same file under a fresh idempotency key cannot pay
+   * twice. A corrected resubmission is a new run and needs its own id.
+   * 1-128 characters: letters, digits, space, `. _ : -`.
+   */
+  externalReferenceId: string;
+  /**
+   * True (the default): a run with zero validation errors proceeds straight
+   * to creation. False, or any errors found: the batch holds at
+   * `awaiting_confirmation` for `confirmPayoutBatch` / `cancelPayoutBatch`.
+   */
+  autoCommit?: boolean;
+  /**
+   * Covers the RUN: resubmitting the same file under the same key returns the
+   * same batch, never a second payroll. Persist it before you send.
+   */
+  idempotencyKey?: string;
+  /** Repeat a byte-identical run on purpose. Sets `X-Allow-Duplicate: true`. */
+  allowDuplicate?: boolean;
+}
+
 export declare class PayoutsClient {
   constructor(opts?: PayoutsClientOptions);
 
@@ -259,8 +445,8 @@ export declare class PayoutsClient {
    * suite — `expect(avvio.mode).toBe('test')` before a test that sends is the
    * cheapest guard there is against a live key reaching a payroll fixture.
    *
-   * A key that is not recognisably `ak_test_` reports `'live'`, because the two
-   * wrong answers are not equally bad.
+   * The constructor rejects unrecognized and retired credential formats before
+   * deriving this value.
    */
   readonly mode: 'test' | 'live';
 
@@ -272,7 +458,7 @@ export declare class PayoutsClient {
    * caller following the instruction had no typed path to the field and had to
    * reach for an unsound cast.
    */
-  corridors(): Promise<{
+  corridors(currency?: string): Promise<{
     corridors: Corridor[];
     capabilities: { exactOutput: boolean; indicativePricing: boolean };
   }>;
@@ -299,9 +485,7 @@ export declare class PayoutsClient {
     idempotencyKey?: string;
   }): Promise<Beneficiary>;
 
-  listBeneficiaries(args?: {
-    endUserId?: string;
-  }): Promise<{
+  listBeneficiaries(args?: { endUserId?: string }): Promise<{
     /** 'organization' or the end user the list was scoped to. Undeclared previously. */
     scope: string;
     recipients: Beneficiary[];
@@ -313,6 +497,75 @@ export declare class PayoutsClient {
     nextCursor?: string | null;
   }>;
 
+  /** One beneficiary, by the id we returned. `NOT_FOUND` if it is not yours. */
+  getBeneficiary(recipientId: string): Promise<Beneficiary>;
+
+  /**
+   * One beneficiary, by YOUR id for them — the same `externalId` that makes
+   * creation idempotent. Unique per organization, so this is exactly one
+   * beneficiary or a `NOT_FOUND`, rather than paging your whole book.
+   */
+  getBeneficiaryByExternalId(externalId: string): Promise<Beneficiary>;
+
+  /**
+   * Correct a beneficiary's own details. Only the fields you pass are changed.
+   *
+   * **Bank details are NOT editable.** The rail validated that account, and
+   * swapping it underneath would send the next payout somewhere you never
+   * registered — a wrong account is a new payment method, and the old one is
+   * deleted with `deleteBeneficiaryMethod`.
+   */
+  updateBeneficiary(
+    recipientId: string,
+    patch: {
+      type?: 'individual' | 'business';
+      name?: string;
+      email?: string;
+      phone?: string;
+      /** ISO-3166 alpha-2. */
+      country?: string;
+    },
+    opts?: { idempotencyKey?: string },
+  ): Promise<Beneficiary>;
+
+  /**
+   * Remove a beneficiary and every payment method on it. Payouts already sent
+   * are history, not references — this cancels nothing in flight.
+   */
+  deleteBeneficiary(
+    recipientId: string,
+    opts?: { idempotencyKey?: string },
+  ): Promise<{ success: true }>;
+
+  /**
+   * Remove one way of paying a beneficiary — an account that closed, or one
+   * entered wrong. Returns the beneficiary without it; the
+   * `destinationAccountId` that method carried stops being payable.
+   */
+  deleteBeneficiaryMethod(
+    recipientId: string,
+    methodId: string,
+    opts?: { idempotencyKey?: string },
+  ): Promise<Beneficiary>;
+
+  /**
+   * The full account details behind one payment method — lists carry only
+   * `last4`. Deliberately loose: the fields are the corridor's own, so they
+   * differ by rail exactly as `requirements()` does.
+   */
+  getBeneficiaryMethodDetails(
+    recipientId: string,
+    methodId: string,
+  ): Promise<Record<string, unknown>>;
+
+  /**
+   * The stated payment reasons this organization may use — the vocabulary
+   * `purposeOfPayment` on a payout, and `paymentReason` on a quote you accept,
+   * are validated against. Read it rather than guessing: a rejected value is a
+   * 400 on a payout you have already promised somebody.
+   */
+  paymentReasons(): Promise<{ payment_reasons: Record<string, unknown>[] }>;
+
   /**
    * Every event since a watermark, paged for you. At-least-once — `since` is
    * inclusive, so a resumed run re-reads the row at your watermark. Dedupe on
@@ -322,8 +575,17 @@ export declare class PayoutsClient {
     since?: string;
     limit?: number;
     payoutId?: string;
+    /** Event types to include; a string (`'payout.completed,payout.returned'`) or an array. */
+    type?: PayoutEventType | PayoutEventType[] | string;
   }): AsyncIterableIterator<PayoutEvent>;
 
+  /** Every audit event matching a filter, newest first, paged for you. */
+  eachAuditEvent(
+    args?: AuditEventFilters & {
+      limit?: number;
+    },
+  ): AsyncIterableIterator<AuditEvent>;
+
   /** Every payout matching a filter, paged for you. */
   eachPayout(args?: {
     limit?: number;
@@ -401,15 +663,55 @@ export declare class PayoutsClient {
     limit?: number;
     /** Everything that ever happened to one payout. */
     payoutId?: string;
+    /**
+     * Event types to include; a string (`'payout.completed,payout.returned'`)
+     * or an array. Unknown values are a 400, never an empty page.
+     */
+    type?: PayoutEventType | PayoutEventType[] | string;
   }): Promise<{
     data: PayoutEvent[];
     hasMore: boolean;
     nextSince: string | null;
   }>;
 
+  /**
+   * Payouts and batch runs waiting on your approvers. `payout()` and
+   * `confirmPayoutBatch()` answer 202 with a `PendingApproval` when the
+   * organization's policy holds them; this is that queue. Approving and
+   * rejecting are dashboard actions — a key cannot, so there is no method.
+   */
+  listApprovals(args?: {
+    status?: PayoutApprovalStatus;
+    /** 1–100, default 50. */
+    limit?: number;
+  }): Promise<{ data: PayoutApproval[] }>;
+
+  /** One approval, by the `approvalId` a 202 gave you. */
+  getApproval(approvalId: string): Promise<PayoutApproval>;
+
+  /**
+   * A PAGE of audit events, newest first — who did what, from where, with which
+   * credential. `id` is the cursor. A read-only key may read this.
+   */
+  listAuditEvents(
+    args?: AuditEventFilters & {
+      /** 1–100, default 50. */
+      limit?: number;
+      /** A `nextCursor` we issued: rows strictly older than it. */
+      cursor?: string;
+    },
+  ): Promise<{
+    data: AuditEvent[];
+    hasMore: boolean;
+    nextCursor: string | null;
+  }>;
+
   /**
    * How to fund a payout that came back with `requiresFunding: true`. Your funds
    * stay in your wallet until you move them.
+   *
+   * A pure read — poll it freely. It no longer returns `signableOperations`:
+   * that are a dashboard action — an API key cannot sign them.
    */
   getFunding(payoutId: string): Promise<{
     payoutId: string;
@@ -417,19 +719,22 @@ export declare class PayoutsClient {
     currency: string;
     depositAddress: string;
     network: string;
-    expiresAt: string;
-    /** Present when you can sign through this API instead of broadcasting. */
-    signableOperations?: unknown[];
+    /**
+     * Normally `null`. There is no countdown on the deposit address — the rail
+     * decides when an unfunded payout is over and reports that as the payout's
+     * own status, so read `getPayout()` before sending against instructions you
+     * fetched a while ago. Declared as a non-null `string` until now, so a
+     * TypeScript caller had no reason not to build a timer on it.
+     */
+    expiresAt: string | null;
     instructions: string;
   }>;
 
-  /** Proof you sent the funds: a hash you broadcast, or operations you signed. */
+  /** Proof you sent the funds: the transaction hash you broadcast. */
   confirmFunding(
     payoutId: string,
     proof: {
-      transactionHash?: string;
-      signedOperations?: unknown[];
-      tamperProofSignature?: string;
+      transactionHash: string;
       idempotencyKey?: string;
     },
   ): Promise<Payout>;
@@ -466,40 +771,134 @@ export declare class PayoutsClient {
     updatedSince?: string;
   }): Promise<{ data: Payout[]; hasMore: boolean; nextCursor: string | null }>;
 
+  /**
+   * Submit up to 1,000 payouts as one run. `202` means RECEIVED, not paid:
+   * every line is validated first (nothing priced, nothing debited), then the
+   * valid lines become ordinary payouts, each with its own `payoutId`.
+   */
+  createPayoutBatch(args: PayoutBatchArgs): Promise<PayoutBatch>;
+
+  /** A PAGE of batches, newest first — not an array. */
+  listPayoutBatches(args?: {
+    status?: PayoutBatchStatus;
+    /** Exact match on your own run id. */
+    externalReferenceId?: string;
+    /** 1–100, default 50. */
+    limit?: number;
+    /** A `nextCursor` we issued. Anything else is a 400, never an empty page. */
+    cursor?: string;
+  }): Promise<{
+    data: PayoutBatch[];
+    hasMore: boolean;
+    nextCursor: string | null;
+  }>;
+
+  /** One run, with its counts. Authoritative for the batch, not the payouts. */
+  getPayoutBatch(batchId: string): Promise<PayoutBatch>;
+
+  /**
+   * The lines of a run, instruction echoed back verbatim. `status: 'invalid'`
+   * is the review screen after `awaiting_confirmation`; `'created'` joins the
+   * run to the payout ledger. The CSV export (`?format=csv`) is a plain file
+   * download — this method returns the JSON page.
+   */
+  listPayoutBatchItems(
+    batchId: string,
+    args?: {
+      status?: PayoutBatchItemStatus;
+      /** 1–1,000, default 100. */
+      limit?: number;
+      /** The `nextCursor` from your previous page — the last line index. */
+      cursor?: string;
+    },
+  ): Promise<{
+    data: PayoutBatchItem[];
+    hasMore: boolean;
+    nextCursor: string | null;
+  }>;
+
+  /**
+   * Proceed with the valid lines of a held run. Only legal from
+   * `awaiting_confirmation` — anything else is `PAYOUT_BATCH_NOT_CONFIRMABLE`.
+   */
+  confirmPayoutBatch(
+    batchId: string,
+    opts?: { idempotencyKey?: string },
+  ): Promise<PayoutBatch>;
+
+  /**
+   * Stop a run before any payout exists. Once creation begins the run is
+   * committed and this is `PAYOUT_BATCH_NOT_CANCELABLE` — cancel individual
+   * payouts via `cancelPayout` instead.
+   */
+  cancelPayoutBatch(
+    batchId: string,
+    opts?: { idempotencyKey?: string },
+  ): Promise<PayoutBatch>;
+
   fundingAccounts(): Promise<unknown>;
 
-  /** What you can currently send. */
-  balance(): Promise<{ currency: string; amount: string }>;
+  /**
+   * What your organization is bound by, read live. Read it first: caps,
+   * approval threshold, features, rate limits, idempotency windows and the
+   * currencies that need a `purposeOfPayment`.
+   */
+  getPolicy(): Promise<Policy>;
 
   /**
-   * Why the balance is what it is: every movement with the running balance
-   * after it. Reconcile against this rather than trusting a single number.
+   * Everything a payout can draw on (cached up to 60 s): what the payment
+   * network holds for you (`provider`) plus the USD stablecoins in your own
+   * wallet (`wallet`, per chain, at face value), summed per currency into
+   * `balances` with USD as the `amount` headline. Size payouts against that,
+   * knowing wallet figures are face value before the network and conversion
+   * cost of moving them onto the settling rail — a payout for exactly
+   * `amount` can fail to fund when the money must be gathered from several
+   * chains first.
+   * `ledger` is our own append-only record of the network-held part, with
+   * what holds currently reserve. Never summed with the others; a difference
+   * from `provider` is what `listBalanceTransactions()` explains.
+   * `unavailable` names any source that failed to read: when non-empty the
+   * figures are a floor, not the balance — retry before concluding you
+   * cannot fund a payout.
    */
-  balanceHistory(limit?: number): Promise<{
+  balance(): Promise<{
     currency: string;
-    balance: string;
-    entries: {
-      id: string;
-      /**
-       * `reversal` is a returned payout crediting the balance back. It is a
-       * SEPARATE appended entry, not a rewrite of the original debit — an entry
-       * already emitted never changes.
-       */
-      type: 'funding' | 'payout' | 'reversal';
-      /**
-       * What this ENTRY records, frozen at the moment it was written — not the
-       * payout's current status, which would make a historical row mutate.
-       * `DEBITED` money left, `RETURNED` money came back, `COMPLETED` funding
-       * landed. For a payout's live fate, read `getPayout()`.
-       */
-      status: 'DEBITED' | 'RETURNED' | 'COMPLETED' | (string & {});
-      amount: string;
-      balanceAfter: string;
-      reference?: string;
-      at: string;
-    }[];
+    amount: string;
+    balances: Money[];
+    provider: Money[];
+    /** Always empty in sandbox. */
+    wallet: WalletBalance[];
+    /** Sources that failed to read; non-empty results are not cached, so retry. */
+    unavailable: Array<'network' | 'wallet'>;
+    ledger: LedgerBalance[];
   }>;
 
+  /**
+   * A PAGE of balance transactions, newest first — not an array. Every change
+   * to what you can spend, each with `balanceAfter`; `id` is the cursor and
+   * the dedupe key. Served on every environment; an empty page means no rows
+   * yet, not an error.
+   */
+  listBalanceTransactions(
+    args?: BalanceTransactionFilters & {
+      /** 1–100, default 100. */
+      limit?: number;
+      /** A `nextCursor` we issued: rows strictly older than it. */
+      cursor?: string;
+    },
+  ): Promise<{
+    data: BalanceTransaction[];
+    hasMore: boolean;
+    nextCursor: string | null;
+  }>;
+
+  /** Every balance transaction matching a filter, newest first, paged for you. */
+  eachBalanceTransaction(
+    args?: BalanceTransactionFilters & {
+      limit?: number;
+    },
+  ): AsyncIterableIterator<BalanceTransaction>;
+
   /** Credit a sandbox balance. Test keys only. */
   fund(amount?: string, idempotencyKey?: string): Promise<{ balance: string }>;
 
@@ -528,13 +927,10 @@ export declare class PayoutsClient {
 
   /**
    * Register a sandbox webhook endpoint. The `secret` is returned ONCE and is
-   * not retrievable afterwards. Test keys only.
+   * not retrievable afterwards. Test keys only. Sends no `Idempotency-Key` and
+   * is never retried: a stored replay would keep the secret.
    */
-  createWebhookEndpoint(args: {
-    url: string;
-    events?: string[];
-    idempotencyKey?: string;
-  }): Promise<{
+  createWebhookEndpoint(args: { url: string; events?: string[] }): Promise<{
     id: string;
     url: string;
     events: string[];
@@ -542,7 +938,53 @@ export declare class PayoutsClient {
     warning: string;
   }>;
 
-  /** What we sent, what came back, and what we retried. */
+  /**
+   * The webhook endpoints registered for your organization.
+   *
+   * Read-only by design, and there is no create/pause/delete counterpart here:
+   * a key that could repoint its own webhook URL could redirect every payout
+   * notification. The signing secret is never returned — it is shown once, at
+   * creation.
+   */
+  webhookEndpoints(): Promise<
+    {
+      id: string;
+      url: string;
+      events: string[];
+      /** Non-null while the endpoint is paused or auto-disabled. */
+      disabledAt: string | null;
+      disabledReason: 'paused_by_owner' | 'auto_disabled_after_failures' | null;
+      /** Retry ladders exhausted since the last accepted delivery. */
+      consecutiveFailures: number;
+      lastSuccessAt: string | null;
+      lastFailureAt: string | null;
+      createdAt: string;
+    }[]
+  >;
+
+  /**
+   * The 50 most recent delivery attempts for one endpoint, newest first. No
+   * payloads — replay from the dashboard if you need the body, which re-fires
+   * under the same `eventId` so your dedupe still holds.
+   */
+  webhookEndpointDeliveries(endpointId: string): Promise<
+    {
+      id: string;
+      /** The event id: the `svix-id` we sent and the feed row's `id`. Dedupe on this. */
+      eventId: string;
+      eventType: string;
+      attempts: number;
+      /** Null until an attempt is accepted. */
+      deliveredAt: string | null;
+      /** When we will try again. Retries back off over roughly 70 hours. */
+      nextAttemptAt: string | null;
+      /** Your server's response on the most recent failure. */
+      lastError: string | null;
+      createdAt: string;
+    }[]
+  >;
+
+  /** What we sent, what came back, and what we retried. Sandbox endpoints. */
   webhookDeliveries(endpointId: string): Promise<unknown>;
 }
 
@@ -580,8 +1022,175 @@ export declare function stableKey(...parts: (string | number)[]): string;
  * so they cannot be confused, and `scripts/sdk-contract.ts` asserts this one
  * against a real delivered event.
  */
+/** What your organization is bound by, from `getPolicy()`. `null` on a cap or threshold means not set. */
+export interface Policy {
+  /** The id you addressed; a test key sends the live organization id and gets it back. */
+  organizationId: string;
+  /** `test`: nothing reaches a payment network. */
+  mode: 'test' | 'live';
+  /** Effective feature names, sorted. `mass_payouts` enables batches, `developer` enables webhook endpoints. */
+  features: string[];
+  /** USD caps; over one is `422 PAYOUT_LIMIT_EXCEEDED`. Two-decimal strings. */
+  limits: {
+    maxSinglePayoutUsd: string | null;
+    maxDailyPayoutUsd: string | null;
+    /** Counted against `endUser.id`; when set, a payout without an `endUser` is refused. */
+    maxDailyPerEndUserUsd: string | null;
+  };
+  /** When `thresholdUsd` is set, a send above it answers 202 and needs `requiredApprovals` humans. */
+  approvals: {
+    thresholdUsd: string | null;
+    requiredApprovals: number | null;
+    appliesTo: ('payouts' | 'batches' | 'payout_links')[];
+  };
+  purposeOfPayment: {
+    /** Destination currencies that require `purposeOfPayment` on a payout. */
+    requiredForCurrencies: string[];
+  };
+  /**
+   * What your routing can state about its fees BEFORE a quote exists. `null`
+   * on a number means "not published before a quote", never zero. The binding
+   * figure is `fee` on the quote and the payout.
+   */
+  fees: {
+    payout: {
+      /** Basis points of the send for corridors not in `byCurrency`. */
+      bps: number | null;
+      /** Fixed component in USD, two decimals. */
+      fixedUsd: string | null;
+      /** Corridors priced differently from the default, by destination currency. */
+      byCurrency: Record<string, { bps: number; fixedUsd: string | null }>;
+      /** Prose; do not branch on it. */
+      note: string;
+    };
+  };
+  /** Requests per minute per credential, by bucket. */
+  rateLimits: {
+    default: number;
+    payouts: number;
+    batches: number;
+    reads: number;
+  };
+  idempotency: {
+    /** An API key must send `Idempotency-Key` on every money route. */
+    required: boolean;
+    replayWindowDays: number;
+    nearDuplicateWindowMinutes: number;
+  };
+  /** Relative paths with your organization id filled in. */
+  links: { corridors: string; events: string; balanceTransactions: string };
+}
+
+export interface LedgerBalance {
+  currency: string;
+  /** What a payout can draw on right now. */
+  available: string;
+  /** Reserved by holds not yet converted to payouts or released. */
+  held: string;
+  /** `available` + `held`. */
+  total: string;
+}
+
+/** One USD stablecoin position in your own wallet, on one chain. */
+export interface WalletBalance {
+  currency: 'USDC' | 'USDT';
+  /** Chain name: Ethereum, Base, Arbitrum, Optimism, Solana. */
+  network: string;
+  /** Token units, up to six decimals. Counted into `balances` at face value. */
+  amount: string;
+}
+
+export type BalanceTransactionType =
+  | 'funding'
+  | 'payout'
+  | 'payout_return'
+  | 'hold'
+  | 'hold_release'
+  | 'adjustment';
+
+export interface BalanceTransactionFilters {
+  /** One type, several, or a comma-separated string. Unknown values are a 400. */
+  type?: BalanceTransactionType | BalanceTransactionType[] | string;
+  /** Everything that moved for one payout. */
+  orderId?: string;
+  currency?: string;
+  /** Inclusive, ISO-8601 with a timezone. */
+  createdAfter?: string;
+  /** Inclusive, ISO-8601 with a timezone. */
+  createdBefore?: string;
+}
+
+/**
+ * One append-only change to what you can spend. `amount` is signed and always
+ * means "how this row changed `available`".
+ */
+export interface BalanceTransaction {
+  /** Monotonic, and the cursor. A string: it can exceed 2^53. */
+  id: string;
+  type: BalanceTransactionType;
+  amount: string;
+  /** Fee portion of `amount`. Null means not known, which is not zero. */
+  fee: string | null;
+  /** The amount less the fee, carrying the amount's sign. Absent when `fee` is null. */
+  net?: string;
+  currency: string;
+  /** `available` after this row. */
+  balanceAfter: string;
+  orderId: string | null;
+  /**
+   * The quote snapshot that sized this row. A `hold` has no `orderId` (it is
+   * placed before the network answers); its `hold_release` and `payout` rows
+   * share this `snapshotId`, which is the join. Null on `funding`/`adjustment`.
+   */
+  snapshotId: string | null;
+  batchId: string | null;
+  reference: string | null;
+  endUserId: string | null;
+  reason: string | null;
+  description: string | null;
+  createdAt: string;
+}
+
+/**
+ * Every event the feed and the webhooks carry. `payout.returned` is its OWN
+ * type, not a flavour of `payout.failed` — it is the one event that reverses
+ * something you already booked. New types are added without a major version;
+ * ignore ones you do not handle.
+ */
+export type PayoutEventType =
+  | 'payout.pending'
+  | 'payout.processing'
+  | 'payout.completed'
+  | 'payout.failed'
+  | 'payout.returned'
+  | 'payout.canceled'
+  | 'payout_batch.awaiting_confirmation'
+  | 'payout_batch.completed'
+  | 'payout_batch.canceled'
+  | 'payout_batch.failed'
+  | 'payout_approval.pending'
+  | 'payout_approval.approved'
+  | 'payout_approval.rejected'
+  | 'payout_approval.expired'
+  | 'payout_approval.executed'
+  | 'payout_approval.execution_failed'
+  | 'webhook_endpoint.disabled'
+  | (string & {});
+
+/**
+ * The `data` of an event, by family. Discriminate on the row's `type`:
+ * `payout.*` → `WebhookPayout`, `payout_batch.*` → `PayoutBatch`,
+ * `payout_approval.*` → `PayoutApprovalEvent`, `webhook_endpoint.*` →
+ * `WebhookEndpointDisabled`.
+ */
+export type EventData =
+  | WebhookPayout
+  | PayoutBatch
+  | PayoutApprovalEvent
+  | WebhookEndpointDisabled;
+
 export interface PayoutEvent {
-  /** Stable. Dedupe on this — the feed is at-least-once. */
+  /** Stable. Dedupe on this — the feed is at-least-once. Equals the webhook `svix-id`. */
   id: string;
   /**
    * The cursor, as a decimal STRING. A 64-bit sequence past 2^53 is not
@@ -589,23 +1198,121 @@ export interface PayoutEvent {
    * unrecoverable.
    */
   sequence: string;
-  /**
-   * `payout.returned` is its OWN type, not a flavour of `payout.failed` — it is
-   * the one event that reverses something you already booked. New types are
-   * added without a major version; ignore ones you do not handle.
-   */
-  type:
-    | 'payout.pending'
-    | 'payout.processing'
-    | 'payout.completed'
-    | 'payout.failed'
-    | 'payout.returned'
-    | (string & {});
-  payoutId: string;
-  status: PayoutStatus;
+  type: PayoutEventType;
+  /** Null on batch, approval and endpoint events. */
+  payoutId: string | null;
+  /** Set on `payout_batch.*` rows and on a batch approval. */
+  batchId: string | null;
+  /** The resource's status after this transition; a `PayoutStatus` on `payout.*` rows. */
+  status: PayoutStatus | string;
   failureCode?: PayoutFailureCode;
   fundsReturned?: boolean;
   createdAt: string;
+  /** The `data` shape version. Same value as the `Avvio-Webhook-Version` header. */
+  apiVersion: number;
+  /** The webhook body for this event, verbatim. */
+  data: EventData;
+}
+
+export type PayoutApprovalStatus =
+  | 'pending'
+  | 'approved'
+  | 'rejected'
+  | 'expired'
+  | 'executing'
+  | 'executed'
+  | 'execution_failed'
+  | 'execution_unknown';
+
+/** One request for M-of-N human approval. A PRE-payout resource, not a payout status. */
+export interface PayoutApproval {
+  id: string;
+  kind: 'payout' | 'payout_batch';
+  status: PayoutApprovalStatus;
+  /** M, snapshotted when the request was created. */
+  requiredApprovals: number;
+  /** Approve votes so far. */
+  approvals: number;
+  /** Present once a `payout` approval is `executed` — the payout it became. */
+  payoutId?: string;
+  /** Present on `payout_batch` approvals. */
+  batchId?: string;
+  amount: string | null;
+  currency: string | null;
+  destinationAccountId?: string;
+  /** Present on `execution_failed`. */
+  error?: string;
+  createdAt: string;
+  /** A `pending` request expires 24 hours after creation. */
+  expiresAt: string | null;
+  updatedAt: string;
+}
+
+/** The `data` of a `payout_approval.*` event. */
+export interface PayoutApprovalEvent {
+  approval: PayoutApproval;
+  /** On `payout_approval.executed` — the payout the approval became. */
+  payoutId?: string;
+}
+
+/** The `data` of `webhook_endpoint.disabled`, delivered to your OTHER endpoints. */
+export interface WebhookEndpointDisabled {
+  endpointId: string;
+  url: string;
+  reason: 'auto_disabled_after_failures';
+  consecutiveFailures: number;
+  lastSuccessAt: string | null;
+  disabledAt: string;
+}
+
+/**
+ * The 202 body from `payout()` and `confirmPayoutBatch()` when the
+ * organization's policy holds the instruction for its approvers. Nothing was
+ * priced or sent.
+ */
+export interface PendingApproval {
+  status: 'pending_approval';
+  approvalId: string;
+  /** Same value as `approvalId`; kept for the dashboard client. */
+  approvalRequestId?: string;
+  requiredApprovals: number;
+  expiresAt: string;
+}
+
+export interface AuditEventFilters {
+  /** One action, e.g. `payout.create`. */
+  action?: string;
+  /** Everything done to one payout, batch, approval, beneficiary, key or endpoint. */
+  resourceId?: string;
+  /** A key prefix. An unknown prefix is an empty page, not a 404. */
+  apiKey?: string;
+  actorUserId?: string;
+  /** Inclusive, ISO-8601 with a timezone. */
+  createdAfter?: string;
+  /** Inclusive, ISO-8601 with a timezone. */
+  createdBefore?: string;
+}
+
+/** One audited mutation. Append-only; never updated. */
+export interface AuditEvent {
+  /** Monotonic, and the cursor. A decimal string. */
+  id: string;
+  /** e.g. `payout.create`, `payout_batch.confirm`, `recipient.delete`, `api_key.rotate`. New actions are added without a version. */
+  action: string;
+  resourceType: string;
+  /** Null when the request was refused before a resource existed. */
+  resourceId: string | null;
+  /** The key's prefix as you named it. Null for a dashboard action. */
+  apiKeyPrefix: string | null;
+  /** The dashboard user. Null for an API-key action. */
+  actorUserId: string | null;
+  ip: string | null;
+  /** The `x-request-id` of that request; joins to `BalanceTransaction.requestId`. */
+  requestId: string | null;
+  outcome: 'ok' | 'error';
+  /** The error `type` when `outcome` is `error`. */
+  errorType: string | null;
+  createdAt: string;
 }
 
 export interface WebhookPayout {
@@ -628,25 +1335,29 @@ export interface WebhookPayout {
   completedAt: string | null;
 }
 
+/**
+ * A signed delivery. The envelope is the feed row: the same `id`, `sequence`,
+ * `type`, `createdAt`, `apiVersion` and `data` come back from `listEvents()`,
+ * so a delivery is the trigger to read the feed from the right place.
+ */
 export interface WebhookEvent {
-  /** New types are added without a major version — return 2xx for unknown ones. */
-  /**
-   * Every type actually delivered, confirmed by capturing raw bodies — this
-   * omitted `payout.returned`, `payout.canceled` and `payout.processing`, all
-   * three of which arrive. The `(string & {})` escape made the omission
-   * invisible: an exhaustive switch compiled with no `payout.returned` case,
-   * and a bank return was silently ignored — the exact failure the separate
-   * type exists to prevent.
-   */
-  type:
-    | 'payout.pending'
-    | 'payout.processing'
-    | 'payout.completed'
-    | 'payout.failed'
-    | 'payout.returned'
-    | 'payout.canceled'
-    | (string & {});
-  data: WebhookPayout;
+  /** The event id. Equals the `svix-id` header and the feed row's `id`. Dedupe on it. */
+  id: string;
+  /** The feed cursor for this event, as a decimal string. */
+  sequence: string;
+  /**
+   * Every type actually delivered. An earlier version omitted `payout.returned`,
+   * `payout.canceled` and `payout.processing`, all three of which arrive; the
+   * `(string & {})` escape made the omission invisible. Return 2xx for types
+   * you do not handle.
+   */
+  type: PayoutEventType;
+  createdAt: string;
+  /** Which body shape `data` is. Also the `Avvio-Webhook-Version` header. */
+  apiVersion: number;
+  /** False from a sandbox organization's endpoint. */
+  livemode: boolean;
+  data: EventData;
 }
 
 /**
@@ -678,3 +1389,11 @@ export declare function createWebhookHandler(opts: {
   /** Reject timestamps outside this window. Defaults to 300. */
   toleranceSeconds?: number;
 }): (req: any, res: any) => Promise<void>;
+
+// PARKED request-signing helper. The runtime implementation remains available
+// for a coordinated restoration, but it is intentionally absent from the
+// current bearer-key type surface.
+// export function generateSigningKeyPair(): {
+//   publicKeyPem: string;
+//   privateKeyPem: string;
+// };