@allma/cdk-integration-utils 1.0.1

package/README.md

@@ -0,0 +1,25 @@
+# Allma CDK Integration Utilities
+
+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.
+
+## Purpose
+
+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.
+
+## Usage
+
+To allow Allma to invoke a custom Lambda function, you need to use the `grantInvoke` utility from this package within your CDK stack.
+
+```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,
+});

package/dist/cdk-utils.d.ts

@@ -0,0 +1,42 @@
+import { Construct } from 'constructs';
+import { StepType } from '@allma/core-types';
+export interface ExternalStepRegistrationProps {
+    /**
+    The name of the central Allma configuration table.
+    */
+    configTableName: string;
+    /**
+    The unique identifier for the step (e.g., 'my-module/my-step').
+    */
+    moduleIdentifier: string;
+    /**
+    The user-friendly name for the step in the UI.
+    */
+    displayName: string;
+    /**
+    A short description of what the step does.
+    */
+    description: string;
+    /**
+    The step's functional type (e.g., DATA_LOAD).
+    */
+    stepType: StepType;
+    /**
+    The ARN of the Lambda function that executes the step's logic.
+    */
+    lambdaArn: string;
+    /**
+    A default configuration object for the step instance when dragged onto the canvas.
+    It will be automatically merged with the moduleIdentifier.
+    */
+    defaultConfig: Record<string, any>;
+}
+/**
+A reusable CDK utility to register an external step in the Allma DynamoDB registry.
+Creates an AwsCustomResource that handles putting the item on deploy/update and deleting it on destroy.
+@param scope The CDK Construct scope.
+@param id The unique ID for this construct.
+@param props The properties for the step registration.
+*/
+export declare function createExternalStepRegistration(scope: Construct, id: string, props: ExternalStepRegistrationProps): void;
+//# sourceMappingURL=cdk-utils.d.ts.map

package/dist/cdk-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cdk-utils.d.ts","sourceRoot":"","sources":["../src/cdk-utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAKvC,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAC7C,MAAM,WAAW,6BAA6B;IAC1C;;MAEE;IACF,eAAe,EAAE,MAAM,CAAC;IACxB;;MAEE;IACF,gBAAgB,EAAE,MAAM,CAAC;IACzB;;MAEE;IACF,WAAW,EAAE,MAAM,CAAC;IACpB;;MAEE;IACF,WAAW,EAAE,MAAM,CAAC;IACpB;;MAEE;IACF,QAAQ,EAAE,QAAQ,CAAC;IACnB;;MAEE;IACF,SAAS,EAAE,MAAM,CAAC;IAClB;;;MAGE;IACF,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CACtC;AACD;;;;;;EAME;AACF,wBAAgB,8BAA8B,CAAC,KAAK,EAAE,SAAS,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,6BAA6B,QAiDhH"}

package/dist/cdk-utils.js

@@ -0,0 +1,62 @@
+import * as cdk from 'aws-cdk-lib';
+import * as iam from 'aws-cdk-lib/aws-iam';
+import { AwsCustomResource, PhysicalResourceId } from 'aws-cdk-lib/custom-resources';
+import { RetentionDays } from 'aws-cdk-lib/aws-logs';
+/**
+A reusable CDK utility to register an external step in the Allma DynamoDB registry.
+Creates an AwsCustomResource that handles putting the item on deploy/update and deleting it on destroy.
+@param scope The CDK Construct scope.
+@param id The unique ID for this construct.
+@param props The properties for the step registration.
+*/
+export function createExternalStepRegistration(scope, id, props) {
+    const { configTableName, moduleIdentifier, displayName, description, stepType, lambdaArn, defaultConfig } = props;
+    const registrationId = `EXTERNAL_STEP#${moduleIdentifier}`;
+    const stack = cdk.Stack.of(scope);
+    const sdkCall = {
+        service: 'DynamoDB',
+        action: 'putItem',
+        parameters: {
+            TableName: configTableName,
+            Item: {
+                PK: { S: registrationId },
+                SK: { S: 'METADATA' },
+                itemType: { S: 'ALLMA_EXTERNAL_STEP_REGISTRY' },
+                moduleIdentifier: { S: moduleIdentifier },
+                lambdaArn: { S: lambdaArn },
+                displayName: { S: displayName },
+                description: { S: description },
+                stepType: { S: stepType },
+                defaultConfig: { S: JSON.stringify({ moduleIdentifier, ...defaultConfig }) },
+            },
+        },
+        physicalResourceId: PhysicalResourceId.of(registrationId),
+    };
+    const deleteCall = {
+        service: 'DynamoDB',
+        action: 'deleteItem',
+        parameters: {
+            TableName: configTableName,
+            Key: {
+                PK: { S: registrationId },
+                SK: { S: 'METADATA' },
+            },
+        },
+    };
+    new AwsCustomResource(scope, id, {
+        onCreate: sdkCall,
+        onUpdate: sdkCall,
+        onDelete: deleteCall,
+        logRetention: RetentionDays.ONE_WEEK,
+        installLatestAwsSdk: true, // Ensures SDK is up-to-date for DynamoDB calls
+        policy: {
+            statements: [
+                new iam.PolicyStatement({
+                    actions: ['dynamodb:PutItem', 'dynamodb:DeleteItem'],
+                    resources: [`arn:aws:dynamodb:${stack.region}:${stack.account}:table/${configTableName}`],
+                }),
+            ],
+        },
+    });
+}
+//# sourceMappingURL=cdk-utils.js.map

