sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ SES/ ContactList.ts

import * as sesv2 from "@distilled.cloud/aws/sesv2";
import { unownedUnlessPrevious } 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 } from "alchemy/Tags";
import * as Effect from "effect/Effect";
import * as Schedule from "effect/Schedule";
import * as Stream from "effect/Stream";
import { AWSEnvironment } from "../Environment.ts";
import type { Providers } from "../Providers.ts";

/**
 * A subscription topic on a contact list. Pass the distilled shape directly:
 * `TopicName` (the stable id), `DisplayName`, an optional `Description`, and a
 * `DefaultSubscriptionStatus` of `"OPT_IN"` or `"OPT_OUT"`.
 */
export type ContactListTopic = sesv2.Topic;

export interface ContactListProps {
  /**
   * Name of the contact list. May contain letters, numbers, dashes and
   * underscores, up to 64 characters. If omitted, a deterministic physical
   * name is generated from the app, stage, and logical ID. Changing the name
   * replaces the contact list.
   */
  contactListName?: string;
  /**
   * A human-readable description of the contact list. Leave undefined to keep
   * whatever SES currently has.
   */
  description?: string;
  /**
   * The interest topics contacts can subscribe to. Replaced wholesale when
   * set — pass the full desired set. Leave undefined to keep whatever SES
   * currently has.
   */
  topics?: ContactListTopic[];
  /**
   * Tags to apply to the contact list. Merged with internal Alchemy tags.
   */
  tags?: Record<string, string>;
}

export interface ContactList extends Resource<
  "AWS.SES.ContactList",
  ContactListProps,
  {
    /** Name of the contact list. */
    contactListName: string;
    /** ARN of the contact list. */
    contactListArn: string;
  },
  never,
  Providers
> {}

/**
 * An Amazon SES v2 contact list — a named audience of email contacts with
 * subscription topics, used with SES's list-management and unsubscribe
 * handling.
 *
 * Add contacts with `SES.Contact`. Deleting the list deletes all of its
 * contacts.
 *
 * SES allows only **one contact list per AWS account**, so renaming a list
 * replaces it by deleting the old list (and its contacts) before creating the
 * new one — a create-then-delete replacement would exceed the account limit.
 * ### Creating Contact Lists
 * **Example:** Basic Contact List
 * ```typescript
 * import * as SES from "@alchemy.run/aws/SES";
 *
 * const list = yield* SES.ContactList("Newsletter", {
 *   description: "Weekly product newsletter",
 * });
 * ```
 *
 * **Example:** Contact List with Topics
 * ```typescript
 * const list = yield* SES.ContactList("Newsletter", {
 *   topics: [
 *     {
 *       TopicName: "product-updates",
 *       DisplayName: "Product Updates",
 *       DefaultSubscriptionStatus: "OPT_IN",
 *     },
 *     {
 *       TopicName: "promotions",
 *       DisplayName: "Promotions",
 *       DefaultSubscriptionStatus: "OPT_OUT",
 *     },
 *   ],
 * });
 * ```
 *
 * **Example:** Contact List with Tags
 * ```typescript
 * const list = yield* SES.ContactList("Newsletter", {
 *   tags: { Team: "growth", Environment: "prod" },
 * });
 * ```
 *
 * ### Populating the List
 * **Example:** Add Contacts to the List
 * ```typescript
 * const list = yield* SES.ContactList("Newsletter", {
 *   topics: [
 *     {
 *       TopicName: "product-updates",
 *       DisplayName: "Product Updates",
 *       DefaultSubscriptionStatus: "OPT_IN",
 *     },
 *   ],
 * });
 *
 * for (const email of ["a@example.com", "b@example.com"]) {
 *   yield* SES.Contact(`Subscriber-${email}`, {
 *     contactListName: list.contactListName,
 *     emailAddress: email,
 *     topicPreferences: [
 *       { TopicName: "product-updates", SubscriptionStatus: "OPT_IN" },
 *     ],
 *   });
 * }
 * ```
 *
 * @resource
 */
export const ContactList = Resource<ContactList>("AWS.SES.ContactList");

const toTagRecord = (
  tags: ReadonlyArray<{ Key: string; Value: string }> | undefined,
): Record<string, string> => Object.fromEntries((tags ?? []).map((tag) => [tag.Key, tag.Value]));

const contactListArnOf = (region: string, accountId: string, name: string) =>
  `arn:aws:ses:${region}:${accountId}:contact-list/${name}`;

const sameTopics = (
  a: ReadonlyArray<ContactListTopic> | undefined,
  b: ReadonlyArray<ContactListTopic> | undefined,
): boolean => {
  const key = (topics: ReadonlyArray<ContactListTopic> | undefined) =>
    JSON.stringify(
      [...(topics ?? [])]
        .map((t) => ({
          TopicName: t.TopicName,
          DisplayName: t.DisplayName,
          Description: t.Description,
          DefaultSubscriptionStatus: t.DefaultSubscriptionStatus,
        }))
        .sort((x, y) => x.TopicName.localeCompare(y.TopicName)),
    );
  return key(a) === key(b);
};

