patchr 0.1.0__py3-none-any.whl

picux/storage/keyspace.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+
+LegacyKind = Literal["user", "task", "receipt", "metric"]
+
+
+@dataclass(frozen=True)
+class Keyspace:
+    prefix: str = "picux:v1"
+
+    def user(self, userId: str) -> str:
+        return f"{self.prefix}:user:{userId}"
+
+    def task(self, taskId: str) -> str:
+        return f"{self.prefix}:task:{taskId}"
+
+    def taskLog(self, taskId: str) -> str:
+        return f"{self.prefix}:audit:task:{taskId}"
+
+    def userTasks(self, userId: str) -> str:
+        return f"{self.prefix}:userTasks:{userId}"
+
+    def userLog(self, userId: str) -> str:
+        return f"{self.prefix}:audit:user:{userId}"
+
+    def metric(self, name: str) -> str:
+        return f"{self.prefix}:metrics:{name}"
+
+    def receipt(self, receiptId: str) -> str:
+        return f"{self.prefix}:receipt:{receiptId}"
+
+    def legacyCandidates(self, kind: LegacyKind, itemId: str) -> list[str]:
+        item = str(itemId or "")
+        if kind == "user":
+            return [f"swarm:user:{item}", f"swarm:v2:user:{item}"]
+        if kind == "task":
+            return [f"swarm:task:{item}", f"swarm:v2:task:{item}"]
+        if kind == "receipt":
+            return [f"swarm:receipt:{item}", f"swarm:v2:receipt:{item}"]
+        if kind == "metric":
+            return [f"swarm:metrics:{item}", f"swarm:v2:metrics:{item}"]
+        return []
+
+    def migrationReadPlan(self, kind: LegacyKind, itemId: str) -> dict[str, object]:
+        current = {
+            "user": self.user,
+            "task": self.task,
+            "receipt": self.receipt,
+            "metric": self.metric,
+        }[kind](itemId)
+        return {
+            "kind": kind,
+            "id": itemId,
+            "writeKey": current,
+            "readKeys": [current, *self.legacyCandidates(kind, itemId)],
+            "writePolicy": "picuxOnly",
+        }

picux/storage/mandates.py

@@ -0,0 +1,107 @@
+from __future__ import annotations
+
+import copy
+import time
+from typing import Any
+
+
+class MandateBook:
+    """Mandate record storage with optional durable backing."""
+
+    def __init__(self, *, backing: Any | None = None) -> None:
+        self.backing = backing
+        self._records: dict[str, dict[str, Any]] = {}
+
+    def saveMandate(self, mandate: dict[str, Any], *, status: str = "pendingVerification") -> dict[str, Any]:
+        mandateId = str(mandate.get("mandateId", "") or "")
+        if not mandateId:
+            return {"ok": False, "error": "missing:mandateId"}
+        now = int(time.time())
+        current = self.getMandate(mandateId)
+        createdAt = current.get("record", {}).get("createdAt", now) if current.get("ok") else now
+        record = {
+            "mandateId": mandateId,
+            "status": status,
+            "mandate": copy.deepcopy(mandate),
+            "validation": current.get("record", {}).get("validation", {}) if current.get("ok") else {},
+            "createdAt": createdAt,
+            "updatedAt": now,
+        }
+        self._saveRecord(record)
+        return {"ok": True, "record": copy.deepcopy(record)}
+
+    def saveValidation(self, mandateId: str, mandate: dict[str, Any], validation: dict[str, Any]) -> dict[str, Any]:
+        status = "verified" if validation.get("ok") else "rejected"
+        base = self.saveMandate({**mandate, "mandateId": mandateId}, status=status)
+        if not base.get("ok"):
+            return base
+        record = base["record"]
+        record["validation"] = copy.deepcopy(validation)
+        record["updatedAt"] = int(time.time())
+        self._saveRecord(record)
+        return {"ok": True, "record": copy.deepcopy(record)}
+
+    def getMandate(self, mandateId: str) -> dict[str, Any]:
+        mandateId = str(mandateId or "")
+        record = self._records.get(mandateId)
+        if record is None and self._backingEnabled() and hasattr(self.backing, "fetchMandate"):
+            record = self.backing.fetchMandate(mandateId)
+            if record:
+                self._records[mandateId] = copy.deepcopy(record)
+        if not record:
+            return {"ok": False, "error": "mandateNotFound", "mandateId": mandateId}
+        return {"ok": True, "record": copy.deepcopy(record)}
+
+    def listMandates(self, filters: dict[str, Any] | None = None) -> dict[str, Any]:
+        self._loadBacking()
+        filters = filters or {}
+        status = str(filters.get("status", "") or "")
+        issuerId = str(filters.get("issuerId", "") or "")
+        records = list(self._records.values())
+        if status:
+            records = [record for record in records if record.get("status") == status]
+        if issuerId:
+            records = [
+                record
+                for record in records
+                if str(record.get("mandate", {}).get("issuer", {}).get("entityId", "") or "") == issuerId
+            ]
+        records.sort(
+            key=lambda item: (int(item.get("createdAt", 0) or 0), str(item.get("mandateId", ""))),
+            reverse=True,
+        )
+        limit = _limit(filters.get("limit", 100))
+        return {
+            "ok": True,
+            "mandates": [copy.deepcopy(record) for record in records[:limit]],
+            "count": min(len(records), limit),
+        }
+
+    def _saveRecord(self, record: dict[str, Any]) -> None:
+        mandateId = str(record.get("mandateId", "") or "")
+        if not mandateId:
+            return
+        self._records[mandateId] = copy.deepcopy(record)
+        if self._backingEnabled() and hasattr(self.backing, "upsertMandate"):
+            self.backing.upsertMandate(record)
+
+    def _loadBacking(self) -> None:
+        if self.backing is None or not self._backingEnabled() or not hasattr(self.backing, "listMandates"):
+            return
+        for record in self.backing.listMandates():
+            mandateId = str(record.get("mandateId", "") or "")
+            if mandateId:
+                self._records[mandateId] = copy.deepcopy(record)
+
+    def _backingEnabled(self) -> bool:
+        if self.backing is None:
+            return False
+        return bool(getattr(self.backing, "enabled", True))
+
+
+def _limit(value: Any) -> int:
+    try:
+        parsed = int(value)
+    except (TypeError, ValueError):
+        return 100
+    return max(1, min(parsed, 500))

