@composurecdk/sns 0.7.0 → 0.8.0

package/README.md

@@ -50,7 +50,7 @@ The builder creates [AWS-recommended CloudWatch alarms](https://docs.aws.amazon.
 | `numberOfNotificationsRedrivenToDlq`                | NumberOfNotificationsRedrivenToDlq (Sum, 1 min)                 | > 0               | Always[^dlq] |
 | `numberOfNotificationsFailedToRedriveToDlq`         | NumberOfNotificationsFailedToRedriveToDlq (Sum, 1 min)          | > 0               | Always[^dlq] |
 
-[^dlq]: Metric only emits when a subscription on the topic has a dead-letter queue attached and SNS attempts redrive. `TreatMissingData` defaults to `notBreaching`, so the alarm stays quiet on topics without DLQs. Attach a DLQ via the `SubscriptionBuilder`'s `.deadLetterQueue(...)` — see [SNS DLQ docs](https://docs.aws.amazon.com/sns/latest/dg/sns-dead-letter-queues.html).
+[^dlq]: Metric only emits when a subscription on the topic has a dead-letter queue attached and SNS attempts redrive. `TreatMissingData` defaults to `notBreaching`, so the alarm stays quiet on topics without DLQs. Attach a DLQ on the `ITopicSubscription` itself (e.g. `new LambdaSubscription(fn, { deadLetterQueue: dlq })`) — see [SNS DLQ docs](https://docs.aws.amazon.com/sns/latest/dg/sns-dead-letter-queues.html).
 
 The defaults are exported as `TOPIC_ALARM_DEFAULTS` for visibility and testing:
 
@@ -167,31 +167,47 @@ const system = compose(
 
 ## Subscription Builder
 
+Use `createSubscriptionBuilder` when subscribing to a **foreign** topic — one that is not built in the same `compose` system (for example, a topic owned by another stack or account). When the topic and its subscriptions are declared together, prefer [`TopicBuilder.addSubscription`](#adding-subscriptions-to-a-topic) instead.
+
 ```ts
 import { createSubscriptionBuilder } from "@composurecdk/sns";
-import { SubscriptionProtocol } from "aws-cdk-lib/aws-sns";
+import { EmailSubscription } from "aws-cdk-lib/aws-sns-subscriptions";
 
 const emailAlerts = createSubscriptionBuilder()
   .topic(budgetTopic)
-  .protocol(SubscriptionProtocol.EMAIL)
-  .endpoint("ops@example.com")
+  .subscription(new EmailSubscription("ops@example.com"))
   .build(stack, "BudgetEmailSubscription");
 ```
 
-Every [SubscriptionProps](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_sns.SubscriptionProps.html) property is available as a fluent setter. `topic` and `deadLetterQueue` additionally accept a `Ref` so the subscription can be composed with a `TopicBuilder` (or any other component) without post-build wiring:
+The builder accepts any CDK [`ITopicSubscription`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_sns.ITopicSubscription.html) (e.g. `EmailSubscription`, `LambdaSubscription`, `SqsSubscription`) and binds it via `ITopicSubscription.bind(topic)` — the same path CDK uses for `topic.addSubscription(...)`, so endpoint-specific wire-up (Lambda invoke permission, SQS queue policy, KMS decrypt grant) happens automatically. Subscription-specific options — dead-letter queue, filter policy, raw message delivery — are configured on the `ITopicSubscription` itself, matching CDK's own API:
+
+```ts
+import { LambdaSubscription } from "aws-cdk-lib/aws-sns-subscriptions";
+
+createSubscriptionBuilder()
+  .topic(orderEventsTopic)
+  .subscription(
+    new LambdaSubscription(handler, {
+      deadLetterQueue: dlq,
+      filterPolicy: { severity: SubscriptionFilter.stringFilter({ allowlist: ["HIGH"] }) },
+    }),
+  )
+  .build(stack, "OrderEventsHandler");
+```
+
+Both `.topic(...)` and `.subscription(...)` accept a `Ref`, so the builder composes cleanly with a `TopicBuilder` — or with any other component that produces the endpoint resource:
 
 ```ts
 import { compose, ref } from "@composurecdk/core";
 import { createTopicBuilder, createSubscriptionBuilder } from "@composurecdk/sns";
-import { SubscriptionProtocol } from "aws-cdk-lib/aws-sns";
+import { EmailSubscription } from "aws-cdk-lib/aws-sns-subscriptions";
 
 const system = compose(
   {
     budget: createTopicBuilder().topicName("budget-alerts"),
     email: createSubscriptionBuilder()
       .topic(ref("budget", (r) => r.topic))
-      .protocol(SubscriptionProtocol.EMAIL)
-      .endpoint("ops@example.com"),
+      .subscription(new EmailSubscription("ops@example.com")),
   },
   { budget: [], email: ["budget"] },
 );
@@ -199,11 +215,42 @@ const system = compose(
 
 ### Subscription reliability
 
-Attaching a dead-letter queue is the primary reliability control for SNS subscriptions ([AWS Well-Architected — Reliability Pillar](https://docs.aws.amazon.com/wellarchitected/latest/reliability-pillar/welcome.html), [SNS DLQ docs](https://docs.aws.amazon.com/sns/latest/dg/sns-dead-letter-queues.html)). Pass a queue via `.deadLetterQueue(queue)` or a `ref` to one; the builder does not create a DLQ automatically because the queue resource needs to be caller-owned.
+Attaching a dead-letter queue is the primary reliability control for SNS subscriptions ([AWS Well-Architected — Reliability Pillar](https://docs.aws.amazon.com/wellarchitected/latest/reliability-pillar/welcome.html), [SNS DLQ docs](https://docs.aws.amazon.com/sns/latest/dg/sns-dead-letter-queues.html)). Pass a queue to the `ITopicSubscription` constructor (e.g. `new EmailSubscription("ops@example.com", { deadLetterQueue: dlq })`); the builder does not create a DLQ automatically because the queue resource needs to be caller-owned.
 
 The CloudWatch metrics that surface delivery failures (`NumberOfNotificationsRedrivenToDlq`, `NumberOfNotificationsFailedToRedriveToDlq`) are topic-level, so the recommended alarms for them live on the `TopicBuilder` (see [Recommended Alarms](#recommended-alarms) above) and only report data once at least one subscription has a DLQ attached.
 
-Also note: `SubscriptionProtocol.HTTP` is allowed for compatibility; prefer `HTTPS` for transport encryption ([SNS security best practices](https://docs.aws.amazon.com/sns/latest/dg/sns-security-best-practices.html)).
+## Subscription Defaults
+
+Both `createSubscriptionBuilder` and `TopicBuilder.addSubscription` apply per-protocol defaults to the `TopicSubscriptionConfig` returned by `ITopicSubscription.bind(topic)`. Defaults are gap-filling: anything the `ITopicSubscription` itself configured (via its constructor options) wins; defaults only apply where the bound config left a field unset.
+
+| Protocol   | Default                    | Rationale                                                                                                                                                                                                                                                                   |
+| ---------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `SQS`      | `rawMessageDelivery: true` | Removes the SNS envelope so downstream SQS consumers see the publisher's payload as-is — fewer bytes, no parse step. The typical choice for SNS → SQS fan-out.                                                                                                              |
+| `FIREHOSE` | `rawMessageDelivery: true` | Stores records as the publisher sent them rather than wrapped in an SNS envelope.                                                                                                                                                                                           |
+| `HTTP`     | _(no default applied)_     | Emits a synth-time warning instead — plain HTTP delivery means messages and signed-confirmation tokens travel unencrypted. Prefer `SubscriptionProtocol.HTTPS`. ([SNS security best practices](https://docs.aws.amazon.com/sns/latest/dg/sns-security-best-practices.html)) |
+
+`LAMBDA` is intentionally absent — SNS does not support raw delivery to Lambda subscriptions; the handler always receives the SNS envelope. Other protocols (HTTPS, EMAIL, EMAIL_JSON, SMS, APPLICATION) receive no overrides.
+
+These defaults are guided by [SNS raw message delivery](https://docs.aws.amazon.com/sns/latest/dg/sns-large-payload-raw-message-delivery.html) and the [AWS SNS security best practices](https://docs.aws.amazon.com/sns/latest/dg/sns-security-best-practices.html).
+
+The map is exported as `SUBSCRIPTION_DEFAULTS` for visibility and testing:
+
+```ts
+import { SUBSCRIPTION_DEFAULTS } from "@composurecdk/sns";
+```
+
+### Overriding a default
+
+Any default is individually overridable through the `ITopicSubscription`'s own constructor options:
+
+```ts
+import { SqsSubscription } from "aws-cdk-lib/aws-sns-subscriptions";
+
+createSubscriptionBuilder()
+  .topic(orders)
+  .subscription(new SqsSubscription(queue, { rawMessageDelivery: false }))
+  .build(stack, "OrdersToQueue");
+```
 
 ## Examples
 

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

@@ -0,0 +1 @@
+{"version":3,"file":"defaults.d.ts","sourceRoot":"","sources":["../../src/defaults.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAEtD;;;;GAIG;AACH,eAAO,MAAM,cAAc,EAAE,OAAO,CAAC,UAAU,CAO9C,CAAC"}

package/dist/commonjs/defaults.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TOPIC_DEFAULTS = void 0;
+/**
+ * Secure, AWS-recommended defaults applied to every SNS topic built
+ * with {@link createTopicBuilder}. Each property can be individually
+ * overridden via the builder's fluent API.
+ */
+exports.TOPIC_DEFAULTS = {
+    /**
+     * Enforce TLS for all publish and subscribe operations on the topic.
+     * Adds a resource policy condition that denies requests not using SSL.
+     * @see https://docs.aws.amazon.com/sns/latest/dg/sns-security-best-practices.html#enforce-encryption-data-in-transit
+     */
+    enforceSSL: true,
+};
+//# 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":";;;AAEA;;;;GAIG;AACU,QAAA,cAAc,GAAwB;IACjD;;;;OAIG;IACH,UAAU,EAAE,IAAI;CACjB,CAAC"}

package/dist/{index.d.ts → commonjs/index.d.ts}

@@ -3,4 +3,5 @@ export { TOPIC_DEFAULTS } from "./defaults.js";
 export { type TopicAlarmConfig } from "./topic-alarm-config.js";
 export { TOPIC_ALARM_DEFAULTS } from "./topic-alarm-defaults.js";
 export { createSubscriptionBuilder, type ISubscriptionBuilder, type SubscriptionBuilderProps, type SubscriptionBuilderResult, } from "./subscription-builder.js";
+export { SUBSCRIPTION_DEFAULTS, type SubscriptionDefaults } from "./subscription-defaults.js";
 //# sourceMappingURL=index.d.ts.map

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,kBAAkB,EAClB,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACvB,KAAK,aAAa,GACnB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EAAE,KAAK,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AACjE,OAAO,EACL,yBAAyB,EACzB,KAAK,oBAAoB,EACzB,KAAK,wBAAwB,EAC7B,KAAK,yBAAyB,GAC/B,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,qBAAqB,EAAE,KAAK,oBAAoB,EAAE,MAAM,4BAA4B,CAAC"}

package/dist/commonjs/index.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SUBSCRIPTION_DEFAULTS = exports.createSubscriptionBuilder = exports.TOPIC_ALARM_DEFAULTS = exports.TOPIC_DEFAULTS = exports.createTopicBuilder = void 0;
+var topic_builder_js_1 = require("./topic-builder.js");
+Object.defineProperty(exports, "createTopicBuilder", { enumerable: true, get: function () { return topic_builder_js_1.createTopicBuilder; } });
+var defaults_js_1 = require("./defaults.js");
+Object.defineProperty(exports, "TOPIC_DEFAULTS", { enumerable: true, get: function () { return defaults_js_1.TOPIC_DEFAULTS; } });
+var topic_alarm_defaults_js_1 = require("./topic-alarm-defaults.js");
+Object.defineProperty(exports, "TOPIC_ALARM_DEFAULTS", { enumerable: true, get: function () { return topic_alarm_defaults_js_1.TOPIC_ALARM_DEFAULTS; } });
+var subscription_builder_js_1 = require("./subscription-builder.js");
+Object.defineProperty(exports, "createSubscriptionBuilder", { enumerable: true, get: function () { return subscription_builder_js_1.createSubscriptionBuilder; } });
+var subscription_defaults_js_1 = require("./subscription-defaults.js");
+Object.defineProperty(exports, "SUBSCRIPTION_DEFAULTS", { enumerable: true, get: function () { return subscription_defaults_js_1.SUBSCRIPTION_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,uDAK4B;AAJ1B,sHAAA,kBAAkB,OAAA;AAKpB,6CAA+C;AAAtC,6GAAA,cAAc,OAAA;AAEvB,qEAAiE;AAAxD,+HAAA,oBAAoB,OAAA;AAC7B,qEAKmC;AAJjC,oIAAA,yBAAyB,OAAA;AAK3B,uEAA8F;AAArF,iIAAA,qBAAqB,OAAA"}

package/dist/commonjs/package.json

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

package/dist/{subscription-builder.d.ts → commonjs/subscription-builder.d.ts}

@@ -1,34 +1,32 @@
-import { type ITopic, Subscription, type SubscriptionProps } from "aws-cdk-lib/aws-sns";
-import type { IQueue } from "aws-cdk-lib/aws-sqs";
+import { type ITopic, type ITopicSubscription, Subscription } from "aws-cdk-lib/aws-sns";
 import { type IConstruct } from "constructs";
 import { type IBuilder, type Lifecycle, type Resolvable } from "@composurecdk/core";
 /**
  * Configuration properties for the SNS subscription builder.
  *
- * Extends the CDK {@link SubscriptionProps} but accepts {@link Resolvable}
- * values for `topic` and `deadLetterQueue` so the builder can be wired to
- * other components via {@link ref} inside a {@link compose}d system.
+ * Both fields are required at build time. Both accept {@link Resolvable}
+ * values so the subscription can be wired to other components via
+ * {@link ref} inside a {@link compose}d system.
  */
-export interface SubscriptionBuilderProps extends Omit<SubscriptionProps, "topic" | "deadLetterQueue"> {
+export interface SubscriptionBuilderProps {
     /**
      * The topic to subscribe to. Accepts a concrete {@link ITopic} or a
      * {@link Ref} to another component's output (e.g. a `TopicBuilder`).
      */
     topic: Resolvable<ITopic>;
     /**
-     * Dead-letter queue for messages that cannot be delivered to the
-     * subscribed endpoint. Accepts a concrete {@link IQueue} or a
-     * {@link Ref} to another component's output.
+     * The subscription to attach. Accepts any CDK
+     * {@link ITopicSubscription} (e.g. `EmailSubscription`,
+     * `LambdaSubscription`, `SqsSubscription`) or a {@link Ref} to one.
      *
-     * Attaching a DLQ is the primary reliability control for SNS
-     * subscriptions. Redrive and redrive-failure alarms are created on the
-     * subscribed {@link TopicBuilder} since the underlying metrics are
-     * topic-level.
-     *
-     * @see https://docs.aws.amazon.com/sns/latest/dg/sns-dead-letter-queues.html
-     * @default - no dead letter queue
+     * The subscription is bound via `ITopicSubscription.bind(topic)`, which
+     * performs the endpoint-specific IAM/resource-policy wire-up (Lambda
+     * invoke permission, SQS queue policy, KMS decrypt grant, etc.).
+     * Subscription-specific options — dead-letter queue, filter policy, raw
+     * message delivery — are configured on the `ITopicSubscription` itself,
+     * matching CDK's own subscription API.
      */
-    deadLetterQueue?: Resolvable<IQueue>;
+    subscription: Resolvable<ITopicSubscription>;
 }
 /**
  * The build output of an {@link ISubscriptionBuilder}. Contains the CDK
@@ -41,28 +39,33 @@ export interface SubscriptionBuilderResult {
 /**
  * A fluent builder for configuring and creating an AWS SNS subscription.
  *
- * Each configuration property from the CDK {@link SubscriptionProps} 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}. Its `topic` and
- * `deadLetterQueue` properties accept {@link Resolvable} values so they can
- * be supplied by another component's build output via {@link ref}.
+ * `subscription` properties accept {@link Resolvable} values so they can be
+ * supplied by another component's build output via {@link ref}.
+ *
+ * At build time, the configured `ITopicSubscription` is bound to the topic
+ * via `ITopicSubscription.bind(topic)` — the same path CDK uses for
+ * `topic.addSubscription(...)`. This ensures endpoint-specific wire-up
+ * (Lambda invoke permission, SQS queue policy, etc.) happens correctly.
  *
  * Recommended CloudWatch alarms related to subscription delivery (redrive
  * to DLQ, failed redrive to DLQ) are emitted against topic-level metrics,
  * so they live on {@link createTopicBuilder} rather than here.
  *
+ * Use this builder when subscribing to a *foreign* topic — one not built in
+ * the same `compose` system. For the common case where a topic and its
+ * subscriptions are declared together, use `TopicBuilder.addSubscription`.
+ *
  * @see https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_sns.Subscription.html
  *
  * @example
  * ```ts
+ * import { EmailSubscription } from "aws-cdk-lib/aws-sns-subscriptions";
+ *
  * const emailAlerts = createSubscriptionBuilder()
  *   .topic(ref("topic", (r: TopicBuilderResult) => r.topic))
- *   .protocol(SubscriptionProtocol.EMAIL)
- *   .endpoint("ops@example.com");
+ *   .subscription(new EmailSubscription("ops@example.com"));
  * ```
  */
 export type ISubscriptionBuilder = IBuilder<SubscriptionBuilderProps, SubscriptionBuilder>;
@@ -74,22 +77,23 @@ declare class SubscriptionBuilder implements Lifecycle<SubscriptionBuilderResult
  * Creates a new {@link ISubscriptionBuilder} for configuring an AWS SNS
  * subscription.
  *
- * This is the entry point for defining an SNS subscription component. The
- * returned builder exposes every {@link SubscriptionProps} property as a
- * fluent setter/getter and implements {@link Lifecycle} for use with
- * {@link compose}.
+ * The returned builder exposes `topic` and `subscription` as fluent
+ * setter/getters and implements {@link Lifecycle} for use with
+ * {@link compose}. Subscription-specific options (DLQ, filter policy, raw
+ * message delivery) are configured on the `ITopicSubscription` itself.
  *
  * @returns A fluent builder for an AWS SNS subscription.
  *
  * @example
  * ```ts
+ * import { EmailSubscription } from "aws-cdk-lib/aws-sns-subscriptions";
+ *
  * const system = compose(
  *   {
  *     topic: createTopicBuilder().topicName("budget-alerts"),
  *     email: createSubscriptionBuilder()
  *       .topic(ref("topic", (r: TopicBuilderResult) => r.topic))
- *       .protocol(SubscriptionProtocol.EMAIL)
- *       .endpoint("ops@example.com"),
+ *       .subscription(new EmailSubscription("ops@example.com")),
  *   },
  *   { topic: [], email: ["topic"] },
  * );

package/dist/commonjs/subscription-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subscription-builder.d.ts","sourceRoot":"","sources":["../../src/subscription-builder.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,MAAM,EAAE,KAAK,kBAAkB,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACzF,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EAEL,KAAK,QAAQ,EACb,KAAK,SAAS,EACd,KAAK,UAAU,EAEhB,MAAM,oBAAoB,CAAC;AAG5B;;;;;;GAMG;AACH,MAAM,WAAW,wBAAwB;IACvC;;;OAGG;IACH,KAAK,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC;IAE1B;;;;;;;;;;;OAWG;IACH,YAAY,EAAE,UAAU,CAAC,kBAAkB,CAAC,CAAC;CAC9C;AAED;;;GAGG;AACH,MAAM,WAAW,yBAAyB;IACxC,6DAA6D;IAC7D,YAAY,EAAE,YAAY,CAAC;CAC5B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,MAAM,MAAM,oBAAoB,GAAG,QAAQ,CAAC,wBAAwB,EAAE,mBAAmB,CAAC,CAAC;AAE3F,cAAM,mBAAoB,YAAW,SAAS,CAAC,yBAAyB,CAAC;IACvE,KAAK,EAAE,OAAO,CAAC,wBAAwB,CAAC,CAAM;IAE9C,KAAK,CACH,KAAK,EAAE,UAAU,EACjB,EAAE,EAAE,MAAM,EACV,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,GACnC,yBAAyB;CA6B7B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,yBAAyB,IAAI,oBAAoB,CAGhE"}

package/dist/commonjs/subscription-builder.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSubscriptionBuilder = createSubscriptionBuilder;
+const aws_sns_1 = require("aws-cdk-lib/aws-sns");
+const core_1 = require("@composurecdk/core");
+const subscription_defaults_js_1 = require("./subscription-defaults.js");
+class SubscriptionBuilder {
+    props = {};
+    build(scope, id, context = {}) {
+        const { topic, subscription } = this.props;
+        if (topic === undefined) {
+            throw new Error(`SubscriptionBuilder "${id}": topic is required. Call .topic(...) with an ITopic or a Ref before building.`);
+        }
+        if (subscription === undefined) {
+            throw new Error(`SubscriptionBuilder "${id}": subscription is required. Call .subscription(...) with an ITopicSubscription (e.g. EmailSubscription, LambdaSubscription, SqsSubscription) or a Ref before building.`);
+        }
+        const resolvedTopic = (0, core_1.resolve)(topic, context);
+        const resolvedSubscription = (0, core_1.resolve)(subscription, context);
+        const subscriptionConfig = (0, subscription_defaults_js_1.applySubscriptionDefaults)(scope, id, resolvedSubscription.bind(resolvedTopic));
+        const built = new aws_sns_1.Subscription(scope, id, {
+            topic: resolvedTopic,
+            ...subscriptionConfig,
+        });
+        return { subscription: built };
+    }
+}
+/**
+ * Creates a new {@link ISubscriptionBuilder} for configuring an AWS SNS
+ * subscription.
+ *
+ * The returned builder exposes `topic` and `subscription` as fluent
+ * setter/getters and implements {@link Lifecycle} for use with
+ * {@link compose}. Subscription-specific options (DLQ, filter policy, raw
+ * message delivery) are configured on the `ITopicSubscription` itself.
+ *
+ * @returns A fluent builder for an AWS SNS subscription.
+ *
+ * @example
+ * ```ts
+ * import { EmailSubscription } from "aws-cdk-lib/aws-sns-subscriptions";
+ *
+ * const system = compose(
+ *   {
+ *     topic: createTopicBuilder().topicName("budget-alerts"),
+ *     email: createSubscriptionBuilder()
+ *       .topic(ref("topic", (r: TopicBuilderResult) => r.topic))
+ *       .subscription(new EmailSubscription("ops@example.com")),
+ *   },
+ *   { topic: [], email: ["topic"] },
+ * );
+ * ```
+ */
+function createSubscriptionBuilder() {
+    // eslint-disable-next-line composurecdk/builder-must-be-tagged -- AWS::SNS::Subscription has no Tags property
+    return (0, core_1.Builder)(SubscriptionBuilder);
+}
+//# sourceMappingURL=subscription-builder.js.map

package/dist/commonjs/subscription-builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"subscription-builder.js","sourceRoot":"","sources":["../../src/subscription-builder.ts"],"names":[],"mappings":";;AAoJA,8DAGC;AAvJD,iDAAyF;AAEzF,6CAM4B;AAC5B,yEAAuE;AA2EvE,MAAM,mBAAmB;IACvB,KAAK,GAAsC,EAAE,CAAC;IAE9C,KAAK,CACH,KAAiB,EACjB,EAAU,EACV,UAAkC,EAAE;QAEpC,MAAM,EAAE,KAAK,EAAE,YAAY,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC;QAE3C,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,MAAM,IAAI,KAAK,CACb,wBAAwB,EAAE,iFAAiF,CAC5G,CAAC;QACJ,CAAC;QACD,IAAI,YAAY,KAAK,SAAS,EAAE,CAAC;YAC/B,MAAM,IAAI,KAAK,CACb,wBAAwB,EAAE,yKAAyK,CACpM,CAAC;QACJ,CAAC;QAED,MAAM,aAAa,GAAG,IAAA,cAAO,EAAC,KAAK,EAAE,OAAO,CAAC,CAAC;QAC9C,MAAM,oBAAoB,GAAG,IAAA,cAAO,EAAC,YAAY,EAAE,OAAO,CAAC,CAAC;QAC5D,MAAM,kBAAkB,GAAG,IAAA,oDAAyB,EAClD,KAAK,EACL,EAAE,EACF,oBAAoB,CAAC,IAAI,CAAC,aAAa,CAAC,CACzC,CAAC;QAEF,MAAM,KAAK,GAAG,IAAI,sBAAY,CAAC,KAAK,EAAE,EAAE,EAAE;YACxC,KAAK,EAAE,aAAa;YACpB,GAAG,kBAAkB;SACtB,CAAC,CAAC;QAEH,OAAO,EAAE,YAAY,EAAE,KAAK,EAAE,CAAC;IACjC,CAAC;CACF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,SAAgB,yBAAyB;IACvC,8GAA8G;IAC9G,OAAO,IAAA,cAAO,EAAgD,mBAAmB,CAAC,CAAC;AACrF,CAAC"}

package/dist/commonjs/subscription-defaults.d.ts

@@ -0,0 +1,60 @@
+import { SubscriptionProtocol, type TopicSubscriptionConfig } from "aws-cdk-lib/aws-sns";
+import type { IConstruct } from "constructs";
+/**
+ * Per-protocol overrides applied to a {@link TopicSubscriptionConfig}.
+ *
+ * Only fields relevant to delivery semantics are included; `protocol`,
+ * `endpoint`, `subscriberId`, etc. are determined by the
+ * {@link aws-cdk-lib.aws_sns.ITopicSubscription | ITopicSubscription} and
+ * are never defaulted here.
+ */
+export type SubscriptionDefaults = Pick<TopicSubscriptionConfig, "rawMessageDelivery">;
+/**
+ * AWS-recommended defaults applied per `SubscriptionProtocol` when a
+ * subscription is bound through either `createSubscriptionBuilder` or
+ * `TopicBuilder.addSubscription`.
+ *
+ * Defaults are merged into the {@link TopicSubscriptionConfig} returned by
+ * `ITopicSubscription.bind(topic)`: any field the `ITopicSubscription`
+ * itself set to a defined value wins, and the default only fills the gap
+ * when the bound config left the field `undefined`. This keeps every
+ * default individually overridable through the `ITopicSubscription`
+ * constructor options.
+ *
+ * Only the protocols on which SNS actually supports raw message delivery
+ * (SQS and Firehose) receive a default — applying it elsewhere would
+ * trigger CDK's own raw-delivery validation at synth time. Lambda is
+ * intentionally absent: SNS does not support raw delivery to Lambda
+ * subscriptions, and Lambda handlers always receive the SNS envelope.
+ *
+ * @see https://docs.aws.amazon.com/sns/latest/dg/sns-large-payload-raw-message-delivery.html
+ */
+export declare const SUBSCRIPTION_DEFAULTS: Partial<Record<SubscriptionProtocol, SubscriptionDefaults>>;
+/**
+ * Merge {@link SUBSCRIPTION_DEFAULTS} into the result of
+ * `ITopicSubscription.bind(topic)` and emit transport-security warnings.
+ *
+ * Both `createSubscriptionBuilder` and `TopicBuilder.addSubscription`
+ * route through this helper so SNS subscriptions get the same defaults
+ * regardless of which builder created them.
+ *
+ * - Defaults are gap-filling: any field the `ITopicSubscription`
+ *   explicitly set wins, and the default only applies when the bound
+ *   config left the field `undefined`. Many `ITopicSubscription`
+ *   implementations propagate `undefined` from their props, so a naive
+ *   `{ ...defaults, ...config }` spread would clobber the defaults —
+ *   this helper filters undefined entries before merging.
+ * - Emits a synth-time warning when subscribing over plain `HTTP` to
+ *   nudge callers toward `HTTPS` for transport encryption. Other invalid
+ *   protocol/option combinations (e.g. `rawMessageDelivery` on EMAIL)
+ *   are surfaced by CDK's own `Subscription` validation.
+ *
+ * @param scope - The construct scope used to attach annotations.
+ * @param id - The subscription's logical id, used in warning text.
+ * @param config - The `TopicSubscriptionConfig` returned by
+ *   `ITopicSubscription.bind(topic)`.
+ *
+ * @see https://docs.aws.amazon.com/sns/latest/dg/sns-security-best-practices.html
+ */
+export declare function applySubscriptionDefaults(scope: IConstruct, id: string, config: TopicSubscriptionConfig): TopicSubscriptionConfig;
+//# sourceMappingURL=subscription-defaults.d.ts.map

package/dist/commonjs/subscription-defaults.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subscription-defaults.d.ts","sourceRoot":"","sources":["../../src/subscription-defaults.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,oBAAoB,EAAE,KAAK,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AACzF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C;;;;;;;GAOG;AACH,MAAM,MAAM,oBAAoB,GAAG,IAAI,CAAC,uBAAuB,EAAE,oBAAoB,CAAC,CAAC;AAEvF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,qBAAqB,EAAE,OAAO,CAAC,MAAM,CAAC,oBAAoB,EAAE,oBAAoB,CAAC,CAe7F,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,UAAU,EACjB,EAAE,EAAE,MAAM,EACV,MAAM,EAAE,uBAAuB,GAC9B,uBAAuB,CAgBzB"}

package/dist/commonjs/subscription-defaults.js

@@ -0,0 +1,78 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SUBSCRIPTION_DEFAULTS = void 0;
+exports.applySubscriptionDefaults = applySubscriptionDefaults;
+const aws_cdk_lib_1 = require("aws-cdk-lib");
+const aws_sns_1 = require("aws-cdk-lib/aws-sns");
+/**
+ * AWS-recommended defaults applied per `SubscriptionProtocol` when a
+ * subscription is bound through either `createSubscriptionBuilder` or
+ * `TopicBuilder.addSubscription`.
+ *
+ * Defaults are merged into the {@link TopicSubscriptionConfig} returned by
+ * `ITopicSubscription.bind(topic)`: any field the `ITopicSubscription`
+ * itself set to a defined value wins, and the default only fills the gap
+ * when the bound config left the field `undefined`. This keeps every
+ * default individually overridable through the `ITopicSubscription`
+ * constructor options.
+ *
+ * Only the protocols on which SNS actually supports raw message delivery
+ * (SQS and Firehose) receive a default — applying it elsewhere would
+ * trigger CDK's own raw-delivery validation at synth time. Lambda is
+ * intentionally absent: SNS does not support raw delivery to Lambda
+ * subscriptions, and Lambda handlers always receive the SNS envelope.
+ *
+ * @see https://docs.aws.amazon.com/sns/latest/dg/sns-large-payload-raw-message-delivery.html
+ */
+exports.SUBSCRIPTION_DEFAULTS = {
+    /**
+     * Deliver raw payloads to SQS so downstream consumers don't have to
+     * unwrap the SNS envelope. Halves payload size and removes a parse step
+     * — the typical choice for SNS → SQS fan-out.
+     * @see https://docs.aws.amazon.com/sns/latest/dg/sns-large-payload-raw-message-delivery.html
+     */
+    [aws_sns_1.SubscriptionProtocol.SQS]: { rawMessageDelivery: true },
+    /**
+     * Deliver raw payloads to Firehose so records are stored as the
+     * publisher sent them rather than wrapped in an SNS envelope.
+     * @see https://docs.aws.amazon.com/sns/latest/dg/sns-large-payload-raw-message-delivery.html
+     */
+    [aws_sns_1.SubscriptionProtocol.FIREHOSE]: { rawMessageDelivery: true },
+};
+/**
+ * Merge {@link SUBSCRIPTION_DEFAULTS} into the result of
+ * `ITopicSubscription.bind(topic)` and emit transport-security warnings.
+ *
+ * Both `createSubscriptionBuilder` and `TopicBuilder.addSubscription`
+ * route through this helper so SNS subscriptions get the same defaults
+ * regardless of which builder created them.
+ *
+ * - Defaults are gap-filling: any field the `ITopicSubscription`
+ *   explicitly set wins, and the default only applies when the bound
+ *   config left the field `undefined`. Many `ITopicSubscription`
+ *   implementations propagate `undefined` from their props, so a naive
+ *   `{ ...defaults, ...config }` spread would clobber the defaults —
+ *   this helper filters undefined entries before merging.
+ * - Emits a synth-time warning when subscribing over plain `HTTP` to
+ *   nudge callers toward `HTTPS` for transport encryption. Other invalid
+ *   protocol/option combinations (e.g. `rawMessageDelivery` on EMAIL)
+ *   are surfaced by CDK's own `Subscription` validation.
+ *
+ * @param scope - The construct scope used to attach annotations.
+ * @param id - The subscription's logical id, used in warning text.
+ * @param config - The `TopicSubscriptionConfig` returned by
+ *   `ITopicSubscription.bind(topic)`.
+ *
+ * @see https://docs.aws.amazon.com/sns/latest/dg/sns-security-best-practices.html
+ */
+function applySubscriptionDefaults(scope, id, config) {
+    const protocolDefaults = exports.SUBSCRIPTION_DEFAULTS[config.protocol] ?? {};
+    const definedConfig = Object.fromEntries(Object.entries(config).filter(([, value]) => value !== undefined));
+    const merged = { ...protocolDefaults, ...definedConfig };
+    if (merged.protocol === aws_sns_1.SubscriptionProtocol.HTTP) {
+        aws_cdk_lib_1.Annotations.of(scope).addWarningV2("@composurecdk/sns:http-subscription-insecure", `SNS subscription "${id}": delivering over plain HTTP — messages and any signed-confirmation tokens travel unencrypted. ` +
+            `Prefer SubscriptionProtocol.HTTPS for transport encryption.`);
+    }
+    return merged;
+}
+//# sourceMappingURL=subscription-defaults.js.map

package/dist/commonjs/subscription-defaults.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"subscription-defaults.js","sourceRoot":"","sources":["../../src/subscription-defaults.ts"],"names":[],"mappings":";;;AA6EA,8DAoBC;AAjGD,6CAA0C;AAC1C,iDAAyF;AAazF;;;;;;;;;;;;;;;;;;;GAmBG;AACU,QAAA,qBAAqB,GAAgE;IAChG;;;;;OAKG;IACH,CAAC,8BAAoB,CAAC,GAAG,CAAC,EAAE,EAAE,kBAAkB,EAAE,IAAI,EAAE;IAExD;;;;OAIG;IACH,CAAC,8BAAoB,CAAC,QAAQ,CAAC,EAAE,EAAE,kBAAkB,EAAE,IAAI,EAAE;CAC9D,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,SAAgB,yBAAyB,CACvC,KAAiB,EACjB,EAAU,EACV,MAA+B;IAE/B,MAAM,gBAAgB,GAAG,6BAAqB,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC;IACtE,MAAM,aAAa,GAAG,MAAM,CAAC,WAAW,CACtC,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,KAAK,KAAK,SAAS,CAAC,CAClE,CAAC;IACF,MAAM,MAAM,GAAG,EAAE,GAAG,gBAAgB,EAAE,GAAG,aAAa,EAA6B,CAAC;IAEpF,IAAI,MAAM,CAAC,QAAQ,KAAK,8BAAoB,CAAC,IAAI,EAAE,CAAC;QAClD,yBAAW,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,YAAY,CAChC,8CAA8C,EAC9C,qBAAqB,EAAE,kGAAkG;YACvH,6DAA6D,CAChE,CAAC;IACJ,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/commonjs/topic-alarm-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"topic-alarm-config.d.ts","sourceRoot":"","sources":["../../src/topic-alarm-config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAE5D;;;;;;;GAOG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;;;;;;OAOG;IACH,2BAA2B,CAAC,EAAE,WAAW,GAAG,KAAK,CAAC;IAElD;;;;;;;;;OASG;IACH,iDAAiD,CAAC,EAAE,WAAW,GAAG,KAAK,CAAC;IAExE;;;;;;;;;;;;;;;OAeG;IACH,kCAAkC,CAAC,EAAE,WAAW,GAAG,KAAK,CAAC;IAEzD;;;;;;;;;;OAUG;IACH,yCAAyC,CAAC,EAAE,WAAW,GAAG,KAAK,CAAC;CACjE"}

package/dist/commonjs/topic-alarm-config.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=topic-alarm-config.js.map

package/dist/commonjs/topic-alarm-config.js.map

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

package/dist/commonjs/topic-alarm-defaults.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"topic-alarm-defaults.d.ts","sourceRoot":"","sources":["../../src/topic-alarm-defaults.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAEpE,UAAU,kBAAkB;IAC1B,OAAO,EAAE,IAAI,CAAC;IACd,2BAA2B,EAAE,mBAAmB,CAAC;IACjD,iDAAiD,EAAE,mBAAmB,CAAC;IACvE,kCAAkC,EAAE,mBAAmB,CAAC;IACxD,yCAAyC,EAAE,mBAAmB,CAAC;CAChE;AAED;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,EAAE,kBAkClC,CAAC"}

package/dist/commonjs/topic-alarm-defaults.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TOPIC_ALARM_DEFAULTS = void 0;
+const aws_cloudwatch_1 = require("aws-cdk-lib/aws-cloudwatch");
+/**
+ * AWS-recommended default alarm configuration for SNS topics.
+ *
+ * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#SNS
+ */
+exports.TOPIC_ALARM_DEFAULTS = {
+    enabled: true,
+    /** Any delivery failure is worth investigating; threshold 0. */
+    numberOfNotificationsFailed: {
+        threshold: 0,
+        evaluationPeriods: 1,
+        datapointsToAlarm: 1,
+        treatMissingData: aws_cloudwatch_1.TreatMissingData.NOT_BREACHING,
+    },
+    /** Any message filtered due to invalid attributes indicates a configuration issue; threshold 0. */
+    numberOfNotificationsFilteredOutInvalidAttributes: {
+        threshold: 0,
+        evaluationPeriods: 1,
+        datapointsToAlarm: 1,
+        treatMissingData: aws_cloudwatch_1.TreatMissingData.NOT_BREACHING,
+    },
+    /** Any redrive to a subscription DLQ indicates a delivery failure worth investigating; threshold 0. */
+    numberOfNotificationsRedrivenToDlq: {
+        threshold: 0,
+        evaluationPeriods: 1,
+        datapointsToAlarm: 1,
+        treatMissingData: aws_cloudwatch_1.TreatMissingData.NOT_BREACHING,
+    },
+    /** Any failure to redrive to a DLQ means message loss; threshold 0. */
+    numberOfNotificationsFailedToRedriveToDlq: {
+        threshold: 0,
+        evaluationPeriods: 1,
+        datapointsToAlarm: 1,
+        treatMissingData: aws_cloudwatch_1.TreatMissingData.NOT_BREACHING,
+    },
+};
+//# sourceMappingURL=topic-alarm-defaults.js.map

package/dist/commonjs/topic-alarm-defaults.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"topic-alarm-defaults.js","sourceRoot":"","sources":["../../src/topic-alarm-defaults.ts"],"names":[],"mappings":";;;AAAA,+DAA8D;AAW9D;;;;GAIG;AACU,QAAA,oBAAoB,GAAuB;IACtD,OAAO,EAAE,IAAI;IAEb,gEAAgE;IAChE,2BAA2B,EAAE;QAC3B,SAAS,EAAE,CAAC;QACZ,iBAAiB,EAAE,CAAC;QACpB,iBAAiB,EAAE,CAAC;QACpB,gBAAgB,EAAE,iCAAgB,CAAC,aAAa;KACjD;IAED,mGAAmG;IACnG,iDAAiD,EAAE;QACjD,SAAS,EAAE,CAAC;QACZ,iBAAiB,EAAE,CAAC;QACpB,iBAAiB,EAAE,CAAC;QACpB,gBAAgB,EAAE,iCAAgB,CAAC,aAAa;KACjD;IAED,uGAAuG;IACvG,kCAAkC,EAAE;QAClC,SAAS,EAAE,CAAC;QACZ,iBAAiB,EAAE,CAAC;QACpB,iBAAiB,EAAE,CAAC;QACpB,gBAAgB,EAAE,iCAAgB,CAAC,aAAa;KACjD;IAED,uEAAuE;IACvE,yCAAyC,EAAE;QACzC,SAAS,EAAE,CAAC;QACZ,iBAAiB,EAAE,CAAC;QACpB,iBAAiB,EAAE,CAAC;QACpB,gBAAgB,EAAE,iCAAgB,CAAC,aAAa;KACjD;CACF,CAAC"}

package/dist/commonjs/topic-alarms.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"topic-alarms.d.ts","sourceRoot":"","sources":["../../src/topic-alarms.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,KAAK,EAAsB,MAAM,4BAA4B,CAAC;AAC5E,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAChE,OAAO,EAAE,sBAAsB,EAAoC,MAAM,0BAA0B,CAAC;AACpG,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAMhE;;;GAGG;AACH,wBAAgB,4BAA4B,CAC1C,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,gBAAgB,GAAG,SAAS,GACnC,eAAe,EAAE,CAsFnB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,UAAU,EACjB,EAAE,EAAE,MAAM,EACV,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,gBAAgB,GAAG,KAAK,GAAG,SAAS,EAC5C,YAAY,GAAE,sBAAsB,CAAC,MAAM,CAAC,EAAO,GAClD,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAUvB"}