@matimo/microsoft 0.1.0 → 0.1.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@matimo/microsoft",
-  "version": "0.1.0",
+  "version": "0.1.4",
   "description": "Microsoft Graph tools for Matimo (search, files, mail, Teams, calendar, SharePoint)",
   "type": "module",
   "files": [
@@ -8,11 +8,14 @@
     "README.md",
     "definition.yaml"
   ],
+  "dependencies": {
+    "axios": "^1.15.2",
+    "@matimo/core": "0.1.4"
+  },
   "peerDependencies": {
-    "matimo": "0.1.3"
+    "matimo": "0.1.4"
   },
-  "devDependencies": {
-    "axios": "^1.15.2",
-    "@matimo/core": "0.1.3"
+  "scripts": {
+    "build": "tsc"
   }
 }

package/tools/graph-client.js

@@ -0,0 +1,132 @@
+/**
+ * Shared Microsoft Graph helpers for all `type: function` tools in this package.
+ *
+ * Conventions (mirrors @matimo/slack and @matimo/gmail):
+ * - Tools NEVER perform OAuth token exchange. A delegated Graph access token is
+ *   injected at execution time via `context.credentials.MICROSOFT_GRAPH_ACCESS_TOKEN`
+ *   (or the MICROSOFT_GRAPH_ACCESS_TOKEN environment variable as a fallback).
+ * - Every Graph error is normalized into a MatimoError with the closest matching
+ *   ErrorCode (Matimo has no per-provider error classes — see errors/matimo-error.ts).
+ */
+import axios from 'axios';
+import { MatimoError, ErrorCode } from '@matimo/core/runtime';
+export const GRAPH_BASE_URL = 'https://graph.microsoft.com/v1.0';
+const RETRYABLE_STATUS_CODES = new Set([429, 500, 503]);
+const MAX_RETRIES = 3;
+const INITIAL_BACKOFF_MS = 500;
+/**
+ * Resolve the delegated Graph access token. Matimo never exchanges OAuth codes —
+ * the token must already be present in per-call credentials or the environment.
+ */
+export function getAccessToken(context) {
+    const token = context?.credentials?.MICROSOFT_GRAPH_ACCESS_TOKEN ?? process.env.MICROSOFT_GRAPH_ACCESS_TOKEN;
+    if (!token) {
+        throw new MatimoError('Microsoft Graph access token is missing. Provide it via credentials.MICROSOFT_GRAPH_ACCESS_TOKEN ' +
+            'or the MICROSOFT_GRAPH_ACCESS_TOKEN environment variable. Matimo never performs the OAuth ' +
+            'exchange itself — connect Microsoft in Nova first.', ErrorCode.AUTH_FAILED, { provider: 'microsoft', placeholder: 'MICROSOFT_GRAPH_ACCESS_TOKEN' });
+    }
+    return token;
+}
+/**
+ * Validate required parameters BEFORE any network call, mirroring the
+ * "ValidationError before any API call" requirement. Throws VALIDATION_FAILED.
+ */
+export function requireParams(params, required, toolName) {
+    const missing = required.filter((name) => {
+        const value = params[name];
+        return value === undefined || value === null || value === '';
+    });
+    if (missing.length > 0) {
+        throw new MatimoError(`${toolName}: missing required parameter(s): ${missing.join(', ')}`, ErrorCode.VALIDATION_FAILED, { toolName, missingParams: missing });
+    }
+}
+/**
+ * Map a Microsoft Graph HTTP error response onto a MatimoError using the closest
+ * matching ErrorCode (Matimo has no CredentialError/NotFoundError/ProviderError
+ * classes — see typescript/packages/core/src/errors/matimo-error.ts):
+ *   401/403 -> AUTH_FAILED      ("Microsoft Graph access denied. Check connection status in Nova.")
+ *   404     -> FILE_NOT_FOUND   (details.resourceType identifies what was missing)
+ *   429     -> RATE_LIMIT_EXCEEDED (details.retryAfterSeconds carries Retry-After)
+ *   500/503 -> EXECUTION_FAILED (retryable)
+ *   other   -> EXECUTION_FAILED
+ */
+export function mapGraphError(status, data, headers, resourceType) {
+    const graphError = data?.error;
+    const details = { statusCode: status, graphError, resourceType };
+    if (status === 401 || status === 403) {
+        return new MatimoError('Microsoft Graph access denied. Check connection status in Nova.', ErrorCode.AUTH_FAILED, details);
+    }
+    if (status === 404) {
+        return new MatimoError(`${resourceType} not found.`, ErrorCode.FILE_NOT_FOUND, details);
+    }
+    if (status === 429) {
+        const retryAfterHeader = headers?.['retry-after'] ?? headers?.['Retry-After'];
+        const retryAfterSeconds = retryAfterHeader !== undefined ? Number(retryAfterHeader) : undefined;
+        return new MatimoError('Microsoft Graph rate limit exceeded. Respect Retry-After before retrying.', ErrorCode.RATE_LIMIT_EXCEEDED, { ...details, retryAfterSeconds });
+    }
+    if (status === 500 || status === 503) {
+        return new MatimoError('Microsoft Graph service is temporarily unavailable. Please retry shortly.', ErrorCode.EXECUTION_FAILED, details);
+    }
+    return new MatimoError(`Microsoft Graph request failed with status ${status}.`, ErrorCode.EXECUTION_FAILED, details);
+}
+function buildQueryString(query) {
+    if (!query)
+        return '';
+    const parts = Object.entries(query)
+        .filter(([, value]) => value !== undefined && value !== null && value !== '')
+        .map(([key, value]) => `${encodeURIComponent(key)}=${encodeURIComponent(String(value))}`);
+    return parts.length > 0 ? `?${parts.join('&')}` : '';
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Perform an authenticated Microsoft Graph request with retry-on-429/5xx
+ * (respecting Retry-After, exponential backoff, max 3 retries) and normalized
+ * MatimoError mapping for every other failure.
+ */
+export async function graphRequest(options) {
+    const { method, path, token, query, body, headers, resourceType = 'Resource', responseType = 'json', allowEmptyResponse = false, } = options;
+    const url = `${GRAPH_BASE_URL}${path}${buildQueryString(query)}`;
+    let attempt = 0;
+    for (;;) {
+        let response;
+        try {
+            response = await axios.request({
+                method,
+                url,
+                data: body,
+                responseType,
+                validateStatus: () => true,
+                headers: {
+                    Authorization: `Bearer ${token}`,
+                    ...(responseType === 'json' ? { Accept: 'application/json' } : {}),
+                    ...(body !== undefined && !(body instanceof Buffer)
+                        ? { 'Content-Type': 'application/json' }
+                        : {}),
+                    ...headers,
+                },
+            });
+        }
+        catch (error) {
+            throw new MatimoError('Microsoft Graph request failed before a response was received (network error).', ErrorCode.NETWORK_ERROR, { path, originalError: error instanceof Error ? error.message : String(error) }, error);
+        }
+        if (response.status >= 200 && response.status < 300) {
+            if (allowEmptyResponse && (response.status === 204 || !response.data)) {
+                return null;
+            }
+            return response.data;
+        }
+        const error = mapGraphError(response.status, response.data, response.headers, resourceType);
+        const isRetryable = RETRYABLE_STATUS_CODES.has(response.status) && attempt < MAX_RETRIES;
+        if (!isRetryable) {
+            throw error;
+        }
+        const retryAfterSeconds = error.details?.retryAfterSeconds;
+        const delayMs = retryAfterSeconds !== undefined && !Number.isNaN(retryAfterSeconds)
+            ? retryAfterSeconds * 1000
+            : INITIAL_BACKOFF_MS * 2 ** attempt;
+        attempt += 1;
+        await sleep(delayMs);
+    }
+}

package/tools/graph-client.ts

@@ -9,7 +9,7 @@
  *   ErrorCode (Matimo has no per-provider error classes — see errors/matimo-error.ts).
  */
 import axios from 'axios';
-import { MatimoError, ErrorCode } from '@matimo/core';
+import { MatimoError, ErrorCode } from '@matimo/core/runtime';
 
 export const GRAPH_BASE_URL = 'https://graph.microsoft.com/v1.0';
 

package/tools/ms_create_calendar_event/definition.yaml

@@ -53,7 +53,7 @@ parameters:
 
 execution:
   type: function
-  code: ms_create_calendar_event.ts
+  code: ms_create_calendar_event.js
   timeout: 25000
 
 authentication:

package/tools/ms_create_calendar_event/ms_create_calendar_event.js

@@ -0,0 +1,54 @@
+/**
+ * ms_create_calendar_event — POST /me/events
+ * https://learn.microsoft.com/en-us/graph/api/user-post-events
+ */
+import { MatimoError, ErrorCode } from '@matimo/core/runtime';
+import { getAccessToken, requireParams, graphRequest } from '../graph-client.js';
+const DEFAULT_TIMEZONE = 'UTC';
+function toAttendeeList(value) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value) || value.some((entry) => typeof entry !== 'string' || !entry)) {
+        throw new MatimoError("ms_create_calendar_event: 'attendees' must be an array of email address strings", ErrorCode.VALIDATION_FAILED, { attendees: value });
+    }
+    return value.map((address) => ({
+        emailAddress: { address },
+        type: 'required',
+    }));
+}
+export default async function execute(params, context) {
+    requireParams(params, ['subject', 'start', 'end'], 'ms_create_calendar_event');
+    const subject = String(params.subject);
+    const start = String(params.start);
+    const end = String(params.end);
+    const timezone = typeof params.timezone === 'string' && params.timezone ? params.timezone : DEFAULT_TIMEZONE;
+    const attendees = toAttendeeList(params.attendees);
+    const isOnlineMeeting = params.is_online_meeting === true;
+    const token = getAccessToken(context);
+    const event = await graphRequest({
+        method: 'POST',
+        path: '/me/events',
+        token,
+        resourceType: 'Calendar',
+        body: {
+            subject,
+            ...(typeof params.body === 'string' && params.body
+                ? { body: { contentType: 'Text', content: params.body } }
+                : {}),
+            start: { dateTime: start, timeZone: timezone },
+            end: { dateTime: end, timeZone: timezone },
+            ...(attendees.length > 0 ? { attendees } : {}),
+            ...(typeof params.location === 'string' && params.location
+                ? { location: { displayName: params.location } }
+                : {}),
+            isOnlineMeeting,
+            ...(isOnlineMeeting ? { onlineMeetingProvider: 'teamsForBusiness' } : {}),
+        },
+    });
+    return {
+        success: true,
+        event_id: event?.id ?? '',
+        web_link: event?.webLink ?? '',
+        ...(event?.onlineMeeting?.joinUrl ? { join_url: event.onlineMeeting.joinUrl } : {}),
+    };
+}

