@dawnlit/outlook-bridge 1.1.1 → 2.1.0

package/dist/mac/scripts.d.ts

@@ -1,106 +1,113 @@
-import type { MailFolderRef } from '../types';
+import type { ItemFailure, MailFolderRef } from '../types';
 /**
- * Resolve the account whose SMTP address matches, or raise. Emitted into a
- * `tell application "Microsoft Outlook"` block; binds `targetAcct`.
+ * An account as the generated AppleScript reaches it.
  *
- * `every account` errors even in legacy mode, so probe the typed classes. A
- * `whose email address is ...` filter can't be used either: `email address` is
- * also a class name, and AppleScript resolves it as one ("into type specifier").
- *
- * The thrown sentence is the one `classifyRunFailure` recognises to raise
- * `AccountNotFoundError`, so its wording is load-bearing.
+ * `folderIds` carries what Outlook's profile database knows about the mailbox's
+ * well-known folders — the only handle on a mailbox the dictionary publishes no
+ * account object for (see profile.ts). It is filled in for every account the
+ * profile lists, because the generated script chooses between the account
+ * object and the folder id at run time; nothing here has to predict which kinds
+ * of account a given Outlook build exposes.
  */
-export declare function accountLookupSnippet(emailAccount: string): string;
+export interface MacAccount {
+    readonly emailAccount: string;
+    readonly folderIds?: Readonly<Record<string, number>>;
+}
+/** Look an address up in Outlook's profile database, for the folder ids it can add. */
+export declare function resolveMacAccount(emailAccount: string): Promise<MacAccount>;
 /**
- * Outlook for Mac's dictionary term for each well-known root, keyed by the
- * olDefaultFolders id `mailFolderRef` resolves.
+ * Resolve the account whose address matches into `targetAcct`, inside a
+ * `tell application "Microsoft Outlook"` block.
+ *
+ * `every account` errors even in legacy mode, so the typed classes are probed.
+ * A `whose email address is …` filter can't be used either: `email address` is
+ * also a class name, and AppleScript resolves it as one.
  *
- * Verified against the running app. The terms are NOT the ones the Windows ids
- * suggest — `sent mail` and `junk email` do not compile at all, while
- * `sent items` and `junk mail` do, and a bad term fails the whole script at
- * compile time rather than at the offending line.
+ * A mailbox the dictionary publishes no account object for leaves `targetAcct`
+ * as `missing value` rather than failing, provided the profile gave a folder id
+ * to reach it by. `needsAccountObject` is for composing mail, which can't work
+ * without the object: the account a message is sent from can only be set from
+ * it, and a message composed without it goes out from the default mailbox.
+ */
+export declare function accountLookupSnippet(acct: MacAccount, needsAccountObject?: boolean): string;
+/**
+ * Bind `variable` to one of the account's well-known folders: through the
+ * account object when the probe found one, else by the folder's own id. `mail
+ * folder id N` resolves against the application rather than an account, and N is
+ * the id Outlook's profile database records for that folder.
+ */
+export declare function rootFolderSnippet(acct: MacAccount, term: string, variable: string): string;
+/**
+ * Outlook for Mac's dictionary term for each well-known root, by olDefaultFolders
+ * id. Verified against the running app: the terms are NOT what the Windows names
+ * suggest — `sent mail` and `junk email` don't compile, `sent items` and `junk
+ * mail` do — and one bad term fails the whole script at compile time.
  */
-export declare const MAC_ROOT_TERMS: Record<number, string>;
-/** The date property a folder's items actually carry. */
+export declare const MAC_ROOT_TERMS: Readonly<Record<number, string>>;
+/** The date property a root's items carry. */
 export declare function dateProperty(rootId: number): string;
 /**
- * The Windows `FolderPath` shape (`\\mailbox\Inbox\Invoices`), built here rather
- * than in AppleScript — escaping backslashes through a template literal and then
- * an AppleScript literal is unreadable, and TS already knows the parts.
+ * The Windows folder-path shape (`\\mailbox\Inbox\Invoices`), assembled in
+ * TypeScript: escaping backslashes through a template literal and then an
+ * AppleScript literal is unreadable, and the parts are known here anyway.
  */
