@buenojs/bueno 0.8.6 → 0.8.8

package/dist/observability/types.d.ts

@@ -0,0 +1,172 @@
+/**
+ * Observability Types
+ *
+ * Core interfaces for the error tracking and observability integration layer.
+ * Implement ErrorReporter to integrate with Sentry, Bugsnag, Datadog, etc.
+ */
+/**
+ * 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>;
+}
+/**
+ * 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>;
+}
+/**
+ * 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>;
+}
+/**
+ * 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;
+}
+/**
+ * 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[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/observability/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/observability/types.ts"],"names":[],"mappings":"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"}

package/dist/openapi/__tests__/decorators.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=decorators.test.d.ts.map

package/dist/openapi/__tests__/decorators.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decorators.test.d.ts","sourceRoot":"","sources":["../../../src/openapi/__tests__/decorators.test.ts"],"names":[],"mappings":""}

package/dist/openapi/__tests__/document-builder.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=document-builder.test.d.ts.map

package/dist/openapi/__tests__/document-builder.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"document-builder.test.d.ts","sourceRoot":"","sources":["../../../src/openapi/__tests__/document-builder.test.ts"],"names":[],"mappings":""}

package/dist/openapi/__tests__/route-scanner.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=route-scanner.test.d.ts.map

package/dist/openapi/__tests__/route-scanner.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"route-scanner.test.d.ts","sourceRoot":"","sources":["../../../src/openapi/__tests__/route-scanner.test.ts"],"names":[],"mappings":""}

package/dist/openapi/__tests__/schema-generator.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=schema-generator.test.d.ts.map

package/dist/openapi/__tests__/schema-generator.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-generator.test.d.ts","sourceRoot":"","sources":["../../../src/openapi/__tests__/schema-generator.test.ts"],"names":[],"mappings":""}

package/dist/openapi/decorators.d.ts

@@ -0,0 +1,173 @@
+/**
+ * OpenAPI Decorators
+ *
+ * Decorators for documenting controllers, methods, parameters, and DTOs with OpenAPI metadata.
+ */
+import type { ApiBodyOptions, ApiHeaderOptions, ApiKeySecurityOptions, ApiOperationOptions, ApiParamOptions, ApiPropertyOptions, ApiQueryOptions, ApiResponseOptions, SecuritySchemeOptions } from './types';
+/**
+ * Mark one or more tags that apply to all operations in this controller
+ *
+ * @example
+ * ```typescript
+ * @Controller('/users')
+ * @ApiTags('users', 'accounts')
+ * class UserController { ... }
+ * ```
+ */
+export declare function ApiTags(...tags: string[]): ClassDecorator;
+/**
+ * Mark this controller with Bearer token authentication
+ *
+ * @example
+ * ```typescript
+ * @Controller('/api')
+ * @ApiBearerAuth()
+ * class ApiController { ... }
+ * ```
+ */
+export declare function ApiBearerAuth(name?: string, options?: SecuritySchemeOptions): ClassDecorator | MethodDecorator;
+/**
+ * Mark this controller with Basic authentication
+ *
+ * @example
+ * ```typescript
+ * @Controller('/api')
+ * @ApiBasicAuth()
+ * class ApiController { ... }
+ * ```
+ */
+export declare function ApiBasicAuth(name?: string): ClassDecorator | MethodDecorator;
+/**
+ * Mark this controller with API Key authentication
+ *
+ * @example
+ * ```typescript
+ * @Controller('/api')
+ * @ApiApiKey({ in: 'header', name: 'X-API-Key' })
+ * class ApiController { ... }
+ * ```
+ */
+export declare function ApiApiKey(options: ApiKeySecurityOptions, name?: string): ClassDecorator | MethodDecorator;
+/**
+ * Exclude this entire controller from OpenAPI documentation
+ *
+ * @example
+ * ```typescript
+ * @Controller('/internal')
+ * @ApiExcludeController()
+ * class InternalController { ... }
+ * ```
+ */
+export declare function ApiExcludeController(): ClassDecorator;
+/**
+ * Document the operation (HTTP method) with summary, description, and other metadata
+ *
+ * @example
+ * ```typescript
+ * @Get('/:id')
+ * @ApiOperation({ summary: 'Get user by ID', description: 'Retrieve a single user' })
+ * getUser(@Param('id') id: string) { ... }
+ * ```
+ */
+export declare function ApiOperation(options: ApiOperationOptions): MethodDecorator;
+/**
+ * Document an HTTP response from this operation
+ * Can be used multiple times for different status codes
+ *
+ * @example
+ * ```typescript
+ * @ApiResponse({ status: 200, description: 'Success', type: UserDto })
+ * @ApiResponse({ status: 404, description: 'Not found' })
+ * getUser() { ... }
+ * ```
+ */
+export declare function ApiResponse(options: ApiResponseOptions): MethodDecorator;
+/**
+ * Document a path parameter
+ * Can be used multiple times for different parameters
+ *
+ * @example
+ * ```typescript
+ * @Get('/:userId/posts/:postId')
+ * @ApiParam({ name: 'userId', type: 'string', description: 'User ID' })
+ * @ApiParam({ name: 'postId', type: 'string', description: 'Post ID' })
+ * getPost(@Param('userId') userId: string, @Param('postId') postId: string) { ... }
+ * ```
+ */
+export declare function ApiParam(options: ApiParamOptions): MethodDecorator;
+/**
+ * Document a query parameter
+ * Can be used multiple times for different parameters
+ *
+ * @example
+ * ```typescript
+ * @Get()
+ * @ApiQuery({ name: 'page', type: 'number', description: 'Page number', required: false })
+ * @ApiQuery({ name: 'limit', type: 'number', description: 'Items per page', required: false })
+ * getUsers(@Query('page') page?: number, @Query('limit') limit?: number) { ... }
+ * ```
+ */
+export declare function ApiQuery(options: ApiQueryOptions): MethodDecorator;
+/**
+ * Document an HTTP header
+ * Can be used multiple times for different headers
+ *
+ * @example
+ * ```typescript
+ * @Post()
+ * @ApiHeader({ name: 'X-Request-ID', description: 'Request ID', required: true })
+ * create() { ... }
+ * ```
+ */
+export declare function ApiHeader(options: ApiHeaderOptions): MethodDecorator;
+/**
+ * Document the request body
+ *
+ * @example
+ * ```typescript
+ * @Post()
+ * @ApiBody({ type: CreateUserDto, description: 'User data to create' })
+ * create(@Body() dto: CreateUserDto) { ... }
+ * ```
+ */
+export declare function ApiBody(options: ApiBodyOptions): MethodDecorator;
+/**
+ * Exclude this endpoint from OpenAPI documentation
+ *
+ * @example
+ * ```typescript
+ * @Get()
+ * @ApiExcludeEndpoint()
+ * internalOnly() { ... }
+ * ```
+ */
+export declare function ApiExcludeEndpoint(): MethodDecorator;
+/**
+ * Document a DTO property with type, description, validation rules, etc.
+ *
+ * @example
+ * ```typescript
+ * class CreateUserDto {
+ *   @ApiProperty({ description: 'Email address', example: 'user@example.com' })
+ *   email: string;
+ *
+ *   @ApiProperty({ minLength: 2, maxLength: 50, description: 'Full name' })
+ *   name: string;
+ * }
+ * ```
+ */
+export declare function ApiProperty(options?: ApiPropertyOptions): PropertyDecorator;
+/**
+ * Document an optional DTO property
+ * Equivalent to ApiProperty with required: false
+ *
+ * @example
+ * ```typescript
+ * class UserFilterDto {
+ *   @ApiPropertyOptional({ description: 'Filter by name', example: 'John' })
+ *   name?: string;
+ * }
+ * ```
+ */
+export declare function ApiPropertyOptional(options?: Omit<ApiPropertyOptions, 'required'>): PropertyDecorator;
+//# sourceMappingURL=decorators.d.ts.map

