@firela/billclaw-core 0.1.3

package/dist/storage/indexes.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Query indexes for BillClaw
+ *
+ * Provides in-memory indexes for common query patterns:
+ * - Date-based queries (transactions by date range)
+ * - Category-based queries
+ * - Merchant-based queries
+ * - Amount-based queries
+ *
+ * Indexes improve query performance from O(n) to O(log n) or O(1).
+ */
+import type { Transaction } from "./transaction-storage.js";
+import type { Logger } from "../errors/errors.js";
+/**
+ * Index configuration
+ */
+export interface IndexConfig {
+    rebuildThreshold?: number;
+    logger?: Logger;
+}
+/**
+ * Transaction indexes
+ */
+export declare class TransactionIndexes {
+    private indexes;
+    private config;
+    constructor(config?: IndexConfig);
+    /**
+     * Build indexes for a set of transactions
+     *
+     * @param transactions - Transactions to index
+     * @param indexType - Type of index to build
+     */
+    buildIndex(transactions: Transaction[], indexType: IndexType): void;
+    /**
+     * Get the index key for a transaction
+     */
+    private getIndexKey;
+    /**
+     * Query transactions by index key
+     *
+     * @param indexType - Type of index to query
+     * @param _key - Key to look up (not used in simplified implementation)
+     * @returns Set of transaction IDs matching the key
+     */
+    query(indexType: IndexType, _key: string): Set<string>;
+    /**
+     * Clear all indexes
+     */
+    clear(): void;
+    /**
+     * Get index statistics
+     */
+    getStats(): Record<string, number>;
+}
+/**
+ * Index types
+ */
+export declare enum IndexType {
+    /** Index by transaction date */
+    DATE = "date",
+    /** Index by primary category */
+    CATEGORY = "category",
+    /** Index by merchant name */
+    MERCHANT = "merchant",
+    /** Index by amount range (buckets) */
+    AMOUNT_RANGE = "amount_range",
+    /** Index by pending status */
+    PENDING = "pending"
+}
+/**
+ * Query builder for filtering transactions
+ */
+export declare class TransactionQueryBuilder {
+    private filters;
+    /**
+     * Filter by date range
+     */
+    dateRange(start: Date, end: Date): this;
+    /**
+     * Filter by category
+     */
+    category(category: string): this;
+    /**
+     * Filter by merchant name (partial match)
+     */
+    merchant(merchant: string): this;
+    /**
+     * Filter by amount range (in cents)
+     */
+    amountRange(min: number, max: number): this;
+    /**
+     * Filter by pending status
+     */
+    pending(isPending: boolean): this;
+    /**
+     * Apply all filters to a set of transactions
+     */
+    apply(transactions: Transaction[]): Transaction[];
+    /**
+     * Clear all filters
+     */
+    clear(): this;
+}
+/**
+ * Inverted index for full-text search
+ */
+export declare class FullTextIndex {
+    private index;
+    private transactionData;
+    /**
+     * Add a transaction to the index
+     */
+    add(transaction: Transaction): void;
+    /**
+     * Index a document
+     */
+    private indexDocument;
+    /**
+     * Search for transactions matching a query
+     */
+    search(query: string): Transaction[];
+    /**
+     * Clear the index
+     */
+    clear(): void;
+}
+/**
+ * Create a query builder
+ */
+export declare function createQueryBuilder(): TransactionQueryBuilder;
+/**
+ * Create a full-text index
+ */
+export declare function createFullTextIndex(): FullTextIndex;
+//# sourceMappingURL=indexes.d.ts.map

