@teaminabottle/domain-cdk-packer 0.1.0

package/dist/__tests__/pack-flows.test.js

@@ -0,0 +1,121 @@
+import { describe, it, expect } from 'vitest';
+import { FlowsStack, packFlows } from '../pack-flows.js';
+import * as cdk from 'aws-cdk-lib';
+describe('packFlows', () => {
+    it('creates a FlowsStack from a registry', () => {
+        const app = new cdk.App();
+        const registry = {
+            schemaVersion: '1',
+            flows: [
+                {
+                    id: 'test-flow',
+                    name: 'Test Flow',
+                    steps: [
+                        {
+                            type: 'flow-control',
+                            control: 'succeed',
+                            name: 'End',
+                        },
+                    ],
+                },
+            ],
+        };
+        const stack = packFlows(registry, app, 'test-flows', {
+            domainLambdaArns: {},
+            eventBusArn: 'arn:aws:events:us-east-1:123456789012:event-bus/test',
+        });
+        expect(stack).toBeInstanceOf(FlowsStack);
+        expect(stack.flowArnMap).toBeDefined();
+    });
+    it('throws when domain-action step references missing Lambda ARN', () => {
+        const app = new cdk.App();
+        const registry = {
+            schemaVersion: '1',
+            flows: [
+                {
+                    id: 'action-flow',
+                    name: 'Action Flow',
+                    steps: [
+                        {
+                            type: 'domain-action',
+                            name: 'RunAction',
+                            domainId: 'example',
+                            actionId: 'process',
+                        },
+                    ],
+                },
+            ],
+        };
+        expect(() => {
+            packFlows(registry, app, 'test-flows', {
+                domainLambdaArns: {},
+                eventBusArn: 'arn:aws:events:us-east-1:123456789012:event-bus/test',
+            });
+        }).toThrow(/no Lambda ARN for example-action/);
+    });
+    it('translates domain-action step with Lambda ARN', () => {
+        const app = new cdk.App();
+        const registry = {
+            schemaVersion: '1',
+            flows: [
+                {
+                    id: 'action-flow',
+                    name: 'Action Flow',
+                    steps: [
+                        {
+                            type: 'domain-action',
+                            name: 'RunAction',
+                            domainId: 'example',
+                            actionId: 'process',
+                        },
+                    ],
+                },
+            ],
+        };
+        const stack = packFlows(registry, app, 'test-flows', {
+            domainLambdaArns: {
+                'example-action': 'arn:aws:lambda:us-east-1:123456789012:function:test',
+            },
+            eventBusArn: 'arn:aws:events:us-east-1:123456789012:event-bus/test',
+        });
+        expect(stack.flowArnMap['action-flow']).toBeDefined();
+    });
+    it('translates domain-event step to putEvents', () => {
+        const app = new cdk.App();
+        const registry = {
+            schemaVersion: '1',
+            flows: [
+                {
+                    id: 'event-flow',
+                    name: 'Event Flow',
+                    steps: [
+                        {
+                            type: 'domain-event',
+                            name: 'EmitEvent',
+                            eventId: 'example.completed',
+                            payload: { status: 'ok' },
+                            version: 1,
+                        },
+                    ],
+                },
+            ],
+        };
+        const stack = packFlows(registry, app, 'test-flows', {
+            domainLambdaArns: {},
+            eventBusArn: 'arn:aws:events:us-east-1:123456789012:event-bus/test',
+        });
+        expect(stack.flowArnMap['event-flow']).toBeDefined();
+    });
+    it('handles empty flow registry gracefully', () => {
+        const app = new cdk.App();
+        const registry = {
+            schemaVersion: '1',
+            flows: [],
+        };
+        const stack = packFlows(registry, app, 'test-flows', {
+            domainLambdaArns: {},
+            eventBusArn: 'arn:aws:events:us-east-1:123456789012:event-bus/test',
+        });
+        expect(Object.keys(stack.flowArnMap)).toHaveLength(0);
+    });
+});

package/dist/__tests__/registry.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/registry.test.js

