List Documents

List documents (signing sessions) with filtering, search, sorting, and status facets computed over the ENTIRE matching data set, not just the current page.

Query params: offset, limit -- pagination over the status-filtered result set. status -- exact SessionStatus value, the legacy "cancelled" alias (widened to voided+declined; see _status_clause), or the list-only owner-draft keys draft / ready_to_send. recipient -- substring match against recipient email (legacy filter, unchanged scope: email only, not name). date_from, date_to -- ISO-8601, inclusive, filtering created_at. A value that fails to parse is a 422, not a silently-ignored filter. q -- substring search across document name, document filename, recipient name, and recipient email (case-insensitive; %/_ in the term are escaped so they match literally rather than acting as SQL wildcards). Also matches against the session/document ids, but ONLY when q looks like it could plausibly be one -- see _looks_like_id -- since casting a uuid column to text to ILIKE it is unindexable: Postgres has to evaluate that cast-and-compare on every row the join produces, on every request, whether or not q could ever match an id. Dropping the two id branches for ordinary text queries measurably cuts per-request time (~45-50% in an EXPLAIN ANALYZE repro over 60k seeded sessions); it does NOT turn the underlying Seq Scans on documents/session_recipients into index scans -- those columns have no index that supports ILIKE substring search at all, id cast or not. sort -- one of _SORT_COLUMNS's keys (created_at, updated_at, name, status); unrecognized values default to created_at. direction -- "asc" or "desc"; unrecognized values default to desc. Every sort has SigningSession.id appended as a deterministic secondary key.

Response: DocumentListResponse (app/schemas/document.py) -- items is the requested page; total, status_facets, and needs_attention_count are all computed over the full status-filtered (total) or status-UNfiltered (status_facets, needs_attention_count) matching set, per D2's "same base query" requirement, not derived from items. status_facets always includes every SessionStatus key plus the list-only owner-draft keys draft and ready_to_send.