Skip to content

Supercharge your AI agents with data from the web and beyond. Building the library for superintelligence. 🔥

22.9 KB
Raw Blame
const {
  mockEnsureRecipient,
  mockListRecipients,
  mockTouchNotified,
  mockMarkConfirmationSent,
  mockResendSend,
} = vi.hoisted(() => ({
  mockEnsureRecipient: vi.fn(),
  mockListRecipients: vi.fn(),
  mockTouchNotified: vi.fn(),
  mockMarkConfirmationSent: vi.fn(),
  mockResendSend: vi.fn(),
}));

vi.mock("../monitoring/email_recipients", async importOriginal => {
  const actual =
    await importOriginal<typeof import("../monitoring/email_recipients")>();
  return {
    ...actual,
    ensureMonitorEmailRecipient: (...args: unknown[]) =>
      mockEnsureRecipient(...args),
    listMonitorEmailRecipients: (...args: unknown[]) =>
      mockListRecipients(...args),
    touchRecipientsNotified: (...args: unknown[]) => mockTouchNotified(...args),
    markRecipientConfirmationSent: (...args: unknown[]) =>
      mockMarkConfirmationSent(...args),
  };
});

vi.mock("resend", () => ({
  // Regular function (not arrow) so it works as a constructor under `new Resend()`.
  Resend: vi.fn(function () {
    return { emails: { send: mockResendSend } };
  }),
}));

import {
  buildConfirmationHtml,
  buildHtml,
  buildMonitoringCheckDashboardUrl,
  buildRecipientConfirmationUrl,
  buildRecipientUnsubscribeUrl,
  sendMonitoringConfirmationEmail,
  sendMonitoringEmailSummary,
  type MonitoringEmailPayload,
} from "./monitoring_email";
import { config } from "../../config";

const ORIGINAL_RESEND_API_KEY = config.RESEND_API_KEY;

beforeEach(() => {
  mockEnsureRecipient.mockReset();
  mockListRecipients.mockReset();
  mockTouchNotified.mockReset();
  mockMarkConfirmationSent.mockReset();
  mockResendSend.mockReset();
  mockResendSend.mockResolvedValue({ data: { id: "msg-1" }, error: null });
  mockTouchNotified.mockResolvedValue(undefined);
  mockMarkConfirmationSent.mockResolvedValue(undefined);
  // getResendClient() reads config.RESEND_API_KEY (a snapshot of process.env at
  // import time), so set it on the config object directly to make the suite
  // hermetic regardless of the runner's environment.
  config.RESEND_API_KEY = "test-key";
});

afterAll(() => {
  config.RESEND_API_KEY = ORIGINAL_RESEND_API_KEY;
});

function fakeRecipient(
  email: string,
  status: "pending" | "confirmed" | "unsubscribed",
  source: "team" | "opt_in" | "legacy" = "opt_in",
) {
  const sanitized = email.replace(/[^a-z0-9]/gi, "");
  return {
    id: `rec-${sanitized}`,
    monitor_id: "monitor-1",
    team_id: "team-1",
    email,
    status,
    token: `tok-${sanitized}`,
    source,
    confirmation_sent_at:
      status === "pending" ? new Date().toISOString() : null,
    confirmed_at: status === "confirmed" ? new Date().toISOString() : null,
    unsubscribed_at:
      status === "unsubscribed" ? new Date().toISOString() : null,
    last_notified_at: null,
    created_at: new Date().toISOString(),
    updated_at: new Date().toISOString(),
  };
}

