socialsforai 0.1.0__py3-none-any.whl

socialsforai/__init__.py

@@ -0,0 +1,13 @@
+"""SocialsForAI: post, schedule and measure on social networks from Python and AI agents.
+
+    from socialsforai import SocialsForAI
+    socials = SocialsForAI()  # reads SOCIALSFORAI_API_KEY
+    socials.posts.create(["linkedin", "bluesky"], "We just shipped webhooks.", dry_run=True)
+
+Docs: https://socialsforai.com/docs · Agent guide: https://socialsforai.com/llms.txt
+"""
+
+from ._client import DEFAULT_BASE_URL, VERSION, SocialsError, SocialsForAI, verify_webhook
+
+__all__ = ["SocialsForAI", "SocialsError", "verify_webhook", "DEFAULT_BASE_URL", "VERSION"]
+__version__ = VERSION

socialsforai/_client.py

@@ -0,0 +1,335 @@
+"""The HTTP client. Standard library only, so it installs anywhere an agent runs."""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import os
+import time
+import uuid
+from typing import Any, Mapping
+from urllib import error as urlerror
+from urllib import parse, request
+
+DEFAULT_BASE_URL = "https://socialsforai.com"
+VERSION = "0.1.0"
+
+
+class SocialsError(Exception):
+    """An error the API returned. `code` is stable, `fix` says what to do, `issues` lists failed checks."""
+
+    def __init__(self, status: int, code: str | None, message: str, fix: str | None = None, issues: list[dict] | None = None, request_id: str | None = None):
+        super().__init__(message)
+        self.status = status
+        self.code = code or "http_error"
+        self.message = message
+        self.fix = fix
+        self.issues = issues or []
+        self.request_id = request_id
+
+    def to_dict(self) -> dict:
+        """The error as the API sent it, for handing back to a model."""
+        out: dict[str, Any] = {"code": self.code, "message": self.message}
+        if self.fix:
+            out["fix"] = self.fix
+        if self.issues:
+            out["issues"] = self.issues
+        if self.request_id:
+            out["request_id"] = self.request_id
+        return {"error": out}
+
+    def __str__(self) -> str:
+        return f"{self.code}: {self.message}" + (f" Fix: {self.fix}" if self.fix else "")
+
+
+def _query(params: Mapping[str, Any] | None) -> str:
+    if not params:
+        return ""
+    pairs = []
+    for k, v in params.items():
+        if v is None:
+            continue
+        if isinstance(v, bool):
+            v = "true" if v else "false"
+        elif isinstance(v, (list, tuple)):
+            v = ",".join(str(x) for x in v)
+        pairs.append((k, str(v)))
+    return ("?" + parse.urlencode(pairs)) if pairs else ""
+
+
+def _quote(s: str) -> str:
+    return parse.quote(str(s), safe="")
+
+
+class _Group:
+    def __init__(self, client: "SocialsForAI"):
+        self._c = client
+
+
+class Workspaces(_Group):
+    def create(self, name: str | None = None, email: str | None = None) -> dict:
+        """Create a workspace and get an API key. Needs no key. The client starts using the new key."""
+        body = {k: v for k, v in {"name": name, "email": email}.items() if v}
+        ws = self._c.request("POST", "/v1/workspaces", body=body, auth=False)
+        if ws.get("api_key") and not self._c.api_key:
+            self._c.api_key = ws["api_key"]
+        return ws
+
+
+class Workspace(_Group):
+    def get(self) -> dict:
+        return self._c.request("GET", "/v1/workspace")
+
+    def set_owner_email(self, email: str) -> dict:
+        """Attach the owner's email (only while none is set): dashboard sign-in, recovery, paying for a plan."""
+        return self._c.request("PATCH", "/v1/workspace", body={"email": email})
+
+
+class Accounts(_Group):
+    def list(self, platform: str | None = None, external_ref: str | None = None, status: str | None = None) -> list[dict]:
+        return self._c.request("GET", "/v1/accounts" + _query({"platform": platform, "external_ref": external_ref, "status": status}))["data"]
+
+    def get(self, id: str) -> dict:
+        return self._c.request("GET", f"/v1/accounts/{_quote(id)}")
+
+    def connect(self, platform: str, credentials: Mapping[str, str], external_ref: str | None = None) -> dict:
+        """Connect Bluesky, Mastodon, Telegram, Discord, Slack or Nostr with credentials the owner gave you (or "sandbox" with {})."""
+        body: dict[str, Any] = {"platform": platform, "credentials": dict(credentials)}
+        if external_ref:
+            body["external_ref"] = external_ref
+        return self._c.request("POST", "/v1/accounts", body=body)
+
+    def disconnect(self, id: str) -> dict:
+        return self._c.request("DELETE", f"/v1/accounts/{_quote(id)}")
+
+
+class ConnectLinks(_Group):
+    def create(self, platforms: list[str] | None = None, external_ref: str | None = None, redirect_url: str | None = None, expires_in: int | None = None) -> dict:
+        body = {k: v for k, v in {"platforms": platforms, "external_ref": external_ref, "redirect_url": redirect_url, "expires_in": expires_in}.items() if v is not None}
+        return self._c.request("POST", "/v1/connect-links", body=body)
+
+    def get(self, id: str, wait_seconds: int | None = None, until: str | None = None) -> dict:
+        """The link's status. With wait_seconds (max 120) it holds until the owner finishes."""
+        return self._c.request("GET", f"/v1/connect-links/{_quote(id)}" + _query({"wait": wait_seconds, "until": until}))
+
+    def wait_for(self, id: str, until: str = "all", timeout: float = 900) -> dict:
+        """Keep waiting until the owner has connected (all networks, or any with until="any") or the link expired."""
+        deadline = time.monotonic() + timeout
+        while True:
+            s = self.get(id, wait_seconds=60, until=until)
+            if s.get("status") in ("connected", "expired") or (until == "any" and s.get("status") == "partially_connected") or time.monotonic() >= deadline:
+                return s
+
+
+class Posts(_Group):
+    def create(self, accounts: list[str], text: str = "", *, idempotency_key: str | None = None, **fields: Any) -> dict:
+        """Publish now or schedule. Any API field works as a keyword: media, link, thread, auto_thread, poll,
+        scheduled_at ("best" too), timezone, repeat, reply_to, reply_to_comment, first_comment, platform_options,
+        approval="required", dry_run=True, wait=True. An idempotency key is generated when you don't pass one,
+        so retries never publish twice; pass your own to make your own retries safe too."""
+        body = {"accounts": accounts, "text": text, **fields}
+        key = idempotency_key or body.pop("idempotency_key", None) or (None if body.get("dry_run") else str(uuid.uuid4()))
+        return self._c.request("POST", "/v1/posts", body=body, headers={"Idempotency-Key": key} if key else None)
+
+    def create_many(self, posts: list[dict], *, dry_run: bool = False, idempotency_key: str | None = None) -> dict:
+        """Up to 50 posts in one request (a content calendar). Each is checked and created by itself."""
+        key = idempotency_key or (None if dry_run else str(uuid.uuid4()))
+        return self._c.request("POST", "/v1/posts/batch", body={"posts": posts, "dry_run": dry_run}, headers={"Idempotency-Key": key} if key else None)
+
+    def list(self, status: str | None = None, series_id: str | None = None, limit: int | None = None, before: str | None = None) -> dict:
+        return self._c.request("GET", "/v1/posts" + _query({"status": status, "series_id": series_id, "limit": limit, "before": before}))
+
+    def get(self, id: str) -> dict:
+        return self._c.request("GET", f"/v1/posts/{_quote(id)}")
+
+    def update(self, id: str, **fields: Any) -> dict:
+        """Edit a post that hasn't started publishing. Fields left out stay; scheduled_at=None publishes now."""
+        return self._c.request("PATCH", f"/v1/posts/{_quote(id)}", body=fields)
+
+    def delete(self, id: str, accounts: list[str] | None = None, series: bool = False) -> dict:
+        """Delete it everywhere it went out (or only from some accounts). series=True cancels the rest of a repeat series."""
+        return self._c.request("DELETE", f"/v1/posts/{_quote(id)}" + _query({"accounts": accounts, "series": True if series else None}))
+
+    def metrics(self, id: str) -> dict:
+        return self._c.request("GET", f"/v1/posts/{_quote(id)}/metrics")
+
+    def replies(self, id: str) -> dict:
+        """What people replied under each published copy. Answer one with create(..., reply_to=id, reply_to_comment=reply["id"])."""
+        return self._c.request("GET", f"/v1/posts/{_quote(id)}/replies")
+
+    def wait_for_approval(self, id: str, timeout: float = 3600) -> dict:
+        """Wait while the post is pending_approval; returns it once a person decides (or the timeout passes)."""
+        deadline = time.monotonic() + timeout
+        while True:
+            p = self._c.request("GET", f"/v1/posts/{_quote(id)}?wait=60")
+            if p.get("status") != "pending_approval" or time.monotonic() >= deadline:
+                return p
+
+
+class Media(_Group):
+    def upload(self, data: bytes, content_type: str) -> dict:
+        """Upload a file of up to 4 MB and get a url to use in posts."""
+        return self._c.request("POST", "/v1/media", raw=data, headers={"Content-Type": content_type})
+
+    def upload_file(self, path: str, content_type: str | None = None) -> dict:
+        """Upload a local file of any supported size; returns {url}."""
+        import mimetypes
+
+        ctype = content_type or mimetypes.guess_type(path)[0]
+        if not ctype:
+            raise ValueError(f"Can't tell the type of {path}; pass content_type.")
+        with open(path, "rb") as f:
+            data = f.read()
+        if len(data) <= 4 * 1024 * 1024:
+            return self.upload(data, ctype)
+        up = self._c.request("POST", "/v1/media/uploads", body={"content_type": ctype, "size_bytes": len(data)})
+        req = request.Request(up["upload_url"], data=data, method=up.get("method", "PUT"), headers=up.get("headers") or {"Content-Type": ctype})
+        with request.urlopen(req, timeout=self._c.timeout) as res:
+            if res.status >= 300:
+                raise SocialsError(res.status, "upload_failed", f"The storage upload answered {res.status}.", "Upload again for a fresh URL.")
+        return {"url": up["url"]}
+
+
+class Events(_Group):
+    def list(self, after: str | None = None, types: list[str] | None = None, limit: int | None = None, wait_seconds: int | None = None) -> dict:
+        """What happened since `after` (an event id), oldest first. Keep last_id for the next call."""
+        return self._c.request("GET", "/v1/events" + _query({"after": after, "types": types, "limit": limit, "wait": wait_seconds}))
+
+
+class Webhooks(_Group):
+    def list(self) -> list[dict]:
+        return self._c.request("GET", "/v1/webhooks")["data"]
+
+    def create(self, url: str, events: list[str] | None = None) -> dict:
+        return self._c.request("POST", "/v1/webhooks", body={"url": url, "events": events or ["*"]})
+
+    def delete(self, id: str) -> dict:
+        return self._c.request("DELETE", f"/v1/webhooks/{_quote(id)}")
+
+
+class Keys(_Group):
+    def list(self) -> list[dict]:
+        return self._c.request("GET", "/v1/keys")["data"]
+
+    def create(self, **fields: Any) -> dict:
+        """name, scopes, account_ids, require_approval, daily_post_limit. The key is returned once."""
+        return self._c.request("POST", "/v1/keys", body=fields)
+
+    def revoke(self, id: str) -> dict:
+        return self._c.request("DELETE", f"/v1/keys/{_quote(id)}")
+
+
+class SocialsForAI:
+    """Client for the SocialsForAI API.
+
+        from socialsforai import SocialsForAI
+        socials = SocialsForAI()  # reads SOCIALSFORAI_API_KEY
+        post = socials.posts.create(["linkedin"], "Hello", wait=True)
+    """
+
+    def __init__(self, api_key: str | None = None, *, base_url: str | None = None, max_retries: int = 2, timeout: float = 330):
+        self.api_key = api_key or os.environ.get("SOCIALSFORAI_API_KEY") or os.environ.get("SOCIALS_API_KEY")
+        self.base_url = (base_url or os.environ.get("SOCIALSFORAI_BASE_URL") or DEFAULT_BASE_URL).rstrip("/")
+        self.max_retries = max_retries
+        self.timeout = timeout
+        #: The rate limit as of the last response: {"limit", "remaining", "reset"}, or None.
+        self.rate_limit: dict | None = None
+        self.workspaces = Workspaces(self)
+        self.workspace = Workspace(self)
+        self.accounts = Accounts(self)
+        self.connect_links = ConnectLinks(self)
+        self.posts = Posts(self)
+        self.media = Media(self)
+        self.events = Events(self)
+        self.webhooks = Webhooks(self)
+        self.keys = Keys(self)
+
+    # One-call groups
+    def platforms(self) -> list[dict]:
+        return self.request("GET", "/v1/platforms", auth=False)["data"]
+
+    def usage(self) -> dict:
+        return self.request("GET", "/v1/usage")
+
+    def analytics(self, **params: Any) -> dict:
+        return self.request("GET", "/v1/analytics" + _query(params))
+
+    def health(self) -> dict:
+        return self.request("GET", "/v1/health", auth=False, ok_statuses=(503,))
+
+    def upgrade_link(self, plan: str) -> dict:
+        """A payment link for a human: you can't pay, the workspace owner can."""
+        return self.request("POST", "/v1/upgrade-links", body={"plan": plan})
+
+    def request(self, method: str, path: str, *, body: Any = None, raw: bytes | None = None, headers: Mapping[str, str] | None = None, auth: bool = True, ok_statuses: tuple[int, ...] = ()) -> Any:
+        """Low-level request. Retries 429, 5xx and network errors (honouring Retry-After); never retries other errors."""
+        if auth and not self.api_key:
+            raise SocialsError(0, "missing_api_key", "No API key.", "Pass api_key or set SOCIALSFORAI_API_KEY. Get one with socials.workspaces.create().")
+        h = {"Accept": "application/json", "User-Agent": f"socialsforai-sdk-python/{VERSION}"}
+        if auth:
+            h["Authorization"] = f"Bearer {self.api_key}"
+        data = raw
+        if body is not None and raw is None:
+            data = json.dumps(body).encode()
+            h["Content-Type"] = "application/json"
+        h.update(headers or {})
+        attempt = 0
+        while True:
+            req = request.Request(self.base_url + path, data=data, method=method, headers=h)
+            try:
+                with request.urlopen(req, timeout=self.timeout) as res:
+                    return self._finish(res.status, res.headers, res.read())
+            except urlerror.HTTPError as e:
+                status, hdrs, payload = e.code, e.headers, e.read()
+                if status in ok_statuses:
+                    return self._finish(status, hdrs, payload)
+                if (status == 429 or status >= 500) and attempt < self.max_retries:
+                    after = hdrs.get("Retry-After")
+                    time.sleep(min(float(after), 60) if after and after.replace(".", "", 1).isdigit() else 0.5 * 2**attempt)
+                    attempt += 1
+                    continue
+                self._note_rate(hdrs)
+                err = {}
+                try:
+                    err = json.loads(payload or b"{}").get("error") or {}
+                except ValueError:
+                    pass
+                raise SocialsError(status, err.get("code"), err.get("message") or f"HTTP {status}", err.get("fix"), err.get("issues"), err.get("request_id") or hdrs.get("Request-Id")) from None
+            except (urlerror.URLError, TimeoutError, ConnectionError) as e:
+                if attempt < self.max_retries:
+                    time.sleep(0.5 * 2**attempt)
+                    attempt += 1
+                    continue
+                reason = getattr(e, "reason", e)
+                raise SocialsError(0, "network_error", f"Could not reach {self.base_url}: {reason}", "Check the network and retry; creating a post is safe to retry with the same idempotency key.") from None
+
+    def _note_rate(self, headers: Any) -> None:
+        limit = headers.get("RateLimit-Limit") if headers else None
+        if limit:
+            self.rate_limit = {"limit": int(limit), "remaining": int(headers.get("RateLimit-Remaining") or 0), "reset": int(headers.get("RateLimit-Reset") or 0)}
+
+    def _finish(self, status: int, headers: Any, payload: bytes) -> Any:
+        self._note_rate(headers)
+        if not payload:
+            return None
+        try:
+            return json.loads(payload)
+        except ValueError:
+            return None
+
+
+def verify_webhook(secret: str, header: str | None, raw_body: bytes | str, *, tolerance_seconds: int = 300, now: float | None = None) -> bool:
+    """Check a delivery's Socials-Signature header ("t=<unix>,v1=<hex>"): HMAC-SHA256 of "<t>.<raw body>".
+    Pass the raw request body as received, before parsing it."""
+    parts = dict(p.strip().split("=", 1) for p in (header or "").split(",") if "=" in p)
+    try:
+        t = int(parts["t"])
+        v1 = parts["v1"]
+    except (KeyError, ValueError):
+        return False
+    if abs((now if now is not None else time.time()) - t) > tolerance_seconds:
+        return False
+    body = raw_body.encode() if isinstance(raw_body, str) else raw_body
+    expected = hmac.new(secret.encode(), f"{t}.".encode() + body, hashlib.sha256).hexdigest()
+    return hmac.compare_digest(expected, v1)

