sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ Chatbot/ CustomAction.ts

import * as chatbot from "@distilled.cloud/aws/chatbot";
import { Unowned } from "alchemy/AdoptPolicy";
import { isResolved } from "alchemy/Diff";
import { createPhysicalName } from "alchemy/PhysicalName";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import { createInternalTags, diffTags, hasAlchemyTags } from "alchemy/Tags";
import * as Effect from "effect/Effect";
import * as Stream from "effect/Stream";
import { AWSEnvironment } from "../Environment.ts";
import type { Providers } from "../Providers.ts";
import { fromChatbotTags, inChatbotRegion, toChatbotTags } from "./internal.ts";

/**
 * A criteria block controlling when a custom action button is shown on a
 * notification.
 */
export interface CustomActionAttachmentCriteria {
  /**
   * The operation to perform on the named variable: `HAS_VALUE` or `EQUALS`.
   */
  operator: "HAS_VALUE" | "EQUALS" | (string & {});
  /**
   * The name of the notification variable to operate on.
   */
  variableName: string;
  /**
   * The value to compare the variable against when the operator is `EQUALS`.
   */
  value?: string;
}

/**
 * Defines when and how a custom action surfaces as a button on chat
 * notifications.
 */
export interface CustomActionAttachment {
  /**
   * The type of notification the action button appears on, e.g.
   * `CloudWatch`. Although the AWS API documentation marks this optional,
   * the live API rejects attachments without it (`Invalid request body`).
   */
  notificationType: string;
  /**
   * The label of the button that appears on the notification.
   */
  buttonText?: string;
  /**
   * Conditions (over notification variables) that must be met for the button
   * to appear.
   */
  criteria?: CustomActionAttachmentCriteria[];
  /**
   * Variable values bound into the action's command text.
   */
  variables?: Record<string, string>;
}

export interface CustomActionProps {
  /**
   * Name of the custom action (1-64 characters, `A-Za-z0-9-_`). Forms the
   * trailing segment of the custom action ARN.
   *
   * Changing the name replaces the custom action.
   * @default ${app}-${stage}-${id}
   */
  actionName?: string;
  /**
   * The CLI command text executed when the action is invoked, e.g.
   * `aws lambda list-functions`. Variables from attachments may be
   * interpolated with `$variable` syntax.
   */
  commandText: string;
  /**
   * An alias that lets chat users invoke the action as `@aws run <alias>`.
   */
  aliasName?: string;
  /**
   * Notification attachments that surface the action as a button on
   * matching notifications.
   */
  attachments?: CustomActionAttachment[];
  /**
   * Tags to apply to the custom action. Merged with internal Alchemy tags.
   */
  tags?: Record<string, string>;
}

export interface CustomAction extends Resource<
  "AWS.Chatbot.CustomAction",
  CustomActionProps,
  {
    /**
     * Name of the custom action.
     */
    actionName: string;
    /**
     * The ARN of the custom action.
     */
    customActionArn: string;
  },
  never,
  Providers
> {}

/**
 * An AWS Chatbot (Amazon Q Developer in chat applications) custom action —
 * a reusable CLI command that chat users invoke by alias or as a button on
 * notifications.
 *
 * Custom actions exist at the account level and do not require a chat
 * workspace to be onboarded, though they only become usable once a Slack or
 * Microsoft Teams channel configuration exists.
 *
 * ### Creating Custom Actions
 * **Example:** List Lambda functions from chat
 * ```typescript
 * import * as Chatbot from "@alchemy.run/aws/Chatbot";
 *
 * const action = yield* Chatbot.CustomAction("ListFunctions", {
 *   commandText: "aws lambda list-functions",
 *   aliasName: "list-functions",
 * });
 * ```
 *
 * **Example:** Button on CloudWatch alarm notifications
 * ```typescript
 * const action = yield* Chatbot.CustomAction("DescribeAlarm", {
 *   commandText: "aws cloudwatch describe-alarms --alarm-names $AlarmName",
 *   attachments: [
 *     {
 *       notificationType: "CloudWatch",
 *       buttonText: "Describe alarm",
 *       criteria: [
 *         { operator: "HAS_VALUE", variableName: "AlarmName" },
 *       ],
 *     },
 *   ],
 * });
 * ```
 *
 * @resource
 */
export const CustomAction = Resource<CustomAction>("AWS.Chatbot.CustomAction");

const toWireAttachment = (attachment: CustomActionAttachment): chatbot.CustomActionAttachment => ({
  NotificationType: attachment.notificationType,
  ButtonText: attachment.buttonText,
  Criteria: attachment.criteria?.map((c) => ({
    Operator: c.operator,
    VariableName: c.variableName,
    Value: c.value,
  })),
  Variables: attachment.variables,
});

