dre/docs/letter-queue-scope.md

# Letter Queue - Backend Scope (draft)

Date: 2026-08-24
Author: Sho'Nuff (draft for Germaine review)

## Current state (ground truth, verified 2026-08-24)

- **Send pipeline is BUILT and verified end-to-end.** Two new modules:
  - `/opt/dre-portal/app/letterstream.py` — LetterStream integration (auth, account
    status, send single/batch, preauth/doauth, tracking, signature, proof).
  - `/opt/dre-portal/app/letters.py` — router: letters queue lifecycle, PDF render
    (fpdf2 2.8.8), LetterStream send, and the callback receiver.
- **Live DB tables exist:** `letters` and `letter_events` (added to `schema.sql`,
  applied on restart).
- **LetterStream API contract fully recovered** from the user-supplied
  `api_fulfillment.pdf` (21 pages): `POST https://www.letterstream.com/apis/` with
  `a`=api_id, `h`=hash, `t`=unique_id. Hash = `md5(base64_encode(last6(t) . api_key
  . first6(t)))`. Verified three ways: PDF formula + live `AUTHOK` + user screenshot
  sample vector.
- **Account live-verified:** balance `$100.00`, `testmode=disabled`. No documents
  submitted, no charges incurred.
- Letter *content* still lives on `claims` (subject/body/tier) and is generated by
  `analysis.recommend_letter()` (deterministic, no LLM) — the `letters` queue is the
  physical-send layer on top.
- **Queue UI is wired and smoke-tested (2026-08-25, task ls7).** `letter-queue.html` is
  a functional queue: filterable list, status badges, Approve / Price & Queue /
  Confirm & Mail / Track actions, and a New Letter modal (claim picker + structured
  recipient + mail class). `GET /api/staff/letters` now joins `claims` to expose
  `claim_number`. Verified via live API lifecycle + Node render harness + 9-page HTTP
  smoke (all 200).
- LetterStream callback is **NOT enabled yet** — the receiver is live and tested, but
  the callback toggle in the LetterStream dashboard stays off until after the first
  real send is confirmed.

## Target state

A durable letter queue: many letters per claim, each with a lifecycle
(draft -> approved -> queued -> sent -> delivered/failed), sendable via
LetterStream certified mail, with FDCPA-compliant content and a full audit trail.

## 1. Data model - new `letters` table

| Column | Type | Purpose |
|---|---|---|
| id | TEXT PK | uuid4 |
| claim_id | TEXT FK -> claims.id | owning claim |
| letter_type | TEXT | demand / escalation / validation / custom |
| tier | TEXT | tier the letter was generated for |
| subject | TEXT | letter subject |
| body | TEXT | letter body (markdown or plain) |
| status | TEXT | draft / approved / queued / sending / sent / delivered / failed |
| recipient_name | TEXT | debtor or registered-agent name |
| addr1, addr2, city, state, zip | TEXT | mailing address |
| letterstream_job_id | TEXT | LetterStream job reference (nullable) |
| tracking_number | TEXT | USPS tracking (nullable) |
| sent_at | TEXT | ISO timestamp (nullable) |
| delivered_at | TEXT | ISO timestamp (nullable) |
| error | TEXT | last send error (nullable) |
| created_by | TEXT | RBAC actor name |
| created_at / updated_at | TEXT | ISO timestamps |

Migration: keep the four claim columns as the "current draft" during transition,
then deprecate them once the queue is live. No destructive drop until the queue
is proven in production.

## 2. API

- `GET /api/staff/claims/{n}/letters` - list letters for a claim
- `POST /api/staff/claims/{n}/letters/generate` - generate a draft row via
  `recommend_letter()` (inserts, does not overwrite the claim columns)
- `PUT /api/staff/letters/{id}` - edit a draft
- `POST /api/staff/letters/{id}/queue` - mark queued (requires full mailing address)
- `POST /api/staff/letters/{id}/send` - call LetterStream, store job_id + tracking
- `POST /api/letters/webhook` - LetterStream status callback (delivered / failed)
- `GET /api/staff/letters` - global queue across claims (feeds letter-queue.html)

Idempotency: `send` is guarded by status (only `queued` -> `sending`), so a
double-click cannot mail a letter twice. Store `letterstream_job_id` before
marking sent.

## 3. Send pipeline (LetterStream)

Order of work:

1. Verify the existing `LETTERSTREAM_API_KEY` against their API (is it valid,
   what account, what products are enabled).
2. Map their REST surface: auth method, endpoint shape, certified vs
   first-class, PDF upload vs HTML/plain rendering, return address handling,
   tracking + status webhook. Do not assume - confirm from their docs or a test
   call.
3. PDF generation: render the letter body (reportlab or weasyprint) with DRE
   letterhead, or pass content to LetterStream to render.
4. Address handling: return address (DRE office / PO box) and debtor mailing
   address must both be resolved before send.
5. Status sync: webhook or poll updates `status`, `tracking_number`,
   `delivered_at`.

## 4. Compliance (FDCPA)

- Every first-contact letter MUST carry the 1692g validation notice: amount of
  debt, creditor name, 30-day dispute right, right to request verification.
- No false, deceptive, or misleading language (1692e); no threats of action DRE
  does not intend to take.
- Human sign-off gate: a letter cannot move to `queued` until status is
  `approved` (actor recorded).
- Full immutable audit log (actor + timestamp + old/new) - the `audit_log`
  pattern already exists and extends here.

## 5. UI (letter-queue.html) — DONE 2026-08-25 (ls7)

`/var/www/internal/letter-queue.html` is live:
- filterable list (status) with per-status summary chips
- Approve (DRAFT) / Price & Queue (APPROVED/PREAUTH/ERROR) / Confirm & Mail (PREAUTH) / Reject / Cancel / Track actions
- status badges (DRAFT/APPROVED/PREAUTH/SENT/REJECTED/CANCELLED/ERROR)
- tracking timeline (USPS scan events) in the detail panel
- New Letter modal: claim picker (prefills debtor name), structured recipient, mail class

Reject/cancel implemented 2026-08-25: `POST /api/staff/letters/{id}/reject` (requires `reason`) and
`POST /api/staff/letters/{id}/cancel` (optional `reason`) move DRAFT/APPROVED/PREAUTH/ERROR letters to
REJECTED/CANCELLED, persist the reason in `letters.note`, and write an `audit_log` row. Guards return 409
for SENT/REJECTED/CANCELLED and 422 for a missing reject reason. Queue UI has Reject (red) / Cancel buttons
for all non-terminal states.

## 6. Decisions locked (2026-08-24)

1. **LetterStream key** — valid and live; `$100.00` balance, `testmode=disabled`.
2. **Return address** — Germaine provides it 2026-08-25. Set as
   `LETTERSTREAM_RETURN_ADDRESS` in `.env`; drafting does NOT block on it, only
   `send` does (clean 409 until configured).
3. **Signatory** — `Debt Recovery Experts LLC` (no named individual). Default in code;
   overridable via `LETTERSTREAM_SIGNATORY` in `.env`.
4. **Address verification / NCOA** — none. Pull debtor/return-address data from the
   client's claim info + Super Search.
5. **FDCPA 1692g notice** — mandatory on first contact (DRE is a third-party debt
   collector). Content is generated by `analysis.recommend_letter()`; final validation-
   notice wording vs welcome-packet copy still to be finalized (task ls8).