@avvio/payments 0.1.0

package/src/mcp.js

@@ -0,0 +1,434 @@
+'use strict';
+
+/**
+ * MCP server over stdio, so an agent can drive payouts directly.
+ *
+ * Newline-delimited JSON-RPC 2.0 on stdin/stdout. That is the whole protocol
+ * for this transport, which is why there is no SDK here — a dependency to
+ * format JSON would not earn its place in a package that holds a credential
+ * capable of moving money.
+ *
+ * STDOUT IS THE PROTOCOL. Nothing may be written to it except responses, so
+ * every diagnostic goes to stderr.
+ */
+
+const { PayoutsClient, PayoutsError } = require('./client');
+
+// Read, not hardcoded: an agent uses this in the handshake to decide what the
+// server can do, and a literal is wrong the moment the package is released.
+const SERVER = {
+  name: 'avvio-payments',
+  version: require('../package.json').version,
+};
+
+/**
+ * Money-moving tools are marked and gated.
+ *
+ * `send_payout` additionally requires `confirm: true`. An agent that has been
+ * told "pay Maria" should have to state the intent to move money as a separate
+ * argument, so a half-parsed instruction cannot become a payment. It costs one
+ * field and removes a category of accident.
+ */
+const TOOLS = [
+  {
+    name: 'list_corridors',
+    annotations: { readOnlyHint: true },
+    description:
+      'List every currency this organization can pay out to, with the beneficiary fields each one requires. Read this instead of hardcoding a form — field names differ by corridor and can change.',
+    inputSchema: { type: 'object', properties: {} },
+  },
+  {
+    name: 'get_requirements',
+    annotations: { readOnlyHint: true },
+    description:
+      'The exact beneficiary fields needed to pay out in one currency, with validation patterns. Call this before create_beneficiary.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        currency: { type: 'string', description: 'ISO code, e.g. MXN' },
+      },
+      required: ['currency'],
+    },
+  },
+  {
+    name: 'quote',
+    annotations: { readOnlyHint: true },
+    description:
+      'Indicative price for a corridor with no beneficiary needed: what the recipient gets, the fee, the rate, and the corridor minimum and maximum. Use this while a user is still choosing an amount. It is an estimate, not a locked rate.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        amount: { type: 'string', description: 'Amount to send, e.g. "200.00"' },
+        to: { type: 'string', description: 'Destination currency, e.g. MXN' },
+        from: { type: 'string', description: 'Source currency. Defaults to USD.' },
+      },
+      required: ['amount', 'to'],
+    },
+  },
+  {
+    name: 'create_beneficiary',
+    description:
+      'Register who is being paid. Scope it to the end user paying them via endUserId, so each of your users only ever sees their own beneficiaries. Returns destinationAccountId, which send_payout needs.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: { type: 'string' },
+        email: { type: 'string' },
+        country: { type: 'string', description: 'ISO-3166 alpha-2, e.g. MX' },
+        currency: { type: 'string' },
+        endUserId: {
+          type: 'string',
+          description: 'Your id for the person SENDING the money.',
+        },
+        externalId: {
+          type: 'string',
+          description: 'Your own id for this beneficiary. Makes creation idempotent.',
+        },
+        details: {
+          type: 'object',
+          description: 'Corridor fields from get_requirements, e.g. {"clabeNumber":"012..."}',
+        },
+      },
+      required: ['name', 'currency', 'details'],
+    },
+  },
+  {
+    name: 'list_beneficiaries',
+    annotations: { readOnlyHint: true },
+    description:
+      'Beneficiaries saved for one end user. Always pass endUserId for anything shown to a user; omitting it returns the whole organization.',
+    inputSchema: {
+      type: 'object',
+      properties: { endUserId: { type: 'string' } },
+    },
+  },
+  {
+    name: 'send_payout',
+    annotations: { destructiveHint: true, readOnlyHint: false },
+    description:
+      'MOVES MONEY. Prices the payout and executes it, debiting your balance. Requires confirm:true. If it times out, the outcome is unknown — call again with the same idempotencyKey rather than starting over.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        amount: { type: 'string' },
+        destinationAccountId: {
+          type: 'string',
+          description: 'From create_beneficiary or list_beneficiaries.',
+        },
+        endUserId: { type: 'string' },
+        endUserName: { type: 'string' },
+        reference: { type: 'string', description: 'Your payment reference.' },
+        purposeOfPayment: { type: 'string' },
+        expectDestinationAmount: {
+          type: 'string',
+          description:
+            'What you told the payer they would receive. The send is refused if the binding quote drifts more than 2% from it.',
+        },
+        idempotencyKey: {
+          type: 'string',
+          description:
+            'REQUIRED. A unique id you generate for this payout. If the call times out, call again with this SAME value — that replays the original payout instead of sending a second one.',
+        },
+        confirm: {
+          type: 'boolean',
+          description: 'Must be true. Explicit acknowledgement that this moves money.',
+        },
+      },
+      // idempotencyKey is required because a timeout is the case this tool is
+      // most likely to hit, and retrying is what an agent does by reflex.
+      // Without a caller-supplied key that retry is a second payment.
+      required: [
+        'amount',
+        'destinationAccountId',
+        'confirm',
+        'idempotencyKey',
+      ],
+    },
+  },
+  {
+    name: 'get_payout',
+    annotations: { readOnlyHint: true },
+    description:
+      'Current state of one payout. Always live — this is authoritative, more so than a webhook you may have missed.',
+    inputSchema: {
+      type: 'object',
+      properties: { payoutId: { type: 'string' } },
+      required: ['payoutId'],
+    },
+  },
+  {
+    name: 'list_payouts',
+    annotations: { readOnlyHint: true },
+    description: 'Recent payouts for this organization.',
+    inputSchema: { type: 'object', properties: {} },
+  },
+  {
+    name: 'funding_accounts',
+    annotations: { readOnlyHint: true },
+    description:
+      'Where to wire money to top up the balance that payouts debit.',
+    inputSchema: { type: 'object', properties: {} },
+  },
+  {
+    name: 'list_events',
+    annotations: { readOnlyHint: true },
+    description:
+      'The change feed: one row per payout transition, with a `sequence` cursor. This is the reconciliation primitive — carry `nextSince` back as `since` and you observe every revision. A payout that completed and was then returned by the bank appears here as a second row.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        since: { type: 'string', description: 'A `sequence` from a previous page. Digits only.' },
+        limit: { type: 'number', description: '1-500, default 100.' },
+        payoutId: { type: 'string', description: 'Only this payout\u2019s transitions.' },
+      },
+    },
+  },
+  {
+    name: 'get_balance',
+    annotations: { readOnlyHint: true },
+    description:
+      'The organization\u2019s available balance. Check this before sending: an underfunded payout is refused, and the refusal is a 400 rather than a queued payment.',
+    inputSchema: { type: 'object', properties: {} },
+  },
+  {
+    name: 'get_funding',
+    annotations: { readOnlyHint: true },
+    description:
+      'Deposit instructions for a payout that requires funding: the address, the exact amount, the network, and an expiry. Only some routings need this; the payout says so with `requiresFunding`.',
+    inputSchema: {
+      type: 'object',
+      properties: { payoutId: { type: 'string' } },
+      required: ['payoutId'],
+    },
+  },
+  {
+    name: 'create_payout_link',
+    annotations: { readOnlyHint: false },
+    description:
+      'Mint a one-time link that collects the recipient\u2019s own bank details and pays them, so you never handle the details yourself. The link is a credential: it is the only thing needed to be paid, so send it to the person being paid and nobody else.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        amount: { type: 'string', description: 'Decimal string, e.g. "200.00".' },
+        destinationCurrency: { type: 'string', description: 'ISO code, e.g. MXN' },
+        endUserId: { type: 'string', description: 'Your id for the person being paid.' },
+        reference: { type: 'string' },
+        expiresInMinutes: { type: 'number', description: '1-10080, default 60.' },
+      },
+      required: ['amount', 'destinationCurrency', 'endUserId'],
+    },
+  },
+  {
+    name: 'confirm_funding',
+    annotations: { readOnlyHint: false },
+    description:
+      'Report the transaction that funded a payout. We read the chain before recording it: a hash that does not fund this payout is refused and nothing is written, so a rejection is always safe to correct. One transfer funds exactly one payout.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        payoutId: { type: 'string' },
+        transactionHash: { type: 'string', description: '0x-prefixed 32-byte hex.' },
+        confirm: {
+          type: 'boolean',
+          description: 'Must be true. This commits funds you have already sent.',
+        },
+      },
+      required: ['payoutId', 'transactionHash', 'confirm'],
+    },
+  },
+  {
+    name: 'cancel_payout',
+    annotations: { readOnlyHint: false },
+    description:
+      'Stop a payout that has NOT been funded yet \u2014 the recovery for one created by mistake. Once funded it cannot be cancelled and you get PAYOUT_NOT_CANCELABLE, which is the honest answer rather than a cancellation that does not happen.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        payoutId: { type: 'string' },
+        confirm: {
+          type: 'boolean',
+          description: 'Must be true. Cancelling is irreversible.',
+        },
+      },
+      required: ['payoutId', 'confirm'],
+    },
+  },
+];
+
+async function dispatch(client, name, args) {
+  switch (name) {
+    case 'list_corridors':
+      return client.corridors();
+    case 'get_requirements':
+      return client.requirements(args.currency);
+    case 'quote':
+      return client.quote({ amount: args.amount, to: args.to, from: args.from });
+    case 'create_beneficiary':
+      return client.createBeneficiary(args);
+    case 'list_beneficiaries':
+      return client.listBeneficiaries({ endUserId: args.endUserId });
+    case 'send_payout':
+      if (args.confirm !== true) {
+        throw new Error(
+          'send_payout moves money and requires confirm:true. Confirm the amount, currency and recipient with whoever is paying before calling again.',
+        );
+      }
+      return client.payout({
+        amount: args.amount,
+        destinationAccountId: args.destinationAccountId,
+        purposeOfPayment: args.purposeOfPayment,
+        reference: args.reference,
+        expectDestinationAmount: args.expectDestinationAmount,
+        idempotencyKey: args.idempotencyKey,
+        endUser: args.endUserId
+          ? { id: args.endUserId, name: args.endUserName }
+          : undefined,
+      });
+    case 'get_payout':
+      return client.getPayout(args.payoutId);
+    case 'list_payouts':
+      return client.listPayouts();
+    case 'funding_accounts':
+      return client.fundingAccounts();
+    case 'list_events':
+      return client.listEvents({
+        since: args.since,
+        limit: args.limit,
+        payoutId: args.payoutId,
+      });
+    case 'get_balance':
+      return client.balance();
+    case 'get_funding':
+      return client.getFunding(args.payoutId);
+    case 'create_payout_link':
+      return client.createPayoutLink({
+        amount: args.amount,
+        destinationCurrency: args.destinationCurrency,
+        endUserId: args.endUserId,
+        reference: args.reference,
+        expiresInMinutes: args.expiresInMinutes,
+      });
+    // The two below commit money, so they carry the same confirm gate
+    // `send_payout` does. An agent should not be able to fund or stop a payment
+    // on its own reading of a conversation.
+    case 'confirm_funding':
+      if (args.confirm !== true) {
+        throw new Error(
+          'confirm_funding commits funds you have already sent and requires confirm:true. Check the transaction hash against what you actually broadcast before calling again.',
+        );
+      }
+      return client.confirmFunding(args.payoutId, {
+        transactionHash: args.transactionHash,
+      });
+    case 'cancel_payout':
+      if (args.confirm !== true) {
+        throw new Error(
+          'cancel_payout is irreversible and requires confirm:true. Confirm with whoever is paying that this payout should not go out.',
+        );
+      }
+      return client.cancelPayout(args.payoutId);
+    default:
+      throw new Error(`Unknown tool: ${name}`);
+  }
+}
+
+/** JSON-RPC plumbing. Split out so the routing above stays readable. */
+function createServer({ makeClient = () => new PayoutsClient(), write } = {}) {
+  let client;
+  const clientOnce = () => (client = client || makeClient());
+
+  return async function handle(msg) {
+    const { id, method, params } = msg || {};
+    const reply = (result) => ({ jsonrpc: '2.0', id, result });
+    const fail = (code, message, data) => ({
+      jsonrpc: '2.0',
+      id,
+      error: { code, message, ...(data ? { data } : {}) },
+    });
+
+    try {
+      switch (method) {
+        case 'initialize':
+          return reply({
+            // Echo the client's version when they name one: this server's
+            // surface is stable across the versions that matter, and refusing
+            // over a version string helps nobody.
+            protocolVersion:
+              (params && params.protocolVersion) || '2025-06-18',
+            capabilities: { tools: {} },
+            serverInfo: SERVER,
+          });
+
+        case 'notifications/initialized':
+          return null; // notification — no response
+
+        case 'tools/list':
+          return reply({ tools: TOOLS });
+
+        case 'tools/call': {
+          const name = params && params.name;
+          const args = (params && params.arguments) || {};
+          try {
+            const out = await dispatch(clientOnce(), name, args);
+            return reply({
+              content: [
+                { type: 'text', text: JSON.stringify(out, null, 2) },
+              ],
+            });
+          } catch (err) {
+            // Tool errors belong in the result with isError, not as protocol
+            // errors — the agent needs to read them and adjust.
+            const text =
+              err instanceof PayoutsError
+                ? `${err.type}: ${err.message}` +
+                  (err.retryable ? '\n\nThis is safe to retry unchanged.' : '')
+                : String((err && err.message) || err);
+            return reply({ content: [{ type: 'text', text }], isError: true });
+          }
+        }
+
+        default:
+          if (id === undefined) return null; // unknown notification
+          return fail(-32601, `Method not found: ${method}`);
+      }
+    } catch (err) {
+      return fail(-32603, String((err && err.message) || err));
+    }
+  };
+}
+
+function main() {
+  const handle = createServer();
+  let buffer = '';
+
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', (chunk) => {
+    buffer += chunk;
+    let nl;
+    while ((nl = buffer.indexOf('\n')) !== -1) {
+      const line = buffer.slice(0, nl).trim();
+      buffer = buffer.slice(nl + 1);
+      if (!line) continue;
+      let msg;
+      try {
+        msg = JSON.parse(line);
+      } catch {
+        process.stderr.write(`avvio-payments: unparseable line ignored\n`);
+        continue;
+      }
+      Promise.resolve(handle(msg))
+        .then((res) => {
+          if (res) process.stdout.write(JSON.stringify(res) + '\n');
+        })
+        .catch((err) => {
+          process.stderr.write(`avvio-payments: ${err && err.message}\n`);
+        });
+    }
+  });
+
+  process.stdin.on('end', () => process.exit(0));
+}
+
+module.exports = { createServer, TOOLS, dispatch, main, SERVER };
+
+if (require.main === module) main();

