sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ Budgets/ Budget.ts

import * as budgets from "@distilled.cloud/aws/budgets";
import { isResolved } from "alchemy/Diff";
import { createPhysicalName } from "alchemy/PhysicalName";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import { createInternalTags, diffTags } from "alchemy/Tags";
import * as Effect from "effect/Effect";
import * as Redacted from "effect/Redacted";
import * as Stream from "effect/Stream";
import { AWSEnvironment } from "../Environment.ts";
import type { Providers } from "../Providers.ts";

/**
 * A subscriber notified when a budget notification is triggered.
 */
export interface BudgetSubscriber {
  /**
   * How the subscriber is notified.
   */
  subscriptionType: "EMAIL" | "SNS" | (string & {});
  /**
   * The destination — an email address (for `EMAIL`) or an SNS topic ARN
   * (for `SNS`).
   */
  address: string;
}

/**
 * A threshold that, when crossed, notifies the configured subscribers.
 */
export interface BudgetNotification {
  /**
   * Whether the notification is based on actual or forecasted spend/usage.
   */
  notificationType: "ACTUAL" | "FORECASTED" | (string & {});
  /**
   * How the actual/forecasted amount is compared to the threshold.
   */
  comparisonOperator: "GREATER_THAN" | "LESS_THAN" | "EQUAL_TO" | (string & {});
  /**
   * The threshold value. Interpreted as a percentage of the budget limit by
   * default, or an absolute amount when `thresholdType` is `ABSOLUTE_VALUE`.
   */
  threshold: number;
  /**
   * Whether `threshold` is a percentage of the budget or an absolute value.
   * @default "PERCENTAGE"
   */
  thresholdType?: "PERCENTAGE" | "ABSOLUTE_VALUE" | (string & {});
  /**
   * Subscribers notified when this threshold is crossed.
   */
  subscribers: BudgetSubscriber[];
}

/**
 * The types of cost included in a `COST` budget, such as tax and
 * subscriptions. Other budget types do not have cost types. A flag left out
 * is sent with its AWS default.
 *
 * AWS deprecated cost types in favor of budget metrics and filter
 * expressions, but the Budgets API still accepts them.
 */
export interface BudgetCostTypes {
  /**
   * Whether the budget includes taxes.
   * @default true
   */
  includeTax?: boolean;
  /**
   * Whether the budget includes subscriptions.
   * @default true
   */
  includeSubscription?: boolean;
  /**
   * Whether the budget uses the blended rate.
   * @default false
   */
  useBlended?: boolean;
  /**
   * Whether the budget includes refunds.
   * @default true
   */
  includeRefund?: boolean;
  /**
   * Whether the budget includes credits.
   * @default true
   */
  includeCredit?: boolean;
  /**
   * Whether the budget includes upfront reserved instance costs.
   * @default true
   */
  includeUpfront?: boolean;
  /**
   * Whether the budget includes recurring fees, such as monthly reserved
   * instance fees.
   * @default true
   */
  includeRecurring?: boolean;
  /**
   * Whether the budget includes subscription costs other than reserved
   * instances.
   * @default true
   */
  includeOtherSubscription?: boolean;
  /**
   * Whether the budget includes support subscription fees.
   * @default true
   */
  includeSupport?: boolean;
  /**
   * Whether the budget includes discounts.
   * @default true
   */
  includeDiscount?: boolean;
  /**
   * Whether the budget uses the amortized rate.
   * @default false
   */
  useAmortized?: boolean;
}

export interface BudgetProps {
  /**
   * Name of the budget. Must be unique within the account. If omitted, a
   * unique name is generated from the app, stage, and logical ID.
   *
   * Changing the name replaces the budget.
   */
  budgetName?: string;
  /**
   * What the budget tracks.
   * @default "COST"
   */
  budgetType?:
    | "COST"
    | "USAGE"
    | "RI_UTILIZATION"
    | "RI_COVERAGE"
    | "SAVINGS_PLANS_UTILIZATION"
    | "SAVINGS_PLANS_COVERAGE"
    | (string & {});
  /**
   * The period the budget resets over.
   * @default "MONTHLY"
   */
  timeUnit?: "DAILY" | "MONTHLY" | "QUARTERLY" | "ANNUALLY" | (string & {});
  /**
   * The budgeted amount and its unit, e.g. `{ amount: "100", unit: "USD" }`.
   * Required for `COST` and `USAGE` budgets.
   */
  budgetLimit?: {
    /** The amount, as a string, e.g. `"100"`. */
    amount: string;
    /** The unit — `"USD"` for cost budgets, or the usage unit. */
    unit: string;
  };
  /**
   * Cost filters restricting which costs count against the budget, e.g.
   * `{ Service: ["Amazon Elastic Compute Cloud - Compute"] }`.
   */
  costFilters?: Record<string, string[]>;
  /**
   * The types of cost included in a `COST` budget, e.g.
   * `{ includeCredit: false, includeRefund: false }` to track spend before
   * credits and refunds.
   */
  costTypes?: BudgetCostTypes;
  /**
   * Notifications and their subscribers.
   */
  notifications?: BudgetNotification[];
  /**
   * Tags applied to the budget at creation.
   */
  tags?: Record<string, string>;
}

