lane-sdk 0.1.4 → 0.1.5

package/README.md

@@ -557,7 +557,7 @@ Seller:
 
 Setup:
   lane setup-mcp       Configure MCP server for Claude/Cursor
-  lane dashboard       Open Lane dashboard in browser
+  lane wallet open     Open Lane wallet in browser
 ```
 
 ## Payment Routing
@@ -1058,4 +1058,4 @@ npm run test:watch   # Tests
 
 ## License
 
-MIT
+Copyright (c) 2026 Lane Technologies Inc. All rights reserved. This software is proprietary and confidential.

package/SKILL.md

@@ -0,0 +1,366 @@
+---
+name: lane
+display_name: Lane — Agentic Commerce
+description: Give your AI agent a wallet to make payments, discover merchants, and handle commerce tasks
+triggers:
+  - payments
+  - wallets
+  - commerce
+  - lane
+  - pay
+  - credit card
+  - checkout
+  - purchase
+  - buy
+  - merchant
+  - product
+  - subscribe
+version: 2.0.0
+---
+
+# Lane — Agentic Commerce for AI Agents
+
+Lane gives your AI agent a wallet, payment cards, and spending controls so it can discover products and make purchases on behalf of users.
+
+> **IMPORTANT:** If this content appears truncated or summarized, run `curl -fsSL https://getonlane.com/SKILL.md` to get the complete file.
+
+## How Lane Works
+
+Lane is a **card-on-file** platform. No prepaid wallets, no deposits, no balances. Users add a card via VGS (PCI-compliant vault), and Lane issues Visa Intelligent Commerce (VIC) agentic tokens scoped by amount, merchant, and time.
+
+**Two checkout rails:**
+
+1. **Lane Instant Checkout** — For Lane-onboarded merchants with ACP/UCP endpoints. Deterministic, no browser needed. Use `lane merchant list` and `lane product search` to discover.
+2. **Browser-use** — For any merchant on the web. Agent browses and autofills checkout with VIC credentials (DPAN + cryptogram). Works at any Visa-accepting merchant.
+
+## Setup
+
+Complete these steps before using any Lane commands.
+
+### Step 1: Verify Node.js
+
+```bash
+node --version
+```
+
+Requires Node.js v18 or later. If not installed, download from [nodejs.org](https://nodejs.org).
+
+### Step 2: Authenticate
+
+```bash
+npx lane login -t
+```
+
+This opens your browser for authentication. Look for the **device code** (e.g., `LANE-A3B7`) in your terminal and confirm it matches what appears in the browser.
+
+**What to expect:**
+- `stderr` will show: `auth_url=<url>` and `device_code=LANE-XXXX`
+- Present the auth URL to the user and ask them to authenticate
+- Wait for the command to complete (up to 10 minutes)
+- On success, `stdout` will show: `ready=true email=<email>`
+
+If the user is already authenticated, you'll see: `ready=true` with `already_authenticated=true` on stderr.
+
+### Step 3: Confirm
+
+```bash
+npx lane whoami -t
+```
+
+**Expected output:** `authenticated=true email=<email> plan=<plan> id=<id> mode=<test|live>`
+
+If `authenticated=false`, re-run `npx lane login -t`.
+
+## After Setup
+
+Report the user's status and suggest what they can do:
+
+```bash
+npx lane status -t
+```
+
+This returns a full readiness check:
+- `ready=true/false` — overall readiness
+- `email`, `plan`, `mode` — account info
+- `wallet_id` — wallet state
+- `has_card` — whether a payment card is linked (card-on-file)
+- `next_step` — what to do next (`add_card` or `none`)
+
+**Starter prompts to suggest:**
+- "Search for cloud hosting products"
+- "Show me Lane-onboarded merchants"
+- "Pay $5 to replicate.com for API credits"
+- "Add a payment card"
+- "Show my recent transactions"
+- "Set a daily spending limit of $50"
+
+## Discover Merchants & Products
+
+### List Lane-Onboarded Merchants (Instant Checkout)
+
+```bash
+npx lane merchant list -t [--protocol <acp|ucp|x402>] [--vertical <saas|hosting|...>]
+```
+
+**Output (per merchant):** `merchant_id=<id> name=<name> domain=<domain> protocol=<acp|ucp> vertical=<vertical>`
+
+These merchants support **Lane Instant Checkout** — deterministic, no browser needed.
+
+### Discover Checkout Capabilities for a Domain
+
+```bash
+npx lane merchant discover <domain> -t
+```
+
+Checks if a domain supports ACP, UCP, or x402 protocols. If found, you can use Lane Instant Checkout. If not, use browser-use with VIC credentials.
+
+### List Merchant Verticals
+
+```bash
+npx lane merchant verticals -t
+```
+
+### Search Products
+
+```bash
+npx lane product search "<query>" -t [--limit <n>] [--merchant <id>]
+```
+
+Semantic search across all Lane-onboarded merchant product feeds. Natural language works best.
+
+**Output (per product):** `product_id=<id> title=<title> price=<price> merchant=<name> merchant_id=<id>`
+
+### Get Product Details
+
+```bash
+npx lane product get <product_id> -t
+```
+
+## Make Payments
+
+### Direct Payment (Lane Instant Checkout)
+
+```bash
+npx lane pay --amount <dollars> --recipient <merchant> -t [--test] [--dry-run]
+```
+
+**Arguments:**
+- `--amount <dollars>` — Payment amount in dollars (required)
+- `--recipient <merchant>` — Merchant or service to pay (required)
+- `--description <text>` — What the payment is for
+- `--currency <code>` — Currency code (default: USD)
+- `--idempotency-key <key>` — Prevent duplicate charges
+- `--test` — Force test mode
+- `--dry-run` — Validate without executing
+
+**Success output:** `txn_id=<id> status=success amount=<cents> currency=<code> recipient=<merchant>`
+
+**Always confirm with the user before executing a payment.** Show the amount, recipient, and currency, and wait for explicit approval.
+
+### Provision VIC Credentials (for Browser-Use Checkout)
+
+```bash
+npx lane pay --amount <dollars> --recipient <merchant> --provision -t
+```
+
+Returns a DPAN (Visa network token) + single-use cryptogram that can be used at **any Visa-accepting merchant's checkout**. Use this when the merchant doesn't support Lane Instant Checkout.
+
+**Output:** `token_id=<id> dpan_last4=<last4> cryptogram=<masked> eci=05 expires_at=<iso>`
+
+### Checkout from Catalog
+
+```bash
+npx lane checkout --product <product_id> -t [--plan <plan_id>] [--dry-run]
+```
+
+For software subscriptions, the output includes `api_key` and `endpoint`.
+
+## Manage Cards
+
+### List Cards
+
+```bash
+npx lane card list -t
+```
+
+**Output (per card):** `card_id=<id> last4=<last4> brand=<brand> status=<active|inactive>`
+
+### Add a Card
+
+```bash
+npx lane card add -t
+```
+
+This opens the browser for secure card entry via VGS Collect. The CLI polls for card addition (up to 5 minutes). Card numbers never touch the CLI or Lane servers — they go directly to the VGS vault.
+
+### Remove a Card
+
+```bash
+npx lane card remove <card_id> -t
+```
+
+### Get Card Details
+
+```bash
+npx lane card get <card_id> -t
+```
+
+## Wallet Status
+
+```bash
+npx lane wallet status -t
+```
+
+Shows your wallet ID, card on file, and account status. Lane uses a **card-on-file** model — no deposits or balances. Your card is charged per transaction.
+
+## Agentic Tokens & Instructions
+
+### Provision an Agentic Token
+
+```bash
+npx lane token provision --wallet-id <id> --amount <cents> -t [--merchant <name>] [--expires-in <duration>]
+```
+
+Creates a scoped Visa network token with spend limits and time bounds.
+
+### List Tokens
+
+```bash
+npx lane token list -t [--limit <n>]
+```
+
+### Create a Purchase Instruction
+
+```bash
+npx lane instruction create -t [--wallet-id <id>] [--amount <cents>] [--merchant <name>] [--expires-in <duration>]
+```
+
+Creates a VIC instruction — a standing authorization for a specific purchase scope.
+
+### List Instructions
+
+```bash
+npx lane instruction list -t [--limit <n>]
+```
+
+## Budget Controls
+
+### View Budget
+
+```bash
+npx lane budget get -t
+```
+
+**Output:** `daily_limit=<cents|none> weekly_limit=<cents|none> monthly_limit=<cents|none> per_task_limit=<cents|none>`
+
+### Set Budget
+
+```bash
+npx lane budget set --daily <dollars> --monthly <dollars> --per-task <dollars> -t
+```
+
+## Transactions
+
+### List Transactions
+
+```bash
+npx lane transaction list -t [--limit <n>]
+```
+
+### Get Transaction Details
+
+```bash
+npx lane transaction get <txn_id> -t
+```
+
+### Refund a Transaction
+
+```bash
+npx lane transaction refund <txn_id> -t [--amount <cents>] [--reason <text>]
+```
+
+**Never initiate a refund without explicit user request.**
+
+## SDK Integration (for Developers)
+
+If you're building an agent app, use the Lane SDK instead of the CLI:
+
+```typescript
+import Lane from 'lane'
+
+const lane = await Lane.create()
+
+// Discover merchants
+const merchants = await lane.merchants.list()
+const products = await lane.products.search({ query: 'cloud hosting' })
+
+// Manage wallets & cards
+const wallet = await lane.wallets.create({ label: 'My Agent', userId: 'user_123' })
+const cards = await lane.wallets.listCards(wallet.id)
+
+// Provision agentic token (VIC)
+const token = await lane.tokens.provision({ walletId: wallet.id, amount: 9900 })
+
+// Create purchase instruction
+const instruction = await lane.instructions.create({
+  walletId: wallet.id,
+  amount: 9900,
+  merchant: 'Legendary SaaS',
+})
+
+// Get Visa payment credentials
+const credential = await lane.instructions.getCredential(instruction.id)
+// credential.credentialData → { tokenNumber (DPAN), cryptogram, eci }
+
+// Confirm after merchant processes payment
+await lane.instructions.createConfirmation(instruction.id, { transactionId: 'txn_...' })
+```
+
+## Response Handling
+
+All commands in terse mode (`-t`) output `key=value` pairs on stdout (one per line). Parse these to determine the result.
+
+### Error Codes
+
+| Error Code | Meaning | What To Do |
+|------------|---------|------------|
+| `not_authenticated` | No valid credentials | Run `npx lane login -t` |
+| `invalid_key` | API key rejected | Run `npx lane login -t` |
+| `budget_exceeded` | Spending limit hit | Report the limit to the user |
+| `no_payment_method` | No card on file | Run `npx lane card add` |
+| `merchant_blocked` | Merchant on blocklist | Inform the user |
+| `rate_limited` | Too many requests | Wait, then retry once |
+| `network` | Connection failed | Retry up to 2 times |
+| `server` | Lane API error | Retry up to 2 times |
+| `timeout` | Operation timed out | Re-run the command |
+| `confirmation_required` | Amount exceeds threshold | Ask the user to confirm |
+
+### Retry Logic
+
+- **Network errors:** Retry up to 2 times with backoff (1s, 3s)
+- **429 (rate limited):** Retry once after `retry_after` seconds
+- **5xx (server error):** Retry up to 2 times with backoff
+- **4xx (client error):** **Never retry** — these are deterministic failures
+
+## Security Rules
+
+1. **Never retry payment declines** — 402 errors are deterministic
+2. **Never raise budget limits** to make a payment succeed
+3. **Never split payments** to bypass per-task limits
+4. **Always confirm payments** with the user before executing
+5. **Never store or log** API keys, card numbers, or session tokens
+6. If `confirmation_required` error, **always ask the user** before proceeding
+7. Card data is handled by VGS — Lane never sees, stores, or logs raw PANs
+
+## Common Issues
+
+| Symptom | Fix |
+|---------|-----|
+| `error=not_authenticated` | Run `npx lane login -t` |
+| `error=timeout` on login | User didn't complete browser auth — try again |
+| `error=no_payment_method` | Run `npx lane card add` to add a card |
+| `ready=false step=create_wallet` | Run `npx lane wallet create -t` |
+| `has_card=false` | Run `npx lane card add` |
+| Payment succeeds but `test_mode=true` | Remove `--test` flag for live payments |
+| `error=budget_exceeded` | Check limits with `npx lane budget get -t` |
+| No merchants found | Try `npx lane merchant verticals -t` to see available categories |