optimal-cli 1.0.0 → 1.0.1

package/dist/lib/transactions/delete-batch.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Transaction & Staging Batch Deletion — Safe Preview and Execute
+ *
+ * Provides safe batch deletion of transactions (OptimalOS) and staging
+ * financials (ReturnPro) with preview mode defaulting to dryRun=true.
+ *
+ * Tables:
+ *   - transactions       → OptimalOS Supabase (getSupabase('optimal'))
+ *   - stg_financials_raw → ReturnPro Supabase  (getSupabase('returnpro'))
+ *
+ * Columns:
+ *   transactions:       id, user_id, date, description, amount, category, source, stamp_match_type, created_at
+ *   stg_financials_raw: id, account_code, account_name, amount (TEXT), month (YYYY-MM), source, user_id, created_at
+ */
+import 'dotenv/config';
+export interface DeleteBatchOptions {
+    table: 'transactions' | 'stg_financials_raw';
+    userId?: string;
+    filters: {
+        dateFrom?: string;
+        dateTo?: string;
+        source?: string;
+        category?: string;
+        accountCode?: string;
+        month?: string;
+    };
+    dryRun?: boolean;
+}
+export interface DeleteBatchResult {
+    table: string;
+    deletedCount: number;
+    dryRun: boolean;
+    filters: Record<string, string>;
+}
+export interface PreviewResult {
+    table: string;
+    matchCount: number;
+    sample: Array<Record<string, unknown>>;
+    groupedCounts: Record<string, number>;
+}
+/**
+ * Preview what would be deleted without touching any data.
+ *
+ * Returns:
+ *   - matchCount: total rows matching the filters
+ *   - sample: first 10 matching rows
+ *   - groupedCounts: row counts grouped by `source` (transactions) or `account_code` (staging)
+ */
+export declare function previewBatch(opts: DeleteBatchOptions): Promise<PreviewResult>;
+/**
+ * Delete matching rows in batch — or preview them without deleting (dryRun=true).
+ *
+ * Safety: dryRun defaults to TRUE. Caller must explicitly pass dryRun=false
+ * to execute an actual deletion.
+ *
+ * In dryRun mode: counts matching rows and returns deletedCount=0.
+ * In execute mode: issues a Supabase DELETE with the same filters and returns
+ *                  the number of rows deleted.
+ */
+export declare function deleteBatch(opts: DeleteBatchOptions): Promise<DeleteBatchResult>;

package/dist/lib/transactions/delete-batch.js

