@composurecdk/s3 0.6.0 → 0.8.0

package/dist/commonjs/defaults.js

@@ -0,0 +1,118 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BUCKET_DEFAULTS = exports.DEFAULT_ACCESS_LOG_BUCKET_LIFECYCLE_RULES = exports.DEFAULT_BUCKET_LIFECYCLE_RULES = void 0;
+const aws_s3_1 = require("aws-cdk-lib/aws-s3");
+const aws_cdk_lib_1 = require("aws-cdk-lib");
+/**
+ * Aborts multipart uploads that have not completed within 7 days. AWS recommends
+ * this rule on every bucket — orphaned upload parts are billed as storage but
+ * never become objects, so the rule is pure cost hygiene with no functional
+ * downside.
+ *
+ * @see https://docs.aws.amazon.com/AmazonS3/latest/userguide/mpu-abort-incomplete-mpu-lifecycle-config.html
+ */
+const ABORT_INCOMPLETE_MULTIPART_UPLOADS = {
+    id: "AbortIncompleteMultipartUploadAfter7Days",
+    abortIncompleteMultipartUploadAfter: aws_cdk_lib_1.Duration.days(7),
+};
+/**
+ * Lifecycle rules applied to general-purpose buckets built with
+ * {@link createBucketBuilder}. Bounds storage cost from orphaned multipart
+ * parts and from accumulated noncurrent versions of objects in versioned
+ * buckets, while preserving a generous recovery window.
+ *
+ * Users who need different rules can override the entire set via the
+ * `.lifecycleRules([...])` builder method.
+ */
+exports.DEFAULT_BUCKET_LIFECYCLE_RULES = [
+    ABORT_INCOMPLETE_MULTIPART_UPLOADS,
+    {
+        /**
+         * Buckets default to `versioned: true`, so replaced and deleted objects
+         * accumulate as noncurrent versions indefinitely. Expiring them after a
+         * year preserves a long recovery window for "oops" deletions while
+         * preventing unbounded storage growth.
+         *
+         * @see https://docs.aws.amazon.com/AmazonS3/latest/userguide/lifecycle-configuration-examples.html
+         */
+        id: "ExpireNoncurrentVersionsAfter365Days",
+        noncurrentVersionExpiration: aws_cdk_lib_1.Duration.days(365),
+    },
+];
+/**
+ * Lifecycle rules applied to auto-created S3 server access log buckets and
+ * CloudFront access log buckets. Mirrors the 2-year retention used by
+ * {@link LOG_GROUP_DEFAULTS} so the audit window is consistent across log
+ * destinations in the library.
+ *
+ * @see https://docs.aws.amazon.com/wellarchitected/latest/security-pillar/sec_detect_investigate_events_app_service_logging.html
+ */
+exports.DEFAULT_ACCESS_LOG_BUCKET_LIFECYCLE_RULES = [
+    ABORT_INCOMPLETE_MULTIPART_UPLOADS,
+    {
+        id: "ExpireAccessLogsAfter2Years",
+        expiration: aws_cdk_lib_1.Duration.days(731),
+    },
+];
+/**
+ * Secure, AWS-recommended defaults applied to every S3 bucket built
+ * with {@link createBucketBuilder}. Each property can be individually
+ * overridden via the builder's fluent API.
+ */
+exports.BUCKET_DEFAULTS = {
+    /**
+     * Auto-create a dedicated logging bucket and write S3 server access logs
+     * to it under the `logs/` prefix. Access logging provides an audit trail
+     * of all object-level operations for security monitoring and
+     * troubleshooting.
+     *
+     * @see https://docs.aws.amazon.com/wellarchitected/latest/security-pillar/sec_detect_investigate_events_app_service_logging.html
+     */
+    serverAccessLogs: { prefix: "logs/" },
+    /**
+     * Block all public access to the bucket. S3 buckets should not be
+     * publicly accessible unless explicitly required (e.g. static website
+     * hosting via CloudFront OAC).
+     * @see https://docs.aws.amazon.com/AmazonS3/latest/userguide/access-control-block-public-access.html
+     */
+    blockPublicAccess: aws_s3_1.BlockPublicAccess.BLOCK_ALL,
+    /**
+     * Enable server-side encryption with S3-managed keys (SSE-S3).
+     * This is the default and lowest-cost encryption option.
+     * @see https://docs.aws.amazon.com/wellarchitected/latest/security-pillar/protecting-data-at-rest.html
+     */
+    encryption: aws_s3_1.BucketEncryption.S3_MANAGED,
+    /**
+     * Enforce SSL/TLS for all requests to the bucket.
+     * @see https://docs.aws.amazon.com/AmazonS3/latest/userguide/security-best-practices.html
+     */
+    enforceSSL: true,
+    /**
+     * Enable versioning to protect against accidental deletions and
+     * support rollback.
+     * @see https://docs.aws.amazon.com/AmazonS3/latest/userguide/Versioning.html
+     */
+    versioned: true,
+    /**
+     * Bound storage cost on every bucket: abort orphaned multipart uploads
+     * after 7 days and expire noncurrent object versions after 365 days.
+     *
+     * Override with `.lifecycleRules([...])` to supply your own rule set —
+     * the array is replaced wholesale, consistent with how every other
+     * builder default is overridden.
+     *
+     * @see {@link DEFAULT_BUCKET_LIFECYCLE_RULES}
+     */
+    lifecycleRules: exports.DEFAULT_BUCKET_LIFECYCLE_RULES,
+    /**
+     * Retain the bucket on stack deletion to prevent data loss.
+     *
+     * When overridden to `RemovalPolicy.DESTROY`, the builder automatically
+     * enables `autoDeleteObjects` (unless explicitly set to `false`) so that
+     * non-empty buckets can be cleanly removed during stack deletion.
+     *
+     * @see https://docs.aws.amazon.com/cdk/v2/guide/resources.html#resources_removal
+     */
+    removalPolicy: aws_cdk_lib_1.RemovalPolicy.RETAIN,
+};
+//# sourceMappingURL=defaults.js.map

