sailfork / t3code-github / .repos/ alchemy-effect/ packages/ stripe/ src/ Alert.ts

import { withRequestOptions } from "@distilled.cloud/stripe";
import {
  GetBillingAlerts,
  GetBillingAlert,
  CreateBillingAlert,
  CreateBillingAlertActivate,
  CreateBillingAlertArchive,
  CreateBillingAlertDeactivate,
  type BillingAlert as StripeBillingAlert,
  type ThresholdsResourceUsageAlertFilterCustomer,
  type ThresholdsResourceUsageThresholdConfig,
  type ThresholdsResourceUsageThresholdConfigMeter,
} from "@distilled.cloud/stripe/stripe";
import { isResolved } from "alchemy/Diff";
import { createPhysicalName } from "alchemy/PhysicalName";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import { isMissingStripeResource } from "./missing.ts";
import type { Providers } from "./Providers.ts";

const TITLE_MAX_LENGTH = 256;
const LIST_PAGE_SIZE = 100;
const LIST_MAX_PAGES = 100;

/** The type of billing alert. Currently only usage-threshold alerts. */
export type AlertType = "usage_threshold";

/** Status of a billing alert. Archived alerts cannot be reactivated. */
export type AlertStatus = "active" | "archived" | "inactive";

/** Desired status for a managed alert. Archived is delete-only. */
export type AlertDesiredStatus = "active" | "inactive";

/** How a usage-threshold alert fires. */
export type AlertRecurrence = "one_time";

/** Restricts a usage-threshold alert to a single customer. */
export interface AlertUsageThresholdFilter {
  /**
   * Filter kind. Must be `customer`.
   */
  type: "customer";
  /**
   * Stripe Customer id (`cus_…`) this alert is limited to.
   */
  customer?: string;
}

/** Configuration for a usage-threshold billing alert. Create-only. */
export interface AlertUsageThreshold {
  /**
   * Usage value at which the alert fires. Create-only — changing it
   * replaces the alert.
   */
  gte: number;
  /**
   * Id of the Billing Meter whose usage is monitored (`mtr_…`).
   * Create-only — changing it replaces the alert.
   */
  meter: string;
  /**
   * How the alert behaves after firing.
   * @default "one_time"
   */
  recurrence?: AlertRecurrence;
  /**
   * Optional filters that limit the alert's scope. Stripe currently
   * accepts at most one `customer` filter. Create-only.
   */
  filters?: AlertUsageThresholdFilter[];
}

export interface AlertProps {
  /**
   * Title of the alert. If omitted, a unique title is generated from the
   * stack, stage, and logical id. Create-only — changing it replaces the
   * alert. Max 256 characters.
   */
  title?: string;
  /**
   * Type of alert to create.
   * @default "usage_threshold"
   */
  alertType?: AlertType;
  /**
   * Usage-threshold configuration. Create-only — changing `gte`, `meter`,
   * `recurrence`, or `filters` replaces the alert.
   */
  usageThreshold: AlertUsageThreshold;
  /**
   * Whether the alert can fire. `inactive` deactivates in place (and can
   * be reactivated). Destroy archives the alert (irreversible).
   * @default "active"
   */
  status?: AlertDesiredStatus;
}

export type Alert = Resource<
  "Stripe.Alert",
  AlertProps,
  {
    /** Stripe billing alert id (`alrt_…`). */
    id: string;
    /** Title of the alert. */
    title: string;
    /** Type of the alert. */
    alertType: AlertType;
    /** Status of the alert. */
    status: AlertStatus;
    /** Usage-threshold configuration, if set. */
    usageThreshold: AlertUsageThreshold | undefined;
    /** Whether the alert exists in live mode. */
    livemode: boolean;
  },
  never,
  Providers
>;

