hey-pingr 0.1.0__tar.gz

hey_pingr-0.1.0/PKG-INFO

@@ -0,0 +1,146 @@
+Metadata-Version: 2.4
+Name: hey-pingr
+Version: 0.1.0
+Summary: Official Python SDK for the Pingr WhatsApp messaging API
+Author-email: Pingr <support@heypingr.com>
+License: MIT
+Project-URL: Homepage, https://heypingr.com
+Project-URL: Docs, https://heypingr.com/docs
+Project-URL: Repository, https://github.com/heypingr/pingr-python
+Keywords: pingr,whatsapp,messaging,otp,api,sdk
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+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
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Provides-Extra: async
+Requires-Dist: httpx>=0.25; extra == "async"
+Provides-Extra: dev
+Requires-Dist: httpx>=0.25; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+
+# pingr
+
+Official Python SDK for the [Pingr](https://heypingr.com) WhatsApp messaging API.
+
+## Installation
+
+```bash
+pip install hey-pingr
+```
+
+For async support (uses `httpx`):
+
+```bash
+pip install hey-pingr[async]
+```
+
+## Quick start
+
+```python
+import pingr
+
+client = pingr.Pingr("pk_live_your_key_here")
+
+result = client.messages.send(
+    to="919876543210",      # digits only, with country code
+    message="Your OTP is 482910. Valid for 10 minutes.",
+)
+
+print(result["message_id"])           # msg_abc123
+print(result["rate_limit_remaining"]) # 499
+```
+
+## Async usage
+
+```python
+import asyncio
+import pingr
+
+async def main():
+    async with pingr.AsyncPingr("pk_live_your_key_here") as client:
+        result = await client.messages.send(
+            to="919876543210",
+            message="Your OTP is 482910",
+        )
+        print(result["message_id"])
+
+asyncio.run(main())
+```
+
+## Verifying webhooks
+
+```python
+from flask import Flask, request
+from pingr import verify_webhook, PingrWebhookError
+import os
+
+app = Flask(__name__)
+
+@app.route("/webhook", methods=["POST"])
+def webhook():
+    try:
+        payload = verify_webhook(
+            request.get_data(),
+            request.headers["x-pingr-signature"],
+            os.environ["PINGR_WEBHOOK_SECRET"],
+        )
+        print(payload["event"], payload["session_id"])
+        return "", 200
+    except PingrWebhookError as e:
+        print("Invalid webhook:", e)
+        return "", 400
+```
+
+## Error handling
+
+```python
+from pingr import Pingr, PingrRateLimitError, PingrAuthError, PingrError
+
+client = Pingr("pk_live_...")
+
+try:
+    client.messages.send(to="919...", message="Hello")
+except PingrRateLimitError as e:
+    print(f"Rate limited. Retry in {e.retry_after}s")
+except PingrAuthError:
+    print("Invalid API key")
+except PingrError as e:
+    print(f"Error {e.code}: {e.message}")
+```
+
+## Test mode
+
+Use a `pk_test_` key to exercise the API without sending real messages.
+The response is identical to live mode — ideal for unit tests and CI.
+
+## API reference
+
+### `Pingr(api_key, *, base_url=..., timeout=15.0)`
+
+### `client.messages.send(*, to, message, session_id=None)`
+
+| Param        | Type | Required | Description                                       |
+|--------------|------|----------|---------------------------------------------------|
+| `to`         | str  | ✓        | Recipient phone — digits + country code           |
+| `message`    | str  | ✓        | Text to send                                      |
+| `session_id` | str  |          | Specific session (auto-picks connected if omitted)|
+
+Returns a dict with: `success`, `message_id`, `to`, `session_id`, `rate_limit_remaining`.
+
+### `verify_webhook(raw_body, signature, secret, *, check_timestamp=True)`
+
+Verifies `x-pingr-signature` and returns the parsed payload dict.  
+Raises `PingrWebhookError` on failure.
+
+## License
+
+MIT

hey_pingr-0.1.0/README.md

@@ -0,0 +1,117 @@
+# pingr
+
+Official Python SDK for the [Pingr](https://heypingr.com) WhatsApp messaging API.
+
+## Installation
+
+```bash
+pip install hey-pingr
+```
+
+For async support (uses `httpx`):
+
+```bash
+pip install hey-pingr[async]
+```
+
+## Quick start
+
+```python
+import pingr
+
+client = pingr.Pingr("pk_live_your_key_here")
+
+result = client.messages.send(
+    to="919876543210",      # digits only, with country code
+    message="Your OTP is 482910. Valid for 10 minutes.",
+)
+
+print(result["message_id"])           # msg_abc123
+print(result["rate_limit_remaining"]) # 499
+```
+
+## Async usage
+
+```python
+import asyncio
+import pingr
+
+async def main():
+    async with pingr.AsyncPingr("pk_live_your_key_here") as client:
+        result = await client.messages.send(
+            to="919876543210",
+            message="Your OTP is 482910",
+        )
+        print(result["message_id"])
+
+asyncio.run(main())
+```
+
+## Verifying webhooks
+
+```python
+from flask import Flask, request
+from pingr import verify_webhook, PingrWebhookError
+import os
+
+app = Flask(__name__)
+
+@app.route("/webhook", methods=["POST"])
+def webhook():
+    try:
+        payload = verify_webhook(
+            request.get_data(),
+            request.headers["x-pingr-signature"],
+            os.environ["PINGR_WEBHOOK_SECRET"],
+        )
+        print(payload["event"], payload["session_id"])
+        return "", 200
+    except PingrWebhookError as e:
+        print("Invalid webhook:", e)
+        return "", 400
+```
+
+## Error handling
+
+```python
+from pingr import Pingr, PingrRateLimitError, PingrAuthError, PingrError
+
+client = Pingr("pk_live_...")
+
+try:
+    client.messages.send(to="919...", message="Hello")
+except PingrRateLimitError as e:
+    print(f"Rate limited. Retry in {e.retry_after}s")
+except PingrAuthError:
+    print("Invalid API key")
+except PingrError as e:
+    print(f"Error {e.code}: {e.message}")
+```
+
+## Test mode
+
+Use a `pk_test_` key to exercise the API without sending real messages.
+The response is identical to live mode — ideal for unit tests and CI.
+
+## API reference
+
+### `Pingr(api_key, *, base_url=..., timeout=15.0)`
+
+### `client.messages.send(*, to, message, session_id=None)`
+
+| Param        | Type | Required | Description                                       |
+|--------------|------|----------|---------------------------------------------------|
+| `to`         | str  | ✓        | Recipient phone — digits + country code           |
+| `message`    | str  | ✓        | Text to send                                      |
+| `session_id` | str  |          | Specific session (auto-picks connected if omitted)|
+
+Returns a dict with: `success`, `message_id`, `to`, `session_id`, `rate_limit_remaining`.
+
+### `verify_webhook(raw_body, signature, secret, *, check_timestamp=True)`
+
+Verifies `x-pingr-signature` and returns the parsed payload dict.  
+Raises `PingrWebhookError` on failure.
+
+## License
+
+MIT

hey_pingr-0.1.0/hey_pingr.egg-info/PKG-INFO

@@ -0,0 +1,146 @@
+Metadata-Version: 2.4
+Name: hey-pingr
+Version: 0.1.0
+Summary: Official Python SDK for the Pingr WhatsApp messaging API
+Author-email: Pingr <support@heypingr.com>
+License: MIT
+Project-URL: Homepage, https://heypingr.com
+Project-URL: Docs, https://heypingr.com/docs
+Project-URL: Repository, https://github.com/heypingr/pingr-python
+Keywords: pingr,whatsapp,messaging,otp,api,sdk
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+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
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Provides-Extra: async
+Requires-Dist: httpx>=0.25; extra == "async"
+Provides-Extra: dev
+Requires-Dist: httpx>=0.25; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+
+# pingr
+
+Official Python SDK for the [Pingr](https://heypingr.com) WhatsApp messaging API.
+
+## Installation
+
+```bash
+pip install hey-pingr
+```
+
+For async support (uses `httpx`):
+
+```bash
+pip install hey-pingr[async]
+```
+
+## Quick start
+
+```python
+import pingr
+
+client = pingr.Pingr("pk_live_your_key_here")
+
+result = client.messages.send(
+    to="919876543210",      # digits only, with country code
+    message="Your OTP is 482910. Valid for 10 minutes.",
+)
+
+print(result["message_id"])           # msg_abc123
+print(result["rate_limit_remaining"]) # 499
+```
+
+## Async usage
+
+```python
+import asyncio
+import pingr
+
+async def main():
+    async with pingr.AsyncPingr("pk_live_your_key_here") as client:
+        result = await client.messages.send(
+            to="919876543210",
+            message="Your OTP is 482910",
+        )
+        print(result["message_id"])
+
+asyncio.run(main())
+```
+
+## Verifying webhooks
+
+```python
+from flask import Flask, request
+from pingr import verify_webhook, PingrWebhookError
+import os
+
+app = Flask(__name__)
+
+@app.route("/webhook", methods=["POST"])
+def webhook():
+    try:
+        payload = verify_webhook(
+            request.get_data(),
+            request.headers["x-pingr-signature"],
+            os.environ["PINGR_WEBHOOK_SECRET"],
+        )
+        print(payload["event"], payload["session_id"])
+        return "", 200
+    except PingrWebhookError as e:
+        print("Invalid webhook:", e)
+        return "", 400
+```
+
+## Error handling
+
+```python
+from pingr import Pingr, PingrRateLimitError, PingrAuthError, PingrError
+
+client = Pingr("pk_live_...")
+
+try:
+    client.messages.send(to="919...", message="Hello")
+except PingrRateLimitError as e:
+    print(f"Rate limited. Retry in {e.retry_after}s")
+except PingrAuthError:
+    print("Invalid API key")
+except PingrError as e:
+    print(f"Error {e.code}: {e.message}")
+```
+
+## Test mode
+
+Use a `pk_test_` key to exercise the API without sending real messages.
+The response is identical to live mode — ideal for unit tests and CI.
+
+## API reference
+
+### `Pingr(api_key, *, base_url=..., timeout=15.0)`
+
+### `client.messages.send(*, to, message, session_id=None)`
+
+| Param        | Type | Required | Description                                       |
+|--------------|------|----------|---------------------------------------------------|
+| `to`         | str  | ✓        | Recipient phone — digits + country code           |
+| `message`    | str  | ✓        | Text to send                                      |
+| `session_id` | str  |          | Specific session (auto-picks connected if omitted)|
+
+Returns a dict with: `success`, `message_id`, `to`, `session_id`, `rate_limit_remaining`.
+
+### `verify_webhook(raw_body, signature, secret, *, check_timestamp=True)`
+
+Verifies `x-pingr-signature` and returns the parsed payload dict.  
+Raises `PingrWebhookError` on failure.
+
+## License
+
+MIT

hey_pingr-0.1.0/hey_pingr.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+README.md
+pyproject.toml
+hey_pingr.egg-info/PKG-INFO
+hey_pingr.egg-info/SOURCES.txt
+hey_pingr.egg-info/dependency_links.txt
+hey_pingr.egg-info/requires.txt
+hey_pingr.egg-info/top_level.txt
+pingr/__init__.py
+pingr/client.py
+pingr/errors.py
+pingr/webhook.py

hey_pingr-0.1.0/hey_pingr.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

hey_pingr-0.1.0/hey_pingr.egg-info/requires.txt

@@ -0,0 +1,8 @@
+
+[async]
+httpx>=0.25
+
+[dev]
+httpx>=0.25
+pytest
+pytest-asyncio

hey_pingr-0.1.0/hey_pingr.egg-info/top_level.txt

@@ -0,0 +1 @@
+pingr

hey_pingr-0.1.0/pingr/__init__.py

@@ -0,0 +1,24 @@
+"""Pingr — Official Python SDK for the Pingr WhatsApp messaging API."""
+
+from .client import AsyncPingr, Messages, Pingr
+from .errors import (
+    PingrAuthError,
+    PingrError,
+    PingrRateLimitError,
+    PingrValidationError,
+    PingrWebhookError,
+)
+from .webhook import verify_webhook
+
+__version__ = "0.1.0"
+__all__ = [
+    "Pingr",
+    "AsyncPingr",
+    "Messages",
+    "verify_webhook",
+    "PingrError",
+    "PingrAuthError",
+    "PingrRateLimitError",
+    "PingrValidationError",
+    "PingrWebhookError",
+]

hey_pingr-0.1.0/pingr/client.py

@@ -0,0 +1,275 @@
+"""Pingr API client — sync and async."""
+
+from __future__ import annotations
+
+import json
+import re
+import urllib.error
+import urllib.request
+from typing import Any
+
+from .errors import PingrAuthError, PingrError, PingrRateLimitError, PingrValidationError
+from .webhook import verify_webhook
+
+_DEFAULT_BASE_URL = "https://pingr-0bj5.onrender.com"
+_SDK_VERSION      = "0.1.0"
+
+
+def _parse_error(status: int, body: bytes, headers: Any) -> PingrError:
+    try:
+        data    = json.loads(body)
+        detail  = data.get("detail", {})
+        message = detail if isinstance(detail, str) else detail.get("message", "Unknown error")
+        code    = None if isinstance(detail, str) else detail.get("error")
+    except Exception:
+        message = body.decode(errors="replace") or "Unknown error"
+        code    = None
+
+    if status == 401:
+        return PingrAuthError(message)
+    if status == 422:
+        return PingrValidationError(message)
+    if status == 429:
+        retry_after = None
+        try:
+            retry_after = int(headers.get("Retry-After") or 0) or None
+        except (TypeError, ValueError):
+            pass
+        return PingrRateLimitError(message, code or "rate_limit", retry_after)
+    return PingrError(message, code or "unknown_error", status)
+
+
+class Messages:
+    def __init__(self, client: "Pingr") -> None:
+        self._client = client
+
+    def send(self, *, to: str, message: str, session_id: str | None = None) -> dict[str, Any]:
+        """Send a WhatsApp message.
+
+        Args:
+            to:         Recipient phone number — digits only with country code.
+                        e.g. ``"919876543210"``
+            message:    Text to send.
+            session_id: Specific session to use. Auto-picks any connected session if omitted.
+
+        Returns:
+            dict with keys: ``success``, ``message_id``, ``to``,
+            ``session_id``, ``rate_limit_remaining``.
+
+        Raises:
+            PingrValidationError:  Missing or invalid parameters.
+            PingrAuthError:        Invalid API key.
+            PingrRateLimitError:   Quota exceeded or number in cooldown.
+            PingrError:            Any other API error.
+
+        Example::
+
+            result = client.messages.send(
+                to="919876543210",
+                message="Your OTP is 482910",
+            )
+            print(result["message_id"])
+        """
+        if not to:
+            raise PingrValidationError('"to" is required')
+        if not message:
+            raise PingrValidationError('"message" is required')
+
+        digits = re.sub(r"\D", "", str(to))
+        if not digits:
+            raise PingrValidationError('"to" must contain at least one digit')
+
+        body: dict[str, Any] = {"to": digits, "message": message}
+        if session_id:
+            body["session_id"] = session_id
+
+        return self._client._request("POST", "/v1/send", body)
+
+
+class Pingr:
+    """Synchronous Pingr client.
+
+    Args:
+        api_key:  Your Pingr API key (``pk_live_...`` or ``pk_test_...``).
+        base_url: Override the API base URL (useful for self-hosted deployments).
+        timeout:  Request timeout in seconds. Default: 15.
+
+    Example::
+
+        import pingr
+
+        client = pingr.Pingr("pk_live_your_key_here")
+        result = client.messages.send(to="919876543210", message="Hello!")
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = _DEFAULT_BASE_URL,
+        timeout: float = 15.0,
+    ) -> None:
+        if not api_key or not isinstance(api_key, str):
+            raise PingrError("API key is required", "missing_api_key")
+        if not (api_key.startswith("pk_live_") or api_key.startswith("pk_test_")):
+            raise PingrError(
+                "Invalid API key format. Keys must start with pk_live_ or pk_test_",
+                "invalid_api_key",
+            )
+        self._api_key  = api_key
+        self._base_url = base_url.rstrip("/")
+        self._timeout  = timeout
+        self._is_test  = api_key.startswith("pk_test_")
+
+        self.messages = Messages(self)
+
+    def verify_webhook(
+        self,
+        raw_body: bytes | str,
+        signature: str,
+        secret: str,
+        *,
+        check_timestamp: bool = True,
+    ) -> dict[str, Any]:
+        """Verify a webhook signature. Delegates to :func:`pingr.verify_webhook`."""
+        return verify_webhook(raw_body, signature, secret, check_timestamp=check_timestamp)
+
+    def _request(self, method: str, path: str, body: dict | None = None) -> dict[str, Any]:
+        url     = self._base_url + path
+        payload = json.dumps(body).encode() if body else None
+
+        req = urllib.request.Request(
+            url,
+            data=payload,
+            method=method,
+            headers={
+                "X-API-Key"    : self._api_key,
+                "Content-Type" : "application/json",
+                "User-Agent"   : f"pingr-python/{_SDK_VERSION}",
+            },
+        )
+
+        try:
+            with urllib.request.urlopen(req, timeout=self._timeout) as resp:
+                return json.loads(resp.read())
+        except urllib.error.HTTPError as exc:
+            raise _parse_error(exc.code, exc.read(), exc.headers) from exc
+        except OSError as exc:
+            raise PingrError(f"Network error: {exc}", "network_error") from exc
+
+
+# ── Async client ──────────────────────────────────────────────────────────────
+
+try:
+    import asyncio  # noqa: F401 — only imported to confirm Python 3.7+
+
+    class AsyncMessages:
+        def __init__(self, client: "AsyncPingr") -> None:
+            self._client = client
+
+        async def send(
+            self,
+            *,
+            to: str,
+            message: str,
+            session_id: str | None = None,
+        ) -> dict[str, Any]:
+            """Async version of :meth:`Messages.send`."""
+            if not to:
+                raise PingrValidationError('"to" is required')
+            if not message:
+                raise PingrValidationError('"message" is required')
+            digits = re.sub(r"\D", "", str(to))
+            if not digits:
+                raise PingrValidationError('"to" must contain at least one digit')
+
+            body: dict[str, Any] = {"to": digits, "message": message}
+            if session_id:
+                body["session_id"] = session_id
+
+            return await self._client._request("POST", "/v1/send", body)
+
+    class AsyncPingr:
+        """Async Pingr client (requires ``httpx`` — install with ``pip install pingr[async]``).
+
+        Example::
+
+            async with pingr.AsyncPingr("pk_live_...") as client:
+                result = await client.messages.send(to="919...", message="Hello!")
+        """
+
+        def __init__(
+            self,
+            api_key: str,
+            *,
+            base_url: str = _DEFAULT_BASE_URL,
+            timeout: float = 15.0,
+        ) -> None:
+            if not api_key or not isinstance(api_key, str):
+                raise PingrError("API key is required", "missing_api_key")
+            if not (api_key.startswith("pk_live_") or api_key.startswith("pk_test_")):
+                raise PingrError(
+                    "Invalid API key format. Keys must start with pk_live_ or pk_test_",
+                    "invalid_api_key",
+                )
+            self._api_key  = api_key
+            self._base_url = base_url.rstrip("/")
+            self._timeout  = timeout
+            self._httpx    = None
+            self.messages  = AsyncMessages(self)
+
+        async def __aenter__(self) -> "AsyncPingr":
+            try:
+                import httpx
+            except ImportError as exc:
+                raise ImportError(
+                    "httpx is required for AsyncPingr. Install with: pip install pingr[async]"
+                ) from exc
+            self._httpx = httpx.AsyncClient(timeout=self._timeout)
+            return self
+
+        async def __aexit__(self, *_: Any) -> None:
+            if self._httpx:
+                await self._httpx.aclose()
+
+        def verify_webhook(
+            self,
+            raw_body: bytes | str,
+            signature: str,
+            secret: str,
+            *,
+            check_timestamp: bool = True,
+        ) -> dict[str, Any]:
+            return verify_webhook(raw_body, signature, secret, check_timestamp=check_timestamp)
+
+        async def _request(self, method: str, path: str, body: dict | None = None) -> dict[str, Any]:
+            if not self._httpx:
+                raise PingrError(
+                    "Use AsyncPingr as a context manager: async with AsyncPingr(...) as client:",
+                    "not_initialized",
+                )
+            try:
+                import httpx
+            except ImportError as exc:
+                raise ImportError("httpx is required for AsyncPingr. Install with: pip install pingr[async]") from exc
+
+            try:
+                resp = await self._httpx.request(
+                    method,
+                    self._base_url + path,
+                    json=body,
+                    headers={
+                        "X-API-Key"  : self._api_key,
+                        "User-Agent" : f"pingr-python/{_SDK_VERSION}",
+                    },
+                )
+            except httpx.RequestError as exc:
+                raise PingrError(f"Network error: {exc}", "network_error") from exc
+
+            if resp.is_success:
+                return resp.json()
+
+            raise _parse_error(resp.status_code, resp.content, resp.headers)
+
+except ImportError:
+    pass

hey_pingr-0.1.0/pingr/errors.py

@@ -0,0 +1,40 @@
+class PingrError(Exception):
+    """Base class for all Pingr SDK errors."""
+
+    def __init__(self, message: str, code: str = "unknown_error", status: int | None = None, retry_after: int | None = None):
+        super().__init__(message)
+        self.message = message
+        self.code = code
+        self.status = status
+        self.retry_after = retry_after
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}(message={self.message!r}, code={self.code!r})"
+
+
+class PingrAuthError(PingrError):
+    """Raised when the API key is missing, malformed, or inactive."""
+
+    def __init__(self, message: str = "Invalid or inactive API key"):
+        super().__init__(message, code="auth_error", status=401)
+
+
+class PingrRateLimitError(PingrError):
+    """Raised when the monthly quota or per-number cooldown is exceeded."""
+
+    def __init__(self, message: str, code: str = "rate_limit", retry_after: int | None = None):
+        super().__init__(message, code=code, status=429, retry_after=retry_after)
+
+
+class PingrValidationError(PingrError):
+    """Raised when request parameters are invalid."""
+
+    def __init__(self, message: str):
+        super().__init__(message, code="validation_error", status=422)
+
+
+class PingrWebhookError(PingrError):
+    """Raised when webhook signature verification fails."""
+
+    def __init__(self, message: str):
+        super().__init__(message, code="webhook_error")

hey_pingr-0.1.0/pingr/webhook.py

@@ -0,0 +1,76 @@
+"""Webhook signature verification for Pingr."""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import time
+from typing import Any
+
+from .errors import PingrWebhookError
+
+_TOLERANCE_SECONDS = 5 * 60  # 5 minutes
+
+
+def verify_webhook(
+    raw_body: bytes | str,
+    signature: str,
+    secret: str,
+    *,
+    check_timestamp: bool = True,
+) -> dict[str, Any]:
+    """Verify a Pingr webhook signature and return the parsed payload.
+
+    Pingr signs every webhook POST with HMAC-SHA256.
+    The signature arrives in the ``x-pingr-signature`` header as ``sha256=<hex>``.
+
+    Args:
+        raw_body:        Raw request body bytes (do **not** JSON-decode first).
+        signature:       Value of the ``x-pingr-signature`` header.
+        secret:          Your webhook signing secret (``whsec_...``).
+        check_timestamp: If True (default), reject payloads older than 5 minutes.
+
+    Returns:
+        Parsed webhook payload as a dict.
+
+    Raises:
+        PingrWebhookError: If the signature is invalid or the timestamp is stale.
+
+    Example::
+
+        # Flask
+        @app.route('/webhook', methods=['POST'])
+        def webhook():
+            payload = verify_webhook(
+                request.get_data(),
+                request.headers['x-pingr-signature'],
+                os.environ['PINGR_WEBHOOK_SECRET'],
+            )
+            print(payload['event'])
+            return '', 200
+    """
+    if not signature or not signature.startswith("sha256="):
+        raise PingrWebhookError("Missing or malformed x-pingr-signature header")
+
+    body = raw_body if isinstance(raw_body, bytes) else raw_body.encode()
+    expected = "sha256=" + hmac.new(
+        secret.encode(), body, hashlib.sha256
+    ).hexdigest()
+
+    if not hmac.compare_digest(signature.encode(), expected.encode()):
+        raise PingrWebhookError("Webhook signature verification failed")
+
+    try:
+        payload = json.loads(body)
+    except json.JSONDecodeError as exc:
+        raise PingrWebhookError(f"Webhook body is not valid JSON: {exc}") from exc
+
+    if check_timestamp:
+        ts = payload.get("timestamp")
+        if ts is None or abs(time.time() * 1000 - ts) > _TOLERANCE_SECONDS * 1000:
+            raise PingrWebhookError(
+                "Webhook timestamp is too old or missing — possible replay attack"
+            )
+
+    return payload

hey_pingr-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["setuptools>=42", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "hey-pingr"
+version = "0.1.0"
+description = "Official Python SDK for the Pingr WhatsApp messaging API"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "Pingr", email = "support@heypingr.com" }]
+requires-python = ">=3.9"
+keywords = ["pingr", "whatsapp", "messaging", "otp", "api", "sdk"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Communications",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = []
+
+[project.optional-dependencies]
+async = ["httpx>=0.25"]
+dev   = ["httpx>=0.25", "pytest", "pytest-asyncio"]
+
+[project.urls]
+Homepage   = "https://heypingr.com"
+Docs       = "https://heypingr.com/docs"
+Repository = "https://github.com/heypingr/pingr-python"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["pingr*"]

hey_pingr-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+