-export declare function macFolderPath(emailAccount: string, rootLabel: string, segments: string[]): string;
-/** The dictionary term for a root, or a NOT_IMPLEMENTED naming what was asked. */
-export declare function rootTerm(ref: MailFolderRef, folderLabel?: string): string;
+export declare function macFolderPath(emailAccount: string, rootLabel: string, segments: readonly string[]): string;
 /**
- * Emit the AppleScript that resolves `scopeFolder` from `targetAcct`, walking a
- * well-known root down through any further path segments. Also binds
- * `scopeCreated`.
+ * Walk a folder's `container` chain to the top as the list `chainNames`,
+ * nearest first. Requires `theFolder`, and leaves `cur` on the folder the walk
+ * stopped at: the account's nameless root folder, when it got that far.
  *
- * Folder names are compared with `is`, which is case-insensitive in AppleScript —
- * matching the Windows walk's `-ieq` so 'invoices' finds 'Invoices' on both.
- * A missing segment errors by name instead of falling back to the root: silently
- * returning the Inbox for a caller that scoped to one folder hands back the wrong
- * emails under a name that says otherwise. `createMissing` builds the whole
- * chain instead, so a nested destination is one call.
+ * The chain's last element is the folder directly under the account, and an
+ * account can't hold two top-level folders of one name, so comparing that name
+ * is exact.
  */
-export declare function mailScopeSnippet(ref: MailFolderRef, folderLabel?: string, createMissing?: boolean): string;
+export declare function folderChainSnippet(indent: string): string;
 /**
- * The message-id text for a script, or an InvalidRequestError.
+ * Resolve `scopeFolder` from `targetAcct`: a well-known root walked down through
+ * any further segments. Also binds `scopeCreated`.
  *
- * Outlook for Mac ids are small integers; a Windows MAPI EntryID is rejected up
- * front rather than left to fail as a confusing "not found", because a caller
- * that persisted one from a Windows run needs to be told exactly that.
+ * Names compare with `is`, which is case-insensitive in AppleScript, matching
+ * the Windows walk. A missing segment fails as NOT_FOUND rather than falling
+ * back to the root; `createMissing` builds the chain instead.
  */
-export declare function macMessageId(entryId: string): string;
+export declare function mailScopeSnippet(acct: MacAccount, ref: MailFolderRef, folderLabel?: string, createMissing?: boolean): string;
 /**
- * Split ids into the ones a script can look up and the ones that can only fail.
+ * The message id text for a script, or INVALID_REQUEST.
  *
- * The per-id operations report failures rather than throwing, so an unusable id
- * belongs in the result's `failed` list beside a genuine lookup miss — not as an
- * exception that discards the ids that would have worked.
+ * Outlook for Mac ids are small integers; a Windows EntryID is refused up front
+ * rather than left to fail as a confusing "not found", because a caller that
+ * persisted one from a Windows run needs to be told exactly that.
+ */
+export declare function macMessageId(entryId: string): string;
+/**
+ * Split ids into those a script can look up and those that can only fail. A
+ * batch reports an unusable id beside a genuine miss rather than throwing and
+ * discarding the ids that would have worked.
  */
 export declare function partitionMessageIds(entryIds: readonly string[]): {
     valid: string[];
-    invalid: {
-        entryId: string;
-        error: string;
-    }[];
+    invalid: ItemFailure[];
 };
 /**
- * Resolve `theMsg` from a macOS message id, or raise.
- *
- * `message id N` resolves against the application rather than one folder, so the
- * message is found wherever it currently sits — including a subfolder.
+ * Bind `theMsg` to a message id, or fail as NOT_FOUND. `message id N` resolves
+ * against the application, so the message is found wherever it sits.
  */
-export declare function messageLookupSnippet(id: string, variable?: string): string;
+export declare function messageLookupSnippet(id: string): string;
 /**
- * The sender's display name and address, as `sndName` / `sndAddr`.
- *
- * `sender` yields a record, and `address of sender of m` fails to coerce, so the
- * record has to be bound first. `name` is absent when there is no display name.
+ * `theMsg`'s sender as `sndName` / `sndAddr`. `sender` is a record, and
+ * `address of sender of m` doesn't coerce, so the record is bound first.
  */
