n8n-nodes-onedrive-business 1.0.0

package/dist/utils/DeltaProcessor.d.ts

@@ -0,0 +1,91 @@
+import type { FileStabilityInfo, TriggerEvent } from '../types';
+import { GraphClient } from './GraphClient';
+import { StateStore } from './StateStore';
+/**
+ * Delta Query Processor for OneDrive Business
+ *
+ * This is the CORE deduplication engine that implements:
+ *
+ * 1. File Stability Checking
+ *    - Ensures files have completed uploading before processing
+ *    - Validates quickXorHash presence
+ *    - Checks timestamp alignment
+ *
+ * 2. Version-based Deduplication
+ *    - Tracks ${itemId}_${eTag} to identify unique versions
+ *    - Prevents multiple executions for the same file version
+ *
+ * 3. Stability Window
+ *    - Waits 15 seconds for files still being modified
+ *    - Prevents processing incomplete uploads
+ *
+ * 4. Event Classification
+ *    - Distinguishes 'created' vs 'updated' using eTag comparison
+ *    - Provides accurate event types to workflows
+ *
+ * WHY THIS IS NECESSARY:
+ * SharePoint-backed OneDrive generates multiple updates per upload:
+ * - File created (size=0)
+ * - Metadata updated
+ * - Content uploaded
+ * - Final metadata sync
+ *
+ * Without this processor, ONE file upload would trigger FOUR workflow executions.
+ */
+export declare class DeltaProcessor {
+    private graphClient;
+    private stateStore;
+    private drivePath;
+    private stabilityTracker;
+    private readonly STABILITY_WINDOW_MS;
+    constructor(graphClient: GraphClient, stateStore: StateStore, drivePath: string);
+    /**
+     * Process delta query and return triggerable events
+     *
+     * This is the main entry point called by the trigger node
+     */
+    processDeltaQuery(eventFilter: Set<string>): Promise<TriggerEvent[]>;
+    /**
+     * Fetch all pages from delta query
+     * Handles @odata.nextLink pagination and stores @odata.deltaLink
+     */
+    private fetchAllDeltaPages;
+    /**
+     * Process a single delta item
+     * Returns a TriggerEvent if the item should trigger a workflow
+     */
+    private processItem;
+    /**
+     * Classify event as created vs updated
+     *
+     * Logic:
+     * - If item NOT in lastKnownItems → created
+     * - If item eTag differs from lastKnownItems → updated
+     */
+    private classifyEvent;
+    /**
+     * Check if a file is stable and ready to be processed
+     *
+     * A file is considered stable when:
+     * 1. Size > 0 (not empty placeholder)
+     * 2. quickXorHash is present (upload complete)
+     * 3. lastModifiedDateTime matches fileSystemInfo.lastModifiedDateTime
+     * 4. At least 15 seconds have passed since last modification
+     *
+     * Returns true if stable, false if still being uploaded
+     */
+    private checkFileStability;
+    /**
+     * Track file stability over time
+     * Helps debug upload issues
+     */
+    private trackFileStability;
+    /**
+     * Get stability information for debugging
+     */
+    getStabilityInfo(itemId: string): FileStabilityInfo | undefined;
+    /**
+     * Clean up resources
+     */
+    dispose(): void;
+}

package/dist/utils/DeltaProcessor.js

