sailfork / t3code-github / .repos/ alchemy-effect/ packages/ cloudflare/ src/ Zaraz/ Config.ts

import * as zaraz from "@distilled.cloud/cloudflare/zaraz";
import { deepEqual, isResolved } from "alchemy/Diff";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import { stripNullFields, stripUndefinedFields, unwrapRedacted } from "alchemy/Util/data";
import * as Effect from "effect/Effect";
import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
import type { Providers } from "../Providers.ts";
import { resolveZoneId, type Reference } from "../Zone/index.ts";
import { listAllZones } from "../Zone/lookup.ts";
import { defineZarazEvents } from "./ZarazEventTypes.ts";

export type Workflow = zaraz.GetWorkflowResponse;
export type Settings = zaraz.PutConfigRequest["settings"];
export type Analytics = NonNullable<zaraz.PutConfigRequest["analytics"]>;
export type Consent = NonNullable<zaraz.PutConfigRequest["consent"]>;

export type ConfigProps = {
  /**
   * Zone whose Zaraz config should be managed. Accepts a zone id, a zone name
   * (`example.com`), or a `{ zoneId, name? }` object.
   */
  zone: Reference;
  /**
   * Data layer compatibility mode.
   */
  dataLayer?: boolean;
  /**
   * Key used for Zaraz debug mode. Defaults to the current zone config value.
   */
  debugKey?: string;
  /**
   * Zaraz settings to merge into the current zone config.
   */
  settings?: Partial<Settings>;
  /**
   * Zaraz tools keyed by tool id. When omitted, existing tools are retained.
   */
  tools?: Record<string, unknown>;
  /**
   * Zaraz triggers keyed by trigger id. When omitted, existing triggers are
   * retained.
   */
  triggers?: Record<string, unknown>;
  /**
   * Zaraz variables keyed by variable id. When omitted, existing variables are
   * retained. Secret variable values are not returned by Cloudflare reads.
   */
  variables?: Record<string, unknown>;
  /**
   * Cloudflare Monitoring settings.
   */
  analytics?: Analytics;
  /**
   * Zaraz consent management configuration.
   */
  consent?: Consent;
  /**
   * Single Page Application support.
   */
  historyChange?: boolean;
  /**
   * Zaraz workflow mode. When omitted, the current workflow is retained.
   */
  workflow?: Workflow;
  /**
   * Whether destroy should restore Cloudflare's default Zaraz config.
   *
   * By default, destroy only removes this resource from Alchemy state and keeps
   * the current zone-level Zaraz config intact.
   * If `workflow` is set, `delete: true` restores the workflow to real-time
   * mode, Cloudflare's default.
   * @default false
   */
  delete?: boolean;
};

export type Config = Resource<
  "Cloudflare.Zaraz.Config",
  ConfigProps,
  ConfigAttributes,
  never,
  Providers
>;

export type ConfigAttributes = {
  /**
   * Cloudflare zone id.
   */
  zoneId: string;
  /**
   * Data layer compatibility mode.
   */
  dataLayer: boolean;
  /**
   * Key used for Zaraz debug mode.
   */
  debugKey: string;
  /**
   * General Zaraz settings.
   */
  settings: zaraz.GetConfigResponse["settings"];
  /**
   * Zaraz tools keyed by tool id.
   */
  tools: Record<string, unknown>;
  /**
   * Zaraz triggers keyed by trigger id.
   */
  triggers: Record<string, unknown>;
  /**
   * Zaraz variables keyed by variable id.
   */
  variables: Record<string, unknown>;
  /**
   * Zaraz internal version of the config.
   */
  zarazVersion: number;
  /**
   * Cloudflare Monitoring settings.
   */
  analytics?: zaraz.GetConfigResponse["analytics"];
  /**
   * Consent management configuration.
   */
  consent?: zaraz.GetConfigResponse["consent"];
  /**
   * Single Page Application support.
   */
  historyChange?: boolean | null;
  /**
   * Current Zaraz workflow mode.
   */
  workflow: Workflow;
};

