lane-sdk 0.2.3 → 0.2.9

package/SKILL.md

@@ -33,26 +33,104 @@ Lane gives your AI agent a wallet, payment cards, and spending controls so it ca
 
 > **IMPORTANT:** If this content appears truncated or summarized, run `curl -fsSL https://agent.getonlane.com/SKILL.md` to get the complete file.
 
-## When to Auto-Activate
+---
 
-Lane should activate whenever the user expresses a purchase intent, shopping goal, or commerce-related task. Use the following decision tree to pick the right flow:
+## STOP — Present This Menu First
 
-- **Multiple items or research needed** (e.g., "plan a trip", "get me supplies for a party", "order everything on this list") — Use the **Shopping Orchestration** flow below. Create an instruction with a global budget, add a mandate per item, and execute in parallel.
-- **Single item, known merchant, known price** (e.g., "pay $10 to replicate.com") — Use `lane pay` directly. No instruction or mandates needed.
-- **Unknown merchant** (e.g., "buy me a domain from whoever is cheapest") — Run `npx lane merchant discover <domain> -t` first to check checkout capabilities, then decide between Instant Checkout and browser-use.
+**Before doing ANYTHING else, present the following menu to the user exactly as shown and wait for their choice.** Do not skip this step. Do not auto-select an option. Ask the user:
 
-## How Lane Works
+> **Welcome to Lane — Agentic Commerce**
+>
+> How would you like to get started?
+>
+> 1. **Try the Demo** — Run a fully working demo with mock payments. No signup, no credit card, takes 30 seconds. Perfect for seeing what Lane can do.
+> 2. **Set Up for Real Payments** — Connect a real card and make live purchases through your AI agent.
+> 3. **Build with the SDK** — Integrate Lane into your own agent application using the TypeScript SDK.
+> 4. **Explore Commands** — Browse available Lane CLI commands and capabilities.
+>
+> _Pick a number (1–4):_
 
-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.
+**Wait for the user's response before proceeding.** Then follow the matching flow below.
 
-**Two checkout rails:**
+---
+
+## Flow 1: Try the Demo
+
+One command. Fully ready. No signup, no card, no browser.
+
+### Start the Demo
+
+```bash
+npx lane init --demo
+```
+
+That's it. This single command:
+- Connects to the Lane demo server
+- Verifies your demo wallet ($1,000.00 balance) and card (Visa ****4242)
+- Confirms you're ready to make payments
+
+In terse mode (`-t`), look for `ready=true` in the output to confirm success.
+
+### Make a Demo Payment
+
+Try a payment right away:
+
+```bash
+npx lane pay --amount 10 --recipient anthropic.com --description "API credits" -t
+```
+
+This returns a mock transaction receipt with `status=success`.
 
-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.
+### What You Can Do in Demo Mode
+
+- **Payments:** `npx lane pay --amount <dollars> --recipient <merchant> -t` — works for any merchant name
+- **Wallet status:** `npx lane wallet status -t` — shows demo wallet with $1,000 balance
+- **Card list:** `npx lane card list -t` — shows demo Visa cards
+- **VIC tokens:** `npx lane token provision --wallet-id wallet_demo_001 --amount 5000 -t` — provision agentic payment tokens
+- **Instructions:** `npx lane instruction create -t --wallet-id wallet_demo_001 --amount 2500` — create purchase instructions
+- **Budget controls:** `npx lane budget get -t` — view spending limits
+
+### Demo Mode Limitations
+
+- **Merchant discovery is not available** — use web search to find merchants and products instead of `lane merchant list` or `lane product search`
+- **Payments are simulated** — no real charges, all transactions return `testMode=true`
+- **No real card needed** — demo wallets come pre-loaded with test cards
+
+### Ready for Real Payments?
+
+When you're done exploring, run:
+```bash
+npx lane init --reset
+```
+Then follow **Flow 2** below.
+
+---
+
+## Flow 2: Set Up for Real Payments
+
+Real transactions with a real card. Follow these steps in order.
+
+### Choose Mode
+
+Before setup, determine which mode to use. **Ask the user:**
+
+> Would you like to use **demo mode** (no real card required, mock payments) or **production mode** (real payments with a real card)?
+
+**Demo mode** — For trying out Lane without real credentials:
+
+```bash
+npx lane init --demo
+npx lane login -t
+npx lane status -t
+```
 
