blueticks 1.0.0__tar.gz

blueticks-1.0.0/LICENSE

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

blueticks-1.0.0/PKG-INFO

@@ -0,0 +1,75 @@
+Metadata-Version: 2.4
+Name: blueticks
+Version: 1.0.0
+Summary: Official Python client for the Blueticks API.
+Author-email: Blueticks <support@blueticks.co>
+License: MIT License
+        
+        Copyright (c) 2026 serenix-com
+        
+        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.
+        
+Project-URL: Homepage, https://blueticks.co
+Project-URL: Documentation, https://docs.blueticks.co
+Project-URL: Source, https://github.com/serenix-com/blueticks-python
+Project-URL: Changelog, https://github.com/serenix-com/blueticks-python/blob/main/CHANGELOG.md
+Keywords: blueticks,whatsapp,api,sdk
+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: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx<1.0,>=0.27
+Requires-Dist: pydantic<3.0,>=2.6
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-httpx>=0.30; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Dynamic: license-file
+
+# blueticks — Python client for the Blueticks API
+
+Official Python SDK for [Blueticks](https://blueticks.co).
+
+## Install
+
+```bash
+pip install blueticks
+```
+
+## Quickstart
+
+```python
+from blueticks import Blueticks
+
+client = Blueticks(api_key="bt_live_...")
+ping = client.ping()
+account = client.account.retrieve()
+print(account.name)
+```
+
+See https://docs.blueticks.co for full documentation.

blueticks-1.0.0/README.md

@@ -0,0 +1,22 @@
+# blueticks — Python client for the Blueticks API
+
+Official Python SDK for [Blueticks](https://blueticks.co).
+
+## Install
+
+```bash
+pip install blueticks
+```
+
+## Quickstart
+
+```python
+from blueticks import Blueticks
+
+client = Blueticks(api_key="bt_live_...")
+ping = client.ping()
+account = client.account.retrieve()
+print(account.name)
+```
+
+See https://docs.blueticks.co for full documentation.

blueticks-1.0.0/pyproject.toml

@@ -0,0 +1,65 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "blueticks"
+dynamic = ["version"]
+description = "Official Python client for the Blueticks API."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { file = "LICENSE" }
+authors = [{ name = "Blueticks", email = "support@blueticks.co" }]
+keywords = ["blueticks", "whatsapp", "api", "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",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+  "httpx>=0.27,<1.0",
+  "pydantic>=2.6,<3.0",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.0",
+  "pytest-httpx>=0.30",
+  "ruff>=0.5",
+  "mypy>=1.10",
+]
+
+[project.urls]
+Homepage = "https://blueticks.co"
+Documentation = "https://docs.blueticks.co"
+Source = "https://github.com/serenix-com/blueticks-python"
+Changelog = "https://github.com/serenix-com/blueticks-python/blob/main/CHANGELOG.md"
+
+[tool.setuptools.dynamic]
+version = { attr = "blueticks._version.__version__" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+blueticks = ["py.typed"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py39"
+
+[tool.ruff.lint]
+select = ["A", "B", "E", "F", "I", "UP", "W"]
+
+[tool.mypy]
+python_version = "3.9"
+strict = true
+warn_return_any = true
+warn_unused_ignores = true
+files = ["src/blueticks"]

blueticks-1.0.0/setup.cfg

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

blueticks-1.0.0/src/blueticks/__init__.py

@@ -0,0 +1,25 @@
+from blueticks._client import Blueticks
+from blueticks._errors import (
+    APIConnectionError,
+    APIError,
+    AuthenticationError,
+    BadRequestError,
+    BluetickError,
+    NotFoundError,
+    PermissionDeniedError,
+    RateLimitError,
+)
+from blueticks._version import __version__
+
+__all__ = [
+    "APIConnectionError",
+    "APIError",
+    "AuthenticationError",
+    "BadRequestError",
+    "Blueticks",
+    "BluetickError",
+    "NotFoundError",
+    "PermissionDeniedError",
+    "RateLimitError",
+    "__version__",
+]

blueticks-1.0.0/src/blueticks/_base_resource.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from blueticks._client import Blueticks
+
+
+class BaseResource:
+    """Shared plumbing for all resource classes. Holds a reference to the parent client."""
+
+    def __init__(self, client: Blueticks) -> None:
+        self._client = client

blueticks-1.0.0/src/blueticks/_client.py

@@ -0,0 +1,101 @@
+from __future__ import annotations
+
+import os
+from typing import TYPE_CHECKING, Any
+
+import httpx
+
+if TYPE_CHECKING:
+    from blueticks.types.ping import Ping
+
+from blueticks._errors import BluetickError
+from blueticks._transport import Transport
+from blueticks._version import __version__
+
+_DEFAULT_BASE_URL = "https://api.blueticks.co"
+_DEFAULT_TIMEOUT = 30.0
+_DEFAULT_MAX_RETRIES = 2
+
+
+class Blueticks:
+    """Synchronous client for the Blueticks API."""
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str | None = None,
+        timeout: float = _DEFAULT_TIMEOUT,
+        max_retries: int = _DEFAULT_MAX_RETRIES,
+        user_agent: str | None = None,
+        _http_transport: httpx.BaseTransport | None = None,
+    ) -> None:
+        resolved_key = api_key if api_key is not None else os.environ.get("BLUETICKS_API_KEY")
+        if not resolved_key:
+            raise BluetickError(
+                status_code=None,
+                code="authentication_required",
+                message=(
+                    "No api_key provided. Pass Blueticks(api_key=...) "
+                    "or set BLUETICKS_API_KEY in your environment."
+                ),
+                request_id=None,
+            )
+        self._api_key = resolved_key
+
+        resolved_base = (
+            base_url
+            if base_url is not None
+            else os.environ.get("BLUETICKS_BASE_URL") or _DEFAULT_BASE_URL
+        )
+        self._base_url = resolved_base
+
+        self._transport = Transport(
+            api_key=self._api_key,
+            base_url=self._base_url,
+            timeout=timeout,
+            max_retries=max_retries,
+            user_agent_suffix=user_agent,
+            version=__version__,
+            http_transport=_http_transport,
+        )
+
+        # Lazy-imported to avoid import cycles and to keep core import cheap.
+        from blueticks.resources.account import AccountResource
+
+        self.account = AccountResource(self)
+
+    # -- Public API ----------------------------------------------------------
+
+    def ping(self) -> Ping:
+        from blueticks.resources.ping import PingResource
+
+        return PingResource(self).retrieve()
+
+    def close(self) -> None:
+        self._transport.close()
+
+    def __enter__(self) -> Blueticks:
+        return self
+
+    def __exit__(self, *_: Any) -> None:
+        self.close()
+
+    # -- Internal ------------------------------------------------------------
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        body: dict[str, Any] | None = None,
+        idempotency_key: str | None = None,
+    ) -> Any:
+        return self._transport.request(
+            method,
+            path,
+            params=params,
+            body=body,
+            idempotency_key=idempotency_key,
+        )

blueticks-1.0.0/src/blueticks/_errors.py

@@ -0,0 +1,120 @@
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+
+class BluetickError(Exception):
+    """Base class for all Blueticks client errors."""
+
+    status_code: int | None
+    code: str | None
+    message: str
+    request_id: str | None
+    response: httpx.Response | None
+
+    def __init__(
+        self,
+        *,
+        status_code: int | None = None,
+        code: str | None = None,
+        message: str = "",
+        request_id: str | None = None,
+        response: httpx.Response | None = None,
+    ) -> None:
+        self.status_code = status_code
+        self.code = code
+        self.message = message
+        self.request_id = request_id
+        self.response = response
+        super().__init__(str(self))
+
+    def __str__(self) -> str:
+        return f"{self.status_code} {self.code}: {self.message} (request_id={self.request_id})"
+
+
+class AuthenticationError(BluetickError):
+    """401 — missing or invalid API key."""
+
+
+class PermissionDeniedError(BluetickError):
+    """403 — the key lacks the required scope or workspace access."""
+
+
+class NotFoundError(BluetickError):
+    """404 — the resource does not exist."""
+
+
+class BadRequestError(BluetickError):
+    """400 / 422 — the request was malformed or failed validation."""
+
+
+class RateLimitError(BluetickError):
+    """429 — the client is being throttled."""
+
+    retry_after: float | None
+
+    def __init__(self, *, retry_after: float | None = None, **kwargs: Any) -> None:
+        super().__init__(**kwargs)
+        self.retry_after = retry_after
+
+
+class APIError(BluetickError):
+    """5xx or otherwise-unparseable error response from the API."""
+
+
+class APIConnectionError(BluetickError):
+    """Network failure: DNS, TLS, timeout, connection reset."""
+
+
+_STATUS_TO_CLASS: dict[int, type[BluetickError]] = {
+    400: BadRequestError,
+    401: AuthenticationError,
+    403: PermissionDeniedError,
+    404: NotFoundError,
+    422: BadRequestError,
+    429: RateLimitError,
+}
+
+
+def _class_for_status(status: int) -> type[BluetickError]:
+    return _STATUS_TO_CLASS.get(status, APIError)
+
+
+def from_envelope(
+    *,
+    status_code: int,
+    body: Any,
+    response: httpx.Response | None,
+    retry_after: float | None = None,
+) -> BluetickError:
+    """Map a non-2xx response body to a typed Blueticks exception."""
+    cls = _class_for_status(status_code)
+
+    error = body.get("error") if isinstance(body, dict) else None
+    if isinstance(error, dict) and isinstance(error.get("code"), str):
+        kwargs: dict[str, Any] = {
+            "status_code": status_code,
+            "code": error.get("code"),
+            "message": error.get("message", ""),
+            "request_id": error.get("request_id"),
+            "response": response,
+        }
+        if cls is RateLimitError:
+            kwargs["retry_after"] = retry_after
+        return cls(**kwargs)
+
+    # Fallback: unknown shape. Render the body as a truncated string.
+    raw = body if isinstance(body, str) else repr(body)
+    truncated = raw[:200] + ("..." if len(raw) > 200 else "")
+    kwargs = {
+        "status_code": status_code,
+        "code": None,
+        "message": truncated,
+        "request_id": None,
+        "response": response,
+    }
+    if cls is RateLimitError:
+        kwargs["retry_after"] = retry_after
+    return cls(**kwargs)

blueticks-1.0.0/src/blueticks/_transport.py

@@ -0,0 +1,141 @@
+from __future__ import annotations
+
+import json
+import random
+import time
+from typing import Any
+
+import httpx
+
+from blueticks._errors import (
+    APIConnectionError,
+    from_envelope,
+)
+
+_RETRIABLE_STATUS = {429, 502, 503, 504}
+_IDEMPOTENT_METHODS = {"GET", "HEAD", "OPTIONS", "DELETE", "PATCH", "PUT"}
+# Note: PATCH is not strictly idempotent per RFC 5789 but most REST APIs treat
+# partial updates as idempotent in practice. Matches Stripe/OpenAI convention.
+_BACKOFF_BASE_SECONDS = 0.5
+_BACKOFF_CAP_SECONDS = 8.0
+
+
+class Transport:
+    """HTTP transport for the Blueticks API. Wraps httpx.Client with retries."""
+
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        base_url: str,
+        timeout: float,
+        max_retries: int,
+        user_agent_suffix: str | None,
+        version: str,
+        http_transport: httpx.BaseTransport | None = None,
+    ) -> None:
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._max_retries = max_retries
+        self._version = version
+        self._user_agent = f"blueticks-python/{version}"
+        if user_agent_suffix:
+            self._user_agent = f"{self._user_agent} {user_agent_suffix}"
+        self._client = httpx.Client(
+            base_url=self._base_url,
+            timeout=timeout,
+            transport=http_transport,
+        )
+
+    def close(self) -> None:
+        self._client.close()
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, Any] | None,
+        body: dict[str, Any] | None,
+        idempotency_key: str | None = None,
+    ) -> Any:
+        method = method.upper()
+        headers: dict[str, str] = {
+            "Authorization": f"Bearer {self._api_key}",
+            "User-Agent": self._user_agent,
+            "Accept": "application/json",
+        }
+        if body is not None:
+            headers["Content-Type"] = "application/json"
+        if idempotency_key:
+            headers["Idempotency-Key"] = idempotency_key
+
+        is_idempotent = method in _IDEMPOTENT_METHODS or idempotency_key is not None
+
+        attempt = 0
+        while True:
+            try:
+                response = self._client.request(
+                    method,
+                    path,
+                    params=params,
+                    content=json.dumps(body).encode() if body is not None else None,
+                    headers=headers,
+                )
+            except httpx.TransportError as exc:
+                if attempt < self._max_retries:
+                    self._sleep_backoff(attempt, retry_after=None)
+                    attempt += 1
+                    continue
+                raise APIConnectionError(
+                    status_code=None,
+                    code=None,
+                    message=f"connection error: {exc}",
+                    request_id=None,
+                    response=None,
+                ) from exc
+
+            if 200 <= response.status_code < 300:
+                if not response.content:
+                    return None
+                return response.json()
+
+            parsed_body: Any
+            try:
+                parsed_body = response.json()
+            except (json.JSONDecodeError, ValueError):
+                parsed_body = response.text
+
+            retry_after = self._parse_retry_after(response) if response.status_code == 429 else None
+
+            retriable_status = response.status_code in _RETRIABLE_STATUS
+            if retriable_status and is_idempotent and attempt < self._max_retries:
+                self._sleep_backoff(attempt, retry_after=retry_after)
+                attempt += 1
+                continue
+
+            raise from_envelope(
+                status_code=response.status_code,
+                body=parsed_body,
+                response=response,
+                retry_after=retry_after,
+            )
+
+    @staticmethod
+    def _parse_retry_after(response: httpx.Response) -> float | None:
+        raw = response.headers.get("retry-after")
+        if raw is None:
+            return None
+        try:
+            return float(raw)
+        except ValueError:
+            return None
+
+    @staticmethod
+    def _sleep_backoff(attempt: int, *, retry_after: float | None) -> None:
+        if retry_after is not None:
+            time.sleep(retry_after)
+            return
+        backoff = min(_BACKOFF_BASE_SECONDS * (2**attempt), _BACKOFF_CAP_SECONDS)
+        jitter = random.uniform(0, _BACKOFF_BASE_SECONDS)
+        time.sleep(backoff + jitter)

