optimal-cli 0.1.0

package/dist/lib/social/scraper.js

@@ -0,0 +1,361 @@
+/**
+ * Meta Ad Library Scraper
+ *
+ * Ported from Python: ~/projects/meta-ad-scraper/scripts/meta_ad_scraper_v2.py
+ *
+ * Scrapes Facebook Ad Library for competitor ad intelligence.
+ * Uses Playwright headless Chromium with anti-detection measures.
+ * Splits ads by Library ID pattern, extracts metadata via regex.
+ *
+ * Functions:
+ *   buildUrl()              — construct Facebook Ad Library URL for a company
+ *   scrollAndLoad()         — auto-scroll page to load all ads (max 15 scrolls)
+ *   extractAds()            — two-stage extraction: DOM containers, then text split fallback
+ *   parseAdText()           — regex extraction of ad metadata from text blocks
+ *   extractLandingUrls()    — find landing page URLs from DOM links
+ *   scrapeCompany()         — orchestrate single company scrape
+ *   scrapeCompanies()       — batch-scrape multiple companies with configurable parallelism
+ *   formatCsv()             — convert ad records to CSV string
+ */
+import { chromium } from 'playwright';
+import { writeFileSync } from 'node:fs';
+// ── CSV Column Order ────────────────────────────────────────────────
+const CSV_FIELDS = [
+    'company_searched',
+    'ad_id',
+    'page_name',
+    'ad_text',
+    'status',
+    'start_date',
+    'impressions',
+    'spend',
+    'media_type',
+    'platforms',
+    'landing_page_url',
+    'full_text_snippet',
+];
+// ── URL Builder ─────────────────────────────────────────────────────
+export function buildUrl(companyName) {
+    const base = 'https://www.facebook.com/ads/library/';
+    const params = `?active_status=active` +
+        `&ad_type=all` +
+        `&country=US` +
+        `&is_targeted_country=false` +
+        `&media_type=all` +
+        `&sort_data[mode]=total_impressions` +
+        `&sort_data[direction]=desc` +
+        `&q=${encodeURIComponent(companyName)}`;
+    return base + params;
+}
+// ── Scroll & Load ───────────────────────────────────────────────────
+export async function scrollAndLoad(page, maxScrolls = 15) {
+    let prevHeight = 0;
+    for (let i = 0; i < maxScrolls; i++) {
+        await page.evaluate(() => window.scrollTo(0, document.body.scrollHeight));
+        await page.waitForTimeout(2000);
+        const currHeight = await page.evaluate(() => document.body.scrollHeight);
+        if (currHeight === prevHeight && i > 1)
+            break;
+        prevHeight = currHeight;
+    }
+}
+// ── Parse Ad Text ───────────────────────────────────────────────────
+export function parseAdText(text, companyName) {
+    if (!text || text.length < 20)
+        return null;
+    const ad = { company_searched: companyName };
+    // Library ID
+    const idMatch = text.match(/Library ID:\s*(\d+)/);
+    if (idMatch) {
+        ad.ad_id = idMatch[1];
+    }
+    else {
+        return null; // Skip blocks without a Library ID
+    }
+    // Start date
+    const dateMatch = text.match(/Started running on\s+(\w+ \d+,?\s*\d*)/);
+    if (dateMatch) {
+        ad.start_date = dateMatch[1].trim();
+    }
+    else {
+        ad.start_date = '';
+    }
+    // Status (Active/Inactive)
+    if (text.includes('Active')) {
+        ad.status = 'Active';
+    }
+    else if (text.includes('Inactive')) {
+        ad.status = 'Inactive';
+    }
+    else {
+        ad.status = 'Unknown';
+    }
+    // Page name - look for "Sponsored" text preceded by the page name
+    const sponsorMatch = text.match(/(?:^|\n)([^\n]+)\nSponsored/);
+    if (sponsorMatch) {
+        ad.page_name = sponsorMatch[1].trim();
+    }
+    else {
+        ad.page_name = '';
+    }
+    // Ad creative text - text after "Sponsored" and before common end markers
+    const creativeMatch = text.match(/Sponsored\n(.+?)(?:\n(?:Learn More|Sign Up|Shop Now|Get Offer|Download|Apply Now|Book Now|Contact Us|Send Message|Watch More|See Menu|Get Quote|Subscribe|Get Showtimes)|\Z)/s);
+    if (creativeMatch) {
+        ad.ad_text = creativeMatch[1].trim().slice(0, 500);
+    }
+    else {
+        ad.ad_text = '';
+    }
+    // Impressions
+    const impMatch = text.match(/(?:impressions?)\s*[:\s]*([\d,.]+\s*[-\u2013]\s*[\d,.]+)/i);
+    if (impMatch) {
+        ad.impressions = impMatch[1];
+    }
+    else {
+        ad.impressions = '';
+    }
+    // Spend
+    const spendMatch = text.match(/(?:spend|spent)\s*[:\s]*\$?([\d,.]+\s*[-\u2013]\s*\$?[\d,.]+)/i);
+    if (spendMatch) {
+        ad.spend = spendMatch[1];
+    }
+    else {
+        ad.spend = '';
+    }
+    // Media type
+    const textLower = text.toLowerCase();
+    if (['video', '0:00', 'play'].some((kw) => textLower.includes(kw))) {
+        ad.media_type = 'video';
+    }
+    else if (textLower.includes('carousel') ||
+        textLower.includes('multiple versions')) {
+        ad.media_type = 'carousel/multiple';
+    }
+    else {
+        ad.media_type = 'image';
+    }
+    // Platforms
+    const platformNames = ['Facebook', 'Instagram', 'Messenger', 'Audience Network'];
+    const platforms = platformNames.filter((p) => textLower.includes(p.toLowerCase()));
+    ad.platforms = platforms.join(', ');
+    // Landing page URL (not available from text, would need DOM links)
+    ad.landing_page_url = '';
+    // Full text snippet for reference
+    ad.full_text_snippet = text.slice(0, 500);
+    return ad;
+}
+// ── Extract Ads ─────────────────────────────────────────────────────
+export async function extractAds(page, companyName, maxScrolls = 15) {
+    const ads = [];
+    // Wait for content
+    try {
+        await page.waitForLoadState('networkidle', { timeout: 15000 });
+    }
+    catch {
+        // Timeout is acceptable — continue with what loaded
+    }
+    await page.waitForTimeout(3000);
+    // Check for no results
+    const pageText = await page.evaluate(() => document.body.innerText);
+    if (!pageText ||
+        pageText.toLowerCase().includes('no results') ||
+        pageText.toLowerCase().includes('no ads match')) {
+        console.log(`  [INFO] No ads found for ${companyName}`);
+        return ads;
+    }
+    // Scroll to load all ads
+    await scrollAndLoad(page, maxScrolls);
+    // Also try to extract structured data from the DOM
+    const domAds = await page.evaluate(() => {
+        const results = [];
+        // Find all Library ID occurrences via DOM containers
+        const allElements = document.querySelectorAll('div');
+        const adContainers = [];
+        allElements.forEach((el) => {
+            const text = el.innerText || '';
+            // An ad container typically has EXACTLY ONE Library ID
+            const idMatches = text.match(/Library ID:\s*\d+/g);
+            if (idMatches && idMatches.length === 1) {
+                // Check it's not too small (just a label) or too large (parent of multiple ads)
+                const textLen = text.length;
+                if (textLen > 50 && textLen < 5000) {
+                    adContainers.push({
+                        text,
+                        textLen,
+                        tag: el.tagName,
+                    });
+                }
+            }
+        });
+        // Deduplicate - remove containers that are subsets of other containers
+        // Sort by text length (smallest first - these are the most specific)
+        adContainers.sort((a, b) => a.textLen - b.textLen);
+        const seen = new Set();
+        adContainers.forEach((container) => {
+            const idMatch = container.text.match(/Library ID:\s*(\d+)/);
+            if (idMatch && !seen.has(idMatch[1])) {
+                seen.add(idMatch[1]);
+                results.push(container);
+            }
+        });
+        return results;
+    });
+    if (domAds && domAds.length > 0) {
+        console.log(`  [DOM] Found ${domAds.length} individual ad containers`);
+        for (const raw of domAds) {
+            const ad = parseAdText(raw.text, companyName);
+            if (ad)
+                ads.push(ad);
+        }
+    }
+    else {
+        // Fallback: split page text by "Library ID:" pattern
+        console.log(`  [TEXT] Falling back to text-based splitting`);
+        const fullText = await page.evaluate(() => document.body.innerText);
+        const sections = fullText.split(/(?=Library ID:\s*\d+)/);
+        for (const section of sections) {
+            const trimmed = section.trim();
+            if (!trimmed || trimmed.length < 30)
+                continue;
+            const ad = parseAdText(trimmed, companyName);
+            if (ad)
+                ads.push(ad);
+        }
+    }
+    return ads;
+}
+// ── Extract Landing URLs ────────────────────────────────────────────
+export async function extractLandingUrls(page, adIds) {
+    return page.evaluate((ids) => {
+        const result = {};
+        const links = document.querySelectorAll('a[href*="l.facebook.com"]');
+        links.forEach((link) => {
+            const href = link.href || '';
+            const parent = link.closest('div');
+            if (parent) {
+                const text = parent.innerText || '';
+                for (const id of ids) {
+                    if (text.includes(id) && !result[id]) {
+                        result[id] = href;
+                    }
+                }
+            }
+        });
+        return result;
+    }, adIds);
+}
+// ── Scrape Single Company ───────────────────────────────────────────
+export async function scrapeCompany(page, companyName, maxScrolls = 15) {
+    const url = buildUrl(companyName);
+    console.log(`\n${'='.repeat(60)}`);
+    console.log(`Scraping: ${companyName}`);
+    console.log(`URL: ${url}`);
+    console.log(`${'='.repeat(60)}`);
+    try {
+        await page.goto(url, { timeout: 30000, waitUntil: 'domcontentloaded' });
+    }
+    catch {
+        console.log(`  [ERROR] Page load timeout for ${companyName}`);
+        return [];
+    }
+    const ads = await extractAds(page, companyName, maxScrolls);
+    // Try to get landing URLs
+    if (ads.length > 0) {
+        const adIds = ads.map((a) => a.ad_id).filter(Boolean);
+        if (adIds.length > 0) {
+            const urls = await extractLandingUrls(page, adIds);
+            for (const ad of ads) {
+                if (ad.ad_id in urls) {
+                    ad.landing_page_url = urls[ad.ad_id];
+                }
+            }
+        }
+    }
+    console.log(`  [DONE] Extracted ${ads.length} individual ads for ${companyName}`);
+    return ads;
+}
+// ── Batch Scraper ───────────────────────────────────────────────────
+/**
+ * Scrape multiple companies in batches.
+ * Default: 6 companies per batch, 3 parallel batches (as documented in memory).
+ */
+export async function scrapeCompanies(opts) {
+    const { companies, outputPath, batchSize = 6, maxScrolls = 15, companyDelay = 4000, headless = true, } = opts;
+    console.log(`Starting Meta Ad Library scraper for ${companies.length} companies`);
+    if (outputPath)
+        console.log(`Output: ${outputPath}`);
+    const allAds = [];
+    let companiesScraped = 0;
+    // Split into batches
+    const batches = [];
+    for (let i = 0; i < companies.length; i += batchSize) {
+        batches.push(companies.slice(i, i + batchSize));
+    }
+    console.log(`Processing ${batches.length} batch(es) of up to ${batchSize} companies each`);
+    let browser = null;
+    try {
+        browser = await chromium.launch({
+            headless,
+            args: [
+                '--no-sandbox',
+                '--disable-setuid-sandbox',
+                '--disable-dev-shm-usage',
+                '--disable-blink-features=AutomationControlled',
+            ],
+        });
+        for (let bi = 0; bi < batches.length; bi++) {
+            const batch = batches[bi];
+            console.log(`\nBatch ${bi + 1}/${batches.length}: ${batch.length} companies`);
+            const context = await browser.newContext({
+                viewport: { width: 1920, height: 1080 },
+                userAgent: 'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36',
+            });
+            const page = await context.newPage();
+            for (let ci = 0; ci < batch.length; ci++) {
+                const company = batch[ci];
+                if (ci > 0) {
+                    console.log(`\n  [WAIT] Waiting ${companyDelay / 1000}s before next company...`);
+                    await page.waitForTimeout(companyDelay);
+                }
+                const ads = await scrapeCompany(page, company, maxScrolls);
+                allAds.push(...ads);
+                companiesScraped++;
+            }
+            await context.close();
+        }
+    }
+    finally {
+        if (browser)
+            await browser.close();
+    }
+    // Write CSV output if path specified
+    if (outputPath) {
+        const csv = formatCsv(allAds);
+        writeFileSync(outputPath, csv, 'utf-8');
+        console.log(`\nSaved ${allAds.length} ads to ${outputPath}`);
+    }
+    console.log(`\nBatch complete: ${allAds.length} total ads from ${companiesScraped} companies`);
+    return {
+        ads: allAds,
+        totalCompanies: companies.length,
+        companiesScraped,
+        outputPath,
+    };
+}
+// ── CSV Formatter ───────────────────────────────────────────────────
+/** Escape a value for CSV (double-quote wrapping, escape inner quotes) */
+function escapeCsvField(value) {
+    if (value.includes(',') ||
+        value.includes('"') ||
+        value.includes('\n') ||
+        value.includes('\r')) {
+        return `"${value.replace(/"/g, '""')}"`;
+    }
+    return value;
+}
+/** Convert ad records to CSV string */
+export function formatCsv(ads) {
+    const header = CSV_FIELDS.join(',');
+    const rows = ads.map((ad) => CSV_FIELDS.map((field) => escapeCsvField(ad[field] ?? '')).join(','));
+    return [header, ...rows].join('\n') + '\n';
+}

