patchr 0.1.0__py3-none-any.whl

picux/storage/channels.py

@@ -0,0 +1,476 @@
+from __future__ import annotations
+
+import copy
+import hashlib
+import json
+import time
+from typing import Any
+
+
+THREAD_STATUSES = {"active", "closed", "archived"}
+TOUCHPOINT_DIRECTIONS = {"inbound", "outbound", "internal"}
+TOUCHPOINT_STATUSES = {"received", "queued", "sent", "delivered", "failed", "needsInput", "pending"}
+ACTION_STATUSES = {"queued", "running", "succeeded", "failed", "blocked", "needsInput"}
+
+
+class ChannelBook:
+    """Persistent conversation state across channel providers and touchpoints."""
+
+    def __init__(self, *, backing: Any | None = None) -> None:
+        self.backing = backing
+        self._threads: dict[str, dict[str, Any]] = {}
+        self._touchpoints: dict[str, dict[str, Any]] = {}
+        self._actions: dict[str, dict[str, Any]] = {}
+        self._callbacks: dict[str, dict[str, Any]] = {}
+
+    def createThread(self, payload: dict[str, Any]) -> dict[str, Any]:
+        now = int(time.time())
+        threadId = str(payload.get("threadId", "") or _stableId("thread", _threadIdentity(payload)))
+        current = self.getThread(threadId)
+        createdAt = int(current.get("thread", {}).get("createdAt", now) if current.get("ok") else now)
+        record = _threadFromPayload({**payload, "threadId": threadId}, createdAt=createdAt, updatedAt=now)
+        self._saveThread(record)
+        return {"ok": True, "thread": copy.deepcopy(record)}
+
+    def getThread(self, threadId: str) -> dict[str, Any]:
+        threadId = str(threadId or "")
+        record = self._threads.get(threadId)
+        if record is None and self._backingEnabled() and hasattr(self.backing, "fetchChannelThread"):
+            record = self.backing.fetchChannelThread(threadId)
+            if record:
+                self._threads[threadId] = copy.deepcopy(record)
+        if not record:
+            return {"ok": False, "error": "channelThreadNotFound", "threadId": threadId}
+        return {"ok": True, "thread": copy.deepcopy(record)}
+
+    def listThreads(self, filters: dict[str, Any] | None = None) -> dict[str, Any]:
+        self._loadThreads()
+        filters = filters or {}
+        records = list(self._threads.values())
+        for key in ("caseId", "conversationId", "channel", "provider", "connectorId", "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("threadId", ""))), reverse=True)
+        limit = _limit(filters.get("limit", 100))
+        return {"ok": True, "threads": [copy.deepcopy(record) for record in records[:limit]], "count": min(len(records), limit)}
+
+    def updateThread(self, threadId: str, updates: dict[str, Any]) -> dict[str, Any]:
+        current = self.getThread(threadId)
+        if not current.get("ok"):
+            return current
+        merged = {**current["thread"], **updates, "threadId": threadId}
+        record = _threadFromPayload(
+            merged,
+            createdAt=int(current["thread"].get("createdAt", int(time.time())) or int(time.time())),
+            updatedAt=int(time.time()),
+        )
+        self._saveThread(record)
+        return {"ok": True, "thread": copy.deepcopy(record)}
+
+    def recordTouchpoint(self, payload: dict[str, Any]) -> dict[str, Any]:
+        now = int(time.time())
+        thread = self._ensureThread(payload)
+        threadRecord = thread.get("thread", {}) if thread.get("ok") else {}
+        touchpointId = str(payload.get("touchpointId", "") or _stableId("touch", {**payload, "threadId": threadRecord.get("threadId", "")}))
+        record = _touchpointFromPayload({**payload, "touchpointId": touchpointId, **_threadRefs(threadRecord, payload)}, createdAt=now)
+        self._saveTouchpoint(record)
+        if threadRecord:
+            self._updateThreadState(threadRecord, record)
+        return {"ok": True, "touchpoint": copy.deepcopy(record), "thread": self.getThread(record["threadId"]).get("thread", threadRecord)}
+
+    def getTouchpoint(self, touchpointId: str) -> dict[str, Any]:
+        touchpointId = str(touchpointId or "")
+        record = self._touchpoints.get(touchpointId)
+        if record is None and self._backingEnabled() and hasattr(self.backing, "fetchTouchpoint"):
+            record = self.backing.fetchTouchpoint(touchpointId)
+            if record:
+                self._touchpoints[touchpointId] = copy.deepcopy(record)
+        if not record:
+            return {"ok": False, "error": "touchpointNotFound", "touchpointId": touchpointId}
+        return {"ok": True, "touchpoint": copy.deepcopy(record)}
+
+    def listTouchpoints(self, filters: dict[str, Any] | None = None) -> dict[str, Any]:
+        self._loadTouchpoints(filters or {})
+        filters = filters or {}
+        records = list(self._touchpoints.values())
+        for key in ("threadId", "caseId", "conversationId", "channel", "provider", "connectorId", "direction", "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("createdAt", 0) or 0), str(item.get("touchpointId", ""))), reverse=True)
+        limit = _limit(filters.get("limit", 100))
+        return {"ok": True, "touchpoints": [copy.deepcopy(record) for record in records[:limit]], "count": min(len(records), limit)}
+
+    def createProviderAction(self, payload: dict[str, Any]) -> dict[str, Any]:
+        now = int(time.time())
+        actionId = str(payload.get("actionId", "") or _stableId("action", payload))
+        record = _actionFromPayload({**payload, "actionId": actionId}, createdAt=now, updatedAt=now)
+        self._saveAction(record)
+        touchpoint = {}
+        if record.get("threadId") or record.get("conversationId") or record.get("caseId"):
+            touchpoint = self.recordTouchpoint(
+                {
+                    "threadId": record.get("threadId", ""),
+                    "caseId": record.get("caseId", ""),
+                    "conversationId": record.get("conversationId", ""),
+                    "channel": record.get("channel", "bridge"),
+                    "provider": record.get("provider", ""),
+                    "connectorId": record.get("connectorId", ""),
+                    "sessionId": record.get("sessionId", ""),
+                    "direction": "outbound",
+                    "status": "queued",
+                    "text": str(record.get("action", "") or ""),
+                    "meta": {"actionId": actionId, "resource": record.get("resource", "")},
+                }
+            ).get("touchpoint", {})
+        result = {"ok": True, "action": copy.deepcopy(record)}
+        if touchpoint:
+            result["touchpoint"] = touchpoint
+        return result
+
+    def getProviderAction(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, "fetchProviderAction"):
+            record = self.backing.fetchProviderAction(actionId)
+            if record:
+                self._actions[actionId] = copy.deepcopy(record)
+        if not record:
+            return {"ok": False, "error": "providerActionNotFound", "actionId": actionId}
+        return {"ok": True, "action": copy.deepcopy(record)}
+
+    def listProviderActions(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", "threadId", "connectorId", "sessionId", "status", "channel", "provider"):
+            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("actionId", ""))), 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 updateProviderAction(self, actionId: str, updates: dict[str, Any]) -> dict[str, Any]:
+        current = self.getProviderAction(actionId)
+        if not current.get("ok"):
+            return current
+        record = _actionFromPayload(
+            {**current["action"], **updates, "actionId": 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 ingestProviderCallback(self, payload: dict[str, Any]) -> dict[str, Any]:
+        now = int(time.time())
+        callbackId = str(payload.get("callbackId", "") or _stableId("callback", payload))
+        callback = _callbackFromPayload({**payload, "callbackId": callbackId}, receivedAt=now)
+        self._saveCallback(callback)
+        touchPayload = _touchpointPayloadFromCallback(callback)
+        touchpoint = self.recordTouchpoint(touchPayload) if touchPayload else {}
+        result = {"ok": True, "callback": copy.deepcopy(callback)}
+        if touchpoint.get("ok"):
+            result["touchpoint"] = touchpoint["touchpoint"]
+            result["thread"] = touchpoint.get("thread", {})
+        return result
+
+    def listProviderCallbacks(self, filters: dict[str, Any] | None = None) -> dict[str, Any]:
+        self._loadCallbacks()
+        filters = filters or {}
+        records = list(self._callbacks.values())
+        for key in ("caseId", "conversationId", "threadId", "connectorId", "sessionId", "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("receivedAt", 0) or 0), str(item.get("callbackId", ""))), reverse=True)
+        limit = _limit(filters.get("limit", 100))
+        return {"ok": True, "callbacks": [copy.deepcopy(record) for record in records[:limit]], "count": min(len(records), limit)}
+
+    def _ensureThread(self, payload: dict[str, Any]) -> dict[str, Any]:
+        threadId = str(payload.get("threadId", "") or "")
+        if threadId:
+            found = self.getThread(threadId)
+            if found.get("ok"):
+                return found
+        refs = _threadIdentity(payload)
+        found = self.findThread(refs)
+        if found.get("ok"):
+            return found
+        return self.createThread(refs)
+
+    def findThread(self, refs: dict[str, Any]) -> dict[str, Any]:
+        self._loadThreads()
+        for record in self._threads.values():
+            if _threadMatches(record, refs):
+                return {"ok": True, "thread": copy.deepcopy(record)}
+        if self._backingEnabled() and hasattr(self.backing, "findChannelThread"):
+            record = self.backing.findChannelThread(refs)
+            if record:
+                self._threads[str(record.get("threadId", "") or "")] = copy.deepcopy(record)
+                return {"ok": True, "thread": copy.deepcopy(record)}
+        return {"ok": False, "error": "channelThreadNotFound"}
+
+    def _updateThreadState(self, thread: dict[str, Any], touchpoint: dict[str, Any]) -> None:
+        state = thread.get("state", {}) if isinstance(thread.get("state"), dict) else {}
+        count = int(state.get("touchpointCount", 0) or 0) + 1
+        now = int(touchpoint.get("createdAt", int(time.time())) or int(time.time()))
+        direction = str(touchpoint.get("direction", "") or "")
+        nextState = {
+            **state,
+            "touchpointCount": count,
+            "lastTouchpointId": str(touchpoint.get("touchpointId", "") or ""),
+            "lastStatus": str(touchpoint.get("status", "") or ""),
+            "lastAt": now,
+        }
+        if direction == "inbound":
+            nextState["lastInboundAt"] = now
+        if direction == "outbound":
+            nextState["lastOutboundAt"] = now
+        self.updateThread(str(thread.get("threadId", "") or ""), {"state": nextState})
+
+    def _saveThread(self, record: dict[str, Any]) -> None:
+        threadId = str(record.get("threadId", "") or "")
+        if not threadId:
+            return
+        self._threads[threadId] = copy.deepcopy(record)
+        if self._backingEnabled() and hasattr(self.backing, "upsertChannelThread"):
+            self.backing.upsertChannelThread(record)
+
+    def _saveTouchpoint(self, record: dict[str, Any]) -> None:
+        touchpointId = str(record.get("touchpointId", "") or "")
+        if not touchpointId:
+            return
+        self._touchpoints[touchpointId] = copy.deepcopy(record)
+        if self._backingEnabled() and hasattr(self.backing, "upsertTouchpoint"):
+            self.backing.upsertTouchpoint(record)
+
+    def _saveAction(self, record: dict[str, Any]) -> None:
+        actionId = str(record.get("actionId", "") or "")
+        if not actionId:
+            return
+        self._actions[actionId] = copy.deepcopy(record)
+        if self._backingEnabled() and hasattr(self.backing, "upsertProviderAction"):
+            self.backing.upsertProviderAction(record)
+
+    def _saveCallback(self, record: dict[str, Any]) -> None:
+        callbackId = str(record.get("callbackId", "") or "")
+        if not callbackId:
+            return
+        self._callbacks[callbackId] = copy.deepcopy(record)
+        if self._backingEnabled() and hasattr(self.backing, "upsertProviderCallback"):
+            self.backing.upsertProviderCallback(record)
+
+    def _loadThreads(self) -> None:
+        if self._backingEnabled() and hasattr(self.backing, "listChannelThreads"):
+            for record in self.backing.listChannelThreads():
+                if record.get("threadId"):
+                    self._threads[str(record["threadId"])] = copy.deepcopy(record)
+
+    def _loadTouchpoints(self, filters: dict[str, Any]) -> None:
+        if self._backingEnabled() and hasattr(self.backing, "listTouchpoints"):
+            for record in self.backing.listTouchpoints(**_backingFilters(filters)):
+                if record.get("touchpointId"):
+                    self._touchpoints[str(record["touchpointId"])] = copy.deepcopy(record)
+
+    def _loadActions(self) -> None:
+        if self._backingEnabled() and hasattr(self.backing, "listProviderActions"):
+            for record in self.backing.listProviderActions():
+                if record.get("actionId"):
+                    self._actions[str(record["actionId"])] = copy.deepcopy(record)
+
+    def _loadCallbacks(self) -> None:
+        if self._backingEnabled() and hasattr(self.backing, "listProviderCallbacks"):
+            for record in self.backing.listProviderCallbacks():
+                if record.get("callbackId"):
+                    self._callbacks[str(record["callbackId"])] = copy.deepcopy(record)
+
+    def _backingEnabled(self) -> bool:
+        return bool(self.backing is not None and getattr(self.backing, "enabled", True))
+
+
+def _threadFromPayload(payload: dict[str, Any], *, createdAt: int, updatedAt: int) -> dict[str, Any]:
+    return {
+        "threadId": str(payload.get("threadId", "") or ""),
+        "caseId": str(payload.get("caseId", "") or ""),
+        "conversationId": str(payload.get("conversationId", "") or ""),
+        "channel": str(payload.get("channel", "api") or "api"),
+        "provider": str(payload.get("provider", "") or ""),
+        "providerThreadId": str(payload.get("providerThreadId", payload.get("threadRef", "")) or ""),
+        "connectorId": str(payload.get("connectorId", "") or ""),
+        "sessionId": str(payload.get("sessionId", "") or ""),
+        "subject": str(payload.get("subject", "") or ""),
+        "participants": _cleanList(payload.get("participants", [])),
+        "status": _choice(payload.get("status", "active"), THREAD_STATUSES, "active"),
+        "state": payload.get("state", {}) if isinstance(payload.get("state"), dict) else {},
+        "meta": payload.get("meta", {}) if isinstance(payload.get("meta"), dict) else {},
+        "createdAt": int(createdAt),
+        "updatedAt": int(updatedAt),
+    }
+
+
+def _touchpointFromPayload(payload: dict[str, Any], *, createdAt: int) -> dict[str, Any]:
+    return {
+        "touchpointId": str(payload.get("touchpointId", "") or ""),
+        "threadId": str(payload.get("threadId", "") or ""),
+        "caseId": str(payload.get("caseId", "") or ""),
+        "conversationId": str(payload.get("conversationId", "") or ""),
+        "direction": _choice(payload.get("direction", "inbound"), TOUCHPOINT_DIRECTIONS, "inbound"),
+        "channel": str(payload.get("channel", "api") or "api"),
+        "provider": str(payload.get("provider", "") or ""),
+        "connectorId": str(payload.get("connectorId", "") or ""),
+        "sessionId": str(payload.get("sessionId", "") or ""),
+        "providerMessageId": str(payload.get("providerMessageId", payload.get("messageId", "")) or ""),
+        "from": str(payload.get("from", payload.get("sender", "")) or ""),
+        "to": _cleanList(payload.get("to", payload.get("recipients", []))),
+        "text": str(payload.get("text", payload.get("body", payload.get("message", ""))) or ""),
+        "status": _choice(payload.get("status", "received"), TOUCHPOINT_STATUSES, "received"),
+        "artifactRefs": _cleanList(payload.get("artifactRefs", payload.get("artifacts", []))),
+        "transcript": payload.get("transcript", []) if isinstance(payload.get("transcript"), list) else [],
+        "meta": payload.get("meta", {}) if isinstance(payload.get("meta"), dict) else {},
+        "createdAt": int(createdAt),
+    }
+
+
+def _actionFromPayload(payload: dict[str, Any], *, createdAt: int, updatedAt: int) -> dict[str, Any]:
+    return {
+        "actionId": str(payload.get("actionId", "") or ""),
+        "caseId": str(payload.get("caseId", "") or ""),
+        "conversationId": str(payload.get("conversationId", "") or ""),
+        "threadId": str(payload.get("threadId", "") or ""),
+        "connectorId": str(payload.get("connectorId", "") or ""),
+        "sessionId": str(payload.get("sessionId", "") or ""),
+        "channel": str(payload.get("channel", "bridge") or "bridge"),
+        "provider": str(payload.get("provider", "") or ""),
+        "action": str(payload.get("action", payload.get("kind", "send")) or "send"),
+        "resource": str(payload.get("resource", "") or ""),
+        "status": _choice(payload.get("status", "queued"), ACTION_STATUSES, "queued"),
+        "request": payload.get("request", {}) if isinstance(payload.get("request"), dict) else {},
+        "response": payload.get("response", {}) if isinstance(payload.get("response"), dict) else {},
+        "error": str(payload.get("error", "") or ""),
+        "proofRefs": _cleanList(payload.get("proofRefs", [])),
+        "meta": payload.get("meta", {}) if isinstance(payload.get("meta"), dict) else {},
+        "createdAt": int(createdAt),
+        "updatedAt": int(updatedAt),
+    }
+
+
+def _callbackFromPayload(payload: dict[str, Any], *, receivedAt: int) -> dict[str, Any]:
+    raw = payload.get("payload", payload.get("body", {}))
+    return {
+        "callbackId": str(payload.get("callbackId", "") or ""),
+        "caseId": str(payload.get("caseId", "") or ""),
+        "conversationId": str(payload.get("conversationId", "") or ""),
+        "threadId": str(payload.get("threadId", "") or ""),
+        "connectorId": str(payload.get("connectorId", "") or ""),
+        "sessionId": str(payload.get("sessionId", "") or ""),
+        "provider": str(payload.get("provider", "") or ""),
+        "providerEventId": str(payload.get("providerEventId", payload.get("eventId", "")) or ""),
+        "status": str(payload.get("status", "received") or "received"),
+        "payload": raw if isinstance(raw, dict) else {"value": raw},
+        "receivedAt": int(receivedAt),
+    }
+
+
+def _touchpointPayloadFromCallback(callback: dict[str, Any]) -> dict[str, Any]:
+    payload = callback.get("payload", {}) if isinstance(callback.get("payload"), dict) else {}
+    text = str(payload.get("text", payload.get("body", payload.get("message", ""))) or "")
+    providerThreadId = str(payload.get("threadId", payload.get("providerThreadId", "")) or "")
+    return {
+        "threadId": str(callback.get("threadId", "") or ""),
+        "caseId": str(callback.get("caseId", "") or payload.get("caseId", "") or ""),
+        "conversationId": str(callback.get("conversationId", "") or payload.get("conversationId", "") or ""),
+        "channel": str(payload.get("channel", payload.get("type", "callback")) or "callback"),
+        "provider": str(callback.get("provider", payload.get("provider", "")) or ""),
+        "providerThreadId": providerThreadId,
+        "connectorId": str(callback.get("connectorId", "") or ""),
+        "sessionId": str(callback.get("sessionId", "") or ""),
+        "providerMessageId": str(payload.get("messageId", payload.get("id", callback.get("providerEventId", ""))) or ""),
+        "direction": str(payload.get("direction", "inbound") or "inbound"),
+        "status": str(payload.get("status", "received") or "received"),
+        "from": str(payload.get("from", payload.get("sender", "")) or ""),
+        "to": payload.get("to", payload.get("recipients", [])),
+        "text": text,
+        "artifactRefs": payload.get("artifactRefs", []),
+        "transcript": payload.get("transcript", []),
+        "meta": {"callbackId": callback.get("callbackId", ""), "providerEventId": callback.get("providerEventId", "")},
+    }
+
+
+def _threadIdentity(payload: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "caseId": str(payload.get("caseId", "") or ""),
+        "conversationId": str(payload.get("conversationId", "") or ""),
+        "channel": str(payload.get("channel", "api") or "api"),
+        "provider": str(payload.get("provider", "") or ""),
+        "providerThreadId": str(payload.get("providerThreadId", payload.get("threadRef", "")) or ""),
+        "connectorId": str(payload.get("connectorId", "") or ""),
+        "sessionId": str(payload.get("sessionId", "") or ""),
+        "subject": str(payload.get("subject", "") or ""),
+        "participants": _cleanList(payload.get("participants", [])),
+        "meta": payload.get("meta", {}) if isinstance(payload.get("meta"), dict) else {},
+    }
+
+
+def _threadRefs(thread: dict[str, Any], payload: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "threadId": str(thread.get("threadId", payload.get("threadId", "")) or ""),
+        "caseId": str(payload.get("caseId", thread.get("caseId", "")) or ""),
+        "conversationId": str(payload.get("conversationId", thread.get("conversationId", "")) or ""),
+        "channel": str(payload.get("channel", thread.get("channel", "api")) or "api"),
+        "provider": str(payload.get("provider", thread.get("provider", "")) or ""),
+        "connectorId": str(payload.get("connectorId", thread.get("connectorId", "")) or ""),
+        "sessionId": str(payload.get("sessionId", thread.get("sessionId", "")) or ""),
+    }
+
+
+def _threadMatches(record: dict[str, Any], refs: dict[str, Any]) -> bool:
+    providerThreadId = str(refs.get("providerThreadId", "") or "")
+    if providerThreadId and str(record.get("providerThreadId", "") or "") == providerThreadId:
+        return True
+    conversationId = str(refs.get("conversationId", "") or "")
+    channel = str(refs.get("channel", "") or "")
+    provider = str(refs.get("provider", "") or "")
+    if conversationId and conversationId == str(record.get("conversationId", "") or ""):
+        if not channel or channel == str(record.get("channel", "") or ""):
+            if not provider or provider == str(record.get("provider", "") or ""):
+                return True
+    caseId = str(refs.get("caseId", "") or "")
+    if caseId and caseId == str(record.get("caseId", "") or "") and channel and channel == str(record.get("channel", "") or ""):
+        return True
+    return False
+
+
+def _choice(value: Any, allowed: set[str], default: str) -> str:
+    clean = str(value or default)
+    return clean if clean in allowed else default
+
+
+def _cleanList(value: Any) -> list[Any]:
+    if isinstance(value, list):
+        return [item for item in value if item not in {"", None}]
+    if value in {"", None}:
+        return []
+    return [value]
+
+
+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]}"
+
+
+def _backingFilters(filters: dict[str, Any]) -> dict[str, Any]:
+    out: dict[str, Any] = {}
+    for key in ("threadId", "caseId", "conversationId", "limit"):
+        if filters.get(key):
+            out[key] = filters[key]
+    return out