@thenavidm/facebook-ad-library-mcp 0.1.0

package/dist/backends/apify.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Apify backend. Needs a token, works serverless, about $3.40 to $5.80 per 1,000 ads.
+ *
+ * Two to three times the price of ScrapeCreators, and an actor run to wait on
+ * rather than a plain request, so it is not the default provider. It is here
+ * because plenty of people already have an Apify account and a token, and
+ * because its e-commerce enrichment has no equivalent elsewhere.
+ *
+ * The actor takes an Ad Library URL as `startUrls`, which is the same URL the
+ * browser backend navigates to, so both share `adlibrary/url.ts`.
+ *
+ * Actor input schema read from the live API on 2026-08-31.
+ */
+import type { Ad, Advertiser, Backend, SearchParams, SearchResult } from "../adlibrary/types.js";
+export declare class ApifyBackend implements Backend {
+    private readonly token;
+    private readonly options;
+    readonly name: "apify";
+    readonly needsKey = true;
+    constructor(token: string, options?: {
+        timeoutMs?: number;
+        ecommerce?: boolean;
+    });
+    close(): Promise<void>;
+    /**
+     * One synchronous actor run, returning its dataset items.
+     *
+     * `run-sync-get-dataset-items` blocks until the run finishes, which is why the
+     * default timeout is generous. Apify caps a sync run at five minutes, so a very
+     * large limit times out rather than returning partial data.
+     */
+    private run;
+    search(params: SearchParams): Promise<SearchResult>;
+    /** No company-search endpoint on this actor, so derive advertisers from results. */
+    listAdvertisers(query: string, country?: string): Promise<Advertiser[]>;
+    getAd(libraryId: string): Promise<Ad | undefined>;
+}

package/dist/backends/apify.js