export interface Budget extends Resource<
  "AWS.Budgets.Budget",
  BudgetProps,
  {
    /**
     * Name of the budget.
     */
    budgetName: string;
    /**
     * The AWS account ID that owns the budget.
     */
    accountId: string;
    /**
     * ARN of the budget, e.g. `arn:aws:budgets::123456789012:budget/my-budget`.
     */
    budgetArn: string;
  },
  never,
  Providers
> {}

/**
 * An AWS Budget — tracks cost or usage against a defined limit over a time
 * period and notifies subscribers when configured thresholds are crossed.
 *
 * Budgets are a global (account-level) resource; they are free and take
 * effect immediately.
 *
 * ### Creating a Budget
 * **Example:** Monthly cost budget with an email alert at 80%
 * ```typescript
 * import * as Budgets from "@alchemy.run/aws/Budgets";
 *
 * const budget = yield* Budgets.Budget("MonthlyCost", {
 *   budgetType: "COST",
 *   timeUnit: "MONTHLY",
 *   budgetLimit: { amount: "100", unit: "USD" },
 *   notifications: [
 *     {
 *       notificationType: "ACTUAL",
 *       comparisonOperator: "GREATER_THAN",
 *       threshold: 80,
 *       thresholdType: "PERCENTAGE",
 *       subscribers: [{ subscriptionType: "EMAIL", address: "team@example.com" }],
 *     },
 *   ],
 * });
 * ```
 *
 * **Example:** Budget scoped to a single service
 * ```typescript
 * const budget = yield* Budgets.Budget("EC2Spend", {
 *   budgetLimit: { amount: "500", unit: "USD" },
 *   costFilters: {
 *     Service: ["Amazon Elastic Compute Cloud - Compute"],
 *   },
 * });
 * ```
 *
 * **Example:** Budget that credits and refunds do not offset
 * ```typescript
 * const budget = yield* Budgets.Budget("GrossSpend", {
 *   budgetLimit: { amount: "600", unit: "USD" },
 *   costTypes: { includeCredit: false, includeRefund: false },
 * });
 * ```
 *
 * @resource
 */
export const Budget = Resource<Budget>("AWS.Budgets.Budget");

/**
 * Compute the ARN of a budget. Budgets is a global service, so the ARN has no
 * region component.
 */
export const budgetArn = (accountId: string, budgetName: string): string =>
  `arn:aws:budgets::${accountId}:budget/${budgetName}`;

const notificationKey = (n: budgets.Notification): string =>
  JSON.stringify({
    NotificationType: n.NotificationType,
    ComparisonOperator: n.ComparisonOperator,
    Threshold: n.Threshold,
    ThresholdType: n.ThresholdType ?? "PERCENTAGE",
  });

const toNotification = (n: BudgetNotification): budgets.Notification => ({
  NotificationType: n.notificationType,
  ComparisonOperator: n.comparisonOperator,
  Threshold: n.threshold,
  ThresholdType: n.thresholdType ?? "PERCENTAGE",
});

const toCostTypes = (c: BudgetCostTypes): budgets.CostTypes => ({
  IncludeTax: c.includeTax ?? true,
  IncludeSubscription: c.includeSubscription ?? true,
  UseBlended: c.useBlended ?? false,
  IncludeRefund: c.includeRefund ?? true,
  IncludeCredit: c.includeCredit ?? true,
  IncludeUpfront: c.includeUpfront ?? true,
  IncludeRecurring: c.includeRecurring ?? true,
  IncludeOtherSubscription: c.includeOtherSubscription ?? true,
  IncludeSupport: c.includeSupport ?? true,
  IncludeDiscount: c.includeDiscount ?? true,
  UseAmortized: c.useAmortized ?? false,
});

/**
 * Distilled marks `Subscriber.Address` sensitive, so observed subscribers
 * come back as `Redacted` — unwrap before diffing, or every observed
 * subscriber compares as `<redacted>` and gets torn down (and deleting the
 * last subscriber deletes the whole notification).
 */
