Meta Ads Collector Adarsh

Collects active Meta ads for a brand, reporting total ads, formats, ad types, longest-running ad duration, and estimated spend if available.

Security Scan

The skill's described behavior (querying Meta's Ad Library) is coherent, but the SKILL.md explicitly requires Meta credentials and environment variables that are not declared in the registry metadata — a configuration mismatch that should be resolved before trusting or installing the skill.

Purpose & Capability

The name and description match the implementation notes: the skill queries the Meta Ad Library API and computes ad metrics. Requesting a Meta access token and app credentials is appropriate for that purpose. However, the registry metadata lists no required environment variables or primary credential while the SKILL.md explicitly requires META_ACCESS_TOKEN, META_APP_ID, and META_APP_SECRET — an inconsistency between declared requirements and the runtime instructions.

Instruction Scope

The runtime instructions are focused on the Ad Library API and metric calculation (formats, counts, durations, optional spend). They reference process.env variables and other project files (e.g., metaAdsService.ts, src/types/audit.types.ts) and instruct logging errors with Winston. The instructions do not ask for unrelated system files or other service credentials, but they do require reading secret env vars (Meta credentials). Because the registry omitted those env requirements, the instructions grant the agent access to secrets that were not declared to users/installers — this is a scope/visibility concern.

Install Mechanism

This is an instruction-only skill with no install spec and no code files. That minimizes install-time risk (nothing is downloaded or written by an installer).

Credentials

The env vars named in SKILL.md (META_ACCESS_TOKEN, META_APP_ID, META_APP_SECRET) are appropriate and proportionate for querying Meta's Ad Library. However, the skill registry metadata claims 'Required env vars: none' and 'Primary credential: none'. The absence of declared env requirements in the registry is misleading and increases risk because users may not realize they must supply sensitive credentials. No unrelated secrets are requested, but the mismatch is a serious transparency issue.

Persistence & Privilege

The skill does not request always: true, does not include an install script, and does not appear to alter other skills or system-wide settings. It relies on runtime environment variables only and does not request elevated persistence.

What to consider before installing

Before installing or enabling this skill: 1) Do not provide META_ACCESS_TOKEN, META_APP_ID, or META_APP_SECRET until you confirm the skill source and how secrets are handled — the registry metadata did not declare any required env vars even though the SKILL.md requires them. 2) Prefer creating an app/credentials with minimal permissions and short-lived tokens (or use a dedicated read-only token) and rotate them after testing. 3) Ask the publisher to update the registry metadata to list the exact environment variables and explain how tokens are used and stored/logged. 4) Verify where logs and any returned data are sent (the SKILL.md references Winston logging and external APIs); ensure logs do not leak tokens or PII. 5) If you cannot verify the source, test in an isolated environment and avoid providing production credentials. If the developer cannot explain the metadata mismatch, treat the skill as untrusted.

Meta Ads Collector Skill

Purpose

Scans the Meta Ad Library API to find active advertisements for a given brand. Extracts the number of active ads, ad formats used, ad types, and the longest-running ad duration. This collector feeds into the Marketing Audit Pipeline to populate the Paid Ads Strategy section of the final report.

Input Schema

// Function signature
collectMetaAds(brandName: string, domain?: string): Promise<MetaAdsData>

// brandName: The brand name to search for in the Ad Library (e.g. "Gymshark")
// domain: Optional domain to refine search (e.g. "gymshark.com"). Used to filter
// results and improve relevance when the brand name is ambiguous.

Output Schema

interface MetaAdsData {
 activeAds: number; // Total count of currently active ads
 formatsUsed: string[]; // e.g. ["image", "video", "carousel"]
 longestRunningAdDays: number; // Days the longest-running active ad has been live
 adTypes: string[]; // e.g. ["POLITICAL_AND_ISSUE_ADS", "HOUSING_ADS", "OTHER"]
 estimatedSpend?: string; // e.g. "$10,000 - $50,000" (if available from API)
 error?: string; // Present only when collector fails
}

API Dependencies

• API Name: Meta Ad Library API
• Endpoint: https://graph.facebook.com/v19.0/ads_archive
• Auth: META_ACCESS_TOKEN environment variable (requires a Facebook App with Ad Library API access)
• Additional env vars: META_APP_ID, META_APP_SECRET (used for token generation if needed)
• Cost estimate: Free (no per-request charge)
• Rate limits: Subject to Meta's standard Graph API rate limits (~200 calls/hour)

