globodai-mcp-payment-manager 1.0.1

package/src/tools/add-wallet.ts

@@ -0,0 +1,114 @@
+/**
+ * Add a new crypto wallet
+ */
+
+import { z } from "zod";
+import { randomUUID } from "crypto";
+import { addWallet } from "../lib/wallets";
+import type { WalletType } from "../lib/wallets";
+
+export const name = "add_wallet";
+
+export const description = `Add a new crypto wallet. Supports hot wallets (with private key - encrypted), watch-only (address only), and hardware wallets (address + device info).
+
+For hot wallets: private key will be encrypted at rest.
+For watch-only: only the address is stored, no spending capability.
+For hardware: address is stored, transactions require hardware signing.`;
+
+export const parameters = z.object({
+  nickname: z.string().describe("Friendly name for the wallet (e.g., 'ETH principal', 'Trading wallet')"),
+  address: z.string().describe("Public wallet address"),
+  chain: z.enum(["ethereum", "polygon", "arbitrum", "optimism", "base", "avalanche", "bsc", "bitcoin", "solana", "starknet"])
+    .describe("Blockchain network"),
+  type: z.enum(["hot", "watch-only", "hardware"]).describe("Wallet type"),
+  private_key: z.string().optional().describe("Private key (for hot wallets only - will be encrypted)"),
+  mnemonic: z.string().optional().describe("Seed phrase (for hot wallets only - will be encrypted)"),
+  hardware_type: z.enum(["ledger", "trezor", "other"]).optional().describe("Hardware wallet type"),
+  derivation_path: z.string().optional().describe("Derivation path (e.g., m/44'/60'/0'/0/0)"),
+  allowed_operations: z.array(z.enum(["send", "swap", "approve", "sign"])).optional()
+    .describe("Allowed operations (default: all for hot, none for watch-only)"),
+  per_transaction_limit: z.number().optional().describe("Max amount per transaction"),
+  daily_limit: z.number().optional().describe("Max daily spending"),
+  limit_token: z.string().optional().describe("Token symbol for limits (e.g., 'ETH', 'USDC')"),
+});
+
+export async function execute(args: z.infer<typeof parameters>) {
+  try {
+    // Validate based on type
+    if (args.type === "hot" && !args.private_key && !args.mnemonic) {
+      return {
+        success: false,
+        error: "Hot wallets require either a private_key or mnemonic",
+      };
+    }
+    
+    if (args.type === "watch-only" && (args.private_key || args.mnemonic)) {
+      return {
+        success: false,
+        error: "Watch-only wallets cannot have private keys",
+      };
+    }
+    
+    if (args.type === "hardware" && !args.hardware_type) {
+      return {
+        success: false,
+        error: "Hardware wallets must specify hardware_type",
+      };
+    }
+    
+    const walletId = randomUUID();
+    
+    // Default operations based on type
+    let operations = args.allowed_operations;
+    if (!operations) {
+      if (args.type === "hot") {
+        operations = ["send", "swap", "approve", "sign"];
+      } else if (args.type === "hardware") {
+        operations = ["send", "swap", "approve", "sign"]; // Requires hardware confirmation
+      } else {
+        operations = []; // Watch-only can't do anything
+      }
+    }
+    
+    await addWallet({
+      id: walletId,
+      nickname: args.nickname,
+      address: args.address,
+      chain: args.chain,
+      type: args.type as WalletType,
+      privateKey: args.private_key,
+      mnemonic: args.mnemonic,
+      hardwareType: args.hardware_type,
+      derivationPath: args.derivation_path,
+      enabled: true,
+      allowedOperations: operations,
+      limits: args.per_transaction_limit || args.daily_limit ? {
+        perTransaction: args.per_transaction_limit,
+        daily: args.daily_limit,
+        tokenSymbol: args.limit_token ?? "ETH",
+      } : undefined,
+      addedAt: new Date().toISOString(),
+    });
+    
+    const typeInfo = {
+      hot: "Private key encrypted and stored securely",
+      "watch-only": "Address only - no spending capability",
+      hardware: `${args.hardware_type} wallet - requires device for signing`,
+    };
+    
+    return {
+      success: true,
+      message: `Wallet "${args.nickname}" added successfully`,
+      wallet_id: walletId,
+      type: args.type,
+      chain: args.chain,
+      address: `${args.address.slice(0, 10)}...${args.address.slice(-8)}`,
+      security_note: typeInfo[args.type as WalletType],
+    };
+  } catch (error) {
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : "Failed to add wallet",
+    };
+  }
+}

