@geekmidas/constructs 0.0.3 → 0.0.5

package/dist/{Endpoint-D1nnEsBU.cjs → Endpoint-BVZJb4OR.cjs}

@@ -44,12 +44,16 @@ var Endpoint = class Endpoint extends require_Function.Function {
 	tags;
 	/** The HTTP success status code to return (default: 200) */
 	status;
+	/** Default headers to apply to all responses */
+	defaultHeaders = {};
 	/** Function to extract session data from the request context */
 	getSession = () => ({});
 	/** Function to determine if the request is authorized */
 	authorize = () => true;
 	/** Optional rate limiting configuration */
 	rateLimit;
+	/** The endpoint handler function */
+	endpointFn;
 	/**
 	* Builds a complete OpenAPI 3.1 schema from an array of endpoints.
 	*
@@ -126,6 +130,67 @@ var Endpoint = class Endpoint extends require_Function.Function {
 		};
 	}
 	/**
+	* Parses cookie string and creates a cookie lookup function.
+	*
+	* @param cookieHeader - The Cookie header value
+	* @returns Function to retrieve cookie values by name
+	*
+	* @example
+	* ```typescript
+	* const cookieFn = Endpoint.createCookies('session=abc123; theme=dark');
+	* cookieFn('session'); // Returns 'abc123'
+	* cookieFn('theme'); // Returns 'dark'
+	* ```
+	*/
+	static createCookies(cookieHeader) {
+		const cookieMap = /* @__PURE__ */ new Map();
+		if (cookieHeader) {
+			const cookies = cookieHeader.split(";");
+			for (const cookie of cookies) {
+				const [name, ...valueParts] = cookie.trim().split("=");
+				if (name) {
+					const value = valueParts.join("=");
+					cookieMap.set(name, decodeURIComponent(value));
+				}
+			}
+		}
+		return function get(name) {
+			return cookieMap.get(name);
+		};
+	}
+	/**
+	* Formats a cookie as a Set-Cookie header string.
+	*
+	* @param name - Cookie name
+	* @param value - Cookie value
+	* @param options - Cookie options (httpOnly, secure, sameSite, etc.)
+	* @returns Formatted Set-Cookie header string
+	*
+	* @example
+	* ```typescript
+	* const header = Endpoint.formatCookieHeader('session', 'abc123', {
+	*   httpOnly: true,
+	*   secure: true,
+	*   sameSite: 'strict',
+	*   maxAge: 3600
+	* });
+	* // Returns: "session=abc123; Max-Age=3600; HttpOnly; Secure; SameSite=Strict"
+	* ```
+	*/
+	static formatCookieHeader(name, value, options) {
+		let cookie = `${name}=${value}`;
+		if (options) {
+			if (options.domain) cookie += `; Domain=${options.domain}`;
+			if (options.path) cookie += `; Path=${options.path}`;
+			if (options.expires) cookie += `; Expires=${options.expires.toUTCString()}`;
+			if (options.maxAge !== void 0) cookie += `; Max-Age=${options.maxAge}`;
+			if (options.httpOnly) cookie += "; HttpOnly";
+			if (options.secure) cookie += "; Secure";
+			if (options.sameSite) cookie += `; SameSite=${options.sameSite.charAt(0).toUpperCase() + options.sameSite.slice(1)}`;
+		}
+		return cookie;
+	}
+	/**
 	* Extracts and refines input data from the endpoint context.
 	*
 	* @param ctx - The endpoint execution context
@@ -140,14 +205,16 @@ var Endpoint = class Endpoint extends require_Function.Function {
 		]);
 		return input;
 	}
-	handler = (ctx) => {
-		return this.fn({
+	handler = (ctx, response) => {
+		for (const [key, value] of Object.entries(this.defaultHeaders)) response.header(key, value);
+		return this.endpointFn({
 			...this.refineInput(ctx),
 			services: ctx.services,
 			logger: ctx.logger,
 			header: ctx.header,
+			cookie: ctx.cookie,
 			session: ctx.session
-		});
+		}, response);
 	};
 	/**
 	* Type guard to check if an object is an Endpoint instance.
@@ -159,6 +226,12 @@ var Endpoint = class Endpoint extends require_Function.Function {
 		return Boolean(obj && obj.__IS_FUNCTION__ === true && obj.type === require_Construct.ConstructType.Endpoint);
 	}
 	/**
+	* Helper to check if response has metadata
+	*/
+	static hasMetadata(response) {
+		return response !== null && typeof response === "object" && "data" in response && "metadata" in response;
+	}
+	/**
 	* Converts Express-style route params to OpenAPI format.
 	* @returns Route with ':param' converted to '{param}'
 	* @internal
@@ -251,12 +324,57 @@ var Endpoint = class Endpoint extends require_Function.Function {
 		this.description = description;
 		this.tags = tags;
 		this.status = status;
+		this.endpointFn = fn;
 		if (getSession) this.getSession = getSession;
 		if (authorize) this.authorize = authorize;
 		if (rateLimit) this.rateLimit = rateLimit;
 	}
 };
 /**
+* Response builder for fluent API in handlers
+*/
+var ResponseBuilder = class {
+	metadata = {
+		headers: {},
+		cookies: /* @__PURE__ */ new Map()
+	};
+	header(key, value) {
+		this.metadata.headers[key] = value;
+		return this;
+	}
+	cookie(name, value, options) {
+		this.metadata.cookies.set(name, {
+			value,
+			options
+		});
+		return this;
+	}
+	deleteCookie(name, options) {
+		this.metadata.cookies.set(name, {
+			value: "",
+			options: {
+				...options,
+				maxAge: 0,
+				expires: /* @__PURE__ */ new Date(0)
+			}
+		});
+		return this;
+	}
+	status(code) {
+		this.metadata.status = code;
+		return this;
+	}
+	send(data) {
+		return {
+			data,
+			metadata: this.metadata
+		};
+	}
+	getMetadata() {
+		return this.metadata;
+	}
+};
+/**
 * HTTP success status codes that can be returned by endpoints.
 */
 let SuccessStatus = /* @__PURE__ */ function(SuccessStatus$1) {
@@ -282,10 +400,16 @@ Object.defineProperty(exports, 'Endpoint', {
     return Endpoint;
   }
 });
+Object.defineProperty(exports, 'ResponseBuilder', {
+  enumerable: true,
+  get: function () {
+    return ResponseBuilder;
+  }
+});
 Object.defineProperty(exports, 'SuccessStatus', {
   enumerable: true,
   get: function () {
     return SuccessStatus;
   }
 });
-//# sourceMappingURL=Endpoint-D1nnEsBU.cjs.map
+//# sourceMappingURL=Endpoint-BVZJb4OR.cjs.map

package/dist/Endpoint-BVZJb4OR.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"Endpoint-BVZJb4OR.cjs","names":["Function","endpoints: Endpoint<any, any, any, any, any, any>[]","options?: OpenApiSchemaOptions","input: unknown","key: K","body: unknown","status: number","headers: Record<string, string>","key: string","cookieHeader: string | undefined","name: string","value: string","options?: CookieOptions","ctx: EndpointContext<TInput, TServices, TLogger, TSession>","response: ResponseBuilder","obj: any","ConstructType","response: T | ResponseWithMetadata<T>","componentCollector?: ComponentCollector","operation: OpenAPIV3_1.OperationObject","pathParameters: OpenAPIV3_1.ParameterObject[]","queryParameters: OpenAPIV3_1.ParameterObject[]","routeObject: any","options?: Pick<CookieOptions, 'domain' | 'path'>","code: SuccessStatus","data: T"],"sources":["../src/endpoints/Endpoint.ts"],"sourcesContent":["import type { Logger } from '@geekmidas/logger';\nimport type { StandardSchemaV1 } from '@standard-schema/spec';\nimport pick from 'lodash.pick';\nimport set from 'lodash.set';\nimport type { OpenAPIV3_1 } from 'openapi-types';\n\nimport type { Service, ServiceRecord } from '@geekmidas/services';\nimport { ConstructType } from '../Construct';\nimport { Function, type FunctionHandler } from '../functions';\n\nimport type {\n  EventPublisher,\n  ExtractPublisherMessage,\n  MappedEvent,\n} from '@geekmidas/events';\nimport type { RateLimitConfig } from '@geekmidas/rate-limit';\nimport type {\n  InferComposableStandardSchema,\n  InferStandardSchema,\n} from '@geekmidas/schema';\nimport {\n  convertSchemaWithComponents,\n  convertStandardSchemaToJsonSchema,\n} from '@geekmidas/schema/conversion';\nimport {\n  type ComponentCollector,\n  type OpenApiSchemaOptions,\n  buildOpenApiSchema,\n} from '@geekmidas/schema/openapi';\nimport type { HttpMethod, LowerHttpMethod, RemoveUndefined } from '../types';\n\n/**\n * Represents an HTTP endpoint that can handle requests with type-safe input/output validation,\n * dependency injection, session management, and authorization.\n *\n * @template TRoute - The route path string with parameter placeholders (e.g., '/users/:id')\n * @template TMethod - The HTTP method (GET, POST, PUT, DELETE, PATCH)\n * @template TInput - The input schema definition for body, query, and path parameters\n * @template OutSchema - The output schema for response validation\n * @template TServices - Array of service dependencies to inject\n * @template TLogger - The logger instance type\n * @template TSession - The session data type\n *\n * @extends Function - Base function construct for handler execution\n *\n * @example\n * ```typescript\n * const endpoint = new Endpoint({\n *   route: '/users/:id',\n *   method: 'GET',\n *   input: { params: userIdSchema },\n *   output: userSchema,\n *   fn: async ({ params }) => getUserById(params.id)\n * });\n * ```\n */\nexport class Endpoint<\n  TRoute extends string,\n  TMethod extends HttpMethod,\n  TInput extends EndpointSchemas = {},\n  OutSchema extends StandardSchemaV1 | undefined = undefined,\n  TServices extends Service[] = [],\n  TLogger extends Logger = Logger,\n  TSession = unknown,\n  TEventPublisher extends EventPublisher<any> | undefined = undefined,\n  TEventPublisherServiceName extends string = string,\n> extends Function<\n  TInput,\n  TServices,\n  TLogger,\n  OutSchema,\n  FunctionHandler<TInput, TServices, TLogger, OutSchema>,\n  TEventPublisher,\n  TEventPublisherServiceName\n> {\n  operationId?: string;\n  /** The route path pattern with parameter placeholders */\n  route: TRoute;\n  /** The HTTP method for this endpoint */\n  method: TMethod;\n  /** Optional description for OpenAPI documentation */\n  description?: string;\n  /** Optional tags for OpenAPI documentation */\n  tags?: string[];\n  /** The HTTP success status code to return (default: 200) */\n  public readonly status: SuccessStatus;\n  /** Default headers to apply to all responses */\n  public readonly defaultHeaders: Record<string, string> = {};\n  /** Function to extract session data from the request context */\n  public getSession: SessionFn<TServices, TLogger, TSession> = () =>\n    ({}) as TSession;\n  /** Function to determine if the request is authorized */\n  public authorize: AuthorizeFn<TServices, TLogger, TSession> = () => true;\n  /** Optional rate limiting configuration */\n  public rateLimit?: RateLimitConfig;\n  /** The endpoint handler function */\n  private endpointFn!: EndpointHandler<\n    TInput,\n    TServices,\n    TLogger,\n    OutSchema,\n    TSession\n  >;\n\n  /**\n   * Builds a complete OpenAPI 3.1 schema from an array of endpoints.\n   *\n   * @param endpoints - Array of endpoint instances to document\n   * @param options - Optional configuration for OpenAPI generation\n   * @returns OpenAPI 3.1 specification object\n   *\n   * @example\n   * ```typescript\n   * const schema = await Endpoint.buildOpenApiSchema([\n   *   getUserEndpoint,\n   *   createUserEndpoint\n   * ], {\n   *   title: 'User API',\n   *   version: '1.0.0'\n   * });\n   * ```\n   */\n  static async buildOpenApiSchema(\n    endpoints: Endpoint<any, any, any, any, any, any>[],\n    options?: OpenApiSchemaOptions,\n  ) {\n    return buildOpenApiSchema(endpoints, options);\n  }\n\n  /**\n   * Gets the full path including HTTP method and route.\n   * @returns Formatted string like 'GET /users/{id}'\n   */\n  get fullPath() {\n    return `${this.method} ${this._path}` as const;\n  }\n\n  /**\n   * Parses and validates input data for a specific input type (body, query, params).\n   *\n   * @param input - The raw input data to validate\n   * @param key - The input type key ('body', 'query', or 'params')\n   * @returns The validated input data for the specified key\n   * @throws {UnprocessableEntityError} When validation fails\n   */\n  async parseInput<K extends keyof TInput>(\n    input: unknown,\n    key: K,\n  ): Promise<InferComposableStandardSchema<TInput[K]>> {\n    const schema = this.input?.[key];\n    return Endpoint.parseSchema(schema as StandardSchemaV1, input) as Promise<\n      InferComposableStandardSchema<TInput[K]>\n    >;\n  }\n\n  /**\n   * Parses and validates the request body against the body schema.\n   *\n   * @param body - The raw request body to validate\n   * @returns The validated body data\n   * @throws {UnprocessableEntityError} When body validation fails\n   */\n  async parseBody(body: unknown): Promise<InferStandardSchema<TInput['body']>> {\n    return this.parseInput(body, 'body') as Promise<\n      InferStandardSchema<TInput['body']>\n    >;\n  }\n\n  static isSuccessStatus(status: number): boolean {\n    return status >= 200 && status < 300;\n  }\n\n  /**\n   * Creates a case-insensitive header lookup function from a headers object.\n   *\n   * @param headers - Object containing header key-value pairs\n   * @returns Function to retrieve header values by case-insensitive key\n   *\n   * @example\n   * ```typescript\n   * const headerFn = Endpoint.createHeaders({ 'Content-Type': 'application/json' });\n   * headerFn('content-type'); // Returns 'application/json'\n   * ```\n   */\n  static createHeaders(headers: Record<string, string>): HeaderFn {\n    const headerMap = new Map<string, string>();\n    for (const [k, v] of Object.entries(headers)) {\n      const key = k.toLowerCase();\n      headerMap.set(key, v);\n    }\n\n    return function get(key: string): string | undefined {\n      return headerMap.get(key.toLowerCase());\n    };\n  }\n\n  /**\n   * Parses cookie string and creates a cookie lookup function.\n   *\n   * @param cookieHeader - The Cookie header value\n   * @returns Function to retrieve cookie values by name\n   *\n   * @example\n   * ```typescript\n   * const cookieFn = Endpoint.createCookies('session=abc123; theme=dark');\n   * cookieFn('session'); // Returns 'abc123'\n   * cookieFn('theme'); // Returns 'dark'\n   * ```\n   */\n  static createCookies(cookieHeader: string | undefined): CookieFn {\n    const cookieMap = new Map<string, string>();\n\n    if (cookieHeader) {\n      // Parse cookie string: \"name1=value1; name2=value2\"\n      const cookies = cookieHeader.split(';');\n      for (const cookie of cookies) {\n        const [name, ...valueParts] = cookie.trim().split('=');\n        if (name) {\n          const value = valueParts.join('='); // Handle values with = in them\n          cookieMap.set(name, decodeURIComponent(value));\n        }\n      }\n    }\n\n    return function get(name: string): string | undefined {\n      return cookieMap.get(name);\n    };\n  }\n\n  /**\n   * Formats a cookie as a Set-Cookie header string.\n   *\n   * @param name - Cookie name\n   * @param value - Cookie value\n   * @param options - Cookie options (httpOnly, secure, sameSite, etc.)\n   * @returns Formatted Set-Cookie header string\n   *\n   * @example\n   * ```typescript\n   * const header = Endpoint.formatCookieHeader('session', 'abc123', {\n   *   httpOnly: true,\n   *   secure: true,\n   *   sameSite: 'strict',\n   *   maxAge: 3600\n   * });\n   * // Returns: \"session=abc123; Max-Age=3600; HttpOnly; Secure; SameSite=Strict\"\n   * ```\n   */\n  static formatCookieHeader(\n    name: string,\n    value: string,\n    options?: CookieOptions,\n  ): string {\n    let cookie = `${name}=${value}`;\n\n    if (options) {\n      if (options.domain) cookie += `; Domain=${options.domain}`;\n      if (options.path) cookie += `; Path=${options.path}`;\n      if (options.expires)\n        cookie += `; Expires=${options.expires.toUTCString()}`;\n      if (options.maxAge !== undefined) cookie += `; Max-Age=${options.maxAge}`;\n      if (options.httpOnly) cookie += '; HttpOnly';\n      if (options.secure) cookie += '; Secure';\n      if (options.sameSite) {\n        cookie += `; SameSite=${options.sameSite.charAt(0).toUpperCase() + options.sameSite.slice(1)}`;\n      }\n    }\n\n    return cookie;\n  }\n\n  /**\n   * Extracts and refines input data from the endpoint context.\n   *\n   * @param ctx - The endpoint execution context\n   * @returns Object containing only the input data (body, query, params)\n   * @internal\n   */\n  refineInput(\n    ctx: EndpointContext<TInput, TServices, TLogger, TSession>,\n  ): InferComposableStandardSchema<TInput> {\n    const input = pick(ctx, [\n      'body',\n      'query',\n      'params',\n    ]) as InferComposableStandardSchema<TInput>;\n\n    return input;\n  }\n\n  handler = (\n    ctx: EndpointContext<TInput, TServices, TLogger, TSession>,\n    response: ResponseBuilder,\n  ): OutSchema extends StandardSchemaV1\n    ?\n        | InferStandardSchema<OutSchema>\n        | ResponseWithMetadata<InferStandardSchema<OutSchema>>\n        | Promise<InferStandardSchema<OutSchema>>\n        | Promise<ResponseWithMetadata<InferStandardSchema<OutSchema>>>\n    :\n        | any\n        | ResponseWithMetadata<any>\n        | Promise<any>\n        | Promise<ResponseWithMetadata<any>> => {\n    // Apply default headers to response builder\n    for (const [key, value] of Object.entries(this.defaultHeaders)) {\n      response.header(key, value);\n    }\n\n    return this.endpointFn(\n      {\n        ...this.refineInput(ctx),\n        services: ctx.services,\n        logger: ctx.logger,\n        header: ctx.header,\n        cookie: ctx.cookie,\n        session: ctx.session,\n      } as EndpointContext<TInput, TServices, TLogger, TSession>,\n      response,\n    );\n  };\n\n  /**\n   * Type guard to check if an object is an Endpoint instance.\n   *\n   * @param obj - The object to check\n   * @returns True if the object is an Endpoint\n   */\n  static isEndpoint(obj: any): obj is Endpoint<any, any, any, any> {\n    return Boolean(\n      obj &&\n        (obj as Function).__IS_FUNCTION__ === true &&\n        obj.type === ConstructType.Endpoint,\n    );\n  }\n\n  /**\n   * Helper to check if response has metadata\n   */\n  static hasMetadata<T>(\n    response: T | ResponseWithMetadata<T>,\n  ): response is ResponseWithMetadata<T> {\n    return (\n      response !== null &&\n      typeof response === 'object' &&\n      'data' in response &&\n      'metadata' in response\n    );\n  }\n\n  /**\n   * Converts Express-style route params to OpenAPI format.\n   * @returns Route with ':param' converted to '{param}'\n   * @internal\n   */\n  get _path() {\n    return this.route.replace(/:(\\w+)/g, '{$1}') as ConvertRouteParams<TRoute>;\n  }\n\n  /**\n   * Generates OpenAPI 3.1 schema for this endpoint.\n   *\n   * @returns OpenAPI route definition with operation details\n   */\n  async toOpenApi3Route(\n    componentCollector?: ComponentCollector,\n  ): Promise<EndpointOpenApiSchema<TRoute, TMethod>> {\n    const operation: OpenAPIV3_1.OperationObject = {\n      operationId: this.operationId,\n      ...(this.description && { description: this.description }),\n      ...(this.tags && this.tags.length > 0 && { tags: this.tags }),\n      responses: {\n        '200': {\n          description: 'Successful response',\n        } as OpenAPIV3_1.ResponseObject,\n      },\n    };\n\n    // Add response schema\n    if (this.outputSchema) {\n      const responseSchema = await convertSchemaWithComponents(\n        this.outputSchema,\n        componentCollector,\n      );\n      if (responseSchema) {\n        set(\n          operation,\n          ['responses', '200', 'content', 'application/json', 'schema'],\n          responseSchema,\n        );\n      }\n    }\n\n    // Separate path and query parameters\n    const pathParameters: OpenAPIV3_1.ParameterObject[] = [];\n    const queryParameters: OpenAPIV3_1.ParameterObject[] = [];\n\n    // Since the EndpointBuilder doesn't have body/search/params methods yet,\n    // and the input is a composite type, we need to check if input exists\n    // and has the expected shape\n    if (this.input && typeof this.input === 'object') {\n      // Add request body for methods that support it\n      if (\n        ['POST', 'PUT', 'PATCH'].includes(this.method) &&\n        'body' in this.input &&\n        this.input.body\n      ) {\n        const bodySchema = await convertSchemaWithComponents(\n          this.input.body as StandardSchemaV1,\n          componentCollector,\n        );\n        if (bodySchema) {\n          set(operation, ['requestBody'], {\n            required: true,\n            content: {\n              'application/json': {\n                schema: bodySchema,\n              },\n            },\n          });\n        }\n      }\n\n      // Add path parameters\n      if ('params' in this.input && this.input.params) {\n        const paramsSchema = await convertStandardSchemaToJsonSchema(\n          this.input.params as StandardSchemaV1,\n        );\n        if (\n          paramsSchema &&\n          paramsSchema.type === 'object' &&\n          paramsSchema.properties\n        ) {\n          for (const [name, schema] of Object.entries(\n            paramsSchema.properties,\n          )) {\n            pathParameters.push({\n              name,\n              in: 'path',\n              required: paramsSchema.required?.includes(name) ?? true,\n              schema: schema as any,\n            });\n          }\n        }\n      }\n\n      // Add query parameters\n      if ('query' in this.input && this.input.query) {\n        const querySchema = await convertStandardSchemaToJsonSchema(\n          this.input.query,\n        );\n        if (\n          querySchema &&\n          querySchema.type === 'object' &&\n          querySchema.properties\n        ) {\n          for (const [name, schema] of Object.entries(querySchema.properties)) {\n            queryParameters.push({\n              name,\n              in: 'query',\n              required: querySchema.required?.includes(name) ?? false,\n              schema: schema as any,\n            });\n          }\n        }\n      }\n    }\n\n    // Only add query parameters to the operation\n    if (queryParameters.length > 0) {\n      operation.parameters = queryParameters;\n    }\n\n    // Build the route object with path parameters at the route level\n    const routeObject: any = {};\n    if (pathParameters.length > 0) {\n      routeObject.parameters = pathParameters;\n    }\n    routeObject[this.method.toLowerCase()] = operation;\n\n    return {\n      [this._path]: routeObject,\n    } as EndpointOpenApiSchema<TRoute, TMethod>;\n  }\n\n  /**\n   * Creates a new Endpoint instance.\n   *\n   * @param options - Configuration options for the endpoint\n   * @param options.fn - The handler function to execute\n   * @param options.method - HTTP method\n   * @param options.route - Route path with parameter placeholders\n   * @param options.description - Optional description for documentation\n   * @param options.input - Input schemas for validation\n   * @param options.logger - Logger instance\n   * @param options.output - Output schema for response validation\n   * @param options.services - Service dependencies\n   * @param options.timeout - Execution timeout in milliseconds\n   * @param options.getSession - Session extraction function\n   * @param options.authorize - Authorization check function\n   * @param options.status - Success HTTP status code (default: 200)\n   */\n  constructor({\n    fn,\n    method,\n    route,\n    description,\n    tags,\n    input,\n    logger,\n    output: outputSchema,\n    services,\n    timeout,\n    getSession,\n    authorize,\n    rateLimit,\n    status = SuccessStatus.OK,\n    publisherService,\n    events,\n  }: EndpointOptions<\n    TRoute,\n    TMethod,\n    TInput,\n    OutSchema,\n    TServices,\n    TLogger,\n    TSession,\n    OutSchema,\n    TEventPublisher,\n    TEventPublisherServiceName\n  >) {\n    super(\n      fn as unknown as FunctionHandler<TInput, TServices, TLogger, OutSchema>,\n      timeout,\n      ConstructType.Endpoint,\n      input,\n      outputSchema,\n      services,\n      logger,\n      publisherService,\n      events,\n    );\n\n    this.route = route;\n    this.method = method;\n    this.description = description;\n    this.tags = tags;\n    this.status = status;\n    this.endpointFn = fn;\n\n    if (getSession) {\n      this.getSession = getSession;\n    }\n\n    if (authorize) {\n      this.authorize = authorize;\n    }\n\n    if (rateLimit) {\n      this.rateLimit = rateLimit;\n    }\n  }\n}\n\n/**\n * Defines the input schema structure for an endpoint.\n *\n * @template TBody - Schema for request body validation\n * @template TSearch - Schema for query string validation\n * @template TParams - Schema for URL path parameters validation\n *\n * @example\n * ```typescript\n * type UserInput = EndpointInput<\n *   typeof createUserBodySchema,\n *   typeof userQuerySchema,\n *   typeof userParamsSchema\n * >;\n * ```\n */\nexport type EndpointInput<\n  TBody extends StandardSchemaV1 | undefined = undefined,\n  TSearch extends StandardSchemaV1 | undefined = undefined,\n  TParams extends StandardSchemaV1 | undefined = undefined,\n> = RemoveUndefined<{\n  body: TBody;\n  search: TSearch;\n  params: TParams;\n}>;\n\n/**\n * Configuration options for creating an Endpoint instance.\n *\n * @template TRoute - The route path string\n * @template TMethod - The HTTP method\n * @template TInput - Input schema definitions\n * @template TOutput - Output schema definition\n * @template TServices - Service dependencies array\n * @template TLogger - Logger type\n * @template TSession - Session data type\n */\nexport interface EndpointOptions<\n  TRoute extends string,\n  TMethod extends HttpMethod,\n  TInput extends EndpointSchemas = {},\n  TOutput extends StandardSchemaV1 | undefined = undefined,\n  TServices extends Service[] = [],\n  TLogger extends Logger = Logger,\n  TSession = unknown,\n  OutSchema extends StandardSchemaV1 | undefined = undefined,\n  TEventPublisher extends EventPublisher<any> | undefined = undefined,\n  TEventPublisherServiceName extends string = string,\n> {\n  /** The route path with parameter placeholders */\n  route: TRoute;\n  /** The HTTP method for this endpoint */\n  method: TMethod;\n  /** The handler function that implements the endpoint logic */\n  fn: EndpointHandler<TInput, TServices, TLogger, TOutput, TSession>;\n  /** Optional authorization check function */\n  authorize: AuthorizeFn<TServices, TLogger, TSession> | undefined;\n  /** Optional description for documentation */\n  description: string | undefined;\n  /** Optional tags for OpenAPI documentation */\n  tags?: string[];\n  /** Optional execution timeout in milliseconds */\n  timeout: number | undefined;\n  /** Input validation schemas */\n  input: TInput | undefined;\n  /** Output validation schema */\n  output: TOutput | undefined;\n  /** Service dependencies to inject */\n  services: TServices;\n  /** Logger instance */\n  logger: TLogger;\n  /** Optional session extraction function */\n  getSession: SessionFn<TServices, TLogger, TSession> | undefined;\n  /** Optional rate limiting configuration */\n  rateLimit?: RateLimitConfig;\n  /** Success HTTP status code */\n  status: SuccessStatus | undefined;\n  /**\n   * Event publisher service for publishing events from this endpoint\n   */\n  publisherService?: Service<TEventPublisherServiceName, TEventPublisher>;\n\n  events?: MappedEvent<TEventPublisher, OutSchema>[];\n}\n\n/**\n * Defines the possible input schema types for an endpoint.\n * Each property represents a different part of the HTTP request.\n */\nexport type EndpointSchemas = Partial<{\n  /** Schema for URL path parameters (e.g., /users/:id) */\n  params: StandardSchemaV1;\n  /** Schema for query string parameters */\n  query: StandardSchemaV1;\n  /** Schema for request body (POST, PUT, PATCH) */\n  body: StandardSchemaV1;\n}>;\n\nexport type AuthorizeContext<\n  TServices extends Service[] = [],\n  TLogger extends Logger = Logger,\n  TSession = unknown,\n> = {\n  services: ServiceRecord<TServices>;\n  logger: TLogger;\n  header: HeaderFn;\n  cookie: CookieFn;\n  session: TSession;\n};\n/**\n * Function type for endpoint authorization checks.\n *\n * @template TServices - Available service dependencies\n * @template TLogger - Logger type\n * @template TSession - Session data type\n *\n * @param ctx - Context containing services, logger, headers, and session\n * @returns Boolean indicating if the request is authorized\n *\n * @example\n * ```typescript\n * const authorize: AuthorizeFn = ({ session }) => {\n *   return session.userId !== undefined;\n * };\n * ```\n */\nexport type AuthorizeFn<\n  TServices extends Service[] = [],\n  TLogger extends Logger = Logger,\n  TSession = unknown,\n> = (\n  ctx: AuthorizeContext<TServices, TLogger, TSession>,\n) => Promise<boolean> | boolean;\n\nexport type SessionContext<\n  TServices extends Service[] = [],\n  TLogger extends Logger = Logger,\n> = {\n  services: ServiceRecord<TServices>;\n  logger: TLogger;\n  header: HeaderFn;\n  cookie: CookieFn;\n};\n/**\n * Function type for extracting session data from a request.\n *\n * @template TServices - Available service dependencies\n * @template TLogger - Logger type\n * @template TSession - Session data type to extract\n *\n * @param ctx - Context containing services, logger, and headers\n * @returns The extracted session data\n *\n * @example\n * ```typescript\n * const getSession: SessionFn<Services, Logger, UserSession> = async ({ header, services }) => {\n *   const token = header('authorization');\n *   return await services.auth.verifyToken(token);\n * };\n * ```\n */\nexport type SessionFn<\n  TServices extends Service[] = [],\n  TLogger extends Logger = Logger,\n  TSession = unknown,\n> = (ctx: SessionContext<TServices, TLogger>) => Promise<TSession> | TSession;\n\n/**\n * Utility type that converts Express-style route parameters to OpenAPI format.\n * Transforms ':param' syntax to '{param}' syntax.\n *\n * @template T - The route string to convert\n *\n * @example\n * ```typescript\n * type Route1 = ConvertRouteParams<'/users/:id'>; // '/users/{id}'\n * type Route2 = ConvertRouteParams<'/users/:userId/posts/:postId'>; // '/users/{userId}/posts/{postId}'\n * ```\n */\nexport type ConvertRouteParams<T extends string> =\n  T extends `${infer Start}:${infer Param}/${infer Rest}`\n    ? `${Start}{${Param}}/${ConvertRouteParams<Rest>}`\n    : T extends `${infer Start}:${infer Param}`\n      ? `${Start}{${Param}}`\n      : T;\n\n/**\n * Type representing the OpenAPI schema structure for an endpoint.\n *\n * @template TRoute - The route path\n * @template TMethod - The HTTP method\n *\n * @example\n * ```typescript\n * type Schema = EndpointOpenApiSchema<'/users/:id', 'GET'>;\n * // Results in: { '/users/{id}': { get: OperationObject, parameters?: ParameterObject[] } }\n * ```\n */\nexport type EndpointOpenApiSchema<\n  TRoute extends string,\n  TMethod extends HttpMethod,\n> = {\n  [key in ConvertRouteParams<TRoute>]: {\n    [key in LowerHttpMethod<TMethod>]: OpenAPIV3_1.OperationObject<{}>;\n  } & {\n    parameters?: OpenAPIV3_1.ParameterObject[];\n  };\n};\n\nexport type SingleHeaderFn = (key: string) => string | undefined;\nexport type MultiHeaderFn = () => EndpointHeaders;\n/**\n * Type representing HTTP headers as a Map.\n */\nexport type EndpointHeaders = Map<string, string>;\n\n/**\n * Function type for retrieving HTTP header values.\n *\n * @param key - The header name (case-insensitive)\n * @returns The header value or undefined if not found\n */\nexport type HeaderFn = SingleHeaderFn;\n\n/**\n * Function type for retrieving cookie values.\n *\n * @param name - The cookie name\n * @returns The cookie value or undefined if not found\n *\n * @example\n * ```typescript\n * const sessionId = cookie('session');\n * ```\n */\nexport type CookieFn = (name: string) => string | undefined;\n\n/**\n * Cookie options matching standard Set-Cookie attributes\n */\nexport interface CookieOptions {\n  domain?: string;\n  path?: string;\n  expires?: Date;\n  maxAge?: number;\n  httpOnly?: boolean;\n  secure?: boolean;\n  sameSite?: 'strict' | 'lax' | 'none';\n}\n\n/**\n * Response metadata that handlers can set\n */\nexport interface ResponseMetadata {\n  headers?: Record<string, string>;\n  cookies?: Map<string, { value: string; options?: CookieOptions }>;\n  status?: SuccessStatus;\n}\n\n/**\n * Return type for handlers that want to set response metadata\n */\nexport interface ResponseWithMetadata<T> {\n  data: T;\n  metadata: ResponseMetadata;\n}\n\n/**\n * Response builder for fluent API in handlers\n */\nexport class ResponseBuilder {\n  private metadata: ResponseMetadata = {\n    headers: {},\n    cookies: new Map(),\n  };\n\n  header(key: string, value: string): this {\n    this.metadata.headers![key] = value;\n    return this;\n  }\n\n  cookie(name: string, value: string, options?: CookieOptions): this {\n    this.metadata.cookies!.set(name, { value, options });\n    return this;\n  }\n\n  deleteCookie(\n    name: string,\n    options?: Pick<CookieOptions, 'domain' | 'path'>,\n  ): this {\n    this.metadata.cookies!.set(name, {\n      value: '',\n      options: { ...options, maxAge: 0, expires: new Date(0) },\n    });\n    return this;\n  }\n\n  status(code: SuccessStatus): this {\n    this.metadata.status = code;\n    return this;\n  }\n\n  send<T>(data: T): ResponseWithMetadata<T> {\n    return { data, metadata: this.metadata };\n  }\n\n  getMetadata(): ResponseMetadata {\n    return this.metadata;\n  }\n}\n\n/**\n * The execution context provided to endpoint handlers.\n * Contains all parsed input data, services, logger, headers, cookies, and session.\n *\n * @template Input - The input schemas (body, query, params)\n * @template TServices - Available service dependencies\n * @template TLogger - Logger type\n * @template TSession - Session data type\n */\nexport type EndpointContext<\n  Input extends EndpointSchemas | undefined = undefined,\n  TServices extends Service[] = [],\n  TLogger extends Logger = Logger,\n  TSession = unknown,\n> = {\n  /** Injected service instances */\n  services: ServiceRecord<TServices>;\n  /** Logger instance for this request */\n  logger: TLogger;\n  /** Function to retrieve request headers */\n  header: HeaderFn;\n  /** Function to retrieve request cookies */\n  cookie: CookieFn;\n  /** Session data extracted by getSession */\n  session: TSession;\n} & InferComposableStandardSchema<Input>;\n\n/**\n * Handler function type for endpoint implementations.\n *\n * @template TInput - Input schemas for validation\n * @template TServices - Available service dependencies\n * @template TLogger - Logger type\n * @template OutSchema - Output schema for response validation\n * @template TSession - Session data type\n *\n * @param ctx - The endpoint execution context\n * @param response - Response builder for setting cookies, headers, and status\n * @returns The response data (validated if OutSchema is provided) or ResponseWithMetadata\n *\n * @example\n * ```typescript\n * // Simple response\n * const handler: EndpointHandler<Input, [UserService], Logger, UserSchema> =\n *   async ({ params, services }) => {\n *     return await services.users.findById(params.id);\n *   };\n *\n * // With response builder\n * const handler: EndpointHandler<Input, [UserService], Logger, UserSchema> =\n *   async ({ params, services }, response) => {\n *     const user = await services.users.findById(params.id);\n *     return response.header('X-User-Id', user.id).send(user);\n *   };\n * ```\n */\nexport type EndpointHandler<\n  TInput extends EndpointSchemas | undefined = undefined,\n  TServices extends Service[] = [],\n  TLogger extends Logger = Logger,\n  OutSchema extends StandardSchemaV1 | undefined = undefined,\n  TSession = unknown,\n> = (\n  ctx: EndpointContext<TInput, TServices, TLogger, TSession>,\n  response: ResponseBuilder,\n) => OutSchema extends StandardSchemaV1\n  ?\n      | InferStandardSchema<OutSchema>\n      | ResponseWithMetadata<InferStandardSchema<OutSchema>>\n      | Promise<InferStandardSchema<OutSchema>>\n      | Promise<ResponseWithMetadata<InferStandardSchema<OutSchema>>>\n  :\n      | unknown\n      | ResponseWithMetadata<unknown>\n      | Promise<unknown>\n      | Promise<ResponseWithMetadata<unknown>>;\n\n/**\n * HTTP success status codes that can be returned by endpoints.\n */\nexport enum SuccessStatus {\n  /** Standard response for successful HTTP requests */\n  OK = 200,\n  /** Request has been fulfilled and resulted in a new resource being created */\n  Created = 201,\n  /** Request has been accepted for processing, but processing is not complete */\n  Accepted = 202,\n  /** Server successfully processed the request but is not returning any content */\n  NoContent = 204,\n  /** Server successfully processed the request and is not returning any content, client should reset the document view */\n  ResetContent = 205,\n  /** Server is delivering only part of the resource due to a range header */\n  PartialContent = 206,\n}\n\nexport type EndpointOutput<T> = T extends Endpoint<\n  any,\n  any,\n  any,\n  infer OutSchema,\n  any,\n  any,\n  any,\n  any\n>\n  ? InferStandardSchema<OutSchema>\n  : never;\n\nexport type EndpointEvent<T> = T extends Endpoint<\n  any,\n  any,\n  any,\n  any,\n  any,\n  any,\n  any,\n  infer TEventPublisher\n>\n  ? ExtractPublisherMessage<TEventPublisher>\n  : never;\n"],"mappings":"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"}

