przypominamy 2.0.0__tar.gz

przypominamy-2.0.0/.gitignore

@@ -0,0 +1,4 @@
+dist
+*.egg-info
+__pycache__
+.venv

przypominamy-2.0.0/PKG-INFO

@@ -0,0 +1,119 @@
+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

przypominamy-2.0.0/README.md

@@ -0,0 +1,97 @@
+# 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

przypominamy-2.0.0/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "przypominamy"
+version = "2.0.0"
+description = "Klient API SMS przypominamy.com — wysyłka SMS z Pythona. Polska bramka SMS, REST, Bearer, webhooki HMAC. Zero zależności."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [{ name = "Przypominamy.com", email = "support@przypominamy.com" }]
+keywords = ["sms", "sms api", "bramka sms", "api sms polska", "przypominamy", "wysylka sms", "otp", "2fa"]
+classifiers = [
+  "Development Status :: 5 - Production/Stable",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Natural Language :: Polish",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Topic :: Communications :: Telephony",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+[project.urls]
+Homepage = "https://przypominamy.com/api"
+Documentation = "https://przypominamy.com/api/docs"
+Repository = "https://github.com/pawelmamcarz/przypominamy-com"
+"OpenAPI" = "https://przypominamy.com/openapi.json"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/przypominamy"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/przypominamy", "README.md", "tests"]

przypominamy-2.0.0/src/przypominamy/__init__.py

@@ -0,0 +1,15 @@
+"""Oficjalny klient API SMS przypominamy.com.
+
+    from przypominamy import Przypominamy
+
+    sms = Przypominamy(os.environ["PRZYPOMINAMY_API_KEY"])
+    msg = sms.send(to="+48600100200", text="Przypominamy o wizycie jutro o 10:00.")
+    print(msg["id"], msg["status"])
+
+Dokumentacja: https://przypominamy.com/api/docs
+"""
+
+from .client import Przypominamy, PrzypominamyError, verify_webhook
+
+__all__ = ["Przypominamy", "PrzypominamyError", "verify_webhook"]
+__version__ = "2.0.0"

przypominamy-2.0.0/src/przypominamy/client.py

