feat(imap): implement flag-based SEARCH criteria (ANSWERED/DELETED/DRAFT/FLAGGED/SEEN/UNSEEN)

[ssilvius]

Problem

The IMAP SEARCH command parser in `packages/imap/src/protocol/parser.ts` does not recognize flag-based search criteria. Any client sending `SEARCH UNSEEN`, `SEARCH SEEN`, `SEARCH ANSWERED`, `SEARCH DELETED`, `SEARCH DRAFT`, or `SEARCH FLAGGED` receives:

```
a001 BAD Unknown search criterion: UNSEEN
```

These are all RFC 3501 Section 6.4.4 criteria and are used heavily by mainstream clients:

• Apple Mail: `SEARCH UNSEEN` on folder select to build the unread badge
• Thunderbird: `SEARCH FLAGGED` for the "Starred" smart folder
• K-9 Mail: `SEARCH UNSEEN SINCE ` for "new mail since last check"
• Outlook: `SEARCH ANSWERED` for the "Replied" view

Without support, these UI elements either fail to populate or hit the error path.

Current state

Verified by reading `packages/imap/src/protocol/parser.ts` directly. The switch statement in `parseCriterion` has cases for: ALL, NEW, FROM, TO, CC, BCC, SUBJECT, BEFORE, ON, SINCE, LARGER, SMALLER, TEXT, BODY, UID, NOT, OR, plus bare sequence sets. No flag-based cases.

The `MessageAdapter.searchMessages` interface signature already accepts a criterion shape that could carry flag comparisons -- the gap is in the parser, not the adapter.

Fix scope

1. Extend `SearchCriterion` type in parser.ts to include flag variants
2. Add case statements in `parseCriterion` for ANSWERED, DELETED, DRAFT, FLAGGED, SEEN, UNSEEN
3. Update `searchMessages` implementations to evaluate flag criteria against the message's `isRead`, `isStarred`, `deletedAt`, and thread-reply / folder-slug derivations
4. Add tests referencing RFC 3501 Section 6.4.4 for each criterion
5. Also consider: KEYWORD, UNKEYWORD, HEADER, SENTBEFORE / SENTON / SENTSINCE -- all RFC 3501 criteria that are similarly unimplemented. Could be a follow-up issue if this one gets too large.

Related

• Doc gap already fixed in PR docs: fix interface drift across adapters.md, better-auth-resend, react-email #81: `packages/imap/docs/commands.md` now accurately lists the supported criteria and flags the missing ones.
• Discovered during the doc accuracy audit pass on PR docs: fix interface drift across adapters.md, better-auth-resend, react-email #81.

[ssilvius]

Closing as invalid. I filed this based on an incomplete audit of parser.ts -- I grepped for case " in parseCriterion and counted 17 switch entries, concluding the flag-based criteria were missing. I missed the FLAG_CRITERIA lookup table earlier in the same function:

const FLAG_CRITERIA: Record<string, { flag: string; negated: boolean }> = {
  ANSWERED, DELETED, DRAFT, FLAGGED, SEEN, RECENT,
  UNANSWERED, UNDELETED, UNDRAFT, UNFLAGGED, UNSEEN, OLD,
};

The table dispatches all 12 flag variants plus RECENT/OLD BEFORE the switch runs. Parser tests at packages/imap/tests/protocol/parser.test.ts:326 cover ANSWERED and DELETED/UNDELETED explicitly.

There is no implementation gap. PR #84 reverts the incorrect 'not yet supported' section I added to commands.md in PR #81 and restores the correct list with reference to FLAG_CRITERIA + test coverage so a future reader cannot repeat the same mistake.

The actual remaining unsupported criteria are narrower: KEYWORD, UNKEYWORD, HEADER, SENTBEFORE / SENTON / SENTSINCE. If any of those turn out to be load-bearing for mainstream clients I'll file a new, accurate issue.

Please close this when you see it.