alchemy 2.0.0-beta.37 → 2.0.0-beta.39

package/src/Cloudflare/Email/EmailAddress.ts

@@ -0,0 +1,155 @@
+import * as emailRouting from "@distilled.cloud/cloudflare/email-routing";
+import * as Effect from "effect/Effect";
+import { isResolved } from "../../Diff.ts";
+import * as Provider from "../../Provider.ts";
+import { Resource } from "../../Resource.ts";
+import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
+import type { Providers } from "../Providers.ts";
+
+export type EmailAddressProps = {
+  /**
+   * 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 EmailAddress = Resource<
+  "Cloudflare.EmailAddress",
+  EmailAddressProps,
+  {
+    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 `EmailRule` actions and can also serve as the
+ * `destinationAddress` on a `send_email` Worker binding.
+ *
+ * @section Registering an Address
+ * @example Register a destination address
+ * ```typescript
+ * const ops = yield* Cloudflare.EmailAddress("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.
+ */
+export const EmailAddress = Resource<EmailAddress>("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,
+});
+
+export const EmailAddressProvider = () =>
+  Provider.effect(
+    EmailAddress,
+    Effect.gen(function* () {
+      const { accountId } = yield* CloudflareEnvironment;
+      const create = yield* emailRouting.createAddress;
+      const get = yield* emailRouting.getAddress;
+      const del = yield* emailRouting.deleteAddress;
+
+      return {
+        stables: ["addressId", "accountId", "email"],
+        diff: Effect.fn(function* ({ news, output }) {
+          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 identifier =
+            output?.addressId ??
+            (olds?.email ? encodeURIComponent(olds.email) : undefined);
+          if (!identifier) return undefined;
+          const acct = output?.accountId ?? accountId;
+          return yield* get({
+            accountId: acct,
+            destinationAddressIdentifier: identifier,
+          }).pipe(
+            Effect.map((r) => toAttrs(acct, r)),
+            Effect.catch(() => Effect.succeed(undefined)),
+          );
+        }),
+        reconcile: Effect.fn(function* ({ news, output }) {
+          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* get({
+                  accountId: acct,
+                  destinationAddressIdentifier: output.addressId,
+                }).pipe(
+                  Effect.map((r) => toAttrs(acct, r)),
+                  Effect.catch(() => Effect.succeed(undefined)),
+                )
+              : undefined;
+
+          if (!observed) {
+            observed = yield* get({
+              accountId: acct,
+              destinationAddressIdentifier: encodeURIComponent(email),
+            }).pipe(
+              Effect.map((r) => toAttrs(acct, r)),
+              Effect.catch(() => Effect.succeed(undefined)),
+            );
+          }
+
+          // Ensure — register the address if it doesn't already exist.
+          if (!observed) {
+            const created = yield* create({ accountId: acct, email });
+            observed = toAttrs(acct, created);
+          }
+
+          return observed;
+        }),
+        delete: Effect.fn(function* ({ output }) {
+          if (!output?.addressId) return;
+          yield* del({
+            accountId: output.accountId,
+            destinationAddressIdentifier: output.addressId,
+          }).pipe(Effect.catch(() => Effect.void));
+        }),
+      };
+    }),
+  );

package/src/Cloudflare/Email/EmailRouting.ts

