@attesso/sdk 1.0.0 → 1.0.2

package/README.md

@@ -1,305 +1,136 @@
 # @attesso/sdk
 
-The official TypeScript SDK for Attesso. Hardware-backed identity for autonomous commerce.
+API client for executing payments against FIDO2-signed mandates.
 
 ```bash
 npm install @attesso/sdk
 ```
 
-## What This Is
-
-AI agents need to spend money. Attesso gives them a wallet with hardware-backed security and user-controlled spending limits.
-
-This SDK lets agents:
-- Execute payments within pre-authorized limits
-- Prove their identity to merchants
-- Check available spending power
-
-**No mobile app required.** Users authorize spending with WebAuthn passkeys (FaceID/TouchID) directly in the browser.
-
-## Quick Start
+## AttessoClient
 
 ```typescript
 import { AttessoClient } from '@attesso/sdk';
 
 const client = new AttessoClient({
   apiKey: process.env.ATTESSO_API_KEY,
+  baseUrl: process.env.ATTESSO_BASE_URL, // optional
 });
+```
+
+### Methods
 
-// Check mandate limits
+#### getMandate(mandateId)
+```typescript
 const mandate = await client.getMandate('mandate_xyz');
-console.log(`Available: $${mandate.maxAmount / 100}`);
+// { id, botId, maxAmount, currency, merchant?, status, expiresAt?, createdAt }
+```
 
-// Execute payment
+#### executePayment(options)
+```typescript
 const payment = await client.executePayment({
   mandateId: 'mandate_xyz',
-  amount: 34700, // $347.00
-  merchant: 'United Airlines',
+  amount: 34700, // cents
+  merchant: 'Acme Corp',
 });
-
-// Get identity token for merchant verification
-const passport = await client.getPassport('mandate_xyz');
+// { id, mandateId, amount, merchant, status, createdAt }
 ```
 
-## How Users Create Mandates
-
-Users create spending mandates in your web dashboard using WebAuthn passkeys:
-
+#### getPayment(paymentId)
 ```typescript
-// Frontend: User creates mandate with passkey
-import { startAuthentication } from '@simplewebauthn/browser';
-
-// 1. Get authentication options from your backend
-const authOptions = await fetch('/api/auth/webauthn/authenticate/options', {
-  method: 'POST',
-}).then(r => r.json());
-
-// 2. User authenticates with FaceID/TouchID (or QR code on desktop)
-const assertion = await startAuthentication(authOptions);
-
-// 3. Create mandate with the assertion
-const mandate = await fetch('/api/mandates', {
-  method: 'POST',
-  headers: { 'Content-Type': 'application/json' },
-  body: JSON.stringify({
-    botId: 'bot_travel_agent',
-    maxAmount: 50000, // $500.00
-    currency: 'usd',
-    merchant: 'United Airlines',
-    webAuthnAssertion: assertion,
-  }),
-}).then(r => r.json());
-
-// 4. Pass mandateId to your AI agent
+const payment = await client.getPayment('payment_abc');
 ```
 
-### Cross-Device Authentication
-
-On desktops without biometrics (TouchID), WebAuthn automatically shows a QR code. Users scan it with their phone and authenticate using the phone's FaceID/TouchID. The signature still comes from hardware (phone's Secure Enclave).
-
-## Vercel AI SDK Integration
-
-One line gives your AI agent a wallet:
-
+#### getPassport(mandateId)
 ```typescript
-import { generateText } from 'ai';
-import { attesso } from '@attesso/sdk/vercel';
-
-const result = await generateText({
-  model: openai('gpt-4o'),
-  tools: attesso.tools(),
-  prompt: 'Book me a flight to NYC under $500',
-});
+const passport = await client.getPassport('mandate_xyz');
+// { token, expiresAt }
 ```
 
-### Available Tools
-
-| Tool | Description |
-|------|-------------|
-| `attesso_pay` | Execute payment against mandate |
-| `attesso_get_mandate` | Check spending limits |
-| `attesso_get_passport` | Get identity token |
-| `attesso_capture` | Capture authorized payment |
-| `attesso_cancel` | Cancel and release funds |
-| `attesso_check_balance` | Quick balance check |
-
-### Configuration
-
+#### capture(paymentId, options)
 ```typescript
-const tools = attesso.tools({
-  mandateId: 'mandate_xyz',           // Pre-select mandate
-  merchant: 'United Airlines',        // Lock to merchant
-  maxAmountPerTransaction: 50000,     // $500 cap
+const result = await client.capture('payment_abc', {
+  amount: 34700,
+  metadata: { orderId: '123' },
 });
+// { id, authorizedAmount, capturedAmount, status: 'completed' }
 ```
 
