# @kody/microsoft — agent notes Human setup and intent live in [`README.md`](./README.md). This file is for agents: imports, smoke/dryRun execute snippets, and edge cases. OAuth by **name** only — never paste tokens or client secrets. Do not disable live webhooks or jobs. ## Auth | Call | Resolves to | | --- | --- | | omit / `account: 'default'` | `microsoft` | | `account: 'work'` | `microsoft-work` | | `integration: 'microsoft-work'` | that exact OAuth name | | value already `microsoft-*` | used as-is | OAuth only. Hosts: `graph.microsoft.com`, `login.microsoftonline.com`. API base: `https://graph.microsoft.com/v1.0`. ## Import paths | Export | Import | | --- | --- | | overview + `smokeTest` | `kody:@kody/microsoft` | | accounts | `kody:@kody/microsoft/accounts` | | smoke-test | `kody:@kody/microsoft/smoke-test` | | scopes | `kody:@kody/microsoft/scopes` | | core | `kody:@kody/microsoft/core` | | mail | `kody:@kody/microsoft/mail` | | outlook (alias of mail) | `kody:@kody/microsoft/outlook` | | calendar | `kody:@kody/microsoft/calendar` | | todo | `kody:@kody/microsoft/todo` | | onedrive | `kody:@kody/microsoft/onedrive` | | teams | `kody:@kody/microsoft/teams` | | request | `kody:@kody/microsoft/request` | | types | `kody:@kody/microsoft/types` | Prefer static `kody:@kody/microsoft/...` imports from `execute`. Do not lead with `packages.invoke`. Named helpers re-export from product modules (`listMessages`, `sendMail`, `listEvents`, `listJoinedTeams`, …). ## Smoke test (read-only) ```ts import smokeTest from 'kody:@kody/microsoft/smoke-test' export default async function main() { return await smokeTest() // => { ok: true, integration: 'microsoft', id, displayName, mail, userPrincipalName } } ``` Missing integration errors name OAuth (not API key / bot token) and include the `/connect/oauth` URL. A Graph 403 names `User.Read` and the reconnect URL. ## Common snippets ```ts import { listMessages } from 'kody:@kody/microsoft/mail' export default async function main() { return await listMessages({ top: 5 }) } ``` ```ts import { listEvents } from 'kody:@kody/microsoft/calendar' export default async function main() { return await listEvents({ account: 'work', startDateTime: '2026-08-22T00:00:00Z', endDateTime: '2026-08-23T00:00:00Z', }) } ``` Escape hatch: ```ts import request from 'kody:@kody/microsoft/request' export default async function main() { return await request({ path: '/me', query: { $select: 'id,displayName' }, }) } ``` ## dryRun / confirm Mutations (`sendMail`, `createReplyDraft`, `createEvent`, `updateEvent`, `createTask`, `sendChatMessage`, `sendChannelMessage`, and non-GET `request`) require `confirm: true`. Pass `dryRun: true` to preview without calling Graph. ```ts import { sendMail } from 'kody:@kody/microsoft/mail' export default async function main() { return await sendMail({ subject: 'Status update', body: 'Shipped the Microsoft helpers package.', to: 'teammate@example.com', dryRun: true, }) } ``` After the user approves the exact recipients + body, retry with `confirm: true` (not only `dryRun: false`). ## Edge cases - `MicrosoftGraphError` on 403 includes path, integration, likely scope, admin- consent hint, and reconnect URL — reconnect after every Azure scope change. - Do not hide Teams / mail / calendar helpers when a scope is missing. - Never paste Graph access tokens into `/account/secrets/new`. - No hard-coded person or brand account aliases.