@avvio/payments 0.1.0 → 0.5.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "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.",
+  "version": "0.5.0",
+  "description": "Pay out to your own customers from your Avvio balance. CLI, MCP server, and Node client \u2014 zero dependencies.",
   "license": "MIT",
   "engines": {
     "node": ">=18"
@@ -11,7 +11,7 @@
     "url": "git+https://github.com/anzolabs/anzolabs-B2B-backend.git",
     "directory": "packages/avvio-payments"
   },
-  "homepage": "https://avvio-docs.pages.dev",
+  "homepage": "https://docs.avvio.xyz",
   "bugs": {
     "url": "https://github.com/anzolabs/anzolabs-B2B-backend/issues",
     "email": "support@avvio.xyz"
@@ -47,9 +47,15 @@
     "test": "node --test test/*.test.js"
   },
   "keywords": [
-    "payouts",
+    "avvio",
     "cross-border",
-    "mcp"
+    "cross-border-payments",
+    "mass-payments",
+    "mcp",
+    "payout-api",
+    "payouts",
+    "stablecoin",
+    "usdc"
   ],
   "types": "index.d.ts"
 }

package/src/cli.js

@@ -20,8 +20,10 @@ avvio-payments — pay out to your customers from your balance
     mcp                         Run as an MCP server over stdio (for agents)
 
   Discovery
+    policy                      Your caps, approval threshold, features and rate limits: read first
     corridors                   Currencies you can pay out to
     requirements <CCY>          Fields a beneficiary in that currency needs
+    payment-reasons             What --purpose may say, where one is required
 
   Pricing
     quote --amount 200 --to MXN         What the recipient gets, and the fee
@@ -30,30 +32,52 @@ avvio-payments — pay out to your customers from your balance
     beneficiary create --name "Maria Gonzalez" --email maria@example.com \\
       --currency MXN --end-user emp_42 \\
       --external-id emp42_maria \\
-      --field clabeNumber=012345678901234567
+      --field clabeNumber=012180000080004471
       [--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>]
+    beneficiary get <id> | beneficiary get --external-id emp42_maria
+    beneficiary update <id> [--name] [--email] [--phone] [--country] [--type]
+                                Contact details only. Bank details are not
+                                editable — register a new method instead
+    beneficiary delete <id>     Removes them and every method on them
+    beneficiary method delete|details <id> <methodId>
+                                Drop one account, or read the whole one on file
 
   Sandbox
     fund [--amount 5000]        Credit your test balance
-    balance [--history]         What you can send; --history explains every change
+    balance                     What you can send (network figure and our ledger)
 
   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]
+        [--exact]                       --amount is what they RECEIVE, in their currency
+        [--worth]                       --amount is what they receive, in YOURS; fees on top
     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]
+    events [--since <sequence>] [--limit N] [--payout-id ID] [--type a,b] [--follow]
                                 Every transition, in order. Carry the returned
-                                nextSince back as --since; --follow polls and
-                                prints new rows as they land (--interval SECONDS)
+                                nextSince back as --since; --type narrows to the
+                                families you book; --follow polls and prints new
+                                rows as they land (--interval SECONDS)
+    approvals [--status pending] Payouts and runs waiting on your approvers
+                                (a 202 from pay or a batch confirm). Deciding
+                                one is a dashboard action, not a command
+    approval <approvalId>       One approval; executed ones name the payoutId
+    audit-events [--cursor <id>] [--limit N] [--action payout.create]
+                 [--resource-id ID] [--api-key <prefix>] [--actor <userId>]
+                 [--after ISO] [--before ISO]
+                                Who did what, with which credential, newest first
+    balance-transactions [--cursor <id>] [--limit N] [--type payout,funding]
+                         [--order-id ID] [--currency USD] [--after ISO] [--before ISO]
+                                Every change to your balance, newest first, with
+                                balanceAfter. Carry nextCursor back as --cursor
 
   Funding
     funding                     Where to wire money to top up your balance
@@ -61,19 +85,24 @@ avvio-payments — pay out to your customers from your balance
                                 yourself (requiresFunding: true)
     funding confirm <payoutId> --tx <hash>
                                 Report the transfer you already sent
+                                this API. Takes a quote — not for a loop
 
   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
