@tlj-blocks/billing-alarm-cdk 0.1.0

package/README.md

@@ -0,0 +1,189 @@
+# @tlj-blocks/billing-alarm-cdk
+
+CloudWatch alarms that email you when your AWS bill passes a spend threshold.
+The default thresholds are 10 USD and 100 USD.
+
+There is one alarm per threshold, so crossing 10 USD sends an email and crossing
+100 USD later in the same month sends a second one.
+
+## Install
+
+```sh
+npm install @tlj-blocks/billing-alarm-cdk
+```
+
+`aws-cdk-lib` and `constructs` are peer dependencies. Your CDK app already has
+them, but if not:
+
+```sh
+npm install aws-cdk-lib constructs
+```
+
+Requires `aws-cdk-lib` 2.160.0 or later and `constructs` 10.x.
+
+## Quick start
+
+```ts
+// bin/app.ts
+import { App } from "aws-cdk-lib";
+import { BillingAlarmStack } from "@tlj-blocks/billing-alarm-cdk";
+
+const app = new App();
+
+new BillingAlarmStack(app, "BillingAlarms", {
+  notificationEmail: "me@example.com",
+  // thresholds defaults to [10, 100]
+  env: { account: process.env.CDK_DEFAULT_ACCOUNT },
+});
+```
+
+```sh
+cdk deploy BillingAlarms
+```
+
+You do not set a region. The stack pins itself to `us-east-1`, because that is
+the only region where AWS publishes the billing metric. See
+[Why us-east-1](#why-us-east-1).
+
+## Two steps you have to do by hand
+
+CloudFormation cannot do either of these, and the alarms report no data until
+you finish the first one.
+
+### 1. Turn on billing alerts
+
+Open the [billing preferences
+page](https://console.aws.amazon.com/billing/home#/preferences), tick "Receive
+CloudWatch billing alerts", and save. Do this in the payer account if you use
+AWS Organizations.
+
+Until you do, AWS never publishes the `EstimatedCharges` metric and every alarm
+sits in `INSUFFICIENT_DATA`. After you switch it on, the first data point can
+take up to 24 hours to appear.
+
+### 2. Confirm the subscription email
+
+The first deploy creates an SNS email subscription, and AWS sends a confirmation
+link to `notificationEmail`. Click it. Until you do, SNS delivers nothing.
+
+## Using the construct in a stack you already have
+
+Use `BillingAlarm` instead of `BillingAlarmStack` if you would rather not deploy
+a separate stack. Put it in a `us-east-1` stack yourself.
+
+```ts
+import { Stack, StackProps } from "aws-cdk-lib";
+import { Construct } from "constructs";
+import { BillingAlarm } from "@tlj-blocks/billing-alarm-cdk";
+
+export class OpsStack extends Stack {
+  constructor(scope: Construct, id: string, props?: StackProps) {
+    super(scope, id, { ...props, env: { ...props?.env, region: "us-east-1" } });
+
+    new BillingAlarm(this, "BillingAlarm", {
+      notificationEmail: "me@example.com",
+      thresholds: [10, 100, 500],
+      alarmNamePrefix: "personal",
+    });
+  }
+}
+```
+
+## Props
+
+`BillingAlarm` and `BillingAlarmStack` both take these. `BillingAlarmStack` also
+takes the usual `StackProps`, except that it sets `env.region` itself.
+
+| Prop                | Type          | Default     | Notes                                                           |
+| ------------------- | ------------- | ----------- | --------------------------------------------------------------- |
+| `notificationEmail` | `string`      | required    | Who gets the email. Optional only if you pass `topic`.           |
+| `thresholds`        | `number[]`    | `[10, 100]` | One alarm each. Must be positive and must not repeat.            |
+| `currency`          | `string`      | `"USD"`     | Must match your billing currency or no data arrives.             |
+| `topic`             | `sns.ITopic`  | a new topic | Notify a topic you already have. Ignores `notificationEmail`.    |
+| `topicName`         | `string`      | generated   | Names the created topic.                                         |
+| `alarmNamePrefix`   | `string`      | `"aws"`     | Alarms are named `prefix-billing-over-threshold-currency`.       |
+| `period`            | `Duration`    | 6 hours     | Evaluation period. The metric updates a few times a day.         |
+
+## What the construct exposes
+
+`topic` is the `sns.ITopic` the alarms notify. Add subscribers to it for SMS or
+a chatbot.
+
+`alarms` is the array of `cloudwatch.Alarm`, one per threshold, in the order you
+listed them.
+
+`BillingAlarmStack` exposes its `BillingAlarm` as `billingAlarm`, so you can
+reach both of the above from the stack.
+
+To email a second address:
+
+```ts
+import { Subscription, SubscriptionProtocol } from "aws-cdk-lib/aws-sns";
+
+const billing = new BillingAlarm(this, "BillingAlarm", {
+  notificationEmail: "me@example.com",
+});
+
+new Subscription(this, "Ops", {
+  topic: billing.topic,
+  protocol: SubscriptionProtocol.EMAIL,
+  endpoint: "ops@example.com",
+});
+```
+
+## How the alarms behave
+
+`AWS/Billing EstimatedCharges` is a running total for the current month. An
+alarm that fires on the 12th stays in `ALARM` until charges reset on the 1st,
+then returns to `OK` and can fire again. You therefore get one email per
+threshold per month rather than one every evaluation period.
+
+The flip side is that spend climbing from 10 USD to 99 USD sends no further
+email, because the 10 USD alarm is already in `ALARM`. Add more thresholds if
+you want finer steps.
+
+The number AWS reports is an estimate. It excludes credits and refunds that get
+applied later, so it will not match your final invoice.
+
+Missing data counts as `notBreaching`, so the first days of a month and the
+period before you switch on billing alerts do not raise false alarms.
+
+## Why us-east-1
+
+AWS publishes billing metrics to `us-east-1` only, whatever regions you actually
+spend in. An alarm on `AWS/Billing` created anywhere else receives no data and
+never fires. `BillingAlarmStack` sets the region for you and throws if you pass
+a different one, rather than deploying a stack that cannot work.
+
+## Alarms or AWS Budgets
+
+This package uses CloudWatch alarms. They are plain CloudFormation, and the
+first 10 alarms in an account are free.
+
+AWS Budgets is the better fit if you want alerts on a forecast, such as "you are
+on track to exceed 100 USD", or budgets split by service or tag, or alerts on
+usage rather than cost. Nothing stops you running both.
+
+## Resources created
+
+An `AWS::SNS::Topic`, an `AWS::SNS::Subscription` of protocol `email`, and one
+`AWS::CloudWatch::Alarm` per threshold.
+
+## Troubleshooting
+
+If the alarms stay in `INSUFFICIENT_DATA`, billing alerts are probably still
+off. Check step 1 above, then confirm the metric exists:
+
+```sh
+aws cloudwatch list-metrics --namespace AWS/Billing --region us-east-1
+```
+
+An empty result means AWS is not publishing it yet. Allow 24 hours after
+enabling the preference.
+
+If an alarm fires but no email arrives, the SNS subscription is unconfirmed.
+Look in the inbox and the spam folder for the confirmation from AWS.
+
+If real spend never trips an alarm, check that `currency` matches your billing
+currency, and that you deployed into the payer account. Member account charges
+in AWS Organizations roll up to the payer, not to the member.

package/dist/billing-alarm-stack.d.ts

@@ -0,0 +1,41 @@
+import { Stack, type StackProps } from "aws-cdk-lib";
+import { Construct } from "constructs";
+import { BillingAlarm, type BillingAlarmProps } from "./billing-alarm";
+/** The only region in which AWS publishes the `AWS/Billing` metrics. */
+export declare const BILLING_METRIC_REGION = "us-east-1";
+/**
+ * Configuration for {@link BillingAlarmStack}. It takes everything
+ * {@link BillingAlarm} takes, plus the usual stack properties.
+ */
+export interface BillingAlarmStackProps extends StackProps, BillingAlarmProps {
+}
+/**
+ * A stack that holds account billing alarms and nothing else.
+ *
+ * It wraps {@link BillingAlarm} and sets the region to `us-east-1`, the only
+ * region where AWS publishes the billing metric, so you do not have to remember
+ * to. Passing a different region throws, rather than deploying a stack whose
+ * alarms can never fire.
+ *
+ * One manual step remains. In the billing console, open Billing preferences,
+ * tick "Receive CloudWatch billing alerts", and save.
+ *
+ * @example
+ * ```ts
+ * // bin/app.ts
+ * import { App } from "aws-cdk-lib";
+ * import { BillingAlarmStack } from "@tlj-blocks/billing-alarm-cdk";
+ *
+ * const app = new App();
+ * new BillingAlarmStack(app, "BillingAlarms", {
+ *   notificationEmail: "me@example.com",
+ *   thresholds: [10, 100], // the default
+ * });
+ * ```
+ */
+export declare class BillingAlarmStack extends Stack {
+    /** The alarms and the topic this stack created. */
+    readonly billingAlarm: BillingAlarm;
+    constructor(scope: Construct, id: string, props: BillingAlarmStackProps);
+}
+//# sourceMappingURL=billing-alarm-stack.d.ts.map

package/dist/billing-alarm-stack.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"billing-alarm-stack.d.ts","sourceRoot":"","sources":["../src/billing-alarm-stack.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AACrD,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,EAAE,YAAY,EAAE,KAAK,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAEvE,wEAAwE;AACxE,eAAO,MAAM,qBAAqB,cAAc,CAAC;AAEjD;;;GAGG;AACH,MAAM,WAAW,sBAAuB,SAAQ,UAAU,EAAE,iBAAiB;CAAG;AAEhF;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,mDAAmD;IACnD,QAAQ,CAAC,YAAY,EAAE,YAAY,CAAC;gBAExB,KAAK,EAAE,SAAS,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,sBAAsB;CAcxE"}

package/dist/billing-alarm-stack.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BillingAlarmStack = exports.BILLING_METRIC_REGION = void 0;
+const aws_cdk_lib_1 = require("aws-cdk-lib");
+const billing_alarm_1 = require("./billing-alarm");
+/** The only region in which AWS publishes the `AWS/Billing` metrics. */
+exports.BILLING_METRIC_REGION = "us-east-1";
+/**
+ * A stack that holds account billing alarms and nothing else.
+ *
+ * It wraps {@link BillingAlarm} and sets the region to `us-east-1`, the only
+ * region where AWS publishes the billing metric, so you do not have to remember
+ * to. Passing a different region throws, rather than deploying a stack whose
+ * alarms can never fire.
+ *
+ * One manual step remains. In the billing console, open Billing preferences,
+ * tick "Receive CloudWatch billing alerts", and save.
+ *
+ * @example
+ * ```ts
+ * // bin/app.ts
+ * import { App } from "aws-cdk-lib";
+ * import { BillingAlarmStack } from "@tlj-blocks/billing-alarm-cdk";
+ *
+ * const app = new App();
+ * new BillingAlarmStack(app, "BillingAlarms", {
+ *   notificationEmail: "me@example.com",
+ *   thresholds: [10, 100], // the default
+ * });
+ * ```
+ */
+class BillingAlarmStack extends aws_cdk_lib_1.Stack {
+    /** The alarms and the topic this stack created. */
+    billingAlarm;
+    constructor(scope, id, props) {
+        const { env, ...rest } = props;
+        if (env?.region && env.region !== exports.BILLING_METRIC_REGION) {
+            throw new Error(`BillingAlarmStack only works in ${exports.BILLING_METRIC_REGION}, because AWS publishes billing metrics there and nowhere else. Got ${env.region}. ` +
+                `Use the BillingAlarm construct directly if you need it in a stack of your own.`);
+        }
+        super(scope, id, { ...rest, env: { ...env, region: exports.BILLING_METRIC_REGION } });
+        this.billingAlarm = new billing_alarm_1.BillingAlarm(this, "BillingAlarm", props);
+    }
+}
+exports.BillingAlarmStack = BillingAlarmStack;
+//# sourceMappingURL=billing-alarm-stack.js.map

package/dist/billing-alarm-stack.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"billing-alarm-stack.js","sourceRoot":"","sources":["../src/billing-alarm-stack.ts"],"names":[],"mappings":";;;AAAA,6CAAqD;AAErD,mDAAuE;AAEvE,wEAAwE;AAC3D,QAAA,qBAAqB,GAAG,WAAW,CAAC;AAQjD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAa,iBAAkB,SAAQ,mBAAK;IAC1C,mDAAmD;IAC1C,YAAY,CAAe;IAEpC,YAAY,KAAgB,EAAE,EAAU,EAAE,KAA6B;QACrE,MAAM,EAAE,GAAG,EAAE,GAAG,IAAI,EAAE,GAAG,KAAK,CAAC;QAE/B,IAAI,GAAG,EAAE,MAAM,IAAI,GAAG,CAAC,MAAM,KAAK,6BAAqB,EAAE,CAAC;YACxD,MAAM,IAAI,KAAK,CACb,mCAAmC,6BAAqB,uEAAuE,GAAG,CAAC,MAAM,IAAI;gBAC3I,gFAAgF,CACnF,CAAC;QACJ,CAAC;QAED,KAAK,CAAC,KAAK,EAAE,EAAE,EAAE,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,EAAE,GAAG,GAAG,EAAE,MAAM,EAAE,6BAAqB,EAAE,EAAE,CAAC,CAAC;QAE9E,IAAI,CAAC,YAAY,GAAG,IAAI,4BAAY,CAAC,IAAI,EAAE,cAAc,EAAE,KAAK,CAAC,CAAC;IACpE,CAAC;CACF;AAlBD,8CAkBC"}

package/dist/billing-alarm.d.ts

@@ -0,0 +1,117 @@
+import { Duration } from "aws-cdk-lib";
+import { Construct } from "constructs";
+import * as cloudwatch from "aws-cdk-lib/aws-cloudwatch";
+import * as sns from "aws-cdk-lib/aws-sns";
+/** Spend thresholds used when {@link BillingAlarmProps.thresholds} is omitted. */
+export declare const DEFAULT_THRESHOLDS: number[];
+/**
+ * Configuration for the {@link BillingAlarm} construct.
+ */
+export interface BillingAlarmProps {
+    /**
+     * Email address that receives the alarm notifications.
+     *
+     * The construct creates an SNS email subscription for this address. After
+     * the first deploy, AWS sends one confirmation email here. You must click the
+     * link in it before SNS delivers any notification.
+     *
+     * Ignored when {@link topic} is supplied.
+     */
+    notificationEmail?: string;
+    /**
+     * Spend levels, in {@link currency}, to alarm at. The construct creates one
+     * alarm per threshold, so you get a separate email each time the bill crosses
+     * one of them.
+     *
+     * @default [10, 100]
+     */
+    thresholds?: number[];
+    /**
+     * Currency of the estimated-charges metric. This must match the currency
+     * your account is billed in. AWS publishes the metric under that one currency
+     * only, so a mismatch produces alarms that never receive data.
+     *
+     * @default "USD"
+     */
+    currency?: string;
+    /**
+     * An existing SNS topic to notify instead of creating one. Use this to send
+     * billing alarms to a topic you already have, such as one wired to Slack or
+     * PagerDuty. When set, the construct ignores {@link notificationEmail}.
+     *
+     * @default - a new topic with an email subscription to `notificationEmail`
+     */
+    topic?: sns.ITopic;
+    /**
+     * Explicit SNS topic name for the created topic. Leave unset to let
+     * CloudFormation generate a unique name.
+     *
+     * @default - a CloudFormation-generated name
+     */
+    topicName?: string;
+    /**
+     * Prefix for the generated alarm names. `MyAccount` yields
+     * `MyAccount-billing-over-10-USD`. The alarm name is what you see in the
+     * CloudWatch console and in the subject of the notification email.
+     *
+     * @default "aws"
+     */
+    alarmNamePrefix?: string;
+    /**
+     * How often the alarms evaluate the estimated-charges metric. AWS refreshes
+     * this metric a few times a day, so a period shorter than a few hours only
+     * adds evaluations that find no new data.
+     *
+     * @default Duration.hours(6)
+     */
+    period?: Duration;
+}
+/**
+ * CloudWatch billing alarms for an AWS account.
+ *
+ * In your stack it creates an {@link sns.Topic} with an email subscription,
+ * unless you pass your own topic, and one {@link cloudwatch.Alarm} per
+ * threshold. Each alarm watches the `AWS/Billing EstimatedCharges` metric and
+ * notifies the topic when the month-to-date charges pass its threshold.
+ *
+ * CloudFormation cannot do either of the two account-level prerequisites, so
+ * you have to do them once by hand.
+ *
+ * 1. Turn on billing alerts. In the billing console, open Billing preferences,
+ *    tick "Receive CloudWatch billing alerts", and save. Until you do, AWS
+ *    never publishes the metric and the alarms stay in `INSUFFICIENT_DATA`.
+ * 2. Deploy to `us-east-1`. AWS publishes the billing metric there only,
+ *    whatever regions you spend in. {@link BillingAlarmStack} sets the region
+ *    for you. If you use this construct directly, put it in a `us-east-1`
+ *    stack.
+ *
+ * The charges reset at the start of each month, so an alarm that fired in
+ * January returns to `OK` in February and can fire again.
+ *
+ * @example
+ * ```ts
+ * import { Stack, StackProps } from "aws-cdk-lib";
+ * import { Construct } from "constructs";
+ * import { BillingAlarm } from "@tlj-blocks/billing-alarm-cdk";
+ *
+ * export class OpsStack extends Stack {
+ *   constructor(scope: Construct, id: string, props?: StackProps) {
+ *     // The billing metric only exists in us-east-1.
+ *     super(scope, id, { ...props, env: { ...props?.env, region: "us-east-1" } });
+ *
+ *     new BillingAlarm(this, "BillingAlarm", {
+ *       notificationEmail: "me@example.com",
+ *       thresholds: [10, 100],
+ *     });
+ *   }
+ * }
+ * ```
+ */
+export declare class BillingAlarm extends Construct {
+    /** The topic the alarms notify. Add more subscribers to it if you need them. */
+    readonly topic: sns.ITopic;
+    /** One alarm per threshold, in the order the thresholds were given. */
+    readonly alarms: cloudwatch.Alarm[];
+    constructor(scope: Construct, id: string, props?: BillingAlarmProps);
+}
+//# sourceMappingURL=billing-alarm.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"billing-alarm.d.ts","sourceRoot":"","sources":["../src/billing-alarm.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,KAAK,UAAU,MAAM,4BAA4B,CAAC;AAEzD,OAAO,KAAK,GAAG,MAAM,qBAAqB,CAAC;AAG3C,kFAAkF;AAClF,eAAO,MAAM,kBAAkB,UAAY,CAAC;AAE5C;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;;;;;OAQG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAE3B;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IAEtB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC;IAEnB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IAEzB;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,QAAQ,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,qBAAa,YAAa,SAAQ,SAAS;IACzC,gFAAgF;IAChF,QAAQ,CAAC,KAAK,EAAE,GAAG,CAAC,MAAM,CAAC;IAC3B,uEAAuE;IACvE,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC,KAAK,EAAE,CAAC;gBAExB,KAAK,EAAE,SAAS,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,GAAE,iBAAsB;CAyExE"}

package/dist/billing-alarm.js

@@ -0,0 +1,153 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BillingAlarm = exports.DEFAULT_THRESHOLDS = void 0;
+const aws_cdk_lib_1 = require("aws-cdk-lib");
+const constructs_1 = require("constructs");
+const cloudwatch = __importStar(require("aws-cdk-lib/aws-cloudwatch"));
+const cloudwatchActions = __importStar(require("aws-cdk-lib/aws-cloudwatch-actions"));
+const sns = __importStar(require("aws-cdk-lib/aws-sns"));
+const snsSubscriptions = __importStar(require("aws-cdk-lib/aws-sns-subscriptions"));
+/** Spend thresholds used when {@link BillingAlarmProps.thresholds} is omitted. */
+exports.DEFAULT_THRESHOLDS = [10, 100];
+/**
+ * CloudWatch billing alarms for an AWS account.
+ *
+ * In your stack it creates an {@link sns.Topic} with an email subscription,
+ * unless you pass your own topic, and one {@link cloudwatch.Alarm} per
+ * threshold. Each alarm watches the `AWS/Billing EstimatedCharges` metric and
+ * notifies the topic when the month-to-date charges pass its threshold.
+ *
+ * CloudFormation cannot do either of the two account-level prerequisites, so
+ * you have to do them once by hand.
+ *
+ * 1. Turn on billing alerts. In the billing console, open Billing preferences,
+ *    tick "Receive CloudWatch billing alerts", and save. Until you do, AWS
+ *    never publishes the metric and the alarms stay in `INSUFFICIENT_DATA`.
+ * 2. Deploy to `us-east-1`. AWS publishes the billing metric there only,
+ *    whatever regions you spend in. {@link BillingAlarmStack} sets the region
+ *    for you. If you use this construct directly, put it in a `us-east-1`
+ *    stack.
+ *
+ * The charges reset at the start of each month, so an alarm that fired in
+ * January returns to `OK` in February and can fire again.
+ *
+ * @example
+ * ```ts
+ * import { Stack, StackProps } from "aws-cdk-lib";
+ * import { Construct } from "constructs";
+ * import { BillingAlarm } from "@tlj-blocks/billing-alarm-cdk";
+ *
+ * export class OpsStack extends Stack {
+ *   constructor(scope: Construct, id: string, props?: StackProps) {
+ *     // The billing metric only exists in us-east-1.
+ *     super(scope, id, { ...props, env: { ...props?.env, region: "us-east-1" } });
+ *
+ *     new BillingAlarm(this, "BillingAlarm", {
+ *       notificationEmail: "me@example.com",
+ *       thresholds: [10, 100],
+ *     });
+ *   }
+ * }
+ * ```
+ */
+class BillingAlarm extends constructs_1.Construct {
+    /** The topic the alarms notify. Add more subscribers to it if you need them. */
+    topic;
+    /** One alarm per threshold, in the order the thresholds were given. */
+    alarms;
+    constructor(scope, id, props = {}) {
+        super(scope, id);
+        const currency = props.currency ?? "USD";
+        const prefix = props.alarmNamePrefix ?? "aws";
+        const period = props.period ?? aws_cdk_lib_1.Duration.hours(6);
+        const thresholds = props.thresholds ?? exports.DEFAULT_THRESHOLDS;
+        if (thresholds.length === 0) {
+            throw new Error("BillingAlarm: `thresholds` must not be empty.");
+        }
+        for (const threshold of thresholds) {
+            if (!Number.isFinite(threshold) || threshold <= 0) {
+                throw new Error(`BillingAlarm: thresholds must be positive numbers, got ${threshold}.`);
+            }
+        }
+        if (new Set(thresholds).size !== thresholds.length) {
+            // Duplicates would collide on the generated alarm name.
+            throw new Error("BillingAlarm: `thresholds` must not contain duplicates.");
+        }
+        if (props.topic) {
+            this.topic = props.topic;
+        }
+        else {
+            if (!props.notificationEmail) {
+                throw new Error("BillingAlarm: pass `notificationEmail`, or `topic` to notify an existing topic.");
+            }
+            const topic = new sns.Topic(this, "Topic", {
+                topicName: props.topicName,
+                displayName: "AWS Billing Alarms",
+            });
+            // SNS delivers nothing until the recipient confirms this subscription.
+            topic.addSubscription(new snsSubscriptions.EmailSubscription(props.notificationEmail));
+            this.topic = topic;
+        }
+        const action = new cloudwatchActions.SnsAction(this.topic);
+        this.alarms = thresholds.map((threshold) => {
+            // AWS/Billing EstimatedCharges is a cumulative month-to-date total. AWS
+            // publishes it in us-east-1 only, a few times a day. Maximum over the
+            // period is the right statistic for a running total.
+            const metric = new cloudwatch.Metric({
+                namespace: "AWS/Billing",
+                metricName: "EstimatedCharges",
+                dimensionsMap: { Currency: currency },
+                statistic: "Maximum",
+                period,
+            });
+            const alarm = new cloudwatch.Alarm(this, `Over${threshold}`, {
+                alarmName: `${prefix}-billing-over-${threshold}-${currency}`,
+                alarmDescription: `Estimated AWS charges for the current month exceeded ${threshold} ${currency}.`,
+                metric,
+                threshold,
+                evaluationPeriods: 1,
+                comparisonOperator: cloudwatch.ComparisonOperator.GREATER_THAN_THRESHOLD,
+                // Early in the month, and before you switch billing alerts on, there
+                // is no data. That is not a billing problem, so do not alarm on it.
+                treatMissingData: cloudwatch.TreatMissingData.NOT_BREACHING,
+            });
+            alarm.addAlarmAction(action);
+            return alarm;
+        });
+    }
+}
+exports.BillingAlarm = BillingAlarm;
+//# sourceMappingURL=billing-alarm.js.map

package/dist/billing-alarm.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { BillingAlarm, DEFAULT_THRESHOLDS, type BillingAlarmProps, } from "./billing-alarm";
+export { BillingAlarmStack, BILLING_METRIC_REGION, type BillingAlarmStackProps, } from "./billing-alarm-stack";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,YAAY,EACZ,kBAAkB,EAClB,KAAK,iBAAiB,GACvB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,iBAAiB,EACjB,qBAAqB,EACrB,KAAK,sBAAsB,GAC5B,MAAM,uBAAuB,CAAC"}

package/dist/index.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BILLING_METRIC_REGION = exports.BillingAlarmStack = exports.DEFAULT_THRESHOLDS = exports.BillingAlarm = void 0;
+var billing_alarm_1 = require("./billing-alarm");
+Object.defineProperty(exports, "BillingAlarm", { enumerable: true, get: function () { return billing_alarm_1.BillingAlarm; } });
+Object.defineProperty(exports, "DEFAULT_THRESHOLDS", { enumerable: true, get: function () { return billing_alarm_1.DEFAULT_THRESHOLDS; } });
+var billing_alarm_stack_1 = require("./billing-alarm-stack");
+Object.defineProperty(exports, "BillingAlarmStack", { enumerable: true, get: function () { return billing_alarm_stack_1.BillingAlarmStack; } });
+Object.defineProperty(exports, "BILLING_METRIC_REGION", { enumerable: true, get: function () { return billing_alarm_stack_1.BILLING_METRIC_REGION; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,iDAIyB;AAHvB,6GAAA,YAAY,OAAA;AACZ,mHAAA,kBAAkB,OAAA;AAGpB,6DAI+B;AAH7B,wHAAA,iBAAiB,OAAA;AACjB,4HAAA,qBAAqB,OAAA"}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@tlj-blocks/billing-alarm-cdk",
+  "version": "0.1.0",
+  "description": "AWS CDK stack and construct that email you when your AWS bill crosses spend thresholds",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TimothyJones/tlj-blocks.git",
+    "directory": "packages/tlj-billing-alarm"
+  },
+  "homepage": "https://github.com/TimothyJones/tlj-blocks/tree/main/packages/tlj-billing-alarm#readme",
+  "bugs": {
+    "url": "https://github.com/TimothyJones/tlj-blocks/issues"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json",
+    "clean": "rm -rf dist",
+    "pretest": "npm run build",
+    "test": "node --test",
+    "prepublishOnly": "npm run clean && npm run build && npm test"
+  },
+  "peerDependencies": {
+    "aws-cdk-lib": "^2.160.0",
+    "constructs": "^10.0.0"
+  },
+  "devDependencies": {
+    "aws-cdk-lib": "^2.160.0",
+    "constructs": "^10.3.0"
+  },
+  "license": "MIT"
+}

package/src/billing-alarm-stack.ts

@@ -0,0 +1,56 @@
+import { Stack, type StackProps } from "aws-cdk-lib";
+import { Construct } from "constructs";
+import { BillingAlarm, type BillingAlarmProps } from "./billing-alarm";
+
+/** The only region in which AWS publishes the `AWS/Billing` metrics. */
+export const BILLING_METRIC_REGION = "us-east-1";
+
+/**
+ * Configuration for {@link BillingAlarmStack}. It takes everything
+ * {@link BillingAlarm} takes, plus the usual stack properties.
+ */
+export interface BillingAlarmStackProps extends StackProps, BillingAlarmProps {}
+
+/**
+ * A stack that holds account billing alarms and nothing else.
+ *
+ * It wraps {@link BillingAlarm} and sets the region to `us-east-1`, the only
+ * region where AWS publishes the billing metric, so you do not have to remember
+ * to. Passing a different region throws, rather than deploying a stack whose
+ * alarms can never fire.
+ *
+ * One manual step remains. In the billing console, open Billing preferences,
+ * tick "Receive CloudWatch billing alerts", and save.
+ *
+ * @example
+ * ```ts
+ * // bin/app.ts
+ * import { App } from "aws-cdk-lib";
+ * import { BillingAlarmStack } from "@tlj-blocks/billing-alarm-cdk";
+ *
+ * const app = new App();
+ * new BillingAlarmStack(app, "BillingAlarms", {
+ *   notificationEmail: "me@example.com",
+ *   thresholds: [10, 100], // the default
+ * });
+ * ```
+ */
+export class BillingAlarmStack extends Stack {
+  /** The alarms and the topic this stack created. */
+  readonly billingAlarm: BillingAlarm;
+
+  constructor(scope: Construct, id: string, props: BillingAlarmStackProps) {
+    const { env, ...rest } = props;
+
+    if (env?.region && env.region !== BILLING_METRIC_REGION) {
+      throw new Error(
+        `BillingAlarmStack only works in ${BILLING_METRIC_REGION}, because AWS publishes billing metrics there and nowhere else. Got ${env.region}. ` +
+          `Use the BillingAlarm construct directly if you need it in a stack of your own.`,
+      );
+    }
+
+    super(scope, id, { ...rest, env: { ...env, region: BILLING_METRIC_REGION } });
+
+    this.billingAlarm = new BillingAlarm(this, "BillingAlarm", props);
+  }
+}

package/src/billing-alarm.ts

@@ -0,0 +1,200 @@
+import { Duration } from "aws-cdk-lib";
+import { Construct } from "constructs";
+import * as cloudwatch from "aws-cdk-lib/aws-cloudwatch";
+import * as cloudwatchActions from "aws-cdk-lib/aws-cloudwatch-actions";
+import * as sns from "aws-cdk-lib/aws-sns";
+import * as snsSubscriptions from "aws-cdk-lib/aws-sns-subscriptions";
+
+/** Spend thresholds used when {@link BillingAlarmProps.thresholds} is omitted. */
+export const DEFAULT_THRESHOLDS = [10, 100];
+
+/**
+ * Configuration for the {@link BillingAlarm} construct.
+ */
+export interface BillingAlarmProps {
+  /**
+   * Email address that receives the alarm notifications.
+   *
+   * The construct creates an SNS email subscription for this address. After
+   * the first deploy, AWS sends one confirmation email here. You must click the
+   * link in it before SNS delivers any notification.
+   *
+   * Ignored when {@link topic} is supplied.
+   */
+  notificationEmail?: string;
+
+  /**
+   * Spend levels, in {@link currency}, to alarm at. The construct creates one
+   * alarm per threshold, so you get a separate email each time the bill crosses
+   * one of them.
+   *
+   * @default [10, 100]
+   */
+  thresholds?: number[];
+
+  /**
+   * Currency of the estimated-charges metric. This must match the currency
+   * your account is billed in. AWS publishes the metric under that one currency
+   * only, so a mismatch produces alarms that never receive data.
+   *
+   * @default "USD"
+   */
+  currency?: string;
+
+  /**
+   * An existing SNS topic to notify instead of creating one. Use this to send
+   * billing alarms to a topic you already have, such as one wired to Slack or
+   * PagerDuty. When set, the construct ignores {@link notificationEmail}.
+   *
+   * @default - a new topic with an email subscription to `notificationEmail`
+   */
+  topic?: sns.ITopic;
+
+  /**
+   * Explicit SNS topic name for the created topic. Leave unset to let
+   * CloudFormation generate a unique name.
+   *
+   * @default - a CloudFormation-generated name
+   */
+  topicName?: string;
+
+  /**
+   * Prefix for the generated alarm names. `MyAccount` yields
+   * `MyAccount-billing-over-10-USD`. The alarm name is what you see in the
+   * CloudWatch console and in the subject of the notification email.
+   *
+   * @default "aws"
+   */
+  alarmNamePrefix?: string;
+
+  /**
+   * How often the alarms evaluate the estimated-charges metric. AWS refreshes
+   * this metric a few times a day, so a period shorter than a few hours only
+   * adds evaluations that find no new data.
+   *
+   * @default Duration.hours(6)
+   */
+  period?: Duration;
+}
+
+/**
+ * CloudWatch billing alarms for an AWS account.
+ *
+ * In your stack it creates an {@link sns.Topic} with an email subscription,
+ * unless you pass your own topic, and one {@link cloudwatch.Alarm} per
+ * threshold. Each alarm watches the `AWS/Billing EstimatedCharges` metric and
+ * notifies the topic when the month-to-date charges pass its threshold.
+ *
+ * CloudFormation cannot do either of the two account-level prerequisites, so
+ * you have to do them once by hand.
+ *
+ * 1. Turn on billing alerts. In the billing console, open Billing preferences,
+ *    tick "Receive CloudWatch billing alerts", and save. Until you do, AWS
+ *    never publishes the metric and the alarms stay in `INSUFFICIENT_DATA`.
+ * 2. Deploy to `us-east-1`. AWS publishes the billing metric there only,
+ *    whatever regions you spend in. {@link BillingAlarmStack} sets the region
+ *    for you. If you use this construct directly, put it in a `us-east-1`
+ *    stack.
+ *
+ * The charges reset at the start of each month, so an alarm that fired in
+ * January returns to `OK` in February and can fire again.
+ *
+ * @example
+ * ```ts
+ * import { Stack, StackProps } from "aws-cdk-lib";
+ * import { Construct } from "constructs";
+ * import { BillingAlarm } from "@tlj-blocks/billing-alarm-cdk";
+ *
+ * export class OpsStack extends Stack {
+ *   constructor(scope: Construct, id: string, props?: StackProps) {
+ *     // The billing metric only exists in us-east-1.
+ *     super(scope, id, { ...props, env: { ...props?.env, region: "us-east-1" } });
+ *
+ *     new BillingAlarm(this, "BillingAlarm", {
+ *       notificationEmail: "me@example.com",
+ *       thresholds: [10, 100],
+ *     });
+ *   }
+ * }
+ * ```
+ */
+export class BillingAlarm extends Construct {
+  /** The topic the alarms notify. Add more subscribers to it if you need them. */
+  readonly topic: sns.ITopic;
+  /** One alarm per threshold, in the order the thresholds were given. */
+  readonly alarms: cloudwatch.Alarm[];
+
+  constructor(scope: Construct, id: string, props: BillingAlarmProps = {}) {
+    super(scope, id);
+
+    const currency = props.currency ?? "USD";
+    const prefix = props.alarmNamePrefix ?? "aws";
+    const period = props.period ?? Duration.hours(6);
+    const thresholds = props.thresholds ?? DEFAULT_THRESHOLDS;
+
+    if (thresholds.length === 0) {
+      throw new Error("BillingAlarm: `thresholds` must not be empty.");
+    }
+    for (const threshold of thresholds) {
+      if (!Number.isFinite(threshold) || threshold <= 0) {
+        throw new Error(
+          `BillingAlarm: thresholds must be positive numbers, got ${threshold}.`,
+        );
+      }
+    }
+    if (new Set(thresholds).size !== thresholds.length) {
+      // Duplicates would collide on the generated alarm name.
+      throw new Error("BillingAlarm: `thresholds` must not contain duplicates.");
+    }
+
+    if (props.topic) {
+      this.topic = props.topic;
+    } else {
+      if (!props.notificationEmail) {
+        throw new Error(
+          "BillingAlarm: pass `notificationEmail`, or `topic` to notify an existing topic.",
+        );
+      }
+      const topic = new sns.Topic(this, "Topic", {
+        topicName: props.topicName,
+        displayName: "AWS Billing Alarms",
+      });
+      // SNS delivers nothing until the recipient confirms this subscription.
+      topic.addSubscription(
+        new snsSubscriptions.EmailSubscription(props.notificationEmail),
+      );
+      this.topic = topic;
+    }
+
+    const action = new cloudwatchActions.SnsAction(this.topic);
+
+    this.alarms = thresholds.map((threshold) => {
+      // AWS/Billing EstimatedCharges is a cumulative month-to-date total. AWS
+      // publishes it in us-east-1 only, a few times a day. Maximum over the
+      // period is the right statistic for a running total.
+      const metric = new cloudwatch.Metric({
+        namespace: "AWS/Billing",
+        metricName: "EstimatedCharges",
+        dimensionsMap: { Currency: currency },
+        statistic: "Maximum",
+        period,
+      });
+
+      const alarm = new cloudwatch.Alarm(this, `Over${threshold}`, {
+        alarmName: `${prefix}-billing-over-${threshold}-${currency}`,
+        alarmDescription: `Estimated AWS charges for the current month exceeded ${threshold} ${currency}.`,
+        metric,
+        threshold,
+        evaluationPeriods: 1,
+        comparisonOperator:
+          cloudwatch.ComparisonOperator.GREATER_THAN_THRESHOLD,
+        // Early in the month, and before you switch billing alerts on, there
+        // is no data. That is not a billing problem, so do not alarm on it.
+        treatMissingData: cloudwatch.TreatMissingData.NOT_BREACHING,
+      });
+
+      alarm.addAlarmAction(action);
+      return alarm;
+    });
+  }
+}

package/src/index.ts

@@ -0,0 +1,10 @@
+export {
+  BillingAlarm,
+  DEFAULT_THRESHOLDS,
+  type BillingAlarmProps,
+} from "./billing-alarm";
+export {
+  BillingAlarmStack,
+  BILLING_METRIC_REGION,
+  type BillingAlarmStackProps,
+} from "./billing-alarm-stack";