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

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

/**
 * Whether SES requires (`REQUIRE`) or merely prefers (`OPTIONAL`) a TLS
 * connection when delivering email through this configuration set.
 */
export type TlsPolicy = "REQUIRE" | "OPTIONAL";

/**
 * The reasons for which SES automatically adds recipients to the account
 * suppression list when sending through this configuration set.
 */
export type SuppressionListReason = "BOUNCE" | "COMPLAINT";

export interface ConfigurationSetTrackingSettings {
  /**
   * A custom domain — a verified subdomain you own, with a valid certificate —
   * that SES uses to host open- and click-tracking links for email sent
   * through this configuration set.
   *
   * Required: SES has no way to set an HTTPS policy for the default tracking
   * domain, so `httpsPolicy` is only meaningful alongside a custom domain.
   */
  customRedirectDomain: string;
  /**
   * Whether tracking links use HTTPS (`REQUIRE`), plain HTTP (`OPTIONAL`), or
   * HTTPS only for the open pixel (`REQUIRE_OPEN_ONLY`).
   */
  httpsPolicy?: sesv2.HttpsPolicy;
}

export interface ConfigurationSetVdmSettings {
  /**
   * Whether SES collects engagement (open/click) metrics for the Virtual
   * Deliverability Manager dashboard for email sent through this configuration
   * set.
   */
  dashboardEngagementMetrics?: sesv2.FeatureStatus;
  /**
   * Whether SES applies Guardian optimized shared delivery to email sent
   * through this configuration set.
   */
  guardianOptimizedSharedDelivery?: sesv2.FeatureStatus;
}

export interface ConfigurationSetProps {
  /**
   * The name of the configuration set. May contain letters, numbers, hyphens
   * 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 configuration set.
   */
  configurationSetName?: string;
  /**
   * Whether email sending through this configuration set is enabled.
   * @default true
   */
  sendingEnabled?: boolean;
  /**
   * Whether SES publishes reputation metrics (bounce and complaint rates)
   * for this configuration set to CloudWatch.
   * @default false
   */
  reputationMetricsEnabled?: boolean;
  /**
   * Whether SES requires a TLS connection when delivering email through
   * this configuration set. Messages are dropped when `REQUIRE` is set and
   * TLS cannot be established.
   * @default "OPTIONAL"
   */
  tlsPolicy?: TlsPolicy;
  /**
   * The maximum amount of time (5 minutes to 14 hours) that SES will attempt
   * delivery of email through this configuration set. Accepts any
   * `Duration.Input` (e.g. `"1 hour"`, `Duration.hours(1)`; a bare number
   * is milliseconds); the wire unit is whole seconds.
   */
  maxDelivery?: Duration.Input;
  /**
   * Which events cause SES to add a recipient to the account suppression
   * list when sending through this configuration set. Overrides the
   * account-level setting; leave undefined to inherit it.
   */
  suppressedReasons?: SuppressionListReason[];
  /**
   * Open- and click-tracking configuration. Leave undefined to keep whatever
   * SES currently has.
   *
   * Members cannot be unset once set: SES exposes no API to remove a custom
   * redirect domain, so dropping this prop keeps the current state rather
   * than restoring the default SES tracking domain.
   */
  tracking?: ConfigurationSetTrackingSettings;
  /**
   * Virtual Deliverability Manager configuration for this configuration set.
   * Requires account-level VDM to be enabled — see `SES.AccountSettings`.
   *
   * Members cannot be unset once set: dropping this prop keeps the current
   * state rather than clearing it. A member you do omit while managing its
   * sibling is preserved (SES replaces VdmOptions wholesale, so the
   * unmanaged member is backfilled from observed state).
   */
  vdm?: ConfigurationSetVdmSettings;
  /**
   * Tags to apply to the configuration set. Merged with internal Alchemy
   * tags.
   */
  tags?: Record<string, string>;
}

export interface ConfigurationSet extends Resource<
  "AWS.SES.ConfigurationSet",
  ConfigurationSetProps,
  {
    configurationSetName: string;
    configurationSetArn: string;
    /**
     * Sending, reputation and delivery options, the declared suppression,
     * tracking and VDM options, and the tags, as observed. Lets
     * `alchemy drift` detect out-of-band changes.
     */
    configuration?: Record<string, unknown>;
  },
  never,
  Providers