package/tools/ms_create_calendar_event/ms_create_calendar_event.ts

@@ -2,8 +2,12 @@
  * ms_create_calendar_event — POST /me/events
  * https://learn.microsoft.com/en-us/graph/api/user-post-events
  */
-import { MatimoError, ErrorCode } from '@matimo/core';
-import { getAccessToken, requireParams, graphRequest, type ToolContext } from '../graph-client';
+import { MatimoError, ErrorCode } from '@matimo/core/runtime';
+import { getAccessToken, requireParams, graphRequest } from '../graph-client.js';
+
+interface ToolContext {
+  credentials?: Record<string, string>;
+}
 
 const DEFAULT_TIMEZONE = 'UTC';
 

package/tools/ms_create_document/definition.yaml

@@ -51,7 +51,7 @@ parameters:
 
 execution:
   type: function
-  code: ms_create_document.ts
+  code: ms_create_document.js
   timeout: 30000
 
 authentication:

package/tools/ms_create_document/ms_create_document.js

@@ -0,0 +1,59 @@
+/**
+ * ms_create_document — PUT /drives/{drive-id}/items/{parent-item-id}:/{filename}:/content
+ * https://learn.microsoft.com/en-us/graph/api/driveitem-put-content
+ *
+ * Uses the "simple upload" by-path addressing syntax. Graph caps this endpoint at
+ * 4 MB; larger files require a resumable upload session, which is out of scope here
+ * and is rejected with a clear validation error rather than silently truncating.
+ */
+import { MatimoError, ErrorCode } from '@matimo/core/runtime';
+import { getAccessToken, requireParams, graphRequest } from '../graph-client.js';
+const VALID_ENCODINGS = ['text', 'base64'];
+const VALID_CONFLICT_BEHAVIOURS = ['replace', 'rename', 'fail'];
+const DEFAULT_PARENT_ITEM_ID = 'root';
+const MAX_UPLOAD_BYTES = 4 * 1024 * 1024;
+export default async function execute(params, context) {
+    requireParams(params, ['drive_id', 'filename', 'content'], 'ms_create_document');
+    const driveId = String(params.drive_id);
+    const parentItemId = typeof params.parent_item_id === 'string' && params.parent_item_id
+        ? params.parent_item_id
+        : DEFAULT_PARENT_ITEM_ID;
+    const filename = String(params.filename);
+    const encoding = params.content_encoding === undefined ? 'text' : String(params.content_encoding);
+    if (!VALID_ENCODINGS.includes(encoding)) {
+        throw new MatimoError(`ms_create_document: 'content_encoding' must be one of ${VALID_ENCODINGS.join(', ')} (received '${encoding}')`, ErrorCode.VALIDATION_FAILED, { content_encoding: params.content_encoding });
+    }
+    const conflictBehaviour = params.conflict_behaviour === undefined ? 'replace' : String(params.conflict_behaviour);
+    if (!VALID_CONFLICT_BEHAVIOURS.includes(conflictBehaviour)) {
+        throw new MatimoError(`ms_create_document: 'conflict_behaviour' must be one of ${VALID_CONFLICT_BEHAVIOURS.join(', ')} (received '${conflictBehaviour}')`, ErrorCode.VALIDATION_FAILED, { conflict_behaviour: params.conflict_behaviour });
+    }
+    const buffer = encoding === 'base64'
+        ? Buffer.from(String(params.content), 'base64')
+        : Buffer.from(String(params.content), 'utf-8');
+    if (buffer.byteLength > MAX_UPLOAD_BYTES) {
+        throw new MatimoError(`ms_create_document: content is ${buffer.byteLength} bytes, exceeding the ` +
+            `${MAX_UPLOAD_BYTES}-byte limit of the simple-upload endpoint. Files this large ` +
+            'require a resumable upload session, which this tool does not implement.', ErrorCode.VALIDATION_FAILED, { sizeBytes: buffer.byteLength, maxBytes: MAX_UPLOAD_BYTES });
+    }
+    const token = getAccessToken(context);
+    // By-path addressing uses literal colons as delimiters — only the path SEGMENTS
+    // (drive id, parent item id, filename) are percent-encoded, not the colons.
+    const path = `/drives/${encodeURIComponent(driveId)}/items/${encodeURIComponent(parentItemId)}` +
+        `:/${encodeURIComponent(filename)}:/content`;
+    const item = await graphRequest({
+        method: 'PUT',
+        path,
+        token,
+        resourceType: 'Drive folder',
+        query: { '@microsoft.graph.conflictBehavior': conflictBehaviour },
+        body: buffer,
+        headers: { 'Content-Type': 'application/octet-stream' },
+    });
+    return {
+        success: true,
+        item_id: item?.id ?? '',
+        name: item?.name ?? filename,
+        web_url: item?.webUrl ?? '',
+        size_bytes: item?.size ?? buffer.byteLength,
+    };
+}

