Metadata-Version: 2.4
Name: maacgo-sms
Version: 0.1.0
Summary: MAAC Go SMS — send Taiwan SMS in 3 lines from Python. NCC-compliant, NT$50 free trial.
Author-email: Cresclab <sms@cresclab.com>
License: MIT
Project-URL: Homepage, https://sms.cresclab.com
Project-URL: Documentation, https://sms.cresclab.com/developers.html
Project-URL: Repository, https://github.com/jinhsueh/cresclab-sms-self-serve
Project-URL: Issues, https://github.com/jinhsueh/cresclab-sms-self-serve/issues
Project-URL: Changelog, https://github.com/jinhsueh/cresclab-sms-self-serve/commits/main/sdk/python
Keywords: sms,taiwan,otp,twilio-alternative,maacgo,maac,ncc
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Communications :: Telephony
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.25
Dynamic: license-file

# maacgo-sms · Python SDK

Taiwan-first SMS API. Send SMS in 3 lines of Python.

```bash
pip install maacgo-sms
```

## Quickstart

```python
from maacgo_sms import Maacgo

sms = Maacgo("sk_live_...")

r = sms.send(
    to="+886912345678",
    body="【你的品牌】驗證碼 123456，5 分鐘內有效。",
)
print(r["id"], r["status"])
```

## Context manager

```python
with Maacgo("sk_live_...") as sms:
    sms.send(to="+886912345678", body="...")
```

## Batch send

```python
sms.broadcast(
    name="週年慶",
    body="【你的品牌】週年慶 5 折起！",
    recipients=["+886912345678", "+886987654321"],
)
```

## Errors

```python
from maacgo_sms import Maacgo, MaacgoError

try:
    sms.send(to="09XXX", body="【...】Hi")
except MaacgoError as e:
    if e.data.get("error") == "ncc_blocked":
        print("NCC compliance failed:", e.data.get("issues"))
    elif e.data.get("error") == "insufficient_balance":
        print("Please top up")
```

## Webhooks (Django / Flask / FastAPI)

```python
import hmac, hashlib, os
from fastapi import FastAPI, Request, HTTPException

app = FastAPI()
SECRET = os.environ["CRESCLAB_WEBHOOK_SECRET"]

@app.post("/webhooks/cresclab")
async def webhook(request: Request):
    body = await request.body()
    sig = request.headers.get("x-cresclab-signature", "")
    expected = hmac.new(SECRET.encode(), body, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(sig, expected):
        raise HTTPException(401)

    payload = await request.json()
    if payload["event"] == "sms.delivered":
        mark_delivered(payload["data"]["id"])
    return {"received": True}
```

## License

MIT
