specs: migrate to ms graph

Author: komplexb

.kiro/specs/ms-graph-migration/design.md

@@ -0,0 +1,263 @@
+# Design Document
+
+## Overview
+
+This design outlines the migration from direct REST API calls using superagent to the official Microsoft Graph SDK (@microsoft/microsoft-graph-client) for OneNote operations. The migration will maintain all existing functionality while leveraging the SDK's built-in features including automatic retries, better error handling, and improved authentication integration.
+
+The current system uses direct HTTP calls to Microsoft Graph endpoints for OneNote operations including retrieving sections, pages, page content, and image downloads. The new implementation will use the Graph SDK's fluent API while preserving the exact same behavior and data flow.
+
+## Architecture
+
+### Current Architecture
+```
+MSAL Authentication → superagent HTTP calls → OneNote REST API
+```
+
+### New Architecture
+```
+MSAL Authentication → Graph SDK Client → OneNote REST API
+```
+
+### Authentication Integration
+
+The Graph SDK will integrate with the existing MSAL authentication system through a custom authentication provider that bridges the current token management with the SDK's authentication interface.
+
+```javascript
+class MSALAuthenticationProvider {
+  async getAccessToken() {
+    const onenoteData = localStorage.getItem('onenote');
+    if (!onenoteData || !onenoteData.accessToken) {
+      throw new Error('No access token available');
+    }
+    return onenoteData.accessToken;
+  }
+}
+```
+
+## Components and Interfaces
+
+### 1. Authentication Provider Bridge
+
+**Purpose**: Bridge existing MSAL token management with Graph SDK authentication requirements
+
+**Implementation**:
+- Implements the Graph SDK's `AuthenticationProvider` interface
+- Retrieves tokens from existing localStorage cache
+- Handles token expiration by delegating to existing refresh mechanisms
+
+### 2. Graph Client Factory
+
+**Purpose**: Create and configure the Microsoft Graph client instance
+
+**Implementation**:
+```javascript
+function createGraphClient() {
+  const authProvider = new MSALAuthenticationProvider();
+  
+  return Client.initWithMiddleware({
+    authProvider,
+    defaultVersion: 'v1.0',
+    debugLogging: process.env.NODE_ENV === 'development'
+  });
+}
+```
+
+### 3. OneNote Service Layer
+
+**Purpose**: Encapsulate all OneNote operations using the Graph SDK
+
+**Key Methods**:
+- `getSections(notebookName, sectionName)` - Find section by notebook and name
+- `getPageCount(sectionId)` - Get total page count for a section
+- `getPages(sectionId, options)` - Get pages with pagination
+- `getPagePreview(pageId)` - Get page preview content
+- `getPageContent(pageId)` - Get full page HTML content
+- `downloadImage(imageUrl)` - Download images from Graph endpoints
+
+### 4. Migration Wrapper
+
+**Purpose**: Provide backward compatibility during migration
+
+**Implementation**: Maintains the same function signatures as existing code while internally using the Graph SDK.
+
+## Data Models
+
+### Section Model
+```javascript
+{
+  id: string,
+  displayName: string,
+  pagesUrl: string,
+  parentNotebook: {
+    displayName: string,
+    sectionsUrl: string
+  }
+}
+```
+
+### Page Model
+```javascript
+{
+  id: string,
+  title: string,
+  self: string,
+  links: {
+    oneNoteClientUrl: { href: string },
+    oneNoteWebUrl: { href: string }
+  }
+}
+```
+
+### Page Preview Model
+```javascript
+{
+  previewText: string,
+  links: {
+    previewImageUrl?: { href: string }
+  }
+}
+```
+
+## Error Handling
+
+### SDK Error Mapping
+
+The Graph SDK provides enhanced error handling that will be mapped to maintain compatibility with existing error handling patterns:
+
+```javascript
+function mapGraphError(error) {
+  // Map Graph SDK errors to existing error format
+  if (error.code === 'InvalidAuthenticationToken') {
+    throw new Error('Token refresh failed - device login required');
+  }
+  
+  if (error.code === 'TooManyRequests') {
+    // SDK handles retries automatically, but we can add custom logic
+    throw new Error('Rate limit exceeded');
+  }
+  
+  // Preserve original error structure for unknown errors
+  throw error;
+}
+```
+
+### Timeout Configuration
+
+Configure SDK timeouts to match existing behavior:
+
+```javascript
+const client = Client.initWithMiddleware({
+  authProvider,
+  middleware: [
+    new TimeoutHandler({
+      timeout: 120000 // 120 seconds to match existing TIMEOUTS.response
+    })
+  ]
+});
+```
+
+## Testing Strategy
+
+### Unit Tests
+
+1. **Authentication Provider Tests**
+   - Test token retrieval from localStorage
+   - Test error handling when tokens are missing/expired
+   - Test integration with existing MSAL flow
+
+2. **OneNote Service Tests**
+   - Mock Graph SDK client responses
+   - Test all OneNote operations (sections, pages, content, images)
+   - Verify data transformation matches existing format
+   - Test error scenarios and mapping
+
+3. **Integration Tests**
+   - Test complete flow from authentication to data retrieval
+   - Verify backward compatibility with existing function signatures
+   - Test timeout and retry behavior
+
+### Migration Testing
+
+1. **Parallel Testing**
+   - Run both old and new implementations side-by-side
+   - Compare outputs to ensure identical behavior
+   - Measure performance differences
+
+2. **Feature Parity Tests**
+   - Random note selection produces same distribution
+   - Sequential note tracking works identically
+   - Image download maintains size limits and streaming
+   - Recent note filtering behaves the same
+
+## Implementation Plan
+
+### Phase 1: Foundation
+- Install Graph SDK and fetch polyfill dependencies
+- Create authentication provider bridge
+- Set up Graph client factory with proper configuration
+
+### Phase 2: Core Services
+- Implement OneNote service layer using Graph SDK
+- Create migration wrapper maintaining existing interfaces
+- Add comprehensive error handling and mapping
+
+### Phase 3: Feature Migration
+- Replace section lookup functionality
+- Replace page counting and retrieval
+- Replace page preview and content operations
+- Replace image download functionality
+
+### Phase 4: Testing & Validation
+- Implement comprehensive test suite
+- Run parallel testing to verify behavior
+- Performance testing and optimization
+- Remove superagent dependency if no longer needed
+
+## Configuration Changes
+
+### Package.json Updates
+```json
+{
+  "dependencies": {
+    "@microsoft/microsoft-graph-client": "^3.0.7",
+    "isomorphic-fetch": "^3.0.0"
+  }
+}
+```
+
+### Environment Variables
+No new environment variables required - existing MS Graph configuration will be reused.
+
+## Backward Compatibility
+
+The migration maintains 100% backward compatibility by:
+
+1. **Preserving Function Signatures**: All existing function calls work unchanged
+2. **Maintaining Data Structures**: Response objects have identical structure
+3. **Keeping Error Patterns**: Error messages and types remain consistent
+4. **Preserving Behavior**: Random selection, sequential tracking, and caching work identically
+
+## Performance Considerations
+
+### Expected Improvements
+- **Automatic Retries**: SDK handles transient failures automatically
+- **Connection Pooling**: Better HTTP connection management
+- **Request Optimization**: SDK optimizes Graph API calls
+
+### Monitoring Points
+- Response times for OneNote operations
+- Memory usage during image downloads
+- Error rates and retry patterns
+- Token refresh frequency
+
+## Security Considerations
+
+### Token Handling
+- Graph SDK never stores tokens - relies on our authentication provider
+- Existing MSAL security model remains unchanged
+- Token refresh logic preserved exactly
+
+### Image Downloads
+- Maintain existing 3MB size limits
+- Preserve streaming download behavior for large files
+- Keep existing timeout protections

