@opencard-dev/core 0.1.0

package/dist/stripe-client.js

@@ -0,0 +1,444 @@
+"use strict";
+/**
+ * StripeClient
+ * ============
+ * A clean, typed wrapper around Stripe's Issuing API.
+ *
+ * Stripe's Issuing product lets you create virtual (and physical) payment cards
+ * programmatically. OpenCard uses it to give AI agents their own cards with
+ * spending controls attached.
+ *
+ * ─── Why a wrapper? ─────────────────────────────────────────────────────────
+ * The raw Stripe SDK is powerful but returns Stripe's own types, which don't
+ * always match what OpenCard needs. This wrapper:
+ *  - Converts Stripe's snake_case fields to camelCase (matches our TypeScript style)
+ *  - Maps Stripe's types to our internal interfaces (Card, Cardholder, etc.)
+ *  - Centralizes error handling in one place
+ *  - Makes the API surface smaller and easier to understand
+ *
+ * ─── Stripe API version ─────────────────────────────────────────────────────
+ * We pin to "2023-10-16". If you upgrade the Stripe SDK, check if the API
+ * version needs updating and whether any field names/types changed.
+ *
+ * ─── Test vs. Live mode ─────────────────────────────────────────────────────
+ * Stripe uses the key prefix to determine mode:
+ *   sk_test_... → test mode (no real money, safe to experiment)
+ *   sk_live_... → live mode (REAL money — be careful!)
+ * Never commit a live key to git.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StripeClient = void 0;
+const stripe_1 = __importDefault(require("stripe"));
+const rules_store_1 = require("./rules-store");
+const errors_1 = require("./errors");
+class StripeClient {
+    /** The underlying Stripe SDK instance. Use this for any Stripe calls not yet wrapped here. */
+    stripe;
+    /** Stored config so we can reference it in later operations. */
+    config;
+    /**
+     * Creates a new StripeClient.
+     *
+     * @param config - Optional configuration. If omitted, reads from environment variables.
+     *
+     * @throws Error if no API key is found (neither in config nor in STRIPE_SECRET_KEY env var)
+     *
+     * @example
+     * // Use environment variable (recommended for production)
+     * const client = new StripeClient();
+     *
+     * // Pass key directly (good for testing)
+     * const client = new StripeClient({ secretKey: 'sk_test_...' });
+     */
+    constructor(config = {}) {
+        // The API key can come from either the config object or the environment variable.
+        // If neither is set, we throw early with a helpful message.
+        const secretKey = config.secretKey || process.env.STRIPE_SECRET_KEY;
+        // Check if key is missing or empty
+        if (!secretKey || secretKey.trim() === '') {
+            throw new errors_1.StripeAuthenticationError('STRIPE_SECRET_KEY not set. Get your test key from https://dashboard.stripe.com/apikeys', { source: 'config' });
+        }
+        // Validate key format
+        const trimmedKey = secretKey.trim();
+        if (!trimmedKey.startsWith('sk_test_') && !trimmedKey.startsWith('sk_live_')) {
+            console.warn('STRIPE_SECRET_KEY looks invalid — test keys start with sk_test_, live keys with sk_live_');
+        }
+        // Initialize the Stripe SDK. The apiVersion pin ensures consistent behavior
+        // even if the SDK package is updated.
+        this.stripe = new stripe_1.default(trimmedKey, {
+            apiVersion: '2023-10-16',
+        });
+        this.config = {
+            secretKey: trimmedKey,
+            // defaultRules is optional — if not provided, use an empty rule set
+            defaultRules: config.defaultRules ?? {},
+            apiVersion: config.apiVersion || '2023-10-16',
+        };
+    }
+    // ─── Cardholders ────────────────────────────────────────────────────────────
+    /**
+     * Creates a new cardholder in Stripe Issuing.
+     *
+     * A cardholder is the entity that "owns" the cards. In a typical OpenCard
+     * setup, you'd create one cardholder per agent or per project, then create
+     * multiple cards under that cardholder.
+     *
+     * Stripe requires a billing address for cardholders in most configurations.
+     * In test mode this requirement may be relaxed.
+     *
+     * @param name - Display name for the cardholder (e.g. "Atlas Agent", "Research Bot")
+     * @param email - Contact email (used by Stripe for notifications)
+     * @param billing - Billing address (required for live mode)
+     * @returns The created Cardholder object
+     */
+    async createCardholder(name, email, billing) {
+        try {
+            const cardholder = await this.stripe.issuing.cardholders.create({
+                name,
+                email,
+                type: 'individual', // Stripe supports 'individual' and 'company'
+                billing: billing
+                    ? {
+                        address: {
+                            line1: billing.line1,
+                            line2: billing.line2,
+                            city: billing.city,
+                            state: billing.state,
+                            postal_code: billing.postalCode,
+                            country: billing.country,
+                        },
+                    }
+                    : {
+                        // Stripe requires a billing field even if minimal.
+                        // In test mode, a placeholder address is acceptable.
+                        address: {
+                            line1: '354 Oyster Point Blvd',
+                            city: 'South San Francisco',
+                            state: 'CA',
+                            postal_code: '94080',
+                            country: 'US',
+                        },
+                    },
+                status: 'active',
+            });
+            // Map Stripe's response to our internal Cardholder type.
+            // Note: Stripe's `email` field can be null, so we fall back to the
+            // input email (which we know is a string since the caller passed it).
+            return {
+                id: cardholder.id,
+                name: cardholder.name,
+                email: cardholder.email ?? email,
+                billing,
+                createdAt: new Date(cardholder.created * 1000), // Stripe uses Unix timestamps (seconds)
+                status: 'active',
+            };
+        }
+        catch (error) {
+            throw (0, errors_1.wrapStripeError)(error, 'Failed to create cardholder', 'stripe-client', { name, email });
+        }
+    }
+    // ─── Cards ──────────────────────────────────────────────────────────────────
+    /**
+     * Creates a new virtual card for an agent.
+     *
+     * The card is issued under the specified cardholder. Spending limits can be
+     * applied either via Stripe's native spending_controls (enforced at the
+     * Stripe level, last-resort safeguard) or via OpenCard's rules engine
+     * (enforced via the webhook server, smarter but requires the server to be running).
+     *
+     * The `agentName` is stored in card metadata so you can identify which
+     * agent this card belongs to when reviewing Stripe dashboard or logs.
+     *
+     * @param cardholderId - The Stripe cardholder ID (e.g. "ich_abc123")
+     * @param options - Card creation options (name, rules, status, metadata)
+     * @returns The created Card object
+     */
+    async createCard(cardholderId, options) {
+        try {
+            // ── Resolve the rule ID ───────────────────────────────────────────────
+            // We want to store only a rule reference ID in Stripe metadata, not the
+            // full rule JSON. This prevents anyone with Stripe dashboard access from
+            // modifying rules by editing card metadata.
+            //
+            // Three cases:
+            //  1. Caller passed `ruleId` directly → use it as-is
+            //  2. Caller passed `rules` (inline) without a ruleId → auto-create in store
+            //  3. Neither passed → no rules on this card
+            let resolvedRuleId = options.ruleId;
+            if (!resolvedRuleId && options.rules) {
+                // Auto-migrate: create the inline rules in the store and use the returned ID.
+                // This maintains backward compatibility — callers don't HAVE to know about
+                // the rules store, it just happens automatically.
+                console.log(`[StripeClient] createCard: inline rules provided without ruleId — auto-creating in rules store`);
+                resolvedRuleId = await rules_store_1.rulesStore.createRule(options.rules);
+                console.log(`[StripeClient] createCard: auto-created rule ${resolvedRuleId} for card under cardholder ${cardholderId}`);
+            }
+            const card = await this.stripe.issuing.cards.create({
+                cardholder: cardholderId,
+                currency: 'usd',
+                type: 'virtual', // We only create virtual cards (no physical plastic)
+                status: options.status || 'active',
+                // spending_controls are Stripe-native limits — they're enforced even if
+                // our webhook server is down. Think of them as the safety net under the net.
+                spending_controls: options.spendingLimits
+                    ? {
+                        spending_limits: [
+                            {
+                                amount: options.spendingLimits.amount,
+                                interval: options.spendingLimits.intervalType,
+                            },
+                        ],
+                    }
+                    : undefined,
+                metadata: {
+                    // Store the agent name so we can identify this card in Stripe's dashboard
+                    // and in our webhook logs.
+                    agentName: options.agentName,
+                    // Store only the rule reference ID, not the full rule JSON.
+                    // The webhook server will look up the actual rule from our rules store.
+                    // This is the core security improvement: Stripe metadata no longer holds
+                    // the actual rules, so modifying metadata cannot change spending behavior.
+                    ...(resolvedRuleId ? { opencard_rule_id: resolvedRuleId } : {}),
+                    // Human-readable description of what this card is for. Helps agents
+                    // pick the right card at purchase time without guessing from limits alone.
+                    ...(options.description ? { opencard_description: options.description } : {}),
+                    // Spread any caller-provided custom metadata (project IDs, tags, etc.)
+                    ...options.metadata,
+                },
+            });
+            return mapCardResponse(card, cardholderId, options);
+        }
+        catch (error) {
+            throw (0, errors_1.wrapStripeError)(error, 'Failed to create card', 'stripe-client', { cardholderId, ruleId: options.ruleId });
+        }
+    }
+    /**
+     * Retrieves a card by its Stripe card ID.
+     * Useful for checking current status, limits, and metadata.
+     *
+     * @param cardId - Stripe card ID (e.g. "ic_abc123")
+     */
+    async getCard(cardId) {
+        try {
+            const card = await this.stripe.issuing.cards.retrieve(cardId);
+            const cardholderId = typeof card.cardholder === 'string'
+                ? card.cardholder
+                : card.cardholder?.id || '';
+            return mapCardResponse(card, cardholderId, {
+                agentName: card.metadata?.agentName || 'unknown',
+            });
+        }
+        catch (error) {
+            throw (0, errors_1.wrapStripeError)(error, 'Failed to get card', 'stripe-client', { cardId });
+        }
+    }
+    /**
+     * Pauses a card by setting its status to 'inactive'.
+     *
+     * A paused card will decline all new charges but can be resumed later.
+     * This is different from canceling — canceled cards cannot be reactivated.
+     *
+     * Use this when an agent has violated rules and needs to be stopped temporarily,
+     * or when you want to manually review spending before re-enabling.
+     *
+     * @param cardId - Stripe card ID to pause
+     */
+    async pauseCard(cardId) {
+        try {
+            const card = await this.stripe.issuing.cards.update(cardId, {
+                status: 'inactive', // Stripe's term for "paused" on virtual cards
+            });
+            const cardholderId = typeof card.cardholder === 'string'
+                ? card.cardholder
+                : card.cardholder?.id || '';
+            return mapCardResponse(card, cardholderId, {
+                agentName: card.metadata?.agentName || 'unknown',
+            });
+        }
+        catch (error) {
+            throw (0, errors_1.wrapStripeError)(error, 'Failed to pause card', 'stripe-client', { cardId });
+        }
+    }
+    /**
+     * Resumes a paused card by setting its status back to 'active'.
+     * The card will accept new charges again immediately after this call.
+     *
+     * @param cardId - Stripe card ID to resume
+     */
+    async resumeCard(cardId) {
+        try {
+            const card = await this.stripe.issuing.cards.update(cardId, {
+                status: 'active',
+            });
+            const cardholderId = typeof card.cardholder === 'string'
+                ? card.cardholder
+                : card.cardholder?.id || '';
+            return mapCardResponse(card, cardholderId, {
+                agentName: card.metadata?.agentName || 'unknown',
+            });
+        }
+        catch (error) {
+            throw (0, errors_1.wrapStripeError)(error, 'Failed to resume card', 'stripe-client', { cardId });
+        }
+    }
+    /**
+     * Updates the spending limits on a card.
+     *
+     * These are Stripe-native limits (not OpenCard rules). They're enforced at
+     * the Stripe level regardless of whether our webhook server is running.
+     * Good for setting hard floors that can never be bypassed.
+     *
+     * @param cardId - Stripe card ID
+     * @param limits - Array of spending limit objects
+     */
+    async setSpendingLimits(cardId, limits) {
+        try {
+            const card = await this.stripe.issuing.cards.update(cardId, {
+                spending_controls: {
+                    spending_limits: limits.map((limit) => ({
+                        amount: limit.amount,
+                        interval: limit.intervalType,
+                    })),
+                },
+            });
+            const cardholderId = typeof card.cardholder === 'string'
+                ? card.cardholder
+                : card.cardholder?.id || '';
+            return mapCardResponse(card, cardholderId, {
+                agentName: card.metadata?.agentName || 'unknown',
+                spendingLimits: limits[0], // Return the first limit for display purposes
+            });
+        }
+        catch (error) {
+            throw (0, errors_1.wrapStripeError)(error, 'Failed to set spending limits', 'stripe-client', { cardId, limits });
+        }
+    }
+    // ─── Transactions ────────────────────────────────────────────────────────────
+    /**
+     * Retrieves the transaction history for a card.
+     *
+     * Note: Stripe Issuing transactions are distinct from regular Stripe charges.
+     * They represent captured spending on issued cards.
+     *
+     * Note on Stripe v14 Transaction type: The `status` and `decline_reason` fields
+     * don't exist on Issuing.Transaction in the v14 type definitions (the transaction
+     * object represents *completed* captures, not pending authorizations). For
+     * pending/declined status, use the Issuing.Authorization type instead.
+     *
+     * @param cardId - Stripe card ID
+     * @param options - Optional filters (limit, date range, etc.)
+     */
+    async getTransactions(cardId, options) {
+        try {
+            const transactions = await this.stripe.issuing.transactions.list({
+                card: cardId,
+                limit: options?.limit || 100,
+            });
+            return transactions.data.map((tx) => ({
+                id: tx.id,
+                // tx.card can be either a card ID string or a full Card object
+                cardId: typeof tx.card === 'string' ? tx.card : tx.card?.id || '',
+                amount: tx.amount,
+                currency: tx.currency,
+                merchant: {
+                    name: tx.merchant_data?.name || 'Unknown',
+                    category: tx.merchant_data?.category || 'unknown',
+                    // Stripe returns null for optional geo fields — convert to undefined
+                    // for consistency with our Transaction type (which uses string | undefined)
+                    city: tx.merchant_data?.city ?? undefined,
+                    country: tx.merchant_data?.country ?? undefined,
+                },
+                // Issuing transactions represent completed captures, so status is always 'captured'
+                // unless the transaction was reversed.
+                status: tx.type === 'capture' ? 'captured' : 'reversed',
+                createdAt: new Date(tx.created * 1000),
+                metadata: tx.metadata || {},
+            }));
+        }
+        catch (error) {
+            throw (0, errors_1.wrapStripeError)(error, 'Failed to get transactions', 'stripe-client', { cardId });
+        }
+    }
+    // ─── Balance ─────────────────────────────────────────────────────────────────
+    /**
+     * Returns a balance snapshot for this account.
+     *
+     * Note: Stripe Issuing doesn't expose a per-card balance API. The "balance"
+     * for virtual cards is determined by your spending limits, not a pre-loaded
+     * amount. This is a stub that returns zeroes.
+     *
+     * Phase 2 will compute this by summing transactions against spending limits.
+     */
+    async getBalance() {
+        return {
+            available: 0,
+            reserved: 0,
+            spent: 0,
+            asOf: new Date(),
+        };
+    }
+    /**
+     * Returns pending authorizations for a card.
+     *
+     * Stripe doesn't provide a REST API for pending authorizations — they're
+     * delivered exclusively via webhooks. This stub exists for API completeness.
+     * Phase 1 uses the webhook server for real-time authorization handling.
+     *
+     * @param _cardId - Card ID (unused in Phase 1)
+     */
+    async getPendingAuthorizations(_cardId) {
+        // In Phase 1, authorizations are handled via webhooks, not polling.
+        // The webhook server receives issuing_authorization.request events in real time.
+        // This endpoint is here for future use (Phase 2 may add a polling fallback).
+        return [];
+    }
+}
+exports.StripeClient = StripeClient;
+// ─── Internal helpers ─────────────────────────────────────────────────────────
+/**
+ * Converts a Stripe.Issuing.Card response into our internal Card type.
+ *
+ * This helper is used by multiple methods (createCard, getCard, pauseCard, etc.)
+ * to avoid duplicating the mapping logic. Any time the Stripe SDK returns a card
+ * object, we run it through this function to get our clean Card interface.
+ *
+ * @param card - Raw Stripe.Issuing.Card from the SDK
+ * @param cardholderId - The cardholder's ID string
+ * @param options - The original creation options (for agentName and rules)
+ */
+function mapCardResponse(card, cardholderId, options) {
+    // Stripe stores expiry as separate month/year integers.
+    // We combine them into MM/YY format (e.g. "03/28" for March 2028).
+    const expiry = `${String(card.exp_month).padStart(2, '0')}/${String(card.exp_year).slice(-2)}`;
+    // card.metadata is typed as Stripe.Metadata (Record<string, string>), but
+    // can be null in some edge cases. We cast to our expected shape.
+    const metadata = card.metadata;
+    return {
+        id: card.id,
+        last4: card.last4,
+        brand: 'visa', // Stripe Issuing only issues Visa cards (in the US)
+        expiry,
+        // Stripe card status: 'active', 'inactive', or 'canceled'
+        status: card.status,
+        cardholderId,
+        agentName: metadata?.agentName || options.agentName || 'unknown',
+        // Human-readable description of what this card is for.
+        // Stored in Stripe metadata as opencard_description. Null if not set.
+        description: metadata?.opencard_description ?? null,
+        rules: options.rules,
+        // Stripe returns spending limits as an array of SpendingLimit objects.
+        // Our SpendingLimits type has different field names (camelCase vs snake_case),
+        // so we map them here. If there are no limits set, return an empty array.
+        spendingControls: (card.spending_controls?.spending_limits || []).map((sl) => ({
+            amount: sl.amount,
+            intervalType: sl.interval,
+            intervalCurrencyUnit: 'usd',
+        })),
+        metadata: metadata ?? undefined,
+        createdAt: new Date(card.created * 1000),
+    };
+}
+//# sourceMappingURL=stripe-client.js.map

