@incloodsolutions/devkit 0.0.2 → 0.0.4

package/README.md

@@ -1,58 +1,167 @@
 # @incloodsolutions/devkit
 
 [![npm version](https://img.shields.io/npm/v/@incloodsolutions/devkit.svg?style=for-the-badge)](https://www.npmjs.com/package/@incloodsolutions/devkit)
-[![npm dm](https://img.shields.io/npm/dm/@incloodsolutions/devkit.svg?style=for-the-badge)](https://www.npmjs.com/package/@incloodsolutions/devkit)
-[![downloads](https://img.shields.io/npm/dt/@incloodsolutions/devkit.svg?style=for-the-badge)](https://www.npmjs.com/package/@incloodsolutions/devkit)
+[![npm downloads](https://img.shields.io/npm/dm/@incloodsolutions/devkit.svg?style=for-the-badge)](https://www.npmjs.com/package/@incloodsolutions/devkit)
 [![license](https://img.shields.io/npm/l/@incloodsolutions/devkit.svg?style=for-the-badge)](https://www.npmjs.com/package/@incloodsolutions/devkit)
 
-A comprehensive development toolkit for Node.js and TypeScript applications. It provides reusable development utilities, configuration helpers, AWS CDK constructs and stacks, build tooling, project scaffolding, and other resources to simplify modern application development and infrastructure management.
+Opinionated **AWS CDK v2 constructs** with sensible defaults for building serverless
+applications. Each construct wraps one or more `aws-cdk-lib` resources, applies defaults
+(ARM64, current Node.js runtime, source maps, stage-based timeouts, CloudFormation
+outputs), and exposes the underlying resource for further customisation.
+
+> For a one-line index of every construct and type in this package (and the other
+> toolkits), see [`../docs/AI-INDEX.md`](../docs/AI-INDEX.md). Every construct, its props
+> interface, and the created resource fields carry inline TSDoc comments describing the
+> applied defaults.
 
 ---
 
-## 📦 Installation
+## Installation
 
 ```bash
-npm install @incloodsolutions/devkit
-# or
-yarn add @incloodsolutions/devkit
+npm install @incloodsolutions/devkit aws-cdk-lib constructs
 ```
 
-## 🚀 Usage
+Depends on `aws-cdk-lib`, `constructs`, `esbuild`, and
+[`@incloodsolutions/toolkit`](../toolkit).
+
+> **Scope note.** Only the AWS CDK constructs and their types are currently exported. The
+> `src/utility`, `src/lint`, `src/prettier`, and `src/aws/cli` folders are placeholders and
+> export nothing yet, despite what older documentation suggested.
+
+## Common props
+
+Every construct constructor is `new XxxConstruct(scope, id, props)`. `props` is based on
+`IBaseCdkConstructProps`:
 
 ```typescript
-import { EnvironmentHelper } from "@incloodsolutions/devkit";
+interface IBaseCdkConstructProps<TOptions = any> {
+  readonly stage?: AppEnvironmentType;   // 'production' | 'staging' | 'qa' | ...
+  readonly options?: TOptions;           // the service-specific options (see each construct)
+  readonly stackName?: string;
+  readonly appName?: string;
+  readonly enableDebug?: boolean;
+}
+```
+
+The created resource is exposed as a public readonly field (`.function`, `.api`, `.table`,
+`.topic`, `.queue`, `.layer`, `.distribution`, ...).
+
+## Modular imports (tree-shaking)
+
+**There is no package-root import.** `import ... from '@incloodsolutions/devkit'` does not
+resolve — you must import a specific subpath. Every construct is published as its own
+subpath, so a stack that uses one construct does not bundle the code for all seventeen:
 
-// Example usage
-const env = EnvironmentHelper.load();
+```typescript
+import { BaseLambdaConstruct } from '@incloodsolutions/devkit/aws-cdk/lambda';
+import { BaseDynamoDBConstruct } from '@incloodsolutions/devkit/aws-cdk/dynamo-db';
+import type { IBaseCdkConstructProps } from '@incloodsolutions/devkit/aws-types';
 ```
 
-## ✨ Features
-
-- ⚙️ Node.js development utilities
-- 📝 Configuration management
-- 🏗️ AWS CDK constructs
-- ☁️ Reusable AWS CDK stacks
-- 🛠️ Infrastructure helpers
-- 🔐 IAM, Route53, ACM, Lambda, API Gateway, S3 & DynamoDB utilities
-- 🏷️ Resource naming & tagging helpers
-- 📁 Project templates & scaffolding
-- 🧩 Build & release utilities
-- 🔧 Development tooling and helpers
-- 💙 First-class TypeScript support
-
-## 🎯 Goals
-
-- Reduce development and infrastructure boilerplate
-- Standardise project structure and configuration
-- Promote reusable infrastructure components
-- Simplify AWS CDK development
-- Improve developer productivity
-- Encourage consistency across projects
-- Provide sensible defaults while remaining extensible
-
-## 📚 Part of the IncloodSolutions Toolkit Ecosystem
-
-- **@incloodsolutions/toolkit** — Core utilities and shared helpers
-- **@incloodsolutions/node-toolkit** — Node.js runtime and backend utilities
-- **@incloodsolutions/toolkit-react** — React utilities and components
-- **@incloodsolutions/devkit** — Development tooling, configuration, AWS CDK constructs, stacks, and infrastructure utilities
+| Subpath | Contents |
+| ------- | -------- |
+| `.../aws` · `.../aws-cdk` | all `Base*` constructs |
+| `.../aws-cdk/<name>` | one construct — `api-gateway`, `api-gateway-v2`, `api-gateway-websocket`, `cloudfront`, `cloudwatch`, `dynamo-db`, `event-bridge`, `lambda`, `lambda-authorizer`, `lambda-authorizer-v2`, `lambda-layer`, `role-policy`, `s3`, `s3-deployment`, `sns`, `sqs`, `vpc` |
+| `.../aws-types` | `IBaseConstruct`, `IBaseCdkConstructProps` |
+
+Every subpath resolves ESM (`import`), CommonJS (`require`), and its own `.d.ts`.
+`aws-cdk-lib` and `constructs` stay external in every bundle.
+
+## Constructs
+
+| Construct | Wraps | Notable defaults |
+| --------- | ----- | ---------------- |
+| `BaseLambdaConstruct` | `aws-lambda.Function` | Node.js 24, ARM64, 1024 MB, `Code.fromAsset('dist')`, handler `lambda.handler`, timeout 30 s (prod) / 15 s, `--enable-source-maps`, injects `NODE_ENV` from `stage`, validates env vars for duplicates. Exposes `.function`. |
+| `BaseLambdaLayerConstruct` | `aws-lambda.LayerVersion` | Create new or import via `fromExistingLayerArn` / `fromExistingLayerAttribute`. Exposes `.layer` / `.existingLayer`. |
+| `BaseApiGatewayConstruct` | `aws-apigateway.RestApi` | REST API with Lambda proxy integration and permissive CORS. |
+| `BaseApiGatewayV2Construct` | `aws-apigatewayv2.HttpApi` | HTTP API; takes `handlerFunctions` and `routeOptions`. Exposes `.api`. |
+| `BaseApiGatewayWebSocketConstruct` | `aws-apigatewayv2.WebSocketApi` + `WebSocketStage` | Lambda route integrations for `$connect` / `$disconnect` / custom routes. |
+| `BaseLambdaAuthoriserConstruct` | `aws-apigateway.TokenAuthorizer` | REST API token authorizer backed by a Lambda. |
+| `BaseLambdaAuthoriserV2Construct` | `aws-apigatewayv2-authorizers.HttpLambdaAuthorizer` | HTTP API Lambda authorizer. |
+| `BaseDynamoDBConstruct` | `aws-dynamodb.Table` | Create new or import (`fromExistingTableArn` / `Name` / `Attributes`); `globalSecondaryIndexes` / `localSecondaryIndexes`. Exposes `.table` / `.existingTable`. |
+| `BaseS3Construct` | `aws-s3.Bucket` | Bucket with defaults. |
+| `BaseS3DeploymentConstruct` | S3 `Bucket` + CloudFront `Distribution` + `BucketDeployment` | Static-site deploy; toggles `withS3Bucket` / `withCloudfront`; `bucketDeploymentOptions.sources` required. |
+| `BaseCloudfrontConstruct` | `aws-cloudfront.Distribution` | Distribution with `ViewerProtocolPolicy` default. |
+| `BaseCloudwatchLogGroupConstruct` | `aws-logs.LogGroup` | Log group with retention. |
+| `BaseSnsConstruct` | `aws-sns.Topic` | Optional `targetFunctions` as `LambdaSubscription`. Exposes `.topic`. |
+| `BaseSqsConstruct` | `aws-sqs.Queue` | Optional Lambda `EventSourceMapping`. Exposes `.queue`. |
+| `BaseEventBridgeConstruct` | `aws-events.Rule` | Rule with a Lambda target. |
+| `BaseVpcConstruct` | `aws-ec2.Vpc` | VPC with defaults. |
+| `BaseRolePolicyConstruct` | `aws-iam.Role` + `PolicyStatement` / `ManagedPolicy` | IAM role and policy helper. |
+
+## Types
+
+| Symbol | Summary |
+| ------ | ------- |
+| `IBaseConstruct` | extends `IBaseEnableDebug`. |
+| `IBaseCdkConstructProps<TOptions>` | shared construct props (see above). |
+
+## Usage
+
+```typescript
+import { Stack, StackProps } from 'aws-cdk-lib';
+import { Construct } from 'constructs';
+import { BaseLambdaConstruct } from '@incloodsolutions/devkit/aws-cdk/lambda';
+import { BaseApiGatewayV2Construct } from '@incloodsolutions/devkit/aws-cdk/api-gateway-v2';
+import { BaseDynamoDBConstruct } from '@incloodsolutions/devkit/aws-cdk/dynamo-db';
+
+export class ApiStack extends Stack {
+  constructor(scope: Construct, id: string, props?: StackProps) {
+    super(scope, id, props);
+
+    const table = new BaseDynamoDBConstruct(this, 'Table', {
+      stage: 'production',
+      stackName: this.stackName,
+      options: { tableOptions: { partitionKey: { name: 'id', type: AttributeType.STRING } } },
+    });
+
+    const handler = new BaseLambdaConstruct(this, 'Handler', {
+      stage: 'production',
+      stackName: this.stackName,
+      options: { lambdaOptions: { environment: { TABLE_NAME: table.table.tableName } } },
+    });
+
+    table.table.grantReadWriteData(handler.function);
+
+    new BaseApiGatewayV2Construct(this, 'Api', {
+      stage: 'production',
+      stackName: this.stackName,
+      options: {
+        handlerFunctions: [handler.function],
+        routeOptions: [{ path: '/{proxy+}' }],
+      },
+    });
+  }
+}
+```
+
+## Development
+
+```bash
+npm install
+npm run build      # tsup: bundles ESM + CJS and a single dist/index.d.ts
+npm run format     # prettier --write (tabs, single quotes, trailing commas)
+npm run lint       # eslint --fix
+npm test           # vitest run — synthesises every construct and asserts its CloudFormation
+npm run test:watch # vitest in watch mode
+npm run package    # build, then npm pack a tarball
+```
+
+[`test/constructs.spec.ts`](./test/constructs.spec.ts) instantiates each `Base*` construct
+in a throwaway `Stack` and checks the output with `aws-cdk-lib/assertions` (`Template`).
+Nothing is deployed and no AWS credentials are used. Its header comment records the
+constructs that need extra props or currently throw.
+[`test/esm-bundle.spec.ts`](./test/esm-bundle.spec.ts) guards that every subpath entry is
+built, loads as ESM, and keeps `aws-cdk-lib` / `constructs` external.
+
+> The whole build is `tsup` (`dts: true`), pinned to `typescript@^6`. There is **no root
+> export** and no `main`/`module`/`types` fields — every module and every construct is a
+> `./*` subpath in `exports` (see [Modular imports](#modular-imports-tree-shaking)),
+> configured by the `entry` map in `tsup.config.ts` and `exports` + `typesVersions` in
+> `package.json`. The `index` bundle is still built as the test aggregation point but is
+> not reachable by the package name.
+
+## License
+
+MIT © Inclood Solutions

package/dist/aws-cdk/api-gateway-v2.cjs

@@ -0,0 +1,77 @@
+'use strict';
+
+var constructs = require('constructs');
+var awsCdkLib = require('aws-cdk-lib');
+var awsApigatewayv2Integrations = require('aws-cdk-lib/aws-apigatewayv2-integrations');
+var awsApigatewayv2 = require('aws-cdk-lib/aws-apigatewayv2');
+var toolkit = require('@incloodsolutions/toolkit');
+
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+var BaseApiGatewayV2Construct = class extends constructs.Construct {
+  static {
+    __name(this, "BaseApiGatewayV2Construct");
+  }
+  /** The created HTTP API instance */
+  api;
+  /** Enables debug logging (if used externally) */
+  enableDebug = false;
+  /**
+   * @param scope Parent construct
+   * @param id Unique construct identifier
+   * @param props Configuration for API, routes, and handlers
+   */
+  constructor(scope, id, props) {
+    super(scope, id);
+    this.enableDebug = props.enableDebug;
+    this.api = new awsApigatewayv2.HttpApi(this, id, {
+      ...props?.options?.gatewayOptions,
+      /** Default API description if not provided */
+      description: props?.options?.gatewayOptions?.description || "This is an Http API using CDK",
+      /**
+       * CORS configuration
+       * Falls back to allowing all methods and standard headers if not explicitly defined
+       */
+      corsPreflight: {
+        ...props.options?.gatewayOptions?.corsPreflight,
+        /** Allow all HTTP methods by default */
+        allowMethods: props.options?.gatewayOptions?.corsPreflight?.allowMethods || Object.values(awsApigatewayv2.CorsHttpMethod),
+        /** Merge default headers with user-defined headers */
+        allowHeaders: [
+          "Content-Type",
+          "Accept",
+          "X-Amz-Date",
+          "Authorization",
+          "X-Api-Key",
+          "X-Amz-Security-Token",
+          "X-Amz-User-Agent",
+          ...props.options?.gatewayOptions?.corsPreflight?.allowHeaders || []
+        ]
+      }
+    });
+    if (!props?.handlerFunctions?.length) {
+      throw new toolkit.CustomException("Construct requires atleast one function");
+    }
+    if (props?.options?.routeOptions?.length) {
+      props.handlerFunctions.forEach((handlerFunc) => {
+        props?.options?.routeOptions.forEach((route) => {
+          this.api.addRoutes({
+            ...route,
+            /**
+             * Lambda integration for each route
+             */
+            integration: new awsApigatewayv2Integrations.HttpLambdaIntegration("routes", handlerFunc)
+          });
+        });
+      });
+    }
+    this.api.applyRemovalPolicy(awsCdkLib.RemovalPolicy.DESTROY);
+    new awsCdkLib.CfnOutput(this, "ApiGatewayV2", {
+      value: this.api.url
+    });
+  }
+};
+
+exports.BaseApiGatewayV2Construct = BaseApiGatewayV2Construct;
+//# sourceMappingURL=api-gateway-v2.cjs.map
+//# sourceMappingURL=api-gateway-v2.cjs.map

package/dist/aws-cdk/api-gateway-v2.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/aws/cdk/constructs/api-gateway-v2-construct.ts"],"names":["Construct","HttpApi","CorsHttpMethod","CustomException","HttpLambdaIntegration","RemovalPolicy","CfnOutput"],"mappings":";;;;;;;;;;AAsDO,IAAM,yBAAA,GAAN,cACEA,oBAAA,CAET;AAAA,EAzDA;AAyDA,IAAA,MAAA,CAAA,IAAA,EAAA,2BAAA,CAAA;AAAA;AAAA;AAAA,EAEU,GAAA;AAAA;AAAA,EAGT,WAAA,GAAc,KAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOd,WAAA,CACC,KAAA,EACA,EAAA,EACA,KAAA,EACC;AACD,IAAA,KAAA,CAAM,OAAO,EAAE,CAAA;AAEf,IAAA,IAAA,CAAK,cAAc,KAAA,CAAM,WAAA;AAEzB,IAAA,IAAA,CAAK,GAAA,GAAM,IAAIC,uBAAA,CAAQ,IAAA,EAAM,EAAA,EAAI;AAAA,MAChC,GAAG,OAAO,OAAA,EAAS,cAAA;AAAA;AAAA,MAGnB,WAAA,EACC,KAAA,EAAO,OAAA,EAAS,cAAA,EAAgB,WAAA,IAChC,+BAAA;AAAA;AAAA;AAAA;AAAA;AAAA,MAMD,aAAA,EAAe;AAAA,QACd,GAAG,KAAA,CAAM,OAAA,EAAS,cAAA,EAAgB,aAAA;AAAA;AAAA,QAGlC,YAAA,EACC,MAAM,OAAA,EAAS,cAAA,EAAgB,eAAe,YAAA,IAC9C,MAAA,CAAO,OAAOC,8BAAc,CAAA;AAAA;AAAA,QAG7B,YAAA,EAAc;AAAA,UACb,cAAA;AAAA,UACA,QAAA;AAAA,UACA,YAAA;AAAA,UACA,eAAA;AAAA,UACA,WAAA;AAAA,UACA,sBAAA;AAAA,UACA,kBAAA;AAAA,UACA,GAAI,KAAA,CAAM,OAAA,EAAS,cAAA,EAAgB,aAAA,EAAe,gBAAgB;AAAC;AACpE;AACD,KACA,CAAA;AAKD,IAAA,IAAI,CAAC,KAAA,EAAO,gBAAA,EAAkB,MAAA,EAAQ;AACrC,MAAA,MAAM,IAAIC,wBAAgB,yCAAyC,CAAA;AAAA,IACpE;AAKA,IAAA,IAAI,KAAA,EAAO,OAAA,EAAS,YAAA,EAAc,MAAA,EAAQ;AACzC,MAAA,KAAA,CAAM,gBAAA,CAAiB,OAAA,CAAQ,CAAC,WAAA,KAAgB;AAC/C,QAAA,KAAA,EAAO,OAAA,EAAS,YAAA,CAAa,OAAA,CAAQ,CAAC,KAAA,KAAU;AAC/C,UAAA,IAAA,CAAK,IAAI,SAAA,CAAU;AAAA,YAClB,GAAG,KAAA;AAAA;AAAA;AAAA;AAAA,YAKH,WAAA,EAAa,IAAIC,iDAAA,CAAsB,QAAA,EAAU,WAAW;AAAA,WACxC,CAAA;AAAA,QACtB,CAAC,CAAA;AAAA,MACF,CAAC,CAAA;AAAA,IACF;AAKA,IAAA,IAAA,CAAK,GAAA,CAAI,kBAAA,CAAmBC,uBAAA,CAAc,OAAO,CAAA;AAKjD,IAAA,IAAIC,mBAAA,CAAU,MAAM,cAAA,EAAgB;AAAA,MACnC,KAAA,EAAO,KAAK,GAAA,CAAI;AAAA,KAChB,CAAA;AAAA,EACF;AACD","file":"api-gateway-v2.cjs","sourcesContent":["import { Construct } from 'constructs';\nimport { Function } from 'aws-cdk-lib/aws-lambda';\nimport { CfnOutput, RemovalPolicy } from 'aws-cdk-lib';\nimport { HttpLambdaIntegration } from 'aws-cdk-lib/aws-apigatewayv2-integrations';\nimport {\n\tAddRoutesOptions,\n\tCorsHttpMethod,\n\tHttpApi,\n\tHttpApiProps,\n} from 'aws-cdk-lib/aws-apigatewayv2';\n\nimport { CustomException } from '@incloodsolutions/toolkit';\nimport { IBaseCdkConstructProps, IBaseConstruct } from '../../types';\n\n/**\n * Properties for configuring the API Gateway v2 construct\n *\n * Extends base CDK construct props and provides configuration for:\n * - HTTP API (Api Gateway v2)\n * - Route definitions\n * - Lambda handlers\n */\ninterface IApiGatewayV2ConstructProps extends Omit<\n\tIBaseCdkConstructProps<{\n\t\t/** HTTP API configuration options */\n\t\treadonly gatewayOptions: HttpApiProps;\n\n\t\t/** Route definitions passed directly to `addRoutes` */\n\t\treadonly routeOptions: Partial<AddRoutesOptions>[];\n\t}>,\n\t'appName' | 'stage' | 'stackName'\n> {\n\t/**\n\t * Lambda functions used as route handlers\n\t *\n\t * Note:\n\t * Each handler is paired with each route during route creation\n\t */\n\treadonly handlerFunctions: Function[];\n}\n\n/**\n * CDK construct for creating an API Gateway v2 (HTTP API)\n *\n * Responsibilities:\n * - Creates an HTTP API with optional custom configuration\n * - Applies default CORS configuration when not provided\n * - Attaches routes with Lambda integrations\n * - Exposes API URL as a CloudFormation output\n *\n * Behaviour:\n * - Each route is registered for every provided handler function\n * - Throws if no handler functions are supplied\n */\nexport class BaseApiGatewayV2Construct\n\textends Construct\n\timplements IBaseConstruct\n{\n\t/** The created HTTP API instance */\n\treadonly api: HttpApi;\n\n\t/** Enables debug logging (if used externally) */\n\tenableDebug = false;\n\n\t/**\n\t * @param scope Parent construct\n\t * @param id Unique construct identifier\n\t * @param props Configuration for API, routes, and handlers\n\t */\n\tconstructor(\n\t\tscope: Construct,\n\t\tid: string,\n\t\tprops: IApiGatewayV2ConstructProps,\n\t) {\n\t\tsuper(scope, id);\n\n\t\tthis.enableDebug = props.enableDebug;\n\n\t\tthis.api = new HttpApi(this, id, {\n\t\t\t...props?.options?.gatewayOptions,\n\n\t\t\t/** Default API description if not provided */\n\t\t\tdescription:\n\t\t\t\tprops?.options?.gatewayOptions?.description ||\n\t\t\t\t'This is an Http API using CDK',\n\n\t\t\t/**\n\t\t\t * CORS configuration\n\t\t\t * Falls back to allowing all methods and standard headers if not explicitly defined\n\t\t\t */\n\t\t\tcorsPreflight: {\n\t\t\t\t...props.options?.gatewayOptions?.corsPreflight,\n\n\t\t\t\t/** Allow all HTTP methods by default */\n\t\t\t\tallowMethods:\n\t\t\t\t\tprops.options?.gatewayOptions?.corsPreflight?.allowMethods ||\n\t\t\t\t\tObject.values(CorsHttpMethod),\n\n\t\t\t\t/** Merge default headers with user-defined headers */\n\t\t\t\tallowHeaders: [\n\t\t\t\t\t'Content-Type',\n\t\t\t\t\t'Accept',\n\t\t\t\t\t'X-Amz-Date',\n\t\t\t\t\t'Authorization',\n\t\t\t\t\t'X-Api-Key',\n\t\t\t\t\t'X-Amz-Security-Token',\n\t\t\t\t\t'X-Amz-User-Agent',\n\t\t\t\t\t...(props.options?.gatewayOptions?.corsPreflight?.allowHeaders || []),\n\t\t\t\t],\n\t\t\t},\n\t\t});\n\n\t\t/**\n\t\t * Ensure at least one handler function is provided\n\t\t */\n\t\tif (!props?.handlerFunctions?.length) {\n\t\t\tthrow new CustomException('Construct requires atleast one function');\n\t\t}\n\n\t\t/**\n\t\t * Register routes with Lambda integrations\n\t\t */\n\t\tif (props?.options?.routeOptions?.length) {\n\t\t\tprops.handlerFunctions.forEach((handlerFunc) => {\n\t\t\t\tprops?.options?.routeOptions.forEach((route) => {\n\t\t\t\t\tthis.api.addRoutes({\n\t\t\t\t\t\t...route,\n\n\t\t\t\t\t\t/**\n\t\t\t\t\t\t * Lambda integration for each route\n\t\t\t\t\t\t */\n\t\t\t\t\t\tintegration: new HttpLambdaIntegration('routes', handlerFunc),\n\t\t\t\t\t} as AddRoutesOptions);\n\t\t\t\t});\n\t\t\t});\n\t\t}\n\n\t\t/**\n\t\t * Apply removal policy (useful for non-production environments)\n\t\t */\n\t\tthis.api.applyRemovalPolicy(RemovalPolicy.DESTROY);\n\n\t\t/**\n\t\t * CloudFormation output exposing the API base URL\n\t\t */\n\t\tnew CfnOutput(this, 'ApiGatewayV2', {\n\t\t\tvalue: this.api.url,\n\t\t});\n\t}\n}\n"]}

package/dist/aws-cdk/api-gateway-v2.d.cts

@@ -0,0 +1,55 @@
+import { Construct } from 'constructs';
+import { Function } from 'aws-cdk-lib/aws-lambda';
+import { HttpApi, HttpApiProps, AddRoutesOptions } from 'aws-cdk-lib/aws-apigatewayv2';
+import { IBaseConstruct, IBaseCdkConstructProps } from '../aws-types.cjs';
+import '@incloodsolutions/toolkit';
+
+/**
+ * Properties for configuring the API Gateway v2 construct
+ *
+ * Extends base CDK construct props and provides configuration for:
+ * - HTTP API (Api Gateway v2)
+ * - Route definitions
+ * - Lambda handlers
+ */
+interface IApiGatewayV2ConstructProps extends Omit<IBaseCdkConstructProps<{
+    /** HTTP API configuration options */
+    readonly gatewayOptions: HttpApiProps;
+    /** Route definitions passed directly to `addRoutes` */
+    readonly routeOptions: Partial<AddRoutesOptions>[];
+}>, 'appName' | 'stage' | 'stackName'> {
+    /**
+     * Lambda functions used as route handlers
+     *
+     * Note:
+     * Each handler is paired with each route during route creation
+     */
+    readonly handlerFunctions: Function[];
+}
+/**
+ * CDK construct for creating an API Gateway v2 (HTTP API)
+ *
+ * Responsibilities:
+ * - Creates an HTTP API with optional custom configuration
+ * - Applies default CORS configuration when not provided
+ * - Attaches routes with Lambda integrations
+ * - Exposes API URL as a CloudFormation output
+ *
+ * Behaviour:
+ * - Each route is registered for every provided handler function
+ * - Throws if no handler functions are supplied
+ */
+declare class BaseApiGatewayV2Construct extends Construct implements IBaseConstruct {
+    /** The created HTTP API instance */
+    readonly api: HttpApi;
+    /** Enables debug logging (if used externally) */
+    enableDebug: boolean;
+    /**
+     * @param scope Parent construct
+     * @param id Unique construct identifier
+     * @param props Configuration for API, routes, and handlers
+     */
+    constructor(scope: Construct, id: string, props: IApiGatewayV2ConstructProps);
+}
+
+export { BaseApiGatewayV2Construct };

package/dist/aws-cdk/api-gateway-v2.d.ts

@@ -0,0 +1,55 @@
+import { Construct } from 'constructs';
+import { Function } from 'aws-cdk-lib/aws-lambda';
+import { HttpApi, HttpApiProps, AddRoutesOptions } from 'aws-cdk-lib/aws-apigatewayv2';
+import { IBaseConstruct, IBaseCdkConstructProps } from '../aws-types.js';
+import '@incloodsolutions/toolkit';
+
+/**
+ * Properties for configuring the API Gateway v2 construct
+ *
+ * Extends base CDK construct props and provides configuration for:
+ * - HTTP API (Api Gateway v2)
+ * - Route definitions
+ * - Lambda handlers
+ */
+interface IApiGatewayV2ConstructProps extends Omit<IBaseCdkConstructProps<{
+    /** HTTP API configuration options */
+    readonly gatewayOptions: HttpApiProps;
+    /** Route definitions passed directly to `addRoutes` */
+    readonly routeOptions: Partial<AddRoutesOptions>[];
+}>, 'appName' | 'stage' | 'stackName'> {
+    /**
+     * Lambda functions used as route handlers
+     *
+     * Note:
+     * Each handler is paired with each route during route creation
+     */
+    readonly handlerFunctions: Function[];
+}
+/**
+ * CDK construct for creating an API Gateway v2 (HTTP API)
+ *
+ * Responsibilities:
+ * - Creates an HTTP API with optional custom configuration
+ * - Applies default CORS configuration when not provided
+ * - Attaches routes with Lambda integrations
+ * - Exposes API URL as a CloudFormation output
+ *
+ * Behaviour:
+ * - Each route is registered for every provided handler function
+ * - Throws if no handler functions are supplied
+ */
+declare class BaseApiGatewayV2Construct extends Construct implements IBaseConstruct {
+    /** The created HTTP API instance */
+    readonly api: HttpApi;
+    /** Enables debug logging (if used externally) */
+    enableDebug: boolean;
+    /**
+     * @param scope Parent construct
+     * @param id Unique construct identifier
+     * @param props Configuration for API, routes, and handlers
+     */
+    constructor(scope: Construct, id: string, props: IApiGatewayV2ConstructProps);
+}
+
+export { BaseApiGatewayV2Construct };

package/dist/aws-cdk/api-gateway-v2.js

@@ -0,0 +1,75 @@
+import { Construct } from 'constructs';
+import { RemovalPolicy, CfnOutput } from 'aws-cdk-lib';
+import { HttpLambdaIntegration } from 'aws-cdk-lib/aws-apigatewayv2-integrations';
+import { HttpApi, CorsHttpMethod } from 'aws-cdk-lib/aws-apigatewayv2';
+import { CustomException } from '@incloodsolutions/toolkit';
+
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+var BaseApiGatewayV2Construct = class extends Construct {
+  static {
+    __name(this, "BaseApiGatewayV2Construct");
+  }
+  /** The created HTTP API instance */
+  api;
+  /** Enables debug logging (if used externally) */
+  enableDebug = false;
+  /**
+   * @param scope Parent construct
+   * @param id Unique construct identifier
+   * @param props Configuration for API, routes, and handlers
+   */
+  constructor(scope, id, props) {
+    super(scope, id);
+    this.enableDebug = props.enableDebug;
+    this.api = new HttpApi(this, id, {
+      ...props?.options?.gatewayOptions,
+      /** Default API description if not provided */
+      description: props?.options?.gatewayOptions?.description || "This is an Http API using CDK",
+      /**
+       * CORS configuration
+       * Falls back to allowing all methods and standard headers if not explicitly defined
+       */
+      corsPreflight: {
+        ...props.options?.gatewayOptions?.corsPreflight,
+        /** Allow all HTTP methods by default */
+        allowMethods: props.options?.gatewayOptions?.corsPreflight?.allowMethods || Object.values(CorsHttpMethod),
+        /** Merge default headers with user-defined headers */
+        allowHeaders: [
+          "Content-Type",
+          "Accept",
+          "X-Amz-Date",
+          "Authorization",
+          "X-Api-Key",
+          "X-Amz-Security-Token",
+          "X-Amz-User-Agent",
+          ...props.options?.gatewayOptions?.corsPreflight?.allowHeaders || []
+        ]
+      }
+    });
+    if (!props?.handlerFunctions?.length) {
+      throw new CustomException("Construct requires atleast one function");
+    }
+    if (props?.options?.routeOptions?.length) {
+      props.handlerFunctions.forEach((handlerFunc) => {
+        props?.options?.routeOptions.forEach((route) => {
+          this.api.addRoutes({
+            ...route,
+            /**
+             * Lambda integration for each route
+             */
+            integration: new HttpLambdaIntegration("routes", handlerFunc)
+          });
+        });
+      });
+    }
+    this.api.applyRemovalPolicy(RemovalPolicy.DESTROY);
+    new CfnOutput(this, "ApiGatewayV2", {
+      value: this.api.url
+    });
+  }
+};
+
+export { BaseApiGatewayV2Construct };
+//# sourceMappingURL=api-gateway-v2.js.map
+//# sourceMappingURL=api-gateway-v2.js.map

package/dist/aws-cdk/api-gateway-v2.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/aws/cdk/constructs/api-gateway-v2-construct.ts"],"names":[],"mappings":";;;;;;;;AAsDO,IAAM,yBAAA,GAAN,cACE,SAAA,CAET;AAAA,EAzDA;AAyDA,IAAA,MAAA,CAAA,IAAA,EAAA,2BAAA,CAAA;AAAA;AAAA;AAAA,EAEU,GAAA;AAAA;AAAA,EAGT,WAAA,GAAc,KAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOd,WAAA,CACC,KAAA,EACA,EAAA,EACA,KAAA,EACC;AACD,IAAA,KAAA,CAAM,OAAO,EAAE,CAAA;AAEf,IAAA,IAAA,CAAK,cAAc,KAAA,CAAM,WAAA;AAEzB,IAAA,IAAA,CAAK,GAAA,GAAM,IAAI,OAAA,CAAQ,IAAA,EAAM,EAAA,EAAI;AAAA,MAChC,GAAG,OAAO,OAAA,EAAS,cAAA;AAAA;AAAA,MAGnB,WAAA,EACC,KAAA,EAAO,OAAA,EAAS,cAAA,EAAgB,WAAA,IAChC,+BAAA;AAAA;AAAA;AAAA;AAAA;AAAA,MAMD,aAAA,EAAe;AAAA,QACd,GAAG,KAAA,CAAM,OAAA,EAAS,cAAA,EAAgB,aAAA;AAAA;AAAA,QAGlC,YAAA,EACC,MAAM,OAAA,EAAS,cAAA,EAAgB,eAAe,YAAA,IAC9C,MAAA,CAAO,OAAO,cAAc,CAAA;AAAA;AAAA,QAG7B,YAAA,EAAc;AAAA,UACb,cAAA;AAAA,UACA,QAAA;AAAA,UACA,YAAA;AAAA,UACA,eAAA;AAAA,UACA,WAAA;AAAA,UACA,sBAAA;AAAA,UACA,kBAAA;AAAA,UACA,GAAI,KAAA,CAAM,OAAA,EAAS,cAAA,EAAgB,aAAA,EAAe,gBAAgB;AAAC;AACpE;AACD,KACA,CAAA;AAKD,IAAA,IAAI,CAAC,KAAA,EAAO,gBAAA,EAAkB,MAAA,EAAQ;AACrC,MAAA,MAAM,IAAI,gBAAgB,yCAAyC,CAAA;AAAA,IACpE;AAKA,IAAA,IAAI,KAAA,EAAO,OAAA,EAAS,YAAA,EAAc,MAAA,EAAQ;AACzC,MAAA,KAAA,CAAM,gBAAA,CAAiB,OAAA,CAAQ,CAAC,WAAA,KAAgB;AAC/C,QAAA,KAAA,EAAO,OAAA,EAAS,YAAA,CAAa,OAAA,CAAQ,CAAC,KAAA,KAAU;AAC/C,UAAA,IAAA,CAAK,IAAI,SAAA,CAAU;AAAA,YAClB,GAAG,KAAA;AAAA;AAAA;AAAA;AAAA,YAKH,WAAA,EAAa,IAAI,qBAAA,CAAsB,QAAA,EAAU,WAAW;AAAA,WACxC,CAAA;AAAA,QACtB,CAAC,CAAA;AAAA,MACF,CAAC,CAAA;AAAA,IACF;AAKA,IAAA,IAAA,CAAK,GAAA,CAAI,kBAAA,CAAmB,aAAA,CAAc,OAAO,CAAA;AAKjD,IAAA,IAAI,SAAA,CAAU,MAAM,cAAA,EAAgB;AAAA,MACnC,KAAA,EAAO,KAAK,GAAA,CAAI;AAAA,KAChB,CAAA;AAAA,EACF;AACD","file":"api-gateway-v2.js","sourcesContent":["import { Construct } from 'constructs';\nimport { Function } from 'aws-cdk-lib/aws-lambda';\nimport { CfnOutput, RemovalPolicy } from 'aws-cdk-lib';\nimport { HttpLambdaIntegration } from 'aws-cdk-lib/aws-apigatewayv2-integrations';\nimport {\n\tAddRoutesOptions,\n\tCorsHttpMethod,\n\tHttpApi,\n\tHttpApiProps,\n} from 'aws-cdk-lib/aws-apigatewayv2';\n\nimport { CustomException } from '@incloodsolutions/toolkit';\nimport { IBaseCdkConstructProps, IBaseConstruct } from '../../types';\n\n/**\n * Properties for configuring the API Gateway v2 construct\n *\n * Extends base CDK construct props and provides configuration for:\n * - HTTP API (Api Gateway v2)\n * - Route definitions\n * - Lambda handlers\n */\ninterface IApiGatewayV2ConstructProps extends Omit<\n\tIBaseCdkConstructProps<{\n\t\t/** HTTP API configuration options */\n\t\treadonly gatewayOptions: HttpApiProps;\n\n\t\t/** Route definitions passed directly to `addRoutes` */\n\t\treadonly routeOptions: Partial<AddRoutesOptions>[];\n\t}>,\n\t'appName' | 'stage' | 'stackName'\n> {\n\t/**\n\t * Lambda functions used as route handlers\n\t *\n\t * Note:\n\t * Each handler is paired with each route during route creation\n\t */\n\treadonly handlerFunctions: Function[];\n}\n\n/**\n * CDK construct for creating an API Gateway v2 (HTTP API)\n *\n * Responsibilities:\n * - Creates an HTTP API with optional custom configuration\n * - Applies default CORS configuration when not provided\n * - Attaches routes with Lambda integrations\n * - Exposes API URL as a CloudFormation output\n *\n * Behaviour:\n * - Each route is registered for every provided handler function\n * - Throws if no handler functions are supplied\n */\nexport class BaseApiGatewayV2Construct\n\textends Construct\n\timplements IBaseConstruct\n{\n\t/** The created HTTP API instance */\n\treadonly api: HttpApi;\n\n\t/** Enables debug logging (if used externally) */\n\tenableDebug = false;\n\n\t/**\n\t * @param scope Parent construct\n\t * @param id Unique construct identifier\n\t * @param props Configuration for API, routes, and handlers\n\t */\n\tconstructor(\n\t\tscope: Construct,\n\t\tid: string,\n\t\tprops: IApiGatewayV2ConstructProps,\n\t) {\n\t\tsuper(scope, id);\n\n\t\tthis.enableDebug = props.enableDebug;\n\n\t\tthis.api = new HttpApi(this, id, {\n\t\t\t...props?.options?.gatewayOptions,\n\n\t\t\t/** Default API description if not provided */\n\t\t\tdescription:\n\t\t\t\tprops?.options?.gatewayOptions?.description ||\n\t\t\t\t'This is an Http API using CDK',\n\n\t\t\t/**\n\t\t\t * CORS configuration\n\t\t\t * Falls back to allowing all methods and standard headers if not explicitly defined\n\t\t\t */\n\t\t\tcorsPreflight: {\n\t\t\t\t...props.options?.gatewayOptions?.corsPreflight,\n\n\t\t\t\t/** Allow all HTTP methods by default */\n\t\t\t\tallowMethods:\n\t\t\t\t\tprops.options?.gatewayOptions?.corsPreflight?.allowMethods ||\n\t\t\t\t\tObject.values(CorsHttpMethod),\n\n\t\t\t\t/** Merge default headers with user-defined headers */\n\t\t\t\tallowHeaders: [\n\t\t\t\t\t'Content-Type',\n\t\t\t\t\t'Accept',\n\t\t\t\t\t'X-Amz-Date',\n\t\t\t\t\t'Authorization',\n\t\t\t\t\t'X-Api-Key',\n\t\t\t\t\t'X-Amz-Security-Token',\n\t\t\t\t\t'X-Amz-User-Agent',\n\t\t\t\t\t...(props.options?.gatewayOptions?.corsPreflight?.allowHeaders || []),\n\t\t\t\t],\n\t\t\t},\n\t\t});\n\n\t\t/**\n\t\t * Ensure at least one handler function is provided\n\t\t */\n\t\tif (!props?.handlerFunctions?.length) {\n\t\t\tthrow new CustomException('Construct requires atleast one function');\n\t\t}\n\n\t\t/**\n\t\t * Register routes with Lambda integrations\n\t\t */\n\t\tif (props?.options?.routeOptions?.length) {\n\t\t\tprops.handlerFunctions.forEach((handlerFunc) => {\n\t\t\t\tprops?.options?.routeOptions.forEach((route) => {\n\t\t\t\t\tthis.api.addRoutes({\n\t\t\t\t\t\t...route,\n\n\t\t\t\t\t\t/**\n\t\t\t\t\t\t * Lambda integration for each route\n\t\t\t\t\t\t */\n\t\t\t\t\t\tintegration: new HttpLambdaIntegration('routes', handlerFunc),\n\t\t\t\t\t} as AddRoutesOptions);\n\t\t\t\t});\n\t\t\t});\n\t\t}\n\n\t\t/**\n\t\t * Apply removal policy (useful for non-production environments)\n\t\t */\n\t\tthis.api.applyRemovalPolicy(RemovalPolicy.DESTROY);\n\n\t\t/**\n\t\t * CloudFormation output exposing the API base URL\n\t\t */\n\t\tnew CfnOutput(this, 'ApiGatewayV2', {\n\t\t\tvalue: this.api.url,\n\t\t});\n\t}\n}\n"]}

package/dist/aws-cdk/api-gateway-websocket.cjs

@@ -0,0 +1,77 @@
+'use strict';
+
+var constructs = require('constructs');
+var awsCdkLib = require('aws-cdk-lib');
+var awsApigatewayv2Integrations = require('aws-cdk-lib/aws-apigatewayv2-integrations');
+var awsApigatewayv2 = require('aws-cdk-lib/aws-apigatewayv2');
+
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+var BaseApiGatewayWebSocketConstruct = class extends constructs.Construct {
+  static {
+    __name(this, "BaseApiGatewayWebSocketConstruct");
+  }
+  /** The created WebSocket API instance */
+  socketApi;
+  /**
+   * @param scope Parent construct
+   * @param id Unique construct identifier
+   * @param props Configuration for API, stage, and route handlers
+   */
+  constructor(scope, id, props) {
+    super(scope, id);
+    this.socketApi = new awsApigatewayv2.WebSocketApi(this, id, {
+      ...props.options.webSocketApiOptions,
+      /**
+       * Route for connection establishment ($connect)
+       */
+      connectRouteOptions: {
+        ...props.handlers.connect?.option,
+        integration: new awsApigatewayv2Integrations.WebSocketLambdaIntegration(
+          "connectIntegration",
+          props.handlers.connect.function
+        )
+      },
+      /**
+       * Route for disconnection events ($disconnect)
+       */
+      disconnectRouteOptions: {
+        ...props.handlers.disconnect?.option,
+        integration: new awsApigatewayv2Integrations.WebSocketLambdaIntegration(
+          "disconnectIntegration",
+          props.handlers.disconnect.function
+        )
+      },
+      /**
+       * Default route for unmatched messages ($default)
+       */
+      defaultRouteOptions: {
+        ...props.handlers.default?.option,
+        integration: new awsApigatewayv2Integrations.WebSocketLambdaIntegration(
+          "defaultIntegration",
+          props.handlers.default.function
+        )
+      }
+    });
+    this.socketApi.addRoute("notifications", {
+      ...props.handlers.message?.option,
+      /** Lambda integration for message handling */
+      integration: new awsApigatewayv2Integrations.WebSocketLambdaIntegration(
+        "routes",
+        props.handlers.message.function
+      )
+    });
+    const webSocketStage = new awsApigatewayv2.WebSocketStage(this, `${id}_stage`, {
+      ...props.options?.webSocketStageOptions,
+      webSocketApi: this.socketApi,
+      autoDeploy: true
+    });
+    new awsCdkLib.CfnOutput(this, "WebSocketURL", {
+      value: webSocketStage.url
+    });
+  }
+};
+
+exports.BaseApiGatewayWebSocketConstruct = BaseApiGatewayWebSocketConstruct;
+//# sourceMappingURL=api-gateway-websocket.cjs.map
+//# sourceMappingURL=api-gateway-websocket.cjs.map

package/dist/aws-cdk/api-gateway-websocket.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/aws/cdk/constructs/api-gateway-websocket-construct.ts"],"names":["Construct","WebSocketApi","WebSocketLambdaIntegration","WebSocketStage","CfnOutput"],"mappings":";;;;;;;;;AA6EO,IAAM,gCAAA,GAAN,cAA+CA,oBAAA,CAAU;AAAA,EA7EhE;AA6EgE,IAAA,MAAA,CAAA,IAAA,EAAA,kCAAA,CAAA;AAAA;AAAA;AAAA,EAEtD,SAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOT,WAAA,CACC,KAAA,EACA,EAAA,EACA,KAAA,EACC;AACD,IAAA,KAAA,CAAM,OAAO,EAAE,CAAA;AAEf,IAAA,IAAA,CAAK,SAAA,GAAY,IAAIC,4BAAA,CAAa,IAAA,EAAM,EAAA,EAAI;AAAA,MAC3C,GAAG,MAAM,OAAA,CAAQ,mBAAA;AAAA;AAAA;AAAA;AAAA,MAKjB,mBAAA,EAAqB;AAAA,QACpB,GAAG,KAAA,CAAM,QAAA,CAAS,OAAA,EAAS,MAAA;AAAA,QAC3B,aAAa,IAAIC,sDAAA;AAAA,UAChB,oBAAA;AAAA,UACA,KAAA,CAAM,SAAS,OAAA,CAAQ;AAAA;AACxB,OACD;AAAA;AAAA;AAAA;AAAA,MAKA,sBAAA,EAAwB;AAAA,QACvB,GAAG,KAAA,CAAM,QAAA,CAAS,UAAA,EAAY,MAAA;AAAA,QAC9B,aAAa,IAAIA,sDAAA;AAAA,UAChB,uBAAA;AAAA,UACA,KAAA,CAAM,SAAS,UAAA,CAAW;AAAA;AAC3B,OACD;AAAA;AAAA;AAAA;AAAA,MAKA,mBAAA,EAAqB;AAAA,QACpB,GAAG,KAAA,CAAM,QAAA,CAAS,OAAA,EAAS,MAAA;AAAA,QAC3B,aAAa,IAAIA,sDAAA;AAAA,UAChB,oBAAA;AAAA,UACA,KAAA,CAAM,SAAS,OAAA,CAAQ;AAAA;AACxB;AACD,KACA,CAAA;AAKD,IAAA,IAAA,CAAK,SAAA,CAAU,SAAS,eAAA,EAAiB;AAAA,MACxC,GAAG,KAAA,CAAM,QAAA,CAAS,OAAA,EAAS,MAAA;AAAA;AAAA,MAG3B,aAAa,IAAIA,sDAAA;AAAA,QAChB,QAAA;AAAA,QACA,KAAA,CAAM,SAAS,OAAA,CAAQ;AAAA;AACxB,KACA,CAAA;AAMD,IAAA,MAAM,iBAAiB,IAAIC,8BAAA,CAAe,IAAA,EAAM,CAAA,EAAG,EAAE,CAAA,MAAA,CAAA,EAAU;AAAA,MAC9D,GAAG,MAAM,OAAA,EAAS,qBAAA;AAAA,MAClB,cAAc,IAAA,CAAK,SAAA;AAAA,MACnB,UAAA,EAAY;AAAA,KACZ,CAAA;AAKD,IAAA,IAAIC,mBAAA,CAAU,MAAM,cAAA,EAAgB;AAAA,MACnC,OAAO,cAAA,CAAe;AAAA,KACtB,CAAA;AAAA,EACF;AACD","file":"api-gateway-websocket.cjs","sourcesContent":["import { Construct } from 'constructs';\nimport { CfnOutput } from 'aws-cdk-lib';\nimport { Function } from 'aws-cdk-lib/aws-lambda';\nimport { WebSocketLambdaIntegration } from 'aws-cdk-lib/aws-apigatewayv2-integrations';\nimport {\n\tWebSocketApi,\n\tWebSocketApiProps,\n\tWebSocketRouteOptions,\n\tWebSocketStage,\n\tWebSocketStageProps,\n} from 'aws-cdk-lib/aws-apigatewayv2';\n\nimport { IBaseCdkConstructProps } from '../../types';\n\n/**\n * Props for BaseApiGatewayWebSocketConstruct\n *\n * Provides configuration for:\n * - WebSocket API (API Gateway v2)\n * - WebSocket stage\n * - Route handlers for lifecycle events\n */\ninterface IApiGatewayWebsocketConstructProps extends Omit<\n\tIBaseCdkConstructProps<{\n\t\t/** WebSocket API configuration options */\n\t\treadonly webSocketApiOptions: WebSocketApiProps;\n\n\t\t/** WebSocket stage configuration options */\n\t\treadonly webSocketStageOptions: WebSocketStageProps;\n\t}>,\n\t'appName' | 'stage' | 'stackName'\n> {\n\t/**\n\t * Lambda handlers mapped to WebSocket lifecycle routes\n\t *\n\t * Includes:\n\t * - $connect\n\t * - $disconnect\n\t * - $default\n\t * - custom message route\n\t */\n\treadonly handlers: {\n\t\t/** Handler for connection establishment ($connect) */\n\t\treadonly connect: {\n\t\t\toption: WebSocketRouteOptions;\n\t\t\tfunction: Function;\n\t\t};\n\n\t\t/** Handler for unmatched routes ($default) */\n\t\treadonly default: {\n\t\t\toption: WebSocketRouteOptions;\n\t\t\tfunction: Function;\n\t\t};\n\n\t\t/** Handler for custom message route (e.g. 'notifications') */\n\t\treadonly message: {\n\t\t\toption: WebSocketRouteOptions;\n\t\t\tfunction: Function;\n\t\t};\n\n\t\t/** Handler for disconnection events ($disconnect) */\n\t\treadonly disconnect: {\n\t\t\toption: WebSocketRouteOptions;\n\t\t\tfunction: Function;\n\t\t};\n\t};\n}\n\n/**\n * CDK construct for WebSocket API Gateway\n *\n * Responsibilities:\n * - Creates a WebSocket API with lifecycle route integrations\n * - Registers a custom message route\n * - Deploys a stage with auto-deploy enabled\n * - Exposes WebSocket endpoint URL as a CloudFormation output\n */\nexport class BaseApiGatewayWebSocketConstruct extends Construct {\n\t/** The created WebSocket API instance */\n\treadonly socketApi: WebSocketApi;\n\n\t/**\n\t * @param scope Parent construct\n\t * @param id Unique construct identifier\n\t * @param props Configuration for API, stage, and route handlers\n\t */\n\tconstructor(\n\t\tscope: Construct,\n\t\tid: string,\n\t\tprops: IApiGatewayWebsocketConstructProps,\n\t) {\n\t\tsuper(scope, id);\n\n\t\tthis.socketApi = new WebSocketApi(this, id, {\n\t\t\t...props.options.webSocketApiOptions,\n\n\t\t\t/**\n\t\t\t * Route for connection establishment ($connect)\n\t\t\t */\n\t\t\tconnectRouteOptions: {\n\t\t\t\t...props.handlers.connect?.option,\n\t\t\t\tintegration: new WebSocketLambdaIntegration(\n\t\t\t\t\t'connectIntegration',\n\t\t\t\t\tprops.handlers.connect.function,\n\t\t\t\t),\n\t\t\t},\n\n\t\t\t/**\n\t\t\t * Route for disconnection events ($disconnect)\n\t\t\t */\n\t\t\tdisconnectRouteOptions: {\n\t\t\t\t...props.handlers.disconnect?.option,\n\t\t\t\tintegration: new WebSocketLambdaIntegration(\n\t\t\t\t\t'disconnectIntegration',\n\t\t\t\t\tprops.handlers.disconnect.function,\n\t\t\t\t),\n\t\t\t},\n\n\t\t\t/**\n\t\t\t * Default route for unmatched messages ($default)\n\t\t\t */\n\t\t\tdefaultRouteOptions: {\n\t\t\t\t...props.handlers.default?.option,\n\t\t\t\tintegration: new WebSocketLambdaIntegration(\n\t\t\t\t\t'defaultIntegration',\n\t\t\t\t\tprops.handlers.default.function,\n\t\t\t\t),\n\t\t\t},\n\t\t});\n\n\t\t/**\n\t\t * Custom message route (e.g. \"notifications\")\n\t\t */\n\t\tthis.socketApi.addRoute('notifications', {\n\t\t\t...props.handlers.message?.option,\n\n\t\t\t/** Lambda integration for message handling */\n\t\t\tintegration: new WebSocketLambdaIntegration(\n\t\t\t\t'routes',\n\t\t\t\tprops.handlers.message.function,\n\t\t\t),\n\t\t});\n\n\t\t/**\n\t\t * WebSocket stage deployment\n\t\t * Auto-deploy ensures changes are immediately available\n\t\t */\n\t\tconst webSocketStage = new WebSocketStage(this, `${id}_stage`, {\n\t\t\t...props.options?.webSocketStageOptions,\n\t\t\twebSocketApi: this.socketApi,\n\t\t\tautoDeploy: true,\n\t\t});\n\n\t\t/**\n\t\t * CloudFormation output exposing WebSocket endpoint URL\n\t\t */\n\t\tnew CfnOutput(this, 'WebSocketURL', {\n\t\t\tvalue: webSocketStage.url,\n\t\t});\n\t}\n}\n"]}