optimal-cli 0.1.0

package/dist/lib/returnpro/kpis.d.ts

@@ -0,0 +1,32 @@
+export interface KpiRow {
+    month: string;
+    kpiName: string;
+    kpiBucket: string;
+    programName: string;
+    clientName: string;
+    totalAmount: number;
+}
+export interface ExportKpiOptions {
+    /** YYYY-MM months to export. If omitted, uses the 3 most recent months. */
+    months?: string[];
+    /** Program name substrings to filter by. Case-insensitive partial match. */
+    programs?: string[];
+}
+/**
+ * Export KPI data from ReturnPro, aggregated by program/client/month.
+ *
+ * Calls the `get_kpi_totals_by_program_client` Supabase RPC function
+ * (same as dashboard-returnpro's /api/kpis/by-program-client route).
+ *
+ * @returns Flat array of KpiRow sorted by month, kpiName, clientName, programName.
+ */
+export declare function exportKpis(options?: ExportKpiOptions): Promise<KpiRow[]>;
+/**
+ * Format KPI rows as a compact markdown table.
+ * Amounts shown in compact notation ($1.2M, $890K).
+ */
+export declare function formatKpiTable(rows: KpiRow[]): string;
+/**
+ * Format KPI rows as CSV.
+ */
+export declare function formatKpiCsv(rows: KpiRow[]): string;

package/dist/lib/returnpro/kpis.js