package/dist/cdk-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cdk-utils.js","sourceRoot":"","sources":["../src/cdk-utils.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,GAAG,MAAM,aAAa,CAAC;AACnC,OAAO,KAAK,GAAG,MAAM,qBAAqB,CAAC;AAC3C,OAAO,EAAE,iBAAiB,EAAc,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AACjG,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAiCrD;;;;;;EAME;AACF,MAAM,UAAU,8BAA8B,CAAC,KAAgB,EAAE,EAAU,EAAE,KAAoC;IAC7G,MAAM,EAAE,eAAe,EAAE,gBAAgB,EAAE,WAAW,EAAE,WAAW,EAAE,QAAQ,EAAE,SAAS,EAAE,aAAa,EAAE,GAAG,KAAK,CAAC;IAClH,MAAM,cAAc,GAAG,iBAAkB,gBAAiB,EAAE,CAAC;IAC7D,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC;IAClC,MAAM,OAAO,GAAe;QACxB,OAAO,EAAE,UAAU;QACnB,MAAM,EAAE,SAAS;QACjB,UAAU,EAAE;YACR,SAAS,EAAE,eAAe;YAC1B,IAAI,EAAE;gBACF,EAAE,EAAE,EAAE,CAAC,EAAE,cAAc,EAAE;gBACzB,EAAE,EAAE,EAAE,CAAC,EAAE,UAAU,EAAE;gBACrB,QAAQ,EAAE,EAAE,CAAC,EAAE,8BAA8B,EAAE;gBAC/C,gBAAgB,EAAE,EAAE,CAAC,EAAE,gBAAgB,EAAE;gBACzC,SAAS,EAAE,EAAE,CAAC,EAAE,SAAS,EAAE;gBAC3B,WAAW,EAAE,EAAE,CAAC,EAAE,WAAW,EAAE;gBAC/B,WAAW,EAAE,EAAE,CAAC,EAAE,WAAW,EAAE;gBAC/B,QAAQ,EAAE,EAAE,CAAC,EAAE,QAAQ,EAAE;gBACzB,aAAa,EAAE,EAAE,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,gBAAgB,EAAE,GAAG,aAAa,EAAE,CAAC,EAAE;aAC/E;SACJ;QACD,kBAAkB,EAAE,kBAAkB,CAAC,EAAE,CAAC,cAAc,CAAC;KAC5D,CAAC;IACF,MAAM,UAAU,GAAe;QAC3B,OAAO,EAAE,UAAU;QACnB,MAAM,EAAE,YAAY;QACpB,UAAU,EAAE;YACR,SAAS,EAAE,eAAe;YAC1B,GAAG,EAAE;gBACD,EAAE,EAAE,EAAE,CAAC,EAAE,cAAc,EAAE;gBACzB,EAAE,EAAE,EAAE,CAAC,EAAE,UAAU,EAAE;aACxB;SACJ;KACJ,CAAC;IACF,IAAI,iBAAiB,CAAC,KAAK,EAAE,EAAE,EAAE;QAC7B,QAAQ,EAAE,OAAO;QACjB,QAAQ,EAAE,OAAO;QACjB,QAAQ,EAAE,UAAU;QACpB,YAAY,EAAE,aAAa,CAAC,QAAQ;QACpC,mBAAmB,EAAE,IAAI,EAAE,+CAA+C;QAC1E,MAAM,EAAE;YACJ,UAAU,EAAE;gBACR,IAAI,GAAG,CAAC,eAAe,CAAC;oBACpB,OAAO,EAAE,CAAC,kBAAkB,EAAE,qBAAqB,CAAC;oBACpD,SAAS,EAAE,CAAC,oBAAoB,KAAK,CAAC,MAAM,IAAI,KAAK,CAAC,OAAO,UAAU,eAAe,EAAE,CAAC;iBAC5F,CAAC;aACL;SACJ;KACJ,CAAC,CAAC;AACP,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './cdk-utils.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export * from './cdk-utils.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC"}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@allma/cdk-integration-utils",
+  "version": "1.0.1",
+  "description": "Shared CDK constructs and utilities for integrating external modules with the Allma serverless AI orchestration platform.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "clean": "rimraf dist tsconfig.tsbuildinfo",
+    "build": "npm run clean && tsc",
+    "dev": "tsc --watch",
+    "lint": "eslint ."
+  },
+  "keywords": [
+    "allma",
+    "cdk",
+    "constructs",
+    "aws",
+    "serverless",
+    "integration",
+    "ai",
+    "orchestration"
+  ],
+  "author": "@webjema",
+  "license": "Apache-2.0",
+  "homepage": "https://docs.allma.dev",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ALLMA-dev/allma-core.git",
+    "directory": "packages/cdk-integration-utils"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@allma/core-types": "1.0.1",
+    "aws-cdk-lib": "^2.200.1",
+    "constructs": "^10.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.30",
+    "eslint": "^9.8.0",
+    "typescript-eslint": "^8.0.0",
+    "rimraf": "^6.0.1",
+    "typescript": "^5.9.3"
+  }
+}