sailfork / t3code-github / .repos/ alchemy-effect/ packages/ gcp/ src/ BillingBudgets/ BillingBudget.ts

import * as billingbudgets from "@distilled.cloud/gcp/billingbudgets_v1";
import { unownedUnlessPrevious } from "alchemy/AdoptPolicy";
import { isResolved } from "alchemy/Diff";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import type { Providers } from "../Providers.ts";
import {
  billingAccountIdOf,
  billingAccountParent,
  budgetNameOf,
  compact,
  filterChanged,
  findBudgetByDisplayName,
  generatedDisplayName,
  getBudget,
  jsonEqual,
  parseBudgetName,
  resolveBillingAccountId,
  resolveProjectRefs,
  sortedStrings,
} from "./internal.ts";

export type Money = {
  /**
   * Whole units of the amount. For USD, `1` is one dollar.
   */
  units?: string;
  /**
   * ISO 4217 currency code. If set on create, it must match the billing
   * account currency.
   */
  currencyCode?: string;
  /**
   * Nano (10^-9) units of the amount. Must be between -999,999,999 and
   * 999,999,999.
   */
  nanos?: number;
};

export type BudgetAmount = {
  /**
   * Use last calendar period's actual spend as this period's budget.
   * Cannot be combined with `customPeriod`. Empty object selects this
   * mode.
   */
  lastPeriodAmount?: Record<string, never> | {};
  /**
   * Explicit budgeted amount. `currencyCode` is optional on create and
   * must match the billing account (and the existing budget on update).
   */
  specifiedAmount?: Money;
};

export type CustomPeriod = {
  /**
   * Inclusive start date. Must be after 2017-01-01.
   */
  startDate?: { year?: number; month?: number; day?: number };
  /**
   * Inclusive end date. Budgets past this date are not processed. Omit
   * to track all usage since `startDate`.
   */
  endDate?: { year?: number; month?: number; day?: number };
};

export type BudgetFilter = {
  /**
   * Folders and organizations whose usage is included, as
   * `folders/{folderId}` or `organizations/{organizationId}`.
   */
  resourceAncestors?: string[];
  /**
   * Subaccounts of the form `billingAccounts/{account_id}`.
   */
  subaccounts?: string[];
  /**
   * Recurring calendar period (`MONTH`, `QUARTER`, `YEAR`). Default
   * `MONTH` when `customPeriod` is unset.
   */
  calendarPeriod?: string;
  /**
   * Services of the form `services/{service_id}`.
   */
  services?: string[];
  /**
   * Credit types subtracted from gross cost when
   * `creditTypesTreatment` is `INCLUDE_SPECIFIED_CREDITS`.
   */
  creditTypes?: string[];
  /**
   * How credits are treated (`INCLUDE_ALL_CREDITS`,
   * `EXCLUDE_ALL_CREDITS`, `INCLUDE_SPECIFIED_CREDITS`).
   */
  creditTypesTreatment?: string;
  /**
   * Projects of the form `projects/{project}`. Omit to include every
   * project the billing account pays for.
   */
  projects?: string[];
  /**
   * Static (non-recurring) time period. Mutually exclusive with
   * `calendarPeriod`.
   */
  customPeriod?: CustomPeriod;
  /**
   * Single resource-label key mapped to a list of values. Usage from
   * only those labeled resources is included.
   */
  labels?: Record<string, unknown[] | undefined>;
};

export type ThresholdRule = {
  /**
   * Alert when spend exceeds this fraction of the budget (`0.5` is 50%).
   */
  thresholdPercent?: number;
  /**
   * Spend basis (`CURRENT_SPEND` or `FORECASTED_SPEND`). Defaults to
   * `CURRENT_SPEND`.
   */
  spendBasis?: string;
};

export type NotificationsRule = {
  /**
   * Schema version of Pub/Sub notifications. Only `"1.0"` is accepted.
   */
  schemaVersion?: string;
  /**
   * Pub/Sub topic for programmatic notifications, as
   * `projects/{project}/topics/{topic}`.
   */
  pubsubTopic?: string;
  /**
   * When true, default IAM billing-account recipients are not emailed.
   */
  disableDefaultIamRecipients?: boolean;
  /**
   * When true and the budget tracks a single project, also notify that
   * project's Owners.
   */
  enableProjectLevelRecipients?: boolean;
  /**
   * Cloud Monitoring email notification channels, as
   * `projects/{project}/notificationChannels/{channel}`. Max 5.
   */
  monitoringNotificationChannels?: string[];
};