@@ -0,0 +1,152 @@
+/**
+ * Apify backend. Needs a token, works serverless, about $3.40 to $5.80 per 1,000 ads.
+ *
+ * Two to three times the price of ScrapeCreators, and an actor run to wait on
+ * rather than a plain request, so it is not the default provider. It is here
+ * because plenty of people already have an Apify account and a token, and
+ * because its e-commerce enrichment has no equivalent elsewhere.
+ *
+ * The actor takes an Ad Library URL as `startUrls`, which is the same URL the
+ * browser backend navigates to, so both share `adlibrary/url.ts`.
+ *
+ * Actor input schema read from the live API on 2026-08-31.
+ */
+import { AdLibraryError } from "../errors.js";
+import { adFromApify } from "../adlibrary/normalize.js";
+import { adDetailsUrl, buildUrl } from "../adlibrary/url.js";
+const ACTOR = "apify~facebook-ads-scraper";
+const BASE = "https://api.apify.com/v2";
+export class ApifyBackend {
+    token;
+    options;
+    name = "apify";
+    needsKey = true;
+    constructor(token, options = {}) {
+        this.token = token;
+        this.options = options;
+        if (!token) {
+            throw new AdLibraryError("The apify backend needs a token.", {
+                backend: this.name,
+                hint: "Set APIFY_TOKEN, or use the free browser backend with FBADS_BACKEND=browser.",
+            });
+        }
+    }
+    async close() {
+        // Nothing to release: this backend is stateless fetch calls.
+    }
+    /**
+     * One synchronous actor run, returning its dataset items.
+     *
+     * `run-sync-get-dataset-items` blocks until the run finishes, which is why the
+     * default timeout is generous. Apify caps a sync run at five minutes, so a very
+     * large limit times out rather than returning partial data.
+     */
+    async run(url, limit, details = true) {
+        const endpoint = new URL(`/v2/acts/${ACTOR}/run-sync-get-dataset-items`, BASE);
+        endpoint.searchParams.set("token", this.token);
+        const response = await fetch(endpoint, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({
+                startUrls: [{ url }],
+                resultsLimit: limit,
+                isDetailsPerAd: details,
+                enrichWithEcommerceData: this.options.ecommerce ?? false,
+            }),
+            signal: AbortSignal.timeout(this.options.timeoutMs ?? 300_000),
+        });
+        if (response.status === 401) {
+            throw new AdLibraryError("Apify rejected the token (401).", {
+                backend: this.name,
+                hint: "Check APIFY_TOKEN.",
+            });
+        }
+        if (response.status === 402) {
+            throw new AdLibraryError("Apify reports insufficient credit (402).", {
+                backend: this.name,
+                hint: "Top up the account, or switch to the free browser backend with FBADS_BACKEND=browser.",
+            });
+        }
+        if (response.status === 408) {
+            throw new AdLibraryError("The Apify run exceeded the five-minute synchronous limit.", {
+                backend: this.name,
+                hint: "Lower `limit` and make several calls instead of one large one.",
+            });
+        }
+        if (!response.ok) {
+            const body = (await response.text()).slice(0, 300);
+            throw new AdLibraryError(`Apify error ${response.status}: ${body}`, { backend: this.name });
+        }
+        const items = await response.json();
+        return Array.isArray(items) ? items : [];
+    }
+    async search(params) {
+        if (!params.query && !params.pageId) {
+            throw new AdLibraryError("Pass either query or page_id.", { backend: this.name });
+        }
+        const limit = params.limit ?? 30;
+        const url = buildUrl(params);
+        const items = await this.run(url, limit);
+        const ads = [];
+        const seen = new Set();
+        for (const item of items) {
+            if (typeof item !== "object" || item === null)
+                continue;
+            const ad = adFromApify(item);
+            if (!ad.libraryId || seen.has(ad.libraryId))
+                continue;
+            seen.add(ad.libraryId);
+            ads.push(ad);
+        }
+        const kept = ads.slice(0, limit);
+        return {
+            backend: this.name,
+            count: kept.length,
+            hasMore: false,
+            // The actor paginates internally against resultsLimit and exposes no
+            // cursor, so raise `limit` rather than paging. Said plainly here so
+            // nobody goes hunting for one.
+            cursor: undefined,
+            url,
+            note: kept.length > 0
+                ? "This backend has no cursor. Raise `limit` to get more rather than paging."
+                : "The Apify actor returned no ads for these filters.",
+            ads: kept,
+        };
+    }
+    /** No company-search endpoint on this actor, so derive advertisers from results. */
+    async listAdvertisers(query, country = "US") {
+        const result = await this.search({ query, country, activeStatus: "all", limit: 60 });
+        const byPage = new Map();
+        for (const ad of result.ads) {
+            if (!ad.pageId)
+                continue;
+            const existing = byPage.get(ad.pageId);
+            if (existing) {
+                existing.adCount = (existing.adCount ?? 0) + 1;
+                continue;
+            }
+            byPage.set(ad.pageId, {
+                pageId: ad.pageId,
+                pageName: ad.pageName,
+                pageUrl: ad.pageUrl,
+                pageLikes: ad.pageLikes,
+                profilePictureUrl: ad.pageProfilePictureUrl,
+                adCount: 1,
+            });
+        }
+        return [...byPage.values()].sort((a, b) => (b.adCount ?? 0) - (a.adCount ?? 0));
+    }
+    async getAd(libraryId) {
+        const items = await this.run(adDetailsUrl(libraryId), 1);
+        for (const item of items) {
+            if (typeof item !== "object" || item === null)
+                continue;
+            const ad = adFromApify(item);
+            if (ad.libraryId)
+                return ad;
+        }
+        return undefined;
+    }
+}
+//# sourceMappingURL=apify.js.map