export const ContactListProvider = () =>
  Provider.effect(
    ContactList,
    Effect.gen(function* () {
      const createName = Effect.fn(function* (
        id: string,
        props: Pick<ContactListProps, "contactListName">,
      ) {
        return props.contactListName ?? (yield* createPhysicalName({ id, maxLength: 64 }));
      });

      const getList = Effect.fn(function* (name: string) {
        return yield* sesv2
          .getContactList({ ContactListName: name })
          .pipe(Effect.catchTag("NotFoundException", () => Effect.undefined));
      });

      return ContactList.Provider.of({
        stables: ["contactListName", "contactListArn"],

        list: Effect.fn(function* () {
          const { accountId, region } = yield* AWSEnvironment.current;
          const pages = yield* sesv2.listContactLists.pages({}).pipe(Stream.runCollect);
          return Array.from(pages)
            .flatMap((page) => page.ContactLists ?? [])
            .flatMap((entry) =>
              entry.ContactListName
                ? [
                    {
                      contactListName: entry.ContactListName,
                      contactListArn: contactListArnOf(region, accountId, entry.ContactListName),
                    },
                  ]
                : [],
            );
        }),

        read: Effect.fn(function* ({ id, olds, output, previous }) {
          const { accountId, region } = yield* AWSEnvironment.current;
          const name = output?.contactListName ?? (yield* createName(id, olds ?? {}));
          const found = yield* getList(name);
          if (!found) return undefined;
          const attrs = {
            contactListName: name,
            contactListArn: contactListArnOf(region, accountId, name),
          };
          const tags = toTagRecord(found.Tags);
          return (yield* hasAlchemyTags(id, tags))
            ? attrs
            : unownedUnlessPrevious(attrs, previous, "contactListName");
        }),

        diff: Effect.fn(function* ({ id, news, olds }) {
          if (!isResolved(news)) return undefined;
          const oldName = yield* createName(id, olds ?? {});
          const newName = yield* createName(id, news ?? {});
          if (oldName !== newName) {
            // Only one contact list is allowed per account, so the old list
            // has to go before the new one can be created.
            return { action: "replace", deleteFirst: true } as const;
          }
        }),

        reconcile: Effect.fn(function* ({ id, news, output, session }) {
          const { accountId, region } = yield* AWSEnvironment.current;
          const name = output?.contactListName ?? (yield* createName(id, news));
          const contactListArn = contactListArnOf(region, accountId, name);
          const internalTags = yield* createInternalTags(id);
          const desiredTags = { ...news.tags, ...internalTags };

          // 1. OBSERVE — cloud state is authoritative.
          let observed = yield* getList(name);

          if (observed === undefined) {
            // 2. ENSURE — create with the full desired set; AlreadyExists is a
            //    race → converge via update.
            yield* sesv2
              .createContactList({
                ContactListName: name,
                Description: news.description,
                Topics: news.topics,
                Tags: createTagsList(desiredTags),
              })
              .pipe(
                Effect.catchTag("AlreadyExistsException", () =>
                  sesv2.updateContactList({
                    ContactListName: name,
                    Description: news.description,
                    Topics: news.topics,
                  }),
                ),
              );
            // getList tolerates NotFound; the list is not always readable the
            // instant create returns, and on the AlreadyExists race another
            // writer may still be mid-create.
            observed = (yield* getList(name).pipe(
              Effect.repeat({
                schedule: Schedule.spaced("1 second"),
                until: (list) => list !== undefined,
                times: 8,
              }),
            ))!;
          } else {
            // 3. SYNC — only the aspects the caller manages. An omitted prop
            //    keeps whatever SES currently has, matching every sibling
            //    resource in this service; updateContactList replaces each
            //    field it is given, so observed values are echoed back for the
            //    fields we are not managing.
            const managesDescription = news.description !== undefined;
            const managesTopics = news.topics !== undefined;
            const descriptionChanged =
              managesDescription && observed.Description !== news.description;
            const topicsChanged = managesTopics && !sameTopics(observed.Topics, news.topics);

            if (descriptionChanged || topicsChanged) {
              yield* sesv2.updateContactList({
                ContactListName: name,
                Description: managesDescription ? news.description : observed.Description,
                Topics: managesTopics ? news.topics : observed.Topics,
              });
            }
          }

          // 3b. SYNC TAGS — diff against OBSERVED cloud tags so adoption
          //     converges.
          const observedTags = toTagRecord(observed.Tags);
          const { upsert, removed } = diffTags(observedTags, desiredTags);
          if (upsert.length > 0) {
            yield* sesv2.tagResource({
              ResourceArn: contactListArn,
              Tags: upsert,
            });
          }
          if (removed.length > 0) {
            yield* sesv2.untagResource({
              ResourceArn: contactListArn,
              TagKeys: removed,
            });
          }

          yield* session.note(contactListArn);
          return { contactListName: name, contactListArn };
        }),

        delete: Effect.fn(function* ({ output }) {
          // deleteContactList removes the list and all of its contacts, and is
          // idempotent for a missing list.
          yield* sesv2
            .deleteContactList({ ContactListName: output.contactListName })
            .pipe(Effect.catchTag("NotFoundException", () => Effect.void));
        }),
      });
    }),
  );