OneNote CI Integration

Overview

Testing OneNote integrations in CI requires Azure AD app registration, credential management, and mock strategies for Graph API responses. This skill provides two proven CI strategies: mock-only PR checks (zero Azure credentials required) and nightly live integration tests with proper credential isolation and rate limit awareness.

Prerequisites

• GitHub Actions or equivalent CI platform
• Node.js 18+ or Python 3.10+
• For mock-only CI: no Azure credentials needed
• For live integration tests: Azure AD test tenant with app registration
• GitHub repository secrets configured (live tests only)

Instructions

Strategy 1: Mock-Only CI (PR Checks)

Use msw (Mock Service Worker) to intercept Graph API calls with zero Azure dependency:

// tests/mocks/handlers.ts
import { http, HttpResponse } from "msw";
const GRAPH = "https://graph.microsoft.com/v1.0";

export const handlers = [
  http.get(`${GRAPH}/me/onenote/notebooks`, () =>
    HttpResponse.json({ value: [
      { id: "nb-001", displayName: "Work Notes", createdDateTime: "2026-01-15T10:00:00Z" },
    ]})),

  http.get(`${GRAPH}/me/onenote/sections/:sectionId/pages`, () =>
    HttpResponse.json({ value: [
      { id: "page-001", title: "Sprint Review", createdDateTime: "2026-03-10T14:00:00Z" },
    ]})),

  http.post(`${GRAPH}/me/onenote/sections/:sectionId/pages`, async ({ request }) => {
    const body = await request.text();
    if (!body.includes("<html")) {
      return new HttpResponse(JSON.stringify({
        error: { code: "InvalidArgument", message: "Page content must be valid XHTML" }
      }), { status: 400 });
    }
    return HttpResponse.json({ id: "page-new", title: "Created Page" }, { status: 201 });
  }),
];

// tests/setup.ts
import { setupServer } from "msw/node";
import { handlers } from "./mocks/handlers";
export const server = setupServer(...handlers);
beforeAll(() => server.listen({ onUnhandledRequest: "error" }));
afterEach(() => server.resetHandlers());
afterAll(() => server.close());

Strategy 2: Live Integration Tests (Nightly)

Required GitHub Secrets: AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET.

Warning: ClientSecretCredential (app-only auth) was deprecated March 31, 2025 for OneNote APIs. CI test environments may still use it for automation, but production code must use delegated auth. Monitor Microsoft deprecation notices.

GitHub Actions Workflows

# .github/workflows/onenote-pr.yml — Mock-only, every PR
n…

OneNote Common Errors

Overview

A complete error decoder for the OneNote Graph API. Each HTTP status code has multiple possible root causes — this skill maps every cause, provides diagnostic steps, and gives fix-it code. Special attention to the two trickiest errors: 403 (which could mean wrong permissions OR deprecated app-only auth) and 200 with empty body (silent upload failure that causes data loss).

Prerequisites

• A OneNote Graph API integration that is returning errors
• Access to application logs or the ability to add logging
• Familiarity with the Graph API request/response format

Instructions

Complete Error Reference Table

OneNote — Full CRUD Lifecycle (Notebooks, Sections, Pages)

Overview

OneNote's hierarchy — Notebook, Section Group, Section, Page — maps cleanly to Graph API endpoints, but the implementation has sharp edges. Section groups created via API sometimes don't render in the desktop client. Page content must be strict XHTML with self-closing tags, and the HTML you send in differs from the HTML you get back. This skill covers the full create/read/update/delete lifecycle with production-safe patterns for every level of the hierarchy.

Key pain points addressed:

• Page content requires XHTML (all tags must close, UTF-8 encoded, no rowspan/colspan)
• Section groups support API nesting depths that the desktop app cannot render beyond two levels
• Output HTML from GET /pages/{id}/content contains Graph-injected data-id attributes and rewritten image URLs that differ from your input HTML
• PATCH page updates use a JSON array with target/action/content — not raw HTML

Prerequisites

• Azure app registration with delegated permissions: Notes.ReadWrite or Notes.ReadWrite.All
• App-only auth deprecated March 31, 2025 — use delegated auth only (DeviceCodeCredential or InteractiveBrowserCredential)
• Python: pip install msgraph-sdk azure-identity
• Node/TypeScript: npm install @microsoft/microsoft-graph-client @azure/identity @azure/msal-node

Instructions

Step 1 — Authenticate with Delegated Credentials

TypeScript:

import { Client } from "@microsoft/microsoft-graph-client";
import { TokenCredentialAuthenticationProvider } from "@microsoft/microsoft-graph-client/authProviders/azureTokenCredentials";
import { DeviceCodeCredential } from "@azure/identity";