package/dist/backends/apify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"apify.js","sourceRoot":"","sources":["../../src/backends/apify.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AACxD,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAG7D,MAAM,KAAK,GAAG,4BAA4B,CAAC;AAC3C,MAAM,IAAI,GAAG,0BAA0B,CAAC;AAExC,MAAM,OAAO,YAAY;IAKJ;IACA;IALV,IAAI,GAAG,OAAgB,CAAC;IACxB,QAAQ,GAAG,IAAI,CAAC;IAEzB,YACmB,KAAa,EACb,UAAuD,EAAE;QADzD,UAAK,GAAL,KAAK,CAAQ;QACb,YAAO,GAAP,OAAO,CAAkD;QAE1E,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,MAAM,IAAI,cAAc,CAAC,kCAAkC,EAAE;gBAC3D,OAAO,EAAE,IAAI,CAAC,IAAI;gBAClB,IAAI,EAAE,8EAA8E;aACrF,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,KAAK,CAAC,KAAK;QACT,6DAA6D;IAC/D,CAAC;IAED;;;;;;OAMG;IACK,KAAK,CAAC,GAAG,CAAC,GAAW,EAAE,KAAa,EAAE,OAAO,GAAG,IAAI;QAC1D,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,YAAY,KAAK,6BAA6B,EAAE,IAAI,CAAC,CAAC;QAC/E,QAAQ,CAAC,YAAY,CAAC,GAAG,CAAC,OAAO,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC;QAE/C,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,QAAQ,EAAE;YACrC,MAAM,EAAE,MAAM;YACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;YAC/C,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC;gBACnB,SAAS,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC;gBACpB,YAAY,EAAE,KAAK;gBACnB,cAAc,EAAE,OAAO;gBACvB,uBAAuB,EAAE,IAAI,CAAC,OAAO,CAAC,SAAS,IAAI,KAAK;aACzD,CAAC;YACF,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,SAAS,IAAI,OAAO,CAAC;SAC/D,CAAC,CAAC;QAEH,IAAI,QAAQ,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;YAC5B,MAAM,IAAI,cAAc,CAAC,iCAAiC,EAAE;gBAC1D,OAAO,EAAE,IAAI,CAAC,IAAI;gBAClB,IAAI,EAAE,oBAAoB;aAC3B,CAAC,CAAC;QACL,CAAC;QACD,IAAI,QAAQ,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;YAC5B,MAAM,IAAI,cAAc,CAAC,0CAA0C,EAAE;gBACnE,OAAO,EAAE,IAAI,CAAC,IAAI;gBAClB,IAAI,EAAE,uFAAuF;aAC9F,CAAC,CAAC;QACL,CAAC;QACD,IAAI,QAAQ,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;YAC5B,MAAM,IAAI,cAAc,CAAC,2DAA2D,EAAE;gBACpF,OAAO,EAAE,IAAI,CAAC,IAAI;gBAClB,IAAI,EAAE,gEAAgE;aACvE,CAAC,CAAC;QACL,CAAC;QACD,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;YACjB,MAAM,IAAI,GAAG,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;YACnD,MAAM,IAAI,cAAc,CAAC,eAAe,QAAQ,CAAC,MAAM,KAAK,IAAI,EAAE,EAAE,EAAE,OAAO,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;QAC9F,CAAC;QAED,MAAM,KAAK,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;QACpC,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;IAC3C,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,MAAoB;QAC/B,IAAI,CAAC,MAAM,CAAC,KAAK,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC;YACpC,MAAM,IAAI,cAAc,CAAC,+BAA+B,EAAE,EAAE,OAAO,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;QACpF,CAAC;QACD,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,IAAI,EAAE,CAAC;QACjC,MAAM,GAAG,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC;QAC7B,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QAEzC,MAAM,GAAG,GAAS,EAAE,CAAC;QACrB,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;QAC/B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI;gBAAE,SAAS;YACxD,MAAM,EAAE,GAAG,WAAW,CAAC,IAA+B,CAAC,CAAC;YACxD,IAAI,CAAC,EAAE,CAAC,SAAS,IAAI,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,SAAS,CAAC;gBAAE,SAAS;YACtD,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,SAAS,CAAC,CAAC;YACvB,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACf,CAAC;QAED,MAAM,IAAI,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;QACjC,OAAO;YACL,OAAO,EAAE,IAAI,CAAC,IAAI;YAClB,KAAK,EAAE,IAAI,CAAC,MAAM;YAClB,OAAO,EAAE,KAAK;YACd,qEAAqE;YACrE,oEAAoE;YACpE,+BAA+B;YAC/B,MAAM,EAAE,SAAS;YACjB,GAAG;YACH,IAAI,EACF,IAAI,CAAC,MAAM,GAAG,CAAC;gBACb,CAAC,CAAC,2EAA2E;gBAC7E,CAAC,CAAC,oDAAoD;YAC1D,GAAG,EAAE,IAAI;SACV,CAAC;IACJ,CAAC;IAED,oFAAoF;IACpF,KAAK,CAAC,eAAe,CAAC,KAAa,EAAE,OAAO,GAAG,IAAI;QACjD,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,YAAY,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,CAAC;QACrF,MAAM,MAAM,GAAG,IAAI,GAAG,EAAsB,CAAC;QAC7C,KAAK,MAAM,EAAE,IAAI,MAAM,CAAC,GAAG,EAAE,CAAC;YAC5B,IAAI,CAAC,EAAE,CAAC,MAAM;gBAAE,SAAS;YACzB,MAAM,QAAQ,GAAG,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC;YACvC,IAAI,QAAQ,EAAE,CAAC;gBACb,QAAQ,CAAC,OAAO,GAAG,CAAC,QAAQ,CAAC,OAAO,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;gBAC/C,SAAS;YACX,CAAC;YACD,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,MAAM,EAAE;gBACpB,MAAM,EAAE,EAAE,CAAC,MAAM;gBACjB,QAAQ,EAAE,EAAE,CAAC,QAAQ;gBACrB,OAAO,EAAE,EAAE,CAAC,OAAO;gBACnB,SAAS,EAAE,EAAE,CAAC,SAAS;gBACvB,iBAAiB,EAAE,EAAE,CAAC,qBAAqB;gBAC3C,OAAO,EAAE,CAAC;aACX,CAAC,CAAC;QACL,CAAC;QACD,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,OAAO,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,IAAI,CAAC,CAAC,CAAC,CAAC;IAClF,CAAC;IAED,KAAK,CAAC,KAAK,CAAC,SAAiB;QAC3B,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,YAAY,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC,CAAC;QACzD,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI;gBAAE,SAAS;YACxD,MAAM,EAAE,GAAG,WAAW,CAAC,IAA+B,CAAC,CAAC;YACxD,IAAI,EAAE,CAAC,SAAS;gBAAE,OAAO,EAAE,CAAC;QAC9B,CAAC;QACD,OAAO,SAAS,CAAC;IACnB,CAAC;CACF"}

