@composurecdk/sns 0.7.0 → 0.8.1

package/dist/commonjs/topic-alarms.js

@@ -0,0 +1,108 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveTopicAlarmDefinitions = resolveTopicAlarmDefinitions;
+exports.createTopicAlarms = createTopicAlarms;
+const aws_cdk_lib_1 = require("aws-cdk-lib");
+const aws_cloudwatch_1 = require("aws-cdk-lib/aws-cloudwatch");
+const cloudwatch_1 = require("@composurecdk/cloudwatch");
+const topic_alarm_defaults_js_1 = require("./topic-alarm-defaults.js");
+const METRIC_PERIOD = aws_cdk_lib_1.Duration.minutes(1);
+const METRIC_PERIOD_LABEL = `${String(METRIC_PERIOD.toMinutes())} minute`;
+/**
+ * Resolves the recommended alarm configuration into fully-resolved
+ * {@link AlarmDefinition}s for an SNS topic.
+ */
+function resolveTopicAlarmDefinitions(topic, config) {
+    if (config?.enabled === false)
+        return [];
+    const definitions = [];
+    if (config?.numberOfNotificationsFailed !== false) {
+        const cfg = (0, cloudwatch_1.resolveAlarmConfig)(config?.numberOfNotificationsFailed, topic_alarm_defaults_js_1.TOPIC_ALARM_DEFAULTS.numberOfNotificationsFailed);
+        definitions.push({
+            key: "numberOfNotificationsFailed",
+            alarmName: cfg.alarmName,
+            metric: topic.metricNumberOfNotificationsFailed({ period: METRIC_PERIOD }),
+            threshold: cfg.threshold,
+            comparisonOperator: aws_cloudwatch_1.ComparisonOperator.GREATER_THAN_THRESHOLD,
+            evaluationPeriods: cfg.evaluationPeriods,
+            datapointsToAlarm: cfg.datapointsToAlarm,
+            treatMissingData: cfg.treatMissingData,
+            description: `SNS topic is failing to deliver notifications. Threshold: > ${String(cfg.threshold)} failures in ${METRIC_PERIOD_LABEL}.`,
+        });
+    }
+    if (config?.numberOfNotificationsFilteredOutInvalidAttributes !== false) {
+        const cfg = (0, cloudwatch_1.resolveAlarmConfig)(config?.numberOfNotificationsFilteredOutInvalidAttributes, topic_alarm_defaults_js_1.TOPIC_ALARM_DEFAULTS.numberOfNotificationsFilteredOutInvalidAttributes);
+        definitions.push({
+            key: "numberOfNotificationsFilteredOutInvalidAttributes",
+            alarmName: cfg.alarmName,
+            metric: topic.metricNumberOfNotificationsFilteredOutInvalidAttributes({
+                period: METRIC_PERIOD,
+            }),
+            threshold: cfg.threshold,
+            comparisonOperator: aws_cloudwatch_1.ComparisonOperator.GREATER_THAN_THRESHOLD,
+            evaluationPeriods: cfg.evaluationPeriods,
+            datapointsToAlarm: cfg.datapointsToAlarm,
+            treatMissingData: cfg.treatMissingData,
+            description: `SNS topic messages are being filtered out due to invalid subscription filter policy attributes. Threshold: > ${String(cfg.threshold)} filtered messages in ${METRIC_PERIOD_LABEL}.`,
+        });
+    }
+    if (config?.numberOfNotificationsRedrivenToDlq !== false) {
+        const cfg = (0, cloudwatch_1.resolveAlarmConfig)(config?.numberOfNotificationsRedrivenToDlq, topic_alarm_defaults_js_1.TOPIC_ALARM_DEFAULTS.numberOfNotificationsRedrivenToDlq);
+        definitions.push({
+            key: "numberOfNotificationsRedrivenToDlq",
+            alarmName: cfg.alarmName,
+            metric: topic.metric("NumberOfNotificationsRedrivenToDlq", {
+                period: METRIC_PERIOD,
+                statistic: "Sum",
+            }),
+            threshold: cfg.threshold,
+            comparisonOperator: aws_cloudwatch_1.ComparisonOperator.GREATER_THAN_THRESHOLD,
+            evaluationPeriods: cfg.evaluationPeriods,
+            datapointsToAlarm: cfg.datapointsToAlarm,
+            treatMissingData: cfg.treatMissingData,
+            description: `SNS topic is redriving messages to a subscription dead-letter queue, indicating delivery failures. Threshold: > ${String(cfg.threshold)} redrives in ${METRIC_PERIOD_LABEL}.`,
+        });
+    }
+    if (config?.numberOfNotificationsFailedToRedriveToDlq !== false) {
+        const cfg = (0, cloudwatch_1.resolveAlarmConfig)(config?.numberOfNotificationsFailedToRedriveToDlq, topic_alarm_defaults_js_1.TOPIC_ALARM_DEFAULTS.numberOfNotificationsFailedToRedriveToDlq);
+        definitions.push({
+            key: "numberOfNotificationsFailedToRedriveToDlq",
+            alarmName: cfg.alarmName,
+            metric: topic.metric("NumberOfNotificationsFailedToRedriveToDlq", {
+                period: METRIC_PERIOD,
+                statistic: "Sum",
+            }),
+            threshold: cfg.threshold,
+            comparisonOperator: aws_cloudwatch_1.ComparisonOperator.GREATER_THAN_THRESHOLD,
+            evaluationPeriods: cfg.evaluationPeriods,
+            datapointsToAlarm: cfg.datapointsToAlarm,
+            treatMissingData: cfg.treatMissingData,
+            description: `SNS topic failed to redrive a message to a subscription dead-letter queue; messages may be lost. Threshold: > ${String(cfg.threshold)} failed redrives in ${METRIC_PERIOD_LABEL}.`,
+        });
+    }
+    return definitions;
+}
+/**
+ * Creates AWS-recommended CloudWatch alarms for an SNS topic,
+ * merging recommended definitions with any custom alarm builders.
+ *
+ * @param scope - CDK construct scope for creating alarm constructs.
+ * @param id - Base identifier for alarm construct ids.
+ * @param topic - The SNS topic to create alarms for.
+ * @param config - User-provided alarm configuration, or `false` to disable all.
+ * @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#SNS
+ */
+function createTopicAlarms(scope, id, topic, config, customAlarms = []) {
+    if (config === false)
+        return {};
+    const enabled = config?.enabled ?? topic_alarm_defaults_js_1.TOPIC_ALARM_DEFAULTS.enabled;
+    if (!enabled)
+        return {};
+    const recommended = resolveTopicAlarmDefinitions(topic, config);
+    const custom = customAlarms.map((b) => b.resolve(topic));
+    return (0, cloudwatch_1.createAlarms)(scope, id, [...recommended, ...custom]);
+}
+//# sourceMappingURL=topic-alarms.js.map

