sailfork / t3code-github / .repos/ alchemy-effect/ packages/ gcp/ src/ DiscoveryEngine/ DataStoresControl.ts

import * as discoveryengine from "@distilled.cloud/gcp/discoveryengine_v1";
import { unownedUnlessPrevious } from "alchemy/AdoptPolicy";
import { isResolved } from "alchemy/Diff";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import { GcpEnvironment } from "../Environment.ts";
import type { Providers } from "../Providers.ts";
import {
  controlIdOf,
  expandDataStore,
  fingerprint,
  parseResourceName,
  toPhysical,
} from "./internal.ts";

export type DataStoresControlQueryTerm = {
  /** Query value to match. Must be lowercase UTF-8. */
  value: string;
  /**
   * Whether the search query must exactly match the term.
   * @default false
   */
  fullMatch?: boolean;
};

export type DataStoresControlTimeRange = {
  /** Inclusive start of the active window (RFC3339). */
  startTime?: string;
  /** Inclusive end of the active window (RFC3339). */
  endTime?: string;
};

export type DataStoresControlCondition = {
  /** Query regex matching the whole search query. */
  queryRegex?: string;
  /** Query terms to match. Maximum 10. */
  queryTerms?: DataStoresControlQueryTerm[];
  /** Active time windows. Maximum 10. */
  activeTimeRange?: DataStoresControlTimeRange[];
};

export type DataStoresControlRedirectAction = {
  /** URI to redirect the shopper to (max 2000 characters). */
  redirectUri: string;
};

export type DataStoresControlFilterAction = {
  /** Filter expression applied to matching results. */
  filter: string;
  /** Data store whose documents can be filtered. Defaults to the parent. */
  dataStore?: string;
};

export type DataStoresControlSynonymsAction = {
  /** Synonym set. At least 2, at most 100. */
  synonyms: string[];
};

export type DataStoresControlBoostAction = {
  /** Filter selecting documents to boost. */
  filter?: string;
  /** Data store whose documents can be boosted. Defaults to the parent. */
  dataStore?: string;
  /** Boost strength in `[-1, 1]`. Negative values demote. */
  boost?: number;
  /** Fixed boost strength in `[-1, 1]`. */
  fixedBoost?: number;
};

export type DataStoresControlPromoteAction = {
  /** Data store this promotion is attached to. Defaults to the parent. */
  dataStore?: string;
  /** Promotion title (max 160 characters). */
  title: string;
  /** Promotion URI. */
  uri?: string;
  /** Promotion description (max 200 characters). */
  description?: string;
  /** Thumbnail image URI. */
  imageUri?: string;
  /** Document resource name to promote. */
  document?: string;
  /**
   * Whether the promotion is enabled.
   * @default true
   */
  enabled?: boolean;
};

export type DataStoresControlProps = {
  /**
   * Parent Data Store resource name
   * `projects/{project}/locations/{location}/dataStores/{dataStore}`.
   * Immutable — changing it replaces the control.
   */
  dataStore: string;
  /**
   * Control id (1-63 characters, `a-z`, `_`, `-`). If omitted, a unique
   * id is generated. Immutable — changing it replaces the control.
   */
  controlId?: string;
  /**
   * Human-readable name (max 128 characters).
   */
  displayName?: string;
  /**
   * Solution this control belongs to. Immutable — changing it replaces
   * the control.
   * @default "SOLUTION_TYPE_SEARCH"
   */
  solutionType?: string;
  /**
   * Search use cases. Required when `solutionType` is
   * `SOLUTION_TYPE_SEARCH`.
   * @default ["SEARCH_USE_CASE_SEARCH"]
   */
  useCases?: string[];
  /**
   * Conditions that trigger the action. Omit to always apply.
   */
  conditions?: DataStoresControlCondition[];
  /** Redirect-type action. Mutually exclusive with the other actions. */
  redirectAction?: DataStoresControlRedirectAction;
  /** Filter-type action. Mutually exclusive with the other actions. */
  filterAction?: DataStoresControlFilterAction;
  /** Synonyms-type action. Mutually exclusive with the other actions. */
  synonymsAction?: DataStoresControlSynonymsAction;
  /** Boost-type action. Mutually exclusive with the other actions. */
  boostAction?: DataStoresControlBoostAction;
  /** Promote-type action. Mutually exclusive with the other actions. */
  promoteAction?: DataStoresControlPromoteAction;
};

export type DataStoresControl = Resource<
  "GCP.DiscoveryEngine.DataStoresControl",
  DataStoresControlProps,
  {
    /** Full resource name `.../dataStores/{dataStore}/controls/{control}`. */
    name: string;
    /** Control id (last path segment). */
    controlId: string;
    /** Parent data store resource name. */
    dataStore: string;
    /** Project id. */
    project: string;
    /** Location id. */
    location: string;
    /** Display name. */
    displayName: string | undefined;
    /** Solution type. */
    solutionType: string | undefined;
    /** Search use cases. */
    useCases: string[];
    /** Serving configs this control is attached to. */
    associatedServingConfigIds: string[];
  },
  never,
  Providers
