facebook-scraper-api 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 SocialAPIsHub
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,194 @@
1
- # Temporary Holding Version
1
+ # facebook-scraper-js
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ [![facebook-scraper-api on npm](https://img.shields.io/npm/v/facebook-scraper-api?label=facebook-scraper-api&logo=npm)](https://www.npmjs.com/package/facebook-scraper-api)
4
+ [![npm](https://img.shields.io/npm/v/socialapis-sdk?cacheSeconds=300&label=npm&logo=npm)](https://www.npmjs.com/package/socialapis-sdk)
5
+ [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
6
+ [![Node](https://img.shields.io/badge/node-%3E%3D18-blue.svg)](https://nodejs.org)
7
+
8
+ > Modern TypeScript/JavaScript alternative to abandoned Node.js Facebook scrapers — `facebook-scraper-with-puppeteer`, `node-facebook-scraper`, and the long tail of dead packages that broke when Meta last changed their interface. Hosted backend means it doesn't break next time either, **and you don't need Instagram credentials, OAuth tokens, or Puppeteer at all**.
9
+
10
+ This repo ships the **`facebook-scraper-api`** package: Page details, Page and group posts, reels, videos, comments and search, with pagination handled for you and a command-line tool. TypeScript types included.
11
+
12
+ ```bash
13
+ npm install facebook-scraper-api
14
+ export SOCIALAPIS_TOKEN=your_key
15
+ ```
16
+
17
+ ```js
18
+ import { FacebookScraperAPI } from "facebook-scraper-api";
19
+
20
+ const fb = new FacebookScraperAPI(); // or new FacebookScraperAPI({ apiToken: "..." })
21
+ const page = await fb.getPageInfo("EngenSA");
22
+ console.log(page.title, page.followers_count);
23
+
24
+ // Follows the cursor: 1 API call per page, stops when there are no more posts
25
+ for await (const post of fb.getPosts("EngenSA", { pages: 2, limit: 9 })) {
26
+ console.log(post);
27
+ }
28
+ ```
29
+
30
+ ```bash
31
+ npx facebook-scraper-api posts EngenSA --pages 3 --limit 9 --out posts.csv
32
+ npx facebook-scraper-api comments https://www.facebook.com/EngenSA/posts/123 --format jsonl
33
+ ```
34
+
35
+ | Method | Returns |
36
+ |---|---|
37
+ | `getPageInfo(account)` / `getGroupInfo(group)` | Page / public group details |
38
+ | `getPosts(account, { pages, limit, after, before })` | A Page's posts, newest first (limit 3-9 per call, cost round(limit ÷ 3) credits) |
39
+ | `getGroupPosts(group, { … })` | A public group's posts |
40
+ | `getReels(account)` / `getVideos(account)` | A Page's reels / videos |
41
+ | `getPost(postUrl, { extended })` / `getComments(postUrl)` | One post / its comments |
42
+ | `searchPosts(query)` / `searchPages(query)` | Keyword search |
43
+
44
+ Listings are async generators; `pages` (default 1) caps the API calls. Failed calls (4xx / 5xx) are not charged. Need Instagram, Marketplace or the Ads Library too? Use the full SDK, [`socialapis-sdk`](https://www.npmjs.com/package/socialapis-sdk) ([source](https://github.com/SocialAPIsHub/socialapis-js)); the rest of this page shows the migration with it. Ads only: [`facebook-ads-library-api`](https://www.npmjs.com/package/facebook-ads-library-api).
45
+
46
+ **[Get a free API token →](https://socialapis.io/auth/signup)** — 200 calls/month, no credit card
47
+
48
+ ---
49
+
50
+ ## Why this exists
51
+
52
+ The Node.js Facebook-scraping ecosystem is a graveyard. Pick almost any popular package and you'll find:
53
+
54
+ - Last commit ~2-3 years old
55
+ - Open issues piling up about Meta's latest HTML change
56
+ - README still says "works as of 2021"
57
+ - PRs that fix one selector and break two others, sitting unmerged
58
+
59
+ If you're here because:
60
+
61
+ - Your old scraper returns empty arrays or `undefined`
62
+ - You searched for "facebook scraper node alternative" or "facebook-scraper-with-puppeteer fork"
63
+ - You're tired of running Puppeteer just to get a page's follower count
64
+ - Your scraper got blocked once Meta updated detection
65
+ - You don't want to manage Facebook OAuth, login cookies, or Graph API app review
66
+
67
+ …this is the modern replacement. Same idea (Facebook public data via Node.js) but the actual scraping runs on a hosted API ([socialapis.io](https://socialapis.io)) — so when Meta changes their HTML, **we fix it**. Your code doesn't change.
68
+
69
+ ## Side-by-side migration
70
+
71
+ ```ts
72
+ // BEFORE — Puppeteer-based scraping (fragile, slow, breaks on every Meta change)
73
+ import puppeteer from "puppeteer";
74
+
75
+ const browser = await puppeteer.launch();
76
+ const page = await browser.newPage();
77
+ await page.goto("https://www.facebook.com/EngenSA");
78
+ const data = await page.evaluate(() => {
79
+ // ...50 lines of brittle DOM selectors...
80
+ });
81
+ await browser.close();
82
+ ```
83
+
84
+ ```ts
85
+ // AFTER — socialapis-sdk (one HTTP call, typed response, no browser)
86
+ import { FacebookScraper } from "socialapis-sdk";
87
+
88
+ const fb = new FacebookScraper({ apiToken: "..." });
89
+ const page = await fb.getPageInfo("EngenSA");
90
+ // page.title, page.followers_count, page.likes_count, page.bio, ...
91
+ // All typed, IDE autocomplete, no HTML parsing, no headless browser
92
+ ```
93
+
94
+ `FacebookScraper` is an exact alias of `Facebook` from `socialapis-sdk` — identical class, identical methods, just a different name so your grep-replace migration stays a one-liner.
95
+
96
+ Full working example: [`examples/migrate.ts`](examples/migrate.ts).
97
+
98
+ ## Method-by-method mapping
99
+
100
+ | Common Node.js scraper API | `socialapis-sdk` |
101
+ |---|---|
102
+ | `getPageInfo(page)` / scraping `<title>` + counts | `new FacebookScraper({apiToken}).getPageInfo(page)` |
103
+ | `getPagePosts(page)` / scraping post feed | `.getPagePosts(page)` |
104
+ | Page videos via scrape | `.getPageVideos(page)` |
105
+ | Group details via Puppeteer | `.getGroupDetails(group)` |
106
+ | Group posts via scrape | `.getGroupPosts(group)` |
107
+ | Meta Ad Library scraping | `.searchAds(query, { country: "US" })` |
108
+ | Marketplace scraping | `.searchMarketplace(query, { ... })` |
109
+ | Login cookies / Puppeteer auth | **Not needed** — hosted backend handles it |
110
+ | User-Agent rotation / proxy mgmt | **Not needed** — we manage the scraping infra |
111
+ | Headless browser | **Not needed** — single HTTP call |
112
+
113
+ ## What you get on top of common scrapers
114
+
115
+ The hosted API exposes 35 Facebook endpoints + 13 Instagram + 3 Account, all from the same SDK. From the `FacebookScraper` (or `Facebook`) instance:
116
+
117
+ ```ts
118
+ // Search — pages, people, posts, videos, locations
119
+ await fb.searchPages("marketing", { location_id: "103006566409959" });
120
+ await fb.searchPosts("nike", { recency: "last_month" });
121
+
122
+ // Meta Ads Library (full transparency data — creative, spend, impressions)
123
+ await fb.searchAds("fitness", { country: "US", activeStatus: "Active" });
124
+ await fb.getAdArchiveDetails("...", "...");
125
+
126
+ // Marketplace (listings, vehicles, rentals)
127
+ await fb.searchMarketplace("cars", {
128
+ filter_location_latitude: "40.7142",
129
+ filter_location_longitude: "-74.0064",
130
+ });
131
+ await fb.getListingDetails("123456789");
132
+
133
+ // Reels
134
+ await fb.getPageReels("EngenSA");
135
+ ```
136
+
137
+ Full method list + TypeScript response types: [main SDK README →](https://github.com/SocialAPIsHub/socialapis-js#readme)
138
+
139
+ ## Comparison at a glance
140
+
141
+ | | Typical Node scraper (Puppeteer-based) | `socialapis-sdk` (2026) |
142
+ |---|---|---|
143
+ | **Setup** | `puppeteer`, `puppeteer-extra`, stealth plugins | `npm install socialapis-sdk` |
144
+ | **Maintenance** | Mostly abandoned | Active; 7M+ calls/month in prod |
145
+ | **Reliability** | Breaks on every Meta change | Hosted backend; we absorb breakage |
146
+ | **Type hints** | Manual `interface { ... }` | Strict TypeScript types ship with the package |
147
+ | **HTTP client** | Headless browser + page evaluation | Native `fetch` |
148
+ | **Auth** | Login cookies / app review / OAuth | Single `x-api-token` header, 200 free calls/month |
149
+ | **Browser dependency** | Headless Chrome (~150MB) | None |
150
+ | **Bundle size impact** | Server-only — can't ship to browsers | Works in Node 18+, browsers, Bun, Deno |
151
+ | **Memory footprint** | ~300MB+ per Puppeteer instance | ~5MB |
152
+ | **Detection risk** | High — fingerprinted, captcha walls | None — we handle it |
153
+ | **Surface area** | Whatever you can scrape (fragile) | 35 Facebook endpoints + 13 IG + Account |
154
+
155
+ ## Pricing
156
+
157
+ | Tier | Calls / month | Price |
158
+ |---|---|---|
159
+ | **Free** | 200 | $0 |
160
+ | Pro | 1,500 | $4.99 |
161
+ | Ultra | 30,000 | $49 |
162
+ | Mega | 120,000 | $179 |
163
+ | Enterprise | Custom | [Contact us](https://socialapis.io/contact-us) |
164
+
165
+ One credit per successful call. Failed calls (4xx caused by bad input) don't consume credits.
166
+
167
+ ## Free live follower badge
168
+
169
+ Show a public Facebook Page's follower count on your website or README, updated about once a day. No API key, no account.
170
+
171
+ [![NASA Facebook followers](https://socialapis.io/badge/facebook/nasa.svg)](https://socialapis.io/tools/facebook-follower-count?utm_source=github&utm_medium=readme&utm_campaign=badges)
172
+
173
+ ```markdown
174
+ [![Facebook followers](https://socialapis.io/badge/facebook/<page>.svg)](https://socialapis.io/tools/facebook-follower-count)
175
+ ```
176
+
177
+ Options: `?theme=dark`, `?style=flat`, `?label=Your%20text`. Get the HTML, Markdown or forum code for any Page on the [Facebook follower count checker](https://socialapis.io/tools/facebook-follower-count?utm_source=github&utm_medium=readme&utm_campaign=badges).
178
+
179
+ ## Other resources
180
+
181
+ - **Full SDK source + docs**: [SocialAPIsHub/socialapis-js](https://github.com/SocialAPIsHub/socialapis-js)
182
+ - **Python SDK** (PyPI `socialapis-sdk`): [SocialAPIsHub/socialapis-python](https://github.com/SocialAPIsHub/socialapis-python)
183
+ - **Go SDK**: [SocialAPIsHub/socialapis-go](https://github.com/SocialAPIsHub/socialapis-go)
184
+ - **Hosted API docs**: [docs.socialapis.io](https://docs.socialapis.io)
185
+ - **Endpoint catalog (50+ endpoints)**: [socialapis.io/api-sources](https://socialapis.io/api-sources)
186
+ - **Status page**: [socialapis.io/status](https://socialapis.io/status)
187
+ - **Telegram (fastest support)**: [t.me/socialapis](https://t.me/socialapis)
188
+ - **Email**: [support@socialapis.io](mailto:support@socialapis.io)
189
+
190
+ ## License
191
+
192
+ MIT — see [LICENSE](LICENSE).
193
+
194
+ The `socialapis-sdk` package this repo points at is also MIT-licensed. Both are open source; the hosted scraping API is the commercial layer.
@@ -0,0 +1,7 @@
1
+ #!/usr/bin/env node
2
+ import { main } from "../src/cli.js";
3
+
4
+ main().catch((err) => {
5
+ process.stderr.write(`error: ${err.message}\n`);
6
+ process.exitCode = 1;
7
+ });
package/package.json CHANGED
@@ -1,6 +1,52 @@
1
1
  {
2
2
  "name": "facebook-scraper-api",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.0",
4
+ "description": "Facebook scraper API for Node.js: public Pages, posts, groups, reels, comments and search, with no login, cookies or Puppeteer.",
5
+ "keywords": [
6
+ "facebook-scraper",
7
+ "facebook-scraper-api",
8
+ "facebook-api",
9
+ "facebook-posts",
10
+ "facebook-pages",
11
+ "facebook-groups",
12
+ "facebook-comments",
13
+ "puppeteer-alternative",
14
+ "scraping",
15
+ "socialapis"
16
+ ],
17
+ "homepage": "https://github.com/SocialAPIsHub/facebook-scraper-js#readme",
18
+ "repository": {
19
+ "type": "git",
20
+ "url": "git+https://github.com/SocialAPIsHub/facebook-scraper-js.git"
21
+ },
22
+ "bugs": "https://github.com/SocialAPIsHub/facebook-scraper-js/issues",
23
+ "license": "MIT",
24
+ "author": "SocialAPIs <support@socialapis.io> (https://socialapis.io)",
25
+ "type": "module",
26
+ "exports": {
27
+ ".": {
28
+ "types": "./src/index.d.ts",
29
+ "default": "./src/index.js"
30
+ }
31
+ },
32
+ "types": "./src/index.d.ts",
33
+ "bin": {
34
+ "facebook-scraper-api": "bin/facebook-scraper-api.js"
35
+ },
36
+ "files": [
37
+ "src",
38
+ "bin",
39
+ "README.md",
40
+ "LICENSE"
41
+ ],
42
+ "engines": {
43
+ "node": ">=18.3"
44
+ },
45
+ "sideEffects": false,
46
+ "scripts": {
47
+ "test": "node --test test/*.test.js"
48
+ },
49
+ "dependencies": {
50
+ "socialapis-sdk": "^0.1.3"
51
+ }
52
+ }
package/src/cli.js ADDED
@@ -0,0 +1,92 @@
1
+ // Command line: Facebook Pages, posts, groups, reels and comments to CSV or JSON lines.
2
+ //
3
+ // npx facebook-scraper-api page nasa
4
+ // npx facebook-scraper-api posts nasa --pages 3 --limit 9 --out nasa.csv
5
+ // npx facebook-scraper-api comments https://www.facebook.com/nasa/posts/123 --format jsonl
6
+ //
7
+ // The API key comes from --token or the SOCIALAPIS_TOKEN environment variable.
8
+
9
+ import { writeFileSync } from "node:fs";
10
+ import { parseArgs } from "node:util";
11
+ import { FacebookScraperAPI, toCsv, VERSION } from "./index.js";
12
+
13
+ const HELP = `facebook-scraper-api ${VERSION}: public Facebook data without a login or browser
14
+
15
+ Usage:
16
+ facebook-scraper-api page <Page URL | username> details (JSON)
17
+ facebook-scraper-api group <group URL | id> details (JSON)
18
+ facebook-scraper-api posts <Page URL | username> Page posts
19
+ facebook-scraper-api group-posts <group URL | id> group posts
20
+ facebook-scraper-api reels <Page URL | username>
21
+ facebook-scraper-api videos <Page URL | username>
22
+ facebook-scraper-api comments <post URL>
23
+ facebook-scraper-api search-posts <keyword>
24
+ facebook-scraper-api search-pages <keyword>
25
+
26
+ Options:
27
+ --pages <n> API calls to make (default 1)
28
+ --limit <n> posts per call, 3-9 (posts / group-posts; cost round(limit / 3) credits per call)
29
+ --after <time> only posts after this time (ISO 8601)
30
+ --before <time> only posts before this time (ISO 8601)
31
+ --format <f> csv (default) or jsonl
32
+ --out <file> file to write (default: standard output)
33
+ --token <key> SocialAPIs API key (default: $SOCIALAPIS_TOKEN)
34
+
35
+ Free API key (200 calls/month): https://socialapis.io/auth/signup`;
36
+
37
+ export async function main(argv = process.argv.slice(2), out = process.stdout) {
38
+ const { values, positionals } = parseArgs({
39
+ args: argv,
40
+ allowPositionals: true,
41
+ options: {
42
+ pages: { type: "string", default: "1" },
43
+ limit: { type: "string" },
44
+ after: { type: "string" },
45
+ before: { type: "string" },
46
+ format: { type: "string", default: "csv" },
47
+ out: { type: "string" },
48
+ token: { type: "string" },
49
+ help: { type: "boolean", short: "h" },
50
+ version: { type: "boolean", short: "v" },
51
+ },
52
+ });
53
+ if (values.version) return void out.write(`${VERSION}\n`);
54
+ const [command, target] = positionals;
55
+ if (values.help || !command) return void out.write(`${HELP}\n`);
56
+ if (!target) throw new RangeError(`${command} needs an argument (see --help)`);
57
+ if (!["csv", "jsonl"].includes(values.format)) throw new RangeError("--format is csv or jsonl");
58
+
59
+ const fb = new FacebookScraperAPI({ apiToken: values.token });
60
+ if (command === "page" || command === "group") {
61
+ const info = command === "page" ? await fb.getPageInfo(target) : await fb.getGroupInfo(target);
62
+ return void out.write(`${JSON.stringify(info, null, 2)}\n`);
63
+ }
64
+
65
+ const pages = Number(values.pages);
66
+ const postOptions = {
67
+ pages,
68
+ limit: values.limit === undefined ? undefined : Number(values.limit),
69
+ after: values.after,
70
+ before: values.before,
71
+ };
72
+ const listings = {
73
+ posts: () => fb.getPosts(target, postOptions),
74
+ "group-posts": () => fb.getGroupPosts(target, postOptions),
75
+ reels: () => fb.getReels(target, { pages }),
76
+ videos: () => fb.getVideos(target, { pages }),
77
+ comments: () => fb.getComments(target, { pages }),
78
+ "search-posts": () => fb.searchPosts(target, { pages }),
79
+ "search-pages": () => fb.searchPages(target, { pages }),
80
+ };
81
+ if (!listings[command]) throw new RangeError(`unknown command "${command}" (see --help)`);
82
+
83
+ const records = [];
84
+ for await (const record of listings[command]()) records.push(record);
85
+ const text = values.format === "csv" ? toCsv(records) : records.map((r) => `${JSON.stringify(r)}\n`).join("");
86
+ if (values.out) {
87
+ writeFileSync(values.out, text);
88
+ process.stderr.write(`${records.length} rows written to ${values.out}\n`);
89
+ } else {
90
+ out.write(text);
91
+ }
92
+ }
package/src/index.d.ts ADDED
@@ -0,0 +1,55 @@
1
+ import type { Facebook, GroupInfo, PageInfo } from "socialapis-sdk";
2
+
3
+ export declare const VERSION: string;
4
+
5
+ /** One record as the API returns it (fields vary by endpoint; extra fields are kept). */
6
+ export type FacebookRecord = Record<string, any>;
7
+
8
+ export interface ListOptions {
9
+ /** How many API calls to make at most (default 1). */
10
+ pages?: number;
11
+ /** Any other query parameter of the endpoint (see socialapis.io/api-sources). */
12
+ [param: string]: unknown;
13
+ }
14
+
15
+ export interface PostListOptions extends ListOptions {
16
+ /** Posts per call, 3-9 (default 3). Cost: round(limit / 3) credits per call. */
17
+ limit?: number;
18
+ /** ISO 8601 timestamp. */
19
+ after?: string;
20
+ /** ISO 8601 timestamp. */
21
+ before?: string;
22
+ }
23
+
24
+ export interface FacebookScraperAPIOptions {
25
+ /** Defaults to process.env.SOCIALAPIS_TOKEN. */
26
+ apiToken?: string;
27
+ fetch?: typeof fetch;
28
+ client?: Facebook;
29
+ }
30
+
31
+ type Listing = AsyncGenerator<FacebookRecord, void, unknown>;
32
+
33
+ export declare class FacebookScraperAPI {
34
+ constructor(opts?: FacebookScraperAPIOptions);
35
+ getPageInfo(account: string, extra?: Record<string, unknown>): Promise<PageInfo>;
36
+ getGroupInfo(group: string, extra?: Record<string, unknown>): Promise<GroupInfo>;
37
+ getPost(postUrl: string, options?: { extended?: boolean; [param: string]: unknown }): Promise<FacebookRecord>;
38
+ getPosts(account: string, options?: PostListOptions): Listing;
39
+ getGroupPosts(group: string, options?: PostListOptions): Listing;
40
+ getReels(account: string, options?: ListOptions): Listing;
41
+ getVideos(account: string, options?: ListOptions): Listing;
42
+ getComments(postUrl: string, options?: ListOptions): Listing;
43
+ searchPosts(query: string, options?: ListOptions): Listing;
44
+ searchPages(query: string, options?: ListOptions): Listing;
45
+ }
46
+
47
+ export declare function itemsOf(body: unknown): FacebookRecord[];
48
+ export declare function recordOf(body: unknown): FacebookRecord;
49
+ export declare function flatten(record: FacebookRecord): Record<string, string | number | boolean>;
50
+ export declare function toCsv(records: FacebookRecord[]): string;
51
+ export declare function nextCursor(body: unknown): string | null;
52
+ export declare function paginate<T>(
53
+ fetchPage: (cursor: string | null) => Promise<T>,
54
+ pages: number,
55
+ ): AsyncGenerator<T, void, unknown>;
package/src/index.js ADDED
@@ -0,0 +1,116 @@
1
+ // Facebook scraper API for Node.js: public Pages, posts, groups, reels,
2
+ // comments and search.
3
+ //
4
+ // The data comes from a hosted API, so nothing breaks when Facebook changes
5
+ // its pages: no login, no cookies, no Puppeteer, no proxies. Powered by
6
+ // SocialAPIs (https://socialapis.io).
7
+ //
8
+ // import { FacebookScraperAPI } from "facebook-scraper-api";
9
+ //
10
+ // const fb = new FacebookScraperAPI(); // reads SOCIALAPIS_TOKEN
11
+ // console.log((await fb.getPageInfo("nasa")).followers_count);
12
+ // for await (const post of fb.getPosts("nasa", { pages: 2 })) console.log(post);
13
+ //
14
+ // Free API key (200 calls/month, no card): https://socialapis.io/auth/signup
15
+
16
+ import { Facebook } from "socialapis-sdk";
17
+ import { itemsOf, recordOf } from "./items.js";
18
+ import { paginate } from "./paging.js";
19
+
20
+ export { flatten, itemsOf, recordOf, toCsv } from "./items.js";
21
+ export { nextCursor, paginate } from "./paging.js";
22
+ export const VERSION = "0.1.0";
23
+
24
+ export class FacebookScraperAPI {
25
+ /**
26
+ * @param {{ apiToken?: string, fetch?: typeof fetch, client?: Facebook }} [opts]
27
+ * apiToken defaults to process.env.SOCIALAPIS_TOKEN.
28
+ */
29
+ constructor(opts = {}) {
30
+ if (opts.client) {
31
+ this.fb = opts.client;
32
+ return;
33
+ }
34
+ const apiToken = opts.apiToken || (typeof process !== "undefined" ? process.env.SOCIALAPIS_TOKEN : undefined);
35
+ if (!apiToken) {
36
+ throw new Error(
37
+ "Pass { apiToken } or set SOCIALAPIS_TOKEN. Get a free key at https://socialapis.io/auth/signup (200 calls/month, no card).",
38
+ );
39
+ }
40
+ this.fb = new Facebook({ apiToken, fetch: opts.fetch });
41
+ }
42
+
43
+ async *#items(call, pages, params = {}) {
44
+ for await (const body of paginate((cursor) => call({ ...params, end_cursor: cursor ?? undefined }), pages)) {
45
+ yield* itemsOf(body);
46
+ }
47
+ }
48
+
49
+ // ---- single records ------------------------------------------------------
50
+
51
+ /** A Page's public details: name, followers, likes, category, contact, links. */
52
+ getPageInfo(account, extra) {
53
+ return this.fb.getPageInfo(account, extra);
54
+ }
55
+
56
+ /** A public group's details: name, members, privacy, description. */
57
+ getGroupInfo(group, extra) {
58
+ return this.fb.getGroupDetails(group, extra);
59
+ }
60
+
61
+ /** One post's details ({ extended: true } adds views, video URLs, music). */
62
+ async getPost(postUrl, { extended = false, ...extra } = {}) {
63
+ const body = extended
64
+ ? await this.fb.getPostDetailsExtended(postUrl, extra)
65
+ : await this.fb.getPostDetails(postUrl, extra);
66
+ return recordOf(body);
67
+ }
68
+
69
+ // ---- listings (async generators, 1 API call per page) ----------------------
70
+
71
+ /**
72
+ * Recent posts of a Page, newest first. `limit` is posts per call (3-9,
73
+ * default 3; cost round(limit / 3) credits per call); `after` / `before` are
74
+ * ISO 8601 timestamps.
75
+ */
76
+ getPosts(account, options = {}) {
77
+ return this.#posts((p) => this.fb.getPagePosts(account, p), options);
78
+ }
79
+
80
+ /** Recent posts of a public group. Same options as getPosts. */
81
+ getGroupPosts(group, options = {}) {
82
+ return this.#posts((p) => this.fb.getGroupPosts(group, p), options);
83
+ }
84
+
85
+ #posts(call, { pages = 1, limit, after, before, ...extra }) {
86
+ if (limit !== undefined && !(Number.isInteger(limit) && limit >= 3 && limit <= 9)) {
87
+ throw new RangeError("limit is posts per call, from 3 to 9");
88
+ }
89
+ return this.#items(call, pages, { ...extra, limit, after_time: after, before_time: before });
90
+ }
91
+
92
+ /** A Page's reels. */
93
+ getReels(account, { pages = 1, ...extra } = {}) {
94
+ return this.#items((p) => this.fb.getPageReels(account, p), pages, extra);
95
+ }
96
+
97
+ /** A Page's long-form videos. */
98
+ getVideos(account, { pages = 1, ...extra } = {}) {
99
+ return this.#items((p) => this.fb.getPageVideos(account, p), pages, extra);
100
+ }
101
+
102
+ /** Top-level comments on a post or reel. */
103
+ getComments(postUrl, { pages = 1, ...extra } = {}) {
104
+ return this.#items((p) => this.fb.getPostComments(postUrl, p), pages, extra);
105
+ }
106
+
107
+ /** Public posts matching a keyword. */
108
+ searchPosts(query, { pages = 1, ...extra } = {}) {
109
+ return this.#items((p) => this.fb.searchPosts(query, p), pages, extra);
110
+ }
111
+
112
+ /** Pages matching a keyword. */
113
+ searchPages(query, { pages = 1, ...extra } = {}) {
114
+ return this.#items((p) => this.fb.searchPages(query, p), pages, extra);
115
+ }
116
+ }
package/src/items.js ADDED
@@ -0,0 +1,71 @@
1
+ // Find the records in an answer and flatten them for CSV.
2
+ //
3
+ // Endpoints wrap their list under different keys (`posts`, `items`, `videos`,
4
+ // …), so instead of a per-endpoint path we take the longest list of objects in
5
+ // the answer, outside our own `meta` / `message` envelope. The same rule reads
6
+ // live answers in the SocialAPIs Google Sheets add-on.
7
+
8
+ import { ENVELOPE_KEYS } from "./paging.js";
9
+
10
+ const isRecord = (x) => x !== null && typeof x === "object" && !Array.isArray(x);
11
+
12
+ function bestList(node, depth) {
13
+ if (depth > 3) return null;
14
+ if (Array.isArray(node)) return node.length && node.every(isRecord) ? node : null;
15
+ if (!isRecord(node)) return null;
16
+ let best = null;
17
+ for (const [key, value] of Object.entries(node)) {
18
+ if (ENVELOPE_KEYS.includes(key)) continue;
19
+ const found = bestList(value, depth + 1);
20
+ if (found && (!best || found.length > best.length)) best = found;
21
+ }
22
+ return best;
23
+ }
24
+
25
+ /** The records of one answer (posts, comments, videos…), or []. */
26
+ export function itemsOf(body) {
27
+ return bestList(body, 0) || [];
28
+ }
29
+
30
+ /** A single-record answer without our envelope (and its "0" / data wrapper). */
31
+ export function recordOf(body) {
32
+ if (!isRecord(body)) return {};
33
+ for (const key of ["0", "data"]) if (isRecord(body[key])) return body[key];
34
+ return Object.fromEntries(Object.entries(body).filter(([k]) => !ENVELOPE_KEYS.includes(k)));
35
+ }
36
+
37
+ function cell(value) {
38
+ if (value === null || value === undefined) return "";
39
+ if (["string", "number", "boolean"].includes(typeof value)) return value;
40
+ if (Array.isArray(value) && value.every((x) => x === null || typeof x !== "object")) {
41
+ return value.filter((x) => x !== null && x !== undefined).join(", ");
42
+ }
43
+ return JSON.stringify(value);
44
+ }
45
+
46
+ /** { a: 1, b: { c: 2 } } → { a: 1, "b.c": 2 } (two levels; deeper parts stay JSON). */
47
+ export function flatten(record, prefix = "", depth = 0) {
48
+ const out = {};
49
+ for (const [key, value] of Object.entries(record)) {
50
+ const name = prefix ? `${prefix}.${key}` : key;
51
+ if (isRecord(value) && depth < 2) Object.assign(out, flatten(value, name, depth + 1));
52
+ else out[name] = cell(value);
53
+ }
54
+ return out;
55
+ }
56
+
57
+ function csvCell(value) {
58
+ const s = String(value);
59
+ return /[",\r\n]/.test(s) ? `"${s.replace(/"/g, '""')}"` : s;
60
+ }
61
+
62
+ /** Records → CSV text; the headers are every field seen, in order of first appearance. */
63
+ export function toCsv(records) {
64
+ const flat = records.map((r) => flatten(r));
65
+ const headers = [];
66
+ for (const row of flat) for (const k of Object.keys(row)) if (!headers.includes(k)) headers.push(k);
67
+ if (!headers.length) return "(no results)\r\n";
68
+ const lines = [headers.map(csvCell).join(",")];
69
+ for (const row of flat) lines.push(headers.map((h) => csvCell(row[h] ?? "")).join(","));
70
+ return `${lines.join("\r\n")}\r\n`;
71
+ }
package/src/paging.js ADDED
@@ -0,0 +1,50 @@
1
+ // Cursor handling shared by every paginated call.
2
+ //
3
+ // The API returns its next-page cursor as `end_cursor` (usually inside a
4
+ // `page_info` block next to `has_next_page`). Where exactly it sits differs by
5
+ // endpoint, so we look for it instead of hard-coding a path, and stop as soon
6
+ // as there is no cursor, `has_next_page` is false, or a cursor repeats.
7
+
8
+ // Our own envelope around every answer: never data, never a cursor.
9
+ export const ENVELOPE_KEYS = ["meta", "message"];
10
+
11
+ const STOP = Symbol("stop");
12
+
13
+ function findCursor(node, depth) {
14
+ if (depth > 4 || !node || typeof node !== "object" || Array.isArray(node)) return null;
15
+ const info = node.page_info;
16
+ if (info && typeof info === "object") {
17
+ if (info.has_next_page === false) return STOP;
18
+ if (typeof info.end_cursor === "string" && info.end_cursor) return info.end_cursor;
19
+ }
20
+ if (typeof node.end_cursor === "string" && node.end_cursor) return node.end_cursor;
21
+ for (const [key, value] of Object.entries(node)) {
22
+ if (ENVELOPE_KEYS.includes(key)) continue;
23
+ const found = findCursor(value, depth + 1);
24
+ if (found !== null) return found;
25
+ }
26
+ return null;
27
+ }
28
+
29
+ /** The cursor for the next page, or null when there is no next page. */
30
+ export function nextCursor(body) {
31
+ const found = findCursor(body, 0);
32
+ return typeof found === "string" ? found : null;
33
+ }
34
+
35
+ /**
36
+ * Call `fetchPage(cursor)` up to `pages` times, yielding each answer.
37
+ * Every call is a billed API call, so `pages` is a hard ceiling.
38
+ */
39
+ export async function* paginate(fetchPage, pages) {
40
+ if (!Number.isInteger(pages) || pages < 1) throw new RangeError("pages must be a whole number, 1 or more");
41
+ let cursor = null;
42
+ const seen = new Set();
43
+ for (let i = 0; i < pages; i++) {
44
+ const body = await fetchPage(cursor);
45
+ yield body;
46
+ cursor = nextCursor(body);
47
+ if (cursor === null || seen.has(cursor)) return;
48
+ seen.add(cursor);
49
+ }
50
+ }