@kody/microsoft
Microsoft 365 helpers for Outlook, Calendar, To Do, OneDrive, and Teams.
Files
@kody/microsoft — agent notes
Human setup and intent live in 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 |
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)
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
import { listMessages } from 'kody:@kody/microsoft/mail'
export default async function main() {
return await listMessages({ top: 5 })
}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:
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.
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
MicrosoftGraphErroron 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.