@jbctechsolutions/mcp-office365 2.5.1 → 4.0.0

package/dist/ids/next-action.js

@@ -0,0 +1,58 @@
+/**
+ * Copyright (c) 2026 JBC Tech Solutions, LLC
+ * Licensed under the MIT License. See LICENSE file in the project root.
+ */
+/**
+ * Next-action hints (U6).
+ *
+ * List/search/create tools that mint durable ids can attach a single short
+ * `next` string to their JSON result, suggesting the natural follow-up tool(s)
+ * and naming the token prefix the caller will feed forward — e.g. list_plans →
+ * "Use get_plan or list_buckets with a returned `pl_` id." The wording and the
+ * prefix are derived centrally (from the token tables) so they stay consistent
+ * as the tool surface evolves.
+ *
+ * Intentionally minimal: one top-level `next` key per result (never per row),
+ * added only where a follow-up is genuinely useful. Get and write results skip it.
+ */
+import { prefixForEntity } from './token.js';
+/**
+ * Follow-up tool names suggested for a returned id of each entity. Exported so a
+ * contract test can cross-check every named tool against the registry.
+ */
+export const FOLLOWUP_TOOLS = {
+    task: 'get_task, update_task, or complete_task',
+    taskList: 'create_task',
+    plan: 'get_plan or list_buckets',
+    plannerBucket: 'list_planner_tasks or create_planner_task',
+    plannerTask: 'get_planner_task or update_planner_task',
+    message: 'get_email, list_attachments, or reply_as_draft',
+    folder: 'list_emails or search_emails',
+    contact: 'get_contact or update_contact',
+    event: 'get_event or respond_to_event',
+    driveItem: 'get_drive_item or download_file',
+    site: 'list_document_libraries',
+    documentLibrary: 'list_library_items',
+    libraryDriveItem: 'download_library_file',
+    sharePointList: 'list_list_items',
+    sharePointListItem: 'get_list_item or update_list_item',
+    team: 'list_channels',
+    channel: 'list_channel_messages',
+    chat: 'list_chat_messages',
+    onlineMeeting: 'get_online_meeting, list_meeting_recordings, or list_meeting_transcripts',
+    noteNotebook: 'list_note_sections',
+    noteSection: 'list_note_pages',
+    notePage: 'get_note_page',
+};
+/**
+ * The next-action hint sentence for an entity, or null when none is defined.
+ * The `_` suffix on the prefix mirrors the token shape callers see.
+ */
+export function nextActionFor(entityType) {
+    const tools = FOLLOWUP_TOOLS[entityType];
+    if (tools == null) {
+        return null;
+    }
+    return `Use ${tools} with a returned \`${prefixForEntity(entityType)}_\` id.`;
+}
+//# sourceMappingURL=next-action.js.map

package/dist/ids/next-action.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"next-action.js","sourceRoot":"","sources":["../../src/ids/next-action.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,eAAe,EAAmB,MAAM,YAAY,CAAC;AAE9D;;;GAGG;AACH,MAAM,CAAC,MAAM,cAAc,GAAwC;IACjE,IAAI,EAAE,yCAAyC;IAC/C,QAAQ,EAAE,aAAa;IACvB,IAAI,EAAE,0BAA0B;IAChC,aAAa,EAAE,2CAA2C;IAC1D,WAAW,EAAE,yCAAyC;IACtD,OAAO,EAAE,gDAAgD;IACzD,MAAM,EAAE,8BAA8B;IACtC,OAAO,EAAE,+BAA+B;IACxC,KAAK,EAAE,+BAA+B;IACtC,SAAS,EAAE,iCAAiC;IAC5C,IAAI,EAAE,yBAAyB;IAC/B,eAAe,EAAE,oBAAoB;IACrC,gBAAgB,EAAE,uBAAuB;IACzC,cAAc,EAAE,iBAAiB;IACjC,kBAAkB,EAAE,mCAAmC;IACvD,IAAI,EAAE,eAAe;IACrB,OAAO,EAAE,uBAAuB;IAChC,IAAI,EAAE,oBAAoB;IAC1B,aAAa,EAAE,0EAA0E;IACzF,YAAY,EAAE,oBAAoB;IAClC,WAAW,EAAE,iBAAiB;IAC9B,QAAQ,EAAE,eAAe;CAC1B,CAAC;AAEF;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,UAAsB;IAClD,MAAM,KAAK,GAAG,cAAc,CAAC,UAAU,CAAC,CAAC;IACzC,IAAI,KAAK,IAAI,IAAI,EAAE,CAAC;QAClB,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,OAAO,KAAK,sBAAsB,eAAe,CAAC,UAAU,CAAC,SAAS,CAAC;AAChF,CAAC"}

