@firela/billclaw-core 0.1.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 fire-la
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,109 @@
+# @firela/billclaw-core
+
+Framework-agnostic core business logic for BillClaw financial data import.
+
+## Overview
+
+This package contains all core functionality with zero dependencies on any AI framework (OpenClaw, OpenHands, etc.). It provides:
+
+- **Data Models**: TypeScript types and Zod schemas for financial data
+- **Storage**: Transaction storage with JSON/CSV support, file locking, and streaming
+- **Sync**: Plaid and Gmail integration for fetching transactions
+- **Exporters**: Beancount and Ledger format exporters
+- **Security**: Platform keychain integration and audit logging
+- **Performance**: TTL-based memory cache and query indexes
+- **Runtime Abstractions**: Logger, ConfigProvider, and EventEmitter interfaces
+
+## Installation
+
+```bash
+pnpm add @firela/billclaw-core
+```
+
+## Quick Start
+
+```typescript
+import { Billclaw } from "@firela/billclaw-core";
+import { createRuntimeContext } from "./runtime.js";
+
+// Create a runtime context (framework-specific adapter)
+const runtime = createRuntimeContext();
+
+// Initialize BillClaw
+const billclaw = new Billclaw(runtime);
+
+// Sync transactions from Plaid
+const results = await billclaw.syncPlaid();
+
+// Export to Beancount
+const transactions = await billclaw.getTransactions("all", 2024, 1);
+const beancount = await exportToBeancount(transactions, {
+  accountId: "all",
+  year: 2024,
+  month: 1,
+  commodity: "USD",
+});
+```
+
+## Architecture
+
+### Core Classes
+
+- **`Billclaw`**: Main class for managing financial data operations
+- **`TransactionStorage`**: Handles transaction persistence and queries
+- **`MemoryCache`**: TTL-based in-memory caching
+- **`AuditLogger`**: Security event logging
+
+### Data Sources
+
+- **Plaid**: Bank account and credit card transactions via Plaid API
+- **Gmail**: Bill parsing from email using pattern recognition
+- **GoCardless**: European bank accounts via open banking (planned)
+
+### Exporters
+
+- **Beancount**: Plain text accounting format export
+- **Ledger**: Ledger CLI format export
+
+## API Reference
+
+### Billclaw
+
+```typescript
+class Billclaw {
+  constructor(context: RuntimeContext)
+  
+  // Account management
+  getAccounts(): Promise<AccountConfig[]>
+  
+  // Sync operations
+  syncPlaid(accountIds?: string[]): Promise<PlaidSyncResult[]>
+  syncGmail(accountIds?: string[], days?: number): Promise<GmailFetchResult[]>
+  syncDueAccounts(): Promise<any[]>
+  
+  // Transaction queries
+  getTransactions(accountId: string, year: number, month: number): Promise<Transaction[]>
+  
+  // Export operations
+  exportToBeancount(transactions: Transaction[], options: BeancountExportOptions): Promise<string>
+  exportToLedger(transactions: Transaction[], options: LedgerExportOptions): Promise<string>
+}
+```
+
+### Configuration
+
+```typescript
+interface BillclawConfig {
+  accounts: AccountConfig[];
+  webhooks: WebhookConfig[];
+  storage: StorageConfig;
+  sync: SyncConfig;
+  plaid: PlaidConfig;
+  gocardless?: GoCardlessConfig;
+  gmail?: GmailConfig;
+}
+```
+
+## License
+
+MIT

package/dist/billclaw.d.ts

