fopost-fastapi 0.1.0__py3-none-any.whl

fopost_fastapi/__init__.py

@@ -0,0 +1,85 @@
+"""fopost-fastapi — the official FastAPI integration for the FoPost API.
+
+A thin wrapper: every request, model, retry, and error type lives in the
+``fopost`` package. This one wires that client into FastAPI's idioms —
+settings, dependency injection, a webhook receiver, and an exception handler.
+
+::
+
+    from fastapi import FastAPI
+    from fopost_fastapi import FoPostDep, install_exception_handlers, setup_fopost
+
+    app = FastAPI()
+    setup_fopost(app)
+    install_exception_handlers(app)
+
+    @app.get("/workspaces")
+    def workspaces(fopost: FoPostDep):
+        return fopost.workspaces.list()
+
+``fopost`` is synchronous. A ``def`` route like the one above is already run in
+a worker thread by FastAPI; from an ``async def`` route, wrap the call in
+:func:`run_fopost` so the event loop keeps turning.
+"""
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _pkg_version
+
+from .client import (
+    STATE_ATTR,
+    FoPostDep,
+    FoPostSettingsDep,
+    create_client,
+    fopost_lifespan,
+    get_client,
+    get_settings,
+    setup_fopost,
+)
+from .concurrency import run_fopost
+from .errors import fopost_exception_handler, install_exception_handlers
+from .settings import FoPostSettings
+from .webhooks import (
+    ANY_EVENT,
+    DELIVERY_HEADER,
+    EVENT_HEADER,
+    SIGNATURE_HEADER,
+    WEBHOOK_EVENTS,
+    FoPostWebhookRouter,
+    WebhookEvent,
+    on_event,
+    sign_payload,
+    verify_webhook_signature,
+    webhook_router,
+)
+
+try:
+    __version__ = _pkg_version("fopost-fastapi")
+except PackageNotFoundError:  # running from a source tree
+    __version__ = "0.0.0"
+
+__all__ = [
+    "ANY_EVENT",
+    "DELIVERY_HEADER",
+    "EVENT_HEADER",
+    "SIGNATURE_HEADER",
+    "STATE_ATTR",
+    "WEBHOOK_EVENTS",
+    "FoPostDep",
+    "FoPostSettings",
+    "FoPostSettingsDep",
+    "FoPostWebhookRouter",
+    "WebhookEvent",
+    "__version__",
+    "create_client",
+    "fopost_exception_handler",
+    "fopost_lifespan",
+    "get_client",
+    "get_settings",
+    "install_exception_handlers",
+    "on_event",
+    "run_fopost",
+    "setup_fopost",
+    "sign_payload",
+    "verify_webhook_signature",
+    "webhook_router",
+]

fopost_fastapi/client.py