@@ -0,0 +1,34 @@
+import { describe, it, expect } from 'vitest';
+describe('DomainRegistry type', () => {
+    it('accepts a valid minimal registry object', () => {
+        const r = {
+            schemaVersion: '1',
+            domainRoot: '/workspace/my-domain',
+            domain: { id: 'my-domain', kind: 'domain', name: 'My Domain', tenancy: 'required' },
+            apis: [],
+            webhooks: [],
+            subscribers: [],
+            schedules: [],
+            jobs: [],
+            actions: [],
+            integrations: [],
+            events: [],
+        };
+        expect(r.schemaVersion).toBe('1');
+        expect(r.domain.kind).toBe('domain');
+    });
+    it('discriminates RegistryEntry union by kind', () => {
+        const entries = [
+            { id: 'test-api', kind: 'api', handlerFile: 'src/api.ts', path: '/test', method: 'GET', authType: 'jwt' },
+            { id: 'test-job', kind: 'job', handlerFile: 'src/job.ts', maxRetries: 3, visibilityTimeoutSeconds: 30 },
+        ];
+        for (const entry of entries) {
+            if (entry.kind === 'api') {
+                expect(entry.path).toBeDefined();
+            }
+            if (entry.kind === 'job') {
+                expect(entry.maxRetries).toBeDefined();
+            }
+        }
+    });
+});

package/dist/__tests__/step-functions-codegen.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/step-functions-codegen.test.js

@@ -0,0 +1,159 @@
+import { describe, it, expect } from 'vitest';
+import { StepFunctionsCodegen } from '../step-functions-codegen.js';
+describe('StepFunctionsCodegen', () => {
+    const codegen = new StepFunctionsCodegen();
+    describe('generateTaskState', () => {
+        it('should set Next when node has next property', () => {
+            const node = {
+                type: 'domain-action',
+                domainId: 'payments',
+                actionId: 'charge-card',
+                next: 'Step2',
+            };
+            const state = codegen.generateTaskState(node);
+            expect(state.Next).toBe('Step2');
+            expect(state.End).toBeUndefined();
+        });
+        it('should set End=true when node has no next property', () => {
+            const node = {
+                type: 'domain-action',
+                domainId: 'payments',
+                actionId: 'charge-card',
+            };
+            const state = codegen.generateTaskState(node);
+            expect(state.End).toBe(true);
+            expect(state.Next).toBeUndefined();
+        });
+        it('should generate correct FunctionName from domainId and actionId', () => {
+            const node = {
+                type: 'domain-action',
+                domainId: 'payments',
+                actionId: 'charge-card',
+            };
+            const state = codegen.generateTaskState(node);
+            expect(state.Parameters?.FunctionName).toBe('payments-charge-card');
+        });
+        it('should use label as Comment when provided', () => {
+            const node = {
+                type: 'domain-action',
+                domainId: 'payments',
+                actionId: 'charge-card',
+                label: 'Charge the card',
+            };
+            const state = codegen.generateTaskState(node);
+            expect(state.Comment).toBe('Charge the card');
+        });
+        it('should use default comment format when label is not provided', () => {
+            const node = {
+                type: 'domain-action',
+                domainId: 'payments',
+                actionId: 'charge-card',
+            };
+            const state = codegen.generateTaskState(node);
+            expect(state.Comment).toBe('Invoke domain action payments/charge-card');
+        });
+        it('should include standard Task fields in the state', () => {
+            const node = {
+                type: 'domain-action',
+                domainId: 'payments',
+                actionId: 'charge-card',
+            };
+            const state = codegen.generateTaskState(node);
+            expect(state.Type).toBe('Task');
+            expect(state.Resource).toBe('arn:aws:states:::lambda:invoke');
+            expect(state.Parameters?.['Payload.$']).toBe('$');
+        });
+        it('should include node parameters in the Parameters object', () => {
+            const node = {
+                type: 'domain-action',
+                domainId: 'payments',
+                actionId: 'charge-card',
+                parameters: { amount: 100, currency: 'USD' },
+            };
+            const state = codegen.generateTaskState(node);
+            expect(state.Parameters?.amount).toBe(100);
+            expect(state.Parameters?.currency).toBe('USD');
+        });
+    });
+    describe('generateStateMachine', () => {
+        it('should set StartAt to first node label by default', () => {
+            const nodes = [
+                {
+                    type: 'domain-action',
+                    domainId: 'payments',
+                    actionId: 'charge-card',
+                    label: 'Charge Card',
+                    next: 'Validate Payment',
+                },
+                {
+                    type: 'domain-action',
+                    domainId: 'payments',
+                    actionId: 'validate-payment',
+                    label: 'Validate Payment',
+                },
+            ];
+            const result = codegen.generateStateMachine(nodes);
+            expect(result.StartAt).toBe('Charge Card');
+        });
+        it('should set StartAt to first node actionId when label is missing', () => {
+            const nodes = [
+                {
+                    type: 'domain-action',
+                    domainId: 'payments',
+                    actionId: 'charge-card',
+                    next: 'payments/validate-payment',
+                },
+                {
+                    type: 'domain-action',
+                    domainId: 'payments',
+                    actionId: 'validate-payment',
+                },
+            ];
+            const result = codegen.generateStateMachine(nodes);
+            expect(result.StartAt).toBe('payments/charge-card');
+        });
+        it('should include all nodes as states with correct state names', () => {
+            const nodes = [
+                {
+                    type: 'domain-action',
+                    domainId: 'payments',
+                    actionId: 'charge-card',
+                    label: 'Charge Card',
+                },
+                {
+                    type: 'domain-action',
+                    domainId: 'payments',
+                    actionId: 'validate-payment',
+                    label: 'Validate Payment',
+                },
+            ];
+            const result = codegen.generateStateMachine(nodes);
+            expect(Object.keys(result.States)).toHaveLength(2);
+            expect(result.States['Charge Card']).toBeDefined();
+            expect(result.States['Validate Payment']).toBeDefined();
+        });
+        it('should use custom startAt parameter when provided', () => {
+            const nodes = [
+                {
+                    type: 'domain-action',
+                    domainId: 'payments',
+                    actionId: 'charge-card',
+                    label: 'Charge Card',
+                },
+                {
+                    type: 'domain-action',
+                    domainId: 'payments',
+                    actionId: 'validate-payment',
+                    label: 'Validate Payment',
+                },
+            ];
+            const result = codegen.generateStateMachine(nodes, 'CustomStart');
+            expect(result.StartAt).toBe('CustomStart');
+        });
+        it('should handle empty nodes array', () => {
+            const result = codegen.generateStateMachine([]);
+            expect(result.StartAt).toBe('Start');
+            expect(Object.keys(result.States)).toHaveLength(0);
+        });
+    });
+});