package/dist/ids/resolver.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Copyright (c) 2026 JBC Tech Solutions, LLC
+ * Licensed under the MIT License. See LICENSE file in the project root.
+ */
+/**
+ * Universal durable-ID resolver (U5 / D1, D2, D4, D7). Turns any ID a tool
+ * receives — a self-encoding token, an alias-backed token, a raw Graph ID, or a
+ * legacy numeric ID — into a live Graph ID, or a typed error.
+ *
+ * - self-encoding token → decode, zero storage (cold-state durable).
+ * - alias-backed token   → alias table lookup (account-scoped). A cold/foreign
+ *   miss is distinguished: ID_FOREIGN_ACCOUNT vs ID_UNKNOWN.
+ * - numeric (v2 hash)    → NUMERIC_ID_UNSUPPORTED on Graph (lossy, D4).
+ * - raw non-token string → passed through as an opaque Graph ID (a user may
+ *   paste a real Graph ID; Graph IDs are opaque, so rejecting them would be
+ *   hostile). Mutation of state lives in the alias table, not here.
+ */
+import type { StateStore } from '../state/store.js';
+import { type EntityType } from './token.js';
+/** A resolved Graph ID plus whether it came from a mutable (drift-prone) alias. */
+export interface ResolvedId {
+    graphId: string;
+    /** True for `$search`-minted mutable alias rows that may need re-resolution. */
+    mutable: boolean;
+}
+/**
+ * Resolves an ID parameter to a Graph ID for the given signed-in account.
+ * Throws a typed {@link import('../utils/errors.js').OutlookMcpError} on failure.
+ */
+export declare function resolveId(id: string, accountId: string, store: StateStore | undefined, expectedEntityType?: EntityType): ResolvedId;
+//# sourceMappingURL=resolver.d.ts.map

package/dist/ids/resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolver.d.ts","sourceRoot":"","sources":["../../src/ids/resolver.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAOpD,OAAO,EAAc,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAEzD,mFAAmF;AACnF,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,gFAAgF;IAChF,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;;GAGG;AACH,wBAAgB,SAAS,CACvB,EAAE,EAAE,MAAM,EACV,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,UAAU,GAAG,SAAS,EAC7B,kBAAkB,CAAC,EAAE,UAAU,GAC9B,UAAU,CA8CZ"}

package/dist/ids/resolver.js

@@ -0,0 +1,52 @@
+/**
+ * Copyright (c) 2026 JBC Tech Solutions, LLC
+ * Licensed under the MIT License. See LICENSE file in the project root.
+ */
+import { IdForeignAccountError, IdUnknownError, IdEntityMismatchError, NumericIdUnsupportedError, } from '../utils/errors.js';
+import { parseToken } from './token.js';
+/**
+ * Resolves an ID parameter to a Graph ID for the given signed-in account.
+ * Throws a typed {@link import('../utils/errors.js').OutlookMcpError} on failure.
+ */
+export function resolveId(id, accountId, store, expectedEntityType) {
+    // A bare all-digits string is a legacy v2 hash id (Graph ids and durable
+    // tokens are never purely numeric), so surface the same actionable
+    // NUMERIC_ID_UNSUPPORTED rather than passing it through to Graph as an opaque
+    // id that only 404s. Covers callers whose schema is string-only (U6).
+    if (/^\d+$/.test(id)) {
+        throw new NumericIdUnsupportedError(id);
+    }
+    const parsed = parseToken(id);
+    if (parsed === null) {
+        // Not a known token — treat as an opaque Graph ID the caller supplied.
+        return { graphId: id, mutable: false };
+    }
+    // A durable token for the wrong entity kind (e.g. a folder token passed as a
+    // contact id) must not resolve — otherwise it decodes to a foreign Graph id
+    // and the safety rests only on Graph 404-ing the mismatched collection.
+    if (expectedEntityType != null && parsed.entityType !== expectedEntityType) {
+        throw new IdEntityMismatchError(id, expectedEntityType, parsed.entityType);
+    }
+    if (parsed.kind === 'self') {
+        // graphId is always present for a self-encoding parse. Self-encoding tokens
+        // decode with zero storage, so no store is required to resolve them.
+        return { graphId: parsed.graphId, mutable: false };
+    }
+    // Alias-backed tokens need the store. Without one they can't be resolved.
+    if (store == null) {
+        throw new IdUnknownError(id);
+    }
+    // Alias-backed: resolve against the store, scoped to the account.
+    const row = store.getAlias(id, accountId);
+    if (row !== null) {
+        return { graphId: row.graphId, mutable: row.mutable };
+    }
+    // Miss — distinguish a foreign-account token from a genuinely unknown one so
+    // the agent gets an actionable message (D7).
+    const owner = store.getAliasAccount(id);
+    if (owner !== null && owner !== accountId) {
+        throw new IdForeignAccountError(id);
+    }
+    throw new IdUnknownError(id);
+}
+//# sourceMappingURL=resolver.js.map

