fulkruma 0.1.0__py3-none-any.whl

fulkruma/__init__.py

@@ -0,0 +1,18 @@
+"""Official Python SDK for Fulkruma.
+
+Mirrors the Node SDK (`@forjio/fulkruma-node`) API surface — HMAC-signed
+requests, 14 resource namespaces, optional `X-Fulkruma-On-Behalf-Of`
+platform-admin scoping, plus webhook signature verification.
+"""
+
+from .client import FulkrumaClient
+from .errors import FulkrumaError
+from .webhooks import verify_webhook
+
+__all__ = [
+    "FulkrumaClient",
+    "FulkrumaError",
+    "verify_webhook",
+]
+
+__version__ = "0.1.0"

fulkruma/client.py

@@ -0,0 +1,237 @@
+"""High-level Fulkruma HMAC client.
+
+Mirrors `FulkrumaClient` from the Node SDK 1:1:
+
+- ``Authorization: Fulkruma-HMAC-SHA256 keyId=…, scope=*, signature=…``
+- ``X-Fulkruma-Timestamp: <unix>``
+- ``X-Fulkruma-On-Behalf-Of: <accountId>`` for platform-admin keys
+- ``Idempotency-Key`` on every mutation that needs replay safety
+- Standard ``{ data, error, meta }`` envelope unwrapping
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import time
+import uuid
+from typing import Any, Dict, Optional
+from urllib.parse import urlencode
+
+import httpx
+
+from .errors import FulkrumaError
+from .resources import (
+    AddressesResources,
+    AdminResources,
+    ApiKeysResources,
+    AuditLogResources,
+    BillingResources,
+    DeliveriesResources,
+    IntegrationsResources,
+    LicensesResources,
+    ProductsResources,
+    ShipmentsResources,
+    ShippingResources,
+    StatsResources,
+    StockResources,
+    WarehousesResources,
+    WebhooksResources,
+)
+
+
+class FulkrumaClient:
+    """HMAC-signed client for the Fulkruma REST API.
+
+    Parameters
+    ----------
+    key_id:
+        HMAC access key id, e.g. ``AKIAFULK...``.
+    secret:
+        HMAC secret.
+    base_url:
+        Default ``https://fulkruma.com``. Trailing slashes are stripped.
+    on_behalf_of:
+        Optional merchant ``accountId`` — forwarded as
+        ``X-Fulkruma-On-Behalf-Of``. Only allowed when ``key_id`` holds
+        the ``fulkruma:platform:admin`` scope.
+    timeout_ms:
+        Per-request timeout in milliseconds. Default 30 000.
+    http:
+        Inject a pre-configured ``httpx.Client`` (e.g. with a custom
+        transport for tests). Caller owns its lifecycle.
+    """
+
+    def __init__(
+        self,
+        *,
+        key_id: str,
+        secret: str,
+        base_url: str = "https://fulkruma.com",
+        on_behalf_of: Optional[str] = None,
+        timeout_ms: int = 30_000,
+        http: Optional[httpx.Client] = None,
+    ) -> None:
+        if not key_id or not secret:
+            raise ValueError("FulkrumaClient: key_id and secret are required")
+        self.key_id = key_id
+        self._secret = secret
+        self.base_url = base_url.rstrip("/")
+        self._default_obo = on_behalf_of
+        self.timeout_ms = timeout_ms
+        self._http = http or httpx.Client(timeout=timeout_ms / 1000.0)
+        self._owns_http = http is None
+
+        # Resource namespaces — match the Node SDK property names.
+        self.products = ProductsResources(self)
+        self.warehouses = WarehousesResources(self)
+        self.stock = StockResources(self)
+        self.addresses = AddressesResources(self)
+        self.shipments = ShipmentsResources(self)
+        self.shipping = ShippingResources(self)
+        self.licenses = LicensesResources(self)
+        self.deliveries = DeliveriesResources(self)
+        self.api_keys = ApiKeysResources(self)
+        self.audit_log = AuditLogResources(self)
+        self.billing = BillingResources(self)
+        self.integrations = IntegrationsResources(self)
+        self.stats = StatsResources(self)
+        self.webhooks = WebhooksResources(self)
+        self.admin = AdminResources(self)
+
+    # ─── Lifecycle ───────────────────────────────────────────────────────
+
+    def close(self) -> None:
+        if self._owns_http:
+            self._http.close()
+
+    def __enter__(self) -> "FulkrumaClient":
+        return self
+
+    def __exit__(self, *_: Any) -> None:
+        self.close()
+
+    def for_merchant(self, account_id: str) -> "FulkrumaClient":
+        """Clone scoped to a specific merchant. For platform-admin keys."""
+        return FulkrumaClient(
+            key_id=self.key_id,
+            secret=self._secret,
+            base_url=self.base_url,
+            on_behalf_of=account_id,
+            timeout_ms=self.timeout_ms,
+        )
+
+    # ─── Internal helpers ────────────────────────────────────────────────
+
+    @staticmethod
+    def _qs(params: Dict[str, Any]) -> str:
+        entries = [(k, v) for k, v in params.items() if v is not None]
+        if not entries:
+            return ""
+        # str(bool) → "True"/"False"; Node SDK emits the JS coercion ("true"/"false")
+        norm = []
+        for k, v in entries:
+            if isinstance(v, bool):
+                norm.append((k, "true" if v else "false"))
+            else:
+                norm.append((k, str(v)))
+        return "?" + urlencode(norm)
+
+    @staticmethod
+    def _gen_idem() -> str:
+        return f"idem_{uuid.uuid4()}"
+
+    def _sign(
+        self,
+        *,
+        method: str,
+        path: str,
+        body: Optional[str],
+        idempotency_key: Optional[str],
+    ) -> Dict[str, str]:
+        ts = str(int(time.time()))
+        body_hash = hashlib.sha256((body or "").encode("utf-8")).hexdigest()
+        idem = f"\n{idempotency_key}" if idempotency_key else ""
+        string_to_sign = f"{method.upper()}\n{path}\n{ts}\n{body_hash}{idem}"
+        signature = hmac.new(
+            self._secret.encode("utf-8"),
+            string_to_sign.encode("utf-8"),
+            hashlib.sha256,
+        ).hexdigest()
+        return {"signature": signature, "timestamp": ts}
+
+    # ─── Low-level request ───────────────────────────────────────────────
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        body: Any = None,
+        idempotency_key: Optional[str] = None,
+        on_behalf_of: Optional[str] = None,
+    ) -> Any:
+        body_json = json.dumps(body, separators=(",", ":")) if body is not None else None
+        signed = self._sign(
+            method=method, path=path, body=body_json, idempotency_key=idempotency_key,
+        )
+
+        headers: Dict[str, str] = {
+            "Accept": "application/json",
+            "Authorization": (
+                f"Fulkruma-HMAC-SHA256 keyId={self.key_id}, scope=*, "
+                f"signature={signed['signature']}"
+            ),
+            "X-Fulkruma-Timestamp": signed["timestamp"],
+        }
+        if body_json is not None:
+            headers["Content-Type"] = "application/json"
+        if idempotency_key:
+            headers["Idempotency-Key"] = idempotency_key
+        effective_obo = on_behalf_of if on_behalf_of is not None else self._default_obo
+        if effective_obo:
+            headers["X-Fulkruma-On-Behalf-Of"] = effective_obo
+
+        try:
+            res = self._http.request(
+                method.upper(),
+                f"{self.base_url}{path}",
+                headers=headers,
+                content=body_json,
+            )
+        except httpx.TimeoutException as exc:
+            raise FulkrumaError(
+                0, "timeout", f"Fulkruma request timed out after {self.timeout_ms}ms",
+            ) from exc
+        except httpx.HTTPError as exc:
+            raise FulkrumaError(0, "network_error", str(exc)) from exc
+
+        text = res.text
+        try:
+            env = json.loads(text) if text else {}
+        except ValueError:
+            raise FulkrumaError(
+                res.status_code, "invalid_response", f"Non-JSON response: {text[:200]}",
+            ) from None
+
+        request_id = None
+        if isinstance(env, dict):
+            meta = env.get("meta")
+            if isinstance(meta, dict):
+                request_id = meta.get("requestId")
+            err = env.get("error")
+        else:
+            err = None
+
+        if res.status_code >= 400 or err:
+            if not err:
+                err = {"code": "unknown", "message": f"HTTP {res.status_code}"}
+            raise FulkrumaError(
+                res.status_code,
+                err.get("code", "unknown"),
+                err.get("message", f"HTTP {res.status_code}"),
+                request_id,
+            )
+
+        return env.get("data") if isinstance(env, dict) else env

fulkruma/errors.py

@@ -0,0 +1,33 @@
+"""Typed error class for the Fulkruma SDK.
+
+Mirrors `FulkrumaError` from the Node SDK: every non-2xx response and
+every enveloped `{ error: { code, message } }` payload raises this with
+the upstream code preserved.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+
+class FulkrumaError(Exception):
+    """Raised on any non-success response from a Fulkruma endpoint."""
+
+    def __init__(
+        self,
+        status: int,
+        code: str,
+        message: str,
+        request_id: Optional[str] = None,
+    ) -> None:
+        super().__init__(message)
+        self.status = status
+        self.code = code
+        self.message = message
+        self.request_id = request_id
+
+    def __repr__(self) -> str:
+        return (
+            f"FulkrumaError(status={self.status}, code={self.code!r}, "
+            f"message={self.message!r}, request_id={self.request_id!r})"
+        )

