@jbctechsolutions/mcp-office365 2.5.1 → 3.0.0

package/dist/registry/context.js

@@ -0,0 +1,31 @@
+/**
+ * Copyright (c) 2026 JBC Tech Solutions, LLC
+ * Licensed under the MIT License. See LICENSE file in the project root.
+ */
+/**
+ * Resolves an initialized Graph-backend toolset from the runtime context, or
+ * throws a clear error when the Graph backend is unavailable.
+ *
+ * Centralizes the per-domain "resolve toolset or throw" boilerplate so every
+ * migrated domain shares one implementation instead of hand-rolling a null
+ * check. The `key` is type-checked against the augmented `GraphToolsets`, and
+ * the return type is the exact toolset class for that key.
+ */
+export function requireGraphToolset(ctx, key) {
+    if (ctx.graph == null) {
+        throw new Error('This tool requires the Microsoft Graph API backend.');
+    }
+    return ctx.graph[key];
+}
+/**
+ * Resolves an initialized AppleScript-backend toolset from the runtime context,
+ * or throws when the AppleScript backend is unavailable. The dual-backend
+ * counterpart to {@link requireGraphToolset}.
+ */
+export function requireAppleScriptToolset(ctx, key) {
+    if (ctx.applescript == null) {
+        throw new Error('This tool requires the AppleScript (classic Outlook) backend.');
+    }
+    return ctx.applescript[key];
+}
+//# sourceMappingURL=context.js.map

package/dist/registry/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/registry/context.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAQH;;;;;;;;GAQG;AACH,MAAM,UAAU,mBAAmB,CACjC,GAAgB,EAChB,GAAM;IAEN,IAAI,GAAG,CAAC,KAAK,IAAI,IAAI,EAAE,CAAC;QACtB,MAAM,IAAI,KAAK,CAAC,qDAAqD,CAAC,CAAC;IACzE,CAAC;IACD,OAAO,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;AACxB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,yBAAyB,CACvC,GAAgB,EAChB,GAAM;IAEN,IAAI,GAAG,CAAC,WAAW,IAAI,IAAI,EAAE,CAAC;QAC5B,MAAM,IAAI,KAAK,CAAC,+DAA+D,CAAC,CAAC;IACnF,CAAC;IACD,OAAO,GAAG,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;AAC9B,CAAC"}

package/dist/registry/define-tool.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Copyright (c) 2026 JBC Tech Solutions, LLC
+ * Licensed under the MIT License. See LICENSE file in the project root.
+ */
+/**
+ * `defineTool` — typed helper for authoring a tool definition.
+ *
+ * Preserves the inference link between the Zod input schema and the handler's
+ * `params` argument, so a domain module declares its schema once and the
+ * handler is type-checked against it.
+ */
+import type { z } from 'zod';
+import type { ToolDefinition } from './types.js';
+export declare function defineTool<S extends z.ZodType>(def: ToolDefinition<S>): ToolDefinition<S>;
+//# sourceMappingURL=define-tool.d.ts.map

package/dist/registry/define-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-tool.d.ts","sourceRoot":"","sources":["../../src/registry/define-tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD,wBAAgB,UAAU,CAAC,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,GAAG,EAAE,cAAc,CAAC,CAAC,CAAC,GAAG,cAAc,CAAC,CAAC,CAAC,CAEzF"}

package/dist/registry/define-tool.js

@@ -0,0 +1,8 @@
+/**
+ * Copyright (c) 2026 JBC Tech Solutions, LLC
+ * Licensed under the MIT License. See LICENSE file in the project root.
+ */
+export function defineTool(def) {
+    return def;
+}
+//# sourceMappingURL=define-tool.js.map