package/dist/constructs/action-construct.d.ts

@@ -0,0 +1,30 @@
+import * as lambdaNode from 'aws-cdk-lib/aws-lambda-nodejs';
+import { Construct } from 'constructs';
+import { LambdaFactory } from '../lambda-factory.js';
+import { IamPolicyBuilder } from '../iam/iam-policy-builder.js';
+import type { DomainRegistry } from '../registry.js';
+/**
+ * Configuration properties for ActionConstruct.
+ */
+export interface ActionConstructProps {
+    /** Domain registry containing all action entries. */
+    registry: DomainRegistry;
+    /** Factory for creating Lambda functions from registry entries. */
+    lambdaFactory: LambdaFactory;
+    /** IAM policy builder for granting permissions to Lambda roles. */
+    iamBuilder: IamPolicyBuilder;
+}
+/**
+ * CDK Construct that synthesises one Lambda per registered action, with optional Function URL for workspace-visible actions.
+ */
+export declare class ActionConstruct extends Construct {
+    /** Lambda function per action id. */
+    readonly functions: Map<string, lambdaNode.NodejsFunction>;
+    /**
+     * Create a new ActionConstruct instance.
+     * @param scope - Parent CDK scope.
+     * @param id - Construct identifier.
+     * @param props - Construct properties.
+     */
+    constructor(scope: Construct, id: string, props: ActionConstructProps);
+}

package/dist/constructs/action-construct.js

