onenote-sdk-patterns

What this skill does

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

```typescript
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)

```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 decorator(func: Callable[..., Any]) -> Callable[..., Any]:
        @functools.wraps(func)
        async def wrapper(*args: Any, **kwargs: Any) -> Any:
            last_exception = None
            for attempt in range(max_retries + 1):
                try:
                    return await func(*args, **kwargs)
                except Exception as e:
                    last_exception = e
                    error_code = getattr(e, "status_code", None) or getattr(e, "code", 0)

                    if error_code == 429:
                        # Parse Retry-After from response headers
                        retry_after = getattr(e, "retry_after", 30)
                        print(f"Rate limited. Waiting {retry_after}s "
                              f"(attempt {attempt + 1}/{max_retries + 1})")
                        await asyncio.sleep(retry_after)
                    elif error_code in (502, 503, 504):
                        backoff = (2 ** attempt) * 1.0
                        print(f"Server error {error_code}. Backoff {backoff}s.")
                        await asyncio.sleep(backoff)
                    else:
                        raise  # Non-retryable error
            raise last_exception
        return wrapper
    return decorator

# Usage:
@retry_graph(max_retries=3)
async def list_notebooks(client):
    return await client.me.onenote.notebooks.get()
```

### Pattern 3: Rate Limit Tracker

Track request counts locally to proactively avoid 429 responses instead of reacting to them.

```typescript
class RateLimitTracker {
  private userRequests: { timestamp: number }[] = [];
  private tenantRequests: { timestamp: number }[] = [];

  // Graph limits for OneNote
  private readonly USER_LIMIT = 600;     // per 60 seconds
  private readonly USER_WINDOW = 60_000; // 60 seconds in ms
  private readonly TENANT_LIMIT = 10_000; // per 10 minutes
  private readonly TENANT_WINDOW = 600_000; // 10 minutes in ms

  canMakeRequest(): { allowed: boolean; waitMs: number } {
    const now = Date.now();

    // Prune expired entries
    this.userRequests = this.userRequests.filter(
      (r) => now - r.timestamp < this.USER_WINDOW
    );
    this.tenantRequests = this.tenantRequests.filter(
      (r) => now - r.timestamp < this.TENANT_WINDOW
    );

    if (this.userRequests.length >= this.USER_LIMIT) {
      const oldest = this.userRequests[0].timestamp;
      return { allowed: false, waitMs: this.USER_WINDOW - (now - oldest) };
    }

    if (this.tenantRequests.length >= this.TENANT_LIMIT) {
      const oldest = this.tenantRequests[0].timestamp;
      return { allowed: false, waitMs: this.TENANT_WINDOW - (now - oldest) };
    }

    return { allowed: true, waitMs: 0 };
  }

  recordRequest(): void {
    const now = Date.now();
    this.userRequests.push({ timestamp: now });
    this.tenantRequests.push({ timestamp: now });
  }
}

// Usage in middleware:
const tracker = new RateLimitTracker();

async function rateLimitedRequest<T>(fn: () => Promise<T>): Promise<T> {
  const check = tracker.canMakeRequest();
  if (!check.allowed) {
    console.warn(`Proactive rate limit pause: ${check.waitMs}ms`);
    await new Promise((r) => setTimeout(r, check.waitMs));
  }
  tracker.recordRequest();
  return fn();
}
```

### Pattern 4: Batch Requests ($batch Endpoint)

Reduce round trips by batching up to 20 Graph requests into a single HTTP call.

```typescript
// Batch request to fetch multiple pages in parallel
const batchBody = {
  requests: [
    { id: "1", method: "GET", url: `/me/onenote/pages/${pageId1}` },
    { id: "2", method: "GET", url: `/me/onenote/pages/${pageId2}` },
    { id: "3", method: "GET", url: `/me/onenote/pages/${pageId3}` },
  ],
};

const batchResponse = await client
  .api("/$batch")
  .post(batchBody);

// Each response has its own status code — some may fail while others succeed
for (const resp of batchResponse.responses) {
  if (resp.status === 200) {
    console.log(`Page ${resp.id}: ${resp.body.title}`);
  } else {
    console.error(`Page ${resp.id} failed: ${resp.status} — ${resp.body?.error?.message}`);
  }
}
```

**Batch limits:** Maximum 20 requests per batch. Requests within a batch count individually toward rate limits. Use `dependsOn` for sequential ordering within a batch.

### Pattern 5: Safe File Upload with Silent Failure Detection

Files larger than 4MB return 200 OK with an empty response body. The page is never created. You must check the response body after every upload.

```typescript
const MAX_UPLOAD_SIZE = 4 * 1024 * 1024; // 4MB

async function safeCreatePage(
  client: Client,
  sectionId: string,
  htmlContent: string,
  attachments?: { name: string; contentType: string; data: Buffer }[]
): Promise<{ success: boolean; pageId?: string; error?: string }> {
  // Calculate total payload size
  const htmlSize = Buffer.byteLength(htmlContent, "utf-8");
  const attachmentSize = attachments?.reduce((sum, a) => sum + a.data.length, 0) ?? 0;
  const totalSize = htmlSize + attachmentSize;

  if (totalSize > MAX_UPLOAD_SIZE) {
    return {
      success: false,
      error: `Payload ${(totalSize / 1024 / 1024).toFixed(1)}MB exceeds 4MB limit. ` +
        `Split content or upload images as URLs instead of inline data.`,
    };
  }

  const response = await c