package/dist/{Endpoint-DYUjJdEs.d.mts → Endpoint-C7jPJzAH.d.mts}

@@ -48,12 +48,16 @@ declare class Endpoint<TRoute extends string, TMethod extends HttpMethod, TInput
   tags?: string[];
   /** The HTTP success status code to return (default: 200) */
   readonly status: SuccessStatus;
+  /** Default headers to apply to all responses */
+  readonly defaultHeaders: Record<string, string>;
   /** Function to extract session data from the request context */
   getSession: SessionFn<TServices, TLogger, TSession>;
   /** Function to determine if the request is authorized */
   authorize: AuthorizeFn<TServices, TLogger, TSession>;
   /** Optional rate limiting configuration */
   rateLimit?: RateLimitConfig;
+  /** The endpoint handler function */
+  private endpointFn;
   /**
    * Builds a complete OpenAPI 3.1 schema from an array of endpoints.
    *
@@ -109,6 +113,40 @@ declare class Endpoint<TRoute extends string, TMethod extends HttpMethod, TInput
    * ```
    */
   static createHeaders(headers: Record<string, string>): HeaderFn;
+  /**
+   * Parses cookie string and creates a cookie lookup function.
+   *
+   * @param cookieHeader - The Cookie header value
+   * @returns Function to retrieve cookie values by name
+   *
+   * @example
+   * ```typescript
+   * const cookieFn = Endpoint.createCookies('session=abc123; theme=dark');
+   * cookieFn('session'); // Returns 'abc123'
+   * cookieFn('theme'); // Returns 'dark'
+   * ```
+   */
+  static createCookies(cookieHeader: string | undefined): CookieFn;
+  /**
+   * Formats a cookie as a Set-Cookie header string.
+   *
+   * @param name - Cookie name
+   * @param value - Cookie value
+   * @param options - Cookie options (httpOnly, secure, sameSite, etc.)
+   * @returns Formatted Set-Cookie header string
+   *
+   * @example
+   * ```typescript
+   * const header = Endpoint.formatCookieHeader('session', 'abc123', {
+   *   httpOnly: true,
+   *   secure: true,
+   *   sameSite: 'strict',
+   *   maxAge: 3600
+   * });
+   * // Returns: "session=abc123; Max-Age=3600; HttpOnly; Secure; SameSite=Strict"
+   * ```
+   */
+  static formatCookieHeader(name: string, value: string, options?: CookieOptions): string;
   /**
    * Extracts and refines input data from the endpoint context.
    *
@@ -117,7 +155,7 @@ declare class Endpoint<TRoute extends string, TMethod extends HttpMethod, TInput
    * @internal
    */
   refineInput(ctx: EndpointContext<TInput, TServices, TLogger, TSession>): InferComposableStandardSchema<TInput>;
