@n8n/frontend-module-sdk 0.1.0 → 0.2.0

package/LICENSE_EE.md

@@ -0,0 +1,27 @@
+# The n8n Enterprise License (the “Enterprise License”)
+
+Copyright (c) 2022-present n8n GmbH.
+
+With regard to the n8n Software:
+
+This software and associated documentation files (the "Software") may only be used in production, if
+you (and any entity that you represent) hold a valid n8n Enterprise license corresponding to your
+usage. Subject to the foregoing sentence, you are free to modify this Software and publish patches
+to the Software. You agree that n8n and/or its licensors (as applicable) retain all right, title and
+interest in and to all such modifications and/or patches, and all such modifications and/or patches
+may only be used, copied, modified, displayed, distributed, or otherwise exploited with a valid n8n
+Enterprise license for the corresponding usage. Notwithstanding the foregoing, you may copy and
+modify the Software for development and testing purposes, without requiring a subscription. You
+agree that n8n and/or its licensors (as applicable) retain all right, title and interest in and to
+all such modifications. You are not granted any other rights beyond what is expressly stated herein.
+Subject to the foregoing, it is forbidden to copy, merge, publish, distribute, sublicense, and/or
+sell 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.
+
+For all third party components incorporated into the n8n Software, those components are licensed
+under the original license provided by the owner of the applicable component.

package/package.json

