@n8n/frontend-module-insights 0.1.0

package/src/insights.api.ts

@@ -0,0 +1,71 @@
+import { getLocalTimeZone } from '@internationalized/date';
+import type {
+	InsightsSummary,
+	InsightsByTime,
+	InsightsByWorkflow,
+	ListInsightsWorkflowQueryDto,
+	InsightsDateFilterDto,
+} from '@n8n/api-types';
+import { makeRestApiRequest } from '@n8n/rest-api-client';
+import type { IRestApiContext } from '@n8n/rest-api-client';
+
+type SerializedDateFilter<T> = Omit<T, 'startDate' | 'endDate'> & {
+	startDate?: string;
+	endDate?: string;
+};
+
+export function serializeInsightsFilter<
+	T extends InsightsDateFilterDto | ListInsightsWorkflowQueryDto,
+>(filter?: T): SerializedDateFilter<T> | undefined {
+	if (!filter) return undefined;
+
+	const { startDate, endDate, ...rest } = filter;
+	const serialized: SerializedDateFilter<T> = { ...rest };
+
+	if (startDate) {
+		serialized.startDate = startDate.toISOString();
+	}
+	if (endDate) {
+		serialized.endDate = endDate.toISOString();
+	}
+
+	// Send the browser timezone so the backend floors custom ranges to the day the
+	// user actually selected instead of the UTC calendar day.
+	serialized.timeZone = getLocalTimeZone();
+
+	return serialized;
+}
+
+export const fetchInsightsSummary = async (
+	context: IRestApiContext,
+	filter?: InsightsDateFilterDto,
+): Promise<InsightsSummary> =>
+	await makeRestApiRequest(context, 'GET', '/insights/summary', serializeInsightsFilter(filter));
+
+export const fetchInsightsByTime = async (
+	context: IRestApiContext,
+	filter?: InsightsDateFilterDto,
+): Promise<InsightsByTime[]> =>
+	await makeRestApiRequest(context, 'GET', '/insights/by-time', serializeInsightsFilter(filter));
+
+export const fetchInsightsTimeSaved = async (
+	context: IRestApiContext,
+	filter?: InsightsDateFilterDto,
+): Promise<InsightsByTime[]> =>
+	await makeRestApiRequest(
+		context,
+		'GET',
+		'/insights/by-time/time-saved',
+		serializeInsightsFilter(filter),
+	);
+
+export const fetchInsightsByWorkflow = async (
+	context: IRestApiContext,
+	filter?: ListInsightsWorkflowQueryDto,
+): Promise<InsightsByWorkflow> =>
+	await makeRestApiRequest(
+		context,
+		'GET',
+		'/insights/by-workflow',
+		serializeInsightsFilter(filter),
+	);

package/src/insights.constants.ts

@@ -0,0 +1,69 @@
+import type { InsightsSummaryType } from '@n8n/api-types';
+import dateformat from 'dateformat';
+
+export const INSIGHT_TYPES = {
+	TOTAL: 'total',
+	FAILED: 'failed',
+	FAILURE_RATE: 'failureRate',
+	TIME_SAVED: 'timeSaved',
+	AVERAGE_RUN_TIME: 'averageRunTime',
+} as const;
+
+export const INSIGHTS_SUMMARY_ORDER: InsightsSummaryType[] = [
+	INSIGHT_TYPES.TOTAL,
+	INSIGHT_TYPES.FAILED,
+	INSIGHT_TYPES.FAILURE_RATE,
+	INSIGHT_TYPES.TIME_SAVED,
+	INSIGHT_TYPES.AVERAGE_RUN_TIME,
+] as const;
+
+export const INSIGHTS_UNIT_MAPPING: Record<InsightsSummaryType, (value: number) => string> = {
+	total: () => '',
+	failed: () => '',
+	failureRate: () => '%',
+	timeSaved: (value: number) => (Math.abs(value) < 60 ? 'm' : 'h'),
+	averageRunTime: () => 's',
+} as const;
+
+export const INSIGHTS_DEVIATION_UNIT_MAPPING: Record<
+	InsightsSummaryType,
+	(deviation: number) => string
+> = {
+	total: () => '%',
+	failed: () => '%',
+	failureRate: () => 'pp',
+	timeSaved: (deviation: number) => (Math.abs(deviation) < 60 ? 'm' : 'h'),
+	averageRunTime: () => 's',
+} as const;
+
+export const INSIGHT_IMPACT_TYPES = {
+	POSITIVE: 'positive',
+	NEGATIVE: 'negative',
+	NEUTRAL: 'neutral',
+} as const;
+
+export const INSIGHTS_UNIT_IMPACT_MAPPING: Record<
+	InsightsSummaryType,
+	(typeof INSIGHT_IMPACT_TYPES)[keyof typeof INSIGHT_IMPACT_TYPES]
+> = {
+	total: INSIGHT_IMPACT_TYPES.POSITIVE,
+	failed: INSIGHT_IMPACT_TYPES.NEGATIVE,
+	failureRate: INSIGHT_IMPACT_TYPES.NEGATIVE, // Higher failureRate is bad → negative (red)
+	timeSaved: INSIGHT_IMPACT_TYPES.POSITIVE, // More time saved is good → positive (green)
+	averageRunTime: INSIGHT_IMPACT_TYPES.NEUTRAL, // Not good or bad → neutral (grey)
+} as const;
+
+export const GRANULARITY_DATE_FORMAT_MASK = {
+	hour: (date: string) => dateformat(date, 'HH:MM'),
+	day: (date: string) => dateformat(date, 'mmm d'),
+	week: (date: string) => {
+		const startDate = new Date(date);
+		const endDate = new Date(startDate);
+		endDate.setDate(startDate.getDate() + 7);
+
+		const spansTwoMonths = startDate.getMonth() !== endDate.getMonth();
+		const endDateFormat = spansTwoMonths ? 'mmm d' : 'd';
+
+		return [dateformat(startDate, 'mmm d'), dateformat(endDate, endDateFormat)].join('-');
+	},
+};