-  handler: EndpointHandler<TInput, TServices, TLogger, OutSchema, TSession>;
+  handler: (ctx: EndpointContext<TInput, TServices, TLogger, TSession>, response: ResponseBuilder) => OutSchema extends StandardSchemaV1 ? InferStandardSchema<OutSchema> | ResponseWithMetadata<InferStandardSchema<OutSchema>> | Promise<InferStandardSchema<OutSchema>> | Promise<ResponseWithMetadata<InferStandardSchema<OutSchema>>> : any | ResponseWithMetadata<any> | Promise<any> | Promise<ResponseWithMetadata<any>>;
   /**
    * Type guard to check if an object is an Endpoint instance.
    *
@@ -125,6 +163,10 @@ declare class Endpoint<TRoute extends string, TMethod extends HttpMethod, TInput
    * @returns True if the object is an Endpoint
    */
   static isEndpoint(obj: any): obj is Endpoint<any, any, any, any>;
+  /**
+   * Helper to check if response has metadata
+   */
+  static hasMetadata<T>(response: T | ResponseWithMetadata<T>): response is ResponseWithMetadata<T>;
   /**
    * Converts Express-style route params to OpenAPI format.
    * @returns Route with ':param' converted to '{param}'
@@ -256,6 +298,7 @@ type AuthorizeContext<TServices extends Service[] = [], TLogger extends Logger =
   services: ServiceRecord<TServices>;
   logger: TLogger;
   header: HeaderFn;
+  cookie: CookieFn;
   session: TSession;
 };
 /**
@@ -280,6 +323,7 @@ type SessionContext<TServices extends Service[] = [], TLogger extends Logger = L
   services: ServiceRecord<TServices>;
   logger: TLogger;
   header: HeaderFn;
+  cookie: CookieFn;
 };
 /**
  * Function type for extracting session data from a request.
@@ -341,9 +385,63 @@ type EndpointHeaders = Map<string, string>;
  * @returns The header value or undefined if not found
  */
 type HeaderFn = SingleHeaderFn;
