Practice Management backend: Clio-backed Matters seam + routes

↗ view on GitHub · sloth-ninja · 2026-08-07 · 7945ad49

Task 2 of the Practice Management plan. Live Clio reads only; the sole
stored artefact is the matter_workspace_links id/number pair, whose
migration (20260807_01) is Task 1 and is NOT in this PR - every links
query degrades on 42P01/42703/PGRST204 so this runs safely ahead of it.

- lib/clio/mattersSurface.ts: list (mine = responsible union originating,
  de-duped, sorted open_date desc; all = one order=open_date(desc) page),
  detail + financials, related contacts, time entries, activity update
  (If-Match) / delete, workspace link lifecycle. 60s per-user list cache
  keyed user+tab+query+status, 200-entry cap, cleared on activity write.
- routes/clioMatters.ts mounted at /clio-matters behind the research
  limiter; requireAuth + asyncHandler throughout, fixed client details +
  safeErrorLog, uuid/numeric id guards. Minutes to seconds happens at
  this boundary once.
- clioRequest gains an additive headers option for If-Match; caller
  headers sit beneath the fixed ones so Authorization / Accept /
  X-API-VERSION can never be overridden.
- Selector fixes (docs-verified 06/08 spike, live probe pending):
  clio_matter_financials asks billable_matters for its own fields
  (the shipped matter{...} brace 400'd every call, owner-reproduced);
  clio_find_contact treats primary_email_address as a scalar.
- Lifecycle: account deletion and SAR export cover the links table,
  42P01-tolerant.

Probe-gated per the spec's open questions: one 200-row page with honest
counts, billed entries locked AND refused server-side with a fixed 409.

Every read uses the caller's own Clio token; link lookups go through
checkProjectAccess, the choke point that also excludes tombstoned
matters. Redacted money/hours report as hidden, never as zero.

Verified: tsc clean; full vitest 836 passed / 48 files (baseline 757,
79 new); prettier clean on all new files.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Repository Sloth-ninja/JessicaOSS
Author sloth-ninja <ezanahaddis@gmail.com>
Authored
Parents d178f027
Stats 15 files changed , +3520 , -6
Part of Practice Management: Clio-backed Matters and workspace links

Capture this commit into my fork

Download a Markdown prompt that tells Claude how to port this exact commit into your working tree. Run it via claude -p < capture-commit-7945ad49.md from inside the repo you want the change in.

⬇ Download capture-commit-7945ad49.md