sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ FraudDetector/ DetectorVersion.ts

import * as frauddetector from "@distilled.cloud/aws/frauddetector";
import { deepEqual, isResolved } from "alchemy/Diff";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import { createInternalTags } from "alchemy/Tags";
import * as Effect from "effect/Effect";
import type { Providers } from "../Providers.ts";
import { syncFraudDetectorTags } from "./internal.ts";

/**
 * An inline rule definition owned by a detector version. Fraud Detector rules
 * are versioned resources scoped to a detector; a detector version references
 * a specific rule version. Declaring rules inline here lets the detector
 * version own their whole lifecycle.
 */
export interface RuleDefinition {
  /**
   * Identifier of the rule, unique within the detector (e.g. `high_risk`).
   */
  ruleId: string;
  /**
   * The rule expression, written in the rule language (see `language`). It
   * references variables and evaluates to a boolean, e.g.
   * `$order_price > 1000 and $email == "unknown"`.
   */
  expression: string;
  /**
   * Names of the outcomes returned when the rule matches. Must reference
   * existing Fraud Detector outcomes.
   */
  outcomes: string[];
  /**
   * The rule language. Only `DETECTORPL` is supported.
   * @default "DETECTORPL"
   */
  language?: string;
  /**
   * Human-readable description of the rule.
   */
  description?: string;
}

export interface DetectorVersionProps {
  /**
   * The identifier of the detector this version belongs to. Immutable —
   * changing it replaces the detector version.
   */
  detectorId: string;
  /**
   * Human-readable description of the version. Changing it replaces the
   * version (published versions are immutable).
   */
  description?: string;
  /**
   * The rules evaluated by this version, in priority order. Changing the set
   * of rules replaces the version.
   */
  rules: RuleDefinition[];
  /**
   * How rules are evaluated: `FIRST_MATCHED` stops at the first matching rule,
   * `ALL_MATCHED` evaluates every rule. Changing it replaces the version.
   * @default "FIRST_MATCHED"
   */
  ruleExecutionMode?: string;
  /**
   * The desired status of the version: `DRAFT`, `ACTIVE`, or `INACTIVE`. Only
   * an `ACTIVE` version serves predictions. This is an in-place update.
   * @default "ACTIVE"
   */
  status?: string;
  /**
   * User-defined tags for the detector version.
   */
  tags?: Record<string, string>;
}

export interface DetectorVersion extends Resource<
  "AWS.FraudDetector.DetectorVersion",
  DetectorVersionProps,
  {
    /** The identifier of the parent detector. */
    detectorId: string;
    /** The generated version identifier, e.g. `"1"`. */
    detectorVersionId: string;
    /** The ARN of the detector version. */
    arn: string;
    /** The version status: `DRAFT`, `ACTIVE`, or `INACTIVE`. */
    status: string;
  },
  never,
  Providers
> {}

/**
 * An Amazon Fraud Detector detector version — the deployable revision of a
 * detector. It bundles a set of rules (owned inline here) over the detector's
 * event type and, when `ACTIVE`, serves real-time predictions via
 * `getEventPrediction`. Rules and the version are cheap, rule-based
 * configuration objects — no model training is involved.
 *
 * ### Creating a Detector Version
 * **Example:** Active Version with One Rule
 * ```typescript
 * const version = yield* FraudDetector.DetectorVersion("v1", {
 *   detectorId: detector.detectorId,
 *   status: "ACTIVE",
 *   ruleExecutionMode: "FIRST_MATCHED",
 *   rules: [
 *     {
 *       ruleId: "high_risk",
 *       expression: '$email == "fraud@example.com"',
 *       outcomes: ["review"],
 *     },
 *   ],
 * });
 * ```
 *
 * @resource
 */
export const DetectorVersion = Resource<DetectorVersion>("AWS.FraudDetector.DetectorVersion");