@@ -0,0 +1,152 @@
+"""Client construction, app wiring, and the injectable dependency."""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Callable
+from contextlib import AbstractAsyncContextManager, asynccontextmanager
+from typing import Annotated, Any
+
+import httpx
+from fastapi import Depends, FastAPI, Request
+from fopost import Fopost
+
+from .concurrency import run_fopost
+from .settings import FoPostSettings
+
+__all__ = [
+    "STATE_ATTR",
+    "FoPostDep",
+    "FoPostSettingsDep",
+    "create_client",
+    "fopost_lifespan",
+    "get_client",
+    "get_settings",
+    "setup_fopost",
+]
+
+#: Attribute on ``app.state`` holding the one client the app shares.
+STATE_ATTR = "fopost"
+_SETTINGS_ATTR = "fopost_settings"
+
+
+def create_client(
+    settings: FoPostSettings | None = None,
+    *,
+    http_client: httpx.Client | None = None,
+) -> Fopost:
+    """Build a ``Fopost`` client from settings.
+
+    ``http_client`` is an injection point for tests: pass an ``httpx.Client``
+    carrying a mock transport and no request ever leaves the process.
+    """
+    settings = settings or FoPostSettings()
+    if not settings.api_key:
+        raise RuntimeError(
+            "fopost-fastapi: no API key — set FOPOST_API_KEY or pass "
+            "FoPostSettings(api_key=...) to setup_fopost()"
+        )
+    return Fopost(
+        api_key=settings.api_key,
+        base_url=settings.base_url,
+        timeout=settings.timeout,
+        max_retries=settings.max_retries,
+        http_client=http_client,
+    )
+
+
+def setup_fopost(
+    app: FastAPI,
+    settings: FoPostSettings | None = None,
+    *,
+    http_client: httpx.Client | None = None,
+) -> FoPostSettings:
+    """Wire FoPost into ``app``: one client for the whole process.
+
+    Call this at import time, before the app starts serving::
+
+        app = FastAPI()
+        setup_fopost(app)
+
+    The client is created when the app starts and closed when it stops, and it
+    wraps whatever lifespan the app already has rather than replacing it.
+    Returns the resolved settings so routers can read ``webhook_secret`` and
+    ``default_workspace_id`` from them.
+    """
+    settings = settings or FoPostSettings()
+    setattr(app.state, _SETTINGS_ATTR, settings)
+
+    inner = app.router.lifespan_context
+
+    @asynccontextmanager
+    async def lifespan(app: FastAPI) -> AsyncIterator[Any]:
+        client = create_client(settings, http_client=http_client)
+        setattr(app.state, STATE_ATTR, client)
+        try:
+            async with inner(app) as state:
+                yield state
+        finally:
+            setattr(app.state, STATE_ATTR, None)
+            await run_fopost(client.close)
+
+    app.router.lifespan_context = lifespan
+    return settings
+
+
+def fopost_lifespan(
+    settings: FoPostSettings | None = None,
+    *,
+    http_client: httpx.Client | None = None,
+) -> Callable[[FastAPI], AbstractAsyncContextManager[None]]:
+    """A lifespan to hand straight to ``FastAPI(lifespan=...)``.
+
+    ::
+
+        app = FastAPI(lifespan=fopost_lifespan())
+
+    Equivalent to :func:`setup_fopost` for an app with no lifespan of its own.
+    """
+    resolved = settings or FoPostSettings()
+
+    @asynccontextmanager
+    async def lifespan(app: FastAPI) -> AsyncIterator[None]:
+        setattr(app.state, _SETTINGS_ATTR, resolved)
+        client = create_client(resolved, http_client=http_client)
+        setattr(app.state, STATE_ATTR, client)
+        try:
+            yield
+        finally:
+            setattr(app.state, STATE_ATTR, None)
+            await run_fopost(client.close)
+
+    return lifespan
+
+
+def get_client(request: Request) -> Fopost:
+    """Dependency returning the shared client. Never builds one per request."""
+    client = getattr(request.app.state, STATE_ATTR, None)
+    if not isinstance(client, Fopost):
+        raise RuntimeError(
+            "fopost-fastapi: no client on app.state — call setup_fopost(app) or pass "
+            "lifespan=fopost_lifespan() when creating the app"
+        )
+    return client
+
+
+def get_settings(request: Request) -> FoPostSettings:
+    """Dependency returning the settings the app was wired with."""
+    settings = getattr(request.app.state, _SETTINGS_ATTR, None)
+    if settings is None:
+        raise RuntimeError(
+            "fopost-fastapi: no settings on app.state — call setup_fopost(app) or pass "
+            "lifespan=fopost_lifespan() when creating the app"
+        )
+    if not isinstance(settings, FoPostSettings):  # pragma: no cover - defensive
+        raise RuntimeError("fopost-fastapi: app.state.fopost_settings is not FoPostSettings")
+    return settings
+
+
+#: Inject the shared client: ``def route(fopost: FoPostDep) -> ...``
+FoPostDep = Annotated[Fopost, Depends(get_client)]
+
+#: Inject the resolved settings: ``def route(settings: FoPostSettingsDep) -> ...``
+FoPostSettingsDep = Annotated[FoPostSettings, Depends(get_settings)]

fopost_fastapi/concurrency.py

@@ -0,0 +1,43 @@
+"""Bridge between the synchronous ``fopost`` SDK and the event loop.
+
+The ``fopost`` package ships a blocking client only — there is no async variant —
+so every call made from an ``async def`` route has to leave the event loop.
+"""
+
+from __future__ import annotations
+
+import functools
+from collections.abc import Callable
+from typing import ParamSpec, TypeVar
+
+from fastapi.concurrency import run_in_threadpool
+
+__all__ = ["run_fopost"]
+
+P = ParamSpec("P")
+R = TypeVar("R")
+
+
+async def run_fopost(
+    func: Callable[P, R],
+    /,
+    *args: P.args,
+    **kwargs: P.kwargs,
+) -> R:
+    """Await a blocking FoPost call without stalling the event loop.
+
+    ::
+
+        @app.post("/posts")
+        async def create(fopost: FoPostDep):
+            return await run_fopost(
+                fopost.posts.create,
+                workspace_id="9b2f6c1e-...",
+                content="Hello from FastAPI",
+                accounts=[...],
+            )
+
+    A plain ``def`` route needs none of this — FastAPI already runs those in a
+    worker thread, so call the SDK directly there.
+    """
+    return await run_in_threadpool(functools.partial(func, *args, **kwargs))