@@ -0,0 +1,76 @@
+/**
+ * BillClaw - Main class for financial data import
+ *
+ * This class provides the primary API for interacting with BillClaw.
+ * It is framework-agnostic and can be used by any adapter (CLI, OpenClaw, etc.).
+ */
+import type { Logger } from "./errors/errors.js";
+import type { RuntimeContext, ConfigProvider } from "./runtime/types.js";
+import type { Transaction, SyncState } from "./storage/transaction-storage.js";
+import type { PlaidSyncResult } from "./sources/plaid/plaid-sync.js";
+import type { GmailFetchResult } from "./sources/gmail/gmail-fetch.js";
+import type { SyncResult } from "./sync/sync-service.js";
+/**
+ * BillClaw - Main class for financial data import
+ */
+export declare class Billclaw {
+    private readonly context;
+    constructor(context: RuntimeContext);
+    /**
+     * Get the logger
+     */
+    get logger(): Logger;
+    /**
+     * Get the config provider
+     */
+    get config(): ConfigProvider;
+    /**
+     * Initialize the storage directory structure
+     */
+    initializeStorage(): Promise<void>;
+    /**
+     * Get all registered accounts
+     */
+    getAccounts(): Promise<any[]>;
+    /**
+     * Get transactions for an account and month
+     */
+    getTransactions(accountId: string, year: number, month: number): Promise<Transaction[]>;
+    /**
+     * Get sync states for an account
+     */
+    getSyncStates(accountId: string): Promise<SyncState[]>;
+    /**
+     * Sync provider interface - implemented by adapters
+     */
+    syncAccount(accountId: string): Promise<SyncResult>;
+    /**
+     * Sync all accounts that are due
+     */
+    syncDueAccounts(): Promise<SyncResult[]>;
+    /**
+     * Sync Plaid accounts
+     */
+    syncPlaid(accountIds?: string[]): Promise<PlaidSyncResult[]>;
+    /**
+     * Sync a single Plaid account
+     */
+    private syncPlaidAccount;
+    /**
+     * Sync Gmail accounts
+     */
+    syncGmail(accountIds?: string[], days?: number): Promise<GmailFetchResult[]>;
+    /**
+     * Sync a single Gmail account
+     */
+    private syncGmailAccount;
+    /**
+     * Export transactions to Beancount format
+     */
+    exportToBeancount(accountId: string, year: number, month: number, options?: Partial<any>): Promise<string>;
+    /**
+     * Export transactions to Ledger format
+     */
+    exportToLedger(accountId: string, year: number, month: number, options?: Partial<any>): Promise<string>;
+}
+//# sourceMappingURL=billclaw.d.ts.map

package/dist/billclaw.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"billclaw.d.ts","sourceRoot":"","sources":["../src/billclaw.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAA;AAChD,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AACxE,OAAO,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,kCAAkC,CAAA;AAC9E,OAAO,KAAK,EACV,eAAe,EAGhB,MAAM,+BAA+B,CAAA;AACtC,OAAO,KAAK,EACV,gBAAgB,EAGjB,MAAM,gCAAgC,CAAA;AACvC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAA;AAsBxD;;GAEG;AACH,qBAAa,QAAQ;IACnB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAgB;gBAE5B,OAAO,EAAE,cAAc;IAInC;;OAEG;IACH,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED;;OAEG;IACH,IAAI,MAAM,IAAI,cAAc,CAE3B;IAID;;OAEG;IACG,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC;IAMxC;;OAEG;IACG,WAAW,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;IAKnC;;OAEG;IACG,eAAe,CACnB,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,WAAW,EAAE,CAAC;IAKzB;;OAEG;IACG,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IAO5D;;OAEG;IACG,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAgCzD;;OAEG;IACG,eAAe,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;IAO9C;;OAEG;IACG,SAAS,CAAC,UAAU,CAAC,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;IAgClE;;OAEG;YACW,gBAAgB;IAe9B;;OAEG;IACG,SAAS,CACb,UAAU,CAAC,EAAE,MAAM,EAAE,EACrB,IAAI,GAAE,MAAW,GAChB,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAyC9B;;OAEG;YACW,gBAAgB;IAe9B;;OAEG;IACG,iBAAiB,CACrB,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,OAAO,CAAC,GAAG,CAAC,GACrB,OAAO,CAAC,MAAM,CAAC;IAWlB;;OAEG;IACG,cAAc,CAClB,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,OAAO,CAAC,GAAG,CAAC,GACrB,OAAO,CAAC,MAAM,CAAC;CAInB"}

package/dist/billclaw.js

