From f110c2eecb95a911b1487fc6fcd2534860d3d996 Mon Sep 17 00:00:00 2001
From: Scott Idem <stidem@gmail.com>
Date: Tue, 10 Mar 2026 19:30:01 -0400
Subject: [PATCH] docs: Expand TODO with Novi-Mailman bridge details and
 session notes

- Add confirmed Novi API patterns (auth, field names, endpoints)
- List remaining unknowns and data_store credential setup requirements
- Add pydantic/SQLAlchemy migration notes
- Summarize completed operational hardening and BuildKit cache work

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 documentation/TODO__Agents.md | 24 +++++++++++++++++++++++-
 1 file changed, 23 insertions(+), 1 deletion(-)

diff --git a/documentation/TODO__Agents.md b/documentation/TODO__Agents.md
index af8afbc..7d9d611 100644
--- a/documentation/TODO__Agents.md
+++ b/documentation/TODO__Agents.md
@@ -33,7 +33,26 @@
 
 ## 🚧 Strategic Goals (V3.5+)
 - [ ] **Pydantic V2 / SQLAlchemy 2.0:** Major framework upgrade for performance and type safety.
-- [~] **Novi-Mailman Bridge:** Synchronization between Novi AMS and Mailman 3. (Scaffolded — needs Novi field name verification + credential setup in data_store)
+    - SQLAlchemy 2.0 is likely the easier migration (additive, legacy mode available).
+    - Pydantic v2 touches every model definition — do this second.
+    - Current pins: `pydantic==1.*`, `SQLAlchemy==1.4.52` — intentional, do not remove until migration is done.
+- [~] **Novi-Mailman Bridge:** Synchronization between Novi AMS and Mailman 3.
+    - Files: `app/methods/e_novi_mailman_methods.py`, `app/routers/api_v3_actions_e_novi_mailman.py`
+    - Registered at `/v3/action/e_novi_mailman/`
+    - **Confirmed from IDAA Jitsi code:**
+        - Auth: `Authorization: Basic {api_key}` (Base64-encoded key stored in `data_store`)
+        - Novi member fields are PascalCase: `Email`, `FirstName`, `LastName`, `Name`
+        - Individual member lookup: `GET /customers/{uuid}`
+        - Group member list: `GET /groups/{guid}/members?pageSize=200` (returns `Results` or `Members` key)
+        - Emails may contain spaces instead of `+` — sanitize with `.replace(' ', '+')`
+    - **Still needs confirmation:**
+        - Bulk member list endpoint (likely `/members` or `/customers`) — hit `/novi/members` route after creds are set to inspect
+        - `MembershipStatus` field name in bulk response (may be `Status`)
+        - Webhook `EventType` values and payload shape (check Novi webhook docs)
+    - **data_store setup required (two records):**
+        - `novi_api_config` → `{"api_key": "<base64-key>", "base_url": "https://www.idaa.org/api", "mailman_list_id": "members@yourdomain.org"}`
+        - `mailman_api_config` → `{"base_url": "http://<host>:8001", "username": "restadmin", "password": "<password>"}`
+    - **Outstanding TODO in code:** Webhook HMAC signature verification once Novi webhook secret is known.
 - [ ] **Lookup System Batch 2:** Migration of `post_topic`, `user_status`, `file_purpose`.
 - [ ] **Zoom Events Integration:** Implement cron synchronization for OAuth2 ticket retrieval.
 
@@ -41,3 +60,6 @@
 - **Unified Stack:** Merged API orchestration into the master environment.
 - **Root Assets:** Docker assets are now part of this git repo again.
 - **Pruning:** Successfully reduced dependency bloat in `requirements.txt`.
+- **Operational Hardening complete:** Healthcheck, config refactor (pydantic-settings), requirements.lock all done.
+- **BuildKit pip cache:** Dockerfile now uses `--mount=type=cache` — rebuild with `docker compose up -d --build ae_api`.
+- **Novi-Mailman Bridge scaffolded:** Auth pattern and field names confirmed from existing IDAA Jitsi frontend code.