Metadata-Version: 2.4
Name: pilot-status
Version: 0.1.3
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

# 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",
    }
)

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`, `correlationId`.
- `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`.
