@opencard-dev/mcp-server 0.1.0

package/dist/tools.js

@@ -0,0 +1,1199 @@
+"use strict";
+/**
+ * OpenCard MCP Tool Definitions and Handlers
+ * ==================================== * Defines the MCP tool schemas and wires each tool to the real
+ * @opencard/core SDK so AI agents can manage virtual cards via MCP.
+ *
+ * ─── Architecture ────────────────────────────────────────────────────────────
+ *
+ * Each tool follows this pattern:
+ *   1. Extract + validate input args
+ *   2. Initialize StripeClient with the API key from env
+ *   3. Call the appropriate SDK method
+ *   4. Return a structured result or error object (never throw)
+ *
+ * ─── Error handling ──────────────────────────────────────────────────────────
+ *
+ * All handlers catch errors and return `{ status: 'error', message }` rather
+ * than throwing. This prevents the MCP server from crashing on Stripe API
+ * errors, network failures, or bad input. The caller decides what to do with
+ * the error.
+ *
+ * ─── Stripe key ──────────────────────────────────────────────────────────────
+ *
+ * The StripeClient reads STRIPE_SECRET_KEY from the environment by default.
+ * Callers can also pass it explicitly via the `stripe_secret_key` arg (useful
+ * when the MCP server is shared across multiple callers with different keys).
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.openCardTools = void 0;
+exports.createToolHandler = createToolHandler;
+const core_1 = require("@opencard-dev/core");
+const stripe_1 = __importDefault(require("stripe"));
+// ─── Tool schemas ─────────────────────────────────────────────────────────────
+/**
+ * MCP Tool definition for OpenCard.
+ * These schemas are consumed by MCP-compatible agents to discover available tools.
+ */
+exports.openCardTools = [
+    {
+        name: 'opencard_create_card',
+        description: 'Use when setting up a new agent that needs to make purchases. Creates a virtual Stripe Issuing card with spending rules attached. Requires an existing cardholder ID — if you don\'t have one, tell the human operator to create one via the Stripe dashboard or CLI first. This hits the Stripe API.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                agent_name: {
+                    type: 'string',
+                    description: 'Name of the agent this card is for (e.g., research-bot, shopping-agent)',
+                },
+                cardholder_id: {
+                    type: 'string',
+                    description: 'Stripe cardholder ID (must exist)',
+                },
+                rule_template: {
+                    type: 'string',
+                    enum: ['balanced', 'category_locked', 'daily_limit', 'approval_gated'],
+                    description: 'Pre-built rule template to apply',
+                },
+                daily_limit_cents: {
+                    type: 'number',
+                    description: 'Daily spending limit in CENTS (e.g., 2500 = $25.00, 100000 = $1,000.00). NOT dollars.',
+                },
+                max_per_transaction_cents: {
+                    type: 'number',
+                    description: 'Per-transaction limit in CENTS (e.g., 2500 = $25.00). NOT dollars.',
+                },
+                description: {
+                    type: 'string',
+                    description: "What this card is for (e.g., 'Engineering SaaS subscriptions — Vercel, AWS, Anthropic'). Helps agents pick the right card for each purchase.",
+                },
+                metadata: {
+                    type: 'object',
+                    description: 'Custom metadata (tags, project ID, etc)',
+                },
+            },
+            required: ['agent_name', 'cardholder_id'],
+        },
+    },
+    {
+        name: 'opencard_get_balance',
+        description: 'Get spending totals and remaining budget for a card. Shows today\'s spend, monthly spend, and remaining amounts based on the card\'s rules. Call this to check if there\'s enough budget before making a purchase.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                card_id: {
+                    type: 'string',
+                    description: 'Stripe card ID',
+                },
+            },
+            required: ['card_id'],
+        },
+    },
+    {
+        name: 'opencard_get_transactions',
+        description: 'Use for expense reporting, debugging declined charges, or reviewing what was purchased. Returns transaction history for a specific card. Supports filtering by status. For real-time spend totals, use get_balance instead.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                card_id: {
+                    type: 'string',
+                    description: 'Stripe card ID',
+                },
+                limit: {
+                    type: 'number',
+                    description: 'Max transactions to return (default 50)',
+                },
+                status: {
+                    type: 'string',
+                    enum: ['approved', 'declined', 'pending', 'captured', 'reversed'],
+                    description: 'Filter by transaction status',
+                },
+            },
+            required: ['card_id'],
+        },
+    },
+    {
+        name: 'opencard_pause_card',
+        description: 'Temporarily freeze a card when something is wrong — overspending, suspicious activity, or you need to investigate. All new charges are declined immediately. The card is NOT canceled — use resume_card to re-enable it later.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                card_id: {
+                    type: 'string',
+                    description: 'Stripe card ID',
+                },
+                reason: {
+                    type: 'string',
+                    description: 'Optional reason for pausing',
+                },
+            },
+            required: ['card_id'],
+        },
+    },
+    {
+        name: 'opencard_resume_card',
+        description: 'Re-enable a card that was paused. Only works on paused (inactive) cards, not canceled ones. Call this after resolving whatever caused the pause.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                card_id: {
+                    type: 'string',
+                    description: 'Stripe card ID',
+                },
+            },
+            required: ['card_id'],
+        },
+    },
+    {
+        name: 'opencard_set_limits',
+        description: 'Update spending limits on a card when budget needs change. Sets hard limits enforced by Stripe directly (these work even if the OpenCard webhook server is down). Currently only "decline" mode is active (alert/pause modes are planned). Amounts are in CENTS.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                card_id: {
+                    type: 'string',
+                    description: 'Stripe card ID',
+                },
+                daily_limit_cents: {
+                    type: 'number',
+                    description: 'Daily limit in CENTS (e.g., 2500 = $25.00, 100000 = $1,000.00). NOT dollars.',
+                },
+                monthly_limit_cents: {
+                    type: 'number',
+                    description: 'Monthly limit in CENTS (e.g., 2500 = $25.00, 100000 = $1,000.00). NOT dollars.',
+                },
+                per_tx_limit_cents: {
+                    type: 'number',
+                    description: 'Per-transaction limit in CENTS (e.g., 2500 = $25.00). NOT dollars.',
+                },
+            },
+            required: ['card_id'],
+        },
+    },
+    {
+        name: 'opencard_get_card_details',
+        description: 'Get full details for a specific card when you need more than what list_cards provides — metadata, spending controls, Stripe-level config. For just checking budget, use get_balance instead.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                card_id: {
+                    type: 'string',
+                    description: 'Stripe card ID',
+                },
+            },
+            required: ['card_id'],
+        },
+    },
+    {
+        name: 'opencard_list_cards',
+        description: 'Call this FIRST when you need to make a purchase or check spending — find the right card before doing anything else. Returns all cards with their rules, current spend, and remaining budget. Don\'t hardcode card IDs; always discover them here.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                status: {
+                    type: 'string',
+                    enum: ['active', 'inactive', 'canceled'],
+                    description: 'Filter by card status (default: active)',
+                },
+                limit: {
+                    type: 'number',
+                    description: 'Max cards to return (default 20, max 100)',
+                },
+            },
+            required: [],
+        },
+    },
+    {
+        name: 'opencard_check_rules',
+        description: 'Call this before attempting any purchase to verify it will be approved. Dry-runs the charge against the card\'s rules locally — no real charge, no Stripe API call, instant response. Returns detailed breakdown of which checks passed or failed. Amounts are in CENTS (2500 = $25.00). NOTE: rule_id is required when multiple rules exist in the store; optional only if a single rule is configured.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                card_id: {
+                    type: 'string',
+                    description: 'Stripe card ID to check against',
+                },
+                amount_cents: {
+                    type: 'number',
+                    description: 'Amount in CENTS (e.g., 2500 = $25.00, 100000 = $1,000.00). NOT dollars.',
+                },
+                merchant_category: {
+                    type: 'string',
+                    description: 'MCC category code (e.g., "software", "restaurants")',
+                },
+                merchant_name: {
+                    type: 'string',
+                    description: 'Merchant name (for logging/context only)',
+                },
+                rule_id: {
+                    type: 'string',
+                    description: 'OpenCard rule ID. Required when multiple rules exist in the store. Optional only if a single rule is configured.',
+                },
+            },
+            required: ['card_id', 'amount_cents'],
+        },
+    },
+    {
+        name: 'opencard_request_approval',
+        description: 'Request human approval when you need to make a purchase that exceeds your normal limits or is unusual. Blocks until the human approves, denies, or the request times out (default 5 minutes). You MUST provide a reason — the human sees it. Approval gives you PERMISSION only — it does not execute the purchase. Amounts are in CENTS.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                card_id: {
+                    type: 'string',
+                    description: 'Card to charge',
+                },
+                amount_cents: {
+                    type: 'number',
+                    description: 'Requested amount in CENTS (e.g., 2500 = $25.00, 100000 = $1,000.00). NOT dollars.',
+                },
+                merchant_name: {
+                    type: 'string',
+                    description: 'Where the money is going',
+                },
+                merchant_category: {
+                    type: 'string',
+                    description: 'MCC category (optional)',
+                },
+                reason: {
+                    type: 'string',
+                    description: 'Why the agent needs this purchase (shown to human)',
+                },
+                timeout_seconds: {
+                    type: 'number',
+                    description: 'How long to wait for approval in seconds (default: 300)',
+                },
+            },
+            required: ['card_id', 'amount_cents', 'merchant_name', 'reason'],
+        },
+    },
+];
+// ─── Tool handlers ────────────────────────────────────────────────────────────
+/**
+ * Routes an MCP tool call to the appropriate handler and returns the result.
+ *
+ * All handlers are async and catch their own errors — this function will
+ * always return a result object, never throw. Unknown tool names return an
+ * error result rather than crashing.
+ *
+ * @param toolName - The MCP tool name (e.g. 'opencard_create_card')
+ * @param args - The tool's input arguments from the MCP request
+ * @returns A result object. Structure varies per tool; always includes `status`.
+ */
+async function createToolHandler(toolName, args) {
+    switch (toolName) {
+        case 'opencard_create_card':
+            return handleCreateCard(args);
+        case 'opencard_get_balance':
+            return handleGetBalance(args);
+        case 'opencard_get_transactions':
+            return handleGetTransactions(args);
+        case 'opencard_pause_card':
+            return handlePauseCard(args);
+        case 'opencard_resume_card':
+            return handleResumeCard(args);
+        case 'opencard_set_limits':
+            return handleSetLimits(args);
+        case 'opencard_get_card_details':
+            return handleGetCardDetails(args);
+        case 'opencard_check_rules':
+            return handleCheckRules(args);
+        case 'opencard_list_cards':
+            return handleListCards(args);
+        case 'opencard_request_approval':
+            return handleRequestApproval(args);
+        default:
+            return {
+                status: 'error',
+                message: `Unknown tool: ${toolName}`,
+            };
+    }
+}
+// ─── Individual handlers ──────────────────────────────────────────────────────
+/**
+ * opencard_create_card
+ * Creates a new virtual card under the specified cardholder.
+ * Optionally applies a spend-rule template and custom limit overrides.
+ */
+async function handleCreateCard(args) {
+    try {
+        const agentName = args.agent_name;
+        const cardholderId = args.cardholder_id;
+        if (!agentName || !cardholderId) {
+            return { status: 'error', message: 'agent_name and cardholder_id are required' };
+        }
+        // Build spend rules from optional template + overrides
+        let rulesBuilder = args.rule_template
+            ? core_1.SpendRules.template(args.rule_template)
+            : new core_1.SpendRules();
+        if (typeof args.daily_limit_cents === 'number') {
+            rulesBuilder = rulesBuilder.dailyLimit(args.daily_limit_cents);
+        }
+        if (typeof args.max_per_transaction_cents === 'number') {
+            rulesBuilder = rulesBuilder.maxPerTx(args.max_per_transaction_cents);
+        }
+        const rules = rulesBuilder.build();
+        const client = new core_1.StripeClient();
+        const card = await client.createCard(cardholderId, {
+            agentName,
+            rules,
+            description: args.description || undefined,
+            metadata: args.metadata || {},
+        });
+        return {
+            status: 'success',
+            card: {
+                id: card.id,
+                last4: card.last4,
+                expiry: card.expiry,
+                status: card.status,
+                agentName: card.agentName,
+                description: card.description,
+                rules: card.rules,
+                createdAt: card.createdAt,
+            },
+        };
+    }
+    catch (err) {
+        return { status: 'error', message: String(err) };
+    }
+}
+/**
+ * Formats a timestamp as a human-readable relative time string (e.g. "2 hours ago").
+ */
+function formatRelativeTime(dateStr) {
+    if (!dateStr)
+        return 'unknown';
+    const date = new Date(dateStr);
+    const now = new Date();
+    const diffMs = now.getTime() - date.getTime();
+    const diffMins = Math.floor(diffMs / 60000);
+    if (diffMins < 1)
+        return 'just now';
+    if (diffMins < 60)
+        return `${diffMins} minute${diffMins === 1 ? '' : 's'} ago`;
+    const diffHours = Math.floor(diffMins / 60);
+    if (diffHours < 24)
+        return `${diffHours} hour${diffHours === 1 ? '' : 's'} ago`;
+    const diffDays = Math.floor(diffHours / 24);
+    return `${diffDays} day${diffDays === 1 ? '' : 's'} ago`;
+}
+/**
+ * opencard_get_balance
+ * Returns per-card spend totals from SQLite (authorizations + transactions),
+ * enriched with rule limits from RulesStore. Falls back to in-memory tracker
+ * if SQLite is unavailable.
+ *
+ * R1: Query SQLite for daily/monthly authorizations and all-time transactions
+ * R2: New response shape with spend, limits, remaining, recent_transactions
+ * R3: Fallback to in-memory tracker if SQLite unavailable
+ * R4: Look up rule limits from RulesStore via card metadata opencard_rule_id
+ * R5: No more account-level available/reserved/spent fields
+ * R6: Updated tool description (see schema above)
+ */
+async function handleGetBalance(args) {
+    try {
+        const cardId = args.card_id;
+        if (!cardId) {
+            return { status: 'error', message: 'card_id is required' };
+        }
+        // ── R4: Fetch card metadata to get rule ID and limits ────────────────
+        const secretKey = process.env.STRIPE_SECRET_KEY;
+        let ruleLimits = {
+            daily_limit_cents: null,
+            monthly_limit_cents: null,
+            max_per_transaction_cents: null,
+        };
+        if (secretKey) {
+            try {
+                const stripe = new stripe_1.default(secretKey, { apiVersion: '2023-10-16' });
+                const stripeCard = await stripe.issuing.cards.retrieve(cardId);
+                const metadata = (stripeCard.metadata ?? {});
+                const ruleId = metadata.opencard_rule_id ?? null;
+                if (ruleId) {
+                    const rule = await core_1.rulesStore.getRule(ruleId);
+                    if (rule) {
+                        ruleLimits = {
+                            daily_limit_cents: rule.dailyLimit ?? null,
+                            monthly_limit_cents: rule.monthlyLimit ?? null,
+                            max_per_transaction_cents: rule.maxPerTransaction ?? null,
+                        };
+                    }
+                }
+            }
+            catch {
+                // Card fetch or rule lookup failed — proceed with null limits
+            }
+        }
+        // ── R1: Query SQLite for spend totals ────────────────────────────────
+        let db = null;
+        try {
+            db = (0, core_1.initDatabase)();
+        }
+        catch {
+            // SQLite unavailable — will fall back to in-memory tracker (R3)
+        }
+        if (db) {
+            // SQLite is available — query authorizations and transactions
+            try {
+                const rawDb = db.getDb();
+                // Spend from authorizations table with status='approved' for real-time budget enforcement.
+                // We use authorizations (not transactions) because:
+                //   - authorizations are real-time and status reflects rule enforcement decisions
+                //   - transactions are a subset of authorizations that were captured by Stripe
+                //   - using the same table ensures budget enforcement and reporting show the same spend totals
+                //   - this matches CLI status and MCP list_cards for consistency
+                // Daily spend: approved authorizations from midnight UTC today
+                const dailyResult = rawDb
+                    .prepare("SELECT COALESCE(SUM(amount), 0) as total FROM authorizations WHERE card_id = ? AND status = 'approved' AND created_at >= date('now')")
+                    .get(cardId);
+                // Monthly spend: approved authorizations from 1st of current month UTC
+                const monthlyResult = rawDb
+                    .prepare("SELECT COALESCE(SUM(amount), 0) as total FROM authorizations WHERE card_id = ? AND status = 'approved' AND created_at >= strftime('%Y-%m-01', 'now')")
+                    .get(cardId);
+                // All-time spend: captured transactions
+                const allTimeResult = rawDb
+                    .prepare("SELECT COALESCE(SUM(amount), 0) as total FROM transactions WHERE card_id = ? AND status = 'captured'")
+                    .get(cardId);
+                // Recent transactions (last 5 captured, newest first)
+                const recentRows = rawDb
+                    .prepare("SELECT amount, merchant_name, merchant_category, stripe_created_at FROM transactions WHERE card_id = ? AND status = 'captured' ORDER BY stripe_created_at DESC LIMIT 5")
+                    .all(cardId);
+                const todayCents = dailyResult.total;
+                const thisMonthCents = monthlyResult.total;
+                const allTimeCents = allTimeResult.total;
+                const recentTransactions = recentRows.map((row) => ({
+                    amount_cents: row.amount,
+                    merchant: row.merchant_name ?? 'Unknown',
+                    category: row.merchant_category ?? 'unknown',
+                    when: formatRelativeTime(row.stripe_created_at),
+                }));
+                const result = {
+                    status: 'success',
+                    card_id: cardId,
+                    spend: {
+                        today_cents: todayCents,
+                        this_month_cents: thisMonthCents,
+                        all_time_cents: allTimeCents,
+                    },
+                    limits: {
+                        daily_limit_cents: ruleLimits.daily_limit_cents,
+                        monthly_limit_cents: ruleLimits.monthly_limit_cents,
+                        max_per_transaction_cents: ruleLimits.max_per_transaction_cents,
+                    },
+                    remaining: {
+                        today_cents: ruleLimits.daily_limit_cents !== null
+                            ? Math.max(0, ruleLimits.daily_limit_cents - todayCents)
+                            : null,
+                        this_month_cents: ruleLimits.monthly_limit_cents !== null
+                            ? Math.max(0, ruleLimits.monthly_limit_cents - thisMonthCents)
+                            : null,
+                    },
+                    recent_transactions: recentTransactions,
+                    data_source: 'sqlite',
+                };
+                db.close();
+                return result;
+            }
+            catch (dbErr) {
+                // Query failed — fall through to in-memory fallback
+                try {
+                    db.close();
+                }
+                catch { /* ignore */ }
+                db = null;
+            }
+        }
+        // ── R3: Fallback to in-memory tracker ────────────────────────────────
+        const trackerInstance = new core_1.TransactionTracker();
+        const todayCents = trackerInstance.getDailySpend(cardId);
+        const thisMonthCents = trackerInstance.getMonthlySpend(cardId);
+        return {
+            status: 'success',
+            card_id: cardId,
+            spend: {
+                today_cents: todayCents,
+                this_month_cents: thisMonthCents,
+                all_time_cents: null, // Not available in in-memory tracker
+            },
+            limits: {
+                daily_limit_cents: ruleLimits.daily_limit_cents,
+                monthly_limit_cents: ruleLimits.monthly_limit_cents,
+                max_per_transaction_cents: ruleLimits.max_per_transaction_cents,
+            },
+            remaining: {
+                today_cents: ruleLimits.daily_limit_cents !== null
+                    ? Math.max(0, ruleLimits.daily_limit_cents - todayCents)
+                    : null,
+                this_month_cents: ruleLimits.monthly_limit_cents !== null
+                    ? Math.max(0, ruleLimits.monthly_limit_cents - thisMonthCents)
+                    : null,
+            },
+            recent_transactions: [],
+            data_source: 'in_memory',
+            warning: 'SQLite database unavailable. Spend data is from in-memory tracker only and will reset on server restart.',
+        };
+    }
+    catch (err) {
+        return { status: 'error', message: String(err) };
+    }
+}
+/**
+ * opencard_get_transactions
+ * Retrieves the transaction history for a card from Stripe Issuing.
+ * Note: These are captured/settled transactions, not pending authorizations.
+ * Pending authorizations are handled via webhooks in real time.
+ */
+async function handleGetTransactions(args) {
+    try {
+        const cardId = args.card_id;
+        if (!cardId) {
+            return { status: 'error', message: 'card_id is required' };
+        }
+        const client = new core_1.StripeClient();
+        const transactions = await client.getTransactions(cardId, {
+            limit: typeof args.limit === 'number' ? args.limit : 50,
+        });
+        // Optionally filter by status if the caller asked for a specific status
+        const statusFilter = args.status;
+        const filtered = statusFilter
+            ? transactions.filter((tx) => tx.status === statusFilter)
+            : transactions;
+        return {
+            status: 'success',
+            card_id: cardId,
+            count: filtered.length,
+            transactions: filtered.map((tx) => ({
+                id: tx.id,
+                amount: tx.amount,
+                currency: tx.currency,
+                merchant_name: tx.merchant.name,
+                merchant_category: tx.merchant.category,
+                status: tx.status,
+                created_at: tx.createdAt,
+            })),
+        };
+    }
+    catch (err) {
+        return { status: 'error', message: String(err) };
+    }
+}
+/**
+ * opencard_pause_card
+ * Sets the card status to 'inactive', blocking all new charges.
+ * The card can be re-enabled via opencard_resume_card.
+ * Useful for temporarily suspending an agent that has exceeded its budget.
+ */
+async function handlePauseCard(args) {
+    try {
+        const cardId = args.card_id;
+        if (!cardId) {
+            return { status: 'error', message: 'card_id is required' };
+        }
+        const client = new core_1.StripeClient();
+        const card = await client.pauseCard(cardId);
+        return {
+            status: 'success',
+            card_id: card.id,
+            new_status: card.status,
+            reason: args.reason ?? null,
+            message: `Card ${card.id} paused. All new charges will be declined until resumed.`,
+        };
+    }
+    catch (err) {
+        return { status: 'error', message: String(err) };
+    }
+}
+/**
+ * opencard_resume_card
+ * Sets the card status back to 'active', re-enabling new charges.
+ * Only works on cards that were paused (inactive), not canceled ones.
+ */
+async function handleResumeCard(args) {
+    try {
+        const cardId = args.card_id;
+        if (!cardId) {
+            return { status: 'error', message: 'card_id is required' };
+        }
+        const client = new core_1.StripeClient();
+        const card = await client.resumeCard(cardId);
+        return {
+            status: 'success',
+            card_id: card.id,
+            new_status: card.status,
+            message: `Card ${card.id} resumed. Charges are now accepted again.`,
+        };
+    }
+    catch (err) {
+        return { status: 'error', message: String(err) };
+    }
+}
+/**
+ * opencard_set_limits
+ * Updates Stripe-native spending limits on the card.
+ * These limits are enforced by Stripe regardless of whether the OpenCard
+ * webhook server is running — they're the hard floor under our soft rules.
+ *
+ * Accepts any combination of daily, monthly, and per-transaction limits.
+ * At least one limit must be specified.
+ */
+async function handleSetLimits(args) {
+    try {
+        const cardId = args.card_id;
+        if (!cardId) {
+            return { status: 'error', message: 'card_id is required' };
+        }
+        // Build the spending limits array from whichever limits were provided.
+        // Stripe requires at least one limit; we return an error if none given.
+        const limits = [];
+        if (typeof args.daily_limit_cents === 'number') {
+            limits.push({ amount: args.daily_limit_cents, intervalType: 'daily', intervalCurrencyUnit: 'usd' });
+        }
+        if (typeof args.monthly_limit_cents === 'number') {
+            limits.push({ amount: args.monthly_limit_cents, intervalType: 'monthly', intervalCurrencyUnit: 'usd' });
+        }
+        if (typeof args.per_tx_limit_cents === 'number') {
+            limits.push({ amount: args.per_tx_limit_cents, intervalType: 'per_authorization', intervalCurrencyUnit: 'usd' });
+        }
+        if (limits.length === 0) {
+            return {
+                status: 'error',
+                message: 'At least one of daily_limit_cents, monthly_limit_cents, or per_tx_limit_cents must be specified',
+            };
+        }
+        const client = new core_1.StripeClient();
+        const card = await client.setSpendingLimits(cardId, limits);
+        return {
+            status: 'success',
+            card_id: card.id,
+            limits_applied: limits,
+            spending_controls: card.spendingControls,
+            message: `Spending limits updated on card ${card.id}.`,
+        };
+    }
+    catch (err) {
+        return { status: 'error', message: String(err) };
+    }
+}
+/**
+ * opencard_get_card_details
+ * Retrieves full card details from Stripe including status, expiry,
+ * agent name, applied rules, and spending controls.
+ */
+async function handleGetCardDetails(args) {
+    try {
+        const cardId = args.card_id;
+        if (!cardId) {
+            return { status: 'error', message: 'card_id is required' };
+        }
+        const client = new core_1.StripeClient();
+        const card = await client.getCard(cardId);
+        return {
+            status: 'success',
+            card: {
+                id: card.id,
+                last4: card.last4,
+                brand: card.brand,
+                expiry: card.expiry,
+                status: card.status,
+                cardholder_id: card.cardholderId,
+                agent_name: card.agentName,
+                description: card.description,
+                rules: card.rules,
+                spending_controls: card.spendingControls,
+                metadata: card.metadata,
+                created_at: card.createdAt,
+            },
+        };
+    }
+    catch (err) {
+        return { status: 'error', message: String(err) };
+    }
+}
+/**
+
+ * opencard_list_cards
+ * Lists all cards from Stripe Issuing, enriched with rule details and
+ * best-effort spend data from SQLite. Designed for agent discovery — call
+ * this first to find the right card ID before any other operation.
+ *
+ * Spend data is pulled from the local SQLite DB (populated by the webhook
+ * server). If the DB is unavailable (hasn't been set up yet), spend is
+ * returned as null — the card list still works fine without it.
+ *
+ * Rule data is pulled from RulesStore using the opencard_rule_id stored in
+ * each card's Stripe metadata. If no rule is assigned, rule is null.
+ */
+async function handleListCards(args) {
+    try {
+        const statusFilter = args.status ?? 'active';
+        const limit = typeof args.limit === 'number' ? Math.min(args.limit, 100) : 20;
+        // ── Fetch cards from Stripe ────────────────────────────────────────────
+        const secretKey = process.env.STRIPE_SECRET_KEY;
+        if (!secretKey) {
+            return { status: 'error', message: 'STRIPE_SECRET_KEY must be set' };
+        }
+        const stripe = new stripe_1.default(secretKey, { apiVersion: '2023-10-16' });
+        const stripeCards = await stripe.issuing.cards.list({
+            status: statusFilter,
+            limit,
+        });
+        // ── Best-effort SQLite spend lookup ───────────────────────────────────
+        // Open DB once for all cards; if it throws, spend will be null for all.
+        let db = null;
+        try {
+            db = (0, core_1.initDatabase)();
+        }
+        catch {
+            // DB unavailable — spend will be null for all cards (per R3)
+        }
+        // Helper: compute today_cents and this_month_cents for a card from SQLite.
+        // Returns null if DB is not available.
+        // Uses authorizations table with status='approved' for consistency with get_balance.
+        // We use authorizations (not transactions) because:
+        //   - authorizations are real-time and status reflects rule enforcement decisions
+        //   - transactions are a subset of authorizations that were captured by Stripe
+        //   - using the same table ensures budget enforcement and reporting show the same spend totals
+        function getSpendFromDb(cardId) {
+            if (!db)
+                return null;
+            try {
+                const rawDb = db.getDb();
+                // Daily spend: approved authorizations from midnight UTC today
+                const todayResult = rawDb
+                    .prepare("SELECT COALESCE(SUM(amount), 0) as total FROM authorizations WHERE card_id = ? AND status = 'approved' AND created_at >= date('now')")
+                    .get(cardId);
+                // Monthly spend: approved authorizations from 1st of current month UTC
+                const monthResult = rawDb
+                    .prepare("SELECT COALESCE(SUM(amount), 0) as total FROM authorizations WHERE card_id = ? AND status = 'approved' AND created_at >= strftime('%Y-%m-01', 'now')")
+                    .get(cardId);
+                return {
+                    today_cents: todayResult.total,
+                    this_month_cents: monthResult.total,
+                };
+            }
+            catch {
+                return null;
+            }
+        }
+        // ── Build enriched card list ───────────────────────────────────────────
+        const cards = await Promise.all(stripeCards.data.map(async (stripeCard) => {
+            const metadata = (stripeCard.metadata ?? {});
+            const agentName = metadata.agentName ?? metadata.agent_name ?? null;
+            // Rule lookup: read opencard_rule_id from metadata, fetch from RulesStore
+            const ruleId = metadata.opencard_rule_id ?? null;
+            let rule = null;
+            if (ruleId) {
+                try {
+                    const spendRule = await core_1.rulesStore.getRule(ruleId);
+                    if (spendRule) {
+                        rule = {
+                            id: ruleId,
+                            name: spendRule.name,
+                            daily_limit_cents: spendRule.dailyLimit,
+                            monthly_limit_cents: spendRule.monthlyLimit,
+                            max_per_transaction_cents: spendRule.maxPerTransaction,
+                        };
+                    }
+                }
+                catch {
+                    // Rule store unavailable — return null for rule gracefully
+                }
+            }
+            // Spend from SQLite (best-effort, null if DB not available)
+            const spend = getSpendFromDb(stripeCard.id);
+            const description = metadata.opencard_description ?? null;
+            return {
+                id: stripeCard.id,
+                last4: stripeCard.last4,
+                name: agentName,
+                description,
+                status: stripeCard.status,
+                rule,
+                spend,
+                created_at: new Date(stripeCard.created * 1000).toISOString(),
+            };
+        }));
+        // Close DB when done
+        if (db) {
+            try {
+                db.close();
+            }
+            catch { /* ignore close errors */ }
+        }
+        return {
+            status: 'success',
+            count: cards.length,
+            cards,
+        };
+    }
+    catch (err) {
+        return { status: 'error', message: String(err) };
+    }
+}
+/**
+ * opencard_check_rules
+ * Dry-runs a purchase against the card's current rules without making
+ * any real charge or Stripe API calls. Uses:
+ *  1. RulesStore to look up the card's rule (via card metadata opencard_rule_id)
+ *  2. SQLite to get current daily/monthly spend (same queries as CLI status)
+ *  3. evaluateAuthorization from the rules engine for the decision
+ *
+ * Entirely local — zero Stripe API calls.
+ */
+async function handleCheckRules(args) {
+    try {
+        const cardId = args.card_id;
+        const amountCents = args.amount_cents;
+        if (!cardId) {
+            return { status: 'error', message: 'card_id is required' };
+        }
+        if (typeof amountCents !== 'number' || amountCents < 0) {
+            return { status: 'error', message: 'amount_cents must be a non-negative number' };
+        }
+        const merchantCategory = args.merchant_category ?? '';
+        const merchantName = args.merchant_name ?? 'unknown merchant';
+        // ── Step 1: Look up the rule for this card ────────────────────────────────
+        // We need the card's opencard_rule_id to find the rule.
+        // Per the brief, we use getRulesForCard logic — but we don't have a
+        // Stripe.Issuing.Card object here without an API call. Instead, we accept
+        // either a rule_id passed directly, or we check the rules store.
+        // Per R3: no Stripe API calls. We'll use the rulesStore directly with
+        // the card_id as the rule lookup key — the card metadata mapping is only
+        // available via Stripe. We look up the first rule that lists this card_id,
+        // or fall back to reading card metadata from a local cache.
+        //
+        // Practical approach: try to load rule by treating card_id as a potential
+        // rule_id lookup key, or query RulesStore.listRules() to find one
+        // matching this card. If not found, return default-deny.
+        //
+        // For maximum usefulness without a Stripe call, we support:
+        //  - A card_rule_id arg (optional) to skip the card lookup
+        //  - Fallback: search rules store for a rule with card_id matching this card
+        //  - Final fallback: no rule found → default-deny with explanation
+        let rule = null;
+        let ruleName = 'unknown';
+        let ruleId = null;
+        // Check if caller provided an explicit rule ID override
+        const explicitRuleId = args.rule_id;
+        if (explicitRuleId) {
+            rule = await core_1.rulesStore.getRule(explicitRuleId);
+            if (rule) {
+                ruleId = explicitRuleId;
+                ruleName = rule.name ?? explicitRuleId;
+            }
+        }
+        if (!rule) {
+            // Search the rules store for a rule associated with this card_id
+            const allRules = await core_1.rulesStore.listRules();
+            // Rules don't store card_id in the JSON file — they're referenced via
+            // Stripe card metadata. Without a Stripe call we can't resolve
+            // card → rule_id. Instead, if there's exactly one rule, use it as a
+            // best-effort heuristic (useful in dev/single-card setups).
+            // In production with multiple cards, the agent should pass rule_id explicitly.
+            if (allRules.length === 0) {
+                // No rules at all
+                return {
+                    status: 'error',
+                    message: 'No rules found in the store. Create a rule first using opencard_set_limits or rules store API.',
+                };
+            }
+            else if (allRules.length === 1) {
+                rule = allRules[0].rule;
+                ruleId = allRules[0].id;
+                ruleName = rule.name ?? ruleId;
+            }
+            else {
+                // Multiple rules exist and no rule_id was provided
+                const ruleList = allRules
+                    .map((r) => `${r.id} (${r.rule.name || 'unnamed'})`)
+                    .join(', ');
+                return {
+                    status: 'error',
+                    message: `Multiple rules found in the store and rule_id was not provided. Pass rule_id explicitly. Available rules: ${ruleList}`,
+                };
+            }
+        }
+        if (!rule) {
+            return {
+                status: 'success',
+                would_approve: false,
+                reason: 'Could not resolve which rule applies to this card. This usually means: (1) the card has no opencard_rule_id in its Stripe metadata, or (2) there are multiple rules in the store and we can\'t pick one without a Stripe API call. Fix: pass rule_id explicitly, or assign a rule to the card via opencard_rule_id metadata.',
+                rule_name: null,
+                rule_id: null,
+                checks: {},
+            };
+        }
+        // ── Step 2: Get current daily/monthly spend from SQLite ───────────────────
+        let dailySpend = 0;
+        let monthlySpend = 0;
+        let spendDataNote = null;
+        try {
+            const db = new core_1.OpenCardDatabase();
+            const rawDb = db.getDb();
+            const now = new Date();
+            const todayMidnight = new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate()));
+            const monthStart = new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), 1));
+            const todayStr = todayMidnight.toISOString().replace('T', ' ').slice(0, 19);
+            const monthStr = monthStart.toISOString().replace('T', ' ').slice(0, 19);
+            const todayRow = rawDb.prepare(`SELECT COALESCE(SUM(amount), 0) as total FROM authorizations WHERE card_id = ? AND status = 'approved' AND created_at >= ?`).get(cardId, todayStr);
+            const monthRow = rawDb.prepare(`SELECT COALESCE(SUM(amount), 0) as total FROM authorizations WHERE card_id = ? AND status = 'approved' AND created_at >= ?`).get(cardId, monthStr);
+            dailySpend = todayRow.total;
+            monthlySpend = monthRow.total;
+            db.close();
+        }
+        catch {
+            spendDataNote = 'unavailable — webhook server not running or DB not initialized';
+            // Continue with zeroed spend — run the check without spend context
+        }
+        // ── Step 3: Build a mock Stripe authorization object ──────────────────────
+        const mockAuth = {
+            id: `dry_run_${Date.now()}`,
+            object: 'issuing.authorization',
+            amount: amountCents,
+            approved: false,
+            currency: 'usd',
+            merchant_data: {
+                category: merchantCategory,
+                name: merchantName,
+                city: null,
+                country: null,
+                network_id: '',
+                postal_code: null,
+                state: null,
+            },
+            card: { id: cardId, metadata: {} },
+            metadata: {},
+            pending_request: null,
+            request_history: [],
+            status: 'pending',
+            created: Math.floor(Date.now() / 1000),
+            livemode: false,
+            network_data: null,
+            transactions: [],
+            verification_data: {
+                address_line1_check: 'not_provided',
+                address_postal_code_check: 'not_provided',
+                cvc_check: 'not_provided',
+                expiry_check: 'match',
+            },
+            wallet: null,
+            amount_details: null,
+            balance_transactions: [],
+            cardholder: null,
+            fleet: null,
+            fuel: null,
+            merchant_amount: amountCents,
+            merchant_currency: 'usd',
+            token: null,
+        };
+        // ── Step 4: Evaluate against the rules engine ─────────────────────────────
+        const decision = (0, core_1.evaluateAuthorization)(mockAuth, rule, {
+            dailySpend,
+            monthlySpend,
+        });
+        // ── Step 5: Build detailed checks breakdown ────────────────────────────────
+        const checks = {};
+        if (rule.maxPerTransaction !== undefined) {
+            checks.per_transaction = {
+                limit: rule.maxPerTransaction,
+                amount: amountCents,
+                passed: amountCents <= rule.maxPerTransaction,
+            };
+        }
+        if (rule.dailyLimit !== undefined) {
+            checks.daily = {
+                limit: rule.dailyLimit,
+                spent_today: dailySpend,
+                after_purchase: dailySpend + amountCents,
+                passed: dailySpend + amountCents <= rule.dailyLimit,
+                ...(spendDataNote ? { spend_data: spendDataNote } : {}),
+            };
+        }
+        if (rule.monthlyLimit !== undefined) {
+            checks.monthly = {
+                limit: rule.monthlyLimit,
+                spent_this_month: monthlySpend,
+                after_purchase: monthlySpend + amountCents,
+                passed: monthlySpend + amountCents <= rule.monthlyLimit,
+                ...(spendDataNote ? { spend_data: spendDataNote } : {}),
+            };
+        }
+        if (rule.allowedCategories && rule.allowedCategories.length > 0) {
+            checks.category = {
+                allowed: rule.allowedCategories,
+                requested: merchantCategory || null,
+                passed: !merchantCategory || rule.allowedCategories.includes(merchantCategory),
+            };
+        }
+        else if (rule.blockedCategories && rule.blockedCategories.length > 0) {
+            checks.category = {
+                blocked: rule.blockedCategories,
+                requested: merchantCategory || null,
+                passed: !merchantCategory || !rule.blockedCategories.includes(merchantCategory),
+            };
+        }
+        // ── Step 6: Include card description so agent can confirm right card ──────
+        // Try to read description from Stripe metadata. Best-effort — if Stripe
+        // call fails (no key set, test env, etc.), description is null.
+        let cardDescription = null;
+        const secretKeyForDesc = process.env.STRIPE_SECRET_KEY;
+        if (secretKeyForDesc) {
+            try {
+                const stripe = new stripe_1.default(secretKeyForDesc, { apiVersion: '2023-10-16' });
+                const stripeCard = await stripe.issuing.cards.retrieve(cardId);
+                cardDescription = stripeCard.metadata?.opencard_description ?? null;
+            }
+            catch {
+                // Not critical — proceed without description
+            }
+        }
+        return {
+            status: 'success',
+            would_approve: decision.approved,
+            reason: decision.reason,
+            rule_name: ruleName,
+            rule_id: ruleId,
+            card_description: cardDescription,
+            checks,
+            ...(spendDataNote && Object.keys(checks).length === 0 ? { spend_data: spendDataNote } : {}),
+        };
+    }
+    catch (err) {
+        return { status: 'error', message: String(err) };
+    }
+}
+/**
+ * opencard_request_approval
+ * Human-in-the-loop spending approval. Creates an approval request in SQLite,
+ * notifies the operator (via stderr + optional webhook), then polls every 2s
+ * until the human approves/denies or the timeout expires.
+ *
+ * Approval does NOT auto-execute the purchase — it returns permission only.
+ * The agent then decides whether to proceed.
+ */
+async function handleRequestApproval(args) {
+    try {
+        const cardId = args.card_id;
+        const amountCents = args.amount_cents;
+        const merchantName = args.merchant_name;
+        const reason = args.reason;
+        const merchantCategory = args.merchant_category ?? null;
+        const timeoutSeconds = typeof args.timeout_seconds === 'number' ? args.timeout_seconds : 300;
+        if (!cardId)
+            return { status: 'error', message: 'card_id is required' };
+        if (typeof amountCents !== 'number' || amountCents < 0)
+            return { status: 'error', message: 'amount_cents must be a non-negative number' };
+        if (!merchantName)
+            return { status: 'error', message: 'merchant_name is required' };
+        if (!reason)
+            return { status: 'error', message: 'reason is required' };
+        // ── Create the approval request in SQLite ─────────────────────────────
+        const db = (0, core_1.initDatabase)();
+        const request = db.createApprovalRequest({
+            card_id: cardId,
+            amount: amountCents,
+            merchant_name: merchantName,
+            merchant_category: merchantCategory,
+            reason,
+            timeout_seconds: timeoutSeconds,
+        });
+        const requestId = request.id;
+        const amountDollars = `$${(amountCents / 100).toFixed(2)}`;
+        // ── Notify operator ───────────────────────────────────────────────────
+        const notifyMsg = [
+            ``,
+            `╔══════════════════════════════════════════════════════╗`,
+            `║  🔔  APPROVAL REQUEST — ${requestId}`,
+            `╠══════════════════════════════════════════════════════╣`,
+            `║  Amount:   ${amountDollars}`,
+            `║  Merchant: ${merchantName}${merchantCategory ? ` (${merchantCategory})` : ''}`,
+            `║  Card:     ${cardId}`,
+            `║  Reason:   ${reason}`,
+            `║  Timeout:  ${timeoutSeconds}s`,
+            `╠══════════════════════════════════════════════════════╣`,
+            `║  opencard approvals approve ${requestId}`,
+            `║  opencard approvals deny ${requestId} --note "reason"`,
+            `╚══════════════════════════════════════════════════════╝`,
+            ``,
+        ].join('\n');
+        process.stderr.write(notifyMsg + '\n');
+        // Fire webhook notification (non-blocking, don't fail if it errors)
+        const webhookUrl = process.env.OPENCARD_APPROVAL_WEBHOOK_URL;
+        if (webhookUrl) {
+            const payload = {
+                event: 'approval_request.created',
+                request_id: requestId,
+                card_id: cardId,
+                amount_cents: amountCents,
+                merchant_name: merchantName,
+                merchant_category: merchantCategory,
+                reason,
+                timeout_seconds: timeoutSeconds,
+                created_at: request.created_at,
+                expires_at: request.expires_at,
+            };
+            fetch(webhookUrl, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify(payload),
+            }).catch(err => {
+                process.stderr.write(`[OpenCard] Approval webhook notification failed: ${err}\n`);
+            });
+        }
+        // ── Poll until decided or expired ─────────────────────────────────────
+        const pollIntervalMs = 2000;
+        const deadlineMs = Date.now() + timeoutSeconds * 1000;
+        while (Date.now() < deadlineMs) {
+            await new Promise(resolve => setTimeout(resolve, pollIntervalMs));
+            db.expireStaleApprovalRequests();
+            const current = db.getApprovalRequest(requestId);
+            if (!current) {
+                db.close();
+                return { status: 'error', message: `Approval request ${requestId} disappeared` };
+            }
+            if (current.status === 'approved') {
+                db.close();
+                return {
+                    status: 'approved',
+                    request_id: requestId,
+                    approved_by: current.decided_by,
+                    note: current.decision_note ?? null,
+                    approved_at: current.decided_at,
+                };
+            }
+            if (current.status === 'denied') {
+                db.close();
+                return {
+                    status: 'denied',
+                    request_id: requestId,
+                    denied_by: current.decided_by,
+                    note: current.decision_note ?? null,
+                    denied_at: current.decided_at,
+                };
+            }
+            if (current.status === 'expired') {
+                db.close();
+                return {
+                    status: 'expired',
+                    request_id: requestId,
+                    message: `No response within ${timeoutSeconds} seconds`,
+                };
+            }
+        }
+        db.expireStaleApprovalRequests();
+        db.close();
+        return {
+            status: 'expired',
+            request_id: requestId,
+            message: `No response within ${timeoutSeconds} seconds`,
+        };
+    }
+    catch (err) {
+        return { status: 'error', message: String(err) };
+    }
+}
+//# sourceMappingURL=tools.js.map