nkz-platform-sdk 0.3.0__tar.gz

nkz_platform_sdk-0.3.0/PKG-INFO

@@ -0,0 +1,13 @@
+Metadata-Version: 2.4
+Name: nkz-platform-sdk
+Version: 0.3.0
+Summary: Nekazari Platform SDK for module backends
+License: Apache-2.0
+Requires-Python: >=3.11
+Requires-Dist: fastapi>=0.109.0
+Requires-Dist: httpx>=0.26.0
+Requires-Dist: python-jose[cryptography]>=3.3.0
+Requires-Dist: cryptography>=42.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"

nkz_platform_sdk-0.3.0/nkz_platform_sdk/__init__.py

@@ -0,0 +1,31 @@
+"""
+Nekazari Platform SDK — Backend module development kit.
+
+Provides:
+- ModuleApp: FastAPI subclass pre-wired with CORS, /health, JSON logs, auth helpers
+- require_auth: FastAPI dependency for authenticated routes
+- OrionClient: Typed NGSI-LD client with automatic tenant header injection
+- TimescaleClient: Typed timeseries reader, tenant headers auto-injected
+- ModuleLifecycle: Base class for install/uninstall/enable/disable hooks
+- ModuleConfig: Per-tenant encrypted configuration storage
+
+License: Apache-2.0 — modules using this SDK may use any license.
+"""
+
+from nkz_platform_sdk.auth import require_auth, AuthContext
+from nkz_platform_sdk.module_app import ModuleApp
+from nkz_platform_sdk.orion import OrionClient
+from nkz_platform_sdk.timescale import TimescaleClient
+from nkz_platform_sdk.lifecycle import ModuleLifecycle, LifecycleResult
+from nkz_platform_sdk.config import ModuleConfig
+
+__all__ = [
+    "ModuleApp",
+    "require_auth",
+    "AuthContext",
+    "OrionClient",
+    "TimescaleClient",
+    "ModuleLifecycle",
+    "LifecycleResult",
+    "ModuleConfig",
+]

nkz_platform_sdk-0.3.0/nkz_platform_sdk/auth.py

@@ -0,0 +1,92 @@
+"""
+Authentication dependency for module backends.
+
+The api-gateway validates the JWT and injects headers:
+  X-Tenant-ID, X-User-ID, X-User-Roles, X-Request-ID
+
+This module provides require_auth() which reads those headers.
+Module backends do NOT validate JWT signatures — the gateway did that.
+Defense in depth: we still validate header presence and format.
+"""
+
+import re
+from dataclasses import dataclass
+from typing import Sequence
+from fastapi import Request, HTTPException, Depends
+
+
+@dataclass(frozen=True)
+class AuthContext:
+    """Authenticated request context injected by the gateway."""
+
+    tenant_id: str
+    user_id: str
+    roles: tuple[str, ...]
+    request_id: str | None = None
+
+    def has_role(self, role: str) -> bool:
+        return role in self.roles
+
+    def has_any_role(self, roles: Sequence[str]) -> bool:
+        return any(r in self.roles for r in roles)
+
+
+def require_auth(roles: Sequence[str] | None = None):
+    """
+    FastAPI dependency that validates gateway-injected auth headers.
+
+    Args:
+        roles: If provided, at least one role must match.
+
+    Returns:
+        FastAPI dependency yielding AuthContext.
+
+    Raises:
+        HTTPException 401 if headers are missing or invalid.
+        HTTPException 403 if roles are provided and none match.
+    """
+
+    async def _require_auth(request: Request) -> AuthContext:
+        tenant_id = request.headers.get("X-Tenant-ID", "").strip()
+        user_id = request.headers.get("X-User-ID", "").strip()
+        roles_header = request.headers.get("X-User-Roles", "").strip()
+        request_id = request.headers.get("X-Request-ID", "").strip() or None
+
+        # Validate presence
+        if not tenant_id:
+            raise HTTPException(
+                status_code=401,
+                detail="Missing X-Tenant-ID header — gateway misconfiguration?",
+            )
+        if not user_id:
+            raise HTTPException(
+                status_code=401,
+                detail="Missing X-User-ID header — gateway misconfiguration?",
+            )
+
+        # Validate tenant_id format (alphanumeric + underscore + hyphen, 3-63 chars)
+        if not re.match(r"^[a-z0-9_-]{3,63}$", tenant_id):
+            raise HTTPException(
+                status_code=401,
+                detail=f"Invalid X-Tenant-ID format: {tenant_id}",
+            )
+
+        user_roles = tuple(r.strip() for r in roles_header.split(",") if r.strip())
+
+        # Role check (defense in depth — gateway also checks)
+        if roles is not None:
+            allowed = set(roles)
+            if not any(r in allowed for r in user_roles):
+                raise HTTPException(
+                    status_code=403,
+                    detail=f"Access denied. Required one of: {roles}",
+                )
+
+        return AuthContext(
+            tenant_id=tenant_id,
+            user_id=user_id,
+            roles=user_roles,
+            request_id=request_id,
+        )
+
+    return Depends(_require_auth)