package/dist/commonjs/defaults.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"defaults.js","sourceRoot":"","sources":["../../src/defaults.ts"],"names":[],"mappings":";;;AAAA,+CAA6F;AAC7F,6CAAsD;AAGtD;;;;;;;GAOG;AACH,MAAM,kCAAkC,GAAkB;IACxD,EAAE,EAAE,0CAA0C;IAC9C,mCAAmC,EAAE,sBAAQ,CAAC,IAAI,CAAC,CAAC,CAAC;CACtD,CAAC;AAEF;;;;;;;;GAQG;AACU,QAAA,8BAA8B,GAAoB;IAC7D,kCAAkC;IAClC;QACE;;;;;;;WAOG;QACH,EAAE,EAAE,sCAAsC;QAC1C,2BAA2B,EAAE,sBAAQ,CAAC,IAAI,CAAC,GAAG,CAAC;KAChD;CACF,CAAC;AAEF;;;;;;;GAOG;AACU,QAAA,yCAAyC,GAAoB;IACxE,kCAAkC;IAClC;QACE,EAAE,EAAE,6BAA6B;QACjC,UAAU,EAAE,sBAAQ,CAAC,IAAI,CAAC,GAAG,CAAC;KAC/B;CACF,CAAC;AAEF;;;;GAIG;AACU,QAAA,eAAe,GAAgC;IAC1D;;;;;;;OAOG;IACH,gBAAgB,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE;IAErC;;;;;OAKG;IACH,iBAAiB,EAAE,0BAAiB,CAAC,SAAS;IAE9C;;;;OAIG;IACH,UAAU,EAAE,yBAAgB,CAAC,UAAU;IAEvC;;;OAGG;IACH,UAAU,EAAE,IAAI;IAEhB;;;;OAIG;IACH,SAAS,EAAE,IAAI;IAEf;;;;;;;;;OASG;IACH,cAAc,EAAE,sCAA8B;IAE9C;;;;;;;;OAQG;IACH,aAAa,EAAE,2BAAa,CAAC,MAAM;CACpC,CAAC"}

package/dist/commonjs/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,mBAAmB,EACnB,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,EACxB,KAAK,cAAc,EACnB,KAAK,sBAAsB,GAC5B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,eAAe,EACf,yCAAyC,EACzC,8BAA8B,GAC/B,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,KAAK,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAC3D,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,EACL,6BAA6B,EAC7B,KAAK,6BAA6B,EAClC,KAAK,wBAAwB,GAC9B,MAAM,gCAAgC,CAAC;AACxC,OAAO,EAAE,KAAK,4BAA4B,EAAE,MAAM,8BAA8B,CAAC;AACjF,OAAO,EAAE,0BAA0B,EAAE,MAAM,iCAAiC,CAAC"}

package/dist/commonjs/index.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BUCKET_DEPLOYMENT_DEFAULTS = exports.createBucketDeploymentBuilder = exports.BUCKET_ALARM_DEFAULTS = exports.DEFAULT_BUCKET_LIFECYCLE_RULES = exports.DEFAULT_ACCESS_LOG_BUCKET_LIFECYCLE_RULES = exports.BUCKET_DEFAULTS = exports.createBucketBuilder = void 0;
+var bucket_builder_js_1 = require("./bucket-builder.js");
+Object.defineProperty(exports, "createBucketBuilder", { enumerable: true, get: function () { return bucket_builder_js_1.createBucketBuilder; } });
+var defaults_js_1 = require("./defaults.js");
+Object.defineProperty(exports, "BUCKET_DEFAULTS", { enumerable: true, get: function () { return defaults_js_1.BUCKET_DEFAULTS; } });
+Object.defineProperty(exports, "DEFAULT_ACCESS_LOG_BUCKET_LIFECYCLE_RULES", { enumerable: true, get: function () { return defaults_js_1.DEFAULT_ACCESS_LOG_BUCKET_LIFECYCLE_RULES; } });
+Object.defineProperty(exports, "DEFAULT_BUCKET_LIFECYCLE_RULES", { enumerable: true, get: function () { return defaults_js_1.DEFAULT_BUCKET_LIFECYCLE_RULES; } });
+var alarm_defaults_js_1 = require("./alarm-defaults.js");
+Object.defineProperty(exports, "BUCKET_ALARM_DEFAULTS", { enumerable: true, get: function () { return alarm_defaults_js_1.BUCKET_ALARM_DEFAULTS; } });
+var bucket_deployment_builder_js_1 = require("./bucket-deployment-builder.js");
+Object.defineProperty(exports, "createBucketDeploymentBuilder", { enumerable: true, get: function () { return bucket_deployment_builder_js_1.createBucketDeploymentBuilder; } });
+var bucket_deployment_defaults_js_1 = require("./bucket-deployment-defaults.js");
+Object.defineProperty(exports, "BUCKET_DEPLOYMENT_DEFAULTS", { enumerable: true, get: function () { return bucket_deployment_defaults_js_1.BUCKET_DEPLOYMENT_DEFAULTS; } });
+//# sourceMappingURL=index.js.map