@@ -0,0 +1,205 @@
+/**
+ * BillClaw - Main class for financial data import
+ *
+ * This class provides the primary API for interacting with BillClaw.
+ * It is framework-agnostic and can be used by any adapter (CLI, OpenClaw, etc.).
+ */
+// Storage
+import { readTransactions, readSyncStates, initializeStorage, } from "./storage/transaction-storage.js";
+// Sync
+import { syncDueAccounts } from "./sync/sync-service.js";
+// Sources
+import { syncPlaidAccounts } from "./sources/plaid/plaid-sync.js";
+import { fetchGmailBills } from "./sources/gmail/gmail-fetch.js";
+// Exporters
+import { exportStorageToBeancount, exportStorageToLedger, } from "./exporters/index.js";
+/**
+ * BillClaw - Main class for financial data import
+ */
+export class Billclaw {
+    context;
+    constructor(context) {
+        this.context = context;
+    }
+    /**
+     * Get the logger
+     */
+    get logger() {
+        return this.context.logger;
+    }
+    /**
+     * Get the config provider
+     */
+    get config() {
+        return this.context.config;
+    }
+    // ==================== Storage ====================
+    /**
+     * Initialize the storage directory structure
+     */
+    async initializeStorage() {
+        const storageConfig = await this.context.config.getStorageConfig();
+        await initializeStorage(storageConfig);
+        this.logger.info?.("Storage initialized");
+    }
+    /**
+     * Get all registered accounts
+     */
+    async getAccounts() {
+        const config = await this.context.config.getConfig();
+        return config.accounts || [];
+    }
+    /**
+     * Get transactions for an account and month
+     */
+    async getTransactions(accountId, year, month) {
+        const storageConfig = await this.context.config.getStorageConfig();
+        return readTransactions(accountId, year, month, storageConfig);
+    }
+    /**
+     * Get sync states for an account
+     */
+    async getSyncStates(accountId) {
+        const storageConfig = await this.context.config.getStorageConfig();
+        return readSyncStates(accountId, storageConfig);
+    }
+    // ==================== Sync ====================
+    /**
+     * Sync provider interface - implemented by adapters
+     */
+    async syncAccount(accountId) {
+        const config = await this.context.config.getConfig();
+        const account = config.accounts.find((a) => a.id === accountId);
+        if (!account) {
+            return {
+                accountId,
+                success: false,
+                transactionsAdded: 0,
+                transactionsUpdated: 0,
+                errors: [`Account not found: ${accountId}`],
+            };
+        }
+        switch (account.type) {
+            case "plaid":
+                return await this.syncPlaidAccount(account);
+            case "gmail":
+                return await this.syncGmailAccount(account);
+            default:
+                return {
+                    accountId,
+                    success: false,
+                    transactionsAdded: 0,
+                    transactionsUpdated: 0,
+                    errors: [`Unsupported account type: ${account.type}`],
+                };
+        }
+    }
+    /**
+     * Sync all accounts that are due
+     */
+    async syncDueAccounts() {
+        const config = await this.context.config.getConfig();
+        return syncDueAccounts(config.accounts, this, this.logger);
+    }
+    // ==================== Plaid ====================
+    /**
+     * Sync Plaid accounts
+     */
+    async syncPlaid(accountIds) {
+        const config = await this.context.config.getConfig();
+        const storageConfig = await this.context.config.getStorageConfig();
+        const plaidConfig = {
+            clientId: config.plaid.clientId || process.env.PLAID_CLIENT_ID || "",
+            secret: config.plaid.secret || process.env.PLAID_SECRET || "",
+            environment: config.plaid.environment || "sandbox",
+        };
+        const accounts = config.accounts
+            .filter((a) => a.type === "plaid" && a.enabled && a.plaidAccessToken)
+            .filter((a) => !accountIds || accountIds.includes(a.id))
+            .map((a) => ({
+            id: a.id,
+            plaidAccessToken: a.plaidAccessToken,
+        }));
+        if (accounts.length === 0) {
+            this.logger.warn?.("No enabled Plaid accounts found");
+            return [];
+        }
+        return syncPlaidAccounts(accounts, plaidConfig, storageConfig, this.logger, config.webhooks || []);
+    }
+    /**
+     * Sync a single Plaid account
+     */
+    async syncPlaidAccount(account) {
+        const results = await this.syncPlaid([account.id]);
+        const result = results[0];
+        return {
+            accountId: result.accountId,
+            success: result.success,
+            transactionsAdded: result.transactionsAdded,
+            transactionsUpdated: result.transactionsUpdated,
+            errors: result.errors,
+        };
+    }
+    // ==================== Gmail ====================
+    /**
+     * Sync Gmail accounts
+     */
+    async syncGmail(accountIds, days = 30) {
+        const config = await this.context.config.getConfig();
+        const storageConfig = await this.context.config.getStorageConfig();
+        const gmailConfig = config.gmail || {
+            senderWhitelist: [],
+            keywords: ["invoice", "statement", "bill due", "receipt", "payment due"],
+            confidenceThreshold: 0.5,
+            requireAmount: false,
+            requireDate: false,
+        };
+        const accounts = config.accounts
+            .filter((a) => a.type === "gmail" && a.enabled)
+            .filter((a) => !accountIds || accountIds.includes(a.id))
+            .map((a) => ({
+            id: a.id,
+            gmailEmailAddress: a.gmailEmailAddress || "",
+        }));
+        if (accounts.length === 0) {
+            this.logger.warn?.("No enabled Gmail accounts found");
+            return [];
+        }
+        const results = [];
+        for (const account of accounts) {
+            const result = await fetchGmailBills(account, days, gmailConfig, storageConfig, this.logger);
+            results.push(result);
+        }
+        return results;
+    }
+    /**
+     * Sync a single Gmail account
+     */
+    async syncGmailAccount(account) {
+        const results = await this.syncGmail([account.id]);
+        const result = results[0];
+        return {
+            accountId: result.accountId,
+            success: result.success,
+            transactionsAdded: result.transactionsAdded,
+            transactionsUpdated: result.transactionsUpdated,
+            errors: result.errors,
+        };
+    }
+    // ==================== Exporters ====================
+    /**
+     * Export transactions to Beancount format
+     */
+    async exportToBeancount(accountId, year, month, options) {
+        const storageConfig = await this.context.config.getStorageConfig();
+        return exportStorageToBeancount(accountId, year, month, storageConfig, options);
+    }
+    /**
+     * Export transactions to Ledger format
+     */
+    async exportToLedger(accountId, year, month, options) {
+        const storageConfig = await this.context.config.getStorageConfig();
+        return exportStorageToLedger(accountId, year, month, storageConfig, options);
+    }
+}
+//# sourceMappingURL=billclaw.js.map