nkz_platform_sdk-0.3.0/nkz_platform_sdk/config.py

@@ -0,0 +1,77 @@
+"""
+ModuleConfig — per-tenant encrypted configuration storage.
+
+Values are encrypted at rest using Fernet symmetric encryption.
+The encryption key is derived from MODULE_CONFIG_SECRET env var.
+"""
+
+import os
+from base64 import urlsafe_b64encode
+from hashlib import sha256
+
+from cryptography.fernet import Fernet
+import httpx
+
+
+class ModuleConfig:
+    """Per-tenant encrypted configuration backed by platform API."""
+
+    def __init__(
+        self,
+        module_id: str,
+        tenant_id: str,
+        api_url: str | None = None,
+    ):
+        self.module_id = module_id
+        self.tenant_id = tenant_id
+        self._api_url = api_url or os.getenv(
+            "MODULE_CONFIG_API",
+            "http://entity-manager-service:5000/api/internal/module-config",
+        )
+        self._secret = os.getenv("MODULE_CONFIG_SECRET")
+        self._fernet: Fernet | None = None
+        if self._secret:
+            key = urlsafe_b64encode(sha256(self._secret.encode()).digest())
+            self._fernet = Fernet(key)
+
+    async def get(self, key: str) -> str | None:
+        resp = await self._request("GET", key)
+        if resp.status_code == 404:
+            return None
+        resp.raise_for_status()
+        value = resp.json().get("value")
+        if value and self._fernet:
+            value = self._fernet.decrypt(value.encode()).decode()
+        return value
+
+    async def set(self, key: str, value: str) -> None:
+        if self._fernet:
+            value = self._fernet.encrypt(value.encode()).decode()
+        await self._request("POST", key, {"value": value})
+
+    async def delete(self, key: str) -> None:
+        await self._request("DELETE", key)
+
+    async def list_keys(self) -> list[str]:
+        resp = await self._request("GET", "")
+        resp.raise_for_status()
+        return resp.json().get("keys", [])
+
+    async def _request(
+        self, method: str, key: str, data: dict | None = None
+    ) -> httpx.Response:
+        url = f"{self._api_url}/{self.module_id}/{self.tenant_id}"
+        if key:
+            url = f"{url}/{key}"
+        async with httpx.AsyncClient(timeout=10.0) as client:
+            headers = {
+                "X-Internal-Service": "nkz-platform-sdk",
+                "Content-Type": "application/json",
+            }
+            if method == "GET":
+                return await client.get(url, headers=headers)
+            elif method == "POST":
+                return await client.post(url, json=data, headers=headers)
+            elif method == "DELETE":
+                return await client.delete(url, headers=headers)
+            raise ValueError(f"Unknown method: {method}")

nkz_platform_sdk-0.3.0/nkz_platform_sdk/lifecycle.py

@@ -0,0 +1,58 @@
+"""
+ModuleLifecycle — base class for module lifecycle hooks.
+
+The platform calls lifecycle webhooks via HMAC-signed HTTP POST.
+Modules extend this class and implement on_install/on_uninstall/etc.
+
+Guarantees provided by the platform:
+- Idempotency: same call N times = same result
+- Retry: exponential backoff (3 attempts: 1s, 4s, 16s)
+- Dead-letter: after retries exhausted, logged for manual intervention
+"""
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class LifecycleResult:
+    status: str  # "active" | "failed" | "pending"
+    message: str = ""
+    resources: dict[str, Any] = field(default_factory=dict)
+
+
+class ModuleLifecycle:
+    """Base class for module lifecycle hooks. Override any hook needed."""
+
+    def __init__(self):
+        self._handlers: dict[str, Any] = {}
+
+    def on_install(self, func):
+        self._handlers["install"] = func
+        return func
+
+    def on_uninstall(self, func):
+        self._handlers["uninstall"] = func
+        return func
+
+    def on_enable(self, func):
+        self._handlers["enable"] = func
+        return func
+
+    def on_disable(self, func):
+        self._handlers["disable"] = func
+        return func
+
+    async def handle(
+        self, event: str, tenant_id: str, config: dict | None = None
+    ) -> LifecycleResult:
+        handler = self._handlers.get(event)
+        if handler is None:
+            return LifecycleResult(
+                status="active",
+                message=f"No handler registered for '{event}' — noop",
+            )
+        try:
+            return await handler(tenant_id, config or {})
+        except Exception as e:
+            return LifecycleResult(status="failed", message=str(e))

nkz_platform_sdk-0.3.0/nkz_platform_sdk/module_app.py

