n8n-nodes-elearning-magic 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Discover eLearning Ltd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,68 @@
+# n8n-nodes-elearning-magic
+
+Community node that receives signed payloads from the eLearning Magic SCORM wrapper. It exposes a lightweight webhook trigger that validates the `X-EM-Signature` HMAC header (SHA-256) and optionally enforces the `X-EM-Node-Id` header before emitting the request body into your workflow.
+
+## Features
+- Webhook trigger dedicated to eLearning Magic course events
+- HMAC validation of inbound payloads using your signing secret
+- Optional `X-EM-Node-Id` enforcement so each connection can stay isolated
+- Emits body, query, headers, and optional raw body for debugging
+- Customizable HTTP response body/status for Storyline debugging
+
+## Installation
+From your n8n root (typically `~/.n8n`):
+
+```bash
+npm install n8n-nodes-elearning-magic
+```
+
+Restart n8n and enable Community Nodes if prompted.
+
+## Usage
+1. Add the **eLearning Magic Trigger** node to a workflow.
+2. Set a **Webhook Path** (e.g., `elearning-magic` or something unique per connection).
+3. (Recommended) Set a **Node ID** and enable **Enforce Node ID Match**. This value must match the `X-EM-Node-Id` header sent by the eLearning Magic app.
+4. Configure the **eLearning Magic Signing Secret** credential with your chosen secret. This secret signs incoming payloads; the app will use it to produce `X-EM-Signature`.
+5. Copy the **Webhook URL** shown in the node’s “Webhook URLs” panel and paste it into the eLearning Magic app when creating an n8n connection. Also provide the Node ID and signing secret there.
+6. Save the workflow and activate it. Incoming Storyline triggers will appear as items with `body`, `query`, `headers`, and `meta` (signature status, nodeId match, timestamp). Enable “Include Raw Body” for debugging HMAC issues.
+
+## Expected request format
+- Method: `POST`
+- Headers:
+  - `X-EM-Signature`: HMAC-SHA256 of the raw request body using the configured signing secret.
+  - `X-EM-Node-Id` (optional): Must match the configured Node ID when enforcement is enabled.
+- Body: JSON payload forwarded by the eLearning Magic app, e.g.:
+
+```json
+{
+  "connectionId": "abc-123",
+  "projectId": "storyline-project-id",
+  "wrapperVersion": "1.0.17",
+  "meta": {
+    "learnerId": "jane.doe",
+    "learnerName": "Jane Doe",
+    "launchDomain": "lms.example.com",
+    "attemptId": "attempt-001",
+    "receivedAt": "2025-01-01T12:34:56Z"
+  },
+  "fields": {
+    "score": 92,
+    "lessonStatus": "complete",
+    "learnerEmail": "jane@example.com"
+  }
+}
+```
+
+The node relays the full body; you can route on any property inside your workflow.
+
+## Response customization
+- **Response Code**: HTTP status returned to the caller (default `200`).
+- **Response Body**: JSON string or plain text returned to the caller (default `{"received":true}`).
+
+## Development
+```bash
+npm install
+npm run build
+```
+
+Publish to npm with `npm publish` once you are happy with the build output in `dist/`.

package/dist/credentials/ElearningMagicApi.credentials.d.ts

@@ -0,0 +1,7 @@
+import type { ICredentialType, INodeProperties } from 'n8n-workflow';
+export declare class ElearningMagicApi implements ICredentialType {
+    name: string;
+    displayName: string;
+    documentationUrl: string;
+    properties: INodeProperties[];
+}

package/dist/credentials/ElearningMagicApi.credentials.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ElearningMagicApi = void 0;
+class ElearningMagicApi {
+    constructor() {
+        this.name = 'elearningMagicApi';
+        this.displayName = 'eLearning Magic Signing Secret';
+        this.documentationUrl = 'https://github.com/discoverelearning/n8n-nodes-elearning-magic';
+        this.properties = [
+            {
+                displayName: 'Signing Secret',
+                name: 'signingSecret',
+                type: 'string',
+                typeOptions: {
+                    password: true,
+                },
+                default: '',
+                description: 'HMAC SHA-256 secret to verify the X-EM-Signature header from eLearning Magic',
+            },
+        ];
+    }
+}
+exports.ElearningMagicApi = ElearningMagicApi;

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+import { ElearningMagicTrigger } from './nodes/ElearningMagic/ElearningMagicTrigger.node';
+import { ElearningMagicApi } from './credentials/ElearningMagicApi.credentials';
+export declare const nodes: (typeof ElearningMagicTrigger)[];
+export declare const credentials: (typeof ElearningMagicApi)[];