package/src/insights.module.test.ts

@@ -0,0 +1,59 @@
+import { VIEWS } from '@n8n/frontend-constants/views';
+import { createMemoryHistory, createRouter, type RouteRecordRaw } from 'vue-router';
+
+import { InsightsModule } from './insights.module';
+
+const mocks = vi.hoisted(() => ({ isInsightsEnabled: true }));
+
+vi.mock('./insights.store', () => ({
+	useInsightsStore: () => ({
+		get isInsightsEnabled() {
+			return mocks.isInsightsEnabled;
+		},
+	}),
+}));
+
+const stub = { render: () => null };
+
+// Swap the lazy dashboard for a stub so navigation doesn't pull the chart tree.
+function withStubbedComponents(route: RouteRecordRaw): RouteRecordRaw {
+	const clone = { ...route } as Record<string, unknown>;
+	if (Array.isArray(clone.children)) {
+		clone.children = (clone.children as RouteRecordRaw[]).map(withStubbedComponents);
+	} else if (clone.component) {
+		clone.component = stub;
+	}
+	return clone as unknown as RouteRecordRaw;
+}
+
+function createTestRouter() {
+	return createRouter({
+		history: createMemoryHistory(),
+		routes: [
+			...(InsightsModule.routes ?? []).map(withStubbedComponents),
+			{ path: '/:pathMatch(.*)*', name: VIEWS.NOT_FOUND, component: stub },
+		],
+	});
+}
+
+describe('InsightsModule routes', () => {
+	beforeEach(() => {
+		mocks.isInsightsEnabled = true;
+	});
+
+	it('enters the dashboard with a default insight type when insights is enabled', async () => {
+		const router = createTestRouter();
+		await router.push('/insights');
+
+		expect(router.currentRoute.value.name).toBe(VIEWS.INSIGHTS);
+		expect(router.currentRoute.value.params).toEqual({ insightType: 'total' });
+	});
+
+	it('redirects to not found when insights is disabled', async () => {
+		mocks.isInsightsEnabled = false;
+		const router = createTestRouter();
+		await router.push('/insights');
+
+		expect(router.currentRoute.value.name).toBe(VIEWS.NOT_FOUND);
+	});
+});

package/src/insights.module.ts

@@ -0,0 +1,45 @@
+import { VIEWS } from '@n8n/frontend-constants/views';
+import type { FrontendModuleDescription } from '@n8n/frontend-module-sdk';
+import { RouterView } from 'vue-router';
+
+const InsightsDashboard = async () => await import('./components/InsightsDashboard.vue');
+
+export const InsightsModule: FrontendModuleDescription = {
+	id: 'insights',
+	name: 'Insights',
+	description: 'Provides insights and analytics features for projects.',
+	icon: 'chart-column-decreasing',
+	routes: [
+		{
+			path: '/insights',
+			// Loaded inside the guard, not at module top level: the descriptor is imported
+			// eagerly by the shell manifest, so a static store import would pull the whole
+			// feature into the boot chunk even when the module is disabled.
+			async beforeEnter() {
+				const { useInsightsStore } = await import('./insights.store');
+				return useInsightsStore().isInsightsEnabled || { name: VIEWS.NOT_FOUND };
+			},
+			component: RouterView,
+			meta: {
+				middleware: ['authenticated', 'rbac'],
+				middlewareOptions: {
+					rbac: {
+						scope: ['insights:list'],
+					},
+				},
+			},
+			children: [
+				{
+					path: ':insightType?',
+					name: VIEWS.INSIGHTS,
+					beforeEnter(to) {
+						if (to.params.insightType) return true;
+						return Object.assign(to, { params: { ...to.params, insightType: 'total' } });
+					},
+					component: InsightsDashboard,
+					props: true,
+				},
+			],
+		},
+	],
+};

