usenadia 0.1.0__py3-none-any.whl

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/generated/__init__.py

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

usenadia/generated/api/__init__.py

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

usenadia/generated/api/public_api/__init__.py

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

usenadia/generated/api/public_api/call_video_function.py

@@ -0,0 +1,176 @@
+from http import HTTPStatus
+from typing import Any
+
+import httpx
+
+from ... import errors
+from ...client import AuthenticatedClient, Client
+from ...models.api_error_dto import ApiErrorDto
+from ...models.call_video_function_response_201 import CallVideoFunctionResponse201
+from ...models.video_function_dto import VideoFunctionDto
+from ...types import Response
+
+
+def _get_kwargs(
+    *,
+    body: VideoFunctionDto,
+) -> dict[str, Any]:
+    headers: dict[str, Any] = {}
+
+    _kwargs: dict[str, Any] = {
+        "method": "post",
+        "url": "/public/v1/video/function",
+    }
+
+    _kwargs["json"] = body.to_dict()
+
+    headers["Content-Type"] = "application/json"
+
+    _kwargs["headers"] = headers
+    return _kwargs
+
+
+def _parse_response(
+    *, client: AuthenticatedClient | Client, response: httpx.Response
+) -> ApiErrorDto | CallVideoFunctionResponse201 | None:
+    if response.status_code == 201:
+        response_201 = CallVideoFunctionResponse201.from_dict(response.json())
+
+        return response_201
+
+    if response.status_code == 400:
+        response_400 = ApiErrorDto.from_dict(response.json())
+
+        return response_400
+
+    if response.status_code == 401:
+        response_401 = ApiErrorDto.from_dict(response.json())
+
+        return response_401
+
+    if response.status_code == 404:
+        response_404 = ApiErrorDto.from_dict(response.json())
+
+        return response_404
+
+    if client.raise_on_unexpected_status:
+        raise errors.UnexpectedStatus(response.status_code, response.content)
+    else:
+        return None
+
+
+def _build_response(
+    *, client: AuthenticatedClient | Client, response: httpx.Response
+) -> Response[ApiErrorDto | CallVideoFunctionResponse201]:
+    return Response(
+        status_code=HTTPStatus(response.status_code),
+        content=response.content,
+        headers=response.headers,
+        parsed=_parse_response(client=client, response=response),
+    )
+
+
+def sync_detailed(
+    *,
+    client: AuthenticatedClient | Client,
+    body: VideoFunctionDto,
+) -> Response[ApiErrorDto | CallVideoFunctionResponse201]:
+    """Call a function of a video provider
+
+    Args:
+        body (VideoFunctionDto):
+
+    Raises:
+        errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
+        httpx.TimeoutException: If the request takes longer than Client.timeout.
+
+    Returns:
+        Response[ApiErrorDto | CallVideoFunctionResponse201]
+    """
+
+    kwargs = _get_kwargs(
+        body=body,
+    )
+
+    response = client.get_httpx_client().request(
+        **kwargs,
+    )
+
+    return _build_response(client=client, response=response)
+
+
+def sync(
+    *,
+    client: AuthenticatedClient | Client,
+    body: VideoFunctionDto,
+) -> ApiErrorDto | CallVideoFunctionResponse201 | None:
+    """Call a function of a video provider
+
+    Args:
+        body (VideoFunctionDto):
+
+    Raises:
+        errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
+        httpx.TimeoutException: If the request takes longer than Client.timeout.
+
+    Returns:
+        ApiErrorDto | CallVideoFunctionResponse201
+    """
+
+    return sync_detailed(
+        client=client,
+        body=body,
+    ).parsed
+
+
+async def asyncio_detailed(
+    *,
+    client: AuthenticatedClient | Client,
+    body: VideoFunctionDto,
+) -> Response[ApiErrorDto | CallVideoFunctionResponse201]:
+    """Call a function of a video provider
+
+    Args:
+        body (VideoFunctionDto):
+
+    Raises:
+        errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
+        httpx.TimeoutException: If the request takes longer than Client.timeout.
+
+    Returns:
+        Response[ApiErrorDto | CallVideoFunctionResponse201]
+    """
+
+    kwargs = _get_kwargs(
+        body=body,
+    )
+
+    response = await client.get_async_httpx_client().request(**kwargs)
+
+    return _build_response(client=client, response=response)
+
+
+async def asyncio(
+    *,
+    client: AuthenticatedClient | Client,
+    body: VideoFunctionDto,
+) -> ApiErrorDto | CallVideoFunctionResponse201 | None:
+    """Call a function of a video provider
+
+    Args:
+        body (VideoFunctionDto):
+
+    Raises:
+        errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
+        httpx.TimeoutException: If the request takes longer than Client.timeout.
+
+    Returns:
+        ApiErrorDto | CallVideoFunctionResponse201
+    """
+
+    return (
+        await asyncio_detailed(
+            client=client,
+            body=body,
+        )
+    ).parsed

