feat(marketing-pages): sendWelcomeEmail job + handler enqueues it

sendWelcomeEmailJob takes IMailerService, validates the typed input
(userId + email), and delegates to mailer.sendWelcome. The
onAuthUserSignedUpHandler now takes IJobQueue and enqueues
"marketing-pages.send-welcome-email" with the event payload.

Both binders bind a RecordingMailerService at the IMailerService
symbol (production placeholder until a real adapter ships) and pass
mailer / queue into the wrapped factories. Dev-seed additionally
queue.register()s the slug so the in-memory queue dispatches via
the wrapped job; production relies on the generated Payload event-task
to resolve the wrapped handler from the container.

packages/marketing-pages/src/di/bind-dev-seed.ts

@@ -19,6 +19,9 @@ import type { IPagesRepository } from "../application/repositories/pages.reposit
 import type { ISiteSettingsRepository } from "../application/repositories/site-settings.repository.interface.js";
 import { userSignedUpEvent } from "@repo/auth";
 import { onAuthUserSignedUpHandler } from "../events/handlers/on-auth-user-signed-up.handler.js";
+import { sendWelcomeEmailJob, type ISendWelcomeEmailJob, type SendWelcomeEmailInput } from "../jobs/send-welcome-email.job.js";
+import { RecordingMailerService } from "../infrastructure/services/recording-mailer.service.js";
+import type { IMailerService } from "../application/services/mailer.service.interface.js";
 
 /**
  * Replace the default empty mocks with populated ones for dev mode + storybook.
@@ -129,10 +132,15 @@ export async function bindDevSeedMarketingPages(
         ),
       ),
     );
-  // bus + queue are accept-and-forward in Phase 6; consumed by Phase 7 generator
-  // output at the <gen:event-handlers> / <gen:jobs> anchors below.
-  void bus;
-  void queue;
+  // Bind the dev-seed mailer (recording so e2e tests can inspect calls).
+  if (marketingPagesContainer.isBound(MARKETING_PAGES_SYMBOLS.IMailerService)) {
+    marketingPagesContainer.unbind(MARKETING_PAGES_SYMBOLS.IMailerService);
+  }
+  const mailer = new RecordingMailerService();
+  marketingPagesContainer
+    .bind<IMailerService>(MARKETING_PAGES_SYMBOLS.IMailerService)
+    .toConstantValue(mailer);
+
   // <gen:event-handlers>
   // onAuthUserSignedUpHandler subscription — generated, edit the handler file (not this block) for behavior.
   const wrappedAuthUserSignedUp = withSpan(
@@ -145,7 +153,7 @@ export async function bindDevSeedMarketingPages(
         layer: "event-handler",
         name: "marketing-pages.onAuthUserSignedUpHandler",
       },
-      onAuthUserSignedUpHandler(),
+      onAuthUserSignedUpHandler(queue),
     ),
   );
   if (marketingPagesContainer.isBound(MARKETING_PAGES_SYMBOLS.IOnAuthUserSignedUpHandler)) {
@@ -154,4 +162,35 @@ export async function bindDevSeedMarketingPages(
   marketingPagesContainer.bind(MARKETING_PAGES_SYMBOLS.IOnAuthUserSignedUpHandler).toConstantValue(wrappedAuthUserSignedUp);
   bus.subscribe(userSignedUpEvent, "marketing-pages", wrappedAuthUserSignedUp);
   // <gen:jobs>
+  const wrappedSendWelcomeEmail = withSpan(
+    tracer,
+    { name: "marketing-pages.sendWelcomeEmail", op: "job" },
+    withCapture(
+      logger,
+      {
+        feature: "marketing-pages",
+        layer: "job",
+        name: "marketing-pages.sendWelcomeEmail",
+      },
+      sendWelcomeEmailJob(mailer),
+    ),
+  );
+  if (marketingPagesContainer.isBound(MARKETING_PAGES_SYMBOLS.ISendWelcomeEmailJob)) {
+    marketingPagesContainer.unbind(MARKETING_PAGES_SYMBOLS.ISendWelcomeEmailJob);
+  }
+  marketingPagesContainer.bind(MARKETING_PAGES_SYMBOLS.ISendWelcomeEmailJob).toConstantValue(wrappedSendWelcomeEmail);
+
+  // Register the dev-seed in-memory queue handler so enqueue() actually fires
+  // the wrapped job. Production binding skips this — the Payload task does it.
+  if ("register" in queue && typeof (queue as { register?: unknown }).register === "function") {
+    (queue as { register: (slug: string, h: (input: unknown) => Promise<void>) => void }).register(
+      "marketing-pages.send-welcome-email",
+      async (input) => {
+        const wrapped = marketingPagesContainer.get<ISendWelcomeEmailJob>(
+          MARKETING_PAGES_SYMBOLS.ISendWelcomeEmailJob,
+        );
+        await wrapped(input as SendWelcomeEmailInput);
+      },
+    );
+  }
 }

packages/marketing-pages/src/di/bind-production.ts

@@ -18,6 +18,9 @@ import { getSiteSettingsController } from "../interface-adapters/controllers/get
 import { getPageBySlugController } from "../interface-adapters/controllers/get-page-by-slug.controller";
 import { userSignedUpEvent } from "@repo/auth";
 import { onAuthUserSignedUpHandler } from "../events/handlers/on-auth-user-signed-up.handler";
+import { sendWelcomeEmailJob } from "../jobs/send-welcome-email.job";
+import { RecordingMailerService } from "../infrastructure/services/recording-mailer.service";
+import type { IMailerService } from "../application/services/mailer.service.interface";
 
 export function bindProductionMarketingPages(
   config: SanitizedConfig,
@@ -119,10 +122,17 @@ export function bindProductionMarketingPages(
         ),
       ),
     );
-  // bus + queue are accept-and-forward in Phase 6; consumed by Phase 7 generator
-  // output at the <gen:event-handlers> / <gen:jobs> anchors below.
-  void bus;
-  void queue;
+  // Bind the production mailer. Until a real SMTP/SES adapter ships, this is
+  // a placeholder RecordingMailerService — production wiring is structurally
+  // identical to dev-seed but the impl is the seam where a real mailer plugs in.
+  if (marketingPagesContainer.isBound(MARKETING_PAGES_SYMBOLS.IMailerService)) {
+    marketingPagesContainer.unbind(MARKETING_PAGES_SYMBOLS.IMailerService);
+  }
+  const mailer = new RecordingMailerService();
+  marketingPagesContainer
+    .bind<IMailerService>(MARKETING_PAGES_SYMBOLS.IMailerService)
+    .toConstantValue(mailer);
+
   // <gen:event-handlers>
   // onAuthUserSignedUpHandler subscription — generated, edit the handler file (not this block) for behavior.
   const wrappedAuthUserSignedUp = withSpan(
@@ -135,7 +145,7 @@ export function bindProductionMarketingPages(
         layer: "event-handler",
         name: "marketing-pages.onAuthUserSignedUpHandler",
       },
-      onAuthUserSignedUpHandler(),
+      onAuthUserSignedUpHandler(queue),
     ),
   );
   if (marketingPagesContainer.isBound(MARKETING_PAGES_SYMBOLS.IOnAuthUserSignedUpHandler)) {
@@ -144,4 +154,21 @@ export function bindProductionMarketingPages(
   marketingPagesContainer.bind(MARKETING_PAGES_SYMBOLS.IOnAuthUserSignedUpHandler).toConstantValue(wrappedAuthUserSignedUp);
   bus.subscribe(userSignedUpEvent, "marketing-pages", wrappedAuthUserSignedUp);
   // <gen:jobs>
+  const wrappedSendWelcomeEmail = withSpan(
+    tracer,
+    { name: "marketing-pages.sendWelcomeEmail", op: "job" },
+    withCapture(
+      logger,
+      {
+        feature: "marketing-pages",
+        layer: "job",
+        name: "marketing-pages.sendWelcomeEmail",
+      },
+      sendWelcomeEmailJob(mailer),
+    ),
+  );
+  if (marketingPagesContainer.isBound(MARKETING_PAGES_SYMBOLS.ISendWelcomeEmailJob)) {
+    marketingPagesContainer.unbind(MARKETING_PAGES_SYMBOLS.ISendWelcomeEmailJob);
+  }
+  marketingPagesContainer.bind(MARKETING_PAGES_SYMBOLS.ISendWelcomeEmailJob).toConstantValue(wrappedSendWelcomeEmail);
 }

packages/marketing-pages/src/di/symbols.ts

@@ -11,4 +11,5 @@ export const MARKETING_PAGES_SYMBOLS = {
   // <gen:event-handler-symbols>
   IOnAuthUserSignedUpHandler: Symbol.for("@repo/marketing-pages/onAuthUserSignedUp"),
   // <gen:job-symbols>
+  ISendWelcomeEmailJob: Symbol.for("@repo/marketing-pages/sendWelcomeEmailJob"),
 } as const;

packages/marketing-pages/src/events/handlers/on-auth-user-signed-up.handler.test.ts

@@ -1,15 +1,25 @@
 // packages/marketing-pages/src/events/handlers/on-auth-user-signed-up.handler.test.ts
 import { describe, it, expect } from "vitest";
+import { RecordingJobQueue } from "@repo/core-testing/instrumentation";
 import { onAuthUserSignedUpHandler } from "@/events/handlers/on-auth-user-signed-up.handler";
 
 describe("onAuthUserSignedUpHandler", () => {
-  it("returns a function (factory shape)", () => {
-    const handler = onAuthUserSignedUpHandler();
-    expect(typeof handler).toBe("function");
+  it("enqueues marketing-pages.send-welcome-email with userId + email", async () => {
+    const queue = new RecordingJobQueue();
+    const handler = onAuthUserSignedUpHandler(queue);
+
+    await handler({
+      userId: "u-42",
+      email: "alice@example.com",
+      signedUpAt: "2026-05-08T12:00:00.000Z",
     });
 
-  it("does not throw on a valid stub event", async () => {
-    const handler = onAuthUserSignedUpHandler();
-    await expect(handler({} as never)).resolves.toBeUndefined();
+    expect(queue.enqueued).toHaveLength(1);
+    expect(queue.enqueued[0]).toEqual(
+      expect.objectContaining({
+        taskSlug: "marketing-pages.send-welcome-email",
+        input: { userId: "u-42", email: "alice@example.com" },
+      }),
+    );
   });
 });

packages/marketing-pages/src/events/handlers/on-auth-user-signed-up.handler.ts

@@ -1,14 +1,16 @@
 // packages/marketing-pages/src/events/handlers/on-auth-user-signed-up.handler.ts
 import type { UserSignedUpEvent } from "@repo/auth";
+import type { IJobQueue } from "@repo/core-shared/jobs";
 
 export type IOnAuthUserSignedUpHandler = ReturnType<
   typeof onAuthUserSignedUpHandler
 >;
 
 export const onAuthUserSignedUpHandler =
-  () =>
-  async (_event: UserSignedUpEvent): Promise<void> => {
-    // TODO: implement the reaction. Inject dependencies via the factory's
-    // constructor and use them here. The handler runs inside the consumer's
-    // span+capture sandwich, so just throwing on failure is the right shape.
+  (queue: IJobQueue) =>
+  async (event: UserSignedUpEvent): Promise<void> => {
+    await queue.enqueue("marketing-pages.send-welcome-email", {
+      userId: event.userId,
+      email: event.email,
+    });
   };

packages/marketing-pages/src/integrations/cms/index.ts

@@ -1,4 +1,5 @@
 export { pages } from "./collections/pages";
 export { siteSettings } from "./globals/site-settings";
 // <gen:job-tasks>
+export { sendWelcomeEmailTask } from "./jobs/send-welcome-email.task";
 export { onAuthUserSignedUpEventTask } from "./jobs/__events-auth-user-signed-up.task";

packages/marketing-pages/src/integrations/cms/jobs/send-welcome-email.task.ts

@@ -0,0 +1,18 @@
+// packages/marketing-pages/src/integrations/cms/jobs/send-welcome-email.task.ts
+import type { TaskConfig } from "payload";
+import { marketingPagesContainer } from "../../../di/container";
+import { MARKETING_PAGES_SYMBOLS } from "../../../di/symbols";
+import type { ISendWelcomeEmailJob } from "../../../jobs/send-welcome-email.job";
+
+export const sendWelcomeEmailTask: TaskConfig<"marketing-pages.send-welcome-email"> = {
+  slug: "marketing-pages.send-welcome-email",
+  inputSchema: [],
+  retries: { attempts: 3, backoff: { type: "exponential", delay: 1000 } },
+  handler: async ({ input }) => {
+    const job = marketingPagesContainer.get<ISendWelcomeEmailJob>(
+      MARKETING_PAGES_SYMBOLS.ISendWelcomeEmailJob,
+    );
+    await job(input as never);
+    return { output: {} };
+  },
+};

packages/marketing-pages/src/jobs/send-welcome-email.job.test.ts

@@ -0,0 +1,37 @@
+// packages/marketing-pages/src/jobs/send-welcome-email.job.test.ts
+import { describe, it, expect } from "vitest";
+import { sendWelcomeEmailJob, sendWelcomeEmailInputSchema } from "@/jobs/send-welcome-email.job";
+import { RecordingMailerService } from "@/infrastructure/services/recording-mailer.service";
+
+describe("sendWelcomeEmailJob", () => {
+  it("rejects unknown input fields", async () => {
+    const mailer = new RecordingMailerService();
+    const job = sendWelcomeEmailJob(mailer);
+    await expect(job({ unexpectedField: 1 } as never)).rejects.toThrow();
+  });
+
+  it("rejects input missing required fields", async () => {
+    const mailer = new RecordingMailerService();
+    const job = sendWelcomeEmailJob(mailer);
+    await expect(job({ userId: "u1" } as never)).rejects.toThrow();
+  });
+
+  it("rejects invalid email", async () => {
+    const mailer = new RecordingMailerService();
+    const job = sendWelcomeEmailJob(mailer);
+    await expect(
+      job({ userId: "u1", email: "not-an-email" }),
+    ).rejects.toThrow();
+  });
+
+  it("sends a welcome email via the mailer on valid input", async () => {
+    const mailer = new RecordingMailerService();
+    const job = sendWelcomeEmailJob(mailer);
+    await job({ userId: "u1", email: "u1@example.com" });
+    expect(mailer.sent).toEqual([{ userId: "u1", email: "u1@example.com" }]);
+  });
+
+  it("references its input schema", () => {
+    expect(sendWelcomeEmailInputSchema).toBeDefined();
+  });
+});

packages/marketing-pages/src/jobs/send-welcome-email.job.ts

@@ -0,0 +1,20 @@
+// packages/marketing-pages/src/jobs/send-welcome-email.job.ts
+import { z } from "zod";
+import type { IMailerService } from "../application/services/mailer.service.interface";
+
+export const sendWelcomeEmailInputSchema = z
+  .object({
+    userId: z.string(),
+    email: z.string().email(),
+  })
+  .strict();
+
+export type SendWelcomeEmailInput = z.infer<typeof sendWelcomeEmailInputSchema>;
+export type ISendWelcomeEmailJob = ReturnType<typeof sendWelcomeEmailJob>;
+
+export const sendWelcomeEmailJob =
+  (mailer: IMailerService) =>
+  async (input: SendWelcomeEmailInput): Promise<void> => {
+    sendWelcomeEmailInputSchema.parse(input);
+    await mailer.sendWelcome(input.userId, input.email);
+  };