Metadata-Version: 2.5
Name: grubgenie-waba-sdk
Version: 0.3.1
Summary: Python SDK for the GrubGenie WABA middleware — send messages, manage templates, handle media, receive webhooks
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Provides-Extra: dev
Requires-Dist: fastapi>=0.115; extra == 'dev'
Requires-Dist: httpx>=0.27; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Provides-Extra: fastapi
Requires-Dist: fastapi>=0.115; extra == 'fastapi'
Description-Content-Type: text/markdown

# grubgenie-waba-sdk

Python SDK for the GrubGenie WABA middleware. Send WhatsApp messages, manage templates, handle media, and receive inbound webhooks.

## Install

```bash
pip install grubgenie-waba-sdk
```

With FastAPI webhook support:

```bash
pip install grubgenie-waba-sdk[fastapi]
```

## Quick Start

```python
import os
from waba_sdk import WabaClient

waba = WabaClient(
    base_url="https://waba.grubgenie.ai",
    service_key=os.environ["WABA_SERVICE_KEY"],
)
```

## Messages

```python
# Text message
await waba.messages.send_text("phone_number_id", "919999999999", "Hello!")

# Template message
await waba.messages.send_template(
    "phone_number_id", "919999999999",
    template_name="hello_world",
    language_code="en_US",
)

# Media message (image, video, document, audio)
await waba.messages.send_media(
    "phone_number_id", "919999999999",
    media_type="image",
    media_url="https://example.com/photo.jpg",
    caption="Check this out",
)

# Interactive message (buttons, lists)
await waba.messages.send_interactive("phone_number_id", "919999999999", {
    "type": "button",
    "body": {"text": "Pick one"},
    "action": {
        "buttons": [
            {"type": "reply", "reply": {"id": "yes", "title": "Yes"}},
            {"type": "reply", "reply": {"id": "no", "title": "No"}},
        ]
    },
})

# Mark message as read
await waba.messages.mark_as_read("phone_number_id", "wamid.xxx")

# Raw send (full control over body)
await waba.messages.send("phone_number_id", {
    "messaging_product": "whatsapp",
    "to": "919999999999",
    "type": "text",
    "text": {"body": "raw"},
})
```

## Templates

```python
WABA_ID = "your_waba_id"
PN_ID = "phone_number_id"

# List templates (single page)
page = await waba.templates.list(PN_ID, WABA_ID)

# List all templates (auto-paginates)
all_templates = await waba.templates.list_all(PN_ID, WABA_ID)

# Get template by name
template = await waba.templates.get(PN_ID, WABA_ID, "hello_world")

# Get template by ID
template = await waba.templates.get_by_id(PN_ID, WABA_ID, "123456789")

# Create template
await waba.templates.create(PN_ID, WABA_ID, {
    "name": "order_update",
    "language": "en_US",
    "category": "UTILITY",
    "components": [{"type": "BODY", "text": "Your order {{1}} is ready."}],
})

# Update template
await waba.templates.update(PN_ID, WABA_ID, "123456789", {
    "components": [{"type": "BODY", "text": "Order {{1}} updated."}],
})

# Delete template
await waba.templates.delete(PN_ID, WABA_ID, "order_update")
```

## Media

```python
# Upload
result = await waba.media.upload("phone_number_id", file_bytes, "photo.png", "image/png")
media_id = result["id"]

# Download
data = await waba.media.download(media_id, "phone_number_id")
```

## Phone Numbers

```python
# List phone numbers for a WABA
numbers = await waba.phone_numbers.list("phone_number_id", "waba_id")

# Register a phone number
await waba.phone_numbers.register("phone_number_id", pin="123456")
```

## Cloud API Proxy

Direct access to any WhatsApp Cloud API endpoint through the middleware:

```python
response = await waba.proxy("phone_number_id", "GET", "{waba_id}/phone_numbers")
print(response.json())
```

## Inbound Webhooks (FastAPI)

```python
from fastapi import FastAPI, Request
from waba_sdk import WabaWebhookHandler

app = FastAPI()

async def on_event(event):
    context = event["context"]  # { partnerId, phoneNumberId }
    raw = event["raw"]          # original Meta webhook body
    print(f"Message from partner {context['partnerId']}")

handler = WabaWebhookHandler(
    secret=os.environ["WABA_WEBHOOK_SECRET"],
    on_event=on_event,
)

@app.post("/webhooks/waba")
async def waba_webhook(request: Request):
    return await handler.handle(request)
```

## Signature Verification

```python
from waba_sdk import verify_signature

is_valid = verify_signature(payload_bytes, signature_header, secret)
```

## Requirements

- Python >= 3.10
- httpx >= 0.27
- fastapi >= 0.115 (optional, for webhook handler)
