pilot-status 0.0.9__py3-none-any.whl

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/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/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/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/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/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/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)

pilot_status/resources/messages.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+from typing import Any
+
+from ..http import HttpClient
+from ..types import MessageDetails, OptInCheckResult, SendMessageAccepted, SendMessageInput
+
+
+class MessagesResource:
+    def __init__(self, http: HttpClient):
+        self._http = http
+
+    def send(self, input: SendMessageInput) -> SendMessageAccepted:
+        body: dict[str, Any] = {
+            "templateId": input["templateId"],
+            "destinationNumber": input["destinationNumber"],
+            "variables": input.get("variables") or {},
+        }
+        if "deliverAt" in input:
+            body["deliverAt"] = input["deliverAt"]
+        if "deliverUntil" in input:
+            body["deliverUntil"] = input["deliverUntil"]
+        return self._http.request_json(method="POST", path="/v1/messages/send", body=body)
+
+    def get(self, id: str) -> MessageDetails:
+        return self._http.request_json(method="GET", path=f"/v1/messages/{id}")
+
+    def check_opt_in(self, destination_number: str) -> OptInCheckResult:
+        return self._http.request_json(
+            method="GET",
+            path="/v1/messages/opt-in",
+            query={"destinationNumber": destination_number},
+        )

pilot_status/resources/numbers.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+from typing import Any
+
+from ..http import HttpClient
+from ..types import (
+    CreateNumberInput,
+    CreateNumberResult,
+    NumberConnectResult,
+    NumberStatusResult,
+)
+
+
+class NumbersResource:
+    def __init__(self, http: HttpClient):
+        self._http = http
+
+    def create(self, input: CreateNumberInput) -> CreateNumberResult:
+        body: dict[str, Any] = {
+            "name": input["name"],
+            "number": input["number"],
+        }
+        if "linkToApiKey" in input:
+            body["linkToApiKey"] = input["linkToApiKey"]
+        return self._http.request_json(method="POST", path="/v1/numbers", body=body)
+
+    def connect(self, id: str) -> NumberConnectResult:
+        return self._http.request_json(
+            method="GET",
+            path=f"/v1/numbers/{id}/connect",
+        )
+
+    def get_status(self, id: str) -> NumberStatusResult:
+        return self._http.request_json(
+            method="GET",
+            path=f"/v1/numbers/{id}/status",
+        )

pilot_status/resources/projects.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from typing import Any
+
+from ..http import HttpClient
+from ..types import CreateProjectInput, Project
+
+
+class ProjectsResource:
+    def __init__(self, http: HttpClient):
+        self._http = http
+
+    def list(self) -> list[Project]:
+        return self._http.request_json(method="GET", path="/v1/projects")
+
+    def create(self, input: CreateProjectInput) -> Project:
+        body: dict[str, Any] = {"name": input["name"]}
+        if "description" in input:
+            body["description"] = input["description"]
+        return self._http.request_json(method="POST", path="/v1/projects", body=body)

pilot_status/types.py

