pilot-status 0.0.9__tar.gz

pilot_status-0.0.9/PKG-INFO

@@ -0,0 +1,137 @@
+Metadata-Version: 2.4
+Name: pilot-status
+Version: 0.0.9
+Summary: Official Python SDK for the Pilot Status public API.
+Author: Pilot Status
+License: MIT
+Project-URL: Homepage, https://pilotstatus.online
+Project-URL: Repository, https://github.com/pilot-status/pilot-status
+Project-URL: Issues, https://github.com/pilot-status/pilot-status/issues
+Keywords: pilot-status,whatsapp,api,sdk,python
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: typing-extensions>=4.8.0
+
+# pilot-status (Python SDK)
+
+Official Python SDK for the Pilot Status public API.
+
+## Installation
+
+```bash
+pip install pilot-status
+```
+
+## Quickstart
+
+Create an API key in the dashboard and use it only on the backend.
+
+```python
+import os
+
+from pilot_status import PilotStatusClient
+
+client = PilotStatusClient(
+    api_key=os.environ["PILOT_STATUS_API_KEY"],
+)
+
+accepted = client.messages.send(
+    {
+        "templateId": "onboarding-test",
+        "destinationNumber": "+5511999999999",
+        "variables": {"name": "John"},
+    }
+)
+
+message = client.messages.get(accepted["id"])
+print(message["status"])
+```
+
+## Management (projects, API keys, numbers)
+
+These endpoints create resources within the scope (project + environment) of the current `api_key`.
+
+### Projects
+
+```python
+project = client.projects.create(
+    {
+        "name": "My Project",
+        "description": "Optional description",
+    }
+)
+
+projects = client.projects.list()
+```
+
+### API keys
+
+```python
+key = client.api_keys.create(
+    {
+        "name": "Backend Key",
+        "retentionDays": 30,
+    }
+)
+
+keys = client.api_keys.list()
+```
+
+### Numbers (WhatsApp)
+
+```python
+created = client.numbers.create(
+    {
+        "name": "My WhatsApp",
+        "number": "+5511999999999",
+    }
+)
+# created["qrcodeBase64"], created["pairingCode"] (letter code or None)
+
+refreshed = client.numbers.connect(created["instance"]["id"])
+# refreshed["qrcodeBase64"], refreshed["pairingCode"]
+
+status = client.numbers.get_status(created["instance"]["id"])
+print(status["state"])
+```
+
+## Opt-in check (destination authorization)
+
+In LIVE, sending may require opt-in when using the Pilot Status WhatsApp number. You can check whether a destination is already authorized for your project:
+
+```python
+opt_in = client.messages.check_opt_in("+5511999999999")
+if not opt_in["authorized"]:
+    raise Exception(f"Missing opt-in: {opt_in['reason']}")
+```
+
+## Analytics
+
+```python
+stats = client.analytics.get_dashboard_stats(tz="America/Sao_Paulo")
+print(stats["totalSent"], stats["failureRate"])
+```
+
+## Webhooks (parse / validation)
+
+```python
+from pilot_status import parse_customer_webhook
+
+def handler(payload: dict):
+    event = parse_customer_webhook(payload)
+
+    if event["event"] == "message.failed":
+        print(event["data"]["errorMessage"])
+```
+
+Notes:
+- Customer webhook payloads do not include: `projectSlug`, `lastMessageId`. Optional `correlationId` (same as HTTP 202 when present) may appear on outbound status events and on `message.reply` / `message.received` when correlated to a prior send.
+- `message.received` includes `fromMe` (boolean).
+- `message.group` is delivered for inbound group messages (includes `groupName`).
+- Supported events in the parser: `message.sent`, `message.delivered`, `message.read`, `message.failed`, `message.reply`, `message.received`, `message.group`, `optin.created`.

pilot_status-0.0.9/README.md