package/dist/commonjs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;AAAA,yDAM6B;AAL3B,wHAAA,mBAAmB,OAAA;AAMrB,6CAIuB;AAHrB,8GAAA,eAAe,OAAA;AACf,wIAAA,yCAAyC,OAAA;AACzC,6HAAA,8BAA8B,OAAA;AAGhC,yDAA4D;AAAnD,0HAAA,qBAAqB,OAAA;AAC9B,+EAIwC;AAHtC,6IAAA,6BAA6B,OAAA;AAK/B,iFAA6E;AAApE,2IAAA,0BAA0B,OAAA"}

package/dist/commonjs/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}

package/dist/esm/alarm-config.d.ts

@@ -0,0 +1,48 @@
+import type { AlarmConfig } from "@composurecdk/cloudwatch";
+/**
+ * Controls which recommended alarms are created for an S3 bucket.
+ * All applicable alarms are enabled by default with AWS-recommended thresholds.
+ * Set individual alarms to `false` to disable them, or provide an
+ * {@link AlarmConfig} to tune thresholds.
+ *
+ * S3 request metric alarms (5xxErrors, 4xxErrors) require
+ * [CloudWatch request metrics](https://docs.aws.amazon.com/AmazonS3/latest/userguide/configure-request-metrics-bucket.html)
+ * to be enabled on the bucket. Alarms are automatically created for each
+ * entry in the bucket's {@link BucketProps.metrics} array, keyed by the
+ * metrics configuration ID (e.g. `serverErrors:EntireBucket`).
+ *
+ * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#S3
+ */
+export interface BucketAlarmConfig {
+    /**
+     * Master switch: set to `false` to disable all recommended alarms.
+     * Individual alarms can also be disabled via their own entry.
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Alarm when S3 returns server-side errors (5xx HTTP status codes).
+     *
+     * Metric: `AWS/S3 5xxErrors`, statistic Sum, period 5 minutes.
+     * Default threshold: > 0 errors.
+     *
+     * Only created when the bucket has request metrics configured via
+     * {@link BucketProps.metrics}. One alarm per metrics configuration.
+     *
+     * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#S3
+     */
+    serverErrors?: AlarmConfig | false;
+    /**
+     * Alarm when S3 returns client-side errors (4xx HTTP status codes).
+     *
+     * Metric: `AWS/S3 4xxErrors`, statistic Sum, period 5 minutes.
+     * Default threshold: > 0 errors.
+     *
+     * Only created when the bucket has request metrics configured via
+     * {@link BucketProps.metrics}. One alarm per metrics configuration.
+     *
+     * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#S3
+     */
+    clientErrors?: AlarmConfig | false;
+}
+//# sourceMappingURL=alarm-config.d.ts.map

package/dist/esm/alarm-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"alarm-config.d.ts","sourceRoot":"","sources":["../../src/alarm-config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAE5D;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;;;;;;;;;OAUG;IACH,YAAY,CAAC,EAAE,WAAW,GAAG,KAAK,CAAC;IAEnC;;;;;;;;;;OAUG;IACH,YAAY,CAAC,EAAE,WAAW,GAAG,KAAK,CAAC;CACpC"}

package/dist/esm/alarm-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"alarm-config.js","sourceRoot":"","sources":["../../src/alarm-config.ts"],"names":[],"mappings":""}

package/dist/esm/alarm-defaults.d.ts

@@ -0,0 +1,14 @@
+import type { AlarmConfigDefaults } from "@composurecdk/cloudwatch";
+interface BucketAlarmDefaults {
+    enabled: true;
+    serverErrors: AlarmConfigDefaults;
+    clientErrors: AlarmConfigDefaults;
+}
+/**
+ * AWS-recommended default alarm configuration for S3 buckets.
+ *
+ * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#S3
+ */
+export declare const BUCKET_ALARM_DEFAULTS: BucketAlarmDefaults;
+export {};
+//# sourceMappingURL=alarm-defaults.d.ts.map

package/dist/esm/alarm-defaults.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"alarm-defaults.d.ts","sourceRoot":"","sources":["../../src/alarm-defaults.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAEpE,UAAU,mBAAmB;IAC3B,OAAO,EAAE,IAAI,CAAC;IACd,YAAY,EAAE,mBAAmB,CAAC;IAClC,YAAY,EAAE,mBAAmB,CAAC;CACnC;AAED;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,EAAE,mBAkBnC,CAAC"}

package/dist/esm/alarm-defaults.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"alarm-defaults.js","sourceRoot":"","sources":["../../src/alarm-defaults.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAS9D;;;;GAIG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAwB;IACxD,OAAO,EAAE,IAAI;IAEb,iEAAiE;IACjE,YAAY,EAAE;QACZ,SAAS,EAAE,CAAC;QACZ,iBAAiB,EAAE,CAAC;QACpB,iBAAiB,EAAE,CAAC;QACpB,gBAAgB,EAAE,gBAAgB,CAAC,aAAa;KACjD;IAED,yEAAyE;IACzE,YAAY,EAAE;QACZ,SAAS,EAAE,CAAC;QACZ,iBAAiB,EAAE,CAAC;QACpB,iBAAiB,EAAE,CAAC;QACpB,gBAAgB,EAAE,gBAAgB,CAAC,aAAa;KACjD;CACF,CAAC"}

package/dist/esm/bucket-alarms.d.ts