fopost_fastapi/errors.py

@@ -0,0 +1,57 @@
+"""Turn ``fopost`` SDK exceptions into HTTP responses.
+
+An unhandled SDK error is a 500 with a stack trace. Registering the handler
+below turns it into the status the FoPost API actually answered with, keeping
+the machine-readable ``error`` code, the 402 ``upgrade_url``, and the 429
+``Retry-After`` intact so the caller can act on them.
+"""
+
+from __future__ import annotations
+
+import math
+from typing import Any
+
+from fastapi import FastAPI, Request
+from fastapi.responses import JSONResponse
+from fopost import FopostError, PaymentRequiredError, RateLimitError
+
+__all__ = ["fopost_exception_handler", "install_exception_handlers"]
+
+#: Upstream 5xx becomes a gateway error — this app is fine, its dependency is not.
+_UPSTREAM_FAILURE_STATUS = 502
+
+
+def _status_for(exc: FopostError) -> int:
+    if 400 <= exc.status < 500:
+        return exc.status
+    return _UPSTREAM_FAILURE_STATUS
+
+
+def _retry_after_header(exc: RateLimitError) -> dict[str, str]:
+    if exc.retry_after is None:
+        return {}
+    return {"Retry-After": str(max(0, math.ceil(exc.retry_after)))}
+
+
+async def fopost_exception_handler(request: Request, exc: Exception) -> JSONResponse:
+    """Render a ``FopostError`` as JSON, preserving what the caller needs."""
+    if not isinstance(exc, FopostError):  # pragma: no cover - registered by type
+        raise exc
+
+    payload: dict[str, Any] = {
+        "error": exc.code or "fopost_error",
+        "message": exc.message,
+    }
+    headers: dict[str, str] = {}
+
+    if isinstance(exc, PaymentRequiredError) and exc.upgrade_url:
+        payload["upgrade_url"] = exc.upgrade_url
+    if isinstance(exc, RateLimitError):
+        headers = _retry_after_header(exc)
+
+    return JSONResponse(payload, status_code=_status_for(exc), headers=headers or None)
+
+
+def install_exception_handlers(app: FastAPI) -> None:
+    """Register :func:`fopost_exception_handler` for every SDK error."""
+    app.add_exception_handler(FopostError, fopost_exception_handler)

fopost_fastapi/settings.py

@@ -0,0 +1,54 @@
+"""Configuration for the FoPost integration, read from ``FOPOST_*`` environment variables."""
+
+from __future__ import annotations
+
+from fopost import DEFAULT_BASE_URL
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+__all__ = ["FoPostSettings"]
+
+
+class FoPostSettings(BaseSettings):
+    """Settings for the FoPost client and webhook receiver.
+
+    Every field is read from the matching ``FOPOST_``-prefixed environment
+    variable, so ``FOPOST_API_KEY`` fills ``api_key``::
+
+        settings = FoPostSettings()                     # from the environment
+        settings = FoPostSettings(api_key="fp_...")     # or explicitly
+    """
+
+    model_config = SettingsConfigDict(
+        env_prefix="FOPOST_",
+        env_file=".env",
+        env_file_encoding="utf-8",
+        extra="ignore",
+    )
+
+    api_key: str | None = Field(
+        default=None,
+        description="API key from https://app.fopost.com/api-keys, sent as X-API-Key.",
+    )
+    base_url: str = Field(
+        default=DEFAULT_BASE_URL,
+        description="Root of the FoPost API.",
+    )
+    timeout: float = Field(
+        default=30.0,
+        gt=0,
+        description="Seconds to wait for a single request before giving up.",
+    )
+    max_retries: int = Field(
+        default=3,
+        ge=1,
+        description="Attempts a rate limited request gets, including the first.",
+    )
+    default_workspace_id: str | None = Field(
+        default=None,
+        description="Workspace to fall back to when a route does not name one.",
+    )
+    webhook_secret: str | None = Field(
+        default=None,
+        description="Secret of the FoPost webhook whose deliveries this app receives.",
+    )

