@composurecdk/sns 0.3.0

package/README.md

@@ -0,0 +1,129 @@
+# @composurecdk/sns
+
+SNS topic builder for [ComposureCDK](../../README.md).
+
+This package provides a fluent builder for SNS topics with secure, AWS-recommended defaults. It wraps the CDK [Topic](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_sns.Topic.html) construct — refer to the CDK documentation for the full set of configurable properties.
+
+## Topic Builder
+
+```ts
+import { createTopicBuilder } from "@composurecdk/sns";
+
+const alerts = createTopicBuilder()
+  .topicName("my-alerts")
+  .displayName("My Alert Topic")
+  .build(stack, "AlertTopic");
+```
+
+Every [TopicProps](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_sns.TopicProps.html) property is available as a fluent setter on the builder.
+
+## Secure Defaults
+
+`createTopicBuilder` applies the following defaults. Each can be overridden via the builder's fluent API.
+
+| Property     | Default | Rationale                                                                     |
+| ------------ | ------- | ----------------------------------------------------------------------------- |
+| `enforceSSL` | `true`  | Denies publish/subscribe requests that do not use TLS (transport encryption). |
+
+These defaults are guided by the [AWS SNS Security Best Practices](https://docs.aws.amazon.com/sns/latest/dg/sns-security-best-practices.html#enforce-encryption-data-in-transit).
+
+The defaults are exported as `TOPIC_DEFAULTS` for visibility and testing:
+
+```ts
+import { TOPIC_DEFAULTS } from "@composurecdk/sns";
+```
+
+### Overriding defaults
+
+```ts
+const topic = createTopicBuilder().topicName("my-topic").enforceSSL(false).build(stack, "MyTopic");
+```
+
+## Recommended Alarms
+
+The builder creates [AWS-recommended CloudWatch alarms](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#SNS) by default. No alarm actions are configured — access alarms from the build result to add SNS topics or other actions.
+
+| Alarm                                               | Metric                                                          | Default threshold | Created when |
+| --------------------------------------------------- | --------------------------------------------------------------- | ----------------- | ------------ |
+| `numberOfNotificationsFailed`                       | NumberOfNotificationsFailed (Sum, 1 min)                        | > 0               | Always       |
+| `numberOfNotificationsFilteredOutInvalidAttributes` | NumberOfNotificationsFilteredOut-InvalidAttributes (Sum, 1 min) | > 0               | Always       |
+
+The defaults are exported as `TOPIC_ALARM_DEFAULTS` for visibility and testing:
+
+```ts
+import { TOPIC_ALARM_DEFAULTS } from "@composurecdk/sns";
+```
+
+### Customizing thresholds
+
+Override individual alarm properties via `recommendedAlarms`. Unspecified fields keep their defaults.
+
+```ts
+const topic = createTopicBuilder()
+  .topicName("my-topic")
+  .recommendedAlarms({
+    numberOfNotificationsFailed: { threshold: 5, evaluationPeriods: 3 },
+  });
+```
+
+### Disabling alarms
+
+Disable all recommended alarms:
+
+```ts
+builder.recommendedAlarms(false);
+// or
+builder.recommendedAlarms({ enabled: false });
+```
+
+Disable individual alarms:
+
+```ts
+builder.recommendedAlarms({ numberOfNotificationsFailed: false });
+```
+
+### Custom alarms
+
+Add custom alarms alongside the recommended ones via `addAlarm`. The callback receives an `AlarmDefinitionBuilder` typed to `ITopic`, so the metric factory has access to the topic's properties.
+
+```ts
+import { Metric } from "aws-cdk-lib/aws-cloudwatch";
+
+const topic = createTopicBuilder()
+  .topicName("my-topic")
+  .addAlarm("highPublishRate", (alarm) =>
+    alarm
+      .metric(
+        (topic) =>
+          new Metric({
+            namespace: "AWS/SNS",
+            metricName: "NumberOfMessagesPublished",
+            dimensionsMap: { TopicName: topic.topicName },
+            statistic: "Sum",
+            period: Duration.minutes(1),
+          }),
+      )
+      .threshold(10000)
+      .greaterThanOrEqual()
+      .description("Topic receiving unusually high message volume"),
+  );
+```
+
+### Applying alarm actions
+
+Alarms are returned in the build result as `Record<string, Alarm>`:
+
+```ts
+const result = topic.build(stack, "MyTopic");
+
+const alertTopic = new Topic(stack, "AlertTopic");
+for (const alarm of Object.values(result.alarms)) {
+  alarm.addAlarmAction(new SnsAction(alertTopic));
+}
+```
+
+## Examples
+
+- [LambdaApiStack](../examples/src/lambda-api-app.ts) — REST API with TopicBuilder for alarm actions
+- [DualFunctionStack](../examples/src/dual-function-app.ts) — Two Lambda functions with TopicBuilder for alarm actions
+- [StaticWebsiteStack](../examples/src/static-website/app.ts) — Static website with TopicBuilder for alarm actions

package/dist/alarm-config.d.ts

@@ -0,0 +1,38 @@
+import type { AlarmConfig } from "@composurecdk/cloudwatch";
+/**
+ * Controls which recommended alarms are created for an SNS topic.
+ * 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.
+ *
+ * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#SNS
+ */
+export interface TopicAlarmConfig {
+    /**
+     * 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 SNS fails to deliver notifications to subscribed endpoints.
+     *
+     * Metric: `AWS/SNS NumberOfNotificationsFailed`, statistic Sum, period 1 minute.
+     * Default threshold: > 0 failures.
+     *
+     * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#SNS
+     */
+    numberOfNotificationsFailed?: AlarmConfig | false;
+    /**
+     * Alarm when messages are rejected due to invalid subscription filter
+     * policy attributes.
+     *
+     * Metric: `AWS/SNS NumberOfNotificationsFilteredOut-InvalidAttributes`,
+     * statistic Sum, period 1 minute.
+     * Default threshold: > 0 filtered messages.
+     *
+     * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#SNS
+     */
+    numberOfNotificationsFilteredOutInvalidAttributes?: 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;;;;;;;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;CACzE"}

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 TopicAlarmDefaults {
+    enabled: true;
+    numberOfNotificationsFailed: Required<AlarmConfig>;
+    numberOfNotificationsFilteredOutInvalidAttributes: Required<AlarmConfig>;
+}
+/**
+ * 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
+ */
+export declare const TOPIC_ALARM_DEFAULTS: TopicAlarmDefaults;
+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,kBAAkB;IAC1B,OAAO,EAAE,IAAI,CAAC;IACd,2BAA2B,EAAE,QAAQ,CAAC,WAAW,CAAC,CAAC;IACnD,iDAAiD,EAAE,QAAQ,CAAC,WAAW,CAAC,CAAC;CAC1E;AAED;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,EAAE,kBAkBlC,CAAC"}

package/dist/alarm-defaults.js

@@ -0,0 +1,24 @@
+import { TreatMissingData } from "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
+ */
+export const TOPIC_ALARM_DEFAULTS = {
+    enabled: true,
+    /** Any delivery failure is worth investigating; threshold 0. */
+    numberOfNotificationsFailed: {
+        threshold: 0,
+        evaluationPeriods: 1,
+        datapointsToAlarm: 1,
+        treatMissingData: TreatMissingData.NOT_BREACHING,
+    },
+    /** Any message filtered due to invalid attributes indicates a configuration issue; threshold 0. */
+    numberOfNotificationsFilteredOutInvalidAttributes: {
+        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,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,gBAAgB,CAAC,aAAa;KACjD;IAED,mGAAmG;IACnG,iDAAiD,EAAE;QACjD,SAAS,EAAE,CAAC;QACZ,iBAAiB,EAAE,CAAC;QACpB,iBAAiB,EAAE,CAAC;QACpB,gBAAgB,EAAE,gBAAgB,CAAC,aAAa;KACjD;CACF,CAAC"}

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

@@ -0,0 +1,14 @@
+/**
+ * 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 const 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/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/index.d.ts

@@ -0,0 +1,5 @@
+export { createTopicBuilder, type TopicBuilderResult, type ITopicBuilder, } from "./topic-builder.js";
+export { TOPIC_DEFAULTS } from "./defaults.js";
+export { type TopicAlarmConfig } from "./alarm-config.js";
+export { TOPIC_ALARM_DEFAULTS } from "./alarm-defaults.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/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,kBAAkB,EACvB,KAAK,aAAa,GACnB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EAAE,KAAK,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAC1D,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/index.js

@@ -0,0 +1,4 @@
+export { createTopicBuilder, } from "./topic-builder.js";
+export { TOPIC_DEFAULTS } from "./defaults.js";
+export { TOPIC_ALARM_DEFAULTS } from "./alarm-defaults.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,GAGnB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAE/C,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/topic-alarms.d.ts

@@ -0,0 +1,26 @@
+import { type Alarm } from "aws-cdk-lib/aws-cloudwatch";
+import type { ITopic } from "aws-cdk-lib/aws-sns";
+import type { IConstruct } from "constructs";
+import type { AlarmDefinition } from "@composurecdk/cloudwatch";
+import { AlarmDefinitionBuilder } from "@composurecdk/cloudwatch";
+import type { TopicAlarmConfig } from "./alarm-config.js";
+/**
+ * Resolves the recommended alarm configuration into fully-resolved
+ * {@link AlarmDefinition}s for an SNS topic.
+ */
+export declare function resolveTopicAlarmDefinitions(topic: ITopic, config: TopicAlarmConfig | undefined): AlarmDefinition[];
+/**
+ * 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
+ */
+export declare function createTopicAlarms(scope: IConstruct, id: string, topic: ITopic, config: TopicAlarmConfig | false | undefined, customAlarms?: AlarmDefinitionBuilder<ITopic>[]): Record<string, Alarm>;
+//# sourceMappingURL=topic-alarms.d.ts.map

package/dist/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,mBAAmB,CAAC;AAM1D;;;GAGG;AACH,wBAAgB,4BAA4B,CAC1C,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,gBAAgB,GAAG,SAAS,GACnC,eAAe,EAAE,CA0CnB;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"}

package/dist/topic-alarms.js

@@ -0,0 +1,68 @@
+import { Duration } from "aws-cdk-lib";
+import { ComparisonOperator } from "aws-cdk-lib/aws-cloudwatch";
+import { createAlarms, resolveAlarmConfig } from "@composurecdk/cloudwatch";
+import { TOPIC_ALARM_DEFAULTS } from "./alarm-defaults.js";
+const METRIC_PERIOD = 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.
+ */
+export function resolveTopicAlarmDefinitions(topic, config) {
+    if (config?.enabled === false)
+        return [];
+    const definitions = [];
+    if (config?.numberOfNotificationsFailed !== false) {
+        const cfg = resolveAlarmConfig(config?.numberOfNotificationsFailed, TOPIC_ALARM_DEFAULTS.numberOfNotificationsFailed);
+        definitions.push({
+            key: "numberOfNotificationsFailed",
+            metric: topic.metricNumberOfNotificationsFailed({ period: METRIC_PERIOD }),
+            threshold: cfg.threshold,
+            comparisonOperator: 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 = resolveAlarmConfig(config?.numberOfNotificationsFilteredOutInvalidAttributes, TOPIC_ALARM_DEFAULTS.numberOfNotificationsFilteredOutInvalidAttributes);
+        definitions.push({
+            key: "numberOfNotificationsFilteredOutInvalidAttributes",
+            metric: topic.metricNumberOfNotificationsFilteredOutInvalidAttributes({
+                period: METRIC_PERIOD,
+            }),
+            threshold: cfg.threshold,
+            comparisonOperator: 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}.`,
+        });
+    }
+    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
+ */
+export function createTopicAlarms(scope, id, topic, config, customAlarms = []) {
+    if (config === false)
+        return {};
+    const enabled = config?.enabled ?? TOPIC_ALARM_DEFAULTS.enabled;
+    if (!enabled)
+        return {};
+    const recommended = resolveTopicAlarmDefinitions(topic, config);
+    const custom = customAlarms.map((b) => b.resolve(topic));
+    return createAlarms(scope, id, [...recommended, ...custom]);
+}
+//# sourceMappingURL=topic-alarms.js.map

package/dist/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/topic-builder.d.ts

@@ -0,0 +1,108 @@
+import { type Alarm } from "aws-cdk-lib/aws-cloudwatch";
+import { type ITopic, Topic, type TopicProps } from "aws-cdk-lib/aws-sns";
+import { type IConstruct } from "constructs";
+import { type IBuilder, type Lifecycle } from "@composurecdk/core";
+import { AlarmDefinitionBuilder } from "@composurecdk/cloudwatch";
+import type { TopicAlarmConfig } from "./alarm-config.js";
+/**
+ * Configuration properties for the SNS topic builder.
+ *
+ * Extends the CDK {@link TopicProps} with additional builder-specific options.
+ */
+export interface TopicBuilderProps extends TopicProps {
+    /**
+     * Configuration for AWS-recommended CloudWatch alarms.
+     *
+     * By default, the builder creates recommended alarms with sensible
+     * thresholds for every applicable metric. Individual alarms can be
+     * customized or disabled. Set to `false` to disable all 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#SNS
+     */
+    recommendedAlarms?: TopicAlarmConfig | false;
+}
+/**
+ * The build output of a {@link ITopicBuilder}. Contains the CDK constructs
+ * created during {@link Lifecycle.build}, keyed by role.
+ */
+export interface TopicBuilderResult {
+    /** The SNS topic construct created by the builder. */
+    topic: Topic;
+    /**
+     * CloudWatch alarms created for the topic, keyed by alarm name.
+     *
+     * Includes both AWS-recommended alarms and any custom alarms added
+     * via {@link ITopicBuilder.addAlarm}. Access individual alarms
+     * by key (e.g., `result.alarms.numberOfNotificationsFailed`).
+     *
+     * 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#SNS
+     */
+    alarms: Record<string, Alarm>;
+}
+/**
+ * A fluent builder for configuring and creating an AWS SNS topic.
+ *
+ * Each configuration property from the CDK {@link TopicProps} is exposed
+ * as an overloaded method: call with a value to set it (returns the builder
+ * for chaining), or call with no arguments to read the current value.
+ *
+ * The builder implements {@link Lifecycle}, so it can be used directly as a
+ * component in a {@link compose | composed system}. When built, it creates
+ * an SNS topic with the configured properties and returns a
+ * {@link TopicBuilderResult}.
+ *
+ * The builder also creates AWS-recommended CloudWatch alarms by default.
+ * Alarms can be customized or disabled via the `recommendedAlarms` property.
+ * Custom alarms can be added via the {@link addAlarm} method.
+ *
+ * @see https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_sns.Topic.html
+ *
+ * @example
+ * ```ts
+ * const alerts = createTopicBuilder()
+ *   .topicName("my-alerts")
+ *   .displayName("My Alert Topic");
+ * ```
+ */
+export type ITopicBuilder = IBuilder<TopicBuilderProps, TopicBuilder>;
+declare class TopicBuilder implements Lifecycle<TopicBuilderResult> {
+    props: Partial<TopicBuilderProps>;
+    private readonly customAlarms;
+    addAlarm(key: string, configure: (alarm: AlarmDefinitionBuilder<ITopic>) => AlarmDefinitionBuilder<ITopic>): this;
+    build(scope: IConstruct, id: string): TopicBuilderResult;
+}
+/**
+ * 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: [] },
+ * );
+ * ```
+ */
+export declare function createTopicBuilder(): ITopicBuilder;
+export {};
+//# sourceMappingURL=topic-builder.d.ts.map

package/dist/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,EAAE,KAAK,MAAM,EAAE,KAAK,EAAE,KAAK,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAC1E,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,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAI1D;;;;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;CAC/B;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,MAAM,aAAa,GAAG,QAAQ,CAAC,iBAAiB,EAAE,YAAY,CAAC,CAAC;AAEtE,cAAM,YAAa,YAAW,SAAS,CAAC,kBAAkB,CAAC;IACzD,KAAK,EAAE,OAAO,CAAC,iBAAiB,CAAC,CAAM;IACvC,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,kBAAkB;CAczD;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,kBAAkB,IAAI,aAAa,CAElD"}

package/dist/topic-builder.js

@@ -0,0 +1,52 @@
+import { Topic } from "aws-cdk-lib/aws-sns";
+import { Builder } from "@composurecdk/core";
+import { AlarmDefinitionBuilder } from "@composurecdk/cloudwatch";
+import { createTopicAlarms } from "./topic-alarms.js";
+import { TOPIC_DEFAULTS } from "./defaults.js";
+class TopicBuilder {
+    props = {};
+    customAlarms = [];
+    addAlarm(key, configure) {
+        this.customAlarms.push(configure(new AlarmDefinitionBuilder(key)));
+        return this;
+    }
+    build(scope, id) {
+        const { recommendedAlarms: alarmConfig, ...topicProps } = this.props;
+        const mergedProps = {
+            ...TOPIC_DEFAULTS,
+            ...topicProps,
+        };
+        const topic = new Topic(scope, id, mergedProps);
+        const alarms = createTopicAlarms(scope, id, topic, alarmConfig, this.customAlarms);
+        return { topic, alarms };
+    }
+}
+/**
+ * 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: [] },
+ * );
+ * ```
+ */
+export function createTopicBuilder() {
+    return Builder(TopicBuilder);
+}
+//# sourceMappingURL=topic-builder.js.map

package/dist/topic-builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"topic-builder.js","sourceRoot":"","sources":["../src/topic-builder.ts"],"names":[],"mappings":"AACA,OAAO,EAAe,KAAK,EAAmB,MAAM,qBAAqB,CAAC;AAE1E,OAAO,EAAE,OAAO,EAAiC,MAAM,oBAAoB,CAAC;AAC5E,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAElE,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AA0E/C,MAAM,YAAY;IAChB,KAAK,GAA+B,EAAE,CAAC;IACtB,YAAY,GAAqC,EAAE,CAAC;IAErE,QAAQ,CACN,GAAW,EACX,SAAoF;QAEpF,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,sBAAsB,CAAS,GAAG,CAAC,CAAC,CAAC,CAAC;QAC3E,OAAO,IAAI,CAAC;IACd,CAAC;IAED,KAAK,CAAC,KAAiB,EAAE,EAAU;QACjC,MAAM,EAAE,iBAAiB,EAAE,WAAW,EAAE,GAAG,UAAU,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC;QAErE,MAAM,WAAW,GAAG;YAClB,GAAG,cAAc;YACjB,GAAG,UAAU;SACO,CAAC;QAEvB,MAAM,KAAK,GAAG,IAAI,KAAK,CAAC,KAAK,EAAE,EAAE,EAAE,WAAW,CAAC,CAAC;QAEhD,MAAM,MAAM,GAAG,iBAAiB,CAAC,KAAK,EAAE,EAAE,EAAE,KAAK,EAAE,WAAW,EAAE,IAAI,CAAC,YAAY,CAAC,CAAC;QAEnF,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC;IAC3B,CAAC;CACF;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,UAAU,kBAAkB;IAChC,OAAO,OAAO,CAAkC,YAAY,CAAC,CAAC;AAChE,CAAC"}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@composurecdk/sns",
+  "version": "0.3.0",
+  "description": "Composable SNS topic builder with well-architected defaults",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/laazyj/composureCDK",
+    "directory": "packages/sns"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "clean": "rm -rf dist",
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "keywords": [],
+  "author": "Jason Duffett (https://github.com/laazyj)",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "peerDependencies": {
+    "@composurecdk/cloudwatch": "^0.3.0",
+    "@composurecdk/core": "^0.3.0",
+    "aws-cdk-lib": "^2.0.0",
+    "constructs": "^10.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "aws-cdk-lib": "^2.245.0",
+    "constructs": "^10.6.0",
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.2"
+  }
+}