talqing 0.1.0__py3-none-any.whl

talqing/__init__.py

@@ -0,0 +1,34 @@
+"""Python client for the Talqing API.
+
+```python
+from talqing import Talqing
+
+with Talqing.from_env() as talqing:
+    agent = talqing.agents.get(agent_id)
+```
+
+The API surface under `talqing.agents`, `talqing.calls` and the rest is
+generated from `openapi/openapi.json` — it is the same set of operations, under
+the same names, as the TypeScript SDK. Every request and response shape is
+exported from here too, as a TypedDict.
+"""
+
+from ._transport import OMIT, AsyncStream, Stream
+from ._version import __version__
+from .client import AsyncTalqing, Talqing, paginate, paginate_async
+from .errors import TalqingAPIError
+from .gen.types import *  # noqa: F403
+from .gen.types import __all__ as _types
+
+__all__ = [
+    "AsyncStream",
+    "AsyncTalqing",
+    "OMIT",
+    "Stream",
+    "Talqing",
+    "TalqingAPIError",
+    "__version__",
+    "paginate",
+    "paginate_async",
+    *_types,
+]

talqing/_transport.py

@@ -0,0 +1,361 @@
+"""The half of the SDK the OpenAPI document cannot describe: the HTTP itself.
+
+`gen/` says what every operation is; this says how one is sent. It carries the
+credentials, turns a non-2xx into `TalqingAPIError`, reads an event stream, and
+holds the sentinel that separates "leave this alone" from "set it to null".
+"""
+
+from __future__ import annotations
+
+import json as jsonlib
+from types import TracebackType
+from typing import Any, AsyncIterator, Generic, Iterator, Literal, Mapping, TypeVar
+from urllib.parse import quote
+
+import httpx
+
+from ._version import __version__
+from .errors import TalqingAPIError
+
+T = TypeVar("T")
+
+Expect = Literal["json", "none", "bytes"]
+
+
+class _Omit:
+    """The absence of an argument, which is not the same as `None`.
+
+    Several PATCH bodies take `null` as a real value — `orgs.update(
+    retention_days=None)` means "keep everything forever" — so a default of
+    `None` would leave "leave the policy alone" unsayable. An argument still at
+    `OMIT` is not sent at all, and the server applies its own default.
+    """
+
+    __slots__ = ()
+
+    def __repr__(self) -> str:
+        return "OMIT"
+
+    def __bool__(self) -> bool:
+        return False
+
+
+# Typed `Any` deliberately: this is the default of every optional argument in
+# `gen/`, and typing it as itself would put `| _Omit` in three hundred
+# signatures for no reader's benefit.
+OMIT: Any = _Omit()
+
+
+def encode_path(value: Any) -> str:
+    """One path segment, escaped. `safe=""` because a path parameter is never a path."""
+    return quote(str(value), safe="")
+
+
+def sent(values: Mapping[str, Any] | None) -> dict[str, Any] | None:
+    """Drop the arguments the caller never passed."""
+    if values is None:
+        return None
+    return {key: value for key, value in values.items() if value is not OMIT}
+
+
+def raise_for_status(response: httpx.Response) -> None:
+    if response.is_success:
+        return
+    # The contract is strict: the body is always {"detail": {"message", "errors"}}.
+    # The fallback below is for a failure that never reached the API at all — a
+    # proxy's HTML 502, a gateway timeout — not for a second response shape.
+    detail: Any
+    errors: list[str] = []
+    try:
+        detail = response.json()["detail"]
+        message = detail["message"]
+        errors = [str(error) for error in detail["errors"]]
+    except (ValueError, KeyError, TypeError):
+        detail = response.text or response.reason_phrase
+        message = detail
+    raise TalqingAPIError(
+        message,
+        status_code=response.status_code,
+        detail=detail,
+        errors=errors,
+        response=response,
+    )
+
+
+class _Decoder:
+    """The `text/event-stream` state machine, fed one line at a time.
+
+    A class rather than a generator because `async for` cannot drive a
+    synchronous one, and the parsing itself must not be written twice.
+
+    The `event:` line is not read. Every frame repeats its own name in the
+    JSON's `event` field — what the unions in `gen/types.py` discriminate on —
+    so reading it twice would only create somewhere for the two to disagree.
+    """
+
+    def __init__(self) -> None:
+        self._data: list[str] = []
+
+    def feed(self, line: str) -> list[Any]:
+        """The frames this line completed: none, or one. A list, so "not yet"
+        needs no sentinel to tell it from a frame that decoded to `None`."""
+        if line == "":
+            return self.flush()
+        if line.startswith(":"):
+            return []  # a keep-alive, sent every 15s so idle proxies hold on
+        field, _, value = line.partition(":")
+        if field == "data":
+            self._data.append(value[1:] if value.startswith(" ") else value)
+        return []
+
+    def flush(self) -> list[Any]:
+        if not self._data:
+            return []
+        frame = jsonlib.loads("\n".join(self._data))
+        self._data = []
+        return [frame]
+
+
+def _options(expect: Expect) -> dict[str, Any]:
+    """The request options that depend on what is coming back.
+
+    The two recording endpoints answer `302` and the media is what the caller
+    asked for, so those follow the redirect. Nothing else in the API redirects,
+    and a POST that silently followed one would be a surprise worth avoiding.
+    httpx drops the Authorization header when a redirect leaves our origin,
+    which is what makes handing the request on to object storage safe.
+    """
+    binary = expect == "bytes"
+    return {
+        "headers": {"Accept": "*/*" if binary else "application/json"},
+        "follow_redirects": binary,
+    }
+
+
+def _decode(response: httpx.Response, expect: Expect) -> Any:
+    if expect == "none":
+        return None
+    if expect == "bytes":
+        return response.content
+    return response.json()
+
+
+def _headers(token: str, extra: Mapping[str, str] | None) -> dict[str, str]:
+    headers = {
+        "Authorization": f"Bearer {token}",
+        "User-Agent": f"talqing-python/{__version__}",
+    }
+    headers.update(extra or {})
+    return headers
+
+
+class Stream(Generic[T]):
+    """An open `text/event-stream`, as an iterator of decoded frames.
+
+    Iterating opens the connection and closes it when the stream ends or the
+    loop is left. Use it as a context manager when the loop may exit early::
+
+        with talqing.conversations.events(conversation_id) as events:
+            for event in events:
+                if event["event"] == "turn":
+                    break
+    """
+
+    def __init__(
+        self, client: httpx.Client, url: str, params: Mapping[str, Any] | None
+    ) -> None:
+        self._context = client.stream(
+            "GET", url, params=params, headers={"Accept": "text/event-stream"}
+        )
+        self._response: httpx.Response | None = None
+        self._spent = False
+
+    def __enter__(self) -> "Stream[T]":
+        self._open()
+        return self
+
+    def __exit__(
+        self,
+        kind: type[BaseException] | None,
+        error: BaseException | None,
+        trace: TracebackType | None,
+    ) -> None:
+        self.close()
+
+    def __iter__(self) -> Iterator[T]:
+        self._open()
+        assert self._response is not None
+        decoder = _Decoder()
+        try:
+            for line in self._response.iter_lines():
+                yield from decoder.feed(line)
+            yield from decoder.flush()
+        finally:
+            self.close()
+
+    def _open(self) -> None:
+        if self._response is not None:
+            return
+        if self._spent:
+            raise RuntimeError("this stream is finished; open a new one to watch again")
+        self._response = self._context.__enter__()
+        if not self._response.is_success:
+            # Nothing has been read yet, so the error body is still on the wire.
+            self._response.read()
+            try:
+                raise_for_status(self._response)
+            finally:
+                self.close()
+
+    def close(self) -> None:
+        if self._response is None:
+            return
+        self._response = None
+        self._spent = True
+        self._context.__exit__(None, None, None)
+
+
+class AsyncStream(Generic[T]):
+    """`Stream`, awaited. See it for the shape; this differs only in `async for`."""
+
+    def __init__(
+        self, client: httpx.AsyncClient, url: str, params: Mapping[str, Any] | None
+    ) -> None:
+        self._context = client.stream(
+            "GET", url, params=params, headers={"Accept": "text/event-stream"}
+        )
+        self._response: httpx.Response | None = None
+        self._spent = False
+
+    async def __aenter__(self) -> "AsyncStream[T]":
+        await self._open()
+        return self
+
+    async def __aexit__(
+        self,
+        kind: type[BaseException] | None,
+        error: BaseException | None,
+        trace: TracebackType | None,
+    ) -> None:
+        await self.aclose()
+
+    async def __aiter__(self) -> AsyncIterator[T]:
+        await self._open()
+        assert self._response is not None
+        decoder = _Decoder()
+        try:
+            async for line in self._response.aiter_lines():
+                for frame in decoder.feed(line):
+                    yield frame
+            for frame in decoder.flush():
+                yield frame
+        finally:
+            await self.aclose()
+
+    async def _open(self) -> None:
+        if self._response is not None:
+            return
+        if self._spent:
+            raise RuntimeError("this stream is finished; open a new one to watch again")
+        self._response = await self._context.__aenter__()
+        if not self._response.is_success:
+            await self._response.aread()
+            try:
+                raise_for_status(self._response)
+            finally:
+                await self.aclose()
+
+    async def aclose(self) -> None:
+        if self._response is None:
+            return
+        self._response = None
+        self._spent = True
+        await self._context.__aexit__(None, None, None)
+
+
+class Transport:
+    """One configured `httpx.Client`, and the two things every method needs."""
+
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        token: str,
+        timeout: float | httpx.Timeout,
+        headers: Mapping[str, str] | None,
+        transport: httpx.BaseTransport | None,
+    ) -> None:
+        self.base_url = base_url
+        self.http = httpx.Client(
+            base_url=base_url,
+            timeout=timeout,
+            transport=transport,
+            headers=_headers(token, headers),
+        )
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        query: Mapping[str, Any] | None = None,
+        body: Mapping[str, Any] | None = None,
+        expect: Expect = "json",
+    ) -> Any:
+        response = self.http.request(
+            method, path, params=sent(query), json=sent(body), **_options(expect)
+        )
+        raise_for_status(response)
+        return _decode(response, expect)
+
+    def stream(
+        self, path: str, *, query: Mapping[str, Any] | None = None
+    ) -> Stream[Any]:
+        return Stream(self.http, path, sent(query))
+
+    def close(self) -> None:
+        self.http.close()
+
+
+class AsyncTransport:
+    """`Transport`, awaited."""
+
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        token: str,
+        timeout: float | httpx.Timeout,
+        headers: Mapping[str, str] | None,
+        transport: httpx.AsyncBaseTransport | None,
+    ) -> None:
+        self.base_url = base_url
+        self.http = httpx.AsyncClient(
+            base_url=base_url,
+            timeout=timeout,
+            transport=transport,
+            headers=_headers(token, headers),
+        )
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        query: Mapping[str, Any] | None = None,
+        body: Mapping[str, Any] | None = None,
+        expect: Expect = "json",
+    ) -> Any:
+        response = await self.http.request(
+            method, path, params=sent(query), json=sent(body), **_options(expect)
+        )
+        raise_for_status(response)
+        return _decode(response, expect)
+
+    def stream(
+        self, path: str, *, query: Mapping[str, Any] | None = None
+    ) -> AsyncStream[Any]:
+        return AsyncStream(self.http, path, sent(query))
+
+    async def close(self) -> None:
+        await self.http.aclose()