package/dist/backends/browser.d.ts

@@ -0,0 +1,51 @@
+/**
+ * The free backend. No key, no account, no provider.
+ *
+ * How it works, and why it is not what the other Ad Library scrapers do:
+ *
+ * The Ad Library is a React app that receives every ad from Meta as JSON over
+ * GraphQL. The common approach is to let it render, flatten the DOM to markdown
+ * and regex the fields back out. That round trip is lossy: it recovers one
+ * creative per ad, loses the platform list, hands back an l.facebook.com
+ * redirect instead of the real landing page, and breaks whenever Meta ships
+ * markup.
+ *
+ * This backend reads the payload the page was already given. Same browser, same
+ * cost, no parsing.
+ *
+ * Two sources, because Meta uses two. The first page of results is inlined in
+ * the document as a JSON script block and no GraphQL call is made for it; every
+ * page after that arrives as a GraphQL response triggered by scrolling. Reading
+ * only the XHRs makes the first search depend on a scroll landing in time.
+ *
+ * Verified against a live capture on 2026-08-31.
+ */
+import type { Ad, Advertiser, Backend, SearchParams, SearchResult } from "../adlibrary/types.js";
+export type BrowserOptions = {
+    headless?: boolean;
+    hydrateMs?: number;
+    scrollWaitMs?: number;
+};
+export declare class BrowserBackend implements Backend {
+    readonly name: "browser";
+    readonly needsKey = false;
+    private readonly headless;
+    private readonly hydrateMs;
+    private readonly scrollWaitMs;
+    private browser;
+    private queue;
+    constructor(options?: BrowserOptions);
+    private launch;
+    close(): Promise<void>;
+    /** Run one page job at a time, whatever the caller does. */
+    private serialise;
+    private collect;
+    search(params: SearchParams): Promise<SearchResult>;
+    /**
+     * Meta publishes no advertiser-search payload we can rely on, so derive the
+     * list from who is actually running ads for the term. Fewer false hits than a
+     * name lookup, and it only surfaces pages with live creative.
+     */
+    listAdvertisers(query: string, country?: string): Promise<Advertiser[]>;
+    getAd(libraryId: string): Promise<Ad | undefined>;
+}

package/dist/backends/browser.js