/**
 * A Cloudflare Zaraz zone configuration.
 *
 * Cloudflare Zaraz is an edge-managed third-party tool manager and analytics
 * event pipeline. See the
 * {@link https://developers.cloudflare.com/zaraz/ | Cloudflare Zaraz docs} and
 * {@link https://developers.cloudflare.com/zaraz/web-api/ | Web API docs}.
 *
 * Zaraz is a zone-level singleton. This resource reconciles the current zone
 * config and workflow to the desired values while retaining existing settings
 * for fields omitted from props.
 *
 * Destroy keeps the current Zaraz config by default to avoid wiping unrelated
 * zone-level analytics setup. Set `delete: true` to restore Cloudflare's
 * default Zaraz config on destroy.
 * ### Managing Zaraz
 * **Example:** Enable data layer compatibility
 * ```typescript
 * const zaraz = yield* Cloudflare.Zaraz.Config("Analytics", {
 *   zone: "example.com",
 *   dataLayer: true,
 * });
 * ```
 *
 * **Example:** Update Zaraz settings
 * ```typescript
 * const zaraz = yield* Cloudflare.Zaraz.Config("Analytics", {
 *   zone: "example.com",
 *   settings: {
 *     autoInjectScript: true,
 *     hideIPAddress: true,
 *   },
 * });
 * ```
 *
 * **Example:** Enable preview workflow
 * ```typescript
 * const zaraz = yield* Cloudflare.Zaraz.Config("Analytics", {
 *   zone: "example.com",
 *   workflow: "preview",
 * });
 * ```
 *
 * @resource
 * @product Zaraz
 * @category Performance & Reliability
 */
export const Config = Object.assign(
  Resource<Config>("Cloudflare.Zaraz.Config", {
    aliases: ["Cloudflare.ZarazConfig"],
  }),
  {
    /**
     * Define a type-only contract for the events sent through this Zaraz config.
     *
     * The returned value carries only types. Browser code should use
     * Cloudflare's injected `window.zaraz` API at runtime.
     */
    events: defineZarazEvents,
  },
);

export const ConfigProvider = () =>
  Provider.succeed(Config, {
    nuke: { singleton: true },
    stables: ["zoneId"],
    list: Effect.fn(function* () {
      const { accountId } = yield* yield* CloudflareEnvironment;
      // Zaraz config is a zone-level singleton with no account-wide list
      // API — enumerate every zone and read its config (one per zone).
      const allZones = yield* listAllZones(accountId);
      const rows = yield* Effect.forEach(
        allZones.map((zone) => zone.id),
        (zoneId) =>
          observe(zoneId).pipe(
            // Best-effort account-wide fan-out: a zone where Zaraz isn't
            // provisioned (rejects the route) or that the token can't read
            // (missing permission / code-10000 auth blip surfaced as
            // Unauthorized, or a 403/404) must be skipped, not fail the whole
            // enumeration.
            Effect.catchTag(
              ["InvalidRoute", "Unauthorized", "Forbidden", "NotFound"],
              () => Effect.undefined,
            ),
          ),
        { concurrency: 10 },
      );
      return rows.filter((row): row is Config["Attributes"] => row !== undefined);
    }),
    diff: Effect.fn(function* ({ olds, news, output }) {
      if (!output) return undefined;
      if (!isResolved(news)) return undefined;

      const zoneId = yield* resolve(news.zone);
      if (zoneId !== output.zoneId) {
        return { action: "replace" } as const;
      }

      const outputConfig = fromAttributes(output);
      const comparableOutput = configForCompare(outputConfig, olds, news);
      const desired = desiredConfig(outputConfig, news);
      const desiredWorkflow = news.workflow ?? output.workflow;
      if (
        desiredWorkflow !== output.workflow ||
        !deepEqual(comparableConfig(comparableOutput), comparableConfig(desired))
      ) {
        return { action: "update" } as const;
      }
    }),
    read: Effect.fn(function* ({ olds, output }) {
      const zoneId =
        // `olds.zone` may be `undefined` when a `creating` row was persisted
        // before upstream Outputs resolved — report "not found" then.
        output?.zoneId ?? (olds?.zone !== undefined ? yield* resolve(olds.zone) : undefined);
      if (!zoneId) return undefined;
      return yield* observe(zoneId);
    }),
    reconcile: Effect.fn(function* ({ news, output }) {
      const zoneId = output?.zoneId ?? (yield* resolve(news.zone));
      const observed = yield* observe(zoneId);
      const observedConfig = fromAttributes(observed);
      const desired = desiredConfig(observedConfig, news);
      const desiredWorkflow = news.workflow ?? observed.workflow;

      const updatedConfig = deepEqual(comparableConfig(observedConfig), comparableConfig(desired))
        ? observedConfig
        : yield* zaraz.putConfig(toPutConfig(zoneId, desired));
      const updatedWorkflow =
        desiredWorkflow === observed.workflow
          ? observed.workflow
          : yield* zaraz.putZaraz({
              zoneId,
              workflow: desiredWorkflow,
            });

      return toAttributes(zoneId, updatedConfig, updatedWorkflow);
    }),
    delete: Effect.fn(function* ({ output, olds }) {
      if (olds.delete !== true) return;
      // Restore real-time first: in `preview` mode a config PUT is staged
      // rather than published, so resetting the config before switching the
      // workflow back would leave the published config untouched.
      if (olds.workflow !== undefined) {
        yield* zaraz.putZaraz({
          zoneId: output.zoneId,
          workflow: "realtime",
        });
      }
      const defaults = yield* zaraz.getDefault({ zoneId: output.zoneId });
      yield* zaraz.putConfig(toPutConfig(output.zoneId, defaults));
    }),
  });