talqing/_version.py

@@ -0,0 +1,3 @@
+# The one place the version is written. `pyproject.toml` reads it from here, and
+# so does the User-Agent every request carries.
+__version__ = "0.1.0"

talqing/client.py

@@ -0,0 +1,280 @@
+"""The client itself: credentials, the two browser redirects, and pagination.
+
+Every one of the API's operations is generated into `gen/` from
+`openapi/openapi.json`. What is left here is only what the document cannot say.
+"""
+
+from __future__ import annotations
+
+import os
+from types import TracebackType
+from typing import Any, AsyncIterator, Awaitable, Callable, Iterator, Mapping, TypeVar
+from urllib.parse import quote, urlencode
+
+import httpx
+
+from ._transport import AsyncTransport, Transport
+from .gen.api import TalqingApi
+from .gen.async_api import AsyncTalqingApi
+from .gen.types import Page
+
+T = TypeVar("T")
+
+TOKEN_ENV = "TALQING_API_KEY"
+BASE_URL_ENV = "TALQING_BASE_URL"
+
+
+def _token(value: str | None) -> str:
+    if value and value.strip():
+        return value.strip()
+    raise ValueError(
+        "a Talqing personal access token is required: pass token=..., or set "
+        f"{TOKEN_ENV} and use Talqing.from_env(). Create one on the dashboard's "
+        "Tokens page."
+    )
+
+
+def _base_url(value: str | None) -> str:
+    if value and value.strip():
+        return value.strip().rstrip("/")
+    # No default, deliberately. A client that quietly points at localhost fails
+    # in production as a connection error three layers down; one that refuses to
+    # start says what is actually wrong.
+    raise ValueError(
+        "base_url is required: pass base_url='https://api.in.talqing.com', or "
+        f"set {BASE_URL_ENV} and use Talqing.from_env()."
+    )
+
+
+# Both routes are `include_in_schema=False` in the backend because they are
+# browser redirects, not operations, so nothing generates them — which is also
+# why the two clients must not each carry their own copy of the path.
+def _google_login_url(base_url: str) -> str:
+    return f"{base_url}/v1/auth/google/start"
+
+
+def _oauth_start_url(base_url: str, provider: str, integration_id: str | None) -> str:
+    url = f"{base_url}/v1/integrations/oauth/{quote(provider, safe='')}/start"
+    if integration_id:
+        url += "?" + urlencode({"integration_id": integration_id})
+    return url
+
+
+def _from_env(overrides: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "token": os.getenv(TOKEN_ENV),
+        "base_url": os.getenv(BASE_URL_ENV),
+        **overrides,
+    }
+
+
+class Talqing(TalqingApi):
+    """A synchronous client for the Talqing API.
+
+    ```python
+    with Talqing(token=..., base_url="https://api.in.talqing.com") as talqing:
+        agent = talqing.agents.get(agent_id)
+    ```
+
+    Operations are reached by resource, the way `backend/api/sdk_surface.py`
+    names them: `talqing.agents.versions.rollback(agent_id, 3)`. Every one of
+    them raises `TalqingAPIError` on a non-2xx and returns the decoded body
+    otherwise.
+    """
+
+    def __init__(
+        self,
+        token: str | None = None,
+        *,
+        base_url: str | None = None,
+        timeout: float | httpx.Timeout = 30.0,
+        headers: Mapping[str, str] | None = None,
+        transport: httpx.BaseTransport | None = None,
+    ) -> None:
+        super().__init__(
+            Transport(
+                base_url=_base_url(base_url),
+                token=_token(token),
+                timeout=timeout,
+                headers=headers,
+                transport=transport,
+            )
+        )
+
+    @classmethod
+    def from_env(cls, **overrides: Any) -> "Talqing":
+        """Build a client from `TALQING_API_KEY` and `TALQING_BASE_URL`.
+
+        Anything passed here wins over the environment.
+        """
+        return cls(**_from_env(overrides))
+
+    @property
+    def base_url(self) -> str:
+        return self._t.base_url
+
+    @property
+    def http(self) -> httpx.Client:
+        """The underlying `httpx.Client`, already carrying the base URL and token."""
+        return self._t.http
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        query: Mapping[str, Any] | None = None,
+        body: Mapping[str, Any] | None = None,
+    ) -> Any:
+        """Call a path directly, with this client's credentials and error handling.
+
+        The escape hatch for an endpoint that shipped since this SDK was
+        generated. Everything the document knows about already has a method.
+        """
+        return self._t.request(method, path, query=query, body=body)
+
+    def google_login_url(self) -> str:
+        """Where to send a browser to start Google sign-in."""
+        return _google_login_url(self.base_url)
+
+    def oauth_start_url(self, provider: str, integration_id: str | None = None) -> str:
+        """Where to send a browser to authorize an integration."""
+        return _oauth_start_url(self.base_url, provider, integration_id)
+
+    def close(self) -> None:
+        self._t.close()
+
+    def __enter__(self) -> "Talqing":
+        return self
+
+    def __exit__(
+        self,
+        kind: type[BaseException] | None,
+        error: BaseException | None,
+        trace: TracebackType | None,
+    ) -> None:
+        self.close()
+
+
+class AsyncTalqing(AsyncTalqingApi):
+    """`Talqing`, awaited. See it for the shape; every operation here is a coroutine.
+
+    ```python
+    async with AsyncTalqing.from_env() as talqing:
+        agents = await talqing.agents.list()
+    ```
+
+    The exception is a stream, which is not a coroutine on either client:
+    `async for event in talqing.conversations.events(conversation_id)`.
+    """
+
+    def __init__(
+        self,
+        token: str | None = None,
+        *,
+        base_url: str | None = None,
+        timeout: float | httpx.Timeout = 30.0,
+        headers: Mapping[str, str] | None = None,
+        transport: httpx.AsyncBaseTransport | None = None,
+    ) -> None:
+        super().__init__(
+            AsyncTransport(
+                base_url=_base_url(base_url),
+                token=_token(token),
+                timeout=timeout,
+                headers=headers,
+                transport=transport,
+            )
+        )
+
+    @classmethod
+    def from_env(cls, **overrides: Any) -> "AsyncTalqing":
+        """Build a client from `TALQING_API_KEY` and `TALQING_BASE_URL`."""
+        return cls(**_from_env(overrides))
+
+    @property
+    def base_url(self) -> str:
+        return self._t.base_url
+
+    @property
+    def http(self) -> httpx.AsyncClient:
+        """The underlying `httpx.AsyncClient`, already carrying the base URL and token."""
+        return self._t.http
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        query: Mapping[str, Any] | None = None,
+        body: Mapping[str, Any] | None = None,
+    ) -> Any:
+        """Call a path directly, with this client's credentials and error handling."""
+        return await self._t.request(method, path, query=query, body=body)
+
+    def google_login_url(self) -> str:
+        """Where to send a browser to start Google sign-in."""
+        return _google_login_url(self.base_url)
+
+    def oauth_start_url(self, provider: str, integration_id: str | None = None) -> str:
+        """Where to send a browser to authorize an integration."""
+        return _oauth_start_url(self.base_url, provider, integration_id)
+
+    async def close(self) -> None:
+        await self._t.close()
+
+    async def __aenter__(self) -> "AsyncTalqing":
+        return self
+
+    async def __aexit__(
+        self,
+        kind: type[BaseException] | None,
+        error: BaseException | None,
+        trace: TracebackType | None,
+    ) -> None:
+        await self.close()
+
+
+def paginate(
+    page: Callable[..., Page[T]], *, limit: int = 200, **filters: Any
+) -> Iterator[T]:
+    """Walk every page of a list endpoint.
+
+    ```python
+    for agent in paginate(talqing.agents.list):
+        ...
+    for call in paginate(talqing.calls.list, agent_id=agent_id):
+        ...
+    ```
+
+    One helper rather than a `list_all_*` per endpoint: all 28 list endpoints
+    page the same way, so this does too. Anything else the endpoint filters on
+    is passed straight through.
+    """
+    offset = 0
+    while True:
+        result = page(limit=limit, offset=offset, **filters)
+        yield from result["items"]
+        if not result["has_more"]:
+            return
+        offset += limit
+
+
+async def paginate_async(
+    page: Callable[..., Awaitable[Page[T]]], *, limit: int = 200, **filters: Any
+) -> AsyncIterator[T]:
+    """`paginate`, awaited.
+
+    ```python
+    async for agent in paginate_async(talqing.agents.list):
+        ...
+    ```
+    """
+    offset = 0
+    while True:
+        result = await page(limit=limit, offset=offset, **filters)
+        for item in result["items"]:
+            yield item
+        if not result["has_more"]:
+            return
+        offset += limit

talqing/errors.py

@@ -0,0 +1,32 @@
+"""The one exception this SDK raises."""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+import httpx
+
+
+class TalqingAPIError(Exception):
+    """Every error the API returns, in the one shape it returns them in.
+
+    The wire body is always ``{"detail": {"message", "errors"}}``, so there is
+    nothing to branch on: ``str(exc)`` is the message, ``exc.errors`` lists the
+    per-field problems when the failure had more than one, and ``exc.detail`` is
+    the decoded body for anything else you want off it.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int,
+        detail: Any = None,
+        errors: Optional[list[str]] = None,
+        response: Optional[httpx.Response] = None,
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.detail = detail
+        self.errors = errors or []
+        self.response = response