package/src/tools/card-status.ts

@@ -0,0 +1,32 @@
+/**
+ * Get card lock status
+ */
+
+import { z } from "zod";
+import { getStatus, isPinConfigured } from "../lib/pin-manager";
+import { getCardsSafe } from "../lib/cards";
+
+export const name = "card_status";
+
+export const description = "Check if cards are locked or unlocked, and how many cards are saved.";
+
+export const parameters = z.object({});
+
+export async function execute(_args: z.infer<typeof parameters>) {
+  const pinStatus = getStatus();
+  const cards = await getCardsSafe();
+  
+  return {
+    success: true,
+    pin_configured: pinStatus.configured,
+    cards_unlocked: pinStatus.unlocked,
+    remaining_minutes: pinStatus.remainingMinutes ?? null,
+    saved_cards: cards.length,
+    cards: cards.map((c) => ({
+      nickname: c.nickname,
+      type: c.cardType.toUpperCase(),
+      lastFour: `****${c.lastFourDigits}`,
+      enabled: c.enabled,
+    })),
+  };
+}

package/src/tools/confirm-payment.ts

@@ -0,0 +1,103 @@
+/**
+ * Confirm and execute a prepared payment
+ * 
+ * This is where the actual charge would happen.
+ * CVV is retrieved from encrypted storage (requires PIN unlock).
+ */
+
+import { z } from "zod";
+import { getCard, getCardCvv, getTransactions, updateTransaction, updateCardUsage } from "../lib/cards";
+import { isUnlocked } from "../lib/pin-manager";
+
+export const name = "confirm_payment";
+
+export const description = "Confirm and execute a prepared payment. Cards must be unlocked with your PIN. CVV is retrieved from secure storage.";
+
+export const parameters = z.object({
+  transaction_id: z.string().describe("ID of the pending transaction to confirm"),
+  confirm: z.boolean().describe("Must be true to confirm you want to proceed with the charge"),
+});
+
+export async function execute(args: z.infer<typeof parameters>) {
+  if (!args.confirm) {
+    return {
+      success: false,
+      error: "You must set confirm=true to proceed with the payment",
+    };
+  }
+  
+  // Check cards are unlocked
+  if (!isUnlocked()) {
+    return {
+      success: false,
+      error: "Cards are locked. Use unlock_cards with your PIN first.",
+    };
+  }
+  
+  // Find the pending transaction
+  const transactions = await getTransactions(100);
+  const tx = transactions.find((t) => t.id === args.transaction_id);
+  
+  if (!tx) {
+    return {
+      success: false,
+      error: "Transaction not found",
+    };
+  }
+  
+  if (tx.status !== "pending") {
+    return {
+      success: false,
+      error: `Transaction is already ${tx.status}`,
+    };
+  }
+  
+  // Get the card
+  const card = await getCard(tx.cardId);
+  if (!card) {
+    return {
+      success: false,
+      error: "Card no longer exists",
+    };
+  }
+  
+  // Get CVV from encrypted storage
+  const cvv = await getCardCvv(tx.cardId);
+  if (!cvv) {
+    return {
+      success: false,
+      error: "Could not retrieve CVV. Make sure cards are unlocked.",
+    };
+  }
+  
+  // Here we would integrate with actual payment providers
+  // CVV is available in `cvv` variable for the API call
+  // For now, we mark as confirmed and return what would be needed
+  
+  await updateTransaction(tx.id, {
+    status: "confirmed",
+    confirmedAt: new Date().toISOString(),
+  });
+  
+  await updateCardUsage(card.id);
+  
+  return {
+    success: true,
+    status: "confirmed",
+    transaction_id: tx.id,
+    message: `Payment of ${tx.amount} ${tx.currency} confirmed`,
+    summary: {
+      card: `${card.nickname} (****${card.lastFourDigits})`,
+      amount: `${tx.amount} ${tx.currency}`,
+      type: tx.type,
+      description: tx.description,
+      provider: tx.provider,
+    },
+    // In production, this would return actual booking reference
+    note: "Integration with payment provider needed. Transaction marked as confirmed.",
+    next_steps: [
+      "Integrate with Stripe/payment processor for actual charge",
+      "Integrate with booking APIs (Amadeus, Trainline, etc.) for reservations",
+    ],
+  };
+}