package/src/webhooks.js

@@ -0,0 +1,191 @@
+'use strict';
+
+/**
+ * Webhook signature verification.
+ *
+ * The docs used to tell a partner to go install a Svix library for this. That
+ * did not remove a dependency, it moved one onto them and made it bigger — the
+ * whole argument for shipping zero dependencies is undermined by outsourcing
+ * fifteen lines of HMAC to somebody else's package.
+ *
+ * Standard Webhooks format, so an off-the-shelf verifier still works if they
+ * prefer one.
+ */
+
+const { createHmac, timingSafeEqual } = require('node:crypto');
+
+/** Default tolerance. A replayed delivery outside this window is rejected. */
+const TOLERANCE_SECONDS = 300;
+
+class WebhookVerificationError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'WebhookVerificationError';
+  }
+}
+
+/**
+ * Verify a delivery and return its parsed body.
+ *
+ * @param {object} p
+ * @param {string|Buffer} p.body    The RAW request body. Not a re-serialized
+ *   object — JSON.stringify does not guarantee byte-identical output, and a
+ *   single reordered key fails every signature.
+ * @param {object} p.headers        The request headers.
+ * @param {string} p.secret         `whsec_…` from the dashboard.
+ * @param {number} [p.toleranceSeconds]
+ */
+function verifyWebhook({ body, headers, secret, toleranceSeconds }) {
+  if (!secret || !secret.startsWith('whsec_')) {
+    throw new WebhookVerificationError(
+      'Secret must be the whsec_… value shown when the endpoint was created.',
+    );
+  }
+  const get = (name) => {
+    const v = headers?.[name] ?? headers?.[name.toUpperCase()];
+    return Array.isArray(v) ? v[0] : v;
+  };
+  const id = get('svix-id');
+  const timestamp = get('svix-timestamp');
+  const signature = get('svix-signature');
+  if (!id || !timestamp || !signature) {
+    throw new WebhookVerificationError(
+      'Missing svix-id, svix-timestamp or svix-signature.',
+    );
+  }
+
+  const age = Math.abs(Math.floor(Date.now() / 1000) - Number(timestamp));
+  const tolerance = toleranceSeconds ?? TOLERANCE_SECONDS;
+  if (!Number.isFinite(age) || age > tolerance) {
+    throw new WebhookVerificationError(
+      `Timestamp is ${age}s away from now, outside the ${tolerance}s window. This may be a replay.`,
+    );
+  }
+
+  const raw = Buffer.isBuffer(body) ? body.toString('utf8') : String(body);
+  const key = Buffer.from(secret.slice('whsec_'.length), 'base64');
+  const expected = createHmac('sha256', key)
+    .update(`${id}.${timestamp}.${raw}`)
+    .digest('base64');
+
+  // A delivery can carry several `v1,` signatures during a secret rotation.
+  // Accept if ANY matches, so a rotation drops no events.
+  const presented = String(signature)
+    .split(' ')
+    .map((part) => part.split(',')[1])
+    .filter(Boolean);
+
+  const ok = presented.some((candidate) => {
+    const a = Buffer.from(candidate);
+    const b = Buffer.from(expected);
+    return a.length === b.length && timingSafeEqual(a, b);
+  });
+  if (!ok) {
+    throw new WebhookVerificationError(
+      'Signature did not match. Verify over the RAW body, before any JSON parsing.',
+    );
+  }
+
+  try {
+    return JSON.parse(raw);
+  } catch {
+    throw new WebhookVerificationError('Body is not valid JSON.');
+  }
+}
+
+/**
+ * A request handler that verifies for you.
+ *
+ * ── Why this exists ──
+ *
+ * `verifyWebhook` is correct and partners still get it wrong, because the
+ * failure is upstream of it: `express.json()` parses and discards the raw body
+ * before your handler runs, and the signature is over the RAW BYTES. Re-encoding
+ * the parsed object almost works — until a payload has a non-ASCII character or
+ * different key order, and then signatures fail in production for a subset of
+ * events with no pattern to it.
+ *
+ * Documentation can only warn about that. This removes it: the handler reads the
+ * stream itself, so it is correct whether or not a body parser is mounted, and
+ * whichever order the middleware happens to run in.
+ *
+ * Framework-agnostic on purpose — it takes (req, res) and works under Express,
+ * Fastify's raw handler, and a bare node:http server, because a zero-dependency
+ * package cannot depend on any of them.
+ *
+ *   const handler = createWebhookHandler({
+ *     secret: process.env.AVVIO_WEBHOOK_SECRET,
+ *     onEvent: async (event) => { … },
+ *   });
+ *   app.post('/hooks/avvio', handler);
+ */
+function createWebhookHandler({ secret, onEvent, toleranceSeconds } = {}) {
+  if (!secret) throw new Error('createWebhookHandler needs { secret }.');
+  if (typeof onEvent !== 'function') {
+    throw new Error('createWebhookHandler needs { onEvent }.');
+  }
+
+  return async function avvioWebhookHandler(req, res) {
+    const send = (code, message) => {
+      res.statusCode = code;
+      res.end(message);
+    };
+
+    let raw;
+    try {
+      // `req.rawBody` is set by some setups (Next.js, a configured Express).
+      // Otherwise read the stream — which is why a parser mounted ahead of us
+      // does not break verification.
+      raw =
+        req.rawBody !== undefined
+          ? Buffer.from(req.rawBody)
+          : await readRawBody(req);
+    } catch {
+      return send(400, 'Could not read the request body.');
+    }
+
+    let event;
+    try {
+      event = verifyWebhook({
+        body: raw,
+        headers: req.headers,
+        secret,
+        toleranceSeconds,
+      });
+    } catch (err) {
+      // 400, never 401: a signature that does not verify is not an auth
+      // challenge and must never be retried into a loop. The sender should give
+      // up on this delivery and move on.
+      return send(400, err && err.message ? err.message : 'Invalid signature');
+    }
+
+    try {
+      await onEvent(event);
+    } catch (err) {
+      // 500 so the delivery is RETRIED. A handler that throws has not processed
+      // the event, and acknowledging it anyway loses it permanently — which for
+      // a bank return means a ledger that never learns the money came back.
+      return send(500, 'Handler failed; retry this delivery.');
+    }
+
+    // 2xx quickly. Anything slow belongs in a queue, not in the handler: the
+    // sender times out and retries, and a non-idempotent handler then runs
+    // twice.
+    return send(200, 'ok');
+  };
+}
+
+function readRawBody(req) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    req.on('data', (c) => chunks.push(Buffer.from(c)));
+    req.on('end', () => resolve(Buffer.concat(chunks)));
+    req.on('error', reject);
+  });
+}
+
+module.exports = {
+  verifyWebhook,
+  createWebhookHandler,
+  WebhookVerificationError,
+};