onenote-sdk-patterns

Production SDK patterns for OneNote Graph API: retry logic, batch requests, and safe file uploads. Use when building production OneNote integrations that need rate limit handling and reliable uploads. Trigger with "onenote sdk patterns", "onenote retry logic", "onenote batch requests".

설치로 이동

저장소: jeremylongshore/claude-code-plugins-plus-skills
최근 소스 활동: 2026년 7월 17일 22:18
감지된 SKILL.md 언어: 영어
스타: 2,604
포크: 378

설치 방법

기본적으로 소스를 먼저 확인하는 Prompt가 선택됩니다. 직접 명령으로 전환하거나 로컬 사본을 다운로드할 수도 있습니다.

소스 파일 검토

설치 여부를 결정하기 전에 SKILL.md와 SkillsMP에 표시된 보조 파일을 읽어 보세요.

검색으로 돌아가기 설치로 돌아가기

name	onenote-sdk-patterns
description	Production SDK patterns for OneNote Graph API: retry logic, batch requests, and safe file uploads. Use when building production OneNote integrations that need rate limit handling and reliable uploads. Trigger with "onenote sdk patterns", "onenote retry logic", "onenote batch requests".
allowed-tools	Read, Write, Edit, Bash(npm:), Bash(pip:), Grep
version	1.6.0
license	MIT
author	Jeremy Longshore <jeremy@intentsolutions.io>
tags	["saas","onenote","microsoft"]
compatibility	Designed for Claude Code

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 <= .; attempt++) {
       {
         response =  (context);

         (response. === ) {
           retryAfter = response..();
           waitSeconds = retryAfter ? (retryAfter, ) : ;
          .(
             +
            
          );
            ( (r, waitSeconds * ));
          ;
        }

         (response. ===  || response. === ) {
           backoff = .(, attempt) * ;
          .(
            
          );
            ( (r, backoff));
          ;
        }

         response;
      }  (err) {
        lastError = err  ;
         (attempt < .) {
           backoff = .(, attempt) * ;
            ( (r, backoff));
        }
      }
    }
     lastError ??  ();
  }
}

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()

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();
}

// 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}`);
  }
}

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 client
    .api(`/me/onenote/sections/${sectionId}/pages`)
    .header("Content-Type", "text/html")
    .post(htmlContent);

  // CRITICAL: Check for silent failure — 200 with empty body
  if (!response || !response.id) {
    return {
      success: false,
      error: "Silent upload failure: API returned 200 but response body is empty. " +
        "This typically means the content was too large or contained invalid binary data.",
    };
  }

  return { success: true, pageId: response.id };
}

import { DeviceCodeCredential } from "@azure/identity";

class TokenRefreshMiddleware {
  private credential: DeviceCodeCredential;
  private cachedToken: string | null = null;
  private tokenExpiry: number = 0;

  constructor(credential: DeviceCodeCredential) {
    this.credential = credential;
  }

  async getValidToken(scopes: string[]): Promise<string> {
    const now = Date.now();
    // Refresh 5 minutes before expiry to avoid mid-request failures
    const REFRESH_BUFFER = 5 * 60 * 1000;

    if (this.cachedToken && this.tokenExpiry > now + REFRESH_BUFFER) {
      return this.cachedToken;
    }

    const tokenResponse = await this.credential.getToken(scopes);
    if (!tokenResponse) {
      throw new Error("Failed to acquire token — user may need to re-authenticate");
    }

    this.cachedToken = tokenResponse.token;
    this.tokenExpiry = tokenResponse.expiresOnTimestamp;
    return this.cachedToken;
  }
}

interface GraphError {
  statusCode: number;
  code: string;
  message: string;
  requestId: string;
  diagnostics: string;
  retryable: boolean;
}

function extractGraphError(error: any): GraphError {
  const statusCode = error.statusCode ?? error.code ?? 0;
  const body = error.body ? JSON.parse(error.body) : error;
  const innerError = body?.error ?? {};

  return {
    statusCode,
    code: innerError.code ?? "Unknown",
    message: innerError.message ?? error.message ?? "No message",
    requestId: error.headers?.get?.("request-id") ?? "unavailable",
    diagnostics: error.headers?.get?.("x-ms-ags-diagnostic") ?? "",
    retryable: [429, 502, 503, 504].includes(statusCode),
  };
}

Scenario	Detection	Recovery
429 rate limit	HTTP status code	Parse `Retry-After` header, wait exact seconds
Silent upload failure	200 status but `response.id` is undefined	Log error, check payload size, retry with smaller content
Token expired mid-batch	401 on individual batch response	Refresh token, retry failed batch items only
Tenant quota exceeded	429 with long Retry-After (>60s)	Switch to batch requests, reduce concurrency
502 Bad Gateway	HTTP status code	Exponential backoff, max 3 retries

const tracker = new RateLimitTracker();
const tokenMiddleware = new TokenRefreshMiddleware(credential);

async function graphRequest<T>(fn: () => Promise<T>): Promise<T> {
  const check = tracker.canMakeRequest();
  if (!check.allowed) {
    await new Promise((r) => setTimeout(r, check.waitMs));
  }
  tracker.recordRequest();

  try {
    return await fn();
  } catch (error) {
    const parsed = extractGraphError(error);
    if (parsed.retryable) {
      console.warn(`Retryable error: ${parsed.code} — ${parsed.message}`);
      // RetryHandler will handle the actual retry
    }
    throw error;
  }
}