@@ -0,0 +1,117 @@
+# pilot-status (Python SDK)
+
+Official Python SDK for the Pilot Status public API.
+
+## Installation
+
+```bash
+pip install pilot-status
+```
+
+## Quickstart
+
+Create an API key in the dashboard and use it only on the backend.
+
+```python
+import os
+
+from pilot_status import PilotStatusClient
+
+client = PilotStatusClient(
+    api_key=os.environ["PILOT_STATUS_API_KEY"],
+)
+
+accepted = client.messages.send(
+    {
+        "templateId": "onboarding-test",
+        "destinationNumber": "+5511999999999",
+        "variables": {"name": "John"},
+    }
+)
+
+message = client.messages.get(accepted["id"])
+print(message["status"])
+```
+
+## Management (projects, API keys, numbers)
+
+These endpoints create resources within the scope (project + environment) of the current `api_key`.
+
+### Projects
+
+```python
+project = client.projects.create(
+    {
+        "name": "My Project",
+        "description": "Optional description",
+    }
+)
+
+projects = client.projects.list()
+```
+
+### API keys
+
+```python
+key = client.api_keys.create(
+    {
+        "name": "Backend Key",
+        "retentionDays": 30,
+    }
+)
+
+keys = client.api_keys.list()
+```
+
+### Numbers (WhatsApp)
+
+```python
+created = client.numbers.create(
+    {
+        "name": "My WhatsApp",
+        "number": "+5511999999999",
+    }
+)
+# created["qrcodeBase64"], created["pairingCode"] (letter code or None)
+
+refreshed = client.numbers.connect(created["instance"]["id"])
+# refreshed["qrcodeBase64"], refreshed["pairingCode"]
+
+status = client.numbers.get_status(created["instance"]["id"])
+print(status["state"])
+```
+
+## Opt-in check (destination authorization)
+
+In LIVE, sending may require opt-in when using the Pilot Status WhatsApp number. You can check whether a destination is already authorized for your project:
+
+```python
+opt_in = client.messages.check_opt_in("+5511999999999")
+if not opt_in["authorized"]:
+    raise Exception(f"Missing opt-in: {opt_in['reason']}")
+```
+
+## Analytics
+
+```python
+stats = client.analytics.get_dashboard_stats(tz="America/Sao_Paulo")
+print(stats["totalSent"], stats["failureRate"])
+```
+
+## Webhooks (parse / validation)
+
+```python
+from pilot_status import parse_customer_webhook
+
+def handler(payload: dict):
+    event = parse_customer_webhook(payload)
+
+    if event["event"] == "message.failed":
+        print(event["data"]["errorMessage"])
+```
+
+Notes:
+- Customer webhook payloads do not include: `projectSlug`, `lastMessageId`. Optional `correlationId` (same as HTTP 202 when present) may appear on outbound status events and on `message.reply` / `message.received` when correlated to a prior send.
+- `message.received` includes `fromMe` (boolean).
+- `message.group` is delivered for inbound group messages (includes `groupName`).
+- Supported events in the parser: `message.sent`, `message.delivered`, `message.read`, `message.failed`, `message.reply`, `message.received`, `message.group`, `optin.created`.

pilot_status-0.0.9/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pilot-status"
+version = "0.0.9"
+description = "Official Python SDK for the Pilot Status public API."
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = ["typing-extensions>=4.8.0"]
+license = { text = "MIT" }
+authors = [{ name = "Pilot Status" }]
+keywords = ["pilot-status", "whatsapp", "api", "sdk", "python"]
+classifiers = [
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+]
+
+[project.urls]
+Homepage = "https://pilotstatus.online"
+Repository = "https://github.com/pilot-status/pilot-status"
+Issues = "https://github.com/pilot-status/pilot-status/issues"
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+
+[tool.setuptools.packages.find]
+where = ["src"]

pilot_status-0.0.9/setup.cfg

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

pilot_status-0.0.9/src/pilot_status/__init__.py