package/dist/openapi/decorators.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decorators.d.ts","sourceRoot":"","sources":["../../src/openapi/decorators.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EACX,cAAc,EACd,gBAAgB,EAChB,qBAAqB,EACrB,mBAAmB,EACnB,eAAe,EACf,kBAAkB,EAClB,eAAe,EACf,kBAAkB,EAGlB,qBAAqB,EACrB,MAAM,SAAS,CAAC;AAYjB;;;;;;;;;GASG;AACH,wBAAgB,OAAO,CAAC,GAAG,IAAI,EAAE,MAAM,EAAE,GAAG,cAAc,CAOzD;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,IAAI,SAAW,EAAE,OAAO,CAAC,EAAE,qBAAqB,GAAG,cAAc,GAAG,eAAe,CAiBhH;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,IAAI,SAAU,GAAG,cAAc,GAAG,eAAe,CAiB7E;AAED;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,qBAAqB,EAAE,IAAI,SAAY,GAAG,cAAc,GAAG,eAAe,CAmB5G;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,IAAI,cAAc,CAKrD;AAID;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,eAAe,CAI1E;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,eAAe,CAOxE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,eAAe,CAOlE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,eAAe,CAOlE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,gBAAgB,GAAG,eAAe,CAOpE;AAED;;;;;;;;;GASG;AACH,wBAAgB,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,eAAe,CAIhE;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,IAAI,eAAe,CAIpD;AAID;;;;;;;;;;;;;GAaG;AACH,wBAAgB,WAAW,CAAC,OAAO,CAAC,EAAE,kBAAkB,GAAG,iBAAiB,CAK3E;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,CAAC,EAAE,IAAI,CAAC,kBAAkB,EAAE,UAAU,CAAC,GAAG,iBAAiB,CAKrG"}