package/src/insights.store.test.ts

@@ -0,0 +1,118 @@
+import type { FrontendModuleSettings } from '@n8n/api-types';
+import { mockedStore, type MockedStore } from '@n8n/frontend-test-utils';
+import type { IUser } from '@n8n/rest-api-client/api/users';
+import { useSettingsStore } from '@n8n/stores/settings.store';
+import { useRootStore } from '@n8n/stores/useRootStore';
+import { useUsersStore } from '@n8n/stores/users.store';
+import { createTestingPinia } from '@pinia/testing';
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { reactive } from 'vue';
+
+import * as insightsApi from './insights.api';
+import { useInsightsStore } from './insights.store';
+
+vi.mock('vue-router', async (importOriginal) => ({
+	...(await importOriginal()),
+	useRoute: () => reactive({}),
+}));
+vi.mock('./insights.api');
+
+const mockFilter = { projectId: 'test-project' };
+const mockData = [
+	{
+		date: '2023-01-01',
+		values: {
+			total: 100,
+			failed: 10,
+			failureRate: 10,
+			timeSaved: 50,
+			averageRunTime: 5,
+			succeeded: 90,
+		},
+	},
+];
+
+describe('useInsightsStore', () => {
+	let insightsStore: ReturnType<typeof useInsightsStore>;
+	let settingsStore: MockedStore<typeof useSettingsStore>;
+	let rootStore: MockedStore<typeof useRootStore>;
+	let usersStore: MockedStore<typeof useUsersStore>;
+
+	beforeEach(() => {
+		createTestingPinia();
+
+		settingsStore = mockedStore(useSettingsStore);
+		rootStore = mockedStore(useRootStore);
+		usersStore = mockedStore(useUsersStore);
+
+		rootStore.restApiContext = {
+			baseUrl: 'http://localhost',
+			pushRef: 'pushRef',
+		};
+
+		usersStore.currentUser = { globalScopes: ['insights:list'] } as IUser;
+
+		insightsStore = useInsightsStore();
+	});
+
+	afterEach(() => {
+		vi.clearAllMocks();
+	});
+
+	describe('charts data fetcher', () => {
+		it('should use fetchInsightsTimeSaved when dashboard is disabled', async () => {
+			settingsStore.moduleSettings = { insights: { dashboard: false } } as FrontendModuleSettings;
+
+			vi.mocked(insightsApi.fetchInsightsTimeSaved).mockResolvedValue(mockData);
+
+			await insightsStore.charts.execute(0, mockFilter);
+
+			expect(insightsApi.fetchInsightsTimeSaved).toHaveBeenCalledWith(
+				rootStore.restApiContext,
+				mockFilter,
+			);
+			expect(insightsApi.fetchInsightsByTime).not.toHaveBeenCalled();
+		});
+
+		it('should use fetchInsightsByTime when dashboard is enabled', async () => {
+			settingsStore.moduleSettings = { insights: { dashboard: true } } as FrontendModuleSettings;
+
+			vi.mocked(insightsApi.fetchInsightsByTime).mockResolvedValue(mockData);
+
+			await insightsStore.charts.execute(0, mockFilter);
+
+			expect(insightsApi.fetchInsightsByTime).toHaveBeenCalledWith(
+				rootStore.restApiContext,
+				mockFilter,
+			);
+			expect(insightsApi.fetchInsightsTimeSaved).not.toHaveBeenCalled();
+		});
+
+		it('should use fetchInsightsTimeSaved when dashboard setting is undefined', async () => {
+			settingsStore.moduleSettings = { insights: {} } as FrontendModuleSettings;
+
+			vi.mocked(insightsApi.fetchInsightsTimeSaved).mockResolvedValue(mockData);
+
+			await insightsStore.charts.execute(0, mockFilter);
+
+			expect(insightsApi.fetchInsightsTimeSaved).toHaveBeenCalledWith(
+				rootStore.restApiContext,
+				mockFilter,
+			);
+			expect(insightsApi.fetchInsightsByTime).not.toHaveBeenCalled();
+		});
+
+		it('should work without filter parameter', async () => {
+			settingsStore.moduleSettings = { insights: { dashboard: true } } as FrontendModuleSettings;
+
+			vi.mocked(insightsApi.fetchInsightsByTime).mockResolvedValue(mockData);
+
+			await insightsStore.charts.execute();
+
+			expect(insightsApi.fetchInsightsByTime).toHaveBeenCalledWith(
+				rootStore.restApiContext,
+				undefined,
+			);
+		});
+	});
+});

