@allma/cdk-integration-utils 1.0.1 → 1.0.2

package/README.md

@@ -1,25 +1,72 @@
-# Allma CDK Integration Utilities
+# @allma/cdk-integration-utils
 
-This package contains shared CDK constructs and utilities intended for consumers of the Allma platform. It provides the necessary building blocks to integrate your own AWS resources, such as custom Lambda functions, with your Allma flows.
+[![npm version](https://img.shields.io/npm/v/%40allma%2Fcdk-integration-utils)](https://www.npmjs.com/package/@allma/cdk-integration-utils)
+[![License](https://img.shields.io/npm/l/%40allma%2Fcdk-integration-utils)](https://github.com/ALLMA-dev/allma-core/blob/main/LICENSE)
 
-## Purpose
+This package provides helper utilities for developers who are building their own AWS CDK constructs to integrate with an existing Allma deployment. Its primary purpose is to simplify the process of registering custom modules with the Allma platform.
 
-The primary purpose of this package is to facilitate the `CUSTOM_LAMBDA_INVOKE` step type within Allma. It exports the necessary interfaces and utility functions to grant the Allma orchestrator the required IAM permissions to invoke your custom Lambdas.
+## What is Allma?
 
-## Usage
+**Allma is a serverless, event-driven platform designed to build, execute, and manage complex, AI-powered automated workflows, known as `Flows`.** It acts as a "digital factory" for orchestrating sophisticated business processes, combining data integration, conditional logic, and advanced AI capabilities in a robust, scalable, and observable environment built on AWS.
 
-To allow Allma to invoke a custom Lambda function, you need to use the `grantInvoke` utility from this package within your CDK stack.
+## Installation
+
+```bash
+npm install @allma/cdk-integration-utils
+```
+
+## Core Usage
+
+The most common use case is registering a custom Lambda function as an invokable step (`CUSTOM_LAMBDA_INVOKE`) within the Allma Flow Editor. The `createExternalStepRegistration` utility creates a CDK `AwsCustomResource` that automatically adds an entry to Allma's DynamoDB configuration table during `cdk deploy`.
+
+**Example: Registering a custom "Premium Calculator" Lambda.**
 
 ```typescript
-import { grantInvoke } from '@allma/cdk-integration-utils';
-import { MyCustomStack } from './my-custom-stack';
-
-// In your CDK app file
-const app = new cdk.App();
-const myStack = new MyCustomStack(app, 'MyCustomStack');
-
-// Grant the Allma orchestrator permission to invoke your function
-grantInvoke(myStack, 'MyCustomFunction', {
-  allmaStackName: 'MyAllmaStack',
-  function: myStack.myFunction,
-});
+import * as cdk from 'aws-cdk-lib';
+import { Construct } from 'constructs';
+import * as lambda from 'aws-cdk-lib/aws-lambda';
+import { StepType } from '@allma/core-types';
+import { createExternalStepRegistration } from '@allma/cdk-integration-utils';
+
+export interface MyCustomModuleStackProps extends cdk.StackProps {
+  // Pass in the name of the Allma config table from your Allma deployment
+  allmaConfigTableName: string;
+}
+
+export class MyCustomModuleStack extends cdk.Stack {
+  constructor(scope: Construct, id: string, props: MyCustomModuleStackProps) {
+    super(scope, id, props);
+
+    // 1. Define your custom Lambda function
+    const premiumCalculatorLambda = new lambda.Function(this, 'PremiumCalculator', {
+      runtime: lambda.Runtime.NODEJS_20_X,
+      handler: 'index.handler',
+      code: lambda.Code.fromAsset('./lambda'),
+      // ... other lambda props
+    });
+
+    // 2. Register it with Allma using the utility
+    createExternalStepRegistration(this, 'AllmaPremiumCalculatorRegistration', {
+      configTableName: props.allmaConfigTableName,
+      moduleIdentifier: 'my-company/premium-calculator',
+      displayName: 'Premium Calculator',
+      description: 'Calculates an insurance premium based on user data.',
+      stepType: StepType.CUSTOM_LAMBDA_INVOKE,
+      lambdaArn: premiumCalculatorLambda.functionArn,
+      defaultConfig: {
+        // This is the default JSON config that appears in the Flow Editor
+        // when a user drags this step onto the canvas.
+        someDefaultParameter: 'defaultValue',
+      },
+    });
+  }
+}
+```
+
+## Contributing
+
+This package is part of the `allma-core` monorepo. We welcome contributions! Please see our main [repository](https://github.com/ALLMA-dev/allma-core) and [contribution guide](https://docs.allma.dev/docs/community/contribution-guide) for more details.
+
+## License
+
+This project is licensed under the Apache-2.0 License.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@allma/cdk-integration-utils",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "Shared CDK constructs and utilities for integrating external modules with the Allma serverless AI orchestration platform.",
   "type": "module",
   "main": "dist/index.js",
@@ -36,7 +36,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@allma/core-types": "1.0.1",
+    "@allma/core-types": "1.0.2",
     "aws-cdk-lib": "^2.200.1",
     "constructs": "^10.0.0"
   },