@opencard-dev/core 0.1.0

package/dist/rules-store.js

@@ -0,0 +1,291 @@
+"use strict";
+/**
+ * Rules Store
+ * ===========
+ * Persistent storage for SpendRule objects, backed by a local JSON file.
+ *
+ * ─── Why not keep rules in Stripe metadata? ─────────────────────────────────
+ * Storing rules in Stripe card metadata (as we did in Phase 1) is a security
+ * problem: anyone with Stripe dashboard access can edit the rules directly,
+ * bypassing any access controls we might add. By moving rules to our own store,
+ * we control who can read or modify them — and Stripe metadata only holds a
+ * reference ID (opencard_rule_id), not the rules themselves.
+ *
+ * ─── Why a JSON file? ────────────────────────────────────────────────────────
+ * Phase 1 is all about getting something working and safe without adding
+ * operational complexity. A JSON file:
+ *  - Survives process restarts (unlike in-memory)
+ *  - Requires no database setup or migration
+ *  - Is easy to inspect, back up, and version-control
+ *  - Is fast enough for Phase 1 workloads (hundreds of rules, not millions)
+ *
+ * Phase 2 will replace this with a proper database when we need multi-instance
+ * support or higher write throughput.
+ *
+ * ─── File format ─────────────────────────────────────────────────────────────
+ * The file is a JSON object: { [ruleId]: SpendRule }
+ * Example:
+ *   {
+ *     "rule_01HX9K2Z3A4B5C6D7E8F9G0H1J": { "dailyLimit": 10000, "onFailure": "decline" },
+ *     "rule_01HX9K2Z3A4B5C6D7E8F9G0H1K": { "monthlyLimit": 50000 }
+ *   }
+ *
+ * ─── ID format ───────────────────────────────────────────────────────────────
+ * IDs use the format `rule_<timestamp_hex><random_hex>` — lexicographically
+ * sortable (newer rules sort after older ones) and globally unique without
+ * a central counter. We implement this without external dependencies using
+ * Node.js's built-in crypto module.
+ *
+ * ─── Thread safety ───────────────────────────────────────────────────────────
+ * We serialize all writes through a simple async queue (each write awaits the
+ * previous one). This isn't needed for single-threaded Node.js, but it makes
+ * the behavior explicit and protects against future async-write bugs.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rulesStore = exports.RulesStore = void 0;
+const promises_1 = __importDefault(require("fs/promises"));
+const path_1 = __importDefault(require("path"));
+const crypto_1 = __importDefault(require("crypto"));
+const rules_validation_1 = require("./rules-validation");
+// ─── RulesStore class ─────────────────────────────────────────────────────────
+class RulesStore {
+    /**
+     * Path to the JSON file where rules are stored.
+     * Configurable via OPENCARD_RULES_PATH env var.
+     * Defaults to ./opencard-rules.json relative to the process working directory.
+     */
+    filePath;
+    /**
+     * Internal write queue: we chain writes so concurrent callers don't
+     * corrupt the file by reading stale contents and overwriting each other.
+     */
+    writeQueue = Promise.resolve();
+    constructor(filePath) {
+        // Prefer explicit argument, then env var, then default.
+        // path.resolve() converts relative paths to absolute, using process.cwd().
+        this.filePath = filePath
+            || process.env.OPENCARD_RULES_PATH
+            || path_1.default.resolve(process.cwd(), 'opencard-rules.json');
+    }
+    // ─── ID generation ─────────────────────────────────────────────────────────
+    /**
+     * Generates a unique, sortable rule ID.
+     *
+     * Format: `rule_<timestamp_ms_hex><random_8_hex_chars>`
+     * Example: `rule_018f1a2b3c4d5e6f7a8b9c0d`
+     *
+     * - The timestamp prefix makes IDs sort chronologically (newest last in
+     *   a lexicographic sort), which is useful when listing rules.
+     * - The random suffix prevents collisions even if two rules are created
+     *   in the same millisecond.
+     * - No external library needed — uses Node.js built-in crypto.
+     */
+    generateId() {
+        const timestampHex = Date.now().toString(16).padStart(12, '0');
+        const randomHex = crypto_1.default.randomBytes(6).toString('hex');
+        return `rule_${timestampHex}${randomHex}`;
+    }
+    // ─── File I/O ───────────────────────────────────────────────────────────────
+    /**
+     * Reads the rules file from disk and parses it.
+     *
+     * If the file doesn't exist yet, returns an empty object (not an error) —
+     * the file will be created on the first write.
+     *
+     * If the file exists but contains invalid JSON, throws an error. This
+     * shouldn't happen in normal operation (we always write valid JSON), but
+     * could happen if the file was manually edited.
+     */
+    async readFile() {
+        try {
+            const raw = await promises_1.default.readFile(this.filePath, 'utf8');
+            return JSON.parse(raw);
+        }
+        catch (err) {
+            // ENOENT = file not found — that's OK, just means no rules stored yet
+            if (err.code === 'ENOENT') {
+                return {};
+            }
+            // Any other error (permission denied, malformed JSON, etc.) is a real problem
+            throw new Error(`[RulesStore] Failed to read rules file at ${this.filePath}: ${String(err)}`);
+        }
+    }
+    /**
+     * Writes the entire rules object to disk, atomically.
+     *
+     * We write to a temp file first, then rename it into place. This avoids
+     * leaving a half-written file if the process crashes mid-write.
+     *
+     * All writes are serialized through the writeQueue to prevent concurrent
+     * writes from racing each other.
+     */
+    async writeFile(contents) {
+        // Chain this write onto the end of the queue
+        this.writeQueue = this.writeQueue.then(async () => {
+            const tmpPath = `${this.filePath}.tmp`;
+            const json = JSON.stringify(contents, null, 2); // pretty-print for human readability
+            try {
+                // Ensure the parent directory exists (in case OPENCARD_RULES_PATH points
+                // to a dir that hasn't been created yet)
+                await promises_1.default.mkdir(path_1.default.dirname(this.filePath), { recursive: true });
+                // Write to temp file first
+                await promises_1.default.writeFile(tmpPath, json, 'utf8');
+                // Rename into place (atomic on POSIX systems when same filesystem)
+                await promises_1.default.rename(tmpPath, this.filePath);
+            }
+            catch (err) {
+                // Clean up temp file if we can (ignore errors from cleanup itself)
+                await promises_1.default.unlink(tmpPath).catch(() => { });
+                throw new Error(`[RulesStore] Failed to write rules file at ${this.filePath}: ${String(err)}`);
+            }
+        });
+        // Wait for this specific write to complete before returning
+        return this.writeQueue;
+    }
+    // ─── CRUD operations ────────────────────────────────────────────────────────
+    /**
+     * Creates a new rule in the store.
+     *
+     * Validates the rule before writing — throws if validation fails.
+     * This is the right place to reject bad rules so they never make it
+     * into the store and can never affect a live transaction.
+     *
+     * @param rule - The spend rule to store
+     * @returns The generated rule ID (e.g. "rule_018f1a2b3c4d5e6f7a8b9c0d")
+     *
+     * @throws Error if the rule fails validation
+     *
+     * @example
+     * const ruleId = await rulesStore.createRule({
+     *   dailyLimit: 10000,    // $100/day
+     *   onFailure: 'decline',
+     * });
+     * // ruleId → "rule_018f1a2b3c4d5e6f7a8b9c0d"
+     */
+    async createRule(rule) {
+        // Validate before writing — reject invalid rules with clear error messages
+        const validation = (0, rules_validation_1.validateRule)(rule);
+        if (!validation.valid) {
+            throw new Error(`[RulesStore] Invalid rule: ${validation.errors.join('; ')}`);
+        }
+        const ruleId = this.generateId();
+        const contents = await this.readFile();
+        // Sanity check: generated ID should never collide, but just in case
+        if (contents[ruleId]) {
+            throw new Error(`[RulesStore] ID collision on ${ruleId} — this should never happen`);
+        }
+        contents[ruleId] = rule;
+        await this.writeFile(contents);
+        console.log(`[RulesStore] Created rule ${ruleId}`);
+        return ruleId;
+    }
+    /**
+     * Looks up a rule by its ID.
+     *
+     * Returns null (not an error) if the rule doesn't exist. This is important
+     * in the webhook path: if a card references a rule ID that's been deleted,
+     * the webhook handler should fall back to default-deny, not crash.
+     *
+     * @param ruleId - The rule ID to look up
+     * @returns The SpendRule, or null if not found
+     *
+     * @example
+     * const rule = await rulesStore.getRule('rule_018f1a2b...');
+     * if (rule === null) {
+     *   // rule was deleted or ID is wrong — use default-deny
+     * }
+     */
+    async getRule(ruleId) {
+        const contents = await this.readFile();
+        return contents[ruleId] ?? null;
+    }
+    /**
+     * Updates an existing rule.
+     *
+     * Validates the new rule before writing. The update replaces the entire
+     * rule — it's not a partial merge. Pass the full updated rule object.
+     *
+     * @throws Error if the rule doesn't exist (can't update what isn't there)
+     * @throws Error if the new rule fails validation
+     *
+     * @example
+     * await rulesStore.updateRule('rule_018f1a2b...', {
+     *   dailyLimit: 20000,  // raised from $100 to $200
+     *   onFailure: 'decline',
+     * });
+     */
+    async updateRule(ruleId, rule) {
+        // Validate before writing
+        const validation = (0, rules_validation_1.validateRule)(rule);
+        if (!validation.valid) {
+            throw new Error(`[RulesStore] Invalid rule: ${validation.errors.join('; ')}`);
+        }
+        const contents = await this.readFile();
+        if (!contents[ruleId]) {
+            throw new Error(`[RulesStore] Rule ${ruleId} not found — cannot update a rule that doesn't exist`);
+        }
+        contents[ruleId] = rule;
+        await this.writeFile(contents);
+        console.log(`[RulesStore] Updated rule ${ruleId}`);
+    }
+    /**
+     * Deletes a rule from the store.
+     *
+     * Note: this does NOT update any cards that reference this rule.
+     * Cards referencing a deleted rule ID will fall back to default-deny
+     * in the webhook handler (by design — it's better to be safe).
+     *
+     * If the rule doesn't exist, this is a no-op (not an error).
+     *
+     * @param ruleId - The rule ID to delete
+     */
+    async deleteRule(ruleId) {
+        const contents = await this.readFile();
+        if (!contents[ruleId]) {
+            // No-op — deleting a non-existent rule is fine
+            console.warn(`[RulesStore] deleteRule called for non-existent rule ${ruleId} — no-op`);
+            return;
+        }
+        delete contents[ruleId];
+        await this.writeFile(contents);
+        console.log(`[RulesStore] Deleted rule ${ruleId}`);
+    }
+    /**
+     * Lists all rules in the store.
+     *
+     * Returns them sorted by ID (which is chronological since IDs are
+     * timestamp-prefixed). Newest rules appear last.
+     *
+     * @returns Array of { id, rule } objects, sorted by creation order
+     *
+     * @example
+     * const rules = await rulesStore.listRules();
+     * for (const { id, rule } of rules) {
+     *   console.log(`${id}: ${rule.name ?? 'unnamed'}`);
+     * }
+     */
+    async listRules() {
+        const contents = await this.readFile();
+        return Object.entries(contents)
+            .sort(([a], [b]) => a.localeCompare(b)) // sort by ID = sort by creation time
+            .map(([id, rule]) => ({ id, rule }));
+    }
+}
+exports.RulesStore = RulesStore;
+// ─── Singleton ────────────────────────────────────────────────────────────────
+/**
+ * Module-level singleton instance of RulesStore.
+ *
+ * Export and use this everywhere, just like the `tracker` singleton.
+ * This ensures all parts of the system share the same file path and
+ * write queue — critical for avoiding concurrent write corruption.
+ *
+ * @example
+ * import { rulesStore } from '@opencard-dev/core';
+ * const ruleId = await rulesStore.createRule({ dailyLimit: 10000 });
+ */
+exports.rulesStore = new RulesStore();
+//# sourceMappingURL=rules-store.js.map

