onenote-reference-architecture

What this skill does

# 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 admin needed)
- Cannot be shared with external tenants via API

**2. SharePoint Site Notebooks**

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

- Owned by the SharePoint site, accessible to site members
- Stored in the site's document library
- Permission: `Notes.ReadWrite` + `Sites.Read.All` (Sites scope often requires admin consent)
- **Gotcha:** You need the site ID, not the site URL. Resolve it first:

  ```
  GET https://graph.microsoft.com/v1.0/sites/{hostname}:/{server-relative-path}
  ```

**3. Group Notebooks (Microsoft 365 Groups / Teams)**

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

- Owned by the M365 Group (every Teams team has one)
- Stored in the group's SharePoint site document library
- Permission: `Notes.ReadWrite` + `Group.Read.All`
- Each group has exactly one default notebook (created automatically)

### Object Hierarchy

```
Notebook
├── Section Group (optional nesting)
│   └── Section
│       ├── Page
│       │   └── Content (HTML)
│       └── Page
└── Section
    ├── Page
    │   └── Content (HTML)
    └── Page
```

**Critical gotcha — Section Groups:** The API supports creating nested section groups, but the OneNote desktop and mobile apps cannot render section groups deeper than two levels. If your API creates `Notebook > Group A > Group B > Group C > Section`, desktop users will see a broken hierarchy. Limit nesting to one level of section groups.

**Page content is HTML:** Every page body is returned as XHTML. You must POST valid XHTML when creating pages (all tags self-closed, UTF-8 encoded). The Graph API silently strips invalid HTML rather than rejecting it, so malformed content appears to succeed but renders incorrectly.

### API Path Construction

Build paths dynamically based on notebook location:

```typescript
type NotebookLocation = "personal" | "sharepoint" | "group";

function buildOneNotePath(
  location: NotebookLocation,
  resourceId?: string
): string {
  const base = "https://graph.microsoft.com/v1.0";
  switch (location) {
    case "personal":
      return `${base}/me/onenote`;
    case "sharepoint":
      if (!resourceId) throw new Error("SharePoint requires site-id");
      return `${base}/sites/${resourceId}/onenote`;
    case "group":
      if (!resourceId) throw new Error("Group requires group-id");
      return `${base}/groups/${resourceId}/onenote`;
  }
}

// Usage
const path = buildOneNotePath("sharepoint", "contoso.sharepoint.com,guid1,guid2");
// => https://graph.microsoft.com/v1.0/sites/contoso.sharepoint.com,guid1,guid2/onenote
```

### Service Layer Abstraction

Normalize all three locations behind a single interface so callers never deal with path differences:

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

interface NotebookTarget {
  location: "personal" | "sharepoint" | "group";
  resourceId?: string;  // site-id or group-id
}

class OneNoteService {
  private client: Client;

  constructor(clientId: string, tenantId: string) {
    const credential = new DeviceCodeCredential({ clientId, tenantId });
    const authProvider = new TokenCredentialAuthenticationProvider(credential, {
      scopes: ["Notes.ReadWrite"],
    });
    this.client = Client.initWithMiddleware({ authProvider });
  }

  private basePath(target: NotebookTarget): string {
    switch (target.location) {
      case "personal": return "/me/onenote";
      case "sharepoint": return `/sites/${target.resourceId}/onenote`;
      case "group": return `/groups/${target.resourceId}/onenote`;
    }
  }

  async listNotebooks(target: NotebookTarget) {
    return this.client.api(`${this.basePath(target)}/notebooks`).get();
  }

  async listSections(target: NotebookTarget, notebookId: string) {
    return this.client
      .api(`${this.basePath(target)}/notebooks/${notebookId}/sections`)
      .get();
  }

  async listPages(target: NotebookTarget, sectionId: string) {
    return this.client
      .api(`${this.basePath(target)}/sections/${sectionId}/pages`)
      .select("id,title,createdDateTime,lastModifiedDateTime")
      .orderby("lastModifiedDateTime desc")
      .top(50)
      .get();
  }

  async createPage(target: NotebookTarget, sectionId: string, htmlBody: string) {
    return this.client
      .api(`${this.basePath(target)}/sections/${sectionId}/pages`)
      .header("Content-Type", "text/html")
      .post(htmlBody);
  }
}
```

### Decision Matrix: When to Use Which API Path

| Scenario | Path | Why |
|----------|------|-----|
| Personal note-taking app | `/me/onenote` | Simplest auth, user consent only |
| Team knowledge base | `/groups/{id}/onenote` | Shared with all team members automatically |
| Department wiki | `/sites/{id}/onenote` | SharePoin