package/dist/lib/supabase.d.ts

@@ -0,0 +1,4 @@
+import { SupabaseClient } from '@supabase/supabase-js';
+import 'dotenv/config';
+export type SupabaseInstance = 'optimal' | 'returnpro';
+export declare function getSupabase(instance: SupabaseInstance): SupabaseClient;

package/dist/lib/supabase.js

@@ -0,0 +1,20 @@
+import { createClient } from '@supabase/supabase-js';
+import 'dotenv/config';
+const configs = {
+    optimal: { urlEnv: 'OPTIMAL_SUPABASE_URL', keyEnv: 'OPTIMAL_SUPABASE_SERVICE_KEY' },
+    returnpro: { urlEnv: 'RETURNPRO_SUPABASE_URL', keyEnv: 'RETURNPRO_SUPABASE_SERVICE_KEY' },
+};
+const clients = new Map();
+export function getSupabase(instance) {
+    const existing = clients.get(instance);
+    if (existing)
+        return existing;
+    const config = configs[instance];
+    const url = process.env[config.urlEnv];
+    const key = process.env[config.keyEnv];
+    if (!url || !key)
+        throw new Error(`Missing env vars: ${config.urlEnv}, ${config.keyEnv}`);
+    const client = createClient(url, key);
+    clients.set(instance, client);
+    return client;
+}

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>;