@composurecdk/budgets 0.6.0 → 0.8.0

package/dist/commonjs/email.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.email = email;
+const MAX_LEN = 50;
+const EMAIL_REGEX = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+/**
+ * Validates and brands a string as an {@link Email}.
+ *
+ * The pattern intentionally errs on the side of acceptance — anything
+ * obviously not an email (whitespace, missing `@`, missing TLD) is
+ * rejected, but any address AWS Budgets will plausibly accept passes.
+ * The 50-char cap matches the Budgets API's documented per-subscriber
+ * limit.
+ *
+ * @throws If the input is empty, exceeds 50 characters, or doesn't
+ * contain `local@domain.tld`.
+ *
+ * @see https://docs.aws.amazon.com/aws-cost-management/latest/APIReference/API_budgets_Subscriber.html
+ */
+function email(input) {
+    const trimmed = input.trim();
+    if (trimmed.length === 0) {
+        throw new Error("email cannot be empty");
+    }
+    if (trimmed.length > MAX_LEN) {
+        throw new Error(`email exceeds ${String(MAX_LEN)} chars (AWS Budgets per-subscriber limit): "${trimmed}"`);
+    }
+    if (!EMAIL_REGEX.test(trimmed)) {
+        throw new Error(`invalid email address: "${trimmed}"`);
+    }
+    return trimmed;
+}
+//# sourceMappingURL=email.js.map

package/dist/commonjs/email.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"email.js","sourceRoot":"","sources":["../../src/email.ts"],"names":[],"mappings":";;AA4BA,sBAcC;AA/BD,MAAM,OAAO,GAAG,EAAE,CAAC;AACnB,MAAM,WAAW,GAAG,4BAA4B,CAAC;AAEjD;;;;;;;;;;;;;GAaG;AACH,SAAgB,KAAK,CAAC,KAAa;IACjC,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IAC7B,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,MAAM,IAAI,KAAK,CAAC,uBAAuB,CAAC,CAAC;IAC3C,CAAC;IACD,IAAI,OAAO,CAAC,MAAM,GAAG,OAAO,EAAE,CAAC;QAC7B,MAAM,IAAI,KAAK,CACb,iBAAiB,MAAM,CAAC,OAAO,CAAC,+CAA+C,OAAO,GAAG,CAC1F,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;QAC/B,MAAM,IAAI,KAAK,CAAC,2BAA2B,OAAO,GAAG,CAAC,CAAC;IACzD,CAAC;IACD,OAAO,OAAgB,CAAC;AAC1B,CAAC"}

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,mBAAmB,EACnB,KAAK,cAAc,EACnB,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,EACxB,KAAK,WAAW,GACjB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,wBAAwB,EACxB,KAAK,mBAAmB,EACxB,KAAK,uBAAuB,EAC5B,KAAK,wBAAwB,GAC9B,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,eAAe,EAAE,yBAAyB,EAAE,MAAM,eAAe,CAAC;AAC3E,OAAO,EAAE,KAAK,iBAAiB,EAAE,KAAK,2BAA2B,EAAE,MAAM,mBAAmB,CAAC;AAC7F,OAAO,EAAE,0BAA0B,EAAE,MAAM,mBAAmB,CAAC;AAC/D,OAAO,EAAE,KAAK,EAAE,KAAK,KAAK,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,EACL,kBAAkB,EAClB,gCAAgC,EAChC,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACtB,KAAK,mBAAmB,GACzB,MAAM,oBAAoB,CAAC"}

package/dist/commonjs/index.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toCfnNotificationWithSubscribers = exports.resolveSubscribers = exports.email = exports.createBudgetsTopicPolicies = exports.DEFAULT_BUDGET_CURRENCIES = exports.BUDGET_DEFAULTS = exports.createBudgetAlarmBuilder = exports.createBudgetBuilder = void 0;
+var budget_builder_js_1 = require("./budget-builder.js");
+Object.defineProperty(exports, "createBudgetBuilder", { enumerable: true, get: function () { return budget_builder_js_1.createBudgetBuilder; } });
+var budget_alarm_builder_js_1 = require("./budget-alarm-builder.js");
+Object.defineProperty(exports, "createBudgetAlarmBuilder", { enumerable: true, get: function () { return budget_alarm_builder_js_1.createBudgetAlarmBuilder; } });
+var defaults_js_1 = require("./defaults.js");
+Object.defineProperty(exports, "BUDGET_DEFAULTS", { enumerable: true, get: function () { return defaults_js_1.BUDGET_DEFAULTS; } });
+Object.defineProperty(exports, "DEFAULT_BUDGET_CURRENCIES", { enumerable: true, get: function () { return defaults_js_1.DEFAULT_BUDGET_CURRENCIES; } });
+var topic_policy_js_1 = require("./topic-policy.js");
+Object.defineProperty(exports, "createBudgetsTopicPolicies", { enumerable: true, get: function () { return topic_policy_js_1.createBudgetsTopicPolicies; } });
+var email_js_1 = require("./email.js");
+Object.defineProperty(exports, "email", { enumerable: true, get: function () { return email_js_1.email; } });
+var notifications_js_1 = require("./notifications.js");
+Object.defineProperty(exports, "resolveSubscribers", { enumerable: true, get: function () { return notifications_js_1.resolveSubscribers; } });
+Object.defineProperty(exports, "toCfnNotificationWithSubscribers", { enumerable: true, get: function () { return notifications_js_1.toCfnNotificationWithSubscribers; } });
+//# sourceMappingURL=index.js.map