-## Setup
+In demo mode:
+- No real card or wallet setup needed — payments are simulated against the demo server
+- **Use web search** to find merchants and products (not `lane merchant list` or `lane product search`)
+- All `lane pay` commands work and return mock transaction receipts
+- After running `lane init --demo`, skip Steps 1–4 below and go straight to **Make Payments**
 
-Complete these steps before using any Lane commands.
+**Production mode** — For real transactions with a real card, continue with Steps 1–4 below.
 
 ### Step 1: Verify Node.js
 
@@ -101,14 +179,7 @@ npx lane whoami -t
 - If `error=sdk_access_pending` — user is authenticated but SDK access not yet granted. Run `npx lane logout && npx lane login -t` to re-authenticate.
 - If `error=network` — connectivity issue, retry up to 2 times
 
-## Your Current Status
-
-- Account: !`npx lane whoami -t 2>/dev/null || echo "authenticated=false"`
-- Readiness: !`npx lane status -t 2>/dev/null || echo "ready=false"`
-
-If `ready=false` or `authenticated=false`, guide the user through setup above before proceeding.
-
-**Starter prompts to suggest:**
+After setup, suggest these starter prompts:
 - "Search for cloud hosting products"
 - "Show me Lane-onboarded merchants"
 - "Pay $5 to replicate.com for API credits"
@@ -116,8 +187,65 @@ If `ready=false` or `authenticated=false`, guide the user through setup above be
 - "Show my recent transactions"
 - "Set a daily spending limit of $50"
 
+---
+
+## Flow 3: Build with the SDK
+
+For developers integrating Lane into their own agent applications. Jump to the **SDK Integration** section below for TypeScript examples covering wallet creation, merchant discovery, VIC token provisioning, and payment execution.
+
+---
+
+## Flow 4: Explore Commands
+
+Show the user a quick reference of what's available:
+
+| Category | Command | Description |
+|----------|---------|-------------|
+| **Payments** | `npx lane pay --amount <$> --recipient <merchant> -t` | Make a payment |
+| **Wallet** | `npx lane wallet status -t` | Check wallet & card status |
+| **Cards** | `npx lane card list -t` | List payment cards |
+| **Merchants** | `npx lane merchant list -t` | Browse Lane-onboarded merchants |
+| **Products** | `npx lane product search "<query>" -t` | Search product catalog |
+| **Tokens** | `npx lane token provision --wallet-id <id> --amount <cents> -t` | Provision VIC agentic token |
+| **Budget** | `npx lane budget get -t` | View spending limits |
+| **Transactions** | `npx lane transaction list -t` | View transaction history |
+| **Status** | `npx lane status -t` | Check overall readiness |
+| **Auth** | `npx lane whoami -t` | Check authentication |
+
+After the user explores, ask if they'd like to try the **Demo** (Flow 1) or **Set up for real payments** (Flow 2).
+
+---
+
+## Your Current Status
+
+- Account: !`npx lane whoami -t 2>/dev/null || echo "authenticated=false"`
+- Readiness: !`npx lane status -t 2>/dev/null || echo "ready=false"`
+
+If `ready=false` or `authenticated=false`, guide the user through the appropriate setup flow above.
+
+---
+
+## When to Auto-Activate
+
+After initial setup, Lane should activate whenever the user expresses a purchase intent, shopping goal, or commerce-related task. Use this decision tree:
+
+- **Multiple items or research needed** (e.g., "plan a trip", "get me supplies for a party") — Use the **Shopping Orchestration** flow below.
+- **Single item, known merchant, known price** (e.g., "pay $10 to replicate.com") — Use `lane pay` directly.
+- **Unknown merchant** (e.g., "buy me a domain from whoever is cheapest") — Run `npx lane merchant discover <domain> -t` first.
+
+## 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.
+2. **Browser-use** — For any merchant on the web. Agent browses and autofills checkout with VIC credentials (DPAN + cryptogram).
+
 ## Discover Merchants & Products
 