package/src/tools/get-total-balance.ts

@@ -0,0 +1,123 @@
+/**
+ * Get consolidated view of all balances
+ */
+
+import { z } from "zod";
+import { getCardsSafe } from "../lib/cards";
+import { getWalletsSafe, type Chain } from "../lib/wallets";
+import { getWalletBalance, getUsdPrice } from "../lib/blockchain";
+
+export const name = "get_total_balance";
+
+export const description = "Get a consolidated view of all financial accounts: cards and crypto wallets. Shows individual and total balances.";
+
+export const parameters = z.object({
+  include_disabled: z.boolean().optional().describe("Include disabled accounts (default: false)"),
+  crypto_only: z.boolean().optional().describe("Only show crypto wallets"),
+  cards_only: z.boolean().optional().describe("Only show payment cards"),
+});
+
+interface BalanceItem {
+  id: string;
+  type: "card" | "wallet";
+  name: string;
+  chain?: string;
+  balance?: string;
+  currency?: string;
+  usdValue?: number;
+  status: "active" | "disabled" | "error";
+  error?: string;
+}
+
+export async function execute(args: z.infer<typeof parameters>) {
+  const includeDisabled = args.include_disabled ?? false;
+  const items: BalanceItem[] = [];
+  let totalUsdValue = 0;
+
+  // Get cards (if not crypto_only)
+  if (!args.crypto_only) {
+    const cards = await getCardsSafe();
+    const filteredCards = includeDisabled ? cards : cards.filter(c => c.enabled);
+
+    for (const card of filteredCards) {
+      items.push({
+        id: card.id,
+        type: "card",
+        name: `${card.nickname} (****${card.lastFourDigits})`,
+        currency: card.limits?.currency || "EUR",
+        balance: "N/A", // Requires bank integration
+        status: card.enabled ? "active" : "disabled",
+      });
+    }
+  }
+
+  // Get wallets (if not cards_only)
+  if (!args.cards_only) {
+    const wallets = await getWalletsSafe();
+    const filteredWallets = includeDisabled ? wallets : wallets.filter(w => w.enabled);
+
+    // Fetch balances in parallel
+    const balancePromises = filteredWallets.map(async (wallet) => {
+      try {
+        const balance = await getWalletBalance(wallet.address, wallet.chain as Chain);
+        const price = await getUsdPrice(balance.nativeCurrency);
+        const usdValue = price ? parseFloat(balance.nativeBalanceFormatted) * price : undefined;
+
+        if (usdValue) {
+          totalUsdValue += usdValue;
+        }
+
+        return {
+          id: wallet.id,
+          type: "wallet" as const,
+          name: wallet.nickname,
+          chain: wallet.chain,
+          balance: balance.nativeBalanceFormatted,
+          currency: balance.nativeCurrency,
+          usdValue,
+          status: wallet.enabled ? "active" as const : "disabled" as const,
+        };
+      } catch (err) {
+        return {
+          id: wallet.id,
+          type: "wallet" as const,
+          name: wallet.nickname,
+          chain: wallet.chain,
+          status: "error" as const,
+          error: err instanceof Error ? err.message : "Failed to fetch balance",
+        };
+      }
+    });
+
+    const walletResults = await Promise.all(balancePromises);
+    items.push(...walletResults);
+  }
+
+  // Separate by type for summary
+  const cardItems = items.filter(i => i.type === "card");
+  const walletItems = items.filter(i => i.type === "wallet");
+  const errorItems = items.filter(i => i.status === "error");
+
+  return {
+    success: true,
+    summary: {
+      totalAccounts: items.length,
+      cards: cardItems.length,
+      wallets: walletItems.length,
+      errors: errorItems.length,
+      totalCryptoUsd: totalUsdValue > 0 ? `$${totalUsdValue.toFixed(2)}` : null,
+      note: cardItems.length > 0 ? "Card balances require bank integration (Plaid/Tink)" : undefined,
+    },
+    accounts: items.map(item => ({
+      id: item.id,
+      type: item.type,
+      name: item.name,
+      chain: item.chain,
+      balance: item.balance || "N/A",
+      currency: item.currency,
+      usdValue: item.usdValue ? `$${item.usdValue.toFixed(2)}` : null,
+      status: item.status,
+      ...(item.error && { error: item.error }),
+    })),
+  };
+}

