linkbridge 0.1.0__tar.gz

linkbridge-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,80 @@
+# 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/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-0.1.0/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-0.1.0/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-0.1.0/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/linkbridge.egg-info/PKG-INFO

@@ -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/linkbridge.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+README.md
+pyproject.toml
+linkbridge/__init__.py
+linkbridge/client.py
+linkbridge/errors.py
+linkbridge/webhook.py
+linkbridge.egg-info/PKG-INFO
+linkbridge.egg-info/SOURCES.txt
+linkbridge.egg-info/dependency_links.txt
+linkbridge.egg-info/requires.txt
+linkbridge.egg-info/top_level.txt
+tests/test_client.py
+tests/test_webhook.py

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

@@ -0,0 +1 @@
+

linkbridge-0.1.0/linkbridge.egg-info/requires.txt

@@ -0,0 +1,4 @@
+
+[test]
+pytest>=7
+pytest-cov>=4

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

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

linkbridge-0.1.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "linkbridge"
+version = "0.1.0"
+description = "Official Python SDK for the Linkbridge e-invoicing API"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "Apache-2.0" }
+authors = [{ name = "Linkbridge" }]
+keywords = ["linkbridge", "e-invoicing", "nrs", "fbr", "fiscalisation"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: Apache Software License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Topic :: Office/Business :: Financial",
+]
+# Zero runtime dependencies — we deliberately use stdlib (urllib, hmac,
+# json, secrets) so the package installs cleanly into restricted
+# environments (Lambda layers, vendored merchant POS firmware, etc.).
+dependencies = []
+
+[project.optional-dependencies]
+test = ["pytest>=7", "pytest-cov>=4"]
+
+[project.urls]
+Homepage = "https://docs.linkbridge.ng"
+Documentation = "https://docs.linkbridge.ng"
+Source = "https://github.com/Linkbridge-Systems/linkbridge-sdks/tree/main/sdk-python"
+Issues = "https://github.com/Linkbridge-Systems/linkbridge-sdks/issues"
+
+[tool.setuptools.packages.find]
+include = ["linkbridge*"]
+exclude = ["tests*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"

linkbridge-0.1.0/setup.cfg

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

linkbridge-0.1.0/tests/test_client.py

@@ -0,0 +1,269 @@
+"""Unit tests for the Linkbridge Python SDK client.
+
+We rely on the Transport injection point to drive every code path
+hermetically — no real HTTP, no Postgres. The contract is small enough
+(four arguments in, three values out) that tests stay readable.
+"""
+
+from __future__ import annotations
+
+import json
+import threading
+import time
+from typing import Any, List, Mapping, Optional, Tuple
+
+import pytest
+
+from linkbridge import APIError, LinkbridgeClient
+
+
+# --- helpers ---------------------------------------------------------------
+
+
+class FakeTransport:
+    """Records every call and returns canned responses."""
+
+    def __init__(self, responses: List[Tuple[int, Mapping[str, str], bytes]]) -> None:
+        self._responses = list(responses)
+        self.calls: List[Tuple[str, str, Mapping[str, str], Optional[bytes]]] = []
+        self.lock = threading.Lock()
+
+    def __call__(
+        self,
+        method: str,
+        url: str,
+        headers: Mapping[str, str],
+        body: Optional[bytes],
+    ) -> Tuple[int, Mapping[str, str], bytes]:
+        with self.lock:
+            self.calls.append((method, url, dict(headers), body))
+            if not self._responses:
+                raise AssertionError(f"FakeTransport: unexpected call {method} {url}")
+            return self._responses.pop(0)
+
+
+def _ok(body: Any, *, status: int = 200) -> Tuple[int, Mapping[str, str], bytes]:
+    return status, {"content-type": "application/json"}, json.dumps(body).encode()
+
+
+def _err(status: int, code: str, message: str) -> Tuple[int, Mapping[str, str], bytes]:
+    body = {"error": {"code": code, "message": message, "trace_id": "trace-xyz"}}
+    return status, {"content-type": "application/json"}, json.dumps(body).encode()
+
+
+def _new_client(transport: FakeTransport, **overrides: Any) -> LinkbridgeClient:
+    base: dict[str, Any] = {
+        "base_url": "https://api.test",
+        "client_id": "cid",
+        "client_secret": "csecret",
+        "transport": transport,
+    }
+    base.update(overrides)
+    return LinkbridgeClient(**base)
+
+
+# --- construction ----------------------------------------------------------
+
+
+def test_constructor_requires_credentials():
+    with pytest.raises(ValueError):
+        LinkbridgeClient(base_url="https://x")
+
+
+def test_constructor_requires_base_url():
+    with pytest.raises(ValueError):
+        LinkbridgeClient(base_url="", static_token="t")
+
+
+def test_static_token_skips_oauth_dance():
+    transport = FakeTransport([_ok({"data": [], "next_cursor": None})])
+    client = LinkbridgeClient(
+        base_url="https://api.test", static_token="static-bearer", transport=transport
+    )
+    client.invoices.list()
+    method, url, headers, _ = transport.calls[0]
+    assert method == "GET"
+    assert url == "https://api.test/v1/invoices"
+    assert headers["authorization"] == "Bearer static-bearer"
+
+
+# --- token caching ---------------------------------------------------------
+
+
+def test_token_is_fetched_once_and_cached():
+    transport = FakeTransport(
+        [
+            _ok({"access_token": "tok-1", "expires_in": 3600, "token_type": "Bearer"}),
+            _ok({"data": [], "next_cursor": None}),
+            _ok({"data": [], "next_cursor": None}),
+        ]
+    )
+    client = _new_client(transport)
+    client.invoices.list()
+    client.invoices.list()
+    # Only one /v1/oauth/token call despite two list() calls.
+    token_calls = [c for c in transport.calls if c[1].endswith("/v1/oauth/token")]
+    assert len(token_calls) == 1
+
+
+def test_token_refreshes_when_near_expiry(monkeypatch: pytest.MonkeyPatch):
+    transport = FakeTransport(
+        [
+            _ok({"access_token": "tok-1", "expires_in": 30, "token_type": "Bearer"}),
+            _ok({"data": [], "next_cursor": None}),
+            _ok({"access_token": "tok-2", "expires_in": 3600, "token_type": "Bearer"}),
+            _ok({"data": [], "next_cursor": None}),
+        ]
+    )
+    client = _new_client(transport)
+    client.invoices.list()  # first call → fetches tok-1
+    # Advance time well past tok-1's window. expires_in=30 means cache
+    # window is now-60; we cross instantly.
+    base = time.time()
+    monkeypatch.setattr("linkbridge.client.time.time", lambda: base + 120)
+    client.invoices.list()  # should refresh
+    token_calls = [c for c in transport.calls if c[1].endswith("/v1/oauth/token")]
+    assert len(token_calls) == 2
+
+
+# --- error envelopes -------------------------------------------------------
+
+
+def test_api_error_decodes_canonical_envelope():
+    transport = FakeTransport(
+        [
+            _ok({"access_token": "t", "expires_in": 3600}),
+            _err(404, "invoice_not_found", "no invoice with that IRN"),
+        ]
+    )
+    client = _new_client(transport)
+    with pytest.raises(APIError) as excinfo:
+        client.invoices.get("INV-MISSING")
+    assert excinfo.value.status == 404
+    assert excinfo.value.code == "invoice_not_found"
+    assert excinfo.value.trace_id == "trace-xyz"
+
+
+def test_api_error_handles_non_envelope_body():
+    transport = FakeTransport(
+        [
+            _ok({"access_token": "t", "expires_in": 3600}),
+            (502, {}, b"<html>Bad Gateway</html>"),
+        ]
+    )
+    client = _new_client(transport)
+    with pytest.raises(APIError) as excinfo:
+        client.invoices.get("INV-X")
+    assert excinfo.value.status == 502
+    # Falls back to opaque code rather than crashing on the HTML body.
+    assert excinfo.value.code == "http_error"
+
+
+# --- resource calls --------------------------------------------------------
+
+
+def test_invoices_submit_attaches_idempotency_key_and_body():
+    transport = FakeTransport(
+        [
+            _ok({"access_token": "t", "expires_in": 3600}),
+            _ok(
+                {"irn": "INV001", "status": "pending", "tracking_url": "/v1/invoices/INV001"},
+                status=202,
+            ),
+        ]
+    )
+    client = _new_client(transport)
+    out = client.invoices.submit({"irn": "INV001"}, idempotency_key="my-key", mode="async")
+    assert out["irn"] == "INV001"
+
+    method, url, headers, body = transport.calls[1]
+    assert method == "POST"
+    assert url == "https://api.test/v1/invoices?mode=async"
+    assert headers["idempotency-key"] == "my-key"
+    assert headers["content-type"] == "application/json"
+    assert json.loads(body) == {"irn": "INV001"}
+
+
+def test_invoices_submit_generates_idempotency_key_when_omitted():
+    transport = FakeTransport(
+        [
+            _ok({"access_token": "t", "expires_in": 3600}),
+            _ok({"irn": "INV", "status": "pending", "tracking_url": "/v1/invoices/INV"}, status=202),
+        ]
+    )
+    client = _new_client(transport)
+    client.invoices.submit({"irn": "INV"})
+    _, _, headers, _ = transport.calls[1]
+    assert headers["idempotency-key"].startswith("lb-")
+    assert len(headers["idempotency-key"]) == len("lb-") + 32
+
+
+def test_invoices_transmit_targets_correct_path():
+    transport = FakeTransport(
+        [
+            _ok({"access_token": "t", "expires_in": 3600}),
+            _ok({"irn": "INV-X", "status": "failed", "tracking_url": "/v1/invoices/INV-X"}, status=202),
+        ]
+    )
+    client = _new_client(transport)
+    client.invoices.transmit("INV-X")
+    _, url, _, body = transport.calls[1]
+    assert url == "https://api.test/v1/invoices/INV-X/transmit"
+    assert body is None
+
+
+def test_invoices_update_status_serialises_body():
+    transport = FakeTransport(
+        [
+            _ok({"access_token": "t", "expires_in": 3600}),
+            _ok({"irn": "INV-Y", "status": "transmitted"}),
+        ]
+    )
+    client = _new_client(transport)
+    client.invoices.update_status("INV-Y", payment_status="PAID", reference="RCPT-1")
+    _, url, _, body = transport.calls[1]
+    assert url == "https://api.test/v1/invoices/INV-Y/status"
+    assert json.loads(body) == {"payment_status": "PAID", "reference": "RCPT-1"}
+
+
+def test_invoices_list_drops_empty_query_params():
+    transport = FakeTransport(
+        [
+            _ok({"access_token": "t", "expires_in": 3600}),
+            _ok({"data": [], "next_cursor": None}),
+        ]
+    )
+    client = _new_client(transport)
+    client.invoices.list(limit=20)
+    _, url, _, _ = transport.calls[1]
+    # cursor=None and status=None must not appear in the query string.
+    assert url == "https://api.test/v1/invoices?limit=20"
+
+
+def test_webhooks_create_and_delete():
+    transport = FakeTransport(
+        [
+            _ok({"access_token": "t", "expires_in": 3600}),
+            _ok({"id": "wh-1", "url": "https://hook", "events": ["invoice.accepted"]}),
+            (204, {}, b""),
+        ]
+    )
+    client = _new_client(transport)
+    created = client.webhooks.create(url="https://hook", events=["invoice.accepted"])
+    assert created["id"] == "wh-1"
+    assert client.webhooks.delete("wh-1") is None
+    assert transport.calls[-1][0] == "DELETE"
+
+
+def test_user_agent_includes_sdk_version_and_suffix():
+    transport = FakeTransport(
+        [
+            _ok({"access_token": "t", "expires_in": 3600}),
+            _ok({"data": [], "next_cursor": None}),
+        ]
+    )
+    client = _new_client(transport, user_agent="myapp/1.0")
+    client.invoices.list()
+    _, _, headers, _ = transport.calls[1]
+    assert headers["user-agent"].startswith("linkbridge-python/")
+    assert headers["user-agent"].endswith("myapp/1.0")

linkbridge-0.1.0/tests/test_webhook.py

@@ -0,0 +1,98 @@
+"""Tests for the webhook signature verifier.
+
+The vector below is reproduced byte-for-byte against the Go SDK's
+``VerifyWebhook`` (see ``packages/sdk-go/webhook_test.go``) so the two
+implementations stay in lockstep.
+"""
+
+from __future__ import annotations
+
+import hmac
+import time
+from hashlib import sha256
+
+import pytest
+
+from linkbridge import (
+    MAX_WEBHOOK_SKEW_SECONDS,
+    SignatureError,
+    verify_webhook,
+)
+
+
+SECRET = b"shhh-it-is-a-secret"
+BODY = b'{"event":"invoice.accepted","data":{"irn":"INV-1"}}'
+NOW = 1_700_000_000  # fixed reference timestamp
+
+
+def _sign(secret: bytes, body: bytes, t: int) -> str:
+    mac = hmac.new(secret, f"{t}.".encode("ascii"), sha256)
+    mac.update(body)
+    return f"t={t},v1={mac.hexdigest()}"
+
+
+def test_accepts_well_formed_signature():
+    header = _sign(SECRET, BODY, NOW)
+    verify_webhook(secret=SECRET, body=BODY, header=header, now=NOW)
+
+
+def test_rejects_missing_header():
+    with pytest.raises(SignatureError, match="missing"):
+        verify_webhook(secret=SECRET, body=BODY, header="", now=NOW)
+
+
+def test_rejects_malformed_header():
+    with pytest.raises(SignatureError, match="malformed"):
+        verify_webhook(secret=SECRET, body=BODY, header="garbage", now=NOW)
+
+
+def test_rejects_negative_timestamp():
+    with pytest.raises(SignatureError, match="malformed"):
+        verify_webhook(secret=SECRET, body=BODY, header="t=-1,v1=abc", now=NOW)
+
+
+def test_rejects_replay_outside_window():
+    header = _sign(SECRET, BODY, NOW)
+    skewed = NOW + MAX_WEBHOOK_SKEW_SECONDS + 1
+    with pytest.raises(SignatureError, match="replay"):
+        verify_webhook(secret=SECRET, body=BODY, header=header, now=skewed)
+
+
+def test_rejects_signature_mismatch():
+    header = _sign(b"different-secret", BODY, NOW)
+    with pytest.raises(SignatureError, match="mismatch"):
+        verify_webhook(secret=SECRET, body=BODY, header=header, now=NOW)
+
+
+def test_tolerates_unknown_keys_for_forward_compat():
+    # The verifier must ignore unknown k=v pairs (e.g. v2= once we add
+    # an algorithm bump) so that future signers stay backward-compatible
+    # with deployed receivers.
+    header = _sign(SECRET, BODY, NOW) + ",v2=ignored"
+    verify_webhook(secret=SECRET, body=BODY, header=header, now=NOW)
+
+
+def test_uppercased_hex_is_accepted():
+    header = _sign(SECRET, BODY, NOW)
+    parts = dict(p.split("=", 1) for p in header.split(","))
+    upper_header = f"t={parts['t']},v1={parts['v1'].upper()}"
+    verify_webhook(secret=SECRET, body=BODY, header=upper_header, now=NOW)
+
+
+def test_secret_must_be_bytes():
+    header = _sign(SECRET, BODY, NOW)
+    with pytest.raises(TypeError):
+        verify_webhook(secret="str-secret", body=BODY, header=header, now=NOW)  # type: ignore[arg-type]
+
+
+def test_body_must_be_bytes():
+    header = _sign(SECRET, BODY, NOW)
+    with pytest.raises(TypeError):
+        verify_webhook(secret=SECRET, body="str-body", header=header, now=NOW)  # type: ignore[arg-type]
+
+
+def test_default_now_uses_wall_clock(monkeypatch):
+    """When ``now`` is omitted, the verifier must call ``time.time()``."""
+    monkeypatch.setattr(time, "time", lambda: float(NOW))
+    header = _sign(SECRET, BODY, NOW)
+    verify_webhook(secret=SECRET, body=BODY, header=header)