@@ -0,0 +1,175 @@
+"""
+ModuleApp — FastAPI subclass pre-wired for Nekazari module backends.
+
+What you write:
+    from nkz_platform_sdk import ModuleApp, AuthContext
+
+    app = ModuleApp(id="soil-health", description="Soil Health backend")
+
+    @app.get("/parcels/{parcel_id}/analysis")
+    async def analysis(parcel_id: str, ctx: AuthContext = app.auth()):
+        orion = app.orion(ctx)
+        return await orion.get_entity(parcel_id)
+
+What you get for free:
+- CORS configured from `ALLOWED_ORIGINS` env (comma-separated, default same-origin only).
+- `/health` and `/ready` endpoints exempt from auth and rate limit.
+- JSON structured logs with `tenant_id`, `user_id`, `module_id`, `trace_id` (when reachable).
+- OpenAPI at `/openapi.json` (FastAPI native — keep your endpoints typed for free docs).
+- `app.auth(roles=...)` shortcut → `require_auth(roles)`.
+- `app.orion(ctx)` → an `OrionClient` scoped to the authenticated tenant.
+- `app.timescale(ctx)` → a `TimescaleClient` scoped to the authenticated tenant.
+"""
+
+import json
+import logging
+import os
+import time
+import uuid
+from typing import Any, Sequence
+
+from fastapi import FastAPI, Request
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import JSONResponse
+
+from nkz_platform_sdk.auth import AuthContext, require_auth
+from nkz_platform_sdk.orion import OrionClient
+from nkz_platform_sdk.timescale import TimescaleClient
+
+
+def _parse_origins(env_value: str | None) -> list[str]:
+    if not env_value:
+        return []
+    return [o.strip() for o in env_value.split(",") if o.strip()]
+
+
+class _JsonFormatter(logging.Formatter):
+    """Single-line JSON log records — Loki / Cloud Logging / Datadog friendly."""
+
+    def format(self, record: logging.LogRecord) -> str:
+        payload: dict[str, Any] = {
+            "ts": self.formatTime(record, "%Y-%m-%dT%H:%M:%S"),
+            "level": record.levelname,
+            "logger": record.name,
+            "msg": record.getMessage(),
+        }
+        for attr in ("module_id", "tenant_id", "user_id", "trace_id"):
+            v = getattr(record, attr, None)
+            if v is not None:
+                payload[attr] = v
+        if record.exc_info:
+            payload["exc"] = self.formatException(record.exc_info)
+        return json.dumps(payload, default=str)
+
+
+def _configure_json_logging(module_id: str) -> None:
+    """Replace the root logger's handlers with one that emits JSON.
+    Idempotent — re-applying ModuleApp() in tests won't keep stacking handlers.
+    """
+    root = logging.getLogger()
+    for h in list(root.handlers):
+        root.removeHandler(h)
+    handler = logging.StreamHandler()
+    handler.setFormatter(_JsonFormatter())
+    root.addHandler(handler)
+    root.setLevel(os.getenv("LOG_LEVEL", "INFO").upper())
+    # Attach module_id to every record via a filter
+    module_filter = logging.Filter()
+    module_filter.filter = lambda r: setattr(r, "module_id", module_id) or True  # type: ignore[assignment]
+    root.addFilter(module_filter)
+
+
+class ModuleApp(FastAPI):
+    """FastAPI app pre-cabled with everything a Nekazari module backend needs."""
+
+    def __init__(
+        self,
+        id: str,
+        description: str = "",
+        version: str = "0.1.0",
+        allowed_origins: Sequence[str] | None = None,
+        configure_logging: bool = True,
+        **fastapi_kwargs: Any,
+    ) -> None:
+        super().__init__(
+            title=f"Nekazari module: {id}",
+            description=description,
+            version=version,
+            **fastapi_kwargs,
+        )
+        self.module_id = id
+
+        if configure_logging:
+            _configure_json_logging(id)
+
+        origins = (
+            list(allowed_origins)
+            if allowed_origins is not None
+            else _parse_origins(os.getenv("ALLOWED_ORIGINS"))
+        )
+        if origins:
+            self.add_middleware(
+                CORSMiddleware,
+                allow_origins=origins,
+                allow_credentials=True,
+                allow_methods=["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"],
+                allow_headers=[
+                    "Authorization",
+                    "Content-Type",
+                    "X-Tenant-ID",
+                    "X-Module-Id",
+                    "X-User-ID",
+                    "X-User-Roles",
+                    "X-Request-ID",
+                    "Cookie",
+                ],
+            )
+
+        # Request-scope trace id + access log
+        @self.middleware("http")
+        async def _request_scope(request: Request, call_next: Any) -> Any:
+            trace_id = request.headers.get("X-Request-ID") or uuid.uuid4().hex
+            start = time.monotonic()
+            response = await call_next(request)
+            elapsed_ms = int((time.monotonic() - start) * 1000)
+            logging.getLogger("nkz.access").info(
+                "%s %s %s in %dms",
+                request.method,
+                request.url.path,
+                response.status_code,
+                elapsed_ms,
+                extra={
+                    "tenant_id": request.headers.get("X-Tenant-ID"),
+                    "user_id": request.headers.get("X-User-ID"),
+                    "trace_id": trace_id,
+                },
+            )
+            response.headers["X-Request-ID"] = trace_id
+            return response
+
+        @self.get("/health", include_in_schema=False)
+        async def _health() -> dict[str, str]:
+            return {"status": "ok", "module": id}
+
+        @self.get("/ready", include_in_schema=False)
+        async def _ready() -> dict[str, str]:
+            return {"status": "ready", "module": id}
+
+        @self.exception_handler(Exception)
+        async def _unhandled(_request: Request, exc: Exception) -> JSONResponse:
+            logging.getLogger("nkz.error").exception("unhandled exception: %s", exc)
+            return JSONResponse(
+                status_code=500, content={"error": "internal", "detail": str(exc)}
+            )
+
+    def auth(self, roles: Sequence[str] | None = None) -> Any:
+        """Shortcut for `require_auth(roles)`."""
+        return require_auth(roles)
+
+    def orion(self, ctx: AuthContext) -> OrionClient:
+        """Create an OrionClient scoped to the authenticated tenant."""
+        return OrionClient(ctx.tenant_id)
+
+    def timescale(self, ctx: AuthContext) -> TimescaleClient:
+        """Create a TimescaleClient scoped to the authenticated tenant."""
+        return TimescaleClient(ctx.tenant_id)

