optimal-cli 0.1.0

package/dist/lib/social/post-generator.js

@@ -0,0 +1,333 @@
+/**
+ * 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';
+import { strapiPost } from '../cms/strapi-client.js';
+// ── Constants ────────────────────────────────────────────────────────
+const OVERLAY_STYLES = [
+    'dark-bottom',
+    'brand-bottom',
+    'brand-full',
+    'dark-full',
+];
+const BRAND_CONFIGS = {
+    'CRE-11TRUST': {
+        displayName: 'ElevenTrust Commercial Real Estate',
+        ctaUrl: 'https://eleventrust.com',
+        industry: 'commercial real estate in South Florida',
+    },
+    'LIFEINSUR': {
+        displayName: 'Anchor Point Insurance Co.',
+        ctaUrl: 'https://anchorpointinsurance.com',
+        industry: 'life insurance and financial protection',
+    },
+};
+// ── Environment helper ───────────────────────────────────────────────
+function requireEnv(name) {
+    const val = process.env[name];
+    if (!val)
+        throw new Error(`Missing env var: ${name}`);
+    return val;
+}
+// ── 1. Groq API Call ─────────────────────────────────────────────────
+/**
+ * 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 async function callGroq(systemPrompt, userPrompt) {
+    const apiKey = requireEnv('GROQ_API_KEY');
+    const model = process.env.GROQ_MODEL ?? 'llama-3.3-70b-versatile';
+    const messages = [
+        { role: 'system', content: systemPrompt },
+        { role: 'user', content: userPrompt },
+    ];
+    const response = await fetch('https://api.groq.com/openai/v1/chat/completions', {
+        method: 'POST',
+        headers: {
+            Authorization: `Bearer ${apiKey}`,
+            'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({
+            model,
+            messages,
+            temperature: 0.8,
+        }),
+    });
+    const data = await response.json();
+    if (!data.choices || data.choices.length === 0) {
+        throw new Error(`Groq error: ${JSON.stringify(data.error ?? data)}`);
+    }
+    return data.choices[0].message.content;
+}
+// ── 2. Unsplash Image Search ─────────────────────────────────────────
+/**
+ * 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 async function searchUnsplashImage(query) {
+    try {
+        const encodedQuery = encodeURIComponent(query);
+        const response = await fetch(`https://unsplash.com/napi/search/photos?query=${encodedQuery}&per_page=3`, {
+            headers: {
+                'User-Agent': 'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36',
+                Accept: 'application/json',
+            },
+        });
+        if (!response.ok) {
+            console.warn(`   [Unsplash] HTTP ${response.status} for query: "${query}"`);
+            return null;
+        }
+        const data = await response.json();
+        const url = data.results?.[0]?.urls?.regular ?? null;
+        if (!url) {
+            console.warn(`   [Unsplash] No results for query: "${query}"`);
+        }
+        return url;
+    }
+    catch (err) {
+        console.warn(`   [Unsplash] Error searching for "${query}": ${err.message}`);
+        return null;
+    }
+}
+// ── 3. Build Weekly Schedule ─────────────────────────────────────────
+/**
+ * Distribute post dates across a week (Mon-Fri + weekend for overflow).
+ * Returns an array of ISO date strings (YYYY-MM-DD).
+ */
+function buildWeeklySchedule(weekOf, count) {
+    const start = new Date(weekOf);
+    // Ensure we start from Monday — find the Monday of the given week
+    const dayOfWeek = start.getDay(); // 0=Sun, 1=Mon, ..., 6=Sat
+    const daysToMonday = dayOfWeek === 0 ? -6 : 1 - dayOfWeek;
+    start.setDate(start.getDate() + daysToMonday);
+    // Build Mon-Sun sequence (7 days)
+    const weekDays = [];
+    for (let i = 0; i < 7; i++) {
+        const d = new Date(start);
+        d.setDate(start.getDate() + i);
+        weekDays.push(d.toISOString().slice(0, 10));
+    }
+    // Fill schedule: Mon-Fri first, then Sat-Sun for overflow
+    const schedule = [];
+    const weekdaySlots = weekDays.slice(0, 5); // Mon-Fri
+    const weekendSlots = weekDays.slice(5); // Sat-Sun
+    for (let i = 0; i < count; i++) {
+        if (i < weekdaySlots.length) {
+            schedule.push(weekdaySlots[i]);
+        }
+        else {
+            // Overflow into weekend, then repeat weekdays
+            const overflowSlots = [...weekendSlots, ...weekdaySlots];
+            schedule.push(overflowSlots[(i - weekdaySlots.length) % overflowSlots.length]);
+        }
+    }
+    return schedule;
+}
+// ── 4. Build AI Prompts ──────────────────────────────────────────────
+function buildSystemPrompt(brand) {
+    const config = BRAND_CONFIGS[brand];
+    const displayName = config?.displayName ?? brand;
+    const industry = config?.industry ?? 'professional services';
+    return `You are an expert social media copywriter specializing in ${industry} for ${displayName}.
+
+Your task is to generate engaging, conversion-focused social media ad posts. Each post must:
+- Hook the viewer in the first line (no generic openers)
+- Speak to a specific pain point or aspiration
+- Include a clear, action-oriented CTA
+- Be authentic and avoid jargon
+- Be appropriate for paid social advertising (Instagram and Facebook)
+
+Always respond with ONLY valid JSON — no markdown fences, no explanations, no extra text.`;
+}
+function buildUserPrompt(brand, platforms, weekStart, count) {
+    const config = BRAND_CONFIGS[brand];
+    const displayName = config?.displayName ?? brand;
+    const ctaUrl = config?.ctaUrl ?? 'https://example.com';
+    const industry = config?.industry ?? 'professional services';
+    return `Generate ${count} social media ad posts for ${displayName} (brand: ${brand}).
+
+Target platforms: ${platforms.join(', ')}
+Week of: ${weekStart}
+Industry: ${industry}
+CTA URL: ${ctaUrl}
+
+Return a JSON array of exactly ${count} post objects. Each object must have these exact fields:
+- "headline": string — attention-grabbing first line (max 60 chars)
+- "body": string — 2-4 sentence post copy (max 280 chars)
+- "cta_text": string — button label (e.g., "Get a Free Quote", "Learn More", "Schedule a Call")
+- "cta_url": string — full URL for the CTA
+- "image_search_query": string — 3-5 keyword search string to find a relevant stock photo on Unsplash
+- "overlay_style": string — one of: "dark-bottom", "brand-bottom", "brand-full", "dark-full"
+- "template": string — one of: "standard", "quote", "offer", "testimonial", "educational"
+
+Vary the templates, tones, and angles across the ${count} posts. Mix benefit-focused, story-driven, and urgency-based approaches.
+
+Return ONLY the JSON array, no other text.`;
+}
+// ── 5. Parse AI Response ─────────────────────────────────────────────
+function parseAiPostIdeas(raw) {
+    let content = raw.trim();
+    // Strip markdown fences if present
+    if (content.startsWith('```')) {
+        const firstNewline = content.indexOf('\n');
+        content = firstNewline !== -1 ? content.slice(firstNewline + 1) : content.slice(3);
+    }
+    if (content.endsWith('```')) {
+        content = content.slice(0, -3).trim();
+    }
+    const parsed = JSON.parse(content);
+    if (!Array.isArray(parsed)) {
+        throw new Error('AI response is not a JSON array');
+    }
+    return parsed;
+}
+// ── 6. Orchestrator ──────────────────────────────────────────────────
+/**
+ * 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 async function generateSocialPosts(opts) {
+    const { brand, count = 9, weekOf = new Date().toISOString().slice(0, 10), platforms = ['instagram', 'facebook'], dryRun = false, } = opts;
+    const config = BRAND_CONFIGS[brand];
+    const displayName = config?.displayName ?? brand;
+    console.log('='.repeat(60));
+    console.log(`SOCIAL POST GENERATOR — ${displayName}`);
+    console.log('='.repeat(60));
+    console.log(`Brand: ${brand}`);
+    console.log(`Count: ${count}`);
+    console.log(`Week of: ${weekOf}`);
+    console.log(`Platforms: ${platforms.join(', ')}`);
+    if (dryRun)
+        console.log('DRY RUN — will not push to Strapi');
+    const result = {
+        brand,
+        postsCreated: 0,
+        posts: [],
+        errors: [],
+    };
+    // Step 1: Generate post ideas via Groq
+    console.log(`\n1. Calling Groq to generate ${count} post ideas...`);
+    let postIdeas;
+    try {
+        const systemPrompt = buildSystemPrompt(brand);
+        const userPrompt = buildUserPrompt(brand, platforms, weekOf, count);
+        const raw = await callGroq(systemPrompt, userPrompt);
+        postIdeas = parseAiPostIdeas(raw);
+        console.log(`   Generated ${postIdeas.length} post ideas`);
+    }
+    catch (err) {
+        const msg = `Failed to generate post ideas: ${err.message}`;
+        console.error(`   ERROR: ${msg}`);
+        result.errors.push(msg);
+        return result;
+    }
+    // Step 2: Build weekly schedule
+    const schedule = buildWeeklySchedule(weekOf, count);
+    console.log(`\n2. Scheduling posts: ${schedule[0]} → ${schedule[schedule.length - 1]}`);
+    // Step 3: Process each post idea
+    console.log(`\n3. Processing ${postIdeas.length} posts (image search + Strapi push)...`);
+    for (let i = 0; i < postIdeas.length; i++) {
+        const idea = postIdeas[i];
+        const platform = platforms[i % platforms.length];
+        const scheduled_date = schedule[i] ?? schedule[schedule.length - 1];
+        const overlay_style = OVERLAY_STYLES[i % OVERLAY_STYLES.length];
+        console.log(`\n   [${i + 1}/${postIdeas.length}] "${idea.headline}"`);
+        console.log(`   Platform: ${platform} | Date: ${scheduled_date}`);
+        // Search Unsplash for image
+        let image_url = null;
+        if (idea.image_search_query) {
+            console.log(`   Searching Unsplash: "${idea.image_search_query}"`);
+            image_url = await searchUnsplashImage(idea.image_search_query);
+            if (image_url) {
+                console.log(`   Image found: ${image_url.slice(0, 60)}...`);
+            }
+            else {
+                console.log(`   No image found — posting without image`);
+            }
+        }
+        // Build post data
+        const postData = {
+            headline: idea.headline,
+            body: idea.body,
+            cta_text: idea.cta_text,
+            cta_url: idea.cta_url,
+            image_url,
+            overlay_style: idea.overlay_style ?? overlay_style,
+            template: idea.template ?? 'standard',
+            platform,
+            brand,
+            scheduled_date,
+            delivery_status: 'pending',
+        };
+        // Push to Strapi (unless dry run)
+        if (dryRun) {
+            console.log(`   DRY RUN — would create post in Strapi`);
+            result.posts.push({
+                documentId: `dry-run-${i + 1}`,
+                headline: postData.headline,
+                platform: postData.platform,
+                scheduled_date: postData.scheduled_date,
+            });
+            result.postsCreated++;
+        }
+        else {
+            try {
+                const created = await strapiPost('/api/social-posts', postData);
+                const documentId = created.documentId ?? 'unknown';
+                console.log(`   Created in Strapi (documentId: ${documentId})`);
+                result.posts.push({
+                    documentId,
+                    headline: postData.headline,
+                    platform: postData.platform,
+                    scheduled_date: postData.scheduled_date,
+                });
+                result.postsCreated++;
+            }
+            catch (err) {
+                const msg = `Failed to create post "${idea.headline}": ${err.message}`;
+                console.error(`   ERROR: ${msg}`);
+                result.errors.push(msg);
+            }
+        }
+    }
+    // Summary
+    console.log('\n' + '='.repeat(60));
+    console.log(`DONE! Created ${result.postsCreated}/${count} posts`);
+    if (result.errors.length > 0) {
+        console.log(`Errors (${result.errors.length}):`);
+        for (const e of result.errors) {
+            console.log(`  - ${e}`);
+        }
+    }
+    console.log('='.repeat(60));
+    return result;
+}

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

@@ -0,0 +1,66 @@
+/**
+ * Social Post Publisher
+ *
+ * Handles publishing social posts from Strapi to platforms via n8n webhooks,
+ * with delivery status tracking written back to Strapi.
+ *
+ * Functions:
+ *   publishSocialPosts()  — Main orchestrator: fetch pending posts, publish to Strapi,
+ *                           trigger n8n webhook, update delivery_status
+ *   getPublishQueue()     — List posts ready to publish (pending + has scheduled_date)
+ *   retryFailed()         — Re-attempt posts with delivery_status = 'failed'
+ */
+import 'dotenv/config';
+export interface PublishOptions {
+    brand: string;
+    /** Max posts to publish (default: all pending) */
+    limit?: number;
+    /** Preview without actually publishing */
+    dryRun?: boolean;
+}
+export interface QueuedPost {
+    documentId: string;
+    headline: string;
+    platform: string;
+    brand: string;
+    scheduled_date: string;
+}
+export interface PublishResult {
+    published: number;
+    failed: number;
+    skipped: number;
+    details: Array<{
+        documentId: string;
+        headline: string;
+        status: 'published' | 'failed' | 'skipped';
+        error?: string;
+    }>;
+}
+/**
+ * Fetch pending social posts for a brand and publish them:
+ *   1. Publish in Strapi (set publishedAt)
+ *   2. Trigger n8n webhook
+ *   3. Update delivery_status to 'scheduled' (or 'failed' on error)
+ *
+ * @example
+ *   const result = await publishSocialPosts({ brand: 'LIFEINSUR', limit: 3 })
+ *   console.log(`Published: ${result.published}, Failed: ${result.failed}`)
+ */
+export declare function publishSocialPosts(opts: PublishOptions): Promise<PublishResult>;
+/**
+ * List posts ready to publish: delivery_status = 'pending' AND has a scheduled_date.
+ *
+ * @example
+ *   const queue = await getPublishQueue('LIFEINSUR')
+ *   queue.forEach(p => console.log(p.scheduled_date, p.headline))
+ */
+export declare function getPublishQueue(brand: string): Promise<QueuedPost[]>;
+/**
+ * Re-attempt publishing posts with delivery_status = 'failed'.
+ * Resets delivery_status to 'pending' on each post before re-processing.
+ *
+ * @example
+ *   const result = await retryFailed('LIFEINSUR')
+ *   console.log(`Re-published: ${result.published}, Still failing: ${result.failed}`)
+ */
+export declare function retryFailed(brand: string): Promise<PublishResult>;