@@ -0,0 +1,34 @@
+import { type Alarm } from "aws-cdk-lib/aws-cloudwatch";
+import type { Bucket, BucketMetrics } from "aws-cdk-lib/aws-s3";
+import type { IConstruct } from "constructs";
+import { AlarmDefinitionBuilder } from "@composurecdk/cloudwatch";
+import type { AlarmDefinition } from "@composurecdk/cloudwatch";
+import type { BucketAlarmConfig } from "./alarm-config.js";
+/**
+ * Resolves the recommended alarm configuration into fully-resolved
+ * {@link AlarmDefinition}s for an S3 bucket.
+ *
+ * Creates alarms for each entry in `metricsConfigs`, keyed as
+ * `{alarmType}:{filterId}` (e.g. `serverErrors:EntireBucket`).
+ */
+export declare function resolveBucketAlarmDefinitions(bucket: Bucket, config: BucketAlarmConfig | undefined, metricsConfigs: BucketMetrics[]): AlarmDefinition[];
+/**
+ * Creates AWS-recommended CloudWatch alarms for an S3 bucket,
+ * merging recommended definitions with any custom alarm builders.
+ *
+ * Alarms are created for each entry in `metricsConfigs` (from
+ * {@link BucketProps.metrics}). If no metrics configurations are
+ * provided, only custom alarms are created.
+ *
+ * @param scope - CDK construct scope for creating alarm constructs.
+ * @param id - Base identifier for alarm construct ids.
+ * @param bucket - The S3 bucket to create alarms for.
+ * @param config - User-provided alarm configuration, or `false` to disable all.
+ * @param metricsConfigs - The bucket's request metrics configurations.
+ * @param customAlarms - Custom alarm builders added via `addAlarm()`.
+ * @returns A record mapping alarm keys to their created Alarm constructs.
+ *
+ * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#S3
+ */
+export declare function createBucketAlarms(scope: IConstruct, id: string, bucket: Bucket, config: BucketAlarmConfig | false | undefined, metricsConfigs: BucketMetrics[], customAlarms?: AlarmDefinitionBuilder<Bucket>[]): Record<string, Alarm>;
+//# sourceMappingURL=bucket-alarms.d.ts.map

package/dist/esm/bucket-alarms.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bucket-alarms.d.ts","sourceRoot":"","sources":["../../src/bucket-alarms.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,KAAK,EAAqC,MAAM,4BAA4B,CAAC;AAC3F,OAAO,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAChE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EAAE,sBAAsB,EAAoC,MAAM,0BAA0B,CAAC;AACpG,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAChE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AA2B3D;;;;;;GAMG;AACH,wBAAgB,6BAA6B,CAC3C,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,iBAAiB,GAAG,SAAS,EACrC,cAAc,EAAE,aAAa,EAAE,GAC9B,eAAe,EAAE,CAyCnB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,UAAU,EACjB,EAAE,EAAE,MAAM,EACV,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,iBAAiB,GAAG,KAAK,GAAG,SAAS,EAC7C,cAAc,EAAE,aAAa,EAAE,EAC/B,YAAY,GAAE,sBAAsB,CAAC,MAAM,CAAC,EAAO,GAClD,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAUvB"}

