feat(cloudflare): send email binding

alchemy/src/cloudflare/bindings.ts

@@ -24,6 +24,7 @@ import type { RateLimit } from "./rate-limit.ts";
 import type { SecretKey } from "./secret-key.ts";
 import type { SecretRef as CloudflareSecretRef } from "./secret-ref.ts";
 import type { Secret as CloudflareSecret } from "./secret.ts";
+import type { SendEmail } from "./send-email.ts";
 import type { VectorizeIndex } from "./vectorize-index.ts";
 import type { VersionMetadata } from "./version-metadata.ts";
 import type { VpcService } from "./vpc-service.ts";
@@ -70,6 +71,7 @@ export type Binding =
     }
   | Secret
   | SecretKey
+  | SendEmail
   | string
   | VectorizeIndex
   | Worker
@@ -138,6 +140,7 @@ export type WorkerBindingSpec =
   | WorkerBindingSecretText
   | WorkerBindingSecretsStore
   | WorkerBindingSecretsStoreSecret
+  | WorkerBindingSendEmail
   | WorkerBindingService
   | WorkerBindingStaticContent
   | WorkerBindingTailConsumer
@@ -410,6 +413,19 @@ export interface WorkerBindingSecretsStoreSecret {
   secret_name: string;
 }
 
+export interface WorkerBindingSendEmail {
+  /* The kind of resource that the binding provides. */
+  type: "send_email";
+  /* A JavaScript variable name for the binding. */
+  name: string;
+  /* List of allowed destination addresses. */
+  allowed_destination_addresses?: Array<string>;
+  /* List of allowed sender addresses. */
+  allowed_sender_addresses?: Array<string>;
+  /* Destination address for the email. */
+  destination_address?: string;
+}
+
 /**
  * Service binding type
  */

alchemy/src/cloudflare/bound.ts

@@ -18,6 +18,7 @@ import type { RateLimit as _RateLimit } from "./rate-limit.ts";
 import type { SecretKey } from "./secret-key.ts";
 import type { SecretRef as CloudflareSecretRef } from "./secret-ref.ts";
 import type { Secret as CloudflareSecret } from "./secret.ts";
+import type { SendEmail as _SendEmail } from "./send-email.ts";
 import type { VectorizeIndex as _VectorizeIndex } from "./vectorize-index.ts";
 import type { VersionMetadata as _VersionMetadata } from "./version-metadata.ts";
 import type { VpcService as _VpcService } from "./vpc-service.ts";
@@ -106,8 +107,10 @@ export type Bound<T extends Binding> =
                                                                 Obj &
                                                                   Rpc.DurableObjectBranded
                                                               >
-                                                            : T extends _VpcService
-                                                              ? Fetcher
-                                                              : T extends undefined
-                                                                ? undefined
-                                                                : Service;
+                                                            : T extends _SendEmail
+                                                              ? SendEmail
+                                                              : T extends _VpcService
+                                                                ? Fetcher
+                                                                : T extends undefined
+                                                                  ? undefined
+                                                                  : Service;

alchemy/src/cloudflare/index.ts

@@ -64,6 +64,7 @@ export * from "./secret-key.ts";
 export * from "./secret-ref.ts";
 export * from "./secret.ts";
 export * from "./secrets-store.ts";
+export * from "./send-email.ts";
 export * from "./state.ts";
 export * from "./sveltekit/sveltekit.ts";
 export * from "./tanstack-start/tanstack-start.ts";

alchemy/src/cloudflare/miniflare/build-worker-options.ts

@@ -50,7 +50,10 @@ type RemoteBinding =
       }
     > & { raw: true })
   // Fetcher type bindings do not require the `raw` flag and will throw an error if it is present.
