cspr402 0.4.7

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.
Files changed (63) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +173 -0
  3. package/dist/cli.d.ts +3 -0
  4. package/dist/cli.d.ts.map +1 -0
  5. package/dist/cli.js +108 -0
  6. package/dist/cli.js.map +1 -0
  7. package/dist/client.d.ts +207 -0
  8. package/dist/client.d.ts.map +1 -0
  9. package/dist/client.js +400 -0
  10. package/dist/client.js.map +1 -0
  11. package/dist/commands/onboard.d.ts +4 -0
  12. package/dist/commands/onboard.d.ts.map +1 -0
  13. package/dist/commands/onboard.js +192 -0
  14. package/dist/commands/onboard.js.map +1 -0
  15. package/dist/commands/onboard.test.d.ts +2 -0
  16. package/dist/commands/onboard.test.d.ts.map +1 -0
  17. package/dist/commands/onboard.test.js +48 -0
  18. package/dist/commands/onboard.test.js.map +1 -0
  19. package/dist/commands/purchase.d.ts +2 -0
  20. package/dist/commands/purchase.d.ts.map +1 -0
  21. package/dist/commands/purchase.js +206 -0
  22. package/dist/commands/purchase.js.map +1 -0
  23. package/dist/commands/wallet.d.ts +2 -0
  24. package/dist/commands/wallet.d.ts.map +1 -0
  25. package/dist/commands/wallet.js +161 -0
  26. package/dist/commands/wallet.js.map +1 -0
  27. package/dist/config.d.ts +77 -0
  28. package/dist/config.d.ts.map +1 -0
  29. package/dist/config.js +329 -0
  30. package/dist/config.js.map +1 -0
  31. package/dist/errors.d.ts +101 -0
  32. package/dist/errors.d.ts.map +1 -0
  33. package/dist/errors.js +197 -0
  34. package/dist/errors.js.map +1 -0
  35. package/dist/index.d.ts +6 -0
  36. package/dist/index.d.ts.map +1 -0
  37. package/dist/index.js +22 -0
  38. package/dist/index.js.map +1 -0
  39. package/dist/mcp.d.ts +2 -0
  40. package/dist/mcp.d.ts.map +1 -0
  41. package/dist/mcp.js +337 -0
  42. package/dist/mcp.js.map +1 -0
  43. package/dist/mpp.d.ts +57 -0
  44. package/dist/mpp.d.ts.map +1 -0
  45. package/dist/mpp.js +165 -0
  46. package/dist/mpp.js.map +1 -0
  47. package/dist/ows.d.ts +190 -0
  48. package/dist/ows.d.ts.map +1 -0
  49. package/dist/ows.js +565 -0
  50. package/dist/ows.js.map +1 -0
  51. package/dist/soroban.d.ts +92 -0
  52. package/dist/soroban.d.ts.map +1 -0
  53. package/dist/soroban.js +313 -0
  54. package/dist/soroban.js.map +1 -0
  55. package/dist/stellar.d.ts +53 -0
  56. package/dist/stellar.d.ts.map +1 -0
  57. package/dist/stellar.js +180 -0
  58. package/dist/stellar.js.map +1 -0
  59. package/dist/version-check.d.ts +5 -0
  60. package/dist/version-check.d.ts.map +1 -0
  61. package/dist/version-check.js +203 -0
  62. package/dist/version-check.js.map +1 -0
  63. package/package.json +80 -0
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 CTX.com
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,173 @@
1
+ # cards402
2
+
3
+ > CardCasper402 hackathon fork note: the default SDK root export is now kept to
4
+ > API/client helpers so Windows CI and demos do not load the legacy Stellar OWS
5
+ > native package. The active MVP path is Casper testnet CSPR order creation and
6
+ > deploy verification, with optional mockUSDC CEP-18 test-token payments. The Stellar/OWS sections below are upstream legacy
7
+ > reference material until they are rewritten or moved.
8
+
9
+ Virtual Visa cards for AI agents — pay with USDC or XLM on Stellar, get a card number, CVV, and expiry in ~60 seconds.
10
+
11
+ [cards402.com](https://cards402.com) issues prepaid Visa virtual cards on demand. This SDK lets AI agents create an order, pay the cards402 Soroban receiver contract on Stellar, and receive card details programmatically — all in one call.
12
+
13
+ ## Install
14
+
15
+ ```bash
16
+ npm install cards402
17
+ ```
18
+
19
+ Requires Node.js 18 or newer (the SDK uses native `fetch`, `ReadableStream`, and `WebCrypto`). Supported platforms via the bundled `@ctx.com/stellar-ows-core` native wallet bindings: macOS (arm64 + x64), Linux (arm64 + x64). Windows is not currently supported.
20
+
21
+ ### A note on `npm audit`
22
+
23
+ You'll see 3 critical advisories on `axios <= 1.14.0` after installing. They come from `@stellar/stellar-sdk`, which hard-pins an older axios version that we can't override from inside this package. The SDK's own HTTP calls only talk to hardcoded Stellar RPC / Horizon endpoints, so neither advisory (NO_PROXY SSRF, header-injection metadata exfil) is reachable through cards402 code — it's noise for our use, but noise you should still silence at your own project root.
24
+
25
+ Fix in your own `package.json`:
26
+
27
+ ```json
28
+ {
29
+ "overrides": {
30
+ "axios": "^1.15.0"
31
+ }
32
+ }
33
+ ```
34
+
35
+ then `rm -rf node_modules package-lock.json && npm install`. `npm audit` returns clean. Upstream fix tracked at [stellar/js-stellar-sdk#1381](https://github.com/stellar/js-stellar-sdk/pull/1381); this note will be removed as soon as it merges and a new stellar-sdk ships.
36
+
37
+ ## Quick start
38
+
39
+ ```typescript
40
+ import { createOWSWallet, getOWSBalance, purchaseCardOWS } from 'cards402';
41
+
42
+ // 1. Create (or fetch existing) encrypted wallet. Idempotent.
43
+ const { publicKey } = createOWSWallet('my-agent');
44
+ console.log('Fund this Stellar address:', publicKey);
45
+
46
+ // 2. Pause here until the address has funds. Re-run to check:
47
+ const bal = await getOWSBalance('my-agent');
48
+ console.log(`XLM: ${bal.xlm} USDC: ${bal.usdc}`);
49
+
50
+ // 3. Purchase a card — only do this when the user explicitly asks.
51
+ const card = await purchaseCardOWS({
52
+ apiKey: process.env.CARDS402_API_KEY!,
53
+ walletName: 'my-agent',
54
+ amountUsdc: '10.00',
55
+ paymentAsset: 'xlm', // or 'usdc' (trustline added automatically)
56
+ });
57
+
58
+ console.log(card.number, card.cvv, card.expiry);
59
+ ```
60
+
61
+ `purchaseCardOWS` handles the whole flow:
62
+
63
+ 1. `POST /v1/orders` with the amount
64
+ 2. Sign + submit the Soroban payment from your OWS wallet
65
+ 3. Subscribe to the SSE stream at `/v1/orders/:id/stream`
66
+ 4. Return the card details as soon as the `ready` event arrives
67
+
68
+ No polling loops, no webhook endpoint required.
69
+
70
+ ## Funding your wallet
71
+
72
+ Stellar accounts need a minimum balance to be activated on-chain:
73
+
74
+ - **Pay with XLM:** send ≥ 1 XLM to cover the base reserve, plus whatever XLM the card costs at the current spot rate (shown in `payment.xlm.amount` when you create an order).
75
+ - **Pay with USDC:** send ≥ 2 XLM (1 base reserve + 1 for the USDC trustline entry), plus the USDC card amount. The SDK will add the trustline automatically the first time you purchase with USDC, so you just need the ≥ 2 XLM on-chain before calling `purchaseCardOWS`.
76
+
77
+ ## Step-by-step API (for more control)
78
+
79
+ ```typescript
80
+ import { Cards402Client } from 'cards402';
81
+
82
+ const client = new Cards402Client({
83
+ apiKey: process.env.CARDS402_API_KEY!,
84
+ // baseUrl defaults to https://api.cards402.com/v1
85
+ });
86
+
87
+ // Create the order
88
+ const order = await client.createOrder({ amount_usdc: '10.00' });
89
+ console.log(`Pay ${order.payment.xlm.amount} XLM to contract ${order.payment.contract_id}`);
90
+
91
+ // ... submit the Soroban transaction yourself, or use the payViaContract helpers ...
92
+
93
+ // Wait for delivery (uses SSE under the hood, with polling fallback)
94
+ const card = await client.waitForCard(order.order_id, { timeoutMs: 120000 });
95
+ console.log(card.number, card.cvv, card.expiry);
96
+ ```
97
+
98
+ ### CardCasper402 Casper testnet flow
99
+
100
+ ```typescript
101
+ const csprOrder = await client.createOrder({ amount_usdc: '10.00' });
102
+ // Submit csprOrder.payment as a Casper native transfer, then verify:
103
+ await client.verifyCasperPayment(csprOrder.order_id, deployHash, { senderPublicKey });
104
+
105
+ const mockUsdcOrder = await client.createOrder({
106
+ amount_usdc: '10.00',
107
+ payment_asset: 'mock_usdc_cep18',
108
+ payer_public_key: senderPublicKey,
109
+ });
110
+ // Submit mockUsdcOrder.payment as a CEP-18 transfer, then verify with the same method.
111
+ ```
112
+
113
+ `mock_usdc_cep18` is a Casper testnet mock token rail for demos, not official USDC.
114
+
115
+ ## MCP server — for Claude Desktop, Cursor, and other MCP clients
116
+
117
+ Add to your client's `mcpServers` config:
118
+
119
+ ```json
120
+ {
121
+ "mcpServers": {
122
+ "cards402": {
123
+ "command": "npx",
124
+ "args": ["-y", "cards402"],
125
+ "env": { "CARDS402_API_KEY": "cards402_<your key>" }
126
+ }
127
+ }
128
+ }
129
+ ```
130
+
131
+ The MCP server exposes four tools: `setup_wallet`, `check_budget`, `check_order`, and `purchase_vcc`.
132
+
133
+ ## Error handling
134
+
135
+ All SDK errors inherit from `Cards402Error`. Typed subclasses let you react to specific failure modes:
136
+
137
+ ```typescript
138
+ import {
139
+ Cards402Error,
140
+ AuthError,
141
+ SpendLimitError,
142
+ RateLimitError,
143
+ ServiceUnavailableError,
144
+ InvalidAmountError,
145
+ OrderFailedError,
146
+ WaitTimeoutError,
147
+ } from 'cards402';
148
+
149
+ try {
150
+ const card = await purchaseCardOWS({ ... });
151
+ } catch (err) {
152
+ if (err instanceof SpendLimitError) { /* cap reached — ask owner to raise */ }
153
+ else if (err instanceof OrderFailedError) { /* check err.refund for refund tx */ }
154
+ else if (err instanceof WaitTimeoutError) { /* network flake or stalled fulfillment */ }
155
+ else if (err instanceof AuthError) { /* bad key */ }
156
+ }
157
+ ```
158
+
159
+ ## Keeping card details safe
160
+
161
+ `purchaseCardOWS` returns the card PAN, CVV, and expiry as plain strings. **Treat them as secrets.** Don't log them, don't write them to disk, don't send them to observability pipelines unless those pipelines are explicitly PCI-compliant.
162
+
163
+ ## Links
164
+
165
+ - [cards402.com](https://cards402.com) — dashboard and docs
166
+ - [cards402.com/docs](https://cards402.com/docs) — full API reference
167
+ - [cards402.com/skill.md](https://cards402.com/skill.md) — drop-in agent onboarding brief
168
+ - [cards402.com/llms.txt](https://cards402.com/llms.txt) — LLM-index of every docs surface
169
+ - [github.com/CTX-com/Cards402](https://github.com/CTX-com/Cards402) — source
170
+
171
+ ## License
172
+
173
+ MIT — see [LICENSE](./LICENSE).
package/dist/cli.d.ts ADDED
@@ -0,0 +1,3 @@
1
+ #!/usr/bin/env node
2
+ export {};
3
+ //# sourceMappingURL=cli.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}
package/dist/cli.js ADDED
@@ -0,0 +1,108 @@
1
+ #!/usr/bin/env node
2
+ "use strict";
3
+ // cspr402 CLI dispatcher.
4
+ var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
5
+ if (k2 === undefined) k2 = k;
6
+ var desc = Object.getOwnPropertyDescriptor(m, k);
7
+ if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
8
+ desc = { enumerable: true, get: function() { return m[k]; } };
9
+ }
10
+ Object.defineProperty(o, k2, desc);
11
+ }) : (function(o, m, k, k2) {
12
+ if (k2 === undefined) k2 = k;
13
+ o[k2] = m[k];
14
+ }));
15
+ var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
16
+ Object.defineProperty(o, "default", { enumerable: true, value: v });
17
+ }) : function(o, v) {
18
+ o["default"] = v;
19
+ });
20
+ var __importStar = (this && this.__importStar) || (function () {
21
+ var ownKeys = function(o) {
22
+ ownKeys = Object.getOwnPropertyNames || function (o) {
23
+ var ar = [];
24
+ for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
25
+ return ar;
26
+ };
27
+ return ownKeys(o);
28
+ };
29
+ return function (mod) {
30
+ if (mod && mod.__esModule) return mod;
31
+ var result = {};
32
+ if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
33
+ __setModuleDefault(result, mod);
34
+ return result;
35
+ };
36
+ })();
37
+ Object.defineProperty(exports, "__esModule", { value: true });
38
+ async function main() {
39
+ const [, , cmd = 'mcp', ...rest] = process.argv;
40
+ if (cmd !== 'version' &&
41
+ cmd !== '--version' &&
42
+ cmd !== '-v' &&
43
+ cmd !== '-h' &&
44
+ cmd !== '--help' &&
45
+ cmd !== 'help') {
46
+ try {
47
+ const { checkForUpdates } = await Promise.resolve().then(() => __importStar(require('./version-check')));
48
+ checkForUpdates();
49
+ }
50
+ catch {
51
+ /* non-fatal */
52
+ }
53
+ }
54
+ if (cmd === '-h' || cmd === '--help' || cmd === 'help') {
55
+ process.stdout.write(`cspr402 - Casper testnet payment verification for AI agents
56
+
57
+ Usage:
58
+ cspr402 onboard --claim <code> Set up an agent from a dashboard claim code
59
+ cspr402 purchase --amount <USD> Create a native CSPR order
60
+ cspr402 wallet address Print this agent's Casper public key
61
+ cspr402 wallet balance Print this agent's testnet CSPR balance
62
+ cspr402 mcp Start the MCP server over stdio (default)
63
+ cspr402 version Print the SDK version
64
+ cspr402 --help Show this message
65
+
66
+ Commands read ~/.cspr402/config.json (written by 'cspr402 onboard') so you
67
+ don't need to pass an api key.
68
+
69
+ Docs: https://cspr402.xyz/docs
70
+ Onboarding guide for agents: https://cspr402.xyz/skill.md
71
+ `);
72
+ return 0;
73
+ }
74
+ if (cmd === 'version' || cmd === '--version' || cmd === '-v') {
75
+ // eslint-disable-next-line @typescript-eslint/no-require-imports
76
+ const pkg = require('../package.json');
77
+ process.stdout.write(`${pkg.version}\n`);
78
+ return 0;
79
+ }
80
+ if (cmd === 'onboard') {
81
+ const { onboardCommand } = await Promise.resolve().then(() => __importStar(require('./commands/onboard')));
82
+ return onboardCommand(rest);
83
+ }
84
+ if (cmd === 'purchase' || cmd === 'buy') {
85
+ const { purchaseCommand } = await Promise.resolve().then(() => __importStar(require('./commands/purchase')));
86
+ return purchaseCommand(rest);
87
+ }
88
+ if (cmd === 'wallet') {
89
+ const { walletCommand } = await Promise.resolve().then(() => __importStar(require('./commands/wallet')));
90
+ return walletCommand(rest);
91
+ }
92
+ if (cmd === 'mcp') {
93
+ const { startMcpServer } = await Promise.resolve().then(() => __importStar(require('./mcp')));
94
+ await startMcpServer();
95
+ return 0;
96
+ }
97
+ process.stderr.write(`error: unknown command '${cmd}'\n`);
98
+ process.stderr.write(`Run 'cspr402 --help' to see available commands.\n`);
99
+ return 2;
100
+ }
101
+ main().then((code) => {
102
+ if (code !== 0)
103
+ process.exit(code);
104
+ }, (err) => {
105
+ process.stderr.write(`fatal: ${err instanceof Error ? err.stack || err.message : String(err)}\n`);
106
+ process.exit(1);
107
+ });
108
+ //# sourceMappingURL=cli.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";;AACA,0BAA0B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAE1B,KAAK,UAAU,IAAI;IACjB,MAAM,CAAC,EAAE,AAAD,EAAG,GAAG,GAAG,KAAK,EAAE,GAAG,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAEhD,IACE,GAAG,KAAK,SAAS;QACjB,GAAG,KAAK,WAAW;QACnB,GAAG,KAAK,IAAI;QACZ,GAAG,KAAK,IAAI;QACZ,GAAG,KAAK,QAAQ;QAChB,GAAG,KAAK,MAAM,EACd,CAAC;QACD,IAAI,CAAC;YACH,MAAM,EAAE,eAAe,EAAE,GAAG,wDAAa,iBAAiB,GAAC,CAAC;YAC5D,eAAe,EAAE,CAAC;QACpB,CAAC;QAAC,MAAM,CAAC;YACP,eAAe;QACjB,CAAC;IACH,CAAC;IAED,IAAI,GAAG,KAAK,IAAI,IAAI,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,MAAM,EAAE,CAAC;QACvD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC;;;;;;;;;;;;;;;;CAgBxB,CAAC,CAAC;QACC,OAAO,CAAC,CAAC;IACX,CAAC;IAED,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,KAAK,WAAW,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;QAC7D,iEAAiE;QACjE,MAAM,GAAG,GAAG,OAAO,CAAC,iBAAiB,CAAwB,CAAC;QAC9D,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC,OAAO,IAAI,CAAC,CAAC;QACzC,OAAO,CAAC,CAAC;IACX,CAAC;IAED,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;QACtB,MAAM,EAAE,cAAc,EAAE,GAAG,wDAAa,oBAAoB,GAAC,CAAC;QAC9D,OAAO,cAAc,CAAC,IAAI,CAAC,CAAC;IAC9B,CAAC;IAED,IAAI,GAAG,KAAK,UAAU,IAAI,GAAG,KAAK,KAAK,EAAE,CAAC;QACxC,MAAM,EAAE,eAAe,EAAE,GAAG,wDAAa,qBAAqB,GAAC,CAAC;QAChE,OAAO,eAAe,CAAC,IAAI,CAAC,CAAC;IAC/B,CAAC;IAED,IAAI,GAAG,KAAK,QAAQ,EAAE,CAAC;QACrB,MAAM,EAAE,aAAa,EAAE,GAAG,wDAAa,mBAAmB,GAAC,CAAC;QAC5D,OAAO,aAAa,CAAC,IAAI,CAAC,CAAC;IAC7B,CAAC;IAED,IAAI,GAAG,KAAK,KAAK,EAAE,CAAC;QAClB,MAAM,EAAE,cAAc,EAAE,GAAG,wDAAa,OAAO,GAAC,CAAC;QACjD,MAAM,cAAc,EAAE,CAAC;QACvB,OAAO,CAAC,CAAC;IACX,CAAC;IAED,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,2BAA2B,GAAG,KAAK,CAAC,CAAC;IAC1D,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,mDAAmD,CAAC,CAAC;IAC1E,OAAO,CAAC,CAAC;AACX,CAAC;AAED,IAAI,EAAE,CAAC,IAAI,CACT,CAAC,IAAI,EAAE,EAAE;IACP,IAAI,IAAI,KAAK,CAAC;QAAE,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACrC,CAAC,EACD,CAAC,GAAG,EAAE,EAAE;IACN,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,UAAU,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAC5E,CAAC;IACF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CACF,CAAC"}
@@ -0,0 +1,207 @@
1
+ export { Cards402Error, SpendLimitError, RateLimitError, ServiceUnavailableError, PriceUnavailableError, InvalidAmountError, AuthError, OrderFailedError, WaitTimeoutError, ResumableError, } from './errors';
2
+ export interface Budget {
3
+ spent_usdc: string;
4
+ /** In-flight orders (pending_payment, ordering, etc.) not yet settled. */
5
+ in_flight_usdc: string;
6
+ /** spent_usdc + in_flight_usdc — the committed total against the limit. */
7
+ committed_usdc: string;
8
+ limit_usdc: string | null;
9
+ remaining_usdc: string | null;
10
+ }
11
+ export interface UsageSummary {
12
+ api_key_id: string;
13
+ label: string | null;
14
+ budget: Budget;
15
+ orders: {
16
+ total: number;
17
+ delivered: number;
18
+ failed: number;
19
+ refunded: number;
20
+ in_progress: number;
21
+ };
22
+ }
23
+ export interface OrderOptions {
24
+ amount_usdc: string;
25
+ payment_asset?: 'cspr_casper' | 'mock_usdc_cep18';
26
+ payer_public_key?: string;
27
+ webhook_url?: string;
28
+ metadata?: Record<string, unknown>;
29
+ }
30
+ export interface SorobanPaymentInstructions {
31
+ type: 'soroban_contract';
32
+ contract_id: string;
33
+ order_id: string;
34
+ usdc: {
35
+ amount: string;
36
+ asset: string;
37
+ };
38
+ xlm?: {
39
+ amount: string;
40
+ };
41
+ }
42
+ export interface CasperCSPRPaymentInstructions {
43
+ type: 'casper_cspr_transfer';
44
+ network: 'testnet';
45
+ chain_name: 'casper-test';
46
+ recipient: string;
47
+ sender_public_key?: string | null;
48
+ order_id: string;
49
+ amount_usdc: string;
50
+ amount_cspr: string;
51
+ amount_motes: string;
52
+ transfer_id: number;
53
+ expires_at: string;
54
+ }
55
+ export interface MockUsdcCep18PaymentInstructions {
56
+ type: 'casper_cep18_transfer';
57
+ asset: 'mockUSDC';
58
+ decimals: 6;
59
+ network: 'testnet';
60
+ chain_name: 'casper-test';
61
+ contract_package_hash: string;
62
+ contract_hash: string | null;
63
+ sender_public_key: string;
64
+ recipient_public_key: string;
65
+ order_id: string;
66
+ amount: string;
67
+ amount_base_units: string;
68
+ expires_at: string;
69
+ verify_url: string | null;
70
+ }
71
+ export type PaymentInstructions = SorobanPaymentInstructions | CasperCSPRPaymentInstructions | MockUsdcCep18PaymentInstructions;
72
+ export interface OrderResponse {
73
+ order_id: string;
74
+ status: string;
75
+ payment: PaymentInstructions;
76
+ poll_url: string;
77
+ budget: Budget;
78
+ }
79
+ export interface CardDetails {
80
+ number: string;
81
+ cvv: string;
82
+ expiry: string;
83
+ brand: string | null;
84
+ }
85
+ export type OrderPhase = 'awaiting_approval' | 'awaiting_payment' | 'processing' | 'ready' | 'failed' | 'refunded' | 'rejected' | 'expired';
86
+ export interface OrderListItem {
87
+ id: string;
88
+ status: string;
89
+ amount_usdc: string;
90
+ payment_asset: string;
91
+ created_at: string;
92
+ updated_at: string;
93
+ }
94
+ export interface OrderStatus {
95
+ order_id: string;
96
+ status: string;
97
+ phase: OrderPhase;
98
+ amount_usdc: string;
99
+ payment_asset: string;
100
+ card?: CardDetails;
101
+ error?: string;
102
+ note?: string;
103
+ refund?: {
104
+ stellar_txid: string;
105
+ };
106
+ /**
107
+ * Present when status === 'pending_payment'. Carries the Soroban
108
+ * contract invocation the agent needs to submit. The backend
109
+ * stores this verbatim in orders.vcc_payment_json and re-emits it
110
+ * on GET /orders/:id so a resumed purchaseCardOWS can rebuild a
111
+ * fresh payment tx without having to recompute the payment
112
+ * instructions from scratch. Used by the F1-resume fix for dropped
113
+ * Soroban txs.
114
+ */
115
+ payment?: PaymentInstructions;
116
+ receipt?: CasperPaymentReceipt;
117
+ created_at: string;
118
+ updated_at: string;
119
+ }
120
+ export interface CasperCSPRPaymentReceipt {
121
+ type: 'casper_cspr_receipt';
122
+ order_id: string;
123
+ payment_asset: 'cspr_casper';
124
+ network: string;
125
+ chain_name: string;
126
+ deploy_hash: string;
127
+ sender_public_key: string | null;
128
+ recipient: string | null;
129
+ transfer_id: number;
130
+ amount_motes: string | null;
131
+ verified_at: string | null;
132
+ card_mode: 'mock';
133
+ }
134
+ export interface MockUsdcReceipt {
135
+ type: 'casper_mock_usdc_receipt';
136
+ order_id: string;
137
+ payment_asset: 'mock_usdc_cep18';
138
+ network: string;
139
+ chain_name: string;
140
+ deploy_hash: string;
141
+ sender_public_key: string | null;
142
+ asset: 'mockUSDC';
143
+ decimals: number;
144
+ contract_package_hash: string | null;
145
+ contract_hash: string | null;
146
+ recipient_public_key: string | null;
147
+ recipient_account_hash: string | null;
148
+ amount_base_units: string | null;
149
+ verified_at: string | null;
150
+ card_mode: 'mock';
151
+ }
152
+ export type CasperPaymentReceipt = CasperCSPRPaymentReceipt | MockUsdcReceipt;
153
+ export interface VerifyCasperPaymentResponse {
154
+ ok: true;
155
+ note?: string;
156
+ receipt: CasperPaymentReceipt;
157
+ order: OrderStatus;
158
+ }
159
+ export interface RetryOptions {
160
+ /** Max number of retry attempts on transient failures. 0 disables retries. */
161
+ attempts?: number;
162
+ /** Initial backoff in ms. Doubles on each retry. */
163
+ baseDelayMs?: number;
164
+ /** Max backoff cap in ms. */
165
+ maxDelayMs?: number;
166
+ }
167
+ export declare class Cards402Client {
168
+ private baseUrl;
169
+ private apiKey;
170
+ private retry;
171
+ constructor({ baseUrl, apiKey, retry, }?: {
172
+ baseUrl?: string;
173
+ apiKey?: string;
174
+ retry?: RetryOptions;
175
+ });
176
+ private handleError;
177
+ private shouldRetry;
178
+ private fetchWithRetry;
179
+ createOrder(opts: OrderOptions & {
180
+ idempotencyKey?: string;
181
+ }): Promise<OrderResponse>;
182
+ getOrder(orderId: string): Promise<OrderStatus>;
183
+ verifyCasperPayment(orderId: string, deployHash: string, opts?: {
184
+ senderPublicKey?: string;
185
+ }): Promise<VerifyCasperPaymentResponse>;
186
+ waitForCard(orderId: string, { timeoutMs, intervalMs }?: {
187
+ timeoutMs?: number;
188
+ intervalMs?: number;
189
+ }): Promise<CardDetails>;
190
+ private waitForCardStream;
191
+ private waitForCardPoll;
192
+ listOrders({ status, limit, offset, since_created_at, since_updated_at, }?: {
193
+ status?: string;
194
+ limit?: number;
195
+ offset?: number;
196
+ since_created_at?: string;
197
+ since_updated_at?: string;
198
+ }): Promise<OrderListItem[]>;
199
+ getUsage(): Promise<UsageSummary>;
200
+ reportStatus(state: 'initializing' | 'awaiting_funding', opts?: {
201
+ wallet_public_key?: string;
202
+ detail?: string;
203
+ }): Promise<void>;
204
+ }
205
+ export declare class CSPR402Client extends Cards402Client {
206
+ }
207
+ //# sourceMappingURL=client.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,aAAa,EACb,eAAe,EACf,cAAc,EACd,uBAAuB,EACvB,qBAAqB,EACrB,kBAAkB,EAClB,SAAS,EACT,gBAAgB,EAChB,gBAAgB,EAChB,cAAc,GACf,MAAM,UAAU,CAAC;AASlB,MAAM,WAAW,MAAM;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,0EAA0E;IAC1E,cAAc,EAAE,MAAM,CAAC;IACvB,2EAA2E;IAC3E,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AAED,MAAM,WAAW,YAAY;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE;QACN,KAAK,EAAE,MAAM,CAAC;QACd,SAAS,EAAE,MAAM,CAAC;QAClB,MAAM,EAAE,MAAM,CAAC;QACf,QAAQ,EAAE,MAAM,CAAC;QACjB,WAAW,EAAE,MAAM,CAAC;KACrB,CAAC;CACH;AAED,MAAM,WAAW,YAAY;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,aAAa,GAAG,iBAAiB,CAAC;IAClD,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,MAAM,WAAW,0BAA0B;IAEzC,IAAI,EAAE,kBAAkB,CAAC;IAEzB,WAAW,EAAE,MAAM,CAAC;IAEpB,QAAQ,EAAE,MAAM,CAAC;IAEjB,IAAI,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAExC,GAAG,CAAC,EAAE;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CAC1B;AAED,MAAM,WAAW,6BAA6B;IAC5C,IAAI,EAAE,sBAAsB,CAAC;IAC7B,OAAO,EAAE,SAAS,CAAC;IACnB,UAAU,EAAE,aAAa,CAAC;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,gCAAgC;IAC/C,IAAI,EAAE,uBAAuB,CAAC;IAC9B,KAAK,EAAE,UAAU,CAAC;IAClB,QAAQ,EAAE,CAAC,CAAC;IACZ,OAAO,EAAE,SAAS,CAAC;IACnB,UAAU,EAAE,aAAa,CAAC;IAC1B,qBAAqB,EAAE,MAAM,CAAC;IAC9B,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,oBAAoB,EAAE,MAAM,CAAC;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,iBAAiB,EAAE,MAAM,CAAC;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED,MAAM,MAAM,mBAAmB,GAC3B,0BAA0B,GAC1B,6BAA6B,GAC7B,gCAAgC,CAAC;AAErC,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,mBAAmB,CAAC;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAED,MAAM,MAAM,UAAU,GAClB,mBAAmB,GACnB,kBAAkB,GAClB,YAAY,GACZ,OAAO,GACP,QAAQ,GACR,UAAU,GACV,UAAU,GACV,SAAS,CAAC;AAId,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,UAAU,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE;QAAE,YAAY,EAAE,MAAM,CAAA;KAAE,CAAC;IAClC;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,mBAAmB,CAAC;IAC9B,OAAO,CAAC,EAAE,oBAAoB,CAAC;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,qBAAqB,CAAC;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,aAAa,CAAC;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,0BAA0B,CAAC;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,iBAAiB,CAAC;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,KAAK,EAAE,UAAU,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,qBAAqB,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,oBAAoB,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,sBAAsB,EAAE,MAAM,GAAG,IAAI,CAAC;IACtC,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,MAAM,oBAAoB,GAAG,wBAAwB,GAAG,eAAe,CAAC;AAE9E,MAAM,WAAW,2BAA2B;IAC1C,EAAE,EAAE,IAAI,CAAC;IACT,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,oBAAoB,CAAC;IAC9B,KAAK,EAAE,WAAW,CAAC;CACpB;AAED,MAAM,WAAW,YAAY;IAC3B,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,oDAAoD;IACpD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6BAA6B;IAC7B,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAiBD,qBAAa,cAAc;IACzB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,KAAK,CAAyB;gBAE1B,EACV,OAAO,EACP,MAAM,EACN,KAAU,GACX,GAAE;QACD,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,KAAK,CAAC,EAAE,YAAY,CAAC;KACjB;YAsEQ,WAAW;IASzB,OAAO,CAAC,WAAW;YAIL,cAAc;IA0BtB,WAAW,CAAC,IAAI,EAAE,YAAY,GAAG;QAAE,cAAc,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,aAAa,CAAC;IAkBrF,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IAY/C,mBAAmB,CACvB,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,IAAI,GAAE;QAAE,eAAe,CAAC,EAAE,MAAM,CAAA;KAAO,GACtC,OAAO,CAAC,2BAA2B,CAAC;IA2BjC,WAAW,CACf,OAAO,EAAE,MAAM,EACf,EAAE,SAAkB,EAAE,UAAiB,EAAE,GAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAO,GAC1F,OAAO,CAAC,WAAW,CAAC;YAkCT,iBAAiB;YAiGjB,eAAe;IA+BvB,UAAU,CAAC,EACf,MAAM,EACN,KAAU,EACV,MAAM,EACN,gBAAgB,EAChB,gBAAgB,GACjB,GAAE;QACD,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,gBAAgB,CAAC,EAAE,MAAM,CAAC;QAC1B,gBAAgB,CAAC,EAAE,MAAM,CAAC;KACtB,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC;IAgB3B,QAAQ,IAAI,OAAO,CAAC,YAAY,CAAC;IAwBjC,YAAY,CAChB,KAAK,EAAE,cAAc,GAAG,kBAAkB,EAC1C,IAAI,GAAE;QAAE,iBAAiB,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAO,GACzD,OAAO,CAAC,IAAI,CAAC;CAkBjB;AAED,qBAAa,aAAc,SAAQ,cAAc;CAAG"}