optimal-cli 0.1.0 → 1.0.0

package/lib/returnpro/templates.ts

@@ -0,0 +1,323 @@
+import { writeFile } from 'node:fs/promises'
+import path from 'node:path'
+import ExcelJS from 'exceljs'
+import { getSupabase } from '../supabase.js'
+
+// --- Types ---
+
+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
+}
+
+// --- Internal types matching Supabase rows ---
+
+interface ProgramIdRow {
+  program_code: string
+  master_program_name: string
+  is_primary: boolean
+}
+
+interface AccountRow {
+  account_code: string
+  account_id: number
+  netsuite_label: string | null
+}
+
+// --- Helpers ---
+
+const MONTH_MAP: Record<string, string> = {
+  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: string): string | null {
+  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<T>(
+  table: string,
+  select: string,
+  orderCol: string,
+  filters?: Record<string, string>,
+): Promise<T[]> {
+  const sb = getSupabase('returnpro')
+  const all: T[] = []
+  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 as T[]))
+    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: string,
+  options?: GenerateNetSuiteTemplateOptions,
+): Promise<TemplateResult> {
+  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<ProgramIdRow>(
+      'dim_program_id',
+      'program_code,master_program_name,is_primary',
+      'master_program_name',
+      { is_active: 'true' },
+    ),
+    paginateAll<AccountRow>(
+      '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: (string | null)[] = [
+      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: (string | null)[] = [
+      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: [string, string][] = [
+    ['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/lib/returnpro/upload-income.ts

@@ -0,0 +1,311 @@
+import { readFileSync } from 'node:fs'
+import { getSupabase } from '../supabase.js'
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+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[]
+}
+
+// Internal row shape before DB upsert
+interface ParsedRow {
+  account_code: string
+  netsuite_label: string
+  total_amount: number
+}
+
+// Shape returned from Supabase upsert with return=representation
+interface UpsertedRow {
+  id: number
+  account_code: string
+  total_amount: number
+}
+
+// ---------------------------------------------------------------------------
+// CSV parsing helpers (mirrors dashboard-returnpro/lib/income-statement-parser.ts)
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse a single CSV line, handling quoted fields and escaped double-quotes.
+ */
+function parseCsvLine(line: string): string[] {
+  const result: string[] = []
+  let current = ''
+  let inQuotes = false
+  let i = 0
+
+  while (i < line.length) {
+    const char = line[i]
+
+    if (char === '"') {
+      if (!inQuotes) {
+        inQuotes = true
+        i++
+        continue
+      }
+      // Inside quotes — check for escaped quote
+      if (line[i + 1] === '"') {
+        current += '"'
+        i += 2
+        continue
+      }
+      inQuotes = false
+      i++
+      continue
+    }
+
+    if (char === ',' && !inQuotes) {
+      result.push(current.trim())
+      current = ''
+      i++
+      continue
+    }
+
+    current += char
+    i++
+  }
+
+  result.push(current.trim())
+  return result
+}
+
+/**
+ * Parse a currency string like "$1,234.56" or "($1,234.56)" to a number.
+ */
+function parseCurrency(value: string): number {
+  if (!value || value.trim() === '') return 0
+  const cleaned = value.trim()
+  const isNegative = cleaned.startsWith('(') && cleaned.endsWith(')')
+  const numericStr = cleaned.replace(/[$,()]/g, '').trim()
+  if (numericStr === '' || numericStr === '-') return 0
+  const parsed = parseFloat(numericStr)
+  if (isNaN(parsed)) return 0
+  return isNegative ? -parsed : parsed
+}
+
+/**
+ * Extract account_code and netsuite_label from a row's first column.
+ * Expects format "30010 - B2B Owned Sales".
+ * Returns null for header/summary rows that should be skipped.
+ */
+function extractAccountCode(
+  label: string,
+): { account_code: string; netsuite_label: string } | null {
+  if (!label) return null
+  const trimmed = label.trim()
+
+  const SKIP = [
+    '',
+    'Ordinary Income/Expense',
+    'Income',
+    'Cost Of Sales',
+    'Expense',
+    'Other Income and Expenses',
+    'Other Income',
+    'Other Expense',
+  ]
+  if (SKIP.includes(trimmed)) return null
+  if (
+    trimmed.startsWith('Total -') ||
+    trimmed.startsWith('Gross Profit') ||
+    trimmed.startsWith('Net Ordinary Income') ||
+    trimmed.startsWith('Net Other Income') ||
+    trimmed.startsWith('Net Income')
+  ) {
+    return null
+  }
+
+  // Pattern: "XXXXX - Label"
+  const match = trimmed.match(/^(\d{5})\s*-\s*(.+)$/)
+  if (!match) return null
+
+  return {
+    account_code: match[1],
+    netsuite_label: match[2].trim(),
+  }
+}
+
+const MONTH_MAP: Record<string, string> = {
+  jan: '01', january: '01',
+  feb: '02', february: '02',
+  mar: '03', march: '03',
+  apr: '04', april: '04',
+  may: '05',
+  jun: '06', june: '06',
+  jul: '07', july: '07',
+  aug: '08', august: '08',
+  sep: '09', september: '09',
+  oct: '10', october: '10',
+  nov: '11', november: '11',
+  dec: '12', december: '12',
+}
+
+/**
+ * Convert "Apr 2025" -> "2025-04".  Returns "" on failure.
+ */
+function monthLabelToPeriod(label: string): string {
+  const match = label.trim().match(/^([a-zA-Z]+)\s+(\d{4})$/i)
+  if (!match) return ''
+  const month = MONTH_MAP[match[1].toLowerCase()]
+  if (!month) return ''
+  return `${match[2]}-${month}`
+}
+
+interface ParseResult {
+  period: string
+  monthLabel: string
+  rows: ParsedRow[]
+  errors: string[]
+}
+
+/**
+ * Parse a NetSuite income statement CSV text into rows.
+ *
+ * NetSuite export format:
+ *   Row 4  (index 3): Month label — "Apr 2025"
+ *   Row 7  (index 6): Column headers (last "Total" col is the consolidated amount)
+ *   Row 9+ (index 8+): Data rows
+ */
+function parseIncomeStatementCSV(csvText: string): ParseResult {
+  const lines = csvText.replace(/\r\n/g, '\n').replace(/\r/g, '\n').split('\n')
+  const errors: string[] = []
+  const rows: ParsedRow[] = []
+
+  // Month label is on row 4 (0-indexed: 3)
+  const monthLabel = lines[3]?.trim() ?? ''
+  const period = monthLabelToPeriod(monthLabel)
+
+  if (!period) {
+    errors.push(`Could not parse period from row 4: "${monthLabel}"`)
+  }
+
+  // Find "Total" column index from header row (row 7, index 6)
+  const headerLine = lines[6] ?? ''
+  const headers = parseCsvLine(headerLine)
+  let totalColIdx = headers.length - 1
+  for (let i = headers.length - 1; i >= 0; i--) {
+    if (headers[i].toLowerCase().includes('total')) {
+      totalColIdx = i
+      break
+    }
+  }
+
+  // Data rows start at index 8 (row 9)
+  for (let i = 8; i < lines.length; i++) {
+    const line = lines[i]
+    if (!line || line.trim() === '') continue
+
+    const cols = parseCsvLine(line)
+    if (cols.length === 0) continue
+
+    const acctInfo = extractAccountCode(cols[0])
+    if (!acctInfo) continue
+
+    const totalStr = cols[totalColIdx] ?? ''
+    const amount = parseCurrency(totalStr)
+
+    rows.push({
+      account_code: acctInfo.account_code,
+      netsuite_label: acctInfo.netsuite_label,
+      total_amount: amount,
+    })
+  }
+
+  if (rows.length === 0) {
+    errors.push('No valid account rows found in CSV')
+  }
+
+  return { period, monthLabel, rows, errors }
+}
+
+// ---------------------------------------------------------------------------
+// Core export
+// ---------------------------------------------------------------------------
+
+/**
+ * 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 async function uploadIncomeStatements(
+  filePath: string,
+  userId: string,
+  periodOverride?: string,
+): Promise<IncomeStatementResult> {
+  // 1. Read file
+  const csvText = readFileSync(filePath, 'utf-8')
+
+  // 2. Parse CSV
+  const parsed = parseIncomeStatementCSV(csvText)
+
+  // 3. Resolve period
+  const period = periodOverride ?? parsed.period
+
+  if (!period) {
+    throw new Error(
+      `Could not detect period from CSV. Provide a periodOverride (e.g. "2025-04"). Parse errors: ${parsed.errors.join('; ')}`,
+    )
+  }
+
+  if (parsed.rows.length === 0) {
+    throw new Error(
+      `No valid account rows found in ${filePath}. Parse errors: ${parsed.errors.join('; ')}`,
+    )
+  }
+
+  // 4. Build insert rows
+  const now = new Date().toISOString()
+  const insertRows = parsed.rows.map((row) => ({
+    account_code: row.account_code,
+    netsuite_label: row.netsuite_label,
+    period,
+    total_amount: row.total_amount,
+    source: 'netsuite',
+    updated_at: now,
+  }))
+
+  // 5. Upsert into confirmed_income_statements
+  //    Conflict target: (account_code, period) — merge-duplicates via onConflict
+  const sb = getSupabase('returnpro')
+
+  const { data, error } = await sb
+    .from('confirmed_income_statements')
+    .upsert(insertRows, {
+      onConflict: 'account_code,period',
+      ignoreDuplicates: false,
+    })
+    .select('id,account_code,total_amount')
+
+  if (error) {
+    throw new Error(`Supabase upsert failed: ${error.message}${error.hint ? ` (Hint: ${error.hint})` : ''}`)
+  }
+
+  const upserted = (data as UpsertedRow[] | null)?.length ?? 0
+  const skipped = parsed.rows.length - upserted
+
+  return {
+    period,
+    monthLabel: parsed.monthLabel,
+    upserted,
+    skipped,
+    warnings: parsed.errors,
+  }
+}