Metadata-Version: 2.4
Name: usebuddy
Version: 0.1.0b1
Summary: Server-side Python client for the Buddy API
Author: Creovine LTD
License: MIT
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# Buddy Python SDK

After registry publication, install with:

```bash
pip install --pre usebuddy
```

Server-side Python 3.9+ client with no runtime dependencies.

```python
import os
from buddy import Buddy

buddy = Buddy(os.environ["BUDDY_API_KEY"])
account = buddy.me()
buddy.subscribers.create({"phone": "+15550000001", "name": "Amira"})
message = buddy.messages.send({
    "to": "+15550000001",
    "template": "buddy_test_hello",
    "variables": ["Amira"],
}, idempotency_key="my-first-test-message")
print(message["data"]["id"])
```

Use a test key for this example. Every operation is also available by its OpenAPI
operation ID: `buddy.call("getMessage", path={"id": message_id})`.
Use `buddy.paginate("listSubscribers", query={"limit": 50})` to iterate all pages.

POST calls create one idempotency key and retain it across bounded retries. Supply
a stable key for retries across process restarts. PATCH is not retried. Redirects
are refused so credentials are never forwarded to a new location. Replayed server
failures are surfaced immediately; never change the key to bypass an uncertain outcome.

Catch `BuddyError` for status, code, request_id, details and retry_after.
`SubscriberOptedOut` and `TemplateNotApproved` allow specific handling.
Verify webhooks with `verify_webhook(raw_bytes, signature_header, signing_secret)`
before parsing or acting on them. Deduplicate event IDs durably.

Run tests with `PYTHONPATH=packages/python python3 -m unittest discover -s packages/python/tests`.
Install locally using `python3 -m pip install ./packages/python` in a virtual
environment. Package publication requires verified registry ownership.

Every OpenAPI operation also has a generated snake_case method, such as
`buddy.send_message(body={...})` and `buddy.get_subscriber(id="sub_...")`.
Request and response `TypedDict` models are exported from `buddy.models`.
Generate both SDKs from the contract with `node scripts/generate-sdk.mjs`.

Resource helpers include `subscribers`, `messages`, `templates`, `events`, `otp`, `campaigns` and `webhooks`. Generated snake_case operation methods cover every API endpoint. Safe requests retry network failures, non-JSON gateway errors, rate limits and `request_in_progress` within `max_retries` (default 2), retaining the original body and idempotency key. Replayed failures are not retried.

For writes that must survive a process restart or exhausted retry budget, supply and persist your own stable idempotency key before the first call. Automatically generated keys are retained only within that call; a fresh SDK call generates another key.
