@flowdular/sdk 0.1.0

package/.ai/references/catalog/tests/agent-tools.test.ts

@@ -0,0 +1,277 @@
+import type { DatabaseProvider } from '@flowdular/sdk/database';
+import { validateToolInput, validateToolOutput } from '@flowdular/sdk/harness';
+import type { AgentToolContext } from '@flowdular/sdk/harness/runtime';
+import { afterAll, afterEach, describe, expect, it } from 'vitest';
+import { catalogAgentTools } from '../src/agent/tools.ts';
+import type { CatalogItem } from '../src/domain/types.ts';
+import {
+	createCatalogRuntime,
+	type CatalogRuntime,
+} from '../src/server/runtime.ts';
+import {
+	agentActor,
+	createPlatformVariableRegistry,
+} from '@flowdular/sdk/kernel';
+import { CATALOG_PERMISSIONS } from '../src/acl/permissions.ts';
+import { registerCatalogVariableSource } from '../src/domain/variables.ts';
+import {
+	catalogTestProvider,
+	closeCatalogTestDatabases,
+} from './support/database.ts';
+
+const runtimes = new Set<CatalogRuntime>();
+
+afterEach(async () => {
+	await Promise.all([...runtimes].map((runtime) => runtime.dispose()));
+	runtimes.clear();
+});
+
+afterAll(closeCatalogTestDatabases);
+
+function catalogRuntime(databases: DatabaseProvider): CatalogRuntime {
+	const runtime = createCatalogRuntime({ databases, purpose: 'test' });
+	runtimes.add(runtime);
+	return runtime;
+}
+
+/* execute never reads context.permissions: RBAC is enforced by the harness
+   before it calls the tool, and that path is proven in modules/agents. These
+   tests cover what the tool itself owns: tenant from context, reused service
+   validation, and bounded output. */
+function toolContext(
+	tenantId: string,
+	overrides: Partial<AgentToolContext> = {},
+): AgentToolContext {
+	return {
+		runId: 'run-1',
+		tenantId,
+		requestedBy: 'account-1',
+		idempotencyKey: 'direct-tool-call-1',
+		permissions: new Set<string>(),
+		signal: new AbortController().signal,
+		...overrides,
+	};
+}
+
+const item = (sku: string) => ({
+	sku,
+	name: `Item ${sku}`,
+	kind: 'product' as const,
+	unit: 'ea',
+	basePriceMinor: 1000,
+	currency: 'EUR',
+});
+
+describe('catalog agent tools', () => {
+	it('registers the two catalog tools with the right permissions', async () => {
+		expect(
+			catalogAgentTools(catalogRuntime(await catalogTestProvider())).map(
+				(tool) => ({
+					id: tool.id,
+					permissions: tool.requiredPermissions,
+					version: tool.contractVersion,
+					risk: tool.risk,
+					idempotency: tool.idempotency,
+					idempotencyProtection: tool.idempotencyProtection,
+					cancellation: tool.cancellation,
+					hasInput: tool.inputSchema !== undefined,
+					hasOutput: tool.outputSchema !== undefined,
+				}),
+			),
+		).toEqual([
+			{
+				id: 'catalog.item.list',
+				permissions: ['catalog.items.read'],
+				version: 1,
+				risk: 'read',
+				idempotency: 'required',
+				idempotencyProtection: undefined,
+				cancellation: 'cooperative',
+				hasInput: true,
+				hasOutput: true,
+			},
+			{
+				id: 'catalog.item.create',
+				permissions: ['catalog.items.manage'],
+				version: 1,
+				risk: 'workspace-write',
+				idempotency: 'required',
+				idempotencyProtection: 'target-ledger',
+				cancellation: 'cooperative',
+				hasInput: true,
+				hasOutput: true,
+			},
+		]);
+	});
+
+	it('cooperates with cancellation before reading or writing', async () => {
+		const controller = new AbortController();
+		controller.abort('workflow-cancelled');
+		const [list, create] = catalogAgentTools(
+			catalogRuntime(await catalogTestProvider()),
+		);
+		await expect(
+			list!.execute({}, toolContext('tenant-a', { signal: controller.signal })),
+		).rejects.toBeDefined();
+		await expect(
+			create!.execute(
+				item('CANCELLED-1'),
+				toolContext('tenant-a', { signal: controller.signal }),
+			),
+		).rejects.toBeDefined();
+	});
+
+	it('refuses a mutating call without a durable idempotency key', async () => {
+		const create = catalogAgentTools(
+			catalogRuntime(await catalogTestProvider()),
+		)[1]!;
+		const { idempotencyKey: _ignored, ...withoutKey } = toolContext('tenant-a');
+		await expect(
+			create.execute(item('NO-KEY'), withoutKey as AgentToolContext),
+		).rejects.toMatchObject({ code: 'TOOL_IDEMPOTENCY_KEY_REQUIRED' });
+	});
+
+	it('validates workflow action input and output against the published schemas', async () => {
+		const [list, create] = catalogAgentTools(
+			catalogRuntime(await catalogTestProvider()),
+		);
+		expect(() =>
+			validateToolInput(create!.inputSchema, {
+				...item('INVALID-TENANT'),
+				tenantId: 'tenant-b',
+			}),
+		).toThrowError(/tenantId/);
+		const listed = await list!.execute({}, toolContext('tenant-a'));
+		expect(() => validateToolOutput(list!.outputSchema, listed)).not.toThrow();
+		const created = await create!.execute(
+			item('SCHEMA-1'),
+			toolContext('tenant-a'),
+		);
+		expect(() =>
+			validateToolOutput(create!.outputSchema, created),
+		).not.toThrow();
+	});
+
+	it('creates under the run tenant and ignores a tenant named in the input', async () => {
+		const runtime = catalogRuntime(await catalogTestProvider());
+		const [, create] = catalogAgentTools(runtime);
+		const created = (await create!.execute(
+			{ ...item('SKU-1'), tenantId: 'tenant-b' },
+			toolContext('tenant-a'),
+		)) as CatalogItem;
+		expect(created.tenantId).toBe('tenant-a');
+		await expect(
+			(await runtime.service()).list('tenant-a'),
+		).resolves.toHaveLength(1);
+		await expect(
+			(await runtime.service()).list('tenant-b'),
+		).resolves.toHaveLength(0);
+	});
+
+	it('preserves a workflow service actor and its configuring user in history', async () => {
+		const runtime = catalogRuntime(await catalogTestProvider());
+		const [, create] = catalogAgentTools(runtime);
+		const actor = {
+			kind: 'service',
+			id: 'workflow:catalog-sync',
+			label: 'Catalog sync',
+			configuredBy: {
+				kind: 'user',
+				id: 'account-owner',
+				label: 'Workspace owner',
+			},
+		} as const;
+		const created = (await create!.execute(
+			item('WORKFLOW-1'),
+			toolContext('tenant-a', {
+				actor,
+				idempotencyKey: 'workflow-run:node:attempt-1',
+			}),
+		)) as CatalogItem;
+
+		expect(
+			(
+				await (
+					await runtime.service()
+				).history('tenant-a', {
+					recordId: created.id,
+					limit: 10,
+					cursor: null,
+				})
+			).entries[0]?.actor,
+		).toEqual(actor);
+		await expect((await runtime.service()).list('tenant-b')).resolves.toEqual(
+			[],
+		);
+	});
+
+	it('reuses the service validation so a tool cannot persist a bad currency', async () => {
+		const runtime = catalogRuntime(await catalogTestProvider());
+		const [, create] = catalogAgentTools(runtime);
+		await expect(
+			create!.execute(
+				{ ...item('SKU-2'), currency: 'US' },
+				toolContext('tenant-a'),
+			),
+		).rejects.toMatchObject({ code: 'INVALID_INPUT' });
+	});
+
+	it('bounds list output at the page cap and filters by query', async () => {
+		const runtime = catalogRuntime(await catalogTestProvider());
+		const [list] = catalogAgentTools(runtime);
+		for (let index = 0; index < 205; index += 1) {
+			const context = toolContext('tenant-a');
+			await (
+				await runtime.service()
+			).create(
+				'tenant-a',
+				item(`SKU-${String(index).padStart(3, '0')}`),
+				agentActor(context),
+			);
+		}
+		expect(
+			(await list!.execute(
+				{},
+				toolContext('tenant-a'),
+			)) as readonly CatalogItem[],
+		).toHaveLength(200);
+
+		const filtered = (await list!.execute(
+			{ query: 'sku-004' },
+			toolContext('tenant-a'),
+		)) as readonly CatalogItem[];
+		expect(filtered.map((entry) => entry.sku)).toEqual(['SKU-004']);
+	});
+
+	it('resolves catalog variables through the tenant-scoped read tool', async () => {
+		const runtime = catalogRuntime(await catalogTestProvider());
+		const tools = catalogAgentTools(runtime);
+		const created = (await tools[1]!.execute(
+			item('LINKED-1'),
+			toolContext('tenant-a'),
+		)) as CatalogItem;
+		const registry = createPlatformVariableRegistry();
+		registerCatalogVariableSource(registry, tools);
+		const request = (tenantId: string) => ({
+			tenantId,
+			actor: {
+				kind: 'user' as const,
+				id: 'account-1',
+				label: 'Account 1',
+			},
+			permissionSnapshot: [CATALOG_PERMISSIONS.read],
+			signal: new AbortController().signal,
+			bindings: { catalogItemId: created.id },
+		});
+
+		await expect(
+			registry.resolve(
+				'{{ catalogItem.sku }}: {{ catalogItem.name }}',
+				request('tenant-a'),
+			),
+		).resolves.toBe('LINKED-1: Item LINKED-1');
+		await expect(
+			registry.resolve('{{ catalogItem.name }}', request('tenant-b')),
+		).rejects.toMatchObject({ code: 'VARIABLE_VALUE_UNAVAILABLE' });
+	});
+});

