sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ SSMContacts/ ContactChannel.ts

import * as contacts from "@distilled.cloud/aws/ssm-contacts";
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 * as Effect from "effect/Effect";
import * as Stream from "effect/Stream";
import type { Providers } from "../Providers.ts";

/** How Incident Manager engages the contact through this channel. */
export type ContactChannelType = "SMS" | "VOICE" | "EMAIL";

export interface ContactChannelProps {
  /**
   * The ARN of the contact this channel belongs to. Changing it replaces the
   * channel.
   */
  contactId: string;

  /**
   * The name of the contact channel.
   *
   * @default ${app}-${id}-${stage}-${suffix}
   */
  name?: string;

  /**
   * The channel type: `SMS`, `VOICE`, or `EMAIL`. Changing it replaces the
   * channel.
   */
  type: ContactChannelType;

  /**
   * The address of the channel: an E.164 phone number (`+15551234567`) for
   * `SMS`/`VOICE`, or an email address for `EMAIL`.
   */
  deliveryAddress: contacts.ContactChannelAddress;

  /**
   * When `true`, the channel is created without sending an activation code —
   * the contact's device does not receive a message. Activate later with
   * `sendActivationCode` + `activateContactChannel`.
   *
   * @default false (AWS sends an activation code on create)
   */
  deferActivation?: boolean;
}

/** @resource */
export interface ContactChannel extends Resource<
  "AWS.SSMContacts.ContactChannel",
  ContactChannelProps,
  {
    /** ARN of the contact channel. */
    contactChannelArn: string;
    /** ARN of the owning contact. */
    contactArn: string;
    /** Name of the channel. */
    name: string;
    /** The channel type. */
    type: string;
    /** `ACTIVATED` or `NOT_ACTIVATED`. */
    activationStatus: string | undefined;
  },
  never,
  Providers
> {}

/**
 * An Incident Manager contact channel — the method (SMS, voice, or email)
 * that Incident Manager uses to engage a contact during an incident.
 *
 * ### Creating Contact Channels
 * **Example:** Email channel without activation
 * ```typescript
 * const email = yield* SSMContacts.ContactChannel("Email", {
 *   contactId: oncall.contactArn,
 *   type: "EMAIL",
 *   deliveryAddress: { SimpleAddress: "oncall@example.com" },
 *   deferActivation: true,
 * });
 * ```
 *
 * **Example:** SMS channel
 * ```typescript
 * const sms = yield* SSMContacts.ContactChannel("Sms", {
 *   contactId: oncall.contactArn,
 *   type: "SMS",
 *   deliveryAddress: { SimpleAddress: "+15551234567" },
 * });
 * ```
 */
const ContactChannelResource = Resource<ContactChannel>("AWS.SSMContacts.ContactChannel");

export { ContactChannelResource as ContactChannel };

export const ContactChannelProvider = () =>
  Provider.effect(
    ContactChannelResource,
    Effect.gen(function* () {
      const createName = Effect.fn(function* (id: string, props: { name?: string }) {
        return props.name ?? (yield* createPhysicalName({ id, maxLength: 200 }));
      });

      const getChannel = (arn: string) =>
        contacts
          .getContactChannel({ ContactChannelId: arn })
          .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));

      // A channel's ARN embeds a generated UUID, so without cached output we
      // fall back to searching the owning contact's channels by name + type.
      const findChannel = (contactId: string, name: string, type: string) =>
        contacts.listContactChannels.items({ ContactId: contactId }).pipe(
          Stream.filter((channel) => channel.Name === name && (channel.Type ?? type) === type),
          Stream.take(1),
          Stream.runCollect,
          Effect.map((chunk) => Array.from(chunk)[0]),
          Effect.catchTag("ResourceNotFoundException", () => Effect.undefined),
        );

      const buildAttrs = (channel: {
        ContactChannelArn: string;
        ContactArn: string;
        Name: string;
        Type?: string | undefined;
        ActivationStatus?: string | undefined;
      }) => ({
        contactChannelArn: channel.ContactChannelArn,
        contactArn: channel.ContactArn,
        name: channel.Name,
        type: channel.Type ?? "",
        activationStatus: channel.ActivationStatus,
      });

      return ContactChannelResource.Provider.of({
        stables: ["contactChannelArn", "contactArn", "type"],

        // Sub-resource keyed by its parent contact — enumeration across all
        // contacts is not meaningful here.
        list: () => Effect.succeed([]),

        read: Effect.fn(function* ({ id, olds, output }) {
          if (output !== undefined) {
            const channel = yield* getChannel(output.contactChannelArn);
            if (channel === undefined) return undefined;
            return buildAttrs(channel);
          }
          // No cached identifier — recover by searching the parent contact
          // from prior props. Channels are not taggable, so a match found
          // this way cannot prove ownership.
          if (olds?.contactId === undefined) return undefined;
          const name = yield* createName(id, olds);
          const found = yield* findChannel(olds.contactId, name, olds.type);
          return found === undefined ? undefined : Unowned(buildAttrs(found));
        }),

        // The owning contact and channel type are create-only; name and
        // delivery address update in place.
        diff: Effect.fn(function* ({ news, olds }) {
          if (!isResolved(news)) return undefined;
          if (olds.contactId !== news.contactId) {
            return { action: "replace" } as const;
          }
          if (olds.type !== news.type) return { action: "replace" } as const;
        }),

        reconcile: Effect.fn(function* ({ id, news, output, session }) {
          const name = output?.name ?? (yield* createName(id, news));

          // 1. OBSERVE — by cached ARN first, then by (contact, name, type).
          let channel = output ? yield* getChannel(output.contactChannelArn) : undefined;
          if (channel === undefined) {
            const found = yield* findChannel(news.contactId, name, news.type);
            if (found !== undefined) {
              channel = yield* getChannel(found.ContactChannelArn);
            }
          }

          // 2. ENSURE — create if missing; tolerate the already-exists race
          //    by re-searching.
          if (channel === undefined) {
            yield* session.note(`creating contact channel ${name}`);
            const arn = yield* contacts
              .createContactChannel({
                ContactId: news.contactId,
                Name: name,
                Type: news.type,
                DeliveryAddress: news.deliveryAddress,
                DeferActivation: news.deferActivation,
              })
              .pipe(
                Effect.map((r) => r.ContactChannelArn),
                Effect.catchTag("ConflictException", () =>
                  findChannel(news.contactId, name, news.type).pipe(
                    Effect.map((found) => found!.ContactChannelArn),
                  ),
                ),
              );
            channel = (yield* getChannel(arn))!;
          }

          // 3. SYNC name + delivery address — observed vs desired.
          const nameDelta = channel.Name !== name;
          const addressDelta =
            (channel.DeliveryAddress.SimpleAddress ?? "") !==
            (news.deliveryAddress.SimpleAddress ?? "");
          if (nameDelta || addressDelta) {
            yield* contacts.updateContactChannel({
              ContactChannelId: channel.ContactChannelArn,
              Name: name,
              DeliveryAddress: news.deliveryAddress,
            });
          }

          // 4. RETURN fresh attributes.
          const final = (yield* getChannel(channel.ContactChannelArn))!;
          yield* session.note(final.ContactChannelArn);
          return buildAttrs(final);
        }),

        delete: Effect.fn(function* ({ output }) {
          yield* contacts
            .deleteContactChannel({
              ContactChannelId: output.contactChannelArn,
            })
            .pipe(
              Effect.asVoid,
              Effect.catchTag("ResourceNotFoundException", () => Effect.void),
            );
        }),
      });
    }),
  );