linkbridge 0.1.0__py3-none-any.whl

linkbridge/__init__.py

@@ -0,0 +1,25 @@
+"""Linkbridge Python SDK — public surface.
+
+Stable imports for downstream callers; everything else is implementation
+detail and may change without a major version bump.
+"""
+
+from .client import LinkbridgeClient, SDK_VERSION
+from .errors import APIError, SignatureError
+from .webhook import (
+    MAX_WEBHOOK_SKEW_SECONDS,
+    SIGNATURE_HEADER,
+    verify_webhook,
+)
+
+__all__ = [
+    "LinkbridgeClient",
+    "APIError",
+    "SignatureError",
+    "verify_webhook",
+    "SIGNATURE_HEADER",
+    "MAX_WEBHOOK_SKEW_SECONDS",
+    "SDK_VERSION",
+]
+
+__version__ = SDK_VERSION

linkbridge/client.py

@@ -0,0 +1,322 @@
+"""LinkbridgeClient — the SDK entry point.
+
+Design notes
+------------
+
+* Stdlib-only HTTP via ``urllib.request``. We deliberately avoid the
+  ``requests``/``httpx`` dependency so the package installs cleanly
+  into AWS Lambda layers and air-gapped POS firmware.
+* OAuth2 client-credentials flow with lazy, thread-safe token refresh.
+  Tokens are refreshed 60 seconds before expiry; concurrent callers
+  block on a single in-flight refresh via a threading.Lock.
+* Mirrors the resource grouping of the Node and Go SDKs:
+  ``client.invoices.{submit, get, list, transmit, update_status}``,
+  ``client.webhooks.{create, list, delete}``, ``client.lookups.*``.
+* The ``transport`` constructor argument lets tests inject a fake
+  request handler (see ``tests/test_client.py``).
+"""
+
+from __future__ import annotations
+
+import json
+import secrets
+import threading
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any, Callable, Dict, Iterable, Mapping, Optional, Tuple
+
+from .errors import APIError
+
+SDK_VERSION = "0.1.0"
+
+# A Transport is a pluggable HTTP function. Returning the tuple
+# (status, headers, body_bytes) keeps the interface trivially mockable.
+Transport = Callable[[str, str, Mapping[str, str], Optional[bytes]], Tuple[int, Mapping[str, str], bytes]]
+
+
+def _stdlib_transport(
+    method: str,
+    url: str,
+    headers: Mapping[str, str],
+    body: Optional[bytes],
+) -> Tuple[int, Mapping[str, str], bytes]:
+    """Default transport built on urllib. Captures error responses so
+    callers (and ``APIError.from_response``) can decode the body even
+    on 4xx/5xx — urllib normally treats those as exceptions."""
+    req = urllib.request.Request(url, data=body, method=method, headers=dict(headers))
+    try:
+        with urllib.request.urlopen(req, timeout=30) as resp:  # noqa: S310 — trusted scheme
+            return resp.status, dict(resp.headers), resp.read()
+    except urllib.error.HTTPError as exc:
+        return exc.code, dict(exc.headers or {}), exc.read()
+
+
+class LinkbridgeClient:
+    """Synchronous Linkbridge API client."""
+
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        client_id: Optional[str] = None,
+        client_secret: Optional[str] = None,
+        static_token: Optional[str] = None,
+        scopes: Optional[Iterable[str]] = None,
+        user_agent: Optional[str] = None,
+        transport: Optional[Transport] = None,
+    ) -> None:
+        if not base_url:
+            raise ValueError("linkbridge: base_url is required")
+        if not static_token and not (client_id and client_secret):
+            raise ValueError(
+                "linkbridge: either static_token or client_id+client_secret is required"
+            )
+
+        self._base_url = base_url.rstrip("/")
+        self._client_id = client_id
+        self._client_secret = client_secret
+        self._static_token = static_token
+        self._scopes = list(scopes) if scopes else ["invoices:write", "invoices:read"]
+        self._user_agent_suffix = user_agent or ""
+        self._transport: Transport = transport or _stdlib_transport
+
+        self._token_cache: Optional[Tuple[str, float]] = None  # (token, expires_at_epoch)
+        self._token_lock = threading.Lock()
+
+        self.invoices = InvoicesAPI(self)
+        self.webhooks = WebhooksAPI(self)
+        self.lookups = LookupsAPI(self)
+
+    # ----- public helpers -------------------------------------------------
+
+    @staticmethod
+    def idempotency_key() -> str:
+        """Return a fresh URL-safe Idempotency-Key (32 hex chars + prefix)."""
+        return "lb-" + secrets.token_hex(16)
+
+    def user_agent(self) -> str:
+        base = f"linkbridge-python/{SDK_VERSION}"
+        return f"{base} {self._user_agent_suffix}".rstrip()
+
+    # ----- token management ----------------------------------------------
+
+    def _token(self) -> str:
+        if self._static_token:
+            return self._static_token
+        with self._token_lock:
+            if self._token_cache and self._token_cache[1] - time.time() > 60:
+                return self._token_cache[0]
+            self._refresh_token_locked()
+            assert self._token_cache is not None
+            return self._token_cache[0]
+
+    def _refresh_token_locked(self) -> None:
+        body = json.dumps(
+            {
+                "client_id": self._client_id,
+                "client_secret": self._client_secret,
+                "grant_type": "client_credentials",
+                "scope": " ".join(self._scopes),
+            }
+        ).encode("utf-8")
+        status, _headers, raw = self._transport(
+            "POST",
+            f"{self._base_url}/v1/oauth/token",
+            {
+                "content-type": "application/json",
+                "accept": "application/json",
+                "user-agent": self.user_agent(),
+            },
+            body,
+        )
+        if status // 100 != 2:
+            raise APIError.from_response(status, raw)
+        try:
+            decoded = json.loads(raw)
+        except ValueError as exc:
+            raise APIError(
+                status=status,
+                code="invalid_token_response",
+                message="non-JSON token response",
+                raw=raw,
+            ) from exc
+        token = decoded.get("access_token")
+        ttl = int(decoded.get("expires_in") or 300)
+        if not token:
+            raise APIError(
+                status=status,
+                code="invalid_token_response",
+                message="empty access_token",
+                raw=raw,
+            )
+        self._token_cache = (token, time.time() + ttl)
+
+    # ----- request plumbing ----------------------------------------------
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        query: Optional[Mapping[str, Any]] = None,
+        body: Any = None,
+        extra_headers: Optional[Mapping[str, str]] = None,
+        expect_json: bool = True,
+    ) -> Any:
+        """Authenticated request. Returns the decoded JSON body on
+        2xx (or ``None`` for 204 / empty bodies). Raises :class:`APIError`
+        otherwise."""
+        url = self._base_url + path
+        if query:
+            cleaned = {k: str(v) for k, v in query.items() if v is not None and v != ""}
+            if cleaned:
+                url = f"{url}?{urllib.parse.urlencode(cleaned)}"
+
+        headers: Dict[str, str] = {
+            "authorization": "Bearer " + self._token(),
+            "accept": "application/json",
+            "user-agent": self.user_agent(),
+        }
+        raw_body: Optional[bytes] = None
+        if body is not None:
+            headers["content-type"] = "application/json"
+            raw_body = json.dumps(body).encode("utf-8")
+        if extra_headers:
+            for k, v in extra_headers.items():
+                headers[k.lower()] = v
+
+        status, _resp_headers, payload = self._transport(method, url, headers, raw_body)
+        if status // 100 != 2:
+            raise APIError.from_response(status, payload)
+        if not expect_json or status == 204 or not payload:
+            return None
+        try:
+            return json.loads(payload)
+        except ValueError as exc:
+            raise APIError(
+                status=status,
+                code="invalid_json_response",
+                message="server returned non-JSON body",
+                raw=payload,
+            ) from exc
+
+
+# ---------------------------------------------------------------------------
+# Resource handles. Each one is a thin facade over LinkbridgeClient.request
+# so callers get IDE-friendly grouping (`client.invoices.submit(...)`).
+# ---------------------------------------------------------------------------
+
+
+class InvoicesAPI:
+    def __init__(self, client: LinkbridgeClient) -> None:
+        self._c = client
+
+    def submit(
+        self,
+        invoice: Mapping[str, Any],
+        *,
+        idempotency_key: Optional[str] = None,
+        mode: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """POST /v1/invoices. Returns the InvoiceAccepted envelope."""
+        headers = {
+            "idempotency-key": idempotency_key or LinkbridgeClient.idempotency_key(),
+        }
+        return self._c.request(
+            "POST",
+            "/v1/invoices",
+            query={"mode": mode} if mode else None,
+            body=invoice,
+            extra_headers=headers,
+        )
+
+    def get(self, irn: str) -> Dict[str, Any]:
+        """GET /v1/invoices/{irn}."""
+        return self._c.request("GET", f"/v1/invoices/{urllib.parse.quote(irn, safe='')}")
+
+    def list(
+        self,
+        *,
+        cursor: Optional[str] = None,
+        limit: Optional[int] = None,
+        status: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """GET /v1/invoices. Returns ``{"data": [...], "next_cursor": ...}``."""
+        return self._c.request(
+            "GET",
+            "/v1/invoices",
+            query={"cursor": cursor, "limit": limit, "status": status},
+        )
+
+    def transmit(self, irn: str) -> Dict[str, Any]:
+        """POST /v1/invoices/{irn}/transmit — re-queue for transmission."""
+        return self._c.request(
+            "POST", f"/v1/invoices/{urllib.parse.quote(irn, safe='')}/transmit"
+        )
+
+    def update_status(
+        self,
+        irn: str,
+        *,
+        payment_status: str,
+        reference: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """POST /v1/invoices/{irn}/status — record a payment-state change."""
+        body: Dict[str, Any] = {"payment_status": payment_status}
+        if reference is not None:
+            body["reference"] = reference
+        return self._c.request(
+            "POST",
+            f"/v1/invoices/{urllib.parse.quote(irn, safe='')}/status",
+            body=body,
+        )
+
+
+class WebhooksAPI:
+    def __init__(self, client: LinkbridgeClient) -> None:
+        self._c = client
+
+    def create(
+        self,
+        *,
+        url: str,
+        events: Iterable[str],
+        description: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """POST /v1/webhooks. The plaintext ``secret`` is returned on
+        the response and never again — store it securely."""
+        body: Dict[str, Any] = {"url": url, "events": list(events)}
+        if description is not None:
+            body["description"] = description
+        return self._c.request("POST", "/v1/webhooks", body=body)
+
+    def list(self) -> Dict[str, Any]:
+        """GET /v1/webhooks."""
+        return self._c.request("GET", "/v1/webhooks")
+
+    def delete(self, webhook_id: str) -> None:
+        """DELETE /v1/webhooks/{id}."""
+        self._c.request(
+            "DELETE",
+            f"/v1/webhooks/{urllib.parse.quote(webhook_id, safe='')}",
+            expect_json=False,
+        )
+
+
+class LookupsAPI:
+    def __init__(self, client: LinkbridgeClient) -> None:
+        self._c = client
+
+    def tax_codes(self) -> Dict[str, Any]:
+        """GET /v1/lookups/tax-codes."""
+        return self._c.request("GET", "/v1/lookups/tax-codes")
+
+    def hsn_codes(self, *, limit: Optional[int] = None, cursor: Optional[str] = None) -> Dict[str, Any]:
+        """GET /v1/lookups/hsn-codes (paginated)."""
+        return self._c.request(
+            "GET",
+            "/v1/lookups/hsn-codes",
+            query={"limit": limit, "cursor": cursor},
+        )

linkbridge/errors.py

@@ -0,0 +1,66 @@
+"""Error types for the Linkbridge Python SDK.
+
+The API always returns a `{"error": {"code", "message", "trace_id"}}`
+envelope on failure. We surface those fields verbatim on `APIError` so
+callers can switch on the canonical code without parsing the message.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Mapping, Optional
+
+
+class APIError(Exception):
+    """Raised for any non-2xx HTTP response from the Linkbridge API."""
+
+    def __init__(
+        self,
+        *,
+        status: int,
+        code: str,
+        message: str,
+        trace_id: Optional[str] = None,
+        details: Optional[Any] = None,
+        raw: Optional[bytes] = None,
+    ) -> None:
+        super().__init__(f"linkbridge: {status} {code}: {message}")
+        self.status = status
+        self.code = code
+        self.message = message
+        self.trace_id = trace_id
+        self.details = details
+        self.raw = raw
+
+    @classmethod
+    def from_response(cls, status: int, body: bytes) -> "APIError":
+        """Best-effort decoder. Falls back to opaque codes when the
+        response is not the canonical error envelope (e.g. a 502 from a
+        load balancer that has no idea what an APIError looks like)."""
+        code = "http_error"
+        message = body.decode("utf-8", errors="replace")[:500] or f"http {status}"
+        trace_id: Optional[str] = None
+        details: Any = None
+        try:
+            decoded = json.loads(body)
+        except (ValueError, UnicodeDecodeError):
+            decoded = None
+        if isinstance(decoded, Mapping):
+            err = decoded.get("error")
+            if isinstance(err, Mapping):
+                code = str(err.get("code") or code)
+                message = str(err.get("message") or message)
+                trace_id = err.get("trace_id")
+                details = err.get("details")
+        return cls(
+            status=status,
+            code=code,
+            message=message,
+            trace_id=trace_id,
+            details=details,
+            raw=body,
+        )
+
+
+class SignatureError(Exception):
+    """Raised by ``verify_webhook`` when a delivery cannot be trusted."""

linkbridge/webhook.py

@@ -0,0 +1,97 @@
+"""HMAC-SHA256 verification for Linkbridge webhook deliveries.
+
+Spec contract (see openapi.yaml §security and ADR-0006):
+
+    X-Linkbridge-Signature: t=<unix>,v1=<hex>
+    v1 = hex(HMAC-SHA256(secret, f"{t}.{body}"))
+
+The receiver MUST reject deliveries whose timestamp falls outside a
+5-minute window to bound replay-attack horizons. We mirror the same
+constant-time comparison logic the API server uses.
+"""
+
+from __future__ import annotations
+
+import hmac
+import time
+from hashlib import sha256
+from typing import Optional
+
+from .errors import SignatureError
+
+SIGNATURE_HEADER = "X-Linkbridge-Signature"
+MAX_WEBHOOK_SKEW_SECONDS = 5 * 60
+
+
+def verify_webhook(
+    *,
+    secret: bytes,
+    body: bytes,
+    header: str,
+    now: Optional[float] = None,
+) -> None:
+    """Verify a webhook signature. Raises ``SignatureError`` on any
+    failure mode (missing/malformed header, replay-window violation,
+    signature mismatch). Returns ``None`` on success.
+
+    Parameters
+    ----------
+    secret:
+        The raw webhook secret bytes returned by ``POST /v1/webhooks``.
+        Do NOT pass the secret as ``str`` — Python would otherwise
+        encode it implicitly with the platform's default encoding.
+    body:
+        The exact request body bytes as read off the wire. JSON
+        re-serialisation will alter byte ordering and break verification.
+    header:
+        The raw value of the ``X-Linkbridge-Signature`` header.
+    now:
+        Override the current time (epoch seconds). Production code
+        should leave this as ``None`` so we use ``time.time()``.
+    """
+    if not header:
+        raise SignatureError("missing X-Linkbridge-Signature")
+    if not isinstance(secret, (bytes, bytearray)):
+        raise TypeError("secret must be bytes; pass secret.encode() if it's a str")
+    if not isinstance(body, (bytes, bytearray)):
+        raise TypeError("body must be bytes; do not pre-decode the request body")
+
+    t, sig = _parse_header(header)
+    current = time.time() if now is None else now
+    if abs(current - t) > MAX_WEBHOOK_SKEW_SECONDS:
+        raise SignatureError("signature timestamp outside replay window")
+
+    expected = hmac.new(secret, f"{t}.".encode("ascii"), sha256)
+    expected.update(body)
+    expected_hex = expected.hexdigest()
+    # hmac.compare_digest is constant-time; explicit lower() avoids
+    # accidentally rejecting a server that uppercased the hex.
+    if not hmac.compare_digest(expected_hex, sig.lower()):
+        raise SignatureError("signature mismatch")
+
+
+def _parse_header(header: str) -> tuple[int, str]:
+    """Parse ``t=<unix>,v1=<hex>`` into ``(timestamp_int, hex_str)``.
+
+    Raises ``SignatureError`` for any structural problem.
+    """
+    t: Optional[int] = None
+    sig: Optional[str] = None
+    for part in header.split(","):
+        kv = part.strip().split("=", 1)
+        if len(kv) != 2:
+            raise SignatureError("malformed signature header")
+        key, value = kv[0], kv[1]
+        if key == "t":
+            try:
+                t = int(value)
+            except ValueError as exc:
+                raise SignatureError("malformed signature timestamp") from exc
+            if t <= 0:
+                raise SignatureError("malformed signature timestamp")
+        elif key == "v1":
+            sig = value
+        # Unknown keys are tolerated for forward-compat (e.g. v2=).
+    if t is None or not sig:
+        raise SignatureError("malformed signature header")
+    return t, sig

linkbridge-0.1.0.dist-info/METADATA

@@ -0,0 +1,103 @@
+Metadata-Version: 2.4
+Name: linkbridge
+Version: 0.1.0
+Summary: Official Python SDK for the Linkbridge e-invoicing API
+Author: Linkbridge
+License: Apache-2.0
+Project-URL: Homepage, https://docs.linkbridge.ng
+Project-URL: Documentation, https://docs.linkbridge.ng
+Project-URL: Source, https://github.com/Linkbridge-Systems/linkbridge-sdks/tree/main/sdk-python
+Project-URL: Issues, https://github.com/Linkbridge-Systems/linkbridge-sdks/issues
+Keywords: linkbridge,e-invoicing,nrs,fbr,fiscalisation
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Office/Business :: Financial
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Requires-Dist: pytest-cov>=4; extra == "test"
+
+# linkbridge (Python SDK)
+
+Official Python client for the [Linkbridge](https://linkbridge.ng)
+e-invoicing API. Mirrors the surface of the [Go](../sdk-go) and
+[Node](../sdk-node) SDKs against the same OpenAPI contract
+(`tools/openapi/openapi.yaml`).
+
+* **Zero runtime dependencies** — uses only the Python standard library
+  so the package drops cleanly into Lambda layers, vendored POS
+  firmware, and air-gapped merchant ERPs.
+* **Sync API** with explicit OAuth2 client-credentials handling and
+  automatic token refresh.
+* **Webhook signature verification** with constant-time comparison and
+  the same 5-minute clock-skew window enforced server-side.
+
+## Install
+
+```bash
+pip install linkbridge
+```
+
+Requires Python 3.9 or newer.
+
+## Quickstart
+
+```python
+from linkbridge import LinkbridgeClient
+
+client = LinkbridgeClient(
+    base_url="https://api.linkbridge.ng",
+    client_id="your-client-id",
+    client_secret="your-client-secret",
+    scopes=["invoices:write", "invoices:read"],
+)
+
+accepted = client.invoices.submit({
+    "irn": "INV001-SVC01-20260601",
+    "invoice_kind": "Standard",
+    # …rest of the canonical NRS payload — see
+    # packages/schema/invoice.schema.json
+})
+print(accepted["irn"], accepted["status"])
+
+# Read back, paginate, retry, mutate payment status:
+record   = client.invoices.get(accepted["irn"])
+page     = client.invoices.list(limit=20, status="failed")
+requeued = client.invoices.transmit(accepted["irn"])
+paid     = client.invoices.update_status(accepted["irn"],
+              payment_status="PAID", reference="RCPT-001")
+```
+
+## Webhook verification
+
+```python
+from linkbridge import verify_webhook, SignatureError
+
+@app.post("/hooks/linkbridge")
+def hook(request):
+    try:
+        verify_webhook(
+            secret=os.environ["WEBHOOK_SECRET"].encode(),
+            body=request.body,                     # raw bytes off the wire
+            header=request.headers["X-Linkbridge-Signature"],
+        )
+    except SignatureError:
+        return 401
+    # …handle the event
+```
+
+## Errors
+
+All non-2xx responses raise `linkbridge.APIError`, which exposes the
+HTTP status, the canonical `error.code`, the human `error.message`, and
+the `trace_id` so that operators can correlate against server logs.
+
+## Versioning
+
+The package follows the same `0.MINOR.PATCH` cadence as the API surface
+during the beta. Breaking changes will be confined to MINOR bumps until
+the API freezes at `1.0.0`.

linkbridge-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+linkbridge/__init__.py,sha256=lw8ZIos96eouCrAZ2qZRo3WcJgfJwIOayaqn8SSs4sw,569
+linkbridge/client.py,sha256=91pJ5602Ww3ZWm_4g4PiKDbC6lv1lcmCQ-gsdq6z4wI,11326
+linkbridge/errors.py,sha256=7h65rWbhJfS6kZIdfv0SBExek_dO5ygKdkkqB2R4vvE,2161
+linkbridge/webhook.py,sha256=7jv66umJJaaZQuMmlghRsbpKieCNDLRWJhZmUcjTMXI,3466
+linkbridge-0.1.0.dist-info/METADATA,sha256=WuBKXIUPDvw1OGjPmUgnSqzIArbcRnW4g3Dq2L4WMb8,3409
+linkbridge-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+linkbridge-0.1.0.dist-info/top_level.txt,sha256=ouOG4YXK5s5ePtI7mN8gRsY6YC5JEFpC8pyKu4Nq3as,11
+linkbridge-0.1.0.dist-info/RECORD,,

linkbridge-0.1.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
+

linkbridge-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+linkbridge