@@ -0,0 +1,202 @@
+/**
+ * The free backend. No key, no account, no provider.
+ *
+ * How it works, and why it is not what the other Ad Library scrapers do:
+ *
+ * The Ad Library is a React app that receives every ad from Meta as JSON over
+ * GraphQL. The common approach is to let it render, flatten the DOM to markdown
+ * and regex the fields back out. That round trip is lossy: it recovers one
+ * creative per ad, loses the platform list, hands back an l.facebook.com
+ * redirect instead of the real landing page, and breaks whenever Meta ships
+ * markup.
+ *
+ * This backend reads the payload the page was already given. Same browser, same
+ * cost, no parsing.
+ *
+ * Two sources, because Meta uses two. The first page of results is inlined in
+ * the document as a JSON script block and no GraphQL call is made for it; every
+ * page after that arrives as a GraphQL response triggered by scrolling. Reading
+ * only the XHRs makes the first search depend on a scroll landing in time.
+ *
+ * Verified against a live capture on 2026-08-31.
+ */
+import { AdLibraryError } from "../errors.js";
+import { inlinePayloads, parsePayloads } from "../adlibrary/harvest.js";
+import { adFromGraphql } from "../adlibrary/normalize.js";
+import { adDetailsUrl, buildUrl } from "../adlibrary/url.js";
+const USER_AGENT = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 " +
+    "(KHTML, like Gecko) Chrome/140.0.0.0 Safari/537.36";
+export class BrowserBackend {
+    name = "browser";
+    needsKey = false;
+    headless;
+    hydrateMs;
+    scrollWaitMs;
+    // Launching Chromium costs seconds, so one instance is kept warm across calls.
+    browser;
+    // Meta rate-limits hard on parallel pages, so calls are serialised.
+    queue = Promise.resolve();
+    constructor(options = {}) {
+        this.headless = options.headless ?? true;
+        this.hydrateMs = options.hydrateMs ?? 9000;
+        this.scrollWaitMs = options.scrollWaitMs ?? 4000;
+    }
+    async launch() {
+        if (this.browser)
+            return this.browser;
+        let chromium;
+        try {
+            ({ chromium } = await import("playwright"));
+        }
+        catch {
+            throw new AdLibraryError("The browser backend needs Playwright, which is not installed.", {
+                backend: this.name,
+                hint: "Run `npx playwright install chromium`, or switch to a provider backend " +
+                    "by setting FBADS_BACKEND=scrapecreators and SCRAPECREATORS_API_KEY.",
+            });
+        }
+        try {
+            this.browser = await chromium.launch({ headless: this.headless });
+        }
+        catch (error) {
+            throw new AdLibraryError(`Chromium failed to launch: ${error.message}`, { backend: this.name, hint: "Run `npx playwright install chromium` to install the browser." });
+        }
+        return this.browser;
+    }
+    async close() {
+        if (this.browser) {
+            await this.browser.close().catch(() => undefined);
+            this.browser = undefined;
+        }
+    }
+    /** Run one page job at a time, whatever the caller does. */
+    serialise(job) {
+        const result = this.queue.then(job, job);
+        this.queue = result.then(() => undefined, () => undefined);
+        return result;
+    }
+    async collect(url, limit) {
+        const browser = await this.launch();
+        const context = await browser.newContext({
+            viewport: { width: 1440, height: 1200 },
+            locale: "en-US",
+            userAgent: USER_AGENT,
+        });
+        const bodies = [];
+        try {
+            const page = await context.newPage();
+            page.on("response", (response) => {
+                if (!String(response.url()).includes("/api/graphql"))
+                    return;
+                // A body can vanish when the page navigates. Losing one is survivable;
+                // an unhandled rejection here would take the whole call down.
+                void response
+                    .text()
+                    .then((body) => bodies.push(body))
+                    .catch(() => undefined);
+            });
+            // Meta answers a headless browser with HTTP 403 on the document but still
+            // serves the app and every payload. Judge success by ads parsed, never by status.
+            await page.goto(url, { waitUntil: "domcontentloaded", timeout: 60_000 });
+            await page.waitForTimeout(this.hydrateMs);
+            // The inlined first page. Read once: it does not change as we scroll.
+            bodies.push(...inlinePayloads(await page.content()));
+            let seen = new Set();
+            let stalls = 0;
+            while (stalls < 3) {
+                const harvest = parsePayloads(bodies);
+                const ids = new Set(harvest.nodes.map((node) => String(node["ad_archive_id"])));
+                const sameAsLast = ids.size === seen.size && [...ids].every((id) => seen.has(id));
+                if (ids.size >= limit || (!harvest.hasMore && ids.size > 0 && sameAsLast))
+                    break;
+                stalls = sameAsLast ? stalls + 1 : 0;
+                seen = ids;
+                await page.mouse.wheel(0, 8000);
+                await page.waitForTimeout(this.scrollWaitMs);
+            }
+            await page.close();
+        }
+        finally {
+            await context.close().catch(() => undefined);
+        }
+        return parsePayloads(bodies);
+    }
+    async search(params) {
+        if (!params.query && !params.pageId) {
+            throw new AdLibraryError("Pass either query or page_id.", { backend: this.name });
+        }
+        const limit = params.limit ?? 30;
+        const url = buildUrl(params);
+        const harvest = await this.serialise(() => this.collect(url, limit));
+        const ads = [];
+        const seen = new Set();
+        for (const node of harvest.nodes) {
+            const ad = adFromGraphql(node);
+            if (!ad.libraryId || seen.has(ad.libraryId))
+                continue;
+            seen.add(ad.libraryId);
+            ads.push(ad);
+        }
+        let note;
+        if (harvest.captcha) {
+            note =
+                "Meta served a captcha instead of results, so nothing could be read. Wait a few " +
+                    "minutes, or use a provider backend, which is not affected.";
+        }
+        else if (ads.length === 0) {
+            note = harvest.total
+                ? `No ads captured even though Meta reports ${harvest.total} matching. Retry in a minute.`
+                : "No ads captured. Either this search genuinely has no results, or Meta declined " +
+                    "to serve them. Open the `url` in a browser to tell the two apart.";
+        }
+        else if (harvest.total && harvest.total > ads.length) {
+            note = `Meta reports ${harvest.total} matching ads. Raise \`limit\` for more.`;
+        }
+        const kept = ads.slice(0, limit);
+        return {
+            backend: this.name,
+            count: kept.length,
+            hasMore: harvest.hasMore || ads.length > limit,
+            cursor: harvest.cursor,
+            totalAvailable: harvest.total,
+            url,
+            note,
+            ads: kept,
+        };
+    }
+    /**
+     * Meta publishes no advertiser-search payload we can rely on, so derive the
+     * list from who is actually running ads for the term. Fewer false hits than a
+     * name lookup, and it only surfaces pages with live creative.
+     */
+    async listAdvertisers(query, country = "US") {
+        const result = await this.search({ query, country, activeStatus: "all", limit: 60 });
+        const byPage = new Map();
+        for (const ad of result.ads) {
+            if (!ad.pageId)
+                continue;
+            const existing = byPage.get(ad.pageId);
+            if (existing) {
+                existing.adCount = (existing.adCount ?? 0) + 1;
+                continue;
+            }
+            byPage.set(ad.pageId, {
+                pageId: ad.pageId,
+                pageName: ad.pageName,
+                pageUrl: ad.pageUrl,
+                pageLikes: ad.pageLikes,
+                category: ad.pageCategories[0],
+                profilePictureUrl: ad.pageProfilePictureUrl,
+                adCount: 1,
+            });
+        }
+        return [...byPage.values()].sort((a, b) => (b.adCount ?? 0) - (a.adCount ?? 0));
+    }
+    async getAd(libraryId) {
+        const harvest = await this.serialise(() => this.collect(adDetailsUrl(libraryId), 1));
+        const match = harvest.nodes.find((node) => String(node["ad_archive_id"]) === String(libraryId));
+        const node = match ?? harvest.nodes[0];
+        return node ? adFromGraphql(node) : undefined;
+    }
+}
+//# sourceMappingURL=browser.js.map

