fopost 0.1.0__py3-none-any.whl

fopost/__init__.py

@@ -0,0 +1,87 @@
+"""fopost — official Python SDK for the FoPost API.
+
+Quick start::
+
+    from fopost import Fopost
+
+    client = Fopost(api_key="osk_...")
+
+    accounts = client.accounts.list(workspace_id="9b2f6c1e-...")
+    post = client.posts.create(
+        workspace_id="9b2f6c1e-...",
+        content="Hello from Python",
+        accounts=[a.id for a in accounts],
+    )
+    client.posts.publish(post.id)
+"""
+
+from ._http import DEFAULT_BASE_URL
+from .client import Fopost
+from .errors import (
+    AuthenticationError,
+    NotFoundError,
+    FopostError,
+    PaymentRequiredError,
+    PermissionDeniedError,
+    RateLimitError,
+)
+from .models import (
+    PLATFORMS,
+    POST_STATUSES,
+    AiCreditBalance,
+    AiCredits,
+    CaptionResult,
+    ContentBlock,
+    Delivery,
+    Label,
+    MediaItem,
+    Page,
+    PageMeta,
+    Platform,
+    Post,
+    PostAccount,
+    PostStatus,
+    RepurposeResult,
+    RewriteResult,
+    RewriteVariant,
+    SocialAccount,
+    Workspace,
+)
+
+__version__ = "0.1.0"
+
+#: Alias for people arriving from the TypeScript SDK, where the class is `FoPost`.
+FoPost = Fopost
+
+__all__ = [
+    "DEFAULT_BASE_URL",
+    "PLATFORMS",
+    "POST_STATUSES",
+    "AiCreditBalance",
+    "AiCredits",
+    "AuthenticationError",
+    "CaptionResult",
+    "ContentBlock",
+    "Delivery",
+    "Label",
+    "MediaItem",
+    "NotFoundError",
+    "FoPost",
+    "Fopost",
+    "FopostError",
+    "Page",
+    "PageMeta",
+    "PaymentRequiredError",
+    "PermissionDeniedError",
+    "Platform",
+    "Post",
+    "PostAccount",
+    "PostStatus",
+    "RateLimitError",
+    "RepurposeResult",
+    "RewriteResult",
+    "RewriteVariant",
+    "SocialAccount",
+    "Workspace",
+    "__version__",
+]

fopost/_http.py

