@inflowpayai/inflow 0.5.2 → 0.6.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +105 -37
- package/dist/cli.js +2114 -531
- package/package.json +6 -4
package/README.md
CHANGED
|
@@ -9,20 +9,26 @@ should request.
|
|
|
9
9
|
|
|
10
10
|
## Command index
|
|
11
11
|
|
|
12
|
-
| Command | Purpose
|
|
13
|
-
| ------------------------------------ |
|
|
14
|
-
| `inflow auth login` | Run the OAuth device flow to authenticate. Saves a refreshable access token.
|
|
15
|
-
| `inflow auth logout` | Clear the saved access token and API key from local config.
|
|
16
|
-
| `inflow auth status` | Show which credential the CLI would use, plus the active environment and resolved API URL.
|
|
17
|
-
| `inflow user get` | Fetch the authenticated user's profile.
|
|
18
|
-
| `inflow balances list` | List the authenticated user's balances.
|
|
19
|
-
| `inflow deposit-addresses list` | List the user's configured deposit addresses, grouped by network.
|
|
20
|
-
| `inflow x402 pay <url>` | Probe a seller; if it returns 402, drive the approval flow and replay the request with the signed `PAYMENT-SIGNATURE`.
|
|
21
|
-
| `inflow x402 inspect <url>` | Read-only probe. Show the seller's `PAYMENT-REQUIRED` accepts for a URL — no auth, no payment.
|
|
22
|
-
| `inflow x402 status <transactionId>` | Poll the signing state of an in-flight transaction. Used to resume a previous `pay` across CLI invocations.
|
|
23
|
-
| `inflow x402 cancel <approvalId>` | Best-effort cancel of an in-flight approval. Always reports success.
|
|
24
|
-
| `inflow x402 decode <header>` | Decode a raw `PAYMENT-REQUIRED` header value. No auth required.
|
|
25
|
-
| `inflow x402 supported` | List the buyer-side `(scheme, network)` capability cache.
|
|
12
|
+
| Command | Purpose |
|
|
13
|
+
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
|
|
14
|
+
| `inflow auth login` | Run the OAuth device flow to authenticate. Saves a refreshable access token. |
|
|
15
|
+
| `inflow auth logout` | Clear the saved access token and API key from local config. |
|
|
16
|
+
| `inflow auth status` | Show which credential the CLI would use, plus the active environment and resolved API URL. |
|
|
17
|
+
| `inflow user get` | Fetch the authenticated user's profile. |
|
|
18
|
+
| `inflow balances list` | List the authenticated user's balances. |
|
|
19
|
+
| `inflow deposit-addresses list` | List the user's configured deposit addresses, grouped by network. |
|
|
20
|
+
| `inflow x402 pay <url>` | Probe a seller; if it returns 402, drive the approval flow and replay the request with the signed `PAYMENT-SIGNATURE`. |
|
|
21
|
+
| `inflow x402 inspect <url>` | Read-only probe. Show the seller's `PAYMENT-REQUIRED` accepts for a URL — no auth, no payment. |
|
|
22
|
+
| `inflow x402 status <transactionId>` | Poll the signing state of an in-flight transaction. Used to resume a previous `pay` across CLI invocations. |
|
|
23
|
+
| `inflow x402 cancel <approvalId>` | Best-effort cancel of an in-flight approval. Always reports success. |
|
|
24
|
+
| `inflow x402 decode <header>` | Decode a raw `PAYMENT-REQUIRED` header value. No auth required. |
|
|
25
|
+
| `inflow x402 supported` | List the buyer-side `(scheme, network)` capability cache. |
|
|
26
|
+
| `inflow mpp pay <url>` | Probe a seller; if it returns a `WWW-Authenticate: Payment` 402, fulfil the challenge and replay with `Authorization: Payment`. |
|
|
27
|
+
| `inflow mpp inspect <url>` | Read-only probe. Parse the seller's MPP `Payment` challenge(s) for a URL — no auth, no payment. |
|
|
28
|
+
| `inflow mpp status <transactionId>` | Poll the buyer-side state of an in-flight MPP transaction. Used to resume a previous `pay` across CLI invocations. |
|
|
29
|
+
| `inflow mpp cancel <approvalId>` | Best-effort cancel of an in-flight MPP approval. Always reports success. |
|
|
30
|
+
| `inflow mpp decode <value>` | Decode a `WWW-Authenticate: Payment` header, or a base64url credential / receipt. No auth required. |
|
|
31
|
+
| `inflow mpp supported` | List the methods the buyer can pay with — by intent, settlement rail, and currency. |
|
|
26
32
|
|
|
27
33
|
## Global flags
|
|
28
34
|
|
|
@@ -142,22 +148,22 @@ with the signed `PAYMENT-SIGNATURE` header.
|
|
|
142
148
|
|
|
143
149
|
#### Useful flags
|
|
144
150
|
|
|
145
|
-
| Flag | Default | Notes
|
|
146
|
-
| -------------------------------- | ------- |
|
|
147
|
-
| `--method <verb>` | `GET` | HTTP method for the seller request.
|
|
148
|
-
| `--data <body>` | — | Request body. Sets `Content-Type: application/json` unless a `--header` overrides it.
|
|
149
|
-
| `--header <"Name: Value">` | — | Repeatable. Forwarded on both the probe and the replay.
|
|
150
|
-
| `--scheme <scheme>` | — | Constrain the picked `accepts[]` entry to a specific scheme (e.g. `balance`, `exact`).
|
|
151
|
-
| `--network <network>` | — | Constrain the picked `accepts[]` entry to a specific network (e.g. `inflow:1`, `eip155:84532`, `solana:...`).
|
|
152
|
-
| `--asset <asset>` | — | Constrain the picked `accepts[]` entry to a specific on-chain asset identifier (ERC-20 contract address for EVM, mint pubkey for SVM).
|
|
153
|
-
| `--asset-name <name>` | — | Constrain the picked `accepts[]` entry by its `extra.
|
|
154
|
-
| `--interval <seconds>` | `0` | Inline poll cadence while awaiting approval. `0` returns the approval URL and a follow-up command hint without blocking.
|
|
155
|
-
| `--max-attempts <n>` | `0` | Hard cap on poll attempts when `--interval > 0`. `0` is unlimited.
|
|
156
|
-
| `--timeout <seconds>` | `900` | Polling deadline. Matches `@inflowpayai/x402-buyer`'s default approval expiry.
|
|
157
|
-
| `--payment-id <id>` | — | Caller-supplied payment identifier (16–128 chars, `^[a-zA-Z0-9_-]+$`). Forwarded to the server as `remotePaymentId`.
|
|
158
|
-
| `--show-body` / `--no-show-body` | `true` | Include the seller response body inline in the result. Default suits AI assistants paying for content.
|
|
159
|
-
| `--output-file <path>` | — | Write the seller response body bytes to disk (overwrites silently) and surface `output_saved_to: <abs-path>` instead of `body` / `body_base64`. Natural for binary downloads. Pair with `--no-show-body`.
|
|
160
|
-
| `--payload-file <path>` | — | Write the signed `encoded_payload` bytes to disk (mode `0o600`, overwrites silently) and surface `payload_saved_to: <abs-path>` instead of `encoded_payload`. Keeps one-time payment credentials out of chat transcripts and logs.
|
|
151
|
+
| Flag | Default | Notes |
|
|
152
|
+
| -------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
153
|
+
| `--method <verb>` | `GET` | HTTP method for the seller request. |
|
|
154
|
+
| `--data <body>` | — | Request body. Sets `Content-Type: application/json` unless a `--header` overrides it. |
|
|
155
|
+
| `--header <"Name: Value">` | — | Repeatable. Forwarded on both the probe and the replay. |
|
|
156
|
+
| `--scheme <scheme>` | — | Constrain the picked `accepts[]` entry to a specific scheme (e.g. `balance`, `exact`). |
|
|
157
|
+
| `--network <network>` | — | Constrain the picked `accepts[]` entry to a specific network (e.g. `inflow:1`, `eip155:84532`, `solana:...`). |
|
|
158
|
+
| `--asset <asset>` | — | Constrain the picked `accepts[]` entry to a specific on-chain asset identifier (ERC-20 contract address for EVM, mint pubkey for SVM). |
|
|
159
|
+
| `--asset-name <name>` | — | Constrain the picked `accepts[]` entry by its `extra.assetName` — the human-readable symbol the seller advertises (e.g. `USDC`). Distinct from `extra.name` (the EIP-712 domain, e.g. `USD Coin`); matches the symbol, not the on-chain asset. |
|
|
160
|
+
| `--interval <seconds>` | `0` | Inline poll cadence while awaiting approval. `0` returns the approval URL and a follow-up command hint without blocking. |
|
|
161
|
+
| `--max-attempts <n>` | `0` | Hard cap on poll attempts when `--interval > 0`. `0` is unlimited. |
|
|
162
|
+
| `--timeout <seconds>` | `900` | Polling deadline. Matches `@inflowpayai/x402-buyer`'s default approval expiry. |
|
|
163
|
+
| `--payment-id <id>` | — | Caller-supplied payment identifier (16–128 chars, `^[a-zA-Z0-9_-]+$`). Forwarded to the server as `remotePaymentId`. |
|
|
164
|
+
| `--show-body` / `--no-show-body` | `true` | Include the seller response body inline in the result. Default suits AI assistants paying for content. |
|
|
165
|
+
| `--output-file <path>` | — | Write the seller response body bytes to disk (overwrites silently) and surface `output_saved_to: <abs-path>` instead of `body` / `body_base64`. Natural for binary downloads. Pair with `--no-show-body`. |
|
|
166
|
+
| `--payload-file <path>` | — | Write the signed `encoded_payload` bytes to disk (mode `0o600`, overwrites silently) and surface `payload_saved_to: <abs-path>` instead of `encoded_payload`. Keeps one-time payment credentials out of chat transcripts and logs. |
|
|
161
167
|
|
|
162
168
|
#### TTY example
|
|
163
169
|
|
|
@@ -225,9 +231,10 @@ inflow x402 pay https://seller.example.com/api/widgets \
|
|
|
225
231
|
|
|
226
232
|
`--scheme`, `--network`, `--asset`, and `--asset-name` are independent and AND-combined: each one that's set narrows the
|
|
227
233
|
seller's `accepts[]` further. `--asset` matches the on-chain asset identifier; `--asset-name` matches the
|
|
228
|
-
seller-declared `extra.
|
|
229
|
-
|
|
230
|
-
|
|
234
|
+
seller-declared `extra.assetName` symbol (e.g. `USDC`) — not `extra.name`, which is the EIP-712 domain (e.g.
|
|
235
|
+
`USD Coin`). When the resulting set is empty the command fails with `NO_FILTERED_MATCH` and the message reports the
|
|
236
|
+
scheme/network/asset/name tuples the seller actually advertises. When a match exists but the buyer-side cache can't sign
|
|
237
|
+
it, the existing `NO_INFLOW_MATCH` still fires — filtering and routing are orthogonal.
|
|
231
238
|
|
|
232
239
|
### `x402 inspect`
|
|
233
240
|
|
|
@@ -241,8 +248,8 @@ no replay. Useful for surfacing the seller's prices and network choices to a use
|
|
|
241
248
|
|
|
242
249
|
TTY renders a table with proper-cased headers — `Scheme`, `Network`, `Amount`, `Asset`, `Pay To`, `Timeout`, `Extra` —
|
|
243
250
|
with `Pay To` rendered verbatim (no truncation). The `Extra` column shows the comma-separated keys of the
|
|
244
|
-
scheme-specific `extra` record (e.g. `name, version, assetTransferMethod` for EIP-3009
|
|
245
|
-
values.
|
|
251
|
+
scheme-specific `extra` record (e.g. `assetName, name, version, assetTransferMethod` for EIP-3009, where `assetName` is
|
|
252
|
+
the symbol `--asset-name` matches on); pass `--format json` to see the values.
|
|
246
253
|
|
|
247
254
|
```
|
|
248
255
|
PAYMENT-REQUIRED for https://seller.example.com/api/widgets · x402Version 2 · 3 accepts
|
|
@@ -250,7 +257,7 @@ PAYMENT-REQUIRED for https://seller.example.com/api/widgets · x402Version 2
|
|
|
250
257
|
Scheme Network Amount Asset Pay To Timeout Extra
|
|
251
258
|
------- ------------------------------------------- ------ ----- ------------------------------------------- ------- -----------------------------------
|
|
252
259
|
balance inflow:1 500 USDC inflow:abc 60s —
|
|
253
|
-
exact eip155:84532 500 USDC 0xAbCdEfABcDef0123456789aBcDeF0123456789aB 60s name, version, assetTransferMethod
|
|
260
|
+
exact eip155:84532 500 USDC 0xAbCdEfABcDef0123456789aBcDeF0123456789aB 60s assetName, name, version, assetTransferMethod
|
|
254
261
|
exact solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1 500 USDC sol-payto 60s —
|
|
255
262
|
|
|
256
263
|
Use --format json to inspect extras values.
|
|
@@ -273,7 +280,7 @@ Agent shape:
|
|
|
273
280
|
"asset": "USDC",
|
|
274
281
|
"pay_to": "0xabc...",
|
|
275
282
|
"max_timeout_seconds": 60,
|
|
276
|
-
"extra": { "name": "USD Coin", "version": "2", "assetTransferMethod": "eip3009" },
|
|
283
|
+
"extra": { "assetName": "USDC", "name": "USD Coin", "version": "2", "assetTransferMethod": "eip3009" },
|
|
277
284
|
},
|
|
278
285
|
],
|
|
279
286
|
}
|
|
@@ -349,6 +356,67 @@ code. The `x402` group adds these codes:
|
|
|
349
356
|
| `POLLING_TIMEOUT` | `x402 status --interval` exhausted its budget before the transaction settled. Retryable. |
|
|
350
357
|
| `INSPECT_FAILED` | Transport-layer failure during `x402 inspect` (DNS, connection refused, etc.). |
|
|
351
358
|
|
|
359
|
+
## `mpp`
|
|
360
|
+
|
|
361
|
+
The `mpp` command group is the MPP analog of `x402`, for sellers that answer `402` with `WWW-Authenticate: Payment …`
|
|
362
|
+
(the MPP `Payment` auth scheme) instead of x402's `PAYMENT-REQUIRED`. It is built on `@inflowpayai/mpp`'s `MppClient`
|
|
363
|
+
and mirrors `x402` command-for-command — `pay`, `inspect`, `status`, `cancel`, `decode`, `supported` — with the same
|
|
364
|
+
TTY + agent renderings, the same two-process approval handoff, and the same `--output-file` / `--format` behaviour.
|
|
365
|
+
|
|
366
|
+
```bash
|
|
367
|
+
inflow mpp inspect <url> # parse the seller's Payment challenge(s) — read-only
|
|
368
|
+
inflow mpp pay <url> --interval 5 --max-attempts 60 # fast path: create -> poll -> replay -> return body
|
|
369
|
+
inflow mpp pay <url> --format json # two-process: returns transaction_id + a `mpp status` _next hint
|
|
370
|
+
inflow mpp status <transactionId> --interval 5 # resume an in-flight transaction; ready frames carry `credential`
|
|
371
|
+
inflow mpp cancel <approvalId> # best-effort cancel of a pending approval
|
|
372
|
+
inflow mpp decode '<WWW-Authenticate: Payment value>' # or a base64url credential / receipt
|
|
373
|
+
inflow mpp supported # methods the buyer can pay with: method -> intent -> rail -> currencies
|
|
374
|
+
```
|
|
375
|
+
|
|
376
|
+
Differences from `x402`:
|
|
377
|
+
|
|
378
|
+
- The seller's challenge pins the settlement rail, so the buyer does not choose a scheme/network/asset the way x402
|
|
379
|
+
does. Instead the buyer narrows _which advertised challenge_ to fulfil (see the flags below), then optionally names a
|
|
380
|
+
funding instrument.
|
|
381
|
+
- `pay` (when ready) and `status` surface a base64url `credential`; replay the request with
|
|
382
|
+
`Authorization: Payment <credential>`. `--credential-file <path>` writes it at mode `0o600` and the frame carries
|
|
383
|
+
`credential_saved_to` instead of `credential` — the analog of x402's `--payload-file` / `encoded_payload`.
|
|
384
|
+
- A 402 carrying no `inflow`-method challenge fails with `NO_INFLOW_MATCH`.
|
|
385
|
+
|
|
386
|
+
#### Challenge-selection flags (`pay` and `inspect`)
|
|
387
|
+
|
|
388
|
+
These narrow the seller's advertised challenge set; each is independent and AND-combined. When the result is empty the
|
|
389
|
+
command fails with `NO_FILTERED_MATCH`. (`x402`'s `--scheme`/`--network`/`--asset`/`--asset-name` have no MPP analog —
|
|
390
|
+
the rail is fixed by the seller, so the buyer filters by method/intent/currency/rail instead.)
|
|
391
|
+
|
|
392
|
+
| Flag | Notes |
|
|
393
|
+
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
394
|
+
| `--payment-method <m>` | Only consider challenges with this payment method (e.g. `inflow`). |
|
|
395
|
+
| `--intent <intent>` | Only consider challenges with this intent (e.g. `charge`). |
|
|
396
|
+
| `--currency <CODE>` | Only consider challenges in this currency (e.g. `USDC`). Disambiguates when the seller offers the `inflow` method in more than one currency. |
|
|
397
|
+
| `--rail <rail>` | Only consider challenges on this settlement rail (e.g. `balance`, `instrument`). |
|
|
398
|
+
| `--instrument-id <uuid>` | Funding instrument id for an instrument-rail (fiat) challenge. The only option that selects _how_ to fund rather than which challenge — the rail itself is seller-pinned. |
|
|
399
|
+
|
|
400
|
+
### Errors (mpp group)
|
|
401
|
+
|
|
402
|
+
Same `--format json` envelope as `x402` (`{ code, message, retryable? }` plus a non-zero exit code). The shared
|
|
403
|
+
probe/decode/match codes carry the same meaning as in the `x402` table above; the rail-specific terminal codes differ:
|
|
404
|
+
|
|
405
|
+
| Code | When |
|
|
406
|
+
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
407
|
+
| `NOT_AUTHENTICATED` | No saved device token and no `--api-key`. (Not raised by `inspect` or `decode` — both are auth-free.) |
|
|
408
|
+
| `INVALID_HEADER` | A `--header` flag wasn't in `Name: Value` form. |
|
|
409
|
+
| `INVALID_402` | Seller returned 402 without a parseable `WWW-Authenticate: Payment` challenge. |
|
|
410
|
+
| `DECODE_FAILED` | Challenge / credential / receipt parse failed. |
|
|
411
|
+
| `UNEXPECTED_PROBE_STATUS` | Seller returned a non-2xx, non-402 status during the probe. Raised by `pay` and `inspect`. |
|
|
412
|
+
| `NO_INFLOW_MATCH` | The 402 carried no `inflow`-method challenge the buyer can fulfil. |
|
|
413
|
+
| `NO_FILTERED_MATCH` | `--payment-method` / `--intent` / `--currency` / `--rail` excluded every challenge. The message lists the challenges the seller actually advertised. |
|
|
414
|
+
| `PAYMENT_NOT_ACCEPTED` | The seller still returned non-2xx on the replayed (`Authorization: Payment`) request. The transaction was ready but the seller did not honour the credential. |
|
|
415
|
+
| `PAYMENT_FAILED` | The transaction reached a terminal `failed` state, or the pay pipeline could not produce a credential. |
|
|
416
|
+
| `PAYMENT_EXPIRED` | The transaction expired before it became ready. |
|
|
417
|
+
| `POLLING_TIMEOUT` | `mpp status --interval` exhausted its budget before the transaction became ready. Retryable. |
|
|
418
|
+
| `INSPECT_FAILED` | Transport-layer failure during `mpp inspect` (DNS, connection refused, etc.). |
|
|
419
|
+
|
|
352
420
|
## Notes
|
|
353
421
|
|
|
354
422
|
Output is intentionally machine-parseable when `--format` is set, even on the error path. AI assistants and pipelines
|