fulkruma/resources.py

@@ -0,0 +1,351 @@
+"""Resource namespaces for FulkrumaClient — Python parity with fulkruma-node.
+
+Each builder takes the parent FulkrumaClient and exposes methods that map
+1:1 to backend REST routes. Every method accepts a keyword-only
+``on_behalf_of`` for per-call merchant override (no-op unless the key
+holds the ``fulkruma:platform:admin`` scope).
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Dict, List, Optional
+
+if TYPE_CHECKING:
+    from .client import FulkrumaClient
+
+
+class _Namespace:
+    def __init__(self, client: "FulkrumaClient") -> None:
+        self._c = client
+
+
+class ProductsResources(_Namespace):
+    def create(self, body: Dict[str, Any], *, on_behalf_of: Optional[str] = None):
+        return self._c.request(
+            "POST", "/api/v1/products", body=body,
+            idempotency_key=self._c._gen_idem(), on_behalf_of=on_behalf_of,
+        )
+
+    def get(self, product_id: str, *, on_behalf_of: Optional[str] = None):
+        return self._c.request("GET", f"/api/v1/products/{product_id}", on_behalf_of=on_behalf_of)
+
+    def list(self, *, archived: Optional[bool] = None, on_behalf_of: Optional[str] = None):
+        return self._c.request(
+            "GET", "/api/v1/products" + self._c._qs({"archived": archived}),
+            on_behalf_of=on_behalf_of,
+        )
+
+    def update(self, product_id: str, patch: Dict[str, Any], *, on_behalf_of: Optional[str] = None):
+        return self._c.request(
+            "PATCH", f"/api/v1/products/{product_id}", body=patch, on_behalf_of=on_behalf_of,
+        )
+
+    def archive(self, product_id: str, *, on_behalf_of: Optional[str] = None):
+        return self._c.request(
+            "DELETE", f"/api/v1/products/{product_id}", on_behalf_of=on_behalf_of,
+        )
+
+    def add_variant(self, product_id: str, body: Dict[str, Any], *, on_behalf_of: Optional[str] = None):
+        return self._c.request(
+            "POST", f"/api/v1/products/{product_id}/variants",
+            body=body, on_behalf_of=on_behalf_of,
+        )
+
+    def update_variant(
+        self, product_id: str, variant_id: str, patch: Dict[str, Any],
+        *, on_behalf_of: Optional[str] = None,
+    ):
+        return self._c.request(
+            "PATCH", f"/api/v1/products/{product_id}/variants/{variant_id}",
+            body=patch, on_behalf_of=on_behalf_of,
+        )
+
+    def archive_variant(self, product_id: str, variant_id: str, *, on_behalf_of: Optional[str] = None):
+        return self._c.request(
+            "DELETE", f"/api/v1/products/{product_id}/variants/{variant_id}",
+            on_behalf_of=on_behalf_of,
+        )
+
+
+class WarehousesResources(_Namespace):
+    def create(self, body: Dict[str, Any], *, on_behalf_of: Optional[str] = None):
+        return self._c.request("POST", "/api/v1/warehouses", body=body, on_behalf_of=on_behalf_of)
+
+    def list(self, *, on_behalf_of: Optional[str] = None):
+        return self._c.request("GET", "/api/v1/warehouses", on_behalf_of=on_behalf_of)
+
+    def update(self, warehouse_id: str, patch: Dict[str, Any], *, on_behalf_of: Optional[str] = None):
+        return self._c.request(
+            "PATCH", f"/api/v1/warehouses/{warehouse_id}", body=patch, on_behalf_of=on_behalf_of,
+        )
+
+    def archive(self, warehouse_id: str, *, on_behalf_of: Optional[str] = None):
+        return self._c.request(
+            "DELETE", f"/api/v1/warehouses/{warehouse_id}", on_behalf_of=on_behalf_of,
+        )
+
+
+class StockResources(_Namespace):
+    def levels(self, *, variant_id: Optional[str] = None, on_behalf_of: Optional[str] = None):
+        return self._c.request(
+            "GET", "/api/v1/stock/levels" + self._c._qs({"variant_id": variant_id}),
+            on_behalf_of=on_behalf_of,
+        )
+
+    def movements(self, *, variant_id: Optional[str] = None, on_behalf_of: Optional[str] = None):
+        return self._c.request(
+            "GET", "/api/v1/stock/movements" + self._c._qs({"variant_id": variant_id}),
+            on_behalf_of=on_behalf_of,
+        )
+
+    def reservations(self, *, on_behalf_of: Optional[str] = None):
+        return self._c.request("GET", "/api/v1/stock/reservations", on_behalf_of=on_behalf_of)
+
+    def adjust(self, body: Dict[str, Any], *, on_behalf_of: Optional[str] = None):
+        return self._c.request(
+            "POST", "/api/v1/stock/adjust", body=body,
+            idempotency_key=self._c._gen_idem(), on_behalf_of=on_behalf_of,
+        )
+
+
+class AddressesResources(_Namespace):
+    def list(self, *, customer_id: Optional[str] = None, on_behalf_of: Optional[str] = None):
+        return self._c.request(
+            "GET", "/api/v1/addresses" + self._c._qs({"customer_id": customer_id}),
+            on_behalf_of=on_behalf_of,
+        )
+
+    def create(self, body: Dict[str, Any], *, on_behalf_of: Optional[str] = None):
+        return self._c.request("POST", "/api/v1/addresses", body=body, on_behalf_of=on_behalf_of)
+
+    def delete(self, address_id: str, *, on_behalf_of: Optional[str] = None):
+        return self._c.request(
+            "DELETE", f"/api/v1/addresses/{address_id}", on_behalf_of=on_behalf_of,
+        )
+
+
+class ShipmentsResources(_Namespace):
+    def list(self, *, status: Optional[str] = None, on_behalf_of: Optional[str] = None):
+        return self._c.request(
+            "GET", "/api/v1/shipments" + self._c._qs({"status": status}),
+            on_behalf_of=on_behalf_of,
+        )
+
+    def get(self, shipment_id: str, *, on_behalf_of: Optional[str] = None):
+        return self._c.request("GET", f"/api/v1/shipments/{shipment_id}", on_behalf_of=on_behalf_of)
+
+    def create(self, body: Dict[str, Any], *, on_behalf_of: Optional[str] = None):
+        return self._c.request(
+            "POST", "/api/v1/shipments", body=body,
+            idempotency_key=self._c._gen_idem(), on_behalf_of=on_behalf_of,
+        )
+
+
+class ShippingResources(_Namespace):
+    def couriers(self, *, on_behalf_of: Optional[str] = None):
+        return self._c.request("GET", "/api/v1/shipping/couriers", on_behalf_of=on_behalf_of)
+
+    def origin(self, *, on_behalf_of: Optional[str] = None):
+        return self._c.request("GET", "/api/v1/shipping/origin", on_behalf_of=on_behalf_of)
+
+    def set_origin(self, body: Dict[str, Any], *, on_behalf_of: Optional[str] = None):
+        return self._c.request(
+            "PATCH", "/api/v1/shipping/origin", body=body, on_behalf_of=on_behalf_of,
+        )
+
+    def rates(self, body: Dict[str, Any], *, on_behalf_of: Optional[str] = None):
+        return self._c.request(
+            "POST", "/api/v1/shipping/rates", body=body, on_behalf_of=on_behalf_of,
+        )
+
+
+class LicensesResources(_Namespace):
+    def list(self, *, on_behalf_of: Optional[str] = None):
+        return self._c.request("GET", "/api/v1/licenses", on_behalf_of=on_behalf_of)
+
+    def issue(self, body: Dict[str, Any], *, on_behalf_of: Optional[str] = None):
+        return self._c.request(
+            "POST", "/api/v1/licenses", body=body,
+            idempotency_key=self._c._gen_idem(), on_behalf_of=on_behalf_of,
+        )
+
+    def revoke(self, license_id: str, *, on_behalf_of: Optional[str] = None):
+        return self._c.request(
+            "POST", f"/api/v1/licenses/{license_id}/revoke",
+            body={}, on_behalf_of=on_behalf_of,
+        )
+
+    def activate(self, body: Dict[str, Any]):
+        """Public unauthenticated endpoint — buyers' apps call this."""
+        return self._c.request("POST", "/api/v1/licenses/activate", body=body)
+
+    def deactivate(self, body: Dict[str, Any]):
+        """Public unauthenticated — release a previously-activated instance."""
+        return self._c.request("POST", "/api/v1/licenses/deactivate", body=body)
+
+    def validate(self, *, key: str, product_id: Optional[str] = None):
+        """Public unauthenticated — software pings this on launch."""
+        return self._c.request(
+            "GET", "/api/v1/licenses/validate" + self._c._qs({"key": key, "productId": product_id}),
+        )
+
+
+class DeliveriesResources(_Namespace):
+    def list(self, *, on_behalf_of: Optional[str] = None):
+        return self._c.request("GET", "/api/v1/deliveries", on_behalf_of=on_behalf_of)
+
+    def get(self, delivery_id: str, *, on_behalf_of: Optional[str] = None):
+        return self._c.request(
+            "GET", f"/api/v1/deliveries/{delivery_id}", on_behalf_of=on_behalf_of,
+        )
+
+    def create(self, body: Dict[str, Any], *, on_behalf_of: Optional[str] = None):
+        return self._c.request(
+            "POST", "/api/v1/deliveries", body=body,
+            idempotency_key=self._c._gen_idem(), on_behalf_of=on_behalf_of,
+        )
+
+
+class ApiKeysResources(_Namespace):
+    def list(self, *, on_behalf_of: Optional[str] = None):
+        return self._c.request("GET", "/api/v1/api-keys", on_behalf_of=on_behalf_of)
+
+    def create(self, body: Optional[Dict[str, Any]] = None, *, on_behalf_of: Optional[str] = None):
+        return self._c.request(
+            "POST", "/api/v1/api-keys", body=body or {},
+            idempotency_key=self._c._gen_idem(), on_behalf_of=on_behalf_of,
+        )
+
+    def revoke(self, key_id: str, *, on_behalf_of: Optional[str] = None):
+        return self._c.request(
+            "POST", f"/api/v1/api-keys/{key_id}/revoke",
+            body={}, on_behalf_of=on_behalf_of,
+        )
+
+
+class AuditLogResources(_Namespace):
+    def list(
+        self,
+        *,
+        limit: Optional[int] = None,
+        cursor: Optional[str] = None,
+        since: Optional[str] = None,
+        event_type: Optional[str] = None,
+        on_behalf_of: Optional[str] = None,
+    ):
+        return self._c.request(
+            "GET",
+            "/api/v1/audit-log" + self._c._qs({
+                "limit": limit,
+                "cursor": cursor,
+                "since": since,
+                "eventType": event_type,
+            }),
+            on_behalf_of=on_behalf_of,
+        )
+
+
+class BillingResources(_Namespace):
+    def plans(self, *, on_behalf_of: Optional[str] = None):
+        return self._c.request("GET", "/api/v1/billing/plans", on_behalf_of=on_behalf_of)
+
+    def current_plan(self, *, on_behalf_of: Optional[str] = None):
+        return self._c.request("GET", "/api/v1/billing/plan", on_behalf_of=on_behalf_of)
+
+    def subscription(self, *, on_behalf_of: Optional[str] = None):
+        return self._c.request("GET", "/api/v1/billing/subscription", on_behalf_of=on_behalf_of)
+
+    def usage(self, *, on_behalf_of: Optional[str] = None):
+        return self._c.request("GET", "/api/v1/billing/usage", on_behalf_of=on_behalf_of)
+
+    def invoices(
+        self, *, limit: Optional[int] = None, cursor: Optional[str] = None,
+        on_behalf_of: Optional[str] = None,
+    ):
+        return self._c.request(
+            "GET",
+            "/api/v1/billing/invoices" + self._c._qs({"limit": limit, "cursor": cursor}),
+            on_behalf_of=on_behalf_of,
+        )
+
+    def checkout(self, body: Dict[str, Any], *, on_behalf_of: Optional[str] = None):
+        return self._c.request(
+            "POST", "/api/v1/billing/checkout", body=body, on_behalf_of=on_behalf_of,
+        )
+
+    def cancel(self, *, on_behalf_of: Optional[str] = None):
+        return self._c.request(
+            "POST", "/api/v1/billing/cancel", body={}, on_behalf_of=on_behalf_of,
+        )
+
+
+class IntegrationsResources(_Namespace):
+    def status(self, *, on_behalf_of: Optional[str] = None):
+        return self._c.request("GET", "/api/v1/integrations/status", on_behalf_of=on_behalf_of)
+
+
+class StatsResources(_Namespace):
+    def overview(self, *, on_behalf_of: Optional[str] = None):
+        return self._c.request("GET", "/api/v1/stats/overview", on_behalf_of=on_behalf_of)
+
+
+class WebhooksResources(_Namespace):
+    def list_endpoints(self, *, on_behalf_of: Optional[str] = None):
+        return self._c.request(
+            "GET", "/api/v1/webhooks/endpoints", on_behalf_of=on_behalf_of,
+        )
+
+    def create_endpoint(self, body: Dict[str, Any], *, on_behalf_of: Optional[str] = None):
+        return self._c.request(
+            "POST", "/api/v1/webhooks/endpoints", body=body,
+            idempotency_key=self._c._gen_idem(), on_behalf_of=on_behalf_of,
+        )
+
+    def update_endpoint(self, endpoint_id: str, patch: Dict[str, Any], *, on_behalf_of: Optional[str] = None):
+        return self._c.request(
+            "PATCH", f"/api/v1/webhooks/endpoints/{endpoint_id}",
+            body=patch, on_behalf_of=on_behalf_of,
+        )
+
+    def delete_endpoint(self, endpoint_id: str, *, on_behalf_of: Optional[str] = None):
+        return self._c.request(
+            "DELETE", f"/api/v1/webhooks/endpoints/{endpoint_id}",
+            on_behalf_of=on_behalf_of,
+        )
+
+    def list_events(
+        self,
+        *,
+        limit: Optional[int] = None,
+        cursor: Optional[str] = None,
+        type: Optional[str] = None,
+        on_behalf_of: Optional[str] = None,
+    ):
+        return self._c.request(
+            "GET",
+            "/api/v1/webhooks/events"
+            + self._c._qs({"limit": limit, "cursor": cursor, "type": type}),
+            on_behalf_of=on_behalf_of,
+        )
+
+
+class AdminResources(_Namespace):
+    def provision_workspace(self, body: Dict[str, Any]):
+        """Idempotent — refuses to re-route a workspace already provisioned
+        by a different partner. Mirrors the Node SDK key `ws_<acc>_<partner>`."""
+        account_id = body.get("accountId", "unknown")
+        partner = body.get("partner", "unknown")
+        return self._c.request(
+            "POST", "/api/v1/admin/workspaces", body=body,
+            idempotency_key=f"ws_{account_id}_{partner}",
+        )
+
+    def get_workspace(self, account_id: str):
+        return self._c.request("GET", f"/api/v1/admin/workspaces/{account_id}")
+
+    def partner_usage(self, *, partner: str, from_: str, to: str):
+        return self._c.request(
+            "GET",
+            "/api/v1/admin/partner/usage"
+            + self._c._qs({"partner": partner, "from": from_, "to": to}),
+        )