package/dist/stripe-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stripe-client.js","sourceRoot":"","sources":["../src/stripe-client.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;;;;;;AAEH,oDAA4B;AAa5B,+CAA2C;AAC3C,qCAAsE;AAEtE,MAAa,YAAY;IACvB,8FAA8F;IACtF,MAAM,CAAS;IACvB,gEAAgE;IACxD,MAAM,CAA2B;IAEzC;;;;;;;;;;;;;OAaG;IACH,YAAY,SAAyB,EAAE;QACrC,kFAAkF;QAClF,4DAA4D;QAC5D,MAAM,SAAS,GAAG,MAAM,CAAC,SAAS,IAAI,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAC;QAEpE,mCAAmC;QACnC,IAAI,CAAC,SAAS,IAAI,SAAS,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;YAC1C,MAAM,IAAI,kCAAyB,CACjC,wFAAwF,EACxF,EAAE,MAAM,EAAE,QAAQ,EAAE,CACrB,CAAC;QACJ,CAAC;QAED,sBAAsB;QACtB,MAAM,UAAU,GAAG,SAAS,CAAC,IAAI,EAAE,CAAC;QACpC,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC,UAAU,CAAC,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;YAC7E,OAAO,CAAC,IAAI,CACV,0FAA0F,CAC3F,CAAC;QACJ,CAAC;QAED,4EAA4E;QAC5E,sCAAsC;QACtC,IAAI,CAAC,MAAM,GAAG,IAAI,gBAAM,CAAC,UAAU,EAAE;YACnC,UAAU,EAAE,YAAY;SACzB,CAAC,CAAC;QAEH,IAAI,CAAC,MAAM,GAAG;YACZ,SAAS,EAAE,UAAU;YACrB,oEAAoE;YACpE,YAAY,EAAE,MAAM,CAAC,YAAY,IAAI,EAAE;YACvC,UAAU,EAAE,MAAM,CAAC,UAAU,IAAI,YAAY;SAC9C,CAAC;IACJ,CAAC;IAED,+EAA+E;IAE/E;;;;;;;;;;;;;;OAcG;IACH,KAAK,CAAC,gBAAgB,CACpB,IAAY,EACZ,KAAa,EACb,OAAwB;QAExB,IAAI,CAAC;YACH,MAAM,UAAU,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,WAAW,CAAC,MAAM,CAAC;gBAC9D,IAAI;gBACJ,KAAK;gBACL,IAAI,EAAE,YAAY,EAAE,6CAA6C;gBACjE,OAAO,EAAE,OAAO;oBACd,CAAC,CAAC;wBACE,OAAO,EAAE;4BACP,KAAK,EAAE,OAAO,CAAC,KAAK;4BACpB,KAAK,EAAE,OAAO,CAAC,KAAK;4BACpB,IAAI,EAAE,OAAO,CAAC,IAAI;4BAClB,KAAK,EAAE,OAAO,CAAC,KAAK;4BACpB,WAAW,EAAE,OAAO,CAAC,UAAU;4BAC/B,OAAO,EAAE,OAAO,CAAC,OAAO;yBACzB;qBACF;oBACH,CAAC,CAAC;wBACE,mDAAmD;wBACnD,qDAAqD;wBACrD,OAAO,EAAE;4BACP,KAAK,EAAE,uBAAuB;4BAC9B,IAAI,EAAE,qBAAqB;4BAC3B,KAAK,EAAE,IAAI;4BACX,WAAW,EAAE,OAAO;4BACpB,OAAO,EAAE,IAAI;yBACd;qBACF;gBACL,MAAM,EAAE,QAAQ;aACjB,CAAC,CAAC;YAEH,yDAAyD;YACzD,mEAAmE;YACnE,sEAAsE;YACtE,OAAO;gBACL,EAAE,EAAE,UAAU,CAAC,EAAE;gBACjB,IAAI,EAAE,UAAU,CAAC,IAAI;gBACrB,KAAK,EAAE,UAAU,CAAC,KAAK,IAAI,KAAK;gBAChC,OAAO;gBACP,SAAS,EAAE,IAAI,IAAI,CAAC,UAAU,CAAC,OAAO,GAAG,IAAI,CAAC,EAAE,wCAAwC;gBACxF,MAAM,EAAE,QAAQ;aACjB,CAAC;QACJ,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,IAAA,wBAAe,EAAC,KAAK,EAAE,6BAA6B,EAAE,eAAe,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;QAChG,CAAC;IACH,CAAC;IAED,+EAA+E;IAE/E;;;;;;;;;;;;;;OAcG;IACH,KAAK,CAAC,UAAU,CACd,YAAoB,EACpB,OAA0B;QAE1B,IAAI,CAAC;YACH,yEAAyE;YACzE,wEAAwE;YACxE,yEAAyE;YACzE,4CAA4C;YAC5C,EAAE;YACF,eAAe;YACf,qDAAqD;YACrD,6EAA6E;YAC7E,6CAA6C;YAC7C,IAAI,cAAc,GAAuB,OAAO,CAAC,MAAM,CAAC;YAExD,IAAI,CAAC,cAAc,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC;gBACrC,8EAA8E;gBAC9E,2EAA2E;gBAC3E,kDAAkD;gBAClD,OAAO,CAAC,GAAG,CAAC,gGAAgG,CAAC,CAAC;gBAC9G,cAAc,GAAG,MAAM,wBAAU,CAAC,UAAU,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;gBAC5D,OAAO,CAAC,GAAG,CAAC,gDAAgD,cAAc,8BAA8B,YAAY,EAAE,CAAC,CAAC;YAC1H,CAAC;YAED,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC;gBAClD,UAAU,EAAE,YAAY;gBACxB,QAAQ,EAAE,KAAK;gBACf,IAAI,EAAE,SAAS,EAAE,qDAAqD;gBACtE,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,QAAQ;gBAClC,wEAAwE;gBACxE,6EAA6E;gBAC7E,iBAAiB,EAAE,OAAO,CAAC,cAAc;oBACvC,CAAC,CAAC;wBACE,eAAe,EAAE;4BACf;gCACE,MAAM,EAAE,OAAO,CAAC,cAAc,CAAC,MAAM;gCACrC,QAAQ,EAAE,OAAO,CAAC,cAAc,CAAC,YAAY;6BAC9C;yBACF;qBACF;oBACH,CAAC,CAAC,SAAS;gBACb,QAAQ,EAAE;oBACR,0EAA0E;oBAC1E,2BAA2B;oBAC3B,SAAS,EAAE,OAAO,CAAC,SAAS;oBAC5B,4DAA4D;oBAC5D,wEAAwE;oBACxE,yEAAyE;oBACzE,2EAA2E;oBAC3E,GAAG,CAAC,cAAc,CAAC,CAAC,CAAC,EAAE,gBAAgB,EAAE,cAAc,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;oBAC/D,oEAAoE;oBACpE,2EAA2E;oBAC3E,GAAG,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,oBAAoB,EAAE,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;oBAC7E,uEAAuE;oBACvE,GAAG,OAAO,CAAC,QAAQ;iBACpB;aACF,CAAC,CAAC;YAEH,OAAO,eAAe,CAAC,IAAI,EAAE,YAAY,EAAE,OAAO,CAAC,CAAC;QACtD,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,IAAA,wBAAe,EAAC,KAAK,EAAE,uBAAuB,EAAE,eAAe,EAAE,EAAE,YAAY,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;QACnH,CAAC;IACH,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,OAAO,CAAC,MAAc;QAC1B,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;YAC9D,MAAM,YAAY,GAAG,OAAO,IAAI,CAAC,UAAU,KAAK,QAAQ;gBACtD,CAAC,CAAC,IAAI,CAAC,UAAU;gBACjB,CAAC,CAAC,IAAI,CAAC,UAAU,EAAE,EAAE,IAAI,EAAE,CAAC;YAC9B,OAAO,eAAe,CAAC,IAAI,EAAE,YAAY,EAAE;gBACzC,SAAS,EAAG,IAAI,CAAC,QAAmC,EAAE,SAAS,IAAI,SAAS;aAC7E,CAAC,CAAC;QACL,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,IAAA,wBAAe,EAAC,KAAK,EAAE,oBAAoB,EAAE,eAAe,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC;QAClF,CAAC;IACH,CAAC;IAED;;;;;;;;;;OAUG;IACH,KAAK,CAAC,SAAS,CAAC,MAAc;QAC5B,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE;gBAC1D,MAAM,EAAE,UAAU,EAAE,8CAA8C;aACnE,CAAC,CAAC;YACH,MAAM,YAAY,GAAG,OAAO,IAAI,CAAC,UAAU,KAAK,QAAQ;gBACtD,CAAC,CAAC,IAAI,CAAC,UAAU;gBACjB,CAAC,CAAC,IAAI,CAAC,UAAU,EAAE,EAAE,IAAI,EAAE,CAAC;YAC9B,OAAO,eAAe,CAAC,IAAI,EAAE,YAAY,EAAE;gBACzC,SAAS,EAAG,IAAI,CAAC,QAAmC,EAAE,SAAS,IAAI,SAAS;aAC7E,CAAC,CAAC;QACL,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,IAAA,wBAAe,EAAC,KAAK,EAAE,sBAAsB,EAAE,eAAe,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC;QACpF,CAAC;IACH,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,UAAU,CAAC,MAAc;QAC7B,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE;gBAC1D,MAAM,EAAE,QAAQ;aACjB,CAAC,CAAC;YACH,MAAM,YAAY,GAAG,OAAO,IAAI,CAAC,UAAU,KAAK,QAAQ;gBACtD,CAAC,CAAC,IAAI,CAAC,UAAU;gBACjB,CAAC,CAAC,IAAI,CAAC,UAAU,EAAE,EAAE,IAAI,EAAE,CAAC;YAC9B,OAAO,eAAe,CAAC,IAAI,EAAE,YAAY,EAAE;gBACzC,SAAS,EAAG,IAAI,CAAC,QAAmC,EAAE,SAAS,IAAI,SAAS;aAC7E,CAAC,CAAC;QACL,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,IAAA,wBAAe,EAAC,KAAK,EAAE,uBAAuB,EAAE,eAAe,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC;QACrF,CAAC;IACH,CAAC;IAED;;;;;;;;;OASG;IACH,KAAK,CAAC,iBAAiB,CACrB,MAAc,EACd,MAAwB;QAExB,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE;gBAC1D,iBAAiB,EAAE;oBACjB,eAAe,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;wBACtC,MAAM,EAAE,KAAK,CAAC,MAAM;wBACpB,QAAQ,EAAE,KAAK,CAAC,YAAY;qBAC7B,CAAC,CAAC;iBACJ;aACF,CAAC,CAAC;YACH,MAAM,YAAY,GAAG,OAAO,IAAI,CAAC,UAAU,KAAK,QAAQ;gBACtD,CAAC,CAAC,IAAI,CAAC,UAAU;gBACjB,CAAC,CAAC,IAAI,CAAC,UAAU,EAAE,EAAE,IAAI,EAAE,CAAC;YAC9B,OAAO,eAAe,CAAC,IAAI,EAAE,YAAY,EAAE;gBACzC,SAAS,EAAG,IAAI,CAAC,QAAmC,EAAE,SAAS,IAAI,SAAS;gBAC5E,cAAc,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,8CAA8C;aAC1E,CAAC,CAAC;QACL,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,IAAA,wBAAe,EAAC,KAAK,EAAE,+BAA+B,EAAE,eAAe,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;QACrG,CAAC;IACH,CAAC;IAED,gFAAgF;IAEhF;;;;;;;;;;;;;OAaG;IACH,KAAK,CAAC,eAAe,CACnB,MAAc,EACd,OAAiC;QAEjC,IAAI,CAAC;YACH,MAAM,YAAY,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,YAAY,CAAC,IAAI,CAAC;gBAC/D,IAAI,EAAE,MAAM;gBACZ,KAAK,EAAE,OAAO,EAAE,KAAK,IAAI,GAAG;aAC7B,CAAC,CAAC;YAEH,OAAO,YAAY,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;gBACpC,EAAE,EAAE,EAAE,CAAC,EAAE;gBACT,+DAA+D;gBAC/D,MAAM,EAAE,OAAO,EAAE,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,EAAE,EAAE,IAAI,EAAE;gBACjE,MAAM,EAAE,EAAE,CAAC,MAAM;gBACjB,QAAQ,EAAE,EAAE,CAAC,QAAQ;gBACrB,QAAQ,EAAE;oBACR,IAAI,EAAE,EAAE,CAAC,aAAa,EAAE,IAAI,IAAI,SAAS;oBACzC,QAAQ,EAAE,EAAE,CAAC,aAAa,EAAE,QAAQ,IAAI,SAAS;oBACjD,qEAAqE;oBACrE,4EAA4E;oBAC5E,IAAI,EAAE,EAAE,CAAC,aAAa,EAAE,IAAI,IAAI,SAAS;oBACzC,OAAO,EAAE,EAAE,CAAC,aAAa,EAAE,OAAO,IAAI,SAAS;iBAChD;gBACD,oFAAoF;gBACpF,uCAAuC;gBACvC,MAAM,EAAE,EAAE,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,UAAmC;gBAChF,SAAS,EAAE,IAAI,IAAI,CAAC,EAAE,CAAC,OAAO,GAAG,IAAI,CAAC;gBACtC,QAAQ,EAAG,EAAE,CAAC,QAAmC,IAAI,EAAE;aACxD,CAAC,CAAC,CAAC;QACN,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,IAAA,wBAAe,EAAC,KAAK,EAAE,4BAA4B,EAAE,eAAe,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC;QAC1F,CAAC;IACH,CAAC;IAED,gFAAgF;IAEhF;;;;;;;;OAQG;IACH,KAAK,CAAC,UAAU;QACd,OAAO;YACL,SAAS,EAAE,CAAC;YACZ,QAAQ,EAAE,CAAC;YACX,KAAK,EAAE,CAAC;YACR,IAAI,EAAE,IAAI,IAAI,EAAE;SACjB,CAAC;IACJ,CAAC;IAED;;;;;;;;OAQG;IACH,KAAK,CAAC,wBAAwB,CAAC,OAAe;QAC5C,oEAAoE;QACpE,iFAAiF;QACjF,6EAA6E;QAC7E,OAAO,EAAE,CAAC;IACZ,CAAC;CACF;AA3YD,oCA2YC;AAED,iFAAiF;AAEjF;;;;;;;;;;GAUG;AACH,SAAS,eAAe,CACtB,IAAyB,EACzB,YAAoB,EACpB,OAAmC;IAEnC,wDAAwD;IACxD,mEAAmE;IACnE,MAAM,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAE/F,0EAA0E;IAC1E,iEAAiE;IACjE,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAyC,CAAC;IAEhE,OAAO;QACL,EAAE,EAAE,IAAI,CAAC,EAAE;QACX,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,KAAK,EAAE,MAAM,EAAE,oDAAoD;QACnE,MAAM;QACN,0DAA0D;QAC1D,MAAM,EAAE,IAAI,CAAC,MAA4C;QACzD,YAAY;QACZ,SAAS,EAAE,QAAQ,EAAE,SAAS,IAAI,OAAO,CAAC,SAAS,IAAI,SAAS;QAChE,uDAAuD;QACvD,sEAAsE;QACtE,WAAW,EAAE,QAAQ,EAAE,oBAAoB,IAAI,IAAI;QACnD,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,uEAAuE;QACvE,+EAA+E;QAC/E,0EAA0E;QAC1E,gBAAgB,EAAE,CAAC,IAAI,CAAC,iBAAiB,EAAE,eAAe,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;YAC7E,MAAM,EAAE,EAAE,CAAC,MAAM;YACjB,YAAY,EAAE,EAAE,CAAC,QAA0C;YAC3D,oBAAoB,EAAE,KAAc;SACrC,CAAC,CAAC;QACH,QAAQ,EAAE,QAAQ,IAAI,SAAS;QAC/B,SAAS,EAAE,IAAI,IAAI,CAAC,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;KACzC,CAAC;AACJ,CAAC"}