@@ -0,0 +1,180 @@
+from __future__ import annotations
+
+from typing import Literal, TypedDict
+
+Environment = Literal["TEST", "LIVE"]
+
+MessageStatus = Literal["QUEUED", "SENT", "DELIVERED", "FAILED", "READ"]
+
+
+class SendMessageInput(TypedDict, total=False):
+    templateId: str
+    destinationNumber: str
+    groupId: str
+    variables: dict[str, str]
+    labels: list[str]
+    deliverAt: str
+    deliverUntil: str
+
+
+class SendMessageAccepted(TypedDict):
+    id: str
+    correlationId: str
+    status: MessageStatus
+    createdAt: str
+    origin: str
+
+
+class MessageDetails(TypedDict):
+    id: str
+    status: MessageStatus
+    correlationId: str
+    destinationNumber: str
+    template: str
+    createdAt: str
+    sentAt: str | None
+    deliveredAt: str | None
+    readAt: str | None
+    errorMessage: str | None
+
+
+class DashboardDailyMessages(TypedDict):
+    date: str
+    count: int
+
+
+class DashboardStatusDistribution(TypedDict):
+    queued: int
+    sent: int
+    delivered: int
+    failed: int
+    read: int
+
+
+class DashboardStats(TypedDict):
+    totalSent: int
+    totalFailed: int
+    sentPercentChange: float
+    failedPercentChange: float
+    failureRate: float
+    dailyMessages: list[DashboardDailyMessages]
+    statusDistribution: DashboardStatusDistribution
+
+
+OptInCheckReason = Literal[
+    "OPTIN_DISABLED",
+    "NON_DEFAULT_INSTANCE",
+    "NOT_LIVE",
+    "MISSING_PROJECT",
+    "INVALID_PHONE",
+    "NO_OPTIN",
+]
+
+
+class OptInCheckResult(TypedDict):
+    authorized: bool
+    required: bool
+    enabled: bool
+    reason: OptInCheckReason | None
+    firstOptInAt: str | None
+    lastSeenAt: str | None
+
+
+class Project(TypedDict):
+    id: str
+    name: str
+    slug: str
+    description: str
+    productionApproved: bool
+    createdAt: str
+
+
+class CreateProjectInput(TypedDict, total=False):
+    name: str
+    description: str
+
+
+class ApiKeyCreateInput(TypedDict, total=False):
+    name: str
+    webhookId: str | None
+    whatsappInstanceId: str | None
+    retentionDays: int
+
+
+class ApiKeyCreated(TypedDict):
+    id: str
+    name: str
+    environment: Environment
+    key: str
+    keyPrefix: str
+    createdAt: str
+    webhookId: str | None
+    whatsappInstanceId: str | None
+    retentionDays: int
+
+
+class ApiKeyLinkedWebhook(TypedDict):
+    id: str
+    name: str
+    url: str
+
+
+class ApiKeyLinkedWhatsAppInstance(TypedDict):
+    id: str
+    instanceName: str
+    displayName: str
+    number: str
+    state: str
+
+
+class ApiKeyListItem(TypedDict):
+    id: str
+    name: str
+    keyPrefix: str
+    environment: Environment
+    lastUsedAt: str | None
+    createdAt: str
+    webhookId: str | None
+    projectId: str | None
+    webhook: ApiKeyLinkedWebhook | None
+    whatsappInstanceId: str | None
+    whatsappInstance: ApiKeyLinkedWhatsAppInstance | None
+    retentionDays: int
+
+
+class WhatsAppNumberInstance(TypedDict):
+    id: str
+    tenantId: str
+    instanceName: str
+    number: str
+    displayName: str
+    state: str
+    integration: str
+    createdAt: str
+    updatedAt: str
+    name: str
+    status: str
+    quality: Literal["GOOD", "UNKNOWN"]
+
+
+class CreateNumberInput(TypedDict, total=False):
+    name: str
+    number: str
+    linkToApiKey: bool
+
+
+class CreateNumberResult(TypedDict):
+    instance: WhatsAppNumberInstance
+    qrcodeBase64: str | None
+    pairingCode: str | None
+    linkedApiKeyId: str | None
+
+
+class NumberConnectResult(TypedDict):
+    qrcodeBase64: str | None
+    pairingCode: str | None
+
+
+class NumberStatusResult(TypedDict):
+    id: str
+    state: str

pilot_status/webhooks/__init__.py

@@ -0,0 +1,19 @@
+from .parse import is_customer_webhook_event, parse_customer_webhook
+from .types import (
+    CustomerWebhookEvent,
+    MessageFailedEvent,
+    MessageReadEvent,
+    MessageReplyEvent,
+    MessageSentEvent,
+)
+
+__all__ = [
+    "CustomerWebhookEvent",
+    "MessageSentEvent",
+    "MessageReadEvent",
+    "MessageFailedEvent",
+    "MessageReplyEvent",
+    "parse_customer_webhook",
+    "is_customer_webhook_event",
+]
+