@composurecdk/budgets 0.5.0 → 0.6.0

package/README.md

@@ -7,12 +7,12 @@ This package provides a fluent builder for `AWS::Budgets::Budget` with well-arch
 ## Budget Builder
 
 ```ts
-import { createBudgetBuilder } from "@composurecdk/budgets";
+import { createBudgetBuilder, email } from "@composurecdk/budgets";
 
 const budget = createBudgetBuilder()
   .budgetName("AgentBudget")
-  .limit({ amount: 50, unit: "GBP" })
-  .notifyOnActual(100, "ops@example.com")
+  .limit({ amount: 50 })
+  .notifyOnActual(100, { emails: [email("ops@example.com")] })
   .build(stack, "AgentBudget");
 ```
 
@@ -31,34 +31,43 @@ Every field on [CfnBudget.BudgetDataProperty](https://docs.aws.amazon.com/cdk/ap
 
 ### Notifications
 
-Percentage-threshold helpers cover the common case; `addNotification` accepts the raw shape when you need absolute-value thresholds or a different comparison operator.
+Each notification takes a `NotifySubscribers` object with **at most one** `sns` topic and a list of validated `emails` — AWS Budgets caps every notification at 1 SNS subscriber plus up to 10 EMAIL subscribers. The shape encodes that constraint in the type system: passing two SNS topics is unrepresentable.
 
 ```ts
+import { email } from "@composurecdk/budgets";
+
 createBudgetBuilder()
   .limit({ amount: 100 })
-  .notifyOnActual(80, "ops@example.com") // 80% ACTUAL → email
-  .notifyOnForecasted(
-    100,
-    ref("alerts", (r) => r.topic),
-  ) // 100% FORECASTED → SNS topic
+  .notifyOnActual(80, { emails: [email("ops@example.com")] }) // 80% ACTUAL → email
+  .notifyOnForecasted(100, { sns: ref("alerts", (r) => r.topic) }) // 100% FORECASTED → SNS topic
+  .notifyOnActual(100, {
+    sns: killSwitchTopic,
+    emails: [email("oncall@example.com")],
+  }) // hard breach → automation + human
   .addNotification({
     notificationType: "ACTUAL",
     threshold: 120,
     thresholdType: "ABSOLUTE_VALUE",
-    subscribers: ["oncall@example.com"],
+    subscribers: { emails: [email("oncall@example.com")] },
   });
 ```
 
-Subscribers may be email strings, `ITopic` instances, or `Resolvable<ITopic>` references to topics owned by sibling components.
+Email addresses must be constructed via `email(string)`, which validates and brands the value — bare strings are rejected at compile time. The `sns` slot accepts an `ITopic` instance or a `Resolvable<ITopic>` reference to a topic owned by a sibling component.
 
 ### Recommended Thresholds
 
 ```ts
-createBudgetBuilder().limit({ amount: 50 }).withRecommendedThresholds("ops@example.com");
+createBudgetBuilder()
+  .limit({ amount: 50 })
+  .withRecommendedThresholds({ emails: [email("ops@example.com")] });
 ```
 
 Applies the AWS Cost Optimization pillar defaults: `ACTUAL` at 80% and `FORECASTED` at 100%.
 
+### Currency
+
+`limit({ amount, unit })` validates `unit` against the AWS-Budgets-supported ISO 4217 set (`DEFAULT_BUDGET_CURRENCIES`). Typos like `"ZZZ"` throw at synth instead of mid-deploy. Because the synth context cannot see an account's billing currency, anything other than `"USD"` also emits a non-fatal warning (`@composurecdk/budgets:limit-currency`) — verify the configured unit matches your billing currency before deploying.
+
 ## Defaults
 
 | Property                                  | Default     | Rationale                                                                     |

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

@@ -1 +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"}
+{"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/budget-alarms.js

@@ -1,5 +1,6 @@
 import { Duration } from "aws-cdk-lib";
 import { ComparisonOperator, Metric, TreatMissingData } from "aws-cdk-lib/aws-cloudwatch";
+import { assertValidBudgetCurrency } from "./currency.js";
 const BILLING_METRIC_PERIOD = Duration.hours(6);
 /**
  * Resolves the recommended alarm configuration into fully-resolved
@@ -26,6 +27,7 @@ export function resolveBudgetAlarmDefinitions(config) {
         return [];
     const cfg = config.estimatedCharges;
     const currency = cfg.currency ?? "USD";
+    assertValidBudgetCurrency(currency, `EstimatedChargesAlarmConfig: currency`);
     return [
         {
             key: "estimatedCharges",

package/dist/budget-alarms.js.map

@@ -1 +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"}
+{"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"}

package/dist/budget-builder.d.ts

@@ -5,7 +5,7 @@ import type { IConstruct } from "constructs";
 import { type IBuilder, type Lifecycle } from "@composurecdk/core";
 import { AlarmDefinitionBuilder } from "@composurecdk/cloudwatch";
 import type { BudgetAlarmConfig } from "./alarm-config.js";
-import { type BudgetSubscriber, type NotificationEntry } from "./notifications.js";
+import { type NotificationEntry, type NotifySubscribers } from "./notifications.js";
 /**
  * Spend limit for a cost or usage budget.
  */
@@ -15,6 +15,12 @@ export interface BudgetLimit {
     /**
      * Currency or usage unit. Defaults to
      * {@link BUDGET_DEFAULTS.limitUnit} when omitted.
+     *
+     * For `COST` budgets, must be a recognised AWS Budgets currency
+     * (validated at synth — see {@link DEFAULT_BUDGET_CURRENCIES}). The
+     * builder also emits a non-fatal warning when this is anything other
+     * than `"USD"`, since the account's billing currency isn't visible
+     * at synth and a mismatch is rejected at deploy time.
      */
     unit?: string;
 }
@@ -108,9 +114,12 @@ export interface BudgetBuilderResult {
  * ```ts
  * createBudgetBuilder()
  *   .budgetName("AgentBudget")
- *   .limit({ amount: 50, unit: "GBP" })
- *   .notifyOnActual(100, ref("alerts", r => r.topic))
- *   .withRecommendedThresholds()
+ *   .limit({ amount: 50 })
+ *   .notifyOnActual(100, {
+ *     emails: [email("ops@example.com")],
+ *     sns: ref("alerts", r => r.topic),
+ *   })
+ *   .withRecommendedThresholds({ emails: [email("ops@example.com")] })
  *   .build(stack, "AgentBudget");
  * ```
  */
@@ -124,18 +133,21 @@ declare class BudgetBuilder implements Lifecycle<BudgetBuilderResult> {
      *
      * @param thresholdPercent - Percentage of the budget limit (e.g. `80`).
      *   For absolute-value thresholds, use {@link addNotification} directly.
-     * @param subscribers - One or more email addresses / SNS topics (or
-     *   {@link Resolvable} refs to topics).
+     * @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: number, ...subscribers: BudgetSubscriber[]): this;
+    notifyOnActual(thresholdPercent: number, subscribers: NotifySubscribers): this;
     /**
      * 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: number, ...subscribers: BudgetSubscriber[]): this;
+    notifyOnForecasted(thresholdPercent: number, subscribers: NotifySubscribers): this;
     /**
      * Raw notification passthrough for callers that need the full
      * CloudFormation surface (e.g. absolute-value thresholds).
@@ -148,11 +160,11 @@ declare class BudgetBuilder implements Lifecycle<BudgetBuilderResult> {
      * - `FORECASTED` at 100% — trending-over-budget alert.
      *
      * Must be called with at least one subscriber; the same subscriber
-     * list is used for both thresholds.
+     * set is used for both thresholds.
      *
      * @see https://docs.aws.amazon.com/cost-management/latest/userguide/budgets-best-practices.html
      */
-    withRecommendedThresholds(...subscribers: BudgetSubscriber[]): this;
+    withRecommendedThresholds(subscribers: NotifySubscribers): this;
     /**
      * Adds a custom CloudWatch alarm against the budget. The configure
      * callback receives a fresh {@link AlarmDefinitionBuilder} pre-set with

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

@@ -1 +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,KAAK,QAAQ,EAAE,KAAK,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAC5E,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAG3D,OAAO,EACL,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EAIvB,MAAM,oBAAoB,CAAC;AAG5B;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,qBAAqB;IACrB,MAAM,EAAE,MAAM,CAAC;IACf;;;OAGG;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;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,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;;;;;;;;OAQG;IACH,cAAc,CAAC,gBAAgB,EAAE,MAAM,EAAE,GAAG,WAAW,EAAE,gBAAgB,EAAE,GAAG,IAAI;IAIlF;;;;;;OAMG;IACH,kBAAkB,CAAC,gBAAgB,EAAE,MAAM,EAAE,GAAG,WAAW,EAAE,gBAAgB,EAAE,GAAG,IAAI;IAItF;;;OAGG;IACH,eAAe,CAAC,KAAK,EAAE,iBAAiB,GAAG,IAAI;IAK/C;;;;;;;;;;OAUG;IACH,yBAAyB,CAAC,GAAG,WAAW,EAAE,gBAAgB,EAAE,GAAG,IAAI;IAcnE;;;;;;;;;;;;;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,KAAK,CAAC,KAAK,EAAE,UAAU,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,GAAG,mBAAmB;CAiFhG;AAED;;GAEG;AACH,wBAAgB,mBAAmB,IAAI,cAAc,CAEpD"}
+{"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,KAAK,QAAQ,EAAE,KAAK,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAC5E,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;AACH,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,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,CAEpD"}

package/dist/budget-builder.js

@@ -2,9 +2,11 @@ import { CfnBudget } from "aws-cdk-lib/aws-budgets";
 import { Builder } from "@composurecdk/core";
 import { AlarmDefinitionBuilder } from "@composurecdk/cloudwatch";
 import { buildBudgetAlarms } from "./budget-alarm-builder.js";
+import { assertValidBudgetCurrency, warnIfNonUsdCurrency } from "./currency.js";
 import { BUDGET_DEFAULTS } from "./defaults.js";
 import { resolveSubscribers, toCfnNotificationWithSubscribers, } from "./notifications.js";
 import { createBudgetsTopicPolicies } from "./topic-policy.js";
+const MAX_EMAILS_PER_NOTIFICATION = 10;
 class BudgetBuilder {
     props = {};
     #notifications = [];
@@ -15,10 +17,11 @@ class BudgetBuilder {
      *
      * @param thresholdPercent - Percentage of the budget limit (e.g. `80`).
      *   For absolute-value thresholds, use {@link addNotification} directly.
-     * @param subscribers - One or more email addresses / SNS topics (or
-     *   {@link Resolvable} refs to topics).
+     * @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) {
+    notifyOnActual(thresholdPercent, subscribers) {
         return this.#addPercentageNotification("ACTUAL", thresholdPercent, subscribers);
     }
     /**
@@ -27,8 +30,10 @@ class BudgetBuilder {
      *
      * @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) {
+    notifyOnForecasted(thresholdPercent, subscribers) {
         return this.#addPercentageNotification("FORECASTED", thresholdPercent, subscribers);
     }
     /**
@@ -46,12 +51,12 @@ class BudgetBuilder {
      * - `FORECASTED` at 100% — trending-over-budget alert.
      *
      * Must be called with at least one subscriber; the same subscriber
-     * list is used for both thresholds.
+     * set is used for both thresholds.
      *
      * @see https://docs.aws.amazon.com/cost-management/latest/userguide/budgets-best-practices.html
      */
-    withRecommendedThresholds(...subscribers) {
-        if (subscribers.length === 0) {
+    withRecommendedThresholds(subscribers) {
+        if (!hasAnySubscriber(subscribers)) {
             throw new Error(`BudgetBuilder: withRecommendedThresholds(...) must be called with at least one subscriber.`);
         }
         const { actualPercent, forecastedPercent } = BUDGET_DEFAULTS.recommendedThresholds;
@@ -84,7 +89,12 @@ class BudgetBuilder {
         if (requiresLimit && !budgetProps.limit) {
             throw new Error(`BudgetBuilder "${id}": limit({ amount, unit }) must be set for ${budgetType} budgets.`);
         }
-        const { notificationsWithSubscribers, snsTopics } = this.#buildNotifications(context);
+        const limitUnit = budgetProps.limit?.unit ?? BUDGET_DEFAULTS.limitUnit;
+        if (budgetType === "COST" && budgetProps.limit) {
+            assertValidBudgetCurrency(limitUnit, `BudgetBuilder "${id}": limit unit`);
+            warnIfNonUsdCurrency(scope, limitUnit, `BudgetBuilder "${id}": limit unit`);
+        }
+        const { notificationsWithSubscribers, snsTopics } = this.#buildNotifications(id, context);
         const budgetData = {
             budgetName: budgetProps.budgetName,
             budgetType,
@@ -93,7 +103,7 @@ class BudgetBuilder {
                 ? {
                     budgetLimit: {
                         amount: budgetProps.limit.amount,
-                        unit: budgetProps.limit.unit ?? BUDGET_DEFAULTS.limitUnit,
+                        unit: limitUnit,
                     },
                 }
                 : {}),
@@ -113,16 +123,21 @@ class BudgetBuilder {
         return { budget, topicPolicies, alarms };
     }
     #addPercentageNotification(notificationType, thresholdPercent, subscribers) {
-        if (subscribers.length === 0) {
+        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(context) {
+    #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 = resolveSubscribers(entry.subscribers, context);
             notificationsWithSubscribers.push(toCfnNotificationWithSubscribers(entry, resolved.cfn));
             allSnsTopics.push(...resolved.snsTopics);
@@ -130,6 +145,13 @@ class BudgetBuilder {
         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.
  */

package/dist/budget-builder.js.map

@@ -1 +1 @@
-{"version":3,"file":"budget-builder.js","sourceRoot":"","sources":["../src/budget-builder.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAuB,MAAM,yBAAyB,CAAC;AAIzE,OAAO,EAAE,OAAO,EAAiC,MAAM,oBAAoB,CAAC;AAC5E,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAElE,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAC9D,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAIL,kBAAkB,EAClB,gCAAgC,GACjC,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,0BAA0B,EAAE,MAAM,mBAAmB,CAAC;AAmH/D,MAAM,aAAa;IACjB,KAAK,GAAgC,EAAE,CAAC;IAC/B,cAAc,GAAwB,EAAE,CAAC;IACzC,aAAa,GAAwC,EAAE,CAAC;IAEjE;;;;;;;;OAQG;IACH,cAAc,CAAC,gBAAwB,EAAE,GAAG,WAA+B;QACzE,OAAO,IAAI,CAAC,0BAA0B,CAAC,QAAQ,EAAE,gBAAgB,EAAE,WAAW,CAAC,CAAC;IAClF,CAAC;IAED;;;;;;OAMG;IACH,kBAAkB,CAAC,gBAAwB,EAAE,GAAG,WAA+B;QAC7E,OAAO,IAAI,CAAC,0BAA0B,CAAC,YAAY,EAAE,gBAAgB,EAAE,WAAW,CAAC,CAAC;IACtF,CAAC;IAED;;;OAGG;IACH,eAAe,CAAC,KAAwB;QACtC,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAChC,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;;;;;;;OAUG;IACH,yBAAyB,CAAC,GAAG,WAA+B;QAC1D,IAAI,WAAW,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC7B,MAAM,IAAI,KAAK,CACb,4FAA4F,CAC7F,CAAC;QACJ,CAAC;QACD,MAAM,EAAE,aAAa,EAAE,iBAAiB,EAAE,GAAG,eAAe,CAAC,qBAAqB,CAAC;QACnF,IAAI,CAAC,cAAc,CAAC,IAAI,CACtB,EAAE,gBAAgB,EAAE,QAAQ,EAAE,SAAS,EAAE,aAAa,EAAE,WAAW,EAAE,EACrE,EAAE,gBAAgB,EAAE,YAAY,EAAE,SAAS,EAAE,iBAAiB,EAAE,WAAW,EAAE,CAC9E,CAAC;QACF,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;;;;;;;;;;OAaG;IACH,QAAQ,CACN,GAAW,EACX,SAA0F;QAE1F,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,sBAAsB,CAAY,GAAG,CAAC,CAAC,CAAC,CAAC;QAC/E,OAAO,IAAI,CAAC;IACd,CAAC;IAED,KAAK,CAAC,KAAiB,EAAE,EAAU,EAAE,UAAkC,EAAE;QACvE,MAAM,EAAE,iBAAiB,EAAE,WAAW,EAAE,GAAG,WAAW,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC;QAEtE,MAAM,UAAU,GAAG,WAAW,CAAC,UAAU,IAAI,eAAe,CAAC,UAAU,CAAC;QACxE,MAAM,QAAQ,GAAG,WAAW,CAAC,QAAQ,IAAI,eAAe,CAAC,QAAQ,CAAC;QAElE,MAAM,aAAa,GAAG,UAAU,KAAK,MAAM,IAAI,UAAU,KAAK,OAAO,CAAC;QACtE,IAAI,aAAa,IAAI,CAAC,WAAW,CAAC,KAAK,EAAE,CAAC;YACxC,MAAM,IAAI,KAAK,CACb,kBAAkB,EAAE,8CAA8C,UAAU,WAAW,CACxF,CAAC;QACJ,CAAC;QAED,MAAM,EAAE,4BAA4B,EAAE,SAAS,EAAE,GAAG,IAAI,CAAC,mBAAmB,CAAC,OAAO,CAAC,CAAC;QAEtF,MAAM,UAAU,GAAiC;YAC/C,UAAU,EAAE,WAAW,CAAC,UAAU;YAClC,UAAU;YACV,QAAQ;YACR,GAAG,CAAC,WAAW,CAAC,KAAK;gBACnB,CAAC,CAAC;oBACE,WAAW,EAAE;wBACX,MAAM,EAAE,WAAW,CAAC,KAAK,CAAC,MAAM;wBAChC,IAAI,EAAE,WAAW,CAAC,KAAK,CAAC,IAAI,IAAI,eAAe,CAAC,SAAS;qBAC1D;iBACF;gBACH,CAAC,CAAC,EAAE,CAAC;YACP,GAAG,CAAC,WAAW,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,WAAW,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC5E,GAAG,CAAC,WAAW,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,WAAW,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACvE,CAAC;QAEF,MAAM,QAAQ,GAAmB;YAC/B,MAAM,EAAE,UAAU;YAClB,GAAG,CAAC,4BAA4B,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,4BAA4B,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACrF,CAAC;QAEF,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC,KAAK,EAAE,EAAE,EAAE,QAAQ,CAAC,CAAC;QAElD,MAAM,aAAa,GAAG,0BAA0B,CAAC,KAAK,EAAE,EAAE,EAAE,SAAS,CAAC,CAAC;QACvE,MAAM,MAAM,GAAG,iBAAiB,CAC9B,KAAK,EACL,EAAE,EACF,EAAE,MAAM,EAAE,EACV;YACE,iBAAiB,EAAE,WAAW;YAC9B,YAAY,EAAE,IAAI,CAAC,aAAa;SACjC,CACF,CAAC;QAEF,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,CAAC;IAC3C,CAAC;IAED,0BAA0B,CACxB,gBAAkC,EAClC,gBAAwB,EACxB,WAA+B;QAE/B,IAAI,WAAW,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC7B,MAAM,IAAI,KAAK,CACb,kBAAkB,gBAAgB,oBAAoB,MAAM,CAAC,gBAAgB,CAAC,qCAAqC,CACpH,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,EAAE,gBAAgB,EAAE,SAAS,EAAE,gBAAgB,EAAE,WAAW,EAAE,CAAC,CAAC;QACzF,OAAO,IAAI,CAAC;IACd,CAAC;IAED,mBAAmB,CAAC,OAA+B;QAIjD,MAAM,4BAA4B,GAAoD,EAAE,CAAC;QACzF,MAAM,YAAY,GAAa,EAAE,CAAC;QAElC,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,cAAc,EAAE,CAAC;YACxC,MAAM,QAAQ,GAAG,kBAAkB,CAAC,KAAK,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;YAChE,4BAA4B,CAAC,IAAI,CAAC,gCAAgC,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC;YACzF,YAAY,CAAC,IAAI,CAAC,GAAG,QAAQ,CAAC,SAAS,CAAC,CAAC;QAC3C,CAAC;QAED,OAAO,EAAE,4BAA4B,EAAE,SAAS,EAAE,YAAY,EAAE,CAAC;IACnE,CAAC;CACF;AAED;;GAEG;AACH,MAAM,UAAU,mBAAmB;IACjC,OAAO,OAAO,CAAoC,aAAa,CAAC,CAAC;AACnE,CAAC"}
+{"version":3,"file":"budget-builder.js","sourceRoot":"","sources":["../src/budget-builder.ts"],"names":[],"mappings":"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"}

package/dist/currency.d.ts

@@ -0,0 +1,21 @@
+import type { IConstruct } from "constructs";
+/**
+ * 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.
+ */
+export declare function assertValidBudgetCurrency(unit: string, context: string): void;
+/**
+ * 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.
+ */
+export declare function warnIfNonUsdCurrency(scope: IConstruct, unit: string, context: string): void;
+//# sourceMappingURL=currency.d.ts.map

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

@@ -0,0 +1,35 @@
+import { Annotations, Token } from "aws-cdk-lib";
+import { DEFAULT_BUDGET_CURRENCIES } from "./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.
+ */
+export function assertValidBudgetCurrency(unit, context) {
+    if (DEFAULT_BUDGET_CURRENCIES.includes(unit))
+        return;
+    throw new Error(`${context}: "${unit}" is not a recognised AWS Budgets currency code. ` +
+        `Expected one of: ${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.
+ */
+export function warnIfNonUsdCurrency(scope, unit, context) {
+    if (Token.isUnresolved(unit))
+        return;
+    if (unit === "USD")
+        return;
+    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/currency.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"currency.js","sourceRoot":"","sources":["../src/currency.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAEjD,OAAO,EAAE,yBAAyB,EAAE,MAAM,eAAe,CAAC;AAE1D;;;;;;GAMG;AACH,MAAM,UAAU,yBAAyB,CAAC,IAAY,EAAE,OAAe;IACrE,IAAI,yBAAyB,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,OAAO;IACrD,MAAM,IAAI,KAAK,CACb,GAAG,OAAO,MAAM,IAAI,mDAAmD;QACrE,oBAAoB,yBAAyB,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAC9D,CAAC;AACJ,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,oBAAoB,CAAC,KAAiB,EAAE,IAAY,EAAE,OAAe;IACnF,IAAI,KAAK,CAAC,YAAY,CAAC,IAAI,CAAC;QAAE,OAAO;IACrC,IAAI,IAAI,KAAK,KAAK;QAAE,OAAO;IAC3B,WAAW,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/defaults.d.ts

@@ -40,4 +40,18 @@ export declare const BUDGET_DEFAULTS: {
         forecastedPercent: number;
     };
 };
+/**
+ * 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
+ */
+export declare const DEFAULT_BUDGET_CURRENCIES: readonly string[];
 //# sourceMappingURL=defaults.d.ts.map

package/dist/defaults.d.ts.map

@@ -1 +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"}
+{"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/defaults.js

@@ -40,4 +40,52 @@ export const BUDGET_DEFAULTS = {
         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
+ */
+export const 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/defaults.js.map

@@ -1 +1 @@
-{"version":3,"file":"defaults.js","sourceRoot":"","sources":["../src/defaults.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,CAAC,MAAM,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"}
+{"version":3,"file":"defaults.js","sourceRoot":"","sources":["../src/defaults.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,CAAC,MAAM,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;AACH,MAAM,CAAC,MAAM,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/email.d.ts

@@ -0,0 +1,28 @@
+declare const emailBrand: unique symbol;
+/**
+ * A validated email address suitable for use as a budget notification
+ * subscriber. Construct via {@link email}; the brand prevents bare
+ * strings from being passed where an `Email` is required, ensuring the
+ * value has been syntactically validated and length-checked against
+ * AWS Budgets' per-subscriber limit.
+ */
+export type Email = string & {
+    readonly [emailBrand]: true;
+};
+/**
+ * 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
+ */
+export declare function email(input: string): Email;
+export {};
+//# sourceMappingURL=email.d.ts.map

package/dist/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"}

package/dist/email.js

@@ -0,0 +1,30 @@
+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
+ */
+export 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/email.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"email.js","sourceRoot":"","sources":["../src/email.ts"],"names":[],"mappings":"AAWA,MAAM,OAAO,GAAG,EAAE,CAAC;AACnB,MAAM,WAAW,GAAG,4BAA4B,CAAC;AAEjD;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,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/index.d.ts

@@ -1,7 +1,8 @@
 export { createBudgetBuilder, type IBudgetBuilder, type BudgetBuilderProps, type BudgetBuilderResult, type BudgetLimit, } from "./budget-builder.js";
 export { createBudgetAlarmBuilder, type IBudgetAlarmBuilder, type BudgetAlarmBuilderProps, type BudgetAlarmBuilderResult, } from "./budget-alarm-builder.js";
-export { BUDGET_DEFAULTS } from "./defaults.js";
+export { BUDGET_DEFAULTS, DEFAULT_BUDGET_CURRENCIES } from "./defaults.js";
 export { type BudgetAlarmConfig, type EstimatedChargesAlarmConfig } from "./alarm-config.js";
 export { createBudgetsTopicPolicies } from "./topic-policy.js";
-export { resolveSubscribers, toCfnNotificationWithSubscribers, type BudgetSubscriber, type NotificationEntry, type NotificationType, type ResolvedSubscribers, } from "./notifications.js";
+export { email, type Email } from "./email.js";
+export { resolveSubscribers, toCfnNotificationWithSubscribers, type NotificationEntry, type NotificationType, type NotifySubscribers, type ResolvedSubscribers, } from "./notifications.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +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,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,KAAK,iBAAiB,EAAE,KAAK,2BAA2B,EAAE,MAAM,mBAAmB,CAAC;AAC7F,OAAO,EAAE,0BAA0B,EAAE,MAAM,mBAAmB,CAAC;AAC/D,OAAO,EACL,kBAAkB,EAClB,gCAAgC,EAChC,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,GACzB,MAAM,oBAAoB,CAAC"}
+{"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/index.js

@@ -1,6 +1,7 @@
 export { createBudgetBuilder, } from "./budget-builder.js";
 export { createBudgetAlarmBuilder, } from "./budget-alarm-builder.js";
-export { BUDGET_DEFAULTS } from "./defaults.js";
+export { BUDGET_DEFAULTS, DEFAULT_BUDGET_CURRENCIES } from "./defaults.js";
 export { createBudgetsTopicPolicies } from "./topic-policy.js";
+export { email } from "./email.js";
 export { resolveSubscribers, toCfnNotificationWithSubscribers, } from "./notifications.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,mBAAmB,GAKpB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,wBAAwB,GAIzB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAEhD,OAAO,EAAE,0BAA0B,EAAE,MAAM,mBAAmB,CAAC;AAC/D,OAAO,EACL,kBAAkB,EAClB,gCAAgC,GAKjC,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,mBAAmB,GAKpB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,wBAAwB,GAIzB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,eAAe,EAAE,yBAAyB,EAAE,MAAM,eAAe,CAAC;AAE3E,OAAO,EAAE,0BAA0B,EAAE,MAAM,mBAAmB,CAAC;AAC/D,OAAO,EAAE,KAAK,EAAc,MAAM,YAAY,CAAC;AAC/C,OAAO,EACL,kBAAkB,EAClB,gCAAgC,GAKjC,MAAM,oBAAoB,CAAC"}

package/dist/notifications.d.ts

@@ -1,11 +1,37 @@
 import { CfnBudget } from "aws-cdk-lib/aws-budgets";
 import type { ITopic } from "aws-cdk-lib/aws-sns";
 import { type Resolvable } from "@composurecdk/core";
+import type { Email } from "./email.js";
 /**
- * A subscriber that receives budget notifications. Either an email
- * address (string) or an SNS topic (concrete or resolvable reference).
+ * Subscribers attached to a budget notification.
+ *
+ * AWS Budgets enforces an asymmetric per-notification subscriber rule
+ * that CloudFormation does not model:
+ *
+ * - up to 10 subscribers per notification
+ * - **at most one** with `SubscriptionType=SNS`
+ * - the remainder must be `EMAIL`
+ *
+ * This shape encodes that constraint in the type system: `sns` is
+ * singular, so passing two SNS topics is unrepresentable. The
+ * combined-count cap is enforced at synth time.
+ *
+ * @see https://docs.aws.amazon.com/aws-cost-management/latest/APIReference/API_budgets_NotificationWithSubscribers.html
  */
-export type BudgetSubscriber = string | ITopic | Resolvable<ITopic>;
+export interface NotifySubscribers {
+    /**
+     * Optional SNS topic to publish notifications to. AWS Budgets allows
+     * at most one SNS subscriber per notification; route fan-out by
+     * adding additional subscriptions to this single topic.
+     */
+    sns?: ITopic | Resolvable<ITopic>;
+    /**
+     * Optional list of validated email addresses. Construct each value
+     * via {@link email}; bare strings are rejected at compile time. The
+     * combined `sns` + `emails` count must be ≤ 10.
+     */
+    emails?: Email[];
+}
 /**
  * Which side of spend a notification triggers on.
  *
@@ -31,27 +57,29 @@ export interface NotificationEntry {
      * absolute amount when `thresholdType` is `ABSOLUTE_VALUE`.
      */
     threshold: number;
-    subscribers: BudgetSubscriber[];
+    subscribers: NotifySubscribers;
     comparisonOperator?: "GREATER_THAN" | "LESS_THAN" | "EQUAL_TO";
     thresholdType?: "PERCENTAGE" | "ABSOLUTE_VALUE";
 }
 /**
- * Resolved subscriber after any {@link Resolvable} has been resolved.
- *
- * `snsTopics` is surfaced separately so the builder can create
- * `AWS::SNS::TopicPolicy` entries granting `budgets.amazonaws.com`
- * permission to publish.
+ * Resolved subscribers in the CloudFormation shape required by
+ * `AWS::Budgets::Budget`, plus any SNS topic referenced (so the caller
+ * can create matching `AWS::SNS::TopicPolicy` grants).
  */
 export interface ResolvedSubscribers {
     cfn: CfnBudget.SubscriberProperty[];
     snsTopics: ITopic[];
 }
 /**
- * Resolve a list of {@link BudgetSubscriber}s into the CloudFormation
- * shape required by `AWS::Budgets::Budget` and a flat list of any SNS
- * topics referenced (so the caller can create topic policies).
+ * 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.
  */
-export declare function resolveSubscribers(subscribers: BudgetSubscriber[], context: Record<string, object>): ResolvedSubscribers;
+export declare function resolveSubscribers(subscribers: NotifySubscribers, context: Record<string, object>): ResolvedSubscribers;
 /**
  * Convert a {@link NotificationEntry} plus resolved subscribers into the
  * CloudFormation `NotificationWithSubscribersProperty` shape.

package/dist/notifications.d.ts.map

@@ -1 +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;AAE9D;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,MAAM,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC;AAEpE;;;;;;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,gBAAgB,EAAE,CAAC;IAChC,kBAAkB,CAAC,EAAE,cAAc,GAAG,WAAW,GAAG,UAAU,CAAC;IAC/D,aAAa,CAAC,EAAE,YAAY,GAAG,gBAAgB,CAAC;CACjD;AAED;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC,GAAG,EAAE,SAAS,CAAC,kBAAkB,EAAE,CAAC;IACpC,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,WAAW,EAAE,gBAAgB,EAAE,EAC/B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC9B,mBAAmB,CAgBrB;AAED;;;GAGG;AACH,wBAAgB,gCAAgC,CAC9C,KAAK,EAAE,iBAAiB,EACxB,mBAAmB,EAAE,SAAS,CAAC,kBAAkB,EAAE,GAClD,SAAS,CAAC,mCAAmC,CAU/C"}
+{"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/notifications.js

@@ -1,21 +1,24 @@
 import { resolve } from "@composurecdk/core";
 /**
- * Resolve a list of {@link BudgetSubscriber}s into the CloudFormation
- * shape required by `AWS::Budgets::Budget` and a flat list of any SNS
- * topics referenced (so the caller can create topic policies).
+ * 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.
  */
 export function resolveSubscribers(subscribers, context) {
     const cfn = [];
     const snsTopics = [];
-    for (const subscriber of subscribers) {
-        if (typeof subscriber === "string") {
-            cfn.push({ address: subscriber, subscriptionType: "EMAIL" });
-            continue;
-        }
-        const topic = resolve(subscriber, context);
+    if (subscribers.sns !== undefined) {
+        const topic = 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 };
 }
 /**

package/dist/notifications.js.map

@@ -1 +1 @@
-{"version":3,"file":"notifications.js","sourceRoot":"","sources":["../src/notifications.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,OAAO,EAAmB,MAAM,oBAAoB,CAAC;AAmD9D;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAChC,WAA+B,EAC/B,OAA+B;IAE/B,MAAM,GAAG,GAAmC,EAAE,CAAC;IAC/C,MAAM,SAAS,GAAa,EAAE,CAAC;IAE/B,KAAK,MAAM,UAAU,IAAI,WAAW,EAAE,CAAC;QACrC,IAAI,OAAO,UAAU,KAAK,QAAQ,EAAE,CAAC;YACnC,GAAG,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,UAAU,EAAE,gBAAgB,EAAE,OAAO,EAAE,CAAC,CAAC;YAC7D,SAAS;QACX,CAAC;QAED,MAAM,KAAK,GAAG,OAAO,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;QAC3C,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,OAAO,EAAE,GAAG,EAAE,SAAS,EAAE,CAAC;AAC5B,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,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"}
+{"version":3,"file":"notifications.js","sourceRoot":"","sources":["../src/notifications.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,OAAO,EAAmB,MAAM,oBAAoB,CAAC;AA2E9D;;;;;;;;GAQG;AACH,MAAM,UAAU,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,OAAO,CAAC,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,MAAM,UAAU,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@composurecdk/budgets",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Composable AWS Budgets builder with well-architected defaults and automatic SNS topic policies",
   "repository": {
     "type": "git",
@@ -35,8 +35,8 @@
   },
   "type": "module",
   "peerDependencies": {
-    "@composurecdk/cloudwatch": "^0.5.0",
-    "@composurecdk/core": "^0.5.0",
+    "@composurecdk/cloudwatch": "^0.6.0",
+    "@composurecdk/core": "^0.6.0",
     "aws-cdk-lib": "^2.0.0",
     "constructs": "^10.0.0"
   },