package/dist/openapi/document-builder.d.ts

@@ -0,0 +1,82 @@
+/**
+ * OpenAPI Document Builder
+ *
+ * Fluent API for building OpenAPI 3.1 documents with configuration for
+ * servers, security schemes, tags, and other top-level metadata.
+ */
+import type { ApiKeySecurityOptions, OpenAPIDocument, SecuritySchemeOptions } from './types';
+/**
+ * DocumentBuilder - Fluent API for constructing OpenAPI documents
+ *
+ * @example
+ * ```typescript
+ * const document = new DocumentBuilder()
+ *   .setTitle('My API')
+ *   .setVersion('1.0.0')
+ *   .setDescription('API description')
+ *   .addBearerAuth()
+ *   .addTag('users', 'User management endpoints')
+ *   .build();
+ * ```
+ */
+export declare class DocumentBuilder {
+    private document;
+    /**
+     * Set the API title
+     */
+    setTitle(title: string): this;
+    /**
+     * Set the API description
+     */
+    setDescription(description: string): this;
+    /**
+     * Set the API version
+     */
+    setVersion(version: string): this;
+    /**
+     * Set contact information
+     */
+    setContact(name: string, url?: string, email?: string): this;
+    /**
+     * Set license information
+     */
+    setLicense(name: string, url?: string): this;
+    /**
+     * Add a server
+     */
+    addServer(url: string, description?: string): this;
+    /**
+     * Add Bearer token authentication
+     *
+     * @example
+     * ```typescript
+     * builder.addBearerAuth('JWT')
+     * ```
+     */
+    addBearerAuth(name?: string, options?: SecuritySchemeOptions): this;
+    /**
+     * Add Basic authentication
+     */
+    addBasicAuth(name?: string, options?: SecuritySchemeOptions): this;
+    /**
+     * Add API Key authentication
+     */
+    addApiKey(options: ApiKeySecurityOptions, name?: string): this;
+    /**
+     * Add an OAuth2 security scheme
+     */
+    addOAuth2(name: string, authorizationUrl: string, tokenUrl?: string, refreshUrl?: string): this;
+    /**
+     * Add an OpenID Connect security scheme
+     */
+    addOpenIdConnect(name: string, url: string): this;
+    /**
+     * Add a tag for organizing operations
+     */
+    addTag(name: string, description?: string): this;
+    /**
+     * Build and return the final OpenAPI document
+     */
+    build(): OpenAPIDocument;
+}
+//# sourceMappingURL=document-builder.d.ts.map

