lane-sdk 0.1.0

package/README.md

@@ -0,0 +1,1061 @@
+# Lane Agent SDK
+
+> `npm install lane` — Add wallets and payments to your AI agents.
+
+Lane is the payment infrastructure for AI agents. It lets agent developers give their agents the ability to discover merchants, manage payment methods, and complete purchases — all through a type-safe SDK, 14 MCP tools, and a CLI.
+
+```ts
+import Lane from 'lane'
+
+const lane = Lane.fromApiKey(process.env.LANE_KEY!)
+
+// Discover merchants
+const { data: merchants } = await lane.merchants.list({ query: 'sneakers' })
+const merchant = merchants[0]
+
+// Search products
+const { data: products } = await lane.products.search({ query: 'jordan 4' })
+
+// Execute payment
+const txn = await lane.pay.execute({
+  recipient: merchant.domain,
+  amount: 19999,  // cents
+  currency: 'USD',
+  description: 'Jordan 4 Retro',
+})
+
+console.log(txn.status)    // 'success'
+console.log(txn.receiptUrl) // 'https://...'
+```
+
+## Table of Contents
+
+- [How It Works](#how-it-works)
+- [Quick Start](#quick-start)
+- [Authentication](#authentication)
+- [SDK Resources](#sdk-resources)
+- [MCP Integration](#mcp-integration)
+- [CLI](#cli)
+- [Payment Routing](#payment-routing)
+- [Merchant Directory](#merchant-directory)
+- [Security](#security)
+- [Enterprise Features](#enterprise-features)
+- [Server](#server)
+- [Architecture](#architecture)
+- [Development](#development)
+
+## How It Works
+
+### End-to-End Agent Payment Flow
+
+This is the core flow when an AI agent discovers a merchant and makes a purchase:
+
+```
+ AI Agent (Claude, Cursor, etc.)
+ │
+ │  1. "Find me sneakers under $200"
+ │
+ ▼
+┌──────────────────────────────────────────────────────────────────────────┐
+│                           Lane SDK                                      │
+│                                                                          │
+│  ┌─────────────────┐    ┌─────────────────┐    ┌──────────────────────┐ │
+│  │  2. DISCOVER     │    │  3. SEARCH       │    │  4. PAY              │ │
+│  │                  │    │                  │    │                      │ │
+│  │  merchants.list  │───▶│  products.search │───▶│  pay.execute         │ │
+│  │  ({ query:       │    │  ({ query:       │    │  ({ recipient,       │ │
+│  │    "sneakers" }) │    │    "jordan 4" }) │    │    amount: 19999 })  │ │
+│  └────────┬─────────┘    └────────┬─────────┘    └──────────┬───────────┘ │
+│           │                       │                          │            │
+└───────────┼───────────────────────┼──────────────────────────┼────────────┘
+            │                       │                          │
+            ▼                       ▼                          ▼
+┌───────────────────┐  ┌───────────────────┐  ┌────────────────────────────┐
+│ Merchant Directory│  │  Product Catalog  │  │     Payment Pipeline       │
+│                   │  │                   │  │                            │
+│ • Legendary       │  │ • Jordan 4 Retro  │  │  Budget ──▶ Route ──▶ PSP │
+│   Sneakers        │  │   $199.99         │  │  Check      Engine    Charge│
+│ • tier: onboarded │  │ • Air Max 90      │  │                            │
+│ • fashion/shoes   │  │   $129.99         │  │  ┌────────────────────┐    │
+│                   │  │                   │  │  │ Routing Decision:  │    │
+│                   │  │                   │  │  │ billing_api (Tier 1)│   │
+│                   │  │                   │  │  └────────────────────┘    │
+└───────────────────┘  └───────────────────┘  └────────────────────────────┘
+```
+
+### Three Ways to Integrate
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                            Your Application                             │
+├──────────────────┬────────────────────────┬──────────────────────────────┤
+│                  │                        │                              │
+│   MCP Server     │     SDK (TypeScript)   │          CLI                 │
+│                  │                        │                              │
+│  For AI agents   │  For application code  │  For developers & scripts   │
+│  that speak MCP  │  that calls Lane APIs  │  that need quick access     │
+│                  │                        │                              │
+│  14 tools:       │  17 resources:         │  16 commands:               │
+│  • discover_     │  • lane.merchants      │  • lane login               │
+│    merchants     │  • lane.pay            │  • lane pay                 │
+│  • pay           │  • lane.wallets        │  • lane balance             │
+│  • checkout      │  • lane.checkout       │  • lane checkout            │
+│  • check_balance │  • lane.admin          │  • lane set-budget          │
+│  • ...           │  • ...                 │  • ...                      │
+│                  │                        │                              │
+│  ┌────────────┐  │  ┌──────────────────┐  │  ┌────────────────────────┐ │
+│  │ stdio or   │  │  │ Lane.fromApiKey() │  │  │ npx lane <command>    │ │
+│  │ HTTP       │  │  │ Lane.create()     │  │  │ Reads ~/.lane/creds   │ │
+│  │ transport  │  │  │                   │  │  │                       │ │
+│  └─────┬──────┘  │  └────────┬─────────┘  │  └───────────┬───────────┘ │
+│        │         │           │             │              │              │
+├────────┴─────────┴───────────┴─────────────┴──────────────┴──────────────┤
+│                          Lane HTTP Client                                │
+│               HMAC-SHA256 · Retries · Circuit Breaker                    │
+└──────────────────────────────────┬───────────────────────────────────────┘
+                                   │
+                                   ▼
+                          Lane API Server
+```
+
+### Payment Routing Decision Tree
+
+```
+                         Incoming Payment
+                              │
+                              ▼
+                    ┌───────────────────┐
+                    │   Budget Check    │
+                    │   within limits?  │
+                    └────────┬──────────┘
+                             │
+                    ┌────────┴────────┐
+                    │ NO              │ YES
+                    ▼                 ▼
+              ┌──────────┐  ┌──────────────────┐
+              │  DENIED  │  │ Lookup Merchant   │
+              │  budget  │  │ in Registry       │
+              │  exceeded│  └────────┬──────────┘
+              └──────────┘           │
+                            ┌────────┴─────────┐
+                            │                  │
+                            ▼                  ▼
+                    Has Billing API?     Supports ACP?
+                            │                  │
+                      ┌─────┴─────┐      ┌─────┴─────┐
+                      │YES        │NO    │YES        │NO
+                      ▼           │      ▼           │
+               ┌─────────────┐   │ ┌──────────┐     │
+               │   TIER 1    │   │ │  TIER 2  │     │
+               │ Billing API │   │ │   ACP    │     │
+               │ (cheapest)  │   │ │(protocol)│     │
+               └─────────────┘   │ └──────────┘     │
+                                 │                   │
+                                 └─────────┬─────────┘
+                                           │
+                                           ▼
+                                  Has VIC Token +
+                                  Visa Card?
+                                           │
+                                     ┌─────┴─────┐
+                                     │YES        │NO
+                                     ▼           ▼
+                              ┌──────────┐ ┌──────────┐
+                              │  TIER 3  │ │  TIER 4  │
+                              │   VIC    │ │ Fallback │
+                              │ (Visa    │ │ (standard│
+                              │  network)│ │  card)   │
+                              └──────────┘ └──────────┘
+```
+
+### Merchant Discovery Flow
+
+```
+                    ┌──────────────────────────────────────────┐
+                    │         Merchant Directory Service        │
+                    │                                          │
+                    │   In-Memory Cache (refreshed every 30m)  │
+                    └───────────┬──────────────┬───────────────┘
+                                │              │
+              ┌─────────────────┘              └──────────────────┐
+              │                                                    │
+              ▼                                                    ▼
+   ┌─────────────────────┐                          ┌──────────────────────┐
+   │  Lane-Onboarded     │                          │  Protocol Discovery  │
+   │  (Tier 1)           │                          │  (Tier 2)            │
+   │                     │                          │                      │
+   │  Sync from Lane     │                          │  Probe domain:       │
+   │  backend on startup │                          │                      │
+   │                     │                          │  GET /.well-known/ucp│
+   │  POST /merchants/   │                          │  GET /.well-known/acp│
+   │       sync          │                          │                      │
+   │                     │                          │  POST /merchants/    │
+   │  Full checkout API  │                          │       discover       │
+   │  Product catalog    │                          │                      │
+   │  Payment routing    │                          │  Protocol endpoints  │
+   └─────────┬───────────┘                          │  Cached manifests    │
+             │                                      └──────────┬───────────┘
+             │                                                  │
+             ▼                                                  ▼
+   ┌──────────────────────────────────────────────────────────────────────┐
+   │                        merchant_directory (PostgreSQL)               │
+   │                                                                      │
+   │  ┌─────────────────────────────────────────────────────────────────┐ │
+   │  │ id │ name               │ tier          │ type      │ vertical │ │
+   │  ├────┼────────────────────┼───────────────┼───────────┼──────────┤ │
+   │  │ ...│ Legendary Sneakers │ lane_onboarded│ ecommerce │ fashion  │ │
+   │  │ ...│ shop.example.com   │ protocol      │ ecommerce │ ...      │ │
+   │  └─────────────────────────────────────────────────────────────────┘ │
+   │                                                                      │
+   │  Indexes: slug (unique), domain (unique), subcategories (GIN),      │
+   │           name (trigram), tier, status, merchant_type, vertical      │
+   └──────────────────────────────────────────────────────────────────────┘
+```
+
+### Security & Card Data Flow
+
+```
+                Agent adds a card
+                       │
+                       ▼
+            ┌────────────────────┐
+            │  VGS Collect Form  │    Card PAN entered in
+            │  (iframe/hosted)   │    VGS-controlled form
+            └─────────┬──────────┘
+                      │
+                      │  PAN goes directly to VGS
+                      │  (never touches Lane servers)
+                      ▼
+            ┌────────────────────┐
+            │  VGS Vault         │    PAN stored as token
+            │                    │    tok_4111...1234
+            │  PCI DSS Level 1   │
+            └─────────┬──────────┘
+                      │
+                      │  Token (alias) returned
+                      ▼
+            ┌────────────────────┐
+            │  Lane Server       │    Stores only: last4,
+            │                    │    brand, token alias
+            │  Never sees PAN    │    (never the full PAN)
+            └─────────┬──────────┘
+                      │
+                      │  Payment request with token
+                      ▼
+            ┌────────────────────┐
+            │  VGS Outbound      │    VGS replaces token
+            │  Proxy             │    with real PAN in-flight
+            └─────────┬──────────┘
+                      │
+                      │  Real PAN sent to PSP
+                      ▼
+            ┌────────────────────┐
+            │  PSP               │    Stripe / Worldpay /
+            │  (Payment          │    CyberSource processes
+            │   Processor)       │    the charge
+            └────────────────────┘
+```
+
+### Enterprise Budget Enforcement
+
+```
+                         Payment Request ($150)
+                                │
+                                ▼
+              ┌─────────────────────────────────────┐
+              │       Hierarchical Budget Check      │
+              │                                     │
+              │  Org Budget     $10,000/mo  ✓ pass  │
+              │       │                             │
+              │       ▼                             │
+              │  Team Budget    $2,000/mo   ✓ pass  │
+              │       │                             │
+              │       ▼                             │
+              │  Dev Budget     $500/day    ✓ pass  │
+              │       │                             │
+              │       ▼                             │
+              │  Agent Policy   $200/txn    ✓ pass  │
+              │       │                             │
+              │       ▼                             │
+              │  Merchant       allowlist   ✓ pass  │
+              │  Allowlist      check              │
+              │       │                             │
+              │       ▼                             │
+              │  MCC Check      5661 (shoes) ✓ pass │
+              │                                     │
+              │  Effective limit = min(all levels)  │
+              └────────────────┬────────────────────┘
+                               │
+                          All passed
+                               │
+                               ▼
+                     Route to Payment
+```
+
+## Quick Start
+
+```bash
+# Install
+npm install lane
+
+# Authenticate (opens browser)
+npx lane login
+
+# Verify
+npx lane whoami
+
+# Check balance
+npx lane balance
+
+# Make a payment
+npx lane pay --recipient replicate.com --amount 20.00
+```
+
+### Programmatic Usage
+
+```ts
+import Lane from 'lane'
+
+// Option 1: Async config resolution (constructor > env > credentials file)
+const lane = await Lane.create()
+
+// Option 2: Explicit API key
+const lane = Lane.fromApiKey('lane_sk_...')
+
+// Option 3: Test mode
+const lane = Lane.fromApiKey('lane_sk_test_...', { testMode: true })
+```
+
+## Authentication
+
+Config resolution order (first match wins):
+
+1. **Constructor:** `Lane.fromApiKey('lane_sk_...')` or `Lane.create({ apiKey: '...' })`
+2. **Environment variable:** `LANE_API_KEY`
+3. **Credentials file:** `~/.lane/credentials.json` (written by `npx lane login`)
+
+```ts
+// Check who you are
+const profile = await lane.auth.whoami()
+// { id: 'dev_...', email: 'you@company.com', plan: 'pro', memberSince: '2025-01-15' }
+
+// Rotate API key (old key valid for 15 min)
+const { apiKey, expiresOldKeyAt } = await lane.auth.rotateKey()
+```
+
+## SDK Resources
+
+The SDK exposes 17 resource classes, all lazily initialized on first access.
+
+### Core Resources
+
+| Resource | Description | Key Methods |
+|---|---|---|
+| `lane.auth` | Authentication & key management | `whoami()`, `login()`, `rotateKey()` |
+| `lane.wallets` | Wallet lifecycle & cards | `create()`, `list()`, `balance()`, `deposit()`, `listCards()`, `getAddCardLink()` |
+| `lane.pay` | Payment execution | `createToken()`, `execute()`, `listTransactions()`, `refund()` |
+| `lane.products` | Product discovery | `search()`, `get()`, `listMerchants()` |
+| `lane.checkout` | Checkout sessions | `create()`, `complete()`, `get()`, `cancel()` |
+| `lane.merchants` | Merchant directory | `list()`, `get()`, `listByVertical()`, `discover()`, `verticals()` |
+| `lane.sell` | Seller tools (Make-a-SaaS) | `create()`, `list()`, `analytics()`, `createSoftwareProduct()` |
+| `lane.webhooks` | Webhook management | `create()`, `list()`, `verify()`, `constructEvent()` |
+| `lane.admin` | Spending & budgets | `spending()`, `setBudget()`, `listMembers()`, `exportData()` |
+| `lane.subscriptions` | Subscription management | `create()`, `cancel()`, `upgrade()`, `pause()`, `resume()` |
+
+### Phase 2 — VIC (Visa Intelligent Commerce)
+
+| Resource | Description | Key Methods |
+|---|---|---|
+| `lane.vic` | Visa network tokens | `issue()`, `getCryptogram()`, `revoke()`, `suspend()` |
+
+### Phase 4 — Make-a-SaaS
+
+| Resource | Description | Key Methods |
+|---|---|---|
+| `lane.metering` | Usage tracking for sellers | `record()`, `recordBatch()`, `report()`, `setConfig()` |
+| `lane.payouts` | Seller disbursements | `getConfig()`, `setConfig()`, `list()` |
+
+### Phase 5 — Corporate Agent Spend
+
+| Resource | Description | Key Methods |
+|---|---|---|
+| `lane.teams` | Team management | `create()`, `addMember()`, `setBudget()`, `getHierarchicalBudget()` |
+| `lane.agents` | Agent fleet management | `register()`, `setPolicy()`, `suspend()`, `assignWallet()` |
+| `lane.audit` | SOC 2 audit trail | `query()`, `export()`, `summary()` |
+
+### Phase 6 — Agent Identity
+
+| Resource | Description | Key Methods |
+|---|---|---|
+| `lane.identity` | Agent KYC chain | `register()`, `verify()`, `getAttestation()`, `refreshAttestation()` |
+
+### Usage Examples
+
+```ts
+// Wallets & Cards
+const wallet = await lane.wallets.create({ userId: 'user_123' })
+const cards = await lane.wallets.listCards(wallet.id)
+const balance = await lane.wallets.balance(wallet.id)
+
+// Payments
+const token = await lane.pay.createToken({
+  walletId: wallet.id,
+  amount: 5000,
+  merchant: 'legendarysneakers.com',
+  expiresIn: '1h',
+})
+const txn = await lane.pay.execute({
+  tokenId: token.id,
+  recipient: 'legendarysneakers.com',
+  amount: 4999,
+})
+
+// Refunds
+const refund = await lane.pay.refund({
+  transactionId: txn.id,
+  reason: 'Wrong size',
+})
+
+// Checkout profiles (saved address/email for faster checkout)
+await lane.wallets.setProfile(wallet.id, {
+  email: 'agent@company.com',
+  fullName: 'AI Agent',
+  billingLine1: '123 Main St',
+  billingCity: 'San Francisco',
+  billingState: 'CA',
+  billingPostalCode: '94105',
+  billingCountry: 'US',
+})
+
+// Merchant accounts (saved credentials per merchant)
+await lane.wallets.saveMerchantAccount(wallet.id, {
+  merchantDomain: 'legendarysneakers.com',
+  merchantName: 'Legendary Sneakers',
+  authType: 'api_key',
+  apiKeyAlias: 'vgs_tok_...',
+})
+
+// Budgets
+await lane.admin.setBudget({
+  dailyLimit: 10000,    // $100.00
+  perTaskLimit: 5000,   // $50.00
+  merchantAllowlist: ['legendarysneakers.com'],
+})
+
+// Subscriptions
+const sub = await lane.subscriptions.create({
+  productId: 'prod_...',
+  plan: 'pro',
+  paymentSource: 'wallet',
+})
+
+// Agent fleet management
+const agent = await lane.agents.register({
+  name: 'shopping-agent',
+  type: 'autonomous',
+  walletId: wallet.id,
+  policy: {
+    budget: { dailyLimit: 5000 },
+    maxTransactionAmount: 2500,
+    canDiscover: true,
+    canRefund: false,
+  },
+})
+
+// Webhooks
+await lane.webhooks.create({
+  url: 'https://api.myapp.com/hooks/lane',
+  events: ['transaction.completed', 'budget.exceeded'],
+})
+```
+
+## MCP Integration
+
+Lane ships with 14 MCP tools that any AI agent (Claude, Cursor, etc.) can use out of the box.
+
+### Setup
+
+```bash
+# Auto-configure for Claude Desktop / Cursor
+npx lane setup-mcp
+```
+
+Or add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "lane": {
+      "command": "npx",
+      "args": ["lane-mcp-server"],
+      "env": {
+        "LANE_API_KEY": "lane_sk_..."
+      }
+    }
+  }
+}
+```
+
+### Programmatic MCP Server
+
+```ts
+import { Lane, LaneMCPServer } from 'lane'
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+
+const lane = Lane.fromApiKey(process.env.LANE_API_KEY!)
+const server = new LaneMCPServer(lane)
+
+const transport = new StdioServerTransport()
+await server.mcp.connect(transport)
+```
+
+### Available Tools (14)
+
+| Tool | Description | Key Inputs |
+|---|---|---|
+| `whoami` | Get authenticated developer profile | — |
+| `check_balance` | Get wallet balance | `walletId?` |
+| `list_cards` | List cards in wallet | `walletId?` |
+| `pay` | Execute a payment | `amount`, `recipient`, `currency?`, `description?` |
+| `list_transactions` | List transaction history | `limit?`, `offset?` |
+| `search_products` | Search product catalog | `query`, `type?`, `limit?` |
+| `search_software` | Search software products | `query`, `type?`, `pricingModel?` |
+| `checkout` | Purchase a product | `productId`, `walletId?`, `quantity?` |
+| `set_budget` | Set spending limits | `daily?`, `weekly?`, `monthly?`, `perTask?` |
+| `request_refund` | Refund a transaction | `transactionId`, `amount?`, `reason?` |
+| `subscribe` | Create a subscription | `productId`, `plan`, `walletId?` |
+| `list_subscriptions` | List active subscriptions | `status?`, `limit?` |
+| `cancel_subscription` | Cancel a subscription | `subscriptionId` |
+| `discover_merchants` | Search merchant directory | `query?`, `merchantType?`, `vertical?`, `subcategory?` |
+
+## CLI
+
+```
+lane <command>
+
+Authentication:
+  lane login           Start OAuth login flow (opens browser)
+  lane logout          Delete stored credentials
+  lane whoami          Display authenticated developer profile
+  lane rotate-key      Rotate API key
+
+Wallet:
+  lane balance         Get wallet balance
+  lane cards           List cards in wallet
+  lane add-card        Get VGS Collect link to securely add a card
+  lane wallet          Wallet management (list, create, deposit)
+  lane transactions    List transaction history
+
+Payments:
+  lane pay             Execute a payment
+  lane checkout        Purchase a product from catalog
+  lane set-budget      Set spending limits
+
+Seller:
+  lane vendor          Seller tools (list products, view analytics)
+  lane schema          Display API schema
+
+Setup:
+  lane setup-mcp       Configure MCP server for Claude/Cursor
+  lane dashboard       Open Lane dashboard in browser
+```
+
+## Payment Routing
+
+Lane's routing engine selects the optimal payment path for each transaction using a 4-tier priority system:
+
+```
+Tier 1: Billing API   — Direct merchant API integration (cheapest, fastest)
+Tier 2: ACP           — Agent Commerce Protocol checkout
+Tier 3: VIC           — Visa Intelligent Commerce token (works at any Visa merchant)
+Tier 4: Fallback      — Standard card payment via PSP
+```
+
+The router considers merchant capabilities, card brand, VIC token availability, and budget constraints:
+
+```ts
+import { PaymentRouter, MerchantRegistry } from 'lane'
+
+const registry = new MerchantRegistry()
+registry.register({
+  merchantId: 'merch_123',
+  hasBillingAPI: true,
+  supportsACP: true,
+  supportsVIC: false,
+  acceptsVisa: true,
+  acceptsMastercard: true,
+  mccs: ['5661'],
+})
+
+const router = new PaymentRouter(registry)
+const decision = router.route({
+  amount: 4999,
+  currency: 'USD',
+  merchantId: 'merch_123',
+  cardBrand: 'visa',
+  hasVICToken: false,
+})
+// { route: 'billing_api', reason: 'Merchant has direct billing API integration (cheapest path).', fallbacks: ['acp', 'fallback'] }
+```
+
+The `MerchantRegistry` can be populated directly from the merchant directory:
+
+```ts
+const capabilities = await container.merchantDirectory.populateRegistry()
+const registry = MerchantRegistry.fromDirectory(capabilities)
+```
+
+## Merchant Directory
+
+The merchant directory is a live, queryable registry of AI-shoppable merchants. Two tiers:
+
+- **Lane-onboarded** — Full checkout API, synced from Lane backend (e.g., Legendary Sneakers)
+- **Protocol-compatible** — Merchants exposing `/.well-known/acp` or `/.well-known/ucp` endpoints
+
+### Taxonomy
+
+Merchants are classified hierarchically:
+
+| Type | Verticals | Example Subcategories |
+|---|---|---|
+| `ecommerce` | fashion, electronics, beauty, home, food_beverage, sports_outdoor, kids_baby | shoes, sneakers, laptops, skincare |
+| `software` | developer_tools, productivity, ai_ml, security | hosting, databases, ci_cd, auth |
+| `api` | data, communications, payments, infrastructure | enrichment, sms, processing, cdn |
+| `saas` | business, marketing, finance | crm, analytics, accounting |
+| `skill` | agent_tools | web_scraping, code_gen, research |
+| `service` | travel, delivery, professional | flights, food, legal |
+
+### Vertical-Specific Product Attributes
+
+Each merchant stores a `productAttributes` schema tailored to its vertical:
+
+```ts
+// Fashion/shoes merchant
+{ available_sizes: ['7','8','9'], colors: ['black','white'], brands: ['Nike','Jordan'] }
+
+// Electronics merchant
+{ specs: { ram_gb: 16, storage_gb: 512 }, brand: 'Apple', model_year: 2025 }
+
+// Software merchant
+{ runtime: 'node', sdk_package: '@acme/sdk', docs_url: '...' }
+```
+
+### Usage
+
+```ts
+// Search by text
+const { data } = await lane.merchants.list({ query: 'sneakers' })
+
+// Filter by vertical
+const fashion = await lane.merchants.listByVertical('fashion')
+
+// Filter by protocol
+const acpMerchants = await lane.merchants.listByProtocol('acp')
+
+// Lane-onboarded only
+const onboarded = await lane.merchants.listOnboarded()
+
+// List all verticals and subcategories
+const verticals = await lane.merchants.verticals()
+
+// Discover a protocol-compatible merchant by domain
+const result = await lane.merchants.discover('shop.example.com')
+```
+
+### Seeded Merchants
+
+The directory ships with pre-populated merchants including:
+
+- **Legendary Sneakers** (`legendarysneakers.com`) — Premium sneakers and streetwear. Lane-onboarded, Shopify/Worldpay, billing API + ACP support. Fashion vertical with sizes 7-13, brands (Nike, Jordan, Adidas, New Balance, Yeezy).
+
+Additional merchants are synced from the Lane backend on startup or via the sync API.
+
+## Security
+
+### PCI DSS Compliance
+
+Card PANs **never** touch Lane servers. All card data is tokenized through [VGS](https://www.verygoodsecurity.com/) (Very Good Security):
+
+```ts
+import { VGSOutboundProxy, detectCardBrand, luhnCheck } from 'lane'
+
+// Card utilities
+detectCardBrand('4111111111111111')  // 'visa'
+luhnCheck('4111111111111111')        // true
+
+// Generate secure card collection form
+import { generateCollectPage } from 'lane'
+const html = generateCollectPage({
+  vaultId: 'tnt...',
+  environment: 'sandbox',
+  formId: 'card-form',
+  redirectUrl: 'https://app.example.com/done',
+})
+```
+
+### HMAC Request Signing
+
+Every SDK request is signed with HMAC-SHA256:
+
+```ts
+import { HMACSignature, verifyWebhookSignature } from 'lane'
+
+// Verify incoming webhook
+const isValid = verifyWebhookSignature(
+  rawBody,
+  req.headers['x-lane-signature'],
+  webhookSecret,
+  parseInt(req.headers['x-lane-timestamp']),
+)
+```
+
+### Credential Storage
+
+Credentials are stored at `~/.lane/credentials.json` with `0600` file permissions (owner read/write only). Directory permissions are set to `0700`.
+
+### HTTP Client Resilience
+
+- **Automatic retries** with exponential backoff (1s, 3s, max 5s jitter) on 5xx and 429
+- **Circuit breaker** pattern (3 consecutive failures opens circuit for 30s)
+- **Idempotency keys** to prevent duplicate charges on retry
+- **Rate limit awareness** with `Retry-After` header support
+
+## Enterprise Features
+
+### Hierarchical Budgets
+
+Budget limits cascade: Organization > Team > Developer > Agent. The effective limit is the minimum across all levels.
+
+```ts
+// Set team budget
+await lane.teams.setBudget('team_123', {
+  dailyLimit: 100000,     // $1,000
+  monthlyLimit: 1000000,  // $10,000
+  perTaskLimit: 10000,    // $100
+})
+
+// View effective limits
+const budget = await lane.teams.getHierarchicalBudget('team_123')
+// { orgBudget, teamBudget, developerBudget, agentBudget, effectiveLimits }
+```
+
+### Agent Policies
+
+Per-agent spending constraints:
+
+```ts
+await lane.agents.setPolicy('agent_123', {
+  budget: { dailyLimit: 5000 },
+  allowedMCCs: ['5661', '5699'],     // Shoe stores only
+  maxTransactionAmount: 25000,        // $250 max per transaction
+  canRefund: false,
+  canDiscover: true,
+  approvalThreshold: 10000,           // Human approval above $100
+})
+```
+
+### Agent Identity & KYC Chain
+
+Lane-issued identity credentials with a 4-step verification chain: Human (developer KYC) > Lane (platform verification) > Agent (registration + policy binding) > Transaction (cryptographic attestation).
+
+```ts
+const identity = await lane.identity.register({
+  agentId: 'agent_123',
+  capabilities: ['payments', 'product_discovery'],
+  purpose: 'Autonomous shopping assistant',
+})
+
+const attestation = await lane.identity.getAttestation(identity.id)
+```
+
+### Audit Trail
+
+Immutable audit log for SOC 2 compliance:
+
+```ts
+const { data: entries } = await lane.audit.query({
+  startDate: '2025-01-01',
+  actorType: 'agent',
+  action: 'payment.execute',
+  limit: 50,
+})
+
+const summary = await lane.audit.summary({ period: '30d' })
+// { totalEntries, byAction, byActorType, topActors }
+```
+
+### GDPR
+
+```ts
+const data = await lane.admin.exportData()
+const { deletionCompletesAt } = await lane.admin.deleteAccount()
+```
+
+## Server
+
+The SDK includes a full Express backend with OOP service architecture.
+
+### Environment Variables
+
+```bash
+SUPABASE_URL=https://...supabase.co     # Required
+SUPABASE_SERVICE_KEY=eyJ0eXAi...        # Required
+PORT=3001                                # Default: 3001
+LOG_LEVEL=INFO                           # DEBUG | INFO | WARN | ERROR
+
+# Merchant directory sync (optional)
+LANE_BACKEND_URL=https://app.getonlane.com
+LANE_BACKEND_TOKEN=...
+```
+
+### API Routes
+
+All routes are under `/api/sdk/` and require API key authentication.
+
+| Prefix | Description |
+|---|---|
+| `/api/sdk/auth` | Login, token exchange, key rotation |
+| `/api/sdk/wallets` | Wallet CRUD, cards, profiles, merchant accounts |
+| `/api/sdk/pay` | Token creation, payment execution, refunds |
+| `/api/sdk/admin` | Spending reports, budgets, team members |
+| `/api/sdk/merchants` | Merchant directory (list, get, capabilities, sync, discover) |
+
+### Middleware Stack
+
+```
+Request → JSON Parser → CORS → API Key Auth → Rate Limit → HMAC Verify → Audit → Route → Error Handler
+```
+
+### Services (9)
+
+| Service | Description |
+|---|---|
+| `WalletService` | Wallet lifecycle, balance tracking |
+| `CardService` | Card management, VGS tokenization |
+| `TokenService` | Agentic token lifecycle (create, validate, consume, expire) |
+| `PaymentService` | Payment execution, PSP routing, refunds |
+| `BudgetService` | Budget enforcement, spending counters, period resets |
+| `ProfileService` | Checkout profiles (address, email, phone) |
+| `MerchantAccountService` | Saved merchant credentials per wallet |
+| `MerchantDirectoryService` | Merchant registry, backend sync, protocol discovery |
+| `VGSProxyService` | VGS outbound proxy for PCI-compliant card operations |
+
+### Database
+
+11 SQL migrations using Supabase (PostgreSQL) with Row Level Security on all tables:
+
+```
+001_developers.sql          — Developer accounts
+002_api_keys.sql            — API key management
+003_vgs_vault_configs.sql   — VGS vault configurations
+004_wallets_cards.sql       — Wallets and payment cards
+005_checkout_profiles.sql   — Saved checkout information
+006_merchant_accounts.sql   — Per-merchant credentials
+007_agentic_tokens.sql      — Scoped payment tokens
+008_transactions.sql        — Transaction ledger
+009_budgets.sql             — Spending limits and counters
+010_audit_log.sql           — Immutable audit trail
+011_merchant_directory.sql  — Merchant directory, sync log, protocol manifests
+```
+
+## Architecture
+
+### System Overview
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                            AI Agent Layer                                │
+│                  Claude · Cursor · Custom Agents                         │
+├──────────────────┬────────────────────────┬──────────────────────────────┤
+│   MCP Server     │    SDK Client Library   │         CLI                  │
+│   (stdio/HTTP)   │    (TypeScript/JS)      │    (16 commands)             │
+│                  │                         │                              │
+│  14 tools        │  17 resource classes    │  login · pay · balance       │
+│  Zod validation  │  Lazy initialization    │  checkout · set-budget       │
+│  JSON responses  │  Type-safe methods      │  setup-mcp · vendor          │
+├──────────────────┴────────────────────────┴──────────────────────────────┤
+│                          HTTP Client (src/client.ts)                      │
+│                                                                          │
+│  HMAC-SHA256 signing    Exponential backoff     Circuit breaker           │
+│  Idempotency keys       Retry on 5xx/429        (3 failures → 30s open)  │
+│  Request ID tracking    Rate limit awareness     Event emitter            │
+├──────────────────────────────────────────────────────────────────────────┤
+│                                                                          │
+│                        Express Server (port 3001)                        │
+│                                                                          │
+│  ┌────────┐  ┌───────────┐  ┌────────────┐  ┌─────────┐  ┌───────────┐ │
+│  │JSON    │─▶│ API Key   │─▶│ Rate Limit │─▶│ HMAC    │─▶│ Audit     │ │
+│  │Parser  │  │ Auth      │  │            │  │ Verify  │  │ Logger    │ │
+│  └────────┘  └───────────┘  └────────────┘  └─────────┘  └─────┬─────┘ │
+│                                                                  │       │
+│  ┌───────────────────────────────────────────────────────────────┘       │
+│  │                                                                       │
+│  ▼  Routes                                                               │
+│  ┌──────────┬──────────┬──────────┬──────────┬────────────────┐          │
+│  │ /auth    │ /wallets │  /pay    │  /admin  │  /merchants    │          │
+│  │          │          │          │          │                │          │
+│  │ login    │ create   │ tokens   │ budgets  │ list/search    │          │
+│  │ exchange │ cards    │ execute  │ spending │ get by id/slug │          │
+│  │ rotate   │ profiles │ refunds  │ members  │ capabilities   │          │
+│  │          │ accounts │          │ export   │ sync/discover  │          │
+│  └────┬─────┴────┬─────┴────┬─────┴────┬─────┴───────┬────────┘         │
+│       │          │          │          │             │                    │
+│  ─────┴──────────┴──────────┴──────────┴─────────────┴───────────────    │
+│                        Service Container (DI)                            │
+│                                                                          │
+│  ┌──────────┬──────────┬──────────┬──────────┬──────────┬──────────────┐ │
+│  │ Wallet   │ Card     │ Token    │ Payment  │ Budget   │ Merchant     │ │
+│  │ Service  │ Service  │ Service  │ Service  │ Service  │ Directory    │ │
+│  ├──────────┼──────────┼──────────┼──────────┼──────────┤ Service      │ │
+│  │ Profile  │ Merchant │ VGS      │          │          │              │ │
+│  │ Service  │ Account  │ Proxy    │          │          │ 30m cache    │ │
+│  │          │ Service  │ Service  │          │          │ auto-sync    │ │
+│  └──────────┴──────────┴──────────┴──────────┴──────────┴──────────────┘ │
+│                                                                          │
+├──────────────────────────────────────────────────────────────────────────┤
+│                        Payment Infrastructure                            │
+│                                                                          │
+│  ┌──────────────────┐  ┌──────────────────┐  ┌────────────────────────┐ │
+│  │  Routing Engine   │  │  VGS Integration │  │  PSP Registry          │ │
+│  │                   │  │                  │  │                        │ │
+│  │  MerchantRegistry │  │  Outbound Proxy  │  │  ┌──────────────────┐ │ │
+│  │  PaymentRouter    │  │  Token Manager   │  │  │ Stripe (pri: 1)  │ │ │
+│  │                   │  │  Card Detection  │  │  │ Worldpay (pri: 2)│ │ │
+│  │  4-tier routing:  │  │  Luhn Validation │  │  │ CyberSource (3)  │ │ │
+│  │  billing_api      │  │  Collect Forms   │  │  └──────────────────┘ │ │
+│  │  acp              │  │                  │  │                        │ │
+│  │  vic              │  │  PCI DSS Level 1 │  │  Priority failover    │ │
+│  │  fallback         │  │  PAN never       │  │  Health checks        │ │
+│  │                   │  │  touches Lane    │  │                        │ │
+│  └──────────────────┘  └──────────────────┘  └────────────────────────┘ │
+│                                                                          │
+├──────────────────────────────────────────────────────────────────────────┤
+│                    Supabase (PostgreSQL + Row Level Security)             │
+│                                                                          │
+│  developers · api_keys · wallets · cards · tokens · transactions         │
+│  budgets · profiles · merchant_accounts · audit_log                      │
+│  merchant_directory · sync_log · protocol_manifests                      │
+│                                                                          │
+│  11 migrations · GIN indexes · trigram search · RLS on all tables        │
+└──────────────────────────────────────────────────────────────────────────┘
+```
+
+### Request Lifecycle
+
+```
+  Client                    Lane Server                          External
+    │                           │                                   │
+    │  POST /api/sdk/pay        │                                   │
+    │  Authorization: Bearer    │                                   │
+    │  X-Lane-Signature: sha256 │                                   │
+    │  X-Lane-Timestamp: ...    │                                   │
+    │  Idempotency-Key: ...     │                                   │
+    │ ─────────────────────────▶│                                   │
+    │                           │                                   │
+    │                     ┌─────┴─────┐                             │
+    │                     │ API Key   │  Verify key in DB           │
+    │                     │ Auth      │                              │
+    │                     └─────┬─────┘                             │
+    │                     ┌─────┴─────┐                             │
+    │                     │ Rate      │  Check rate limit           │
+    │                     │ Limit     │                              │
+    │                     └─────┬─────┘                             │
+    │                     ┌─────┴─────┐                             │
+    │                     │ HMAC      │  Verify request signature   │
+    │                     │ Verify    │                              │
+    │                     └─────┬─────┘                             │
+    │                     ┌─────┴─────┐                             │
+    │                     │ Audit     │  Log request                │
+    │                     │ Logger    │                              │
+    │                     └─────┬─────┘                             │
+    │                           │                                   │
+    │                     ┌─────┴─────┐                             │
+    │                     │ Budget    │  Check daily/weekly/monthly  │
+    │                     │ Service   │  limits, merchant allow/deny │
+    │                     └─────┬─────┘                             │
+    │                     ┌─────┴─────┐                             │
+    │                     │ Payment   │                              │
+    │                     │ Router    │  Select: billing_api         │
+    │                     └─────┬─────┘                             │
+    │                     ┌─────┴─────┐                             │
+    │                     │ VGS       │  Detokenize card ───────────▶│ VGS Vault
+    │                     │ Proxy     │◀──────────── real PAN ──────│
+    │                     └─────┬─────┘                             │
+    │                     ┌─────┴─────┐                             │
+    │                     │ PSP       │  Charge via Worldpay ──────▶│ Worldpay
+    │                     │ Adapter   │◀──────── auth code ────────│
+    │                     └─────┬─────┘                             │
+    │                     ┌─────┴─────┐                             │
+    │                     │ Record    │  Update spend counters      │
+    │                     │ Spend     │  Write transaction row      │
+    │                     └─────┬─────┘                             │
+    │                           │                                   │
+    │  200 OK                   │                                   │
+    │  { transactionId,         │                                   │
+    │    status: "success",     │                                   │
+    │    receiptUrl }           │                                   │
+    │ ◀─────────────────────────│                                   │
+    │                           │                                   │
+```
+
+### PSP Adapters
+
+Three payment processor adapters with priority-based failover:
+
+```ts
+import { PSPRegistry, StripeAdapter, WorldpayAdapter, CyberSourceAdapter } from 'lane'
+
+const registry = new PSPRegistry()
+registry.register(new StripeAdapter(config), 1)      // Primary
+registry.register(new WorldpayAdapter(config), 2)     // Secondary
+registry.register(new CyberSourceAdapter(config), 3)  // Tertiary
+
+const primary = registry.getPrimary()
+const result = await primary.charge({
+  amount: 4999,
+  currency: 'USD',
+  token: 'vgs_tok_...',
+  cardholderName: 'AI Agent',
+})
+```
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build (ESM + CJS + CLI + DTS)
+npm run build
+
+# Type check
+npx tsc --noEmit
+
+# Run tests (110 tests via Vitest)
+npm test
+
+# Watch mode
+npm run dev          # Build
+npm run test:watch   # Tests
+```
+
+### Test Coverage
+
+| Suite | Tests | Covers |
+|---|---|---|
+| `config.test.ts` | 13 | Config resolution (constructor, env, file) |
+| `errors.test.ts` | 18 | Error hierarchy, factory, serialization |
+| `lane.test.ts` | 6 | Lane class initialization, resource accessors |
+| `lane.phase.test.ts` | 7 | Phase-specific resource availability |
+| `signature.test.ts` | 11 | HMAC signing, webhook verification |
+| `token-store.test.ts` | 8 | File credential storage, permissions |
+| `card-types.test.ts` | 13 | Card brand detection, Luhn check, masking |
+| `collect.test.ts` | 10 | VGS Collect form generation |
+| `token.test.ts` | 4 | VGS token management |
+| `engine.test.ts` | 9 | Payment routing decisions, budget enforcement |
+| `tool.test.ts` | 4 | MCP tool execution, error formatting |
+| `registry.test.ts` | 7 | PSP adapter registration, failover |
+
+## License
+
+MIT