.kiro/specs/ms-graph-migration/requirements.md

@@ -0,0 +1,73 @@
+# Requirements Document
+
+## Introduction
+
+This feature involves migrating the existing OneNote API integration from direct REST API calls using superagent to the official Microsoft Graph SDK (@microsoft/microsoft-graph-client). The current system retrieves random or sequential notes from OneNote sections and sends them via Telegram notifications. The migration should maintain all existing functionality while leveraging the benefits of the official SDK including better error handling, automatic retries, and improved type safety.
+
+## Requirements
+
+### Requirement 1
+
+**User Story:** As a system administrator, I want the OneNote integration to use the official Microsoft Graph SDK, so that the system benefits from improved reliability, better error handling, and official Microsoft support.
+
+#### Acceptance Criteria
+
+1. WHEN the system initializes THEN it SHALL use @microsoft/microsoft-graph-client instead of direct superagent calls
+2. WHEN making Graph API requests THEN the system SHALL use the Graph SDK's built-in authentication handling
+3. WHEN API errors occur THEN the system SHALL leverage the SDK's enhanced error handling and retry mechanisms
+4. WHEN the migration is complete THEN all existing OneNote functionality SHALL work identically to the current implementation
+
+### Requirement 2
+
+**User Story:** As a developer, I want comprehensive tests for the migrated OneNote functionality, so that I can ensure the migration maintains all existing behavior and catches any regressions.
+
+#### Acceptance Criteria
+
+1. WHEN tests are written THEN they SHALL cover all OneNote API operations (getNote, getNoteCount, setNoteSection, getNotePreview, getNoteContents)
+2. WHEN tests run THEN they SHALL verify authentication token handling works correctly with the Graph SDK
+3. WHEN tests execute THEN they SHALL validate that random and sequential note retrieval functions identically to the current implementation
+4. WHEN tests complete THEN they SHALL confirm that image extraction and download functionality remains unchanged
+
+### Requirement 3
+
+**User Story:** As a system user, I want the note retrieval functionality to work exactly as before, so that my Telegram notifications continue to deliver the same OneNote content without interruption.
+
+#### Acceptance Criteria
+
+1. WHEN retrieving notes in random mode THEN the system SHALL return random notes from the specified section with the same distribution as before
+2. WHEN retrieving notes in sequential mode THEN the system SHALL return notes in the same order and track the last page identically
+3. WHEN getting note previews THEN the system SHALL return the same preview text and metadata as the current implementation
+4. WHEN extracting images THEN the system SHALL download and process images with the same size limits and error handling
+
+### Requirement 4
+
+**User Story:** As a system maintainer, I want the authentication flow to remain unchanged, so that existing token management and device login processes continue to work without modification.
+
+#### Acceptance Criteria
+
+1. WHEN using the Graph SDK THEN it SHALL integrate seamlessly with the existing MSAL authentication system
+2. WHEN tokens are refreshed THEN the Graph SDK SHALL use the same cached tokens from the current MSAL implementation
+3. WHEN authentication fails THEN the system SHALL trigger the same device login flow as currently implemented
+4. WHEN tokens expire THEN the Graph SDK SHALL handle token refresh transparently using existing mechanisms
+
+### Requirement 5
+
+**User Story:** As a developer, I want the migration to include proper dependency management, so that the new Graph SDK is correctly installed and configured while removing unused dependencies.
+
+#### Acceptance Criteria
+
+1. WHEN installing dependencies THEN the system SHALL add @microsoft/microsoft-graph-client and appropriate fetch polyfill
+2. WHEN the migration is complete THEN superagent dependency SHALL be removed if no longer needed elsewhere
+3. WHEN the application starts THEN it SHALL import and configure the Graph SDK with proper authentication middleware
+4. WHEN making API calls THEN the system SHALL use the Graph SDK's fluent API instead of manual URL construction
+
+### Requirement 6
+
+**User Story:** As a system operator, I want the migrated system to maintain the same performance characteristics, so that note retrieval times and resource usage remain consistent.
+
+#### Acceptance Criteria
+
+1. WHEN retrieving notes THEN response times SHALL be comparable to or better than the current implementation
+2. WHEN handling timeouts THEN the Graph SDK SHALL respect the same timeout values (120s response, 60s deadline)
+3. WHEN processing large images THEN the system SHALL maintain the same 3MB size limits and streaming download behavior
+4. WHEN caching data THEN the system SHALL continue to use the same localStorage and DynamoDB persistence patterns