fopost_fastapi/webhooks.py

@@ -0,0 +1,197 @@
+"""Receive FoPost webhooks.
+
+FoPost signs every delivery with HMAC-SHA256 over the **raw** request body,
+using that webhook's secret, and sends it as::
+
+    X-FoPost-Signature: sha256=<hex digest>
+    X-FoPost-Event: post.published
+    X-FoPost-Delivery: <delivery id>
+
+The body is ``{"event": ..., "data": {...}, "timestamp": "<ISO 8601>"}``.
+The signature covers the bytes as sent, so it is verified before any parsing —
+re-serialising the JSON would change the digest.
+"""
+
+from __future__ import annotations
+
+import hmac
+import inspect
+from collections import defaultdict
+from collections.abc import Awaitable, Callable
+from hashlib import sha256
+from typing import Any, TypeVar, cast
+
+from fastapi import APIRouter, HTTPException, Request, status
+from pydantic import BaseModel, Field
+
+from .concurrency import run_fopost
+from .settings import FoPostSettings
+
+__all__ = [
+    "ANY_EVENT",
+    "DELIVERY_HEADER",
+    "EVENT_HEADER",
+    "SIGNATURE_HEADER",
+    "WEBHOOK_EVENTS",
+    "FoPostWebhookRouter",
+    "WebhookEvent",
+    "on_event",
+    "sign_payload",
+    "verify_webhook_signature",
+    "webhook_router",
+]
+
+SIGNATURE_HEADER = "X-FoPost-Signature"
+EVENT_HEADER = "X-FoPost-Event"
+DELIVERY_HEADER = "X-FoPost-Delivery"
+_SIGNATURE_PREFIX = "sha256="
+
+#: Subscribe to every event, whatever it is.
+ANY_EVENT = "*"
+
+#: Events FoPost can deliver, as accepted by ``POST /v1/webhooks``.
+WEBHOOK_EVENTS = (
+    "post.published",
+    "post.failed",
+    "post.partially_failed",
+    "delivery.published",
+    "delivery.failed",
+    "delivery.delayed",
+    "account.health_changed",
+)
+
+
+class WebhookEvent(BaseModel):
+    """One delivery, as FoPost sends it."""
+
+    event: str
+    data: dict[str, Any] = Field(default_factory=dict)
+    timestamp: str | None = None
+    delivery_id: str | None = Field(
+        default=None,
+        description="Value of the X-FoPost-Delivery header, not part of the body.",
+    )
+
+
+Handler = Callable[[WebhookEvent], Awaitable[None] | None]
+H = TypeVar("H", bound=Handler)
+
+
+def sign_payload(body: bytes, secret: str) -> str:
+    """Return the header value FoPost sends for ``body``, ``sha256=`` included."""
+    digest = hmac.new(secret.encode("utf-8"), body, sha256).hexdigest()
+    return f"{_SIGNATURE_PREFIX}{digest}"
+
+
+def verify_webhook_signature(body: bytes, header: str | None, secret: str) -> bool:
+    """Constant-time check of a delivery signature against the raw body."""
+    if not header or not secret:
+        return False
+    return hmac.compare_digest(sign_payload(body, secret), header.strip())
+
+
+class FoPostWebhookRouter(APIRouter):
+    """An ``APIRouter`` that verifies FoPost signatures and fans out to handlers.
+
+    ::
+
+        app.include_router(webhook_router, prefix="/fopost")
+
+        @on_event("post.published")
+        async def published(event: WebhookEvent) -> None:
+            ...
+
+    The secret comes from ``FoPostSettings.webhook_secret`` (``FOPOST_WEBHOOK_SECRET``)
+    unless one is passed here. With no secret at all the route answers 500 rather
+    than accepting unverified traffic.
+    """
+
+    def __init__(
+        self,
+        *,
+        path: str = "/webhooks",
+        secret: str | None = None,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(**kwargs)
+        self._handlers: defaultdict[str, list[Handler]] = defaultdict(list)
+        self._secret = secret
+        self.add_api_route(
+            path,
+            self._receive,
+            methods=["POST"],
+            name="fopost_webhook",
+            summary="Receive a FoPost webhook",
+            include_in_schema=False,
+        )
+
+    def on_event(self, event: str = ANY_EVENT) -> Callable[[H], H]:
+        """Register a handler for one event, or for :data:`ANY_EVENT`."""
+
+        def decorator(func: H) -> H:
+            self._handlers[event].append(func)
+            return func
+
+        return decorator
+
+    def handlers_for(self, event: str) -> list[Handler]:
+        return [*self._handlers.get(event, ()), *self._handlers.get(ANY_EVENT, ())]
+
+    def _resolve_secret(self, request: Request) -> str | None:
+        if self._secret:
+            return self._secret
+        settings = getattr(request.app.state, "fopost_settings", None)
+        if isinstance(settings, FoPostSettings):
+            return settings.webhook_secret
+        return None
+
+    async def _receive(self, request: Request) -> dict[str, Any]:
+        secret = self._resolve_secret(request)
+        if not secret:
+            raise HTTPException(
+                status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+                detail="fopost webhook secret is not configured",
+            )
+
+        # Read the raw bytes first — the signature covers them exactly.
+        body = await request.body()
+        if not verify_webhook_signature(body, request.headers.get(SIGNATURE_HEADER), secret):
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail="invalid fopost webhook signature",
+            )
+
+        try:
+            payload = await request.json()
+        except ValueError as exc:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="fopost webhook body is not valid JSON",
+            ) from exc
+        if not isinstance(payload, dict):
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="fopost webhook body is not an object",
+            )
+
+        payload.setdefault("event", request.headers.get(EVENT_HEADER, ""))
+        payload["delivery_id"] = request.headers.get(DELIVERY_HEADER) or None
+        event = WebhookEvent.model_validate(payload)
+
+        handled = await self._dispatch(event)
+        return {"received": True, "event": event.event, "handlers": handled}
+
+    async def _dispatch(self, event: WebhookEvent) -> int:
+        """Run every handler for the event. Blocking handlers go to a worker thread."""
+        handlers = self.handlers_for(event.event)
+        for handler in handlers:
+            if inspect.iscoroutinefunction(handler):
+                await handler(event)
+            else:
+                await run_fopost(cast(Callable[[WebhookEvent], None], handler), event)
+        return len(handlers)
+
+
+#: The router most apps include, and the decorator that feeds it.
+webhook_router = FoPostWebhookRouter()
+on_event = webhook_router.on_event