package/dist/rules-store.js.map

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

package/dist/rules-validation.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Rule Validation
+ * ===============
+ * Validates SpendRule objects before they're written to the rules store.
+ *
+ * ─── Why validate at write time? ────────────────────────────────────────────
+ * We check rules when they're created or updated — not at authorization time.
+ * This means:
+ *  1. If you write a bad rule, you find out immediately (not at 2am when a
+ *     card transaction fails in a confusing way).
+ *  2. The authorization path (hot path, ~2 second window) stays fast and simple.
+ *  3. We can give detailed error messages to whoever is creating the rule,
+ *     not bury them in webhook logs.
+ *
+ * ─── What we validate ────────────────────────────────────────────────────────
+ *  - Numeric limits must be positive integers (cents, so negative = nonsense)
+ *  - Category arrays must actually be arrays of strings
+ *  - onFailure must be one of the known action strings
+ *
+ * ─── What we don't validate ──────────────────────────────────────────────────
+ * We don't validate category strings themselves (i.e., we don't check if
+ * "grocery" is a real Stripe MCC category). That would require a lookup table
+ * and would break if Stripe adds new categories. Better to allow unknown
+ * categories and just have them never match.
+ */
+import { SpendRule } from './types';
+/**
+ * Result of a rule validation check.
+ * `valid: true` means the rule is safe to store.
+ * `valid: false` means there are errors — check the `errors` array.
+ */
+export interface ValidationResult {
+    valid: boolean;
+    errors: string[];
+}
+/**
+ * Validates a SpendRule before it's written to the rules store.
+ *
+ * Collects ALL errors at once (instead of failing on the first one),
+ * so callers get a complete picture of what's wrong in a single call.
+ *
+ * @param rule - The rule to validate
+ * @returns { valid, errors } — if valid is false, errors has at least one entry
+ *
+ * @example
+ * const result = validateRule({ dailyLimit: -500, onFailure: 'explode' });
+ * // result.valid === false
+ * // result.errors === [
+ * //   "dailyLimit must be a positive number (in cents), got -500",
+ * //   "onFailure must be one of: decline, alert, pause — got 'explode'"
+ * // ]
+ */
+export declare function validateRule(rule: SpendRule): ValidationResult;
+//# sourceMappingURL=rules-validation.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"rules-validation.d.ts","sourceRoot":"","sources":["../src/rules-validation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAEpC;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AA+BD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,SAAS,GAAG,gBAAgB,CAgD9D"}

