@attesso/sdk 1.0.1 → 1.0.3

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 +77 -130
  2. package/package.json +6 -9
package/README.md CHANGED
@@ -1,195 +1,142 @@
1
1
  # @attesso/sdk
2
2
 
3
- Financial infrastructure for AI agents. Programmatic card issuing with hardware-bound biometric authorization.
3
+ API client for executing payments against FIDO2-signed mandates.
4
4
 
5
5
  ```bash
6
6
  npm install @attesso/sdk
7
7
  ```
8
8
 
9
- ## What is Attesso?
10
-
11
- Attesso provides scoped, ephemeral credentials for AI agents. Users authorize via FIDO2 assertion, and agents receive time-limited cards with spend constraints. Revocation is immediate. All credentials are bound to hardware attestation.
12
-
13
- **No credit cards are exposed to agents.** Agents receive mandate IDs and can only transact within user-defined limits.
14
-
15
- ## Quick Start
9
+ ## AttessoClient
16
10
 
17
11
  ```typescript
18
12
  import { AttessoClient } from '@attesso/sdk';
19
13
 
20
14
  const client = new AttessoClient({
21
15
  apiKey: process.env.ATTESSO_API_KEY,
16
+ baseUrl: process.env.ATTESSO_BASE_URL, // optional
22
17
  });
18
+ ```
23
19
 
24
- // Check spending constraints
20
+ ### Methods
21
+
22
+ #### getMandate(mandateId)
23
+ ```typescript
25
24
  const mandate = await client.getMandate('mandate_xyz');
26
- console.log(`Authorized: $${mandate.maxAmount / 100}`);
25
+ // { id, botId, maxAmount, currency, merchant?, status, expiresAt?, createdAt }
26
+ ```
27
27
 
28
- // Execute payment within constraints
28
+ #### executePayment(options)
29
+ ```typescript
29
30
  const payment = await client.executePayment({
30
31
  mandateId: 'mandate_xyz',
31
- amount: 34700, // $347.00
32
- merchant: 'United Airlines',
32
+ amount: 34700, // cents
33
+ merchant: 'Acme Corp',
33
34
  });
34
-
35
- // Get passport for merchant verification
36
- const passport = await client.getPassport('mandate_xyz');
35
+ // { id, mandateId, amount, merchant, status, createdAt }
37
36
  ```
38
37
 
39
- ## Authorization Flow
40
-
41
- ```
42
- 01. Link Delivery Agent generates authorization URL. User receives via any channel.
43
- 02. FIDO2 Assertion Browser invokes WebAuthn API. Authenticator signs in Secure Enclave.
44
- 03. Agent Execution Agent receives mandate ID. Operates within authorized constraints.
45
- 04. Capture Agent calls capture() with final amount. Excess authorization released.
46
- 05. Settlement Transaction settles via Stripe. Event dispatched to webhook.
38
+ #### getPayment(paymentId)
39
+ ```typescript
40
+ const payment = await client.getPayment('payment_abc');
47
41
  ```
48
42
 
49
- ## Vercel AI SDK Integration
50
-
51
- Inject payment capabilities into any agent runtime:
52
-
43
+ #### getPassport(mandateId)
53
44
  ```typescript
54
- import { generateText } from 'ai';
55
- import { attesso } from '@attesso/sdk/vercel';
56
-
57
- const result = await generateText({
58
- model: openai('gpt-4o'),
59
- tools: attesso.tools(),
60
- prompt: 'Book cheapest flight to NYC',
61
- });
45
+ const passport = await client.getPassport('mandate_xyz');
46
+ // { token, expiresAt }
62
47
  ```
63
48
 
64
- ### Available Tools
65
-
66
- | Tool | Description |
67
- |------|-------------|
68
- | `attesso_pay` | Execute payment against mandate |
69
- | `attesso_get_mandate` | Check spending constraints |
70
- | `attesso_get_passport` | Get identity token for merchant verification |
71
- | `attesso_capture` | Capture authorized payment |
72
- | `attesso_cancel` | Cancel and release held funds |
73
- | `attesso_check_balance` | Quick balance check |
74
-
75
- ### Configuration
76
-
49
+ #### capture(paymentId, options)
77
50
  ```typescript
