socialscrape-cli 0.1.0__py3-none-any.whl

socialscrape_cli/client.py

@@ -0,0 +1,104 @@
+# GENERATED COPY of sdks/mcp/socialscrape_mcp/client.py: edit that file, then run sdks/mcp/generate.py.
+"""A small synchronous client for the SocialScrape API.
+
+One job: send a request with the caller's key and hand back the envelope.
+It never raises for an API failure (the envelope carries the error); a
+network failure becomes a synthetic, retryable error envelope with the same
+shape, so callers have one path to handle.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from dataclasses import dataclass
+from typing import Any, Callable
+from urllib.parse import quote
+
+import httpx
+
+from . import __version__
+
+DEFAULT_API_URL = "https://api.socialscrape.dev"
+USER_AGENT = f"socialscrape-mcp/{__version__}"
+
+
+@dataclass
+class ApiResponse:
+    status: int
+    body: dict[str, Any]
+    headers: dict[str, str]
+
+    @property
+    def ok(self) -> bool:
+        return bool(self.body.get("ok"))
+
+
+def wire_value(v: Any) -> Any:
+    """Query strings carry text: booleans as true/false."""
+    if isinstance(v, bool):
+        return "true" if v else "false"
+    return v
+
+
+class ApiClient:
+    def __init__(self, base_url: str = DEFAULT_API_URL, *, http: httpx.Client | None = None, timeout: float = 70.0,
+                 sleep: Callable[[float], None] = time.sleep, max_retry_wait: float = 5.0,
+                 user_agent: str = USER_AGENT):
+        self.base_url = base_url.rstrip("/")
+        self.user_agent = user_agent
+        self._owns_http = http is None
+        self.http = http or httpx.Client(timeout=timeout)
+        self._sleep = sleep
+        self.max_retry_wait = max_retry_wait
+
+    def close(self) -> None:
+        if self._owns_http:
+            self.http.close()
+
+    def request(self, method: str, path: str, *, api_key: str | None, query: dict[str, Any] | None = None,
+                body: Any = None, path_params: dict[str, str] | None = None) -> ApiResponse:
+        for name, value in (path_params or {}).items():
+            path = path.replace("{" + name + "}", quote(str(value), safe=""))
+        headers = {"x-api-key": api_key or "", "user-agent": self.user_agent, "accept": "application/json"}
+        params = {k: wire_value(v) for k, v in (query or {}).items() if v is not None}
+        attempts = 0
+        while True:
+            attempts += 1
+            resp = self._send(method, path, headers, params, body)
+            err = resp.body.get("error") or {}
+            if err.get("code") == "rate_limited" and attempts == 1:
+                wait = _retry_after(resp.headers)
+                if wait is not None and wait <= self.max_retry_wait:
+                    self._sleep(wait)  # a failure is free, so one polite retry costs nothing
+                    continue
+            return resp
+
+    def _send(self, method: str, path: str, headers: dict, params: dict, body: Any) -> ApiResponse:
+        try:
+            r = self.http.request(method, self.base_url + path, headers=headers, params=params or None,
+                                  json=body if body is not None else None)
+        except httpx.TimeoutException:
+            return _synthetic(504, "upstream_timeout", "the request to the SocialScrape API timed out", True)
+        except httpx.HTTPError as e:
+            return _synthetic(502, "upstream_error", f"could not reach the SocialScrape API: {type(e).__name__}", True)
+        try:
+            data = r.json()
+        except (json.JSONDecodeError, ValueError):
+            data = None
+        if not isinstance(data, dict):
+            return _synthetic(r.status_code if r.status_code >= 400 else 502, "upstream_error",
+                              f"the API answered HTTP {r.status_code} with a body that is not JSON", True)
+        return ApiResponse(r.status_code, data, {k.lower(): v for k, v in r.headers.items()})
+
+
+def _retry_after(headers: dict[str, str]) -> float | None:
+    try:
+        return float(headers.get("retry-after", ""))
+    except ValueError:
+        return None
+
+
+def _synthetic(status: int, code: str, message: str, retryable: bool) -> ApiResponse:
+    return ApiResponse(status, {"ok": False, "error": {"code": code, "message": message, "retryable": retryable},
+                                "credits_charged": 0, "request_id": None}, {})

socialscrape_cli/config.py

@@ -0,0 +1,40 @@
+"""The CLI's saved settings: ~/.config/socialscrape/config.json (mode 0600).
+
+Order of precedence for the key: --key, SOCIALSCRAPE_API_KEY, this file.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+
+def config_path(env: dict[str, str] | None = None) -> Path:
+    e = os.environ if env is None else env
+    base = e.get("XDG_CONFIG_HOME") or str(Path(e.get("HOME") or Path.home()) / ".config")
+    return Path(base) / "socialscrape" / "config.json"
+
+
+def load(path: Path) -> dict:
+    try:
+        data = json.loads(path.read_text())
+    except (OSError, ValueError):
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def save(path: Path, data: dict) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_suffix(".tmp")
+    fd = os.open(tmp, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)  # never world-readable, not even briefly
+    os.fchmod(fd, 0o600)  # a leftover file from an older run keeps its old mode otherwise
+    with os.fdopen(fd, "w") as f:
+        f.write(json.dumps(data, indent=1) + "\n")
+    os.replace(tmp, path)
+
+
+def mask(key: str | None) -> str:
+    if not key:
+        return "(none)"
+    return key[:12] + "..." + key[-2:] if len(key) > 16 else "(set)"