package/dist/billclaw.js.map

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

package/dist/credentials/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Credential storage for BillClaw
+ *
+ * @packageDocumentation
+ */
+export * from "./store.js";
+export * from "./keychain.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/credentials/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/credentials/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,YAAY,CAAA;AAC1B,cAAc,eAAe,CAAA"}

package/dist/credentials/index.js

@@ -0,0 +1,8 @@
+/**
+ * Credential storage for BillClaw
+ *
+ * @packageDocumentation
+ */
+export * from "./store.js";
+export * from "./keychain.js";
+//# sourceMappingURL=index.js.map

package/dist/credentials/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/credentials/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,YAAY,CAAA;AAC1B,cAAc,eAAe,CAAA"}

package/dist/credentials/keychain.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Platform keychain credential storage for BillClaw
+ *
+ * Uses keytar to securely store sensitive tokens in the platform keychain:
+ * - macOS: Keychain
+ * - Windows: Credential Manager
+ * - Linux: Secret Service API / KWallet
+ *
+ * This provides P0 security for:
+ * - Plaid access tokens
+ * - Gmail refresh tokens
+ * - GoCardless access tokens
+ */
+import type { Logger } from "../errors/errors.js";
+/**
+ * Initialize keytar module
+ * Call this before using keychain functions
+ */
+export declare function initKeytar(): Promise<void>;
+/**
+ * Store a credential in the platform keychain
+ *
+ * @param key - Credential identifier (e.g., "plaid_access_token:account123")
+ * @param value - Sensitive value to store (e.g., access token)
+ * @param logger - Optional logger for audit logging
+ */
+export declare function setCredential(key: string, value: string, logger?: Logger): Promise<void>;
+/**
+ * Retrieve a credential from the platform keychain
+ *
+ * @param key - Credential identifier
+ * @param logger - Optional logger for audit logging
+ * @returns The credential value, or null if not found
+ */
+export declare function getCredential(key: string, logger?: Logger): Promise<string | null>;
+/**
+ * Delete a credential from the platform keychain
+ *
+ * @param key - Credential identifier
+ * @param logger - Optional logger for audit logging
+ * @returns true if the credential was deleted, false if it didn't exist
+ */
+export declare function deleteCredential(key: string, logger?: Logger): Promise<boolean>;
+/**
+ * Check if a credential exists in the keychain
+ *
+ * @param key - Credential identifier
+ * @param logger - Optional logger for audit logging
+ * @returns true if the credential exists
+ */
+export declare function hasCredential(key: string, logger?: Logger): Promise<boolean>;
+/**
+ * List all credential keys for BillClaw
+ *
+ * Note: keytar doesn't provide a direct way to list all keys,
+ * so this returns empty array. Applications should track
+ * their own credential keys separately.
+ *
+ * @returns Empty array (keytar limitation)
+ */
+export declare function listCredentialKeys(): Promise<string[]>;
+/**
+ * Clear all BillClaw credentials from the keychain
+ *
+ * WARNING: This is a destructive operation. Use with caution.
+ *
+ * @param keys - List of credential keys to delete
+ * @param logger - Optional logger for audit logging
+ */
+export declare function clearAllCredentials(keys: string[], logger?: Logger): Promise<void>;
+/**
+ * Keychain utility functions for building credential keys
+ */
+export declare const KeychainKeys: {
+    /**
+     * Build a Plaid access token key
+     */
+    plaidAccessToken(accountId: string): string;
+    /**
+     * Build a Gmail refresh token key
+     */
+    gmailRefreshToken(accountId: string): string;
+    /**
+     * Build a GoCardless access token key
+     */
+    gocardlessAccessToken(accountId: string): string;
+    /**
+     * Build a GoCardless requisition ID key
+     */
+    gocardlessRequisitionId(accountId: string): string;
+};
+//# sourceMappingURL=keychain.d.ts.map