package/dist/openapi/document-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"document-builder.d.ts","sourceRoot":"","sources":["../../src/openapi/document-builder.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EACX,qBAAqB,EAErB,eAAe,EAIf,qBAAqB,EACrB,MAAM,SAAS,CAAC;AAEjB;;;;;;;;;;;;;GAaG;AACH,qBAAa,eAAe;IAC3B,OAAO,CAAC,QAAQ,CAYd;IAEF;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAS7B;;OAEG;IACH,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI;IASzC;;OAEG;IACH,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IASjC;;OAEG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI;IAQ5D;;OAEG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI;IAQ5C;;OAEG;IACH,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI;IAQlD;;;;;;;OAOG;IACH,aAAa,CACZ,IAAI,SAAW,EACf,OAAO,CAAC,EAAE,qBAAqB,GAC7B,IAAI;IAsBP;;OAEG;IACH,YAAY,CAAC,IAAI,SAAU,EAAE,OAAO,CAAC,EAAE,qBAAqB,GAAG,IAAI;IAqBnE;;OAEG;IACH,SAAS,CACR,OAAO,EAAE,qBAAqB,EAC9B,IAAI,SAAY,GACd,IAAI;IAsBP;;OAEG;IACH,SAAS,CACR,IAAI,EAAE,MAAM,EACZ,gBAAgB,EAAE,MAAM,EACxB,QAAQ,CAAC,EAAE,MAAM,EACjB,UAAU,CAAC,EAAE,MAAM,GACjB,IAAI;IAuBP;;OAEG;IACH,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI;IAgBjD;;OAEG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI;IAchD;;OAEG;IACH,KAAK,IAAI,eAAe;CAGxB"}

package/dist/openapi/index.d.ts

@@ -0,0 +1,48 @@
+/**
+ * OpenAPI Module
+ *
+ * Auto-generate OpenAPI 3.1 specifications from Bueno controllers and decorators.
+ * Provides decorators for documenting API endpoints and a SwaggerModule for setup.
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   DocumentBuilder,
+ *   SwaggerModule,
+ *   ApiOperation,
+ *   ApiResponse,
+ *   ApiTags,
+ * } from '@buenojs/bueno/openapi';
+ *
+ * // 1. Document your controller
+ * @Controller('/users')
+ * @ApiTags('users')
+ * class UsersController {
+ *   @Get()
+ *   @ApiOperation({ summary: 'List all users' })
+ *   @ApiResponse({ status: 200, description: 'Success', type: [User] })
+ *   async getAll() { ... }
+ * }
+ *
+ * // 2. Create OpenAPI document
+ * const config = new DocumentBuilder()
+ *   .setTitle('My API')
+ *   .setVersion('1.0.0')
+ *   .addBearerAuth()
+ *   .build();
+ *
+ * const document = SwaggerModule.createDocument(app, config, [UsersController]);
+ *
+ * // 3. Setup Swagger UI
+ * SwaggerModule.setup('/api-docs', app, document);
+ * ```
+ */
+export type { OpenAPIDocument, OpenAPIInfo, OpenAPIContact, OpenAPILicense, OpenAPIServer, OpenAPIPaths, OpenAPIPath, OpenAPIOperation, OpenAPIExternalDocs, OpenAPIParameter, OpenAPIRequestBody, OpenAPIMediaType, OpenAPIExample, OpenAPIResponse, OpenAPIHeader, OpenAPIResponses, OpenAPISchema, OpenAPIDiscriminator, OpenAPIXML, OpenAPIComponents, OpenAPISecurityScheme, OpenAPIOAuthFlows, OpenAPIOAuthFlow, OpenAPISecurity, OpenAPITag, SwaggerOptions, ApiOperationOptions, ApiResponseOptions, ApiParamOptions, ApiQueryOptions, ApiHeaderOptions, ApiBodyOptions, ApiPropertyOptions, SecuritySchemeOptions, ApiKeySecurityOptions, Constructor, } from './types';
+export { DocumentBuilder } from './document-builder';
+export { SchemaGenerator } from './schema-generator';
+export { RouteScanner } from './route-scanner';
+export { SwaggerModule } from './swagger-module';
+export { ApiTags, ApiBearerAuth, ApiBasicAuth, ApiApiKey, ApiExcludeController, } from './decorators';
+export { ApiOperation, ApiResponse, ApiParam, ApiQuery, ApiHeader, ApiBody, ApiExcludeEndpoint, } from './decorators';
+export { ApiProperty, ApiPropertyOptional } from './decorators';
+//# sourceMappingURL=index.d.ts.map

