Self-improving AI Employees for everyone
Python ai-agentsai-employeeai-employeesassistantautonomous-agentsco-employeescompanygrok-botinstinctloop-agentsmuseown-your-datapersonalself-hosted
"""Shared helpers for Microsoft Graph plugins.
Every Microsoft plugin follows the same pattern:
ensure a fresh access token -> ctx.connection("microsoft").<verb>(url)
-> response.json() -> track usage -> return Output
``graph_request`` captures the token-freshness + base-URL + error
handling so each ``@Operation`` shrinks to the Graph-specific call +
argument shaping. Graph is plain bearer REST, so — unlike Google — no
SDK object is built; the :class:`Connection` facade injects the token
and retries once on 401/403.
"""
from __future__ import annotations
from typing import Any, Dict, Optional
import httpx
from core.logging import get_logger
from services.plugin import NodeUserError
from services.pricing import get_pricing_service
from ._auth_helper import ensure_fresh_microsoft_token
logger = get_logger(__name__)
GRAPH_BASE_URL = "https://graph.microsoft.com/v1.0"
def mailbox_base(mailbox: Optional[str] = None) -> str:
"""Return the Graph path prefix for the target mailbox.
Empty / None -> ``/me`` (the signed-in user's own mailbox, unchanged
behaviour). A shared/other mailbox address -> ``/users/{address}``.
Accessing another mailbox over the delegated flow requires the caller
to have been granted Full Access (and Send As, to send) on it, plus the
``.Shared`` OAuth scopes (Mail.ReadWrite.Shared / Mail.Send.Shared /
Calendars.ReadWrite.Shared) — see microsoft_apis.json.
"""
addr = (mailbox or "").strip()
if not addr:
return "/me"
# Guard against a path-breaking value; the address becomes a URL segment.
if "/" in addr or " " in addr:
raise NodeUserError(f"Invalid mailbox address: {addr!r}")
return f"/users/{addr}"
async def graph_request(
ctx,
method: str,
path: str,
*,
params: Optional[Dict[str, Any]] = None,
json: Optional[Any] = None,
) -> Optional[Dict[str, Any]]:
"""Issue an authed Microsoft Graph request.
Args:
ctx: NodeContext (provides the Connection factory + user_id).
method: HTTP verb.
path: Graph path beginning with ``/`` (appended to ``GRAPH_BASE_URL``),
or an absolute URL (used verbatim, e.g. an ``@odata.nextLink``).
params: Query string params.
json: JSON request body.
Returns:
Parsed JSON dict, or ``None`` for empty-body responses (e.g. 202
from sendMail, 204 from delete).
Raises:
NodeUserError: on a non-2xx Graph response, carrying Graph's own
error message so the user/LLM can correct the input.
"""
# Guarantee the STORED access token is fresh before the Connection
# facade resolves + injects it (get_oauth_tokens does not refresh).
await ensure_fresh_microsoft_token(getattr(ctx, "user_id", "owner"))
url = path if path.startswith("http") else f"{GRAPH_BASE_URL}{path}"
async with ctx.connection("microsoft") as conn:
response = await conn.request(method, url, params=params, json=json)
if response.status_code >= 400:
raise NodeUserError(_format_graph_error(response))
if response.status_code == 204 or not response.content:
return None
try:
return response.json()
except (ValueError, httpx.DecodingError):
return None
async def graph_get_raw(
path: str,
*,
params: Optional[Dict[str, Any]] = None,
user_id: str = "owner",
) -> Dict[str, Any]:
"""Authed Graph GET for contexts without a NodeContext / Connection.
The polling-trigger hooks (``fetch_ids`` / ``fetch_detail``) run inside
the deployment loop and the Temporal poll activity — neither has a
``ctx`` to source the :class:`Connection` factory from. This helper
resolves a fresh token via :func:`ensure_fresh_microsoft_token` and
issues a plain httpx GET with the bearer header.
Raises:
NodeUserError: on a non-2xx Graph response.
"""
token = await ensure_fresh_microsoft_token(user_id)
url = path if path.startswith("http") else f"{GRAPH_BASE_URL}{path}"
async with httpx.AsyncClient(timeout=30.0) as client:
response = await client.get(url, params=params, headers={"Authorization": f"Bearer {token}"})
if response.status_code >= 400:
raise NodeUserError(_format_graph_error(response))
if not response.content:
return {}
try:
return response.json()
except (ValueError, httpx.DecodingError):
return {}
async def mark_message_read_raw(message_id: str, *, mailbox: Optional[str] = None, user_id: str = "owner") -> None:
"""PATCH a message's ``isRead`` flag to true (ctx-free; best-effort caller).
``mailbox`` targets a shared/other mailbox (``/users/{addr}``); empty = ``/me``.
"""
token = await ensure_fresh_microsoft_token(user_id)
url = f"{GRAPH_BASE_URL}{mailbox_base(mailbox)}/messages/{message_id}"
async with httpx.AsyncClient(timeout=30.0) as client:
await client.patch(url, json={"isRead": True}, headers={"Authorization": f"Bearer {token}"})
def _format_graph_error(response: httpx.Response) -> str:
"""Extract Microsoft Graph's structured error message for a user-facing warning."""
try:
body = response.json()
except (ValueError, httpx.DecodingError):
body = None
if isinstance(body, dict):
err = body.get("error")
if isinstance(err, dict):
code = err.get("code", "")
message = err.get("message", "")
detail = f"{code}: {message}".strip(": ") if (code or message) else ""
if detail:
return f"Microsoft Graph error ({response.status_code}): {detail}"
return f"Microsoft Graph request failed with HTTP {response.status_code}"
def write_attachment_bytes(payload, *, ctx, filename, mime_type=None):
"""Write attachment bytes into the workspace; return ``(FileRef, abs_path)``.
Mirrors ``services.media.workspace.write_audio``'s proven pattern
(workspace_root -> resolve_media -> atomic_write_bytes) but returns a
plain ``kind="file"`` :class:`FileRef` rather than an ``AudioRef`` — a PDF
is not audio and must never claim ``kind="audio"`` (that asserts an
``inspect_audio`` probe that never ran). Files land under
``<workspace>/attachments/`` with a random-suffixed name so retries and
repeated runs never collide or overwrite.
The absolute path is returned alongside the ref because the downstream
``documentParser`` node consumes a plain path string (``file_path`` /
``input_dir``), not a FileRef.
Raises:
NodeUserError: on empty payload.
"""
import hashlib
import mimetypes
from uuid import uuid4
from core.paths import safe_path_component
from nodes.filesystem._backend import atomic_write_bytes
from services.media.refs import FileRef
from services.media.workspace import _slugify, resolve_media, workspace_file_url, workspace_root
from services.plugin import NodeUserError
if not payload:
raise NodeUserError("Refusing to write an empty attachment file.")
root = workspace_root(ctx)
# Canvas node ids carry colons (``7:mail:1``), which Windows refuses in a file name.
node = safe_path_component(str(getattr(ctx, "node_id", "") or "node")[:8], "node")
workflow_id = getattr(ctx, "workflow_id", None)
# Preserve the real extension (documentParser globs on *.pdf); slugify the stem.
dot = filename.rfind(".") if filename else -1
stem = filename[:dot] if dot > 0 else (filename or "attachment")
ext = filename[dot + 1 :].lower() if dot > 0 else ""
safe = f"{_slugify(stem)}-{node}-{uuid4().hex[:6]}"
name = f"{safe}.{ext}" if ext else safe
rel = f"attachments/{name}"
target = resolve_media(rel, ctx=ctx)
target.parent.mkdir(parents=True, exist_ok=True)
atomic_write_bytes(target, payload, root_dir=root)
ref = FileRef(
kind="file",
path=rel,
workflow_id=workflow_id,
filename=filename or name,
mime_type=mime_type or mimetypes.guess_type(filename or name)[0] or "application/octet-stream",
size_bytes=len(payload),
sha256=hashlib.sha256(payload).hexdigest(),
url=workspace_file_url(workflow_id, rel),
)
return ref, str(target)
async def track_microsoft_usage(
node_id: str,
action: str,
resource_count: int,
context: Dict[str, Any],
) -> Dict[str, float]:
"""Record a Microsoft Graph call in ``api_usage_metrics``.
``action`` maps through ``pricing.json``'s ``microsoft_graph``
operation_map (send / read / search / reply / create / update /
delete / list). Graph is free at our tier — analytics bookkeeping,
cost is $0.
"""
from services.plugin.deps import get_database
pricing = get_pricing_service()
cost_data = pricing.calculate_api_cost("microsoft_graph", action, resource_count)
db = get_database()
await db.save_api_usage_metric(
{
"session_id": context.get("session_id", "default"),
"node_id": node_id,
"workflow_id": context.get("workflow_id"),
"service": "microsoft_graph",
"operation": cost_data.get("operation", action),
"endpoint": action,
"resource_count": resource_count,
"cost": cost_data.get("total_cost", 0.0),
}
)
return cost_data