sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ LexV2/ Intent.ts

import * as lexm from "@distilled.cloud/aws/lex-models-v2";
import { isResolved } from "alchemy/Diff";
import { createPhysicalName } from "alchemy/PhysicalName";
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 Stream from "effect/Stream";
import type { Providers } from "../Providers.ts";
import { retryWhileConflict, toLexName } from "./internal.ts";

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

export interface IntentProps {
  /**
   * ID of the bot the intent belongs to. Changing it replaces the intent.
   */
  botId: string;
  /**
   * Locale the intent lives under, e.g. `en_US`. Changing it replaces the
   * intent. Pass the `localeId` attribute of a `BotLocale` so the intent
   * depends on the locale.
   */
  localeId: string;
  /**
   * Name of the intent. Mutable — renames update the intent in place
   * (identity is the generated intent ID).
   * @default ${app}-${id}-${stage}-${suffix}
   */
  intentName?: string;
  /**
   * Description of the intent.
   */
  description?: string;
  /**
   * Sample utterances that invoke the intent, e.g. `"I want to order a
   * pizza"`. Utterances may reference slots with `{slotName}`.
   */
  sampleUtterances?: string[];
  /**
   * Signature of a built-in intent to base this intent on, e.g.
   * `AMAZON.HelpIntent`.
   */
  parentIntentSignature?: string;
  /**
   * Invoke the alias's Lambda code hook on every dialog turn of this intent
   * (slot elicitation, validation). Attach the function itself with
   * `LexV2.onCodeHook`.
   * @default false
   */
  dialogCodeHook?: boolean;
  /**
   * Invoke the alias's Lambda code hook to fulfill the intent once all
   * required slots are filled. Attach the function itself with
   * `LexV2.onCodeHook`.
   * @default false
   */
  fulfillmentCodeHook?: boolean;
}

export interface Intent extends Resource<
  "AWS.LexV2.Intent",
  IntentProps,
  {
    /** Unique identifier assigned to the intent. */
    intentId: string;
    /** Name of the intent. */
    intentName: string;
    /** ID of the bot the intent belongs to. */
    botId: string;
    /** Bot version the intent lives on — always `DRAFT`. */
    botVersion: string;
    /** Locale the intent lives under. */
    localeId: string;
  },
  never,
  Providers
> {}

/**
 * An intent on the DRAFT locale of an Amazon Lex V2 bot — an action the user
 * wants to perform, recognized from sample utterances.
 *
 * ### Creating Intents
 * **Example:** Intent with Sample Utterances
 * ```typescript
 * import * as AWS from "@alchemy.run/aws";
 *
 * const greet = yield* AWS.LexV2.Intent("Greet", {
 *   botId: locale.botId,
 *   localeId: locale.localeId,
 *   sampleUtterances: ["hello", "hi", "good morning"],
 * });
 * ```
 *
 * **Example:** Built-in Parent Intent
 * ```typescript
 * const help = yield* AWS.LexV2.Intent("Help", {
 *   botId: locale.botId,
 *   localeId: locale.localeId,
 *   parentIntentSignature: "AMAZON.HelpIntent",
 * });
 * ```
 *
 * @resource
 */
export const Intent = Resource<Intent>("AWS.LexV2.Intent");

const createIntentName = (id: string, props: { intentName?: string | undefined }) =>
  Effect.gen(function* () {
    if (props.intentName) return props.intentName;
    return toLexName(yield* createPhysicalName({ id, maxLength: 100 }));
  });

const describeIntent = Effect.fn(function* (botId: string, localeId: string, intentId: string) {
  return yield* lexm
    .describeIntent({ botId, botVersion: "DRAFT", localeId, intentId })
    .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));
});

/** Find an intent of the locale by exact name (used when state was lost). */
const findIntentByName = Effect.fn(function* (botId: string, localeId: string, intentName: string) {
  const pages = yield* lexm.listIntents
    .pages({
      botId,
      botVersion: "DRAFT",
      localeId,
      filters: [{ name: "IntentName", values: [intentName], operator: "EQ" }],
    })
    .pipe(
      Stream.runCollect,
      Effect.catchTag("ResourceNotFoundException", () =>
        Effect.succeed([] as lexm.ListIntentsResponse[]),
      ),
    );
  const summary = Array.from(pages)
    .flatMap((page) => page.intentSummaries ?? [])
    .find((intent) => intent.intentName === intentName);
  if (summary?.intentId === undefined) return undefined;
  return yield* describeIntent(botId, localeId, summary.intentId);
});

const utterancesOf = (intent: lexm.DescribeIntentResponse | lexm.CreateIntentResponse): string[] =>
  (intent.sampleUtterances ?? []).map((u) => u.utterance);

const toUtterances = (utterances: string[] | undefined): lexm.SampleUtterance[] | undefined =>
  utterances?.map((utterance) => ({ utterance }));