@@ -0,0 +1,32 @@
+import * as lambda from 'aws-cdk-lib/aws-lambda';
+import { Construct } from 'constructs';
+/**
+ * CDK Construct that synthesises one Lambda per registered action, with optional Function URL for workspace-visible actions.
+ */
+export class ActionConstruct extends Construct {
+    /** Lambda function per action id. */
+    functions;
+    /**
+     * Create a new ActionConstruct instance.
+     * @param scope - Parent CDK scope.
+     * @param id - Construct identifier.
+     * @param props - Construct properties.
+     */
+    constructor(scope, id, props) {
+        super(scope, id);
+        this.functions = new Map();
+        for (const entry of props.registry.actions) {
+            const fn = props.lambdaFactory.createFunction(entry, entry.deployment);
+            this.functions.set(entry.id, fn);
+            props.iamBuilder.forAction().forEach((statement) => {
+                fn.addToRolePolicy(statement);
+            });
+            if (entry.visibility === 'workspace') {
+                fn.addFunctionUrl({
+                    authType: lambda.FunctionUrlAuthType.NONE,
+                    cors: { allowedOrigins: ['*'], allowedMethods: [lambda.HttpMethod.ALL] },
+                });
+            }
+        }
+    }
+}

package/dist/constructs/api-construct.d.ts

@@ -0,0 +1,30 @@
+import * as apigwv2 from 'aws-cdk-lib/aws-apigatewayv2';
+import { Construct } from 'constructs';
+import { LambdaFactory } from '../lambda-factory.js';
+import { IamPolicyBuilder } from '../iam/iam-policy-builder.js';
+import type { DomainRegistry } from '../registry.js';
+/**
+ * Configuration properties for ApiConstruct.
+ */
+export interface ApiConstructProps {
+    /** Domain registry containing all API entries. */
+    registry: DomainRegistry;
+    /** Shared HttpApi to route requests to Lambdas. */
+    httpApi: apigwv2.HttpApi;
+    /** Factory for creating Lambda functions from registry entries. */
+    lambdaFactory: LambdaFactory;
+    /** IAM policy builder for granting permissions to Lambda roles. */
+    iamBuilder: IamPolicyBuilder;
+}
+/**
+ * CDK Construct that synthesises one Lambda per registered API and wires each to the shared HttpApi.
+ */
+export declare class ApiConstruct extends Construct {
+    /**
+     * Create a new ApiConstruct instance.
+     * @param scope - Parent CDK scope.
+     * @param id - Construct identifier.
+     * @param props - Construct properties.
+     */
+    constructor(scope: Construct, id: string, props: ApiConstructProps);
+}

package/dist/constructs/api-construct.js

@@ -0,0 +1,64 @@
+import * as apigwv2 from 'aws-cdk-lib/aws-apigatewayv2';
+import * as apigwv2integrations from 'aws-cdk-lib/aws-apigatewayv2-integrations';
+import { Construct } from 'constructs';
+/**
+ * CDK Construct that synthesises one Lambda per registered API and wires each to the shared HttpApi.
+ */
+export class ApiConstruct extends Construct {
+    /**
+     * Create a new ApiConstruct instance.
+     * @param scope - Parent CDK scope.
+     * @param id - Construct identifier.
+     * @param props - Construct properties.
+     */
+    constructor(scope, id, props) {
+        super(scope, id);
+        for (const entry of props.registry.apis) {
+            const fn = props.lambdaFactory.createFunction(entry, entry.deployment);
+            props.iamBuilder.forApi().forEach((statement) => {
+                fn.addToRolePolicy(statement);
+            });
+            props.httpApi.addRoutes({
+                path: entry.path,
+                methods: [toHttpMethod(entry.method)],
+                integration: new apigwv2integrations.HttpLambdaIntegration(`${id}${toPascalCase(entry.id)}Integration`, fn),
+            });
+        }
+    }
+}
+/**
+ * Convert kebab-case or snake_case string to PascalCase.
+ * @param s - Input string.
+ * @returns PascalCase string.
+ */
+function toPascalCase(s) {
+    return s
+        .split(/[-_]/)
+        .map((segment) => segment.charAt(0).toUpperCase() + segment.slice(1))
+        .join('');
+}
+/**
+ * Convert HTTP method string to ApiGatewayV2 HttpMethod enum.
+ * @param method - HTTP method string (e.g., 'GET', 'POST').
+ * @returns HttpMethod enum value.
+ */
+function toHttpMethod(method) {
+    switch (method.toUpperCase()) {
+        case 'GET':
+            return apigwv2.HttpMethod.GET;
+        case 'POST':
+            return apigwv2.HttpMethod.POST;
+        case 'PUT':
+            return apigwv2.HttpMethod.PUT;
+        case 'PATCH':
+            return apigwv2.HttpMethod.PATCH;
+        case 'DELETE':
+            return apigwv2.HttpMethod.DELETE;
+        case 'HEAD':
+            return apigwv2.HttpMethod.HEAD;
+        case 'OPTIONS':
+            return apigwv2.HttpMethod.OPTIONS;
+        default:
+            return apigwv2.HttpMethod.ANY;
+    }
+}