package/dist/ids/resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolver.js","sourceRoot":"","sources":["../../src/ids/resolver.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAiBH,OAAO,EACL,qBAAqB,EACrB,cAAc,EACd,qBAAqB,EACrB,yBAAyB,GAC1B,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,UAAU,EAAmB,MAAM,YAAY,CAAC;AASzD;;;GAGG;AACH,MAAM,UAAU,SAAS,CACvB,EAAU,EACV,SAAiB,EACjB,KAA6B,EAC7B,kBAA+B;IAE/B,yEAAyE;IACzE,mEAAmE;IACnE,8EAA8E;IAC9E,sEAAsE;IACtE,IAAI,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC;QACrB,MAAM,IAAI,yBAAyB,CAAC,EAAE,CAAC,CAAC;IAC1C,CAAC;IAED,MAAM,MAAM,GAAG,UAAU,CAAC,EAAE,CAAC,CAAC;IAC9B,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;QACpB,uEAAuE;QACvE,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IACzC,CAAC;IAED,6EAA6E;IAC7E,4EAA4E;IAC5E,wEAAwE;IACxE,IAAI,kBAAkB,IAAI,IAAI,IAAI,MAAM,CAAC,UAAU,KAAK,kBAAkB,EAAE,CAAC;QAC3E,MAAM,IAAI,qBAAqB,CAAC,EAAE,EAAE,kBAAkB,EAAE,MAAM,CAAC,UAAU,CAAC,CAAC;IAC7E,CAAC;IAED,IAAI,MAAM,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;QAC3B,4EAA4E;QAC5E,qEAAqE;QACrE,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,OAAiB,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IAC/D,CAAC;IAED,0EAA0E;IAC1E,IAAI,KAAK,IAAI,IAAI,EAAE,CAAC;QAClB,MAAM,IAAI,cAAc,CAAC,EAAE,CAAC,CAAC;IAC/B,CAAC;IAED,kEAAkE;IAClE,MAAM,GAAG,GAAG,KAAK,CAAC,QAAQ,CAAC,EAAE,EAAE,SAAS,CAAC,CAAC;IAC1C,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;QACjB,OAAO,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE,CAAC;IACxD,CAAC;IAED,6EAA6E;IAC7E,6CAA6C;IAC7C,MAAM,KAAK,GAAG,KAAK,CAAC,eAAe,CAAC,EAAE,CAAC,CAAC;IACxC,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QAC1C,MAAM,IAAI,qBAAqB,CAAC,EAAE,CAAC,CAAC;IACtC,CAAC;IACD,MAAM,IAAI,cAAc,CAAC,EAAE,CAAC,CAAC;AAC/B,CAAC"}

