@framers/agentos-ext-wallet 0.2.0 → 0.2.1

package/src/cards/CardManager.ts

@@ -1,274 +0,0 @@
-// @ts-nocheck
-/**
- * @fileoverview High-level card lifecycle manager.
- *
- * Mirrors AgentWalletManager's pattern: one card per agent, spending policy
- * enforcement via the shared SpendingPolicyEnforcer, and in-memory/DB store
- * abstraction via ICardStore.
- *
- * @module wallet/cards/CardManager
- */
-
-import { v4 as uuidv4 } from 'uuid';
-import type { SpendingPolicyEnforcer } from '../SpendingPolicyEnforcer.js';
-import type { SpendCategory } from '../types.js';
-import type { MccCategoryMap } from './MccCategoryMap.js';
-import type {
-  AgentCardRecord,
-  CardConfig,
-  CardTransactionRecord,
-  ICardAdapter,
-  ICardStore,
-  LithicTransaction,
-  SpendingSummary,
-} from './types.js';
-
-// ---------------------------------------------------------------------------
-// CardManager
-// ---------------------------------------------------------------------------
-
-export interface CardManagerOptions {
-  adapter: ICardAdapter;
-  store: ICardStore;
-  policyEnforcer: SpendingPolicyEnforcer;
-  mccMap: MccCategoryMap;
-  config: CardConfig;
-}
-
-export class CardManager {
-  private readonly adapter: ICardAdapter;
-  private readonly store: ICardStore;
-  private readonly policy: SpendingPolicyEnforcer;
-  private readonly mccMap: MccCategoryMap;
-  private readonly config: CardConfig;
-
-  constructor(opts: CardManagerOptions) {
-    this.adapter = opts.adapter;
-    this.store = opts.store;
-    this.policy = opts.policyEnforcer;
-    this.mccMap = opts.mccMap;
-    this.config = opts.config;
-  }
-
-  // -----------------------------------------------------------------------
-  // Card lifecycle
-  // -----------------------------------------------------------------------
-
-  /**
-   * Issue a new virtual card for the agent.
-   * One card per agent — throws if card already exists.
-   */
-  async issueCard(
-    agentId: string,
-    opts?: { memo?: string; spendLimitUsd?: number },
-  ): Promise<AgentCardRecord> {
-    const existing = await this.store.getCard(agentId);
-    if (existing) {
-      throw new Error(`Agent ${agentId} already has a card (last4: ${existing.last4})`);
-    }
-
-    const spendLimit = opts?.spendLimitUsd ?? this.config.defaultSpendLimitUsd;
-
-    const lithicCard = await this.adapter.createCard({
-      type: 'VIRTUAL',
-      memo: opts?.memo || `Agent ${agentId} virtual card`,
-      spend_limit: Math.round(spendLimit * 100), // Lithic uses cents
-      spend_limit_duration: 'MONTHLY',
-      state: 'OPEN',
-    });
-
-    // Set auth rules for blocked categories
-    const blockedMccs = this.getBlockedMccs();
-    if (blockedMccs.length > 0) {
-      await this.adapter.createAuthRule(lithicCard.token, {
-        blocked_mcc: blockedMccs,
-      });
-    }
-
-    const record: AgentCardRecord = {
-      id: uuidv4(),
-      agentId,
-      lithicCardToken: lithicCard.token,
-      last4: lithicCard.last_four,
-      cardType: lithicCard.type,
-      state: lithicCard.state,
-      spendLimitUsd: spendLimit,
-      spendLimitDuration: 'MONTHLY',
-      network: 'VISA',
-      memo: opts?.memo,
-      createdAt: Date.now(),
-    };
-
-    await this.store.saveCard(record);
-    return record;
-  }
-
-  /** Get the agent's card record, or null. */
-  async getCard(agentId: string): Promise<AgentCardRecord | null> {
-    return this.store.getCard(agentId);
-  }
-
-  /**
-   * Get sensitive card details (PAN, CVV, expiry) for online payments.
-   * Enforces spending policy before revealing details.
-   */
-  async getCardDetails(
-    agentId: string,
-    estimatedAmountUsd?: number,
-    category?: SpendCategory,
-  ): Promise<{ last4: string; expMonth: string; expYear: string; cvv: string; pan: string }> {
-    const card = await this.requireCard(agentId);
-
-    // If an estimated amount is provided, check spending policy first
-    if (estimatedAmountUsd !== undefined) {
-      const check = await this.policy.canSpend(agentId, estimatedAmountUsd, category || 'shopping');
-      if (!check.allowed) {
-        throw new CardSpendingBlockedError(check.reason || 'Spending policy violation');
-      }
-    }
-
-    const lithicCard = await this.adapter.getCard(card.lithicCardToken);
-
-    return {
-      last4: lithicCard.last_four,
-      expMonth: lithicCard.exp_month || '',
-      expYear: lithicCard.exp_year || '',
-      cvv: lithicCard.cvv || '',
-      pan: lithicCard.pan || '',
-    };
-  }
-
-  /** Freeze (pause) the agent's card. */
-  async freezeCard(agentId: string): Promise<void> {
-    const card = await this.requireCard(agentId);
-    if (card.state === 'PAUSED') return;
-    if (card.state === 'CLOSED') throw new Error('Cannot freeze a closed card');
-
-    await this.adapter.pauseCard(card.lithicCardToken);
-    await this.store.updateCardState(agentId, 'PAUSED');
-  }
-
-  /** Unfreeze (resume) the agent's card. */
-  async unfreezeCard(agentId: string): Promise<void> {
-    const card = await this.requireCard(agentId);
-    if (card.state === 'OPEN') return;
-    if (card.state === 'CLOSED') throw new Error('Cannot unfreeze a closed card');
-
-    await this.adapter.resumeCard(card.lithicCardToken);
-    await this.store.updateCardState(agentId, 'OPEN');
-  }
-
-  /** Permanently close the agent's card. */
-  async closeCard(agentId: string): Promise<void> {
-    const card = await this.requireCard(agentId);
-    if (card.state === 'CLOSED') return;
-
-    await this.adapter.closeCard(card.lithicCardToken);
-    await this.store.updateCardState(agentId, 'CLOSED');
-  }
-
-  // -----------------------------------------------------------------------
-  // Spending summary
-  // -----------------------------------------------------------------------
-
-  async getSpendingSummary(agentId: string, period: 'day' | 'month' = 'month'): Promise<SpendingSummary> {
-    const card = await this.requireCard(agentId);
-
-    const now = new Date();
-    let since: number;
-    if (period === 'day') {
-      since = new Date(now.getFullYear(), now.getMonth(), now.getDate()).getTime();
-    } else {
-      since = new Date(now.getFullYear(), now.getMonth(), 1).getTime();
-    }
-
-    const txs = await this.store.getTransactionsByPeriod(card.id, since);
-    const settled = txs.filter(t => t.status === 'SETTLED' || t.status === 'PENDING');
-
-    const byCategory = new Map<SpendCategory, number>();
-    let totalUsd = 0;
-
-    for (const tx of settled) {
-      totalUsd += tx.amountUsd;
-      byCategory.set(tx.category, (byCategory.get(tx.category) || 0) + tx.amountUsd);
-    }
-
-    return {
-      totalUsd,
-      period,
-      byCategory: [...byCategory.entries()].map(([category, amountUsd]) => ({ category, amountUsd })),
-      transactionCount: settled.length,
-    };
-  }
-
-  // -----------------------------------------------------------------------
-  // Webhook processing
-  // -----------------------------------------------------------------------
-
-  /**
-   * Process a Lithic transaction webhook event.
-   * Resolves MCC → category and records the spend in the shared ledger.
-   */
-  async processWebhookTransaction(agentId: string, lithicTx: LithicTransaction): Promise<void> {
-    const card = await this.store.getCard(agentId);
-    if (!card) return; // Unknown card — ignore
-
-    const category = this.mccMap.mccToCategory(lithicTx.merchant.mcc);
-    const amountUsd = Math.abs(lithicTx.amount) / 100; // Lithic amounts are in cents
-
-    const txRecord: CardTransactionRecord = {
-      id: uuidv4(),
-      cardId: card.id,
-      lithicTxToken: lithicTx.token,
-      merchantName: lithicTx.merchant.descriptor,
-      merchantMcc: lithicTx.merchant.mcc,
-      category,
-      amountUsd,
-      status: lithicTx.status,
-      createdAt: Date.now(),
-    };
-
-    await this.store.insertTransaction(txRecord);
-
-    // Record in shared spending ledger (same as crypto sends)
-    if (lithicTx.status === 'SETTLED' || lithicTx.status === 'PENDING') {
-      await this.policy.recordSpend(agentId, amountUsd, category);
-    }
-  }
-
-  // -----------------------------------------------------------------------
-  // Internal helpers
-  // -----------------------------------------------------------------------
-
-  private async requireCard(agentId: string): Promise<AgentCardRecord> {
-    const card = await this.store.getCard(agentId);
-    if (!card) {
-      throw new Error(`No card found for agent ${agentId}. Issue one first.`);
-    }
-    return card;
-  }
-
-  /**
-   * Build a flat list of blocked MCC codes from the spending policy's
-   * blockedCategories, expanded via the MCC map.
-   */
-  private getBlockedMccs(): string[] {
-    // Access the policy's config to get blocked categories
-    // The SpendingPolicyEnforcer doesn't expose config directly,
-    // so we pass blocked categories through the card config or
-    // use the MCC map to expand known blocked categories.
-    // For now, this is handled at the extension pack level.
-    return [];
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Error classes
-// ---------------------------------------------------------------------------
-
-export class CardSpendingBlockedError extends Error {
-  constructor(reason: string) {
-    super(reason);
-    this.name = 'CardSpendingBlockedError';
-  }
-}

package/src/cards/LithicCardAdapter.ts

@@ -1,159 +0,0 @@
-// @ts-nocheck
-/**
- * @fileoverview Pure REST client for the Lithic card issuance API.
- *
- * No SDK dependency — uses fetch() directly. Supports sandbox and production
- * environments via configurable base URL.
- *
- * @see https://docs.lithic.com/reference
- * @module wallet/cards/LithicCardAdapter
- */
-
-import type {
-  AuthRuleParams,
-  CreateCardParams,
-  ICardAdapter,
-  LithicCardResponse,
-  LithicTransaction,
-  ListTxOpts,
-  UpdateCardParams,
-} from './types.js';
-
-// ---------------------------------------------------------------------------
-// Config
-// ---------------------------------------------------------------------------
-
-export interface LithicCardAdapterOptions {
-  apiKey: string;
-  /** Use sandbox environment. Defaults to true. */
-  sandbox?: boolean;
-  /** Override base URL (for testing). */
-  baseUrl?: string;
-}
-
-const SANDBOX_URL = 'https://sandbox.lithic.com/v1';
-const PRODUCTION_URL = 'https://api.lithic.com/v1';
-
-// ---------------------------------------------------------------------------
-// Adapter
-// ---------------------------------------------------------------------------
-
-export class LithicCardAdapter implements ICardAdapter {
-  private readonly apiKey: string;
-  private readonly baseUrl: string;
-
-  constructor(opts: LithicCardAdapterOptions) {
-    this.apiKey = opts.apiKey;
-    this.baseUrl = opts.baseUrl || (opts.sandbox !== false ? SANDBOX_URL : PRODUCTION_URL);
-  }
-
-  // -----------------------------------------------------------------------
-  // Card CRUD
-  // -----------------------------------------------------------------------
-
-  async createCard(params: CreateCardParams): Promise<LithicCardResponse> {
-    return this.post<LithicCardResponse>('/cards', params);
-  }
-
-  async getCard(cardToken: string): Promise<LithicCardResponse> {
-    return this.get<LithicCardResponse>(`/cards/${cardToken}`);
-  }
-
-  async updateCard(cardToken: string, updates: UpdateCardParams): Promise<LithicCardResponse> {
-    return this.patch<LithicCardResponse>(`/cards/${cardToken}`, updates);
-  }
-
-  async pauseCard(cardToken: string): Promise<void> {
-    await this.patch(`/cards/${cardToken}`, { state: 'PAUSED' });
-  }
-
-  async resumeCard(cardToken: string): Promise<void> {
-    await this.patch(`/cards/${cardToken}`, { state: 'OPEN' });
-  }
-
-  async closeCard(cardToken: string): Promise<void> {
-    await this.patch(`/cards/${cardToken}`, { state: 'CLOSED' });
-  }
-
-  // -----------------------------------------------------------------------
-  // Transactions
-  // -----------------------------------------------------------------------
-
-  async listTransactions(cardToken: string, opts?: ListTxOpts): Promise<LithicTransaction[]> {
-    const params = new URLSearchParams();
-    params.set('card_token', cardToken);
-    if (opts?.begin) params.set('begin', opts.begin);
-    if (opts?.end) params.set('end', opts.end);
-    if (opts?.page_size) params.set('page_size', String(opts.page_size));
-
-    const result = await this.get<{ data: LithicTransaction[] }>(`/transactions?${params.toString()}`);
-    return result.data;
-  }
-
-  // -----------------------------------------------------------------------
-  // Auth rules (MCC-based spending controls)
-  // -----------------------------------------------------------------------
-
-  async createAuthRule(cardToken: string, rule: AuthRuleParams): Promise<void> {
-    await this.post('/auth_rules', {
-      card_tokens: [cardToken],
-      ...rule,
-    });
-  }
-
-  // -----------------------------------------------------------------------
-  // HTTP helpers
-  // -----------------------------------------------------------------------
-
-  private async get<T>(path: string): Promise<T> {
-    return this.request<T>('GET', path);
-  }
-
-  private async post<T>(path: string, body: unknown): Promise<T> {
-    return this.request<T>('POST', path, body);
-  }
-
-  private async patch<T>(path: string, body: unknown): Promise<T> {
-    return this.request<T>('PATCH', path, body);
-  }
-
-  private async request<T>(method: string, path: string, body?: unknown): Promise<T> {
-    const url = `${this.baseUrl}${path}`;
-    const headers: Record<string, string> = {
-      'Authorization': this.apiKey,
-      'Accept': 'application/json',
-    };
-    if (body) headers['Content-Type'] = 'application/json';
-
-    const resp = await fetch(url, {
-      method,
-      headers,
-      body: body ? JSON.stringify(body) : undefined,
-    });
-
-    if (!resp.ok) {
-      const text = await resp.text().catch(() => '');
-      throw new LithicApiError(resp.status, `Lithic API error ${resp.status}: ${text}`, path);
-    }
-
-    // Some endpoints return no body (204)
-    if (resp.status === 204) return undefined as T;
-
-    return resp.json() as Promise<T>;
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Error
-// ---------------------------------------------------------------------------
-
-export class LithicApiError extends Error {
-  constructor(
-    public readonly statusCode: number,
-    message: string,
-    public readonly path: string,
-  ) {
-    super(message);
-    this.name = 'LithicApiError';
-  }
-}

package/src/cards/MccCategoryMap.ts

@@ -1,138 +0,0 @@
-// @ts-nocheck
-/**
- * @fileoverview Merchant Category Code (MCC) → SpendCategory mapping.
- *
- * Maps 4-digit MCC codes used by card networks to the wallet extension's
- * SpendCategory enum. Uses range-based matching for efficient lookup.
- *
- * @module wallet/cards/MccCategoryMap
- */
-
-import type { SpendCategory } from '../types.js';
-
-// ---------------------------------------------------------------------------
-// MCC range definitions
-// ---------------------------------------------------------------------------
-
-interface MccRange {
-  min: number;
-  max: number;
-  category: SpendCategory;
-}
-
-/**
- * Ordered list of MCC ranges → SpendCategory mappings.
- * Ranges are inclusive on both ends.
- */
-const MCC_RANGES: MccRange[] = [
-  // Travel: airlines, hotels, rental cars, travel agencies
-  { min: 3000, max: 3999, category: 'travel' },
-  { min: 4511, max: 4511, category: 'travel' },   // airlines
-  { min: 4722, max: 4722, category: 'travel' },   // travel agencies
-  { min: 7011, max: 7012, category: 'travel' },   // hotels, timeshares
-  { min: 7033, max: 7033, category: 'travel' },   // trailer parks
-  { min: 7512, max: 7519, category: 'travel' },   // car rental
-
-  // Utilities: telecom, electric, gas, water
-  { min: 4812, max: 4816, category: 'utilities' }, // telecom
-  { min: 4899, max: 4900, category: 'utilities' }, // cable, electric/gas/water
-
-  // Shopping: general retail
-  { min: 5200, max: 5499, category: 'shopping' },  // home supply, dept stores
-  { min: 5511, max: 5599, category: 'shopping' },  // auto dealers, auto parts
-  { min: 5600, max: 5699, category: 'shopping' },  // apparel
-  { min: 5700, max: 5799, category: 'shopping' },  // furniture, electronics
-  { min: 5900, max: 5999, category: 'shopping' },  // retail stores, misc
-
-  // Dining: restaurants, bars, fast food
-  { min: 5811, max: 5811, category: 'dining' },    // caterers
-  { min: 5812, max: 5812, category: 'dining' },    // eating places/restaurants
-  { min: 5813, max: 5813, category: 'dining' },    // bars/taverns
-  { min: 5814, max: 5814, category: 'dining' },    // fast food
-
-  // Subscriptions: digital goods/services
-  { min: 5815, max: 5818, category: 'subscriptions' }, // digital goods, games, apps, streaming
-
-  // Entertainment: movies, theaters, events, recreation
-  { min: 7832, max: 7833, category: 'entertainment' }, // movie theaters
-  { min: 7841, max: 7841, category: 'entertainment' }, // video tape rental
-  { min: 7911, max: 7911, category: 'entertainment' }, // dance halls/studios
-  { min: 7922, max: 7922, category: 'entertainment' }, // theatrical producers
-  { min: 7929, max: 7929, category: 'entertainment' }, // bands/orchestras
-  { min: 7932, max: 7933, category: 'entertainment' }, // billiards, bowling
-  { min: 7941, max: 7941, category: 'entertainment' }, // sports clubs/fields
-  { min: 7991, max: 7999, category: 'entertainment' }, // tourist attractions, recreation
-
-  // Web services: computer programming, data processing, IT
-  { min: 7372, max: 7379, category: 'web_services' }, // computer services
-  { min: 4816, max: 4816, category: 'web_services' }, // computer network/info services (re-mapped from utilities for precision)
-
-  // API costs: SaaS / cloud compute (commonly billed under computer services)
-  // Note: most SaaS bills under 7372 (web_services). If needed, specific
-  // merchant descriptors can override at the CardManager level.
-];
-
-// ---------------------------------------------------------------------------
-// Lookup class
-// ---------------------------------------------------------------------------
-
-export class MccCategoryMap {
-  private readonly ranges: MccRange[];
-
-  constructor() {
-    // Sort by min for binary-search-friendly access
-    this.ranges = [...MCC_RANGES].sort((a, b) => a.min - b.min);
-  }
-
-  /**
-   * Resolve a 4-digit MCC string to a SpendCategory.
-   * Returns 'other' if no matching range is found.
-   */
-  mccToCategory(mcc: string): SpendCategory {
-    const code = parseInt(mcc, 10);
-    if (isNaN(code)) return 'other';
-
-    for (const range of this.ranges) {
-      if (code >= range.min && code <= range.max) {
-        return range.category;
-      }
-    }
-    return 'other';
-  }
-
-  /**
-   * Get all MCC ranges that map to a given SpendCategory.
-   * Useful for building Lithic auth rules.
-   */
-  categoryToMccRanges(category: SpendCategory): Array<{ min: number; max: number }> {
-    return this.ranges
-      .filter(r => r.category === category)
-      .map(({ min, max }) => ({ min, max }));
-  }
-
-  /**
-   * Get all individual MCC codes for a category (expands ranges).
-   * Useful for Lithic's blocked_mcc list which expects individual codes.
-   */
-  categoryToMccCodes(category: SpendCategory): string[] {
-    const codes: string[] = [];
-    for (const range of this.ranges) {
-      if (range.category !== category) continue;
-      for (let code = range.min; code <= range.max; code++) {
-        codes.push(code.toString().padStart(4, '0'));
-      }
-    }
-    return codes;
-  }
-
-  /**
-   * Get all categories that have MCC mappings.
-   */
-  getMappedCategories(): SpendCategory[] {
-    const categories = new Set<SpendCategory>();
-    for (const range of this.ranges) {
-      categories.add(range.category);
-    }
-    return [...categories];
-  }
-}