package/dist/backends/browser.js.map

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

package/dist/backends/index.d.ts

@@ -0,0 +1,8 @@
+/** Picking a backend, failing with a message that names the fix. */
+import type { Backend } from "../adlibrary/types.js";
+import type { Config } from "../config.js";
+import { ApifyBackend } from "./apify.js";
+import { BrowserBackend } from "./browser.js";
+import { ScrapeCreatorsBackend } from "./scrapecreators.js";
+export declare function createBackend(config: Config): Backend;
+export { ApifyBackend, BrowserBackend, ScrapeCreatorsBackend };

package/dist/backends/index.js

@@ -0,0 +1,25 @@
+/** Picking a backend, failing with a message that names the fix. */
+import { AdLibraryError } from "../errors.js";
+import { ApifyBackend } from "./apify.js";
+import { BrowserBackend } from "./browser.js";
+import { ScrapeCreatorsBackend } from "./scrapecreators.js";
+export function createBackend(config) {
+    switch (config.backend) {
+        case "browser":
+            return new BrowserBackend({
+                headless: config.headless,
+                hydrateMs: config.hydrateMs,
+                scrollWaitMs: config.scrollWaitMs,
+            });
+        case "scrapecreators":
+            return new ScrapeCreatorsBackend(config.scrapeCreatorsKey ?? "");
+        case "apify":
+            return new ApifyBackend(config.apifyToken ?? "");
+        default:
+            throw new AdLibraryError(`Unknown backend ${String(config.backend)}.`, {
+                hint: "FBADS_BACKEND must be browser, scrapecreators or apify.",
+            });
+    }
+}
+export { ApifyBackend, BrowserBackend, ScrapeCreatorsBackend };
+//# sourceMappingURL=index.js.map

