@attesso/sdk 1.3.0 → 1.3.2

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 (2) hide show
  1. package/README.md +42 -69
  2. package/package.json +10 -10
package/README.md CHANGED
@@ -1,24 +1,11 @@
1
1
  # @attesso/sdk
2
2
 
3
- Isomorphic client for the Attesso Settlement Protocol. FIDO2-signed execution bindings.
3
+ Isomorphic client for the Attesso API. Card-based payment primitives for AI agents.
4
4
 
5
5
  ```bash
6
6
  npm install @attesso/sdk
7
7
  ```
8
8
 
9
- ## Architecture
10
-
11
- Attesso exposes financial execution as a secure system primitive, similar to `fs` or `net`.
12
-
13
- Instead of managing sensitive credentials in plaintext, agents interact with **Signed Mandates**—cryptographic proofs that authorize a specific scope of execution (amount, merchant, duration), verified server-side.
14
-
15
- ### Key Properties
16
-
17
- - **Deterministic**: Same mandate, same constraints, every time
18
- - **Isolated**: Credentials never exposed to agent runtime
19
- - **Revocable**: Sub-millisecond propagation via Redis-backed block store
20
- - **Typed**: Full TypeScript coverage with Zod validation
21
-
22
9
  ## AttessoClient
23
10
 
24
11
  ```typescript
@@ -35,43 +22,55 @@ const client = new AttessoClient({
35
22
  #### getMandate(mandateId)
36
23
  ```typescript
37
24
  const mandate = await client.getMandate('mandate_xyz');
38
- // { id, botId, maxAmount, currency, merchant?, status, expiresAt?, createdAt }
25
+ // { id, botId, spendingLimit, totalCharged, currency, status, feeMode, fees, ... }
39
26
  ```
40
27
 
41
- #### executePayment(options)
28
+ #### issueCard(mandateId, options)
29
+
30
+ Issue an ephemeral virtual card from a standing mandate. The card auto-destructs after use or when the TTL expires.
31
+
42
32
  ```typescript
