@firela/billclaw-core 0.1.3

package/dist/storage/locking.js

@@ -0,0 +1,158 @@
+/**
+ * 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
+ */
+// Lockfile module (lazy loaded)
+let lockfileModule = null;
+/**
+ * Initialize lockfile module
+ */
+async function initLockfile() {
+    if (!lockfileModule) {
+        try {
+            lockfileModule = await import("proper-lockfile");
+        }
+        catch (error) {
+            throw new Error("proper-lockfile is not installed. Install it with: npm install proper-lockfile");
+        }
+    }
+    return lockfileModule;
+}
+/**
+ * Default lock options
+ */
+const DEFAULT_LOCK_OPTIONS = {
+    stale: 60 * 1000, // 1 minute
+    retries: {
+        count: 10,
+        min: 100,
+        max: 500,
+    },
+};
+/**
+ * File lock implementation
+ */
+class FileLock {
+    filePath;
+    logger;
+    released = false;
+    constructor(filePath, logger) {
+        this.filePath = filePath;
+        this.logger = logger;
+    }
+    async release() {
+        if (this.released) {
+            return;
+        }
+        const lockfile = await initLockfile();
+        try {
+            await lockfile.unlock(this.filePath);
+            this.released = true;
+            this.logger?.debug?.(`Released lock: ${this.filePath}`);
+        }
+        catch (error) {
+            this.logger?.error?.(`Failed to release lock: ${this.filePath}`, error);
+            throw error;
+        }
+    }
+    async isLocked() {
+        if (this.released) {
+            return false;
+        }
+        const lockfile = await initLockfile();
+        return lockfile.check(this.filePath);
+    }
+}
+/**
+ * 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 async function acquireLock(filePath, options = {}) {
+    const opts = { ...DEFAULT_LOCK_OPTIONS, ...options };
+    const lockfile = await initLockfile();
+    try {
+        await lockfile.lock(filePath, {
+            stale: opts.stale,
+            retries: opts.retries
+                ? {
+                    retries: opts.retries.count,
+                    minTimeout: opts.retries.min,
+                    maxTimeout: opts.retries.max,
+                }
+                : undefined,
+        });
+        options.logger?.debug?.(`Acquired lock: ${filePath}`);
+        return new FileLock(filePath, options.logger);
+    }
+    catch (error) {
+        options.logger?.error?.(`Failed to acquire lock: ${filePath}`, error);
+        throw new Error(`Failed to acquire lock on ${filePath}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+/**
+ * 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 async function withLock(filePath, fn, options = {}) {
+    const lock = await acquireLock(filePath, options);
+    try {
+        return await fn();
+    }
+    finally {
+        await lock.release();
+    }
+}
+/**
+ * Check if a file is locked
+ *
+ * @param filePath - Path to the file to check
+ * @returns true if the file is locked
+ */
+export async function isLocked(filePath) {
+    const lockfile = await initLockfile();
+    return lockfile.check(filePath);
+}
+/**
+ * Lock names for common operations
+ */
+export const LockNames = {
+    /**
+     * Global sync lock (prevents concurrent sync operations)
+     */
+    SYNC: ".sync.lock",
+    /**
+     * Account-specific sync lock
+     */
+    accountSync(accountId) {
+        return `.sync_${accountId}.lock`;
+    },
+    /**
+     * Credential lock (protects credential writes)
+     */
+    CREDENTIALS: ".credentials.lock",
+    /**
+     * Account-specific credential lock
+     */
+    accountCredentials(accountId) {
+        return `.credentials_${accountId}.lock`;
+    },
+    /**
+     * Export lock (protects data export operations)
+     */
+    EXPORT: ".export.lock",
+};
+//# sourceMappingURL=locking.js.map

package/dist/storage/locking.js.map

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