@@ -0,0 +1,267 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DeltaProcessor = void 0;
+const helpers_1 = require("./helpers");
+/**
+ * Delta Query Processor for OneDrive Business
+ *
+ * This is the CORE deduplication engine that implements:
+ *
+ * 1. File Stability Checking
+ *    - Ensures files have completed uploading before processing
+ *    - Validates quickXorHash presence
+ *    - Checks timestamp alignment
+ *
+ * 2. Version-based Deduplication
+ *    - Tracks ${itemId}_${eTag} to identify unique versions
+ *    - Prevents multiple executions for the same file version
+ *
+ * 3. Stability Window
+ *    - Waits 15 seconds for files still being modified
+ *    - Prevents processing incomplete uploads
+ *
+ * 4. Event Classification
+ *    - Distinguishes 'created' vs 'updated' using eTag comparison
+ *    - Provides accurate event types to workflows
+ *
+ * WHY THIS IS NECESSARY:
+ * SharePoint-backed OneDrive generates multiple updates per upload:
+ * - File created (size=0)
+ * - Metadata updated
+ * - Content uploaded
+ * - Final metadata sync
+ *
+ * Without this processor, ONE file upload would trigger FOUR workflow executions.
+ */
+class DeltaProcessor {
+    constructor(graphClient, stateStore, drivePath) {
+        // Stability tracking for files currently being uploaded
+        this.stabilityTracker = new Map();
+        // Stability window: wait 15 seconds after last modification
+        this.STABILITY_WINDOW_MS = 15000;
+        this.graphClient = graphClient;
+        this.stateStore = stateStore;
+        this.drivePath = drivePath;
+    }
+    /**
+     * Process delta query and return triggerable events
+     *
+     * This is the main entry point called by the trigger node
+     */
+    async processDeltaQuery(eventFilter // e.g., ['file.created', 'file.updated']
+    ) {
+        const events = [];
+        try {
+            // Get current state
+            const state = this.stateStore.getState();
+            // Determine the delta endpoint
+            let deltaEndpoint;
+            if (state.deltaLink) {
+                // Use existing delta link (contains the full URL)
+                // Extract the path after /v1.0
+                const deltaUrl = new URL(state.deltaLink);
+                deltaEndpoint = deltaUrl.pathname.replace('/v1.0', '') + deltaUrl.search;
+            }
+            else {
+                // Initial delta query
+                deltaEndpoint = `${this.drivePath}/root/delta`;
+            }
+            // Fetch delta changes (handle pagination)
+            const items = await this.fetchAllDeltaPages(deltaEndpoint);
+            // Process each item
+            for (const item of items) {
+                const event = await this.processItem(item, eventFilter);
+                if (event) {
+                    events.push(event);
+                }
+            }
+            return events;
+        }
+        catch (error) {
+            console.error('Error processing delta query:', error);
+            throw error;
+        }
+    }
+    /**
+     * Fetch all pages from delta query
+     * Handles @odata.nextLink pagination and stores @odata.deltaLink
+     */
+    async fetchAllDeltaPages(initialEndpoint) {
+        const allItems = [];
+        let currentEndpoint = initialEndpoint;
+        while (currentEndpoint) {
+            const response = await this.graphClient.get(currentEndpoint);
+            allItems.push(...response.value);
+            // Check for next page
+            if (response['@odata.nextLink']) {
+                // Extract path from full URL
+                const url = new URL(response['@odata.nextLink']);
+                currentEndpoint = url.pathname.replace('/v1.0', '') + url.search;
+            }
+            else if (response['@odata.deltaLink']) {
+                // Save delta link for next run
+                await this.stateStore.updateDeltaLink(response['@odata.deltaLink']);
+                currentEndpoint = '';
+            }
+            else {
+                // No more pages
+                currentEndpoint = '';
+            }
+        }
+        return allItems;
+    }
+    /**
+     * Process a single delta item
+     * Returns a TriggerEvent if the item should trigger a workflow
+     */
+    async processItem(item, eventFilter) {
+        // Skip deleted items (unless specifically requested)
+        if (item.deleted) {
+            return null;
+        }
+        // Skip root folder
+        if (!item.parentReference) {
+            return null;
+        }
+        // Determine event type
+        const eventType = this.classifyEvent(item);
+        // Check if this event type is enabled
+        if (!eventFilter.has(eventType)) {
+            return null;
+        }
+        // Check if already processed (deduplication)
+        const versionKey = (0, helpers_1.buildVersionKey)(item.id, item.eTag);
+        if (this.stateStore.isVersionProcessed(item.id, item.eTag)) {
+            // Already processed this version
+            return null;
+        }
+        // For files, check stability
+        if ((0, helpers_1.isFile)(item)) {
+            const isStable = await this.checkFileStability(item);
+            if (!isStable) {
+                // File is still being uploaded/modified, skip for now
+                return null;
+            }
+        }
+        // Mark as processed
+        await this.stateStore.markVersionProcessed(item.id, item.eTag);
+        // Update last known state
+        await this.stateStore.updateLastKnownItem(item.id, item.eTag, item.lastModifiedDateTime);
+        // Return the event
+        return {
+            eventType,
+            item,
+            timestamp: new Date().toISOString(),
+        };
+    }
+    /**
+     * Classify event as created vs updated
+     *
+     * Logic:
+     * - If item NOT in lastKnownItems → created
+     * - If item eTag differs from lastKnownItems → updated
+     */
+    classifyEvent(item) {
+        const lastKnown = this.stateStore.getLastKnownItem(item.id);
+        const isFileItem = (0, helpers_1.isFile)(item);
+        const isFolderItem = (0, helpers_1.isFolder)(item);
+        if (!lastKnown) {
+            // New item
+            if (isFileItem) {
+                return 'file.created';
+            }
+            else if (isFolderItem) {
+                return 'folder.created';
+            }
+        }
+        else {
+            // Existing item
+            if (lastKnown.eTag !== item.eTag) {
+                if (isFileItem) {
+                    return 'file.updated';
+                }
+                else if (isFolderItem) {
+                    return 'folder.updated';
+                }
+            }
+        }
+        // Default to updated
+        return isFileItem ? 'file.updated' : 'folder.updated';
+    }
+    /**
+     * Check if a file is stable and ready to be processed
+     *
+     * A file is considered stable when:
+     * 1. Size > 0 (not empty placeholder)
+     * 2. quickXorHash is present (upload complete)
+     * 3. lastModifiedDateTime matches fileSystemInfo.lastModifiedDateTime
+     * 4. At least 15 seconds have passed since last modification
+     *
+     * Returns true if stable, false if still being uploaded
+     */
+    async checkFileStability(item) {
+        var _a, _b, _c;
+        // Basic stability checks
+        const hasSize = item.size > 0;
+        const hasHash = !!((_b = (_a = item.file) === null || _a === void 0 ? void 0 : _a.hashes) === null || _b === void 0 ? void 0 : _b.quickXorHash);
+        const timestampsAlign = item.lastModifiedDateTime === ((_c = item.fileSystemInfo) === null || _c === void 0 ? void 0 : _c.lastModifiedDateTime);
+        const basicStability = hasSize && hasHash && timestampsAlign;
+        if (!basicStability) {
+            // Track this file for stability checking
+            this.trackFileStability(item, false);
+            return false;
+        }
+        // Check stability window (15 seconds)
+        const lastModified = new Date(item.lastModifiedDateTime).getTime();
+        const now = Date.now();
+        const timeSinceModification = now - lastModified;
+        if (timeSinceModification < this.STABILITY_WINDOW_MS) {
+            // File was modified recently, wait longer
+            this.trackFileStability(item, false);
+            return false;
+        }
+        // File is stable
+        this.trackFileStability(item, true);
+        return true;
+    }
+    /**
+     * Track file stability over time
+     * Helps debug upload issues
+     */
+    trackFileStability(item, isStable) {
+        var _a, _b;
+        const now = Date.now();
+        const existing = this.stabilityTracker.get(item.id);
+        const stabilityInfo = {
+            itemId: item.id,
+            eTag: item.eTag,
+            size: item.size,
+            lastModifiedDateTime: item.lastModifiedDateTime,
+            hasHash: !!((_b = (_a = item.file) === null || _a === void 0 ? void 0 : _a.hashes) === null || _b === void 0 ? void 0 : _b.quickXorHash),
+            isStable,
+            firstSeen: (existing === null || existing === void 0 ? void 0 : existing.firstSeen) || now,
+            lastChecked: now,
+        };
+        this.stabilityTracker.set(item.id, stabilityInfo);
+        // Clean up old entries (keep only last hour)
+        const oneHourAgo = now - 3600000;
+        for (const [itemId, info] of this.stabilityTracker.entries()) {
+            if (info.lastChecked < oneHourAgo) {
+                this.stabilityTracker.delete(itemId);
+            }
+        }
+    }
+    /**
+     * Get stability information for debugging
+     */
+    getStabilityInfo(itemId) {
+        return this.stabilityTracker.get(itemId);
+    }
+    /**
+     * Clean up resources
+     */
+    dispose() {
+        this.stabilityTracker.clear();
+    }
+}
+exports.DeltaProcessor = DeltaProcessor;

