toktik 0.1.0__tar.gz

toktik-0.1.0/LICENSE

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

toktik-0.1.0/PKG-INFO

@@ -0,0 +1,146 @@
+Metadata-Version: 2.4
+Name: toktik
+Version: 0.1.0
+Summary: Typed Python client for the TokTik Developer API (REST + realtime LIVE events)
+Author: TokTik
+License-Expression: MIT
+Project-URL: Homepage, https://toktikhq.com
+Project-URL: Documentation, https://docs.toktikhq.com/docs/sdks
+Keywords: tiktok,live,realtime,developer-api
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: realtime
+Requires-Dist: websockets<17,>=12; extra == "realtime"
+Provides-Extra: dev
+Requires-Dist: websockets<17,>=12; extra == "dev"
+Requires-Dist: mypy>=1.8; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Dynamic: license-file
+
+# toktik — Python SDK for the TokTik Developer API
+
+Typed Python client for the TokTik Developer API: the full REST data-plane plus a realtime
+(`asyncio`) LIVE-event client. Feature parity with [`@toktikhq/sdk-js`](../sdk-js); the contract source
+of truth is [`@v2/contracts`](../contracts) / the served `GET /openapi.json`.
+
+```python
+from toktik import TokTikClient
+
+client = TokTikClient(api_key="ttk_live_...")
+board = client.rankings.official(board="hourly", region="VN")
+print(board["provenance"])          # the envelope is never stripped
+```
+
+```python
+import asyncio
+from toktik import TokTikClient, EventFrame
+
+async def main():
+    client = TokTikClient(api_key="ttk_live_...")
+    async for frame in await client.live.stream(["@creator"]):
+        if isinstance(frame, EventFrame):
+            print(frame.event, frame.data)          # chat / gift / like / ...
+
+asyncio.run(main())
+```
+
+## Install
+
+```bash
+pip install toktik                # REST only — zero dependencies
+pip install "toktik[realtime]"    # adds `websockets` for the realtime client
+```
+
+The REST client speaks HTTP through the standard library, so the data-plane surface pulls in nothing.
+The realtime client needs a WebSocket implementation; installing the `realtime` extra provides it, or
+you can pass your own transport (`RealtimeStream(connect=...)`).
+
+## Design
+
+- **Provenance is never stripped.** Data methods return the parsed JSON envelope unchanged —
+  `{"data": ..., "provenance": {...}}`. For observed (rather than officially published) data, that
+  context *is* part of the answer. The two documented exceptions match the JS SDK: `exports.download`
+  returns CSV text, and `account.usage` is returned directly (no envelope).
+- **Errors are surfaced, not swallowed.** A non-2xx raises `TokTikApiError` carrying `status`, `code`,
+  `request_id` and helpers (`is_payment_required` for 402, `is_forbidden` for 403, `is_rate_limited`
+  for 429, `retryable`). Distinguishing them is the whole point: 402 means buy credits, 403 means the
+  key lacks the scope, 429 means back off.
+- **Argument names are snake_case, mapped to the server's wire names.** Every route's Fastify schema
+  sets `additionalProperties: false`, so a wrong query key is a hard 400. The mapping is transcribed
+  from the routes, and a CI parity test asserts every documented data-plane path is covered.
+- **The realtime client owns token lifetime, reconnection and resume.** A fresh handshake token is
+  minted per connection (expiry becomes a reconnect, not a dead socket); reconnects use exponential
+  backoff with full jitter; and because the gateway keeps no per-connection memory, subscriptions are
+  re-sent on every open. `queued` / `active` / `offline` / `unavailable` are reported honestly.
+
+## REST surface
+
+| Namespace | Methods | Scope |
+|---|---|---|
+| `client.rankings` | `official(board, region, limit)`, `movers(board, region, limit)`, `history(board, region, limit, cursor, league_tier)`, `regions()`, `games(region)` | `rank:read` |
+| `client.live` | `list_sessions`, `get_session`, `creator_performance`, `stream_token`, `stream` | `live:read` / `live:stream` |
+| `client.creators` | `list`, `get`, `changes`, `analysis`, `following`, `followers` | `creator:read` |
+| `client.content` | `creator_videos`, `video`, `video_comments` | `content:read` |
+| `client.gifters` | `list`, `get`, `for_creator` | `gifter:read` |
+| `client.trends` | `list(region, type)` | `trend:read` |
+| `client.exports` | `list`, `create`, `get`, `download` | `export` |
+| `client.account` | `entitlements`, `usage` | `keys:manage` |
+
+## Realtime
+
+`await client.live.stream(creator_ids)` returns a connected `RealtimeStream` — an async iterator of
+frames:
+
+- `StatusFrame(creator_id, status, room_id, reason)` — subscription lifecycle
+  (`queued`→`active`→…, or `offline`).
+- `EventFrame(event, event_id, creator_id, room_id, sequence, room_state, data, provenance)` — a LIVE
+  event (`chat`, `gift`, `like`, `member`, `roomUser`, `social`, `control`, `envelope`, `goodyBag`, `unknown`).
+- `ErrorFrame(code, message, retryable)` — a server-side subscription error.
+
+`subscribe(id)` / `unsubscribe(id)` change the set mid-stream; `aclose()` (or `async with`) stops for
+good and cancels reconnection.
+
+The token is minted from platform-api; its `wsUrl` points at the API host, which nginx routes to the
+gateway in production. Driving a **local** gateway directly, mint the token yourself and pass the
+gateway URL — see [`examples/realtime_demo.py`](examples/realtime_demo.py).
+
+## Development
+
+```bash
+python -m venv .venv && . .venv/bin/activate
+pip install -e ".[dev]"
+python -m unittest discover -s tests    # 51 tests, no network
+mypy && ruff check src tests
+```
+
+The OpenAPI parity snapshot is generated from `@v2/contracts` (regenerated + diffed in CI):
+
+```bash
+npm run build --workspace @v2/contracts
+node packages/sdk-python/scripts/gen_openapi_snapshot.mjs
+```
+
+## Publishing
+
+Releases are tag-driven through `.github/workflows/sdk-release.yml`:
+
+```bash
+git tag sdk-python-v0.1.0
+git push origin sdk-python-v0.1.0
+```
+
+The release job builds and checks both the sdist and wheel, installs the wheel into a clean virtual
+environment, and publishes with PyPI Trusted Publishing. The PyPI project must trust this repository,
+that workflow, and the `pypi` GitHub environment before the first release.
+
+## Known scope limits
+
+- **Response bodies are typed `dict` (`JsonDict`), not generated models.** The shapes live in
+  `@v2/contracts` (TypeScript); generating Pydantic models from them was deliberately deferred to
+  avoid silent drift. Method arguments and realtime frames *are* typed.
+- **Sync REST only.** An `asyncio` REST client is not yet provided; the realtime client is async, and
+  it mints its token off the event loop via `asyncio.to_thread`.