package/dist/esm/bucket-alarms.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bucket-alarms.js","sourceRoot":"","sources":["../../src/bucket-alarms.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,OAAO,EAAc,kBAAkB,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,4BAA4B,CAAC;AAG3F,OAAO,EAA0B,YAAY,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAGpG,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAE5D,MAAM,aAAa,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;AAC1C,MAAM,mBAAmB,GAAG,GAAG,MAAM,CAAC,aAAa,CAAC,SAAS,EAAE,CAAC,UAAU,CAAC;AAE3E;;GAEG;AACH,SAAS,eAAe,CACtB,MAAc,EACd,QAAgB,EAChB,UAAkB,EAClB,SAAiB;IAEjB,OAAO,IAAI,MAAM,CAAC;QAChB,SAAS,EAAE,QAAQ;QACnB,UAAU;QACV,aAAa,EAAE;YACb,UAAU,EAAE,MAAM,CAAC,UAAU;YAC7B,QAAQ,EAAE,QAAQ;SACnB;QACD,SAAS;QACT,MAAM,EAAE,aAAa;KACtB,CAAC,CAAC;AACL,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,6BAA6B,CAC3C,MAAc,EACd,MAAqC,EACrC,cAA+B;IAE/B,IAAI,MAAM,EAAE,OAAO,KAAK,KAAK;QAAE,OAAO,EAAE,CAAC;IACzC,IAAI,cAAc,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAE3C,MAAM,WAAW,GAAsB,EAAE,CAAC;IAE1C,KAAK,MAAM,OAAO,IAAI,cAAc,EAAE,CAAC;QACrC,MAAM,QAAQ,GAAG,OAAO,CAAC,EAAE,CAAC;QAE5B,IAAI,MAAM,EAAE,YAAY,KAAK,KAAK,EAAE,CAAC;YACnC,MAAM,GAAG,GAAG,kBAAkB,CAAC,MAAM,EAAE,YAAY,EAAE,qBAAqB,CAAC,YAAY,CAAC,CAAC;YACzF,WAAW,CAAC,IAAI,CAAC;gBACf,GAAG,EAAE,gBAAgB,QAAQ,EAAE;gBAC/B,SAAS,EAAE,GAAG,CAAC,SAAS;gBACxB,MAAM,EAAE,eAAe,CAAC,MAAM,EAAE,QAAQ,EAAE,WAAW,EAAE,KAAK,CAAC,GAAG,CAAC;gBACjE,SAAS,EAAE,GAAG,CAAC,SAAS;gBACxB,kBAAkB,EAAE,kBAAkB,CAAC,sBAAsB;gBAC7D,iBAAiB,EAAE,GAAG,CAAC,iBAAiB;gBACxC,iBAAiB,EAAE,GAAG,CAAC,iBAAiB;gBACxC,gBAAgB,EAAE,GAAG,CAAC,gBAAgB;gBACtC,WAAW,EAAE,sDAAsD,QAAQ,mBAAmB,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,kBAAkB,mBAAmB,GAAG;aAC5J,CAAC,CAAC;QACL,CAAC;QAED,IAAI,MAAM,EAAE,YAAY,KAAK,KAAK,EAAE,CAAC;YACnC,MAAM,GAAG,GAAG,kBAAkB,CAAC,MAAM,EAAE,YAAY,EAAE,qBAAqB,CAAC,YAAY,CAAC,CAAC;YACzF,WAAW,CAAC,IAAI,CAAC;gBACf,GAAG,EAAE,gBAAgB,QAAQ,EAAE;gBAC/B,SAAS,EAAE,GAAG,CAAC,SAAS;gBACxB,MAAM,EAAE,eAAe,CAAC,MAAM,EAAE,QAAQ,EAAE,WAAW,EAAE,KAAK,CAAC,GAAG,CAAC;gBACjE,SAAS,EAAE,GAAG,CAAC,SAAS;gBACxB,kBAAkB,EAAE,kBAAkB,CAAC,sBAAsB;gBAC7D,iBAAiB,EAAE,GAAG,CAAC,iBAAiB;gBACxC,iBAAiB,EAAE,GAAG,CAAC,iBAAiB;gBACxC,gBAAgB,EAAE,GAAG,CAAC,gBAAgB;gBACtC,WAAW,EAAE,sDAAsD,QAAQ,mBAAmB,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,kBAAkB,mBAAmB,GAAG;aAC5J,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,OAAO,WAAW,CAAC;AACrB,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,kBAAkB,CAChC,KAAiB,EACjB,EAAU,EACV,MAAc,EACd,MAA6C,EAC7C,cAA+B,EAC/B,eAAiD,EAAE;IAEnD,IAAI,MAAM,KAAK,KAAK;QAAE,OAAO,EAAE,CAAC;IAEhC,MAAM,OAAO,GAAG,MAAM,EAAE,OAAO,IAAI,qBAAqB,CAAC,OAAO,CAAC;IACjE,IAAI,CAAC,OAAO;QAAE,OAAO,EAAE,CAAC;IAExB,MAAM,WAAW,GAAG,6BAA6B,CAAC,MAAM,EAAE,MAAM,EAAE,cAAc,CAAC,CAAC;IAClF,MAAM,MAAM,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;IAE1D,OAAO,YAAY,CAAC,KAAK,EAAE,EAAE,EAAE,CAAC,GAAG,WAAW,EAAE,GAAG,MAAM,CAAC,CAAC,CAAC;AAC9D,CAAC"}

package/dist/esm/bucket-builder.d.ts