-export declare function senderSnippet(messageVariable?: string, indent?: string): string;
+export declare function senderSnippet(indent?: string): string;
 /**
- * Everything a reader wants off ONE message already bound to `theMsg`, and the
- * row it produces — emitted together so the read order and the positions the
- * TypeScript decoders index into cannot drift apart.
- *
- * Three callers share it (`readEmailBody`, `readSelectedEmail`, and the
- * attachment resolver) and differ only in how they bind `theMsg`. They used to
- * share it by copy: thirty lines repeated, with the `time received` → `time sent`
- * fallback and the field order restated each time, so a dictionary fix reached
- * one reader and not the others.
- *
- * `bodyText` is emitted LAST when asked for, so a stray separator in an earlier
- * field cannot shift it.
+ * Everything a reader wants off one message bound to `theMsg`, emitted together
+ * with the row it produces (see `messageDetailFields`) so the read order and the
+ * positions the decoders index into cannot drift apart. `bodyText` is emitted
+ * LAST when asked for, so a stray separator in an earlier field can't shift it.
  */
 export declare function messageDetailSnippet(withBody?: boolean, indent?: string): string;
-/**
- * The fields `messageDetailSnippet` fills, in row order. The decoders read them
- * back by the positions in `MessageDetail`.
- */
+/** The fields `messageDetailSnippet` fills, in row order — see `MessageDetail`. */
 export declare function messageDetailFields(withBody?: boolean): string[];
-/** Where each of those fields lands in the emitted row. */
+/** Where each of those fields lands in the row. */
 export declare const MessageDetail: {
     readonly id: 0;
     readonly subject: 1;
@@ -111,27 +118,19 @@ export declare const MessageDetail: {
     readonly body: 6;
 };
 /**
- * The first recipient's name and address, as `sndName` / `sndAddr` — what
- * outgoing mail reports in place of a sender, matching the Windows reader's
- * contract for Sent Items (a folder of mail from yourself is unreadable).
- */
-export declare function firstRecipientSnippet(messageVariable?: string, indent?: string): string;
-/**
- * Every SMTP address a message was addressed to, as the list `addrList`.
- *
- * `every recipient` covers To, CC and BCC — the full set, which is the whole
- * point of readSentRecipientGroups.
+ * `theMsg`'s first recipient as `sndName` / `sndAddr` — what outgoing mail
+ * reports in place of a sender.
  */
-export declare function allRecipientsSnippet(messageVariable?: string, indent?: string): string;
+export declare function firstRecipientSnippet(indent?: string): string;
+/** Every address `theMsg` was sent to — To, CC and BCC — as the list `addrList`. */
+export declare function allRecipientsSnippet(indent?: string): string;
 /**
- * Recursive folder-by-name search from `startFolder`, case-insensitive and
- * depth-capped — the macOS counterpart of the Windows Find-FolderByName, used to
- * resolve a template folder anywhere in the mailbox tree.
+ * Recursive, case-insensitive, depth-capped folder search from `startFolder` —
+ * the macOS counterpart of the Windows Find-FolderByName.
  */
 export declare const FIND_FOLDER_HANDLER = "\non findFolderByName(startFolder, wantedName, depth)\n    tell application \"Microsoft Outlook\"\n        set subs to mail folders of startFolder\n    end tell\n    repeat with f in subs\n        if (name of f as string) is wantedName then return f\n    end repeat\n    if depth is less than or equal to 1 then return missing value\n    repeat with f in subs\n        set hit to my findFolderByName(f, wantedName, depth - 1)\n        if hit is not missing value then return hit\n    end repeat\n    return missing value\nend findFolderByName\n";
 /**
- * Account enumeration only works when Outlook runs in legacy mode; New Outlook
- * errors on `every account` and returns empty lists for the typed classes, so
- * each class is probed independently and failures are ignored.
+ * Enumerate the accounts, probing each class separately: legacy Outlook errors
+ * on `every account`, and New Outlook returns empty lists for the classes.
  */
 export declare const LIST_ACCOUNTS_SNIPPET = "\nset acctList to {}\ntell application \"Microsoft Outlook\"\n    repeat with acctClass in {\"exchange\", \"imap\", \"pop\"}\n        try\n            if (acctClass as string) is \"exchange\" then\n                set accts to exchange accounts\n            else if (acctClass as string) is \"imap\" then\n                set accts to imap accounts\n            else\n                set accts to pop accounts\n            end if\n            repeat with a in accts\n                try\n                    set end of acctList to (email address of a as string)\n                end try\n            end repeat\n        end try\n    end repeat\nend tell\n";