package/dist/rules-validation.js

@@ -0,0 +1,110 @@
+"use strict";
+/**
+ * Rule Validation
+ * ===============
+ * Validates SpendRule objects before they're written to the rules store.
+ *
+ * ─── Why validate at write time? ────────────────────────────────────────────
+ * We check rules when they're created or updated — not at authorization time.
+ * This means:
+ *  1. If you write a bad rule, you find out immediately (not at 2am when a
+ *     card transaction fails in a confusing way).
+ *  2. The authorization path (hot path, ~2 second window) stays fast and simple.
+ *  3. We can give detailed error messages to whoever is creating the rule,
+ *     not bury them in webhook logs.
+ *
+ * ─── What we validate ────────────────────────────────────────────────────────
+ *  - Numeric limits must be positive integers (cents, so negative = nonsense)
+ *  - Category arrays must actually be arrays of strings
+ *  - onFailure must be one of the known action strings
+ *
+ * ─── What we don't validate ──────────────────────────────────────────────────
+ * We don't validate category strings themselves (i.e., we don't check if
+ * "grocery" is a real Stripe MCC category). That would require a lookup table
+ * and would break if Stripe adds new categories. Better to allow unknown
+ * categories and just have them never match.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateRule = validateRule;
+/**
+ * The three valid values for onFailure.
+ * - 'decline': reject the transaction immediately
+ * - 'alert': approve but send an alert (Phase 2 feature)
+ * - 'pause': pause the card after violation (blocks future transactions)
+ */
+const VALID_ON_FAILURE_VALUES = ['decline', 'alert', 'pause'];
+/**
+ * The numeric fields in SpendRule that must be positive numbers if present.
+ * All are in cents (USD). Zero doesn't make sense as a limit — it would mean
+ * "allow spending of $0" which is effectively a declined card.
+ */
+const NUMERIC_LIMIT_FIELDS = [
+    'dailyLimit',
+    'monthlyLimit',
+    'maxPerTransaction',
+    'approvalThreshold',
+];
+/**
+ * The array fields in SpendRule that must be string arrays if present.
+ * These hold merchant category codes (MCCs) like "grocery", "transit", etc.
+ */
+const CATEGORY_ARRAY_FIELDS = [
+    'allowedCategories',
+    'blockedCategories',
+];
+/**
+ * Validates a SpendRule before it's written to the rules store.
+ *
+ * Collects ALL errors at once (instead of failing on the first one),
+ * so callers get a complete picture of what's wrong in a single call.
+ *
+ * @param rule - The rule to validate
+ * @returns { valid, errors } — if valid is false, errors has at least one entry
+ *
+ * @example
+ * const result = validateRule({ dailyLimit: -500, onFailure: 'explode' });
+ * // result.valid === false
+ * // result.errors === [
+ * //   "dailyLimit must be a positive number (in cents), got -500",
+ * //   "onFailure must be one of: decline, alert, pause — got 'explode'"
+ * // ]
+ */
+function validateRule(rule) {
+    const errors = [];
+    // ── Check numeric limit fields ──────────────────────────────────────────────
+    for (const field of NUMERIC_LIMIT_FIELDS) {
+        const value = rule[field];
+        if (value !== undefined) {
+            if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) {
+                errors.push(`${field} must be a positive number (in cents), got ${JSON.stringify(value)}`);
+            }
+        }
+    }
+    // ── Check category array fields ─────────────────────────────────────────────
+    for (const field of CATEGORY_ARRAY_FIELDS) {
+        const value = rule[field];
+        if (value !== undefined) {
+            if (!Array.isArray(value)) {
+                errors.push(`${field} must be an array of strings, got ${typeof value}`);
+            }
+            else {
+                // All elements must be strings
+                const nonStrings = value.filter((v) => typeof v !== 'string');
+                if (nonStrings.length > 0) {
+                    errors.push(`${field} must contain only strings — found ${nonStrings.length} non-string value(s): ${JSON.stringify(nonStrings)}`);
+                }
+            }
+        }
+    }
+    // ── Check onFailure ─────────────────────────────────────────────────────────
+    if (rule.onFailure !== undefined) {
+        if (!VALID_ON_FAILURE_VALUES.includes(rule.onFailure)) {
+            errors.push(`onFailure must be one of: ${VALID_ON_FAILURE_VALUES.join(', ')} — got '${rule.onFailure}'`);
+        }
+    }
+    return {
+        valid: errors.length === 0,
+        errors,
+    };
+}
+//# sourceMappingURL=rules-validation.js.map

