@dawnlit/outlook-bridge 1.1.1 → 2.0.0

package/README.md

@@ -1,253 +1,220 @@
 # @dawnlit/outlook-bridge
 
-Drive a real, locally installed Outlook client from Node — read the inbox, send and reply to mail, manage drafts, work
-with signatures and template emails, file and delete messages. No Graph API, no app registration, no cloud permissions:
-this automates the desktop client itself, the same way a person would.
+Drive a real, locally installed Outlook client from Node — read and search mail, send and reply, manage drafts, save
+attachments, work with signatures and template emails, file and delete messages. No Graph API, no app registration, no
+cloud permissions: this automates the desktop client itself, the way a person would.
 
-- **Windows** — via PowerShell + Outlook's COM object model.
-- **macOS** — via AppleScript. The whole surface is ported, with two differences no capability flag can express (see
-  [Platform differences](#platform-differences)). Requires **legacy** Outlook for Mac: New Outlook implements only a
-  slice of the AppleScript dictionary — accounts don't enumerate and the inbox reports 0 messages — so calls fail
-  loudly with `ACCOUNT_NOT_FOUND` there rather than quietly doing the wrong thing.
-- Any other platform — `capabilities()` reports everything false and every call rejects with `UNSUPPORTED_PLATFORM`.
+- **Windows** — PowerShell and Outlook's COM object model.
+- **macOS** — AppleScript. Requires **legacy** Outlook for Mac: New Outlook implements only a slice of the AppleScript
+  dictionary (accounts don't enumerate, the inbox reports no messages), so every call fails with `ACCOUNT_NOT_FOUND`
+  there rather than quietly doing the wrong thing.
+- **Anywhere else** — `capabilities()` reports nothing supported and every call rejects with `UNSUPPORTED_PLATFORM`.
 
 ## Install
 
-Install straight off GitHub `main`, rather than a versioned release:
-
 ```bash
-npm install github:dawnlit-ai/outlook-bridge#main
+npm install @dawnlit/outlook-bridge
 ```
 
-`prepare` runs `npm run build` automatically on install, so `dist/` is built from that checked-out
-source with no separate step. npm resolves the branch to a commit and pins it in `package-lock.json`,
-so a later plain `npm install` won't pick up new commits on its own — re-run the command above
-(naming the package and `#main` explicitly) whenever you want to advance to the current tip.
-
-Requires Node 24+ and a real Outlook installation on the machine running it — this is desktop automation, not a hosted
-API client.
+Requires Node 24+ and a real Outlook on the machine running it — this is desktop automation, not a hosted API client.
 
 ## Usage
 
 ```ts
-import { getOutlookAccounts, readInboxEmails, sendOutlookEmail } from '@dawnlit/outlook-bridge';
+import { getOutlookAccounts, readInboxEmails, readEmailBody, replyOutlookEmail } from '@dawnlit/outlook-bridge';
+
+const [account] = await getOutlookAccounts();
 
-const accounts = await getOutlookAccounts();
+const recent = await readInboxEmails(account, { daysBack: 7, limit: 20 });
 
-const emails = await readInboxEmails(accounts[0]);
+// A listing row can be passed straight back in as the email to act on.
+const email = recent[0];
+const { body } = await readEmailBody(email);
 
-await sendOutlookEmail({
-    emailAccount: accounts[0],
-    to: 'someone@example.com',          // comma- or semicolon-separated
-    subject: 'Hello from @dawnlit/outlook-bridge',
-    htmlBody: '<p>Sent by driving the Outlook client directly.</p>',
-    sendImmediately: false,             // false leaves it in Drafts
+await replyOutlookEmail({
+    emailAccount: account,
+    entryId: email.entryId,
+    storeId: email.storeId,
+    htmlBody: '<p>Thanks — received.</p>',
+    openDraftWindow: false, // file the reply in Drafts without opening a window
 });
 ```
 
-Every function is exposed under one signature regardless of platform — the dispatcher pins both implementations to the
-same `OutlookBridge` interface, so nothing here returns a per-platform union you have to narrow.
-
-## Platform differences
-
-Both platforms implement the whole contract, so `capabilities()` is all-true on Windows and on macOS. It still exists,
-and is still worth asking, because it answers for the machine you are actually on — on any other OS every entry is
-false and every call rejects:
+Every operation takes its required arguments positionally and everything optional as one options object, with the
+same defaults and the same validation on both platforms.
 
-```ts
-import { createOutlookBridge } from '@dawnlit/outlook-bridge';
+### Operations
 
-const bridge = createOutlookBridge();
+| Area                   | Operations                                                                                                                                                                                                                                                                                                                                                                                       |
+|------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| Accounts               | `getOutlookAccounts`                                                                                                                                                                                                                                                                                                                                                                             |
+| Reading                | `readInboxEmails` (the Inbox root, or any folder by name or path), `searchInboxByFilter` (walks the whole Inbox tree by subject glob or pattern, date window, attachments, folders), `readEmailBody` (the sender's own text, split from the quoted thread), `readSelectedEmail`, `openOutlookEmail`, `locateEmail` (finds an email again by subject, sender and time once its id has gone stale) |
+| Folders                | `listInboxFolders`, `moveOutlookEmails` (creates a missing destination chain on request)                                                                                                                                                                                                                                                                                                         |
+| Composing              | `sendOutlookEmail` (to/cc/bcc, several attachments, a named signature, send or draft), `replyOutlookEmail` (reply or reply-all, from HTML or a saved template)                                                                                                                                                                                                                                   |
+| Drafts                 | `listOutlookDrafts`, `sendDrafts` (a chosen subset), `sendAllDrafts`, `deleteOutlookDrafts`                                                                                                                                                                                                                                                                                                      |
+| Attachments            | `saveEmailAttachment`, `saveEmailAttachments`                                                                                                                                                                                                                                                                                                                                                    |
+| Cleanup                | `deleteOutlookEmails` (refuses received and sent mail unless allowed; dry-run first), `purgeDeletedItems`                                                                                                                                                                                                                                                                                        |
+| Bounces                | `cleanUndeliverableEmails`, `readBounceReport` (which sent messages bounced, and for which recipients), `collectBouncedRecipients`, `readSentRecipientGroups`                                                                                                                                                                                                                                    |
+| Signatures & templates | `listOutlookSignatures`, `readOutlookSignatureHtml`, `readTemplateEmails`, `saveTemplateEmail`, `editEmailTemplate`                                                                                                                                                                                                                                                                              |
 
-if (bridge.supports('searchInboxByFilter')) { /* … */ }
+Each is documented where it is declared, in `OutlookBridge` (see `dist/types.d.ts`), with every option and default.
 
-bridge.capabilities(); // { readInboxEmails: true, replyOutlookEmail: true, … }
-```
+A few pure helpers need no Outlook: `threadSubject` (a subject with every stacked reply and forward prefix stripped, in
+any of the languages `RE:`, `AW:` or `回复:` come in — the subject a whole thread shares), `hasReplyPrefix`,
+`splitQuotedOriginal` (the sender's new text apart from the quoted thread) and `mailFolderRef`.
 
-The map is derived from `keyof OutlookBridge`, so a function added to the contract fails both platform maps at
-compile time rather than quietly defaulting to supported.
+### Identifying an email
 
-Two things differ between the platforms that no flag can express, and code moving between them has to know both:
+Listings return an `entryId` and a `storeId`. Operations on one email accept an `EmailRef`: the entry id alone, or any
+object carrying `{ entryId, storeId? }` — so the row itself can be passed back. Passing the row is also the reliable way
+to keep a `storeId` with its own `entryId`; the store id is what lets an email resolve in a mailbox other than the
+default one.
 
-**Ids are not portable.** Windows returns MAPI `EntryID` strings; macOS returns Outlook for Mac's small integer message
-ids (`"1263"`). Each platform rejects the other's with `INVALID_REQUEST` rather than failing later as a confusing "not
-found". `storeId` has no macOS equivalent: it is returned as `''` and accepted-and-ignored wherever it is a parameter.
-Don't persist an id from one platform and look it up on the other.
+**Ids are not portable between platforms.** Windows returns MAPI EntryIDs; macOS returns Outlook for macOS small integer
+message ids, and has no store id (it reports `''` and ignores one passed in). Each platform rejects the other's ids with
+`INVALID_REQUEST`. **Moving an email rewrites its id** on both, so ids saved before a move are stale afterward. Keep the
+subject, sender and received time beside a saved id, and `locateEmail` finds the email again from them wherever it has
+moved under the Inbox, on either platform.
 
-**`searchInboxByFilter` filters in-process on macOS.** Windows hands `subjectLike` and the date window to Outlook's
-server-side `Items.Restrict`; AppleScript has no counterpart, so the macOS walk indexes each folder with bulk property
-reads and applies the same tests here. Same results, different cost — a `daysBack` of 0 over a large mailbox tree is
-considerably heavier on macOS.
+Timestamps are local time as `yyyy-MM-dd HH:mm`, which sorts correctly as a string.
 
-Two smaller notes: `replyOutlookEmail` reports `to` as the reply's resolved recipient addresses on macOS rather than the
-display-name string Windows reports; and `editEmailTemplate` on macOS files the edited draft when you answer Outlook's
-own "save this message?" prompt on close, where Windows asks for Ctrl+S.
-
-## Configuration
+### Templates
 
-Each call generates a script and shells out to an interpreter. That leaves four things otherwise out of your reach:
-how long a run may take, how much it may print, how to call it off, and what the script actually said.
-
-`createOutlookBridge()` gives you those on an instance no other caller in the process can disturb:
+A template email is an ordinary email saved in a mailbox folder (default `Templates`) and edited in Outlook. One template
+can hold several variants of a reply between `[[SECTION]] ... [[/SECTION]]` markers around a shared greeting and
+closing, with `{{PLACEHOLDER}}` tokens:
 
 ```ts
-import { createOutlookBridge } from '@dawnlit/outlook-bridge';
-
-const bridge = createOutlookBridge({
-    timeoutMs: 120_000,               // default per-run ceiling; 0 disables
-    maxBufferBytes: 32 * 1024 * 1024, // raise before a scan that returns thousands of bodies
-    tempDir: '/var/tmp/outlook',      // scratch scripts and default attachment destination
-    debug: (e) => log(e.script),      // every generated script, its duration, and any error
+await replyOutlookEmail({
+    emailAccount: account,
+    entryId: email.entryId,
+    storeId: email.storeId,
+    templateSubject: 'Standard reply',
+    templateSection: 'ACCEPT',
+    templatePlaceholders: { NOTE: 'We will confirm by Friday.' },
+    signatureName: 'Work', // fills {{SIGNATURE}}
 });
-
-await bridge.readInboxEmails(account);
 ```
 
-`bridge.withOptions({ … })` derives a bridge with some settings changed — how one call gets its own budget, or its
-own cancellation:
+The template, the section, the placeholders and the signature are all resolved inside the package, so a large
+Word-generated template never has to pass through the caller. Composition refuses rather than guesses: a missing section,
+an unknown placeholder, or a marker left unresolved fails with `INVALID_REQUEST` before anything is created.
 
-```ts
-const controller = new AbortController();
-cancelButton.onclick = () => controller.abort();
+The same toolkit works on any HTML string: `composeTemplateBody`, `findTemplateMarkers`, and for `{Token}`-style fills,
+`replaceToken`, `removeTokenLine` (removes a token together with its table row or paragraph), `findTokens` and
+`findUnfilledTokens`.
 
-await bridge.withOptions({ signal: controller.signal }).searchInboxByFilter(account, filter);
-// → rejects with an AbortedError (code 'ABORTED'), interpreter killed
-```
+## Configuration
 
-The same functions are also exported directly, running against a process-wide config that `configure()` sets. That is
-the simpler thing for a program that owns its process; prefer `createOutlookBridge` in anything sharing a process
-with code you do not own.
+Every call generates a script and runs it under an interpreter. The settings are how long a run may take, how much it may
+print, how to call it off, and what the script said:
 
 ```ts
-import { configure, readInboxEmails } from '@dawnlit/outlook-bridge';
+import { createOutlookBridge } from '@dawnlit/outlook-bridge';
 
-configure({ timeoutMs: 60_000 });
-await readInboxEmails(account);
+const outlook = createOutlookBridge({
+    timeoutMs: 120_000,               // ceiling on every run (default: a budget sized for each operation)
+    maxBufferBytes: 32 * 1024 * 1024, // output cap; searches returning bodies push against it (default 8 MiB)
+    tempDir: '/var/tmp/outlook',      // generated scripts, and attachments saved without a destination
+    debug: event => log(event.script),// every generated script, its duration, and any error
+});
 ```
 
-`OUTLOOK_BRIDGE_DEBUG=1` in the environment turns on script logging to stderr without a code change.
+- **Timeouts.** Unless `timeoutMs` is set, each run gets a budget sized for its work — a minute for a lookup, two for
+  composing or reading a folder, five for a mailbox walk or a batch, ten for purging. `timeoutMs` replaces all of them;
+  `0` disables timeouts; `null` goes back to the budgets. `editEmailTemplate` waits on a person and is never timed —
+  cancel it with a signal.
+- **Instances.** A bridge's settings apply to its own calls only, even when several bridges run at once.
+  `outlook.withOptions({ ... })` derives a bridge with some settings changed — which is how a single call gets its own
+  budget or cancellation:
 
-Calls that carry a genuinely different budget (a full-mailbox walk, a purge) keep their own timeout and ignore
-`timeoutMs`. `searchInboxByFilter` is the one most likely to push against `maxBufferBytes`, since it returns whole
-message bodies.
+  ```ts
+  const controller = new AbortController();
+  cancelButton.onclick = () => controller.abort();
+  await outlook.withOptions({ signal: controller.signal }).searchInboxByFilter(account, { daysBack: 365 });
+  // → rejects with ABORTED, interpreter killed
+  ```
+
+- **Process-wide.** The exported functions run under process-wide settings that `configure()` changes. That is the
+  simpler choice for a program that owns its process; prefer `createOutlookBridge` in anything sharing one.
+- **Debugging.** `OUTLOOK_BRIDGE_DEBUG=1` logs every script to stderr without a code change.
+
+Capability discovery answers for the machine you are on: `capabilities()` returns a map of every operation to
+`true`/`false`, and `supports('searchInboxByFilter')` asks about one.
 
 ## Errors
 
-Every deliberate failure is an `OutlookError` carrying a stable `code`. **The codes are the API; the messages are
-not** — branch on `code`, never on message text.
+Every deliberate failure is an `OutlookError` with a stable `code`. **The codes are the API; the messages are not** —
+branch on `code`, never on message text.
 
 ```ts
 import { OutlookError } from '@dawnlit/outlook-bridge';
 
 try {
-    await bridge.replyOutlookEmail(params);
+    await outlook.readInboxEmails(account, { folder: 'Invoices\\2026' });
 } catch (error) {
-    if (!(error instanceof OutlookError)) throw error; // a real bug
+    if (!(error instanceof OutlookError)) throw error; // a bug
     switch (error.code) {
-        case 'ACCOUNT_NOT_FOUND': return promptForAccount(error.account);
-        case 'NOT_IMPLEMENTED':   return degrade(error.operation);
-        case 'ABORTED':           return;
-        case 'SCRIPT_FAILED':     return report(error.script, error.stderr);
+        case 'ACCOUNT_NOT_FOUND': return askForAccount(error.account);
+        case 'NOT_FOUND':         return report(`${error.kind} missing: ${error.message}`);
+        case 'OUTPUT_TOO_LARGE':  return retryWithNarrowerWindow();
+        case 'SCRIPT_FAILED':     return logFailure(error.script, error.line, error.stderr);
     }
 }
 ```
 
-| code | class | meaning |
-| --- | --- | --- |
-| `UNSUPPORTED_PLATFORM` | `UnsupportedPlatformError` | No Outlook automation exists on this OS. |
-| `NOT_IMPLEMENTED` | `NotImplementedError` | The platform could, but this corner isn't written. Carries `operation`. Now only reachable for a folder root macOS has no term for (Journal and the like). |
-| `ACCOUNT_NOT_FOUND` | `AccountNotFoundError` | No configured account matches. Carries `account`. |
-| `NOT_FOUND` | `NotFoundError` | A folder, template, signature or item did not resolve. Carries `kind`. |
-| `INVALID_REQUEST` | `InvalidRequestError` | The arguments cannot produce a call; nothing was attempted. |
-| `SCRIPT_FAILED` | `ScriptError` | The interpreter ran and failed. Carries `script`, `stderr`, `runner`, `durationMs`. |
-| `TIMEOUT` | `TimeoutError` | The run exceeded its budget and was killed. Carries `timeoutMs`. |
-| `ABORTED` | `AbortedError` | The caller's `AbortSignal` fired. |
-
-`ScriptError` carries the generated script verbatim — the thing you actually want when one fires, and otherwise
-reachable only if you wired up a `debug` hook in advance.
+| code                   | class                      | meaning                                                                                                                                                        |
+|------------------------|----------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `UNSUPPORTED_PLATFORM` | `UnsupportedPlatformError` | No Outlook automation exists on this OS.                                                                                                                       |
+| `NOT_IMPLEMENTED`      | `NotImplementedError`      | The platform could do this, but this corner isn't written (a folder root macOS has no term for).                                                               |
+| `ACCOUNT_NOT_FOUND`    | `AccountNotFoundError`     | No mailbox in the profile matches the address. Carries `account`.                                                                                              |
+| `NOT_FOUND`            | `NotFoundError`            | A `folder`, `email`, `attachment`, `template`, `signature` or `file` didn't resolve. Carries `kind`.                                                           |
+| `INVALID_REQUEST`      | `InvalidRequestError`      | The arguments can't produce a call — a wrong type, a missing value, a template edited into an unusable state, or a mailbox that can be read but not sent from. |
+| `SCRIPT_FAILED`        | `ScriptError`              | The script ran and failed. Carries `script`, `line`, `stderr`, `runner`, `durationMs`.                                                                         |
+| `OUTPUT_TOO_LARGE`     | `OutputTooLargeError`      | The script printed more than `maxBufferBytes`.                                                                                                                 |
+| `TIMEOUT`              | `TimeoutError`             | The run exceeded its time budget and was killed. Carries `timeoutMs`.                                                                                          |
+| `ABORTED`              | `AbortedError`             | The caller's `AbortSignal` fired.                                                                                                                              |
+
+Batch operations (moving, deleting, sending drafts, cleaning bounces) don't throw for one bad item: they report each
+failure in `failed` beside the items that worked.
+
+## Security
+
+Caller text ends up inside generated scripts, so the package treats every argument as untrusted:
+
+- Arguments are checked for type at run time — a count must be a finite number, a flag a boolean — before any script
+  is generated, whatever TypeScript believed at compile time.
+- On Windows, caller text only ever appears in single-quoted PowerShell literals, with every quote character PowerShell
+  accepts (including the typographic `‘ ’ ‚ ‛`) escaped. Text that has to appear in a message is referenced through a
+  variable, never interpolated into a double-quoted string where `$(...)` would run. Scripts run from UTF-8 files with a
+  byte-order mark, so non-ASCII text arrives intact.
+- Attachment names come from the sender, so a saved file's name is sanitized — no path separators, reserved device
+  names or characters the file system rejects — and never overwrites an existing file.
 
 ## Module format
 
-Published as CommonJS. ESM consumers can use named imports normally (`import { sendOutlookEmail } from …`); Node
-resolves them off the CJS build.
-
-There is deliberately no dual ESM/CJS build. This package identifies its errors with `instanceof`, and a dual-format
-package can load two copies of itself into one process — at which point `error instanceof OutlookError` returns
-`false` for errors the package itself threw. One format avoids that failure entirely.
-
-## API
-
-**Accounts & inbox** — `getOutlookAccounts`, `readInboxEmails`, `readEmailBody`,
-`listInboxFolders`, `moveOutlookEmails`, `openOutlookEmail`.
-
-**Search & selection** — `searchInboxByFilter` (walks every folder under the Inbox for one
-account, filtering by subject pattern/date window/reply-exclusion/attachment presence — the
-building block for "find the emails matching X" without knowing which subfolder holds them),
-`readSelectedEmail` (the email currently selected or open in Outlook).
-
-**Sending & replying** — `sendOutlookEmail`, `replyOutlookEmail` (answers the sender; pass `replyAll: true` to answer
-every recipient), `sendAllDrafts`.
-
-**Drafts** — `listOutlookDrafts`, `deleteOutlookDrafts`, `sendDrafts` (sends a chosen subset by
-EntryID — the review-and-select alternative to `sendAllDrafts`'s account-wide sweep).
-
-**Attachments** — `saveEmailAttachment`, `saveEmailAttachmentDetailed`, `saveEmailAttachments`
-(the same, batched into one COM round trip for several attachments off one email). All take an optional `destDir`,
-created if absent. Without one, each call saves into a fresh private directory — attachments keep the name the sender
-gave them, so a shared folder means two emails carrying `invoice.pdf` overwrite each other.
-
-**Signatures & templates** — `listOutlookSignatures`, `readOutlookSignatureHtml`,
-`readTemplateEmails`, `saveTemplateEmail`, `editEmailTemplate` (opens the template in a real Outlook compose window,
-waits for the user to close it, and returns the saved HTML — so it has no timeout by default; give it an
-`AbortSignal` if you need a way to give up).
-
-**Bounce handling** — `cleanUndeliverableEmails`, `collectBouncedRecipients`,
-`readSentRecipientGroups`.
-
-**Mailbox cleanup** — `deleteOutlookEmails`, `purgeDeletedItems`.
-
-**Template-section parsing** — a small pure-string toolkit for templates that carry several reply variants between
-`[[SECTION]] ... [[/SECTION]]` markers around one shared greeting/signature, with `{{PLACEHOLDER}}` tokens filled in by
-the caller: `findTemplateMarkers`, `composeTemplateBody`, `findTokens`,
-`findUnfilledTokens`, `replaceToken`, `removeTokenLine`.
-
-**Platform-neutral helpers** — usable with no Outlook session at all: `mailFolderRef` (parse any folder string a user
-might type into a well-known root plus segments), `splitQuotedOriginal` (separate a reply's own text from the thread
-quoted below it), `WELL_KNOWN_FOLDERS`.
-
-**Instances, capabilities and errors** — `createOutlookBridge` (a bridge with its own settings; see
-[Configuration](#configuration)), `capabilities` / `supports`, and the `OutlookError` family
-(see [Errors](#errors)).
-
-Every exported type (`InboxEmail`, `ReplyEmailParams`, `MailFolderRef`, `OutlookBridge`, `CapabilityMap`,
-`OutlookErrorCode`, etc.) is exported alongside its function.
+Published as CommonJS; ESM consumers can use named imports normally. There is deliberately no dual build: the package
+identifies its errors with `instanceof`, and a dual-format package can load two copies of itself into one process.
 
 ## Development
 
 ```bash
 npm run build   # tsc → dist/
-npm test        # build, then node:test over the platform-independent parts
+npm test        # build, then node:test
 ```
 
-The tests cover the parts that need no Outlook session — folder-string parsing, quote splitting, template
-composition, scratch-file handling, the error taxonomy and its run classifier, capability maps, config scoping, and
-the shape of the PowerShell the folder walk emits — so they run anywhere, with or without Outlook installed.
-
-On a **Mac with Outlook installed** they additionally compile every AppleScript the macOS implementation generates.
-The runner is stubbed, each operation is driven with plausible arguments, and the captured scripts go through
-`osacompile` — which resolves terminology against the real dictionary without opening a session, sending anything or
-touching a message. This is worth the trouble because one bad dictionary term fails the WHOLE script at compile time
-rather than at the offending line, so a live failure never names the thing that caused it. Those tests skip
-automatically elsewhere.
-
-Two guards over the same captured scripts run **everywhere**, with no Outlook needed, because they cover the
-failures compiling cannot catch — both of which shipped once and only surfaced against a live mailbox: assigning to a
-reserved AppleScript word (`set rest to …` parses, then fails at run time), and reading a record field through a
-nested accessor (`address of (sender of m)` does not coerce, and inside a `try` that means a silently empty sender).
-
-What no test can cover is the automation itself: driving a real Outlook client is the whole point of the package, and
-behaviour against a live mailbox — that a `move` really filed the mail, that a reply threaded correctly — is verified
-by running it, not in CI.
+The tests need no Outlook. They cover every operation's validation and defaults against a fake backend, the pure
+helpers, the error taxonomy, and the generated scripts themselves:
+
+- **On Windows**, every PowerShell script every operation generates is put through PowerShell's own parser, with
+  arguments built to break out of a badly escaped literal. The test fails on a syntax error, and on any caller text
+  inside a double-quoted string.
+- **On a Mac with Outlook installed**, every AppleScript is compiled with `osacompile`, which resolves dictionary terms
+  without opening a session. Elsewhere, those tests skip; two guards that need no Outlook — no assignment to a reserved
+  AppleScript word, no record field read through a nested accessor — run everywhere.
+
+What no test covers is the automation itself: that a move really filed the mail, or a reply threaded correctly, is
+verified against a live mailbox.
 
 ## License
 

package/dist/backend.d.ts

@@ -0,0 +1,151 @@
+import type { CleanUndeliverableResult, DeleteDraftsResult, DeleteMailResult, EmailLocator, InboxEmail, InboxFolderInfo, InboxSearchMatch, ListDraftsResult, MailFolderRef, MoveEmailsResult, PurgeDeletedItemsResult, ReplyEmailResult, SavedAttachment, SaveTemplateResult, SelectedEmail, SendDraftsResult, SentRecipientGroup, TemplateFolderResult } from './types';
+/** What to do with a composed email. */
+export type Disposition = 
+/** Send it now. */
+'send'
+/** Open it in a compose window for review. */
+ | 'display'
+/** File it into Drafts without a window. */
+ | 'save';
+export interface AccountRequest {
+    /** The mailbox's SMTP address, trimmed. */
+    readonly account: string;
+}
+export interface SendRequest extends AccountRequest {
+    /** One entry per recipient, each an address or a display-name form. */
+    readonly to: readonly string[];
+    readonly cc: readonly string[];
+    readonly bcc: readonly string[];
+    readonly subject: string;
+    readonly htmlBody: string;
+    /** Absolute paths, each verified to exist. */
+    readonly attachments: readonly string[];
+    readonly disposition: Disposition;
+}
+export interface ReplyRequest extends AccountRequest {
+    readonly email: EmailLocator;
+    /** The HTML to insert above the quoted original, fully composed. */
+    readonly html: string;
+    readonly replyAll: boolean;
+    readonly disposition: Disposition;
+}
+export interface ReadInboxRequest extends AccountRequest {
+    readonly folder: MailFolderRef;
+    /** The folder as the caller wrote it, for messages. */
+    readonly folderLabel: string;
+    readonly daysBack: number;
+    readonly limit: number;
+    /** 0 means no body is read at all. */
+    readonly previewChars: number;
+}
+export interface SearchRequest extends AccountRequest {
+    readonly daysBack: number;
+    readonly subjectLike?: string;
+    readonly subjectPattern?: RegExp;
+    readonly excludeReplies: boolean;
+    readonly requireAttachment: boolean;
+    readonly includeFolders: readonly string[];
+    readonly excludeFolders: readonly string[];
+    readonly includeBody: boolean;
+}
+/** One email as a backend reads it, before any splitting or capping. */
+export interface RawEmail {
+    readonly entryId: string;
+    readonly subject: string;
+    readonly senderName: string;
+    readonly senderEmail: string;
+    readonly receivedTime: string;
+    /** The full plain-text body. */
+    readonly body: string;
+    readonly attachmentNames: readonly string[];
+}
+export interface ListFoldersRequest extends AccountRequest {
+    readonly maxDepth: number;
+}
+export interface MoveRequest extends AccountRequest {
+    /** Non-empty, deduplicated. */
+    readonly entryIds: readonly string[];
+    readonly folder: MailFolderRef;
+    readonly folderLabel: string;
+    readonly createIfMissing: boolean;
+}
+export interface ListDraftsRequest extends AccountRequest {
+    readonly limit: number;
+    readonly previewChars: number;
+}
+export interface EntryIdsRequest extends AccountRequest {
+    /** Non-empty, deduplicated. */
+    readonly entryIds: readonly string[];
+}
+export interface DeleteEmailsRequest extends EntryIdsRequest {
+    readonly allowProtected: boolean;
+    readonly dryRun: boolean;
+}
+export interface PurgeRequest extends AccountRequest {
+    readonly olderThanDays: number;
+    readonly dryRun: boolean;
+}
+export interface SaveAttachmentsRequest {
+    readonly email: EmailLocator;
+    /** Non-empty; matched exactly first, then ignoring case and whitespace. */
+    readonly fileNames: readonly string[];
+    /** An existing directory to save into. */
+    readonly destDir: string;
+}
+export interface CleanUndeliverableRequest extends AccountRequest {
+    readonly daysBack: number;
+    readonly dryRun: boolean;
+}
+export interface CollectBouncesRequest extends AccountRequest {
+    readonly daysBack: number;
+    readonly includeDeletedItems: boolean;
+}
+export interface SentGroupsRequest extends AccountRequest {
+    readonly daysBack: number;
+    readonly limit: number;
+}
+export interface ReadTemplatesRequest extends AccountRequest {
+    readonly folder: string;
+    readonly limit: number;
+    readonly includeBody: boolean;
+    /** Only the template with this subject, case-insensitively. */
+    readonly subject?: string;
+}
+export interface SaveTemplateRequest extends AccountRequest {
+    readonly folder: string;
+    readonly subject: string;
+    readonly htmlBody: string;
+}
+export interface EditTemplateRequest {
+    readonly label: string;
+    readonly html: string;
+}
+/** One platform's Outlook automation. */
+export interface Backend {
+    getOutlookAccounts(): Promise<string[]>;
+    sendOutlookEmail(request: SendRequest): Promise<void>;
+    replyOutlookEmail(request: ReplyRequest): Promise<ReplyEmailResult>;
+    readInboxEmails(request: ReadInboxRequest): Promise<InboxEmail[]>;
+    searchInboxByFilter(request: SearchRequest): Promise<InboxSearchMatch[]>;
+    readSelectedEmail(): Promise<SelectedEmail>;
+    readEmailBody(email: EmailLocator): Promise<RawEmail>;
+    openOutlookEmail(email: EmailLocator): Promise<void>;
+    listInboxFolders(request: ListFoldersRequest): Promise<InboxFolderInfo[]>;
+    moveOutlookEmails(request: MoveRequest): Promise<MoveEmailsResult>;
+    listOutlookDrafts(request: ListDraftsRequest): Promise<ListDraftsResult>;
+    sendDrafts(request: EntryIdsRequest): Promise<SendDraftsResult>;
+    sendAllDrafts(request: AccountRequest): Promise<SendDraftsResult>;
+    deleteOutlookDrafts(request: EntryIdsRequest): Promise<DeleteDraftsResult>;
+    deleteOutlookEmails(request: DeleteEmailsRequest): Promise<DeleteMailResult>;
+    purgeDeletedItems(request: PurgeRequest): Promise<PurgeDeletedItemsResult>;
+    saveEmailAttachments(request: SaveAttachmentsRequest): Promise<SavedAttachment[]>;
+    cleanUndeliverableEmails(request: CleanUndeliverableRequest): Promise<CleanUndeliverableResult>;
+    collectBouncedRecipients(request: CollectBouncesRequest): Promise<string[]>;
+    readSentRecipientGroups(request: SentGroupsRequest): Promise<SentRecipientGroup[]>;
+    listOutlookSignatures(): Promise<string[]>;
+    /** '' when there is no signature by that name. */
+    readOutlookSignatureHtml(name: string): Promise<string>;
+    readTemplateEmails(request: ReadTemplatesRequest): Promise<TemplateFolderResult>;
+    saveTemplateEmail(request: SaveTemplateRequest): Promise<SaveTemplateResult>;
+    editEmailTemplate(request: EditTemplateRequest): Promise<string>;
+}

package/dist/backend.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=backend.js.map

package/dist/backend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backend.js","sourceRoot":"","sources":["../src/backend.ts"],"names":[],"mappings":"","sourcesContent":["// What a platform implements.\n//\n// The public operations (bridge.ts) check every argument, apply every default,\n// and do all the work that is the same on both platforms — composing a reply\n// from a template, splitting a body from its quoted thread, choosing where\n// attachments go. What reaches a backend is a request in its final shape: counts\n// are whole numbers in range, strings are trimmed, folders are parsed, and each\n// field the platform's script needs is present. A backend's job is only to turn\n// that request into Outlook automation and its output into the result.\nimport type {\n    CleanUndeliverableResult,\n    DeleteDraftsResult,\n    DeleteMailResult,\n    EmailLocator,\n    InboxEmail,\n    InboxFolderInfo,\n    InboxSearchMatch,\n    ListDraftsResult,\n    MailFolderRef,\n    MoveEmailsResult,\n    PurgeDeletedItemsResult,\n    ReplyEmailResult,\n    SavedAttachment,\n    SaveTemplateResult,\n    SelectedEmail,\n    SendDraftsResult,\n    SentRecipientGroup,\n    TemplateFolderResult,\n} from './types';\n\n/** What to do with a composed email. */\nexport type Disposition =\n/** Send it now. */\n    | 'send'\n    /** Open it in a compose window for review. */\n    | 'display'\n    /** File it into Drafts without a window. */\n    | 'save';\n\nexport interface AccountRequest {\n    /** The mailbox's SMTP address, trimmed. */\n    readonly account: string;\n}\n\nexport interface SendRequest extends AccountRequest {\n    /** One entry per recipient, each an address or a display-name form. */\n    readonly to: readonly string[];\n    readonly cc: readonly string[];\n    readonly bcc: readonly string[];\n    readonly subject: string;\n    readonly htmlBody: string;\n    /** Absolute paths, each verified to exist. */\n    readonly attachments: readonly string[];\n    readonly disposition: Disposition;\n}\n\nexport interface ReplyRequest extends AccountRequest {\n    readonly email: EmailLocator;\n    /** The HTML to insert above the quoted original, fully composed. */\n    readonly html: string;\n    readonly replyAll: boolean;\n    readonly disposition: Disposition;\n}\n\nexport interface ReadInboxRequest extends AccountRequest {\n    readonly folder: MailFolderRef;\n    /** The folder as the caller wrote it, for messages. */\n    readonly folderLabel: string;\n    readonly daysBack: number;\n    readonly limit: number;\n    /** 0 means no body is read at all. */\n    readonly previewChars: number;\n}\n\nexport interface SearchRequest extends AccountRequest {\n    readonly daysBack: number;\n    readonly subjectLike?: string;\n    readonly subjectPattern?: RegExp;\n    readonly excludeReplies: boolean;\n    readonly requireAttachment: boolean;\n    readonly includeFolders: readonly string[];\n    readonly excludeFolders: readonly string[];\n    readonly includeBody: boolean;\n}\n\n/** One email as a backend reads it, before any splitting or capping. */\nexport interface RawEmail {\n    readonly entryId: string;\n    readonly subject: string;\n    readonly senderName: string;\n    readonly senderEmail: string;\n    readonly receivedTime: string;\n    /** The full plain-text body. */\n    readonly body: string;\n    readonly attachmentNames: readonly string[];\n}\n\nexport interface ListFoldersRequest extends AccountRequest {\n    readonly maxDepth: number;\n}\n\nexport interface MoveRequest extends AccountRequest {\n    /** Non-empty, deduplicated. */\n    readonly entryIds: readonly string[];\n    readonly folder: MailFolderRef;\n    readonly folderLabel: string;\n    readonly createIfMissing: boolean;\n}\n\nexport interface ListDraftsRequest extends AccountRequest {\n    readonly limit: number;\n    readonly previewChars: number;\n}\n\nexport interface EntryIdsRequest extends AccountRequest {\n    /** Non-empty, deduplicated. */\n    readonly entryIds: readonly string[];\n}\n\nexport interface DeleteEmailsRequest extends EntryIdsRequest {\n    readonly allowProtected: boolean;\n    readonly dryRun: boolean;\n}\n\nexport interface PurgeRequest extends AccountRequest {\n    readonly olderThanDays: number;\n    readonly dryRun: boolean;\n}\n\nexport interface SaveAttachmentsRequest {\n    readonly email: EmailLocator;\n    /** Non-empty; matched exactly first, then ignoring case and whitespace. */\n    readonly fileNames: readonly string[];\n    /** An existing directory to save into. */\n    readonly destDir: string;\n}\n\nexport interface CleanUndeliverableRequest extends AccountRequest {\n    readonly daysBack: number;\n    readonly dryRun: boolean;\n}\n\nexport interface CollectBouncesRequest extends AccountRequest {\n    readonly daysBack: number;\n    readonly includeDeletedItems: boolean;\n}\n\nexport interface SentGroupsRequest extends AccountRequest {\n    readonly daysBack: number;\n    readonly limit: number;\n}\n\nexport interface ReadTemplatesRequest extends AccountRequest {\n    readonly folder: string;\n    readonly limit: number;\n    readonly includeBody: boolean;\n    /** Only the template with this subject, case-insensitively. */\n    readonly subject?: string;\n}\n\nexport interface SaveTemplateRequest extends AccountRequest {\n    readonly folder: string;\n    readonly subject: string;\n    readonly htmlBody: string;\n}\n\nexport interface EditTemplateRequest {\n    readonly label: string;\n    readonly html: string;\n}\n\n/** One platform's Outlook automation. */\nexport interface Backend {\n    getOutlookAccounts(): Promise<string[]>;\n\n    sendOutlookEmail(request: SendRequest): Promise<void>;\n\n    replyOutlookEmail(request: ReplyRequest): Promise<ReplyEmailResult>;\n\n    readInboxEmails(request: ReadInboxRequest): Promise<InboxEmail[]>;\n\n    searchInboxByFilter(request: SearchRequest): Promise<InboxSearchMatch[]>;\n\n    readSelectedEmail(): Promise<SelectedEmail>;\n\n    readEmailBody(email: EmailLocator): Promise<RawEmail>;\n\n    openOutlookEmail(email: EmailLocator): Promise<void>;\n\n    listInboxFolders(request: ListFoldersRequest): Promise<InboxFolderInfo[]>;\n\n    moveOutlookEmails(request: MoveRequest): Promise<MoveEmailsResult>;\n\n    listOutlookDrafts(request: ListDraftsRequest): Promise<ListDraftsResult>;\n\n    sendDrafts(request: EntryIdsRequest): Promise<SendDraftsResult>;\n\n    sendAllDrafts(request: AccountRequest): Promise<SendDraftsResult>;\n\n    deleteOutlookDrafts(request: EntryIdsRequest): Promise<DeleteDraftsResult>;\n\n    deleteOutlookEmails(request: DeleteEmailsRequest): Promise<DeleteMailResult>;\n\n    purgeDeletedItems(request: PurgeRequest): Promise<PurgeDeletedItemsResult>;\n\n    saveEmailAttachments(request: SaveAttachmentsRequest): Promise<SavedAttachment[]>;\n\n    cleanUndeliverableEmails(request: CleanUndeliverableRequest): Promise<CleanUndeliverableResult>;\n\n    collectBouncedRecipients(request: CollectBouncesRequest): Promise<string[]>;\n\n    readSentRecipientGroups(request: SentGroupsRequest): Promise<SentRecipientGroup[]>;\n\n    listOutlookSignatures(): Promise<string[]>;\n\n    /** '' when there is no signature by that name. */\n    readOutlookSignatureHtml(name: string): Promise<string>;\n\n    readTemplateEmails(request: ReadTemplatesRequest): Promise<TemplateFolderResult>;\n\n    saveTemplateEmail(request: SaveTemplateRequest): Promise<SaveTemplateResult>;\n\n    editEmailTemplate(request: EditTemplateRequest): Promise<string>;\n}\n"]}