@composurecdk/budgets 0.6.0 → 0.8.0

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

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=alarm-config.js.map

package/dist/{alarm-config.js.map → commonjs/alarm-config.js.map}

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

package/dist/{budget-alarm-builder.d.ts → commonjs/budget-alarm-builder.d.ts}

@@ -1,7 +1,8 @@
 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 { 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";
@@ -54,7 +55,7 @@ export interface BudgetAlarmBuilderResult {
  *
  * @see {@link createBudgetAlarmBuilder}
  */
-export type IBudgetAlarmBuilder = IBuilder<BudgetAlarmBuilderProps, BudgetAlarmBuilder>;
+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
@@ -103,6 +104,8 @@ declare class BudgetAlarmBuilder implements Lifecycle<BudgetAlarmBuilderResult>
      * 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;
 }
 /**

package/dist/commonjs/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/commonjs/budget-alarm-builder.js

@@ -0,0 +1,149 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildBudgetAlarms = buildBudgetAlarms;
+exports.createBudgetAlarmBuilder = createBudgetAlarmBuilder;
+const aws_cdk_lib_1 = require("aws-cdk-lib");
+const core_1 = require("@composurecdk/core");
+const cloudformation_1 = require("@composurecdk/cloudformation");
+const cloudwatch_1 = require("@composurecdk/cloudwatch");
+const budget_alarms_js_1 = require("./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 = aws_cdk_lib_1.Stack.of(scope).region;
+    if (aws_cdk_lib_1.Token.isUnresolved(region))
+        return;
+    if (region === "us-east-1")
+        return;
+    aws_cdk_lib_1.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
+ */
+function buildBudgetAlarms(scope, id, target, options = {}) {
+    const recommended = options.recommendedAlarms;
+    const recommendedDefs = recommended === false ? [] : (0, budget_alarms_js_1.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 (0, cloudwatch_1.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 cloudwatch_1.AlarmDefinitionBuilder(key)));
+        return this;
+    }
+    /** @internal — see ADR-0005. */
+    [core_1.COPY_STATE](target) {
+        target.#budget = this.#budget;
+        target.#customAlarms.push(...this.#customAlarms);
+    }
+    build(scope, id, context) {
+        const target = this.#budget ? (0, core_1.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()`.
+ */
+function createBudgetAlarmBuilder() {
+    return (0, cloudformation_1.taggedBuilder)(BudgetAlarmBuilder);
+}
+//# sourceMappingURL=budget-alarm-builder.js.map

package/dist/commonjs/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/commonjs/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/commonjs/budget-alarms.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveBudgetAlarmDefinitions = resolveBudgetAlarmDefinitions;
+const aws_cdk_lib_1 = require("aws-cdk-lib");
+const aws_cloudwatch_1 = require("aws-cdk-lib/aws-cloudwatch");
+const currency_js_1 = require("./currency.js");
+const BILLING_METRIC_PERIOD = aws_cdk_lib_1.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
+ */
+function resolveBudgetAlarmDefinitions(config) {
+    if (config?.enabled === false)
+        return [];
+    if (!config?.estimatedCharges)
+        return [];
+    const cfg = config.estimatedCharges;
+    const currency = cfg.currency ?? "USD";
+    (0, currency_js_1.assertValidBudgetCurrency)(currency, `EstimatedChargesAlarmConfig: currency`);
+    return [
+        {
+            key: "estimatedCharges",
+            metric: new aws_cloudwatch_1.Metric({
+                namespace: "AWS/Billing",
+                metricName: "EstimatedCharges",
+                dimensionsMap: { Currency: currency },
+                statistic: "Maximum",
+                period: BILLING_METRIC_PERIOD,
+            }),
+            threshold: cfg.threshold,
+            comparisonOperator: aws_cloudwatch_1.ComparisonOperator.GREATER_THAN_THRESHOLD,
+            evaluationPeriods: cfg.evaluationPeriods ?? 1,
+            datapointsToAlarm: cfg.datapointsToAlarm ?? 1,
+            treatMissingData: cfg.treatMissingData ?? aws_cloudwatch_1.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/commonjs/budget-alarms.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"budget-alarms.js","sourceRoot":"","sources":["../../src/budget-alarms.ts"],"names":[],"mappings":";;AA0BA,sEA4BC;AAtDD,6CAAuC;AACvC,+DAA0F;AAG1F,+CAA0D;AAE1D,MAAM,qBAAqB,GAAG,sBAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AAEhD;;;;;;;;;;;;;;;;;GAiBG;AACH,SAAgB,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,IAAA,uCAAyB,EAAC,QAAQ,EAAE,uCAAuC,CAAC,CAAC;IAE7E,OAAO;QACL;YACE,GAAG,EAAE,kBAAkB;YACvB,MAAM,EAAE,IAAI,uBAAM,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,mCAAkB,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,iCAAgB,CAAC,aAAa;YACxE,WAAW,EAAE,4CAA4C,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,QAAQ,kDAAkD;SAC7I;KACF,CAAC;AACJ,CAAC"}

package/dist/{budget-builder.d.ts → commonjs/budget-builder.d.ts}

@@ -2,7 +2,7 @@ import { CfnBudget } from "aws-cdk-lib/aws-budgets";
 import { type Alarm } from "aws-cdk-lib/aws-cloudwatch";
 import type { TopicPolicy } from "aws-cdk-lib/aws-sns";
 import type { IConstruct } from "constructs";
-import { type IBuilder, type Lifecycle } from "@composurecdk/core";
+import { COPY_STATE, type IBuilder, type Lifecycle } from "@composurecdk/core";
 import { AlarmDefinitionBuilder } from "@composurecdk/cloudwatch";
 import type { BudgetAlarmConfig } from "./alarm-config.js";
 import { type NotificationEntry, type NotifySubscribers } from "./notifications.js";
@@ -180,6 +180,8 @@ declare class BudgetBuilder implements Lifecycle<BudgetBuilderResult> {
      * {@link createBudgetAlarmBuilder} into a `us-east-1` stack.
      */
     addAlarm(key: string, configure: (alarm: AlarmDefinitionBuilder<CfnBudget>) => AlarmDefinitionBuilder<CfnBudget>): this;
+    /** @internal — see ADR-0005. */
+    [COPY_STATE](target: BudgetBuilder): void;
     build(scope: IConstruct, id: string, context?: Record<string, object>): BudgetBuilderResult;
 }
 /**

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

@@ -0,0 +1 @@
+{"version":3,"file":"budget-builder.d.ts","sourceRoot":"","sources":["../../src/budget-builder.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAuB,MAAM,yBAAyB,CAAC;AACzE,OAAO,EAAE,KAAK,KAAK,EAAE,MAAM,4BAA4B,CAAC;AACxD,OAAO,KAAK,EAAU,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAC/D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EAAW,UAAU,EAAE,KAAK,QAAQ,EAAE,KAAK,SAAS,EAAE,MAAM,oBAAoB,CAAC;AACxF,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAI3D,OAAO,EACL,KAAK,iBAAiB,EAEtB,KAAK,iBAAiB,EAGvB,MAAM,oBAAoB,CAAC;AAK5B;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,qBAAqB;IACrB,MAAM,EAAE,MAAM,CAAC;IACf;;;;;;;;;OASG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,+DAA+D;IAC/D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,yBAAyB;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,yDAAyD;IACzD,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IACvC,8CAA8C;IAC9C,SAAS,CAAC,EAAE,SAAS,CAAC,iBAAiB,CAAC;IACxC;;;;;;;;;;;;;;;;;OAiBG;IACH,iBAAiB,CAAC,EAAE,iBAAiB,GAAG,KAAK,CAAC;CAC/C;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,4CAA4C;IAC5C,MAAM,EAAE,SAAS,CAAC;IAClB;;;;;;;OAOG;IACH,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IAC3C;;;;;;;;;;OAUG;IACH,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;CAC/B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,MAAM,MAAM,cAAc,GAAG,QAAQ,CAAC,kBAAkB,EAAE,aAAa,CAAC,CAAC;AAEzE,cAAM,aAAc,YAAW,SAAS,CAAC,mBAAmB,CAAC;;IAC3D,KAAK,EAAE,OAAO,CAAC,kBAAkB,CAAC,CAAM;IAIxC;;;;;;;;;OASG;IACH,cAAc,CAAC,gBAAgB,EAAE,MAAM,EAAE,WAAW,EAAE,iBAAiB,GAAG,IAAI;IAI9E;;;;;;;;OAQG;IACH,kBAAkB,CAAC,gBAAgB,EAAE,MAAM,EAAE,WAAW,EAAE,iBAAiB,GAAG,IAAI;IAIlF;;;OAGG;IACH,eAAe,CAAC,KAAK,EAAE,iBAAiB,GAAG,IAAI;IAK/C;;;;;;;;;;OAUG;IACH,yBAAyB,CAAC,WAAW,EAAE,iBAAiB,GAAG,IAAI;IAc/D;;;;;;;;;;;;;OAaG;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,aAAa,GAAG,IAAI;IAKzC,KAAK,CAAC,KAAK,EAAE,UAAU,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,GAAG,mBAAmB;CAkGhG;AAWD;;GAEG;AACH,wBAAgB,mBAAmB,IAAI,cAAc,CAGpD"}

package/dist/commonjs/budget-builder.js

@@ -0,0 +1,170 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createBudgetBuilder = createBudgetBuilder;
+const aws_budgets_1 = require("aws-cdk-lib/aws-budgets");
+const core_1 = require("@composurecdk/core");
+const cloudwatch_1 = require("@composurecdk/cloudwatch");
+const budget_alarm_builder_js_1 = require("./budget-alarm-builder.js");
+const currency_js_1 = require("./currency.js");
+const defaults_js_1 = require("./defaults.js");
+const notifications_js_1 = require("./notifications.js");
+const topic_policy_js_1 = require("./topic-policy.js");
+const MAX_EMAILS_PER_NOTIFICATION = 10;
+class BudgetBuilder {
+    props = {};
+    #notifications = [];
+    #customAlarms = [];
+    /**
+     * Add a notification that fires when ACTUAL spend crosses the given
+     * percentage of the budget limit.
+     *
+     * @param thresholdPercent - Percentage of the budget limit (e.g. `80`).
+     *   For absolute-value thresholds, use {@link addNotification} directly.
+     * @param subscribers - Up to one SNS topic plus up to ten validated
+     *   email addresses. AWS Budgets caps each notification at 1 SNS + up
+     *   to 10 EMAIL subscribers.
+     */
+    notifyOnActual(thresholdPercent, subscribers) {
+        return this.#addPercentageNotification("ACTUAL", thresholdPercent, subscribers);
+    }
+    /**
+     * Add a notification that fires when FORECASTED spend crosses the
+     * given percentage of the budget limit.
+     *
+     * @param thresholdPercent - Percentage of the budget limit (e.g. `100`).
+     *   For absolute-value thresholds, use {@link addNotification} directly.
+     * @param subscribers - Up to one SNS topic plus up to ten validated
+     *   email addresses.
+     */
+    notifyOnForecasted(thresholdPercent, subscribers) {
+        return this.#addPercentageNotification("FORECASTED", thresholdPercent, subscribers);
+    }
+    /**
+     * Raw notification passthrough for callers that need the full
+     * CloudFormation surface (e.g. absolute-value thresholds).
+     */
+    addNotification(entry) {
+        this.#notifications.push(entry);
+        return this;
+    }
+    /**
+     * Apply the well-architected recommended notification thresholds:
+     *
+     * - `ACTUAL` at 80% — early warning before breach.
+     * - `FORECASTED` at 100% — trending-over-budget alert.
+     *
+     * Must be called with at least one subscriber; the same subscriber
+     * set is used for both thresholds.
+     *
+     * @see https://docs.aws.amazon.com/cost-management/latest/userguide/budgets-best-practices.html
+     */
+    withRecommendedThresholds(subscribers) {
+        if (!hasAnySubscriber(subscribers)) {
+            throw new Error(`BudgetBuilder: withRecommendedThresholds(...) must be called with at least one subscriber.`);
+        }
+        const { actualPercent, forecastedPercent } = defaults_js_1.BUDGET_DEFAULTS.recommendedThresholds;
+        this.#notifications.push({ notificationType: "ACTUAL", threshold: actualPercent, subscribers }, { notificationType: "FORECASTED", threshold: forecastedPercent, subscribers });
+        return this;
+    }
+    /**
+     * Adds a custom CloudWatch 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.
+     *
+     * Custom alarms are materialised in this builder's stack alongside any
+     * recommended alarms. Like the recommended `EstimatedCharges` alarm,
+     * custom alarms on `AWS/Billing` metrics will only fire when this
+     * stack is in `us-east-1` — the builder emits the same synth-time
+     * warning (`@composurecdk/budgets:alarm-region`) when used elsewhere.
+     * For non-`us-east-1` stacks, route alarms via
+     * {@link createBudgetAlarmBuilder} into a `us-east-1` stack.
+     */
+    addAlarm(key, configure) {
+        this.#customAlarms.push(configure(new cloudwatch_1.AlarmDefinitionBuilder(key)));
+        return this;
+    }
+    /** @internal — see ADR-0005. */
+    [core_1.COPY_STATE](target) {
+        target.#notifications.push(...this.#notifications);
+        target.#customAlarms.push(...this.#customAlarms);
+    }
+    build(scope, id, context = {}) {
+        const { recommendedAlarms: alarmConfig, ...budgetProps } = this.props;
+        const budgetType = budgetProps.budgetType ?? defaults_js_1.BUDGET_DEFAULTS.budgetType;
+        const timeUnit = budgetProps.timeUnit ?? defaults_js_1.BUDGET_DEFAULTS.timeUnit;
+        const requiresLimit = budgetType === "COST" || budgetType === "USAGE";
+        if (requiresLimit && !budgetProps.limit) {
+            throw new Error(`BudgetBuilder "${id}": limit({ amount, unit }) must be set for ${budgetType} budgets.`);
+        }
+        const limitUnit = budgetProps.limit?.unit ?? defaults_js_1.BUDGET_DEFAULTS.limitUnit;
+        if (budgetType === "COST" && budgetProps.limit) {
+            (0, currency_js_1.assertValidBudgetCurrency)(limitUnit, `BudgetBuilder "${id}": limit unit`);
+            (0, currency_js_1.warnIfNonUsdCurrency)(scope, limitUnit, `BudgetBuilder "${id}": limit unit`);
+        }
+        const { notificationsWithSubscribers, snsTopics } = this.#buildNotifications(id, context);
+        const budgetData = {
+            budgetName: budgetProps.budgetName,
+            budgetType,
+            timeUnit,
+            ...(budgetProps.limit
+                ? {
+                    budgetLimit: {
+                        amount: budgetProps.limit.amount,
+                        unit: limitUnit,
+                    },
+                }
+                : {}),
+            ...(budgetProps.costFilters ? { costFilters: budgetProps.costFilters } : {}),
+            ...(budgetProps.costTypes ? { costTypes: budgetProps.costTypes } : {}),
+        };
+        const cfnProps = {
+            budget: budgetData,
+            ...(notificationsWithSubscribers.length > 0 ? { notificationsWithSubscribers } : {}),
+        };
+        const budget = new aws_budgets_1.CfnBudget(scope, id, cfnProps);
+        const topicPolicies = (0, topic_policy_js_1.createBudgetsTopicPolicies)(scope, id, snsTopics);
+        const alarms = (0, budget_alarm_builder_js_1.buildBudgetAlarms)(scope, id, { budget }, {
+            recommendedAlarms: alarmConfig,
+            customAlarms: this.#customAlarms,
+        });
+        return { budget, topicPolicies, alarms };
+    }
+    #addPercentageNotification(notificationType, thresholdPercent, subscribers) {
+        if (!hasAnySubscriber(subscribers)) {
+            throw new Error(`BudgetBuilder: ${notificationType} notification at ${String(thresholdPercent)}% requires at least one subscriber.`);
+        }
+        this.#notifications.push({ notificationType, threshold: thresholdPercent, subscribers });
+        return this;
+    }
+    #buildNotifications(id, context) {
+        const notificationsWithSubscribers = [];
+        const allSnsTopics = [];
+        for (const entry of this.#notifications) {
+            const emailCount = entry.subscribers.emails?.length ?? 0;
+            if (emailCount > MAX_EMAILS_PER_NOTIFICATION) {
+                throw new Error(`BudgetBuilder "${id}": ${describeNotification(entry)} has ${String(emailCount)} email subscribers; ` +
+                    `AWS Budgets allows at most ${String(MAX_EMAILS_PER_NOTIFICATION)} email subscribers per notification (plus up to 1 SNS topic).`);
+            }
+            const resolved = (0, notifications_js_1.resolveSubscribers)(entry.subscribers, context);
+            notificationsWithSubscribers.push((0, notifications_js_1.toCfnNotificationWithSubscribers)(entry, resolved.cfn));
+            allSnsTopics.push(...resolved.snsTopics);
+        }
+        return { notificationsWithSubscribers, snsTopics: allSnsTopics };
+    }
+}
+function hasAnySubscriber(subscribers) {
+    return subscribers.sns !== undefined || (subscribers.emails?.length ?? 0) > 0;
+}
+function describeNotification(entry) {
+    const unit = (entry.thresholdType ?? "PERCENTAGE") === "PERCENTAGE" ? "%" : "";
+    return `notification ${entry.notificationType} @ ${String(entry.threshold)}${unit}`;
+}
+/**
+ * Creates a new {@link IBudgetBuilder} for configuring an AWS Budget.
+ */
+function createBudgetBuilder() {
+    // eslint-disable-next-line composurecdk/builder-must-be-tagged -- AWS::Budgets::Budget has no Tags property
+    return (0, core_1.Builder)(BudgetBuilder);
+}
+//# sourceMappingURL=budget-builder.js.map

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"currency.d.ts","sourceRoot":"","sources":["../../src/currency.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAG7C;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAM7E;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAS3F"}

package/dist/commonjs/currency.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertValidBudgetCurrency = assertValidBudgetCurrency;
+exports.warnIfNonUsdCurrency = warnIfNonUsdCurrency;
+const aws_cdk_lib_1 = require("aws-cdk-lib");
+const defaults_js_1 = require("./defaults.js");
+/**
+ * Throws if `unit` is not in {@link DEFAULT_BUDGET_CURRENCIES}.
+ *
+ * `context` is woven into the message (e.g. `BudgetBuilder "X": limit
+ * unit ...`) so callers can blame the right field. Catches typos like
+ * `"USDD"` or `"ZZZ"` at synth instead of mid-deploy.
+ */
+function assertValidBudgetCurrency(unit, context) {
+    if (defaults_js_1.DEFAULT_BUDGET_CURRENCIES.includes(unit))
+        return;
+    throw new Error(`${context}: "${unit}" is not a recognised AWS Budgets currency code. ` +
+        `Expected one of: ${defaults_js_1.DEFAULT_BUDGET_CURRENCIES.join(", ")}.`);
+}
+/**
+ * Annotates `scope` with a non-fatal warning when `unit` is anything
+ * other than `USD`. The synth context cannot see an account's billing
+ * currency, and AWS Budgets rejects `BudgetLimit.Unit` values that
+ * don't match it — so a non-USD configuration deserves a "make sure
+ * this matches your billing currency" nudge.
+ *
+ * Short-circuits on unresolved tokens so env-agnostic stacks aren't
+ * spammed.
+ */
+function warnIfNonUsdCurrency(scope, unit, context) {
+    if (aws_cdk_lib_1.Token.isUnresolved(unit))
+        return;
+    if (unit === "USD")
+        return;
+    aws_cdk_lib_1.Annotations.of(scope).addWarningV2("@composurecdk/budgets:limit-currency", `${context}: currency "${unit}" must match the account's billing currency or AWS Budgets ` +
+        `will reject the request at deploy time. Most accounts default to USD; verify yours and ` +
+        `suppress this warning if intentional.`);
+}
+//# sourceMappingURL=currency.js.map

package/dist/commonjs/currency.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"currency.js","sourceRoot":"","sources":["../../src/currency.ts"],"names":[],"mappings":";;AAWA,8DAMC;AAYD,oDASC;AAtCD,6CAAiD;AAEjD,+CAA0D;AAE1D;;;;;;GAMG;AACH,SAAgB,yBAAyB,CAAC,IAAY,EAAE,OAAe;IACrE,IAAI,uCAAyB,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,OAAO;IACrD,MAAM,IAAI,KAAK,CACb,GAAG,OAAO,MAAM,IAAI,mDAAmD;QACrE,oBAAoB,uCAAyB,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAC9D,CAAC;AACJ,CAAC;AAED;;;;;;;;;GASG;AACH,SAAgB,oBAAoB,CAAC,KAAiB,EAAE,IAAY,EAAE,OAAe;IACnF,IAAI,mBAAK,CAAC,YAAY,CAAC,IAAI,CAAC;QAAE,OAAO;IACrC,IAAI,IAAI,KAAK,KAAK;QAAE,OAAO;IAC3B,yBAAW,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,YAAY,CAChC,sCAAsC,EACtC,GAAG,OAAO,eAAe,IAAI,6DAA6D;QACxF,yFAAyF;QACzF,uCAAuC,CAC1C,CAAC;AACJ,CAAC"}

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