@@ -0,0 +1,192 @@
+import { getSupabase } from '../supabase.js';
+// --- Helpers ---
+const PAGE_SIZE = 1000;
+/**
+ * Fetch distinct months available in stg_financials_raw.
+ * Returns sorted YYYY-MM strings.
+ */
+async function fetchAvailableMonths() {
+    const sb = getSupabase('returnpro');
+    const months = new Set();
+    let from = 0;
+    while (true) {
+        const { data, error } = await sb
+            .from('stg_financials_raw')
+            .select('date')
+            .order('date')
+            .range(from, from + PAGE_SIZE - 1);
+        if (error)
+            throw new Error(`Fetch months failed: ${error.message}`);
+        if (!data || data.length === 0)
+            break;
+        for (const row of data) {
+            if (row.date)
+                months.add(row.date.substring(0, 7));
+        }
+        if (data.length < PAGE_SIZE)
+            break;
+        from += PAGE_SIZE;
+    }
+    return [...months].sort();
+}
+/**
+ * Call the get_kpi_totals_by_program_client RPC function for a single month.
+ * Optionally filter by master_program_id.
+ */
+async function fetchKpisByMonth(month, masterProgramId) {
+    const sb = getSupabase('returnpro');
+    const params = { p_month: month };
+    if (masterProgramId !== undefined) {
+        params.p_master_program_id = masterProgramId;
+    }
+    const { data, error } = await sb.rpc('get_kpi_totals_by_program_client', params);
+    if (error)
+        throw new Error(`RPC get_kpi_totals_by_program_client failed for ${month}: ${error.message}`);
+    return (data ?? []);
+}
+/**
+ * Resolve program name filter to master_program_id(s).
+ * Searches both dim_master_program.master_name (full names like "Bass Pro Shops Liquidation (Finished)")
+ * and dim_program_id.program_name (codes like "BRTON-WM-LIQ") for case-insensitive partial match.
+ */
+async function resolveProgramIds(names) {
+    const sb = getSupabase('returnpro');
+    // Fetch both tables in parallel
+    const [masterRes, programRes] = await Promise.all([
+        sb.from('dim_master_program').select('master_program_id,master_name').order('master_name'),
+        sb.from('dim_program_id').select('program_id_key,program_code,master_program_id').order('program_code'),
+    ]);
+    if (masterRes.error)
+        throw new Error(`Fetch dim_master_program failed: ${masterRes.error.message}`);
+    if (programRes.error)
+        throw new Error(`Fetch dim_program_id failed: ${programRes.error.message}`);
+    const lowerNames = names.map(n => n.toLowerCase());
+    const ids = new Set();
+    // Match against master program names
+    for (const row of (masterRes.data ?? [])) {
+        if (lowerNames.some(n => row.master_name.toLowerCase().includes(n))) {
+            ids.add(row.master_program_id);
+        }
+    }
+    // Match against program codes and map back to master_program_id
+    for (const row of (programRes.data ?? [])) {
+        if (row.master_program_id && lowerNames.some(n => row.program_code.toLowerCase().includes(n))) {
+            ids.add(row.master_program_id);
+        }
+    }
+    return [...ids];
+}
+/**
+ * Export KPI data from ReturnPro, aggregated by program/client/month.
+ *
+ * Calls the `get_kpi_totals_by_program_client` Supabase RPC function
+ * (same as dashboard-returnpro's /api/kpis/by-program-client route).
+ *
+ * @returns Flat array of KpiRow sorted by month, kpiName, clientName, programName.
+ */
+export async function exportKpis(options) {
+    // Resolve months
+    let targetMonths;
+    if (options?.months && options.months.length > 0) {
+        targetMonths = options.months.sort();
+    }
+    else {
+        const allMonths = await fetchAvailableMonths();
+        // Default to 3 most recent months
+        targetMonths = allMonths.slice(-3);
+    }
+    if (targetMonths.length === 0) {
+        return [];
+    }
+    // Resolve program filter
+    let programIds;
+    if (options?.programs && options.programs.length > 0) {
+        programIds = await resolveProgramIds(options.programs);
+        if (programIds.length === 0) {
+            console.error(`No programs matched: ${options.programs.join(', ')}`);
+            return [];
+        }
+    }
+    // Fetch KPI data for each month
+    // If we have program filter, call once per programId x month
+    // If no program filter, call once per month (no filter)
+    const allRows = [];
+    for (const month of targetMonths) {
+        if (programIds && programIds.length > 0) {
+            // Call per program to use the RPC filter
+            for (const pid of programIds) {
+                const results = await fetchKpisByMonth(month, pid);
+                for (const row of results) {
+                    allRows.push(mapRow(row));
+                }
+            }
+        }
+        else {
+            const results = await fetchKpisByMonth(month);
+            for (const row of results) {
+                allRows.push(mapRow(row));
+            }
+        }
+    }
+    // Sort: month, kpiName, clientName, programName
+    allRows.sort((a, b) => a.month.localeCompare(b.month)
+        || a.kpiName.localeCompare(b.kpiName)
+        || a.clientName.localeCompare(b.clientName)
+        || a.programName.localeCompare(b.programName));
+    return allRows;
+}
+function mapRow(row) {
+    return {
+        month: row.month,
+        kpiName: row.kpi_name,
+        kpiBucket: row.kpi_bucket,
+        programName: row.master_name ?? '- None -',
+        clientName: row.client_name ?? 'Unknown',
+        totalAmount: typeof row.total_amount === 'string'
+            ? parseFloat(row.total_amount) || 0
+            : Number(row.total_amount) || 0,
+    };
+}
+// --- Formatting ---
+/**
+ * Format KPI rows as a compact markdown table.
+ * Amounts shown in compact notation ($1.2M, $890K).
+ */
+export function formatKpiTable(rows) {
+    if (rows.length === 0)
+        return 'No KPI data found.';
+    const lines = [];
+    lines.push('| Month   | KPI | Bucket | Client | Program | Amount |');
+    lines.push('|---------|-----|--------|--------|---------|--------|');
+    for (const r of rows) {
+        lines.push(`| ${r.month} | ${r.kpiName} | ${r.kpiBucket} | ${r.clientName} | ${r.programName} | ${fmtAmount(r.totalAmount)} |`);
+    }
+    lines.push(`\n${rows.length} rows`);
+    return lines.join('\n');
+}
+/**
+ * Format KPI rows as CSV.
+ */
+export function formatKpiCsv(rows) {
+    const lines = [];
+    lines.push('month,kpi_name,kpi_bucket,client_name,program_name,total_amount');
+    for (const r of rows) {
+        lines.push(`${r.month},${csvEscape(r.kpiName)},${csvEscape(r.kpiBucket)},${csvEscape(r.clientName)},${csvEscape(r.programName)},${r.totalAmount.toFixed(2)}`);
+    }
+    return lines.join('\n');
+}
+function csvEscape(s) {
+    if (s.includes(',') || s.includes('"') || s.includes('\n')) {
+        return `"${s.replace(/"/g, '""')}"`;
+    }
+    return s;
+}
+function fmtAmount(n) {
+    const abs = Math.abs(n);
+    const sign = n < 0 ? '-' : '';
+    if (abs >= 1_000_000)
+        return `${sign}$${(abs / 1_000_000).toFixed(1)}M`;
+    if (abs >= 1_000)
+        return `${sign}$${(abs / 1_000).toFixed(1)}K`;
+    return `${sign}$${abs.toFixed(0)}`;
+}

package/dist/lib/returnpro/templates.d.ts

