n8n-nodes-onedrive-business 1.0.0

package/dist/utils/StateStore.js

@@ -0,0 +1,280 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StateStore = void 0;
+const fs_1 = require("fs");
+const path_1 = require("path");
+/**
+ * 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
+ */
+class StateStore {
+    constructor(nodeId, storageDir = '.n8n-state') {
+        this.state = null;
+        this.saveDebounceTimer = null;
+        this.nodeId = nodeId;
+        // Store state in .n8n-state directory within the n8n user directory
+        // This ensures persistence across restarts
+        const userHome = process.env.N8N_USER_FOLDER || process.env.HOME || process.env.USERPROFILE || '/tmp';
+        const stateDir = (0, path_1.join)(userHome, storageDir, 'onedrive-business');
+        this.stateFilePath = (0, path_1.join)(stateDir, `${nodeId}.json`);
+    }
+    /**
+     * Initialize and load state from disk
+     * Creates default state if file doesn't exist
+     */
+    async initialize(tenantId, driveId, userId, siteId) {
+        try {
+            await this.ensureStateDirectory();
+            // Try to load existing state
+            const existingState = await this.loadFromDisk();
+            if (existingState) {
+                // Validate that the state matches the current configuration
+                if (existingState.tenantId === tenantId &&
+                    existingState.driveId === driveId) {
+                    this.state = existingState;
+                    return this.state;
+                }
+                // Configuration changed, reset state
+                console.log(`OneDrive Business state configuration changed for node ${this.nodeId}, resetting state`);
+            }
+            // Create fresh state
+            this.state = this.createDefaultState(tenantId, driveId, userId, siteId);
+            await this.saveToDisk();
+            return this.state;
+        }
+        catch (error) {
+            console.error(`Failed to initialize state for node ${this.nodeId}:`, error);
+            // Return default state even if loading fails
+            this.state = this.createDefaultState(tenantId, driveId, userId, siteId);
+            return this.state;
+        }
+    }
+    /**
+     * Get current state
+     * Throws if not initialized
+     */
+    getState() {
+        if (!this.state) {
+            throw new Error('State not initialized. Call initialize() first.');
+        }
+        return this.state;
+    }
+    /**
+     * Update delta link
+     */
+    async updateDeltaLink(deltaLink) {
+        if (!this.state) {
+            throw new Error('State not initialized');
+        }
+        this.state.deltaLink = deltaLink;
+        this.state.lastDeltaQuery = Date.now();
+        await this.saveToDiskDebounced();
+    }
+    /**
+     * Mark a file version as processed
+     * Returns true if this version was NOT already processed
+     */
+    async markVersionProcessed(itemId, eTag) {
+        if (!this.state) {
+            throw new Error('State not initialized');
+        }
+        const versionKey = `${itemId}_${eTag}`;
+        // Check if already processed
+        if (this.state.processedVersions[versionKey]) {
+            return false; // Already processed
+        }
+        // Mark as processed
+        this.state.processedVersions[versionKey] = true;
+        // Save asynchronously
+        await this.saveToDiskDebounced();
+        return true; // Newly processed
+    }
+    /**
+     * Check if a version has been processed
+     */
+    isVersionProcessed(itemId, eTag) {
+        if (!this.state) {
+            return false;
+        }
+        const versionKey = `${itemId}_${eTag}`;
+        return !!this.state.processedVersions[versionKey];
+    }
+    /**
+     * Update last known state of an item
+     * Used for event classification (created vs updated)
+     */
+    async updateLastKnownItem(itemId, eTag, lastModifiedDateTime) {
+        if (!this.state) {
+            throw new Error('State not initialized');
+        }
+        this.state.lastKnownItems[itemId] = {
+            eTag,
+            lastModifiedDateTime,
+        };
+        await this.saveToDiskDebounced();
+    }
+    /**
+     * Get last known state of an item
+     */
+    getLastKnownItem(itemId) {
+        if (!this.state) {
+            return null;
+        }
+        return this.state.lastKnownItems[itemId] || null;
+    }
+    /**
+     * Update webhook subscription information
+     */
+    async updateSubscription(subscriptionId, expirationTimestamp) {
+        if (!this.state) {
+            throw new Error('State not initialized');
+        }
+        this.state.subscriptionId = subscriptionId;
+        this.state.subscriptionExpiration = expirationTimestamp;
+        await this.saveToDiskDebounced();
+    }
+    /**
+     * Clear webhook subscription information
+     */
+    async clearSubscription() {
+        if (!this.state) {
+            throw new Error('State not initialized');
+        }
+        this.state.subscriptionId = undefined;
+        this.state.subscriptionExpiration = undefined;
+        await this.saveToDiskDebounced();
+    }
+    /**
+     * Clean up old processed versions to prevent unbounded growth
+     * Keeps only the most recent versions per item
+     */
+    async cleanupOldVersions(maxVersionsPerItem = 10) {
+        if (!this.state) {
+            throw new Error('State not initialized');
+        }
+        // Group versions by itemId
+        const itemVersions = {};
+        for (const versionKey of Object.keys(this.state.processedVersions)) {
+            const [itemId] = versionKey.split('_');
+            if (!itemVersions[itemId]) {
+                itemVersions[itemId] = [];
+            }
+            itemVersions[itemId].push(versionKey);
+        }
+        // Keep only recent versions
+        const cleaned = {};
+        for (const itemId of Object.keys(itemVersions)) {
+            const versions = itemVersions[itemId];
+            // Sort by eTag (not perfect, but good enough)
+            // In production, you might want to use timestamps
+            versions.sort();
+            // Keep the last N versions
+            const toKeep = versions.slice(-maxVersionsPerItem);
+            for (const versionKey of toKeep) {
+                cleaned[versionKey] = true;
+            }
+        }
+        this.state.processedVersions = cleaned;
+        await this.saveToDisk();
+        console.log(`Cleaned up old versions for node ${this.nodeId}. Kept ${Object.keys(cleaned).length} versions.`);
+    }
+    /**
+     * Create default state
+     */
+    createDefaultState(tenantId, driveId, userId, siteId) {
+        return {
+            tenantId,
+            driveId,
+            userId,
+            siteId,
+            deltaLink: null,
+            lastDeltaQuery: 0,
+            processedVersions: {},
+            lastKnownItems: {},
+        };
+    }
+    /**
+     * Ensure state directory exists
+     */
+    async ensureStateDirectory() {
+        const dir = this.stateFilePath.substring(0, this.stateFilePath.lastIndexOf('/'));
+        try {
+            await fs_1.promises.mkdir(dir, { recursive: true });
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST') {
+                throw error;
+            }
+        }
+    }
+    /**
+     * Load state from disk
+     */
+    async loadFromDisk() {
+        try {
+            const data = await fs_1.promises.readFile(this.stateFilePath, 'utf-8');
+            return JSON.parse(data);
+        }
+        catch (error) {
+            if (error.code === 'ENOENT') {
+                // File doesn't exist yet
+                return null;
+            }
+            throw error;
+        }
+    }
+    /**
+     * Save state to disk immediately
+     */
+    async saveToDisk() {
+        if (!this.state) {
+            return;
+        }
+        try {
+            await this.ensureStateDirectory();
+            const data = JSON.stringify(this.state, null, 2);
+            await fs_1.promises.writeFile(this.stateFilePath, data, 'utf-8');
+        }
+        catch (error) {
+            console.error(`Failed to save state for node ${this.nodeId}:`, error);
+            // Don't throw - state is cached in memory
+        }
+    }
+    /**
+     * Save state to disk with debouncing
+     * Prevents excessive writes during rapid updates
+     */
+    async saveToDiskDebounced(debounceMs = 1000) {
+        // Clear existing timer
+        if (this.saveDebounceTimer) {
+            clearTimeout(this.saveDebounceTimer);
+        }
+        // Set new timer
+        this.saveDebounceTimer = setTimeout(async () => {
+            await this.saveToDisk();
+            this.saveDebounceTimer = null;
+        }, debounceMs);
+    }
+    /**
+     * Force save any pending changes
+     * Call this before deactivating the node
+     */
+    async flush() {
+        if (this.saveDebounceTimer) {
+            clearTimeout(this.saveDebounceTimer);
+            this.saveDebounceTimer = null;
+        }
+        await this.saveToDisk();
+    }
+}
+exports.StateStore = StateStore;

