@hybridlabor-api/bdb-antigravity-skills 1.0.0

package/skills/global_config/apify-lead-generation/reference/scripts/run_actor.js

@@ -0,0 +1,363 @@
+#!/usr/bin/env node
+/**
+ * Apify Actor Runner - Runs Apify actors and exports results.
+ *
+ * Usage:
+ *   # Quick answer (display in chat, no file saved)
+ *   node --env-file=.env scripts/run_actor.js --actor ACTOR_ID --input '{}'
+ *
+ *   # Export to file
+ *   node --env-file=.env scripts/run_actor.js --actor ACTOR_ID --input '{}' --output leads.csv --format csv
+ */
+
+import { parseArgs } from 'node:util';
+import { writeFileSync, statSync } from 'node:fs';
+
+// User-Agent for tracking skill usage in Apify analytics
+const USER_AGENT = 'apify-agent-skills/apify-lead-generation-1.1.11';
+
+// Parse command-line arguments
+function parseCliArgs() {
+    const options = {
+        actor: { type: 'string', short: 'a' },
+        input: { type: 'string', short: 'i' },
+        output: { type: 'string', short: 'o' },
+        format: { type: 'string', short: 'f', default: 'csv' },
+        timeout: { type: 'string', short: 't', default: '600' },
+        'poll-interval': { type: 'string', default: '5' },
+        help: { type: 'boolean', short: 'h' },
+    };
+
+    const { values } = parseArgs({ options, allowPositionals: false });
+
+    if (values.help) {
+        printHelp();
+        process.exit(0);
+    }
+
+    if (!values.actor) {
+        console.error('Error: --actor is required');
+        printHelp();
+        process.exit(1);
+    }
+
+    if (!values.input) {
+        console.error('Error: --input is required');
+        printHelp();
+        process.exit(1);
+    }
+
+    return {
+        actor: values.actor,
+        input: values.input,
+        output: values.output,
+        format: values.format || 'csv',
+        timeout: parseInt(values.timeout, 10),
+        pollInterval: parseInt(values['poll-interval'], 10),
+    };
+}
+
+function printHelp() {
+    console.log(`
+Apify Actor Runner - Run Apify actors and export results
+
+Usage:
+  node --env-file=.env scripts/run_actor.js --actor ACTOR_ID --input '{}'
+
+Options:
+  --actor, -a       Actor ID (e.g., compass/crawler-google-places) [required]
+  --input, -i       Actor input as JSON string [required]
+  --output, -o      Output file path (optional - if not provided, displays quick answer)
+  --format, -f      Output format: csv, json (default: csv)
+  --timeout, -t     Max wait time in seconds (default: 600)
+  --poll-interval   Seconds between status checks (default: 5)
+  --help, -h        Show this help message
+
+Output Formats:
+  JSON (all data)     --output file.json --format json
+  CSV (all data)      --output file.csv --format csv
+  Quick answer        (no --output) - displays top 5 in chat
+
+Examples:
+  # Quick answer - display top 5 in chat
+  node --env-file=.env scripts/run_actor.js \\
+    --actor "compass/crawler-google-places" \\
+    --input '{"searchStringsArray": ["coffee shops"], "locationQuery": "Seattle, USA"}'
+
+  # Export all data to CSV
+  node --env-file=.env scripts/run_actor.js \\
+    --actor "compass/crawler-google-places" \\
+    --input '{"searchStringsArray": ["coffee shops"], "locationQuery": "Seattle, USA"}' \\
+    --output leads.csv --format csv
+`);
+}
+
+// Start an actor run and return { runId, datasetId }
+async function startActor(token, actorId, inputJson) {
+    // Convert "author/actor" format to "author~actor" for API compatibility
+    const apiActorId = actorId.replace('/', '~');
+    const url = `https://api.apify.com/v2/acts/${apiActorId}/runs?token=${encodeURIComponent(token)}`;
+
+    let data;
+    try {
+        data = JSON.parse(inputJson);
+    } catch (e) {
+        console.error(`Error: Invalid JSON input: ${e.message}`);
+        process.exit(1);
+    }
+
+    const response = await fetch(url, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            'User-Agent': `${USER_AGENT}/start_actor`,
+        },
+        body: JSON.stringify(data),
+    });
+
+    if (response.status === 404) {
+        console.error(`Error: Actor '${actorId}' not found`);
+        process.exit(1);
+    }
+
+    if (!response.ok) {
+        const text = await response.text();
+        console.error(`Error: API request failed (${response.status}): ${text}`);
+        process.exit(1);
+    }
+
+    const result = await response.json();
+    return {
+        runId: result.data.id,
+        datasetId: result.data.defaultDatasetId,
+    };
+}
+
+// Poll run status until complete or timeout
+async function pollUntilComplete(token, runId, timeout, interval) {
+    const url = `https://api.apify.com/v2/actor-runs/${runId}?token=${encodeURIComponent(token)}`;
+    const startTime = Date.now();
+    let lastStatus = null;
+
+    while (true) {
+        const response = await fetch(url);
+        if (!response.ok) {
+            const text = await response.text();
+            console.error(`Error: Failed to get run status: ${text}`);
+            process.exit(1);
+        }
+
+        const result = await response.json();
+        const status = result.data.status;
+
+        // Only print when status changes
+        if (status !== lastStatus) {
+            console.log(`Status: ${status}`);
+            lastStatus = status;
+        }
+
+        if (['SUCCEEDED', 'FAILED', 'ABORTED', 'TIMED-OUT'].includes(status)) {
+            return status;
+        }
+
+        const elapsed = (Date.now() - startTime) / 1000;
+        if (elapsed > timeout) {
+            console.error(`Warning: Timeout after ${timeout}s, actor still running`);
+            return 'TIMED-OUT';
+        }
+
+        await sleep(interval * 1000);
+    }
+}
+
+// Download dataset items
+async function downloadResults(token, datasetId, outputPath, format) {
+    const url = `https://api.apify.com/v2/datasets/${datasetId}/items?token=${encodeURIComponent(token)}&format=json`;
+
+    const response = await fetch(url, {
+        headers: {
+            'User-Agent': `${USER_AGENT}/download_${format}`,
+        },
+    });
+
+    if (!response.ok) {
+        const text = await response.text();
+        console.error(`Error: Failed to download results: ${text}`);
+        process.exit(1);
+    }
+
+    const data = await response.json();
+
+    if (format === 'json') {
+        writeFileSync(outputPath, JSON.stringify(data, null, 2));
+    } else {
+        // CSV output
+        if (data.length > 0) {
+            const fieldnames = Object.keys(data[0]);
+            const csvLines = [fieldnames.join(',')];
+
+            for (const row of data) {
+                const values = fieldnames.map((key) => {
+                    let value = row[key];
+
+                    // Truncate long text fields
+                    if (typeof value === 'string' && value.length > 200) {
+                        value = value.slice(0, 200) + '...';
+                    } else if (Array.isArray(value) || (typeof value === 'object' && value !== null)) {
+                        value = JSON.stringify(value) || '';
+                    }
+
+                    // CSV escape: wrap in quotes if contains comma, quote, or newline
+                    if (value === null || value === undefined) {
+                        return '';
+                    }
+                    const strValue = String(value);
+                    if (strValue.includes(',') || strValue.includes('"') || strValue.includes('\n')) {
+                        return `"${strValue.replace(/"/g, '""')}"`;
+                    }
+                    return strValue;
+                });
+                csvLines.push(values.join(','));
+            }
+
+            writeFileSync(outputPath, csvLines.join('\n'));
+        } else {
+            writeFileSync(outputPath, '');
+        }
+    }
+
+    console.log(`Saved to: ${outputPath}`);
+}
+
+// Display top 5 results in chat format
+async function displayQuickAnswer(token, datasetId) {
+    const url = `https://api.apify.com/v2/datasets/${datasetId}/items?token=${encodeURIComponent(token)}&format=json`;
+
+    const response = await fetch(url, {
+        headers: {
+            'User-Agent': `${USER_AGENT}/quick_answer`,
+        },
+    });
+
+    if (!response.ok) {
+        const text = await response.text();
+        console.error(`Error: Failed to download results: ${text}`);
+        process.exit(1);
+    }
+
+    const data = await response.json();
+    const total = data.length;
+
+    if (total === 0) {
+        console.log('\nNo results found.');
+        return;
+    }
+
+    // Display top 5
+    console.log(`\n${'='.repeat(60)}`);
+    console.log(`TOP 5 RESULTS (of ${total} total)`);
+    console.log('='.repeat(60));
+
+    for (let i = 0; i < Math.min(5, data.length); i++) {
+        const item = data[i];
+        console.log(`\n--- Result ${i + 1} ---`);
+
+        for (const [key, value] of Object.entries(item)) {
+            let displayValue = value;
+
+            // Truncate long values
+            if (typeof value === 'string' && value.length > 100) {
+                displayValue = value.slice(0, 100) + '...';
+            } else if (Array.isArray(value) || (typeof value === 'object' && value !== null)) {
+                const jsonStr = JSON.stringify(value);
+                displayValue = jsonStr.length > 100 ? jsonStr.slice(0, 100) + '...' : jsonStr;
+            }
+
+            console.log(`  ${key}: ${displayValue}`);
+        }
+    }
+
+    console.log(`\n${'='.repeat(60)}`);
+    if (total > 5) {
+        console.log(`Showing 5 of ${total} results.`);
+    }
+    console.log(`Full data available at: https://console.apify.com/storage/datasets/${datasetId}`);
+    console.log('='.repeat(60));
+}
+
+// Report summary of downloaded data
+function reportSummary(outputPath, format) {
+    const stats = statSync(outputPath);
+    const size = stats.size;
+
+    let count;
+    try {
+        const content = require('fs').readFileSync(outputPath, 'utf-8');
+        if (format === 'json') {
+            const data = JSON.parse(content);
+            count = Array.isArray(data) ? data.length : 1;
+        } else {
+            // CSV - count lines minus header
+            const lines = content.split('\n').filter((line) => line.trim());
+            count = Math.max(0, lines.length - 1);
+        }
+    } catch {
+        count = 'unknown';
+    }
+
+    console.log(`Records: ${count}`);
+    console.log(`Size: ${size.toLocaleString()} bytes`);
+}
+
+// Helper: sleep for ms
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// Main function
+async function main() {
+    // Parse args first so --help works without token
+    const args = parseCliArgs();
+
+    // Check for APIFY_TOKEN
+    const token = process.env.APIFY_TOKEN;
+    if (!token) {
+        console.error('Error: APIFY_TOKEN not found in .env file');
+        console.error('');
+        console.error('Add your token to .env file:');
+        console.error('  APIFY_TOKEN=your_token_here');
+        console.error('');
+        console.error('Get your token: https://console.apify.com/account/integrations');
+        process.exit(1);
+    }
+
+    // Start the actor run
+    console.log(`Starting actor: ${args.actor}`);
+    const { runId, datasetId } = await startActor(token, args.actor, args.input);
+    console.log(`Run ID: ${runId}`);
+    console.log(`Dataset ID: ${datasetId}`);
+
+    // Poll for completion
+    const status = await pollUntilComplete(token, runId, args.timeout, args.pollInterval);
+
+    if (status !== 'SUCCEEDED') {
+        console.error(`Error: Actor run ${status}`);
+        console.error(`Details: https://console.apify.com/actors/runs/${runId}`);
+        process.exit(1);
+    }
+
+    // Determine output mode
+    if (args.output) {
+        // File output mode
+        await downloadResults(token, datasetId, args.output, args.format);
+        reportSummary(args.output, args.format);
+    } else {
+        // Quick answer mode - display in chat
+        await displayQuickAnswer(token, datasetId);
+    }
+}
+
+main().catch((err) => {
+    console.error(`Error: ${err.message}`);
+    process.exit(1);
+});