/**
 * A Stripe Billing Alert — notifies you when a usage threshold on a
 * [Billing Meter](https://docs.stripe.com/api/billing/meter) is crossed.
 * `title`, `alertType`, and `usageThreshold` are immutable; changing them
 * replaces the alert. `status` is changed with Stripe's activate/deactivate
 * endpoints.
 *
 * Billing alerts have no metadata field and cannot be hard-deleted.
 * Destroying this resource archives the alert (irreversible). Archived
 * alerts leave the list API and cannot be reactivated.
 *
 * @see https://docs.stripe.com/api/billing/alert
 *
 * ### Creating an Alert
 * **Example:** Usage threshold on a meter
 * ```typescript
 * const apiCalls = yield* Stripe.BillingMeter("api-calls", {
 *   displayName: "API Calls",
 *   eventName: "api_call",
 *   defaultAggregation: { formula: "sum" },
 * });
 * const highUsage = yield* Stripe.Alert("high-usage", {
 *   title: "API Request usage alert",
 *   usageThreshold: {
 *     gte: 10000,
 *     meter: apiCalls.id,
 *     recurrence: "one_time",
 *   },
 * });
 * ```
 *
 * **Example:** Limit the alert to one customer
 * ```typescript
 * const highUsage = yield* Stripe.Alert("high-usage", {
 *   title: "Customer API usage alert",
 *   usageThreshold: {
 *     gte: 1000,
 *     meter: apiCalls.id,
 *     recurrence: "one_time",
 *     filters: [{ type: "customer", customer: customer.id }],
 *   },
 * });
 * ```
 *
 * ### Updating an Alert
 * **Example:** Deactivate without archiving
 * ```typescript
 * const highUsage = yield* Stripe.Alert("high-usage", {
 *   title: "API Request usage alert",
 *   usageThreshold: {
 *     gte: 10000,
 *     meter: apiCalls.id,
 *     recurrence: "one_time",
 *   },
 *   status: "inactive",
 * });
 * ```
 *
 * ### Archiving an Alert
 * **Example:** Destroy archives rather than deleting
 * ```typescript
 * // stack.destroy() / resource removal archives the alert
 * const highUsage = yield* Stripe.Alert("high-usage", {
 *   title: "API Request usage alert",
 *   usageThreshold: {
 *     gte: 10000,
 *     meter: apiCalls.id,
 *     recurrence: "one_time",
 *   },
 * });
 * ```
 *
 * @resource
 * @product Billing
 */
export const Alert = Resource<Alert>("Stripe.Alert");

export class AlertNotResolved extends Data.TaggedError("Stripe.AlertNotResolved")<{
  title: string;
}> {}

type AlertAttributes = Alert["Attributes"];

const toTitle = (id: string, title: string | undefined, existing?: string) =>
  Effect.gen(function* () {
    return title ?? existing ?? (yield* createPhysicalName({ id, maxLength: TITLE_MAX_LENGTH }));
  });

const toMeterId = (meter: ThresholdsResourceUsageThresholdConfigMeter): string =>
  typeof meter === "string" ? meter : meter.id;

const toCustomerId = (
  customer: ThresholdsResourceUsageAlertFilterCustomer | null,
): string | undefined => {
  if (customer == null) return undefined;
  if (typeof customer === "string") return customer;
  return customer.id;
};

const toUsageThreshold = (
  config: ThresholdsResourceUsageThresholdConfig | null,
): AlertUsageThreshold | undefined => {
  if (config === null) return undefined;
  const filters = (config.filters ?? []).map((filter) => {
    const customer = toCustomerId(filter.customer);
    return customer !== undefined ? { type: filter.type, customer } : { type: filter.type };
  });
  return {
    gte: config.gte,
    meter: toMeterId(config.meter),
    recurrence: config.recurrence,
    ...(filters.length > 0 ? { filters } : {}),
  };
};

const toAttrs = (alert: StripeBillingAlert): AlertAttributes => ({
  id: alert.id,
  title: alert.title,
  alertType: alert.alert_type,
  status: alert.status ?? "active",
  usageThreshold: toUsageThreshold(alert.usage_threshold),
  livemode: alert.livemode,
});

const isMissingAlert = isMissingStripeResource;

const getById = (id: string) =>
  GetBillingAlert({ id }).pipe(Effect.catchIf(isMissingAlert, () => Effect.undefined));

const listAlerts = Effect.fn(function* () {
  const alerts: StripeBillingAlert[] = [];
  let startingAfter: string | undefined;
  for (let page = 0; page < LIST_MAX_PAGES; page++) {
    const response = yield* GetBillingAlerts({
      limit: LIST_PAGE_SIZE,
      ...(startingAfter !== undefined ? { starting_after: startingAfter } : {}),
    });
    alerts.push(...response.data);
    if (!response.has_more || response.data.length === 0) {
      break;
    }
    startingAfter = response.data[response.data.length - 1]?.id;
    if (startingAfter === undefined) {
      break;
    }
  }
  return alerts;
});

const findByTitle = Effect.fn(function* (title: string) {
  const alerts = yield* listAlerts();
  return alerts.find((alert) => alert.title === title);
});

const isArchived = (alert: StripeBillingAlert): boolean => alert.status === "archived";

