blueticks 1.0.0__py3-none-any.whl

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/_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/_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/_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/_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/_version.py

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

blueticks/resources/__init__.py

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

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/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/types/__init__.py

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

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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,18 @@
+blueticks/__init__.py,sha256=hmmpwdP3y-bD-NHJxeeKWbP7tvBuCE87y5Ye3BHCKs8,522
+blueticks/_base_resource.py,sha256=itU_RAahBEmY91XxGIQoBS0uNIZe5rq797GUyLInNRU,328
+blueticks/_client.py,sha256=-0NeYumrSuQWJkLK6TUO5GxQSi62DB8weo22j5m0A3g,2883
+blueticks/_errors.py,sha256=zSnzxyJNEbWtCgxio9VNosydYwkJ0o7okRkSXRYAD9E,3320
+blueticks/_transport.py,sha256=cbM8pSAZNv2jBfwe8pC0FBFvOVJHHfVxQzr22mkMk6o,4524
+blueticks/_version.py,sha256=J-j-u0itpEFT6irdmWmixQqYMadNl1X91TxUmoiLHMI,22
+blueticks/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+blueticks/resources/__init__.py,sha256=1AtiCuEvYCjHHOup_m9yC8Dbk_RAl0Y6cOUkx1YMEQw,153
+blueticks/resources/account.py,sha256=IXlD5KVbwYX4_wDhtkPRUPmP44oGxw2AmHF7H1gniDA,446
+blueticks/resources/ping.py,sha256=Ger2Kn37nmomnSDVgcpxGoXDqlMaNRl6TBPUGythz28,387
+blueticks/types/__init__.py,sha256=CrPKlrqRuiva695qZR2uU7z_56AL3UG1IxbWdfKFLx8,113
+blueticks/types/account.py,sha256=dMgKf6PhAxA1v8MYbvQgacm93Q615-2tYJy3l_MCGvY,356
+blueticks/types/ping.py,sha256=yUiZBRsa0IvYe4fhURwVM-dS-2pDZNUZsk5IE1Kx1pY,252
+blueticks-1.0.0.dist-info/licenses/LICENSE,sha256=N9gRIkVgfrCtyAj5rMQJcKxcBSbhqmycHvtHbpNWOso,1068
+blueticks-1.0.0.dist-info/METADATA,sha256=d0KHvdg4D-0ATI3Vl945HEiT-4S1Ih0lBqiSFH-eJ4E,2928
+blueticks-1.0.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+blueticks-1.0.0.dist-info/top_level.txt,sha256=Os-3VKE73EIGlrIrw37TpewHTTryFOZRrV2s71v5aPc,10
+blueticks-1.0.0.dist-info/RECORD,,

blueticks-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

blueticks-1.0.0.dist-info/licenses/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.dist-info/top_level.txt

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