checkoutmain-inventory-api 1.0.0__py3-none-any.whl

checkoutmain_inventory/__init__.py

@@ -0,0 +1,202 @@
+"""CheckoutMain Inventory API client (Python, standard library only).
+
+    from checkoutmain_inventory import InventoryApi
+    api = InventoryApi(key=os.environ["LC_KEY"])
+    for item in api.items(updated_after=since):
+        upsert(item)
+
+Retries 429/503 honouring Retry-After with jitter, pages through cursors,
+sends API-Version when pinned, and raises InventoryApiError with the error
+code, doc link and request id from the body.
+"""
+
+from __future__ import annotations
+
+import json
+import random
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from dataclasses import dataclass
+from typing import Any, Callable, Dict, Iterator, List, Optional
+
+__all__ = ["InventoryApi", "InventoryApiError", "LIVE_BASE_URL"]
+
+LIVE_BASE_URL = "https://api.liquidculture.checkoutmain.co/v1"
+USER_AGENT = "checkoutmain-inventory-api-py/1.0"
+
+
+class InventoryApiError(Exception):
+    """An error body from the API: code, message, doc link, request id."""
+
+    def __init__(
+        self,
+        status: int,
+        code: str,
+        message: str,
+        doc: Optional[str] = None,
+        request_id: Optional[str] = None,
+        retry_after: Optional[int] = None,
+        param: Optional[str] = None,
+        scope: Optional[str] = None,
+    ) -> None:
+        super().__init__(f"{code} ({status}): {message}")
+        self.status = status
+        self.code = code
+        self.message = message
+        self.doc = doc
+        self.request_id = request_id
+        self.retry_after = retry_after
+        self.param = param
+        self.scope = scope
+
+
+@dataclass
+class _Response:
+    status: int
+    headers: Dict[str, str]
+    text: str
+
+
+# A transport is (method, url, headers, body) -> _Response; the default uses urllib.
+Transport = Callable[[str, str, Dict[str, str], Optional[bytes]], _Response]
+
+
+def _urllib_transport(method: str, url: str, headers: Dict[str, str], body: Optional[bytes]) -> _Response:
+    req = urllib.request.Request(url, data=body, method=method, headers=headers)
+    try:
+        with urllib.request.urlopen(req, timeout=30) as res:  # noqa: S310 (https only by contract)
+            return _Response(res.status, {k.lower(): v for k, v in res.headers.items()}, res.read().decode("utf-8"))
+    except urllib.error.HTTPError as e:
+        return _Response(e.code, {k.lower(): v for k, v in e.headers.items()}, e.read().decode("utf-8"))
+
+
+class InventoryApi:
+    def __init__(
+        self,
+        key: str,
+        base_url: str = LIVE_BASE_URL,
+        api_version: Optional[str] = None,
+        store: Optional[str] = None,
+        max_retries: int = 4,
+        transport: Optional[Transport] = None,
+        sleep: Callable[[float], None] = time.sleep,
+    ) -> None:
+        if not key:
+            raise ValueError("key is required")
+        self.key = key
+        self.base_url = base_url.rstrip("/")
+        self.api_version = api_version
+        self.store_id = store
+        self.max_retries = max_retries
+        self._transport = transport or _urllib_transport
+        self._sleep = sleep
+
+    # ── transport ──
+
+    def request(self, method: str, path: str, query: Optional[Dict[str, Any]] = None, body: Any = None) -> Any:
+        q = {k: v for k, v in (query or {}).items() if v is not None and v != ""}
+        if self.store_id and "store" not in q:
+            q["store"] = self.store_id
+        for k, v in list(q.items()):
+            if isinstance(v, (list, tuple)):
+                q[k] = ",".join(str(x) for x in v)
+            elif isinstance(v, bool):
+                q[k] = "true" if v else "false"
+        url = f"{self.base_url}{path}"
+        if q:
+            url += "?" + urllib.parse.urlencode(q)
+        headers = {
+            "Authorization": f"Bearer {self.key}",
+            "Accept": "application/json",
+            "User-Agent": USER_AGENT,
+        }
+        if self.api_version:
+            headers["API-Version"] = self.api_version
+        data = None
+        if body is not None:
+            headers["Content-Type"] = "application/json"
+            data = json.dumps(body).encode("utf-8")
+        attempt = 0
+        while True:
+            res = self._transport(method, url, headers, data)
+            if 200 <= res.status < 300 or res.status == 304:
+                return json.loads(res.text) if res.text else None
+            err: Dict[str, Any] = {}
+            try:
+                err = json.loads(res.text).get("error", {}) or {}
+            except (ValueError, AttributeError):
+                err = {}
+            retry_after = res.headers.get("retry-after") or err.get("retry_after")
+            try:
+                retry_after_s: Optional[int] = int(retry_after) if retry_after is not None else None
+            except ValueError:
+                retry_after_s = None
+            if res.status in (429, 503) and attempt < self.max_retries:
+                attempt += 1
+                base = retry_after_s if retry_after_s is not None else 2**attempt
+                self._sleep(base + random.random() * 0.25)
+                continue
+            raise InventoryApiError(
+                res.status,
+                err.get("code", "http_error"),
+                err.get("message", f"HTTP {res.status}"),
+                err.get("doc"),
+                err.get("request_id") or res.headers.get("x-request-id"),
+                retry_after_s,
+                err.get("param"),
+                err.get("scope"),
+            )
+
+    def _walk(self, path: str, query: Optional[Dict[str, Any]] = None) -> Iterator[Dict[str, Any]]:
+        q = dict(query or {})
+        while True:
+            page = self.request("GET", path, q)
+            for row in page["data"]:
+                yield row
+            if not page.get("has_more") or not page.get("cursor"):
+                return
+            q["cursor"] = page["cursor"]
+
+    # ── endpoints ──
+
+    def store(self) -> Dict[str, Any]:
+        return self.request("GET", "/store")["data"]
+
+    def stores(self) -> List[Dict[str, Any]]:
+        return self.request("GET", "/stores")["data"]
+
+    def items_page(self, **query: Any) -> Dict[str, Any]:
+        return self.request("GET", "/catalog/items", query)
+
+    def items(self, **query: Any) -> Iterator[Dict[str, Any]]:
+        return self._walk("/catalog/items", query)
+
+    def item(self, guid: str) -> Dict[str, Any]:
+        return self.request("GET", f"/catalog/items/{urllib.parse.quote(guid, safe='')}")["data"]
+
+    def categories(self) -> List[Dict[str, Any]]:
+        return self.request("GET", "/catalog/categories")["data"]
+
+    def counts(self, **query: Any) -> Iterator[Dict[str, Any]]:
+        return self._walk("/inventory/counts", query)
+
+    def changes(self, **query: Any) -> Iterator[Dict[str, Any]]:
+        return self._walk("/inventory/changes", query)
+
+    def search(self, **body: Any) -> Dict[str, Any]:
+        return self.request("POST", "/catalog/search", None, body)
+
+    def export_catalog(self, fmt: str = "csv") -> str:
+        url = f"{self.base_url}/exports/catalog?" + urllib.parse.urlencode(
+            {k: v for k, v in {"format": fmt, "store": self.store_id}.items() if v}
+        )
+        res = self._transport("GET", url, {"Authorization": f"Bearer {self.key}", "User-Agent": USER_AGENT}, None)
+        if res.status != 200:
+            try:
+                err = json.loads(res.text).get("error", {}) or {}
+            except ValueError:
+                err = {}
+            raise InventoryApiError(res.status, err.get("code", "http_error"), err.get("message", f"HTTP {res.status}"), err.get("doc"), err.get("request_id"))
+        return res.text