Implementation Pattern

Data Flow

1. Receive brandName and optional domain from the pipeline
2. Call metaAdsService.getMetaAds(brandName, domain) which queries the Ad Library API
3. Process the returned ads array to extract metrics
4. Map processed data to the MetaAdsData interface

API Query Parameters

{
 access_token: process.env.META_ACCESS_TOKEN,
 search_terms: brandName,
 ad_reached_countries: "['US']", // Default to US; can be expanded
 ad_active_status: "ACTIVE", // Only fetch currently active ads
 ad_type: "ALL", // Include all ad types
 fields: "id,ad_creation_time,ad_creative_bodies,ad_creative_link_captions,ad_creative_link_titles,ad_delivery_start_time,ad_snapshot_url,page_name",
 limit: 100 // Max results per page
}

Metrics Calculation

Active Ads Count:

• Count the total number of ads returned from the API response

Formats Detection:

• Analyze ad_snapshot_url or creative fields to classify format
• Categories: "image", "video", "carousel", "dynamic", "collection"
• Deduplicate into a unique list

Longest Running Ad:

const now = new Date();
const longestRunningAdDays = Math.max(
 ...ads.map(ad => {
 const startDate = new Date(ad.ad_delivery_start_time);
 return Math.floor((now.getTime() - startDate.getTime()) / (1000 * 60 * 60 * 24));
 })
);

Ad Types:

• Extract unique ad_type values from the response
• Common types: "POLITICAL_AND_ISSUE_ADS", "HOUSING_ADS", "CREDIT_ADS", "EMPLOYMENT_ADS", general/uncategorized

Estimated Spend:

• Only available for political/issue ads (Meta requirement)
• For other ad types, this field will be undefined
• If available, format as a range string: "$10,000 - $50,000"

Domain Filtering

When domain is provided:

• Filter results to only include ads where the creative body, link caption, or link title references the domain
• This improves accuracy for brands with common names

Error Handling

• Entire function wrapped in try/catch
• On failure, return EMPTY_META_ADS_DATA with error field set:

return { ...EMPTY_META_ADS_DATA, error: 'Meta Ads data unavailable: <reason>' };

• Never throw -- always return a valid MetaAdsData object
• Log errors with Winston logger including brandName and error details:

logger.error('Meta Ads collector failed', { brandName, domain, err });

• Common failure scenarios:
• Access token invalid, expired, or lacking Ad Library permissions
• Brand name returns zero results (not necessarily an error -- return zeroed data without error flag)
• Rate limit exceeded (Meta Graph API throttling)
• Network timeout

Example Usage

import { collectMetaAds } from '../collectors/metaAdsCollector';

// Successful collection
const data = await collectMetaAds('Gymshark', 'gymshark.com');
// Returns:
// {
// activeAds: 47,
// formatsUsed: ["image", "video", "carousel"],
// longestRunningAdDays: 182,
// adTypes: ["OTHER"],
// estimatedSpend: undefined,
// }

// No ads found (not an error)
const noAds = await collectMetaAds('TinyLocalShop');
// Returns:
// {
// activeAds: 0,
// formatsUsed: [],
// longestRunningAdDays: 0,
// adTypes: [],
// }

// Failed collection (graceful degradation)
const failedData = await collectMetaAds('Gymshark');
// Returns:
// {
// activeAds: 0,
// formatsUsed: [],
// longestRunningAdDays: 0,
// adTypes: [],
// error: "Meta Ads data unavailable: Access token expired"
// }

Notes

• The collector depends on metaAdsService.ts for the actual API communication. The collector handles only data aggregation and metric calculation.
• Meta Ad Library API requires a Facebook App registered with Ad Library access. The app must be reviewed and approved by Meta for production use.
• The API only returns publicly available ad data. Spend data is only available for political/issue ads as mandated by Meta's transparency policies.
• Zero active ads is a valid result (small or new brands may not run Meta ads) and should be returned without an error flag.
• The EMPTY_META_ADS_DATA constant is defined in src/types/audit.types.ts and should be imported for fallback returns.
• This collector must never block the pipeline. Even a complete failure returns valid typed data with an error flag.
• Pagination: the Meta API returns a maximum of 100 results per page. For brands with many ads, pagination via the after cursor may be needed. For audit purposes, the first page (100 ads) is sufficient.