matimo-microsoft 0.1.0__py3-none-any.whl

matimo_microsoft/__init__.py

@@ -0,0 +1,17 @@
+"""Matimo microsoft provider — exposes the path to YAML tool definitions."""
+from __future__ import annotations
+
+import importlib.resources
+from pathlib import Path
+
+
+def get_tools_path() -> str:
+    """Return the absolute path to the bundled microsoft tool definitions."""
+    try:
+        ref = importlib.resources.files("matimo_microsoft") / "tools"
+        return str(ref)
+    except Exception:
+        return str(Path(__file__).parent / "tools")
+
+
+__all__ = ["get_tools_path"]

matimo_microsoft/graph_client.py

@@ -0,0 +1,236 @@
+"""
+Shared Microsoft Graph helpers for all 'type: function' tools in this package.
+Mirrors: typescript/packages/microsoft/tools/graph-client.ts
+
+Conventions (mirrors matimo-slack and matimo-gmail):
+- Tools NEVER perform OAuth token exchange. A delegated Graph access token is
+  injected at execution time via params['MICROSOFT_GRAPH_ACCESS_TOKEN'] (merged
+  from credentials by the function executor) 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 matimo.errors).
+- Unlike the TypeScript executor, Python's MatimoInstance.execute() re-raises
+  MatimoError rather than converting it to {success: False} — every failure path
+  here raises directly.
+"""
+from __future__ import annotations
+
+import asyncio
+import os
+from typing import Any, Literal
+
+import httpx
+
+from matimo.errors import ErrorCode, MatimoError
+
+GRAPH_BASE_URL = "https://graph.microsoft.com/v1.0"
+
+_RETRYABLE_STATUS_CODES = {429, 500, 503}
+_MAX_RETRIES = 3
+_INITIAL_BACKOFF_S = 0.5
+
+HttpMethod = Literal["GET", "POST", "PUT", "PATCH", "DELETE"]
+ResponseType = Literal["json", "bytes"]
+
+
+def get_access_token(params: dict[str, Any]) -> str:
+    """
+    Resolve the delegated Graph access token. Matimo never exchanges OAuth codes —
+    the token must already be present in the merged params (credentials) or the
+    environment.
+    """
+    token = params.get("MICROSOFT_GRAPH_ACCESS_TOKEN") or os.environ.get(
+        "MICROSOFT_GRAPH_ACCESS_TOKEN"
+    )
+
+    if not token:
+        raise 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 str(token)
+
+
+def require_params(params: dict[str, Any], required: list[str], tool_name: str) -> None:
+    """
+    Validate required parameters BEFORE any network call, mirroring the
+    "ValidationError before any API call" requirement. Raises VALIDATION_FAILED.
+    """
+    missing = [name for name in required if params.get(name) in (None, "")]
+
+    if missing:
+        raise MatimoError(
+            f"{tool_name}: missing required parameter(s): {', '.join(missing)}",
+            ErrorCode.VALIDATION_FAILED,
+            {"toolName": tool_name, "missingParams": missing},
+        )
+
+
+def _parse_retry_after_seconds(retry_after_header: str | None) -> float | None:
+    """
+    Parse a `Retry-After` header into delta-seconds, returning None when it's
+    absent or not a numeric delay. Per RFC 9110 §10.2.3, `Retry-After` MAY be
+    an HTTP-date instead of delta-seconds — float() raises ValueError on that
+    (unlike JS's Number(), which yields NaN), so the conversion must be guarded
+    to avoid crashing error mapping for 429 responses.
+    """
+    if retry_after_header is None:
+        return None
+    try:
+        return float(retry_after_header)
+    except (TypeError, ValueError):
+        return None
+
+
+def map_graph_error(
+    status: int,
+    data: Any,
+    headers: httpx.Headers | dict[str, str] | None,
+    resource_type: str,
+) -> MatimoError:
+    """
+    Map a Microsoft Graph HTTP error response onto a MatimoError using the closest
+    matching ErrorCode (Matimo has no CredentialError/NotFoundError/ProviderError
+    classes — see matimo.errors):
+      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
+    """
+    graph_error = data.get("error") if isinstance(data, dict) else None
+    details: dict[str, Any] = {"statusCode": status, "graphError": graph_error, "resourceType": resource_type}
+
+    if status in (401, 403):
+        return MatimoError(
+            "Microsoft Graph access denied. Check connection status in Nova.",
+            ErrorCode.AUTH_FAILED,
+            details,
+        )
+
+    if status == 404:
+        return MatimoError(f"{resource_type} not found.", ErrorCode.FILE_NOT_FOUND, details)
+
+    if status == 429:
+        retry_after_header = None
+        if headers is not None:
+            retry_after_header = headers.get("retry-after") or headers.get("Retry-After")
+        retry_after_seconds = _parse_retry_after_seconds(retry_after_header)
+        return MatimoError(
+            "Microsoft Graph rate limit exceeded. Respect Retry-After before retrying.",
+            ErrorCode.RATE_LIMIT_EXCEEDED,
+            {**details, "retryAfterSeconds": retry_after_seconds},
+        )
+
+    if status in (500, 503):
+        return MatimoError(
+            "Microsoft Graph service is temporarily unavailable. Please retry shortly.",
+            ErrorCode.EXECUTION_FAILED,
+            details,
+        )
+
+    return MatimoError(
+        f"Microsoft Graph request failed with status {status}.",
+        ErrorCode.EXECUTION_FAILED,
+        details,
+    )
+
+
+async def graph_request(
+    *,
+    method: HttpMethod,
+    path: str,
+    token: str,
+    query: dict[str, Any] | None = None,
+    body: Any = None,
+    headers: dict[str, str] | None = None,
+    resource_type: str = "Resource",
+    response_type: ResponseType = "json",
+    allow_empty_response: bool = False,
+) -> Any:
+    """
+    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.
+
+    Args:
+        path: Path relative to https://graph.microsoft.com/v1.0, e.g. '/me/messages'
+        response_type: 'bytes' for binary downloads (e.g. file content)
+        allow_empty_response: Treat a 204/empty body as success and return None
+            (e.g. publish, sendMail)
+    """
+    url = f"{GRAPH_BASE_URL}{path}"
+
+    is_json_body = body is not None and not isinstance(body, (bytes, bytearray))
+    request_headers: dict[str, str] = {
+        "Authorization": f"Bearer {token}",
+        **({"Accept": "application/json"} if response_type == "json" else {}),
+        **({"Content-Type": "application/json"} if is_json_body else {}),
+        **(headers or {}),
+    }
+
+    request_kwargs: dict[str, Any] = {}
+    if isinstance(body, (bytes, bytearray)):
+        request_kwargs["content"] = bytes(body)
+    elif body is not None:
+        request_kwargs["json"] = body
+
+    filtered_query = {
+        key: value
+        for key, value in (query or {}).items()
+        if value is not None and value != ""
+    }
+
+    attempt = 0
+    async with httpx.AsyncClient(timeout=30.0) as client:
+        while True:
+            try:
+                response = await client.request(
+                    method,
+                    url,
+                    params=filtered_query or None,
+                    headers=request_headers,
+                    **request_kwargs,
+                )
+            except httpx.HTTPError as exc:
+                raise MatimoError(
+                    "Microsoft Graph request failed before a response was received (network error).",
+                    ErrorCode.NETWORK_ERROR,
+                    {"path": path, "originalError": str(exc)},
+                    cause=exc,
+                ) from exc
+
+            if 200 <= response.status_code < 300:
+                if allow_empty_response and (response.status_code == 204 or not response.content):
+                    return None
+                if response_type == "bytes":
+                    return response.content
+                if not response.content:
+                    return None
+                return response.json()
+
+            try:
+                error_body: Any = response.json()
+            except ValueError:
+                error_body = None
+
+            error = map_graph_error(response.status_code, error_body, response.headers, resource_type)
+
+            is_retryable = response.status_code in _RETRYABLE_STATUS_CODES and attempt < _MAX_RETRIES
+            if not is_retryable:
+                raise error
+
+            retry_after_seconds = error.details.get("retryAfterSeconds") if error.details else None
+            delay_s = (
+                retry_after_seconds
+                if isinstance(retry_after_seconds, (int, float))
+                else _INITIAL_BACKOFF_S * (2**attempt)
+            )
+
+            attempt += 1
+            await asyncio.sleep(delay_s)

