itaja 0.1.0__py3-none-any.whl

itaja/__init__.py

@@ -0,0 +1,77 @@
+"""Itaja for Python servers: declare what you sell, push it, mount one webhook route, react to events."""
+
+from ._transport import DEFAULT_BASE_URL, mode_of_key
+from ._version import SDK_VERSION
+from .catalog import (
+    CreditPack,
+    Credits,
+    Feature,
+    Group,
+    License,
+    Plan,
+    credit_pack,
+    credits,
+    feature,
+    group,
+    license,
+    plan,
+    to_catalog_document,
+)
+from .client import Itaja, create_itaja
+from .errors import (
+    ItajaAuthenticationError,
+    ItajaConfigError,
+    ItajaConflictError,
+    ItajaConnectionError,
+    ItajaError,
+    ItajaNotFoundError,
+    ItajaPermissionError,
+    ItajaRateLimitError,
+    ItajaServerError,
+    ItajaSignatureError,
+    ItajaValidationError,
+)
+from .handler import DedupeStore, MemoryDedupeStore, WebhookProcessor, WebhookResult
+from .webhooks import EVENT_TYPES, Event, construct_event, sign_payload
+
+__version__ = SDK_VERSION
+
+__all__ = [
+    "DEFAULT_BASE_URL",
+    "EVENT_TYPES",
+    "SDK_VERSION",
+    "CreditPack",
+    "Credits",
+    "DedupeStore",
+    "Event",
+    "Feature",
+    "Group",
+    "Itaja",
+    "ItajaAuthenticationError",
+    "ItajaConfigError",
+    "ItajaConflictError",
+    "ItajaConnectionError",
+    "ItajaError",
+    "ItajaNotFoundError",
+    "ItajaPermissionError",
+    "ItajaRateLimitError",
+    "ItajaServerError",
+    "ItajaSignatureError",
+    "ItajaValidationError",
+    "License",
+    "MemoryDedupeStore",
+    "Plan",
+    "WebhookProcessor",
+    "WebhookResult",
+    "construct_event",
+    "create_itaja",
+    "credit_pack",
+    "credits",
+    "feature",
+    "group",
+    "license",
+    "mode_of_key",
+    "plan",
+    "sign_payload",
+    "to_catalog_document",
+]

itaja/_transport.py