package/dist/openapi/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/openapi/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAIH,YAAY,EACX,eAAe,EACf,WAAW,EACX,cAAc,EACd,cAAc,EACd,aAAa,EACb,YAAY,EACZ,WAAW,EACX,gBAAgB,EAChB,mBAAmB,EACnB,gBAAgB,EAChB,kBAAkB,EAClB,gBAAgB,EAChB,cAAc,EACd,eAAe,EACf,aAAa,EACb,gBAAgB,EAChB,aAAa,EACb,oBAAoB,EACpB,UAAU,EACV,iBAAiB,EACjB,qBAAqB,EACrB,iBAAiB,EACjB,gBAAgB,EAChB,eAAe,EACf,UAAU,EACV,cAAc,EACd,mBAAmB,EACnB,kBAAkB,EAClB,eAAe,EACf,eAAe,EACf,gBAAgB,EAChB,cAAc,EACd,kBAAkB,EAClB,qBAAqB,EACrB,qBAAqB,EACrB,WAAW,GACX,MAAM,SAAS,CAAC;AAIjB,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC/C,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAKjD,OAAO,EACN,OAAO,EACP,aAAa,EACb,YAAY,EACZ,SAAS,EACT,oBAAoB,GACpB,MAAM,cAAc,CAAC;AAGtB,OAAO,EACN,YAAY,EACZ,WAAW,EACX,QAAQ,EACR,QAAQ,EACR,SAAS,EACT,OAAO,EACP,kBAAkB,GAClB,MAAM,cAAc,CAAC;AAGtB,OAAO,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC"}

package/dist/openapi/metadata.d.ts

@@ -0,0 +1,36 @@
+/**
+ * OpenAPI Metadata Storage
+ *
+ * Isolated metadata storage using WeakMap, following the same pattern as src/modules/metadata.ts
+ * This avoids circular dependencies and keeps metadata separate from the core module system.
+ */
+import type { Constructor } from './types';
+/**
+ * Set metadata on a class constructor
+ */
+export declare function setApiMetadata(target: Constructor, key: string, value: unknown): void;
+/**
+ * Get metadata from a class constructor
+ */
+export declare function getApiMetadata<T>(target: Constructor, key: string): T | undefined;
+/**
+ * Set metadata on a method prototype
+ */
+export declare function setApiMethodMetadata(target: object, key: string, value: unknown): void;
+/**
+ * Get metadata from a method prototype
+ */
+export declare function getApiMethodMetadata<T>(target: object, key: string): T | undefined;
+/**
+ * Set metadata on a property of a class prototype
+ */
+export declare function setApiPropertyMetadata(target: object, propertyKey: string | symbol, value: unknown): void;
+/**
+ * Get metadata from a property of a class prototype
+ */
+export declare function getApiPropertyMetadata<T>(target: object, propertyKey: string | symbol): T | undefined;
+/**
+ * Get all property metadata keys from a class prototype
+ */
+export declare function getApiPropertyKeys(target: object): (string | symbol)[];
+//# sourceMappingURL=metadata.d.ts.map

package/dist/openapi/metadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadata.d.ts","sourceRoot":"","sources":["../../src/openapi/metadata.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAS3C;;GAEG;AACH,wBAAgB,cAAc,CAC7B,MAAM,EAAE,WAAW,EACnB,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,OAAO,GACZ,IAAI,CAKN;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAC/B,MAAM,EAAE,WAAW,EACnB,GAAG,EAAE,MAAM,GACT,CAAC,GAAG,SAAS,CAEf;AASD;;GAEG;AACH,wBAAgB,oBAAoB,CACnC,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,OAAO,GACZ,IAAI,CAKN;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EACrC,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,MAAM,GACT,CAAC,GAAG,SAAS,CAEf;AASD;;GAEG;AACH,wBAAgB,sBAAsB,CACrC,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,GAAG,MAAM,EAC5B,KAAK,EAAE,OAAO,GACZ,IAAI,CAMN;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,CAAC,EACvC,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,GAAG,MAAM,GAC1B,CAAC,GAAG,SAAS,CAGf;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAItE"}