package/dist/backends/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/backends/index.ts"],"names":[],"mappings":"AAAA,oEAAoE;AAEpE,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAG9C,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAE5D,MAAM,UAAU,aAAa,CAAC,MAAc;IAC1C,QAAQ,MAAM,CAAC,OAAO,EAAE,CAAC;QACvB,KAAK,SAAS;YACZ,OAAO,IAAI,cAAc,CAAC;gBACxB,QAAQ,EAAE,MAAM,CAAC,QAAQ;gBACzB,SAAS,EAAE,MAAM,CAAC,SAAS;gBAC3B,YAAY,EAAE,MAAM,CAAC,YAAY;aAClC,CAAC,CAAC;QACL,KAAK,gBAAgB;YACnB,OAAO,IAAI,qBAAqB,CAAC,MAAM,CAAC,iBAAiB,IAAI,EAAE,CAAC,CAAC;QACnE,KAAK,OAAO;YACV,OAAO,IAAI,YAAY,CAAC,MAAM,CAAC,UAAU,IAAI,EAAE,CAAC,CAAC;QACnD;YACE,MAAM,IAAI,cAAc,CAAC,mBAAmB,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,GAAG,EAAE;gBACrE,IAAI,EAAE,yDAAyD;aAChE,CAAC,CAAC;IACP,CAAC;AACH,CAAC;AAED,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,qBAAqB,EAAE,CAAC"}

package/dist/backends/scrapecreators.d.ts

@@ -0,0 +1,29 @@
+/**
+ * ScrapeCreators backend. Needs a key, works serverless, about $1.88 per 1,000 ads.
+ *
+ * Use this instead of the browser when Chromium cannot run (a serverless
+ * function, a container without a browser) or when the volume makes babysitting
+ * Meta's rate limits not worth it.
+ *
+ * Request parameters are taken from their published OpenAPI spec, read
+ * 2026-08-31. Their *response* envelope is not published, so nothing here
+ * assumes a path into it: we walk the payload for ad-shaped objects. See
+ * `adlibrary/harvest.ts`.
+ *
+ * One thing this backend can do that the browser cannot: `transcribe`, which is
+ * server-side speech to text on a video ad.
+ */
+import type { Ad, Advertiser, Backend, SearchParams, SearchResult } from "../adlibrary/types.js";
+export declare class ScrapeCreatorsBackend implements Backend {
+    private readonly apiKey;
+    private readonly timeoutMs;
+    readonly name: "scrapecreators";
+    readonly needsKey = true;
+    constructor(apiKey: string, timeoutMs?: number);
+    close(): Promise<void>;
+    private get;
+    search(params: SearchParams): Promise<SearchResult>;
+    listAdvertisers(query: string): Promise<Advertiser[]>;
+    getAd(libraryId: string): Promise<Ad | undefined>;
+    transcribe(libraryId: string): Promise<string | undefined>;
+}