@littlebearapps/outlook-assistant 3.12.0 → 3.12.1

package/rules/index.js

@@ -180,7 +180,7 @@ const rulesTools = [
   {
     name: 'manage-rules',
     description:
-      'Server-side inbox rule CRUD (destructive: covers `delete`; supports `dryRun` on create/update for preview). Rules run on the Exchange server regardless of which client is open. action=`list` (default) returns rules with id/name/sequence — pass `includeDetails: true` to expand conditions/actions/exceptions. action=`create` builds a new rule from condition params (12 supported: fromAddresses, containsSubject, bodyContains, hasAttachments, importance, sentTo, sensitivity, etc.), action params (9 supported: moveToFolder, forwardTo, redirectTo, assignCategories, markAsRead, delete, etc.), and optional `except*` exceptions. action=`update` patches the named fields by `ruleId`. action=`reorder` changes execution priority via `sequence` (lower = earlier). action=`delete` removes a rule. Recipient allowlist applies to forwardTo/redirectTo. `permanentDelete` action is intentionally omitted (too dangerous for AI use — use the Outlook UI). Subject to session rate limits (`OUTLOOK_MAX_MANAGE_RULES_PER_SESSION`).',
+      'Server-side inbox rule CRUD (destructive: covers `delete`; supports `dryRun` on create/update for preview). Rules run on the Exchange server regardless of which client is open. action=`list` (default) returns rules with id/name/sequence — pass `includeDetails: true` to expand conditions/actions/exceptions. action=`create` builds a new rule from condition params (12 supported: fromAddresses, containsSubject, bodyContains, hasAttachments, importance, sentTo, sensitivity, etc.), action params (9 supported: moveToFolder/copyToFolder — folder name, nested path like `Triage/Delete`, or ID — forwardTo, redirectTo, assignCategories, markAsRead, delete, etc.), and optional `except*` exceptions. action=`update` patches the named fields by `ruleId`. action=`reorder` changes execution priority via `sequence` (lower = earlier). action=`delete` removes a rule. Recipient allowlist applies to forwardTo/redirectTo. `permanentDelete` action is intentionally omitted (too dangerous for AI use — use the Outlook UI). Subject to session rate limits (`OUTLOOK_MAX_MANAGE_RULES_PER_SESSION`).',
     annotations: {
       title: 'Inbox Rules',
       readOnlyHint: false,
@@ -304,12 +304,12 @@ const rulesTools = [
         moveToFolder: {
           type: 'string',
           description:
-            'Folder name to move matching emails to (action=create/update)',
+            'Folder to move matching emails to: a name, a nested path like `Triage/Delete`, a well-known name (e.g. `archive`), or a folder ID (action=create/update)',
         },
         copyToFolder: {
           type: 'string',
           description:
-            'Folder name to copy matching emails to (action=create/update)',
+            'Folder to copy matching emails to: a name, a nested path like `Projects/Backup`, a well-known name, or a folder ID (action=create/update)',
         },
         markAsRead: {
           type: 'boolean',

package/rules/rule-builder.js

@@ -2,7 +2,7 @@
  * Shared rule builder utilities for creating and updating mail rules.
  * Converts flat MCP tool parameters into Microsoft Graph API rule objects.
  */
-const { getFolderIdByName } = require('../email/folder-utils');
+const { resolveFolder, looksLikeFolderId } = require('../folder/resolve');
 const { checkRecipientAllowlist } = require('../utils/safety');
 
 const VALID_IMPORTANCE = ['low', 'normal', 'high'];
@@ -104,6 +104,49 @@ function buildConditions(args) {
   return { conditions, warnings };
 }
 
+/**
+ * Resolve a rule's target folder (ID, well-known alias, nested path such as
+ * "Triage/Delete", or bare name) to a folder ID with the shared resolver. (#248)
+ * Not-found and ambiguous folders become a warning containing "not found", which
+ * create/update treat as fatal when no other action is left; any other failure
+ * (auth, network, Graph outage) is rethrown rather than misreported.
+ * @param {string} accessToken - Graph API access token
+ * @param {string} folder - Folder ID, alias, path, or name
+ * @param {string} label - Warning prefix, e.g. "Target folder"
+ * @returns {Promise<{ folderId?: string, warning?: string }>}
+ */
+async function resolveRuleFolder(accessToken, folder, label) {
+  const spec = looksLikeFolderId(folder)
+    ? { id: folder.trim() }
+    : { name: folder };
+  try {
+    const resolved = await resolveFolder(accessToken, spec);
+    return { folderId: resolved.id };
+  } catch (error) {
+    const message = error.message || '';
+    if (message.includes('ambiguous')) {
+      return {
+        warning: `${label} "${folder}" not found as a single folder. ${message}`,
+      };
+    }
+    if (
+      message.includes('not found') ||
+      message.startsWith('Invalid folder path') ||
+      /status (400|404):/.test(message)
+    ) {
+      // The resolver's reason follows (an empty path segment, Graph's 400 text);
+      // its own not-found message already carries the action=list guidance.
+      const hint = message.includes('action=list')
+        ? ''
+        : ' Use `folders` action=list to see folders (with IDs and full paths), or pass a path like "Parent/Child" or a folderId.';
+      return {
+        warning: `${label} "${folder}" not found. ${message}${hint}`,
+      };
+    }
+    throw error;
+  }
+}
+
 /**
  * Build a Graph API actions object from flat tool parameters.
  * Async because folder resolution requires API calls.
@@ -115,21 +158,23 @@ async function buildActions(args, accessToken) {
   const actions = {};
   const warnings = [];
 
-  // Folder-based actions (name → ID resolution)
-  if (args.moveToFolder) {
-    const folderId = await getFolderIdByName(accessToken, args.moveToFolder);
-    if (!folderId) {
-      warnings.push(`Target folder "${args.moveToFolder}" not found.`);
-    } else {
-      actions.moveToFolder = folderId;
-    }
-  }
-  if (args.copyToFolder) {
-    const folderId = await getFolderIdByName(accessToken, args.copyToFolder);
-    if (!folderId) {
-      warnings.push(`Copy-to folder "${args.copyToFolder}" not found.`);
-    } else {
-      actions.copyToFolder = folderId;
+  // Folder-based actions (ID, alias, nested path or name → ID)
+  const folderActions = [
+    ['moveToFolder', 'Target folder'],
+    ['copyToFolder', 'Copy-to folder'],
+  ];
+  for (const [param, label] of folderActions) {
+    if (args[param]) {
+      const { folderId, warning } = await resolveRuleFolder(
+        accessToken,
+        args[param],
+        label
+      );
+      if (folderId) {
+        actions[param] = folderId;
+      } else {
+        warnings.push(warning);
+      }
     }
   }
 

package/utils/datetime.js

@@ -0,0 +1,170 @@
+/**
+ * Shared ISO 8601 date-time parsing and timezone conversion.
+ *
+ * Nothing here reads the server's local timezone: zoned values are converted
+ * with their own `Z`/offset, and wall-clock values are read in an explicit IANA
+ * zone through Intl, so results are the same on every machine.
+ */
+const config = require('../config');
+
+// An ISO 8601 instant with an explicit zone: `Z` or a ±hh:mm offset. A
+// zone-less value would be read in the server's local timezone by Date.parse,
+// so results would differ between machines; date-only values are rejected for
+// the same reason.
+const ISO_INSTANT =
+  /^(\d{4})-(\d{2})-(\d{2})T\d{2}:\d{2}(?::\d{2}(?:\.\d{1,9})?)?(?:Z|[+-]\d{2}:\d{2})$/;
+
+// A wall-clock date-time with no zone, e.g. 2026-03-01T09:00 or
+// 2026-03-01T09:00:00.5. Callers decide which zone it is read in.
+const WALL_TIME =
+  /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2})(?::(\d{2})(?:\.\d{1,9})?)?$/;
+
+const MIN_YEAR = 1900;
+
+/**
+ * Error raised for a date-time argument that can't be read, so handlers can
+ * report it as a tool error before touching the network.
+ */
+class InvalidDateTimeError extends Error {}
+
+/** True when year/month/day name a real calendar day (no 30 Feb roll-over). */
+function isRealDate(year, month, day) {
+  return (
+    year >= MIN_YEAR &&
+    month >= 1 &&
+    month <= 12 &&
+    new Date(Date.UTC(year, month - 1, day)).getUTCDate() === day
+  );
+}
+
+/**
+ * Parse an ISO 8601 instant that carries `Z` or a ±hh:mm offset.
+ * @returns {number} epoch milliseconds, or NaN when the value isn't one
+ */
+function parseIsoInstant(value) {
+  const s = typeof value === 'string' ? value.trim().replace(/z$/, 'Z') : '';
+  const m = ISO_INSTANT.exec(s);
+  if (!m || !isRealDate(Number(m[1]), Number(m[2]), Number(m[3]))) {
+    return NaN;
+  }
+  return Date.parse(s);
+}
+
+/**
+ * Parse a zone-less wall-clock date-time.
+ * @returns {number[]|null} [year, month, day, hour, minute, second], or null
+ */
+function parseWallTime(value) {
+  const m = typeof value === 'string' ? WALL_TIME.exec(value.trim()) : null;
+  if (!m) return null;
+  const [year, month, day, hour, minute] = m.slice(1, 6).map(Number);
+  const second = m[6] === undefined ? 0 : Number(m[6]);
+  if (
+    !isRealDate(year, month, day) ||
+    hour > 23 ||
+    minute > 59 ||
+    second > 59
+  ) {
+    return null;
+  }
+  return [year, month, day, hour, minute, second];
+}
+
+const formatters = new Map();
+
+/**
+ * Wall-clock date and time of an instant in an IANA zone.
+ * @returns {{date: string, time: string, wallMs: number}|null} `date` is
+ *   YYYY-MM-DD, `time` HH:mm:ss, `wallMs` the wall-clock fields read as UTC;
+ *   null when the zone is unknown to Intl
+ */
+function zonedParts(ms, timeZone) {
+  let fmt = formatters.get(timeZone);
+  if (!fmt) {
+    try {
+      fmt = new Intl.DateTimeFormat('en-US', {
+        timeZone,
+        hourCycle: 'h23',
+        year: 'numeric',
+        month: '2-digit',
+        day: '2-digit',
+        hour: '2-digit',
+        minute: '2-digit',
+        second: '2-digit',
+      });
+    } catch (_e) {
+      return null;
+    }
+    formatters.set(timeZone, fmt);
+  }
+  const p = {};
+  for (const { type, value } of fmt.formatToParts(new Date(ms))) {
+    p[type] = value;
+  }
+  const date = `${p.year}-${p.month}-${p.day}`;
+  const time = `${p.hour}:${p.minute}:${p.second}`;
+  return {
+    date,
+    time,
+    wallMs: Date.parse(`${date}T${time}Z`),
+  };
+}
+
+/**
+ * Convert a wall-clock date-time in an IANA zone to an instant.
+ * @returns {number} epoch milliseconds, or NaN for a bad value or zone
+ */
+function zonedWallTimeToUtcMs(wall, timeZone) {
+  const f = parseWallTime(wall);
+  if (!f) return NaN;
+  const guess = Date.UTC(f[0], f[1] - 1, f[2], f[3], f[4], f[5]);
+  const offsetAt = (t) => {
+    const parts = zonedParts(t, timeZone);
+    return parts ? parts.wallMs - t : NaN;
+  };
+  const first = offsetAt(guess);
+  if (Number.isNaN(first)) return NaN;
+  // Re-check the offset at the candidate instant, in case a DST change falls
+  // between the naive guess and the real instant.
+  const second = offsetAt(guess - first);
+  return guess - (second === first ? first : second);
+}
+
+/**
+ * Turn an ISO 8601 date-time into a Graph dateTimeTimeZone envelope.
+ *
+ * - With `Z` or a ±hh:mm offset: the same instant, sent in UTC (Graph wants
+ *   the dateTime without a trailing Z).
+ * - Without a zone: sent unchanged, read in `timeZone` (default
+ *   DEFAULT_TIMEZONE).
+ *
+ * @throws {InvalidDateTimeError} for anything else (date-only, impossible
+ *   dates, free text)
+ */
+function toGraphDateTimeTimeZone(
+  value,
+  paramName,
+  timeZone = config.DEFAULT_TIMEZONE
+) {
+  const instant = parseIsoInstant(value);
+  if (!Number.isNaN(instant)) {
+    return {
+      dateTime: new Date(instant).toISOString().replace(/(?:\.000)?Z$/, ''),
+      timeZone: 'UTC',
+    };
+  }
+  if (parseWallTime(value)) {
+    return { dateTime: value.trim(), timeZone };
+  }
+  throw new InvalidDateTimeError(
+    `Invalid ${paramName}: expected an ISO 8601 date-time with a time, e.g. "2026-03-01T09:00:00Z" (UTC), "2026-03-01T09:00:00+10:00" (offset) or "2026-03-01T09:00:00" (read in ${timeZone}) (got ${JSON.stringify(String(value).slice(0, 40))}).`
+  );
+}
+
+module.exports = {
+  InvalidDateTimeError,
+  parseIsoInstant,
+  zonedParts,
+  zonedWallTimeToUtcMs,
+  toGraphDateTimeTimeZone,
+};