package/skills/global_config/apify-ultimate-scraper/SKILL.md

@@ -0,0 +1,241 @@
+---
+name: apify-ultimate-scraper
+description: "AI-driven data extraction from 55+ Actors across all major platforms. This skill automatically selects the best Actor for your task."
+risk: unknown
+source: community
+---
+
+# Universal Web Scraper
+
+AI-driven data extraction from 55+ Actors across all major platforms. This skill automatically selects the best Actor for your task.
+
+## When to Use
+- The user needs web data extraction but has not yet chosen a specific Apify Actor.
+- You need a general-purpose Apify entry point that maps a broad scraping goal to the most suitable Actor.
+- The task spans multiple platforms and benefits from one unified workflow for actor selection, execution, and summarization.
+
+## Prerequisites
+(No need to check it upfront)
+
+- `.env` file with `APIFY_TOKEN`
+- Node.js 20.6+ (for native `--env-file` support)
+- `mcpc` CLI tool: `npm install -g @apify/mcpc`
+
+## Workflow
+
+Copy this checklist and track progress:
+
+```
+Task Progress:
+- [ ] Step 1: Understand user goal and select Actor
+- [ ] Step 2: Fetch Actor schema via mcpc
+- [ ] Step 3: Ask user preferences (format, filename)
+- [ ] Step 4: Run the scraper script
+- [ ] Step 5: Summarize results and offer follow-ups
+```
+
+### Step 1: Understand User Goal and Select Actor
+
+First, understand what the user wants to achieve. Then select the best Actor from the options below.
+
+#### Instagram Actors (12)
+
+| Actor ID | Best For |
+|----------|----------|
+| `apify/instagram-profile-scraper` | Profile data, follower counts, bio info |
+| `apify/instagram-post-scraper` | Individual post details, engagement metrics |
+| `apify/instagram-comment-scraper` | Comment extraction, sentiment analysis |
+| `apify/instagram-hashtag-scraper` | Hashtag content, trending topics |
+| `apify/instagram-hashtag-stats` | Hashtag performance metrics |
+| `apify/instagram-reel-scraper` | Reels content and metrics |
+| `apify/instagram-search-scraper` | Search users, places, hashtags |
+| `apify/instagram-tagged-scraper` | Posts tagged with specific accounts |
+| `apify/instagram-followers-count-scraper` | Follower count tracking |
+| `apify/instagram-scraper` | Comprehensive Instagram data |
+| `apify/instagram-api-scraper` | API-based Instagram access |
+| `apify/export-instagram-comments-posts` | Bulk comment/post export |
+
+#### Facebook Actors (14)
+
+| Actor ID | Best For |
+|----------|----------|
+| `apify/facebook-pages-scraper` | Page data, metrics, contact info |
+| `apify/facebook-page-contact-information` | Emails, phones, addresses from pages |
+| `apify/facebook-posts-scraper` | Post content and engagement |
+| `apify/facebook-comments-scraper` | Comment extraction |
+| `apify/facebook-likes-scraper` | Reaction analysis |
+| `apify/facebook-reviews-scraper` | Page reviews |
+| `apify/facebook-groups-scraper` | Group content and members |
+| `apify/facebook-events-scraper` | Event data |
+| `apify/facebook-ads-scraper` | Ad creative and targeting |
+| `apify/facebook-search-scraper` | Search results |
+| `apify/facebook-reels-scraper` | Reels content |
+| `apify/facebook-photos-scraper` | Photo extraction |
+| `apify/facebook-marketplace-scraper` | Marketplace listings |
+| `apify/facebook-followers-following-scraper` | Follower/following lists |
+
+#### TikTok Actors (14)
+
+| Actor ID | Best For |
+|----------|----------|
+| `clockworks/tiktok-scraper` | Comprehensive TikTok data |
+| `clockworks/free-tiktok-scraper` | Free TikTok extraction |
+| `clockworks/tiktok-profile-scraper` | Profile data |
+| `clockworks/tiktok-video-scraper` | Video details and metrics |
+| `clockworks/tiktok-comments-scraper` | Comment extraction |
+| `clockworks/tiktok-followers-scraper` | Follower lists |
+| `clockworks/tiktok-user-search-scraper` | Find users by keywords |
+| `clockworks/tiktok-hashtag-scraper` | Hashtag content |
+| `clockworks/tiktok-sound-scraper` | Trending sounds |
+| `clockworks/tiktok-ads-scraper` | Ad content |
+| `clockworks/tiktok-discover-scraper` | Discover page content |
+| `clockworks/tiktok-explore-scraper` | Explore content |
+| `clockworks/tiktok-trends-scraper` | Trending content |
+| `clockworks/tiktok-live-scraper` | Live stream data |
+
+#### YouTube Actors (5)
+
+| Actor ID | Best For |
+|----------|----------|
+| `streamers/youtube-scraper` | Video data and metrics |
+| `streamers/youtube-channel-scraper` | Channel information |
+| `streamers/youtube-comments-scraper` | Comment extraction |
+| `streamers/youtube-shorts-scraper` | Shorts content |
+| `streamers/youtube-video-scraper-by-hashtag` | Videos by hashtag |
+
+#### Google Maps Actors (4)
+
+| Actor ID | Best For |
+|----------|----------|
+| `compass/crawler-google-places` | Business listings, ratings, contact info |
+| `compass/google-maps-extractor` | Detailed business data |
+| `compass/Google-Maps-Reviews-Scraper` | Review extraction |
+| `poidata/google-maps-email-extractor` | Email discovery from listings |
+
+#### Other Actors (6)
+
+| Actor ID | Best For |
+|----------|----------|
+| `apify/google-search-scraper` | Google search results |
+| `apify/google-trends-scraper` | Google Trends data |
+| `voyager/booking-scraper` | Booking.com hotel data |
+| `voyager/booking-reviews-scraper` | Booking.com reviews |
+| `maxcopell/tripadvisor-reviews` | TripAdvisor reviews |
+| `vdrmota/contact-info-scraper` | Contact enrichment from URLs |
+
+---
+
+#### Actor Selection by Use Case
+
+| Use Case | Primary Actors |
+|----------|---------------|
+| **Lead Generation** | `compass/crawler-google-places`, `poidata/google-maps-email-extractor`, `vdrmota/contact-info-scraper` |
+| **Influencer Discovery** | `apify/instagram-profile-scraper`, `clockworks/tiktok-profile-scraper`, `streamers/youtube-channel-scraper` |
+| **Brand Monitoring** | `apify/instagram-tagged-scraper`, `apify/instagram-hashtag-scraper`, `compass/Google-Maps-Reviews-Scraper` |
+| **Competitor Analysis** | `apify/facebook-pages-scraper`, `apify/facebook-ads-scraper`, `apify/instagram-profile-scraper` |
+| **Content Analytics** | `apify/instagram-post-scraper`, `clockworks/tiktok-scraper`, `streamers/youtube-scraper` |
+| **Trend Research** | `apify/google-trends-scraper`, `clockworks/tiktok-trends-scraper`, `apify/instagram-hashtag-stats` |
+| **Review Analysis** | `compass/Google-Maps-Reviews-Scraper`, `voyager/booking-reviews-scraper`, `maxcopell/tripadvisor-reviews` |
+| **Audience Analysis** | `apify/instagram-followers-count-scraper`, `clockworks/tiktok-followers-scraper`, `apify/facebook-followers-following-scraper` |
+
+---
+
+#### Multi-Actor Workflows
+
+For complex tasks, chain multiple Actors:
+
+| Workflow | Step 1 | Step 2 |
+|----------|--------|--------|
+| **Lead enrichment** | `compass/crawler-google-places` → | `vdrmota/contact-info-scraper` |
+| **Influencer vetting** | `apify/instagram-profile-scraper` → | `apify/instagram-comment-scraper` |
+| **Competitor deep-dive** | `apify/facebook-pages-scraper` → | `apify/facebook-posts-scraper` |
+| **Local business analysis** | `compass/crawler-google-places` → | `compass/Google-Maps-Reviews-Scraper` |
+
+#### Can't Find a Suitable Actor?
+
+If none of the Actors above match the user's request, search the Apify Store directly:
+
+```bash
+export $(grep APIFY_TOKEN .env | xargs) && mcpc --json mcp.apify.com --header "Authorization: Bearer $APIFY_TOKEN" tools-call search-actors keywords:="SEARCH_KEYWORDS" limit:=10 offset:=0 category:="" | jq -r '.content[0].text'
+```
+
+Replace `SEARCH_KEYWORDS` with 1-3 simple terms (e.g., "LinkedIn profiles", "Amazon products", "Twitter").
+
+### Step 2: Fetch Actor Schema
+
+Fetch the Actor's input schema and details dynamically using mcpc:
+
+```bash
+export $(grep APIFY_TOKEN .env | xargs) && mcpc --json mcp.apify.com --header "Authorization: Bearer $APIFY_TOKEN" tools-call fetch-actor-details actor:="ACTOR_ID" | jq -r ".content"
+```
+
+Replace `ACTOR_ID` with the selected Actor (e.g., `compass/crawler-google-places`).
+
+This returns:
+- Actor description and README
+- Required and optional input parameters
+- Output fields (if available)
+
+### Step 3: Ask User Preferences
+
+Before running, ask:
+1. **Output format**:
+   - **Quick answer** - Display top few results in chat (no file saved)
+   - **CSV** - Full export with all fields
+   - **JSON** - Full export in JSON format
+2. **Number of results**: Based on character of use case
+
+### Step 4: Run the Script
+
+**Quick answer (display in chat, no file):**
+```bash
+node --env-file=.env ${CLAUDE_PLUGIN_ROOT}/reference/scripts/run_actor.js \
+  --actor "ACTOR_ID" \
+  --input 'JSON_INPUT'
+```
+
+**CSV:**
+```bash
+node --env-file=.env ${CLAUDE_PLUGIN_ROOT}/reference/scripts/run_actor.js \
+  --actor "ACTOR_ID" \
+  --input 'JSON_INPUT' \
+  --output YYYY-MM-DD_OUTPUT_FILE.csv \
+  --format csv
+```
+
+**JSON:**
+```bash
+node --env-file=.env ${CLAUDE_PLUGIN_ROOT}/reference/scripts/run_actor.js \
+  --actor "ACTOR_ID" \
+  --input 'JSON_INPUT' \
+  --output YYYY-MM-DD_OUTPUT_FILE.json \
+  --format json
+```
+
+### Step 5: Summarize Results and Offer Follow-ups
+
+After completion, report:
+- Number of results found
+- File location and name
+- Key fields available
+- **Suggested follow-up workflows** based on results:
+
+| If User Got | Suggest Next |
+|-------------|--------------|
+| Business listings | Enrich with `vdrmota/contact-info-scraper` or get reviews |
+| Influencer profiles | Analyze engagement with comment scrapers |
+| Competitor pages | Deep-dive with post/ad scrapers |
+| Trend data | Validate with platform-specific hashtag scrapers |
+
+## Error Handling
+
+`APIFY_TOKEN not found` - Ask user to create `.env` with `APIFY_TOKEN=your_token`
+`mcpc not found` - Ask user to install `npm install -g @apify/mcpc`
+`Actor not found` - Check Actor ID spelling
+`Run FAILED` - Ask user to check Apify console link in error output
+`Timeout` - Reduce input size or increase `--timeout`
+
+## Limitations
+- Use this skill only when the task clearly matches the scope described above.
+- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
+- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.