nixflex 0.1.0__tar.gz

nixflex-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,14 @@
+name: CI
+on: [push, pull_request]
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "${{ matrix.python-version }}" }
+      - run: pip install -e ".[dev]"
+      - run: python -m pytest -q

nixflex-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+dist/
+build/
+*.egg-info/
+__pycache__/
+.pytest_cache/
+.venv/

nixflex-0.1.0/CHANGELOG.md

@@ -0,0 +1,2 @@
+## 0.1.0
+- First release. Sync (`Nixflex`) and async (`AsyncNixflex`) clients covering every endpoint - 46 methods mirroring the Node SDK. Retry policy identical to Node (429 with Retry-After, network once, 5xx only on GET/DELETE, POST never blind-retried). Eight typed error classes. `verify_webhook_signature`. Python 3.9+, `httpx` only.

nixflex-0.1.0/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 Nixflex Enterprises LLC
+
+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.

nixflex-0.1.0/PKG-INFO

@@ -0,0 +1,67 @@
+Metadata-Version: 2.5
+Name: nixflex
+Version: 0.1.0
+Summary: Official Python SDK for the Nixflex voice AI platform - AI phone agents, outbound campaigns, SMS and caller context.
+Project-URL: Homepage, https://nixflex.com
+Project-URL: Documentation, https://docs.nixflex.com/sdks/python
+Project-URL: Repository, https://github.com/nixflex/nixflex-python
+Project-URL: Changelog, https://github.com/nixflex/nixflex-python/blob/main/CHANGELOG.md
+Author-email: Nixflex <stackadvisor.app@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: ai-receptionist,nixflex,phone,sdk,sms,telephony,telnyx,twilio,voice-agent,voice-ai
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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: Topic :: Communications :: Telephony
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx<2,>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# nixflex
+
+Official Python SDK for the [Nixflex](https://nixflex.com) voice AI platform - AI phone agents, outbound campaigns, SMS and caller context.
+
+```bash
+pip install nixflex
+```
+
+```python
+from nixflex import Nixflex
+
+client = Nixflex(api_key="nxf_xxx:nxfs_xxx")   # both halves, joined by a colon
+
+call = client.calls.create(
+    agent_id="agent_15d1a9ee16294087",
+    to_number="+447700900123",
+    prompt="Call Sam to confirm his appointment on Tuesday at 11.",
+)
+print(call["call_id"])
+```
+
+Async:
+
+```python
+from nixflex import AsyncNixflex
+
+async with AsyncNixflex(api_key="nxf_xxx:nxfs_xxx") as client:
+    agents = await client.agents.list()
+```
+
+- Every endpoint: `agents`, `calls`, `campaigns`, `phone_numbers`, `callers` (caller context), `sms` (+ `sms.campaigns`), `keys`, `usage`, `webhooks`, `storage`, `llm`, `tts` - the same names as the Node SDK and the CLI.
+- Retries: a 429 is retried once honouring `Retry-After`; network failures retry once; 5xx retries only `GET`/`DELETE`. A `POST` is never blind-retried - a call is never dialled twice.
+- Typed errors: `NixflexAuthenticationError`, `NixflexRateLimitError` (`.retry_after_seconds`), `NixflexNotFoundError`, ...
+- `verify_webhook_signature(raw_body, header, key_secret)` for signed webhooks.
+- Python 3.9+, one dependency (`httpx`).
+
+Docs: https://docs.nixflex.com/sdks/python

nixflex-0.1.0/README.md

@@ -0,0 +1,37 @@
+# nixflex
+
+Official Python SDK for the [Nixflex](https://nixflex.com) voice AI platform - AI phone agents, outbound campaigns, SMS and caller context.
+
+```bash
+pip install nixflex
+```
+
+```python
+from nixflex import Nixflex
+
+client = Nixflex(api_key="nxf_xxx:nxfs_xxx")   # both halves, joined by a colon
+
+call = client.calls.create(
+    agent_id="agent_15d1a9ee16294087",
+    to_number="+447700900123",
+    prompt="Call Sam to confirm his appointment on Tuesday at 11.",
+)
+print(call["call_id"])
+```
+
+Async:
+
+```python
+from nixflex import AsyncNixflex
+
+async with AsyncNixflex(api_key="nxf_xxx:nxfs_xxx") as client:
+    agents = await client.agents.list()
+```
+
+- Every endpoint: `agents`, `calls`, `campaigns`, `phone_numbers`, `callers` (caller context), `sms` (+ `sms.campaigns`), `keys`, `usage`, `webhooks`, `storage`, `llm`, `tts` - the same names as the Node SDK and the CLI.
+- Retries: a 429 is retried once honouring `Retry-After`; network failures retry once; 5xx retries only `GET`/`DELETE`. A `POST` is never blind-retried - a call is never dialled twice.
+- Typed errors: `NixflexAuthenticationError`, `NixflexRateLimitError` (`.retry_after_seconds`), `NixflexNotFoundError`, ...
+- `verify_webhook_signature(raw_body, header, key_secret)` for signed webhooks.
+- Python 3.9+, one dependency (`httpx`).
+
+Docs: https://docs.nixflex.com/sdks/python

nixflex-0.1.0/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "nixflex"
+version = "0.1.0"
+description = "Official Python SDK for the Nixflex voice AI platform - AI phone agents, outbound campaigns, SMS and caller context."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.9"
+authors = [{ name = "Nixflex", email = "stackadvisor.app@gmail.com" }]
+keywords = ["nixflex", "voice-ai", "voice-agent", "phone", "telephony", "ai-receptionist", "twilio", "telnyx", "sms", "sdk"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "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",
+  "Topic :: Communications :: Telephony",
+  "Typing :: Typed",
+]
+dependencies = ["httpx>=0.27,<2"]
+
+[project.urls]
+Homepage = "https://nixflex.com"
+Documentation = "https://docs.nixflex.com/sdks/python"
+Repository = "https://github.com/nixflex/nixflex-python"
+Changelog = "https://github.com/nixflex/nixflex-python/blob/main/CHANGELOG.md"
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "pytest-asyncio>=0.23"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/nixflex"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

nixflex-0.1.0/src/nixflex/__init__.py

@@ -0,0 +1,94 @@
+"""Official Nixflex SDK for Python.
+
+    from nixflex import Nixflex
+    client = Nixflex(api_key="nxf_xxx:nxfs_xxx")
+    call = client.calls.create(agent_id="agent_x", to_number="+447700900123", prompt="...")
+
+Async:
+    from nixflex import AsyncNixflex
+    async with AsyncNixflex(api_key=...) as client:
+        agents = await client.agents.list()
+
+Every method mirrors the Node SDK and the CLI - same names in snake_case. The docs
+(docs.nixflex.com) are the source of truth; this SDK changes in the same session as the API.
+"""
+from __future__ import annotations
+
+from typing import Optional
+
+import httpx
+
+from ._http import AsyncHttp, SyncHttp, __version__
+from .errors import (
+    NixflexAuthenticationError,
+    NixflexConnectionError,
+    NixflexError,
+    NixflexInvalidRequestError,
+    NixflexNotFoundError,
+    NixflexPaymentRequiredError,
+    NixflexRateLimitError,
+    NixflexServerError,
+)
+from .resources.account import Keys, Llm, Storage, Tts, Usage, Webhooks
+from .resources.agents import Agents
+from .resources.callers import Callers
+from .resources.calls import Calls, Campaigns
+from .resources.phone_numbers import PhoneNumbers
+from .resources.sms import Sms
+from .webhook import verify_webhook_signature
+
+__all__ = [
+    "Nixflex", "AsyncNixflex", "verify_webhook_signature", "__version__",
+    "NixflexError", "NixflexAuthenticationError", "NixflexPaymentRequiredError", "NixflexNotFoundError",
+    "NixflexRateLimitError", "NixflexInvalidRequestError", "NixflexServerError", "NixflexConnectionError",
+]
+
+
+class _Resources:
+    def _attach(self, http) -> None:
+        self.agents = Agents(http)
+        self.calls = Calls(http)
+        self.campaigns = Campaigns(http)
+        self.phone_numbers = PhoneNumbers(http)
+        self.callers = Callers(http)
+        self.sms = Sms(http)
+        self.keys = Keys(http)
+        self.usage = Usage(http)
+        self.webhooks = Webhooks(http)
+        self.storage = Storage(http)
+        self.llm = Llm(http)
+        self.tts = Tts(http)
+
+
+class Nixflex(_Resources):
+    """Synchronous client. Use as a context manager or call close() when done."""
+
+    def __init__(self, api_key: str, base_url: Optional[str] = None, timeout: Optional[float] = None, max_retries: Optional[int] = None, transport: Optional[httpx.BaseTransport] = None):
+        self._http = SyncHttp(api_key, base_url, timeout, max_retries, transport)
+        self._attach(self._http)
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> "Nixflex":
+        return self
+
+    def __exit__(self, *exc) -> None:
+        self.close()
+
+
+class AsyncNixflex(_Resources):
+    """Asynchronous client - every method returns an awaitable."""
+
+    def __init__(self, api_key: str, base_url: Optional[str] = None, timeout: Optional[float] = None, max_retries: Optional[int] = None, transport: Optional[httpx.AsyncBaseTransport] = None):
+        self._http = AsyncHttp(api_key, base_url, timeout, max_retries, transport)
+        self._attach(self._http)
+
+    async def close(self) -> None:
+        await self._http.close()
+
+    async def __aenter__(self) -> "AsyncNixflex":
+        return self
+
+    async def __aexit__(self, *exc) -> None:
+        await self.close()

nixflex-0.1.0/src/nixflex/_http.py

@@ -0,0 +1,147 @@
+"""The core HTTP layer every resource uses - sync and async, one retry policy.
+
+Behaviours (identical to the Node SDK, both verified against the live API):
+  - Bearer auth with the full key "key_id:key_secret".
+  - Per-request timeout (default 30 s).
+  - RETRY: a 429 honours the API's Retry-After header (capped 30 s). 5xx and network
+    failures retry once with a small backoff. GET/DELETE always retry; POST/PUT/PATCH
+    retry ONLY on 429 or a network failure before any response - never after a 5xx,
+    which may already have acted (no double calls, no double sends).
+  - Every non-2xx becomes a typed error (errors.py); the request id is surfaced.
+"""
+from __future__ import annotations
+
+import asyncio
+import json
+import time
+from typing import Any, Dict, Mapping, Optional
+from urllib.parse import quote
+
+import httpx
+
+from .errors import NixflexConnectionError, error_from_response
+
+__version__ = "0.1.0"
+DEFAULT_BASE_URL = "https://api.nixflex.com"
+DEFAULT_TIMEOUT = 30.0
+_IDEMPOTENT = {"GET", "DELETE"}
+
+
+def enc(number: str) -> str:
+    """E.164 numbers go in URL paths - the + MUST be encoded or routing breaks."""
+    return quote(number, safe="")
+
+
+def _check_key(api_key: Any) -> str:
+    if not isinstance(api_key, str) or ":" not in api_key:
+        raise ValueError(
+            'Nixflex: api_key is required in the form "key_id:key_secret" (both parts, joined by a colon). '
+            "Find yours at https://dashboard.nixflex.com under API Keys."
+        )
+    return api_key
+
+
+def _clean_query(query: Optional[Mapping[str, Any]]) -> Dict[str, str]:
+    if not query:
+        return {}
+    return {k: str(v) for k, v in query.items() if v is not None}
+
+
+def _retry_plan(status: int, method: str, retry_after: int, attempt: int, max_retries: int) -> Optional[float]:
+    """Seconds to sleep before retrying, or None = do not retry."""
+    if attempt > max_retries:
+        return None
+    if status == 429:
+        return float(min(retry_after, 30)) or 1.0
+    if status >= 500 and method in _IDEMPOTENT:
+        return 0.5 * attempt
+    return None
+
+
+def _parse_error(res: httpx.Response):
+    request_id = res.headers.get("x-railway-request-id")
+    try:
+        retry_after = int(res.headers.get("retry-after") or "0")
+    except ValueError:
+        retry_after = 0
+    try:
+        body = res.json()
+    except Exception:
+        body = None
+    return request_id, retry_after, body
+
+
+class _Base:
+    def __init__(self, api_key: str, base_url: Optional[str], timeout: Optional[float], max_retries: Optional[int]):
+        self._api_key = _check_key(api_key)
+        self._base_url = (base_url or DEFAULT_BASE_URL).rstrip("/")
+        self._timeout = DEFAULT_TIMEOUT if timeout is None else timeout
+        self._max_retries = 1 if max_retries is None else max_retries
+        self._headers = {
+            "Authorization": f"Bearer {self._api_key}",
+            "Content-Type": "application/json",
+            "User-Agent": f"nixflex-python/{__version__}",
+        }
+
+    def _url(self, path: str) -> str:
+        return self._base_url + "/v1" + path
+
+
+class SyncHttp(_Base):
+    def __init__(self, api_key: str, base_url: Optional[str] = None, timeout: Optional[float] = None, max_retries: Optional[int] = None, transport: Optional[httpx.BaseTransport] = None):
+        super().__init__(api_key, base_url, timeout, max_retries)
+        self._client = httpx.Client(timeout=self._timeout, transport=transport)
+
+    def close(self) -> None:
+        self._client.close()
+
+    def request(self, method: str, path: str, body: Any = None, query: Optional[Mapping[str, Any]] = None, timeout: Optional[float] = None) -> Any:
+        attempt = 0
+        content = None if body is None else json.dumps(body).encode("utf-8")
+        while True:
+            attempt += 1
+            try:
+                res = self._client.request(method, self._url(path), params=_clean_query(query), content=content, headers=self._headers, timeout=self._timeout if timeout is None else timeout)
+            except (httpx.TransportError, httpx.TimeoutException) as err:
+                if attempt <= self._max_retries:
+                    time.sleep(0.3 * attempt)
+                    continue
+                raise NixflexConnectionError(f"Could not reach the Nixflex API ({err.__class__.__name__}: {err}). Check connectivity and https://nixflex.com/status") from None
+            if res.is_success:
+                return None if res.status_code == 204 else res.json()
+            request_id, retry_after, err_body = _parse_error(res)
+            wait = _retry_plan(res.status_code, method, retry_after, attempt, self._max_retries)
+            if wait is not None:
+                time.sleep(wait)
+                continue
+            raise error_from_response(res.status_code, err_body, request_id, retry_after)
+
+
+class AsyncHttp(_Base):
+    def __init__(self, api_key: str, base_url: Optional[str] = None, timeout: Optional[float] = None, max_retries: Optional[int] = None, transport: Optional[httpx.AsyncBaseTransport] = None):
+        super().__init__(api_key, base_url, timeout, max_retries)
+        self._client = httpx.AsyncClient(timeout=self._timeout, transport=transport)
+
+    async def close(self) -> None:
+        await self._client.aclose()
+
+    async def request(self, method: str, path: str, body: Any = None, query: Optional[Mapping[str, Any]] = None, timeout: Optional[float] = None) -> Any:
+        attempt = 0
+        content = None if body is None else json.dumps(body).encode("utf-8")
+        while True:
+            attempt += 1
+            try:
+                res = await self._client.request(method, self._url(path), params=_clean_query(query), content=content, headers=self._headers, timeout=self._timeout if timeout is None else timeout)
+            except (httpx.TransportError, httpx.TimeoutException) as err:
+                if attempt <= self._max_retries:
+                    await asyncio.sleep(0.3 * attempt)
+                    continue
+                raise NixflexConnectionError(f"Could not reach the Nixflex API ({err.__class__.__name__}: {err}). Check connectivity and https://nixflex.com/status") from None
+            if res.is_success:
+                return None if res.status_code == 204 else res.json()
+            request_id, retry_after, err_body = _parse_error(res)
+            wait = _retry_plan(res.status_code, method, retry_after, attempt, self._max_retries)
+            if wait is not None:
+                await asyncio.sleep(wait)
+                continue
+            raise error_from_response(res.status_code, err_body, request_id, retry_after)

nixflex-0.1.0/src/nixflex/errors.py

@@ -0,0 +1,78 @@
+"""Typed error family. Mirrors the API's error shape exactly:
+    { "error": { "type", "code", "message", "doc_url", "details" } }
+Every non-2xx response becomes one of these - catch by class:
+    try: ...
+    except NixflexRateLimitError as e: sleep(e.retry_after_seconds)
+"""
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+
+class NixflexError(Exception):
+    """Base class. `status` is the HTTP status (0 for network/timeout failures)."""
+
+    def __init__(self, status: int, body: Optional[Dict[str, Any]], request_id: Optional[str] = None, fallback_message: Optional[str] = None):
+        e = (body or {}).get("error") or {}
+        super().__init__(e.get("message") or fallback_message or f"Nixflex API error (HTTP {status})")
+        self.status: int = status
+        self.code: str = e.get("code") or "unknown_error"
+        self.type: str = e.get("type") or "error"
+        self.doc_url: Optional[str] = e.get("doc_url")
+        self.details: Dict[str, Any] = e.get("details") or {}
+        self.request_id: Optional[str] = request_id
+
+    def __repr__(self) -> str:  # pragma: no cover
+        return f"{self.__class__.__name__}(status={self.status}, code={self.code!r}, message={str(self)!r})"
+
+
+class NixflexAuthenticationError(NixflexError):
+    """401 - missing or invalid API key."""
+
+
+class NixflexPaymentRequiredError(NixflexError):
+    """402 - balance or credit exhausted."""
+
+
+class NixflexNotFoundError(NixflexError):
+    """404 - the resource does not exist (or is not yours)."""
+
+
+class NixflexInvalidRequestError(NixflexError):
+    """400/422 - the request itself is malformed or invalid."""
+
+
+class NixflexServerError(NixflexError):
+    """5xx - something failed on Nixflex's side. GET/DELETE are retried once automatically."""
+
+
+class NixflexRateLimitError(NixflexError):
+    """429 - rate limit hit. `retry_after_seconds` says when to try again."""
+
+    def __init__(self, status: int, body: Optional[Dict[str, Any]], request_id: Optional[str], retry_after_seconds: int):
+        super().__init__(status, body, request_id)
+        self.retry_after_seconds: int = retry_after_seconds
+
+
+class NixflexConnectionError(NixflexError):
+    """Network failure / timeout - the request never got an HTTP response."""
+
+    def __init__(self, message: str):
+        super().__init__(0, None, None, message)
+
+
+def error_from_response(status: int, body: Optional[Dict[str, Any]], request_id: Optional[str], retry_after_seconds: int) -> NixflexError:
+    """Map a status + body to the right error class (same table as the Node SDK)."""
+    if status == 401:
+        return NixflexAuthenticationError(status, body, request_id)
+    if status == 402:
+        return NixflexPaymentRequiredError(status, body, request_id)
+    if status == 404:
+        return NixflexNotFoundError(status, body, request_id)
+    if status == 429:
+        return NixflexRateLimitError(status, body, request_id, retry_after_seconds)
+    if status in (400, 422):
+        return NixflexInvalidRequestError(status, body, request_id)
+    if status >= 500:
+        return NixflexServerError(status, body, request_id)
+    return NixflexError(status, body, request_id)

nixflex-0.1.0/src/nixflex/resources/__init__.py

@@ -0,0 +1,3 @@
+"""Resources are written ONCE. Each method returns `self._http.request(...)`, so on the
+sync client that is the result and on the async client it is an awaitable. Same 46
+methods, same names as the Node SDK (snake_case), no duplication."""

nixflex-0.1.0/src/nixflex/resources/account.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+from typing import Any
+from .._http import enc
+
+
+class Keys:
+    def __init__(self, http):
+        self._http = http
+
+    def rotate(self):
+        """New secret. The current one stops working immediately - update every integration."""
+        return self._http.request("POST", "/keys/rotate")
+
+
+class Usage:
+    def __init__(self, http):
+        self._http = http
+
+    def get(self):
+        return self._http.request("GET", "/usage")
+
+
+class _ByoBase:
+    """Bring your own storage / LLM / TTS. set() is verified by the API with a real probe before saving; get() never returns secrets."""
+    _path = ""
+
+    def __init__(self, http):
+        self._http = http
+
+    def set(self, **params: Any):
+        return self._http.request("PUT", self._path, params)
+
+    def get(self):
+        return self._http.request("GET", self._path)
+
+    def delete(self):
+        """Disconnect - calls fall back to Nixflex."""
+        return self._http.request("DELETE", self._path)
+
+
+class Storage(_ByoBase):
+    _path = "/account/storage"
+
+
+class Llm(_ByoBase):
+    _path = "/account/llm"
+
+
+class Tts(_ByoBase):
+    _path = "/account/tts"
+
+
+class Webhooks:
+    """Per-number post-call webhook (two slots). Verify deliveries with nixflex.verify_webhook_signature."""
+
+    def __init__(self, http):
+        self._http = http
+
+    @staticmethod
+    def _base(slot: int) -> str:
+        return "webhook2" if slot == 2 else "webhook"
+
+    def set(self, phone_number: str, url: str, slot: int = 1):
+        return self._http.request("PUT", f"/integrations/{self._base(slot)}/number/{enc(phone_number)}", {"url": url})
+
+    def get(self, phone_number: str, slot: int = 1):
+        return self._http.request("GET", f"/integrations/{self._base(slot)}/number/{enc(phone_number)}")
+
+    def delete(self, phone_number: str, slot: int = 1):
+        return self._http.request("DELETE", f"/integrations/{self._base(slot)}/number/{enc(phone_number)}")

nixflex-0.1.0/src/nixflex/resources/agents.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+from typing import Any, Dict, Optional
+
+
+class Agents:
+    def __init__(self, http):
+        self._http = http
+
+    def create(self, **params: Any):
+        """Create an agent. Any field the API accepts (name, system_prompt, voice_id, language, incall_sms_enabled, ...)."""
+        return self._http.request("POST", "/agents", params)
+
+    def list(self, limit: Optional[int] = None, offset: Optional[int] = None):
+        return self._http.request("GET", "/agents", None, {"limit": limit, "offset": offset})
+
+    def get(self, agent_id: str):
+        return self._http.request("GET", f"/agents/{agent_id}")
+
+    def update(self, agent_id: str, **params: Any):
+        """Only the fields you pass change."""
+        return self._http.request("PUT", f"/agents/{agent_id}", params)
+
+    def delete(self, agent_id: str):
+        return self._http.request("DELETE", f"/agents/{agent_id}")

nixflex-0.1.0/src/nixflex/resources/callers.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+from typing import Any, Dict, List
+from .._http import enc
+
+
+class Callers:
+    """Caller context - what the agent knows about a caller on one of your numbers.
+    phone_number is YOUR number; caller_number is the customer. Docs: /concepts/caller-context"""
+
+    def __init__(self, http):
+        self._http = http
+
+    def get(self, phone_number: str, caller_number: str):
+        return self._http.request("GET", f"/phone-numbers/{enc(phone_number)}/callers/{enc(caller_number)}")
+
+    def set(self, phone_number: str, caller_number: str, **fields: Any):
+        """name, email, phone, location, reference_id, preference. Omitted fields are kept; pass None to remove one. last_call / open_item are engine-only (400 engine_only_field)."""
+        return self._http.request("PUT", f"/phone-numbers/{enc(phone_number)}/callers/{enc(caller_number)}", fields)
+
+    def delete(self, phone_number: str, caller_number: str):
+        """Erases the whole record - yours and the engine's."""
+        return self._http.request("DELETE", f"/phone-numbers/{enc(phone_number)}/callers/{enc(caller_number)}")
+
+    def import_(self, phone_number: str, callers: List[Dict[str, Any]]):
+        """Up to 1,000 rows, each {"caller_number": "+44...", ...fields}. Every row is validated before any is written."""
+        return self._http.request("POST", f"/phone-numbers/{enc(phone_number)}/callers/import", {"callers": callers})

nixflex-0.1.0/src/nixflex/resources/calls.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+from typing import Any, Dict, List, Optional
+
+
+class Calls:
+    def __init__(self, http):
+        self._http = http
+
+    def create(self, agent_id: str, to_number: str, prompt: str, from_number: Optional[str] = None, variables: Optional[Dict[str, str]] = None, **extra: Any):
+        """Place an outbound call now. Never retried after a 5xx - a call is never dialled twice."""
+        body: Dict[str, Any] = {"agent_id": agent_id, "to_number": to_number, "prompt": prompt, **extra}
+        if from_number is not None:
+            body["from_number"] = from_number
+        if variables is not None:
+            body["variables"] = variables
+        return self._http.request("POST", "/calls/outbound", body)
+
+    def list(self, limit: Optional[int] = None, offset: Optional[int] = None, agent_id: Optional[str] = None):
+        return self._http.request("GET", "/calls", None, {"limit": limit, "offset": offset, "agent_id": agent_id})
+
+    def get(self, call_id: str):
+        return self._http.request("GET", f"/calls/{call_id}")
+
+    def delete(self, call_id: str):
+        """Removes the record and its recording (GDPR)."""
+        return self._http.request("DELETE", f"/calls/{call_id}")
+
+    def delete_all(self):
+        """Every call, recording and SMS record on the account. Cannot be undone."""
+        return self._http.request("DELETE", "/calls")
+
+
+class Campaigns:
+    """Voice batch campaigns - many calls under one prompt."""
+
+    def __init__(self, http):
+        self._http = http
+
+    def create(self, agent_id: str, from_number: str, prompt: str, recipients: List[Dict[str, Any]], **extra: Any):
+        """recipients: [{"phone": "+44...", "variables": {...}, "prompt_override": "..."}, ...]. Dials immediately unless schedule_type="schedule"."""
+        return self._http.request("POST", "/calls/batch", {"agent_id": agent_id, "from_number": from_number, "prompt": prompt, "recipients": recipients, **extra})
+
+    def launch(self, campaign_id: str):
+        return self._http.request("POST", f"/calls/batch/{campaign_id}/launch")

nixflex-0.1.0/src/nixflex/resources/phone_numbers.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+from typing import Any, Optional
+from .._http import enc
+
+
+class PhoneNumbers:
+    def __init__(self, http):
+        self._http = http
+
+    def import_(self, phone_number: str, agent_id: str, **credentials: Any):
+        """Attach a number you own. Twilio: twilio_account_sid + twilio_auth_token. Telnyx: telnyx_api_key + telnyx_connection_id. The carrier is inferred from which you send."""
+        return self._http.request("POST", "/phone-numbers", {"phone_number": phone_number, "agent_id": agent_id, **credentials})
+
+    def list(self, agent_id: Optional[str] = None):
+        return self._http.request("GET", "/phone-numbers", None, {"agent_id": agent_id})
+
+    def update(self, phone_number: str, **params: Any):
+        """Per-number settings: custom_prompt, sms_prompt, sms_reply_enabled, web_prompt, dtmf_enabled, record_call, voice_id, speaking_rate, ... Only passed fields change; None clears where the API allows null."""
+        return self._http.request("PATCH", f"/phone-numbers/{enc(phone_number)}", params)
+
+    def delete(self, phone_number: str):
+        """Disconnects from Nixflex. Your carrier keeps the number and keeps billing it."""
+        return self._http.request("DELETE", f"/phone-numbers/{enc(phone_number)}")
+
+    def set_monitor(self, phone_number: str, enabled: bool):
+        """Live call monitoring. On bills that number's inbound calls at the premium rate."""
+        return self._http.request("PUT", f"/integrations/monitor/number/{enc(phone_number)}", {"enabled": enabled})
+
+    def get_monitor(self, phone_number: str):
+        return self._http.request("GET", f"/integrations/monitor/number/{enc(phone_number)}")
+
+    def set_web_calls(self, phone_number: str, enabled: bool):
+        return self._http.request("PUT", f"/integrations/web-calls/number/{enc(phone_number)}", {"enabled": enabled})
+
+    def get_web_calls(self, phone_number: str):
+        return self._http.request("GET", f"/integrations/web-calls/number/{enc(phone_number)}")

nixflex-0.1.0/src/nixflex/resources/sms.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+from typing import Any, Dict, List, Optional
+
+
+class SmsCampaigns:
+    def __init__(self, http):
+        self._http = http
+
+    def create(self, agent_id: str, from_number: str, message: str, recipients: List[Dict[str, Any]], **extra: Any):
+        """recipients: [{"phone": "+44...", "variables": {...}}, ...]. from_number may be on either carrier."""
+        return self._http.request("POST", "/sms/campaigns", {"agent_id": agent_id, "from_number": from_number, "message": message, "recipients": recipients, **extra})
+
+    def launch(self, campaign_id: str):
+        return self._http.request("POST", f"/sms/campaigns/{campaign_id}/launch")
+
+    def list(self, status: Optional[str] = None, limit: Optional[int] = None):
+        return self._http.request("GET", "/sms/campaigns", None, {"status": status, "limit": limit})
+
+    def get(self, campaign_id: str):
+        return self._http.request("GET", f"/sms/campaigns/{campaign_id}")
+
+    def delete(self, campaign_id: str):
+        """Pending recipients are not messaged. Sent messages cannot be recalled."""
+        return self._http.request("DELETE", f"/sms/campaigns/{campaign_id}")
+
+
+class Sms:
+    def __init__(self, http):
+        self._http = http
+        self.campaigns = SmsCampaigns(http)
+
+    def send(self, agent_id: str, from_number: str, to: str, message: str, **extra: Any):
+        """One text from one of your numbers. Under 600 characters delivers reliably."""
+        return self._http.request("POST", "/sms", {"agent_id": agent_id, "from_number": from_number, "to": to, "message": message, **extra})

nixflex-0.1.0/src/nixflex/webhook.py

@@ -0,0 +1,51 @@
+"""Verify Nixflex webhook signatures.
+
+The engine signs every delivery:
+    header   X-Nixflex-Signature: t=<unix_ts>,v1=<hmac_sha256_hex>
+    payload  "<timestamp>.<raw_body>"      secret: your key_secret
+
+Use the RAW request body BYTES exactly as received - a re-serialised JSON body may
+differ from what was signed and will fail verification. Never raises.
+"""
+from __future__ import annotations
+
+import hashlib
+import hmac
+import re
+import time
+from typing import Optional, Union
+
+_HEX64 = re.compile(r"^[0-9a-f]{64}$")
+
+
+def verify_webhook_signature(
+    raw_body: Union[bytes, str],
+    signature_header: Optional[str],
+    key_secret: str,
+    tolerance_seconds: int = 300,
+    now: Optional[int] = None,
+) -> bool:
+    """True only if the signature is authentic AND fresh (within `tolerance_seconds`)."""
+    try:
+        if not signature_header or not key_secret:
+            return False
+        parts = {}
+        for seg in signature_header.split(","):
+            i = seg.find("=")
+            if i > 0:
+                parts[seg[:i].strip()] = seg[i + 1:].strip()
+        try:
+            t = int(parts.get("t", ""))
+        except ValueError:
+            return False
+        v1 = parts.get("v1", "")
+        if not _HEX64.match(v1):
+            return False
+        current = int(time.time()) if now is None else now
+        if abs(current - t) > tolerance_seconds:
+            return False  # stale or future-dated = replay risk
+        body = raw_body.encode("utf-8") if isinstance(raw_body, str) else raw_body
+        expected = hmac.new(key_secret.encode("utf-8"), f"{t}.".encode("utf-8") + body, hashlib.sha256).hexdigest()
+        return hmac.compare_digest(expected, v1)  # constant-time
+    except Exception:
+        return False

nixflex-0.1.0/tests/test_client.py

@@ -0,0 +1,187 @@
+"""Behaviour tests against a mock transport - no network. Same cases as the Node SDK."""
+import json
+import time
+
+import httpx
+import pytest
+
+from nixflex import (
+    AsyncNixflex,
+    Nixflex,
+    NixflexAuthenticationError,
+    NixflexConnectionError,
+    NixflexInvalidRequestError,
+    NixflexNotFoundError,
+    NixflexPaymentRequiredError,
+    NixflexRateLimitError,
+    NixflexServerError,
+)
+
+KEY = "nxf_test:nxfs_test"
+ERR = lambda code, msg="boom", typ="invalid_request": {"error": {"type": typ, "code": code, "message": msg, "doc_url": "https://docs.nixflex.com/errors/" + code, "details": {}}}
+
+
+def client_with(handler, **kw):
+    return Nixflex(api_key=KEY, transport=httpx.MockTransport(handler), **kw)
+
+
+def test_requires_full_key_pair():
+    with pytest.raises(ValueError):
+        Nixflex(api_key="nxf_only_the_id")
+
+
+def test_auth_header_user_agent_and_path():
+    seen = {}
+
+    def handler(req: httpx.Request):
+        seen["auth"] = req.headers["authorization"]
+        seen["ua"] = req.headers["user-agent"]
+        seen["url"] = str(req.url)
+        return httpx.Response(200, json=[{"agent_id": "a1"}])
+
+    with client_with(handler) as c:
+        assert c.agents.list(limit=5) == [{"agent_id": "a1"}]
+    assert seen["auth"] == "Bearer " + KEY
+    assert seen["ua"].startswith("nixflex-python/")
+    assert seen["url"] == "https://api.nixflex.com/v1/agents?limit=5"
+
+
+def test_phone_numbers_are_url_encoded():
+    seen = {}
+
+    def handler(req):
+        seen["path"] = req.url.raw_path.decode()
+        return httpx.Response(200, json={"caller": {}})
+
+    with client_with(handler) as c:
+        c.callers.get("+447450307843", "+447453573770")
+    assert seen["path"] == "/v1/phone-numbers/%2B447450307843/callers/%2B447453573770"
+
+
+def test_error_classes_by_status():
+    cases = [(401, NixflexAuthenticationError), (402, NixflexPaymentRequiredError), (404, NixflexNotFoundError), (400, NixflexInvalidRequestError), (422, NixflexInvalidRequestError), (503, NixflexServerError)]
+    for status, cls in cases:
+        with client_with(lambda req, s=status: httpx.Response(s, json=ERR("x_code", "why"), headers={"x-railway-request-id": "req-1"}), max_retries=0) as c:
+            with pytest.raises(cls) as ei:
+                c.agents.get("a1")
+            e = ei.value
+            assert e.status == status and e.code == "x_code" and str(e) == "why" and e.request_id == "req-1"
+            assert e.doc_url.endswith("/x_code")
+
+
+def test_429_retries_once_honouring_retry_after():
+    calls = []
+
+    def handler(req):
+        calls.append(time.monotonic())
+        if len(calls) == 1:
+            return httpx.Response(429, json=ERR("rate_limit_exceeded", typ="rate_limit"), headers={"retry-after": "1"})
+        return httpx.Response(200, json={"ok": True})
+
+    with client_with(handler) as c:
+        assert c.agents.get("a1") == {"ok": True}
+    assert len(calls) == 2 and (calls[1] - calls[0]) >= 0.9
+
+
+def test_429_exhausted_raises_with_retry_after_seconds():
+    with client_with(lambda req: httpx.Response(429, json=ERR("rate_limit_exceeded", typ="rate_limit"), headers={"retry-after": "7"}), max_retries=0) as c:
+        with pytest.raises(NixflexRateLimitError) as ei:
+            c.usage.get()
+    assert ei.value.retry_after_seconds == 7
+
+
+def test_5xx_retries_GET_but_never_POST():
+    n = {"get": 0, "post": 0}
+
+    def handler(req):
+        n[req.method.lower()] += 1
+        return httpx.Response(502, json=ERR("upstream", typ="server_error"))
+
+    with client_with(handler) as c:
+        with pytest.raises(NixflexServerError):
+            c.agents.get("a1")
+        with pytest.raises(NixflexServerError):
+            c.calls.create(agent_id="a1", to_number="+447700900123", prompt="hi")
+    assert n["get"] == 2, "GET must retry once on 5xx"
+    assert n["post"] == 1, "POST must NEVER be retried after a 5xx - a call could be dialled twice"
+
+
+def test_network_failure_retries_then_connection_error():
+    n = {"c": 0}
+
+    def handler(req):
+        n["c"] += 1
+        raise httpx.ConnectError("refused")
+
+    with client_with(handler) as c:
+        with pytest.raises(NixflexConnectionError) as ei:
+            c.usage.get()
+    assert n["c"] == 2 and ei.value.status == 0
+
+
+def test_204_returns_none_and_none_query_values_are_dropped():
+    seen = {}
+
+    def handler(req):
+        seen["q"] = req.url.query.decode()
+        return httpx.Response(204)
+
+    with client_with(handler) as c:
+        assert c.agents.list() is None
+    assert seen["q"] == ""
+
+
+def test_import_and_set_bodies():
+    seen = {}
+
+    def handler(req):
+        seen[req.url.raw_path.decode()] = json.loads(req.content)
+        return httpx.Response(200, json={})
+
+    with client_with(handler) as c:
+        c.callers.set("+447450307843", "+447453573770", name="Sam Carter", email=None)
+        c.callers.import_("+447450307843", [{"caller_number": "+447700900002", "name": "Priya"}])
+        c.webhooks.set("+447450307843", "https://x.example/hook", slot=2)
+    assert seen["/v1/phone-numbers/%2B447450307843/callers/%2B447453573770"] == {"name": "Sam Carter", "email": None}
+    assert seen["/v1/phone-numbers/%2B447450307843/callers/import"] == {"callers": [{"caller_number": "+447700900002", "name": "Priya"}]}
+    assert "/v1/integrations/webhook2/number/%2B447450307843" in seen
+
+
+async def test_async_client_same_behaviour():
+    n = {"c": 0}
+
+    def handler(req):
+        n["c"] += 1
+        if n["c"] == 1:
+            return httpx.Response(429, json=ERR("rate_limit_exceeded", typ="rate_limit"), headers={"retry-after": "0"})
+        return httpx.Response(200, json={"plan": "pay_as_you_go"})
+
+    async with AsyncNixflex(api_key=KEY, transport=httpx.MockTransport(handler)) as c:
+        assert await c.usage.get() == {"plan": "pay_as_you_go"}
+    assert n["c"] == 2
+
+
+def test_every_resource_and_method_exists():
+    """The Python surface must equal the Node SDK's API methods (snake_case; import -> import_). 44 API methods + verify_webhook_signature as a module function (Node has webhooks.verify)."""
+    expected = {
+        "agents": ["create", "list", "get", "update", "delete"],
+        "calls": ["create", "list", "get", "delete", "delete_all"],
+        "campaigns": ["create", "launch"],
+        "phone_numbers": ["import_", "list", "update", "delete", "set_monitor", "get_monitor", "set_web_calls", "get_web_calls"],
+        "callers": ["get", "set", "delete", "import_"],
+        "sms": ["send"], "sms.campaigns": ["create", "launch", "list", "get", "delete"],
+        "keys": ["rotate"], "usage": ["get"], "webhooks": ["set", "get", "delete"],
+        "storage": ["set", "get", "delete"], "llm": ["set", "get", "delete"], "tts": ["set", "get", "delete"],
+    }
+    c = Nixflex(api_key=KEY, transport=httpx.MockTransport(lambda r: httpx.Response(200, json={})))
+    total = 0
+    for res, methods in expected.items():
+        obj = c
+        for part in res.split("."):
+            obj = getattr(obj, part)
+        for m in methods:
+            assert callable(getattr(obj, m)), f"{res}.{m} missing"
+            total += 1
+    assert total == 44
+    from nixflex import verify_webhook_signature
+    assert callable(verify_webhook_signature)

nixflex-0.1.0/tests/test_webhook.py

@@ -0,0 +1,40 @@
+import hashlib
+import hmac
+
+from nixflex import verify_webhook_signature
+
+SECRET = "nxfs_test_secret"
+BODY = b'{"event":"call.ended","call_id":"CA1"}'
+T = 1_788_600_000
+
+
+def sig(t=T, body=BODY, secret=SECRET):
+    return "t=%d,v1=%s" % (t, hmac.new(secret.encode(), f"{t}.".encode() + body, hashlib.sha256).hexdigest())
+
+
+def test_golden_vector_matches_node_scheme():
+    # Same inputs as the Node SDK's golden vector: HMAC-SHA256 of "<ts>.<raw_body>".
+    assert verify_webhook_signature(BODY, sig(), SECRET, now=T)
+
+
+def test_str_body_and_bytes_body_agree():
+    assert verify_webhook_signature(BODY.decode(), sig(), SECRET, now=T)
+
+
+def test_rejects_wrong_secret_tampered_body_and_bad_header():
+    assert not verify_webhook_signature(BODY, sig(), "other", now=T)
+    assert not verify_webhook_signature(BODY + b" ", sig(), SECRET, now=T)
+    assert not verify_webhook_signature(BODY, "garbage", SECRET, now=T)
+    assert not verify_webhook_signature(BODY, None, SECRET, now=T)
+    assert not verify_webhook_signature(BODY, sig(), "", now=T)
+
+
+def test_replay_window():
+    assert verify_webhook_signature(BODY, sig(), SECRET, now=T + 299)
+    assert not verify_webhook_signature(BODY, sig(), SECRET, now=T + 301)
+    assert not verify_webhook_signature(BODY, sig(), SECRET, now=T - 301)
+    assert verify_webhook_signature(BODY, sig(), SECRET, now=T + 1000, tolerance_seconds=2000)
+
+
+def test_never_raises():
+    assert verify_webhook_signature(None, sig(), SECRET, now=T) is False  # type: ignore[arg-type]