@avvio/payments 0.1.0

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@avvio/payments",
+  "version": "0.1.0",
+  "description": "Pay out to your own customers from your Avvio balance. CLI, MCP server, and Node client — zero dependencies.",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/anzolabs/anzolabs-B2B-backend.git",
+    "directory": "packages/avvio-payments"
+  },
+  "homepage": "https://avvio-docs.pages.dev",
+  "bugs": {
+    "url": "https://github.com/anzolabs/anzolabs-B2B-backend/issues",
+    "email": "support@avvio.xyz"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./src/client.js"
+    },
+    "./webhooks": {
+      "types": "./index.d.ts",
+      "default": "./src/webhooks.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "src/client.js",
+  "bin": {
+    "avvio-payments": "src/cli.js"
+  },
+  "files": [
+    "src",
+    "index.d.ts",
+    "LICENSE",
+    "README.md",
+    "QUICKSTART.md",
+    "ERRORS.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  },
+  "keywords": [
+    "payouts",
+    "cross-border",
+    "mcp"
+  ],
+  "types": "index.d.ts"
+}

package/src/cli.js

@@ -0,0 +1,635 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * The CLI. Same operations as the MCP server, same client underneath.
+ *
+ * Design rule throughout: every failure says what to do next. An integrator
+ * hitting an error at 2am should not have to read our source to find out
+ * whether to retry, change something, or call us.
+ */
+
+const { PayoutsClient, PayoutsError } = require('./client');
+
+const USAGE = `
+avvio-payments — pay out to your customers from your balance
+
+  Setup
+    guide                       The whole flow, as commands you can paste
+    doctor                      Check your credentials, connectivity and balance
+    mcp                         Run as an MCP server over stdio (for agents)
+
+  Discovery
+    corridors                   Currencies you can pay out to
+    requirements <CCY>          Fields a beneficiary in that currency needs
+
+  Pricing
+    quote --amount 200 --to MXN         What the recipient gets, and the fee
+
+  Beneficiaries
+    beneficiary create --name "Maria Gonzalez" --email maria@example.com \\
+      --currency MXN --end-user emp_42 \\
+      --external-id emp42_maria \\
+      --field clabeNumber=012345678901234567
+      [--country MX] [--external-id <your id>]   external-id makes a repeat
+                                                 create return the existing
+                                                 beneficiary instead of
+                                                 registering a second account
+    beneficiary list [--end-user emp_42] [--limit 50] [--cursor <id>]
+
+  Sandbox
+    fund [--amount 5000]        Credit your test balance
+    balance [--history]         What you can send; --history explains every change
+
+  Paying
+    pay --amount 200 --to <destinationAccountId> --end-user emp_42 \\
+        [--expect <destinationAmount from quote>] [--end-user-name "Ana Lopez"] \\
+        [--reference ZZ-1] [--idempotency-key k1] [--max-drift-bps 200]
+    cancel <payoutId>      stop a payout that has not been funded yet
+  status <payoutId> [--watch]   --watch polls until it stops moving
+    payouts                     Recent payouts
+
+  Reconciliation
+    events [--since <sequence>] [--limit N] [--payout-id ID] [--follow]
+                                Every transition, in order. Carry the returned
+                                nextSince back as --since; --follow polls and
+                                prints new rows as they land (--interval SECONDS)
+
+  Funding
+    funding                     Where to wire money to top up your balance
+    funding <payoutId>          Deposit instructions for a payout you fund
+                                yourself (requiresFunding: true)
+    funding confirm <payoutId> --tx <hash>
+                                Report the transfer you already sent
+
+  Payout links
+    link create --amount --to --end-user
+                                Mint a one-time link; the recipient enters their
+                                own bank details (--reference, --expires MINUTES)
+
+  Webhooks (sandbox)
+    webhook create --url <url>  Register an endpoint, print its signing secret
+                                (--events a,b to filter; localhost ok in sandbox)
+    webhook deliveries <id>     What we sent, what came back, what we retried
+
+  Configuration (environment)
+    AVVIO_API_KEY   required    Server-side only. Never ship it to a browser or a phone.
+    AVVIO_ORG_ID    required
+    AVVIO_BASE_URL  optional
+
+  Every command takes --json for machine-readable output.
+`;
+
+function parseArgs(argv) {
+  const positional = [];
+  const flags = {};
+  const fields = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--field') {
+      const [k, ...rest] = String(argv[++i] || '').split('=');
+      if (k) fields[k] = rest.join('=');
+    } else if (a.startsWith('--')) {
+      const key = a.slice(2);
+      const next = argv[i + 1];
+      if (next === undefined || next.startsWith('--')) flags[key] = true;
+      else flags[key] = argv[++i];
+    } else {
+      positional.push(a);
+    }
+  }
+  return { positional, flags, fields };
+}
+
+/**
+ * Every byte this CLI prints goes through here.
+ *
+ * Not an abstraction for its own sake: it is the only way a test can read what
+ * a command printed without replacing `process.stdout.write`, which the test
+ * runner is also using — patching it globally silently swallowed the runner's
+ * own results and made a third of the suite invisible.
+ */
+const io = {
+  out: (s) => process.stdout.write(s),
+  err: (s) => process.stderr.write(s),
+};
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+/** A --interval flag in seconds. `0` is honoured; a missing flag is not. */
+const seconds = (flag, fallback) => {
+  const n = Number(flag);
+  return (Number.isFinite(n) && n >= 0 ? n : fallback) * 1000;
+};
+
+/**
+ * Where a payout stops moving on its own. `completed` is in here because
+ * nothing further happens without a bank return — which is a NEW event days
+ * later, not a state this poll will ever see. Waiting for it here would hang
+ * forever; reading the event feed is how you catch it.
+ */
+const TERMINAL = new Set(['completed', 'failed', 'canceled']);
+
+const out = (v, json) =>
+  io.out(
+    (json ? JSON.stringify(v) : JSON.stringify(v, null, 2)) + '\n',
+  );
+
+/**
+ * Preflight. This is the first command an integrator should run, and it exists
+ * because "it doesn't work" is otherwise four different problems that look the
+ * same: wrong key, wrong org, wrong URL, or an account not yet able to pay.
+ */
+async function doctor(json) {
+  const checks = [];
+  const add = (name, ok, detail) => checks.push({ name, ok, detail });
+
+  const key = process.env.AVVIO_API_KEY;
+  const org = process.env.AVVIO_ORG_ID;
+  const base = process.env.AVVIO_BASE_URL || '(default)';
+
+  add('AVVIO_API_KEY set', !!key, key ? `${key.slice(0, 16)}…` : 'missing');
+  add('AVVIO_ORG_ID set', !!org, org || 'missing');
+  add('AVVIO_BASE_URL', true, base);
+  if (!key || !org) {
+    report(checks, json);
+    process.exitCode = 1;
+    return;
+  }
+
+  const client = new PayoutsClient();
+  // Read off the client rather than re-deriving it here. This was the same
+  // prefix test written twice, and the version a partner can assert on in their
+  // own suite is the one that has to be right.
+  add(
+    'mode',
+    true,
+    client.mode === 'test'
+      ? 'TEST — no real money can move'
+      : 'LIVE — payouts move real money',
+  );
+  try {
+    const { corridors } = await client.corridors();
+    add(
+      'credentials accepted',
+      true,
+      `${(corridors || []).length} payout corridors available`,
+    );
+  } catch (err) {
+    const e = err instanceof PayoutsError ? err : null;
+    add(
+      'credentials accepted',
+      false,
+      e
+        ? e.status === 401
+          ? 'Key rejected. Check it was copied whole, and has not been revoked.'
+          : e.status === 403
+            ? 'Key is valid but not for this organization. Check AVVIO_ORG_ID.'
+            : `${e.type}: ${e.message}`
+        : String(err && err.message),
+    );
+    report(checks, json);
+    process.exitCode = 1;
+    return;
+  }
+
+  // In test mode the useful question is "can I send right now", not "where do
+  // I wire money" — a sandbox balance is one command away, and reporting wire
+  // instructions there sends someone off to do something pointless.
+  if (client.mode === 'test') {
+    try {
+      const bal = await client.balance();
+      const amount = Number(bal && bal.amount);
+      add(
+        'sandbox balance',
+        amount > 0,
+        amount > 0
+          ? `${bal.amount} ${bal.currency}`
+          : 'empty — run: avvio-payments fund',
+      );
+    } catch (err) {
+      add('sandbox balance', false, String(err && err.message));
+    }
+  } else {
+    try {
+      const funding = await client.fundingAccounts();
+      const n = Array.isArray(funding)
+        ? funding.length
+        : (funding && funding.accounts && funding.accounts.length) || 0;
+      add(
+        'funding instructions available',
+        n > 0,
+        n > 0 ? `${n} account(s)` : 'none yet — your account may still be in review',
+      );
+    } catch (err) {
+      add('funding instructions available', false, String(err && err.message));
+    }
+  }
+
+  report(checks, json);
+  if (checks.some((c) => !c.ok)) process.exitCode = 1;
+  else if (!json) {
+    // The point of a preflight is to say what to do next, not to award a pass.
+    io.out("Next:  avvio-payments guide\n");
+  }
+}
+
+function report(checks, json) {
+  if (json) return out({ checks }, true);
+  for (const c of checks) {
+    io.out(
+      `  ${c.ok ? 'ok  ' : 'FAIL'}  ${c.name.padEnd(32)} ${c.detail}\n`,
+    );
+  }
+  const bad = checks.filter((c) => !c.ok);
+  io.out(
+    bad.length
+      ? `\n${bad.length} check(s) failed. Fix the first one — the rest usually follow.\n`
+      : '\nReady to pay out.\n',
+  );
+}
+
+/**
+ * The flow, as commands rather than prose.
+ *
+ * Exists because the docs live somewhere else and an integrator's first
+ * question is "what do I type next". Reading a page and translating it into
+ * five commands is work we can do once instead of every partner doing it.
+ */
+function guide() {
+  io.out(`
+Send your first payout — five commands, about two minutes.
+
+  1. Check your setup
+     avvio-payments doctor
+
+  2. Give your sandbox a balance
+     avvio-payments fund --amount 5000
+
+  3. See what Mexico needs
+     avvio-payments requirements MXN
+
+  4. Create who you're paying
+     avvio-payments beneficiary create --name "Maria Gonzalez" \\
+       --email maria@example.com --currency MXN --end-user employee_42 \\
+       --field clabeNumber=012345678901234567
+
+  5. Price it, then send it
+     avvio-payments quote --amount 200 --to MXN
+     avvio-payments pay --amount 200 --to <destinationAccountId> \\
+       --end-user employee_42 --expect <the destinationAmount from the quote>
+
+  6. Watch it settle
+     avvio-payments status <payoutId>
+
+Before you go live, run the case most integrations get wrong: create a
+beneficiary whose account number ends 0003, pay it, and keep polling past
+"completed". It reverses to failed with returned_by_bank — a settled payout is
+not always final, and this is how you see it happen rather than take our word.
+
+Full walkthrough: QUICKSTART.md in this package.
+Every error code and what to do: ERRORS.md.
+`);
+}
+
+async function run(argv) {
+  const { positional, flags, fields } = parseArgs(argv);
+  const cmd = positional[0];
+  const json = !!flags.json;
+
+  if (!cmd || cmd === 'help' || flags.help) {
+    io.out(USAGE);
+    return;
+  }
+  if (cmd === 'mcp') return require('./mcp').main();
+  if (cmd === 'doctor') return doctor(json);
+  if (cmd === 'guide') return guide();
+
+  const client = new PayoutsClient();
+
+  switch (cmd) {
+    case 'corridors':
+      return out(await client.corridors(), json);
+
+    case 'requirements': {
+      const ccy = positional[1] || flags.currency;
+      if (!ccy) throw new Error('Usage: requirements <CURRENCY>');
+      return out(await client.requirements(ccy), json);
+    }
+
+    case 'quote': {
+      if (!flags.amount || !flags.to) {
+        throw new Error('Usage: quote --amount 200 --to MXN');
+      }
+      return out(
+        await client.quote({
+          amount: flags.amount,
+          to: flags.to,
+          from: flags.from,
+        }),
+        json,
+      );
+    }
+
+    case 'beneficiary': {
+      const sub = positional[1];
+      if (sub === 'list') {
+        return out(
+          await client.listBeneficiaries({
+            endUserId: flags['end-user'],
+            limit: flags.limit ? Number(flags.limit) : undefined,
+            cursor: flags.cursor,
+          }),
+          json,
+        );
+      }
+      if (sub === 'create') {
+        if (!flags.name || !flags.currency || !flags.email) {
+          throw new Error(
+            'Usage: beneficiary create --name "..." --email "..." --currency MXN --field <name>=<value>',
+          );
+        }
+        if (!Object.keys(fields).length) {
+          throw new Error(
+            `No --field given. Run "requirements ${flags.currency}" to see what this corridor needs.`,
+          );
+        }
+        return out(
+          await client.createBeneficiary({
+            name: flags.name,
+            email: flags.email,
+            country: flags.country,
+            currency: flags.currency,
+            endUserId: flags['end-user'],
+            externalId: flags['external-id'],
+            details: fields,
+          }),
+          json,
+        );
+      }
+      throw new Error('Usage: beneficiary <create|list>');
+    }
+
+    case 'pay': {
+      if (!flags.amount || !flags.to) {
+        throw new Error(
+          'Usage: pay --amount 200 --to <destinationAccountId> [--expect 3410.00]',
+        );
+      }
+      return out(
+        await client.payout({
+          amount: flags.amount,
+          destinationAccountId: flags.to,
+          reference: flags.reference,
+          purposeOfPayment: flags.purpose,
+          expectDestination: flags.expect,
+          ...(flags['max-drift-bps']
+            ? { maxRateDrift: Number(flags['max-drift-bps']) / 10_000 }
+            : {}),
+          idempotencyKey: flags['idempotency-key'],
+          endUser: flags['end-user']
+            ? {
+                id: flags['end-user'],
+                ...(flags['end-user-name']
+                  ? { name: flags['end-user-name'] }
+                  : {}),
+              }
+            : undefined,
+        }),
+        json,
+      );
+    }
+
+    case 'status': {
+      const id = positional[1];
+      if (!id) throw new Error('Usage: status <payoutId> [--watch]');
+      if (!flags.watch) return out(await client.getPayout(id), json);
+
+      // Polling by hand is what people already do, so do it here and get the
+      // caveat printed with it. Progress goes to stderr so stdout stays a single
+      // parseable payout — a --watch that interleaves progress into --json
+      // output would break the pipe it exists to serve.
+      const interval = seconds(flags.interval, 3);
+      let last;
+      for (;;) {
+        const payout = await client.getPayout(id);
+        if (payout.status !== last) {
+          last = payout.status;
+          io.err(
+            `${new Date().toISOString()}  ${payout.status}${payout.failureCode ? ` (${payout.failureCode})` : ''}\n`,
+          );
+        }
+        if (TERMINAL.has(payout.status)) {
+          if (payout.status === 'completed') {
+            // The whole package says this and it matters most right here: the
+            // person watching just saw "completed" and is about to close the
+            // terminal and mark a wage settled.
+            io.err(
+              'completed is not final — a bank can return a settled payout days later.\n' +
+                'Keep reading: avvio-payments events --payout-id ' + id + '\n',
+            );
+          }
+          return out(payout, json);
+        }
+        await sleep(interval);
+      }
+    }
+
+    case 'events': {
+      // The reconciliation primitive. `since` is INCLUSIVE, so the row at your
+      // watermark comes back again on every resume — dedupe on `id` rather than
+      // assuming a page starts after it.
+      const args = {
+        since: flags.since,
+        limit: flags.limit ? Number(flags.limit) : undefined,
+        payoutId: flags['payout-id'],
+      };
+      if (!flags.follow) return out(await client.listEvents(args), json);
+
+      // --follow holds the watermark in MEMORY. It is a tail, not a reconciler:
+      // when it stops, everything that happened while it was down is only ever
+      // read again if you persisted a `nextSince` and pass it back as --since.
+      // One row per line, so it pipes into something that does persist.
+      const interval = seconds(flags.interval, 5);
+      let since = args.since;
+      let previous = new Set();
+      for (;;) {
+        const page = await client.listEvents({ ...args, since });
+        const current = new Set();
+        for (const event of page.data || []) {
+          current.add(event.id);
+          // The inclusive boundary re-delivers the row at the watermark on the
+          // next poll. Suppressing just the previous page's ids keeps the tail
+          // readable without pretending the feed is exactly-once — anything
+          // consuming this still has to dedupe on `id`.
+          if (!previous.has(event.id)) {
+            io.out(JSON.stringify(event) + '\n');
+          }
+        }
+        previous = current;
+        if (page.nextSince) since = page.nextSince;
+        // A backlog is drained at once; only a caught-up tail waits. Sleeping
+        // after a page the server said has more behind it means a tail that
+        // never catches up.
+        if (!page.hasMore) await sleep(interval);
+      }
+    }
+
+    case 'payouts':
+      return out(await client.listPayouts(), json);
+
+    case 'cancel': {
+      // The recovery an operator actually reaches for: a payout created for the
+      // wrong amount, before any money has been sent.
+      const id = positional[1];
+      if (!id) throw new Error('Usage: cancel <payoutId>');
+      return out(await client.cancelPayout(id), json);
+    }
+
+    case 'fund': {
+      // Sandbox only. Kept in the CLI so the whole first-payout flow is one
+      // tool — an integrator dropping to curl for one step is where a
+      // quickstart stops being a quickstart.
+      const res = await client.fund(flags.amount ?? '5000.00');
+      return out(res, json);
+    }
+
+    case 'balance':
+      // `--history` answers "why did my balance change", which a single number
+      // never can.
+      return out(
+        flags.history
+          ? await client.balanceHistory(flags.limit ? Number(flags.limit) : undefined)
+          : await client.balance(),
+        json,
+      );
+
+    case 'funding': {
+      const sub = positional[1];
+      if (sub === 'confirm') {
+        const id = positional[2];
+        const tx = flags.tx;
+        if (!id || !tx || tx === true) {
+          throw new Error(
+            'Usage: funding confirm <payoutId> --tx <transactionHash>',
+          );
+        }
+        // Checked here rather than left to the server, because by the time
+        // anyone runs this the money has already left their wallet. A truncated
+        // paste should come back naming the hash, not as a rejection of a
+        // transfer that really did happen — the difference between "fix your
+        // argument" and "did my transfer fail?".
+        if (!/^0x[0-9a-fA-F]{64}$/.test(tx)) {
+          throw new Error(
+            `--tx must be a 0x-prefixed 32-byte transaction hash. Got: ${tx}`,
+          );
+        }
+        return out(
+          await client.confirmFunding(id, {
+            transactionHash: tx,
+            // A confirm that times out has an unknown outcome like any other
+            // mutation, and the same key is what makes asking again a replay.
+            idempotencyKey: flags['idempotency-key'],
+          }),
+          json,
+        );
+      }
+      // `funding <payoutId>` is "how do I fund THIS payout"; bare `funding` is
+      // "where do I wire a top-up". Different questions, and the second one was
+      // here first — so it stays the bare verb.
+      if (sub) return out(await client.getFunding(sub), json);
+      return out(await client.fundingAccounts(), json);
+    }
+
+    case 'link': {
+      if (positional[1] !== 'create') {
+        throw new Error('link create --amount <usd> --to <CCY> --end-user <id>');
+      }
+      const res = await client.createPayoutLink({
+        amount: flags.amount,
+        destinationCurrency: flags.to,
+        endUserId: flags['end-user'],
+        reference: flags.reference,
+        expiresInMinutes: flags.expires ? Number(flags.expires) : undefined,
+      });
+      if (!json) {
+        io.out(
+          `\nSend this to the person being paid:\n  ${res.url}\n\n` +
+            `Expires ${res.expiresAt}. It can be spent once.\n`,
+        );
+      }
+      return out(res, json);
+    }
+
+    case 'webhook': {
+      const sub = positional[1];
+      if (sub === 'create') {
+        if (!flags.url) {
+          throw new Error(
+            'webhook create needs --url <https endpoint>\n' +
+              'Testing locally? http://localhost:PORT is accepted in sandbox.',
+          );
+        }
+        const res = await client.createWebhookEndpoint({
+          url: flags.url,
+          events: flags.events ? String(flags.events).split(',') : undefined,
+        });
+        if (!json && res.secret) {
+          io.out(
+            `\nSigning secret (shown once — store it now):\n  ${res.secret}\n\n` +
+              `  export AVVIO_WEBHOOK_SECRET=${res.secret}\n\n` +
+              'Verify with verifyWebhook({ body, headers, secret }) over the RAW bytes.\n',
+          );
+          return out({ id: res.id, url: res.url, events: res.events }, json);
+        }
+        return out(res, json);
+      }
+      if (sub === 'deliveries') {
+        const id = positional[2];
+        if (!id) throw new Error('webhook deliveries needs an endpoint id');
+        return out(await client.webhookDeliveries(id), json);
+      }
+      throw new Error('webhook create --url <url> | webhook deliveries <id>');
+    }
+
+    default:
+      throw new Error(`Unknown command: ${cmd}\n${USAGE}`);
+  }
+}
+
+function main() {
+  run(process.argv.slice(2)).catch((err) => {
+    if (err instanceof PayoutsError) {
+      io.err(`\n${err.type}: ${err.message}\n`);
+      // The API says exactly which fields failed. Printing only the summary —
+      // "1 field(s) failed validation" — turns a two-second fix into a guess.
+      const fields = err.body && err.body.errors;
+      if (Array.isArray(fields)) {
+        for (const f of fields) io.err(`  - ${f}\n`);
+      }
+      if (err.body && err.body.resolution) {
+        io.err(`${err.body.resolution}\n`);
+      }
+      if (err.requestId) {
+        io.err(`request id: ${err.requestId}\n`);
+      }
+      if (err.idempotencyKey) {
+        // Naming the actual value matters: telling someone to "reuse the same
+        // key" when they never passed one is advice that double-pays.
+        io.err(
+          `retry with: --idempotency-key ${err.idempotencyKey}\n`,
+        );
+      }
+      if (err.retryable) {
+        io.err('This is safe to retry unchanged.\n');
+      }
+    } else {
+      io.err(`\n${(err && err.message) || err}\n`);
+    }
+    process.exitCode = 1;
+  });
+}
+
+module.exports = { run, parseArgs, io };
+
+if (require.main === module) main();