@moostjs/event-http 0.5.33 → 0.6.1

package/dist/index.d.ts

@@ -1,20 +1,109 @@
-import { THook } from '@wooksjs/event-core';
-import { TCookieAttributes as TCookieAttributes$1, useSetCookies, WooksHttp, TWooksHttpOptions } from '@wooksjs/event-http';
-export { HttpError, TCacheControl, TCookieAttributesInput, TSetCookieData, useHttpContext } from '@wooksjs/event-http';
 import * as moost from 'moost';
-import { TInterceptorFn, TMoostAdapter, Moost, TConsoleBase, TMoostAdapterOptions } from 'moost';
-import * as _prostojs_infact from '@prostojs/infact';
+import { TInterceptorPriority, TOvertakeFn, TInterceptorDef, TClassConstructor, TMoostAdapter, Moost, TConsoleBase, TMoostAdapterOptions } from 'moost';
+import { TCookieAttributes as TCookieAttributes$1, TCookieAttributesInput, WooksHttp, TWooksHttpOptions } from '@wooksjs/event-http';
+export { HttpError, TCacheControl, TCookieAttributesInput, TSetCookieData, httpKind, useHttpContext } from '@wooksjs/event-http';
 import * as http from 'http';
 import { TProstoRouterPathBuilder } from '@prostojs/router';
 import { ListenOptions } from 'net';
 
