@dawnlit/outlook-bridge 1.1.0 → 2.0.0

package/dist/runtime.js

@@ -3,54 +3,57 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.RUN_BUDGETS = void 0;
 exports.mergeOptions = mergeOptions;
 exports.configure = configure;
 exports.getConfig = getConfig;
 exports.getGlobalConfig = getGlobalConfig;
 exports.withConfig = withConfig;
+exports.timeoutFor = timeoutFor;
 exports.reportRun = reportRun;
 exports.tempFile = tempFile;
-exports.makeAttachmentDir = makeAttachmentDir;
-exports.resolveDestDir = resolveDestDir;
-// Process-wide knobs and shared scratch-file handling for the generated
-// PowerShell / AppleScript runs.
+exports.removeTempFile = removeTempFile;
+exports.attachmentDestination = attachmentDestination;
+// Settings, and the scratch files every run needs.
 //
-// Every call in this package works by generating a script and shelling out to an
-// interpreter, which leaves a consumer four things they cannot otherwise reach:
-// how long a run may take, how much it may print, how to call it off, and what
-// the script actually said when it failed. Those are the settings here.
+// Each operation generates a script and runs it under an interpreter, which
+// leaves a caller four things they cannot otherwise reach: how long a run may
+// take, how much it may print, how to call it off, and what the script actually
+// said. Those are the settings here — process-wide through `configure()`, or per
+// bridge through `createOutlookBridge()`.
 const async_hooks_1 = require("async_hooks");
 const fs_1 = __importDefault(require("fs"));
 const os_1 = __importDefault(require("os"));
 const path_1 = __importDefault(require("path"));
+const errors_1 = require("./errors");
 const envDebug = process.env.OUTLOOK_BRIDGE_DEBUG;