package/dist/index.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.credentials = exports.nodes = void 0;
+const ElearningMagicTrigger_node_1 = require("./nodes/ElearningMagic/ElearningMagicTrigger.node");
+const ElearningMagicApi_credentials_1 = require("./credentials/ElearningMagicApi.credentials");
+exports.nodes = [ElearningMagicTrigger_node_1.ElearningMagicTrigger];
+exports.credentials = [ElearningMagicApi_credentials_1.ElearningMagicApi];

package/dist/nodes/ElearningMagic/ElearningMagicTrigger.node.d.ts

@@ -0,0 +1,5 @@
+import type { INodeType, INodeTypeDescription, IWebhookFunctions, IWebhookResponseData } from 'n8n-workflow';
+export declare class ElearningMagicTrigger implements INodeType {
+    description: INodeTypeDescription;
+    webhook(this: IWebhookFunctions): Promise<IWebhookResponseData>;
+}

package/dist/nodes/ElearningMagic/ElearningMagicTrigger.node.js

@@ -0,0 +1,192 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ElearningMagicTrigger = void 0;
+const crypto_1 = require("crypto");
+const computeSignature = (secret, rawBody) => {
+    return (0, crypto_1.createHmac)('sha256', secret).update(rawBody).digest('hex');
+};
+const safeCompare = (a, b) => {
+    if (!a || !b || a.length !== b.length) {
+        return false;
+    }
+    try {
+        return (0, crypto_1.timingSafeEqual)(Buffer.from(a), Buffer.from(b));
+    }
+    catch {
+        return false;
+    }
+};
+class ElearningMagicTrigger {
+    constructor() {
+        this.description = {
+            displayName: 'eLearning Magic Trigger',
+            name: 'elearningMagicTrigger',
+            icon: 'fa:magic',
+            group: ['trigger'],
+            version: 1,
+            description: 'Receive SCORM wrapper payloads from eLearning Magic via a signed webhook',
+            defaults: {
+                name: 'eLearning Magic Trigger',
+            },
+            subtitle: '={{$parameter["path"]}}',
+            inputs: [],
+            outputs: ['main'],
+            credentials: [
+                {
+                    name: 'elearningMagicApi',
+                    required: false,
+                },
+            ],
+            webhooks: [
+                {
+                    name: 'default',
+                    httpMethod: 'POST',
+                    responseMode: 'onReceived',
+                    path: '={{$parameter["path"]}}',
+                    restartWebhook: true,
+                },
+            ],
+            properties: [
+                {
+                    displayName: 'Webhook Path',
+                    name: 'path',
+                    type: 'string',
+                    default: 'elearning-magic',
+                    description: 'Unique path segment to receive data on (visible in the Webhook URLs panel)',
+                },
+                {
+                    displayName: 'Node ID (optional)',
+                    name: 'nodeId',
+                    type: 'string',
+                    default: '',
+                    description: 'If set, the trigger expects the X-EM-Node-Id header to match this value',
+                },
+                {
+                    displayName: 'Enforce Node ID Match',
+                    name: 'enforceNodeId',
+                    type: 'boolean',
+                    default: false,
+                    description: 'Reject requests whose X-EM-Node-Id header does not match the configured Node ID',
+                },
+                {
+                    displayName: 'Require Signature',
+                    name: 'requireSignature',
+                    type: 'boolean',
+                    default: true,
+                    description: 'Reject requests without a valid X-EM-Signature HMAC (SHA-256) header',
+                },
+                {
+                    displayName: 'Include Raw Body',
+                    name: 'includeRawBody',
+                    type: 'boolean',
+                    default: false,
+                    description: 'Attach the raw request body to the emitted item for debugging',
+                },
+                {
+                    displayName: 'Response Code',
+                    name: 'responseCode',
+                    type: 'number',
+                    default: 200,
+                    typeOptions: {
+                        minValue: 100,
+                        maxValue: 599,
+                    },
+                    description: 'HTTP status returned to the caller after processing',
+                },
+                {
+                    displayName: 'Response Body',
+                    name: 'responseBody',
+                    type: 'string',
+                    typeOptions: {
+                        rows: 3,
+                    },
+                    default: '{"received":true}',
+                    description: 'JSON string or plain text to return to the caller',
+                },
+            ],
+        };
+    }
+    async webhook() {
+        const req = this.getRequestObject();
+        const res = this.getResponseObject();
+        const nodeId = (this.getNodeParameter('nodeId') || '').trim();
+        const enforceNodeId = this.getNodeParameter('enforceNodeId');
+        const requireSignature = this.getNodeParameter('requireSignature');
+        const includeRawBody = this.getNodeParameter('includeRawBody');
+        const responseCode = this.getNodeParameter('responseCode');
+        const responseBodyParam = this.getNodeParameter('responseBody');
+        const credentials = await this.getCredentials('elearningMagicApi');
+        const signingSecret = (credentials === null || credentials === void 0 ? void 0 : credentials.signingSecret) || '';
+        const rawBody = req.rawBody !== undefined
+            ? req.rawBody.toString('utf8')
+            : JSON.stringify(req.body || {});
+        const headerSignature = req.headers['x-em-signature'] || '';
+        const headerNodeId = req.headers['x-em-node-id'] || '';
+        let signatureValid = false;
+        if (headerSignature && signingSecret) {
+            const computed = computeSignature(signingSecret, rawBody);
+            signatureValid = safeCompare(computed, headerSignature);
+        }
+        if (requireSignature) {
+            if (!signingSecret) {
+                res.status(401);
+                return {
+                    webhookResponse: { error: 'Signing secret is not configured on this node' },
+                };
+            }
+            if (!headerSignature || !signatureValid) {
+                res.status(403);
+                return {
+                    webhookResponse: { error: 'Invalid or missing X-EM-Signature header' },
+                };
+            }
+        }
+        let nodeIdMatched = true;
+        if (enforceNodeId) {
+            nodeIdMatched = !!nodeId && !!headerNodeId && nodeId === headerNodeId;
+            if (!nodeIdMatched) {
+                res.status(403);
+                return {
+                    webhookResponse: { error: 'X-EM-Node-Id header did not match the configured Node ID' },
+                };
+            }
+        }
+        else if (nodeId) {
+            nodeIdMatched = headerNodeId ? nodeId === headerNodeId : true;
+        }
+        const payload = {
+            json: {
+                body: req.body,
+                query: req.query,
+                headers: req.headers,
+                meta: {
+                    receivedAt: new Date().toISOString(),
+                    signatureValid: requireSignature ? signatureValid : null,
+                    nodeIdMatched,
+                    webhookPath: req.url,
+                },
+            },
+        };
+        if (includeRawBody) {
+            payload.json.rawBody = rawBody;
+        }
+        let responseBody = responseBodyParam;
+        if (typeof responseBodyParam === 'string') {
+            const trimmed = responseBodyParam.trim();
+            if ((trimmed.startsWith('{') && trimmed.endsWith('}')) || (trimmed.startsWith('[') && trimmed.endsWith(']'))) {
+                try {
+                    responseBody = JSON.parse(trimmed);
+                }
+                catch {
+                    responseBody = responseBodyParam;
+                }
+            }
+        }
+        res.status(responseCode || 200);
+        return {
+            webhookResponse: responseBody,
+            workflowData: [this.helpers.returnJsonArray([payload.json])],
+        };
+    }
+}
+exports.ElearningMagicTrigger = ElearningMagicTrigger;

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "n8n-nodes-elearning-magic",
+  "version": "0.1.0",
+  "description": "n8n community node for receiving signed payloads from the eLearning Magic SCORM wrapper",
+  "keywords": [
+    "n8n-community-node",
+    "elearning",
+    "storyline",
+    "scorm",
+    "webhook"
+  ],
+  "license": "MIT",
+  "author": {
+    "name": "Discover eLearning Ltd",
+    "email": "support@discoverelearning.com"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/discoverelearning/n8n-nodes-elearning-magic.git"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepare": "npm run build"
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.21",
+    "@types/node": "^22.10.2",
+    "@types/ssh2": "^1.11.15",
+    "nock": "^13.4.0",
+    "typescript": "^5.6.3"
+  },
+  "dependencies": {
+    "n8n-core": "^1.0.0",
+    "n8n-workflow": "^1.0.0"
+  },
+  "overrides": {
+    "form-data": "^4.0.4"
+  },
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "n8n": {
+    "n8nNodesApiVersion": 1,
+    "nodes": [
+      {
+        "type": "dist/nodes/ElearningMagic/ElearningMagicTrigger.node.js"
+      }
+    ],
+    "credentials": [
+      {
+        "type": "dist/credentials/ElearningMagicApi.credentials.js"
+      }
+    ]
+  }
+}