+  Webhooks
+    webhook create --url <url>  Sandbox only. Register an endpoint, print its
+                                signing secret (--events a,b; localhost ok)
+    webhook deliveries <id>     Sandbox endpoint: what we sent and retried
+    webhook endpoints           Endpoints registered for your org (read-only —
+                                registering and pausing are dashboard actions)
+    webhook attempts <id>       Last 50 delivery attempts for a registered
+                                endpoint: eventId, attempts, lastError
 
   Configuration (environment)
-    AVVIO_API_KEY   required    Server-side only. Never ship it to a browser or a phone.
+    AVVIO_API_KEY   required    Complete avvio_live_* or avvio_test_* bearer key
     AVVIO_ORG_ID    required
     AVVIO_BASE_URL  optional
 
@@ -145,13 +174,26 @@ async function doctor(json) {
   const add = (name, ok, detail) => checks.push({ name, ok, detail });
 
   const key = process.env.AVVIO_API_KEY;
+  // PARKED request-signing configuration:
+  // const privateKey = process.env.AVVIO_PRIVATE_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');
+  const bearerKey =
+    /^avvio_(?:live|test)_[0-9a-f]{32}_[A-Za-z0-9_-]{43}$/.test(key || '');
+  add(
+    'AVVIO_API_KEY bearer format',
+    bearerKey,
+    bearerKey
+      ? 'valid complete bearer key'
+      : 'legacy or unrecognized credential',
+  );
+  // PARKED request-signing check:
+  // add('AVVIO_PRIVATE_KEY set', !!privateKey, ...);
   add('AVVIO_ORG_ID set', !!org, org || 'missing');
   add('AVVIO_BASE_URL', true, base);
-  if (!key || !org) {
+  if (!key || !bearerKey || !org) {
     report(checks, json);
     process.exitCode = 1;
     return;
@@ -272,7 +314,7 @@ Send your first payout — five commands, about two minutes.
   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
+       --field clabeNumber=012180000080004471
 
   5. Price it, then send it
      avvio-payments quote --amount 200 --to MXN
@@ -367,19 +409,98 @@ async function run(argv) {
           json,
         );
       }
-      throw new Error('Usage: beneficiary <create|list>');
+      if (sub === 'get') {
+        // Two ways in, because a partner holds one of two ids: ours, or theirs.
+        // `--external-id` is the one they already have in their own database.
+        const id = positional[2];
+        const external = flags['external-id'];
+        if (external && external !== true) {
+          return out(await client.getBeneficiaryByExternalId(external), json);
+        }
+        if (!id) {
+          throw new Error(
+            'Usage: beneficiary get <recipientId> | beneficiary get --external-id <your id>',
+          );
+        }
+        return out(await client.getBeneficiary(id), json);
+      }
+      if (sub === 'update') {
+        const id = positional[2];
+        if (!id) {
+          throw new Error(
+            'Usage: beneficiary update <recipientId> [--name] [--email] [--phone] [--country] [--type]',
+          );
+        }
+        const patch = {};
+        for (const [flag, key] of [
+          ['name', 'name'],
+          ['email', 'email'],
+          ['phone', 'phone'],
+          ['country', 'country'],
+          ['type', 'type'],
+        ]) {
+          if (flags[flag] !== undefined && flags[flag] !== true) {
+            patch[key] = flags[flag];
+          }
+        }
+        if (!Object.keys(patch).length) {
+          // An empty PATCH is a round trip that changes nothing and reads like
+          // it worked. Say which fields exist rather than letting someone
+          // conclude the update was applied.
+          throw new Error(
+            'Nothing to update. Pass at least one of --name --email --phone --country --type.\n' +
+              'Bank details are not editable: register a new payment method and delete the old one.',
+          );
+        }
+        return out(await client.updateBeneficiary(id, patch), json);
+      }
+      if (sub === 'delete') {
+        const id = positional[2];
+        if (!id) throw new Error('Usage: beneficiary delete <recipientId>');
+        return out(await client.deleteBeneficiary(id), json);
+      }
+      if (sub === 'method') {
+        const action = positional[2];
+        const id = positional[3];
+        const methodId = positional[4];
+        if (!id || !methodId || !['delete', 'details'].includes(action)) {
+          throw new Error(
+            'Usage: beneficiary method <delete|details> <recipientId> <methodId>',
+          );
+        }
+        return out(
+          action === 'delete'
+            ? await client.deleteBeneficiaryMethod(id, methodId)
+            : await client.getBeneficiaryMethodDetails(id, methodId),
+          json,
+        );
+      }
+      throw new Error(
+        'Usage: beneficiary <create|list|get|update|delete|method>',
+      );
     }
 
+    case 'payment-reasons':
+      return out(await client.paymentReasons(), json);
+
     case 'pay': {
       if (!flags.amount || !flags.to) {
         throw new Error(
-          'Usage: pay --amount 200 --to <destinationAccountId> [--expect 3410.00]',
+          'Usage: pay --amount 200 --to <destinationAccountId> [--expect 3410.00] [--exact|--worth]',
         );
       }
       return out(
         await client.payout({
           amount: flags.amount,
           destinationAccountId: flags.to,
+          // `--exact` reads better at a prompt than `--amount-leg destination`.
+          // `--worth` is the same promise with the figure left in the sender's
+          // own currency, which is how a wage is denominated.
+          ...(flags.worth
+            ? { amountLeg: 'source_net' }
+            : flags.exact
+              ? { amountLeg: 'destination' }
+              : {}),
           reference: flags.reference,
           purposeOfPayment: flags.purpose,
           expectDestination: flags.expect,
@@ -443,6 +564,7 @@ async function run(argv) {
         since: flags.since,
         limit: flags.limit ? Number(flags.limit) : undefined,
         payoutId: flags['payout-id'],
+        type: flags.type,
       };
       if (!flags.follow) return out(await client.listEvents(args), json);
 
@@ -478,6 +600,37 @@ async function run(argv) {
     case 'payouts':
       return out(await client.listPayouts(), json);
 
+    case 'approvals':
+      return out(
+        await client.listApprovals({
+          status: flags.status,
+          limit: flags.limit ? Number(flags.limit) : undefined,
+        }),
+        json,
+      );
+
+    case 'approval': {
+      const id = positional[1];
+      if (!id) throw new Error('Usage: approval <approvalId>');
+      return out(await client.getApproval(id), json);
+    }
+
+    case 'audit-events':
+      // Newest first, one page per call; carry nextCursor back as --cursor.
+      return out(
+        await client.listAuditEvents({
+          cursor: flags.cursor,
+          limit: flags.limit ? Number(flags.limit) : undefined,
+          action: flags.action,
+          resourceId: flags['resource-id'],
+          apiKey: flags['api-key'],
+          actorUserId: flags.actor,
+          createdAfter: flags.after,
+          createdBefore: flags.before,
+        }),
+        json,
+      );
+
     case 'cancel': {
       // The recovery an operator actually reaches for: a payout created for the
       // wrong amount, before any money has been sent.
@@ -494,13 +647,26 @@ async function run(argv) {
       return out(res, json);
     }
 
+    case 'policy':
+      // Caps, approval threshold, features, rate limits: read before sending.
+      return out(await client.getPolicy(), json);
+
     case 'balance':
-      // `--history` answers "why did my balance change", which a single number
-      // never can.
+      return out(await client.balance(), json);
+
+    case 'balance-transactions':
+      // "Why did my balance change": every ledger row, holds included, newest
+      // first. One page per call; carry nextCursor back as --cursor.
       return out(
-        flags.history
-          ? await client.balanceHistory(flags.limit ? Number(flags.limit) : undefined)
-          : await client.balance(),
+        await client.listBalanceTransactions({
+          cursor: flags.cursor,
+          limit: flags.limit ? Number(flags.limit) : undefined,
+          type: flags.type,
+          orderId: flags['order-id'],
+          currency: flags.currency,
+          createdAfter: flags.after,
+          createdBefore: flags.before,
+        }),
         json,
       );
 
@@ -589,7 +755,25 @@ async function run(argv) {
         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>');
+      if (sub === 'endpoints') {
+        return out(await client.webhookEndpoints(), json);
+      }
+      if (sub === 'attempts') {
+        // Separate from `deliveries` rather than replacing it: that one reads a
+        // sandbox registration, this one reads a registered org endpoint. Same
+        // question, two different stores, and quietly repointing the existing
+        // command would answer about the wrong one.
+        const id = positional[2];
+        if (!id) {
+          throw new Error(
+            'webhook attempts needs an endpoint id — run: webhook endpoints',
+          );
+        }
+        return out(await client.webhookEndpointDeliveries(id), json);
+      }
+      throw new Error(
+        'webhook <create|deliveries|endpoints|attempts>',
+      );
     }
 
     default: