@opencard-dev/core 0.1.0

package/dist/errors.js

@@ -0,0 +1,124 @@
+"use strict";
+/**
+ * OpenCard Error Classes
+ * ======================
+ * Custom error types for OpenCard, designed to wrap Stripe errors while
+ * preserving the original error code, message, and type.
+ *
+ * This allows callers to recover from specific errors (e.g., retry on
+ * rate limits, handle authorization failures differently) rather than
+ * treating all errors as opaque strings.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RuleError = exports.InvalidParameterError = exports.RateLimitError = exports.StripeAuthenticationError = exports.OpenCardError = void 0;
+exports.wrapStripeError = wrapStripeError;
+/**
+ * Base class for all OpenCard errors.
+ * Extends Error and preserves the Stripe error context.
+ */
+class OpenCardError extends Error {
+    /** Original error if this is wrapping a thrown error */
+    cause;
+    /** Context about what operation failed (stripe-client, rules-engine, etc.) */
+    component;
+    /** Stripe error code if available (e.g., 'rate_limit_error', 'authentication_error') */
+    stripeCode;
+    /** Stripe error type if available (e.g., 'StripeInvalidRequestError') */
+    stripeType;
+    /** Additional context (cardId, ruleId, etc.) */
+    context;
+    constructor(message, component, context = {}) {
+        super(message);
+        this.name = 'OpenCardError';
+        this.component = component;
+        this.context = context;
+        // Maintain proper prototype chain for instanceof checks
+        Object.setPrototypeOf(this, OpenCardError.prototype);
+    }
+}
+exports.OpenCardError = OpenCardError;
+/**
+ * Wraps a Stripe error, preserving its type and code.
+ * Useful for error recovery based on the specific Stripe error.
+ *
+ * @param error - The original error (likely from a Stripe SDK call)
+ * @param message - User-friendly message describing what we were doing
+ * @param component - Component name (e.g., 'stripe-client')
+ * @param context - Additional context (cardId, etc.)
+ * @returns OpenCardError with Stripe error info preserved
+ *
+ * @example
+ * try {
+ *   await stripe.issuing.cards.create({ ... });
+ * } catch (err) {
+ *   throw wrapStripeError(err, 'Failed to create card', 'stripe-client', { cardholderId });
+ * }
+ */
+function wrapStripeError(error, message, component, context = {}) {
+    const err = new OpenCardError(message, component, context);
+    if (error instanceof Error) {
+        err.cause = error;
+        err.message = `${message}: ${error.message}`;
+        // Extract Stripe-specific error info if available
+        const stripeErr = error;
+        if (stripeErr.code) {
+            err.stripeCode = stripeErr.code;
+        }
+        if (stripeErr.type) {
+            err.stripeType = stripeErr.type;
+        }
+    }
+    else {
+        err.message = `${message}: ${String(error)}`;
+    }
+    Object.setPrototypeOf(err, OpenCardError.prototype);
+    return err;
+}
+/**
+ * Specific error: Stripe authentication failed (invalid key, revoked key, etc.)
+ */
+class StripeAuthenticationError extends OpenCardError {
+    constructor(message, context = {}) {
+        super(message, 'stripe-client', context);
+        this.name = 'StripeAuthenticationError';
+        Object.setPrototypeOf(this, StripeAuthenticationError.prototype);
+    }
+}
+exports.StripeAuthenticationError = StripeAuthenticationError;
+/**
+ * Specific error: Rate limit exceeded — client should retry with backoff.
+ */
+class RateLimitError extends OpenCardError {
+    /** Seconds to wait before retrying (from Stripe's Retry-After header) */
+    retryAfter;
+    constructor(message, component, retryAfter, context = {}) {
+        super(message, component, context);
+        this.name = 'RateLimitError';
+        this.retryAfter = retryAfter;
+        Object.setPrototypeOf(this, RateLimitError.prototype);
+    }
+}
+exports.RateLimitError = RateLimitError;
+/**
+ * Specific error: Invalid parameters (e.g., missing required field, bad enum value)
+ */
+class InvalidParameterError extends OpenCardError {
+    constructor(message, context = {}) {
+        super(message, 'stripe-client', context);
+        this.name = 'InvalidParameterError';
+        Object.setPrototypeOf(this, InvalidParameterError.prototype);
+    }
+}
+exports.InvalidParameterError = InvalidParameterError;
+/**
+ * Specific error: Rule not found or invalid in the rules store.
+ */
+class RuleError extends OpenCardError {
+    constructor(message, context = {}) {
+        super(message, 'rules-store', context);
+        this.name = 'RuleError';
+        Object.setPrototypeOf(this, RuleError.prototype);
+    }
+}
+exports.RuleError = RuleError;
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @opencard/core — Public API
+ * ==========================
+ * Everything a consumer of this package needs is re-exported from here.
+ * Import paths never need to go deeper than "@opencard/core".
+ *
+ * Organized into logical sections:
+ *  - Types: TypeScript interfaces and type aliases
+ *  - Client: The StripeClient wrapper for Stripe Issuing
+ *  - Rules: Rule builder, templates, and evaluation
+ *  - Tracker: In-memory spend tracking
+ *  - Webhooks: Stripe event handlers
+ */
+export type { OpenCardConfig, Cardholder, BillingDetails, CardCreateOptions, Card, SpendRule, SpendRuleTemplate, Transaction, Authorization, CardBalance, TransactionQueryOptions, SpendingLimits, StripeOperationConfig, } from './types';
+export { StripeClient } from './stripe-client';
+export { SpendRules, evaluateRule, evaluateAuthorization } from './rules-engine';
+export type { AuthorizationDecision, SpendContext } from './rules-engine';
+export { TransactionTracker, tracker } from './tracker';
+export type { CardSpend } from './tracker';
+export { RulesStore, rulesStore } from './rules-store';
+export { validateRule } from './rules-validation';
+export type { ValidationResult } from './rules-validation';
+export { mockAuthorization } from './test-utils';
+export type { MockAuthorizationParams } from './test-utils';
+export { handleAuthorizationRequest, handleAuthorizationCreated, handleTransactionCreated, handleCardUpdated, setReconciler, getReconciler, getRulesForCard, } from './webhooks';
+export type { AuthorizationResult } from './webhooks';
+export { OpenCardDatabase, initDatabase } from './db';
+export type { StoredTransaction, StoredAuthorization, RuleVersion, StoredRule, StoredCard, StoredCardholder, ApprovalRequest, } from './db';
+export { TransactionReconciler } from './transaction-reconciler';
+export type { ReconciliationResult } from './transaction-reconciler';
+export { getLogger, configureLogger } from './logger';
+export type { LogLevel, LogEntry } from './logger';
+export { OpenCardError, wrapStripeError, StripeAuthenticationError, RateLimitError, InvalidParameterError, RuleError, } from './errors';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,YAAY,EACV,cAAc,EACd,UAAU,EACV,cAAc,EACd,iBAAiB,EACjB,IAAI,EACJ,SAAS,EACT,iBAAiB,EACjB,WAAW,EACX,aAAa,EACb,WAAW,EACX,uBAAuB,EACvB,cAAc,EACd,qBAAqB,GACtB,MAAM,SAAS,CAAC;AAIjB,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAI/C,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AACjF,YAAY,EAAE,qBAAqB,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAI1E,OAAO,EAAE,kBAAkB,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACxD,YAAY,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAI3C,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAIvD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,YAAY,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAI3D,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACjD,YAAY,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAC;AAI5D,OAAO,EACL,0BAA0B,EAC1B,0BAA0B,EAC1B,wBAAwB,EACxB,iBAAiB,EACjB,aAAa,EACb,aAAa,EACb,eAAe,GAChB,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAItD,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,MAAM,CAAC;AACtD,YAAY,EACV,iBAAiB,EACjB,mBAAmB,EACnB,WAAW,EACX,UAAU,EACV,UAAU,EACV,gBAAgB,EAChB,eAAe,GAChB,MAAM,MAAM,CAAC;AAId,OAAO,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AACjE,YAAY,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAIrE,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AACtD,YAAY,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAInD,OAAO,EACL,aAAa,EACb,eAAe,EACf,yBAAyB,EACzB,cAAc,EACd,qBAAqB,EACrB,SAAS,GACV,MAAM,UAAU,CAAC"}

package/dist/index.js

@@ -0,0 +1,67 @@
+"use strict";
+/**
+ * @opencard/core — Public API
+ * ==========================
+ * Everything a consumer of this package needs is re-exported from here.
+ * Import paths never need to go deeper than "@opencard/core".
+ *
+ * Organized into logical sections:
+ *  - Types: TypeScript interfaces and type aliases
+ *  - Client: The StripeClient wrapper for Stripe Issuing
+ *  - Rules: Rule builder, templates, and evaluation
+ *  - Tracker: In-memory spend tracking
+ *  - Webhooks: Stripe event handlers
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RuleError = exports.InvalidParameterError = exports.RateLimitError = exports.StripeAuthenticationError = exports.wrapStripeError = exports.OpenCardError = exports.configureLogger = exports.getLogger = exports.TransactionReconciler = exports.initDatabase = exports.OpenCardDatabase = exports.getRulesForCard = exports.getReconciler = exports.setReconciler = exports.handleCardUpdated = exports.handleTransactionCreated = exports.handleAuthorizationCreated = exports.handleAuthorizationRequest = exports.mockAuthorization = exports.validateRule = exports.rulesStore = exports.RulesStore = exports.tracker = exports.TransactionTracker = exports.evaluateAuthorization = exports.evaluateRule = exports.SpendRules = exports.StripeClient = void 0;
+// ─── Stripe Client ────────────────────────────────────────────────────────────
+var stripe_client_1 = require("./stripe-client");
+Object.defineProperty(exports, "StripeClient", { enumerable: true, get: function () { return stripe_client_1.StripeClient; } });
+// ─── Rules Engine ─────────────────────────────────────────────────────────────
+var rules_engine_1 = require("./rules-engine");
+Object.defineProperty(exports, "SpendRules", { enumerable: true, get: function () { return rules_engine_1.SpendRules; } });
+Object.defineProperty(exports, "evaluateRule", { enumerable: true, get: function () { return rules_engine_1.evaluateRule; } });
+Object.defineProperty(exports, "evaluateAuthorization", { enumerable: true, get: function () { return rules_engine_1.evaluateAuthorization; } });
+// ─── Transaction Tracker ──────────────────────────────────────────────────────
+var tracker_1 = require("./tracker");
+Object.defineProperty(exports, "TransactionTracker", { enumerable: true, get: function () { return tracker_1.TransactionTracker; } });
+Object.defineProperty(exports, "tracker", { enumerable: true, get: function () { return tracker_1.tracker; } });
+// ─── Rules Store ──────────────────────────────────────────────────────────────
+var rules_store_1 = require("./rules-store");
+Object.defineProperty(exports, "RulesStore", { enumerable: true, get: function () { return rules_store_1.RulesStore; } });
+Object.defineProperty(exports, "rulesStore", { enumerable: true, get: function () { return rules_store_1.rulesStore; } });
+// ─── Rule Validation ──────────────────────────────────────────────────────────
+var rules_validation_1 = require("./rules-validation");
+Object.defineProperty(exports, "validateRule", { enumerable: true, get: function () { return rules_validation_1.validateRule; } });
+// ─── Test Utilities ───────────────────────────────────────────────────────────
+var test_utils_1 = require("./test-utils");
+Object.defineProperty(exports, "mockAuthorization", { enumerable: true, get: function () { return test_utils_1.mockAuthorization; } });
+// ─── Webhook Handlers ─────────────────────────────────────────────────────────
+var webhooks_1 = require("./webhooks");
+Object.defineProperty(exports, "handleAuthorizationRequest", { enumerable: true, get: function () { return webhooks_1.handleAuthorizationRequest; } });
+Object.defineProperty(exports, "handleAuthorizationCreated", { enumerable: true, get: function () { return webhooks_1.handleAuthorizationCreated; } });
+Object.defineProperty(exports, "handleTransactionCreated", { enumerable: true, get: function () { return webhooks_1.handleTransactionCreated; } });
+Object.defineProperty(exports, "handleCardUpdated", { enumerable: true, get: function () { return webhooks_1.handleCardUpdated; } });
+Object.defineProperty(exports, "setReconciler", { enumerable: true, get: function () { return webhooks_1.setReconciler; } });
+Object.defineProperty(exports, "getReconciler", { enumerable: true, get: function () { return webhooks_1.getReconciler; } });
+Object.defineProperty(exports, "getRulesForCard", { enumerable: true, get: function () { return webhooks_1.getRulesForCard; } });
+// ─── Database ─────────────────────────────────────────────────────────────────
+var db_1 = require("./db");
+Object.defineProperty(exports, "OpenCardDatabase", { enumerable: true, get: function () { return db_1.OpenCardDatabase; } });
+Object.defineProperty(exports, "initDatabase", { enumerable: true, get: function () { return db_1.initDatabase; } });
+// ─── Transaction Reconciler ───────────────────────────────────────────────────
+var transaction_reconciler_1 = require("./transaction-reconciler");
+Object.defineProperty(exports, "TransactionReconciler", { enumerable: true, get: function () { return transaction_reconciler_1.TransactionReconciler; } });
+// ─── Logger ────────────────────────────────────────────────────────────────────
+var logger_1 = require("./logger");
+Object.defineProperty(exports, "getLogger", { enumerable: true, get: function () { return logger_1.getLogger; } });
+Object.defineProperty(exports, "configureLogger", { enumerable: true, get: function () { return logger_1.configureLogger; } });
+// ─── Error Classes ──────────────────────────────────────────────────────────────
+var errors_1 = require("./errors");
+Object.defineProperty(exports, "OpenCardError", { enumerable: true, get: function () { return errors_1.OpenCardError; } });
+Object.defineProperty(exports, "wrapStripeError", { enumerable: true, get: function () { return errors_1.wrapStripeError; } });
+Object.defineProperty(exports, "StripeAuthenticationError", { enumerable: true, get: function () { return errors_1.StripeAuthenticationError; } });
+Object.defineProperty(exports, "RateLimitError", { enumerable: true, get: function () { return errors_1.RateLimitError; } });
+Object.defineProperty(exports, "InvalidParameterError", { enumerable: true, get: function () { return errors_1.InvalidParameterError; } });
+Object.defineProperty(exports, "RuleError", { enumerable: true, get: function () { return errors_1.RuleError; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;GAYG;;;AAoBH,iFAAiF;AAEjF,iDAA+C;AAAtC,6GAAA,YAAY,OAAA;AAErB,iFAAiF;AAEjF,+CAAiF;AAAxE,0GAAA,UAAU,OAAA;AAAE,4GAAA,YAAY,OAAA;AAAE,qHAAA,qBAAqB,OAAA;AAGxD,iFAAiF;AAEjF,qCAAwD;AAA/C,6GAAA,kBAAkB,OAAA;AAAE,kGAAA,OAAO,OAAA;AAGpC,iFAAiF;AAEjF,6CAAuD;AAA9C,yGAAA,UAAU,OAAA;AAAE,yGAAA,UAAU,OAAA;AAE/B,iFAAiF;AAEjF,uDAAkD;AAAzC,gHAAA,YAAY,OAAA;AAGrB,iFAAiF;AAEjF,2CAAiD;AAAxC,+GAAA,iBAAiB,OAAA;AAG1B,iFAAiF;AAEjF,uCAQoB;AAPlB,sHAAA,0BAA0B,OAAA;AAC1B,sHAAA,0BAA0B,OAAA;AAC1B,oHAAA,wBAAwB,OAAA;AACxB,6GAAA,iBAAiB,OAAA;AACjB,yGAAA,aAAa,OAAA;AACb,yGAAA,aAAa,OAAA;AACb,2GAAA,eAAe,OAAA;AAIjB,iFAAiF;AAEjF,2BAAsD;AAA7C,sGAAA,gBAAgB,OAAA;AAAE,kGAAA,YAAY,OAAA;AAWvC,iFAAiF;AAEjF,mEAAiE;AAAxD,+HAAA,qBAAqB,OAAA;AAG9B,kFAAkF;AAElF,mCAAsD;AAA7C,mGAAA,SAAS,OAAA;AAAE,yGAAA,eAAe,OAAA;AAGnC,mFAAmF;AAEnF,mCAOkB;AANhB,uGAAA,aAAa,OAAA;AACb,yGAAA,eAAe,OAAA;AACf,mHAAA,yBAAyB,OAAA;AACzB,wGAAA,cAAc,OAAA;AACd,+GAAA,qBAAqB,OAAA;AACrB,mGAAA,SAAS,OAAA"}

package/dist/logger.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Structured Logger
+ * =================
+ * A minimal, zero-dependency structured logger for OpenCard.
+ *
+ * Outputs JSON in production, human-readable format in development.
+ * Components: stripe-client, rules-engine, webhook-server, tracker, rules-store
+ *
+ * Usage:
+ *   const logger = getLogger('rules-engine');
+ *   logger.info('evaluating rule', { ruleId, cardId, amount });
+ *   logger.error('rule evaluation failed', { ruleId, error: err.message });
+ */
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+export interface LogEntry {
+    timestamp: string;
+    level: LogLevel;
+    component: string;
+    message: string;
+    [key: string]: unknown;
+}
+/**
+ * Configuration for the logger.
+ * Allows switching between JSON (production) and pretty (development) modes.
+ */
+interface LoggerConfig {
+    /** Output format: 'json' or 'pretty' (default: detect from NODE_ENV) */
+    format?: 'json' | 'pretty';
+    /** Minimum log level to output (default: 'debug') */
+    minLevel?: LogLevel;
+}
+/**
+ * Configure the global logger.
+ */
+export declare function configureLogger(config: Partial<LoggerConfig>): void;
+/**
+ * Get a logger for a specific component.
+ *
+ * @param component - Component name (e.g. 'stripe-client', 'rules-engine')
+ * @returns Logger instance with info, warn, error, debug methods
+ *
+ * @example
+ * const logger = getLogger('rules-engine');
+ * logger.info('rule evaluated', { ruleId, decision: 'approved' });
+ */
+export declare function getLogger(component: string): {
+    debug: (message: string, context?: Record<string, unknown>) => void;
+    info: (message: string, context?: Record<string, unknown>) => void;
+    warn: (message: string, context?: Record<string, unknown>) => void;
+    error: (message: string, context?: Record<string, unknown>) => void;
+};
+export {};
+//# sourceMappingURL=logger.d.ts.map

package/dist/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAE3D,MAAM,WAAW,QAAQ;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,QAAQ,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;;GAGG;AACH,UAAU,YAAY;IACpB,wEAAwE;IACxE,MAAM,CAAC,EAAE,MAAM,GAAG,QAAQ,CAAC;IAC3B,qDAAqD;IACrD,QAAQ,CAAC,EAAE,QAAQ,CAAC;CACrB;AAUD;;GAEG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,OAAO,CAAC,YAAY,CAAC,GAAG,IAAI,CAEnE;AAYD;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CAAC,SAAS,EAAE,MAAM;qBA6BtB,MAAM,YAAY,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;oBAC1C,MAAM,YAAY,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;oBACzC,MAAM,YAAY,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;qBACxC,MAAM,YAAY,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;EAE7D"}

package/dist/logger.js

@@ -0,0 +1,109 @@
+"use strict";
+/**
+ * Structured Logger
+ * =================
+ * A minimal, zero-dependency structured logger for OpenCard.
+ *
+ * Outputs JSON in production, human-readable format in development.
+ * Components: stripe-client, rules-engine, webhook-server, tracker, rules-store
+ *
+ * Usage:
+ *   const logger = getLogger('rules-engine');
+ *   logger.info('evaluating rule', { ruleId, cardId, amount });
+ *   logger.error('rule evaluation failed', { ruleId, error: err.message });
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.configureLogger = configureLogger;
+exports.getLogger = getLogger;
+/**
+ * Global logger configuration.
+ */
+let globalConfig = {
+    format: process.env.NODE_ENV === 'production' ? 'json' : 'pretty',
+    minLevel: 'debug',
+};
+/**
+ * Configure the global logger.
+ */
+function configureLogger(config) {
+    globalConfig = { ...globalConfig, ...config };
+}
+/**
+ * Check if a log level should be output.
+ */
+function shouldLog(level) {
+    const levels = ['debug', 'info', 'warn', 'error'];
+    const minIndex = levels.indexOf(globalConfig.minLevel || 'debug');
+    const currentIndex = levels.indexOf(level);
+    return currentIndex >= minIndex;
+}
+/**
+ * Get a logger for a specific component.
+ *
+ * @param component - Component name (e.g. 'stripe-client', 'rules-engine')
+ * @returns Logger instance with info, warn, error, debug methods
+ *
+ * @example
+ * const logger = getLogger('rules-engine');
+ * logger.info('rule evaluated', { ruleId, decision: 'approved' });
+ */
+function getLogger(component) {
+    /**
+     * Format and output a log entry.
+     */
+    const log = (level, message, context) => {
+        if (!shouldLog(level)) {
+            return;
+        }
+        const entry = {
+            timestamp: new Date().toISOString(),
+            level,
+            component,
+            message,
+            ...(context || {}),
+        };
+        const output = globalConfig.format === 'json'
+            ? formatJSON(entry)
+            : formatPretty(entry);
+        // Use the appropriate console method for the level
+        const consoleMethod = level === 'error' ? console.error :
+            level === 'warn' ? console.warn :
+                console.log;
+        consoleMethod(output);
+    };
+    return {
+        debug: (message, context) => log('debug', message, context),
+        info: (message, context) => log('info', message, context),
+        warn: (message, context) => log('warn', message, context),
+        error: (message, context) => log('error', message, context),
+    };
+}
+/**
+ * Format a log entry as JSON.
+ */
+function formatJSON(entry) {
+    return JSON.stringify(entry);
+}
+/**
+ * Format a log entry as human-readable text.
+ */
+function formatPretty(entry) {
+    const levelEmoji = {
+        debug: '🔍',
+        info: 'ℹ',
+        warn: '⚠',
+        error: '❌',
+    };
+    const timestamp = new Date(entry.timestamp).toLocaleTimeString();
+    const level = entry.level.toUpperCase().padEnd(5);
+    const emoji = levelEmoji[entry.level];
+    const component = `[${entry.component}]`.padEnd(20);
+    // Format context as key=value pairs
+    const contextEntries = Object.entries(entry)
+        .filter(([key]) => !['timestamp', 'level', 'component', 'message'].includes(key))
+        .map(([key, value]) => `${key}=${typeof value === 'string' ? value : JSON.stringify(value)}`)
+        .join(' | ');
+    const contextStr = contextEntries ? ` | ${contextEntries}` : '';
+    return `${emoji} ${timestamp} ${level} ${component} ${entry.message}${contextStr}`;
+}
+//# sourceMappingURL=logger.js.map