package/dist/lib/social/publish.js

@@ -0,0 +1,226 @@
+/**
+ * Social Post Publisher
+ *
+ * Handles publishing social posts from Strapi to platforms via n8n webhooks,
+ * with delivery status tracking written back to Strapi.
+ *
+ * Functions:
+ *   publishSocialPosts()  — Main orchestrator: fetch pending posts, publish to Strapi,
+ *                           trigger n8n webhook, update delivery_status
+ *   getPublishQueue()     — List posts ready to publish (pending + has scheduled_date)
+ *   retryFailed()         — Re-attempt posts with delivery_status = 'failed'
+ */
+import 'dotenv/config';
+import { strapiGet, strapiPut, publish, } from '../cms/strapi-client.js';
+// ── Config ────────────────────────────────────────────────────────────
+function getN8nWebhookUrl() {
+    const url = process.env.N8N_WEBHOOK_URL;
+    if (!url) {
+        throw new Error('Missing env var: N8N_WEBHOOK_URL\n' +
+            'Set it in your .env file, e.g.:\n' +
+            '  N8N_WEBHOOK_URL=https://n8n.op-hub.com');
+    }
+    return url.replace(/\/+$/, '');
+}
+// ── Internal helpers ──────────────────────────────────────────────────
+/** Trigger n8n webhook for a single social post */
+async function triggerN8nWebhook(documentId, platform, brand) {
+    const baseUrl = getN8nWebhookUrl();
+    const webhookUrl = `${baseUrl}/webhook/social-post-publish`;
+    const res = await fetch(webhookUrl, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ documentId, platform, brand }),
+    });
+    if (!res.ok) {
+        let detail = `HTTP ${res.status}: ${res.statusText}`;
+        try {
+            const body = await res.text();
+            if (body)
+                detail += ` — ${body.slice(0, 200)}`;
+        }
+        catch {
+            // non-text body, ignore
+        }
+        throw new Error(`n8n webhook failed: ${detail}`);
+    }
+}
+/** Fetch social posts by brand + delivery_status from Strapi */
+async function fetchPostsByStatus(brand, deliveryStatus) {
+    const result = await strapiGet('/api/social-posts', {
+        'filters[brand][$eq]': brand,
+        'filters[delivery_status][$eq]': deliveryStatus,
+        'sort': 'scheduled_date:asc',
+        'pagination[pageSize]': '250',
+    });
+    return result.data;
+}
+/** Process a single post: publish in Strapi, trigger n8n, update status */
+async function processPost(post, dryRun) {
+    const documentId = post.documentId;
+    const headline = post.headline ?? '(no headline)';
+    const platform = post.platform ?? 'unknown';
+    const brand = post.brand ?? 'unknown';
+    if (dryRun) {
+        return { status: 'skipped' };
+    }
+    try {
+        // Step 1: Publish in Strapi (set publishedAt)
+        await publish('social-posts', documentId);
+        // Step 2: Trigger n8n webhook
+        try {
+            await triggerN8nWebhook(documentId, platform, brand);
+        }
+        catch (webhookErr) {
+            // Webhook failure: mark failed, but don't rethrow — continue to next post
+            const errMsg = webhookErr instanceof Error ? webhookErr.message : String(webhookErr);
+            await strapiPut('/api/social-posts', documentId, {
+                delivery_status: 'failed',
+                delivery_errors: [{ timestamp: new Date().toISOString(), error: errMsg }],
+            });
+            return { status: 'failed', error: errMsg };
+        }
+        // Step 3: Update delivery_status to 'scheduled' on success
+        await strapiPut('/api/social-posts', documentId, {
+            delivery_status: 'scheduled',
+        });
+        return { status: 'published' };
+    }
+    catch (err) {
+        const errMsg = err instanceof Error ? err.message : String(err);
+        // Best-effort status update on unexpected errors
+        try {
+            await strapiPut('/api/social-posts', documentId, {
+                delivery_status: 'failed',
+                delivery_errors: [{ timestamp: new Date().toISOString(), error: errMsg }],
+            });
+        }
+        catch {
+            // Ignore secondary failure — original error is more important
+        }
+        return { status: 'failed', error: errMsg };
+    }
+}
+// ── Core orchestrator ─────────────────────────────────────────────────
+/**
+ * Fetch pending social posts for a brand and publish them:
+ *   1. Publish in Strapi (set publishedAt)
+ *   2. Trigger n8n webhook
+ *   3. Update delivery_status to 'scheduled' (or 'failed' on error)
+ *
+ * @example
+ *   const result = await publishSocialPosts({ brand: 'LIFEINSUR', limit: 3 })
+ *   console.log(`Published: ${result.published}, Failed: ${result.failed}`)
+ */
+export async function publishSocialPosts(opts) {
+    const { brand, limit, dryRun = false } = opts;
+    // Validate n8n URL up front (unless dry run)
+    if (!dryRun) {
+        getN8nWebhookUrl();
+    }
+    const posts = await fetchPostsByStatus(brand, 'pending');
+    const postsToProcess = limit !== undefined ? posts.slice(0, limit) : posts;
+    const result = {
+        published: 0,
+        failed: 0,
+        skipped: 0,
+        details: [],
+    };
+    for (const post of postsToProcess) {
+        const documentId = post.documentId;
+        const headline = post.headline ?? '(no headline)';
+        const outcome = await processPost(post, dryRun);
+        if (outcome.status === 'published')
+            result.published++;
+        else if (outcome.status === 'failed')
+            result.failed++;
+        else
+            result.skipped++;
+        result.details.push({
+            documentId,
+            headline,
+            status: outcome.status,
+            ...(outcome.error !== undefined && { error: outcome.error }),
+        });
+    }
+    return result;
+}
+// ── Publish queue ─────────────────────────────────────────────────────
+/**
+ * List posts ready to publish: delivery_status = 'pending' AND has a scheduled_date.
+ *
+ * @example
+ *   const queue = await getPublishQueue('LIFEINSUR')
+ *   queue.forEach(p => console.log(p.scheduled_date, p.headline))
+ */
+export async function getPublishQueue(brand) {
+    const posts = await fetchPostsByStatus(brand, 'pending');
+    return posts
+        .filter((post) => {
+        const scheduledDate = post.scheduled_date;
+        return scheduledDate != null && scheduledDate !== '';
+    })
+        .map((post) => ({
+        documentId: post.documentId,
+        headline: post.headline ?? '(no headline)',
+        platform: post.platform ?? 'unknown',
+        brand: post.brand ?? brand,
+        scheduled_date: post.scheduled_date,
+    }));
+}
+// ── Retry failed ──────────────────────────────────────────────────────
+/**
+ * Re-attempt publishing posts with delivery_status = 'failed'.
+ * Resets delivery_status to 'pending' on each post before re-processing.
+ *
+ * @example
+ *   const result = await retryFailed('LIFEINSUR')
+ *   console.log(`Re-published: ${result.published}, Still failing: ${result.failed}`)
+ */
+export async function retryFailed(brand) {
+    // Validate n8n URL up front
+    getN8nWebhookUrl();
+    const posts = await fetchPostsByStatus(brand, 'failed');
+    const result = {
+        published: 0,
+        failed: 0,
+        skipped: 0,
+        details: [],
+    };
+    for (const post of posts) {
+        const documentId = post.documentId;
+        const headline = post.headline ?? '(no headline)';
+        // Reset to pending so processPost can re-publish cleanly
+        try {
+            await strapiPut('/api/social-posts', documentId, {
+                delivery_status: 'pending',
+                delivery_errors: null,
+            });
+        }
+        catch (err) {
+            const errMsg = err instanceof Error ? err.message : String(err);
+            result.failed++;
+            result.details.push({
+                documentId,
+                headline,
+                status: 'failed',
+                error: `Could not reset delivery_status: ${errMsg}`,
+            });
+            continue;
+        }
+        const outcome = await processPost(post, false);
+        if (outcome.status === 'published')
+            result.published++;
+        else if (outcome.status === 'failed')
+            result.failed++;
+        else
+            result.skipped++;
+        result.details.push({
+            documentId,
+            headline,
+            status: outcome.status,
+            ...(outcome.error !== undefined && { error: outcome.error }),
+        });
+    }
+    return result;
+}

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