describe("monitoring email URLs", () => {
  it("builds a dashboard link for a monitor check", () => {
    expect(
      buildMonitoringCheckDashboardUrl(
        {
          monitorId: "019e07fb-fb25-74cb-9a6c-f36c685c6e5b",
          checkId: "019e0903-bf7c-779f-a8a5-736ba82d3974",
        },
        "https://firecrawl-o2cg7p09w-side-guide.vercel.app/",
      ),
    ).toBe(
      "https://firecrawl-o2cg7p09w-side-guide.vercel.app/app/monitoring/019e07fb-fb25-74cb-9a6c-f36c685c6e5b?checkId=019e0903-bf7c-779f-a8a5-736ba82d3974",
    );
  });

  it("builds opt-in and unsubscribe URLs against the dashboard base", () => {
    const confirm = buildRecipientConfirmationUrl("abc123");
    expect(confirm).toContain("/monitoring/email/confirm");
    expect(confirm).not.toContain("/v2/");
    expect(confirm).toContain("token=abc123");

    const unsub = buildRecipientUnsubscribeUrl("abc123");
    expect(unsub).toContain("/monitoring/email/unsubscribe");
    expect(unsub).not.toContain("/v2/");
    expect(unsub).toContain("token=abc123");
  });

  it("includes the dashboard check link and unsubscribe footer in the email html", () => {
    const dashboardUrl = buildMonitoringCheckDashboardUrl(
      {
        monitorId: "monitor-1",
        checkId: "check-1",
      },
      "https://www.firecrawl.dev",
    );
    const payload: MonitoringEmailPayload = {
      monitorId: "monitor-1",
      monitorName: "Docs monitor",
      checkId: "check-1",
      dashboardUrl,
      summary: {
        changed: 1,
        new: 0,
        removed: 0,
        error: 0,
        totalPages: 1,
      },
      pages: [
        {
          url: "https://example.com/docs",
          status: "changed",
        },
      ],
      creditsUsed: 1,
      unsubscribeUrl:
        "https://www.firecrawl.dev/monitoring/email/unsubscribe?token=tok123",
    };

    const html = buildHtml(payload);
    expect(html).toContain(
      `<a href="${dashboardUrl}">View this check in the dashboard</a>`,
    );
    expect(html).toContain(
      "https://www.firecrawl.dev/monitoring/email/unsubscribe?token=tok123",
    );
    expect(html).toContain("Unsubscribe from this monitor");
  });

  it("omits the unsubscribe footer when no unsubscribe URL is provided", () => {
    const html = buildHtml({
      monitorId: "m1",
      monitorName: "M",
      checkId: "c1",
      dashboardUrl: "https://www.firecrawl.dev/app/monitoring/m1?checkId=c1",
      summary: { changed: 0, new: 1, removed: 0, error: 0, totalPages: 1 },
      pages: [{ url: "https://example.com", status: "new" }],
      creditsUsed: 1,
    });
    expect(html).not.toContain("Unsubscribe from this monitor");
  });
});

describe("buildConfirmationHtml", () => {
  it("renders a confirm CTA and a fallback unsubscribe link", () => {
    const html = buildConfirmationHtml({
      monitorName: "Marketing site",
      recipientEmail: "[email protected]",
      confirmUrl:
        "https://www.firecrawl.dev/monitoring/email/confirm?token=tok1",
      unsubscribeUrl:
        "https://www.firecrawl.dev/monitoring/email/unsubscribe?token=tok1",
    });
    expect(html).toContain("Confirm subscription");
    expect(html).toContain("Marketing site");
    expect(html).toContain("[email protected]");
    expect(html).toContain("token=tok1");
  });

  it("escapes HTML in recipient and monitor names", () => {
    const html = buildConfirmationHtml({
      monitorName: "<script>x</script>",
      recipientEmail: "[email protected]",
      confirmUrl: "https://example.com/c?token=t",
      unsubscribeUrl: "https://example.com/u?token=t",
    });
    expect(html).not.toContain("<script>x</script>");
    expect(html).toContain("&lt;script&gt;");
  });
});

describe("sendMonitoringConfirmationEmail", () => {
  it("sends a Resend email and marks confirmation_sent_at", async () => {
    const result = await sendMonitoringConfirmationEmail({
      recipient: fakeRecipient("[email protected]", "pending"),
      monitorName: "My monitor",
    });
    expect(result).toEqual({ attempted: true, success: true });
    expect(mockResendSend).toHaveBeenCalledTimes(1);
    expect(mockResendSend.mock.calls[0][0].to).toBe("[email protected]");
    expect(mockResendSend.mock.calls[0][0].subject).toContain(
      "Confirm subscription",
    );
    expect(mockMarkConfirmationSent).toHaveBeenCalledWith("rec-newexamplecom");
  });

  it("returns failure if Resend reports an error", async () => {
    mockResendSend.mockResolvedValueOnce({ data: null, error: "boom" });
    const result = await sendMonitoringConfirmationEmail({
      recipient: fakeRecipient("[email protected]", "pending"),
      monitorName: "My monitor",
    });
    expect(result.attempted).toBe(true);
    expect(result.success).toBe(false);
    expect(mockMarkConfirmationSent).not.toHaveBeenCalled();
  });
});

