sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ SSMContacts/ Contact.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 {
  createInternalTags,
  createTagsList,
  diffTags,
  hasAlchemyTags,
  tagRecord,
} 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";

/** The kind of contact: a person, an escalation plan, or an on-call schedule. */
export type ContactType = "PERSONAL" | "ESCALATION" | "ONCALL_SCHEDULE";

export interface ContactProps {
  /**
   * The unique, identifiable alias of the contact or escalation plan
   * (lowercase letters, numbers, `-`, `_`, `.`). Changing it replaces the
   * contact.
   *
   * @default ${app}-${id}-${stage}-${suffix} (lowercased)
   */
  alias?: string;

  /**
   * The full name of the contact or escalation plan.
   */
  displayName?: string;

  /**
   * `PERSONAL` for a single person, `ESCALATION` for an escalation plan that
   * engages contacts in phases, or `ONCALL_SCHEDULE` for a rotation-backed
   * schedule. Changing it replaces the contact.
   */
  type: ContactType;

  /**
   * The stages (engagement plan) that Incident Manager runs through when
   * engaging this contact. Stage targets are contact channels for `PERSONAL`
   * contacts and contacts for `ESCALATION` plans; `ONCALL_SCHEDULE` contacts
   * reference rotations via `RotationIds`.
   *
   * When omitted, an existing plan is left untouched so it can be managed by
   * the standalone `SSMContacts.Plan` resource.
   */
  plan?: contacts.Plan;

  /**
   * The contact's resource policy as a JSON policy document (string or
   * object) — shares the contact and its engagements with other accounts.
   * When omitted, any existing policy is left untouched (SSM Contacts has
   * no delete-policy API).
   */
  policy?: string | Record<string, unknown>;

  /**
   * Tags applied to the contact. Alchemy ownership tags are merged in
   * automatically.
   */
  tags?: Record<string, string>;
}

/** @resource */
export interface Contact extends Resource<
  "AWS.SSMContacts.Contact",
  ContactProps,
  {
    /** ARN of the contact. */
    contactArn: string;
    /** Alias of the contact. */
    alias: string;
    /** The contact type. */
    type: string;
    /** Display name of the contact. */
    displayName: string | undefined;
  },
  never,
  Providers
> {}

/**
 * An Incident Manager contact — a person Incident Manager engages during an
 * incident, an escalation plan that engages contacts in phases, or an
 * on-call schedule backed by rotations.
 *
 * Requires the account's Incident Manager replication set
 * (`SSMIncidents.ReplicationSet`) to exist.
 *
 * ### Creating Contacts
 * **Example:** Personal contact
 * ```typescript
 * const oncall = yield* SSMContacts.Contact("Oncall", {
 *   type: "PERSONAL",
 *   displayName: "Primary On-Call",
 * });
 * ```
 *
 * **Example:** Contact with an inline engagement plan
 * ```typescript
 * const channel = yield* SSMContacts.ContactChannel("Email", {
 *   contactId: oncall.contactArn,
 *   type: "EMAIL",
 *   deliveryAddress: { SimpleAddress: "oncall@example.com" },
 *   deferActivation: true,
 * });
 * const escalation = yield* SSMContacts.Contact("Escalation", {
 *   type: "ESCALATION",
 *   plan: {
 *     Stages: [
 *       {
 *         DurationInMinutes: 5,
 *         Targets: [
 *           { ContactTargetInfo: { ContactId: oncall.contactArn, IsEssential: true } },
 *         ],
 *       },
 *     ],
 *   },
 * });
 * ```
 */
const ContactResource = Resource<Contact>("AWS.SSMContacts.Contact");

export { ContactResource as Contact };

const normalize = (value: unknown): unknown => {
  if (Array.isArray(value)) return value.map(normalize);
  if (value !== null && typeof value === "object") {
    return Object.fromEntries(
      Object.entries(value as Record<string, unknown>)
        .filter(([, v]) => v !== undefined)
        .sort(([l], [r]) => l.localeCompare(r))
        .map(([k, v]) => [k, normalize(v)]),
    );
  }
  return value;
};
const same = (l: unknown, r: unknown) =>
  JSON.stringify(normalize(l)) === JSON.stringify(normalize(r));

/** Parse a policy JSON string for structural comparison; fall back to the raw string. */
const parsePolicy = (policy: string): unknown => {
  try {
    return JSON.parse(policy);
  } catch {
    return policy;
  }
};

/** Builds the ARN of a contact from its alias in the ambient account/region. */
export const contactArn = Effect.fn(function* (alias: string) {
  const { accountId, region } = yield* AWSEnvironment.current;
  return `arn:aws:ssm-contacts:${region}:${accountId}:contact/${alias}`;
});

