@buenojs/bueno 0.8.4 → 0.8.6

package/src/observability/types.ts

@@ -0,0 +1,196 @@
+/**
+ * Observability Types
+ *
+ * Core interfaces for the error tracking and observability integration layer.
+ * Implement ErrorReporter to integrate with Sentry, Bugsnag, Datadog, etc.
+ */
+
+// ============= Breadcrumbs =============
+
+/**
+ * A single breadcrumb entry recording an event that occurred before an error
+ */
+export interface BreadcrumbEntry {
+	/** When this breadcrumb was recorded */
+	timestamp: Date;
+	/** Category of event */
+	type: "http" | "log" | "navigation" | "custom";
+	/** Severity level */
+	level: "debug" | "info" | "warning" | "error";
+	/** Human-readable description of the event */
+	message: string;
+	/** Optional structured data for context */
+	data?: Record<string, unknown>;
+}
+
+// ============= Error Event =============
+
+/**
+ * Request metadata captured at error time
+ */
+export interface ErrorRequestContext {
+	/** HTTP method */
+	method: string;
+	/** Request path */
+	path: string;
+	/** Relevant request headers (sanitized) */
+	headers: Record<string, string>;
+	/** Client IP address */
+	ip: string;
+	/** User-Agent header if present */
+	userAgent?: string;
+}
+
+/**
+ * User identity snapshot (sourced from context.get('user'))
+ */
+export interface ErrorUserContext {
+	id?: string | number;
+	email?: string;
+	[key: string]: unknown;
+}
+
+/**
+ * A captured error event with full context, ready for the reporter
+ */
+export interface ErrorEvent {
+	/** Unique ID for this error event (for deduplication) */
+	id: string;
+	/** When the error occurred */
+	timestamp: Date;
+	/** The original Error object */
+	error: Error;
+	/** Severity level */
+	level: "fatal" | "error" | "warning";
+	/** HTTP request context (undefined for non-HTTP errors) */
+	request?: ErrorRequestContext;
+	/** W3C trace ID (from traceparent header or generated) */
+	traceId?: string;
+	/** W3C span ID */
+	spanId?: string;
+	/** Authenticated user at time of error */
+	user?: ErrorUserContext;
+	/** Recent events leading up to this error */
+	breadcrumbs: BreadcrumbEntry[];
+	/** Custom tags for categorization */
+	tags?: Record<string, string>;
+	/** Any additional context */
+	extra?: Record<string, unknown>;
+}
+
+/**
+ * A captured message event (non-error) for the reporter
+ */
+export interface MessageEvent {
+	/** Unique ID */
+	id: string;
+	/** When the message was captured */
+	timestamp: Date;
+	/** The message text */
+	message: string;
+	/** Severity */
+	level: "debug" | "info" | "warning" | "error";
+	/** Optional extra context */
+	extra?: Record<string, unknown>;
+}
+
+// ============= ErrorReporter Interface =============
+
+/**
+ * Implement this interface to report errors to your platform (Sentry, Bugsnag, etc.).
+ *
+ * @example
+ * ```typescript
+ * class SentryReporter implements ErrorReporter {
+ *   captureError(event: ErrorEvent) {
+ *     Sentry.withScope(scope => {
+ *       if (event.user) scope.setUser(event.user);
+ *       if (event.traceId) scope.setTag('traceId', event.traceId);
+ *       Sentry.captureException(event.error);
+ *     });
+ *   }
+ *   async flush() { await Sentry.flush(2000); }
+ * }
+ * ```
+ */
+export interface ErrorReporter {
+	/**
+	 * Report an error event. Called asynchronously (non-blocking).
+	 * Throw errors only if truly unrecoverable — they are caught and logged.
+	 */
+	captureError(event: ErrorEvent): void | Promise<void>;
+
+	/**
+	 * Report a non-error message. Optional.
+	 */
+	captureMessage?(event: MessageEvent): void | Promise<void>;
+
+	/**
+	 * Flush pending events. Called on application shutdown.
+	 * Use this to ensure all buffered events are sent before process exit.
+	 */
+	flush?(): Promise<void>;
+}
+
+// ============= Module Options =============
+
+/**
+ * Options for ObservabilityModule.forRoot()
+ */
+export interface ObservabilityOptions {
+	/**
+	 * The reporter that receives all captured error events.
+	 * Required — without a reporter, no events are sent anywhere.
+	 */
+	reporter: ErrorReporter;
+
+	/**
+	 * Maximum number of breadcrumbs to retain in the ring buffer.
+	 * Older breadcrumbs are evicted when the buffer is full.
+	 * @default 20
+	 */
+	breadcrumbsSize?: number;
+
+	/**
+	 * Error classes to suppress — events with these types are not reported.
+	 * Useful for suppressing expected errors like 404s or 401s.
+	 *
+	 * @example ignoreErrors: [NotFoundError, UnauthorizedError]
+	 */
+	ignoreErrors?: Array<new (...args: unknown[]) => Error>;
+
+	/**
+	 * HTTP status codes to suppress.
+	 * Errors whose statusCode property matches are not reported.
+	 * @example ignoreStatusCodes: [404, 401]
+	 */
+	ignoreStatusCodes?: number[];
+
+	/**
+	 * Custom tags attached to every error event.
+	 * @example tags: { environment: 'production', version: '1.2.3' }
+	 */
+	tags?: Record<string, string>;
+
+	/**
+	 * Also capture unhandled promise rejections and uncaught exceptions
+	 * at the process level (outside the HTTP request pipeline).
+	 * @default false
+	 */
+	captureUnhandled?: boolean;
+}
+
+// ============= Config =============
+
+/**
+ * Configuration values that can be set via environment variables.
+ * These are applied as defaults; ObservabilityOptions take precedence.
+ */
+export interface ObservabilityConfig {
+	/** Enable/disable the observability system */
+	enabled?: boolean;
+	/** Maximum breadcrumb ring buffer size */
+	breadcrumbsSize?: number;
+	/** HTTP status codes to ignore (comma-separated in env) */
+	ignoreStatusCodes?: number[];
+}