> {}

/**
 * An Amazon SES v2 configuration set — a named group of sending options
 * (TLS policy, reputation metrics, suppression overrides) that you apply to
 * outbound email, either per-message or as an identity's default.
 *
 * Attach event destinations with `SES.ConfigurationSetEventDestination` to
 * stream send/delivery/bounce/complaint events to SNS, EventBridge, or
 * CloudWatch.
 * ### Creating Configuration Sets
 * **Example:** Basic Configuration Set
 * ```typescript
 * import * as SES from "@alchemy.run/aws/SES";
 *
 * const configSet = yield* SES.ConfigurationSet("Default", {});
 * ```
 *
 * **Example:** Require TLS and Publish Reputation Metrics
 * ```typescript
 * const configSet = yield* SES.ConfigurationSet("Strict", {
 *   tlsPolicy: "REQUIRE",
 *   reputationMetricsEnabled: true,
 * });
 * ```
 *
 * **Example:** Suppress Bounces and Complaints
 * ```typescript
 * const configSet = yield* SES.ConfigurationSet("Suppressing", {
 *   suppressedReasons: ["BOUNCE", "COMPLAINT"],
 * });
 * ```
 *
 * ### Open and Click Tracking
 * **Example:** Host Tracking Links on Your Own Domain
 * ```typescript
 * // The redirect domain must be a verified subdomain you own with a valid
 * // certificate. Omit `tracking` entirely to keep SES's current setting.
 * const configSet = yield* SES.ConfigurationSet("Tracked", {
 *   tracking: {
 *     customRedirectDomain: "links.example.com",
 *     httpsPolicy: "REQUIRE",
 *   },
 * });
 * ```
 *
 * ### Virtual Deliverability Manager
 * **Example:** Collect Engagement Metrics for This Configuration Set
 * ```typescript
 * // Requires account-level VDM — see SES.AccountSettings.
 * const configSet = yield* SES.ConfigurationSet("Measured", {
 *   vdm: {
 *     dashboardEngagementMetrics: "ENABLED",
 *     guardianOptimizedSharedDelivery: "ENABLED",
 *   },
 * });
 * ```
 *
 * ### Event Destinations
 * **Example:** Stream Events to SNS
 * ```typescript
 * const topic = yield* SNS.Topic("EmailEvents", {});
 * const destination = yield* SES.ConfigurationSetEventDestination("ToSns", {
 *   configurationSetName: configSet.configurationSetName,
 *   matchingEventTypes: ["SEND", "DELIVERY", "BOUNCE", "COMPLAINT"],
 *   snsDestination: { topicArn: topic.topicArn },
 * });
 * ```
 *
 * @resource
 */
export const ConfigurationSet = Resource<ConfigurationSet>("AWS.SES.ConfigurationSet");

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

const configurationSetArnOf = (region: string, accountId: string, name: string) =>
  `arn:aws:ses:${region}:${accountId}:configuration-set/${name}`;

const sameReasons = (a: ReadonlyArray<string> | undefined, b: ReadonlyArray<string>) => {
  const left = [...(a ?? [])].sort();
  const right = [...b].sort();
  return left.length === right.length && left.every((v, i) => v === right[i]);
};

/**
 * The options reconcile converges, as observed. Options reconcile only
 * applies when declared are only observed when declared. `read` and
 * `reconcile` share it so a converged configuration set reads unchanged.
 */