package/dist/utils/WebhookHandler.d.ts

@@ -0,0 +1,78 @@
+/// <reference types="node" />
+/// <reference types="node/http" />
+/// <reference types="n8n-workflow" />
+import type { IncomingMessage, ServerResponse } from 'http';
+import type { GraphSubscription } from '../types';
+import { GraphClient } from './GraphClient';
+import { StateStore } from './StateStore';
+/**
+ * Webhook Handler for OneDrive Business
+ *
+ * Manages Microsoft Graph webhook subscriptions lifecycle:
+ * 1. Creates subscription on node activation
+ * 2. Handles validation token handshake
+ * 3. Auto-renews subscription before expiration
+ * 4. Deletes subscription on node deactivation
+ *
+ * CRITICAL ARCHITECTURE DECISION:
+ * The webhook does NOT emit workflow data directly.
+ * It only acts as a NOTIFICATION that changes occurred.
+ * The actual data is fetched via Delta Query by DeltaProcessor.
+ *
+ * WHY:
+ * - Webhook notifications don't contain full file metadata
+ * - Multiple notifications may come for one upload
+ * - Delta Query provides the single source of truth
+ * - Deduplication happens in DeltaProcessor, not here
+ */
+export declare class WebhookHandler {
+    private graphClient;
+    private stateStore;
+    private subscriptionResource;
+    private clientState;
+    private readonly RENEWAL_BUFFER_MS;
+    private readonly SUBSCRIPTION_DURATION_DAYS;
+    constructor(graphClient: GraphClient, stateStore: StateStore, subscriptionResource: string);
+    /**
+     * Create or renew webhook subscription
+     * Called when trigger node is activated
+     */
+    createOrRenewSubscription(notificationUrl: string): Promise<GraphSubscription>;
+    /**
+     * Create a new webhook subscription
+     */
+    private createSubscription;
+    /**
+     * Renew an existing subscription
+     */
+    private renewSubscription;
+    /**
+     * Delete webhook subscription
+     * Called when trigger node is deactivated
+     */
+    deleteSubscription(): Promise<void>;
+    /**
+     * Handle incoming webhook request
+     *
+     * Microsoft Graph sends two types of requests:
+     * 1. Validation request (during subscription creation)
+     * 2. Notification request (when changes occur)
+     *
+     * CRITICAL: This method returns immediately and does NOT trigger workflows.
+     * It only validates the request and returns HTTP 200.
+     */
+    handleWebhookRequest(req: IncomingMessage, res: ServerResponse): Promise<void>;
+    /**
+     * Handle validation request from Microsoft Graph
+     * Must respond with the validation token in plain text
+     */
+    private handleValidationRequest;
+    /**
+     * Read request body from stream
+     */
+    private readRequestBody;
+    /**
+     * Get the client state for validation
+     */
+    getClientState(): string;
+}

