optimal-cli 0.1.0

package/dist/lib/returnpro/upload-r1.js

@@ -0,0 +1,398 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import ExcelJS from 'exceljs';
+import { getSupabase } from '../supabase.js';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/**
+ * Account code / ID for Checked-In Qty, which is the primary volume type
+ * produced by a standard R1 upload. This matches the dashboard's volume-configs.ts.
+ *
+ * account_code: "Checked-In Qty"
+ * account_id:   130
+ */
+const CHECKED_IN_ACCOUNT_CODE = 'Checked-In Qty';
+const CHECKED_IN_ACCOUNT_ID = 130;
+const CHUNK_SIZE = 500;
+const PAGE_SIZE = 1000;
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Extract location from a ProgramName / program code string.
+ * - If starts with "DS-", location is "DS"
+ * - Otherwise, first 5 characters (uppercased)
+ * Mirrors dashboard-returnpro/lib/r1-monthly/processing.ts extractLocation()
+ */
+function extractLocation(programName) {
+    const trimmed = programName.trim();
+    if (!trimmed)
+        return 'UNKNOWN';
+    if (trimmed.startsWith('DS-'))
+        return 'DS';
+    return trimmed.substring(0, 5).toUpperCase();
+}
+/**
+ * Split an array into fixed-size chunks for batched inserts.
+ */
+function chunk(arr, size) {
+    const out = [];
+    for (let i = 0; i < arr.length; i += size) {
+        out.push(arr.slice(i, i + size));
+    }
+    return out;
+}
+// ---------------------------------------------------------------------------
+// Supabase dim table lookups
+// ---------------------------------------------------------------------------
+/**
+ * Fetch all dim_program_id rows and build a map: program_code -> program_id_key.
+ * Fetches ALL rows in pages to avoid the 1000-row Supabase cap.
+ * First occurrence wins for any duplicate program_code.
+ */
+async function buildProgramIdKeyMap(supabaseUrl, supabaseKey) {
+    const map = new Map();
+    let offset = 0;
+    while (true) {
+        const url = `${supabaseUrl}/rest/v1/dim_program_id` +
+            `?select=program_id_key,program_code` +
+            `&order=program_id_key` +
+            `&offset=${offset}&limit=${PAGE_SIZE}`;
+        const res = await fetch(url, {
+            headers: { apikey: supabaseKey, Authorization: `Bearer ${supabaseKey}` },
+        });
+        if (!res.ok) {
+            const text = await res.text();
+            throw new Error(`Failed to fetch dim_program_id: ${text}`);
+        }
+        const rows = (await res.json());
+        for (const row of rows) {
+            if (!map.has(row.program_code)) {
+                map.set(row.program_code, row.program_id_key);
+            }
+        }
+        if (rows.length < PAGE_SIZE)
+            break;
+        offset += PAGE_SIZE;
+    }
+    return map;
+}
+/**
+ * Fetch all dim_master_program rows and build a map: master_name -> {master_program_id, client_id}.
+ * Fetches ALL rows in pages to avoid the 1000-row Supabase cap.
+ */
+async function buildMasterProgramMap(supabaseUrl, supabaseKey) {
+    const map = new Map();
+    let offset = 0;
+    while (true) {
+        const url = `${supabaseUrl}/rest/v1/dim_master_program` +
+            `?select=master_program_id,master_name,client_id` +
+            `&order=master_program_id` +
+            `&offset=${offset}&limit=${PAGE_SIZE}`;
+        const res = await fetch(url, {
+            headers: { apikey: supabaseKey, Authorization: `Bearer ${supabaseKey}` },
+        });
+        if (!res.ok) {
+            const text = await res.text();
+            throw new Error(`Failed to fetch dim_master_program: ${text}`);
+        }
+        const rows = (await res.json());
+        for (const row of rows) {
+            if (!map.has(row.master_name)) {
+                map.set(row.master_name, row);
+            }
+        }
+        if (rows.length < PAGE_SIZE)
+            break;
+        offset += PAGE_SIZE;
+    }
+    return map;
+}
+// ---------------------------------------------------------------------------
+// XLSX parsing
+// ---------------------------------------------------------------------------
+/**
+ * Parse the first sheet of an R1 XLSX file into R1Row records.
+ *
+ * Required columns (case-sensitive, matching the Rust WASM parser):
+ *   ProgramName
+ *   Master Program Name
+ *   TRGID
+ *
+ * Optional columns:
+ *   LocationID
+ *   MR_LMR_UPC_AverageCategoryRetail  (or "RetailPrice" / "Retail Price")
+ *
+ * Returns { rows, totalRead, skipped, warnings }
+ */
+async function parseR1Xlsx(filePath) {
+    const warnings = [];
+    const workbook = new ExcelJS.Workbook();
+    await workbook.xlsx.readFile(filePath);
+    const worksheet = workbook.worksheets[0];
+    if (!worksheet) {
+        throw new Error(`R1 XLSX has no worksheets: ${filePath}`);
+    }
+    // Read header row (row 1)
+    const headerRow = worksheet.getRow(1);
+    const headers = new Map();
+    headerRow.eachCell({ includeEmpty: false }, (cell, colNum) => {
+        const val = String(cell.value ?? '').trim();
+        if (val)
+            headers.set(val, colNum);
+    });
+    // Resolve required column indices
+    const programCol = headers.get('ProgramName');
+    const masterCol = headers.get('Master Program Name');
+    const trgidCol = headers.get('TRGID');
+    if (programCol === undefined || masterCol === undefined || trgidCol === undefined) {
+        throw new Error(`R1 XLSX missing required columns. ` +
+            `Expected: ProgramName, Master Program Name, TRGID. ` +
+            `Found: ${[...headers.keys()].join(', ')}`);
+    }
+    // Resolve optional column indices
+    const locationCol = headers.get('LocationID');
+    const retailCol = headers.get('MR_LMR_UPC_AverageCategoryRetail') ??
+        headers.get('RetailPrice') ??
+        headers.get('Retail Price');
+    const rows = [];
+    let totalRead = 0;
+    let skipped = 0;
+    worksheet.eachRow({ includeEmpty: false }, (row, rowNum) => {
+        if (rowNum === 1)
+            return; // skip header
+        totalRead++;
+        const programCode = String(row.getCell(programCol).value ?? '').trim();
+        const masterProgram = String(row.getCell(masterCol).value ?? '').trim();
+        const trgid = String(row.getCell(trgidCol).value ?? '').trim();
+        // Skip rows missing the three required values
+        if (!programCode || !masterProgram || !trgid) {
+            skipped++;
+            return;
+        }
+        const locationId = locationCol
+            ? String(row.getCell(locationCol).value ?? '').trim()
+            : '';
+        let avgRetail = null;
+        if (retailCol !== undefined) {
+            const rawRetail = row.getCell(retailCol).value;
+            if (rawRetail !== null && rawRetail !== undefined && rawRetail !== '') {
+                const parsed = typeof rawRetail === 'number' ? rawRetail : parseFloat(String(rawRetail));
+                if (!isNaN(parsed) && parsed > 0)
+                    avgRetail = parsed;
+            }
+        }
+        rows.push({ programCode, masterProgram, trgid, locationId, avgRetail });
+    });
+    if (rows.length === 0 && totalRead > 0) {
+        warnings.push(`All ${totalRead} rows were skipped (missing ProgramName, Master Program Name, or TRGID). ` +
+            `Check that the first sheet contains data with the expected column headers.`);
+    }
+    return { rows, totalRead, skipped, warnings };
+}
+// ---------------------------------------------------------------------------
+// Aggregation
+// ---------------------------------------------------------------------------
+/**
+ * Aggregate raw R1 rows into per-(masterProgram, programCode, location) groups.
+ * For each group we track distinct TRGIDs and distinct LocationIDs.
+ * This mirrors the Rust WASM aggregation in wasm/r1-parser/src/lib.rs.
+ *
+ * The count stored in `amount` uses distinct TRGID count (Checked-In Qty
+ * for most programs). The LocationID set is retained for callers that need it.
+ */
+function aggregateRows(rows) {
+    const groups = new Map();
+    for (const row of rows) {
+        const location = extractLocation(row.programCode);
+        const key = `${row.masterProgram}|||${row.programCode}|||${location}`;
+        let group = groups.get(key);
+        if (!group) {
+            group = {
+                masterProgram: row.masterProgram,
+                masterProgramId: null,
+                programCode: row.programCode,
+                programIdKey: null,
+                clientId: null,
+                location,
+                trgidSet: new Set(),
+                locationIdSet: new Set(),
+            };
+            groups.set(key, group);
+        }
+        group.trgidSet.add(row.trgid);
+        if (row.locationId)
+            group.locationIdSet.add(row.locationId);
+    }
+    return groups;
+}
+// ---------------------------------------------------------------------------
+// Insertion helpers
+// ---------------------------------------------------------------------------
+/**
+ * Insert a batch of rows directly into stg_financials_raw via PostgREST.
+ * Returns the number of rows inserted (or throws on failure).
+ */
+async function insertBatch(supabaseUrl, supabaseKey, rows) {
+    const res = await fetch(`${supabaseUrl}/rest/v1/stg_financials_raw`, {
+        method: 'POST',
+        headers: {
+            apikey: supabaseKey,
+            Authorization: `Bearer ${supabaseKey}`,
+            'Content-Type': 'application/json',
+            Prefer: 'return=minimal',
+        },
+        body: JSON.stringify(rows),
+    });
+    if (!res.ok) {
+        const text = await res.text();
+        let message = text || res.statusText;
+        try {
+            const payload = JSON.parse(text);
+            message = payload.message ?? message;
+            if (payload.hint)
+                message += ` (Hint: ${payload.hint})`;
+            if (payload.details)
+                message += ` (Details: ${payload.details})`;
+        }
+        catch {
+            // use raw text
+        }
+        throw new Error(`Insert batch failed: ${message}`);
+    }
+    return rows.length;
+}
+// ---------------------------------------------------------------------------
+// Main export
+// ---------------------------------------------------------------------------
+/**
+ * Parse an R1 XLSX file, aggregate financial data by program, and insert
+ * into the ReturnPro `stg_financials_raw` staging table.
+ *
+ * Flow:
+ *   1. Read and parse the XLSX (first sheet, required columns: ProgramName,
+ *      Master Program Name, TRGID).
+ *   2. Aggregate rows into (masterProgram, programCode, location) groups,
+ *      counting distinct TRGIDs per group.
+ *   3. Look up dim_master_program and dim_program_id to resolve FK columns.
+ *   4. Insert into stg_financials_raw in batches of 500.
+ *
+ * @param filePath   Absolute path to the R1 XLSX file on disk.
+ * @param userId     The user_id to stamp on each inserted row.
+ * @param monthYear  Target month in "YYYY-MM" format (e.g. "2025-10").
+ *                   Stored as the `date` column as "YYYY-MM-01".
+ */
+export async function processR1Upload(filePath, userId, monthYear) {
+    if (!fs.existsSync(filePath)) {
+        throw new Error(`File not found: ${filePath}`);
+    }
+    // Validate monthYear format
+    if (!/^\d{4}-\d{2}$/.test(monthYear)) {
+        throw new Error(`monthYear must be in YYYY-MM format (e.g. "2025-10"), got: "${monthYear}"`);
+    }
+    const sourceFileName = path.basename(filePath);
+    const dateStr = `${monthYear}-01`;
+    const loadedAt = new Date().toISOString();
+    const warnings = [];
+    // -------------------------------------------------------------------------
+    // 1. Parse XLSX
+    // -------------------------------------------------------------------------
+    const { rows: rawRows, totalRead, skipped, warnings: parseWarnings } = await parseR1Xlsx(filePath);
+    warnings.push(...parseWarnings);
+    if (rawRows.length === 0) {
+        return {
+            sourceFileName,
+            date: dateStr,
+            totalRowsRead: totalRead,
+            rowsSkipped: skipped,
+            programGroupsFound: 0,
+            rowsInserted: 0,
+            warnings,
+        };
+    }
+    // -------------------------------------------------------------------------
+    // 2. Aggregate rows into groups
+    // -------------------------------------------------------------------------
+    const groups = aggregateRows(rawRows);
+    // -------------------------------------------------------------------------
+    // 3. Fetch dim tables for FK resolution
+    // -------------------------------------------------------------------------
+    const sb = getSupabase('returnpro');
+    // Pull the connection URL + key from the client's config via env (same env
+    // vars that supabase.ts reads from process.env)
+    const supabaseUrl = process.env['RETURNPRO_SUPABASE_URL'];
+    const supabaseKey = process.env['RETURNPRO_SUPABASE_SERVICE_KEY'];
+    if (!supabaseUrl || !supabaseKey) {
+        throw new Error('Missing env vars: RETURNPRO_SUPABASE_URL, RETURNPRO_SUPABASE_SERVICE_KEY');
+    }
+    const [programIdKeyMap, masterProgramMap] = await Promise.all([
+        buildProgramIdKeyMap(supabaseUrl, supabaseKey),
+        buildMasterProgramMap(supabaseUrl, supabaseKey),
+    ]);
+    // Track master programs not found in dim_master_program
+    const unknownMasterPrograms = new Set();
+    // -------------------------------------------------------------------------
+    // 4. Build insert rows
+    // -------------------------------------------------------------------------
+    const insertRows = [];
+    for (const [, group] of groups) {
+        const masterDim = masterProgramMap.get(group.masterProgram);
+        if (!masterDim) {
+            unknownMasterPrograms.add(group.masterProgram);
+        }
+        const trgidCount = group.trgidSet.size;
+        if (trgidCount === 0)
+            continue;
+        insertRows.push({
+            source_file_name: sourceFileName,
+            loaded_at: loadedAt,
+            user_id: userId,
+            location: group.location,
+            master_program: group.masterProgram,
+            program_code: group.programCode,
+            program_id_key: programIdKeyMap.get(group.programCode) ?? null,
+            date: dateStr,
+            account_code: CHECKED_IN_ACCOUNT_CODE,
+            account_id: CHECKED_IN_ACCOUNT_ID,
+            // amount is TEXT in stg_financials_raw — store as string
+            amount: String(trgidCount),
+            mode: 'actual',
+            master_program_id: masterDim?.master_program_id ?? null,
+            client_id: masterDim?.client_id ?? null,
+        });
+    }
+    if (unknownMasterPrograms.size > 0) {
+        warnings.push(`${unknownMasterPrograms.size} master program(s) not found in dim_master_program ` +
+            `(master_program_id and client_id will be NULL): ` +
+            [...unknownMasterPrograms].sort().join(', '));
+    }
+    // -------------------------------------------------------------------------
+    // 5. Insert in batches of CHUNK_SIZE
+    // -------------------------------------------------------------------------
+    let totalInserted = 0;
+    const batches = chunk(insertRows, CHUNK_SIZE);
+    for (const [i, batch] of batches.entries()) {
+        try {
+            const inserted = await insertBatch(supabaseUrl, supabaseKey, batch);
+            totalInserted += inserted;
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            throw new Error(`Batch ${i + 1}/${batches.length} insert failed after ${totalInserted} rows inserted: ${message}`);
+        }
+    }
+    // Suppress unused variable warning — sb is a valid Supabase client kept
+    // as a reference for future use (e.g. RPC calls). The dim lookups above
+    // use raw fetch for pagination control (no .range() on PostgREST URL).
+    void sb;
+    return {
+        sourceFileName,
+        date: dateStr,
+        totalRowsRead: totalRead,
+        rowsSkipped: skipped,
+        programGroupsFound: groups.size,
+        rowsInserted: totalInserted,
+        warnings,
+    };
+}