package/dist/utils/GraphClient.d.ts

@@ -0,0 +1,67 @@
+/// <reference types="node" />
+/// <reference types="node" />
+import { IExecuteFunctions, IHookFunctions, IPollFunctions } from 'n8n-workflow';
+import type { DriveItem, RetryConfig } from '../types';
+/**
+ * Microsoft Graph API Client
+ *
+ * Centralized client for all Microsoft Graph API interactions.
+ * Handles:
+ * - Authentication (OAuth2 token management)
+ * - Retry logic with exponential backoff
+ * - 429 Throttling handling
+ * - Error normalization
+ * - Request/response type safety
+ */
+export declare class GraphClient {
+    private baseUrl;
+    private context;
+    private retryConfig;
+    constructor(context: IExecuteFunctions | IHookFunctions | IPollFunctions, retryConfig?: Partial<RetryConfig>);
+    /**
+     * Make a GET request to Microsoft Graph API
+     */
+    get<T = any>(endpoint: string, queryParameters?: Record<string, any>): Promise<T>;
+    /**
+     * Make a POST request to Microsoft Graph API
+     */
+    post<T = any>(endpoint: string, body?: any, queryParameters?: Record<string, any>): Promise<T>;
+    /**
+     * Make a PATCH request to Microsoft Graph API
+     */
+    patch<T = any>(endpoint: string, body?: any, queryParameters?: Record<string, any>): Promise<T>;
+    /**
+     * Make a PUT request to Microsoft Graph API
+     */
+    put<T = any>(endpoint: string, body?: any, queryParameters?: Record<string, any>): Promise<T>;
+    /**
+     * Make a DELETE request to Microsoft Graph API
+     */
+    delete<T = any>(endpoint: string, queryParameters?: Record<string, any>): Promise<T>;
+    /**
+     * Download binary content from Microsoft Graph
+     */
+    downloadBinary(endpoint: string): Promise<Buffer>;
+    /**
+     * Upload binary content to Microsoft Graph
+     */
+    uploadBinary(endpoint: string, binaryData: Buffer, contentType?: string): Promise<DriveItem>;
+    /**
+     * Fetch all pages from a paginated endpoint
+     * Automatically follows @odata.nextLink
+     */
+    getAllPages<T>(endpoint: string, queryParameters?: Record<string, any>): Promise<T[]>;
+    /**
+     * Core request method with retry logic
+     */
+    private request;
+    /**
+     * Execute request with exponential backoff retry logic
+     * Handles 429 throttling and transient errors
+     */
+    private executeWithRetry;
+    /**
+     * Normalize errors to NodeApiError
+     */
+    private handleError;
+}