>;

/**
 * A Vertex AI Search Control attached to a Data Store.
 *
 * Without labels, ownership rests on the deterministic id: `read` reports a
 * resource it finds without prior state as unowned (adopt it with `--adopt`).
 * Parent, control id, solution type, and action kind are immutable; display
 * name, conditions, and action payload update in place.
 *
 * ### Creating a Control
 * **Example:** Synonym control
 * ```typescript
 * const control = yield* GCP.DiscoveryEngine.DataStoresControl("Synonyms", {
 *   dataStore: dataStore.name,
 *   displayName: "happy-glad",
 *   synonymsAction: { synonyms: ["happy", "glad"] },
 * });
 * ```
 *
 * ### Updating a Control
 * **Example:** Rename and expand the synonym set
 * ```typescript
 * // Same logical id as before; only the changed props differ.
 * const control = yield* GCP.DiscoveryEngine.DataStoresControl("Synonyms", {
 *   dataStore: dataStore.name,
 *   displayName: "mood",
 *   synonymsAction: { synonyms: ["happy", "glad", "cheerful"] },
 * });
 * ```
 *
 * @resource
 * @category DiscoveryEngine
 */
export const DataStoresControl = Resource<DataStoresControl>(
  "GCP.DiscoveryEngine.DataStoresControl",
);

export class DataStoresControlNotResolved extends Data.TaggedError(
  "GCP.DiscoveryEngine.DataStoresControlNotResolved",
)<{
  resourceName: string;
}> {}

const DEFAULT_SOLUTION = "SOLUTION_TYPE_SEARCH";
const DEFAULT_USE_CASES = ["SEARCH_USE_CASE_SEARCH"];

const resourceName = (dataStore: string, controlId: string) => `${dataStore}/controls/${controlId}`;

const actionKind = (props: {
  redirectAction?: unknown;
  filterAction?: unknown;
  synonymsAction?: unknown;
  boostAction?: unknown;
  promoteAction?: unknown;
}) => {
  if (props.redirectAction) return "redirect";
  if (props.filterAction) return "filter";
  if (props.synonymsAction) return "synonyms";
  if (props.boostAction) return "boost";
  if (props.promoteAction) return "promote";
  return "none";
};

const toBody = (
  news: DataStoresControlProps,
  displayName: string,
): discoveryengine.GoogleCloudDiscoveryengineV1Control => ({
  displayName,
  solutionType: news.solutionType ?? DEFAULT_SOLUTION,
  useCases: news.useCases ?? DEFAULT_USE_CASES,
  conditions: news.conditions,
  redirectAction: news.redirectAction,
  filterAction: news.filterAction
    ? {
        filter: news.filterAction.filter,
        dataStore: news.filterAction.dataStore ?? news.dataStore,
      }
    : undefined,
  synonymsAction: news.synonymsAction,
  boostAction: news.boostAction
    ? {
        filter: news.boostAction.filter,
        dataStore: news.boostAction.dataStore ?? news.dataStore,
        boost: news.boostAction.boost,
        fixedBoost: news.boostAction.fixedBoost,
      }
    : undefined,
  promoteAction: news.promoteAction
    ? {
        dataStore: news.promoteAction.dataStore ?? news.dataStore,
        searchLinkPromotion: {
          title: news.promoteAction.title,
          uri: news.promoteAction.uri,
          description: news.promoteAction.description,
          imageUri: news.promoteAction.imageUri,
          document: news.promoteAction.document,
          enabled: news.promoteAction.enabled,
        },
      }
    : undefined,
});

const toAttrs = (
  control: discoveryengine.GoogleCloudDiscoveryengineV1Control,
  project: string,
  dataStoreHint?: string,
) => {
  const name = control.name ?? "";
  const parsed = parseResourceName(name, "controls");
  const dataStore = parsed.dataStore.includes("/dataStores/")
    ? parsed.dataStore
    : (dataStoreHint ?? parsed.dataStore);
  return {
    name,
    controlId: parsed.id,
    dataStore,
    project: parsed.project || project,
    location: parsed.location,
    displayName: control.displayName,
    solutionType: control.solutionType,
    useCases: [...(control.useCases ?? [])],
    associatedServingConfigIds: [...(control.associatedServingConfigIds ?? [])],
  };
};

const getByName = (name: string) =>
  name.length === 0
    ? Effect.undefined
    : discoveryengine
        .getProjectsLocationsDataStoresControls({ name })
        .pipe(Effect.catchTag("NotFound", () => Effect.undefined));

