@opencard-dev/core 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,194 @@
+/**
+ * OpenCard TypeScript Types and Interfaces
+ * Core data structures for Stripe Issuing wrapper
+ */
+/**
+ * OpenCard configuration for StripeClient initialization
+ */
+export interface OpenCardConfig {
+    /** Stripe secret API key (or reads from STRIPE_SECRET_KEY env) */
+    secretKey?: string;
+    /** Default spending rules applied to new cards if not overridden */
+    defaultRules?: SpendRule;
+    /** Stripe API version override (defaults to latest stable) */
+    apiVersion?: string;
+}
+/**
+ * Cardholder information
+ */
+export interface Cardholder {
+    id: string;
+    name: string;
+    email: string;
+    billing?: BillingDetails;
+    metadata?: Record<string, string>;
+    createdAt: Date;
+    status: 'active' | 'inactive';
+}
+/**
+ * Billing address details
+ */
+export interface BillingDetails {
+    line1: string;
+    line2?: string;
+    city: string;
+    state: string;
+    postalCode: string;
+    country: string;
+}
+/**
+ * Options for card creation
+ */
+export interface CardCreateOptions {
+    /** Agent or project name for this card */
+    agentName: string;
+    /**
+     * Human-readable description of what this card is for.
+     * Stored in Stripe card metadata as `opencard_description`.
+     * Helps agents pick the right card for each purchase.
+     * Example: "Engineering SaaS subscriptions — Vercel, AWS, Anthropic"
+     */
+    description?: string;
+    /**
+     * Custom rules for this card (overrides default).
+     *
+     * You can pass either `rules` (inline) or `ruleId` (a pre-created rule from
+     * the rules store). If you pass `rules` without a `ruleId`, the StripeClient
+     * will automatically create a rule in the store and use the returned ID.
+     *
+     * Prefer `ruleId` for production use — it keeps rule definitions out of
+     * Stripe metadata (where they'd be editable by anyone with Stripe access).
+     */
+    rules?: SpendRule;
+    /**
+     * ID of a pre-created rule in the rules store (e.g. "rule_018f1a2b...").
+     *
+     * This is the preferred way to attach rules to cards. The card metadata
+     * will store only this ID, not the full rule JSON. The webhook server
+     * looks up the actual rule from the store at authorization time.
+     *
+     * Create a rule ID with: `const ruleId = await rulesStore.createRule(myRule);`
+     */
+    ruleId?: string;
+    /** Card status: 'active' or 'inactive' */
+    status?: 'active' | 'inactive';
+    /** Custom metadata (tags, project ID, etc) */
+    metadata?: Record<string, string>;
+    /** Card replacement reason if replacing existing card */
+    replacement?: boolean;
+    /** Spending limits (alternative to rules) */
+    spendingLimits?: SpendingLimits;
+}
+/**
+ * Stripe spending limits format (for direct Stripe API calls)
+ */
+export interface SpendingLimits {
+    intervalType: 'per_authorization' | 'daily' | 'monthly' | 'all_time';
+    intervalCurrencyUnit: 'usd';
+    amount: number;
+}
+/**
+ * Virtual card representation
+ */
+export interface Card {
+    id: string;
+    last4: string;
+    brand: 'visa';
+    expiry: string;
+    status: 'active' | 'inactive' | 'canceled';
+    cardholderId: string;
+    agentName: string;
+    /**
+     * Human-readable description of what this card is for.
+     * Read from Stripe card metadata `opencard_description`.
+     * Null if no description was set at creation time.
+     */
+    description: string | null;
+    rules?: SpendRule;
+    spendingControls: SpendingLimits[];
+    metadata?: Record<string, string>;
+    createdAt: Date;
+    replacedAt?: Date;
+}
+/**
+ * Spend rule: defines what an agent card can and cannot do
+ */
+export interface SpendRule {
+    requiresApproval?: boolean;
+    approvalThreshold?: number;
+    allowedCategories?: string[];
+    blockedCategories?: string[];
+    maxPerTransaction?: number;
+    dailyLimit?: number;
+    monthlyLimit?: number;
+    spendingInterval?: 'per_authorization' | 'daily' | 'monthly' | 'all_time';
+    onFailure?: 'decline' | 'alert' | 'pause';
+    name?: string;
+    description?: string;
+}
+/**
+ * Pre-built spend rule templates for common patterns
+ */
+export type SpendRuleTemplate = 'balanced' | 'category_locked' | 'daily_limit' | 'approval_gated';
+/**
+ * Transaction representation
+ */
+export interface Transaction {
+    id: string;
+    cardId: string;
+    amount: number;
+    currency: string;
+    merchant: {
+        name: string;
+        category: string;
+        city?: string;
+        country?: string;
+    };
+    status: 'approved' | 'declined' | 'pending' | 'captured' | 'reversed';
+    declineReason?: string;
+    createdAt: Date;
+    metadata?: Record<string, string>;
+}
+/**
+ * Authorization event (pending transaction waiting for approval/decline)
+ */
+export interface Authorization {
+    id: string;
+    cardId: string;
+    amount: number;
+    currency: string;
+    merchant: {
+        name: string;
+        category: string;
+    };
+    createdAt: Date;
+    status: 'pending' | 'approved' | 'declined';
+}
+/**
+ * Card balance snapshot
+ */
+export interface CardBalance {
+    available: number;
+    reserved: number;
+    spent: number;
+    asOf: Date;
+}
+/**
+ * Transaction query options
+ */
+export interface TransactionQueryOptions {
+    limit?: number;
+    offset?: number;
+    startDate?: Date;
+    endDate?: Date;
+    status?: Transaction['status'];
+}
+/**
+ * Configuration for Stripe client operations
+ */
+export interface StripeOperationConfig {
+    idempotencyKey?: string;
+    timeout?: number;
+    retryCount?: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,7 @@
+"use strict";
+/**
+ * OpenCard TypeScript Types and Interfaces
+ * Core data structures for Stripe Issuing wrapper
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":";AAAA;;;GAGG"}

package/dist/webhooks.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Webhook Event Handlers
+ * ======================
+ * Stripe communicates real-time card activity to us via webhooks — HTTP POST
+ * requests that Stripe sends to our server whenever something happens.
+ *
+ * The most critical event is `issuing_authorization.request`:
+ *  - Stripe sends it SYNCHRONOUSLY when a card is swiped.
+ *  - We have ~2 seconds to respond with approve or decline.
+ *  - If we don't respond in time, Stripe declines by default.
+ *
+ * Other events (created, updated) are fire-and-forget notifications we use
+ * for logging and bookkeeping. They don't require a synchronous decision.
+ *
+ * ─── Stripe Issuing event flow ──────────────────────────────────────────────
+ *
+ *  Card swipe → Stripe → POST /webhooks/stripe (issuing_authorization.request)
+ *                              ↓
+ *                        evaluateAuthorization()
+ *                              ↓
+ *                        HTTP 200 { approved: true/false }
+ *                              ↓
+ *                        Stripe approves/declines at POS terminal
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ * Reference: https://stripe.com/docs/issuing/controls/real-time-authorizations
+ */
+import Stripe from 'stripe';
+import { SpendRule } from './types';
+import { TransactionReconciler } from './transaction-reconciler';
+/**
+ * Inject the reconciler instance (called at server startup, after DB init).
+ * If never called, reconciliation is skipped silently.
+ */
+export declare function setReconciler(r: TransactionReconciler): void;
+/**
+ * Get the current reconciler. Returns null if not initialized.
+ */
+export declare function getReconciler(): TransactionReconciler | null;
+/**
+ * Returned by handleAuthorizationRequest.
+ * The webhook server uses `approved` to set the HTTP response body,
+ * and `reason` is logged for debugging.
+ */
+export interface AuthorizationResult {
+    approved: boolean;
+    reason: string;
+}
+/**
+ * Looks up the SpendRules that apply to a given card.
+ *
+ * New behavior (Phase 2):
+ *  1. Look for `opencard_rule_id` in card metadata
+ *  2. Look up the rule from our rules store using that ID
+ *  3. If lookup fails for any reason, return DEFAULT_DENY_RULE
+ *
+ * Backward compatibility:
+ *  - If `opencard_rule_id` is not found, check for legacy `opencard_rules` JSON
+ *    in metadata. If found, parse and use it (but log a deprecation warning).
+ *  - If neither is found, return DEFAULT_DENY_RULE (previously returned `{}`)
+ *
+ * @param card - The Stripe Issuing.Card object from the authorization event
+ * @returns Resolved SpendRule — never null/undefined, always falls back to DEFAULT_DENY_RULE
+ */
+export declare function getRulesForCard(card: Stripe.Issuing.Card): Promise<SpendRule>;
+/**
+ * Handles `issuing_authorization.request`
+ * ─────────────────────────────────────────
+ * This is the real-time authorization handler — the most important webhook.
+ * Stripe calls this SYNCHRONOUSLY when a card is presented at a merchant.
+ * We must respond within ~2 seconds with { approved: true } or { approved: false }.
+ *
+ * What we do:
+ *  1. Extract the authorization details (card, amount, merchant category)
+ *  2. Look up the rules for this card
+ *  3. Run the rules engine against the current authorization + spend history
+ *  4. Return the decision
+ *  5. If approved, record the spend so future checks see up-to-date totals
+ *
+ * @param authorization - The Stripe Issuing.Authorization object
+ * @returns { approved, reason } — fed directly into the HTTP response
+ */
+export declare function handleAuthorizationRequest(authorization: Stripe.Issuing.Authorization): Promise<AuthorizationResult>;
+/**
+ * Handles `issuing_authorization.created`
+ * ─────────────────────────────────────────
+ * Fired after an authorization is definitively approved or declined.
+ * This is NOT the real-time request — it's a notification after the fact.
+ *
+ * Use this for logging, audit trails, and alerting. We don't make
+ * approve/decline decisions here.
+ *
+ * @param authorization - The completed Stripe Issuing.Authorization
+ */
+export declare function handleAuthorizationCreated(authorization: Stripe.Issuing.Authorization): void;
+/**
+ * Handles `issuing_transaction.created`
+ * ───────────────────────────────────────
+ * Fired when a transaction is fully captured (i.e., the merchant actually
+ * settled the charge). This happens after the authorization, sometimes days
+ * later (e.g., hotels that pre-auth then capture at checkout).
+ *
+ * The amount here may differ from the authorization amount — for example,
+ * a restaurant tip added after auth.
+ *
+ * Phase 2 will reconcile these with the tracker totals.
+ *
+ * @param transaction - The Stripe Issuing.Transaction
+ */
+export declare function handleTransactionCreated(transaction: Stripe.Issuing.Transaction): void;
+/**
+ * Handles `issuing_card.updated`
+ * ─────────────────────────────────
+ * Fired when a card's status, spending controls, or metadata changes.
+ * We log status changes so operators can see when cards are paused/resumed.
+ *
+ * @param card - The updated Stripe Issuing.Card
+ */
+export declare function handleCardUpdated(card: Stripe.Issuing.Card): void;
+//# sourceMappingURL=webhooks.d.ts.map

package/dist/webhooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhooks.d.ts","sourceRoot":"","sources":["../src/webhooks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,MAAM,MAAM,QAAQ,CAAC;AAC5B,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAKpC,OAAO,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AASjE;;;GAGG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,qBAAqB,GAAG,IAAI,CAE5D;AAED;;GAEG;AACH,wBAAgB,aAAa,IAAI,qBAAqB,GAAG,IAAI,CAE5D;AAID;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;CAChB;AA2BD;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE,MAAM,CAAC,OAAO,CAAC,IAAI,GAAG,OAAO,CAAC,SAAS,CAAC,CAyEnF;AAID;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,0BAA0B,CAC9C,aAAa,EAAE,MAAM,CAAC,OAAO,CAAC,aAAa,GAC1C,OAAO,CAAC,mBAAmB,CAAC,CA6D9B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,0BAA0B,CACxC,aAAa,EAAE,MAAM,CAAC,OAAO,CAAC,aAAa,GAC1C,IAAI,CAuBN;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,wBAAwB,CACtC,WAAW,EAAE,MAAM,CAAC,OAAO,CAAC,WAAW,GACtC,IAAI,CAoBN;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,CAAC,OAAO,CAAC,IAAI,GAAG,IAAI,CAEjE"}

package/dist/webhooks.js

@@ -0,0 +1,307 @@
+"use strict";
+/**
+ * Webhook Event Handlers
+ * ======================
+ * Stripe communicates real-time card activity to us via webhooks — HTTP POST
+ * requests that Stripe sends to our server whenever something happens.
+ *
+ * The most critical event is `issuing_authorization.request`:
+ *  - Stripe sends it SYNCHRONOUSLY when a card is swiped.
+ *  - We have ~2 seconds to respond with approve or decline.
+ *  - If we don't respond in time, Stripe declines by default.
+ *
+ * Other events (created, updated) are fire-and-forget notifications we use
+ * for logging and bookkeeping. They don't require a synchronous decision.
+ *
+ * ─── Stripe Issuing event flow ──────────────────────────────────────────────
+ *
+ *  Card swipe → Stripe → POST /webhooks/stripe (issuing_authorization.request)
+ *                              ↓
+ *                        evaluateAuthorization()
+ *                              ↓
+ *                        HTTP 200 { approved: true/false }
+ *                              ↓
+ *                        Stripe approves/declines at POS terminal
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ * Reference: https://stripe.com/docs/issuing/controls/real-time-authorizations
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setReconciler = setReconciler;
+exports.getReconciler = getReconciler;
+exports.getRulesForCard = getRulesForCard;
+exports.handleAuthorizationRequest = handleAuthorizationRequest;
+exports.handleAuthorizationCreated = handleAuthorizationCreated;
+exports.handleTransactionCreated = handleTransactionCreated;
+exports.handleCardUpdated = handleCardUpdated;
+const rules_engine_1 = require("./rules-engine");
+const tracker_1 = require("./tracker");
+const rules_store_1 = require("./rules-store");
+const rules_validation_1 = require("./rules-validation");
+const logger_1 = require("./logger");
+const logger = (0, logger_1.getLogger)('webhooks');
+// Module-level reconciler instance, used when no reconciler is injected.
+// Replaced at startup via setReconciler() for the live webhook server.
+let _reconciler = null;
+/**
+ * Inject the reconciler instance (called at server startup, after DB init).
+ * If never called, reconciliation is skipped silently.
+ */
+function setReconciler(r) {
+    _reconciler = r;
+}
+/**
+ * Get the current reconciler. Returns null if not initialized.
+ */
+function getReconciler() {
+    return _reconciler;
+}
+// ─── Rule resolver ─────────────────────────────────────────────────────────
+/**
+ * The default-deny rule used when a card has no valid rule ID or the rule lookup fails.
+ *
+ * ─── Why default-deny? ────────────────────────────────────────────────────────
+ * If a card's rule ID is missing or the lookup fails (e.g., rule was deleted,
+ * rules file is corrupted, rules store is unavailable), we want to DECLINE,
+ * not allow. The alternative — allowing all transactions when rules are missing
+ * — would mean a configuration error silently removes all spending controls.
+ * That's much worse than being overly restrictive.
+ *
+ * An operator who sees unexpected declines will investigate. An operator who
+ * sees unexpected approvals might not notice until damage is done.
+ */
+const DEFAULT_DENY_RULE = {
+    // maxPerTransaction: 0 would be rejected by validation, so we use 1 cent.
+    // The rules engine will decline any transaction over $0.01.
+    // More importantly, we set onFailure: 'decline' explicitly.
+    onFailure: 'decline',
+    maxPerTransaction: 1, // 1 cent — effectively declines everything
+    name: 'default-deny',
+    description: 'Default deny rule — applied when no valid rule is found for this card',
+};
+/**
+ * Looks up the SpendRules that apply to a given card.
+ *
+ * New behavior (Phase 2):
+ *  1. Look for `opencard_rule_id` in card metadata
+ *  2. Look up the rule from our rules store using that ID
+ *  3. If lookup fails for any reason, return DEFAULT_DENY_RULE
+ *
+ * Backward compatibility:
+ *  - If `opencard_rule_id` is not found, check for legacy `opencard_rules` JSON
+ *    in metadata. If found, parse and use it (but log a deprecation warning).
+ *  - If neither is found, return DEFAULT_DENY_RULE (previously returned `{}`)
+ *
+ * @param card - The Stripe Issuing.Card object from the authorization event
+ * @returns Resolved SpendRule — never null/undefined, always falls back to DEFAULT_DENY_RULE
+ */
+async function getRulesForCard(card) {
+    // card.metadata is a Record<string, string> — all values are strings.
+    const metadata = card.metadata ?? {};
+    // ── Case 1: New-style — look up by rule ID ──────────────────────────────────
+    const ruleId = metadata.opencard_rule_id;
+    if (ruleId) {
+        try {
+            const rule = await rules_store_1.rulesStore.getRule(ruleId);
+            if (rule) {
+                // Happy path: rule found in store
+                return rule;
+            }
+            // Rule ID exists in metadata but was not found in the store.
+            // This can happen if a rule was deleted without updating the card.
+            // Fall back to default-deny and log clearly so operators know.
+            console.error(`[Webhooks] ⚠️  Card ${card.id} references rule ID "${ruleId}" but that rule was not found in the store. ` +
+                `Did you delete the rule? Falling back to DEFAULT DENY — this card will decline all transactions.`);
+            return DEFAULT_DENY_RULE;
+        }
+        catch (err) {
+            // Unexpected error during rules store lookup (e.g., file system error)
+            console.error(`[Webhooks] ⚠️  Failed to look up rule "${ruleId}" for card ${card.id}: ${String(err)}. ` +
+                `Falling back to DEFAULT DENY.`);
+            return DEFAULT_DENY_RULE;
+        }
+    }
+    // ── Case 2: Backward compat — legacy opencard_rules JSON in metadata ────────
+    const legacyRaw = metadata.opencard_rules;
+    if (legacyRaw) {
+        console.warn(`[Webhooks] ⚠️  DEPRECATED: Card ${card.id} uses legacy opencard_rules metadata (full rule JSON in Stripe). ` +
+            `This is a security risk. Migrate this card to use opencard_rule_id with the rules store. ` +
+            `See docs/rules-engine.md for migration instructions.`);
+        try {
+            const parsed = JSON.parse(legacyRaw);
+            // Validate the parsed rule — don't trust raw JSON from Stripe metadata.
+            // This closes the same security hole the rules store was built to fix:
+            // without validation, anyone with Stripe dashboard access could inject
+            // malformed or malicious rules (e.g. negative limits that always pass).
+            const validation = (0, rules_validation_1.validateRule)(parsed);
+            if (!validation.valid) {
+                console.error(`[Webhooks] ⚠️  Legacy opencard_rules for card ${card.id} failed validation: ` +
+                    `${validation.errors.join(', ')}. Falling back to DEFAULT DENY.`);
+                return DEFAULT_DENY_RULE;
+            }
+            return parsed;
+        }
+        catch {
+            console.error(`[Webhooks] ⚠️  Failed to parse legacy opencard_rules for card ${card.id}. ` +
+                `Falling back to DEFAULT DENY.`);
+            return DEFAULT_DENY_RULE;
+        }
+    }
+    // ── Case 3: No rules at all ──────────────────────────────────────────────────
+    // Previously we returned {} here, which allowed everything. Now we default-deny.
+    console.error(`[Webhooks] ⚠️  Card ${card.id} has no opencard_rule_id or opencard_rules metadata. ` +
+        `Falling back to DEFAULT DENY — this card will decline all transactions. ` +
+        `Did you forget to attach a rule when creating the card?`);
+    return DEFAULT_DENY_RULE;
+}
+// ─── Event handlers ───────────────────────────────────────────────────────────
+/**
+ * Handles `issuing_authorization.request`
+ * ─────────────────────────────────────────
+ * This is the real-time authorization handler — the most important webhook.
+ * Stripe calls this SYNCHRONOUSLY when a card is presented at a merchant.
+ * We must respond within ~2 seconds with { approved: true } or { approved: false }.
+ *
+ * What we do:
+ *  1. Extract the authorization details (card, amount, merchant category)
+ *  2. Look up the rules for this card
+ *  3. Run the rules engine against the current authorization + spend history
+ *  4. Return the decision
+ *  5. If approved, record the spend so future checks see up-to-date totals
+ *
+ * @param authorization - The Stripe Issuing.Authorization object
+ * @returns { approved, reason } — fed directly into the HTTP response
+ */
+async function handleAuthorizationRequest(authorization) {
+    const cardId = typeof authorization.card === 'string'
+        ? authorization.card
+        : authorization.card.id;
+    // Log enough context to debug any issues after the fact.
+    console.log(`[Auth] Request ${authorization.id} | card=${cardId} | amount=${authorization.amount}¢ | merchant=${authorization.merchant_data?.name} | mcc=${authorization.merchant_data?.category}`);
+    // ── Get the card's rules ─────────────────────────────────────────────
+    // The card object is embedded in the authorization event — no extra API
+    // call needed. We look up the rules from our rules store using the rule ID
+    // stored in card metadata. If the rule can't be found, we get default-deny.
+    const card = authorization.card;
+    const rules = await getRulesForCard(card);
+    // ── Pull current spend totals ────────────────────────────────────────
+    // The tracker holds running daily/monthly totals so the rules engine can
+    // check "would this push us over the limit?"
+    const dailySpend = tracker_1.tracker.getDailySpend(cardId);
+    const monthlySpend = tracker_1.tracker.getMonthlySpend(cardId);
+    // ── Evaluate the authorization ───────────────────────────────────────
+    // The rules engine checks all applicable rules (category, amount limit,
+    // daily budget, monthly budget, confidence) and returns a decision.
+    const decision = (0, rules_engine_1.evaluateAuthorization)(authorization, rules, {
+        dailySpend,
+        monthlySpend,
+    });
+    // ── Record approved spend immediately ───────────────────────────────
+    // If approved, we immediately add this amount to the running totals.
+    // This prevents a race condition where two simultaneous authorizations
+    // both see the pre-approval total and both get approved even though
+    // together they exceed the limit.
+    //
+    // Note: Stripe may later reverse the transaction (e.g. if the merchant
+    // cancels). Phase 2 will handle reversals. For now we're conservative.
+    if (decision.approved) {
+        tracker_1.tracker.addTransaction(cardId, authorization.amount);
+        console.log(`[Auth] ✓ APPROVED ${authorization.id} — ${decision.reason}`);
+    }
+    else {
+        console.log(`[Auth] ✗ DECLINED ${authorization.id} — ${decision.reason}`);
+    }
+    // ── Persist to SQLite (non-blocking) ────────────────────────────────────
+    // DB errors must NEVER block the 2s SLA. Wrap in try/catch, log failures.
+    if (_reconciler) {
+        try {
+            _reconciler.handleAuthorizationRequest(authorization, decision.reason);
+        }
+        catch (err) {
+            logger.error('Failed to persist authorization request to DB — decision not affected', {
+                stripe_id: authorization.id,
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    return {
+        approved: decision.approved,
+        reason: decision.reason,
+    };
+}
+/**
+ * Handles `issuing_authorization.created`
+ * ─────────────────────────────────────────
+ * Fired after an authorization is definitively approved or declined.
+ * This is NOT the real-time request — it's a notification after the fact.
+ *
+ * Use this for logging, audit trails, and alerting. We don't make
+ * approve/decline decisions here.
+ *
+ * @param authorization - The completed Stripe Issuing.Authorization
+ */
+function handleAuthorizationCreated(authorization) {
+    const cardId = typeof authorization.card === 'string'
+        ? authorization.card
+        : authorization.card.id;
+    // Stripe stores the final approval status on the `approved` field.
+    const status = authorization.approved ? 'approved' : 'declined';
+    console.log(`[Auth] Created: ${authorization.id} | status=${status} | card=${cardId} | amount=${authorization.amount}¢ | merchant=${authorization.merchant_data?.name}`);
+    // Persist status update to SQLite
+    if (_reconciler) {
+        try {
+            _reconciler.handleAuthorizationCreated(authorization);
+        }
+        catch (err) {
+            logger.error('Failed to persist authorization.created to DB', {
+                stripe_id: authorization.id,
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+}
+/**
+ * Handles `issuing_transaction.created`
+ * ───────────────────────────────────────
+ * Fired when a transaction is fully captured (i.e., the merchant actually
+ * settled the charge). This happens after the authorization, sometimes days
+ * later (e.g., hotels that pre-auth then capture at checkout).
+ *
+ * The amount here may differ from the authorization amount — for example,
+ * a restaurant tip added after auth.
+ *
+ * Phase 2 will reconcile these with the tracker totals.
+ *
+ * @param transaction - The Stripe Issuing.Transaction
+ */
+function handleTransactionCreated(transaction) {
+    const cardId = typeof transaction.card === 'string'
+        ? transaction.card
+        : transaction.card?.id || 'unknown';
+    console.log(`[Tx] Created: ${transaction.id} | card=${cardId} | amount=${transaction.amount}¢ | merchant=${transaction.merchant_data?.name} | category=${transaction.merchant_data?.category}`);
+    // Persist transaction to SQLite
+    if (_reconciler) {
+        try {
+            _reconciler.handleTransactionCreated(transaction);
+        }
+        catch (err) {
+            logger.error('Failed to persist transaction.created to DB', {
+                stripe_id: transaction.id,
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+}
+/**
+ * Handles `issuing_card.updated`
+ * ─────────────────────────────────
+ * Fired when a card's status, spending controls, or metadata changes.
+ * We log status changes so operators can see when cards are paused/resumed.
+ *
+ * @param card - The updated Stripe Issuing.Card
+ */
+function handleCardUpdated(card) {
+    console.log(`[Card] Updated: ${card.id} | status=${card.status}`);
+}
+//# sourceMappingURL=webhooks.js.map

package/dist/webhooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhooks.js","sourceRoot":"","sources":["../src/webhooks.ts"],"names":[],"mappings":"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"}