-  | Extract<WorkerBindingSpec, { type: "service" | "vpc_service" }>;
+  | Extract<
+      WorkerBindingSpec,
+      { type: "send_email" | "service" | "vpc_service" }
+    >;
 
 type BaseWorkerOptions = {
   [K in keyof miniflare.WorkerOptions]: K extends
@@ -271,6 +274,35 @@ export const buildWorkerOptions = async (
         };
         break;
       }
+      case "send_email": {
+        const properties = {
+          name: key,
+          ...("allowedSenderAddresses" in binding
+            ? {
+                allowed_sender_addresses: binding.allowedSenderAddresses,
+              }
+            : {}),
+          ...("allowedDestinationAddresses" in binding
+            ? {
+                allowed_destination_addresses:
+                  binding.allowedDestinationAddresses,
+              }
+            : "destinationAddress" in binding
+              ? {
+                  destination_address: binding.destinationAddress,
+                }
+              : {}),
+        };
+        if (isRemoteBinding(binding)) {
+          remoteBindings.push({
+            type: "send_email",
+            ...properties,
+          });
+        } else {
+          (options.email ??= { send_email: [] }).send_email!.push(properties);
+        }
+        break;
+      }
       case "r2_bucket": {
         if (isRemoteBinding(binding)) {
           remoteBindings.push({
@@ -441,6 +473,23 @@ export const buildWorkerOptions = async (
             remoteProxyConnectionString: remoteProxy.connectionString,
           };
           break;
+        case "send_email":
+          (options.email ??= { send_email: [] }).send_email!.push({
+            name: binding.name,
+            allowed_sender_addresses: binding.allowed_sender_addresses,
+            ...("allowed_destination_addresses" in binding
+              ? {
+                  allowed_destination_addresses:
+                    binding.allowed_destination_addresses,
+                }
+              : "destination_address" in binding
+                ? {
+                    destination_address: binding.destination_address,
+                  }
+                : {}),
+            remoteProxyConnectionString: remoteProxy.connectionString,
+          });
+          break;
         case "service":
           (options.serviceBindings ??= {})[binding.name] = {
             name: binding.name,

alchemy/src/cloudflare/miniflare/miniflare-controller.ts

@@ -101,7 +101,7 @@ export class MiniflareController {
         unsafeDevRegistryPath: miniflare.getDefaultDevRegistryPath(),
         log: process.env.DEBUG
           ? new miniflare.Log(miniflare.LogLevel.DEBUG)
-          : undefined,
+          : new DefaultLogger(),
         // This is required to allow websites and other separate processes
         // to detect Alchemy-managed Durable Objects via the Wrangler dev registry.
         unsafeDevRegistryDurableObjectProxy: true,
@@ -170,3 +170,22 @@ export class MiniflareController {
     ]);
   }
 }
+
+class DefaultLogger extends miniflare.Log {
+  constructor() {
+    // The "info" level is used to log outgoing messages from the `send_email` binding:
+    // https://github.com/cloudflare/workers-sdk/blob/9dd447b8ba8f7c317ddf98d0c52d67352022896b/packages/miniflare/src/workers/email/send_email.worker.ts#L64
+    super(miniflare.LogLevel.INFO);
+  }
+
+  override info(message: string) {
+    // Alchemy does its own logging and the port is different from the one
+    // used by Miniflare, so suppress those messages to avoid confusion.
+    if (
+      message.startsWith("Ready on") ||
+      message.startsWith("Updated and ready on")
+    )
+      return;
+    super.info(message);
+  }
+}

alchemy/src/cloudflare/send-email.ts

@@ -0,0 +1,22 @@
+export type BaseSendEmailProps = {
+  allowedSenderAddresses?: Array<string>;
+  dev?: { remote?: boolean };
+};
+
+export type SendEmailProps = BaseSendEmailProps &
+  (
+    | {
+        destinationAddress?: string;
+      }
+    | {
+        allowedDestinationAddresses?: Array<string>;
+      }
+  );
+
+export type SendEmail = SendEmailProps & {
+  type: "send_email";
+};
+
+export function SendEmail(props?: SendEmailProps): SendEmail {
+  return { type: "send_email", ...props };
+}

alchemy/src/cloudflare/worker-metadata.ts

@@ -626,6 +626,20 @@ export async function prepareWorkerMetadata(
         namespace_id: binding.namespace_id.toString(),
         simple: binding.simple,
       });
+    } else if (binding.type === "send_email") {
+      meta.bindings.push({
+        type: "send_email",
+        name: bindingName,
+        allowed_destination_addresses:
+          "allowedDestinationAddresses" in binding
+            ? binding.allowedDestinationAddresses
+            : undefined,
+        allowed_sender_addresses: binding.allowedSenderAddresses,
+        destination_address:
+          "destinationAddress" in binding
+            ? binding.destinationAddress
+            : undefined,
+      });
     } else if (binding.type === "vpc_service") {
       meta.bindings.push({
         type: "vpc_service",

alchemy/src/cloudflare/wrangler.json.ts

@@ -284,6 +284,7 @@ async function processBindings(
   const pipelines: WranglerJsonConfig["pipelines"] = [];
   const secretsStoreSecrets: WranglerJsonConfig["secrets_store_secrets"] = [];
   const dispatchNamespaces: WranglerJsonConfig["dispatch_namespaces"] = [];
+  const sendEmails: WranglerJsonConfig["send_email"] = [];
   const ratelimits: WranglerJsonConfig["ratelimits"] = [];
   const containers: WranglerJsonConfig["containers"] = [];
   const workerLoaders: WranglerJsonConfig["worker_loaders"] = [];
@@ -509,6 +510,22 @@ async function processBindings(
       });
     } else if (binding.type === "secret_key") {
       // no-op
+    } else if (binding.type === "send_email") {
+      sendEmails.push({
+        name: bindingName,
+        allowed_sender_addresses: binding.allowedSenderAddresses,
+        ...("allowedDestinationAddresses" in binding
+          ? {
+              allowed_destination_addresses:
+                binding.allowedDestinationAddresses,
+            }
+          : "destinationAddress" in binding
+            ? {
+                destination_address: binding.destinationAddress,
+              }
+            : {}),
+        ...(binding.dev?.remote ? { remote: true } : {}),
+      });
     } else if (binding.type === "container") {
       durableObjects.push({
         name: bindingName,
@@ -621,6 +638,10 @@ async function processBindings(
     spec.containers = containers;
   }
 
+  if (sendEmails.length > 0) {
+    spec.send_email = sendEmails;
+  }
+
   if (ratelimits.length > 0) {
     spec.ratelimits = ratelimits;
   }

examples/cloudflare-email/alchemy.run.ts

@@ -0,0 +1,19 @@
+import alchemy from "alchemy";
+import { SendEmail, Worker } from "alchemy/cloudflare";
+
+const app = await alchemy("cloudflare-email");
+
+export const worker = await Worker("email-worker", {
+  entrypoint: "worker.ts",
+  compatibility: "node",
+  bindings: {
+    SEND_EMAIL: SendEmail(),
+  },
+});
+
+console.log({
+  name: worker.name,
+  url: worker.url,
+});
+
+await app.finalize();

examples/cloudflare-email/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "cloudflare-email",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "build": "tsc -b",
+    "deploy": "alchemy deploy --env-file ../../.env",
+    "destroy": "alchemy destroy --env-file ../../.env",
+    "dev": "alchemy dev --env-file ../../.env"
+  },
+  "dependencies": {
+    "mimetext": "^3.0.28"
+  },
+  "devDependencies": {
+    "@cloudflare/workers-types": "catalog:",
+    "alchemy": "workspace:*"
+  }
+}

examples/cloudflare-email/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "types": ["@cloudflare/workers-types"],
+    "noEmit": true
+  },
+  "references": [
+    {
+      "path": "../../alchemy/tsconfig.json"
+    }
+  ]
+}