export const DataStoresControlProvider = () =>
  Provider.succeed(DataStoresControl, {
    stables: ["name", "controlId", "dataStore", "project", "location"],

    diff: Effect.fn(function* ({ news, olds, output }) {
      if (!isResolved(news)) return undefined;
      const previousParent = olds?.dataStore ?? output?.dataStore;
      if (previousParent !== undefined && news.dataStore !== previousParent) {
        return { action: "replace" as const, deleteFirst: false };
      }
      const previousId = olds?.controlId ?? output?.controlId;
      if (
        previousId !== undefined &&
        news.controlId !== undefined &&
        news.controlId !== previousId
      ) {
        return { action: "replace" as const, deleteFirst: true };
      }
      const previousSolution = olds?.solutionType ?? output?.solutionType ?? DEFAULT_SOLUTION;
      const nextSolution = news.solutionType ?? previousSolution;
      if (previousSolution !== nextSolution) {
        return { action: "replace" as const, deleteFirst: true };
      }
      const previousKind = actionKind(olds ?? {});
      const nextKind = actionKind(news);
      if (previousKind !== "none" && nextKind !== previousKind) {
        return { action: "replace" as const, deleteFirst: true };
      }
      const previousAction = fingerprint({
        redirectAction: olds?.redirectAction,
        filterAction: olds?.filterAction,
        synonymsAction: olds?.synonymsAction,
        boostAction: olds?.boostAction,
        promoteAction: olds?.promoteAction,
      });
      const nextAction = fingerprint({
        redirectAction: news.redirectAction,
        filterAction: news.filterAction,
        synonymsAction: news.synonymsAction,
        boostAction: news.boostAction,
        promoteAction: news.promoteAction,
      });
      if (previousKind !== "none" && previousAction !== nextAction) {
        return { action: "replace" as const, deleteFirst: true };
      }
      return undefined;
    }),

    read: Effect.fn(function* ({ id, olds, output, previous }) {
      const env = yield* GcpEnvironment.current;
      const controlId = yield* toPhysical(id, olds?.controlId, output?.controlId, controlIdOf);
      const parent = olds?.dataStore
        ? expandDataStore(olds.dataStore, env.project, output?.location ?? "global")
        : undefined;
      const name = output?.name ?? (parent ? resourceName(parent, controlId) : "");
      const existing = yield* getByName(name);
      if (existing === undefined) return undefined;
      const attrs = toAttrs(existing, env.project);
      // No labels field: without prior state it may not be ours.
      return output !== undefined ? attrs : unownedUnlessPrevious(attrs, previous, "name");
    }),

    reconcile: Effect.fn(function* ({ id, news, output }) {
      const env = yield* GcpEnvironment.current;
      const parent = expandDataStore(news.dataStore, env.project, output?.location ?? "global");
      const controlId = yield* toPhysical(id, news.controlId, output?.controlId, controlIdOf);
      const name = resourceName(parent, controlId);
      const displayName = news.displayName ?? controlId;

      let current = yield* getByName(output?.name ?? name);

      if (current === undefined) {
        const created = yield* discoveryengine
          .createProjectsLocationsDataStoresControls({
            parent,
            controlId,
            body: toBody(news, displayName),
          })
          .pipe(Effect.catchTag("Conflict", () => getByName(name)));
        current = created ?? undefined;
      }

      if (current === undefined) {
        return yield* new DataStoresControlNotResolved({ resourceName: name });
      }

      const desired = toBody(news, displayName);
      const displayChanged = (current.displayName ?? "") !== displayName;
      const useCasesChanged =
        fingerprint([...(current.useCases ?? [])].sort()) !==
        fingerprint([...(desired.useCases ?? [])].sort());
      const conditionsChanged = fingerprint(current.conditions) !== fingerprint(desired.conditions);
      if (displayChanged || useCasesChanged || conditionsChanged) {
        current = yield* discoveryengine.patchProjectsLocationsDataStoresControls({
          name: current.name ?? name,
          updateMask: [
            displayChanged ? "display_name" : undefined,
            useCasesChanged ? "use_cases" : undefined,
            conditionsChanged ? "conditions" : undefined,
          ]
            .filter((field): field is string => field !== undefined)
            .join(","),
          body: { ...desired, name: current.name ?? name },
        });
      }

      return toAttrs(current, env.project, parent);
    }),

    delete: Effect.fn(function* ({ output }) {
      const existing = yield* getByName(output.name);
      if (existing === undefined) return;
      yield* discoveryengine
        .deleteProjectsLocationsDataStoresControls({ name: output.name })
        .pipe(Effect.catchTag("NotFound", () => Effect.void));
    }),
  });