@@ -0,0 +1,130 @@
+import { type Alarm } from "aws-cdk-lib/aws-cloudwatch";
+import { Bucket, type BucketProps, type IBucket } from "aws-cdk-lib/aws-s3";
+import { type IConstruct } from "constructs";
+import { COPY_STATE, type Lifecycle } from "@composurecdk/core";
+import { type ITaggedBuilder } from "@composurecdk/cloudformation";
+import { AlarmDefinitionBuilder } from "@composurecdk/cloudwatch";
+import type { BucketAlarmConfig } from "./alarm-config.js";
+/**
+ * Configures how server access logs are handled. Pass `false` to disable
+ * logging; pass an object to wire a destination, prefix, or customize the
+ * auto-created sub-builder.
+ *
+ * `configure` cannot be combined with `destination` — a user-managed
+ * destination is not built by this builder.
+ */
+export type ServerAccessLogsConfig = false | {
+    destination?: IBucket;
+    prefix?: string;
+    /**
+     * Customize the auto-created logging sub-builder. Receives a builder
+     * pre-seeded with `versioned: false`, `removalPolicy: RETAIN`, and
+     * recursive access logging disabled.
+     */
+    configure?: (b: IBucketBuilder) => IBucketBuilder;
+};
+/**
+ * Configuration properties for the S3 bucket builder. Extends CDK
+ * {@link BucketProps} with builder-specific options.
+ */
+export interface BucketBuilderProps extends Omit<BucketProps, "serverAccessLogsBucket" | "serverAccessLogsPrefix"> {
+    /** See {@link ServerAccessLogsConfig}. Defaults to `{ prefix: "logs/" }`. */
+    serverAccessLogs?: ServerAccessLogsConfig;
+    /**
+     * Configuration for AWS-recommended CloudWatch alarms.
+     *
+     * S3 request metric alarms (5xxErrors, 4xxErrors) require
+     * [CloudWatch request metrics](https://docs.aws.amazon.com/AmazonS3/latest/userguide/configure-request-metrics-bucket.html)
+     * to be enabled on the bucket. Set {@link BucketAlarmConfig.requestMetricsFilterId}
+     * to the ID of the request metrics configuration to create these alarms.
+     *
+     * No alarm actions are configured by default since notification
+     * methods are user-specific. Access alarms from the build result
+     * or use an `afterBuild` hook to apply actions.
+     *
+     * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#S3
+     */
+    recommendedAlarms?: BucketAlarmConfig | false;
+}
+/**
+ * The build output of a {@link IBucketBuilder}. Contains the CDK constructs
+ * created during {@link Lifecycle.build}, keyed by role.
+ */
+export interface BucketBuilderResult {
+    /** The S3 bucket construct created by the builder. */
+    bucket: Bucket;
+    /**
+     * The S3 bucket created for access logging, or `undefined` if access
+     * logging was disabled or the user provided their own destination.
+     */
+    accessLogsBucket?: Bucket;
+    /**
+     * CloudWatch alarms created for the bucket, keyed by alarm name.
+     *
+     * Includes both AWS-recommended alarms and any custom alarms added
+     * via {@link IBucketBuilder.addAlarm}. Access individual alarms
+     * by key (e.g., `result.alarms.serverErrors`).
+     *
+     * No alarm actions are configured — apply them via the result or an
+     * `afterBuild` hook.
+     *
+     * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#S3
+     */
+    alarms: Record<string, Alarm>;
+}
+/**
+ * A fluent builder for configuring and creating an Amazon S3 bucket.
+ *
+ * Each configuration property from the CDK {@link BucketProps} is exposed
+ * as an overloaded method: call with a value to set it (returns the builder
+ * for chaining), or call with no arguments to read the current value.
+ *
+ * The builder implements {@link Lifecycle}, so it can be used directly as a
+ * component in a {@link compose | composed system}. When built, it creates
+ * an S3 bucket with the configured properties and returns a
+ * {@link BucketBuilderResult}.
+ *
+ * @example
+ * ```ts
+ * const site = createBucketBuilder()
+ *   .bucketName("my-website-bucket")
+ *   .versioned(false);
+ * ```
+ */
+export type IBucketBuilder = ITaggedBuilder<BucketBuilderProps, BucketBuilder>;
+declare class BucketBuilder implements Lifecycle<BucketBuilderResult> {
+    #private;
+    props: Partial<BucketBuilderProps>;
+    addAlarm(key: string, configure: (alarm: AlarmDefinitionBuilder<Bucket>) => AlarmDefinitionBuilder<Bucket>): this;
+    /** @internal — see ADR-0005. */
+    [COPY_STATE](target: BucketBuilder): void;
+    build(scope: IConstruct, id: string): BucketBuilderResult;
+}
+/**
+ * Creates a new {@link IBucketBuilder} for configuring an Amazon S3 bucket.
+ *
+ * This is the entry point for defining an S3 bucket component. The returned
+ * builder exposes every {@link BucketProps} property as a fluent setter/getter
+ * and implements {@link Lifecycle} for use with {@link compose}.
+ *
+ * @returns A fluent builder for an Amazon S3 bucket.
+ *
+ * @example
+ * ```ts
+ * const site = createBucketBuilder()
+ *   .bucketName("my-site")
+ *   .versioned(false);
+ *
+ * // Use standalone:
+ * const result = site.build(stack, "SiteBucket");
+ *
+ * // Or compose into a system:
+ * const system = compose(
+ *   { site, cdn: createDistributionBuilder() },
+ *   { site: [], cdn: ["site"] },
+ * );
+ * ```
+ */
+export declare function createBucketBuilder(): IBucketBuilder;
+export {};
+//# sourceMappingURL=bucket-builder.d.ts.map

package/dist/esm/bucket-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bucket-builder.d.ts","sourceRoot":"","sources":["../../src/bucket-builder.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,KAAK,EAAE,MAAM,4BAA4B,CAAC;AACxD,OAAO,EAAE,MAAM,EAAE,KAAK,WAAW,EAAE,KAAK,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAC5E,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EAAE,UAAU,EAAE,KAAK,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAChE,OAAO,EAAE,KAAK,cAAc,EAAiB,MAAM,8BAA8B,CAAC;AAClF,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAI3D;;;;;;;GAOG;AACH,MAAM,MAAM,sBAAsB,GAC9B,KAAK,GACL;IACE,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,SAAS,CAAC,EAAE,CAAC,CAAC,EAAE,cAAc,KAAK,cAAc,CAAC;CACnD,CAAC;AAEN;;;GAGG;AACH,MAAM,WAAW,kBAAmB,SAAQ,IAAI,CAC9C,WAAW,EACX,wBAAwB,GAAG,wBAAwB,CACpD;IACC,6EAA6E;IAC7E,gBAAgB,CAAC,EAAE,sBAAsB,CAAC;IAE1C;;;;;;;;;;;;;OAaG;IACH,iBAAiB,CAAC,EAAE,iBAAiB,GAAG,KAAK,CAAC;CAC/C;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,sDAAsD;IACtD,MAAM,EAAE,MAAM,CAAC;IAEf;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B;;;;;;;;;;;OAWG;IACH,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;CAC/B;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,MAAM,cAAc,GAAG,cAAc,CAAC,kBAAkB,EAAE,aAAa,CAAC,CAAC;AAE/E,cAAM,aAAc,YAAW,SAAS,CAAC,mBAAmB,CAAC;;IAC3D,KAAK,EAAE,OAAO,CAAC,kBAAkB,CAAC,CAAM;IAGxC,QAAQ,CACN,GAAG,EAAE,MAAM,EACX,SAAS,EAAE,CAAC,KAAK,EAAE,sBAAsB,CAAC,MAAM,CAAC,KAAK,sBAAsB,CAAC,MAAM,CAAC,GACnF,IAAI;IAKP,gCAAgC;IAChC,CAAC,UAAU,CAAC,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI;IAIzC,KAAK,CAAC,KAAK,EAAE,UAAU,EAAE,EAAE,EAAE,MAAM,GAAG,mBAAmB;CA+B1D;AAgED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,mBAAmB,IAAI,cAAc,CAEpD"}