43
- const payment = await client.executePayment({
44
- mandateId: 'mandate_xyz',
45
- amount: 34700, // cents
46
- merchant: 'Acme Corp',
33
+ const card = await client.issueCard('mandate_xyz', {
34
+ amount: 34700, // cents
35
+ ttlSeconds: 300, // optional, 60-900
36
+ allowedMccs: ['...'],// optional
37
+ blockedMccs: ['...'],// optional
47
38
  });
48
- // { id, mandateId, amount, merchant, status, createdAt }
39
+ // { cardId, number, cvc, expMonth, expYear, expiresAt, spendingLimit, fees }
49
40
  ```
50
41
 
51
42
  #### getPayment(paymentId)
52
43
  ```typescript
53
44
  const payment = await client.getPayment('payment_abc');
45
+ // { id, mandateId, amount, merchant, status, createdAt }
54
46
  ```
55
47
 
56
- #### getPassport(mandateId)
48
+ #### createMandateRequest(input)
49
+
50
+ Create a mandate request and get an approval URL. Send this to the user so they can authorize the spending.
51
+
57
52
  ```typescript
58
- const passport = await client.getPassport('mandate_xyz');
59
- // { token, expiresAt }
53
+ const request = await client.createMandateRequest({
54
+ amount: 10000, // cents
55
+ validityWindow: '24h',
56
+ category: 'travel',
57
+ feeMode: 'markup', // optional, default 'markup'
58
+ callbackUrl: 'https://your-server.com/webhooks/attesso',
59
+ });
60
+ // { id, approvalUrl, expiresAt, status, callbackSecret }
60
61
  ```
61
62
 
62
- #### capture(paymentId, options)
63
+ #### getMandateRequest(requestId)
63
64
  ```typescript
64
- const result = await client.capture('payment_abc', {
65
- amount: 34700,
66
- metadata: { orderId: '123' },
67
- });
68
- // { id, authorizedAmount, capturedAmount, status: 'completed' }
65
+ const status = await client.getMandateRequest('req_abc123');
66
+ if (status.status === 'approved') {
67
+ console.log('Mandate created:', status.mandate.id);
68
+ }
69
69
  ```
70
70
 
71
- #### cancel(paymentId)
71
+ #### cancelMandateRequest(requestId)
72
72
  ```typescript
73
- const result = await client.cancel('payment_abc');
74
- // { id, authorizedAmount, status: 'cancelled' }
73
+ await client.cancelMandateRequest('req_abc123');
75
74
  ```
76
75
 
77
76
  ## Vercel AI SDK
@@ -83,9 +82,8 @@ import { attesso } from '@attesso/sdk/vercel';
83
82
  const result = await generateText({
84
83
  model: openai('gpt-4o'),
85
84
  tools: attesso.tools({
86
- mandateId: 'mandate_xyz', // optional: pre-select mandate
87
- merchant: 'Acme Corp', // optional: lock to merchant
88
- maxAmountPerTransaction: 50000, // optional: per-tx cap
85
+ mandateId: 'mandate_xyz', // optional: pre-select mandate
86
+ maxAmountPerTransaction: 50000, // optional: per-tx cap in cents
89
87
  }),
90
88
  prompt: 'Book a flight under $500',
91
89
  });
@@ -93,39 +91,14 @@ const result = await generateText({
93
91
 
94
92
  ### Tools
95
93
 
96
- | Tool | Parameters | Returns |
97
- |------|------------|---------|
98
- | `attesso_pay` | `{ mandateId?, amount, merchant? }` | PaymentResponse |
99
- | `attesso_get_mandate` | `{ mandateId? }` | MandateResponse |
100
- | `attesso_get_payment` | `{ paymentId }` | PaymentResponse |
101
- | `attesso_get_passport` | `{ mandateId? }` | PassportToken |
102
- | `attesso_capture` | `{ paymentId, amount, metadata? }` | CaptureResponse |
103
- | `attesso_cancel` | `{ paymentId }` | CancelResponse |
104
-
105
- > **Note**: The Vercel AI SDK uses `attesso_pay` for payments. If using the MCP server (`@attesso/mcp`) directly with Claude Desktop or other MCP clients, the equivalent tool is named `attesso_execute_payment`.
106
-
107
- ## Origin Restrictions
108
-
109
- ```typescript
110
- const client = new AttessoClient({
111
- apiKey: '...',
112
- allowedOrigins: ['https://myapp.com', 'https://*.trusted.com'],
113
- });
114
- ```
115
-
116
- Throws `OriginNotAllowedError` if called from unlisted origin.
94
+ | Tool | Parameters | Description |
95
+ |------|------------|-------------|
96
+ | `attesso_get_mandate` | `{ mandateId }` | Check spending limit, status, and restrictions |
97
+ | `attesso_issue_card` | `{ mandateId, amount, ttlSeconds? }` | Issue an ephemeral virtual card |
98
+ | `attesso_get_card` | `{ cardId }` | Check card status and details |
99
+ | `attesso_revoke_mandate` | `{ mandateId }` | Revoke a mandate |
117
100
 
118
- ## Types
119
-
120
- ```typescript
121
- import type {
122
- MandateResponse,
123
- PaymentResponse,
124
- PassportToken,
125
- CapturePaymentResponse,
126
- CancelAuthorizationResponse,
127
- } from '@attesso/sdk';
128
- ```
101
+ When a `mandateId` is provided in the config, it is omitted from tool parameters automatically.
129
102
 
130
103
  ## Errors
131
104
 
@@ -133,7 +106,7 @@ import type {
133
106
  import { AttessoError, OriginNotAllowedError } from '@attesso/sdk';
134
107
 
135
108
  try {
136
- await client.executePayment({ ... });
109
+ await client.issueCard('mandate_xyz', { amount: 50000 });
137
110
  } catch (e) {
138
111
  if (e instanceof AttessoError) {
139
112
  console.log(e.code); // MANDATE_NOT_FOUND, AMOUNT_EXCEEDS_LIMIT, etc.
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@attesso/sdk",
3
- "version": "1.3.0",
4
- "description": "TypeScript SDK for the Attesso API — create mandates, issue virtual cards, and manage payments for AI agents.",
3
+ "version": "1.3.2",
4
+ "description": "Attesso Node.js library. Financial execution primitives for autonomous systems.",
5
5
  "author": "Attesso",
6
6
  "license": "MIT",
7
7
  "repository": {
@@ -32,12 +32,6 @@
32
32
  "require": "./dist/vercel/index.js"
33
33
  }
34
34
  },
35
- "scripts": {
36
- "build": "tsc",
37
- "dev": "tsc --watch",
38
- "clean": "rm -rf dist",
39
- "test": "vitest run"
40
- },
41
35
  "keywords": [
42
36
  "attesso",
43
37
  "sdk",
@@ -48,7 +42,7 @@
48
42
  "vercel-ai-sdk"
49
43
  ],
50
44
  "dependencies": {
51
- "@attesso/types": "workspace:*"
45
+ "@attesso/types": "1.2.2"
52
46
  },
53
47
  "peerDependencies": {
54
48
  "ai": ">=3.0.0",
@@ -67,5 +61,11 @@
67
61
  "typescript": "^5.7.0",
68
62
  "vitest": "^2.1.0",
69
63
  "zod": "^3.23.0"
64
+ },
65
+ "scripts": {
66
+ "build": "tsc",
67
+ "dev": "tsc --watch",
68
+ "clean": "rm -rf dist",
69
+ "test": "vitest run"
70
70
  }
71
- }
71
+ }