package/dist/ids/schema.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Copyright (c) 2026 JBC Tech Solutions, LLC
+ * Licensed under the MIT License. See LICENSE file in the project root.
+ */
+/**
+ * Canonical per-entity Zod id schemas (U6).
+ *
+ * Every tool that accepts a durable-ID param should reference the shared schema
+ * for its entity (`Id.task`, `Id.plan`, …) instead of an ad-hoc
+ * `z.string().min(1).describe(...)`. This gives one place to define:
+ *
+ * - **normalization** — `.trim()` so a copy/pasted id with stray whitespace
+ *   still resolves; `.min(1)` so an empty/whitespace-only id fails fast.
+ * - **a consistent, prefix-named description** — derived from the token tables
+ *   (`prefixForEntity`), so the param doc always names the token shape (e.g.
+ *   "a `td_` token") and where to get it.
+ *
+ * Deliberately NOT here: classification of the id (numeric-vs-token, wrong
+ * entity, alias store lookup). That stays in {@link resolveId} at execution
+ * time, which is the single source of truth and emits the specific typed codes
+ * (`NUMERIC_ID_UNSUPPORTED`, `ID_ENTITY_MISMATCH`, `ID_UNKNOWN`) agents key on.
+ * The schema is string-only (a JSON-number legacy id is a type error); a numeric
+ * *string* still passes and reaches `resolveId` for the specific message.
+ */
+import { z } from 'zod';
+import { type EntityType } from './token.js';
+/** Human label + the tools that mint an entity's id, for the description. */
+interface EntityMeta {
+    readonly label: string;
+    readonly from: string;
+}
+/**
+ * Per-entity description metadata. Only entities actually exposed as tool id
+ * params need an entry; others fall back to a generic description. Exported so a
+ * contract test can cross-check every `from` tool name against the registry,
+ * catching drift when a tool is renamed.
+ */
+export declare const ENTITY_META: Partial<Record<EntityType, EntityMeta>>;
+/** Builds the canonical, prefix-named description for an entity id. */
+export declare function describeId(entityType: EntityType): string;
+/**
+ * The canonical required id schema for an entity: a trimmed, non-empty string
+ * with a prefix-named description. Classification stays in `resolveId`.
+ */
+export declare function idSchema(entityType: EntityType): z.ZodString;
+/** The canonical optional id schema for an entity. */
+export declare function optionalIdSchema(entityType: EntityType): z.ZodOptional<z.ZodString>;
+/**
+ * Canonical required id schemas keyed by entity. Tools reference these directly
+ * (`Id.task`, `Id.plan`, …). A per-call `.describe()` may override the default
+ * description where a param needs extra context.
+ */
+export declare const Id: {
+    readonly message: z.ZodString;
+    readonly event: z.ZodString;
+    readonly contact: z.ZodString;
+    readonly folder: z.ZodString;
+    readonly driveItem: z.ZodString;
+    readonly task: z.ZodString;
+    readonly taskList: z.ZodString;
+    readonly plan: z.ZodString;
+    readonly plannerBucket: z.ZodString;
+    readonly plannerTask: z.ZodString;
+    readonly attachment: z.ZodString;
+    readonly checklistItem: z.ZodString;
+    readonly linkedResource: z.ZodString;
+    readonly taskAttachment: z.ZodString;
+    readonly chat: z.ZodString;
+    readonly team: z.ZodString;
+    readonly channel: z.ZodString;
+    readonly chatMessage: z.ZodString;
+    readonly channelMessage: z.ZodString;
+    readonly contactFolder: z.ZodString;
+    readonly mailRule: z.ZodString;
+    readonly category: z.ZodString;
+    readonly focusedOverride: z.ZodString;
+    readonly calendarPermission: z.ZodString;
+    readonly onlineMeeting: z.ZodString;
+    readonly recording: z.ZodString;
+    readonly transcript: z.ZodString;
+    readonly site: z.ZodString;
+    readonly documentLibrary: z.ZodString;
+    readonly libraryDriveItem: z.ZodString;
+    readonly sharePointList: z.ZodString;
+    readonly sharePointListItem: z.ZodString;
+    readonly noteNotebook: z.ZodString;
+    readonly noteSection: z.ZodString;
+    readonly notePage: z.ZodString;
+};
+export {};
+//# sourceMappingURL=schema.d.ts.map

package/dist/ids/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/ids/schema.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAmB,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAE9D,6EAA6E;AAC7E,UAAU,UAAU;IAClB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED;;;;;GAKG;AACH,eAAO,MAAM,WAAW,EAAE,OAAO,CAAC,MAAM,CAAC,UAAU,EAAE,UAAU,CAAC,CAoC/D,CAAC;AAEF,uEAAuE;AACvE,wBAAgB,UAAU,CAAC,UAAU,EAAE,UAAU,GAAG,MAAM,CAMzD;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,UAAU,EAAE,UAAU,GAAG,CAAC,CAAC,SAAS,CAE5D;AAED,sDAAsD;AACtD,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,UAAU,GAAG,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,SAAS,CAAC,CAEnF;AAED;;;;GAIG;AACH,eAAO,MAAM,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoCiC,CAAC"}