package/tools/ms_create_document/ms_create_document.ts

@@ -6,8 +6,12 @@
  * 4 MB; larger files require a resumable upload session, which is out of scope here
  * and is rejected with a clear validation error rather than silently truncating.
  */
-import { MatimoError, ErrorCode } from '@matimo/core';
-import { getAccessToken, requireParams, graphRequest, type ToolContext } from '../graph-client';
+import { MatimoError, ErrorCode } from '@matimo/core/runtime';
+import { getAccessToken, requireParams, graphRequest } from '../graph-client.js';
+
+interface ToolContext {
+  credentials?: Record<string, string>;
+}
 
 const VALID_ENCODINGS = ['text', 'base64'];
 const VALID_CONFLICT_BEHAVIOURS = ['replace', 'rename', 'fail'];

package/tools/ms_get_email/definition.yaml

@@ -35,7 +35,7 @@ parameters:
 
 execution:
   type: function
-  code: ms_get_email.ts
+  code: ms_get_email.js
   timeout: 20000
 
 authentication:

package/tools/ms_get_email/ms_get_email.js

@@ -0,0 +1,56 @@
+/**
+ * ms_get_email — GET /me/messages
+ * https://learn.microsoft.com/en-us/graph/api/user-list-messages
+ */
+import { MatimoError, ErrorCode } from '@matimo/core/runtime';
+import { getAccessToken, requireParams, graphRequest } from '../graph-client.js';
+const DEFAULT_TOP = 10;
+const MAX_TOP = 50;
+function formatSender(message) {
+    const address = message.from?.emailAddress;
+    if (!address)
+        return '';
+    if (address.name && address.address)
+        return `${address.name} <${address.address}>`;
+    return address.name ?? address.address ?? '';
+}
+export default async function execute(params, context) {
+    requireParams(params, [], 'ms_get_email');
+    const top = params.top === undefined ? DEFAULT_TOP : Number(params.top);
+    if (!Number.isFinite(top) || top < 1 || top > MAX_TOP) {
+        throw new MatimoError(`ms_get_email: 'top' must be a number between 1 and ${MAX_TOP} (received ${String(params.top)})`, ErrorCode.VALIDATION_FAILED, { top: params.top });
+    }
+    const folderId = typeof params.folder_id === 'string' && params.folder_id ? params.folder_id : undefined;
+    const filter = typeof params.filter === 'string' && params.filter ? params.filter : undefined;
+    const search = typeof params.search === 'string' && params.search ? params.search : undefined;
+    const token = getAccessToken(context);
+    const path = folderId
+        ? `/me/mailFolders/${encodeURIComponent(folderId)}/messages`
+        : '/me/messages';
+    const data = await graphRequest({
+        method: 'GET',
+        path,
+        token,
+        resourceType: 'Mail folder',
+        headers: search ? { 'ConsistencyLevel': 'eventual' } : undefined,
+        query: {
+            $top: top,
+            $select: 'id,subject,from,receivedDateTime,isRead,bodyPreview,hasAttachments',
+            ...(filter ? { $filter: filter } : {}),
+            ...(search ? { $search: search } : {}),
+        },
+    });
+    const messages = (data?.value ?? []).map((message) => ({
+        id: message.id ?? '',
+        subject: message.subject ?? '',
+        from: formatSender(message),
+        received_at: message.receivedDateTime ?? '',
+        is_read: message.isRead ?? false,
+        body_preview: message.bodyPreview ?? '',
+        has_attachments: message.hasAttachments ?? false,
+    }));
+    return {
+        success: true,
+        messages,
+    };
+}

