@avvio/payments 0.1.0

package/README.md

@@ -0,0 +1,411 @@
+# @avvio/payments
+
+Pay out to your own customers, from your balance, over one API.
+
+One package, three ways to use it: a **Node client**, a **CLI**, and an **MCP
+server** so an agent can drive payouts directly. All three share the same core,
+so they cannot drift apart.
+
+## Zero dependencies
+
+Not a boast — a deliberate answer to a question your security review will ask.
+
+This package sits inside your infrastructure holding a credential that moves
+money. Transitive npm compromise is the most realistic path to that credential,
+and the shortest answer to "what is in this dependency tree" is *nothing*. It
+also means no peer conflicts inside your app and nothing to compile.
+
+Node 18 or newer.
+
+## Setup
+
+```bash
+npm i @avvio/payments
+```
+
+Not published yet. Until it is, install the tarball from the repo:
+
+```bash
+cd packages/avvio-payments && npm pack
+npm i /path/to/avvio-payments-0.1.0.tgz
+```
+
+```bash
+export AVVIO_API_KEY=ak_test_…      # server-side only
+export AVVIO_ORG_ID=cmsx…   # a cuid, not an org_ prefix
+export AVVIO_BASE_URL=https://api.avvio.xyz/api/v1   # optional
+```
+
+Calling the API directly instead? The credential goes in an `x-api-key`
+header, and every mutation needs an `Idempotency-Key`:
+
+```bash
+curl "$AVVIO_BASE_URL/recipients/$AVVIO_ORG_ID/corridors" \
+  -H "x-api-key: $AVVIO_API_KEY"
+```
+
+> **Never ship the key to a browser or a mobile app.** It is a bearer
+> credential for your money. Our CORS policy does not allow the header, so a
+> browser cannot send one even by accident.
+
+Start here:
+
+```bash
+npx -y @avvio/payments doctor
+```
+
+It checks the key, the organization, connectivity and your balance, and names
+which one is wrong. "It doesn't work" is otherwise four indistinguishable
+problems.
+
+## Sixty seconds to a payout
+
+```bash
+npx -y @avvio/payments guide                     # the whole flow, as commands
+npx -y @avvio/payments fund --amount 5000        # sandbox balance
+npx -y @avvio/payments corridors                 # what you can pay
+npx -y @avvio/payments requirements MXN          # what Mexico needs
+npx -y @avvio/payments quote --amount 200 --to MXN
+
+npx -y @avvio/payments beneficiary create \
+  --name "Maria Gonzalez" --email maria@example.com \
+  --currency MXN --end-user employee_42 \
+  --field clabeNumber=012345678901234567
+
+npx -y @avvio/payments pay --amount 200 --to <destinationAccountId> \
+  --end-user employee_42 --expect 3410.00
+```
+
+Use a `ak_test_` key and none of this touches a payment network. The **last four
+digits** of the account number choose what happens — `0003` completes and is
+then returned by the bank, which is the case worth testing before you go live.
+
+## Node
+
+```js
+const { PayoutsClient } = require('@avvio/payments');
+// or, from ESM — the package declares an `exports` map, so named imports work:
+// import { PayoutsClient, stableKey } from '@avvio/payments';
+// import { verifyWebhook } from '@avvio/payments/webhooks';
+
+const avvio = new PayoutsClient();
+
+// Which world this key pays into, from its prefix. Worth asserting in your own
+// test suite before anything sends: a live key in a payroll fixture pays real
+// people. Anything not recognisably `ak_test_` reports 'live'.
+if (avvio.mode !== 'test') throw new Error('refusing to run tests against live');
+
+// Show the price while your user is still typing. No beneficiary needed.
+const quote = await avvio.quote({ amount: '200.00', to: 'MXN' });
+// → { sourceAmount, destinationAmount, fee, rate, limits, indicative: true }
+
+const beneficiary = await avvio.createBeneficiary({
+  name: 'Maria Gonzalez',
+  email: 'maria@example.com',
+  currency: 'MXN',
+  endUserId: 'employee_42',          // scopes it to ONE of your users
+  externalId: 'emp42_maria',         // makes a repeat create safe
+  details: { clabeNumber: '012345678901234567' },
+});
+
+const payout = await avvio.payout({
+  amount: '200.00',
+  destinationAccountId: beneficiary.paymentMethods[0].destinationAccountId,
+  expectDestination: quote.destinationAmount.amount,   // read this next
+  endUser: { id: 'employee_42', name: 'Ana Lopez' },
+  reference: 'ZZ-2026-0042',
+});
+```
+
+**`expectDestination` is the one option not to skip.** (The CLI spells it `--expect`; the wire field is
+`expectDestination`. This client also accepts `expectDestinationAmount` and
+translates it — but that is a courtesy of the Node client only, so if you are
+generating a client from the OpenAPI spec, `expectDestination` is the only name
+that exists.) Between the quote
+you showed your user and the send, the rate can move. Pass the number you
+promised and the send is refused if it has drifted more than 2% — nothing is
+sent, and you re-quote. Without it, you ship whatever the market did in between.
+
+## Retrying safely
+
+**Persist your own `idempotencyKey` before you send, and reuse it on every
+retry.** That single habit is what prevents a double payment; everything else on
+this page is a safety net under it.
+
+We generate a key when you omit one, which makes a single call safe — and means
+**calling `payout()` again is not a retry**, it is a second payment with a second
+key. A job that crashes and requeues without having persisted its key will
+eventually pay a wage twice. Our server-side duplicate check covers 15 minutes of
+that gap; a backoff longer than 15 minutes is outside it, by design and by
+arithmetic.
+
+Retry with the *same* key and you get the original result, never a second
+payment.
+
+**If you would rather not persist one, derive it.** `stableKey()` hashes the
+things that make the payment unique into a UUID, so the same payroll row
+produces the same key on every attempt — including the attempt after the crash,
+where there is nothing left in memory to reuse and nothing was written down:
+
+```js
+const { stableKey } = require('@avvio/payments');
+
+await avvio.payout({
+  ...args,
+  idempotencyKey: stableKey(orgId, payrollRunId, employeeId),
+});
+```
+
+Pass whatever identifies *this* payment and nothing that changes between
+attempts — a timestamp or a retry counter in there defeats the whole thing.
+Parts are NUL-separated, so `('a','bc')` and `('ab','c')` are different keys,
+and an empty part throws rather than quietly collapsing two people's wages onto
+one key.
+
+**A timeout is an unknown outcome, not a failure.** If a send times out the
+payout may exist. The key is on the error:
+
+```js
+try {
+  await avvio.payout({ ...args });
+} catch (err) {
+  if (err.type === 'TIMEOUT') {
+    // Same key. A replay returns the original payout; a new one pays twice.
+    await avvio.payout({ ...args, idempotencyKey: err.idempotencyKey });
+  }
+}
+```
+
+The drift guard throws the same `RATE_DRIFT_EXCEEDED` you would get over
+HTTP, so one branch handles both surfaces.
+
+`err.retryable` tells you whether retrying unchanged is worth it. A `409`
+conflict is **not** retryable — it means the same key was used with a different
+body, which is a bug on your side.
+
+### The retry that quietly defeats all of this
+
+`payout()` generates a key when you do not pass one. That makes the safe thing
+the default for a single call — and it means **calling `payout()` again is not a
+retry**, it is a second payment with a second key. An HTTP client that mints a
+key per attempt has the same shape, and it is the most common way a retry turns
+into a double charge: key-based replay never fires, because every attempt looks
+like a new request.
+
+So we watch a second signal server-side: same body, different key, inside 15
+minutes. You get a `409` instead of a payment. It applies only to routes that
+move money — registering the same beneficiary twice is not a duplicate payment
+and is not refused.
+
+```js
+try {
+  await avvio.payout({ ...args });
+} catch (err) {
+  if (err.type === 'DUPLICATE_REQUEST_DETECTED') {
+    // Nothing was sent. Two ways forward — pick one, we will not guess.
+    await avvio.payout({ ...args, idempotencyKey: err.originalIdempotencyKey });
+    // …or, if you really do mean to send it twice:
+    // await avvio.payout({ ...args, allowDuplicate: true });
+  }
+}
+```
+
+It refuses rather than returning the first payout, because both readings happen.
+Two advances of the same amount to the same worker in one week is ordinary
+payroll — replaying there would mean the second never goes out while your ledger
+says it did. **The best outcome for a genuinely ambiguous request is a loud one.**
+
+Retention is seven days, and it is about storage, not correctness: there is no
+"the key expired, so we ran it again" path. A key we still hold replays; past
+seven days the record is gone and the key is unknown to us.
+
+## Webhooks
+
+First, get a signing secret. In sandbox you can issue one yourself:
+
+```bash
+npx -y @avvio/payments webhook create --url http://localhost:4000/hooks
+# Signing secret (shown once — store it now):
+#   whsec_…
+```
+
+`http://localhost` is accepted **in sandbox only**, so your first receiver can be
+a script on your laptop rather than a tunnel you have to stand up first. Live
+endpoints are https-only and are created from the dashboard by a human — a
+credential that could repoint its own webhook URL could quietly redirect every
+payout notification, so that one stays off the API.
+
+The secret is shown **once** and is not retrievable. Store it before you close
+the terminal.
+
+```bash
+npx -y @avvio/payments webhook deliveries <endpointId>   # what we sent, what came back
+```
+
+```js
+const { verifyWebhook } = require('@avvio/payments');
+
+app.post('/hooks/avvio', express.raw({ type: '*/*' }), (req, res) => {
+  let event;
+  try {
+    event = verifyWebhook({
+      body: req.body,          // the RAW bytes, not a parsed object
+      headers: req.headers,
+      secret: process.env.AVVIO_WEBHOOK_SECRET,
+    });
+  } catch {
+    return res.sendStatus(400);
+  }
+  res.sendStatus(200);         // ack fast, process after
+  handle(event);
+});
+```
+
+Verify over the **raw** body. Re-serializing a parsed object does not reproduce
+the same bytes, and one reordered key fails every signature.
+
+Worth doing once before you go live: verify a real event with the **wrong**
+secret and confirm your handler rejects it. A verification step that silently
+passes is indistinguishable from no verification at all until someone posts you
+a forged payout.
+
+Two things to build for:
+
+- **Webhooks are the fast path, not the guarantee.** `getPayout()` is
+  authoritative. Treat a webhook as the nudge to look.
+- **`completed` is not always final.** A bank can return a settled payment days
+  later, giving `failed` with `returned_by_bank` and `fundsReturned: true`. Do
+  not write a ledger that treats `completed` as immutable.
+
+## Reconciling
+
+The event feed is the durable half of the pair above: every transition, in
+order, each with a `sequence` you carry forward. A webhook you missed is gone;
+an event is still there.
+
+```bash
+avvio-payments events --since 4102          # a page, plus the nextSince to keep
+avvio-payments events --payout-id pay_01J…  # everything that happened to one
+avvio-payments events --follow              # tail it, one JSON row per line
+```
+
+`--follow` polls and prints new rows as they land, which is what a terminal is
+for. **It holds the watermark in memory only** — it is a tail, not a
+reconciler. When it stops, the gap is read again only if you persisted a
+`nextSince` and pass it back as `--since`. In Node, `eachEvent()` pages for you:
+
+```js
+for await (const event of avvio.eachEvent({ since: savedWatermark })) {
+  await apply(event);               // dedupe on event.id — the feed is at-least-once
+  savedWatermark = event.sequence;
+}
+```
+
+To watch one payout instead of the whole feed:
+
+```bash
+avvio-payments status pay_01J… --watch
+```
+
+It polls until the payout stops moving and prints the final payout to stdout,
+with progress on stderr so `--json` still pipes. It stops on `completed`
+because nothing further happens *on this payout* — a bank return arrives days
+later as a new event, which is why it tells you to keep reading the feed.
+
+## Payouts you fund yourself
+
+Some routings hand you the payout with `requiresFunding: true` instead of
+debiting a balance. The money stays in your wallet until you move it; we hold no
+key and cannot move it.
+
+```bash
+avvio-payments funding pay_01J…                       # address, amount, network, expiry
+avvio-payments funding confirm pay_01J… --tx 0xabc…   # after you have broadcast it
+```
+
+`confirm` reports a transfer that has **already left your wallet**, so it is
+strict about the hash: a truncated paste is refused here, before anything is
+reported, rather than coming back as a rejection that reads like your transfer
+failed. Pass `--idempotency-key` if you want a timed-out confirm to be safely
+repeatable. Bare `funding`, with no payout id, is still the other question —
+where to wire a top-up for your balance.
+
+## MCP
+
+For an agent that pays people.
+
+```json
+{
+  "mcpServers": {
+    "avvio-payments": {
+      "command": "npx",
+      "args": ["-y", "@avvio/payments", "mcp"],
+      "env": {
+        "AVVIO_API_KEY": "ak_test_…",
+        "AVVIO_ORG_ID": "cmsx…"
+      }
+    }
+  }
+}
+```
+
+Fifteen tools: `list_corridors`, `get_requirements`, `quote`,
+`create_beneficiary`, `list_beneficiaries`, `send_payout`, `get_payout`,
+`list_payouts`, `funding_accounts`, `list_events`, `get_balance`,
+`get_funding`, `create_payout_link`, `confirm_funding`, `cancel_payout`. Ten
+reads are marked read-only so a host can auto-approve them.
+
+> **Three tools move money or end a payment**, and each requires an explicit
+> `confirm: true`: `send_payout`, `confirm_funding` and `cancel_payout`.
+> `send_payout` additionally requires an `idempotencyKey`, so a half-parsed
+> instruction cannot become a payment and a reflexive retry cannot become two.
+> Start with a test key.
+
+## CLI reference
+
+| Command | |
+|---|---|
+| `guide` | The whole flow, as commands you can paste |
+| `doctor` | Check credentials, connectivity, balance |
+| `fund [--amount]` | Credit your sandbox balance |
+| `balance` | What you can currently send |
+| `corridors` | Currencies you can pay out to |
+| `requirements <CCY>` | Fields that corridor needs |
+| `quote --amount --to` | Price with no beneficiary |
+| `beneficiary create` | Register who is paid. `--external-id` makes a repeat create safe |
+| `beneficiary list [--end-user]` | Saved beneficiaries |
+| `pay --amount --to [--expect]` | Send. `--expect` refuses the send if the rate moved |
+| `status <payoutId> [--watch]` | One payout, live. `--watch` polls until it stops moving |
+| `payouts` | Recent payouts |
+| `events [--since] [--follow]` | The change feed. `--follow` tails it as JSON lines |
+| `funding` | Where to wire a top-up |
+| `funding <payoutId>` | Deposit instructions for a payout you fund yourself |
+| `funding confirm <payoutId> --tx` | Report the transfer you already sent |
+| `mcp` | Run as an MCP server |
+
+Every command takes `--json`.
+
+## What can change under you
+
+`CHANGELOG.md` says exactly which parts of this API we may change without
+warning and which we will not. The short version: **branch on `type` and on
+`status`, ignore fields you do not recognise, and never treat `completed` as
+final** — a bank can return a settled payment days later.
+
+## Errors
+
+`PayoutsError` carries `type` (stable — branch on this, not the message),
+`status`, `requestId`, `idempotencyKey`, and `retryable`.
+
+In TypeScript, `type` is the `PayoutsErrorType` union of every documented code,
+so a `switch` over it is checked rather than a set of string literals nobody
+verifies. It keeps `(string & {})` in the union deliberately: new types ship
+without a major version, and an unrecognised one must still compile rather than
+break your build against a live API. Write the `default` branch.
+
+Quote the `requestId`
+when you contact us; it is in the body of every ERROR, and on every response as the `x-request-id` header.
+
+## License
+
+MIT. See [LICENSE](./LICENSE).