package/dist/utils/GraphClient.js

@@ -0,0 +1,182 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GraphClient = void 0;
+const n8n_workflow_1 = require("n8n-workflow");
+const helpers_1 = require("./helpers");
+/**
+ * Microsoft Graph API Client
+ *
+ * Centralized client for all Microsoft Graph API interactions.
+ * Handles:
+ * - Authentication (OAuth2 token management)
+ * - Retry logic with exponential backoff
+ * - 429 Throttling handling
+ * - Error normalization
+ * - Request/response type safety
+ */
+class GraphClient {
+    constructor(context, retryConfig) {
+        var _a, _b, _c, _d;
+        this.baseUrl = 'https://graph.microsoft.com/v1.0';
+        this.context = context;
+        this.retryConfig = {
+            maxRetries: (_a = retryConfig === null || retryConfig === void 0 ? void 0 : retryConfig.maxRetries) !== null && _a !== void 0 ? _a : 3,
+            initialDelayMs: (_b = retryConfig === null || retryConfig === void 0 ? void 0 : retryConfig.initialDelayMs) !== null && _b !== void 0 ? _b : 1000,
+            maxDelayMs: (_c = retryConfig === null || retryConfig === void 0 ? void 0 : retryConfig.maxDelayMs) !== null && _c !== void 0 ? _c : 60000,
+            backoffMultiplier: (_d = retryConfig === null || retryConfig === void 0 ? void 0 : retryConfig.backoffMultiplier) !== null && _d !== void 0 ? _d : 2,
+        };
+    }
+    /**
+     * Make a GET request to Microsoft Graph API
+     */
+    async get(endpoint, queryParameters) {
+        return this.request('GET', endpoint, undefined, queryParameters);
+    }
+    /**
+     * Make a POST request to Microsoft Graph API
+     */
+    async post(endpoint, body, queryParameters) {
+        return this.request('POST', endpoint, body, queryParameters);
+    }
+    /**
+     * Make a PATCH request to Microsoft Graph API
+     */
+    async patch(endpoint, body, queryParameters) {
+        return this.request('PATCH', endpoint, body, queryParameters);
+    }
+    /**
+     * Make a PUT request to Microsoft Graph API
+     */
+    async put(endpoint, body, queryParameters) {
+        return this.request('PUT', endpoint, body, queryParameters);
+    }
+    /**
+     * Make a DELETE request to Microsoft Graph API
+     */
+    async delete(endpoint, queryParameters) {
+        return this.request('DELETE', endpoint, undefined, queryParameters);
+    }
+    /**
+     * Download binary content from Microsoft Graph
+     */
+    async downloadBinary(endpoint) {
+        const options = {
+            method: 'GET',
+            url: `${this.baseUrl}${endpoint}`,
+            encoding: null, // Return as Buffer
+            json: false,
+        };
+        try {
+            const response = await this.executeWithRetry(options);
+            return Buffer.from(response);
+        }
+        catch (error) {
+            throw this.handleError(error, 'GET', endpoint);
+        }
+    }
+    /**
+     * Upload binary content to Microsoft Graph
+     */
+    async uploadBinary(endpoint, binaryData, contentType = 'application/octet-stream') {
+        const options = {
+            method: 'PUT',
+            url: `${this.baseUrl}${endpoint}`,
+            body: binaryData,
+            headers: {
+                'Content-Type': contentType,
+            },
+            json: false,
+        };
+        try {
+            const response = await this.executeWithRetry(options);
+            // Parse the JSON response
+            return typeof response === 'string' ? JSON.parse(response) : response;
+        }
+        catch (error) {
+            throw this.handleError(error, 'PUT', endpoint);
+        }
+    }
+    /**
+     * Fetch all pages from a paginated endpoint
+     * Automatically follows @odata.nextLink
+     */
+    async getAllPages(endpoint, queryParameters) {
+        const allItems = [];
+        let nextLink = endpoint;
+        while (nextLink) {
+            const response = await this.get(nextLink, 
+            // Only send query parameters on the first request
+            nextLink === endpoint ? queryParameters : undefined);
+            allItems.push(...response.value);
+            nextLink = response['@odata.nextLink'];
+        }
+        return allItems;
+    }
+    /**
+     * Core request method with retry logic
+     */
+    async request(method, endpoint, body, queryParameters) {
+        const options = {
+            method,
+            url: `${this.baseUrl}${endpoint}`,
+            json: true,
+        };
+        if (body !== undefined) {
+            options.body = body;
+        }
+        if (queryParameters) {
+            options.qs = queryParameters;
+        }
+        try {
+            return await this.executeWithRetry(options);
+        }
+        catch (error) {
+            throw this.handleError(error, method, endpoint);
+        }
+    }
+    /**
+     * Execute request with exponential backoff retry logic
+     * Handles 429 throttling and transient errors
+     */
+    async executeWithRetry(options, retryCount = 0) {
+        var _a, _b;
+        try {
+            return await this.context.helpers.requestOAuth2.call(this.context, 'oneDriveBusinessOAuth2Api', options);
+        }
+        catch (error) {
+            const statusCode = error.statusCode || ((_a = error.response) === null || _a === void 0 ? void 0 : _a.statusCode);
+            // Handle 429 Too Many Requests (Throttling)
+            if (statusCode === 429) {
+                if (retryCount < this.retryConfig.maxRetries) {
+                    const retryAfter = (0, helpers_1.parseRetryAfter)((_b = error.response) === null || _b === void 0 ? void 0 : _b.headers['retry-after']);
+                    await (0, helpers_1.sleep)(retryAfter);
+                    return this.executeWithRetry(options, retryCount + 1);
+                }
+            }
+            // Handle transient errors (5xx)
+            if (statusCode >= 500 && statusCode < 600) {
+                if (retryCount < this.retryConfig.maxRetries) {
+                    const delay = (0, helpers_1.calculateBackoffDelay)(retryCount, this.retryConfig.initialDelayMs, this.retryConfig.maxDelayMs, this.retryConfig.backoffMultiplier);
+                    await (0, helpers_1.sleep)(delay);
+                    return this.executeWithRetry(options, retryCount + 1);
+                }
+            }
+            // No retry for other errors
+            throw error;
+        }
+    }
+    /**
+     * Normalize errors to NodeApiError
+     */
+    handleError(error, method, endpoint) {
+        var _a;
+        const parsedError = (0, helpers_1.parseGraphError)(error.error || error);
+        const errorMessage = `Microsoft Graph API Error [${method} ${endpoint}]: ${parsedError.code} - ${parsedError.message}`;
+        return new n8n_workflow_1.NodeApiError(this.context.getNode(), error, {
+            message: errorMessage,
+            description: parsedError.message,
+            httpCode: (_a = error.statusCode) === null || _a === void 0 ? void 0 : _a.toString(),
+        });
+    }
+}
+exports.GraphClient = GraphClient;

