@fnd-platform/api 1.0.0-alpha.1

package/lib/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @fnd-platform/api
+ *
+ * Projen project class and runtime utilities for building Lambda APIs.
+ *
+ * Use FndApiProject to add a serverless API to your monorepo with Lambda
+ * handlers, middleware patterns, and type-safe response utilities.
+ *
+ * @packageDocumentation
+ */
+export { FndApiProject } from './api-project';
+export type { FndApiProjectOptions } from './options';
+export { success, error, notFound, unauthorized, forbidden, badRequest, created, } from './lib/response';
+export type { SuccessResponse, ErrorResponse } from './lib/response';
+export { ApiError, NotFoundError, ValidationError, UnauthorizedError, ForbiddenError, ConflictError, } from './lib/errors';
+export { parseBody, requirePathParam, getQueryParam, getUserId } from './lib/request';
+export type { Handler, AuthenticatedEvent, AuthenticatedHandler, CognitoClaims, PaginatedRequest, PaginatedResponse, } from './types/api';
+export { compose } from './lib/middleware';
+export { withErrorHandler, withAuth, withValidation, withCors, withLogging } from './middleware';
+export type { ErrorHandlerOptions, AuthOptions, CorsOptions, LoggingOptions } from './middleware';
+export type { MiddlewareHandler, Middleware, ValidatedEvent } from './types/middleware';
+//# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAG9C,YAAY,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAC;AAGtD,OAAO,EACL,OAAO,EACP,KAAK,EACL,QAAQ,EACR,YAAY,EACZ,SAAS,EACT,UAAU,EACV,OAAO,GACR,MAAM,gBAAgB,CAAC;AACxB,YAAY,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAGrE,OAAO,EACL,QAAQ,EACR,aAAa,EACb,eAAe,EACf,iBAAiB,EACjB,cAAc,EACd,aAAa,GACd,MAAM,cAAc,CAAC;AAGtB,OAAO,EAAE,SAAS,EAAE,gBAAgB,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAGtF,YAAY,EACV,OAAO,EACP,kBAAkB,EAClB,oBAAoB,EACpB,aAAa,EACb,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,aAAa,CAAC;AAGrB,OAAO,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAG3C,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,cAAc,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAGjG,YAAY,EAAE,mBAAmB,EAAE,WAAW,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAGlG,YAAY,EAAE,iBAAiB,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC"}

package/lib/index.js

