esaalat 0.1.0__tar.gz

esaalat-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Esaalat
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

esaalat-0.1.0/PKG-INFO

@@ -0,0 +1,115 @@
+Metadata-Version: 2.4
+Name: esaalat
+Version: 0.1.0
+Summary: Server-side Esaalat client: locked checkout sessions, payment intents and signed webhook verification.
+Author-email: Esaalat <support@esaalat.com>
+License: MIT
+Project-URL: Homepage, https://esaalat.com/en/sdk
+Project-URL: Documentation, https://esaalat.com/en/api-reference
+Project-URL: Source, https://github.com/Esaalat/esaalat-python
+Keywords: esaalat,payments,checkout,webhook,yemen
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Office/Business :: Financial
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# esaalat (Python)
+
+**Server-side [Esaalat](https://esaalat.com) client.** It does the three things
+a merchant backend always writes by hand — the 1-hour token, the idempotency
+key, and the webhook HMAC — so an integration is three calls instead of forty
+lines.
+
+- **Locked checkout sessions** — create the session on your server, give the
+  browser only the token.
+- **Payment intents** — create one server-side for platform orders, attach the
+  buyer's reference, read status.
+- **Signed webhooks** — verify `X-Esaalat-Signature` over the raw body, with a
+  replay window.
+- **No dependencies** — standard library only (`urllib`, `hmac`, `json`).
+
+## Install
+
+```bash
+pip install esaalat
+```
+
+## Quick start
+
+```python
+from esaalat import EsaalatClient
+
+# Reads ESAALAT_CLIENT_ID, ESAALAT_CLIENT_SECRET and ESAALAT_WEBHOOK_SECRET.
+esaalat = EsaalatClient.from_env()
+
+# 1. Your server decides the amount; the browser gets only the token.
+session = esaalat.create_session(order_id="order-123", amount=5000)
+session["session_token"]  # → checkout.open({ sessionToken }) in the browser
+session["portal_url"]     # → or send the buyer straight to this page
+
+# 2. Fulfil on the signed webhook, never on the buyer's page.
+@app.post("/esaalat/webhooks")
+def webhook():
+    try:
+        event = esaalat.verify_webhook(
+            request.data,                      # the RAW body
+            request.headers["X-Esaalat-Signature"],
+        )
+    except EsaalatWebhookError:
+        return "", 400
+
+    if event["event"] == "payment.verified":
+        mark_order_paid(event["order_id"])     # idempotent on intent_id
+    return "", 200
+```
+
+Also available: `create_intent(wallet=..., amount=..., order_id=...)`,
+`retrieve_intent(intent_id)`, `attach_reference(intent_id, reference)` and
+`format_amount(value)`.
+
+## What it handles for you
+
+| | |
+|---|---|
+| **Token** | Issued once per client, cached, refreshed a minute before the JWT's own `exp`. |
+| **Idempotency** | A UUID per create call, reused on every retry — a 429 or a timeout can never double-book an order. |
+| **Retries** | `429`, `5xx` and network failures, honouring `Retry-After`. |
+| **Errors** | `EsaalatError` with `code`, `status`, `detail`, `attr` and the API's per-field `errors`. |
+| **Webhooks** | `hmac.compare_digest`, optional ±5 min window, `400`-shaped `EsaalatWebhookError`. |
+
+## Configuration
+
+| Argument | Environment | Default |
+|---|---|---|
+| `client_id` | `ESAALAT_CLIENT_ID` | — (required) |
+| `client_secret` | `ESAALAT_CLIENT_SECRET` | — (required) |
+| `webhook_secret` | `ESAALAT_WEBHOOK_SECRET` | — (needed by `verify_webhook`) |
+| `base_url` | `ESAALAT_BASE_URL` | `https://api.esaalat.com/api/v1` |
+| `timeout` | — | `20` seconds |
+| `max_retries` | — | `2` |
+
+Every endpoint takes a `secret=` override in `verify_webhook`, because each
+webhook endpoint on the dashboard has its own signing secret.
+
+## Notes
+
+- The client secret is a **server** secret. Never call this from a browser or
+  ship it in a mobile app; the browser only ever needs the session token.
+- Amounts are whole Yemeni riyals. `format_amount(5000.5)` refuses before the
+  request leaves your process.
+- The webhook body must be the **raw** bytes: `json.dumps(request.get_json())`
+  will not match the signature.
+
+## Development
+
+```bash
+python -m unittest discover -s tests -t .
+```
+
+## License
+
+MIT © Esaalat

esaalat-0.1.0/README.md

@@ -0,0 +1,96 @@
+# esaalat (Python)
+
+**Server-side [Esaalat](https://esaalat.com) client.** It does the three things
+a merchant backend always writes by hand — the 1-hour token, the idempotency
+key, and the webhook HMAC — so an integration is three calls instead of forty
+lines.
+
+- **Locked checkout sessions** — create the session on your server, give the
+  browser only the token.
+- **Payment intents** — create one server-side for platform orders, attach the
+  buyer's reference, read status.
+- **Signed webhooks** — verify `X-Esaalat-Signature` over the raw body, with a
+  replay window.
+- **No dependencies** — standard library only (`urllib`, `hmac`, `json`).
+
+## Install
+
+```bash
+pip install esaalat
+```
+
+## Quick start
+
+```python
+from esaalat import EsaalatClient
+
+# Reads ESAALAT_CLIENT_ID, ESAALAT_CLIENT_SECRET and ESAALAT_WEBHOOK_SECRET.
+esaalat = EsaalatClient.from_env()
+
+# 1. Your server decides the amount; the browser gets only the token.
+session = esaalat.create_session(order_id="order-123", amount=5000)
+session["session_token"]  # → checkout.open({ sessionToken }) in the browser
+session["portal_url"]     # → or send the buyer straight to this page
+
+# 2. Fulfil on the signed webhook, never on the buyer's page.
+@app.post("/esaalat/webhooks")
+def webhook():
+    try:
+        event = esaalat.verify_webhook(
+            request.data,                      # the RAW body
+            request.headers["X-Esaalat-Signature"],
+        )
+    except EsaalatWebhookError:
+        return "", 400
+
+    if event["event"] == "payment.verified":
+        mark_order_paid(event["order_id"])     # idempotent on intent_id
+    return "", 200
+```
+
+Also available: `create_intent(wallet=..., amount=..., order_id=...)`,
+`retrieve_intent(intent_id)`, `attach_reference(intent_id, reference)` and
+`format_amount(value)`.
+
+## What it handles for you
+
+| | |
+|---|---|
+| **Token** | Issued once per client, cached, refreshed a minute before the JWT's own `exp`. |
+| **Idempotency** | A UUID per create call, reused on every retry — a 429 or a timeout can never double-book an order. |
+| **Retries** | `429`, `5xx` and network failures, honouring `Retry-After`. |
+| **Errors** | `EsaalatError` with `code`, `status`, `detail`, `attr` and the API's per-field `errors`. |
+| **Webhooks** | `hmac.compare_digest`, optional ±5 min window, `400`-shaped `EsaalatWebhookError`. |
+
+## Configuration
+
+| Argument | Environment | Default |
+|---|---|---|
+| `client_id` | `ESAALAT_CLIENT_ID` | — (required) |
+| `client_secret` | `ESAALAT_CLIENT_SECRET` | — (required) |
+| `webhook_secret` | `ESAALAT_WEBHOOK_SECRET` | — (needed by `verify_webhook`) |
+| `base_url` | `ESAALAT_BASE_URL` | `https://api.esaalat.com/api/v1` |
+| `timeout` | — | `20` seconds |
+| `max_retries` | — | `2` |
+
+Every endpoint takes a `secret=` override in `verify_webhook`, because each
+webhook endpoint on the dashboard has its own signing secret.
+
+## Notes
+
+- The client secret is a **server** secret. Never call this from a browser or
+  ship it in a mobile app; the browser only ever needs the session token.
+- Amounts are whole Yemeni riyals. `format_amount(5000.5)` refuses before the
+  request leaves your process.
+- The webhook body must be the **raw** bytes: `json.dumps(request.get_json())`
+  will not match the signature.
+
+## Development
+
+```bash
+python -m unittest discover -s tests -t .
+```
+
+## License
+
+MIT © Esaalat

esaalat-0.1.0/esaalat/__init__.py

@@ -0,0 +1,21 @@
+"""Server-side Esaalat client.
+
+    from esaalat import EsaalatClient
+
+    esaalat = EsaalatClient.from_env()
+    session = esaalat.create_session(order_id="order-123", amount=5000)
+    event = esaalat.verify_webhook(request.data, signature)
+"""
+
+from .client import DEFAULT_API_BASE, EsaalatClient, format_amount
+from .errors import EsaalatError, EsaalatWebhookError
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "DEFAULT_API_BASE",
+    "EsaalatClient",
+    "EsaalatError",
+    "EsaalatWebhookError",
+    "format_amount",
+]

esaalat-0.1.0/esaalat/client.py

@@ -0,0 +1,474 @@
+"""Server-side Esaalat client.
+
+    from esaalat import EsaalatClient
+
+    esaalat = EsaalatClient.from_env()
+    session = esaalat.create_session(order_id="order-123", amount=5000)
+    # browser: checkout.open({ sessionToken: session["session_token"] })
+
+    event = esaalat.verify_webhook(request.data, request.headers["X-Esaalat-Signature"])
+
+The client owns the three parts a merchant backend always writes by hand: the
+1-hour token (cached, refreshed from its own ``exp`` claim), the idempotency
+key (generated per create, reused on every retry) and the webhook HMAC (raw
+body, constant-time compare, replay window). Standard library only.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+import json
+import os
+import time
+import urllib.error
+import urllib.request
+from decimal import Decimal
+from typing import Any, Callable, Dict, Mapping, Optional, Tuple, Union
+
+from .errors import EsaalatError, EsaalatWebhookError
+
+DEFAULT_API_BASE = "https://api.esaalat.com/api/v1"
+DEFAULT_TIMEOUT = 20.0
+DEFAULT_TOKEN_SKEW = 60.0
+# The JWT lives one hour and its `exp` is authoritative; this is the fallback
+# for an opaque token.
+DEFAULT_TOKEN_TTL = 3300.0
+DEFAULT_WEBHOOK_TOLERANCE = 300
+RETRY_BASE_SECONDS = 0.4
+
+Amount = Union[str, int, float, Decimal]
+
+# transport(method, url, headers, body, timeout) -> (status, headers, body)
+Transport = Callable[
+    [str, str, Mapping[str, str], Optional[bytes], float],
+    Tuple[int, Mapping[str, str], bytes],
+]
+
+
+def format_amount(value: Amount) -> str:
+    """Whole riyals, as the API requires.
+
+    ``5000``, ``5000.0``, ``Decimal("5000")`` and ``"5000"`` all become
+    ``"5000"``; a fraction is refused here rather than by the API after the
+    buyer has clicked pay.
+    """
+    if isinstance(value, bool):
+        raise EsaalatError(
+            "Amount must be a whole number of riyals, got a boolean.",
+            code="configuration",
+        )
+    if isinstance(value, int):
+        return str(value)
+    if isinstance(value, Decimal):
+        if value != value.to_integral_value():
+            raise EsaalatError(
+                "Amount must be a whole number of riyals, got %s." % value,
+                code="configuration",
+            )
+        return str(int(value))
+    if isinstance(value, float):
+        if not value.is_integer():
+            raise EsaalatError(
+                "Amount must be a whole number of riyals, got %s." % value,
+                code="configuration",
+            )
+        return str(int(value))
+    text = str(value).strip()
+    if not text.isdigit():
+        raise EsaalatError(
+            'Amount must be a whole number of riyals, got "%s".' % text,
+            code="configuration",
+        )
+    return text
+
+
+def _jwt_expiry(token: str) -> Optional[float]:
+    """The token's ``exp`` claim in epoch seconds, when it has one."""
+    parts = token.split(".")
+    if len(parts) != 3:
+        return None
+    payload = parts[1] + "=" * (-len(parts[1]) % 4)
+    try:
+        data = json.loads(base64.urlsafe_b64decode(payload.encode("ascii")))
+    except Exception:  # noqa: BLE001 - an opaque token is not an error here
+        return None
+    exp = data.get("exp") if isinstance(data, dict) else None
+    if isinstance(exp, (int, float)):
+        return float(exp)
+    return None
+
+
+def _urllib_transport(
+    method: str,
+    url: str,
+    headers: Mapping[str, str],
+    body: Optional[bytes],
+    timeout: float,
+) -> Tuple[int, Mapping[str, str], bytes]:
+    request = urllib.request.Request(
+        url, data=body, headers=dict(headers), method=method
+    )
+    try:
+        with urllib.request.urlopen(request, timeout=timeout) as response:
+            return response.status, dict(response.headers), response.read()
+    except urllib.error.HTTPError as error:
+        return error.code, dict(error.headers or {}), error.read()
+    except urllib.error.URLError as error:
+        raise EsaalatError(
+            "Could not reach Esaalat at %s." % url, code="network"
+        ) from error
+    except TimeoutError as error:
+        raise EsaalatError(
+            "Esaalat did not answer within %s s." % timeout, code="timeout"
+        ) from error
+
+
+def _api_error(status: int, raw: bytes) -> EsaalatError:
+    detail = ""
+    attr: Optional[str] = None
+    errors: list = []
+    try:
+        parsed = json.loads(raw.decode("utf-8")) if raw else {}
+    except (ValueError, UnicodeDecodeError):
+        parsed = {}
+    if isinstance(parsed, dict):
+        items = parsed.get("errors")
+        if not isinstance(items, list):
+            items = [parsed["detail"]] if "detail" in parsed else []
+        for item in items:
+            if isinstance(item, str):
+                errors.append({"code": "error", "detail": item, "attr": None})
+            elif isinstance(item, dict):
+                errors.append(
+                    {
+                        "code": item.get("code") or "error",
+                        "detail": item.get("detail") or "",
+                        "attr": item.get("attr"),
+                    }
+                )
+        if errors:
+            detail = errors[0]["detail"] or ""
+            attr = errors[0]["attr"]
+    if not detail:
+        detail = "Esaalat rejected the request (HTTP %s)." % status
+    return EsaalatError(detail, code="api", status=status, detail=detail,
+                        attr=attr, errors=errors)
+
+
+class EsaalatClient:
+    """Create sessions, intents and verify webhooks — with your client secret."""
+
+    def __init__(
+        self,
+        client_id: Optional[str] = None,
+        client_secret: Optional[str] = None,
+        *,
+        base_url: Optional[str] = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = 2,
+        webhook_secret: Optional[str] = None,
+        transport: Optional[Transport] = None,
+    ) -> None:
+        self.client_id = client_id or os.environ.get("ESAALAT_CLIENT_ID", "")
+        self.client_secret = client_secret or os.environ.get(
+            "ESAALAT_CLIENT_SECRET", ""
+        )
+        if not self.client_id or not self.client_secret:
+            raise EsaalatError(
+                "Missing API credentials. Pass client_id/client_secret or set "
+                "ESAALAT_CLIENT_ID and ESAALAT_CLIENT_SECRET.",
+                code="configuration",
+            )
+        self.base_url = (
+            base_url
+            or os.environ.get("ESAALAT_BASE_URL")
+            or DEFAULT_API_BASE
+        ).rstrip("/")
+        if not self.base_url.startswith(("http://", "https://")):
+            raise EsaalatError(
+                'base_url must be an http(s) URL, got "%s".' % self.base_url,
+                code="configuration",
+            )
+        self.timeout = float(timeout)
+        self.max_retries = int(max_retries)
+        self.webhook_secret = webhook_secret or os.environ.get(
+            "ESAALAT_WEBHOOK_SECRET"
+        )
+        self._transport = transport or _urllib_transport
+        self._token: Optional[str] = None
+        self._token_expires_at = 0.0
+
+    @classmethod
+    def from_env(cls, **kwargs: Any) -> "EsaalatClient":
+        """Build the client from ``ESAALAT_*`` environment variables."""
+        return cls(**kwargs)
+
+    # -- public surface ----------------------------------------------------
+
+    def create_session(self, **input: Any) -> Dict[str, Any]:
+        """Create a hosted checkout session and return the API's 201 payload.
+
+        ``order_id``/``external_order_id`` become ``external_order_id``;
+        ``amount`` must be whole riyals. The browser only needs
+        ``session_token`` from the response.
+        """
+        body = _session_body(input)
+        return self._request(
+            "POST",
+            "/checkout/merchant/sessions/",
+            body,
+            idempotency_key=input.get("idempotency_key")
+            or _uuid4(),
+        )
+
+    def create_intent(self, **input: Any) -> Dict[str, Any]:
+        """Create a payment intent (server-driven orders: marketplaces, Shopify)."""
+        body = {
+            "wallet": input.get("wallet"),
+            "currency": input.get("currency"),
+            "external_order_id": input.get("order_id")
+            or input.get("external_order_id"),
+            "notes": input.get("notes"),
+        }
+        if input.get("amount") is not None:
+            body["amount"] = format_amount(input["amount"])
+        if input.get("items"):
+            body["items"] = _items(input["items"])
+        return self._request(
+            "POST",
+            "/merchant/intents/",
+            body,
+            idempotency_key=input.get("idempotency_key") or _uuid4(),
+        )
+
+    def retrieve_intent(self, intent_id: str) -> Dict[str, Any]:
+        """Read one intent's current status."""
+        return self._request("GET", "/merchant/intents/%s/" % intent_id)
+
+    def attach_reference(self, intent_id: str, reference: str) -> Dict[str, Any]:
+        """Attach the buyer's wallet reference to a pending intent."""
+        return self._request(
+            "PATCH",
+            "/merchant/intents/%s/" % intent_id,
+            {"reference": reference},
+        )
+
+    def verify_webhook(
+        self,
+        raw_body: Union[bytes, str],
+        signature: str,
+        *,
+        secret: Optional[str] = None,
+        tolerance: int = DEFAULT_WEBHOOK_TOLERANCE,
+    ) -> Dict[str, Any]:
+        """Verify ``X-Esaalat-Signature`` over the raw body and return the event.
+
+        Pass the bytes you received, not a re-serialized object: the HMAC is
+        computed over exactly what Esaalat sent. Raises ``EsaalatWebhookError``
+        when the signature, its age, or the body itself does not hold up — catch
+        it and answer ``400``.
+        """
+        secret = secret or self.webhook_secret
+        if not secret:
+            raise EsaalatError(
+                "No webhook secret. Pass webhook_secret to EsaalatClient, set "
+                "ESAALAT_WEBHOOK_SECRET, or pass secret= per call.",
+                code="configuration",
+            )
+
+        timestamp, provided = _parse_signature(signature)
+        if tolerance and abs(time.time() - timestamp) > tolerance:
+            raise EsaalatWebhookError(
+                "Webhook timestamp is outside the %ss window (possible replay)."
+                % tolerance
+            )
+
+        body = raw_body.encode("utf-8") if isinstance(raw_body, str) else raw_body
+        expected = hmac.new(
+            secret.encode("utf-8"),
+            ("%s." % timestamp).encode("utf-8") + body,
+            hashlib.sha256,
+        ).hexdigest()
+        if not hmac.compare_digest(expected, provided):
+            raise EsaalatWebhookError(
+                "Webhook signature does not match. Verify against the raw "
+                "request body and this endpoint's secret."
+            )
+
+        try:
+            payload = json.loads(body.decode("utf-8"))
+        except (ValueError, UnicodeDecodeError) as error:
+            raise EsaalatWebhookError("Webhook body is not JSON.") from error
+        if not isinstance(payload, dict):
+            raise EsaalatWebhookError("Webhook body is not a JSON object.")
+        return payload
+
+    # -- internals ---------------------------------------------------------
+
+    def _access_token(self) -> str:
+        now = time.time()
+        if self._token and self._token_expires_at - DEFAULT_TOKEN_SKEW > now:
+            return self._token
+
+        status, _headers, raw = self._transport(
+            "POST",
+            self.base_url + "/merchant/token",
+            {
+                "ESAALAT-CLIENT-ID": self.client_id,
+                "ESAALAT-CLIENT-SECRET": self.client_secret,
+                "Accept": "application/json",
+            },
+            None,
+            self.timeout,
+        )
+        if not 200 <= status < 300:
+            raise _api_error(status, raw)
+
+        try:
+            data = json.loads(raw.decode("utf-8")) if raw else {}
+        except (ValueError, UnicodeDecodeError):
+            data = {}
+        token = data.get("access_token") if isinstance(data, dict) else None
+        if not isinstance(token, str) or not token:
+            raise EsaalatError(
+                "Esaalat did not return an access token.", status=status
+            )
+
+        self._token = token
+        self._token_expires_at = _jwt_expiry(token) or (now + DEFAULT_TOKEN_TTL)
+        return token
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        payload: Optional[Dict[str, Any]] = None,
+        *,
+        idempotency_key: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        url = self.base_url + path
+        body = (
+            json.dumps(_prune(payload)).encode("utf-8")
+            if payload is not None
+            else None
+        )
+        authorization = self._access_token()
+        refreshed = False
+        retries = 0
+
+        while True:
+            headers = {"Accept": "application/json"}
+            if body is not None:
+                headers["Content-Type"] = "application/json"
+            if authorization:
+                headers["Authorization"] = "Bearer " + authorization
+            if idempotency_key:
+                headers["ESAALAT-IDEMPOTENCY-KEY"] = idempotency_key
+
+            try:
+                status, response_headers, raw = self._transport(
+                    method, url, headers, body, self.timeout
+                )
+            except EsaalatError as error:
+                if error.code in ("network", "timeout") and retries < self.max_retries:
+                    time.sleep(RETRY_BASE_SECONDS * (2 ** retries))
+                    retries += 1
+                    continue
+                raise
+
+            if 200 <= status < 300:
+                if not raw:
+                    return {}
+                try:
+                    parsed = json.loads(raw.decode("utf-8"))
+                except (ValueError, UnicodeDecodeError) as error:
+                    raise EsaalatError(
+                        "Esaalat returned a response that is not JSON.",
+                        status=status,
+                    ) from error
+                return parsed if isinstance(parsed, dict) else {"data": parsed}
+
+            if status == 401 and not refreshed and authorization:
+                refreshed = True
+                self._token = None
+                authorization = self._access_token()
+                continue
+
+            if (status == 429 or status >= 500) and retries < self.max_retries:
+                delay = _retry_after(response_headers)
+                time.sleep(delay if delay is not None
+                           else RETRY_BASE_SECONDS * (2 ** retries))
+                retries += 1
+                continue
+
+            raise _api_error(status, raw)
+
+
+def _session_body(input: Dict[str, Any]) -> Dict[str, Any]:
+    body: Dict[str, Any] = {
+        "currency": input.get("currency"),
+        "external_order_id": input.get("order_id")
+        or input.get("external_order_id"),
+        "wallet": input.get("wallet"),
+        "notes": input.get("notes"),
+    }
+    if input.get("amount") is not None:
+        body["amount"] = format_amount(input["amount"])
+    if input.get("items"):
+        body["items"] = _items(input["items"])
+    if input.get("show_testing_wallet") is not None:
+        body["show_testing_wallet"] = bool(input["show_testing_wallet"])
+    return body
+
+
+def _items(items: Any) -> list:
+    normalized = []
+    for item in items:
+        entry = {
+            "name": item.get("name"),
+            "description": item.get("description"),
+            "price": format_amount(item["price"]),
+            "quantity": item.get("quantity"),
+        }
+        normalized.append(_prune(entry))
+    return normalized
+
+
+def _prune(payload: Optional[Dict[str, Any]]) -> Dict[str, Any]:
+    return {key: value for key, value in (payload or {}).items()
+            if value is not None}
+
+
+def _parse_signature(header: str) -> Tuple[int, str]:
+    timestamp: Optional[int] = None
+    signature = ""
+    for part in header.split(","):
+        key, _, value = part.strip().partition("=")
+        if key == "t":
+            try:
+                timestamp = int(value)
+            except ValueError:
+                timestamp = None
+        elif key == "v1":
+            signature = value.lower()
+    if timestamp is None or not signature:
+        raise EsaalatWebhookError("Malformed X-Esaalat-Signature header.")
+    return timestamp, signature
+
+
+def _retry_after(headers: Mapping[str, str]) -> Optional[float]:
+    for key, value in headers.items():
+        if key.lower() == "retry-after":
+            try:
+                return max(0.0, float(value))
+            except ValueError:
+                return None
+    return None
+
+
+def _uuid4() -> str:
+    import uuid
+
+    return str(uuid.uuid4())

esaalat-0.1.0/esaalat/errors.py

@@ -0,0 +1,45 @@
+"""Errors raised by the Esaalat server client."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+
+class EsaalatError(Exception):
+    """Every failure the client raises.
+
+    ``code`` says whose fault it is in the caller's terms:
+
+    * ``configuration`` — a key, a URL or a missing webhook secret.
+    * ``network`` / ``timeout`` — retry later.
+    * ``api`` — the request reached Esaalat and was rejected; ``status``,
+      ``detail`` and ``attr`` say what.
+    * ``webhook`` — a signature that does not verify.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        code: str = "api",
+        status: Optional[int] = None,
+        detail: Optional[str] = None,
+        attr: Optional[str] = None,
+        errors: Optional[List[Dict[str, Any]]] = None,
+    ) -> None:
+        super().__init__(message)
+        self.code = code
+        self.status = status
+        self.detail = detail
+        self.attr = attr
+        self.errors = errors or []
+
+    def __str__(self) -> str:  # pragma: no cover - inherited message is enough
+        return str(self.args[0]) if self.args else self.code
+
+
+class EsaalatWebhookError(EsaalatError):
+    """A webhook body that does not match its signature (or is stale)."""
+
+    def __init__(self, message: str, *, status: int = 400) -> None:
+        super().__init__(message, code="webhook", status=status)

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

