@dawnlit/outlook-bridge 1.1.1 → 2.0.0

package/dist/types.d.ts

@@ -1,123 +1,157 @@
+/**
+ * Where an email lives, as a listing reported it.
+ *
+ * Every listing row (`InboxEmail`, `InboxSearchMatch`, `SelectedEmail`, …)
+ * carries both fields, so a row can be passed straight back in wherever an
+ * `EmailRef` is accepted — which is also the reliable way to keep the two ids
+ * from different rows apart.
+ */
+export interface EmailLocator {
+    /** Windows: the MAPI EntryID. macOS: Outlook for Mac's integer message id. */
+    readonly entryId: string;
+    /**
+     * Windows: the StoreID the email was listed from, which lets it resolve in
+     * any mounted mailbox rather than only the default one. macOS has no
+     * equivalent and ignores it.
+     */
+    readonly storeId?: string;
+}
+/** An email to act on: its entry id alone, or anything carrying a locator. */
+export type EmailRef = string | EmailLocator;
+/**
+ * Recipients: one address, a comma- or semicolon-separated list, or an array.
+ * Display-name forms such as `"Doe, Jo" <jo@example.com>` are kept whole.
+ */
+export type Recipients = string | readonly string[];
 export interface SendEmailParams {
-    /** SMTP address of the account to send from. Never falls back to the default
-     *  account — an address that doesn't resolve is an error, not a silent switch. */
+    /** SMTP address of the mailbox to send from. Never falls back to the
+     *  default account — an address that doesn't resolve is an error. */
     emailAccount: string;
-    /** One or more addresses, comma- or semicolon-separated. */
-    to: string;
-    cc?: string;
+    to?: Recipients;
+    cc?: Recipients;
+    bcc?: Recipients;
     subject: string;
     htmlBody: string;
-    attachmentPath?: string;
-    sendImmediately: boolean;
+    /** Absolute paths of files to attach. Each has to exist. */
+    attachments?: readonly string[];
+    /**
+     * An Outlook signature, by the name listOutlookSignatures reports, added to
+     * the body: in its `{{SIGNATURE}}` placeholder when it has one, otherwise
+     * at the end. Outlook adds no signature of its own to a body set this way,
+     * so this is how a composed email gets one.
+     */
+    signatureName?: string;
+    /** Send now. Default false: the email is staged as a draft instead. */
+    sendImmediately?: boolean;
     /**
-     * Draft mode only. True pops an Outlook compose window per email; false saves
-     * straight to Drafts with no window — the only workable option for batches.
-     * Defaults to true, matching the single-email callers that rely on the window.
+     * Drafts only. True (the default) opens an Outlook compose window; false
+     * files the draft silently into Drafts — the workable choice for batches.
      */
     openDraftWindow?: boolean;
 }
