@dawnlit/outlook-bridge 1.0.0

package/dist/types.d.ts

@@ -0,0 +1,365 @@
+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. */
+    emailAccount: string;
+    /** One or more addresses, comma- or semicolon-separated. */
+    to: string;
+    cc?: string;
+    subject: string;
+    htmlBody: string;
+    attachmentPath?: string;
+    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.
+     */
+    openDraftWindow?: boolean;
+}
+export interface ReplyEmailParams {
+    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.
+     */
+    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. */
+    templateSubject?: string;
+    /** Folder holding the template when templateSubject is used (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.
+     */
+    templateSection?: string;
+    /** `{{PLACEHOLDER}}` → HTML substituted into the composed body. */
+    templatePlaceholders?: 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.
+     */
+    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.
+     */
+    replyAll?: boolean;
+    sendImmediately?: boolean;
+    openDraftWindow?: boolean;
+}
+export interface ReplyEmailResult {
+    to: string;
+    subject: string;
+    /** The original email's sender — verify it's who you meant to answer. */
+    repliedToSender: string;
+}
+/** One draft that couldn't be sent, identified by its subject for the report. */
+export interface DraftSendFailure {
+    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). */
+    to: string;
+    /** 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. */
+    bodyPreview: string;
+    hasAttachments: boolean;
+    lastModified: string;
+    /** Which Drafts folder it sits in, since two can hold one account's mail. */
+    folderPath: string;
+}
+export interface ListDraftsResult {
+    account: string;
+    /** The Drafts folders scanned, in scan order. */
+    foldersScanned: string[];
+    /** Total matching drafts found, before `limit` was applied. */
+    count: number;
+    truncated: boolean;
+    drafts: OutlookDraft[];
+}
+export interface DeleteDraftsResult {
+    deleted: number;
+    failed: {
+        entryId: string;
+        error: string;
+    }[];
+}
+/** 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. */
+    folderPath: string;
+    status: 'deleted' | 'would-delete' | 'refused' | 'failed';
+    reason: string;
+}
+export interface DeleteMailResult {
+    dryRun: boolean;
+    deleted: number;
+    refused: number;
+    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. */
+    dryRun?: boolean;
+}
+export interface PurgeDeletedItemsResult {
+    folderPath: string;
+    dryRun: boolean;
+    /** Items old enough to qualify. */
+    matched: number;
+    purged: number;
+    /** Items left because they were newer than `olderThanDays`. */
+    kept: number;
+    failed: number;
+}
+/** One bounce-back / non-delivery message found in the inbox. */
+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). */
+    matchedReason: string;
+    /** Best-effort recipient addresses parsed from the bounce body — which sends failed. */
+    failedRecipients: string[];
+}
+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[];
+}
+/** One sent message and the full set of SMTP addresses it went to. */
+export interface SentRecipientGroup {
+    entryId: string;
+    subject: string;
+    sentOn: string;
+    recipients: string[];
+}
+export interface InboxEmail {
+    entryId: string;
+    storeId: string;
+    subject: string;
+    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;
+}
+export interface InboxSearchFilter {
+    /** SQL-LIKE fragment for the [Subject] clause in Items.Restrict — the
+     *  server-side prefilter that keeps a full-mailbox walk cheap, e.g.
+     *  '*invoice*'. Omit to restrict on date only. */
+    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. */
+    subjectPattern?: RegExp;
+    /** Drop subjects starting with Re:/Fw:/Fwd:. */
+    excludeReplies?: boolean;
+    /** Only return items carrying at least one attachment. */
+    requireAttachment?: boolean;
+}
+export interface InboxSearchMatch {
+    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. */
+    senderEmail: string;
+    /** 'yyyy-MM-dd HH:mm'. */
+    receivedTime: string;
+    body: string;
+    /** Not saved to disk — pass the ones you want through saveEmailAttachments. */
+    attachmentNames: string[];
+    folderPath: string;
+}
+export interface SelectedEmail {
+    entryId: string;
+    storeId: string;
+    subject: string;
+    senderName: string;
+    senderEmail: string;
+    receivedTime: string;
+    body: string;
+    /** Not saved to disk — pass the ones you want through saveEmailAttachments. */
+    attachmentNames: string[];
+}
+export interface EmailBodyResult {
+    entryId: string;
+    subject: string;
+    senderName: string;
+    senderEmail: string;
+    receivedTime: string;
+    /** The sender's own new text — everything above the quoted thread. */
+    body: string;
+    /** True when `body` hit maxChars and was cut. */
+    truncated: boolean;
+    /** Length of the sender's new text before any capping. */
+    bodyLength: number;
+    /** What the quoted thread was split on ("-----Original Message-----", …); empty 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. */
+    quotedOriginal: string;
+    attachmentNames: string[];
+    attachmentCount: number;
+}
+export interface MailFolderRef {
+    /** olDefaultFolders id of the root the walk starts from. */
+    rootId: number;
+    /** That root's name, for error messages. */
+    rootLabel: string;
+    /** Path segments below the root. */
+    segments: string[];
+}
+export interface InboxFolderInfo {
+    name: string;
+    /** Outlook folder path, e.g. "\\\\mailbox\\Inbox\\Invoices". */
+    folderPath: string;
+    itemCount: number;
+    /** 1 = direct child of Inbox, 2 = grandchild, … */
+    depth: number;
+}
+export interface MoveEmailsResult {
+    folderPath: string;
+    folderCreated: boolean;
+    moved: number;
+    failed: {
+        entryId: string;
+        error: string;
+    }[];
+}
+export interface SavedAttachment {
+    path: string;
+    subject: string;
+    senderName: string;
+    senderEmail: string;
+    receivedTime: string;
+}
+/** 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). */
+    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[];
+    lastModified: string;
+}
+export interface TemplateFolderResult {
+    folderFound: boolean;
+    /** Outlook folder path when found, e.g. "\\\\mailbox\\Templates". */
+    folderPath: string;
+    templates: TemplateEmail[];
+    /** When the folder wasn't found: the mailbox's folder names, so the caller can pick or create one. */
+    availableFolders: 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.
+ */
+export interface OutlookBridge {
+    getOutlookAccounts(): Promise<string[]>;
+    sendOutlookEmail(params: SendEmailParams): Promise<void>;
+    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[]>;
+    readSelectedEmail(): Promise<SelectedEmail>;
+    readEmailBody(entryId: string, storeId?: string, maxChars?: number, includeQuoted?: boolean): Promise<EmailBodyResult>;
+    openOutlookEmail(entryId: 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>;
+    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[]>;
+    listOutlookSignatures(): Promise<string[]>;
+    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>;
+    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 grey 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.
+ */
+export type CapabilityMap = Readonly<Record<BridgeCapability, boolean>>;

package/dist/types.js

@@ -0,0 +1,13 @@
+"use strict";
+// The package's data contract, and the interface both platform implementations
+// answer to.
+//
+// These types used to live in the Windows implementation, so macOS imported its
+// own return shapes from it and its stubs re-declared them structurally. The two
+// drifted, and because OutlookService dispatches by picking one implementation or
+// the other, every drift surfaced in the PUBLIC types as a union — `matched:
+// UndeliverableEmail[] | unknown[]` and the like. Both now implement
+// `OutlookBridge` from here, so a drift is a compile error in the package rather
+// than a union in the consumer's editor.
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":";AAAA,+EAA+E;AAC/E,aAAa;AACb,EAAE;AACF,gFAAgF;AAChF,iFAAiF;AACjF,kFAAkF;AAClF,6EAA6E;AAC7E,qEAAqE;AACrE,iFAAiF;AACjF,yCAAyC"}

package/dist/windows/accounts.d.ts

@@ -0,0 +1,2 @@
+/** Retrieve all Outlook email accounts (SMTP addresses). */
+export declare function getOutlookAccounts(): Promise<string[]>;

package/dist/windows/accounts.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getOutlookAccounts = getOutlookAccounts;
+const run_1 = require("./run");
+/** Retrieve all Outlook email accounts (SMTP addresses). */
+async function getOutlookAccounts() {
+    if (process.platform !== 'win32')
+        return [];
+    const script = `
+$outlook = New-Object -ComObject Outlook.Application
+$accounts = @()
+foreach ($a in $outlook.Session.Accounts) {
+    $accounts += $a.SmtpAddress
+}
+$accounts -join '|'
+`;
+    const result = await (0, run_1.runPowerShell)(script);
+    if (!result)
+        return [];
+    return result.split('|').filter(Boolean);
+}
+//# sourceMappingURL=accounts.js.map

package/dist/windows/accounts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"accounts.js","sourceRoot":"","sources":["../../src/windows/accounts.ts"],"names":[],"mappings":";;AAGA,gDAaC;AAhBD,+BAAsC;AAEtC,4DAA4D;AACrD,KAAK,UAAU,kBAAkB;IACpC,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO;QAAE,OAAO,EAAE,CAAC;IAC5C,MAAM,MAAM,GAAG;;;;;;;CAOlB,CAAC;IACE,MAAM,MAAM,GAAG,MAAM,IAAA,mBAAa,EAAC,MAAM,CAAC,CAAC;IAC3C,IAAI,CAAC,MAAM;QAAE,OAAO,EAAE,CAAC;IACvB,OAAO,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;AAC7C,CAAC"}

package/dist/windows/attachments.d.ts

@@ -0,0 +1,28 @@
+import type { SavedAttachment } from '../types';
+/**
+ * Save an email attachment by entryId and filename, returning the saved path
+ * together with the resolved email's subject/sender so the caller can confirm the
+ * file came from the email it intended.
+ *
+ * `destDir` is created if absent. Without one the file lands in a fresh directory
+ * of its own, because attachments keep the name the sender gave them: a single
+ * shared folder means two emails carrying "invoice.pdf" silently overwrite each
+ * other. Pass `destDir` whenever you want the files somewhere you control.
+ *
+ * When the attachment isn't found, throws an error that names the email actually
+ * resolved (from/subject/received) and the attachments it does carry. Because
+ * GetItemFromID happily returns a *different* message when handed a stale or wrong
+ * EntryID (common when many replies share one subject), a bare "not found" is
+ * misleading — this surfaces which email you're really looking at.
+ */
+export declare function saveEmailAttachmentDetailed(entryId: string, fileName: string, storeId?: string, destDir?: string): Promise<SavedAttachment>;
+/** Save an attachment and return just the saved file path. */
+export declare function saveEmailAttachment(entryId: string, fileName: string, storeId?: string, destDir?: string): Promise<string>;
+/**
+ * Save several attachments from one email in a single COM round trip — what a
+ * caller working through searchInboxByFilter/readSelectedEmail results wants,
+ * rather than paying a PowerShell process spawn per attachment. Destination,
+ * matching and the not-found error follow saveEmailAttachmentDetailed's rules
+ * exactly, applied per name; results come back in the same order as `fileNames`.
+ */
+export declare function saveEmailAttachments(entryId: string, fileNames: string[], storeId?: string, destDir?: string): Promise<SavedAttachment[]>;

package/dist/windows/attachments.js

@@ -0,0 +1,141 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.saveEmailAttachmentDetailed = saveEmailAttachmentDetailed;
+exports.saveEmailAttachment = saveEmailAttachment;
+exports.saveEmailAttachments = saveEmailAttachments;
+// Saving attachments off an email, one at a time or in a batch.
+const run_1 = require("./run");
+const scripts_1 = require("./scripts");
+const json_1 = require("../shared/json");
+const attachmentMatch_1 = require("../shared/attachmentMatch");
+const runtime_1 = require("../runtime");
+const errors_1 = require("../errors");
+/**
+ * The "not found" throw, built from the shared wording with PowerShell
+ * interpolations in place of the values — so the sentence a Windows caller sees
+ * is literally the same one macOS composes.
+ */
+const NOT_FOUND_THROW = `throw "${(0, attachmentMatch_1.attachmentNotFoundMessage)({
+    fileName: '$target',
+    senderEmail: '$($item.SenderEmailAddress)',
+    subject: '$($item.Subject)',
+    receivedTime: '$($item.ReceivedTime)',
+    present: '$haveStr',
+    idLabel: 'EntryID',
+})}"`;
+/**
+ * Locate one attachment by name into `$found`, or throw naming the email that
+ * actually resolved. Matching is exact first, then whitespace-normalized (trim +
+ * collapse runs, incl. non-breaking spaces) so a trivially reformatted filename
+ * still resolves.
+ */
+const FIND_ATTACHMENT_PS = `
+    $found = $null
+    foreach ($att in $item.Attachments) {
+        if ($att.FileName -eq $target) { $found = $att; break }
+    }
+    if ($found -eq $null) {
+        $tnorm = ($target -replace '\\s+', ' ').Trim()
+        foreach ($att in $item.Attachments) {
+            if ((($att.FileName -replace '\\s+', ' ').Trim()) -ieq $tnorm) { $found = $att; break }
+        }
+    }
+    if ($found -eq $null) {
+        $have = @(); foreach ($a in $item.Attachments) { $have += $a.FileName }
+        $haveStr = if ($have.Count -gt 0) { $have -join ', ' } else { '(none)' }
+        ${NOT_FOUND_THROW}
+    }
+`;
+/** The row every saver returns: the file, plus who the email was really from. */
+const SAVED_ROW_PS = `[PSCustomObject]@{
+        path         = $savePath
+        subject      = if ($item.Subject) { $item.Subject } else { '' }
+        senderName   = if ($item.SenderName) { $item.SenderName } else { '' }
+        senderEmail  = if ($item.SenderEmailAddress) { $item.SenderEmailAddress } else { '' }
+        receivedTime = if ($item.ReceivedTime) { $item.ReceivedTime.ToString('yyyy-MM-dd HH:mm') } else { '' }
+    }`;
+function savedAttachment(value) {
+    const e = (0, json_1.record)(value);
+    return {
+        path: (0, json_1.str)(e.path),
+        subject: (0, json_1.str)(e.subject),
+        senderName: (0, json_1.str)(e.senderName),
+        senderEmail: (0, json_1.str)(e.senderEmail),
+        receivedTime: (0, json_1.str)(e.receivedTime),
+    };
+}
+/**
+ * Save an email attachment by entryId and filename, returning the saved path
+ * together with the resolved email's subject/sender so the caller can confirm the
+ * file came from the email it intended.
+ *
+ * `destDir` is created if absent. Without one the file lands in a fresh directory
+ * of its own, because attachments keep the name the sender gave them: a single
+ * shared folder means two emails carrying "invoice.pdf" silently overwrite each
+ * other. Pass `destDir` whenever you want the files somewhere you control.
+ *
+ * When the attachment isn't found, throws an error that names the email actually
+ * resolved (from/subject/received) and the attachments it does carry. Because
+ * GetItemFromID happily returns a *different* message when handed a stale or wrong
+ * EntryID (common when many replies share one subject), a bare "not found" is
+ * misleading — this surfaces which email you're really looking at.
+ */
+async function saveEmailAttachmentDetailed(entryId, fileName, storeId, destDir) {
+    (0, run_1.requireWindows)();
+    const outDir = (0, runtime_1.resolveDestDir)(destDir);
+    const script = `
+$outlook = New-Object -ComObject Outlook.Application
+$ns = $outlook.GetNamespace('mapi')
+$ns.Logon()
+${(0, scripts_1.getItemScript)(entryId, storeId)}
+if ($item -eq $null) { throw "Email not found for EntryID '${(0, run_1.psEscape)(entryId)}'" }
+$target = '${(0, run_1.psEscape)(fileName)}'
+${FIND_ATTACHMENT_PS}
+$savePath = [IO.Path]::Combine('${(0, run_1.psEscape)(outDir)}', $found.FileName)
+$found.SaveAsFile($savePath)
+$out = ${SAVED_ROW_PS}
+ConvertTo-Json $out -Compress
+`;
+    const raw = await (0, run_1.runPowerShell)(script, 15000);
+    if (!raw || !raw.trim())
+        throw new errors_1.NotFoundError('attachment', 'Failed to save attachment.');
+    return savedAttachment((0, json_1.parseObject)(raw));
+}
+/** Save an attachment and return just the saved file path. */
+async function saveEmailAttachment(entryId, fileName, storeId, destDir) {
+    return (await saveEmailAttachmentDetailed(entryId, fileName, storeId, destDir)).path;
+}
+/**
+ * Save several attachments from one email in a single COM round trip — what a
+ * caller working through searchInboxByFilter/readSelectedEmail results wants,
+ * rather than paying a PowerShell process spawn per attachment. Destination,
+ * matching and the not-found error follow saveEmailAttachmentDetailed's rules
+ * exactly, applied per name; results come back in the same order as `fileNames`.
+ */
+async function saveEmailAttachments(entryId, fileNames, storeId, destDir) {
+    (0, run_1.requireWindows)();
+    if (fileNames.length === 0)
+        return [];
+    const outDir = (0, runtime_1.resolveDestDir)(destDir);
+    const script = `
+$outlook = New-Object -ComObject Outlook.Application
+$ns = $outlook.GetNamespace('mapi')
+$ns.Logon()
+${(0, scripts_1.getItemScript)(entryId, storeId)}
+if ($item -eq $null) { throw "Email not found for EntryID '${(0, run_1.psEscape)(entryId)}'" }
+$targets = @(${(0, run_1.psList)(fileNames)})
+$results = @()
+foreach ($target in $targets) {
+${FIND_ATTACHMENT_PS}
+    $savePath = [IO.Path]::Combine('${(0, run_1.psEscape)(outDir)}', $found.FileName)
+    $found.SaveAsFile($savePath)
+    $results += ${SAVED_ROW_PS}
+}
+ConvertTo-Json $results -Depth 3 -Compress
+`;
+    const raw = await (0, run_1.runPowerShell)(script, 15000);
+    if (!raw || !raw.trim())
+        throw new errors_1.NotFoundError('attachment', 'Failed to save attachments.');
+    return (0, json_1.parseArray)(raw).map(savedAttachment);
+}
+//# sourceMappingURL=attachments.js.map

package/dist/windows/attachments.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attachments.js","sourceRoot":"","sources":["../../src/windows/attachments.ts"],"names":[],"mappings":"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"}

package/dist/windows/bounces.d.ts

@@ -0,0 +1,34 @@
+import type { CleanUndeliverableResult, SentRecipientGroup } from '../types';
+/**
+ * Scan an account's inbox for bounce-back / non-delivery messages — Outlook NDRs,
+ * mail-daemon/postmaster rejections, and "Message blocked"-style Google/O365
+ * failure notices — and, unless previewing, move each to Deleted Items (recoverable).
+ *
+ * Classification is deliberately conservative so ordinary mail that merely
+ * mentions "delivery" is never caught: an item matches only when its
+ * MessageClass is an NDR report, its sender fingerprints as a mail-delivery
+ * daemon/postmaster, or its subject contains a specific bounce phrase.
+ *
+ * Matched item references are snapshotted before any Delete() call — deleting
+ * mutates the folder collection, so deleting mid-enumeration would skip items
+ * (same pattern as sendAllDrafts).
+ */
+export declare function cleanUndeliverableEmails(emailAccount: string, daysBack?: number, dryRun?: boolean): Promise<CleanUndeliverableResult>;
+/**
+ * Read-only scan of an account's Inbox (and, when scanDeleted, its Deleted Items)
+ * for bounce messages, returning just the deduped set of failed recipient
+ * addresses. Uses the same conservative classifier as cleanUndeliverableEmails.
+ *
+ * Deleted Items is included so this still works after cleanUndeliverableEmails has
+ * already filed the bounces there — the blacklist step doesn't depend on running
+ * before the cleanup. This never deletes anything.
+ */
+export declare function collectBouncedRecipients(emailAccount: string, daysBack?: number, scanDeleted?: boolean): Promise<string[]>;
+/**
+ * Read the account's Sent Items within the window, returning each mail with the
+ * full SMTP address set it was sent to (To + CC + BCC), newest first. This is how
+ * the "was every address for this contact tried?" question gets answered: where a
+ * blast sends one email per organization addressed to all of its addresses, a sent
+ * message's recipient set IS that organization's full address set.
+ */
+export declare function readSentRecipientGroups(emailAccount: string, daysBack?: number, limit?: number): Promise<SentRecipientGroup[]>;