package/dist/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;GAYG;;AAkCH,0CAEC;AAsBD,8BAkCC;AArED;;GAEG;AACH,IAAI,YAAY,GAAiB;IAC/B,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,YAAY,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ;IACjE,QAAQ,EAAE,OAAO;CAClB,CAAC;AAEF;;GAEG;AACH,SAAgB,eAAe,CAAC,MAA6B;IAC3D,YAAY,GAAG,EAAE,GAAG,YAAY,EAAE,GAAG,MAAM,EAAE,CAAC;AAChD,CAAC;AAED;;GAEG;AACH,SAAS,SAAS,CAAC,KAAe;IAChC,MAAM,MAAM,GAAe,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9D,MAAM,QAAQ,GAAG,MAAM,CAAC,OAAO,CAAC,YAAY,CAAC,QAAQ,IAAI,OAAO,CAAC,CAAC;IAClE,MAAM,YAAY,GAAG,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IAC3C,OAAO,YAAY,IAAI,QAAQ,CAAC;AAClC,CAAC;AAED;;;;;;;;;GASG;AACH,SAAgB,SAAS,CAAC,SAAiB;IACzC;;OAEG;IACH,MAAM,GAAG,GAAG,CAAC,KAAe,EAAE,OAAe,EAAE,OAAiC,EAAQ,EAAE;QACxF,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC;YACtB,OAAO;QACT,CAAC;QAED,MAAM,KAAK,GAAa;YACtB,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;YACnC,KAAK;YACL,SAAS;YACT,OAAO;YACP,GAAG,CAAC,OAAO,IAAI,EAAE,CAAC;SACnB,CAAC;QAEF,MAAM,MAAM,GAAG,YAAY,CAAC,MAAM,KAAK,MAAM;YAC3C,CAAC,CAAC,UAAU,CAAC,KAAK,CAAC;YACnB,CAAC,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC;QAExB,mDAAmD;QACnD,MAAM,aAAa,GAAG,KAAK,KAAK,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;YACpC,KAAK,KAAK,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;gBACjC,OAAO,CAAC,GAAG,CAAC;QACjC,aAAa,CAAC,MAAM,CAAC,CAAC;IACxB,CAAC,CAAC;IAEF,OAAO;QACL,KAAK,EAAE,CAAC,OAAe,EAAE,OAAiC,EAAE,EAAE,CAAC,GAAG,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC;QAC7F,IAAI,EAAE,CAAC,OAAe,EAAE,OAAiC,EAAE,EAAE,CAAC,GAAG,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC;QAC3F,IAAI,EAAE,CAAC,OAAe,EAAE,OAAiC,EAAE,EAAE,CAAC,GAAG,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC;QAC3F,KAAK,EAAE,CAAC,OAAe,EAAE,OAAiC,EAAE,EAAE,CAAC,GAAG,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC;KAC9F,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,SAAS,UAAU,CAAC,KAAe;IACjC,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;AAC/B,CAAC;AAED;;GAEG;AACH,SAAS,YAAY,CAAC,KAAe;IACnC,MAAM,UAAU,GAAG;QACjB,KAAK,EAAE,IAAI;QACX,IAAI,EAAE,GAAG;QACT,IAAI,EAAE,GAAG;QACT,KAAK,EAAE,GAAG;KACX,CAAC;IAEF,MAAM,SAAS,GAAG,IAAI,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,kBAAkB,EAAE,CAAC;IACjE,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;IAClD,MAAM,KAAK,GAAG,UAAU,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IACtC,MAAM,SAAS,GAAG,IAAI,KAAK,CAAC,SAAS,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IAEpD,oCAAoC;IACpC,MAAM,cAAc,GAAG,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC;SACzC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,OAAO,EAAE,WAAW,EAAE,SAAS,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;SAChF,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,IAAI,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC;SAC5F,IAAI,CAAC,KAAK,CAAC,CAAC;IAEf,MAAM,UAAU,GAAG,cAAc,CAAC,CAAC,CAAC,MAAM,cAAc,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IAEhE,OAAO,GAAG,KAAK,IAAI,SAAS,IAAI,KAAK,IAAI,SAAS,IAAI,KAAK,CAAC,OAAO,GAAG,UAAU,EAAE,CAAC;AACrF,CAAC"}