package/dist/registry/define-tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-tool.js","sourceRoot":"","sources":["../../src/registry/define-tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAaH,MAAM,UAAU,UAAU,CAAsB,GAAsB;IACpE,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/registry/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Copyright (c) 2026 JBC Tech Solutions, LLC
+ * Licensed under the MIT License. See LICENSE file in the project root.
+ */
+/**
+ * Tool registry barrel.
+ */
+export type { Backend, Preset, ToolAnnotations, ToolResult, ToolContext, ToolDefinition, GraphToolsets, AppleScriptToolsets, } from './types.js';
+export { ToolRegistry, toInputSchema } from './registry.js';
+export type { SurfaceOptions } from './registry.js';
+export { defineTool } from './define-tool.js';
+export { requireGraphToolset, requireAppleScriptToolset } from './context.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/registry/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/registry/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;GAEG;AAEH,YAAY,EACV,OAAO,EACP,MAAM,EACN,eAAe,EACf,UAAU,EACV,WAAW,EACX,cAAc,EACd,aAAa,EACb,mBAAmB,GACpB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC5D,YAAY,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,mBAAmB,EAAE,yBAAyB,EAAE,MAAM,cAAc,CAAC"}

package/dist/registry/index.js

@@ -0,0 +1,8 @@
+/**
+ * Copyright (c) 2026 JBC Tech Solutions, LLC
+ * Licensed under the MIT License. See LICENSE file in the project root.
+ */
+export { ToolRegistry, toInputSchema } from './registry.js';
+export { defineTool } from './define-tool.js';
+export { requireGraphToolset, requireAppleScriptToolset } from './context.js';
+//# sourceMappingURL=index.js.map

package/dist/registry/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/registry/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAgBH,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAE5D,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,mBAAmB,EAAE,yBAAyB,EAAE,MAAM,cAAc,CAAC"}

package/dist/registry/registry.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Copyright (c) 2026 JBC Tech Solutions, LLC
+ * Licensed under the MIT License. See LICENSE file in the project root.
+ */
+/**
+ * ToolRegistry — single source of truth for the MCP tool surface (U1).
+ *
+ * Holds tool definitions, derives the advertised JSON Schema from each Zod
+ * schema, filters the surface by backend / preset / read-only, and dispatches
+ * a call to the matching handler after validating its arguments.
+ */
+import { z } from 'zod';
+import type { Tool } from '@modelcontextprotocol/sdk/types.js';
+import type { Backend, Preset, ToolContext, ToolDefinition, ToolResult } from './types.js';
+/** Options controlling which tools are exposed to a client. */
+export interface SurfaceOptions {
+    readonly backend: Backend;
+    /** Presets to include. Undefined/empty means the full surface. */
+    readonly presets?: readonly Preset[];
+    /** When true, only non-destructive tools are exposed. */
+    readonly readOnly?: boolean;
+}
+/**
+ * Converts a Zod schema to an MCP-compatible `inputSchema`.
+ *
+ * Uses zod 4's native `z.toJSONSchema` (draft-07 target) and strips the
+ * `$schema` key, which MCP's `Tool.inputSchema` does not carry. Transitional
+ * alias keys (U6/D11) are handled by the input pipeline, not here; when a
+ * schema opts into aliases it should expose them as optional properties so the
+ * advertised schema stays validation-safe.
+ */
+export declare function toInputSchema(schema: z.ZodType): Tool['inputSchema'];
+/**
+ * In-memory registry of tool definitions.
+ */
+export declare class ToolRegistry {
+    private readonly definitions;
+    /** Registers a batch of tool definitions. Throws on a duplicate name. */
+    register(defs: readonly ToolDefinition[]): void;
+    /** True when a tool with this name is registered. */
+    has(name: string): boolean;
+    /** All registered names, insertion order preserved. */
+    names(): string[];
+    /** Returns a single definition, or undefined. */
+    get(name: string): ToolDefinition | undefined;
+    /**
+     * Returns the MCP tool list for a given surface, filtered by backend,
+     * preset membership, and read-only mode.
+     */
+    listTools(options: SurfaceOptions): Tool[];
+    /** True when a tool is exposed under the given surface. */
+    isExposed(name: string, options: SurfaceOptions): boolean;
+    /**
+     * Validates arguments against the tool's schema and invokes its handler.
+     * Returns undefined when no tool with this name is registered, so the caller
+     * can fall back to the legacy dispatch during the U2 migration window.
+     */
+    dispatch(name: string, args: unknown, ctx: ToolContext, options: SurfaceOptions): Promise<ToolResult | undefined>;
+    private filtered;
+    private matches;
+}
+//# sourceMappingURL=registry.d.ts.map

