optimal-cli 1.0.0 → 1.0.1

package/lib/returnpro/anomalies.ts

@@ -1,258 +0,0 @@
-import { getSupabase } from '../supabase.js'
-
-// --- Types ---
-
-export interface RateAnomaly {
-  /** Master program name (e.g., "Bass Pro Shops Liquidation") */
-  master_program: string
-  /** Program code (e.g., "BRTON-BPS-LIQ") */
-  program_code: string | null
-  /** Numeric program ID key from dim_program_id */
-  program_id: number | null
-  /** Client ID from dim_client */
-  client_id: number | null
-  /** Client display name */
-  client_name: string | null
-  /** YYYY-MM period */
-  month: string
-  /** Service Check In Fee dollars for this program+month */
-  checkin_fee_dollars: number
-  /** Checked-in units for this program+month */
-  units: number
-  /** Dollars per unit = checkin_fee_dollars / units */
-  rate_per_unit: number
-  /** Prior month's rate_per_unit for comparison */
-  prev_month_rate: number | null
-  /** % change in rate vs prior month */
-  rate_delta_pct: number | null
-  /** % change in units vs prior month */
-  units_change_pct: number | null
-  /** % change in dollars vs prior month */
-  dollars_change_pct: number | null
-  /** Z-score of rate_per_unit within the portfolio cross-section */
-  zscore: number
-  /**
-   * The [mean - 2σ, mean + 2σ] interval computed from all program rates
-   * in the same period. Rates outside this window are flagged.
-   */
-  expected_range: [number, number]
-}
-
-export interface AnomalyResult {
-  /** Anomalies that exceed the z-score threshold */
-  anomalies: RateAnomaly[]
-  /** Total rows fetched from v_rate_anomaly_analysis before filtering */
-  totalRows: number
-  /** Z-score threshold used (default 2.0) */
-  threshold: number
-  /** Months included in the analysis */
-  months: string[]
-}
-
-// --- Helpers ---
-
-const PAGE_SIZE = 1000
-
-interface ViewRow {
-  master_program: string
-  program_code: string | null
-  program_id: number | null
-  client_id: number | null
-  client_name: string | null
-  month: string
-  checkin_fee_dollars: number | string
-  units: number | string
-  rate_per_unit: number | string | null
-  prev_month_rate: number | string | null
-  rate_delta_pct: number | string | null
-  units_change_pct: number | string | null
-  dollars_change_pct: number | string | null
-}
-
-function toNum(v: number | string | null | undefined): number {
-  if (v === null || v === undefined) return 0
-  return typeof v === 'string' ? parseFloat(v) || 0 : Number(v) || 0
-}
-
-function toNumOrNull(v: number | string | null | undefined): number | null {
-  if (v === null || v === undefined) return null
-  const n = typeof v === 'string' ? parseFloat(v) : Number(v)
-  return isFinite(n) ? n : null
-}
-
-/**
- * Paginate through v_rate_anomaly_analysis with optional month filters.
- * Returns raw view rows.
- */
-async function fetchViewRows(months?: string[]): Promise<ViewRow[]> {
-  const sb = getSupabase('returnpro')
-  const allRows: ViewRow[] = []
-  let from = 0
-
-  while (true) {
-    let query = sb
-      .from('v_rate_anomaly_analysis')
-      .select(
-        'master_program,program_code,program_id,client_id,client_name,' +
-        'month,checkin_fee_dollars,units,rate_per_unit,prev_month_rate,' +
-        'rate_delta_pct,units_change_pct,dollars_change_pct'
-      )
-      .order('month', { ascending: false })
-      .order('master_program')
-      .range(from, from + PAGE_SIZE - 1)
-
-    if (months && months.length > 0) {
-      query = query.in('month', months)
-    }
-
-    const { data, error } = await query
-
-    if (error) throw new Error(`Fetch v_rate_anomaly_analysis failed: ${error.message}`)
-    if (!data || data.length === 0) break
-
-    allRows.push(...(data as unknown as ViewRow[]))
-    if (data.length < PAGE_SIZE) break
-    from += PAGE_SIZE
-  }
-
-  return allRows
-}
-
-/**
- * Compute mean and standard deviation for an array of numbers.
- * Returns { mean, stddev }. If fewer than 2 values, stddev = 0.
- */
-function computeStats(values: number[]): { mean: number; stddev: number } {
-  if (values.length === 0) return { mean: 0, stddev: 0 }
-  const mean = values.reduce((s, v) => s + v, 0) / values.length
-  if (values.length < 2) return { mean, stddev: 0 }
-  const variance = values.reduce((s, v) => s + (v - mean) ** 2, 0) / (values.length - 1)
-  return { mean, stddev: Math.sqrt(variance) }
-}
-
-// --- Core ---
-
-/**
- * Detect $/unit rate outliers across all programs in stg_financials_raw.
- *
- * Method:
- *   1. Fetch all rows from v_rate_anomaly_analysis (paginated) filtered to
- *      the requested months (or fiscal YTD if omitted).
- *   2. For each month, compute mean and population stddev of rate_per_unit
- *      across all programs with valid rates.
- *   3. Flag any program-month where |z-score| > threshold (default 2.0).
- *   4. Return the flagged rows sorted by |z-score| descending.
- *
- * @param options.months   - YYYY-MM strings to analyse. If omitted, uses fiscal
- *                           YTD (April of current/previous fiscal year → today).
- * @param options.threshold - Z-score magnitude threshold. Default 2.0.
- */
-export async function detectRateAnomalies(
-  options?: { months?: string[]; threshold?: number }
-): Promise<AnomalyResult> {
-  const threshold = options?.threshold ?? 2.0
-
-  // Resolve target months: explicit list, or derive fiscal YTD
-  let targetMonths: string[] | undefined = options?.months
-
-  if (!targetMonths || targetMonths.length === 0) {
-    // Fiscal year starts April. If Jan-Mar, fiscal year began previous calendar year.
-    const now = new Date()
-    const month0 = now.getMonth() // 0-indexed
-    const year = now.getFullYear()
-    const fiscalStartYear = month0 < 3 ? year - 1 : year
-    const fiscalStart = `${fiscalStartYear}-04`
-    const currentMonthStr = `${year}-${String(month0 + 1).padStart(2, '0')}`
-
-    // Build explicit month list for fiscal YTD so the DB filter is tight
-    const start = new Date(`${fiscalStart}-01`)
-    const end = new Date(`${currentMonthStr}-01`)
-    const months: string[] = []
-    const cursor = new Date(start)
-    while (cursor <= end) {
-      months.push(
-        `${cursor.getFullYear()}-${String(cursor.getMonth() + 1).padStart(2, '0')}`
-      )
-      cursor.setMonth(cursor.getMonth() + 1)
-    }
-    targetMonths = months
-  }
-
-  // Fetch view rows
-  const rawRows = await fetchViewRows(targetMonths)
-  const totalRows = rawRows.length
-
-  if (totalRows === 0) {
-    return { anomalies: [], totalRows: 0, threshold, months: targetMonths }
-  }
-
-  // Group rows by month for per-month z-score calculation
-  const byMonth = new Map<string, ViewRow[]>()
-  for (const row of rawRows) {
-    const m = row.month
-    if (!byMonth.has(m)) byMonth.set(m, [])
-    byMonth.get(m)!.push(row)
-  }
-
-  // Compute z-scores per month and collect anomalies
-  const anomalies: RateAnomaly[] = []
-
-  for (const [month, rows] of byMonth) {
-    // Collect valid (non-null, positive-unit) rate values for this month
-    const validRates = rows
-      .map(r => toNumOrNull(r.rate_per_unit))
-      .filter((v): v is number => v !== null && isFinite(v))
-
-    const { mean, stddev } = computeStats(validRates)
-
-    for (const row of rows) {
-      const rate = toNumOrNull(row.rate_per_unit)
-      if (rate === null) continue // cannot score rows with no rate
-
-      const units = toNum(row.units)
-      if (units <= 0) continue // require positive units for a meaningful rate
-
-      // Z-score: how many std-deviations from the mean
-      const zscore = stddev > 0 ? (rate - mean) / stddev : 0
-
-      if (Math.abs(zscore) <= threshold) continue // within normal range
-
-      const expectedLow = mean - threshold * stddev
-      const expectedHigh = mean + threshold * stddev
-
-      anomalies.push({
-        master_program: row.master_program,
-        program_code: row.program_code,
-        program_id: typeof row.program_id === 'number' ? row.program_id : null,
-        client_id: typeof row.client_id === 'number' ? row.client_id : null,
-        client_name: row.client_name,
-        month,
-        checkin_fee_dollars: toNum(row.checkin_fee_dollars),
-        units,
-        rate_per_unit: rate,
-        prev_month_rate: toNumOrNull(row.prev_month_rate),
-        rate_delta_pct: toNumOrNull(row.rate_delta_pct),
-        units_change_pct: toNumOrNull(row.units_change_pct),
-        dollars_change_pct: toNumOrNull(row.dollars_change_pct),
-        zscore: Math.round(zscore * 100) / 100,
-        expected_range: [
-          Math.round(expectedLow * 10000) / 10000,
-          Math.round(expectedHigh * 10000) / 10000,
-        ],
-      })
-    }
-  }
-
-  // Sort by absolute z-score descending (most extreme outliers first)
-  anomalies.sort((a, b) => Math.abs(b.zscore) - Math.abs(a.zscore))
-
-  // Collect distinct months that were actually present in the data
-  const observedMonths = [...new Set(rawRows.map(r => r.month))].sort().reverse()
-
-  return {
-    anomalies,
-    totalRows,
-    threshold,
-    months: observedMonths,
-  }
-}