toktik-0.1.0/README.md

@@ -0,0 +1,123 @@
+# toktik — Python SDK for the TokTik Developer API
+
+Typed Python client for the TokTik Developer API: the full REST data-plane plus a realtime
+(`asyncio`) LIVE-event client. Feature parity with [`@toktikhq/sdk-js`](../sdk-js); the contract source
+of truth is [`@v2/contracts`](../contracts) / the served `GET /openapi.json`.
+
+```python
+from toktik import TokTikClient
+
+client = TokTikClient(api_key="ttk_live_...")
+board = client.rankings.official(board="hourly", region="VN")
+print(board["provenance"])          # the envelope is never stripped
+```
+
+```python
+import asyncio
+from toktik import TokTikClient, EventFrame
+
+async def main():
+    client = TokTikClient(api_key="ttk_live_...")
+    async for frame in await client.live.stream(["@creator"]):
+        if isinstance(frame, EventFrame):
+            print(frame.event, frame.data)          # chat / gift / like / ...
+
+asyncio.run(main())
+```
+
+## Install
+
+```bash
+pip install toktik                # REST only — zero dependencies
+pip install "toktik[realtime]"    # adds `websockets` for the realtime client
+```
+
+The REST client speaks HTTP through the standard library, so the data-plane surface pulls in nothing.
+The realtime client needs a WebSocket implementation; installing the `realtime` extra provides it, or
+you can pass your own transport (`RealtimeStream(connect=...)`).
+
+## Design
+
+- **Provenance is never stripped.** Data methods return the parsed JSON envelope unchanged —
+  `{"data": ..., "provenance": {...}}`. For observed (rather than officially published) data, that
+  context *is* part of the answer. The two documented exceptions match the JS SDK: `exports.download`
+  returns CSV text, and `account.usage` is returned directly (no envelope).
+- **Errors are surfaced, not swallowed.** A non-2xx raises `TokTikApiError` carrying `status`, `code`,
+  `request_id` and helpers (`is_payment_required` for 402, `is_forbidden` for 403, `is_rate_limited`
+  for 429, `retryable`). Distinguishing them is the whole point: 402 means buy credits, 403 means the
+  key lacks the scope, 429 means back off.
+- **Argument names are snake_case, mapped to the server's wire names.** Every route's Fastify schema
+  sets `additionalProperties: false`, so a wrong query key is a hard 400. The mapping is transcribed
+  from the routes, and a CI parity test asserts every documented data-plane path is covered.
+- **The realtime client owns token lifetime, reconnection and resume.** A fresh handshake token is
+  minted per connection (expiry becomes a reconnect, not a dead socket); reconnects use exponential
+  backoff with full jitter; and because the gateway keeps no per-connection memory, subscriptions are
+  re-sent on every open. `queued` / `active` / `offline` / `unavailable` are reported honestly.
+
+## REST surface
+
+| Namespace | Methods | Scope |
+|---|---|---|
+| `client.rankings` | `official(board, region, limit)`, `movers(board, region, limit)`, `history(board, region, limit, cursor, league_tier)`, `regions()`, `games(region)` | `rank:read` |
+| `client.live` | `list_sessions`, `get_session`, `creator_performance`, `stream_token`, `stream` | `live:read` / `live:stream` |
+| `client.creators` | `list`, `get`, `changes`, `analysis`, `following`, `followers` | `creator:read` |
+| `client.content` | `creator_videos`, `video`, `video_comments` | `content:read` |
+| `client.gifters` | `list`, `get`, `for_creator` | `gifter:read` |
+| `client.trends` | `list(region, type)` | `trend:read` |
+| `client.exports` | `list`, `create`, `get`, `download` | `export` |
+| `client.account` | `entitlements`, `usage` | `keys:manage` |
+
+## Realtime
+
+`await client.live.stream(creator_ids)` returns a connected `RealtimeStream` — an async iterator of
+frames:
+
+- `StatusFrame(creator_id, status, room_id, reason)` — subscription lifecycle
+  (`queued`→`active`→…, or `offline`).
+- `EventFrame(event, event_id, creator_id, room_id, sequence, room_state, data, provenance)` — a LIVE
+  event (`chat`, `gift`, `like`, `member`, `roomUser`, `social`, `control`, `envelope`, `goodyBag`, `unknown`).
+- `ErrorFrame(code, message, retryable)` — a server-side subscription error.
+
+`subscribe(id)` / `unsubscribe(id)` change the set mid-stream; `aclose()` (or `async with`) stops for
+good and cancels reconnection.
+
+The token is minted from platform-api; its `wsUrl` points at the API host, which nginx routes to the
+gateway in production. Driving a **local** gateway directly, mint the token yourself and pass the
+gateway URL — see [`examples/realtime_demo.py`](examples/realtime_demo.py).
+
+## Development
+
+```bash
+python -m venv .venv && . .venv/bin/activate
+pip install -e ".[dev]"
+python -m unittest discover -s tests    # 51 tests, no network
+mypy && ruff check src tests
+```
+
+The OpenAPI parity snapshot is generated from `@v2/contracts` (regenerated + diffed in CI):
+
+```bash
+npm run build --workspace @v2/contracts
+node packages/sdk-python/scripts/gen_openapi_snapshot.mjs
+```
+
+## Publishing
+
+Releases are tag-driven through `.github/workflows/sdk-release.yml`:
+
+```bash
+git tag sdk-python-v0.1.0
+git push origin sdk-python-v0.1.0
+```
+
+The release job builds and checks both the sdist and wheel, installs the wheel into a clean virtual
+environment, and publishes with PyPI Trusted Publishing. The PyPI project must trust this repository,
+that workflow, and the `pypi` GitHub environment before the first release.
+
+## Known scope limits
+
+- **Response bodies are typed `dict` (`JsonDict`), not generated models.** The shapes live in
+  `@v2/contracts` (TypeScript); generating Pydantic models from them was deliberately deferred to
+  avoid silent drift. Method arguments and realtime frames *are* typed.
+- **Sync REST only.** An `asyncio` REST client is not yet provided; the realtime client is async, and
+  it mints its token off the event loop via `asyncio.to_thread`.

