@avvio/payments 0.1.0

package/index.d.ts

@@ -0,0 +1,680 @@
+/**
+ * Types for @avvio/payments.
+ *
+ * Hand-written rather than generated, and shipped as a plain `.d.ts` alongside
+ * the JavaScript: TypeScript as a build step would add a compile to a package
+ * whose selling point is that there is nothing to compile, and a devDependency
+ * is still a dependency to explain. This file adds no runtime surface at all.
+ */
+
+/** An amount and its currency. Decimal strings — never floats. */
+export interface Money {
+  currency: string;
+  amount: string;
+}
+
+/** The whole partner-facing status vocabulary. */
+export type PayoutStatus =
+  | 'pending'
+  | 'processing'
+  | 'completed'
+  | 'failed'
+  | 'canceled';
+
+/**
+ * Why a payout did not land. Treat an unrecognised value as `execution_failed`
+ * — new codes are added without a major version.
+ */
+export type PayoutFailureCode =
+  | 'quote_expired'
+  | 'insufficient_funds'
+  | 'limit_exceeded'
+  | 'account_invalid'
+  | 'account_cannot_receive'
+  | 'compliance_rejected'
+  | 'authorization_not_completed'
+  | 'returned_by_bank'
+  | 'execution_failed'
+  | 'canceled_by_platform'
+  | 'unknown';
+
+/** Informational only. Never branch integration behaviour on it. */
+export type PayoutStage = 'awaiting_details' | 'under_review' | 'settling';
+
+export interface EndUser {
+  id?: string;
+  name?: string;
+  email?: string;
+}
+
+export interface Payout {
+  payoutId: string;
+  status: PayoutStatus;
+  /**
+   * Present and true when this payout waits on YOU to fund it from your own
+   * wallet. Absent on routings that settle on acceptance, so its presence is
+   * the signal — call `getFunding()`.
+   */
+  requiresFunding?: boolean;
+  /** When this payout last changed. Your `updatedSince` watermark. */
+  updatedAt?: string;
+  stage?: PayoutStage;
+  failureCode?: PayoutFailureCode;
+  /**
+   * Whether the money is back in your balance. Absent means not established
+   * yet — deliberately not `false`, which would be a claim we cannot support.
+   */
+  fundsReturned?: boolean;
+  sourceAmount: Money | null;
+  destinationAmount: Money | null;
+  destinationAccountId: string | null;
+  rate: string | null;
+  reference: string | null;
+  endUser: EndUser | null;
+  createdAt: string | null;
+  completedAt: string | null;
+}
+
+export interface PreviewQuote {
+  /** Always true. This is an estimate; the binding price comes at send. */
+  indicative: true;
+  sourceAmount: Money;
+  destinationAmount: Money;
+  /** Deducted from the send: destinationAmount = (sourceAmount - fee) x rate. */
+  fee: Money;
+  totalDebit: Money;
+  rate: string;
+  limits: { min: string; max: string };
+}
+
+export interface CorridorField {
+  id: string;
+  title: string;
+  type: string;
+  pattern?: string;
+  required: boolean;
+  description?: string;
+}
+
+export interface Corridor {
+  currency: string;
+  fields: CorridorField[];
+  limits?: { min: string; max: string };
+}
+
+export interface BeneficiaryMethod {
+  id: string;
+  kind: string;
+  currency: string | null;
+  last4: string | null;
+  status: string;
+  /** Pass this as `destinationAccountId` when paying. */
+  destinationAccountId: string | null;
+}
+
+export interface Beneficiary {
+  id: string;
+  name: string;
+  email?: string;
+  country?: string;
+  externalId?: string;
+  endUserId?: string | null;
+  paymentMethods: BeneficiaryMethod[];
+}
+
+/**
+ * Every `type` the API and this client can produce.
+ *
+ * Declared as a bare `string` until now, so the `switch (err.type)` the docs
+ * insist on could not be checked at all: a typo'd case compiled, an unhandled
+ * one compiled, and the branch that decides whether a payment is retried was
+ * the least-typed code a partner wrote.
+ *
+ * `(string & {})` is deliberately kept in the union. New types are added
+ * without a major version, so an unrecognised one must still compile — the
+ * alternative is a partner pinned to an old package failing to build against a
+ * live API. It costs the exhaustiveness check on the `default` branch, which is
+ * the branch you should be writing anyway.
+ *
+ * Kept in step with `docs/partner/ERRORS.md` by a test, not by hand.
+ */
+export type PayoutsErrorType =
+  // General
+  | 'VALIDATION_ERROR'
+  | 'UNAUTHORIZED'
+  | 'FORBIDDEN'
+  | 'NOT_FOUND'
+  | 'RATE_LIMITED'
+  | 'BAD_REQUEST'
+  | 'PROVIDER_REJECTED'
+  | 'FUNDING_TRANSACTION_INVALID'
+  | 'FUNDING_NOT_YET_VERIFIABLE'
+  | 'FUNDING_TRANSACTION_ALREADY_USED'
+  | 'PAYOUT_NOT_FUNDABLE'
+  | 'BENEFICIARY_EXTERNAL_ID_CONFLICT'
+  | 'CONFLICT'
+  | 'ACCOUNT_BLOCKED'
+  | 'INSUFFICIENT_BALANCE'
+  | 'ORDERS_TEMPORARILY_UNAVAILABLE'
+  | 'INTERNAL'
+  // Idempotency
+  | 'IDEMPOTENCY_KEY_REQUIRED'
+  | 'IDEMPOTENCY_KEY_INVALID'
+  | 'IDEMPOTENCY_KEY_CONFLICT'
+  | 'IDEMPOTENCY_KEY_REQUEST_IN_PROGRESS'
+  | 'IDEMPOTENCY_UNAVAILABLE'
+  | 'DUPLICATE_REQUEST_DETECTED'
+  // Paying
+  | 'DESTINATION_ACCOUNT_NOT_FOUND'
+  | 'RATE_DRIFT_EXCEEDED'
+  | 'QUOTE_UNVERIFIABLE'
+  | 'EXACT_OUTPUT_UNSUPPORTED'
+  | 'PAYOUT_NOT_CANCELABLE'
+  | 'INSUFFICIENT_SCOPE'
+  | 'INDICATIVE_PRICING_UNAVAILABLE'
+  | 'PAYOUT_LINK_UNUSABLE'
+  // 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.
+  | 'TIMEOUT'
+  | 'NETWORK_ERROR'
+  | 'CORRIDOR_UNAVAILABLE'
+  | (string & {});
+
+export declare class PayoutsError extends Error {
+  readonly name: 'PayoutsError';
+  /** Stable machine-readable code. Branch on this, not on the message. */
+  readonly type: PayoutsErrorType;
+  readonly status: number;
+  readonly requestId?: string;
+  /**
+   * The key the failed request used. On a timeout, retry with THIS value — a
+   * new one is a second payment.
+   */
+  readonly idempotencyKey?: string;
+  readonly body?: unknown;
+  /** Whether retrying the identical request unchanged is worth doing. */
+  readonly retryable: boolean;
+}
+
+export interface PayoutsClientOptions {
+  /** Server-side only. Never ship to a browser or a mobile app. */
+  apiKey?: string;
+  orgId?: string;
+  baseUrl?: string;
+  timeoutMs?: number;
+}
+
+export interface PayoutArgs {
+  amount: string;
+  destinationAccountId: string;
+  /**
+   * 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
+   * whatever the rate did between quoting and sending.
+   */
+  expectDestinationAmount?: string;
+  /**
+   * Alias of `expectDestinationAmount`, accepted at runtime and used by every
+   * example in the README. It was undeclared, so a TypeScript user copying the
+   * documented example got a compile error on the drift guard — the one field
+   * the docs insist you should never skip.
+   */
+  expectDestination?: string;
+  /** Fractional, so 0.02 is 2%. Defaults to 0.02. */
+  maxRateDrift?: number;
+  /** Reuse to retry safely. Generated if omitted. */
+  idempotencyKey?: string;
+  /**
+   * On `DUPLICATE_REQUEST_DETECTED` only. Re-send with this VALUE as your
+   * `idempotencyKey` to replay the original payout instead of making a second
+   * one. Set by the client at runtime and previously undeclared — so the
+   * recovery path both ERRORS.md and the README instruct you to take did not
+   * typecheck, on the guard whose entire purpose is preventing a double
+   * payment.
+   */
+  originalIdempotencyKey?: string;
+  /** On `DUPLICATE_REQUEST_DETECTED` only. The payout the first request made. */
+  originalPayoutId?: string;
+  /**
+   * Send a SECOND real payment when an identical body was seen in the last 15
+   * minutes. Sets `X-Allow-Duplicate: true`. Used by the README's recovery
+   * example and previously undeclared.
+   *
+   * This is the branch that pays twice. To REPLAY the original instead, re-send
+   * with `idempotencyKey` set to the `originalIdempotencyKey` value from the
+   * 409 body.
+   */
+  allowDuplicate?: boolean;
+  reference?: string;
+  purposeOfPayment?: string;
+  endUser?: EndUser;
+}
+
+export declare class PayoutsClient {
+  constructor(opts?: PayoutsClientOptions);
+
+  /**
+   * Which world this key pays into, from its prefix. Assert on it in your own
+   * 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.
+   */
+  readonly mode: 'test' | 'live';
+
+  /**
+   * The currencies you can pay out to, and what this routing can do.
+   *
+   * `capabilities` was missing from this declaration while the docs said
+   * "check `capabilities.exactOutput` on the corridors call" — so a TypeScript
+   * caller following the instruction had no typed path to the field and had to
+   * reach for an unsound cast.
+   */
+  corridors(): Promise<{
+    corridors: Corridor[];
+    capabilities: { exactOutput: boolean; indicativePricing: boolean };
+  }>;
+  requirements(currency: string): Promise<Corridor>;
+
+  quote(args: {
+    amount: string;
+    to: string;
+    from?: string;
+  }): Promise<PreviewQuote>;
+
+  createBeneficiary(args: {
+    name: string;
+    currency: string;
+    details: Record<string, string>;
+    /** REQUIRED. The server rejects a create without it. */
+    email: string;
+    type?: 'individual' | 'business';
+    country?: string;
+    /** YOUR id for the person SENDING. Scopes the beneficiary to them. */
+    endUserId?: string;
+    /** YOUR id for this beneficiary. Makes a repeat create safe. */
+    externalId?: string;
+    idempotencyKey?: string;
+  }): Promise<Beneficiary>;
+
+  listBeneficiaries(args?: {
+    endUserId?: string;
+  }): Promise<{
+    /** 'organization' or the end user the list was scoped to. Undeclared previously. */
+    scope: string;
+    recipients: Beneficiary[];
+    /**
+     * This route is NOT paginated today — these never appear. Kept optional so
+     * adding pagination later is not a breaking change.
+     */
+    hasMore?: boolean;
+    nextCursor?: string | null;
+  }>;
+
+  /**
+   * 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
+   * `id`.
+   */
+  eachEvent(args?: {
+    since?: string;
+    limit?: number;
+    payoutId?: string;
+  }): AsyncIterableIterator<PayoutEvent>;
+
+  /** Every payout matching a filter, paged for you. */
+  eachPayout(args?: {
+    limit?: number;
+    status?: string;
+    endUserId?: string;
+    reference?: string;
+    updatedSince?: string;
+  }): AsyncIterableIterator<Payout>;
+
+  /**
+   * The raw escape hatch: any method, any path, with auth and error handling
+   * applied. For an endpoint the typed methods do not cover yet.
+   *
+   * Implemented since the beginning and undeclared until now, so a TypeScript
+   * user could not reach the one method that exists for reaching everything
+   * else.
+   */
+  request(
+    method: string,
+    path: string,
+    opts?: {
+      body?: unknown;
+      query?: Record<string, unknown>;
+      idempotencyKey?: string;
+      headers?: Record<string, string>;
+    },
+  ): Promise<unknown>;
+
+  /**
+   * Stop a payout that has not been funded yet. Once funded it cannot be
+   * cancelled — you get `PAYOUT_NOT_CANCELABLE`, which is the honest answer.
+   */
+  cancelPayout(
+    payoutId: string,
+    opts?: { idempotencyKey?: string },
+  ): Promise<Payout>;
+
+  /**
+   * The two halves of `createPayout`, exposed for callers that need to show a
+   * binding quote before committing. Both are implemented and were undeclared,
+   * so TypeScript users could not reach them.
+   */
+  pricePayout(args: {
+    amount: string;
+    destinationAccountId: string;
+    purposeOfPayment?: string;
+    // Deliberately loose: the snapshot is the rail's own quote object and its
+    // shape varies by routing. Pass it straight back to `send()`.
+  }): Promise<{ id: string; best_quote_id?: string; [k: string]: unknown }>;
+
+  send(args: {
+    snapshotId: string;
+    quoteId?: string;
+    endUser?: EndUser;
+    reference?: string;
+    idempotencyKey?: string;
+  }): Promise<Payout>;
+
+  /** Price and send in one call, with the drift guard applied. */
+  payout(args: PayoutArgs): Promise<Payout>;
+
+  /**
+   * 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, which listing
+   * payouts (ordered by creation) can never surface.
+   *
+   * At-least-once: dedupe on `id`.
+   */
+  listEvents(args?: {
+    /** The `nextSince` from your last page. */
+    since?: string;
+    limit?: number;
+    /** Everything that ever happened to one payout. */
+    payoutId?: string;
+  }): Promise<{
+    data: PayoutEvent[];
+    hasMore: boolean;
+    nextSince: string | null;
+  }>;
+
+  /**
+   * How to fund a payout that came back with `requiresFunding: true`. Your funds
+   * stay in your wallet until you move them.
+   */
+  getFunding(payoutId: string): Promise<{
+    payoutId: string;
+    amount: string;
+    currency: string;
+    depositAddress: string;
+    network: string;
+    expiresAt: string;
+    /** Present when you can sign through this API instead of broadcasting. */
+    signableOperations?: unknown[];
+    instructions: string;
+  }>;
+
+  /** Proof you sent the funds: a hash you broadcast, or operations you signed. */
+  confirmFunding(
+    payoutId: string,
+    proof: {
+      transactionHash?: string;
+      signedOperations?: unknown[];
+      tamperProofSignature?: string;
+      idempotencyKey?: string;
+    },
+  ): Promise<Payout>;
+
+  /** Always live. More authoritative than a webhook you may have missed. */
+  getPayout(payoutId: string): Promise<Payout>;
+  /**
+   * A PAGE of payouts, not an array.
+   *
+   * This was declared as `Payout[]`, so code written straight off the type —
+   * `payouts.map(...)`, `payouts.length` — threw a TypeError on the first call.
+   * In a reconciliation job wrapped in try/catch that is a silently skipped
+   * cycle rather than an alert.
+   */
+  listPayouts(args?: {
+    limit?: number;
+    cursor?: string;
+    status?: string;
+    endUserId?: string;
+    reference?: string;
+    /**
+     * **The change feed.** Payouts whose state changed at or after this time,
+     * oldest-changed first.
+     *
+     * Ordinary listing is newest-first by CREATION, which by construction can
+     * never tell you an OLD payout changed — and `completed → failed` on a bank
+     * return, days later, is exactly the change a ledger cannot afford to miss.
+     * Page forward, carry the highest `updatedAt` you have seen as your
+     * watermark, and you observe every revision at least once.
+     *
+     * `updatedSince` is INCLUSIVE, so resuming re-reads the row at your
+     * watermark. Dedupe on payoutId + updatedAt.
+     */
+    updatedSince?: string;
+  }): Promise<{ data: Payout[]; hasMore: boolean; nextCursor: string | null }>;
+
+  fundingAccounts(): Promise<unknown>;
+
+  /** What you can currently send. */
+  balance(): Promise<{ currency: string; amount: string }>;
+
+  /**
+   * Why the balance is what it is: every movement with the running balance
+   * after it. Reconcile against this rather than trusting a single number.
+   */
+  balanceHistory(limit?: number): 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;
+    }[];
+  }>;
+
+  /** Credit a sandbox balance. Test keys only. */
+  fund(amount?: string, idempotencyKey?: string): Promise<{ balance: string }>;
+
+  /**
+   * Mint a one-time link for the person being paid, so they enter their own
+   * bank details and you never hold them.
+   *
+   * The token the recipient's page needs is the part of `url` after `/l/`.
+   */
+  createPayoutLink(args: {
+    amount: string;
+    /** e.g. 'MXN'. `to` is accepted as an alias. */
+    destinationCurrency?: string;
+    to?: string;
+    endUserId: string;
+    reference?: string;
+    /** Defaults to 60. Capped at 7 days. */
+    expiresInMinutes?: number;
+    idempotencyKey?: string;
+  }): Promise<{
+    payoutLinkId: string;
+    url: string;
+    expiresAt: string;
+    status: string;
+  }>;
+
+  /**
+   * Register a sandbox webhook endpoint. The `secret` is returned ONCE and is
+   * not retrievable afterwards. Test keys only.
+   */
+  createWebhookEndpoint(args: {
+    url: string;
+    events?: string[];
+    idempotencyKey?: string;
+  }): Promise<{
+    id: string;
+    url: string;
+    events: string[];
+    secret: string;
+    warning: string;
+  }>;
+
+  /** What we sent, what came back, and what we retried. */
+  webhookDeliveries(endpointId: string): Promise<unknown>;
+}
+
+export declare class WebhookVerificationError extends Error {
+  readonly name: 'WebhookVerificationError';
+}
+
+/**
+ * A deterministic idempotency key, formatted as a UUID.
+ *
+ *   stableKey(orgId, payrollRunId, employeeId)
+ *
+ * The same parts always produce the same key, so a job that crashes and
+ * requeues retries into a REPLAY rather than sending a second payment. The
+ * generated `randomUUID()` a call gets by default cannot do that: it is new on
+ * every attempt, which is precisely the restart the retry docs are about.
+ *
+ * Parts are NUL-separated, so `('a','bc')` and `('ab','c')` are different keys.
+ * An empty or missing part throws rather than silently collapsing two people's
+ * wages onto one key.
+ */
+export declare function stableKey(...parts: (string | number)[]): string;
+
+/**
+ * The payout as it appears INSIDE A WEBHOOK.
+ *
+ * Deliberately not `Payout`. The webhook body is flat — `sourceAmount` is a
+ * decimal string beside a separate `sourceCurrency` — where the REST payout
+ * nests them as `Money` objects. Declaring `data: Payout` meant that code
+ * written off the type (`event.data.sourceAmount.amount`) threw a TypeError on
+ * the first real delivery.
+ *
+ * That is the same mistake `listPayouts` made, shipped a second time in the one
+ * place the docs tell you to build first. The two shapes are now separate types
+ * so they cannot be confused, and `scripts/sdk-contract.ts` asserts this one
+ * against a real delivered event.
+ */
+export interface PayoutEvent {
+  /** Stable. Dedupe on this — the feed is at-least-once. */
+  id: string;
+  /**
+   * The cursor, as a decimal STRING. A 64-bit sequence past 2^53 is not
+   * representable as a JSON number, and losing precision on a cursor is
+   * 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;
+  failureCode?: PayoutFailureCode;
+  fundsReturned?: boolean;
+  createdAt: string;
+}
+
+export interface WebhookPayout {
+  payoutId: string;
+  status: PayoutStatus;
+  stage?: PayoutStage;
+  failureCode?: PayoutFailureCode;
+  /** Absent when not yet established. Absent is NOT the same as false. */
+  fundsReturned?: boolean;
+  /** Decimal strings, not `Money`. Currency is the adjacent field. */
+  sourceCurrency: string | null;
+  sourceAmount: string | null;
+  destinationCurrency: string | null;
+  destinationAmount: string | null;
+  destinationAccountId: string | null;
+  rate: string | null;
+  endUser: EndUser | null;
+  reference?: string | null;
+  createdAt: string;
+  completedAt: string | null;
+}
+
+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;
+}
+
+/**
+ * Verify a delivery and return its parsed body.
+ *
+ * `body` must be the RAW bytes. Re-serializing a parsed object does not
+ * reproduce the same bytes, and one reordered key fails every signature.
+ */
+export declare function verifyWebhook(args: {
+  body: string | Buffer;
+  headers: Record<string, string | string[] | undefined>;
+  secret: string;
+  toleranceSeconds?: number;
+}): WebhookEvent;
+
+/**
+ * A (req, res) handler that verifies the signature from the RAW request stream.
+ *
+ * The failure `verifyWebhook` alone cannot prevent is upstream of it: a body
+ * parser consumes and discards the raw bytes before your handler runs, and the
+ * signature is over those bytes. This reads the stream itself, so it is correct
+ * whichever middleware is mounted and in whatever order.
+ *
+ * Framework-agnostic: Express, Fastify's raw handler, or node:http.
+ */
+export declare function createWebhookHandler(opts: {
+  secret: string;
+  onEvent: (event: WebhookEvent) => void | Promise<void>;
+  /** Reject timestamps outside this window. Defaults to 300. */
+  toleranceSeconds?: number;
+}): (req: any, res: any) => Promise<void>;