package/dist/utils/StateStore.d.ts

@@ -0,0 +1,96 @@
+import type { NodeState } from '../types';
+/**
+ * State Store for OneDrive Business Trigger Node
+ *
+ * Provides persistent storage for:
+ * - Delta query links
+ * - Processed file versions (deduplication)
+ * - Last known item states (for event classification)
+ * - Webhook subscription information
+ *
+ * State MUST survive n8n restarts and redeployments to prevent:
+ * - Duplicate workflow executions
+ * - Re-processing old changes
+ * - Losing track of processed items
+ */
+export declare class StateStore {
+    private stateFilePath;
+    private nodeId;
+    private state;
+    private saveDebounceTimer;
+    constructor(nodeId: string, storageDir?: string);
+    /**
+     * Initialize and load state from disk
+     * Creates default state if file doesn't exist
+     */
+    initialize(tenantId: string, driveId: string, userId?: string, siteId?: string): Promise<NodeState>;
+    /**
+     * Get current state
+     * Throws if not initialized
+     */
+    getState(): NodeState;
+    /**
+     * Update delta link
+     */
+    updateDeltaLink(deltaLink: string): Promise<void>;
+    /**
+     * Mark a file version as processed
+     * Returns true if this version was NOT already processed
+     */
+    markVersionProcessed(itemId: string, eTag: string): Promise<boolean>;
+    /**
+     * Check if a version has been processed
+     */
+    isVersionProcessed(itemId: string, eTag: string): boolean;
+    /**
+     * Update last known state of an item
+     * Used for event classification (created vs updated)
+     */
+    updateLastKnownItem(itemId: string, eTag: string, lastModifiedDateTime: string): Promise<void>;
+    /**
+     * Get last known state of an item
+     */
+    getLastKnownItem(itemId: string): {
+        eTag: string;
+        lastModifiedDateTime: string;
+    } | null;
+    /**
+     * Update webhook subscription information
+     */
+    updateSubscription(subscriptionId: string, expirationTimestamp: number): Promise<void>;
+    /**
+     * Clear webhook subscription information
+     */
+    clearSubscription(): Promise<void>;
+    /**
+     * Clean up old processed versions to prevent unbounded growth
+     * Keeps only the most recent versions per item
+     */
+    cleanupOldVersions(maxVersionsPerItem?: number): Promise<void>;
+    /**
+     * Create default state
+     */
+    private createDefaultState;
+    /**
+     * Ensure state directory exists
+     */
+    private ensureStateDirectory;
+    /**
+     * Load state from disk
+     */
+    private loadFromDisk;
+    /**
+     * Save state to disk immediately
+     */
+    private saveToDisk;
+    /**
+     * Save state to disk with debouncing
+     * Prevents excessive writes during rapid updates
+     */
+    private saveToDiskDebounced;
+    /**
+     * Force save any pending changes
+     * Call this before deactivating the node
+     */
+    flush(): Promise<void>;
+}