@@ -0,0 +1,138 @@
+import * as emailRouting from "@distilled.cloud/cloudflare/email-routing";
+import * as Effect from "effect/Effect";
+import { isResolved } from "../../Diff.ts";
+import * as Provider from "../../Provider.ts";
+import { Resource } from "../../Resource.ts";
+import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
+import type { Providers } from "../Providers.ts";
+import { resolveZoneId, type ZoneReference } from "../Zone.ts";
+
+export type EmailRoutingStatus =
+  | "ready"
+  | "unconfigured"
+  | "misconfigured"
+  | "misconfigured/locked"
+  | "unlocked";
+
+export type EmailRoutingProps = {
+  /**
+   * Zone to enable email routing on. Accepts a zone id, a zone name
+   * (`example.com`), or a `{ zoneId, name? }` object.
+   */
+  zone: ZoneReference;
+  /**
+   * Whether to enable Email Routing on the zone.
+   *
+   * @default true
+   */
+  enabled?: boolean;
+};
+
+export type EmailRouting = Resource<
+  "Cloudflare.EmailRouting",
+  EmailRoutingProps,
+  {
+    routingId: string;
+    zoneId: string;
+    name: string;
+    enabled: boolean;
+    status: EmailRoutingStatus | undefined;
+  },
+  never,
+  Providers
+>;
+
+/**
+ * Enables Cloudflare Email Routing on a zone. This is the prerequisite for
+ * receiving mail at any address on the domain and for sending email from a
+ * Worker via `send_email` bindings.
+ *
+ * @section Enabling Email Routing
+ * @example Enable on a zone you own
+ * ```typescript
+ * const routing = yield* Cloudflare.EmailRouting("Routing", {
+ *   zone: "example.com",
+ * });
+ * ```
+ */
+export const EmailRouting = Resource<EmailRouting>("Cloudflare.EmailRouting");
+
+export const EmailRoutingProvider = () =>
+  Provider.effect(
+    EmailRouting,
+    Effect.gen(function* () {
+      const { accountId } = yield* CloudflareEnvironment;
+      const enable = yield* emailRouting.enableEmailRouting;
+      const disable = yield* emailRouting.disableEmailRouting;
+      const get = yield* emailRouting.getEmailRouting;
+
+      const resolve = (zone: ZoneReference) =>
+        resolveZoneId({
+          accountId,
+          zone,
+          hostname: typeof zone === "string" ? zone : (zone.name ?? ""),
+        });
+
+      return {
+        stables: ["zoneId", "routingId"],
+        diff: Effect.fn(function* ({ news, output }) {
+          if (!output) return undefined;
+          if (!isResolved(news)) return undefined;
+          const zoneId = yield* resolve(news.zone);
+          if (zoneId !== output.zoneId) {
+            return { action: "replace" } as const;
+          }
+          if ((news.enabled ?? true) !== output.enabled) {
+            return { action: "update" } as const;
+          }
+          return undefined;
+        }),
+        read: Effect.fn(function* ({ output }) {
+          if (!output?.zoneId) return undefined;
+          const result = yield* get({ zoneId: output.zoneId });
+          return {
+            routingId: result.id,
+            zoneId: output.zoneId,
+            name: result.name,
+            enabled: result.enabled,
+            status: (result.status ?? undefined) as
+              | EmailRoutingStatus
+              | undefined,
+          };
+        }),
+        reconcile: Effect.fn(function* ({ news, output }) {
+          const zoneId = output?.zoneId ?? (yield* resolve(news.zone));
+          const desired = news.enabled ?? true;
+
+          if (desired) {
+            const result = yield* enable({ zoneId, body: {} });
+            return {
+              routingId: result.id,
+              zoneId,
+              name: result.name,
+              enabled: result.enabled,
+              status: (result.status ?? undefined) as
+                | EmailRoutingStatus
+                | undefined,
+            };
+          } else {
+            const result = yield* disable({ zoneId, body: {} });
+            return {
+              routingId: result.id,
+              zoneId,
+              name: result.name,
+              enabled: result.enabled,
+              status: (result.status ?? undefined) as
+                | EmailRoutingStatus
+                | undefined,
+            };
+          }
+        }),
+        delete: Effect.fn(function* ({ output }) {
+          yield* disable({ zoneId: output.zoneId, body: {} }).pipe(
+            Effect.catch(() => Effect.void),
+          );
+        }),
+      };
+    }),
+  );

package/src/Cloudflare/Email/EmailRule.ts

