Adds the high-level mail folder walk that sync pipelines need on top of
the raw mail API (list -> get -> download-attachment), so consumers stop
re-implementing it against private client copies.
type MailSyncMessage struct { ID, Folder, Subject, From, Date, IsNew,
HasAttachments, Attachments }
type MailSyncAttachment struct { ID, Name, Size, Body }
func (c *Client) FetchMailFolder(ctx, folderID, MailSyncOptions)
([]MailSyncMessage, error)
Options: Limit / StartIndex for checkpointed walks, FetchBodies to
eagerly download attachment bytes via download.ashx (session-cookie path).
Hydration details:
- list items may omit the attachment array; when hasAttachments is set
the full record is fetched and its attachments merged
- attachment ids accepted from id/fileId/attachmentId variants
- timestamps parsed from RFC3339 (any fractional digits) and
second-precision forms
This is the first step of the 2dph integration layer (#1): the brain's
mail-ingest pipeline can now drop its private OOClient copy and consume
this canonical walk directly.
Tests: httptest-backed coverage for pagination, hydration with
full-record fallback, body download incl. auth-cookie requirement,
Limit/StartIndex windows, timestamp parsing.