-declare function HttpMethod(method: '*' | 'GET' | 'PUT' | 'POST' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS', path?: string): MethodDecorator;
+/** Bearer token transport configuration for auth guards. */
+interface TAuthTransportBearer {
+    format?: string;
+    description?: string;
+}
+/** Basic auth transport configuration for auth guards. */
+interface TAuthTransportBasic {
+    description?: string;
+}
+/** API key transport configuration specifying location (header, query, or cookie). */
+interface TAuthTransportApiKey {
+    name: string;
+    in: 'header' | 'query' | 'cookie';
+    description?: string;
+}
+/** Cookie-based auth transport configuration. */
+interface TAuthTransportCookie {
+    name: string;
+    description?: string;
+}
+/** Declares which auth credential transports a guard accepts. */
+interface TAuthTransportDeclaration {
+    bearer?: TAuthTransportBearer;
+    basic?: TAuthTransportBasic;
+    apiKey?: TAuthTransportApiKey;
+    cookie?: TAuthTransportCookie;
+}
+/** Type-narrowed credential values extracted from declared transports. */
+type TAuthTransportValues<T extends TAuthTransportDeclaration> = {
+    [K in keyof T & keyof TAuthTransportDeclaration]: K extends 'basic' ? {
+        username: string;
+        password: string;
+    } : string;
+};
+/** Extracts auth credentials from the current request based on transport declarations. Throws 401 if none found. */
+declare function extractTransports<T extends TAuthTransportDeclaration>(declaration: T): TAuthTransportValues<T>;
+/** Auth guard def returned by defineAuthGuard — carries transport declarations. */
+interface TAuthGuardDef extends TInterceptorDef {
+    __authTransports: TAuthTransportDeclaration;
+}
+/** Auth guard class extending AuthGuard — carries transport declarations as static property. */
+type TAuthGuardClass = TClassConstructor<AuthGuard> & {
+    transports: TAuthTransportDeclaration;
+    priority: TInterceptorPriority;
+};
+/** Accepted handler for Authenticate — either a functional or class-based auth guard. */
+type TAuthGuardHandler = TAuthGuardDef | TAuthGuardClass;
+/**
+ * Creates a functional auth guard interceptor.
+ * Extracts credentials from declared transports and passes them to the handler.
+ * Return a value from the handler to short-circuit with that response.
+ */
+declare function defineAuthGuard<T extends TAuthTransportDeclaration>(transports: T, handler: (transports: TAuthTransportValues<T>) => unknown | Promise<unknown>): TAuthGuardDef;
+/**
+ * Abstract base class for class-based auth guards.
+ * Extend this class, set `static transports`, and implement `handle()`.
+ */
+declare abstract class AuthGuard<T extends TAuthTransportDeclaration = TAuthTransportDeclaration> {
+    static transports: TAuthTransportDeclaration;
+    static priority: TInterceptorPriority;
+    abstract handle(transports: TAuthTransportValues<T>): unknown | Promise<unknown>;
+    __intercept(reply: TOvertakeFn): Promise<undefined> | undefined;
+}
+/**
+ * Registers an auth guard as an interceptor and stores its transport
+ * declarations in metadata for swagger auto-discovery.
+ *
+ * Accepts either a functional guard from `defineAuthGuard()` or a
+ * class-based guard extending `AuthGuard`.
+ */
+declare function Authenticate(handler: TAuthGuardHandler): ClassDecorator & MethodDecorator;
+
+/** Base decorator for registering an HTTP route handler with an explicit method. */
+declare function HttpMethod(method: '*' | 'GET' | 'PUT' | 'POST' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS' | 'UPGRADE', path?: string): MethodDecorator;
+/** Register a catch-all route handler matching any HTTP method. */
 declare const All: (path?: string) => MethodDecorator;
+/** Register a GET route handler. */
 declare const Get: (path?: string) => MethodDecorator;
+/** Register a POST route handler. */
 declare const Post: (path?: string) => MethodDecorator;
+/** Register a PUT route handler. */
 declare const Put: (path?: string) => MethodDecorator;
+/** Register a DELETE route handler. */
 declare const Delete: (path?: string) => MethodDecorator;
+/** Register a PATCH route handler. */
 declare const Patch: (path?: string) => MethodDecorator;
+/**
+ * Register an UPGRADE route handler for WebSocket upgrade requests.
+ *
+ * Use together with `WooksWs` (injected via DI) to complete the handshake:
+ * ```ts
+ * @Upgrade('/ws')
+ * handleUpgrade(ws: WooksWs) {
+ *   return ws.upgrade()
+ * }
+ * ```
+ */
+declare const Upgrade: (path?: string) => MethodDecorator;
 
 /**
  * Hook to the Response Status
@@ -130,16 +219,27 @@ declare function Body(): MethodDecorator & ClassDecorator & ParameterDecorator &
  * @paramType Promise<Buffer>
  */
 declare function RawBody(): ParameterDecorator & PropertyDecorator;
-type TStatusHook = THook<number>;
-type THeaderHook = THook;
+/** Reactive hook for reading/writing the response status code. */
+interface TStatusHook {
+    value: number;
+}
+/** Reactive hook for reading/writing a response header value. */
+interface THeaderHook {
+    value: string | string[] | undefined;
+}
+/** Partial cookie attributes (all optional). */
 type TCookieAttributes = Partial<TCookieAttributes$1>;
-type TCookieHook = THook & Partial<THook<TCookieAttributes, 'attrs'>>;
+/** Reactive hook for reading/writing a response cookie. */
+interface TCookieHook {
+    value: string;
+    attrs?: TCookieAttributes;
+}
 
 declare const setHeaderInterceptor: (name: string, value: string, opts?: {
     force?: boolean;
     status?: number;
-    when?: 'always' | 'error' | 'ok';
-}) => TInterceptorFn;
+    when?: "always" | "error" | "ok";
+}) => TInterceptorDef;
 /**
  * Set Header for Request Handler
  *
@@ -178,7 +278,7 @@ declare const setHeaderInterceptor: (name: string, value: string, opts?: {
  * @param options options { status?: number, force?: boolean }
  */
 declare function SetHeader(...args: Parameters<typeof setHeaderInterceptor>): ClassDecorator & MethodDecorator;
-declare const setCookieInterceptor: (...args: Parameters<ReturnType<typeof useSetCookies>['setCookie']>) => TInterceptorFn;
+declare const setCookieInterceptor: (name: string, value: string, attrs?: TCookieAttributesInput) => TInterceptorDef;
 /**
  * Set Cookie for Request Handler
  * ```ts
@@ -203,7 +303,7 @@ declare const setCookieInterceptor: (...args: Parameters<ReturnType<typeof useSe
 declare function SetCookie(...args: Parameters<typeof setCookieInterceptor>): ClassDecorator & MethodDecorator;
 declare const setStatusInterceptor: (code: number, opts?: {
     force?: boolean;
-}) => TInterceptorFn;
+}) => TInterceptorDef;
 /**
  * Set Response Status for Request Handler
  *
@@ -229,23 +329,23 @@ declare function SetStatus(...args: Parameters<typeof setStatusInterceptor>): Cl
  * Creates an interceptor that sets the maximum allowed inflated body size in bytes.
  *
  * @param n - Maximum body size in bytes after decompression.
- * @returns Interceptor function to enforce the limit.
+ * @returns Interceptor def to enforce the limit.
  */