socialsforai/integrations/__init__.py

@@ -0,0 +1,2 @@
+"""Adapters that turn socialsforai.tools into tools for agent frameworks. Each imports its framework
+only when used, so installing socialsforai never pulls them in."""

socialsforai/integrations/_common.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+import json
+from typing import Any, Iterable
+
+from .._client import SocialsForAI
+from ..tools import TOOLS
+
+
+def pick(names: Iterable[str] | None, include_destructive: bool) -> list[dict[str, Any]]:
+    """The tool specs to expose: all, or the named ones. Destructive tools (delete_post) need opting in."""
+    wanted = set(names) if names is not None else None
+    out = [t for t in TOOLS if (wanted is None or t["name"] in wanted) and (include_destructive or not t.get("destructive") or (wanted is not None and t["name"] in wanted))]
+    if wanted is not None:
+        missing = wanted - {t["name"] for t in TOOLS}
+        if missing:
+            raise ValueError(f"Unknown tools: {', '.join(sorted(missing))}. Available: {', '.join(t['name'] for t in TOOLS)}.")
+    return out
+
+
+def client_or_default(client: SocialsForAI | None) -> SocialsForAI:
+    return client or SocialsForAI()
+
+
+def as_text(result: dict[str, Any]) -> str:
+    return json.dumps(result, ensure_ascii=False)