+/**
+ * Function type for retrieving cookie values.
+ *
+ * @param name - The cookie name
+ * @returns The cookie value or undefined if not found
+ *
+ * @example
+ * ```typescript
+ * const sessionId = cookie('session');
+ * ```
+ */
+type CookieFn = (name: string) => string | undefined;
+/**
+ * Cookie options matching standard Set-Cookie attributes
+ */
+interface CookieOptions {
+  domain?: string;
+  path?: string;
+  expires?: Date;
+  maxAge?: number;
+  httpOnly?: boolean;
+  secure?: boolean;
+  sameSite?: 'strict' | 'lax' | 'none';
+}
+/**
+ * Response metadata that handlers can set
+ */
+interface ResponseMetadata {
+  headers?: Record<string, string>;
+  cookies?: Map<string, {
+    value: string;
+    options?: CookieOptions;
+  }>;
+  status?: SuccessStatus;
+}
+/**
+ * Return type for handlers that want to set response metadata
+ */
+interface ResponseWithMetadata<T> {
+  data: T;
+  metadata: ResponseMetadata;
+}
+/**
+ * Response builder for fluent API in handlers
+ */
+declare class ResponseBuilder {
+  private metadata;
+  header(key: string, value: string): this;
+  cookie(name: string, value: string, options?: CookieOptions): this;
+  deleteCookie(name: string, options?: Pick<CookieOptions, 'domain' | 'path'>): this;
+  status(code: SuccessStatus): this;
+  send<T>(data: T): ResponseWithMetadata<T>;
+  getMetadata(): ResponseMetadata;
+}
 /**
  * The execution context provided to endpoint handlers.
- * Contains all parsed input data, services, logger, headers, and session.
+ * Contains all parsed input data, services, logger, headers, cookies, and session.
  *
  * @template Input - The input schemas (body, query, params)
  * @template TServices - Available service dependencies
@@ -357,6 +455,8 @@ type EndpointContext<Input extends EndpointSchemas | undefined = undefined, TSer
   logger: TLogger;
   /** Function to retrieve request headers */
   header: HeaderFn;