package/src/tools/get-transactions.ts

@@ -0,0 +1,49 @@
+/**
+ * Get transaction history
+ */
+
+import { z } from "zod";
+import { getTransactions } from "../lib/cards";
+
+export const name = "get_transactions";
+
+export const description = "Get payment transaction history. Shows all bookings and payments made through the system.";
+
+export const parameters = z.object({
+  limit: z.number().optional().describe("Number of transactions to return (default: 20)"),
+  status: z.enum(["pending", "confirmed", "completed", "failed", "refunded"]).optional()
+    .describe("Filter by transaction status"),
+  type: z.enum(["flight", "train", "hotel", "other"]).optional()
+    .describe("Filter by transaction type"),
+});
+
+export async function execute(args: z.infer<typeof parameters>) {
+  let transactions = await getTransactions(args.limit ?? 20);
+  
+  if (args.status) {
+    transactions = transactions.filter((t) => t.status === args.status);
+  }
+  
+  if (args.type) {
+    transactions = transactions.filter((t) => t.type === args.type);
+  }
+  
+  if (transactions.length === 0) {
+    return { success: true, transactions: [], message: "No transactions found" };
+  }
+  
+  return {
+    success: true,
+    count: transactions.length,
+    transactions: transactions.map((t) => ({
+      id: t.id,
+      type: t.type,
+      amount: `${t.amount} ${t.currency}`,
+      description: t.description,
+      provider: t.provider,
+      status: t.status,
+      reference: t.reference ?? "N/A",
+      date: t.createdAt,
+    })),
+  };
+}

package/src/tools/get-wallet-balance.ts

@@ -0,0 +1,75 @@
+/**
+ * Get wallet balance via blockchain API
+ */
+
+import { z } from "zod";
+import { getWallet, getWalletsSafe, type Chain } from "../lib/wallets";
+import { getWalletBalance, getUsdPrice } from "../lib/blockchain";
+
+export const name = "get_wallet_balance";
+
+export const description = "Get the current balance of a crypto wallet. Fetches live data from the blockchain.";
+
+export const parameters = z.object({
+  wallet_id: z.string().optional().describe("Wallet ID (use list_wallets to see available wallets)"),
+  address: z.string().optional().describe("Wallet address (alternative to wallet_id)"),
+  chain: z.enum(["ethereum", "polygon", "arbitrum", "optimism", "base", "avalanche", "bsc", "bitcoin", "solana", "starknet"]).optional()
+    .describe("Blockchain (required if using address)"),
+  include_usd: z.boolean().optional().describe("Include USD value conversion (default: true)"),
+});
+
+export async function execute(args: z.infer<typeof parameters>) {
+  let address: string;
+  let chain: Chain;
+
+  // Get wallet by ID or use provided address
+  if (args.wallet_id) {
+    const wallet = await getWallet(args.wallet_id);
+    if (!wallet) {
+      return { success: false, error: `Wallet not found: ${args.wallet_id}` };
+    }
+    address = wallet.address;
+    chain = wallet.chain;
+  } else if (args.address && args.chain) {
+    address = args.address;
+    chain = args.chain;
+  } else {
+    return { 
+      success: false, 
+      error: "Provide either wallet_id or both address and chain" 
+    };
+  }
+
+  try {
+    const balance = await getWalletBalance(address, chain);
+    
+    // Get USD price if requested
+    let usdValue: number | null = null;
+    if (args.include_usd !== false) {
+      const price = await getUsdPrice(balance.nativeCurrency);
+      if (price) {
+        usdValue = parseFloat(balance.nativeBalanceFormatted) * price;
+      }
+    }
+
+    return {
+      success: true,
+      wallet: {
+        address: `${address.slice(0, 10)}...${address.slice(-8)}`,
+        fullAddress: address,
+        chain,
+      },
+      balance: {
+        native: balance.nativeBalanceFormatted,
+        currency: balance.nativeCurrency,
+        raw: balance.nativeBalance,
+        usdValue: usdValue ? `$${usdValue.toFixed(2)}` : null,
+      },
+    };
+  } catch (err) {
+    return {
+      success: false,
+      error: `Failed to fetch balance: ${err instanceof Error ? err.message : err}`,
+    };
+  }
+}

