sailfork / t3code-github / .repos/ alchemy-effect/ packages/ cloudflare/ src/ AI/ CustomTopics.ts

import * as aiSecurity from "@distilled.cloud/cloudflare/ai-security";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import * as Effect from "effect/Effect";
import * as Predicate from "effect/Predicate";
import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
import type { Providers } from "../Providers.ts";
import { listAllZones } from "../Zone/lookup.ts";

const TypeId = "Cloudflare.AI.Security.CustomTopics" as const;
type TypeId = typeof TypeId;

/**
 * A custom topic category for AI Security for Apps content detection.
 */
export type Topic = {
  /**
   * Human-readable label for the topic category.
   */
  label: string;
  /**
   * The topic description used to classify AI (LLM) traffic content.
   */
  topic: string;
};

export type CustomTopicsProps = {
  /**
   * Zone the custom topics belong to. Stable — changing the zone
   * triggers a replacement (the old zone's topic list is restored to
   * the value it had before Alchemy managed it).
   */
  zoneId: string;
  /**
   * The full list of custom topic categories. Mutable — the PUT
   * replaces the entire list, so reconcile syncs the list as a whole.
   */
  topics: Topic[];
};

export type CustomTopicsAttributes = {
  /** Zone the custom topics belong to. */
  zoneId: string;
  /** The custom topic categories currently configured on the zone. */
  topics: Topic[];
  /**
   * The topic list the zone had before Alchemy first managed it.
   * Restored on destroy, so deleting the resource puts the zone back
   * the way it was found.
   */
  initialTopics: Topic[];
};

export type CustomTopics = Resource<
  TypeId,
  CustomTopicsProps,
  CustomTopicsAttributes,
  never,
  Providers
>;

/**
 * Custom topic categories for AI Security for Apps (Firewall for AI)
 * content detection on a Cloudflare zone
 * (`/zones/{zone_id}/ai-security/custom-topics`).
 *
 * The topic list is a zone singleton — it always exists (defaulting to
 * empty) and is never created or deleted, only replaced wholesale via
 * PUT. Reconcile PUTs the desired list when the observed list differs;
 * destroy restores the list the zone had before Alchemy first managed it.
 *
 * Declare at most one `CustomTopics` per zone — two instances
 * managing the same zone would fight over the single underlying list.
 *
 * AI Security for Apps is entitlement-gated: on accounts without the
 * feature every call fails with the typed `AiSecurityNotEntitled` error
 * (Cloudflare error code 13101).
 * ### Managing custom topics
 * **Example:** Classify traffic into two custom topics
 * ```typescript
 * const topics = yield* Cloudflare.AI.CustomTopics("Topics", {
 *   zoneId: zone.zoneId,
 *   topics: [
 *     { label: "billing", topic: "Questions about invoices and payments" },
 *     { label: "abuse", topic: "Harassment or abusive language" },
 *   ],
 * });
 * ```
 *
 * **Example:** Clear all custom topics
 * ```typescript
 * yield* Cloudflare.AI.CustomTopics("Topics", {
 *   zoneId: zone.zoneId,
 *   topics: [],
 * });
 * ```
 *
 * @see https://developers.cloudflare.com/waf/detections/firewall-for-ai/
 *
 * @resource
 * @product AI Security
 * @category Application Security
 */
export const CustomTopics = Resource<CustomTopics>(TypeId, {
  aliases: ["Cloudflare.AiSecurity.CustomTopics"],
});

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