package/src/openapi/__tests__/decorators.test.ts

@@ -0,0 +1,335 @@
+import { describe, test, expect } from 'bun:test';
+import {
+	ApiTags,
+	ApiBearerAuth,
+	ApiBasicAuth,
+	ApiApiKey,
+	ApiExcludeController,
+	ApiOperation,
+	ApiResponse,
+	ApiParam,
+	ApiQuery,
+	ApiHeader,
+	ApiBody,
+	ApiExcludeEndpoint,
+	ApiProperty,
+	ApiPropertyOptional,
+} from '../decorators';
+import { getApiMetadata, getApiMethodMetadata, getApiPropertyMetadata } from '../metadata';
+
+// ============= Fixtures =============
+
+class TestDto {}
+
+// ============= Class-Level Decorators =============
+
+describe('Class-Level Decorators', () => {
+	describe('@ApiTags', () => {
+		test('should store tags on class constructor', () => {
+			@ApiTags('users', 'admin')
+			class UserController {}
+
+			const tags = getApiMetadata<string[]>(UserController, 'api:tags');
+			expect(tags).toEqual(['users', 'admin']);
+		});
+
+		test('should merge multiple @ApiTags decorators', () => {
+			@ApiTags('users')
+			@ApiTags('admin')
+			class UserController {}
+
+			const tags = getApiMetadata<string[]>(UserController, 'api:tags');
+			expect(tags?.includes('users')).toBe(true);
+			expect(tags?.includes('admin')).toBe(true);
+		});
+	});
+
+	describe('@ApiBearerAuth', () => {
+		test('should store bearer auth security on class', () => {
+			@ApiBearerAuth()
+			class ApiController {}
+
+			const security = getApiMetadata<Record<string, string[]>[]>(ApiController, 'api:security');
+			expect(security).toBeDefined();
+			expect(security?.length).toBeGreaterThan(0);
+			expect(security?.[0]).toHaveProperty('bearer');
+		});
+
+		test('should use custom bearer name', () => {
+			@ApiBearerAuth('jwt')
+			class ApiController {}
+
+			const security = getApiMetadata<Record<string, string[]>[]>(ApiController, 'api:security');
+			expect(security?.[0]).toHaveProperty('jwt');
+		});
+	});
+
+	describe('@ApiBasicAuth', () => {
+		test('should store basic auth security on class', () => {
+			@ApiBasicAuth()
+			class ApiController {}
+
+			const security = getApiMetadata<Record<string, string[]>[]>(ApiController, 'api:security');
+			expect(security).toBeDefined();
+			expect(security?.[0]).toHaveProperty('basic');
+		});
+	});
+
+	describe('@ApiApiKey', () => {
+		test('should store API key security on class', () => {
+			@ApiApiKey({ in: 'header', name: 'X-API-Key' })
+			class ApiController {}
+
+			const security = getApiMetadata<Record<string, string[]>[]>(ApiController, 'api:security');
+			expect(security).toBeDefined();
+			expect(security?.[0]).toHaveProperty('api_key');
+		});
+	});
+
+	describe('@ApiExcludeController', () => {
+		test('should mark controller as excluded', () => {
+			@ApiExcludeController()
+			class HiddenController {}
+
+			const excluded = getApiMetadata<boolean>(HiddenController, 'api:exclude');
+			expect(excluded).toBe(true);
+		});
+	});
+});
+
+// ============= Method-Level Decorators =============
+// Note: metadata is stored as 'api:<key>:<methodName>' on the prototype
+
+describe('Method-Level Decorators', () => {
+	describe('@ApiOperation', () => {
+		test('should store operation metadata keyed by method name', () => {
+			class UserController {
+				@ApiOperation({ summary: 'Get all users', description: 'Retrieve a list of users' })
+				getAll() {}
+			}
+
+			const meta = getApiMethodMetadata<any>(UserController.prototype, 'api:operation:getAll');
+			expect(meta).toBeDefined();
+			expect(meta?.summary).toBe('Get all users');
+			expect(meta?.description).toBe('Retrieve a list of users');
+		});
+
+		test('should store deprecated flag', () => {
+			class UserController {
+				@ApiOperation({ summary: 'Old endpoint', deprecated: true })
+				oldMethod() {}
+			}
+
+			const meta = getApiMethodMetadata<any>(UserController.prototype, 'api:operation:oldMethod');
+			expect(meta?.deprecated).toBe(true);
+		});
+	});
+
+	describe('@ApiResponse', () => {
+		test('should store single response keyed by method name', () => {
+			class UserController {
+				@ApiResponse({ status: 200, description: 'Success' })
+				getUser() {}
+			}
+
+			const responses = getApiMethodMetadata<any[]>(UserController.prototype, 'api:responses:getUser');
+			expect(responses).toBeDefined();
+			expect(responses?.length).toBe(1);
+			expect(responses?.[0].status).toBe(200);
+			expect(responses?.[0].description).toBe('Success');
+		});
+
+		test('should accumulate multiple @ApiResponse decorators', () => {
+			class UserController {
+				@ApiResponse({ status: 200, description: 'Success' })
+				@ApiResponse({ status: 404, description: 'Not found' })
+				getUser() {}
+			}
+
+			const responses = getApiMethodMetadata<any[]>(UserController.prototype, 'api:responses:getUser');
+			expect(responses?.length).toBe(2);
+		});
+	});
+
+	describe('@ApiParam', () => {
+		test('should store path parameter keyed by method name', () => {
+			class UserController {
+				@ApiParam({ name: 'id', type: 'string', description: 'User ID' })
+				getUser() {}
+			}
+
+			const params = getApiMethodMetadata<any[]>(UserController.prototype, 'api:params:getUser');
+			expect(params).toBeDefined();
+			expect(params?.length).toBe(1);
+			expect(params?.[0].name).toBe('id');
+			expect(params?.[0].type).toBe('string');
+		});
+
+		test('should accumulate multiple @ApiParam decorators', () => {
+			class UserController {
+				@ApiParam({ name: 'userId', type: 'string' })
+				@ApiParam({ name: 'postId', type: 'string' })
+				getPost() {}
+			}
+
+			const params = getApiMethodMetadata<any[]>(UserController.prototype, 'api:params:getPost');
+			expect(params?.length).toBe(2);
+		});
+	});
+
+	describe('@ApiQuery', () => {
+		test('should store query parameter keyed by method name', () => {
+			class UserController {
+				@ApiQuery({ name: 'page', type: 'number', required: false })
+				getUsers() {}
+			}
+
+			const query = getApiMethodMetadata<any[]>(UserController.prototype, 'api:query:getUsers');
+			expect(query).toBeDefined();
+			expect(query?.length).toBe(1);
+			expect(query?.[0].name).toBe('page');
+			expect(query?.[0].required).toBe(false);
+		});
+	});
+
+	describe('@ApiHeader', () => {
+		test('should store header keyed by method name', () => {
+			class UserController {
+				@ApiHeader({ name: 'X-Request-ID', description: 'Request ID', required: true })
+				create() {}
+			}
+
+			const headers = getApiMethodMetadata<any[]>(UserController.prototype, 'api:headers:create');
+			expect(headers).toBeDefined();
+			expect(headers?.length).toBe(1);
+			expect(headers?.[0].name).toBe('X-Request-ID');
+			expect(headers?.[0].required).toBe(true);
+		});
+	});
+
+	describe('@ApiBody', () => {
+		test('should store request body keyed by method name', () => {
+			class UserController {
+				@ApiBody({ type: TestDto, description: 'User data' })
+				create() {}
+			}
+
+			const body = getApiMethodMetadata<any>(UserController.prototype, 'api:body:create');
+			expect(body).toBeDefined();
+			expect(body?.type).toBe(TestDto);
+			expect(body?.description).toBe('User data');
+		});
+	});
+
+	describe('@ApiExcludeEndpoint', () => {
+		test('should mark endpoint as excluded keyed by method name', () => {
+			class UserController {
+				@ApiExcludeEndpoint()
+				internalMethod() {}
+			}
+
+			const excluded = getApiMethodMetadata<boolean>(
+				UserController.prototype,
+				'api:exclude:internalMethod',
+			);
+			expect(excluded).toBe(true);
+		});
+	});
+});
+
+// ============= Property-Level Decorators (for DTOs) =============
+
+describe('Property-Level Decorators (DTOs)', () => {
+	describe('@ApiProperty', () => {
+		test('should store property with required=true by default', () => {
+			class UserDto {
+				@ApiProperty({ description: 'User email' })
+				email!: string;
+			}
+
+			const meta = getApiPropertyMetadata<any>(UserDto.prototype, 'email');
+			expect(meta?.description).toBe('User email');
+			expect(meta?.required).toBe(true);
+		});
+
+		test('should store type information', () => {
+			class UserDto {
+				@ApiProperty({ type: 'string' })
+				name!: string;
+			}
+
+			const meta = getApiPropertyMetadata<any>(UserDto.prototype, 'name');
+			expect(meta?.type).toBe('string');
+		});
+
+		test('should store validation constraints', () => {
+			class UserDto {
+				@ApiProperty({ minLength: 2, maxLength: 100, pattern: '^[a-zA-Z]+$' })
+				name!: string;
+			}
+
+			const meta = getApiPropertyMetadata<any>(UserDto.prototype, 'name');
+			expect(meta?.minLength).toBe(2);
+			expect(meta?.maxLength).toBe(100);
+			expect(meta?.pattern).toBe('^[a-zA-Z]+$');
+		});
+
+		test('should store numeric constraints', () => {
+			class UserDto {
+				@ApiProperty({ minimum: 0, maximum: 150 })
+				age!: number;
+			}
+
+			const meta = getApiPropertyMetadata<any>(UserDto.prototype, 'age');
+			expect(meta?.minimum).toBe(0);
+			expect(meta?.maximum).toBe(150);
+		});
+
+		test('should store enum values', () => {
+			class UserDto {
+				@ApiProperty({ enum: ['active', 'inactive', 'pending'] })
+				status!: string;
+			}
+
+			const meta = getApiPropertyMetadata<any>(UserDto.prototype, 'status');
+			expect(meta?.enum).toEqual(['active', 'inactive', 'pending']);
+		});
+
+		test('should store examples and defaults', () => {
+			class UserDto {
+				@ApiProperty({ example: 'john@example.com', default: 'user@example.com' })
+				email!: string;
+			}
+
+			const meta = getApiPropertyMetadata<any>(UserDto.prototype, 'email');
+			expect(meta?.example).toBe('john@example.com');
+			expect(meta?.default).toBe('user@example.com');
+		});
+	});
+
+	describe('@ApiPropertyOptional', () => {
+		test('should store property with required=false', () => {
+			class UserDto {
+				@ApiPropertyOptional({ description: 'Optional middle name' })
+				middleName?: string;
+			}
+
+			const meta = getApiPropertyMetadata<any>(UserDto.prototype, 'middleName');
+			expect(meta?.description).toBe('Optional middle name');
+			expect(meta?.required).toBe(false);
+		});
+
+		test('should accept same options as @ApiProperty except required', () => {
+			class UserDto {
+				@ApiPropertyOptional({ minLength: 1, maxLength: 50, example: 'Smith' })
+				suffix?: string;
+			}
+
+			const meta = getApiPropertyMetadata<any>(UserDto.prototype, 'suffix');
+			expect(meta?.minLength).toBe(1);
+			expect(meta?.maxLength).toBe(50);
+			expect(meta?.example).toBe('Smith');
+			expect(meta?.required).toBe(false);
+		});
+	});
+});