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.
- {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/.env.example +6 -1
- {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/CHANGELOG.md +11 -6
- {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/PKG-INFO +7 -9
- {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/README.md +5 -5
- {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/SECURITY.md +1 -1
- {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/docs/index.md +2 -3
- {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/docs/mapping.md +62 -30
- rrss_sdk_wrapper-0.2.1/docs/platforms/facebook.md +34 -0
- rrss_sdk_wrapper-0.2.1/docs/platforms/x.md +34 -0
- {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/mkdocs.yml +2 -2
- {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/pyproject.toml +4 -4
- {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/rrss/__init__.py +1 -1
- rrss_sdk_wrapper-0.2.1/rrss/adapters/facebook.py +154 -0
- rrss_sdk_wrapper-0.2.1/rrss/adapters/read_http.py +105 -0
- rrss_sdk_wrapper-0.2.1/rrss/adapters/x.py +154 -0
- {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/rrss/cli.py +1 -1
- {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/rrss/client.py +2 -5
- {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/rrss/gateway.py +1 -5
- rrss_sdk_wrapper-0.2.1/rrss/normalize/common.py +97 -0
- rrss_sdk_wrapper-0.2.1/rrss/normalize/facebook.py +102 -0
- rrss_sdk_wrapper-0.2.1/rrss/normalize/x.py +103 -0
- rrss_sdk_wrapper-0.2.1/tests/fixtures/facebook/comments.json +12 -0
- rrss_sdk_wrapper-0.2.1/tests/fixtures/facebook/post.json +12 -0
- rrss_sdk_wrapper-0.2.1/tests/fixtures/facebook/posts.json +18 -0
- rrss_sdk_wrapper-0.2.1/tests/fixtures/facebook/user.json +10 -0
- rrss_sdk_wrapper-0.2.1/tests/fixtures/x/comments.json +13 -0
- rrss_sdk_wrapper-0.2.1/tests/fixtures/x/post.json +12 -0
- rrss_sdk_wrapper-0.2.1/tests/fixtures/x/posts.json +20 -0
- rrss_sdk_wrapper-0.2.1/tests/fixtures/x/user.json +10 -0
- {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/tests/test_client.py +4 -2
- rrss_sdk_wrapper-0.2.1/tests/test_facebook.py +222 -0
- {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/tests/test_gateway.py +2 -0
- rrss_sdk_wrapper-0.2.1/tests/test_x.py +322 -0
- rrss_sdk_wrapper-0.2.0/docs/platforms/facebook-v1-deferral.md +0 -17
- rrss_sdk_wrapper-0.2.0/docs/platforms/x.md +0 -38
- rrss_sdk_wrapper-0.2.0/rrss/adapters/x.py +0 -224
- rrss_sdk_wrapper-0.2.0/rrss/normalize/x.py +0 -192
- rrss_sdk_wrapper-0.2.0/tests/fixtures/x/replies.json +0 -21
- rrss_sdk_wrapper-0.2.0/tests/fixtures/x/tweets.json +0 -20
- rrss_sdk_wrapper-0.2.0/tests/fixtures/x/user.json +0 -17
- rrss_sdk_wrapper-0.2.0/tests/test_x.py +0 -351
- {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/.gitignore +0 -0
- {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/compose.yaml +0 -0
- {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/docs/generated-clients.md +0 -0
- {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/docs/platforms/instagram.md +0 -0
- {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/docs/platforms/threads.md +0 -0
- {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/docs/platforms/tiktok.md +0 -0
- {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/generated/go/client.go +0 -0
- {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/generated/go/go.mod +0 -0
- {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/generated/go/models.go +0 -0
- {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/generated/python/rrss_client.py +0 -0
- {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/generated/rust/Cargo.toml +0 -0
- {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/generated/rust/src/lib.rs +0 -0
- {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/rrss/adapters/base.py +0 -0
- {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/rrss/adapters/instagram.py +0 -0
- {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/rrss/adapters/threads.py +0 -0
- {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/rrss/adapters/tiktok.py +0 -0
- {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/rrss/adapters/x_stub.py +0 -0
- {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/rrss/auth/__init__.py +0 -0
- {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/rrss/cache.py +0 -0
- {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/rrss/errors.py +0 -0
- {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/rrss/models.py +0 -0
- {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/rrss/normalize/__init__.py +0 -0
- {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/rrss/normalize/instagram.py +0 -0
- {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/rrss/normalize/threads.py +0 -0
- {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/rrss/normalize/tiktok.py +0 -0
- {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/rrss/ratelimit.py +0 -0
- {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/rrss/serialize.py +0 -0
- {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/rrss/stream.py +0 -0
- {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/schemas/openapi.yaml +0 -0
- {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/schemas/rrss-v1.json +0 -0
- {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/scripts/generate_client_stub.py +0 -0
- {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/sidecar/threads/.dockerignore +0 -0
- {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/sidecar/threads/Dockerfile +0 -0
- {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/sidecar/threads/README.md +0 -0
- {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/sidecar/threads/package-lock.json +0 -0
- {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/sidecar/threads/package.json +0 -0
- {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/sidecar/threads/server.js +0 -0
- {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/tests/fakes.py +0 -0
- {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/tests/fixtures/instagram/media.json +0 -0
- {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/tests/fixtures/instagram/user.json +0 -0
- {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/tests/fixtures/threads/threads.json +0 -0
- {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/tests/fixtures/threads/user.json +0 -0
- {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/tests/fixtures/tiktok/user.json +0 -0
- {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/tests/fixtures/tiktok/video.json +0 -0
- {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/tests/test_adapter_edges.py +0 -0
- {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/tests/test_cache.py +0 -0
- {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/tests/test_cli.py +0 -0
- {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/tests/test_errors_retry_integration.py +0 -0
- {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/tests/test_generated_client.py +0 -0
- {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/tests/test_normalize.py +0 -0
- {rrss_sdk_wrapper-0.2.0 → rrss_sdk_wrapper-0.2.1}/tests/test_normalize_edges.py +0 -0
- {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
|
|
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
|
-
|
|
7
|
+
## 0.2.1 — 2026-11-20
|
|
8
8
|
|
|
9
9
|
### Added
|
|
10
10
|
|
|
11
|
-
- Platform guides for Instagram, Threads, TikTok, and
|
|
12
|
-
- X read-only adapter
|
|
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
|
-
|
|
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
|
|
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
|
|
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.
|
|
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
|
|
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
|
-
|
|
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]" #
|
|
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 |
|
|
171
|
-
| Facebook |
|
|
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
|
|
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
|
-
|
|
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]" #
|
|
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 |
|
|
144
|
-
| Facebook |
|
|
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
|
|
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 (
|
|
121
|
+
## X (unofficial read JSON)
|
|
122
122
|
|
|
123
|
-
|
|
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` | `
|
|
130
|
-
| `username` | `
|
|
131
|
-
| `display_name` | `
|
|
132
|
-
| `bio` | `
|
|
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` | `
|
|
135
|
-
| `follower_count` | `
|
|
136
|
-
| `following_count` | `
|
|
137
|
-
| `is_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` | `
|
|
145
|
-
| `author_id` | `
|
|
146
|
-
| `text` | `
|
|
147
|
-
| `created_at` | `
|
|
148
|
-
| `url` | `https://x.com/{
|
|
149
|
-
| `media` | `
|
|
150
|
-
| `like_count` | `
|
|
151
|
-
| `comment_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` |
|
|
161
|
-
| `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: `
|
|
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 (
|
|
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
|
-
|
|
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
|
-
|
|
|
178
|
-
|
|
|
179
|
-
| `
|
|
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
|
|
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
|
|
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.
|
|
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 = [
|
|
19
|
+
x = []
|
|
20
20
|
cache = ["redis>=5"]
|
|
21
21
|
docs = ["mkdocs>=1.6"]
|
|
22
|
-
all = ["httpx>=0.27"
|
|
22
|
+
all = ["httpx>=0.27"]
|
|
23
23
|
dev = [
|
|
24
24
|
"pytest>=8.0",
|
|
25
25
|
"ruff>=0.6",
|
|
@@ -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
|
+
)
|