package/dist/storage/indexes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"indexes.d.ts","sourceRoot":"","sources":["../../src/storage/indexes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAA;AAC3D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAA;AAWjD;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAeD;;GAEG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,OAAO,CAAgC;IAC/C,OAAO,CAAC,MAAM,CAAuB;gBAEzB,MAAM,GAAE,WAAgB;IAQpC;;;;;OAKG;IACH,UAAU,CAAC,YAAY,EAAE,WAAW,EAAE,EAAE,SAAS,EAAE,SAAS,GAAG,IAAI;IAoBnE;;OAEG;IACH,OAAO,CAAC,WAAW;IA+BnB;;;;;;OAMG;IACH,KAAK,CAAC,SAAS,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC;IAatD;;OAEG;IACH,KAAK,IAAI,IAAI;IAKb;;OAEG;IACH,QAAQ,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;CASnC;AAED;;GAEG;AACH,oBAAY,SAAS;IACnB,gCAAgC;IAChC,IAAI,SAAS;IAEb,gCAAgC;IAChC,QAAQ,aAAa;IAErB,6BAA6B;IAC7B,QAAQ,aAAa;IAErB,sCAAsC;IACtC,YAAY,iBAAiB;IAE7B,8BAA8B;IAC9B,OAAO,YAAY;CACpB;AAED;;GAEG;AACH,qBAAa,uBAAuB;IAClC,OAAO,CAAC,OAAO,CAA2C;IAE1D;;OAEG;IACH,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,GAAG,IAAI;IAQvC;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAOhC;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAOhC;;OAEG;IACH,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI;IAK3C;;OAEG;IACH,OAAO,CAAC,SAAS,EAAE,OAAO,GAAG,IAAI;IAKjC;;OAEG;IACH,KAAK,CAAC,YAAY,EAAE,WAAW,EAAE,GAAG,WAAW,EAAE;IAMjD;;OAEG;IACH,KAAK,IAAI,IAAI;CAId;AAED;;GAEG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,KAAK,CAAiC;IAC9C,OAAO,CAAC,eAAe,CAAiC;IAExD;;OAEG;IACH,GAAG,CAAC,WAAW,EAAE,WAAW,GAAG,IAAI;IAcnC;;OAEG;IACH,OAAO,CAAC,aAAa;IAcrB;;OAEG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW,EAAE;IAoDpC;;OAEG;IACH,KAAK,IAAI,IAAI;CAId;AAED;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,uBAAuB,CAE5D;AAED;;GAEG;AACH,wBAAgB,mBAAmB,IAAI,aAAa,CAEnD"}

package/dist/storage/indexes.js

