optimal-cli 0.1.0 → 1.0.1

package/dist/lib/format.js

@@ -0,0 +1,98 @@
+/**
+ * Lightweight CLI output formatting — ANSI colors, tables, badges.
+ * Zero external dependencies. Respects NO_COLOR env var.
+ */
+// ── ANSI escape codes ───────────────────────────────────────────────
+const CODES = {
+    red: [31, 39],
+    green: [32, 39],
+    yellow: [33, 39],
+    blue: [34, 39],
+    cyan: [36, 39],
+    gray: [90, 39],
+    bold: [1, 22],
+    dim: [2, 22],
+};
+/**
+ * Wrap text in ANSI escape codes for the given color/style.
+ * Returns plain text when NO_COLOR env var is set.
+ */
+export function colorize(text, color) {
+    if (process.env.NO_COLOR !== undefined)
+        return text;
+    const [open, close] = CODES[color];
+    return `\x1b[${open}m${text}\x1b[${close}m`;
+}
+// ── Table rendering ─────────────────────────────────────────────────
+/** Strip ANSI escape sequences to measure visible string width. */
+function stripAnsi(s) {
+    return s.replace(/\x1b\[\d+m/g, '');
+}
+/**
+ * Render a bordered ASCII table with auto-sized columns.
+ * Headers are rendered in bold.
+ */
+export function table(headers, rows) {
+    // Compute column widths from headers and all rows
+    const colWidths = headers.map((h, i) => {
+        let max = stripAnsi(h).length;
+        for (const row of rows) {
+            const cell = row[i] ?? '';
+            const len = stripAnsi(cell).length;
+            if (len > max)
+                max = len;
+        }
+        return max;
+    });
+    function padCell(cell, width) {
+        const visible = stripAnsi(cell).length;
+        return cell + ' '.repeat(Math.max(0, width - visible));
+    }
+    const sep = '+-' + colWidths.map(w => '-'.repeat(w)).join('-+-') + '-+';
+    const headerRow = '| ' + headers.map((h, i) => padCell(colorize(h, 'bold'), colWidths[i])).join(' | ') + ' |';
+    const bodyRows = rows.map(row => '| ' + row.map((cell, i) => padCell(cell ?? '', colWidths[i])).join(' | ') + ' |');
+    return [sep, headerRow, sep, ...bodyRows, sep].join('\n');
+}
+// ── Status & priority badges ────────────────────────────────────────
+const STATUS_COLORS = {
+    done: 'green',
+    in_progress: 'blue',
+    blocked: 'red',
+    ready: 'cyan',
+    backlog: 'gray',
+    cancelled: 'dim',
+    review: 'yellow',
+};
+/** Return a colored status string (e.g. "done" in green). */
+export function statusBadge(status) {
+    const color = STATUS_COLORS[status] ?? 'dim';
+    return colorize(status, color);
+}
+const PRIORITY_COLORS = {
+    1: 'red',
+    2: 'yellow',
+    3: 'blue',
+    4: 'gray',
+};
+/** Return a colored priority label (e.g. "P1" in red). */
+export function priorityBadge(p) {
+    const color = PRIORITY_COLORS[p] ?? 'gray';
+    return colorize(`P${p}`, color);
+}
+// ── Logging helpers ─────────────────────────────────────────────────
+/** Print a green success message with a check mark prefix. */
+export function success(msg) {
+    console.log(`${colorize('\u2713', 'green')} ${msg}`);
+}
+/** Print a red error message with an X prefix. */
+export function error(msg) {
+    console.error(`${colorize('\u2717', 'red')} ${msg}`);
+}
+/** Print a yellow warning message with a warning prefix. */
+export function warn(msg) {
+    console.warn(`${colorize('\u26a0', 'yellow')} ${msg}`);
+}
+/** Print a blue info message with an info prefix. */
+export function info(msg) {
+    console.log(`${colorize('\u2139', 'blue')} ${msg}`);
+}

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

@@ -0,0 +1,37 @@
+export interface ValidationResult {
+    valid: boolean;
+    errors: string[];
+}
+export interface BatchValidationResult {
+    totalRows: number;
+    validRows: number;
+    invalidRows: number;
+    errors: Array<{
+        row: number;
+        errors: string[];
+    }>;
+}
+/**
+ * Validate a single row destined for `stg_financials_raw`.
+ *
+ * Checks:
+ * - Required fields: client, program, account_code, amount, period
+ * - `amount` is numeric (the DB column is TEXT, so non-numeric strings are a common bug)
+ * - `period` matches YYYY-MM format
+ */
+export declare function validateFinancialRow(row: Record<string, unknown>): ValidationResult;
+/**
+ * Validate a batch of rows destined for `stg_financials_raw`.
+ *
+ * Runs `validateFinancialRow` on each row and aggregates results.
+ */
+export declare function validateBatch(rows: Record<string, unknown>[]): BatchValidationResult;
+/**
+ * Validate a single row destined for `confirmed_income_statements`.
+ *
+ * Checks:
+ * - Required fields: account_id, client_id, amount, period, source
+ * - `amount` is numeric
+ * - `period` matches YYYY-MM format
+ */
+export declare function validateIncomeStatementRow(row: Record<string, unknown>): ValidationResult;

package/dist/lib/returnpro/validate.js

@@ -0,0 +1,124 @@
+// ---------------------------------------------------------------------------
+// ReturnPro data validation
+// ---------------------------------------------------------------------------
+//
+// Pre-insert validators for stg_financials_raw and confirmed_income_statements.
+// No external dependencies — pure TypeScript, no Supabase calls.
+// ---------------------------------------------------------------------------
+// --- Constants ---
+/** Required fields for a stg_financials_raw row. */
+const FINANCIAL_REQUIRED_FIELDS = ['client', 'program', 'account_code', 'amount', 'period'];
+/** Required fields for a confirmed_income_statements row. */
+const INCOME_REQUIRED_FIELDS = ['account_id', 'client_id', 'amount', 'period', 'source'];
+/** Matches YYYY-MM format (e.g. "2025-04"). */
+const PERIOD_REGEX = /^\d{4}-(0[1-9]|1[0-2])$/;
+// --- Helpers ---
+/**
+ * Check whether a value is present (not null, undefined, or empty string).
+ */
+function isPresent(value) {
+    if (value === null || value === undefined)
+        return false;
+    if (typeof value === 'string' && value.trim() === '')
+        return false;
+    return true;
+}
+/**
+ * Check whether a value can be parsed as a finite number.
+ * Accepts numbers and numeric strings. Rejects NaN, Infinity, empty strings.
+ */
+function isNumeric(value) {
+    if (typeof value === 'number')
+        return isFinite(value);
+    if (typeof value === 'string') {
+        const trimmed = value.trim();
+        if (trimmed === '')
+            return false;
+        const parsed = Number(trimmed);
+        return isFinite(parsed);
+    }
+    return false;
+}
+// --- Core validators ---
+/**
+ * Validate a single row destined for `stg_financials_raw`.
+ *
+ * Checks:
+ * - Required fields: client, program, account_code, amount, period
+ * - `amount` is numeric (the DB column is TEXT, so non-numeric strings are a common bug)
+ * - `period` matches YYYY-MM format
+ */
+export function validateFinancialRow(row) {
+    const errors = [];
+    // Check required fields
+    for (const field of FINANCIAL_REQUIRED_FIELDS) {
+        if (!isPresent(row[field])) {
+            errors.push(`Missing required field: ${field}`);
+        }
+    }
+    // Validate amount is numeric (only if present, to avoid duplicate error)
+    if (isPresent(row.amount) && !isNumeric(row.amount)) {
+        errors.push(`amount must be numeric, got: ${JSON.stringify(row.amount)}`);
+    }
+    // Validate period format (only if present)
+    if (isPresent(row.period)) {
+        const period = String(row.period).trim();
+        if (!PERIOD_REGEX.test(period)) {
+            errors.push(`period must be YYYY-MM format (e.g. "2025-04"), got: "${period}"`);
+        }
+    }
+    return { valid: errors.length === 0, errors };
+}
+/**
+ * Validate a batch of rows destined for `stg_financials_raw`.
+ *
+ * Runs `validateFinancialRow` on each row and aggregates results.
+ */
+export function validateBatch(rows) {
+    const batchErrors = [];
+    let validRows = 0;
+    for (let i = 0; i < rows.length; i++) {
+        const result = validateFinancialRow(rows[i]);
+        if (result.valid) {
+            validRows++;
+        }
+        else {
+            batchErrors.push({ row: i, errors: result.errors });
+        }
+    }
+    return {
+        totalRows: rows.length,
+        validRows,
+        invalidRows: rows.length - validRows,
+        errors: batchErrors,
+    };
+}
+/**
+ * Validate a single row destined for `confirmed_income_statements`.
+ *
+ * Checks:
+ * - Required fields: account_id, client_id, amount, period, source
+ * - `amount` is numeric
+ * - `period` matches YYYY-MM format
+ */
+export function validateIncomeStatementRow(row) {
+    const errors = [];
+    // Check required fields
+    for (const field of INCOME_REQUIRED_FIELDS) {
+        if (!isPresent(row[field])) {
+            errors.push(`Missing required field: ${field}`);
+        }
+    }
+    // Validate amount is numeric (only if present)
+    if (isPresent(row.amount) && !isNumeric(row.amount)) {
+        errors.push(`amount must be numeric, got: ${JSON.stringify(row.amount)}`);
+    }
+    // Validate period format (only if present)
+    if (isPresent(row.period)) {
+        const period = String(row.period).trim();
+        if (!PERIOD_REGEX.test(period)) {
+            errors.push(`period must be YYYY-MM format (e.g. "2025-04"), got: "${period}"`);
+        }
+    }
+    return { valid: errors.length === 0, errors };
+}

package/dist/lib/social/meta.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Meta Graph API — Instagram Content Publishing
+ *
+ * Direct Instagram publishing via Meta's Content Publishing API.
+ * Replaces n8n webhook intermediary for IG posts.
+ *
+ * Functions:
+ *   publishIgPhoto()     — Publish a single image post to Instagram
+ *   publishIgCarousel()  — Publish a carousel (multi-image) post to Instagram
+ *   getMetaConfig()      — Read Meta credentials from env vars
+ *   getMetaConfigForBrand() — Read brand-specific Meta credentials
+ */
+export interface MetaConfig {
+    accessToken: string;
+    igAccountId: string;
+}
+export interface PublishIgResult {
+    containerId: string;
+    mediaId: string;
+}
+export interface PublishIgPhotoOptions {
+    imageUrl: string;
+    caption: string;
+}
+export interface CarouselItem {
+    imageUrl: string;
+}
+export interface PublishIgCarouselOptions {
+    caption: string;
+    items: CarouselItem[];
+}
+export declare class MetaApiError extends Error {
+    status: number;
+    metaError?: {
+        message: string;
+        type?: string;
+        code?: number;
+    } | undefined;
+    constructor(message: string, status: number, metaError?: {
+        message: string;
+        type?: string;
+        code?: number;
+    } | undefined);
+}
+export declare function setFetchForTests(fn: typeof globalThis.fetch): void;
+export declare function resetFetchForTests(): void;
+/**
+ * Read Meta API credentials from environment variables.
+ * Requires: META_ACCESS_TOKEN, META_IG_ACCOUNT_ID
+ */
+export declare function getMetaConfig(): MetaConfig;
+/**
+ * Read Meta API credentials for a specific brand.
+ * Looks for META_IG_ACCOUNT_ID_{BRAND} first, falls back to META_IG_ACCOUNT_ID.
+ * Brand key is normalized: hyphens become underscores (CRE-11TRUST → CRE_11TRUST).
+ */
+export declare function getMetaConfigForBrand(brand: string): MetaConfig;
+/**
+ * Publish a single photo to Instagram.
+ *
+ * Two-step process per Meta Content Publishing API:
+ * 1. Create media container with image_url + caption
+ * 2. Publish the container
+ *
+ * @example
+ *   const result = await publishIgPhoto(config, {
+ *     imageUrl: 'https://cdn.example.com/photo.jpg',
+ *     caption: 'Check out our latest listing! #realestate',
+ *   })
+ *   console.log(`Published: ${result.mediaId}`)
+ */
+export declare function publishIgPhoto(config: MetaConfig, opts: PublishIgPhotoOptions): Promise<PublishIgResult>;
+/**
+ * Publish a carousel (multi-image) post to Instagram.
+ *
+ * Three-step process:
+ * 1. Create individual item containers (is_carousel_item=true)
+ * 2. Create carousel container referencing all item IDs
+ * 3. Publish the carousel container
+ *
+ * @example
+ *   const result = await publishIgCarousel(config, {
+ *     caption: 'Property tour highlights',
+ *     items: [
+ *       { imageUrl: 'https://cdn.example.com/1.jpg' },
+ *       { imageUrl: 'https://cdn.example.com/2.jpg' },
+ *     ],
+ *   })
+ */
+export declare function publishIgCarousel(config: MetaConfig, opts: PublishIgCarouselOptions): Promise<PublishIgResult>;

package/dist/lib/social/meta.js

@@ -0,0 +1,160 @@
+/**
+ * Meta Graph API — Instagram Content Publishing
+ *
+ * Direct Instagram publishing via Meta's Content Publishing API.
+ * Replaces n8n webhook intermediary for IG posts.
+ *
+ * Functions:
+ *   publishIgPhoto()     — Publish a single image post to Instagram
+ *   publishIgCarousel()  — Publish a carousel (multi-image) post to Instagram
+ *   getMetaConfig()      — Read Meta credentials from env vars
+ *   getMetaConfigForBrand() — Read brand-specific Meta credentials
+ */
+export class MetaApiError extends Error {
+    status;
+    metaError;
+    constructor(message, status, metaError) {
+        super(message);
+        this.status = status;
+        this.metaError = metaError;
+        this.name = 'MetaApiError';
+    }
+}
+// ── Config ───────────────────────────────────────────────────────────
+const GRAPH_API_BASE = 'https://graph.facebook.com/v21.0';
+// Injectable fetch for testing
+let _fetch = globalThis.fetch;
+export function setFetchForTests(fn) {
+    _fetch = fn;
+}
+export function resetFetchForTests() {
+    _fetch = globalThis.fetch;
+}
+// ── Internal helpers ─────────────────────────────────────────────────
+async function graphPost(path, body) {
+    const res = await _fetch(`${GRAPH_API_BASE}${path}`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(body),
+    });
+    const data = await res.json();
+    if (!res.ok) {
+        const err = data.error;
+        throw new MetaApiError(err?.message ?? `Meta API ${res.status}: ${res.statusText}`, res.status, err ? { message: err.message ?? '', type: err.type, code: err.code } : undefined);
+    }
+    return data;
+}
+// ── Config readers ───────────────────────────────────────────────────
+/**
+ * Read Meta API credentials from environment variables.
+ * Requires: META_ACCESS_TOKEN, META_IG_ACCOUNT_ID
+ */
+export function getMetaConfig() {
+    const accessToken = process.env.META_ACCESS_TOKEN;
+    const igAccountId = process.env.META_IG_ACCOUNT_ID;
+    if (!accessToken) {
+        throw new Error('Missing env var: META_ACCESS_TOKEN\n' +
+            'Get a long-lived page access token from Meta Business Suite:\n' +
+            '  https://business.facebook.com/settings/system-users');
+    }
+    if (!igAccountId) {
+        throw new Error('Missing env var: META_IG_ACCOUNT_ID\n' +
+            'Find your IG Business account ID via Graph API Explorer:\n' +
+            '  GET /me/accounts → page_id → GET /{page_id}?fields=instagram_business_account');
+    }
+    return { accessToken, igAccountId };
+}
+/**
+ * Read Meta API credentials for a specific brand.
+ * Looks for META_IG_ACCOUNT_ID_{BRAND} first, falls back to META_IG_ACCOUNT_ID.
+ * Brand key is normalized: hyphens become underscores (CRE-11TRUST → CRE_11TRUST).
+ */
+export function getMetaConfigForBrand(brand) {
+    const accessToken = process.env.META_ACCESS_TOKEN;
+    if (!accessToken) {
+        throw new Error('Missing env var: META_ACCESS_TOKEN');
+    }
+    const envKey = `META_IG_ACCOUNT_ID_${brand.replace(/-/g, '_')}`;
+    const igAccountId = process.env[envKey] ?? process.env.META_IG_ACCOUNT_ID;
+    if (!igAccountId) {
+        throw new Error(`Missing env var: ${envKey} or META_IG_ACCOUNT_ID`);
+    }
+    return { accessToken, igAccountId };
+}
+// ── Publishing ───────────────────────────────────────────────────────
+/**
+ * Publish a single photo to Instagram.
+ *
+ * Two-step process per Meta Content Publishing API:
+ * 1. Create media container with image_url + caption
+ * 2. Publish the container
+ *
+ * @example
+ *   const result = await publishIgPhoto(config, {
+ *     imageUrl: 'https://cdn.example.com/photo.jpg',
+ *     caption: 'Check out our latest listing! #realestate',
+ *   })
+ *   console.log(`Published: ${result.mediaId}`)
+ */
+export async function publishIgPhoto(config, opts) {
+    // Step 1: Create media container
+    const container = await graphPost(`/${config.igAccountId}/media`, {
+        image_url: opts.imageUrl,
+        caption: opts.caption,
+        access_token: config.accessToken,
+    });
+    // Step 2: Publish the container
+    const published = await graphPost(`/${config.igAccountId}/media_publish`, {
+        creation_id: container.id,
+        access_token: config.accessToken,
+    });
+    return {
+        containerId: container.id,
+        mediaId: published.id,
+    };
+}
+/**
+ * Publish a carousel (multi-image) post to Instagram.
+ *
+ * Three-step process:
+ * 1. Create individual item containers (is_carousel_item=true)
+ * 2. Create carousel container referencing all item IDs
+ * 3. Publish the carousel container
+ *
+ * @example
+ *   const result = await publishIgCarousel(config, {
+ *     caption: 'Property tour highlights',
+ *     items: [
+ *       { imageUrl: 'https://cdn.example.com/1.jpg' },
+ *       { imageUrl: 'https://cdn.example.com/2.jpg' },
+ *     ],
+ *   })
+ */
+export async function publishIgCarousel(config, opts) {
+    // Step 1: Create individual item containers
+    const itemIds = [];
+    for (const item of opts.items) {
+        const container = await graphPost(`/${config.igAccountId}/media`, {
+            image_url: item.imageUrl,
+            is_carousel_item: true,
+            access_token: config.accessToken,
+        });
+        itemIds.push(container.id);
+    }
+    // Step 2: Create carousel container
+    const carousel = await graphPost(`/${config.igAccountId}/media`, {
+        media_type: 'CAROUSEL',
+        children: itemIds,
+        caption: opts.caption,
+        access_token: config.accessToken,
+    });
+    // Step 3: Publish
+    const published = await graphPost(`/${config.igAccountId}/media_publish`, {
+        creation_id: carousel.id,
+        access_token: config.accessToken,
+    });
+    return {
+        containerId: carousel.id,
+        mediaId: published.id,
+    };
+}