package/dist/commonjs/topic-alarms.js.map

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"topic-builder.d.ts","sourceRoot":"","sources":["../../src/topic-builder.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,KAAK,EAAE,MAAM,4BAA4B,CAAC;AACxD,OAAO,EACL,KAAK,MAAM,EACX,KAAK,kBAAkB,EACvB,YAAY,EACZ,KAAK,EACL,KAAK,UAAU,EAChB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EAAE,UAAU,EAAE,KAAK,SAAS,EAAW,KAAK,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAC1F,OAAO,EAAE,KAAK,cAAc,EAAiB,MAAM,8BAA8B,CAAC;AAClF,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAKhE;;;;GAIG;AACH,MAAM,WAAW,iBAAkB,SAAQ,UAAU;IACnD;;;;;;;;;;;;OAYG;IACH,iBAAiB,CAAC,EAAE,gBAAgB,GAAG,KAAK,CAAC;CAC9C;AAED;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,sDAAsD;IACtD,KAAK,EAAE,KAAK,CAAC;IAEb;;;;;;;;;;;OAWG;IACH,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IAE9B;;;;;;OAMG;IACH,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;CAC7C;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,MAAM,aAAa,GAAG,cAAc,CAAC,iBAAiB,EAAE,YAAY,CAAC,CAAC;AAO5E,cAAM,YAAa,YAAW,SAAS,CAAC,kBAAkB,CAAC;;IACzD,KAAK,EAAE,OAAO,CAAC,iBAAiB,CAAC,CAAM;IAIvC,QAAQ,CACN,GAAG,EAAE,MAAM,EACX,SAAS,EAAE,CAAC,KAAK,EAAE,sBAAsB,CAAC,MAAM,CAAC,KAAK,sBAAsB,CAAC,MAAM,CAAC,GACnF,IAAI;IAKP;;;;;;;;;;;;;;;OAeG;IACH,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,YAAY,EAAE,UAAU,CAAC,kBAAkB,CAAC,GAAG,IAAI;IAWhF,gCAAgC;IAChC,CAAC,UAAU,CAAC,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI;IAKxC,KAAK,CAAC,KAAK,EAAE,UAAU,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,kBAAkB;CA6B3F;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,kBAAkB,IAAI,aAAa,CAElD"}