@@ -0,0 +1,48 @@
+export interface TemplateResult {
+    /** Absolute path where the XLSX was written */
+    outputPath: string;
+    /** Number of account columns included */
+    accountCount: number;
+    /** Number of program rows included */
+    programCount: number;
+    /** Month string used (e.g. "Jan 2026") or undefined if no month was specified */
+    month: string | undefined;
+}
+export interface GenerateNetSuiteTemplateOptions {
+    /**
+     * Fiscal year string, e.g. "2025" or "FY2026". Currently unused for filtering
+     * (all active programs/accounts are included regardless), but stored in the
+     * Instructions sheet for reference.
+     */
+    fiscalYear?: string;
+    /**
+     * Optional month string in "MMM YYYY" format (e.g. "Jan 2026").
+     * When provided the template's Upload Date and Solution7 Date columns are
+     * pre-filled. When omitted those cells are left empty.
+     */
+    month?: string;
+}
+/**
+ * Generate a blank NetSuite upload template XLSX.
+ *
+ * The workbook mirrors the structure produced by dashboard-returnpro's
+ * `/api/admin/netsuite-template` route:
+ *
+ *   Sheet 1 — Data Entry
+ *     Row 1: headers — Master Program | Program ID | Date (Upload) | Date (Solution7) | <account_code>…
+ *     Row 2+: one row per active program, upload/solution7 date cells pre-filled when `month` is given
+ *
+ *   Sheet 2 — Account Reference
+ *     Account Code | Account ID | NetSuite Label
+ *
+ *   Sheet 3 — Instructions
+ *     Key/value metadata + usage instructions
+ *
+ * Accounts are ordered by account_id; programs are ordered by
+ * master_program_name then program_code (matching the route).
+ *
+ * @param outputPath  Destination file path (will be created or overwritten).
+ * @param options     Optional month / fiscalYear metadata.
+ * @returns           TemplateResult with final path and counts.
+ */
+export declare function generateNetSuiteTemplate(outputPath: string, options?: GenerateNetSuiteTemplateOptions): Promise<TemplateResult>;

package/dist/lib/returnpro/templates.js