package/lib/returnpro/audit.ts

@@ -1,194 +0,0 @@
-import { getSupabase } from '../supabase.js'
-
-// --- Types ---
-
-export interface MonthSummary {
-  month: string              // YYYY-MM
-  confirmedAccounts: number
-  stagedAccounts: number
-  exactMatch: number
-  signFlipMatch: number
-  mismatch: number
-  confirmedOnly: number
-  stagingOnly: number
-  accuracy: number | null    // percentage on overlap, null if no overlap
-  stagedTotal: number        // absolute sum of staged amounts
-  confirmedTotal: number     // absolute sum of confirmed amounts
-}
-
-export interface AuditResult {
-  summaries: MonthSummary[]
-  totalStagingRows: number
-  totalConfirmedRows: number
-}
-
-// --- Helpers ---
-
-const PAGE_SIZE = 1000
-
-/**
- * Paginate through a Supabase table, fetching all rows.
- * Uses .range() to bypass the 1000-row cap.
- */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-async function paginateAll(
-  table: string,
-  select: string,
-  orderCol: string,
-): Promise<any[]> {
-  const sb = getSupabase('returnpro')
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  const allRows: any[] = []
-  let from = 0
-
-  while (true) {
-    const query = sb.from(table).select(select).order(orderCol).range(from, from + PAGE_SIZE - 1)
-
-    const { data, error } = await query
-
-    if (error) throw new Error(`Fetch ${table} failed: ${error.message}`)
-    if (!data || data.length === 0) break
-
-    allRows.push(...data)
-    if (data.length < PAGE_SIZE) break
-    from += PAGE_SIZE
-  }
-
-  return allRows
-}
-
-// --- Core ---
-
-/**
- * Compare staged financials against confirmed income statements.
- *
- * Replicates the logic from dashboard-returnpro's /api/staging/audit-summary route:
- * 1. Paginate stg_financials_raw (amount is TEXT, must parseFloat)
- * 2. Paginate confirmed_income_statements
- * 3. Aggregate staging by account_code|YYYY-MM key
- * 4. Compare with tolerance (default $1.00), detect sign-flips
- * 5. Return per-month summaries with accuracy %
- *
- * @param months - Optional array of YYYY-MM strings to filter to. If omitted, all months are included.
- * @param tolerance - Dollar tolerance for match detection. Default $1.00.
- */
-export async function runAuditComparison(
-  months?: string[],
-  tolerance = 1.00,
-): Promise<AuditResult> {
-  // 1. Fetch all staging rows (paginated)
-  const stagingRows = await paginateAll(
-    'stg_financials_raw', 'account_code,date,amount', 'date',
-  ) as Array<{ account_code: string; date: string; amount: string }>
-
-  // 2. Fetch all confirmed income statements (paginated)
-  const confirmedRows = await paginateAll(
-    'confirmed_income_statements', 'account_code,period,total_amount', 'period',
-  ) as Array<{ account_code: string; period: string; total_amount: number }>
-
-  // 3. Aggregate staging: account_code|YYYY-MM -> sum(amount)
-  //    amount is TEXT in the DB — must parseFloat
-  const stagingAgg = new Map<string, number>()
-  for (const row of stagingRows) {
-    const month = row.date ? row.date.substring(0, 7) : null
-    if (!month) continue
-    const key = `${row.account_code}|${month}`
-    stagingAgg.set(key, (stagingAgg.get(key) ?? 0) + (parseFloat(row.amount) || 0))
-  }
-
-  // 4. Build confirmed lookup: account_code|YYYY-MM -> total_amount
-  const confirmedMap = new Map<string, number>()
-  for (const row of confirmedRows) {
-    const key = `${row.account_code}|${row.period}`
-    confirmedMap.set(key, parseFloat(String(row.total_amount)) || 0)
-  }
-
-  // 5. Collect all months present in either dataset
-  const allMonths = new Set<string>()
-  for (const key of stagingAgg.keys()) allMonths.add(key.split('|')[1])
-  for (const key of confirmedMap.keys()) allMonths.add(key.split('|')[1])
-
-  // 6. Filter to requested months if specified
-  const targetMonths = months
-    ? [...allMonths].filter(m => months.includes(m)).sort()
-    : [...allMonths].sort()
-
-  // 7. Build per-month summaries
-  const summaries: MonthSummary[] = []
-
-  for (const month of targetMonths) {
-    // Collect accounts present in each dataset for this month
-    const cAccounts = new Set<string>()
-    const sAccounts = new Set<string>()
-
-    for (const key of confirmedMap.keys()) {
-      if (key.endsWith(`|${month}`)) cAccounts.add(key.split('|')[0])
-    }
-    for (const key of stagingAgg.keys()) {
-      if (key.endsWith(`|${month}`)) sAccounts.add(key.split('|')[0])
-    }
-
-    let exactMatch = 0
-    let signFlipMatch = 0
-    let mismatch = 0
-    let confirmedOnly = 0
-    let stagingOnly = 0
-    let stagedTotal = 0
-    let confirmedTotal = 0
-
-    // Compare confirmed accounts against staging
-    for (const acct of cAccounts) {
-      const cAmt = confirmedMap.get(`${acct}|${month}`) ?? 0
-      confirmedTotal += Math.abs(cAmt)
-
-      if (sAccounts.has(acct)) {
-        const sAmt = stagingAgg.get(`${acct}|${month}`) ?? 0
-        const directDiff = Math.abs(cAmt - sAmt)
-        const signFlipDiff = Math.abs(cAmt + sAmt)
-
-        if (directDiff <= tolerance) {
-          exactMatch++
-        } else if (signFlipDiff <= tolerance) {
-          signFlipMatch++
-        } else {
-          mismatch++
-        }
-      } else {
-        confirmedOnly++
-      }
-    }
-
-    // Count staging-only accounts and accumulate staged total
-    for (const acct of sAccounts) {
-      const sAmt = stagingAgg.get(`${acct}|${month}`) ?? 0
-      stagedTotal += Math.abs(sAmt)
-      if (!cAccounts.has(acct)) stagingOnly++
-    }
-
-    // Accuracy = (exactMatch + signFlipMatch) / overlap, null if no overlap
-    const overlap = exactMatch + signFlipMatch + mismatch
-    const accuracy = overlap > 0
-      ? Math.round(((exactMatch + signFlipMatch) / overlap) * 1000) / 10
-      : null
-
-    summaries.push({
-      month,
-      confirmedAccounts: cAccounts.size,
-      stagedAccounts: sAccounts.size,
-      exactMatch,
-      signFlipMatch,
-      mismatch,
-      confirmedOnly,
-      stagingOnly,
-      accuracy,
-      stagedTotal,
-      confirmedTotal,
-    })
-  }
-
-  return {
-    summaries,
-    totalStagingRows: stagingRows.length,
-    totalConfirmedRows: confirmedRows.length,
-  }
-}