package/dist/rules-engine.d.ts

@@ -0,0 +1,159 @@
+/**
+ * Rules Engine
+ * ============
+ * Two responsibilities:
+ *
+ *  1. SpendRules — a fluent builder that makes it easy to construct SpendRule
+ *     objects without remembering field names. Also ships pre-built templates
+ *     for common agent configurations.
+ *
+ *  2. evaluateAuthorization — takes a live Stripe authorization request plus
+ *     a card's rules and returns an approve/decline decision. This is called
+ *     from the webhook handler in real time (within the ~2s Stripe window).
+ *
+ * All amounts are in cents throughout. Stripe uses cents; we match that to
+ * avoid any float-to-dollar conversion bugs.
+ *
+ * ─── Design philosophy ───────────────────────────────────────────────────────
+ * The rules engine enforces two core hard controls:
+ *   1. Spend limits (daily, monthly, per-transaction)
+ *   2. Category locks (allowed/blocked merchant categories)
+ *
+ * Confidence scoring — where agents self-report how sure they are about a
+ * purchase — was deliberately removed. Self-reported confidence is unreliable:
+ * an agent with no safety awareness will report 1.0; a cautious agent might
+ * report 0.7 for a perfectly reasonable purchase. It adds noise without
+ * adding real safety. Hard limits are the guardrail. Category locks add
+ * specificity. That's the model.
+ */
+import Stripe from 'stripe';
+import { SpendRule, SpendRuleTemplate } from './types';
+export declare class SpendRules {
+    private rule;
+    /**
+     * Create a new SpendRules builder
+     */
+    constructor();
+    /**
+     * Load a pre-built template
+     */
+    static template(template: SpendRuleTemplate): SpendRules;
+    /**
+     * Set allowed merchant categories
+     * Only transactions in these categories will be approved
+     */
+    category(categories: string[]): SpendRules;
+    /**
+     * Set blocked merchant categories
+     * Transactions in these categories will be declined
+     */
+    blockCategory(categories: string[]): SpendRules;
+    /**
+     * Set maximum amount per transaction (in cents)
+     */
+    maxPerTx(cents: number): SpendRules;
+    /**
+     * Set daily spending limit (in cents)
+     */
+    dailyLimit(cents: number): SpendRules;
+    /**
+     * Set monthly spending limit (in cents)
+     */
+    monthlyLimit(cents: number): SpendRules;
+    /**
+     * Set per-authorization limit (in cents)
+     */
+    perAuthLimit(cents: number): SpendRules;
+    /**
+     * Set whether transactions above the approval threshold require human sign-off.
+     * Usually you don't call this directly — `approvalThreshold()` sets it automatically.
+     * But you can call it explicitly if you need to toggle approval requirements
+     * independently of the threshold value.
+     */
+    requiresApproval(required: boolean): SpendRules;
+    /**
+     * Set approval threshold (in cents)
+     * Transactions above this amount require human approval.
+     * Also sets requiresApproval = true automatically.
+     */
+    approvalThreshold(cents: number): SpendRules;
+    /**
+     * Set failure handling behavior.
+     *
+     * Currently only 'decline' is fully implemented in the authorization flow.
+     * 'alert' and 'pause' are accepted for forward compatibility but behave
+     * the same as 'decline' today — the charge is declined. These modes will
+     * be wired to notification and card-pausing logic in a future release.
+     */
+    onFailure(action: 'decline' | 'alert' | 'pause'): SpendRules;
+    /**
+     * Set human-readable name for this rule set
+     */
+    name(name: string): SpendRules;
+    /**
+     * Set human-readable description for this rule set
+     */
+    description(desc: string): SpendRules;
+    /**
+     * Build and return the final SpendRule object
+     */
+    build(): SpendRule;
+    /**
+     * Get a string representation of the rules
+     */
+    toString(): string;
+}
+/**
+ * Evaluate a transaction against a rule set
+ * Returns { allowed: boolean, reason?: string }
+ */
+export declare function evaluateRule(rule: SpendRule, transaction: {
+    amount: number;
+    category?: string;
+}): {
+    allowed: boolean;
+    reason?: string;
+};
+/**
+ * The decision returned by evaluateAuthorization.
+ * `approved` goes directly into the Stripe webhook response.
+ * `reason` is logged for debugging and audit purposes.
+ */
+export interface AuthorizationDecision {
+    approved: boolean;
+    reason: string;
+}
+/**
+ * Current spend context passed into evaluateAuthorization.
+ * The caller (webhook handler) retrieves these from the tracker and passes
+ * them in, keeping the rules engine pure and easy to test without mocking
+ * any global state.
+ */
+export interface SpendContext {
+    /** How many cents the card has spent today (UTC calendar day). */
+    dailySpend: number;
+    /** How many cents the card has spent this calendar month (UTC). */
+    monthlySpend: number;
+}
+/**
+ * evaluateAuthorization
+ * ──────────────────────
+ * The core decision function. Given a live Stripe authorization request and
+ * the card's spending rules, determines whether to approve or decline.
+ *
+ * Rules are checked in order of cheapest/fastest first:
+ *  1. Merchant category (allowed list, then blocked list)
+ *  2. Per-transaction amount limit
+ *  3. Daily budget (current spend + this tx > limit?)
+ *  4. Monthly budget
+ *
+ * The first failing check short-circuits and returns a decline with a reason
+ * string that explains exactly which rule tripped.
+ *
+ * @param auth    - The Stripe Issuing.Authorization from the webhook event
+ * @param rules   - The SpendRule configured for this card
+ * @param context - Current spend totals from the tracker
+ * @returns AuthorizationDecision with approved flag and human-readable reason
+ */
+export declare function evaluateAuthorization(auth: Stripe.Issuing.Authorization, rules: SpendRule, context: SpendContext): AuthorizationDecision;
+//# sourceMappingURL=rules-engine.d.ts.map