matimo_microsoft/tools/ms_create_calendar_event/definition.yaml

@@ -0,0 +1,100 @@
+name: ms_create_calendar_event
+description: |
+  Create an event on the signed-in user's default calendar (POST /me/events).
+  Supports attendees, location, a single IANA/Windows time zone for both start and
+  end, and Microsoft Teams online meetings (isOnlineMeeting), returning the meeting's
+  join URL when one is created.
+version: '1.0.0'
+status: approved
+risk: medium
+
+parameters:
+  subject:
+    type: string
+    description: Title of the event
+    required: true
+
+  body:
+    type: string
+    description: Description / agenda for the event (plain text)
+    required: false
+
+  start:
+    type: string
+    description: 'Start date and time, e.g. "2026-06-15T09:00:00"'
+    required: true
+
+  end:
+    type: string
+    description: 'End date and time, e.g. "2026-06-15T09:30:00"'
+    required: true
+
+  timezone:
+    type: string
+    description: 'IANA or Windows time zone applied to both `start` and `end`, e.g. "America/Los_Angeles"'
+    required: false
+    default: UTC
+
+  attendees:
+    type: array
+    description: Email addresses of attendees to invite
+    required: false
+
+  location:
+    type: string
+    description: Free-text location / room name for the event
+    required: false
+
+  is_online_meeting:
+    type: boolean
+    description: When true, Microsoft Teams creates an online meeting for this event
+    required: false
+    default: false
+
+execution:
+  type: function
+  code: ./ms_create_calendar_event.py
+  timeout: 25000
+
+authentication:
+  type: oauth2
+  provider: microsoft
+  scopes:
+    - https://graph.microsoft.com/Calendars.ReadWrite
+
+output_schema:
+  type: object
+  properties:
+    success:
+      type: boolean
+    event_id:
+      type: string
+    web_link:
+      type: string
+    join_url:
+      type: string
+      description: Microsoft Teams meeting join URL — present only when is_online_meeting is true
+
+error_handling:
+  retry: 1
+  backoff_type: exponential
+  initial_delay_ms: 1000
+
+tags: [microsoft, graph, calendar, outlook, teams, write]
+
+examples:
+  - name: Schedule a 30-minute internal sync
+    params:
+      subject: 'Sprint planning'
+      start: '2026-06-15T09:00:00'
+      end: '2026-06-15T09:30:00'
+      timezone: 'America/Los_Angeles'
+      attendees: ['alice@contoso.com', 'bob@contoso.com']
+  - name: Schedule an online Teams meeting with a location fallback
+    params:
+      subject: 'All-hands'
+      start: '2026-06-20T17:00:00'
+      end: '2026-06-20T18:00:00'
+      timezone: UTC
+      location: 'Building 4, Room 200'
+      is_online_meeting: true