package/dist/lib/social/post-generator.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Social Post Generation Pipeline
+ *
+ * Ported from Python: ~/projects/newsletter-automation social post pipeline
+ *
+ * Pipeline: Groq AI generates post ideas -> Unsplash image search -> Strapi push
+ *
+ * Functions:
+ *   callGroq()            — call Groq API (OpenAI-compatible) for AI content
+ *   searchUnsplashImage() — search Unsplash NAPI for a stock photo URL
+ *   generateSocialPosts() — orchestrator: generate posts and push to Strapi
+ */
+import 'dotenv/config';
+export interface GeneratePostsOptions {
+    brand: string;
+    /** Number of posts to generate (default: 9) */
+    count?: number;
+    /** Week start date in YYYY-MM-DD format */
+    weekOf?: string;
+    /** Platforms to target (default: ['instagram', 'facebook']) */
+    platforms?: string[];
+    /** Generate but do not push to Strapi */
+    dryRun?: boolean;
+}
+export interface SocialPostData {
+    headline: string;
+    body: string;
+    cta_text: string;
+    cta_url: string;
+    image_url: string | null;
+    overlay_style: 'dark-bottom' | 'brand-bottom' | 'brand-full' | 'dark-full';
+    template: string;
+    platform: string;
+    brand: string;
+    scheduled_date: string;
+    delivery_status: 'pending';
+}
+export interface GeneratePostsResult {
+    brand: string;
+    postsCreated: number;
+    posts: Array<{
+        documentId: string;
+        headline: string;
+        platform: string;
+        scheduled_date: string;
+    }>;
+    errors: string[];
+}
+/**
+ * Call the Groq API (OpenAI-compatible) and return the assistant's response text.
+ *
+ * @example
+ *   const response = await callGroq('You are a copywriter.', 'Write a tagline.')
+ */
+export declare function callGroq(systemPrompt: string, userPrompt: string): Promise<string>;
+/**
+ * Search Unsplash NAPI for a themed stock photo URL.
+ * Returns the `.results[0].urls.regular` URL, or null if not found.
+ *
+ * Note: Uses the public NAPI endpoint — no auth required but may be rate-limited.
+ *
+ * @example
+ *   const url = await searchUnsplashImage('life insurance family protection')
+ */
+export declare function searchUnsplashImage(query: string): Promise<string | null>;
+/**
+ * Main orchestrator: generate AI-powered social media posts and push to Strapi.
+ *
+ * Steps:
+ *   1. Call Groq to generate post ideas as JSON
+ *   2. For each post, search Unsplash for a themed image
+ *   3. Build SocialPostData and push to Strapi via POST /api/social-posts
+ *   4. Return summary of created posts and any errors
+ *
+ * @example
+ *   const result = await generateSocialPosts({
+ *     brand: 'LIFEINSUR',
+ *     count: 9,
+ *     weekOf: '2026-03-02',
+ *   })
+ *   console.log(`Created ${result.postsCreated} posts`)
+ */
+export declare function generateSocialPosts(opts: GeneratePostsOptions): Promise<GeneratePostsResult>;