@@ -0,0 +1,115 @@
+Metadata-Version: 2.4
+Name: esaalat
+Version: 0.1.0
+Summary: Server-side Esaalat client: locked checkout sessions, payment intents and signed webhook verification.
+Author-email: Esaalat <support@esaalat.com>
+License: MIT
+Project-URL: Homepage, https://esaalat.com/en/sdk
+Project-URL: Documentation, https://esaalat.com/en/api-reference
+Project-URL: Source, https://github.com/Esaalat/esaalat-python
+Keywords: esaalat,payments,checkout,webhook,yemen
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Office/Business :: Financial
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# esaalat (Python)
+
+**Server-side [Esaalat](https://esaalat.com) client.** It does the three things
+a merchant backend always writes by hand — the 1-hour token, the idempotency
+key, and the webhook HMAC — so an integration is three calls instead of forty
+lines.
+
+- **Locked checkout sessions** — create the session on your server, give the
+  browser only the token.
+- **Payment intents** — create one server-side for platform orders, attach the
+  buyer's reference, read status.
+- **Signed webhooks** — verify `X-Esaalat-Signature` over the raw body, with a
+  replay window.
+- **No dependencies** — standard library only (`urllib`, `hmac`, `json`).
+
+## Install
+
+```bash
+pip install esaalat
+```
+
+## Quick start
+
+```python
+from esaalat import EsaalatClient
+
+# Reads ESAALAT_CLIENT_ID, ESAALAT_CLIENT_SECRET and ESAALAT_WEBHOOK_SECRET.
+esaalat = EsaalatClient.from_env()
+
+# 1. Your server decides the amount; the browser gets only the token.
+session = esaalat.create_session(order_id="order-123", amount=5000)
+session["session_token"]  # → checkout.open({ sessionToken }) in the browser
+session["portal_url"]     # → or send the buyer straight to this page
+
+# 2. Fulfil on the signed webhook, never on the buyer's page.
+@app.post("/esaalat/webhooks")
+def webhook():
+    try:
+        event = esaalat.verify_webhook(
+            request.data,                      # the RAW body
+            request.headers["X-Esaalat-Signature"],
+        )
+    except EsaalatWebhookError:
+        return "", 400
+
+    if event["event"] == "payment.verified":
+        mark_order_paid(event["order_id"])     # idempotent on intent_id
+    return "", 200
+```
+
+Also available: `create_intent(wallet=..., amount=..., order_id=...)`,
+`retrieve_intent(intent_id)`, `attach_reference(intent_id, reference)` and
+`format_amount(value)`.
+
+## What it handles for you
+
+| | |
+|---|---|
+| **Token** | Issued once per client, cached, refreshed a minute before the JWT's own `exp`. |
+| **Idempotency** | A UUID per create call, reused on every retry — a 429 or a timeout can never double-book an order. |
+| **Retries** | `429`, `5xx` and network failures, honouring `Retry-After`. |
+| **Errors** | `EsaalatError` with `code`, `status`, `detail`, `attr` and the API's per-field `errors`. |
+| **Webhooks** | `hmac.compare_digest`, optional ±5 min window, `400`-shaped `EsaalatWebhookError`. |
+
+## Configuration
+
+| Argument | Environment | Default |
+|---|---|---|
+| `client_id` | `ESAALAT_CLIENT_ID` | — (required) |
+| `client_secret` | `ESAALAT_CLIENT_SECRET` | — (required) |
+| `webhook_secret` | `ESAALAT_WEBHOOK_SECRET` | — (needed by `verify_webhook`) |
+| `base_url` | `ESAALAT_BASE_URL` | `https://api.esaalat.com/api/v1` |
+| `timeout` | — | `20` seconds |
+| `max_retries` | — | `2` |
+
+Every endpoint takes a `secret=` override in `verify_webhook`, because each
+webhook endpoint on the dashboard has its own signing secret.
+
+## Notes
+
+- The client secret is a **server** secret. Never call this from a browser or
+  ship it in a mobile app; the browser only ever needs the session token.
+- Amounts are whole Yemeni riyals. `format_amount(5000.5)` refuses before the
+  request leaves your process.
+- The webhook body must be the **raw** bytes: `json.dumps(request.get_json())`
+  will not match the signature.
+
+## Development
+
+```bash
+python -m unittest discover -s tests -t .
+```
+
+## License
+
+MIT © Esaalat

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

@@ -0,0 +1,12 @@
+LICENSE
+README.md
+pyproject.toml
+esaalat/__init__.py
+esaalat/client.py
+esaalat/errors.py
+esaalat/py.typed
+esaalat.egg-info/PKG-INFO
+esaalat.egg-info/SOURCES.txt
+esaalat.egg-info/dependency_links.txt
+esaalat.egg-info/top_level.txt
+tests/test_client.py

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

@@ -0,0 +1 @@
+

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

@@ -0,0 +1 @@
+esaalat

esaalat-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "esaalat"
+version = "0.1.0"
+description = "Server-side Esaalat client: locked checkout sessions, payment intents and signed webhook verification."
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [{ name = "Esaalat", email = "support@esaalat.com" }]
+keywords = ["esaalat", "payments", "checkout", "webhook", "yemen"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Topic :: Office/Business :: Financial",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://esaalat.com/en/sdk"
+Documentation = "https://esaalat.com/en/api-reference"
+Source = "https://github.com/Esaalat/esaalat-python"
+
+[tool.setuptools.packages.find]
+include = ["esaalat*"]
+
+[tool.setuptools.package-data]
+esaalat = ["py.typed"]

esaalat-0.1.0/setup.cfg

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

esaalat-0.1.0/tests/test_client.py

@@ -0,0 +1,176 @@
+"""Tests for the Esaalat Python server client (standard library only)."""
+
+from __future__ import annotations
+
+import json
+import time
+import unittest
+
+from esaalat import EsaalatClient, EsaalatError, EsaalatWebhookError, format_amount
+
+SECRET = "whsec_test"
+TOKEN = "token-abc"
+
+
+class ScriptedTransport:
+    """Answers from a script and records what was sent."""
+
+    def __init__(self, responses):
+        self._responses = list(responses)
+        self.calls = []
+
+    def __call__(self, method, url, headers, body, timeout):
+        self.calls.append(
+            {"method": method, "url": url, "headers": dict(headers), "body": body}
+        )
+        if len(self._responses) > 1:
+            status, extra_headers, payload = self._responses.pop(0)
+        else:
+            status, extra_headers, payload = self._responses[0]
+        if isinstance(payload, bytes):
+            raw = payload
+        else:
+            raw = json.dumps(payload).encode("utf-8")
+        return status, extra_headers, raw
+
+
+def _client(*responses, **kwargs):
+    transport = ScriptedTransport(list(responses))
+    client = EsaalatClient(
+        "cid",
+        "secret",
+        webhook_secret=SECRET,
+        transport=transport,
+        **kwargs,
+    )
+    return client, transport
+
+
+def _sign(body: bytes, timestamp: int, secret: str = SECRET) -> str:
+    import hashlib
+    import hmac
+
+    digest = hmac.new(
+        secret.encode(), str(timestamp).encode() + b"." + body, hashlib.sha256
+    ).hexdigest()
+    return "t=%s,v1=%s" % (timestamp, digest)
+
+
+class SessionTests(unittest.TestCase):
+    def test_token_is_issued_once_and_reused(self):
+        client, transport = _client(
+            (200, {}, {"access_token": TOKEN}),
+            (201, {}, {"session_token": "s-1"}),
+            (201, {}, {"session_token": "s-2"}),
+        )
+
+        client.create_session(order_id="order-1", amount=5000)
+        client.create_session(order_id="order-2", amount=6000)
+
+        self.assertEqual(len(transport.calls), 3)
+        self.assertTrue(transport.calls[0]["url"].endswith("/merchant/token"))
+        self.assertEqual(
+            transport.calls[1]["headers"]["Authorization"], "Bearer " + TOKEN
+        )
+        self.assertEqual(
+            transport.calls[2]["headers"]["Authorization"], "Bearer " + TOKEN
+        )
+
+    def test_session_sends_amount_order_id_and_idempotency_key(self):
+        client, transport = _client(
+            (200, {}, {"access_token": TOKEN}),
+            (201, {}, {"session_token": "s-1"}),
+        )
+
+        client.create_session(order_id="order-123", amount="5000")
+
+        request = transport.calls[1]
+        self.assertTrue(
+            request["url"].endswith("/checkout/merchant/sessions/")
+        )
+        self.assertEqual(
+            json.loads(request["body"]),
+            {"amount": "5000", "external_order_id": "order-123"},
+        )
+        self.assertIn("ESAALAT-IDEMPOTENCY-KEY", request["headers"])
+
+    def test_retries_a_429_with_the_same_idempotency_key(self):
+        client, transport = _client(
+            (200, {}, {"access_token": TOKEN}),
+            (429, {"Retry-After": "0"}, {}),
+            (201, {}, {"session_token": "s-1"}),
+        )
+
+        session = client.create_session(order_id="order-9", amount=2500)
+
+        self.assertEqual(session["session_token"], "s-1")
+        creates = [call for call in transport.calls if "/sessions/" in call["url"]]
+        self.assertEqual(len(creates), 2)
+        self.assertEqual(
+            creates[0]["headers"]["ESAALAT-IDEMPOTENCY-KEY"],
+            creates[1]["headers"]["ESAALAT-IDEMPOTENCY-KEY"],
+        )
+
+    def test_api_error_carries_the_field(self):
+        client, _ = _client(
+            (200, {}, {"access_token": TOKEN}),
+            (
+                400,
+                {},
+                {
+                    "type": "validation_error",
+                    "errors": [
+                        {"code": "invalid", "detail": "Wallet not found.", "attr": "wallet"}
+                    ],
+                },
+            ),
+        )
+
+        with self.assertRaises(EsaalatError) as caught:
+            client.create_intent(wallet="missing", amount=1000)
+
+        self.assertEqual(caught.exception.code, "api")
+        self.assertEqual(caught.exception.status, 400)
+        self.assertEqual(caught.exception.attr, "wallet")
+        self.assertEqual(caught.exception.detail, "Wallet not found.")
+
+
+class WebhookTests(unittest.TestCase):
+    def test_verifies_a_signed_body(self):
+        client, _ = _client((200, {}, {"access_token": TOKEN}))
+        body = json.dumps({"event": "payment.verified", "intent_id": "i1"}).encode()
+        timestamp = int(time.time())
+
+        payload = client.verify_webhook(body, _sign(body, timestamp))
+
+        self.assertEqual(payload["event"], "payment.verified")
+        self.assertEqual(payload["intent_id"], "i1")
+
+    def test_rejects_a_tampered_body(self):
+        client, _ = _client((200, {}, {"access_token": TOKEN}))
+        body = b'{"event":"payment.verified","intent_id":"i1"}'
+        timestamp = int(time.time())
+
+        with self.assertRaises(EsaalatWebhookError):
+            client.verify_webhook(body.replace(b"i1", b"i2"), _sign(body, timestamp))
+
+    def test_rejects_a_stale_signature(self):
+        client, _ = _client((200, {}, {"access_token": TOKEN}))
+        body = b'{"event":"payment.verified"}'
+        stale = int(time.time()) - 3600
+
+        with self.assertRaises(EsaalatWebhookError):
+            client.verify_webhook(body, _sign(body, stale))
+
+
+class AmountTests(unittest.TestCase):
+    def test_whole_riyals_only(self):
+        self.assertEqual(format_amount(5000), "5000")
+        self.assertEqual(format_amount("5000"), "5000")
+        self.assertEqual(format_amount(5000.0), "5000")
+        with self.assertRaises(EsaalatError):
+            format_amount(5000.5)
+
+
+if __name__ == "__main__":
+    unittest.main()