-## Direct API Access
-
+#### cancel(paymentId)
 ```typescript
-import { AttessoClient } from '@attesso/sdk';
-
-const client = new AttessoClient({ apiKey: '...' });
-
-// Get mandate details
-const mandate = await client.getMandate(mandateId);
-
-// Execute payment
-const payment = await client.executePayment({
-  mandateId,
-  amount: 10000,
-  merchant: 'Acme Corp',
-});
-
-// Check payment status
-const status = await client.getPayment(payment.id);
-
-// Auth/Capture flow
-const auth = await client.executePayment({
-  mandateId,
-  amount: 50000,
-  merchant: 'Hotel',
-});
-await client.capture(auth.id, { amount: 45000 }); // Final price
-
-// Cancel authorization
-await client.cancel(auth.id);
-
-// Get passport token
-const passport = await client.getPassport(mandateId);
-```
-
-## How It Works
-
-```
-User creates mandate → WebAuthn passkey signs authorization
-        ↓                    (FaceID/TouchID or phone QR)
-Mandate stored → Hardware attestation verified
-        ↓
-AI Agent calls SDK → SDK checks mandate limits
-        ↓
-Payment executed → Funds transferred via Stripe
-        ↓
-Merchant verifies → Passport proves authorized spending
+const result = await client.cancel('payment_abc');
+// { id, authorizedAmount, status: 'cancelled' }
 ```
 
-### Security Model
-
-- **WebAuthn Passkeys**: Mandates signed by device Secure Enclave
-- **Cross-Device Support**: QR-based authentication for desktops
-- **User Control**: Instant revocation, spending limits
-- **Cryptographic Identity**: JWT passports verifiable offline
-
-## Infrastructure Security
-
-### Idempotency
-- Idempotency keys required on all payment operations
-- Concurrent duplicates return `409 Conflict`
-- Request payloads hashed to detect tampering
-
-### WebAuthn
-- Origin-bound credentials (phishing-resistant)
-- Single-use challenges with TTL
-- Hardware counter validation
-
-### Rate Limiting
-| Endpoint | Limit |
-|----------|-------|
-| Auth | 5/min |
-| Payments | 30/min |
-| General | 100/min |
-
-### Webhook Processing
-- Stripe event deduplication via `WebhookEvent` table
-- Row-level locking (`SELECT ... FOR UPDATE`)
-- Serializable transaction isolation
-
-### Hardware Security by Device
-
-| Device | Security | Auth Method |
-|--------|----------|-------------|
-| iPhone/iPad | Secure Enclave | FaceID/TouchID |
-| Mac (Touch ID) | Secure Enclave | TouchID |
-| Mac (no Touch ID) | Phone via QR | Phone's Secure Enclave |
-| Windows (Hello) | TPM 2.0 | Windows Hello |
-| Windows (no Hello) | Phone via QR | Requires Bluetooth + manual selection |
-| Android | TEE/StrongBox | Fingerprint/Face |
-
-**Windows Note:** Without Windows Hello, users see a USB security key prompt first. They must click Cancel and select "iPhone/Android" for QR code. Bluetooth must be enabled.
-
-## Application Fee Routing (Optional)
-
-Configure application fees per transaction. The protocol uses an additive settlement model, calculating charges on top of the base amount. This ensures merchant principal preservation while automating fee routing to the connected Stripe account.
-
-### Configuration
+## Vercel AI SDK
 
 ```typescript
-// Principal is $100, total authorization is $106
-const payment = await rails.processPayment({
-  amount: 10000, // $100.00 principal amount
-  currency: 'usd',
-  merchant: 'Acme Corp',
-  mandateId: 'mandate_xyz',
-  paymentId: 'payment_abc',
-  userId: 'user_123',
-  applicationFee: {
-    destinationAccountId: 'acct_your_stripe_connect_id',
-    feePercent: 5,     // percentage of principal
-    // OR
-    feeFixed: 100,     // fixed amount (cents)
-    // OR both combined
-  },
-});
-```
-
-### Fee Routing Options
-
-| Parameter | Example | On $100 principal |
-|-----------|---------|-------------------|
-| `feePercent` | `5` | +$5.00 |
-| `feeFixed` | `100` | +$1.00 |
-| Hybrid | `{ percent: 2, fixed: 30 }` | +$2.30 |
-
-### Settlement Model
-
-$100 principal with 1% protocol fee + 5% application fee:
-
-| Settlement | Amount |
-|------------|--------|
-| Net Settlement (Merchant) | $100.00 |
-| Protocol Fee (Attesso) | $1.00 |
-| Application Fee | $5.00 |
-| **Total Authorization** | **$106.00** |
+import { generateText } from 'ai';
+import { attesso } from '@attesso/sdk/vercel';
 
