agentic-facebook 0.4.0__py3-none-any.whl

agentic_facebook/__init__.py

@@ -0,0 +1,181 @@
+"""Public Python API (plan §5). See README.md for the full picture."""
+
+from __future__ import annotations
+
+__version__ = "0.4.0"
+
+from collections.abc import Iterator
+from datetime import date
+from pathlib import Path
+
+from . import profiles
+from . import retrieve as retrieve_module
+from . import session as session_module
+from .config import DEFAULT_MAX_SCROLLS, DEFAULT_PROFILE_NAME, DEFAULT_SCROLL_PAUSE
+from .errors import (
+    AgenticFacebookError,
+    ChallengeError,
+    InvalidIdentifierError,
+    LoginRequiredError,
+    ProfileUnavailableError,
+    SessionClosedError,
+    SessionExpiredError,
+)
+from .model import LinkAttachment, Media, Post
+from .retrieve import RetrieveResult
+from .session import Status
+
+__all__ = [
+    "FacebookScraper",
+    "Post",
+    "Media",
+    "LinkAttachment",
+    "Status",
+    "RetrieveResult",
+    "AgenticFacebookError",
+    "LoginRequiredError",
+    "SessionExpiredError",
+    "ChallengeError",
+    "ProfileUnavailableError",
+    "SessionClosedError",
+    "InvalidIdentifierError",
+]
+
+
+def _parse_date(value: str | date | None) -> date | None:
+    if value is None or isinstance(value, date):
+        return value
+    return date.fromisoformat(value)  # strict YYYY-MM-DD; raises ValueError otherwise
+
+
+class _HybridLogin:
+    """Makes ``login`` behave differently on the class vs. an instance:
+
+    - ``FacebookScraper.login(profile=..., profile_dir=...)`` (class access)
+      CONSTRUCTS a new instance with those keywords, then logs it in — so it
+      needs them.
+    - ``FacebookScraper(profile=...).login()`` (instance access) takes NO
+      keywords — ``profile``/``profile_dir`` are already fixed by the
+      instance you're calling it on; passing them again would be ambiguous
+      (log into the instance's own profile, or silently reconstruct a
+      different one?), so it's a plain ``TypeError`` instead of guessing.
+
+    Plain ``def``/``@classmethod`` can't express this one name having two
+    different call shapes — the second definition would just shadow the
+    first in the class namespace. This closes the gap the plan calls out
+    explicitly (§5): a classmethod-only shim can't forward a caller's custom
+    ``profile_dir`` into the same session it then logs into, so a library
+    user with a non-default ``profile_dir`` would log into one place and
+    fetch from another.
+    """
+
+    def __get__(self, obj, objtype=None):
+        if obj is not None:
+            return obj._login_instance
+
+        def classmethod_shim(
+            profile: str = DEFAULT_PROFILE_NAME,
+            *,
+            profile_dir: str | Path | None = None,
+        ) -> bool:
+            return objtype(profile=profile, profile_dir=profile_dir)._login_instance()
+
+        return classmethod_shim
+
+
+class FacebookScraper:
+    """Scrape your own logged-in Facebook timeline. See DISCLAIMER.md first."""
+
+    def __init__(
+        self,
+        profile: str = DEFAULT_PROFILE_NAME,
+        *,
+        headless: bool = True,
+        profile_dir: str | Path | None = None,
+        scroll_pause: tuple[float, float] = DEFAULT_SCROLL_PAUSE,
+        max_scrolls: int = DEFAULT_MAX_SCROLLS,
+    ) -> None:
+        self.profile = profile
+        self.headless = headless
+        self.scroll_pause = scroll_pause
+        self.max_scrolls = max_scrolls
+        self.last_result: RetrieveResult | None = None
+        self._profile_dir = profiles.resolve_profile_dir(profile, profile_dir)
+        self._closed = False
+
+    def __enter__(self) -> FacebookScraper:
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+        self._closed = True
+
+    def _login_instance(self) -> bool:
+        return session_module.run_login(self._profile_dir)
+
+    login = _HybridLogin()
+
+    def status(self) -> Status:
+        return session_module.run_status(self._profile_dir)
+
+    def fetch_profile(
+        self,
+        url: str,
+        *,
+        limit: int | None = None,
+        since: str | date | None = None,
+        until: str | date | None = None,
+        raw: bool = False,
+    ) -> list[Post]:
+        if self._closed:
+            raise SessionClosedError("FacebookScraper is closed; use it inside a `with` block")
+        normalized_url = profiles.normalize_target_identifier(url)
+        result = retrieve_module.fetch_profile(
+            normalized_url,
+            profile_dir=self._profile_dir,
+            # Must travel with profile_dir, not default separately: active mode
+            # keys its token cache by profile NAME while the browser session is
+            # keyed by DIRECTORY. Letting the name fall back to "default" while
+            # the directory points at another profile makes the two disagree —
+            # the run would read (and overwrite) a different account's cached
+            # cookies than the browser profile it is actually driving.
+            profile_name=self.profile,
+            headless=self.headless,
+            limit=limit,
+            since=_parse_date(since),
+            until=_parse_date(until),
+            scroll_pause=self.scroll_pause,
+            max_scrolls=self.max_scrolls,
+            raw=raw,
+        )
+        self.last_result = result
+        return result.posts
+
+    def iter_profile(
+        self,
+        url: str,
+        *,
+        limit: int | None = None,
+        since: str | date | None = None,
+        until: str | date | None = None,
+        raw: bool = False,
+    ) -> Iterator[Post]:
+        """Generator form. Must be consumed inside the owning ``with`` block —
+        advancing it (the first ``next()``, e.g. via a ``for`` loop) after the
+        block exited raises :class:`SessionClosedError` rather than touching
+        an already-closed session. Because this is a generator, that check
+        cannot run at call time — calling ``iter_profile()`` itself never
+        raises, even on an already-closed instance; only advancing it does.
+
+        Note this fully scrolls, captures, and parses before yielding the
+        first post — like ``fetch_profile``, just yielded one at a time
+        afterward. Breaking out of the loop early doesn't reduce browser
+        work already done.
+        """
+        if self._closed:
+            raise SessionClosedError("iter_profile() was advanced after its `with` block exited")
+        for post in self.fetch_profile(url, limit=limit, since=since, until=until, raw=raw):
+            if self._closed:
+                raise SessionClosedError(
+                    "iter_profile() was advanced after its `with` block exited"
+                )
+            yield post