@@ -0,0 +1,210 @@
+import * as emailRouting from "@distilled.cloud/cloudflare/email-routing";
+import * as Effect from "effect/Effect";
+import { isResolved } from "../../Diff.ts";
+import * as Provider from "../../Provider.ts";
+import { Resource } from "../../Resource.ts";
+import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
+import type { Providers } from "../Providers.ts";
+import { resolveZoneId, type ZoneReference } from "../Zone.ts";
+
+export type EmailMatcher =
+  | { type: "all" }
+  | { type: "literal"; field: "to"; value: string };
+
+export type EmailAction =
+  | { type: "drop" }
+  | { type: "forward"; value: string[] }
+  | { type: "worker"; value: string[] };
+
+export type EmailRuleProps = {
+  /**
+   * Zone the rule lives on.
+   */
+  zone: ZoneReference;
+  /**
+   * Display name for the rule.
+   */
+  name?: string;
+  /**
+   * Whether the rule is active. Disabled rules are evaluated last and
+   * effectively skipped.
+   *
+   * @default true
+   */
+  enabled?: boolean;
+  /**
+   * Lower priority numbers run first.
+   *
+   * @default 0
+   */
+  priority?: number;
+  /**
+   * Matchers that define which inbound emails trigger this rule.
+   */
+  matchers: EmailMatcher[];
+  /**
+   * Actions to take for matched emails.
+   */
+  actions: EmailAction[];
+};
+
+export type EmailRule = Resource<
+  "Cloudflare.EmailRule",
+  EmailRuleProps,
+  {
+    ruleId: string;
+    zoneId: string;
+    name: string;
+    enabled: boolean;
+    priority: number;
+    matchers: EmailMatcher[];
+    actions: EmailAction[];
+  },
+  never,
+  Providers
+>;
+
+/**
+ * A Cloudflare Email Routing rule.
+ *
+ * Rules forward inbound mail matching `matchers` to the listed actions
+ * (forward to a verified destination, drop, or hand off to a Worker).
+ *
+ * @section Forwarding Mail
+ * @example Forward `info@` to a verified destination
+ * ```typescript
+ * const rule = yield* Cloudflare.EmailRule("InfoForward", {
+ *   zone: "example.com",
+ *   matchers: [{ type: "literal", field: "to", value: "info@example.com" }],
+ *   actions: [{ type: "forward", value: ["ops@example.com"] }],
+ * });
+ * ```
+ */
+export const EmailRule = Resource<EmailRule>("Cloudflare.EmailRule");
+
+const normalize = (
+  rule: {
+    id?: string | null;
+    name?: string | null;
+    enabled?: boolean | null;
+    priority?: number | null;
+    matchers?:
+      | {
+          type: "all" | "literal";
+          field?: "to" | null;
+          value?: string | null;
+        }[]
+      | null;
+    actions?:
+      | { type: "drop" | "forward" | "worker"; value?: string[] | null }[]
+      | null;
+  },
+  zoneId: string,
+) => ({
+  ruleId: rule.id ?? "",
+  zoneId,
+  name: rule.name ?? "",
+  enabled: rule.enabled ?? true,
+  priority: rule.priority ?? 0,
+  matchers: (rule.matchers ?? []).map(
+    (m): EmailMatcher =>
+      m.type === "all"
+        ? { type: "all" }
+        : { type: "literal", field: "to", value: m.value ?? "" },
+  ),
+  actions: (rule.actions ?? []).map(
+    (a): EmailAction =>
+      a.type === "drop"
+        ? { type: "drop" }
+        : a.type === "forward"
+          ? { type: "forward", value: a.value ?? [] }
+          : { type: "worker", value: a.value ?? [] },
+  ),
+});
+
+export const EmailRuleProvider = () =>
+  Provider.effect(
+    EmailRule,
+    Effect.gen(function* () {
+      const { accountId } = yield* CloudflareEnvironment;
+      const create = yield* emailRouting.createRule;
+      const update = yield* emailRouting.updateRule;
+      const get = yield* emailRouting.getRule;
+      const del = yield* emailRouting.deleteRule;
+
+      const resolve = (zone: ZoneReference) =>
+        resolveZoneId({
+          accountId,
+          zone,
+          hostname: typeof zone === "string" ? zone : (zone.name ?? ""),
+        });
+
+      return {
+        stables: ["ruleId", "zoneId"],
+        diff: Effect.fn(function* ({ news, output }) {
+          if (!output) return undefined;
+          if (!isResolved(news)) return undefined;
+          const zoneId = yield* resolve(news.zone);
+          if (zoneId !== output.zoneId) {
+            return { action: "replace" } as const;
+          }
+          return undefined;
+        }),
+        read: Effect.fn(function* ({ output }) {
+          if (!output?.ruleId || !output?.zoneId) return undefined;
+          return yield* get({
+            zoneId: output.zoneId,
+            ruleIdentifier: output.ruleId,
+          }).pipe(
+            Effect.map((r) => normalize(r, output.zoneId)),
+            Effect.catch(() => Effect.succeed(undefined)),
+          );
+        }),
+        reconcile: Effect.fn(function* ({ news, output }) {
+          const zoneId = output?.zoneId ?? (yield* resolve(news.zone));
+          const body = {
+            actions: news.actions.map((a) =>
+              a.type === "drop"
+                ? { type: a.type }
+                : { type: a.type, value: a.value },
+            ),
+            matchers: news.matchers.map((m) =>
+              m.type === "all"
+                ? { type: "all" as const }
+                : {
+                    type: "literal" as const,
+                    field: "to" as const,
+                    value: m.value,
+                  },
+            ),
+            enabled: news.enabled ?? true,
+            name: news.name ?? "",
+            priority: news.priority ?? 0,
+          };
+
+          if (output?.ruleId) {
+            const result = yield* update({
+              zoneId,
+              ruleIdentifier: output.ruleId,
+              ...body,
+            }).pipe(
+              Effect.catch(() =>
+                create({ zoneId, ...body }).pipe(Effect.map((r) => r)),
+              ),
+            );
+            return normalize(result, zoneId);
+          }
+
+          const result = yield* create({ zoneId, ...body });
+          return normalize(result, zoneId);
+        }),
+        delete: Effect.fn(function* ({ output }) {
+          if (!output?.ruleId) return;
+          yield* del({
+            zoneId: output.zoneId,
+            ruleIdentifier: output.ruleId,
+          }).pipe(Effect.catch(() => Effect.void));
+        }),
+      };
+    }),
+  );

