OneNote Upgrade & Migration Skill

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

| Date | Change | Impact | |------|--------|--------| | June 16, 2023 | Webhooks decommissioned | Subscription notifications stop | | April 2024 | Search endpoint deprecated | /pages?search= returns 404 | | March 31, 2025 | App-only auth deprecated | ClientSecretCredential returns 403 |

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 (DECOMMISSIONED June 2023)
// await client.api("/subscriptions").post({ resource: "/me/onenote/pages", ... });

// NEW — Polling with delta link tracking
async function pollForChanges(client: any, deltaLink: string | null) {
  const endpoint = deltaLink || "/me/onenote/notebooks";
  const response = await client.api(endpoint)
    .header("Prefer", "odata.track-changes").get();

  for (const item of response.value || []) {
    await processChange(item);
  }
  return response["@odata.deltaLink"] || deltaLink;
}

// Poll every 60s (stays under 600 req/60s per-user rate limit)
let deltaLink: string | null = null;
setInterval(async () => {
  try { deltaLink = await pollForChanges(client, deltaLink); }
  catch (err: any) {
    if (err?.statusCode === 429) {
      console.warn(`Rate limited. Retry after ${err.headers?.["retry-after"] ?? 30}s`);
    }
  }
}, 60_000);

Migration 3: Search Endpoint to OData Filters

// OLD — Search endpoint (DEPRECATED April 2024)
// const results = await client.api("/me/onenote/pages").query({ search: "term" }).get();

// NEW — OData filter for title, client-side for content
async function searchPages(client: any, query: string) {
  // Server-side title filter
  const titleMatches = await client.api("/me/onenote/pages")
    .filter(`contains(title,'${query.replace(/'/g, "''")}')`)
    .top(50).orderby("lastModifiedDateTime desc").get();

  // Client-side content search (Graph no longer supports full-text)
  const contentMatches: any[] = [];
  const pages = await client.api("/me/onenote/pages").top(100)
    .orderby("lastModifiedDateTime desc").get();
  for (const page of pages.value) {
    const html = await client.api(`/me/onenote/pages/${page.id}/content`).get();
    if (html.replace(/<[^>]+>/g, "").toLowerCase().includes(query.toLowerCase())) {
      contentMatches.push(page);
    }
  }

  // Deduplicate
  const seen = new Set(titleMatches.value.map((p: any) => p.id));
  return [...titleMatches.value, ...contentMatches.filter((m) => !seen.has(m.id))];
}

Migration 4: Graph SDK v5 to v6 (TypeScript)

// SDK v5 — callback-based auth (REMOVED in v6)
const client = Client.init({
  authProvider: (done) => done(null, accessToken),
});

// SDK v6 — middleware-based auth (REQUIRED)
import { TokenCredentialAuthenticationProvider } from
  "@microsoft/microsoft-graph-client/authProviders/azureTokenCredentials";
const authProvider = new TokenCredentialAuthenticationProvider(credential, {
  scopes: ["Notes.Read", "Notes.ReadWrite"],
});
const client = Client.initWithMiddleware({ authProvider });

Migration Checklists

Auth migration: Remove AZURE_CLIENT_SECRET from env/secrets. Add redirect URI in Azure portal. Replace .default with explicit scopes. Verify GET /me/onenote/notebooks returns 200.

SDK upgrade: Update @microsoft/microsoft-graph-client to v6+. Replace Client.init() with Client.initWithMiddleware(). Remove callback auth providers. Run full test suite.

Search migration: Replace /pages?search= with OData $filter. Add client-side content search fallback. Performance test: client-side search under 2s for 100 pages.

Feature Detection at Runtime

export function requiresDelegatedAuth(): boolean { return true; } // Since March 2025
export function isSearchEndpointAvailable(): boolean { return false; } // Since April 2024
export function isWebhookAvailable(): boolean { return false; } // Since June 2023

Rollback Strategy

Use a feature flag for gradual auth migration:

const useDelegated = process.env.ONENOTE_AUTH_MODE !== "legacy";
const credential = useDelegated
  ? new DeviceCodeCredential({ clientId, tenantId })
  : new ClientSecretCredential(tenantId, clientId, clientSecret); // Legacy fallback

Output

Auth migration: ClientSecretCredential to DeviceCodeCredential with code diff
Webhook migration: subscription API to polling with delta queries
Search migration: deprecated endpoint to OData filters + client-side search
SDK v5 to v6: Client.init() to Client.initWithMiddleware()
Migration checklists and feature detection module
Rollback strategy with feature flag pattern

Error Handling

| Migration Error | Cause | Fix | |----------------|-------|-----| | 403 Forbidden after auth migration | Missing redirect URI | Add http://localhost to "Mobile and desktop" platform in Azure portal | | InvalidScope on token request | Using .default with delegated auth | Use explicit scopes: Notes.Read, Notes.ReadWrite | | TypeError: Client.init is not a function | SDK v6 removed Client.init | Use Client.initWithMiddleware | | 404 on search endpoint | Removed April 2024 | Use OData $filter + client-side content search | | 400 on subscription create | Webhooks decommissioned June 2023 | Switch to polling with delta queries |

Examples

# Check which migrations your codebase needs
grep -r "ClientSecretCredential" src/ --include="*.ts" --include="*.py"
grep -r "search=" src/ --include="*.ts" --include="*.py"
grep -r "/subscriptions" src/ --include="*.ts" --include="*.py"
grep -r "Client.init(" src/ --include="*.ts"

// Smoke test after auth migration
const client = getGraphClient();
const nb = await client.api("/me/onenote/notebooks").top(1).get();
console.log("Auth migration OK:", nb.value.length, "notebooks");

Resources

Next Steps

Set up CI for migrated code with onenote-ci-integration
Debug migration issues with onenote-debug-bundle
Review security after migration with onenote-security-basics

Agent Skills: OneNote Upgrade & Migration

Install this agent skill to your local

Skill Files