ninjachat 0.1.0__tar.gz

ninjachat-0.1.0/LICENSE

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

ninjachat-0.1.0/PKG-INFO

@@ -0,0 +1,73 @@
+Metadata-Version: 2.4
+Name: ninjachat
+Version: 0.1.0
+Summary: Official Python SDK for the NinjaChat API — one typed client for chat, responses, media, routing, usage, and webhooks.
+Author: Helium Technologies, Inc.
+License-Expression: MIT
+Project-URL: Documentation, https://docs.ninjachat.ai
+Project-URL: OpenAPI spec, https://www.ninjachat.ai/api/v1/openapi
+Project-URL: Source, https://github.com/bloon-ai/ninjachat-sdk/tree/main/packages/python
+Project-URL: Issues, https://github.com/bloon-ai/ninjachat-sdk/issues
+Keywords: ninjachat,ai,llm,openai-compatible,sdk
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.28
+Requires-Dist: typing-extensions>=4.8; python_version < "3.11"
+Dynamic: license-file
+
+# NinjaChat Python SDK
+
+Typed client for the clean NinjaChat API v1.
+
+```bash
+pip install ninjachat
+```
+
+```python
+import os
+from ninjachat import NinjaChat
+
+client = NinjaChat(api_key=os.environ["NINJACHAT_API_KEY"])
+response = client.responses.create(
+    model="ninja/auto",
+    input="Write one sentence about clean APIs.",
+    max_output_tokens=64,
+    routing={"strategy": "balanced", "data_policy": "no_training"},
+)
+print(response["output_text"], response["cost_usd"], response["request_id"])
+```
+
+Ordered fallbacks and provider constraints are explicit:
+
+```python
+completion = client.chat.completions.create(
+    models=["gpt-5", "claude-sonnet-4"],
+    messages=[{"role": "user", "content": "Hello"}],
+    max_completion_tokens=100,
+    routing={"strategy": "latency", "allow_fallbacks": True, "caching": "auto", "max_cost_usd": 0.10},
+)
+```
+
+Streams return iterators of typed-shape dictionaries:
+
+```python
+for event in client.responses.create(model="ninja/auto", input="Hello", stream=True):
+    if event.get("type") == "response.output_text.delta":
+        print(event.get("delta", ""), end="")
+```
+
+Models and prices come from `client.models.list()`. Images use `client.images.generate()`, videos use `client.videos.generate()` and `client.videos.wait_for()`, and account observability is available through `client.usage()`, `client.balance()`, and `client.requests.get()`.
+
+Signed webhooks replace video polling and fire spend alerts: `client.webhooks.create(...)` or the [console](https://www.ninjachat.ai/developers/keys#webhooks). Verify deliveries with `verify_webhook_signature`.
+
+The base URL is `https://www.ninjachat.ai/api/v1`. Chat and Responses are billed by actual token usage. See [docs.ninjachat.ai](https://docs.ninjachat.ai).

ninjachat-0.1.0/README.md

@@ -0,0 +1,46 @@
+# NinjaChat Python SDK
+
+Typed client for the clean NinjaChat API v1.
+
+```bash
+pip install ninjachat
+```
+
+```python
+import os
+from ninjachat import NinjaChat
+
+client = NinjaChat(api_key=os.environ["NINJACHAT_API_KEY"])
+response = client.responses.create(
+    model="ninja/auto",
+    input="Write one sentence about clean APIs.",
+    max_output_tokens=64,
+    routing={"strategy": "balanced", "data_policy": "no_training"},
+)
+print(response["output_text"], response["cost_usd"], response["request_id"])
+```
+
+Ordered fallbacks and provider constraints are explicit:
+
+```python
+completion = client.chat.completions.create(
+    models=["gpt-5", "claude-sonnet-4"],
+    messages=[{"role": "user", "content": "Hello"}],
+    max_completion_tokens=100,
+    routing={"strategy": "latency", "allow_fallbacks": True, "caching": "auto", "max_cost_usd": 0.10},
+)
+```
+
+Streams return iterators of typed-shape dictionaries:
+
+```python
+for event in client.responses.create(model="ninja/auto", input="Hello", stream=True):
+    if event.get("type") == "response.output_text.delta":
+        print(event.get("delta", ""), end="")
+```
+
+Models and prices come from `client.models.list()`. Images use `client.images.generate()`, videos use `client.videos.generate()` and `client.videos.wait_for()`, and account observability is available through `client.usage()`, `client.balance()`, and `client.requests.get()`.
+
+Signed webhooks replace video polling and fire spend alerts: `client.webhooks.create(...)` or the [console](https://www.ninjachat.ai/developers/keys#webhooks). Verify deliveries with `verify_webhook_signature`.
+
+The base URL is `https://www.ninjachat.ai/api/v1`. Chat and Responses are billed by actual token usage. See [docs.ninjachat.ai](https://docs.ninjachat.ai).

ninjachat-0.1.0/ninjachat/__init__.py

@@ -0,0 +1,20 @@
+"""ninjachat — Python SDK for the NinjaChat v1 API.
+
+Docs: https://docs.ninjachat.ai
+OpenAPI spec: https://www.ninjachat.ai/api/v1/openapi
+"""
+
+from .client import DEFAULT_BASE_URL, NinjaChat
+from .contract import CONTRACT_SHA256
+from .errors import NinjaChatError
+from .webhooks import verify_webhook_signature
+
+__all__ = [
+    "NinjaChat",
+    "NinjaChatError",
+    "verify_webhook_signature",
+    "DEFAULT_BASE_URL",
+    "CONTRACT_SHA256",
+]
+
+__version__ = "0.1.0"

ninjachat-0.1.0/ninjachat/client.py

@@ -0,0 +1,298 @@
+"""Synchronous, typed NinjaChat API v1 client."""
+
+from __future__ import annotations
+
+import json as _json
+import random
+import time
+import uuid
+from typing import Any, Dict, Iterator, List, Optional, Union
+from urllib.parse import quote
+
+import requests as http_requests
+
+try:
+    from typing import Unpack
+except ImportError:  # Python 3.9-3.10
+    from typing_extensions import Unpack
+
+from .errors import NinjaChatError
+from .types import ChatCompletionParams, ImageGenerateParams, ResponseCreateParams, SearchParams, VideoGenerateParams
+
+DEFAULT_BASE_URL = "https://www.ninjachat.ai/api/v1"
+DEFAULT_MAX_RETRIES = 2
+MAX_BACKOFF_SECONDS = 30.0
+RETRIABLE_STATUSES = {429, 500, 502, 503, 504}
+
+
+def _retry_delay(response: Optional[http_requests.Response], attempt: int) -> float:
+    if response is not None:
+        retry_after = response.headers.get("retry-after")
+        if retry_after:
+            try:
+                return min(max(float(retry_after), 0.0), MAX_BACKOFF_SECONDS)
+            except ValueError:
+                pass
+    base = 0.5 * (2**attempt)
+    return min(base + random.random() * base, MAX_BACKOFF_SECONDS)
+
+
+def _iterate_sse(response: http_requests.Response) -> Iterator[Dict[str, Any]]:
+    try:
+        for raw in response.iter_lines(decode_unicode=True):
+            if not raw or not raw.startswith("data:"):
+                continue
+            data = raw[5:].lstrip()
+            if data == "[DONE]":
+                return
+            try:
+                event = _json.loads(data)
+            except ValueError:
+                continue
+            if not isinstance(event, dict):
+                continue
+            nested = event.get("error") if isinstance(event.get("error"), dict) else None
+            if nested is not None or event.get("type") == "error":
+                error = nested or event
+                raise NinjaChatError(
+                    str(error.get("message") or "Stream failed."),
+                    status=response.status_code,
+                    code=str(error.get("code") or "stream_error"),
+                    type=error.get("type"),
+                    body=event,
+                )
+            yield event
+    finally:
+        response.close()
+
+
+class NinjaChat:
+    """Client for the canonical NinjaChat API v1 surface."""
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        *,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        timeout: float = 120.0,
+        session: Optional[http_requests.Session] = None,
+    ) -> None:
+        if not api_key:
+            raise NinjaChatError(
+                "Missing api_key. Create one at https://www.ninjachat.ai/developers/keys",
+                code="missing_api_key",
+            )
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.max_retries = max_retries
+        self.timeout = timeout
+        self._session = session or http_requests.Session()
+        self.responses = _Responses(self)
+        self.chat = _Chat(self)
+        self.models = _Models(self)
+        self.images = _Images(self)
+        self.videos = _Videos(self)
+        self.search = _Search(self)
+        self.requests = _Requests(self)
+        self.webhooks = _Webhooks(self)
+
+    def balance(self) -> Dict[str, Any]:
+        return self._request("GET", "/balance", idempotent_method=True)
+
+    def usage(self, period: str = "7d") -> Dict[str, Any]:
+        return self._request("GET", "/usage", params={"period": period}, idempotent_method=True)
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Optional[Dict[str, Any]] = None,
+        params: Optional[Dict[str, str]] = None,
+        supports_idempotency: bool = False,
+        idempotent_method: bool = False,
+        idempotency_key: Optional[str] = None,
+        max_retries: Optional[int] = None,
+        stream: bool = False,
+        timeout: Optional[float] = None,
+    ) -> Any:
+        retries = self.max_retries if max_retries is None else max_retries
+        if supports_idempotency and idempotency_key is None and retries > 0:
+            idempotency_key = str(uuid.uuid4())
+        retriable = idempotent_method or idempotency_key is not None
+        attempts = retries + 1 if retriable else 1
+        headers = {
+            "Authorization": f"Bearer {self.api_key}",
+            "Accept": "text/event-stream" if stream else "application/json",
+        }
+        if idempotency_key:
+            headers["Idempotency-Key"] = idempotency_key
+        url = self.base_url + path
+        last_error: Optional[NinjaChatError] = None
+        for attempt in range(attempts):
+            try:
+                response = self._session.request(
+                    method, url, json=json, params=params, headers=headers,
+                    stream=stream, timeout=timeout or self.timeout,
+                )
+            except http_requests.RequestException as exc:
+                last_error = NinjaChatError(f"Network error: {exc}", code="network_error")
+                if attempt == attempts - 1:
+                    raise last_error from exc
+                time.sleep(_retry_delay(None, attempt))
+                continue
+            if response.ok:
+                return response if stream else response.json()
+            try:
+                body = response.json()
+            except ValueError:
+                body = None
+            error = NinjaChatError.from_response(response.status_code, body, response.headers.get("x-request-id"))
+            last_error = error
+            in_flight = response.status_code == 409 and error.code == "request_in_flight" and idempotency_key is not None
+            if not (retriable and attempt < attempts - 1 and (response.status_code in RETRIABLE_STATUSES or in_flight)):
+                raise error
+            time.sleep(_retry_delay(response, attempt))
+        raise last_error or NinjaChatError("Request failed.")
+
+
+class _Responses:
+    def __init__(self, client: NinjaChat) -> None:
+        self._client = client
+
+    def create(
+        self, *, idempotency_key: Optional[str] = None, max_retries: Optional[int] = None,
+        **params: Unpack[ResponseCreateParams],
+    ) -> Union[Dict[str, Any], Iterator[Dict[str, Any]]]:
+        response = self._client._request(
+            "POST", "/responses", json=dict(params), supports_idempotency=True,
+            idempotency_key=idempotency_key, max_retries=max_retries,
+            stream=bool(params.get("stream")),
+        )
+        return _iterate_sse(response) if params.get("stream") else response
+
+
+class _Chat:
+    def __init__(self, client: NinjaChat) -> None:
+        self.completions = _ChatCompletions(client)
+
+
+class _ChatCompletions:
+    def __init__(self, client: NinjaChat) -> None:
+        self._client = client
+
+    def create(
+        self, *, idempotency_key: Optional[str] = None, max_retries: Optional[int] = None,
+        **params: Unpack[ChatCompletionParams],
+    ) -> Union[Dict[str, Any], Iterator[Dict[str, Any]]]:
+        response = self._client._request(
+            "POST", "/chat/completions", json=dict(params), supports_idempotency=True,
+            idempotency_key=idempotency_key, max_retries=max_retries,
+            stream=bool(params.get("stream")),
+        )
+        return _iterate_sse(response) if params.get("stream") else response
+
+
+class _Models:
+    def __init__(self, client: NinjaChat) -> None:
+        self._client = client
+
+    def list(self) -> Dict[str, Any]:
+        return self._client._request("GET", "/models", idempotent_method=True)
+
+    def retrieve(self, model_id: str) -> Dict[str, Any]:
+        return self._client._request("GET", f"/models/{quote(model_id, safe='')}", idempotent_method=True)
+
+
+class _Images:
+    def __init__(self, client: NinjaChat) -> None:
+        self._client = client
+
+    def generate(
+        self, *, idempotency_key: Optional[str] = None, max_retries: Optional[int] = None,
+        **params: Unpack[ImageGenerateParams],
+    ) -> Dict[str, Any]:
+        return self._client._request(
+            "POST", "/images/generations", json=dict(params), supports_idempotency=True,
+            idempotency_key=idempotency_key, max_retries=max_retries, timeout=300.0,
+        )
+
+
+class _Videos:
+    def __init__(self, client: NinjaChat) -> None:
+        self._client = client
+
+    def generate(
+        self, *, idempotency_key: Optional[str] = None, max_retries: Optional[int] = None,
+        **params: Unpack[VideoGenerateParams],
+    ) -> Dict[str, Any]:
+        return self._client._request(
+            "POST", "/videos", json=dict(params), supports_idempotency=True,
+            idempotency_key=idempotency_key, max_retries=max_retries, timeout=300.0,
+        )
+
+    def retrieve(self, video_id: str) -> Dict[str, Any]:
+        return self._client._request("GET", f"/videos/{quote(video_id, safe='')}", idempotent_method=True)
+
+    def wait_for(self, video_id: str, *, poll_seconds: float = 5.0, timeout_seconds: float = 600.0) -> Dict[str, Any]:
+        deadline = time.monotonic() + timeout_seconds
+        while True:
+            result = self.retrieve(video_id)
+            if result.get("status") == "completed":
+                return result
+            if result.get("status") == "failed":
+                raise NinjaChatError(str(result.get("error") or "Video generation failed."), status=200, code="generation_failed", request_id=video_id, body=result)
+            if time.monotonic() + poll_seconds > deadline:
+                raise NinjaChatError(f"Timed out waiting for video job {video_id}.", code="poll_timeout", request_id=video_id)
+            time.sleep(poll_seconds)
+
+
+class _Search:
+    def __init__(self, client: NinjaChat) -> None:
+        self._client = client
+
+    def query(
+        self, *, idempotency_key: Optional[str] = None, max_retries: Optional[int] = None,
+        **params: Unpack[SearchParams],
+    ) -> Dict[str, Any]:
+        return self._client._request(
+            "POST", "/search", json=dict(params), supports_idempotency=True,
+            idempotency_key=idempotency_key, max_retries=max_retries,
+        )
+
+
+class _Requests:
+    def __init__(self, client: NinjaChat) -> None:
+        self._client = client
+
+    def get(self, request_id: str) -> Dict[str, Any]:
+        return self._client._request("GET", f"/requests/{quote(request_id, safe='')}", idempotent_method=True)
+
+
+class _Webhooks:
+    def __init__(self, client: NinjaChat) -> None:
+        self._client = client
+
+    def list(self) -> List[Dict[str, Any]]:
+        return self._client._request("GET", "/webhooks", idempotent_method=True)["endpoints"]
+
+    def create(self, *, url: str, events: Optional[List[str]] = None) -> Dict[str, Any]:
+        body: Dict[str, Any] = {"url": url}
+        if events is not None:
+            body["events"] = events
+        return self._client._request("POST", "/webhooks", json=body, max_retries=0)
+
+    def delete(self, endpoint_id: str) -> Dict[str, Any]:
+        return self._client._request("DELETE", "/webhooks", params={"id": endpoint_id}, idempotent_method=True)
+
+    def list_deliveries(self, *, endpoint_id: Optional[str] = None, limit: Optional[int] = None) -> List[Dict[str, Any]]:
+        params: Dict[str, str] = {}
+        if endpoint_id is not None:
+            params["endpoint_id"] = endpoint_id
+        if limit is not None:
+            params["limit"] = str(limit)
+        return self._client._request("GET", "/webhooks/deliveries", params=params, idempotent_method=True)["deliveries"]
+
+    def test(self, endpoint_id: str) -> Dict[str, Any]:
+        return self._client._request("POST", "/webhooks/test", json={"endpoint_id": endpoint_id}, max_retries=0)

ninjachat-0.1.0/ninjachat/contract.py

@@ -0,0 +1,3 @@
+"""Generated NinjaChat API v1 contract identity. Do not edit."""
+
+CONTRACT_SHA256 = "bcf3aa3d26a7927cecba74a931de447808ace44b3998e140635af714c4192815"

ninjachat-0.1.0/ninjachat/errors.py

@@ -0,0 +1,67 @@
+"""Typed errors for the NinjaChat SDK.
+
+The API returns an OpenAI-compatible envelope::
+
+    {"error": {"message", "type", "code", "param"}}
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+
+class NinjaChatError(Exception):
+    """Raised for every non-2xx API response, network failure, or SDK-level failure.
+
+    Attributes:
+        status: HTTP status (0 for network/timeout errors raised before a response).
+        code: Machine-readable code (e.g. ``insufficient_credits``, ``rate_limit_exceeded``).
+        request_id: The X-Request-ID / request_id, when the server produced one.
+        type: OpenAI-style error type (e.g. ``invalid_request_error``).
+        param: The offending parameter, when reported.
+        body: The full parsed error body (extra fields: balance, retry_after, ...).
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status: int = 0,
+        code: str = "unknown",
+        request_id: Optional[str] = None,
+        type: Optional[str] = None,
+        param: Optional[str] = None,
+        body: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status = status
+        self.code = code
+        self.request_id = request_id
+        self.type = type
+        self.param = param
+        self.body = body or {}
+
+    @classmethod
+    def from_response(
+        cls, status: int, body: Any, header_request_id: Optional[str] = None
+    ) -> "NinjaChatError":
+        b: Dict[str, Any] = body if isinstance(body, dict) else {}
+        nested = b.get("error") if isinstance(b.get("error"), dict) else {}
+        message = nested.get("message") or f"HTTP {status}"
+        code = nested.get("code") or f"http_{status}"
+        return cls(
+            str(message),
+            status=status,
+            code=str(code),
+            request_id=header_request_id,
+            type=nested.get("type"),
+            param=nested.get("param"),
+            body=b,
+        )
+
+    def __repr__(self) -> str:  # pragma: no cover - cosmetic
+        return (
+            f"NinjaChatError(status={self.status}, code={self.code!r}, "
+            f"request_id={self.request_id!r}, message={self.message!r})"
+        )

ninjachat-0.1.0/ninjachat/py.typed

@@ -0,0 +1 @@
+

ninjachat-0.1.0/ninjachat/types.py

@@ -0,0 +1,105 @@
+"""Typed request objects for NinjaChat API v1."""
+
+from typing import Any, Dict, List, Literal, Union
+
+try:
+    from typing import NotRequired, Required, TypedDict
+except ImportError:  # Python 3.9-3.10
+    from typing_extensions import NotRequired, Required, TypedDict
+
+
+class ProviderPolicy(TypedDict, total=False):
+    only: List[str]
+    exclude: List[str]
+    order: List[str]
+
+
+class RoutingPolicy(TypedDict, total=False):
+    strategy: Literal["balanced", "cost", "latency", "quality"]
+    providers: ProviderPolicy
+    allow_fallbacks: bool
+    require_parameters: bool
+    data_policy: Literal["default", "no_training", "zero_retention"]
+    caching: Literal["auto"]
+    max_cost_usd: float
+
+
+class ChatMessage(TypedDict, total=False):
+    role: Required[Literal["developer", "system", "user", "assistant", "tool"]]
+    content: Union[str, List[Dict[str, Any]], None]
+    tool_call_id: str
+    tool_calls: List[Dict[str, Any]]
+
+
+class ChatCompletionParams(TypedDict, total=False):
+    model: str
+    models: List[str]
+    messages: Required[List[ChatMessage]]
+    max_completion_tokens: int
+    temperature: float
+    top_p: float
+    stop: Union[str, List[str]]
+    frequency_penalty: float
+    presence_penalty: float
+    seed: int
+    user: str
+    response_format: Dict[str, Any]
+    stream: bool
+    stream_options: Dict[str, bool]
+    tools: List[Dict[str, Any]]
+    tool_choice: Union[str, Dict[str, Any]]
+    parallel_tool_calls: bool
+    routing: RoutingPolicy
+
+
+class ResponseCreateParams(TypedDict, total=False):
+    model: str
+    models: List[str]
+    input: Required[Union[str, List[Dict[str, Any]]]]
+    instructions: str
+    max_output_tokens: int
+    temperature: float
+    top_p: float
+    tools: List[Dict[str, Any]]
+    tool_choice: Union[str, Dict[str, Any]]
+    parallel_tool_calls: bool
+    text: Dict[str, Any]
+    routing: RoutingPolicy
+    metadata: Dict[str, str]
+    user: str
+    stream: bool
+    store: Literal[False]
+
+
+class ImageGenerateParams(TypedDict, total=False):
+    prompt: Required[str]
+    model: str
+    n: int
+    size: str
+    aspect_ratio: str
+    image: str
+    width: int
+    height: int
+
+
+class VideoGenerateParams(TypedDict, total=False):
+    prompt: Required[str]
+    model: str
+    duration: int
+    aspect_ratio: Literal["16:9", "9:16"]
+    image_url: str
+    reference_images: List[str]
+    reference_video: str
+    reference_audio: str
+    generate_audio: bool
+    watermark: bool
+
+
+class SearchParams(TypedDict, total=False):
+    query: Required[str]
+    group: Literal["web", "news"]
+    max_results: int
+    search_depth: Literal["basic", "advanced"]
+    topic: Literal["general", "news", "finance"]
+    include_answer: bool
+    include_images: bool

ninjachat-0.1.0/ninjachat/webhooks.py

@@ -0,0 +1,50 @@
+"""Outbound-webhook signature verification.
+
+NinjaChat signs every delivery with::
+
+    X-Ninja-Signature: hex( HMAC-SHA256( secret, f"{timestamp}.{raw_body}" ) )
+    X-Ninja-Timestamp: unix seconds at send time
+
+Verify with the RAW request body bytes exactly as received — re-serializing the
+parsed JSON changes the bytes and breaks the signature.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import time
+from typing import Optional, Union
+
+
+def verify_webhook_signature(
+    raw_body: Union[str, bytes],
+    signature: str,
+    timestamp: Union[str, int],
+    secret: str,
+    *,
+    tolerance_seconds: Optional[int] = 300,
+) -> bool:
+    """Return True iff ``signature`` is a valid signature of ``raw_body``.
+
+    Args:
+        raw_body: The raw request body (str or bytes), byte-exact.
+        signature: The ``X-Ninja-Signature`` header value (hex).
+        timestamp: The ``X-Ninja-Timestamp`` header value (unix seconds).
+        secret: The endpoint's signing secret (returned once at creation).
+        tolerance_seconds: Reject deliveries whose timestamp is further than
+            this many seconds from now (replay protection). Default 300;
+            pass ``None`` to skip the check.
+    """
+    try:
+        ts = int(timestamp)
+    except (TypeError, ValueError):
+        return False
+
+    if tolerance_seconds is not None and abs(time.time() - ts) > tolerance_seconds:
+        return False
+
+    body_bytes = raw_body.encode("utf-8") if isinstance(raw_body, str) else raw_body
+    signed_payload = f"{ts}.".encode("utf-8") + body_bytes
+    expected = hmac.new(secret.encode("utf-8"), signed_payload, hashlib.sha256).hexdigest()
+    return hmac.compare_digest(expected, signature.strip().lower())

ninjachat-0.1.0/ninjachat.egg-info/PKG-INFO

@@ -0,0 +1,73 @@
+Metadata-Version: 2.4
+Name: ninjachat
+Version: 0.1.0
+Summary: Official Python SDK for the NinjaChat API — one typed client for chat, responses, media, routing, usage, and webhooks.
+Author: Helium Technologies, Inc.
+License-Expression: MIT
+Project-URL: Documentation, https://docs.ninjachat.ai
+Project-URL: OpenAPI spec, https://www.ninjachat.ai/api/v1/openapi
+Project-URL: Source, https://github.com/bloon-ai/ninjachat-sdk/tree/main/packages/python
+Project-URL: Issues, https://github.com/bloon-ai/ninjachat-sdk/issues
+Keywords: ninjachat,ai,llm,openai-compatible,sdk
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.28
+Requires-Dist: typing-extensions>=4.8; python_version < "3.11"
+Dynamic: license-file
+
+# NinjaChat Python SDK
+
+Typed client for the clean NinjaChat API v1.
+
+```bash
+pip install ninjachat
+```
+
+```python
+import os
+from ninjachat import NinjaChat
+
+client = NinjaChat(api_key=os.environ["NINJACHAT_API_KEY"])
+response = client.responses.create(
+    model="ninja/auto",
+    input="Write one sentence about clean APIs.",
+    max_output_tokens=64,
+    routing={"strategy": "balanced", "data_policy": "no_training"},
+)
+print(response["output_text"], response["cost_usd"], response["request_id"])
+```
+
+Ordered fallbacks and provider constraints are explicit:
+
+```python
+completion = client.chat.completions.create(
+    models=["gpt-5", "claude-sonnet-4"],
+    messages=[{"role": "user", "content": "Hello"}],
+    max_completion_tokens=100,
+    routing={"strategy": "latency", "allow_fallbacks": True, "caching": "auto", "max_cost_usd": 0.10},
+)
+```
+
+Streams return iterators of typed-shape dictionaries:
+
+```python
+for event in client.responses.create(model="ninja/auto", input="Hello", stream=True):
+    if event.get("type") == "response.output_text.delta":
+        print(event.get("delta", ""), end="")
+```
+
+Models and prices come from `client.models.list()`. Images use `client.images.generate()`, videos use `client.videos.generate()` and `client.videos.wait_for()`, and account observability is available through `client.usage()`, `client.balance()`, and `client.requests.get()`.
+
+Signed webhooks replace video polling and fire spend alerts: `client.webhooks.create(...)` or the [console](https://www.ninjachat.ai/developers/keys#webhooks). Verify deliveries with `verify_webhook_signature`.
+
+The base URL is `https://www.ninjachat.ai/api/v1`. Chat and Responses are billed by actual token usage. See [docs.ninjachat.ai](https://docs.ninjachat.ai).

ninjachat-0.1.0/ninjachat.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+LICENSE
+README.md
+pyproject.toml
+ninjachat/__init__.py
+ninjachat/client.py
+ninjachat/contract.py
+ninjachat/errors.py
+ninjachat/py.typed
+ninjachat/types.py
+ninjachat/webhooks.py
+ninjachat.egg-info/PKG-INFO
+ninjachat.egg-info/SOURCES.txt
+ninjachat.egg-info/dependency_links.txt
+ninjachat.egg-info/requires.txt
+ninjachat.egg-info/top_level.txt
+tests/test_smoke.py

ninjachat-0.1.0/ninjachat.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

ninjachat-0.1.0/ninjachat.egg-info/requires.txt

@@ -0,0 +1,4 @@
+requests>=2.28
+
+[:python_version < "3.11"]
+typing-extensions>=4.8

ninjachat-0.1.0/ninjachat.egg-info/top_level.txt

@@ -0,0 +1 @@
+ninjachat

ninjachat-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ninjachat"
+version = "0.1.0"
+description = "Official Python SDK for the NinjaChat API — one typed client for chat, responses, media, routing, usage, and webhooks."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+authors = [{ name = "Helium Technologies, Inc." }]
+dependencies = ["requests>=2.28", "typing-extensions>=4.8; python_version < '3.11'"]
+keywords = ["ninjachat", "ai", "llm", "openai-compatible", "sdk"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Typing :: Typed",
+]
+
+[project.urls]
+Documentation = "https://docs.ninjachat.ai"
+"OpenAPI spec" = "https://www.ninjachat.ai/api/v1/openapi"
+Source = "https://github.com/bloon-ai/ninjachat-sdk/tree/main/packages/python"
+Issues = "https://github.com/bloon-ai/ninjachat-sdk/issues"
+
+[tool.setuptools.packages.find]
+include = ["ninjachat*"]
+
+[tool.setuptools.package-data]
+ninjachat = ["py.typed"]

ninjachat-0.1.0/setup.cfg

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

ninjachat-0.1.0/tests/test_smoke.py

@@ -0,0 +1,32 @@
+import unittest
+from unittest.mock import Mock
+
+from ninjachat import NinjaChat, NinjaChatError, __version__
+
+
+class NinjaChatSmokeTest(unittest.TestCase):
+    def test_lists_models_with_expected_auth_and_base_url(self) -> None:
+        session = Mock()
+        response = Mock()
+        response.ok = True
+        response.json.return_value = {"object": "list", "data": []}
+        session.request.return_value = response
+        client = NinjaChat(api_key="nj_sk_test", max_retries=0, session=session)
+
+        self.assertEqual(client.models.list(), {"object": "list", "data": []})
+        session.request.assert_called_once()
+        args, kwargs = session.request.call_args
+        self.assertEqual(args[:2], ("GET", "https://www.ninjachat.ai/api/v1/models"))
+        self.assertEqual(kwargs["headers"]["Authorization"], "Bearer nj_sk_test")
+
+    def test_missing_key_fails_clearly(self) -> None:
+        with self.assertRaises(NinjaChatError) as raised:
+            NinjaChat(api_key="")
+        self.assertEqual(raised.exception.code, "missing_api_key")
+
+    def test_preview_version_is_synchronized(self) -> None:
+        self.assertEqual(__version__, "0.1.0")
+
+
+if __name__ == "__main__":
+    unittest.main()