package/src/Cloudflare/Email/SendEmail.ts

@@ -0,0 +1,95 @@
+import * as Effect from "effect/Effect";
+import { SendEmailBinding } from "./SendEmailBinding.ts";
+
+type SendEmailTypeId = typeof SendEmailTypeId;
+const SendEmailTypeId = "Cloudflare.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 EmailAddress}).
+   */
+  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 EmailRouting}) 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 SendEmailBinding}.
+ *
+ * @resource
+ *
+ * @section Binding to a Worker
+ * @example Send to any verified destination
+ * ```typescript
+ * const Email = Cloudflare.SendEmail("Email");
+ *
+ * // in the Worker effect:
+ * const email = yield* Cloudflare.SendEmail.bind(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.SendEmail("OpsEmail", {
+ *   allowedSenderAddresses: ["noreply@example.com"],
+ *   destinationAddress: "ops@example.com",
+ * });
+ * ```
+ */
+export type SendEmail = SendEmailProps & {
+  kind: SendEmailTypeId;
+  name: string;
+};
+
+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>;
+  /**
+   * Bind this `send_email` descriptor to the surrounding Worker. Returns a
+   * typed runtime client for sending email.
+   */
+  bind: typeof SendEmailBinding.bind;
+} = Object.assign(
+  Effect.fnUntraced(function* (id: string, props?: SendEmailProps) {
+    return {
+      kind: SendEmailTypeId,
+      name: id,
+      destinationAddress: props?.destinationAddress,
+      allowedDestinationAddresses: props?.allowedDestinationAddresses,
+      allowedSenderAddresses: props?.allowedSenderAddresses,
+    } satisfies SendEmail;
+  }),
+  {
+    bind: (...args: Parameters<typeof SendEmailBinding.bind>) =>
+      SendEmailBinding.bind(...args),
+  },
+);