package/src/tools/list-cards.ts

@@ -0,0 +1,52 @@
+/**
+ * List saved payment cards (safe view - no full card numbers)
+ */
+
+import { z } from "zod";
+import { getCardsSafe } from "../lib/cards";
+
+export const name = "list_cards";
+
+export const description = "List all saved payment cards. Shows card type, last 4 digits, nickname, and allowed usage. Does NOT show full card numbers.";
+
+export const parameters = z.object({
+  enabled_only: z.boolean().optional().describe("Only show enabled cards"),
+  usage_type: z.enum(["flight", "train", "hotel", "general", "all"]).optional().describe("Filter by allowed usage type"),
+});
+
+export async function execute(args: z.infer<typeof parameters>) {
+  const cards = await getCardsSafe();
+  
+  let filtered = cards;
+  
+  if (args.enabled_only) {
+    filtered = filtered.filter((c) => c.enabled);
+  }
+  
+  if (args.usage_type) {
+    filtered = filtered.filter((c) => 
+      c.allowedUsage.includes(args.usage_type!) || c.allowedUsage.includes("all")
+    );
+  }
+  
+  if (filtered.length === 0) {
+    return { success: true, cards: [], message: "No cards found" };
+  }
+  
+  const summary = filtered.map((c) => ({
+    id: c.id,
+    nickname: c.nickname,
+    type: c.cardType.toUpperCase(),
+    lastFour: `****${c.lastFourDigits}`,
+    cardholder: c.cardholderName,
+    usage: c.allowedUsage.join(", "),
+    enabled: c.enabled,
+    lastUsed: c.lastUsedAt ?? "Never",
+  }));
+  
+  return {
+    success: true,
+    count: summary.length,
+    cards: summary,
+  };
+}

package/src/tools/list-wallet-transactions.ts