export type BillingBudgetProps = {
  /**
   * Billing account id (`XXXXXX-XXXXXX-XXXXXX` or
   * `billingAccounts/{id}`). If omitted, Alchemy uses the billing
   * account linked to the current project. Immutable — changing it
   * replaces the budget.
   */
  billingAccountId?: string;
  /**
   * Server-assigned budget id (the `{budget}` segment of
   * `billingAccounts/{billingAccount}/budgets/{budget}`). Omit on
   * create; pass the observed id to update in place. Immutable —
   * changing it replaces the budget.
   */
  budgetId?: string;
  /**
   * User-visible display name (60 characters), shown in budget alert
   * emails. If omitted, a unique name is generated from the stack, stage,
   * and logical id.
   */
  displayName?: string;
  /**
   * Budgeted amount. Required. Either `specifiedAmount` or
   * `lastPeriodAmount`.
   */
  amount: BudgetAmount;
  /**
   * Filters that scope actual spend (projects, services, period, …).
   */
  budgetFilter?: BudgetFilter;
  /**
   * Thresholds that trigger alert emails and populate Pub/Sub payloads.
   */
  thresholdRules?: ThresholdRule[];
  /**
   * Notification targets (email channels and/or Pub/Sub).
   */
  notificationsRule?: NotificationsRule;
  /**
   * Who owns the budget (`ALL_USERS` or `BILLING_ACCOUNT`).
   */
  ownershipScope?: string;
};

export type BillingBudget = Resource<
  "GCP.BillingBudgets.BillingBudget",
  BillingBudgetProps,
  {
    /** Full resource name `billingAccounts/{billingAccount}/budgets/{budget}`. */
    name: string;
    /** Server-assigned budget id (last path segment). */
    budgetId: string;
    /** Billing account id. */
    billingAccountId: string;
    /** Display name. */
    displayName: string | undefined;
    /** Budgeted amount. */
    amount: BudgetAmount | undefined;
    /** Spend filter. */
    budgetFilter: BudgetFilter | undefined;
    /** Threshold rules. */
    thresholdRules: ThresholdRule[];
    /** Notification rules. */
    notificationsRule: NotificationsRule | undefined;
    /** Ownership scope. */
    ownershipScope: string | undefined;
    /** Server etag for read-modify-write. */
    etag: string | undefined;
  },
  never,
  Providers
>;

/**
 * A Cloud Billing budget.
 *
 * Budgets have no labels field and the display name appears in alert
 * emails, so Alchemy finds its budget by display name within the current
 * project's scope: `read` reports a budget as owned only when it carries
 * the generated name (an explicit `displayName` is reported as unowned —
 * adopt it with `--adopt`), and nuke cannot discover budgets. The
 * physical id is a server-assigned UUID. Changing `billingAccountId` or
 * `budgetId` replaces the budget. Amount, filter, thresholds,
 * notifications, and display name update in place.
 *
 * ### Creating a Budget
 * **Example:** Project-scoped monthly budget
 * ```typescript
 * const budget = yield* GCP.BillingBudgets.BillingBudget("Spend", {
 *   displayName: "cap",
 *   amount: { specifiedAmount: { currencyCode: "USD", units: "10" } },
 *   budgetFilter: {
 *     projects: ["projects/my-project"],
 *     calendarPeriod: "MONTH",
 *   },
 *   thresholdRules: [{ thresholdPercent: 0.5, spendBasis: "CURRENT_SPEND" }],
 * });
 * ```
 *
 * **Example:** Last-period amount
 * ```typescript
 * const budget = yield* GCP.BillingBudgets.BillingBudget("Spend", {
 *   amount: { lastPeriodAmount: {} },
 *   budgetFilter: { calendarPeriod: "MONTH" },
 * });
 * ```
 *
 * ### Updating a Budget
 * **Example:** Raise the cap and add a forecasted threshold
 * ```typescript
 * const budget = yield* GCP.BillingBudgets.BillingBudget("Spend", {
 *   displayName: "cap",
 *   amount: { specifiedAmount: { currencyCode: "USD", units: "25" } },
 *   budgetFilter: {
 *     projects: ["projects/my-project"],
 *     calendarPeriod: "MONTH",
 *   },
 *   thresholdRules: [
 *     { thresholdPercent: 0.5, spendBasis: "CURRENT_SPEND" },
 *     { thresholdPercent: 0.9, spendBasis: "FORECASTED_SPEND" },
 *   ],
 * });
 * ```
 *
 * @resource
 * @category BillingBudgets
 */