blueticks-1.0.0/src/blueticks/_version.py

@@ -0,0 +1 @@
+__version__ = "1.0.0"

blueticks-1.0.0/src/blueticks/resources/__init__.py

@@ -0,0 +1,4 @@
+from blueticks.resources.account import AccountResource
+from blueticks.resources.ping import PingResource
+
+__all__ = ["AccountResource", "PingResource"]

blueticks-1.0.0/src/blueticks/resources/account.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+from blueticks._base_resource import BaseResource
+from blueticks.types.account import Account
+
+
+class AccountResource(BaseResource):
+    def retrieve(self) -> Account:
+        """Retrieve the authenticated account.
+
+        Returns the account associated with the API key used for this request.
+        """
+        data = self._client._request("GET", "/v1/account")
+        return Account.model_validate(data)

blueticks-1.0.0/src/blueticks/resources/ping.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+from blueticks._base_resource import BaseResource
+from blueticks.types.ping import Ping
+
+
+class PingResource(BaseResource):
+    def retrieve(self) -> Ping:
+        """Health check.
+
+        Returns basic info about the authenticated API key.
+        """
+        data = self._client._request("GET", "/v1/ping")
+        return Ping.model_validate(data)

blueticks-1.0.0/src/blueticks/types/__init__.py

@@ -0,0 +1,4 @@
+from blueticks.types.account import Account
+from blueticks.types.ping import Ping
+
+__all__ = ["Account", "Ping"]