package/dist/commonjs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;AAAA,yDAM6B;AAL3B,wHAAA,mBAAmB,OAAA;AAMrB,qEAKmC;AAJjC,mIAAA,wBAAwB,OAAA;AAK1B,6CAA2E;AAAlE,8GAAA,eAAe,OAAA;AAAE,wHAAA,yBAAyB,OAAA;AAEnD,qDAA+D;AAAtD,6HAAA,0BAA0B,OAAA;AACnC,uCAA+C;AAAtC,iGAAA,KAAK,OAAA;AACd,uDAO4B;AAN1B,sHAAA,kBAAkB,OAAA;AAClB,oIAAA,gCAAgC,OAAA"}

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

@@ -0,0 +1 @@
+{"version":3,"file":"notifications.d.ts","sourceRoot":"","sources":["../../src/notifications.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AACpD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EAAW,KAAK,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAC9D,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAExC;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;OAIG;IACH,GAAG,CAAC,EAAE,MAAM,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC;IAClC;;;;OAIG;IACH,MAAM,CAAC,EAAE,KAAK,EAAE,CAAC;CAClB;AAED;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,GAAG,QAAQ,GAAG,YAAY,CAAC;AAEvD;;;;;;;;GAQG;AACH,MAAM,WAAW,iBAAiB;IAChC,gBAAgB,EAAE,gBAAgB,CAAC;IACnC;;;;OAIG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,iBAAiB,CAAC;IAC/B,kBAAkB,CAAC,EAAE,cAAc,GAAG,WAAW,GAAG,UAAU,CAAC;IAC/D,aAAa,CAAC,EAAE,YAAY,GAAG,gBAAgB,CAAC;CACjD;AAED;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,GAAG,EAAE,SAAS,CAAC,kBAAkB,EAAE,CAAC;IACpC,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAChC,WAAW,EAAE,iBAAiB,EAC9B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC9B,mBAAmB,CAerB;AAED;;;GAGG;AACH,wBAAgB,gCAAgC,CAC9C,KAAK,EAAE,iBAAiB,EACxB,mBAAmB,EAAE,SAAS,CAAC,kBAAkB,EAAE,GAClD,SAAS,CAAC,mCAAmC,CAU/C"}

package/dist/commonjs/notifications.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveSubscribers = resolveSubscribers;
+exports.toCfnNotificationWithSubscribers = toCfnNotificationWithSubscribers;
+const core_1 = require("@composurecdk/core");
+/**
+ * Resolve a {@link NotifySubscribers} into the CloudFormation shape for
+ * `AWS::Budgets::Budget`'s `Subscribers` array, plus any SNS topic
+ * referenced so the caller can create a matching topic policy.
+ *
+ * The SNS subscriber (if any) is emitted first, followed by emails in
+ * declaration order — the order is not load-bearing, but stable output
+ * keeps test snapshots steady.
+ */
+function resolveSubscribers(subscribers, context) {
+    const cfn = [];
+    const snsTopics = [];
+    if (subscribers.sns !== undefined) {
+        const topic = (0, core_1.resolve)(subscribers.sns, context);
+        cfn.push({ address: topic.topicArn, subscriptionType: "SNS" });
+        snsTopics.push(topic);
+    }
+    for (const address of subscribers.emails ?? []) {
+        cfn.push({ address, subscriptionType: "EMAIL" });
+    }
+    return { cfn, snsTopics };
+}
+/**
+ * Convert a {@link NotificationEntry} plus resolved subscribers into the
+ * CloudFormation `NotificationWithSubscribersProperty` shape.
+ */
+function toCfnNotificationWithSubscribers(entry, resolvedSubscribers) {
+    return {
+        notification: {
+            notificationType: entry.notificationType,
+            threshold: entry.threshold,
+            comparisonOperator: entry.comparisonOperator ?? "GREATER_THAN",
+            thresholdType: entry.thresholdType ?? "PERCENTAGE",
+        },
+        subscribers: resolvedSubscribers,
+    };
+}
+//# sourceMappingURL=notifications.js.map

package/dist/commonjs/notifications.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"notifications.js","sourceRoot":"","sources":["../../src/notifications.ts"],"names":[],"mappings":";;AAsFA,gDAkBC;AAMD,4EAaC;AAzHD,6CAA8D;AA2E9D;;;;;;;;GAQG;AACH,SAAgB,kBAAkB,CAChC,WAA8B,EAC9B,OAA+B;IAE/B,MAAM,GAAG,GAAmC,EAAE,CAAC;IAC/C,MAAM,SAAS,GAAa,EAAE,CAAC;IAE/B,IAAI,WAAW,CAAC,GAAG,KAAK,SAAS,EAAE,CAAC;QAClC,MAAM,KAAK,GAAG,IAAA,cAAO,EAAC,WAAW,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;QAChD,GAAG,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,KAAK,CAAC,QAAQ,EAAE,gBAAgB,EAAE,KAAK,EAAE,CAAC,CAAC;QAC/D,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACxB,CAAC;IAED,KAAK,MAAM,OAAO,IAAI,WAAW,CAAC,MAAM,IAAI,EAAE,EAAE,CAAC;QAC/C,GAAG,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,gBAAgB,EAAE,OAAO,EAAE,CAAC,CAAC;IACnD,CAAC;IAED,OAAO,EAAE,GAAG,EAAE,SAAS,EAAE,CAAC;AAC5B,CAAC;AAED;;;GAGG;AACH,SAAgB,gCAAgC,CAC9C,KAAwB,EACxB,mBAAmD;IAEnD,OAAO;QACL,YAAY,EAAE;YACZ,gBAAgB,EAAE,KAAK,CAAC,gBAAgB;YACxC,SAAS,EAAE,KAAK,CAAC,SAAS;YAC1B,kBAAkB,EAAE,KAAK,CAAC,kBAAkB,IAAI,cAAc;YAC9D,aAAa,EAAE,KAAK,CAAC,aAAa,IAAI,YAAY;SACnD;QACD,WAAW,EAAE,mBAAmB;KACjC,CAAC;AACJ,CAAC"}

