@thenavidm/facebook-ad-library-mcp 0.1.0

package/dist/adlibrary/harvest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"harvest.js","sourceRoot":"","sources":["../../src/adlibrary/harvest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,0EAA0E;AAC1E,MAAM,UAAU,GAAG,CAAC,eAAe,EAAE,aAAa,EAAE,aAAa,CAAU,CAAC;AAE5E;;;;;GAKG;AACH,MAAM,WAAW,GAAG,iEAAiE,CAAC;AAItF,SAAS,QAAQ,CAAC,KAAc;IAC9B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC;AAED,8FAA8F;AAC9F,QAAQ,CAAC,CAAC,IAAI,CAAC,IAAa;IAC1B,MAAM,KAAK,GAAc,CAAC,IAAI,CAAC,CAAC;IAChC,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxB,MAAM,OAAO,GAAG,KAAK,CAAC,GAAG,EAAE,CAAC;QAC5B,IAAI,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;YACtB,MAAM,OAAO,CAAC;YACd,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC;gBAAE,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAChE,CAAC;aAAM,IAAI,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;YAClC,KAAK,MAAM,KAAK,IAAI,OAAO;gBAAE,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACjD,CAAC;IACH,CAAC;AACH,CAAC;AAED,MAAM,UAAU,IAAI,CAAC,IAAU;IAC7B,KAAK,MAAM,GAAG,IAAI,UAAU,EAAE,CAAC;QAC7B,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC;QACxB,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,EAAE;YAAE,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;IAClF,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,qEAAqE;AACrE,MAAM,UAAU,eAAe,CAAC,OAAgB;IAC9C,MAAM,KAAK,GAAW,EAAE,CAAC;IACzB,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;QACjC,IAAI,OAAO,IAAI,IAAI,IAAI,WAAW,IAAI,IAAI;YAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC/D,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,OAAgB;IAC1C,MAAM,GAAG,GAAW,EAAE,CAAC;IACvB,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;QACjC,MAAM,EAAE,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC;QACtB,IAAI,CAAC,EAAE,IAAI,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;YAAE,SAAS;QAClC,IAAI,CAAC,CAAC,UAAU,IAAI,IAAI,CAAC,IAAI,CAAC,CAAC,SAAS,IAAI,IAAI,CAAC,IAAI,CAAC,CAAC,WAAW,IAAI,IAAI,CAAC;YAAE,SAAS;QACtF,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACb,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACjB,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,oFAAoF;AACpF,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC;QAC/C,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;QACtB,IAAI,IAAI,IAAI,UAAU,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;YAAE,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC3E,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAYD;;;;;;GAMG;AACH,QAAQ,CAAC,CAAC,SAAS,CAAC,KAAc;IAChC,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,KAAK,CAAC,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;QAC1B,OAAO;IACT,CAAC;IACD,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,IAAI,KAAK,QAAQ,CAAC,EAAE,CAAC;QAC5E,KAAK,MAAM,IAAI,IAAI,KAAiB;YAAE,KAAK,CAAC,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;QAC/D,OAAO;IACT,CAAC;IACD,MAAM,KAAK,CAAC;AACd,CAAC;AAED;;;GAGG;AACH,QAAQ,CAAC,CAAC,WAAW,CAAC,IAAY;IAChC,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QACpC,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;QAC5B,IAAI,CAAC,OAAO;YAAE,SAAS;QACvB,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QAC5B,CAAC;QAAC,MAAM,CAAC;YACP,mEAAmE;QACrE,CAAC;IACH,CAAC;AACH,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,MAAM,GAAG,GAAY,EAAE,KAAK,EAAE,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IACnE,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAE/B,KAAK,MAAM,GAAG,IAAI,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC;QACnC,KAAK,MAAM,IAAI,IAAI,eAAe,CAAC,GAAG,CAAC,EAAE,CAAC;YACxC,MAAM,IAAI,GAAG,IAAI,CAAC,WAAW,CAAC,CAAC;YAC/B,IAAI,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;gBACnB,IAAI,OAAO,IAAI,CAAC,YAAY,CAAC,KAAK,QAAQ;oBAAE,GAAG,CAAC,MAAM,GAAG,IAAI,CAAC,YAAY,CAAC,CAAC;gBAC5E,IAAI,IAAI,CAAC,eAAe,CAAC,KAAK,IAAI;oBAAE,GAAG,CAAC,OAAO,GAAG,IAAI,CAAC;YACzD,CAAC;QACH,CAAC;QAED,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;YAC7B,IAAI,GAAG,CAAC,KAAK,KAAK,SAAS,IAAI,OAAO,IAAI,CAAC,OAAO,CAAC,KAAK,QAAQ,IAAI,OAAO,IAAI,IAAI,EAAE,CAAC;gBACpF,GAAG,CAAC,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC;YAC5B,CAAC;YACD,IAAI,IAAI,CAAC,oCAAoC,CAAC,KAAK,IAAI;gBAAE,GAAG,CAAC,OAAO,GAAG,IAAI,CAAC;QAC9E,CAAC;QAED,KAAK,MAAM,IAAI,IAAI,WAAW,CAAC,GAAG,CAAC,EAAE,CAAC;YACpC,MAAM,EAAE,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC;YACtB,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC;gBACxB,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;gBACb,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACvB,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/adlibrary/normalize.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Turning each source's payload into one `Ad`.
+ *
+ * Field shapes here were verified against a live capture on 2026-08-31: 40 ads
+ * spanning every display format Meta serves (DCO, DPA, VIDEO, IMAGE, CAROUSEL).
+ * Creatives arrive in three disjoint places depending on that format, which is
+ * the single most common thing other scrapers get wrong.
+ */
+import type { Ad, BackendName } from "./types.js";
+type Json = Record<string, unknown>;
+/** Unix seconds to an ISO date. Meta sends integers, providers sometimes send strings. */
+export declare function isoDate(value: unknown): string | undefined;
+/** Meta wraps copy as {"text": "..."}. Providers send a bare string. */
+export declare function text(value: unknown): string | undefined;
+/** `l.facebook.com/l.php?u=<real>` to `<real>`. */
+export declare function unwrapRedirect(url: string | undefined): string | undefined;
+export declare function domainOf(url: string | undefined): string | undefined;
+/** Normalise one `collated_results` entry from Meta's Ad Library GraphQL. */
+export declare function adFromGraphql(node: Json, source?: BackendName): Ad;
+/**
+ * Apify flattens the card into its own field names. Where it passes Meta's
+ * shape through untouched, reuse the Meta path rather than mapping twice.
+ */
+export declare function adFromApify(item: Json): Ad;
+export {};

package/dist/adlibrary/normalize.js

@@ -0,0 +1,221 @@
+/**
+ * Turning each source's payload into one `Ad`.
+ *
+ * Field shapes here were verified against a live capture on 2026-08-31: 40 ads
+ * spanning every display format Meta serves (DCO, DPA, VIDEO, IMAGE, CAROUSEL).
+ * Creatives arrive in three disjoint places depending on that format, which is
+ * the single most common thing other scrapers get wrong.
+ */
+const AD_DETAILS = "https://www.facebook.com/ads/library/?id=";
+function obj(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function str(value) {
+    return typeof value === "string" && value.trim() !== "" ? value : undefined;
+}
+function num(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+function arr(value) {
+    return Array.isArray(value) ? value.filter((v) => obj(v) !== undefined) : [];
+}
+function strArray(value) {
+    return Array.isArray(value) ? value.filter((v) => typeof v === "string") : [];
+}
+/** Unix seconds to an ISO date. Meta sends integers, providers sometimes send strings. */
+export function isoDate(value) {
+    if (value === null || value === undefined || value === "" || value === 0)
+        return undefined;
+    let seconds;
+    if (typeof value === "number")
+        seconds = value;
+    else if (typeof value === "string") {
+        if (!/^\d+$/.test(value))
+            return value.length >= 10 ? value.slice(0, 10) : value;
+        seconds = Number(value);
+    }
+    if (seconds === undefined || !Number.isFinite(seconds))
+        return undefined;
+    const date = new Date(seconds * 1000);
+    return Number.isNaN(date.getTime()) ? undefined : date.toISOString().slice(0, 10);
+}
+/** Meta wraps copy as {"text": "..."}. Providers send a bare string. */
+export function text(value) {
+    if (typeof value === "string")
+        return str(value);
+    const wrapper = obj(value);
+    return wrapper ? str(wrapper["text"]) : undefined;
+}
+/** `l.facebook.com/l.php?u=<real>` to `<real>`. */
+export function unwrapRedirect(url) {
+    if (!url || !url.includes("l.facebook.com"))
+        return url;
+    try {
+        const target = new URL(url).searchParams.get("u");
+        return target ? decodeURIComponent(target) : url;
+    }
+    catch {
+        return url;
+    }
+}
+export function domainOf(url) {
+    if (!url)
+        return undefined;
+    try {
+        const host = new URL(url).hostname.toLowerCase();
+        return host.startsWith("www.") ? host.slice(4) : host || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** `FACEBOOK` to `Facebook`, `AUDIENCE_NETWORK` to `Audience Network`. */
+function platformLabel(value) {
+    return value
+        .split("_")
+        .map((part) => part.charAt(0).toUpperCase() + part.slice(1).toLowerCase())
+        .join(" ");
+}
+/**
+ * Creatives live in three disjoint places depending on ad format:
+ *   images: IMAGE ads          videos: VIDEO ads
+ *   cards:  DCO, DPA, CAROUSEL, and these carry per-card copy and links
+ */
+function creativesFrom(snapshot) {
+    const out = [];
+    for (const image of arr(snapshot["images"])) {
+        out.push({
+            kind: "image",
+            imageUrl: str(image["original_image_url"]) ?? str(image["resized_image_url"]),
+        });
+    }
+    for (const video of arr(snapshot["videos"])) {
+        out.push({
+            kind: "video",
+            videoHdUrl: str(video["video_hd_url"]),
+            videoSdUrl: str(video["video_sd_url"]),
+            previewImageUrl: str(video["video_preview_image_url"]),
+        });
+    }
+    for (const card of arr(snapshot["cards"])) {
+        const hd = str(card["video_hd_url"]);
+        const sd = str(card["video_sd_url"]);
+        out.push({
+            kind: hd || sd ? "video" : "image",
+            imageUrl: str(card["original_image_url"]) ?? str(card["resized_image_url"]),
+            videoHdUrl: hd,
+            videoSdUrl: sd,
+            previewImageUrl: str(card["video_preview_image_url"]),
+            title: text(card["title"]),
+            body: text(card["body"]),
+            caption: text(card["caption"]),
+            ctaText: str(card["cta_text"]),
+            linkUrl: unwrapRedirect(str(card["link_url"])),
+        });
+    }
+    return out;
+}
+function daysBetween(startIso, endIso) {
+    const start = Date.parse(startIso);
+    const end = endIso ? Date.parse(endIso) : Date.now();
+    if (!Number.isFinite(start) || !Number.isFinite(end))
+        return undefined;
+    return Math.max(0, Math.floor((end - start) / 86_400_000));
+}
+/** Normalise one `collated_results` entry from Meta's Ad Library GraphQL. */
+export function adFromGraphql(node, source = "browser") {
+    const snapshot = obj(node["snapshot"]) ?? {};
+    const linkUrl = unwrapRedirect(str(snapshot["link_url"]));
+    const startedRunning = isoDate(node["start_date"]);
+    const stoppedRunning = isoDate(node["end_date"]);
+    const libraryId = String(node["ad_archive_id"] ?? node["adArchiveId"] ?? "");
+    // Meta gives total_active_time in seconds when it gives it at all; otherwise
+    // measure from the start date, and only to the stop date once it has stopped.
+    const activeSeconds = num(node["total_active_time"]);
+    const daysActive = activeSeconds && activeSeconds > 0
+        ? Math.floor(activeSeconds / 86_400)
+        : startedRunning
+            ? daysBetween(startedRunning, node["is_active"] === true ? undefined : stoppedRunning)
+            : undefined;
+    const impressionsWrapper = obj(node["impressions_with_index"]);
+    return {
+        libraryId,
+        adDetailsUrl: libraryId ? AD_DETAILS + libraryId : "",
+        pageId: node["page_id"] !== undefined ? String(node["page_id"]) : undefined,
+        pageName: str(node["page_name"]) ?? str(snapshot["page_name"]),
+        pageUrl: str(snapshot["page_profile_uri"]),
+        pageLikes: num(snapshot["page_like_count"]),
+        pageCategories: strArray(snapshot["page_categories"]),
+        pageProfilePictureUrl: str(snapshot["page_profile_picture_url"]),
+        isActive: typeof node["is_active"] === "boolean" ? node["is_active"] : undefined,
+        startedRunning,
+        stoppedRunning,
+        daysActive,
+        platforms: strArray(node["publisher_platform"]).map(platformLabel),
+        countries: strArray(node["targeted_or_reached_countries"]),
+        categories: strArray(node["categories"]),
+        displayFormat: str(snapshot["display_format"]),
+        title: text(snapshot["title"]),
+        body: text(snapshot["body"]),
+        caption: text(snapshot["caption"]),
+        linkDescription: text(snapshot["link_description"]),
+        ctaText: str(snapshot["cta_text"]),
+        ctaType: str(snapshot["cta_type"]),
+        linkUrl,
+        linkDomain: domainOf(linkUrl),
+        creatives: creativesFrom(snapshot),
+        variantsUsingCreative: num(node["collation_count"]),
+        spend: node["spend"] ?? undefined,
+        currency: str(node["currency"]),
+        reachEstimate: node["reach_estimate"] ?? undefined,
+        impressions: impressionsWrapper ? impressionsWrapper["impressions_text"] : undefined,
+        source,
+    };
+}
+/**
+ * Apify flattens the card into its own field names. Where it passes Meta's
+ * shape through untouched, reuse the Meta path rather than mapping twice.
+ */
+export function adFromApify(item) {
+    if (obj(item["snapshot"]) && item["ad_archive_id"])
+        return adFromGraphql(item, "apify");
+    const linkUrl = unwrapRedirect(str(item["link_url"]) ?? str(item["linkUrl"]));
+    const libraryId = String(item["ad_archive_id"] ?? item["adArchiveId"] ?? item["id"] ?? "");
+    return {
+        libraryId,
+        adDetailsUrl: libraryId ? AD_DETAILS + libraryId : "",
+        pageId: item["page_id"] !== undefined || item["pageId"] !== undefined
+            ? String(item["page_id"] ?? item["pageId"])
+            : undefined,
+        pageName: str(item["page_name"]) ?? str(item["pageName"]),
+        pageUrl: str(item["page_profile_uri"]) ?? str(item["pageUrl"]),
+        pageLikes: num(item["page_like_count"]) ?? num(item["pageLikes"]),
+        pageCategories: [],
+        isActive: typeof item["is_active"] === "boolean"
+            ? item["is_active"]
+            : typeof item["isActive"] === "boolean"
+                ? item["isActive"]
+                : undefined,
+        startedRunning: isoDate(item["start_date"] ?? item["startDate"]),
+        stoppedRunning: isoDate(item["end_date"] ?? item["endDate"]),
+        platforms: strArray(item["publisher_platform"] ?? item["publisherPlatform"]).map(platformLabel),
+        countries: [],
+        categories: [],
+        displayFormat: str(item["display_format"]) ?? str(item["displayFormat"]),
+        title: text(item["title"]),
+        body: text(item["body"]) ?? text(item["adText"]),
+        caption: text(item["caption"]),
+        ctaText: str(item["cta_text"]) ?? str(item["ctaText"]),
+        ctaType: str(item["cta_type"]) ?? str(item["ctaType"]),
+        linkUrl,
+        linkDomain: domainOf(linkUrl),
+        creatives: [],
+        spend: item["spend"] ?? undefined,
+        currency: str(item["currency"]),
+        reachEstimate: item["reach_estimate"] ?? item["reach"] ?? undefined,
+        source: "apify",
+    };
+}
+//# sourceMappingURL=normalize.js.map

package/dist/adlibrary/normalize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize.js","sourceRoot":"","sources":["../../src/adlibrary/normalize.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,MAAM,UAAU,GAAG,2CAA2C,CAAC;AAI/D,SAAS,GAAG,CAAC,KAAc;IACzB,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QACzE,CAAC,CAAE,KAAc;QACjB,CAAC,CAAC,SAAS,CAAC;AAChB,CAAC;AAED,SAAS,GAAG,CAAC,KAAc;IACzB,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;AAC9E,CAAC;AAED,SAAS,GAAG,CAAC,KAAc;IACzB,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;AACjF,CAAC;AAED,SAAS,GAAG,CAAC,KAAc;IACzB,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAa,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;AAC1F,CAAC;AAED,SAAS,QAAQ,CAAC,KAAc;IAC9B,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;AAC7F,CAAC;AAED,0FAA0F;AAC1F,MAAM,UAAU,OAAO,CAAC,KAAc;IACpC,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,EAAE,IAAI,KAAK,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IAC3F,IAAI,OAA2B,CAAC;IAChC,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,GAAG,KAAK,CAAC;SAC1C,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QACnC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC;YAAE,OAAO,KAAK,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;QACjF,OAAO,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;IAC1B,CAAC;IACD,IAAI,OAAO,KAAK,SAAS,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC;QAAE,OAAO,SAAS,CAAC;IACzE,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,CAAC;IACtC,OAAO,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AACpF,CAAC;AAED,wEAAwE;AACxE,MAAM,UAAU,IAAI,CAAC,KAAc;IACjC,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,GAAG,CAAC,KAAK,CAAC,CAAC;IACjD,MAAM,OAAO,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC;IAC3B,OAAO,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AACpD,CAAC;AAED,mDAAmD;AACnD,MAAM,UAAU,cAAc,CAAC,GAAuB;IACpD,IAAI,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,gBAAgB,CAAC;QAAE,OAAO,GAAG,CAAC;IACxD,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC,YAAY,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAClD,OAAO,MAAM,CAAC,CAAC,CAAC,kBAAkB,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;IACnD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,GAAG,CAAC;IACb,CAAC;AACH,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,GAAuB;IAC9C,IAAI,CAAC,GAAG;QAAE,OAAO,SAAS,CAAC;IAC3B,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,WAAW,EAAE,CAAC;QACjD,OAAO,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,IAAI,SAAS,CAAC;IACrE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED,0EAA0E;AAC1E,SAAS,aAAa,CAAC,KAAa;IAClC,OAAO,KAAK;SACT,KAAK,CAAC,GAAG,CAAC;SACV,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;SACzE,IAAI,CAAC,GAAG,CAAC,CAAC;AACf,CAAC;AAED;;;;GAIG;AACH,SAAS,aAAa,CAAC,QAAc;IACnC,MAAM,GAAG,GAAe,EAAE,CAAC;IAE3B,KAAK,MAAM,KAAK,IAAI,GAAG,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,EAAE,CAAC;QAC5C,GAAG,CAAC,IAAI,CAAC;YACP,IAAI,EAAE,OAAO;YACb,QAAQ,EAAE,GAAG,CAAC,KAAK,CAAC,oBAAoB,CAAC,CAAC,IAAI,GAAG,CAAC,KAAK,CAAC,mBAAmB,CAAC,CAAC;SAC9E,CAAC,CAAC;IACL,CAAC;IAED,KAAK,MAAM,KAAK,IAAI,GAAG,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,EAAE,CAAC;QAC5C,GAAG,CAAC,IAAI,CAAC;YACP,IAAI,EAAE,OAAO;YACb,UAAU,EAAE,GAAG,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC;YACtC,UAAU,EAAE,GAAG,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC;YACtC,eAAe,EAAE,GAAG,CAAC,KAAK,CAAC,yBAAyB,CAAC,CAAC;SACvD,CAAC,CAAC;IACL,CAAC;IAED,KAAK,MAAM,IAAI,IAAI,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC;QAC1C,MAAM,EAAE,GAAG,GAAG,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC,CAAC;QACrC,MAAM,EAAE,GAAG,GAAG,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC,CAAC;QACrC,GAAG,CAAC,IAAI,CAAC;YACP,IAAI,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO;YAClC,QAAQ,EAAE,GAAG,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAC,IAAI,GAAG,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC;YAC3E,UAAU,EAAE,EAAE;YACd,UAAU,EAAE,EAAE;YACd,eAAe,EAAE,GAAG,CAAC,IAAI,CAAC,yBAAyB,CAAC,CAAC;YACrD,KAAK,EAAE,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YAC1B,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YACxB,OAAO,EAAE,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;YAC9B,OAAO,EAAE,GAAG,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;YAC9B,OAAO,EAAE,cAAc,CAAC,GAAG,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC;SAC/C,CAAC,CAAC;IACL,CAAC;IAED,OAAO,GAAG,CAAC;AACb,CAAC;AAED,SAAS,WAAW,CAAC,QAAgB,EAAE,MAA0B;IAC/D,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;IACnC,MAAM,GAAG,GAAG,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC;IACrD,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC;QAAE,OAAO,SAAS,CAAC;IACvE,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,GAAG,KAAK,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC;AAC7D,CAAC;AAED,6EAA6E;AAC7E,MAAM,UAAU,aAAa,CAAC,IAAU,EAAE,SAAsB,SAAS;IACvE,MAAM,QAAQ,GAAG,GAAG,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,IAAI,EAAE,CAAC;IAC7C,MAAM,OAAO,GAAG,cAAc,CAAC,GAAG,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;IAC1D,MAAM,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,CAAC;IACnD,MAAM,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC;IACjD,MAAM,SAAS,GAAG,MAAM,CAAC,IAAI,CAAC,eAAe,CAAC,IAAI,IAAI,CAAC,aAAa,CAAC,IAAI,EAAE,CAAC,CAAC;IAE7E,6EAA6E;IAC7E,8EAA8E;IAC9E,MAAM,aAAa,GAAG,GAAG,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC,CAAC;IACrD,MAAM,UAAU,GACd,aAAa,IAAI,aAAa,GAAG,CAAC;QAChC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,aAAa,GAAG,MAAM,CAAC;QACpC,CAAC,CAAC,cAAc;YACd,CAAC,CAAC,WAAW,CAAC,cAAc,EAAE,IAAI,CAAC,WAAW,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,cAAc,CAAC;YACtF,CAAC,CAAC,SAAS,CAAC;IAElB,MAAM,kBAAkB,GAAG,GAAG,CAAC,IAAI,CAAC,wBAAwB,CAAC,CAAC,CAAC;IAE/D,OAAO;QACL,SAAS;QACT,YAAY,EAAE,SAAS,CAAC,CAAC,CAAC,UAAU,GAAG,SAAS,CAAC,CAAC,CAAC,EAAE;QACrD,MAAM,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS;QAC3E,QAAQ,EAAE,GAAG,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,IAAI,GAAG,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;QAC9D,OAAO,EAAE,GAAG,CAAC,QAAQ,CAAC,kBAAkB,CAAC,CAAC;QAC1C,SAAS,EAAE,GAAG,CAAC,QAAQ,CAAC,iBAAiB,CAAC,CAAC;QAC3C,cAAc,EAAE,QAAQ,CAAC,QAAQ,CAAC,iBAAiB,CAAC,CAAC;QACrD,qBAAqB,EAAE,GAAG,CAAC,QAAQ,CAAC,0BAA0B,CAAC,CAAC;QAChE,QAAQ,EAAE,OAAO,IAAI,CAAC,WAAW,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,SAAS;QAChF,cAAc;QACd,cAAc;QACd,UAAU;QACV,SAAS,EAAE,QAAQ,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAC,CAAC,GAAG,CAAC,aAAa,CAAC;QAClE,SAAS,EAAE,QAAQ,CAAC,IAAI,CAAC,+BAA+B,CAAC,CAAC;QAC1D,UAAU,EAAE,QAAQ,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;QACxC,aAAa,EAAE,GAAG,CAAC,QAAQ,CAAC,gBAAgB,CAAC,CAAC;QAC9C,KAAK,EAAE,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;QAC9B,IAAI,EAAE,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QAC5B,OAAO,EAAE,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;QAClC,eAAe,EAAE,IAAI,CAAC,QAAQ,CAAC,kBAAkB,CAAC,CAAC;QACnD,OAAO,EAAE,GAAG,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC;QAClC,OAAO,EAAE,GAAG,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC;QAClC,OAAO;QACP,UAAU,EAAE,QAAQ,CAAC,OAAO,CAAC;QAC7B,SAAS,EAAE,aAAa,CAAC,QAAQ,CAAC;QAClC,qBAAqB,EAAE,GAAG,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC;QACnD,KAAK,EAAE,IAAI,CAAC,OAAO,CAAC,IAAI,SAAS;QACjC,QAAQ,EAAE,GAAG,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QAC/B,aAAa,EAAE,IAAI,CAAC,gBAAgB,CAAC,IAAI,SAAS;QAClD,WAAW,EAAE,kBAAkB,CAAC,CAAC,CAAC,kBAAkB,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC,SAAS;QACpF,MAAM;KACP,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,IAAU;IACpC,IAAI,GAAG,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,IAAI,IAAI,CAAC,eAAe,CAAC;QAAE,OAAO,aAAa,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IAExF,MAAM,OAAO,GAAG,cAAc,CAAC,GAAG,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,IAAI,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;IAC9E,MAAM,SAAS,GAAG,MAAM,CACtB,IAAI,CAAC,eAAe,CAAC,IAAI,IAAI,CAAC,aAAa,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CACjE,CAAC;IAEF,OAAO;QACL,SAAS;QACT,YAAY,EAAE,SAAS,CAAC,CAAC,CAAC,UAAU,GAAG,SAAS,CAAC,CAAC,CAAC,EAAE;QACrD,MAAM,EACJ,IAAI,CAAC,SAAS,CAAC,KAAK,SAAS,IAAI,IAAI,CAAC,QAAQ,CAAC,KAAK,SAAS;YAC3D,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,CAAC;YAC3C,CAAC,CAAC,SAAS;QACf,QAAQ,EAAE,GAAG,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,IAAI,GAAG,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QACzD,OAAO,EAAE,GAAG,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAC,IAAI,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QAC9D,SAAS,EAAE,GAAG,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC,IAAI,GAAG,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;QACjE,cAAc,EAAE,EAAE;QAClB,QAAQ,EACN,OAAO,IAAI,CAAC,WAAW,CAAC,KAAK,SAAS;YACpC,CAAC,CAAC,IAAI,CAAC,WAAW,CAAC;YACnB,CAAC,CAAC,OAAO,IAAI,CAAC,UAAU,CAAC,KAAK,SAAS;gBACrC,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC;gBAClB,CAAC,CAAC,SAAS;QACjB,cAAc,EAAE,OAAO,CAAC,IAAI,CAAC,YAAY,CAAC,IAAI,IAAI,CAAC,WAAW,CAAC,CAAC;QAChE,cAAc,EAAE,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,IAAI,CAAC,SAAS,CAAC,CAAC;QAC5D,SAAS,EAAE,QAAQ,CAAC,IAAI,CAAC,oBAAoB,CAAC,IAAI,IAAI,CAAC,mBAAmB,CAAC,CAAC,CAAC,GAAG,CAAC,aAAa,CAAC;QAC/F,SAAS,EAAE,EAAE;QACb,UAAU,EAAE,EAAE;QACd,aAAa,EAAE,GAAG,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC,IAAI,GAAG,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC;QACxE,KAAK,EAAE,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAC1B,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAChD,OAAO,EAAE,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QAC9B,OAAO,EAAE,GAAG,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,IAAI,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QACtD,OAAO,EAAE,GAAG,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,IAAI,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QACtD,OAAO;QACP,UAAU,EAAE,QAAQ,CAAC,OAAO,CAAC;QAC7B,SAAS,EAAE,EAAE;QACb,KAAK,EAAE,IAAI,CAAC,OAAO,CAAC,IAAI,SAAS;QACjC,QAAQ,EAAE,GAAG,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QAC/B,aAAa,EAAE,IAAI,CAAC,gBAAgB,CAAC,IAAI,IAAI,CAAC,OAAO,CAAC,IAAI,SAAS;QACnE,MAAM,EAAE,OAAO;KAChB,CAAC;AACJ,CAAC"}

package/dist/adlibrary/types.d.ts

@@ -0,0 +1,101 @@
+/**
+ * The one Ad shape every backend returns.
+ *
+ * Three sources feed this: Meta's own GraphQL payload, ScrapeCreators and Apify.
+ * They disagree about field names and nesting. Everything downstream, including
+ * every tool, sees only the types here.
+ */
+/** One image or video inside an ad. A carousel has several. */
+export type Creative = {
+    kind: "image" | "video";
+    imageUrl?: string;
+    videoHdUrl?: string;
+    videoSdUrl?: string;
+    previewImageUrl?: string;
+    title?: string;
+    body?: string;
+    caption?: string;
+    ctaText?: string;
+    linkUrl?: string;
+};
+export type Ad = {
+    libraryId: string;
+    adDetailsUrl: string;
+    pageId?: string;
+    pageName?: string;
+    pageUrl?: string;
+    pageLikes?: number;
+    pageCategories: string[];
+    pageProfilePictureUrl?: string;
+    isActive?: boolean;
+    startedRunning?: string;
+    stoppedRunning?: string;
+    daysActive?: number;
+    platforms: string[];
+    countries: string[];
+    categories: string[];
+    displayFormat?: string;
+    title?: string;
+    body?: string;
+    caption?: string;
+    linkDescription?: string;
+    ctaText?: string;
+    ctaType?: string;
+    linkUrl?: string;
+    linkDomain?: string;
+    creatives: Creative[];
+    /** Meta's "N ads use this creative". How many variants share this asset. */
+    variantsUsingCreative?: number;
+    spend?: unknown;
+    currency?: string;
+    reachEstimate?: unknown;
+    impressions?: unknown;
+    source: BackendName;
+};
+export type BackendName = "browser" | "scrapecreators" | "apify";
+export type Advertiser = {
+    pageId: string;
+    pageName?: string;
+    pageUrl?: string;
+    pageLikes?: number;
+    verified?: boolean;
+    category?: string;
+    profilePictureUrl?: string;
+    adCount?: number;
+};
+export type SearchResult = {
+    backend: BackendName;
+    count: number;
+    hasMore: boolean;
+    cursor?: string;
+    /** Meta's own count of matching ads for this search, when it tells us. */
+    totalAvailable?: number;
+    url?: string;
+    note?: string;
+    ads: Ad[];
+};
+export declare const ACTIVE_STATUS: readonly ["active", "inactive", "all"];
+export declare const MEDIA_TYPE: readonly ["all", "image", "meme", "video", "none"];
+export declare const AD_TYPE: readonly ["all", "political_and_issue_ads", "employment_ads", "housing_ads", "financial_products_and_services_ads"];
+export type ActiveStatus = (typeof ACTIVE_STATUS)[number];
+export type MediaType = (typeof MEDIA_TYPE)[number];
+export type AdType = (typeof AD_TYPE)[number];
+export type SearchParams = {
+    query?: string;
+    pageId?: string;
+    country?: string;
+    activeStatus?: ActiveStatus;
+    adType?: AdType;
+    mediaType?: MediaType;
+    limit?: number;
+    cursor?: string;
+};
+export interface Backend {
+    readonly name: BackendName;
+    readonly needsKey: boolean;
+    search(params: SearchParams): Promise<SearchResult>;
+    listAdvertisers(query: string, country?: string): Promise<Advertiser[]>;
+    getAd(libraryId: string, country?: string): Promise<Ad | undefined>;
+    transcribe?(libraryId: string): Promise<string | undefined>;
+    close(): Promise<void>;
+}

package/dist/adlibrary/types.js

@@ -0,0 +1,17 @@
+/**
+ * The one Ad shape every backend returns.
+ *
+ * Three sources feed this: Meta's own GraphQL payload, ScrapeCreators and Apify.
+ * They disagree about field names and nesting. Everything downstream, including
+ * every tool, sees only the types here.
+ */
+export const ACTIVE_STATUS = ["active", "inactive", "all"];
+export const MEDIA_TYPE = ["all", "image", "meme", "video", "none"];
+export const AD_TYPE = [
+    "all",
+    "political_and_issue_ads",
+    "employment_ads",
+    "housing_ads",
+    "financial_products_and_services_ads",
+];
+//# sourceMappingURL=types.js.map

package/dist/adlibrary/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/adlibrary/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAsFH,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,QAAQ,EAAE,UAAU,EAAE,KAAK,CAAU,CAAC;AACpE,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAU,CAAC;AAC7E,MAAM,CAAC,MAAM,OAAO,GAAG;IACrB,KAAK;IACL,yBAAyB;IACzB,gBAAgB;IAChB,aAAa;IACb,qCAAqC;CAC7B,CAAC"}

package/dist/adlibrary/url.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The public Ad Library URL for a set of filters.
+ *
+ * Shared, because the browser backend navigates to it and Apify takes the same
+ * URL as its actor input. One builder means the two cannot drift.
+ */
+import type { SearchParams } from "./types.js";
+export declare const AD_LIBRARY = "https://www.facebook.com/ads/library/";
+export declare function buildUrl(params: SearchParams): string;
+export declare function adDetailsUrl(libraryId: string): string;

package/dist/adlibrary/url.js

@@ -0,0 +1,29 @@
+/**
+ * The public Ad Library URL for a set of filters.
+ *
+ * Shared, because the browser backend navigates to it and Apify takes the same
+ * URL as its actor input. One builder means the two cannot drift.
+ */
+export const AD_LIBRARY = "https://www.facebook.com/ads/library/";
+export function buildUrl(params) {
+    const search = new URLSearchParams({
+        active_status: params.activeStatus ?? "active",
+        ad_type: params.adType ?? "all",
+        country: params.country ?? "US",
+        media_type: params.mediaType ?? "all",
+    });
+    if (params.pageId) {
+        search.set("view_all_page_id", params.pageId);
+        search.set("search_type", "page");
+    }
+    else {
+        search.set("search_type", "keyword_unordered");
+    }
+    if (params.query)
+        search.set("q", params.query);
+    return `${AD_LIBRARY}?${search.toString()}`;
+}
+export function adDetailsUrl(libraryId) {
+    return `${AD_LIBRARY}?id=${encodeURIComponent(libraryId)}`;
+}
+//# sourceMappingURL=url.js.map

package/dist/adlibrary/url.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"url.js","sourceRoot":"","sources":["../../src/adlibrary/url.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,MAAM,CAAC,MAAM,UAAU,GAAG,uCAAuC,CAAC;AAElE,MAAM,UAAU,QAAQ,CAAC,MAAoB;IAC3C,MAAM,MAAM,GAAG,IAAI,eAAe,CAAC;QACjC,aAAa,EAAE,MAAM,CAAC,YAAY,IAAI,QAAQ;QAC9C,OAAO,EAAE,MAAM,CAAC,MAAM,IAAI,KAAK;QAC/B,OAAO,EAAE,MAAM,CAAC,OAAO,IAAI,IAAI;QAC/B,UAAU,EAAE,MAAM,CAAC,SAAS,IAAI,KAAK;KACtC,CAAC,CAAC;IAEH,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;QAClB,MAAM,CAAC,GAAG,CAAC,kBAAkB,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;QAC9C,MAAM,CAAC,GAAG,CAAC,aAAa,EAAE,MAAM,CAAC,CAAC;IACpC,CAAC;SAAM,CAAC;QACN,MAAM,CAAC,GAAG,CAAC,aAAa,EAAE,mBAAmB,CAAC,CAAC;IACjD,CAAC;IACD,IAAI,MAAM,CAAC,KAAK;QAAE,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC;IAEhD,OAAO,GAAG,UAAU,IAAI,MAAM,CAAC,QAAQ,EAAE,EAAE,CAAC;AAC9C,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,SAAiB;IAC5C,OAAO,GAAG,UAAU,OAAO,kBAAkB,CAAC,SAAS,CAAC,EAAE,CAAC;AAC7D,CAAC"}

package/dist/archive/client.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Meta's official Ad Library API (`ads_archive`).
+ *
+ * This is not a backend. It cannot find ordinary commercial ads, so it can never
+ * replace the browser or a provider. It does the one thing none of them can:
+ * return real spend, impressions, reach and demographic breakdowns, published
+ * under transparency law.
+ *
+ * Coverage, stated plainly because it is the whole catch:
+ *   - Political and issue ads: worldwide, with spend and impression ranges.
+ *   - Every ad delivered in the EU: covered by the DSA, with reach attached.
+ *   - An ordinary commercial ad in the US: not in here at all.
+ *
+ * So this returning nothing for a US brand is the correct answer, not a failure.
+ *
+ * The Graph version defaults to v26.0, which was the highest version accepting
+ * requests when this was written on 2026-08-31 (v27.0 and above answered
+ * "does not exist"). Override with META_GRAPH_VERSION when Meta moves on.
+ */
+export type ArchiveQuery = {
+    query?: string;
+    pageIds?: string[];
+    country?: string;
+    limit?: number;
+    adType?: string;
+};
+export type ArchiveResult = {
+    count: number;
+    country: string;
+    fieldsReturned: "full" | "core";
+    next?: string;
+    ads: unknown[];
+    note?: string;
+};
+export declare class ArchiveClient {
+    private readonly token;
+    private readonly version;
+    constructor(token: string, options?: {
+        version?: string;
+        timeoutMs?: number;
+    });
+    private readonly timeoutMs;
+    private request;
+    search(query: ArchiveQuery): Promise<ArchiveResult>;
+}

package/dist/archive/client.js

@@ -0,0 +1,124 @@
+/**
+ * Meta's official Ad Library API (`ads_archive`).
+ *
+ * This is not a backend. It cannot find ordinary commercial ads, so it can never
+ * replace the browser or a provider. It does the one thing none of them can:
+ * return real spend, impressions, reach and demographic breakdowns, published
+ * under transparency law.
+ *
+ * Coverage, stated plainly because it is the whole catch:
+ *   - Political and issue ads: worldwide, with spend and impression ranges.
+ *   - Every ad delivered in the EU: covered by the DSA, with reach attached.
+ *   - An ordinary commercial ad in the US: not in here at all.
+ *
+ * So this returning nothing for a US brand is the correct answer, not a failure.
+ *
+ * The Graph version defaults to v26.0, which was the highest version accepting
+ * requests when this was written on 2026-08-31 (v27.0 and above answered
+ * "does not exist"). Override with META_GRAPH_VERSION when Meta moves on.
+ */
+import { AdLibraryError } from "../errors.js";
+const BASE = "https://graph.facebook.com";
+/**
+ * Requested in full first. If the token lacks access to some of these, Meta
+ * rejects the whole call rather than omitting the field, so we retry with CORE.
+ */
+const FULL_FIELDS = [
+    "id", "page_id", "page_name", "ad_snapshot_url",
+    "ad_creation_time", "ad_delivery_start_time", "ad_delivery_stop_time",
+    "ad_creative_bodies", "ad_creative_link_titles",
+    "ad_creative_link_captions", "ad_creative_link_descriptions",
+    "publisher_platforms", "languages", "bylines",
+    "currency", "spend", "impressions",
+    "demographic_distribution", "delivery_by_region",
+    "eu_total_reach", "age_country_gender_reach_breakdown",
+    "target_ages", "target_gender", "target_locations",
+    "beneficiary_payers",
+];
+const CORE_FIELDS = [
+    "id", "page_id", "page_name", "ad_snapshot_url",
+    "ad_delivery_start_time", "ad_delivery_stop_time",
+    "ad_creative_bodies", "ad_creative_link_titles",
+    "publisher_platforms", "currency", "spend", "impressions",
+];
+export class ArchiveClient {
+    token;
+    version;
+    constructor(token, options = {}) {
+        this.token = token;
+        if (!token) {
+            throw new AdLibraryError("Meta's Ad Library API needs a token.", {
+                hint: "Create a Meta app, generate a token, and set META_ADS_ARCHIVE_TOKEN. It is free. " +
+                    "Without it every other tool still works, they just cannot return spend or reach.",
+            });
+        }
+        this.version = options.version ?? process.env["META_GRAPH_VERSION"] ?? "v26.0";
+        this.timeoutMs = options.timeoutMs ?? 60_000;
+    }
+    timeoutMs;
+    async request(params) {
+        const url = new URL(`/${this.version}/ads_archive?${params.toString()}`, BASE);
+        const response = await fetch(url, { signal: AbortSignal.timeout(this.timeoutMs) });
+        let payload;
+        try {
+            payload = (await response.json());
+        }
+        catch {
+            throw new AdLibraryError("The Ad Library API returned a body that is not JSON.");
+        }
+        const error = payload["error"];
+        if (error && typeof error === "object") {
+            const err = error;
+            throw new AdLibraryError(`Ad Library API error ${err["code"]}: ${err["message"]}`, {
+                hint: "Check META_ADS_ARCHIVE_TOKEN is valid and has not expired.",
+            });
+        }
+        return payload;
+    }
+    async search(query) {
+        if (!query.query && !(query.pageIds && query.pageIds.length > 0)) {
+            throw new AdLibraryError("Pass either query or page_ids.");
+        }
+        const country = (query.country ?? "DE").toUpperCase();
+        const build = (fields) => {
+            const params = new URLSearchParams({
+                access_token: this.token,
+                ad_reached_countries: JSON.stringify([country]),
+                ad_type: query.adType ?? "ALL",
+                limit: String(Math.min(Math.max(query.limit ?? 25, 1), 100)),
+                fields: fields.join(","),
+            });
+            if (query.query)
+                params.set("search_terms", query.query);
+            if (query.pageIds?.length)
+                params.set("search_page_ids", JSON.stringify(query.pageIds));
+            return params;
+        };
+        let payload;
+        let fieldsReturned = "full";
+        try {
+            payload = await this.request(build(FULL_FIELDS));
+        }
+        catch {
+            // Most often a permissions problem on the EU-only fields. Retry with the
+            // set every token can read rather than failing the whole call.
+            payload = await this.request(build(CORE_FIELDS));
+            fieldsReturned = "core";
+        }
+        const ads = Array.isArray(payload["data"]) ? payload["data"] : [];
+        const paging = payload["paging"];
+        return {
+            count: ads.length,
+            country,
+            fieldsReturned,
+            next: typeof paging?.["next"] === "string" ? paging["next"] : undefined,
+            ads,
+            note: ads.length === 0
+                ? "Empty is a valid answer. This API covers political and issue ads worldwide, plus " +
+                    "every ad delivered in the EU. Ordinary commercial ads outside the EU are not in " +
+                    "it at all. Use search_ads for those."
+                : undefined,
+        };
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/archive/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/archive/client.ts"],"names":[],"mappings":"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"}