-/** The process-wide defaults, as mutated by `configure()`. */
-const globalConfig = {
-    timeoutMs: 120_000,
+/** The process-wide settings, as `configure()` leaves them. */
+let globalConfig = {
+    timeoutMs: undefined,
     maxBufferBytes: 8 * 1024 * 1024,
     tempDir: os_1.default.tmpdir(),
+    signal: undefined,
     debug: !!envDebug && envDebug !== '0',
 };
 /**
- * Per-instance config, scoped to an async call tree.
+ * Per-bridge settings, scoped to an async call tree.
  *
- * `createOutlookBridge()` hands each instance its own settings, but the platform
- * services are 3,000 lines of module-level functions that read `getConfig()`
- * directly. Threading a config parameter through all of them would touch every
- * line for no behavioural gain; an AsyncLocalStorage lets an instance wrap its
- * calls instead, and the store follows across every `await` inside one. Two
- * bridges with different timeouts can then run concurrently in one process,
- * which is the thing a second consumer actually needs and the global could never
- * give them.
+ * The platform code reads its settings through `getConfig()` wherever it needs
+ * them rather than having a config threaded through every function. A bridge
+ * instance runs each call inside `withConfig`, and the store follows every
+ * `await` beneath it — so two bridges with different timeouts can run at once
+ * in one process without seeing each other's.
  */
 const scoped = new async_hooks_1.AsyncLocalStorage();
-/** Merge caller options over a base, ignoring the keys they left out. */
+/** Caller options merged over a base; keys left out keep the base's value. */
 function mergeOptions(base, options = {}) {
     const next = { ...base };
-    if (options.timeoutMs !== undefined)
-        next.timeoutMs = Math.max(0, options.timeoutMs);
+    if (options.timeoutMs === null)
+        next.timeoutMs = undefined;
+    else if (options.timeoutMs !== undefined)
+        next.timeoutMs = nonNegative(options.timeoutMs, 'timeoutMs');
     if (options.maxBufferBytes !== undefined)
-        next.maxBufferBytes = Math.max(1, options.maxBufferBytes);
+        next.maxBufferBytes = Math.max(1, nonNegative(options.maxBufferBytes, 'maxBufferBytes'));
     if (options.tempDir !== undefined)
         next.tempDir = options.tempDir;
     if (options.signal !== undefined)
@@ -59,21 +62,27 @@ function mergeOptions(base, options = {}) {
         next.debug = options.debug;
     return next;
 }
+function nonNegative(value, name) {
+    if (typeof value !== 'number' || Number.isNaN(value)) {
+        throw new errors_1.InvalidRequestError(`${name} must be a number (got ${String(value)}).`);
+    }
+    return Math.max(0, Math.floor(value));
+}
 /**
- * Override the process-wide defaults. Merges, so naming one option leaves the
- * rest alone. Call before the first automation call.
+ * Change the process-wide settings. Merges, so naming one option leaves the
+ * rest alone.
  *
- * Affects every caller in the process. Prefer `createOutlookBridge(options)` in
- * anything that shares a process with code you don't own.
+ * Affects every caller in the process that uses the exported functions. Prefer
+ * `createOutlookBridge(options)` in a process shared with code you don't own.
  */
 function configure(options) {
-    Object.assign(globalConfig, mergeOptions(globalConfig, options));
+    globalConfig = mergeOptions(globalConfig, options);
 }
-/** The settings in force for the current call — the enclosing scope's, else global. */
+/** The settings in force for the current call: the enclosing bridge's, else the process-wide ones. */
 function getConfig() {
     return scoped.getStore() ?? globalConfig;
 }
-/** The process-wide defaults, ignoring any active scope. */
+/** The process-wide settings, ignoring any bridge scope. */
 function getGlobalConfig() {
     return globalConfig;
 }
@@ -81,7 +90,30 @@ function getGlobalConfig() {
 function withConfig(config, fn) {
     return scoped.run(config, fn);
 }
-/** Report one finished script run to the configured debug hook. */
+/**
+ * How long each kind of run may take when no `timeoutMs` is set.
+ *
+ * Generous on purpose: a budget is a guard against a hung interpreter, not a
+ * performance target, and the first call against an Outlook that isn't running
+ * yet spends much of its budget starting it.
+ */
+exports.RUN_BUDGETS = {
+    /** One lookup: accounts, signatures, opening or reading a single email. */
+    quick: 60_000,
+    /** Composing, filing, saving attachments, or reading one folder. */
+    standard: 120_000,
+    /** Walking a mailbox tree, or acting on a batch of items. */
+    scan: 300_000,
+    /** Emptying Deleted Items. */
+    purge: 600_000,
+};
+/** The timeout one run gets: the configured ceiling if there is one, else its budget. */
+function timeoutFor(budget) {
+    if (budget === 'interactive')
+        return 0;
+    return getConfig().timeoutMs ?? exports.RUN_BUDGETS[budget];
+}
+/** Report one finished run to the configured debug hook. */
 function reportRun(event) {
     const { debug } = getConfig();
     if (!debug)
@@ -94,30 +126,53 @@ function reportRun(event) {
     process.stderr.write(`[outlook-bridge] ${event.runner} ${event.durationMs}ms ${outcome}\n${event.script}\n`);
 }
 /**
- * Path for a scratch file in the configured temp directory. The random suffix
- * matters: two concurrent calls landing in the same millisecond would otherwise
- * pick the same name and overwrite each other's script mid-run.
+ * A scratch-file path in the configured temp directory. The random part
+ * matters: two concurrent calls in the same millisecond would otherwise pick the
+ * same name and overwrite each other's script mid-run.
  */
 function tempFile(kind, extension) {
     const unique = `${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
     return path_1.default.join(getConfig().tempDir, `outlook-bridge-${kind}-${unique}.${extension}`);
 }
+/** Delete a scratch file, ignoring one that is already gone. */
+function removeTempFile(file) {
+    try {
+        fs_1.default.unlinkSync(file);
+    }
+    catch {
+        // The run is over either way; a leftover scratch file isn't worth failing it.
+    }
+}
 /**
- * A fresh directory for one call's saved attachments.
+ * Where one call saves its attachments: the caller's directory (created if
+ * absent), or a fresh private directory of its own.
  *
- * Deliberately per-call rather than one shared folder: attachments are saved
- * under the name the sender gave them, so two emails that both carry
- * "invoice.pdf" would otherwise silently overwrite each other — and so would two
- * unrelated programs using this package on the same machine.
+ * Private by default because attachments keep the names senders gave them, so
+ * one shared folder means two emails carrying 'invoice.pdf' overwrite each
+ * other — and so do two programs using this package on one machine.
  */
-function makeAttachmentDir() {
-    return fs_1.default.mkdtempSync(path_1.default.join(getConfig().tempDir, 'outlook-bridge-attachments-'));
+function attachmentDestination(destDir) {
+    if (destDir) {
+        const existed = fs_1.default.existsSync(destDir);
+        fs_1.default.mkdirSync(destDir, { recursive: true });
+        return {
+            dir: destDir,
+            discardIfUnused() {
+                if (!existed)
+                    removeIfEmpty(destDir);
+            },
+        };
+    }
+    const dir = fs_1.default.mkdtempSync(path_1.default.join(getConfig().tempDir, 'outlook-bridge-attachments-'));
+    return { dir, discardIfUnused: () => removeIfEmpty(dir) };
 }
-/** Resolve a caller-supplied destination, creating it when absent. */
-function resolveDestDir(destDir) {
-    if (!destDir)
-        return makeAttachmentDir();
-    fs_1.default.mkdirSync(destDir, { recursive: true });
-    return destDir;
+function removeIfEmpty(dir) {
+    try {
+        if (fs_1.default.readdirSync(dir).length === 0)
+            fs_1.default.rmdirSync(dir);
+    }
+    catch {
+        // Nothing to undo if it can't be read.
+    }
 }
 //# sourceMappingURL=runtime.js.map

package/dist/runtime.js.map

@@ -1 +1 @@
-{"version":3,"file":"runtime.js","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":";;;;;AAkFA,oCAQC;AASD,8BAEC;AAGD,8BAEC;AAGD,0CAEC;AAGD,gCAEC;AAGD,8BAWC;AAOD,4BAGC;AAUD,8CAEC;AAGD,wCAIC;AA/JD,wEAAwE;AACxE,iCAAiC;AACjC,EAAE;AACF,iFAAiF;AACjF,gFAAgF;AAChF,+EAA+E;AAC/E,wEAAwE;AACxE,6CAAgD;AAChD,4CAAoB;AACpB,4CAAoB;AACpB,gDAAwB;AA+CxB,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,oBAAoB,CAAC;AAElD,8DAA8D;AAC9D,MAAM,YAAY,GAAmB;IACjC,SAAS,EAAE,OAAO;IAClB,cAAc,EAAE,CAAC,GAAG,IAAI,GAAG,IAAI;IAC/B,OAAO,EAAE,YAAE,CAAC,MAAM,EAAE;IACpB,KAAK,EAAE,CAAC,CAAC,QAAQ,IAAI,QAAQ,KAAK,GAAG;CACxC,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,GAAG,IAAI,+BAAiB,EAAkB,CAAC;AAEvD,yEAAyE;AACzE,SAAgB,YAAY,CAAC,IAAoB,EAAE,UAAyB,EAAE;IAC1E,MAAM,IAAI,GAAmB,EAAE,GAAG,IAAI,EAAE,CAAC;IACzC,IAAI,OAAO,CAAC,SAAS,KAAK,SAAS;QAAE,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,SAAS,CAAC,CAAC;IACrF,IAAI,OAAO,CAAC,cAAc,KAAK,SAAS;QAAE,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC,CAAC;IACpG,IAAI,OAAO,CAAC,OAAO,KAAK,SAAS;QAAE,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAClE,IAAI,OAAO,CAAC,MAAM,KAAK,SAAS;QAAE,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAC/D,IAAI,OAAO,CAAC,KAAK,KAAK,SAAS;QAAE,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC;IAC5D,OAAO,IAAI,CAAC;AAChB,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,SAAS,CAAC,OAAsB;IAC5C,MAAM,CAAC,MAAM,CAAC,YAAY,EAAE,YAAY,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC,CAAC;AACrE,CAAC;AAED,uFAAuF;AACvF,SAAgB,SAAS;IACrB,OAAO,MAAM,CAAC,QAAQ,EAAE,IAAI,YAAY,CAAC;AAC7C,CAAC;AAED,4DAA4D;AAC5D,SAAgB,eAAe;IAC3B,OAAO,YAAY,CAAC;AACxB,CAAC;AAED,uEAAuE;AACvE,SAAgB,UAAU,CAAI,MAAsB,EAAE,EAAW;IAC7D,OAAO,MAAM,CAAC,GAAG,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;AAClC,CAAC;AAED,mEAAmE;AACnE,SAAgB,SAAS,CAAC,KAAuB;IAC7C,MAAM,EAAE,KAAK,EAAE,GAAG,SAAS,EAAE,CAAC;IAC9B,IAAI,CAAC,KAAK;QAAE,OAAO;IACnB,IAAI,OAAO,KAAK,KAAK,UAAU,EAAE,CAAC;QAC9B,KAAK,CAAC,KAAK,CAAC,CAAC;QACb,OAAO;IACX,CAAC;IACD,MAAM,OAAO,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,WAAW,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;IAC9D,OAAO,CAAC,MAAM,CAAC,KAAK,CAChB,oBAAoB,KAAK,CAAC,MAAM,IAAI,KAAK,CAAC,UAAU,MAAM,OAAO,KAAK,KAAK,CAAC,MAAM,IAAI,CACzF,CAAC;AACN,CAAC;AAED;;;;GAIG;AACH,SAAgB,QAAQ,CAAC,IAAY,EAAE,SAAiB;IACpD,MAAM,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC;IAC1E,OAAO,cAAI,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC,OAAO,EAAE,kBAAkB,IAAI,IAAI,MAAM,IAAI,SAAS,EAAE,CAAC,CAAC;AAC3F,CAAC;AAED;;;;;;;GAOG;AACH,SAAgB,iBAAiB;IAC7B,OAAO,YAAE,CAAC,WAAW,CAAC,cAAI,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC,OAAO,EAAE,6BAA6B,CAAC,CAAC,CAAC;AACzF,CAAC;AAED,sEAAsE;AACtE,SAAgB,cAAc,CAAC,OAAgB;IAC3C,IAAI,CAAC,OAAO;QAAE,OAAO,iBAAiB,EAAE,CAAC;IACzC,YAAE,CAAC,SAAS,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC3C,OAAO,OAAO,CAAC;AACnB,CAAC"}
+{"version":3,"file":"runtime.js","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"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","sourcesContent":["// Settings, and the scratch files every run needs.\n//\n// Each operation generates a script and runs it under an interpreter, which\n// leaves a caller four things they cannot otherwise reach: how long a run may\n// take, how much it may print, how to call it off, and what the script actually\n// said. Those are the settings here — process-wide through `configure()`, or per\n// bridge through `createOutlookBridge()`.\nimport { AsyncLocalStorage } from 'async_hooks';\nimport fs from 'fs';\nimport os from 'os';\nimport path from 'path';\nimport { InvalidRequestError, type ScriptRunner } from './errors';\n\n/** One completed script run, handed to the `debug` hook. */\nexport interface BridgeDebugEvent {\n    runner: ScriptRunner;\n    /** The script exactly as it ran. */\n    script: string;\n    durationMs: number;\n    /** Present only when the run failed. */\n    error?: string;\n}\n\nexport interface BridgeOptions {\n    /**\n     * Ceiling on every script run, in milliseconds, replacing each operation's\n     * own budget; 0 disables timeouts. Leave unset (or pass null to go back) to\n     * let each operation use a budget sized for its work — a minute for a\n     * lookup, up to ten for purging Deleted Items. `editEmailTemplate` waits on\n     * a person and is never timed; cancel it with `signal`.\n     */\n    timeoutMs?: number | null;\n    /**\n     * Max bytes a script may print before the run is killed with\n     * OUTPUT_TOO_LARGE. Searches that return whole bodies push against this.\n     * Default 8 MiB.\n     */\n    maxBufferBytes?: number;\n    /** Directory for generated scripts, and for saved attachments when a call\n     *  names no destination. Default: the OS temp directory. */\n    tempDir?: string;\n    /**\n     * Cancels in-flight runs: the interpreter is killed and the call rejects\n     * with ABORTED. Most useful scoped to the calls it should cancel:\n     * `bridge.withOptions({ signal }).searchInboxByFilter(...)`.\n     */\n    signal?: AbortSignal;\n    /** `true` logs every script to stderr; a function receives each run\n     *  instead. Default: on when OUTLOOK_BRIDGE_DEBUG is set to anything but '' or '0'. */\n    debug?: boolean | ((event: BridgeDebugEvent) => void);\n}\n\n/** The settings a call runs with, every default applied. */\nexport interface ResolvedConfig {\n    /** undefined = each operation's own budget. */\n    readonly timeoutMs: number | undefined;\n    readonly maxBufferBytes: number;\n    readonly tempDir: string;\n    readonly signal: AbortSignal | undefined;\n    readonly debug: boolean | ((event: BridgeDebugEvent) => void);\n}\n\nconst envDebug = process.env.OUTLOOK_BRIDGE_DEBUG;\n\n/** The process-wide settings, as `configure()` leaves them. */\nlet globalConfig: ResolvedConfig = {\n    timeoutMs: undefined,\n    maxBufferBytes: 8 * 1024 * 1024,\n    tempDir: os.tmpdir(),\n    signal: undefined,\n    debug: !!envDebug && envDebug !== '0',\n};\n\n/**\n * Per-bridge settings, scoped to an async call tree.\n *\n * The platform code reads its settings through `getConfig()` wherever it needs\n * them rather than having a config threaded through every function. A bridge\n * instance runs each call inside `withConfig`, and the store follows every\n * `await` beneath it — so two bridges with different timeouts can run at once\n * in one process without seeing each other's.\n */\nconst scoped = new AsyncLocalStorage<ResolvedConfig>();\n\n/** Caller options merged over a base; keys left out keep the base's value. */\nexport function mergeOptions(base: ResolvedConfig, options: BridgeOptions = {}): ResolvedConfig {\n    const next = {...base};\n    if (options.timeoutMs === null) next.timeoutMs = undefined;\n    else if (options.timeoutMs !== undefined) next.timeoutMs = nonNegative(options.timeoutMs, 'timeoutMs');\n    if (options.maxBufferBytes !== undefined) next.maxBufferBytes = Math.max(1, nonNegative(options.maxBufferBytes, 'maxBufferBytes'));\n    if (options.tempDir !== undefined) next.tempDir = options.tempDir;\n    if (options.signal !== undefined) next.signal = options.signal;\n    if (options.debug !== undefined) next.debug = options.debug;\n    return next;\n}\n\nfunction nonNegative(value: number, name: string): number {\n    if (typeof value !== 'number' || Number.isNaN(value)) {\n        throw new InvalidRequestError(`${name} must be a number (got ${String(value)}).`);\n    }\n    return Math.max(0, Math.floor(value));\n}\n\n/**\n * Change the process-wide settings. Merges, so naming one option leaves the\n * rest alone.\n *\n * Affects every caller in the process that uses the exported functions. Prefer\n * `createOutlookBridge(options)` in a process shared with code you don't own.\n */\nexport function configure(options: BridgeOptions): void {\n    globalConfig = mergeOptions(globalConfig, options);\n}\n\n/** The settings in force for the current call: the enclosing bridge's, else the process-wide ones. */\nexport function getConfig(): ResolvedConfig {\n    return scoped.getStore() ?? globalConfig;\n}\n\n/** The process-wide settings, ignoring any bridge scope. */\nexport function getGlobalConfig(): ResolvedConfig {\n    return globalConfig;\n}\n\n/** Run `fn` with `config` in force for it and everything it awaits. */\nexport function withConfig<T>(config: ResolvedConfig, fn: () => T): T {\n    return scoped.run(config, fn);\n}\n\n/**\n * How long each kind of run may take when no `timeoutMs` is set.\n *\n * Generous on purpose: a budget is a guard against a hung interpreter, not a\n * performance target, and the first call against an Outlook that isn't running\n * yet spends much of its budget starting it.\n */\nexport const RUN_BUDGETS = {\n    /** One lookup: accounts, signatures, opening or reading a single email. */\n    quick: 60_000,\n    /** Composing, filing, saving attachments, or reading one folder. */\n    standard: 120_000,\n    /** Walking a mailbox tree, or acting on a batch of items. */\n    scan: 300_000,\n    /** Emptying Deleted Items. */\n    purge: 600_000,\n} as const;\n\n/** A budget name, or 'interactive' for a run that waits on a person and is never timed. */\nexport type RunBudget = keyof typeof RUN_BUDGETS | 'interactive';\n\n/** The timeout one run gets: the configured ceiling if there is one, else its budget. */\nexport function timeoutFor(budget: RunBudget): number {\n    if (budget === 'interactive') return 0;\n    return getConfig().timeoutMs ?? RUN_BUDGETS[budget];\n}\n\n/** Report one finished run to the configured debug hook. */\nexport function reportRun(event: BridgeDebugEvent): void {\n    const {debug} = getConfig();\n    if (!debug) return;\n    if (typeof debug === 'function') {\n        debug(event);\n        return;\n    }\n    const outcome = event.error ? `FAILED: ${event.error}` : 'ok';\n    process.stderr.write(`[outlook-bridge] ${event.runner} ${event.durationMs}ms ${outcome}\\n${event.script}\\n`);\n}\n\n/**\n * A scratch-file path in the configured temp directory. The random part\n * matters: two concurrent calls in the same millisecond would otherwise pick the\n * same name and overwrite each other's script mid-run.\n */\nexport function tempFile(kind: string, extension: string): string {\n    const unique = `${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;\n    return path.join(getConfig().tempDir, `outlook-bridge-${kind}-${unique}.${extension}`);\n}\n\n/** Delete a scratch file, ignoring one that is already gone. */\nexport function removeTempFile(file: string): void {\n    try {\n        fs.unlinkSync(file);\n    } catch {\n        // The run is over either way; a leftover scratch file isn't worth failing it.\n    }\n}\n\n/** A destination for saved attachments, and how to undo creating it. */\nexport interface AttachmentDestination {\n    dir: string;\n\n    /** Remove the directory if this call created it and left it empty. */\n    discardIfUnused(): void;\n}\n\n/**\n * Where one call saves its attachments: the caller's directory (created if\n * absent), or a fresh private directory of its own.\n *\n * Private by default because attachments keep the names senders gave them, so\n * one shared folder means two emails carrying 'invoice.pdf' overwrite each\n * other — and so do two programs using this package on one machine.\n */\nexport function attachmentDestination(destDir?: string): AttachmentDestination {\n    if (destDir) {\n        const existed = fs.existsSync(destDir);\n        fs.mkdirSync(destDir, {recursive: true});\n        return {\n            dir: destDir,\n            discardIfUnused() {\n                if (!existed) removeIfEmpty(destDir);\n            },\n        };\n    }\n    const dir = fs.mkdtempSync(path.join(getConfig().tempDir, 'outlook-bridge-attachments-'));\n    return {dir, discardIfUnused: () => removeIfEmpty(dir)};\n}\n\nfunction removeIfEmpty(dir: string): void {\n    try {\n        if (fs.readdirSync(dir).length === 0) fs.rmdirSync(dir);\n    } catch {\n        // Nothing to undo if it can't be read.\n    }\n}\n"]}

package/dist/shared/args.d.ts

@@ -0,0 +1,48 @@
+import type { EmailLocator, EmailRef, Recipients } from '../types';
+/** A required parameters object. */
+export declare function requireObject<T extends object>(value: T | undefined | null, name: string): Partial<T>;
+/** An optional options object; undefined and null are an empty one. */
+export declare function optionsObject<T extends object>(value: T | undefined | null, name?: string): Partial<T>;
+/** A required string, trimmed. Blank is an error. */
+export declare function requiredText(value: unknown, name: string): string;
+/** A required string kept exactly as given — content, not an identifier. May be empty. */
+export declare function requiredContent(value: unknown, name: string): string;
+/** Optional content kept exactly as given; undefined and null mean "not given". */
+export declare function optionalContent(value: unknown, name: string): string | undefined;
+/** An optional regular expression. */
+export declare function optionalRegExp(value: unknown, name: string): RegExp | undefined;
+/** An optional string, trimmed; undefined, null and blank all mean "not given". */
+export declare function optionalText(value: unknown, name: string): string | undefined;
+/** An optional flag; undefined and null take the fallback. */
+export declare function flag(value: unknown, name: string, fallback: boolean): boolean;
+/**
+ * An optional count: undefined and null take the fallback, a fraction is
+ * rounded down, and the result is clamped into [min, max] — the documented
+ * range is a guard, not a trap. Anything that isn't a finite number is an error.
+ */
+export declare function count(value: unknown, name: string, fallback: number, min: number, max: number): number;
+/** A list of strings, each non-blank and trimmed. Omitted is an empty list. */
+export declare function textList(value: unknown, name: string): string[];
+/** A list of names matched exactly as given — attachment file names, say. */
+export declare function nameList(value: unknown, name: string): string[];
+/** The entry ids a batch operation acts on. Duplicates are dropped; order is kept. */
+export declare function entryIdList(value: unknown, name?: string): string[];
+/** Where an email lives, from an id or anything carrying a locator. */
+export declare function emailLocator(email: EmailRef | undefined | null, name?: string): EmailLocator;
+/** A string→string map, e.g. template placeholders. */
+export declare function stringRecord(value: unknown, name: string): Record<string, string> | undefined;
+/**
+ * Split a recipient list into its entries.
+ *
+ * Separators are commas and semicolons — but not inside a quoted display name
+ * or between angle brackets, where `"Doe, Jo" <jo@example.com>` has a comma
+ * that belongs to the name.
+ */
+export declare function recipientList(value: Recipients | undefined | null, name: string): string[];
+/** One recipient entry as a display name and an address. */
+export interface ParsedRecipient {
+    name: string;
+    address: string;
+}
+/** `"Doe, Jo" <jo@example.com>` → name + address; a bare address has no name. */
+export declare function parseRecipient(entry: string): ParsedRecipient;

package/dist/shared/args.js

@@ -0,0 +1,216 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.requireObject = requireObject;
+exports.optionsObject = optionsObject;
+exports.requiredText = requiredText;
+exports.requiredContent = requiredContent;
+exports.optionalContent = optionalContent;
+exports.optionalRegExp = optionalRegExp;
+exports.optionalText = optionalText;
+exports.flag = flag;
+exports.count = count;
+exports.textList = textList;
+exports.nameList = nameList;
+exports.entryIdList = entryIdList;
+exports.emailLocator = emailLocator;
+exports.stringRecord = stringRecord;
+exports.recipientList = recipientList;
+exports.parseRecipient = parseRecipient;
+// Checking and normalizing what a caller passes, once, before either platform
+// sees it.
+//
+// This is a security boundary as much as a convenience. Arguments end up
+// inside generated scripts, and TypeScript's types vanish at run time: a
+// JavaScript caller, or a tool layer passing JSON through, can hand a string
+// where a count belongs. So every value is checked for its type here, every
+// count is made a whole number within its documented range, and the platform
+// code only ever receives values of the shape its script templates assume.
+const errors_1 = require("../errors");
+function describe(value) {
+    if (value === null)
+        return 'null';
+    if (Array.isArray(value))
+        return 'an array';
+    return typeof value === 'string' ? `'${value}'` : typeof value;
+}
+/** A required parameters object. */
+function requireObject(value, name) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        throw new errors_1.InvalidRequestError(`${name} must be an object (got ${describe(value)}).`);
+    }
+    return value;
+}
+/** An optional options object; undefined and null are an empty one. */
+function optionsObject(value, name = 'options') {
+    if (value === undefined || value === null)
+        return {};
+    return requireObject(value, name);
+}
+/** A required string, trimmed. Blank is an error. */
+function requiredText(value, name) {
+    if (typeof value !== 'string' || value.trim() === '') {
+        throw new errors_1.InvalidRequestError(`${name} is required and must be a non-empty string (got ${describe(value)}).`);
+    }
+    return value.trim();
+}
+/** A required string kept exactly as given — content, not an identifier. May be empty. */
+function requiredContent(value, name) {
+    if (typeof value !== 'string') {
+        throw new errors_1.InvalidRequestError(`${name} must be a string (got ${describe(value)}).`);
+    }
+    return value;
+}
+/** Optional content kept exactly as given; undefined and null mean "not given". */
+function optionalContent(value, name) {
+    if (value === undefined || value === null)
+        return undefined;
+    return requiredContent(value, name);
+}
+/** An optional regular expression. */
+function optionalRegExp(value, name) {
+    if (value === undefined || value === null)
+        return undefined;
+    // Checked by tag rather than instanceof, so a RegExp from another realm passes.
+    if (Object.prototype.toString.call(value) !== '[object RegExp]') {
+        throw new errors_1.InvalidRequestError(`${name} must be a RegExp (got ${describe(value)}).`);
+    }
+    return value;
+}
+/** An optional string, trimmed; undefined, null and blank all mean "not given". */
+function optionalText(value, name) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== 'string') {
+        throw new errors_1.InvalidRequestError(`${name} must be a string (got ${describe(value)}).`);
+    }
+    return value.trim() || undefined;
+}
+/** An optional flag; undefined and null take the fallback. */
+function flag(value, name, fallback) {
+    if (value === undefined || value === null)
+        return fallback;
+    if (typeof value !== 'boolean') {
+        throw new errors_1.InvalidRequestError(`${name} must be true or false (got ${describe(value)}).`);
+    }
+    return value;
+}
+/**
+ * An optional count: undefined and null take the fallback, a fraction is
+ * rounded down, and the result is clamped into [min, max] — the documented
+ * range is a guard, not a trap. Anything that isn't a finite number is an error.
+ */
+function count(value, name, fallback, min, max) {
+    if (value === undefined || value === null)
+        return fallback;
+    if (typeof value !== 'number' || !Number.isFinite(value)) {
+        throw new errors_1.InvalidRequestError(`${name} must be a finite number (got ${describe(value)}).`);
+    }
+    return Math.min(max, Math.max(min, Math.floor(value)));
+}
+/** A list of strings, each non-blank and trimmed. Omitted is an empty list. */
+function textList(value, name) {
+    if (value === undefined || value === null)
+        return [];
+    if (!Array.isArray(value)) {
+        throw new errors_1.InvalidRequestError(`${name} must be an array of strings (got ${describe(value)}).`);
+    }
+    return value.map((item, index) => requiredText(item, `${name}[${index}]`));
+}
+/** A list of names matched exactly as given — attachment file names, say. */
+function nameList(value, name) {
+    if (!Array.isArray(value)) {
+        throw new errors_1.InvalidRequestError(`${name} must be an array of strings (got ${describe(value)}).`);
+    }
+    return value.map((item, index) => {
+        if (typeof item !== 'string' || item.trim() === '') {
+            throw new errors_1.InvalidRequestError(`${name}[${index}] must be a non-empty string (got ${describe(item)}).`);
+        }
+        return item;
+    });
+}
+/** The entry ids a batch operation acts on. Duplicates are dropped; order is kept. */
+function entryIdList(value, name = 'entryIds') {
+    if (!Array.isArray(value)) {
+        throw new errors_1.InvalidRequestError(`${name} must be an array of entry ids (got ${describe(value)}).`);
+    }
+    return [...new Set(value.map((id, index) => requiredText(id, `${name}[${index}]`)))];
+}
+/** Where an email lives, from an id or anything carrying a locator. */
+function emailLocator(email, name = 'email') {
+    if (typeof email === 'string')
+        return { entryId: requiredText(email, name) };
+    if (email && typeof email === 'object') {
+        const entryId = requiredText(email.entryId, `${name}.entryId`);
+        const storeId = optionalText(email.storeId, `${name}.storeId`);
+        return storeId ? { entryId, storeId } : { entryId };
+    }
+    throw new errors_1.InvalidRequestError(`${name} must be an entry id or an object with an entryId (got ${describe(email)}).`);
+}
+/** A string→string map, e.g. template placeholders. */
+function stringRecord(value, name) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== 'object' || Array.isArray(value)) {
+        throw new errors_1.InvalidRequestError(`${name} must be an object of strings (got ${describe(value)}).`);
+    }
+    const out = {};
+    for (const [key, entry] of Object.entries(value)) {
+        if (typeof entry !== 'string') {
+            throw new errors_1.InvalidRequestError(`${name}.${key} must be a string (got ${describe(entry)}).`);
+        }
+        out[key] = entry;
+    }
+    return out;
+}
+/**
+ * Split a recipient list into its entries.
+ *
+ * Separators are commas and semicolons — but not inside a quoted display name
+ * or between angle brackets, where `"Doe, Jo" <jo@example.com>` has a comma
+ * that belongs to the name.
+ */
+function recipientList(value, name) {
+    if (value === undefined || value === null)
+        return [];
+    const parts = Array.isArray(value) ? value : [value];
+    const out = [];
+    parts.forEach((part, index) => {
+        if (typeof part !== 'string') {
+            throw new errors_1.InvalidRequestError(`${name}[${index}] must be a string (got ${describe(part)}).`);
+        }
+        out.push(...splitAddressList(part));
+    });
+    return out;
+}
+function splitAddressList(text) {
+    const entries = [];
+    let current = '';
+    let quoted = false;
+    let angled = false;
+    for (const ch of text) {
+        if (ch === '"' && !angled)
+            quoted = !quoted;
+        else if (ch === '<' && !quoted)
+            angled = true;
+        else if (ch === '>' && !quoted)
+            angled = false;
+        if ((ch === ',' || ch === ';') && !quoted && !angled) {
+            entries.push(current);
+            current = '';
+        }
+        else {
+            current += ch;
+        }
+    }
+    entries.push(current);
+    return entries.map(entry => entry.trim()).filter(Boolean);
+}
+/** `"Doe, Jo" <jo@example.com>` → name + address; a bare address has no name. */
+function parseRecipient(entry) {
+    const angled = /^(.*)<([^<>]+)>\s*$/.exec(entry);
+    if (!angled)
+        return { name: '', address: entry.trim() };
+    const name = angled[1].trim().replace(/^"(.*)"$/, '$1').trim();
+    return { name, address: angled[2].trim() };
+}
+//# sourceMappingURL=args.js.map

package/dist/shared/args.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"args.js","sourceRoot":"","sources":["../../src/shared/args.ts"],"names":[],"mappings":";;AAmBA,sCAKC;AAGD,sCAGC;AAGD,oCAKC;AAGD,0CAKC;AAGD,0CAGC;AAGD,wCAOC;AAGD,oCAMC;AAGD,oBAMC;AAOD,sBAMC;AAGD,4BAMC;AAGD,4BAUC;AAGD,kCAKC;AAGD,oCAQC;AAGD,oCAaC;AASD,sCAWC;AA6BD,wCAKC;AA5MD,8EAA8E;AAC9E,WAAW;AACX,EAAE;AACF,yEAAyE;AACzE,yEAAyE;AACzE,6EAA6E;AAC7E,4EAA4E;AAC5E,6EAA6E;AAC7E,2EAA2E;AAC3E,sCAAgD;AAGhD,SAAS,QAAQ,CAAC,KAAc;IAC5B,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,MAAM,CAAC;IAClC,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,UAAU,CAAC;IAC5C,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,KAAK,GAAG,CAAC,CAAC,CAAC,OAAO,KAAK,CAAC;AACnE,CAAC;AAED,oCAAoC;AACpC,SAAgB,aAAa,CAAmB,KAA2B,EAAE,IAAY;IACrF,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACtE,MAAM,IAAI,4BAAmB,CAAC,GAAG,IAAI,2BAA2B,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACzF,CAAC;IACD,OAAO,KAAK,CAAC;AACjB,CAAC;AAED,uEAAuE;AACvE,SAAgB,aAAa,CAAmB,KAA2B,EAAE,IAAI,GAAG,SAAS;IACzF,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,EAAE,CAAC;IACrD,OAAO,aAAa,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;AACtC,CAAC;AAED,qDAAqD;AACrD,SAAgB,YAAY,CAAC,KAAc,EAAE,IAAY;IACrD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QACnD,MAAM,IAAI,4BAAmB,CAAC,GAAG,IAAI,oDAAoD,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAClH,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,EAAE,CAAC;AACxB,CAAC;AAED,0FAA0F;AAC1F,SAAgB,eAAe,CAAC,KAAc,EAAE,IAAY;IACxD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC5B,MAAM,IAAI,4BAAmB,CAAC,GAAG,IAAI,0BAA0B,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACxF,CAAC;IACD,OAAO,KAAK,CAAC;AACjB,CAAC;AAED,mFAAmF;AACnF,SAAgB,eAAe,CAAC,KAAc,EAAE,IAAY;IACxD,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,SAAS,CAAC;IAC5D,OAAO,eAAe,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;AACxC,CAAC;AAED,sCAAsC;AACtC,SAAgB,cAAc,CAAC,KAAc,EAAE,IAAY;IACvD,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,SAAS,CAAC;IAC5D,gFAAgF;IAChF,IAAI,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,iBAAiB,EAAE,CAAC;QAC9D,MAAM,IAAI,4BAAmB,CAAC,GAAG,IAAI,0BAA0B,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACxF,CAAC;IACD,OAAO,KAAe,CAAC;AAC3B,CAAC;AAED,mFAAmF;AACnF,SAAgB,YAAY,CAAC,KAAc,EAAE,IAAY;IACrD,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,SAAS,CAAC;IAC5D,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC5B,MAAM,IAAI,4BAAmB,CAAC,GAAG,IAAI,0BAA0B,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACxF,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,EAAE,IAAI,SAAS,CAAC;AACrC,CAAC;AAED,8DAA8D;AAC9D,SAAgB,IAAI,CAAC,KAAc,EAAE,IAAY,EAAE,QAAiB;IAChE,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,QAAQ,CAAC;IAC3D,IAAI,OAAO,KAAK,KAAK,SAAS,EAAE,CAAC;QAC7B,MAAM,IAAI,4BAAmB,CAAC,GAAG,IAAI,+BAA+B,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC7F,CAAC;IACD,OAAO,KAAK,CAAC;AACjB,CAAC;AAED;;;;GAIG;AACH,SAAgB,KAAK,CAAC,KAAc,EAAE,IAAY,EAAE,QAAgB,EAAE,GAAW,EAAE,GAAW;IAC1F,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,QAAQ,CAAC;IAC3D,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QACvD,MAAM,IAAI,4BAAmB,CAAC,GAAG,IAAI,iCAAiC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC/F,CAAC;IACD,OAAO,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AAC3D,CAAC;AAED,+EAA+E;AAC/E,SAAgB,QAAQ,CAAC,KAAc,EAAE,IAAY;IACjD,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,EAAE,CAAC;IACrD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACxB,MAAM,IAAI,4BAAmB,CAAC,GAAG,IAAI,qCAAqC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACnG,CAAC;IACD,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,YAAY,CAAC,IAAI,EAAE,GAAG,IAAI,IAAI,KAAK,GAAG,CAAC,CAAC,CAAC;AAC/E,CAAC;AAED,6EAA6E;AAC7E,SAAgB,QAAQ,CAAC,KAAc,EAAE,IAAY;IACjD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACxB,MAAM,IAAI,4BAAmB,CAAC,GAAG,IAAI,qCAAqC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACnG,CAAC;IACD,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE;QAC7B,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;YACjD,MAAM,IAAI,4BAAmB,CAAC,GAAG,IAAI,IAAI,KAAK,qCAAqC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC3G,CAAC;QACD,OAAO,IAAI,CAAC;IAChB,CAAC,CAAC,CAAC;AACP,CAAC;AAED,sFAAsF;AACtF,SAAgB,WAAW,CAAC,KAAc,EAAE,IAAI,GAAG,UAAU;IACzD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACxB,MAAM,IAAI,4BAAmB,CAAC,GAAG,IAAI,uCAAuC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACrG,CAAC;IACD,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,KAAK,EAAE,EAAE,CAAC,YAAY,CAAC,EAAE,EAAE,GAAG,IAAI,IAAI,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;AACzF,CAAC;AAED,uEAAuE;AACvE,SAAgB,YAAY,CAAC,KAAkC,EAAE,IAAI,GAAG,OAAO;IAC3E,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,EAAC,OAAO,EAAE,YAAY,CAAC,KAAK,EAAE,IAAI,CAAC,EAAC,CAAC;IAC3E,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QACrC,MAAM,OAAO,GAAG,YAAY,CAAC,KAAK,CAAC,OAAO,EAAE,GAAG,IAAI,UAAU,CAAC,CAAC;QAC/D,MAAM,OAAO,GAAG,YAAY,CAAC,KAAK,CAAC,OAAO,EAAE,GAAG,IAAI,UAAU,CAAC,CAAC;QAC/D,OAAO,OAAO,CAAC,CAAC,CAAC,EAAC,OAAO,EAAE,OAAO,EAAC,CAAC,CAAC,CAAC,EAAC,OAAO,EAAC,CAAC;IACpD,CAAC;IACD,MAAM,IAAI,4BAAmB,CAAC,GAAG,IAAI,0DAA0D,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;AACxH,CAAC;AAED,uDAAuD;AACvD,SAAgB,YAAY,CAAC,KAAc,EAAE,IAAY;IACrD,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,SAAS,CAAC;IAC5D,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACpD,MAAM,IAAI,4BAAmB,CAAC,GAAG,IAAI,sCAAsC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACpG,CAAC;IACD,MAAM,GAAG,GAA2B,EAAE,CAAC;IACvC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QAC/C,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YAC5B,MAAM,IAAI,4BAAmB,CAAC,GAAG,IAAI,IAAI,GAAG,0BAA0B,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAC/F,CAAC;QACD,GAAG,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;IACrB,CAAC;IACD,OAAO,GAAG,CAAC;AACf,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,aAAa,CAAC,KAAoC,EAAE,IAAY;IAC5E,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,EAAE,CAAC;IACrD,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;IACrD,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE;QAC1B,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;YAC3B,MAAM,IAAI,4BAAmB,CAAC,GAAG,IAAI,IAAI,KAAK,2BAA2B,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACjG,CAAC;QACD,GAAG,CAAC,IAAI,CAAC,GAAG,gBAAgB,CAAC,IAAI,CAAC,CAAC,CAAC;IACxC,CAAC,CAAC,CAAC;IACH,OAAO,GAAG,CAAC;AACf,CAAC;AAED,SAAS,gBAAgB,CAAC,IAAY;IAClC,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,IAAI,OAAO,GAAG,EAAE,CAAC;IACjB,IAAI,MAAM,GAAG,KAAK,CAAC;IACnB,IAAI,MAAM,GAAG,KAAK,CAAC;IACnB,KAAK,MAAM,EAAE,IAAI,IAAI,EAAE,CAAC;QACpB,IAAI,EAAE,KAAK,GAAG,IAAI,CAAC,MAAM;YAAE,MAAM,GAAG,CAAC,MAAM,CAAC;aACvC,IAAI,EAAE,KAAK,GAAG,IAAI,CAAC,MAAM;YAAE,MAAM,GAAG,IAAI,CAAC;aACzC,IAAI,EAAE,KAAK,GAAG,IAAI,CAAC,MAAM;YAAE,MAAM,GAAG,KAAK,CAAC;QAC/C,IAAI,CAAC,EAAE,KAAK,GAAG,IAAI,EAAE,KAAK,GAAG,CAAC,IAAI,CAAC,MAAM,IAAI,CAAC,MAAM,EAAE,CAAC;YACnD,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YACtB,OAAO,GAAG,EAAE,CAAC;QACjB,CAAC;aAAM,CAAC;YACJ,OAAO,IAAI,EAAE,CAAC;QAClB,CAAC;IACL,CAAC;IACD,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACtB,OAAO,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;AAC9D,CAAC;AAQD,iFAAiF;AACjF,SAAgB,cAAc,CAAC,KAAa;IACxC,MAAM,MAAM,GAAG,qBAAqB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACjD,IAAI,CAAC,MAAM;QAAE,OAAO,EAAC,IAAI,EAAE,EAAE,EAAE,OAAO,EAAE,KAAK,CAAC,IAAI,EAAE,EAAC,CAAC;IACtD,MAAM,IAAI,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC;IAC/D,OAAO,EAAC,IAAI,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,EAAC,CAAC;AAC7C,CAAC","sourcesContent":["// Checking and normalizing what a caller passes, once, before either platform\n// sees it.\n//\n// This is a security boundary as much as a convenience. Arguments end up\n// inside generated scripts, and TypeScript's types vanish at run time: a\n// JavaScript caller, or a tool layer passing JSON through, can hand a string\n// where a count belongs. So every value is checked for its type here, every\n// count is made a whole number within its documented range, and the platform\n// code only ever receives values of the shape its script templates assume.\nimport { InvalidRequestError } from '../errors';\nimport type { EmailLocator, EmailRef, Recipients } from '../types';\n\nfunction describe(value: unknown): string {\n    if (value === null) return 'null';\n    if (Array.isArray(value)) return 'an array';\n    return typeof value === 'string' ? `'${value}'` : typeof value;\n}\n\n/** A required parameters object. */\nexport function requireObject<T extends object>(value: T | undefined | null, name: string): Partial<T> {\n    if (value === null || typeof value !== 'object' || Array.isArray(value)) {\n        throw new InvalidRequestError(`${name} must be an object (got ${describe(value)}).`);\n    }\n    return value;\n}\n\n/** An optional options object; undefined and null are an empty one. */\nexport function optionsObject<T extends object>(value: T | undefined | null, name = 'options'): Partial<T> {\n    if (value === undefined || value === null) return {};\n    return requireObject(value, name);\n}\n\n/** A required string, trimmed. Blank is an error. */\nexport function requiredText(value: unknown, name: string): string {\n    if (typeof value !== 'string' || value.trim() === '') {\n        throw new InvalidRequestError(`${name} is required and must be a non-empty string (got ${describe(value)}).`);\n    }\n    return value.trim();\n}\n\n/** A required string kept exactly as given — content, not an identifier. May be empty. */\nexport function requiredContent(value: unknown, name: string): string {\n    if (typeof value !== 'string') {\n        throw new InvalidRequestError(`${name} must be a string (got ${describe(value)}).`);\n    }\n    return value;\n}\n\n/** Optional content kept exactly as given; undefined and null mean \"not given\". */\nexport function optionalContent(value: unknown, name: string): string | undefined {\n    if (value === undefined || value === null) return undefined;\n    return requiredContent(value, name);\n}\n\n/** An optional regular expression. */\nexport function optionalRegExp(value: unknown, name: string): RegExp | undefined {\n    if (value === undefined || value === null) return undefined;\n    // Checked by tag rather than instanceof, so a RegExp from another realm passes.\n    if (Object.prototype.toString.call(value) !== '[object RegExp]') {\n        throw new InvalidRequestError(`${name} must be a RegExp (got ${describe(value)}).`);\n    }\n    return value as RegExp;\n}\n\n/** An optional string, trimmed; undefined, null and blank all mean \"not given\". */\nexport function optionalText(value: unknown, name: string): string | undefined {\n    if (value === undefined || value === null) return undefined;\n    if (typeof value !== 'string') {\n        throw new InvalidRequestError(`${name} must be a string (got ${describe(value)}).`);\n    }\n    return value.trim() || undefined;\n}\n\n/** An optional flag; undefined and null take the fallback. */\nexport function flag(value: unknown, name: string, fallback: boolean): boolean {\n    if (value === undefined || value === null) return fallback;\n    if (typeof value !== 'boolean') {\n        throw new InvalidRequestError(`${name} must be true or false (got ${describe(value)}).`);\n    }\n    return value;\n}\n\n/**\n * An optional count: undefined and null take the fallback, a fraction is\n * rounded down, and the result is clamped into [min, max] — the documented\n * range is a guard, not a trap. Anything that isn't a finite number is an error.\n */\nexport function count(value: unknown, name: string, fallback: number, min: number, max: number): number {\n    if (value === undefined || value === null) return fallback;\n    if (typeof value !== 'number' || !Number.isFinite(value)) {\n        throw new InvalidRequestError(`${name} must be a finite number (got ${describe(value)}).`);\n    }\n    return Math.min(max, Math.max(min, Math.floor(value)));\n}\n\n/** A list of strings, each non-blank and trimmed. Omitted is an empty list. */\nexport function textList(value: unknown, name: string): string[] {\n    if (value === undefined || value === null) return [];\n    if (!Array.isArray(value)) {\n        throw new InvalidRequestError(`${name} must be an array of strings (got ${describe(value)}).`);\n    }\n    return value.map((item, index) => requiredText(item, `${name}[${index}]`));\n}\n\n/** A list of names matched exactly as given — attachment file names, say. */\nexport function nameList(value: unknown, name: string): string[] {\n    if (!Array.isArray(value)) {\n        throw new InvalidRequestError(`${name} must be an array of strings (got ${describe(value)}).`);\n    }\n    return value.map((item, index) => {\n        if (typeof item !== 'string' || item.trim() === '') {\n            throw new InvalidRequestError(`${name}[${index}] must be a non-empty string (got ${describe(item)}).`);\n        }\n        return item;\n    });\n}\n\n/** The entry ids a batch operation acts on. Duplicates are dropped; order is kept. */\nexport function entryIdList(value: unknown, name = 'entryIds'): string[] {\n    if (!Array.isArray(value)) {\n        throw new InvalidRequestError(`${name} must be an array of entry ids (got ${describe(value)}).`);\n    }\n    return [...new Set(value.map((id, index) => requiredText(id, `${name}[${index}]`)))];\n}\n\n/** Where an email lives, from an id or anything carrying a locator. */\nexport function emailLocator(email: EmailRef | undefined | null, name = 'email'): EmailLocator {\n    if (typeof email === 'string') return {entryId: requiredText(email, name)};\n    if (email && typeof email === 'object') {\n        const entryId = requiredText(email.entryId, `${name}.entryId`);\n        const storeId = optionalText(email.storeId, `${name}.storeId`);\n        return storeId ? {entryId, storeId} : {entryId};\n    }\n    throw new InvalidRequestError(`${name} must be an entry id or an object with an entryId (got ${describe(email)}).`);\n}\n\n/** A string→string map, e.g. template placeholders. */\nexport function stringRecord(value: unknown, name: string): Record<string, string> | undefined {\n    if (value === undefined || value === null) return undefined;\n    if (typeof value !== 'object' || Array.isArray(value)) {\n        throw new InvalidRequestError(`${name} must be an object of strings (got ${describe(value)}).`);\n    }\n    const out: Record<string, string> = {};\n    for (const [key, entry] of Object.entries(value)) {\n        if (typeof entry !== 'string') {\n            throw new InvalidRequestError(`${name}.${key} must be a string (got ${describe(entry)}).`);\n        }\n        out[key] = entry;\n    }\n    return out;\n}\n\n/**\n * Split a recipient list into its entries.\n *\n * Separators are commas and semicolons — but not inside a quoted display name\n * or between angle brackets, where `\"Doe, Jo\" <jo@example.com>` has a comma\n * that belongs to the name.\n */\nexport function recipientList(value: Recipients | undefined | null, name: string): string[] {\n    if (value === undefined || value === null) return [];\n    const parts = Array.isArray(value) ? value : [value];\n    const out: string[] = [];\n    parts.forEach((part, index) => {\n        if (typeof part !== 'string') {\n            throw new InvalidRequestError(`${name}[${index}] must be a string (got ${describe(part)}).`);\n        }\n        out.push(...splitAddressList(part));\n    });\n    return out;\n}\n\nfunction splitAddressList(text: string): string[] {\n    const entries: string[] = [];\n    let current = '';\n    let quoted = false;\n    let angled = false;\n    for (const ch of text) {\n        if (ch === '\"' && !angled) quoted = !quoted;\n        else if (ch === '<' && !quoted) angled = true;\n        else if (ch === '>' && !quoted) angled = false;\n        if ((ch === ',' || ch === ';') && !quoted && !angled) {\n            entries.push(current);\n            current = '';\n        } else {\n            current += ch;\n        }\n    }\n    entries.push(current);\n    return entries.map(entry => entry.trim()).filter(Boolean);\n}\n\n/** One recipient entry as a display name and an address. */\nexport interface ParsedRecipient {\n    name: string;\n    address: string;\n}\n\n/** `\"Doe, Jo\" <jo@example.com>` → name + address; a bare address has no name. */\nexport function parseRecipient(entry: string): ParsedRecipient {\n    const angled = /^(.*)<([^<>]+)>\\s*$/.exec(entry);\n    if (!angled) return {name: '', address: entry.trim()};\n    const name = angled[1].trim().replace(/^\"(.*)\"$/, '$1').trim();\n    return {name, address: angled[2].trim()};\n}\n"]}