package/dist/ids/schema.js

@@ -0,0 +1,131 @@
+/**
+ * Copyright (c) 2026 JBC Tech Solutions, LLC
+ * Licensed under the MIT License. See LICENSE file in the project root.
+ */
+/**
+ * Canonical per-entity Zod id schemas (U6).
+ *
+ * Every tool that accepts a durable-ID param should reference the shared schema
+ * for its entity (`Id.task`, `Id.plan`, …) instead of an ad-hoc
+ * `z.string().min(1).describe(...)`. This gives one place to define:
+ *
+ * - **normalization** — `.trim()` so a copy/pasted id with stray whitespace
+ *   still resolves; `.min(1)` so an empty/whitespace-only id fails fast.
+ * - **a consistent, prefix-named description** — derived from the token tables
+ *   (`prefixForEntity`), so the param doc always names the token shape (e.g.
+ *   "a `td_` token") and where to get it.
+ *
+ * Deliberately NOT here: classification of the id (numeric-vs-token, wrong
+ * entity, alias store lookup). That stays in {@link resolveId} at execution
+ * time, which is the single source of truth and emits the specific typed codes
+ * (`NUMERIC_ID_UNSUPPORTED`, `ID_ENTITY_MISMATCH`, `ID_UNKNOWN`) agents key on.
+ * The schema is string-only (a JSON-number legacy id is a type error); a numeric
+ * *string* still passes and reaches `resolveId` for the specific message.
+ */
+import { z } from 'zod';
+import { prefixForEntity } from './token.js';
+/**
+ * Per-entity description metadata. Only entities actually exposed as tool id
+ * params need an entry; others fall back to a generic description. Exported so a
+ * contract test can cross-check every `from` tool name against the registry,
+ * catching drift when a tool is renamed.
+ */
+export const ENTITY_META = {
+    message: { label: 'email message', from: 'list_emails / search_emails' },
+    event: { label: 'calendar event', from: 'list_events / search_events' },
+    contact: { label: 'contact', from: 'list_contacts / search_contacts' },
+    folder: { label: 'mail folder', from: 'list_folders' },
+    driveItem: { label: 'OneDrive item', from: 'list_drive_items / search_drive_items' },
+    task: { label: 'To Do task', from: 'list_tasks / search_tasks' },
+    taskList: { label: 'To Do task list', from: 'list_task_lists' },
+    plan: { label: 'Planner plan', from: 'list_plans' },
+    plannerBucket: { label: 'Planner bucket', from: 'list_buckets' },
+    plannerTask: { label: 'Planner task', from: 'list_planner_tasks' },
+    attachment: { label: 'email attachment', from: 'list_attachments' },
+    checklistItem: { label: 'task checklist item', from: 'list_checklist_items' },
+    linkedResource: { label: 'task linked resource', from: 'list_linked_resources' },
+    taskAttachment: { label: 'task attachment', from: 'list_task_attachments' },
+    chat: { label: 'Teams chat', from: 'list_chats' },
+    team: { label: 'team', from: 'list_teams' },
+    channel: { label: 'Teams channel', from: 'list_channels' },
+    chatMessage: { label: 'chat message', from: 'list_chat_messages' },
+    channelMessage: { label: 'channel message', from: 'list_channel_messages' },
+    contactFolder: { label: 'contact folder', from: 'list_contact_folders' },
+    mailRule: { label: 'inbox rule', from: 'list_mail_rules' },
+    category: { label: 'master category', from: 'list_categories' },
+    focusedOverride: { label: 'focused-inbox override', from: 'list_focused_overrides' },
+    calendarPermission: { label: 'calendar permission', from: 'list_calendar_permissions' },
+    onlineMeeting: { label: 'online meeting', from: 'list_online_meetings' },
+    recording: { label: 'meeting recording', from: 'list_meeting_recordings' },
+    transcript: { label: 'meeting transcript', from: 'list_meeting_transcripts' },
+    site: { label: 'SharePoint site', from: 'list_sites / search_sites' },
+    documentLibrary: { label: 'document library', from: 'list_document_libraries' },
+    libraryDriveItem: { label: 'library item', from: 'list_library_items' },
+    sharePointList: { label: 'SharePoint list', from: 'list_lists' },
+    sharePointListItem: { label: 'SharePoint list item', from: 'list_list_items' },
+    noteNotebook: { label: 'OneNote notebook', from: 'list_notebooks' },
+    noteSection: { label: 'OneNote section', from: 'list_note_sections' },
+    notePage: { label: 'OneNote page', from: 'list_note_pages / search_note_pages' },
+};
+/** Builds the canonical, prefix-named description for an entity id. */
+export function describeId(entityType) {
+    const prefix = prefixForEntity(entityType);
+    const meta = ENTITY_META[entityType];
+    const label = meta?.label ?? entityType;
+    const source = meta != null ? ` from ${meta.from}` : '';
+    return `Durable ${label} ID — a \`${prefix}_\` token${source}. A raw Graph id is also accepted.`;
+}
+/**
+ * The canonical required id schema for an entity: a trimmed, non-empty string
+ * with a prefix-named description. Classification stays in `resolveId`.
+ */
+export function idSchema(entityType) {
+    return z.string().trim().min(1).describe(describeId(entityType));
+}
+/** The canonical optional id schema for an entity. */
+export function optionalIdSchema(entityType) {
+    return idSchema(entityType).optional();
+}
+/**
+ * Canonical required id schemas keyed by entity. Tools reference these directly
+ * (`Id.task`, `Id.plan`, …). A per-call `.describe()` may override the default
+ * description where a param needs extra context.
+ */
+export const Id = {
+    message: idSchema('message'),
+    event: idSchema('event'),
+    contact: idSchema('contact'),
+    folder: idSchema('folder'),
+    driveItem: idSchema('driveItem'),
+    task: idSchema('task'),
+    taskList: idSchema('taskList'),
+    plan: idSchema('plan'),
+    plannerBucket: idSchema('plannerBucket'),
+    plannerTask: idSchema('plannerTask'),
+    attachment: idSchema('attachment'),
+    checklistItem: idSchema('checklistItem'),
+    linkedResource: idSchema('linkedResource'),
+    taskAttachment: idSchema('taskAttachment'),
+    chat: idSchema('chat'),
+    team: idSchema('team'),
+    channel: idSchema('channel'),
+    chatMessage: idSchema('chatMessage'),
+    channelMessage: idSchema('channelMessage'),
+    contactFolder: idSchema('contactFolder'),
+    mailRule: idSchema('mailRule'),
+    category: idSchema('category'),
+    focusedOverride: idSchema('focusedOverride'),
+    calendarPermission: idSchema('calendarPermission'),
+    onlineMeeting: idSchema('onlineMeeting'),
+    recording: idSchema('recording'),
+    transcript: idSchema('transcript'),
+    site: idSchema('site'),
+    documentLibrary: idSchema('documentLibrary'),
+    libraryDriveItem: idSchema('libraryDriveItem'),
+    sharePointList: idSchema('sharePointList'),
+    sharePointListItem: idSchema('sharePointListItem'),
+    noteNotebook: idSchema('noteNotebook'),
+    noteSection: idSchema('noteSection'),
+    notePage: idSchema('notePage'),
+};
+//# sourceMappingURL=schema.js.map