export const BillingBudget = Resource<BillingBudget>("GCP.BillingBudgets.BillingBudget");

export class BillingBudgetNotResolved extends Data.TaggedError(
  "GCP.BillingBudgets.BillingBudgetNotResolved",
)<{
  resourceName: string;
}> {}

const toMoney = (money: billingbudgets.GoogleTypeMoney | Money | undefined): Money | undefined => {
  if (money === undefined) return undefined;
  if (money.units === undefined && money.currencyCode === undefined && money.nanos === undefined) {
    return undefined;
  }
  return compact({
    units: money.units,
    currencyCode: money.currencyCode,
    nanos: money.nanos === 0 ? undefined : money.nanos,
  });
};

const toAmount = (
  amount: billingbudgets.GoogleCloudBillingBudgetsV1BudgetAmount | BudgetAmount | undefined,
): BudgetAmount | undefined => {
  if (amount === undefined) return undefined;
  const specifiedAmount = toMoney(amount.specifiedAmount);
  const lastPeriodAmount = amount.lastPeriodAmount !== undefined ? {} : undefined;
  if (specifiedAmount === undefined && lastPeriodAmount === undefined) {
    return undefined;
  }
  return compact({ specifiedAmount, lastPeriodAmount });
};

const toDate = (
  date: billingbudgets.GoogleTypeDate | CustomPeriod["startDate"] | undefined,
): CustomPeriod["startDate"] | undefined => {
  if (date === undefined) return undefined;
  if (date.year === undefined && date.month === undefined && date.day === undefined) {
    return undefined;
  }
  return compact({ year: date.year, month: date.month, day: date.day });
};

const toCustomPeriod = (
  period: billingbudgets.GoogleCloudBillingBudgetsV1CustomPeriod | CustomPeriod | undefined,
): CustomPeriod | undefined => {
  if (period === undefined) return undefined;
  const startDate = toDate(period.startDate);
  const endDate = toDate(period.endDate);
  if (startDate === undefined && endDate === undefined) return undefined;
  return compact({ startDate, endDate });
};

const toFilter = (
  filter: billingbudgets.GoogleCloudBillingBudgetsV1Filter | BudgetFilter | undefined,
): BudgetFilter | undefined => {
  if (filter === undefined) return undefined;
  const next = compact({
    resourceAncestors: filter.resourceAncestors
      ? sortedStrings(filter.resourceAncestors)
      : undefined,
    subaccounts: filter.subaccounts ? sortedStrings(filter.subaccounts) : undefined,
    calendarPeriod: filter.calendarPeriod,
    services: filter.services ? sortedStrings(filter.services) : undefined,
    creditTypes: filter.creditTypes ? sortedStrings(filter.creditTypes) : undefined,
    creditTypesTreatment: filter.creditTypesTreatment,
    projects: filter.projects ? sortedStrings(filter.projects) : undefined,
    customPeriod: toCustomPeriod(filter.customPeriod),
    labels: filter.labels,
  });
  return Object.keys(next).length > 0 ? next : undefined;
};

const toThresholdRules = (
  rules:
    | readonly billingbudgets.GoogleCloudBillingBudgetsV1ThresholdRule[]
    | readonly ThresholdRule[]
    | undefined,
): ThresholdRule[] =>
  (rules ?? [])
    .map((rule) =>
      compact({
        thresholdPercent: rule.thresholdPercent,
        spendBasis: rule.spendBasis ?? "CURRENT_SPEND",
      }),
    )
    .sort((left, right) => {
      const percent = (left.thresholdPercent ?? 0) - (right.thresholdPercent ?? 0);
      if (percent !== 0) return percent;
      return (left.spendBasis ?? "").localeCompare(right.spendBasis ?? "");
    });

