{"_id":"@circuitwall/ms-todo-langchain","name":"@circuitwall/ms-todo-langchain","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@circuitwall/ms-todo-langchain","version":"0.1.0","description":"LangChain tools for Microsoft To Do (Microsoft Graph /me/todo) — direct REST calls, no MCP. Extracted from Jarela.","license":"Apache-2.0","author":{"name":"Andrew Ge Wu"},"homepage":"https://github.com/CircuitWall/jarela/tree/main/packages/ms-todo-langchain#readme","repository":{"type":"git","url":"git+https://github.com/CircuitWall/jarela.git","directory":"packages/ms-todo-langchain"},"bugs":{"url":"https://github.com/CircuitWall/jarela/issues"},"keywords":["microsoft","ms-todo","todo","tasks","microsoft-graph","langchain","langgraph","tool","tools","agent","outlook"],"type":"module","main":"./dist/index.cjs","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"},"./package.json":"./package.json"},"publishConfig":{"access":"public","registry":"https://registry.npmjs.org"},"engines":{"node":">=20"},"scripts":{"build":"tsup","clean":"rimraf dist","test":"vitest run","typecheck":"tsc --noEmit"},"peerDependencies":{"@langchain/core":">=0.3.0","zod":">=3.23.0 <5"},"devDependencies":{"@langchain/core":"^1.1.46","rimraf":"^6.0.1","tsup":"^8.3.5","typescript":"^5.7.2","vitest":"^4.1.7","zod":"^3.25.0"},"gitHead":"aed413324531a175d6788f1bde4cc4eea42b5871","_id":"@circuitwall/ms-todo-langchain@0.1.0","_nodeVersion":"24.14.0","_npmVersion":"11.9.0","dist":{"integrity":"sha512-6i8OoFjn0AtN172YoO5Njohlm4teW3+7ZTi/kQmfxx5e+D1qpyVrjcj/BEp8OSFYMzYRhLiARSBVxD48pWMxUA==","shasum":"26342b021186a3d11e70d05cd0a8177511980f2b","tarball":"https://registry.npmjs.org/@circuitwall/ms-todo-langchain/-/ms-todo-langchain-0.1.0.tgz","fileCount":10,"unpackedSize":202671,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDUfsD7pc6TRYaTq9MKPUuek+agEaVbbW9qtHpDtesiugIhAO+pnt0oeznZPD7Ya2h12dYzMe+03CDL18MhR8545HIG"}]},"_npmUser":{"name":"andrew-ge-wu","email":"andrew.ge.wu@gmail.com"},"directories":{},"maintainers":[{"name":"andrew-ge-wu","email":"andrew.ge.wu@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/ms-todo-langchain_0.1.0_1781637656215_0.5910430341806658"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-16T19:20:56.034Z","0.1.0":"2026-06-16T19:20:56.344Z","modified":"2026-06-16T19:20:56.656Z"},"maintainers":[{"name":"andrew-ge-wu","email":"andrew.ge.wu@gmail.com"}],"description":"LangChain tools for Microsoft To Do (Microsoft Graph /me/todo) — direct REST calls, no MCP. Extracted from Jarela.","homepage":"https://github.com/CircuitWall/jarela/tree/main/packages/ms-todo-langchain#readme","keywords":["microsoft","ms-todo","todo","tasks","microsoft-graph","langchain","langgraph","tool","tools","agent","outlook"],"repository":{"type":"git","url":"git+https://github.com/CircuitWall/jarela.git","directory":"packages/ms-todo-langchain"},"author":{"name":"Andrew Ge Wu"},"bugs":{"url":"https://github.com/CircuitWall/jarela/issues"},"license":"Apache-2.0","readme":"# @circuitwall/ms-todo-langchain\r\n\r\nLangChain tools for **Microsoft To Do** via the Microsoft Graph\r\n(`/me/todo`) — direct REST calls, no MCP, no Graph SDK, no extra\r\nprocesses.\r\n\r\n> Extracted from [Jarela](https://github.com/CircuitWall/jarela). Works in\r\n> any Node 20+ LangChain.js / LangGraph project. Inherits whatever HTTP\r\n> proxy + CA bundle the host runtime configures, so it works on\r\n> locked-down corp networks where the MCP install path is blocked.\r\n\r\n## Install\r\n\r\n```bash\r\nnpm install @circuitwall/ms-todo-langchain @langchain/core zod\r\n```\r\n\r\n`@langchain/core` and `zod` are peer dependencies — bring your own\r\nversion.\r\n\r\n## Quick start\r\n\r\n```ts\r\nimport {\r\n  setAuthResolver,\r\n  msTodoListListsTool,\r\n  msTodoCreateTaskTool,\r\n  msTodoTools,\r\n} from \"@circuitwall/ms-todo-langchain\";\r\n\r\n// Option A: rely on env vars. The package will run the OAuth refresh\r\n// flow internally on every call (cached for the token's lifetime).\r\n//\r\n//   MS_TODO_CLIENT_ID=<azure app client id>\r\n//   MS_TODO_CLIENT_SECRET=<azure app client secret>\r\n//   MS_TODO_REFRESH_TOKEN=<delegated refresh_token with Tasks.ReadWrite + offline_access>\r\n//   MS_TODO_TENANT=common   # optional; \"common\" works for personal + M365\r\n//\r\n// Or, for short-lived script use, MS_TODO_ACCESS_TOKEN.\r\n\r\n// Option B: plug in your own credential source (vault, UI form, an\r\n// embedder that already runs the refresh flow elsewhere).\r\nsetAuthResolver(async () => ({ access_token: await mintAccessToken() }));\r\n\r\n// Use individual tools …\r\nconst lists = await msTodoListListsTool.invoke({});\r\n\r\n// … or pass the whole array to a LangGraph agent.\r\nconst agent = await createReactAgent({ llm, tools: [...msTodoTools] });\r\n```\r\n\r\n## What's in the box\r\n\r\n12 tools covering the Microsoft To Do surface of Microsoft Graph.\r\n\r\n### Task lists\r\n- `ms_todo_list_lists`\r\n- `ms_todo_create_list`\r\n- `ms_todo_update_list`\r\n- `ms_todo_delete_list`\r\n\r\n### Tasks\r\n- `ms_todo_list_tasks` — `$filter` on status / importance / due window\r\n- `ms_todo_get_task`\r\n- `ms_todo_create_task` — title, body, importance, due, reminder, categories\r\n- `ms_todo_update_task` — patch any subset; `clear_due` / `clear_reminder` to remove dates\r\n- `ms_todo_complete_task` — convenience: PATCH status='completed'\r\n- `ms_todo_delete_task`\r\n\r\n### Checklist sub-items\r\n- `ms_todo_list_checklist_items`\r\n- `ms_todo_add_checklist_item`\r\n\r\n## Capability groups\r\n\r\nFor tool-policy systems that need read / write partitions:\r\n\r\n```ts\r\nimport {\r\n  msTodoReadTools,    // 4 read-only tools\r\n  msTodoWriteTools,   // 8 mutating tools\r\n} from \"@circuitwall/ms-todo-langchain\";\r\n```\r\n\r\nThere is no `execute` bucket — Microsoft To Do has no irreversible\r\nside-effect operations beyond plain delete, which is in `write`.\r\n\r\n## Low-level escape hatch\r\n\r\nFor Graph endpoints not yet wrapped as tools:\r\n\r\n```ts\r\nimport { graphFetch } from \"@circuitwall/ms-todo-langchain\";\r\n\r\nconst data = await graphFetch(\"/me/todo/lists/<id>/tasks/<task-id>/attachments\");\r\n```\r\n\r\n`graphFetch` uses the same auth resolver as the tools, so plug in once\r\nand it works everywhere.\r\n\r\n## Auth — required Azure setup\r\n\r\n1. **Register an app** at\r\n   [portal.azure.com → Microsoft Entra ID → App registrations](https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps/ApplicationsListBlade).\r\n   Pick \"Accounts in any organizational directory and personal Microsoft\r\n   accounts\" for the broadest reach.\r\n2. **Add a Web redirect URI** that matches where your OAuth callback\r\n   listens.\r\n3. **API permissions → Microsoft Graph → Delegated permissions**, add:\r\n   - `Tasks.ReadWrite`\r\n   - `offline_access`\r\n4. **Certificates & secrets → New client secret**. Copy the **value**\r\n   immediately — Azure only shows it once.\r\n5. Run the OAuth2 authorization-code flow once to mint a\r\n   `refresh_token`. Pass `prompt=consent` and `scope=offline_access\r\n   Tasks.ReadWrite` to the\r\n   `https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize`\r\n   endpoint.\r\n\r\n## Notes\r\n\r\n- **Datetimes:** Graph rejects `Z`-suffixed strings on `dueDateTime` and\r\n  `reminderDateTime`. The package strips a trailing `Z` and defaults the\r\n  `timeZone` to `UTC`. Pass `due_time_zone` / `reminder_time_zone` for\r\n  any other IANA zone.\r\n- **Default list:** the user's main \"Tasks\" inbox shows up with\r\n  `wellknownListName: \"defaultList\"`. Its display name is locale-aware,\r\n  so always resolve by the well-known marker, not by name.\r\n- **Personal vs work accounts:** both work via the `common` tenant.\r\n  Microsoft To Do is fully available on personal accounts and M365.\r\n  Some Graph endpoints (e.g. Teams meetings) are work-only; To Do is\r\n  not one of them.\r\n- **Rate limits:** Graph applies a 10,000-requests-per-10-minutes per-app\r\n  budget for delegated calls. The package does not retry on 429 — you\r\n  should not hit it under normal agent use.\r\n\r\n## License\r\n\r\n[Apache-2.0](./LICENSE)\r\n","readmeFilename":"README.md","_rev":"1-f3de35347472209787d3ab11d14f149a"}