export const CustomActionProvider = () =>
  Provider.effect(
    CustomAction,
    Effect.gen(function* () {
      const createActionName = Effect.fn(function* (
        id: string,
        props: Pick<CustomActionProps, "actionName">,
      ) {
        // Custom action names are limited to 64 characters of [A-Za-z0-9-_].
        return props.actionName ?? (yield* createPhysicalName({ id, maxLength: 64 }));
      });

      const actionArn = Effect.fn(function* (actionName: string) {
        const { accountId } = yield* AWSEnvironment.current;
        // Chatbot custom action ARNs are global (no region component).
        return `arn:aws:chatbot::${accountId}:custom-action/${actionName}`;
      });

      const observeAction = (arn: string) =>
        chatbot.getCustomAction({ CustomActionArn: arn }).pipe(
          inChatbotRegion,
          Effect.map((r) => r.CustomAction),
          Effect.catchTag("ResourceNotFoundException", () => Effect.undefined),
        );

      const observedTags = (arn: string) =>
        chatbot.listTagsForResource({ ResourceARN: arn }).pipe(
          inChatbotRegion,
          Effect.map((r) => fromChatbotTags(r.Tags)),
          Effect.catchTag("ResourceNotFoundException", () =>
            Effect.succeed({} as Record<string, string>),
          ),
        );

      return CustomAction.Provider.of({
        stables: ["actionName", "customActionArn"],
        list: () =>
          Effect.gen(function* () {
            const arns = yield* chatbot.listCustomActions
              .items({})
              .pipe(Stream.runCollect, inChatbotRegion);
            return Array.from(arns).map((arn) => ({
              actionName: arn.slice(arn.lastIndexOf("/") + 1),
              customActionArn: arn,
            }));
          }),
        read: Effect.fn(function* ({ id, olds, output }) {
          const actionName = output?.actionName ?? (yield* createActionName(id, olds ?? {}));
          const arn = output?.customActionArn ?? (yield* actionArn(actionName));
          const found = yield* observeAction(arn);
          if (found === undefined) return undefined;
          const attrs = { actionName, customActionArn: found.CustomActionArn };
          const tags = yield* observedTags(found.CustomActionArn);
          return (yield* hasAlchemyTags(id, tags)) ? attrs : Unowned(attrs);
        }),
        diff: Effect.fn(function* ({ id, news, olds }) {
          if (!isResolved(news)) return undefined;
          const oldName = yield* createActionName(id, olds ?? {});
          const newName = yield* createActionName(id, news ?? {});
          if (oldName !== newName) {
            return { action: "replace" } as const;
          }
          // fall through: engine default update logic for mutable fields
        }),
        reconcile: Effect.fn(function* ({ id, news, output, session }) {
          const actionName = output?.actionName ?? (yield* createActionName(id, news));
          const arn = output?.customActionArn ?? (yield* actionArn(actionName));
          const internalTags = yield* createInternalTags(id);
          const desiredTags = { ...news.tags, ...internalTags };
          const desiredDefinition = { CommandText: news.commandText };
          const desiredAttachments = news.attachments?.map(toWireAttachment);

          // 1. OBSERVE — cloud state is authoritative.
          let live = yield* observeAction(arn);

          // 2. ENSURE — create when missing; a concurrent create surfaces as
          //    the typed ConflictException, which we treat as a race and
          //    re-observe.
          if (live === undefined) {
            live = yield* chatbot
              .createCustomAction({
                ActionName: actionName,
                Definition: desiredDefinition,
                AliasName: news.aliasName,
                Attachments: desiredAttachments,
                Tags: toChatbotTags(desiredTags),
              })
              .pipe(
                inChatbotRegion,
                Effect.map((r) => r.CustomActionArn),
                Effect.catchTag("ConflictException", () => Effect.succeed(arn)),
                Effect.flatMap(observeAction),
              );
          }

          // 3. SYNC — diff the OBSERVED definition, alias, and attachments
          //    against the desired state; update only on drift.
          const inSync =
            live !== undefined &&
            live.Definition.CommandText === news.commandText &&
            live.AliasName === news.aliasName &&
            JSON.stringify(live.Attachments ?? []) === JSON.stringify(desiredAttachments ?? []);
          if (!inSync) {
            yield* chatbot
              .updateCustomAction({
                CustomActionArn: arn,
                Definition: desiredDefinition,
                AliasName: news.aliasName,
                Attachments: desiredAttachments,
              })
              .pipe(inChatbotRegion);
          }

          // 3b. SYNC TAGS — diff against OBSERVED cloud tags so adoption
          //     converges (create-time Tags only apply on first create).
          const currentTags = yield* observedTags(arn);
          const { upsert, removed } = diffTags(currentTags, desiredTags);
          if (upsert.length > 0) {
            yield* chatbot
              .tagResource({
                ResourceARN: arn,
                Tags: upsert.map(({ Key, Value }) => ({
                  TagKey: Key,
                  TagValue: Value,
                })),
              })
              .pipe(inChatbotRegion);
          }
          if (removed.length > 0) {
            yield* chatbot
              .untagResource({
                ResourceARN: arn,
                TagKeys: removed,
              })
              .pipe(inChatbotRegion);
          }

          yield* session.note(actionName);
          return { actionName, customActionArn: arn };
        }),
        delete: Effect.fn(function* ({ output }) {
          yield* chatbot.deleteCustomAction({ CustomActionArn: output.customActionArn }).pipe(
            inChatbotRegion,
            // Idempotent delete — a missing action is not an error.
            Effect.catchTag("ResourceNotFoundException", () => Effect.void),
          );
        }),
      });
    }),
  );