@jaypie/constructs 1.2.17 → 1.2.19

package/dist/cjs/index.cjs

@@ -9,7 +9,7 @@ var route53Targets = require('aws-cdk-lib/aws-route53-targets');
 var secretsmanager = require('aws-cdk-lib/aws-secretsmanager');
 var datadogCdkConstructsV2 = require('datadog-cdk-constructs-v2');
 var errors = require('@jaypie/errors');
-var awsIam = require('aws-cdk-lib/aws-iam');
+var iam = require('aws-cdk-lib/aws-iam');
 var acm = require('aws-cdk-lib/aws-certificatemanager');
 var lambda = require('aws-cdk-lib/aws-lambda');
 var logDestinations = require('aws-cdk-lib/aws-logs-destinations');
@@ -28,6 +28,8 @@ var path = require('path');
 var awsCloudtrail = require('aws-cdk-lib/aws-cloudtrail');
 var awsSso = require('aws-cdk-lib/aws-sso');
 var awsSam = require('aws-cdk-lib/aws-sam');
+var apigatewayv2 = require('aws-cdk-lib/aws-apigatewayv2');
+var apigatewayv2Integrations = require('aws-cdk-lib/aws-apigatewayv2-integrations');
 
 function _interopNamespaceDefault(e) {
     var n = Object.create(null);
@@ -52,6 +54,7 @@ var apiGateway__namespace = /*#__PURE__*/_interopNamespaceDefault(apiGateway);
 var route53__namespace = /*#__PURE__*/_interopNamespaceDefault(route53);
 var route53Targets__namespace = /*#__PURE__*/_interopNamespaceDefault(route53Targets);
 var secretsmanager__namespace = /*#__PURE__*/_interopNamespaceDefault(secretsmanager);
+var iam__namespace = /*#__PURE__*/_interopNamespaceDefault(iam);
 var acm__namespace = /*#__PURE__*/_interopNamespaceDefault(acm);
 var lambda__namespace = /*#__PURE__*/_interopNamespaceDefault(lambda);
 var logDestinations__namespace = /*#__PURE__*/_interopNamespaceDefault(logDestinations);
@@ -63,6 +66,8 @@ var cloudfront__namespace = /*#__PURE__*/_interopNamespaceDefault(cloudfront);
 var origins__namespace = /*#__PURE__*/_interopNamespaceDefault(origins);
 var dynamodb__namespace = /*#__PURE__*/_interopNamespaceDefault(dynamodb);
 var path__namespace = /*#__PURE__*/_interopNamespaceDefault(path);
+var apigatewayv2__namespace = /*#__PURE__*/_interopNamespaceDefault(apigatewayv2);
+var apigatewayv2Integrations__namespace = /*#__PURE__*/_interopNamespaceDefault(apigatewayv2Integrations);
 
 const CDK$2 = {
     ACCOUNT: {
@@ -434,22 +439,22 @@ function extendDatadogRole(scope, options) {
     }
     const { id = "DatadogCustomPolicy", project, service = CDK$2.SERVICE.DATADOG, } = options || {};
     // Lookup the Datadog role
-    const datadogRole = awsIam.Role.fromRoleArn(scope, "DatadogRole", datadogRoleArn);
+    const datadogRole = iam.Role.fromRoleArn(scope, "DatadogRole", datadogRoleArn);
     // Build policy statements
     const statements = [
         // Allow view budget
-        new awsIam.PolicyStatement({
+        new iam.PolicyStatement({
             actions: ["budgets:ViewBudget"],
             resources: ["*"],
         }),
         // Allow describe log groups
-        new awsIam.PolicyStatement({
+        new iam.PolicyStatement({
             actions: ["logs:DescribeLogGroups"],
             resources: ["*"],
         }),
     ];
     // Create the custom policy
-    const datadogCustomPolicy = new awsIam.Policy(scope, id, {
+    const datadogCustomPolicy = new iam.Policy(scope, id, {
         roles: [datadogRole],
         statements,
     });
@@ -2225,22 +2230,22 @@ class JaypieDatadogBucket extends constructs.Construct {
         }
         const { project, service = CDK$2.SERVICE.DATADOG } = options || {};
         // Lookup the Datadog role
-        const datadogRole = awsIam.Role.fromRoleArn(this, "DatadogRole", datadogRoleArn);
+        const datadogRole = iam.Role.fromRoleArn(this, "DatadogRole", datadogRoleArn);
         // Build policy statements for bucket access
         const statements = [
             // Allow list bucket
-            new awsIam.PolicyStatement({
+            new iam.PolicyStatement({
                 actions: ["s3:ListBucket"],
                 resources: [this.bucket.bucketArn],
             }),
             // Allow read and write to the bucket
-            new awsIam.PolicyStatement({
+            new iam.PolicyStatement({
                 actions: ["s3:GetObject", "s3:PutObject"],
                 resources: [`${this.bucket.bucketArn}/*`],
             }),
         ];
         // Create the custom policy
-        const datadogBucketPolicy = new awsIam.Policy(this, "DatadogBucketPolicy", {
+        const datadogBucketPolicy = new iam.Policy(this, "DatadogBucketPolicy", {
             roles: [datadogRole],
             statements,
         });
@@ -3009,8 +3014,8 @@ class JaypieGitHubDeployRole extends constructs.Construct {
             repoRestriction = `repo:${organization}/*:*`;
         }
         // Create the IAM role
-        this._role = new awsIam.Role(this, "GitHubActionsRole", {
-            assumedBy: new awsIam.FederatedPrincipal(oidcProviderArn, {
+        this._role = new iam.Role(this, "GitHubActionsRole", {
+            assumedBy: new iam.FederatedPrincipal(oidcProviderArn, {
                 StringLike: {
                     "token.actions.githubusercontent.com:sub": repoRestriction,
                 },
@@ -3020,12 +3025,12 @@ class JaypieGitHubDeployRole extends constructs.Construct {
         });
         cdk.Tags.of(this._role).add(CDK$2.TAG.ROLE, CDK$2.ROLE.DEPLOY);
         // Allow the role to access the GitHub OIDC provider
-        this._role.addToPolicy(new awsIam.PolicyStatement({
+        this._role.addToPolicy(new iam.PolicyStatement({
             actions: ["sts:AssumeRoleWithWebIdentity"],
             resources: [`arn:aws:iam::${accountId}:oidc-provider/*`],
         }));
         // Allow the role to deploy CDK apps
-        this._role.addToPolicy(new awsIam.PolicyStatement({
+        this._role.addToPolicy(new iam.PolicyStatement({
             actions: [
                 "cloudformation:CreateStack",
                 "cloudformation:DeleteStack",
@@ -3042,12 +3047,12 @@ class JaypieGitHubDeployRole extends constructs.Construct {
                 "s3:GetObject",
                 "s3:ListBucket",
             ],
-            effect: awsIam.Effect.ALLOW,
+            effect: iam.Effect.ALLOW,
             resources: ["*"],
         }));
-        this._role.addToPolicy(new awsIam.PolicyStatement({
+        this._role.addToPolicy(new iam.PolicyStatement({
             actions: ["iam:PassRole", "sts:AssumeRole"],
-            effect: awsIam.Effect.ALLOW,
+            effect: iam.Effect.ALLOW,
             resources: [
                 "arn:aws:iam::*:role/cdk-hnb659fds-deploy-role-*",
                 "arn:aws:iam::*:role/cdk-hnb659fds-file-publishing-*",
@@ -3142,7 +3147,7 @@ class JaypieHostedZone extends constructs.Construct {
             cdk__namespace.Tags.of(this.logGroup).add(CDK$2.TAG.PROJECT, project);
         }
         // Grant Route 53 permissions to write to the log group
-        this.logGroup.grantWrite(new awsIam.ServicePrincipal(SERVICE.ROUTE53));
+        this.logGroup.grantWrite(new iam.ServicePrincipal(SERVICE.ROUTE53));
         // Add destination based on configuration
         if (destination !== false) {
             const lambdaDestination = destination === true
@@ -3217,13 +3222,19 @@ class JaypieMongoDbSecret extends JaypieEnvSecret {
 class JaypieNextJs extends constructs.Construct {
     constructor(scope, id, props) {
         super(scope, id);
-        const domainName = typeof props?.domainName === "string"
-            ? props.domainName
-            : envHostname(props?.domainName);
+        // Determine if we should use a custom domain
+        const useDomain = props?.domainProps !== false;
+        // Resolve domain name only if using a custom domain
+        const domainName = useDomain
+            ? typeof props?.domainName === "string"
+                ? props.domainName
+                : envHostname(props?.domainName)
+            : undefined;
         this.domainName = domainName;
-        const domainNameSanitized = domainName
-            .replace(/\./g, "-")
-            .replace(/[^a-zA-Z0-9]/g, "_");
+        // Use domain name or construct ID for cache policy naming
+        const cachePolicyIdentifier = domainName
+            ? domainName.replace(/\./g, "-").replace(/[^a-zA-Z0-9]/g, "_")
+            : id.replace(/[^a-zA-Z0-9]/g, "_");
         // Resolve environment from array or object syntax
         const environment = resolveEnvironment(props?.environment);
         const envSecrets = props?.envSecrets || {};
@@ -3260,27 +3271,32 @@ class JaypieNextJs extends constructs.Construct {
         }, {});
         const nextjs = new cdkNextjsStandalone.Nextjs(this, "NextJsApp", {
             nextjsPath,
-            domainProps: {
-                domainName,
-                hostedZone: resolveHostedZone(this, {
-                    zone: props?.hostedZone,
-                }),
-            },
+            // Only configure custom domain if useDomain is true
+            ...(useDomain &&
+                domainName && {
+                domainProps: {
+                    domainName,
+                    hostedZone: resolveHostedZone(this, {
+                        zone: props?.hostedZone,
+                    }),
+                },
+            }),
             environment: {
                 ...jaypieLambdaEnv(),
                 ...environment,
                 ...secretsEnvironment,
                 ...jaypieSecretsEnvironment,
                 ...nextPublicEnv,
-                NEXT_PUBLIC_SITE_URL: `https://${domainName}`,
+                // NEXT_PUBLIC_SITE_URL will be set after construct creation for CloudFront URL
+                ...(domainName && { NEXT_PUBLIC_SITE_URL: `https://${domainName}` }),
             },
             overrides: {
                 nextjsDistribution: {
                     imageCachePolicyProps: {
-                        cachePolicyName: `NextJsImageCachePolicy-${domainNameSanitized}`,
+                        cachePolicyName: `NextJsImageCachePolicy-${cachePolicyIdentifier}`,
                     },
                     serverCachePolicyProps: {
-                        cachePolicyName: `NextJsServerCachePolicy-${domainNameSanitized}`,
+                        cachePolicyName: `NextJsServerCachePolicy-${cachePolicyIdentifier}`,
                     },
                 },
                 nextjsImage: {
@@ -3295,6 +3311,10 @@ class JaypieNextJs extends constructs.Construct {
                 },
             },
         });
+        // Set NEXT_PUBLIC_SITE_URL to CloudFront URL when no custom domain
+        if (!domainName) {
+            nextjs.serverFunction.lambdaFunction.addEnvironment("NEXT_PUBLIC_SITE_URL", `https://${nextjs.distribution.distributionDomain}`);
+        }
         addDatadogLayers(nextjs.imageOptimizationFunction);
         addDatadogLayers(nextjs.serverFunction.lambdaFunction);
         // Grant secret read permissions
@@ -3425,21 +3445,21 @@ class JaypieOrganizationTrail extends constructs.Construct {
             ],
         });
         // Add CloudTrail bucket policies
-        this.bucket.addToResourcePolicy(new awsIam.PolicyStatement({
+        this.bucket.addToResourcePolicy(new iam.PolicyStatement({
             actions: ["s3:GetBucketAcl"],
-            effect: awsIam.Effect.ALLOW,
-            principals: [new awsIam.ServicePrincipal("cloudtrail.amazonaws.com")],
+            effect: iam.Effect.ALLOW,
+            principals: [new iam.ServicePrincipal("cloudtrail.amazonaws.com")],
             resources: [this.bucket.bucketArn],
         }));
-        this.bucket.addToResourcePolicy(new awsIam.PolicyStatement({
+        this.bucket.addToResourcePolicy(new iam.PolicyStatement({
             actions: ["s3:PutObject"],
             conditions: {
                 StringEquals: {
                     "s3:x-amz-acl": "bucket-owner-full-control",
                 },
             },
-            effect: awsIam.Effect.ALLOW,
-            principals: [new awsIam.ServicePrincipal("cloudtrail.amazonaws.com")],
+            effect: iam.Effect.ALLOW,
+            principals: [new iam.ServicePrincipal("cloudtrail.amazonaws.com")],
             resources: [`${this.bucket.bucketArn}/*`],
         }));
         // Add tags to bucket
@@ -3532,9 +3552,9 @@ class JaypieSsoPermissions extends constructs.Construct {
                 ],
             },
             managedPolicies: [
-                awsIam.ManagedPolicy.fromAwsManagedPolicyName("AdministratorAccess")
+                iam.ManagedPolicy.fromAwsManagedPolicyName("AdministratorAccess")
                     .managedPolicyArn,
-                awsIam.ManagedPolicy.fromAwsManagedPolicyName("AWSManagementConsoleBasicUserAccess").managedPolicyArn,
+                iam.ManagedPolicy.fromAwsManagedPolicyName("AWSManagementConsoleBasicUserAccess").managedPolicyArn,
             ],
             sessionDuration: cdk.Duration.hours(1).toIsoString(),
             tags: [
@@ -3613,10 +3633,10 @@ class JaypieSsoPermissions extends constructs.Construct {
                 ],
             },
             managedPolicies: [
-                awsIam.ManagedPolicy.fromAwsManagedPolicyName("AmazonQDeveloperAccess")
+                iam.ManagedPolicy.fromAwsManagedPolicyName("AmazonQDeveloperAccess")
                     .managedPolicyArn,
-                awsIam.ManagedPolicy.fromAwsManagedPolicyName("AWSManagementConsoleBasicUserAccess").managedPolicyArn,
-                awsIam.ManagedPolicy.fromAwsManagedPolicyName("ReadOnlyAccess")
+                iam.ManagedPolicy.fromAwsManagedPolicyName("AWSManagementConsoleBasicUserAccess").managedPolicyArn,
+                iam.ManagedPolicy.fromAwsManagedPolicyName("ReadOnlyAccess")
                     .managedPolicyArn,
             ],
             sessionDuration: cdk.Duration.hours(12).toIsoString(),
@@ -3671,12 +3691,12 @@ class JaypieSsoPermissions extends constructs.Construct {
                 ],
             },
             managedPolicies: [
-                awsIam.ManagedPolicy.fromAwsManagedPolicyName("AmazonQDeveloperAccess")
+                iam.ManagedPolicy.fromAwsManagedPolicyName("AmazonQDeveloperAccess")
                     .managedPolicyArn,
-                awsIam.ManagedPolicy.fromAwsManagedPolicyName("AWSManagementConsoleBasicUserAccess").managedPolicyArn,
-                awsIam.ManagedPolicy.fromAwsManagedPolicyName("ReadOnlyAccess")
+                iam.ManagedPolicy.fromAwsManagedPolicyName("AWSManagementConsoleBasicUserAccess").managedPolicyArn,
+                iam.ManagedPolicy.fromAwsManagedPolicyName("ReadOnlyAccess")
                     .managedPolicyArn,
-                awsIam.ManagedPolicy.fromAwsManagedPolicyName("job-function/SystemAdministrator").managedPolicyArn,
+                iam.ManagedPolicy.fromAwsManagedPolicyName("job-function/SystemAdministrator").managedPolicyArn,
             ],
             sessionDuration: cdk.Duration.hours(4).toIsoString(),
             tags: [
@@ -3889,8 +3909,8 @@ class JaypieWebDeploymentBucket extends constructs.Construct {
             repo = `repo:${process.env.CDK_ENV_REPO}:*`;
         }
         if (repo) {
-            const bucketDeployRole = new awsIam.Role(this, "DestinationBucketDeployRole", {
-                assumedBy: new awsIam.FederatedPrincipal(cdk.Fn.importValue(CDK$2.IMPORT.OIDC_PROVIDER), {
+            const bucketDeployRole = new iam.Role(this, "DestinationBucketDeployRole", {
+                assumedBy: new iam.FederatedPrincipal(cdk.Fn.importValue(CDK$2.IMPORT.OIDC_PROVIDER), {
                     StringLike: {
                         "token.actions.githubusercontent.com:sub": repo,
                     },
@@ -3899,8 +3919,8 @@ class JaypieWebDeploymentBucket extends constructs.Construct {
             });
             cdk.Tags.of(bucketDeployRole).add(CDK$2.TAG.ROLE, CDK$2.ROLE.DEPLOY);
             // Allow the role to write to the bucket
-            bucketDeployRole.addToPolicy(new awsIam.PolicyStatement({
-                effect: awsIam.Effect.ALLOW,
+            bucketDeployRole.addToPolicy(new iam.PolicyStatement({
+                effect: iam.Effect.ALLOW,
                 actions: [
                     "s3:DeleteObject",
                     "s3:GetObject",
@@ -3909,16 +3929,16 @@ class JaypieWebDeploymentBucket extends constructs.Construct {
                 ],
                 resources: [`${this.bucket.bucketArn}/*`],
             }));
-            bucketDeployRole.addToPolicy(new awsIam.PolicyStatement({
-                effect: awsIam.Effect.ALLOW,
+            bucketDeployRole.addToPolicy(new iam.PolicyStatement({
+                effect: iam.Effect.ALLOW,
                 actions: ["s3:ListBucket"],
                 resources: [this.bucket.bucketArn],
             }));
             // Allow the role to describe the current stack
             const stack = cdk.Stack.of(this);
-            bucketDeployRole.addToPolicy(new awsIam.PolicyStatement({
+            bucketDeployRole.addToPolicy(new iam.PolicyStatement({
                 actions: ["cloudformation:DescribeStacks"],
-                effect: awsIam.Effect.ALLOW,
+                effect: iam.Effect.ALLOW,
                 resources: [
                     `arn:aws:cloudformation:${stack.region}:${stack.account}:stack/${stack.stackName}/*`,
                 ],
@@ -4135,6 +4155,377 @@ class JaypieTraceSigningKeySecret extends JaypieEnvSecret {
     }
 }
 
+//
+//
+// Main
+//
+class JaypieWebSocket extends constructs.Construct {
+    constructor(scope, id, props = {}) {
+        super(scope, id);
+        const { certificate = true, connect, default: defaultHandler, disconnect, handler, host: propsHost, logRetention = logs__namespace.RetentionDays.THREE_MONTHS, name, roleTag = CDK$2.ROLE.API, routes = {}, stageName = "production", zone: propsZone, } = props;
+        // Validate: either handler OR individual handlers, not both
+        const hasIndividualHandlers = connect || disconnect || defaultHandler;
+        if (handler && hasIndividualHandlers) {
+            throw new Error("Cannot specify both 'handler' and individual route handlers (connect/disconnect/default)");
+        }
+        // Determine zone from props or environment
+        let zone = propsZone;
+        if (!zone && process.env.CDK_ENV_HOSTED_ZONE) {
+            zone = process.env.CDK_ENV_HOSTED_ZONE;
+        }
+        // Determine host from props or environment
+        let host;
+        if (typeof propsHost === "string") {
+            host = propsHost;
+        }
+        else if (typeof propsHost === "object") {
+            // Resolve host from HostConfig using envHostname()
+            host = envHostname(propsHost);
+        }
+        else if (process.env.CDK_ENV_WS_HOST_NAME) {
+            host = process.env.CDK_ENV_WS_HOST_NAME;
+        }
+        else if (process.env.CDK_ENV_WS_SUBDOMAIN &&
+            process.env.CDK_ENV_HOSTED_ZONE) {
+            host = mergeDomain(process.env.CDK_ENV_WS_SUBDOMAIN, process.env.CDK_ENV_HOSTED_ZONE);
+        }
+        const apiName = name || constructEnvName("WebSocket");
+        // Create WebSocket API
+        this._api = new apigatewayv2__namespace.WebSocketApi(this, "Api", {
+            apiName,
+        });
+        cdk.Tags.of(this._api).add(CDK$2.TAG.ROLE, roleTag);
+        // Add routes with Lambda integrations
+        const connectHandler = handler || connect;
+        const disconnectHandler = handler || disconnect;
+        const defaultRouteHandler = handler || defaultHandler;
+        if (connectHandler) {
+            this._api.addRoute("$connect", {
+                integration: new apigatewayv2Integrations__namespace.WebSocketLambdaIntegration("ConnectIntegration", connectHandler),
+            });
+        }
+        if (disconnectHandler) {
+            this._api.addRoute("$disconnect", {
+                integration: new apigatewayv2Integrations__namespace.WebSocketLambdaIntegration("DisconnectIntegration", disconnectHandler),
+            });
+        }
+        if (defaultRouteHandler) {
+            this._api.addRoute("$default", {
+                integration: new apigatewayv2Integrations__namespace.WebSocketLambdaIntegration("DefaultIntegration", defaultRouteHandler),
+            });
+        }
+        // Add custom routes
+        for (const [routeKey, routeHandler] of Object.entries(routes)) {
+            this._api.addRoute(routeKey, {
+                integration: new apigatewayv2Integrations__namespace.WebSocketLambdaIntegration(`${routeKey}Integration`, routeHandler),
+            });
+        }
+        // Create log group for access logs
+        // Note: logGroup is created for future use when API Gateway v2 WebSocket
+        // access logging is fully supported in CDK
+        new logs__namespace.LogGroup(this, "AccessLogs", {
+            removalPolicy: cdk.RemovalPolicy.DESTROY,
+            retention: logRetention,
+        });
+        // Create stage
+        this._stage = new apigatewayv2__namespace.WebSocketStage(this, "Stage", {
+            autoDeploy: true,
+            stageName,
+            webSocketApi: this._api,
+        });
+        cdk.Tags.of(this._stage).add(CDK$2.TAG.ROLE, roleTag);
+        // Set up custom domain if host and zone are provided
+        let hostedZone;
+        let certificateToUse;
+        if (host && zone) {
+            hostedZone = resolveHostedZone(this, { zone });
+            // Use resolveCertificate to create certificate at stack level (enables reuse)
+            certificateToUse = resolveCertificate(this, {
+                certificate,
+                domainName: host,
+                roleTag: CDK$2.ROLE.HOSTING,
+                zone: hostedZone,
+            });
+            this._certificate = certificateToUse;
+            this._host = host;
+            if (certificateToUse) {
+                // Create custom domain
+                this._domainName = new apigatewayv2__namespace.DomainName(this, "DomainName", {
+                    certificate: certificateToUse,
+                    domainName: host,
+                });
+                cdk.Tags.of(this._domainName).add(CDK$2.TAG.ROLE, roleTag);
+                // Map domain to stage
+                new apigatewayv2__namespace.ApiMapping(this, "ApiMapping", {
+                    api: this._api,
+                    domainName: this._domainName,
+                    stage: this._stage,
+                });
+                // Create DNS record
+                new route53__namespace.ARecord(this, "AliasRecord", {
+                    recordName: host,
+                    target: route53__namespace.RecordTarget.fromAlias(new route53Targets__namespace.ApiGatewayv2DomainProperties(this._domainName.regionalDomainName, this._domainName.regionalHostedZoneId)),
+                    zone: hostedZone,
+                });
+                // Also create AAAA record for IPv6
+                new route53__namespace.AaaaRecord(this, "AaaaAliasRecord", {
+                    recordName: host,
+                    target: route53__namespace.RecordTarget.fromAlias(new route53Targets__namespace.ApiGatewayv2DomainProperties(this._domainName.regionalDomainName, this._domainName.regionalHostedZoneId)),
+                    zone: hostedZone,
+                });
+            }
+        }
+        // Grant all handlers permission to manage connections
+        const allHandlers = new Set();
+        if (connectHandler)
+            allHandlers.add(connectHandler);
+        if (disconnectHandler)
+            allHandlers.add(disconnectHandler);
+        if (defaultRouteHandler)
+            allHandlers.add(defaultRouteHandler);
+        Object.values(routes).forEach((h) => allHandlers.add(h));
+        for (const lambdaHandler of allHandlers) {
+            this.grantManageConnections(lambdaHandler);
+        }
+    }
+    //
+    //
+    // Public accessors
+    //
+    get api() {
+        return this._api;
+    }
+    get apiId() {
+        return this._api.apiId;
+    }
+    get certificate() {
+        return this._certificate;
+    }
+    get domainName() {
+        return this._domainName?.name;
+    }
+    /**
+     * The WebSocket endpoint URL.
+     * Uses custom domain if configured, otherwise returns the default stage URL.
+     */
+    get endpoint() {
+        if (this._host) {
+            return `wss://${this._host}`;
+        }
+        return this._stage.url;
+    }
+    get host() {
+        return this._host;
+    }
+    get stage() {
+        return this._stage;
+    }
+    /**
+     * The callback URL for API Gateway Management API.
+     * Use this URL to send messages to connected clients.
+     */
+    get callbackUrl() {
+        if (this._host) {
+            return `https://${this._host}`;
+        }
+        // Extract callback URL from stage URL
+        // Stage URL: wss://abc123.execute-api.us-east-1.amazonaws.com/production
+        // Callback URL: https://abc123.execute-api.us-east-1.amazonaws.com/production
+        return this._stage.url.replace("wss://", "https://");
+    }
+    //
+    //
+    // Public methods
+    //
+    /**
+     * Grant a Lambda function permission to manage WebSocket connections
+     * (post to connections, delete connections).
+     */
+    grantManageConnections(grantee) {
+        return iam__namespace.Grant.addToPrincipal({
+            actions: ["execute-api:ManageConnections"],
+            grantee: grantee.grantPrincipal,
+            resourceArns: [
+                cdk.Stack.of(this).formatArn({
+                    arnFormat: cdk.ArnFormat.SLASH_RESOURCE_SLASH_RESOURCE_NAME,
+                    resource: this._api.apiId,
+                    resourceName: `${this._stage.stageName}/*`,
+                    service: "execute-api",
+                }),
+            ],
+        });
+    }
+}
+
+/**
+ * JaypieWebSocketLambda - A Lambda function optimized for WebSocket handlers.
+ *
+ * Provides sensible defaults for WebSocket event handling:
+ * - 30 second timeout (same as API handlers)
+ * - API role tag
+ *
+ * @example
+ * ```typescript
+ * const handler = new JaypieWebSocketLambda(this, "ChatHandler", {
+ *   code: "dist/handlers",
+ *   handler: "chat.handler",
+ *   secrets: ["MONGODB_URI"],
+ * });
+ *
+ * new JaypieWebSocket(this, "Chat", {
+ *   host: "ws.example.com",
+ *   handler,
+ * });
+ * ```
+ */
+class JaypieWebSocketLambda extends JaypieLambda {
+    constructor(scope, id, props) {
+        super(scope, id, {
+            roleTag: CDK$2.ROLE.API,
+            timeout: cdk.Duration.seconds(CDK$2.DURATION.EXPRESS_API),
+            ...props,
+        });
+    }
+}
+
+//
+//
+// Main
+//
+/**
+ * JaypieWebSocketTable - DynamoDB table for storing WebSocket connection IDs.
+ *
+ * Provides a simple table structure for tracking active WebSocket connections:
+ * - Partition key: connectionId (String)
+ * - TTL attribute: expiresAt (for automatic cleanup)
+ * - Optional GSI: userId-index (for looking up connections by user)
+ *
+ * @example
+ * ```typescript
+ * const connectionTable = new JaypieWebSocketTable(this, "Connections");
+ *
+ * const ws = new JaypieWebSocket(this, "Chat", {
+ *   host: "ws.example.com",
+ *   handler: chatHandler,
+ * });
+ *
+ * // Grant Lambda access to the table
+ * connectionTable.grantReadWriteData(chatHandler);
+ *
+ * // Pass table name to Lambda
+ * chatHandler.addEnvironment("CONNECTION_TABLE", connectionTable.tableName);
+ * ```
+ *
+ * @example
+ * // With user index for looking up all connections for a user
+ * const connectionTable = new JaypieWebSocketTable(this, "Connections", {
+ *   userIndex: true,
+ *   ttl: Duration.hours(12),
+ * });
+ */
+class JaypieWebSocketTable extends constructs.Construct {
+    constructor(scope, id, props = {}) {
+        super(scope, id);
+        const { roleTag = CDK$2.ROLE.STORAGE, tableName, ttl = cdk.Duration.hours(24), userIndex = false, } = props;
+        this._ttlDuration = ttl;
+        // Build global secondary indexes
+        const globalSecondaryIndexes = [];
+        if (userIndex) {
+            globalSecondaryIndexes.push({
+                indexName: "userId-index",
+                partitionKey: { name: "userId", type: dynamodb__namespace.AttributeType.STRING },
+                sortKey: { name: "connectedAt", type: dynamodb__namespace.AttributeType.STRING },
+            });
+        }
+        // Create the table
+        this._table = new dynamodb__namespace.TableV2(this, "Table", {
+            billing: dynamodb__namespace.Billing.onDemand(),
+            globalSecondaryIndexes: globalSecondaryIndexes.length > 0 ? globalSecondaryIndexes : undefined,
+            partitionKey: {
+                name: "connectionId",
+                type: dynamodb__namespace.AttributeType.STRING,
+            },
+            removalPolicy: cdk.RemovalPolicy.DESTROY,
+            tableName: tableName || constructEnvName("WebSocketConnections"),
+            timeToLiveAttribute: "expiresAt",
+        });
+        cdk.Tags.of(this._table).add(CDK$2.TAG.ROLE, roleTag);
+    }
+    //
+    //
+    // Public accessors
+    //
+    /**
+     * The underlying DynamoDB TableV2 construct.
+     */
+    get table() {
+        return this._table;
+    }
+    /**
+     * The name of the DynamoDB table.
+     */
+    get tableName() {
+        return this._table.tableName;
+    }
+    /**
+     * The ARN of the DynamoDB table.
+     */
+    get tableArn() {
+        return this._table.tableArn;
+    }
+    /**
+     * TTL duration for connections in seconds.
+     * Use this to calculate expiresAt when storing connections.
+     */
+    get ttlSeconds() {
+        return this._ttlDuration.toSeconds();
+    }
+    //
+    //
+    // Grant methods
+    //
+    /**
+     * Grant read permissions to the table.
+     */
+    grantReadData(grantee) {
+        return this._table.grantReadData(grantee);
+    }
+    /**
+     * Grant write permissions to the table.
+     */
+    grantWriteData(grantee) {
+        return this._table.grantWriteData(grantee);
+    }
+    /**
+     * Grant read and write permissions to the table.
+     */
+    grantReadWriteData(grantee) {
+        return this._table.grantReadWriteData(grantee);
+    }
+    //
+    //
+    // Convenience methods
+    //
+    /**
+     * Add the table name to a Lambda function's environment variables.
+     * Also grants read/write access to the table.
+     */
+    connectLambda(lambdaFunction, options = {}) {
+        const { envKey = "CONNECTION_TABLE", readOnly = false } = options;
+        // Add environment variable
+        if ("addEnvironment" in lambdaFunction) {
+            lambdaFunction.addEnvironment(envKey, this.tableName);
+        }
+        // Grant permissions
+        if (readOnly) {
+            this.grantReadData(lambdaFunction.grantPrincipal);
+        }
+        else {
+            this.grantReadWriteData(lambdaFunction.grantPrincipal);
+        }
+    }
+}
+
 exports.CDK = CDK$2;
 exports.JaypieAccountLoggingBucket = JaypieAccountLoggingBucket;
 exports.JaypieApiGateway = JaypieApiGateway;
@@ -4165,6 +4556,9 @@ exports.JaypieStack = JaypieStack;
 exports.JaypieStaticWebBucket = JaypieStaticWebBucket;
 exports.JaypieTraceSigningKeySecret = JaypieTraceSigningKeySecret;
 exports.JaypieWebDeploymentBucket = JaypieWebDeploymentBucket;
+exports.JaypieWebSocket = JaypieWebSocket;
+exports.JaypieWebSocketLambda = JaypieWebSocketLambda;
+exports.JaypieWebSocketTable = JaypieWebSocketTable;
 exports.addDatadogLayers = addDatadogLayers;
 exports.clearAllCertificateCaches = clearAllCertificateCaches;
 exports.clearAllSecretsCaches = clearAllSecretsCaches;