package/dist/registry/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/registry/registry.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;GAMG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,oCAAoC,CAAC;AAE/D,OAAO,KAAK,EACV,OAAO,EACP,MAAM,EACN,WAAW,EACX,cAAc,EACd,UAAU,EACX,MAAM,YAAY,CAAC;AAEpB,+DAA+D;AAC/D,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,kEAAkE;IAClE,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,yDAAyD;IACzD,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,GAAG,IAAI,CAAC,aAAa,CAAC,CAWpE;AAED;;GAEG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAqC;IAEjE,yEAAyE;IACzE,QAAQ,CAAC,IAAI,EAAE,SAAS,cAAc,EAAE,GAAG,IAAI;IAS/C,qDAAqD;IACrD,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI1B,uDAAuD;IACvD,KAAK,IAAI,MAAM,EAAE;IAIjB,iDAAiD;IACjD,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS;IAI7C;;;OAGG;IACH,SAAS,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI,EAAE;IAc1C,2DAA2D;IAC3D,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO;IAKzD;;;;OAIG;IACG,QAAQ,CACZ,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,OAAO,EACb,GAAG,EAAE,WAAW,EAChB,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC;IAsBlC,OAAO,CAAC,QAAQ;IAIhB,OAAO,CAAC,OAAO;CAahB"}

package/dist/registry/registry.js