socialsforai/integrations/crewai.py

@@ -0,0 +1,48 @@
+"""CrewAI tools.
+
+    from socialsforai.integrations.crewai import socials_tools
+    agent = Agent(role="Social media manager", tools=socials_tools(), ...)
+"""
+
+from __future__ import annotations
+
+from typing import Any, Iterable
+
+from .._client import SocialsForAI
+from ..tools import run_tool
+from ._common import as_text, client_or_default, pick
+
+
+def _model_for(spec: dict[str, Any]):
+    """A pydantic model for the tool's input (CrewAI validates arguments with it)."""
+    from pydantic import ConfigDict, Field, create_model
+
+    types = {"string": str, "integer": int, "boolean": bool, "array": list, "object": dict}
+    props = spec["input"].get("properties", {})
+    required = set(spec["input"].get("required", []))
+    fields = {}
+    for name, p in props.items():
+        t = types.get(p.get("type"), Any)
+        fields[name] = (t, Field(... if name in required else None, description=p.get("description", "")))
+    return create_model(f"{spec['name']}_input", __config__=ConfigDict(extra="allow"), **fields)
+
+
+def socials_tools(client: SocialsForAI | None = None, *, tools: Iterable[str] | None = None, include_destructive: bool = False) -> list:
+    try:
+        from crewai.tools import BaseTool
+    except ImportError as e:  # pragma: no cover
+        raise ImportError("Install CrewAI first: pip install crewai") from e
+    c = client_or_default(client)
+    out = []
+    for spec in pick(tools, include_destructive):
+
+        class SocialsTool(BaseTool):
+            name: str = spec["name"]
+            description: str = spec["description"]
+            args_schema: type = _model_for(spec)
+
+            def _run(self, **kwargs) -> str:
+                return as_text(run_tool(c, self.name, {k: v for k, v in kwargs.items() if v is not None}))
+
+        out.append(SocialsTool())
+    return out