package/src/insights.store.ts

@@ -0,0 +1,88 @@
+import type { ListInsightsWorkflowQueryDto, InsightsDateFilterDto } from '@n8n/api-types';
+import { getResourcePermissions } from '@n8n/permissions';
+import { useSettingsStore } from '@n8n/stores/settings.store';
+import { useRootStore } from '@n8n/stores/useRootStore';
+import { useUsersStore } from '@n8n/stores/users.store';
+import { useAsyncState } from '@vueuse/core';
+import { defineStore } from 'pinia';
+import { computed } from 'vue';
+
+import * as insightsApi from './insights.api';
+import { transformInsightsSummary } from './insights.utils';
+
+export const useInsightsStore = defineStore('insights', () => {
+	const rootStore = useRootStore();
+	const usersStore = useUsersStore();
+	const settingsStore = useSettingsStore();
+
+	const globalInsightsPermissions = computed(
+		() => getResourcePermissions(usersStore.currentUser?.globalScopes).insights,
+	);
+
+	const isInsightsEnabled = computed(() => settingsStore.isModuleActive('insights'));
+
+	const isDashboardEnabled = computed(() => !!settingsStore.moduleSettings.insights?.dashboard);
+
+	const isSummaryEnabled = computed(
+		() => globalInsightsPermissions.value.list && isInsightsEnabled.value,
+	);
+
+	const weeklySummary = useAsyncState(
+		async () => {
+			const raw = await insightsApi.fetchInsightsSummary(rootStore.restApiContext);
+			return transformInsightsSummary(raw);
+		},
+		[],
+		{ immediate: false, resetOnExecute: false },
+	);
+
+	const summary = useAsyncState(
+		async (filter?: InsightsDateFilterDto) => {
+			const raw = await insightsApi.fetchInsightsSummary(rootStore.restApiContext, filter);
+			return transformInsightsSummary(raw);
+		},
+		[],
+		{ immediate: false, resetOnExecute: false },
+	);
+
+	const charts = useAsyncState(
+		async (filter?: InsightsDateFilterDto) => {
+			const dataFetcher = isDashboardEnabled.value
+				? insightsApi.fetchInsightsByTime
+				: insightsApi.fetchInsightsTimeSaved;
+			return await dataFetcher(rootStore.restApiContext, filter);
+		},
+		[],
+		{ immediate: false, resetOnExecute: false },
+	);
+
+	const table = useAsyncState(
+		async (filter?: ListInsightsWorkflowQueryDto) => {
+			return await insightsApi.fetchInsightsByWorkflow(rootStore.restApiContext, filter);
+		},
+		{
+			count: 0,
+			data: [],
+		},
+		{ immediate: false, resetOnExecute: false },
+	);
+
+	const dateRanges = computed(() => settingsStore.moduleSettings.insights?.dateRanges ?? []);
+
+	const earliestDataDate = computed(
+		() => settingsStore.moduleSettings.insights?.earliestDataDate ?? null,
+	);
+
+	return {
+		globalInsightsPermissions,
+		isInsightsEnabled,
+		isSummaryEnabled,
+		isDashboardEnabled,
+		weeklySummary,
+		summary,
+		charts,
+		table,
+		dateRanges,
+		earliestDataDate,
+	};
+});

package/src/insights.types.ts

@@ -0,0 +1,16 @@
+import type { INSIGHTS_UNIT_MAPPING, INSIGHTS_DEVIATION_UNIT_MAPPING } from './insights.constants';
+
+type InsightsDisplayUnits = typeof INSIGHTS_UNIT_MAPPING;
+type InsightsDisplayDeviationUnits = typeof INSIGHTS_DEVIATION_UNIT_MAPPING;
+
+export type InsightsSummaryDisplay = Array<
+	{
+		[K in keyof InsightsDisplayUnits]: {
+			id: K;
+			value: number;
+			deviation: number | null;
+			deviationUnit: ReturnType<InsightsDisplayDeviationUnits[K]>;
+			unit: ReturnType<InsightsDisplayUnits[K]>;
+		};
+	}[keyof InsightsDisplayUnits]
+>;