-export interface ReplyEmailParams {
+export interface ReplyEmailParams extends EmailLocator {
+    /** SMTP address of the mailbox to reply from. */
     emailAccount: string;
-    entryId: string;
-    /** StoreID from the same listing row — disambiguates across mailboxes. */
-    storeId?: string;
     /**
-     * HTML inserted above the quoted original (a full document is reduced to its <body>
-     * content). Optional when `templateSubject` is given — the body is then resolved from
-     * the saved template server-side, so the caller never has to carry the (often large,
-     * Word-generated) template HTML.
+     * HTML inserted above the quoted original (a full document is reduced to
+     * its <body> content). Optional when `templateSubject` is given.
      */
     htmlBody?: string;
-    /** Reply with a saved template's body, resolved by subject from the mailbox — an
-     *  alternative to htmlBody that keeps a big template out of the caller's payload. */
+    /**
+     * Reply with a template email saved in the mailbox, found by subject, so
+     * the caller never carries a large template's HTML itself.
+     */
     templateSubject?: string;
-    /** Folder holding the template when templateSubject is used (default 'Templates'). */
+    /** Folder holding the template. Default 'Templates'. */
     templateFolder?: string;
     /**
-     * Section of the template to keep when one template holds several reply variants
-     * between [[SECTION]] markers (see outlookTemplateSections). The other sections and
-     * all markers are stripped before the reply is built.
+     * The [[SECTION]] of the template to keep, when one template holds several
+     * reply variants (see composeTemplateBody). Required if it has sections.
      */
     templateSection?: string;
     /** `{{PLACEHOLDER}}` → HTML substituted into the composed body. */
-    templatePlaceholders?: Record<string, string>;
+    templatePlaceholders?: Readonly<Record<string, string>>;
     /**
-     * Name of an Outlook signature (as listed by listOutlookSignatures) to substitute
-     * into the template's `{{SIGNATURE}}` placeholder. Resolved by the package rather
-     * than by the caller, so the signature HTML — images and all — never crosses the wire.
+     * An Outlook signature (by the name listOutlookSignatures reports), put in
+     * the body's `{{SIGNATURE}}` placeholder, or below the new text when there
+     * is none. Resolved here, so the signature's HTML never crosses the
+     * caller's boundary.
      */
     signatureName?: string;
     /**
-     * Answer every recipient of the original (Reply All) rather than just its
-     * sender. Off by default: widening a reply is the kind of mistake that can't
-     * be taken back, so it has to be asked for.
+     * Answer every recipient of the original instead of only its sender.
+     * Default false: widening a reply cannot be taken back, so it is opt-in.
      */
     replyAll?: boolean;
+    /** Send now. Default false. */
     sendImmediately?: boolean;
+    /** Drafts only: open a compose window (the default) or file silently. */
     openDraftWindow?: boolean;
 }
 export interface ReplyEmailResult {
+    /** Who the reply is addressed to. Windows reports Outlook's To line
+     *  (display names); macOS the resolved addresses. */
     to: string;
     subject: string;
-    /** The original email's sender — verify it's who you meant to answer. */
+    /** The original email's sender — check it is who you meant to answer. */
     repliedToSender: string;
 }
-/** One draft that couldn't be sent, identified by its subject for the report. */
-export interface DraftSendFailure {
+/** One item a batch operation could not handle, and why. */
+export interface ItemFailure {
+    entryId: string;
+    /** The item's subject when it could be read, else ''. */
     subject: string;
     error: string;
 }
-export interface SendAllDraftsResult {
-    sent: number;
-    failed: DraftSendFailure[];
-}
 /** One mail draft belonging to an account. */
 export interface OutlookDraft {
     entryId: string;
     subject: string;
-    /** The To line as Outlook renders it (display names). */
+    /** The To line as Outlook renders it. */
     to: string;
-    /** Recipient addresses, best-effort — an unresolved Exchange entry falls back to its name. */
+    /** Recipient addresses, best effort — an unresolved Exchange entry falls back to its name. */
     toEmails: string[];
-    /** Short plain-text preview — enough to tell one template section from another. */
+    /** Short plain-text preview, enough to tell similar drafts apart. */
     bodyPreview: string;
     hasAttachments: boolean;
     lastModified: string;
-    /** Which Drafts folder it sits in, since two can hold one account's mail. */
+    /** The Drafts folder it sits in; one account's drafts can span two. */
     folderPath: string;
 }
+export interface ListDraftsOptions {
+    /** Newest-first cap on the drafts returned. Default 100. */
+    limit?: number;
+    /** Characters of body preview per draft. Default 300; 0 omits it. */
+    previewChars?: number;
+}
 export interface ListDraftsResult {
     account: string;
     /** The Drafts folders scanned, in scan order. */
     foldersScanned: string[];
-    /** Total matching drafts found, before `limit` was applied. */
+    /** Matching drafts found, before `limit` was applied. */
     count: number;
     truncated: boolean;
     drafts: OutlookDraft[];
 }
+export interface SendDraftsResult {
+    sent: number;
+    failed: ItemFailure[];
+}
 export interface DeleteDraftsResult {
     deleted: number;
-    failed: {
-        entryId: string;
-        error: string;
-    }[];
-}
-/** One draft that couldn't be sent in a selective send, identified by both id and
- *  subject — id for the caller to retry or reconcile, subject for a human report. */
-export interface SendDraftsFailure {
-    entryId: string;
-    subject: string;
-    error: string;
+    failed: ItemFailure[];
 }
-export interface SendDraftsResult {
-    sent: number;
-    failed: SendDraftsFailure[];
+export interface DeleteMailOptions {
+    /** Lift the refusal to touch Inbox and Sent Items (and their subfolders). */
+    allowProtected?: boolean;
+    /** Resolve and report every id without deleting anything. */
+    dryRun?: boolean;
 }
 /** What happened to one id in a deleteOutlookEmails call. */
 export interface DeleteMailOutcome {
     entryId: string;
     subject: string;
-    /** The folder the item was actually in — the audit trail for what you deleted. */
+    /** The folder the item was actually in — the audit trail for a wrong id. */
     folderPath: string;
     status: 'deleted' | 'would-delete' | 'refused' | 'failed';
     reason: string;
@@ -129,10 +163,10 @@ export interface DeleteMailResult {
     failed: number;
     items: DeleteMailOutcome[];
 }
-export interface DeleteMailOptions {
-    /** Lift the Inbox/Sent Items refusal, taking responsibility for reaching received mail. */
-    allowProtected?: boolean;
-    /** Resolve and report without deleting anything. */
+export interface PurgeDeletedItemsOptions {
+    /** Keep items newer than this many days. Default 0: purge everything. */
+    olderThanDays?: number;
+    /** Count what would be purged without destroying anything. */
     dryRun?: boolean;
 }
 export interface PurgeDeletedItemsResult {
@@ -145,86 +179,194 @@ export interface PurgeDeletedItemsResult {
     kept: number;
     failed: number;
 }
-/** One bounce-back / non-delivery message found in the inbox. */
+/** One bounce-back / non-delivery message found in a mailbox. */
 export interface UndeliverableEmail {
     entryId: string;
     subject: string;
     senderName: string;
     senderEmail: string;
     receivedTime: string;
-    /** Which rule flagged it (NDR class, mail-daemon sender, or a bounce subject phrase). */
+    /** Which rule flagged it: an NDR message class, a mail-daemon sender, or a bounce subject phrase. */
     matchedReason: string;
-    /** Best-effort recipient addresses parsed from the bounce body — which sends failed. */
+    /** Best-effort addresses parsed from the bounce body — the sends that failed. */
     failedRecipients: string[];
 }
+export interface CleanUndeliverableOptions {
+    /** How far back to scan. Default 30. */
+    daysBack?: number;
+    /** Report without deleting. Default TRUE — deleting has to be asked for. */
+    dryRun?: boolean;
+}
 export interface CleanUndeliverableResult {
     account: string;
     scannedDays: number;
-    /** True when nothing was deleted (preview run). */
     dryRun: boolean;
     matchedCount: number;
     deletedCount: number;
     matched: UndeliverableEmail[];
-    /** Matched items that could not be deleted (only populated on a delete run). */
-    failed: DraftSendFailure[];
+    /** Matched items that could not be deleted (a delete run only). */
+    failed: ItemFailure[];
+}
+export interface CollectBouncedRecipientsOptions {
+    /** How far back to scan. Default 30. */
+    daysBack?: number;
+    /** Scan Deleted Items too, so bounces already cleaned away still count. Default true. */
+    includeDeletedItems?: boolean;
 }
-/** One sent message and the full set of SMTP addresses it went to. */
+export interface SentRecipientGroupsOptions {
+    /** How far back to read Sent Items. Default 30. */
+    daysBack?: number;
+    /** Newest-first cap on messages. Default 3000. */
+    limit?: number;
+}
+/** One sent message and every SMTP address it went to (To, CC and BCC). */
 export interface SentRecipientGroup {
     entryId: string;
     subject: string;
     sentOn: string;
     recipients: string[];
 }
-export interface InboxEmail {
+export interface BounceReportOptions {
+    /** How far back to read bounce-backs and Sent Items. Default 30. */
+    daysBack?: number;
+    /** Count bounces already moved to Deleted Items too. Default true. */
+    includeDeletedItems?: boolean;
+}
+/** A sent message that at least one of its recipients bounced back from. */
+export interface BouncedSend {
+    entryId: string;
+    subject: string;
+    sentOn: string;
+    /** Every address it went to, lower-cased and deduplicated. */
+    recipients: string[];
+    /** The recipients a bounce-back reported as failed. */
+    failedRecipients: string[];
+    /** True when every recipient failed: the message reached nobody. */
+    allFailed: boolean;
+}
+export interface BounceReport {
+    account: string;
+    scannedDays: number;
+    /** Every distinct address the bounce-backs reported, lower-cased. */
+    bouncedAddresses: string[];
+    /** The sent messages with a bounced recipient, newest first. */
+    sends: BouncedSend[];
+    /**
+     * Bounced addresses no sent message in the window went to: an alias the
+     * server expanded, or a send older than the window.
+     */
+    unmatchedAddresses: string[];
+}
+export interface ReadInboxOptions {
+    /**
+     * Read this folder instead of the Inbox root: a folder under the Inbox by
+     * name or path, a well-known folder ('Sent Items', 'Drafts', …), or a full
+     * folder path — see mailFolderRef. Only that folder is read, not its
+     * subfolders.
+     */
+    folder?: string;
+    /** Only mail from the last this-many days. Default 60. */
+    daysBack?: number;
+    /** Newest-first cap on rows. Default 50. */
+    limit?: number;
+    /** Characters of plain-text body per row. Default 600; 0 skips reading bodies. */
+    previewChars?: number;
+}
+export interface InboxEmail extends EmailLocator {
     entryId: string;
     storeId: string;
     subject: string;
+    /** For outgoing folders (Sent Items, Outbox, Drafts) these carry the
+     *  RECIPIENT, since a folder of mail "from" its own owner says nothing. */
     senderName: string;
     senderEmail: string;
     receivedTime: string;
     bodyPreview: string;
     attachmentNames: string[];
     attachmentCount: number;
-    /** Outlook path of the folder each email was read from, so a caller that
-     *  scoped to a subfolder can confirm which folder actually matched.
-     *  Populated on both platforms. */
-    folderPath?: string;
+    /** The folder the email was read from. */
+    folderPath: string;
 }
 export interface InboxSearchFilter {
-    /** Glob-style subject pattern — `*` and `?` wildcards, e.g. '*invoice*'.
-     *  Handed to Items.Restrict as the server-side prefilter that keeps a
-     *  full-mailbox walk cheap, and re-checked against every subject that
-     *  comes back, so it filters the result set on stores that won't run the
-     *  query as well. Omit to restrict on date only. */
+    /** Only mail from the last this-many days. Default 60 — a scan has no
+     *  unbounded mode; ask for 365 to reach back a year. */
+    daysBack?: number;
+    /** Glob-style subject pattern: `*` matches any run, `?` one character,
+     *  case-insensitive, e.g. '*invoice*'. */
     subjectLike?: string;
-    /** Regex re-checked client-side against each survivor's trimmed subject,
-     *  since Restrict's `like` is a blunt substring match. A normal JS
-     *  RegExp — only its `.source` crosses into the PowerShell/.NET regex
-     *  engine, which reads the same syntax; `-match` is case-insensitive
-     *  there by default regardless of the JS pattern's `i` flag. */
+    /**
+     * Regular expression tested against each subject, case-insensitively
+     * whatever the RegExp's own flags. On Windows the pattern runs in .NET's
+     * regex engine, so keep to syntax JavaScript and .NET share.
+     */
     subjectPattern?: RegExp;
-    /** Drop subjects starting with Re:/Fw:/Fwd:. */
+    /** Drop subjects carrying a reply or forward prefix (RE:, FW:, AW:, 回复:, …). */
     excludeReplies?: boolean;
-    /** Only return items carrying at least one attachment. */
+    /** Only return mail with at least one attachment. */
     requireAttachment?: boolean;
+    /**
+     * Folders under the Inbox to leave out, by full folder path or bare name,
+     * case-insensitively. An excluded folder takes its whole subtree with it.
+     * Sent, Drafts, Deleted and Junk are always skipped, even where the profile
+     * nests them under the Inbox. macOS matches the leaf name only.
+     */
+    excludeFolders?: readonly string[];
+    /**
+     * Scan only these folders, given the same way. Matched exactly: naming a
+     * folder does not bring its children, and the Inbox root is included only
+     * when named. Exclusion wins where the two overlap.
+     */
+    includeFolders?: readonly string[];
+    /** Return each match's full plain-text body. Default true; false makes a
+     *  scan much lighter when only the metadata is needed. */
+    includeBody?: boolean;
 }
-export interface InboxSearchMatch {
+export interface InboxSearchMatch extends EmailLocator {
     entryId: string;
-    /** Store the item lives in — pass alongside entryId so it resolves unambiguously
-     *  across mailboxes (replyOutlookEmail, saveEmailAttachments). */
     storeId: string;
     subject: string;
     senderName: string;
-    /** SMTP address; resolved from the Exchange DN when the sender is an EX recipient. */
+    /** SMTP address, resolved from the Exchange DN where the sender is an Exchange user. */
     senderEmail: string;
-    /** 'yyyy-MM-dd HH:mm'. */
     receivedTime: string;
+    /** The plain-text body; '' when the search asked for no bodies. */
     body: string;
-    /** Not saved to disk — pass the ones you want through saveEmailAttachments. */
+    /** Not saved to disk — pass the ones you want to saveEmailAttachments. */
     attachmentNames: string[];
     folderPath: string;
 }
-export interface SelectedEmail {
+/**
+ * What was kept about an email besides its id, for finding it again once the
+ * id no longer resolves: Outlook rewrites an email's id whenever it moves, and
+ * an id from one platform means nothing on the other.
+ *
+ * At least two of `subject`, `sender` and `receivedTime` are needed, since a
+ * subject alone names every message in a thread.
+ */
+export interface EmailDescription {
+    /** Compared without reply and forward prefixes, spacing or case. */
+    subject?: string;
+    /**
+     * An address, a display name, or both (`Jo Doe <jo@example.com>`). An
+     * address is compared as an address; a bare name only against the
+     * sender's display name.
+     */
+    sender?: string;
+    /** `yyyy-MM-dd HH:mm` as a listing reported it, or just the day. */
+    receivedTime?: string;
+    /** The mailbox to search. Default: every account, the one `folderPath` names first. */
+    emailAccount?: string;
+    /**
+     * The folderPath a listing reported (`\\team@example.com\Inbox\Invoices`).
+     * Only decides which mailbox is searched first.
+     */
+    folderPath?: string;
+}
+export interface LocateEmailOptions {
+    /** How far back to search when the description has no receivedTime. Default 60. */
+    daysBack?: number;
+}
+export interface SelectedEmail extends EmailLocator {
     entryId: string;
     storeId: string;
     subject: string;
@@ -232,9 +374,17 @@ export interface SelectedEmail {
     senderEmail: string;
     receivedTime: string;
     body: string;
-    /** Not saved to disk — pass the ones you want through saveEmailAttachments. */
+    /** Not saved to disk — pass the ones you want to saveEmailAttachments. */
     attachmentNames: string[];
 }
+export interface ReadEmailBodyOptions {
+    /** Cap on the returned body. Default 8000. */
+    maxChars?: number;
+    /** Also return the quoted thread below the reply. Default false. */
+    includeQuoted?: boolean;
+    /** Cap on the quoted thread when it is returned. Default 4000. */
+    maxQuotedChars?: number;
+}
 export interface EmailBodyResult {
     entryId: string;
     subject: string;
@@ -243,144 +393,187 @@ export interface EmailBodyResult {
     receivedTime: string;
     /** The sender's own new text — everything above the quoted thread. */
     body: string;
-    /** True when `body` hit maxChars and was cut. */
+    /** True when `body` was cut at maxChars. */
     truncated: boolean;
-    /** Length of the sender's new text before any capping. */
+    /** Length of the sender's new text before any cut. */
     bodyLength: number;
-    /** What the quoted thread was split on ("-----Original Message-----", …); empty when none was found. */
+    /** What the quoted thread was split on; '' when none was found. */
     quoteSeparator: string;
     /** Length of the quoted thread, reported even when it isn't returned. */
     quotedLength: number;
-    /** The quoted thread — only populated when the caller asked for it. */
+    /** The quoted thread — only when asked for. */
     quotedOriginal: string;
     attachmentNames: string[];
     attachmentCount: number;
 }
 export interface MailFolderRef {
-    /** olDefaultFolders id of the root the walk starts from. */
+    /** olDefaultFolders id of the well-known root the path starts from. */
     rootId: number;
-    /** That root's name, for error messages. */
+    /** That root as the caller spelled it, for messages. */
     rootLabel: string;
     /** Path segments below the root. */
     segments: string[];
 }
+export interface ListFoldersOptions {
+    /** How many levels below the Inbox to list, 1–10. Default 2. */
+    maxDepth?: number;
+}
 export interface InboxFolderInfo {
     name: string;
-    /** Outlook folder path, e.g. "\\\\mailbox\\Inbox\\Invoices". */
+    /** Outlook folder path, e.g. `\\mailbox\Inbox\Invoices`. */
     folderPath: string;
     itemCount: number;
-    /** 1 = direct child of Inbox, 2 = grandchild, … */
+    /** 1 = direct child of the Inbox, 2 = grandchild, … */
     depth: number;
 }
+export interface MoveEmailsOptions {
+    /** Create the destination — the whole missing chain — when absent. Default false. */
+    createIfMissing?: boolean;
+}
 export interface MoveEmailsResult {
     folderPath: string;
     folderCreated: boolean;
     moved: number;
-    failed: {
-        entryId: string;
-        error: string;
-    }[];
+    failed: ItemFailure[];
+}
+export interface SaveAttachmentOptions {
+    /**
+     * Directory to save into, created if absent. Without one, each call saves
+     * into a fresh private directory, so two emails that both carry
+     * 'invoice.pdf' can never overwrite each other.
+     */
+    destDir?: string;
 }
 export interface SavedAttachment {
+    /** Where the file was written. A name already taken in the directory gets
+     *  a numbered suffix rather than overwriting what is there. */
     path: string;
+    /** The attachment's name as the email carries it. */
+    fileName: string;
+    /** Who the email was from — confirm it is the email you meant. */
     subject: string;
     senderName: string;
     senderEmail: string;
     receivedTime: string;
 }
+export interface ReadTemplatesOptions {
+    /** Mailbox folder holding the templates, searched up to 3 levels deep. Default 'Templates'. */
+    folder?: string;
+    /** Return only the template with this subject (case-insensitive). */
+    subject?: string;
+    /** Return each full HTML body. Default true; false returns previews. */
+    includeBody?: boolean;
+    /** Newest-first cap on templates, 1–200. Default 20. */
+    limit?: number;
+}
 /** One template email stored in a mailbox folder. */
 export interface TemplateEmail {
     entryId: string;
     subject: string;
-    /** Full HTML body — reusable verbatim as another email's htmlBody. Empty when the
-     *  listing was requested without bodies (includeBody:false). */
+    /** Full HTML body with embedded (cid:) images removed; '' without includeBody. */
     htmlBody: string;
-    /** Short plain-text preview, returned instead of htmlBody when includeBody is false. */
-    bodyPreview?: string;
-    /** [[SECTION]] names when the template holds several reply variants (see
-     *  outlookTemplateSections) — returned with or without the body, so a caller can
-     *  confirm the sections it's about to ask for still exist. */
-    sections?: string[];
-    /** `{{PLACEHOLDER}}` names the template expects to have filled in. */
-    placeholders?: string[];
+    /** Short plain-text preview; '' with includeBody. */
+    bodyPreview: string;
+    /** [[SECTION]] names, returned with or without the body. */
+    sections: string[];
+    /** `{{PLACEHOLDER}}` names the template expects filled. */
+    placeholders: string[];
     lastModified: string;
 }
 export interface TemplateFolderResult {
     folderFound: boolean;
-    /** Outlook folder path when found, e.g. "\\\\mailbox\\Templates". */
+    /** The folder's path when found. */
     folderPath: string;
     templates: TemplateEmail[];
-    /** When the folder wasn't found: the mailbox's folder names, so the caller can pick or create one. */
+    /** When the folder wasn't found: the mailbox's top-level folder names. */
     availableFolders: string[];
 }
+export interface SaveTemplateParams {
+    subject: string;
+    htmlBody: string;
+    /** Folder to save into, created at the mailbox root if absent. Default 'Templates'. */
+    folder?: string;
+}
 export interface SaveTemplateResult {
     folderPath: string;
     folderCreated: boolean;
 }
 /**
- * What every platform implementation provides. `OutlookService` picks one at load
- * time and exposes it under these exact signatures.
- *
- * Not everything is implemented everywhere — macOS in particular still throws for
- * a good part of this. That is a runtime answer ("not implemented on this
- * platform"), deliberately not a type-level one: a consumer writing against the
- * package should see one signature per function, not a per-platform subset they
- * have to narrow.
+ * Everything the package does, under one signature per operation whatever the
+ * platform. A platform that cannot do something says so at run time — see
+ * `CapabilityMap` — rather than through a narrower type.
  */
 export interface OutlookBridge {
+    /** Every mailbox this Outlook profile can reach, as SMTP addresses. */
     getOutlookAccounts(): Promise<string[]>;
+    /** Send an email, or stage it as a draft. */
     sendOutlookEmail(params: SendEmailParams): Promise<void>;
+    /** Reply to an email, with the new text above the quoted original. */
     replyOutlookEmail(params: ReplyEmailParams): Promise<ReplyEmailResult>;
-    sendAllDrafts(emailAccount: string): Promise<SendAllDraftsResult>;
-    readInboxEmails(emailAccount: string, daysBack?: number, limit?: number, folder?: string): Promise<InboxEmail[]>;
-    searchInboxByFilter(emailAccount: string, filter?: InboxSearchFilter, daysBack?: number): Promise<InboxSearchMatch[]>;
+    /** Recent mail from the Inbox root or one named folder, newest first. */
+    readInboxEmails(emailAccount: string, options?: ReadInboxOptions): Promise<InboxEmail[]>;
+    /** Walk every folder under the Inbox for the mail matching `filter`. */
+    searchInboxByFilter(emailAccount: string, filter?: InboxSearchFilter): Promise<InboxSearchMatch[]>;
+    /** The email currently selected, or open, in Outlook. */
     readSelectedEmail(): Promise<SelectedEmail>;
-    readEmailBody(entryId: string, storeId?: string, maxChars?: number, includeQuoted?: boolean): Promise<EmailBodyResult>;
-    openOutlookEmail(entryId: string, storeId?: string): Promise<void>;
-    listInboxFolders(emailAccount: string, maxDepth?: number): Promise<InboxFolderInfo[]>;
-    moveOutlookEmails(emailAccount: string, entryIds: string[], folderName: string, createIfMissing?: boolean): Promise<MoveEmailsResult>;
-    listOutlookDrafts(emailAccount: string, limit?: number, previewChars?: number): Promise<ListDraftsResult>;
-    deleteOutlookDrafts(emailAccount: string, entryIds: string[]): Promise<DeleteDraftsResult>;
+    /** One email's plain-text body, split from the thread it quotes. */
+    readEmailBody(email: EmailRef, options?: ReadEmailBodyOptions): Promise<EmailBodyResult>;
+    /** Open an email in Outlook. */
+    openOutlookEmail(email: EmailRef): Promise<void>;
     /**
-     * Send a chosen subset of an account's drafts by EntryID — e.g. after
-     * `listOutlookDrafts` and a user review pass — rather than the account-wide
-     * `sendAllDrafts`. Same "must be THIS account's draft" gate as
-     * `deleteOutlookDrafts`: an id pointing at ordinary mail, or at another
-     * account's draft, is refused and reported rather than sent.
+     * Find an email again from what was kept about it, when its id no longer
+     * resolves. Searches the Inbox and its subfolders, and returns null rather
+     * than a guess: every field the description gives has to agree.
      */
-    sendDrafts(emailAccount: string, entryIds: string[]): Promise<SendDraftsResult>;
-    deleteOutlookEmails(emailAccount: string, entryIds: string[], options?: DeleteMailOptions): Promise<DeleteMailResult>;
-    purgeDeletedItems(emailAccount: string, olderThanDays?: number, dryRun?: boolean): Promise<PurgeDeletedItemsResult>;
-    saveEmailAttachment(entryId: string, fileName: string, storeId?: string, destDir?: string): Promise<string>;
-    saveEmailAttachmentDetailed(entryId: string, fileName: string, storeId?: string, destDir?: string): Promise<SavedAttachment>;
-    saveEmailAttachments(entryId: string, fileNames: string[], storeId?: string, destDir?: string): Promise<SavedAttachment[]>;
-    cleanUndeliverableEmails(emailAccount: string, daysBack?: number, dryRun?: boolean): Promise<CleanUndeliverableResult>;
-    collectBouncedRecipients(emailAccount: string, daysBack?: number, scanDeleted?: boolean): Promise<string[]>;
-    readSentRecipientGroups(emailAccount: string, daysBack?: number, limit?: number): Promise<SentRecipientGroup[]>;
+    locateEmail(description: EmailDescription, options?: LocateEmailOptions): Promise<InboxSearchMatch | null>;
+    /** The folders under an account's Inbox. */
+    listInboxFolders(emailAccount: string, options?: ListFoldersOptions): Promise<InboxFolderInfo[]>;
+    /** File emails into a folder. Moving rewrites each email's entry id. */
+    moveOutlookEmails(emailAccount: string, entryIds: readonly string[], folder: string, options?: MoveEmailsOptions): Promise<MoveEmailsResult>;
+    /** The mail drafts bound to an account, newest first. */
+    listOutlookDrafts(emailAccount: string, options?: ListDraftsOptions): Promise<ListDraftsResult>;
+    /** Send the named drafts — each has to be one of this account's drafts. */
+    sendDrafts(emailAccount: string, entryIds: readonly string[]): Promise<SendDraftsResult>;
+    /** Send every draft bound to an account. */
+    sendAllDrafts(emailAccount: string): Promise<SendDraftsResult>;
+    /** Delete the named drafts (into Deleted Items) — each has to be one of this account's drafts. */
+    deleteOutlookDrafts(emailAccount: string, entryIds: readonly string[]): Promise<DeleteDraftsResult>;
+    /** Delete mail by id into Deleted Items, refusing received and sent mail unless allowed. */
+    deleteOutlookEmails(emailAccount: string, entryIds: readonly string[], options?: DeleteMailOptions): Promise<DeleteMailResult>;
+    /** Permanently empty an account's Deleted Items. The one irreversible operation. */
+    purgeDeletedItems(emailAccount: string, options?: PurgeDeletedItemsOptions): Promise<PurgeDeletedItemsResult>;
+    /** Save one attachment to disk. */
+    saveEmailAttachment(email: EmailRef, fileName: string, options?: SaveAttachmentOptions): Promise<SavedAttachment>;
+    /** Save several attachments from one email, in the order named. */
+    saveEmailAttachments(email: EmailRef, fileNames: readonly string[], options?: SaveAttachmentOptions): Promise<SavedAttachment[]>;
+    /** Find bounce-backs in the Inbox and, unless dry-running, delete them. */
+    cleanUndeliverableEmails(emailAccount: string, options?: CleanUndeliverableOptions): Promise<CleanUndeliverableResult>;
+    /** The addresses bounce-backs report as having failed, deduplicated. */
+    collectBouncedRecipients(emailAccount: string, options?: CollectBouncedRecipientsOptions): Promise<string[]>;
+    /** Sent Items, each message with the full set of addresses it went to. */
+    readSentRecipientGroups(emailAccount: string, options?: SentRecipientGroupsOptions): Promise<SentRecipientGroup[]>;
+    /** Which sent messages bounced, and for which of their recipients. */
+    readBounceReport(emailAccount: string, options?: BounceReportOptions): Promise<BounceReport>;
+    /** The names of the Outlook signatures on this machine. */
     listOutlookSignatures(): Promise<string[]>;
+    /** A signature's HTML, or '' when there is no signature by that name. */
     readOutlookSignatureHtml(name: string): Promise<string>;
-    readTemplateEmails(emailAccount: string, folderName?: string, limit?: number, includeBody?: boolean, subject?: string): Promise<TemplateFolderResult>;
-    saveTemplateEmail(emailAccount: string, subject: string, htmlBody: string, folderName?: string): Promise<SaveTemplateResult>;
+    /** The template emails saved in a mailbox folder. */
+    readTemplateEmails(emailAccount: string, options?: ReadTemplatesOptions): Promise<TemplateFolderResult>;
+    /** Save a new template email. Always adds; never overwrites. */
+    saveTemplateEmail(emailAccount: string, template: SaveTemplateParams): Promise<SaveTemplateResult>;
+    /**
+     * Open HTML in an Outlook compose window, wait for the person editing it to
+     * save and close, and return what they saved. Has no timeout; cancel it
+     * with an AbortSignal.
+     */
     editEmailTemplate(label: string, currentHtml: string): Promise<string>;
 }
 /** Every operation whose availability can be asked about. */
 export type BridgeCapability = keyof OutlookBridge;
 /**
- * Which operations actually work on this machine.
- *
- * The alternative was matching on an error message: a consumer had no way to
- * learn a gap existed except by calling into it. A UI can now gray out the
- * buttons it can't back rather than discovering the gap when the user clicks one.
- *
- * Windows and macOS both answer the whole contract today, so every flag is
- * `true` on either; the map earns its place on the third case — any other OS,
- * where all of them are `false` and every call rejects with
- * `UNSUPPORTED_PLATFORM`. `false` is also how a platform would announce the
- * softer gap, an operation that answers emptily rather than throwing, so an
- * empty result there means "can't" rather than "none found".
- *
- * Each platform derives its map from its bridge object minus an explicit
- * not-ported list (see `shared/capabilities.ts`), and the key type is
- * `keyof OutlookBridge`, so a new function in the contract cannot be missed.
+ * Which operations work on this machine: all of them on Windows and macOS,
+ * none anywhere else. Lets a UI disable what it cannot back instead of
+ * discovering the gap when a user clicks.
  */
 export type CapabilityMap = Readonly<Record<BridgeCapability, boolean>>;