export const ContactProvider = () =>
  Provider.effect(
    ContactResource,
    Effect.gen(function* () {
      const createAlias = Effect.fn(function* (id: string, props: { alias?: string }) {
        // Contact aliases must be lowercase.
        return props.alias ?? (yield* createPhysicalName({ id, maxLength: 200, lowercase: true }));
      });

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

      const readTags = (arn: string) =>
        contacts.listTagsForResource({ ResourceARN: arn }).pipe(
          // Distilled Tag has optional Key/Value; narrow to defined pairs
          // before handing off to the shared tagRecord helper.
          Effect.map((r) =>
            tagRecord(
              (r.Tags ?? []).flatMap((t) =>
                t.Key !== undefined && t.Value !== undefined
                  ? [{ Key: t.Key, Value: t.Value }]
                  : [],
              ),
            ),
          ),
          Effect.orElseSucceed(() => ({})),
        );

      const buildAttrs = (contact: contacts.GetContactResult) => ({
        contactArn: contact.ContactArn,
        alias: contact.Alias,
        type: contact.Type as string,
        displayName: contact.DisplayName,
      });

      return ContactResource.Provider.of({
        stables: ["contactArn", "alias", "type"],

        list: () =>
          contacts.listContacts.items({}).pipe(
            Stream.runCollect,
            Effect.map((chunk) =>
              Array.from(chunk).map((contact) => ({
                contactArn: contact.ContactArn,
                alias: contact.Alias,
                type: contact.Type as string,
                displayName: contact.DisplayName,
              })),
            ),
          ),

        read: Effect.fn(function* ({ id, olds, output }) {
          const alias = output?.alias ?? (yield* createAlias(id, olds ?? {}));
          const arn = output?.contactArn ?? (yield* contactArn(alias));
          const contact = yield* getContact(arn);
          if (contact === undefined) return undefined;
          const attrs = buildAttrs(contact);
          const tags = yield* readTags(contact.ContactArn);
          return (yield* hasAlchemyTags(id, tags)) ? attrs : Unowned(attrs);
        }),

        // Alias and type are create-only; display name, plan, and tags update
        // in place.
        diff: Effect.fn(function* ({ id, news, olds }) {
          if (!isResolved(news)) return undefined;
          const oldAlias = yield* createAlias(id, olds);
          const newAlias = yield* createAlias(id, news);
          if (oldAlias !== newAlias) return { action: "replace" } as const;
          if (olds.type !== news.type) return { action: "replace" } as const;
        }),

        reconcile: Effect.fn(function* ({ id, news, output, session }) {
          const alias = output?.alias ?? (yield* createAlias(id, news));
          const arn = output?.contactArn ?? (yield* contactArn(alias));
          const internalTags = yield* createInternalTags(id);
          const desiredTags = { ...news.tags, ...internalTags };

          // 1. OBSERVE
          let contact = yield* getContact(arn);

          // 2. ENSURE — create if missing; tolerate the already-exists race.
          if (contact === undefined) {
            yield* session.note(`creating contact ${alias}`);
            yield* contacts
              .createContact({
                Alias: alias,
                DisplayName: news.displayName,
                Type: news.type,
                Plan: news.plan ?? { Stages: [] },
                Tags: createTagsList(desiredTags),
              })
              .pipe(
                Effect.asVoid,
                Effect.catchTag("ConflictException", () => Effect.void),
              );
            contact = (yield* getContact(arn))!;
          }

          // 3. SYNC display name + plan — diff observed against desired.
          //    `plan` is only managed here when the prop is provided, so the
          //    standalone `SSMContacts.Plan` resource can own it otherwise.
          const displayNameDelta = (contact.DisplayName ?? "") !== (news.displayName ?? "");
          const planDelta = news.plan !== undefined && !same(contact.Plan, news.plan);
          if (displayNameDelta || planDelta) {
            yield* contacts.updateContact({
              ContactId: contact.ContactArn,
              DisplayName: news.displayName ?? "",
              ...(planDelta ? { Plan: news.plan } : {}),
            });
          }

          // 3b. SYNC resource policy — observed vs desired. Only managed
          //     when the prop is provided; there is no delete-policy API.
          if (news.policy !== undefined) {
            const desiredPolicy =
              typeof news.policy === "string" ? news.policy : JSON.stringify(news.policy);
            const observedPolicy = yield* contacts
              .getContactPolicy({ ContactArn: contact.ContactArn })
              .pipe(
                Effect.map((r) => r.Policy),
                Effect.catchTag("ResourceNotFoundException", () => Effect.undefined),
              );
            if (
              observedPolicy === undefined ||
              !same(parsePolicy(observedPolicy), parsePolicy(desiredPolicy))
            ) {
              yield* contacts.putContactPolicy({
                ContactArn: contact.ContactArn,
                Policy: desiredPolicy,
              });
            }
          }

          // 3c. SYNC tags — diff against OBSERVED cloud tags.
          const currentTags = yield* readTags(contact.ContactArn);
          const { upsert, removed } = diffTags(currentTags, desiredTags);
          if (upsert.length > 0) {
            yield* contacts.tagResource({
              ResourceARN: contact.ContactArn,
              Tags: upsert,
            });
          }
          if (removed.length > 0) {
            yield* contacts.untagResource({
              ResourceARN: contact.ContactArn,
              TagKeys: removed,
            });
          }

          // 4. RETURN fresh attributes.
          const final = (yield* getContact(contact.ContactArn))!;
          yield* session.note(final.ContactArn);
          return buildAttrs(final);
        }),

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