-declare const globalBodySizeLimit: (n: number) => moost.TInterceptorFn;
+declare const globalBodySizeLimit: (n: number) => moost.TInterceptorDef;
 /**
  * Creates an interceptor that sets the maximum allowed compressed body size in bytes.
  *
  * @param n - Maximum body size in bytes before decompression.
- * @returns Interceptor function to enforce the limit.
+ * @returns Interceptor def to enforce the limit.
  */
-declare const globalCompressedBodySizeLimit: (n: number) => moost.TInterceptorFn;
+declare const globalCompressedBodySizeLimit: (n: number) => moost.TInterceptorDef;
 /**
  * Creates an interceptor that sets the timeout for reading the request body.
  *
  * @param n - Timeout in milliseconds.
- * @returns Interceptor function to enforce the timeout.
+ * @returns Interceptor def to enforce the timeout.
  */
-declare const globalBodyReadTimeoutMs: (n: number) => moost.TInterceptorFn;
+declare const globalBodyReadTimeoutMs: (n: number) => moost.TInterceptorDef;
 /**
  * Decorator to limit the maximum inflated body size for the request. Default: 10 MB
  *
@@ -265,6 +365,7 @@ declare const CompressedBodySizeLimit: (n: number) => ClassDecorator & MethodDec
  */
 declare const BodyReadTimeoutMs: (n: number) => ClassDecorator & MethodDecorator;
 
+/** Handler metadata for HTTP events, carrying the HTTP method and route path. */
 interface THttpHandlerMeta {
     method: string;
     path: string;
@@ -319,10 +420,10 @@ declare class MoostHttp implements TMoostAdapter<THttpHandlerMeta> {
     onNotFound(): Promise<unknown>;
     protected moost?: Moost;
     onInit(moost: Moost): void;
-    getProvideRegistry(): _prostojs_infact.TProvideRegistry;
+    getProvideRegistry(): moost.TProvideRegistry;
     getLogger(): TConsoleBase;
     bindHandler<T extends object = object>(opts: TMoostAdapterOptions<THttpHandlerMeta, T>): void;
 }
 
-export { All, Authorization, Body, BodyReadTimeoutMs, BodySizeLimit, CompressedBodySizeLimit, Cookie, CookieAttrsHook, CookieHook, Delete, Get, Header, HeaderHook, HttpMethod, Ip, IpList, Method, MoostHttp, Patch, Post, Put, Query, RawBody, Req, ReqId, Res, SetCookie, SetHeader, SetStatus, StatusHook, Url, globalBodyReadTimeoutMs, globalBodySizeLimit, globalCompressedBodySizeLimit };
-export type { TCookieAttributes, TCookieHook, THeaderHook, THttpHandlerMeta, TStatusHook };
+export { All, AuthGuard, Authenticate, Authorization, Body, BodyReadTimeoutMs, BodySizeLimit, CompressedBodySizeLimit, Cookie, CookieAttrsHook, CookieHook, Delete, Get, Header, HeaderHook, HttpMethod, Ip, IpList, Method, MoostHttp, Patch, Post, Put, Query, RawBody, Req, ReqId, Res, SetCookie, SetHeader, SetStatus, StatusHook, Upgrade, Url, defineAuthGuard, extractTransports, globalBodyReadTimeoutMs, globalBodySizeLimit, globalCompressedBodySizeLimit };
+export type { TAuthGuardClass, TAuthGuardDef, TAuthGuardHandler, TAuthTransportApiKey, TAuthTransportBasic, TAuthTransportBearer, TAuthTransportCookie, TAuthTransportDeclaration, TAuthTransportValues, TCookieAttributes, TCookieHook, THeaderHook, THttpHandlerMeta, TStatusHook };