@avvio/payments 0.1.0

package/src/client.js

@@ -0,0 +1,799 @@
+'use strict';
+
+/**
+ * The payouts client. Everything the CLI and the MCP server do goes through
+ * here, so there is one place where auth, idempotency and error shape live.
+ *
+ * No dependencies, on purpose. This package ends up inside a payments partner's
+ * infrastructure holding a credential that moves money, and "what is in this
+ * dependency tree" is a question their security review will ask. The answer
+ * being "nothing" is worth more than any convenience a library would buy.
+ */
+
+const { createHash, randomUUID } = require('node:crypto');
+
+/** Thrown for any non-2xx. Carries enough to act on without parsing prose. */
+class PayoutsError extends Error {
+  constructor(status, body, requestId) {
+    const type = (body && (body.type || body.error)) || 'error';
+    const message =
+      (body && body.message) || `Request failed with status ${status}`;
+    super(message);
+    this.name = 'PayoutsError';
+    this.status = status;
+    this.type = type;
+    this.requestId = requestId;
+    this.body = body;
+    // Recovery hints, when the server sent them. On DUPLICATE_REQUEST_DETECTED
+    // these are the whole point: they name the key to retry with and the payout
+    // that already exists.
+    if (body && body.originalIdempotencyKey)
+      this.originalIdempotencyKey = body.originalIdempotencyKey;
+    if (body && body.originalPayoutId)
+      this.originalPayoutId = body.originalPayoutId;
+  }
+
+  /**
+   * Is retrying this exact request, unchanged, worth doing?
+   *
+   * A 409 in flight is the one non-obvious yes: it means an identical request
+   * is already running, and the right response is to back off and ask again,
+   * not to mint a new idempotency key and send a second payment.
+   */
+  /**
+   * Make the error survive `JSON.stringify` and structured logging.
+   *
+   * `retryable` is a getter and `message` is non-enumerable on Error, so the
+   * README told people to branch on `err.retryable` while the object they piped
+   * to their logger contained neither. An error whose most important field
+   * disappears the moment you log it is the error you cannot debug at 3am.
+   */
+  toJSON() {
+    return {
+      name: this.name,
+      type: this.type,
+      message: this.message,
+      status: this.status,
+      retryable: this.retryable,
+      requestId: this.requestId,
+      idempotencyKey: this.idempotencyKey,
+      ...(this.originalIdempotencyKey
+        ? { originalIdempotencyKey: this.originalIdempotencyKey }
+        : {}),
+      ...(this.originalPayoutId
+        ? { originalPayoutId: this.originalPayoutId }
+        : {}),
+    };
+  }
+
+  get retryable() {
+    if (this.type === 'IDEMPOTENCY_KEY_REQUEST_IN_PROGRESS') return true;
+    // NOT retryable as-is, deliberately. It means an identical request just went
+    // out under a different key, and blindly retrying is either a second payment
+    // or a pointless loop. It needs a decision: reuse `originalIdempotencyKey`,
+    // or declare the duplicate intentional. Auto-resolving it here would be the
+    // same silent guess the server refused to make.
+    if (this.type === 'DUPLICATE_REQUEST_DETECTED') return false;
+    if (this.status === 429) return true;
+    return this.status >= 500;
+  }
+}
+
+/**
+ * A drift ceiling as a fraction (0.02 = 2%) -> basis points.
+ *
+ * Refuses rather than clamping. Passing 100000 — a plausible misreading of "in
+ * basis points" — produced a server-side VALIDATION_ERROR that named neither the
+ * unit nor the limit, and the three surfaces spell this differently
+ * (`maxRateDrift` fractional here, `maxDriftBps` on the wire,
+ * `--max-drift-bps` in the CLI), which is exactly how someone reaches for the
+ * wrong one.
+ */
+function toDriftBps(fraction) {
+  const n = Number(fraction);
+  if (!Number.isFinite(n) || n < 0 || n > 1) {
+    throw new PayoutsError(
+      400,
+      {
+        type: 'VALIDATION_ERROR',
+        message:
+          `maxRateDrift must be a fraction between 0 and 1 (0.02 = 2%). ` +
+          `Got ${fraction}. If you meant basis points, divide by 10000.`,
+      },
+      undefined,
+    );
+  }
+  return Math.round(n * 10_000);
+}
+
+/**
+ * A deterministic idempotency key, derived from what makes the payment unique.
+ *
+ *   stableKey(orgId, payrollRunId, employeeId)
+ *
+ * `randomUUID()` is the right default for a single call and the wrong one for
+ * the exact failure the docs tell partners to retry through: a job that crashes
+ * mid-payroll and requeues mints a NEW key for the same wage, so the key-based
+ * replay that was supposed to protect it never fires and the worker is paid
+ * twice. Persisting the key before sending is the other answer, and it needs a
+ * durable write on the hot path; this one needs nothing remembered at all,
+ * because the key is recomputed rather than recalled.
+ *
+ * Formatted as a UUID because the server accepts one everywhere a key is
+ * allowed, and because a value that lands in someone's logs and database
+ * columns should look like what it is.
+ */
+function stableKey(...parts) {
+  // Both refusals below are the same failure wearing different clothes: a key
+  // that does not depend on WHO is being paid is one key for the whole run, and
+  // after the first payout every later one replays it — so nine people are
+  // silently not paid while nine ledger rows say they were. Refusing is the only
+  // safe answer; there is nothing sensible to substitute.
+  if (!parts.length) {
+    throw new PayoutsError(
+      400,
+      {
+        type: 'VALIDATION_ERROR',
+        message:
+          'stableKey() needs at least one part identifying THIS payment, e.g. ' +
+          'stableKey(orgId, payrollRunId, employeeId). With no parts every ' +
+          'payout would share one key and only the first would ever be sent.',
+      },
+      undefined,
+    );
+  }
+  const empty = parts.findIndex((p) => p === undefined || p === null || p === '');
+  if (empty !== -1) {
+    throw new PayoutsError(
+      400,
+      {
+        type: 'VALIDATION_ERROR',
+        message:
+          `stableKey() part ${empty} is empty. An undefined id collapses ` +
+          'distinct payments onto one key, and every payment after the first ' +
+          'replays instead of sending.',
+      },
+      undefined,
+    );
+  }
+
+  // NUL-separated, not concatenated: ('a','bc') and ('ab','c') are different
+  // payments and must not hash alike. A separator that can appear inside an id
+  // would rebuild the same collision, and NUL cannot appear in one.
+  const hex = createHash('sha256')
+    .update(parts.map(String).join('\u0000'))
+    .digest('hex');
+  const bytes = Buffer.from(hex.slice(0, 32), 'hex');
+  // Stamp version 8 (custom/derived) and the RFC 4122 variant, so this is a
+  // well-formed UUID rather than a string that merely looks like one — and so
+  // anything parsing it can see it was derived, not drawn at random.
+  bytes[6] = (bytes[6] & 0x0f) | 0x80;
+  bytes[8] = (bytes[8] & 0x3f) | 0x80;
+  const h = bytes.toString('hex');
+  return `${h.slice(0, 8)}-${h.slice(8, 12)}-${h.slice(12, 16)}-${h.slice(16, 20)}-${h.slice(20)}`;
+}
+
+const DEFAULT_TIMEOUT_MS = 30_000;
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+/**
+ * Full jitter: random between 0 and the exponential ceiling.
+ *
+ * Not fixed backoff — a payroll batch that fails together would retry together
+ * and rebuild the spike that caused it. `Retry-After` wins when the server sent
+ * one, because it knows when the window actually resets.
+ */
+function backoffMs(attempt, retryAfterSeconds) {
+  if (retryAfterSeconds) return Math.min(retryAfterSeconds * 1000, 30_000);
+  const ceiling = Math.min(500 * 2 ** attempt, 8_000);
+  return Math.random() * ceiling;
+}
+
+class PayoutsClient {
+  /**
+   * @param {object} opts
+   * @param {string} opts.apiKey     Server-side only. Never ship this to a browser or a phone.
+   * @param {string} opts.orgId      Your organization id.
+   * @param {string} [opts.baseUrl]  Defaults to the AVVIO_BASE_URL env var.
+   * @param {number} [opts.timeoutMs]
+   */
+  constructor(opts = {}) {
+    this.apiKey = opts.apiKey || process.env.AVVIO_API_KEY;
+    this.orgId = opts.orgId || process.env.AVVIO_ORG_ID;
+    // `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
+    // consumer host sits behind a bot challenge, so the default used to answer
+    // a partner's server-to-server call with an HTML interstitial rather than
+    // JSON, which reads as "your key is broken" rather than "wrong host".
+    this.baseUrl = (
+      opts.baseUrl ||
+      process.env.AVVIO_BASE_URL ||
+      'https://api.avvio.xyz/business/api/v1'
+    ).replace(/\/+$/, '');
+    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;
+
+    if (!this.apiKey) {
+      throw new Error(
+        'Missing API key. Set AVVIO_API_KEY, or pass { apiKey } to the client.',
+      );
+    }
+    if (!this.orgId) {
+      throw new Error(
+        'Missing organization id. Set AVVIO_ORG_ID, or pass { orgId } to the client.',
+      );
+    }
+
+    /**
+     * `'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.
+     */
+    this.mode = this.apiKey.startsWith('ak_test_') ? 'test' : 'live';
+  }
+
+  // ─── transport ───
+
+  /**
+   * Send, with retries.
+   *
+   * ── Why the client retries and the caller does not ──
+   *
+   * `err.retryable` was computed, documented, and told to partners to branch
+   * on — and then never acted on, so every partner wrote the same loop, and
+   * each one had to independently work out the rule that makes retrying a
+   * PAYMENT safe. That rule is subtle enough that it should not be redistributed
+   * 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.
+   *
+   * `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 = {}) {
+    const idempotent = method === 'GET' || Boolean(opts.idempotencyKey);
+    let attempt = 0;
+
+    for (;;) {
+      try {
+        return await this._send(method, path, opts);
+      } catch (err) {
+        const canRetry =
+          idempotent &&
+          attempt < this.maxRetries &&
+          err instanceof PayoutsError &&
+          err.retryable &&
+          err.type !== 'DUPLICATE_REQUEST_DETECTED';
+
+        if (!canRetry) throw err;
+
+        await sleep(backoffMs(attempt, err.retryAfterSeconds));
+        attempt += 1;
+      }
+    }
+  }
+
+  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
+    // they retry by calling us again and we mint a fresh one.
+    const tag = (err) => {
+      if (idempotencyKey) err.idempotencyKey = idempotencyKey;
+      return err;
+    };
+    const url = new URL(this.baseUrl + path);
+    for (const [k, v] of Object.entries(query || {})) {
+      if (v !== undefined && v !== null && v !== '') url.searchParams.set(k, v);
+    }
+
+    const headers = { 'x-api-key': this.apiKey };
+    if (body) headers['content-type'] = 'application/json';
+    // Mutations always carry one. Generating it here rather than making the
+    // caller remember means the safe thing is the default thing; a caller that
+    // wants retry-across-process-restarts passes their own stable value.
+    if (idempotencyKey) headers['idempotency-key'] = idempotencyKey;
+    Object.assign(headers, extra || {});
+
+    let res;
+    try {
+      res = await fetch(url, {
+        method,
+        headers,
+        body: body ? JSON.stringify(body) : undefined,
+        signal: AbortSignal.timeout(this.timeoutMs),
+      });
+    } catch (err) {
+      // A timeout is an UNKNOWN outcome, not a failure. If this was a send, the
+      // payout may well have been accepted — so the instruction is to retry the
+      // same idempotency key, never to start again.
+      const isTimeout = err && err.name === 'TimeoutError';
+      const e = new PayoutsError(
+        isTimeout ? 504 : 502,
+        {
+          type: isTimeout ? 'TIMEOUT' : 'NETWORK_ERROR',
+          message: isTimeout
+            ? `No response within ${this.timeoutMs}ms. The outcome is unknown — retry with the SAME idempotency key.`
+            : `Could not reach ${url.host}: ${err && err.message}`,
+        },
+        undefined,
+      );
+      throw tag(e);
+    }
+
+    const requestId = res.headers.get('x-request-id') || undefined;
+    const replayed = res.headers.get('idempotency-replayed') === 'true';
+    const text = await res.text();
+    let parsed;
+    try {
+      parsed = text ? JSON.parse(text) : undefined;
+    } catch {
+      parsed = { message: text.slice(0, 500) };
+    }
+
+    if (!res.ok) {
+      const err = new PayoutsError(res.status, parsed, requestId);
+      // The server tells us when its window resets; guessing is worse. Only
+      // present on a 429, which is the one case where the wait is knowable.
+      const after = Number(res.headers.get('retry-after'));
+      if (Number.isFinite(after) && after > 0) err.retryAfterSeconds = after;
+      throw tag(err);
+    }
+    if (idempotencyKey && parsed && typeof parsed === 'object') {
+      // Non-enumerable so it never pollutes a partner's stored payload, but
+      // reachable for logging and for a retry after a later failure.
+      Object.defineProperty(parsed, 'idempotencyKey', {
+        value: idempotencyKey,
+        enumerable: false,
+      });
+    }
+    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 });
+    }
+    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`);
+  }
+
+  /**
+   * What a beneficiary in this currency requires.
+   *
+   * Read this rather than hardcoding a form: the field set and the field NAMES
+   * 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 match = (corridors || []).find(
+      (c) => String(c.currency || '').toUpperCase() === want,
+    );
+    if (!match) {
+      const available = (corridors || []).map((c) => c.currency).join(', ');
+      // A PayoutsError, not a bare Error. The docs say "branch on `type`,
+      // always" — and this was the one failure in the package that had no
+      // `type`, `status` or `retryable`, so code written exactly as instructed
+      // fell straight through the branch it was told to write.
+      throw new PayoutsError(
+        400,
+        {
+          type: 'CORRIDOR_UNAVAILABLE',
+          message: `No ${want} corridor is available for this organization. Available: ${available}`,
+        },
+        undefined,
+      );
+    }
+    return match;
+  }
+
+  // ─── pricing ───
+
+  /**
+   * Indicative price for a corridor, with no beneficiary in existence.
+   *
+   * This is what you show while someone is still typing an amount. It is an
+   * estimate: the binding number is locked when you quote against a real
+   * beneficiary.
+   */
+  quote({ amount, to, from = 'USD' }) {
+    return this.request('GET', `/payments/organizations/${this.orgId}/rates`, {
+      query: { from, to, amount },
+    });
+  }
+
+  // ─── beneficiaries ───
+
+  /**
+   * @param {object} p
+   * @param {string} p.endUserId  YOUR id for the person sending. Scopes the
+   *   beneficiary to them, so listing for that id returns only what they added.
+   * @param {object} p.details    The corridor's fields, from requirements().
+   */
+  createBeneficiary(p) {
+    const body = {
+      type: p.type || 'individual',
+      name: p.name,
+      email: p.email,
+      country: p.country,
+      externalId: p.externalId,
+      endUserId: p.endUserId,
+      method: {
+        kind: 'fiat',
+        currency: p.currency,
+        recipientDetails: p.details || {},
+      },
+    };
+    return this.request('POST', `/recipients/${this.orgId}`, {
+      body,
+      idempotencyKey: p.idempotencyKey || randomUUID(),
+    });
+  }
+
+  listBeneficiaries({ endUserId, limit, cursor } = {}) {
+    return this.request('GET', `/recipients/${this.orgId}`, {
+      query: { endUserId, limit, cursor },
+    });
+  }
+
+  // ─── paying ───
+
+  /**
+   * Price a payout against a real beneficiary. Nothing moves.
+   *
+   * The returned snapshot is what `send` executes; it has an expiry, so quote
+   * and send close together.
+   */
+  pricePayout({ amount, destinationAccountId, purposeOfPayment }) {
+    return this.request(
+      'POST',
+      `/payments/organizations/${this.orgId}/quotes/offramp`,
+      { body: { amount, destinationAccountId, purposeOfPayment } },
+    );
+  }
+
+  /**
+   * Execute. This is the step that moves money.
+   *
+   * If it times out, retry with the SAME idempotencyKey — a replay returns the
+   * original payout. Re-quoting instead is a second payment.
+   */
+  send({ snapshotId, quoteId, endUser, reference, idempotencyKey }) {
+    return this.request(
+      'POST',
+      `/payments/organizations/${this.orgId}/quotes/accept`,
+      {
+        body: {
+          snapshotId,
+          quoteId,
+          type: 'OFFRAMP',
+          reference,
+          endUser,
+        },
+        idempotencyKey: idempotencyKey || randomUUID(),
+      },
+    );
+  }
+
+  /**
+   * Send a payout. One request.
+   *
+   * Deliberately NOT price-then-send from here. That sequence is not
+   * retry-safe: a retry re-prices, produces a different quote, and therefore a
+   * different request body — so the idempotency key that was supposed to
+   * protect the retry conflicts with itself instead. The server prices and
+   * sends in one call, which makes the body a partner can retry a stable one.
+   *
+   * `expectDestination` is the guard: pass what you told the payer they would
+   * 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.
+   */
+  payout(p) {
+    const expect =
+      p.expectDestination !== undefined
+        ? p.expectDestination
+        : p.expectDestinationAmount;
+    return this.request(
+      'POST',
+      `/payments/organizations/${this.orgId}/payouts`,
+      {
+        body: {
+          amount: p.amount,
+          destinationAccountId: p.destinationAccountId,
+          ...(expect !== undefined ? { expectDestination: String(expect) } : {}),
+          ...(p.maxRateDrift !== undefined
+            ? { maxDriftBps: toDriftBps(p.maxRateDrift) }
+            : {}),
+          ...(p.reference ? { reference: p.reference } : {}),
+          ...(p.purposeOfPayment
+            ? { purposeOfPayment: p.purposeOfPayment }
+            : {}),
+          ...(p.endUser ? { endUser: p.endUser } : {}),
+        },
+        idempotencyKey: p.idempotencyKey || randomUUID(),
+        // 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' } } : {}),
+      },
+    );
+  }
+
+  // ─── reading ───
+
+  /**
+   * Everything that has happened to your payouts, in order.
+   *
+   * The reconciliation primitive. Events are written once and never change, so
+   * carrying `nextSince` gives you exactly what is new — including a bank return
+   * that lands days after you booked the payout as settled.
+   *
+   * At-least-once: dedupe on `id`.
+   */
+  listEvents({ since, limit, payoutId } = {}) {
+    return this.request('GET', `/payments/organizations/${this.orgId}/events`, {
+      query: { since, limit, payoutId },
+    });
+  }
+
+  /**
+   * Every event since a watermark, paged for you.
+   *
+   *   for await (const e of avvio.eachEvent({ since: saved })) { … }
+   *
+   * The two list endpoints page differently — payouts use `nextCursor`, events
+   * use `nextSince` — and the reconciliation loop the docs tell partners to
+   * build is the one place that difference bites. Every partner writes the same
+   * while-loop, and the one that gets it subtly wrong stops reconciling
+   * silently. Written once, here.
+   *
+   * 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 } = {}) {
+    let cursor = since;
+    for (;;) {
+      const page = await this.listEvents({ since: cursor, limit, payoutId });
+      for (const event of page.data || []) yield event;
+      if (!page.hasMore || !page.nextSince || page.nextSince === cursor) return;
+      cursor = page.nextSince;
+    }
+  }
+
+  /**
+   * Every payout matching a filter, paged for you.
+   *
+   *   for await (const p of avvio.eachPayout({ status: 'failed' })) { … }
+   *
+   * Stops when the server says there is no more. It does NOT stop on an empty
+   * page alone — a cursor we did not issue is a 400, not an empty page, so an
+   * 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 } = {}) {
+    let cursor;
+    for (;;) {
+      const page = await this.listPayouts({
+        limit,
+        cursor,
+        status,
+        endUserId,
+        reference,
+        updatedSince,
+      });
+      for (const payout of page.data || []) yield payout;
+      if (!page.hasMore || !page.nextCursor || page.nextCursor === cursor) return;
+      cursor = page.nextCursor;
+    }
+  }
+
+  /**
+   * 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.
+   */
+  getFunding(payoutId) {
+    return this.request(
+      'GET',
+      `/payments/organizations/${this.orgId}/payouts/${encodeURIComponent(payoutId)}/funding`,
+    );
+  }
+
+  /**
+   * 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.
+   */
+  confirmFunding(payoutId, proof = {}) {
+    return this.request(
+      'POST',
+      `/payments/organizations/${this.orgId}/payouts/${encodeURIComponent(payoutId)}/funding/confirm`,
+      {
+        body: {
+          ...(proof.transactionHash
+            ? { transactionHash: proof.transactionHash }
+            : {}),
+          ...(proof.signedOperations
+            ? { signedOperations: proof.signedOperations }
+            : {}),
+          ...(proof.tamperProofSignature
+            ? { tamperProofSignature: proof.tamperProofSignature }
+            : {}),
+        },
+        idempotencyKey: proof.idempotencyKey || randomUUID(),
+      },
+    );
+  }
+
+  getPayout(payoutId) {
+    return this.request(
+      'GET',
+      `/payments/organizations/${this.orgId}/orders/${encodeURIComponent(payoutId)}`,
+    );
+  }
+
+  /**
+   * Stop a payout that has NOT been funded yet.
+   *
+   * The API has documented this since the beginning and the SDK never exposed
+   * it, so a Node partner who created a `requiresFunding` payout by mistake had
+   * no supported way to stop it — the one recovery an operator actually reaches
+   * for.
+   *
+   * Once a payout is funded it cannot be cancelled: you get
+   * `PAYOUT_NOT_CANCELABLE`, which is the honest answer rather than a
+   * cancellation that does not happen.
+   */
+  cancelPayout(payoutId, { idempotencyKey } = {}) {
+    return this.request(
+      'POST',
+      `/payments/organizations/${this.orgId}/payouts/${encodeURIComponent(payoutId)}/cancel`,
+      { idempotencyKey },
+    );
+  }
+
+  /**
+   * A PAGE of payouts: `{ data, hasMore, nextCursor }`, not an array. The type
+   * declaration used to claim an array, so code written off it threw on the
+   * first call.
+   */
+  listPayouts({ limit, cursor, status, endUserId, reference, updatedSince } = {}) {
+    return this.request('GET', `/payments/organizations/${this.orgId}/orders`, {
+      query: { limit, cursor, status, endUserId, reference, updatedSince },
+    });
+  }
+
+  /** Sandbox only: credit the test balance so you can send. */
+  /**
+   * Register a sandbox webhook endpoint and get its signing secret.
+   *
+   * The secret is returned ONCE and is not retrievable afterwards, which is why
+   * 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.
+   */
+  createWebhookEndpoint({ url, events, idempotencyKey } = {}) {
+    return this.request(
+      'POST',
+      `/payments/organizations/${this.orgId}/sandbox/webhook-endpoints`,
+      {
+        body: { url, ...(events ? { events } : {}) },
+        idempotencyKey: idempotencyKey || randomUUID(),
+      },
+    );
+  }
+
+  /** What we sent, what came back, and what we retried. */
+  webhookDeliveries(endpointId) {
+    return this.request(
+      'GET',
+      `/payments/organizations/${this.orgId}/sandbox/webhook-endpoints/${encodeURIComponent(endpointId)}/deliveries`,
+    );
+  }
+
+  /**
+   * Mint a one-time link for the person being paid.
+   *
+   * Use this instead of `createBeneficiary` + `payout()` when you would rather
+   * not collect bank details yourself — the recipient enters their own, so the
+   * details never touch your systems or your compliance surface.
+   *
+   * The idempotency key is carried onto the link, so the payout it eventually
+   * creates deduplicates against YOUR retry rather than only against ours.
+   */
+  createPayoutLink(p = {}) {
+    return this.request(
+      'POST',
+      `/payments/organizations/${this.orgId}/payout-links`,
+      {
+        body: {
+          amount: p.amount,
+          destinationCurrency: p.destinationCurrency ?? p.to,
+          endUserId: p.endUserId,
+          ...(p.reference ? { reference: p.reference } : {}),
+          ...(p.expiresInMinutes
+            ? { expiresInMinutes: p.expiresInMinutes }
+            : {}),
+        },
+        idempotencyKey: p.idempotencyKey || randomUUID(),
+      },
+    );
+  }
+
+  /**
+   * 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.
+   */
+  balanceHistory(limit) {
+    return this.request(
+      'GET',
+      `/payments/organizations/${this.orgId}/balance/history`,
+      { query: { limit } },
+    );
+  }
+
+  fund(amount = '5000.00', idempotencyKey) {
+    return this.request(
+      'POST',
+      `/payments/organizations/${this.orgId}/sandbox/fund`,
+      { body: { amount }, idempotencyKey: idempotencyKey || randomUUID() },
+    );
+  }
+
+  /** 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(
+      'GET',
+      `/payments/organizations/${this.orgId}/payin-accounts`,
+    );
+  }
+}
+
+const {
+  verifyWebhook,
+  // Declared in index.d.ts and documented, and until now exported only from
+  // `./webhooks` — so `require('@avvio/payments').createWebhookHandler` was
+  // undefined against a type declaration that promised a function. That is the
+  // same declared-but-missing failure this package has been bitten by three
+  // times, in the surface the docs tell you to build first.
+  createWebhookHandler,
+  WebhookVerificationError,
+} = require('./webhooks');
+
+module.exports = {
+  PayoutsClient,
+  PayoutsError,
+  stableKey,
+  verifyWebhook,
+  createWebhookHandler,
+  WebhookVerificationError,
+};