package/tools/ms_get_email/ms_get_email.ts

@@ -2,8 +2,12 @@
  * ms_get_email — GET /me/messages
  * https://learn.microsoft.com/en-us/graph/api/user-list-messages
  */
-import { MatimoError, ErrorCode } from '@matimo/core';
-import { getAccessToken, requireParams, graphRequest, type ToolContext } from '../graph-client';
+import { MatimoError, ErrorCode } from '@matimo/core/runtime';
+import { getAccessToken, requireParams, graphRequest } from '../graph-client.js';
+
+interface ToolContext {
+  credentials?: Record<string, string>;
+}
 
 const DEFAULT_TOP = 10;
 const MAX_TOP = 50;

package/tools/ms_list_files/definition.yaml

@@ -27,7 +27,7 @@ parameters:
 
 execution:
   type: function
-  code: ms_list_files.ts
+  code: ms_list_files.js
   timeout: 20000
 
 authentication:

package/tools/ms_list_files/ms_list_files.js

@@ -0,0 +1,42 @@
+/**
+ * ms_list_files — GET /drives/{drive_id}/items/{item_id}/children
+ * https://learn.microsoft.com/en-us/graph/api/driveitem-list-children
+ */
+import { MatimoError, ErrorCode } from '@matimo/core/runtime';
+import { getAccessToken, requireParams, graphRequest } from '../graph-client.js';
+const DEFAULT_ITEM_ID = 'root';
+const DEFAULT_TOP = 20;
+const MAX_TOP = 100;
+export default async function execute(params, context) {
+    requireParams(params, ['drive_id'], 'ms_list_files');
+    const driveId = String(params.drive_id);
+    const itemId = typeof params.item_id === 'string' && params.item_id ? params.item_id : DEFAULT_ITEM_ID;
+    const top = params.top === undefined ? DEFAULT_TOP : Number(params.top);
+    if (!Number.isFinite(top) || top < 1 || top > MAX_TOP) {
+        throw new MatimoError(`ms_list_files: 'top' must be a number between 1 and ${MAX_TOP} (received ${String(params.top)})`, ErrorCode.VALIDATION_FAILED, { top: params.top });
+    }
+    const token = getAccessToken(context);
+    const data = await graphRequest({
+        method: 'GET',
+        path: `/drives/${encodeURIComponent(driveId)}/items/${encodeURIComponent(itemId)}/children`,
+        token,
+        resourceType: 'Drive folder',
+        query: {
+            $top: top,
+            $select: 'id,name,size,lastModifiedDateTime,webUrl,file,folder',
+        },
+    });
+    const items = (data?.value ?? []).map((item) => ({
+        id: item.id ?? '',
+        name: item.name ?? '',
+        type: item.folder ? 'folder' : 'file',
+        size_bytes: item.size ?? 0,
+        last_modified: item.lastModifiedDateTime ?? '',
+        ...(item.file?.mimeType ? { mime_type: item.file.mimeType } : {}),
+        web_url: item.webUrl ?? '',
+    }));
+    return {
+        success: true,
+        items,
+    };
+}

