sailfork / t3code-github / .repos/ alchemy-effect/ packages/ cloudflare/ src/ Alerting/ NotificationPolicy.ts

import * as alerting from "@distilled.cloud/cloudflare/alerting";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as Predicate from "effect/Predicate";
import * as Stream from "effect/Stream";
import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
import type { Providers } from "../Providers.ts";
import {
  createPolicyName,
  findPolicyByName,
  narrowPolicy,
  type ObservedPolicy,
  boundMechanisms,
  type NotificationPolicyBinding,
  observePolicy,
  type PolicyBody,
  policyEqualsObserved,
} from "./internal.ts";

export class NotificationPolicyUnexpectedResponse extends Data.TaggedError(
  "NotificationPolicyUnexpectedResponse",
)<{
  readonly message: string;
  readonly cause?: unknown;
}> {}

export type { NotificationPolicyBinding } from "./internal.ts";

const TypeId = "Cloudflare.Alerting.NotificationPolicy" as const;
type TypeId = typeof TypeId;

/**
 * The event that triggers a notification dispatch. The full catalog (and
 * which types your plan can use) is returned by the available-alerts
 * endpoint. The union is kept open so new Cloudflare alert types aren't
 * blocked by stale types.
 */
export type AlertType = alerting.CreatePolicyRequest["alertType"];

/**
 * Optional filters restricting which events trigger the policy. Which keys
 * are valid (or required — Cloudflare returns `FiltersRequired`) depends on
 * the alert type.
 */
export type NotificationPolicyFilters = alerting.CreatePolicyRequest["filters"];

/**
 * Destinations notified when the policy fires. At least one mechanism is
 * required (Cloudflare returns `MechanismRequired` otherwise). Email ids
 * are email addresses; webhook/pagerduty ids reference destination UUIDs.
 */
export interface NotificationPolicyMechanisms {
  /** Email destinations — `id` is the recipient email address. */
  email?: ReadonlyArray<{ id: string }>;
  /** Webhook destinations — `id` references a {@link NotificationWebhook}. */
  webhooks?: ReadonlyArray<{ id: string }>;
  /** PagerDuty destinations — `id` references a connected PagerDuty service. */
  pagerduty?: ReadonlyArray<{ id: string }>;
}

export interface NotificationPolicyProps {
  /**
   * Name of the policy. If omitted, a unique name is generated.
   * Mutable — renames are applied in place.
   * @default ${app}-${id}-${stage}-${suffix}
   */
  name?: string;
  /**
   * The event that triggers a notification dispatch (e.g.
   * `universal_ssl_event_type`, `billing_usage_alert`). Changing the alert
   * type triggers a replacement: the valid filter set depends on the alert
   * type, so a policy alerting on a different event is a different policy.
   */
  alertType: AlertType;
  /**
   * Whether the policy is enabled.
   * @default true
   */
  enabled?: boolean;
  /**
   * Optional human-readable description of the policy.
   */
  description?: string;
  /**
   * How often to re-alert from the same incident (e.g. `"30m"`). Not
   * supported by all alert types.
   */
  alertInterval?: string;
  /**
   * Destinations notified when the policy fires. At least one destination is
   * required, either declared here or bound by a runtime that consumes the
   * policy's notifications (`Cloudflare.Alerting.consumeNotifications`).
   */
  mechanisms?: NotificationPolicyMechanisms;
  /**
   * Optional filters restricting which events trigger the policy. Some
   * alert types require specific filters (`FiltersRequired`).
   */
  filters?: NotificationPolicyFilters;
}

export interface NotificationPolicyAttributes {
  /** Cloudflare-assigned notification policy UUID. */
  policyId: string;
  /** Account that owns this policy. */
  accountId: string;
  /** Name of the policy. */
  name: string;
  /** The alert type the policy fires on. */
  alertType: AlertType;
  /** Whether the policy is enabled. */
  enabled: boolean;
  /** ISO8601 creation timestamp. */
  created: string | undefined;
  /** ISO8601 last-modified timestamp. */
  modified: string | undefined;
}

export type NotificationPolicy = Resource<
  TypeId,
  NotificationPolicyProps,
  NotificationPolicyAttributes,
  NotificationPolicyBinding,
  Providers
>;

