(fix/monitoring) Email Confirmation (firecrawl#3645)

* Nick:

* Nick:

* Nick:

* Nick:

* Nick:

Author: nickscamara

apps/api/src/__tests__/snips/v2/lib.ts

@@ -179,6 +179,26 @@ export async function monitorCheckRaw(
   return query ? req.query(query) : req;
 }
 
+export async function monitorEmailConfirmRaw(token: string) {
+  return await request(TEST_API_URL)
+    .post(`/v2/monitor/email/confirm`)
+    .set("Content-Type", "application/json")
+    .send({ token });
+}
+
+export async function monitorEmailUnsubscribeRaw(token: string) {
+  return await request(TEST_API_URL)
+    .post(`/v2/monitor/email/unsubscribe`)
+    .set("Content-Type", "application/json")
+    .send({ token });
+}
+
+export async function monitorEmailConfirmRawViaQuery(token: string) {
+  return await request(TEST_API_URL)
+    .post(`/v2/monitor/email/confirm`)
+    .query({ token });
+}
+
 export async function parseRaw(
   body: {
     options?: Omit<ParseRequestInput, "file">;

apps/api/src/__tests__/snips/v2/monitor.test.ts

@@ -10,6 +10,9 @@ import {
   monitorCheckRaw,
   monitorCreateRaw,
   monitorDeleteRaw,
+  monitorEmailConfirmRaw,
+  monitorEmailConfirmRawViaQuery,
+  monitorEmailUnsubscribeRaw,
   monitorGetRaw,
   monitorListRaw,
   monitorPatchRaw,
@@ -308,6 +311,124 @@ describeIf(ALLOW_TEST_SUITE_WEBSITE && !TEST_SELF_HOST)("/v2/monitor", () => {
     2 * scrapeTimeout,
   );
 
+  describe("email recipient opt-in", () => {
+    function externalRecipient(): string {
+      const id = Math.random().toString(36).slice(2, 10);
+      return `optin-${id}@external-test.example`;
+    }
+
+    it("starts external recipients as pending without sending notifications", async () => {
+      const recipient = externalRecipient();
+      const create = await monitorCreateRaw(
+        {
+          name: "opt-in monitor",
+          schedule: { cron: "*/30 * * * *", timezone: "UTC" },
+          targets: [
+            {
+              type: "scrape",
+              urls: [createTestIdUrl()],
+              scrapeOptions: { formats: ["markdown"] },
+            },
+          ],
+          notification: {
+            email: { enabled: true, recipients: [recipient] },
+          },
+        },
+        identity,
+      );
+      expect(create.statusCode).toBe(200);
+      expect(create.body.data.emailRecipientSubscriptions).toEqual(
+        expect.arrayContaining([
+          expect.objectContaining({
+            email: recipient.toLowerCase(),
+            status: "pending",
+            source: "opt_in",
+          }),
+        ]),
+      );
+
+      const get = await monitorGetRaw(create.body.data.id, identity);
+      expect(get.body.data.emailRecipientSubscriptions).toEqual(
+        expect.arrayContaining([
+          expect.objectContaining({
+            email: recipient.toLowerCase(),
+            status: "pending",
+          }),
+        ]),
+      );
+
+      await monitorDeleteRaw(create.body.data.id, identity);
+    });
+
+    it("rejects malformed confirm/unsubscribe tokens with a 400 JSON error", async () => {
+      const badConfirm = await monitorEmailConfirmRaw("x");
+      expect(badConfirm.statusCode).toBe(400);
+      expect(badConfirm.body).toEqual({
+        success: false,
+        error: "invalid_token",
+      });
+
+      const badUnsub = await monitorEmailUnsubscribeRaw("x");
+      expect(badUnsub.statusCode).toBe(400);
+      expect(badUnsub.body).toEqual({
+        success: false,
+        error: "invalid_token",
+      });
+    });
+
+    it("rejects tokens sent in the query string (body-only)", async () => {
+      // Tokens in URLs leak into access/proxy logs and APM URL tags, so
+      // the controller deliberately ignores query params.
+      const unknownToken = "a".repeat(43);
+      const response = await monitorEmailConfirmRawViaQuery(unknownToken);
+      expect(response.statusCode).toBe(400);
+      expect(response.body).toEqual({
+        success: false,
+        error: "invalid_token",
+      });
+    });
+
+    it("returns 404 JSON for unknown but well-formed tokens", async () => {
+      const unknownToken = "a".repeat(43);
+
+      const confirm = await monitorEmailConfirmRaw(unknownToken);
+      expect(confirm.statusCode).toBe(404);
+      expect(confirm.body).toEqual({
+        success: false,
+        error: "not_found",
+      });
+
+      const unsub = await monitorEmailUnsubscribeRaw(unknownToken);
+      expect(unsub.statusCode).toBe(404);
+      expect(unsub.body).toEqual({
+        success: false,
+        error: "not_found",
+      });
+    });
+
+    it("does not require opt-in when recipients are unset (team-default path)", async () => {
+      const create = await monitorCreateRaw(
+        {
+          name: "team default monitor",
+          schedule: { cron: "*/30 * * * *", timezone: "UTC" },
+          targets: [
+            {
+              type: "scrape",
+              urls: [createTestIdUrl()],
+              scrapeOptions: { formats: ["markdown"] },
+            },
+          ],
+          notification: { email: { enabled: true } },
+        },
+        identity,
+      );
+      expect(create.statusCode).toBe(200);
+      expect(create.body.data.emailRecipientSubscriptions).toEqual([]);
+
+      await monitorDeleteRaw(create.body.data.id, identity);
+    });
+  });
+
   it(
     "accepts mixed json + git-diff changeTracking modes",
     async () => {