z-zero-mcp-server 1.0.3 → 1.0.4

package/README.md

@@ -1,53 +1,80 @@
-# Z-ZERO: AI Virtual Card MCP Server
+# OpenClaw: Z-ZERO AI Agent MCP Server
 
-A Zero-Trust Payment Protocol built specifically for AI Agents utilizing the Model Context Protocol (MCP).
+A Zero-Trust Payment Protocol built specifically for AI Agents utilizing the Model Context Protocol (MCP). Use this to give your local agents (Claude, Cursor, AutoGPT) the power to make real-world purchases securely.
 
 ## The Concept (Tokenized JIT Payments)
 This MCP server acts as an "Invisible Bridge" for your AI Agents. Instead of giving your LLM direct access to a 16-digit credit card number (which triggers safety filters and risks prompt injection theft), the AI only handles **temporary, single-use tokens**.
 
-The local MCP client resolves the token securely in RAM, injects the real card data directly into the payment form (via Playwright headless browser), and clicks "Pay". The virtual card and token are burned milliseconds later.
-
-## Features
-- **Zero PII (Blind Execution):** AI never sees card numbers.
-- **Exact-Match Funding:** Tokens are tied to virtual cards locked to the exact requested amount.
-- **Phantom Burn:** Single-use architecture. Cards self-destruct after checking out.
-- **Stripe/HTML Form Injection:** Automatically fills common checkout domains.
-
-## Documentation
-Check the `docs/` folder for complete system design and architecture:
-- [Product Plan & Core Concept](docs/ai_card_product_plan.md)
-- [MCP Implementation Plan](docs/implementation_plan.md)
-- [Mock Backend Architecture](docs/backend_architecture.md)
-- [Live Demo Walkthrough & Test Results](docs/walkthrough.md)
+The local MCP client resolves the token securely in RAM, injects the real card data directly into the payment form (via Playwright), and clicks "Pay". The virtual card and token are burned milliseconds later.
 
 ## Getting Started
 