package/dist/commonjs/package.json

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"topic-policy.d.ts","sourceRoot":"","sources":["../../src/topic-policy.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,MAAM,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAC/D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,UAAU,EACjB,EAAE,EAAE,MAAM,EACV,MAAM,EAAE,MAAM,EAAE,GACf,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CA2B7B"}

package/dist/commonjs/topic-policy.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createBudgetsTopicPolicies = createBudgetsTopicPolicies;
+const aws_iam_1 = require("aws-cdk-lib/aws-iam");
+const aws_sns_1 = require("aws-cdk-lib/aws-sns");
+/**
+ * Create an `AWS::SNS::TopicPolicy` granting the AWS Budgets service
+ * principal (`budgets.amazonaws.com`) permission to publish to each of
+ * the supplied topics.
+ *
+ * Without this policy, a budget notification configured with an SNS
+ * subscriber will silently fail to deliver — one of the most common
+ * footguns when wiring Budgets to SNS by hand. The builder wires it up
+ * automatically whenever at least one `SNS` subscriber is configured.
+ *
+ * Each topic gets its own `TopicPolicy` construct, keyed by the topic's
+ * fully-qualified CDK node path, so callers can inspect or extend them
+ * via the build result.
+ *
+ * @see https://docs.aws.amazon.com/cost-management/latest/userguide/budgets-sns-policy.html
+ */
+function createBudgetsTopicPolicies(scope, id, topics) {
+    const policies = {};
+    const seen = new Set();
+    for (const topic of topics) {
+        const key = topic.node.path;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        const policy = new aws_sns_1.TopicPolicy(scope, `${id}TopicPolicy${topic.node.addr}`, {
+            topics: [topic],
+            policyDocument: undefined,
+        });
+        policy.document.addStatements(new aws_iam_1.PolicyStatement({
+            sid: "AllowBudgetsPublish",
+            effect: aws_iam_1.Effect.ALLOW,
+            principals: [new aws_iam_1.ServicePrincipal("budgets.amazonaws.com")],
+            actions: ["SNS:Publish"],
+            resources: [topic.topicArn],
+        }));
+        policies[key] = policy;
+    }
+    return policies;
+}
+//# sourceMappingURL=topic-policy.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"topic-policy.js","sourceRoot":"","sources":["../../src/topic-policy.ts"],"names":[],"mappings":";;AAoBA,gEA+BC;AAnDD,iDAAgF;AAChF,iDAA+D;AAG/D;;;;;;;;;;;;;;;GAeG;AACH,SAAgB,0BAA0B,CACxC,KAAiB,EACjB,EAAU,EACV,MAAgB;IAEhB,MAAM,QAAQ,GAAgC,EAAE,CAAC;IACjD,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAE/B,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,MAAM,GAAG,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC;QAC5B,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;YAAE,SAAS;QAC5B,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAEd,MAAM,MAAM,GAAG,IAAI,qBAAW,CAAC,KAAK,EAAE,GAAG,EAAE,cAAc,KAAK,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE;YAC1E,MAAM,EAAE,CAAC,KAAK,CAAC;YACf,cAAc,EAAE,SAAS;SAC1B,CAAC,CAAC;QACH,MAAM,CAAC,QAAQ,CAAC,aAAa,CAC3B,IAAI,yBAAe,CAAC;YAClB,GAAG,EAAE,qBAAqB;YAC1B,MAAM,EAAE,gBAAM,CAAC,KAAK;YACpB,UAAU,EAAE,CAAC,IAAI,0BAAgB,CAAC,uBAAuB,CAAC,CAAC;YAC3D,OAAO,EAAE,CAAC,aAAa,CAAC;YACxB,SAAS,EAAE,CAAC,KAAK,CAAC,QAAQ,CAAC;SAC5B,CAAC,CACH,CAAC;QAEF,QAAQ,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC;IACzB,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC"}

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

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

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

