usenadia 0.1.0__tar.gz

usenadia-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+usenadia/generated/
+dist/
+*.egg-info/
+__pycache__/
+.venv/
+.ruff_cache/

usenadia-0.1.0/LICENSE

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

usenadia-0.1.0/PKG-INFO

@@ -0,0 +1,98 @@
+Metadata-Version: 2.5
+Name: usenadia
+Version: 0.1.0
+Summary: Python SDK for the UseNadia public API — schedule posts, manage channels, run the Instagram comment/story → DM machinery
+Project-URL: Homepage, https://usenadia.com
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: attrs>=22.2
+Requires-Dist: httpx<1,>=0.23
+Requires-Dist: python-dateutil>=2.8
+Description-Content-Type: text/markdown
+
+# usenadia
+
+Python SDK for the **UseNadia** public API (`/public/v1`) — schedule posts,
+manage channels, and drive the Instagram comment/story → DM machinery.
+
+```bash
+pip install usenadia
+```
+
+```python
+from usenadia import Nadia, NadiaError
+
+nadia = Nadia(api_key=os.environ["USENADIA_API_KEY"])
+
+channels = nadia.integrations()
+
+try:
+    nadia.post({
+        "type": "schedule",
+        "date": "2026-10-01T09:00:00.000Z",
+        "shortLink": False,
+        "tags": [],
+        "posts": [{
+            "integration": {"id": channels[0]["id"]},
+            "value": [{"content": "Hello from the SDK", "image": []}],
+            "settings": {},
+        }],
+    })
+except NadiaError as err:
+    print(err.status, err)      # 402 You have reached your limit
+```
+
+## The content board
+
+Every card of the board in the app is reachable: create one from anywhere
+(a voice note, a Notion page, a DM), move it along, read its numbers once
+it is published.
+
+```python
+card = nadia.create_content(
+    "Three mistakes when moving to Malta",
+    hook="Nobody told me about the third one.",
+)
+
+nadia.move_content(card["id"], "SCRIPT")
+nadia.update_content(card["id"], script="…")
+
+# Scheduled with nadia.post({..., "posts": [{"group": "g-42", ...}]}):
+nadia.link_content_post(card["id"], "g-42")  # → PUBLISHED when it goes live
+
+numbers = nadia.contents_performance()  # keyed by card id
+```
+
+Columns, in order: `IDEA`, `SCRIPT`, `VALIDATED`, `TO_SHOOT`, `TO_EDIT`,
+`TO_SCHEDULE`, `PUBLISHED`.
+
+## How it is built
+
+Two layers, and the split is deliberate.
+
+- **`usenadia/generated/`** — the transport. Generated from
+  `openapi.public.json` by
+  [`openapi-python-client`](https://github.com/openapi-generators/openapi-python-client)
+  (httpx + attrs), covers every operation, never edited by hand, not
+  committed.
+- **`usenadia/__init__.py`** — this SDK's own surface: the `Nadia` class,
+  sane defaults, typed errors, retries. Small, hand-written, reviewed.
+
+Anything the facade does not wrap is reachable through `nadia.raw`, the
+configured generated client.
+
+## Errors
+
+Every response with a status ≥ 400 raises a `NadiaError` carrying `status`,
+`body` and the API's `msg`. `err.is_transient` is true for 429 and 5xx — those
+are retried automatically (twice by default, `Nadia(key, retries=0)` to turn
+it off).
+
+## Regenerating
+
+```bash
+pnpm run sdk:generate   # from the repo root — regenerates both SDKs
+```
+
+Plan: `docs/roadmap/19-sdk-public-api.md`.

usenadia-0.1.0/README.md

@@ -0,0 +1,85 @@
+# usenadia
+
+Python SDK for the **UseNadia** public API (`/public/v1`) — schedule posts,
+manage channels, and drive the Instagram comment/story → DM machinery.
+
+```bash
+pip install usenadia
+```
+
+```python
+from usenadia import Nadia, NadiaError
+
+nadia = Nadia(api_key=os.environ["USENADIA_API_KEY"])
+
+channels = nadia.integrations()
+
+try:
+    nadia.post({
+        "type": "schedule",
+        "date": "2026-10-01T09:00:00.000Z",
+        "shortLink": False,
+        "tags": [],
+        "posts": [{
+            "integration": {"id": channels[0]["id"]},
+            "value": [{"content": "Hello from the SDK", "image": []}],
+            "settings": {},
+        }],
+    })
+except NadiaError as err:
+    print(err.status, err)      # 402 You have reached your limit
+```
+
+## The content board
+
+Every card of the board in the app is reachable: create one from anywhere
+(a voice note, a Notion page, a DM), move it along, read its numbers once
+it is published.
+
+```python
+card = nadia.create_content(
+    "Three mistakes when moving to Malta",
+    hook="Nobody told me about the third one.",
+)
+
+nadia.move_content(card["id"], "SCRIPT")
+nadia.update_content(card["id"], script="…")
+
+# Scheduled with nadia.post({..., "posts": [{"group": "g-42", ...}]}):
+nadia.link_content_post(card["id"], "g-42")  # → PUBLISHED when it goes live
+
+numbers = nadia.contents_performance()  # keyed by card id
+```
+
+Columns, in order: `IDEA`, `SCRIPT`, `VALIDATED`, `TO_SHOOT`, `TO_EDIT`,
+`TO_SCHEDULE`, `PUBLISHED`.
+
+## How it is built
+
+Two layers, and the split is deliberate.
+
+- **`usenadia/generated/`** — the transport. Generated from
+  `openapi.public.json` by
+  [`openapi-python-client`](https://github.com/openapi-generators/openapi-python-client)
+  (httpx + attrs), covers every operation, never edited by hand, not
+  committed.
+- **`usenadia/__init__.py`** — this SDK's own surface: the `Nadia` class,
+  sane defaults, typed errors, retries. Small, hand-written, reviewed.
+
+Anything the facade does not wrap is reachable through `nadia.raw`, the
+configured generated client.
+
+## Errors
+
+Every response with a status ≥ 400 raises a `NadiaError` carrying `status`,
+`body` and the API's `msg`. `err.is_transient` is true for 429 and 5xx — those
+are retried automatically (twice by default, `Nadia(key, retries=0)` to turn
+it off).
+
+## Regenerating
+
+```bash
+pnpm run sdk:generate   # from the repo root — regenerates both SDKs
+```
+
+Plan: `docs/roadmap/19-sdk-public-api.md`.

usenadia-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[project]
+name = "usenadia"
+version = "0.1.0"
+description = "Python SDK for the UseNadia public API — schedule posts, manage channels, run the Instagram comment/story → DM machinery"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+dependencies = [
+    "httpx>=0.23,<1",
+    "attrs>=22.2",
+    "python-dateutil>=2.8",
+]
+
+[project.urls]
+Homepage = "https://usenadia.com"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["usenadia"]
+
+# usenadia/generated is git-ignored (regenerated from the spec) and hatch
+# leaves ignored files out: without this, the wheel ships a facade whose
+# generated client is missing.
+[tool.hatch.build]
+artifacts = ["usenadia/generated"]
+
+# openapi-python-client is NOT a dependency of this package: it is a build
+# tool, run isolated. Its output uses `typing.Self`, hence Python >= 3.11:
+#     uvx openapi-python-client generate ...
+# See the repo-root `pnpm sdk:generate`.

usenadia-0.1.0/tests/test_facade.py

@@ -0,0 +1,131 @@
+"""Offline tests of the hand-written layer — no network, no API key.
+
+Same reason as the Node side: what this facade adds over a bare `requests`
+call is error handling and retries, and a regression there would be silent.
+
+The smoke tests against the real API (plan 19, phase 4) are a different thing
+and live elsewhere: these run in CI with nothing configured.
+
+    uv run --python 3.11 --with httpx --with pytest pytest tests/
+"""
+
+import json
+
+import httpx
+import pytest
+
+from usenadia import DEFAULT_BASE_URL, Nadia, NadiaError
+
+
+def client_with(*responses):
+    """An httpx client that replays the queued responses and records requests."""
+    calls = []
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        calls.append(request)
+        return responses[min(len(calls) - 1, len(responses) - 1)]
+
+    transport = httpx.MockTransport(handler)
+    return (
+        httpx.Client(
+            base_url=DEFAULT_BASE_URL,
+            headers={"Authorization": "ma-clef"},
+            transport=transport,
+        ),
+        calls,
+    )
+
+
+def test_sends_the_api_key_and_hits_the_documented_base_url():
+    http, calls = client_with(httpx.Response(200, json=[{"id": "c1", "name": "Channel"}]))
+    nadia = Nadia("ma-clef", client=http)
+
+    assert nadia.integrations() == [{"id": "c1", "name": "Channel"}]
+    assert str(calls[0].url) == f"{DEFAULT_BASE_URL}/public/v1/integrations"
+    assert calls[0].method == "GET"
+    assert calls[0].headers["authorization"] == "ma-clef"
+
+
+def test_a_402_raises_with_the_api_message():
+    http, _ = client_with(httpx.Response(402, json={"msg": "You have reached your limit"}))
+    nadia = Nadia("ma-clef", client=http)
+
+    with pytest.raises(NadiaError) as excinfo:
+        nadia.post({"type": "schedule"})
+
+    assert excinfo.value.status == 402
+    assert str(excinfo.value) == "You have reached your limit"
+    assert excinfo.value.is_transient is False
+
+
+def test_a_401_raises_so_a_bad_key_is_not_silent():
+    http, _ = client_with(httpx.Response(401, json={"msg": "Unauthorized"}))
+    nadia = Nadia("mauvaise-clef", client=http)
+
+    with pytest.raises(NadiaError) as excinfo:
+        nadia.is_connected()
+
+    assert excinfo.value.status == 401
+
+
+def test_retries_a_500_then_succeeds():
+    http, calls = client_with(
+        httpx.Response(500, json={"msg": "boom"}),
+        httpx.Response(200, json={"date": "2026-10-01T09:00:00.000Z"}),
+    )
+    nadia = Nadia("ma-clef", client=http)
+
+    assert nadia.find_slot("c1") == {"date": "2026-10-01T09:00:00.000Z"}
+    assert len(calls) == 2
+
+
+def test_gives_up_after_the_configured_retries():
+    http, calls = client_with(httpx.Response(503, json={"msg": "boom"}))
+    nadia = Nadia("ma-clef", client=http, retries=1)
+
+    with pytest.raises(NadiaError) as excinfo:
+        nadia.groups()
+
+    assert excinfo.value.status == 503
+    assert len(calls) == 2
+
+
+def test_an_empty_body_is_not_a_json_error():
+    http, _ = client_with(httpx.Response(204))
+    nadia = Nadia("ma-clef", client=http)
+
+    assert nadia.delete_post("p1") is None
+
+
+def test_an_error_without_the_msg_shape_still_raises_cleanly():
+    http, _ = client_with(httpx.Response(400, text="<html>nginx</html>"))
+    nadia = Nadia("ma-clef", client=http)
+
+    with pytest.raises(NadiaError) as excinfo:
+        nadia.groups()
+
+    assert excinfo.value.status == 400
+    assert excinfo.value.body == "<html>nginx</html>"
+
+
+def test_an_empty_api_key_is_refused_up_front():
+    with pytest.raises(ValueError):
+        Nadia("")
+
+
+def test_the_board_creates_then_moves_a_card_with_only_a_stage():
+    http, calls = client_with(
+        httpx.Response(201, json={"id": "k1", "title": "Idée", "stage": "IDEA"}),
+        httpx.Response(200, json={"id": "k1", "stage": "SCRIPT"}),
+    )
+    nadia = Nadia("ma-clef", client=http)
+
+    card = nadia.create_content("Idée", hook="Accroche")
+    nadia.move_content(card["id"], "SCRIPT")
+
+    assert calls[0].method == "POST"
+    assert str(calls[0].url) == f"{DEFAULT_BASE_URL}/public/v1/contents"
+    assert json.loads(calls[0].content) == {"title": "Idée", "hook": "Accroche"}
+    assert calls[1].method == "PUT"
+    assert str(calls[1].url) == f"{DEFAULT_BASE_URL}/public/v1/contents/k1/move"
+    assert json.loads(calls[1].content) == {"stage": "SCRIPT"}

usenadia-0.1.0/usenadia/__init__.py

@@ -0,0 +1,278 @@
+"""UseNadia Python SDK.
+
+Two layers, on purpose (plan 19) — this module is the second one.
+
+    usenadia/generated/   transport, regenerated from ``openapi.public.json``
+                          by openapi-python-client, covers every operation,
+                          never edited by hand, not committed.
+    usenadia/__init__.py  this file: the small, hand-written surface that makes
+                          the common calls pleasant, and that we take
+                          responsibility for.
+
+Anything the facade does not wrap stays reachable through :attr:`Nadia.raw`,
+the configured generated client.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Any, Callable, Mapping, Optional, TypeVar
+
+import httpx
+
+__all__ = ["Nadia", "NadiaError", "DEFAULT_BASE_URL"]
+
+DEFAULT_BASE_URL = "https://app.usenadia.com/api"
+
+T = TypeVar("T")
+
+
+class NadiaError(Exception):
+    """Raised for every response with a status >= 400."""
+
+    def __init__(self, status: int, body: Any, message: Optional[str] = None):
+        self.status = status
+        self.body = body
+        super().__init__(message or f"UseNadia API responded {status}")
+
+    @property
+    def is_transient(self) -> bool:
+        """True when retrying later could plausibly work (rate limit, server hiccup)."""
+        return self.status == 429 or self.status >= 500
+
+
+def _message_of(body: Any) -> Optional[str]:
+    """Read the API's ``{"msg": ...}`` error shape without assuming it is there."""
+    if isinstance(body, Mapping):
+        msg = body.get("msg")
+        if isinstance(msg, str):
+            return msg
+    return None
+
+
+class Nadia:
+    """Client for the UseNadia public API.
+
+    >>> nadia = Nadia(api_key="...")
+    >>> channels = nadia.integrations()
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        *,
+        retries: int = 2,
+        timeout: float = 30.0,
+        client: Optional[httpx.Client] = None,
+    ):
+        if not api_key:
+            raise ValueError("An API key is required.")
+
+        self._api_key = api_key
+        self._retries = retries
+        self._typed: Any = None
+        self._client = client or httpx.Client(
+            base_url=base_url.rstrip("/"),
+            headers={"Authorization": api_key},
+            timeout=timeout,
+        )
+
+    # ------------------------------------------------------------------ #
+
+    def _request(self, method: str, path: str, **kwargs: Any) -> Any:
+        """Send a request, raise :class:`NadiaError` on non-2xx, retry the
+        transient ones. Every method below goes through here — that is the
+        whole point of the facade."""
+        last: Optional[NadiaError] = None
+
+        for attempt in range(self._retries + 1):
+            response = self._client.request(method, path, **kwargs)
+
+            if response.is_success:
+                if not response.content:
+                    return None
+                try:
+                    return response.json()
+                except ValueError:
+                    return response.content
+
+            try:
+                body: Any = response.json()
+            except ValueError:
+                body = response.text
+
+            last = NadiaError(response.status_code, body, _message_of(body))
+
+            if not last.is_transient or attempt == self._retries:
+                raise last
+
+            time.sleep(2**attempt * 0.5)
+
+        assert last is not None
+        raise last
+
+    # -- the five calls upstream's Node SDK had, same names -------------- #
+
+    def post(self, body: Mapping[str, Any]) -> Any:
+        """Schedule, publish or draft a post on one or more channels."""
+        return self._request("POST", "/public/v1/posts", json=body)
+
+    def post_list(self, **query: Any) -> Any:
+        """List posts in a date range."""
+        return self._request("GET", "/public/v1/posts", params=query or None)
+
+    def upload(self, file: bytes, filename: str = "upload") -> Any:
+        """Upload a file and get a URL usable in a post."""
+        return self._request(
+            "POST", "/public/v1/upload", files={"file": (filename, file)}
+        )
+
+    def integrations(self, group: Optional[str] = None) -> Any:
+        """List your connected channels."""
+        return self._request(
+            "GET",
+            "/public/v1/integrations",
+            params={"group": group} if group else None,
+        )
+
+    def delete_post(self, post_id: str) -> Any:
+        """Delete a post and everything published with it."""
+        return self._request("DELETE", f"/public/v1/posts/{post_id}")
+
+    # -- the rest of our surface, which upstream never had --------------- #
+
+    def is_connected(self) -> bool:
+        """Check the API key. Raises :class:`NadiaError` with status 401 if invalid."""
+        self._request("GET", "/public/v1/is-connected")
+        return True
+
+    def find_slot(self, integration_id: str) -> Any:
+        """Next free slot in a channel's schedule."""
+        return self._request("GET", f"/public/v1/find-slot/{integration_id}")
+
+    def groups(self) -> Any:
+        """List your groups (brands)."""
+        return self._request("GET", "/public/v1/groups")
+
+    def inbox(self, integration_id: str, limit: Optional[int] = None) -> Any:
+        """Direct message conversations of a channel."""
+        return self._request(
+            "GET",
+            f"/public/v1/inbox/{integration_id}",
+            params={"limit": limit} if limit else None,
+        )
+
+    # -- the content board: one card per video, idea to numbers --------- #
+
+    def contents(self, **filters: Any) -> Any:
+        """The cards of the board, with the posts scheduled from each.
+
+        Filters combine: ``stage``, ``tag``, ``externalId``; ``fields``
+        (``"id,title,stage"``) leaves the scripts out.
+        """
+        return self._request(
+            "GET", "/public/v1/contents", params=filters or None
+        )
+
+    def content(self, content_id: str) -> Any:
+        """One card."""
+        return self._request("GET", f"/public/v1/contents/{content_id}")
+
+    def create_content(self, title: str, **fields: Any) -> Any:
+        """Create a card — in ``IDEA`` unless ``stage`` says otherwise.
+
+        Other fields: ``externalId``, ``hook``, ``hookText``, ``script``,
+        ``notes``, ``tags``, ``resourceStatus``, ``resourceUrl``,
+        ``resourceBrief``, ``integrationIds``, ``plannedAt``, ``parentId``.
+        """
+        return self._request(
+            "POST", "/public/v1/contents", json={"title": title, **fields}
+        )
+
+    def upsert_content(self, external_id: str, title: str, **fields: Any) -> Any:
+        """Create or update the card holding ``external_id`` (your own id).
+
+        Re-running an import never duplicates; an existing card keeps its
+        column. Returns ``{"created": bool, "content": {...}}``.
+        """
+        return self._request(
+            "POST",
+            "/public/v1/contents/upsert",
+            json={"externalId": external_id, "title": title, **fields},
+        )
+
+    def update_content(self, content_id: str, **fields: Any) -> Any:
+        """Update a card: only the fields passed change, ``None`` clears one."""
+        return self._request(
+            "PUT", f"/public/v1/contents/{content_id}", json=fields
+        )
+
+    def move_content(
+        self, content_id: str, stage: str, position: Optional[float] = None
+    ) -> Any:
+        """Move a card to another column (to the bottom unless ``position`` is given)."""
+        body: dict = {"stage": stage}
+        if position is not None:
+            body["position"] = position
+        return self._request(
+            "PUT", f"/public/v1/contents/{content_id}/move", json=body
+        )
+
+    def link_content_post(self, content_id: str, post_group: str) -> Any:
+        """Tie a card to a post scheduled from it (the post's ``group``).
+
+        A card holds several posts (a TikTok draft, an Instagram post): each
+        call adds one. The card moves to ``PUBLISHED`` when the first of them
+        goes live.
+        """
+        return self._request(
+            "PUT",
+            f"/public/v1/contents/{content_id}/post",
+            json={"postGroup": post_group},
+        )
+
+    def delete_content(self, content_id: str) -> Any:
+        """Delete a card."""
+        return self._request("DELETE", f"/public/v1/contents/{content_id}")
+
+    def contents_performance(self) -> Any:
+        """The numbers of the published cards, keyed by card id."""
+        return self._request("GET", "/public/v1/contents/performance")
+
+    # ------------------------------------------------------------------ #
+
+    @property
+    def raw(self) -> httpx.Client:
+        """The configured httpx client, for a call the facade does not wrap."""
+        return self._client
+
+    @property
+    def typed(self) -> Any:
+        """The generated, fully typed client — every operation, with models.
+
+        >>> from usenadia.generated.api.public_api import list_channels
+        >>> list_channels.sync(client=nadia.typed)
+
+        Imported lazily so the facade still works from a checkout where the
+        client has not been generated yet (it is gitignored, see the README).
+        """
+        if self._typed is None:
+            from .generated import AuthenticatedClient  # noqa: PLC0415
+
+            self._typed = AuthenticatedClient(
+                base_url=str(self._client.base_url),
+                token=self._api_key,
+                # The API reads `Authorization: <key>`, with no `Bearer` prefix.
+                prefix="",
+            )
+        return self._typed
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> "Nadia":
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()

usenadia-0.1.0/usenadia/generated/__init__.py

@@ -0,0 +1,8 @@
+"""A client library for accessing UseNadia public API"""
+
+from .client import AuthenticatedClient, Client
+
+__all__ = (
+    "AuthenticatedClient",
+    "Client",
+)

usenadia-0.1.0/usenadia/generated/api/__init__.py

@@ -0,0 +1 @@
+"""Contains methods for accessing the API"""

usenadia-0.1.0/usenadia/generated/api/public_api/__init__.py

@@ -0,0 +1 @@
+"""Contains endpoint functions for accessing the API"""