@geekmidas/constructs 0.0.1 → 0.0.3

package/src/endpoints/Endpoint.ts

@@ -6,11 +6,7 @@ import type { OpenAPIV3_1 } from 'openapi-types';
 
 import type { Service, ServiceRecord } from '@geekmidas/services';
 import { ConstructType } from '../Construct';
-import {
-  Function,
-  type FunctionContext,
-  type FunctionHandler,
-} from '../functions';
+import { Function, type FunctionHandler } from '../functions';
 
 import type {
   EventPublisher,
@@ -88,6 +84,8 @@ export class Endpoint<
   tags?: string[];
   /** The HTTP success status code to return (default: 200) */
   public readonly status: SuccessStatus;
+  /** Default headers to apply to all responses */
+  public readonly defaultHeaders: Record<string, string> = {};
   /** Function to extract session data from the request context */
   public getSession: SessionFn<TServices, TLogger, TSession> = () =>
     ({}) as TSession;
@@ -95,6 +93,14 @@ export class Endpoint<
   public authorize: AuthorizeFn<TServices, TLogger, TSession> = () => true;
   /** Optional rate limiting configuration */
   public rateLimit?: RateLimitConfig;
+  /** The endpoint handler function */
+  private endpointFn!: EndpointHandler<
+    TInput,
+    TServices,
+    TLogger,
+    OutSchema,
+    TSession
+  >;
 
   /**
    * Builds a complete OpenAPI 3.1 schema from an array of endpoints.
@@ -188,6 +194,81 @@ export class Endpoint<
     };
   }
 
+  /**
+   * 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 {
+    const cookieMap = new Map<string, string>();
+
+    if (cookieHeader) {
+      // Parse cookie string: "name1=value1; name2=value2"
+      const cookies = cookieHeader.split(';');
+      for (const cookie of cookies) {
+        const [name, ...valueParts] = cookie.trim().split('=');
+        if (name) {
+          const value = valueParts.join('='); // Handle values with = in them
+          cookieMap.set(name, decodeURIComponent(value));
+        }
+      }
+    }
+
+    return function get(name: string): string | undefined {
+      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: string,
+    value: string,
+    options?: CookieOptions,
+  ): string {
+    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 !== undefined) 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.
    *
@@ -207,18 +288,36 @@ export class Endpoint<
     return input;
   }
 
-  handler: EndpointHandler<TInput, TServices, TLogger, OutSchema, TSession> = (
+  handler = (
     ctx: EndpointContext<TInput, TServices, TLogger, TSession>,
+    response: ResponseBuilder,
   ): OutSchema extends StandardSchemaV1
-    ? InferStandardSchema<OutSchema> | Promise<InferStandardSchema<OutSchema>>
-    : void | Promise<void> => {
-    return this.fn({
-      ...this.refineInput(ctx),
-      services: ctx.services,
-      logger: ctx.logger,
-      header: ctx.header,
-      session: ctx.session,
-    } as unknown as FunctionContext<TInput, TServices, TLogger>);
+    ?
+        | InferStandardSchema<OutSchema>
+        | ResponseWithMetadata<InferStandardSchema<OutSchema>>
+        | Promise<InferStandardSchema<OutSchema>>
+        | Promise<ResponseWithMetadata<InferStandardSchema<OutSchema>>>
+    :
+        | any
+        | ResponseWithMetadata<any>
+        | Promise<any>
+        | Promise<ResponseWithMetadata<any>> => {
+    // Apply default headers to response builder
+    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,
+      } as EndpointContext<TInput, TServices, TLogger, TSession>,
+      response,
+    );
   };
 
   /**
@@ -235,6 +334,20 @@ export class Endpoint<
     );
   }
 
+  /**
+   * Helper to check if response has metadata
+   */
+  static hasMetadata<T>(
+    response: T | ResponseWithMetadata<T>,
+  ): response is ResponseWithMetadata<T> {
+    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}'
@@ -433,6 +546,8 @@ export class Endpoint<
     this.description = description;
     this.tags = tags;
     this.status = status;
+    this.endpointFn = fn;
+
     if (getSession) {
       this.getSession = getSession;
     }
@@ -553,6 +668,7 @@ export type AuthorizeContext<
   services: ServiceRecord<TServices>;
   logger: TLogger;
   header: HeaderFn;
+  cookie: CookieFn;
   session: TSession;
 };
 /**
@@ -587,6 +703,7 @@ export type SessionContext<
   services: ServiceRecord<TServices>;
   logger: TLogger;
   header: HeaderFn;
+  cookie: CookieFn;
 };
 /**
  * Function type for extracting session data from a request.
@@ -669,9 +786,96 @@ export type EndpointHeaders = Map<string, string>;
  */
 export 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');
