@avvio/payments 0.1.0 → 0.5.0

package/src/mcp.js

@@ -34,8 +34,16 @@ 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: {} },
+      'List every currency this organization can pay out to, or pass one currency to use its exact approved provider routing. Read this instead of hardcoding a form — field names differ by corridor and can change.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        currency: {
+          type: 'string',
+          description: 'Optional ISO code, e.g. MXN',
+        },
+      },
+    },
   },
   {
     name: 'get_requirements',
@@ -58,9 +66,15 @@ const TOOLS = [
     inputSchema: {
       type: 'object',
       properties: {
-        amount: { type: 'string', description: 'Amount to send, e.g. "200.00"' },
+        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.' },
+        from: {
+          type: 'string',
+          description: 'Source currency. Defaults to USD.',
+        },
       },
       required: ['amount', 'to'],
     },
@@ -82,11 +96,13 @@ const TOOLS = [
         },
         externalId: {
           type: 'string',
-          description: 'Your own id for this beneficiary. Makes creation idempotent.',
+          description:
+            'Your own id for this beneficiary. Makes creation idempotent.',
         },
         details: {
           type: 'object',
-          description: 'Corridor fields from get_requirements, e.g. {"clabeNumber":"012..."}',
+          description:
+            'Corridor fields from get_requirements, e.g. {"clabeNumber":"012..."}',
         },
       },
       required: ['name', 'currency', 'details'],
@@ -102,6 +118,80 @@ const TOOLS = [
       properties: { endUserId: { type: 'string' } },
     },
   },
+  {
+    name: 'get_beneficiary',
+    annotations: { readOnlyHint: true },
+    description:
+      'One beneficiary by the id this API returned, with their payment methods and each destinationAccountId.',
+    inputSchema: {
+      type: 'object',
+      properties: { recipientId: { type: 'string' } },
+      required: ['recipientId'],
+    },
+  },
+  {
+    name: 'get_beneficiary_by_external_id',
+    annotations: { readOnlyHint: true },
+    description:
+      'One beneficiary by YOUR own id for them — the externalId you sent when you created them. Use this instead of listing everyone and filtering: it is unique per organization, so it returns exactly one or NOT_FOUND.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        externalId: {
+          type: 'string',
+          description: 'Your id for this beneficiary, e.g. "payroll-4471".',
+        },
+      },
+      required: ['externalId'],
+    },
+  },
+  {
+    name: 'update_beneficiary',
+    annotations: { readOnlyHint: false },
+    description:
+      'Correct a beneficiary’s contact details: name, email, phone, country, individual/business. Only the fields you pass change. BANK DETAILS CANNOT BE EDITED — a wrong account is a new payment method, and the old one is deleted.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        recipientId: { type: 'string' },
+        name: { type: 'string' },
+        email: { type: 'string' },
+        phone: { type: 'string' },
+        country: { type: 'string', description: 'ISO-3166 alpha-2, e.g. MX' },
+        type: { type: 'string', enum: ['individual', 'business'] },
+      },
+      required: ['recipientId'],
+    },
+  },
+  {
+    name: 'delete_beneficiary_method',
+    annotations: { destructiveHint: true, readOnlyHint: false },
+    description:
+      'Remove one way of paying a beneficiary — an account that closed, or one entered wrong. Irreversible, and the destinationAccountId it carried stops being payable, so it requires confirm:true. The beneficiary and their other methods are untouched.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        recipientId: { type: 'string' },
+        methodId: {
+          type: 'string',
+          description: 'From the beneficiary’s paymentMethods[].id.',
+        },
+        confirm: {
+          type: 'boolean',
+          description:
+            'Must be true. The account cannot be restored, only re-registered.',
+        },
+      },
+      required: ['recipientId', 'methodId', 'confirm'],
+    },
+  },
+  {
+    name: 'list_payment_reasons',
+    annotations: { readOnlyHint: true },
+    description:
+      'The stated payment reasons this organization may use. Some corridors require one on a payout; read this rather than inventing a value, because a rejected one is a 400 on a payout already promised to somebody.',
+    inputSchema: { type: 'object', properties: {} },
+  },
   {
     name: 'send_payout',
     annotations: { destructiveHint: true, readOnlyHint: false },
@@ -124,6 +214,12 @@ const TOOLS = [
           description:
             'What you told the payer they would receive. The send is refused if the binding quote drifts more than 2% from it.',
         },
+        amountLeg: {
+          type: 'string',
+          enum: ['source', 'destination', 'source_net'],
+          description:
+            "Which side `amount` describes. 'source' (default) takes the fees out of what you send. 'destination' pays the beneficiary that exact figure in THEIR currency and adds the fees to your debit. 'source_net' means the same but keeps the figure in the sender's currency — 'send them $200 worth' — converted at the market rate. The two locking modes need capabilities.exactOutput from list_corridors.",
+        },
         idempotencyKey: {
           type: 'string',
           description:
@@ -131,18 +227,14 @@ const TOOLS = [
         },
         confirm: {
           type: 'boolean',
-          description: 'Must be true. Explicit acknowledgement that this moves money.',
+          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',
-      ],
+      required: ['amount', 'destinationAccountId', 'confirm', 'idempotencyKey'],
     },
   },
   {
@@ -173,16 +265,77 @@ const TOOLS = [
     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.',
+      'The change feed: one row per transition, with a `sequence` cursor. This is the reconciliation primitive — carry `nextSince` back as `since` and you observe every revision. Each row\u2019s `data` is the webhook body for the same event (amounts, fee, reference). Payout, batch, approval and endpoint events share the feed; pass `type` to narrow it.',
     inputSchema: {
       type: 'object',
       properties: {
-        since: { type: 'string', description: 'A `sequence` from a previous page. Digits only.' },
+        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.' },
+        payoutId: {
+          type: 'string',
+          description: 'Only this payout\u2019s transitions.',
+        },
+        type: {
+          type: 'string',
+          description:
+            'Comma-separated event types, e.g. payout.completed,payout.failed,payout.returned. Unknown values are a 400.',
+        },
+      },
+    },
+  },
+  {
+    name: 'list_approvals',
+    annotations: { readOnlyHint: true },
+    description:
+      'Payouts and batch runs waiting on the organization\u2019s human approvers. send_payout answers 202 with `approvalId` when a policy holds it; this is that queue. Approving is a dashboard action — there is no tool for it, by design.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        status: { type: 'string', description: 'pending, approved, rejected, expired, executing, executed, execution_failed, execution_unknown.' },
+        limit: { type: 'number', description: '1-100, default 50.' },
       },
     },
   },