package/dist/rules-validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rules-validation.js","sourceRoot":"","sources":["../src/rules-validation.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;;AA4DH,oCAgDC;AA9FD;;;;;GAKG;AACH,MAAM,uBAAuB,GAAG,CAAC,SAAS,EAAE,OAAO,EAAE,OAAO,CAAU,CAAC;AAEvE;;;;GAIG;AACH,MAAM,oBAAoB,GAAG;IAC3B,YAAY;IACZ,cAAc;IACd,mBAAmB;IACnB,mBAAmB;CACX,CAAC;AAEX;;;GAGG;AACH,MAAM,qBAAqB,GAAG;IAC5B,mBAAmB;IACnB,mBAAmB;CACX,CAAC;AAEX;;;;;;;;;;;;;;;;GAgBG;AACH,SAAgB,YAAY,CAAC,IAAe;IAC1C,MAAM,MAAM,GAAa,EAAE,CAAC;IAE5B,+EAA+E;IAC/E,KAAK,MAAM,KAAK,IAAI,oBAAoB,EAAE,CAAC;QACzC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC;QAC1B,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,EAAE,CAAC;gBACvE,MAAM,CAAC,IAAI,CACT,GAAG,KAAK,8CAA8C,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CAC9E,CAAC;YACJ,CAAC;QACH,CAAC;IACH,CAAC;IAED,+EAA+E;IAC/E,KAAK,MAAM,KAAK,IAAI,qBAAqB,EAAE,CAAC;QAC1C,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC;QAC1B,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;gBAC1B,MAAM,CAAC,IAAI,CACT,GAAG,KAAK,qCAAqC,OAAO,KAAK,EAAE,CAC5D,CAAC;YACJ,CAAC;iBAAM,CAAC;gBACN,+BAA+B;gBAC/B,MAAM,UAAU,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC;gBAC9D,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;oBAC1B,MAAM,CAAC,IAAI,CACT,GAAG,KAAK,sCAAsC,UAAU,CAAC,MAAM,yBAAyB,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,EAAE,CACrH,CAAC;gBACJ,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;IAED,+EAA+E;IAC/E,IAAI,IAAI,CAAC,SAAS,KAAK,SAAS,EAAE,CAAC;QACjC,IAAI,CAAC,uBAAuB,CAAC,QAAQ,CAAC,IAAI,CAAC,SAAmD,CAAC,EAAE,CAAC;YAChG,MAAM,CAAC,IAAI,CACT,6BAA6B,uBAAuB,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,IAAI,CAAC,SAAS,GAAG,CAC5F,CAAC;QACJ,CAAC;IACH,CAAC;IAED,OAAO;QACL,KAAK,EAAE,MAAM,CAAC,MAAM,KAAK,CAAC;QAC1B,MAAM;KACP,CAAC;AACJ,CAAC"}