+ * ```
+ */
+export type CookieFn = (name: string) => string | undefined;
+
+/**
+ * Cookie options matching standard Set-Cookie attributes
+ */
+export interface CookieOptions {
+  domain?: string;
+  path?: string;
+  expires?: Date;
+  maxAge?: number;
+  httpOnly?: boolean;
+  secure?: boolean;
+  sameSite?: 'strict' | 'lax' | 'none';
+}
+
+/**
+ * Response metadata that handlers can set
+ */
+export 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
+ */
+export interface ResponseWithMetadata<T> {
+  data: T;
+  metadata: ResponseMetadata;
+}
+
+/**
+ * Response builder for fluent API in handlers
+ */
+export class ResponseBuilder {
+  private metadata: ResponseMetadata = {
+    headers: {},
+    cookies: new Map(),
+  };
+
+  header(key: string, value: string): this {
+    this.metadata.headers![key] = value;
+    return this;
+  }
+
+  cookie(name: string, value: string, options?: CookieOptions): this {
+    this.metadata.cookies!.set(name, { value, options });
+    return this;
+  }
+
+  deleteCookie(
+    name: string,
+    options?: Pick<CookieOptions, 'domain' | 'path'>,
+  ): this {
+    this.metadata.cookies!.set(name, {
+      value: '',
+      options: { ...options, maxAge: 0, expires: new Date(0) },
+    });
+    return this;
+  }
+
+  status(code: SuccessStatus): this {
+    this.metadata.status = code;
+    return this;
+  }
+
+  send<T>(data: T): ResponseWithMetadata<T> {
+    return { data, metadata: this.metadata };
+  }
+
+  getMetadata(): ResponseMetadata {
+    return this.metadata;
+  }
+}
+
 /**
  * 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
@@ -690,6 +894,8 @@ export type EndpointContext<
   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>;
@@ -704,14 +910,23 @@ export type EndpointContext<
  * @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);
+ *   };
  * ```
  */
 export type EndpointHandler<
@@ -722,9 +937,18 @@ export type EndpointHandler<
   TSession = unknown,
 > = (
   ctx: EndpointContext<TInput, TServices, TLogger, TSession>,
+  response: ResponseBuilder,
 ) => OutSchema extends StandardSchemaV1
-  ? InferStandardSchema<OutSchema> | Promise<InferStandardSchema<OutSchema>>
-  : any | Promise<any>;
+  ?
+      | 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.

package/src/endpoints/HonoEndpointAdaptor.ts

@@ -4,12 +4,14 @@ import type { Logger } from '@geekmidas/logger';
 import { checkRateLimit, getRateLimitHeaders } from '@geekmidas/rate-limit';
 import type { StandardSchemaV1 } from '@standard-schema/spec';
 import { type Context, Hono } from 'hono';
+import { setCookie } from 'hono/cookie';
 import { validator } from 'hono/validator';
 import type { HttpMethod, LowerHttpMethod } from '../types';
 import {
   Endpoint,
   type EndpointContext,
   type EndpointSchemas,
+  ResponseBuilder,
 } from './Endpoint';
 import { getEndpointsFromRoutes } from './helpers';
 import { parseHonoQuery } from './parseHonoQuery';
@@ -242,6 +244,7 @@ export class HonoEndpoint<
           const headerValues = c.req.header();
 
           const header = Endpoint.createHeaders(headerValues);
+          const cookie = Endpoint.createCookies(headerValues.cookie);
 
           const services = await serviceDiscovery.register(endpoint.services);
 
@@ -249,10 +252,12 @@ export class HonoEndpoint<
             services,
             logger,
             header,
+            cookie,
           });
 
           const isAuthorized = await endpoint.authorize({
             header,
+            cookie,
             services,
             logger,
             session,
@@ -286,29 +291,60 @@ export class HonoEndpoint<
             }
           }
 