package/.ai/references/catalog/tests/endpoints.test.ts

@@ -0,0 +1,320 @@
+import type { DatabaseProvider } from '@flowdular/sdk/database';
+import type { AuthPrincipal } from '@flowdular/sdk/modules/auth';
+import type { AuthRuntime } from '@flowdular/sdk/modules/auth/server';
+import { AUTH_PRINCIPAL_STATE_KEY } from '@flowdular/sdk/modules/auth/server';
+import { afterAll, afterEach, describe, expect, it } from 'vitest';
+import { createCatalogRoutes } from '../src/api/endpoints.ts';
+import { CATALOG_PERMISSIONS } from '../src/acl/permissions.ts';
+import {
+	createCatalogRuntime,
+	type CatalogRuntime,
+} from '../src/server/runtime.ts';
+import {
+	catalogTestProvider,
+	closeCatalogTestDatabases,
+} from './support/database.ts';
+
+/* auth.core resolves the browser session in its middleware and publishes it in
+   context state; sessionMutationDenial reads it from there. The key is not yet
+   exported from @flowdular/sdk/modules/auth/server, so this double mirrors it. */
+const AUTH_SESSION_STATE_KEY = 'flowdular.auth.session';
+
+type CatalogRoute = ReturnType<typeof createCatalogRoutes>[number];
+type CatalogRouteContext = Parameters<CatalogRoute['handler']>[0];
+
+const runtimes = new Set<CatalogRuntime>();
+
+afterEach(async () => {
+	await Promise.all([...runtimes].map((runtime) => runtime.dispose()));
+	runtimes.clear();
+});
+
+afterAll(closeCatalogTestDatabases);
+
+function catalogRuntime(databases: DatabaseProvider): CatalogRuntime {
+	const runtime = createCatalogRuntime({ databases, purpose: 'test' });
+	runtimes.add(runtime);
+	return runtime;
+}
+
+function principal(
+	scopes: readonly string[],
+	tenantId = 'tenant-a',
+): AuthPrincipal {
+	return {
+		accountId: 'account-a',
+		tenantId,
+		email: 'owner@example.test',
+		displayName: 'Owner',
+		role: 'owner',
+		scopes,
+		tenants: [],
+	};
+}
+
+function authRuntime(actor: AuthPrincipal): AuthRuntime {
+	const session = {
+		principal: actor,
+		csrfToken: 'csrf-token',
+		expiresAt: Date.now() + 60_000,
+		sessionId: 'session-id',
+		passwordChangeRequired: false,
+	};
+	return {
+		cookie: { name: 'test-session', secure: false, maxAgeSeconds: 3_600 },
+		authorizeAgentToolAccess: () => [],
+		service: () => ({
+			resolveSession: (token: string) => (token === 'token' ? session : null),
+		}),
+	} as unknown as AuthRuntime;
+}
+
+function context(request: Request, actor?: AuthPrincipal): CatalogRouteContext {
+	const state = new Map<string, unknown>();
+	if (actor) {
+		state.set(AUTH_PRINCIPAL_STATE_KEY, actor);
+		state.set(AUTH_SESSION_STATE_KEY, {
+			principal: actor,
+			csrfToken: 'csrf-token',
+			expiresAt: Date.now() + 60_000,
+			sessionId: 'session-id',
+			passwordChangeRequired: false,
+		});
+	}
+	return {
+		request,
+		url: new URL(request.url),
+		state,
+	} as unknown as CatalogRouteContext;
+}
+
+function mutation(path: string, body: unknown, csrf = 'csrf-token'): Request {
+	return new Request(`https://erp.example${path}`, {
+		method: 'POST',
+		headers: {
+			'content-type': 'application/json',
+			origin: 'https://erp.example',
+			cookie: 'test-session=token',
+			'x-csrf-token': csrf,
+		},
+		body: JSON.stringify(body),
+	});
+}
+
+function route(
+	routes: readonly CatalogRoute[],
+	path: string,
+	method: string,
+): CatalogRoute {
+	const result = routes.find(
+		(entry) => entry.path === path && entry.methods.includes(method),
+	);
+	if (!result) throw new Error(`Missing ${method} ${path}.`);
+	return result;
+}
+
+describe('catalog lifecycle and history endpoints', () => {
+	it('returns 401 and 403 for every endpoint before access to tenant data', async () => {
+		const routes = createCatalogRoutes(
+			{ authorizeAgentToolAccess: () => [] } as unknown as AuthRuntime,
+			catalogRuntime(await catalogTestProvider()),
+		);
+		for (const endpoint of routes) {
+			const method = endpoint.methods.includes('GET') ? 'GET' : 'POST';
+			const request = new Request(`https://erp.example${endpoint.path}`, {
+				method,
+				...(method === 'POST'
+					? { headers: { 'content-type': 'application/json' }, body: '{}' }
+					: {}),
+			});
+			const unauthenticated = await endpoint.handler(context(request));
+			expect(unauthenticated.status, `${method} ${endpoint.path}`).toBe(401);
+			const forbidden = await endpoint.handler(context(request, principal([])));
+			expect(forbidden.status, `${method} ${endpoint.path}`).toBe(403);
+		}
+	});
+
+	it('records the user actor for a protected lifecycle transition', async () => {
+		const actor = principal([
+			CATALOG_PERMISSIONS.read,
+			CATALOG_PERMISSIONS.manage,
+		]);
+		const runtime = catalogRuntime(await catalogTestProvider());
+		const routes = createCatalogRoutes(authRuntime(actor), runtime);
+		const created = await route(routes, '/api/catalog/items', 'POST').handler(
+			context(
+				mutation('/api/catalog/items', {
+					sku: 'A-1',
+					name: 'Alpha',
+					kind: 'product',
+					unit: 'each',
+					basePriceMinor: 100,
+					currency: 'EUR',
+				}),
+				actor,
+			),
+		);
+		const item = ((await created.json()) as { item: { id: string } }).item;
+		const archived = await route(
+			routes,
+			'/api/catalog/items/archive',
+			'POST',
+		).handler(
+			context(mutation('/api/catalog/items/archive', { id: item.id }), actor),
+		);
+		expect(archived.status).toBe(200);
+
+		const history = await route(
+			routes,
+			'/api/catalog/items/history',
+			'GET',
+		).handler(
+			context(
+				new Request(
+					`https://erp.example/api/catalog/items/history?recordId=${item.id}`,
+				),
+				actor,
+			),
+		);
+		expect(history.status).toBe(200);
+		expect(await history.json()).toMatchObject({
+			entries: [
+				{ action: 'archived', actor: { kind: 'user', id: 'account-a' } },
+				{ action: 'created', actor: { kind: 'user', id: 'account-a' } },
+			],
+		});
+	});
+
+	it('updates, restores, and permanently deletes only an archived item in the active tenant', async () => {
+		const actor = principal([
+			CATALOG_PERMISSIONS.read,
+			CATALOG_PERMISSIONS.manage,
+		]);
+		const runtime = catalogRuntime(await catalogTestProvider());
+		const routes = createCatalogRoutes(authRuntime(actor), runtime);
+		const created = await route(routes, '/api/catalog/items', 'POST').handler(
+			context(
+				mutation('/api/catalog/items', {
+					sku: 'LIFECYCLE-1',
+					name: 'Lifecycle item',
+					kind: 'product',
+					unit: 'each',
+					basePriceMinor: 100,
+					currency: 'EUR',
+				}),
+				actor,
+			),
+		);
+		const item = ((await created.json()) as { item: { id: string } }).item;
+
+		const updated = await route(
+			routes,
+			'/api/catalog/items/update',
+			'POST',
+		).handler(
+			context(
+				mutation('/api/catalog/items/update', {
+					id: item.id,
+					name: 'Lifecycle item revised',
+					kind: 'service',
+					unit: 'hour',
+					basePriceMinor: 250,
+					currency: 'PLN',
+				}),
+				actor,
+			),
+		);
+		expect(updated.status).toBe(200);
+		expect(await updated.json()).toMatchObject({
+			item: { id: item.id, name: 'Lifecycle item revised', currency: 'PLN' },
+		});
+
+		const activeDelete = await route(
+			routes,
+			'/api/catalog/items/delete',
+			'POST',
+		).handler(
+			context(mutation('/api/catalog/items/delete', { id: item.id }), actor),
+		);
+		expect(activeDelete.status).toBe(409);
+		expect(await activeDelete.json()).toMatchObject({
+			error: { code: 'CATALOG_ITEM_NOT_ARCHIVED' },
+		});
+
+		const foreignActor = principal(
+			[CATALOG_PERMISSIONS.read, CATALOG_PERMISSIONS.manage],
+			'tenant-b',
+		);
+		const foreignArchive = await route(
+			createCatalogRoutes(authRuntime(foreignActor), runtime),
+			'/api/catalog/items/archive',
+			'POST',
+		).handler(
+			context(
+				mutation('/api/catalog/items/archive', { id: item.id }),
+				foreignActor,
+			),
+		);
+		expect(foreignArchive.status).toBe(404);
+
+		for (const action of ['archive', 'restore', 'archive'] as const) {
+			const response = await route(
+				routes,
+				`/api/catalog/items/${action}`,
+				'POST',
+			).handler(
+				context(
+					mutation(`/api/catalog/items/${action}`, { id: item.id }),
+					actor,
+				),
+			);
+			expect(response.status, action).toBe(200);
+		}
+
+		const removed = await route(
+			routes,
+			'/api/catalog/items/delete',
+			'POST',
+		).handler(
+			context(mutation('/api/catalog/items/delete', { id: item.id }), actor),
+		);
+		expect(removed.status).toBe(200);
+		expect(await removed.json()).toEqual({ deleted: true });
+		await expect(
+			(await runtime.service()).get('tenant-a', item.id),
+		).resolves.toBeNull();
+	});
+
+	it('rejects a lifecycle mutation without a valid CSRF token', async () => {
+		const actor = principal([CATALOG_PERMISSIONS.manage]);
+		const runtime = catalogRuntime(await catalogTestProvider());
+		const item = await (
+			await runtime.service()
+		).create(
+			'tenant-a',
+			{
+				sku: 'A-1',
+				name: 'Alpha',
+				kind: 'product',
+				unit: 'each',
+				basePriceMinor: 100,
+				currency: 'EUR',
+			},
+			{ kind: 'user', id: 'account-a', label: 'Owner' },
+		);
+		const response = await route(
+			createCatalogRoutes(authRuntime(actor), runtime),
+			'/api/catalog/items/archive',
+			'POST',
+		).handler(
+			context(
+				mutation('/api/catalog/items/archive', { id: item.id }, 'bad'),
+				actor,
+			),
+		);
+		expect(response.status).toBe(403);
+		expect(
+			(await (await runtime.service()).get('tenant-a', item.id))?.status,
+		).toBe('active');
+	});
+});