@@ -0,0 +1,67 @@
+/**
+ * Meta Ad Library Scraper
+ *
+ * Ported from Python: ~/projects/meta-ad-scraper/scripts/meta_ad_scraper_v2.py
+ *
+ * Scrapes Facebook Ad Library for competitor ad intelligence.
+ * Uses Playwright headless Chromium with anti-detection measures.
+ * Splits ads by Library ID pattern, extracts metadata via regex.
+ *
+ * Functions:
+ *   buildUrl()              — construct Facebook Ad Library URL for a company
+ *   scrollAndLoad()         — auto-scroll page to load all ads (max 15 scrolls)
+ *   extractAds()            — two-stage extraction: DOM containers, then text split fallback
+ *   parseAdText()           — regex extraction of ad metadata from text blocks
+ *   extractLandingUrls()    — find landing page URLs from DOM links
+ *   scrapeCompany()         — orchestrate single company scrape
+ *   scrapeCompanies()       — batch-scrape multiple companies with configurable parallelism
+ *   formatCsv()             — convert ad records to CSV string
+ */
+import { type Page } from 'playwright';
+export interface AdRecord {
+    company_searched: string;
+    ad_id: string;
+    page_name: string;
+    ad_text: string;
+    status: string;
+    start_date: string;
+    impressions: string;
+    spend: string;
+    media_type: string;
+    platforms: string;
+    landing_page_url: string;
+    full_text_snippet: string;
+}
+export interface ScrapeOptions {
+    /** Companies to scrape */
+    companies: string[];
+    /** Output file path (if undefined, return results only) */
+    outputPath?: string;
+    /** Batch size for parallel processing (default: 6) */
+    batchSize?: number;
+    /** Maximum scrolls per page (default: 15) */
+    maxScrolls?: number;
+    /** Delay between companies in ms (default: 4000) */
+    companyDelay?: number;
+    /** Run headless (default: true) */
+    headless?: boolean;
+}
+export interface ScrapeResult {
+    ads: AdRecord[];
+    totalCompanies: number;
+    companiesScraped: number;
+    outputPath?: string;
+}
+export declare function buildUrl(companyName: string): string;
+export declare function scrollAndLoad(page: Page, maxScrolls?: number): Promise<void>;
+export declare function parseAdText(text: string, companyName: string): AdRecord | null;
+export declare function extractAds(page: Page, companyName: string, maxScrolls?: number): Promise<AdRecord[]>;
+export declare function extractLandingUrls(page: Page, adIds: string[]): Promise<Record<string, string>>;
+export declare function scrapeCompany(page: Page, companyName: string, maxScrolls?: number): Promise<AdRecord[]>;
+/**
+ * Scrape multiple companies in batches.
+ * Default: 6 companies per batch, 3 parallel batches (as documented in memory).
+ */
+export declare function scrapeCompanies(opts: ScrapeOptions): Promise<ScrapeResult>;
+/** Convert ad records to CSV string */
+export declare function formatCsv(ads: AdRecord[]): string;