package/dist/openapi/route-scanner.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Route Scanner
+ *
+ * Scans controllers and extracts OpenAPI operation metadata from decorators.
+ * Combines HTTP method decorators, parameter documentation, and responses
+ * into OpenAPI operation objects.
+ */
+import type { Constructor, OpenAPIPaths } from './types';
+import { SchemaGenerator } from './schema-generator';
+/**
+ * RouteScanner - Scans controllers and extracts OpenAPI operations
+ */
+export declare class RouteScanner {
+    private schemaGenerator;
+    constructor(schemaGenerator: SchemaGenerator);
+    /**
+     * Scan all controllers and generate OpenAPI paths
+     */
+    scanControllers(controllers: Constructor[]): OpenAPIPaths;
+    /**
+     * Generate an OpenAPI operation for a single route
+     */
+    private generateOperation;
+    /**
+     * Convert a route pattern from :param format to {param} format (OpenAPI style)
+     * Handles optional params (:param?) and regex params (:param<regex>)
+     */
+    private convertPathToOpenAPI;
+    /**
+     * Get the schema generator instance
+     */
+    getSchemaGenerator(): SchemaGenerator;
+}
+//# sourceMappingURL=route-scanner.d.ts.map

package/dist/openapi/route-scanner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"route-scanner.d.ts","sourceRoot":"","sources":["../../src/openapi/route-scanner.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EACX,WAAW,EAGX,YAAY,EAGZ,MAAM,SAAS,CAAC;AAIjB,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAQrD;;GAEG;AACH,qBAAa,YAAY;IACZ,OAAO,CAAC,eAAe;gBAAf,eAAe,EAAE,eAAe;IAEpD;;OAEG;IACH,eAAe,CAAC,WAAW,EAAE,WAAW,EAAE,GAAG,YAAY;IAyDzD;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAkLzB;;;OAGG;IACH,OAAO,CAAC,oBAAoB;IAI5B;;OAEG;IACH,kBAAkB,IAAI,eAAe;CAGrC"}

package/dist/openapi/schema-generator.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Schema Generator
+ *
+ * Converts TypeScript class types and @ApiProperty decorators into OpenAPI schemas.
+ */
+import type { Constructor, OpenAPISchema } from './types';
+/**
+ * SchemaGenerator - Converts TypeScript types to OpenAPI schemas
+ */
+export declare class SchemaGenerator {
+    private schemas;
+    private typeNames;
+    private typeCounter;
+    /**
+     * Generate an OpenAPI schema from a TypeScript type
+     * Supports classes, interfaces (via decorators), primitives, arrays
+     */
+    generateSchema(type: Constructor | string | Function): OpenAPISchema;
+    /**
+     * Generate schema for an object/class type
+     * Reads @ApiProperty metadata from class properties
+     */
+    private generateObjectSchema;
+    /**
+     * Generate schema from an @ApiProperty options object
+     */
+    private generatePropertySchema;
+    /**
+     * Generate schema for a primitive TypeScript type
+     */
+    private generatePrimitiveSchema;
+    /**
+     * Map string type names to OpenAPI schema
+     */
+    private mapStringType;
+    /**
+     * Check if type is a built-in TypeScript type
+     */
+    private isBuiltInType;
+    /**
+     * Get the name for a type (for referencing in components.schemas)
+     */
+    private getTypeName;
+    /**
+     * Get all generated schemas (for components.schemas)
+     */
+    getSchemas(): Record<string, OpenAPISchema>;
+    /**
+     * Clear cached schemas
+     */
+    clear(): void;
+}
+//# sourceMappingURL=schema-generator.d.ts.map

package/dist/openapi/schema-generator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-generator.d.ts","sourceRoot":"","sources":["../../src/openapi/schema-generator.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAsB,WAAW,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAG9E;;GAEG;AACH,qBAAa,eAAe;IAC3B,OAAO,CAAC,OAAO,CAAoC;IACnD,OAAO,CAAC,SAAS,CAAkC;IACnD,OAAO,CAAC,WAAW,CAAK;IAExB;;;OAGG;IACH,cAAc,CAAC,IAAI,EAAE,WAAW,GAAG,MAAM,GAAG,QAAQ,GAAG,aAAa;IAiCpE;;;OAGG;IACH,OAAO,CAAC,oBAAoB;IAsC5B;;OAEG;IACH,OAAO,CAAC,sBAAsB;IAkD9B;;OAEG;IACH,OAAO,CAAC,uBAAuB;IAe/B;;OAEG;IACH,OAAO,CAAC,aAAa;IA+BrB;;OAEG;IACH,OAAO,CAAC,aAAa;IAWrB;;OAEG;IACH,OAAO,CAAC,WAAW;IAkBnB;;OAEG;IACH,UAAU,IAAI,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC;IAQ3C;;OAEG;IACH,KAAK,IAAI,IAAI;CAKb"}