-```typescript
-const settlement = rails.calculateFees(10000, 5, 0);
-// { netSettlement: 10000, protocolFee: 100, applicationFee: 500, totalAuthorization: 10600 }
+const result = await generateText({
+  model: openai('gpt-4o'),
+  tools: attesso.tools({
+    mandateId: 'mandate_xyz',      // optional: pre-select mandate
+    merchant: 'Acme Corp',         // optional: lock to merchant
+    maxAmountPerTransaction: 50000, // optional: per-tx cap
+  }),
+  prompt: 'Book a flight under $500',
+});
 ```
 
-### Requirements
-
-- Stripe Connect account (`acct_...` ID)
-- Application fee routing is optional—omit to disable
+### Tools
 
-## Origin Restrictions (Optional)
+| Tool | Parameters | Returns |
+|------|------------|---------|
+| `attesso_pay` | `{ mandateId?, amount, merchant? }` | PaymentResponse |
+| `attesso_get_mandate` | `{ mandateId? }` | MandateResponse |
+| `attesso_get_payment` | `{ paymentId }` | PaymentResponse |
+| `attesso_get_passport` | `{ mandateId? }` | PassportToken |
+| `attesso_capture` | `{ paymentId, amount, metadata? }` | CaptureResponse |
+| `attesso_cancel` | `{ paymentId }` | CancelResponse |
+| `attesso_check_balance` | `{ mandateId? }` | `{ available, currency, status }` |
 
-Restrict SDK usage to specific domains:
+## Origin Restrictions
 
 ```typescript
 const client = new AttessoClient({
-  apiKey: 'sk_bot_xyz',
-  allowedOrigins: [
-    'https://myapp.com',
-    'https://*.trusted-partner.com',  // Wildcard subdomains
-  ],
+  apiKey: '...',
+  allowedOrigins: ['https://myapp.com', 'https://*.trusted.com'],
 });
 ```
 
-Requests from non-allowed origins throw `OriginNotAllowedError`.
-
-## Environment Variables
-
-```bash
-ATTESSO_API_KEY=your_api_key
-ATTESSO_BASE_URL=https://api.attesso.dev  # optional
-```
+Throws `OriginNotAllowedError` if called from unlisted origin.
 
-## TypeScript
-
-Full type safety included:
+## Types
 
 ```typescript
 import type {
   MandateResponse,
   PaymentResponse,
   PassportToken,
-  WebAuthnAssertion,
+  CapturePaymentResponse,
+  CancelAuthorizationResponse,
 } from '@attesso/sdk';
 ```
 
+## Errors
+
+```typescript
+import { AttessoError, OriginNotAllowedError } from '@attesso/sdk';
+
+try {
+  await client.executePayment({ ... });
+} catch (e) {
+  if (e instanceof AttessoError) {
+    console.log(e.code); // MANDATE_NOT_FOUND, AMOUNT_EXCEEDS_LIMIT, etc.
+  }
+}
+```
+
 ## Requirements
 
 - Node.js 18+
-- For Vercel AI SDK integration: `ai` >= 3.0, `zod` >= 3.0
+- For Vercel AI SDK: `ai` >= 3.0, `zod` >= 3.0
 
 ## License
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@attesso/sdk",
-  "version": "1.0.0",
-  "description": "Attesso SDK for autonomous commerce - enable AI agents to make purchases",
+  "version": "1.0.2",
+  "description": "API client for executing payments against FIDO2-signed mandates. Includes Vercel AI SDK tools.",
   "author": "Attesso",
   "license": "MIT",
   "repository": {
@@ -41,11 +41,9 @@
   "keywords": [
     "attesso",
     "payments",
-    "ai-agents",
-    "autonomous-commerce",
-    "open-banking",
-    "vercel-ai-sdk",
-    "ai-tools"
+    "mandates",
+    "fido2",
+    "vercel-ai-sdk"
   ],
   "dependencies": {
     "@attesso/gatekeeper": "workspace:*",