nkz_platform_sdk-0.3.0/nkz_platform_sdk/orion.py

@@ -0,0 +1,167 @@
+"""
+OrionClient — typed NGSI-LD client with automatic FIWARE header injection.
+
+Rules enforced at library level (impossible to forget):
+- Every request sends NGSILD-Tenant AND Fiware-Service headers
+- Content-Type: application/ld+json with @context in body
+- Or Content-Type: application/json with Link header
+"""
+
+import os
+from typing import Any
+from urllib.parse import urljoin
+
+import httpx
+
+CONTEXT_URL = os.getenv(
+    "CONTEXT_URL",
+    "http://api-gateway-service:5000/ngsi-ld-context.json",
+)
+
+
+class OrionClient:
+    """NGSI-LD client scoped to a single tenant."""
+
+    def __init__(
+        self,
+        tenant_id: str,
+        base_url: str | None = None,
+        context_url: str | None = None,
+    ):
+        self.tenant_id = tenant_id
+        self.base_url = base_url or os.getenv(
+            "ORION_LD_URL", "http://orion-ld-service:1026"
+        )
+        self.context_url = context_url or CONTEXT_URL
+        self._client = httpx.AsyncClient(timeout=30.0)
+
+    def _headers(self, content_type: str = "application/ld+json") -> dict[str, str]:
+        headers = {
+            "NGSILD-Tenant": self.tenant_id,
+            "Fiware-Service": self.tenant_id,
+            "Fiware-ServicePath": "/",
+        }
+        if content_type == "application/ld+json":
+            headers["Content-Type"] = "application/ld+json"
+        elif content_type == "application/json":
+            headers["Content-Type"] = "application/json"
+            headers["Link"] = (
+                f'<{self.context_url}>; rel="http://www.w3.org/ns/json-ld#context";'
+                ' type="application/ld+json"'
+            )
+        return headers
+
+    def _url(self, path: str) -> str:
+        return urljoin(f"{self.base_url}/", path.lstrip("/"))
+
+    async def query_entities(
+        self,
+        type: str | None = None,
+        q: str | None = None,
+        limit: int = 100,
+        offset: int = 0,
+        attrs: str | None = None,
+    ) -> list[dict[str, Any]]:
+        params: dict[str, Any] = {"limit": limit, "offset": offset}
+        if type:
+            params["type"] = type
+        if q:
+            params["q"] = q
+        if attrs:
+            params["attrs"] = attrs
+        resp = await self._client.get(
+            self._url("/ngsi-ld/v1/entities"),
+            params=params,
+            headers=self._headers("application/json"),
+        )
+        resp.raise_for_status()
+        return resp.json()
+
+    async def get_entity(self, entity_id: str) -> dict[str, Any]:
+        resp = await self._client.get(
+            self._url(f"/ngsi-ld/v1/entities/{entity_id}"),
+            headers=self._headers("application/json"),
+        )
+        resp.raise_for_status()
+        return resp.json()
+
+    def _ensure_context(self, entity: dict[str, Any]) -> dict[str, Any]:
+        if "@context" not in entity:
+            return {"@context": [self.context_url], **entity}
+        return entity
+
+    async def create_entity(self, entity: dict[str, Any]) -> dict[str, Any]:
+        entity = self._ensure_context(entity)
+        resp = await self._client.post(
+            self._url("/ngsi-ld/v1/entities"),
+            json=entity,
+            headers=self._headers("application/ld+json"),
+        )
+        resp.raise_for_status()
+        location = resp.headers.get("Location", "")
+        return {"id": location.split("/")[-1] if location else "", "status": "created"}
+
+    async def create_entities_batch(
+        self,
+        entities: list[dict[str, Any]],
+    ) -> dict[str, Any]:
+        """Create multiple entities via POST /ngsi-ld/v1/entityOperations/create.
+
+        Returns:
+            dict with keys ``created``, ``errors``, ``entity_ids``.
+        Raises:
+            httpx.HTTPStatusError: on non-batchable failure (caller may fall back).
+        """
+        prepared = [self._ensure_context(e) for e in entities]
+        if not prepared:
+            return {"created": 0, "errors": [], "entity_ids": []}
+
+        resp = await self._client.post(
+            self._url("/ngsi-ld/v1/entityOperations/create"),
+            json=prepared,
+            headers=self._headers("application/ld+json"),
+        )
+
+        entity_ids = [e["id"] for e in prepared if e.get("id")]
+
+        if resp.status_code in (200, 201, 204):
+            return {
+                "created": len(prepared),
+                "errors": [],
+                "entity_ids": entity_ids,
+            }
+
+        if resp.status_code == 207:
+            body = resp.json() if resp.content else {}
+            success = body.get("success", entity_ids)
+            errors = body.get("errors", [])
+            if isinstance(success, list) and success and isinstance(success[0], dict):
+                success_ids = [s.get("id", "") for s in success if s.get("id")]
+            else:
+                success_ids = success if isinstance(success, list) else entity_ids
+            return {
+                "created": len(success_ids),
+                "errors": errors,
+                "entity_ids": success_ids,
+            }
+
+        resp.raise_for_status()
+        return {"created": 0, "errors": [], "entity_ids": []}
+
+    async def update_entity_attrs(self, entity_id: str, attrs: dict[str, Any]) -> None:
+        resp = await self._client.patch(
+            self._url(f"/ngsi-ld/v1/entities/{entity_id}/attrs"),
+            json=attrs,
+            headers=self._headers("application/ld+json"),
+        )
+        resp.raise_for_status()
+
+    async def delete_entity(self, entity_id: str) -> None:
+        resp = await self._client.delete(
+            self._url(f"/ngsi-ld/v1/entities/{entity_id}"),
+            headers=self._headers(),
+        )
+        resp.raise_for_status()
+
+    async def close(self) -> None:
+        await self._client.aclose()