package/tools/ms_list_files/ms_list_files.ts

@@ -2,8 +2,12 @@
  * ms_list_files — GET /drives/{drive_id}/items/{item_id}/children
  * https://learn.microsoft.com/en-us/graph/api/driveitem-list-children
  */
-import { MatimoError, ErrorCode } from '@matimo/core';
-import { getAccessToken, requireParams, graphRequest, type ToolContext } from '../graph-client';
+import { MatimoError, ErrorCode } from '@matimo/core/runtime';
+import { getAccessToken, requireParams, graphRequest } from '../graph-client.js';
+
+interface ToolContext {
+  credentials?: Record<string, string>;
+}
 
 const DEFAULT_ITEM_ID = 'root';
 const DEFAULT_TOP = 20;

package/tools/ms_publish_to_sharepoint/definition.yaml

@@ -43,7 +43,7 @@ parameters:
 
 execution:
   type: function
-  code: ms_publish_to_sharepoint.ts
+  code: ms_publish_to_sharepoint.js
   timeout: 30000
 
 authentication:

package/tools/ms_publish_to_sharepoint/ms_publish_to_sharepoint.js

@@ -0,0 +1,96 @@
+/**
+ * ms_publish_to_sharepoint
+ *   Create:  POST /sites/{site-id}/pages
+ *            https://learn.microsoft.com/en-us/graph/api/sitepage-create
+ *   Publish: POST /sites/{site-id}/pages/{page-id}/microsoft.graph.sitePage/publish
+ *            https://learn.microsoft.com/en-us/graph/api/sitepage-publish
+ *
+ * Site pages always store web part bodies as HTML, so plain-text content is
+ * HTML-escaped and wrapped in a single <p> before being placed in a textWebPart.
+ */
+import { MatimoError, ErrorCode } from '@matimo/core/runtime';
+import { getAccessToken, requireParams, graphRequest } from '../graph-client.js';
+const VALID_CONTENT_TYPES = ['html', 'text'];
+const HTML_ESCAPES = {
+    '&': '&amp;',
+    '<': '&lt;',
+    '>': '&gt;',
+    '"': '&quot;',
+    "'": '&#39;',
+};
+function escapeHtml(text) {
+    return text.replace(/[&<>"']/g, (ch) => HTML_ESCAPES[ch]);
+}
+function deriveFileName(title) {
+    const slug = title
+        .toLowerCase()
+        .trim()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+    return `${slug || 'page'}.aspx`;
+}
+export default async function execute(params, context) {
+    requireParams(params, ['site_id', 'title', 'content'], 'ms_publish_to_sharepoint');
+    const siteId = String(params.site_id);
+    const title = String(params.title);
+    const contentType = params.content_type === undefined ? 'html' : String(params.content_type);
+    if (!VALID_CONTENT_TYPES.includes(contentType)) {
+        throw new MatimoError(`ms_publish_to_sharepoint: 'content_type' must be one of ${VALID_CONTENT_TYPES.join(', ')} (received '${contentType}')`, ErrorCode.VALIDATION_FAILED, { content_type: params.content_type });
+    }
+    const rawContent = String(params.content);
+    const innerHtml = contentType === 'text' ? `<p>${escapeHtml(rawContent)}</p>` : rawContent;
+    const shouldPublish = params.publish === undefined ? true : params.publish === true;
+    const token = getAccessToken(context);
+    const page = await graphRequest({
+        method: 'POST',
+        path: `/sites/${encodeURIComponent(siteId)}/pages`,
+        token,
+        resourceType: 'SharePoint site',
+        body: {
+            '@odata.type': '#microsoft.graph.sitePage',
+            name: deriveFileName(title),
+            title,
+            pageLayout: 'article',
+            canvasLayout: {
+                horizontalSections: [
+                    {
+                        layout: 'oneColumn',
+                        id: '1',
+                        emphasis: 'none',
+                        columns: [
+                            {
+                                id: '1',
+                                width: 12,
+                                webparts: [
+                                    {
+                                        '@odata.type': '#microsoft.graph.textWebPart',
+                                        innerHtml,
+                                    },
+                                ],
+                            },
+                        ],
+                    },
+                ],
+            },
+        },
+    });
+    const pageId = page?.id;
+    if (!pageId) {
+        throw new MatimoError('ms_publish_to_sharepoint: Microsoft Graph did not return an ID for the created page.', ErrorCode.EXECUTION_FAILED, { page });
+    }
+    if (shouldPublish) {
+        await graphRequest({
+            method: 'POST',
+            path: `/sites/${encodeURIComponent(siteId)}/pages/${encodeURIComponent(pageId)}/microsoft.graph.sitePage/publish`,
+            token,
+            resourceType: 'SharePoint page',
+            allowEmptyResponse: true,
+        });
+    }
+    return {
+        success: true,
+        page_id: pageId,
+        web_url: page?.webUrl ?? '',
+        published: shouldPublish,
+    };
+}

package/tools/ms_publish_to_sharepoint/ms_publish_to_sharepoint.ts

@@ -8,8 +8,12 @@
  * Site pages always store web part bodies as HTML, so plain-text content is
  * HTML-escaped and wrapped in a single <p> before being placed in a textWebPart.
  */
-import { MatimoError, ErrorCode } from '@matimo/core';
-import { getAccessToken, requireParams, graphRequest, type ToolContext } from '../graph-client';
+import { MatimoError, ErrorCode } from '@matimo/core/runtime';
+import { getAccessToken, requireParams, graphRequest } from '../graph-client.js';
+
+interface ToolContext {
+  credentials?: Record<string, string>;
+}
 
 const VALID_CONTENT_TYPES = ['html', 'text'];
 

package/tools/ms_read_file/definition.yaml

@@ -23,7 +23,7 @@ parameters:
 
 execution:
   type: function
-  code: ms_read_file.ts
+  code: ms_read_file.js
   timeout: 30000
 
 authentication:

package/tools/ms_read_file/ms_read_file.js

@@ -0,0 +1,79 @@
+/**
+ * ms_read_file — GET /drives/{drive_id}/items/{item_id}/content
+ * https://learn.microsoft.com/en-us/graph/api/driveitem-get-content
+ *
+ * Scope decision (documented, not a shortcut): this tool performs REAL UTF-8 text
+ * extraction only for plain-text formats. Rich document formats (PDF/Word/Excel/
+ * PowerPoint) return `content: ""` with a format-specific warning rather than
+ * bundling unverified parsing dependencies (no matimo package currently depends on
+ * pdf-parse/mammoth/xlsx/cheerio). Truly-unsupported binaries get the exact warning
+ * the tool's contract specifies: "Binary file — text extraction not supported".
+ */
+import { getAccessToken, requireParams, graphRequest } from '../graph-client.js';
+const TEXT_MIME_PREFIXES = ['text/'];
+const TEXT_MIME_TYPES = new Set(['application/json', 'application/xml']);
+const RICH_DOCUMENT_LABELS = {
+    'application/pdf': 'PDF document',
+    'application/vnd.openxmlformats-officedocument.wordprocessingml.document': 'Word document (.docx)',
+    'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet': 'Excel workbook (.xlsx)',
+    'application/vnd.openxmlformats-officedocument.presentationml.presentation': 'PowerPoint presentation (.pptx)',
+    'application/msword': 'Word document (.doc)',
+    'application/vnd.ms-excel': 'Excel workbook (.xls)',
+    'application/vnd.ms-powerpoint': 'PowerPoint presentation (.ppt)',
+};
+function isPlainTextMime(mimeType) {
+    return TEXT_MIME_TYPES.has(mimeType) || TEXT_MIME_PREFIXES.some((p) => mimeType.startsWith(p));
+}
+export default async function execute(params, context) {
+    requireParams(params, ['drive_id', 'item_id'], 'ms_read_file');
+    const driveId = String(params.drive_id);
+    const itemId = String(params.item_id);
+    const token = getAccessToken(context);
+    const metadata = await graphRequest({
+        method: 'GET',
+        path: `/drives/${encodeURIComponent(driveId)}/items/${encodeURIComponent(itemId)}`,
+        token,
+        resourceType: 'Drive item',
+        query: { $select: 'name,size,file' },
+    });
+    const name = metadata?.name ?? '';
+    const mimeType = metadata?.file?.mimeType ?? 'application/octet-stream';
+    const sizeBytes = metadata?.size ?? 0;
+    const raw = await graphRequest({
+        method: 'GET',
+        path: `/drives/${encodeURIComponent(driveId)}/items/${encodeURIComponent(itemId)}/content`,
+        token,
+        resourceType: 'Drive item content',
+        responseType: 'arraybuffer',
+    });
+    const buffer = Buffer.from(raw);
+    if (isPlainTextMime(mimeType)) {
+        return {
+            success: true,
+            content: buffer.toString('utf-8'),
+            name,
+            mime_type: mimeType,
+            size_bytes: sizeBytes,
+        };
+    }
+    const richDocumentLabel = RICH_DOCUMENT_LABELS[mimeType];
+    if (richDocumentLabel) {
+        return {
+            success: true,
+            content: '',
+            name,
+            mime_type: mimeType,
+            size_bytes: sizeBytes,
+            warning: `${richDocumentLabel} — text extraction for this format is not implemented to avoid ` +
+                'bundling unverified parsing dependencies. Share the file via its web URL instead.',
+        };
+    }
+    return {
+        success: true,
+        content: '',
+        name,
+        mime_type: mimeType,
+        size_bytes: sizeBytes,
+        warning: 'Binary file — text extraction not supported',
+    };
+}

package/tools/ms_read_file/ms_read_file.ts

@@ -9,7 +9,11 @@
  * pdf-parse/mammoth/xlsx/cheerio). Truly-unsupported binaries get the exact warning
  * the tool's contract specifies: "Binary file — text extraction not supported".
  */
-import { getAccessToken, requireParams, graphRequest, type ToolContext } from '../graph-client';
+import { getAccessToken, requireParams, graphRequest } from '../graph-client.js';
+
+interface ToolContext {
+  credentials?: Record<string, string>;
+}
 
 const TEXT_MIME_PREFIXES = ['text/'];
 const TEXT_MIME_TYPES = new Set(['application/json', 'application/xml']);

package/tools/ms_search_knowledge/definition.yaml

@@ -44,7 +44,7 @@ parameters:
 
 execution:
   type: function
-  code: ms_search_knowledge.ts
+  code: ms_search_knowledge.js
   timeout: 20000
 
 authentication:

package/tools/ms_search_knowledge/ms_search_knowledge.js

@@ -0,0 +1,63 @@
+/**
+ * ms_search_knowledge — POST /search/query
+ * https://learn.microsoft.com/en-us/graph/api/search-query
+ */
+import { MatimoError, ErrorCode } from '@matimo/core/runtime';
+import { getAccessToken, requireParams, graphRequest } from '../graph-client.js';
+const VALID_ENTITY_TYPES = ['driveItem', 'listItem', 'site', 'list', 'drive'];
+const DEFAULT_ENTITY_TYPES = ['driveItem', 'listItem', 'site'];
+const DEFAULT_TOP = 10;
+const MAX_TOP = 25;
+export default async function execute(params, context) {
+    requireParams(params, ['query'], 'ms_search_knowledge');
+    const query = String(params.query);
+    const entityTypes = Array.isArray(params.entity_types)
+        ? params.entity_types.map(String)
+        : DEFAULT_ENTITY_TYPES;
+    const invalidEntityTypes = entityTypes.filter((t) => !VALID_ENTITY_TYPES.includes(t));
+    if (entityTypes.length === 0 || invalidEntityTypes.length > 0) {
+        throw new MatimoError(`ms_search_knowledge: invalid entity_types ${JSON.stringify(invalidEntityTypes)}. ` +
+            `Valid values are: ${VALID_ENTITY_TYPES.join(', ')}`, ErrorCode.VALIDATION_FAILED, { entityTypes, invalidEntityTypes });
+    }
+    const top = params.top === undefined ? DEFAULT_TOP : Number(params.top);
+    if (!Number.isFinite(top) || top < 1 || top > MAX_TOP) {
+        throw new MatimoError(`ms_search_knowledge: 'top' must be a number between 1 and ${MAX_TOP} (received ${String(params.top)})`, ErrorCode.VALIDATION_FAILED, { top: params.top });
+    }
+    // Microsoft Search has no dedicated site/drive filter for driveItem/listItem/site
+    // entity types — fold the IDs into the query string as a best-effort scoping hint.
+    // This is documented in the tool description so callers don't expect a hard filter.
+    const scopeHints = [params.site_id, params.drive_id].filter((value) => typeof value === 'string' && value.length > 0);
+    const queryString = scopeHints.length > 0 ? `${query} ${scopeHints.join(' ')}` : query;
+    const token = getAccessToken(context);
+    const data = await graphRequest({
+        method: 'POST',
+        path: '/search/query',
+        token,
+        resourceType: 'Search results',
+        body: {
+            requests: [
+                {
+                    entityTypes,
+                    query: { queryString },
+                    from: 0,
+                    size: top,
+                },
+            ],
+        },
+    });
+    const container = data?.value?.[0]?.hitsContainers?.[0];
+    const hits = container?.hits ?? [];
+    const results = hits.map((hit) => ({
+        id: hit.resource?.id ?? hit.hitId ?? '',
+        name: hit.resource?.name ?? '',
+        summary: hit.summary ?? '',
+        web_url: hit.resource?.webUrl ?? '',
+        last_modified: hit.resource?.lastModifiedDateTime ?? '',
+        score: hit.rank ?? 0,
+    }));
+    return {
+        success: true,
+        results,
+        total_count: container?.total ?? results.length,
+    };
+}

package/tools/ms_search_knowledge/ms_search_knowledge.ts

@@ -2,8 +2,12 @@
  * ms_search_knowledge — POST /search/query
  * https://learn.microsoft.com/en-us/graph/api/search-query
  */
-import { MatimoError, ErrorCode } from '@matimo/core';
-import { getAccessToken, requireParams, graphRequest, type ToolContext } from '../graph-client';
+import { MatimoError, ErrorCode } from '@matimo/core/runtime';
+import { getAccessToken, requireParams, graphRequest } from '../graph-client.js';
+
+interface ToolContext {
+  credentials?: Record<string, string>;
+}
 
 const VALID_ENTITY_TYPES = ['driveItem', 'listItem', 'site', 'list', 'drive'];
 const DEFAULT_ENTITY_TYPES = ['driveItem', 'listItem', 'site'];

package/tools/ms_send_email/definition.yaml

@@ -45,7 +45,7 @@ parameters:
 
 execution:
   type: function
-  code: ms_send_email.ts
+  code: ms_send_email.js
   timeout: 30000
 
 authentication:

package/tools/ms_send_email/ms_send_email.js

@@ -0,0 +1,66 @@
+/**
+ * ms_send_email — draft + send, two Graph calls
+ *   1. POST /me/messages           https://learn.microsoft.com/en-us/graph/api/user-post-messages
+ *   2. POST /me/messages/{id}/send https://learn.microsoft.com/en-us/graph/api/message-send
+ *
+ * Why two calls: POST /me/sendMail returns an empty 202 Accepted with no message
+ * identifier, but this tool's contract promises a `message_id`. Creating a draft
+ * first gives us a real message ID we can report back, then we send that draft.
+ */
+import { MatimoError, ErrorCode } from '@matimo/core/runtime';
+import { getAccessToken, requireParams, graphRequest } from '../graph-client.js';
+const VALID_BODY_TYPES = ['text', 'html'];
+function toRecipientList(value, fieldName) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value) || value.some((entry) => typeof entry !== 'string' || !entry)) {
+        throw new MatimoError(`ms_send_email: '${fieldName}' must be an array of email address strings`, ErrorCode.VALIDATION_FAILED, { field: fieldName, received: value });
+    }
+    return value.map((address) => ({ emailAddress: { address } }));
+}
+export default async function execute(params, context) {
+    requireParams(params, ['to', 'subject', 'body'], 'ms_send_email');
+    const to = toRecipientList(params.to, 'to');
+    if (to.length === 0) {
+        throw new MatimoError("ms_send_email: 'to' must contain at least one recipient email address", ErrorCode.VALIDATION_FAILED, { to: params.to });
+    }
+    const cc = toRecipientList(params.cc, 'cc');
+    const bcc = toRecipientList(params.bcc, 'bcc');
+    const bodyType = params.body_type === undefined ? 'text' : String(params.body_type);
+    if (!VALID_BODY_TYPES.includes(bodyType)) {
+        throw new MatimoError(`ms_send_email: 'body_type' must be one of ${VALID_BODY_TYPES.join(', ')} (received '${bodyType}')`, ErrorCode.VALIDATION_FAILED, { body_type: params.body_type });
+    }
+    const token = getAccessToken(context);
+    const draft = await graphRequest({
+        method: 'POST',
+        path: '/me/messages',
+        token,
+        resourceType: 'Mail draft',
+        body: {
+            subject: String(params.subject),
+            body: {
+                contentType: bodyType === 'html' ? 'HTML' : 'Text',
+                content: String(params.body),
+            },
+            toRecipients: to,
+            ...(cc.length > 0 ? { ccRecipients: cc } : {}),
+            ...(bcc.length > 0 ? { bccRecipients: bcc } : {}),
+        },
+    });
+    const messageId = draft?.id;
+    if (!messageId) {
+        throw new MatimoError('ms_send_email: Microsoft Graph did not return an ID for the created draft message.', ErrorCode.EXECUTION_FAILED, { draft });
+    }
+    await graphRequest({
+        method: 'POST',
+        path: `/me/messages/${encodeURIComponent(messageId)}/send`,
+        token,
+        resourceType: 'Mail draft',
+        allowEmptyResponse: true,
+    });
+    return {
+        success: true,
+        sent: true,
+        message_id: messageId,
+    };
+}

