lane-sdk 0.2.8 → 0.2.9

package/SKILL.md

@@ -33,26 +33,82 @@ 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:
 
-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.
+```bash
+npx lane pay --amount 10 --recipient anthropic.com --description "API credits" -t
+```
+
+This returns a mock transaction receipt with `status=success`.
+
+### 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
 
-## Setup
+### Demo Mode Limitations
 
-Complete these steps before using any Lane commands.
+- **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
 
@@ -123,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"
@@ -138,6 +187,61 @@ 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.

package/dist/cli/index.js

@@ -1,4 +1,6 @@
 #!/usr/bin/env node
+import { createRequire as __createRequire } from "module";
+const require = __createRequire(import.meta.url);
 var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
@@ -12145,6 +12147,7 @@ var init_node_figlet = __esm({
 // src/cli/onboarding.ts
 var onboarding_exports = {};
 __export(onboarding_exports, {
+  showDemoOnboarding: () => showDemoOnboarding,
   showOnboarding: () => showOnboarding
 });
 function sleep2(ms) {
@@ -12201,6 +12204,32 @@ async function showOnboarding(email) {
     console.log(source_default.white('  Welcome to Lane. Try: lane product search "headphones"'));
   }
 }
+async function showDemoOnboarding() {
+  const env2 = detectEnvironment();
+  const tier = getTier(env2);
+  const success3 = source_default.hex("#22C55E");
+  if (tier === 1 && env2.isTTY) {
+    console.log(brand("  \u2554\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2557"));
+    console.log(brand("  \u2551") + source_default.white("                                      ") + brand("\u2551"));
+    console.log(brand("  \u2551") + "   " + success3("\u2713") + source_default.white(" Demo server connected".padEnd(33)) + brand("\u2551"));
+    console.log(brand("  \u2551") + "   " + success3("\u2713") + source_default.white(" Wallet: $1,000.00 balance".padEnd(33)) + brand("\u2551"));
+    console.log(brand("  \u2551") + "   " + success3("\u2713") + source_default.white(" Card: Visa ****4242".padEnd(33)) + brand("\u2551"));
+    console.log(brand("  \u2551") + "   " + success3("\u2713") + source_default.white(" Ready to make payments".padEnd(33)) + brand("\u2551"));
+    console.log(brand("  \u2551") + source_default.white("                                      ") + brand("\u2551"));
+    console.log(brand("  \u255A\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u255D"));
+    console.log();
+    console.log(laneBold.primary("  Try these:"));
+    console.log(source_default.white("  lane pay --amount 10 --recipient anthropic.com -t"));
+    console.log(source_default.white("  lane wallet status"));
+    console.log(source_default.white("  lane card list"));
+    console.log(source_default.white("  lane budget get"));
+    console.log();
+  } else {
+    console.log(success3("  \u2713 Demo ready \u2014 wallet $1,000, card Visa ****4242"));
+    console.log(source_default.white("  Try: lane pay --amount 10 --recipient anthropic.com -t"));
+    console.log();
+  }
+}
 var brand, muted, THEN_DIAGRAM, NOW_DIAGRAM, FUTURE_DIAGRAM, PHASES;
 var init_onboarding = __esm({
   "src/cli/onboarding.ts"() {
@@ -28245,6 +28274,7 @@ init_token_store();
 
 // src/cli/commands/init.ts
 init_source();
+init_lane();
 import { readFile as readFile4, writeFile as writeFile2, mkdir as mkdir2, unlink } from "fs/promises";
 import { join as join4 } from "path";
 import { homedir as homedir3 } from "os";
@@ -28283,8 +28313,8 @@ var initCommand = new Command("init").description("Initialize Lane CLI configura
 `));
     return;
   }
-  if (options.demo) {
-    const demoUrl = options.url ?? DEFAULT_DEMO_URL;
+  if (options.demo || globalOpts.demo) {
+    const demoUrl = options.url ?? globalOpts.url ?? DEFAULT_DEMO_URL;
     const spinner = await createSpinner("Checking demo server...", outputOpts);
     let healthy = false;
     try {
@@ -28303,12 +28333,33 @@ var initCommand = new Command("init").description("Initialize Lane CLI configura
     await writePersistentConfig({ demo: true, demoUrl });
     process.env["LANE_DEMO"] = "true";
     process.env["LANE_DEMO_URL"] = demoUrl;
+    let readyStatus = { email: "demo@getonlane.com", walletId: "wallet_demo_001", hasCard: true };
+    if (healthy) {
+      try {
+        const lane6 = await Lane.create();
+        const profile = await lane6.auth.whoami();
+        const wallets = await lane6.wallets.list({ limit: 1 });
+        const cards = await lane6.cards.list();
+        readyStatus = {
+          email: profile.email,
+          walletId: wallets.data[0]?.id ?? "wallet_demo_001",
+          hasCard: cards.data.length > 0
+        };
+      } catch {
+      }
+    }
     if (terse2) {
       terseOut({
         demo: true,
         demo_url: demoUrl,
         config_path: CONFIG_FILE,
-        server_healthy: healthy
+        server_healthy: healthy,
+        ready: true,
+        email: readyStatus.email,
+        wallet_id: readyStatus.walletId,
+        has_card: readyStatus.hasCard,
+        mode: "test",
+        next_step: "make_payment"
       });
       return;
     }
@@ -28322,9 +28373,8 @@ var initCommand = new Command("init").description("Initialize Lane CLI configura
       console.log(source_default.dim(`    Start locally: npm run dev:vic-demo`));
       console.log();
     }
-    console.log(laneBold.primary("  Try:  ") + source_default.white("lane status"));
-    console.log(lane.info("  Reset: lane init --reset"));
-    console.log();
+    const { showDemoOnboarding: showDemoOnboarding2 } = await Promise.resolve().then(() => (init_onboarding(), onboarding_exports));
+    await showDemoOnboarding2();
     return;
   }
   cmd.help();