socialsforai/integrations/langchain.py

@@ -0,0 +1,30 @@
+"""LangChain tools (also usable from LangGraph).
+
+    from socialsforai.integrations.langchain import socials_tools
+    tools = socials_tools()            # reads SOCIALSFORAI_API_KEY
+    agent = create_react_agent(model, tools)
+"""
+
+from __future__ import annotations
+
+from typing import Iterable
+
+from .._client import SocialsForAI
+from ..tools import run_tool
+from ._common import as_text, client_or_default, pick
+
+
+def socials_tools(client: SocialsForAI | None = None, *, tools: Iterable[str] | None = None, include_destructive: bool = False) -> list:
+    try:
+        from langchain_core.tools import StructuredTool
+    except ImportError as e:  # pragma: no cover
+        raise ImportError("Install LangChain first: pip install langchain-core") from e
+    c = client_or_default(client)
+    out = []
+    for spec in pick(tools, include_destructive):
+
+        def call(_name: str = spec["name"], **kwargs) -> str:
+            return as_text(run_tool(c, _name, kwargs))
+
+        out.append(StructuredTool.from_function(func=call, name=spec["name"], description=spec["description"], args_schema=spec["input"]))
+    return out

socialsforai/integrations/openai_agents.py

@@ -0,0 +1,35 @@
+"""Tools for the OpenAI Agents SDK.
+
+    from agents import Agent
+    from socialsforai.integrations.openai_agents import socials_tools
+    agent = Agent(name="Social media", tools=socials_tools())
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Iterable
+
+from .._client import SocialsForAI
+from ..tools import run_tool
+from ._common import as_text, client_or_default, pick
+
+
+def socials_tools(client: SocialsForAI | None = None, *, tools: Iterable[str] | None = None, include_destructive: bool = False) -> list:
+    try:
+        from agents import FunctionTool
+    except ImportError as e:  # pragma: no cover
+        raise ImportError("Install the OpenAI Agents SDK first: pip install openai-agents") from e
+    c = client_or_default(client)
+    out = []
+    for spec in pick(tools, include_destructive):
+
+        async def invoke(_ctx, raw: str, _name: str = spec["name"]) -> str:
+            import asyncio
+
+            args = json.loads(raw or "{}")
+            return as_text(await asyncio.to_thread(run_tool, c, _name, args))
+
+        # Our schemas have optional fields, so strict mode (which requires every field) is off.
+        out.append(FunctionTool(name=spec["name"], description=spec["description"], params_json_schema=spec["input"], on_invoke_tool=invoke, strict_json_schema=False))
+    return out

socialsforai/tools.json

@@ -0,0 +1,566 @@
+{
+  "version": 1,
+  "tools": [
+    {
+      "name": "list_accounts",
+      "description": "List the social accounts connected to this workspace. Use their ids in create_post. If the one you need is missing, call create_connect_link.",
+      "request": {
+        "method": "GET",
+        "path": "/v1/accounts",
+        "query": [
+          "platform"
+        ]
+      },
+      "input": {
+        "type": "object",
+        "properties": {
+          "platform": {
+            "type": "string",
+            "description": "Only accounts on this network, e.g. \"x\"."
+          }
+        }
+      },
+      "readOnly": true
+    },
+    {
+      "name": "list_platforms",
+      "description": "Which networks are available and what each supports: character and media limits, threads, polls, delete, metrics.",
+      "request": {
+        "method": "GET",
+        "path": "/v1/platforms"
+      },
+      "input": {
+        "type": "object",
+        "properties": {}
+      },
+      "readOnly": true
+    },
+    {
+      "name": "create_connect_link",
+      "description": "Create a link the account owner opens to connect social accounts (they approve on the network's own page). Give them the url, then check list_accounts.",
+      "request": {
+        "method": "POST",
+        "path": "/v1/connect-links",
+        "body": [
+          "platforms",
+          "external_ref"
+        ]
+      },
+      "input": {
+        "type": "object",
+        "properties": {
+          "platforms": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Networks to offer, e.g. [\"x\", \"linkedin\"]. Omit for all."
+          },
+          "external_ref": {
+            "type": "string",
+            "description": "Your label for whose accounts these are."
+          }
+        }
+      }
+    },
+    {
+      "name": "create_post",
+      "description": "Publish or schedule a post to one or more accounts and get one result per account. Run it with dry_run: true first and show the person the text per network. Every error includes a fix: act on it. Reuse idempotency_key when retrying.",
+      "request": {
+        "method": "POST",
+        "path": "/v1/posts",
+        "body": "*",
+        "defaults": {
+          "wait": true
+        },
+        "idempotency": true
+      },
+      "input": {
+        "type": "object",
+        "properties": {
+          "accounts": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Account ids (acc_...) from list_accounts, or a network name like \"linkedin\" when there is exactly one account on it."
+          },
+          "text": {
+            "type": "string",
+            "description": "The post's text."
+          },
+          "media": {
+            "type": "array",
+            "description": "Images, videos or a document, by public URL. The URL must be the file itself, not a share page.",
+            "items": {
+              "type": "object",
+              "properties": {
+                "url": {
+                  "type": "string",
+                  "description": "Public URL of the file."
+                },
+                "type": {
+                  "type": "string",
+                  "enum": [
+                    "image",
+                    "video",
+                    "document"
+                  ]
+                },
+                "alt": {
+                  "type": "string",
+                  "description": "Alt text."
+                }
+              },
+              "required": [
+                "url"
+              ]
+            }
+          },
+          "link": {
+            "type": "object",
+            "description": "Share a URL as a preview card.",
+            "properties": {
+              "url": {
+                "type": "string",
+                "description": "The page to link to."
+              }
+            },
+            "required": [
+              "url"
+            ]
+          },
+          "thread": {
+            "type": "array",
+            "description": "Follow-up posts, each a reply to the one before (X, Bluesky, Mastodon, Telegram, Nostr).",
+            "items": {
+              "type": "object",
+              "properties": {
+                "text": {
+                  "type": "string"
+                }
+              },
+              "required": [
+                "text"
+              ]
+            }
+          },
+          "auto_thread": {
+            "type": "boolean",
+            "description": "Split text that is over a network's limit into a thread there instead of failing."
+          },
+          "scheduled_at": {
+            "type": "string",
+            "description": "When to publish: ISO-8601 with an offset, a local time together with timezone, or \"best\" for the hour that has worked best. Omit to publish now."
+          },
+          "timezone": {
+            "type": "string",
+            "description": "IANA time zone for a local scheduled_at, e.g. \"America/New_York\"."
+          },
+          "repeat": {
+            "type": "object",
+            "description": "Repeat the post: count posts, every day, week or month, at the same local time.",
+            "properties": {
+              "every": {
+                "type": "string",
+                "enum": [
+                  "day",
+                  "week",
+                  "month"
+                ]
+              },
+              "count": {
+                "type": "integer",
+                "minimum": 2,
+                "maximum": 52
+              },
+              "interval": {
+                "type": "integer",
+                "minimum": 1
+              }
+            },
+            "required": [
+              "every",
+              "count"
+            ]
+          },
+          "reply_to": {
+            "type": "string",
+            "description": "A post id (post_...) to reply to, on the same accounts."
+          },
+          "reply_to_comment": {
+            "type": "string",
+            "description": "With reply_to: the id of someone's reply under that post (from list_replies), to answer them. One account only."
+          },
+          "first_comment": {
+            "type": "string",
+            "description": "Posted as a comment right after the post (LinkedIn), e.g. to hold a link."
+          },
+          "platform_options": {
+            "type": "object",
+            "description": "Per-network settings, e.g. {\"x\": {\"text\": \"shorter version\"}, \"reddit\": {\"subreddit\": \"test\"}}. See https://socialsforai.com/llms.txt."
+          },
+          "approval": {
+            "type": "string",
+            "enum": [
+              "required"
+            ],
+            "description": "Hold the post until a person approves it at approval.url."
+          },
+          "dry_run": {
+            "type": "boolean",
+            "description": "Check everything without publishing. Returns ok, issues (each with a fix) and the exact text per network."
+          },
+          "idempotency_key": {
+            "type": "string",
+            "description": "Send the same key when retrying the same post, so it is never published twice."
+          }
+        },
+        "required": [
+          "accounts"
+        ]
+      }
+    },
+    {
+      "name": "create_posts",
+      "description": "Create up to 50 posts in one call, such as a week or month of scheduled content. Each is checked and created by itself; results come back per item.",
+      "request": {
+        "method": "POST",
+        "path": "/v1/posts/batch",
+        "body": "*",
+        "idempotency": true
+      },
+      "input": {
+        "type": "object",
+        "properties": {
+          "posts": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "accounts": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  },
+                  "description": "Account ids (acc_...) from list_accounts, or a network name like \"linkedin\" when there is exactly one account on it."
+                },
+                "text": {
+                  "type": "string",
+                  "description": "The post's text."
+                },
+                "media": {
+                  "type": "array",
+                  "description": "Images, videos or a document, by public URL. The URL must be the file itself, not a share page.",
+                  "items": {
+                    "type": "object",
+                    "properties": {
+                      "url": {
+                        "type": "string",
+                        "description": "Public URL of the file."
+                      },
+                      "type": {
+                        "type": "string",
+                        "enum": [
+                          "image",
+                          "video",
+                          "document"
+                        ]
+                      },
+                      "alt": {
+                        "type": "string",
+                        "description": "Alt text."
+                      }
+                    },
+                    "required": [
+                      "url"
+                    ]
+                  }
+                },
+                "link": {
+                  "type": "object",
+                  "description": "Share a URL as a preview card.",
+                  "properties": {
+                    "url": {
+                      "type": "string",
+                      "description": "The page to link to."
+                    }
+                  },
+                  "required": [
+                    "url"
+                  ]
+                },
+                "thread": {
+                  "type": "array",
+                  "description": "Follow-up posts, each a reply to the one before (X, Bluesky, Mastodon, Telegram, Nostr).",
+                  "items": {
+                    "type": "object",
+                    "properties": {
+                      "text": {
+                        "type": "string"
+                      }
+                    },
+                    "required": [
+                      "text"
+                    ]
+                  }
+                },
+                "auto_thread": {
+                  "type": "boolean",
+                  "description": "Split text that is over a network's limit into a thread there instead of failing."
+                },
+                "scheduled_at": {
+                  "type": "string",
+                  "description": "When to publish: ISO-8601 with an offset, a local time together with timezone, or \"best\" for the hour that has worked best. Omit to publish now."
+                },
+                "timezone": {
+                  "type": "string",
+                  "description": "IANA time zone for a local scheduled_at, e.g. \"America/New_York\"."
+                },
+                "repeat": {
+                  "type": "object",
+                  "description": "Repeat the post: count posts, every day, week or month, at the same local time.",
+                  "properties": {
+                    "every": {
+                      "type": "string",
+                      "enum": [
+                        "day",
+                        "week",
+                        "month"
+                      ]
+                    },
+                    "count": {
+                      "type": "integer",
+                      "minimum": 2,
+                      "maximum": 52
+                    },
+                    "interval": {
+                      "type": "integer",
+                      "minimum": 1
+                    }
+                  },
+                  "required": [
+                    "every",
+                    "count"
+                  ]
+                },
+                "reply_to": {
+                  "type": "string",
+                  "description": "A post id (post_...) to reply to, on the same accounts."
+                },
+                "reply_to_comment": {
+                  "type": "string",
+                  "description": "With reply_to: the id of someone's reply under that post (from list_replies), to answer them. One account only."
+                },
+                "first_comment": {
+                  "type": "string",
+                  "description": "Posted as a comment right after the post (LinkedIn), e.g. to hold a link."
+                },
+                "platform_options": {
+                  "type": "object",
+                  "description": "Per-network settings, e.g. {\"x\": {\"text\": \"shorter version\"}, \"reddit\": {\"subreddit\": \"test\"}}. See https://socialsforai.com/llms.txt."
+                },
+                "approval": {
+                  "type": "string",
+                  "enum": [
+                    "required"
+                  ],
+                  "description": "Hold the post until a person approves it at approval.url."
+                },
+                "dry_run": {
+                  "type": "boolean",
+                  "description": "Check everything without publishing. Returns ok, issues (each with a fix) and the exact text per network."
+                },
+                "idempotency_key": {
+                  "type": "string",
+                  "description": "Send the same key when retrying the same post, so it is never published twice."
+                }
+              },
+              "required": [
+                "accounts"
+              ]
+            },
+            "minItems": 1,
+            "maxItems": 50
+          },
+          "dry_run": {
+            "type": "boolean",
+            "description": "Check everything without publishing. Returns ok, issues (each with a fix) and the exact text per network."
+          }
+        },
+        "required": [
+          "posts"
+        ]
+      }
+    },
+    {
+      "name": "get_post",
+      "description": "A post's status and, per account, its link or error with a fix.",
+      "request": {
+        "method": "GET",
+        "path": "/v1/posts/{id}"
+      },
+      "input": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "The post id (post_...)."
+          }
+        },
+        "required": [
+          "id"
+        ]
+      },
+      "readOnly": true
+    },
+    {
+      "name": "list_posts",
+      "description": "Recent posts, newest first. Filter by status, e.g. scheduled or failed.",
+      "request": {
+        "method": "GET",
+        "path": "/v1/posts",
+        "query": [
+          "status",
+          "limit"
+        ]
+      },
+      "input": {
+        "type": "object",
+        "properties": {
+          "status": {
+            "type": "string",
+            "enum": [
+              "pending_approval",
+              "scheduled",
+              "publishing",
+              "published",
+              "partially_published",
+              "failed",
+              "canceled",
+              "deleted"
+            ]
+          },
+          "limit": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 100
+          }
+        }
+      },
+      "readOnly": true
+    },
+    {
+      "name": "delete_post",
+      "description": "Delete a post everywhere it went out, or cancel it if it hasn't. Permanent: confirm with the person first. series: true also cancels the rest of a repeat series.",
+      "request": {
+        "method": "DELETE",
+        "path": "/v1/posts/{id}",
+        "query": [
+          "accounts",
+          "series"
+        ]
+      },
+      "input": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "The post id."
+          },
+          "accounts": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Only delete it from these accounts."
+          },
+          "series": {
+            "type": "boolean"
+          }
+        },
+        "required": [
+          "id"
+        ]
+      },
+      "destructive": true
+    },
+    {
+      "name": "get_post_metrics",
+      "description": "Likes, reposts, replies, views and more for each published copy of a post, plus totals. Cached 15 minutes; X bills per read, so don't poll it in a loop.",
+      "request": {
+        "method": "GET",
+        "path": "/v1/posts/{id}/metrics"
+      },
+      "input": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "The post id."
+          }
+        },
+        "required": [
+          "id"
+        ]
+      },
+      "readOnly": true
+    },
+    {
+      "name": "list_replies",
+      "description": "What people replied under each published copy of a post. Answer one with create_post (one account, reply_to, reply_to_comment). Show the person your answer first.",
+      "request": {
+        "method": "GET",
+        "path": "/v1/posts/{id}/replies"
+      },
+      "input": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "The post id."
+          }
+        },
+        "required": [
+          "id"
+        ]
+      },
+      "readOnly": true
+    },
+    {
+      "name": "list_events",
+      "description": "What happened since you last looked: posts that failed, approvals, accounts needing reconnection. Pass the last_id from the previous call as after.",
+      "request": {
+        "method": "GET",
+        "path": "/v1/events",
+        "query": [
+          "after",
+          "types",
+          "limit"
+        ]
+      },
+      "input": {
+        "type": "object",
+        "properties": {
+          "after": {
+            "type": "string",
+            "description": "An event id (evt_...)."
+          },
+          "types": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Only these event types."
+          },
+          "limit": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 200
+          }
+        }
+      },
+      "readOnly": true
+    }
+  ]
+}

socialsforai/tools.py

@@ -0,0 +1,56 @@
+"""Agent tools, independent of any framework: the definitions (name, description, JSON Schema) and
+one function that runs them. The framework adapters in socialsforai.integrations wrap these.
+
+    from socialsforai import SocialsForAI
+    from socialsforai.tools import TOOLS, run_tool
+    result = run_tool(SocialsForAI(), "create_post", {"accounts": ["linkedin"], "text": "Hi", "dry_run": True})
+
+Errors come back as {"error": {"code", "message", "fix", ...}} instead of being raised, so the model
+can read the fix and act on it.
+"""
+
+from __future__ import annotations
+
+import json
+import uuid
+from importlib import resources
+from typing import Any
+
+from ._client import SocialsError, SocialsForAI, _query, _quote
+
+_SPEC = json.loads(resources.files(__package__).joinpath("tools.json").read_text())
+#: Every tool: {"name", "description", "input" (JSON Schema), "request", "readOnly"?, "destructive"?}.
+TOOLS: list[dict[str, Any]] = _SPEC["tools"]
+_BY_NAME = {t["name"]: t for t in TOOLS}
+
+
+def tool_names(read_only: bool = False, include_destructive: bool = True) -> list[str]:
+    return [t["name"] for t in TOOLS if (not read_only or t.get("readOnly")) and (include_destructive or not t.get("destructive"))]
+
+
+def run_tool(client: SocialsForAI, name: str, args: dict[str, Any] | None = None) -> dict[str, Any]:
+    """Run one tool with the model's arguments and return the API's JSON (or its error)."""
+    spec = _BY_NAME.get(name)
+    if not spec:
+        return {"error": {"code": "unknown_tool", "message": f"No tool named {name}."}}
+    args = dict(args or {})
+    req = spec["request"]
+    path = req["path"]
+    for key in [k[1:-1] for k in path.split("/") if k.startswith("{")]:
+        if key not in args:
+            return {"error": {"code": "missing_argument", "message": f"{name} needs {key}."}}
+        path = path.replace("{" + key + "}", _quote(args.pop(key)))
+    query = {k: args.pop(k) for k in req.get("query", []) if k in args}
+    body: Any = None
+    if req.get("body") == "*":
+        body = {**req.get("defaults", {}), **args}
+    elif req.get("body"):
+        body = {k: args[k] for k in req["body"] if k in args}
+    headers = None
+    if req.get("idempotency") and not (body or {}).get("dry_run"):
+        headers = {"Idempotency-Key": (body or {}).pop("idempotency_key", None) or str(uuid.uuid4())}
+    try:
+        out = client.request(req["method"], path + _query(query), body=body, headers=headers, auth=name != "list_platforms")
+        return out if isinstance(out, dict) else {"result": out}
+    except SocialsError as e:
+        return e.to_dict()

socialsforai-0.1.0.dist-info/METADATA

@@ -0,0 +1,111 @@
+Metadata-Version: 2.5
+Name: socialsforai
+Version: 0.1.0
+Summary: Python client and agent tools for SocialsForAI: post to X, LinkedIn, Bluesky, Mastodon, Telegram, Discord and more from code or AI agents.
+Project-URL: Homepage, https://socialsforai.com
+Project-URL: Documentation, https://socialsforai.com/docs
+Project-URL: Source, https://github.com/SocialsForAi/socialsforai
+Author-email: Codehorts LLC <lee@socialsforai.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agents,bluesky,crewai,langchain,linkedin,mcp,openai-agents,social-media,social-media-api,twitter
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Internet
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Provides-Extra: crewai
+Requires-Dist: crewai>=0.80; extra == 'crewai'
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.3; extra == 'langchain'
+Provides-Extra: openai-agents
+Requires-Dist: openai-agents>=0.1; extra == 'openai-agents'
+Description-Content-Type: text/markdown
+
+# socialsforai
+
+Python client and agent tools for [SocialsForAI](https://socialsforai.com): one API to publish, schedule and measure posts on X, LinkedIn, Bluesky, Mastodon, Telegram, Discord, Slack, Nostr and more, built for AI agents.
+
+- No dependencies. Python 3.9+.
+- Safe retries: rate limits, server errors and network errors are retried, and every post gets an idempotency key, so a retry never publishes twice.
+- Every error has a stable `code` and a `fix` that says what to do next.
+- Ready-made tools for LangChain, CrewAI and the OpenAI Agents SDK.
+
+```bash
+pip install socialsforai
+```
+
+## Quickstart
+
+```python
+from socialsforai import SocialsForAI
+
+socials = SocialsForAI()  # reads SOCIALSFORAI_API_KEY
+
+# No key yet? An agent can sign itself up:
+# socials.workspaces.create(name="My agent", email="owner@example.com")
+
+# Connect accounts: send this link to the account owner.
+link = socials.connect_links.create(platforms=["x", "linkedin", "bluesky"])
+print(link["url"])
+socials.connect_links.wait_for(link["id"])
+
+# Check, then publish. One result per account.
+check = socials.posts.create(["linkedin", "bluesky"], "We just shipped webhooks.", dry_run=True)
+print(check["ok"], check["issues"])
+post = socials.posts.create(["linkedin", "bluesky"], "We just shipped webhooks.", wait=True)
+for t in post["targets"]:
+    print(t["platform"], t["status"], t["url"])
+```
+
+Any API field works as a keyword on `posts.create`: `media`, `link`, `thread`, `auto_thread=True` (split long text into a thread), `scheduled_at="best"`, `timezone`, `repeat={"every": "week", "count": 4}`, `approval="required"`, `platform_options`, `reply_to` and `reply_to_comment`. The full list is in the [agent guide](https://socialsforai.com/llms.txt).
+
+| Group | Methods |
+| --- | --- |
+| Posts | `posts.create`, `posts.create_many` (up to 50), `posts.list`, `posts.get`, `posts.update`, `posts.delete`, `posts.metrics`, `posts.replies`, `posts.wait_for_approval` |
+| Accounts | `accounts.list`, `accounts.get`, `accounts.connect`, `accounts.disconnect`, `connect_links.create`, `connect_links.get`, `connect_links.wait_for` |
+| Media | `media.upload` (≤4 MB), `media.upload_file` (any size) |
+| Events | `events.list` (what happened since an event id; for when you can't receive webhooks) |
+| Workspace | `workspaces.create`, `workspace.get`, `workspace.set_owner_email`, `usage()`, `analytics()`, `platforms()`, `health()`, `upgrade_link(plan)` |
+| Admin | `keys.list/create/revoke`, `webhooks.list/create/delete`, `verify_webhook(secret, header, raw_body)` |
+
+## Agent tools
+
+The same tools work in each framework: `list_accounts`, `list_platforms`, `create_connect_link`, `create_post`, `create_posts`, `get_post`, `list_posts`, `get_post_metrics`, `list_replies`, `list_events`, and `delete_post`. `delete_post` is off unless you pass `include_destructive=True`. Errors come back to the model as `{"error": {"code", "message", "fix"}}` so it can act on the fix.
+
+**LangChain / LangGraph** (`pip install "socialsforai[langchain]"`)
+
+```python
+from langgraph.prebuilt import create_react_agent
+from socialsforai.integrations.langchain import socials_tools
+
+agent = create_react_agent(model, socials_tools())
+```
+
+**CrewAI** (`pip install "socialsforai[crewai]"`)
+
+```python
+from crewai import Agent
+from socialsforai.integrations.crewai import socials_tools
+
+manager = Agent(role="Social media manager", goal="Publish our launch", backstory="...", tools=socials_tools())
+```
+
+**OpenAI Agents SDK** (`pip install "socialsforai[openai-agents]"`)
+
+```python
+from agents import Agent
+from socialsforai.integrations.openai_agents import socials_tools
+
+agent = Agent(name="Social media", instructions="Dry-run before publishing.", tools=socials_tools())
+```
+
+**Anything else:** `socialsforai.tools.TOOLS` has each tool's name, description and JSON Schema, and `run_tool(client, name, args)` runs one.
+
+Limit what an agent can do with `socials_tools(tools=["list_accounts", "create_post"])`, or give it a scoped key: `socials.keys.create(name="drafts", scopes=["posts:write"], require_approval=True)`.
+
+## Links
+
+- Docs: https://socialsforai.com/docs
+- MCP server: https://socialsforai.com/api/mcp
+- JavaScript SDK: `npm install @socialsforai/sdk`

socialsforai-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+socialsforai/__init__.py,sha256=8gdX4MBfhMkMKirF86NICP7sDAqWwijVVOmgSOPV0wA,583
+socialsforai/_client.py,sha256=n-rfPfyIXdKb5ERFiBsaXS4X6o8tl72lld2hACXxuK4,16539
+socialsforai/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+socialsforai/tools.json,sha256=NVd4XYQMklPTz5yrz1yF2GL1cJ7hhbA79WmfR4pJ_GM,18138
+socialsforai/tools.py,sha256=uWUZqyFsDIHryuXn1P6u0Mo0d7qY-pxBrNQznJtuigU,2589
+socialsforai/integrations/__init__.py,sha256=wSJTGYcX7grhGLzIjNCdUNbhKR8VagWhcFECb6clMrM,168
+socialsforai/integrations/_common.py,sha256=6A36vkajfUnADYJoGw6_3rJTCG7cGtd2J3Lb4A02NSE,1018
+socialsforai/integrations/crewai.py,sha256=Y8lzqmmOIT_RCGJCbFtr3lsazMDojNaF_mibZOKVQz8,1814
+socialsforai/integrations/langchain.py,sha256=BmO3n_dfII4SrkqysoWzrY-GPERubPTukAmv1PJLdn8,1128
+socialsforai/integrations/openai_agents.py,sha256=jC-nMiktnRdTvuTAppo1SuuMMLUbp3l9IBKO1gm-8hw,1337
+socialsforai-0.1.0.dist-info/METADATA,sha256=UbjlLLyoF88RDgwxiwqRWCYMuF8COvC7CGnzKigeUIY,5275
+socialsforai-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+socialsforai-0.1.0.dist-info/licenses/LICENSE,sha256=ssGiy7YfLrCObMMi-0DFnJU4Fqn0zYU4VKN7K9xCqas,1070
+socialsforai-0.1.0.dist-info/RECORD,,

socialsforai-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

socialsforai-0.1.0.dist-info/licenses/LICENSE

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