toktik-0.1.0/pyproject.toml

@@ -0,0 +1,61 @@
+[build-system]
+requires = ["setuptools>=77", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "toktik"
+version = "0.1.0"
+description = "Typed Python client for the TokTik Developer API (REST + realtime LIVE events)"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "TokTik" }]
+keywords = ["tiktok", "live", "realtime", "developer-api"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Typing :: Typed",
+]
+# The REST client is dependency-free (stdlib urllib). The realtime client needs a WebSocket
+# implementation; it is an OPTIONAL dependency so `import toktik` and every REST call work without it.
+dependencies = []
+
+[project.optional-dependencies]
+realtime = ["websockets>=12,<17"]
+dev = ["websockets>=12,<17", "mypy>=1.8", "ruff>=0.5"]
+
+[project.urls]
+Homepage = "https://toktikhq.com"
+Documentation = "https://docs.toktikhq.com/docs/sdks"
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+toktik = ["py.typed"]
+
+[tool.mypy]
+# Runtime supports 3.9 (see requires-python); the type-checker baseline is 3.10 because current mypy
+# refuses to target 3.9. Checking against 3.10 still validates the 3.9 code (all annotations are
+# stringised via `from __future__ import annotations`).
+python_version = "3.10"
+strict = true
+# The data methods return parsed JSON, which is genuinely dynamic (`Any`). The `JsonDict` return
+# annotations document intent; warn_return_any would only force noisy casts around every call.
+warn_return_any = false
+files = ["src/toktik"]
+
+[tool.ruff]
+line-length = 110
+target-version = "py39"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+# E/F/I/B catch real defects. The UP (pyupgrade) family is intentionally omitted: the package
+# supports Python 3.9, and auto-rewriting to PEP 604/585 forms risks runtime `X | None` aliases that
+# only work on 3.10+. `Optional`/`Dict`/`List` are correct and clear here.
+select = ["E", "F", "I", "B"]

