Initial skills documentation — 25 categories, all SKILL.md + references + scripts

2026-07-15 17:42:20 -04:00
commit 1b4fcd4427
976 changed files with 188344 additions and 0 deletions
@@ -0,0 +1,70 @@
+# DRE Mail Poller Pattern
+
+Session: July 8, 2026
+
+## Overview
+
+Lightweight no-LLM IMAP poller that checks multiple DRE mailboxes on MXroute, parses headers + body, and writes a rolling JSON database for a web portal.
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+| `/root/.hermes/scripts/dre-mail-poller.py` | Main poller script |
+| `/var/www/internal/data/dre-mails.json` | Output JSON database |
+| `/var/log/dre-mail-poller.log` | Log file |
+| `/etc/cron.d/dre-mail-poller` | Cron config (every minute) |
+
+## IMAP Server
+
+- **Host:** `heracles.mxrouting.net:993`
+- **Mailboxes:**
+  - `dre@debtrecoveryexperts.com` / `M8ke.Money.Honey!`
+  - `collections@debtrecoveryexperts.com` / `M8ke.Money.Honey!`
+
+The password is shared across both mailboxes — the MXroute cPanel config uses the same password for all mailboxes under that domain.
+
+## Script Architecture
+
+```python
+MAILBOXES = [
+    {"label": "dre", "user": "dre@debtrecoveryexperts.com", "pass": "M8ke.Money.Honey!"},
+    {"label": "collections", "user": "collections@debtrecoveryexperts.com", "pass": "M8ke.Money.Honey!"},
+]
+```
+
+Each mailbox iterates independently. A connection failure on one doesn't block the other.
+
+## Deduplication
+
+Composite key: `{label}:{IMAP_UID}`. UIDs are stable per-mailbox in IMAP. Existing IDs loaded from JSON file into a `set()` on each run; new messages appended only when `id` not in set.
+
+## Output schema
+
+```json
+{
+  "id": "dre:12345",
+  "mailbox": "dre",
+  "from": "John Doe <john@example.com>",
+  "to": "dre@debtrecoveryexperts.com",
+  "subject": "Invoice #123",
+  "date": "2025-07-08T09:38:00+00:00",
+  "body_preview": "First 500 chars...",
+  "body": "Full plain-text body...",
+  "is_read": false,
+  "claim_match": "DRE-2025-0001"
+}
+```
+
+`claim_match` is extracted via `re.search(r'DRE-\d{4}-\d{4}', subject)`.
+
+## Caddy integration
+
+No Caddy changes needed — the existing `internal.debtrecoveryexperts.com` block already has `root * /var/www/internal` and `file_server`. The JSON is served at `/data/dre-mails.json` without any extra config.
+
+## Pitfalls
+
+- **Connection timeouts:** MXroute can be slow (1-2s per connect). Script uses `imaplib.IMAP4_SSL` with default timeout which is usually sufficient.
+- **Large bodies:** Some emails have megabytes of HTML. Body extraction with stdlib is fast but the rolling DB cap (500 entries) prevents unbounded growth.
+- **UNSEEN only:** The poller fetches `UNSEEN` and never marks messages as `SEEN`. This means the same mail appears on every poll until a real email client reads it. The dedup set prevents duplicate entries in the JSON.
+- **Body extraction order:** `text/plain` → `text/html` → any `text/*`. HTML-only messages (common from Apple Mail replies) are handled by the HTML fallback.