+  /** Function to retrieve request cookies */
+  cookie: CookieFn;
   /** Session data extracted by getSession */
   session: TSession;
 } & InferComposableStandardSchema<Input>;
@@ -370,17 +470,26 @@ type EndpointContext<Input extends EndpointSchemas | undefined = undefined, TSer
  * @template TSession - Session data type
  *
  * @param ctx - The endpoint execution context
- * @returns The response data (validated if OutSchema is provided)
+ * @param response - Response builder for setting cookies, headers, and status
+ * @returns The response data (validated if OutSchema is provided) or ResponseWithMetadata
  *
  * @example
  * ```typescript
+ * // Simple response
  * const handler: EndpointHandler<Input, [UserService], Logger, UserSchema> =
  *   async ({ params, services }) => {
  *     return await services.users.findById(params.id);
  *   };
+ *
+ * // With response builder
+ * const handler: EndpointHandler<Input, [UserService], Logger, UserSchema> =
+ *   async ({ params, services }, response) => {
+ *     const user = await services.users.findById(params.id);
+ *     return response.header('X-User-Id', user.id).send(user);
+ *   };
  * ```
  */
-type EndpointHandler<TInput extends EndpointSchemas | undefined = undefined, TServices extends Service[] = [], TLogger extends Logger = Logger, OutSchema extends StandardSchemaV1 | undefined = undefined, TSession = unknown> = (ctx: EndpointContext<TInput, TServices, TLogger, TSession>) => OutSchema extends StandardSchemaV1 ? InferStandardSchema<OutSchema> | Promise<InferStandardSchema<OutSchema>> : any | Promise<any>;
+type EndpointHandler<TInput extends EndpointSchemas | undefined = undefined, TServices extends Service[] = [], TLogger extends Logger = Logger, OutSchema extends StandardSchemaV1 | undefined = undefined, TSession = unknown> = (ctx: EndpointContext<TInput, TServices, TLogger, TSession>, response: ResponseBuilder) => OutSchema extends StandardSchemaV1 ? InferStandardSchema<OutSchema> | ResponseWithMetadata<InferStandardSchema<OutSchema>> | Promise<InferStandardSchema<OutSchema>> | Promise<ResponseWithMetadata<InferStandardSchema<OutSchema>>> : unknown | ResponseWithMetadata<unknown> | Promise<unknown> | Promise<ResponseWithMetadata<unknown>>;
 /**
  * HTTP success status codes that can be returned by endpoints.
  */
