sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ SES/ Tenant.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 * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as Schedule from "effect/Schedule";
import * as Stream from "effect/Stream";
import type { Providers } from "../Providers.ts";
import type { SuppressionListReason } from "./ConfigurationSet.ts";

export class TenantUnexpectedResponse extends Data.TaggedError("TenantUnexpectedResponse")<{
  readonly message: string;
  readonly cause?: unknown;
}> {}

/**
 * The scope of the tenant's suppression list: `ACCOUNT` shares the
 * account-level suppression list, `TENANT` maintains a separate list scoped to
 * this tenant.
 */
export type SuppressionListScope = sesv2.SuppressionListScope;

export interface TenantSuppressionSettings {
  /**
   * The bounce/complaint reasons for which SES adds destinations to the
   * tenant's suppression list.
   */
  reasons: SuppressionListReason[];
  /**
   * Whether the tenant uses the account-level suppression list (`ACCOUNT`) or
   * maintains its own tenant-scoped list (`TENANT`).
   */
  scope: SuppressionListScope;
}

export interface TenantProps {
  /**
   * Name of the tenant. If omitted, a deterministic physical name is generated
   * from the app, stage, and logical ID. Changing the name replaces the
   * tenant.
   */
  tenantName?: string;
  /**
   * The tenant's suppression list configuration, synced in place via
   * `putTenantSuppressionAttributes`. Leave undefined to keep SES's current
   * setting.
   *
   * `reasons` and `scope` are both required together: SES rejects a
   * suppression update carrying only one of them
   * (`BadRequestException: SuppressedReasons cannot be specified without
   * SuppressionScope`, and vice versa).
   */
  suppression?: TenantSuppressionSettings;
  /**
   * Tags to apply to the tenant. Merged with internal Alchemy tags.
   */
  tags?: Record<string, string>;
}

export interface Tenant extends Resource<
  "AWS.SES.Tenant",
  TenantProps,
  {
    /** Name of the tenant. */
    tenantName: string;
    /** Opaque tenant identifier assigned by SES. */
    tenantId: string;
    /** ARN of the tenant. */
    tenantArn: string;
  },
  never,
  Providers
> {}

/**
 * An Amazon SES v2 tenant — a logical container that groups related SES
 * resources (email identities, configuration sets, templates) together, each
 * with its own reputation metrics, sending status, and optional
 * tenant-scoped suppression list. Useful for isolating email sending across
 * customers or business units within a single SES account.
 *
 * Associate resources with a tenant using `SES.TenantResourceAssociation`.
 * Deleting the tenant removes its resource associations but leaves the
 * underlying resources in place.
 * ### Creating Tenants
 * **Example:** Basic Tenant
 * ```typescript
 * import * as SES from "@alchemy.run/aws/SES";
 *
 * const tenant = yield* SES.Tenant("CustomerA", {});
 * ```
 *
 * **Example:** Tenant with a Scoped Suppression List
 * ```typescript
 * // SES requires the reasons and the scope together, so they travel as one
 * // prop rather than two independently-optional ones.
 * const tenant = yield* SES.Tenant("CustomerA", {
 *   suppression: { reasons: ["BOUNCE", "COMPLAINT"], scope: "TENANT" },
 * });
 * ```
 *
 * **Example:** Tenant with Tags
 * ```typescript
 * const tenant = yield* SES.Tenant("CustomerA", {
 *   tags: { Customer: "acme", CostCenter: "growth" },
 * });
 * ```
 *
 * ### Associating Resources
 * **Example:** Give the Tenant an Identity, Config Set, and Template
 * ```typescript
 * const tenant = yield* SES.Tenant("CustomerA", {});
 * const identity = yield* SES.EmailIdentity("Sender", {
 *   emailIdentity: "mail.acme.example.com",
 * });
 * const configSet = yield* SES.ConfigurationSet("AcmeTracking", {});
 *
 * // A resource must be associated before the tenant can send with it.
 * yield* SES.TenantResourceAssociation("AcmeIdentity", {
 *   tenantName: tenant.tenantName,
 *   resourceArn: identity.identityArn,
 * });
 * yield* SES.TenantResourceAssociation("AcmeConfigSet", {
 *   tenantName: tenant.tenantName,
 *   resourceArn: configSet.configurationSetArn,
 * });
 * ```
 *
 * ### Tenant Suppression Lists
 * **Example:** Read and Write the Tenant's Own Suppression List
 * ```typescript
 * // With scope "TENANT" the list is separate from the account's.
 * const tenant = yield* SES.Tenant("CustomerA", {
 *   suppression: { reasons: ["BOUNCE", "COMPLAINT"], scope: "TENANT" },
 * });
 *
 * // init — account-level bindings, scoped per call via TenantName
 * const suppress = yield* SES.PutSuppressedDestination();
 * const listSuppressed = yield* SES.ListSuppressedDestinations();
 *
 * // runtime
 * yield* suppress({
 *   EmailAddress: "hard-bounce@example.com",
 *   Reason: "BOUNCE",
 *   TenantName: yield* tenant.tenantName,
 * });
 * const { SuppressedDestinationSummaries } = yield* listSuppressed({
 *   TenantName: yield* tenant.tenantName,
 * });
 * ```
 *
 * @resource
 */