-### 1. Install Dependencies
+### 1. Requirements
+- **Node.js** (v18+)
+- **Git**
+- **Z-ZERO Passport Key** (Get yours at [clawcard.store/dashboard/agents](https://clawcard.store/dashboard/agents))
+
+### 2. Installation
 ```bash
+git clone https://github.com/openclaw/z-zero-mcp-server.git
+cd z-zero-mcp-server
 npm install
 npx playwright install chromium
-```
-
-### 2. Build the Server
-```bash
 npm run build
 ```
 
-### 3. Usage with Claude Desktop
-Add this to your `mcp_config.json`:
+### 3. Integration into AI Tools
+
+#### Claude Desktop
+Add the following to your `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
 ```json
 {
   "mcpServers": {
-    "ai-card-mcp": {
+    "openclaw": {
       "command": "node",
-      "args": ["/absolute/path/to/ai-card-mcp/dist/index.js"]
+      "args": ["/ABSOLUTE/PATH/TO/z-zero-mcp-server/dist/index.js"],
+      "env": {
+        "Z_ZERO_API_KEY": "your_passport_key_here",
+        "Z_ZERO_API_BASE_URL": "https://clawcard.store"
+      }
     }
   }
 }
 ```
 
-## Available MCP Tools
-- `list_cards`: View available virtual cards and balances.
+#### Cursor / IDEs
+1. Go to **Settings** > **Cursor Settings** > **Features** > **MCP**.
+2. Click **+ Add New MCP Server**.
+3. Name: `openclaw`
+4. Type: `command`
+5. Command: `env Z_ZERO_API_KEY=your_passport_key_here node /ABSOLUTE/PATH/TO/z-zero-mcp-server/dist/index.js`
+
+## Available Tools
+- `list_cards`: View available virtual card aliases and balances.
 - `check_balance`: Query a specific card's real-time balance.
-- `request_payment_token`: Generate a JIT auth token locked to a specific amount.
-- `execute_payment`: Passes the token to the Playwright bridge to auto-fill the checkout URL and burn the token.
+- `request_payment_token`: Generate a JIT auth token for a specific amount.
+- `execute_payment`: Securely auto-fills checkout URLs and executes the payment.
+- `get_deposit_addresses`: Get your unique addresses to top up your balance.
+
+## Troubleshooting
+
+### Error: "Z_ZERO_API_KEY is missing"
+If your AI Agent reports this error, it means the `Z_ZERO_API_KEY` environment variable is not set correctly in your MCP configuration.
+1.  Go to [clawcard.store/dashboard/agents](https://clawcard.store/dashboard/agents).
+2.  Generate or Copy your **Passport Key** (starts with `zk_live_`).
+3.  Ensure it is correctly pasted into your `claude_desktop_config.json` or your IDE's MCP settings.
+4.  **Restart** your AI Agent (Claude Desktop or IDE) for the changes to take effect.
+
+---
+
+## Troubleshooting
+
+### Error: "Z_ZERO_API_KEY is missing"
+This error means your AI Agent (Claude/Cursor) doesn't have your **Passport Key** yet. 
+1. Go to [clawcard.store/dashboard/agents](https://clawcard.store/dashboard/agents).
+2. Copy your **Passport Key** (starts with `zk_live_`).
+3. Add it to your config (e.g., `claude_desktop_config.json`) as `Z_ZERO_API_KEY`.
+4. **Restart** your AI Agent (Claude Desktop or IDE).
+
+*Security Note: OpenClaw never stores your Passport Key. It is passed via environment variables and card data exists only in RAM during execution.*

package/dist/api_backend.d.ts

@@ -1,22 +1,9 @@
 import type { CardData } from "./types.js";
-export declare function listCardsRemote(): Promise<Array<{
-    alias: string;
-    balance: number;
-    currency: string;
-}>>;
-export declare function getBalanceRemote(cardAlias: string): Promise<{
-    balance: number;
-    currency: string;
-} | null>;
-export declare function getDepositAddressesRemote(): Promise<{
-    evm: string;
-    tron: string;
-} | null>;
+export declare function listCardsRemote(): Promise<any>;
+export declare function getBalanceRemote(cardAlias: string): Promise<any>;
+export declare function getDepositAddressesRemote(): Promise<any>;
 export declare function issueTokenRemote(cardAlias: string, amount: number, merchant: string): Promise<any | null>;
 export declare function resolveTokenRemote(token: string): Promise<CardData | null>;
 export declare function burnTokenRemote(token: string, receipt_id?: string): Promise<boolean>;
-export declare function cancelTokenRemote(token: string): Promise<{
-    success: boolean;
-    refunded_amount: number;
-}>;
+export declare function cancelTokenRemote(token: string): Promise<any>;
 export declare function refundUnderspendRemote(token: string, actualSpent: number): Promise<void>;

package/dist/api_backend.js

@@ -14,9 +14,14 @@ exports.refundUnderspendRemote = refundUnderspendRemote;
 const API_BASE_URL = process.env.Z_ZERO_API_BASE_URL || "https://clawcard.store";
 const PASSPORT_KEY = process.env.Z_ZERO_API_KEY || "";
 if (!PASSPORT_KEY) {
-    console.error("❌ Missing Z_ZERO_API_KEY (Your Passport) in environment variables.");
+    console.error("❌ ERROR: Z_ZERO_API_KEY (Passport Key) is missing!");
+    console.error("🔐 Please get your Passport Key from: https://clawcard.store/dashboard/agents");
+    console.error("🛠️ Setup: Ensure 'Z_ZERO_API_KEY' is set in your environment variables.");
 }
 async function apiRequest(endpoint, method = 'GET', body = null) {
+    if (!PASSPORT_KEY) {
+        return { error: "AUTH_REQUIRED", message: "Z_ZERO_API_KEY is missing. Human needs to set it in MCP config." };
+    }
     const url = `${API_BASE_URL.replace(/\/$/, '')}${endpoint}`;
     try {
         const res = await fetch(url, {
@@ -30,29 +35,30 @@ async function apiRequest(endpoint, method = 'GET', body = null) {
         if (!res.ok) {
             const err = await res.json().catch(() => ({ error: res.statusText }));
             console.error(`[API ERROR] ${endpoint}:`, err.error);
-            return null;
+            return { error: "API_ERROR", message: err.error || res.statusText };
         }
         return await res.json();
     }
     catch (err) {
         console.error(`[NETWORK ERROR] ${endpoint}:`, err.message);
-        return null;
+        return { error: "NETWORK_ERROR", message: err.message };
     }
 }
 async function listCardsRemote() {
-    const data = await apiRequest('/api/tokens/cards', 'GET');
-    return data?.cards || [];
+    return await apiRequest('/api/tokens/cards', 'GET');
 }
 async function getBalanceRemote(cardAlias) {
-    const cards = await listCardsRemote();
-    const card = cards.find(c => c.alias === cardAlias);
+    const data = await listCardsRemote();
+    if (data?.error)
+        return data;
+    const cards = data?.cards || [];
+    const card = cards.find((c) => c.alias === cardAlias);
     if (!card)
         return null;
     return { balance: card.balance, currency: card.currency };
 }
 async function getDepositAddressesRemote() {
-    const data = await apiRequest('/api/tokens/cards', 'GET');
-    return data?.deposit_addresses || null;
+    return await apiRequest('/api/tokens/cards', 'GET');
 }
 async function issueTokenRemote(cardAlias, amount, merchant) {
     const data = await apiRequest('/api/tokens/issue', 'POST', {
@@ -98,6 +104,8 @@ async function burnTokenRemote(token, receipt_id) {
 }
 async function cancelTokenRemote(token) {
     const data = await apiRequest('/api/tokens/cancel', 'POST', { token });
+    if (data?.error)
+        return data;
     return {
         success: !!data,
         refunded_amount: data?.refunded_amount || 0

package/dist/index.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 "use strict";
-// Z-ZERO MCP Server (z-zero-mcp-server) v1.0.2
+// OpenClaw MCP Server (z-zero-mcp-server) v1.0.3
 // Exposes secure JIT payment tools to AI Agents via Model Context Protocol
-// Now connected to REAL Airwallex Issuing API — produces real Mastercards
+// Status: Connected to Z-ZERO Gateway — produces secure JIT virtual cards
 Object.defineProperty(exports, "__esModule", { value: true });
 const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
 const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
@@ -14,13 +14,25 @@ const playwright_bridge_js_1 = require("./playwright_bridge.js");
 // ============================================================
 const server = new mcp_js_1.McpServer({
     name: "z-zero-mcp-server",
-    version: "1.0.2",
+    version: "1.0.3",
 });
 // ============================================================
 // TOOL 1: List available cards (safe - no sensitive data)
 // ============================================================
 server.tool("list_cards", "List all available virtual card aliases and their balances. No sensitive data is returned.", {}, async () => {
-    const cards = await (0, api_backend_js_1.listCardsRemote)();
+    const data = await (0, api_backend_js_1.listCardsRemote)();
+    if (data?.error === "AUTH_REQUIRED") {
+        return {
+            content: [{
+                    type: "text",
+                    text: "❌ AUTHENTICATION REQUIRED: Your Z_ZERO_API_KEY (Passport Key) is missing from the MCP configuration.\n\n" +
+                        "👉 Please GET your key here: https://clawcard.store/dashboard/agents\n" +
+                        "👉 Then SET it as the 'Z_ZERO_API_KEY' environment variable in your AI tool (Claude Desktop/Cursor) and RESTART the tool."
+                }],
+            isError: true
+        };
+    }
+    const cards = data?.cards || [];
     return {
         content: [
             {
@@ -41,13 +53,24 @@ server.tool("check_balance", "Check the remaining balance of a virtual card by i
         .string()
         .describe("The alias of the card to check, e.g. 'Card_01'"),
 }, async ({ card_alias }) => {
-    const balance = await (0, api_backend_js_1.getBalanceRemote)(card_alias);
-    if (!balance) {
+    const data = await (0, api_backend_js_1.getBalanceRemote)(card_alias);
+    if (data?.error === "AUTH_REQUIRED") {
+        return {
+            content: [{
+                    type: "text",
+                    text: "❌ AUTHENTICATION REQUIRED: Your Z_ZERO_API_KEY (Passport Key) is missing from the MCP configuration.\n\n" +
+                        "👉 Please GET your key here: https://clawcard.store/dashboard/agents\n" +
+                        "👉 Then SET it as the 'Z_ZERO_API_KEY' environment variable and RESTART."
+                }],
+            isError: true
+        };
+    }
+    if (!data || data.error) {
         return {
             content: [
                 {
                     type: "text",
-                    text: `Card "${card_alias}" not found or API key is invalid. Use list_cards to see available cards.`,
+                    text: `Card "${card_alias}" not found or API issue. Use list_cards to see available cards.`,
                 },
             ],
             isError: true,
@@ -57,7 +80,7 @@ server.tool("check_balance", "Check the remaining balance of a virtual card by i
         content: [
             {
                 type: "text",
-                text: JSON.stringify({ card_alias, ...balance }, null, 2),
+                text: JSON.stringify({ card_alias, ...data }, null, 2),
             },
         ],
     };
@@ -66,13 +89,25 @@ server.tool("check_balance", "Check the remaining balance of a virtual card by i
 // TOOL 2.5: Get deposit addresses (Phase 14 feature)
 // ============================================================
 server.tool("get_deposit_addresses", "Get your unique deposit addresses for EVM networks (Base, BSC, Ethereum) and Tron. Provide these to the human user when they need to add funds to their Z-ZERO balance.", {}, async () => {
-    const addresses = await (0, api_backend_js_1.getDepositAddressesRemote)();
+    const data = await (0, api_backend_js_1.getDepositAddressesRemote)();
+    if (data?.error === "AUTH_REQUIRED") {
+        return {
+            content: [{
+                    type: "text",
+                    text: "❌ AUTHENTICATION REQUIRED: Your Z_ZERO_API_KEY (Passport Key) is missing from the MCP configuration.\n\n" +
+                        "👉 Please GET your key here: https://clawcard.store/dashboard/agents\n" +
+                        "👉 Then SET it as the 'Z_ZERO_API_KEY' environment variable and RESTART."
+                }],
+            isError: true
+        };
+    }
+    const addresses = data?.deposit_addresses;
     if (!addresses) {
         return {
             content: [
                 {
                     type: "text",
-                    text: "Failed to retrieve deposit addresses. Please ensure your API key (passport) is valid.",
+                    text: "Failed to retrieve deposit addresses. Please ensure your Z_ZERO_API_KEY (Passport Key) is valid. You can find it at https://clawcard.store/dashboard/agents",
                 },
             ],
             isError: true,
@@ -102,9 +137,9 @@ server.tool("get_deposit_addresses", "Get your unique deposit addresses for EVM
     };
 });
 // ============================================================
-// TOOL 3: Request a temporary payment token (issues real JIT card)
+// TOOL 3: Request a temporary payment token (issues secure JIT card)
 // ============================================================
-server.tool("request_payment_token", "Request a temporary payment token for a specific amount. A real single-use virtual Mastercard is issued via Airwallex. The token is valid for 30 minutes. Min: $1, Max: $100. Use this token with execute_payment to complete a purchase.", {
+server.tool("request_payment_token", "Request a temporary payment token for a specific amount. A secure single-use virtual card is issued via the Z-ZERO network. The token is valid for 30 minutes. Min: $1, Max: $100. Use this token with execute_payment to complete a purchase.", {
     card_alias: zod_1.z
         .string()
         .describe("Which card to charge, e.g. 'Card_01'"),
@@ -118,15 +153,26 @@ server.tool("request_payment_token", "Request a temporary payment token for a sp
         .describe("Name or URL of the merchant/service being purchased"),
 }, async ({ card_alias, amount, merchant }) => {
     const token = await (0, api_backend_js_1.issueTokenRemote)(card_alias, amount, merchant);
-    if (!token) {
-        const balance = await (0, api_backend_js_1.getBalanceRemote)(card_alias);
+    if (token?.error === "AUTH_REQUIRED") {
+        return {
+            content: [{
+                    type: "text",
+                    text: "❌ AUTHENTICATION REQUIRED: Your Z_ZERO_API_KEY (Passport Key) is missing from the MCP configuration.\n\n" +
+                        "👉 Please GET your key here: https://clawcard.store/dashboard/agents"
+                }],
+            isError: true
+        };
+    }
+    if (!token || token.error) {
+        const balanceData = await (0, api_backend_js_1.getBalanceRemote)(card_alias);
+        const balance = balanceData?.balance;
         return {
             content: [
                 {
                     type: "text",
-                    text: balance
-                        ? `Insufficient balance. Card "${card_alias}" has $${balance.balance} but you requested $${amount}. Or amount is outside the $1-$100 limit.`
-                        : `Card "${card_alias}" not found or API key is invalid.`,
+                    text: balance !== undefined
+                        ? `Insufficient balance. Card "${card_alias}" has $${balance} but you requested $${amount}. Or amount is outside the $1-$100 limit.`
+                        : `Card "${card_alias}" not found, API key is invalid, or amount limit exceeded.`,
                 },
             ],
             isError: true,
@@ -142,7 +188,7 @@ server.tool("request_payment_token", "Request a temporary payment token for a sp
                     amount: token.amount,
                     merchant: token.merchant,
                     expires_at: expiresAt,
-                    real_card_issued: !!token.airwallex_card_id,
+                    card_issued: true,
                     instructions: "Use this token with execute_payment within 30 minutes. IMPORTANT: If the actual checkout price is HIGHER than the token amount, do NOT proceed — call cancel_payment_token first and request a new token with the correct amount.",
                 }, null, 2),
             },
@@ -167,7 +213,17 @@ server.tool("execute_payment", "Execute a payment using a temporary token. This
 }, async ({ token, checkout_url, actual_amount }) => {
     // Step 1: Resolve token → card data (RAM only)
     const cardData = await (0, api_backend_js_1.resolveTokenRemote)(token);
-    if (!cardData) {
+    if (cardData?.error === "AUTH_REQUIRED") {
+        return {
+            content: [{
+                    type: "text",
+                    text: "❌ AUTHENTICATION REQUIRED: Your Z_ZERO_API_KEY (Passport Key) is missing from the MCP configuration.\n\n" +
+                        "👉 Please GET your key here: https://clawcard.store/dashboard/agents"
+                }],
+            isError: true
+        };
+    }
+    if (!cardData || cardData.error) {
         return {
             content: [
                 {
@@ -214,7 +270,17 @@ server.tool("cancel_payment_token", "Cancel a payment token that has not been us
         .describe("Reason for cancellation, e.g. 'Price mismatch: checkout shows $20 but token is $15'"),
 }, async ({ token, reason }) => {
     const result = await (0, api_backend_js_1.cancelTokenRemote)(token);
-    if (!result.success) {
+    if (result?.error === "AUTH_REQUIRED") {
+        return {
+            content: [{
+                    type: "text",
+                    text: "❌ AUTHENTICATION REQUIRED: Your Z_ZERO_API_KEY (Passport Key) is missing from the MCP configuration.\n\n" +
+                        "👉 Please GET your key here: https://clawcard.store/dashboard/agents"
+                }],
+            isError: true
+        };
+    }
+    if (!result || !result.success) {
         return {
             content: [
                 {
@@ -337,8 +403,8 @@ When asked to make a purchase, execute the following steps precisely in order:
 async function main() {
     const transport = new stdio_js_1.StdioServerTransport();
     await server.connect(transport);
-    console.error("🔐 Z-ZERO MCP Server v1.0.2 running...");
-    console.error("Backend: Supabase + Airwallex Issuing API (Real JIT Cards)");
+    console.error("🔐 OpenClaw MCP Server v1.0.3 running...");
+    console.error("Status: Secure & Connected to Z-ZERO Gateway");
     console.error("Tools: list_cards, check_balance, request_payment_token, execute_payment, cancel_payment_token, request_human_approval");
 }
 main().catch(console.error);

package/dist/types.d.ts

@@ -7,6 +7,8 @@ export interface VirtualCard {
     name: string;
     balance: number;
     currency: string;
+    error?: string;
+    message?: string;
 }
 export interface PaymentToken {
     token: string;
@@ -16,6 +18,8 @@ export interface PaymentToken {
     created_at: number;
     ttl_seconds: number;
     used: boolean;
+    error?: string;
+    message?: string;
 }
 export interface CardData {
     number: string;
@@ -23,6 +27,8 @@ export interface CardData {
     exp_year: string;
     cvv: string;
     name: string;
+    error?: string;
+    message?: string;
 }
 export interface PaymentResult {
     success: boolean;

package/package.json

@@ -1,13 +1,14 @@
 {
     "name": "z-zero-mcp-server",
-    "version": "1.0.3",
+    "version": "1.0.4",
     "description": "Z-ZERO MCP Server — Secure JIT Virtual Card Payment tools for AI Agents (Claude, AutoGPT, CrewAI) — Real Airwallex Mastercards",
     "main": "dist/index.js",
     "bin": "dist/index.js",
     "scripts": {
         "build": "tsc",
         "start": "node dist/index.js",
-        "dev": "npx tsx src/index.ts"
+        "dev": "npx tsx src/index.ts",
+        "postinstall": "echo 'IMPORTANT: Run \"npx playwright install chromium\" to enable automated checkouts.'"
     },
     "keywords": [
         "mcp",
@@ -28,14 +29,13 @@
     ],
     "dependencies": {
         "@modelcontextprotocol/sdk": "^1.12.1",
-        "@supabase/supabase-js": "^2.49.4",
         "dotenv": "^16.5.0",
         "playwright": "^1.52.0",
         "zod": "^3.25.11"
     },
     "devDependencies": {
-        "typescript": "^5.8.3",
+        "@types/node": "^22.15.21",
         "tsx": "^4.19.4",
-        "@types/node": "^22.15.21"
+        "typescript": "^5.8.3"
     }
 }

package/dist/supabase_backend.d.ts

@@ -1,27 +0,0 @@
-import type { CardData, PaymentToken } from "./types.js";
-interface ExtendedToken extends PaymentToken {
-    airwallex_card_id?: string;
-    cancelled?: boolean;
-}
-export declare function listCardsRemote(): Promise<Array<{
-    alias: string;
-    balance: number;
-    currency: string;
-}>>;
-export declare function getBalanceRemote(cardAlias: string): Promise<{
-    balance: number;
-    currency: string;
-} | null>;
-export declare function getDepositAddressesRemote(): Promise<{
-    evm: string;
-    tron: string;
-} | null>;
-export declare function issueTokenRemote(cardAlias: string, amount: number, merchant: string, ttlSeconds?: number): Promise<ExtendedToken | null>;
-export declare function resolveTokenRemote(tokenId: string): Promise<CardData | null>;
-export declare function cancelTokenRemote(tokenId: string): Promise<{
-    success: boolean;
-    refunded_amount: number;
-}>;
-export declare function burnTokenRemote(tokenId: string): Promise<boolean>;
-export declare function refundUnderspendRemote(tokenId: string, actualSpent: number): Promise<void>;
-export {};

package/dist/supabase_backend.js

@@ -1,353 +0,0 @@
-"use strict";
-// Z-ZERO Supabase Backend v2
-// Connects to real Supabase DB + Airwallex Issuing API for real JIT Mastercards
-// Card data is looked up via Z_ZERO_API_KEY, cards are issued via Airwallex
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.listCardsRemote = listCardsRemote;
-exports.getBalanceRemote = getBalanceRemote;
-exports.getDepositAddressesRemote = getDepositAddressesRemote;
-exports.issueTokenRemote = issueTokenRemote;
-exports.resolveTokenRemote = resolveTokenRemote;
-exports.cancelTokenRemote = cancelTokenRemote;
-exports.burnTokenRemote = burnTokenRemote;
-exports.refundUnderspendRemote = refundUnderspendRemote;
-const supabase_js_1 = require("@supabase/supabase-js");
-const crypto_1 = __importDefault(require("crypto"));
-// ============================================================
-// SUPABASE CLIENT
-// ============================================================
-const SUPABASE_URL = process.env.Z_ZERO_SUPABASE_URL || process.env.NEXT_PUBLIC_SUPABASE_URL || "";
-const SUPABASE_ANON_KEY = process.env.Z_ZERO_SUPABASE_ANON_KEY || process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY || "";
-const API_KEY = process.env.Z_ZERO_API_KEY || "";
-let supabase = null;
-if (SUPABASE_URL && SUPABASE_ANON_KEY) {
-    try {
-        supabase = (0, supabase_js_1.createClient)(SUPABASE_URL, SUPABASE_ANON_KEY);
-    }
-    catch (err) {
-        console.error("Failed to initialize Supabase client:", err);
-    }
-}
-else {
-    console.error("⚠️ Supabase backend is disabled (Missing Z_ZERO_SUPABASE_URL/ANON_KEY).");
-}
-// ============================================================
-// AIRWALLEX CONFIG
-// ============================================================
-const AIRWALLEX_API_KEY = process.env.Z_ZERO_AIRWALLEX_API_KEY || "";
-const AIRWALLEX_CLIENT_ID = process.env.Z_ZERO_AIRWALLEX_CLIENT_ID || "";
-const AIRWALLEX_ENV = process.env.Z_ZERO_AIRWALLEX_ENV || "demo";
-const AIRWALLEX_BASE = AIRWALLEX_ENV === "prod"
-    ? "https://api.airwallex.com/api/v1"
-    : "https://api-demo.airwallex.com/api/v1";
-// Cached auth token for Airwallex (avoids re-login per call)
-let airwallexToken = null;
-let airwallexTokenExpiry = 0;
-async function getAirwallexToken() {
-    if (!AIRWALLEX_API_KEY || !AIRWALLEX_CLIENT_ID)
-        return null;
-    if (airwallexToken && Date.now() < airwallexTokenExpiry)
-        return airwallexToken;
-    try {
-        const res = await fetch(`${AIRWALLEX_BASE}/authentication/login`, {
-            method: "POST",
-            headers: {
-                "x-api-key": AIRWALLEX_API_KEY,
-                "x-client-id": AIRWALLEX_CLIENT_ID,
-                "Content-Type": "application/json",
-            },
-        });
-        if (!res.ok)
-            throw new Error(await res.text());
-        const data = await res.json();
-        airwallexToken = data.token;
-        airwallexTokenExpiry = Date.now() + 25 * 60 * 1000; // 25 min cache
-        return airwallexToken;
-    }
-    catch (err) {
-        console.error("[AIRWALLEX] Auth failed:", err);
-        return null;
-    }
-}
-const tokenStore = new Map();
-// ============================================================
-// RESOLVE API KEY → USER INFO
-// ============================================================
-async function resolveApiKey() {
-    if (!API_KEY)
-        return null;
-    const { data: card, error } = await supabase
-        .from("cards")
-        .select("id, alias, user_id, allocated_limit_usd, is_active")
-        .eq("card_number_encrypted", API_KEY)
-        .eq("is_active", true)
-        .single();
-    if (error || !card) {
-        console.error("API Key not found:", error?.message);
-        return null;
-    }
-    const { data: wallet } = await supabase
-        .from("wallets")
-        .select("balance")
-        .eq("user_id", card.user_id)
-        .single();
-    return {
-        userId: card.user_id,
-        walletBalance: Number(wallet?.balance || 0),
-        cardId: card.id,
-        cardAlias: card.alias,
-    };
-}
-// ============================================================
-// PUBLIC API
-// ============================================================
-async function listCardsRemote() {
-    const info = await resolveApiKey();
-    if (!info)
-        return [];
-    return [{ alias: info.cardAlias, balance: info.walletBalance, currency: "USD" }];
-}
-async function getBalanceRemote(cardAlias) {
-    const info = await resolveApiKey();
-    if (!info || info.cardAlias !== cardAlias)
-        return null;
-    return { balance: info.walletBalance, currency: "USD" };
-}
-async function getDepositAddressesRemote() {
-    const info = await resolveApiKey();
-    if (!info)
-        return null;
-    const { data: wallet, error } = await supabase
-        .from("deposit_wallets")
-        .select("evm_address, tron_address")
-        .eq("user_id", info.userId)
-        .single();
-    if (error || !wallet) {
-        console.error("Deposit wallets not found for user:", info.userId);
-        return null;
-    }
-    return {
-        evm: wallet.evm_address,
-        tron: wallet.tron_address,
-    };
-}
-async function issueTokenRemote(cardAlias, amount, merchant, ttlSeconds = 1800 // 30 minutes default
-) {
-    // 1. Validate business rules
-    if (amount < 1) {
-        console.error("[ISSUE] Card amount must be at least $1.00");
-        return null;
-    }
-    if (amount > 100) {
-        console.error("[ISSUE] Card amount exceeds $100 maximum limit");
-        return null;
-    }
-    // 2. Resolve user from API key
-    const info = await resolveApiKey();
-    if (!info)
-        return null;
-    if (info.cardAlias !== cardAlias)
-        return null;
-    if (info.walletBalance < amount) {
-        console.error(`[ISSUE] Insufficient balance: $${info.walletBalance} < $${amount}`);
-        return null;
-    }
-    const tokenId = `z_jit_${crypto_1.default.randomBytes(8).toString("hex")}`;
-    // 3. Try to create a REAL Airwallex card
-    let airwallexCardId;
-    const airwallexAuth = await getAirwallexToken();
-    if (airwallexAuth) {
-        try {
-            const expiryTime = new Date(Date.now() + 30 * 60 * 1000).toISOString();
-            const payload = {
-                request_id: tokenId,
-                issue_to: "ORGANISATION",
-                name_on_card: "Z-ZERO AI AGENT",
-                form_factor: "VIRTUAL",
-                primary_currency: "USD",
-                valid_to: expiryTime,
-                authorization_controls: {
-                    allowed_transaction_count: "SINGLE",
-                    transaction_limits: {
-                        currency: "USD",
-                        limits: [{ amount, interval: "ALL_TIME" }],
-                    },
-                },
-            };
-            const res = await fetch(`${AIRWALLEX_BASE}/issuing/cards/create`, {
-                method: "POST",
-                headers: {
-                    Authorization: `Bearer ${airwallexAuth}`,
-                    "Content-Type": "application/json",
-                },
-                body: JSON.stringify(payload),
-            });
-            if (res.ok) {
-                const data = await res.json();
-                airwallexCardId = data.card_id;
-                console.error(`[AIRWALLEX] ✅ Real card issued: ${data.card_id} for $${amount}`);
-            }
-            else {
-                const errText = await res.text();
-                console.error("[AIRWALLEX] Card creation failed:", errText);
-                // Fall through — will still create token but without real card ID
-            }
-        }
-        catch (err) {
-            console.error("[AIRWALLEX] Error creating card:", err);
-        }
-    }
-    else {
-        console.error("[AIRWALLEX] No auth token — running in mock mode");
-    }
-    const token = {
-        token: tokenId,
-        card_alias: cardAlias,
-        amount,
-        merchant,
-        created_at: Date.now(),
-        ttl_seconds: ttlSeconds,
-        used: false,
-        cancelled: false,
-        airwallex_card_id: airwallexCardId,
-    };
-    tokenStore.set(tokenId, token);
-    // 4. Pre-hold the amount in Supabase (deduct immediately, refund on cancel or underspend)
-    const newBalance = info.walletBalance - amount;
-    await supabase
-        .from("wallets")
-        .update({ balance: newBalance })
-        .eq("user_id", info.userId);
-    console.error(`[ISSUE] Token ${tokenId} created. Balance: $${info.walletBalance} → $${newBalance}`);
-    return token;
-}
-async function resolveTokenRemote(tokenId) {
-    const token = tokenStore.get(tokenId);
-    if (!token || token.used || token.cancelled)
-        return null;
-    const age = (Date.now() - token.created_at) / 1000;
-    if (age > token.ttl_seconds) {
-        tokenStore.delete(tokenId);
-        return null;
-    }
-    // Try to fetch REAL card details from Airwallex
-    if (token.airwallex_card_id) {
-        const airwallexAuth = await getAirwallexToken();
-        if (airwallexAuth) {
-            try {
-                const res = await fetch(`${AIRWALLEX_BASE}/issuing/cards/${token.airwallex_card_id}`, {
-                    headers: { Authorization: `Bearer ${airwallexAuth}` },
-                });
-                if (res.ok) {
-                    const data = await res.json();
-                    console.error("[AIRWALLEX] ✅ Real card details fetched.");
-                    return {
-                        number: data.card_number || "4242424242424242",
-                        exp_month: data.expiry_month || "12",
-                        exp_year: data.expiry_year || "2030",
-                        cvv: data.cvv || "123",
-                        name: data.name_on_card || "Z-ZERO AI AGENT",
-                    };
-                }
-            }
-            catch (err) {
-                console.error("[AIRWALLEX] Failed to fetch card details:", err);
-            }
-        }
-    }
-    // Fallback to Stripe test card (demo/sandbox mode)
-    console.error("[AIRWALLEX] ⚠️ Using test card fallback (4242...)");
-    return {
-        number: "4242424242424242",
-        exp_month: "12",
-        exp_year: "2030",
-        cvv: "123",
-        name: "Z-ZERO Agent",
-    };
-}
-async function cancelTokenRemote(tokenId) {
-    const token = tokenStore.get(tokenId);
-    if (!token || token.used || token.cancelled) {
-        return { success: false, refunded_amount: 0 };
-    }
-    // Mark token as cancelled in memory
-    token.cancelled = true;
-    // Cancel the Airwallex card (if one was issued)
-    if (token.airwallex_card_id) {
-        const airwallexAuth = await getAirwallexToken();
-        if (airwallexAuth) {
-            try {
-                await fetch(`${AIRWALLEX_BASE}/issuing/cards/${token.airwallex_card_id}/deactivate`, {
-                    method: "POST",
-                    headers: { Authorization: `Bearer ${airwallexAuth}`, "Content-Type": "application/json" },
-                    body: JSON.stringify({ cancellation_reason: "CANCELLED_BY_USER" }),
-                });
-                console.error(`[AIRWALLEX] Card ${token.airwallex_card_id} cancelled.`);
-            }
-            catch (err) {
-                console.error("[AIRWALLEX] Failed to cancel card:", err);
-            }
-        }
-    }
-    // Refund the held amount back to wallet
-    const info = await resolveApiKey();
-    if (info) {
-        const currentBalanceRes = await supabase
-            .from("wallets")
-            .select("balance")
-            .eq("user_id", info.userId)
-            .single();
-        const currentBalance = Number(currentBalanceRes.data?.balance || 0);
-        await supabase
-            .from("wallets")
-            .update({ balance: currentBalance + token.amount })
-            .eq("user_id", info.userId);
-        console.error(`[CANCEL] Refunded $${token.amount}. New balance: $${currentBalance + token.amount}`);
-    }
-    setTimeout(() => tokenStore.delete(tokenId), 5000);
-    return { success: true, refunded_amount: token.amount };
-}
-async function burnTokenRemote(tokenId) {
-    const token = tokenStore.get(tokenId);
-    if (!token || token.cancelled)
-        return false;
-    token.used = true;
-    // Log the transaction — NOTE: wallet was already debited at issue time
-    const info = await resolveApiKey();
-    if (info) {
-        await supabase.from("transactions").insert({
-            card_id: info.cardId,
-            amount: token.amount,
-            merchant: token.merchant,
-            status: "SUCCESS",
-        });
-    }
-    setTimeout(() => tokenStore.delete(tokenId), 5000);
-    return true;
-}
-// Handle underspend: called when transaction amount < token amount
-async function refundUnderspendRemote(tokenId, actualSpent) {
-    const token = tokenStore.get(tokenId);
-    if (!token)
-        return;
-    const overheld = token.amount - actualSpent;
-    if (overheld <= 0)
-        return;
-    const info = await resolveApiKey();
-    if (!info)
-        return;
-    const currentBalanceRes = await supabase
-        .from("wallets")
-        .select("balance")
-        .eq("user_id", info.userId)
-        .single();
-    const currentBalance = Number(currentBalanceRes.data?.balance || 0);
-    await supabase
-        .from("wallets")
-        .update({ balance: currentBalance + overheld })
-        .eq("user_id", info.userId);
-    console.error(`[REFUND] Underspend refunded: $${overheld} (Spent $${actualSpent} of $${token.amount})`);
-}