/**
 * A Cloudflare Notifications policy.
 *
 * A notification policy connects an alert type (the event Cloudflare
 * watches for) to one or more destinations — email addresses, webhook
 * destinations, or PagerDuty services — optionally narrowed by filters.
 * ### Creating a policy
 * **Example:** Email notifications for Universal SSL events
 * ```typescript
 * yield* Cloudflare.Alerting.NotificationPolicy("SslAlerts", {
 *   alertType: "universal_ssl_event_type",
 *   mechanisms: { email: [{ id: "ops@example.com" }] },
 * });
 * ```
 *
 * **Example:** Disabled policy with a description
 * ```typescript
 * yield* Cloudflare.Alerting.NotificationPolicy("SslAlerts", {
 *   alertType: "universal_ssl_event_type",
 *   enabled: false,
 *   description: "Paused during migration",
 *   mechanisms: { email: [{ id: "ops@example.com" }] },
 * });
 * ```
 *
 * ### Webhook destinations
 * **Example:** Dispatch to a webhook destination
 * ```typescript
 * const webhook = yield* Cloudflare.Alerting.NotificationWebhook("AlertsHook", {
 *   url: "https://alerts.example.com/cf",
 * });
 *
 * yield* Cloudflare.Alerting.NotificationPolicy("SslAlerts", {
 *   alertType: "universal_ssl_event_type",
 *   mechanisms: { webhooks: [{ id: webhook.webhookId }] },
 * });
 * ```
 *
 * ### Filters
 * **Example:** Health check alerts for specific zones
 * ```typescript
 * yield* Cloudflare.Alerting.NotificationPolicy("HealthAlerts", {
 *   alertType: "health_check_status_notification",
 *   mechanisms: { email: [{ id: "ops@example.com" }] },
 *   filters: {
 *     healthCheckId: [healthCheckId],
 *     newHealth: ["Unhealthy"],
 *   },
 * });
 * ```
 *
 * ### Handling notifications in code
 * **Example:** Run an Effect for each notification
 * `consumeNotifications` adds a webhook destination at the consuming
 * runtime, so the policy needs no `mechanisms`.
 * ```typescript
 * const policy = yield* Cloudflare.Alerting.NotificationPolicy("SslAlerts", {
 *   alertType: "universal_ssl_event_type",
 * });
 *
 * // in a Worker's Construction phase, with NotificationEventSourceLive provided
 * yield* Cloudflare.Alerting.consumeNotifications(policy, (notification) =>
 *   Effect.log(notification.text),
 * );
 * ```
 *
 * ### SQL custom alerts <!-- api-prose -->
 * Alerts on a SQL query (Cloudflare's `custom_analytics` alert type) have
 * their own resource with typed triggers: `Cloudflare.Alerting.CustomAlert`.
 *
 * ### Workers Issues notifications
 * **Example:** Notify on new Worker issues
 * ```typescript
 * const policy = yield* Cloudflare.Alerting.NotificationPolicy("IssuePolicy", {
 *   alertType: "workers_observability_real_time_issue",
 *   mechanisms: { email: [{ id: "ops@example.com" }] },
 * });
 *
 * yield* Cloudflare.Workers.IssueAutomation("IssueAlerts", {
 *   policyId: policy.policyId,
 *   afterOccurrences: 5,
 * });
 * ```
 *
 * @see https://developers.cloudflare.com/notifications/
 *
 * @resource
 * @product Alerting
 * @category Observability & Analytics
 */
export const NotificationPolicy = Resource<NotificationPolicy>(TypeId);

/**
 * Returns true if the given value is a NotificationPolicy resource.
 */
export const isNotificationPolicy = (value: unknown): value is NotificationPolicy =>
  Predicate.hasProperty(value, "Type") && value.Type === TypeId;