blueticks-1.0.0/src/blueticks/types/account.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Optional
+
+from pydantic import BaseModel, ConfigDict
+
+
+class Account(BaseModel):
+    """Response from GET /v1/account."""
+
+    model_config = ConfigDict(extra="ignore")
+
+    id: str
+    name: str
+    timezone: Optional[str] = None  # noqa: UP045
+    created_at: datetime

blueticks-1.0.0/src/blueticks/types/ping.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict
+
+
+class Ping(BaseModel):
+    """Response from GET /v1/ping."""
+
+    model_config = ConfigDict(extra="ignore")
+
+    account_id: str
+    key_prefix: str
+    scopes: list[str]

blueticks-1.0.0/src/blueticks.egg-info/PKG-INFO

@@ -0,0 +1,75 @@
+Metadata-Version: 2.4
+Name: blueticks
+Version: 1.0.0
+Summary: Official Python client for the Blueticks API.
+Author-email: Blueticks <support@blueticks.co>
+License: MIT License
+        
+        Copyright (c) 2026 serenix-com
+        
+        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.
+        
+Project-URL: Homepage, https://blueticks.co
+Project-URL: Documentation, https://docs.blueticks.co
+Project-URL: Source, https://github.com/serenix-com/blueticks-python
+Project-URL: Changelog, https://github.com/serenix-com/blueticks-python/blob/main/CHANGELOG.md
+Keywords: blueticks,whatsapp,api,sdk
+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: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx<1.0,>=0.27
+Requires-Dist: pydantic<3.0,>=2.6
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-httpx>=0.30; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Dynamic: license-file
+
+# blueticks — Python client for the Blueticks API
+
+Official Python SDK for [Blueticks](https://blueticks.co).
+
+## Install
+
+```bash
+pip install blueticks
+```
+
+## Quickstart
+
+```python
+from blueticks import Blueticks
+
+client = Blueticks(api_key="bt_live_...")
+ping = client.ping()
+account = client.account.retrieve()
+print(account.name)
+```
+
+See https://docs.blueticks.co for full documentation.

blueticks-1.0.0/src/blueticks.egg-info/SOURCES.txt

@@ -0,0 +1,26 @@
+LICENSE
+README.md
+pyproject.toml
+src/blueticks/__init__.py
+src/blueticks/_base_resource.py
+src/blueticks/_client.py
+src/blueticks/_errors.py
+src/blueticks/_transport.py
+src/blueticks/_version.py
+src/blueticks/py.typed
+src/blueticks.egg-info/PKG-INFO
+src/blueticks.egg-info/SOURCES.txt
+src/blueticks.egg-info/dependency_links.txt
+src/blueticks.egg-info/requires.txt
+src/blueticks.egg-info/top_level.txt
+src/blueticks/resources/__init__.py
+src/blueticks/resources/account.py
+src/blueticks/resources/ping.py
+src/blueticks/types/__init__.py
+src/blueticks/types/account.py
+src/blueticks/types/ping.py
+tests/test_account.py
+tests/test_client.py
+tests/test_errors.py
+tests/test_ping.py
+tests/test_transport.py

blueticks-1.0.0/src/blueticks.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

blueticks-1.0.0/src/blueticks.egg-info/requires.txt

@@ -0,0 +1,8 @@
+httpx<1.0,>=0.27
+pydantic<3.0,>=2.6
+
+[dev]
+pytest>=8.0
+pytest-httpx>=0.30
+ruff>=0.5
+mypy>=1.10

blueticks-1.0.0/src/blueticks.egg-info/top_level.txt

@@ -0,0 +1 @@
+blueticks

blueticks-1.0.0/tests/test_account.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+import json
+from datetime import datetime
+
+import httpx
+import pytest
+from pydantic import ValidationError
+
+from blueticks import AuthenticationError
+from blueticks.types.account import Account
+
+
+def test_account_retrieve_returns_typed_model(mock_client) -> None:
+    def handler(request: httpx.Request) -> httpx.Response:
+        assert request.method == "GET"
+        assert request.url.path == "/v1/account"
+        return httpx.Response(
+            200,
+            content=json.dumps(
+                {
+                    "id": "acc_1",
+                    "name": "Acme",
+                    "timezone": "America/New_York",
+                    "created_at": "2026-04-22T10:00:00Z",
+                }
+            ).encode(),
+            headers={"content-type": "application/json"},
+        )
+
+    with mock_client(handler) as client:
+        result = client.account.retrieve()
+    assert isinstance(result, Account)
+    assert result.id == "acc_1"
+    assert result.name == "Acme"
+    assert result.timezone == "America/New_York"
+    assert isinstance(result.created_at, datetime)
+
+
+def test_account_retrieve_accepts_null_timezone(mock_client) -> None:
+    def handler(_request: httpx.Request) -> httpx.Response:
+        return httpx.Response(
+            200,
+            content=json.dumps(
+                {
+                    "id": "acc_2",
+                    "name": "Nobody",
+                    "timezone": None,
+                    "created_at": "2026-01-01T00:00:00Z",
+                }
+            ).encode(),
+            headers={"content-type": "application/json"},
+        )
+
+    with mock_client(handler) as client:
+        result = client.account.retrieve()
+    assert result.timezone is None
+
+
+def test_account_retrieve_propagates_authentication_error(mock_client) -> None:
+    def handler(_request: httpx.Request) -> httpx.Response:
+        body = {
+            "error": {
+                "code": "authentication_required",
+                "message": "bad key",
+                "request_id": "req_a",
+            }
+        }
+        return httpx.Response(
+            401,
+            content=json.dumps(body).encode(),
+            headers={"content-type": "application/json"},
+        )
+
+    with mock_client(handler) as client:
+        with pytest.raises(AuthenticationError) as info:
+            client.account.retrieve()
+    assert info.value.code == "authentication_required"
+    assert info.value.message == "bad key"
+    assert info.value.request_id == "req_a"
+
+
+def test_account_retrieve_missing_required_field_raises_validation_error(mock_client) -> None:
+    def handler(_request: httpx.Request) -> httpx.Response:
+        return httpx.Response(200, content=b"{}", headers={"content-type": "application/json"})
+
+    with mock_client(handler) as client:
+        with pytest.raises(ValidationError):
+            client.account.retrieve()

blueticks-1.0.0/tests/test_client.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+import pytest
+
+from blueticks import Blueticks
+from blueticks._errors import BluetickError
+
+
+def test_constructor_accepts_api_key() -> None:
+    c = Blueticks(api_key="bt_live_x")
+    assert c._api_key == "bt_live_x"
+    c.close()
+
+
+def test_constructor_falls_back_to_env_var(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("BLUETICKS_API_KEY", "bt_test_env")
+    c = Blueticks()
+    assert c._api_key == "bt_test_env"
+    c.close()
+
+
+def test_constructor_raises_when_no_key(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.delenv("BLUETICKS_API_KEY", raising=False)
+    with pytest.raises(BluetickError) as info:
+        Blueticks()
+    assert "api_key" in str(info.value).lower() or "BLUETICKS_API_KEY" in str(info.value)
+
+
+def test_base_url_env_var_overrides_default(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("BLUETICKS_BASE_URL", "https://staging.example.test")
+    c = Blueticks(api_key="k")
+    assert c._base_url == "https://staging.example.test"
+    c.close()
+
+
+def test_explicit_base_url_overrides_env(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("BLUETICKS_BASE_URL", "https://env.example.test")
+    c = Blueticks(api_key="k", base_url="https://explicit.example.test")
+    assert c._base_url == "https://explicit.example.test"
+    c.close()
+
+
+def test_context_manager_closes_transport() -> None:
+    with Blueticks(api_key="k") as c:
+        transport = c._transport
+    assert transport._client.is_closed
+
+
+def test_default_base_url() -> None:
+    c = Blueticks(api_key="k")
+    assert c._base_url == "https://api.blueticks.co"
+    c.close()

blueticks-1.0.0/tests/test_errors.py

@@ -0,0 +1,101 @@
+from __future__ import annotations
+
+import pytest
+
+from blueticks._errors import (
+    APIConnectionError,
+    APIError,
+    AuthenticationError,
+    BadRequestError,
+    BluetickError,
+    NotFoundError,
+    PermissionDeniedError,
+    RateLimitError,
+    from_envelope,
+)
+
+
+def test_base_class_is_exception() -> None:
+    assert issubclass(BluetickError, Exception)
+
+
+def test_all_subclasses_inherit_bluetick_error() -> None:
+    for cls in [
+        AuthenticationError,
+        PermissionDeniedError,
+        NotFoundError,
+        BadRequestError,
+        RateLimitError,
+        APIError,
+        APIConnectionError,
+    ]:
+        assert issubclass(cls, BluetickError)
+
+
+def test_str_renders_status_code_and_request_id() -> None:
+    err = BluetickError(
+        status_code=401,
+        code="authentication_required",
+        message="bad key",
+        request_id="req_123",
+    )
+    assert str(err) == "401 authentication_required: bad key (request_id=req_123)"
+
+
+def test_str_handles_missing_request_id() -> None:
+    err = BluetickError(status_code=500, code="internal_error", message="boom", request_id=None)
+    assert "request_id=None" in str(err)
+
+
+@pytest.mark.parametrize(
+    "status,code,expected_cls",
+    [
+        (401, "authentication_required", AuthenticationError),
+        (403, "permission_denied", PermissionDeniedError),
+        (404, "not_found", NotFoundError),
+        (400, "invalid_request", BadRequestError),
+        (422, "invalid_request", BadRequestError),
+        (429, "rate_limited", RateLimitError),
+        (500, "internal_error", APIError),
+        (503, "internal_error", APIError),
+    ],
+)
+def test_from_envelope_maps_status_to_typed_exception(
+    status: int, code: str, expected_cls: type[BluetickError]
+) -> None:
+    err = from_envelope(
+        status_code=status,
+        body={"error": {"code": code, "message": "m", "request_id": "r"}},
+        response=None,
+    )
+    assert isinstance(err, expected_cls)
+    assert err.status_code == status
+    assert err.code == code
+    assert err.message == "m"
+    assert err.request_id == "r"
+
+
+def test_from_envelope_falls_back_when_body_has_no_error_key() -> None:
+    err = from_envelope(status_code=502, body={"weird": "shape"}, response=None)
+    assert isinstance(err, APIError)
+    assert err.code is None
+    # raw body, truncated
+    assert "weird" in err.message
+
+
+def test_from_envelope_truncates_long_bodies() -> None:
+    big = "x" * 500
+    err = from_envelope(status_code=500, body=big, response=None)
+    assert err.message.endswith("...")
+    assert len(err.message) == 203  # 200 chars + 3-char ellipsis
+
+
+def test_rate_limit_error_carries_retry_after() -> None:
+    err = RateLimitError(
+        status_code=429,
+        code="rate_limited",
+        message="slow down",
+        request_id=None,
+        retry_after=30.0,
+    )
+    assert err.retry_after == 30.0

blueticks-1.0.0/tests/test_ping.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+import json
+
+import httpx
+import pytest
+from pydantic import ValidationError
+
+from blueticks import AuthenticationError
+from blueticks.types.ping import Ping
+
+
+def test_ping_retrieve_returns_typed_model(mock_client) -> None:
+    def handler(request: httpx.Request) -> httpx.Response:
+        assert request.method == "GET"
+        assert request.url.path == "/v1/ping"
+        return httpx.Response(
+            200,
+            content=json.dumps(
+                {
+                    "account_id": "acc_abc",
+                    "key_prefix": "xy12ab34",
+                    "scopes": ["messages:read"],
+                }
+            ).encode(),
+            headers={"content-type": "application/json"},
+        )
+
+    with mock_client(handler) as client:
+        result = client.ping()
+    assert isinstance(result, Ping)
+    assert result.account_id == "acc_abc"
+    assert result.key_prefix == "xy12ab34"
+    assert result.scopes == ["messages:read"]
+
+
+def test_ping_propagates_authentication_error(mock_client) -> None:
+    def handler(_request: httpx.Request) -> httpx.Response:
+        body = {
+            "error": {
+                "code": "authentication_required",
+                "message": "bad key",
+                "request_id": "req_1",
+            }
+        }
+        return httpx.Response(
+            401,
+            content=json.dumps(body).encode(),
+            headers={"content-type": "application/json"},
+        )
+
+    with mock_client(handler) as client:
+        with pytest.raises(AuthenticationError) as info:
+            client.ping()
+    assert info.value.code == "authentication_required"
+    assert info.value.message == "bad key"
+    assert info.value.request_id == "req_1"
+
+
+def test_ping_missing_required_field_raises_validation_error(mock_client) -> None:
+    def handler(_request: httpx.Request) -> httpx.Response:
+        return httpx.Response(200, content=b"{}", headers={"content-type": "application/json"})
+
+    with mock_client(handler) as client:
+        with pytest.raises(ValidationError):
+            client.ping()

blueticks-1.0.0/tests/test_transport.py

@@ -0,0 +1,195 @@
+from __future__ import annotations
+
+import json
+from typing import Any
+
+import httpx
+import pytest
+
+from blueticks._errors import (
+    APIConnectionError,
+    APIError,
+    AuthenticationError,
+    RateLimitError,
+)
+from blueticks._transport import Transport
+
+
+def _envelope(code: str, message: str = "x", request_id: str = "req_1") -> bytes:
+    body = {"error": {"code": code, "message": message, "request_id": request_id}}
+    return json.dumps(body).encode()
+
+
+def _ok(body: Any) -> bytes:
+    return json.dumps(body).encode()
+
+
+def _mock(handler):
+    return httpx.MockTransport(handler)
+
+
+def _make_transport(mock: httpx.MockTransport, *, max_retries: int = 2) -> Transport:
+    return Transport(
+        api_key="bt_test_abc",
+        base_url="https://example.test",
+        timeout=5.0,
+        max_retries=max_retries,
+        user_agent_suffix=None,
+        version="1.0.0",
+        http_transport=mock,
+    )
+
+
+def test_get_returns_parsed_json_on_200() -> None:
+    def handler(request: httpx.Request) -> httpx.Response:
+        assert request.headers["authorization"] == "Bearer bt_test_abc"
+        assert "blueticks-python/1.0.0" in request.headers["user-agent"]
+        return httpx.Response(200, content=_ok({"hello": "world"}))
+
+    transport = _make_transport(_mock(handler))
+    result = transport.request("GET", "/v1/ping", params=None, body=None)
+    assert result == {"hello": "world"}
+
+
+def test_401_raises_authentication_error() -> None:
+    def handler(_request: httpx.Request) -> httpx.Response:
+        return httpx.Response(401, content=_envelope("authentication_required", "bad"))
+
+    transport = _make_transport(_mock(handler))
+    with pytest.raises(AuthenticationError) as info:
+        transport.request("GET", "/v1/ping", params=None, body=None)
+    assert info.value.code == "authentication_required"
+    assert info.value.message == "bad"
+
+
+def test_non_json_body_still_raises_api_error() -> None:
+    def handler(_request: httpx.Request) -> httpx.Response:
+        return httpx.Response(502, content=b"<html>bad gateway</html>")
+
+    transport = _make_transport(_mock(handler))
+    with pytest.raises(APIError) as info:
+        transport.request("GET", "/v1/ping", params=None, body=None)
+    assert info.value.status_code == 502
+
+
+def test_429_with_retry_after_retries_then_succeeds() -> None:
+    calls = {"n": 0}
+
+    def handler(_request: httpx.Request) -> httpx.Response:
+        calls["n"] += 1
+        if calls["n"] == 1:
+            return httpx.Response(
+                429,
+                headers={"retry-after": "0"},
+                content=_envelope("rate_limited", "slow"),
+            )
+        return httpx.Response(200, content=_ok({"ok": True}))
+
+    transport = _make_transport(_mock(handler), max_retries=3)
+    result = transport.request("GET", "/v1/ping", params=None, body=None)
+    assert result == {"ok": True}
+    assert calls["n"] == 2
+
+
+def test_429_exhausts_retries_and_raises_rate_limit() -> None:
+    def handler(_request: httpx.Request) -> httpx.Response:
+        return httpx.Response(429, headers={"retry-after": "0"}, content=_envelope("rate_limited"))
+
+    transport = _make_transport(_mock(handler), max_retries=1)
+    with pytest.raises(RateLimitError) as info:
+        transport.request("GET", "/v1/ping", params=None, body=None)
+    assert info.value.retry_after == 0.0
+
+
+def test_503_retries_then_succeeds() -> None:
+    calls = {"n": 0}
+
+    def handler(_request: httpx.Request) -> httpx.Response:
+        calls["n"] += 1
+        if calls["n"] == 1:
+            return httpx.Response(503, content=_envelope("internal_error"))
+        return httpx.Response(200, content=_ok({"ok": True}))
+
+    transport = _make_transport(_mock(handler), max_retries=2)
+    result = transport.request("GET", "/v1/ping", params=None, body=None)
+    assert result == {"ok": True}
+
+
+def test_post_does_not_retry_on_5xx_without_idempotency_key() -> None:
+    calls = {"n": 0}
+
+    def handler(_request: httpx.Request) -> httpx.Response:
+        calls["n"] += 1
+        return httpx.Response(503, content=_envelope("internal_error"))
+
+    transport = _make_transport(_mock(handler), max_retries=3)
+    with pytest.raises(APIError):
+        transport.request("POST", "/v1/messages", params=None, body={"x": 1})
+    assert calls["n"] == 1
+
+
+def test_connection_error_retries() -> None:
+    calls = {"n": 0}
+
+    def handler(_request: httpx.Request) -> httpx.Response:
+        calls["n"] += 1
+        if calls["n"] == 1:
+            raise httpx.ConnectError("dns fail")
+        return httpx.Response(200, content=_ok({"ok": True}))
+
+    transport = _make_transport(_mock(handler), max_retries=2)
+    result = transport.request("GET", "/v1/ping", params=None, body=None)
+    assert result == {"ok": True}
+
+
+def test_connection_error_exhausted_raises_api_connection_error() -> None:
+    def handler(_request: httpx.Request) -> httpx.Response:
+        raise httpx.ConnectError("dns fail")
+
+    transport = _make_transport(_mock(handler), max_retries=1)
+    with pytest.raises(APIConnectionError):
+        transport.request("GET", "/v1/ping", params=None, body=None)
+
+
+def test_user_agent_includes_suffix() -> None:
+    captured: dict[str, str] = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        captured["ua"] = request.headers["user-agent"]
+        return httpx.Response(200, content=_ok({}))
+
+    t = Transport(
+        api_key="k",
+        base_url="https://example.test",
+        timeout=5.0,
+        max_retries=0,
+        user_agent_suffix="myapp/1.2",
+        version="1.0.0",
+        http_transport=_mock(handler),
+    )
+    t.request("GET", "/v1/ping", params=None, body=None)
+    assert captured["ua"] == "blueticks-python/1.0.0 myapp/1.2"
+
+
+def test_query_params_are_sent() -> None:
+    captured: dict[str, Any] = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        captured["url"] = str(request.url)
+        return httpx.Response(200, content=_ok({}))
+
+    transport = _make_transport(_mock(handler))
+    transport.request("GET", "/v1/messages", params={"limit": 10}, body=None)
+    assert "limit=10" in captured["url"]
+
+
+def test_body_is_json_encoded() -> None:
+    captured: dict[str, Any] = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        captured["body"] = request.content
+        return httpx.Response(200, content=_ok({}))
+
+    transport = _make_transport(_mock(handler))
+    transport.request("POST", "/v1/messages", params=None, body={"text": "hi"})
+    assert json.loads(captured["body"]) == {"text": "hi"}