package/dist/constructs/job-construct.d.ts

@@ -0,0 +1,33 @@
+import * as sqs from 'aws-cdk-lib/aws-sqs';
+import { Construct } from 'constructs';
+import { LambdaFactory } from '../lambda-factory.js';
+import { IamPolicyBuilder } from '../iam/iam-policy-builder.js';
+import type { DomainRegistry } from '../registry.js';
+/**
+ * Configuration properties for JobConstruct.
+ */
+export interface JobConstructProps {
+    /** Domain registry containing job definitions. */
+    registry: DomainRegistry;
+    /** Factory for creating Lambda functions. */
+    lambdaFactory: LambdaFactory;
+    /** Builder for generating IAM policies. */
+    iamBuilder: IamPolicyBuilder;
+}
+/**
+ * CDK Construct that synthesizes Lambda functions with SQS queues, dead-letter queues,
+ * and event source mappings for background jobs defined in the domain registry.
+ */
+export declare class JobConstruct extends Construct {
+    /**
+     * Map of job IDs to their corresponding SQS queues.
+     */
+    readonly queues: Map<string, sqs.Queue>;
+    /**
+     * Create a new JobConstruct.
+     * @param scope - Parent CDK scope
+     * @param id - Construct identifier
+     * @param props - Configuration properties
+     */
+    constructor(scope: Construct, id: string, props: JobConstructProps);
+}

package/dist/constructs/job-construct.js

@@ -0,0 +1,54 @@
+import * as cdk from 'aws-cdk-lib';
+import * as sqs from 'aws-cdk-lib/aws-sqs';
+import * as lambdaEventSources from 'aws-cdk-lib/aws-lambda-event-sources';
+import { Construct } from 'constructs';
+/**
+ * CDK Construct that synthesizes Lambda functions with SQS queues, dead-letter queues,
+ * and event source mappings for background jobs defined in the domain registry.
+ */
+export class JobConstruct extends Construct {
+    /**
+     * Map of job IDs to their corresponding SQS queues.
+     */
+    queues;
+    /**
+     * Create a new JobConstruct.
+     * @param scope - Parent CDK scope
+     * @param id - Construct identifier
+     * @param props - Configuration properties
+     */
+    constructor(scope, id, props) {
+        super(scope, id);
+        this.queues = new Map();
+        for (const entry of props.registry.jobs) {
+            const pascalId = toPascalCase(entry.id);
+            const dlq = new sqs.Queue(this, `${pascalId}Dlq`, {
+                retentionPeriod: cdk.Duration.days(14),
+            });
+            const queue = new sqs.Queue(this, `${pascalId}Queue`, {
+                visibilityTimeout: cdk.Duration.seconds(entry.visibilityTimeoutSeconds),
+                deadLetterQueue: {
+                    queue: dlq,
+                    maxReceiveCount: entry.maxRetries,
+                },
+            });
+            this.queues.set(entry.id, queue);
+            const fn = props.lambdaFactory.createFunction(entry, entry.deployment);
+            props.iamBuilder
+                .forJob({ queueArn: queue.queueArn, dlqArn: dlq.queueArn })
+                .forEach((s) => fn.addToRolePolicy(s));
+            fn.addEventSource(new lambdaEventSources.SqsEventSource(queue, { batchSize: 1 }));
+        }
+    }
+}
+/**
+ * Convert a kebab-case or snake_case string to PascalCase.
+ * @param s - Input string to convert
+ * @returns PascalCase string
+ */
+function toPascalCase(s) {
+    return s
+        .split(/[-_]/)
+        .map((segment) => segment.charAt(0).toUpperCase() + segment.slice(1))
+        .join('');
+}