+  {
+    name: 'get_approval',
+    annotations: { readOnlyHint: true },
+    description:
+      'One approval by the `approvalId` a 202 returned. Once `status` is `executed`, `payoutId` is the payout it became.',
+    inputSchema: {
+      type: 'object',
+      properties: { approvalId: { type: 'string' } },
+      required: ['approvalId'],
+    },
+  },
+  {
+    name: 'list_audit_events',
+    annotations: { readOnlyHint: true },
+    description:
+      'Who did what, from where, with which credential: every audited mutation on the organization, newest first, refused attempts included. Rows carry the key prefix, actor, IP, requestId, outcome and errorType. Page with `cursor` = the `nextCursor` from the last page.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        cursor: { type: 'string', description: 'A `nextCursor` from a previous page. Digits only.' },
+        limit: { type: 'number', description: '1-100, default 50.' },
+        action: { type: 'string', description: 'e.g. payout.create, payout_batch.confirm, recipient.delete, api_key.rotate.' },
+        resourceId: { type: 'string', description: 'Everything done to one payout, batch, approval, beneficiary, key or endpoint.' },
+        apiKey: { type: 'string', description: 'A key prefix.' },
+        actorUserId: { type: 'string' },
+        createdAfter: { type: 'string', description: 'Inclusive, ISO-8601 with a timezone.' },
+        createdBefore: { type: 'string', description: 'Inclusive, ISO-8601 with a timezone.' },
+      },
+    },
+  },
+  {
+    name: 'get_policy',
+    annotations: { readOnlyHint: true },
+    description:
+      'What this organization is bound by, read live. Call it FIRST: payout caps in USD (null = no cap), the approval threshold and how many approvers a held payout needs, which features are on (mass_payouts, developer), rate limits per minute, idempotency windows, the currencies that require purposeOfPayment, and fees.payout (the pre-quote fee schedule; null = only priced inside a quote). Plan sends against it instead of discovering a cap from a 422 or an approval from a 202.',
+    inputSchema: { type: 'object', properties: {} },
+  },
   {
     name: 'get_balance',
     annotations: { readOnlyHint: true },
@@ -190,6 +343,24 @@ const TOOLS = [
       '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: 'list_balance_transactions',
+    annotations: { readOnlyHint: true },
+    description:
+      'Every change to the balance, newest first, each with `balanceAfter`: funding, payouts, returns, holds and their release, adjustments. Page with `cursor` = the `nextCursor` from the last page. An empty page means no rows yet, not an error.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        cursor: { type: 'string', description: 'A `nextCursor` from a previous page. Digits only.' },
+        limit: { type: 'number', description: '1-100, default 100.' },
+        type: { type: 'string', description: 'Comma-separated: funding, payout, payout_return, hold, hold_release, adjustment.' },
+        orderId: { type: 'string', description: 'Everything that moved for one payout.' },
+        currency: { type: 'string' },
+        createdAfter: { type: 'string', description: 'Inclusive, ISO-8601 with a timezone.' },
+        createdBefore: { type: 'string', description: 'Inclusive, ISO-8601 with a timezone.' },
+      },
+    },
+  },
   {
     name: 'get_funding',
     annotations: { readOnlyHint: true },
@@ -209,11 +380,23 @@ const TOOLS = [
     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.' },
+        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.' },
+        expiresInMinutes: {
+          type: 'number',
+          description: '1-10080, default 60.',
+        },
       },
       required: ['amount', 'destinationCurrency', 'endUserId'],
     },