package/dist/stripe-client.d.ts

@@ -0,0 +1,154 @@
+/**
+ * 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.
+ */
+import { OpenCardConfig, Card, Cardholder, BillingDetails, CardCreateOptions, Transaction, CardBalance, TransactionQueryOptions, Authorization, SpendingLimits } from './types';
+export declare class StripeClient {
+    /** The underlying Stripe SDK instance. Use this for any Stripe calls not yet wrapped here. */
+    private stripe;
+    /** Stored config so we can reference it in later operations. */
+    private 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?: OpenCardConfig);
+    /**
+     * 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
+     */
+    createCardholder(name: string, email: string, billing?: BillingDetails): Promise<Cardholder>;
+    /**
+     * 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
+     */
+    createCard(cardholderId: string, options: CardCreateOptions): Promise<Card>;
+    /**
+     * 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")
+     */
+    getCard(cardId: string): Promise<Card>;
+    /**
+     * 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
+     */
+    pauseCard(cardId: string): Promise<Card>;
+    /**
+     * 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
+     */
+    resumeCard(cardId: string): Promise<Card>;
+    /**
+     * 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
+     */
+    setSpendingLimits(cardId: string, limits: SpendingLimits[]): Promise<Card>;
+    /**
+     * 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.)
+     */
+    getTransactions(cardId: string, options?: TransactionQueryOptions): Promise<Transaction[]>;
+    /**
+     * 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.
+     */
+    getBalance(): Promise<CardBalance>;
+    /**
+     * 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)
+     */
+    getPendingAuthorizations(_cardId: string): Promise<Authorization[]>;
+}
+//# sourceMappingURL=stripe-client.d.ts.map