@@ -0,0 +1,144 @@
+"""The HTTP layer: the ``{success, data}`` envelope unwrapped, typed errors, and
+retries that can never charge twice.
+
+Retry rule: only a call that is safe to send again is retried. The SDK puts an
+``Idempotency-Key`` on EVERY write (one per logical call, reused on each retry),
+so the API answers a retry with the first response instead of running it again.
+Retried: no response, ``5xx``, ``429`` and ``409 IDEMPOTENCY_KEY_IN_PROGRESS``.
+``Retry-After`` is honoured, with a ceiling.
+"""
+
+from __future__ import annotations
+
+import email.utils
+import random
+import time
+import uuid
+from collections.abc import Callable, Mapping
+from typing import Any, Literal
+
+import httpx
+
+from ._version import SDK_VERSION
+from .errors import ItajaConfigError, ItajaConnectionError, error_for_status
+
+DEFAULT_BASE_URL = "https://api.getitaja.com/api/v1"
+Method = Literal["GET", "POST", "PUT", "PATCH", "DELETE"]
+_RETRYABLE_CONFLICT = "IDEMPOTENCY_KEY_IN_PROGRESS"
+_MAX_WAIT = 30.0
+
+
+def mode_of_key(api_key: str | None) -> Literal["sandbox", "live"]:
+    """The collection mode a key acts in: the prefix decides, never an option."""
+    return "sandbox" if (api_key or "").startswith("itjs_") else "live"
+
+
+class Transport:
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 30.0,
+        max_retries: int = 2,
+        http: httpx.Client | None = None,
+        sleep: Callable[[float], None] = time.sleep,
+    ) -> None:
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.max_retries = max_retries
+        self._sleep = sleep
+        self._owns_http = http is None
+        self._http = http or httpx.Client(timeout=timeout)
+
+    def close(self) -> None:
+        if self._owns_http:
+            self._http.close()
+
+    @property
+    def mode(self) -> Literal["sandbox", "live"]:
+        return mode_of_key(self.api_key)
+
+    def request(
+        self,
+        method: Method,
+        path: str,
+        *,
+        query: Mapping[str, Any] | None = None,
+        body: Any = None,
+        idempotency_key: str | None = None,
+    ) -> Any:
+        if not self.api_key:
+            raise ItajaConfigError("No Itaja API key. Set ITAJA_API_KEY, or pass api_key.", code="API_KEY_MISSING")
+        is_write = method != "GET"
+        key = (idempotency_key or str(uuid.uuid4())) if is_write else None
+        params = {k: v for k, v in (query or {}).items() if v is not None}
+        headers = {
+            "x-itj-key": self.api_key,
+            "x-itaja-client": f"itaja-python/{SDK_VERSION}",
+            "accept": "application/json",
+        }
+        if key is not None:
+            headers["Idempotency-Key"] = key
+        url = f"{self.base_url}/{path.lstrip('/')}"
+
+        attempt = 0
+        while True:
+            try:
+                response = self._http.request(method, url, params=params or None, json=body, headers=headers)
+            except httpx.TransportError as error:
+                if attempt < self.max_retries:
+                    self._sleep(_backoff(attempt))
+                    attempt += 1
+                    continue
+                raise ItajaConnectionError(
+                    f"Could not reach Itaja: {type(error).__name__}", code="CONNECTION_ERROR"
+                ) from None
+
+            try:
+                payload = response.json()
+            except ValueError:
+                payload = {}
+            if not isinstance(payload, dict):
+                payload = {}
+            status = response.status_code
+
+            if status < 300 and payload.get("success", True) is not False:
+                return payload.get("data", payload)
+
+            retry_after = _retry_after(response.headers.get("retry-after"))
+            retryable = status >= 500 or status == 429 or (status == 409 and payload.get("code") == _RETRYABLE_CONFLICT)
+            if retryable and attempt < self.max_retries:
+                self._sleep(min(retry_after, _MAX_WAIT) if retry_after is not None else _backoff(attempt))
+                attempt += 1
+                continue
+
+            details = payload.get("details")
+            message = payload.get("error")
+            code = payload.get("code")
+            raise error_for_status(
+                status,
+                message=message if isinstance(message, str) else f"Itaja answered HTTP {status}",
+                code=code if isinstance(code, str) else f"HTTP_{status}",
+                request_id=response.headers.get("x-request-id"),
+                details=details if isinstance(details, dict) else None,
+                retry_after_seconds=int(retry_after) if retry_after is not None else None,
+            )
+
+
+def _backoff(attempt: int) -> float:
+    return float(min(0.5 * (2**attempt) + random.uniform(0, 0.25), _MAX_WAIT))
+
+
+def _retry_after(value: str | None) -> float | None:
+    if not value:
+        return None
+    try:
+        seconds = float(value)
+        return seconds if seconds >= 0 else None
+    except ValueError:
+        pass
+    parsed = email.utils.parsedate_to_datetime(value) if value else None
+    if parsed is None:
+        return None
+    return max(0.0, parsed.timestamp() - time.time())

itaja/_version.py

@@ -0,0 +1 @@
+SDK_VERSION = "0.1.0"

itaja/catalog.py