@@ -401,5 +510,5 @@ declare enum SuccessStatus {
 type EndpointOutput<T> = T extends Endpoint<any, any, any, infer OutSchema, any, any, any, any> ? InferStandardSchema<OutSchema> : never;
 type EndpointEvent<T> = T extends Endpoint<any, any, any, any, any, any, any, infer TEventPublisher> ? ExtractPublisherMessage<TEventPublisher> : never;
 //#endregion
-export { AuthorizeContext, AuthorizeFn, ConvertRouteParams, Endpoint, EndpointContext, EndpointEvent, EndpointHandler, EndpointHeaders, EndpointInput, EndpointOpenApiSchema, EndpointOptions, EndpointOutput, EndpointSchemas, HeaderFn, MultiHeaderFn, SessionContext, SessionFn, SingleHeaderFn, SuccessStatus };
-//# sourceMappingURL=Endpoint-DYUjJdEs.d.mts.map
+export { AuthorizeContext, AuthorizeFn, ConvertRouteParams, CookieFn, CookieOptions, Endpoint, EndpointContext, EndpointEvent, EndpointHandler, EndpointHeaders, EndpointInput, EndpointOpenApiSchema, EndpointOptions, EndpointOutput, EndpointSchemas, HeaderFn, MultiHeaderFn, ResponseBuilder, ResponseMetadata, ResponseWithMetadata, SessionContext, SessionFn, SingleHeaderFn, SuccessStatus };
+//# sourceMappingURL=Endpoint-C7jPJzAH.d.mts.map

package/dist/{Endpoint-DNlmybXV.mjs → Endpoint-DVEmKo6G.mjs}

@@ -43,12 +43,16 @@ var Endpoint = class Endpoint extends Function {
 	tags;
 	/** The HTTP success status code to return (default: 200) */
 	status;
+	/** Default headers to apply to all responses */
+	defaultHeaders = {};
 	/** Function to extract session data from the request context */
 	getSession = () => ({});
 	/** Function to determine if the request is authorized */
 	authorize = () => true;
 	/** Optional rate limiting configuration */
 	rateLimit;
+	/** The endpoint handler function */
+	endpointFn;
 	/**
 	* Builds a complete OpenAPI 3.1 schema from an array of endpoints.
 	*
@@ -125,6 +129,67 @@ var Endpoint = class Endpoint extends Function {
 		};
 	}
 	/**
+	* Parses cookie string and creates a cookie lookup function.
+	*
+	* @param cookieHeader - The Cookie header value
+	* @returns Function to retrieve cookie values by name
+	*
+	* @example
+	* ```typescript
+	* const cookieFn = Endpoint.createCookies('session=abc123; theme=dark');
+	* cookieFn('session'); // Returns 'abc123'
+	* cookieFn('theme'); // Returns 'dark'
+	* ```
+	*/
+	static createCookies(cookieHeader) {
+		const cookieMap = /* @__PURE__ */ new Map();
+		if (cookieHeader) {
+			const cookies = cookieHeader.split(";");
+			for (const cookie of cookies) {
+				const [name, ...valueParts] = cookie.trim().split("=");
+				if (name) {
+					const value = valueParts.join("=");
+					cookieMap.set(name, decodeURIComponent(value));
+				}
+			}
+		}
+		return function get(name) {
+			return cookieMap.get(name);
+		};
+	}
+	/**
+	* Formats a cookie as a Set-Cookie header string.
+	*
+	* @param name - Cookie name
+	* @param value - Cookie value
+	* @param options - Cookie options (httpOnly, secure, sameSite, etc.)
+	* @returns Formatted Set-Cookie header string
+	*
+	* @example
+	* ```typescript
+	* const header = Endpoint.formatCookieHeader('session', 'abc123', {
+	*   httpOnly: true,
+	*   secure: true,
+	*   sameSite: 'strict',
+	*   maxAge: 3600
+	* });
+	* // Returns: "session=abc123; Max-Age=3600; HttpOnly; Secure; SameSite=Strict"
+	* ```
+	*/
+	static formatCookieHeader(name, value, options) {
+		let cookie = `${name}=${value}`;
+		if (options) {
+			if (options.domain) cookie += `; Domain=${options.domain}`;
+			if (options.path) cookie += `; Path=${options.path}`;
+			if (options.expires) cookie += `; Expires=${options.expires.toUTCString()}`;
+			if (options.maxAge !== void 0) cookie += `; Max-Age=${options.maxAge}`;
+			if (options.httpOnly) cookie += "; HttpOnly";
+			if (options.secure) cookie += "; Secure";
+			if (options.sameSite) cookie += `; SameSite=${options.sameSite.charAt(0).toUpperCase() + options.sameSite.slice(1)}`;
+		}
+		return cookie;
+	}
+	/**
 	* Extracts and refines input data from the endpoint context.
 	*
 	* @param ctx - The endpoint execution context
@@ -139,14 +204,16 @@ var Endpoint = class Endpoint extends Function {
 		]);
 		return input;
 	}
-	handler = (ctx) => {
-		return this.fn({
+	handler = (ctx, response) => {
+		for (const [key, value] of Object.entries(this.defaultHeaders)) response.header(key, value);
+		return this.endpointFn({
 			...this.refineInput(ctx),
 			services: ctx.services,
 			logger: ctx.logger,
 			header: ctx.header,
+			cookie: ctx.cookie,
 			session: ctx.session
-		});
+		}, response);
 	};
 	/**
 	* Type guard to check if an object is an Endpoint instance.
@@ -158,6 +225,12 @@ var Endpoint = class Endpoint extends Function {
 		return Boolean(obj && obj.__IS_FUNCTION__ === true && obj.type === ConstructType.Endpoint);
 	}
 	/**
+	* Helper to check if response has metadata
+	*/
+	static hasMetadata(response) {
+		return response !== null && typeof response === "object" && "data" in response && "metadata" in response;
+	}
+	/**
 	* Converts Express-style route params to OpenAPI format.
 	* @returns Route with ':param' converted to '{param}'
 	* @internal
@@ -250,12 +323,57 @@ var Endpoint = class Endpoint extends Function {
 		this.description = description;
 		this.tags = tags;
 		this.status = status;
+		this.endpointFn = fn;
 		if (getSession) this.getSession = getSession;
 		if (authorize) this.authorize = authorize;
 		if (rateLimit) this.rateLimit = rateLimit;
 	}
 };
 /**
+* Response builder for fluent API in handlers
+*/
+var ResponseBuilder = class {
+	metadata = {
+		headers: {},
+		cookies: /* @__PURE__ */ new Map()
+	};
+	header(key, value) {
+		this.metadata.headers[key] = value;
+		return this;
+	}
+	cookie(name, value, options) {
+		this.metadata.cookies.set(name, {
+			value,
+			options
+		});
+		return this;
+	}
+	deleteCookie(name, options) {
+		this.metadata.cookies.set(name, {
+			value: "",
+			options: {
+				...options,
+				maxAge: 0,
+				expires: /* @__PURE__ */ new Date(0)
+			}
+		});
+		return this;
+	}
+	status(code) {
+		this.metadata.status = code;
+		return this;
+	}
+	send(data) {
+		return {
+			data,
+			metadata: this.metadata
+		};
+	}
+	getMetadata() {
+		return this.metadata;
+	}
+};
+/**
 * HTTP success status codes that can be returned by endpoints.
 */
 let SuccessStatus = /* @__PURE__ */ function(SuccessStatus$1) {
@@ -275,5 +393,5 @@ let SuccessStatus = /* @__PURE__ */ function(SuccessStatus$1) {
 }({});
 
 //#endregion
-export { Endpoint, SuccessStatus };
-//# sourceMappingURL=Endpoint-DNlmybXV.mjs.map
+export { Endpoint, ResponseBuilder, SuccessStatus };
+//# sourceMappingURL=Endpoint-DVEmKo6G.mjs.map