const subscriberAddress = (s: budgets.Subscriber): string =>
  Redacted.isRedacted(s.Address) ? Redacted.value(s.Address) : s.Address;

const subscriberKey = (s: budgets.Subscriber): string =>
  `${s.SubscriptionType}:${subscriberAddress(s)}`;

export const BudgetProvider = () =>
  Provider.effect(
    Budget,
    Effect.gen(function* () {
      const createName = Effect.fn(function* (
        id: string,
        props: { budgetName?: string | undefined },
      ) {
        return props.budgetName ?? (yield* createPhysicalName({ id, maxLength: 100 }));
      });

      const buildBudget = (name: string, props: BudgetProps): budgets.Budget => ({
        BudgetName: name,
        BudgetType: props.budgetType ?? "COST",
        TimeUnit: props.timeUnit ?? "MONTHLY",
        BudgetLimit: props.budgetLimit
          ? { Amount: props.budgetLimit.amount, Unit: props.budgetLimit.unit }
          : undefined,
        CostFilters: props.costFilters,
        CostTypes: props.costTypes ? toCostTypes(props.costTypes) : undefined,
      });

      const syncNotifications = Effect.fn(function* (
        accountId: string,
        name: string,
        desired: BudgetNotification[],
      ) {
        const current = yield* budgets.describeNotificationsForBudget
          .pages({
            AccountId: accountId,
            BudgetName: name,
          })
          .pipe(
            Stream.runCollect,
            Effect.map((chunk) => Array.from(chunk).flatMap((page) => page.Notifications ?? [])),
            Effect.catchTag("NotFoundException", () => Effect.succeed([])),
          );
        const currentKeys = new Set(current.map(notificationKey));
        const desiredNotifs = desired.map(toNotification);
        const desiredKeys = new Set(desiredNotifs.map(notificationKey));

        for (const n of desired) {
          const notif = toNotification(n);
          const desiredSubscribers = n.subscribers.map((s): budgets.Subscriber => ({
            SubscriptionType: s.subscriptionType,
            Address: s.address,
          }));
          if (!currentKeys.has(notificationKey(notif))) {
            // The notification listing is eventually consistent — right after
            // `createBudget(NotificationsWithSubscribers)` it can come back
            // empty, so an already-created notification surfaces here as a
            // DuplicateRecordException race.
            yield* budgets
              .createNotification({
                AccountId: accountId,
                BudgetName: name,
                Notification: notif,
                Subscribers: desiredSubscribers,
              })
              .pipe(Effect.catchTag("DuplicateRecordException", () => Effect.void));
            continue;
          }
          // The notification already exists — converge its subscribers by
          // diffing the OBSERVED subscriber list against the desired one.
          const observedSubscribers = yield* budgets
            .describeSubscribersForNotification({
              AccountId: accountId,
              BudgetName: name,
              Notification: notif,
            })
            .pipe(
              Effect.map((r) => r.Subscribers ?? []),
              Effect.catchTag("NotFoundException", () => Effect.succeed([])),
            );
          const observedKeys = new Set(observedSubscribers.map(subscriberKey));
          const desiredSubKeys = new Set(desiredSubscribers.map(subscriberKey));
          // Create before delete so the notification never drops to zero
          // subscribers (the API requires at least one).
          for (const s of desiredSubscribers) {
            if (observedKeys.has(subscriberKey(s))) continue;
            yield* budgets
              .createSubscriber({
                AccountId: accountId,
                BudgetName: name,
                Notification: notif,
                Subscriber: s,
              })
              .pipe(Effect.catchTag("DuplicateRecordException", () => Effect.void));
          }
          for (const s of observedSubscribers) {
            if (desiredSubKeys.has(subscriberKey(s))) continue;
            yield* budgets
              .deleteSubscriber({
                AccountId: accountId,
                BudgetName: name,
                Notification: notif,
                Subscriber: s,
              })
              .pipe(Effect.catchTag("NotFoundException", () => Effect.void));
          }
        }
        for (const n of current) {
          if (desiredKeys.has(notificationKey(n))) continue;
          yield* budgets
            .deleteNotification({
              AccountId: accountId,
              BudgetName: name,
              Notification: n,
            })
            .pipe(Effect.catchTag("NotFoundException", () => Effect.void));
        }
      });

      const syncTags = Effect.fn(function* (arn: string, desired: Record<string, string>) {
        // Diff against OBSERVED cloud tags (not olds/output) so adoption and
        // out-of-band drift converge correctly.
        const observed = yield* budgets.listTagsForResource({ ResourceARN: arn }).pipe(
          Effect.map((r) =>
            Object.fromEntries((r.ResourceTags ?? []).map((t) => [t.Key, t.Value])),
          ),
          Effect.catchTag("NotFoundException", () => Effect.succeed({} as Record<string, string>)),
        );
        const { removed, upsert } = diffTags(observed, desired);
        if (upsert.length > 0) {
          yield* budgets.tagResource({
            ResourceARN: arn,
            ResourceTags: upsert,
          });
        }
        if (removed.length > 0) {
          yield* budgets.untagResource({
            ResourceARN: arn,
            ResourceTagKeys: removed,
          });
        }
      });

      return Budget.Provider.of({
        stables: ["budgetName", "accountId", "budgetArn"],
        list: () =>
          Effect.gen(function* () {
            const { accountId } = yield* AWSEnvironment.current;
            return yield* budgets.describeBudgets.pages({ AccountId: accountId }).pipe(
              Stream.runCollect,
              Effect.map((chunk) =>
                Array.from(chunk)
                  .flatMap((page) => page.Budgets ?? [])
                  .map((b) => ({
                    budgetName: b.BudgetName,
                    accountId,
                    budgetArn: budgetArn(accountId, b.BudgetName),
                  })),
              ),
              Effect.catchTag("NotFoundException", () => Effect.succeed([])),
            );
          }),
        read: Effect.fn(function* ({ id, olds, output }) {
          const { accountId } = yield* AWSEnvironment.current;
          const name = output?.budgetName ?? (yield* createName(id, olds ?? {}));
          const found = yield* budgets
            .describeBudget({ AccountId: accountId, BudgetName: name })
            .pipe(Effect.catchTag("NotFoundException", () => Effect.undefined));
          if (!found?.Budget) return undefined;
          return {
            budgetName: name,
            accountId,
            budgetArn: budgetArn(accountId, name),
          };
        }),
        diff: Effect.fn(function* ({ id, news = {}, olds = {} }) {
          if (!isResolved(news)) return undefined;
          const oldName = yield* createName(id, olds);
          const newName = yield* createName(id, news);
          if (oldName !== newName) return { action: "replace" } as const;
        }),
        reconcile: Effect.fn(function* ({ id, news = {}, output, session }) {
          const { accountId } = yield* AWSEnvironment.current;
          const name = output?.budgetName ?? (yield* createName(id, news));
          const internalTags = yield* createInternalTags(id);
          const budgetBody = buildBudget(name, news);

          // OBSERVE — cloud state is authoritative.
          const live = yield* budgets
            .describeBudget({ AccountId: accountId, BudgetName: name })
            .pipe(
              Effect.map((r) => r.Budget),
              Effect.catchTag("NotFoundException", () => Effect.undefined),
            );

          if (!live) {
            // ENSURE — create; tolerate a DuplicateRecord race.
            yield* budgets
              .createBudget({
                AccountId: accountId,
                Budget: budgetBody,
                NotificationsWithSubscribers: news.notifications?.map((n) => ({
                  Notification: toNotification(n),
                  Subscribers: n.subscribers.map((s) => ({
                    SubscriptionType: s.subscriptionType,
                    Address: s.address,
                  })),
                })),
                ResourceTags: Object.entries({
                  ...news.tags,
                  ...internalTags,
                }).map(([Key, Value]) => ({ Key, Value })),
              })
              .pipe(
                Effect.catchTag("DuplicateRecordException", () =>
                  budgets.updateBudget({
                    AccountId: accountId,
                    NewBudget: budgetBody,
                  }),
                ),
              );
          } else {
            // SYNC — updateBudget is a full replace of the budget definition.
            yield* budgets.updateBudget({
              AccountId: accountId,
              NewBudget: budgetBody,
            });
          }

          // SYNC notifications — the budget update does not touch these.
          yield* syncNotifications(accountId, name, news.notifications ?? []);

          // SYNC tags against observed cloud tags.
          const arn = budgetArn(accountId, name);
          yield* syncTags(arn, { ...news.tags, ...internalTags });

          yield* session.note(name);
          return { budgetName: name, accountId, budgetArn: arn };
        }),
        delete: Effect.fn(function* ({ output }) {
          yield* budgets
            .deleteBudget({
              AccountId: output.accountId,
              BudgetName: output.budgetName,
            })
            .pipe(Effect.catchTag("NotFoundException", () => Effect.void));
        }),
      });
    }),
  );