getsocialapi-facebook 0.1.0__py3-none-any.whl

getsocialapi_facebook/__init__.py

@@ -0,0 +1,23 @@
+from .client import Client
+from .exceptions import (
+    APIKeyError,
+    BadRequestError,
+    GetSocialFacebookError,
+    RateLimitError,
+    ServiceUnavailableError,
+    UpstreamError,
+)
+from .facebook import FacebookAPI
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Client",
+    "FacebookAPI",
+    "GetSocialFacebookError",
+    "BadRequestError",
+    "APIKeyError",
+    "RateLimitError",
+    "UpstreamError",
+    "ServiceUnavailableError",
+]

getsocialapi_facebook/client.py

@@ -0,0 +1,28 @@
+import os
+
+from .facebook import FacebookAPI
+from .http import DEFAULT_BASE_URL, Transport
+
+
+class Client:
+    """GetSocialAPI Facebook client.
+
+    Usage:
+        from getsocialapi_facebook import Client
+        client = Client(api_key="gsa_live_...")
+        group = client.resolve("https://www.facebook.com/groups/freegarden/")
+        client.fb.members(group["group_id"], first=15)
+    """
+
+    def __init__(self, api_key=None, base_url=DEFAULT_BASE_URL, timeout=30,
+                 max_retries=3, session=None):
+        api_key = api_key or os.environ.get("GETSOCIALAPI_FB_API_KEY")
+        if not api_key:
+            raise ValueError(
+                "api_key is required (pass api_key=... or set GETSOCIALAPI_FB_API_KEY)"
+            )
+        self._transport = Transport(
+            base_url=base_url, api_key=api_key, timeout=timeout,
+            max_retries=max_retries, session=session,
+        )
+        self.fb = self.facebook = FacebookAPI(self._transport)

getsocialapi_facebook/exceptions.py

@@ -0,0 +1,58 @@
+class GetSocialFacebookError(Exception):
+    """Base error for all GetSocialAPI Facebook SDK failures."""
+
+    def __init__(self, message, response=None, body=None):
+        super().__init__(message)
+        self.response = response
+        self.body = body if body is not None else {}
+
+
+def _reason(body, fallback):
+    """Extract a human-readable reason: {"error": "..."} | {"error": {"message"}} | {"message": ..."}."""
+    err = body.get("error")
+    if isinstance(err, dict):
+        err = err.get("message")
+    if isinstance(err, str) and err:
+        return err
+    msg = body.get("message")
+    if isinstance(msg, str) and msg:
+        return msg
+    return fallback
+
+
+class BadRequestError(GetSocialFacebookError):
+    """400 — bad parameters."""
+
+    def __init__(self, response=None, body=None):
+        body = body or {}
+        super().__init__(_reason(body, "Bad request"), response, body)
+
+
+class APIKeyError(GetSocialFacebookError):
+    """401 — invalid API key."""
+
+    def __init__(self, response=None, body=None):
+        super().__init__("Invalid API key", response, body)
+
+
+class RateLimitError(GetSocialFacebookError):
+    """429 — rate limit (body: {"error": "rate limit", "limit": N})."""
+
+    def __init__(self, response=None, body=None, limit=None):
+        super().__init__(f"Rate limit exceeded (limit: {limit})", response, body)
+        self.limit = limit
+
+
+class UpstreamError(GetSocialFacebookError):
+    """502 — temporary upstream error. Automatically retried."""
+
+    def __init__(self, response=None, body=None):
+        body = body or {}
+        super().__init__(_reason(body, "Temporary upstream error"), response, body)
+
+
+class ServiceUnavailableError(GetSocialFacebookError):
+    """503 — service overloaded."""
+
+    def __init__(self, response=None, body=None):
+        super().__init__("Service overloaded", response, body)

getsocialapi_facebook/facebook.py

