facebook-comments-client 0.1.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kenesuino
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,225 @@
+# facebook-comments-client
+
+Fetch comments from Facebook posts — including posts inside Facebook Groups where your account already has legitimate access — using an authorized Playwright session. Returns clean, normalized JSON that is independent of Facebook's internal response structure.
+
+This is a **focused library**. It contains no database, no Supabase, no queues, no cron jobs, and no backend server. Its sole responsibility:
+
+```
+Facebook Post URL → Authenticate/Reuse Authorized Session → Fetch Available Comments → Return Clean Structured JSON
+```
+
+## Installation
+
+```bash
+npm install facebook-comments-client
+# The library drives a real browser via Playwright:
+npx playwright install chromium
+```
+
+Requirements: Node.js 20+.
+
+## Quick start
+
+```ts
+import { FacebookCommentsClient } from "facebook-comments-client";
+
+const client = new FacebookCommentsClient({
+  session: {
+    type: "file",
+    path: "./facebook-session.json"
+  }
+});
+
+const result = await client.getComments({
+  url: "https://www.facebook.com/groups/GROUP_ID/posts/POST_ID/",
+  maxComments: 100,
+  includeReplies: true
+});
+
+console.log(result.comments);
+await client.close();
+```
+
+## Interactive login
+
+The library never enters credentials for you. It opens a visible browser, you log in manually, and the authorized session is exported:
+
+```ts
+import { FacebookCommentsClient } from "facebook-comments-client";
+
+await FacebookCommentsClient.login({
+  outputPath: "./facebook-session.json"
+});
+```
+
+Or from the CLI:
+
+```bash
+npx fb-comments login --output ./facebook-session.json
+```
+
+The helper waits for the Facebook `c_user` cookie to appear (up to 5 minutes by default), saves the Playwright storage state, and closes the browser.
+
+## Session file usage
+
+```ts
+const client = new FacebookCommentsClient({
+  session: { type: "file", path: "./facebook-session.json" }
+});
+```
+
+`type: "storage"` is accepted as an alias. The file is a standard Playwright storage state (as produced by `context.storageState()` and by the login helper above).
+
+## Environment variable usage
+
+Handy for deployments. Encode a storage state once:
+
+```ts
+const encoded = Buffer.from(JSON.stringify(storageState)).toString("base64");
+```
+
+Then configure the client:
+
+```ts
+const client = new FacebookCommentsClient({
+  session: { type: "env", envKey: "FACEBOOK_STORAGE_STATE" }
+});
+```
+
+The variable is base64(-url) decoded, JSON parsed, and validated with Zod before a browser context is created. You can also pass a plain cookie array via `{ type: "cookies", cookies }` or an inline object via `{ type: "state", state }`.
+
+## Fetching comments
+
+```ts
+const result = await client.getComments({
+  url: "https://www.facebook.com/groups/123/posts/456/",
+  maxComments: 100,      // default 50
+  includeReplies: true,  // default false
+  maxReplies: 20,        // default 20, per comment
+  timeout: 30000,        // navigation timeout ms
+  headless: true         // override client default
+});
+```
+
+Returns a normalized shape:
+
+```ts
+{
+  post: { id: "456", url: "https://www.facebook.com/groups/123/posts/456/" },
+  comments: [
+    {
+      id: "comment_123" | null,
+      author: { id: "user_123" | null, name: "John Doe" | null, profileUrl: "..." | null },
+      message: "Hello!",
+      createdAt: "2026-08-28T10:30:00.000Z" | null,
+      reactions: { total: 5 | null },
+      parentId: null,
+      replies: [ /* same shape */ ]
+    }
+  ],
+  pagination: { hasMore: false, nextCursor: null }
+}
+```
+
+Every field degrades to `null` instead of crashing when Facebook's markup differs — missing profile URLs, unparseable timestamps, unavailable reaction counts, etc.
+
+## Fetching replies
+
+Set `includeReplies: true` (and optionally `maxReplies`). The fetcher expands "View more replies" controls (bounded) and nests replies under their parent comment with `parentId` set.
+
+## Pagination
+
+```ts
+const page1 = await client.getComments({ url, maxComments: 25 });
+
+if (page1.pagination.hasMore) {
+  const page2 = await client.getComments({
+    url,
+    maxComments: 25,
+    cursor: page1.pagination.nextCursor
+  });
+}
+```
+
+The cursor is an opaque base64url token — an offset into the comment stream. No Facebook internals leak into your code.
+
+## Error handling
+
+```ts
+import {
+  FacebookClientError,
+  FacebookAuthenticationError,
+  FacebookSessionExpiredError,
+  FacebookPostNotFoundError,
+  FacebookAccessDeniedError,
+  FacebookExtractionError
+} from "facebook-comments-client";
+
+try {
+  const { comments } = await client.getComments({ url: postUrl });
+} catch (error) {
+  if (error instanceof FacebookSessionExpiredError) {
+    console.log("Facebook session needs to be refreshed.");
+  }
+}
+```
+
+Every error carries a stable `code` (`FB_AUTH`, `FB_SESSION_EXPIRED`, `FB_POST_NOT_FOUND`, `FB_ACCESS_DENIED`, `FB_EXTRACTION`, `FB_CLIENT`), a safe human-readable message, and a `retryable` boolean. Error messages never contain cookies or storage-state content. See [docs/errors.md](docs/errors.md).
+
+## Security notes
+
+- **Treat session files as passwords.** A storage state grants full access to the logged-in account.
+- The library never logs cookie values, tokens, or storage states; its logger redacts sensitive keys, and error messages are scrubbed.
+- `facebook-session.json`, `*.storage-state.json`, and `.env` are in `.gitignore` — never commit them.
+- Environment variables are convenient for deployment, but session expiration and secret handling are your responsibility. Prefer your platform's secret manager over plaintext `.env` files.
+- Use sessions belonging to accounts that legitimately have access to the requested content. This library does not bypass logins, CAPTCHAs, or access controls, and contains no stealth, fingerprint-spoofing, proxy-rotation, or restriction-evasion features.
+
+## Session refresh instructions
+
+Facebook sessions expire (typically days to weeks):
+
+1. `client.validateSession()` returns `{ valid: true, authenticated: false }`, or `getComments` throws `FacebookSessionExpiredError`.
+2. Re-run the login helper: `await FacebookCommentsClient.login({ outputPath })` (or `fb-comments login`).
+3. If you use the env-var provider, re-encode the fresh state and update the variable.
+
+## Known limitations
+
+- **Facebook markup is unstable by nature.** All selectors and text patterns live in [`src/config/selectors.ts`](src/config/selectors.ts); when extraction quality degrades, that one file is the place to look. Extraction issues throw `FacebookExtractionError` rather than returning garbage silently.
+- The structured-data extractor is opportunistic; on most modern pages the accessibility-based DOM extractor does the real work.
+- Timestamps shown as relative times ("2h") are approximations computed from fetch time.
+- Comment ids are frequently absent in the DOM and are returned as `null`.
+- Localization: text patterns currently target English UI text. Non-English Facebook UIs may need additional patterns in `selectors.ts`.
+- Very long threads (hundreds of comments) require pagination; the load-more loop is intentionally bounded.
+- Integration tests against live Facebook are opt-in (`tests/integration/live.test.ts`) and need `FB_TEST_URL` + `FACEBOOK_STORAGE_STATE`.
+
+## CLI
+
+```bash
+# Login (manual, headed browser)
+fb-comments login --output ./facebook-session.json
+
+# Fetch comments
+fb-comments comments "https://www.facebook.com/groups/123/posts/456/" --replies --limit 100
+
+# Machine-readable output
+fb-comments comments POST_URL --json
+
+# Session from env var
+FACEBOOK_STORAGE_STATE="..." fb-comments comments POST_URL
+```
+
+## Development
+
+```bash
+npm install
+npx playwright install chromium
+npm test        # unit + fixture tests (offline, no Facebook login needed)
+npm run build   # dist/ ESM + CJS + types + CLI
+npm run lint
+```
+
+See [docs/api.md](docs/api.md) for the full API surface, [docs/authentication.md](docs/authentication.md) and [docs/session-management.md](docs/session-management.md) for session details.
+
+## License
+
+MIT