fulkruma/webhooks.py

@@ -0,0 +1,112 @@
+"""HMAC-SHA256 webhook signature verifier for Fulkruma.
+
+Fulkruma signs every webhook delivery with::
+
+    Fulkruma-Signature: t=<unix_seconds>,v1=<hex>
+
+where ``<hex> = HMAC-SHA256(secret, f"{t}.{rawBody}")``. The *raw* body
+bytes are what got signed — re-serialising parsed JSON will produce
+different whitespace and the signature will never match.
+
+Flask example::
+
+    from flask import Flask, request, abort
+    from fulkruma import verify_webhook, FulkrumaError
+
+    app = Flask(__name__)
+
+    @app.post("/webhooks/fulkruma")
+    def fulkruma_hook():
+        raw = request.get_data()
+        sig = request.headers.get("Fulkruma-Signature")
+        try:
+            event = verify_webhook(raw_body=raw, signature=sig, secret=SECRET)
+        except FulkrumaError:
+            abort(400)
+        # event["type"], event["data"], ...
+        return "", 204
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import time
+from typing import Any, Dict, Optional, Union
+
+from .errors import FulkrumaError
+
+
+def verify_webhook(
+    *,
+    raw_body: Union[bytes, str],
+    signature: Optional[str],
+    secret: str,
+    tolerance_sec: int = 300,
+    now: Optional[float] = None,
+) -> Dict[str, Any]:
+    """Verify and parse an inbound Fulkruma webhook.
+
+    Returns the decoded event envelope on success. Raises
+    :class:`FulkrumaError` on any failure (missing header, drift, bad
+    signature, malformed JSON).
+
+    Parameters
+    ----------
+    raw_body:
+        The unparsed request body as received over the wire. ``str`` is
+        encoded as UTF-8 before hashing.
+    signature:
+        The value of the ``Fulkruma-Signature`` header.
+    secret:
+        The endpoint's shared signing secret.
+    tolerance_sec:
+        Maximum drift in seconds — defaults to 300 (5 min), matching the
+        Node SDK and Stripe/GitHub conventions.
+    now:
+        Inject a clock for tests; seconds since epoch.
+    """
+    if not signature:
+        raise FulkrumaError(0, "missing_signature", "missing Fulkruma-Signature header")
+
+    parts: Dict[str, str] = {}
+    for segment in signature.split(","):
+        segment = segment.strip()
+        if not segment or "=" not in segment:
+            continue
+        k, _, v = segment.partition("=")
+        parts[k.strip()] = v.strip()
+
+    ts = parts.get("t")
+    v1 = parts.get("v1")
+    if not ts or not v1:
+        raise FulkrumaError(0, "malformed_signature", "malformed signature header")
+
+    try:
+        ts_num = int(ts)
+    except ValueError:
+        raise FulkrumaError(0, "malformed_signature", "non-numeric timestamp") from None
+
+    current = now if now is not None else time.time()
+    drift = abs(int(current) - ts_num)
+    if drift > tolerance_sec:
+        raise FulkrumaError(
+            0, "signature_expired", f"signature timestamp {drift}s out of tolerance",
+        )
+
+    body_bytes = raw_body.encode("utf-8") if isinstance(raw_body, str) else raw_body
+    expected = hmac.new(
+        secret.encode("utf-8"),
+        f"{ts}.".encode("utf-8") + body_bytes,
+        hashlib.sha256,
+    ).hexdigest()
+
+    if not hmac.compare_digest(expected, v1):
+        raise FulkrumaError(0, "bad_signature", "bad signature")
+
+    body_str = body_bytes.decode("utf-8")
+    try:
+        return json.loads(body_str)
+    except ValueError:
+        raise FulkrumaError(0, "invalid_body", "webhook body is not valid JSON") from None

fulkruma-0.1.0.dist-info/METADATA

@@ -0,0 +1,117 @@
+Metadata-Version: 2.4
+Name: fulkruma
+Version: 0.1.0
+Summary: Official Python SDK for Fulkruma — stock + warehouses + shipping + licenses + deliveries. HMAC-signed requests with full parity to the Node SDK.
+Project-URL: Homepage, https://fulkruma.com
+Project-URL: Source, https://github.com/hachimi-cat/saas-fulkruma/tree/master/sdk/python
+Project-URL: Issues, https://github.com/hachimi-cat/saas-fulkruma/issues
+Author-email: Forjio <hello@fulkruma.com>
+License: MIT
+Keywords: biteship,forjio,fulkruma,licenses,shipping,stock,warehouses
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.27.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# fulkruma (Python)
+
+Official Python SDK for [Fulkruma](https://fulkruma.com) — stock,
+warehouses, shipping, licenses, deliveries. Mirrors the Node SDK
+(`@forjio/fulkruma-node`) API surface 1:1.
+
+## Install
+
+```bash
+pip install fulkruma
+```
+
+## Quickstart
+
+```python
+from fulkruma import FulkrumaClient
+
+client = FulkrumaClient(
+    key_id="AKIAFULK...",
+    secret="sk_...",
+    base_url="https://fulkruma.com",          # default
+)
+
+# Create a warehouse
+wh = client.warehouses.create({"name": "Jakarta DC", "city": "Jakarta"})
+
+# Adjust stock
+client.stock.adjust({
+    "variantId": "var_1",
+    "warehouseId": wh["warehouse"]["id"],
+    "delta": 50,
+    "reason": "initial_stock",
+})
+
+# List shipments
+shipments = client.shipments.list(status="in_transit")
+```
+
+## Platform-admin scope
+
+Keys with the `fulkruma:platform:admin` scope can operate against any
+merchant via the `X-Fulkruma-On-Behalf-Of` header. Either pass it on the
+client:
+
+```python
+admin = FulkrumaClient(key_id="...", secret="...", on_behalf_of="acc_merchant")
+```
+
+…or scope a single call:
+
+```python
+client.shipments.list(on_behalf_of="acc_merchant")
+```
+
+`for_merchant(account_id)` returns a cloned client locked to one merchant.
+
+## Webhook verification
+
+```python
+from fulkruma import verify_webhook
+
+# Flask
+@app.post("/webhooks/fulkruma")
+def hook():
+    raw = request.get_data()  # bytes — verify the raw body, NOT parsed JSON
+    sig = request.headers.get("Fulkruma-Signature", "")
+    event = verify_webhook(raw_body=raw, signature=sig, secret=os.environ["WHSEC"])
+    # event["type"], event["data"], etc.
+    return "", 204
+```
+
+## Resource namespaces
+
+| Namespace | Methods |
+|---|---|
+| `products` | `create`, `get`, `list`, `update`, `archive`, `add_variant`, `update_variant`, `archive_variant` |
+| `warehouses` | `create`, `list`, `update`, `archive` |
+| `stock` | `levels`, `movements`, `reservations`, `adjust` |
+| `addresses` | `list`, `create`, `delete` |
+| `shipments` | `list`, `get`, `create` |
+| `shipping` | `couriers`, `origin`, `set_origin`, `rates` |
+| `licenses` | `list`, `issue`, `revoke`, `activate`, `deactivate`, `validate` |
+| `deliveries` | `list`, `get`, `create` |
+| `api_keys` | `list`, `create`, `revoke` |
+| `audit_log` | `list` |
+| `billing` | `plans`, `current_plan`, `subscription`, `usage`, `invoices`, `checkout`, `cancel` |
+| `integrations` | `status` |
+| `stats` | `overview` |
+| `webhooks` | `list_endpoints`, `create_endpoint`, `update_endpoint`, `delete_endpoint`, `list_events` |
+| `admin` | `provision_workspace`, `get_workspace`, `partner_usage` |
+
+## License
+
+MIT

fulkruma-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+fulkruma/__init__.py,sha256=Guxw2mV-CqMCK8-60aviAH4me-mustCiK5wl7j7Ts_8,457
+fulkruma/client.py,sha256=oFI22gnppq02yl37yVhAYhqW0-FIVNiZ9K7IOE7aO_A,8083
+fulkruma/errors.py,sha256=WDRtb-Eswr-gu9TVFkDdJ0eWJETj0-SWxCfAVwBeXRo,901
+fulkruma/resources.py,sha256=Za7BPszBoUTekkkiwchBnwf1dJbXpfTwXvES3jrppfA,13967
+fulkruma/webhooks.py,sha256=B0LXIOAi-7BPKoksKbvZjQ7heCMmSLOnk4czhYwTQkU,3405
+fulkruma-0.1.0.dist-info/METADATA,sha256=074i602FgnYPKoKIRFMtrk4kj2JFZ7WIyr05UoNbIO4,3601
+fulkruma-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+fulkruma-0.1.0.dist-info/RECORD,,

fulkruma-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any