@@ -0,0 +1,185 @@
+"""Internal HTTP transport: auth headers, JSON coding, envelope unwrap, retries."""
+
+from __future__ import annotations
+
+import time
+from email.utils import parsedate_to_datetime
+from typing import Any
+from urllib.parse import urlsplit
+
+import httpx
+
+from .errors import FopostError, RateLimitError, error_from_response
+
+DEFAULT_BASE_URL = "https://api.fopost.com/api/v1"
+DEFAULT_TIMEOUT = 30.0
+DEFAULT_MAX_RETRIES = 3
+MAX_RETRY_WAIT = 60.0
+
+USER_AGENT = "fopost-python"
+
+# Indirected so tests can replace the wait without touching the real clock.
+_sleep = time.sleep
+
+
+def _retry_after_seconds(response: httpx.Response) -> float | None:
+    """Parse Retry-After, which is either delta-seconds or an HTTP date."""
+    raw = response.headers.get("retry-after")
+    if not raw:
+        return None
+    raw = raw.strip()
+    try:
+        return max(0.0, float(raw))
+    except ValueError:
+        pass
+    try:
+        target = parsedate_to_datetime(raw)
+    except (TypeError, ValueError):
+        return None
+    if target is None:
+        return None
+    delta = target.timestamp() - time.time()
+    return max(0.0, delta)
+
+
+class HttpClient:
+    """Thin httpx wrapper. One per ``Fopost`` instance."""
+
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float | httpx.Timeout = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        client: httpx.Client | None = None,
+    ) -> None:
+        if not api_key:
+            raise ValueError("fopost: api_key is required")
+        if max_retries < 1:
+            raise ValueError("fopost: max_retries must be at least 1")
+
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.max_retries = max_retries
+        self._owns_client = client is None
+        self._client = client or httpx.Client(timeout=timeout)
+
+    @property
+    def headers(self) -> dict[str, str]:
+        return {
+            "Accept": "application/json",
+            "Content-Type": "application/json",
+            "X-API-Key": self.api_key,
+            "User-Agent": USER_AGENT,
+        }
+
+    def _url(self, path: str) -> str:
+        if urlsplit(path).scheme:
+            return path
+        return f"{self.base_url}/{path.lstrip('/')}"
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Any | None = None,
+        params: dict[str, Any] | None = None,
+    ) -> Any:
+        """Send a request, retrying on 429, and return the decoded body."""
+        clean_params = {k: v for k, v in params.items() if v is not None} if params else None
+
+        attempt = 0
+        while True:
+            attempt += 1
+            response = self._client.request(
+                method,
+                self._url(path),
+                json=json,
+                params=clean_params,
+                headers=self.headers,
+            )
+
+            if response.status_code == 429 and attempt < self.max_retries:
+                wait = _retry_after_seconds(response)
+                _sleep(min(wait if wait is not None else 1.0, MAX_RETRY_WAIT))
+                continue
+
+            return self._decode(response)
+
+    def _decode(self, response: httpx.Response) -> Any:
+        body: Any
+        if response.status_code == 204 or not response.content:
+            body = None
+        else:
+            try:
+                body = response.json()
+            except ValueError:
+                body = response.text
+
+        if response.is_success:
+            if isinstance(body, str):
+                content_type = response.headers.get("content-type", "")
+                raise FopostError(
+                    f"Expected a JSON response, got {content_type or 'no content type'}",
+                    status=response.status_code,
+                    body=body,
+                )
+            return body
+
+        if response.status_code == 429:
+            raise RateLimitError(
+                _message_of(body, response.status_code),
+                status=429,
+                code=_code_of(body),
+                body=body,
+                retry_after=_retry_after_seconds(response),
+            )
+        raise error_from_response(response.status_code, body)
+
+    def get(self, path: str, params: dict[str, Any] | None = None) -> Any:
+        return self.request("GET", path, params=params)
+
+    def post(self, path: str, json: Any | None = None) -> Any:
+        return self.request("POST", path, json=json)
+
+    def put(self, path: str, json: Any | None = None) -> Any:
+        return self.request("PUT", path, json=json)
+
+    def delete(self, path: str, json: Any | None = None) -> Any:
+        return self.request("DELETE", path, json=json)
+
+    def close(self) -> None:
+        if self._owns_client:
+            self._client.close()
+
+
+def _message_of(body: Any, status: int) -> str:
+    if isinstance(body, dict):
+        message = body.get("message")
+        if isinstance(message, str) and message:
+            return message
+        error = body.get("error")
+        if isinstance(error, str) and error:
+            return error
+    return f"HTTP {status}"
+
+
+def _code_of(body: Any) -> str | None:
+    if isinstance(body, dict):
+        error = body.get("error")
+        if isinstance(error, str):
+            return error
+    return None
+
+
+def unwrap(body: Any) -> Any:
+    """Peel the ``{"data": ...}`` envelope the API wraps most responses in.
+
+    Some endpoints (``POST /posts``, ``GET /posts/{id}``) return the resource
+    bare, so the envelope is unwrapped only when it is actually there.
+    """
+    if isinstance(body, dict) and "data" in body:
+        return body["data"]
+    return body

fopost/client.py