@@ -0,0 +1,134 @@
+/**
+ * Copyright (c) 2026 JBC Tech Solutions, LLC
+ * Licensed under the MIT License. See LICENSE file in the project root.
+ */
+/**
+ * ToolRegistry — single source of truth for the MCP tool surface (U1).
+ *
+ * Holds tool definitions, derives the advertised JSON Schema from each Zod
+ * schema, filters the surface by backend / preset / read-only, and dispatches
+ * a call to the matching handler after validating its arguments.
+ */
+import { z } from 'zod';
+import { ReadOnlyModeError } from '../utils/errors.js';
+/**
+ * Converts a Zod schema to an MCP-compatible `inputSchema`.
+ *
+ * Uses zod 4's native `z.toJSONSchema` (draft-07 target) and strips the
+ * `$schema` key, which MCP's `Tool.inputSchema` does not carry. Transitional
+ * alias keys (U6/D11) are handled by the input pipeline, not here; when a
+ * schema opts into aliases it should expose them as optional properties so the
+ * advertised schema stays validation-safe.
+ */
+export function toInputSchema(schema) {
+    // `io: 'input'` — the advertised schema describes what a CLIENT sends, so a
+    // field with a `.default()` is optional (the server fills the default at
+    // parse time). Zod 4's default `io: 'output'` would mark defaulted fields as
+    // required, misleading agents into always supplying them.
+    const json = z.toJSONSchema(schema, { target: 'draft-7', io: 'input' });
+    delete json['$schema'];
+    if (json['type'] == null) {
+        json['type'] = 'object';
+    }
+    return json;
+}
+/**
+ * In-memory registry of tool definitions.
+ */
+export class ToolRegistry {
+    definitions = new Map();
+    /** Registers a batch of tool definitions. Throws on a duplicate name. */
+    register(defs) {
+        for (const def of defs) {
+            if (this.definitions.has(def.name)) {
+                throw new Error(`Duplicate tool registration: "${def.name}"`);
+            }
+            this.definitions.set(def.name, def);
+        }
+    }
+    /** True when a tool with this name is registered. */
+    has(name) {
+        return this.definitions.has(name);
+    }
+    /** All registered names, insertion order preserved. */
+    names() {
+        return [...this.definitions.keys()];
+    }
+    /** Returns a single definition, or undefined. */
+    get(name) {
+        return this.definitions.get(name);
+    }
+    /**
+     * Returns the MCP tool list for a given surface, filtered by backend,
+     * preset membership, and read-only mode.
+     */
+    listTools(options) {
+        return this.filtered(options).map((def) => {
+            const tool = {
+                name: def.name,
+                description: def.description,
+                inputSchema: toInputSchema(def.input),
+            };
+            if (Object.keys(def.annotations).length > 0) {
+                return { ...tool, annotations: def.annotations };
+            }
+            return tool;
+        });
+    }
+    /** True when a tool is exposed under the given surface. */
+    isExposed(name, options) {
+        const def = this.definitions.get(name);
+        return def != null && this.matches(def, options);
+    }
+    /**
+     * Validates arguments against the tool's schema and invokes its handler.
+     * Returns undefined when no tool with this name is registered, so the caller
+     * can fall back to the legacy dispatch during the U2 migration window.
+     */
+    async dispatch(name, args, ctx, options) {
+        const def = this.definitions.get(name);
+        if (def == null) {
+            return undefined;
+        }
+        if (!this.matches(def, options)) {
+            // Distinguish the read-only rejection so it surfaces a stable
+            // READ_ONLY_MODE envelope (D13) — but only when read-only is the *sole*
+            // reason (the tool would otherwise be exposed). A tool also filtered by
+            // backend/preset gets the generic error, avoiding misattribution.
+            if (options.readOnly === true && this.matches(def, { ...options, readOnly: false })) {
+                throw new ReadOnlyModeError(name);
+            }
+            throw new Error(`Tool "${name}" is not available in the current mode.`);
+        }
+        // MCP marks `arguments` optional; default to {} so no-input tools
+        // (e.g. list_mail_rules) parse cleanly, matching the codebase-wide
+        // `parse(args ?? {})` convention.
+        const params = def.input.parse(args ?? {});
+        return def.handler(ctx, params);
+    }
+    filtered(options) {
+        return [...this.definitions.values()].filter((def) => this.matches(def, options));
+    }
+    matches(def, options) {
+        if (!def.backends.includes(options.backend)) {
+            return false;
+        }
+        if (options.readOnly === true && !isReadOnly(def)) {
+            return false;
+        }
+        const presets = options.presets;
+        if (presets != null && presets.length > 0 && def.presets.length > 0) {
+            return def.presets.some((p) => presets.includes(p));
+        }
+        return true;
+    }
+}
+/**
+ * A tool is read-only iff it explicitly advertises `readOnlyHint: true`. This is
+ * stricter than `!destructive` — a non-destructive write (e.g. create_draft,
+ * mark_email_read) still mutates state and must be excluded from `--read-only`.
+ */
+function isReadOnly(def) {
+    return def.annotations.readOnlyHint === true;
+}
+//# sourceMappingURL=registry.js.map

package/dist/registry/registry.js.map

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