const toNotifications = (
  rule: billingbudgets.GoogleCloudBillingBudgetsV1NotificationsRule | NotificationsRule | undefined,
): NotificationsRule | undefined => {
  if (rule === undefined) return undefined;
  const next = compact({
    schemaVersion: rule.schemaVersion,
    pubsubTopic: rule.pubsubTopic,
    disableDefaultIamRecipients: rule.disableDefaultIamRecipients,
    enableProjectLevelRecipients: rule.enableProjectLevelRecipients,
    monitoringNotificationChannels: rule.monitoringNotificationChannels
      ? sortedStrings(rule.monitoringNotificationChannels)
      : undefined,
  });
  return Object.keys(next).length > 0 ? next : undefined;
};

const toAttrs = (
  budget: billingbudgets.GoogleCloudBillingBudgetsV1Budget,
  billingAccountId: string,
) => {
  const name = budget.name ?? "";
  const parsed = parseBudgetName(name, billingAccountId);
  return {
    name,
    budgetId: parsed.budgetId,
    billingAccountId: parsed.billingAccountId || billingAccountId,
    displayName: budget.displayName,
    amount: toAmount(budget.amount),
    budgetFilter: toFilter(budget.budgetFilter),
    thresholdRules: toThresholdRules(budget.thresholdRules),
    notificationsRule: toNotifications(budget.notificationsRule),
    ownershipScope: budget.ownershipScope,
    etag: budget.etag,
  };
};

const desiredAmount = (
  news: BudgetAmount,
  observed: BudgetAmount | undefined,
): billingbudgets.GoogleCloudBillingBudgetsV1BudgetAmount => {
  if (news.lastPeriodAmount !== undefined) {
    return { lastPeriodAmount: {} };
  }
  const specified = news.specifiedAmount ?? {};
  return {
    specifiedAmount: compact({
      units: specified.units,
      currencyCode: specified.currencyCode ?? observed?.specifiedAmount?.currencyCode ?? "USD",
      nanos: specified.nanos,
    }),
  };
};

const toCreateBody = (
  news: BillingBudgetProps,
  displayName: string,
  observed: BudgetAmount | undefined,
): billingbudgets.GoogleCloudBillingBudgetsV1Budget =>
  compact({
    displayName,
    amount: desiredAmount(news.amount, observed),
    budgetFilter: news.budgetFilter
      ? (toFilter(news.budgetFilter) as
          | billingbudgets.GoogleCloudBillingBudgetsV1Filter
          | undefined)
      : undefined,
    thresholdRules:
      news.thresholdRules !== undefined ? toThresholdRules(news.thresholdRules) : undefined,
    notificationsRule: news.notificationsRule
      ? (toNotifications(news.notificationsRule) as
          | billingbudgets.GoogleCloudBillingBudgetsV1NotificationsRule
          | undefined)
      : undefined,
    ownershipScope: news.ownershipScope,
  }) as billingbudgets.GoogleCloudBillingBudgetsV1Budget;