const attributesOf = (intent: lexm.DescribeIntentResponse): Intent["Attributes"] => ({
  intentId: intent.intentId!,
  intentName: intent.intentName!,
  botId: intent.botId!,
  botVersion: "DRAFT",
  localeId: intent.localeId!,
});

export const IntentProvider = () =>
  Provider.effect(
    Intent,
    Effect.gen(function* () {
      return {
        stables: ["intentId", "botId", "botVersion", "localeId"],

        // Sub-resource keyed entirely by its bot locale — nuke reaches it
        // through the parent bot's deletion.
        list: () => Effect.succeed([]),

        read: Effect.fn(function* ({ id, olds, output }) {
          const botId = output?.botId ?? olds?.botId;
          const localeId = output?.localeId ?? olds?.localeId;
          if (botId === undefined || localeId === undefined) return undefined;
          const observed =
            output?.intentId !== undefined
              ? yield* describeIntent(botId, localeId, output.intentId)
              : yield* findIntentByName(botId, localeId, yield* createIntentName(id, olds ?? {}));
          return observed === undefined ? undefined : attributesOf(observed);
        }),

        diff: Effect.fn(function* ({ news, olds }) {
          if (!isResolved(news)) return undefined;
          if (olds?.botId !== news.botId || olds?.localeId !== news.localeId) {
            return { action: "replace" } as const;
          }
        }),

        reconcile: Effect.fn(function* ({ id, news, output, session }) {
          const intentName = yield* createIntentName(id, news);
          const desiredUtterances = news.sampleUtterances ?? [];
          const desiredDialogCodeHook =
            news.dialogCodeHook !== undefined ? { enabled: news.dialogCodeHook } : undefined;
          const desiredFulfillmentCodeHook =
            news.fulfillmentCodeHook !== undefined
              ? { enabled: news.fulfillmentCodeHook }
              : undefined;

          // 1. OBSERVE — output.intentId is only a cache; fall back to name.
          let observed =
            output?.intentId !== undefined
              ? yield* describeIntent(news.botId, news.localeId, output.intentId)
              : undefined;
          if (observed === undefined) {
            observed = yield* findIntentByName(news.botId, news.localeId, intentName);
          }

          // 2. ENSURE — create when missing.
          if (observed === undefined) {
            const created = yield* retryWhileConflict(
              lexm.createIntent({
                botId: news.botId,
                botVersion: "DRAFT",
                localeId: news.localeId,
                intentName,
                description: news.description,
                sampleUtterances: toUtterances(news.sampleUtterances),
                parentIntentSignature: news.parentIntentSignature,
                dialogCodeHook: desiredDialogCodeHook,
                fulfillmentCodeHook: desiredFulfillmentCodeHook,
              }),
            );
            observed = yield* describeIntent(news.botId, news.localeId, created.intentId!);
            if (observed === undefined) {
              return yield* new IntentUnexpectedResponse({
                message: `failed to read created Lex intent ${intentName}`,
              });
            }
          } else if (
            // 3. SYNC — UpdateIntent replaces the declared aspects; skip the
            //    call when nothing drifted.
            observed.intentName !== intentName ||
            (observed.description ?? undefined) !== (news.description ?? undefined) ||
            JSON.stringify([...utterancesOf(observed)].sort()) !==
              JSON.stringify([...desiredUtterances].sort()) ||
            (observed.dialogCodeHook?.enabled ?? false) !== (news.dialogCodeHook ?? false) ||
            (observed.fulfillmentCodeHook?.enabled ?? false) !== (news.fulfillmentCodeHook ?? false)
          ) {
            yield* retryWhileConflict(
              lexm.updateIntent({
                botId: news.botId,
                botVersion: "DRAFT",
                localeId: news.localeId,
                intentId: observed.intentId!,
                intentName,
                description: news.description,
                sampleUtterances: toUtterances(news.sampleUtterances),
                parentIntentSignature: news.parentIntentSignature,
                dialogCodeHook: desiredDialogCodeHook,
                fulfillmentCodeHook: desiredFulfillmentCodeHook,
              }),
            );
            observed = yield* describeIntent(news.botId, news.localeId, observed.intentId!);
            if (observed === undefined) {
              return yield* new IntentUnexpectedResponse({
                message: `failed to read updated Lex intent ${intentName}`,
              });
            }
          }

          yield* session.note(observed.intentId!);
          return attributesOf(observed);
        }),

        delete: Effect.fn(function* ({ output }) {
          // Lex reports a missing intent (or already-deleted parent) as
          // PreconditionFailed.
          yield* retryWhileConflict(
            lexm.deleteIntent({
              botId: output.botId,
              botVersion: "DRAFT",
              localeId: output.localeId,
              intentId: output.intentId,
            }),
          ).pipe(Effect.catchTag("PreconditionFailedException", () => Effect.void));
        }),
      };
    }),
  );