@@ -0,0 +1 @@
+{"version":3,"file":"defaults.d.ts","sourceRoot":"","sources":["../../src/defaults.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,eAAO,MAAM,eAAe;IAC1B;;;;OAIG;;IAGH;;;;;OAKG;;IAGH;;;;;OAKG;;IAGH;;;;;;;;;OASG;;;;;CAKJ,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,yBAAyB,EAAE,SAAS,MAAM,EAkCtD,CAAC"}

package/dist/commonjs/defaults.js

@@ -0,0 +1,94 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_BUDGET_CURRENCIES = exports.BUDGET_DEFAULTS = void 0;
+/**
+ * Well-architected defaults for {@link createBudgetBuilder}. Each can be
+ * overridden via the builder's fluent API.
+ *
+ * @see https://docs.aws.amazon.com/wellarchitected/latest/cost-optimization-pillar/welcome.html
+ */
+exports.BUDGET_DEFAULTS = {
+    /**
+     * Default budget type — most budgets are cost budgets.
+     *
+     * @see https://docs.aws.amazon.com/aws-cost-management/latest/APIReference/API_budgets_Budget.html
+     */
+    budgetType: "COST",
+    /**
+     * Default tracking period — monthly is the most common granularity and
+     * aligns with AWS billing cycles.
+     *
+     * @see https://docs.aws.amazon.com/cost-management/latest/userguide/budgets-create.html
+     */
+    timeUnit: "MONTHLY",
+    /**
+     * Default spend currency — most customers need to set this; the builder
+     * defaults to USD to align with the AWS Billing reporting default.
+     *
+     * @see https://docs.aws.amazon.com/aws-cost-management/latest/APIReference/API_budgets_Spend.html
+     */
+    limitUnit: "USD",
+    /**
+     * Recommended percentage thresholds applied by
+     * {@link IBudgetBuilder.withRecommendedThresholds}.
+     *
+     * - `ACTUAL` at 80% — early warning before you breach the budget.
+     * - `FORECASTED` at 100% — notifies when forecasted spend trends over
+     *   budget for the period.
+     *
+     * @see https://docs.aws.amazon.com/cost-management/latest/userguide/budgets-best-practices.html
+     */
+    recommendedThresholds: {
+        actualPercent: 80,
+        forecastedPercent: 100,
+    },
+};
+/**
+ * ISO 4217 currency codes accepted by AWS Budgets for `COST` budgets'
+ * `BudgetLimit.Unit` and the `EstimatedCharges` alarm's `Currency`
+ * dimension. Sourced from the AWS Billing supported-currencies list.
+ *
+ * The synth context cannot see an account's billing currency, so the
+ * builder uses this set for shape validation only — a hard error on
+ * anything outside it (catches typos like `"ZZZ"`/`"USDD"`) — and emits
+ * a soft warning when the configured unit is anything other than `USD`,
+ * since most accounts default to USD billing.
+ *
+ * @see https://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/manage-account-payment.html
+ */
+exports.DEFAULT_BUDGET_CURRENCIES = [
+    "AED",
+    "ARS",
+    "AUD",
+    "BRL",
+    "CAD",
+    "CHF",
+    "CLP",
+    "CNY",
+    "COP",
+    "CZK",
+    "DKK",
+    "EUR",
+    "GBP",
+    "HKD",
+    "IDR",
+    "ILS",
+    "INR",
+    "JPY",
+    "KRW",
+    "MXN",
+    "MYR",
+    "NOK",
+    "NZD",
+    "PLN",
+    "RUB",
+    "SAR",
+    "SEK",
+    "SGD",
+    "THB",
+    "TRY",
+    "TWD",
+    "USD",
+    "ZAR",
+];
+//# sourceMappingURL=defaults.js.map

package/dist/commonjs/defaults.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"defaults.js","sourceRoot":"","sources":["../../src/defaults.ts"],"names":[],"mappings":";;;AAAA;;;;;GAKG;AACU,QAAA,eAAe,GAAG;IAC7B;;;;OAIG;IACH,UAAU,EAAE,MAAe;IAE3B;;;;;OAKG;IACH,QAAQ,EAAE,SAAkB;IAE5B;;;;;OAKG;IACH,SAAS,EAAE,KAAK;IAEhB;;;;;;;;;OASG;IACH,qBAAqB,EAAE;QACrB,aAAa,EAAE,EAAE;QACjB,iBAAiB,EAAE,GAAG;KACvB;CACF,CAAC;AAEF;;;;;;;;;;;;GAYG;AACU,QAAA,yBAAyB,GAAsB;IAC1D,KAAK;IACL,KAAK;IACL,KAAK;IACL,KAAK;IACL,KAAK;IACL,KAAK;IACL,KAAK;IACL,KAAK;IACL,KAAK;IACL,KAAK;IACL,KAAK;IACL,KAAK;IACL,KAAK;IACL,KAAK;IACL,KAAK;IACL,KAAK;IACL,KAAK;IACL,KAAK;IACL,KAAK;IACL,KAAK;IACL,KAAK;IACL,KAAK;IACL,KAAK;IACL,KAAK;IACL,KAAK;IACL,KAAK;IACL,KAAK;IACL,KAAK;IACL,KAAK;IACL,KAAK;IACL,KAAK;IACL,KAAK;IACL,KAAK;CACN,CAAC"}

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

@@ -0,0 +1 @@
+{"version":3,"file":"email.d.ts","sourceRoot":"","sources":["../../src/email.ts"],"names":[],"mappings":"AAAA,OAAO,CAAC,MAAM,UAAU,EAAE,OAAO,MAAM,CAAC;AAExC;;;;;;GAMG;AACH,MAAM,MAAM,KAAK,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,CAAC,UAAU,CAAC,EAAE,IAAI,CAAA;CAAE,CAAC;AAK7D;;;;;;;;;;;;;GAaG;AACH,wBAAgB,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,CAc1C"}