@@ -0,0 +1,76 @@
+from .client import PilotStatusClient
+from .errors import (
+    AuthenticationError,
+    ConflictError,
+    ForbiddenError,
+    NotFoundError,
+    PilotStatusError,
+    PilotStatusHttpError,
+    RateLimitError,
+    ServerError,
+    ValidationError,
+)
+from .types import (
+    ApiKeyCreateInput,
+    ApiKeyCreated,
+    ApiKeyListItem,
+    DashboardStats,
+    CreateNumberInput,
+    CreateNumberResult,
+    CreateProjectInput,
+    Environment,
+    MessageDetails,
+    MessageStatus,
+    NumberConnectResult,
+    NumberStatusResult,
+    OptInCheckResult,
+    Project,
+    SendMessageAccepted,
+    SendMessageInput,
+    WhatsAppNumberInstance,
+)
+from .webhooks.parse import is_customer_webhook_event, parse_customer_webhook
+from .webhooks.types import (
+    CustomerWebhookEvent,
+    MessageFailedEvent,
+    MessageReadEvent,
+    MessageReplyEvent,
+    MessageSentEvent,
+)
+
+__all__ = [
+    "PilotStatusClient",
+    "PilotStatusError",
+    "PilotStatusHttpError",
+    "AuthenticationError",
+    "ValidationError",
+    "ForbiddenError",
+    "NotFoundError",
+    "ConflictError",
+    "RateLimitError",
+    "ServerError",
+    "Environment",
+    "MessageStatus",
+    "SendMessageInput",
+    "SendMessageAccepted",
+    "MessageDetails",
+    "DashboardStats",
+    "OptInCheckResult",
+    "Project",
+    "CreateProjectInput",
+    "ApiKeyCreateInput",
+    "ApiKeyCreated",
+    "ApiKeyListItem",
+    "WhatsAppNumberInstance",
+    "CreateNumberInput",
+    "CreateNumberResult",
+    "NumberConnectResult",
+    "NumberStatusResult",
+    "CustomerWebhookEvent",
+    "MessageSentEvent",
+    "MessageReadEvent",
+    "MessageFailedEvent",
+    "MessageReplyEvent",
+    "parse_customer_webhook",
+    "is_customer_webhook_event",
+]

pilot_status-0.0.9/src/pilot_status/client.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+from typing import Callable
+
+import urllib.request
+
+from .http import HttpClient, HttpClientOptions
+from .resources import AnalyticsResource, ApiKeysResource, MessagesResource, NumbersResource, ProjectsResource
+
+
+class PilotStatusClient:
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        timeout_s: float = 30.0,
+        user_agent: str | None = None,
+        get_retries: int = 2,
+        transport: Callable[[urllib.request.Request, float], tuple[int, dict[str, str], str]] | None = None,
+    ):
+        base_url = "https://pilotstatus.online"
+        http = HttpClient(
+            HttpClientOptions(
+                base_url=base_url,
+                api_key=api_key,
+                timeout_s=timeout_s,
+                user_agent=user_agent,
+                get_retries=get_retries,
+                transport=transport,
+            )
+        )
+        self.messages = MessagesResource(http)
+        self.analytics = AnalyticsResource(http)
+        self.projects = ProjectsResource(http)
+        self.api_keys = ApiKeysResource(http)
+        self.numbers = NumbersResource(http)

pilot_status-0.0.9/src/pilot_status/errors.py

