@avvio/payments 0.1.0 → 0.5.0

package/src/client.js

@@ -10,7 +10,13 @@
  * being "nothing" is worth more than any convenience a library would buy.
  */
 
-const { createHash, randomUUID } = require('node:crypto');
+const {
+  createHash,
+  createPrivateKey,
+  createSign,
+  generateKeyPairSync,
+  randomUUID,
+} = require('node:crypto');
 
 /** Thrown for any non-2xx. Carries enough to act on without parsing prose. */
 class PayoutsError extends Error {
@@ -142,7 +148,9 @@ function stableKey(...parts) {
       undefined,
     );
   }
-  const empty = parts.findIndex((p) => p === undefined || p === null || p === '');
+  const empty = parts.findIndex(
+    (p) => p === undefined || p === null || p === '',
+  );
   if (empty !== -1) {
     throw new PayoutsError(
       400,
@@ -193,7 +201,7 @@ function backoffMs(attempt, retryAfterSeconds) {
 class PayoutsClient {
   /**
    * @param {object} opts
-   * @param {string} opts.apiKey     Server-side only. Never ship this to a browser or a phone.
+   * @param {string} opts.apiKey     Complete `avvio_live_*` or `avvio_test_*` bearer key.
    * @param {string} opts.orgId      Your organization id.
    * @param {string} [opts.baseUrl]  Defaults to the AVVIO_BASE_URL env var.
    * @param {number} [opts.timeoutMs]
@@ -201,6 +209,8 @@ class PayoutsClient {
   constructor(opts = {}) {
     this.apiKey = opts.apiKey || process.env.AVVIO_API_KEY;
     this.orgId = opts.orgId || process.env.AVVIO_ORG_ID;
+    // PARKED request-signing setup. Restore with the signing block in `_send`.
+    // const privatePem = opts.privateKeyPem || process.env.AVVIO_PRIVATE_KEY;
     // `business/api/v1`, NOT `api/v1`. The bare `api/v1` prefix on this host is
     // the CONSUMER backend that the mobile app talks to — a different service.
     // Cloudflare routes only `/business/*` to this one. Worse than a 404: the
@@ -211,7 +221,12 @@ class PayoutsClient {
       opts.baseUrl ||
       process.env.AVVIO_BASE_URL ||
       'https://api.avvio.xyz/business/api/v1'
-    ).replace(/\/+$/, '');
+    );
+    // Trailing slashes, trimmed without `/\/+$/`: that pattern is quadratic on
+    // a long run of slashes, and this value can come from an env var.
+    let baseEnd = this.baseUrl.length;
+    while (baseEnd > 0 && this.baseUrl[baseEnd - 1] === '/') baseEnd--;
+    this.baseUrl = this.baseUrl.slice(0, baseEnd);
     this.timeoutMs = opts.timeoutMs || DEFAULT_TIMEOUT_MS;
     // Attempts AFTER the first, so 2 means up to three calls. Set 0 to disable.
     this.maxRetries = opts.maxRetries === undefined ? 2 : opts.maxRetries;
@@ -226,18 +241,32 @@ class PayoutsClient {
         'Missing organization id. Set AVVIO_ORG_ID, or pass { orgId } to the client.',
       );
     }
+    if (
+      !/^avvio_(?:live|test)_[0-9a-f]{32}_[A-Za-z0-9_-]{43}$/.test(this.apiKey)
+    ) {
+      throw new Error(
+        'Unsupported API credential. Copy the complete avvio_live_* or avvio_test_* API key shown at issuance.',
+      );
+    }
+    // PARKED request-signing constructor behavior. The bearer API key is the
+    // complete credential; AVVIO_PRIVATE_KEY is intentionally ignored.
+    // if (!privatePem) {
+    //   throw new Error(
+    //     'This signed API key id requires a private signing key. Set AVVIO_PRIVATE_KEY, or pass { privateKeyPem } to the client.',
+    //   );
+    // }
+    // this.privateKey = privatePem ? createPrivateKey(privatePem) : null;
 
     /**
      * `'test'` or `'live'`, from the key prefix — so a test suite can assert it
      * is not about to pay real people, before it sends anything.
      *
-     * Anything that is not recognisably a test key is reported as LIVE. The two
-     * wrong answers are not symmetrical: calling a live key "test" is how a
-     * suite happily runs a payroll against real money, while calling a test key
-     * "live" only makes someone check. `doctor` reads this rather than deciding
-     * again, because two places deciding is two places to get it wrong.
+     * The constructor has already rejected every other credential shape, so
+     * this cannot silently interpret an unknown value as live. `doctor` reads
+     * this rather than deciding again, because two places deciding is two
+     * places to get it wrong.
      */
-    this.mode = this.apiKey.startsWith('ak_test_') ? 'test' : 'live';
+    this.mode = this.apiKey.startsWith('avvio_test_') ? 'test' : 'live';
   }
 
   // ─── transport ───
@@ -254,16 +283,20 @@ class PayoutsClient {
    * as prose.
    *
    * The rule: a mutation may only be retried while REUSING its idempotency key.
-   * By the time execution reaches here the key is already fixed — it was minted
-   * by the calling method or supplied by the caller — so a retry reuses it by
-   * construction and cannot become a second payment. A mutation with no key is
-   * never retried, because there is nothing making it safe.
+   * Every mutation carries one — supplied by the caller, or minted here once
+   * per logical call and reused across its attempts — because the server
+   * honours the header on every POST, PATCH and DELETE. So a retry reuses the
+   * key by construction and cannot become a second payment; a mutation that
+   * somehow has no key is never retried, because nothing makes it safe.
    *
    * `DUPLICATE_REQUEST_DETECTED` is never retried at any level: it means an
    * identical body arrived under a DIFFERENT key, and retrying is exactly the
    * behaviour it exists to refuse.
    */
   async request(method, path, opts = {}) {
+    if (method !== 'GET' && !opts.idempotencyKey) {
+      opts = { ...opts, idempotencyKey: randomUUID() };
+    }
     const idempotent = method === 'GET' || Boolean(opts.idempotencyKey);
     let attempt = 0;
 
@@ -286,7 +319,11 @@ class PayoutsClient {
     }
   }
 
-  async _send(method, path, { body, idempotencyKey, query, headers: extra } = {}) {
+  async _send(
+    method,
+    path,
+    { body, idempotencyKey, query, headers: extra } = {},
+  ) {
     // Every failure from a mutation carries the key it used. Without this, the
     // instruction "retry with the same idempotency key" names a value the
     // caller has no way to obtain — which is worse than saying nothing, because
@@ -308,6 +345,30 @@ class PayoutsClient {
     if (idempotencyKey) headers['idempotency-key'] = idempotencyKey;
     Object.assign(headers, extra || {});
 
+    // PARKED request-signing block. Restore only with server verification and
+    // the matching public documentation.
+    // if (this.privateKey) {
+    //   const serialized = body ? JSON.stringify(body) : '';
+    //   const timestamp = String(Math.floor(Date.now() / 1000));
+    //   const nonce = randomUUID();
+    //   const canonical = [
+    //     this.apiKey,
+    //     method.toUpperCase(),
+    //     url.pathname + url.search,
+    //     createHash('sha256').update(serialized, 'utf8').digest('hex'),
+    //     idempotencyKey || '',
+    //     timestamp,
+    //     nonce,
+    //   ].join('\n');
+    //   headers['x-anzo-signature'] = createSign('sha256')
+    //     .update(canonical)
+    //     .end()
+    //     .sign(this.privateKey)
+    //     .toString('base64');
+    //   headers['x-anzo-timestamp'] = timestamp;
+    //   headers['x-anzo-nonce'] = nonce;
+    // }
+
     let res;
     try {
       res = await fetch(url, {
@@ -344,6 +405,13 @@ class PayoutsClient {
       parsed = { message: text.slice(0, 500) };
     }
 
+    // A generic HTTP client considers every 2xx successful. This payload is
+    // authentication work, not a payout response, so fail closed if a signed
+    // client ever receives one instead of quietly handing it to business code.
+    if (res.status === 202 && parsed?.type === 'SIGNATURE_CHALLENGE') {
+      throw tag(new PayoutsError(res.status, parsed, requestId));
+    }
+
     if (!res.ok) {
       const err = new PayoutsError(res.status, parsed, requestId);
       // The server tells us when its window resets; guessing is worse. Only
@@ -363,16 +431,22 @@ class PayoutsClient {
     if (replayed && parsed && typeof parsed === 'object') {
       // Surfaced so a caller reconciling a retry storm can tell "we already did
       // this" from "we just did this".
-      Object.defineProperty(parsed, 'replayed', { value: true, enumerable: false });
+      Object.defineProperty(parsed, 'replayed', {
+        value: true,
+        enumerable: false,
+      });
     }
     return parsed;
   }
 
   // ─── discovery ───
 
-  /** Every currency you can pay out to, with the fields each one needs. */
-  corridors() {
-    return this.request('GET', `/recipients/${this.orgId}/corridors`);
+  /** Every currency you can pay out to, or the exact routed currency requested. */
+  corridors(currency) {
+    const query = currency
+      ? `?currency=${encodeURIComponent(String(currency).toUpperCase())}`
+      : '';
+    return this.request('GET', `/recipients/${this.orgId}/corridors${query}`);
   }
 
   /**
@@ -382,8 +456,8 @@ class PayoutsClient {
    * depend on how your organization is routed, and we may re-route you.
    */
   async requirements(currency) {
-    const { corridors } = await this.corridors();
     const want = String(currency).toUpperCase();
+    const { corridors } = await this.corridors(want);
     const match = (corridors || []).find(
       (c) => String(c.currency || '').toUpperCase() === want,
     );
@@ -405,6 +479,21 @@ class PayoutsClient {
     return match;
   }
 
+  /**
+   * The stated payment reasons this organization may use.
+   *
+   * Some corridors require one — `purposeOfPayment` on a payout, `paymentReason`
+   * on a quote you accept — and this is the list they are validated against.
+   * Read it rather than guessing: a rejected value is a 400 on a payout you have
+   * already promised somebody.
+   */
+  paymentReasons() {
+    return this.request(
+      'GET',
+      `/payments/organizations/${this.orgId}/payment-reasons`,
+    );
+  }
+
   // ─── pricing ───
 
   /**
@@ -454,6 +543,99 @@ class PayoutsClient {
     });
   }
 
+  /** One beneficiary, by the id we returned. */
+  getBeneficiary(recipientId) {
+    return this.request(
+      'GET',
+      `/recipients/${this.orgId}/${encodeURIComponent(recipientId)}`,
+    );
+  }
+
+  /**
+   * One beneficiary, by YOUR id for them.
+   *
+   * `externalId` was already the key that makes creation idempotent; this reads
+   * it back, so "worker 4471" resolves to a `destinationAccountId` in one call
+   * rather than paging your whole book and filtering client-side. Unique per
+   * organization, so this is exactly one beneficiary or a 404.
+   */
+  getBeneficiaryByExternalId(externalId) {
+    return this.request(
+      'GET',
+      `/recipients/${this.orgId}/external/${encodeURIComponent(externalId)}`,
+    );
+  }
+
+  /**
+   * Correct a beneficiary's own details: name, email, phone, country, and
+   * whether they are an individual or a business.
+   *
+   * **The bank account behind a payment method is not editable, by design.**
+   * 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.
+   */
+  updateBeneficiary(recipientId, patch = {}, { idempotencyKey } = {}) {
+    return this.request(
+      'PATCH',
+      `/recipients/${this.orgId}/${encodeURIComponent(recipientId)}`,
+      {
+        idempotencyKey,
+        // Only what was named. Sending `email: undefined` as an explicit null
+        // would ask the server to clear a field the caller never mentioned.
+        body: {
+          ...(patch.type !== undefined ? { type: patch.type } : {}),
+          ...(patch.name !== undefined ? { name: patch.name } : {}),
+          ...(patch.email !== undefined ? { email: patch.email } : {}),
+          ...(patch.phone !== undefined ? { phone: patch.phone } : {}),
+          ...(patch.country !== undefined ? { country: patch.country } : {}),
+        },
+      },
+    );
+  }
+
+  /**
+   * Remove a beneficiary and every payment method on it.
+   *
+   * Payouts already sent are history, not references — deleting cancels
+   * nothing in flight.
+   */
+  deleteBeneficiary(recipientId, { idempotencyKey } = {}) {
+    return this.request(
+      'DELETE',
+      `/recipients/${this.orgId}/${encodeURIComponent(recipientId)}`,
+      { idempotencyKey },
+    );
+  }
+
+  /**
+   * Remove one way of paying a beneficiary — an account that closed, or one
+   * entered wrong. The beneficiary and their other methods are untouched, and
+   * the `destinationAccountId` this method carried stops being payable.
+   */
+  deleteBeneficiaryMethod(recipientId, methodId, { idempotencyKey } = {}) {
+    return this.request(
+      'DELETE',
+      `/recipients/${this.orgId}/${encodeURIComponent(recipientId)}/methods/${encodeURIComponent(methodId)}`,
+      { idempotencyKey },
+    );
+  }
+
+  /**
+   * The full account details behind one payment method.
+   *
+   * Lists carry only `last4`. This returns what was actually registered, so you
+   * can show someone the account on file before they authorize a payout, or
+   * confirm what you stored matches what we hold. Deliberately per-method: bulk
+   * reads do not move full account numbers around.
+   */
+  getBeneficiaryMethodDetails(recipientId, methodId) {
+    return this.request(
+      'GET',
+      `/recipients/${this.orgId}/${encodeURIComponent(recipientId)}/methods/${encodeURIComponent(methodId)}/details`,
+    );
+  }
+
   // ─── paying ───
 
   /**
@@ -506,6 +688,13 @@ class PayoutsClient {
    * receive and the send is refused if the binding quote moved further than
    * `maxRateDrift` from it. Enforced server-side, so it protects every caller
    * rather than only the ones using this package.
+   *
+   * `amountLeg: 'destination'` changes what `amount` MEANS: the beneficiary
+   * receives exactly that figure, in THEIR currency, and the fees are added to
+   * what you are debited rather than taken out of it. Measured on a live
+   * corridor, naming 3400 MXN debited 201.879397 USDC and paid out 3400.00.
+   * Refused with `EXACT_OUTPUT_UNSUPPORTED` where the routing cannot lock it —
+   * check `capabilities.exactOutput` on the corridors call first.
    */
   payout(p) {
     const expect =
@@ -519,7 +708,10 @@ class PayoutsClient {
         body: {
           amount: p.amount,
           destinationAccountId: p.destinationAccountId,
-          ...(expect !== undefined ? { expectDestination: String(expect) } : {}),
+          ...(p.amountLeg ? { amountLeg: p.amountLeg } : {}),
+          ...(expect !== undefined
+            ? { expectDestination: String(expect) }
+            : {}),
           ...(p.maxRateDrift !== undefined
             ? { maxDriftBps: toDriftBps(p.maxRateDrift) }
             : {}),
@@ -533,7 +725,9 @@ class PayoutsClient {
         // Says "I know this looks like the last one, and I mean it". Only ever
         // set deliberately: it switches off the guard that catches a retry
         // arriving under a fresh key.
-        ...(p.allowDuplicate ? { headers: { 'x-allow-duplicate': 'true' } } : {}),
+        ...(p.allowDuplicate
+          ? { headers: { 'x-allow-duplicate': 'true' } }
+          : {}),
       },
     );
   }
@@ -549,9 +743,17 @@ class PayoutsClient {
    *
    * At-least-once: dedupe on `id`.
    */
-  listEvents({ since, limit, payoutId } = {}) {
+  listEvents({ since, limit, payoutId, type } = {}) {
     return this.request('GET', `/payments/organizations/${this.orgId}/events`, {
-      query: { since, limit, payoutId },
+      // `type` narrows the feed to the families you book: a string
+      // ('payout.completed,payout.returned') or an array. Unknown values are a
+      // 400, never an empty page.
+      query: {
+        since,
+        limit,
+        payoutId,
+        type: Array.isArray(type) ? type.join(',') : type,
+      },
     });
   }
 
@@ -569,10 +771,10 @@ class PayoutsClient {
    * At-least-once by design: `since` is inclusive, so a resumed run re-reads the
    * row at your watermark. Dedupe on `id`.
    */
-  async *eachEvent({ since, limit = 100, payoutId } = {}) {
+  async *eachEvent({ since, limit = 100, payoutId, type } = {}) {
     let cursor = since;
     for (;;) {
-      const page = await this.listEvents({ since: cursor, limit, payoutId });
+      const page = await this.listEvents({ since: cursor, limit, payoutId, type });
       for (const event of page.data || []) yield event;
       if (!page.hasMore || !page.nextSince || page.nextSince === cursor) return;
       cursor = page.nextSince;
@@ -589,7 +791,13 @@ class PayoutsClient {
    * empty page with `hasMore` is a real state and swallowing it would rebuild
    * the silent-truncation bug the API was fixed to remove.
    */
-  async *eachPayout({ limit = 50, status, endUserId, reference, updatedSince } = {}) {
+  async *eachPayout({
+    limit = 50,
+    status,
+    endUserId,
+    reference,
+    updatedSince,
+  } = {}) {
     let cursor;
     for (;;) {
       const page = await this.listPayouts({
@@ -601,7 +809,8 @@ class PayoutsClient {
         updatedSince,
       });
       for (const payout of page.data || []) yield payout;
-      if (!page.hasMore || !page.nextCursor || page.nextCursor === cursor) return;
+      if (!page.hasMore || !page.nextCursor || page.nextCursor === cursor)
+        return;
       cursor = page.nextCursor;
     }
   }
@@ -609,8 +818,18 @@ class PayoutsClient {
   /**
    * How to fund a payout that came back with `requiresFunding: true`.
    *
-   * Where to send, how much, on which network, and by when. Your funds stay in
-   * your wallet until you move them — we hold no key and cannot move them.
+   * Where to send, how much, on which network. Your funds stay in your wallet
+   * until you move them — we hold no key and cannot move them.
+   *
+   * A pure read: poll it as often as you like. `expiresAt` is normally `null`,
+   * because 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. Before sending against instructions you fetched a while ago, read
+   * `getPayout()` rather than watching a clock.
+   *
+   * `signableOperations` is no longer returned here; it moved to
+   * a dashboard action: they are operations for the organization's own wallet,
+   * which an API key cannot sign.
    */
   getFunding(payoutId) {
     return this.request(
@@ -619,11 +838,7 @@ class PayoutsClient {
     );
   }
 
-  /**
-   * Proof you sent the funds: a `transactionHash` you broadcast, or
-   * `signedOperations` you signed from `getFunding()`. Which one depends on how
-   * you hold the money, not on anything we prefer.
-   */
+  /** Proof you sent the funds: the transaction hash you broadcast. */
   confirmFunding(payoutId, proof = {}) {
     return this.request(
       'POST',
@@ -633,12 +848,6 @@ class PayoutsClient {
           ...(proof.transactionHash
             ? { transactionHash: proof.transactionHash }
             : {}),
-          ...(proof.signedOperations
-            ? { signedOperations: proof.signedOperations }
-            : {}),
-          ...(proof.tamperProofSignature
-            ? { tamperProofSignature: proof.tamperProofSignature }
-            : {}),
         },
         idempotencyKey: proof.idempotencyKey || randomUUID(),
       },
@@ -677,12 +886,128 @@ class PayoutsClient {
    * declaration used to claim an array, so code written off it threw on the
    * first call.
    */
-  listPayouts({ limit, cursor, status, endUserId, reference, updatedSince } = {}) {
+  listPayouts({
+    limit,
+    cursor,
+    status,
+    endUserId,
+    reference,
+    updatedSince,
+  } = {}) {
     return this.request('GET', `/payments/organizations/${this.orgId}/orders`, {
       query: { limit, cursor, status, endUserId, reference, updatedSince },
     });
   }
 
+  // ─── mass payouts ───
+
+  /**
+   * Submit up to 1,000 payouts as one run. Each item is exactly a `payout()`
+   * body (the wire shape — `expectDestination`, `maxDriftBps`).
+   *
+   * The `202` means RECEIVED, not paid: every line is validated first (nothing
+   * priced, nothing debited), then the valid lines become ordinary payouts.
+   * With `autoCommit: true` — the default — a run with zero validation errors
+   * proceeds straight to creation; otherwise the batch holds at
+   * `awaiting_confirmation` for `confirmPayoutBatch` or `cancelPayoutBatch`.
+   *
+   * The idempotency key covers the RUN: a submit loop that dies and resubmits
+   * the same file under the same key gets the same batch back — never a second
+   * payroll. Persist your own key before you send; the generated fallback only
+   * protects retries inside this process.
+   *
+   * `externalReferenceId` is required and unique per organization: it is the
+   * guard the key cannot be, against the same file re-run under a FRESH key.
+   * A repeat is refused with `PAYOUT_BATCH_DUPLICATE_REFERENCE` naming the
+   * original batch. Sent as-is; the server validates it, so a missing id is
+   * the server's 400, not a silent omission here.
+   */
+  createPayoutBatch(p = {}) {
+    return this.request(
+      'POST',
+      `/payments/organizations/${this.orgId}/payouts/batches`,
+      {
+        body: {
+          externalReferenceId: p.externalReferenceId,
+          items: p.items,
+          ...(p.autoCommit !== undefined ? { autoCommit: p.autoCommit } : {}),
+        },
+        idempotencyKey: p.idempotencyKey || randomUUID(),
+        // Same meaning as on a single payout: "I know this run looks like the
+        // last one, and I mean it".
+        ...(p.allowDuplicate ? { headers: { 'x-allow-duplicate': 'true' } } : {}),
+      },
+    );
+  }
+
+  /** A PAGE of batches, newest first: `{ data, hasMore, nextCursor }`. */
+  listPayoutBatches({ status, externalReferenceId, limit, cursor } = {}) {
+    return this.request(
+      'GET',
+      `/payments/organizations/${this.orgId}/payouts/batches`,
+      { query: { status, externalReferenceId, limit, cursor } },
+    );
+  }
+
+  /**
+   * One run, with its counts. A batch tracks CREATION, not settlement:
+   * `completed` means every line either became a payout or was refused. Once a
+   * line is `created`, watch the payout, not the item.
+   */
+  getPayoutBatch(batchId) {
+    return this.request(
+      'GET',
+      `/payments/organizations/${this.orgId}/payouts/batches/${encodeURIComponent(batchId)}`,
+    );
+  }
+
+  /**
+   * The lines of a run, in submitted order, with the instruction you sent
+   * echoed back verbatim — join errors to your own file by content, not by
+   * counting rows. `status: 'invalid'` is the review screen; `'created'` joins
+   * the run to the payout ledger; `'requires_review'` are lines whose outcome
+   * could not be established and were deliberately NOT retried — contact
+   * support with the batchId rather than resubmitting them.
+   *
+   * The CSV export (`?format=csv`) is a plain file download, not a JSON page —
+   * fetch it over HTTP directly. This method returns the JSON page.
+   */
+  listPayoutBatchItems(batchId, { status, limit, cursor } = {}) {
+    return this.request(
+      'GET',
+      `/payments/organizations/${this.orgId}/payouts/batches/${encodeURIComponent(batchId)}/items`,
+      { query: { status, limit, cursor } },
+    );
+  }
+
+  /**
+   * Proceed with the valid lines of a held run. Only legal while the batch is
+   * `awaiting_confirmation`; anything else is `PAYOUT_BATCH_NOT_CONFIRMABLE`,
+   * naming where it actually is. Invalid lines stay refused — correct them and
+   * resubmit as a new batch.
+   */
+  confirmPayoutBatch(batchId, { idempotencyKey } = {}) {
+    return this.request(
+      'POST',
+      `/payments/organizations/${this.orgId}/payouts/batches/${encodeURIComponent(batchId)}/confirm`,
+      { idempotencyKey: idempotencyKey || randomUUID() },
+    );
+  }
+
+  /**
+   * Stop a run before any payout exists. Honoured in `received`, `validating`
+   * and `awaiting_confirmation` only; once creation begins the run is
+   * committed and this is `PAYOUT_BATCH_NOT_CANCELABLE` — cancel individual
+   * payouts while they are still `pending` via `cancelPayout` instead.
+   */
+  cancelPayoutBatch(batchId, { idempotencyKey } = {}) {
+    return this.request(
+      'POST',
+      `/payments/organizations/${this.orgId}/payouts/batches/${encodeURIComponent(batchId)}/cancel`,
+      { idempotencyKey: idempotencyKey || randomUUID() },
+    );
+  }
+
   /** Sandbox only: credit the test balance so you can send. */
   /**
    * Register a sandbox webhook endpoint and get its signing secret.
@@ -691,19 +1016,61 @@ class PayoutsClient {
    * this returns it rather than storing it for you. Live endpoints are managed
    * from the dashboard on purpose: a credential that could repoint its own
    * webhook URL could redirect every payout notification.
+   *
+   * No `Idempotency-Key`, and so no retry: the server ignores the header here
+   * because a stored replay would keep the secret for seven days. A timeout
+   * means "register again"; an extra endpoint is a delete, a leaked secret is
+   * not.
    */
-  createWebhookEndpoint({ url, events, idempotencyKey } = {}) {
-    return this.request(
+  createWebhookEndpoint({ url, events } = {}) {
+    return this._send(
       'POST',
       `/payments/organizations/${this.orgId}/sandbox/webhook-endpoints`,
-      {
-        body: { url, ...(events ? { events } : {}) },
-        idempotencyKey: idempotencyKey || randomUUID(),
-      },
+      { body: { url, ...(events ? { events } : {}) } },
+    );
+  }
+
+  /**
+   * The webhook endpoints registered for your organization.
+   *
+   * Read-only, and it stays that way. Registering, pausing, deleting and
+   * replaying are dashboard actions: a credential that could repoint its own
+   * webhook URL could quietly redirect every payout notification you receive.
+   * The signing secret is never returned here — you are shown it once, when the
+   * endpoint is created.
+   *
+   * Note the path: `/organizations/{orgId}/…`, not the `/payments/…` prefix the
+   * payout routes use.
+   */
+  webhookEndpoints() {
+    return this.request(
+      'GET',
+      `/organizations/${this.orgId}/webhook-endpoints`,
     );
   }
 
-  /** What we sent, what came back, and what we retried. */
+  /**
+   * The 50 most recent delivery attempts for one endpoint, newest first —
+   * "did you send me that event", without opening a dashboard.
+   *
+   * `eventId` is the `svix-id` we sent, so it is what your dedupe keys on.
+   * `lastError` is the STATUS your server answered with on the last failed
+   * attempt (`HTTP 500`) or the transport error, never your response body — we
+   * do not store one. `nextAttemptAt` is when we try again; retries back off
+   * over roughly 70 hours, after which only the event feed still has it.
+   * Payloads are not returned.
+   *
+   * This is the endpoint from `webhookEndpoints()`. The sandbox registration
+   * view is `webhookDeliveries()`, below.
+   */
+  webhookEndpointDeliveries(endpointId) {
+    return this.request(
+      'GET',
+      `/organizations/${this.orgId}/webhook-endpoints/${encodeURIComponent(endpointId)}/deliveries`,
+    );
+  }
+
+  /** What we sent, what came back, and what we retried. Sandbox endpoints. */
   webhookDeliveries(endpointId) {
     return this.request(
       'GET',
@@ -711,6 +1078,84 @@ class PayoutsClient {
     );
   }
 
+  /**
+   * Payouts and batch runs waiting on your approvers: `{ data }`.
+   *
+   * When your organization requires M-of-N approval on API payouts, `payout()`
+   * and `confirmPayoutBatch()` above the threshold answer 202 with
+   * `{ status: 'pending_approval', approvalId, … }` instead of a payout. This is
+   * that queue. Approving and rejecting are human actions in the dashboard and
+   * deliberately have no method here — a key cannot approve.
+   */
+  listApprovals({ status, limit } = {}) {
+    return this.request(
+      'GET',
+      `/payments/organizations/${this.orgId}/payouts/approvals`,
+      { query: { status, limit } },
+    );
+  }
+
+  /**
+   * One approval, by the `approvalId` a 202 gave you. Once `status` is
+   * `executed`, `payoutId` is the payout it became.
+   */
+  getApproval(approvalId) {
+    return this.request(
+      'GET',
+      `/payments/organizations/${this.orgId}/payouts/approvals/${encodeURIComponent(approvalId)}`,
+    );
+  }
+
+  /**
+   * A PAGE of audit events, newest first: `{ data, hasMore, nextCursor }`.
+   *
+   * Who did what, from where, with which credential — every audited mutation on
+   * your organization, refused attempts included. Rows carry the key PREFIX you
+   * named it by, never the internal id. A read-only key may read this.
+   */
+  listAuditEvents({
+    cursor,
+    limit,
+    action,
+    resourceId,
+    apiKey,
+    actorUserId,
+    createdAfter,
+    createdBefore,
+  } = {}) {
+    return this.request(
+      'GET',
+      `/payments/organizations/${this.orgId}/audit-events`,
+      {
+        query: {
+          cursor,
+          limit,
+          action,
+          resourceId,
+          apiKey,
+          actorUserId,
+          createdAfter,
+          createdBefore,
+        },
+      },
+    );
+  }
+
+  /**
+   * Every audit event matching a filter, newest first, paged for you. Same
+   * stop rule as `eachPayout`: ends when the server says there is no more, or
+   * when the cursor stops advancing.
+   */
+  async *eachAuditEvent({ limit = 100, ...filters } = {}) {
+    let cursor;
+    for (;;) {
+      const page = await this.listAuditEvents({ ...filters, limit, cursor });
+      for (const row of page.data || []) yield row;
+      if (!page.hasMore || !page.nextCursor || page.nextCursor === cursor) return;
+      cursor = page.nextCursor;
+    }
+  }
+
   /**
    * Mint a one-time link for the person being paid.
    *
@@ -741,18 +1186,60 @@ class PayoutsClient {
   }
 
   /**
-   * Why the balance is what it is: every movement, with the running balance
-   * after each. Reconcile against this rather than trusting a single number —
-   * a balance you cannot explain is one you cannot build a ledger on.
+   * A PAGE of balance transactions, newest first: `{ data, hasMore, nextCursor }`.
+   *
+   * Every change to what you can spend — funding, payouts, returns, holds and
+   * their release, adjustments — each with `balanceAfter`. Reconcile your
+   * ledger row by row against this; `id` is the cursor and the dedupe key.
+   * `type` takes a string (`'payout,funding'`) or an array.
+   *
+   * Served on every environment; an empty page means no rows yet, not an
+   * error.
    */
-  balanceHistory(limit) {
+  listBalanceTransactions({
+    cursor,
+    limit,
+    type,
+    orderId,
+    currency,
+    createdAfter,
+    createdBefore,
+  } = {}) {
     return this.request(
       'GET',
-      `/payments/organizations/${this.orgId}/balance/history`,
-      { query: { limit } },
+      `/payments/organizations/${this.orgId}/balance_transactions`,
+      {
+        query: {
+          cursor,
+          limit,
+          type: Array.isArray(type) ? type.join(',') : type,
+          orderId,
+          currency,
+          createdAfter,
+          createdBefore,
+        },
+      },
     );
   }
 
+  /**
+   * Every balance transaction matching a filter, newest first, paged for you.
+   *
+   *   for await (const t of avvio.eachBalanceTransaction({ type: 'payout' })) { … }
+   *
+   * Same stop rule as `eachPayout`: ends when the server says there is no
+   * more, or when the cursor stops advancing.
+   */
+  async *eachBalanceTransaction({ limit = 100, ...filters } = {}) {
+    let cursor;
+    for (;;) {
+      const page = await this.listBalanceTransactions({ ...filters, limit, cursor });
+      for (const row of page.data || []) yield row;
+      if (!page.hasMore || !page.nextCursor || page.nextCursor === cursor) return;
+      cursor = page.nextCursor;
+    }
+  }
+
   fund(amount = '5000.00', idempotencyKey) {
     return this.request(
       'POST',
@@ -761,14 +1248,24 @@ class PayoutsClient {
     );
   }
 
-  /** What you can currently send. */
-  balance() {
+  /**
+   * What your organization is bound by, read live: payout caps (`null` = no
+   * cap), the approval threshold and M, effective features, rate limits per
+   * minute, idempotency windows, the currencies that need a `purposeOfPayment`,
+   * and where to read corridors, events and the ledger. Read it first.
+   */
+  getPolicy() {
     return this.request(
       'GET',
-      `/payments/organizations/${this.orgId}/balance`,
+      `/payments/organizations/${this.orgId}/policy`,
     );
   }
 
+  /** What you can currently send. */
+  balance() {
+    return this.request('GET', `/payments/organizations/${this.orgId}/balance`);
+  }
+
   /** Where to wire funds to top up the balance payouts debit. */
   fundingAccounts() {
     return this.request(
@@ -789,7 +1286,28 @@ const {
   WebhookVerificationError,
 } = require('./webhooks');
 
+/**
+ * Generate a signing pair. The private half is yours and must never be sent to
+ * us — register `publicKeyPem` on the key, keep `privateKeyPem` in your secret
+ * store, and pass it to the client.
+ *
+ * Here rather than in the docs as an openssl incantation, because a partner who
+ * has to look up `openssl ecparam` is a partner who might paste the wrong half.
+ */
+function generateSigningKeyPair() {
+  const { publicKey, privateKey } = generateKeyPairSync('ec', {
+    namedCurve: 'prime256v1',
+  });
+  return {
+    publicKeyPem: publicKey.export({ type: 'spki', format: 'pem' }).toString(),
+    privateKeyPem: privateKey
+      .export({ type: 'pkcs8', format: 'pem' })
+      .toString(),
+  };
+}
+
 module.exports = {
+  generateSigningKeyPair,
   PayoutsClient,
   PayoutsError,
   stableKey,