agentic_facebook/catalog.py

@@ -0,0 +1,156 @@
+"""``agentic-facebook catalog`` — the CLI describing itself, so nothing has to re-type it.
+
+The problem this solves: anything that wants to *explain* this tool (the README,
+a `.claude` skill, an agent's prompt) previously had to transcribe the command
+list, the flags, their choices, and the exit codes. A transcription drifts the
+moment a flag is added, and a stale description is worse than none — a model
+trusts it over its own reading of `--help`.
+
+So the catalog is **derived, never authored**: the command and option tables are
+introspected from the live ``argparse`` parser, the object schemas come from the
+same ``to_dict()``-anchored functions ``schema`` uses, and the exit codes come
+from ``exits.DESCRIPTIONS``. Adding a command or a flag updates this output with
+no edit here, and ``tests/test_catalog.py`` fails if that ever stops being true.
+
+What is genuinely authored here is the short list below of behaviors that no
+amount of introspection can reach — the output contract and the known
+limitations. They live in code, next to the thing they describe, so there is
+still exactly one copy.
+"""
+
+from __future__ import annotations
+
+import argparse
+from typing import Any
+
+from . import exits
+from .comments import schema_fields as comment_schema_fields
+from .model import schema_fields as post_schema_fields
+from .search import schema_fields as entity_schema_fields
+
+#: Facts about how every retrieval command behaves that argparse cannot express.
+#: The first entry is the single most common mistake made against this CLI.
+OUTPUT_CONTRACT = [
+    "Results are written to a JSON FILE. Only a one-line summary goes to stderr, "
+    "and nothing useful goes to stdout — run the command, then read the file.",
+    "Pass --output PATH to choose that file. Without it, results land under the "
+    "platform data directory with a timestamped name (never the current directory, "
+    "because captured posts contain third-party personal data).",
+    "--format json emits one array; --format ndjson emits one object per line.",
+    "fetch/feed/post/search/group emit Post objects; comments emits Comment objects; "
+    "search --type people|pages|groups emits Entity objects instead of Posts.",
+]
+
+#: Known limitations that look like bugs. Authored (they are not derivable), but
+#: authored HERE so the skill and the README can point at them instead of copying.
+LIMITATIONS = [
+    "Active mode replays Facebook query ids (doc_id) that rotate when Facebook ships "
+    "a client build. `fetch` falls back to the browser automatically; feed/comments/"
+    "post/search/group are active-only and simply fail until the package is updated.",
+    "Passive mode cannot see a profile's newest post — the first timeline batch is "
+    "server-rendered into the HTML, never fetched as a GraphQL request. Active mode can.",
+    "post/comments require a real post permalink. Reel URLs are unsupported (a reel "
+    "page embeds no story id).",
+    "comments --replies fetches depth-1 replies only; a comment's reply_count includes "
+    "deeper nested replies that are not returned.",
+    "--limit on comments counts top-level comments only, so one heavily-replied comment "
+    "cannot consume the whole budget.",
+    "Requests are rate-floored in code and cannot be bypassed: >= 1.0s between active "
+    "requests, >= 0.5s between scrolls.",
+]
+
+
+def _subparser_action(parser: argparse.ArgumentParser) -> argparse._SubParsersAction | None:
+    for action in parser._actions:
+        if isinstance(action, argparse._SubParsersAction):
+            return action
+    return None
+
+
+def _describe_option(action: argparse.Action) -> dict[str, Any] | None:
+    """One flag, as the catalog reports it. ``None`` for things not worth listing."""
+    if isinstance(action, argparse._HelpAction | argparse._VersionAction):
+        return None
+    entry: dict[str, Any] = {
+        "flags": list(action.option_strings) or [action.dest],
+        "help": (action.help or "").replace("%(default)s", str(action.default)),
+        "required": bool(action.required),
+    }
+    if action.choices:
+        entry["choices"] = sorted(str(choice) for choice in action.choices)
+    if action.default is not None and not isinstance(action, argparse._StoreTrueAction):
+        entry["default"] = action.default
+    if not action.option_strings:
+        entry["positional"] = True
+    return entry
+
+
+def build_catalog(parser: argparse.ArgumentParser) -> dict[str, Any]:
+    """The whole self-description, derived from ``parser`` plus the schema functions."""
+    from . import __version__
+
+    subparsers = _subparser_action(parser)
+    commands: dict[str, Any] = {}
+    if subparsers is not None:
+        # choices maps name -> subparser; _choices_actions carries the help strings.
+        help_by_name = {choice.dest: (choice.help or "") for choice in subparsers._choices_actions}
+        for name, subparser in subparsers.choices.items():
+            options = [_describe_option(a) for a in subparser._actions]
+            commands[name] = {
+                "summary": help_by_name.get(name, ""),
+                "options": [option for option in options if option is not None],
+            }
+
+    return {
+        "tool": parser.prog,
+        "version": __version__,
+        "commands": commands,
+        "exit_codes": {str(code): text for code, text in sorted(exits.DESCRIPTIONS.items())},
+        "output_contract": OUTPUT_CONTRACT,
+        "limitations": LIMITATIONS,
+        "object_types": {
+            "Post": post_schema_fields(),
+            "Comment": comment_schema_fields(),
+            "Entity": entity_schema_fields(),
+        },
+    }
+
+
+def _format_option(option: dict[str, Any]) -> str:
+    flags = ", ".join(option["flags"])
+    if option.get("choices"):
+        flags += " {" + "|".join(option["choices"]) + "}"
+    return f"    {flags}\n        {option['help']}"
+
+
+def render_text(catalog: dict[str, Any]) -> str:
+    """The human/agent-readable rendering. Same content, no JSON parsing needed."""
+    lines = [f"{catalog['tool']} {catalog['version']} — command catalog", ""]
+
+    lines.append("OUTPUT CONTRACT (read this first)")
+    for item in catalog["output_contract"]:
+        lines.append(f"  - {item}")
+    lines.append("")
+
+    lines.append("COMMANDS")
+    for name, command in catalog["commands"].items():
+        lines.append(f"  {name} — {command['summary']}")
+        for option in command["options"]:
+            lines.append(_format_option(option))
+        lines.append("")
+
+    lines.append("EXIT CODES")
+    for code, text in catalog["exit_codes"].items():
+        lines.append(f"  {code}: {text}")
+    lines.append("")
+
+    lines.append("OBJECT TYPES (full field descriptions: agentic-facebook schema)")
+    for type_name, fields in catalog["object_types"].items():
+        names = ", ".join(field["name"] for field in fields)
+        lines.append(f"  {type_name}: {names}")
+    lines.append("")
+
+    lines.append("KNOWN LIMITATIONS")
+    for item in catalog["limitations"]:
+        lines.append(f"  - {item}")
+    return "\n".join(lines)

