sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ Chatbot/ MicrosoftTeamsChannelConfiguration.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";

export interface MicrosoftTeamsChannelConfigurationProps {
  /**
   * Name of the configuration (1-128 characters, `A-Za-z0-9-_`). Forms the
   * trailing segment of the chat configuration ARN.
   *
   * Changing the name replaces the configuration.
   * @default ${app}-${stage}-${id}
   */
  configurationName?: string;
  /**
   * ID of the Microsoft Teams team authorized with AWS Chatbot. The team
   * must first be onboarded via the AWS Chatbot console OAuth flow — this
   * cannot be automated.
   *
   * Changing the team replaces the configuration.
   */
  teamId: string;
  /**
   * ID of the Microsoft Teams tenant.
   *
   * Changing the tenant replaces the configuration.
   */
  tenantId: string;
  /**
   * ID of the Microsoft Teams channel.
   */
  teamsChannelId: string;
  /**
   * Name of the Microsoft Teams channel. Informational only.
   */
  teamsChannelName?: string;
  /**
   * Name of the Microsoft Teams team. Informational only.
   */
  teamName?: string;
  /**
   * ARN of the IAM role that defines the permissions for running commands
   * from this channel (the channel role). Must trust
   * `chatbot.amazonaws.com`.
   */
  iamRoleArn: string;
  /**
   * ARNs of the SNS topics that deliver notifications to this channel.
   */
  snsTopicArns?: string[];
  /**
   * Logging level for the configuration: `ERROR`, `INFO`, or `NONE`.
   * @default NONE
   */
  loggingLevel?: "ERROR" | "INFO" | "NONE";
  /**
   * ARNs of the IAM managed policies applied as channel guardrails. The AWS
   * managed `AdministratorAccess` policy is applied by default if this is
   * not set.
   */
  guardrailPolicyArns?: string[];
  /**
   * Whether channel members must have their AWS user identities authorized
   * before running commands.
   * @default false
   */
  userAuthorizationRequired?: boolean;
  /**
   * Tags to apply to the configuration. Merged with internal Alchemy tags.
   */
  tags?: Record<string, string>;
}

export interface MicrosoftTeamsChannelConfiguration extends Resource<
  "AWS.Chatbot.MicrosoftTeamsChannelConfiguration",
  MicrosoftTeamsChannelConfigurationProps,
  {
    /**
     * Name of the channel configuration.
     */
    configurationName: string;
    /**
     * The ARN of the channel configuration.
     */
    chatConfigurationArn: string;
    /**
     * The Microsoft Teams team ID.
     */
    teamId: string;
    /**
     * The Microsoft Entra (Azure AD) tenant ID.
     */
    tenantId: string;
    /**
     * The Microsoft Teams channel ID.
     */
    teamsChannelId: string;
    /**
     * Current state of the configuration (e.g. `ENABLED`).
     */
    state: string | undefined;
  },
  never,
  Providers
> {}

/**
 * An AWS Chatbot (Amazon Q Developer in chat applications) Microsoft Teams
 * channel configuration that delivers SNS notifications to a Teams channel
 * and lets channel members run read-only or scoped AWS commands.
 *
 * The Microsoft Teams team must be onboarded to AWS Chatbot beforehand via
 * the console OAuth flow (Chatbot console -> Configure new client ->
 * Microsoft Teams) — team authorization cannot be automated.
 *
 * ### Creating Microsoft Teams Channel Configurations
 * **Example:** Notify a Teams channel from an SNS topic
 * ```typescript
 * import * as Chatbot from "@alchemy.run/aws/Chatbot";
 * import { Role } from "@alchemy.run/aws/IAM/Role";
 * import * as SNS from "@alchemy.run/aws/SNS";
 *
 * const topic = yield* SNS.Topic("Alerts", {});
 * const role = yield* Role("ChatbotRole", {
 *   assumeRolePolicyDocument: {
 *     Version: "2012-10-17",
 *     Statement: [
 *       {
 *         Effect: "Allow",
 *         Principal: { Service: "chatbot.amazonaws.com" },
 *         Action: ["sts:AssumeRole"],
 *       },
 *     ],
 *   },
 *   managedPolicyArns: ["arn:aws:iam::aws:policy/ReadOnlyAccess"],
 * });
 *
 * const config = yield* Chatbot.MicrosoftTeamsChannelConfiguration("Alerts", {
 *   teamId: "0a1b2c3d-4e5f-1a2b-3c4d-0a1b2c3d4e5f",
 *   tenantId: "1a2b3c4d-5e6f-1a2b-3c4d-1a2b3c4d5e6f",
 *   teamsChannelId: "19%3ab6ef35dc342d56ba5654e6fc6d25a071%40thread.tacv2",
 *   iamRoleArn: role.roleArn,
 *   snsTopicArns: [topic.topicArn],
 * });
 * ```
 *
 * @resource
 */
