Metadata-Version: 2.5
Name: przypominamy
Version: 2.0.0
Summary: Klient API SMS przypominamy.com — wysyłka SMS z Pythona. Polska bramka SMS, REST, Bearer, webhooki HMAC. Zero zależności.
Project-URL: Homepage, https://przypominamy.com/api
Project-URL: Documentation, https://przypominamy.com/api/docs
Project-URL: Repository, https://github.com/pawelmamcarz/przypominamy-com
Project-URL: OpenAPI, https://przypominamy.com/openapi.json
Author-email: "Przypominamy.com" <support@przypominamy.com>
License-Expression: MIT
Keywords: 2fa,api sms polska,bramka sms,otp,przypominamy,sms,sms api,wysylka sms
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: Polish
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Communications :: Telephony
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# przypominamy

Oficjalny klient [API SMS przypominamy.com](https://przypominamy.com/api) dla Pythona ≥ 3.9. Zero zależności (standardowa biblioteka).

Polska bramka SMS: jeden endpoint do wysyłki, historia, saldo, własny nadpis, webhooki podpisane HMAC. Pay-as-you-go, bez abonamentu.

```bash
pip install przypominamy
```

## Szybki start

```python
import os
from przypominamy import Przypominamy

sms = Przypominamy(os.environ["PRZYPOMINAMY_API_KEY"])  # pk_live_…

msg = sms.send(
    "+48600100200",
    "Przypominamy o wizycie jutro o 10:00.",
    reference="wizyta-4711",          # Twój identyfikator, wraca w webhookach
    idempotency_key="wizyta-4711-1",  # retry nie wyśle SMS-a drugi raz
)
print(msg["id"], msg["status"], msg["cost_grosze"])  # msg_… queued 9
```

Klucz API dostaniesz po założeniu konta na [przypominamy.com/register](https://przypominamy.com/register) (weryfikacja w 24 h).

## Wysyłka masowa i odroczona

```python
from datetime import datetime, timezone

batch = sms.send(["+48600100200", "+48600100201"], "Promocja -20% do niedzieli. Kod: SMS20", sender="SKLEP")
print(batch["accepted"], "z", batch["count"], "przyjęto, koszt", batch["total_cost_grosze"] / 100, "zł")

sms.send("+48600100200", "Wizyta dziś o 14:00.", send_at=datetime(2026, 9, 18, 8, 0, tzinfo=timezone.utc))
```

## Status, historia, konto

```python
m = sms.get("msg_qY08hZ2mmDXAazdRTytS")
page = sms.list(status="delivered", limit=50)       # page["data"], page["next_cursor"]
for m in sms.iter_messages(reference="wizyta-4711"):  # cała historia, strona po stronie
    print(m["id"], m["status"])
acc = sms.account()                                   # acc["balance_grosze"], acc["price_per_part_grosze"]
print(sms.senders()["data"])
sms.set_sender("ZDROWKO")
```

## Webhooki

```python
secret = sms.set_webhook("https://twojadomena.pl/webhooks/sms")["webhook_secret"]
```

Handler we Flasku:

```python
from flask import Flask, request, abort
from przypominamy import verify_webhook

app = Flask(__name__)

@app.post("/webhooks/sms")
def sms_webhook():
    try:
        event = verify_webhook(request.get_data(), request.headers.get("X-Przypominamy-Signature"), WEBHOOK_SECRET)
    except ValueError:
        abort(403)
    # event["type"]: message.sent | message.delivered | message.undelivered | message.failed | message.expired
    msg = event["data"]["message"]
    print(event["type"], msg["id"], msg["reference"])
    return "", 200
```

## Błędy

Każdy błąd API to `PrzypominamyError` z polami `status`, `code` (`invalid_request`, `unauthorized`, `insufficient_funds`, `rate_limited`, `idempotency_conflict`, `provider_error`…), `param`, `request_id` i `retry_after`.

```python
from przypominamy import PrzypominamyError
try:
    sms.send("+48600100200", "Hej")
except PrzypominamyError as e:
    if e.code == "rate_limited":
        time.sleep(e.retry_after or 5)
```

## Dokumentacja

- [Strona API](https://przypominamy.com/api) · [Redoc](https://przypominamy.com/api/docs) · [OpenAPI 3.1](https://przypominamy.com/openapi.json)
- Wsparcie: support@przypominamy.com

MIT