@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+PilotStatusErrorBody = Any
+
+
+class PilotStatusError(Exception):
+    pass
+
+
+@dataclass(frozen=True)
+class PilotStatusHttpError(PilotStatusError):
+    message: str
+    status: int
+    method: str
+    url: str
+    headers: dict[str, str]
+    body: PilotStatusErrorBody | None = None
+    raw_body: str | None = None
+
+    def __str__(self) -> str:
+        return self.message
+
+
+class AuthenticationError(PilotStatusHttpError):
+    pass
+
+
+class ValidationError(PilotStatusHttpError):
+    pass
+
+
+class ForbiddenError(PilotStatusHttpError):
+    pass
+
+
+class NotFoundError(PilotStatusHttpError):
+    pass
+
+
+class ConflictError(PilotStatusHttpError):
+    pass
+
+
+class RateLimitError(PilotStatusHttpError):
+    pass
+
+
+class ServerError(PilotStatusHttpError):
+    pass
+
+
+def create_http_error(
+    *,
+    message: str,
+    status: int,
+    method: str,
+    url: str,
+    headers: dict[str, str],
+    body: PilotStatusErrorBody | None = None,
+    raw_body: str | None = None,
+) -> PilotStatusHttpError:
+    if status == 401:
+        return AuthenticationError(message, status, method, url, headers, body, raw_body)
+    if status == 400:
+        return ValidationError(message, status, method, url, headers, body, raw_body)
+    if status == 403:
+        return ForbiddenError(message, status, method, url, headers, body, raw_body)
+    if status == 404:
+        return NotFoundError(message, status, method, url, headers, body, raw_body)
+    if status == 409:
+        return ConflictError(message, status, method, url, headers, body, raw_body)
+    if status == 429:
+        return RateLimitError(message, status, method, url, headers, body, raw_body)
+    if status >= 500:
+        return ServerError(message, status, method, url, headers, body, raw_body)
+    return PilotStatusHttpError(message, status, method, url, headers, body, raw_body)
+

pilot_status-0.0.9/src/pilot_status/http.py

@@ -0,0 +1,156 @@
+from __future__ import annotations
+
+import json
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from dataclasses import dataclass
+from typing import Any, Callable, Mapping
+
+from .errors import create_http_error
+
+
+@dataclass(frozen=True)
+class HttpClientOptions:
+    base_url: str
+    api_key: str
+    timeout_s: float
+    user_agent: str | None
+    get_retries: int
+    transport: Callable[[urllib.request.Request, float], tuple[int, Mapping[str, str], str]] | None = None
+
+
+def _normalize_base_url(base_url: str) -> str:
+    return base_url.rstrip("/")
+
+
+def _join_url(base_url: str, path: str) -> str:
+    base = _normalize_base_url(base_url)
+    if not path.startswith("/"):
+        return f"{base}/{path}"
+    return f"{base}{path}"
+
+
+def _build_url(
+    base_url: str,
+    path: str,
+    query: Mapping[str, str | int | float | bool | None] | None,
+) -> str:
+    url = _join_url(base_url, path)
+    if not query:
+        return url
+    parts = list(urllib.parse.urlsplit(url))
+    current = urllib.parse.parse_qsl(parts[3], keep_blank_values=True)
+    for k, v in query.items():
+        if v is None:
+            continue
+        current.append((k, str(v)))
+    parts[3] = urllib.parse.urlencode(current)
+    return urllib.parse.urlunsplit(parts)
+
+
+def _parse_json_if_possible(text: str) -> Any:
+    trimmed = text.strip()
+    if not trimmed:
+        return None
+    try:
+        return json.loads(trimmed)
+    except Exception:
+        return None
+
+
+def _default_transport(req: urllib.request.Request, timeout_s: float) -> tuple[int, Mapping[str, str], str]:
+    with urllib.request.urlopen(req, timeout=timeout_s) as res:
+        status = int(getattr(res, "status", 200))
+        headers = {k.lower(): v for k, v in dict(res.headers).items()}
+        raw = res.read().decode("utf-8", errors="replace")
+        return status, headers, raw
+
+
+def _should_retry(method: str, status: int | None) -> bool:
+    if method != "GET":
+        return False
+    if status is None:
+        return True
+    return status >= 500
+
+
+class HttpClient:
+    def __init__(self, options: HttpClientOptions):
+        self._base_url = _normalize_base_url(options.base_url)
+        self._api_key = options.api_key
+        self._timeout_s = options.timeout_s
+        self._user_agent = options.user_agent
+        self._get_retries = options.get_retries
+        self._transport = options.transport or _default_transport
+
+    def request_json(
+        self,
+        *,
+        method: str,
+        path: str,
+        query: Mapping[str, str | int | float | bool | None] | None = None,
+        body: Any | None = None,
+    ) -> Any:
+        url = _build_url(self._base_url, path, query)
+
+        headers: dict[str, str] = {
+            "x-api-key": self._api_key,
+            "accept": "application/json",
+        }
+        if self._user_agent:
+            headers["user-agent"] = self._user_agent
+
+        data: bytes | None = None
+        if body is not None:
+            headers["content-type"] = "application/json"
+            data = json.dumps(body).encode("utf-8")
+
+        req = urllib.request.Request(url=url, data=data, method=method, headers=headers)
+
+        attempt = 0
+        while True:
+            status: int | None = None
+            response_headers: Mapping[str, str] = {}
+            raw: str = ""
+            try:
+                status, response_headers, raw = self._transport(req, self._timeout_s)
+            except urllib.error.HTTPError as e:
+                status = int(getattr(e, "code", 0) or 0) or None
+                response_headers = {k.lower(): v for k, v in dict(getattr(e, "headers", {}) or {}).items()}
+                raw = (e.read() or b"").decode("utf-8", errors="replace")
+            except urllib.error.URLError as e:
+                if attempt >= self._get_retries or not _should_retry(method, None):
+                    raise e
+                backoff_ms = 250 * (2**attempt)
+                time.sleep(backoff_ms / 1000.0)
+                attempt += 1
+                continue
+
+            parsed = _parse_json_if_possible(raw)
+
+            if status is None or not (200 <= status < 300):
+                message = None
+                if isinstance(parsed, dict) and isinstance(parsed.get("error"), str):
+                    message = str(parsed["error"])
+                if not message:
+                    message = f"HTTP {status}" if status is not None else "HTTP error"
+                err = create_http_error(
+                    message=message,
+                    status=int(status or 0),
+                    method=method,
+                    url=url,
+                    headers=dict(response_headers),
+                    body=parsed,
+                    raw_body=raw or None,
+                )
+                if attempt < self._get_retries and _should_retry(method, err.status):
+                    backoff_ms = 250 * (2**attempt)
+                    time.sleep(backoff_ms / 1000.0)
+                    attempt += 1
+                    continue
+                raise err
+
+            return parsed
+