package/tools/ms_send_email/ms_send_email.ts

@@ -7,8 +7,12 @@
  * identifier, but this tool's contract promises a `message_id`. Creating a draft
  * first gives us a real message ID we can report back, then we send that draft.
  */
-import { MatimoError, ErrorCode } from '@matimo/core';
-import { getAccessToken, requireParams, graphRequest, type ToolContext } from '../graph-client';
+import { MatimoError, ErrorCode } from '@matimo/core/runtime';
+import { getAccessToken, requireParams, graphRequest } from '../graph-client.js';
+
+interface ToolContext {
+  credentials?: Record<string, string>;
+}
 
 const VALID_BODY_TYPES = ['text', 'html'];
 

package/tools/ms_send_teams_message/definition.yaml

@@ -39,7 +39,7 @@ parameters:
 
 execution:
   type: function
-  code: ms_send_teams_message.ts
+  code: ms_send_teams_message.js
   timeout: 20000
 
 authentication:

package/tools/ms_send_teams_message/ms_send_teams_message.js

@@ -0,0 +1,46 @@
+/**
+ * ms_send_teams_message
+ *   New message:  POST /teams/{team-id}/channels/{channel-id}/messages
+ *                 https://learn.microsoft.com/en-us/graph/api/channel-post-messages
+ *   Reply:        POST /teams/{team-id}/channels/{channel-id}/messages/{message-id}/replies
+ *                 https://learn.microsoft.com/en-us/graph/api/chatmessage-post-replies
+ */
+import { MatimoError, ErrorCode } from '@matimo/core/runtime';
+import { getAccessToken, requireParams, graphRequest } from '../graph-client.js';
+const VALID_CONTENT_TYPES = ['text', 'html'];
+export default async function execute(params, context) {
+    requireParams(params, ['team_id', 'channel_id', 'text'], 'ms_send_teams_message');
+    const teamId = String(params.team_id);
+    const channelId = String(params.channel_id);
+    const text = String(params.text);
+    const contentType = params.content_type === undefined ? 'text' : String(params.content_type);
+    if (!VALID_CONTENT_TYPES.includes(contentType)) {
+        throw new MatimoError(`ms_send_teams_message: 'content_type' must be one of ${VALID_CONTENT_TYPES.join(', ')} (received '${contentType}')`, ErrorCode.VALIDATION_FAILED, { content_type: params.content_type });
+    }
+    const replyToMessageId = typeof params.reply_to_message_id === 'string' && params.reply_to_message_id
+        ? params.reply_to_message_id
+        : undefined;
+    const token = getAccessToken(context);
+    const basePath = `/teams/${encodeURIComponent(teamId)}/channels/${encodeURIComponent(channelId)}/messages`;
+    const path = replyToMessageId
+        ? `${basePath}/${encodeURIComponent(replyToMessageId)}/replies`
+        : basePath;
+    const message = await graphRequest({
+        method: 'POST',
+        path,
+        token,
+        resourceType: 'Teams channel',
+        body: {
+            body: {
+                contentType,
+                content: text,
+            },
+        },
+    });
+    return {
+        success: true,
+        message_id: message?.id ?? '',
+        web_url: message?.webUrl ?? '',
+        created_at: message?.createdDateTime ?? '',
+    };
+}

package/tools/ms_send_teams_message/ms_send_teams_message.ts

@@ -5,8 +5,12 @@
  *   Reply:        POST /teams/{team-id}/channels/{channel-id}/messages/{message-id}/replies
  *                 https://learn.microsoft.com/en-us/graph/api/chatmessage-post-replies
  */
-import { MatimoError, ErrorCode } from '@matimo/core';
-import { getAccessToken, requireParams, graphRequest, type ToolContext } from '../graph-client';
+import { MatimoError, ErrorCode } from '@matimo/core/runtime';
+import { getAccessToken, requireParams, graphRequest } from '../graph-client.js';
+
+interface ToolContext {
+  credentials?: Record<string, string>;
+}
 
 const VALID_CONTENT_TYPES = ['text', 'html'];