117 lines
3.6 KiB
Python
117 lines
3.6 KiB
Python
"""Paperclip REST API helper.
|
|
|
|
All HTTP calls from legal-ai backend (FastAPI) to Paperclip should go through
|
|
``pc_request`` so that auth + audit headers are applied consistently.
|
|
|
|
The bash counterpart for agents lives at ``scripts/pc.sh``.
|
|
|
|
Notes
|
|
-----
|
|
* Uses ``PAPERCLIP_BOARD_API_KEY`` (long-lived) — these are *board* actions
|
|
(wakeups, comments-as-user) initiated from outside a heartbeat, not agent
|
|
actions. Board API keys are not JWTs, so they do **not** carry a ``run_id``
|
|
claim; pass ``run_id=`` explicitly when you have one (rare for board flows).
|
|
* For agent actions inside a heartbeat run, agents use the bash helper with
|
|
the auto-injected ``PAPERCLIP_API_KEY`` JWT — those carry ``run_id`` in
|
|
claims, so the header is informational/future-proofing.
|
|
"""
|
|
from __future__ import annotations
|
|
|
|
import logging
|
|
import os
|
|
from datetime import datetime
|
|
from typing import Any
|
|
|
|
import httpx
|
|
|
|
logger = logging.getLogger(__name__)
|
|
|
|
PAPERCLIP_API_URL = os.environ.get("PAPERCLIP_API_URL", "http://localhost:3100")
|
|
PAPERCLIP_BOARD_API_KEY = os.environ.get("PAPERCLIP_BOARD_API_KEY", "")
|
|
|
|
DEFAULT_TIMEOUT = 15.0
|
|
|
|
|
|
def _build_headers(run_id: str | None, has_body: bool) -> dict[str, str]:
|
|
if not PAPERCLIP_BOARD_API_KEY:
|
|
raise RuntimeError("PAPERCLIP_BOARD_API_KEY not set — cannot call Paperclip API")
|
|
headers = {
|
|
"Authorization": f"Bearer {PAPERCLIP_BOARD_API_KEY}",
|
|
"X-Paperclip-Run-Id": run_id or "",
|
|
}
|
|
if has_body:
|
|
headers["Content-Type"] = "application/json"
|
|
return headers
|
|
|
|
|
|
async def pc_request(
|
|
method: str,
|
|
path: str,
|
|
*,
|
|
json: dict[str, Any] | None = None,
|
|
run_id: str | None = None,
|
|
timeout: float = DEFAULT_TIMEOUT,
|
|
raise_on_error: bool = False,
|
|
) -> httpx.Response:
|
|
"""Make a Paperclip REST request.
|
|
|
|
Parameters
|
|
----------
|
|
method : str
|
|
HTTP method (GET, POST, PATCH, DELETE).
|
|
path : str
|
|
Path relative to PAPERCLIP_API_URL (must start with ``/``).
|
|
json : dict, optional
|
|
Request body — sent as JSON.
|
|
run_id : str, optional
|
|
Heartbeat run ID for audit trail (X-Paperclip-Run-Id header).
|
|
Rare for board actions; provide when initiating from inside a run.
|
|
timeout : float
|
|
httpx timeout (default 15s).
|
|
raise_on_error : bool
|
|
If True, calls ``response.raise_for_status()`` on 4xx/5xx.
|
|
|
|
Returns
|
|
-------
|
|
httpx.Response
|
|
"""
|
|
headers = _build_headers(run_id, has_body=json is not None)
|
|
url = f"{PAPERCLIP_API_URL}{path}"
|
|
async with httpx.AsyncClient(timeout=timeout) as client:
|
|
resp = await client.request(method, url, headers=headers, json=json)
|
|
if raise_on_error:
|
|
resp.raise_for_status()
|
|
return resp
|
|
|
|
|
|
async def emit_case_status_webhook(
|
|
case_number: str,
|
|
old_status: str,
|
|
new_status: str,
|
|
company_id: str | None = None,
|
|
run_id: str | None = None,
|
|
) -> None:
|
|
"""Notify the Paperclip plugin that a case status changed.
|
|
|
|
Fire-and-forget: logs errors but never raises, so callers aren't blocked.
|
|
"""
|
|
try:
|
|
await pc_request(
|
|
"POST",
|
|
"/api/plugins/marcusgroup.legal-ai/webhooks/case-status",
|
|
json={
|
|
"caseNumber": case_number,
|
|
"oldStatus": old_status,
|
|
"newStatus": new_status,
|
|
"companyId": company_id,
|
|
"timestamp": datetime.utcnow().isoformat() + "Z",
|
|
},
|
|
run_id=run_id,
|
|
timeout=5.0,
|
|
)
|
|
except Exception as exc:
|
|
logger.warning(
|
|
"emit_case_status_webhook failed for case %s (%s → %s): %s",
|
|
case_number, old_status, new_status, exc,
|
|
)
|