package/dist/commonjs/topic-builder.js

@@ -0,0 +1,97 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createTopicBuilder = createTopicBuilder;
+const aws_sns_1 = require("aws-cdk-lib/aws-sns");
+const core_1 = require("@composurecdk/core");
+const cloudformation_1 = require("@composurecdk/cloudformation");
+const cloudwatch_1 = require("@composurecdk/cloudwatch");
+const topic_alarms_js_1 = require("./topic-alarms.js");
+const defaults_js_1 = require("./defaults.js");
+const subscription_defaults_js_1 = require("./subscription-defaults.js");
+class TopicBuilder {
+    props = {};
+    #customAlarms = [];
+    #subscriptions = [];
+    addAlarm(key, configure) {
+        this.#customAlarms.push(configure(new cloudwatch_1.AlarmDefinitionBuilder(key)));
+        return this;
+    }
+    /**
+     * Register a subscription to be attached to the topic at build time.
+     *
+     * Accepts any {@link ITopicSubscription} (e.g. `EmailSubscription`,
+     * `LambdaSubscription`, `SqsSubscription`) or a {@link Resolvable} so
+     * subscriptions wiring cross-component references (such as a Lambda
+     * function built by a sibling component) can be declared at configuration
+     * time.
+     *
+     * The subscription is bound via `ITopicSubscription.bind(topic)`, which
+     * performs the IAM/resource-policy wire-up required by the endpoint (for
+     * example, `LambdaSubscription.bind` grants the topic permission to
+     * invoke the function; `SqsSubscription.bind` adds the matching SQS queue
+     * policy). The resulting {@link Subscription} construct is exposed on
+     * {@link TopicBuilderResult.subscriptions} under `key`.
+     */
+    addSubscription(key, subscription) {
+        if (this.#subscriptions.some((s) => s.key === key)) {
+            throw new Error(`TopicBuilder.addSubscription: duplicate key "${key}". ` +
+                `Each subscription must use a unique key.`);
+        }
+        this.#subscriptions.push({ key, subscription });
+        return this;
+    }
+    /** @internal — see ADR-0005. */
+    [core_1.COPY_STATE](target) {
+        target.#customAlarms.push(...this.#customAlarms);
+        target.#subscriptions.push(...this.#subscriptions);
+    }
+    build(scope, id, context) {
+        const { recommendedAlarms: alarmConfig, ...topicProps } = this.props;
+        const mergedProps = {
+            ...defaults_js_1.TOPIC_DEFAULTS,
+            ...topicProps,
+        };
+        const topic = new aws_sns_1.Topic(scope, id, mergedProps);
+        const alarms = (0, topic_alarms_js_1.createTopicAlarms)(scope, id, topic, alarmConfig, this.#customAlarms);
+        const subscriptions = {};
+        for (const entry of this.#subscriptions) {
+            const resolvedSub = (0, core_1.resolve)(entry.subscription, context ?? {});
+            const subscriptionId = `${id}${entry.key[0].toUpperCase()}${entry.key.slice(1)}Subscription`;
+            const subscriptionConfig = (0, subscription_defaults_js_1.applySubscriptionDefaults)(scope, subscriptionId, resolvedSub.bind(topic));
+            subscriptions[entry.key] = new aws_sns_1.Subscription(scope, subscriptionId, {
+                topic,
+                ...subscriptionConfig,
+            });
+        }
+        return { topic, alarms, subscriptions };
+    }
+}
+/**
+ * Creates a new {@link ITopicBuilder} for configuring an AWS SNS topic.
+ *
+ * This is the entry point for defining an SNS topic component. The returned
+ * builder exposes every {@link TopicBuilderProps} property as a fluent setter/getter
+ * and implements {@link Lifecycle} for use with {@link compose}.
+ *
+ * @returns A fluent builder for an AWS SNS topic.
+ *
+ * @example
+ * ```ts
+ * const alerts = createTopicBuilder()
+ *   .topicName("my-alerts")
+ *   .displayName("My Alert Topic");
+ *
+ * // Use standalone:
+ * const result = alerts.build(stack, "AlertTopic");
+ *
+ * // Or compose into a system:
+ * const system = compose(
+ *   { alerts, handler: createFunctionBuilder() },
+ *   { alerts: [], handler: [] },
+ * );
+ * ```
+ */
+function createTopicBuilder() {
+    return (0, cloudformation_1.taggedBuilder)(TopicBuilder);
+}
+//# sourceMappingURL=topic-builder.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"topic-builder.js","sourceRoot":"","sources":["../../src/topic-builder.ts"],"names":[],"mappings":";;AA6MA,gDAEC;AA9MD,iDAM6B;AAE7B,6CAA0F;AAC1F,iEAAkF;AAClF,yDAAkE;AAElE,uDAAsD;AACtD,+CAA+C;AAC/C,yEAAuE;AAwFvE,MAAM,YAAY;IAChB,KAAK,GAA+B,EAAE,CAAC;IAC9B,aAAa,GAAqC,EAAE,CAAC;IACrD,cAAc,GAAwB,EAAE,CAAC;IAElD,QAAQ,CACN,GAAW,EACX,SAAoF;QAEpF,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,mCAAsB,CAAS,GAAG,CAAC,CAAC,CAAC,CAAC;QAC5E,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;;;;;;;;;;;;OAeG;IACH,eAAe,CAAC,GAAW,EAAE,YAA4C;QACvE,IAAI,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,KAAK,GAAG,CAAC,EAAE,CAAC;YACnD,MAAM,IAAI,KAAK,CACb,gDAAgD,GAAG,KAAK;gBACtD,0CAA0C,CAC7C,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,YAAY,EAAE,CAAC,CAAC;QAChD,OAAO,IAAI,CAAC;IACd,CAAC;IAED,gCAAgC;IAChC,CAAC,iBAAU,CAAC,CAAC,MAAoB;QAC/B,MAAM,CAAC,aAAa,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,aAAa,CAAC,CAAC;QACjD,MAAM,CAAC,cAAc,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,cAAc,CAAC,CAAC;IACrD,CAAC;IAED,KAAK,CAAC,KAAiB,EAAE,EAAU,EAAE,OAAgC;QACnE,MAAM,EAAE,iBAAiB,EAAE,WAAW,EAAE,GAAG,UAAU,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC;QAErE,MAAM,WAAW,GAAG;YAClB,GAAG,4BAAc;YACjB,GAAG,UAAU;SACO,CAAC;QAEvB,MAAM,KAAK,GAAG,IAAI,eAAK,CAAC,KAAK,EAAE,EAAE,EAAE,WAAW,CAAC,CAAC;QAEhD,MAAM,MAAM,GAAG,IAAA,mCAAiB,EAAC,KAAK,EAAE,EAAE,EAAE,KAAK,EAAE,WAAW,EAAE,IAAI,CAAC,aAAa,CAAC,CAAC;QAEpF,MAAM,aAAa,GAAiC,EAAE,CAAC;QACvD,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,cAAc,EAAE,CAAC;YACxC,MAAM,WAAW,GAAG,IAAA,cAAO,EAAC,KAAK,CAAC,YAAY,EAAE,OAAO,IAAI,EAAE,CAAC,CAAC;YAC/D,MAAM,cAAc,GAAG,GAAG,EAAE,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,GAAG,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,cAAc,CAAC;YAC7F,MAAM,kBAAkB,GAAG,IAAA,oDAAyB,EAClD,KAAK,EACL,cAAc,EACd,WAAW,CAAC,IAAI,CAAC,KAAK,CAAC,CACxB,CAAC;YACF,aAAa,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,IAAI,sBAAY,CAAC,KAAK,EAAE,cAAc,EAAE;gBACjE,KAAK;gBACL,GAAG,kBAAkB;aACtB,CAAC,CAAC;QACL,CAAC;QAED,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,CAAC;IAC1C,CAAC;CACF;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,SAAgB,kBAAkB;IAChC,OAAO,IAAA,8BAAa,EAAkC,YAAY,CAAC,CAAC;AACtE,CAAC"}

package/dist/esm/defaults.d.ts

@@ -0,0 +1,8 @@
+import type { TopicProps } from "aws-cdk-lib/aws-sns";
+/**
+ * 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.
+ */
+export declare const TOPIC_DEFAULTS: Partial<TopicProps>;
+//# sourceMappingURL=defaults.d.ts.map

package/dist/esm/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/esm/defaults.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"defaults.js","sourceRoot":"","sources":["../../src/defaults.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,MAAM,CAAC,MAAM,cAAc,GAAwB;IACjD;;;;OAIG;IACH,UAAU,EAAE,IAAI;CACjB,CAAC"}

package/dist/esm/index.d.ts

@@ -0,0 +1,7 @@
+export { createTopicBuilder, type TopicBuilderProps, type TopicBuilderResult, type ITopicBuilder, } from "./topic-builder.js";
+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/esm/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/{index.js → esm/index.js}

@@ -2,4 +2,5 @@ export { createTopicBuilder, } from "./topic-builder.js";
 export { TOPIC_DEFAULTS } from "./defaults.js";
 export { TOPIC_ALARM_DEFAULTS } from "./topic-alarm-defaults.js";
 export { createSubscriptionBuilder, } from "./subscription-builder.js";
+export { SUBSCRIPTION_DEFAULTS } from "./subscription-defaults.js";
 //# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,GAInB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAE/C,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AACjE,OAAO,EACL,yBAAyB,GAI1B,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,qBAAqB,EAA6B,MAAM,4BAA4B,CAAC"}

package/dist/esm/package.json

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

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

@@ -0,0 +1,104 @@
+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.
+ *
+ * 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 {
+    /**
+     * 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>;
+    /**
+     * The subscription to attach. Accepts any CDK
+     * {@link ITopicSubscription} (e.g. `EmailSubscription`,
+     * `LambdaSubscription`, `SqsSubscription`) or a {@link Ref} to one.
+     *
+     * 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.
+     */
+    subscription: Resolvable<ITopicSubscription>;
+}
+/**
+ * The build output of an {@link ISubscriptionBuilder}. Contains the CDK
+ * constructs created during {@link Lifecycle.build}, keyed by role.
+ */
+export interface SubscriptionBuilderResult {
+    /** The SNS subscription construct created by the builder. */
+    subscription: Subscription;
+}
+/**
+ * A fluent builder for configuring and creating an AWS SNS subscription.
+ *
+ * The builder implements {@link Lifecycle}, so it can be used directly as a
+ * component in a {@link compose | composed system}. Its `topic` and
+ * `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))
+ *   .subscription(new EmailSubscription("ops@example.com"));
+ * ```
+ */
+export type ISubscriptionBuilder = IBuilder<SubscriptionBuilderProps, SubscriptionBuilder>;
+declare class SubscriptionBuilder implements Lifecycle<SubscriptionBuilderResult> {
+    props: Partial<SubscriptionBuilderProps>;
+    build(scope: IConstruct, id: string, context?: Record<string, object>): SubscriptionBuilderResult;
+}
+/**
+ * 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"] },
+ * );
+ * ```
+ */
+export declare function createSubscriptionBuilder(): ISubscriptionBuilder;
+export {};
+//# sourceMappingURL=subscription-builder.d.ts.map

package/dist/esm/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/esm/subscription-builder.js

@@ -0,0 +1,54 @@
+import { Subscription } from "aws-cdk-lib/aws-sns";
+import { Builder, resolve, } from "@composurecdk/core";
+import { applySubscriptionDefaults } from "./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 = resolve(topic, context);
+        const resolvedSubscription = resolve(subscription, context);
+        const subscriptionConfig = applySubscriptionDefaults(scope, id, resolvedSubscription.bind(resolvedTopic));
+        const built = new 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"] },
+ * );
+ * ```
+ */
+export function createSubscriptionBuilder() {
+    // eslint-disable-next-line composurecdk/builder-must-be-tagged -- AWS::SNS::Subscription has no Tags property
+    return Builder(SubscriptionBuilder);
+}
+//# sourceMappingURL=subscription-builder.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"subscription-builder.js","sourceRoot":"","sources":["../../src/subscription-builder.ts"],"names":[],"mappings":"AAAA,OAAO,EAAwC,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAEzF,OAAO,EACL,OAAO,EAIP,OAAO,GACR,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,yBAAyB,EAAE,MAAM,4BAA4B,CAAC;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,OAAO,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;QAC9C,MAAM,oBAAoB,GAAG,OAAO,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;QAC5D,MAAM,kBAAkB,GAAG,yBAAyB,CAClD,KAAK,EACL,EAAE,EACF,oBAAoB,CAAC,IAAI,CAAC,aAAa,CAAC,CACzC,CAAC;QAEF,MAAM,KAAK,GAAG,IAAI,YAAY,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,MAAM,UAAU,yBAAyB;IACvC,8GAA8G;IAC9G,OAAO,OAAO,CAAgD,mBAAmB,CAAC,CAAC;AACrF,CAAC"}

package/dist/esm/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/esm/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/esm/subscription-defaults.js

@@ -0,0 +1,74 @@
+import { Annotations } from "aws-cdk-lib";
+import { SubscriptionProtocol } from "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
+ */
+export const 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
+     */
+    [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
+     */
+    [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
+ */
+export function applySubscriptionDefaults(scope, id, config) {
+    const protocolDefaults = SUBSCRIPTION_DEFAULTS[config.protocol] ?? {};
+    const definedConfig = Object.fromEntries(Object.entries(config).filter(([, value]) => value !== undefined));
+    const merged = { ...protocolDefaults, ...definedConfig };
+    if (merged.protocol === SubscriptionProtocol.HTTP) {
+        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/esm/subscription-defaults.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"subscription-defaults.js","sourceRoot":"","sources":["../../src/subscription-defaults.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,oBAAoB,EAAgC,MAAM,qBAAqB,CAAC;AAazF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAgE;IAChG;;;;;OAKG;IACH,CAAC,oBAAoB,CAAC,GAAG,CAAC,EAAE,EAAE,kBAAkB,EAAE,IAAI,EAAE;IAExD;;;;OAIG;IACH,CAAC,oBAAoB,CAAC,QAAQ,CAAC,EAAE,EAAE,kBAAkB,EAAE,IAAI,EAAE;CAC9D,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,UAAU,yBAAyB,CACvC,KAAiB,EACjB,EAAU,EACV,MAA+B;IAE/B,MAAM,gBAAgB,GAAG,qBAAqB,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,oBAAoB,CAAC,IAAI,EAAE,CAAC;QAClD,WAAW,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"}