package/dist/registry/types.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Copyright (c) 2026 JBC Tech Solutions, LLC
+ * Licensed under the MIT License. See LICENSE file in the project root.
+ */
+/**
+ * Tool registry types (v3 registry-driven architecture, U1).
+ *
+ * A tool definition is the single source of truth for what the four
+ * previously hand-maintained lists carried independently: the JSON-schema
+ * `TOOLS` array, per-module Zod schemas, the dispatch switch, and
+ * `GRAPH_ONLY_TOOL_NAMES`. Definitions register their static metadata
+ * eagerly (before any backend is initialized, so ListTools works without
+ * auth) and resolve their live handler dependencies lazily via ToolContext.
+ */
+import type { z } from 'zod';
+import type { ApprovalTokenManager } from '../approval/index.js';
+/** Which backend(s) expose a tool. */
+export type Backend = 'graph' | 'applescript';
+/** Preset groups a client can select with --preset to shrink the surface. */
+export type Preset = 'mail' | 'calendar' | 'contacts' | 'tasks' | 'notes' | 'teams' | 'planner' | 'files' | 'sharepoint' | 'excel' | 'people' | 'meetings';
+/**
+ * MCP tool annotations (spec 2025-03-26+). Clients use these to auto-approve
+ * safe reads and gate destructive calls.
+ */
+export interface ToolAnnotations {
+    readonly title?: string;
+    readonly readOnlyHint?: boolean;
+    readonly destructiveHint?: boolean;
+    readonly idempotentHint?: boolean;
+    readonly openWorldHint?: boolean;
+}
+/** The MCP text-content result shape every tool returns. */
+export interface ToolResult {
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+    isError?: boolean;
+}
+/**
+ * Bag of initialized Graph-backend tool instances, resolved after the backend
+ * is lazily initialized.
+ *
+ * This is an augmentation target: each domain module declares its own field
+ * via `declare module '../registry/types.js'`, so migrating a domain never
+ * edits this file — avoiding a 25-domain merge-conflict hotspot. Handlers read
+ * their instance through `requireGraphToolset(ctx, key)`.
+ */
+export interface GraphToolsets {
+}
+/**
+ * Bag of initialized AppleScript-backend tool instances. The AppleScript
+ * backend is frozen (v3), but dual-backend tools (mail, calendar, contacts,
+ * tasks, notes, mailbox organization) still register their AppleScript toolset
+ * here so a single registry handler can branch on `ctx.backend`. Like
+ * GraphToolsets, this is a per-file augmentation target — read instances via
+ * `requireAppleScriptToolset(ctx, key)`.
+ */
+export interface AppleScriptToolsets {
+}
+/**
+ * Runtime context passed to a tool handler. Built once per call after the
+ * backend is initialized; carries the live toolset instances so handlers no
+ * longer need the 23-positional-parameter dispatch signature.
+ */
+export interface ToolContext {
+    readonly backend: Backend;
+    readonly tokenManager: ApprovalTokenManager;
+    readonly graph: GraphToolsets | null;
+    readonly applescript: AppleScriptToolsets | null;
+}
+/**
+ * A single tool definition — static metadata plus a lazily-bound handler.
+ *
+ * @typeParam S - the Zod input schema; the handler receives its parsed output.
+ */
+export interface ToolDefinition<S extends z.ZodType = z.ZodType> {
+    /** Tool name exposed over MCP (snake_case). */
+    readonly name: string;
+    /** One-line description shown to the model. */
+    readonly description: string;
+    /** Zod input schema; the advertised JSON Schema is derived from it. */
+    readonly input: S;
+    /** MCP annotations surfaced in ListTools. */
+    readonly annotations: ToolAnnotations;
+    /**
+     * True when the tool participates in a destructive flow (delete/send/upload,
+     * including the prepare_/confirm_ halves). Drives --read-only filtering.
+     */
+    readonly destructive: boolean;
+    /** Presets that include this tool. Empty means "always exposed". */
+    readonly presets: readonly Preset[];
+    /** Backends that expose this tool. */
+    readonly backends: readonly Backend[];
+    /** Handler invoked with the runtime context and validated params. */
+    readonly handler: (ctx: ToolContext, params: z.infer<S>) => Promise<ToolResult> | ToolResult;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/registry/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/registry/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAEjE,sCAAsC;AACtC,MAAM,MAAM,OAAO,GAAG,OAAO,GAAG,aAAa,CAAC;AAE9C,6EAA6E;AAC7E,MAAM,MAAM,MAAM,GACd,MAAM,GACN,UAAU,GACV,UAAU,GACV,OAAO,GACP,OAAO,GACP,OAAO,GACP,SAAS,GACT,OAAO,GACP,YAAY,GACZ,OAAO,GACP,QAAQ,GACR,UAAU,CAAC;AAEf;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC;IAChC,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;IACnC,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,CAAC;IAClC,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;CAClC;AAED,4DAA4D;AAC5D,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/C,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;;;;;;GAQG;AAEH,MAAM,WAAW,aAAa;CAAG;AAEjC;;;;;;;GAOG;AAEH,MAAM,WAAW,mBAAmB;CAAG;AAEvC;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,YAAY,EAAE,oBAAoB,CAAC;IAC5C,QAAQ,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI,CAAC;IACrC,QAAQ,CAAC,WAAW,EAAE,mBAAmB,GAAG,IAAI,CAAC;CAClD;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc,CAAC,CAAC,SAAS,CAAC,CAAC,OAAO,GAAG,CAAC,CAAC,OAAO;IAC7D,+CAA+C;IAC/C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,+CAA+C;IAC/C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,uEAAuE;IACvE,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;IAClB,6CAA6C;IAC7C,QAAQ,CAAC,WAAW,EAAE,eAAe,CAAC;IACtC;;;OAGG;IACH,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,oEAAoE;IACpE,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,sCAAsC;IACtC,QAAQ,CAAC,QAAQ,EAAE,SAAS,OAAO,EAAE,CAAC;IACtC,qEAAqE;IACrE,QAAQ,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,WAAW,EAAE,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,UAAU,CAAC,GAAG,UAAU,CAAC;CAC9F"}

package/dist/registry/types.js

@@ -0,0 +1,6 @@
+/**
+ * Copyright (c) 2026 JBC Tech Solutions, LLC
+ * Licensed under the MIT License. See LICENSE file in the project root.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/registry/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/registry/types.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/dist/search/compiler.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Copyright (c) 2026 JBC Tech Solutions, LLC
+ * Licensed under the MIT License. See LICENSE file in the project root.
+ */
+/**
+ * Structured, typed email-search criteria (replaces the raw `query` KQL). Fields
+ * are `| undefined`-tolerant so a zod-parsed input object (which carries explicit
+ * `undefined` for absent optionals under exactOptionalPropertyTypes) passes
+ * directly; every field is guarded with `!= null` before use.
+ */
+export interface EmailSearchParams {
+    /** Sender address (exact). Property → `$filter`. */
+    from?: string | undefined;
+    /** Recipient address (exact). Property → `$filter`. */
+    to?: string | undefined;
+    /** Received on/after this ISO date/datetime. Property → `$filter`. */
+    received_after?: string | undefined;
+    /** Received on/before this ISO date/datetime. Property → `$filter`. */
+    received_before?: string | undefined;
+    /** Only messages with attachments. Property → `$filter`. */
+    has_attachments?: boolean | undefined;
+    /** Only unread messages. Property → `$filter`. */
+    is_unread?: boolean | undefined;
+    /** Importance level. Property → `$filter`. */
+    importance?: 'low' | 'normal' | 'high' | undefined;
+    /** Subject contains (free-text — Graph `$filter` has no `contains` here). */
+    subject_contains?: string | undefined;
+    /** Body contains (free-text). */
+    body_contains?: string | undefined;
+    /** Free-text across the message. */
+    text?: string | undefined;
+}
+/** The compiled query and which Graph mechanism executes it. */
+export type CompiledSearch = {
+    mechanism: 'filter';
+    filter: string;
+} | {
+    mechanism: 'search';
+    search: string;
+} | {
+    mechanism: 'searchQuery';
+    kql: string;
+};
+/**
+ * Compiles structured params into the correct Graph mechanism + query string.
+ * Throws {@link ValidationError} when no criterion is given or a date is malformed.
+ */
+export declare function compileEmailSearch(params: EmailSearchParams): CompiledSearch;
+//# sourceMappingURL=compiler.d.ts.map

package/dist/search/compiler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compiler.d.ts","sourceRoot":"","sources":["../../src/search/compiler.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAqBH;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,oDAAoD;IACpD,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,uDAAuD;IACvD,EAAE,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACxB,sEAAsE;IACtE,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,uEAAuE;IACvE,eAAe,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC,4DAA4D;IAC5D,eAAe,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACtC,kDAAkD;IAClD,SAAS,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAChC,8CAA8C;IAC9C,UAAU,CAAC,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,SAAS,CAAC;IACnD,6EAA6E;IAC7E,gBAAgB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,iCAAiC;IACjC,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,oCAAoC;IACpC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC3B;AAED,gEAAgE;AAChE,MAAM,MAAM,cAAc,GACtB;IAAE,SAAS,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACvC;IAAE,SAAS,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACvC;IAAE,SAAS,EAAE,aAAa,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC;AAI9C;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,iBAAiB,GAAG,cAAc,CAiB5E"}

package/dist/search/compiler.js

@@ -0,0 +1,168 @@
+/**
+ * Copyright (c) 2026 JBC Tech Solutions, LLC
+ * Licensed under the MIT License. See LICENSE file in the project root.
+ */
+/**
+ * Structured email-search compiler (U7 / D9). Replaces raw KQL — the #1 observed
+ * failure class — with typed params compiled server-side, so correct operator
+ * syntax, quoting, and date formatting are code, not model guesswork.
+ *
+ * Graph makes `$filter` and `$search` mutually exclusive on messages, so:
+ * - property-only criteria  → `$filter`
+ * - free-text-only criteria → quoted `$search`
+ * - mixed                   → server-built KQL for `POST /search/query`
+ *   (the only single-request path for both at once).
+ *
+ * Field → mechanism classification below is the documented default; per D9's
+ * execution note it is confirmed/refined by a live-mailbox spike before release
+ * (Graph's `$filter` has no `contains` on message subject/body, so those are
+ * treated as free-text here).
+ */
+import { ValidationError } from '../utils/errors.js';
+const ISO_DATE = /^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:\d{2})?)?$/;
+/**
+ * Compiles structured params into the correct Graph mechanism + query string.
+ * Throws {@link ValidationError} when no criterion is given or a date is malformed.
+ */
+export function compileEmailSearch(params) {
+    const filters = buildFilters(params);
+    const terms = buildSearchTerms(params);
+    if (filters.length === 0 && terms.length === 0) {
+        throw new ValidationError('Provide at least one search criterion (e.g. from, subject_contains, received_after, text).');
+    }
+    if (terms.length === 0) {
+        return { mechanism: 'filter', filter: filters.join(' and ') };
+    }
+    if (filters.length === 0) {
+        return { mechanism: 'search', search: quoteSearch(terms) };
+    }
+    return { mechanism: 'searchQuery', kql: buildKql(params) };
+}
+/**
+ * Property criteria → OData `$filter` clauses (order is stable for snapshots).
+ * Addressing fields (`from`/`to`) are deliberately NOT here: the D9 live spike
+ * showed Graph rejects a recipient `any()` lambda (`ErrorInvalidUrlQueryFilter`)
+ * and returns `InefficientFilter` when a sender/flag `$filter` is combined with
+ * `$orderby`. So `from`/`to` are handled as `from:`/`to:` in the $search/KQL
+ * layer instead, where both work reliably.
+ */
+function buildFilters(p) {
+    const out = [];
+    if (p.received_after != null) {
+        out.push(`receivedDateTime ge ${requireIsoDate(p.received_after, 'received_after')}`);
+    }
+    if (p.received_before != null) {
+        out.push(`receivedDateTime le ${requireIsoDate(p.received_before, 'received_before')}`);
+    }
+    if (p.has_attachments != null) {
+        out.push(`hasAttachments eq ${p.has_attachments ? 'true' : 'false'}`);
+    }
+    if (p.is_unread != null) {
+        out.push(`isRead eq ${p.is_unread ? 'false' : 'true'}`);
+    }
+    if (p.importance != null) {
+        out.push(`importance eq '${p.importance}'`);
+    }
+    return out;
+}
+/**
+ * `$search`/KQL terms. Includes the addressing fields (`from`/`to`) — Graph's
+ * `$filter` can't reliably express them (see buildFilters) but the `from:`/`to:`
+ * KQL operators work in `$search` and `/search/query` (D9 spike). Order is stable
+ * for snapshots.
+ */
+function buildSearchTerms(p) {
+    const out = [];
+    if (p.from != null && p.from.trim().length > 0) {
+        out.push(`from:${p.from.trim()}`);
+    }
+    if (p.to != null && p.to.trim().length > 0) {
+        out.push(`to:${p.to.trim()}`);
+    }
+    if (p.subject_contains != null && p.subject_contains.trim().length > 0) {
+        out.push(`subject:${p.subject_contains.trim()}`);
+    }
+    if (p.body_contains != null && p.body_contains.trim().length > 0) {
+        out.push(`body:${p.body_contains.trim()}`);
+    }
+    if (p.text != null && p.text.trim().length > 0) {
+        out.push(p.text.trim());
+    }
+    return out;
+}
+/**
+ * Builds the `$search` value: each term wrapped in a quoted phrase, AND-joined.
+ * Embedded double quotes are STRIPPED (not backslash-escaped): Graph's $search
+ * has no documented in-phrase escape, so a `"` in a value could otherwise close
+ * the phrase early and inject a boolean/property clause.
+ */
+function quoteSearch(terms) {
+    return terms.map((t) => kqlPhrase(t)).join(' AND ');
+}
+/**
+ * Builds a KQL string for `POST /search/query` combining property and free-text
+ * criteria (the only single-request path when both are present). EVERY free
+ * value — including from/to — is wrapped as a quoted phrase so a value with
+ * whitespace or KQL operators (e.g. `alice@x.com AND body:secret`) cannot inject
+ * extra clauses. Dates are day-granular here (KQL range syntax); the $filter
+ * path preserves time-of-day, so mixed-mode queries are intentionally
+ * day-granular on dates (documented on the tool in U7b).
+ */
+function buildKql(p) {
+    const clauses = [];
+    if (p.from != null && p.from.length > 0)
+        clauses.push(`from:${kqlPhrase(p.from)}`);
+    if (p.to != null && p.to.length > 0)
+        clauses.push(`to:${kqlPhrase(p.to)}`);
+    if (p.received_after != null)
+        clauses.push(`received>=${toKqlDate(p.received_after, 'received_after')}`);
+    if (p.received_before != null)
+        clauses.push(`received<=${toKqlDate(p.received_before, 'received_before')}`);
+    if (p.has_attachments != null)
+        clauses.push(`hasattachment:${p.has_attachments ? 'true' : 'false'}`);
+    if (p.is_unread === true)
+        clauses.push('isread:false');
+    else if (p.is_unread === false)
+        clauses.push('isread:true');
+    if (p.importance != null)
+        clauses.push(`importance:${p.importance}`);
+    if (p.subject_contains != null && p.subject_contains.trim().length > 0) {
+        clauses.push(`subject:${kqlPhrase(p.subject_contains.trim())}`);
+    }
+    if (p.body_contains != null && p.body_contains.trim().length > 0) {
+        clauses.push(`body:${kqlPhrase(p.body_contains.trim())}`);
+    }
+    if (p.text != null && p.text.trim().length > 0) {
+        clauses.push(kqlPhrase(p.text.trim()));
+    }
+    return clauses.join(' AND ');
+}
+function requireIsoDate(value, field) {
+    if (!ISO_DATE.test(value) || Number.isNaN(Date.parse(value))) {
+        throw invalidDate(field, value);
+    }
+    // Reject rollover-invalid calendar dates: Date.parse('2026-02-30') is NOT NaN
+    // (it rolls to Mar 2), so re-serialize the date part and require an exact
+    // match to catch day/month overflow.
+    const datePart = value.slice(0, 10);
+    if (new Date(`${datePart}T00:00:00Z`).toISOString().slice(0, 10) !== datePart) {
+        throw invalidDate(field, value);
+    }
+    // A bare date becomes midnight UTC so `ge`/`le` compare against a full instant.
+    return value.includes('T') ? value : `${value}T00:00:00Z`;
+}
+function invalidDate(field, value) {
+    return new ValidationError(`${field} must be a valid ISO date (YYYY-MM-DD) or datetime; got "${value}".`);
+}
+function toKqlDate(value, field) {
+    requireIsoDate(value, field);
+    return value.slice(0, 10);
+}
+/** Wraps a value as a quoted KQL phrase, stripping embedded double quotes. */
+function kqlPhrase(value) {
+    return `"${stripQuotes(value)}"`;
+}
+function stripQuotes(value) {
+    return value.replace(/"/g, '');
+}
+//# sourceMappingURL=compiler.js.map