@@ -0,0 +1,203 @@
+/**
+ * Transaction & Staging Batch Deletion — Safe Preview and Execute
+ *
+ * Provides safe batch deletion of transactions (OptimalOS) and staging
+ * financials (ReturnPro) with preview mode defaulting to dryRun=true.
+ *
+ * Tables:
+ *   - transactions       → OptimalOS Supabase (getSupabase('optimal'))
+ *   - stg_financials_raw → ReturnPro Supabase  (getSupabase('returnpro'))
+ *
+ * Columns:
+ *   transactions:       id, user_id, date, description, amount, category, source, stamp_match_type, created_at
+ *   stg_financials_raw: id, account_code, account_name, amount (TEXT), month (YYYY-MM), source, user_id, created_at
+ */
+import 'dotenv/config';
+import { getSupabase } from '../supabase.js';
+// =============================================================================
+// INTERNAL HELPERS
+// =============================================================================
+/**
+ * Return the correct Supabase client for the given table.
+ */
+function getClientForTable(table) {
+    return table === 'transactions'
+        ? getSupabase('optimal')
+        : getSupabase('returnpro');
+}
+/**
+ * Apply the shared set of filters to a Supabase query builder.
+ * Works for both SELECT and DELETE queries because both are PostgREST filters.
+ *
+ * For `stg_financials_raw`:
+ *   - dateFrom / dateTo are ignored (use `month` instead)
+ *   - month is applied as an eq filter on the `month` column
+ *   - accountCode is applied as an eq filter on `account_code`
+ *
+ * For `transactions`:
+ *   - dateFrom / dateTo are applied as gte/lte on `date`
+ *   - source is applied as an eq filter on `source`
+ *   - category is applied as an eq filter on `category`
+ *   - userId is applied as an eq filter on `user_id`
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function applyFilters(query, table, userId, filters) {
+    let q = query;
+    if (table === 'transactions') {
+        if (userId)
+            q = q.eq('user_id', userId);
+        if (filters.dateFrom)
+            q = q.gte('date', filters.dateFrom);
+        if (filters.dateTo)
+            q = q.lte('date', filters.dateTo);
+        if (filters.source)
+            q = q.eq('source', filters.source);
+        if (filters.category)
+            q = q.eq('category', filters.category);
+    }
+    else {
+        // stg_financials_raw
+        if (userId)
+            q = q.eq('user_id', userId);
+        if (filters.month)
+            q = q.eq('month', filters.month);
+        if (filters.accountCode)
+            q = q.eq('account_code', filters.accountCode);
+        if (filters.source)
+            q = q.eq('source', filters.source);
+    }
+    return q;
+}
+/**
+ * Serialize active filters for the result record (human-readable).
+ */
+function serializeFilters(table, userId, filters) {
+    const out = {};
+    if (userId)
+        out.user_id = userId;
+    if (table === 'transactions') {
+        if (filters.dateFrom)
+            out.dateFrom = filters.dateFrom;
+        if (filters.dateTo)
+            out.dateTo = filters.dateTo;
+        if (filters.source)
+            out.source = filters.source;
+        if (filters.category)
+            out.category = filters.category;
+    }
+    else {
+        if (filters.month)
+            out.month = filters.month;
+        if (filters.accountCode)
+            out.accountCode = filters.accountCode;
+        if (filters.source)
+            out.source = filters.source;
+    }
+    return out;
+}
+// =============================================================================
+// PUBLIC FUNCTIONS
+// =============================================================================
+/**
+ * Preview what would be deleted without touching any data.
+ *
+ * Returns:
+ *   - matchCount: total rows matching the filters
+ *   - sample: first 10 matching rows
+ *   - groupedCounts: row counts grouped by `source` (transactions) or `account_code` (staging)
+ */
+export async function previewBatch(opts) {
+    const { table, userId, filters } = opts;
+    const supabase = getClientForTable(table);
+    // --- Count matching rows ---
+    const countQuery = supabase
+        .from(table)
+        .select('*', { count: 'exact', head: true });
+    const countQueryWithFilters = applyFilters(countQuery, table, userId, filters);
+    const { count, error: countError } = await countQueryWithFilters;
+    if (countError) {
+        throw new Error(`previewBatch count error on ${table}: ${countError.message}`);
+    }
+    const matchCount = count ?? 0;
+    // --- Fetch sample rows (first 10) ---
+    const sampleQuery = supabase
+        .from(table)
+        .select('*')
+        .limit(10);
+    const sampleQueryWithFilters = applyFilters(sampleQuery, table, userId, filters);
+    const { data: sampleData, error: sampleError } = await sampleQueryWithFilters;
+    if (sampleError) {
+        throw new Error(`previewBatch sample error on ${table}: ${sampleError.message}`);
+    }
+    const sample = (sampleData ?? []);
+    // --- Grouped counts ---
+    // Group by `source` for transactions, `account_code` for staging
+    const groupCol = table === 'transactions' ? 'source' : 'account_code';
+    const groupQuery = supabase
+        .from(table)
+        .select(groupCol);
+    const groupQueryWithFilters = applyFilters(groupQuery, table, userId, filters);
+    const { data: groupData, error: groupError } = await groupQueryWithFilters;
+    if (groupError) {
+        throw new Error(`previewBatch group error on ${table}: ${groupError.message}`);
+    }
+    const groupedCounts = {};
+    for (const row of (groupData ?? [])) {
+        const key = row[groupCol] ?? '(unknown)';
+        groupedCounts[key] = (groupedCounts[key] ?? 0) + 1;
+    }
+    return {
+        table,
+        matchCount,
+        sample,
+        groupedCounts,
+    };
+}
+/**
+ * Delete matching rows in batch — or preview them without deleting (dryRun=true).
+ *
+ * Safety: dryRun defaults to TRUE. Caller must explicitly pass dryRun=false
+ * to execute an actual deletion.
+ *
+ * In dryRun mode: counts matching rows and returns deletedCount=0.
+ * In execute mode: issues a Supabase DELETE with the same filters and returns
+ *                  the number of rows deleted.
+ */
+export async function deleteBatch(opts) {
+    const { table, userId, filters } = opts;
+    const dryRun = opts.dryRun ?? true; // safe by default
+    const supabase = getClientForTable(table);
+    const serializedFilters = serializeFilters(table, userId, filters);
+    if (dryRun) {
+        // Count matching rows without deleting
+        const countQuery = supabase
+            .from(table)
+            .select('*', { count: 'exact', head: true });
+        const countQueryWithFilters = applyFilters(countQuery, table, userId, filters);
+        const { count, error } = await countQueryWithFilters;
+        if (error) {
+            throw new Error(`deleteBatch dry-run count error on ${table}: ${error.message}`);
+        }
+        return {
+            table,
+            deletedCount: 0,
+            dryRun: true,
+            filters: serializedFilters,
+        };
+    }
+    // Execute deletion
+    const deleteQuery = supabase
+        .from(table)
+        .delete({ count: 'exact' });
+    const deleteQueryWithFilters = applyFilters(deleteQuery, table, userId, filters);
+    const { count, error } = await deleteQueryWithFilters;
+    if (error) {
+        throw new Error(`deleteBatch execute error on ${table}: ${error.message}`);
+    }
+    return {
+        table,
+        deletedCount: count ?? 0,
+        dryRun: false,
+        filters: serializedFilters,
+    };
+}

package/dist/lib/transactions/ingest.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Transaction Ingestion — CSV Parsing & Deduplication
+ *
+ * Ported from OptimalOS:
+ *   - /home/optimal/optimalos/app/api/csv/ingest/route.ts
+ *   - /home/optimal/optimalos/lib/csv/upload.ts
+ *   - /home/optimal/optimalos/lib/stamp-engine/normalizers/
+ *   - /home/optimal/optimalos/lib/stamp-engine/format-detector.ts
+ *
+ * Reads a CSV file from disk, auto-detects bank format, parses into
+ * normalized transactions, deduplicates against existing rows in Supabase,
+ * and batch-inserts new records into the `transactions` table.
+ */
+export interface RawTransaction {
+    date: string;
+    description: string;
+    amount: number;
+    originalCategory?: string;
+    transactionType?: string;
+    postDate?: string;
+    balance?: number;
+    extendedDetails?: string;
+    merchantAddress?: string;
+}
+export type BankFormat = 'chase_checking' | 'chase_credit' | 'discover' | 'amex' | 'generic' | 'unknown';
+export interface IngestResult {
+    inserted: number;
+    skipped: number;
+    failed: number;
+    errors: string[];
+    format: BankFormat;
+}
+/**
+ * Ingest transactions from a CSV file.
+ *
+ * 1. Read & detect format
+ * 2. Parse into normalized transactions
+ * 3. Deduplicate against existing rows (by hash)
+ * 4. Batch-insert new rows into `transactions`
+ *
+ * @returns count of inserted, skipped (duplicate), and failed rows
+ */
+export declare function ingestTransactions(filePath: string, userId: string): Promise<IngestResult>;