export const DetectorVersionProvider = () =>
  Provider.effect(
    DetectorVersion,
    Effect.gen(function* () {
      /** Read a detector version by id; typed not-found → undefined. */
      const getVersion = Effect.fn(function* (detectorId: string, detectorVersionId: string) {
        return yield* frauddetector
          .getDetectorVersion({ detectorId, detectorVersionId })
          .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));
      });

      /**
       * Ensure every declared rule exists as a rule version and return the
       * references (create-once by `ruleId`; existing rules reuse their latest
       * version — rule-expression edits are expressed by changing `ruleId`).
       */
      const ensureRules = Effect.fn(function* (detectorId: string, rules: RuleDefinition[]) {
        const refs: frauddetector.Rule[] = [];
        for (const rule of rules) {
          const existing = yield* frauddetector
            .getRules({ detectorId, ruleId: rule.ruleId })
            .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));
          const details = existing?.ruleDetails ?? [];
          if (details.length === 0) {
            const created = yield* frauddetector.createRule({
              ruleId: rule.ruleId,
              detectorId,
              expression: rule.expression,
              language: rule.language ?? "DETECTORPL",
              outcomes: rule.outcomes,
              description: rule.description,
            });
            refs.push(created.rule!);
          } else {
            // Reuse the latest existing version of the rule.
            const latest = details.reduce((a, b) =>
              Number(b.ruleVersion ?? "0") > Number(a.ruleVersion ?? "0") ? b : a,
            );
            refs.push({
              detectorId,
              ruleId: latest.ruleId!,
              ruleVersion: latest.ruleVersion!,
            });
          }
        }
        return refs;
      });

      return {
        stables: ["detectorId", "detectorVersionId", "arn"],

        diff: Effect.fn(function* ({ olds = {}, news }) {
          if (!isResolved(news)) return undefined;
          // Everything but status is baked into the published version — a
          // change to the detector, rules, execution mode, or description
          // replaces the version. Status transitions happen in place.
          if (
            (olds.detectorId ?? undefined) !== (news.detectorId ?? undefined) ||
            (olds.ruleExecutionMode ?? undefined) !== (news.ruleExecutionMode ?? undefined) ||
            (olds.description ?? undefined) !== (news.description ?? undefined) ||
            !deepEqual(olds.rules, news.rules)
          ) {
            return { action: "replace" } as const;
          }
        }),

        read: Effect.fn(function* ({ output }) {
          if (output?.detectorVersionId === undefined) return undefined;
          const version = yield* getVersion(output.detectorId, output.detectorVersionId);
          if (version === undefined) return undefined;
          return {
            detectorId: version.detectorId!,
            detectorVersionId: version.detectorVersionId!,
            arn: version.arn!,
            status: version.status!,
          };
        }),

        reconcile: Effect.fn(function* ({ id, news, output, session }) {
          const detectorId = news.detectorId;
          const desiredStatus = news.status ?? "ACTIVE";
          const internalTags = yield* createInternalTags(id);
          const desiredTags = { ...internalTags, ...news.tags };

          // 1. ENSURE the rules exist and collect their version references.
          const ruleRefs = yield* ensureRules(detectorId, news.rules);

          // 2. OBSERVE the version; create it if missing. Published versions
          //    are immutable, so any content change triggers replacement (see
          //    diff) — here we only ever create or converge status/tags.
          let detectorVersionId = output?.detectorVersionId;
          let version =
            detectorVersionId !== undefined
              ? yield* getVersion(detectorId, detectorVersionId)
              : undefined;

          if (version === undefined) {
            const created = yield* frauddetector.createDetectorVersion({
              detectorId,
              description: news.description,
              rules: ruleRefs,
              ruleExecutionMode: news.ruleExecutionMode,
              tags: Object.entries(desiredTags).map(([key, value]) => ({
                key,
                value,
              })),
            });
            detectorVersionId = created.detectorVersionId!;
            version = yield* getVersion(detectorId, detectorVersionId);
          }

          // 3. SYNC status — a new version is created in DRAFT; move it to the
          //    desired status if it drifts.
          if ((version!.status ?? undefined) !== desiredStatus) {
            yield* frauddetector.updateDetectorVersionStatus({
              detectorId,
              detectorVersionId: detectorVersionId!,
              status: desiredStatus,
            });
          }

          // 4. SYNC tags — diff against OBSERVED cloud tags.
          yield* syncFraudDetectorTags(version!.arn!, desiredTags);

          yield* session.note(detectorVersionId!);
          return {
            detectorId,
            detectorVersionId: detectorVersionId!,
            arn: version!.arn!,
            status: desiredStatus,
          };
        }),

        delete: Effect.fn(function* ({ output }) {
          const { detectorId, detectorVersionId } = output;
          // Read the rules the version owns before removing it so we can clean
          // them up afterwards (rules block detector deletion otherwise).
          const version = yield* getVersion(detectorId, detectorVersionId);
          const rules = version?.rules ?? [];

          // A version must be INACTIVE before it can be deleted.
          yield* frauddetector
            .updateDetectorVersionStatus({
              detectorId,
              detectorVersionId,
              status: "INACTIVE",
            })
            .pipe(
              Effect.catchTag(
                ["ValidationException", "ConflictException", "ResourceNotFoundException"],
                () => Effect.void,
              ),
            );

          yield* frauddetector
            .deleteDetectorVersion({ detectorId, detectorVersionId })
            .pipe(
              Effect.catchTag(
                ["ValidationException", "ConflictException", "ResourceNotFoundException"],
                () => Effect.void,
              ),
            );

          // Best-effort cleanup of the owned rule versions.
          for (const rule of rules) {
            yield* frauddetector
              .deleteRule({ rule })
              .pipe(
                Effect.catchTag(["ValidationException", "ConflictException"], () => Effect.void),
              );
          }
        }),

        // Detector versions are sub-resources keyed by their parent detector;
        // there is no account-wide enumeration op, so list is a no-op.
        list: () => Effect.succeed([]),
      };
    }),
  );