package/dist/ids/schema.js.map

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

package/dist/ids/token.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.
+ */
+/** Entity kinds addressable by a durable-ID token. */
+export type EntityType = 'message' | 'event' | 'contact' | 'folder' | 'driveItem' | 'task' | 'taskList' | 'plan' | 'plannerBucket' | 'plannerTask' | 'chat' | 'team' | 'attachment' | 'channel' | 'chatMessage' | 'channelMessage' | 'checklistItem' | 'linkedResource' | 'taskAttachment' | 'noteNotebook' | 'noteSection' | 'notePage' | 'mailRule' | 'contactFolder' | 'category' | 'focusedOverride' | 'calendarPermission' | 'onlineMeeting' | 'recording' | 'transcript' | 'site' | 'documentLibrary' | 'libraryDriveItem' | 'sharePointList' | 'sharePointListItem';
+/** How a token encodes its target. */
+export type TokenKind = 'self' | 'alias';
+/**
+ * Prefix → entity maps are NULL-PROTOTYPE so a caller-supplied prefix like
+ * `constructor` or `toString` (from an arbitrary ID string) can never match an
+ * inherited `Object.prototype` member and get misclassified as a known token —
+ * `parseToken` must return null for those and let the resolver pass them through
+ * as opaque Graph IDs.
+ */
+/** Self-encoding prefixes → entity type (the token carries the Graph ID). */
+export declare const SELF_ENCODING_PREFIXES: Readonly<Record<string, EntityType>>;
+/** Alias-backed prefixes → entity type (the token is a digest; needs the store). */
+export declare const ALIAS_PREFIXES: Readonly<Record<string, EntityType>>;
+/** A parsed durable-ID token. */
+export interface ParsedToken {
+    prefix: string;
+    kind: TokenKind;
+    entityType: EntityType;
+    /** For self-encoding tokens: the decoded Graph ID. Absent for alias tokens. */
+    graphId?: string;
+}
+/** True when a prefix is a known self-encoding or alias prefix. */
+export declare function isKnownPrefix(prefix: string): boolean;
+/**
+ * The 2-char token prefix for an entity type (e.g. `task` → `td`). Lets callers
+ * (canonical id schemas, next-action hints) name the token shape without
+ * duplicating the prefix tables. Throws for an entity with no allocated prefix.
+ */
+export declare function prefixForEntity(entityType: EntityType): string;
+/**
+ * Mints a self-encoding token carrying the immutable Graph ID (D1). Determin­istic.
+ */
+export declare function mintSelfEncoded(entityType: EntityType, graphId: string): string;
+/**
+ * Mints a short, deterministic alias-backed token from an entity's canonical
+ * key (D1). The caller stores the token → key mapping in the alias table.
+ */
+export declare function mintComposite(entityType: EntityType, canonicalKey: string): string;
+/**
+ * Builds a canonical key for a composite entity from its identifying tuple.
+ * Keys are sorted so field order never changes the digest. Keys and values are
+ * percent-encoded so a value containing the `&`/`=` delimiters (Graph IDs are
+ * base64-ish and can) cannot forge a boundary and make two distinct tuples
+ * produce the same key — which would collide their tokens without a hash
+ * collision.
+ */
+export declare function canonicalKey(entityType: EntityType, parts: Readonly<Record<string, string>>): string;
+/**
+ * Parses a token into its prefix/kind/entity (and decoded Graph ID for
+ * self-encoding tokens). Returns null when the value is not a well-formed known
+ * token — the caller decides whether to treat that as a raw Graph ID or reject.
+ */
+export declare function parseToken(token: string): ParsedToken | null;
+/** True when a string looks like a durable-ID token (known prefix + payload). */
+export declare function isToken(value: string): boolean;
+//# sourceMappingURL=token.d.ts.map