@@ -0,0 +1,229 @@
+import { writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import ExcelJS from 'exceljs';
+import { getSupabase } from '../supabase.js';
+// --- Helpers ---
+const MONTH_MAP = {
+    Jan: '01', Feb: '02', Mar: '03', Apr: '04',
+    May: '05', Jun: '06', Jul: '07', Aug: '08',
+    Sep: '09', Oct: '10', Nov: '11', Dec: '12',
+};
+/**
+ * Convert "Dec 2025" → "12/1/2025" (NetSuite upload date format).
+ * Returns null if the input is absent or malformed.
+ */
+function monthToUploadDate(monthStr) {
+    const parts = monthStr.trim().split(' ');
+    if (parts.length !== 2)
+        return null;
+    const [name, year] = parts;
+    const num = MONTH_MAP[name];
+    if (!num)
+        return null;
+    return `${num}/1/${year}`;
+}
+const PAGE_SIZE = 1000;
+/** Paginate all rows from a Supabase table, bypassing the 1000-row server cap. */
+async function paginateAll(table, select, orderCol, filters) {
+    const sb = getSupabase('returnpro');
+    const all = [];
+    let from = 0;
+    while (true) {
+        let q = sb.from(table).select(select).order(orderCol).range(from, from + PAGE_SIZE - 1);
+        if (filters) {
+            for (const [col, val] of Object.entries(filters)) {
+                q = q.eq(col, val);
+            }
+        }
+        const { data, error } = await q;
+        if (error)
+            throw new Error(`Fetch ${table} failed: ${error.message}`);
+        if (!data || data.length === 0)
+            break;
+        all.push(...data);
+        if (data.length < PAGE_SIZE)
+            break;
+        from += PAGE_SIZE;
+    }
+    return all;
+}
+// --- Core ---
+/**
+ * Generate a blank NetSuite upload template XLSX.
+ *
+ * The workbook mirrors the structure produced by dashboard-returnpro's
+ * `/api/admin/netsuite-template` route:
+ *
+ *   Sheet 1 — Data Entry
+ *     Row 1: headers — Master Program | Program ID | Date (Upload) | Date (Solution7) | <account_code>…
+ *     Row 2+: one row per active program, upload/solution7 date cells pre-filled when `month` is given
+ *
+ *   Sheet 2 — Account Reference
+ *     Account Code | Account ID | NetSuite Label
+ *
+ *   Sheet 3 — Instructions
+ *     Key/value metadata + usage instructions
+ *
+ * Accounts are ordered by account_id; programs are ordered by
+ * master_program_name then program_code (matching the route).
+ *
+ * @param outputPath  Destination file path (will be created or overwritten).
+ * @param options     Optional month / fiscalYear metadata.
+ * @returns           TemplateResult with final path and counts.
+ */
+export async function generateNetSuiteTemplate(outputPath, options) {
+    const resolvedPath = path.resolve(outputPath);
+    const month = options?.month;
+    const fiscalYear = options?.fiscalYear;
+    // Compute date strings if a month was provided
+    const uploadDate = month ? monthToUploadDate(month) : null;
+    if (month && !uploadDate) {
+        throw new Error(`Invalid month format: "${month}". Expected "MMM YYYY" (e.g. "Jan 2026").`);
+    }
+    // Solution7 date prefixes the month with a leading apostrophe so Excel treats it as text
+    const solution7Date = month ? `'${month}` : null;
+    // --- Fetch dimension data ---
+    const [programs, accounts] = await Promise.all([
+        paginateAll('dim_program_id', 'program_code,master_program_name,is_primary', 'master_program_name', { is_active: 'true' }),
+        paginateAll('dim_account', 'account_code,account_id,netsuite_label', 'account_id'),
+    ]);
+    // Secondary sort: within same master_program_name, order by program_code
+    programs.sort((a, b) => a.master_program_name.localeCompare(b.master_program_name)
+        || a.program_code.localeCompare(b.program_code));
+    // --- Build workbook ---
+    const workbook = new ExcelJS.Workbook();
+    workbook.creator = 'optimal-cli';
+    workbook.created = new Date();
+    // ------------------------------------------------------------------ //
+    // Sheet 1: Data Entry
+    // ------------------------------------------------------------------ //
+    const dataSheet = workbook.addWorksheet('Data Entry');
+    // Build header row
+    const fixedHeaders = ['Master Program', 'Program ID', 'Date (Upload)', 'Date (Solution7)'];
+    const accountHeaders = accounts.map(a => a.account_code);
+    const allHeaders = [...fixedHeaders, ...accountHeaders];
+    // Style the header row
+    const headerRow = dataSheet.addRow(allHeaders);
+    headerRow.font = { bold: true };
+    headerRow.fill = {
+        type: 'pattern',
+        pattern: 'solid',
+        fgColor: { argb: 'FFD9E1F2' }, // light blue
+    };
+    headerRow.alignment = { vertical: 'middle', horizontal: 'center' };
+    // Add one data row per program
+    for (const program of programs) {
+        const rowValues = [
+            program.master_program_name,
+            program.program_code,
+            uploadDate ?? null,
+            solution7Date ?? null,
+            // Account value cells start empty
+            ...accounts.map(() => null),
+        ];
+        dataSheet.addRow(rowValues);
+    }
+    // Freeze the header row and first two columns
+    dataSheet.views = [{ state: 'frozen', xSplit: 2, ySplit: 1 }];
+    // Set column widths
+    const colWidths = [
+        45, // Master Program
+        35, // Program ID
+        15, // Date (Upload)
+        15, // Date (Solution7)
+        ...accounts.map(() => 12),
+    ];
+    dataSheet.columns = allHeaders.map((header, i) => ({
+        header, // overwritten below via addRow — just sets .key
+        key: header,
+        width: colWidths[i],
+    }));
+    // Re-apply the styled header row (addRow above is already row 1; columns
+    // setter re-generates a header via key — replace it with our styled one)
+    // The columns setter inserts an extra header row if we set `header:`.
+    // Avoid that by only setting width/key after rows are added.
+    // Reset: clear columns, re-add rows fresh.
+    // ----- Rebuild cleanly to avoid double-header -----
+    dataSheet.spliceRows(1, dataSheet.rowCount); // clear all rows
+    // Re-add styled header
+    const hdr = dataSheet.addRow(allHeaders);
+    hdr.font = { bold: true };
+    hdr.fill = { type: 'pattern', pattern: 'solid', fgColor: { argb: 'FFD9E1F2' } };
+    hdr.alignment = { vertical: 'middle', horizontal: 'center' };
+    hdr.height = 18;
+    // Re-add data rows
+    for (const program of programs) {
+        const vals = [
+            program.master_program_name,
+            program.program_code,
+            uploadDate ?? null,
+            solution7Date ?? null,
+            ...accounts.map(() => null),
+        ];
+        dataSheet.addRow(vals);
+    }
+    // Column widths (set by index, 1-based)
+    const widths = [45, 35, 15, 15, ...accounts.map(() => 12)];
+    widths.forEach((w, i) => {
+        const col = dataSheet.getColumn(i + 1);
+        col.width = w;
+    });
+    dataSheet.views = [{ state: 'frozen', xSplit: 2, ySplit: 1 }];
+    // ------------------------------------------------------------------ //
+    // Sheet 2: Account Reference
+    // ------------------------------------------------------------------ //
+    const accountSheet = workbook.addWorksheet('Account Reference');
+    const acctHdr = accountSheet.addRow(['Account Code', 'Account ID', 'NetSuite Label']);
+    acctHdr.font = { bold: true };
+    acctHdr.fill = { type: 'pattern', pattern: 'solid', fgColor: { argb: 'FFD9E1F2' } };
+    for (const a of accounts) {
+        accountSheet.addRow([a.account_code, a.account_id, a.netsuite_label ?? '']);
+    }
+    accountSheet.getColumn(1).width = 20;
+    accountSheet.getColumn(2).width = 12;
+    accountSheet.getColumn(3).width = 60;
+    // ------------------------------------------------------------------ //
+    // Sheet 3: Instructions
+    // ------------------------------------------------------------------ //
+    const instrSheet = workbook.addWorksheet('Instructions');
+    const instrHdr = instrSheet.addRow(['Field', 'Value']);
+    instrHdr.font = { bold: true };
+    instrHdr.fill = { type: 'pattern', pattern: 'solid', fgColor: { argb: 'FFD9E1F2' } };
+    const instrRows = [
+        ['Template Generated', new Date().toISOString()],
+        ['Month', month ?? '(not specified)'],
+        ['Upload Date Format', uploadDate ?? '(fill manually — format: MM/1/YYYY)'],
+        ['Fiscal Year', fiscalYear ?? '(not specified)'],
+        ['Total Programs', String(programs.length)],
+        ['Total Account Columns', String(accounts.length)],
+        ['Note', 'Excludes deprecated programs (is_active=false)'],
+        ['', ''],
+        ['Instructions', '1. Fill in account values using Solution7 formulas'],
+        ['', '2. Use the "Date (Solution7)" column value in your formulas'],
+        ['', '3. The "Date (Upload)" column has the format needed for stg_financials_raw'],
+        ['', '4. Save and upload to the dashboard via Browse > stg_financials_raw'],
+        ['', ''],
+        ['Upload Format', 'When uploading, the system expects these columns:'],
+        ['', '  - program_code (from "Program ID" column)'],
+        ['', '  - master_program (from "Master Program" column)'],
+        ['', '  - date (from "Date (Upload)" column)'],
+        ['', '  - account_code (header row value)'],
+        ['', '  - amount (cell value)'],
+    ];
+    for (const [field, value] of instrRows) {
+        instrSheet.addRow([field, value]);
+    }
+    instrSheet.getColumn(1).width = 25;
+    instrSheet.getColumn(2).width = 70;
+    // ------------------------------------------------------------------ //
+    // Write file
+    // ------------------------------------------------------------------ //
+    const buffer = await workbook.xlsx.writeBuffer();
+    await writeFile(resolvedPath, Buffer.from(buffer));
+    return {
+        outputPath: resolvedPath,
+        accountCount: accounts.length,
+        programCount: programs.length,
+        month,
+    };
+}

package/dist/lib/returnpro/upload-income.d.ts

@@ -0,0 +1,25 @@
+export interface IncomeStatementResult {
+    /** Period loaded, e.g. "2025-04" */
+    period: string;
+    /** Human-readable month label parsed from CSV, e.g. "Apr 2025" */
+    monthLabel: string;
+    /** Rows successfully upserted (inserted or updated) */
+    upserted: number;
+    /** Rows skipped due to parse errors */
+    skipped: number;
+    /** Non-fatal warnings / parse error messages */
+    warnings: string[];
+}
+/**
+ * Upload a confirmed income statement CSV into `confirmed_income_statements`.
+ *
+ * Reads the CSV at `filePath`, parses it using the same logic as the
+ * dashboard's income-statement-parser, then upserts all account rows into
+ * ReturnPro Supabase (conflict resolution: account_code + period).
+ *
+ * @param filePath  Absolute path to the NetSuite income statement CSV.
+ * @param userId    User ID to associate with the upload (stored in `uploaded_by` if column exists; otherwise ignored).
+ * @param periodOverride  Optional period override in "YYYY-MM" format.
+ * @returns IncomeStatementResult summary.
+ */
+export declare function uploadIncomeStatements(filePath: string, userId: string, periodOverride?: string): Promise<IncomeStatementResult>;