package/dist/storage/streaming.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Streaming JSON support for BillClaw
+ *
+ * Provides streaming JSON parsing and generation for large datasets.
+ * This keeps memory usage constant regardless of file size.
+ *
+ * Use cases:
+ * - Reading large transaction files without loading entire file
+ * - Writing large datasets incrementally
+ * - Processing transactions one at a time
+ */
+import type { Transaction } from "./transaction-storage.js";
+import type { Logger } from "../errors/errors.js";
+/**
+ * Options for streaming JSON write
+ */
+export interface StreamingWriteOptions {
+    batchSize?: number;
+    logger?: Logger;
+}
+/**
+ * Options for streaming JSON read
+ */
+export interface StreamingReadOptions<T> {
+    batchSize?: number;
+    filter?: (item: T) => boolean;
+    transform?: (item: T) => T;
+    logger?: Logger;
+}
+/**
+ * Write items to a JSON file incrementally
+ *
+ * @param filePath - Path to output file
+ * @param items - Async iterable of items to write
+ * @param options - Write options
+ */
+export declare function writeStreamingJson<T>(filePath: string, items: AsyncIterable<T>, options?: StreamingWriteOptions): Promise<void>;
+/**
+ * Read items from a JSON file incrementally
+ *
+ * @param filePath - Path to input file
+ * @param options - Read options
+ * @returns Async iterable of items
+ */
+export declare function readStreamingJson<T>(filePath: string, options?: StreamingReadOptions<T>): AsyncIterable<T>;
+/**
+ * Stream transactions from a file
+ *
+ * @param filePath - Path to transaction file
+ * @param options - Stream options
+ * @returns Async iterable of transactions
+ */
+export declare function streamTransactions(filePath: string, options?: StreamingReadOptions<Transaction>): AsyncIterable<Transaction>;
+/**
+ * Write transactions to a file incrementally
+ *
+ * @param filePath - Path to output file
+ * @param transactions - Async iterable of transactions
+ * @param options - Write options
+ */
+export declare function writeTransactionsStreaming(filePath: string, transactions: AsyncIterable<Transaction>, options?: StreamingWriteOptions): Promise<void>;
+/**
+ * Map/reduce operations on streaming JSON
+ */
+export declare class StreamingJsonOperations<T> {
+    private filePath;
+    private logger?;
+    constructor(filePath: string, logger?: Logger | undefined);
+    /**
+     * Map each item through a transformation function
+     */
+    map<U>(fn: (item: T) => U): Promise<U[]>;
+    /**
+     * Filter items
+     */
+    filter(fn: (item: T) => boolean): Promise<T[]>;
+    /**
+     * Reduce items to a single value
+     */
+    reduce<U>(fn: (acc: U, item: T) => U, initial: U): Promise<U>;
+    /**
+     * Count items matching a predicate
+     */
+    count(predicate?: (item: T) => boolean): Promise<number>;
+    /**
+     * Find the first item matching a predicate
+     */
+    find(predicate: (item: T) => boolean): Promise<T | null>;
+    /**
+     * Check if any item matches a predicate
+     */
+    some(predicate: (item: T) => boolean): Promise<boolean>;
+    /**
+     * Check if all items match a predicate
+     */
+    every(predicate: (item: T) => boolean): Promise<boolean>;
+}
+/**
+ * Create streaming operations for a file
+ */
+export declare function createStreamingOperations<T>(filePath: string, logger?: Logger): StreamingJsonOperations<T>;
+//# sourceMappingURL=streaming.d.ts.map

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

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

package/dist/storage/streaming.js