@@ -0,0 +1,50 @@
+"use strict";
+/**
+ * @fnd-platform/api
+ *
+ * Projen project class and runtime utilities for building Lambda APIs.
+ *
+ * Use FndApiProject to add a serverless API to your monorepo with Lambda
+ * handlers, middleware patterns, and type-safe response utilities.
+ *
+ * @packageDocumentation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withLogging = exports.withCors = exports.withValidation = exports.withAuth = exports.withErrorHandler = exports.compose = exports.getUserId = exports.getQueryParam = exports.requirePathParam = exports.parseBody = exports.ConflictError = exports.ForbiddenError = exports.UnauthorizedError = exports.ValidationError = exports.NotFoundError = exports.ApiError = exports.created = exports.badRequest = exports.forbidden = exports.unauthorized = exports.notFound = exports.error = exports.success = exports.FndApiProject = void 0;
+// Main project class
+var api_project_1 = require("./api-project");
+Object.defineProperty(exports, "FndApiProject", { enumerable: true, get: function () { return api_project_1.FndApiProject; } });
+// Response helpers
+var response_1 = require("./lib/response");
+Object.defineProperty(exports, "success", { enumerable: true, get: function () { return response_1.success; } });
+Object.defineProperty(exports, "error", { enumerable: true, get: function () { return response_1.error; } });
+Object.defineProperty(exports, "notFound", { enumerable: true, get: function () { return response_1.notFound; } });
+Object.defineProperty(exports, "unauthorized", { enumerable: true, get: function () { return response_1.unauthorized; } });
+Object.defineProperty(exports, "forbidden", { enumerable: true, get: function () { return response_1.forbidden; } });
+Object.defineProperty(exports, "badRequest", { enumerable: true, get: function () { return response_1.badRequest; } });
+Object.defineProperty(exports, "created", { enumerable: true, get: function () { return response_1.created; } });
+// Error classes
+var errors_1 = require("./lib/errors");
+Object.defineProperty(exports, "ApiError", { enumerable: true, get: function () { return errors_1.ApiError; } });
+Object.defineProperty(exports, "NotFoundError", { enumerable: true, get: function () { return errors_1.NotFoundError; } });
+Object.defineProperty(exports, "ValidationError", { enumerable: true, get: function () { return errors_1.ValidationError; } });
+Object.defineProperty(exports, "UnauthorizedError", { enumerable: true, get: function () { return errors_1.UnauthorizedError; } });
+Object.defineProperty(exports, "ForbiddenError", { enumerable: true, get: function () { return errors_1.ForbiddenError; } });
+Object.defineProperty(exports, "ConflictError", { enumerable: true, get: function () { return errors_1.ConflictError; } });
+// Request utilities
+var request_1 = require("./lib/request");
+Object.defineProperty(exports, "parseBody", { enumerable: true, get: function () { return request_1.parseBody; } });
+Object.defineProperty(exports, "requirePathParam", { enumerable: true, get: function () { return request_1.requirePathParam; } });
+Object.defineProperty(exports, "getQueryParam", { enumerable: true, get: function () { return request_1.getQueryParam; } });
+Object.defineProperty(exports, "getUserId", { enumerable: true, get: function () { return request_1.getUserId; } });
+// Middleware composition
+var middleware_1 = require("./lib/middleware");
+Object.defineProperty(exports, "compose", { enumerable: true, get: function () { return middleware_1.compose; } });
+// Middleware functions
+var middleware_2 = require("./middleware");
+Object.defineProperty(exports, "withErrorHandler", { enumerable: true, get: function () { return middleware_2.withErrorHandler; } });
+Object.defineProperty(exports, "withAuth", { enumerable: true, get: function () { return middleware_2.withAuth; } });
+Object.defineProperty(exports, "withValidation", { enumerable: true, get: function () { return middleware_2.withValidation; } });
+Object.defineProperty(exports, "withCors", { enumerable: true, get: function () { return middleware_2.withCors; } });
+Object.defineProperty(exports, "withLogging", { enumerable: true, get: function () { return middleware_2.withLogging; } });
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;GASG;;;AAEH,qBAAqB;AACrB,6CAA8C;AAArC,4GAAA,aAAa,OAAA;AAKtB,mBAAmB;AACnB,2CAQwB;AAPtB,mGAAA,OAAO,OAAA;AACP,iGAAA,KAAK,OAAA;AACL,oGAAA,QAAQ,OAAA;AACR,wGAAA,YAAY,OAAA;AACZ,qGAAA,SAAS,OAAA;AACT,sGAAA,UAAU,OAAA;AACV,mGAAA,OAAO,OAAA;AAIT,gBAAgB;AAChB,uCAOsB;AANpB,kGAAA,QAAQ,OAAA;AACR,uGAAA,aAAa,OAAA;AACb,yGAAA,eAAe,OAAA;AACf,2GAAA,iBAAiB,OAAA;AACjB,wGAAA,cAAc,OAAA;AACd,uGAAA,aAAa,OAAA;AAGf,oBAAoB;AACpB,yCAAsF;AAA7E,oGAAA,SAAS,OAAA;AAAE,2GAAA,gBAAgB,OAAA;AAAE,wGAAA,aAAa,OAAA;AAAE,oGAAA,SAAS,OAAA;AAY9D,yBAAyB;AACzB,+CAA2C;AAAlC,qGAAA,OAAO,OAAA;AAEhB,uBAAuB;AACvB,2CAAiG;AAAxF,8GAAA,gBAAgB,OAAA;AAAE,sGAAA,QAAQ,OAAA;AAAE,4GAAA,cAAc,OAAA;AAAE,sGAAA,QAAQ,OAAA;AAAE,yGAAA,WAAW,OAAA"}

package/lib/lib/errors.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Custom error classes for API responses.
+ *
+ * All API errors extend ApiError and include an error code,
+ * HTTP status code, and optional details for structured error handling.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Base API error class.
+ *
+ * All API errors should extend this class to ensure consistent
+ * error handling and serialization across the application.
+ *
+ * @example
+ * ```typescript
+ * const err = new ApiError('Something went wrong', 'INTERNAL_ERROR', 500);
+ * console.log(err.toJSON());
+ * // { code: 'INTERNAL_ERROR', message: 'Something went wrong', details: undefined }
+ * ```
+ */
+export declare class ApiError extends Error {
+  readonly code: string;
+  readonly statusCode: number;
+  readonly details?: unknown | undefined;
+  /**
+   * Creates a new ApiError.
+   *
+   * @param message - Human-readable error message
+   * @param code - Machine-readable error code (UPPER_SNAKE_CASE)
+   * @param statusCode - HTTP status code (default: 500)
+   * @param details - Optional additional error details
+   */
+  constructor(message: string, code: string, statusCode?: number, details?: unknown | undefined);
+  /**
+   * Converts the error to a JSON-serializable object.
+   *
+   * @returns Object with code, message, and details
+   */
+  toJSON(): {
+    code: string;
+    message: string;
+    details?: unknown;
+  };
+}
+/**
+ * 404 Not Found error.
+ *
+ * Use when a requested resource does not exist.
+ *
+ * @example
+ * ```typescript
+ * throw new NotFoundError('User not found');
+ * ```
+ */
+export declare class NotFoundError extends ApiError {
+  constructor(message?: string);
+}
+/**
+ * 400 Validation error.
+ *
+ * Use when request validation fails, such as missing required fields
+ * or invalid data formats.
+ *
+ * @example
+ * ```typescript
+ * throw new ValidationError('Invalid email format', { field: 'email' });
+ * ```
+ */
+export declare class ValidationError extends ApiError {
+  constructor(message?: string, details?: unknown);
+}
+/**
+ * 401 Unauthorized error.
+ *
+ * Use when authentication is required but missing or invalid.
+ *
+ * @example
+ * ```typescript
+ * throw new UnauthorizedError('Invalid token');
+ * ```
+ */
+export declare class UnauthorizedError extends ApiError {
+  constructor(message?: string);
+}
+/**
+ * 403 Forbidden error.
+ *
+ * Use when the user is authenticated but lacks permission
+ * to access the resource.
+ *
+ * @example
+ * ```typescript
+ * throw new ForbiddenError('Admin access required');
+ * ```
+ */
+export declare class ForbiddenError extends ApiError {
+  constructor(message?: string);
+}
+/**
+ * 409 Conflict error.
+ *
+ * Use when the request conflicts with the current state of the resource,
+ * such as duplicate entries or version conflicts.
+ *
+ * @example
+ * ```typescript
+ * throw new ConflictError('Email already exists');
+ * ```
+ */
+export declare class ConflictError extends ApiError {
+  constructor(message?: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/lib/lib/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/lib/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;;;;;;;;;GAYG;AACH,qBAAa,QAAS,SAAQ,KAAK;aAWf,IAAI,EAAE,MAAM;aACZ,UAAU,EAAE,MAAM;aAClB,OAAO,CAAC,EAAE,OAAO;IAZnC;;;;;;;OAOG;gBAED,OAAO,EAAE,MAAM,EACC,IAAI,EAAE,MAAM,EACZ,UAAU,GAAE,MAAY,EACxB,OAAO,CAAC,EAAE,OAAO,YAAA;IASnC;;;;OAIG;IACH,MAAM,IAAI;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE;CAO/D;AAED;;;;;;;;;GASG;AACH,qBAAa,aAAc,SAAQ,QAAQ;gBAC7B,OAAO,SAAuB;CAI3C;AAED;;;;;;;;;;GAUG;AACH,qBAAa,eAAgB,SAAQ,QAAQ;gBAC/B,OAAO,SAAsB,EAAE,OAAO,CAAC,EAAE,OAAO;CAI7D;AAED;;;;;;;;;GASG;AACH,qBAAa,iBAAkB,SAAQ,QAAQ;gBACjC,OAAO,SAAiB;CAIrC;AAED;;;;;;;;;;GAUG;AACH,qBAAa,cAAe,SAAQ,QAAQ;gBAC9B,OAAO,SAAc;CAIlC;AAED;;;;;;;;;;GAUG;AACH,qBAAa,aAAc,SAAQ,QAAQ;gBAC7B,OAAO,SAAsB;CAI1C"}

package/lib/lib/errors.js

@@ -0,0 +1,154 @@
+'use strict';
+/**
+ * Custom error classes for API responses.
+ *
+ * All API errors extend ApiError and include an error code,
+ * HTTP status code, and optional details for structured error handling.
+ *
+ * @packageDocumentation
+ */
+Object.defineProperty(exports, '__esModule', { value: true });
+exports.ConflictError =
+  exports.ForbiddenError =
+  exports.UnauthorizedError =
+  exports.ValidationError =
+  exports.NotFoundError =
+  exports.ApiError =
+    void 0;
+/**
+ * Base API error class.
+ *
+ * All API errors should extend this class to ensure consistent
+ * error handling and serialization across the application.
+ *
+ * @example
+ * ```typescript
+ * const err = new ApiError('Something went wrong', 'INTERNAL_ERROR', 500);
+ * console.log(err.toJSON());
+ * // { code: 'INTERNAL_ERROR', message: 'Something went wrong', details: undefined }
+ * ```
+ */
+class ApiError extends Error {
+  code;
+  statusCode;
+  details;
+  /**
+   * Creates a new ApiError.
+   *
+   * @param message - Human-readable error message
+   * @param code - Machine-readable error code (UPPER_SNAKE_CASE)
+   * @param statusCode - HTTP status code (default: 500)
+   * @param details - Optional additional error details
+   */
+  constructor(message, code, statusCode = 500, details) {
+    super(message);
+    this.code = code;
+    this.statusCode = statusCode;
+    this.details = details;
+    this.name = 'ApiError';
+    // Maintains proper stack trace for where error was thrown
+    Error.captureStackTrace(this, this.constructor);
+  }
+  /**
+   * Converts the error to a JSON-serializable object.
+   *
+   * @returns Object with code, message, and details
+   */
+  toJSON() {
+    return {
+      code: this.code,
+      message: this.message,
+      details: this.details,
+    };
+  }
+}
+exports.ApiError = ApiError;
+/**
+ * 404 Not Found error.
+ *
+ * Use when a requested resource does not exist.
+ *
+ * @example
+ * ```typescript
+ * throw new NotFoundError('User not found');
+ * ```
+ */
+class NotFoundError extends ApiError {
+  constructor(message = 'Resource not found') {
+    super(message, 'NOT_FOUND', 404);
+    this.name = 'NotFoundError';
+  }
+}
+exports.NotFoundError = NotFoundError;
+/**
+ * 400 Validation error.
+ *
+ * Use when request validation fails, such as missing required fields
+ * or invalid data formats.
+ *
+ * @example
+ * ```typescript
+ * throw new ValidationError('Invalid email format', { field: 'email' });
+ * ```
+ */
+class ValidationError extends ApiError {
+  constructor(message = 'Validation failed', details) {
+    super(message, 'VALIDATION_ERROR', 400, details);
+    this.name = 'ValidationError';
+  }
+}
+exports.ValidationError = ValidationError;
+/**
+ * 401 Unauthorized error.
+ *
+ * Use when authentication is required but missing or invalid.
+ *
+ * @example
+ * ```typescript
+ * throw new UnauthorizedError('Invalid token');
+ * ```
+ */
+class UnauthorizedError extends ApiError {
+  constructor(message = 'Unauthorized') {
+    super(message, 'UNAUTHORIZED', 401);
+    this.name = 'UnauthorizedError';
+  }
+}
+exports.UnauthorizedError = UnauthorizedError;
+/**
+ * 403 Forbidden error.
+ *
+ * Use when the user is authenticated but lacks permission
+ * to access the resource.
+ *
+ * @example
+ * ```typescript
+ * throw new ForbiddenError('Admin access required');
+ * ```
+ */
+class ForbiddenError extends ApiError {
+  constructor(message = 'Forbidden') {
+    super(message, 'FORBIDDEN', 403);
+    this.name = 'ForbiddenError';
+  }
+}
+exports.ForbiddenError = ForbiddenError;
+/**
+ * 409 Conflict error.
+ *
+ * Use when the request conflicts with the current state of the resource,
+ * such as duplicate entries or version conflicts.
+ *
+ * @example
+ * ```typescript
+ * throw new ConflictError('Email already exists');
+ * ```
+ */
+class ConflictError extends ApiError {
+  constructor(message = 'Resource conflict') {
+    super(message, 'CONFLICT', 409);
+    this.name = 'ConflictError';
+  }
+}
+exports.ConflictError = ConflictError;
+//# sourceMappingURL=errors.js.map

package/lib/lib/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/lib/errors.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;;AAEH;;;;;;;;;;;;GAYG;AACH,MAAa,QAAS,SAAQ,KAAK;IAWf;IACA;IACA;IAZlB;;;;;;;OAOG;IACH,YACE,OAAe,EACC,IAAY,EACZ,aAAqB,GAAG,EACxB,OAAiB;QAEjC,KAAK,CAAC,OAAO,CAAC,CAAC;QAJC,SAAI,GAAJ,IAAI,CAAQ;QACZ,eAAU,GAAV,UAAU,CAAc;QACxB,YAAO,GAAP,OAAO,CAAU;QAGjC,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC;QAEvB,0DAA0D;QAC1D,KAAK,CAAC,iBAAiB,CAAC,IAAI,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC;IAClD,CAAC;IAED;;;;OAIG;IACH,MAAM;QACJ,OAAO;YACL,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,OAAO,EAAE,IAAI,CAAC,OAAO;SACtB,CAAC;IACJ,CAAC;CACF;AAlCD,4BAkCC;AAED;;;;;;;;;GASG;AACH,MAAa,aAAc,SAAQ,QAAQ;IACzC,YAAY,OAAO,GAAG,oBAAoB;QACxC,KAAK,CAAC,OAAO,EAAE,WAAW,EAAE,GAAG,CAAC,CAAC;QACjC,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;IAC9B,CAAC;CACF;AALD,sCAKC;AAED;;;;;;;;;;GAUG;AACH,MAAa,eAAgB,SAAQ,QAAQ;IAC3C,YAAY,OAAO,GAAG,mBAAmB,EAAE,OAAiB;QAC1D,KAAK,CAAC,OAAO,EAAE,kBAAkB,EAAE,GAAG,EAAE,OAAO,CAAC,CAAC;QACjD,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;IAChC,CAAC;CACF;AALD,0CAKC;AAED;;;;;;;;;GASG;AACH,MAAa,iBAAkB,SAAQ,QAAQ;IAC7C,YAAY,OAAO,GAAG,cAAc;QAClC,KAAK,CAAC,OAAO,EAAE,cAAc,EAAE,GAAG,CAAC,CAAC;QACpC,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;IAClC,CAAC;CACF;AALD,8CAKC;AAED;;;;;;;;;;GAUG;AACH,MAAa,cAAe,SAAQ,QAAQ;IAC1C,YAAY,OAAO,GAAG,WAAW;QAC/B,KAAK,CAAC,OAAO,EAAE,WAAW,EAAE,GAAG,CAAC,CAAC;QACjC,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;IAC/B,CAAC;CACF;AALD,wCAKC;AAED;;;;;;;;;;GAUG;AACH,MAAa,aAAc,SAAQ,QAAQ;IACzC,YAAY,OAAO,GAAG,mBAAmB;QACvC,KAAK,CAAC,OAAO,EAAE,UAAU,EAAE,GAAG,CAAC,CAAC;QAChC,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;IAC9B,CAAC;CACF;AALD,sCAKC"}

package/lib/lib/middleware.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Middleware composition for Lambda handlers.
+ *
+ * @packageDocumentation
+ */
+import type { APIGatewayProxyEvent } from 'aws-lambda';
+import type { MiddlewareHandler, Middleware } from '../types/middleware';
+/**
+ * Compose multiple middleware into a single middleware.
+ *
+ * Middleware is applied from right to left (innermost first),
+ * meaning the first middleware in the list will be the outermost
+ * wrapper and will execute first.
+ *
+ * @param middlewares - Array of middleware functions to compose
+ * @returns A function that takes a handler and returns a wrapped handler
+ *
+ * @example
+ * ```typescript
+ * // Error handler runs first (outermost), then auth, then validation
+ * const handler = compose(
+ *   withErrorHandler(),
+ *   withAuth(),
+ *   withValidation(schema)
+ * )(async (event) => {
+ *   return success(event.validatedBody);
+ * });
+ * ```
+ */
+export declare function compose<TEvent = APIGatewayProxyEvent>(
+  ...middlewares: Middleware<any, any>[]
+): (handler: MiddlewareHandler<any>) => MiddlewareHandler<TEvent>;
+//# sourceMappingURL=middleware.d.ts.map

package/lib/lib/middleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../../src/lib/middleware.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AACvD,OAAO,KAAK,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAEzE;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,OAAO,CAAC,MAAM,GAAG,oBAAoB,EACnD,GAAG,WAAW,EAAE,UAAU,CAAC,GAAG,EAAE,GAAG,CAAC,EAAE,GACrC,CAAC,OAAO,EAAE,iBAAiB,CAAC,GAAG,CAAC,KAAK,iBAAiB,CAAC,MAAM,CAAC,CAIhE"}

package/lib/lib/middleware.js

@@ -0,0 +1,36 @@
+"use strict";
+/**
+ * Middleware composition for Lambda handlers.
+ *
+ * @packageDocumentation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.compose = compose;
+/**
+ * Compose multiple middleware into a single middleware.
+ *
+ * Middleware is applied from right to left (innermost first),
+ * meaning the first middleware in the list will be the outermost
+ * wrapper and will execute first.
+ *
+ * @param middlewares - Array of middleware functions to compose
+ * @returns A function that takes a handler and returns a wrapped handler
+ *
+ * @example
+ * ```typescript
+ * // Error handler runs first (outermost), then auth, then validation
+ * const handler = compose(
+ *   withErrorHandler(),
+ *   withAuth(),
+ *   withValidation(schema)
+ * )(async (event) => {
+ *   return success(event.validatedBody);
+ * });
+ * ```
+ */
+function compose(...middlewares) {
+    return (handler) => {
+        return middlewares.reduceRight((acc, middleware) => middleware(acc), handler);
+    };
+}
+//# sourceMappingURL=middleware.js.map

package/lib/lib/middleware.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"middleware.js","sourceRoot":"","sources":["../../src/lib/middleware.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;AA2BH,0BAMC;AA5BD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,SAAgB,OAAO,CACrB,GAAG,WAAmC;IAEtC,OAAO,CAAC,OAAO,EAAE,EAAE;QACjB,OAAO,WAAW,CAAC,WAAW,CAAC,CAAC,GAAG,EAAE,UAAU,EAAE,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,OAAO,CAAC,CAAC;IAChF,CAAC,CAAC;AACJ,CAAC"}

package/lib/lib/request.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Request parsing utilities for Lambda handlers.
+ *
+ * Provides type-safe extraction of request data including
+ * JSON body parsing, path parameters, and query parameters.
+ *
+ * @packageDocumentation
+ */
+import type { APIGatewayProxyEvent } from 'aws-lambda';
+import type { AuthenticatedEvent } from '../types/api';
+/**
+ * Parse JSON body from API Gateway event.
+ *
+ * @param event - API Gateway proxy event
+ * @returns Parsed JSON body as type T
+ * @throws {ValidationError} If body is missing or invalid JSON
+ *
+ * @example
+ * ```typescript
+ * interface CreateUserBody {
+ *   name: string;
+ *   email: string;
+ * }
+ *
+ * const handler: Handler = async (event) => {
+ *   const body = parseBody<CreateUserBody>(event);
+ *   // body is typed as CreateUserBody
+ * };
+ * ```
+ */
+export declare function parseBody<T>(event: APIGatewayProxyEvent): T;
+/**
+ * Get a required path parameter from the event.
+ *
+ * @param event - API Gateway proxy event
+ * @param name - Name of the path parameter
+ * @returns The path parameter value
+ * @throws {ValidationError} If the parameter is missing
+ *
+ * @example
+ * ```typescript
+ * // Route: GET /users/{id}
+ * const handler: Handler = async (event) => {
+ *   const userId = requirePathParam(event, 'id');
+ *   // userId is guaranteed to be a string
+ * };
+ * ```
+ */
+export declare function requirePathParam(event: APIGatewayProxyEvent, name: string): string;
+/**
+ * Get an optional query parameter from the event.
+ *
+ * @param event - API Gateway proxy event
+ * @param name - Name of the query parameter
+ * @param defaultValue - Optional default value if parameter is missing
+ * @returns The query parameter value or default
+ *
+ * @example
+ * ```typescript
+ * // GET /users?limit=10&status=active
+ * const handler: Handler = async (event) => {
+ *   const limit = getQueryParam(event, 'limit', '20');  // '10' or '20' default
+ *   const status = getQueryParam(event, 'status');       // 'active' or undefined
+ * };
+ * ```
+ */
+export declare function getQueryParam(
+  event: APIGatewayProxyEvent,
+  name: string,
+  defaultValue?: string
+): string | undefined;
+/**
+ * Get user ID from an authenticated request.
+ *
+ * Extracts the Cognito user ID (sub claim) from the request context.
+ *
+ * @param event - Authenticated API Gateway event
+ * @returns The user ID from the JWT token
+ * @throws {UnauthorizedError} If user ID is not found in the token
+ *
+ * @example
+ * ```typescript
+ * const handler: AuthenticatedHandler = async (event) => {
+ *   const userId = getUserId(event);
+ *   // userId is the Cognito 'sub' claim
+ * };
+ * ```
+ */
+export declare function getUserId(event: AuthenticatedEvent): string;
+//# sourceMappingURL=request.d.ts.map

package/lib/lib/request.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request.d.ts","sourceRoot":"","sources":["../../src/lib/request.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAEvD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAEvD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,KAAK,EAAE,oBAAoB,GAAG,CAAC,CAU3D;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,oBAAoB,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAMlF;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,oBAAoB,EAC3B,IAAI,EAAE,MAAM,EACZ,YAAY,CAAC,EAAE,MAAM,GACpB,MAAM,GAAG,SAAS,CAEpB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,kBAAkB,GAAG,MAAM,CAM3D"}

package/lib/lib/request.js

@@ -0,0 +1,115 @@
+"use strict";
+/**
+ * Request parsing utilities for Lambda handlers.
+ *
+ * Provides type-safe extraction of request data including
+ * JSON body parsing, path parameters, and query parameters.
+ *
+ * @packageDocumentation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseBody = parseBody;
+exports.requirePathParam = requirePathParam;
+exports.getQueryParam = getQueryParam;
+exports.getUserId = getUserId;
+const errors_1 = require("./errors");
+/**
+ * Parse JSON body from API Gateway event.
+ *
+ * @param event - API Gateway proxy event
+ * @returns Parsed JSON body as type T
+ * @throws {ValidationError} If body is missing or invalid JSON
+ *
+ * @example
+ * ```typescript
+ * interface CreateUserBody {
+ *   name: string;
+ *   email: string;
+ * }
+ *
+ * const handler: Handler = async (event) => {
+ *   const body = parseBody<CreateUserBody>(event);
+ *   // body is typed as CreateUserBody
+ * };
+ * ```
+ */
+function parseBody(event) {
+    if (!event.body) {
+        throw new errors_1.ValidationError('Request body is required');
+    }
+    try {
+        return JSON.parse(event.body);
+    }
+    catch {
+        throw new errors_1.ValidationError('Invalid JSON in request body');
+    }
+}
+/**
+ * Get a required path parameter from the event.
+ *
+ * @param event - API Gateway proxy event
+ * @param name - Name of the path parameter
+ * @returns The path parameter value
+ * @throws {ValidationError} If the parameter is missing
+ *
+ * @example
+ * ```typescript
+ * // Route: GET /users/{id}
+ * const handler: Handler = async (event) => {
+ *   const userId = requirePathParam(event, 'id');
+ *   // userId is guaranteed to be a string
+ * };
+ * ```
+ */
+function requirePathParam(event, name) {
+    const value = event.pathParameters?.[name];
+    if (!value) {
+        throw new errors_1.ValidationError(`Missing path parameter: ${name}`);
+    }
+    return value;
+}
+/**
+ * Get an optional query parameter from the event.
+ *
+ * @param event - API Gateway proxy event
+ * @param name - Name of the query parameter
+ * @param defaultValue - Optional default value if parameter is missing
+ * @returns The query parameter value or default
+ *
+ * @example
+ * ```typescript
+ * // GET /users?limit=10&status=active
+ * const handler: Handler = async (event) => {
+ *   const limit = getQueryParam(event, 'limit', '20');  // '10' or '20' default
+ *   const status = getQueryParam(event, 'status');       // 'active' or undefined
+ * };
+ * ```
+ */
+function getQueryParam(event, name, defaultValue) {
+    return event.queryStringParameters?.[name] ?? defaultValue;
+}
+/**
+ * Get user ID from an authenticated request.
+ *
+ * Extracts the Cognito user ID (sub claim) from the request context.
+ *
+ * @param event - Authenticated API Gateway event
+ * @returns The user ID from the JWT token
+ * @throws {UnauthorizedError} If user ID is not found in the token
+ *
+ * @example
+ * ```typescript
+ * const handler: AuthenticatedHandler = async (event) => {
+ *   const userId = getUserId(event);
+ *   // userId is the Cognito 'sub' claim
+ * };
+ * ```
+ */
+function getUserId(event) {
+    const userId = event.requestContext.authorizer?.claims?.sub;
+    if (!userId) {
+        throw new errors_1.UnauthorizedError('User ID not found in token');
+    }
+    return userId;
+}
+//# sourceMappingURL=request.js.map

package/lib/lib/request.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"request.js","sourceRoot":"","sources":["../../src/lib/request.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;AA0BH,8BAUC;AAmBD,4CAMC;AAmBD,sCAMC;AAmBD,8BAMC;AA5GD,qCAA8D;AAG9D;;;;;;;;;;;;;;;;;;;GAmBG;AACH,SAAgB,SAAS,CAAI,KAA2B;IACtD,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;QAChB,MAAM,IAAI,wBAAe,CAAC,0BAA0B,CAAC,CAAC;IACxD,CAAC;IAED,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAM,CAAC;IACrC,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,wBAAe,CAAC,8BAA8B,CAAC,CAAC;IAC5D,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,SAAgB,gBAAgB,CAAC,KAA2B,EAAE,IAAY;IACxE,MAAM,KAAK,GAAG,KAAK,CAAC,cAAc,EAAE,CAAC,IAAI,CAAC,CAAC;IAC3C,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,wBAAe,CAAC,2BAA2B,IAAI,EAAE,CAAC,CAAC;IAC/D,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,SAAgB,aAAa,CAC3B,KAA2B,EAC3B,IAAY,EACZ,YAAqB;IAErB,OAAO,KAAK,CAAC,qBAAqB,EAAE,CAAC,IAAI,CAAC,IAAI,YAAY,CAAC;AAC7D,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,SAAgB,SAAS,CAAC,KAAyB;IACjD,MAAM,MAAM,GAAG,KAAK,CAAC,cAAc,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,CAAC;IAC5D,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,0BAAiB,CAAC,4BAA4B,CAAC,CAAC;IAC5D,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}