@@ -0,0 +1,294 @@
+/**
+ * Query indexes for BillClaw
+ *
+ * Provides in-memory indexes for common query patterns:
+ * - Date-based queries (transactions by date range)
+ * - Category-based queries
+ * - Merchant-based queries
+ * - Amount-based queries
+ *
+ * Indexes improve query performance from O(n) to O(log n) or O(1).
+ */
+/**
+ * Default index configuration
+ */
+const DEFAULT_INDEX_CONFIG = {
+    rebuildThreshold: 0.1, // 10% change threshold
+    logger: {
+        info: () => { },
+        error: () => { },
+        warn: () => { },
+        debug: () => { },
+    },
+};
+/**
+ * Transaction indexes
+ */
+export class TransactionIndexes {
+    indexes = new Map();
+    config;
+    constructor(config = {}) {
+        this.config = {
+            rebuildThreshold: config.rebuildThreshold ?? DEFAULT_INDEX_CONFIG.rebuildThreshold,
+            logger: config.logger ?? DEFAULT_INDEX_CONFIG.logger,
+        };
+    }
+    /**
+     * Build indexes for a set of transactions
+     *
+     * @param transactions - Transactions to index
+     * @param indexType - Type of index to build
+     */
+    buildIndex(transactions, indexType) {
+        const index = {
+            key: indexType,
+            transactionIds: new Set(),
+            updatedAt: Date.now(),
+        };
+        for (const txn of transactions) {
+            const key = this.getIndexKey(txn, indexType);
+            if (key) {
+                index.transactionIds.add(txn.transactionId);
+            }
+        }
+        this.indexes.set(indexType, index);
+        this.config.logger?.debug?.(`Built index: ${indexType} (${index.transactionIds.size} entries)`);
+    }
+    /**
+     * Get the index key for a transaction
+     */
+    getIndexKey(transaction, indexType) {
+        switch (indexType) {
+            case IndexType.DATE:
+                return transaction.date;
+            case IndexType.CATEGORY:
+                return transaction.category?.[0] || "uncategorized";
+            case IndexType.MERCHANT:
+                return transaction.merchantName || "unknown";
+            case IndexType.AMOUNT_RANGE:
+                // Bucket amounts into ranges
+                const amount = Math.abs(transaction.amount);
+                if (amount < 1000)
+                    return "0-10"; // <$10
+                if (amount < 5000)
+                    return "10-50"; // $10-$50
+                if (amount < 10000)
+                    return "50-100"; // $50-$100
+                if (amount < 50000)
+                    return "100-500"; // $100-$500
+                return "500+"; // >$500
+            case IndexType.PENDING:
+                return transaction.pending ? "pending" : "posted";
+            default:
+                return null;
+        }
+    }
+    /**
+     * Query transactions by index key
+     *
+     * @param indexType - Type of index to query
+     * @param _key - Key to look up (not used in simplified implementation)
+     * @returns Set of transaction IDs matching the key
+     */
+    query(indexType, _key) {
+        const index = this.indexes.get(indexType);
+        if (!index) {
+            this.config.logger?.warn?.(`Index not found: ${indexType}`);
+            return new Set();
+        }
+        // For now, return all IDs in the index
+        // A full implementation would need to store key -> IDs mapping
+        return index.transactionIds;
+    }
+    /**
+     * Clear all indexes
+     */
+    clear() {
+        this.indexes.clear();
+        this.config.logger?.debug?.("Indexes cleared");
+    }
+    /**
+     * Get index statistics
+     */
+    getStats() {
+        const stats = {};
+        for (const [key, entry] of this.indexes.entries()) {
+            stats[key] = entry.transactionIds.size;
+        }
+        return stats;
+    }
+}
+/**
+ * Index types
+ */
+export var IndexType;
+(function (IndexType) {
+    /** Index by transaction date */
+    IndexType["DATE"] = "date";
+    /** Index by primary category */
+    IndexType["CATEGORY"] = "category";
+    /** Index by merchant name */
+    IndexType["MERCHANT"] = "merchant";
+    /** Index by amount range (buckets) */
+    IndexType["AMOUNT_RANGE"] = "amount_range";
+    /** Index by pending status */
+    IndexType["PENDING"] = "pending";
+})(IndexType || (IndexType = {}));
+/**
+ * Query builder for filtering transactions
+ */
+export class TransactionQueryBuilder {
+    filters = [];
+    /**
+     * Filter by date range
+     */
+    dateRange(start, end) {
+        this.filters.push((txn) => {
+            const txnDate = new Date(txn.date);
+            return txnDate >= start && txnDate <= end;
+        });
+        return this;
+    }
+    /**
+     * Filter by category
+     */
+    category(category) {
+        this.filters.push((txn) => txn.category?.some((c) => c.toLowerCase() === category.toLowerCase()));
+        return this;
+    }
+    /**
+     * Filter by merchant name (partial match)
+     */
+    merchant(merchant) {
+        this.filters.push((txn) => txn.merchantName?.toLowerCase().includes(merchant.toLowerCase()));
+        return this;
+    }
+    /**
+     * Filter by amount range (in cents)
+     */
+    amountRange(min, max) {
+        this.filters.push((txn) => txn.amount >= min && txn.amount <= max);
+        return this;
+    }
+    /**
+     * Filter by pending status
+     */
+    pending(isPending) {
+        this.filters.push((txn) => txn.pending === isPending);
+        return this;
+    }
+    /**
+     * Apply all filters to a set of transactions
+     */
+    apply(transactions) {
+        return transactions.filter((txn) => this.filters.every((filter) => filter(txn)));
+    }
+    /**
+     * Clear all filters
+     */
+    clear() {
+        this.filters = [];
+        return this;
+    }
+}
+/**
+ * Inverted index for full-text search
+ */
+export class FullTextIndex {
+    index = new Map();
+    transactionData = new Map();
+    /**
+     * Add a transaction to the index
+     */
+    add(transaction) {
+        this.transactionData.set(transaction.transactionId, transaction);
+        // Index merchant name
+        if (transaction.merchantName) {
+            this.indexDocument(transaction.transactionId, transaction.merchantName);
+        }
+        // Index categories
+        for (const category of transaction.category || []) {
+            this.indexDocument(transaction.transactionId, category);
+        }
+    }
+    /**
+     * Index a document
+     */
+    indexDocument(transactionId, text) {
+        const words = text.toLowerCase().split(/\s+/);
+        for (const word of words) {
+            if (word.length < 2)
+                continue; // Skip very short words
+            if (!this.index.has(word)) {
+                this.index.set(word, new Set());
+            }
+            this.index.get(word).add(transactionId);
+        }
+    }
+    /**
+     * Search for transactions matching a query
+     */
+    search(query) {
+        const words = query
+            .toLowerCase()
+            .split(/\s+/)
+            .filter((w) => w.length >= 2);
+        if (words.length === 0) {
+            return [];
+        }
+        // Find transactions matching all words (AND query)
+        let matchingIds = null;
+        for (const word of words) {
+            const ids = this.index.get(word);
+            if (!ids) {
+                // Word not found, no results
+                return [];
+            }
+            if (!matchingIds) {
+                matchingIds = new Set(ids);
+            }
+            else {
+                // Intersect with current results
+                const existingIds = matchingIds;
+                matchingIds = new Set();
+                for (const id of existingIds) {
+                    if (ids.has(id)) {
+                        matchingIds.add(id);
+                    }
+                }
+            }
+            if (matchingIds.size === 0) {
+                return [];
+            }
+        }
+        // Convert IDs to transactions
+        const results = [];
+        for (const id of matchingIds || []) {
+            const txn = this.transactionData.get(id);
+            if (txn) {
+                results.push(txn);
+            }
+        }
+        return results;
+    }
+    /**
+     * Clear the index
+     */
+    clear() {
+        this.index.clear();
+        this.transactionData.clear();
+    }
+}
+/**
+ * Create a query builder
+ */
+export function createQueryBuilder() {
+    return new TransactionQueryBuilder();
+}
+/**
+ * Create a full-text index
+ */
+export function createFullTextIndex() {
+    return new FullTextIndex();
+}
+//# sourceMappingURL=indexes.js.map