@@ -0,0 +1,94 @@
+"""The ``Fopost`` client."""
+
+from __future__ import annotations
+
+import os
+from types import TracebackType
+from typing import Any
+
+import httpx
+
+from ._http import DEFAULT_BASE_URL, DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT, HttpClient
+from .resources import (
+    AccountsResource,
+    AiResource,
+    LabelsResource,
+    PostsResource,
+    WorkspacesResource,
+)
+
+__all__ = ["Fopost"]
+
+
+class Fopost:
+    """Client for the FoPost API.
+
+    ::
+
+        from fopost import Fopost
+
+        client = Fopost(api_key="osk_...")
+        accounts = client.accounts.list(workspace_id="9b2f6c1e-...")
+
+    The key falls back to the ``FOPOST_API_KEY`` environment variable.
+    Requests that come back 429 are retried up to ``max_retries`` attempts,
+    waiting for the interval the API asks for in ``Retry-After``.
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float | httpx.Timeout = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        key = api_key or os.environ.get("FOPOST_API_KEY")
+        if not key:
+            raise ValueError(
+                "fopost: an api_key is required — pass api_key=... or set FOPOST_API_KEY"
+            )
+
+        self._http = HttpClient(
+            api_key=key,
+            base_url=base_url,
+            timeout=timeout,
+            max_retries=max_retries,
+            client=http_client,
+        )
+
+        self.posts = PostsResource(self._http)
+        self.accounts = AccountsResource(self._http)
+        self.workspaces = WorkspacesResource(self._http)
+        self.labels = LabelsResource(self._http)
+        self.ai = AiResource(self._http)
+
+    @property
+    def base_url(self) -> str:
+        return self._http.base_url
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Any | None = None,
+        params: dict[str, Any] | None = None,
+    ) -> Any:
+        """Call an endpoint the SDK does not wrap yet. Returns the decoded body."""
+        return self._http.request(method, path, json=json, params=params)
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> Fopost:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        self.close()

fopost/errors.py

@@ -0,0 +1,122 @@
+"""Exceptions raised by the SDK.
+
+Every non-2xx response becomes an ``FopostError``. The API answers with an
+``{"error": "<code>", "message": "<human readable>"}`` envelope, which maps onto
+the ``code`` and ``message`` attributes.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+__all__ = [
+    "FopostError",
+    "AuthenticationError",
+    "PaymentRequiredError",
+    "PermissionDeniedError",
+    "NotFoundError",
+    "RateLimitError",
+    "error_from_response",
+]
+
+
+class FopostError(Exception):
+    """Base class for every error returned by the FoPost API."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status: int,
+        code: str | None = None,
+        body: Any = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status = status
+        self.code = code
+        self.body = body
+
+    def __str__(self) -> str:
+        suffix = f" ({self.code})" if self.code else ""
+        return f"[{self.status}{suffix}] {self.message}"
+
+
+class AuthenticationError(FopostError):
+    """401 — missing, invalid, or expired API key."""
+
+
+class PaymentRequiredError(FopostError):
+    """402 — no active subscription, or AI credits exhausted.
+
+    ``upgrade_url`` carries the path the API suggests sending the user to.
+    """
+
+    @property
+    def upgrade_url(self) -> str | None:
+        if isinstance(self.body, dict):
+            value = self.body.get("upgrade_url")
+            if isinstance(value, str):
+                return value
+        return None
+
+
+class PermissionDeniedError(FopostError):
+    """403 — the key is valid but lacks the scope or workspace access."""
+
+
+class NotFoundError(FopostError):
+    """404 — no such resource, or it is outside the key's reach."""
+
+
+class RateLimitError(FopostError):
+    """429 — rate limit exceeded. ``retry_after`` is in seconds when sent."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status: int,
+        code: str | None = None,
+        body: Any = None,
+        retry_after: float | None = None,
+    ) -> None:
+        super().__init__(message, status=status, code=code, body=body)
+        self.retry_after = retry_after
+
+
+_BY_STATUS: dict[int, type[FopostError]] = {
+    401: AuthenticationError,
+    402: PaymentRequiredError,
+    403: PermissionDeniedError,
+    404: NotFoundError,
+    429: RateLimitError,
+}
+
+
+def error_from_response(
+    status: int,
+    body: Any,
+    *,
+    retry_after: float | None = None,
+) -> FopostError:
+    """Build the most specific error class for a failed response."""
+    code: str | None = None
+    message = f"HTTP {status}"
+
+    if isinstance(body, dict):
+        raw_error = body.get("error")
+        if isinstance(raw_error, str):
+            code = raw_error
+        raw_message = body.get("message")
+        if isinstance(raw_message, str) and raw_message:
+            message = raw_message
+        elif code:
+            message = code
+    elif isinstance(body, str) and body.strip():
+        message = body.strip()
+
+    cls = _BY_STATUS.get(status, FopostError)
+    if cls is RateLimitError:
+        return RateLimitError(message, status=status, code=code, body=body, retry_after=retry_after)
+    return cls(message, status=status, code=code, body=body)