@@ -0,0 +1,152 @@
+from urllib.parse import quote
+
+
+def _quote(value):
+    return quote(str(value), safe="")
+
+
+def _digits(value, name, max_len=20):
+    s = str(value)
+    if not s.isdigit() or not 1 <= len(s) <= max_len:
+        raise ValueError(f"{name} must be 1-{max_len} digits, got: {value!r}")
+    return s
+
+
+class FacebookAPI:
+    """Facebook endpoints of GetSocialAPI (groups, profiles, connections)."""
+
+    def __init__(self, transport):
+        self._t = transport
+
+    # ---------- Groups ----------
+
+    def resolve(self, url):
+        """Resolve a group link (numeric id, slug, m.facebook, share/g) to group_id."""
+        s = str(url).strip()
+        if not s:
+            raise ValueError("url must not be empty")
+        return self._t.request("GET", "/resolve", params={"url": s})
+
+    def resolve_profile(self, url):
+        """Resolve a profile link to a numeric user_id."""
+        s = str(url).strip()
+        if not s:
+            raise ValueError("url must not be empty")
+        return self._t.request("GET", "/resolve/profile", params={"url": s})
+
+    def overview(self, group_id):
+        """Group card: name, visibility, admins count. Upstream: FetchGroupMemberList."""
+        return self._t.request("GET", "/overview", params={"group_id": _digits(group_id, "group_id")})
+
+    def members(self, group_id, after=None):
+        """Group members, raw Facebook GraphQL (one page of 15).
+
+        Page 1 -> data.group, page 2+ -> data.fetch__Group. The page size is
+        fixed by the service (15 edges); pass page_info.end_cursor as `after`
+        while has_next_page is true to walk the list.
+        """
+        params = {"group_id": _digits(group_id, "group_id")}
+        if after is not None:
+            params["after"] = after
+        return self._t.request("GET", "/api/v1/members", params=params)
+
+    def group_posts(self, group_id, after=None):
+        """Group feed posts, raw GroupFeedCsrQuery payload (2-3 posts/page).
+
+        Story-shaped posts (creation_time, message.text, actors,
+        attachments) — same node schema as the user timeline; skip
+        GroupsSectionHeaderUnit edges. Take the cursor from
+        data.group_address.group_feed.page_info.end_cursor and pass it
+        back as `after` while has_next_page is true. Post visibility in
+        closed groups depends on the scraper token's membership.
+        """
+        params = {"group_id": _digits(group_id, "group_id")}
+        if after is not None:
+            params["after"] = after
+        return self._t.request("GET", "/api/v1/group_posts", params=params)
+
+    # ---------- Profile ----------
+
+    def contacts(self, user_id):
+        """Profile About (contacts) — the untouched Facebook GraphQL payload.
+
+        Walk data.user.profile_intro_card: each About section is a connection
+        with edges[].node; `field_type` describes the entry kind (email,
+        phone, gender, employer, ...), linked entities are full node objects.
+        """
+        return self._t.request("GET", "/api/v1/contacts",
+                               params={"user_id": _digits(user_id, "user_id")})
+
+    def posts(self, user_id, after=None):
+        """User timeline posts, raw Facebook GraphQL (one page of ~100).
+
+        data.profile.timeline_feed_units.edges[] holds Story nodes;
+        take the cursor from timeline_feed_units.page_info.end_cursor
+        and pass it back as `after` while has_next_page is true. The
+        cursor is a ~888-char base64 string — pass it verbatim (the
+        transport URL-encodes it). Cursors are reusable and not bound
+        to a session. Use only the page_info cursor — end_cursor values
+        inside node attachments are impostors and yield Invalid Cursor.
+        """
+        return self._t.request("GET", "/api/v1/posts", params=_conn(user_id, after))
+
+    def feed(self, user_id=None, group_id=None, per_page=None, after=None):
+        """GET /api/v1/feed — unified user/group feed, small pages.
+
+        Pass exactly one of `user_id` / `group_id`. Page size is
+        `per_page` (integer 3-20, default 10); a page may come back
+        short — follow has_next_page instead of counting posts.
+
+        user: `data.profile.timeline_feed_units` (~10 Story nodes;
+        Facebook may return slightly more — the service does not trim,
+        trimming would lose posts at page seams).
+        group: `data.group_address.group_feed` (Facebook caps its own
+        page at ~2 posts; the service stitches several FB pages up to
+        per_page — up to 2 duplicate edges are possible at the seam,
+        dedupe by node.cache_id).
+
+        Cursor: page_info.end_cursor of the respective connection,
+        passed back as `after` while has_next_page is true. A broken
+        cursor raises BadRequestError (400 Invalid Cursor).
+        """
+        if (user_id is None) == (group_id is None):
+            raise ValueError("pass exactly one of user_id or group_id")
+        params = {}
+        if user_id is not None:
+            params["user_id"] = _digits(user_id, "user_id")
+        else:
+            params["group_id"] = _digits(group_id, "group_id")
+        if per_page is not None:
+            if isinstance(per_page, bool) or not isinstance(per_page, int) \
+                    or not 3 <= per_page <= 20:
+                raise ValueError(f"per_page must be an integer 3-20, "
+                                 f"got: {per_page!r}")
+            params["per_page"] = per_page
+        if after is not None:
+            params["after"] = after
+        return self._t.request("GET", "/api/v1/feed", params=params)
+
+    # ---------- Connections ----------
+
+    def followers(self, user_id, after=None):
+        """User followers. Raw GraphQL: data.full_profile_list.list_items."""
+        return self._t.request("GET", "/api/v1/followers",
+                               params=_conn(user_id, after))
+
+    def followings(self, user_id, after=None):
+        """User followings."""
+        return self._t.request("GET", "/api/v1/followings",
+                               params=_conn(user_id, after))
+
+    def friends(self, user_id, after=None):
+        """User friends."""
+        return self._t.request("GET", "/api/v1/friends",
+                               params=_conn(user_id, after))
+
+
+def _conn(user_id, after):
+    params = {"user_id": _digits(user_id, "user_id")}
+    if after is not None:
+        params["after"] = after
+    return params
+