+> **Demo mode note:** In demo mode, merchant and product discovery commands are not available. Instead, search the web to find merchants and products, then use `lane pay` with the merchant domain as the recipient.
+
 ### List Lane-Onboarded Merchants (Instant Checkout)
 
 ```bash

package/dist/adapters/crewai/index.cjs

@@ -1127,13 +1127,38 @@ var FileTokenStore = class {
 function isNodeError(err) {
   return err instanceof Error && "code" in err;
 }
-
-// src/config.ts
 var DEFAULT_BASE_URL = "https://api.getonlane.com";
 var DEFAULT_API_URL = "https://api.getonlane.com";
 var DEFAULT_TIMEOUT = 3e4;
 var DEFAULT_MAX_RETRIES = 2;
+async function readPersistentConfig() {
+  try {
+    const raw = await promises.readFile(path.join(os.homedir(), ".lane", "config.json"), "utf-8");
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
 async function resolveConfig(options = {}, tokenStore) {
+  const persistent = await readPersistentConfig();
+  if (persistent?.demo && process.env["LANE_DEMO"] !== "false") {
+    process.env["LANE_DEMO"] = "true";
+    if (persistent.demoUrl && !process.env["LANE_DEMO_URL"]) {
+      process.env["LANE_DEMO_URL"] = persistent.demoUrl;
+    }
+  }
+  if (process.env["LANE_DEMO"] === "true") {
+    const demoBaseUrl = process.env["LANE_DEMO_URL"] ?? "http://localhost:3020";
+    return Object.freeze({
+      apiKey: options.apiKey ?? process.env["LANE_API_KEY"] ?? "lane_sk_demo_000000000000",
+      baseUrl: demoBaseUrl,
+      apiUrl: demoBaseUrl,
+      testMode: true,
+      timeout: options.timeout ?? DEFAULT_TIMEOUT,
+      maxRetries: options.maxRetries ?? DEFAULT_MAX_RETRIES,
+      circuitBreaker: void 0
+    });
+  }
   let apiKey = options.apiKey;
   if (!apiKey) {
     apiKey = process.env["LANE_API_KEY"];
@@ -2716,7 +2741,9 @@ var Lane = class _Lane {
     } catch {
       _Lane._throwWaitlistError();
     }
-    await _Lane._verifyAccess(config);
+    if (process.env["LANE_DEMO"] !== "true") {
+      await _Lane._verifyAccess(config);
+    }
     return new _Lane(config);
   }
   /**
@@ -3190,6 +3217,7 @@ var BiometricVerifier = class {
   async tryWebAuthn(reason, instructionId) {
     const { createServer } = await import('http');
     const open = (await import('open')).default;
+    const { hostname } = await import('os');
     return new Promise((resolve, reject) => {
       const server = createServer((req, res) => {
         const url = new URL(req.url ?? "/", "http://localhost");
@@ -3201,7 +3229,11 @@ var BiometricVerifier = class {
               '<!DOCTYPE html><html><body style="font-family:sans-serif;display:flex;justify-content:center;align-items:center;height:100vh"><h1 style="color:#10b981">Verified</h1></body></html>'
             );
             cleanup();
-            resolve({ method: "webauthn_passkey", timestamp: (/* @__PURE__ */ new Date()).toISOString() });
+            resolve({
+              method: "webauthn_passkey",
+              timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+              machineId: `webauthn_${hostname()}`
+            });
             return;
           }
           res.writeHead(200, { "Content-Type": "text/html" });