picux/storage/portals.py

@@ -0,0 +1,222 @@
+from __future__ import annotations
+
+import copy
+import hashlib
+import json
+import time
+from typing import Any
+
+
+PORTAL_SESSION_STATUSES = {"active", "needsAuth", "expired", "revoked"}
+PORTAL_ACTION_STATUSES = {"queued", "running", "succeeded", "failed", "blocked", "needsInput", "needsProxy"}
+
+
+class PortalBook:
+    """Authenticated portal action state for merchant, carrier, utility, and provider workflows."""
+
+    def __init__(self, *, backing: Any | None = None) -> None:
+        self.backing = backing
+        self._sessions: dict[str, dict[str, Any]] = {}
+        self._actions: dict[str, dict[str, Any]] = {}
+
+    def createSession(self, payload: dict[str, Any]) -> dict[str, Any]:
+        now = int(time.time())
+        sessionId = str(payload.get("portalSessionId", payload.get("sessionId", "")) or _stableId("portalSession", payload))
+        current = self.getSession(sessionId)
+        createdAt = int(current.get("session", {}).get("createdAt", now) if current.get("ok") else now)
+        record = _sessionFromPayload({**payload, "portalSessionId": sessionId}, createdAt=createdAt, updatedAt=now)
+        self._saveSession(record)
+        return {"ok": True, "session": copy.deepcopy(record)}
+
+    def getSession(self, sessionId: str) -> dict[str, Any]:
+        sessionId = str(sessionId or "")
+        record = self._sessions.get(sessionId)
+        if record is None and self._backingEnabled() and hasattr(self.backing, "fetchPortalSession"):
+            record = self.backing.fetchPortalSession(sessionId)
+            if record:
+                self._sessions[sessionId] = copy.deepcopy(record)
+        if not record:
+            return {"ok": False, "error": "portalSessionNotFound", "portalSessionId": sessionId}
+        return {"ok": True, "session": copy.deepcopy(record)}
+
+    def listSessions(self, filters: dict[str, Any] | None = None) -> dict[str, Any]:
+        self._loadSessions()
+        filters = filters or {}
+        records = list(self._sessions.values())
+        for key in ("caseId", "conversationId", "connectorId", "provider", "status"):
+            value = str(filters.get(key, "") or "")
+            if value:
+                records = [record for record in records if str(record.get(key, "") or "") == value]
+        records.sort(key=lambda item: (int(item.get("updatedAt", 0) or 0), str(item.get("portalSessionId", ""))), reverse=True)
+        limit = _limit(filters.get("limit", 100))
+        return {"ok": True, "sessions": [copy.deepcopy(record) for record in records[:limit]], "count": min(len(records), limit)}
+
+    def createAction(self, payload: dict[str, Any]) -> dict[str, Any]:
+        now = int(time.time())
+        actionId = str(payload.get("portalActionId", payload.get("actionId", "")) or _stableId("portalAction", payload))
+        record = _actionFromPayload({**payload, "portalActionId": actionId}, createdAt=now, updatedAt=now)
+        self._saveAction(record)
+        return {"ok": True, "action": copy.deepcopy(record)}
+
+    def getAction(self, actionId: str) -> dict[str, Any]:
+        actionId = str(actionId or "")
+        record = self._actions.get(actionId)
+        if record is None and self._backingEnabled() and hasattr(self.backing, "fetchPortalAction"):
+            record = self.backing.fetchPortalAction(actionId)
+            if record:
+                self._actions[actionId] = copy.deepcopy(record)
+        if not record:
+            return {"ok": False, "error": "portalActionNotFound", "portalActionId": actionId}
+        return {"ok": True, "action": copy.deepcopy(record)}
+
+    def listActions(self, filters: dict[str, Any] | None = None) -> dict[str, Any]:
+        self._loadActions()
+        filters = filters or {}
+        records = list(self._actions.values())
+        for key in ("caseId", "conversationId", "portalSessionId", "connectorId", "provider", "status", "kind"):
+            value = str(filters.get(key, "") or "")
+            if value:
+                records = [record for record in records if str(record.get(key, "") or "") == value]
+        records.sort(key=lambda item: (int(item.get("updatedAt", 0) or 0), str(item.get("portalActionId", ""))), reverse=True)
+        limit = _limit(filters.get("limit", 100))
+        return {"ok": True, "actions": [copy.deepcopy(record) for record in records[:limit]], "count": min(len(records), limit)}
+
+    def updateAction(self, actionId: str, updates: dict[str, Any]) -> dict[str, Any]:
+        current = self.getAction(actionId)
+        if not current.get("ok"):
+            return current
+        record = _actionFromPayload(
+            {**current["action"], **updates, "portalActionId": actionId},
+            createdAt=int(current["action"].get("createdAt", int(time.time())) or int(time.time())),
+            updatedAt=int(time.time()),
+        )
+        self._saveAction(record)
+        return {"ok": True, "action": copy.deepcopy(record)}
+
+    def appendProof(self, actionId: str, proof: dict[str, Any]) -> dict[str, Any]:
+        current = self.getAction(actionId)
+        if not current.get("ok"):
+            return current
+        action = current["action"]
+        proofs = action.get("proofs", []) if isinstance(action.get("proofs"), list) else []
+        updated = self.updateAction(actionId, {"proofs": [*proofs, _proof(proof)]})
+        if updated.get("ok"):
+            updated["proof"] = updated["action"].get("proofs", [])[-1]
+        return updated
+
+    def _saveSession(self, record: dict[str, Any]) -> None:
+        sessionId = str(record.get("portalSessionId", "") or "")
+        if not sessionId:
+            return
+        self._sessions[sessionId] = copy.deepcopy(record)
+        if self._backingEnabled() and hasattr(self.backing, "upsertPortalSession"):
+            self.backing.upsertPortalSession(record)
+
+    def _saveAction(self, record: dict[str, Any]) -> None:
+        actionId = str(record.get("portalActionId", "") or "")
+        if not actionId:
+            return
+        self._actions[actionId] = copy.deepcopy(record)
+        if self._backingEnabled() and hasattr(self.backing, "upsertPortalAction"):
+            self.backing.upsertPortalAction(record)
+
+    def _loadSessions(self) -> None:
+        if self._backingEnabled() and hasattr(self.backing, "listPortalSessions"):
+            for record in self.backing.listPortalSessions():
+                if record.get("portalSessionId"):
+                    self._sessions[str(record["portalSessionId"])] = copy.deepcopy(record)
+
+    def _loadActions(self) -> None:
+        if self._backingEnabled() and hasattr(self.backing, "listPortalActions"):
+            for record in self.backing.listPortalActions():
+                if record.get("portalActionId"):
+                    self._actions[str(record["portalActionId"])] = copy.deepcopy(record)
+
+    def _backingEnabled(self) -> bool:
+        return bool(self.backing is not None and getattr(self.backing, "enabled", True))
+
+
+def _sessionFromPayload(payload: dict[str, Any], *, createdAt: int, updatedAt: int) -> dict[str, Any]:
+    return {
+        "portalSessionId": str(payload.get("portalSessionId", payload.get("sessionId", "")) or ""),
+        "caseId": str(payload.get("caseId", "") or ""),
+        "conversationId": str(payload.get("conversationId", "") or ""),
+        "connectorId": str(payload.get("connectorId", "") or ""),
+        "provider": str(payload.get("provider", "") or ""),
+        "baseUrl": str(payload.get("baseUrl", payload.get("url", "")) or ""),
+        "status": _choice(payload.get("status", "active"), PORTAL_SESSION_STATUSES, "active"),
+        "credentialRef": str(payload.get("credentialRef", "") or ""),
+        "storageStateRef": str(payload.get("storageStateRef", "") or ""),
+        "mfa": payload.get("mfa", {}) if isinstance(payload.get("mfa"), dict) else {},
+        "meta": payload.get("meta", {}) if isinstance(payload.get("meta"), dict) else {},
+        "createdAt": int(createdAt),
+        "updatedAt": int(updatedAt),
+    }
+
+
+def _actionFromPayload(payload: dict[str, Any], *, createdAt: int, updatedAt: int) -> dict[str, Any]:
+    return {
+        "portalActionId": str(payload.get("portalActionId", payload.get("actionId", "")) or ""),
+        "portalSessionId": str(payload.get("portalSessionId", payload.get("sessionId", "")) or ""),
+        "templateId": str(payload.get("templateId", "") or ""),
+        "caseId": str(payload.get("caseId", "") or ""),
+        "conversationId": str(payload.get("conversationId", "") or ""),
+        "connectorId": str(payload.get("connectorId", "") or ""),
+        "provider": str(payload.get("provider", "") or ""),
+        "kind": str(payload.get("kind", payload.get("action", "submitForm")) or "submitForm"),
+        "targetUrl": str(payload.get("targetUrl", payload.get("url", "")) or ""),
+        "status": _choice(payload.get("status", "queued"), PORTAL_ACTION_STATUSES, "queued"),
+        "steps": [_step(item) for item in payload.get("steps", []) if isinstance(item, dict)],
+        "inputs": payload.get("inputs", {}) if isinstance(payload.get("inputs"), dict) else {},
+        "proofs": [_proof(item) for item in payload.get("proofs", []) if isinstance(item, dict)],
+        "result": payload.get("result", {}) if isinstance(payload.get("result"), dict) else {},
+        "error": str(payload.get("error", "") or ""),
+        "requiresProxy": bool(payload.get("requiresProxy", False)),
+        "meta": payload.get("meta", {}) if isinstance(payload.get("meta"), dict) else {},
+        "createdAt": int(createdAt),
+        "updatedAt": int(updatedAt),
+    }
+
+
+def _step(payload: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "stepId": str(payload.get("stepId", "") or _stableId("portalStep", payload)),
+        "label": str(payload.get("label", payload.get("action", "step")) or "step"),
+        "action": str(payload.get("action", "") or ""),
+        "selector": str(payload.get("selector", "") or ""),
+        "valueKey": str(payload.get("valueKey", "") or ""),
+        "status": str(payload.get("status", "pending") or "pending"),
+        "proofRequired": bool(payload.get("proofRequired", False)),
+        "meta": payload.get("meta", {}) if isinstance(payload.get("meta"), dict) else {},
+    }
+
+
+def _proof(payload: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "proofId": str(payload.get("proofId", "") or _stableId("portalProof", payload)),
+        "kind": str(payload.get("kind", "screenshot") or "screenshot"),
+        "status": str(payload.get("status", "captured") or "captured"),
+        "label": str(payload.get("label", "") or ""),
+        "artifactRef": str(payload.get("artifactRef", payload.get("artifactId", "")) or ""),
+        "sourceUrl": str(payload.get("sourceUrl", "") or ""),
+        "hash": str(payload.get("hash", payload.get("sha256", "")) or ""),
+        "createdAt": int(payload.get("createdAt", int(time.time())) or int(time.time())),
+        "meta": payload.get("meta", {}) if isinstance(payload.get("meta"), dict) else {},
+    }
+
+
+def _choice(value: Any, allowed: set[str], default: str) -> str:
+    clean = str(value or default)
+    return clean if clean in allowed else default
+
+
+def _limit(value: Any) -> int:
+    try:
+        return max(1, min(int(value or 100), 500))
+    except Exception:
+        return 100
+
+
+def _stableId(prefix: str, payload: dict[str, Any]) -> str:
+    digest = hashlib.sha256(json.dumps(payload, ensure_ascii=True, sort_keys=True).encode("utf-8")).hexdigest()
+    return f"{prefix}_{digest[:24]}"