nkz_platform_sdk-0.3.0/nkz_platform_sdk/timescale.py

@@ -0,0 +1,128 @@
+"""
+TimescaleClient — typed read-only client for the platform timeseries store.
+
+Design constraint (defense in depth): tenant isolation lives in the
+`timeseries-reader-service`, which owns Postgres RLS and is the only service
+holding DB credentials. Module backends MUST NOT open direct DB connections —
+they go through HTTP to that service, and the SDK auto-injects the canonical
+tenant headers so a module cannot accidentally read another tenant's data.
+
+Usage:
+    from nkz_platform_sdk import ModuleApp, AuthContext
+
+    app = ModuleApp(id="soil-health")
+
+    @app.get("/parcels/{pid}/moisture")
+    async def moisture(pid: str, ctx: AuthContext = app.auth()):
+        ts = app.timescale(ctx)
+        return await ts.query(
+            entity_id=f"urn:ngsi-ld:AgriParcel:{pid}",
+            attribute="soilMoisture",
+            since="2026-05-01T00:00:00Z",
+        )
+"""
+
+import os
+from datetime import datetime
+from typing import Any
+from urllib.parse import urljoin
+
+import httpx
+
+
+def _iso(value: str | datetime) -> str:
+    if isinstance(value, datetime):
+        return value.isoformat()
+    return value
+
+
+class TimescaleClient:
+    """Read-only timeseries client scoped to a single tenant.
+
+    All calls go through `timeseries-reader-service`, which enforces
+    Postgres row-level security based on the injected tenant headers.
+    """
+
+    def __init__(
+        self,
+        tenant_id: str,
+        base_url: str | None = None,
+    ):
+        self.tenant_id = tenant_id
+        self.base_url = base_url or os.getenv(
+            "TIMESERIES_READER_URL",
+            "http://timeseries-reader-service:5000",
+        )
+        self._client = httpx.AsyncClient(timeout=30.0)
+
+    def _headers(self) -> dict[str, str]:
+        return {
+            "X-Tenant-ID": self.tenant_id,
+            "NGSILD-Tenant": self.tenant_id,
+            "Fiware-Service": self.tenant_id,
+            "Content-Type": "application/json",
+        }
+
+    def _url(self, path: str) -> str:
+        return urljoin(f"{self.base_url}/", path.lstrip("/"))
+
+    async def query(
+        self,
+        entity_id: str,
+        attribute: str,
+        since: str | datetime,
+        until: str | datetime | None = None,
+        limit: int = 1000,
+    ) -> list[dict[str, Any]]:
+        """Fetch a single attribute timeseries for a single entity.
+
+        Returns a list of `{"ts": iso8601, "value": float}` points, oldest first.
+        Non-numeric points are silently filtered out.
+        """
+        params: dict[str, Any] = {
+            "entityId": entity_id,
+            "attribute": attribute,
+            "since": _iso(since),
+            "limit": limit,
+        }
+        if until is not None:
+            params["until"] = _iso(until)
+        resp = await self._client.get(
+            self._url("/api/timeseries"),
+            params=params,
+            headers=self._headers(),
+        )
+        resp.raise_for_status()
+        raw = resp.json()
+        points = raw.get("points", raw) if isinstance(raw, dict) else raw
+        normalised: list[dict[str, Any]] = []
+        for p in points or []:
+            ts = p.get("ts") or p.get("timestamp") or p.get("time")
+            val = p.get("value") if "value" in p else p.get("v")
+            if ts is None or val is None:
+                continue
+            try:
+                normalised.append({"ts": ts, "value": float(val)})
+            except (TypeError, ValueError):
+                continue
+        return normalised
+
+    async def query_aggregate(
+        self,
+        body: dict[str, Any],
+    ) -> dict[str, Any]:
+        """Run a multi-series aggregation against `/api/v2/query`.
+
+        The body is forwarded verbatim — see timeseries-reader-service for the
+        accepted shape (entityIds, attributes, aggregation window, etc.).
+        """
+        resp = await self._client.post(
+            self._url("/api/v2/query"),
+            json=body,
+            headers=self._headers(),
+        )
+        resp.raise_for_status()
+        return resp.json()
+
+    async def close(self) -> None:
+        await self._client.aclose()