-          const response = await endpoint.handler({
-            services,
-            logger,
-            body: c.req.valid('json'),
-            query: c.req.valid('query'),
-            params: c.req.valid('param'),
-            session,
-            header: Endpoint.createHeaders(headerValues),
-          } as unknown as EndpointContext<
-            TInput,
-            TServices,
-            TLogger,
-            TSession
-          >);
+          const responseBuilder = new ResponseBuilder();
+          const response = await endpoint.handler(
+            {
+              services,
+              logger,
+              body: c.req.valid('json'),
+              query: c.req.valid('query'),
+              params: c.req.valid('param'),
+              session,
+              header: Endpoint.createHeaders(headerValues),
+              cookie: Endpoint.createCookies(headerValues.cookie),
+            } as unknown as EndpointContext<
+              TInput,
+              TServices,
+              TLogger,
+              TSession
+            >,
+            responseBuilder,
+          );
 
           // Publish events if configured
 
           // Validate output if schema is defined
 
           try {
-            const status = endpoint.status as ContentfulStatusCode;
+            // Check if response has metadata
+            let data = response;
+            let metadata = responseBuilder.getMetadata();
+            let status = endpoint.status as ContentfulStatusCode;
+
+            if (Endpoint.hasMetadata(response)) {
+              data = response.data;
+              metadata = response.metadata;
+            }
+
+            // Apply response metadata
+            if (metadata.status) {
+              status = metadata.status as ContentfulStatusCode;
+            }
+
+            if (metadata.headers) {
+              for (const [key, value] of Object.entries(metadata.headers)) {
+                c.header(key, value);
+              }
+            }
+
+            if (metadata.cookies) {
+              for (const [name, { value, options }] of metadata.cookies) {
+                setCookie(c, name, value, options);
+              }
+            }
+
             const output = endpoint.outputSchema
-              ? await endpoint.parseOutput(response)
+              ? await endpoint.parseOutput(data)
               : ({} as any);
             // @ts-ignore
             c.set('__response', output);

package/src/endpoints/TestEndpointAdaptor.ts

@@ -13,7 +13,12 @@ import {
 import type { StandardSchemaV1 } from '@standard-schema/spec';
 import { publishConstructEvents } from '../publisher';
 import type { HttpMethod } from '../types';
-import { Endpoint, type EndpointSchemas } from './Endpoint';
+import {
+  Endpoint,
+  type EndpointSchemas,
+  ResponseBuilder,
+  type ResponseWithMetadata,
+} from './Endpoint';
 
 export class TestEndpointAdaptor<
   TRoute extends string,
@@ -79,7 +84,10 @@ export class TestEndpointAdaptor<
       TEventPublisher,
       TEventPublisherServiceName
     >,
-  ): Promise<InferStandardSchema<TOutSchema>> {
+  ): Promise<
+    | InferStandardSchema<TOutSchema>
+    | ResponseWithMetadata<InferStandardSchema<TOutSchema>>
+  > {
     const body = await this.endpoint.parseInput((ctx as any).body, 'body');
     const query = await this.endpoint.parseInput((ctx as any).query, 'query');
     const params = await this.endpoint.parseInput(
@@ -88,6 +96,7 @@ export class TestEndpointAdaptor<
     );
 
     const header = Endpoint.createHeaders(ctx.headers);
+    const cookie = Endpoint.createCookies(ctx.headers.cookie);
     const logger = this.endpoint.logger.child({
       route: this.endpoint.route,
       host: ctx.headers.host,
@@ -97,23 +106,47 @@ export class TestEndpointAdaptor<
       logger,
       services: ctx.services,
       header,
+      cookie,
     });
 
-    const response = await this.endpoint.handler({
-      body,
-      query,
-      params,
-      session,
-      services: ctx.services,
-      logger,
-      header,
-    } as any);
+    const responseBuilder = new ResponseBuilder();
+    const response = await this.endpoint.handler(
+      {
+        body,
+        query,
+        params,
+        session,
+        services: ctx.services,
+        logger,
+        header,
+        cookie,
+      } as any,
+      responseBuilder,
+    );
+
+    // Check if response has metadata
+    let data = response;
+    let metadata = responseBuilder.getMetadata();
 
-    const output = await this.endpoint.parseOutput(response);
+    if (Endpoint.hasMetadata(response)) {
+      data = response.data;
+      metadata = response.metadata;
+    }
+
+    const output = await this.endpoint.parseOutput(data);
     ctx.publisher && (await this.serviceDiscovery.register([ctx.publisher]));
 
     await publishConstructEvents(this.endpoint, output, this.serviceDiscovery);
 
+    // Return with metadata if any was set
+    if (
+      (metadata.headers && Object.keys(metadata.headers).length > 0) ||
+      (metadata.cookies && metadata.cookies.size > 0) ||
+      metadata.status
+    ) {
+      return { data: output, metadata };
+    }
+
     return output;
   }
 }