const credential = new DeviceCodeCredential({
  clientId: process.env.AZURE_CLIENT_ID!,
  tenantId: process.env.AZURE_TENANT_ID!,
});
const scopes = ["Notes.ReadWrite"];
const authProvider = new TokenCredentialAuthenticationProvider(credential, { scopes });
const client = Client.initWithMiddleware({ authProvider });

Python:

from azure.identity import DeviceCodeCredential
from msgraph import GraphServiceClient

credential = DeviceCodeCredential(
    client_id=os.environ["AZURE_CLIENT_ID"],
    tenant_id=os.environ["AZURE_TENANT_ID"],
)
scopes = ["Notes.ReadWrite"]
client = GraphServiceClient(credentials=credential, scopes=scopes)

Step 2 — Create a Notebook

const notebook = await client.api("/me/onenote/notebooks").post({
  displayName: "Project …

OneNote — Search, Query, and Pagination

Overview

OneNote's dedicated search endpoint was deprecated in April 2024. The replacement — OData $filter queries on page listings — cannot search page body content, cannot search across all notebooks in a single call, and sometimes returns deleted pages in results. Pagination via @odata.nextLink is unreliable: the link is sometimes omitted even when more results exist. This skill provides production-tested patterns for content discovery, cross-notebook queries, and safe pagination with guard rails.

Key pain points addressed:

• The $search parameter on /me/onenote/pages is deprecated — use $filter on metadata fields only
• No single endpoint searches across all notebooks — you must iterate notebooks and their sections
• Deleted pages continue appearing in GET /sections/{id}/pages results for up to 30 minutes
• @odata.nextLink may be absent even when $top items were returned (Graph bug with OneNote)

Prerequisites

• Azure app registration with delegated permissions: Notes.Read or Notes.ReadWrite
• App-only auth deprecated March 31, 2025 — use delegated auth only
• Python: pip install msgraph-sdk azure-identity
• Node/TypeScript: npm install @microsoft/microsoft-graph-client @azure/identity @azure/msal-node
• Optional for client-side search: npm install fuse.js or pip install thefuzz

Instructions

Step 1 — Query Pages with OData Filters

OData $filter works on page metadata fields — not body content. Supported fields: title, createdDateTime, lastModifiedDateTime.

import { Client } from "@microsoft/microsoft-graph-client";

// Filter by title substring
const results = await client.api("/me/onenote/pages")
  .filter("contains(title, 'sprint planning')")
  .select("id,title,lastModifiedDateTime,parentSection")
  .top(20)
  .orderby("lastModifiedDateTime desc")
  .get();

// Filter by date range
const recentPages = await client.api("/me/onenote/pages")
  .filter("lastModifiedDateTime ge 2026-03-01T00:00:00Z")
  .select("id,title,lastModifiedDateTime")
  .top(50)
  .orderby("lastModifiedDateTime desc")
  .get();

> Warning: $search was deprecated April 2024. Using it returns 400 Bad Request on most tenants. Use $filter with contains() on title, or implement client-side search on fetched content.

Step 2 — Cross-Notebook Search Pattern

There is no single Graph endpoint that searches page content acr…

OneNote Cost Tuning

Overview

OneNote Graph API calls have no per-request cost — they are included in every Microsoft 365 E3/E5/Business license. However, rate limits create an effective ceiling that functions like a cost constraint: 600 requests per user per 60 seconds and 10,000 requests per app per 10 minutes at the tenant level. Exceeding these limits returns 429 errors with Retry-After headers, degrading user experience the same way budget overruns degrade service. This skill covers the practical optimization strategies that keep you well under those ceilings: metadata caching, JSON batch requests, delta sync, payload minimization with $select/$expand, and content deduplication. A naive integration that polls every user's notebooks every minute burns through the tenant limit in under 10 minutes. An optimized one handles thousands of users within the same budget.

Prerequisites

• Microsoft 365 license (E3/E5/Business) — OneNote API is included, no additional billing
• Azure AD app registration with delegated permissions
• Python: pip install msgraph-sdk azure-identity or Node: npm install @microsoft/microsoft-graph-client @azure/identity
• Understanding of HTTP caching headers (ETag, If-None-Match)

Instructions

Licensing Model and True Cost

The real cost is operational: every 429 response adds latency, retry logic consumes compute, and throttled users see failures. Optimization is about reliability, not billing.

Strategy 1: Cache Metadata Aggressively

Notebook and section metadata changes rarely (names, IDs, hierarchy). Cache it locally and refresh on a schedule, not per-request:

interface CachedMetadata {
  notebooks: any[];
  sections: Map<string, any[]>;  // notebookId -> sections
  fetchedAt: number;
  ttlMs: number;
}

class MetadataCache {
  private cache: CachedMetadata = {
    notebooks: [],
    sections: new Map(),
    fetchedAt: 0,
    ttlMs: 15 * 60 * 1000,  // 15 minutes — notebooks/sections rarely change
  };

  isStale(): boolean {
    return Date.now() - this.cache.fetchedAt > this.cache.ttlMs;
  }

  async getNotebooks(client: any): Promise<any[]> {
    if (!this.isStale() && this.cache.notebooks.length > 0) {
      return this.cache.notebooks;  // 0 API c…

OneNote Debug Bundle

Overview

When OneNote API calls fail, you need the request-id response header (Microsoft support requires it), decoded JWT token claims (to verify granted scopes), the x-ms-ags-diagnostic header (internal Graph routing info), and the full error body — all correlated to a single request. This skill generates structured diagnostic bundles for self-diagnosis and Microsoft support ticket filing.

Prerequisites

• Node.js 18+ or Python 3.10+
• An existing OneNote integration with Graph API calls
• @microsoft/microsoft-graph-client or msgraph-sdk installed
• Access token available (for token inspection)

Instructions

TypeScript Diagnostic Middleware

Intercept all Graph API calls and capture diagnostics automatically:

// src/debug/diagnostic-middleware.ts
interface DiagnosticEntry {
  timestamp: string; method: string; url: string; status: number;
  requestId: string | null; agsDiagnostic: string | null;
  retryAfter: string | null; duration_ms: number; error: any | null;
}

const diagnosticLog: DiagnosticEntry[] = [];

export function createDiagnosticMiddleware() {
  return {
    execute: async (context: any) => {
      const start = Date.now();
      const { url, method } = context.request || { url: "unknown", method: "GET" };
      try {
        await context.next();
        const h = context.response?.headers;
        diagnosticLog.push({
          timestamp: new Date().toISOString(), method, url,
          status: context.response?.status || 0,
          requestId: h?.get?.("request-id") || null,
          agsDiagnostic: h?.get?.("x-ms-ags-diagnostic") || null,
          retryAfter: h?.get?.("retry-after") || null,
          duration_ms: Date.now() - start, error: null,
        });
      } catch (err: any) {
        diagnosticLog.push({
          timestamp: new Date().toISOString(), method, url,
          status: err?.statusCode || 0,
          requestId: err?.headers?.["request-id"] || null,
          agsDiagnostic: err?.headers?.["x-ms-ags-diagnostic"] || null,
          retryAfter: err?.headers?.["retry-after"] || null,
          duration_ms: Date.now() - start,
          error: { code: err?.code, message: err?.message, body: err?.body },
        });
        throw err;
      }
    },
  };
}

export function getDiagnosticLog(): DiagnosticEntry[] { return [...diagnosticLog]; }
export function clearDiagnosticLog(): void { diagnosticLog.length = 0; }

Token Claims Inspection (No External Libraries)

Decode a JWT access token to inspect scopes and expiry using only built-in Base64:

// src/debug/token-inspector.ts
export function decodeTokenClaims(accessToken: string): Record<string, any> …

OneNote Deploy Integration

Overview

Deploying OneNote integrations into containers breaks local development assumptions: MSAL token caches vanish on restart, health checks must validate Graph API connectivity (not just HTTP 200), and graceful shutdown must flush token state. This skill provides production-ready Dockerfile, Docker Compose, and Kubernetes manifests with MSAL token persistence, health/readiness probes that verify actual Graph reachability, and SIGTERM handling.

Prerequisites

• Docker 24+ and Docker Compose v2
• Node.js 20 LTS or Python 3.11+
• Azure AD app registration with delegated permissions (Notes.Read, Notes.ReadWrite)
• Redis (recommended for multi-replica) or persistent volume for token cache

Instructions

Dockerfile

FROM node:20-slim AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY tsconfig.json src/ ./
RUN npm run build

FROM node:20-slim
WORKDIR /app
RUN apt-get update && apt-get install -y --no-install-recommends curl && rm -rf /var/lib/apt/lists/*
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/package.json ./
RUN mkdir -p /app/.cache/msal && chown -R node:node /app/.cache
USER node
ENV NODE_ENV=production MSAL_CACHE_DIR=/app/.cache/msal
HEALTHCHECK --interval=30s --timeout=10s --start-period=15s --retries=3 \
  CMD curl -sf http://localhost:3000/health || exit 1
EXPOSE 3000
CMD ["node", "dist/index.js"]

MSAL Token Cache Persistence

File-based (single replica):

// src/auth/token-cache.ts
import { readFile, writeFile, mkdir } from "fs/promises";
import { existsSync } from "fs";
import path from "path";

const CACHE_DIR = process.env.MSAL_CACHE_DIR || "/app/.cache/msal";
const CACHE_FILE = path.join(CACHE_DIR, "token-cache.json");

export async function loadCache(): Promise<string | null> {
  try {
    if (existsSync(CACHE_FILE)) return await readFile(CACHE_FILE, "utf-8");
  } catch (err) { console.error("Failed to load token cache:", err); }
  return null;
}

export async function saveCache(contents: string): Promise<void> {
  await mkdir(CACHE_DIR, { recursive: true });
  await writeFile(CACHE_FILE, contents, { mode: 0o600 });
}

Redis-based (multi-replica):

// src/auth/redis-cache.ts
import { createClient, RedisClientType } from "redis";
const CACHE_KEY = "msal:onenote:token-cache";
let redis: RedisClientType;

export async function initRedisCache(): Promise<void> {
  redis = createClient({ url: process.env.REDIS_URL || "redis://localhost:6379" });
  redis.on("err…

OneNote Hello World

Overview

Create your first OneNote notebook, section, and page through the Graph API. The critical pitfall this skill addresses: OneNote pages require strict XHTML (not regular HTML). Missing closing tags, unsupported attributes, or table features like rowspan/colspan cause silent content corruption where the API returns 200 OK but the page renders incorrectly or with missing content.

This skill walks through the full creation chain — notebook, section, page — with correct XHTML, then reads back the content to demonstrate that output HTML differs from input HTML.

Prerequisites

• Completed onenote-install-auth — you have a working GraphServiceClient (Python) or Client (TypeScript)
• Azure AD app with Notes.ReadWrite permission scope
• Node.js 18+ or Python 3.10+

Instructions

Step 1: Create a Notebook

// TypeScript — create a new notebook
const notebook = await client.api("/me/onenote/notebooks").post({
  displayName: "Dev Integration Test"
});
console.log(`Notebook created: ${notebook.displayName} (${notebook.id})`);
// Save notebook.id — you need it for creating sections

# Python — create a new notebook
from msgraph.generated.models.notebook import Notebook

request_body = Notebook(display_name="Dev Integration Test")
notebook = await client.me.onenote.notebooks.post(request_body)
print(f"Notebook created: {notebook.display_name} ({notebook.id})")

Naming rules: Notebook names must be unique per user. If a notebook with the same name exists, you get a 400 error with code 20117. Use a timestamp suffix for test notebooks: f"Test-{datetime.now().isoformat()}".

Step 2: Create a Section

// TypeScript — create a section inside the notebook
const section = await client
  .api(`/me/onenote/notebooks/${notebook.id}/sections`)
  .post({ displayName: "Getting Started" });
console.log(`Section created: ${section.displayName} (${section.id})`);

# Python — create a section
from msgraph.generated.models.onenote_section import OnenoteSection

section_body = OnenoteSection(display_name="Getting Started")
section = await client.me.onenote.notebooks.by_notebook_id(
    notebook.id
).sections.post(section_body)
print(f"Section created: {section.display_name} ({section.id})")

Step 3: Create a Page with Correct XHTML

This is where most integrations break. OneNote requires XHTML — every tag must close, the document must be UTF-8, and several HTML features are silently dropped.

VALID XHTML (this works):

OneNote Install & Auth

Overview

Set up Microsoft Graph API authentication for OneNote using delegated credentials via MSAL. This skill walks through Azure AD app registration, SDK installation, permission scope selection, token caching, and connection verification for both Python and TypeScript.

BREAKING CHANGE (March 31, 2025): App-only authentication (ClientSecretCredential) was deprecated for OneNote APIs. All integrations MUST use delegated auth — DeviceCodeCredential or InteractiveBrowserCredential. If your existing code uses ClientSecretCredential with OneNote endpoints, it will receive 403 Forbidden on every call. This skill provides the correct migration path.

Prerequisites

• Azure account with permission to register applications (Azure AD admin or Application Developer role)
• Node.js 18+ or Python 3.10+
• Access to Azure Portal App Registrations
• A OneNote account (personal Microsoft account or Microsoft 365 work/school account)

Instructions

Step 1: Register an Azure AD Application

1. Navigate to Azure Portal > App Registrations
2. Click New registration
3. Set the Name (e.g., onenote-integration-dev)
4. Under Supported account types, choose:

• Single tenant — only your organization (most restrictive, recommended for internal tools)
• Multi-tenant — any Azure AD directory (needed if serving multiple orgs)
• Multi-tenant + personal — includes personal Microsoft accounts (needed if targeting consumer OneNote)

1. Under Redirect URI, select Public client/native and set URI to http://localhost
2. Click Register and note the Application (client) ID and Directory (tenant) ID

Step 2: Configure API Permissions

1. In your app registration, go to API permissions > Add a permission > Microsoft Graph > Delegated permissions
2. Add the appropriate scope:

1. Click Grant a…

OneNote Local Dev Loop

Overview

Testing OneNote integrations typically requires Azure AD credentials and live Graph API calls, which means authentication friction on every dev session and risk of hitting the 600 req/60s rate limit during rapid iteration. This skill sets up a local development loop with mock Graph responses so you can develop and test OneNote features without Azure credentials, without rate limits, and with instant feedback.

The mock layer intercepts HTTP calls to graph.microsoft.com and returns realistic fixture data, including the XHTML output format that differs from input format. You can switch between mock and live Graph with a single environment variable.

Prerequisites

• Node.js 18+ or Python 3.10+
• Familiarity with your project's test framework (vitest/jest for Node, pytest for Python)
• Optional: completed onenote-install-auth for live mode switching

Instructions

Step 1: Project Structure

my-onenote-app/
├── .env                          # GRAPH_MODE=mock or GRAPH_MODE=live
├── .env.example                  # Template (commit this, not .env)
├── src/
│   ├── client.ts                 # Graph client factory (mock/live switching)
│   ├── onenote.ts                # Business logic (testable)
│   └── types.ts                  # OneNote type definitions
├── tests/
│   ├── fixtures/
│   │   ├── notebooks.json        # Mock notebook list response
│   │   ├── sections.json         # Mock section list response
│   │   ├── pages.json            # Mock page list response
│   │   ├── page-content.html     # Mock page HTML (output format)
│   │   └── error-responses.json  # Mock error responses for testing
│   ├── mocks/
│   │   └── graph-handlers.ts     # MSW request handlers
│   └── onenote.test.ts           # Unit tests
├── package.json
└── tsconfig.json

Step 2: Mock Graph API Server (TypeScript with MSW)

MSW (Mock Service Worker) intercepts HTTP requests at the network level, so your production code does not need any changes to work with mocks.

// tests/mocks/graph-handlers.ts
import { http, HttpResponse } from "msw";

const BASE = "https://graph.microsoft.com/v1.0";

// Import fixture data
import notebooksFixture from "../fixtures/notebooks.json";
import sectionsFixture from "../fixtures/sections.json";
import pagesFixture from "../fixtures/pages.json";
import { readFileSync } from "fs";
import { join } from "path";

const pageContentFixture = readFileSync(
  join(__dirname, "../fixtures/page-content.html"),
  "utf-8"
);

export const graphHandlers = [
  // List notebooks
  http.get(`${BASE}/me/onenote/notebooks`, () => {
    return HttpResponse.json(notebooksFixture);
  }),

  // Create notebook
  …

OneNote — Performance Tuning & Optimization

Overview

OneNote performance degrades predictably at scale: notebooks with 100+ sections take 3-5 seconds per API call when using $expand, pages with embedded images over 4MB fail silently, and sections hitting the page limit return 507 Insufficient Storage. Image uploads are capped at 25MB per multipart part, and requesting full page content for hundreds of pages without $select can exhaust your rate budget in seconds.

This skill provides tested patterns for every performance bottleneck: selective $expand and $select for minimal payloads, image compression before upload, batch requests via $batch, pagination with $top to avoid loading thousands of pages, and caching strategies that invalidate on change detection.

Key pain points addressed:

• Full $expand=sections($expand=pages) on large notebooks can take 10+ seconds and return multi-MB responses
• Image uploads silently fail when a single multipart part exceeds 25MB — no error, just missing image
• 507 Insufficient Storage when a section hits its page limit (approximately 5,000 pages)
• Page content retrieval (GET /pages/{id}/content) is 5-10x slower than metadata-only requests

Prerequisites

• Azure app registration with delegated permissions: Notes.ReadWrite
• App-only auth deprecated March 31, 2025 — use delegated auth only
• Python: pip install msgraph-sdk azure-identity Pillow (Pillow for image compression)
• Node/TypeScript: npm install @microsoft/microsoft-graph-client @azure/identity @azure/msal-node sharp (sharp for image compression)

Instructions

Step 1 — Use $select to Minimize Payload Size

Every Graph API call should specify $select to return only the fields you need. The default response includes navigation properties, OData metadata, and verbose timestamps that inflate payloads:

// BAD — returns ~2KB per page with all metadata
const pages = await client.api("/me/onenote/pages").get();

// GOOD — returns ~200 bytes per page with only needed fields
const pages = await client.api("/me/onenote/pages")
  .select("id,title,lastModifiedDateTime")
  .get();

// For notebooks, avoid expanding everything
// BAD — can take 10+ seconds on large notebooks
const notebooks = await client.api("/me/onenote/notebooks")
  .expand("sections($expand=pages)")
  .get();

// GOOD — get structure first, then drill into sections on demand
const notebooks = await client.api("/me/onenote/notebooks")
  .select("id,displayName,lastModifiedDateTime,sectionsUrl")
  .get();

Payload size comparison for a notebook wit…

OneNote Production Checklist

Overview

OneNote integrations that work perfectly in development break in production in predictable ways: SharePoint document libraries exceed the 5,000-item view threshold and stop returning notebooks, image uploads silently truncate above 4MB, rate limits compound across users during business hours, and MSAL token caches lose state across container restarts. This skill is a comprehensive go/no-go checklist organized by failure category. Each item references the specific Graph API behavior that causes the production failure and provides the fix. Use this checklist during launch reviews — every unchecked item is a production incident waiting to happen.

Prerequisites

• A functional OneNote integration that works in development/staging
• Azure AD app registration with delegated permissions configured
• Access to production monitoring infrastructure (logging, alerting)
• Familiarity with your deployment environment (containers, VMs, serverless)
• Completed onenote-security-basics and onenote-rate-limits skills

Instructions

1. Authentication Checklist

Verification test:

import os, time

def verify_auth_resilience(client):
    """Test that auth survives token expiry cycle."""
    # 1. Make a call to confirm auth works
    response = client.me.onenote.notebooks.get()
    assert response.value is not None, "Initial auth failed"

    # 2. Verify token cache exists on disk
    cache_path = os.path.expanduser("~/.onenote-token-cache.json")
    assert os.path.exists(cache_path), "Token cache not persisted"
    stat = os.stat(cache_path)
    assert oct(stat.…

OneNote — Rate Limit Handling & Request Throttling

Overview

Microsoft Graph rate limits OneNote at 600 requests per 60 seconds per user and 10,000 requests per 10 minutes per app/tenant. When you exceed either limit, the API returns 429 Too Many Requests with a Retry-After header specifying how many seconds to wait. Most implementations either ignore this header entirely (retrying immediately, making things worse) or use a fixed backoff that wastes capacity.

This skill implements a token bucket rate limiter, queue-based request throttling, and proper Retry-After header parsing. For multi-user apps, it tracks per-user and per-tenant budgets independently.

Key pain points addressed:

• The Retry-After header value is in seconds (not milliseconds) — many implementations parse this wrong
• The per-user limit (600/60s) is separate from the per-tenant limit (10,000/10min) — you can hit one without the other
• Batch requests ($batch) count as one request toward the limit, regardless of how many operations are inside
• After a 429, subsequent requests to ANY OneNote endpoint are throttled — not just the endpoint that triggered it

Prerequisites

• Azure app registration with delegated permissions: Notes.ReadWrite
• App-only auth deprecated March 31, 2025 — use delegated auth only
• Python: pip install msgraph-sdk azure-identity
• Node/TypeScript: npm install @microsoft/microsoft-graph-client @azure/identity @azure/msal-node
• Optional: npm install p-queue for production queue management

Instructions

Step 1 — Understand the Rate Limit Structure

When either limit is hit:

• Response status: 429 Too Many Requests
• Response header: Retry-After: <seconds> (integer, not milliseconds)
• All subsequent OneNote requests for that scope are blocked until the window resets
• Non-OneNote Graph endpoints (Outlook, OneDrive) are not affected

Step 2 — Token Bucket Rate Limiter (TypeScript)

A token bucket preemptively throttles requests to stay below the limit, avoiding 429s entirely:

class TokenBucket {
  private tokens: number;
  private lastRefill: number;
  private readonly maxTokens: number;
  private readonly refillRate: number; // tokens per…

OneNote Reference Architecture

Overview

OneNote notebooks live in three completely different storage backends — personal OneDrive, SharePoint team sites, and Microsoft 365 Groups — each with its own Graph API path, permission model, and behavioral quirks. Building an integration that "just works with OneNote" means handling all three locations, because users do not know (or care) where their notebook is stored. The API path /me/onenote/notebooks only returns personal notebooks; SharePoint and Group notebooks require different endpoints entirely. This skill maps the full architecture: storage locations, API paths, the object hierarchy (and its gotchas), and a service abstraction layer that normalizes all three locations into a single interface.

Prerequisites

• Azure AD app registration with delegated permissions (Notes.ReadWrite minimum)
• Familiarity with Microsoft Graph API URL structure (https://graph.microsoft.com/v1.0)
• For SharePoint notebooks: Sites.Read.All or Sites.ReadWrite.All permission
• For Group notebooks: Group.Read.All or Group.ReadWrite.All permission
• Python: pip install msgraph-sdk azure-identity or Node: npm install @microsoft/microsoft-graph-client @azure/identity

Instructions

System Architecture

┌─────────────┐     ┌──────────────┐     ┌─────────────────┐
│  Your App   │────>│  MSAL Auth   │────>│  Azure AD       │
│  (Client)   │     │  (Delegated) │     │  Token Service  │
└──────┬──────┘     └──────────────┘     └─────────────────┘
       │
       │ Bearer Token
       v
┌──────────────────────────────────────────────────────────┐
│              Microsoft Graph API (v1.0)                   │
│              https://graph.microsoft.com/v1.0             │
├──────────────┬──────────────────┬────────────────────────┤
│ /me/onenote  │ /sites/{id}/     │ /groups/{id}/          │
│              │  onenote          │  onenote               │
├──────────────┼──────────────────┼────────────────────────┤
│  Personal    │   SharePoint     │   Group                │
│  OneDrive    │   Document Lib   │   Notebook             │
│  Storage     │   Storage        │   Storage              │
└──────────────┴──────────────────┴────────────────────────┘

Three Notebook Locations

1. Personal Notebooks (OneDrive)

GET https://graph.microsoft.com/v1.0/me/onenote/notebooks
GET https://graph.microsoft.com/v1.0/me/onenote/notebooks/{notebook-id}/sections
GET https://graph.microsoft.com/v1.0/me/onenote/sections/{section-id}/pages

• Owned by the signed-in user
• Stored in user's OneDrive root /Documents/ or /Notebooks/
• Permission: Notes.ReadWrite (user consent, no a…

OneNote SDK Patterns

Overview

Production-grade patterns for the OneNote Graph API. The two biggest production issues are rate limits (600 requests per 60 seconds per user, 10,000 per 10 minutes per tenant) and silent upload failures where files >4MB return 200 OK with an empty response body — the page is never created but no error is raised.

This skill provides middleware chains, retry decorators, batch request patterns, and silent failure detection for both TypeScript and Python.

Prerequisites

• Completed onenote-install-auth — working Graph API authentication
• Understanding of async/await patterns in your target language
• Node.js 18+ or Python 3.10+

Instructions

Pattern 1: Retry Middleware with Retry-After Header Parsing (TypeScript)

The Graph API returns a Retry-After header (in seconds) with 429 responses. Hardcoding a fixed retry delay wastes time or hits limits again.

import { Client, ClientOptions } from "@microsoft/microsoft-graph-client";

class RetryHandler {
  private maxRetries = 3;

  async execute(
    context: { request: Request; options: RequestInit },
    next: (context: any) => Promise<Response>
  ): Promise<Response> {
    let lastError: Error | null = null;

    for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
      try {
        const response = await next(context);

        if (response.status === 429) {
          const retryAfter = response.headers.get("Retry-After");
          const waitSeconds = retryAfter ? parseInt(retryAfter, 10) : 30;
          console.warn(
            `Rate limited (429). Retry-After: ${waitSeconds}s. ` +
            `Attempt ${attempt + 1}/${this.maxRetries + 1}`
          );
          await new Promise((r) => setTimeout(r, waitSeconds * 1000));
          continue;
        }

        if (response.status === 502 || response.status === 503) {
          const backoff = Math.pow(2, attempt) * 1000;
          console.warn(
            `Server error (${response.status}). Backing off ${backoff}ms.`
          );
          await new Promise((r) => setTimeout(r, backoff));
          continue;
        }

        return response;
      } catch (err) {
        lastError = err as Error;
        if (attempt < this.maxRetries) {
          const backoff = Math.pow(2, attempt) * 1000;
          await new Promise((r) => setTimeout(r, backoff));
        }
      }
    }
    throw lastError ?? new Error("Max retries exceeded");
  }
}

Pattern 2: Retry Decorator (Python)

import asyncio
import functools
from typing import TypeVar, Callable, Any

T = TypeVar("T")

def retry_graph(max_retries: int = 3):
    """Decorator for Graph API calls with rate limit awareness."""
    def decorato…

OneNote Security Basics

Overview

OneNote Graph API security changed fundamentally on March 31, 2025, when Microsoft deprecated app-only authentication for OneNote endpoints. Every integration must now use delegated authentication through MSAL, which means real users must sign in — no more background service accounts with client secrets. This skill covers the full security surface: permission scoping, token lifecycle management, MSAL cache serialization, credential storage, and multi-tenant hardening. Get any of these wrong and your integration either breaks silently (expired tokens returning 401s) or over-provisions access (Notes.ReadWrite.All when Notes.Read suffices).

Prerequisites

• Azure AD app registration with redirect URI configured at https://portal.azure.com/#blade/Microsoft_AAD_RegisteredApps
• Microsoft 365 license (E3/E5/Business) with OneNote enabled
• Python: pip install msgraph-sdk azure-identity msal or Node: npm install @microsoft/microsoft-graph-client @azure/identity @azure/msal-node
• Understanding of OAuth 2.0 authorization code flow and delegated permissions

Instructions

Permission Scope Matrix

Choose the minimum scope required for your use case:

Least-privilege recommendations:

• Read-only dashboards: Notes.Read (user consent only)
• Personal note creation: Notes.ReadWrite (user consent only)
• Cross-user/organizational access: Notes.ReadWrite.All (requires tenant admin approval)
• Write-only ingestion: Notes.Create (cannot read back what was written)

Delegated Authentication Setup (Post-2025 Mandatory)

CRITICAL: App-only authentication (ClientSecretCredential) was deprecated for OneNote endpoints on March 31, 2025. All code below uses delegated auth exclusively.

Python — Device Code Flow (headless/CLI environments):

from azure.identity import DeviceCodeCredential
from msgraph import GraphServiceClient
import os

CLIENT_ID = os.environ["AZURE_CLIENT_ID"]
TENANT_ID = os.environ["AZURE_TENANT_ID"]

# Minimal scopes — only request what…

OneNote Upgrade & Migration

Overview

Microsoft shipped three breaking changes to OneNote integrations in under two years: webhook decommissioning (June 2023), search endpoint deprecation (April 2024), and app-only auth deprecation (March 2025). The Graph SDK itself had breaking changes between v5 and v6. This skill provides exact migration diffs, verification steps, and rollback strategies for each breaking change.

Prerequisites

• Existing OneNote integration using Graph API
• Node.js 18+ (TypeScript SDK) or Python 3.10+ (Python SDK)
• Git for branch-based migration with rollback capability
• Azure portal access for app registration changes (auth migration)

Instructions

Breaking Changes Timeline

Migration 1: App-Only to Delegated Auth

Before (broken after March 2025):

// OLD — ClientSecretCredential (DEPRECATED for OneNote)
import { ClientSecretCredential } from "@azure/identity";
const credential = new ClientSecretCredential(TENANT_ID, CLIENT_ID, CLIENT_SECRET);
const authProvider = new TokenCredentialAuthenticationProvider(credential, {
  scopes: ["https://graph.microsoft.com/.default"],
});

After:

// NEW — DeviceCodeCredential (required)
import { DeviceCodeCredential } from "@azure/identity";
const credential = new DeviceCodeCredential({
  clientId: CLIENT_ID, tenantId: TENANT_ID,
  userPromptCallback: (info) =>
    console.log(`Open ${info.verificationUri} and enter code: ${info.userCode}`),
});
const authProvider = new TokenCredentialAuthenticationProvider(credential, {
  scopes: ["Notes.Read", "Notes.ReadWrite"],  // Explicit, not .default
});
const client = Client.initWithMiddleware({ authProvider });

Python equivalent:

# OLD: credential = ClientSecretCredential(tenant_id, client_id, client_secret)
# NEW:
from azure.identity import DeviceCodeCredential
credential = DeviceCodeCredential(client_id=CLIENT_ID, tenant_id=TENANT_ID)

Required Azure portal changes: Add "Mobile and desktop applications" platform with http://localhost redirect URI to your app registration.

Migration 2: Webhooks to Polling

// OLD — Webhook subscription (D…

OneNote — Change Detection (Polling & Delta Queries)

Overview

> OneNote webhooks were decommissioned June 16, 2023. The Graph subscription API (POST /subscriptions with changeType: "updated" on OneNote resources) returns 400 Bad Request. Unlike Outlook mail, calendar, and OneDrive — which still support push notifications — OneNote has no webhook replacement. You must poll.

This skill implements efficient change detection for OneNote using lastModifiedDateTime comparisons, delta query patterns, and rate-limit-aware polling intervals. The approach balances freshness (detecting changes within minutes) against the 600 requests/minute per-user rate limit.

Key pain points addressed:

• Subscription API for OneNote resources returns 400 — do not attempt it
• Delta queries (/me/onenote/pages/delta) are not officially documented but work on some tenants
• Polling must stay within rate budget (600/min per user, 10,000/10min per tenant)
• Change detection requires comparing timestamps, not content diffs (output HTML is unstable)

Prerequisites

• Azure app registration with delegated permissions: Notes.Read or Notes.ReadWrite
• App-only auth deprecated March 31, 2025 — use delegated auth only
• Python: pip install msgraph-sdk azure-identity
• Node/TypeScript: npm install @microsoft/microsoft-graph-client @azure/identity @azure/msal-node
• A persistent store for tracking last-seen timestamps (Redis, SQLite, file system)

Instructions

Step 1 — Understand Why Webhooks Do Not Work

// DO NOT DO THIS — it will return 400 Bad Request
// OneNote webhooks decommissioned June 16, 2023
const subscription = await client.api("/subscriptions").post({
  changeType: "updated",
  notificationUrl: "https://yourapp.com/webhooks/onenote",
  resource: "/me/onenote/pages",  // NOT SUPPORTED
  expirationDateTime: new Date(Date.now() + 3600000).toISOString(),
});
// Error: "Subscription validation request failed. Resource not found."

For comparison, these Graph resources still support webhooks: Outlook messages, calendar events, OneDrive files, Teams messages, Planner tasks. OneNote is the notable exception.

Step 2 — Implement Timestamp-Based Polling (TypeScript)

The core pattern: periodically list pages ordered by lastModifiedDateTime and compare against your stored watermark.

import { Client } from "@microsoft/microsoft-graph-client";

interface ChangeEvent {
  pageId: string;
  title: string;
  sectionId: string;
  modifiedAt: string;
  changeType: "created" | "modifi…