const observeConfigurationSetOptions = (
  observed: sesv2.GetConfigurationSetResponse,
  props: ConfigurationSetProps | undefined,
) => ({
  sendingEnabled: observed.SendingOptions?.SendingEnabled ?? true,
  reputationMetricsEnabled: observed.ReputationOptions?.ReputationMetricsEnabled ?? false,
  tlsPolicy: observed.DeliveryOptions?.TlsPolicy ?? "OPTIONAL",
  maxDeliverySeconds:
    props?.maxDelivery === undefined ? undefined : observed.DeliveryOptions?.MaxDeliverySeconds,
  suppressedReasons:
    props?.suppressedReasons === undefined
      ? undefined
      : [...(observed.SuppressionOptions?.SuppressedReasons ?? [])].sort(),
  tracking:
    props?.tracking === undefined
      ? undefined
      : {
          customRedirectDomain: observed.TrackingOptions?.CustomRedirectDomain,
          httpsPolicy:
            props.tracking.httpsPolicy === undefined
              ? undefined
              : observed.TrackingOptions?.HttpsPolicy,
        },
  vdm:
    props?.vdm === undefined
      ? undefined
      : {
          dashboardEngagementMetrics: observed.VdmOptions?.DashboardOptions?.EngagementMetrics,
          guardianOptimizedSharedDelivery:
            observed.VdmOptions?.GuardianOptions?.OptimizedSharedDelivery,
        },
  tags: toTagRecord(observed.Tags),
});

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

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

      return ConfigurationSet.Provider.of({
        stables: ["configurationSetName", "configurationSetArn"],

        list: () =>
          Effect.gen(function* () {
            const { accountId, region } = yield* AWSEnvironment.current;
            const pages = yield* sesv2.listConfigurationSets.pages({}).pipe(Stream.runCollect);
            return Array.from(pages)
              .flatMap((page) => page.ConfigurationSets ?? [])
              .map((name) => ({
                configurationSetName: name,
                configurationSetArn: configurationSetArnOf(region, accountId, name),
              }));
          }),

        read: Effect.fn(function* ({ id, olds, output }) {
          const { accountId, region } = yield* AWSEnvironment.current;
          const name = output?.configurationSetName ?? (yield* createName(id, olds ?? {}));
          const found = yield* getConfigurationSet(name);
          if (!found) return undefined;
          const attrs = {
            configurationSetName: name,
            configurationSetArn: configurationSetArnOf(region, accountId, name),
            configuration: observeConfigurationSetOptions(found, olds),
          };
          const tags = toTagRecord(found.Tags);
          return (yield* hasAlchemyTags(id, tags)) ? attrs : Unowned(attrs);
        }),

        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) {
            return { action: "replace" } as const;
          }
        }),

        reconcile: Effect.fn(function* ({ id, news, output, session }) {
          const { accountId, region } = yield* AWSEnvironment.current;
          const name = output?.configurationSetName ?? (yield* createName(id, news));
          const configurationSetArn = configurationSetArnOf(region, accountId, name);
          const internalTags = yield* createInternalTags(id);
          const desiredTags = { ...news.tags, ...internalTags };
          const desiredMaxDelivery = toWireSeconds(news.maxDelivery);

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

          // 2. ENSURE — create with the full desired option set in one call;
          //    AlreadyExists is a race, not a failure.
          if (observed === undefined) {
            yield* sesv2
              .createConfigurationSet({
                ConfigurationSetName: name,
                SendingOptions:
                  news.sendingEnabled !== undefined
                    ? { SendingEnabled: news.sendingEnabled }
                    : undefined,
                ReputationOptions:
                  news.reputationMetricsEnabled !== undefined
                    ? {
                        ReputationMetricsEnabled: news.reputationMetricsEnabled,
                      }
                    : undefined,
                DeliveryOptions:
                  news.tlsPolicy !== undefined || desiredMaxDelivery !== undefined
                    ? {
                        TlsPolicy: news.tlsPolicy,
                        MaxDeliverySeconds: desiredMaxDelivery,
                      }
                    : undefined,
                SuppressionOptions:
                  news.suppressedReasons !== undefined
                    ? { SuppressedReasons: news.suppressedReasons }
                    : undefined,
                Tags: createTagsList(desiredTags),
              })
              .pipe(Effect.catchTag("AlreadyExistsException", () => Effect.succeed({})));
            observed = yield* sesv2.getConfigurationSet({
              ConfigurationSetName: name,
            });
          }

          // 3. SYNC — per mutable aspect: diff observed against desired and
          //    apply only the delta.
          const desiredSending = news.sendingEnabled ?? true;
          if ((observed.SendingOptions?.SendingEnabled ?? true) !== desiredSending) {
            yield* sesv2.putConfigurationSetSendingOptions({
              ConfigurationSetName: name,
              SendingEnabled: desiredSending,
            });
          }

          const desiredReputation = news.reputationMetricsEnabled ?? false;
          if (
            (observed.ReputationOptions?.ReputationMetricsEnabled ?? false) !== desiredReputation
          ) {
            yield* sesv2.putConfigurationSetReputationOptions({
              ConfigurationSetName: name,
              ReputationMetricsEnabled: desiredReputation,
            });
          }

          const desiredTls = news.tlsPolicy ?? "OPTIONAL";
          const observedTls = observed.DeliveryOptions?.TlsPolicy ?? "OPTIONAL";
          const observedMaxDelivery = observed.DeliveryOptions?.MaxDeliverySeconds;
          if (
            observedTls !== desiredTls ||
            (desiredMaxDelivery !== undefined && observedMaxDelivery !== desiredMaxDelivery)
          ) {
            yield* sesv2.putConfigurationSetDeliveryOptions({
              ConfigurationSetName: name,
              TlsPolicy: desiredTls,
              MaxDeliverySeconds: desiredMaxDelivery ?? observedMaxDelivery,
              // preserve any dedicated sending pool configured out-of-band
              SendingPoolName: observed.DeliveryOptions?.SendingPoolName,
            });
          }

          // Suppression is only synced when explicitly configured so an
          // unset prop keeps inheriting the account-level defaults.
          if (
            news.suppressedReasons !== undefined &&
            !sameReasons(observed.SuppressionOptions?.SuppressedReasons, news.suppressedReasons)
          ) {
            yield* sesv2.putConfigurationSetSuppressionOptions({
              ConfigurationSetName: name,
              SuppressedReasons: news.suppressedReasons,
            });
          }

          // Tracking is only synced when the caller manages it; leaving the
          // prop undefined keeps whatever SES currently has. `httpsPolicy`
          // cannot drift on its own — the type requires a custom domain
          // alongside it, because SES has no way to set an HTTPS policy for
          // the default tracking domain.
          if (
            news.tracking !== undefined &&
            (observed.TrackingOptions?.CustomRedirectDomain !==
              news.tracking.customRedirectDomain ||
              (news.tracking.httpsPolicy !== undefined &&
                observed.TrackingOptions?.HttpsPolicy !== news.tracking.httpsPolicy))
          ) {
            yield* sesv2.putConfigurationSetTrackingOptions({
              ConfigurationSetName: name,
              CustomRedirectDomain: news.tracking.customRedirectDomain,
              HttpsPolicy: news.tracking.httpsPolicy,
            });
          }

          // VDM is only synced when explicitly configured; it requires
          // account-level VDM to be enabled.
          //
          // putConfigurationSetVdmOptions REPLACES VdmOptions wholesale: an
          // omitted DashboardOptions/GuardianOptions is dropped, not left
          // alone (verified against the live API). So a caller who manages
          // only one of the two would silently wipe the other on every
          // deploy. Backfill the unmanaged member from observed state.
          const desiredDashboard =
            news.vdm?.dashboardEngagementMetrics ??
            observed.VdmOptions?.DashboardOptions?.EngagementMetrics;
          const desiredGuardian =
            news.vdm?.guardianOptimizedSharedDelivery ??
            observed.VdmOptions?.GuardianOptions?.OptimizedSharedDelivery;
          if (
            news.vdm !== undefined &&
            (observed.VdmOptions?.DashboardOptions?.EngagementMetrics !== desiredDashboard ||
              observed.VdmOptions?.GuardianOptions?.OptimizedSharedDelivery !== desiredGuardian)
          ) {
            yield* sesv2.putConfigurationSetVdmOptions({
              ConfigurationSetName: name,
              VdmOptions: {
                DashboardOptions:
                  desiredDashboard !== undefined
                    ? { EngagementMetrics: desiredDashboard }
                    : undefined,
                GuardianOptions:
                  desiredGuardian !== undefined
                    ? { OptimizedSharedDelivery: desiredGuardian }
                    : undefined,
              },
            });
          }

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

          yield* session.note(configurationSetArn);
          const final = yield* sesv2.getConfigurationSet({ ConfigurationSetName: name });
          return {
            configurationSetName: name,
            configurationSetArn,
            configuration: {
              ...observeConfigurationSetOptions(final, news),
              tags: desiredTags,
            },
          };
        }),

        delete: Effect.fn(function* ({ output }) {
          yield* sesv2
            .deleteConfigurationSet({
              ConfigurationSetName: output.configurationSetName,
            })
            .pipe(Effect.catchTag("NotFoundException", () => Effect.void));
        }),
      });
    }),
  );