package/dist/utils/WebhookHandler.js

@@ -0,0 +1,220 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebhookHandler = void 0;
+const helpers_1 = require("./helpers");
+/**
+ * Webhook Handler for OneDrive Business
+ *
+ * Manages Microsoft Graph webhook subscriptions lifecycle:
+ * 1. Creates subscription on node activation
+ * 2. Handles validation token handshake
+ * 3. Auto-renews subscription before expiration
+ * 4. Deletes subscription on node deactivation
+ *
+ * CRITICAL ARCHITECTURE DECISION:
+ * The webhook does NOT emit workflow data directly.
+ * It only acts as a NOTIFICATION that changes occurred.
+ * The actual data is fetched via Delta Query by DeltaProcessor.
+ *
+ * WHY:
+ * - Webhook notifications don't contain full file metadata
+ * - Multiple notifications may come for one upload
+ * - Delta Query provides the single source of truth
+ * - Deduplication happens in DeltaProcessor, not here
+ */
+class WebhookHandler {
+    constructor(graphClient, stateStore, subscriptionResource) {
+        // Subscription renewal: renew 2 hours before expiration
+        this.RENEWAL_BUFFER_MS = 2 * 60 * 60 * 1000;
+        // Subscription duration: 3 days (Microsoft Graph maximum)
+        this.SUBSCRIPTION_DURATION_DAYS = 3;
+        this.graphClient = graphClient;
+        this.stateStore = stateStore;
+        this.subscriptionResource = subscriptionResource;
+        // Generate unique client state for security validation
+        this.clientState = (0, helpers_1.generateSecureRandomString)(32);
+    }
+    /**
+     * Create or renew webhook subscription
+     * Called when trigger node is activated
+     */
+    async createOrRenewSubscription(notificationUrl) {
+        const state = this.stateStore.getState();
+        // Check if we have an existing subscription
+        if (state.subscriptionId && state.subscriptionExpiration) {
+            const now = Date.now();
+            const expirationTime = state.subscriptionExpiration;
+            // If subscription is still valid for more than RENEWAL_BUFFER, reuse it
+            if (expirationTime - now > this.RENEWAL_BUFFER_MS) {
+                console.log(`Reusing existing subscription ${state.subscriptionId}`);
+                // Fetch subscription details
+                try {
+                    const subscription = await this.graphClient.get(`/subscriptions/${state.subscriptionId}`);
+                    return subscription;
+                }
+                catch (error) {
+                    console.log('Existing subscription not found, creating new one');
+                    // Subscription doesn't exist, create new one
+                }
+            }
+            else {
+                // Subscription is expiring soon, renew it
+                console.log(`Renewing subscription ${state.subscriptionId}`);
+                try {
+                    const renewed = await this.renewSubscription(state.subscriptionId);
+                    return renewed;
+                }
+                catch (error) {
+                    console.log('Failed to renew subscription, creating new one');
+                    // Renewal failed, create new one
+                }
+            }
+        }
+        // Create new subscription
+        return await this.createSubscription(notificationUrl);
+    }
+    /**
+     * Create a new webhook subscription
+     */
+    async createSubscription(notificationUrl) {
+        const expirationDateTime = new Date();
+        expirationDateTime.setDate(expirationDateTime.getDate() + this.SUBSCRIPTION_DURATION_DAYS);
+        const subscriptionRequest = {
+            changeType: 'created,updated',
+            notificationUrl,
+            resource: this.subscriptionResource,
+            expirationDateTime: expirationDateTime.toISOString(),
+            clientState: this.clientState,
+        };
+        console.log('Creating Microsoft Graph subscription:', {
+            resource: this.subscriptionResource,
+            notificationUrl,
+            expirationDateTime: expirationDateTime.toISOString(),
+        });
+        const subscription = await this.graphClient.post('/subscriptions', subscriptionRequest);
+        // Store subscription info
+        await this.stateStore.updateSubscription(subscription.id, new Date(subscription.expirationDateTime).getTime());
+        console.log(`Created subscription ${subscription.id}`);
+        return subscription;
+    }
+    /**
+     * Renew an existing subscription
+     */
+    async renewSubscription(subscriptionId) {
+        const expirationDateTime = new Date();
+        expirationDateTime.setDate(expirationDateTime.getDate() + this.SUBSCRIPTION_DURATION_DAYS);
+        const subscription = await this.graphClient.patch(`/subscriptions/${subscriptionId}`, {
+            expirationDateTime: expirationDateTime.toISOString(),
+        });
+        // Update stored expiration
+        await this.stateStore.updateSubscription(subscription.id, new Date(subscription.expirationDateTime).getTime());
+        console.log(`Renewed subscription ${subscriptionId}`);
+        return subscription;
+    }
+    /**
+     * Delete webhook subscription
+     * Called when trigger node is deactivated
+     */
+    async deleteSubscription() {
+        const state = this.stateStore.getState();
+        if (!state.subscriptionId) {
+            console.log('No subscription to delete');
+            return;
+        }
+        try {
+            await this.graphClient.delete(`/subscriptions/${state.subscriptionId}`);
+            console.log(`Deleted subscription ${state.subscriptionId}`);
+        }
+        catch (error) {
+            // If subscription doesn't exist (404), that's fine
+            if (error.statusCode !== 404) {
+                console.error('Failed to delete subscription:', error);
+            }
+        }
+        // Clear subscription from state
+        await this.stateStore.clearSubscription();
+    }
+    /**
+     * Handle incoming webhook request
+     *
+     * Microsoft Graph sends two types of requests:
+     * 1. Validation request (during subscription creation)
+     * 2. Notification request (when changes occur)
+     *
+     * CRITICAL: This method returns immediately and does NOT trigger workflows.
+     * It only validates the request and returns HTTP 200.
+     */
+    async handleWebhookRequest(req, res) {
+        var _a;
+        // Handle validation request
+        const validationToken = (_a = req.query) === null || _a === void 0 ? void 0 : _a.validationToken;
+        if (validationToken) {
+            console.log('Received webhook validation request');
+            this.handleValidationRequest(res, validationToken);
+            return;
+        }
+        // Handle notification request
+        console.log('Received webhook notification');
+        try {
+            // Read body
+            const body = await this.readRequestBody(req);
+            const notification = JSON.parse(body);
+            // Validate client state
+            if (notification.value && notification.value.length > 0) {
+                const firstNotification = notification.value[0];
+                if (firstNotification.clientState !== this.clientState) {
+                    console.error('Invalid clientState in webhook notification');
+                    res.writeHead(401);
+                    res.end();
+                    return;
+                }
+            }
+            // Return 200 OK immediately
+            // DO NOT trigger workflow here
+            // The trigger node will poll delta query separately
+            res.writeHead(200);
+            res.end();
+            console.log('Webhook notification acknowledged');
+        }
+        catch (error) {
+            console.error('Error handling webhook notification:', error);
+            res.writeHead(500);
+            res.end();
+        }
+    }
+    /**
+     * Handle validation request from Microsoft Graph
+     * Must respond with the validation token in plain text
+     */
+    handleValidationRequest(res, validationToken) {
+        res.writeHead(200, {
+            'Content-Type': 'text/plain',
+        });
+        res.end(validationToken);
+        console.log('Webhook validation successful');
+    }
+    /**
+     * Read request body from stream
+     */
+    readRequestBody(req) {
+        return new Promise((resolve, reject) => {
+            let body = '';
+            req.on('data', (chunk) => {
+                body += chunk.toString();
+            });
+            req.on('end', () => {
+                resolve(body);
+            });
+            req.on('error', (error) => {
+                reject(error);
+            });
+        });
+    }
+    /**
+     * Get the client state for validation
+     */
+    getClientState() {
+        return this.clientState;
+    }
+}
+exports.WebhookHandler = WebhookHandler;

