@composurecdk/events 0.6.0

package/README.md

@@ -0,0 +1,229 @@
+# @composurecdk/events
+
+EventBridge rule builder for [ComposureCDK](../../README.md).
+
+This package provides a fluent builder for EventBridge rules with secure, AWS-recommended defaults. It wraps the CDK [Rule](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_events.Rule.html) construct — refer to the CDK documentation for the full set of configurable properties.
+
+## Rule Builder
+
+```ts
+import { createRuleBuilder } from "@composurecdk/events";
+import { Schedule } from "aws-cdk-lib/aws-events";
+import { Duration } from "aws-cdk-lib";
+
+const rule = createRuleBuilder()
+  .schedule(Schedule.rate(Duration.minutes(15)))
+  .description("Idle stopper")
+  .build(stack, "IdleStopperSchedule");
+```
+
+Every [RuleProps](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_events.RuleProps.html) property is available as a fluent setter on the builder. The builder requires at least one of `schedule` or `eventPattern` to be set — an EventBridge rule with neither is inert.
+
+`Schedule` and `Match` (used for event-pattern matching) are imported directly from `aws-cdk-lib/aws-events` — this package does not re-export them, matching the convention used elsewhere in the library (e.g. `Runtime` from `aws-cdk-lib/aws-lambda`).
+
+### Cross-component event bus
+
+The `eventBus` property accepts a `Resolvable<IEventBus>` so the rule can attach to a custom bus built by another component:
+
+```ts
+import { compose, ref } from "@composurecdk/core";
+
+compose(
+  {
+    bus: customEventBus,
+    rule: createRuleBuilder()
+      .eventBus(ref("bus", (r) => r.eventBus))
+      .eventPattern({ source: ["my.app"] }),
+  },
+  { bus: [], rule: ["bus"] },
+);
+```
+
+When omitted, the rule attaches to the account default bus, matching CDK's `RuleProps.eventBus` default.
+
+## Recommended Alarms
+
+The builder creates [AWS-recommended CloudWatch alarms](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#EventBridge) by default. No alarm actions are configured — access alarms from the build result, or use the `alarmActionsPolicy` from `@composurecdk/cloudwatch` to wire them to an SNS topic in one place.
+
+| Alarm                            | Metric                                      | Default threshold | Created when |
+| -------------------------------- | ------------------------------------------- | ----------------- | ------------ |
+| `failedInvocations`              | FailedInvocations (Sum, 1 min)              | > 0               | Always       |
+| `throttledRules`                 | ThrottledRules (Sum, 1 min)                 | > 0               | Always       |
+| `invocationsSentToDlq`           | InvocationsSentToDlq (Sum, 1 min)           | > 0               | Always[^dlq] |
+| `invocationsFailedToBeSentToDlq` | InvocationsFailedToBeSentToDlq (Sum, 1 min) | > 0               | Always[^dlq] |
+
+[^dlq]: The DLQ metrics only emit data when at least one target on the rule has a `deadLetterQueue` configured and EventBridge attempts redrive. `TreatMissingData` defaults to `notBreaching`, so the alarm stays quiet on rules without DLQs. Attach a DLQ via the matching target helper's `deadLetterQueue` option — see [Cross-component DLQ wiring](#cross-component-dlq-wiring) below, and the [EventBridge DLQ docs](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-rule-dlq.html).
+
+The defaults are exported as `RULE_ALARM_DEFAULTS` for visibility and testing:
+
+```ts
+import { RULE_ALARM_DEFAULTS } from "@composurecdk/events";
+```
+
+### Customizing thresholds
+
+Override individual alarm properties via `recommendedAlarms`. Unspecified fields keep their defaults.
+
+```ts
+const rule = createRuleBuilder()
+  .eventPattern({ source: ["my.app"] })
+  .recommendedAlarms({
+    failedInvocations: { 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({ throttledRules: false });
+```
+
+### Custom alarms
+
+Add custom alarms alongside the recommended ones via `addAlarm`. The callback receives an `AlarmDefinitionBuilder` typed to `IRule`, so the metric factory has access to the rule's properties. The Serverless Lens flags `RetryInvocationAttempts` as an early indicator of an undersized target — a good candidate for `addAlarm`:
+
+```ts
+import { Metric } from "aws-cdk-lib/aws-cloudwatch";
+import { Duration } from "aws-cdk-lib";
+
+createRuleBuilder()
+  .eventPattern({ source: ["my.app"] })
+  .addAlarm("retryAttempts", (alarm) =>
+    alarm
+      .metric(
+        (rule) =>
+          new Metric({
+            namespace: "AWS/Events",
+            metricName: "RetryInvocationAttempts",
+            dimensionsMap: { RuleName: rule.ruleName },
+            statistic: "Sum",
+            period: Duration.minutes(1),
+          }),
+      )
+      .threshold(10)
+      .greaterThan()
+      .description("Target is being undersized; retries are climbing."),
+  );
+```
+
+### Applying alarm actions
+
+Alarms are returned in the build result as `Record<string, Alarm>`:
+
+```ts
+const result = rule.build(stack, "MyRule");
+
+for (const alarm of Object.values(result.alarms)) {
+  alarm.addAlarmAction(new SnsAction(alertTopic));
+}
+```
+
+Or apply them stack-wide via `alarmActionsPolicy(stack, { defaults: { alarmActions: [new SnsAction(alertTopic)] } })` from `@composurecdk/cloudwatch` — same pattern used by the rest of the library, so a single SNS topic can fan out to function and rule alarms together.
+
+## Adding Targets
+
+Targets are registered via `addTarget(key, target)`, where `target` is a CDK [`IRuleTarget`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_events.IRuleTarget.html) (or a `Resolvable<IRuleTarget>` for cross-component wiring). Each target is exposed on `result.targets` under its key.
+
+```ts
+import { createRuleBuilder } from "@composurecdk/events";
+import { LambdaFunction } from "aws-cdk-lib/aws-events-targets";
+
+const result = createRuleBuilder()
+  .schedule(Schedule.rate(Duration.minutes(15)))
+  .addTarget("stopper", new LambdaFunction(idleStopperFn))
+  .build(stack, "IdleStopperSchedule");
+
+result.targets.stopper; // IRuleTarget
+```
+
+For cross-component wiring inside a [`compose`](../core/README.md) system, pass a `ref` and use the matching target helper from this package (see [Target Helpers](#target-helpers) below):
+
+```ts
+import { compose, ref } from "@composurecdk/core";
+import { createRuleBuilder, lambdaTarget } from "@composurecdk/events";
+import { createFunctionBuilder, type FunctionBuilderResult } from "@composurecdk/lambda";
+
+const system = compose(
+  {
+    stopper: createFunctionBuilder()./* ... */,
+    idleStopperSchedule: createRuleBuilder()
+      .schedule(Schedule.rate(Duration.minutes(15)))
+      .addTarget(
+        "stopper",
+        lambdaTarget(ref("stopper", (r: FunctionBuilderResult) => r.function)),
+      ),
+  },
+  { stopper: [], idleStopperSchedule: ["stopper"] },
+);
+```
+
+## Target Helpers
+
+This package ships small free-function helpers that wrap the corresponding [`aws-events-targets`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_events_targets-readme.html) constructs and accept a `Resolvable<I*>` for the underlying resource. Use them inside `addTarget` instead of constructing the CDK target classes directly — they make cross-component wiring with `ref(...)` work without an `afterBuild` hook.
+
+| Helper                     | Wraps                | Underlying resource |
+| -------------------------- | -------------------- | ------------------- |
+| `lambdaTarget`             | `LambdaFunction`     | `IFunction`         |
+| `sqsTarget`                | `SqsQueue`           | `IQueue`            |
+| `snsTarget`                | `SnsTopic`           | `ITopic`            |
+| `sfnStateMachineTarget`    | `SfnStateMachine`    | `IStateMachine`     |
+| `eventBusTarget`           | `EventBus`           | `IEventBus`         |
+| `cloudWatchLogGroupTarget` | `CloudWatchLogGroup` | `ILogGroup`         |
+
+The second argument is the matching CDK target props type (`LambdaFunctionProps`, `SqsQueueProps`, …) — refer to the CDK docs for available options. Common ones include `deadLetterQueue` (concrete `IQueue`), `retryAttempts`, `maxEventAge`, and target-specific input transforms (`event` / `input` / `message`).
+
+Other CDK target types (API Gateway, ECS task, Batch job, Kinesis, Firehose, AppSync, …) are not yet wrapped — pass them inline as a regular `IRuleTarget` until a wrapper helper lands.
+
+```ts
+import { compose, ref } from "@composurecdk/core";
+import {
+  createRuleBuilder,
+  lambdaTarget,
+  sqsTarget,
+} from "@composurecdk/events";
+import {
+  createFunctionBuilder,
+  type FunctionBuilderResult,
+} from "@composurecdk/lambda";
+
+compose(
+  {
+    handler: createFunctionBuilder()./* ... */,
+    rule: createRuleBuilder()
+      .eventPattern({ source: ["aws.s3"], detailType: ["Object Created"] })
+      .addTarget(
+        "primary",
+        lambdaTarget(ref("handler", (r: FunctionBuilderResult) => r.function), {
+          retryAttempts: 2,
+        }),
+      ),
+  },
+  { handler: [], rule: ["handler"] },
+);
+```
+
+### Cross-component DLQ wiring
+
+Each helper takes a single `Resolvable` for its primary resource. Secondary props such as `deadLetterQueue` accept the concrete CDK type (`IQueue` for most targets). When the DLQ is also a sibling-component output, construct the helper inside `ref().map()` and have the dependency component expose both the resource and the queue:
+
+```ts
+.addTarget(
+  "stopper",
+  ref<{ fn: IFunction; dlq: IQueue }>(
+    "stopperBundle",
+    (b) => lambdaTarget(b.fn, { deadLetterQueue: b.dlq }),
+  ),
+)
+```
+
+A dedicated DLQ component (`createQueueBuilder`-style) — and helpers that accept `Resolvable<IQueue>` for the DLQ directly — are out of scope for this PR; track as a follow-up if a use case emerges.

package/dist/defaults.d.ts

@@ -0,0 +1,12 @@
+import type { RuleProps } from "aws-cdk-lib/aws-events";
+/**
+ * Defaults applied to every EventBridge rule built with
+ * {@link createRuleBuilder}.
+ *
+ * Intentionally empty: the L2 {@link RuleProps} defaults already align with
+ * AWS recommendations (`enabled: true`, default account event bus). No
+ * additional secure default exists at this layer — DLQs are caller-owned and
+ * configured per target, not on the rule itself.
+ */
+export declare const RULE_DEFAULTS: Partial<RuleProps>;
+//# 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,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAExD;;;;;;;;GAQG;AACH,eAAO,MAAM,aAAa,EAAE,OAAO,CAAC,SAAS,CAAM,CAAC"}

package/dist/defaults.js

@@ -0,0 +1,11 @@
+/**
+ * Defaults applied to every EventBridge rule built with
+ * {@link createRuleBuilder}.
+ *
+ * Intentionally empty: the L2 {@link RuleProps} defaults already align with
+ * AWS recommendations (`enabled: true`, default account event bus). No
+ * additional secure default exists at this layer — DLQs are caller-owned and
+ * configured per target, not on the rule itself.
+ */
+export const RULE_DEFAULTS = {};
+//# 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;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,aAAa,GAAuB,EAAE,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export { createRuleBuilder, type IRuleBuilder, type RuleBuilderProps, type RuleBuilderResult, } from "./rule-builder.js";
+export { RULE_DEFAULTS } from "./defaults.js";
+export { type RuleAlarmConfig } from "./rule-alarm-config.js";
+export { RULE_ALARM_DEFAULTS } from "./rule-alarm-defaults.js";
+export { lambdaTarget } from "./targets/lambda-target.js";
+export { sqsTarget } from "./targets/sqs-target.js";
+export { snsTarget } from "./targets/sns-target.js";
+export { sfnStateMachineTarget } from "./targets/sfn-state-machine-target.js";
+export { eventBusTarget } from "./targets/event-bus-target.js";
+export { cloudWatchLogGroupTarget } from "./targets/cloud-watch-log-group-target.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,iBAAiB,EACjB,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,GACvB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAE,KAAK,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAC/D,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAC1D,OAAO,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AACpD,OAAO,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AACpD,OAAO,EAAE,qBAAqB,EAAE,MAAM,uCAAuC,CAAC;AAC9E,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAC/D,OAAO,EAAE,wBAAwB,EAAE,MAAM,2CAA2C,CAAC"}

package/dist/index.js

@@ -0,0 +1,10 @@
+export { createRuleBuilder, } from "./rule-builder.js";
+export { RULE_DEFAULTS } from "./defaults.js";
+export { RULE_ALARM_DEFAULTS } from "./rule-alarm-defaults.js";
+export { lambdaTarget } from "./targets/lambda-target.js";
+export { sqsTarget } from "./targets/sqs-target.js";
+export { snsTarget } from "./targets/sns-target.js";
+export { sfnStateMachineTarget } from "./targets/sfn-state-machine-target.js";
+export { eventBusTarget } from "./targets/event-bus-target.js";
+export { cloudWatchLogGroupTarget } from "./targets/cloud-watch-log-group-target.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,iBAAiB,GAIlB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAE9C,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAC/D,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAC1D,OAAO,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AACpD,OAAO,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AACpD,OAAO,EAAE,qBAAqB,EAAE,MAAM,uCAAuC,CAAC;AAC9E,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAC/D,OAAO,EAAE,wBAAwB,EAAE,MAAM,2CAA2C,CAAC"}

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

@@ -0,0 +1,58 @@
+import type { AlarmConfig } from "@composurecdk/cloudwatch";
+/**
+ * Controls which recommended alarms are created for an EventBridge rule.
+ * 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#EventBridge
+ * @see https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-monitoring-events-best-practices.html
+ */
+export interface RuleAlarmConfig {
+    /**
+     * 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 EventBridge fails to deliver matched events to a target.
+     *
+     * Metric: `AWS/Events FailedInvocations`, statistic Sum, period 1 minute.
+     * Default threshold: > 0 failures.
+     *
+     * @see https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-monitoring-events-best-practices.html
+     */
+    failedInvocations?: AlarmConfig | false;
+    /**
+     * Alarm when invocations are throttled (e.g. by service-side concurrency
+     * limits or quota).
+     *
+     * Metric: `AWS/Events ThrottledRules`, statistic Sum, period 1 minute.
+     * Default threshold: > 0 throttles.
+     */
+    throttledRules?: AlarmConfig | false;
+    /**
+     * Alarm when events that could not be delivered are sent to a target's
+     * dead-letter queue. Only emits data when at least one target has a DLQ
+     * attached and EventBridge attempts redrive; {@link TreatMissingData.NOT_BREACHING}
+     * keeps it quiet otherwise.
+     *
+     * Metric: `AWS/Events InvocationsSentToDlq`, statistic Sum, period 1 minute.
+     * Default threshold: > 0 redrives.
+     *
+     * @see https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-rule-dlq.html
+     */
+    invocationsSentToDlq?: AlarmConfig | false;
+    /**
+     * Alarm when events could not even be delivered to a dead-letter queue.
+     * Indicates a misconfiguration (e.g. missing EventBridge permission on
+     * the DLQ) that results in event loss.
+     *
+     * Metric: `AWS/Events InvocationsFailedToBeSentToDlq`, statistic Sum,
+     * period 1 minute.
+     * Default threshold: > 0 failed redrives.
+     */
+    invocationsFailedToBeSentToDlq?: AlarmConfig | false;
+}
+//# sourceMappingURL=rule-alarm-config.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"rule-alarm-config.d.ts","sourceRoot":"","sources":["../src/rule-alarm-config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAE5D;;;;;;;;GAQG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;;;;;;OAOG;IACH,iBAAiB,CAAC,EAAE,WAAW,GAAG,KAAK,CAAC;IAExC;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,WAAW,GAAG,KAAK,CAAC;IAErC;;;;;;;;;;OAUG;IACH,oBAAoB,CAAC,EAAE,WAAW,GAAG,KAAK,CAAC;IAE3C;;;;;;;;OAQG;IACH,8BAA8B,CAAC,EAAE,WAAW,GAAG,KAAK,CAAC;CACtD"}

package/dist/rule-alarm-config.js

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

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

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

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

@@ -0,0 +1,16 @@
+import type { AlarmConfigDefaults } from "@composurecdk/cloudwatch";
+interface RuleAlarmDefaults {
+    enabled: true;
+    failedInvocations: AlarmConfigDefaults;
+    throttledRules: AlarmConfigDefaults;
+    invocationsSentToDlq: AlarmConfigDefaults;
+    invocationsFailedToBeSentToDlq: AlarmConfigDefaults;
+}
+/**
+ * AWS-recommended default alarm configuration for EventBridge rules.
+ *
+ * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#EventBridge
+ */
+export declare const RULE_ALARM_DEFAULTS: RuleAlarmDefaults;
+export {};
+//# sourceMappingURL=rule-alarm-defaults.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"rule-alarm-defaults.d.ts","sourceRoot":"","sources":["../src/rule-alarm-defaults.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAEpE,UAAU,iBAAiB;IACzB,OAAO,EAAE,IAAI,CAAC;IACd,iBAAiB,EAAE,mBAAmB,CAAC;IACvC,cAAc,EAAE,mBAAmB,CAAC;IACpC,oBAAoB,EAAE,mBAAmB,CAAC;IAC1C,8BAA8B,EAAE,mBAAmB,CAAC;CACrD;AAED;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,EAAE,iBAkCjC,CAAC"}

package/dist/rule-alarm-defaults.js

@@ -0,0 +1,38 @@
+import { TreatMissingData } from "aws-cdk-lib/aws-cloudwatch";
+/**
+ * AWS-recommended default alarm configuration for EventBridge rules.
+ *
+ * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#EventBridge
+ */
+export const RULE_ALARM_DEFAULTS = {
+    enabled: true,
+    /** Any failure to deliver a matched event is worth investigating; threshold 0. */
+    failedInvocations: {
+        threshold: 0,
+        evaluationPeriods: 1,
+        datapointsToAlarm: 1,
+        treatMissingData: TreatMissingData.NOT_BREACHING,
+    },
+    /** Any throttling indicates a quota or downstream-concurrency problem; threshold 0. */
+    throttledRules: {
+        threshold: 0,
+        evaluationPeriods: 1,
+        datapointsToAlarm: 1,
+        treatMissingData: TreatMissingData.NOT_BREACHING,
+    },
+    /** Any redrive to a target DLQ indicates a delivery failure worth investigating; threshold 0. */
+    invocationsSentToDlq: {
+        threshold: 0,
+        evaluationPeriods: 1,
+        datapointsToAlarm: 1,
+        treatMissingData: TreatMissingData.NOT_BREACHING,
+    },
+    /** Any failure to redrive to a DLQ means event loss; threshold 0. */
+    invocationsFailedToBeSentToDlq: {
+        threshold: 0,
+        evaluationPeriods: 1,
+        datapointsToAlarm: 1,
+        treatMissingData: TreatMissingData.NOT_BREACHING,
+    },
+};
+//# sourceMappingURL=rule-alarm-defaults.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"rule-alarm-defaults.js","sourceRoot":"","sources":["../src/rule-alarm-defaults.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAW9D;;;;GAIG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAsB;IACpD,OAAO,EAAE,IAAI;IAEb,kFAAkF;IAClF,iBAAiB,EAAE;QACjB,SAAS,EAAE,CAAC;QACZ,iBAAiB,EAAE,CAAC;QACpB,iBAAiB,EAAE,CAAC;QACpB,gBAAgB,EAAE,gBAAgB,CAAC,aAAa;KACjD;IAED,uFAAuF;IACvF,cAAc,EAAE;QACd,SAAS,EAAE,CAAC;QACZ,iBAAiB,EAAE,CAAC;QACpB,iBAAiB,EAAE,CAAC;QACpB,gBAAgB,EAAE,gBAAgB,CAAC,aAAa;KACjD;IAED,iGAAiG;IACjG,oBAAoB,EAAE;QACpB,SAAS,EAAE,CAAC;QACZ,iBAAiB,EAAE,CAAC;QACpB,iBAAiB,EAAE,CAAC;QACpB,gBAAgB,EAAE,gBAAgB,CAAC,aAAa;KACjD;IAED,qEAAqE;IACrE,8BAA8B,EAAE;QAC9B,SAAS,EAAE,CAAC;QACZ,iBAAiB,EAAE,CAAC;QACpB,iBAAiB,EAAE,CAAC;QACpB,gBAAgB,EAAE,gBAAgB,CAAC,aAAa;KACjD;CACF,CAAC"}

package/dist/rule-alarms.d.ts

@@ -0,0 +1,28 @@
+import { type Alarm } from "aws-cdk-lib/aws-cloudwatch";
+import type { IRule } from "aws-cdk-lib/aws-events";
+import type { IConstruct } from "constructs";
+import type { AlarmDefinition } from "@composurecdk/cloudwatch";
+import { AlarmDefinitionBuilder } from "@composurecdk/cloudwatch";
+import type { RuleAlarmConfig } from "./rule-alarm-config.js";
+/**
+ * Resolves the recommended alarm configuration into fully-resolved
+ * {@link AlarmDefinition}s for an EventBridge rule.
+ *
+ * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#EventBridge
+ */
+export declare function resolveRuleAlarmDefinitions(rule: IRule, config: RuleAlarmConfig | undefined): AlarmDefinition[];
+/**
+ * Creates AWS-recommended CloudWatch alarms for an EventBridge rule,
+ * 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 rule - The EventBridge rule 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#EventBridge
+ */
+export declare function createRuleAlarms(scope: IConstruct, id: string, rule: IRule, config: RuleAlarmConfig | false | undefined, customAlarms?: AlarmDefinitionBuilder<IRule>[]): Record<string, Alarm>;
+//# sourceMappingURL=rule-alarms.d.ts.map

package/dist/rule-alarms.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rule-alarms.d.ts","sourceRoot":"","sources":["../src/rule-alarms.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,KAAK,EAA8B,MAAM,4BAA4B,CAAC;AACpF,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,wBAAwB,CAAC;AACpD,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,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAgB9D;;;;;GAKG;AACH,wBAAgB,2BAA2B,CACzC,IAAI,EAAE,KAAK,EACX,MAAM,EAAE,eAAe,GAAG,SAAS,GAClC,eAAe,EAAE,CA2EnB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,UAAU,EACjB,EAAE,EAAE,MAAM,EACV,IAAI,EAAE,KAAK,EACX,MAAM,EAAE,eAAe,GAAG,KAAK,GAAG,SAAS,EAC3C,YAAY,GAAE,sBAAsB,CAAC,KAAK,CAAC,EAAO,GACjD,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAUvB"}

package/dist/rule-alarms.js

@@ -0,0 +1,107 @@
+import { Duration } from "aws-cdk-lib";
+import { ComparisonOperator, Metric } from "aws-cdk-lib/aws-cloudwatch";
+import { createAlarms, resolveAlarmConfig } from "@composurecdk/cloudwatch";
+import { RULE_ALARM_DEFAULTS } from "./rule-alarm-defaults.js";
+const METRIC_PERIOD = Duration.minutes(1);
+const METRIC_PERIOD_LABEL = `${String(METRIC_PERIOD.toMinutes())} minute`;
+function ruleMetric(rule, metricName) {
+    return new Metric({
+        namespace: "AWS/Events",
+        metricName,
+        dimensionsMap: { RuleName: rule.ruleName },
+        statistic: "Sum",
+        period: METRIC_PERIOD,
+    });
+}
+/**
+ * Resolves the recommended alarm configuration into fully-resolved
+ * {@link AlarmDefinition}s for an EventBridge rule.
+ *
+ * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#EventBridge
+ */
+export function resolveRuleAlarmDefinitions(rule, config) {
+    if (config?.enabled === false)
+        return [];
+    const definitions = [];
+    if (config?.failedInvocations !== false) {
+        const cfg = resolveAlarmConfig(config?.failedInvocations, RULE_ALARM_DEFAULTS.failedInvocations);
+        definitions.push({
+            key: "failedInvocations",
+            alarmName: cfg.alarmName,
+            metric: ruleMetric(rule, "FailedInvocations"),
+            threshold: cfg.threshold,
+            comparisonOperator: ComparisonOperator.GREATER_THAN_THRESHOLD,
+            evaluationPeriods: cfg.evaluationPeriods,
+            datapointsToAlarm: cfg.datapointsToAlarm,
+            treatMissingData: cfg.treatMissingData,
+            description: `EventBridge rule is failing to invoke targets. Threshold: > ${String(cfg.threshold)} failures in ${METRIC_PERIOD_LABEL}.`,
+        });
+    }
+    if (config?.throttledRules !== false) {
+        const cfg = resolveAlarmConfig(config?.throttledRules, RULE_ALARM_DEFAULTS.throttledRules);
+        definitions.push({
+            key: "throttledRules",
+            alarmName: cfg.alarmName,
+            metric: ruleMetric(rule, "ThrottledRules"),
+            threshold: cfg.threshold,
+            comparisonOperator: ComparisonOperator.GREATER_THAN_THRESHOLD,
+            evaluationPeriods: cfg.evaluationPeriods,
+            datapointsToAlarm: cfg.datapointsToAlarm,
+            treatMissingData: cfg.treatMissingData,
+            description: `EventBridge rule is being throttled, indicating quota or downstream concurrency limits. Threshold: > ${String(cfg.threshold)} throttles in ${METRIC_PERIOD_LABEL}.`,
+        });
+    }
+    if (config?.invocationsSentToDlq !== false) {
+        const cfg = resolveAlarmConfig(config?.invocationsSentToDlq, RULE_ALARM_DEFAULTS.invocationsSentToDlq);
+        definitions.push({
+            key: "invocationsSentToDlq",
+            alarmName: cfg.alarmName,
+            metric: ruleMetric(rule, "InvocationsSentToDlq"),
+            threshold: cfg.threshold,
+            comparisonOperator: ComparisonOperator.GREATER_THAN_THRESHOLD,
+            evaluationPeriods: cfg.evaluationPeriods,
+            datapointsToAlarm: cfg.datapointsToAlarm,
+            treatMissingData: cfg.treatMissingData,
+            description: `EventBridge rule is redriving events to a target dead-letter queue. Threshold: > ${String(cfg.threshold)} redrives in ${METRIC_PERIOD_LABEL}.`,
+        });
+    }
+    if (config?.invocationsFailedToBeSentToDlq !== false) {
+        const cfg = resolveAlarmConfig(config?.invocationsFailedToBeSentToDlq, RULE_ALARM_DEFAULTS.invocationsFailedToBeSentToDlq);
+        definitions.push({
+            key: "invocationsFailedToBeSentToDlq",
+            alarmName: cfg.alarmName,
+            metric: ruleMetric(rule, "InvocationsFailedToBeSentToDlq"),
+            threshold: cfg.threshold,
+            comparisonOperator: ComparisonOperator.GREATER_THAN_THRESHOLD,
+            evaluationPeriods: cfg.evaluationPeriods,
+            datapointsToAlarm: cfg.datapointsToAlarm,
+            treatMissingData: cfg.treatMissingData,
+            description: `EventBridge rule failed to redrive an event to a target dead-letter queue; events may be lost. Threshold: > ${String(cfg.threshold)} failed redrives in ${METRIC_PERIOD_LABEL}.`,
+        });
+    }
+    return definitions;
+}
+/**
+ * Creates AWS-recommended CloudWatch alarms for an EventBridge rule,
+ * 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 rule - The EventBridge rule 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#EventBridge
+ */
+export function createRuleAlarms(scope, id, rule, config, customAlarms = []) {
+    if (config === false)
+        return {};
+    const enabled = config?.enabled ?? RULE_ALARM_DEFAULTS.enabled;
+    if (!enabled)
+        return {};
+    const recommended = resolveRuleAlarmDefinitions(rule, config);
+    const custom = customAlarms.map((b) => b.resolve(rule));
+    return createAlarms(scope, id, [...recommended, ...custom]);
+}
+//# sourceMappingURL=rule-alarms.js.map

package/dist/rule-alarms.js.map

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

package/dist/rule-builder.d.ts

@@ -0,0 +1,143 @@
+import { type Alarm } from "aws-cdk-lib/aws-cloudwatch";
+import { type IEventBus, type IRule, type IRuleTarget, Rule, type RuleProps } from "aws-cdk-lib/aws-events";
+import { type IConstruct } from "constructs";
+import { COPY_STATE, type IBuilder, type Lifecycle, type Resolvable } from "@composurecdk/core";
+import { AlarmDefinitionBuilder } from "@composurecdk/cloudwatch";
+import type { RuleAlarmConfig } from "./rule-alarm-config.js";
+/**
+ * Configuration properties for the EventBridge rule builder.
+ *
+ * Extends the CDK {@link RuleProps} but accepts a {@link Resolvable} for
+ * `eventBus` so the rule can be wired to a sibling component (or a custom
+ * event bus built elsewhere) via {@link ref} inside a {@link compose}d
+ * system. `targets` is excluded — use {@link IRuleBuilder.addTarget} so each
+ * target can carry its own `Resolvable` and be exposed in the build result.
+ */
+export interface RuleBuilderProps extends Omit<RuleProps, "targets" | "eventBus"> {
+    /**
+     * The event bus the rule listens on. Accepts a concrete {@link IEventBus} or
+     * a {@link Ref} to another component's output. When omitted, the rule
+     * attaches to the account default bus, matching CDK's `RuleProps.eventBus`
+     * default.
+     */
+    eventBus?: Resolvable<IEventBus>;
+    /**
+     * 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 apply them
+     * via the {@link alarmActionsPolicy} from `@composurecdk/cloudwatch`.
+     *
+     * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#EventBridge
+     */
+    recommendedAlarms?: RuleAlarmConfig | false;
+}
+/**
+ * The build output of an {@link IRuleBuilder}. Contains the CDK constructs
+ * created during {@link Lifecycle.build}, keyed by role.
+ */
+export interface RuleBuilderResult {
+    /** The EventBridge rule construct created by the builder. */
+    rule: Rule;
+    /**
+     * CloudWatch alarms created for the rule, keyed by alarm key.
+     *
+     * Includes both AWS-recommended alarms and any custom alarms added via
+     * {@link IRuleBuilder.addAlarm}. No alarm actions are configured —
+     * apply them via the result or an {@link alarmActionsPolicy}.
+     */
+    alarms: Record<string, Alarm>;
+    /**
+     * Resolved {@link IRuleTarget}s registered via
+     * {@link IRuleBuilder.addTarget}, keyed by the key passed to that call.
+     *
+     * Always present — `{}` when no targets were added.
+     */
+    targets: Record<string, IRuleTarget>;
+}
+/**
+ * A fluent builder for configuring and creating an AWS EventBridge rule.
+ *
+ * Each configuration property from the CDK {@link RuleProps} 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
+ * EventBridge rule with the configured properties and returns a
+ * {@link RuleBuilderResult}.
+ *
+ * Targets are registered via {@link addTarget} and accept a
+ * {@link Resolvable}, so cross-component wiring (a sibling Lambda, queue,
+ * topic, …) flows through the same {@link Ref} machinery as everything else.
+ *
+ * @see https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_events.Rule.html
+ *
+ * @example
+ * ```ts
+ * import { Schedule } from "aws-cdk-lib/aws-events";
+ * import { Duration } from "aws-cdk-lib";
+ *
+ * const rule = createRuleBuilder()
+ *   .schedule(Schedule.rate(Duration.minutes(15)))
+ *   .description("Idle stopper")
+ *   .addTarget("stopper", lambdaTarget(idleStopperFn));
+ * ```
+ */
+export type IRuleBuilder = IBuilder<RuleBuilderProps, RuleBuilder>;
+declare class RuleBuilder implements Lifecycle<RuleBuilderResult> {
+    #private;
+    props: Partial<RuleBuilderProps>;
+    /**
+     * Register a custom CloudWatch alarm on the rule. The configure callback
+     * receives an {@link AlarmDefinitionBuilder} typed to {@link IRule} so the
+     * metric factory has access to the rule's properties.
+     */
+    addAlarm(key: string, configure: (alarm: AlarmDefinitionBuilder<IRule>) => AlarmDefinitionBuilder<IRule>): this;
+    /**
+     * Register a target to be attached to the rule at build time.
+     *
+     * Accepts any concrete {@link IRuleTarget} (the lightweight helpers in
+     * `./targets/` produce these) or a {@link Resolvable} so targets that wire
+     * cross-component references can be declared at configuration time. The
+     * resolved target is exposed on {@link RuleBuilderResult.targets} under
+     * `key`.
+     */
+    addTarget(key: string, target: Resolvable<IRuleTarget>): this;
+    build(scope: IConstruct, id: string, context?: Record<string, object>): RuleBuilderResult;
+    /** Deep-clones accumulator state so `.copy()` produces an independent builder. */
+    [COPY_STATE](next: RuleBuilder): void;
+}
+/**
+ * Creates a new {@link IRuleBuilder} for configuring an AWS EventBridge rule.
+ *
+ * This is the entry point for defining an EventBridge rule component. The
+ * returned builder exposes every {@link RuleBuilderProps} property as a
+ * fluent setter/getter and implements {@link Lifecycle} for use with
+ * {@link compose}.
+ *
+ * @example
+ * ```ts
+ * import { compose, ref } from "@composurecdk/core";
+ * import { createRuleBuilder, lambdaTarget } from "@composurecdk/events";
+ * import { Schedule } from "aws-cdk-lib/aws-events";
+ * import { Duration } from "aws-cdk-lib";
+ *
+ * const system = compose(
+ *   {
+ *     stopper: createFunctionBuilder()...,
+ *     idleStopperSchedule: createRuleBuilder()
+ *       .schedule(Schedule.rate(Duration.minutes(15)))
+ *       .addTarget("stopper", lambdaTarget(ref("stopper", (r) => r.function))),
+ *   },
+ *   { stopper: [], idleStopperSchedule: ["stopper"] },
+ * );
+ * ```
+ */
+export declare function createRuleBuilder(): IRuleBuilder;
+export {};
+//# sourceMappingURL=rule-builder.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"rule-builder.d.ts","sourceRoot":"","sources":["../src/rule-builder.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,KAAK,EAAE,MAAM,4BAA4B,CAAC;AACxD,OAAO,EACL,KAAK,SAAS,EACd,KAAK,KAAK,EACV,KAAK,WAAW,EAChB,IAAI,EACJ,KAAK,SAAS,EACf,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EAEL,UAAU,EACV,KAAK,QAAQ,EACb,KAAK,SAAS,EAEd,KAAK,UAAU,EAChB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAElE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAG9D;;;;;;;;GAQG;AACH,MAAM,WAAW,gBAAiB,SAAQ,IAAI,CAAC,SAAS,EAAE,SAAS,GAAG,UAAU,CAAC;IAC/E;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,UAAU,CAAC,SAAS,CAAC,CAAC;IAEjC;;;;;;;;;;;;OAYG;IACH,iBAAiB,CAAC,EAAE,eAAe,GAAG,KAAK,CAAC;CAC7C;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,6DAA6D;IAC7D,IAAI,EAAE,IAAI,CAAC;IAEX;;;;;;OAMG;IACH,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IAE9B;;;;;OAKG;IACH,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;CACtC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,MAAM,MAAM,YAAY,GAAG,QAAQ,CAAC,gBAAgB,EAAE,WAAW,CAAC,CAAC;AAOnE,cAAM,WAAY,YAAW,SAAS,CAAC,iBAAiB,CAAC;;IACvD,KAAK,EAAE,OAAO,CAAC,gBAAgB,CAAC,CAAM;IAItC;;;;OAIG;IACH,QAAQ,CACN,GAAG,EAAE,MAAM,EACX,SAAS,EAAE,CAAC,KAAK,EAAE,sBAAsB,CAAC,KAAK,CAAC,KAAK,sBAAsB,CAAC,KAAK,CAAC,GACjF,IAAI;IAKP;;;;;;;;OAQG;IACH,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,CAAC,WAAW,CAAC,GAAG,IAAI;IAU7D,KAAK,CAAC,KAAK,EAAE,UAAU,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,iBAAiB;IA+BzF,kFAAkF;IAClF,CAAC,UAAU,CAAC,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI;CAItC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,iBAAiB,IAAI,YAAY,CAGhD"}

package/dist/rule-builder.js

@@ -0,0 +1,93 @@
+import { Rule, } from "aws-cdk-lib/aws-events";
+import { Builder, COPY_STATE, resolve, } from "@composurecdk/core";
+import { AlarmDefinitionBuilder } from "@composurecdk/cloudwatch";
+import { RULE_DEFAULTS } from "./defaults.js";
+import { createRuleAlarms } from "./rule-alarms.js";
+class RuleBuilder {
+    props = {};
+    #customAlarms = [];
+    #targets = [];
+    /**
+     * Register a custom CloudWatch alarm on the rule. The configure callback
+     * receives an {@link AlarmDefinitionBuilder} typed to {@link IRule} so the
+     * metric factory has access to the rule's properties.
+     */
+    addAlarm(key, configure) {
+        this.#customAlarms.push(configure(new AlarmDefinitionBuilder(key)));
+        return this;
+    }
+    /**
+     * Register a target to be attached to the rule at build time.
+     *
+     * Accepts any concrete {@link IRuleTarget} (the lightweight helpers in
+     * `./targets/` produce these) or a {@link Resolvable} so targets that wire
+     * cross-component references can be declared at configuration time. The
+     * resolved target is exposed on {@link RuleBuilderResult.targets} under
+     * `key`.
+     */
+    addTarget(key, target) {
+        if (this.#targets.some((t) => t.key === key)) {
+            throw new Error(`RuleBuilder.addTarget: duplicate key "${key}". Each target must use a unique key.`);
+        }
+        this.#targets.push({ key, target });
+        return this;
+    }
+    build(scope, id, context) {
+        const ctx = context ?? {};
+        const { eventBus, recommendedAlarms: alarmConfig, ...rest } = this.props;
+        if (rest.schedule === undefined && rest.eventPattern === undefined) {
+            throw new Error(`RuleBuilder "${id}": at least one of .schedule(...) or .eventPattern(...) must be set. ` +
+                "An EventBridge rule with neither is inert and never matches.");
+        }
+        const mergedProps = {
+            ...RULE_DEFAULTS,
+            ...rest,
+            ...(eventBus !== undefined && { eventBus: resolve(eventBus, ctx) }),
+        };
+        const rule = new Rule(scope, id, mergedProps);
+        const targets = {};
+        for (const entry of this.#targets) {
+            const resolved = resolve(entry.target, ctx);
+            rule.addTarget(resolved);
+            targets[entry.key] = resolved;
+        }
+        const alarms = createRuleAlarms(scope, id, rule, alarmConfig, this.#customAlarms);
+        return { rule, alarms, targets };
+    }
+    /** Deep-clones accumulator state so `.copy()` produces an independent builder. */
+    [COPY_STATE](next) {
+        next.#targets.push(...this.#targets);
+        next.#customAlarms.push(...this.#customAlarms);
+    }
+}
+/**
+ * Creates a new {@link IRuleBuilder} for configuring an AWS EventBridge rule.
+ *
+ * This is the entry point for defining an EventBridge rule component. The
+ * returned builder exposes every {@link RuleBuilderProps} property as a
+ * fluent setter/getter and implements {@link Lifecycle} for use with
+ * {@link compose}.
+ *
+ * @example
+ * ```ts
+ * import { compose, ref } from "@composurecdk/core";
+ * import { createRuleBuilder, lambdaTarget } from "@composurecdk/events";
+ * import { Schedule } from "aws-cdk-lib/aws-events";
+ * import { Duration } from "aws-cdk-lib";
+ *
+ * const system = compose(
+ *   {
+ *     stopper: createFunctionBuilder()...,
+ *     idleStopperSchedule: createRuleBuilder()
+ *       .schedule(Schedule.rate(Duration.minutes(15)))
+ *       .addTarget("stopper", lambdaTarget(ref("stopper", (r) => r.function))),
+ *   },
+ *   { stopper: [], idleStopperSchedule: ["stopper"] },
+ * );
+ * ```
+ */
+export function createRuleBuilder() {
+    // eslint-disable-next-line composurecdk/builder-must-be-tagged -- AWS::Events::Rule has no Tags property
+    return Builder(RuleBuilder);
+}
+//# sourceMappingURL=rule-builder.js.map

package/dist/rule-builder.js.map

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

package/dist/targets/cloud-watch-log-group-target.d.ts

@@ -0,0 +1,16 @@
+import type { IRuleTarget } from "aws-cdk-lib/aws-events";
+import { type LogGroupProps } from "aws-cdk-lib/aws-events-targets";
+import type { ILogGroup } from "aws-cdk-lib/aws-logs";
+import { type Resolvable } from "@composurecdk/core";
+/**
+ * Wraps a CloudWatch log group as an EventBridge {@link IRuleTarget},
+ * deferring resolution if the log group is a {@link Ref} to a sibling
+ * component's output.
+ *
+ * Mirrors the {@link CloudWatchLogGroup} target from `aws-events-targets`,
+ * useful for audit / debug logging. `props` accepts
+ * {@link LogGroupProps.logEvent} (preferred over the deprecated `event`)
+ * to control the log payload, plus the inherited DLQ/retry options.
+ */
+export declare function cloudWatchLogGroupTarget(logGroup: Resolvable<ILogGroup>, props?: LogGroupProps): Resolvable<IRuleTarget>;
+//# sourceMappingURL=cloud-watch-log-group-target.d.ts.map

package/dist/targets/cloud-watch-log-group-target.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloud-watch-log-group-target.d.ts","sourceRoot":"","sources":["../../src/targets/cloud-watch-log-group-target.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAsB,KAAK,aAAa,EAAE,MAAM,gCAAgC,CAAC;AACxF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAS,KAAK,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAE5D;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,UAAU,CAAC,SAAS,CAAC,EAC/B,KAAK,CAAC,EAAE,aAAa,GACpB,UAAU,CAAC,WAAW,CAAC,CAKzB"}

package/dist/targets/cloud-watch-log-group-target.js

@@ -0,0 +1,19 @@
+import { CloudWatchLogGroup } from "aws-cdk-lib/aws-events-targets";
+import { isRef } from "@composurecdk/core";
+/**
+ * Wraps a CloudWatch log group as an EventBridge {@link IRuleTarget},
+ * deferring resolution if the log group is a {@link Ref} to a sibling
+ * component's output.
+ *
+ * Mirrors the {@link CloudWatchLogGroup} target from `aws-events-targets`,
+ * useful for audit / debug logging. `props` accepts
+ * {@link LogGroupProps.logEvent} (preferred over the deprecated `event`)
+ * to control the log payload, plus the inherited DLQ/retry options.
+ */
+export function cloudWatchLogGroupTarget(logGroup, props) {
+    if (isRef(logGroup)) {
+        return logGroup.map((resolved) => new CloudWatchLogGroup(resolved, props));
+    }
+    return new CloudWatchLogGroup(logGroup, props);
+}
+//# sourceMappingURL=cloud-watch-log-group-target.js.map

package/dist/targets/cloud-watch-log-group-target.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloud-watch-log-group-target.js","sourceRoot":"","sources":["../../src/targets/cloud-watch-log-group-target.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,EAAsB,MAAM,gCAAgC,CAAC;AAExF,OAAO,EAAE,KAAK,EAAmB,MAAM,oBAAoB,CAAC;AAE5D;;;;;;;;;GASG;AACH,MAAM,UAAU,wBAAwB,CACtC,QAA+B,EAC/B,KAAqB;IAErB,IAAI,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC;QACpB,OAAO,QAAQ,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,IAAI,kBAAkB,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC,CAAC;IAC7E,CAAC;IACD,OAAO,IAAI,kBAAkB,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;AACjD,CAAC"}

package/dist/targets/event-bus-target.d.ts

@@ -0,0 +1,16 @@
+import type { IEventBus, IRuleTarget } from "aws-cdk-lib/aws-events";
+import { type EventBusProps } from "aws-cdk-lib/aws-events-targets";
+import { type Resolvable } from "@composurecdk/core";
+/**
+ * Wraps an EventBridge bus as an {@link IRuleTarget}, deferring resolution
+ * if the bus is a {@link Ref} to a sibling component's output.
+ *
+ * Mirrors the {@link EventBusTarget} target from `aws-events-targets` —
+ * useful for cross-bus or cross-account routing. `props` accepts
+ * {@link EventBusProps.role} (otherwise CDK creates one) and a per-target
+ * `deadLetterQueue`. Note: bus targets do **not** support retry policy
+ * configuration, per CDK's {@link EventBusProps} (it intentionally does not
+ * extend the retry base).
+ */
+export declare function eventBusTarget(bus: Resolvable<IEventBus>, props?: EventBusProps): Resolvable<IRuleTarget>;
+//# sourceMappingURL=event-bus-target.d.ts.map

package/dist/targets/event-bus-target.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-bus-target.d.ts","sourceRoot":"","sources":["../../src/targets/event-bus-target.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACrE,OAAO,EAA8B,KAAK,aAAa,EAAE,MAAM,gCAAgC,CAAC;AAChG,OAAO,EAAS,KAAK,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAE5D;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAC5B,GAAG,EAAE,UAAU,CAAC,SAAS,CAAC,EAC1B,KAAK,CAAC,EAAE,aAAa,GACpB,UAAU,CAAC,WAAW,CAAC,CAGzB"}

package/dist/targets/event-bus-target.js

@@ -0,0 +1,19 @@
+import { EventBus as EventBusTarget } from "aws-cdk-lib/aws-events-targets";
+import { isRef } from "@composurecdk/core";
+/**
+ * Wraps an EventBridge bus as an {@link IRuleTarget}, deferring resolution
+ * if the bus is a {@link Ref} to a sibling component's output.
+ *
+ * Mirrors the {@link EventBusTarget} target from `aws-events-targets` —
+ * useful for cross-bus or cross-account routing. `props` accepts
+ * {@link EventBusProps.role} (otherwise CDK creates one) and a per-target
+ * `deadLetterQueue`. Note: bus targets do **not** support retry policy
+ * configuration, per CDK's {@link EventBusProps} (it intentionally does not
+ * extend the retry base).
+ */
+export function eventBusTarget(bus, props) {
+    if (isRef(bus))
+        return bus.map((resolved) => new EventBusTarget(resolved, props));
+    return new EventBusTarget(bus, props);
+}
+//# sourceMappingURL=event-bus-target.js.map

package/dist/targets/event-bus-target.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-bus-target.js","sourceRoot":"","sources":["../../src/targets/event-bus-target.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,IAAI,cAAc,EAAsB,MAAM,gCAAgC,CAAC;AAChG,OAAO,EAAE,KAAK,EAAmB,MAAM,oBAAoB,CAAC;AAE5D;;;;;;;;;;GAUG;AACH,MAAM,UAAU,cAAc,CAC5B,GAA0B,EAC1B,KAAqB;IAErB,IAAI,KAAK,CAAC,GAAG,CAAC;QAAE,OAAO,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,IAAI,cAAc,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC,CAAC;IAClF,OAAO,IAAI,cAAc,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;AACxC,CAAC"}

package/dist/targets/lambda-target.d.ts

@@ -0,0 +1,31 @@
+import type { IRuleTarget } from "aws-cdk-lib/aws-events";
+import { type LambdaFunctionProps } from "aws-cdk-lib/aws-events-targets";
+import type { IFunction } from "aws-cdk-lib/aws-lambda";
+import { type Resolvable } from "@composurecdk/core";
+/**
+ * Wraps a Lambda function as an EventBridge {@link IRuleTarget}, deferring
+ * resolution if the function is a {@link Ref} to a sibling component's
+ * output.
+ *
+ * Mirrors the {@link LambdaFunction} target from `aws-events-targets` —
+ * `props` accepts the same options ({@link LambdaFunctionProps.event} for
+ * input transformation, plus `deadLetterQueue`, `maxEventAge`,
+ * `retryAttempts` from {@link LambdaFunctionProps}'s base).
+ *
+ * Cross-component DLQ wiring (where the queue is built by another component)
+ * is supported by composing through `ref().map()` instead of passing the
+ * queue here directly:
+ *
+ * ```ts
+ * .addTarget(
+ *   "stopper",
+ *   ref<StopperBundle>("stopperBundle", b =>
+ *     lambdaTarget(b.fn, { deadLetterQueue: b.dlq }),
+ *   ),
+ * )
+ * ```
+ *
+ * @see https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-rule-dlq.html
+ */
+export declare function lambdaTarget(fn: Resolvable<IFunction>, props?: LambdaFunctionProps): Resolvable<IRuleTarget>;
+//# sourceMappingURL=lambda-target.d.ts.map

package/dist/targets/lambda-target.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lambda-target.d.ts","sourceRoot":"","sources":["../../src/targets/lambda-target.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAkB,KAAK,mBAAmB,EAAE,MAAM,gCAAgC,CAAC;AAC1F,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,EAAS,KAAK,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAE5D;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,YAAY,CAC1B,EAAE,EAAE,UAAU,CAAC,SAAS,CAAC,EACzB,KAAK,CAAC,EAAE,mBAAmB,GAC1B,UAAU,CAAC,WAAW,CAAC,CAGzB"}

package/dist/targets/lambda-target.js

@@ -0,0 +1,33 @@
+import { LambdaFunction } from "aws-cdk-lib/aws-events-targets";
+import { isRef } from "@composurecdk/core";
+/**
+ * Wraps a Lambda function as an EventBridge {@link IRuleTarget}, deferring
+ * resolution if the function is a {@link Ref} to a sibling component's
+ * output.
+ *
+ * Mirrors the {@link LambdaFunction} target from `aws-events-targets` —
+ * `props` accepts the same options ({@link LambdaFunctionProps.event} for
+ * input transformation, plus `deadLetterQueue`, `maxEventAge`,
+ * `retryAttempts` from {@link LambdaFunctionProps}'s base).
+ *
+ * Cross-component DLQ wiring (where the queue is built by another component)
+ * is supported by composing through `ref().map()` instead of passing the
+ * queue here directly:
+ *
+ * ```ts
+ * .addTarget(
+ *   "stopper",
+ *   ref<StopperBundle>("stopperBundle", b =>
+ *     lambdaTarget(b.fn, { deadLetterQueue: b.dlq }),
+ *   ),
+ * )
+ * ```
+ *
+ * @see https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-rule-dlq.html
+ */
+export function lambdaTarget(fn, props) {
+    if (isRef(fn))
+        return fn.map((resolved) => new LambdaFunction(resolved, props));
+    return new LambdaFunction(fn, props);
+}
+//# sourceMappingURL=lambda-target.js.map

package/dist/targets/lambda-target.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lambda-target.js","sourceRoot":"","sources":["../../src/targets/lambda-target.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAA4B,MAAM,gCAAgC,CAAC;AAE1F,OAAO,EAAE,KAAK,EAAmB,MAAM,oBAAoB,CAAC;AAE5D;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,UAAU,YAAY,CAC1B,EAAyB,EACzB,KAA2B;IAE3B,IAAI,KAAK,CAAC,EAAE,CAAC;QAAE,OAAO,EAAE,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,IAAI,cAAc,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC,CAAC;IAChF,OAAO,IAAI,cAAc,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC;AACvC,CAAC"}

package/dist/targets/sfn-state-machine-target.d.ts

@@ -0,0 +1,16 @@
+import type { IRuleTarget } from "aws-cdk-lib/aws-events";
+import { type SfnStateMachineProps } from "aws-cdk-lib/aws-events-targets";
+import type { IStateMachine } from "aws-cdk-lib/aws-stepfunctions";
+import { type Resolvable } from "@composurecdk/core";
+/**
+ * Wraps a Step Functions state machine as an EventBridge
+ * {@link IRuleTarget}, deferring resolution if the state machine is a
+ * {@link Ref} to a sibling component's output.
+ *
+ * Mirrors the {@link SfnStateMachine} target from `aws-events-targets` —
+ * `props` accepts {@link SfnStateMachineProps.input} for input
+ * transformation, an explicit `role` (otherwise CDK creates one), plus the
+ * inherited DLQ/retry options.
+ */
+export declare function sfnStateMachineTarget(stateMachine: Resolvable<IStateMachine>, props?: SfnStateMachineProps): Resolvable<IRuleTarget>;
+//# sourceMappingURL=sfn-state-machine-target.d.ts.map

package/dist/targets/sfn-state-machine-target.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sfn-state-machine-target.d.ts","sourceRoot":"","sources":["../../src/targets/sfn-state-machine-target.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAmB,KAAK,oBAAoB,EAAE,MAAM,gCAAgC,CAAC;AAC5F,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AACnE,OAAO,EAAS,KAAK,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAE5D;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CACnC,YAAY,EAAE,UAAU,CAAC,aAAa,CAAC,EACvC,KAAK,CAAC,EAAE,oBAAoB,GAC3B,UAAU,CAAC,WAAW,CAAC,CAKzB"}

package/dist/targets/sfn-state-machine-target.js

@@ -0,0 +1,19 @@
+import { SfnStateMachine } from "aws-cdk-lib/aws-events-targets";
+import { isRef } from "@composurecdk/core";
+/**
+ * Wraps a Step Functions state machine as an EventBridge
+ * {@link IRuleTarget}, deferring resolution if the state machine is a
+ * {@link Ref} to a sibling component's output.
+ *
+ * Mirrors the {@link SfnStateMachine} target from `aws-events-targets` —
+ * `props` accepts {@link SfnStateMachineProps.input} for input
+ * transformation, an explicit `role` (otherwise CDK creates one), plus the
+ * inherited DLQ/retry options.
+ */
+export function sfnStateMachineTarget(stateMachine, props) {
+    if (isRef(stateMachine)) {
+        return stateMachine.map((resolved) => new SfnStateMachine(resolved, props));
+    }
+    return new SfnStateMachine(stateMachine, props);
+}
+//# sourceMappingURL=sfn-state-machine-target.js.map

package/dist/targets/sfn-state-machine-target.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sfn-state-machine-target.js","sourceRoot":"","sources":["../../src/targets/sfn-state-machine-target.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAA6B,MAAM,gCAAgC,CAAC;AAE5F,OAAO,EAAE,KAAK,EAAmB,MAAM,oBAAoB,CAAC;AAE5D;;;;;;;;;GASG;AACH,MAAM,UAAU,qBAAqB,CACnC,YAAuC,EACvC,KAA4B;IAE5B,IAAI,KAAK,CAAC,YAAY,CAAC,EAAE,CAAC;QACxB,OAAO,YAAY,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,IAAI,eAAe,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC,CAAC;IAC9E,CAAC;IACD,OAAO,IAAI,eAAe,CAAC,YAAY,EAAE,KAAK,CAAC,CAAC;AAClD,CAAC"}

package/dist/targets/sns-target.d.ts

@@ -0,0 +1,17 @@
+import type { IRuleTarget } from "aws-cdk-lib/aws-events";
+import { type SnsTopicProps } from "aws-cdk-lib/aws-events-targets";
+import type { ITopic } from "aws-cdk-lib/aws-sns";
+import { type Resolvable } from "@composurecdk/core";
+/**
+ * Wraps an SNS topic as an EventBridge {@link IRuleTarget}, deferring
+ * resolution if the topic is a {@link Ref} to a sibling component's output.
+ *
+ * Mirrors the {@link SnsTopic} target from `aws-events-targets` — `props`
+ * accepts {@link SnsTopicProps.message} for input transformation, and the
+ * IAM `role` / `authorizeUsingRole` options for cross-account publishing.
+ *
+ * Note: SNS targets do not accept a per-target DLQ
+ * ({@link SnsTopicProps} does not extend the retry/DLQ base type).
+ */
+export declare function snsTarget(topic: Resolvable<ITopic>, props?: SnsTopicProps): Resolvable<IRuleTarget>;
+//# sourceMappingURL=sns-target.d.ts.map

package/dist/targets/sns-target.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sns-target.d.ts","sourceRoot":"","sources":["../../src/targets/sns-target.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAY,KAAK,aAAa,EAAE,MAAM,gCAAgC,CAAC;AAC9E,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EAAS,KAAK,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAE5D;;;;;;;;;;GAUG;AACH,wBAAgB,SAAS,CACvB,KAAK,EAAE,UAAU,CAAC,MAAM,CAAC,EACzB,KAAK,CAAC,EAAE,aAAa,GACpB,UAAU,CAAC,WAAW,CAAC,CAGzB"}

package/dist/targets/sns-target.js

@@ -0,0 +1,19 @@
+import { SnsTopic } from "aws-cdk-lib/aws-events-targets";
+import { isRef } from "@composurecdk/core";
+/**
+ * Wraps an SNS topic as an EventBridge {@link IRuleTarget}, deferring
+ * resolution if the topic is a {@link Ref} to a sibling component's output.
+ *
+ * Mirrors the {@link SnsTopic} target from `aws-events-targets` — `props`
+ * accepts {@link SnsTopicProps.message} for input transformation, and the
+ * IAM `role` / `authorizeUsingRole` options for cross-account publishing.
+ *
+ * Note: SNS targets do not accept a per-target DLQ
+ * ({@link SnsTopicProps} does not extend the retry/DLQ base type).
+ */
+export function snsTarget(topic, props) {
+    if (isRef(topic))
+        return topic.map((resolved) => new SnsTopic(resolved, props));
+    return new SnsTopic(topic, props);
+}
+//# sourceMappingURL=sns-target.js.map

package/dist/targets/sns-target.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sns-target.js","sourceRoot":"","sources":["../../src/targets/sns-target.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAsB,MAAM,gCAAgC,CAAC;AAE9E,OAAO,EAAE,KAAK,EAAmB,MAAM,oBAAoB,CAAC;AAE5D;;;;;;;;;;GAUG;AACH,MAAM,UAAU,SAAS,CACvB,KAAyB,EACzB,KAAqB;IAErB,IAAI,KAAK,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,IAAI,QAAQ,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC,CAAC;IAChF,OAAO,IAAI,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;AACpC,CAAC"}

package/dist/targets/sqs-target.d.ts

@@ -0,0 +1,16 @@
+import type { IRuleTarget } from "aws-cdk-lib/aws-events";
+import { type SqsQueueProps } from "aws-cdk-lib/aws-events-targets";
+import type { IQueue } from "aws-cdk-lib/aws-sqs";
+import { type Resolvable } from "@composurecdk/core";
+/**
+ * Wraps an SQS queue as an EventBridge {@link IRuleTarget}, deferring
+ * resolution if the queue is a {@link Ref} to a sibling component's output.
+ *
+ * Mirrors the {@link SqsQueue} target from `aws-events-targets` — `props`
+ * accepts {@link SqsQueueProps.message} for input transformation,
+ * {@link SqsQueueProps.messageGroupId} (required for FIFO targets), plus the
+ * `deadLetterQueue` / `maxEventAge` / `retryAttempts` reliability options
+ * from the inherited base.
+ */
+export declare function sqsTarget(queue: Resolvable<IQueue>, props?: SqsQueueProps): Resolvable<IRuleTarget>;
+//# sourceMappingURL=sqs-target.d.ts.map

package/dist/targets/sqs-target.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqs-target.d.ts","sourceRoot":"","sources":["../../src/targets/sqs-target.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAY,KAAK,aAAa,EAAE,MAAM,gCAAgC,CAAC;AAC9E,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EAAS,KAAK,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAE5D;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CACvB,KAAK,EAAE,UAAU,CAAC,MAAM,CAAC,EACzB,KAAK,CAAC,EAAE,aAAa,GACpB,UAAU,CAAC,WAAW,CAAC,CAGzB"}

package/dist/targets/sqs-target.js

@@ -0,0 +1,18 @@
+import { SqsQueue } from "aws-cdk-lib/aws-events-targets";
+import { isRef } from "@composurecdk/core";
+/**
+ * Wraps an SQS queue as an EventBridge {@link IRuleTarget}, deferring
+ * resolution if the queue is a {@link Ref} to a sibling component's output.
+ *
+ * Mirrors the {@link SqsQueue} target from `aws-events-targets` — `props`
+ * accepts {@link SqsQueueProps.message} for input transformation,
+ * {@link SqsQueueProps.messageGroupId} (required for FIFO targets), plus the
+ * `deadLetterQueue` / `maxEventAge` / `retryAttempts` reliability options
+ * from the inherited base.
+ */
+export function sqsTarget(queue, props) {
+    if (isRef(queue))
+        return queue.map((resolved) => new SqsQueue(resolved, props));
+    return new SqsQueue(queue, props);
+}
+//# sourceMappingURL=sqs-target.js.map

package/dist/targets/sqs-target.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqs-target.js","sourceRoot":"","sources":["../../src/targets/sqs-target.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAsB,MAAM,gCAAgC,CAAC;AAE9E,OAAO,EAAE,KAAK,EAAmB,MAAM,oBAAoB,CAAC;AAE5D;;;;;;;;;GASG;AACH,MAAM,UAAU,SAAS,CACvB,KAAyB,EACzB,KAAqB;IAErB,IAAI,KAAK,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,IAAI,QAAQ,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC,CAAC;IAChF,OAAO,IAAI,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;AACpC,CAAC"}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@composurecdk/events",
+  "version": "0.6.0",
+  "description": "Composable EventBridge rule builder with well-architected defaults",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/laazyj/composureCDK",
+    "directory": "packages/events"
+  },
+  "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.6.0",
+    "@composurecdk/core": "^0.6.0",
+    "aws-cdk-lib": "^2.0.0",
+    "constructs": "^10.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.0",
+    "aws-cdk-lib": "^2.250.0",
+    "constructs": "^10.6.0",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.4"
+  }
+}