package/dist/storage/indexes.js.map

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

package/dist/storage/locking.d.ts

@@ -0,0 +1,103 @@
+/**
+ * File locking for BillClaw
+ *
+ * Provides inter-process file locking to prevent concurrent write conflicts.
+ * Uses proper-lockfile for cross-platform file locking.
+ *
+ * Use cases:
+ * - Preventing concurrent sync operations
+ * - Protecting credential writes
+ * - Coordinating between multiple processes
+ */
+import type { Logger } from "../errors/errors.js";
+/**
+ * Lock options
+ */
+export interface LockOptions {
+    /**
+     * Lock stale time in milliseconds
+     * If a lock is older than this, it will be considered stale and released
+     */
+    stale?: number;
+    /**
+     * Retry options
+     */
+    retries?: {
+        /**
+         * Number of retries to acquire the lock
+         */
+        count?: number;
+        /**
+         * Delay between retries in milliseconds
+         */
+        min?: number;
+        max?: number;
+    };
+    /**
+     * Logger for debug output
+     */
+    logger?: Logger;
+}
+/**
+ * Lock handle
+ */
+export interface Lock {
+    /**
+     * Release the lock
+     */
+    release(): Promise<void>;
+    /**
+     * Check if the lock is still held
+     */
+    isLocked(): Promise<boolean>;
+}
+/**
+ * Acquire a file lock
+ *
+ * @param filePath - Path to the file to lock
+ * @param options - Lock options
+ * @returns Lock handle that must be released when done
+ */
+export declare function acquireLock(filePath: string, options?: LockOptions): Promise<Lock>;
+/**
+ * Execute a function while holding a lock
+ *
+ * @param filePath - Path to the file to lock
+ * @param fn - Function to execute while holding the lock
+ * @param options - Lock options
+ * @returns Result of the function
+ */
+export declare function withLock<T>(filePath: string, fn: () => Promise<T>, options?: LockOptions): Promise<T>;
+/**
+ * Check if a file is locked
+ *
+ * @param filePath - Path to the file to check
+ * @returns true if the file is locked
+ */
+export declare function isLocked(filePath: string): Promise<boolean>;
+/**
+ * Lock names for common operations
+ */
+export declare const LockNames: {
+    /**
+     * Global sync lock (prevents concurrent sync operations)
+     */
+    SYNC: string;
+    /**
+     * Account-specific sync lock
+     */
+    accountSync(accountId: string): string;
+    /**
+     * Credential lock (protects credential writes)
+     */
+    CREDENTIALS: string;
+    /**
+     * Account-specific credential lock
+     */
+    accountCredentials(accountId: string): string;
+    /**
+     * Export lock (protects data export operations)
+     */
+    EXPORT: string;
+};
+//# sourceMappingURL=locking.d.ts.map

package/dist/storage/locking.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"locking.d.ts","sourceRoot":"","sources":["../../src/storage/locking.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAA;AAqBjD;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IAEd;;OAEG;IACH,OAAO,CAAC,EAAE;QACR;;WAEG;QACH,KAAK,CAAC,EAAE,MAAM,CAAA;QAEd;;WAEG;QACH,GAAG,CAAC,EAAE,MAAM,CAAA;QACZ,GAAG,CAAC,EAAE,MAAM,CAAA;KACb,CAAA;IAED;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAcD;;GAEG;AACH,MAAM,WAAW,IAAI;IACnB;;OAEG;IACH,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IAExB;;OAEG;IACH,QAAQ,IAAI,OAAO,CAAC,OAAO,CAAC,CAAA;CAC7B;AAwCD;;;;;;GAMG;AACH,wBAAsB,WAAW,CAC/B,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,WAAgB,GACxB,OAAO,CAAC,IAAI,CAAC,CA0Bf;AAED;;;;;;;GAOG;AACH,wBAAsB,QAAQ,CAAC,CAAC,EAC9B,QAAQ,EAAE,MAAM,EAChB,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,OAAO,GAAE,WAAgB,GACxB,OAAO,CAAC,CAAC,CAAC,CAQZ;AAED;;;;;GAKG;AACH,wBAAsB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAGjE;AAED;;GAEG;AACH,eAAO,MAAM,SAAS;IACpB;;OAEG;;IAGH;;OAEG;2BACoB,MAAM,GAAG,MAAM;IAItC;;OAEG;;IAGH;;OAEG;kCAC2B,MAAM,GAAG,MAAM;IAI7C;;OAEG;;CAEJ,CAAA"}