@@ -227,10 +410,14 @@ const TOOLS = [
       type: 'object',
       properties: {
         payoutId: { type: 'string' },
-        transactionHash: { type: 'string', description: '0x-prefixed 32-byte hex.' },
+        transactionHash: {
+          type: 'string',
+          description: '0x-prefixed 32-byte hex.',
+        },
         confirm: {
           type: 'boolean',
-          description: 'Must be true. This commits funds you have already sent.',
+          description:
+            'Must be true. This commits funds you have already sent.',
         },
       },
       required: ['payoutId', 'transactionHash', 'confirm'],
@@ -258,15 +445,52 @@ const TOOLS = [
 async function dispatch(client, name, args) {
   switch (name) {
     case 'list_corridors':
-      return client.corridors();
+      return client.corridors(args.currency);
     case 'get_requirements':
       return client.requirements(args.currency);
     case 'quote':
-      return client.quote({ amount: args.amount, to: args.to, from: args.from });
+      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 'get_beneficiary':
+      return client.getBeneficiary(args.recipientId);
+    case 'get_beneficiary_by_external_id':
+      return client.getBeneficiaryByExternalId(args.externalId);
+    case 'update_beneficiary':
+      // An empty patch is a round trip that changes nothing and reads back as
+      // success — which an agent will report as "done". Name the editable
+      // fields instead, since the one it probably wanted is not among them.
+      if (
+        !['name', 'email', 'phone', 'country', 'type'].some(
+          (f) => args[f] !== undefined,
+        )
+      ) {
+        throw new Error(
+          'update_beneficiary needs at least one of name, email, phone, country, type. Bank details are not editable: register a new payment method and delete the old one.',
+        );
+      }
+      return client.updateBeneficiary(args.recipientId, {
+        name: args.name,
+        email: args.email,
+        phone: args.phone,
+        country: args.country,
+        type: args.type,
+      });
+    case 'delete_beneficiary_method':
+      if (args.confirm !== true) {
+        throw new Error(
+          'delete_beneficiary_method is irreversible and requires confirm:true. The account can only be re-registered, not restored — check with whoever owns this beneficiary first.',
+        );
+      }
+      return client.deleteBeneficiaryMethod(args.recipientId, args.methodId);
+    case 'list_payment_reasons':
+      return client.paymentReasons();
     case 'send_payout':
       if (args.confirm !== true) {
         throw new Error(
@@ -276,6 +500,7 @@ async function dispatch(client, name, args) {
       return client.payout({
         amount: args.amount,
         destinationAccountId: args.destinationAccountId,
+        amountLeg: args.amountLeg,
         purposeOfPayment: args.purposeOfPayment,
         reference: args.reference,
         expectDestinationAmount: args.expectDestinationAmount,
@@ -295,9 +520,37 @@ async function dispatch(client, name, args) {
         since: args.since,
         limit: args.limit,
         payoutId: args.payoutId,
+        type: args.type,
       });
+    case 'list_approvals':
+      return client.listApprovals({ status: args.status, limit: args.limit });
+    case 'get_approval':
+      return client.getApproval(args.approvalId);
+    case 'list_audit_events':
+      return client.listAuditEvents({
+        cursor: args.cursor,
+        limit: args.limit,
+        action: args.action,
+        resourceId: args.resourceId,
+        apiKey: args.apiKey,
+        actorUserId: args.actorUserId,
+        createdAfter: args.createdAfter,
+        createdBefore: args.createdBefore,
+      });
+    case 'get_policy':
+      return client.getPolicy();
     case 'get_balance':
       return client.balance();
+    case 'list_balance_transactions':
+      return client.listBalanceTransactions({
+        cursor: args.cursor,
+        limit: args.limit,
+        type: args.type,
+        orderId: args.orderId,
+        currency: args.currency,
+        createdAfter: args.createdAfter,
+        createdBefore: args.createdBefore,
+      });
     case 'get_funding':
       return client.getFunding(args.payoutId);
     case 'create_payout_link':
@@ -353,8 +606,7 @@ function createServer({ makeClient = () => new PayoutsClient(), write } = {}) {
             // 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',
+            protocolVersion: (params && params.protocolVersion) || '2025-06-18',
             capabilities: { tools: {} },
             serverInfo: SERVER,
           });
@@ -371,9 +623,7 @@ function createServer({ makeClient = () => new PayoutsClient(), write } = {}) {
           try {
             const out = await dispatch(clientOnce(), name, args);
             return reply({
-              content: [
-                { type: 'text', text: JSON.stringify(out, null, 2) },
-              ],
+              content: [{ type: 'text', text: JSON.stringify(out, null, 2) }],
             });
           } catch (err) {
             // Tool errors belong in the result with isError, not as protocol