@navios/core 0.5.1 → 0.7.0

package/src/decorators/endpoint.decorator.mts

@@ -11,6 +11,30 @@ import { ZodDiscriminatedUnion } from 'zod/v4'
 import { getEndpointMetadata } from '../metadata/index.mjs'
 import { EndpointAdapterToken } from '../tokens/index.mjs'
 
+/**
+ * Extracts the typed parameters for an endpoint handler function.
+ *
+ * This utility type extracts URL parameters, query parameters, and request body
+ * from an endpoint declaration and flattens them into a single object.
+ *
+ * @typeParam EndpointDeclaration - The endpoint declaration from @navios/builder
+ *
+ * @example
+ * ```typescript
+ * const getUserEndpoint = api.declareEndpoint({
+ *   method: 'get',
+ *   url: '/users/$userId',
+ *   querySchema: z.object({ include: z.string().optional() }),
+ *   responseSchema: z.object({ id: z.string(), name: z.string() }),
+ * })
+ *
+ * @Endpoint(getUserEndpoint)
+ * async getUser(request: EndpointParams<typeof getUserEndpoint>) {
+ *   // request.urlParams.userId is typed as string
+ *   // request.query.include is typed as string | undefined
+ * }
+ * ```
+ */
 export type EndpointParams<
   EndpointDeclaration extends {
     config: BaseEndpointConfig<any, any, any, any, any>
@@ -39,6 +63,28 @@ export type EndpointParams<
       >
     : Util_FlatObject<EndpointFunctionArgs<Url, undefined, undefined, true>>
 
+/**
+ * Extracts the typed return value for an endpoint handler function.
+ *
+ * This utility type extracts the response schema from an endpoint declaration
+ * and returns the appropriate Promise type.
+ *
+ * @typeParam EndpointDeclaration - The endpoint declaration from @navios/builder
+ *
+ * @example
+ * ```typescript
+ * const getUserEndpoint = api.declareEndpoint({
+ *   method: 'get',
+ *   url: '/users/$userId',
+ *   responseSchema: z.object({ id: z.string(), name: z.string() }),
+ * })
+ *
+ * @Endpoint(getUserEndpoint)
+ * async getUser(request: EndpointParams<typeof getUserEndpoint>): EndpointResult<typeof getUserEndpoint> {
+ *   return { id: '1', name: 'John' } // Type-checked against responseSchema
+ * }
+ * ```
+ */
 export type EndpointResult<
   EndpointDeclaration extends {
     config: BaseEndpointConfig<any, any, any, any, any>
@@ -50,6 +96,36 @@ export type EndpointResult<
     ? Promise<z.input<Options[number]>>
     : Promise<z.input<EndpointDeclaration['config']['responseSchema']>>
 
+/**
+ * Decorator that marks a method as an HTTP endpoint.
+ *
+ * The endpoint must be defined using @navios/builder's `declareEndpoint` method.
+ * This ensures type safety and consistency between client and server.
+ *
+ * @param endpoint - The endpoint declaration from @navios/builder
+ * @returns A method decorator
+ *
+ * @example
+ * ```typescript
+ * import { builder } from '@navios/builder'
+ *
+ * const api = builder()
+ * const getUserEndpoint = api.declareEndpoint({
+ *   method: 'get',
+ *   url: '/users/$userId',
+ *   responseSchema: z.object({ id: z.string(), name: z.string() }),
+ * })
+ *
+ * @Controller()
+ * export class UserController {
+ *   @Endpoint(getUserEndpoint)
+ *   async getUser(request: EndpointParams<typeof getUserEndpoint>) {
+ *     const { userId } = request.urlParams
+ *     return { id: userId, name: 'John' }
+ *   }
+ * }
+ * ```
+ */
 export function Endpoint<
   Method extends HttpMethod = HttpMethod,
   Url extends string = string,

package/src/decorators/header.decorator.d.mts

@@ -0,0 +1,22 @@
+import type { HttpHeader } from '../interfaces/index.mjs';
+/**
+ * Decorator that sets a custom HTTP response header for an endpoint.
+ *
+ * @param name - The header name (e.g., 'Content-Type', 'Cache-Control')
+ * @param value - The header value (string, number, or array of strings)
+ * @returns A method decorator
+ *
+ * @example
+ * ```typescript
+ * @Controller()
+ * export class UserController {
+ *   @Endpoint(getUserEndpoint)
+ *   @Header('Cache-Control', 'max-age=3600')
+ *   async getUser() {
+ *     return { id: '1', name: 'John' }
+ *   }
+ * }
+ * ```
+ */
+export declare function Header(name: HttpHeader, value: string | number | string[]): <T extends Function>(target: T, context: ClassMethodDecoratorContext) => T;
+//# sourceMappingURL=header.decorator.d.mts.map

package/src/decorators/header.decorator.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"header.decorator.d.mts","sourceRoot":"","sources":["header.decorator.mts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAA;AAIzD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,MAAM,CAAC,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,EAAE,IAChE,CAAC,SAAS,QAAQ,EACxB,QAAQ,CAAC,EACT,SAAS,2BAA2B,OAWvC"}

package/src/decorators/header.decorator.mts

@@ -2,6 +2,25 @@ import type { HttpHeader } from '../interfaces/index.mjs'
 
 import { getEndpointMetadata } from '../metadata/index.mjs'
 
+/**
+ * Decorator that sets a custom HTTP response header for an endpoint.
+ * 
+ * @param name - The header name (e.g., 'Content-Type', 'Cache-Control')
+ * @param value - The header value (string, number, or array of strings)
+ * @returns A method decorator
+ * 
+ * @example
+ * ```typescript
+ * @Controller()
+ * export class UserController {
+ *   @Endpoint(getUserEndpoint)
+ *   @Header('Cache-Control', 'max-age=3600')
+ *   async getUser() {
+ *     return { id: '1', name: 'John' }
+ *   }
+ * }
+ * ```
+ */
 export function Header(name: HttpHeader, value: string | number | string[]) {
   return <T extends Function>(
     target: T,

package/src/decorators/http-code.decorator.d.mts

@@ -0,0 +1,22 @@
+/**
+ * Decorator that sets a custom HTTP status code for successful responses.
+ *
+ * By default, endpoints return 200 OK. Use this decorator to return a different status code.
+ *
+ * @param code - The HTTP status code to return (e.g., 201, 204, 202)
+ * @returns A method decorator
+ *
+ * @example
+ * ```typescript
+ * @Controller()
+ * export class UserController {
+ *   @Endpoint(createUserEndpoint)
+ *   @HttpCode(201)
+ *   async createUser() {
+ *     return { id: '1', name: 'John' }
+ *   }
+ * }
+ * ```
+ */
+export declare function HttpCode(code: number): <T extends Function>(target: T, context: ClassMethodDecoratorContext) => T;
+//# sourceMappingURL=http-code.decorator.d.mts.map

package/src/decorators/http-code.decorator.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-code.decorator.d.mts","sourceRoot":"","sources":["http-code.decorator.mts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,IAC3B,CAAC,SAAS,QAAQ,EACxB,QAAQ,CAAC,EACT,SAAS,2BAA2B,OAYvC"}

package/src/decorators/http-code.decorator.mts

@@ -1,5 +1,25 @@
 import { getEndpointMetadata } from '../metadata/index.mjs'
 
+/**
+ * Decorator that sets a custom HTTP status code for successful responses.
+ * 
+ * By default, endpoints return 200 OK. Use this decorator to return a different status code.
+ * 
+ * @param code - The HTTP status code to return (e.g., 201, 204, 202)
+ * @returns A method decorator
+ * 
+ * @example
+ * ```typescript
+ * @Controller()
+ * export class UserController {
+ *   @Endpoint(createUserEndpoint)
+ *   @HttpCode(201)
+ *   async createUser() {
+ *     return { id: '1', name: 'John' }
+ *   }
+ * }
+ * ```
+ */
 export function HttpCode(code: number) {
   return <T extends Function>(
     target: T,

package/src/decorators/index.d.mts

@@ -0,0 +1,9 @@
+export * from './controller.decorator.mjs';
+export * from './endpoint.decorator.mjs';
+export * from './header.decorator.mjs';
+export * from './http-code.decorator.mjs';
+export * from './module.decorator.mjs';
+export * from './multipart.decorator.mjs';
+export * from './stream.decorator.mjs';
+export * from './use-guards.decorator.mjs';
+//# sourceMappingURL=index.d.mts.map

package/src/decorators/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","sourceRoot":"","sources":["index.mts"],"names":[],"mappings":"AAAA,cAAc,4BAA4B,CAAA;AAC1C,cAAc,0BAA0B,CAAA;AACxC,cAAc,wBAAwB,CAAA;AACtC,cAAc,2BAA2B,CAAA;AACzC,cAAc,wBAAwB,CAAA;AACtC,cAAc,2BAA2B,CAAA;AACzC,cAAc,wBAAwB,CAAA;AACtC,cAAc,4BAA4B,CAAA"}

package/src/decorators/module.decorator.d.mts

@@ -0,0 +1,42 @@
+import type { ClassType } from '@navios/di';
+/**
+ * Options for configuring a Navios module.
+ */
+export interface ModuleOptions {
+    /**
+     * Controllers to register in this module.
+     * Controllers handle HTTP requests and define endpoints.
+     */
+    controllers?: ClassType[] | Set<ClassType>;
+    /**
+     * Other modules to import into this module.
+     * Imported modules' controllers and services become available.
+     */
+    imports?: ClassType[] | Set<ClassType>;
+    /**
+     * Guards to apply to all controllers in this module.
+     * Guards are executed in reverse order (last guard first).
+     */
+    guards?: ClassType[] | Set<ClassType>;
+}
+/**
+ * Decorator that marks a class as a Navios module.
+ *
+ * Modules are the basic building blocks of a Navios application.
+ * They organize controllers, services, and other modules into logical units.
+ *
+ * @param options - Module configuration options
+ * @returns A class decorator
+ *
+ * @example
+ * ```typescript
+ * @Module({
+ *   controllers: [UserController, AuthController],
+ *   imports: [DatabaseModule],
+ *   guards: [AuthGuard],
+ * })
+ * export class AppModule {}
+ * ```
+ */
+export declare function Module({ controllers, imports, guards }?: ModuleOptions): (target: ClassType, context: ClassDecoratorContext) => ClassType;
+//# sourceMappingURL=module.decorator.d.mts.map

package/src/decorators/module.decorator.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"module.decorator.d.mts","sourceRoot":"","sources":["module.decorator.mts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAM3C;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B;;;OAGG;IACH,WAAW,CAAC,EAAE,SAAS,EAAE,GAAG,GAAG,CAAC,SAAS,CAAC,CAAA;IAC1C;;;OAGG;IACH,OAAO,CAAC,EAAE,SAAS,EAAE,GAAG,GAAG,CAAC,SAAS,CAAC,CAAA;IACtC;;;OAGG;IACH,MAAM,CAAC,EAAE,SAAS,EAAE,GAAG,GAAG,CAAC,SAAS,CAAC,CAAA;CACtC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,MAAM,CACpB,EAAE,WAAgB,EAAE,OAAY,EAAE,MAAW,EAAE,GAAE,aAIhD,IAEO,QAAQ,SAAS,EAAE,SAAS,qBAAqB,eAsB1D"}

package/src/decorators/module.decorator.mts

@@ -4,12 +4,46 @@ import { Injectable, InjectableScope, InjectionToken } from '@navios/di'
 
 import { getModuleMetadata } from '../metadata/index.mjs'
 
+/**
+ * Options for configuring a Navios module.
+ */
 export interface ModuleOptions {
+  /**
+   * Controllers to register in this module.
+   * Controllers handle HTTP requests and define endpoints.
+   */
   controllers?: ClassType[] | Set<ClassType>
+  /**
+   * Other modules to import into this module.
+   * Imported modules' controllers and services become available.
+   */
   imports?: ClassType[] | Set<ClassType>
+  /**
+   * Guards to apply to all controllers in this module.
+   * Guards are executed in reverse order (last guard first).
+   */
   guards?: ClassType[] | Set<ClassType>
 }
 
+/**
+ * Decorator that marks a class as a Navios module.
+ * 
+ * Modules are the basic building blocks of a Navios application.
+ * They organize controllers, services, and other modules into logical units.
+ * 
+ * @param options - Module configuration options
+ * @returns A class decorator
+ * 
+ * @example
+ * ```typescript
+ * @Module({
+ *   controllers: [UserController, AuthController],
+ *   imports: [DatabaseModule],
+ *   guards: [AuthGuard],
+ * })
+ * export class AppModule {}
+ * ```
+ */
 export function Module(
   { controllers = [], imports = [], guards = [] }: ModuleOptions = {
     controllers: [],

package/src/decorators/multipart.decorator.d.mts

@@ -0,0 +1,54 @@
+import type { BaseEndpointConfig, EndpointFunctionArgs, HttpMethod, Util_FlatObject } from '@navios/builder';
+import type { z, ZodObject, ZodType } from 'zod/v4';
+import { ZodDiscriminatedUnion } from 'zod/v4';
+/**
+ * Extracts the typed parameters for a multipart endpoint handler function.
+ *
+ * Similar to `EndpointParams`, but specifically for multipart/form-data endpoints.
+ *
+ * @typeParam EndpointDeclaration - The endpoint declaration from @navios/builder
+ */
+export type MultipartParams<EndpointDeclaration extends {
+    config: BaseEndpointConfig<any, any, any, any, any>;
+}, Url extends string = EndpointDeclaration['config']['url'], QuerySchema = EndpointDeclaration['config']['querySchema']> = QuerySchema extends ZodObject ? EndpointDeclaration['config']['requestSchema'] extends ZodType ? Util_FlatObject<EndpointFunctionArgs<Url, QuerySchema, EndpointDeclaration['config']['requestSchema'], true>> : Util_FlatObject<EndpointFunctionArgs<Url, QuerySchema, undefined, true>> : EndpointDeclaration['config']['requestSchema'] extends ZodType ? Util_FlatObject<EndpointFunctionArgs<Url, undefined, EndpointDeclaration['config']['requestSchema'], true>> : Util_FlatObject<EndpointFunctionArgs<Url, undefined, undefined, true>>;
+/**
+ * Extracts the typed return value for a multipart endpoint handler function.
+ *
+ * @typeParam EndpointDeclaration - The endpoint declaration from @navios/builder
+ */
+export type MultipartResult<EndpointDeclaration extends {
+    config: BaseEndpointConfig<any, any, any, any, any>;
+}> = EndpointDeclaration['config']['responseSchema'] extends ZodDiscriminatedUnion<infer Options> ? Promise<z.input<Options[number]>> : Promise<z.input<EndpointDeclaration['config']['responseSchema']>>;
+/**
+ * Decorator that marks a method as a multipart/form-data endpoint.
+ *
+ * Use this decorator for endpoints that handle file uploads or form data.
+ * The endpoint must be defined using @navios/builder's `declareMultipart` method.
+ *
+ * @param endpoint - The multipart endpoint declaration from @navios/builder
+ * @returns A method decorator
+ *
+ * @example
+ * ```typescript
+ * const uploadFileEndpoint = api.declareMultipart({
+ *   method: 'post',
+ *   url: '/upload',
+ *   requestSchema: z.object({ file: z.instanceof(File) }),
+ *   responseSchema: z.object({ url: z.string() }),
+ * })
+ *
+ * @Controller()
+ * export class FileController {
+ *   @Multipart(uploadFileEndpoint)
+ *   async uploadFile(request: MultipartParams<typeof uploadFileEndpoint>) {
+ *     const { file } = request.data
+ *     // Handle file upload
+ *     return { url: 'https://example.com/file.jpg' }
+ *   }
+ * }
+ * ```
+ */
+export declare function Multipart<Method extends HttpMethod = HttpMethod, Url extends string = string, QuerySchema = undefined, ResponseSchema extends ZodType = ZodType, RequestSchema = ZodType>(endpoint: {
+    config: BaseEndpointConfig<Method, Url, QuerySchema, ResponseSchema, RequestSchema>;
+}): (target: (params: QuerySchema extends ZodObject ? RequestSchema extends ZodType ? EndpointFunctionArgs<Url, QuerySchema, RequestSchema> : EndpointFunctionArgs<Url, QuerySchema, undefined> : RequestSchema extends ZodType ? EndpointFunctionArgs<Url, undefined, RequestSchema> : EndpointFunctionArgs<Url, undefined, undefined>) => Promise<z.input<ResponseSchema>>, context: ClassMethodDecoratorContext) => (params: QuerySchema extends ZodObject ? RequestSchema extends ZodType ? EndpointFunctionArgs<Url, QuerySchema, RequestSchema> : EndpointFunctionArgs<Url, QuerySchema, undefined> : RequestSchema extends ZodType ? EndpointFunctionArgs<Url, undefined, RequestSchema> : EndpointFunctionArgs<Url, undefined, undefined>) => Promise<z.input<ResponseSchema>>;
+//# sourceMappingURL=multipart.decorator.d.mts.map

package/src/decorators/multipart.decorator.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"multipart.decorator.d.mts","sourceRoot":"","sources":["multipart.decorator.mts"],"names":[],"mappings":"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"}

package/src/decorators/multipart.decorator.mts

@@ -11,6 +11,13 @@ import { ZodDiscriminatedUnion } from 'zod/v4'
 import { getEndpointMetadata } from '../metadata/index.mjs'
 import { MultipartAdapterToken } from '../tokens/index.mjs'
 
+/**
+ * Extracts the typed parameters for a multipart endpoint handler function.
+ * 
+ * Similar to `EndpointParams`, but specifically for multipart/form-data endpoints.
+ * 
+ * @typeParam EndpointDeclaration - The endpoint declaration from @navios/builder
+ */
 export type MultipartParams<
   EndpointDeclaration extends {
     config: BaseEndpointConfig<any, any, any, any, any>
@@ -39,6 +46,11 @@ export type MultipartParams<
       >
     : Util_FlatObject<EndpointFunctionArgs<Url, undefined, undefined, true>>
 
+/**
+ * Extracts the typed return value for a multipart endpoint handler function.
+ * 
+ * @typeParam EndpointDeclaration - The endpoint declaration from @navios/builder
+ */
 export type MultipartResult<
   EndpointDeclaration extends {
     config: BaseEndpointConfig<any, any, any, any, any>
@@ -50,6 +62,35 @@ export type MultipartResult<
     ? Promise<z.input<Options[number]>>
     : Promise<z.input<EndpointDeclaration['config']['responseSchema']>>
 
+/**
+ * Decorator that marks a method as a multipart/form-data endpoint.
+ * 
+ * Use this decorator for endpoints that handle file uploads or form data.
+ * The endpoint must be defined using @navios/builder's `declareMultipart` method.
+ * 
+ * @param endpoint - The multipart endpoint declaration from @navios/builder
+ * @returns A method decorator
+ * 
+ * @example
+ * ```typescript
+ * const uploadFileEndpoint = api.declareMultipart({
+ *   method: 'post',
+ *   url: '/upload',
+ *   requestSchema: z.object({ file: z.instanceof(File) }),
+ *   responseSchema: z.object({ url: z.string() }),
+ * })
+ * 
+ * @Controller()
+ * export class FileController {
+ *   @Multipart(uploadFileEndpoint)
+ *   async uploadFile(request: MultipartParams<typeof uploadFileEndpoint>) {
+ *     const { file } = request.data
+ *     // Handle file upload
+ *     return { url: 'https://example.com/file.jpg' }
+ *   }
+ * }
+ * ```
+ */
 export function Multipart<
   Method extends HttpMethod = HttpMethod,
   Url extends string = string,

package/src/decorators/stream.decorator.d.mts

@@ -0,0 +1,42 @@
+import type { BaseStreamConfig, EndpointFunctionArgs, HttpMethod, Util_FlatObject } from '@navios/builder';
+import type { ZodObject, ZodType } from 'zod/v4';
+/**
+ * Extracts the typed parameters for a stream endpoint handler function.
+ *
+ * Similar to `EndpointParams`, but specifically for streaming endpoints.
+ *
+ * @typeParam EndpointDeclaration - The stream endpoint declaration from @navios/builder
+ */
+export type StreamParams<EndpointDeclaration extends {
+    config: BaseStreamConfig<any, any, any, any>;
+}, Url extends string = EndpointDeclaration['config']['url'], QuerySchema = EndpointDeclaration['config']['querySchema']> = QuerySchema extends ZodObject ? EndpointDeclaration['config']['requestSchema'] extends ZodType ? Util_FlatObject<EndpointFunctionArgs<Url, QuerySchema, EndpointDeclaration['config']['requestSchema'], true>> : Util_FlatObject<EndpointFunctionArgs<Url, QuerySchema, undefined, true>> : EndpointDeclaration['config']['requestSchema'] extends ZodType ? Util_FlatObject<EndpointFunctionArgs<Url, undefined, EndpointDeclaration['config']['requestSchema'], true>> : Util_FlatObject<EndpointFunctionArgs<Url, undefined, undefined, true>>;
+/**
+ * Decorator that marks a method as a streaming endpoint.
+ *
+ * Use this decorator for endpoints that stream data (e.g., file downloads, SSE).
+ * The endpoint must be defined using @navios/builder's `declareStream` method.
+ *
+ * @param endpoint - The stream endpoint declaration from @navios/builder
+ * @returns A method decorator
+ *
+ * @example
+ * ```typescript
+ * const downloadFileEndpoint = api.declareStream({
+ *   method: 'get',
+ *   url: '/files/$fileId',
+ * })
+ *
+ * @Controller()
+ * export class FileController {
+ *   @Stream(downloadFileEndpoint)
+ *   async downloadFile(request: StreamParams<typeof downloadFileEndpoint>, reply: any) {
+ *     const { fileId } = request.urlParams
+ *     // Stream file data to reply
+ *   }
+ * }
+ * ```
+ */
+export declare function Stream<Method extends HttpMethod = HttpMethod, Url extends string = string, QuerySchema = undefined, RequestSchema = ZodType>(endpoint: {
+    config: BaseStreamConfig<Method, Url, QuerySchema, RequestSchema>;
+}): (target: (params: QuerySchema extends ZodObject ? RequestSchema extends ZodType ? EndpointFunctionArgs<Url, QuerySchema, RequestSchema> : EndpointFunctionArgs<Url, QuerySchema, undefined> : RequestSchema extends ZodType ? EndpointFunctionArgs<Url, undefined, RequestSchema> : EndpointFunctionArgs<Url, undefined, undefined>, reply: any) => Promise<void>, context: ClassMethodDecoratorContext) => (params: QuerySchema extends ZodObject ? RequestSchema extends ZodType ? EndpointFunctionArgs<Url, QuerySchema, RequestSchema> : EndpointFunctionArgs<Url, QuerySchema, undefined> : RequestSchema extends ZodType ? EndpointFunctionArgs<Url, undefined, RequestSchema> : EndpointFunctionArgs<Url, undefined, undefined>, reply: any) => Promise<void>;
+//# sourceMappingURL=stream.decorator.d.mts.map

package/src/decorators/stream.decorator.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream.decorator.d.mts","sourceRoot":"","sources":["stream.decorator.mts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,gBAAgB,EAChB,oBAAoB,EACpB,UAAU,EACV,eAAe,EAChB,MAAM,iBAAiB,CAAA;AACxB,OAAO,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAA;AAKhD;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,CACtB,mBAAmB,SAAS;IAC1B,MAAM,EAAE,gBAAgB,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAA;CAC7C,EACD,GAAG,SAAS,MAAM,GAAG,mBAAmB,CAAC,QAAQ,CAAC,CAAC,KAAK,CAAC,EACzD,WAAW,GAAG,mBAAmB,CAAC,QAAQ,CAAC,CAAC,aAAa,CAAC,IACxD,WAAW,SAAS,SAAS,GAC7B,mBAAmB,CAAC,QAAQ,CAAC,CAAC,eAAe,CAAC,SAAS,OAAO,GAC5D,eAAe,CACb,oBAAoB,CAClB,GAAG,EACH,WAAW,EACX,mBAAmB,CAAC,QAAQ,CAAC,CAAC,eAAe,CAAC,EAC9C,IAAI,CACL,CACF,GACD,eAAe,CAAC,oBAAoB,CAAC,GAAG,EAAE,WAAW,EAAE,SAAS,EAAE,IAAI,CAAC,CAAC,GAC1E,mBAAmB,CAAC,QAAQ,CAAC,CAAC,eAAe,CAAC,SAAS,OAAO,GAC5D,eAAe,CACb,oBAAoB,CAClB,GAAG,EACH,SAAS,EACT,mBAAmB,CAAC,QAAQ,CAAC,CAAC,eAAe,CAAC,EAC9C,IAAI,CACL,CACF,GACD,eAAe,CAAC,oBAAoB,CAAC,GAAG,EAAE,SAAS,EAAE,SAAS,EAAE,IAAI,CAAC,CAAC,CAAA;AAE5E;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,MAAM,CACpB,MAAM,SAAS,UAAU,GAAG,UAAU,EACtC,GAAG,SAAS,MAAM,GAAG,MAAM,EAC3B,WAAW,GAAG,SAAS,EACvB,aAAa,GAAG,OAAO,EACvB,QAAQ,EAAE;IACV,MAAM,EAAE,gBAAgB,CAAC,MAAM,EAAE,GAAG,EAAE,WAAW,EAAE,aAAa,CAAC,CAAA;CAClE,IAEG,QAAQ,CACN,MAAM,EAAE,WAAW,SAAS,SAAS,GACjC,aAAa,SAAS,OAAO,GAC3B,oBAAoB,CAAC,GAAG,EAAE,WAAW,EAAE,aAAa,CAAC,GACrD,oBAAoB,CAAC,GAAG,EAAE,WAAW,EAAE,SAAS,CAAC,GACnD,aAAa,SAAS,OAAO,GAC3B,oBAAoB,CAAC,GAAG,EAAE,SAAS,EAAE,aAAa,CAAC,GACnD,oBAAoB,CAAC,GAAG,EAAE,SAAS,EAAE,SAAS,CAAC,EACrD,KAAK,EAAE,GAAG,KACP,OAAO,CAAC,IAAI,CAAC,EAClB,SAAS,2BAA2B,cAT1B,WAAW,SAAS,SAAS,GACjC,aAAa,SAAS,OAAO,GAC3B,oBAAoB,CAAC,GAAG,EAAE,WAAW,EAAE,aAAa,CAAC,GACrD,oBAAoB,CAAC,GAAG,EAAE,WAAW,EAAE,SAAS,CAAC,GACnD,aAAa,SAAS,OAAO,GAC3B,oBAAoB,CAAC,GAAG,EAAE,SAAS,EAAE,aAAa,CAAC,GACnD,oBAAoB,CAAC,GAAG,EAAE,SAAS,EAAE,SAAS,CAAC,SAC9C,GAAG,KACP,OAAO,CAAC,IAAI,CAAC,CAiCrB"}

package/src/decorators/stream.decorator.mts

@@ -9,6 +9,13 @@ import type { ZodObject, ZodType } from 'zod/v4'
 import { getEndpointMetadata } from '../metadata/index.mjs'
 import { StreamAdapterToken } from '../tokens/index.mjs'
 
+/**
+ * Extracts the typed parameters for a stream endpoint handler function.
+ * 
+ * Similar to `EndpointParams`, but specifically for streaming endpoints.
+ * 
+ * @typeParam EndpointDeclaration - The stream endpoint declaration from @navios/builder
+ */
 export type StreamParams<
   EndpointDeclaration extends {
     config: BaseStreamConfig<any, any, any, any>
@@ -37,6 +44,32 @@ export type StreamParams<
       >
     : Util_FlatObject<EndpointFunctionArgs<Url, undefined, undefined, true>>
 
+/**
+ * Decorator that marks a method as a streaming endpoint.
+ * 
+ * Use this decorator for endpoints that stream data (e.g., file downloads, SSE).
+ * The endpoint must be defined using @navios/builder's `declareStream` method.
+ * 
+ * @param endpoint - The stream endpoint declaration from @navios/builder
+ * @returns A method decorator
+ * 
+ * @example
+ * ```typescript
+ * const downloadFileEndpoint = api.declareStream({
+ *   method: 'get',
+ *   url: '/files/$fileId',
+ * })
+ * 
+ * @Controller()
+ * export class FileController {
+ *   @Stream(downloadFileEndpoint)
+ *   async downloadFile(request: StreamParams<typeof downloadFileEndpoint>, reply: any) {
+ *     const { fileId } = request.urlParams
+ *     // Stream file data to reply
+ *   }
+ * }
+ * ```
+ */
 export function Stream<
   Method extends HttpMethod = HttpMethod,
   Url extends string = string,

package/src/decorators/use-guards.decorator.d.mts

@@ -0,0 +1,33 @@
+import type { ClassTypeWithInstance, InjectionToken } from '@navios/di';
+import type { CanActivate } from '../interfaces/index.mjs';
+/**
+ * Decorator that applies guards to a controller or endpoint.
+ *
+ * Guards are used for authentication, authorization, and request validation.
+ * They implement the `CanActivate` interface and are executed before the endpoint handler.
+ * Guards can be applied at the module, controller, or endpoint level.
+ *
+ * @param guards - Guard classes or injection tokens to apply
+ * @returns A class or method decorator
+ *
+ * @example
+ * ```typescript
+ * // Apply to a controller
+ * @Controller()
+ * @UseGuards(AuthGuard, RoleGuard)
+ * export class UserController {
+ *   @Endpoint(getUserEndpoint)
+ *   async getUser() { }
+ * }
+ *
+ * // Apply to a specific endpoint
+ * @Controller()
+ * export class UserController {
+ *   @Endpoint(getUserEndpoint)
+ *   @UseGuards(AuthGuard)
+ *   async getUser() { }
+ * }
+ * ```
+ */
+export declare function UseGuards(...guards: (ClassTypeWithInstance<CanActivate> | InjectionToken<CanActivate, undefined>)[]): <T extends Function>(target: T, context: ClassMethodDecoratorContext | ClassDecoratorContext) => T;
+//# sourceMappingURL=use-guards.decorator.d.mts.map

package/src/decorators/use-guards.decorator.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-guards.decorator.d.mts","sourceRoot":"","sources":["use-guards.decorator.mts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEV,qBAAqB,EACrB,cAAc,EACf,MAAM,YAAY,CAAA;AAEnB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAA;AAO1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,SAAS,CACvB,GAAG,MAAM,EAAE,CACP,qBAAqB,CAAC,WAAW,CAAC,GAClC,cAAc,CAAC,WAAW,EAAE,SAAS,CAAC,CACzC,EAAE,IAEc,CAAC,SAAS,QAAQ,EACjC,QAAQ,CAAC,EACT,SAAS,2BAA2B,GAAG,qBAAqB,KAC3D,CAAC,CAqBL"}

package/src/decorators/use-guards.decorator.mts

@@ -11,6 +11,35 @@ import {
   getEndpointMetadata,
 } from '../metadata/index.mjs'
 
+/**
+ * Decorator that applies guards to a controller or endpoint.
+ * 
+ * Guards are used for authentication, authorization, and request validation.
+ * They implement the `CanActivate` interface and are executed before the endpoint handler.
+ * Guards can be applied at the module, controller, or endpoint level.
+ * 
+ * @param guards - Guard classes or injection tokens to apply
+ * @returns A class or method decorator
+ * 
+ * @example
+ * ```typescript
+ * // Apply to a controller
+ * @Controller()
+ * @UseGuards(AuthGuard, RoleGuard)
+ * export class UserController {
+ *   @Endpoint(getUserEndpoint)
+ *   async getUser() { }
+ * }
+ * 
+ * // Apply to a specific endpoint
+ * @Controller()
+ * export class UserController {
+ *   @Endpoint(getUserEndpoint)
+ *   @UseGuards(AuthGuard)
+ *   async getUser() { }
+ * }
+ * ```
+ */
 export function UseGuards(
   ...guards: (
     | ClassTypeWithInstance<CanActivate>

package/src/exceptions/bad-request.exception.d.mts

@@ -0,0 +1,26 @@
+import { HttpException } from './http.exception.mjs';
+/**
+ * Exception that represents a 400 Bad Request HTTP error.
+ *
+ * Use this exception when the client's request is malformed or invalid.
+ *
+ * @example
+ * ```typescript
+ * @Endpoint(createUserEndpoint)
+ * async createUser(request: EndpointParams<typeof createUserEndpoint>) {
+ *   if (!request.data.email) {
+ *     throw new BadRequestException('Email is required')
+ *   }
+ *   // ...
+ * }
+ * ```
+ */
+export declare class BadRequestException extends HttpException {
+    /**
+     * Creates a new BadRequestException.
+     *
+     * @param message - Error message or response object
+     */
+    constructor(message: string | object);
+}
+//# sourceMappingURL=bad-request.exception.d.mts.map

package/src/exceptions/bad-request.exception.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bad-request.exception.d.mts","sourceRoot":"","sources":["bad-request.exception.mts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAA;AAEpD;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,mBAAoB,SAAQ,aAAa;IACpD;;;;OAIG;gBACS,OAAO,EAAE,MAAM,GAAG,MAAM;CAGrC"}