n8n-nodes-onedrive-business 1.0.0

package/README.md

@@ -0,0 +1,452 @@
+# OneDrive Business Custom Node for n8n
+
+Production-ready OneDrive Business integration for n8n with robust deduplication and webhook-based triggers.
+
+## Features
+
+### ✅ OneDrive Business ONLY
+- **Tenant-based authentication** via Azure Entra ID (OAuth2)
+- Supports **User Drives** (`/users/{userId}/drive`)
+- Supports **SharePoint Site Drives** (`/sites/{siteId}/drive`)
+- ❌ **NOT for OneDrive Personal/Consumer**
+
+### 📁 File Operations
+- **Upload**: Binary file upload with automatic MIME type detection
+- **Download**: Binary file download
+- **Get**: Retrieve file metadata
+- **Delete**: Remove files
+- **Rename**: Rename files
+- **Search**: Search for files
+- **Share**: Create sharing links (view/edit, anonymous/organization)
+
+### 📂 Folder Operations
+- **Create**: Create folders
+- **Delete**: Remove folders
+- **Get Items**: List folder contents
+- **Rename**: Rename folders
+- **Search**: Search for folders
+- **Share**: Create sharing links
+
+### 🔔 Trigger Node (Webhook + Delta Query)
+- **File Created**: Trigger when new files are uploaded
+- **File Updated**: Trigger when files are modified
+- **Folder Created**: Trigger when new folders are created
+- **Folder Updated**: Trigger when folders are modified
+
+## Installation
+
+```bash
+cd ~/.n8n/custom
+git clone <your-repo> n8n-nodes-onedrive-business
+cd n8n-nodes-onedrive-business
+npm install
+npm run build
+```
+
+Restart n8n to load the custom node.
+
+## Azure App Registration Setup
+
+### 1. Create App Registration
+
+1. Go to [Azure Portal](https://portal.azure.com)
+2. Navigate to **Azure Active Directory** → **App registrations**
+3. Click **New registration**
+4. Enter name: `n8n OneDrive Business`
+5. Select **Accounts in this organizational directory only** (or multi-tenant if needed)
+6. Set Redirect URI: `https://your-n8n-instance.com/rest/oauth2-credential/callback`
+7. Click **Register**
+
+### 2. Configure API Permissions
+
+1. Go to **API permissions**
+2. Click **Add a permission** → **Microsoft Graph** → **Delegated permissions**
+3. Add these permissions:
+   - `Files.ReadWrite.All`
+   - `Sites.ReadWrite.All`
+   - `offline_access`
+4. Click **Add permissions**
+5. Click **Grant admin consent** (requires admin)
+
+### 3. Create Client Secret
+
+1. Go to **Certificates & secrets**
+2. Click **New client secret**
+3. Enter description: `n8n integration`
+4. Select expiration (recommend 24 months)
+5. Click **Add**
+6. **Copy the secret value immediately** (you won't see it again)
+
+### 4. Get Required IDs
+
+- **Application (client) ID**: Copy from Overview page
+- **Directory (tenant) ID**: Copy from Overview page
+
+## Configuration in n8n
+
+### 1. Create Credential
+
+1. In n8n, go to **Credentials** → **New**
+2. Search for **OneDrive Business OAuth2 API**
+3. Fill in:
+   - **Tenant ID**: Your Azure AD tenant ID (or "common" for multi-tenant)
+   - **Client ID**: Application ID from Azure
+   - **Client Secret**: Secret value from Azure
+4. Click **Connect my account**
+5. Sign in with a Microsoft 365 account
+6. Grant permissions
+
+### 2. Use in Workflows
+
+#### File Upload Example
+```
+1. Add "OneDrive Business" node
+2. Select Resource: File
+3. Select Operation: Upload
+4. Drive Type: User Drive
+5. User ID: user@contoso.com
+6. File Path: /Documents/report.pdf
+7. Binary Property: data
+```
+
+#### Trigger Example
+```
+1. Add "OneDrive Business Trigger" node
+2. Drive Type: User Drive
+3. User ID: user@contoso.com
+4. Trigger On: File Created, File Updated
+5. Activate workflow
+```
+
+## Deduplication Architecture
+
+### The Problem
+
+SharePoint-backed OneDrive generates **multiple updates per file upload**:
+
+1. File created (size=0, no hash)
+2. Metadata updated
+3. Content uploaded (partial hash)
+4. Final metadata sync (complete hash)
+
+Without deduplication, **ONE upload = FOUR workflow executions**.
+
+### The Solution
+
+This node implements a **4-layer deduplication strategy**:
+
+#### 1. **File Stability Checking**
+```typescript
+function isStable(item): boolean {
+  return (
+    item.size > 0 &&
+    item.file?.hashes?.quickXorHash &&
+    item.lastModifiedDateTime === item.fileSystemInfo?.lastModifiedDateTime
+  );
+}
+```
+
+Ensures files have completed uploading before processing.
+
+#### 2. **Version-based Tracking**
+```typescript
+const versionKey = `${item.id}_${item.eTag}`;
+```
+
+Each file version (identified by eTag) is processed **exactly once**.
+
+#### 3. **Stability Window**
+```typescript
+if (Date.now() - lastModified < 15000) {
+  deferProcessing(); // Wait 15 seconds
+}
+```
+
+Prevents processing files still being modified.
+
+#### 4. **Event Classification**
+```typescript
+if (!previousState[item.id]) {
+  event = 'file.created';
+} else if (item.eTag !== previousState[item.id].eTag) {
+  event = 'file.updated';
+}
+```
+
+Accurately distinguishes between created and updated events.
+
+### State Persistence
+
+State is stored in:
+```
+~/.n8n-state/onedrive-business/{nodeId}.json
+```
+
+Contains:
+- **deltaLink**: Microsoft Graph delta query continuation token
+- **processedVersions**: Map of `${itemId}_${eTag}` → `true`
+- **lastKnownItems**: Map of `itemId` → `{ eTag, lastModifiedDateTime }`
+
+**Survives n8n restarts** to prevent duplicate re-processing.
+
+## Webhook Architecture
+
+### Why Webhook + Delta Query?
+
+Microsoft Graph webhooks **do NOT contain file data**. They only notify that "something changed."
+
+The **Delta Query** is the single source of truth.
+
+### Flow
+
+```
+1. File uploaded to OneDrive
+   ↓
+2. Microsoft Graph sends webhook notification
+   ↓
+3. Webhook endpoint returns 200 OK (does NOT trigger workflow)
+   ↓
+4. n8n polls trigger node (every 60 seconds)
+   ↓
+5. Trigger fetches Delta Query
+   ↓
+6. DeltaProcessor applies deduplication
+   ↓
+7. Workflow triggered with deduplicated events
+```
+
+### Why This Works
+
+- **Webhook**: Low-latency notification (near real-time)
+- **Delta Query**: Complete file metadata + pagination
+- **Deduplication**: Collapses multiple updates into one event
+- **State Persistence**: Prevents re-processing after restarts
+
+## API Rate Limits
+
+Microsoft Graph has rate limits:
+
+- **Per app per tenant**: 10,000 requests per 10 minutes
+- **Per user**: 2,000 requests per second
+
+This node implements:
+- **Exponential backoff** for 429 responses
+- **Retry-After header parsing**
+- **Automatic retry** (up to 3 attempts)
+
+## Troubleshooting
+
+### No Webhook Notifications Received
+
+1. Verify n8n is **publicly accessible** (webhook URL must be reachable)
+2. Check firewall rules
+3. Verify SSL certificate (Microsoft Graph requires HTTPS)
+4. Check n8n logs for webhook validation errors
+
+### Duplicate Workflow Executions
+
+1. Check if deduplication is working:
+   - View `~/.n8n-state/onedrive-business/{nodeId}.json`
+   - Verify `processedVersions` is being populated
+2. Increase stability window if large files are being processed
+3. Check that `eTag` is changing between updates
+
+### Subscription Expired
+
+Subscriptions auto-renew every 2 days. If renewal fails:
+
+1. Check OAuth2 token validity
+2. Verify API permissions are still granted
+3. Manually deactivate and reactivate the trigger node
+
+### Delta Query Not Working
+
+1. Verify drive path is correct:
+   - User drive: `/users/{userId}/drive`
+   - Site drive: `/sites/{siteId}/drive`
+2. Check that user/site ID is valid
+3. Ensure credentials have `Files.ReadWrite.All` permission
+
+## Development
+
+### Build
+
+```bash
+npm run build
+```
+
+### Watch Mode
+
+```bash
+npm run dev
+```
+
+### Lint
+
+```bash
+npm run lint
+npm run lintfix
+```
+
+## License
+
+MIT
+
+## Support
+
+For issues, feature requests, or contributions, please open an issue on GitHub.
+
+---
+
+## ✔ How this OneDrive Business node avoids duplicate executions
+
+### Problem Statement
+
+OneDrive Business is backed by SharePoint, which generates **multiple Graph API notifications for a single file upload**:
+
+1. **File Created**: Empty placeholder (size=0)
+2. **Metadata Updated**: File properties set
+3. **Content Uploaded**: Binary data written (partial hash)
+4. **Final Sync**: Hash finalized, timestamps aligned
+
+Each of these generates a separate webhook notification and appears in the Delta Query.
+
+**Without deduplication**: Uploading one 10MB PDF would trigger **4 workflow executions**.
+
+### Solution Architecture
+
+#### 1. **Webhook as Notification Only**
+
+The webhook endpoint **never emits workflow data**. It only:
+- Validates the request (clientState check)
+- Returns `200 OK`
+- Functions as a "wake-up call" for the polling mechanism
+
+**Result**: Webhook notifications don't directly trigger workflows, eliminating one source of duplicates.
+
+#### 2. **Delta Query as Single Source of Truth**
+
+All workflow triggers come from the **Delta Query** (`GET /drive/root/delta`), which:
+- Provides complete file metadata
+- Handles pagination
+- Returns a `@odata.deltaLink` for continuing from the last check
+
+**Result**: Only one API provides workflow data, creating a single choke point for deduplication.
+
+#### 3. **eTag-based Version Tracking**
+
+Each file version has a unique `eTag` value. The node tracks:
+
+```typescript
+processedVersions: {
+  "fileId123_etag-v1": true,
+  "fileId123_etag-v2": true,
+  "fileId123_etag-v3": true
+}
+```
+
+Before emitting a workflow event:
+```typescript
+const versionKey = `${item.id}_${item.eTag}`;
+if (processedVersions[versionKey]) {
+  return; // Already processed
+}
+processedVersions[versionKey] = true;
+// Emit workflow event
+```
+
+**Result**: Each file version triggers **exactly one** workflow execution, regardless of how many times it appears in Delta Query.
+
+#### 4. **File Stability Window**
+
+Some uploads take time to finalize (especially large files). The node waits for:
+
+- ✅ `size > 0`
+- ✅ `quickXorHash` present
+- ✅ `lastModifiedDateTime` matches `fileSystemInfo.lastModifiedDateTime`
+- ✅ 15 seconds elapsed since last modification
+
+If these conditions aren't met, the file is **deferred** (not processed yet).
+
+**Result**: Only stable, fully uploaded files trigger workflows.
+
+#### 5. **State Persistence Across Restarts**
+
+All deduplication state is saved to disk:
+
+```
+~/.n8n-state/onedrive-business/{nodeId}.json
+```
+
+When n8n restarts:
+1. State is loaded from disk
+2. `deltaLink` is restored
+3. `processedVersions` map is restored
+4. Delta Query continues from where it left off
+
+**Result**: Restarting n8n doesn't cause already-processed files to re-trigger workflows.
+
+### Real-World Example
+
+**Scenario**: User uploads `report.pdf` (10MB) to OneDrive Business.
+
+**What happens in SharePoint**:
+```
+0s:  File created (size=0, no hash)              → eTag-v1
+1s:  Metadata set (name, path)                   → eTag-v2
+2s:  Content upload starts (partial hash)        → eTag-v3
+5s:  Content upload completes (quickXorHash set) → eTag-v4
+6s:  Final metadata sync                         → eTag-v5
+```
+
+**Without this node** (naive approach):
+- Delta Query returns 5 versions
+- **5 workflow executions** 😱
+
+**With this node**:
+```
+Delta Query returns 5 versions:
+
+Version 1 (eTag-v1):
+  ❌ size=0 → Not stable, deferred
+
+Version 2 (eTag-v2):
+  ❌ size=0 → Not stable, deferred
+
+Version 3 (eTag-v3):
+  ❌ No quickXorHash → Not stable, deferred
+
+Version 4 (eTag-v4):
+  ✅ size=10485760
+  ✅ quickXorHash present
+  ✅ Timestamps aligned
+  ❌ Modified 2 seconds ago → Within stability window, deferred
+
+Version 5 (eTag-v5):
+  ✅ size=10485760
+  ✅ quickXorHash present
+  ✅ Timestamps aligned
+  ✅ Modified 20 seconds ago → Stable!
+  ✅ Not in processedVersions
+  
+  → Mark as processed: processedVersions["fileId123_etag-v5"] = true
+  → Emit workflow event: { event: 'file.created', item: {...} }
+```
+
+**Result**: **1 workflow execution** ✅
+
+### Why This Matters for Production
+
+In a real Microsoft 365 tenant with hundreds of users:
+
+- **100 files uploaded per day**
+- **Without deduplication**: 400+ workflow executions
+- **With this node**: 100 workflow executions
+
+**75% reduction in duplicate workflows**, preventing:
+- Wasted compute resources
+- Duplicate notifications to users
+- Redundant database writes
+- API quota exhaustion
+
+This architecture ensures **enterprise-grade reliability** for OneDrive Business integrations.

package/dist/credentials/OneDriveBusinessOAuth2.credentials.d.ts

@@ -0,0 +1,25 @@
+import { ICredentialTestRequest, ICredentialType, INodeProperties, ICredentialDataDecryptedObject, IHttpRequestOptions } from 'n8n-workflow';
+/**
+ * OAuth2 Credentials for OneDrive Business (Azure Entra ID)
+ *
+ * CRITICAL: This is for OneDrive Business ONLY (SharePoint-backed).
+ * It uses Azure Entra ID (formerly Azure AD) tenant-based authentication.
+ *
+ * DO NOT use this for OneDrive Personal/Consumer accounts.
+ */
+export declare class OneDriveBusinessOAuth2 implements ICredentialType {
+    name: string;
+    extends: string[];
+    displayName: string;
+    documentationUrl: string;
+    properties: INodeProperties[];
+    /**
+     * Authenticate requests to Microsoft Graph API
+     * This is called automatically by n8n to add authentication headers
+     */
+    authenticate(credentials: ICredentialDataDecryptedObject, requestOptions: IHttpRequestOptions): Promise<IHttpRequestOptions>;
+    /**
+     * Test credentials by fetching the user's OneDrive information
+     */
+    test: ICredentialTestRequest;
+}

package/dist/credentials/OneDriveBusinessOAuth2.credentials.js

@@ -0,0 +1,114 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OneDriveBusinessOAuth2 = void 0;
+/**
+ * OAuth2 Credentials for OneDrive Business (Azure Entra ID)
+ *
+ * CRITICAL: This is for OneDrive Business ONLY (SharePoint-backed).
+ * It uses Azure Entra ID (formerly Azure AD) tenant-based authentication.
+ *
+ * DO NOT use this for OneDrive Personal/Consumer accounts.
+ */
+class OneDriveBusinessOAuth2 {
+    constructor() {
+        this.name = 'oneDriveBusinessOAuth2Api';
+        this.extends = ['oAuth2Api'];
+        this.displayName = 'OneDrive Business OAuth2 API';
+        this.documentationUrl = 'https://learn.microsoft.com/en-us/graph/auth-v2-user';
+        this.properties = [
+            {
+                displayName: 'Grant Type',
+                name: 'grantType',
+                type: 'hidden',
+                default: 'authorizationCode',
+            },
+            {
+                displayName: 'Tenant ID',
+                name: 'tenantId',
+                type: 'string',
+                default: '',
+                required: true,
+                placeholder: 'common or your-tenant-id',
+                description: 'Azure Entra ID Tenant ID. Use "common" for multi-tenant apps, or specify your organization\'s tenant ID for single-tenant apps.',
+            },
+            {
+                displayName: 'Client ID',
+                name: 'clientId',
+                type: 'string',
+                default: '',
+                required: true,
+                description: 'Application (client) ID from Azure App Registration',
+            },
+            {
+                displayName: 'Client Secret',
+                name: 'clientSecret',
+                type: 'string',
+                typeOptions: {
+                    password: true,
+                },
+                default: '',
+                required: true,
+                description: 'Client secret from Azure App Registration',
+            },
+            {
+                displayName: 'Authorization URL',
+                name: 'authUrl',
+                type: 'hidden',
+                default: '={{$self["tenantId"] ? `https://login.microsoftonline.com/${$self["tenantId"]}/oauth2/v2.0/authorize` : "https://login.microsoftonline.com/common/oauth2/v2.0/authorize"}}',
+                required: true,
+            },
+            {
+                displayName: 'Access Token URL',
+                name: 'accessTokenUrl',
+                type: 'hidden',
+                default: '={{$self["tenantId"] ? `https://login.microsoftonline.com/${$self["tenantId"]}/oauth2/v2.0/token` : "https://login.microsoftonline.com/common/oauth2/v2.0/token"}}',
+                required: true,
+            },
+            {
+                displayName: 'Scope',
+                name: 'scope',
+                type: 'hidden',
+                default: 'https://graph.microsoft.com/Files.ReadWrite.All https://graph.microsoft.com/Sites.ReadWrite.All offline_access',
+                description: 'Required Microsoft Graph API permissions for OneDrive Business',
+            },
+            {
+                displayName: 'Auth URI Query Parameters',
+                name: 'authQueryParameters',
+                type: 'hidden',
+                default: 'response_type=code&prompt=consent',
+            },
+            {
+                displayName: 'Authentication',
+                name: 'authentication',
+                type: 'hidden',
+                default: 'body',
+            },
+        ];
+        /**
+         * Test credentials by fetching the user's OneDrive information
+         */
+        this.test = {
+            request: {
+                baseURL: 'https://graph.microsoft.com/v1.0',
+                url: '/me/drive',
+                method: 'GET',
+            },
+        };
+    }
+    /**
+     * Authenticate requests to Microsoft Graph API
+     * This is called automatically by n8n to add authentication headers
+     */
+    async authenticate(credentials, requestOptions) {
+        // The OAuth2 token is stored in the credentials object
+        const oauthData = credentials.oauthTokenData;
+        if (!requestOptions.headers) {
+            requestOptions.headers = {};
+        }
+        if (oauthData && oauthData.access_token) {
+            requestOptions.headers['Authorization'] = `Bearer ${oauthData.access_token}`;
+        }
+        return requestOptions;
+    }
+}
+exports.OneDriveBusinessOAuth2 = OneDriveBusinessOAuth2;

package/dist/nodes/OneDriveBusiness.node.d.ts

@@ -0,0 +1,35 @@
+import { IExecuteFunctions, INodeExecutionData, INodeType, INodeTypeDescription } from 'n8n-workflow';
+/**
+ * OneDrive Business Node
+ *
+ * Provides file and folder operations for OneDrive Business:
+ * - File: Delete, Download, Get, Rename, Search, Share, Upload
+ * - Folder: Create, Delete, Get Items, Rename, Search, Share
+ *
+ * Uses Microsoft Graph API v1.0 with tenant-based authentication.
+ */
+export declare class OneDriveBusiness implements INodeType {
+    description: INodeTypeDescription;
+    execute(this: IExecuteFunctions): Promise<INodeExecutionData[][]>;
+    /**
+     * Execute file operations
+     */
+    private static executeFileOperation;
+    /**
+     * Execute folder operations
+     */
+    private static executeFolderOperation;
+    private static fileDelete;
+    private static fileDownload;
+    private static fileGet;
+    private static fileRename;
+    private static fileSearch;
+    private static fileShare;
+    private static fileUpload;
+    private static folderCreate;
+    private static folderDelete;
+    private static folderGetItems;
+    private static folderRename;
+    private static folderSearch;
+    private static folderShare;
+}