patchr 0.1.0__py3-none-any.whl

picux/storage/cases.py

@@ -0,0 +1,440 @@
+from __future__ import annotations
+
+import copy
+import hashlib
+import json
+import time
+from typing import Any
+
+
+CASE_STATUSES = {"open", "inReview", "awaitingStakeholder", "awaitingProxy", "resolved", "closed", "archived"}
+DEADLINE_STATUSES = {"open", "met", "missed", "canceled"}
+STAKEHOLDER_ROLES = {"claimant", "merchant", "carrier", "bank", "advisor", "reviewer", "proxy", "other"}
+NOTE_VISIBILITIES = {"internal", "client", "shared", "private"}
+ACTION_STATUSES = {"open", "inProgress", "blocked", "done", "canceled"}
+
+
+class CaseBook:
+    """Formal case workspace for disputes, audits, evidence bundles, and collaboration."""
+
+    def __init__(self, *, backing: Any | None = None) -> None:
+        self.backing = backing
+        self._cases: dict[str, dict[str, Any]] = {}
+        self._events: dict[str, dict[str, Any]] = {}
+
+    def createCase(self, payload: dict[str, Any]) -> dict[str, Any]:
+        now = int(time.time())
+        caseId = str(payload.get("caseId", "") or _stableId("case", _caseIdentity(payload)))
+        current = self.getCase(caseId)
+        createdAt = int(current.get("case", {}).get("createdAt", now) if current.get("ok") else now)
+        record = _caseFromPayload({**payload, "caseId": caseId}, createdAt=createdAt, updatedAt=now)
+        self._saveCase(record)
+        if not current.get("ok"):
+            self.addEvent(caseId, {"type": "case.created", "label": "Case workspace created", "actor": str(payload.get("actor", "picux") or "picux")})
+        return {"ok": True, "case": copy.deepcopy(record)}
+
+    def getCase(self, caseId: str) -> dict[str, Any]:
+        caseId = str(caseId or "")
+        record = self._cases.get(caseId)
+        if record is None and self._backingEnabled() and hasattr(self.backing, "fetchCaseWorkspace"):
+            record = self.backing.fetchCaseWorkspace(caseId)
+            if record:
+                self._cases[caseId] = copy.deepcopy(record)
+        if not record:
+            return {"ok": False, "error": "caseNotFound", "caseId": caseId}
+        return {"ok": True, "case": copy.deepcopy(record)}
+
+    def listCases(self, filters: dict[str, Any] | None = None) -> dict[str, Any]:
+        self._loadCases()
+        filters = filters or {}
+        records = list(self._cases.values())
+        for key in ("status", "ownerId", "conversationId"):
+            value = str(filters.get(key, "") or "")
+            if value:
+                records = [record for record in records if str(record.get(key, "") or "") == value]
+        domain = str(filters.get("domain", "") or "")
+        if domain:
+            records = [record for record in records if domain in record.get("domains", [])]
+        records.sort(key=lambda item: (int(item.get("updatedAt", 0) or 0), str(item.get("caseId", ""))), reverse=True)
+        limit = _limit(filters.get("limit", 100))
+        return {"ok": True, "cases": [copy.deepcopy(record) for record in records[:limit]], "count": min(len(records), limit)}
+
+    def updateCase(self, caseId: str, updates: dict[str, Any]) -> dict[str, Any]:
+        current = self.getCase(caseId)
+        if not current.get("ok"):
+            return current
+        record = _caseFromPayload(
+            {**current["case"], **updates, "caseId": caseId},
+            createdAt=int(current["case"].get("createdAt", int(time.time())) or int(time.time())),
+            updatedAt=int(time.time()),
+        )
+        self._saveCase(record)
+        self.addEvent(caseId, {"type": "case.updated", "label": "Case workspace updated", "actor": str(updates.get("actor", "picux") or "picux")})
+        return {"ok": True, "case": copy.deepcopy(record)}
+
+    def addStakeholder(self, caseId: str, payload: dict[str, Any]) -> dict[str, Any]:
+        current = self.getCase(caseId)
+        if not current.get("ok"):
+            return current
+        stakeholder = _stakeholder(payload)
+        if not stakeholder.get("stakeholderId"):
+            stakeholder["stakeholderId"] = _stableId("stake", {"caseId": caseId, "name": stakeholder.get("name", ""), "role": stakeholder.get("role", "")})
+        case = current["case"]
+        stakeholders = [item for item in case.get("stakeholders", []) if isinstance(item, dict) and item.get("stakeholderId") != stakeholder["stakeholderId"]]
+        updated = self.updateCase(caseId, {"stakeholders": [*stakeholders, stakeholder]})
+        if updated.get("ok"):
+            updated["stakeholder"] = stakeholder
+            self.addEvent(caseId, {"type": "case.stakeholder.added", "label": f"Stakeholder added: {stakeholder.get('name', stakeholder.get('role', 'stakeholder'))}", "actor": "picux", "payload": stakeholder})
+        return updated
+
+    def addDeadline(self, caseId: str, payload: dict[str, Any]) -> dict[str, Any]:
+        current = self.getCase(caseId)
+        if not current.get("ok"):
+            return current
+        deadline = _deadline(payload)
+        if not deadline.get("deadlineId"):
+            deadline["deadlineId"] = _stableId("due", {"caseId": caseId, "label": deadline.get("label", ""), "dueAt": deadline.get("dueAt", "")})
+        case = current["case"]
+        deadlines = [item for item in case.get("deadlines", []) if isinstance(item, dict) and item.get("deadlineId") != deadline["deadlineId"]]
+        updated = self.updateCase(caseId, {"deadlines": [*deadlines, deadline]})
+        if updated.get("ok"):
+            updated["deadline"] = deadline
+            self.addEvent(caseId, {"type": "case.deadline.added", "label": f"Deadline added: {deadline.get('label', 'deadline')}", "actor": "picux", "payload": deadline})
+        return updated
+
+    def addAction(self, caseId: str, payload: dict[str, Any]) -> dict[str, Any]:
+        current = self.getCase(caseId)
+        if not current.get("ok"):
+            return current
+        action = _caseAction({**payload, "caseId": caseId})
+        if not action.get("actionId"):
+            action["actionId"] = _stableId("caseAction", {"caseId": caseId, "title": action.get("title", ""), "owner": action.get("owner", ""), "dueAt": action.get("dueAt", "")})
+        case = current["case"]
+        actions = [item for item in case.get("actions", []) if isinstance(item, dict) and item.get("actionId") != action["actionId"]]
+        updated = self.updateCase(caseId, {"actions": [*actions, action], "actor": str(payload.get("actor", action.get("owner", "picux")) or "picux")})
+        if updated.get("ok"):
+            updated["action"] = action
+            self.addEvent(caseId, {"type": "case.action.added", "label": f"Action added: {action.get('title', action.get('actionId', 'action'))}", "actor": str(payload.get("actor", "picux") or "picux"), "payload": action})
+        return updated
+
+    def updateAction(self, caseId: str, actionId: str, updates: dict[str, Any]) -> dict[str, Any]:
+        current = self.getCase(caseId)
+        if not current.get("ok"):
+            return current
+        actionId = str(actionId or "")
+        case = current["case"]
+        actions = [item for item in case.get("actions", []) if isinstance(item, dict)]
+        found = next((item for item in actions if str(item.get("actionId", "") or "") == actionId), None)
+        if not found:
+            return {"ok": False, "error": "caseActionNotFound", "caseId": caseId, "actionId": actionId}
+        nextAction = _caseAction({**found, **updates, "caseId": caseId, "actionId": actionId, "updatedAt": int(time.time())})
+        merged = [nextAction if str(item.get("actionId", "") or "") == actionId else item for item in actions]
+        updated = self.updateCase(caseId, {"actions": merged, "actor": str(updates.get("actor", nextAction.get("owner", "picux")) or "picux")})
+        if updated.get("ok"):
+            updated["action"] = nextAction
+            self.addEvent(caseId, {"type": "case.action.updated", "label": f"Action updated: {nextAction.get('title', actionId)}", "actor": str(updates.get("actor", "picux") or "picux"), "status": nextAction.get("status", ""), "payload": nextAction})
+        return updated
+
+    def listActions(self, caseId: str, filters: dict[str, Any] | None = None) -> dict[str, Any]:
+        current = self.getCase(caseId)
+        if not current.get("ok"):
+            return current
+        filters = filters or {}
+        actions = [copy.deepcopy(item) for item in current["case"].get("actions", []) if isinstance(item, dict)]
+        for key in ("status", "owner", "stakeholderId"):
+            value = str(filters.get(key, "") or "")
+            if value:
+                actions = [item for item in actions if str(item.get(key, "") or "") == value]
+        actions.sort(key=lambda item: (int(item.get("updatedAt", item.get("createdAt", 0)) or 0), str(item.get("actionId", ""))), reverse=True)
+        limit = _limit(filters.get("limit", 100))
+        return {"ok": True, "caseId": caseId, "actions": actions[:limit], "count": min(len(actions), limit), "total": len(actions)}
+
+    def addEvidence(self, caseId: str, payload: dict[str, Any]) -> dict[str, Any]:
+        current = self.getCase(caseId)
+        if not current.get("ok"):
+            return current
+        evidence = _evidenceRef(payload)
+        if not evidence.get("artifactId"):
+            evidence["artifactId"] = _stableId("evidence", {"caseId": caseId, "payload": payload})
+        case = current["case"]
+        refs = [item for item in case.get("evidenceRefs", []) if isinstance(item, dict) and item.get("artifactId") != evidence["artifactId"]]
+        updated = self.updateCase(caseId, {"evidenceRefs": [*refs, evidence]})
+        if updated.get("ok"):
+            updated["evidence"] = evidence
+            self.addEvent(caseId, {"type": "case.evidence.added", "label": f"Evidence added: {evidence.get('label', evidence.get('artifactId', 'evidence'))}", "actor": "picux", "payload": evidence})
+        return updated
+
+    def addNote(self, caseId: str, payload: dict[str, Any]) -> dict[str, Any]:
+        current = self.getCase(caseId)
+        if not current.get("ok"):
+            return current
+        note = _caseNote({**payload, "caseId": caseId})
+        case = current["case"]
+        collaboration = case.get("collaboration", {}) if isinstance(case.get("collaboration"), dict) else {}
+        notes = [item for item in collaboration.get("notes", []) if isinstance(item, dict) and item.get("noteId") != note["noteId"]]
+        updated = self.updateCase(caseId, {"collaboration": {**collaboration, "notes": [*notes, note]}, "actor": note["author"]})
+        if updated.get("ok"):
+            updated["note"] = note
+            self.addEvent(
+                caseId,
+                {
+                    "type": "case.note.added",
+                    "label": f"Note added: {note.get('text', '')[:80] or note.get('noteId', 'case note')}",
+                    "actor": note["author"],
+                    "payload": {"noteId": note["noteId"], "visibility": note["visibility"], "relatedRefs": note["relatedRefs"]},
+                },
+            )
+        return updated
+
+    def listNotes(self, caseId: str, filters: dict[str, Any] | None = None) -> dict[str, Any]:
+        current = self.getCase(caseId)
+        if not current.get("ok"):
+            return current
+        filters = filters or {}
+        collaboration = current["case"].get("collaboration", {}) if isinstance(current["case"].get("collaboration"), dict) else {}
+        notes = [copy.deepcopy(item) for item in collaboration.get("notes", []) if isinstance(item, dict)]
+        visibility = str(filters.get("visibility", "") or "")
+        if visibility:
+            notes = [item for item in notes if str(item.get("visibility", "") or "") == visibility]
+        author = str(filters.get("author", filters.get("authorId", "")) or "")
+        if author:
+            notes = [item for item in notes if str(item.get("author", "") or "") == author or str(item.get("authorId", "") or "") == author]
+        notes.sort(key=lambda item: (int(item.get("createdAt", 0) or 0), str(item.get("noteId", ""))))
+        limit = _limit(filters.get("limit", 100))
+        return {"ok": True, "caseId": caseId, "notes": notes[-limit:], "count": min(len(notes), limit), "total": len(notes)}
+
+    def addEvent(self, caseId: str, payload: dict[str, Any]) -> dict[str, Any]:
+        current = self.getCase(caseId)
+        if not current.get("ok"):
+            return current
+        event = _caseEvent({**payload, "caseId": caseId})
+        self._saveEvent(event)
+        case = current["case"]
+        timeline = [item for item in case.get("timeline", []) if isinstance(item, dict) and item.get("eventId") != event["eventId"]]
+        record = {**case, "timeline": [*timeline, event], "updatedAt": int(time.time())}
+        self._saveCase(record)
+        return {"ok": True, "event": copy.deepcopy(event), "case": copy.deepcopy(record)}
+
+    def timeline(self, caseId: str, filters: dict[str, Any] | None = None) -> dict[str, Any]:
+        current = self.getCase(caseId)
+        if not current.get("ok"):
+            return current
+        self._loadEvents(caseId)
+        events = [event for event in self._events.values() if event.get("caseId") == caseId]
+        events.sort(key=lambda item: (int(item.get("createdAt", 0) or 0), str(item.get("eventId", ""))))
+        limit = _limit((filters or {}).get("limit", 250))
+        return {"ok": True, "caseId": caseId, "timeline": [copy.deepcopy(item) for item in events[-limit:]], "count": min(len(events), limit)}
+
+    def exportBundle(self, caseId: str, payload: dict[str, Any] | None = None) -> dict[str, Any]:
+        current = self.getCase(caseId)
+        if not current.get("ok"):
+            return current
+        payload = payload or {}
+        case = current["case"]
+        timeline = self.timeline(caseId).get("timeline", [])
+        evidenceRefs = case.get("evidenceRefs", []) if isinstance(case.get("evidenceRefs"), list) else []
+        actions = case.get("actions", []) if isinstance(case.get("actions"), list) else []
+        collaboration = case.get("collaboration", {}) if isinstance(case.get("collaboration"), dict) else {}
+        collaborationNotes = [item for item in collaboration.get("notes", []) if isinstance(item, dict)]
+        bundle = {
+            "bundleId": str(payload.get("bundleId", "") or _stableId("bundle", {"caseId": caseId, "updatedAt": case.get("updatedAt", 0)})),
+            "caseId": caseId,
+            "title": str(case.get("title", "") or ""),
+            "status": str(case.get("status", "") or ""),
+            "formats": _cleanList(payload.get("formats", ["json", "markdown"])) or ["json"],
+            "manifest": {
+                "stakeholders": len(case.get("stakeholders", []) if isinstance(case.get("stakeholders"), list) else []),
+                "deadlines": len(case.get("deadlines", []) if isinstance(case.get("deadlines"), list) else []),
+                "caseActions": len(actions),
+                "timeline": len(timeline),
+                "evidence": len(evidenceRefs),
+                "collaborationNotes": len(collaborationNotes),
+            },
+            "case": case,
+            "timeline": timeline,
+            "actions": actions,
+            "evidenceRefs": evidenceRefs,
+            "collaboration": {"notes": collaborationNotes},
+            "redaction": payload.get("redaction", {}) if isinstance(payload.get("redaction"), dict) else {"mode": "sourceBound"},
+            "share": {
+                "label": "portableCaseFile",
+                "evidenceStatus": "sourceBound" if evidenceRefs else "needsEvidence",
+            },
+            "createdAt": int(time.time()),
+        }
+        self.addEvent(caseId, {"type": "case.export.created", "label": "Evidence bundle exported", "actor": str(payload.get("actor", "picux") or "picux"), "payload": {"bundleId": bundle["bundleId"], "formats": bundle["formats"]}})
+        return {"ok": True, "bundle": bundle}
+
+    def _saveCase(self, record: dict[str, Any]) -> None:
+        caseId = str(record.get("caseId", "") or "")
+        if not caseId:
+            return
+        self._cases[caseId] = copy.deepcopy(record)
+        if self._backingEnabled() and hasattr(self.backing, "upsertCaseWorkspace"):
+            self.backing.upsertCaseWorkspace(record)
+
+    def _saveEvent(self, record: dict[str, Any]) -> None:
+        eventId = str(record.get("eventId", "") or "")
+        if not eventId:
+            return
+        self._events[eventId] = copy.deepcopy(record)
+        if self._backingEnabled() and hasattr(self.backing, "upsertCaseEvent"):
+            self.backing.upsertCaseEvent(record)
+
+    def _loadCases(self) -> None:
+        if self._backingEnabled() and hasattr(self.backing, "listCaseWorkspaces"):
+            for record in self.backing.listCaseWorkspaces():
+                if record.get("caseId"):
+                    self._cases[str(record["caseId"])] = copy.deepcopy(record)
+
+    def _loadEvents(self, caseId: str) -> None:
+        if self._backingEnabled() and hasattr(self.backing, "listCaseEvents"):
+            for record in self.backing.listCaseEvents(caseId=caseId):
+                if record.get("eventId"):
+                    self._events[str(record["eventId"])] = copy.deepcopy(record)
+
+    def _backingEnabled(self) -> bool:
+        return bool(self.backing is not None and getattr(self.backing, "enabled", True))
+
+
+def _caseFromPayload(payload: dict[str, Any], *, createdAt: int, updatedAt: int) -> dict[str, Any]:
+    return {
+        "caseId": str(payload.get("caseId", "") or ""),
+        "status": _choice(payload.get("status", "open"), CASE_STATUSES, "open"),
+        "title": str(payload.get("title", payload.get("subject", "Untitled case")) or "Untitled case"),
+        "summary": str(payload.get("summary", payload.get("description", "")) or ""),
+        "ownerId": str(payload.get("ownerId", payload.get("userId", "")) or ""),
+        "conversationId": str(payload.get("conversationId", "") or ""),
+        "domains": _cleanList(payload.get("domains", payload.get("domain", []))),
+        "stakeholders": [_stakeholder(item) for item in payload.get("stakeholders", []) if isinstance(item, dict)],
+        "deadlines": [_deadline(item) for item in payload.get("deadlines", []) if isinstance(item, dict)],
+        "actions": [_caseAction(item) for item in payload.get("actions", []) if isinstance(item, dict)],
+        "timeline": [item for item in payload.get("timeline", []) if isinstance(item, dict)],
+        "evidenceRefs": [_evidenceRef(item) for item in payload.get("evidenceRefs", payload.get("evidence", [])) if isinstance(item, dict)],
+        "collaboration": payload.get("collaboration", {}) if isinstance(payload.get("collaboration"), dict) else {},
+        "meta": payload.get("meta", {}) if isinstance(payload.get("meta"), dict) else {},
+        "createdAt": int(createdAt),
+        "updatedAt": int(updatedAt),
+    }
+
+
+def _stakeholder(payload: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "stakeholderId": str(payload.get("stakeholderId", "") or ""),
+        "role": _choice(payload.get("role", "other"), STAKEHOLDER_ROLES, "other"),
+        "name": str(payload.get("name", "") or ""),
+        "org": str(payload.get("org", payload.get("organization", "")) or ""),
+        "contactRef": str(payload.get("contactRef", "") or ""),
+        "channelPrefs": _cleanList(payload.get("channelPrefs", payload.get("channels", []))),
+        "permissions": _cleanList(payload.get("permissions", [])),
+        "meta": payload.get("meta", {}) if isinstance(payload.get("meta"), dict) else {},
+    }
+
+
+def _deadline(payload: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "deadlineId": str(payload.get("deadlineId", "") or ""),
+        "label": str(payload.get("label", payload.get("name", "deadline")) or "deadline"),
+        "dueAt": str(payload.get("dueAt", payload.get("date", "")) or ""),
+        "status": _choice(payload.get("status", "open"), DEADLINE_STATUSES, "open"),
+        "owner": str(payload.get("owner", payload.get("ownerId", "")) or ""),
+        "source": str(payload.get("source", "") or ""),
+        "meta": payload.get("meta", {}) if isinstance(payload.get("meta"), dict) else {},
+    }
+
+
+def _caseAction(payload: dict[str, Any]) -> dict[str, Any]:
+    now = int(time.time())
+    createdAt = int(payload.get("createdAt", now) or now)
+    return {
+        "actionId": str(payload.get("actionId", "") or ""),
+        "caseId": str(payload.get("caseId", "") or ""),
+        "title": str(payload.get("title", payload.get("label", "case action")) or "case action"),
+        "status": _choice(payload.get("status", "open"), ACTION_STATUSES, "open"),
+        "owner": str(payload.get("owner", payload.get("ownerId", "")) or ""),
+        "stakeholderId": str(payload.get("stakeholderId", "") or ""),
+        "dueAt": str(payload.get("dueAt", payload.get("date", "")) or ""),
+        "refs": _cleanList(payload.get("refs", payload.get("relatedRefs", []))),
+        "meta": payload.get("meta", {}) if isinstance(payload.get("meta"), dict) else {},
+        "createdAt": createdAt,
+        "updatedAt": int(payload.get("updatedAt", createdAt) or createdAt),
+    }
+
+
+def _caseNote(payload: dict[str, Any]) -> dict[str, Any]:
+    now = int(payload.get("createdAt", int(time.time())) or int(time.time()))
+    text = str(payload.get("text", payload.get("body", payload.get("note", ""))) or "")
+    author = str(payload.get("author", payload.get("authorId", payload.get("actor", "picux"))) or "picux")
+    noteId = str(payload.get("noteId", "") or _stableId("caseNote", {"caseId": payload.get("caseId", ""), "text": text, "author": author, "createdAt": now}))
+    return {
+        "noteId": noteId,
+        "caseId": str(payload.get("caseId", "") or ""),
+        "text": text,
+        "author": author,
+        "authorId": str(payload.get("authorId", "") or ""),
+        "visibility": _choice(payload.get("visibility", "internal"), NOTE_VISIBILITIES, "internal"),
+        "relatedRefs": _cleanList(payload.get("relatedRefs", payload.get("refs", []))),
+        "tags": _cleanList(payload.get("tags", [])),
+        "meta": payload.get("meta", {}) if isinstance(payload.get("meta"), dict) else {},
+        "createdAt": now,
+    }
+
+
+def _caseEvent(payload: dict[str, Any]) -> dict[str, Any]:
+    now = int(time.time())
+    return {
+        "eventId": str(payload.get("eventId", "") or _stableId("caseEvent", {"caseId": payload.get("caseId", ""), "type": payload.get("type", ""), "createdAt": now, "label": payload.get("label", "")})),
+        "caseId": str(payload.get("caseId", "") or ""),
+        "type": str(payload.get("type", "case.note") or "case.note"),
+        "label": str(payload.get("label", payload.get("summary", "")) or ""),
+        "actor": str(payload.get("actor", "picux") or "picux"),
+        "status": str(payload.get("status", "") or ""),
+        "payload": payload.get("payload", {}) if isinstance(payload.get("payload"), dict) else {},
+        "createdAt": int(payload.get("createdAt", now) or now),
+    }
+
+
+def _evidenceRef(payload: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "artifactId": str(payload.get("artifactId", payload.get("id", "")) or ""),
+        "kind": str(payload.get("kind", "") or ""),
+        "label": str(payload.get("label", payload.get("name", "")) or ""),
+        "source": str(payload.get("source", "") or ""),
+        "hash": str(payload.get("hash", payload.get("sha256", "")) or ""),
+        "status": str(payload.get("status", "sourceBound") or "sourceBound"),
+        "meta": payload.get("meta", {}) if isinstance(payload.get("meta"), dict) else {},
+    }
+
+
+def _caseIdentity(payload: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "title": str(payload.get("title", payload.get("subject", "")) or ""),
+        "ownerId": str(payload.get("ownerId", payload.get("userId", "")) or ""),
+        "conversationId": str(payload.get("conversationId", "") or ""),
+        "extRef": str(payload.get("extRef", payload.get("requestId", "")) or ""),
+    }
+
+
+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]}"