feat(cloudflare-runtime): local send_email stub that logs under alchemy dev (#76)

Author: zeyuri

…/src/bindings/send-email/email.worker.ts …ndings/send-email/EmailMessage.worker.tspackages/cloudflare-runtime/src/bindings/send-email/email.worker.ts renamed to packages/cloudflare-runtime/src/bindings/send-email/EmailMessage.worker.ts packages/cloudflare-runtime/src/bindings/send-email/email.worker.ts renamed to packages/cloudflare-runtime/src/bindings/send-email/EmailMessage.worker.ts

@@ -1,6 +1,7 @@
 import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
-import * as EmailWorker from "worker:./email.worker.ts";
+import * as EmailMessageWorker from "worker:./EmailMessage.worker.ts";
+import * as SendEmailBindingWorker from "worker:./SendEmailBinding.worker.ts";
 import { formatExtensionModule } from "../../internal/internal-modules.ts";
 import * as Plugin from "../../Plugin.ts";
 import type { BindingHook } from "../../PluginContext.ts";
@@ -9,26 +10,43 @@ import { makeRemoteBinding } from "../../remote-bindings/RemoteBindings.ts";
 
 export class SendEmail extends Plugin.Service<SendEmail>()("cloudflare-runtime/plugin/SendEmail") {}
 
+/**
+ * Wrapped-binding module for the local `send()` stub — see
+ * `send-email.worker.ts`. Registered alongside the `cloudflare-internal:email`
+ * shim so {@link local} can point its wrapped binding at it.
+ */
+const LOCAL_SEND_EMAIL_MODULE = "cloudflare-runtime:send-email";
+
 export const SendEmailLive = Layer.succeed(
   SendEmail,
   SendEmail.of(
-    Effect.map(formatExtensionModule(EmailWorker), (esModule) => ({
-      extensions: [
-        {
-          modules: [
-            {
-              name: "cloudflare-internal:email",
-              internal: true,
-              esModule,
-            },
-          ],
-        },
-      ],
-    })),
+    Effect.zipWith(
+      formatExtensionModule(EmailMessageWorker),
+      formatExtensionModule(SendEmailBindingWorker),
+      (emailMessage, sendEmailBinding) => ({
+        extensions: [
+          {
+            modules: [
+              {
+                name: "cloudflare-internal:email",
+                internal: true,
+                esModule: emailMessage,
+              },
+              {
+                name: LOCAL_SEND_EMAIL_MODULE,
+                internal: true,
+                esModule: sendEmailBinding,
+              },
+            ],
+          },
+        ],
+      }),
+      { concurrent: true },
+    ),
   ),
 );
 
-export interface RemoteSendEmailProps {
+export interface SendEmailProps {
   readonly binding: string;
   readonly destinationAddress?: string;
   readonly allowedDestinationAddresses?: Array<string>;
@@ -42,7 +60,7 @@ export interface RemoteSendEmailProps {
  * the `EmailMessage` class to user code (workerd does not ship it
  * natively), matching the upstream Miniflare behavior.
  */
-export const remote = (props: RemoteSendEmailProps): BindingHook<RemoteBindings | SendEmail> =>
+export const remote = (props: SendEmailProps): BindingHook<RemoteBindings | SendEmail> =>
   Plugin.use(SendEmail, () =>
     makeRemoteBinding(
       {
@@ -58,3 +76,22 @@ export const remote = (props: RemoteSendEmailProps): BindingHook<RemoteBindings
       }),
     ),
   );
+
+/**
+ * Bind a local `send_email` stub for `alchemy dev`. `send()` logs the message
+ * and resolves instead of delivering real mail — matching how Miniflare and
+ * Wrangler treat `send_email` unless you opt into the real, remote binding.
+ *
+ * Reuses the `cloudflare-internal:email` `EmailMessage` shim registered by
+ * {@link SendEmailLive} (same as {@link remote}), so user code can still
+ * construct `EmailMessage` instances in dev. The address props are accepted
+ * to mirror {@link remote}'s signature; the stub does not enforce them.
+ */
+export const local = (props: SendEmailProps): BindingHook<SendEmail> =>
+  Plugin.useSync(SendEmail, () => ({
+    name: props.binding,
+    wrapped: {
+      moduleName: LOCAL_SEND_EMAIL_MODULE,
+      innerBindings: [],
+    },
+  }));

packages/cloudflare-runtime/src/bindings/send-email/SendEmail.ts

@@ -0,0 +1,47 @@
+/**
+ * Local `send_email` binding stub. Workerd has no real outbound email, and
+ * under `alchemy dev` we deliberately do not proxy to the deployed binding
+ * unless asked — so `send()` logs the message metadata and resolves instead
+ * of delivering. This matches how Miniflare/Wrangler treat `send_email`
+ * unless you opt into the real, remote binding. Mirrors the no-op
+ * `analytics-engine.worker.ts` stub, but logs rather than discards so the
+ * dev loop still shows what would have been sent.
+ */
+
+interface LoggableMessage {
+  from?: unknown;
+  to?: unknown;
+  subject?: unknown;
+}
+
+const formatAddress = (value: unknown): string => {
+  if (typeof value === "string") return value;
+  if (Array.isArray(value)) return value.map(formatAddress).join(", ");
+  if (value && typeof value === "object") {
+    const email = (value as { email?: unknown }).email;
+    if (typeof email === "string") return email;
+    return JSON.stringify(value);
+  }
+  return "<unset>";
+};
+
+class LocalSendEmail {
+  // Accepts both the builder-form message and a pre-built `EmailMessage`
+  // (which carries `from`/`to` but keeps the subject inside its raw MIME).
+  async send(message: LoggableMessage): Promise<void> {
+    const parts = [`from=${formatAddress(message?.from)}`, `to=${formatAddress(message?.to)}`];
+    if (typeof message?.subject === "string") {
+      parts.push(`subject=${JSON.stringify(message.subject)}`);
+    }
+    // Logging IS the behavior of this stub — surface the send in the dev loop.
+    console.log(
+      `[alchemy dev] send_email not delivered (${parts.join(" ")}); ` +
+        `body suppressed locally — opt into the real binding with ` +
+        `\`dev: { remote: true }\` to send for real`,
+    );
+  }
+}
+
+export default function makeBinding(_env: unknown): LocalSendEmail {
+  return new LocalSendEmail();
+}