@composurecdk/s3 0.1.2 → 0.3.0

package/README.md

@@ -0,0 +1,226 @@
+# @composurecdk/s3
+
+S3 builders for [ComposureCDK](../../README.md).
+
+This package provides fluent builders for S3 buckets and bucket deployments with secure, AWS-recommended defaults. It wraps the CDK [Bucket](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3.Bucket.html) and [BucketDeployment](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3_deployment.BucketDeployment.html) constructs — refer to the CDK documentation for the full set of configurable properties.
+
+## Bucket Builder
+
+```ts
+import { createBucketBuilder } from "@composurecdk/s3";
+
+const site = createBucketBuilder().bucketName("my-website-bucket").build(stack, "SiteBucket");
+```
+
+Every [BucketProps](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3.BucketProps.html) property is available as a fluent setter on the builder.
+
+### Secure Defaults
+
+`createBucketBuilder` applies the following defaults. Each can be overridden via the builder's fluent API.
+
+| Property            | Default      | Rationale                                                        |
+| ------------------- | ------------ | ---------------------------------------------------------------- |
+| `accessLogging`     | `true`       | Auto-creates a logging bucket for server access log audit trail. |
+| `accessLogsPrefix`  | `"logs/"`    | Default prefix for access log object keys.                       |
+| `blockPublicAccess` | `BLOCK_ALL`  | Prevents public access unless explicitly required.               |
+| `encryption`        | `S3_MANAGED` | Enables server-side encryption with S3-managed keys (SSE-S3).    |
+| `enforceSSL`        | `true`       | Requires SSL/TLS for all requests to the bucket.                 |
+| `versioned`         | `true`       | Protects against accidental deletions and supports rollback.     |
+| `removalPolicy`     | `RETAIN`     | Retains the bucket on stack deletion to prevent data loss.       |
+
+These defaults are guided by the [AWS Well-Architected Security Pillar](https://docs.aws.amazon.com/wellarchitected/latest/security-pillar/protecting-data-at-rest.html).
+
+The defaults are exported as `BUCKET_DEFAULTS` for visibility and testing:
+
+```ts
+import { BUCKET_DEFAULTS } from "@composurecdk/s3";
+```
+
+### Overriding defaults
+
+```ts
+import { RemovalPolicy } from "aws-cdk-lib";
+import { BlockPublicAccess } from "aws-cdk-lib/aws-s3";
+
+const bucket = createBucketBuilder()
+  .blockPublicAccess(BlockPublicAccess.BLOCK_ACLS)
+  .versioned(false)
+  .removalPolicy(RemovalPolicy.DESTROY)
+  .build(stack, "MyBucket");
+```
+
+When `removalPolicy` is set to `DESTROY`, the builder automatically enables `autoDeleteObjects` (unless explicitly set to `false`) so that non-empty buckets can be cleanly removed during stack deletion.
+
+### Access logging
+
+By default, the builder creates a dedicated logging bucket with secure defaults and configures it as the server access logs destination. The created bucket is returned in the build result:
+
+```ts
+const result = createBucketBuilder().build(stack, "MyBucket");
+
+result.bucket; // Bucket
+result.accessLogsBucket; // Bucket | undefined
+```
+
+To provide your own destination instead, set `serverAccessLogsBucket` — the auto-created logging bucket is skipped. To disable access logging entirely, set `.accessLogging(false)`.
+
+## Recommended Alarms
+
+The builder creates [AWS-recommended CloudWatch alarms](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#S3) automatically when [CloudWatch request metrics](https://docs.aws.amazon.com/AmazonS3/latest/userguide/configure-request-metrics-bucket.html) are configured on the bucket via `.metrics()`. One alarm per metric is created for each metrics configuration entry. No alarm actions are configured — access alarms from the build result to add SNS topics or other actions.
+
+| Alarm          | Metric                 | Default threshold | Created when               |
+| -------------- | ---------------------- | ----------------- | -------------------------- |
+| `serverErrors` | 5xxErrors (Sum, 5 min) | > 0               | `.metrics()` is configured |
+| `clientErrors` | 4xxErrors (Sum, 5 min) | > 0               | `.metrics()` is configured |
+
+Alarm keys include the metrics filter ID (e.g. `serverErrors:EntireBucket`). When multiple metrics configurations are provided, alarms are created for each one.
+
+The defaults are exported as `BUCKET_ALARM_DEFAULTS` for visibility and testing:
+
+```ts
+import { BUCKET_ALARM_DEFAULTS } from "@composurecdk/s3";
+```
+
+### Enabling alarms
+
+Configure request metrics on the bucket — alarms are created automatically:
+
+```ts
+const site = createBucketBuilder().metrics([{ id: "EntireBucket" }]);
+```
+
+### Multiple metrics configurations
+
+Alarms are created for each metrics configuration entry:
+
+```ts
+const site = createBucketBuilder().metrics([
+  { id: "EntireBucket" },
+  { id: "UploadsOnly", prefix: "uploads/" },
+]);
+
+// Creates: serverErrors:EntireBucket, clientErrors:EntireBucket,
+//          serverErrors:UploadsOnly, clientErrors:UploadsOnly
+```
+
+### Customizing thresholds
+
+Override individual alarm properties via `recommendedAlarms`. Unspecified fields keep their defaults.
+
+```ts
+builder.metrics([{ id: "EntireBucket" }]).recommendedAlarms({
+  serverErrors: { threshold: 5, evaluationPeriods: 3 },
+  clientErrors: { threshold: 50 },
+});
+```
+
+### Disabling alarms
+
+Disable all recommended alarms:
+
+```ts
+builder.recommendedAlarms(false);
+// or
+builder.recommendedAlarms({ enabled: false });
+```
+
+Disable individual alarms:
+
+```ts
+builder.metrics([{ id: "EntireBucket" }]).recommendedAlarms({ clientErrors: false });
+```
+
+### Custom alarms
+
+Add custom alarms alongside the recommended ones via `addAlarm`. The callback receives an `AlarmDefinitionBuilder` typed to the S3 `Bucket`, so the metric factory has access to the bucket's metric helpers.
+
+```ts
+import { Metric } from "aws-cdk-lib/aws-cloudwatch";
+
+const site = createBucketBuilder()
+  .metrics([{ id: "EntireBucket" }])
+  .addAlarm("lowTraffic", (alarm) =>
+    alarm
+      .metric(
+        (bucket) =>
+          new Metric({
+            namespace: "AWS/S3",
+            metricName: "GetRequests",
+            dimensionsMap: {
+              BucketName: bucket.bucketName,
+              FilterId: "EntireBucket",
+            },
+            period: Duration.minutes(5),
+          }),
+      )
+      .threshold(10)
+      .lessThan()
+      .description("Bucket traffic has dropped below expected level"),
+  );
+```
+
+### Applying alarm actions
+
+Alarms are returned in the build result as `Record<string, Alarm>`:
+
+```ts
+const result = site.build(stack, "SiteBucket");
+
+const alertTopic = new Topic(stack, "AlertTopic");
+for (const alarm of Object.values(result.alarms)) {
+  alarm.addAlarmAction(new SnsAction(alertTopic));
+}
+```
+
+## Bucket Deployment Builder
+
+Deploys local assets to an S3 bucket with optional CloudFront cache invalidation.
+
+```ts
+import { createBucketDeploymentBuilder } from "@composurecdk/s3";
+import { Source } from "aws-cdk-lib/aws-s3-deployment";
+
+const deploy = createBucketDeploymentBuilder()
+  .sources([Source.asset("./site")])
+  .destinationBucket(myBucket)
+  .build(stack, "Deploy");
+```
+
+The `destinationBucket` and `distribution` methods accept `Ref` values for cross-component wiring:
+
+```ts
+import { compose, ref } from "@composurecdk/core";
+
+const deploy = createBucketDeploymentBuilder()
+  .sources([Source.asset("./site")])
+  .destinationBucket(ref("site", (r) => r.bucket))
+  .distribution(ref("cdn", (r) => r.distribution));
+
+compose(
+  { site: createBucketBuilder(), cdn: createDistributionBuilder(), deploy },
+  { site: [], cdn: ["site"], deploy: ["site", "cdn"] },
+).build(stack, "Website");
+```
+
+### Secure Defaults
+
+`createBucketDeploymentBuilder` applies the following defaults. Each can be overridden via the builder's fluent API.
+
+| Property            | Default  | Rationale                                                                                                           |
+| ------------------- | -------- | ------------------------------------------------------------------------------------------------------------------- |
+| `prune`             | `true`   | Removes stale files from the destination, keeping it in sync with the source.                                       |
+| `memoryLimit`       | `256`    | Allocates 256 MiB to the deployment Lambda (CDK default of 128 MiB is insufficient for larger deployments).         |
+| `retainOnDelete`    | `false`  | Does not retain deployed files on stack deletion, consistent with prune semantics.                                  |
+| `distributionPaths` | `["/*"]` | Invalidates all CloudFront paths so content is immediately visible. Only applied when a distribution is configured. |
+
+The builder also auto-creates a managed CloudWatch LogGroup (using `@composurecdk/logs` with its secure defaults) for the deployment's backing Lambda, preventing the auto-created log group with infinite retention.
+
+The defaults are exported as `BUCKET_DEPLOYMENT_DEFAULTS` for visibility and testing:
+
+```ts
+import { BUCKET_DEPLOYMENT_DEFAULTS } from "@composurecdk/s3";
+```
+
+## Examples
+
+- [StaticWebsiteStack](../examples/src/static-website/app.ts) — S3 + CloudFront static website with OAC, error pages, and content deployment

package/dist/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/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/alarm-config.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=alarm-config.js.map

package/dist/alarm-config.js.map

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

package/dist/alarm-defaults.d.ts

@@ -0,0 +1,14 @@
+import type { AlarmConfig } from "@composurecdk/cloudwatch";
+interface BucketAlarmDefaults {
+    enabled: true;
+    serverErrors: Required<AlarmConfig>;
+    clientErrors: Required<AlarmConfig>;
+}
+/**
+ * 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/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,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAE5D,UAAU,mBAAmB;IAC3B,OAAO,EAAE,IAAI,CAAC;IACd,YAAY,EAAE,QAAQ,CAAC,WAAW,CAAC,CAAC;IACpC,YAAY,EAAE,QAAQ,CAAC,WAAW,CAAC,CAAC;CACrC;AAED;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,EAAE,mBAkBnC,CAAC"}

package/dist/alarm-defaults.js

@@ -0,0 +1,24 @@
+import { TreatMissingData } from "aws-cdk-lib/aws-cloudwatch";
+/**
+ * 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 const BUCKET_ALARM_DEFAULTS = {
+    enabled: true,
+    /** Any server-side error is worth investigating; threshold 0. */
+    serverErrors: {
+        threshold: 0,
+        evaluationPeriods: 1,
+        datapointsToAlarm: 1,
+        treatMissingData: TreatMissingData.NOT_BREACHING,
+    },
+    /** Any client-side error pattern is worth investigating; threshold 0. */
+    clientErrors: {
+        threshold: 0,
+        evaluationPeriods: 1,
+        datapointsToAlarm: 1,
+        treatMissingData: TreatMissingData.NOT_BREACHING,
+    },
+};
+//# sourceMappingURL=alarm-defaults.js.map

package/dist/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/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/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,CAuCnB;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/bucket-alarms.js

@@ -0,0 +1,94 @@
+import { Duration } from "aws-cdk-lib";
+import { ComparisonOperator, Metric, Stats } from "aws-cdk-lib/aws-cloudwatch";
+import { createAlarms, resolveAlarmConfig } from "@composurecdk/cloudwatch";
+import { BUCKET_ALARM_DEFAULTS } from "./alarm-defaults.js";
+const METRIC_PERIOD = Duration.minutes(5);
+const METRIC_PERIOD_LABEL = `${String(METRIC_PERIOD.toMinutes())} minutes`;
+/**
+ * Creates an S3 request metric with the correct namespace and dimensions.
+ */
+function s3RequestMetric(bucket, filterId, metricName, statistic) {
+    return new Metric({
+        namespace: "AWS/S3",
+        metricName,
+        dimensionsMap: {
+            BucketName: bucket.bucketName,
+            FilterId: filterId,
+        },
+        statistic,
+        period: METRIC_PERIOD,
+    });
+}
+/**
+ * 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 function resolveBucketAlarmDefinitions(bucket, config, metricsConfigs) {
+    if (config?.enabled === false)
+        return [];
+    if (metricsConfigs.length === 0)
+        return [];
+    const definitions = [];
+    for (const metrics of metricsConfigs) {
+        const filterId = metrics.id;
+        if (config?.serverErrors !== false) {
+            const cfg = resolveAlarmConfig(config?.serverErrors, BUCKET_ALARM_DEFAULTS.serverErrors);
+            definitions.push({
+                key: `serverErrors:${filterId}`,
+                metric: s3RequestMetric(bucket, filterId, "5xxErrors", Stats.SUM),
+                threshold: cfg.threshold,
+                comparisonOperator: ComparisonOperator.GREATER_THAN_THRESHOLD,
+                evaluationPeriods: cfg.evaluationPeriods,
+                datapointsToAlarm: cfg.datapointsToAlarm,
+                treatMissingData: cfg.treatMissingData,
+                description: `S3 bucket is returning server-side errors (filter: ${filterId}). Threshold: > ${String(cfg.threshold)} 5xx errors in ${METRIC_PERIOD_LABEL}.`,
+            });
+        }
+        if (config?.clientErrors !== false) {
+            const cfg = resolveAlarmConfig(config?.clientErrors, BUCKET_ALARM_DEFAULTS.clientErrors);
+            definitions.push({
+                key: `clientErrors:${filterId}`,
+                metric: s3RequestMetric(bucket, filterId, "4xxErrors", Stats.SUM),
+                threshold: cfg.threshold,
+                comparisonOperator: ComparisonOperator.GREATER_THAN_THRESHOLD,
+                evaluationPeriods: cfg.evaluationPeriods,
+                datapointsToAlarm: cfg.datapointsToAlarm,
+                treatMissingData: cfg.treatMissingData,
+                description: `S3 bucket is returning client-side errors (filter: ${filterId}). Threshold: > ${String(cfg.threshold)} 4xx errors in ${METRIC_PERIOD_LABEL}.`,
+            });
+        }
+    }
+    return definitions;
+}
+/**
+ * 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 function createBucketAlarms(scope, id, bucket, config, metricsConfigs, customAlarms = []) {
+    if (config === false)
+        return {};
+    const enabled = config?.enabled ?? BUCKET_ALARM_DEFAULTS.enabled;
+    if (!enabled)
+        return {};
+    const recommended = resolveBucketAlarmDefinitions(bucket, config, metricsConfigs);
+    const custom = customAlarms.map((b) => b.resolve(bucket));
+    return createAlarms(scope, id, [...recommended, ...custom]);
+}
+//# sourceMappingURL=bucket-alarms.js.map

package/dist/bucket-alarms.js.map

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

package/dist/bucket-builder.d.ts

@@ -1,6 +1,9 @@
+import { type Alarm } from "aws-cdk-lib/aws-cloudwatch";
 import { Bucket, type BucketProps } from "aws-cdk-lib/aws-s3";
 import { type IConstruct } from "constructs";
 import { type IBuilder, type Lifecycle } from "@composurecdk/core";
+import { AlarmDefinitionBuilder } from "@composurecdk/cloudwatch";
+import type { BucketAlarmConfig } from "./alarm-config.js";
 /**
  * Configuration properties for the S3 bucket builder.
  *
@@ -35,6 +38,21 @@ export interface BucketBuilderProps extends BucketProps {
      * @default "logs/"
      */
     accessLogsPrefix?: string;
+    /**
+     * 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
@@ -48,6 +66,19 @@ export interface BucketBuilderResult {
      * 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.
@@ -71,6 +102,8 @@ export interface BucketBuilderResult {
 export type IBucketBuilder = IBuilder<BucketBuilderProps, BucketBuilder>;
 declare class BucketBuilder implements Lifecycle<BucketBuilderResult> {
     props: Partial<BucketBuilderProps>;
+    private readonly customAlarms;
+    addAlarm(key: string, configure: (alarm: AlarmDefinitionBuilder<Bucket>) => AlarmDefinitionBuilder<Bucket>): this;
     build(scope: IConstruct, id: string): BucketBuilderResult;
 }
 /**

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

@@ -1 +1 @@
-{"version":3,"file":"bucket-builder.d.ts","sourceRoot":"","sources":["../src/bucket-builder.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAE,KAAK,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAC9D,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EAAW,KAAK,QAAQ,EAAE,KAAK,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAG5E;;;;GAIG;AACH,MAAM,WAAW,kBAAmB,SAAQ,WAAW;IACrD;;;;;;;;;;;;;;;;OAgBG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IAExB;;;;;;;;OAQG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,sDAAsD;IACtD,MAAM,EAAE,MAAM,CAAC;IAEf;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,MAAM,cAAc,GAAG,QAAQ,CAAC,kBAAkB,EAAE,aAAa,CAAC,CAAC;AAEzE,cAAM,aAAc,YAAW,SAAS,CAAC,mBAAmB,CAAC;IAC3D,KAAK,EAAE,OAAO,CAAC,kBAAkB,CAAC,CAAM;IAExC,KAAK,CAAC,KAAK,EAAE,UAAU,EAAE,EAAE,EAAE,MAAM,GAAG,mBAAmB;CA4C1D;AAqBD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,mBAAmB,IAAI,cAAc,CAEpD"}
+{"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,MAAM,oBAAoB,CAAC;AAC9D,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EAAW,KAAK,QAAQ,EAAE,KAAK,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAC5E,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAI3D;;;;GAIG;AACH,MAAM,WAAW,kBAAmB,SAAQ,WAAW;IACrD;;;;;;;;;;;;;;;;OAgBG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IAExB;;;;;;;;OAQG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B;;;;;;;;;;;;;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,QAAQ,CAAC,kBAAkB,EAAE,aAAa,CAAC,CAAC;AAEzE,cAAM,aAAc,YAAW,SAAS,CAAC,mBAAmB,CAAC;IAC3D,KAAK,EAAE,OAAO,CAAC,kBAAkB,CAAC,CAAM;IACxC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAwC;IAErE,QAAQ,CACN,GAAG,EAAE,MAAM,EACX,SAAS,EAAE,CAAC,KAAK,EAAE,sBAAsB,CAAC,MAAM,CAAC,KAAK,sBAAsB,CAAC,MAAM,CAAC,GACnF,IAAI;IAKP,KAAK,CAAC,KAAK,EAAE,UAAU,EAAE,EAAE,EAAE,MAAM,GAAG,mBAAmB;CA6D1D;AAqBD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,mBAAmB,IAAI,cAAc,CAEpD"}

package/dist/bucket-builder.js

@@ -1,11 +1,18 @@
 import { RemovalPolicy } from "aws-cdk-lib";
 import { Bucket } from "aws-cdk-lib/aws-s3";
 import { Builder } from "@composurecdk/core";
+import { AlarmDefinitionBuilder } from "@composurecdk/cloudwatch";
+import { createBucketAlarms } from "./bucket-alarms.js";
 import { BUCKET_DEFAULTS } from "./defaults.js";
 class BucketBuilder {
     props = {};
+    customAlarms = [];
+    addAlarm(key, configure) {
+        this.customAlarms.push(configure(new AlarmDefinitionBuilder(key)));
+        return this;
+    }
     build(scope, id) {
-        const { accessLogging, accessLogsPrefix, ...bucketProps } = this.props;
+        const { accessLogging, accessLogsPrefix, recommendedAlarms: alarmConfig, ...bucketProps } = this.props;
         const { accessLogging: defaultAccessLogging, accessLogsPrefix: defaultLogsPrefix, ...cdkDefaults } = BUCKET_DEFAULTS;
         const autoAccessLog = (accessLogging ?? defaultAccessLogging) && !bucketProps.serverAccessLogsBucket;
         if (accessLogsPrefix !== undefined && !autoAccessLog) {
@@ -31,9 +38,12 @@ class BucketBuilder {
             ...bucketProps,
             ...autoDeleteProps(bucketProps, BUCKET_DEFAULTS),
         };
+        const bucket = new Bucket(scope, id, mergedProps);
+        const alarms = createBucketAlarms(scope, id, bucket, alarmConfig, bucketProps.metrics ?? [], this.customAlarms);
         return {
-            bucket: new Bucket(scope, id, mergedProps),
+            bucket,
             accessLogsBucket,
+            alarms,
         };
     }
 }

package/dist/bucket-builder.js.map

@@ -1 +1 @@
-{"version":3,"file":"bucket-builder.js","sourceRoot":"","sources":["../src/bucket-builder.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,MAAM,EAAoB,MAAM,oBAAoB,CAAC;AAE9D,OAAO,EAAE,OAAO,EAAiC,MAAM,oBAAoB,CAAC;AAC5E,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AA2EhD,MAAM,aAAa;IACjB,KAAK,GAAgC,EAAE,CAAC;IAExC,KAAK,CAAC,KAAiB,EAAE,EAAU;QACjC,MAAM,EAAE,aAAa,EAAE,gBAAgB,EAAE,GAAG,WAAW,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC;QACvE,MAAM,EACJ,aAAa,EAAE,oBAAoB,EACnC,gBAAgB,EAAE,iBAAiB,EACnC,GAAG,WAAW,EACf,GAAG,eAAe,CAAC;QACpB,MAAM,aAAa,GACjB,CAAC,aAAa,IAAI,oBAAoB,CAAC,IAAI,CAAC,WAAW,CAAC,sBAAsB,CAAC;QAEjF,IAAI,gBAAgB,KAAK,SAAS,IAAI,CAAC,aAAa,EAAE,CAAC;YACrD,MAAM,IAAI,KAAK,CACb,mEAAmE;gBACjE,qEAAqE;gBACrE,8CAA8C,CACjD,CAAC;QACJ,CAAC;QAED,IAAI,gBAAoC,CAAC;QACzC,IAAI,cAAc,GAAG,EAAE,CAAC;QAExB,IAAI,aAAa,EAAE,CAAC;YAClB,gBAAgB,GAAG,mBAAmB,EAAE;iBACrC,aAAa,CAAC,KAAK,CAAC;iBACpB,aAAa,CAAC,aAAa,CAAC,MAAM,CAAC;iBACnC,KAAK,CAAC,KAAK,EAAE,GAAG,EAAE,YAAY,CAAC,CAAC,MAAM,CAAC;YAC1C,cAAc,GAAG;gBACf,sBAAsB,EAAE,gBAAgB;gBACxC,sBAAsB,EAAE,gBAAgB,IAAI,iBAAiB;aAC9D,CAAC;QACJ,CAAC;QAED,MAAM,WAAW,GAAG;YAClB,GAAG,WAAW;YACd,GAAG,cAAc;YACjB,GAAG,WAAW;YACd,GAAG,eAAe,CAAC,WAAW,EAAE,eAAe,CAAC;SAClC,CAAC;QAEjB,OAAO;YACL,MAAM,EAAE,IAAI,MAAM,CAAC,KAAK,EAAE,EAAE,EAAE,WAAW,CAAC;YAC1C,gBAAgB;SACjB,CAAC;IACJ,CAAC;CACF;AAED;;;;;;;GAOG;AACH,SAAS,eAAe,CACtB,SAA+B,EAC/B,QAAqC;IAErC,MAAM,eAAe,GAAG,SAAS,CAAC,aAAa,IAAI,QAAQ,CAAC,aAAa,CAAC;IAC1E,IAAI,eAAe,KAAK,aAAa,CAAC,OAAO,IAAI,SAAS,CAAC,iBAAiB,KAAK,SAAS,EAAE,CAAC;QAC3F,OAAO,EAAE,iBAAiB,EAAE,IAAI,EAAE,CAAC;IACrC,CAAC;IACD,OAAO,EAAE,CAAC;AACZ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,UAAU,mBAAmB;IACjC,OAAO,OAAO,CAAoC,aAAa,CAAC,CAAC;AACnE,CAAC"}
+{"version":3,"file":"bucket-builder.js","sourceRoot":"","sources":["../src/bucket-builder.ts"],"names":[],"mappings":"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"}

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

@@ -1,30 +1,29 @@
-import { BucketDeployment, type BucketDeploymentProps, type ISource } from "aws-cdk-lib/aws-s3-deployment";
+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 { type IBuilder, type Lifecycle, type Resolvable } from "@composurecdk/core";
-/**
- * Configuration properties for the S3 bucket deployment builder.
- *
- * Extends the CDK {@link BucketDeploymentProps} but replaces
- * `destinationBucket` and `distribution` with builder-managed fields that
- * support {@link Resolvable} for cross-component wiring via {@link ref}.
- *
- * `sources` is set via the builder's fluent API rather than the constructor.
- */
-export interface BucketDeploymentBuilderProps extends Omit<BucketDeploymentProps, "sources" | "destinationBucket" | "distribution"> {
-    /**
-     * The sources from which to deploy content. Typically created with
-     * `Source.asset("./path")` or `Source.data("key", "content")`.
-     */
-    sources?: ISource[];
-}
+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.

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

@@ -1 +1 @@
-{"version":3,"file":"bucket-deployment-builder.d.ts","sourceRoot":"","sources":["../src/bucket-deployment-builder.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,EAChB,KAAK,qBAAqB,EAC1B,KAAK,OAAO,EACb,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAE,KAAK,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,KAAK,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAChE,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EAEL,KAAK,QAAQ,EACb,KAAK,SAAS,EAEd,KAAK,UAAU,EAChB,MAAM,oBAAoB,CAAC;AAG5B;;;;;;;;GAQG;AACH,MAAM,WAAW,4BACf,SAAQ,IAAI,CAAC,qBAAqB,EAAE,SAAS,GAAG,mBAAmB,GAAG,cAAc,CAAC;IACrF;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,EAAE,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,6BAA6B;IAC5C,iEAAiE;IACjE,UAAU,EAAE,gBAAgB,CAAC;CAC9B;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,MAAM,wBAAwB,GAAG,QAAQ,CAC7C,4BAA4B,EAC5B,uBAAuB,CACxB,CAAC;AAEF,cAAM,uBAAwB,YAAW,SAAS,CAAC,6BAA6B,CAAC;IAC/E,KAAK,EAAE,OAAO,CAAC,4BAA4B,CAAC,CAAM;IAClD,OAAO,CAAC,kBAAkB,CAAC,CAAsB;IACjD,OAAO,CAAC,aAAa,CAAC,CAA4B;IAElD;;;;;;;;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,KAAK,CACH,KAAK,EAAE,UAAU,EACjB,EAAE,EAAE,MAAM,EACV,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC/B,6BAA6B;CA8CjC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,6BAA6B,IAAI,wBAAwB,CAExE"}
+{"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,EAEL,KAAK,QAAQ,EACb,KAAK,SAAS,EAEd,KAAK,UAAU,EAChB,MAAM,oBAAoB,CAAC;AAG5B,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,QAAQ,CAC7C,4BAA4B,EAC5B,uBAAuB,CACxB,CAAC;AAEF,cAAM,uBAAwB,YAAW,SAAS,CAAC,6BAA6B,CAAC;IAC/E,KAAK,EAAE,OAAO,CAAC,4BAA4B,CAAC,CAAM;IAClD,OAAO,CAAC,kBAAkB,CAAC,CAAsB;IACjD,OAAO,CAAC,aAAa,CAAC,CAA4B;IAElD;;;;;;;;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,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,CAExE"}

package/dist/bucket-deployment-builder.js

@@ -1,6 +1,7 @@
-import { BucketDeployment, } from "aws-cdk-lib/aws-s3-deployment";
+import { BucketDeployment } from "aws-cdk-lib/aws-s3-deployment";
 import { Builder, resolve, } from "@composurecdk/core";
-import { BUCKET_DEPLOYMENT_DEFAULTS } from "./bucket-deployment-defaults.js";
+import { createLogGroupBuilder } from "@composurecdk/logs";
+import { effectiveDefaults } from "./bucket-deployment-defaults.js";
 class BucketDeploymentBuilder {
     props = {};
     _destinationBucket;
@@ -46,17 +47,18 @@ class BucketDeploymentBuilder {
             throw new Error(`BucketDeploymentBuilder "${id}" requires at least one source. ` +
                 `Call .sources() with an array of ISource.`);
         }
-        const resolvedDistribution = this._distribution
-            ? resolve(this._distribution, ctx)
-            : undefined;
-        // Only apply distributionPaths default when a distribution is present;
-        // CDK throws if distributionPaths is set without a distribution.
-        const { distributionPaths: _distPaths, ...defaultsWithoutPaths } = BUCKET_DEPLOYMENT_DEFAULTS;
-        const effectiveDefaults = resolvedDistribution
-            ? BUCKET_DEPLOYMENT_DEFAULTS
-            : defaultsWithoutPaths;
+        const resolvedDistribution = this._distribution ? resolve(this._distribution, ctx) : undefined;
+        // Auto-create a managed LogGroup for the deployment's backing Lambda
+        // unless the user supplied their own, matching the Lambda builder pattern.
+        let logGroup;
+        let logGroupProps = {};
+        if (!deployProps.logGroup) {
+            logGroup = createLogGroupBuilder().build(scope, `${id}LogGroup`).logGroup;
+            logGroupProps = { logGroup };
+        }
         const mergedProps = {
-            ...effectiveDefaults,
+            ...effectiveDefaults(!!resolvedDistribution),
+            ...logGroupProps,
             ...deployProps,
             ...(resolvedDistribution ? { distribution: resolvedDistribution } : {}),
             sources,
@@ -64,6 +66,7 @@ class BucketDeploymentBuilder {
         };
         return {
             deployment: new BucketDeployment(scope, id, mergedProps),
+            logGroup,
         };
     }
 }

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

@@ -1 +1 @@
-{"version":3,"file":"bucket-deployment-builder.js","sourceRoot":"","sources":["../src/bucket-deployment-builder.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,GAGjB,MAAM,+BAA+B,CAAC;AAIvC,OAAO,EACL,OAAO,EAGP,OAAO,GAER,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,0BAA0B,EAAE,MAAM,iCAAiC,CAAC;AAuD7E,MAAM,uBAAuB;IAC3B,KAAK,GAA0C,EAAE,CAAC;IAC1C,kBAAkB,CAAuB;IACzC,aAAa,CAA6B;IAElD;;;;;;;;OAQG;IACH,iBAAiB,CAAC,MAA2B;QAC3C,IAAI,CAAC,kBAAkB,GAAG,MAAM,CAAC;QACjC,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;;;;;;OASG;IACH,YAAY,CAAC,YAAuC;QAClD,IAAI,CAAC,aAAa,GAAG,YAAY,CAAC;QAClC,OAAO,IAAI,CAAC;IACd,CAAC;IAED,KAAK,CACH,KAAiB,EACjB,EAAU,EACV,OAAgC;QAEhC,MAAM,GAAG,GAAG,OAAO,IAAI,EAAE,CAAC;QAE1B,MAAM,cAAc,GAAG,IAAI,CAAC,kBAAkB;YAC5C,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,kBAAkB,EAAE,GAAG,CAAC;YACvC,CAAC,CAAC,SAAS,CAAC;QAEd,IAAI,CAAC,cAAc,EAAE,CAAC;YACpB,MAAM,IAAI,KAAK,CACb,4BAA4B,EAAE,mCAAmC;gBAC/D,4DAA4D,CAC/D,CAAC;QACJ,CAAC;QAED,MAAM,EAAE,OAAO,EAAE,GAAG,WAAW,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC;QAE/C,IAAI,CAAC,OAAO,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACrC,MAAM,IAAI,KAAK,CACb,4BAA4B,EAAE,kCAAkC;gBAC9D,2CAA2C,CAC9C,CAAC;QACJ,CAAC;QAED,MAAM,oBAAoB,GAAG,IAAI,CAAC,aAAa;YAC7C,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,aAAa,EAAE,GAAG,CAAC;YAClC,CAAC,CAAC,SAAS,CAAC;QAEd,uEAAuE;QACvE,iEAAiE;QACjE,MAAM,EAAE,iBAAiB,EAAE,UAAU,EAAE,GAAG,oBAAoB,EAAE,GAAG,0BAA0B,CAAC;QAC9F,MAAM,iBAAiB,GAAG,oBAAoB;YAC5C,CAAC,CAAC,0BAA0B;YAC5B,CAAC,CAAC,oBAAoB,CAAC;QAEzB,MAAM,WAAW,GAAG;YAClB,GAAG,iBAAiB;YACpB,GAAG,WAAW;YACd,GAAG,CAAC,oBAAoB,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,oBAAoB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACvE,OAAO;YACP,iBAAiB,EAAE,cAAc;SACT,CAAC;QAE3B,OAAO;YACL,UAAU,EAAE,IAAI,gBAAgB,CAAC,KAAK,EAAE,EAAE,EAAE,WAAW,CAAC;SACzD,CAAC;IACJ,CAAC;CACF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,UAAU,6BAA6B;IAC3C,OAAO,OAAO,CAAwD,uBAAuB,CAAC,CAAC;AACjG,CAAC"}
+{"version":3,"file":"bucket-deployment-builder.js","sourceRoot":"","sources":["../src/bucket-deployment-builder.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAA8B,MAAM,+BAA+B,CAAC;AAK7F,OAAO,EACL,OAAO,EAGP,OAAO,GAER,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AAoDpE,MAAM,uBAAuB;IAC3B,KAAK,GAA0C,EAAE,CAAC;IAC1C,kBAAkB,CAAuB;IACzC,aAAa,CAA6B;IAElD;;;;;;;;OAQG;IACH,iBAAiB,CAAC,MAA2B;QAC3C,IAAI,CAAC,kBAAkB,GAAG,MAAM,CAAC;QACjC,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;;;;;;OASG;IACH,YAAY,CAAC,YAAuC;QAClD,IAAI,CAAC,aAAa,GAAG,YAAY,CAAC;QAClC,OAAO,IAAI,CAAC;IACd,CAAC;IAED,KAAK,CACH,KAAiB,EACjB,EAAU,EACV,OAAgC;QAEhC,MAAM,GAAG,GAAG,OAAO,IAAI,EAAE,CAAC;QAE1B,MAAM,cAAc,GAAG,IAAI,CAAC,kBAAkB;YAC5C,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,kBAAkB,EAAE,GAAG,CAAC;YACvC,CAAC,CAAC,SAAS,CAAC;QAEd,IAAI,CAAC,cAAc,EAAE,CAAC;YACpB,MAAM,IAAI,KAAK,CACb,4BAA4B,EAAE,mCAAmC;gBAC/D,4DAA4D,CAC/D,CAAC;QACJ,CAAC;QAED,MAAM,EAAE,OAAO,EAAE,GAAG,WAAW,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC;QAE/C,IAAI,CAAC,OAAO,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACrC,MAAM,IAAI,KAAK,CACb,4BAA4B,EAAE,kCAAkC;gBAC9D,2CAA2C,CAC9C,CAAC;QACJ,CAAC;QAED,MAAM,oBAAoB,GAAG,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,aAAa,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QAE/F,qEAAqE;QACrE,2EAA2E;QAC3E,IAAI,QAA8B,CAAC;QACnC,IAAI,aAAa,GAAG,EAAE,CAAC;QAEvB,IAAI,CAAC,WAAW,CAAC,QAAQ,EAAE,CAAC;YAC1B,QAAQ,GAAG,qBAAqB,EAAE,CAAC,KAAK,CAAC,KAAK,EAAE,GAAG,EAAE,UAAU,CAAC,CAAC,QAAQ,CAAC;YAC1E,aAAa,GAAG,EAAE,QAAQ,EAAE,CAAC;QAC/B,CAAC;QAED,MAAM,WAAW,GAAG;YAClB,GAAG,iBAAiB,CAAC,CAAC,CAAC,oBAAoB,CAAC;YAC5C,GAAG,aAAa;YAChB,GAAG,WAAW;YACd,GAAG,CAAC,oBAAoB,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,oBAAoB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACvE,OAAO;YACP,iBAAiB,EAAE,cAAc;SACT,CAAC;QAE3B,OAAO;YACL,UAAU,EAAE,IAAI,gBAAgB,CAAC,KAAK,EAAE,EAAE,EAAE,WAAW,CAAC;YACxD,QAAQ;SACT,CAAC;IACJ,CAAC;CACF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,UAAU,6BAA6B;IAC3C,OAAO,OAAO,CAAwD,uBAAuB,CAAC,CAAC;AACjG,CAAC"}

package/dist/bucket-deployment-defaults.d.ts

@@ -1,8 +1,51 @@
-import type { BucketDeploymentBuilderProps } from "./bucket-deployment-builder.js";
+import type { BucketDeploymentBuilderProps } from "./bucket-deployment-props.js";
 /**
- * Sensible defaults applied to every S3 BucketDeployment built with
- * {@link createBucketDeploymentBuilder}. Each property can be individually
- * overridden via the builder's fluent API.
+ * Secure, AWS-recommended defaults applied to every S3 BucketDeployment
+ * built with {@link createBucketDeploymentBuilder}. Each property can be
+ * individually overridden via the builder's fluent API.
  */
-export declare const BUCKET_DEPLOYMENT_DEFAULTS: Partial<BucketDeploymentBuilderProps>;
+export declare const BUCKET_DEPLOYMENT_DEFAULTS: {
+    sources?: import("aws-cdk-lib/aws-s3-deployment").ISource[];
+    accessControl?: import("aws-cdk-lib/aws-s3").BucketAccessControl;
+    destinationKeyPrefix?: string;
+    extract?: boolean;
+    exclude?: string[];
+    include?: string[];
+    prune?: boolean;
+    retainOnDelete?: boolean;
+    distributionPaths?: string[];
+    waitForDistributionInvalidation?: boolean;
+    logRetention?: import("aws-cdk-lib/aws-logs").RetentionDays;
+    logGroup?: import("aws-cdk-lib/aws-logs").ILogGroupRef;
+    memoryLimit?: number;
+    ephemeralStorageSize?: import("aws-cdk-lib").Size;
+    useEfs?: boolean;
+    role?: import("aws-cdk-lib/aws-iam").IRole;
+    metadata?: {
+        [key: string]: string;
+    };
+    cacheControl?: import("aws-cdk-lib/aws-s3-deployment").CacheControl[];
+    contentDisposition?: string;
+    contentEncoding?: string;
+    contentLanguage?: string;
+    contentType?: string;
+    expires?: import("aws-cdk-lib").Expiration;
+    serverSideEncryption?: import("aws-cdk-lib/aws-s3-deployment").ServerSideEncryption;
+    storageClass?: import("aws-cdk-lib/aws-s3-deployment").StorageClass;
+    websiteRedirectLocation?: string;
+    serverSideEncryptionAwsKmsKeyId?: string;
+    serverSideEncryptionCustomerAlgorithm?: string;
+    vpc?: import("aws-cdk-lib/aws-ec2").IVpc;
+    vpcSubnets?: import("aws-cdk-lib/aws-ec2").SubnetSelection;
+    signContent?: boolean;
+    outputObjectKeys?: boolean;
+    securityGroups?: import("aws-cdk-lib/aws-ec2").ISecurityGroup[];
+};
+/**
+ * Returns the appropriate defaults based on whether a CloudFront
+ * distribution is present. CDK throws if `distributionPaths` is set
+ * without a distribution, so distribution-specific defaults are only
+ * included when applicable.
+ */
+export declare function effectiveDefaults(hasDistribution: boolean): Partial<BucketDeploymentBuilderProps>;
 //# sourceMappingURL=bucket-deployment-defaults.d.ts.map

package/dist/bucket-deployment-defaults.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bucket-deployment-defaults.d.ts","sourceRoot":"","sources":["../src/bucket-deployment-defaults.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,gCAAgC,CAAC;AAEnF;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,EAAE,OAAO,CAAC,4BAA4B,CAc5E,CAAC"}
+{"version":3,"file":"bucket-deployment-defaults.d.ts","sourceRoot":"","sources":["../src/bucket-deployment-defaults.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,8BAA8B,CAAC;AAmDjF;;;;GAIG;AACH,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAGtC,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,eAAe,EAAE,OAAO,GAAG,OAAO,CAAC,4BAA4B,CAAC,CAEjG"}

package/dist/bucket-deployment-defaults.js

@@ -1,20 +1,64 @@
 /**
- * Sensible defaults applied to every S3 BucketDeployment built with
- * {@link createBucketDeploymentBuilder}. Each property can be individually
- * overridden via the builder's fluent API.
+ * Defaults that apply regardless of whether a CloudFront distribution is
+ * present. Split from distribution-specific defaults so the builder can
+ * merge without runtime filtering.
  */
-export const BUCKET_DEPLOYMENT_DEFAULTS = {
-    /**
-     * Invalidate all paths by default so that deployed content is immediately
-     * visible through CloudFront.
-     * @see https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/Invalidation.html
-     */
-    distributionPaths: ["/*"],
+const BASE_DEFAULTS = {
     /**
      * Remove files from the destination bucket that are not present in the
-     * source, keeping the bucket in sync with the deployed assets.
-     * @see https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3_deployment.BucketDeploymentProps.html#prune
+     * source, keeping the bucket in sync with the deployed assets and
+     * preventing stale content from being served.
+     * @see https://docs.aws.amazon.com/wellarchitected/latest/operational-excellence-pillar/ops_evolve_ops_learned_from_experience.html
      */
     prune: true,
+    /**
+     * Allocate 256 MiB to the deployment Lambda. The CDK default of 128 MiB
+     * is insufficient for deployments with more than a handful of files and
+     * can cause silent failures or timeouts.
+     * @see https://docs.aws.amazon.com/wellarchitected/latest/reliability-pillar/rel_withstand_component_failures_avoid_hard_coded_limits.html
+     * @see https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3_deployment-readme.html#memory-limit
+     */
+    memoryLimit: 256,
+    /**
+     * Do not retain deployed files when the stack is deleted. This aligns
+     * with `prune: true` semantics — the deployment keeps the bucket in
+     * sync with the source, so retaining stale files on deletion is
+     * inconsistent. The destination bucket's own removal policy governs
+     * whether the bucket itself is retained.
+     * @see https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3_deployment.BucketDeploymentProps.html#retainondelete
+     */
+    retainOnDelete: false,
+};
+/**
+ * Defaults that only apply when a CloudFront distribution is configured.
+ * CDK throws if `distributionPaths` is set without a distribution.
+ */
+const DISTRIBUTION_DEFAULTS = {
+    /**
+     * Invalidate all paths by default so that deployed content is immediately
+     * visible through CloudFront. Uses a wildcard path which counts as a
+     * single invalidation path. For deployments that only change a subset of
+     * files, override with specific paths to reduce origin fetches.
+     * @see https://docs.aws.amazon.com/wellarchitected/latest/reliability-pillar/rel_withstand_component_failures_static_stability.html
+     */
+    distributionPaths: ["/*"],
 };
+/**
+ * Secure, AWS-recommended defaults applied to every S3 BucketDeployment
+ * built with {@link createBucketDeploymentBuilder}. Each property can be
+ * individually overridden via the builder's fluent API.
+ */
+export const BUCKET_DEPLOYMENT_DEFAULTS = {
+    ...BASE_DEFAULTS,
+    ...DISTRIBUTION_DEFAULTS,
+};
+/**
+ * Returns the appropriate defaults based on whether a CloudFront
+ * distribution is present. CDK throws if `distributionPaths` is set
+ * without a distribution, so distribution-specific defaults are only
+ * included when applicable.
+ */
+export function effectiveDefaults(hasDistribution) {
+    return hasDistribution ? { ...BASE_DEFAULTS, ...DISTRIBUTION_DEFAULTS } : BASE_DEFAULTS;
+}
 //# sourceMappingURL=bucket-deployment-defaults.js.map

package/dist/bucket-deployment-defaults.js.map

@@ -1 +1 @@
-{"version":3,"file":"bucket-deployment-defaults.js","sourceRoot":"","sources":["../src/bucket-deployment-defaults.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAA0C;IAC/E;;;;OAIG;IACH,iBAAiB,EAAE,CAAC,IAAI,CAAC;IAEzB;;;;OAIG;IACH,KAAK,EAAE,IAAI;CACZ,CAAC"}
+{"version":3,"file":"bucket-deployment-defaults.js","sourceRoot":"","sources":["../src/bucket-deployment-defaults.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,MAAM,aAAa,GAA0C;IAC3D;;;;;OAKG;IACH,KAAK,EAAE,IAAI;IAEX;;;;;;OAMG;IACH,WAAW,EAAE,GAAG;IAEhB;;;;;;;OAOG;IACH,cAAc,EAAE,KAAK;CACtB,CAAC;AAEF;;;GAGG;AACH,MAAM,qBAAqB,GAA0C;IACnE;;;;;;OAMG;IACH,iBAAiB,EAAE,CAAC,IAAI,CAAC;CAC1B,CAAC;AAEF;;;;GAIG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG;IACxC,GAAG,aAAa;IAChB,GAAG,qBAAqB;CACzB,CAAC;AAEF;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,eAAwB;IACxD,OAAO,eAAe,CAAC,CAAC,CAAC,EAAE,GAAG,aAAa,EAAE,GAAG,qBAAqB,EAAE,CAAC,CAAC,CAAC,aAAa,CAAC;AAC1F,CAAC"}

package/dist/bucket-deployment-props.d.ts

@@ -0,0 +1,18 @@
+import type { BucketDeploymentProps, ISource } from "aws-cdk-lib/aws-s3-deployment";
+/**
+ * Configuration properties for the S3 bucket deployment builder.
+ *
+ * Extends the CDK {@link BucketDeploymentProps} but replaces
+ * `destinationBucket` and `distribution` with builder-managed fields that
+ * support {@link Resolvable} for cross-component wiring via {@link ref}.
+ *
+ * `sources` is set via the builder's fluent API rather than the constructor.
+ */
+export interface BucketDeploymentBuilderProps extends Omit<BucketDeploymentProps, "sources" | "destinationBucket" | "distribution"> {
+    /**
+     * The sources from which to deploy content. Typically created with
+     * `Source.asset("./path")` or `Source.data("key", "content")`.
+     */
+    sources?: ISource[];
+}
+//# sourceMappingURL=bucket-deployment-props.d.ts.map

package/dist/bucket-deployment-props.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bucket-deployment-props.d.ts","sourceRoot":"","sources":["../src/bucket-deployment-props.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,OAAO,EAAE,MAAM,+BAA+B,CAAC;AAEpF;;;;;;;;GAQG;AACH,MAAM,WAAW,4BAA6B,SAAQ,IAAI,CACxD,qBAAqB,EACrB,SAAS,GAAG,mBAAmB,GAAG,cAAc,CACjD;IACC;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,EAAE,CAAC;CACrB"}

package/dist/bucket-deployment-props.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=bucket-deployment-props.js.map

package/dist/bucket-deployment-props.js.map

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

package/dist/index.d.ts

@@ -1,3 +1,7 @@
 export { createBucketBuilder, type BucketBuilderResult, type IBucketBuilder, } from "./bucket-builder.js";
 export { BUCKET_DEFAULTS } from "./defaults.js";
+export { type BucketAlarmConfig } from "./alarm-config.js";
+export { BUCKET_ALARM_DEFAULTS } from "./alarm-defaults.js";
+export { createBucketDeploymentBuilder, type BucketDeploymentBuilderResult, type IBucketDeploymentBuilder, } from "./bucket-deployment-builder.js";
+export { BUCKET_DEPLOYMENT_DEFAULTS } from "./bucket-deployment-defaults.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,mBAAmB,EACnB,KAAK,mBAAmB,EACxB,KAAK,cAAc,GACpB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,mBAAmB,EACnB,KAAK,mBAAmB,EACxB,KAAK,cAAc,GACpB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,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,0BAA0B,EAAE,MAAM,iCAAiC,CAAC"}

package/dist/index.js

@@ -1,3 +1,6 @@
 export { createBucketBuilder, } from "./bucket-builder.js";
 export { BUCKET_DEFAULTS } from "./defaults.js";
+export { BUCKET_ALARM_DEFAULTS } from "./alarm-defaults.js";
+export { createBucketDeploymentBuilder, } from "./bucket-deployment-builder.js";
+export { BUCKET_DEPLOYMENT_DEFAULTS } from "./bucket-deployment-defaults.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,mBAAmB,GAGpB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,mBAAmB,GAGpB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAEhD,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,EACL,6BAA6B,GAG9B,MAAM,gCAAgC,CAAC;AACxC,OAAO,EAAE,0BAA0B,EAAE,MAAM,iCAAiC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@composurecdk/s3",
-  "version": "0.1.2",
+  "version": "0.3.0",
   "description": "Composable S3 bucket builder with well-architected defaults",
   "repository": {
     "type": "git",
@@ -35,7 +35,9 @@
   },
   "type": "module",
   "peerDependencies": {
-    "@composurecdk/core": "^0.1.0",
+    "@composurecdk/cloudwatch": "^0.3.0",
+    "@composurecdk/core": "^0.3.0",
+    "@composurecdk/logs": "^0.3.0",
     "aws-cdk-lib": "^2.0.0",
     "constructs": "^10.0.0"
   },