agentic_facebook/chrome.py

@@ -0,0 +1,179 @@
+"""Opt-in: reuse the Facebook session in your everyday Chrome (plan §3a, option a).
+
+**This is literal cookie extraction**, which is exactly what the default path
+avoids — hence opt-in, never automatic. It reads Chrome's encryption key from
+the macOS Keychain (which may prompt once) and decrypts the cookie values out
+of Chrome's own database.
+
+Why decryption is unavoidable: simply copying a logged-in Chrome profile and
+opening it with Playwright **fails**. Playwright launches Chrome with
+``--use-mock-keychain``, so Chrome cannot reach the real "Chrome Safe Storage"
+Keychain entry, every cookie fails to decrypt, and the copy opens logged out
+(recon §5.4).
+
+Importing an everyday browser usually means importing your *main* account —
+against this project's throwaway-account guidance. Prefer ``agentic-facebook login``.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import shutil
+import sqlite3
+import subprocess
+import tempfile
+from pathlib import Path
+
+from .errors import AgenticFacebookError
+
+#: Constants of Chrome's macOS cookie encryption (stable for many years).
+_SALT = b"saltysalt"
+_ITERATIONS = 1003
+_KEY_LENGTH = 16
+_IV = b" " * 16
+
+
+class ChromeImportError(AgenticFacebookError):
+    """Chrome's cookies could not be read or decrypted."""
+
+
+def _chrome_user_data_dir() -> Path:
+    return Path.home() / "Library" / "Application Support" / "Google" / "Chrome"
+
+
+def list_profiles_with_facebook_session() -> list[str]:
+    """Chrome profile names that hold a ``facebook.com`` ``c_user`` cookie.
+
+    Reads cookie *names and domains only* — never a value — so identifying the
+    right profile costs no decryption and triggers no Keychain prompt.
+    """
+    found: list[str] = []
+    root = _chrome_user_data_dir()
+    if not root.exists():
+        return found
+    for cookie_db in sorted(root.glob("*/Cookies")):
+        try:
+            with _temp_copy(cookie_db) as path:
+                connection = sqlite3.connect(f"file:{path}?mode=ro", uri=True)
+                try:
+                    row = connection.execute(
+                        "SELECT 1 FROM cookies WHERE host_key LIKE '%facebook.com' "
+                        "AND name = 'c_user' LIMIT 1"
+                    ).fetchone()
+                finally:
+                    connection.close()
+            if row:
+                found.append(cookie_db.parent.name)
+        except (OSError, sqlite3.Error):
+            continue
+    return found
+
+
+class _temp_copy:
+    """Chrome holds a lock on the live DB; work on a copy."""
+
+    def __init__(self, source: Path) -> None:
+        self._source = source
+        self._dir: str | None = None
+
+    def __enter__(self) -> Path:
+        self._dir = tempfile.mkdtemp(prefix="sfb-chrome-")
+        target = Path(self._dir) / "Cookies"
+        shutil.copy2(self._source, target)
+        os.chmod(target, 0o600)
+        return target
+
+    def __exit__(self, *exc) -> None:
+        if self._dir:
+            shutil.rmtree(self._dir, ignore_errors=True)
+
+
+def _safe_storage_password() -> str:
+    try:
+        result = subprocess.run(
+            ["security", "find-generic-password", "-w", "-s", "Chrome Safe Storage"],
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+    except (OSError, subprocess.CalledProcessError) as exc:
+        raise ChromeImportError(
+            "could not read the 'Chrome Safe Storage' key from the Keychain "
+            "(it may need to be allowed once, interactively)"
+        ) from exc
+    return result.stdout.strip()
+
+
+def _derive_key(password: str) -> bytes:
+    return hashlib.pbkdf2_hmac("sha1", password.encode(), _SALT, _ITERATIONS, _KEY_LENGTH)
+
+
+def _decrypt(value: bytes, key: bytes) -> str:
+    try:
+        from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
+    except ImportError as exc:  # pragma: no cover - depends on an optional extra
+        raise ChromeImportError(
+            "--from-chrome needs the optional 'chrome' extra: "
+            "pip install 'agentic-facebook[chrome]'"
+        ) from exc
+
+    if not value.startswith(b"v10"):
+        # An unencrypted value (rare, older Chrome) is already plaintext.
+        return value.decode("utf-8", errors="replace")
+
+    decryptor = Cipher(algorithms.AES(key), modes.CBC(_IV)).decryptor()
+    plaintext = decryptor.update(value[3:]) + decryptor.finalize()
+    if plaintext:
+        padding = plaintext[-1]
+        if 1 <= padding <= 16:
+            plaintext = plaintext[:-padding]
+    # Chrome >= 130 prefixes the plaintext with a 32-byte SHA256 of the domain.
+    # Detected structurally (non-UTF8 leading bytes) rather than by version
+    # sniffing, so both layouts work without knowing which Chrome wrote it.
+    try:
+        return plaintext.decode("utf-8")
+    except UnicodeDecodeError:
+        return plaintext[32:].decode("utf-8", errors="replace")
+
+
+def load_facebook_cookies(profile: str = "Default") -> dict[str, str]:
+    """Decrypted ``facebook.com`` cookies from a local Chrome profile.
+
+    Raises :class:`ChromeImportError` if the profile, the Keychain key, or the
+    session itself is missing — never returns a half-usable cookie jar.
+    """
+    cookie_db = _chrome_user_data_dir() / profile / "Cookies"
+    if not cookie_db.exists():
+        available = ", ".join(list_profiles_with_facebook_session()) or "none found"
+        raise ChromeImportError(
+            f"no Chrome cookie database for profile {profile!r} "
+            f"(profiles with a Facebook session: {available})"
+        )
+
+    key = _derive_key(_safe_storage_password())
+    cookies: dict[str, str] = {}
+    with _temp_copy(cookie_db) as path:
+        connection = sqlite3.connect(f"file:{path}?mode=ro", uri=True)
+        try:
+            rows = connection.execute(
+                "SELECT name, value, encrypted_value FROM cookies "
+                "WHERE host_key LIKE '%facebook.com'"
+            ).fetchall()
+        finally:
+            connection.close()
+
+    for name, value, encrypted in rows:
+        if value:
+            cookies[name] = value
+        elif encrypted:
+            decrypted = _decrypt(encrypted, key)
+            if decrypted:
+                cookies[name] = decrypted
+
+    if "c_user" not in cookies or "xs" not in cookies:
+        raise ChromeImportError(
+            f"Chrome profile {profile!r} has no logged-in Facebook session "
+            "(no c_user/xs cookie after decryption)"
+        )
+    return cookies