package/dist/test-utils.d.ts

@@ -0,0 +1,55 @@
+/**
+ * @opencard/core — Test Utilities
+ * ================================
+ * Shared helpers for testing code that depends on Stripe Issuing types.
+ *
+ * These utilities exist to avoid duplicating fake Stripe object construction
+ * across test files and examples. All builders produce minimal partial objects
+ * that contain only the fields our code actually reads — the real Stripe
+ * authorization has ~30 fields, but we only need a handful for evaluation.
+ *
+ * ─── Usage ───────────────────────────────────────────────────────────────────
+ *
+ *   import { mockAuthorization } from '@opencard-dev/core/test-utils';
+ *
+ *   const auth = mockAuthorization({ amount: 2500, category: 'saas' });
+ *
+ * ─── Why cast through unknown? ───────────────────────────────────────────────
+ * We intentionally build partial Stripe objects — only the fields our rules
+ * engine reads. TypeScript would complain about missing required fields, so we
+ * cast via `unknown` as a deliberate signal that this is a test-only shortcut.
+ */
+import Stripe from 'stripe';
+/**
+ * Parameters for `mockAuthorization()`.
+ * All fields are optional — sensible defaults are provided for each.
+ */
+export interface MockAuthorizationParams {
+    /** Transaction amount in cents. Default: 2500 ($25.00) */
+    amount?: number;
+    /** Merchant category code (e.g. 'saas', 'grocery'). Default: 'saas' */
+    category?: string;
+    /** Merchant display name. Default: 'Acme Corp' */
+    merchantName?: string;
+    /** Stripe card ID. Default: 'ic_test123' */
+    cardId?: string;
+    /** Additional metadata to set on the card object. Default: {} */
+    cardMetadata?: Record<string, string>;
+}
+/**
+ * Creates a minimal fake `Stripe.Issuing.Authorization` for use in tests
+ * and runnable examples.
+ *
+ * Only the fields read by `evaluateAuthorization` are populated:
+ *   - `amount`
+ *   - `merchant_data.category` and `merchant_data.name`
+ *   - `card.id` and `card.metadata`
+ *
+ * All other required Stripe fields are set to null/empty/defaults to satisfy
+ * TypeScript without pulling in the full Stripe fixture machinery.
+ *
+ * @param params - Override defaults for any field
+ * @returns A partial Stripe.Issuing.Authorization cast to the full type
+ */
+export declare function mockAuthorization(params?: MockAuthorizationParams): Stripe.Issuing.Authorization;
+//# sourceMappingURL=test-utils.d.ts.map