fopost_fastapi-0.1.0.dist-info/METADATA

@@ -0,0 +1,233 @@
+Metadata-Version: 2.5
+Name: fopost-fastapi
+Version: 0.1.0
+Summary: Official FastAPI integration for the FoPost API. Dependency injection, settings, webhooks, and error handling on top of the fopost SDK.
+Project-URL: Homepage, https://fopost.com
+Project-URL: Documentation, https://fopost.com/docs
+Project-URL: Repository, https://github.com/fopost/fopost-fastapi
+Project-URL: Issues, https://github.com/fopost/fopost-fastapi/issues
+Project-URL: Support, https://fopost.com/contact
+Author: FoPost, Porter Bridge, LLC
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,fastapi,fopost,publishing,scheduling,sdk,social-media,webhooks
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: fastapi>=0.110
+Requires-Dist: fopost<1.0,>=0.1
+Requires-Dist: pydantic-settings>=2
+Requires-Dist: pydantic>=2
+Provides-Extra: dev
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# fopost-fastapi
+
+[![PyPI](https://img.shields.io/pypi/v/fopost-fastapi.svg)](https://pypi.org/project/fopost-fastapi/)
+[![Python versions](https://img.shields.io/pypi/pyversions/fopost-fastapi.svg)](https://pypi.org/project/fopost-fastapi/)
+[![CI](https://github.com/fopost/fopost-fastapi/actions/workflows/ci.yml/badge.svg)](https://github.com/fopost/fopost-fastapi/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+Official FastAPI integration for the [FoPost](https://fopost.com) API. Schedule and publish to
++30 social platforms from your code.
+
+This is a **thin wrapper**. Every request, model, retry, and error type lives in the
+[`fopost`](https://pypi.org/project/fopost/) SDK — this package wires that client into FastAPI's
+idioms: settings, dependency injection, a webhook receiver, and an exception handler.
+
+```bash
+pip install fopost-fastapi
+```
+
+Requires Python 3.10 or newer, FastAPI 0.110 or newer, and pydantic v2.
+
+> **0.x release.** The public API is still settling and minor versions may contain breaking
+> changes. Pin an exact version if that matters to you.
+
+## Quick start
+
+```python
+from fastapi import FastAPI
+
+from fopost_fastapi import FoPostDep, install_exception_handlers, setup_fopost
+
+app = FastAPI()
+setup_fopost(app)              # one client, created at startup, closed at shutdown
+install_exception_handlers(app)
+
+
+@app.get("/workspaces")
+def workspaces(fopost: FoPostDep):
+    return fopost.workspaces.list()
+```
+
+`FoPostDep` is `Annotated[Fopost, Depends(get_client)]`. The client is built **once** when the
+app starts and shared by every request — the dependency looks it up, it never constructs one.
+
+If your app already has its own lifespan, `setup_fopost` wraps it rather than replacing it.
+To wire FoPost through the lifespan directly instead:
+
+```python
+from fopost_fastapi import fopost_lifespan
+
+app = FastAPI(lifespan=fopost_lifespan())
+```
+
+## Settings
+
+`FoPostSettings` is a `pydantic-settings` model reading `FOPOST_`-prefixed environment variables
+(and a `.env` file, if present).
+
+| Field | Environment variable | Default |
+| :--- | :--- | :--- |
+| `api_key` | `FOPOST_API_KEY` | — (required) |
+| `base_url` | `FOPOST_BASE_URL` | `https://api.fopost.com/v1` |
+| `timeout` | `FOPOST_TIMEOUT` | `30.0` seconds |
+| `max_retries` | `FOPOST_MAX_RETRIES` | `3` attempts |
+| `default_workspace_id` | `FOPOST_DEFAULT_WORKSPACE_ID` | — |
+| `webhook_secret` | `FOPOST_WEBHOOK_SECRET` | — |
+
+Create an API key at <https://app.fopost.com/api-keys>. It is sent as `X-API-Key`.
+
+Pass settings explicitly when you would rather not read the environment:
+
+```python
+setup_fopost(app, FoPostSettings(api_key="fp_...", base_url="https://api.fopost.com/v1"))
+```
+
+`FoPostSettingsDep` injects the resolved settings into a route, which is how you reach
+`default_workspace_id`.
+
+## Sync or async? The SDK is synchronous
+
+The `fopost` package ships a **blocking** client only — there is no async variant, and this
+package deliberately does not write one. That leaves two shapes:
+
+```python
+# A `def` route — FastAPI already runs it in a worker thread. Call the SDK directly.
+@app.get("/accounts")
+def accounts(fopost: FoPostDep, settings: FoPostSettingsDep):
+    return fopost.accounts.list(workspace_id=settings.default_workspace_id)
+
+
+# An `async def` route — the call must leave the event loop, or it stalls the server.
+from fopost_fastapi import run_fopost
+
+@app.post("/posts")
+async def create(fopost: FoPostDep, settings: FoPostSettingsDep):
+    return await run_fopost(
+        fopost.posts.create,
+        workspace_id=settings.default_workspace_id,
+        content="Hello from FastAPI",
+        accounts=["<account id>"],
+    )
+```
+
+`run_fopost` is a thin wrapper over `fastapi.concurrency.run_in_threadpool`. Never call the SDK
+straight from an `async def` route: a 30-second timeout would block every other request.
+
+## Receiving webhooks
+
+```python
+from fopost_fastapi import WebhookEvent, on_event, webhook_router
+
+app.include_router(webhook_router, prefix="/fopost")   # POST /fopost/webhooks
+
+
+@on_event("post.published")
+async def published(event: WebhookEvent) -> None:
+    print(event.data["id"], event.timestamp)
+
+
+@on_event("post.failed")
+def failed(event: WebhookEvent) -> None:      # a `def` handler runs in a worker thread
+    ...
+```
+
+Point a FoPost webhook at `https://<your host>/fopost/webhooks` and put its secret in
+`FOPOST_WEBHOOK_SECRET`.
+
+FoPost signs each delivery with HMAC-SHA256 over the **raw** request body using that webhook's
+secret, and sends it as `X-FoPost-Signature: sha256=<hex>` alongside `X-FoPost-Event` and
+`X-FoPost-Delivery`. The router reads the raw bytes before any parsing, compares with
+`hmac.compare_digest`, and answers **401** on a mismatch or a missing header — no handler runs.
+With no secret configured at all it answers 500 rather than accepting unverifiable traffic.
+
+Events: `post.published`, `post.failed`, `post.partially_failed`, `delivery.published`,
+`delivery.failed`, `delivery.delayed`, `account.health_changed`. `@on_event()` with no argument
+subscribes to all of them.
+
+Run several receivers, or keep the secret out of the environment, by building your own router:
+
+```python
+from fopost_fastapi import FoPostWebhookRouter
+
+router = FoPostWebhookRouter(secret="whsec_...", path="/callbacks")
+app.include_router(router, prefix="/fopost")
+```
+
+`sign_payload(body, secret)` and `verify_webhook_signature(body, header, secret)` are exported
+if you need to verify a delivery somewhere else.
+
+## Error handling
+
+`install_exception_handlers(app)` turns an SDK exception into the status the FoPost API actually
+answered with, instead of a 500 and a stack trace.
+
+| SDK error | Response |
+| :--- | :--- |
+| `AuthenticationError` (401), `PermissionDeniedError` (403), `NotFoundError` (404) | the same status |
+| `PaymentRequiredError` (402) | 402, body keeps `upgrade_url` |
+| `RateLimitError` (429) | 429 with a `Retry-After` header |
+| any 4xx | the same status |
+| any 5xx or transport failure | 502 — your app is fine, its dependency is not |
+
+The body is the API's own envelope: `{"error": "<machine code>", "message": "<human text>"}`.
+
+Retries are the SDK's job, not this package's: a 429 is retried up to `max_retries` attempts,
+honouring `Retry-After`, before the error ever reaches the handler.
+
+## The rest of the API
+
+Everything you can call on the injected client — `posts`, `accounts`, `workspaces`, `labels`,
+`ai`, and the `request()` escape hatch for endpoints the SDK does not wrap — is documented in the
+[`fopost` SDK](https://github.com/fopost/fopost-python). This package adds no resources of its own
+and stores nothing.
+
+## Example
+
+[`examples/main.py`](examples/main.py) is a complete app: settings from the environment, the
+injected client in both a `def` and an `async def` route, and the webhook receiver.
+
+## Development
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -e '.[dev]'
+pytest
+ruff check . && ruff format --check .
+mypy
+```
+
+The suite is fully offline — it stubs the SDK's HTTP transport and never reaches the network.
+
+## Links
+
+- Documentation — <https://fopost.com/docs>
+- Python SDK — <https://github.com/fopost/fopost-python>
+- Issues — <https://github.com/fopost/fopost-fastapi/issues>
+- Support — <https://fopost.com/contact>
+
+MIT licensed. Copyright (c) 2026 Porter Bridge, LLC.

fopost_fastapi-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+fopost_fastapi/__init__.py,sha256=WRbl7bgJtIsLC0djKWKW1e-dnhurjln5f8ywNzL0aa0,2175
+fopost_fastapi/client.py,sha256=murlb3N1i_Y8Sn1bxzeVcklxO_oSDJCavtgIFR7Gzvk,4874
+fopost_fastapi/concurrency.py,sha256=FzZpfX3f9vhytJQbT3HqCf1RZiwLfZF_RObuQWZJb7A,1167
+fopost_fastapi/errors.py,sha256=H-I6o_pz_rFPD_dvJVSVQa2LgF1OHTXRZBndbkUjllc,1974
+fopost_fastapi/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+fopost_fastapi/settings.py,sha256=2eDzp1hjFUM5CXlrD0aoi9oNPp0JHKlEVwml82vXWWM,1711
+fopost_fastapi/webhooks.py,sha256=rWDLd-mmi_smWMiXYES8uIEJrlGJHNy5K74Xjw8LHUc,6414
+fopost_fastapi-0.1.0.dist-info/METADATA,sha256=xr33gr_wz4qy3T9LzqrL15QvUmBGPpzA85yxp7a_pls,8887
+fopost_fastapi-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+fopost_fastapi-0.1.0.dist-info/licenses/LICENSE,sha256=-JJWsKM2TZKYsmCX8qxSbfzkUMZ0NIvV3J08SMypMn0,1075
+fopost_fastapi-0.1.0.dist-info/RECORD,,

fopost_fastapi-0.1.0.dist-info/WHEEL

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

fopost_fastapi-0.1.0.dist-info/licenses/LICENSE

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