export const NotificationPolicyProvider = () =>
  Provider.succeed(NotificationPolicy, {
    stables: ["policyId", "accountId", "alertType"],

    // Account-scoped collection: exhaustively paginate the account's
    // notification policies and hydrate each into the `read` attribute shape.
    list: Effect.fn(function* () {
      const { accountId } = yield* yield* CloudflareEnvironment;
      return yield* alerting.listPolicies.pages({ accountId }).pipe(
        Stream.runCollect,
        Effect.map((chunk) =>
          Array.from(chunk).flatMap((page) =>
            (page.result ?? [])
              .map(narrowPolicy)
              .filter((p): p is ObservedPolicy => p !== undefined)
              .map((p) => toPolicyAttributes(p, accountId)),
          ),
        ),
      );
    }),

    diff: Effect.fn(function* ({ olds = {}, news, output }) {
      const { accountId } = yield* yield* CloudflareEnvironment;
      if ((output?.accountId ?? accountId) !== accountId) {
        return { action: "replace" } as const;
      }
      // The valid filter/mechanism shape depends on the alert type — a
      // policy alerting on a different event is a different policy.
      // `alertType` is a plain string prop, statically knowable here.
      const o = olds as NotificationPolicyProps;
      const n = news as NotificationPolicyProps;
      const oldAlertType = output?.alertType ?? o.alertType;
      if (oldAlertType !== undefined && oldAlertType !== n.alertType) {
        return { action: "replace" } as const;
      }
    }),

    read: Effect.fn(function* ({ id, output, olds }) {
      const { accountId } = yield* yield* CloudflareEnvironment;
      const acct = output?.accountId ?? accountId;

      // Owned path: refresh by the persisted policy id.
      if (output?.policyId) {
        const observed = yield* observePolicy(acct, output.policyId);
        if (observed) return toPolicyAttributes(observed, acct);
        return undefined;
      }

      // Cold read: no persisted id (state-persistence failure) — find the
      // deterministic physical name in the account's policy list.
      const name = yield* createPolicyName(id, olds?.name);
      const match = yield* findPolicyByName(acct, name);
      if (match) return toPolicyAttributes(match, acct);
      return undefined;
    }),

    reconcile: Effect.fn(function* ({ id, news, output, bindings }) {
      const { accountId } = yield* yield* CloudflareEnvironment;
      const name = yield* createPolicyName(id, news.name);
      const desired = buildPolicyBody(name, news, bindings);

      // 1. Observe — by cached id first, then by deterministic name.
      let observed: ObservedPolicy | undefined;
      if (output?.policyId) {
        observed = yield* observePolicy(accountId, output.policyId);
      }
      if (!observed) {
        observed = yield* findPolicyByName(accountId, name);
      }

      // 2. Ensure — create when missing. `createPolicy` only returns the
      //    new id; re-read for the full attribute set.
      if (!observed) {
        const created = yield* alerting.createPolicy({
          accountId,
          ...desired,
        });
        if (!created.id) {
          return yield* new NotificationPolicyUnexpectedResponse({
            message: "Cloudflare did not return an id for the created notification policy",
          });
        }
        const fresh = yield* observePolicy(accountId, created.id);
        return toPolicyAttributes(fresh ?? { id: created.id }, accountId);
      }

      // 3. Sync — PUT the full desired body when any mutable aspect
      //    drifts from the observed cloud state.
      if (!policyEqualsObserved(desired, observed)) {
        yield* alerting.updatePolicy({
          accountId,
          policyId: observed.id,
          ...desired,
        });
        const fresh = yield* observePolicy(accountId, observed.id);
        return toPolicyAttributes(fresh ?? observed, accountId);
      }

      // 4. Return.
      return toPolicyAttributes(observed, accountId);
    }),

    delete: Effect.fn(function* ({ output }) {
      yield* alerting
        .deletePolicy({
          accountId: output.accountId,
          policyId: output.policyId,
        })
        .pipe(Effect.catchTag("PolicyNotFound", () => Effect.void));
    }),
  });

const toPolicyAttributes = (
  observed: ObservedPolicy,
  accountId: string,
): NotificationPolicyAttributes => ({
  policyId: observed.id,
  accountId,
  name: observed.name ?? "",
  alertType: (observed.alertType ?? "universal_ssl_event_type") as AlertType,
  enabled: observed.enabled ?? true,
  created: observed.created,
  modified: observed.modified,
});

const buildPolicyBody = (
  name: string,
  news: NotificationPolicyProps,
  bindings: ReadonlyArray<{ data: NotificationPolicyBinding }>,
): PolicyBody => ({
  name,
  alertType: news.alertType,
  enabled: news.enabled ?? true,
  description: news.description,
  alertInterval: news.alertInterval,
  // `Input<string>` ids are resolved to concrete strings by the engine
  // before reconcile runs; bound webhooks extend the declared ones.
  mechanisms: boundMechanisms(news.mechanisms, bindings),
  filters: news.filters,
});

/**
 * Compare the desired policy body against observed cloud state.
 * `mechanisms`/`filters` are compared structurally with `null`/`undefined`
 * dropped and object keys sorted, since Cloudflare echoes optional fields
 * as `null`.
 */