78
- const tools = attesso.tools({
79
- mandateId: 'mandate_xyz', // Pre-select mandate
80
- merchant: 'United Airlines', // Lock to merchant
81
- maxAmountPerTransaction: 50000, // Per-transaction cap
51
+ const result = await client.capture('payment_abc', {
52
+ amount: 34700,
53
+ metadata: { orderId: '123' },
82
54
  });
55
+ // { id, authorizedAmount, capturedAmount, status: 'completed' }
83
56
  ```
84
57
 
85
- ## Direct API Access
86
-
58
+ #### cancel(paymentId)
87
59
  ```typescript
88
- import { AttessoClient } from '@attesso/sdk';
89
-
90
- const client = new AttessoClient({ apiKey: '...' });
60
+ const result = await client.cancel('payment_abc');
61
+ // { id, authorizedAmount, status: 'cancelled' }
62
+ ```
91
63
 
92
- // Get mandate details
93
- const mandate = await client.getMandate(mandateId);
64
+ ## Vercel AI SDK
94
65
 
95
- // Execute payment
96
- const payment = await client.executePayment({
97
- mandateId,
98
- amount: 10000,
99
- merchant: 'Acme Corp',
100
- });
101
-
102
- // Check payment status
103
- const status = await client.getPayment(payment.id);
66
+ ```typescript
67
+ import { generateText } from 'ai';
68
+ import { attesso } from '@attesso/sdk/vercel';
104
69
 
105
- // Auth/Capture flow
106
- const auth = await client.executePayment({
107
- mandateId,
108
- amount: 50000,
109
- merchant: 'Hotel',
70
+ const result = await generateText({
71
+ model: openai('gpt-4o'),
72
+ tools: attesso.tools({
73
+ mandateId: 'mandate_xyz', // optional: pre-select mandate
74
+ merchant: 'Acme Corp', // optional: lock to merchant
75
+ maxAmountPerTransaction: 50000, // optional: per-tx cap
76
+ }),
77
+ prompt: 'Book a flight under $500',
110
78
  });
111
- await client.capture(auth.id, { amount: 45000 }); // Final price
112
-
113
- // Cancel authorization
114
- await client.cancel(auth.id);
115
-
116
- // Get passport token
117
- const passport = await client.getPassport(mandateId);
118
79
  ```
119
80
 
120
- ## Security Model
121
-
122
- - **FIDO2/WebAuthn**: Mandates signed by device Secure Enclave/TPM
123
- - **Zero Card Exposure**: Agents receive mandate IDs, never card numbers
124
- - **Hardware Attestation**: Non-exportable keys, origin-bound credentials
125
- - **Spend Constraints**: Amount limits, merchant restrictions, TTL
126
- - **Instant Revocation**: Immediate credential invalidation via API
127
-
128
- ### Hardware Security
129
-
130
- | Device | Security | Auth Method |
131
- |--------|----------|-------------|
132
- | iPhone/iPad | Secure Enclave | FaceID/TouchID |
133
- | Mac (Touch ID) | Secure Enclave | TouchID |
134
- | Mac (no Touch ID) | Phone via QR | Phone's Secure Enclave |
135
- | Windows (Hello) | TPM 2.0 | Windows Hello |
136
- | Android | TEE/StrongBox | Fingerprint/Face |
137
-
138
- ## Application Fee Routing
139
-
140
- Configure fees per transaction. Additive settlement model ensures merchant principal preservation:
81
+ ### Tools
141
82
 
142
- ```typescript
143
- const payment = await rails.processPayment({
144
- amount: 10000, // $100.00 principal
145
- currency: 'usd',
146
- merchant: 'Acme Corp',
147
- mandateId: 'mandate_xyz',
148
- paymentId: 'payment_abc',
149
- userId: 'user_123',
150
- applicationFee: {
151
- destinationAccountId: 'acct_your_stripe_connect_id',
152
- feePercent: 5,
153
- },
154
- });
155
- ```
83
+ | Tool | Parameters | Returns |
84
+ |------|------------|---------|
85
+ | `attesso_pay` | `{ mandateId?, amount, merchant? }` | PaymentResponse |
86
+ | `attesso_get_mandate` | `{ mandateId? }` | MandateResponse |
87
+ | `attesso_get_payment` | `{ paymentId }` | PaymentResponse |
88
+ | `attesso_get_passport` | `{ mandateId? }` | PassportToken |
89
+ | `attesso_capture` | `{ paymentId, amount, metadata? }` | CaptureResponse |
90
+ | `attesso_cancel` | `{ paymentId }` | CancelResponse |
91
+ | `attesso_check_balance` | `{ mandateId? }` | `{ available, currency, status }` |
156
92
 
157
93
  ## Origin Restrictions
158
94
 
159
- Restrict SDK usage to specific domains:
160
-
161
95
  ```typescript
162
96
  const client = new AttessoClient({
163
- apiKey: 'sk_bot_xyz',
164
- allowedOrigins: [
165
- 'https://myapp.com',
166
- 'https://*.trusted-partner.com',
167
- ],
97
+ apiKey: '...',
98
+ allowedOrigins: ['https://myapp.com', 'https://*.trusted.com'],
168
99
  });
169
100
  ```
170
101
 
171
- ## Environment Variables
102
+ Throws `OriginNotAllowedError` if called from unlisted origin.
172
103
 
173
- ```bash
174
- ATTESSO_API_KEY=your_api_key
175
- ATTESSO_BASE_URL=https://api.attesso.com # optional
176
- ```
177
-
178
- ## TypeScript
104
+ ## Types
179
105
 
180
106
  ```typescript
181
107
  import type {
182
108
  MandateResponse,
183
109
  PaymentResponse,
184
110
  PassportToken,
111
+ CapturePaymentResponse,
112
+ CancelAuthorizationResponse,
185
113
  } from '@attesso/sdk';
186
114
  ```
187
115
 
116
+ ## Errors
117
+
118
+ ```typescript
119
+ import { AttessoError, OriginNotAllowedError } from '@attesso/sdk';
120
+
121
+ try {
122
+ await client.executePayment({ ... });
123
+ } catch (e) {
124
+ if (e instanceof AttessoError) {
125
+ console.log(e.code); // MANDATE_NOT_FOUND, AMOUNT_EXCEEDS_LIMIT, etc.
126
+ }
127
+ }
128
+ ```
129
+
188
130
  ## Requirements
189
131
 
190
132
  - Node.js 18+
191
133
  - For Vercel AI SDK: `ai` >= 3.0, `zod` >= 3.0
192
134
 
135
+ ## Links
136
+
137
+ - Website: https://attesso.com
138
+ - Support: info@attesso.com
139
+
193
140
  ## License
194
141
 
195
142
  MIT
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@attesso/sdk",
3
- "version": "1.0.1",
4
- "description": "Financial infrastructure for AI agents. Scoped, ephemeral card credentials with FIDO2 authorization and hardware-bound spend constraints.",
3
+ "version": "1.0.3",
4
+ "description": "API client for executing payments against FIDO2-signed mandates. Includes Vercel AI SDK tools.",
5
5
  "author": "Attesso",
6
6
  "license": "MIT",
7
7
  "repository": {
@@ -40,17 +40,14 @@
40
40
  },
41
41
  "keywords": [
42
42
  "attesso",
43
- "ai-agents",
43
+ "payments",
44
+ "mandates",
44
45
  "fido2",
45
- "webauthn",
46
- "card-issuing",
47
- "ephemeral-credentials",
48
- "financial-infrastructure",
49
46
  "vercel-ai-sdk"
50
47
  ],
51
48
  "dependencies": {
52
- "@attesso/gatekeeper": "workspace:*",
53
- "@attesso/types": "workspace:*"
49
+ "@attesso/gatekeeper": "^1.0.2",
50
+ "@attesso/types": "^1.0.2"
54
51
  },
55
52
  "peerDependencies": {
56
53
  "ai": ">=3.0.0",