describe("sendMonitoringEmailSummary", () => {
  function buildArgs(opts: {
    goal?: string | null;
    emailEnabled?: boolean;
    recipients?: string[];
    pages: Array<{
      status: string;
      meaningful?: boolean | null;
      url?: string;
      reason?: string;
    }>;
    judgeEnabled?: boolean;
  }) {
    return {
      monitor: {
        id: "monitor-1",
        team_id: "team-1",
        name: "Test",
        goal: opts.goal ?? null,
        judge_enabled:
          opts.judgeEnabled !== undefined
            ? opts.judgeEnabled
            : Boolean(opts.goal),
        notification: opts.emailEnabled
          ? {
              email: {
                enabled: true,
                recipients: opts.recipients ?? ["[email protected]"],
              },
            }
          : null,
      } as any,
      check: {
        id: "check-1",
        changed_count: opts.pages.filter(p => p.status === "changed").length,
        new_count: opts.pages.filter(p => p.status === "new").length,
        removed_count: opts.pages.filter(p => p.status === "removed").length,
        error_count: opts.pages.filter(p => p.status === "error").length,
      } as any,
      pages: opts.pages.map((p, i) => ({
        url: p.url ?? `https://example.com/${i}`,
        status: p.status,
        judgment:
          p.meaningful === null || p.meaningful === undefined
            ? null
            : {
                meaningful: p.meaningful,
                confidence: "high" as const,
                reason: p.reason ?? "test",
                fields: [],
              },
      })),
    };
  }

  describe("judgment gating", () => {
    beforeEach(() => {
      mockListRecipients.mockResolvedValue([
        fakeRecipient("[email protected]", "confirmed"),
      ]);
    });

    it("suppresses email when goal set and all changed pages are noise", async () => {
      const result = await sendMonitoringEmailSummary(
        buildArgs({
          goal: "track price changes",
          emailEnabled: true,
          pages: [
            { status: "changed", meaningful: false },
            { status: "changed", meaningful: false },
          ],
        }),
      );
      expect(result.attempted).toBe(false);
    });

    it("fires email when goal set and at least one changed page is meaningful", async () => {
      const result = await sendMonitoringEmailSummary(
        buildArgs({
          goal: "track price changes",
          emailEnabled: true,
          pages: [
            { status: "changed", meaningful: false },
            { status: "changed", meaningful: true },
          ],
        }),
      );
      expect(result.attempted).toBe(true);
    });

    it("fires email when goal set and changed page has no judgment (judge errored)", async () => {
      const result = await sendMonitoringEmailSummary(
        buildArgs({
          goal: "track price changes",
          emailEnabled: true,
          pages: [{ status: "changed", meaningful: null }],
        }),
      );
      expect(result.attempted).toBe(true);
    });

    it("fires email when goal set but page status is new/removed (always meaningful)", async () => {
      const result = await sendMonitoringEmailSummary(
        buildArgs({
          goal: "track anything",
          emailEnabled: true,
          pages: [{ status: "changed", meaningful: false }, { status: "new" }],
        }),
      );
      expect(result.attempted).toBe(true);
    });

    it("backwards compat: no goal → fires email on any change (no gating)", async () => {
      const result = await sendMonitoringEmailSummary(
        buildArgs({
          goal: null,
          emailEnabled: true,
          pages: [{ status: "changed", meaningful: false }],
        }),
      );
      expect(result.attempted).toBe(true);
    });

    it("fails open when changed-page list is truncated (would otherwise suppress)", async () => {
      // Only noise is visible. Delivery depends on the truncated changed_count:
      // a complete all-noise list would be suppressed.
      const args = buildArgs({
        goal: "track price changes",
        emailEnabled: true,
        pages: [
          {
            status: "changed",
            meaningful: false,
            url: "https://example.com/clock",
            reason: "Only the timestamp moved",
          },
          {
            status: "changed",
            meaningful: false,
            url: "https://example.com/ads",
            reason: "A recommended link rotated",
          },
        ],
      });
      (args.check as any).changed_count = 50;
      const result = await sendMonitoringEmailSummary(args);
      expect(result.attempted).toBe(true);
      expect(mockResendSend).toHaveBeenCalled();
    });

    it("hides window noise without quoting it as the full changed total", async () => {
      const args = buildArgs({
        goal: "track price changes",
        emailEnabled: true,
        pages: [
          {
            status: "changed",
            meaningful: true,
            url: "https://example.com/price",
            reason: "Pro price changed",
          },
          {
            status: "changed",
            meaningful: false,
            url: "https://example.com/clock",
            reason: "Only the timestamp moved",
          },
        ],
      });
      (args.check as any).changed_count = 50;
      const result = await sendMonitoringEmailSummary(args);
      expect(result.attempted).toBe(true);
      const html = sentHtml();
      expect(html).toContain("https://example.com/price");
      expect(html).not.toContain("https://example.com/clock");
      expect(html).toContain("Changed: 50 (1 meaningful)");
      expect(html).not.toContain("noise omitted");
      expect(html).not.toContain("0 noise");
    });

    function sentHtml(): string {
      expect(mockResendSend).toHaveBeenCalled();
      return mockResendSend.mock.calls[0][0].html as string;
    }

    it("omits noise-judged changed pages from a mixed alert and keeps the tally honest", async () => {
      const result = await sendMonitoringEmailSummary(
        buildArgs({
          goal: "track price changes",
          emailEnabled: true,
          pages: [
            {
              status: "changed",
              meaningful: true,
              url: "https://example.com/price",
              reason: "Pro price changed",
            },
            {
              status: "changed",
              meaningful: false,
              url: "https://example.com/clock",
              reason: "Only the timestamp moved",
            },
            {
              status: "changed",
              meaningful: null,
              url: "https://example.com/unjudged",
            },
            {
              status: "new",
              meaningful: false,
              url: "https://example.com/new-page",
              reason: "A new page stays even when judged noise",
            },
            {
              status: "removed",
              meaningful: false,
              url: "https://example.com/removed-page",
              reason: "A removed page stays even when judged noise",
            },
            {
              status: "error",
              meaningful: false,
              url: "https://example.com/error-page",
              reason: "An error page stays even when judged noise",
            },
          ],
        }),
      );
      expect(result.attempted).toBe(true);
      const html = sentHtml();
      expect(html).toContain("https://example.com/price");
      expect(html).toContain("Pro price changed");
      expect(html).toContain("https://example.com/unjudged");
      expect(html).toContain("https://example.com/new-page");
      expect(html).toContain("A new page stays even when judged noise");
      expect(html).toContain("https://example.com/removed-page");
      expect(html).toContain("A removed page stays even when judged noise");
      expect(html).toContain("https://example.com/error-page");
      expect(html).toContain("An error page stays even when judged noise");
      expect(html).not.toContain("https://example.com/clock");
      expect(html).not.toContain("Only the timestamp moved");
      expect(html).toContain("[noise]");
      expect(html).toContain(
        "Changed: 3 (1 meaningful, 3 noise, 1 noise omitted)",
      );
      expect(html).toContain("New: 1");
      expect(html).toContain("Removed: 1");
      expect(html).toContain("Errors: 1");
      expect(html).toContain("Top pages:");
    });

    it("does not list noise pages or an empty page heading when only unseen activity remains", async () => {
      const args = buildArgs({
        goal: "track price changes",
        emailEnabled: true,
        pages: [
          {
            status: "changed",
            meaningful: false,
            url: "https://example.com/clock",
            reason: "Only the timestamp moved",
          },
        ],
      });
      // The page window is entirely noise, but the check counters report new
      // pages outside that window, so the email still sends.
      (args.check as { new_count: number }).new_count = 2;
      const result = await sendMonitoringEmailSummary(args);
      expect(result.attempted).toBe(true);
      const html = sentHtml();
      expect(html).not.toContain("https://example.com/clock");
      expect(html).not.toContain("Top pages:");
      expect(html).toContain("Changed: 1 (0 meaningful, 1 noise omitted)");
      expect(html).toContain("New: 2");
    });

    it("still lists noise pages when judging is disabled", async () => {
      const result = await sendMonitoringEmailSummary(
        buildArgs({
          goal: "track price changes",
          judgeEnabled: false,
          emailEnabled: true,
          pages: [
            {
              status: "changed",
              meaningful: false,
              url: "https://example.com/clock",
              reason: "Only the timestamp moved",
            },
          ],
        }),
      );
      expect(result.attempted).toBe(true);
      const html = sentHtml();
      expect(html).toContain("https://example.com/clock");
      expect(html).toContain("Only the timestamp moved");
      expect(html).toContain("[noise]");
      expect(html).toContain("Changed: 1 (0 meaningful, 1 noise)");
      expect(html).not.toContain("noise omitted");
    });

    it("still lists noise pages when the goal is empty", async () => {
      const result = await sendMonitoringEmailSummary(
        buildArgs({
          goal: "",
          judgeEnabled: true,
          emailEnabled: true,
          pages: [
            {
              status: "changed",
              meaningful: false,
              url: "https://example.com/clock",
              reason: "Only the timestamp moved",
            },
          ],
        }),
      );
      expect(result.attempted).toBe(true);
      const html = sentHtml();
      expect(html).toContain("https://example.com/clock");
      expect(html).not.toContain("noise omitted");
    });

    it("fails open when counters report new/error pages beyond the truncated list", async () => {
      const args = buildArgs({
        goal: "track price changes",
        emailEnabled: true,
        pages: [
          { status: "changed", meaningful: false },
          { status: "changed", meaningful: false },
        ],
      });
      // The visible page list is all noise, but the check aggregates report new
      // pages that fell outside the 100-page window — the email must still fire.
      (args.check as any).new_count = 5;
      const result = await sendMonitoringEmailSummary(args);
      expect(result.attempted).toBe(true);
    });
  });

  describe("opt-in gating", () => {
    it("skips entirely when no recipients have confirmed", async () => {
      mockListRecipients.mockResolvedValue([
        fakeRecipient("[email protected]", "pending"),
      ]);
      const result = await sendMonitoringEmailSummary(
        buildArgs({
          emailEnabled: true,
          recipients: ["[email protected]"],
          pages: [{ status: "changed" }],
        }),
      );
      expect(result.attempted).toBe(false);
      expect(result.recipients).toEqual([]);
      expect(result.pendingRecipients).toBe(1);
      expect(mockResendSend).not.toHaveBeenCalled();
    });

    it("skips unsubscribed recipients but emails confirmed ones", async () => {
      mockListRecipients.mockResolvedValue([
        fakeRecipient("[email protected]", "confirmed"),
        fakeRecipient("[email protected]", "unsubscribed"),
      ]);
      const result = await sendMonitoringEmailSummary(
        buildArgs({
          emailEnabled: true,
          recipients: ["[email protected]", "[email protected]"],
          pages: [{ status: "changed" }],
        }),
      );
      expect(result.attempted).toBe(true);
      expect(result.recipients).toEqual(["[email protected]"]);
      expect(result.unsubscribedRecipients).toBe(1);
      expect(mockResendSend).toHaveBeenCalledTimes(1);
      expect(mockResendSend.mock.calls[0][0].to).toBe("[email protected]");
    });

    it("sends one email per recipient with a unique unsubscribe link", async () => {
      mockListRecipients.mockResolvedValue([
        fakeRecipient("[email protected]", "confirmed"),
        fakeRecipient("[email protected]", "confirmed"),
      ]);
      const result = await sendMonitoringEmailSummary(
        buildArgs({
          emailEnabled: true,
          recipients: ["[email protected]", "[email protected]"],
          pages: [{ status: "changed" }],
        }),
      );
      expect(result.attempted).toBe(true);
      expect(mockResendSend).toHaveBeenCalledTimes(2);
      const calls = mockResendSend.mock.calls.map(c => c[0]);
      const aCall = calls.find(c => c.to === "[email protected]");
      const bCall = calls.find(c => c.to === "[email protected]");
      expect(aCall.html).toContain("token=tok-aexamplecom");
      expect(bCall.html).toContain("token=tok-bexamplecom");
      expect(aCall.html).not.toContain("token=tok-bexamplecom");
      expect(mockTouchNotified).toHaveBeenCalledWith([
        "rec-aexamplecom",
        "rec-bexamplecom",
      ]);
    });

    it("bootstraps legacy monitors when recipient rows are entirely missing", async () => {
      mockListRecipients.mockResolvedValue([]);
      mockEnsureRecipient.mockResolvedValue({
        created: true,
        row: fakeRecipient("[email protected]", "confirmed", "legacy"),
      });

      const args = buildArgs({
        emailEnabled: true,
        recipients: ["[email protected]"],
        pages: [{ status: "changed" }],
      });
      args.monitor.created_at = "2026-01-01T00:00:00Z";

      const result = await sendMonitoringEmailSummary(args);
      expect(result.attempted).toBe(true);
      expect(result.recipients).toEqual(["[email protected]"]);
      expect(mockEnsureRecipient).toHaveBeenCalledWith({
        monitorId: "monitor-1",
        teamId: "team-1",
        input: {
          email: "[email protected]",
          source: "legacy",
          status: "confirmed",
        },
      });
    });

    it("treats missing recipients as pending when rows are partially present", async () => {
      mockListRecipients.mockResolvedValue([
        fakeRecipient("[email protected]", "confirmed"),
      ]);
      const result = await sendMonitoringEmailSummary(
        buildArgs({
          emailEnabled: true,
          recipients: ["[email protected]", "[email protected]"],
          pages: [{ status: "changed" }],
        }),
      );
      expect(result.attempted).toBe(true);
      expect(result.recipients).toEqual(["[email protected]"]);
      expect(result.pendingRecipients).toBe(1);
      expect(mockEnsureRecipient).not.toHaveBeenCalled();
    });
  });
});