@@ -0,0 +1,83 @@
+/**
+ * List wallet transactions from blockchain
+ */
+
+import { z } from "zod";
+import { getWallet, type Chain } from "../lib/wallets";
+import { getWalletTransactions } from "../lib/blockchain";
+
+export const name = "list_wallet_transactions";
+
+export const description = "List recent transactions for a crypto wallet. Fetches live data from blockchain explorers.";
+
+export const parameters = z.object({
+  wallet_id: z.string().optional().describe("Wallet ID (use list_wallets to see available wallets)"),
+  address: z.string().optional().describe("Wallet address (alternative to wallet_id)"),
+  chain: z.enum(["ethereum", "polygon", "arbitrum", "optimism", "base", "avalanche", "bsc", "bitcoin", "solana", "starknet"]).optional()
+    .describe("Blockchain (required if using address)"),
+  limit: z.number().optional().describe("Number of transactions to return (default: 20, max: 50)"),
+});
+
+export async function execute(args: z.infer<typeof parameters>) {
+  let address: string;
+  let chain: Chain;
+
+  // Get wallet by ID or use provided address
+  if (args.wallet_id) {
+    const wallet = await getWallet(args.wallet_id);
+    if (!wallet) {
+      return { success: false, error: `Wallet not found: ${args.wallet_id}` };
+    }
+    address = wallet.address;
+    chain = wallet.chain;
+  } else if (args.address && args.chain) {
+    address = args.address;
+    chain = args.chain;
+  } else {
+    return { 
+      success: false, 
+      error: "Provide either wallet_id or both address and chain" 
+    };
+  }
+
+  const limit = Math.min(args.limit ?? 20, 50);
+
+  try {
+    const transactions = await getWalletTransactions(address, chain, limit);
+
+    if (transactions.length === 0) {
+      return {
+        success: true,
+        wallet: { address: `${address.slice(0, 10)}...${address.slice(-8)}`, chain },
+        transactions: [],
+        message: "No transactions found",
+      };
+    }
+
+    return {
+      success: true,
+      wallet: {
+        address: `${address.slice(0, 10)}...${address.slice(-8)}`,
+        fullAddress: address,
+        chain,
+      },
+      count: transactions.length,
+      transactions: transactions.map((tx) => ({
+        hash: `${tx.hash.slice(0, 10)}...${tx.hash.slice(-8)}`,
+        fullHash: tx.hash,
+        type: tx.isIncoming ? "RECEIVED" : "SENT",
+        amount: tx.valueFormatted,
+        from: tx.from ? `${tx.from.slice(0, 8)}...` : "N/A",
+        to: tx.to ? `${tx.to.slice(0, 8)}...` : "N/A",
+        status: tx.status,
+        date: new Date(tx.timestamp).toISOString(),
+        fee: tx.fee || null,
+      })),
+    };
+  } catch (err) {
+    return {
+      success: false,
+      error: `Failed to fetch transactions: ${err instanceof Error ? err.message : err}`,
+    };
+  }
+}

package/src/tools/list-wallets.ts

@@ -0,0 +1,63 @@
+/**
+ * List saved crypto wallets (safe view - no private keys)
+ */
+
+import { z } from "zod";
+import { getWalletsSafe, CHAIN_CONFIG } from "../lib/wallets";
+import type { Chain } from "../lib/wallets";
+
+export const name = "list_wallets";
+
+export const description = "List all saved crypto wallets. Shows address, chain, type, and allowed operations. Does NOT show private keys.";
+
+export const parameters = z.object({
+  chain: z.enum(["ethereum", "polygon", "arbitrum", "optimism", "base", "avalanche", "bsc", "bitcoin", "solana", "starknet"]).optional()
+    .describe("Filter by blockchain"),
+  type: z.enum(["hot", "watch-only", "hardware"]).optional()
+    .describe("Filter by wallet type"),
+  enabled_only: z.boolean().optional().describe("Only show enabled wallets"),
+});
+
+export async function execute(args: z.infer<typeof parameters>) {
+  const wallets = await getWalletsSafe();
+  
+  let filtered = wallets;
+  
+  if (args.chain) {
+    filtered = filtered.filter((w) => w.chain === args.chain);
+  }
+  
+  if (args.type) {
+    filtered = filtered.filter((w) => w.type === args.type);
+  }
+  
+  if (args.enabled_only) {
+    filtered = filtered.filter((w) => w.enabled);
+  }
+  
+  if (filtered.length === 0) {
+    return { success: true, wallets: [], message: "No wallets found" };
+  }
+  
+  const summary = filtered.map((w) => {
+    const chainInfo = CHAIN_CONFIG[w.chain as Chain];
+    return {
+      id: w.id,
+      nickname: w.nickname,
+      chain: chainInfo?.name ?? w.chain,
+      nativeCurrency: chainInfo?.nativeCurrency ?? "?",
+      address: `${w.address.slice(0, 10)}...${w.address.slice(-8)}`,
+      fullAddress: w.address,
+      type: w.type,
+      operations: w.allowedOperations.join(", "),
+      enabled: w.enabled,
+      lastUsed: w.lastUsedAt ?? "Never",
+    };
+  });
+  
+  return {
+    success: true,
+    count: summary.length,
+    wallets: summary,
+  };
+}