const resolve = Effect.fn(function* (zone: Reference) {
  const { accountId } = yield* yield* CloudflareEnvironment;
  return yield* resolveZoneId({
    accountId,
    zone,
    hostname: typeof zone === "string" ? zone : (zone.name ?? ""),
  });
});

const observe = (zoneId: string) =>
  Effect.all({
    config: zaraz.getConfig({ zoneId }),
    workflow: zaraz.getWorkflow({ zoneId }),
  }).pipe(Effect.map(({ config, workflow }) => toAttributes(zoneId, config, workflow)));

type ConfigResponse = zaraz.GetConfigResponse | zaraz.PutConfigResponse | zaraz.GetDefaultResponse;

const toAttributes = (
  zoneId: string,
  config: ConfigResponse,
  workflow: Workflow,
): Config["Attributes"] => ({
  zoneId,
  dataLayer: config.dataLayer,
  debugKey: config.debugKey,
  settings: config.settings,
  tools: config.tools,
  triggers: config.triggers,
  variables: config.variables,
  zarazVersion: config.zarazVersion,
  analytics: config.analytics,
  consent: config.consent,
  historyChange: config.historyChange,
  workflow,
});

const fromAttributes = (attrs: ConfigAttributes): ConfigResponse => ({
  dataLayer: attrs.dataLayer,
  debugKey: attrs.debugKey,
  settings: attrs.settings,
  tools: attrs.tools,
  triggers: attrs.triggers,
  variables: attrs.variables,
  zarazVersion: attrs.zarazVersion,
  analytics: attrs.analytics,
  consent: attrs.consent,
  historyChange: attrs.historyChange,
});

const desiredConfig = (observed: ConfigResponse, props: ConfigProps): ConfigResponse => ({
  dataLayer: props.dataLayer ?? observed.dataLayer,
  debugKey: props.debugKey ?? observed.debugKey,
  settings: {
    ...stripNullFields(observed.settings),
    ...props.settings,
  },
  tools: props.tools ?? observed.tools,
  triggers: props.triggers ?? observed.triggers,
  variables: props.variables ?? observed.variables,
  zarazVersion: observed.zarazVersion,
  analytics:
    props.analytics ?? (observed.analytics ? stripNullFields(observed.analytics) : undefined),
  consent: props.consent ?? (observed.consent ? stripNullFields(observed.consent) : undefined),
  historyChange: props.historyChange ?? observed.historyChange,
});

const toPutConfig = (zoneId: string, config: ConfigResponse): zaraz.PutConfigRequest =>
  stripUndefinedFields({
    zoneId,
    dataLayer: config.dataLayer,
    debugKey: config.debugKey,
    settings: stripNullFields(config.settings) as Settings,
    tools: unwrapRedacted(config.tools) as Record<string, unknown>,
    triggers: unwrapRedacted(config.triggers) as Record<string, unknown>,
    variables: unwrapRedacted(config.variables) as Record<string, unknown>,
    zarazVersion: config.zarazVersion,
    analytics: config.analytics ? (stripNullFields(config.analytics) as Analytics) : undefined,
    consent: config.consent ? (stripNullFields(config.consent) as Consent) : undefined,
    historyChange: config.historyChange ?? undefined,
  }) as zaraz.PutConfigRequest;

const comparableConfig = (config: ConfigResponse) => {
  const { zoneId: _, ...request } = toPutConfig("", config);
  return request;
};

const configForCompare = (
  observed: ConfigResponse,
  oldProps: ConfigProps | undefined,
  props: ConfigProps,
): ConfigResponse => {
  if (
    props.variables === undefined ||
    oldProps?.variables === undefined ||
    !deepEqual(oldProps.variables, props.variables)
  ) {
    return observed;
  }

  // If props already requested these variables in the previous state, compare
  // against props instead of Cloudflare's readback because secret variable
  // values are intentionally write-only in the Zaraz API.
  return {
    ...observed,
    variables: props.variables,
  };
};