export const BillingBudgetProvider = () =>
  Provider.succeed(BillingBudget, {
    stables: ["name", "budgetId", "billingAccountId"],

    diff: Effect.fn(function* ({ news, olds, output }) {
      if (!isResolved(news)) return undefined;
      const previousId = olds?.budgetId ?? output?.budgetId;
      const idChanged =
        previousId !== undefined && news.budgetId !== undefined && news.budgetId !== previousId;
      const previousAccount = olds?.billingAccountId ?? output?.billingAccountId;
      const accountChanged =
        previousAccount !== undefined &&
        news.billingAccountId !== undefined &&
        billingAccountIdOf(news.billingAccountId) !== billingAccountIdOf(previousAccount);
      if (!idChanged && !accountChanged) return undefined;
      return { action: "replace" as const, deleteFirst: true };
    }),

    read: Effect.fn(function* ({ id, olds, output, previous }) {
      const billingAccountId = yield* resolveBillingAccountId(
        olds?.billingAccountId,
        output?.billingAccountId,
      );
      const budgetId = output?.budgetId ?? olds?.budgetId;
      const name = output?.name ?? (budgetId ? budgetNameOf(billingAccountId, budgetId) : "");
      const generated = yield* generatedDisplayName(id);
      const existing =
        (yield* getBudget(name)) ??
        (yield* findBudgetByDisplayName(
          billingAccountParent(billingAccountId),
          olds?.displayName ?? output?.displayName ?? generated,
        ));
      if (existing === undefined) return undefined;
      const attrs = toAttrs(existing, billingAccountId);
      return existing.displayName === generated
        ? attrs
        : unownedUnlessPrevious(attrs, previous, "name");
    }),

    reconcile: Effect.fn(function* ({ id, news, output }) {
      const billingAccountId = yield* resolveBillingAccountId(
        news.billingAccountId,
        output?.billingAccountId,
      );
      const parent = billingAccountParent(billingAccountId);
      const desiredDisplayName =
        news.displayName ?? output?.displayName ?? (yield* generatedDisplayName(id));
      const resolvedProjects = yield* resolveProjectRefs(news.budgetFilter?.projects);
      const desiredNews =
        resolvedProjects === undefined
          ? news
          : {
              ...news,
              budgetFilter: {
                ...news.budgetFilter,
                projects: resolvedProjects,
              },
            };

      let current = yield* getBudget(
        output?.name ?? (news.budgetId ? budgetNameOf(billingAccountId, news.budgetId) : ""),
      );
      if (current === undefined && news.budgetId === undefined) {
        current = yield* findBudgetByDisplayName(parent, desiredDisplayName);
      }

      if (current === undefined) {
        const created = yield* billingbudgets
          .createBillingAccountsBudgets({
            parent,
            body: toCreateBody(desiredNews, desiredDisplayName, undefined),
          })
          .pipe(
            Effect.catchTag("Conflict", () => findBudgetByDisplayName(parent, desiredDisplayName)),
          );
        current = created ?? undefined;
      }

      if (current === undefined || !current.name) {
        return yield* new BillingBudgetNotResolved({
          resourceName: output?.name ?? `${parent}/budgets`,
        });
      }

      const observedAmount = toAmount(current.amount);
      const desiredBody = toCreateBody(desiredNews, desiredDisplayName, observedAmount);
      const mask: string[] = [];
      if ((current.displayName ?? "") !== desiredDisplayName) {
        mask.push("displayName");
      }
      if (!jsonEqual(toAmount(current.amount), toAmount(desiredBody.amount))) {
        mask.push("amount");
      }
      if (
        desiredNews.budgetFilter !== undefined &&
        filterChanged(
          toFilter(current.budgetFilter) as Record<string, unknown> | undefined,
          toFilter(desiredNews.budgetFilter) as Record<string, unknown> | undefined,
        )
      ) {
        mask.push("budgetFilter");
      }
      if (
        desiredNews.thresholdRules !== undefined &&
        !jsonEqual(
          toThresholdRules(current.thresholdRules),
          toThresholdRules(desiredNews.thresholdRules),
        )
      ) {
        mask.push("thresholdRules");
      }
      if (
        desiredNews.notificationsRule !== undefined &&
        !jsonEqual(
          toNotifications(current.notificationsRule),
          toNotifications(desiredNews.notificationsRule),
        )
      ) {
        mask.push("notificationsRule");
      }
      if (
        desiredNews.ownershipScope !== undefined &&
        (current.ownershipScope ?? "") !== desiredNews.ownershipScope
      ) {
        mask.push("ownershipScope");
      }

      if (mask.length > 0) {
        current = yield* billingbudgets.patchBillingAccountsBudgets({
          name: current.name,
          updateMask: mask.join(","),
          body: {
            ...desiredBody,
            etag: current.etag,
          },
        });
      }

      return toAttrs(current, billingAccountId);
    }),

    delete: Effect.fn(function* ({ output }) {
      if (!output.name) return;
      yield* billingbudgets
        .deleteBillingAccountsBudgets({ name: output.name })
        .pipe(Effect.catchTag(["NotFound", "BudgetNotFound"], () => Effect.void));
    }),
  });