package/dist/{bucket-builder.js → esm/bucket-builder.js}

@@ -1,6 +1,7 @@
 import { RemovalPolicy } from "aws-cdk-lib";
 import { Bucket } from "aws-cdk-lib/aws-s3";
-import { Builder } from "@composurecdk/core";
+import { COPY_STATE } from "@composurecdk/core";
+import { taggedBuilder } from "@composurecdk/cloudformation";
 import { AlarmDefinitionBuilder } from "@composurecdk/cloudwatch";
 import { createBucketAlarms } from "./bucket-alarms.js";
 import { DEFAULT_ACCESS_LOG_BUCKET_LIFECYCLE_RULES, BUCKET_DEFAULTS } from "./defaults.js";
@@ -11,6 +12,10 @@ class BucketBuilder {
         this.#customAlarms.push(configure(new AlarmDefinitionBuilder(key)));
         return this;
     }
+    /** @internal — see ADR-0005. */
+    [COPY_STATE](target) {
+        target.#customAlarms.push(...this.#customAlarms);
+    }
     build(scope, id) {
         const { serverAccessLogs, recommendedAlarms: alarmConfig, ...bucketProps } = this.props;
         const { serverAccessLogs: defaultServerAccessLogs, ...cdkDefaults } = BUCKET_DEFAULTS;
@@ -105,6 +110,6 @@ function autoDeleteProps(userProps, defaults) {
  * ```
  */
 export function createBucketBuilder() {
-    return Builder(BucketBuilder);
+    return taggedBuilder(BucketBuilder);
 }
 //# sourceMappingURL=bucket-builder.js.map

package/dist/esm/bucket-builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bucket-builder.js","sourceRoot":"","sources":["../../src/bucket-builder.ts"],"names":[],"mappings":"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"}

package/dist/esm/bucket-deployment-builder.d.ts

@@ -0,0 +1,113 @@
+import { BucketDeployment } from "aws-cdk-lib/aws-s3-deployment";
+import { type IBucket } from "aws-cdk-lib/aws-s3";
+import { type IDistribution } from "aws-cdk-lib/aws-cloudfront";
+import type { LogGroup } from "aws-cdk-lib/aws-logs";
+import { type IConstruct } from "constructs";
+import { COPY_STATE, type Lifecycle, type Resolvable } from "@composurecdk/core";
+import { type ITaggedBuilder } from "@composurecdk/cloudformation";
+import { type BucketDeploymentBuilderProps } from "./bucket-deployment-props.js";
+/**
+ * The build output of a {@link IBucketDeploymentBuilder}.
+ */
+export interface BucketDeploymentBuilderResult {
+    /** The CDK BucketDeployment construct created by the builder. */
+    deployment: BucketDeployment;
+    /**
+     * The CloudWatch LogGroup created for the deployment's backing Lambda,
+     * or `undefined` if the user provided their own via the `logGroup`
+     * property.
+     *
+     * By default the builder creates a managed LogGroup using
+     * {@link createLogGroupBuilder} with well-architected defaults (retention
+     * policy, removal policy). This prevents the backing Lambda from
+     * creating an auto-managed log group with infinite retention.
+     *
+     * @see https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3_deployment.BucketDeploymentProps.html#loggroup
+     */
+    logGroup?: LogGroup;
+}
+/**
+ * A fluent builder for configuring and creating an S3 BucketDeployment.
+ *
+ * Each configuration property from the CDK {@link BucketDeploymentProps} is
+ * exposed as an overloaded method: call with a value to set it (returns the
+ * builder for chaining), or call with no arguments to read the current value.
+ *
+ * The `destinationBucket` and `distribution` are set via dedicated methods
+ * that accept {@link Resolvable} values for cross-component wiring.
+ *
+ * The builder implements {@link Lifecycle}, so it can be used directly as a
+ * component in a {@link compose | composed system}.
+ *
+ * @example
+ * ```ts
+ * const deploy = createBucketDeploymentBuilder()
+ *   .sources([Source.asset("./site")])
+ *   .destinationBucket(ref("site", (r: BucketBuilderResult) => r.bucket))
+ *   .distribution(ref("cdn", (r: DistributionBuilderResult) => r.distribution))
+ *   .distributionPaths(["/*"]);
+ * ```
+ */
+export type IBucketDeploymentBuilder = ITaggedBuilder<BucketDeploymentBuilderProps, BucketDeploymentBuilder>;
+declare class BucketDeploymentBuilder implements Lifecycle<BucketDeploymentBuilderResult> {
+    #private;
+    props: Partial<BucketDeploymentBuilderProps>;
+    /**
+     * Sets the destination bucket for the deployment.
+     *
+     * Accepts a concrete {@link IBucket} or a {@link Ref} that resolves to one
+     * at build time.
+     *
+     * @param bucket - The bucket or a Ref to one.
+     * @returns This builder for chaining.
+     */
+    destinationBucket(bucket: Resolvable<IBucket>): this;
+    /**
+     * Sets the CloudFront distribution to invalidate on deployment.
+     *
+     * Accepts a concrete {@link IDistribution} or a {@link Ref} that resolves
+     * to one at build time. This is optional — deployments can target a bucket
+     * without CloudFront invalidation.
+     *
+     * @param distribution - The distribution or a Ref to one.
+     * @returns This builder for chaining.
+     */
+    distribution(distribution: Resolvable<IDistribution>): this;
+    /** @internal — see ADR-0005. */
+    [COPY_STATE](target: BucketDeploymentBuilder): void;
+    build(scope: IConstruct, id: string, context?: Record<string, object>): BucketDeploymentBuilderResult;
+}
+/**
+ * Creates a new {@link IBucketDeploymentBuilder} for deploying content to an
+ * S3 bucket with optional CloudFront cache invalidation.
+ *
+ * This is the entry point for defining an S3 deployment component. The
+ * returned builder exposes {@link BucketDeploymentBuilderProps} properties as
+ * fluent setters/getters, plus {@link IBucketDeploymentBuilder.destinationBucket | destinationBucket()}
+ * and {@link IBucketDeploymentBuilder.distribution | distribution()} for
+ * cross-component wiring with Ref support. It implements {@link Lifecycle}
+ * for use with {@link compose}.
+ *
+ * @returns A fluent builder for an S3 BucketDeployment.
+ *
+ * @example
+ * ```ts
+ * const deploy = createBucketDeploymentBuilder()
+ *   .sources([Source.asset("./site")])
+ *   .destinationBucket(ref("site", (r: BucketBuilderResult) => r.bucket))
+ *   .distribution(ref("cdn", (r: DistributionBuilderResult) => r.distribution))
+ *   .distributionPaths(["/*"]);
+ *
+ * // Use standalone:
+ * const result = deploy.build(stack, "Deploy");
+ *
+ * // Or compose into a system:
+ * const system = compose(
+ *   { site: createBucketBuilder(), cdn: createDistributionBuilder(), deploy },
+ *   { site: [], cdn: ["site"], deploy: ["site", "cdn"] },
+ * );
+ * ```
+ */
+export declare function createBucketDeploymentBuilder(): IBucketDeploymentBuilder;
+export {};
+//# sourceMappingURL=bucket-deployment-builder.d.ts.map

package/dist/esm/bucket-deployment-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bucket-deployment-builder.d.ts","sourceRoot":"","sources":["../../src/bucket-deployment-builder.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAA8B,MAAM,+BAA+B,CAAC;AAC7F,OAAO,EAAE,KAAK,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,KAAK,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAChE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EAAE,UAAU,EAAE,KAAK,SAAS,EAAW,KAAK,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAC1F,OAAO,EAAE,KAAK,cAAc,EAAiB,MAAM,8BAA8B,CAAC;AAGlF,OAAO,EAAE,KAAK,4BAA4B,EAAE,MAAM,8BAA8B,CAAC;AAEjF;;GAEG;AACH,MAAM,WAAW,6BAA6B;IAC5C,iEAAiE;IACjE,UAAU,EAAE,gBAAgB,CAAC;IAE7B;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,EAAE,QAAQ,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,MAAM,wBAAwB,GAAG,cAAc,CACnD,4BAA4B,EAC5B,uBAAuB,CACxB,CAAC;AAEF,cAAM,uBAAwB,YAAW,SAAS,CAAC,6BAA6B,CAAC;;IAC/E,KAAK,EAAE,OAAO,CAAC,4BAA4B,CAAC,CAAM;IAIlD;;;;;;;;OAQG;IACH,iBAAiB,CAAC,MAAM,EAAE,UAAU,CAAC,OAAO,CAAC,GAAG,IAAI;IAKpD;;;;;;;;;OASG;IACH,YAAY,CAAC,YAAY,EAAE,UAAU,CAAC,aAAa,CAAC,GAAG,IAAI;IAK3D,gCAAgC;IAChC,CAAC,UAAU,CAAC,CAAC,MAAM,EAAE,uBAAuB,GAAG,IAAI;IAKnD,KAAK,CACH,KAAK,EAAE,UAAU,EACjB,EAAE,EAAE,MAAM,EACV,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC/B,6BAA6B;CAiDjC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,6BAA6B,IAAI,wBAAwB,CAIxE"}

package/dist/{bucket-deployment-builder.js → esm/bucket-deployment-builder.js}

@@ -1,5 +1,6 @@
 import { BucketDeployment } from "aws-cdk-lib/aws-s3-deployment";
-import { Builder, resolve, } from "@composurecdk/core";
+import { COPY_STATE, resolve } from "@composurecdk/core";
+import { taggedBuilder } from "@composurecdk/cloudformation";
 import { createLogGroupBuilder } from "@composurecdk/logs";
 import { effectiveDefaults } from "./bucket-deployment-defaults.js";
 class BucketDeploymentBuilder {
@@ -33,6 +34,11 @@ class BucketDeploymentBuilder {
         this.#distribution = distribution;
         return this;
     }
+    /** @internal — see ADR-0005. */
+    [COPY_STATE](target) {
+        target.#destinationBucket = this.#destinationBucket;
+        target.#distribution = this.#distribution;
+    }
     build(scope, id, context) {
         const ctx = context ?? {};
         const resolvedBucket = this.#destinationBucket
@@ -102,6 +108,6 @@ class BucketDeploymentBuilder {
  * ```
  */
 export function createBucketDeploymentBuilder() {
-    return Builder(BucketDeploymentBuilder);
+    return taggedBuilder(BucketDeploymentBuilder);
 }
 //# sourceMappingURL=bucket-deployment-builder.js.map

package/dist/esm/bucket-deployment-builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bucket-deployment-builder.js","sourceRoot":"","sources":["../../src/bucket-deployment-builder.ts"],"names":[],"mappings":"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"}