matimo_microsoft/tools/ms_create_calendar_event/ms_create_calendar_event.py

@@ -0,0 +1,81 @@
+"""
+ms_create_calendar_event — POST /me/events
+https://learn.microsoft.com/en-us/graph/api/user-post-events
+Mirrors: typescript/packages/microsoft/tools/ms_create_calendar_event/ms_create_calendar_event.ts
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from matimo.errors import ErrorCode, MatimoError
+from matimo_microsoft.graph_client import get_access_token, graph_request, require_params
+
+_DEFAULT_TIMEZONE = "UTC"
+
+
+def _to_attendee_list(value: Any) -> list[dict[str, Any]]:
+    if value is None:
+        return []
+    if not isinstance(value, list) or any(not isinstance(entry, str) or not entry for entry in value):
+        raise MatimoError(
+            "ms_create_calendar_event: 'attendees' must be an array of email address strings",
+            ErrorCode.VALIDATION_FAILED,
+            {"attendees": value},
+        )
+    return [{"emailAddress": {"address": address}, "type": "required"} for address in value]
+
+
+async def run(params: dict[str, Any]) -> dict[str, Any]:
+    require_params(params, ["subject", "start", "end"], "ms_create_calendar_event")
+
+    subject = str(params["subject"])
+    start = str(params["start"])
+    end = str(params["end"])
+    timezone_param = params.get("timezone")
+    timezone = timezone_param if isinstance(timezone_param, str) and timezone_param else _DEFAULT_TIMEZONE
+
+    attendees = _to_attendee_list(params.get("attendees"))
+    is_online_meeting = params.get("is_online_meeting") is True
+
+    token = get_access_token(params)
+
+    body_param = params.get("body")
+    location_param = params.get("location")
+
+    event_body: dict[str, Any] = {
+        "subject": subject,
+        **(
+            {"body": {"contentType": "Text", "content": body_param}}
+            if isinstance(body_param, str) and body_param
+            else {}
+        ),
+        "start": {"dateTime": start, "timeZone": timezone},
+        "end": {"dateTime": end, "timeZone": timezone},
+        **({"attendees": attendees} if attendees else {}),
+        **(
+            {"location": {"displayName": location_param}}
+            if isinstance(location_param, str) and location_param
+            else {}
+        ),
+        "isOnlineMeeting": is_online_meeting,
+        **({"onlineMeetingProvider": "teamsForBusiness"} if is_online_meeting else {}),
+    }
+
+    event = await graph_request(
+        method="POST",
+        path="/me/events",
+        token=token,
+        resource_type="Calendar",
+        body=event_body,
+    )
+    event = event if isinstance(event, dict) else {}
+
+    online_meeting = event.get("onlineMeeting") or {}
+    join_url = online_meeting.get("joinUrl")
+
+    return {
+        "success": True,
+        "event_id": event.get("id") or "",
+        "web_link": event.get("webLink") or "",
+        **({"join_url": join_url} if join_url else {}),
+    }

matimo_microsoft/tools/ms_create_document/definition.yaml

@@ -0,0 +1,103 @@
+name: ms_create_document
+description: |
+  Create (or overwrite) a small file in OneDrive or a SharePoint document library by
+  uploading content directly
+  (PUT /drives/{drive_id}/items/{parent_item_id}:/{filename}:/content). Intended for
+  small text-based documents — Microsoft Graph requires resumable upload sessions for
+  files larger than 4 MB, which this tool does not implement.
+version: '1.0.0'
+status: approved
+risk: medium
+
+parameters:
+  drive_id:
+    type: string
+    description: ID of the destination drive (OneDrive or SharePoint document library)
+    required: true
+
+  parent_item_id:
+    type: string
+    description: ID of the destination folder item. Defaults to the drive's root folder.
+    required: false
+    default: root
+
+  filename:
+    type: string
+    description: 'Name to give the new file, including extension, e.g. "report.md"'
+    required: true
+
+  content:
+    type: string
+    description: File content. Provide as plain text, or as base64 when content_encoding is "base64"
+    required: true
+
+  content_encoding:
+    type: string
+    description: How `content` is encoded
+    required: false
+    default: text
+    enum: [text, base64]
+
+  conflict_behaviour:
+    type: string
+    description: >-
+      How to handle a name collision with an existing item. Passed as the
+      @microsoft.graph.conflictBehavior query hint on a best-effort basis — Graph's
+      simple-upload (PUT .../content) endpoint documents this parameter primarily for
+      resumable upload sessions, so behaviour may vary by tenant/library configuration.
+    required: false
+    default: replace
+    enum: [replace, rename, fail]
+
+execution:
+  type: function
+  code: ./ms_create_document.py
+  timeout: 30000
+
+authentication:
+  type: oauth2
+  provider: microsoft
+  scopes:
+    - https://graph.microsoft.com/Files.ReadWrite
+
+output_schema:
+  type: object
+  properties:
+    success:
+      type: boolean
+    item_id:
+      type: string
+    name:
+      type: string
+    web_url:
+      type: string
+    size_bytes:
+      type: number
+
+error_handling:
+  retry: 1
+  backoff_type: exponential
+  initial_delay_ms: 1000
+
+tags: [microsoft, graph, files, onedrive, sharepoint, write]
+
+examples:
+  - name: Create a Markdown summary document at the drive root
+    params:
+      drive_id: 'b!xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
+      filename: 'meeting-notes-2026-06-07.md'
+      content: '# Meeting notes\n\n- Decided to ship v2.4.0 next week'
+  - name: Upload a base64-encoded file into a specific folder
+    params:
+      drive_id: 'b!xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
+      parent_item_id: '01ABCXYZ7654321'
+      filename: 'export.csv'
+      content: 'bmFtZSxlbWFpbAphbGljZSxhbGljZUBjb250b3NvLmNvbQ=='
+      content_encoding: base64
+      conflict_behaviour: rename
+
+notes:
+  caution: >-
+    Uses the simple-upload endpoint, which Microsoft Graph limits to files up to
+    4 MB. Larger files require a resumable upload session
+    (createUploadSession), which this tool does not implement.

matimo_microsoft/tools/ms_create_document/ms_create_document.py

@@ -0,0 +1,106 @@
+"""
+ms_create_document — PUT /drives/{drive-id}/items/{parent-item-id}:/{filename}:/content
+https://learn.microsoft.com/en-us/graph/api/driveitem-put-content
+Mirrors: typescript/packages/microsoft/tools/ms_create_document/ms_create_document.ts
+
+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.
+"""
+from __future__ import annotations
+
+import base64
+import binascii
+from typing import Any
+from urllib.parse import quote
+
+from matimo.errors import ErrorCode, MatimoError
+from matimo_microsoft.graph_client import get_access_token, graph_request, require_params
+
+_VALID_ENCODINGS = ["text", "base64"]
+_VALID_CONFLICT_BEHAVIOURS = ["replace", "rename", "fail"]
+_DEFAULT_PARENT_ITEM_ID = "root"
+_MAX_UPLOAD_BYTES = 4 * 1024 * 1024
+
+
+async def run(params: dict[str, Any]) -> dict[str, Any]:
+    require_params(params, ["drive_id", "filename", "content"], "ms_create_document")
+
+    drive_id = str(params["drive_id"])
+    parent_item_id_param = params.get("parent_item_id")
+    parent_item_id = (
+        parent_item_id_param
+        if isinstance(parent_item_id_param, str) and parent_item_id_param
+        else _DEFAULT_PARENT_ITEM_ID
+    )
+    filename = str(params["filename"])
+
+    encoding_param = params.get("content_encoding")
+    encoding = "text" if encoding_param is None else str(encoding_param)
+    if encoding not in _VALID_ENCODINGS:
+        raise MatimoError(
+            f"ms_create_document: 'content_encoding' must be one of {', '.join(_VALID_ENCODINGS)} "
+            f"(received '{encoding}')",
+            ErrorCode.VALIDATION_FAILED,
+            {"content_encoding": encoding_param},
+        )
+
+    conflict_param = params.get("conflict_behaviour")
+    conflict_behaviour = "replace" if conflict_param is None else str(conflict_param)
+    if conflict_behaviour not in _VALID_CONFLICT_BEHAVIOURS:
+        raise MatimoError(
+            f"ms_create_document: 'conflict_behaviour' must be one of {', '.join(_VALID_CONFLICT_BEHAVIOURS)} "
+            f"(received '{conflict_behaviour}')",
+            ErrorCode.VALIDATION_FAILED,
+            {"conflict_behaviour": conflict_param},
+        )
+
+    raw_content = str(params["content"])
+    if encoding == "base64":
+        # Mirror Node's lenient Buffer.from(str, 'base64'), which decodes whatever
+        # it can rather than throwing on malformed input — pad out to a multiple
+        # of 4 and ignore decode errors from stray characters.
+        padded = raw_content + "=" * (-len(raw_content) % 4)
+        try:
+            buffer = base64.b64decode(padded, validate=False)
+        except (binascii.Error, ValueError):
+            buffer = b""
+    else:
+        buffer = raw_content.encode("utf-8")
+
+    if len(buffer) > _MAX_UPLOAD_BYTES:
+        raise MatimoError(
+            f"ms_create_document: content is {len(buffer)} bytes, exceeding the "
+            f"{_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": len(buffer), "maxBytes": _MAX_UPLOAD_BYTES},
+        )
+
+    token = get_access_token(params)
+
+    # By-path addressing uses literal colons as delimiters — only the path SEGMENTS
+    # (drive id, parent item id, filename) are percent-encoded, not the colons.
+    path = (
+        f"/drives/{quote(drive_id, safe='')}/items/{quote(parent_item_id, safe='')}"
+        f":/{quote(filename, safe='')}:/content"
+    )
+
+    item = await graph_request(
+        method="PUT",
+        path=path,
+        token=token,
+        resource_type="Drive folder",
+        query={"@microsoft.graph.conflictBehavior": conflict_behaviour},
+        body=buffer,
+        headers={"Content-Type": "application/octet-stream"},
+    )
+    item = item if isinstance(item, dict) else {}
+
+    return {
+        "success": True,
+        "item_id": item.get("id") or "",
+        "name": item.get("name") or filename,
+        "web_url": item.get("webUrl") or "",
+        "size_bytes": item.get("size") or len(buffer),
+    }