rrss-sdk-wrapper 0.2.0__tar.gz → 0.2.1__tar.gz

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.
Files changed (93) hide show
  1. {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/.env.example +6 -1
  2. {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/CHANGELOG.md +11 -6
  3. {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/PKG-INFO +7 -9
  4. {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/README.md +5 -5
  5. {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/SECURITY.md +1 -1
  6. {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/docs/index.md +2 -3
  7. {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/docs/mapping.md +62 -30
  8. rrss_sdk_wrapper-0.2.1/docs/platforms/facebook.md +34 -0
  9. rrss_sdk_wrapper-0.2.1/docs/platforms/x.md +34 -0
  10. {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/mkdocs.yml +2 -2
  11. {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/pyproject.toml +4 -4
  12. {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/rrss/__init__.py +1 -1
  13. rrss_sdk_wrapper-0.2.1/rrss/adapters/facebook.py +154 -0
  14. rrss_sdk_wrapper-0.2.1/rrss/adapters/read_http.py +105 -0
  15. rrss_sdk_wrapper-0.2.1/rrss/adapters/x.py +154 -0
  16. {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/rrss/cli.py +1 -1
  17. {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/rrss/client.py +2 -5
  18. {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/rrss/gateway.py +1 -5
  19. rrss_sdk_wrapper-0.2.1/rrss/normalize/common.py +97 -0
  20. rrss_sdk_wrapper-0.2.1/rrss/normalize/facebook.py +102 -0
  21. rrss_sdk_wrapper-0.2.1/rrss/normalize/x.py +103 -0
  22. rrss_sdk_wrapper-0.2.1/tests/fixtures/facebook/comments.json +12 -0
  23. rrss_sdk_wrapper-0.2.1/tests/fixtures/facebook/post.json +12 -0
  24. rrss_sdk_wrapper-0.2.1/tests/fixtures/facebook/posts.json +18 -0
  25. rrss_sdk_wrapper-0.2.1/tests/fixtures/facebook/user.json +10 -0
  26. rrss_sdk_wrapper-0.2.1/tests/fixtures/x/comments.json +13 -0
  27. rrss_sdk_wrapper-0.2.1/tests/fixtures/x/post.json +12 -0
  28. rrss_sdk_wrapper-0.2.1/tests/fixtures/x/posts.json +20 -0
  29. rrss_sdk_wrapper-0.2.1/tests/fixtures/x/user.json +10 -0
  30. {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/tests/test_client.py +4 -2
  31. rrss_sdk_wrapper-0.2.1/tests/test_facebook.py +222 -0
  32. {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/tests/test_gateway.py +2 -0
  33. rrss_sdk_wrapper-0.2.1/tests/test_x.py +322 -0
  34. rrss_sdk_wrapper-0.2.0/docs/platforms/facebook-v1-deferral.md +0 -17
  35. rrss_sdk_wrapper-0.2.0/docs/platforms/x.md +0 -38
  36. rrss_sdk_wrapper-0.2.0/rrss/adapters/x.py +0 -224
  37. rrss_sdk_wrapper-0.2.0/rrss/normalize/x.py +0 -192
  38. rrss_sdk_wrapper-0.2.0/tests/fixtures/x/replies.json +0 -21
  39. rrss_sdk_wrapper-0.2.0/tests/fixtures/x/tweets.json +0 -20
  40. rrss_sdk_wrapper-0.2.0/tests/fixtures/x/user.json +0 -17
  41. rrss_sdk_wrapper-0.2.0/tests/test_x.py +0 -351
  42. {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/.gitignore +0 -0
  43. {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/compose.yaml +0 -0
  44. {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/docs/generated-clients.md +0 -0
  45. {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/docs/platforms/instagram.md +0 -0
  46. {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/docs/platforms/threads.md +0 -0
  47. {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/docs/platforms/tiktok.md +0 -0
  48. {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/generated/go/client.go +0 -0
  49. {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/generated/go/go.mod +0 -0
  50. {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/generated/go/models.go +0 -0
  51. {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/generated/python/rrss_client.py +0 -0
  52. {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/generated/rust/Cargo.toml +0 -0
  53. {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/generated/rust/src/lib.rs +0 -0
  54. {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/rrss/adapters/base.py +0 -0
  55. {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/rrss/adapters/instagram.py +0 -0
  56. {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/rrss/adapters/threads.py +0 -0
  57. {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/rrss/adapters/tiktok.py +0 -0
  58. {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/rrss/adapters/x_stub.py +0 -0
  59. {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/rrss/auth/__init__.py +0 -0
  60. {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/rrss/cache.py +0 -0
  61. {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/rrss/errors.py +0 -0
  62. {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/rrss/models.py +0 -0
  63. {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/rrss/normalize/__init__.py +0 -0
  64. {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/rrss/normalize/instagram.py +0 -0
  65. {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/rrss/normalize/threads.py +0 -0
  66. {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/rrss/normalize/tiktok.py +0 -0
  67. {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/rrss/ratelimit.py +0 -0
  68. {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/rrss/serialize.py +0 -0
  69. {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/rrss/stream.py +0 -0
  70. {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/schemas/openapi.yaml +0 -0
  71. {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/schemas/rrss-v1.json +0 -0
  72. {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/scripts/generate_client_stub.py +0 -0
  73. {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/sidecar/threads/.dockerignore +0 -0
  74. {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/sidecar/threads/Dockerfile +0 -0
  75. {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/sidecar/threads/README.md +0 -0
  76. {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/sidecar/threads/package-lock.json +0 -0
  77. {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/sidecar/threads/package.json +0 -0
  78. {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/sidecar/threads/server.js +0 -0
  79. {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/tests/fakes.py +0 -0
  80. {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/tests/fixtures/instagram/media.json +0 -0
  81. {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/tests/fixtures/instagram/user.json +0 -0
  82. {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/tests/fixtures/threads/threads.json +0 -0
  83. {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/tests/fixtures/threads/user.json +0 -0
  84. {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/tests/fixtures/tiktok/user.json +0 -0
  85. {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/tests/fixtures/tiktok/video.json +0 -0
  86. {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/tests/test_adapter_edges.py +0 -0
  87. {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/tests/test_cache.py +0 -0
  88. {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/tests/test_cli.py +0 -0
  89. {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/tests/test_errors_retry_integration.py +0 -0
  90. {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/tests/test_generated_client.py +0 -0
  91. {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/tests/test_normalize.py +0 -0
  92. {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/tests/test_normalize_edges.py +0 -0
  93. {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/tests/test_stream.py +0 -0
@@ -10,9 +10,14 @@ TIKTOK_PROXY=
10
10
  # Threads sidecar (Option A)
11
11
  RRSS_THREADS_SIDECAR_URL=http://127.0.0.1:1877
12
12
 
13
- # X API v2 app-only bearer. Empty keeps the read adapter inert (no requests).
13
+ # X unofficial reads. Empty keeps the adapter inert (no socket).
14
+ # The value is never sent or logged. Inject an HTTP client for reads.
14
15
  X_BEARER_TOKEN=
15
16
 
17
+ # Facebook unofficial reads. Empty keeps the adapter inert (no socket).
18
+ # The value is never sent or logged. Inject an HTTP client for reads.
19
+ FB_ACCESS_TOKEN=
20
+
16
21
  # Optional gateway (stdlib HTTP). Leave the key empty to disable the check.
17
22
  RRSS_GATEWAY_API_KEY=
18
23
  RRSS_GATEWAY_HOST=127.0.0.1
@@ -4,19 +4,24 @@ All notable changes to the `rrss` PyPI package are documented here.
4
4
 
5
5
  ## Unreleased
6
6
 
7
- Not published. No release tag.
7
+ ## 0.2.1 — 2026-11-20
8
8
 
9
9
  ### Added
10
10
 
11
- - Platform guides for Instagram, Threads, TikTok, and X (`docs/platforms/`).
12
- - X read-only adapter (X API v2, tweepy-shaped). Inert without `X_BEARER_TOKEN`. Optional extra `rrss[x]`.
11
+ - Platform guides for Instagram, Threads, TikTok, X, and Facebook (`docs/platforms/`).
12
+ - X read-only unofficial adapter. Inert without `X_BEARER_TOKEN` (no socket). Reads go through an injected HTTP client. The token is not sent or logged.
13
+ - Facebook read-only unofficial adapter (`get_user`, `list_user_posts`, `get_post`, `list_post_comments`). Inert without `FB_ACCESS_TOKEN`. The token is not sent or logged. See `docs/platforms/facebook.md`.
13
14
  - Threads sidecar image and `compose.yaml`. Health check is `http://127.0.0.1:1877/health`.
14
15
  - GitHub bug template (platform, redacted credentials, `include_raw`) and Dependabot.
15
16
  - Optional MkDocs config. `pip install -e ".[docs]"` then `mkdocs build`.
16
17
 
18
+ ### Changed
19
+
20
+ - `rrss-sdk-wrapper[x]` no longer depends on tweepy. The X adapter does not call X.
21
+
17
22
  ## 0.2.0 — 2026-11-20
18
23
 
19
- Not published to PyPI. No release tag.
24
+ Published to PyPI as `rrss-sdk-wrapper` 0.2.0 (tag `v0.2.0`).
20
25
 
21
26
  ### Added
22
27
 
@@ -35,10 +40,10 @@ Not published to PyPI. No release tag.
35
40
  - Unified error taxonomy (`AUTH_FAILED`, `RATE_LIMITED`, `NOT_FOUND`, `NOT_SUPPORTED`, `PLATFORM_ERROR`).
36
41
  - Exponential backoff retries on `RATE_LIMITED` (`rrss.ratelimit.with_retries`), wired for Instagram user fetch.
37
42
  - Threads Node sidecar contract under `python/sidecar/threads/` (local HTTP on `127.0.0.1:1877`).
38
- - X read-only stub (`NOT_SUPPORTED` until X API v2 credentials are configured).
43
+ - X read-only stub (`NOT_SUPPORTED` until configured).
39
44
  - JSON Schema `schemas/rrss-v1.json` for canonical types.
40
45
 
41
46
  ### Notes
42
47
 
43
- - Facebook Graph adapter deferred; see `docs/platforms/facebook-v1-deferral.md`.
48
+ - Facebook was not included in 0.1.0.
44
49
  - Live platform credentials are optional; inject mock upstream clients for tests.
@@ -1,13 +1,12 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: rrss-sdk-wrapper
3
- Version: 0.2.0
4
- Summary: Unified social media data client (Instagram, Threads, TikTok)
3
+ Version: 0.2.1
4
+ Summary: Unified social media data client (Instagram, Threads, TikTok, X, Facebook)
5
5
  Author: Ferran Suils
6
6
  License-Expression: MIT
7
7
  Requires-Python: >=3.11
8
8
  Provides-Extra: all
9
9
  Requires-Dist: httpx>=0.27; extra == 'all'
10
- Requires-Dist: tweepy>=4.14; extra == 'all'
11
10
  Provides-Extra: cache
12
11
  Requires-Dist: redis>=5; extra == 'cache'
13
12
  Provides-Extra: dev
@@ -22,22 +21,21 @@ Provides-Extra: threads
22
21
  Requires-Dist: httpx>=0.27; extra == 'threads'
23
22
  Provides-Extra: tiktok
24
23
  Provides-Extra: x
25
- Requires-Dist: tweepy>=4.14; extra == 'x'
26
24
  Description-Content-Type: text/markdown
27
25
 
28
26
  # rrss
29
27
 
30
- Python meta-package for normalized social profile and post data across Instagram, Threads, and TikTok.
28
+ Python meta-package for normalized social profile and post data across Instagram, Threads, TikTok, X, and Facebook.
31
29
 
32
30
  ## Install
33
31
 
34
- Version 0.2.0 in this tree is not published. PyPI still serves 0.1.0 until a tagged release.
32
+ Current PyPI release: 0.2.1.
35
33
 
36
34
  ```bash
37
35
  pip install rrss-sdk-wrapper
38
36
  # optional extras
39
37
  pip install "rrss-sdk-wrapper[threads]"
40
- pip install "rrss-sdk-wrapper[x]" # tweepy; live X calls only
38
+ pip install "rrss-sdk-wrapper[x]" # no third-party client; inject one
41
39
  pip install "rrss-sdk-wrapper[cache]" # redis; tests use the in-memory cache
42
40
  pip install "rrss-sdk-wrapper[docs]" # mkdocs
43
41
  pip install "rrss-sdk-wrapper[all]"
@@ -167,7 +165,7 @@ See `docs/index.md`.
167
165
  | Instagram | Username/password session | Read only | Unofficial (`instagrapi`) | [docs/platforms/instagram.md](docs/platforms/instagram.md) |
168
166
  | Threads | None (sidecar) | Read only | Unofficial | [docs/platforms/threads.md](docs/platforms/threads.md) |
169
167
  | TikTok | `ms_token` | Read only | Unofficial | [docs/platforms/tiktok.md](docs/platforms/tiktok.md) |
170
- | X | `X_BEARER_TOKEN` (inert if unset) | Read only | Official v2 | [docs/platforms/x.md](docs/platforms/x.md) |
171
- | Facebook | — | Deferred | — | [docs/platforms/facebook-v1-deferral.md](docs/platforms/facebook-v1-deferral.md) |
168
+ | X | `X_BEARER_TOKEN` (inert if unset) | Read only | Unofficial | [docs/platforms/x.md](docs/platforms/x.md) |
169
+ | Facebook | `FB_ACCESS_TOKEN` (inert if unset) | Read only | Unofficial | [docs/platforms/facebook.md](docs/platforms/facebook.md) |
172
170
 
173
171
  Project specification: see the workspace `docs/api-wrapper-plan.md` for the full contract.
@@ -1,16 +1,16 @@
1
1
  # rrss
2
2
 
3
- Python meta-package for normalized social profile and post data across Instagram, Threads, and TikTok.
3
+ Python meta-package for normalized social profile and post data across Instagram, Threads, TikTok, X, and Facebook.
4
4
 
5
5
  ## Install
6
6
 
7
- Version 0.2.0 in this tree is not published. PyPI still serves 0.1.0 until a tagged release.
7
+ Current PyPI release: 0.2.1.
8
8
 
9
9
  ```bash
10
10
  pip install rrss-sdk-wrapper
11
11
  # optional extras
12
12
  pip install "rrss-sdk-wrapper[threads]"
13
- pip install "rrss-sdk-wrapper[x]" # tweepy; live X calls only
13
+ pip install "rrss-sdk-wrapper[x]" # no third-party client; inject one
14
14
  pip install "rrss-sdk-wrapper[cache]" # redis; tests use the in-memory cache
15
15
  pip install "rrss-sdk-wrapper[docs]" # mkdocs
16
16
  pip install "rrss-sdk-wrapper[all]"
@@ -140,7 +140,7 @@ See `docs/index.md`.
140
140
  | Instagram | Username/password session | Read only | Unofficial (`instagrapi`) | [docs/platforms/instagram.md](docs/platforms/instagram.md) |
141
141
  | Threads | None (sidecar) | Read only | Unofficial | [docs/platforms/threads.md](docs/platforms/threads.md) |
142
142
  | TikTok | `ms_token` | Read only | Unofficial | [docs/platforms/tiktok.md](docs/platforms/tiktok.md) |
143
- | X | `X_BEARER_TOKEN` (inert if unset) | Read only | Official v2 | [docs/platforms/x.md](docs/platforms/x.md) |
144
- | Facebook | — | Deferred | — | [docs/platforms/facebook-v1-deferral.md](docs/platforms/facebook-v1-deferral.md) |
143
+ | X | `X_BEARER_TOKEN` (inert if unset) | Read only | Unofficial | [docs/platforms/x.md](docs/platforms/x.md) |
144
+ | Facebook | `FB_ACCESS_TOKEN` (inert if unset) | Read only | Unofficial | [docs/platforms/facebook.md](docs/platforms/facebook.md) |
145
145
 
146
146
  Project specification: see the workspace `docs/api-wrapper-plan.md` for the full contract.
@@ -1,7 +1,7 @@
1
1
  # Security
2
2
 
3
3
  - Never commit credentials or session files. Use `.env` locally (see `.env.example`).
4
- - Logs must not include passwords, tokens, or full session payloads.
4
+ - Logs must not include passwords, tokens, or full session payloads. `X_BEARER_TOKEN` and `FB_ACCESS_TOKEN` only enable the unofficial read adapters. Those adapters do not write them to logs, error messages, or request URLs.
5
5
  - The HTTP gateway does not log request lines. Platform passwords stay in the server environment; callers send `X-RRSS-Key` only. Do not put secrets in webhook bodies you store.
6
6
  - `RRSS_REDIS_URL` may embed a password. Do not print it.
7
7
  - Report security issues privately to the repository owner.
@@ -1,12 +1,11 @@
1
1
  # rrss
2
2
 
3
- Unified read client for Instagram, Threads, TikTok, and X. Facebook stays deferred.
3
+ Unified read client for Instagram, Threads, TikTok, X, and Facebook.
4
4
 
5
5
  Install and the Python quick start live in the package [README](https://github.com/FerranSuils/scraper-rrss/blob/master/python/README.md). This site is the longer reference:
6
6
 
7
7
  - [Field mapping](mapping.md)
8
- - [Instagram](platforms/instagram.md), [Threads](platforms/threads.md), [TikTok](platforms/tiktok.md), [X](platforms/x.md)
9
- - [Facebook deferral](platforms/facebook-v1-deferral.md)
8
+ - [Instagram](platforms/instagram.md), [Threads](platforms/threads.md), [TikTok](platforms/tiktok.md), [X](platforms/x.md), [Facebook](platforms/facebook.md)
10
9
  - [Generated clients](generated-clients.md)
11
10
 
12
11
  ## Build this site
@@ -118,64 +118,96 @@ Map `comment.id`, `text`, `create_time`, `user.uid`.
118
118
 
119
119
  ---
120
120
 
121
- ## X (API v2, read-only)
121
+ ## X (unofficial read JSON)
122
122
 
123
- Responses are tweepy-shaped: `data`, `includes`, `meta`. The adapter stays inert without `X_BEARER_TOKEN`.
123
+ The injected client returns these objects. The adapter stays inert without `X_BEARER_TOKEN` and does not call X. `GET /users/{username}`, `GET /users/id/{id}`, `GET /users/{id}/posts`, `GET /posts/{id}`, `GET /posts/{id}/comments`.
124
124
 
125
125
  ### User
126
126
 
127
127
  | Canonical | Source |
128
128
  |-----------|--------|
129
- | `id` | `data.id` (string) |
130
- | `username` | `data.username` |
131
- | `display_name` | `data.name` |
132
- | `bio` | `data.description` |
129
+ | `id` | `id` (string) |
130
+ | `username` | `username` |
131
+ | `display_name` | `name` |
132
+ | `bio` | `description` |
133
133
  | `profile_url` | `https://x.com/{username}` |
134
- | `avatar_url` | `data.profile_image_url` |
135
- | `follower_count` | `data.public_metrics.followers_count` |
136
- | `following_count` | `data.public_metrics.following_count` |
137
- | `is_verified` | `data.verified` |
134
+ | `avatar_url` | `profile_image_url` |
135
+ | `follower_count` | `followers_count` |
136
+ | `following_count` | `following_count` |
137
+ | `is_verified` | `verified` |
138
138
  | `platform` | `"x"` |
139
139
 
140
140
  ### Post
141
141
 
142
142
  | Canonical | Source |
143
143
  |-----------|--------|
144
- | `id` | `data.id` |
145
- | `author_id` | `data.author_id` |
146
- | `text` | `data.text` |
147
- | `created_at` | `data.created_at` (ISO-8601) |
148
- | `url` | `https://x.com/{username}/status/{id}` when `includes.users` has the author, else `https://x.com/i/web/status/{id}` |
149
- | `media` | `includes.media` joined on `attachments.media_keys`; `video` and `animated_gif` map to `video`, other types to `image` |
150
- | `like_count` | `data.public_metrics.like_count` |
151
- | `comment_count` | `data.public_metrics.reply_count` |
144
+ | `id` | `id` |
145
+ | `author_id` | `author_id` |
146
+ | `text` | `text`, or `message` when `text` is absent |
147
+ | `created_at` | `created_at` (ISO-8601) |
148
+ | `url` | `https://x.com/{author_username}/status/{id}`, else `https://x.com/i/web/status/{id}` |
149
+ | `media` | `media[]` with `url`. `video` and `animated_gif` map to `video`; other types map to `image`. Blank URLs are dropped. |
150
+ | `like_count` | `like_count` |
151
+ | `comment_count` | `reply_count` |
152
152
  | `platform` | `"x"` |
153
153
 
154
154
  ### Comment
155
155
 
156
- Replies come from recent search `conversation_id:{post_id} is:reply`. The root tweet id is skipped.
157
-
158
156
  | Canonical | Source |
159
157
  |-----------|--------|
160
- | `id` | tweet `id` |
161
- | `post_id` | `conversation_id` or the requested post id |
158
+ | `id` | `id` (empty ids are skipped) |
159
+ | `post_id` | `post_id`, or the requested post id |
162
160
  | `author_id` | `author_id` |
163
- | `text` | `text` |
161
+ | `text` | `text`, or `message` when `text` is absent |
164
162
  | `created_at` | `created_at` |
165
163
  | `platform` | `"x"` |
166
164
 
167
- Pagination: `meta.next_token` → `next_cursor`. `has_more` is true when that token is a non-empty string.
165
+ Pagination: `next_cursor` on the JSON object. `has_more` is true when that value is a non-empty string. List bodies use `posts` and `comments`.
168
166
 
169
167
  ---
170
168
 
171
- ## Facebook (v1 deferred)
169
+ ## Facebook (unofficial read JSON)
170
+
171
+ The injected client returns these objects. The adapter stays inert without `FB_ACCESS_TOKEN` and does not call Facebook or Meta. `GET /pages/{username}`, `GET /pages/id/{id}`, `GET /pages/{id}/posts`, `GET /posts/{id}`, `GET /posts/{id}/comments`.
172
+
173
+ ### User
172
174
 
173
- v1 does not ship a Facebook adapter. When added, use Graph API:
175
+ | Canonical | Source |
176
+ |-----------|--------|
177
+ | `id` | `id` (string) |
178
+ | `username` | `username` |
179
+ | `display_name` | `name` |
180
+ | `bio` | `about` |
181
+ | `profile_url` | `https://www.facebook.com/{username}`, else `url` |
182
+ | `avatar_url` | `picture` |
183
+ | `follower_count` | `followers_count` |
184
+ | `following_count` | `following_count` |
185
+ | `is_verified` | `verified` |
186
+ | `platform` | `"facebook"` |
187
+
188
+ ### Post
174
189
 
175
190
  | Canonical | Source |
176
191
  |-----------|--------|
177
- | User | `/page-id?fields=id,name,about,fan_count,picture` |
178
- | Post | `/page-id/posts` with `message`, `created_time`, `id` |
179
- | `next_cursor` | `paging.cursors.after` |
192
+ | `id` | `id` |
193
+ | `author_id` | `author_id` |
194
+ | `text` | `text`, or `message` when `text` is absent |
195
+ | `created_at` | `created_at` (ISO-8601) |
196
+ | `url` | `url` |
197
+ | `media` | `media[]` with `url`. `video` and `animated_gif` map to `video`; other types map to `image`. |
198
+ | `like_count` | `like_count` |
199
+ | `comment_count` | `comment_count` |
200
+ | `platform` | `"facebook"` |
201
+
202
+ ### Comment
203
+
204
+ | Canonical | Source |
205
+ |-----------|--------|
206
+ | `id` | `id` (empty ids are skipped) |
207
+ | `post_id` | `post_id`, or the requested post id |
208
+ | `author_id` | `author_id` |
209
+ | `text` | `text`, or `message` when `text` is absent |
210
+ | `created_at` | `created_at` |
211
+ | `platform` | `"facebook"` |
180
212
 
181
- Do not port deprecated `facebook-api-wrapper` PHP.
213
+ Pagination matches X: `next_cursor` on the page object. Do not port the deprecated `facebook-api-wrapper` PHP client.
@@ -0,0 +1,34 @@
1
+ # Facebook
2
+
3
+ | | |
4
+ |---|---|
5
+ | Upstream | Injected HTTP client. `get(path, params=None)` returns this package's unofficial read JSON. No transport is bundled. |
6
+ | Official vs unofficial | **Unofficial.** This adapter does not call Facebook or Meta. |
7
+ | Read vs write | **Read only:** `get_user`, `list_user_posts`, `get_post`, `list_post_comments`. No posting, liking, or comment creation. |
8
+ | ToS risk | High for any unofficial reader you attach. This package only normalizes JSON from the client you inject. |
9
+
10
+ ## Auth
11
+
12
+ `FB_ACCESS_TOKEN`, or `access_token=` on the client.
13
+
14
+ The token enables the adapter. It is not sent, logged, or copied into error messages. An explicit `access_token=""` does not fall back to the environment. A blank token is treated as unset.
15
+
16
+ Without a token and without an injected client, every read raises `NotSupported` and does not open a socket. With a token and no injected client, every read raises `PlatformError` and still does not open a socket.
17
+
18
+ ```python
19
+ from rrss import Client
20
+
21
+ fb = Client("facebook", client=http_client)
22
+ user = fb.get_user("examplepage") # page username, @name, or numeric id
23
+ page = fb.list_user_posts(user.id) # GET /pages/{id}/posts
24
+ post = fb.get_post(page.items[0].id) # GET /posts/{id}
25
+ comments = fb.list_post_comments(post.id)
26
+ ```
27
+
28
+ Paths are relative. The injected client chooses the host. Tests use fixtures only and must not call Facebook or Meta.
29
+
30
+ `limit` is clamped to 1..100. `next_cursor` in the JSON becomes `next_cursor` on the page.
31
+
32
+ `include_raw=True` keeps the user or post object the client returned. It does not add the token. Strip secrets before filing an issue.
33
+
34
+ Field mapping: [mapping.md](../mapping.md).
@@ -0,0 +1,34 @@
1
+ # X
2
+
3
+ | | |
4
+ |---|---|
5
+ | Upstream | Injected HTTP client. `get(path, params=None)` returns this package's unofficial read JSON. No transport is bundled. |
6
+ | Official vs unofficial | **Unofficial.** This adapter does not call X. |
7
+ | Read vs write | **Read only:** `get_user`, `list_user_posts`, `get_post`, `list_post_comments`. No tweet, like, repost, follow, or delete. |
8
+ | ToS risk | High for any unofficial reader you attach. This package only normalizes JSON from the client you inject. |
9
+
10
+ ## Auth
11
+
12
+ `X_BEARER_TOKEN`, or `bearer_token=` on the client. `Client("twitter")` is the same adapter.
13
+
14
+ The token enables the adapter. It is not sent, logged, or copied into error messages. An explicit `bearer_token=""` does not fall back to the environment. A blank token is treated as unset.
15
+
16
+ Without a token and without an injected client, every read raises `NotSupported` and does not open a socket. With a token and no injected client, every read raises `PlatformError` and still does not open a socket.
17
+
18
+ ```python
19
+ from rrss import Client
20
+
21
+ x = Client("x", client=http_client) # http_client.get(path, params=None) -> dict
22
+ user = x.get_user("twitterdev") # username, @username, or numeric id
23
+ page = x.list_user_posts("twitterdev") # GET /users/{id}/posts
24
+ post = x.get_post(page.items[0].id) # GET /posts/{id}
25
+ comments = x.list_post_comments(post.id) # GET /posts/{id}/comments
26
+ ```
27
+
28
+ Paths are relative. The injected client chooses the host. Tests pass a fake client and must not call X.
29
+
30
+ `limit` is clamped to 1..100 and sent as `limit`. A non-empty `cursor` is sent as `cursor`. `next_cursor` in the JSON becomes `next_cursor` on the page.
31
+
32
+ `include_raw=True` keeps the user or post object the client returned. It does not add the token. Strip secrets before filing an issue.
33
+
34
+ Field mapping: [mapping.md](../mapping.md).
@@ -1,5 +1,5 @@
1
1
  site_name: rrss
2
- site_description: Unified read client for Instagram, Threads, TikTok, and X
2
+ site_description: Unified read client for Instagram, Threads, TikTok, X, and Facebook
3
3
  docs_dir: docs
4
4
  site_dir: site
5
5
 
@@ -11,7 +11,7 @@ nav:
11
11
  - Threads: platforms/threads.md
12
12
  - TikTok: platforms/tiktok.md
13
13
  - X: platforms/x.md
14
- - Facebook (deferred): platforms/facebook-v1-deferral.md
14
+ - Facebook: platforms/facebook.md
15
15
  - Generated clients: generated-clients.md
16
16
 
17
17
  theme:
@@ -4,8 +4,8 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "rrss-sdk-wrapper"
7
- version = "0.2.0"
8
- description = "Unified social media data client (Instagram, Threads, TikTok)"
7
+ version = "0.2.1"
8
+ description = "Unified social media data client (Instagram, Threads, TikTok, X, Facebook)"
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.11"
11
11
  license = "MIT"
@@ -16,10 +16,10 @@ dependencies = []
16
16
  instagram = []
17
17
  tiktok = []
18
18
  threads = ["httpx>=0.27"]
19
- x = ["tweepy>=4.14"]
19
+ x = []
20
20
  cache = ["redis>=5"]
21
21
  docs = ["mkdocs>=1.6"]
22
- all = ["httpx>=0.27", "tweepy>=4.14"]
22
+ all = ["httpx>=0.27"]
23
23
  dev = [
24
24
  "pytest>=8.0",
25
25
  "ruff>=0.6",
@@ -47,4 +47,4 @@ __all__ = [
47
47
  "poll_user_posts",
48
48
  ]
49
49
 
50
- __version__ = "0.2.0"
50
+ __version__ = "0.2.1"
@@ -0,0 +1,154 @@
1
+ """Read-only unofficial Facebook adapter.
2
+
3
+ Reads go through an injected HTTP client. This module does not call Facebook
4
+ or Meta, import an HTTP library, or open a socket. Without ``FB_ACCESS_TOKEN``
5
+ and without an injected client, every method raises ``NotSupported``. The
6
+ token only enables the adapter: it is never sent, logged, or copied into errors.
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ import os
12
+ from typing import Any
13
+ from urllib.parse import quote
14
+
15
+ from rrss.adapters.base import BaseAdapter
16
+ from rrss.adapters.read_http import (
17
+ JsonHttp,
18
+ exposes_secret,
19
+ map_status,
20
+ page_params,
21
+ raise_mapped,
22
+ )
23
+ from rrss.errors import NotFound, NotSupported, PlatformError
24
+ from rrss.models import Comment, CursorPage, Post, User
25
+ from rrss.normalize import facebook as normalize
26
+
27
+
28
+ class FacebookAdapter(BaseAdapter):
29
+ """Unofficial Facebook reads. No post, like, or comment-creation methods."""
30
+
31
+ platform = "facebook"
32
+
33
+ def __init__(
34
+ self,
35
+ *,
36
+ access_token: str | None = None,
37
+ client: JsonHttp | None = None,
38
+ include_raw: bool = False,
39
+ ) -> None:
40
+ if access_token is None:
41
+ access_token = os.environ.get("FB_ACCESS_TOKEN")
42
+ token = (access_token or "").strip()
43
+ self._token = token or None
44
+ self._client = client
45
+ self._include_raw = include_raw
46
+
47
+ def __repr__(self) -> str:
48
+ enabled = self._token is not None
49
+ return f"FacebookAdapter(enabled={enabled}, client={self._client is not None})"
50
+
51
+ @property
52
+ def _secrets(self) -> tuple[str, ...]:
53
+ if self._token:
54
+ return (self._token,)
55
+ return ()
56
+
57
+ def _ensure_client(self) -> JsonHttp:
58
+ if self._client is not None:
59
+ return self._client
60
+ if not self._token:
61
+ raise NotSupported(
62
+ "Facebook read adapter is inert without FB_ACCESS_TOKEN; no request was sent",
63
+ )
64
+ raise PlatformError(
65
+ "Unofficial Facebook reads need an injected HTTP client; no request was sent",
66
+ )
67
+
68
+ def _guard(self, *values: str) -> None:
69
+ for value in values:
70
+ if exposes_secret(value, self._secrets):
71
+ raise PlatformError("refusing to put a credential in a request")
72
+
73
+ def _get(self, path: str, *, params: dict[str, str] | None = None) -> Any:
74
+ self._guard(path)
75
+ if params:
76
+ self._guard(*params.values())
77
+ client = self._ensure_client()
78
+ try:
79
+ return client.get(path, params=params)
80
+ except Exception as exc:
81
+ raise_mapped(
82
+ exc,
83
+ map_status(exc, platform="Facebook", secrets=self._secrets),
84
+ self._secrets,
85
+ )
86
+
87
+ def get_user(self, user_ref: str) -> User:
88
+ self._ensure_client()
89
+ ref = user_ref.strip().lstrip("@")
90
+ self._guard(ref)
91
+ if not ref:
92
+ raise NotFound("Facebook user ref was empty")
93
+ path = (
94
+ f"/pages/id/{quote(ref, safe='')}"
95
+ if ref.isdigit()
96
+ else f"/pages/{quote(ref, safe='')}"
97
+ )
98
+ raw = self._get(path)
99
+ return normalize.user_from_facebook(raw, include_raw=self._include_raw)
100
+
101
+ def list_user_posts(
102
+ self,
103
+ user_ref: str,
104
+ *,
105
+ cursor: str | None = None,
106
+ limit: int = 25,
107
+ ) -> CursorPage[Post]:
108
+ self._ensure_client()
109
+ ref = user_ref.strip().lstrip("@")
110
+ self._guard(ref)
111
+ if cursor:
112
+ self._guard(cursor)
113
+ if not ref:
114
+ raise NotFound("Facebook user ref was empty")
115
+ user_id = ref if ref.isdigit() else self.get_user(ref).id
116
+ self._guard(user_id)
117
+ raw = self._get(
118
+ f"/pages/{quote(user_id, safe='')}/posts",
119
+ params=page_params(limit, cursor),
120
+ )
121
+ return normalize.posts_page_from_facebook(raw, include_raw=self._include_raw)
122
+
123
+ def get_post(self, post_id: str) -> Post:
124
+ self._ensure_client()
125
+ self._guard(post_id)
126
+ post_id = post_id.strip()
127
+ if not post_id:
128
+ raise NotFound("Facebook post id was empty")
129
+ raw = self._get(f"/posts/{quote(post_id, safe='')}")
130
+ return normalize.post_from_facebook(raw, include_raw=self._include_raw)
131
+
132
+ def list_post_comments(
133
+ self,
134
+ post_id: str,
135
+ *,
136
+ cursor: str | None = None,
137
+ limit: int = 25,
138
+ ) -> CursorPage[Comment]:
139
+ self._ensure_client()
140
+ self._guard(post_id)
141
+ if cursor:
142
+ self._guard(cursor)
143
+ post_id = post_id.strip()
144
+ if not post_id:
145
+ raise NotFound("Facebook post id was empty")
146
+ raw = self._get(
147
+ f"/posts/{quote(post_id, safe='')}/comments",
148
+ params=page_params(limit, cursor),
149
+ )
150
+ return normalize.comments_page_from_facebook(
151
+ raw,
152
+ post_id=post_id,
153
+ include_raw=self._include_raw,
154
+ )