@incloodsolutions/devkit 0.0.1 → 0.0.3

package/README.md

@@ -1,32 +1,58 @@
-# @incloodsolutions/node-toolkit
+# @incloodsolutions/devkit
 
-[![npm version](https://img.shields.io/npm/v/@incloodsolutions/node-toolkit.svg?style=for-the-badge)](https://www.npmjs.com/package/@incloodsolutions/node-toolkit)
-[![npm dm](https://img.shields.io/npm/dm/@incloodsolutions/node-toolkit.svg?style=for-the-badge)](https://www.npmjs.com/package/@incloodsolutions/node-toolkit)
-[![downloads](https://img.shields.io/npm/dt/@incloodsolutions/node-toolkit.svg?style=for-the-badge)](https://www.npmjs.com/package/@incloodsolutions/node-toolkit)
-[![licensee](https://img.shields.io/npm/l/@incloodsolutions/node-toolkit.svg?style=for-the-badge)](https://www.npmjs.com/package/@incloodsolutions/node-toolkit)
+[![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)
+[![license](https://img.shields.io/npm/l/@incloodsolutions/devkit.svg?style=for-the-badge)](https://www.npmjs.com/package/@incloodsolutions/devkit)
 
-A Node.js-focused extension of `@incloodsolutions/toolkit`, offering utilities for server-side applications.
-Includes async helpers, file system utilities, configuration management, and runtime tools optimised for building scalable Node.js backends and CLI tools.
+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.
 
 ---
 
 ## 📦 Installation
 
 ```bash
-npm install @incloodsolutions/node-toolkit
+npm install @incloodsolutions/devkit
 # or
-yarn add @incloodsolutions/node-toolkit
+yarn add @incloodsolutions/devkit
 ```
 
 ## 🚀 Usage
 
 ```typescript
-import { readJsonFile } from "@incloodsolutions/node-toolkit";
+import { EnvironmentHelper } from "@incloodsolutions/devkit";
 
-async function main() {
-  const config = await readJsonFile("./config.json");
-  console.log(config);
-}
-
-main();
+// Example usage
+const env = EnvironmentHelper.load();
 ```
+
+## ✨ 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

package/dist/aws/cdk/constructs/api-gateway-construct.cjs

@@ -0,0 +1,95 @@
+'use strict';
+
+var constructs = require('constructs');
+var awsCdkLib = require('aws-cdk-lib');
+var awsApigateway = require('aws-cdk-lib/aws-apigateway');
+var toolkit = require('@incloodsolutions/toolkit');
+
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+var BaseApiGatewayConstruct = class _BaseApiGatewayConstruct extends constructs.Construct {
+  static {
+    __name(this, "BaseApiGatewayConstruct");
+  }
+  /** The created REST API instance */
+  api;
+  /** Enables debug logging for route creation */
+  enableDebug = false;
+  /**
+   * @param scope Parent construct
+   * @param id Unique construct identifier
+   * @param props Configuration for API, routes, and Lambda handler
+   */
+  constructor(scope, id, props) {
+    super(scope, id);
+    this.enableDebug = props.enableDebug;
+    this.api = new awsApigateway.RestApi(this, id, {
+      ...props?.options?.gatewayOptions,
+      /** Default API description if not provided */
+      description: props?.options?.gatewayOptions?.description || "This is a REST API using CDK",
+      /**
+       * CORS configuration
+       * Falls back to allowing all origins, methods, and standard headers
+       */
+      defaultCorsPreflightOptions: {
+        ...props?.options?.gatewayOptions?.defaultCorsPreflightOptions,
+        /** Allow all origins by default */
+        allowOrigins: props?.options?.gatewayOptions?.defaultCorsPreflightOptions?.allowOrigins || awsApigateway.Cors.ALL_ORIGINS,
+        /** Allow all HTTP methods by default */
+        allowMethods: props?.options?.gatewayOptions?.defaultCorsPreflightOptions?.allowMethods || awsApigateway.Cors.ALL_METHODS,
+        /** Merge default headers with user-defined headers */
+        allowHeaders: [
+          ...props.options?.gatewayOptions?.defaultCorsPreflightOptions?.allowHeaders,
+          "Content-Type",
+          "Accept",
+          "X-Amz-Date",
+          "Authorization",
+          "X-Api-Key",
+          "X-Amz-Security-Token",
+          "X-Amz-User-Agent"
+        ]
+      },
+      /** Minimum payload size (in bytes) before compression is applied */
+      minCompressionSize: props?.options?.gatewayOptions?.minCompressionSize || awsCdkLib.Size.bytes(1)
+    });
+    if (props?.options?.routeOptions?.length && props?.handlerFunction) {
+      const integration = new awsApigateway.LambdaIntegration(props.handlerFunction);
+      this.addRoutes(this.api.root, props.options.routeOptions, integration);
+    }
+    this.api.applyRemovalPolicy(awsCdkLib.RemovalPolicy.DESTROY);
+    new awsCdkLib.CfnOutput(this, "ApiGateway", {
+      value: this.api.url
+    });
+  }
+  /**
+   * Recursively attaches routes to the API Gateway
+   *
+   * Behaviour:
+   * - Creates a resource for each route segment
+   * - Attaches method + Lambda integration
+   * - Traverses child routes for nested paths
+   *
+   * @param parent Parent API resource
+   * @param routes Route definitions
+   * @param integration Lambda integration applied to each route
+   * @param previousPath Accumulated path (used for debug logging)
+   * @private
+   */
+  addRoutes(parent, routes, integration, previousPath) {
+    routes.forEach((route) => {
+      const currentPath = `${previousPath || ""}/${route.name}`;
+      const resource = parent.addResource(route.name);
+      resource.addMethod(route.method, integration);
+      if (route?.children.length) {
+        this.addRoutes(resource, route.children, integration, currentPath);
+      }
+      if (this.enableDebug) {
+        toolkit.printLog(_BaseApiGatewayConstruct.name, `Route created: ${route.method} ${currentPath}`);
+      }
+    });
+  }
+};
+
+exports.BaseApiGatewayConstruct = BaseApiGatewayConstruct;
+//# sourceMappingURL=api-gateway-construct.cjs.map
+//# sourceMappingURL=api-gateway-construct.cjs.map

package/dist/aws/cdk/constructs/api-gateway-construct.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../src/aws/cdk/constructs/api-gateway-construct.ts"],"names":["Construct","RestApi","Cors","Size","LambdaIntegration","RemovalPolicy","CfnOutput","printLog"],"mappings":"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","file":"api-gateway-construct.cjs","sourcesContent":["import { Construct } from 'constructs';\nimport { Function } from 'aws-cdk-lib/aws-lambda';\nimport { HttpMethod } from 'aws-cdk-lib/aws-apigatewayv2';\nimport { CfnOutput, RemovalPolicy, Size } from 'aws-cdk-lib';\nimport { Cors, IResource, LambdaIntegration, RestApi, RestApiProps } from 'aws-cdk-lib/aws-apigateway';\n\nimport { printLog } from '@incloodsolutions/toolkit';\n\nimport { IBaseCdkConstructProps, IBaseConstruct } from '../../types';\n\n\n/**\n * Route definition for API Gateway resources\n *\n * Supports hierarchical route structures using `children`\n */\ninterface IRouteOption {\n\t/** Path segment (e.g. 'users', 'orders') */\n\tname: string;\n\n\t/** HTTP method for the route */\n\tmethod: `${HttpMethod}`;\n\n\t/** Nested routes under this path */\n\tchildren?: IRouteOption[];\n}\n\n/**\n * Props for BaseApiGatewayConstruct\n *\n * Provides configuration for:\n * - REST API (API Gateway v1)\n * - Route definitions\n * - Lambda handler\n */\ninterface IApiGatewayConstructProps extends Omit<IBaseCdkConstructProps<{\n\t/** REST API configuration options */\n\treadonly gatewayOptions: RestApiProps;\n\n\t/** Route definitions used to build API resources */\n\treadonly routeOptions: IRouteOption[];\n}>, 'appName' | 'stage' | 'stackName'> {\n\t/**\n\t * Lambda function handling all API routes\n\t *\n\t * Note:\n\t * A single Lambda integration is reused across all routes\n\t */\n\treadonly handlerFunction: Function;\n}\n\n/**\n * CDK construct for REST API Gateway with Lambda integration\n *\n * Responsibilities:\n * - Creates a REST API with configurable options\n * - Applies default CORS and compression settings when not provided\n * - Recursively builds API resources from route definitions\n * - Exposes API base URL as a CloudFormation output\n */\nexport class BaseApiGatewayConstruct extends Construct implements IBaseConstruct {\n\t/** The created REST API instance */\n\treadonly api: RestApi;\n\n\t/** Enables debug logging for route creation */\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 Lambda handler\n\t */\n\tconstructor(scope: Construct, id: string, props: IApiGatewayConstructProps) {\n\t\tsuper(scope, id);\n\n\t\tthis.enableDebug = props.enableDebug;\n\n\t\tthis.api = new RestApi(this, id, {\n\t\t\t...props?.options?.gatewayOptions,\n\n\t\t\t/** Default API description if not provided */\n\t\t\tdescription: props?.options?.gatewayOptions?.description || 'This is a REST API using CDK',\n\n\t\t\t/**\n\t\t\t * CORS configuration\n\t\t\t * Falls back to allowing all origins, methods, and standard headers\n\t\t\t */\n\t\t\tdefaultCorsPreflightOptions: {\n\t\t\t\t...props?.options?.gatewayOptions?.defaultCorsPreflightOptions,\n\n\t\t\t\t/** Allow all origins by default */\n\t\t\t\tallowOrigins: props?.options?.gatewayOptions?.defaultCorsPreflightOptions?.allowOrigins || Cors.ALL_ORIGINS,\n\n\t\t\t\t/** Allow all HTTP methods by default */\n\t\t\t\tallowMethods: props?.options?.gatewayOptions?.defaultCorsPreflightOptions?.allowMethods || Cors.ALL_METHODS,\n\n\t\t\t\t/** Merge default headers with user-defined headers */\n\t\t\t\tallowHeaders: [\n\t\t\t\t\t...props.options?.gatewayOptions?.defaultCorsPreflightOptions?.allowHeaders,\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]\n\t\t\t},\n\n\t\t\t/** Minimum payload size (in bytes) before compression is applied */\n\t\t\tminCompressionSize: props?.options?.gatewayOptions?.minCompressionSize || Size.bytes(1),\n\t\t});\n\n\t\t/**\n\t\t * Register routes if provided\n\t\t */\n\t\tif (props?.options?.routeOptions?.length && props?.handlerFunction) {\n\t\t\tconst integration = new LambdaIntegration(props.handlerFunction);\n\n\t\t\t/**\n\t\t\t * Attach routes recursively starting from API root\n\t\t\t */\n\t\t\tthis.addRoutes(this.api.root, props.options.routeOptions, integration);\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 API base URL\n\t\t */\n\t\tnew CfnOutput(this, 'ApiGateway', {\n\t\t\tvalue: this.api.url\n\t\t});\n\t}\n\n\t/**\n\t * Recursively attaches routes to the API Gateway\n\t *\n\t * Behaviour:\n\t * - Creates a resource for each route segment\n\t * - Attaches method + Lambda integration\n\t * - Traverses child routes for nested paths\n\t *\n\t * @param parent Parent API resource\n\t * @param routes Route definitions\n\t * @param integration Lambda integration applied to each route\n\t * @param previousPath Accumulated path (used for debug logging)\n\t * @private\n\t */\n\tprivate addRoutes(\n\t\tparent: IResource,\n\t\troutes: IRouteOption[],\n\t\tintegration: LambdaIntegration,\n\t\tpreviousPath?: string\n\t) {\n\t\troutes.forEach(route => {\n\t\t\tconst currentPath = `${previousPath || ''}/${route.name}`;\n\n\t\t\tconst resource = parent.addResource(route.name);\n\n\t\t\t/** Attach HTTP method with Lambda integration */\n\t\t\tresource.addMethod(route.method, integration);\n\n\t\t\t/** Recursively process child routes */\n\t\t\tif (route?.children.length) {\n\t\t\t\tthis.addRoutes(resource, route.children, integration, currentPath);\n\t\t\t}\n\n\t\t\t/** Optional debug logging */\n\t\t\tif (this.enableDebug) {\n\t\t\t\tprintLog(BaseApiGatewayConstruct.name, `Route created: ${route.method} ${currentPath}`);\n\t\t\t}\n\t\t});\n\t}\n}"]}

package/dist/aws/cdk/constructs/api-gateway-construct.d.cts

@@ -0,0 +1,80 @@
+import { Construct } from 'constructs';
+import { Function } from 'aws-cdk-lib/aws-lambda';
+import { HttpMethod } from 'aws-cdk-lib/aws-apigatewayv2';
+import { RestApi, RestApiProps } from 'aws-cdk-lib/aws-apigateway';
+import { IBaseConstruct, IBaseCdkConstructProps } from '../../types/index.cjs';
+import '@incloodsolutions/toolkit';
+
+/**
+ * Route definition for API Gateway resources
+ *
+ * Supports hierarchical route structures using `children`
+ */
+interface IRouteOption {
+    /** Path segment (e.g. 'users', 'orders') */
+    name: string;
+    /** HTTP method for the route */
+    method: `${HttpMethod}`;
+    /** Nested routes under this path */
+    children?: IRouteOption[];
+}
+/**
+ * Props for BaseApiGatewayConstruct
+ *
+ * Provides configuration for:
+ * - REST API (API Gateway v1)
+ * - Route definitions
+ * - Lambda handler
+ */
+interface IApiGatewayConstructProps extends Omit<IBaseCdkConstructProps<{
+    /** REST API configuration options */
+    readonly gatewayOptions: RestApiProps;
+    /** Route definitions used to build API resources */
+    readonly routeOptions: IRouteOption[];
+}>, 'appName' | 'stage' | 'stackName'> {
+    /**
+     * Lambda function handling all API routes
+     *
+     * Note:
+     * A single Lambda integration is reused across all routes
+     */
+    readonly handlerFunction: Function;
+}
+/**
+ * CDK construct for REST API Gateway with Lambda integration
+ *
+ * Responsibilities:
+ * - Creates a REST API with configurable options
+ * - Applies default CORS and compression settings when not provided
+ * - Recursively builds API resources from route definitions
+ * - Exposes API base URL as a CloudFormation output
+ */
+declare class BaseApiGatewayConstruct extends Construct implements IBaseConstruct {
+    /** The created REST API instance */
+    readonly api: RestApi;
+    /** Enables debug logging for route creation */
+    enableDebug: boolean;
+    /**
+     * @param scope Parent construct
+     * @param id Unique construct identifier
+     * @param props Configuration for API, routes, and Lambda handler
+     */
+    constructor(scope: Construct, id: string, props: IApiGatewayConstructProps);
+    /**
+     * Recursively attaches routes to the API Gateway
+     *
+     * Behaviour:
+     * - Creates a resource for each route segment
+     * - Attaches method + Lambda integration
+     * - Traverses child routes for nested paths
+     *
+     * @param parent Parent API resource
+     * @param routes Route definitions
+     * @param integration Lambda integration applied to each route
+     * @param previousPath Accumulated path (used for debug logging)
+     * @private
+     */
+    private addRoutes;
+}
+
+export { BaseApiGatewayConstruct };

package/dist/aws/cdk/constructs/api-gateway-construct.d.ts

@@ -0,0 +1,80 @@
+import { Construct } from 'constructs';
+import { Function } from 'aws-cdk-lib/aws-lambda';
+import { HttpMethod } from 'aws-cdk-lib/aws-apigatewayv2';
+import { RestApi, RestApiProps } from 'aws-cdk-lib/aws-apigateway';
+import { IBaseConstruct, IBaseCdkConstructProps } from '../../types/index.js';
+import '@incloodsolutions/toolkit';
+
+/**
+ * Route definition for API Gateway resources
+ *
+ * Supports hierarchical route structures using `children`
+ */
+interface IRouteOption {
+    /** Path segment (e.g. 'users', 'orders') */
+    name: string;
+    /** HTTP method for the route */
+    method: `${HttpMethod}`;
+    /** Nested routes under this path */
+    children?: IRouteOption[];
+}
+/**
+ * Props for BaseApiGatewayConstruct
+ *
+ * Provides configuration for:
+ * - REST API (API Gateway v1)
+ * - Route definitions
+ * - Lambda handler
+ */
+interface IApiGatewayConstructProps extends Omit<IBaseCdkConstructProps<{
+    /** REST API configuration options */
+    readonly gatewayOptions: RestApiProps;
+    /** Route definitions used to build API resources */
+    readonly routeOptions: IRouteOption[];
+}>, 'appName' | 'stage' | 'stackName'> {
+    /**
+     * Lambda function handling all API routes
+     *
+     * Note:
+     * A single Lambda integration is reused across all routes
+     */
+    readonly handlerFunction: Function;
+}
+/**
+ * CDK construct for REST API Gateway with Lambda integration
+ *
+ * Responsibilities:
+ * - Creates a REST API with configurable options
+ * - Applies default CORS and compression settings when not provided
+ * - Recursively builds API resources from route definitions
+ * - Exposes API base URL as a CloudFormation output
+ */
+declare class BaseApiGatewayConstruct extends Construct implements IBaseConstruct {
+    /** The created REST API instance */
+    readonly api: RestApi;
+    /** Enables debug logging for route creation */
+    enableDebug: boolean;
+    /**
+     * @param scope Parent construct
+     * @param id Unique construct identifier
+     * @param props Configuration for API, routes, and Lambda handler
+     */
+    constructor(scope: Construct, id: string, props: IApiGatewayConstructProps);
+    /**
+     * Recursively attaches routes to the API Gateway
+     *
+     * Behaviour:
+     * - Creates a resource for each route segment
+     * - Attaches method + Lambda integration
+     * - Traverses child routes for nested paths
+     *
+     * @param parent Parent API resource
+     * @param routes Route definitions
+     * @param integration Lambda integration applied to each route
+     * @param previousPath Accumulated path (used for debug logging)
+     * @private
+     */
+    private addRoutes;
+}
+
+export { BaseApiGatewayConstruct };

package/dist/aws/cdk/constructs/api-gateway-construct.js

@@ -0,0 +1,93 @@
+import { Construct } from 'constructs';
+import { Size, RemovalPolicy, CfnOutput } from 'aws-cdk-lib';
+import { RestApi, Cors, LambdaIntegration } from 'aws-cdk-lib/aws-apigateway';
+import { printLog } from '@incloodsolutions/toolkit';
+
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+var BaseApiGatewayConstruct = class _BaseApiGatewayConstruct extends Construct {
+  static {
+    __name(this, "BaseApiGatewayConstruct");
+  }
+  /** The created REST API instance */
+  api;
+  /** Enables debug logging for route creation */
+  enableDebug = false;
+  /**
+   * @param scope Parent construct
+   * @param id Unique construct identifier
+   * @param props Configuration for API, routes, and Lambda handler
+   */
+  constructor(scope, id, props) {
+    super(scope, id);
+    this.enableDebug = props.enableDebug;
+    this.api = new RestApi(this, id, {
+      ...props?.options?.gatewayOptions,
+      /** Default API description if not provided */
+      description: props?.options?.gatewayOptions?.description || "This is a REST API using CDK",
+      /**
+       * CORS configuration
+       * Falls back to allowing all origins, methods, and standard headers
+       */
+      defaultCorsPreflightOptions: {
+        ...props?.options?.gatewayOptions?.defaultCorsPreflightOptions,
+        /** Allow all origins by default */
+        allowOrigins: props?.options?.gatewayOptions?.defaultCorsPreflightOptions?.allowOrigins || Cors.ALL_ORIGINS,
+        /** Allow all HTTP methods by default */
+        allowMethods: props?.options?.gatewayOptions?.defaultCorsPreflightOptions?.allowMethods || Cors.ALL_METHODS,
+        /** Merge default headers with user-defined headers */
+        allowHeaders: [
+          ...props.options?.gatewayOptions?.defaultCorsPreflightOptions?.allowHeaders,
+          "Content-Type",
+          "Accept",
+          "X-Amz-Date",
+          "Authorization",
+          "X-Api-Key",
+          "X-Amz-Security-Token",
+          "X-Amz-User-Agent"
+        ]
+      },
+      /** Minimum payload size (in bytes) before compression is applied */
+      minCompressionSize: props?.options?.gatewayOptions?.minCompressionSize || Size.bytes(1)
+    });
+    if (props?.options?.routeOptions?.length && props?.handlerFunction) {
+      const integration = new LambdaIntegration(props.handlerFunction);
+      this.addRoutes(this.api.root, props.options.routeOptions, integration);
+    }
+    this.api.applyRemovalPolicy(RemovalPolicy.DESTROY);
+    new CfnOutput(this, "ApiGateway", {
+      value: this.api.url
+    });
+  }
+  /**
+   * Recursively attaches routes to the API Gateway
+   *
+   * Behaviour:
+   * - Creates a resource for each route segment
+   * - Attaches method + Lambda integration
+   * - Traverses child routes for nested paths
+   *
+   * @param parent Parent API resource
+   * @param routes Route definitions
+   * @param integration Lambda integration applied to each route
+   * @param previousPath Accumulated path (used for debug logging)
+   * @private
+   */
+  addRoutes(parent, routes, integration, previousPath) {
+    routes.forEach((route) => {
+      const currentPath = `${previousPath || ""}/${route.name}`;
+      const resource = parent.addResource(route.name);
+      resource.addMethod(route.method, integration);
+      if (route?.children.length) {
+        this.addRoutes(resource, route.children, integration, currentPath);
+      }
+      if (this.enableDebug) {
+        printLog(_BaseApiGatewayConstruct.name, `Route created: ${route.method} ${currentPath}`);
+      }
+    });
+  }
+};
+
+export { BaseApiGatewayConstruct };
+//# sourceMappingURL=api-gateway-construct.js.map
+//# sourceMappingURL=api-gateway-construct.js.map

package/dist/aws/cdk/constructs/api-gateway-construct.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../src/aws/cdk/constructs/api-gateway-construct.ts"],"names":[],"mappings":"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","file":"api-gateway-construct.js","sourcesContent":["import { Construct } from 'constructs';\nimport { Function } from 'aws-cdk-lib/aws-lambda';\nimport { HttpMethod } from 'aws-cdk-lib/aws-apigatewayv2';\nimport { CfnOutput, RemovalPolicy, Size } from 'aws-cdk-lib';\nimport { Cors, IResource, LambdaIntegration, RestApi, RestApiProps } from 'aws-cdk-lib/aws-apigateway';\n\nimport { printLog } from '@incloodsolutions/toolkit';\n\nimport { IBaseCdkConstructProps, IBaseConstruct } from '../../types';\n\n\n/**\n * Route definition for API Gateway resources\n *\n * Supports hierarchical route structures using `children`\n */\ninterface IRouteOption {\n\t/** Path segment (e.g. 'users', 'orders') */\n\tname: string;\n\n\t/** HTTP method for the route */\n\tmethod: `${HttpMethod}`;\n\n\t/** Nested routes under this path */\n\tchildren?: IRouteOption[];\n}\n\n/**\n * Props for BaseApiGatewayConstruct\n *\n * Provides configuration for:\n * - REST API (API Gateway v1)\n * - Route definitions\n * - Lambda handler\n */\ninterface IApiGatewayConstructProps extends Omit<IBaseCdkConstructProps<{\n\t/** REST API configuration options */\n\treadonly gatewayOptions: RestApiProps;\n\n\t/** Route definitions used to build API resources */\n\treadonly routeOptions: IRouteOption[];\n}>, 'appName' | 'stage' | 'stackName'> {\n\t/**\n\t * Lambda function handling all API routes\n\t *\n\t * Note:\n\t * A single Lambda integration is reused across all routes\n\t */\n\treadonly handlerFunction: Function;\n}\n\n/**\n * CDK construct for REST API Gateway with Lambda integration\n *\n * Responsibilities:\n * - Creates a REST API with configurable options\n * - Applies default CORS and compression settings when not provided\n * - Recursively builds API resources from route definitions\n * - Exposes API base URL as a CloudFormation output\n */\nexport class BaseApiGatewayConstruct extends Construct implements IBaseConstruct {\n\t/** The created REST API instance */\n\treadonly api: RestApi;\n\n\t/** Enables debug logging for route creation */\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 Lambda handler\n\t */\n\tconstructor(scope: Construct, id: string, props: IApiGatewayConstructProps) {\n\t\tsuper(scope, id);\n\n\t\tthis.enableDebug = props.enableDebug;\n\n\t\tthis.api = new RestApi(this, id, {\n\t\t\t...props?.options?.gatewayOptions,\n\n\t\t\t/** Default API description if not provided */\n\t\t\tdescription: props?.options?.gatewayOptions?.description || 'This is a REST API using CDK',\n\n\t\t\t/**\n\t\t\t * CORS configuration\n\t\t\t * Falls back to allowing all origins, methods, and standard headers\n\t\t\t */\n\t\t\tdefaultCorsPreflightOptions: {\n\t\t\t\t...props?.options?.gatewayOptions?.defaultCorsPreflightOptions,\n\n\t\t\t\t/** Allow all origins by default */\n\t\t\t\tallowOrigins: props?.options?.gatewayOptions?.defaultCorsPreflightOptions?.allowOrigins || Cors.ALL_ORIGINS,\n\n\t\t\t\t/** Allow all HTTP methods by default */\n\t\t\t\tallowMethods: props?.options?.gatewayOptions?.defaultCorsPreflightOptions?.allowMethods || Cors.ALL_METHODS,\n\n\t\t\t\t/** Merge default headers with user-defined headers */\n\t\t\t\tallowHeaders: [\n\t\t\t\t\t...props.options?.gatewayOptions?.defaultCorsPreflightOptions?.allowHeaders,\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]\n\t\t\t},\n\n\t\t\t/** Minimum payload size (in bytes) before compression is applied */\n\t\t\tminCompressionSize: props?.options?.gatewayOptions?.minCompressionSize || Size.bytes(1),\n\t\t});\n\n\t\t/**\n\t\t * Register routes if provided\n\t\t */\n\t\tif (props?.options?.routeOptions?.length && props?.handlerFunction) {\n\t\t\tconst integration = new LambdaIntegration(props.handlerFunction);\n\n\t\t\t/**\n\t\t\t * Attach routes recursively starting from API root\n\t\t\t */\n\t\t\tthis.addRoutes(this.api.root, props.options.routeOptions, integration);\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 API base URL\n\t\t */\n\t\tnew CfnOutput(this, 'ApiGateway', {\n\t\t\tvalue: this.api.url\n\t\t});\n\t}\n\n\t/**\n\t * Recursively attaches routes to the API Gateway\n\t *\n\t * Behaviour:\n\t * - Creates a resource for each route segment\n\t * - Attaches method + Lambda integration\n\t * - Traverses child routes for nested paths\n\t *\n\t * @param parent Parent API resource\n\t * @param routes Route definitions\n\t * @param integration Lambda integration applied to each route\n\t * @param previousPath Accumulated path (used for debug logging)\n\t * @private\n\t */\n\tprivate addRoutes(\n\t\tparent: IResource,\n\t\troutes: IRouteOption[],\n\t\tintegration: LambdaIntegration,\n\t\tpreviousPath?: string\n\t) {\n\t\troutes.forEach(route => {\n\t\t\tconst currentPath = `${previousPath || ''}/${route.name}`;\n\n\t\t\tconst resource = parent.addResource(route.name);\n\n\t\t\t/** Attach HTTP method with Lambda integration */\n\t\t\tresource.addMethod(route.method, integration);\n\n\t\t\t/** Recursively process child routes */\n\t\t\tif (route?.children.length) {\n\t\t\t\tthis.addRoutes(resource, route.children, integration, currentPath);\n\t\t\t}\n\n\t\t\t/** Optional debug logging */\n\t\t\tif (this.enableDebug) {\n\t\t\t\tprintLog(BaseApiGatewayConstruct.name, `Route created: ${route.method} ${currentPath}`);\n\t\t\t}\n\t\t});\n\t}\n}"]}

package/dist/aws/cdk/constructs/api-gateway-v2-construct.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-construct.cjs.map
+//# sourceMappingURL=api-gateway-v2-construct.cjs.map

package/dist/aws/cdk/constructs/api-gateway-v2-construct.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":";;;;;;;;;;AA+CO,IAAM,yBAAA,GAAN,cAAwCA,oBAAA,CAAoC;AAAA,EA/CnF;AA+CmF,IAAA,MAAA,CAAA,IAAA,EAAA,2BAAA,CAAA;AAAA;AAAA;AAAA,EAEzE,GAAA;AAAA;AAAA,EAGT,WAAA,GAAc,KAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOd,WAAA,CAAY,KAAA,EAAkB,EAAA,EAAY,KAAA,EAAoC;AAC7E,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,EAAa,KAAA,EAAO,OAAA,EAAS,cAAA,EAAgB,WAAA,IAAe,+BAAA;AAAA;AAAA;AAAA;AAAA;AAAA,MAM5D,aAAA,EAAe;AAAA,QACd,GAAG,KAAA,CAAM,OAAA,EAAS,cAAA,EAAgB,aAAA;AAAA;AAAA,QAGlC,YAAA,EAAc,MAAM,OAAA,EAAS,cAAA,EAAgB,eAAe,YAAA,IAAgB,MAAA,CAAO,OAAOC,8BAAc,CAAA;AAAA;AAAA,QAGxG,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,GAAG,KAAA,CAAM,OAAA,EAAS,cAAA,EAAgB,aAAA,EAAe,gBAAgB;AAAC;AACnE;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,QAAQ,CAAA,WAAA,KAAe;AAC7C,QAAA,KAAA,EAAO,OAAA,EAAS,YAAA,CAAa,OAAA,CAAQ,CAAA,KAAA,KAAS;AAC7C,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-construct.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 { AddRoutesOptions, CorsHttpMethod, HttpApi, HttpApiProps } 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<IBaseCdkConstructProps<{\n\t/** HTTP API configuration options */\n\treadonly gatewayOptions: HttpApiProps;\n\n\t/** Route definitions passed directly to `addRoutes` */\n\treadonly routeOptions: Partial<AddRoutesOptions>[];\n}>, 'appName' | 'stage' | 'stackName'> {\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/**\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 extends Construct implements IBaseConstruct {\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(scope: Construct, id: string, props: IApiGatewayV2ConstructProps) {\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: props?.options?.gatewayOptions?.description || '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: props.options?.gatewayOptions?.corsPreflight?.allowMethods || Object.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}"]}

package/dist/aws/cdk/constructs/api-gateway-v2-construct.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 '../../types/index.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 };