@geekmidas/constructs 0.0.2 → 0.0.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geekmidas/constructs",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "private": false,
   "type": "module",
   "exports": {
@@ -69,10 +69,10 @@
     "@geekmidas/schema": "0.0.1",
     "@geekmidas/services": "0.0.1",
     "@geekmidas/logger": "0.0.1",
-    "@geekmidas/errors": "0.0.1",
-    "@geekmidas/rate-limit": "0.1.0",
     "@geekmidas/events": "0.0.1",
-    "@geekmidas/cache": "0.0.7"
+    "@geekmidas/errors": "0.0.1",
+    "@geekmidas/cache": "0.0.7",
+    "@geekmidas/rate-limit": "0.1.0"
   },
   "devDependencies": {
     "@types/lodash.pick": "~4.4.9",

package/src/endpoints/AmazonApiGatewayEndpointAdaptor.ts

@@ -1,7 +1,7 @@
 import type { Logger } from '@geekmidas/logger';
 import type { StandardSchemaV1 } from '@standard-schema/spec';
 import type { HttpMethod } from '../types';
-import { Endpoint, type EndpointSchemas } from './Endpoint';
+import { Endpoint, type EndpointSchemas, ResponseBuilder } from './Endpoint';
 
 import type { EnvironmentParser } from '@geekmidas/envkit';
 import middy, { type MiddlewareObj } from '@middy/core';
@@ -88,6 +88,7 @@ export abstract class AmazonApiGatewayEndpoint<
           const { body, query, params } = this.getInput(req.event);
           const headers = req.event.headers as Record<string, string>;
           const header = Endpoint.createHeaders(headers);
+          const cookie = Endpoint.createCookies(headers.cookie);
 
           set(req.event, 'body', await this.endpoint.parseInput(body, 'body'));
 
@@ -102,6 +103,7 @@ export abstract class AmazonApiGatewayEndpoint<
             await this.endpoint.parseInput(params, 'params'),
           );
           set(req.event, 'header', header);
+          set(req.event, 'cookie', cookie);
         } catch (error) {
           // Convert validation errors to 422 Unprocessable Entity
           if (error && typeof error === 'object' && Array.isArray(error)) {
@@ -151,10 +153,12 @@ export abstract class AmazonApiGatewayEndpoint<
         const logger = req.event.logger as TLogger;
         const services = req.event.services;
         const header = req.event.header;
+        const cookie = req.event.cookie;
         const session = req.event.session as TSession;
 
         const isAuthorized = await this.endpoint.authorize({
           header,
+          cookie,
           services,
           logger,
           session,
@@ -180,6 +184,7 @@ export abstract class AmazonApiGatewayEndpoint<
           logger,
           services,
           header: req.event.header,
+          cookie: req.event.cookie,
         })) as TSession;
       },
     };
@@ -216,25 +221,66 @@ export abstract class AmazonApiGatewayEndpoint<
   ) {
     const input = this.endpoint.refineInput(event);
 
-    const response = await this.endpoint.handler({
-      header: event.header,
-      logger: event.logger,
-      services: event.services,
-      session: event.session,
-      ...input,
-    });
+    const responseBuilder = new ResponseBuilder();
+    const response = await this.endpoint.handler(
+      {
+        header: event.header,
+        cookie: event.cookie,
+        logger: event.logger,
+        services: event.services,
+        session: event.session,
+        ...input,
+      },
+      responseBuilder,
+    );
+
+    // Check if response has metadata
+    let data = response;
+    let metadata = responseBuilder.getMetadata();
+
+    if (Endpoint.hasMetadata(response)) {
+      data = response.data;
+      metadata = response.metadata;
+    }
 
-    const output = await this.endpoint.parseOutput(response);
+    const output = this.endpoint.outputSchema
+      ? await this.endpoint.parseOutput(data)
+      : undefined;
 
-    const body = output ? JSON.stringify(output) : undefined;
+    const body = output !== undefined ? JSON.stringify(output) : undefined;
 
     // Store response for middleware access
-    (event as any).__response = response;
+    (event as any).__response = output;
 
-    return {
-      statusCode: this.endpoint.status,
+    // Build response with metadata
+    const lambdaResponse: AmazonApiGatewayEndpointHandlerResponse = {
+      statusCode: metadata.status ?? this.endpoint.status,
       body,
     };
+
+    // Add custom headers
+    if (metadata.headers && Object.keys(metadata.headers).length > 0) {
+      lambdaResponse.headers = { ...metadata.headers };
+    }
+
+    // Format cookies as Set-Cookie headers
+    if (metadata.cookies && metadata.cookies.size > 0) {
+      const setCookieHeaders: string[] = [];
+      for (const [name, { value, options }] of metadata.cookies) {
+        setCookieHeaders.push(
+          Endpoint.formatCookieHeader(name, value, options),
+        );
+      }
+
+      if (setCookieHeaders.length > 0) {
+        lambdaResponse.multiValueHeaders = {
+          ...lambdaResponse.multiValueHeaders,
+          'Set-Cookie': setCookieHeaders,
+        };
+      }
+    }
+
+    return lambdaResponse;
   }
 
   get handler() {
@@ -260,6 +306,7 @@ export type Event<
   services: ServiceRecord<TServices>;
   logger: TLogger;
   header(key: string): string | undefined;
+  cookie(name: string): string | undefined;
   session: TSession;
 } & TEvent &
   InferComposableStandardSchema<TInput>;
@@ -275,6 +322,8 @@ type Middleware<
 export type AmazonApiGatewayEndpointHandlerResponse = {
   statusCode: number;
   body: string | undefined;
+  headers?: Record<string, string>;
+  multiValueHeaders?: Record<string, string[]>;
 };
 
 export type LoggerContext = {

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);