nkz_platform_sdk-0.3.0/nkz_platform_sdk.egg-info/PKG-INFO

@@ -0,0 +1,13 @@
+Metadata-Version: 2.4
+Name: nkz-platform-sdk
+Version: 0.3.0
+Summary: Nekazari Platform SDK for module backends
+License: Apache-2.0
+Requires-Python: >=3.11
+Requires-Dist: fastapi>=0.109.0
+Requires-Dist: httpx>=0.26.0
+Requires-Dist: python-jose[cryptography]>=3.3.0
+Requires-Dist: cryptography>=42.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"

nkz_platform_sdk-0.3.0/nkz_platform_sdk.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+pyproject.toml
+nkz_platform_sdk/__init__.py
+nkz_platform_sdk/auth.py
+nkz_platform_sdk/config.py
+nkz_platform_sdk/lifecycle.py
+nkz_platform_sdk/module_app.py
+nkz_platform_sdk/orion.py
+nkz_platform_sdk/timescale.py
+nkz_platform_sdk.egg-info/PKG-INFO
+nkz_platform_sdk.egg-info/SOURCES.txt
+nkz_platform_sdk.egg-info/dependency_links.txt
+nkz_platform_sdk.egg-info/requires.txt
+nkz_platform_sdk.egg-info/top_level.txt
+tests/test_module_app.py
+tests/test_timescale.py

nkz_platform_sdk-0.3.0/nkz_platform_sdk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

nkz_platform_sdk-0.3.0/nkz_platform_sdk.egg-info/requires.txt

@@ -0,0 +1,8 @@
+fastapi>=0.109.0
+httpx>=0.26.0
+python-jose[cryptography]>=3.3.0
+cryptography>=42.0.0
+
+[dev]
+pytest>=7.4.0
+pytest-asyncio>=0.23.0

nkz_platform_sdk-0.3.0/nkz_platform_sdk.egg-info/top_level.txt

@@ -0,0 +1 @@
+nkz_platform_sdk

nkz_platform_sdk-0.3.0/pyproject.toml

@@ -0,0 +1,22 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "nkz-platform-sdk"
+version = "0.3.0"
+description = "Nekazari Platform SDK for module backends"
+license = {text = "Apache-2.0"}
+requires-python = ">=3.11"
+dependencies = [
+    "fastapi>=0.109.0",
+    "httpx>=0.26.0",
+    "python-jose[cryptography]>=3.3.0",
+    "cryptography>=42.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.4.0",
+    "pytest-asyncio>=0.23.0",
+]

nkz_platform_sdk-0.3.0/setup.cfg

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

nkz_platform_sdk-0.3.0/tests/test_module_app.py