@@ -0,0 +1,194 @@
+"""Klient HTTP API SMS przypominamy.com. Zero zależności (urllib ze standardowej biblioteki)."""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import re
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional, Sequence, Union
+
+__all__ = ["Przypominamy", "PrzypominamyError", "verify_webhook"]
+
+DEFAULT_BASE_URL = "https://api.przypominamy.com"
+USER_AGENT = "przypominamy-python/2.0.0"
+
+
+class PrzypominamyError(Exception):
+    """Błąd API: kod HTTP, kod błędu (`insufficient_funds`, `rate_limited`…), pole i request_id do supportu."""
+
+    def __init__(
+        self,
+        status: int,
+        code: str,
+        message: str,
+        param: Optional[str] = None,
+        request_id: Optional[str] = None,
+        retry_after: Optional[int] = None,
+    ) -> None:
+        super().__init__(f"[{status} {code}] {message}")
+        self.status = status
+        self.code = code
+        self.message = message
+        self.param = param
+        self.request_id = request_id
+        self.retry_after = retry_after
+
+
+class Przypominamy:
+    """Klient API. Wszystkie metody zwracają słowniki zgodne z https://przypominamy.com/openapi.json."""
+
+    def __init__(self, api_key: str, *, base_url: str = DEFAULT_BASE_URL, timeout: float = 10.0) -> None:
+        if not api_key:
+            raise ValueError("Brak klucza API (pk_live_…)")
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+
+    # ── Wiadomości ──────────────────────────────────────────────────────
+
+    def send(
+        self,
+        to: Union[str, Sequence[str]],
+        text: str,
+        *,
+        sender: Optional[str] = None,
+        send_at: Union[datetime, str, None] = None,
+        reference: Optional[str] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Wyślij SMS do jednego numeru (str) lub wielu (lista do 500). Zwraca Message albo wynik zbiorczy."""
+        body: Dict[str, Any] = {"to": list(to) if not isinstance(to, str) else to, "text": text}
+        if sender:
+            body["from"] = sender
+        if reference:
+            body["reference"] = reference
+        if send_at is not None:
+            if isinstance(send_at, datetime):
+                if send_at.tzinfo is None:
+                    send_at = send_at.replace(tzinfo=timezone.utc)
+                send_at = send_at.isoformat()
+            body["send_at"] = send_at
+        headers = {"Idempotency-Key": idempotency_key} if idempotency_key else {}
+        return self._request("POST", "/v1/messages", body, headers)
+
+    def get(self, message_id: str) -> Dict[str, Any]:
+        """Pobierz wiadomość po id (`msg_…`)."""
+        return self._request("GET", f"/v1/messages/{urllib.parse.quote(message_id)}")
+
+    def list(
+        self,
+        *,
+        limit: Optional[int] = None,
+        status: Optional[str] = None,
+        reference: Optional[str] = None,
+        to: Optional[str] = None,
+        cursor: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Historia wiadomości: {"data": [...], "next_cursor": ...}."""
+        params = {k: v for k, v in dict(limit=limit, status=status, reference=reference, to=to, cursor=cursor).items() if v is not None}
+        qs = f"?{urllib.parse.urlencode(params)}" if params else ""
+        return self._request("GET", f"/v1/messages{qs}")
+
+    def iter_messages(self, **filters: Any):
+        """Iteruje po całej historii, strona po stronie."""
+        cursor = None
+        while True:
+            page = self.list(cursor=cursor, **filters)
+            yield from page["data"]
+            cursor = page.get("next_cursor")
+            if not cursor:
+                return
+
+    # ── Konto ───────────────────────────────────────────────────────────
+
+    def account(self) -> Dict[str, Any]:
+        """Saldo (balance_grosze), cena za część, nadpis, webhook."""
+        return self._request("GET", "/v1/account")
+
+    def senders(self) -> Dict[str, Any]:
+        """Aktywne nadpisy: {"data": [{"name", "is_default"}], "current": ...}."""
+        return self._request("GET", "/v1/senders")
+
+    def set_sender(self, sender_name: Optional[str]) -> Dict[str, Any]:
+        """Ustaw domyślny nadpis (None przywraca domyślny)."""
+        return self._request("PATCH", "/v1/account", {"sender_name": sender_name})
+
+    def set_webhook(self, url: Optional[str], *, rotate_secret: bool = False) -> Dict[str, Any]:
+        """Ustaw adres webhooka; zwraca webhook_secret. None wyłącza webhooki."""
+        return self._request("PUT", "/v1/account/webhook", {"url": url, "rotate_secret": rotate_secret})
+
+    # ── HTTP ────────────────────────────────────────────────────────────
+
+    def _request(self, method: str, path: str, body: Any = None, extra_headers: Optional[Dict[str, str]] = None) -> Dict[str, Any]:
+        headers = {
+            "Authorization": f"Bearer {self.api_key}",
+            "Accept": "application/json",
+            "User-Agent": USER_AGENT,
+        }
+        if extra_headers:
+            headers.update(extra_headers)
+        data = None
+        if body is not None:
+            headers["Content-Type"] = "application/json"
+            data = json.dumps(body).encode("utf-8")
+        req = urllib.request.Request(f"{self.base_url}{path}", data=data, method=method, headers=headers)
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as res:
+                raw = res.read()
+                return json.loads(raw) if raw else {}
+        except urllib.error.HTTPError as e:
+            raw = e.read()
+            try:
+                payload = json.loads(raw) if raw else {}
+            except ValueError:
+                payload = {}
+            err = payload.get("error") or {}
+            retry_after = e.headers.get("Retry-After")
+            raise PrzypominamyError(
+                e.code,
+                err.get("code", "internal_error"),
+                err.get("message", f"HTTP {e.code}"),
+                err.get("param"),
+                payload.get("request_id") or e.headers.get("X-Request-Id"),
+                int(retry_after) if retry_after and retry_after.isdigit() else None,
+            ) from None
+        except urllib.error.URLError as e:
+            raise PrzypominamyError(0, "network_error", str(e.reason)) from None
+
+
+# ── Webhooki ────────────────────────────────────────────────────────────
+
+_SIG_RE = re.compile(r"t=(\d+),v1=([0-9a-f]{64})")
+
+
+def verify_webhook(
+    raw_body: Union[bytes, str],
+    signature_header: Optional[str],
+    secret: str,
+    *,
+    tolerance_seconds: int = 300,
+    now: Optional[float] = None,
+) -> Dict[str, Any]:
+    """Weryfikuje nagłówek X-Przypominamy-Signature i zwraca zdarzenie. Rzuca ValueError przy złym podpisie."""
+    m = _SIG_RE.search(signature_header or "")
+    if not m:
+        raise ValueError("Brak lub nieprawidłowy nagłówek X-Przypominamy-Signature")
+    t, sig = int(m.group(1)), m.group(2)
+    if abs((now if now is not None else time.time()) - t) > tolerance_seconds:
+        raise ValueError("Podpis webhooka jest przeterminowany")
+    body_bytes = raw_body.encode("utf-8") if isinstance(raw_body, str) else raw_body
+    expected = hmac.new(secret.encode("utf-8"), f"{t}.".encode("utf-8") + body_bytes, hashlib.sha256).hexdigest()
+    if not hmac.compare_digest(expected, sig):
+        raise ValueError("Nieprawidłowy podpis webhooka")
+    return json.loads(body_bytes)
+
+
+# Typy pomocnicze dla użytkowników type hintów
+Message = Dict[str, Any]
+Messages = List[Message]

przypominamy-2.0.0/tests/test_client.py

@@ -0,0 +1,92 @@
+import hashlib
+import hmac
+import io
+import json
+import unittest
+import urllib.error
+from datetime import datetime, timezone
+from unittest import mock
+
+from przypominamy import Przypominamy, PrzypominamyError, verify_webhook
+
+
+class FakeResponse(io.BytesIO):
+    def __init__(self, payload, headers=None):
+        super().__init__(json.dumps(payload).encode())
+        self.headers = headers or {}
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *a):
+        return False
+
+
+def http_error(status, payload, headers=None):
+    return urllib.error.HTTPError("https://api.przypominamy.com/v1/messages", status, "err", headers or {}, io.BytesIO(json.dumps(payload).encode()))
+
+
+class ClientTests(unittest.TestCase):
+    def setUp(self):
+        self.sms = Przypominamy("pk_live_test")
+
+    def test_send_single_builds_request(self):
+        with mock.patch("urllib.request.urlopen", return_value=FakeResponse({"id": "msg_1", "status": "queued"})) as m:
+            msg = self.sms.send(
+                "+48600100200", "Hej", sender="FIRMA", reference="r1",
+                idempotency_key="k1", send_at=datetime(2026, 9, 10, 8, 0, tzinfo=timezone.utc),
+            )
+        self.assertEqual(msg["id"], "msg_1")
+        req = m.call_args[0][0]
+        self.assertEqual(req.full_url, "https://api.przypominamy.com/v1/messages")
+        self.assertEqual(req.get_method(), "POST")
+        self.assertEqual(req.get_header("Authorization"), "Bearer pk_live_test")
+        self.assertEqual(req.get_header("Idempotency-key"), "k1")
+        self.assertEqual(json.loads(req.data), {"to": "+48600100200", "text": "Hej", "from": "FIRMA", "reference": "r1", "send_at": "2026-09-10T08:00:00+00:00"})
+
+    def test_send_many(self):
+        with mock.patch("urllib.request.urlopen", return_value=FakeResponse({"count": 2, "accepted": 2, "total_cost_grosze": 18, "messages": []})) as m:
+            res = self.sms.send(["+48600100200", "+48600100201"], "Hej")
+        self.assertEqual(res["accepted"], 2)
+        self.assertEqual(json.loads(m.call_args[0][0].data)["to"], ["+48600100200", "+48600100201"])
+
+    def test_api_error(self):
+        err = http_error(402, {"error": {"code": "insufficient_funds", "message": "Brak środków"}, "request_id": "req_x"}, {"Retry-After": "30"})
+        with mock.patch("urllib.request.urlopen", side_effect=err):
+            with self.assertRaises(PrzypominamyError) as cm:
+                self.sms.send("+48600100200", "Hej")
+        self.assertEqual(cm.exception.status, 402)
+        self.assertEqual(cm.exception.code, "insufficient_funds")
+        self.assertEqual(cm.exception.request_id, "req_x")
+        self.assertEqual(cm.exception.retry_after, 30)
+
+    def test_list_query_and_iteration(self):
+        pages = [FakeResponse({"data": [{"id": "a"}], "next_cursor": "c1"}), FakeResponse({"data": [{"id": "b"}], "next_cursor": None})]
+        with mock.patch("urllib.request.urlopen", side_effect=pages) as m:
+            ids = [x["id"] for x in self.sms.iter_messages(status="delivered", limit=1)]
+        self.assertEqual(ids, ["a", "b"])
+        self.assertIn("status=delivered", m.call_args_list[0][0][0].full_url)
+        self.assertIn("cursor=c1", m.call_args_list[1][0][0].full_url)
+
+    def test_account_and_webhook(self):
+        with mock.patch("urllib.request.urlopen", side_effect=[FakeResponse({"balance_grosze": 100}), FakeResponse({"webhook_secret": "whsec_1"})]) as m:
+            self.assertEqual(self.sms.account()["balance_grosze"], 100)
+            self.assertEqual(self.sms.set_webhook("https://x")["webhook_secret"], "whsec_1")
+        self.assertEqual(m.call_args_list[1][0][0].get_method(), "PUT")
+
+
+class WebhookTests(unittest.TestCase):
+    def test_verify(self):
+        secret, t = "whsec_test", 1_757_230_000
+        body = json.dumps({"id": "evt_1", "type": "message.delivered", "data": {"message": {"id": "msg_1"}}})
+        sig = hmac.new(secret.encode(), f"{t}.{body}".encode(), hashlib.sha256).hexdigest()
+        ev = verify_webhook(body, f"t={t},v1={sig}", secret, now=t + 10)
+        self.assertEqual(ev["data"]["message"]["id"], "msg_1")
+        with self.assertRaises(ValueError):
+            verify_webhook(body, f"t={t},v1={'0' * 64}", secret, now=t + 10)
+        with self.assertRaises(ValueError):
+            verify_webhook(body, f"t={t},v1={sig}", secret, now=t + 1000)
+
+
+if __name__ == "__main__":
+    unittest.main()