Skip to content
← Public packages

@kody/microsoft

Microsoft 365 helpers for Outlook, Calendar, To Do, OneDrive, and Teams.

FollowFork

Files

AGENTS.md

119 lines · 3.4 KB · Markdown

@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

CallResolves 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

ExportImport
overview + smokeTestkody:@kody/microsoft
accountskody:@kody/microsoft/accounts
smoke-testkody:@kody/microsoft/smoke-test
scopeskody:@kody/microsoft/scopes
corekody:@kody/microsoft/core
mailkody:@kody/microsoft/mail
outlook (alias of mail)kody:@kody/microsoft/outlook
calendarkody:@kody/microsoft/calendar
todokody:@kody/microsoft/todo
onedrivekody:@kody/microsoft/onedrive
teamskody:@kody/microsoft/teams
requestkody:@kody/microsoft/request
typeskody:@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

  • 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.