package/dist/ids/token.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token.d.ts","sourceRoot":"","sources":["../../src/ids/token.ts"],"names":[],"mappings":"AAAA;;;GAGG;AA2BH,sDAAsD;AACtD,MAAM,MAAM,UAAU,GAClB,SAAS,GACT,OAAO,GACP,SAAS,GACT,QAAQ,GACR,WAAW,GACX,MAAM,GACN,UAAU,GACV,MAAM,GACN,eAAe,GACf,aAAa,GACb,MAAM,GACN,MAAM,GACN,YAAY,GACZ,SAAS,GACT,aAAa,GACb,gBAAgB,GAChB,eAAe,GACf,gBAAgB,GAChB,gBAAgB,GAChB,cAAc,GACd,aAAa,GACb,UAAU,GACV,UAAU,GACV,eAAe,GACf,UAAU,GACV,iBAAiB,GACjB,oBAAoB,GACpB,eAAe,GACf,WAAW,GACX,YAAY,GACZ,MAAM,GACN,iBAAiB,GACjB,kBAAkB,GAClB,gBAAgB,GAChB,oBAAoB,CAAC;AAEzB,sCAAsC;AACtC,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,OAAO,CAAC;AAEzC;;;;;;GAMG;AAEH,6EAA6E;AAC7E,eAAO,MAAM,sBAAsB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAYvE,CAAC;AAEF,oFAAoF;AACpF,eAAO,MAAM,cAAc,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CA+B/D,CAAC;AAoBF,iCAAiC;AACjC,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,SAAS,CAAC;IAChB,UAAU,EAAE,UAAU,CAAC;IACvB,+EAA+E;IAC/E,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,mEAAmE;AACnE,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAErD;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,UAAU,EAAE,UAAU,GAAG,MAAM,CAM9D;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,UAAU,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAW/E;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,UAAU,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAMlF;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,UAAU,EAAE,UAAU,EAAE,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,MAAM,CAMpG;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CA0B5D;AAED,iFAAiF;AACjF,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAE9C"}