@geekmidas/constructs 9.0.2 → 10.0.0-alpha.1

package/src/endpoints/__tests__/processAudits.spec.ts

@@ -1,631 +0,0 @@
-import type {
-	AuditableAction,
-	Auditor,
-	AuditRecord,
-	AuditStorage,
-} from '@geekmidas/audit';
-import { DefaultAuditor } from '@geekmidas/audit';
-import { ConsoleLogger } from '@geekmidas/logger/console';
-import type { Service, ServiceDiscovery } from '@geekmidas/services';
-import { describe, expect, it, vi } from 'vitest';
-import { z } from 'zod';
-import { EndpointBuilder } from '../EndpointBuilder';
-import {
-	createAuditContext,
-	executeWithAuditTransaction,
-	processEndpointAudits,
-} from '../processAudits';
-
-// Test audit actions
-type TestAuditAction =
-	| AuditableAction<'user.created', { userId: string; email: string }>
-	| AuditableAction<'user.updated', { userId: string; changes: string[] }>;
-
-// In-memory audit storage
-class InMemoryAuditStorage implements AuditStorage {
-	records: AuditRecord[] = [];
-	withTransactionCalled = false;
-	transactionDb: unknown = null;
-
-	async write(records: AuditRecord[]): Promise<void> {
-		this.records.push(...records);
-	}
-
-	async query(): Promise<AuditRecord[]> {
-		return this.records;
-	}
-
-	withTransaction<T>(
-		auditor: Auditor<any>,
-		fn: () => Promise<T>,
-		db?: unknown,
-	): Promise<T> {
-		this.withTransactionCalled = true;
-		this.transactionDb = db;
-		// Simulate transaction by setting a mock transaction
-		if ('setTransaction' in auditor) {
-			(auditor as any).setTransaction({ mockTrx: true });
-		}
-		return fn().then(async (result) => {
-			await auditor.flush();
-			return result;
-		});
-	}
-}
-
-// Storage without transaction support
-class SimpleAuditStorage implements AuditStorage {
-	records: AuditRecord[] = [];
-
-	async write(records: AuditRecord[]): Promise<void> {
-		this.records.push(...records);
-	}
-
-	async query(): Promise<AuditRecord[]> {
-		return this.records;
-	}
-}
-
-const createMockServiceDiscovery = (
-	storage: AuditStorage,
-): ServiceDiscovery<any, any> => {
-	return {
-		register: vi.fn().mockResolvedValue({ auditStorage: storage }),
-	} as unknown as ServiceDiscovery<any, any>;
-};
-
-const auditStorageService = {
-	serviceName: 'auditStorage' as const,
-	async register() {
-		return new InMemoryAuditStorage();
-	},
-} satisfies Service<'auditStorage', InMemoryAuditStorage>;
-
-const logger = new ConsoleLogger();
-
-describe('processAudits', () => {
-	describe('processEndpointAudits', () => {
-		it('should skip processing when no audits and no existing records', async () => {
-			const endpoint = new EndpointBuilder('/users', 'POST').handle(
-				async () => ({ id: '123' }),
-			);
-
-			const storage = new InMemoryAuditStorage();
-			const discovery = createMockServiceDiscovery(storage);
-
-			await processEndpointAudits(endpoint, { id: '123' }, discovery, logger, {
-				session: {},
-				header: () => undefined,
-				cookie: () => undefined,
-				services: {},
-			});
-
-			expect(storage.records).toHaveLength(0);
-		});
-
-		it('should warn when no storage service but has audits', async () => {
-			const outputSchema = z.object({ id: z.string(), email: z.string() });
-
-			const endpoint = new EndpointBuilder('/users', 'POST')
-				.output(outputSchema)
-				.audit<TestAuditAction>([
-					{
-						type: 'user.created',
-						payload: (r) => ({ userId: r.id, email: r.email }),
-					},
-				])
-				.handle(async () => ({ id: '123', email: 'test@test.com' }));
-
-			const warnSpy = vi.spyOn(logger, 'warn');
-			const discovery = createMockServiceDiscovery(new InMemoryAuditStorage());
-
-			await processEndpointAudits(
-				endpoint,
-				{ id: '123', email: 'test@test.com' },
-				discovery,
-				logger,
-				{
-					session: {},
-					header: () => undefined,
-					cookie: () => undefined,
-					services: {},
-				},
-			);
-
-			expect(warnSpy).toHaveBeenCalledWith(
-				'No auditor storage service available',
-			);
-		});
-
-		it('should process declarative audits', async () => {
-			const outputSchema = z.object({ id: z.string(), email: z.string() });
-			const storage = new InMemoryAuditStorage();
-
-			// Create a custom storage service that returns our shared storage
-			const customStorageService = {
-				serviceName: 'auditStorage' as const,
-				async register() {
-					return storage;
-				},
-			} satisfies Service<'auditStorage', InMemoryAuditStorage>;
-
-			const endpoint = new EndpointBuilder('/users', 'POST')
-				.output(outputSchema)
-				.auditor(customStorageService)
-				.audit<TestAuditAction>([
-					{
-						type: 'user.created',
-						payload: (r) => ({ userId: r.id, email: r.email }),
-					},
-				])
-				.handle(async () => ({ id: '123', email: 'test@test.com' }));
-
-			// Mock the service discovery to return our storage
-			const mockDiscovery = {
-				register: vi.fn().mockImplementation(async () => {
-					return { auditStorage: storage };
-				}),
-			} as unknown as ServiceDiscovery<any, any>;
-
-			await processEndpointAudits(
-				endpoint,
-				{ id: '123', email: 'test@test.com' },
-				mockDiscovery,
-				logger,
-				{
-					session: {},
-					header: () => undefined,
-					cookie: () => undefined,
-					services: {},
-				},
-			);
-
-			expect(storage.records).toHaveLength(1);
-			expect(storage.records[0].type).toBe('user.created');
-			expect(storage.records[0].payload).toEqual({
-				userId: '123',
-				email: 'test@test.com',
-			});
-		});
-
-		it('should skip audits when when condition returns false', async () => {
-			const outputSchema = z.object({
-				id: z.string(),
-				email: z.string(),
-				active: z.boolean(),
-			});
-			const storage = new InMemoryAuditStorage();
-
-			const endpoint = new EndpointBuilder('/users', 'POST')
-				.output(outputSchema)
-				.auditor(auditStorageService)
-				.audit<TestAuditAction>([
-					{
-						type: 'user.created',
-						payload: (r) => ({ userId: r.id, email: r.email }),
-						when: (r) => r.active,
-					},
-				])
-				.handle(async () => ({
-					id: '123',
-					email: 'test@test.com',
-					active: false,
-				}));
-
-			const discovery = createMockServiceDiscovery(storage);
-
-			await processEndpointAudits(
-				endpoint,
-				{ id: '123', email: 'test@test.com', active: false },
-				discovery,
-				logger,
-				{
-					session: {},
-					header: () => undefined,
-					cookie: () => undefined,
-					services: {},
-				},
-			);
-
-			expect(storage.records).toHaveLength(0);
-		});
-
-		it('should use existing auditor when provided', async () => {
-			const outputSchema = z.object({ id: z.string(), email: z.string() });
-			const storage = new InMemoryAuditStorage();
-
-			const endpoint = new EndpointBuilder('/users', 'POST')
-				.output(outputSchema)
-				.auditor(auditStorageService)
-				.audit<TestAuditAction>([
-					{
-						type: 'user.created',
-						payload: (r) => ({ userId: r.id, email: r.email }),
-					},
-				])
-				.handle(async () => ({ id: '123', email: 'test@test.com' }));
-
-			const discovery = createMockServiceDiscovery(storage);
-
-			// Create an existing auditor with some records already
-			const existingAuditor = new DefaultAuditor<TestAuditAction>({
-				actor: { id: 'existing-user', type: 'user' },
-				storage,
-			});
-			existingAuditor.audit('user.updated', {
-				userId: '456',
-				changes: ['name'],
-			});
-
-			await processEndpointAudits(
-				endpoint,
-				{ id: '123', email: 'test@test.com' },
-				discovery,
-				logger,
-				{
-					session: {},
-					header: () => undefined,
-					cookie: () => undefined,
-					services: {},
-				},
-				existingAuditor,
-			);
-
-			// Should have both the existing record and the new declarative one
-			expect(storage.records).toHaveLength(2);
-		});
-
-		it('should extract actor when configured', async () => {
-			const outputSchema = z.object({ id: z.string(), email: z.string() });
-			const storage = new InMemoryAuditStorage();
-
-			const endpoint = new EndpointBuilder('/users', 'POST')
-				.output(outputSchema)
-				.auditor(auditStorageService)
-				.actor(({ session }) => ({
-					id: (session as any).userId,
-					type: 'user',
-				}))
-				.audit<TestAuditAction>([
-					{
-						type: 'user.created',
-						payload: (r) => ({ userId: r.id, email: r.email }),
-					},
-				])
-				.handle(async () => ({ id: '123', email: 'test@test.com' }));
-
-			const discovery = createMockServiceDiscovery(storage);
-
-			await processEndpointAudits(
-				endpoint,
-				{ id: '123', email: 'test@test.com' },
-				discovery,
-				logger,
-				{
-					session: { userId: 'actor-123' },
-					header: () => undefined,
-					cookie: () => undefined,
-					services: {},
-				},
-			);
-
-			expect(storage.records).toHaveLength(1);
-			expect(storage.records[0].actor.id).toBe('actor-123');
-		});
-
-		it('should handle actor extraction errors gracefully', async () => {
-			const outputSchema = z.object({ id: z.string(), email: z.string() });
-			const storage = new InMemoryAuditStorage();
-
-			const endpoint = new EndpointBuilder('/users', 'POST')
-				.output(outputSchema)
-				.auditor(auditStorageService)
-				.actor(() => {
-					throw new Error('Actor extraction failed');
-				})
-				.audit<TestAuditAction>([
-					{
-						type: 'user.created',
-						payload: (r) => ({ userId: r.id, email: r.email }),
-					},
-				])
-				.handle(async () => ({ id: '123', email: 'test@test.com' }));
-
-			const discovery = createMockServiceDiscovery(storage);
-
-			// Should not throw, continue with system actor
-			await processEndpointAudits(
-				endpoint,
-				{ id: '123', email: 'test@test.com' },
-				discovery,
-				logger,
-				{
-					session: {},
-					header: () => undefined,
-					cookie: () => undefined,
-					services: {},
-				},
-			);
-
-			expect(storage.records).toHaveLength(1);
-			expect(storage.records[0].actor.id).toBe('system');
-		});
-
-		it('should include entityId and table when configured', async () => {
-			const outputSchema = z.object({ id: z.string(), email: z.string() });
-			const storage = new InMemoryAuditStorage();
-
-			const endpoint = new EndpointBuilder('/users', 'POST')
-				.output(outputSchema)
-				.auditor(auditStorageService)
-				.audit<TestAuditAction>([
-					{
-						type: 'user.created',
-						payload: (r) => ({ userId: r.id, email: r.email }),
-						entityId: (r) => r.id,
-						table: 'users',
-					},
-				])
-				.handle(async () => ({ id: '123', email: 'test@test.com' }));
-
-			const discovery = createMockServiceDiscovery(storage);
-
-			await processEndpointAudits(
-				endpoint,
-				{ id: '123', email: 'test@test.com' },
-				discovery,
-				logger,
-				{
-					session: {},
-					header: () => undefined,
-					cookie: () => undefined,
-					services: {},
-				},
-			);
-
-			expect(storage.records).toHaveLength(1);
-			expect(storage.records[0].entityId).toBe('123');
-			expect(storage.records[0].table).toBe('users');
-		});
-
-		it('should handle errors during processing', async () => {
-			const outputSchema = z.object({ id: z.string(), email: z.string() });
-
-			const endpoint = new EndpointBuilder('/users', 'POST')
-				.output(outputSchema)
-				.auditor(auditStorageService)
-				.audit<TestAuditAction>([
-					{
-						type: 'user.created',
-						payload: () => {
-							throw new Error('Payload extraction failed');
-						},
-					},
-				])
-				.handle(async () => ({ id: '123', email: 'test@test.com' }));
-
-			const discovery = createMockServiceDiscovery(new InMemoryAuditStorage());
-			const errorSpy = vi.spyOn(logger, 'error');
-
-			// Should not throw
-			await processEndpointAudits(
-				endpoint,
-				{ id: '123', email: 'test@test.com' },
-				discovery,
-				logger,
-				{
-					session: {},
-					header: () => undefined,
-					cookie: () => undefined,
-					services: {},
-				},
-			);
-
-			expect(errorSpy).toHaveBeenCalled();
-		});
-	});
-
-	describe('createAuditContext', () => {
-		it('should return undefined when no storage service', async () => {
-			const endpoint = new EndpointBuilder('/users', 'POST').handle(
-				async () => ({ id: '123' }),
-			);
-
-			const discovery = createMockServiceDiscovery(new InMemoryAuditStorage());
-
-			const context = await createAuditContext(endpoint, discovery, logger, {
-				session: {},
-				header: () => undefined,
-				cookie: () => undefined,
-				services: {},
-			});
-
-			expect(context).toBeUndefined();
-		});
-
-		it('should create audit context with storage and auditor', async () => {
-			const storage = new InMemoryAuditStorage();
-
-			const endpoint = new EndpointBuilder('/users', 'POST')
-				.auditor(auditStorageService)
-				.handle(async () => ({ id: '123' }));
-
-			const discovery = createMockServiceDiscovery(storage);
-
-			const context = await createAuditContext(endpoint, discovery, logger, {
-				session: {},
-				header: () => undefined,
-				cookie: () => undefined,
-				services: {},
-			});
-
-			expect(context).toBeDefined();
-			expect(context!.storage).toBe(storage);
-			expect(context!.auditor).toBeDefined();
-		});
-
-		it('should use custom actor extractor', async () => {
-			const storage = new InMemoryAuditStorage();
-
-			const endpoint = new EndpointBuilder('/users', 'POST')
-				.auditor(auditStorageService)
-				.actor(({ session }) => ({
-					id: (session as any).userId,
-					type: 'user',
-				}))
-				.handle(async () => ({ id: '123' }));
-
-			const discovery = createMockServiceDiscovery(storage);
-
-			const context = await createAuditContext(endpoint, discovery, logger, {
-				session: { userId: 'actor-456' },
-				header: () => undefined,
-				cookie: () => undefined,
-				services: {},
-			});
-
-			expect(context).toBeDefined();
-
-			// Record an audit and check the actor
-			context!.auditor.audit('user.created' as any, {
-				userId: '123',
-				email: 'test@test.com',
-			});
-			await context!.auditor.flush();
-
-			expect(storage.records[0].actor.id).toBe('actor-456');
-		});
-
-		it('should use system actor when extraction fails', async () => {
-			const storage = new InMemoryAuditStorage();
-
-			const endpoint = new EndpointBuilder('/users', 'POST')
-				.auditor(auditStorageService)
-				.actor(() => {
-					throw new Error('Actor extraction failed');
-				})
-				.handle(async () => ({ id: '123' }));
-
-			const discovery = createMockServiceDiscovery(storage);
-
-			const context = await createAuditContext(endpoint, discovery, logger, {
-				session: {},
-				header: () => undefined,
-				cookie: () => undefined,
-				services: {},
-			});
-
-			expect(context).toBeDefined();
-
-			context!.auditor.audit('user.created' as any, {
-				userId: '123',
-				email: 'test@test.com',
-			});
-			await context!.auditor.flush();
-
-			expect(storage.records[0].actor.id).toBe('system');
-		});
-	});
-
-	describe('executeWithAuditTransaction', () => {
-		it('should run handler without context', async () => {
-			const handlerFn = vi.fn().mockResolvedValue({ id: '123' });
-
-			const result = await executeWithAuditTransaction(undefined, handlerFn);
-
-			expect(result).toEqual({ id: '123' });
-			expect(handlerFn).toHaveBeenCalledWith(undefined);
-		});
-
-		it('should use transaction when storage supports it', async () => {
-			const storage = new InMemoryAuditStorage();
-			const auditor = new DefaultAuditor<TestAuditAction>({
-				actor: { id: 'test', type: 'user' },
-				storage,
-			});
-
-			const context = { auditor, storage };
-			const handlerFn = vi.fn().mockResolvedValue({ id: '123' });
-
-			const result = await executeWithAuditTransaction(context, handlerFn);
-
-			expect(result).toEqual({ id: '123' });
-			expect(storage.withTransactionCalled).toBe(true);
-		});
-
-		it('should pass db option to storage transaction', async () => {
-			const storage = new InMemoryAuditStorage();
-			const auditor = new DefaultAuditor<TestAuditAction>({
-				actor: { id: 'test', type: 'user' },
-				storage,
-			});
-
-			const context = { auditor, storage };
-			const mockDb = { isMockDb: true };
-
-			await executeWithAuditTransaction(
-				context,
-				async () => ({ id: '123' }),
-				undefined,
-				{ db: mockDb },
-			);
-
-			expect(storage.transactionDb).toBe(mockDb);
-		});
-
-		it('should call onComplete callback', async () => {
-			const storage = new InMemoryAuditStorage();
-			const auditor = new DefaultAuditor<TestAuditAction>({
-				actor: { id: 'test', type: 'user' },
-				storage,
-			});
-
-			const context = { auditor, storage };
-			const onComplete = vi.fn();
-
-			const _result = await executeWithAuditTransaction(
-				context,
-				async () => ({ id: '123' }),
-				onComplete,
-			);
-
-			expect(onComplete).toHaveBeenCalledWith({ id: '123' }, auditor);
-		});
-
-		it('should flush audits when storage has no transaction support', async () => {
-			const storage = new SimpleAuditStorage();
-			const auditor = new DefaultAuditor<TestAuditAction>({
-				actor: { id: 'test', type: 'user' },
-				storage,
-			});
-
-			const context = { auditor, storage };
-
-			await executeWithAuditTransaction(context, async (a) => {
-				a!.audit('user.created', { userId: '123', email: 'test@test.com' });
-				return { id: '123' };
-			});
-
-			expect(storage.records).toHaveLength(1);
-		});
-
-		it('should call onComplete even without transaction support', async () => {
-			const storage = new SimpleAuditStorage();
-			const auditor = new DefaultAuditor<TestAuditAction>({
-				actor: { id: 'test', type: 'user' },
-				storage,
-			});
-
-			const context = { auditor, storage };
-			const onComplete = vi.fn();
-
-			await executeWithAuditTransaction(
-				context,
-				async () => ({ id: '123' }),
-				onComplete,
-			);
-
-			expect(onComplete).toHaveBeenCalled();
-		});
-	});
-});