usenadia/generated/api/public_api/change_post_status.py

@@ -0,0 +1,192 @@
+from http import HTTPStatus
+from typing import Any
+from urllib.parse import quote
+
+import httpx
+
+from ... import errors
+from ...client import AuthenticatedClient, Client
+from ...models.api_error_dto import ApiErrorDto
+from ...models.change_post_status_dto import ChangePostStatusDto
+from ...models.post_status_dto import PostStatusDto
+from ...types import Response
+
+
+def _get_kwargs(
+    id: str,
+    *,
+    body: ChangePostStatusDto,
+) -> dict[str, Any]:
+    headers: dict[str, Any] = {}
+
+    _kwargs: dict[str, Any] = {
+        "method": "put",
+        "url": "/public/v1/posts/{id}/status".format(
+            id=quote(str(id), safe=""),
+        ),
+    }
+
+    _kwargs["json"] = body.to_dict()
+
+    headers["Content-Type"] = "application/json"
+
+    _kwargs["headers"] = headers
+    return _kwargs
+
+
+def _parse_response(
+    *, client: AuthenticatedClient | Client, response: httpx.Response
+) -> ApiErrorDto | PostStatusDto | None:
+    if response.status_code == 200:
+        response_200 = PostStatusDto.from_dict(response.json())
+
+        return response_200
+
+    if response.status_code == 400:
+        response_400 = ApiErrorDto.from_dict(response.json())
+
+        return response_400
+
+    if response.status_code == 401:
+        response_401 = ApiErrorDto.from_dict(response.json())
+
+        return response_401
+
+    if response.status_code == 404:
+        response_404 = ApiErrorDto.from_dict(response.json())
+
+        return response_404
+
+    if client.raise_on_unexpected_status:
+        raise errors.UnexpectedStatus(response.status_code, response.content)
+    else:
+        return None
+
+
+def _build_response(
+    *, client: AuthenticatedClient | Client, response: httpx.Response
+) -> Response[ApiErrorDto | PostStatusDto]:
+    return Response(
+        status_code=HTTPStatus(response.status_code),
+        content=response.content,
+        headers=response.headers,
+        parsed=_parse_response(client=client, response=response),
+    )
+
+
+def sync_detailed(
+    id: str,
+    *,
+    client: AuthenticatedClient | Client,
+    body: ChangePostStatusDto,
+) -> Response[ApiErrorDto | PostStatusDto]:
+    """Change a post's status
+
+    Args:
+        id (str):
+        body (ChangePostStatusDto):
+
+    Raises:
+        errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
+        httpx.TimeoutException: If the request takes longer than Client.timeout.
+
+    Returns:
+        Response[ApiErrorDto | PostStatusDto]
+    """
+
+    kwargs = _get_kwargs(
+        id=id,
+        body=body,
+    )
+
+    response = client.get_httpx_client().request(
+        **kwargs,
+    )
+
+    return _build_response(client=client, response=response)
+
+
+def sync(
+    id: str,
+    *,
+    client: AuthenticatedClient | Client,
+    body: ChangePostStatusDto,
+) -> ApiErrorDto | PostStatusDto | None:
+    """Change a post's status
+
+    Args:
+        id (str):
+        body (ChangePostStatusDto):
+
+    Raises:
+        errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
+        httpx.TimeoutException: If the request takes longer than Client.timeout.
+
+    Returns:
+        ApiErrorDto | PostStatusDto
+    """
+
+    return sync_detailed(
+        id=id,
+        client=client,
+        body=body,
+    ).parsed
+
+
+async def asyncio_detailed(
+    id: str,
+    *,
+    client: AuthenticatedClient | Client,
+    body: ChangePostStatusDto,
+) -> Response[ApiErrorDto | PostStatusDto]:
+    """Change a post's status
+
+    Args:
+        id (str):
+        body (ChangePostStatusDto):
+
+    Raises:
+        errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
+        httpx.TimeoutException: If the request takes longer than Client.timeout.
+
+    Returns:
+        Response[ApiErrorDto | PostStatusDto]
+    """
+
+    kwargs = _get_kwargs(
+        id=id,
+        body=body,
+    )
+
+    response = await client.get_async_httpx_client().request(**kwargs)
+
+    return _build_response(client=client, response=response)
+
+
+async def asyncio(
+    id: str,
+    *,
+    client: AuthenticatedClient | Client,
+    body: ChangePostStatusDto,
+) -> ApiErrorDto | PostStatusDto | None:
+    """Change a post's status
+
+    Args:
+        id (str):
+        body (ChangePostStatusDto):
+
+    Raises:
+        errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
+        httpx.TimeoutException: If the request takes longer than Client.timeout.
+
+    Returns:
+        ApiErrorDto | PostStatusDto
+    """
+
+    return (
+        await asyncio_detailed(
+            id=id,
+            client=client,
+            body=body,
+        )
+    ).parsed