package/dist/constructs/schedule-construct.d.ts

@@ -0,0 +1,27 @@
+import { Construct } from 'constructs';
+import { LambdaFactory } from '../lambda-factory.js';
+import { IamPolicyBuilder } from '../iam/iam-policy-builder.js';
+import type { DomainRegistry } from '../registry.js';
+/**
+ * Configuration properties for ScheduleConstruct.
+ */
+export interface ScheduleConstructProps {
+    /** Domain registry containing schedule definitions */
+    registry: DomainRegistry;
+    /** Lambda factory for creating schedule handler functions */
+    lambdaFactory: LambdaFactory;
+    /** IAM policy builder for schedule handler permissions */
+    iamBuilder: IamPolicyBuilder;
+}
+/**
+ * CDK Construct that synthesises Lambda functions and EventBridge Scheduler rules per schedule entry.
+ */
+export declare class ScheduleConstruct extends Construct {
+    /**
+     * Create a new ScheduleConstruct.
+     * @param scope - Parent CDK Construct scope
+     * @param id - Logical ID for this construct
+     * @param props - Configuration properties
+     */
+    constructor(scope: Construct, id: string, props: ScheduleConstructProps);
+}

package/dist/constructs/schedule-construct.js

@@ -0,0 +1,54 @@
+import * as iam from 'aws-cdk-lib/aws-iam';
+import * as scheduler from 'aws-cdk-lib/aws-scheduler';
+import { Construct } from 'constructs';
+/**
+ * CDK Construct that synthesises Lambda functions and EventBridge Scheduler rules per schedule entry.
+ */
+export class ScheduleConstruct extends Construct {
+    /**
+     * Create a new ScheduleConstruct.
+     * @param scope - Parent CDK Construct scope
+     * @param id - Logical ID for this construct
+     * @param props - Configuration properties
+     */
+    constructor(scope, id, props) {
+        super(scope, id);
+        for (const entry of props.registry.schedules) {
+            const pascalId = toPascalCase(entry.id);
+            // Create the Lambda function for this schedule
+            const fn = props.lambdaFactory.createFunction(entry, entry.deployment);
+            // Attach schedule-specific IAM policies
+            props.iamBuilder.forSchedule().forEach((statement) => {
+                fn.addToRolePolicy(statement);
+            });
+            // Create a dedicated IAM role for the EventBridge Scheduler to assume
+            const schedulerRole = new iam.Role(this, `${pascalId}SchedulerRole`, {
+                assumedBy: new iam.ServicePrincipal('scheduler.amazonaws.com'),
+            });
+            // Grant the scheduler role permission to invoke the Lambda
+            fn.grantInvoke(schedulerRole);
+            // Create the EventBridge Scheduler rule
+            new scheduler.CfnSchedule(this, `${pascalId}Schedule`, {
+                scheduleExpression: entry.cron,
+                flexibleTimeWindow: { mode: 'OFF' },
+                state: entry.enabled ? 'ENABLED' : 'DISABLED',
+                target: {
+                    arn: fn.functionArn,
+                    roleArn: schedulerRole.roleArn,
+                    input: JSON.stringify({}),
+                },
+            });
+        }
+    }
+}
+/**
+ * Convert a kebab-case or snake_case string to PascalCase.
+ * @param s - Input string
+ * @returns PascalCase string
+ */
+function toPascalCase(s) {
+    return s
+        .split(/[-_]/)
+        .map((segment) => segment.charAt(0).toUpperCase() + segment.slice(1))
+        .join('');
+}