const observe = Effect.fn(function* (input: { id?: string; title?: string }) {
  if (input.id !== undefined) {
    const byId = yield* getById(input.id);
    if (byId !== undefined && !isArchived(byId)) return byId;
  }
  if (input.title !== undefined) {
    return yield* findByTitle(input.title);
  }
  return undefined;
});

const filtersEqual = (
  a: AlertUsageThresholdFilter[] | undefined,
  b: AlertUsageThresholdFilter[] | undefined,
): boolean => {
  const left = a ?? [];
  const right = b ?? [];
  if (left.length !== right.length) return false;
  for (let i = 0; i < left.length; i++) {
    const other = right[i];
    if (
      other === undefined ||
      left[i]?.type !== other.type ||
      left[i]?.customer !== other.customer
    ) {
      return false;
    }
  }
  return true;
};

const shouldReplace = (news: AlertProps, output: AlertAttributes | undefined): boolean => {
  if (output === undefined) return false;
  if (news.title !== undefined && news.title !== output.title) return true;
  if (news.alertType !== undefined && news.alertType !== output.alertType) {
    return true;
  }
  const current = output.usageThreshold;
  if (current === undefined) return true;
  if (news.usageThreshold.gte !== current.gte) return true;
  if (news.usageThreshold.meter !== current.meter) return true;
  const desiredRecurrence = news.usageThreshold.recurrence ?? "one_time";
  if (desiredRecurrence !== current.recurrence) return true;
  if (
    news.usageThreshold.filters !== undefined &&
    !filtersEqual(news.usageThreshold.filters, current.filters)
  ) {
    return true;
  }
  return false;
};

const toCreateUsageThreshold = (threshold: AlertUsageThreshold) => ({
  gte: threshold.gte,
  meter: threshold.meter,
  recurrence: threshold.recurrence ?? "one_time",
  ...(threshold.filters !== undefined
    ? {
        filters: threshold.filters.map((filter) => ({
          type: filter.type,
          ...(filter.customer !== undefined ? { customer: filter.customer } : {}),
        })),
      }
    : {}),
});

export const AlertProvider = () =>
  Provider.succeed(Alert, {
    stables: ["id", "title", "alertType", "usageThreshold", "livemode"],

    diff: Effect.fn(function* ({ news, output }) {
      if (!isResolved(news)) return undefined;
      if (shouldReplace(news, output)) {
        return { action: "replace" } as const;
      }
      return undefined;
    }),

    read: Effect.fn(function* ({ output }) {
      const existing = yield* observe({
        id: output?.id,
        title: output?.title,
      });
      if (existing === undefined) return undefined;
      // Billing alerts have no metadata. Identity is the Stripe id and
      // title; a match is treated as owned.
      return toAttrs(existing);
    }),

    list: Effect.fn(function* () {
      // No metadata on this resource. The list API returns active and
      // inactive alerts; archived rows stay in Stripe but leave the list
      // and must not re-enter nuke.
      const alerts = yield* listAlerts();
      return alerts.map(toAttrs);
    }),

    reconcile: Effect.fn(function* ({ id, news, output, instanceId }) {
      const title = yield* toTitle(id, news.title, output?.title);
      const alertType = news.alertType ?? "usage_threshold";
      const desiredStatus = news.status ?? "active";

      let current = yield* observe({
        id: output?.id,
        title,
      });
      if (current !== undefined && shouldReplace(news, toAttrs(current))) {
        current = undefined;
      }

      if (current === undefined) {
        current = yield* CreateBillingAlert({
          alert_type: alertType,
          title,
          usage_threshold: toCreateUsageThreshold(news.usageThreshold),
        }).pipe(
          withRequestOptions({
            idempotencyKey: `alchemy-billing-alert-${instanceId}`,
          }),
        );
      }

      if (current === undefined) {
        return yield* new AlertNotResolved({ title });
      }

      const currentStatus = current.status ?? "active";
      if (currentStatus !== desiredStatus) {
        current =
          desiredStatus === "inactive"
            ? yield* CreateBillingAlertDeactivate({ id: current.id })
            : yield* CreateBillingAlertActivate({ id: current.id });
      }

      return toAttrs(current);
    }),

    delete: Effect.fn(function* ({ output }) {
      const existing = yield* getById(output.id);
      if (existing === undefined || existing.status === "archived") return;
      yield* CreateBillingAlertArchive({ id: existing.id }).pipe(
        Effect.catchIf(isMissingAlert, () => Effect.void),
      );
    }),
  });