export const CustomTopicsProvider = () =>
  Provider.succeed(CustomTopics, {
    stables: ["zoneId", "initialTopics"],

    list: Effect.fn(function* () {
      const { accountId } = yield* yield* CloudflareEnvironment;
      // No account-wide API for this zone singleton — enumerate every
      // zone in the account and read its custom-topics list (the list
      // always exists, defaulting to empty, on every entitled zone).
      const allZones = yield* listAllZones(accountId);
      const rows = yield* Effect.forEach(
        allZones.map((zone) => zone.id),
        (zoneId) =>
          aiSecurity.getCustomTopic({ zoneId }).pipe(
            Effect.map((observed) => {
              const topics = normalizeTopics(observed.topics);
              return {
                zoneId,
                topics,
                // A freshly listed item adopts its observed list as the
                // pre-management baseline, mirroring a cold `read`.
                initialTopics: topics,
              };
            }),
            // AI Security is entitlement-gated and zones may be partial
            // or deleted out-of-band — skip any zone we can't read.
            Effect.catchTag(
              ["AiSecurityNotEntitled", "ZoneNotAuthorized", "Forbidden"],
              () => Effect.undefined,
            ),
          ),
        { concurrency: 10 },
      );
      return rows.filter((row): row is CustomTopicsAttributes => row !== undefined);
    }),

    diff: Effect.fn(function* ({ olds = {}, news, output }) {
      const o = olds as CustomTopicsProps;
      const n = news as CustomTopicsProps;
      // zoneId is Input<string>; compare only once both sides are concrete.
      const oldZoneId = output?.zoneId ?? (typeof o.zoneId === "string" ? o.zoneId : undefined);
      if (oldZoneId !== undefined && typeof n.zoneId === "string" && oldZoneId !== n.zoneId) {
        return { action: "replace" } as const;
      }
      return undefined;
    }),

    read: Effect.fn(function* ({ output, olds }) {
      const zoneId = output?.zoneId ?? (olds?.zoneId as string | undefined);
      if (!zoneId) return undefined;
      const observed = yield* aiSecurity.getCustomTopic({ zoneId }).pipe(
        // Zone deleted out-of-band — the singleton is gone with it.
        Effect.catchTag("ZoneNotAuthorized", () => Effect.undefined),
      );
      if (observed === undefined) return undefined;
      // The list is a singleton that always exists (default empty) —
      // there is nothing to "own", so a cold read adopts freely (never
      // `Unowned`). The observed list at adoption time becomes the
      // `initialTopics` restored on destroy.
      const topics = normalizeTopics(observed.topics);
      const initialTopics = output !== undefined ? output.initialTopics : topics;
      return { zoneId, topics, initialTopics };
    }),

    reconcile: Effect.fn(function* ({ news, output }) {
      // Inputs have been resolved to concrete strings by Plan.
      const zoneId = news.zoneId as string;
      const desired = news.topics;

      // 1. Observe — the singleton always exists; read the live list.
      const observed = yield* aiSecurity.getCustomTopic({ zoneId });
      const observedTopics = normalizeTopics(observed.topics);

      // 2. Capture — the pre-management list, restored on destroy.
      //    `output` (including an adoption read) already carries it;
      //    otherwise this is our first touch and the observed list is
      //    the zone's original.
      const initialTopics = output !== undefined ? output.initialTopics : observedTopics;

      // 3. Sync — PUT the full desired list only when it differs.
      if (topicsEqual(observedTopics, desired)) {
        return { zoneId, topics: observedTopics, initialTopics };
      }
      const updated = yield* aiSecurity.putCustomTopic({
        zoneId,
        topics: desired,
      });
      return {
        zoneId,
        topics: normalizeTopics(updated.topics ?? desired),
        initialTopics,
      };
    }),

    delete: Effect.fn(function* ({ output }) {
      const { zoneId, initialTopics } = output;
      // Observe — if the zone itself is gone, so is the list; if the
      // entitlement was revoked, the list is unreachable and there is
      // nothing we can restore.
      const observed = yield* aiSecurity.getCustomTopic({ zoneId }).pipe(
        Effect.catchTags({
          ZoneNotAuthorized: () => Effect.undefined,
          AiSecurityNotEntitled: () => Effect.undefined,
        }),
      );
      if (observed === undefined) return;
      // Restore the pre-management list; skip the call when it already
      // matches (idempotent re-delete after a crashed run).
      if (topicsEqual(normalizeTopics(observed.topics), initialTopics)) return;
      yield* aiSecurity
        .putCustomTopic({ zoneId, topics: initialTopics })
        .pipe(Effect.catchTag("ZoneNotAuthorized", () => Effect.void));
    }),
  });

/**
 * Normalize the API's `topics ?? null` into a concrete (mutable) array.
 */
const normalizeTopics = (topics: readonly Topic[] | null | undefined): Topic[] =>
  (topics ?? []).map((t) => ({ ...t }));

/**
 * Order-insensitive structural equality on the `topic` key — the PUT
 * replaces the whole list, so two lists are equal when they contain the
 * same `{ label, topic }` pairs regardless of order.
 */
const topicsEqual = (a: readonly Topic[], b: readonly Topic[]): boolean => {
  if (a.length !== b.length) return false;
  const key = (t: Topic) => `${t.topic}${t.label}`;
  const as = a.map(key).sort();
  const bs = b.map(key).sort();
  return as.every((k, i) => k === bs[i]);
};