@@ -0,0 +1,142 @@
+"""Unit tests for ModuleApp — uses FastAPI TestClient (sync)."""
+
+import logging
+
+from fastapi.testclient import TestClient
+
+from nkz_platform_sdk import ModuleApp, AuthContext
+
+
+def make_client(**kwargs) -> TestClient:
+    # configure_logging=False to avoid mutating root logger between tests
+    app = ModuleApp(id="testmod", configure_logging=False, **kwargs)
+
+    @app.get("/protected")
+    async def protected(ctx: AuthContext = app.auth()):
+        return {"tenant": ctx.tenant_id, "user": ctx.user_id, "roles": list(ctx.roles)}
+
+    @app.get("/farmer-only")
+    async def farmer_only(ctx: AuthContext = app.auth(roles=["Farmer"])):
+        return {"ok": True}
+
+    return TestClient(app)
+
+
+def test_health_no_auth() -> None:
+    c = make_client()
+    r = c.get("/health")
+    assert r.status_code == 200
+    assert r.json() == {"status": "ok", "module": "testmod"}
+
+
+def test_ready_no_auth() -> None:
+    c = make_client()
+    r = c.get("/ready")
+    assert r.status_code == 200
+    assert r.json()["status"] == "ready"
+
+
+def test_protected_requires_tenant_header() -> None:
+    c = make_client()
+    r = c.get("/protected")
+    assert r.status_code == 401
+    assert "X-Tenant-ID" in r.json()["detail"]
+
+
+def test_protected_requires_user_header() -> None:
+    c = make_client()
+    r = c.get("/protected", headers={"X-Tenant-ID": "acme"})
+    assert r.status_code == 401
+    assert "X-User-ID" in r.json()["detail"]
+
+
+def test_protected_rejects_invalid_tenant_format() -> None:
+    c = make_client()
+    r = c.get("/protected", headers={"X-Tenant-ID": "BadTenant!", "X-User-ID": "u"})
+    assert r.status_code == 401
+
+
+def test_protected_success() -> None:
+    c = make_client()
+    r = c.get(
+        "/protected",
+        headers={
+            "X-Tenant-ID": "acme",
+            "X-User-ID": "u-1",
+            "X-User-Roles": "Farmer,TenantAdmin",
+        },
+    )
+    assert r.status_code == 200
+    body = r.json()
+    assert body["tenant"] == "acme"
+    assert body["user"] == "u-1"
+    assert body["roles"] == ["Farmer", "TenantAdmin"]
+
+
+def test_role_check_blocks_when_missing() -> None:
+    c = make_client()
+    r = c.get(
+        "/farmer-only",
+        headers={"X-Tenant-ID": "acme", "X-User-ID": "u", "X-User-Roles": "Random"},
+    )
+    assert r.status_code == 403
+
+
+def test_role_check_allows_when_present() -> None:
+    c = make_client()
+    r = c.get(
+        "/farmer-only",
+        headers={"X-Tenant-ID": "acme", "X-User-ID": "u", "X-User-Roles": "Farmer"},
+    )
+    assert r.status_code == 200
+
+
+def test_cors_origin_allowed_when_configured() -> None:
+    c = make_client(allowed_origins=["https://example.test"])
+    r = c.options(
+        "/protected",
+        headers={
+            "Origin": "https://example.test",
+            "Access-Control-Request-Method": "GET",
+        },
+    )
+    assert r.status_code == 200
+    assert r.headers.get("access-control-allow-origin") == "https://example.test"
+
+
+def test_request_id_header_present_in_response() -> None:
+    c = make_client()
+    r = c.get("/health")
+    assert "x-request-id" in {k.lower() for k in r.headers}
+
+
+def test_request_id_passthrough_when_provided() -> None:
+    c = make_client()
+    r = c.get("/health", headers={"X-Request-ID": "trace-abc"})
+    assert r.headers["x-request-id"] == "trace-abc"
+
+
+def test_orion_factory_returns_scoped_client() -> None:
+    app = ModuleApp(id="testmod", configure_logging=False)
+    ctx = AuthContext(tenant_id="acme", user_id="u", roles=("Farmer",))
+    orion = app.orion(ctx)
+    assert orion.tenant_id == "acme"
+
+
+def test_unhandled_exception_returns_500_json() -> None:
+    app = ModuleApp(id="testmod", configure_logging=False)
+
+    @app.get("/boom")
+    async def boom() -> None:
+        raise RuntimeError("oops")
+
+    c = TestClient(app, raise_server_exceptions=False)
+    r = c.get("/boom")
+    assert r.status_code == 500
+    assert r.json()["error"] == "internal"
+
+
+def test_logging_filter_does_not_break_when_enabled() -> None:
+    # Just construct with logging on, ensure no exceptions
+    ModuleApp(id="testmod", configure_logging=True)
+    logging.getLogger("nkz.access").info("smoke")