export const Tenant = Resource<Tenant>("AWS.SES.Tenant");

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

const sameReasons = (
  a: ReadonlyArray<sesv2.SuppressionListReason> | undefined,
  b: ReadonlyArray<sesv2.SuppressionListReason> | undefined,
): boolean => {
  const key = (reasons: ReadonlyArray<sesv2.SuppressionListReason> | undefined) =>
    JSON.stringify([...(reasons ?? [])].sort());
  return key(a) === key(b);
};

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

      const getTenant = Effect.fn(function* (name: string) {
        return yield* sesv2.getTenant({ TenantName: name }).pipe(
          Effect.map((response) => response.Tenant),
          Effect.catchTag("NotFoundException", () => Effect.undefined),
        );
      });

      return Tenant.Provider.of({
        stables: ["tenantName", "tenantId", "tenantArn"],

        // Account-scoped: enumerate every tenant so leaked test resources are
        // cleaned by nuke.
        list: Effect.fn(function* () {
          const pages = yield* sesv2.listTenants.pages({}).pipe(Stream.runCollect);
          return Array.from(pages)
            .flatMap((page) => page.Tenants ?? [])
            .flatMap((entry) =>
              entry.TenantName && entry.TenantId && entry.TenantArn
                ? [
                    {
                      tenantName: entry.TenantName,
                      tenantId: entry.TenantId,
                      tenantArn: entry.TenantArn,
                    },
                  ]
                : [],
            );
        }),

        read: Effect.fn(function* ({ id, olds, output }) {
          const name = output?.tenantName ?? (yield* createName(id, olds ?? {}));
          const found = yield* getTenant(name);
          if (!found || !found.TenantId || !found.TenantArn) return undefined;
          const attrs = {
            tenantName: name,
            tenantId: found.TenantId,
            tenantArn: found.TenantArn,
          };
          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 name = output?.tenantName ?? (yield* createName(id, news));
          const internalTags = yield* createInternalTags(id);
          const desiredTags = { ...news.tags, ...internalTags };

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

          if (observed === undefined) {
            // 2. ENSURE — create with the full desired set. AlreadyExists is a
            //    race → fall through to the sync steps to converge.
            yield* sesv2
              .createTenant({
                TenantName: name,
                Tags: createTagsList(desiredTags),
                SuppressionAttributes: news.suppression
                  ? {
                      SuppressedReasons: news.suppression.reasons,
                      SuppressionScope: news.suppression.scope,
                    }
                  : undefined,
              })
              .pipe(Effect.catchTag("AlreadyExistsException", () => Effect.succeed({})));
            // Not always readable the instant create returns, and on the
            // AlreadyExists race another writer may still be mid-create.
            observed = yield* getTenant(name).pipe(
              Effect.repeat({
                schedule: Schedule.spaced("1 second"),
                until: (tenant) => tenant !== undefined,
                times: 8,
              }),
            );
          }

          if (observed === undefined || !observed.TenantId || !observed.TenantArn) {
            return yield* new TenantUnexpectedResponse({
              message: `SES tenant ${name} was not found after create`,
            });
          }
          const tenantArn = observed.TenantArn;

          // 3. SYNC SUPPRESSION — diff observed suppression against desired and
          //    apply only on a real delta.
          //
          //    SES requires both members together — a put carrying only one
          //    fails with BadRequestException ("SuppressedReasons cannot be
          //    specified without SuppressionScope", and the mirror image). The
          //    prop nests them so that invalid state is unrepresentable and
          //    the put below always carries both.
          const observedReasons = observed.SuppressionAttributes?.SuppressedReasons;
          const observedScope = observed.SuppressionAttributes?.SuppressionScope;
          if (
            news.suppression !== undefined &&
            (!sameReasons(observedReasons, news.suppression.reasons) ||
              observedScope !== news.suppression.scope)
          ) {
            yield* sesv2.putTenantSuppressionAttributes({
              TenantName: name,
              SuppressedReasons: news.suppression.reasons,
              SuppressionScope: news.suppression.scope,
            });
          }

          // 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: tenantArn, Tags: upsert });
          }
          if (removed.length > 0) {
            yield* sesv2.untagResource({
              ResourceArn: tenantArn,
              TagKeys: removed,
            });
          }

          yield* session.note(tenantArn);
          return {
            tenantName: name,
            tenantId: observed.TenantId,
            tenantArn,
          };
        }),

        delete: Effect.fn(function* ({ output }) {
          // deleteTenant removes the tenant and its resource associations (not
          // the resources themselves), and is idempotent for a missing tenant.
          yield* sesv2
            .deleteTenant({ TenantName: output.tenantName })
            .pipe(Effect.catchTag("NotFoundException", () => Effect.void));
        }),
      });
    }),
  );