@@ -0,0 +1,150 @@
+import { type CfnBudget } from "aws-cdk-lib/aws-budgets";
+import { type Alarm } from "aws-cdk-lib/aws-cloudwatch";
+import { type IConstruct } from "constructs";
+import { COPY_STATE, type Lifecycle, type Resolvable } from "@composurecdk/core";
+import { type ITaggedBuilder } from "@composurecdk/cloudformation";
+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 = ITaggedBuilder<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;
+    /** @internal — see ADR-0005. */
+    [COPY_STATE](target: BudgetAlarmBuilder): void;
+    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/esm/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,EAAE,UAAU,EAAE,KAAK,SAAS,EAAW,KAAK,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAC1F,OAAO,EAAE,KAAK,cAAc,EAAiB,MAAM,8BAA8B,CAAC;AAElF,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,cAAc,CAAC,uBAAuB,EAAE,kBAAkB,CAAC,CAAC;AAsB9F;;;;;;;;;;;;;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,gCAAgC;IAChC,CAAC,UAAU,CAAC,CAAC,MAAM,EAAE,kBAAkB,GAAG,IAAI;IAK9C,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 → esm/budget-alarm-builder.js}

@@ -1,5 +1,6 @@
 import { Annotations, Stack, Token } from "aws-cdk-lib";
-import { Builder, resolve, } from "@composurecdk/core";
+import { COPY_STATE, resolve } from "@composurecdk/core";
+import { taggedBuilder } from "@composurecdk/cloudformation";
 import { AlarmDefinitionBuilder, createAlarms } from "@composurecdk/cloudwatch";
 import { resolveBudgetAlarmDefinitions } from "./budget-alarms.js";
 /**
@@ -86,6 +87,11 @@ class BudgetAlarmBuilder {
         this.#customAlarms.push(configure(new AlarmDefinitionBuilder(key)));
         return this;
     }
+    /** @internal — see ADR-0005. */
+    [COPY_STATE](target) {
+        target.#budget = this.#budget;
+        target.#customAlarms.push(...this.#customAlarms);
+    }
     build(scope, id, context) {
         const target = this.#budget ? resolve(this.#budget, context ?? {}) : undefined;
         return {
@@ -134,6 +140,6 @@ class BudgetAlarmBuilder {
  * budget from custom alarms via `.addAlarm()`.
  */
 export function createBudgetAlarmBuilder() {
-    return Builder(BudgetAlarmBuilder);
+    return taggedBuilder(BudgetAlarmBuilder);
 }
 //# sourceMappingURL=budget-alarm-builder.js.map

package/dist/esm/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/esm/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/esm/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;AAK3D;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,6BAA6B,CAC3C,MAAM,EAAE,iBAAiB,GAAG,SAAS,GACpC,eAAe,EAAE,CA0BnB"}

package/dist/esm/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;AAG1F,OAAO,EAAE,yBAAyB,EAAE,MAAM,eAAe,CAAC;AAE1D,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;IACvC,yBAAyB,CAAC,QAAQ,EAAE,uCAAuC,CAAC,CAAC;IAE7E,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"}