@@ -0,0 +1,245 @@
+/**
+ * Streaming JSON support for BillClaw
+ *
+ * Provides streaming JSON parsing and generation for large datasets.
+ * This keeps memory usage constant regardless of file size.
+ *
+ * Use cases:
+ * - Reading large transaction files without loading entire file
+ * - Writing large datasets incrementally
+ * - Processing transactions one at a time
+ */
+import { createReadStream, createWriteStream } from "node:fs";
+import { createInterface } from "node:readline";
+/**
+ * Write items to a JSON file incrementally
+ *
+ * @param filePath - Path to output file
+ * @param items - Async iterable of items to write
+ * @param options - Write options
+ */
+export async function writeStreamingJson(filePath, items, options = {}) {
+    const { batchSize = 100, logger } = options;
+    return new Promise((resolve, reject) => {
+        const writeStream = createWriteStream(filePath);
+        let first = true;
+        let count = 0;
+        writeStream.write("[");
+        (async () => {
+            try {
+                for await (const item of items) {
+                    if (!first) {
+                        writeStream.write(",");
+                    }
+                    writeStream.write(JSON.stringify(item));
+                    first = false;
+                    count++;
+                    if (count % batchSize === 0) {
+                        logger?.debug?.(`Written ${count} items to ${filePath}`);
+                    }
+                }
+                writeStream.write("]");
+                writeStream.end();
+                logger?.info?.(`Finished writing ${count} items to ${filePath}`);
+            }
+            catch (error) {
+                writeStream.destroy();
+                reject(error);
+            }
+        })();
+        writeStream.on("finish", resolve);
+        writeStream.on("error", reject);
+    });
+}
+/**
+ * Read items from a JSON file incrementally
+ *
+ * @param filePath - Path to input file
+ * @param options - Read options
+ * @returns Async iterable of items
+ */
+export async function* readStreamingJson(filePath, options = {}) {
+    const { filter, transform, logger } = options;
+    let count = 0;
+    const fileStream = createReadStream(filePath);
+    const rl = createInterface({
+        input: fileStream,
+        crlfDelay: Infinity,
+    });
+    let buffer = "";
+    for await (const line of rl) {
+        buffer += line;
+        // Find complete JSON objects
+        let braceCount = 0;
+        let objStart = -1;
+        let inString = false;
+        let escapeNext = false;
+        for (let i = 0; i < buffer.length; i++) {
+            const char = buffer[i];
+            if (escapeNext) {
+                escapeNext = false;
+                continue;
+            }
+            if (char === "\\") {
+                escapeNext = true;
+                continue;
+            }
+            if (char === '"') {
+                inString = !inString;
+                continue;
+            }
+            if (inString) {
+                continue;
+            }
+            if (char === "{") {
+                if (objStart === -1) {
+                    objStart = i;
+                }
+                braceCount++;
+            }
+            else if (char === "}") {
+                braceCount--;
+                if (braceCount === 0 && objStart !== -1) {
+                    const jsonStr = buffer.substring(objStart, i + 1);
+                    buffer = buffer.substring(i + 1).trim();
+                    try {
+                        let item = JSON.parse(jsonStr);
+                        if (transform) {
+                            item = transform(item);
+                        }
+                        if (!filter || filter(item)) {
+                            count++;
+                            yield item;
+                        }
+                    }
+                    catch (error) {
+                        logger?.error?.("Failed to parse JSON item", error);
+                    }
+                    i = -1; // Reset position
+                    objStart = -1;
+                }
+            }
+        }
+    }
+    logger?.debug?.(`Read ${count} items from ${filePath}`);
+}
+/**
+ * Stream transactions from a file
+ *
+ * @param filePath - Path to transaction file
+ * @param options - Stream options
+ * @returns Async iterable of transactions
+ */
+export async function* streamTransactions(filePath, options) {
+    yield* readStreamingJson(filePath, options);
+}
+/**
+ * Write transactions to a file incrementally
+ *
+ * @param filePath - Path to output file
+ * @param transactions - Async iterable of transactions
+ * @param options - Write options
+ */
+export async function writeTransactionsStreaming(filePath, transactions, options) {
+    await writeStreamingJson(filePath, transactions, options);
+}
+/**
+ * Map/reduce operations on streaming JSON
+ */
+export class StreamingJsonOperations {
+    filePath;
+    logger;
+    constructor(filePath, logger) {
+        this.filePath = filePath;
+        this.logger = logger;
+    }
+    /**
+     * Map each item through a transformation function
+     */
+    async map(fn) {
+        const results = [];
+        for await (const item of readStreamingJson(this.filePath, {
+            logger: this.logger,
+        })) {
+            results.push(fn(item));
+        }
+        return results;
+    }
+    /**
+     * Filter items
+     */
+    async filter(fn) {
+        const results = [];
+        for await (const item of readStreamingJson(this.filePath, {
+            filter: fn,
+            logger: this.logger,
+        })) {
+            results.push(item);
+        }
+        return results;
+    }
+    /**
+     * Reduce items to a single value
+     */
+    async reduce(fn, initial) {
+        let acc = initial;
+        for await (const item of readStreamingJson(this.filePath, {
+            logger: this.logger,
+        })) {
+            acc = fn(acc, item);
+        }
+        return acc;
+    }
+    /**
+     * Count items matching a predicate
+     */
+    async count(predicate) {
+        let count = 0;
+        for await (const _item of readStreamingJson(this.filePath, {
+            filter: predicate,
+            logger: this.logger,
+        })) {
+            count++;
+        }
+        return count;
+    }
+    /**
+     * Find the first item matching a predicate
+     */
+    async find(predicate) {
+        for await (const item of readStreamingJson(this.filePath, {
+            logger: this.logger,
+        })) {
+            if (predicate(item)) {
+                return item;
+            }
+        }
+        return null;
+    }
+    /**
+     * Check if any item matches a predicate
+     */
+    async some(predicate) {
+        return (await this.find(predicate)) !== null;
+    }
+    /**
+     * Check if all items match a predicate
+     */
+    async every(predicate) {
+        for await (const item of readStreamingJson(this.filePath, {
+            logger: this.logger,
+        })) {
+            if (!predicate(item)) {
+                return false;
+            }
+        }
+        return true;
+    }
+}
+/**
+ * Create streaming operations for a file
+ */
+export function createStreamingOperations(filePath, logger) {
+    return new StreamingJsonOperations(filePath, logger);
+}
+//# sourceMappingURL=streaming.js.map