pilot_status-0.0.9/src/pilot_status/resources/__init__.py

@@ -0,0 +1,13 @@
+from .analytics import AnalyticsResource
+from .api_keys import ApiKeysResource
+from .messages import MessagesResource
+from .numbers import NumbersResource
+from .projects import ProjectsResource
+
+__all__ = [
+    "MessagesResource",
+    "AnalyticsResource",
+    "ProjectsResource",
+    "ApiKeysResource",
+    "NumbersResource",
+]

pilot_status-0.0.9/src/pilot_status/resources/analytics.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+from ..http import HttpClient
+from ..types import DashboardStats
+
+
+class AnalyticsResource:
+    def __init__(self, http: HttpClient):
+        self._http = http
+
+    def get_dashboard_stats(self, *, tz: str | None = None) -> DashboardStats:
+        query = None if tz is None else {"tz": tz}
+        return self._http.request_json(method="GET", path="/v1/analytics/dashboard", query=query)

pilot_status-0.0.9/src/pilot_status/resources/api_keys.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from typing import Any
+
+from ..http import HttpClient
+from ..types import ApiKeyCreateInput, ApiKeyCreated, ApiKeyListItem
+
+
+class ApiKeysResource:
+    def __init__(self, http: HttpClient):
+        self._http = http
+
+    def list(self) -> list[ApiKeyListItem]:
+        return self._http.request_json(method="GET", path="/v1/api-keys")
+
+    def create(self, input: ApiKeyCreateInput) -> ApiKeyCreated:
+        body: dict[str, Any] = {"name": input["name"]}
+        if "webhookId" in input:
+            body["webhookId"] = input["webhookId"]
+        if "whatsappInstanceId" in input:
+            body["whatsappInstanceId"] = input["whatsappInstanceId"]
+        if "retentionDays" in input:
+            body["retentionDays"] = input["retentionDays"]
+        return self._http.request_json(method="POST", path="/v1/api-keys", body=body)