package/dist/utils/helpers.d.ts

@@ -0,0 +1,113 @@
+import { DriveLocation } from '../types';
+/**
+ * Helper Functions for OneDrive Business Node
+ *
+ * These utilities handle common operations like drive resolution,
+ * path sanitization, and binary data handling.
+ */
+/**
+ * Resolve the drive path for Microsoft Graph API
+ *
+ * OneDrive Business drives are accessed through:
+ * - User context: /users/{userId}/drive
+ * - Site context: /sites/{siteId}/drive
+ *
+ * NEVER use /me/drive without tenant context
+ */
+export declare function resolveDrivePath(location: DriveLocation): string;
+/**
+ * Resolve the subscription resource for webhooks
+ *
+ * For delta queries and webhooks, we use:
+ * - User context: /users/{userId}/drive/root
+ * - Site context: /sites/{siteId}/drive
+ */
+export declare function resolveSubscriptionResource(location: DriveLocation): string;
+/**
+ * Sanitize file or folder path for OneDrive API
+ *
+ * - Removes leading/trailing slashes
+ * - Converts backslashes to forward slashes
+ * - Encodes special characters
+ */
+export declare function sanitizePath(path: string): string;
+/**
+ * Build the full item path for OneDrive API
+ *
+ * Constructs paths like:
+ * - /drive/root:/Documents/file.pdf
+ * - /drive/items/{itemId}
+ */
+export declare function buildItemPath(drivePath: string, itemPath?: string, itemId?: string): string;
+/**
+ * Extract file extension from filename
+ */
+export declare function getFileExtension(filename: string): string;
+/**
+ * Format bytes to human-readable size
+ */
+export declare function formatBytes(bytes: number): string;
+/**
+ * Calculate exponential backoff delay for retries
+ *
+ * Used for throttling (429) and transient errors
+ */
+export declare function calculateBackoffDelay(retryCount: number, initialDelayMs?: number, maxDelayMs?: number, backoffMultiplier?: number): number;
+/**
+ * Sleep for specified milliseconds
+ * Used in retry logic
+ */
+export declare function sleep(ms: number): Promise<void>;
+/**
+ * Parse Retry-After header from 429 responses
+ * Returns delay in milliseconds
+ */
+export declare function parseRetryAfter(retryAfterHeader?: string): number;
+/**
+ * Generate a cryptographically secure random string
+ * Used for clientState in webhook subscriptions
+ */
+export declare function generateSecureRandomString(length?: number): string;
+/**
+ * Validate Microsoft Graph item ID format
+ */
+export declare function isValidItemId(itemId: string): boolean;
+/**
+ * Check if an item is a file (vs folder)
+ */
+export declare function isFile(item: {
+    file?: any;
+    folder?: any;
+}): boolean;
+/**
+ * Check if an item is a folder (vs file)
+ */
+export declare function isFolder(item: {
+    file?: any;
+    folder?: any;
+}): boolean;
+/**
+ * Extract MIME type from DriveItem
+ */
+export declare function getMimeType(item: {
+    file?: {
+        mimeType?: string;
+    };
+}): string;
+/**
+ * Build a version key for deduplication
+ * Format: ${itemId}_${eTag}
+ */
+export declare function buildVersionKey(itemId: string, eTag: string): string;
+/**
+ * Clean up old processed versions to prevent memory bloat
+ * Keeps only the most recent maxVersions per item
+ */
+export declare function cleanupProcessedVersions(processedVersions: Record<string, boolean>, maxVersionsPerItem?: number): Record<string, boolean>;
+/**
+ * Parse Graph API error response
+ */
+export declare function parseGraphError(error: any): {
+    code: string;
+    message: string;
+};