package/dist/test-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-utils.d.ts","sourceRoot":"","sources":["../src/test-utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,MAAM,MAAM,QAAQ,CAAC;AAE5B;;;GAGG;AACH,MAAM,WAAW,uBAAuB;IACtC,0DAA0D;IAC1D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,uEAAuE;IACvE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,kDAAkD;IAClD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,4CAA4C;IAC5C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iEAAiE;IACjE,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACvC;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,GAAE,uBAA4B,GACnC,MAAM,CAAC,OAAO,CAAC,aAAa,CAuD9B"}

package/dist/test-utils.js

@@ -0,0 +1,91 @@
+"use strict";
+/**
+ * @opencard/core — Test Utilities
+ * ================================
+ * Shared helpers for testing code that depends on Stripe Issuing types.
+ *
+ * These utilities exist to avoid duplicating fake Stripe object construction
+ * across test files and examples. All builders produce minimal partial objects
+ * that contain only the fields our code actually reads — the real Stripe
+ * authorization has ~30 fields, but we only need a handful for evaluation.
+ *
+ * ─── Usage ───────────────────────────────────────────────────────────────────
+ *
+ *   import { mockAuthorization } from '@opencard-dev/core/test-utils';
+ *
+ *   const auth = mockAuthorization({ amount: 2500, category: 'saas' });
+ *
+ * ─── Why cast through unknown? ───────────────────────────────────────────────
+ * We intentionally build partial Stripe objects — only the fields our rules
+ * engine reads. TypeScript would complain about missing required fields, so we
+ * cast via `unknown` as a deliberate signal that this is a test-only shortcut.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mockAuthorization = mockAuthorization;
+/**
+ * Creates a minimal fake `Stripe.Issuing.Authorization` for use in tests
+ * and runnable examples.
+ *
+ * Only the fields read by `evaluateAuthorization` are populated:
+ *   - `amount`
+ *   - `merchant_data.category` and `merchant_data.name`
+ *   - `card.id` and `card.metadata`
+ *
+ * All other required Stripe fields are set to null/empty/defaults to satisfy
+ * TypeScript without pulling in the full Stripe fixture machinery.
+ *
+ * @param params - Override defaults for any field
+ * @returns A partial Stripe.Issuing.Authorization cast to the full type
+ */
+function mockAuthorization(params = {}) {
+    const { amount = 2500, // Default: $25.00
+    category = 'saas', // Default: software category
+    merchantName = 'Acme Corp', cardId = 'ic_test123', cardMetadata = {}, } = params;
+    return {
+        id: `iauth_${Date.now()}`,
+        object: 'issuing.authorization',
+        amount,
+        approved: false, // Before evaluation, always false
+        currency: 'usd',
+        merchant_data: {
+            category,
+            name: merchantName,
+            city: 'San Francisco',
+            country: 'US',
+            network_id: '',
+            postal_code: '94105',
+            state: 'CA',
+        },
+        // The card object embedded in the authorization.
+        // Our code reads card.id and card.metadata from here.
+        card: {
+            id: cardId,
+            metadata: cardMetadata,
+        },
+        metadata: {},
+        // Fields below exist in real authorizations but are unused by our code.
+        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: 'ich_test',
+        fleet: null,
+        fuel: null,
+        merchant_amount: amount,
+        merchant_currency: 'usd',
+        token: null,
+    };
+}
+//# sourceMappingURL=test-utils.js.map