socialscrape_cli/table.py

@@ -0,0 +1,76 @@
+"""Plain-text tables for `--output table`: no colour, no box drawing, so the
+output pastes cleanly into a terminal, a ticket or an agent's context."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+PREFERRED = ("id", "handle", "name", "title", "text", "author.handle", "author.name", "published_at", "created_at",
+             "stats.views", "stats.likes", "stats.comments", "stats.followers", "language", "url")
+MAX_COLS = 6
+CELL = 42
+
+
+def flatten(obj: Any, prefix: str = "", depth: int = 2) -> dict[str, Any]:
+    out: dict[str, Any] = {}
+    if isinstance(obj, dict):
+        for k, v in obj.items():
+            key = f"{prefix}{k}"
+            if isinstance(v, dict) and depth > 0:
+                out.update(flatten(v, key + ".", depth - 1))
+            else:
+                out[key] = v
+    return out
+
+
+def cell(v: Any, width: int = CELL) -> str:
+    if v is None:
+        return ""
+    if isinstance(v, (dict, list)):
+        s = json.dumps(v, ensure_ascii=False, separators=(",", ":"))
+        if isinstance(v, list) and all(isinstance(x, (str, int, float)) for x in v):
+            s = ", ".join(str(x) for x in v)
+    else:
+        s = str(v)
+    s = " ".join(s.split())
+    return s if len(s) <= width else s[: width - 3] + "..."
+
+
+def render(data: Any) -> str:
+    """A list page becomes rows; any other object becomes a field/value list."""
+    if isinstance(data, dict) and isinstance(data.get("items"), list):
+        text = _rows(data["items"])
+        tail = []
+        if data.get("has_more"):
+            tail.append(f"more available, cursor: {data.get('cursor')}")
+        return text + ("\n" + "\n".join(tail) if tail else "")
+    if isinstance(data, dict) and isinstance(data.get("results"), list):
+        return _rows(data["results"])
+    if isinstance(data, dict):
+        flat = flatten(data)
+        width = max((len(k) for k in flat), default=0)
+        return "\n".join(f"{k.ljust(width)}  {cell(v, 100)}" for k, v in flat.items() if v not in (None, [], {}))
+    return cell(data, 200)
+
+
+def _rows(items: list[Any]) -> str:
+    if not items:
+        return "(no items)"
+    flat = [flatten(i) if isinstance(i, dict) else {"value": i} for i in items]
+    present = {}
+    for row in flat:
+        for k, v in row.items():
+            if v not in (None, "", [], {}):
+                present[k] = present.get(k, 0) + 1
+    cols = [c for c in PREFERRED if present.get(c, 0) * 2 >= len(flat)]
+    for c in present:  # then whatever else is common and scalar
+        if len(cols) >= MAX_COLS:
+            break
+        if c not in cols and present[c] * 2 >= len(flat) and not any(isinstance(r.get(c), (dict, list)) for r in flat):
+            cols.append(c)
+    cols = cols[:MAX_COLS] or list(present)[:MAX_COLS]
+    grid = [[cell(r.get(c)) for c in cols] for r in flat]
+    widths = [max(len(c), *(len(row[i]) for row in grid)) for i, c in enumerate(cols)]
+    line = lambda cells: "  ".join(c.ljust(w) for c, w in zip(cells, widths)).rstrip()  # noqa: E731
+    return "\n".join([line(cols), line(["-" * w for w in widths]), *[line(r) for r in grid]])

socialscrape_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,76 @@
+Metadata-Version: 2.4
+Name: socialscrape-cli
+Version: 0.1.0
+Summary: SocialScrape on the command line: social media data as JSON or a table
+License-Expression: MIT
+Project-URL: Homepage, https://socialscrape.dev
+Project-URL: Documentation, https://socialscrape.dev/docs
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx<1,>=0.27
+Dynamic: license-file
+
+# socialscrape-cli
+
+`socialscrape`: social media data on the command line, as JSON for scripts and agents or a
+table for people. Python 3.10+, one dependency (`httpx`).
+
+```
+pip install socialscrape-cli        # or: pipx install socialscrape-cli
+socialscrape login                  # paste your key once (saved to ~/.config/socialscrape/config.json, mode 600)
+
+socialscrape github user torvalds
+socialscrape transcript "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
+socialscrape search threads "open source" -o table
+socialscrape threads profile-posts zuck --pages 3
+socialscrape ad-libraries facebook-search nike --region US --all --max-credits 5
+socialscrape credits
+```
+
+The CLI reads the same endpoint catalog as the `socialscrape-mcp` server, so a platform appears here
+in the release after its endpoints are built. It uses plain `httpx` and needs no other SocialScrape package.
+
+## Commands
+
+| | |
+|---|---|
+| `socialscrape <platform> <resource> [value] [--param value]` | Any endpoint. `socialscrape github --help` lists a platform's resources, `socialscrape github user --help` the parameters. Resource names use hyphens: `profile.posts` is `profile-posts` (dots and underscores also work). |
+| `transcript URL` | Transcript of a video or post on any supported platform. |
+| `profile`, `post`, `comments`, `search PLATFORM VALUE` | The same job on any platform that has it (`search` takes `--kind`). Shortcuts for `<platform> <resource>`. |
+| `credits`, `usage [daily\|routes]`, `job ID` | Balance, request history, an async job. All free. |
+| `batch FILE\|-` | Up to 100 requests in one call from JSON: `[{"endpoint": "github.user", "params": {"handle": "torvalds"}}]`. |
+| `monitors list\|create\|delete\|test\|deliveries\|events\|redeliver` | Webhook monitors. |
+| `endpoints [PLATFORM]` | What can be called. |
+| `login`, `logout`, `config` | Save, remove, show (masked) the key. |
+
+The positional `value` is the resource's main parameter; the form is detected (a URL goes to `url`,
+anything else to `handle`, `id` or `query`). Every parameter is also a flag (`--handle`, `--url`,
+`--sort`, `--limit`, `--region`, ...), with the API's aliases (`--username`).
+
+## Output
+
+* stdout is data only: pretty JSON on a terminal, compact JSON in a pipe. `-o table` and `-o ndjson`
+  (one item per line) change the format; `--envelope` prints the whole response (`data`,
+  `credits_charged`, `cursor`, ...); `--raw` asks for the platform's original object (`raw=true`)
+  and prints the whole response.
+* stderr carries the price: `credits charged: 1 | remaining: 4999`. `-q` silences it.
+* `--dry-run` prints the request and what it would cost and sends nothing (no key needed).
+
+## Paging
+
+`--pages N` follows the cursor up to N pages; `--all` follows it to the end (cap `--max-pages`,
+default 50). Each page costs credits, so bound it: `--max-items N`, `--max-credits N`. The merged
+result is one list with every item; if a later page fails you still get the earlier ones.
+
+## Exit codes
+
+`0` ok, `1` API error (not found, private, invalid parameters, ...), `2` usage error (nothing was
+sent, nothing charged), `3` key or credits (`unauthorized`, `forbidden`, `insufficient_credits`),
+`4` retryable (rate limited, upstream blocked or timed out, network). Failures are free.
+
+## Key and server
+
+The key comes from `--key`, then `$SOCIALSCRAPE_API_KEY`, then the saved config. `login` checks the
+key against the API before it saves anything. `--api-url` or `$SOCIALSCRAPE_API_URL` points at another
+server (default `https://api.socialscrape.dev`).

socialscrape_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+socialscrape_cli/__init__.py,sha256=IqDue7WZynb9OVDQO70UGbpf1qWOrGwCxeB2Yn44yVo,60
+socialscrape_cli/__main__.py,sha256=E6Gls0DNz8GQK2K-kOUIx8cYhgANW_CH54VKrfCfs14,52
+socialscrape_cli/catalog.json,sha256=Ami-dF3Qevt1Z8RQjOLG0s6IPZrv9ngpN5auOIUv2IU,461860
+socialscrape_cli/catalog.py,sha256=7y3WW6E-JflPMe2HJvnl0qzIEVW_T3gwduVK8D4GOZg,5926
+socialscrape_cli/cli.py,sha256=bNfjMDvsoTQ1c8tTffGLIzIyK1eAq4XBt_cJoMLXK2I,30323
+socialscrape_cli/client.py,sha256=5GW4dikJfK5Rr6arcj1jVuA4chgd8vSx4VXS7VlJCZo,4240
+socialscrape_cli/config.py,sha256=MEeFe3TOJQ2UuBUB3nwLn2wNWaS8R83-vPNNsXAxOyc,1264
+socialscrape_cli/table.py,sha256=IDEUaIBzoJnNkE-WttgzQkHeqxkoyHXove0m3qCAZrQ,3106
+socialscrape_cli-0.1.0.dist-info/licenses/LICENSE,sha256=LobQzESyU4GpkJMUTQA4TkMEwYV73_t5e07NyYN4EZI,1093
+socialscrape_cli-0.1.0.dist-info/METADATA,sha256=BJOmjAvKBijF3BdvEEL7FsLiEhxpe94DWONO-hKAsTU,3958
+socialscrape_cli-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+socialscrape_cli-0.1.0.dist-info/entry_points.txt,sha256=t7bvxrMj-ybPujPXLxPuHIIOQ79Tn9dpu5NnGtAf6Bk,59
+socialscrape_cli-0.1.0.dist-info/top_level.txt,sha256=cPrNs4Sb-K0jUMRInQMP38J38dWkJtc6yPkMUaTugdE,17
+socialscrape_cli-0.1.0.dist-info/RECORD,,

socialscrape_cli-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
+

socialscrape_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+socialscrape = socialscrape_cli.cli:main

socialscrape_cli-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The Casey Company LLC (SocialScrape)
+
+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.

socialscrape_cli-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+socialscrape_cli