export const MicrosoftTeamsChannelConfiguration = Resource<MicrosoftTeamsChannelConfiguration>(
  "AWS.Chatbot.MicrosoftTeamsChannelConfiguration",
);

export const MicrosoftTeamsChannelConfigurationProvider = () =>
  Provider.effect(
    MicrosoftTeamsChannelConfiguration,
    Effect.gen(function* () {
      const createConfigurationName = Effect.fn(function* (
        id: string,
        props: Pick<MicrosoftTeamsChannelConfigurationProps, "configurationName">,
      ) {
        return props.configurationName ?? (yield* createPhysicalName({ id, maxLength: 128 }));
      });

      const configurationArn = Effect.fn(function* (configurationName: string) {
        const { accountId } = yield* AWSEnvironment.current;
        // Chatbot chat-configuration ARNs are global (no region component).
        return `arn:aws:chatbot::${accountId}:chat-configuration/microsoft-teams-channel/${configurationName}`;
      });

      const observeConfiguration = (arn: string) =>
        chatbot.getMicrosoftTeamsChannelConfiguration({ ChatConfigurationArn: arn }).pipe(
          inChatbotRegion,
          Effect.map((r) => r.ChannelConfiguration),
          // Typed via the distilled chatbot patch — the wire error is a
          // ResourceNotFoundException outside the Smithy model's union.
          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>),
          ),
        );

      const toAttributes = (
        configurationName: string,
        live: chatbot.TeamsChannelConfiguration,
      ) => ({
        configurationName,
        chatConfigurationArn: live.ChatConfigurationArn,
        teamId: live.TeamId,
        tenantId: live.TenantId,
        teamsChannelId: live.ChannelId,
        state: live.State,
      });

      return MicrosoftTeamsChannelConfiguration.Provider.of({
        stables: ["configurationName", "chatConfigurationArn", "teamId", "tenantId"],
        list: () =>
          Effect.gen(function* () {
            const configurations = yield* chatbot.listMicrosoftTeamsChannelConfigurations
              .items({})
              .pipe(Stream.runCollect, inChatbotRegion);
            return Array.from(configurations).map((config) => {
              const arn = config.ChatConfigurationArn;
              return toAttributes(arn.slice(arn.lastIndexOf("/") + 1), config);
            });
          }),
        read: Effect.fn(function* ({ id, olds, output }) {
          const configurationName =
            output?.configurationName ?? (yield* createConfigurationName(id, olds ?? {}));
          const arn = output?.chatConfigurationArn ?? (yield* configurationArn(configurationName));
          const found = yield* observeConfiguration(arn);
          if (found === undefined) return undefined;
          const attrs = toAttributes(configurationName, found);
          const tags = yield* observedTags(found.ChatConfigurationArn);
          return (yield* hasAlchemyTags(id, tags)) ? attrs : Unowned(attrs);
        }),
        diff: Effect.fn(function* ({ id, news, olds }) {
          if (!isResolved(news)) return undefined;
          const oldName = yield* createConfigurationName(id, olds ?? {});
          const newName = yield* createConfigurationName(id, news ?? {});
          if (
            oldName !== newName ||
            olds?.teamId !== news.teamId ||
            olds?.tenantId !== news.tenantId
          ) {
            return { action: "replace" } as const;
          }
          // fall through: engine default update logic for mutable fields
        }),
        reconcile: Effect.fn(function* ({ id, news, output, session }) {
          const configurationName =
            output?.configurationName ?? (yield* createConfigurationName(id, news));
          const arn = output?.chatConfigurationArn ?? (yield* configurationArn(configurationName));
          const internalTags = yield* createInternalTags(id);
          const desiredTags = { ...news.tags, ...internalTags };
          const desiredTopics = [...(news.snsTopicArns ?? [])].sort();
          const desiredGuardrails = news.guardrailPolicyArns
            ? [...news.guardrailPolicyArns].sort()
            : undefined;

          // 1. OBSERVE — cloud state is authoritative.
          let live = yield* observeConfiguration(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
              .createMicrosoftTeamsChannelConfiguration({
                ChannelId: news.teamsChannelId,
                ChannelName: news.teamsChannelName,
                TeamId: news.teamId,
                TeamName: news.teamName,
                TenantId: news.tenantId,
                ConfigurationName: configurationName,
                IamRoleArn: news.iamRoleArn,
                SnsTopicArns: news.snsTopicArns,
                LoggingLevel: news.loggingLevel,
                GuardrailPolicyArns: news.guardrailPolicyArns,
                UserAuthorizationRequired: news.userAuthorizationRequired,
                Tags: toChatbotTags(desiredTags),
              })
              .pipe(
                inChatbotRegion,
                Effect.map((r) => r.ChannelConfiguration),
                Effect.catchTag("ConflictException", () => observeConfiguration(arn)),
              );
          }

          // 3. SYNC — diff the OBSERVED mutable aspects against the desired
          //    state; update only on drift.
          const inSync =
            live !== undefined &&
            live.ChannelId === news.teamsChannelId &&
            live.IamRoleArn === news.iamRoleArn &&
            JSON.stringify([...live.SnsTopicArns].sort()) === JSON.stringify(desiredTopics) &&
            (live.LoggingLevel ?? "NONE") === (news.loggingLevel ?? "NONE") &&
            JSON.stringify(
              live.GuardrailPolicyArns ? [...live.GuardrailPolicyArns].sort() : undefined,
            ) === JSON.stringify(desiredGuardrails) &&
            (live.UserAuthorizationRequired ?? false) === (news.userAuthorizationRequired ?? false);
          if (!inSync) {
            live = yield* chatbot
              .updateMicrosoftTeamsChannelConfiguration({
                ChatConfigurationArn: arn,
                ChannelId: news.teamsChannelId,
                ChannelName: news.teamsChannelName,
                IamRoleArn: news.iamRoleArn,
                SnsTopicArns: news.snsTopicArns,
                LoggingLevel: news.loggingLevel,
                GuardrailPolicyArns: news.guardrailPolicyArns,
                UserAuthorizationRequired: news.userAuthorizationRequired,
              })
              .pipe(
                inChatbotRegion,
                Effect.map((r) => r.ChannelConfiguration),
              );
          }

          // 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(configurationName);
          return live !== undefined
            ? toAttributes(configurationName, live)
            : {
                configurationName,
                chatConfigurationArn: arn,
                teamId: news.teamId,
                tenantId: news.tenantId,
                teamsChannelId: news.teamsChannelId,
                state: undefined,
              };
        }),
        delete: Effect.fn(function* ({ output }) {
          yield* chatbot
            .deleteMicrosoftTeamsChannelConfiguration({
              ChatConfigurationArn: output.chatConfigurationArn,
            })
            .pipe(
              inChatbotRegion,
              // Idempotent delete — a missing configuration is not an error.
              Effect.catchTag("ResourceNotFoundException", () => Effect.void),
            );
        }),
      });
    }),
  );