package/dist/test-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-utils.js","sourceRoot":"","sources":["../src/test-utils.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;;AAoCH,8CAyDC;AAxED;;;;;;;;;;;;;;GAcG;AACH,SAAgB,iBAAiB,CAC/B,SAAkC,EAAE;IAEpC,MAAM,EACJ,MAAM,GAAG,IAAI,EAAa,kBAAkB;IAC5C,QAAQ,GAAG,MAAM,EAAS,6BAA6B;IACvD,YAAY,GAAG,WAAW,EAC1B,MAAM,GAAG,YAAY,EACrB,YAAY,GAAG,EAAE,GAClB,GAAG,MAAM,CAAC;IAEX,OAAO;QACL,EAAE,EAAE,SAAS,IAAI,CAAC,GAAG,EAAE,EAAE;QACzB,MAAM,EAAE,uBAAuB;QAC/B,MAAM;QACN,QAAQ,EAAE,KAAK,EAAW,kCAAkC;QAC5D,QAAQ,EAAE,KAAK;QACf,aAAa,EAAE;YACb,QAAQ;YACR,IAAI,EAAE,YAAY;YAClB,IAAI,EAAE,eAAe;YACrB,OAAO,EAAE,IAAI;YACb,UAAU,EAAE,EAAE;YACd,WAAW,EAAE,OAAO;YACpB,KAAK,EAAE,IAAI;SACZ;QACD,iDAAiD;QACjD,sDAAsD;QACtD,IAAI,EAAE;YACJ,EAAE,EAAE,MAAM;YACV,QAAQ,EAAE,YAAY;SACW;QACnC,QAAQ,EAAE,EAAE;QACZ,wEAAwE;QACxE,eAAe,EAAE,IAAkE;QACnF,eAAe,EAAE,EAAE;QACnB,MAAM,EAAE,SAAS;QACjB,OAAO,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC;QACtC,QAAQ,EAAE,KAAK;QACf,YAAY,EAAE,IAA+D;QAC7E,YAAY,EAAE,EAAE;QAChB,iBAAiB,EAAE;YACjB,mBAAmB,EAAE,cAAc;YACnC,yBAAyB,EAAE,cAAc;YACzC,SAAS,EAAE,cAAc;YACzB,YAAY,EAAE,OAAO;SACtB;QACD,MAAM,EAAE,IAAI;QACZ,cAAc,EAAE,IAAI;QACpB,oBAAoB,EAAE,EAAE;QACxB,UAAU,EAAE,UAAU;QACtB,KAAK,EAAE,IAAI;QACX,IAAI,EAAE,IAAI;QACV,eAAe,EAAE,MAAM;QACvB,iBAAiB,EAAE,KAAK;QACxB,KAAK,EAAE,IAAI;KAC+B,CAAC;AAC/C,CAAC"}