package/dist/stripe-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stripe-client.d.ts","sourceRoot":"","sources":["../src/stripe-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAGH,OAAO,EACL,cAAc,EACd,IAAI,EACJ,UAAU,EACV,cAAc,EACd,iBAAiB,EACjB,WAAW,EACX,WAAW,EACX,uBAAuB,EACvB,aAAa,EACb,cAAc,EACf,MAAM,SAAS,CAAC;AAIjB,qBAAa,YAAY;IACvB,8FAA8F;IAC9F,OAAO,CAAC,MAAM,CAAS;IACvB,gEAAgE;IAChE,OAAO,CAAC,MAAM,CAA2B;IAEzC;;;;;;;;;;;;;OAaG;gBACS,MAAM,GAAE,cAAmB;IAqCvC;;;;;;;;;;;;;;OAcG;IACG,gBAAgB,CACpB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,UAAU,CAAC;IAiDtB;;;;;;;;;;;;;;OAcG;IACG,UAAU,CACd,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAAC,IAAI,CAAC;IA8DhB;;;;;OAKG;IACG,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAc5C;;;;;;;;;;OAUG;IACG,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAgB9C;;;;;OAKG;IACG,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAgB/C;;;;;;;;;OASG;IACG,iBAAiB,CACrB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,cAAc,EAAE,GACvB,OAAO,CAAC,IAAI,CAAC;IAwBhB;;;;;;;;;;;;;OAaG;IACG,eAAe,CACnB,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,uBAAuB,GAChC,OAAO,CAAC,WAAW,EAAE,CAAC;IAkCzB;;;;;;;;OAQG;IACG,UAAU,IAAI,OAAO,CAAC,WAAW,CAAC;IASxC;;;;;;;;OAQG;IACG,wBAAwB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC;CAM1E"}