sailfork / t3code-github / .repos/ alchemy-effect/ packages/ cloudflare/ src/ Email/ Address.ts

import * as emailRouting from "@distilled.cloud/cloudflare/email-routing";
import { isResolved } from "alchemy/Diff";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import * as Effect from "effect/Effect";
import * as Schedule from "effect/Schedule";
import * as Stream from "effect/Stream";
import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
import type { Providers } from "../Providers.ts";

export type AddressProps = {
  /**
   * The email address to register as a verified destination on the
   * account. Cloudflare sends a verification email to this address; the
   * recipient must click the link before the address can receive routed
   * mail or be used as a verified sender.
   *
   * Changing this property triggers a replacement.
   */
  email: string;
};

export type Address = Resource<
  "Cloudflare.Email.Address",
  AddressProps,
  {
    addressId: string;
    email: string;
    accountId: string;
    verified: boolean;
    verifiedAt: string | undefined;
    created: string | undefined;
    modified: string | undefined;
  },
  never,
  Providers
>;

/**
 * A verified destination email address on the account.
 *
 * Destination addresses are account-scoped (not zone-scoped). They are used
 * as forwarding targets in `Rule` actions and can also serve as the
 * `destinationAddress` on a `send_email` Worker binding.
 * ### Registering an Address
 * **Example:** Register a destination address
 * ```typescript
 * const ops = yield* Cloudflare.Email.Address("Ops", {
 *   email: "ops@example.com",
 * });
 * ```
 *
 * Cloudflare sends a verification email when the address is first created.
 * The address must be verified before it can receive routed mail.
 *
 * @resource
 * @product Email
 * @category Email
 */
export const Address = Resource<Address>("Cloudflare.Email.Address", {
  aliases: ["Cloudflare.EmailAddress"],
});

const toAttrs = (
  accountId: string,
  result: {
    id?: string | null;
    email?: string | null;
    verified?: string | null;
    created?: string | null;
    modified?: string | null;
  },
) => ({
  addressId: result.id ?? "",
  email: result.email ?? "",
  accountId,
  verified: Boolean(result.verified),
  verifiedAt: result.verified ?? undefined,
  created: result.created ?? undefined,
  modified: result.modified ?? undefined,
});

// Authoritative account-wide lookup of a destination address by email. The
// per-address `getAddress` identifier is the opaque address id (not the email),
// so the only reliable way to find an address by its email is to enumerate the
// account collection (the same call `list()` exhausts).
const findByEmail = (accountId: string, email: string) =>
  emailRouting.listAddresses.pages({ accountId }).pipe(
    Stream.runCollect,
    Effect.map((chunk) =>
      Array.from(chunk)
        .flatMap((page) => page.result ?? [])
        .map((addr) => toAttrs(accountId, addr))
        .find((a) => a.email === email),
    ),
  );

export const AddressProvider = () =>
  Provider.succeed(Address, {
    stables: ["addressId", "accountId", "email"],
    // Account collection: destination addresses are enumerable account-wide.
    list: Effect.fn(function* () {
      const { accountId } = yield* yield* CloudflareEnvironment;
      return yield* emailRouting.listAddresses.pages({ accountId }).pipe(
        Stream.runCollect,
        Effect.map((chunk) =>
          Array.from(chunk).flatMap((page) =>
            (page.result ?? []).map((addr) => toAttrs(accountId, addr)),
          ),
        ),
      );
    }),
    diff: Effect.fn(function* ({ news, output }) {
      const { accountId } = yield* yield* CloudflareEnvironment;
      if (!output) return undefined;
      if (output.accountId !== accountId) {
        return { action: "replace" } as const;
      }
      if (!isResolved(news)) return undefined;
      if (news.email !== output.email) {
        return { action: "replace" } as const;
      }
      return undefined;
    }),
    read: Effect.fn(function* ({ output, olds }) {
      const { accountId } = yield* yield* CloudflareEnvironment;
      const identifier =
        output?.addressId ?? (olds?.email ? encodeURIComponent(olds.email) : undefined);
      if (!identifier) return undefined;
      const acct = output?.accountId ?? accountId;
      return yield* emailRouting
        .getAddress({
          accountId: acct,
          destinationAddressIdentifier: identifier,
        })
        .pipe(
          Effect.map((r) => toAttrs(acct, r)),
          Effect.orElseSucceed(() => undefined),
        );
    }),
    reconcile: Effect.fn(function* ({ news, output }) {
      const { accountId } = yield* yield* CloudflareEnvironment;
      const acct = output?.accountId ?? accountId;
      const email = news.email;

      // Observe — by addressId if known, else by email lookup.
      let observed: ReturnType<typeof toAttrs> | undefined = output?.addressId
        ? yield* emailRouting
            .getAddress({
              accountId: acct,
              destinationAddressIdentifier: output.addressId,
            })
            .pipe(
              Effect.map((r) => toAttrs(acct, r)),
              Effect.orElseSucceed(() => undefined),
            )
        : undefined;

      if (!observed) {
        observed = yield* emailRouting
          .getAddress({
            accountId: acct,
            destinationAddressIdentifier: encodeURIComponent(email),
          })
          .pipe(
            Effect.map((r) => toAttrs(acct, r)),
            Effect.orElseSucceed(() => undefined),
          );
      }

      // Ensure — register the address if it doesn't already exist.
      if (!observed) {
        observed = yield* emailRouting.createAddress({ accountId: acct, email }).pipe(
          Effect.map((created) => toAttrs(acct, created)),
          // Cloudflare rate-limits verification emails per destination
          // address ("Verification email has been sent too recently"). When
          // the same address was (re)created recently the address record
          // already exists account-wide, so adopt it instead of failing.
          // Re-raise if the address genuinely isn't present.
          Effect.catchTag("TooManyRequests", (error) =>
            findByEmail(acct, email).pipe(
              Effect.flatMap((found) => (found ? Effect.succeed(found) : Effect.fail(error))),
            ),
          ),
        );
      }

      return observed;
    }),
    delete: Effect.fn(function* ({ output }) {
      if (!output?.addressId) return;
      // Idempotent on the typed not-found; transient failures are retried
      // bounded and a persistent failure surfaces — a swallowed failure
      // silently leaks the destination address. Cloudflare refuses to
      // delete an address for ~15 minutes after creation
      // (`EmailAddressCreatedTooRecently`, code 2032) — retrying is
      // pointless within a deploy's lifetime, so that error fails fast:
      // either destroy later or retain the address (`RemovalPolicy.retain`).
      yield* emailRouting
        .deleteAddress({
          accountId: output.accountId,
          destinationAddressIdentifier: output.addressId,
        })
        .pipe(
          Effect.catchTag("EmailAddressNotFound", () => Effect.void),
          Effect.retry({
            while: (e) => e._tag !== "EmailAddressCreatedTooRecently",
            schedule: Schedule.max([Schedule.spaced("3 seconds"), Schedule.recurs(8)]),
          }),
        );
    }),
  });