nkz_platform_sdk-0.3.0/tests/test_timescale.py

@@ -0,0 +1,116 @@
+"""Unit tests for TimescaleClient — fakes the httpx layer, no network."""
+
+from typing import Any
+
+import pytest
+
+from nkz_platform_sdk.timescale import TimescaleClient
+
+
+class _FakeResponse:
+    def __init__(self, status_code: int, payload: Any):
+        self.status_code = status_code
+        self._payload = payload
+
+    def raise_for_status(self) -> None:
+        if self.status_code >= 400:
+            raise RuntimeError(f"HTTP {self.status_code}")
+
+    def json(self) -> Any:
+        return self._payload
+
+
+class _FakeAsyncClient:
+    def __init__(self, response: _FakeResponse):
+        self.response = response
+        self.last_get: dict[str, Any] | None = None
+        self.last_post: dict[str, Any] | None = None
+
+    async def get(self, url: str, params: dict[str, Any], headers: dict[str, str]):
+        self.last_get = {"url": url, "params": params, "headers": headers}
+        return self.response
+
+    async def post(self, url: str, json: dict[str, Any], headers: dict[str, str]):
+        self.last_post = {"url": url, "json": json, "headers": headers}
+        return self.response
+
+    async def aclose(self) -> None:
+        pass
+
+
+def _make(payload: Any, status: int = 200) -> tuple[TimescaleClient, _FakeAsyncClient]:
+    client = TimescaleClient(tenant_id="acme", base_url="http://ts-test:5000")
+    fake = _FakeAsyncClient(_FakeResponse(status, payload))
+    client._client = fake  # type: ignore[assignment]
+    return client, fake
+
+
+@pytest.mark.asyncio
+async def test_query_normalises_points() -> None:
+    client, fake = _make({"points": [{"ts": "2026-05-01T00:00:00Z", "value": "42.5"}]})
+    pts = await client.query(
+        entity_id="urn:ngsi-ld:AgriParcel:p1",
+        attribute="soilMoisture",
+        since="2026-05-01T00:00:00Z",
+    )
+    assert pts == [{"ts": "2026-05-01T00:00:00Z", "value": 42.5}]
+    assert fake.last_get is not None
+    assert fake.last_get["headers"]["X-Tenant-ID"] == "acme"
+    assert fake.last_get["headers"]["NGSILD-Tenant"] == "acme"
+    assert fake.last_get["headers"]["Fiware-Service"] == "acme"
+    assert fake.last_get["params"]["entityId"] == "urn:ngsi-ld:AgriParcel:p1"
+    assert fake.last_get["params"]["attribute"] == "soilMoisture"
+
+
+@pytest.mark.asyncio
+async def test_query_filters_non_numeric() -> None:
+    client, _ = _make(
+        {
+            "points": [
+                {"ts": "2026-05-01T00:00:00Z", "value": "42"},
+                {"ts": "2026-05-02T00:00:00Z", "value": "not-a-number"},
+                {"ts": "2026-05-03T00:00:00Z"},  # missing value
+                {"ts": "2026-05-04T00:00:00Z", "value": 7},
+            ]
+        }
+    )
+    pts = await client.query(
+        entity_id="urn:ngsi-ld:AgriParcel:p1",
+        attribute="x",
+        since="2026-05-01T00:00:00Z",
+    )
+    assert [p["value"] for p in pts] == [42.0, 7.0]
+
+
+@pytest.mark.asyncio
+async def test_query_accepts_bare_list_payload() -> None:
+    client, _ = _make([{"ts": "2026-05-01T00:00:00Z", "value": 1}])
+    pts = await client.query(
+        entity_id="urn:ngsi-ld:AgriParcel:p1",
+        attribute="x",
+        since="2026-05-01T00:00:00Z",
+    )
+    assert pts == [{"ts": "2026-05-01T00:00:00Z", "value": 1.0}]
+
+
+@pytest.mark.asyncio
+async def test_query_aggregate_posts_to_v2() -> None:
+    client, fake = _make({"series": []})
+    body = {"entityIds": ["a", "b"], "attributes": ["x"], "aggrPeriod": "PT1H"}
+    out = await client.query_aggregate(body)
+    assert out == {"series": []}
+    assert fake.last_post is not None
+    assert fake.last_post["url"].endswith("/api/v2/query")
+    assert fake.last_post["json"] == body
+    assert fake.last_post["headers"]["X-Tenant-ID"] == "acme"
+
+
+@pytest.mark.asyncio
+async def test_http_error_propagates() -> None:
+    client, _ = _make({}, status=500)
+    with pytest.raises(RuntimeError):
+        await client.query(
+            entity_id="urn:ngsi-ld:AgriParcel:p1",
+            attribute="x",
+            since="2026-05-01T00:00:00Z",
+        )