patchr 0.1.0__py3-none-any.whl

picux/sdk/client.py

@@ -0,0 +1,768 @@
+from __future__ import annotations
+
+import json
+import hashlib
+from collections.abc import Iterator
+from dataclasses import dataclass
+from typing import Any, Protocol
+from urllib import error, request
+from urllib.parse import urlencode
+
+from picux.config import PicuxSettings
+
+
+class Transport(Protocol):
+    def request(self, method: str, path: str, payload: dict[str, Any] | None = None, headers: dict[str, str] | None = None) -> tuple[int, dict[str, Any]]:
+        ...
+
+    def stream(self, method: str, path: str, payload: dict[str, Any] | None = None, headers: dict[str, str] | None = None) -> Iterator[dict[str, Any]]:
+        ...
+
+
+class PicuxApiError(RuntimeError):
+    def __init__(self, status: int, payload: dict[str, Any]) -> None:
+        super().__init__(str(payload.get("error", f"picux_api_{status}")))
+        self.status = status
+        self.payload = payload
+
+
+@dataclass(frozen=True)
+class HttpTransport:
+    baseUrl: str
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        payload: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> tuple[int, dict[str, Any]]:
+        url = f"{self.baseUrl.rstrip('/')}/{path.lstrip('/')}"
+        body = None
+        reqHeaders = {"Accept": "application/json", **(headers or {})}
+        if payload is not None:
+            body = json.dumps(payload, ensure_ascii=True, sort_keys=True).encode("utf-8")
+            reqHeaders["Content-Type"] = "application/json"
+        req = request.Request(url, data=body, method=method.upper(), headers=reqHeaders)
+        try:
+            with request.urlopen(req, timeout=15) as response:
+                return int(response.status), self._decode(response.read())
+        except error.HTTPError as exc:
+            return int(exc.code), self._decode(exc.read())
+
+    def stream(
+        self,
+        method: str,
+        path: str,
+        payload: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> Iterator[dict[str, Any]]:
+        url = f"{self.baseUrl.rstrip('/')}/{path.lstrip('/')}"
+        body = None
+        reqHeaders = {"Accept": "application/x-ndjson", **(headers or {})}
+        if payload is not None:
+            body = json.dumps(payload, ensure_ascii=True, sort_keys=True).encode("utf-8")
+            reqHeaders["Content-Type"] = "application/json"
+        req = request.Request(url, data=body, method=method.upper(), headers=reqHeaders)
+        try:
+            with request.urlopen(req, timeout=60) as response:
+                for rawLine in response:
+                    event = self._decode(rawLine.strip())
+                    if event:
+                        yield event
+        except error.HTTPError as exc:
+            raise PicuxApiError(int(exc.code), self._decode(exc.read())) from exc
+
+    @staticmethod
+    def _decode(raw: bytes) -> dict[str, Any]:
+        try:
+            payload = json.loads(raw.decode("utf-8") or "{}")
+        except Exception:
+            return {}
+        return payload if isinstance(payload, dict) else {"data": payload}
+
+
+class InProcessTransport:
+    """Test/local migration transport that avoids network I/O."""
+
+    def __init__(self, service: Any | None = None) -> None:
+        if service is None:
+            from picux.api import PicuxApiService
+
+            service = PicuxApiService()
+        self.service = service
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        payload: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> tuple[int, dict[str, Any]]:
+        return self.service.handle(method, path, payload or {}, headers=headers or {})
+
+    def stream(
+        self,
+        method: str,
+        path: str,
+        payload: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> Iterator[dict[str, Any]]:
+        body = payload or {}
+        if method.upper() == "POST" and path == "/v1/orchestrator/run":
+            events: list[dict[str, Any]] = []
+            result = self.service.runOrchestrator(body, onEvent=events.append)
+            yield from events
+            yield {"type": "final", "result": result}
+            return
+        status, result = self.service.handle(method, path, body, headers=headers or {})
+        if status >= 400:
+            raise PicuxApiError(status, result)
+        yield {"type": "final", "result": result}
+
+
+class PicuxClient:
+    def __init__(self, *, baseUrl: str = "http://127.0.0.1:8088", token: str = "", transport: Transport | None = None) -> None:
+        self.baseUrl = baseUrl
+        self.token = token
+        self.transport = transport or HttpTransport(baseUrl)
+
+    @classmethod
+    def fromEnv(cls, env: dict[str, str] | None = None) -> "PicuxClient":
+        settings = PicuxSettings.fromEnv(env)
+        return cls(baseUrl=settings.apiUrl, token=settings.apiToken)
+
+    def request(self, method: str, path: str, payload: dict[str, Any] | None = None, *, raiseForStatus: bool = True) -> dict[str, Any]:
+        if method.upper() == "GET" and payload:
+            path = _pathWithQuery(path, payload)
+            payload = None
+        headers = {"Authorization": f"Bearer {self.token}"} if self.token else {}
+        status, result = self.transport.request(method, path, payload, headers)
+        if status >= 400 and raiseForStatus:
+            raise PicuxApiError(status, result)
+        return result
+
+    def requestRaw(self, method: str, path: str, payload: dict[str, Any] | None = None) -> dict[str, Any]:
+        if method.upper() == "GET" and payload:
+            path = _pathWithQuery(path, payload)
+            payload = None
+        headers = {"Authorization": f"Bearer {self.token}"} if self.token else {}
+        status, result = self.transport.request(method, path, payload, headers)
+        return {"ok": status < 400, "status": status, "result": result}
+
+    def health(self) -> dict[str, Any]:
+        return self.request("GET", "/healthz")
+
+    def runtime(self) -> dict[str, Any]:
+        return self.request("GET", "/runtime")
+
+    def apiStatus(self) -> dict[str, Any]:
+        return self.request("GET", "/v1/status")
+
+    def manifest(self) -> dict[str, Any]:
+        return self.request("GET", "/v1/manifest")
+
+    def protocolMap(self) -> dict[str, Any]:
+        return self.request("GET", "/v1/protocol-map")
+
+    def handshake(self, payload: dict[str, Any]) -> dict[str, Any]:
+        return self.request("POST", "/v1/handshake", payload)
+
+    def a2aContract(self) -> dict[str, Any]:
+        return self.request("GET", "/v1/a2a/contract")
+
+    def evaluatePolicy(self, payload: dict[str, Any]) -> dict[str, Any]:
+        return self.request("POST", "/v1/security/policy/evaluate", payload)
+
+    def checkSecrets(self, payload: dict[str, Any]) -> dict[str, Any]:
+        return self.request("POST", "/v1/security/secrets/check", payload)
+
+    def nlpTool(self, payload: dict[str, Any]) -> dict[str, Any]:
+        return self.request("POST", "/v1/tools/nlp", payload)
+
+    def imageReader(self, payload: dict[str, Any]) -> dict[str, Any]:
+        return self.request("POST", "/v1/tools/imageReader", payload)
+
+    def browserReader(self, payload: dict[str, Any]) -> dict[str, Any]:
+        return self.request("POST", "/v1/tools/browserReader", payload)
+
+    def mapTool(self, payload: dict[str, Any]) -> dict[str, Any]:
+        return self.request("POST", "/v1/tools/map", payload)
+
+    def portalBrowser(self, payload: dict[str, Any]) -> dict[str, Any]:
+        return self.request("POST", "/v1/tools/portalBrowser", payload)
+
+    def runSandbox(self, payload: dict[str, Any] | None = None) -> dict[str, Any]:
+        return self.request("POST", "/v1/sandbox/midnight-arbitrage", payload or {})
+
+    def runOrchestrator(self, payload: dict[str, Any]) -> dict[str, Any]:
+        return self.request("POST", "/v1/orchestrator/run", payload)
+
+    def resumeOrchestrator(self, conversationId: str, itemId: str, action: str, payload: dict[str, Any] | None = None) -> dict[str, Any]:
+        return self.runOrchestrator({**(payload or {}), "conversationId": conversationId, "itemId": itemId, "action": action})
+
+    def streamOrchestrator(self, payload: dict[str, Any]) -> Iterator[dict[str, Any]]:
+        headers = {"Authorization": f"Bearer {self.token}"} if self.token else {}
+        yield from self.transport.stream("POST", "/v1/orchestrator/run", {**payload, "stream": True}, headers)
+
+    def runBenchmark(self, payload: dict[str, Any] | None = None) -> dict[str, Any]:
+        return self.request("POST", "/v1/benchmarks/local", payload or {})
+
+    def listSchemas(self) -> dict[str, Any]:
+        return self.request("GET", "/v1/schemas")
+
+    def getSchema(self, schemaId: str) -> dict[str, Any]:
+        return self.request("GET", f"/v1/schemas/{schemaId}")
+
+    def createA2AEnvelope(self, payload: dict[str, Any]) -> dict[str, Any]:
+        return self.request("POST", "/v1/a2a/envelopes", payload)
+
+    def listA2AEnvelopes(self, filters: dict[str, Any] | None = None) -> dict[str, Any]:
+        return self.request("GET", "/v1/a2a/envelopes", filters)
+
+    def getA2AEnvelope(self, msgId: str) -> dict[str, Any]:
+        return self.request("GET", f"/v1/a2a/envelopes/{msgId}")
+
+    def updateA2AEnvelope(self, msgId: str, payload: dict[str, Any]) -> dict[str, Any]:
+        return self.request("POST", f"/v1/a2a/envelopes/{msgId}/update", payload)
+
+    def recordEvent(self, payload: dict[str, Any]) -> dict[str, Any]:
+        return self.request("POST", "/v1/events", payload)
+
+    def listEvents(self, filters: dict[str, Any] | None = None) -> dict[str, Any]:
+        return self.request("GET", "/v1/events", filters)
+
+    def getEvent(self, eventId: str) -> dict[str, Any]:
+        return self.request("GET", f"/v1/events/{eventId}")
+
+    def ackEvent(self, eventId: str, payload: dict[str, Any] | None = None) -> dict[str, Any]:
+        return self.request("POST", f"/v1/events/{eventId}/ack", payload or {})
+
+    def createEventSubscription(self, payload: dict[str, Any]) -> dict[str, Any]:
+        return self.request("POST", "/v1/event-subscriptions", payload)
+
+    def listEventSubscriptions(self, filters: dict[str, Any] | None = None) -> dict[str, Any]:
+        return self.request("GET", "/v1/event-subscriptions", filters)
+
+    def getEventSubscription(self, subId: str) -> dict[str, Any]:
+        return self.request("GET", f"/v1/event-subscriptions/{subId}")
+
+    def updateEventSubscription(self, subId: str, payload: dict[str, Any]) -> dict[str, Any]:
+        return self.request("POST", f"/v1/event-subscriptions/{subId}/update", payload)
+
+    def createEventDelivery(self, payload: dict[str, Any]) -> dict[str, Any]:
+        return self.request("POST", "/v1/event-deliveries", payload)
+
+    def listEventDeliveries(self, filters: dict[str, Any] | None = None) -> dict[str, Any]:
+        return self.request("GET", "/v1/event-deliveries", filters)
+
+    def eventDeliveryStats(self, filters: dict[str, Any] | None = None) -> dict[str, Any]:
+        return self.request("GET", "/v1/event-deliveries/stats", filters)
+
+    def eventDeliveryReady(self, filters: dict[str, Any] | None = None) -> dict[str, Any]:
+        return self.request("GET", "/v1/event-deliveries/ready", filters)
+
+    def getEventDelivery(self, deliveryId: str) -> dict[str, Any]:
+        return self.request("GET", f"/v1/event-deliveries/{deliveryId}")
+
+    def eventDeliveryChain(self, deliveryId: str, filters: dict[str, Any] | None = None) -> dict[str, Any]:
+        return self.request("GET", f"/v1/event-deliveries/{deliveryId}/chain", filters)
+
+    def claimEventDelivery(self, payload: dict[str, Any] | None = None) -> dict[str, Any]:
+        return self.request("POST", "/v1/event-deliveries/claim", payload or {})
+
+    def claimEventDeliveries(self, payload: dict[str, Any] | None = None) -> dict[str, Any]:
+        return self.request("POST", "/v1/event-deliveries/claimBatch", payload or {})
+
+    def sweepEventDeliveryLeases(self, payload: dict[str, Any] | None = None) -> dict[str, Any]:
+        return self.request("POST", "/v1/event-deliveries/sweep", payload or {})
+
+    def retryEventDelivery(self, deliveryId: str, payload: dict[str, Any] | None = None) -> dict[str, Any]:
+        return self.request("POST", f"/v1/event-deliveries/{deliveryId}/retry", payload or {})
+
+    def failEventDelivery(self, deliveryId: str, payload: dict[str, Any] | None = None) -> dict[str, Any]:
+        return self.request("POST", f"/v1/event-deliveries/{deliveryId}/fail", payload or {})
+
+    def completeEventDelivery(self, deliveryId: str, payload: dict[str, Any] | None = None) -> dict[str, Any]:
+        return self.request("POST", f"/v1/event-deliveries/{deliveryId}/complete", payload or {})
+
+    def cancelEventDelivery(self, deliveryId: str, payload: dict[str, Any] | None = None) -> dict[str, Any]:
+        return self.request("POST", f"/v1/event-deliveries/{deliveryId}/cancel", payload or {})
+
+    def renewEventDeliveryLease(self, deliveryId: str, payload: dict[str, Any] | None = None) -> dict[str, Any]:
+        return self.request("POST", f"/v1/event-deliveries/{deliveryId}/lease", payload or {})
+
+    def releaseEventDelivery(self, deliveryId: str, payload: dict[str, Any] | None = None) -> dict[str, Any]:
+        return self.request("POST", f"/v1/event-deliveries/{deliveryId}/release", payload or {})
+
+    def updateEventDelivery(self, deliveryId: str, payload: dict[str, Any]) -> dict[str, Any]:
+        return self.request("POST", f"/v1/event-deliveries/{deliveryId}/update", payload)
+
+    def createTask(self, payload: dict[str, Any]) -> dict[str, Any]:
+        return self.request("POST", "/v1/tasks", payload)
+
+    def listTasks(self, filters: dict[str, Any] | None = None) -> dict[str, Any]:
+        return self.request("GET", "/v1/tasks", filters)
+
+    def getTask(self, taskId: str) -> dict[str, Any]:
+        return self.request("GET", f"/v1/tasks/{taskId}")
+
+    def updateTask(self, taskId: str, payload: dict[str, Any]) -> dict[str, Any]:
+        return self.request("POST", f"/v1/tasks/{taskId}/update", payload)
+
+    def createCase(self, payload: dict[str, Any]) -> dict[str, Any]:
+        return self.request("POST", "/v1/cases", payload)
+
+    def listCases(self, filters: dict[str, Any] | None = None) -> dict[str, Any]:
+        return self.request("GET", "/v1/cases", filters)
+
+    def getCase(self, caseId: str) -> dict[str, Any]:
+        return self.request("GET", f"/v1/cases/{caseId}")
+
+    def updateCase(self, caseId: str, payload: dict[str, Any]) -> dict[str, Any]:
+        return self.request("POST", f"/v1/cases/{caseId}/update", payload)
+
+    def addCaseStakeholder(self, caseId: str, payload: dict[str, Any]) -> dict[str, Any]:
+        return self.request("POST", f"/v1/cases/{caseId}/stakeholders", payload)
+
+    def addCaseDeadline(self, caseId: str, payload: dict[str, Any]) -> dict[str, Any]:
+        return self.request("POST", f"/v1/cases/{caseId}/deadlines", payload)
+
+    def reviewCaseDeadlines(self, caseId: str, payload: dict[str, Any] | None = None) -> dict[str, Any]:
+        return self.request("POST", f"/v1/cases/{caseId}/deadlines/review", payload or {})
+
+    def addCaseAction(self, caseId: str, payload: dict[str, Any]) -> dict[str, Any]:
+        return self.request("POST", f"/v1/cases/{caseId}/actions", payload)
+
+    def listCaseActions(self, caseId: str, filters: dict[str, Any] | None = None) -> dict[str, Any]:
+        return self.request("GET", f"/v1/cases/{caseId}/actions", filters)
+
+    def updateCaseAction(self, caseId: str, actionId: str, payload: dict[str, Any]) -> dict[str, Any]:
+        return self.request("POST", f"/v1/cases/{caseId}/actions/{actionId}/update", payload)
+
+    def addCaseEvent(self, caseId: str, payload: dict[str, Any]) -> dict[str, Any]:
+        return self.request("POST", f"/v1/cases/{caseId}/events", payload)
+
+    def caseTimeline(self, caseId: str, filters: dict[str, Any] | None = None) -> dict[str, Any]:
+        return self.request("GET", f"/v1/cases/{caseId}/timeline", filters)
+
+    def addCaseEvidence(self, caseId: str, payload: dict[str, Any]) -> dict[str, Any]:
+        return self.request("POST", f"/v1/cases/{caseId}/evidence", payload)
+
+    def addCaseNote(self, caseId: str, payload: dict[str, Any]) -> dict[str, Any]:
+        return self.request("POST", f"/v1/cases/{caseId}/notes", payload)
+
+    def listCaseNotes(self, caseId: str, filters: dict[str, Any] | None = None) -> dict[str, Any]:
+        return self.request("GET", f"/v1/cases/{caseId}/notes", filters)
+
+    def exportCaseBundle(self, caseId: str, payload: dict[str, Any] | None = None) -> dict[str, Any]:
+        return self.request("POST", f"/v1/cases/{caseId}/export", payload or {})
+
+    def listAgents(self) -> dict[str, Any]:
+        return self.request("GET", "/v1/agents")
+
+    def getAgent(self, agentId: str) -> dict[str, Any]:
+        return self.request("GET", f"/v1/agents/{agentId}")
+
+    def registerAgent(self, payload: dict[str, Any]) -> dict[str, Any]:
+        return self.request("POST", "/v1/agents", payload)
+
+    def matchAgents(self, payload: dict[str, Any]) -> dict[str, Any]:
+        return self.request("POST", "/v1/agents/match", payload)
+
+    def delegateAgent(self, payload: dict[str, Any]) -> dict[str, Any]:
+        return self.request("POST", "/v1/agents/delegate", payload)
+
+    def registerConnector(self, payload: dict[str, Any]) -> dict[str, Any]:
+        return self.request("POST", "/v1/bridge/connectors", payload)
+
+    def listReadyConnectors(self) -> dict[str, Any]:
+        return self.request("GET", "/v1/bridge/connectors/ready")
+
+    def installReadyConnectors(self, payload: dict[str, Any] | None = None) -> dict[str, Any]:
+        return self.request("POST", "/v1/bridge/connectors/ready/install", payload or {})
+
+    def createBridgeConnectionSession(self, payload: dict[str, Any]) -> dict[str, Any]:
+        return self.request("POST", "/v1/bridge/connection-sessions", payload)
+
+    def listBridgeConnectionSessions(self, filters: dict[str, Any] | None = None) -> dict[str, Any]:
+        return self.request("GET", "/v1/bridge/connection-sessions", filters)
+
+    def getBridgeConnectionSession(self, sessionId: str) -> dict[str, Any]:
+        return self.request("GET", f"/v1/bridge/connection-sessions/{sessionId}")
+
+    def revokeBridgeConnectionSession(self, sessionId: str, payload: dict[str, Any] | None = None) -> dict[str, Any]:
+        return self.request("POST", f"/v1/bridge/connection-sessions/{sessionId}/revoke", payload or {})
+
+    def createBridgeAction(self, payload: dict[str, Any]) -> dict[str, Any]:
+        return self.request("POST", "/v1/bridge/actions", payload)
+
+    def listBridgeActions(self, filters: dict[str, Any] | None = None) -> dict[str, Any]:
+        return self.request("GET", "/v1/bridge/actions", filters)
+
+    def getBridgeAction(self, actionId: str) -> dict[str, Any]:
+        return self.request("GET", f"/v1/bridge/actions/{actionId}")
+
+    def updateBridgeAction(self, actionId: str, payload: dict[str, Any]) -> dict[str, Any]:
+        return self.request("POST", f"/v1/bridge/actions/{actionId}/update", payload)
+
+    def runBridgeAction(self, actionId: str, payload: dict[str, Any] | None = None) -> dict[str, Any]:
+        return self.request("POST", f"/v1/bridge/actions/{actionId}/run", payload or {})
+
+    def createPortalSession(self, payload: dict[str, Any]) -> dict[str, Any]:
+        return self.request("POST", "/v1/bridge/portal/sessions", payload)
+
+    def listPortalSessions(self, filters: dict[str, Any] | None = None) -> dict[str, Any]:
+        return self.request("GET", "/v1/bridge/portal/sessions", filters)
+
+    def getPortalSession(self, portalSessionId: str) -> dict[str, Any]:
+        return self.request("GET", f"/v1/bridge/portal/sessions/{portalSessionId}")
+
+    def preflightPortalSession(self, portalSessionId: str, payload: dict[str, Any] | None = None) -> dict[str, Any]:
+        return self.request("POST", f"/v1/bridge/portal/sessions/{portalSessionId}/preflight", payload or {})
+
+    def createPortalAction(self, payload: dict[str, Any]) -> dict[str, Any]:
+        return self.request("POST", "/v1/bridge/portal/actions", payload)
+
+    def listPortalActions(self, filters: dict[str, Any] | None = None) -> dict[str, Any]:
+        return self.request("GET", "/v1/bridge/portal/actions", filters)
+
+    def getPortalAction(self, portalActionId: str) -> dict[str, Any]:
+        return self.request("GET", f"/v1/bridge/portal/actions/{portalActionId}")
+
+    def listPortalActionTemplates(self, filters: dict[str, Any] | None = None) -> dict[str, Any]:
+        return self.request("GET", "/v1/bridge/portal/templates", filters)
+
+    def getPortalActionTemplate(self, templateId: str) -> dict[str, Any]:
+        return self.request("GET", f"/v1/bridge/portal/templates/{templateId}")
+
+    def listPortalPlaybooks(self, filters: dict[str, Any] | None = None) -> dict[str, Any]:
+        return self.request("GET", "/v1/bridge/portal/playbooks", filters)
+
+    def getPortalPlaybook(self, playbookId: str) -> dict[str, Any]:
+        return self.request("GET", f"/v1/bridge/portal/playbooks/{playbookId}")
+
+    def instantiatePortalPlaybook(self, playbookId: str, payload: dict[str, Any]) -> dict[str, Any]:
+        return self.request("POST", f"/v1/bridge/portal/playbooks/{playbookId}/instantiate", payload)
+
+    def runPortalAction(self, portalActionId: str, payload: dict[str, Any] | None = None) -> dict[str, Any]:
+        return self.request("POST", f"/v1/bridge/portal/actions/{portalActionId}/run", payload or {})
+
+    def createChannelThread(self, payload: dict[str, Any]) -> dict[str, Any]:
+        return self.request("POST", "/v1/channels/threads", payload)
+
+    def listChannelThreads(self, filters: dict[str, Any] | None = None) -> dict[str, Any]:
+        return self.request("GET", "/v1/channels/threads", filters)
+
+    def getChannelThread(self, threadId: str) -> dict[str, Any]:
+        return self.request("GET", f"/v1/channels/threads/{threadId}")
+
+    def channelThreadTimeline(self, threadId: str, filters: dict[str, Any] | None = None) -> dict[str, Any]:
+        return self.request("GET", f"/v1/channels/threads/{threadId}/timeline", filters)
+
+    def recordTouchpoint(self, payload: dict[str, Any]) -> dict[str, Any]:
+        return self.request("POST", "/v1/channels/touchpoints", payload)
+
+    def listTouchpoints(self, filters: dict[str, Any] | None = None) -> dict[str, Any]:
+        return self.request("GET", "/v1/channels/touchpoints", filters)
+
+    def getTouchpoint(self, touchpointId: str) -> dict[str, Any]:
+        return self.request("GET", f"/v1/channels/touchpoints/{touchpointId}")
+
+    def ingestProviderCallback(self, payload: dict[str, Any]) -> dict[str, Any]:
+        return self.request("POST", "/v1/channels/callbacks", payload)
+
+    def listProviderCallbacks(self, filters: dict[str, Any] | None = None) -> dict[str, Any]:
+        return self.request("GET", "/v1/channels/callbacks", filters)
+
+    def listConnectors(self, filters: dict[str, Any] | None = None) -> dict[str, Any]:
+        return self.request("GET", "/v1/bridge/connectors", filters)
+
+    def getConnector(self, connectorId: str) -> dict[str, Any]:
+        return self.request("GET", f"/v1/bridge/connectors/{connectorId}")
+
+    def updateConnector(self, connectorId: str, payload: dict[str, Any]) -> dict[str, Any]:
+        return self.request("POST", f"/v1/bridge/connectors/{connectorId}/update", payload)
+
+    def matchConnectors(self, payload: dict[str, Any]) -> dict[str, Any]:
+        return self.request("POST", "/v1/bridge/connectors/match", payload)
+
+    def preflightConnector(self, connectorId: str, payload: dict[str, Any]) -> dict[str, Any]:
+        return self.request("POST", f"/v1/bridge/connectors/{connectorId}/preflight", payload)
+
+    def preflightConnectorPaid(
+        self,
+        connectorId: str,
+        payload: dict[str, Any],
+        *,
+        payer: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        return self.payFetch("POST", f"/v1/bridge/connectors/{connectorId}/preflight", payload, payer=payer)
+
+    def createProxyMission(self, payload: dict[str, Any]) -> dict[str, Any]:
+        return self.request("POST", "/v1/proxy/missions", payload)
+
+    def listProxyMissions(self, filters: dict[str, Any] | None = None) -> dict[str, Any]:
+        return self.request("GET", "/v1/proxy/missions", filters)
+
+    def getProxyMission(self, proxyId: str) -> dict[str, Any]:
+        return self.request("GET", f"/v1/proxy/missions/{proxyId}")
+
+    def submitProxyOutcome(self, proxyId: str, payload: dict[str, Any]) -> dict[str, Any]:
+        return self.request("POST", f"/v1/proxy/missions/{proxyId}/outcome", payload)
+
+    def submitProxyOutcomeByRef(self, payload: dict[str, Any]) -> dict[str, Any]:
+        return self.request("POST", "/v1/proxy/outcomes", payload)
+
+    def huntDiscover(self, payload: dict[str, Any]) -> dict[str, Any]:
+        return self.request("POST", "/v1/hunt/discover", payload)
+
+    def listWorkflowTemplates(self) -> dict[str, Any]:
+        return self.request("GET", "/v1/workflows/templates")
+
+    def getWorkflowTemplate(self, templateId: str) -> dict[str, Any]:
+        return self.request("GET", f"/v1/workflows/templates/{templateId}")
+
+    def runWorkflowTemplate(self, templateId: str, payload: dict[str, Any]) -> dict[str, Any]:
+        return self.request("POST", f"/v1/workflows/templates/{templateId}/run", payload)
+
+    def resolveScamTriage(self, payload: dict[str, Any]) -> dict[str, Any]:
+        return self.request("POST", "/v1/resolve/scamTriage", payload)
+
+    def resolveRecovery(self, payload: dict[str, Any]) -> dict[str, Any]:
+        return self.request("POST", "/v1/resolve/recovery", payload)
+
+    def createMandate(self, mandate: dict[str, Any]) -> dict[str, Any]:
+        return self.request("POST", "/v1/mandates", mandate)
+
+    def listMandates(self, filters: dict[str, Any] | None = None) -> dict[str, Any]:
+        return self.request("GET", "/v1/mandates", filters)
+
+    def getMandate(self, mandateId: str) -> dict[str, Any]:
+        return self.request("GET", f"/v1/mandates/{mandateId}")
+
+    def verifyMandate(self, mandateId: str, mandate: dict[str, Any]) -> dict[str, Any]:
+        return self.request("POST", f"/v1/mandates/{mandateId}/verify", mandate)
+
+    def resolveTask(self, taskId: str, payload: dict[str, Any]) -> dict[str, Any]:
+        return self.request("POST", f"/v1/tasks/{taskId}/resolve", payload)
+
+    def createEscrow(self, payload: dict[str, Any]) -> dict[str, Any]:
+        return self.request("POST", "/v1/pay/escrows", payload)
+
+    def listEscrows(self, filters: dict[str, Any] | None = None) -> dict[str, Any]:
+        return self.request("GET", "/v1/pay/escrows", filters)
+
+    def getEscrow(self, escrowId: str) -> dict[str, Any]:
+        return self.request("GET", f"/v1/pay/escrows/{escrowId}")
+
+    def updateEscrow(self, escrowId: str, payload: dict[str, Any]) -> dict[str, Any]:
+        return self.request("POST", f"/v1/pay/escrows/{escrowId}/update", payload)
+
+    def fundEscrow(self, escrowId: str, payload: dict[str, Any] | None = None) -> dict[str, Any]:
+        return self.request("POST", f"/v1/pay/escrows/{escrowId}/fund", payload or {})
+
+    def submitEscrowProof(self, escrowId: str, payload: dict[str, Any]) -> dict[str, Any]:
+        return self.request("POST", f"/v1/pay/escrows/{escrowId}/proof", payload)
+
+    def settleEscrow(self, escrowId: str, payload: dict[str, Any] | None = None) -> dict[str, Any]:
+        return self.request("POST", f"/v1/pay/escrows/{escrowId}/settle", payload or {})
+
+    def refundEscrow(self, escrowId: str, payload: dict[str, Any] | None = None) -> dict[str, Any]:
+        return self.request("POST", f"/v1/pay/escrows/{escrowId}/refund", payload or {})
+
+    def disputeEscrow(self, escrowId: str, payload: dict[str, Any]) -> dict[str, Any]:
+        return self.request("POST", f"/v1/pay/escrows/{escrowId}/dispute", payload)
+
+    def listPayRails(self) -> dict[str, Any]:
+        return self.request("GET", "/v1/pay/rails")
+
+    def getPayRail(self, railId: str) -> dict[str, Any]:
+        return self.request("GET", f"/v1/pay/rails/{railId}")
+
+    def listPayAdapters(self) -> dict[str, Any]:
+        return self.request("GET", "/v1/pay/adapters")
+
+    def getPayAdapter(self, adapterId: str) -> dict[str, Any]:
+        return self.request("GET", f"/v1/pay/adapters/{adapterId}")
+
+    def invokePayAdapter(self, adapterId: str, payload: dict[str, Any]) -> dict[str, Any]:
+        return self.request("POST", f"/v1/pay/adapters/{adapterId}/invoke", payload)
+
+    def initEscrowMission(self, mission: dict[str, Any], *, adapterId: str = "solanaEscrowAdapter", live: bool = False, signedTransaction: str = "") -> dict[str, Any]:
+        payload: dict[str, Any] = {"mission": mission}
+        if live:
+            payload["live"] = True
+        if signedTransaction:
+            payload["signedTransaction"] = signedTransaction
+        return self.invokePayAdapter(adapterId, {"action": "mission.initialize", "payload": payload})
+
+    def settleEscrowMission(self, mission: dict[str, Any], *, adapterId: str = "solanaEscrowAdapter", live: bool = False, signedTransaction: str = "") -> dict[str, Any]:
+        payload: dict[str, Any] = {"mission": mission}
+        if live:
+            payload["live"] = True
+        if signedTransaction:
+            payload["signedTransaction"] = signedTransaction
+        return self.invokePayAdapter(adapterId, {"action": "mission.settle", "payload": payload})
+
+    def abortEscrowMission(self, mission: dict[str, Any], *, adapterId: str = "solanaEscrowAdapter", live: bool = False, signedTransaction: str = "") -> dict[str, Any]:
+        payload: dict[str, Any] = {"mission": mission}
+        if live:
+            payload["live"] = True
+        if signedTransaction:
+            payload["signedTransaction"] = signedTransaction
+        return self.invokePayAdapter(adapterId, {"action": "mission.abort", "payload": payload})
+
+    def listReputationCards(self, filters: dict[str, Any] | None = None) -> dict[str, Any]:
+        return self.request("GET", "/v1/pay/reputation", filters)
+
+    def getReputationCard(self, cardId: str) -> dict[str, Any]:
+        return self.request("GET", f"/v1/pay/reputation/{cardId}")
+
+    def updateReputationCard(self, payload: dict[str, Any]) -> dict[str, Any]:
+        return self.request("POST", "/v1/pay/reputation", payload)
+
+    def createPaymentChallenge(self, payload: dict[str, Any]) -> dict[str, Any]:
+        return self.request("POST", "/v1/pay/challenges", payload)
+
+    def verifyPaymentChallenge(self, challengeId: str, payload: dict[str, Any]) -> dict[str, Any]:
+        return self.request("POST", f"/v1/pay/challenges/{challengeId}/verify", payload)
+
+    def createPaymentSession(self, payload: dict[str, Any]) -> dict[str, Any]:
+        return self.request("POST", "/v1/pay/sessions", payload)
+
+    def authorizePaymentSession(self, sessionId: str, payload: dict[str, Any] | None = None) -> dict[str, Any]:
+        return self.request("POST", f"/v1/pay/sessions/{sessionId}/authorize", payload or {})
+
+    def consumePaymentSession(self, sessionId: str, payload: dict[str, Any]) -> dict[str, Any]:
+        return self.request("POST", f"/v1/pay/sessions/{sessionId}/consume", payload)
+
+    def closePaymentSession(self, sessionId: str, payload: dict[str, Any] | None = None) -> dict[str, Any]:
+        return self.request("POST", f"/v1/pay/sessions/{sessionId}/close", payload or {})
+
+    def localPaymentCredential(self, challenge: dict[str, Any], payer: dict[str, Any] | None = None) -> dict[str, Any]:
+        payerObj = payer if isinstance(payer, dict) else challenge.get("payer", {})
+        payerObj = payerObj if isinstance(payerObj, dict) else {}
+        challengeId = str(challenge.get("challengeId", "") or "")
+        railId = str(challenge.get("railId", "picuxLedger") or "picuxLedger")
+        credential = {
+            "credentialId": _stableId("paycred", {"challengeId": challengeId, "railId": railId, "payer": payerObj}),
+            "challengeId": challengeId,
+            "railId": railId,
+            "payer": payerObj,
+            "signature": _stableId("paysig", {"challengeId": challengeId, "railId": railId, "payer": payerObj}),
+            "paymentRef": _stableId("localpay", {"challengeId": challengeId, "payer": payerObj}),
+            "amount": challenge.get("amount", {}) if isinstance(challenge.get("amount"), dict) else {},
+            "createdAt": str(challenge.get("createdAt", "") or ""),
+            "meta": {"mode": "picuxLedgerLocal"},
+        }
+        return credential
+
+    def payFetch(
+        self,
+        method: str,
+        path: str,
+        payload: dict[str, Any] | None = None,
+        *,
+        payer: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        headers = {"Authorization": f"Bearer {self.token}"} if self.token else {}
+        status, result = self.transport.request(method, path, payload, headers)
+        if status != 402:
+            if status >= 400:
+                raise PicuxApiError(status, result)
+            return result
+        challenge = result.get("challenge", {}) if isinstance(result.get("challenge"), dict) else {}
+        credential = self.localPaymentCredential(challenge, payer=payer)
+        verified = self.verifyPaymentChallenge(str(challenge.get("challengeId", "") or ""), {"credential": credential})
+        retryHeaders = {
+            **headers,
+            "X-Picux-Payment-Challenge": str(challenge.get("challengeId", "") or ""),
+            "X-Picux-Payment-Credential": credential["credentialId"],
+            "Payment-Signature": credential["signature"],
+        }
+        retryStatus, retryResult = self.transport.request(method, path, payload, retryHeaders)
+        if retryStatus >= 400:
+            raise PicuxApiError(retryStatus, retryResult)
+        return {**retryResult, "paymentReceipt": verified.get("receipt", {})}
+
+    def settlementAdapterContract(self) -> dict[str, Any]:
+        return self.request("GET", "/v1/pay/adapters/contract")
+
+    def prepareSettlement(self, payload: dict[str, Any]) -> dict[str, Any]:
+        return self.request("POST", "/v1/pay/prepare", payload)
+
+    def settle(self, payload: dict[str, Any]) -> dict[str, Any]:
+        return self.request("POST", "/v1/pay/settle", payload)
+
+    def listReceipts(self, filters: dict[str, Any] | None = None) -> dict[str, Any]:
+        return self.request("GET", "/v1/receipts", filters)
+
+    def getReceipt(self, receiptId: str) -> dict[str, Any]:
+        return self.request("GET", f"/v1/receipts/{receiptId}")
+
+    def getEvidence(self, artifactId: str) -> dict[str, Any]:
+        return self.request("GET", f"/v1/audit/evidence/{artifactId}")
+
+    def listEvidence(self, filters: dict[str, Any] | None = None) -> dict[str, Any]:
+        return self.request("GET", "/v1/audit/evidence", filters)
+
+    def recordEvidence(self, payload: dict[str, Any]) -> dict[str, Any]:
+        return self.request("POST", "/v1/audit/evidence", payload)
+
+    def createProofPack(self, payload: dict[str, Any]) -> dict[str, Any]:
+        return self.request("POST", "/v1/audit/proofPacks", payload)
+
+    def listProofPacks(self, filters: dict[str, Any] | None = None) -> dict[str, Any]:
+        return self.request("GET", "/v1/audit/proofPacks", filters)
+
+    def getProofPack(self, packId: str) -> dict[str, Any]:
+        return self.request("GET", f"/v1/audit/proofPacks/{packId}")
+
+    def getPov(self, povId: str) -> dict[str, Any]:
+        return self.request("GET", f"/v1/audit/pov/{povId}")
+
+    def listPov(self, filters: dict[str, Any] | None = None) -> dict[str, Any]:
+        return self.request("GET", "/v1/audit/pov", filters)
+
+    def recordPov(self, payload: dict[str, Any]) -> dict[str, Any]:
+        return self.request("POST", "/v1/audit/pov", payload)
+
+    def verifyReceipt(self, payload: dict[str, Any]) -> dict[str, Any]:
+        return self.request("POST", "/v1/audit/receipts/verify", payload)
+
+    def verifyChain(self, payload: dict[str, Any]) -> dict[str, Any]:
+        return self.request("POST", "/v1/audit/chain/verify", payload)
+
+    def communitySignal(self, payload: dict[str, Any]) -> dict[str, Any]:
+        return self.request("POST", "/v1/signals/community", payload)
+
+    def listCommunitySignals(self, filters: dict[str, Any] | None = None) -> dict[str, Any]:
+        return self.request("GET", "/v1/signals/community", filters)
+
+    def getCommunitySignal(self, signalId: str) -> dict[str, Any]:
+        return self.request("GET", f"/v1/signals/community/{signalId}")
+
+    def analyzeCommunitySignal(self, payload: dict[str, Any]) -> dict[str, Any]:
+        return self.request("POST", "/v1/signals/community/analyze", payload)
+
+    def launchCommunityTask(self, payload: dict[str, Any]) -> dict[str, Any]:
+        return self.request("POST", "/v1/signals/community/launch-task", payload)
+
+    def communityEntities(self) -> dict[str, Any]:
+        return self.request("GET", "/v1/signals/community/entities")
+
+
+def _pathWithQuery(path: str, payload: dict[str, Any]) -> str:
+    values = {key: value for key, value in payload.items() if value is not None and value != ""}
+    if not values:
+        return path
+    joiner = "&" if "?" in path else "?"
+    return f"{path}{joiner}{urlencode(values, doseq=True)}"
+
+
+def _stableId(prefix: str, payload: dict[str, Any]) -> str:
+    digest = hashlib.sha256(
+        json.dumps(payload, ensure_ascii=True, sort_keys=True, separators=(",", ":")).encode("utf-8")
+    ).hexdigest()[:24]
+    return f"{prefix}_{digest}"