package/src/endpoints/audit.ts

@@ -1,87 +0,0 @@
-import type {
-	AuditActor,
-	AuditableAction,
-	AuditStorage,
-	ExtractAuditPayload,
-	ExtractAuditType,
-} from '@geekmidas/audit';
-import type { Logger } from '@geekmidas/logger';
-import type { InferStandardSchema } from '@geekmidas/schema';
-import type { Service, ServiceRecord } from '@geekmidas/services';
-import type { StandardSchemaV1 } from '@standard-schema/spec';
-import type { CookieFn, HeaderFn } from './Endpoint';
-
-/**
- * Defines how to map an endpoint response to an audit record.
- * Similar to MappedEvent for events.
- *
- * @template TAuditAction - Union of all allowed audit action types
- * @template TOutput - The output schema of the endpoint
- */
-export interface MappedAudit<
-	TAuditAction extends AuditableAction<string, unknown>,
-	TOutput extends StandardSchemaV1 | undefined,
-	TType extends ExtractAuditType<TAuditAction> = ExtractAuditType<TAuditAction>,
-> {
-	/** The audit type (must be a valid type from TAuditAction) */
-	type: TType;
-	/** Function to extract payload from the endpoint response */
-	payload: (
-		response: TOutput extends StandardSchemaV1
-			? InferStandardSchema<TOutput>
-			: unknown,
-	) => ExtractAuditPayload<TAuditAction, TType>;
-	/** Optional condition to determine if audit should be recorded */
-	when?: (
-		response: TOutput extends StandardSchemaV1
-			? InferStandardSchema<TOutput>
-			: unknown,
-	) => boolean;
-	/** Optional function to extract entity ID for easier querying */
-	entityId?: (
-		response: TOutput extends StandardSchemaV1
-			? InferStandardSchema<TOutput>
-			: unknown,
-	) => string | Record<string, unknown>;
-	/** Optional table name for the audit record */
-	table?: string;
-}
-
-/**
- * Function type for extracting actor information from request context.
- *
- * @template TServices - Available service dependencies
- * @template TSession - Session data type
- * @template TLogger - Logger type
- */
-export type ActorExtractor<
-	TServices extends Service[] = [],
-	TSession = unknown,
-	TLogger extends Logger = Logger,
-> = (ctx: {
-	services: ServiceRecord<TServices>;
-	session: TSession;
-	header: HeaderFn;
-	cookie: CookieFn;
-	logger: TLogger;
-}) => AuditActor | Promise<AuditActor>;
-
-/**
- * Configuration for the auditor on an endpoint.
- */
-export interface EndpointAuditorConfig<
-	TAuditStorage extends AuditStorage,
-	TAuditStorageServiceName extends string,
-	TServices extends Service[],
-	TSession,
-	TLogger extends Logger,
-	TAuditAction extends AuditableAction<string, unknown>,
-	TOutput extends StandardSchemaV1 | undefined,
-> {
-	/** The audit storage service */
-	storageService: Service<TAuditStorageServiceName, TAuditStorage>;
-	/** Optional actor extractor function */
-	actorExtractor?: ActorExtractor<TServices, TSession, TLogger>;
-	/** Declarative audit definitions */
-	audits: MappedAudit<TAuditAction, TOutput>[];
-}