@composurecdk/budgets 0.3.0

package/README.md

@@ -0,0 +1,192 @@
+# @composurecdk/budgets
+
+AWS Budgets builder for [ComposureCDK](../../README.md).
+
+This package provides a fluent builder for `AWS::Budgets::Budget` with well-architected defaults, percentage-threshold notification helpers, and automatic `AWS::SNS::TopicPolicy` wiring for SNS subscribers. It wraps the CDK L1 [CfnBudget](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_budgets.CfnBudget.html) construct — there is no L2 for Budgets.
+
+## Budget Builder
+
+```ts
+import { createBudgetBuilder } from "@composurecdk/budgets";
+
+const budget = createBudgetBuilder()
+  .budgetName("AgentBudget")
+  .limit({ amount: 50, unit: "GBP" })
+  .notifyOnActual(100, "ops@example.com")
+  .build(stack, "AgentBudget");
+```
+
+### Properties
+
+Every field on [CfnBudget.BudgetDataProperty](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_budgets.CfnBudget.BudgetDataProperty.html) that tends to be set by hand is surfaced as a fluent setter:
+
+| Setter              | Purpose                                                               |
+| ------------------- | --------------------------------------------------------------------- |
+| `budgetName(name)`  | `BudgetName` — stable identifier in the console and across regions.   |
+| `budgetType(type)`  | `BudgetType` — `COST`, `USAGE`, `RI_UTILIZATION`, `RI_COVERAGE`, etc. |
+| `timeUnit(unit)`    | `TimeUnit` — `DAILY`, `MONTHLY`, `QUARTERLY`, `ANNUALLY`.             |
+| `limit({ amount })` | `BudgetLimit` — required for `COST` and `USAGE` budgets.              |
+| `costFilters(map)`  | `CostFilters` — e.g. `{ Service: ["AmazonEC2"] }`.                    |
+| `costTypes(types)`  | `CostTypes` passthrough.                                              |
+
+### Notifications
+
+Percentage-threshold helpers cover the common case; `addNotification` accepts the raw shape when you need absolute-value thresholds or a different comparison operator.
+
+```ts
+createBudgetBuilder()
+  .limit({ amount: 100 })
+  .notifyOnActual(80, "ops@example.com") // 80% ACTUAL → email
+  .notifyOnForecasted(
+    100,
+    ref("alerts", (r) => r.topic),
+  ) // 100% FORECASTED → SNS topic
+  .addNotification({
+    notificationType: "ACTUAL",
+    threshold: 120,
+    thresholdType: "ABSOLUTE_VALUE",
+    subscribers: ["oncall@example.com"],
+  });
+```
+
+Subscribers may be email strings, `ITopic` instances, or `Resolvable<ITopic>` references to topics owned by sibling components.
+
+### Recommended Thresholds
+
+```ts
+createBudgetBuilder().limit({ amount: 50 }).withRecommendedThresholds("ops@example.com");
+```
+
+Applies the AWS Cost Optimization pillar defaults: `ACTUAL` at 80% and `FORECASTED` at 100%.
+
+## Defaults
+
+| Property                                  | Default     | Rationale                                                                     |
+| ----------------------------------------- | ----------- | ----------------------------------------------------------------------------- |
+| `budgetType`                              | `"COST"`    | Cost budgets are the most common; usage/RI/SP budgets are explicit overrides. |
+| `timeUnit`                                | `"MONTHLY"` | Aligns with AWS billing cycles.                                               |
+| `limitUnit`                               | `"USD"`     | Matches the AWS Billing console default.                                      |
+| `recommendedThresholds.actualPercent`     | `80`        | Early-warning threshold before breach.                                        |
+| `recommendedThresholds.forecastedPercent` | `100`       | Trending-over-budget alert for the period.                                    |
+
+Exported as `BUDGET_DEFAULTS`.
+
+## Automatic SNS Topic Policies
+
+When at least one notification subscriber is an SNS topic, the builder creates a matching `AWS::SNS::TopicPolicy` granting `SNS:Publish` to the `budgets.amazonaws.com` service principal. Without that policy, budget notifications to SNS silently fail to deliver — one of the most common footguns when wiring Budgets by hand.
+
+The created `TopicPolicy` constructs are returned on `result.topicPolicies`, keyed by the topic's fully-qualified node path (unique within the CDK app).
+
+## Recommended Alarms
+
+AWS Budgets does not publish per-budget CloudWatch metrics, but the well-architected cost-monitoring pattern combines a budget with a CloudWatch alarm on `AWS/Billing EstimatedCharges`. The builder can create that alarm for you, but it is **off by default** — pass an `estimatedCharges` config to opt in.
+
+| Alarm              | Metric                              | Default behaviour |
+| ------------------ | ----------------------------------- | ----------------- |
+| `estimatedCharges` | EstimatedCharges (Maximum, 6 hours) | off               |
+
+`treatMissingData` defaults to `notBreaching`: missing datapoints from a quiet account are not treated as a breach.
+
+```ts
+const stack = new Stack(app, "BillingStack", { env: { region: "us-east-1" } });
+
+createBudgetBuilder()
+  .limit({ amount: 50 })
+  .recommendedAlarms({
+    estimatedCharges: { threshold: 50, currency: "USD" },
+  })
+  .build(stack, "AccountBudget");
+```
+
+The Budget itself is a global service and can be created from any region; only the alarm requires `us-east-1` (see below).
+
+### Customising thresholds
+
+```ts
+createBudgetBuilder()
+  .limit({ amount: 1000 })
+  .recommendedAlarms({
+    estimatedCharges: {
+      threshold: 1000,
+      currency: "USD",
+      evaluationPeriods: 2,
+      datapointsToAlarm: 2,
+    },
+  });
+```
+
+### Disabling alarms
+
+Disable the recommended alarm with `recommendedAlarms({ estimatedCharges: false })`, or disable all recommended alarms with `recommendedAlarms(false)`. Custom alarms attached via `addAlarm` are unaffected by either form.
+
+### Custom alarms
+
+```ts
+import { Metric } from "aws-cdk-lib/aws-cloudwatch";
+
+createBudgetBuilder()
+  .limit({ amount: 1000 })
+  .addAlarm("ec2EstimatedCharges", (a) =>
+    a
+      .metric(
+        () =>
+          new Metric({
+            namespace: "AWS/Billing",
+            metricName: "EstimatedCharges",
+            dimensionsMap: { Currency: "USD", ServiceName: "AmazonEC2" },
+            statistic: "Maximum",
+          }),
+      )
+      .threshold(500)
+      .greaterThan()
+      .description("EC2 estimated charges exceeded $500."),
+  );
+```
+
+### Applying alarm actions
+
+No alarm actions are configured by default. Wire SNS or other actions via [`alarmActionsPolicy`](../cloudwatch/README.md#alarm-actions-policy) (or an `afterBuild` hook) — for cross-region deployments, the policy applied to the `us-east-1` monitoring stack covers both recommended and custom alarms.
+
+### Cross-region: `AWS/Billing EstimatedCharges` lives in `us-east-1` only
+
+The `AWS/Billing EstimatedCharges` metric is emitted in `us-east-1` only, regardless of where your budgets and resources live. CloudWatch alarms are regional, so an alarm in any other region will never receive data. The combined builder emits a synth-time warning (`@composurecdk/budgets:alarm-region`) when used outside `us-east-1`, but the better approach is to route the alarm into a `us-east-1` stack via `createBudgetAlarmBuilder` and `compose().withStacks()`:
+
+```ts
+import { compose, ref } from "@composurecdk/core";
+import {
+  createBudgetBuilder,
+  createBudgetAlarmBuilder,
+  type BudgetBuilderResult,
+} from "@composurecdk/budgets";
+
+compose(
+  {
+    account: createBudgetBuilder()
+      .budgetName("Account")
+      .limit({ amount: 1000 })
+      .recommendedAlarms(false), // suppress alarms in the budget's own stack
+
+    accountAlarms: createBudgetAlarmBuilder()
+      .budget(ref<BudgetBuilderResult>("account"))
+      .recommendedAlarms({ estimatedCharges: { threshold: 1000, currency: "USD" } }),
+  },
+  { account: [], accountAlarms: ["account"] },
+)
+  .withStacks({
+    account: appStack, //         any region — AWS::Budgets::Budget is global
+    accountAlarms: monitoringStack, // us-east-1 — where AWS/Billing metrics live
+  })
+  .build(app, "App");
+```
+
+If your custom `addAlarm` definitions reference the budget construct, set `crossRegionReferences: true` on both stacks so CDK can export the budget's properties from the app stack and import them in the alarm stack. The same pattern is documented for CloudFront and Route 53 alarms, and codified in [ADR-0004](../../docs/adr/0004-split-alarm-builder-for-fixed-region-metrics.md).
+
+## Build Result
+
+```ts
+interface BudgetBuilderResult {
+  budget: CfnBudget;
+  topicPolicies: Record<string, TopicPolicy>;
+  alarms: Record<string, Alarm>;
+}
+```

package/dist/alarm-config.d.ts

@@ -0,0 +1,61 @@
+import type { AlarmConfig } from "@composurecdk/cloudwatch";
+/**
+ * Extended {@link AlarmConfig} for the account-level `EstimatedCharges`
+ * billing alarm.
+ *
+ * The `EstimatedCharges` metric lives in the `AWS/Billing` namespace and
+ * is **only emitted in the `us-east-1` region**, regardless of where
+ * your resources run. The builder emits a synth-time warning when the
+ * surrounding stack is not in `us-east-1`; for non-`us-east-1` stacks,
+ * suppress this alarm with `recommendedAlarms: false` and create the
+ * alarm in a `us-east-1` stack via `createBudgetAlarmBuilder` (see
+ * ADR-0004).
+ *
+ * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/monitor_estimated_charges_with_cloudwatch.html
+ */
+export interface EstimatedChargesAlarmConfig extends AlarmConfig {
+    /**
+     * The absolute cost threshold (in `currency`) at which the alarm fires.
+     * This is a hard monetary value, **not** a percentage of the budget.
+     */
+    threshold: number;
+    /**
+     * ISO 4217 currency code that the `EstimatedCharges` metric is
+     * emitted in. AWS emits the metric with a `Currency` dimension that
+     * must match your billing currency.
+     *
+     * @default "USD"
+     */
+    currency?: string;
+}
+/**
+ * Controls which recommended CloudWatch alarms are created for an AWS
+ * Budget.
+ *
+ * AWS Budgets itself does not publish per-budget CloudWatch metrics.
+ * The recommended-alarm surface therefore mirrors the well-architected
+ * cost-monitoring pattern: a CloudWatch alarm on the account-level
+ * `AWS/Billing EstimatedCharges` metric that fires when total estimated
+ * charges cross a hard threshold.
+ *
+ * Off by default — the alarm only emits data when its stack is deployed
+ * to `us-east-1`, so callers must opt in explicitly.
+ *
+ * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/monitor_estimated_charges_with_cloudwatch.html
+ */
+export interface BudgetAlarmConfig {
+    /**
+     * Master switch.
+     * @default false
+     */
+    enabled?: boolean;
+    /**
+     * Configuration for the `EstimatedCharges` billing alarm.
+     *
+     * Pass `false` to disable, or supply an
+     * {@link EstimatedChargesAlarmConfig} to enable with a specific
+     * monetary threshold.
+     */
+    estimatedCharges?: EstimatedChargesAlarmConfig | false;
+}
+//# sourceMappingURL=alarm-config.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"alarm-config.d.ts","sourceRoot":"","sources":["../src/alarm-config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAE5D;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,2BAA4B,SAAQ,WAAW;IAC9D;;;OAGG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE,2BAA2B,GAAG,KAAK,CAAC;CACxD"}

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/budget-alarm-builder.d.ts

@@ -0,0 +1,147 @@
+import { type CfnBudget } from "aws-cdk-lib/aws-budgets";
+import { type Alarm } from "aws-cdk-lib/aws-cloudwatch";
+import { type IConstruct } from "constructs";
+import { type IBuilder, type Lifecycle, type Resolvable } from "@composurecdk/core";
+import { AlarmDefinitionBuilder } from "@composurecdk/cloudwatch";
+import type { BudgetAlarmConfig } from "./alarm-config.js";
+import type { BudgetBuilderResult } from "./budget-builder.js";
+/**
+ * Configuration properties for {@link createBudgetAlarmBuilder}.
+ *
+ * The standalone alarm builder mirrors the alarm surface that
+ * {@link createBudgetBuilder} creates by default. It exists so that
+ * billing alarms can be created in a different stack from the budget
+ * itself — specifically a `us-east-1` stack, since the
+ * `AWS/Billing EstimatedCharges` metric is only emitted in `us-east-1`
+ * regardless of where the budget is deployed.
+ *
+ * @see ADR-0004 — Split-alarm builder pattern for fixed-region metrics
+ */
+export interface BudgetAlarmBuilderProps {
+    /**
+     * Configuration for AWS-recommended CloudWatch alarms.
+     *
+     * Mirrors {@link BudgetBuilderProps.recommendedAlarms}. Off by default —
+     * pass an {@link BudgetAlarmConfig.estimatedCharges} entry to enable
+     * the account-level billing alarm. Set to `false` to suppress recommended
+     * alarms entirely; custom alarms added via
+     * {@link IBudgetAlarmBuilder.addAlarm} are unaffected.
+     *
+     * No alarm actions are configured by default. Use `alarmActionsPolicy`
+     * (or an `afterBuild` hook) to wire SNS or other actions onto the
+     * resulting alarms.
+     *
+     * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/monitor_estimated_charges_with_cloudwatch.html
+     */
+    recommendedAlarms?: BudgetAlarmConfig | false;
+}
+/**
+ * The build output of an {@link IBudgetAlarmBuilder}.
+ */
+export interface BudgetAlarmBuilderResult {
+    /**
+     * The CloudWatch alarms created by this builder, keyed by alarm name.
+     * Uses the same key scheme as {@link BudgetBuilderResult.alarms}.
+     */
+    alarms: Record<string, Alarm>;
+}
+/**
+ * A fluent builder for budget-related CloudWatch alarms, decoupled from
+ * the budget itself. Use this when the budget lives in a stack outside
+ * `us-east-1` — route this builder's component into a `us-east-1` stack
+ * via `compose().withStacks()` so the alarms land where the
+ * `AWS/Billing EstimatedCharges` metric actually emits.
+ *
+ * @see {@link createBudgetAlarmBuilder}
+ */
+export type IBudgetAlarmBuilder = IBuilder<BudgetAlarmBuilderProps, BudgetAlarmBuilder>;
+/**
+ * Shared alarm-assembly used by both {@link createBudgetBuilder} (in its
+ * own stack) and {@link createBudgetAlarmBuilder} (typically in a separate
+ * `us-east-1` stack). Materialises the recommended billing alarm and any
+ * user-supplied custom alarms, emits the region warning if the resulting
+ * scope is not in `us-east-1`, and creates the alarm constructs.
+ *
+ * The `target.budget` reference is only needed for custom alarms added
+ * via `addAlarm()` — the recommended `EstimatedCharges` alarm is
+ * account-level and does not key off the budget itself, so `target` may
+ * be omitted when only the recommended alarm is being created.
+ *
+ * @internal
+ */
+export declare function buildBudgetAlarms(scope: IConstruct, id: string, target: Pick<BudgetBuilderResult, "budget"> | undefined, options?: {
+    recommendedAlarms?: BudgetAlarmConfig | false;
+    customAlarms?: AlarmDefinitionBuilder<CfnBudget>[];
+}): Record<string, Alarm>;
+declare class BudgetAlarmBuilder implements Lifecycle<BudgetAlarmBuilderResult> {
+    #private;
+    props: Partial<BudgetAlarmBuilderProps>;
+    /**
+     * Sets the budget to alarm on. Pass the result of
+     * {@link createBudgetBuilder} (or a {@link Ref} to it). The builder
+     * reads the underlying `CfnBudget` from the result so custom alarms
+     * added via {@link addAlarm} can reference it.
+     *
+     * Optional when only the recommended `EstimatedCharges` alarm is being
+     * created — that alarm is account-level and does not reference any
+     * specific budget. Required as soon as you call {@link addAlarm}.
+     *
+     * Pair with `compose().withStacks()` to route this component into a
+     * `us-east-1` stack while the budget itself lives elsewhere — set
+     * `crossRegionReferences: true` on both stacks so CDK can wire any
+     * cross-stack references automatically.
+     */
+    budget(budget: Resolvable<BudgetBuilderResult>): this;
+    /**
+     * Adds a custom alarm against the budget. The configure callback
+     * receives a fresh {@link AlarmDefinitionBuilder} pre-set with the
+     * alarm's key; configure metric, threshold, comparison and any other
+     * options.
+     *
+     * The created alarm is materialised in this builder's stack — useful
+     * for cross-region setups where you want all billing-related alarms to
+     * live with the recommended one.
+     */
+    addAlarm(key: string, configure: (alarm: AlarmDefinitionBuilder<CfnBudget>) => AlarmDefinitionBuilder<CfnBudget>): this;
+    build(scope: IConstruct, id: string, context?: Record<string, object>): BudgetAlarmBuilderResult;
+}
+/**
+ * Creates a new {@link IBudgetAlarmBuilder} for materialising AWS Budget
+ * alarms in a stack separate from the budget itself.
+ *
+ * The recommended use is multi-region deployments: the budget lives in
+ * the application's stack (in any region — `AWS::Budgets::Budget` is a
+ * global resource), and the alarms must live in a `us-east-1` stack so
+ * they can read the `AWS/Billing EstimatedCharges` metric AWS emits
+ * there.
+ *
+ * @example
+ * ```ts
+ * compose(
+ *   {
+ *     account: createBudgetBuilder()
+ *       .budgetName("Account")
+ *       .limit({ amount: 1000 })
+ *       .recommendedAlarms(false),                       // suppress alarms in the budget's own stack
+ *
+ *     accountAlarms: createBudgetAlarmBuilder()
+ *       .budget(ref<BudgetBuilderResult>("account"))
+ *       .recommendedAlarms({
+ *         estimatedCharges: { threshold: 1000, currency: "USD" },
+ *       }),
+ *   },
+ *   { account: [], accountAlarms: ["account"] },
+ * )
+ *   .withStacks({
+ *     account:       appStack,         // any region — Budgets is a global service
+ *     accountAlarms: monitoringStack,  // us-east-1 — where AWS/Billing metrics live
+ *   })
+ *   .build(app, "App");
+ * ```
+ *
+ * Set `crossRegionReferences: true` on both stacks if you reference the
+ * budget from custom alarms via `.addAlarm()`.
+ */
+export declare function createBudgetAlarmBuilder(): IBudgetAlarmBuilder;
+export {};
+//# sourceMappingURL=budget-alarm-builder.d.ts.map

package/dist/budget-alarm-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"budget-alarm-builder.d.ts","sourceRoot":"","sources":["../src/budget-alarm-builder.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,yBAAyB,CAAC;AACzD,OAAO,EAAE,KAAK,KAAK,EAAE,MAAM,4BAA4B,CAAC;AAExD,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EAEL,KAAK,QAAQ,EACb,KAAK,SAAS,EAEd,KAAK,UAAU,EAChB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,sBAAsB,EAAgB,MAAM,0BAA0B,CAAC;AAChF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAE3D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAE/D;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,uBAAuB;IACtC;;;;;;;;;;;;;;OAcG;IACH,iBAAiB,CAAC,EAAE,iBAAiB,GAAG,KAAK,CAAC;CAC/C;AAED;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;CAC/B;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,mBAAmB,GAAG,QAAQ,CAAC,uBAAuB,EAAE,kBAAkB,CAAC,CAAC;AAsBxF;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,UAAU,EACjB,EAAE,EAAE,MAAM,EACV,MAAM,EAAE,IAAI,CAAC,mBAAmB,EAAE,QAAQ,CAAC,GAAG,SAAS,EACvD,OAAO,GAAE;IACP,iBAAiB,CAAC,EAAE,iBAAiB,GAAG,KAAK,CAAC;IAC9C,YAAY,CAAC,EAAE,sBAAsB,CAAC,SAAS,CAAC,EAAE,CAAC;CAC/C,GACL,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAoBvB;AAED,cAAM,kBAAmB,YAAW,SAAS,CAAC,wBAAwB,CAAC;;IACrE,KAAK,EAAE,OAAO,CAAC,uBAAuB,CAAC,CAAM;IAI7C;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,mBAAmB,CAAC,GAAG,IAAI;IAKrD;;;;;;;;;OASG;IACH,QAAQ,CACN,GAAG,EAAE,MAAM,EACX,SAAS,EAAE,CAAC,KAAK,EAAE,sBAAsB,CAAC,SAAS,CAAC,KAAK,sBAAsB,CAAC,SAAS,CAAC,GACzF,IAAI;IAKP,KAAK,CAAC,KAAK,EAAE,UAAU,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,wBAAwB;CASjG;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAAgB,wBAAwB,IAAI,mBAAmB,CAE9D"}

package/dist/budget-alarm-builder.js

@@ -0,0 +1,139 @@
+import { Annotations, Stack, Token } from "aws-cdk-lib";
+import { Builder, resolve, } from "@composurecdk/core";
+import { AlarmDefinitionBuilder, createAlarms } from "@composurecdk/cloudwatch";
+import { resolveBudgetAlarmDefinitions } from "./budget-alarms.js";
+/**
+ * The `AWS/Billing EstimatedCharges` metric is emitted in `us-east-1`
+ * only. CloudWatch alarms are regional, so alarms created in any other
+ * region will never receive data. Warn (don't error) when alarms are
+ * being created outside `us-east-1`, unless the region is an unresolved
+ * token (env-agnostic stack — user knows best).
+ */
+function warnIfNotUsEast1(scope) {
+    const region = Stack.of(scope).region;
+    if (Token.isUnresolved(region))
+        return;
+    if (region === "us-east-1")
+        return;
+    Annotations.of(scope).addWarningV2("@composurecdk/budgets:alarm-region", `AWS/Billing EstimatedCharges is emitted in us-east-1 only, but this stack is ` +
+        `deployed in "${region}". CloudWatch alarms created here will not fire. Deploy the ` +
+        `stack in us-east-1, or use createBudgetAlarmBuilder() routed to a ` +
+        `us-east-1 stack via compose().withStacks().`);
+}
+/**
+ * Shared alarm-assembly used by both {@link createBudgetBuilder} (in its
+ * own stack) and {@link createBudgetAlarmBuilder} (typically in a separate
+ * `us-east-1` stack). Materialises the recommended billing alarm and any
+ * user-supplied custom alarms, emits the region warning if the resulting
+ * scope is not in `us-east-1`, and creates the alarm constructs.
+ *
+ * The `target.budget` reference is only needed for custom alarms added
+ * via `addAlarm()` — the recommended `EstimatedCharges` alarm is
+ * account-level and does not key off the budget itself, so `target` may
+ * be omitted when only the recommended alarm is being created.
+ *
+ * @internal
+ */
+export function buildBudgetAlarms(scope, id, target, options = {}) {
+    const recommended = options.recommendedAlarms;
+    const recommendedDefs = recommended === false ? [] : resolveBudgetAlarmDefinitions(recommended);
+    const customAlarms = options.customAlarms ?? [];
+    if (customAlarms.length > 0 && !target) {
+        throw new Error(`BudgetAlarmBuilder "${id}" was given addAlarm() definitions but no budget. ` +
+            `Call .budget() with a BudgetBuilderResult or a Ref to one before adding custom alarms.`);
+    }
+    const customAlarmDefs = target ? customAlarms.map((b) => b.resolve(target.budget)) : [];
+    const allAlarmDefs = [...recommendedDefs, ...customAlarmDefs];
+    if (allAlarmDefs.length > 0) {
+        warnIfNotUsEast1(scope);
+    }
+    return createAlarms(scope, id, allAlarmDefs);
+}
+class BudgetAlarmBuilder {
+    props = {};
+    #budget;
+    #customAlarms = [];
+    /**
+     * Sets the budget to alarm on. Pass the result of
+     * {@link createBudgetBuilder} (or a {@link Ref} to it). The builder
+     * reads the underlying `CfnBudget` from the result so custom alarms
+     * added via {@link addAlarm} can reference it.
+     *
+     * Optional when only the recommended `EstimatedCharges` alarm is being
+     * created — that alarm is account-level and does not reference any
+     * specific budget. Required as soon as you call {@link addAlarm}.
+     *
+     * Pair with `compose().withStacks()` to route this component into a
+     * `us-east-1` stack while the budget itself lives elsewhere — set
+     * `crossRegionReferences: true` on both stacks so CDK can wire any
+     * cross-stack references automatically.
+     */
+    budget(budget) {
+        this.#budget = budget;
+        return this;
+    }
+    /**
+     * Adds a custom alarm against the budget. The configure callback
+     * receives a fresh {@link AlarmDefinitionBuilder} pre-set with the
+     * alarm's key; configure metric, threshold, comparison and any other
+     * options.
+     *
+     * The created alarm is materialised in this builder's stack — useful
+     * for cross-region setups where you want all billing-related alarms to
+     * live with the recommended one.
+     */
+    addAlarm(key, configure) {
+        this.#customAlarms.push(configure(new AlarmDefinitionBuilder(key)));
+        return this;
+    }
+    build(scope, id, context) {
+        const target = this.#budget ? resolve(this.#budget, context ?? {}) : undefined;
+        return {
+            alarms: buildBudgetAlarms(scope, id, target, {
+                recommendedAlarms: this.props.recommendedAlarms,
+                customAlarms: this.#customAlarms,
+            }),
+        };
+    }
+}
+/**
+ * Creates a new {@link IBudgetAlarmBuilder} for materialising AWS Budget
+ * alarms in a stack separate from the budget itself.
+ *
+ * The recommended use is multi-region deployments: the budget lives in
+ * the application's stack (in any region — `AWS::Budgets::Budget` is a
+ * global resource), and the alarms must live in a `us-east-1` stack so
+ * they can read the `AWS/Billing EstimatedCharges` metric AWS emits
+ * there.
+ *
+ * @example
+ * ```ts
+ * compose(
+ *   {
+ *     account: createBudgetBuilder()
+ *       .budgetName("Account")
+ *       .limit({ amount: 1000 })
+ *       .recommendedAlarms(false),                       // suppress alarms in the budget's own stack
+ *
+ *     accountAlarms: createBudgetAlarmBuilder()
+ *       .budget(ref<BudgetBuilderResult>("account"))
+ *       .recommendedAlarms({
+ *         estimatedCharges: { threshold: 1000, currency: "USD" },
+ *       }),
+ *   },
+ *   { account: [], accountAlarms: ["account"] },
+ * )
+ *   .withStacks({
+ *     account:       appStack,         // any region — Budgets is a global service
+ *     accountAlarms: monitoringStack,  // us-east-1 — where AWS/Billing metrics live
+ *   })
+ *   .build(app, "App");
+ * ```
+ *
+ * Set `crossRegionReferences: true` on both stacks if you reference the
+ * budget from custom alarms via `.addAlarm()`.
+ */
+export function createBudgetAlarmBuilder() {
+    return Builder(BudgetAlarmBuilder);
+}
+//# sourceMappingURL=budget-alarm-builder.js.map

package/dist/budget-alarm-builder.js.map

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

package/dist/budget-alarms.d.ts

@@ -0,0 +1,22 @@
+import type { AlarmDefinition } from "@composurecdk/cloudwatch";
+import type { BudgetAlarmConfig } from "./alarm-config.js";
+/**
+ * Resolves the recommended alarm configuration into fully-resolved
+ * {@link AlarmDefinition}s for an AWS Budget.
+ *
+ * AWS Budgets does not publish per-budget CloudWatch metrics — the only
+ * recommended alarm is the account-level `AWS/Billing EstimatedCharges`
+ * billing alarm. Off by default: callers must pass an
+ * {@link BudgetAlarmConfig.estimatedCharges} config to opt in.
+ *
+ * Period and statistic are fixed at the AWS-recommended values
+ * (6 hours, Maximum) and not exposed as configuration knobs — billing
+ * metrics only update every ~6 hours, so a shorter period would
+ * oversample. Threshold, currency, evaluation periods, datapoints and
+ * missing-data behaviour remain user-configurable via
+ * {@link EstimatedChargesAlarmConfig}.
+ *
+ * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/monitor_estimated_charges_with_cloudwatch.html
+ */
+export declare function resolveBudgetAlarmDefinitions(config: BudgetAlarmConfig | undefined): AlarmDefinition[];
+//# sourceMappingURL=budget-alarms.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"budget-alarms.d.ts","sourceRoot":"","sources":["../src/budget-alarms.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAChE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAI3D;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,6BAA6B,CAC3C,MAAM,EAAE,iBAAiB,GAAG,SAAS,GACpC,eAAe,EAAE,CAyBnB"}

package/dist/budget-alarms.js

@@ -0,0 +1,48 @@
+import { Duration } from "aws-cdk-lib";
+import { ComparisonOperator, Metric, TreatMissingData } from "aws-cdk-lib/aws-cloudwatch";
+const BILLING_METRIC_PERIOD = Duration.hours(6);
+/**
+ * Resolves the recommended alarm configuration into fully-resolved
+ * {@link AlarmDefinition}s for an AWS Budget.
+ *
+ * AWS Budgets does not publish per-budget CloudWatch metrics — the only
+ * recommended alarm is the account-level `AWS/Billing EstimatedCharges`
+ * billing alarm. Off by default: callers must pass an
+ * {@link BudgetAlarmConfig.estimatedCharges} config to opt in.
+ *
+ * Period and statistic are fixed at the AWS-recommended values
+ * (6 hours, Maximum) and not exposed as configuration knobs — billing
+ * metrics only update every ~6 hours, so a shorter period would
+ * oversample. Threshold, currency, evaluation periods, datapoints and
+ * missing-data behaviour remain user-configurable via
+ * {@link EstimatedChargesAlarmConfig}.
+ *
+ * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/monitor_estimated_charges_with_cloudwatch.html
+ */
+export function resolveBudgetAlarmDefinitions(config) {
+    if (config?.enabled === false)
+        return [];
+    if (!config?.estimatedCharges)
+        return [];
+    const cfg = config.estimatedCharges;
+    const currency = cfg.currency ?? "USD";
+    return [
+        {
+            key: "estimatedCharges",
+            metric: new Metric({
+                namespace: "AWS/Billing",
+                metricName: "EstimatedCharges",
+                dimensionsMap: { Currency: currency },
+                statistic: "Maximum",
+                period: BILLING_METRIC_PERIOD,
+            }),
+            threshold: cfg.threshold,
+            comparisonOperator: ComparisonOperator.GREATER_THAN_THRESHOLD,
+            evaluationPeriods: cfg.evaluationPeriods ?? 1,
+            datapointsToAlarm: cfg.datapointsToAlarm ?? 1,
+            treatMissingData: cfg.treatMissingData ?? TreatMissingData.NOT_BREACHING,
+            description: `Account-level estimated charges exceeded ${String(cfg.threshold)} ${currency}. Billing metrics are only emitted in us-east-1.`,
+        },
+    ];
+}
+//# sourceMappingURL=budget-alarms.js.map

package/dist/budget-alarms.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"budget-alarms.js","sourceRoot":"","sources":["../src/budget-alarms.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,OAAO,EAAE,kBAAkB,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAI1F,MAAM,qBAAqB,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AAEhD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,6BAA6B,CAC3C,MAAqC;IAErC,IAAI,MAAM,EAAE,OAAO,KAAK,KAAK;QAAE,OAAO,EAAE,CAAC;IACzC,IAAI,CAAC,MAAM,EAAE,gBAAgB;QAAE,OAAO,EAAE,CAAC;IAEzC,MAAM,GAAG,GAAG,MAAM,CAAC,gBAAgB,CAAC;IACpC,MAAM,QAAQ,GAAG,GAAG,CAAC,QAAQ,IAAI,KAAK,CAAC;IAEvC,OAAO;QACL;YACE,GAAG,EAAE,kBAAkB;YACvB,MAAM,EAAE,IAAI,MAAM,CAAC;gBACjB,SAAS,EAAE,aAAa;gBACxB,UAAU,EAAE,kBAAkB;gBAC9B,aAAa,EAAE,EAAE,QAAQ,EAAE,QAAQ,EAAE;gBACrC,SAAS,EAAE,SAAS;gBACpB,MAAM,EAAE,qBAAqB;aAC9B,CAAC;YACF,SAAS,EAAE,GAAG,CAAC,SAAS;YACxB,kBAAkB,EAAE,kBAAkB,CAAC,sBAAsB;YAC7D,iBAAiB,EAAE,GAAG,CAAC,iBAAiB,IAAI,CAAC;YAC7C,iBAAiB,EAAE,GAAG,CAAC,iBAAiB,IAAI,CAAC;YAC7C,gBAAgB,EAAE,GAAG,CAAC,gBAAgB,IAAI,gBAAgB,CAAC,aAAa;YACxE,WAAW,EAAE,4CAA4C,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,QAAQ,kDAAkD;SAC7I;KACF,CAAC;AACJ,CAAC"}