package/dist/credentials/keychain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keychain.d.ts","sourceRoot":"","sources":["../../src/credentials/keychain.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAA;AAKjD;;;GAGG;AACH,wBAAsB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAUhD;AAOD;;;;;;GAMG;AACH,wBAAsB,aAAa,CACjC,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,EACb,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,IAAI,CAAC,CAgBf;AAED;;;;;;GAMG;AACH,wBAAsB,aAAa,CACjC,GAAG,EAAE,MAAM,EACX,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CA0BxB;AAED;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,MAAM,EACX,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,OAAO,CAAC,CAyBlB;AAED;;;;;;GAMG;AACH,wBAAsB,aAAa,CACjC,GAAG,EAAE,MAAM,EACX,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,OAAO,CAAC,CAGlB;AAED;;;;;;;;GAQG;AACH,wBAAsB,kBAAkB,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC,CAI5D;AAED;;;;;;;GAOG;AACH,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,MAAM,EAAE,EACd,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,IAAI,CAAC,CAQf;AAED;;GAEG;AACH,eAAO,MAAM,YAAY;IACvB;;OAEG;gCACyB,MAAM,GAAG,MAAM;IAI3C;;OAEG;iCAC0B,MAAM,GAAG,MAAM;IAI5C;;OAEG;qCAC8B,MAAM,GAAG,MAAM;IAIhD;;OAEG;uCACgC,MAAM,GAAG,MAAM;CAGnD,CAAA"}