package/dist/storage/streaming.js.map

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

package/dist/storage/transaction-storage.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Local file storage utilities for BillClaw data
+ */
+import type { StorageConfig } from "../models/config.js";
+export interface Transaction {
+    transactionId: string;
+    accountId: string;
+    date: string;
+    amount: number;
+    currency: string;
+    category: string[];
+    merchantName: string;
+    paymentChannel: string;
+    pending: boolean;
+    plaidTransactionId: string;
+    createdAt: string;
+}
+/**
+ * Sync state for idempotency
+ */
+export interface SyncState {
+    syncId: string;
+    accountId: string;
+    startedAt: string;
+    completedAt?: string;
+    status: "running" | "completed" | "failed";
+    transactionsAdded: number;
+    transactionsUpdated: number;
+    cursor: string;
+    error?: string;
+    requiresReauth?: boolean;
+}
+/**
+ * Account registry entry
+ */
+export interface AccountRegistry {
+    id: string;
+    type: string;
+    name: string;
+    createdAt: string;
+    lastSync?: string;
+}
+/**
+ * Global cursor for incremental sync
+ */
+export interface GlobalCursor {
+    lastSyncTime: string;
+}
+/**
+ * Get the base storage directory
+ */
+export declare function getStorageDir(config?: StorageConfig): Promise<string>;
+/**
+ * Initialize storage directory structure
+ */
+export declare function initializeStorage(config?: StorageConfig): Promise<void>;
+/**
+ * Read account registry
+ */
+export declare function readAccountRegistry(config?: StorageConfig): Promise<AccountRegistry[]>;
+/**
+ * Write account registry
+ */
+export declare function writeAccountRegistry(accounts: AccountRegistry[], config?: StorageConfig): Promise<void>;
+/**
+ * Read transactions for an account and month
+ */
+export declare function readTransactions(accountId: string, year: number, month: number, config?: StorageConfig): Promise<Transaction[]>;
+/**
+ * Write transactions for an account and month
+ * Uses atomic write (temp file + rename) for safety
+ */
+export declare function writeTransactions(accountId: string, year: number, month: number, transactions: Transaction[], config?: StorageConfig): Promise<void>;
+/**
+ * Append transactions to existing month file (with deduplication)
+ */
+export declare function appendTransactions(accountId: string, year: number, month: number, newTransactions: Transaction[], config?: StorageConfig): Promise<{
+    added: number;
+    updated: number;
+}>;
+/**
+ * Read sync state for an account
+ */
+export declare function readSyncStates(accountId: string, config?: StorageConfig): Promise<SyncState[]>;
+/**
+ * Write sync state
+ */
+export declare function writeSyncState(state: SyncState, config?: StorageConfig): Promise<void>;
+/**
+ * Read global cursor
+ */
+export declare function readGlobalCursor(config?: StorageConfig): Promise<GlobalCursor | null>;
+/**
+ * Write global cursor
+ */
+export declare function writeGlobalCursor(cursor: GlobalCursor, config?: StorageConfig): Promise<void>;
+/**
+ * Deduplicate transactions within a time window (24 hours)
+ */
+export declare function deduplicateTransactions(transactions: Transaction[], windowHours?: number): Transaction[];
+//# sourceMappingURL=transaction-storage.d.ts.map

package/dist/storage/transaction-storage.d.ts.map

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