scraper-for-facebook 0.1.0__tar.gz

scraper_for_facebook-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,83 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  lint-and-test:
+    # macOS is the first-class, tested target (v1); the ubuntu leg exists
+    # because the fixture/parse/CLI layer is browser-agnostic, and running it
+    # on Linux too is a cheap way to make that cross-platform claim real
+    # (plan §14). Neither leg installs an actual browser binary.
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [macos-latest, ubuntu-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install pinned dev dependencies
+        run: python -m pip install -r requirements-dev.lock
+
+      - name: Install package (dependencies already pinned above)
+        run: python -m pip install -e . --no-deps
+
+      - name: Ruff lint
+        run: ruff check .
+
+      - name: Ruff format check
+        run: ruff format --check .
+
+      - name: Fixture PII/secret scan
+        run: python scripts/check_fixtures_pii.py
+
+      - name: Run tests
+        run: pytest
+
+  build-and-smoke:
+    # A wheel-install smoke test, WITH scrapling (a real dependency) but
+    # WITHOUT a browser binary — that's a separate, explicit `scrape-fb setup`
+    # step this job never runs. This catches a wrong entry-point path, a
+    # missing runtime dep, or an import that only fails once scrapling is
+    # actually present (plan §13) — none of which the fixture tests touch.
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [macos-latest, ubuntu-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tool
+        run: python -m pip install build
+
+      - name: Build wheel
+        run: python -m build --wheel
+
+      - name: Install built wheel into a clean venv
+        # POSIX venv layout (bin/, not Scripts\) and the bash default shell
+        # both assume macos-latest/ubuntu-latest only — adding windows-latest
+        # to the matrix above would need this step rewritten, not just the
+        # matrix line (Windows unsupported in v1; see README/pyproject).
+        run: |
+          python -m venv smoke-venv
+          smoke-venv/bin/pip install dist/*.whl
+
+      - name: Smoke test the entry point
+        run: |
+          smoke-venv/bin/scrape-fb --version
+          smoke-venv/bin/scrape-fb --help

scraper_for_facebook-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,49 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Verify tag matches pyproject.toml version
+        run: python3 scripts/check_tag_version.py "${{ github.ref_name }}"
+
+      - name: Install build tool
+        run: python -m pip install build
+
+      - name: Build sdist and wheel
+        run: python -m build
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      # Required to mint the OIDC token for PyPI Trusted Publishing — there is
+      # no stored API token anywhere in this repo (plan §15).
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      # Pinned to the commit for release v1.14.0 — a floating tag on an
+      # action that runs with publish credentials is a hijack vector
+      # (plan §15). Bump deliberately, not automatically.
+      - uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # v1.14.0

scraper_for_facebook-0.1.0/.gitignore

@@ -0,0 +1,36 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+
+# Dev environment
+.venv/
+.ruff_cache/
+.pytest_cache/
+
+# Raw captures and runtime outputs are a PII trap — ignore by an unambiguous,
+# distinct name/location so a safe fixture and an unsafe raw capture can never
+# collide under one glob (see plan §4).
+scratch/
+*.raw.ndjson
+profiles/
+*.json
+*.ndjson
+
+# Un-ignore the committed, synthetic-by-construction fixtures — enumerated
+# explicitly, NOT a wildcard. A wildcard un-ignore (`!tests/fixtures/*.ndjson`)
+# would re-include ANY new .ndjson dropped into this directory, not just
+# these known-synthetic ones — defeating the whole point of the blanket
+# ignore above. Adding a new fixture means adding its name here too.
+!tests/fixtures/basic_status_post.ndjson
+!tests/fixtures/comment_preview_and_universal_marker.ndjson
+!tests/fixtures/media_and_links.ndjson
+!tests/fixtures/pinned_decoy_and_missing_date.ndjson
+!tests/fixtures/shared_post.ndjson
+!tests/fixtures/split_defer_merge.ndjson
+!tests/fixtures/truncated_post.ndjson
+
+.DS_Store

scraper_for_facebook-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,16 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.8.6
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: local
+    hooks:
+      - id: fixture-pii-scan
+        name: scan committed fixtures for PII/secrets
+        entry: python3 scripts/check_fixtures_pii.py
+        language: system
+        files: ^tests/fixtures/.*\.ndjson$
+        pass_filenames: false

scraper_for_facebook-0.1.0/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-07-05
+
+### Added
+- Initial release: `scrape-fb login` / `status` / `setup` / `doctor` / `fetch`.
+- Logged-in Facebook timeline scraping via GraphQL XHR observation (no token replay).
+- `--limit`, `--since`/`--until` retrieval with stop-reason reporting.
+- JSON and NDJSON output formats.
+- Python API: `FacebookScraper`, `Post`, `Media`, `LinkAttachment`.
+
+[Unreleased]: https://github.com/tjdwls101010/Scraper-for-Facebook/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/tjdwls101010/Scraper-for-Facebook/releases/tag/v0.1.0

scraper_for_facebook-0.1.0/CLAUDE.md

@@ -0,0 +1,65 @@
+# CLAUDE.md
+
+Behavioral guidelines to reduce common LLM coding mistakes. Merge with project-specific instructions as needed.
+
+**Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment.
+
+## 1. Think Before Coding
+
+**Don't assume. Don't hide confusion. Surface tradeoffs.**
+
+Before implementing:
+- State your assumptions explicitly. If uncertain, ask.
+- If multiple interpretations exist, present them - don't pick silently.
+- If a simpler approach exists, say so. Push back when warranted.
+- If something is unclear, stop. Name what's confusing. Ask.
+
+## 2. Simplicity First
+
+**Minimum code that solves the problem. Nothing speculative.**
+
+- No features beyond what was asked.
+- No abstractions for single-use code.
+- No "flexibility" or "configurability" that wasn't requested.
+- No error handling for impossible scenarios.
+- If you write 200 lines and it could be 50, rewrite it.
+
+Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
+
+## 3. Surgical Changes
+
+**Touch only what you must. Clean up only your own mess.**
+
+When editing existing code:
+- Don't "improve" adjacent code, comments, or formatting.
+- Don't refactor things that aren't broken.
+- Match existing style, even if you'd do it differently.
+- If you notice unrelated dead code, mention it - don't delete it.
+
+When your changes create orphans:
+- Remove imports/variables/functions that YOUR changes made unused.
+- Don't remove pre-existing dead code unless asked.
+
+The test: Every changed line should trace directly to the user's request.
+
+## 4. Goal-Driven Execution
+
+**Define success criteria. Loop until verified.**
+
+Transform tasks into verifiable goals:
+- "Add validation" → "Write tests for invalid inputs, then make them pass"
+- "Fix the bug" → "Write a test that reproduces it, then make it pass"
+- "Refactor X" → "Ensure tests pass before and after"
+
+For multi-step tasks, state a brief plan:
+```
+1. [Step] → verify: [check]
+2. [Step] → verify: [check]
+3. [Step] → verify: [check]
+```
+
+Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.
+
+---
+
+**These guidelines are working if:** fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes.

scraper_for_facebook-0.1.0/DISCLAIMER.md

@@ -0,0 +1,38 @@
+# Disclaimer — read before you use this
+
+This is not legal advice. It is a plain-language summary of risks you take on by using this tool. If any of this matters to your situation, talk to a lawyer.
+
+## 1. This violates Facebook's Terms of Service
+
+Automating any Meta account to collect data — including logging in with a real browser and reading what it loads — is against Facebook's Terms of Service. Meta enforces this via account bans (temporary or permanent), checkpoints/"login approval" challenges, cease-and-desist letters, and in some cases litigation. Using this tool is entirely at your own risk. Use a **dedicated or throwaway account**, not your primary one, and keep volume low (§9 of the design doc; the CLI's scroll-pause floor and per-run scope exist because of this).
+
+## 2. Publishing this tool exposes its maintainer, not just its users
+
+This package is named `scraper-for-facebook`, published under a real GitHub identity, and distributed via PyPI Trusted Publishing, which binds each release to a named GitHub repository and account. That is a deliberate, informed choice by the maintainer — but it means the maintainer is identifiable in a way an anonymous or unpublished tool would not be. Meta has previously pursued named authors and operators of public Facebook/Instagram scrapers, historically skewed toward commercial mass-scraping and data-broker operations rather than small personal-scale tools — but the exposure exists regardless of scale, and this is recorded here so the choice stays informed.
+
+## 3. You may become a "data controller" for other people's data
+
+Posts you scrape belong to other people — authors, commenters, anyone tagged or mentioned. Collecting identifiable personal data about other people can make *you* a data controller under GDPR, CCPA, or similar law, with real obligations: a lawful basis for processing, honoring data-subject access/deletion requests, and limiting retention. "I did this for personal use" is not automatically a lawful basis. Minimize what you keep, and delete captured output once you're done with it. The MIT license on this code says nothing about, and does not excuse, privacy-law obligations around the *data* you collect with it.
+
+## 4. Output files are not scrubbed — treat them as sensitive
+
+Captured posts contain third-party names, message text, and signed media URLs. This tool:
+- never writes output to a location you'd casually commit to git (default `--output` is outside any repo; see README),
+- never redacts the *output* files themselves (only diagnostic/verbose logs go through redaction — see below),
+- relies on you to delete output you no longer need.
+
+Don't commit scraped output to a public (or even private) git repository, and don't share it beyond what you'd be comfortable being responsible for under §3.
+
+## 5. Diagnostics are redacted — but redaction is not a certification
+
+`-v`/`--verbose` output, error dumps, and anything printed to your terminal are passed through a single redaction path that strips signed media URLs, token-shaped fields, and truncates message text. This reduces accidental leakage into terminal scrollback, bug reports, or screenshots — it is **not** a guarantee that every sensitive value is caught, and it does not apply to the actual `--output` file, which is the full, unredacted capture by design (that's the point of the tool). `--raw --no-redact` disables this path entirely for debugging; only use it locally.
+
+## 6. Your login profile is a live, unencrypted session credential
+
+`scrape-fb login` persists your Facebook session (cookies, local storage) to a directory on disk, permissioned `0700`. Anyone who can read that directory has authenticated access to your Facebook account — no password or 2FA required, because the session already satisfied both. This is **less** protected than your regular browser's keychain-encrypted cookie store. Concretely:
+- **Do not** back this directory up to Time Machine, sync it via iCloud/Dropbox, or commit it anywhere.
+- If the machine or disk is lost or compromised, **revoke the session immediately** by logging out of that session from facebook.com (Settings → Security → Where You're Logged In), not just by deleting the local directory.
+
+## 7. No warranty
+
+This software is provided "as is" under the MIT License, without warranty of any kind. See [LICENSE](LICENSE). Facebook's internal API can and does change without notice; this tool may stop working, or silently return incomplete data, at any time (see the design doc's durability section).

scraper_for_facebook-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tjdwls101010
+
+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.

scraper_for_facebook-0.1.0/PKG-INFO

@@ -0,0 +1,164 @@
+Metadata-Version: 2.4
+Name: scraper-for-facebook
+Version: 0.1.0
+Summary: Scrape your own logged-in Facebook timeline by observing the GraphQL responses your own browser session makes. No token replay, no credential injection.
+Project-URL: Homepage, https://github.com/tjdwls101010/Scraper-for-Facebook
+Project-URL: Issues, https://github.com/tjdwls101010/Scraper-for-Facebook/issues
+Project-URL: Changelog, https://github.com/tjdwls101010/Scraper-for-Facebook/blob/main/CHANGELOG.md
+Author: tjdwls101010
+License-Expression: MIT
+License-File: LICENSE
+Keywords: facebook,graphql,scraper,scraping,scrapling
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP :: Indexing/Search
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: platformdirs>=4.0
+Requires-Dist: scrapling[fetchers]<0.5,>=0.4.9
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: pre-commit>=3.8; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# scraper-for-facebook
+
+Scrape posts from a **logged-in personal Facebook timeline** by observing the GraphQL responses your own browser session makes — no token replay, no credential injection. You log in once by hand; the browser generates its own `fb_dtsg`/`doc_id`/`lsd`, and this tool just reads what comes back.
+
+> **Read [DISCLAIMER.md](DISCLAIMER.md) before using this.** Automating a Facebook account violates its Terms of Service, publishing this tool exposes its maintainer, and scraping other people's posts can make *you* a data controller over their personal data. Use a dedicated/throwaway account, not your primary one.
+
+**This is not the first tool that does this.** [`facebook-graphql-scraper`](https://pypi.org/project/facebook-graphql-scraper/) captures GraphQL responses via Selenium + `selenium-wire` with credential-based login. This project's difference is incremental, not categorical: it reuses a **persisted browser-login profile** instead of injecting a username/password, and builds on [scrapling](https://github.com/D4Vinci/Scrapling)'s modern, actively-maintained fetch stack (Playwright-driven Chromium) instead of the largely-unmaintained `selenium-wire`.
+
+## Install
+
+This package depends on `scrapling[fetchers]`, which pins exact Playwright/patchright versions. Installing it into a shared environment alongside other Playwright-based tools can fail to resolve, or silently break one of them. **Always install this tool in an isolated environment:**
+
+```bash
+uv tool install scraper-for-facebook
+# or
+pipx install scraper-for-facebook
+```
+
+Do **not** `pip install scraper-for-facebook` into a general-purpose virtualenv you share with other projects.
+
+After installing, provision the browser (into its own isolated cache — this never touches a browser install any other tool manages):
+
+```bash
+scrape-fb setup
+```
+
+**Platform:** macOS is the tested, first-class target (v1). Linux likely works for the fetch/parse/CLI layer but is untested against a live Facebook session. Windows is unsupported.
+
+## Quick start
+
+```bash
+# 1. One-time interactive login — opens a real browser window, you log in by hand.
+scrape-fb login
+
+# 2. Verify the session (and that the browser + capture pipeline actually work).
+scrape-fb doctor
+
+# 3. Fetch the last 30 posts from a profile you're logged in and able to view.
+scrape-fb fetch https://www.facebook.com/some.profile --limit 30
+```
+
+Output defaults to a JSON file under this tool's own data directory (never your current directory or stdout — see `--output` below), because captured posts contain other people's personal data (§4 of the disclaimer) that shouldn't casually end up in a git-tracked path.
+
+## CLI reference
+
+```
+scrape-fb --version
+scrape-fb login   [--profile NAME] [--profile-dir PATH]
+scrape-fb status  [--profile NAME] [--profile-dir PATH] [--json]
+scrape-fb setup
+scrape-fb doctor  [--profile NAME] [--profile-dir PATH]
+scrape-fb fetch <profile_url_or_username>
+    --profile NAME            persisted login profile (default: "default")
+    --limit N                 max posts
+    --since YYYY-MM-DD        lower date bound (inclusive), best-effort (see "Limitations" below)
+    --until YYYY-MM-DD        upper date bound (inclusive)
+    --format json|ndjson      default: json
+    --output PATH             default: a non-repo path under this tool's data directory
+    --scroll-pause MIN,MAX    seconds between scrolls; MIN is clamped to >= 0.5 (see "Guardrails")
+    --max-scrolls N           scroll budget (default 40)
+    --profile-dir PATH        override where the login profile is stored
+    --headed                  show the browser (debugging)
+    --raw                     include the raw captured story node per post (debug; contains PII).
+                              Redacted (scrubbed) by default — combine with --no-redact for the
+                              truly raw, unscrubbed node (prints an on-screen PII warning).
+    --no-redact               disable redaction of --raw output (only has an effect with --raw)
+    -v / --verbose            extra diagnostics (redaction-scrubbed by default)
+```
+
+### Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | Success — limit met, requested date window fully reached, or feed genuinely exhausted |
+| 1 | Other/unexpected error |
+| 2 | Login required or session expired — run `scrape-fb login` |
+| 3 | Account checkpoint (Meta flagged the session) — log in again in a real browser |
+| 4 | Zero posts returned — possibly parser drift against a Facebook response-shape change |
+| 5 | Profile unavailable (memorialized, blocked, restricted, or nonexistent) |
+| 7 | Partial: `--since` was requested but not confirmed reached within `--max-scrolls` |
+
+A one-line summary on stderr always states the post count, observed date range, and *why* the run stopped — so a partial `--since` run is never mistaken for a complete one.
+
+## Guardrails
+
+- The scroll-pause floor (`--scroll-pause`) is clamped to **≥ 0.5s and cannot be set to 0** — this is the one non-bypassable limit in this tool, and it exists both to reduce your account's checkpoint/ban risk and to keep this from being usable as a mass-scraping tool.
+- One target profile per invocation; no batch/multi-profile mode; no built-in scheduler or daemon loop.
+- Deeper `--since` runs scroll more, and more scrolling raises checkpoint risk. If you value the account, prefer shallow/recent fetches and `--headed` runs over deep history.
+
+## Limitations (v1)
+
+- Facebook only — no Instagram, no Threads (see roadmap).
+- Personal-profile timeline posts only — no groups, pages, or photo albums.
+- `--since` is **best-effort**: because this tool observes pagination rather than driving it, Facebook can stall further pagination before your requested date is reached. Exit code `7` and the stderr summary tell you when that happened.
+- Media is captured as URLs only (no file download) — and those URLs are signed, expire, and are scoped to your viewing session; treat them as sensitive.
+- No guaranteed deep-history reach; no incremental `--since-last` state (yet).
+
+## Python API
+
+```python
+from scraper_for_facebook import FacebookScraper, Post, Media, LinkAttachment
+from scraper_for_facebook.errors import (
+    LoginRequiredError, SessionExpiredError, ChallengeError,
+    ProfileUnavailableError, SessionClosedError,
+)
+
+# One-time interactive login (opens a headed browser; you log in by hand).
+FacebookScraper(profile="default").login()
+
+with FacebookScraper(profile="default") as fb:                 # headless reuse
+    posts: list[Post] = fb.fetch_profile(
+        "https://www.facebook.com/some.profile", limit=30, since="2026-01-01",
+    )
+    for post in fb.iter_profile("https://www.facebook.com/some.profile", limit=30):
+        ...  # must be consumed inside the `with` block
+
+FacebookScraper(profile="default").status()   # -> Status.LOGGED_IN | EXPIRED | CHECKPOINT
+```
+
+## Contributing
+
+```bash
+uv venv && source .venv/bin/activate
+uv pip install -e ".[dev]"
+pre-commit install
+pytest
+```
+
+Unit tests run against synthetic, PII-free fixtures (`tests/fixtures/`) — never against real captures. Live integration tests (`tests/live/`) are opt-in (`SFB_LIVE_TESTS=1`) and never run in CI. See the design doc in this repo's history for the full architecture and the reasoning behind each guardrail.
+
+## License
+
+MIT — see [LICENSE](LICENSE). The license covers the code; it does not cover what you do with the data you collect (see [DISCLAIMER.md](DISCLAIMER.md)).

scraper_for_facebook-0.1.0/README.md

@@ -0,0 +1,133 @@
+# scraper-for-facebook
+
+Scrape posts from a **logged-in personal Facebook timeline** by observing the GraphQL responses your own browser session makes — no token replay, no credential injection. You log in once by hand; the browser generates its own `fb_dtsg`/`doc_id`/`lsd`, and this tool just reads what comes back.
+
+> **Read [DISCLAIMER.md](DISCLAIMER.md) before using this.** Automating a Facebook account violates its Terms of Service, publishing this tool exposes its maintainer, and scraping other people's posts can make *you* a data controller over their personal data. Use a dedicated/throwaway account, not your primary one.
+
+**This is not the first tool that does this.** [`facebook-graphql-scraper`](https://pypi.org/project/facebook-graphql-scraper/) captures GraphQL responses via Selenium + `selenium-wire` with credential-based login. This project's difference is incremental, not categorical: it reuses a **persisted browser-login profile** instead of injecting a username/password, and builds on [scrapling](https://github.com/D4Vinci/Scrapling)'s modern, actively-maintained fetch stack (Playwright-driven Chromium) instead of the largely-unmaintained `selenium-wire`.
+
+## Install
+
+This package depends on `scrapling[fetchers]`, which pins exact Playwright/patchright versions. Installing it into a shared environment alongside other Playwright-based tools can fail to resolve, or silently break one of them. **Always install this tool in an isolated environment:**
+
+```bash
+uv tool install scraper-for-facebook
+# or
+pipx install scraper-for-facebook
+```
+
+Do **not** `pip install scraper-for-facebook` into a general-purpose virtualenv you share with other projects.
+
+After installing, provision the browser (into its own isolated cache — this never touches a browser install any other tool manages):
+
+```bash
+scrape-fb setup
+```
+
+**Platform:** macOS is the tested, first-class target (v1). Linux likely works for the fetch/parse/CLI layer but is untested against a live Facebook session. Windows is unsupported.
+
+## Quick start
+
+```bash
+# 1. One-time interactive login — opens a real browser window, you log in by hand.
+scrape-fb login
+
+# 2. Verify the session (and that the browser + capture pipeline actually work).
+scrape-fb doctor
+
+# 3. Fetch the last 30 posts from a profile you're logged in and able to view.
+scrape-fb fetch https://www.facebook.com/some.profile --limit 30
+```
+
+Output defaults to a JSON file under this tool's own data directory (never your current directory or stdout — see `--output` below), because captured posts contain other people's personal data (§4 of the disclaimer) that shouldn't casually end up in a git-tracked path.
+
+## CLI reference
+
+```
+scrape-fb --version
+scrape-fb login   [--profile NAME] [--profile-dir PATH]
+scrape-fb status  [--profile NAME] [--profile-dir PATH] [--json]
+scrape-fb setup
+scrape-fb doctor  [--profile NAME] [--profile-dir PATH]
+scrape-fb fetch <profile_url_or_username>
+    --profile NAME            persisted login profile (default: "default")
+    --limit N                 max posts
+    --since YYYY-MM-DD        lower date bound (inclusive), best-effort (see "Limitations" below)
+    --until YYYY-MM-DD        upper date bound (inclusive)
+    --format json|ndjson      default: json
+    --output PATH             default: a non-repo path under this tool's data directory
+    --scroll-pause MIN,MAX    seconds between scrolls; MIN is clamped to >= 0.5 (see "Guardrails")
+    --max-scrolls N           scroll budget (default 40)
+    --profile-dir PATH        override where the login profile is stored
+    --headed                  show the browser (debugging)
+    --raw                     include the raw captured story node per post (debug; contains PII).
+                              Redacted (scrubbed) by default — combine with --no-redact for the
+                              truly raw, unscrubbed node (prints an on-screen PII warning).
+    --no-redact               disable redaction of --raw output (only has an effect with --raw)
+    -v / --verbose            extra diagnostics (redaction-scrubbed by default)
+```
+
+### Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | Success — limit met, requested date window fully reached, or feed genuinely exhausted |
+| 1 | Other/unexpected error |
+| 2 | Login required or session expired — run `scrape-fb login` |
+| 3 | Account checkpoint (Meta flagged the session) — log in again in a real browser |
+| 4 | Zero posts returned — possibly parser drift against a Facebook response-shape change |
+| 5 | Profile unavailable (memorialized, blocked, restricted, or nonexistent) |
+| 7 | Partial: `--since` was requested but not confirmed reached within `--max-scrolls` |
+
+A one-line summary on stderr always states the post count, observed date range, and *why* the run stopped — so a partial `--since` run is never mistaken for a complete one.
+
+## Guardrails
+
+- The scroll-pause floor (`--scroll-pause`) is clamped to **≥ 0.5s and cannot be set to 0** — this is the one non-bypassable limit in this tool, and it exists both to reduce your account's checkpoint/ban risk and to keep this from being usable as a mass-scraping tool.
+- One target profile per invocation; no batch/multi-profile mode; no built-in scheduler or daemon loop.
+- Deeper `--since` runs scroll more, and more scrolling raises checkpoint risk. If you value the account, prefer shallow/recent fetches and `--headed` runs over deep history.
+
+## Limitations (v1)
+
+- Facebook only — no Instagram, no Threads (see roadmap).
+- Personal-profile timeline posts only — no groups, pages, or photo albums.
+- `--since` is **best-effort**: because this tool observes pagination rather than driving it, Facebook can stall further pagination before your requested date is reached. Exit code `7` and the stderr summary tell you when that happened.
+- Media is captured as URLs only (no file download) — and those URLs are signed, expire, and are scoped to your viewing session; treat them as sensitive.
+- No guaranteed deep-history reach; no incremental `--since-last` state (yet).
+
+## Python API
+
+```python
+from scraper_for_facebook import FacebookScraper, Post, Media, LinkAttachment
+from scraper_for_facebook.errors import (
+    LoginRequiredError, SessionExpiredError, ChallengeError,
+    ProfileUnavailableError, SessionClosedError,
+)
+
+# One-time interactive login (opens a headed browser; you log in by hand).
+FacebookScraper(profile="default").login()
+
+with FacebookScraper(profile="default") as fb:                 # headless reuse
+    posts: list[Post] = fb.fetch_profile(
+        "https://www.facebook.com/some.profile", limit=30, since="2026-01-01",
+    )
+    for post in fb.iter_profile("https://www.facebook.com/some.profile", limit=30):
+        ...  # must be consumed inside the `with` block
+
+FacebookScraper(profile="default").status()   # -> Status.LOGGED_IN | EXPIRED | CHECKPOINT
+```
+
+## Contributing
+
+```bash
+uv venv && source .venv/bin/activate
+uv pip install -e ".[dev]"
+pre-commit install
+pytest
+```
+
+Unit tests run against synthetic, PII-free fixtures (`tests/fixtures/`) — never against real captures. Live integration tests (`tests/live/`) are opt-in (`SFB_LIVE_TESTS=1`) and never run in CI. See the design doc in this repo's history for the full architecture and the reasoning behind each guardrail.
+
+## License
+
+MIT — see [LICENSE](LICENSE). The license covers the code; it does not cover what you do with the data you collect (see [DISCLAIMER.md](DISCLAIMER.md)).