package/dist/shared/attachmentMatch.d.ts

@@ -1,32 +1,44 @@
 /**
  * Collapse whitespace runs (non-breaking spaces included) and trim, so a
- * trivially reformatted filename still resolves. Both platforms' regex engines
- * treat `\s` as covering U+00A0, which is the character a mail client is most
- * likely to have substituted.
+ * trivially reformatted file name still resolves. Both platforms' regex engines
+ * count U+00A0 as whitespace.
  */
 export declare function normalizeAttachmentName(name: string): string;
 /**
- * Index of the attachment matching `wanted`, or -1.
- *
- * Exact first, then whitespace-normalized and case-insensitive — in that order,
- * so an email carrying two names differing only in case still resolves the one
- * that was actually asked for.
+ * Index of the attachment matching `wanted`, or -1: exact first, then
+ * whitespace-normalized and case-insensitive — in that order, so two names that
+ * differ only in case still resolve the one asked for.
  */
 export declare function findAttachmentIndex(names: readonly string[], wanted: string): number;
 /**
- * The "attachment not found" message, worded once for both platforms.
- *
- * Every field arrives already stringified, which is what lets the Windows script
- * build the identical sentence: it passes PowerShell interpolations
- * (`$($item.Subject)`) where macOS passes the values it read.
+ * The "attachment not found" message, worded once for both platforms. Fields
+ * arrive as strings so the Windows script can build the same sentence from
+ * PowerShell variables where macOS passes the values it read.
  */
 export declare function attachmentNotFoundMessage(init: {
     fileName: string;
     senderEmail: string;
     subject: string;
     receivedTime: string;
-    /** The attachments the email does carry, already joined for display. */
+    /** The attachments the email does carry, joined for display. */
     present: string;
-    /** What this platform calls the id, for the closing advice. */
-    idLabel: string;
 }): string;
+/** Characters no file name may carry on Windows (a superset of macOS's). */
+export declare const UNSAFE_FILE_NAME_CHARS = "[<>:\"/\\\\|?*\\x00-\\x1F]";
+/** Names Windows reserves for devices, with or without an extension. */
+export declare const RESERVED_FILE_NAME = "^(con|prn|aux|nul|com[1-9]|lpt[1-9])(\\..*)?$";
+/** How long a saved name's stem may run before it is cut. */
+export declare const MAX_FILE_STEM = 150;
+/**
+ * A sender-chosen attachment name made safe to write: no path separators or
+ * characters a file system rejects, no trailing dots or spaces, no reserved
+ * device name, and a stem short enough to stay clear of path-length limits. A
+ * name like `..\..\x.exe` therefore lands inside the destination as
+ * `.._.._x.exe`, never outside it.
+ */
+export declare function safeFileName(name: string): string;
+/**
+ * A path in `dir` for `name` that `exists` reports free: the name itself, else
+ * `name (1).ext`, `name (2).ext`, … Existing files are never overwritten.
+ */
+export declare function uniqueSavePath(dir: string, name: string, exists: (file: string) => boolean): string;