getsocialapi_facebook/http.py

@@ -0,0 +1,77 @@
+import time
+
+import requests
+
+from .exceptions import (
+    APIKeyError,
+    BadRequestError,
+    GetSocialFacebookError,
+    RateLimitError,
+    ServiceUnavailableError,
+    UpstreamError,
+)
+
+DEFAULT_BASE_URL = "https://api.getsocialapi.com/fb"
+
+RETRYABLE_STATUS = {429, 500, 502, 503, 504}
+
+
+class Transport:
+    """HTTP transport: X-API-Key auth, JSON parsing, retries."""
+
+    def __init__(self, base_url=DEFAULT_BASE_URL, api_key=None, timeout=30,
+                 max_retries=3, session=None):
+        self.base_url = base_url.rstrip("/")
+        self.api_key = api_key
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self.session = session or requests.Session()
+
+    def request(self, method, path, params=None):
+        url = f"{self.base_url}{path}"
+        headers = {"X-API-Key": self.api_key}
+        attempts = self.max_retries + 1
+        for attempt in range(attempts):
+            try:
+                resp = self.session.request(
+                    method, url, params=params, headers=headers, timeout=self.timeout,
+                )
+            except (requests.ConnectionError, requests.Timeout) as e:
+                if attempt < attempts - 1:
+                    time.sleep(min(2 ** attempt, 10))
+                    continue
+                raise GetSocialFacebookError(f"Network error: {e}") from e
+
+            if resp.status_code in RETRYABLE_STATUS and attempt < attempts - 1:
+                time.sleep(self._retry_after(resp))
+                continue
+            return self._parse(resp)
+        raise GetSocialFacebookError("Request failed after retries")  # pragma: no cover
+
+    @staticmethod
+    def _retry_after(resp):
+        try:
+            return min(max(int(float(resp.headers.get("Retry-After", 1))), 0), 30)
+        except (TypeError, ValueError):
+            return 1
+
+    @staticmethod
+    def _parse(resp):
+        try:
+            body = resp.json()
+        except ValueError:
+            body = {"raw": resp.text}
+
+        if resp.status_code == 400:
+            raise BadRequestError(resp, body)
+        if resp.status_code == 401:
+            raise APIKeyError(resp, body)
+        if resp.status_code == 429:
+            raise RateLimitError(resp, body, limit=(body or {}).get("limit"))
+        if resp.status_code == 502:
+            raise UpstreamError(resp, body)
+        if resp.status_code == 503:
+            raise ServiceUnavailableError(resp, body)
+        if resp.status_code >= 400:
+            raise GetSocialFacebookError(f"HTTP {resp.status_code}: {body}", resp, body)
+        return body

getsocialapi_facebook-0.1.0.dist-info/METADATA