package/dist/rules-engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rules-engine.d.ts","sourceRoot":"","sources":["../src/rules-engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,MAAM,MAAM,QAAQ,CAAC;AAE5B,OAAO,EAAE,SAAS,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAIvD,qBAAa,UAAU;IACrB,OAAO,CAAC,IAAI,CAAiB;IAE7B;;OAEG;;IAKH;;OAEG;IACH,MAAM,CAAC,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,GAAG,UAAU;IAmDxD;;;OAGG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,UAAU;IAK1C;;;OAGG;IACH,aAAa,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,UAAU;IAK/C;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU;IAQnC;;OAEG;IACH,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU;IASrC;;OAEG;IACH,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU;IASvC;;OAEG;IACH,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU;IASvC;;;;;OAKG;IACH,gBAAgB,CAAC,QAAQ,EAAE,OAAO,GAAG,UAAU;IAK/C;;;;OAIG;IACH,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU;IAS5C;;;;;;;OAOG;IACH,SAAS,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,GAAG,OAAO,GAAG,UAAU;IAK5D;;OAEG;IACH,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU;IAK9B;;OAEG;IACH,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU;IAKrC;;OAEG;IACH,KAAK,IAAI,SAAS;IASlB;;OAEG;IACH,QAAQ,IAAI,MAAM;CAiCnB;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,SAAS,EACf,WAAW,EAAE;IACX,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GACA;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAwCvC;AAID;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,kEAAkE;IAClE,UAAU,EAAE,MAAM,CAAC;IACnB,mEAAmE;IACnE,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,MAAM,CAAC,OAAO,CAAC,aAAa,EAClC,KAAK,EAAE,SAAS,EAChB,OAAO,EAAE,YAAY,GACpB,qBAAqB,CAuFvB"}