checkoutmain_inventory_api-1.0.0.dist-info/METADATA

@@ -0,0 +1,23 @@
+Metadata-Version: 2.4
+Name: checkoutmain-inventory-api
+Version: 1.0.0
+Summary: Client for the CheckoutMain Inventory API (LiquidCulture POS, High Spirits POS)
+License: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# checkoutmain-inventory-api
+
+Standard-library client for the CheckoutMain Inventory API: retries 429/503
+honouring `Retry-After`, pages through cursors, pins `API-Version`, and raises
+`InventoryApiError` with the error code, doc link and request id.
+
+```python
+from checkoutmain_inventory import InventoryApi
+
+api = InventoryApi(key=os.environ["LC_KEY"])
+for item in api.items(updated_after="2026-10-15T00:00:00Z"):
+    upsert(item)
+```
+
+Docs: https://checkoutmain.co/developers/liquidculture

checkoutmain_inventory_api-1.0.0.dist-info/RECORD

@@ -0,0 +1,5 @@
+checkoutmain_inventory/__init__.py,sha256=sBDfMSWrNhY08FQwuNvYq3q3BDEYF1GgCT4cb_wgGtY,7603
+checkoutmain_inventory_api-1.0.0.dist-info/METADATA,sha256=ZlUGySdzIAnSWLqZSZti998cWyyYutPYaQEpN7HVSeQ,730
+checkoutmain_inventory_api-1.0.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+checkoutmain_inventory_api-1.0.0.dist-info/top_level.txt,sha256=jXWHzV6zU2vAOCFa2iM6b3DM_HddKPaT4t9HIAOp_o8,23
+checkoutmain_inventory_api-1.0.0.dist-info/RECORD,,

checkoutmain_inventory_api-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

checkoutmain_inventory_api-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+checkoutmain_inventory