@@ -0,0 +1,157 @@
+Metadata-Version: 2.4
+Name: getsocialapi-facebook
+Version: 0.1.0
+Summary: GetSocialAPI — Python client for the Facebook Scraper API (groups, profiles, connections)
+Author: GetSocialAPI
+License: MIT
+Project-URL: Homepage, https://getsocialapi.com
+Project-URL: Documentation, https://getsocialapi.com/docs/
+Keywords: facebook,api,scraping,sdk,groups,members
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.25
+Dynamic: license-file
+
+# Facebook Scraper API
+
+[![tests](https://github.com/GetSocialAPI/Facebook-Scraper-API/actions/workflows/tests.yml/badge.svg)](https://github.com/GetSocialAPI/Facebook-Scraper-API/actions/workflows/tests.yml)
+[![license](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+[![python](https://img.shields.io/badge/python-3.9%2B-blue)](https://www.python.org)
+
+Python client for the **[GetSocialAPI](https://getsocialapi.com/)** Facebook Scraper API.
+
+- Groups: resolve links, overview, paginated members
+- Profiles: resolve links, About/contacts in raw GraphQL
+- Connections: followers, followings, friends
+- Raw responses — no transformations
+- Automatic retries on 429/502/503, typed exceptions
+
+## Installation
+
+```bash
+pip install git+https://github.com/GetSocialAPI/Facebook-Scraper-API.git
+```
+
+## Quickstart
+
+```python
+from getsocialapi_facebook import Client
+
+# Get your API key at https://getsocialapi.com/dashboard/
+client = Client(api_key="gsa_live_...")  # or set GETSOCIALAPI_FB_API_KEY
+
+# Resolve any group link (slug, m.facebook, share/g) to a group_id
+group = client.fb.resolve("https://www.facebook.com/groups/freegarden/")
+group_id = group["group_id"]
+
+# Profile links resolve the same way
+user = client.fb.resolve_profile("https://www.facebook.com/nasa")
+user_id = user["user_id"]
+
+# Group card
+client.fb.overview(group_id)
+
+# Members: raw GraphQL pages (1st -> data.group, 2nd+ -> data.fetch__Group)
+page = client.fb.members(group_id)  # fixed page of 15 members
+page["data"]["group"]["group_member_profiles"]["page_info"]["end_cursor"]
+
+# Next page: pass page_info.end_cursor as `after`
+client.fb.members(group_id, after="AQHTm5Xq…")  # end_cursor from page_info
+```
+
+Base URL: `https://api.getsocialapi.com/fb` — authenticate with the API key
+from your [dashboard](https://getsocialapi.com/dashboard/).
+
+## Client
+
+```python
+Client(api_key=None, base_url="https://api.getsocialapi.com/fb", timeout=30, max_retries=3)
+```
+
+- `api_key` — your API key (env var `GETSOCIALAPI_FB_API_KEY` works too)
+
+## Methods
+
+| Method | Route | Description |
+| --- | --- | --- |
+| `resolve(url)` | `GET /resolve` | group link → `group_id` (numeric id, slug, m.facebook, `/share/g/…`) |
+| `resolve_profile(url)` | `GET /resolve/profile` | profile link → `user_id` |
+| `overview(group_id)` | `GET /overview` | group card: name, visibility |
+| `members(group_id, after=None)` | `GET /api/v1/members` | raw GraphQL page of 15 (1st — `data.group`, 2nd+ — `data.fetch__Group`) |
+| `group_posts(group_id, after=None)` | `GET /api/v1/group_posts` | group feed: page of 2–3 `Story` posts, cursor from `group_feed.page_info.end_cursor` |
+| `contacts(user_id)` | `GET /api/v1/contacts` | profile About: raw GraphQL |
+| `posts(user_id, after=None)` | `GET /api/v1/posts` | user timeline: page of ~100 posts (the fixed service maximum), cursor from `timeline_feed_units.page_info.end_cursor` |
+| `feed(user_id=None, group_id=None, per_page=None, after=None)` | `GET /api/v1/feed` | unified user/group feed, small pages: `per_page` 3–20 (default 10) |
+| `followers(user_id, after=None)` | `GET /api/v1/followers` | raw GraphQL `full_profile_list` |
+| `followings(user_id, after=None)` | `GET /api/v1/followings` | same shape |
+| `friends(user_id, after=None)` | `GET /api/v1/friends` | same shape |
+
+Full request/response reference with live examples:
+[getsocialapi.com/docs — API Reference / Facebook](https://getsocialapi.com/docs/api/facebook/resolve/).
+
+### Pagination
+
+Every method returns one raw page. Pass the connection's
+`page_info.end_cursor` as `after` while `has_next_page` is true.
+
+| List | Page size (fixed) | Cursor source |
+| --- | --- | --- |
+| `posts` | ~100 posts — the service maximum, there is no `count` parameter | `data.profile.timeline_feed_units.page_info.end_cursor` |
+| `feed` | `per_page` 3–20 (default 10); a page may come back short — follow `has_next_page` | same connection as the target: `timeline_feed_units` / `group_feed` `page_info.end_cursor` |
+| `group_posts` | 2–3 `Story` posts (skip `GroupsSectionHeaderUnit` edges, dedupe by `cache_id`) | `data.group_address.group_feed.page_info.end_cursor` |
+| `members` | 15 | `data.(group / fetch__Group).group_member_profiles.page_info.end_cursor` |
+| `followers` / `followings` / `friends` | 15 | `…list_items.page_info.end_cursor` |
+
+Cursors are reusable and not bound to a session; a broken or foreign cursor
+returns `400 Invalid Cursor` — take `end_cursor` only from the connection's
+`page_info`, never from node fields.
+
+```python
+posts, after = [], None
+while True:
+    page = client.fb.posts(user_id, after=after)
+    tfu = page["data"]["profile"]["timeline_feed_units"]
+    posts += [e["node"] for e in tfu["edges"]]
+    pi = tfu.get("page_info") or {}
+    if not pi.get("has_next_page") or not pi.get("end_cursor"):
+        break
+    after = pi["end_cursor"]
+```
+
+### Response notes
+
+- members page 1 lives in `data.group`, following pages in `data.fetch__Group`
+- connection lists: `can_see_follower_list: false` means the list is hidden by
+  privacy settings (only the count is available)
+
+## Errors
+
+| Exception | HTTP | Notes |
+| --- | --- | --- |
+| `GetSocialFacebookError` | — | base class; also network errors |
+| `BadRequestError` | 400 | bad parameters |
+| `APIKeyError` | 401 | invalid key |
+| `RateLimitError` | 429 | `.limit` from the response |
+| `UpstreamError` | 502 | temporary upstream error — retried automatically |
+| `ServiceUnavailableError` | 503 | service overloaded — retried automatically |
+
+Only successful responses count against your quota.
+Plans and rate limits: [getsocialapi.com/#pricing](https://getsocialapi.com/#pricing).
+
+## Support
+
+- Telegram: [@getsocialapi](https://t.me/getsocialapi)
+- Email: [hello@getsocialapi.com](mailto:hello@getsocialapi.com)
+- Website: [getsocialapi.com](https://getsocialapi.com/)
+- Documentation: [getsocialapi.com/docs](https://getsocialapi.com/docs/)
+- Status: [getsocialapi.com/status](https://getsocialapi.com/status/)
+
+## License
+
+MIT

getsocialapi_facebook-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+getsocialapi_facebook/__init__.py,sha256=65B_2cEW3f-0PuH8fubBhvvIoxEQXUNP4QvWiRsFH7A,440
+getsocialapi_facebook/client.py,sha256=Oa7aboxkTxhut0sQMpWe1lqMy4tKQdhO8o9h8wHmgi4,974
+getsocialapi_facebook/exceptions.py,sha256=kzEhma36WPvF5_9pXwqpYL35-kjMFr6y4xTIY3Hb01E,1876
+getsocialapi_facebook/facebook.py,sha256=vLvPk_A4IeJpd5lpb40fGdQmd1q--fpbxkKsPsFwTAA,6401
+getsocialapi_facebook/http.py,sha256=7pF7tqL4e0NIlGfTU52CMD1ZHOntF7nBOMrG7_EmOWU,2581
+getsocialapi_facebook-0.1.0.dist-info/licenses/LICENSE,sha256=jgv_wwS6fmja7z85ssgPuXIDkB6DTDr-v03_ClRjkyY,1069
+getsocialapi_facebook-0.1.0.dist-info/METADATA,sha256=vz9rta5vzMjl5nehsvrpnJOHtlQ86YQWwBNrJGWiKPw,6790
+getsocialapi_facebook-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+getsocialapi_facebook-0.1.0.dist-info/top_level.txt,sha256=AM6Py7S-OFke-Nk2WN4880ueQSV_kKs35gl6YH9fP-c,22
+getsocialapi_facebook-0.1.0.dist-info/RECORD,,

getsocialapi_facebook-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

getsocialapi_facebook-0.1.0.dist-info/licenses/LICENSE

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

getsocialapi_facebook-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+getsocialapi_facebook