@@ -0,0 +1,388 @@
+"""The catalogue in code: one builder per way of selling, and ``to_catalog_document``
+that turns what you declared into the canonical JSON ``PUT /v1/catalog`` takes
+(``spec/catalog.schema.json``).
+
+Every id is **yours** (``"free"``, ``"pro"``, ``"messages"``). Amounts are in
+**major units** of their currency, as on every product route of the API
+(``5000`` XOF, ``9.99`` EUR).
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Iterable, Sequence
+from dataclasses import dataclass, field
+from typing import Any, Literal, TypedDict
+
+from .errors import ItajaConfigError
+
+Interval = Literal["week", "month", "quarter", "year"]
+Reset = Literal["day", "week", "month", "year"]
+
+INTERVALS: tuple[str, ...] = ("week", "month", "quarter", "year")
+RESETS: tuple[str, ...] = ("day", "week", "month", "year")
+_ID = re.compile(r"^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$")
+_DURATION = re.compile(r"^(lifetime|days-\d+|from-first-activation-days-\d+)$")
+_CURRENCY = re.compile(r"^[A-Za-z]{3}$")
+
+
+class Money(TypedDict):
+    """``{"amount": 5000, "currency": "XOF"}``: major units, ISO 4217."""
+
+    amount: float
+    currency: str
+
+
+class _PriceRequired(TypedDict):
+    amount: float
+    currency: str
+    interval: Interval
+
+
+class Price(_PriceRequired, total=False):
+    """A recurring price: ``{"amount": 5000, "currency": "XOF", "interval": "month"}``."""
+
+    intervalCount: int
+
+
+class Inclusion(TypedDict, total=False):
+    feature: str
+    limit: int
+    reset: Reset
+
+
+def _error(message: str) -> ItajaConfigError:
+    return ItajaConfigError(message, code="CATALOG_DECLARATION_INVALID")
+
+
+def _assert_id(value: str, what: str) -> None:
+    if not isinstance(value, str) or _ID.fullmatch(value) is None:
+        raise _error(
+            f'Invalid {what} id "{value}": 1 to 64 letters, digits, "_" or "-", starting with a letter or a digit.'
+        )
+
+
+def _assert_money(price: Any, what: str) -> None:
+    if not isinstance(price, dict) or "amount" not in price or "currency" not in price:
+        raise _error(f"{what}: price needs an `amount` (major units) and a `currency`.")
+    amount = price["amount"]
+    if isinstance(amount, bool) or not isinstance(amount, (int, float)) or amount < 0:
+        raise _error(f"{what}: price.amount must be a non-negative number.")
+    if not isinstance(price["currency"], str) or _CURRENCY.fullmatch(price["currency"]) is None:
+        raise _error(f"{what}: `currency` must be an ISO 4217 code such as XOF or EUR.")
+
+
+def _humanize(value: str) -> str:
+    words = re.sub(r"[_-]+", " ", value).strip()
+    return words[:1].upper() + words[1:]
+
+
+# ── Features ────────────────────────────────────────────────────────────────
+
+
+@dataclass(frozen=True)
+class Feature:
+    """A right. Call it to include it in a plan: ``export()`` or ``messages(limit=100, reset="month")``."""
+
+    id: str
+    type: Literal["boolean", "metered"]
+
+    def __post_init__(self) -> None:
+        _assert_id(self.id, "feature")
+
+    def __call__(self, limit: int | None = None, reset: Reset | None = None) -> Inclusion:
+        if self.type == "boolean":
+            if limit is not None or reset is not None:
+                raise _error(f'Feature "{self.id}" is boolean: include it as {self.id}(), without a limit.')
+            return {"feature": self.id}
+        if limit is None or isinstance(limit, bool) or not isinstance(limit, int) or limit < 0:
+            raise _error(f'Feature "{self.id}" is metered: include it with a whole, non-negative limit.')
+        if reset is not None and reset not in RESETS:
+            raise _error(f'Feature "{self.id}": reset must be one of {", ".join(RESETS)}.')
+        inclusion: Inclusion = {"feature": self.id, "limit": limit}
+        if reset is not None:
+            inclusion["reset"] = reset
+        return inclusion
+
+
+def feature(id: str, type: Literal["boolean", "metered"]) -> Feature:
+    """``feature("export", "boolean")`` (access) or ``feature("messages", "metered")`` (a quota per period)."""
+    if type not in ("boolean", "metered"):
+        raise _error(f'Feature "{id}": type must be "boolean" or "metered".')
+    return Feature(id, type)
+
+
+# ── Subscriptions ───────────────────────────────────────────────────────────
+
+
+@dataclass(frozen=True)
+class Group:
+    """A subscription product: its plans exclude one another for a customer."""
+
+    id: str
+    name: str
+    description: str | None = None
+
+    def __post_init__(self) -> None:
+        _assert_id(self.id, "group")
+
+
+def group(id: str, name: str, description: str | None = None) -> Group:
+    return Group(id, name, description)
+
+
+@dataclass(frozen=True)
+class Plan:
+    id: str
+    group: Group
+    name: str
+    description: str | None = None
+    price: Price | None = None
+    trial_days: int | None = None
+    default: bool = False
+    includes: tuple[Inclusion, ...] = field(default_factory=tuple)
+
+
+def plan(
+    id: str,
+    group: Group | str,
+    *,
+    name: str | None = None,
+    description: str | None = None,
+    price: Price | None = None,
+    trial_days: int | None = None,
+    default: bool = False,
+    includes: Sequence[Inclusion] = (),
+) -> Plan:
+    """A plan of a group. The group's ``default`` plan is its free fallback and may omit ``price``."""
+    _assert_id(id, "plan")
+    g = group if isinstance(group, Group) else Group(group, _humanize(group))
+    if not default and price is None:
+        raise _error(f'Plan "{id}" has no price: only the group\'s default plan may be free.')
+    if price is not None:
+        _assert_money(price, f'Plan "{id}"')
+        if price.get("interval") not in INTERVALS:
+            raise _error(f'Plan "{id}": price.interval must be one of {", ".join(INTERVALS)}.')
+    return Plan(id, g, name or _humanize(id), description, price, trial_days, default, tuple(includes))
+
+
+# ── Credits ─────────────────────────────────────────────────────────────────
+
+
+@dataclass(frozen=True)
+class Credits:
+    """A credit currency your app spends as the buyer uses it. Sell it with ``credit_pack``."""
+
+    id: str
+    name: str
+    description: str | None = None
+    #: What the buyer calls one credit (``Tokens``, ``Coins``).
+    coin_name: str | None = None
+
+    def __post_init__(self) -> None:
+        _assert_id(self.id, "credits")
+
+
+def credits(id: str, name: str, *, description: str | None = None, coin_name: str | None = None) -> Credits:
+    return Credits(id, name, description, coin_name)
+
+
+@dataclass(frozen=True)
+class CreditPack:
+    id: str
+    of: Credits
+    credits: int
+    price: Money
+    label: str
+    description: str | None = None
+
+
+def credit_pack(
+    id: str, of: Credits, credits: int, price: Money, *, label: str | None = None, description: str | None = None
+) -> CreditPack:
+    """A bundle of credits sold at a fixed price."""
+    _assert_id(id, "credit pack")
+    if isinstance(credits, bool) or not isinstance(credits, int) or credits < 1:
+        raise _error(f'Credit pack "{id}": credits must be a whole number of at least 1.')
+    _assert_money(price, f'Credit pack "{id}"')
+    return CreditPack(id, of, credits, price, label or f"{credits} {of.coin_name or of.name}", description)
+
+
+# ── Licences ────────────────────────────────────────────────────────────────
+
+
+@dataclass(frozen=True)
+class License:
+    id: str
+    name: str
+    price: Money
+    #: Devices one key unlocks; ``None`` = unlimited.
+    devices: int | None
+    duration: str | None = None
+    description: str | None = None
+
+
+def license(
+    id: str,
+    name: str,
+    *,
+    price: Money,
+    devices: int | None,
+    duration: str | None = None,
+    description: str | None = None,
+) -> License:
+    """A licence key that unlocks your software. ``duration``: ``"lifetime"``, ``"days-N"``,
+    ``"from-first-activation-days-N"``."""
+    _assert_id(id, "license")
+    _assert_money(price, f'License "{id}"')
+    if duration is not None and _DURATION.fullmatch(duration) is None:
+        raise _error(f'License "{id}": duration must be "lifetime", "days-N" or "from-first-activation-days-N".')
+    return License(id, name, price, devices, duration, description)
+
+
+# ── The catalogue ───────────────────────────────────────────────────────────
+
+CatalogItem = Feature | Plan | Credits | CreditPack | License
+
+
+def _drop_none(values: dict[str, Any]) -> dict[str, Any]:
+    return {k: v for k, v in values.items() if v is not None}
+
+
+def to_catalog_document(items: Iterable[CatalogItem]) -> dict[str, Any]:
+    """Turns a declaration into the canonical catalogue. Deterministic: the same declaration gives
+    the same JSON, in declaration order, in every language. Features are the ones you list."""
+    features: dict[str, dict[str, str]] = {}
+    groups: dict[str, tuple[Group, list[Plan]]] = {}
+    credit_products: dict[str, tuple[Credits, list[CreditPack]]] = {}
+    licenses: dict[str, License] = {}
+    order: list[tuple[str, str]] = []
+
+    def taken(product_id: str) -> bool:
+        return product_id in groups or product_id in credit_products or product_id in licenses
+
+    def duplicate(product_id: str) -> ItajaConfigError:
+        return _error(
+            f'Product id "{product_id}" is used twice in the catalogue '
+            "(groups, credits and licences share one id space)."
+        )
+
+    for item in items:
+        if isinstance(item, Feature):
+            known = features.get(item.id)
+            if known is not None and known["type"] != item.type:
+                raise _error(f'Feature "{item.id}" is declared twice with different types.')
+            features[item.id] = {"id": item.id, "type": item.type}
+        elif isinstance(item, Plan):
+            gid = item.group.id
+            if gid not in groups:
+                if taken(gid):
+                    raise duplicate(gid)
+                groups[gid] = (item.group, [])
+                order.append(("group", gid))
+            elif groups[gid][0].name != item.group.name:
+                raise _error(f'Group "{gid}" is declared with two different names.')
+            plans = groups[gid][1]
+            if any(p.id == item.id for p in plans):
+                raise _error(f'Plan "{item.id}" is declared twice in group "{gid}".')
+            if item.default and any(p.default for p in plans):
+                raise _error(f'Group "{gid}" has two default plans; keep one.')
+            plans.append(item)
+        elif isinstance(item, (Credits, CreditPack)):
+            currency = item if isinstance(item, Credits) else item.of
+            if currency.id not in credit_products:
+                if taken(currency.id):
+                    raise duplicate(currency.id)
+                credit_products[currency.id] = (currency, [])
+                order.append(("credits", currency.id))
+            if isinstance(item, CreditPack):
+                packs = credit_products[currency.id][1]
+                if any(p.id == item.id for p in packs):
+                    raise _error(f'Credit pack "{item.id}" is declared twice in "{currency.id}".')
+                packs.append(item)
+        elif isinstance(item, License):
+            if taken(item.id):
+                raise duplicate(item.id)
+            licenses[item.id] = item
+            order.append(("license", item.id))
+        else:
+            raise _error("The catalogue accepts feature, plan, credits, credit_pack and license items only.")
+
+    products: list[dict[str, Any]] = []
+    for kind, product_id in order:
+        if kind == "group":
+            g, plans = groups[product_id]
+            for p in plans:
+                for inclusion in p.includes:
+                    if inclusion["feature"] not in features:
+                        raise _error(
+                            f'Plan "{p.id}" includes feature "{inclusion["feature"]}", which the catalogue '
+                            "does not declare. Add the feature to the catalogue."
+                        )
+            products.append(
+                _drop_none(
+                    {
+                        "id": g.id,
+                        "type": "subscription",
+                        "name": g.name,
+                        "description": g.description,
+                        "plans": [
+                            _drop_none(
+                                {
+                                    "id": p.id,
+                                    "name": p.name,
+                                    "description": p.description,
+                                    "price": dict(p.price) if p.price is not None else None,
+                                    "trial": {"days": p.trial_days} if p.trial_days is not None else None,
+                                    "default": True if p.default else None,
+                                    "includes": [dict(i) for i in p.includes],
+                                }
+                            )
+                            for p in plans
+                        ],
+                    }
+                )
+            )
+        elif kind == "credits":
+            c, packs = credit_products[product_id]
+            if not packs:
+                raise _error(f'Credits "{c.id}" has no pack: declare at least one credit_pack for it.')
+            products.append(
+                _drop_none(
+                    {
+                        "id": c.id,
+                        "type": "credits",
+                        "name": c.name,
+                        "description": c.description,
+                        "coinName": c.coin_name,
+                        "packs": [
+                            _drop_none(
+                                {
+                                    "id": p.id,
+                                    "label": p.label,
+                                    "description": p.description,
+                                    "credits": p.credits,
+                                    "price": dict(p.price),
+                                }
+                            )
+                            for p in packs
+                        ],
+                    }
+                )
+            )
+        else:
+            lic = licenses[product_id]
+            document = _drop_none(
+                {
+                    "id": lic.id,
+                    "name": lic.name,
+                    "description": lic.description,
+                    "price": dict(lic.price),
+                    "duration": lic.duration,
+                    "type": "license",
+                }
+            )
+            document["devices"] = lic.devices  # null means unlimited: always sent
+            products.append(document)
+
+    return {"features": list(features.values()), "products": products}