toktik-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

toktik-0.1.0/src/toktik/__init__.py

@@ -0,0 +1,30 @@
+"""Typed Python client for the TokTik Developer API (REST + realtime LIVE events)."""
+
+from ._http import HttpTransport, build_query
+from ._version import __version__
+from .client import TokTikClient
+from .errors import TokTikApiError
+from .realtime import (
+    ErrorFrame,
+    EventFrame,
+    RealtimeError,
+    RealtimeStream,
+    ServerFrame,
+    StatusFrame,
+    normalize_creator_id,
+)
+
+__all__ = [
+    "TokTikClient",
+    "TokTikApiError",
+    "HttpTransport",
+    "build_query",
+    "RealtimeStream",
+    "StatusFrame",
+    "EventFrame",
+    "ErrorFrame",
+    "ServerFrame",
+    "RealtimeError",
+    "normalize_creator_id",
+    "__version__",
+]

toktik-0.1.0/src/toktik/_http.py

@@ -0,0 +1,151 @@
+"""Shared request plumbing. Deliberately has no retries, caching, or credential storage — the same
+stance as ``@toktikhq/sdk-js``'s ``HttpTransport``.
+
+The REST client is intentionally dependency-free: it speaks HTTP through the standard library
+(``urllib.request``) so ``pip install toktik`` pulls in nothing for the data-plane surface. A custom
+``transport`` seam is exposed for tests and for callers who would rather route through ``httpx`` or a
+signed proxy.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import Any, Callable, Mapping, Optional, Tuple
+from urllib.error import HTTPError
+from urllib.parse import urlencode
+from urllib.request import Request, urlopen
+
+from .errors import TokTikApiError
+
+DEFAULT_BASE_URL = "https://api.toktikhq.com"
+
+# A transport turns a request into ``(status, body_text)``. Any non-2xx status is reported here, not
+# raised — this layer, not the transport, owns turning a status into ``TokTikApiError``.
+Transport = Callable[[str, str, Mapping[str, str], Optional[bytes]], Tuple[int, str]]
+
+
+def build_query(parameters: Optional[Mapping[str, Any]] = None) -> str:
+    """Serialise query parameters, dropping ``None``/empty and expanding lists into repeats.
+
+    Repeatable filters (e.g. ``?type=a&type=b``) must not collapse into ``"a,b"`` — mirrors the JS
+    SDK's ``buildQuery``.
+    """
+    if not parameters:
+        return ""
+    pairs: list[tuple[str, str]] = []
+    for key, value in parameters.items():
+        if value is None or value == "":
+            continue
+        if isinstance(value, (list, tuple)):
+            for item in value:
+                if item is None or item == "":
+                    continue
+                pairs.append((key, _stringify(item)))
+        else:
+            pairs.append((key, _stringify(value)))
+    if not pairs:
+        return ""
+    return "?" + urlencode(pairs)
+
+
+def _stringify(value: Any) -> str:
+    if isinstance(value, bool):
+        # Match JS `String(true)` -> "true", not Python's "True".
+        return "true" if value else "false"
+    return str(value)
+
+
+def _safe_json(raw: str) -> Any:
+    try:
+        return json.loads(raw)
+    except (ValueError, TypeError):
+        return None
+
+
+@dataclass
+class _StdlibTransport:
+    """Default transport over ``urllib.request``. Kept tiny and swappable."""
+
+    timeout: float = 30.0
+
+    def __call__(
+        self,
+        method: str,
+        url: str,
+        headers: Mapping[str, str],
+        body: Optional[bytes],
+    ) -> Tuple[int, str]:
+        request = Request(url, data=body, method=method)
+        for name, value in headers.items():
+            request.add_header(name, value)
+        try:
+            with urlopen(request, timeout=self.timeout) as response:  # noqa: S310 - fixed https host
+                return response.status, response.read().decode("utf-8")
+        except HTTPError as error:  # noqa: PERF203 - the error path is not hot
+            # A 4xx/5xx is an ordinary answer to us, not an exception: read the JSON error envelope.
+            raw = error.read().decode("utf-8", errors="replace") if error.fp is not None else ""
+            return error.code, raw
+
+
+class HttpTransport:
+    def __init__(
+        self,
+        api_key: str,
+        base_url: Optional[str] = None,
+        transport: Optional[Transport] = None,
+        timeout: float = 30.0,
+    ) -> None:
+        api_key = (api_key or "").strip()
+        if not api_key:
+            raise ValueError("api_key is required")
+        self._api_key = api_key
+        self.base_url = (base_url or DEFAULT_BASE_URL).rstrip("/")
+        self._transport: Transport = transport or _StdlibTransport(timeout=timeout)
+
+    def get(self, path: str, parameters: Optional[Mapping[str, Any]] = None) -> Any:
+        return self._request("GET", f"{path}{build_query(parameters)}")
+
+    def get_text(self, path: str, parameters: Optional[Mapping[str, Any]] = None) -> str:
+        """For endpoints that answer with something other than JSON (today: the CSV export download).
+
+        Errors are still parsed as JSON, because a failure is always the JSON error envelope.
+        """
+        raw = self._request("GET", f"{path}{build_query(parameters)}", response_kind="text")
+        return raw
+
+    def post(self, path: str, body: Any = None) -> Any:
+        return self._request("POST", path, body=body)
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        body: Any = None,
+        response_kind: str = "json",
+    ) -> Any:
+        headers = {
+            "authorization": f"Bearer {self._api_key}",
+            "accept": "application/json",
+        }
+        encoded: Optional[bytes] = None
+        if body is not None:
+            headers["content-type"] = "application/json"
+            encoded = json.dumps(body).encode("utf-8")
+        status, raw = self._transport(method, f"{self.base_url}{path}", headers, encoded)
+        if not 200 <= status < 300:
+            envelope = _safe_json(raw) if raw else None
+            code = message = request_id = None
+            if isinstance(envelope, dict):
+                code = envelope.get("code")
+                message = envelope.get("message")
+                request_id = envelope.get("requestId")
+            raise TokTikApiError(
+                status,
+                code,
+                request_id,
+                message or f"TokTik API request failed ({status}).",
+            )
+        if response_kind == "text":
+            return raw
+        return _safe_json(raw) if raw else None

toktik-0.1.0/src/toktik/_version.py

@@ -0,0 +1,4 @@
+"""Single source of the package version. Kept in step with ``@toktikhq/sdk-js`` on feature parity,
+not on an identical number — the two ship independently."""
+
+__version__ = "0.1.0"

toktik-0.1.0/src/toktik/client.py

@@ -0,0 +1,103 @@
+"""Typed client for the TokTik Developer API.
+
+Example::
+
+    from toktik import TokTikClient
+
+    client = TokTikClient(api_key="ttk_live_...")
+    board = client.rankings.official(board="hourly", region="VN")
+    print(board["provenance"])
+
+    # realtime (needs the `realtime` extra):
+    async for frame in await client.live.stream(["@creator"]):
+        if frame.type == "event":
+            print(frame.event, frame.data)
+
+Most data methods return the provenance envelope **unchanged** — ``data`` alongside the
+``provenance`` block describing how fresh the answer is and how it was obtained. The SDK never
+strips it. ``exports.download`` (CSV text) and ``account.usage`` are the documented exceptions.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any, List, Optional, Tuple
+
+from ._http import HttpTransport, Transport
+from .realtime import RealtimeStream, WsConnect
+from .resources import (
+    AccountResource,
+    ContentResource,
+    CreatorsResource,
+    ExportsResource,
+    GiftersResource,
+    LiveResource,
+    RankingsResource,
+    TrendsResource,
+)
+
+
+class _LiveNamespace(LiveResource):
+    """``LiveResource`` plus ``stream()`` — the realtime entry point, which needs the client to mint
+    and refresh handshake tokens off the event loop."""
+
+    def __init__(self, http: HttpTransport) -> None:
+        super().__init__(http)
+
+    async def _mint(self) -> Tuple[str, str]:
+        # ``stream_token`` is a blocking stdlib HTTP call; keep it off the event loop.
+        minted: Any = await asyncio.to_thread(self.stream_token)
+        return minted["token"], minted["wsUrl"]
+
+    async def stream(
+        self,
+        creator_ids: List[str],
+        *,
+        connect: Optional[WsConnect] = None,
+        max_reconnect_attempts: float = float("inf"),
+        base_reconnect_delay: float = 0.5,
+        max_reconnect_delay: float = 30.0,
+        on_reconnect: Optional[Any] = None,
+        on_error: Optional[Any] = None,
+    ) -> RealtimeStream:
+        """Open a realtime stream. Mints its own handshake token and keeps it fresh across reconnects.
+
+        Returns a connected :class:`~toktik.realtime.RealtimeStream` that is an async iterator of
+        status/event/error frames.
+        """
+        stream = RealtimeStream(
+            self._mint,
+            connect=connect,
+            max_reconnect_attempts=max_reconnect_attempts,
+            base_reconnect_delay=base_reconnect_delay,
+            max_reconnect_delay=max_reconnect_delay,
+            on_reconnect=on_reconnect,
+            on_error=on_error,
+        )
+        await stream.connect(creator_ids)
+        return stream
+
+
+class TokTikClient:
+    def __init__(
+        self,
+        api_key: str,
+        base_url: Optional[str] = None,
+        transport: Optional[Transport] = None,
+        timeout: float = 30.0,
+    ) -> None:
+        self._http = HttpTransport(
+            api_key=api_key, base_url=base_url, transport=transport, timeout=timeout
+        )
+        self.live = _LiveNamespace(self._http)
+        self.rankings = RankingsResource(self._http)
+        self.creators = CreatorsResource(self._http)
+        self.content = ContentResource(self._http)
+        self.gifters = GiftersResource(self._http)
+        self.trends = TrendsResource(self._http)
+        self.exports = ExportsResource(self._http)
+        self.account = AccountResource(self._http)
+
+    @property
+    def base_url(self) -> str:
+        return self._http.base_url