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

import { ProviderModePolicy } from "alchemy/ProviderMode";
import * as Effect from "effect/Effect";

type SendEmailTypeId = typeof SendEmailTypeId;
const SendEmailTypeId = "Cloudflare.Email.SendEmail" as const;

export type SendEmailProps = {
  /**
   * Restrict the Worker to send to a single verified destination address.
   *
   * Mutually exclusive with `allowedDestinationAddresses`. The destination
   * must be a verified address on the account (see {@link Address}).
   */
  destinationAddress?: string;
  /**
   * Restrict the Worker to send to one of these verified destination addresses.
   *
   * Mutually exclusive with `destinationAddress`.
   */
  allowedDestinationAddresses?: string[];
  /**
   * Restrict the Worker to send from one of these sender addresses.
   *
   * The sender domain must have Email Routing configured (see
   * {@link Routing}) and the addresses must be verified.
   */
  allowedSenderAddresses?: string[];
};

/**
 * A Cloudflare Workers `send_email` binding descriptor.
 *
 * `SendEmail` is a Worker-only binding — it does not create any cloud-side
 * resource. The descriptor names the binding and records optional
 * destination/sender restrictions; the actual `send_email` entry is attached
 * to the Worker via {@link SendBinding}.
 *
 * Under `alchemy dev` the binding is lowered onto the local email simulator:
 * `send()` validates the message and persists it as a `.eml` under
 * `.alchemy/local/email` instead of delivering mail. Pipe the descriptor
 * through `Alchemy.remote()` to send through the live Cloudflare Email
 * service in dev — the same opt-out aspect resources use.
 *
 *
 * ### Binding to a Worker
 * **Example:** Send to any verified destination
 * ```typescript
 * const Email = Cloudflare.Email.SendEmail("Email");
 *
 * // in the Worker effect:
 * const email = yield* Cloudflare.Email.Send(Email);
 * yield* email.send({
 *   from: "noreply@example.com",
 *   to: "user@example.com",
 *   subject: "Hello",
 *   text: "Hi from Alchemy",
 * });
 * ```
 *
 * **Example:** Restrict the sender address
 * ```typescript
 * const Ops = Cloudflare.Email.SendEmail("OpsEmail", {
 *   allowedSenderAddresses: ["noreply@example.com"],
 *   destinationAddress: "ops@example.com",
 * });
 * ```
 *
 * ### Local development
 * **Example:** Send real mail from the dev loop
 * ```typescript
 * // Default: `send()` lands in the local simulator under `alchemy dev`.
 * // Alchemy.remote() opts into the live Email service instead:
 * const Email = Cloudflare.Email.SendEmail("Email", {
 *   allowedSenderAddresses: ["noreply@example.com"],
 * }).pipe(Alchemy.remote());
 * ```
 *
 * @resource
 */
export type SendEmail = SendEmailProps & {
  kind: SendEmailTypeId;
  name: string;
  /**
   * Alchemy-internal: opt-out of local emulation in `alchemy dev` — the
   * `Alchemy.remote()` decoration captured at registration time. Registered
   * on the host Worker via the binding-data `devRemote` channel, never on
   * the wire binding itself.
   */
  devRemote?: boolean;
};

export const isSendEmail = (value: unknown): value is SendEmail =>
  typeof value === "object" &&
  value !== null &&
  "kind" in value &&
  (value as SendEmail).kind === SendEmailTypeId;

export const SendEmail: (id: string, props?: SendEmailProps) => Effect.Effect<SendEmail> =
  Effect.fn(function* (id: string, props?: SendEmailProps) {
    // Capture the `Alchemy.remote()` decoration the same way resources do —
    // at registration time, from the ambient ProviderModePolicy reference.
    // `send_email` has no cloud-side resource (and thus no provider mode to
    // stamp), so the captured flag rides on the descriptor instead.
    const devRemote = (yield* ProviderModePolicy) === true || undefined;
    return {
      kind: SendEmailTypeId,
      name: id,
      destinationAddress: props?.destinationAddress,
      allowedDestinationAddresses: props?.allowedDestinationAddresses,
      allowedSenderAddresses: props?.allowedSenderAddresses,
      devRemote,
    } satisfies SendEmail;
  });