@@ -1,7 +1,7 @@
 {
   "type": "module",
   "name": "@n8n/frontend-module-sdk",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "main": "src/index.ts",
   "import": "src/index.ts",
   "exports": {
@@ -10,7 +10,8 @@
   "dependencies": {
     "vue": "^3.5.13",
     "vue-router": "^4.5.0",
-    "@n8n/design-system": "2.30.0"
+    "@n8n/design-system": "2.31.0",
+    "@n8n/api-types": "1.32.0"
   },
   "devDependencies": {
     "typescript": "6.0.2",
@@ -18,11 +19,20 @@
     "vite": "^8.0.2",
     "vitest": "^4.1.9",
     "vue-tsc": "^2.2.8",
-    "@n8n/typescript-config": "1.9.0",
     "@n8n/eslint-config": "0.0.1",
-    "@n8n/vitest-config": "1.18.0"
+    "@n8n/vitest-config": "1.19.0",
+    "@n8n/typescript-config": "1.9.0"
+  },
+  "license": "SEE LICENSE IN LICENSE.md",
+  "homepage": "https://n8n.io",
+  "author": {
+    "name": "Jan Oberhauser",
+    "email": "jan@n8n.io"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/n8n-io/n8n.git"
   },
-  "license": "LicenseRef-n8n-sustainable-use",
   "scripts": {
     "clean": "rimraf .turbo",
     "typecheck": "vue-tsc --noEmit",

package/src/index.ts

@@ -1,3 +1,6 @@
-export type * from './module.types';
-export * as modalRegistry from './modalRegistry';
-export * from './resourceRegistry';
+export type * from './types';
+
+export * as modalRegistry from './registries/modalRegistry';
+export * from './registries/resourceRegistry';
+export * as pushHandlerRegistry from './registries/pushHandlerRegistry';
+export * as commandRegistry from './registries/commandRegistry';

package/src/registries/commandRegistry.test.ts

@@ -0,0 +1,67 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+
+import * as commandRegistry from './commandRegistry';
+import type { CommandBarEntry } from '../types/command';
+
+describe('commandRegistry', () => {
+	const commandA: CommandBarEntry = { id: 'cmd-a', title: 'Command A' };
+	const commandB: CommandBarEntry = {
+		id: 'cmd-b',
+		title: 'Command B',
+		section: 'Navigation',
+		keywords: ['jump'],
+	};
+
+	beforeEach(() => {
+		commandRegistry.clear();
+	});
+
+	it('should register and retrieve a command', () => {
+		commandRegistry.register(commandA);
+
+		expect(commandRegistry.has('cmd-a')).toBe(true);
+		expect(commandRegistry.get('cmd-a')).toEqual(commandA);
+	});
+
+	it('should return all registered commands in registration order', () => {
+		commandRegistry.register(commandA);
+		commandRegistry.register(commandB);
+
+		expect(commandRegistry.getAll()).toEqual([commandA, commandB]);
+	});
+
+	it('should warn and skip when an id is registered twice', () => {
+		const consoleSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+		commandRegistry.register(commandA);
+		commandRegistry.register(commandA);
+
+		expect(consoleSpy).toHaveBeenCalledWith(
+			'Command with id "cmd-a" is already registered. Skipping.',
+		);
+		expect(commandRegistry.getAll()).toHaveLength(1);
+
+		consoleSpy.mockRestore();
+	});
+
+	it('should notify subscribers on register and unregister', () => {
+		const listener = vi.fn();
+		commandRegistry.subscribe(listener);
+
+		commandRegistry.register(commandA);
+		expect(listener).toHaveBeenLastCalledWith([commandA]);
+
+		commandRegistry.unregister('cmd-a');
+		expect(listener).toHaveBeenLastCalledWith([]);
+	});
+
+	it('should return an unsubscribe function that stops notifications', () => {
+		const listener = vi.fn();
+		const unsubscribe = commandRegistry.subscribe(listener);
+
+		unsubscribe();
+		commandRegistry.register(commandA);
+
+		expect(listener).not.toHaveBeenCalled();
+	});
+});

package/src/registries/commandRegistry.ts

@@ -0,0 +1,51 @@
+import type { CommandBarEntry } from '../types/command';
+
+const commands = new Map<string, CommandBarEntry>();
+const listeners = new Set<(commands: CommandBarEntry[]) => void>();
+
+export function getAll(): CommandBarEntry[] {
+	return Array.from(commands.values());
+}
+
+function notifyListeners(): void {
+	const snapshot = getAll();
+	listeners.forEach((listener) => listener(snapshot));
+}
+
+export function register(command: CommandBarEntry): void {
+	if (commands.has(command.id)) {
+		console.warn(`Command with id "${command.id}" is already registered. Skipping.`);
+		return;
+	}
+	commands.set(command.id, command);
+	notifyListeners();
+}
+
+export function unregister(id: string): void {
+	if (commands.delete(id)) {
+		notifyListeners();
+	}
+}
+
+export function get(id: string): CommandBarEntry | undefined {
+	return commands.get(id);
+}
+
+export function has(id: string): boolean {
+	return commands.has(id);
+}
+
+export function subscribe(listener: (commands: CommandBarEntry[]) => void): () => void {
+	listeners.add(listener);
+	return () => {
+		listeners.delete(listener);
+	};
+}
+
+/**
+ * Remove all registered commands. Primarily for test isolation.
+ */
+export function clear(): void {
+	commands.clear();
+	notifyListeners();
+}

package/src/{modalRegistry.test.ts → registries/modalRegistry.test.ts}

@@ -2,7 +2,7 @@ import { describe, it, expect, beforeEach, vi } from 'vitest';
 import type { Component } from 'vue';
 
 import * as modalRegistry from './modalRegistry';
-import type { ModalDefinition } from './module.types';
+import type { ModalDefinition } from '../types/modal';
 
 describe('modalRegistry', () => {
 	const mockComponent1 = { name: 'TestModal1' } as Component;

package/src/{modalRegistry.ts → registries/modalRegistry.ts}

@@ -1,4 +1,4 @@
-import type { ModalDefinition } from './module.types';
+import type { ModalDefinition } from '../types/modal';
 
 const modals = new Map<string, ModalDefinition>();
 const listeners = new Set<(modals: Map<string, ModalDefinition>) => void>();

package/src/registries/pushHandlerRegistry.test.ts

@@ -0,0 +1,75 @@
+import type { PushMessage } from '@n8n/api-types';
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+
+import * as pushHandlerRegistry from './pushHandlerRegistry';
+import type { ModulePushHandlerContext, ModulePushHandlers } from '../types/push';
+
+const context = { router: {} } as unknown as ModulePushHandlerContext;
+
+describe('pushHandlerRegistry', () => {
+	beforeEach(() => {
+		pushHandlerRegistry.clear();
+	});
+
+	it('should register and retrieve a handler by type', () => {
+		const handler = vi.fn();
+		pushHandlerRegistry.register('executionFinished', handler);
+
+		expect(pushHandlerRegistry.has('executionFinished')).toBe(true);
+		expect(pushHandlerRegistry.get('executionFinished')).toBe(handler);
+	});
+
+	it('should return undefined for an unregistered type', () => {
+		expect(pushHandlerRegistry.get('executionStarted')).toBeUndefined();
+		expect(pushHandlerRegistry.has('executionStarted')).toBe(false);
+	});
+
+	it('should invoke the registered handler with the event and context', async () => {
+		const handler = vi.fn();
+		pushHandlerRegistry.register('executionStarted', handler);
+
+		const event = { type: 'executionStarted', data: {} } as unknown as PushMessage;
+		await pushHandlerRegistry.get('executionStarted')?.(event, context);
+
+		expect(handler).toHaveBeenCalledWith(event, context);
+	});
+
+	it('should warn and keep the first handler when a type is registered twice', () => {
+		const consoleSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+		const first = vi.fn();
+		const second = vi.fn();
+
+		pushHandlerRegistry.register('workflowActivated', first);
+		pushHandlerRegistry.register('workflowActivated', second);
+
+		expect(consoleSpy).toHaveBeenCalledWith(
+			'Push handler for type "workflowActivated" is already registered. Skipping.',
+		);
+		expect(pushHandlerRegistry.get('workflowActivated')).toBe(first);
+
+		consoleSpy.mockRestore();
+	});
+
+	it('should register every entry in a module pushHandlers map', () => {
+		const activated = vi.fn();
+		const deactivated = vi.fn();
+		const handlers: ModulePushHandlers = {
+			workflowActivated: activated,
+			workflowDeactivated: deactivated,
+		};
+
+		pushHandlerRegistry.registerAll(handlers);
+
+		expect(pushHandlerRegistry.getTypes()).toEqual(
+			expect.arrayContaining(['workflowActivated', 'workflowDeactivated']),
+		);
+		expect(pushHandlerRegistry.get('workflowActivated')).toBeDefined();
+	});
+
+	it('should unregister a handler', () => {
+		pushHandlerRegistry.register('workflowDeactivated', vi.fn());
+		pushHandlerRegistry.unregister('workflowDeactivated');
+
+		expect(pushHandlerRegistry.has('workflowDeactivated')).toBe(false);
+	});
+});

package/src/registries/pushHandlerRegistry.ts

@@ -0,0 +1,52 @@
+import type { PushType } from '@n8n/api-types';
+
+import type { ModulePushHandler, ModulePushHandlers } from '../types/push';
+
+// One handler per push message type. The shell consults this before its own
+// switch, so a module can own (or override) a push message type.
+const handlers = new Map<PushType, ModulePushHandler>();
+
+export function register(type: PushType, handler: ModulePushHandler): void {
+	if (handlers.has(type)) {
+		console.warn(`Push handler for type "${type}" is already registered. Skipping.`);
+		return;
+	}
+	handlers.set(type, handler);
+}
+
+/**
+ * Register every handler in a module's `pushHandlers` map. Centralises the one
+ * cast needed to erase the per-type event narrowing: each handler is stored
+ * against its own key, so it only ever receives an event of that type.
+ */
+export function registerAll(pushHandlers: ModulePushHandlers): void {
+	for (const type of Object.keys(pushHandlers) as PushType[]) {
+		const handler = pushHandlers[type];
+		if (handler) {
+			register(type, handler as ModulePushHandler);
+		}
+	}
+}
+
+export function get(type: PushType): ModulePushHandler | undefined {
+	return handlers.get(type);
+}
+
+export function has(type: PushType): boolean {
+	return handlers.has(type);
+}
+
+export function getTypes(): PushType[] {
+	return Array.from(handlers.keys());
+}
+
+export function unregister(type: PushType): void {
+	handlers.delete(type);
+}
+
+/**
+ * Remove all registered handlers. Primarily for test isolation.
+ */
+export function clear(): void {
+	handlers.clear();
+}

package/src/{resourceRegistry.test.ts → registries/resourceRegistry.test.ts}

@@ -1,6 +1,6 @@
 import { describe, it, expect, beforeEach, vi } from 'vitest';
 
-import type { ResourceMetadata } from './module.types';
+import type { ResourceMetadata } from '../types/resource';
 
 // The registry keeps module-level state and exposes no reset, so re-import a
 // fresh module instance before each test to keep them isolated.

package/src/{resourceRegistry.ts → registries/resourceRegistry.ts}

@@ -14,7 +14,7 @@
   	4. Import your resource type from the local types file in your components
  */
 
-import { type ResourceMetadata } from './module.types';
+import { type ResourceMetadata } from '../types/resource';
 
 // Private module state
 const resources: Map<string, ResourceMetadata> = new Map();

package/src/types/banner.ts

@@ -0,0 +1,12 @@
+import type { Component } from 'vue';
+
+/**
+ * A banner a module contributes to the shell's banner stack. `priority` follows
+ * the existing stack semantics (higher wins when several banners are queued).
+ */
+export interface ModuleBanner {
+	name: string;
+	priority: number;
+	component: Component | (() => Promise<Component>);
+	dismissible?: boolean;
+}

package/src/types/command.ts

@@ -0,0 +1,18 @@
+/**
+ * A command-bar entry a module contributes. Deliberately self-contained (a
+ * stable subset of the design-system `CommandBarItem`) so the module contract
+ * does not couple to command-bar internals.
+ */
+export interface CommandBarEntry {
+	id: string;
+	title: string;
+	section?: string;
+	keywords?: string[];
+	icon?: string;
+	handler?: () => void | Promise<void>;
+	children?: CommandBarEntry[];
+	/**
+	 * Route names this command is active on. Undefined/empty means all views.
+	 */
+	activeViews?: string[];
+}

package/src/types/descriptor.test.ts

@@ -0,0 +1,46 @@
+import { describe, it, expect } from 'vitest';
+
+import type { FrontendModuleDescription } from './descriptor';
+
+describe('FrontendModuleDescription', () => {
+	it('accepts a v1-shaped descriptor (no v2 fields)', () => {
+		const descriptor: FrontendModuleDescription = {
+			id: 'legacy',
+			name: 'Legacy',
+			description: 'A descriptor using only the original fields',
+			icon: 'box',
+			routes: [],
+			resources: [{ key: 'legacy', displayName: 'Legacy' }],
+			modals: [],
+			settingsPages: [],
+		};
+
+		expect(descriptor.id).toBe('legacy');
+	});
+
+	it('accepts a v2 descriptor exercising the new optional fields', () => {
+		const cleanups: Array<() => void> = [];
+		const noop = () => {};
+		const descriptor: FrontendModuleDescription = {
+			id: 'v2',
+			name: 'V2',
+			description: 'A descriptor using the v2 fields',
+			icon: 'box',
+			locales: { en: { greeting: 'hi' } },
+			pushHandlers: {
+				workflowActivated: async () => {},
+			},
+			commands: [{ id: 'v2.open', title: 'Open V2' }],
+			shortcuts: [{ keys: 'ctrl+shift+v', run: () => {} }],
+			banners: [{ name: 'v2-banner', priority: 10, component: { name: 'Banner' } }],
+			setup: (ctx) => {
+				ctx.registerCleanup(() => {
+					cleanups.push(noop);
+				});
+			},
+		};
+
+		expect(descriptor.commands?.[0]?.id).toBe('v2.open');
+		expect(descriptor.pushHandlers?.workflowActivated).toBeTypeOf('function');
+	});
+});

package/src/types/descriptor.ts

@@ -0,0 +1,50 @@
+import type { IMenuItem } from '@n8n/design-system';
+import type { RouteRecordRaw } from 'vue-router';
+
+import type { ModuleBanner } from './banner';
+import type { CommandBarEntry } from './command';
+import type { ModuleLocaleMessages } from './locale';
+import type { ModalDefinition } from './modal';
+import type { ModulePushHandlers } from './push';
+import type { ResourceMetadata } from './resource';
+import type { ModuleSetupContext } from './setup';
+import type { ModuleShortcut } from './shortcut';
+import type { DynamicTabOptions } from './tabs';
+
+/**
+ * The declarative contract a frontend module exposes to the editor-ui shell.
+ *
+ * Descriptor v2 adds `locales`, `pushHandlers`, `commands`, `shortcuts`,
+ * `banners`, and a post-login `setup(ctx)` hook. Every v2 field is optional and
+ * additive, so existing descriptors satisfy the type unchanged.
+ */
+export type FrontendModuleDescription = {
+	id: string;
+	name: string;
+	description: string;
+	icon: string;
+	routes?: RouteRecordRaw[];
+	projectTabs?: {
+		overview?: DynamicTabOptions[];
+		project?: DynamicTabOptions[];
+		shared?: DynamicTabOptions[];
+	};
+	resources?: ResourceMetadata[];
+	modals?: ModalDefinition[];
+	settingsPages?: IMenuItem[];
+
+	// --- descriptor v2 (all optional, additive) ---
+
+	/** Per-module i18n messages, merged into the active locale by the shell. */
+	locales?: ModuleLocaleMessages;
+	/** Push-message handlers, keyed by message type. */
+	pushHandlers?: ModulePushHandlers;
+	/** Command-bar contributions. */
+	commands?: CommandBarEntry[];
+	/** Global keyboard shortcuts. */
+	shortcuts?: ModuleShortcut[];
+	/** Banners the module can contribute to the banner stack. */
+	banners?: ModuleBanner[];
+	/** Runs post-login, after the module is confirmed active. */
+	setup?: (ctx: ModuleSetupContext) => void | Promise<void>;
+};

package/src/types/index.ts

@@ -0,0 +1,10 @@
+export type * from './descriptor';
+export type * from './modal';
+export type * from './resource';
+export type * from './tabs';
+export type * from './push';
+export type * from './command';
+export type * from './shortcut';
+export type * from './banner';
+export type * from './setup';
+export type * from './locale';

package/src/types/locale.ts

@@ -0,0 +1,5 @@
+/**
+ * Per-module i18n messages, keyed by locale code (e.g. `en`). Values are merged
+ * additively into the active vue-i18n bundle by the shell.
+ */
+export type ModuleLocaleMessages = Record<string, Record<string, unknown>>;

package/src/types/modal.ts

@@ -0,0 +1,20 @@
+import type { Component } from 'vue';
+
+/**
+ * Shared state shape a modal is initialized with. The SDK owns this type; the
+ * editor-ui shell re-exports it from `@/Interface` for backwards compatibility.
+ */
+export type ModalState = {
+	open: boolean;
+	mode?: string | null;
+	data?: Record<string, unknown>;
+	activeId?: string | null;
+	curlCommand?: string;
+	httpNodeParameters?: string;
+};
+
+export type ModalDefinition = {
+	key: string;
+	component: Component | (() => Promise<Component>);
+	initialState?: ModalState;
+};

package/src/types/push.ts

@@ -0,0 +1,30 @@
+import type { PushMessage, PushType } from '@n8n/api-types';
+import type { Router } from 'vue-router';
+
+/**
+ * Context handed to a module push handler when it runs. The shell may pass a
+ * richer context (it extends this); handlers only see the stable surface.
+ */
+export interface ModulePushHandlerContext {
+	router: Router;
+}
+
+/**
+ * Handler for a single push message type. Contravariant in its context so the
+ * shell can supply a superset context at call time.
+ */
+export type ModulePushHandler<Ctx extends ModulePushHandlerContext = ModulePushHandlerContext> = (
+	event: PushMessage,
+	context: Ctx,
+) => void | Promise<void>;
+
+/**
+ * A module's push-message contributions, keyed by message type. Each handler
+ * receives the event already narrowed to its type.
+ */
+export type ModulePushHandlers = {
+	[T in PushType]?: (
+		event: Extract<PushMessage, { type: T }>,
+		context: ModulePushHandlerContext,
+	) => void | Promise<void>;
+};

package/src/types/resource.ts

@@ -0,0 +1,9 @@
+/**
+ * Metadata a module contributes to describe a resource type it owns. Consumed by
+ * generic list surfaces (e.g. `ResourcesListLayout`).
+ */
+export type ResourceMetadata = {
+	key: string;
+	displayName: string;
+	i18nKeys?: Record<string, string>;
+};

package/src/types/setup.ts

@@ -0,0 +1,16 @@
+import type { Router } from 'vue-router';
+
+export type ModuleCleanupFn = () => void | Promise<void>;
+
+/**
+ * Context handed to a module's post-login `setup(ctx)` hook. Kept intentionally
+ * small; grow it as modules need more, rather than exposing stores directly.
+ */
+export interface ModuleSetupContext {
+	router: Router;
+	/**
+	 * Register a teardown callback to run when the authenticated session ends
+	 * (e.g. on logout). Cleanups run in reverse registration order.
+	 */
+	registerCleanup: (fn: ModuleCleanupFn) => void;
+}

package/src/types/shortcut.ts

@@ -0,0 +1,9 @@
+/**
+ * A global keyboard shortcut a module contributes. `keys` uses the same syntax
+ * as the shell's `useKeybindings` (e.g. `'ctrl+k'`, `'ctrl+b|ctrl+c'`).
+ */
+export interface ModuleShortcut {
+	keys: string;
+	run: (event: KeyboardEvent) => void;
+	disabled?: () => boolean;
+}

package/src/types/tabs.ts

@@ -0,0 +1,17 @@
+import type { TabOptions } from '@n8n/design-system';
+
+/**
+ * A project/overview tab a module contributes. `dynamicRoute` is resolved with
+ * the current project id at render time by the shell's `processDynamicTab`.
+ */
+export type DynamicTabOptions = TabOptions<string> & {
+	dynamicRoute?: {
+		name: string;
+		includeProjectId?: boolean;
+	};
+	/**
+	 * Insert this tab immediately after the tab whose `value` matches.
+	 * If unset (or no match is found at render time), the tab is appended at the end.
+	 */
+	insertAfter?: string;
+};

package/src/module.types.ts

@@ -1,52 +0,0 @@
-import type { IMenuItem, TabOptions } from '@n8n/design-system';
-import type { Component } from 'vue';
-import type { RouteRecordRaw } from 'vue-router';
-
-export type ModalState = {
-	open: boolean;
-	mode?: string | null;
-	data?: Record<string, unknown>;
-	activeId?: string | null;
-	curlCommand?: string;
-	httpNodeParameters?: string;
-};
-
-export type DynamicTabOptions = TabOptions<string> & {
-	dynamicRoute?: {
-		name: string;
-		includeProjectId?: boolean;
-	};
-	/**
-	 * Insert this tab immediately after the tab whose `value` matches.
-	 * If unset (or no match is found at render time), the tab is appended at the end.
-	 */
-	insertAfter?: string;
-};
-
-export type ModalDefinition = {
-	key: string;
-	component: Component | (() => Promise<Component>);
-	initialState?: ModalState;
-};
-
-export type ResourceMetadata = {
-	key: string;
-	displayName: string;
-	i18nKeys?: Record<string, string>;
-};
-
-export type FrontendModuleDescription = {
-	id: string;
-	name: string;
-	description: string;
-	icon: string;
-	routes?: RouteRecordRaw[];
-	projectTabs?: {
-		overview?: DynamicTabOptions[];
-		project?: DynamicTabOptions[];
-		shared?: DynamicTabOptions[];
-	};
-	resources?: ResourceMetadata[];
-	modals?: ModalDefinition[];
-	settingsPages?: IMenuItem[];
-};