Supercharge your AI agents with data from the web and beyond. Building the library for superintelligence. π₯
TypeScript aiai-agentsai-crawlerai-scrapingai-searchcrawlerdata-extractionhtml-to-markdownllmmarkdownscraperscrapingweb-crawlerweb-dataweb-data-extractionweb-scraperweb-scrapingweb-searchwebscraping
(fix/monitoring) Email Confirmation (#3645)
Nicolas84338cb51ca3
diff --git a/apps/api/src/__tests__/snips/v2/lib.ts b/apps/api/src/__tests__/snips/v2/lib.tsindex 581bde158..14f392082 100644--- a/apps/api/src/__tests__/snips/v2/lib.ts+++ b/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">;diff --git a/apps/api/src/__tests__/snips/v2/monitor.test.ts b/apps/api/src/__tests__/snips/v2/monitor.test.tsindex 12f82c1cd..55d99a81c 100644--- a/apps/api/src/__tests__/snips/v2/monitor.test.ts+++ b/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 () => {diff --git a/apps/api/src/controllers/v2/monitor.ts b/apps/api/src/controllers/v2/monitor.tsindex dae0eea83..71d51647c 100644--- a/apps/api/src/controllers/v2/monitor.ts+++ b/apps/api/src/controllers/v2/monitor.ts@@ -41,6 +41,13 @@ import {type WebhookLogRow,} from "../../services/webhook/logs";import { WebhookEvent } from "../../services/webhook";+import {+ confirmRecipientByToken,+ getMonitorNameById,+ listMonitorEmailRecipients,+ unsubscribeRecipientByToken,+} from "../../services/monitoring/email_recipients";+import { syncMonitorEmailRecipients } from "../../services/monitoring/email_recipients_sync";const logger = _logger.child({ module: "monitor-controller" });@@ -67,7 +74,17 @@ function rejectZdr(return false;}-function serializeMonitor(monitor: any) {+function serializeMonitor(+ monitor: any,+ options?: {+ emailRecipientSubscriptions?: Array<{+ email: string;+ status: "pending" | "confirmed" | "unsubscribed";+ source: "team" | "opt_in" | "legacy";+ confirmationEmailSent?: boolean;+ }>;+ },+) {return {id: monitor.id,name: monitor.name,@@ -82,6 +99,9 @@ function serializeMonitor(monitor: any) {targets: monitor.targets,webhook: monitor.webhook,notification: monitor.notification,+ ...(options?.emailRecipientSubscriptions !== undefined+ ? { emailRecipientSubscriptions: options.emailRecipientSubscriptions }+ : {}),retentionDays: monitor.retention_days,estimatedCreditsPerMonth: monitor.estimated_credits_per_month,lastCheckSummary: monitor.last_check_summary,@@ -92,6 +112,16 @@ function serializeMonitor(monitor: any) {};}+async function loadEmailRecipientSubscriptions(monitorId: string) {+ const rows = await listMonitorEmailRecipients(monitorId);+ return rows.map(r => ({+ email: r.email,+ status: r.status,+ source: r.source,+ confirmationEmailSent: r.confirmation_sent_at !== null,+ }));+}+function overlayWebhookLog<T extends { notificationStatus: any }>(serialized: T,log: WebhookLogRow | null,@@ -190,9 +220,19 @@ export async function createMonitorController(}),);+ const sync = await syncMonitorEmailRecipients({ monitor }).catch(error => {+ logger.warn("Failed to sync monitor email recipients on create", {+ error,+ monitorId: monitor.id,+ });+ return { recipients: [] };+ });+res.status(200).json({success: true,- data: serializeMonitor(monitor),+ data: serializeMonitor(monitor, {+ emailRecipientSubscriptions: sync.recipients,+ }),});}@@ -209,7 +249,7 @@ export async function listMonitorsController(res.status(200).json({success: true,- data: monitors.map(serializeMonitor),+ data: monitors.map(monitor => serializeMonitor(monitor)),});}@@ -223,9 +263,21 @@ export async function getMonitorController(return res.status(404).json({ success: false, error: "Monitor not found" });}+ const subscriptions = await loadEmailRecipientSubscriptions(monitorId).catch(+ error => {+ logger.warn("Failed to load email recipient subscriptions", {+ error,+ monitorId,+ });+ return [];+ },+ );+res.status(200).json({success: true,- data: serializeMonitor(monitor),+ data: serializeMonitor(monitor, {+ emailRecipientSubscriptions: subscriptions,+ }),});}@@ -303,9 +355,28 @@ export async function updateMonitorController(}),);+ // Only re-sync when notification config actually changed.+ let subscriptions: Awaited<+ ReturnType<typeof loadEmailRecipientSubscriptions>+ > = [];+ if (input.notification !== undefined) {+ const sync = await syncMonitorEmailRecipients({ monitor }).catch(error => {+ logger.warn("Failed to sync monitor email recipients on update", {+ error,+ monitorId: monitor.id,+ });+ return { recipients: [] };+ });+ subscriptions = sync.recipients;+ } else {+ subscriptions = await loadEmailRecipientSubscriptions(monitor.id);+ }+res.status(200).json({success: true,- data: serializeMonitor(monitor),+ data: serializeMonitor(monitor, {+ emailRecipientSubscriptions: subscriptions,+ }),});}@@ -500,3 +571,138 @@ export async function getMonitorCheckController(},});}++// Unauthenticated POST endpoints β the token is the credential. Backs the+// firecrawl-web confirm/unsubscribe pages; POST-only so passive GET scanners+// can't consume tokens against the dashboard URL.++const emailActionBodySchema = z.object({+ // 32-byte base64url is 43 chars; range leaves room for future formats.+ token: z.string().min(16).max(64),+});++type EmailActionResponse =+ | {+ success: true;+ result: "confirmed" | "already_confirmed" | "unsubscribed" | "already_unsubscribed";+ email: string;+ monitorName: string | null;+ }+ | {+ success: false;+ error: "invalid_token" | "not_found" | "internal_error";+ };+++function parseTokenFromRequest(req: { body?: unknown }): string | null {+ const candidate =+ req.body && typeof req.body === "object"+ ? (req.body as { token?: unknown }).token+ : null;+ const parsed = emailActionBodySchema.safeParse({ token: candidate });+ return parsed.success ? parsed.data.token : null;+}++export async function confirmMonitorEmailController(+ req: { body?: unknown },+ res: Response,+) {+ const token = parseTokenFromRequest(req);+ if (!token) {+ const body: EmailActionResponse = {+ success: false,+ error: "invalid_token",+ };+ return res.status(400).json(body);+ }++ try {+ const row = await confirmRecipientByToken(token);+ if (!row) {+ const body: EmailActionResponse = {+ success: false,+ error: "not_found",+ };+ return res.status(404).json(body);+ }++ const monitorName = await getMonitorNameById(row.monitor_id);++ // Heuristic: if confirmed_at is older than 5s, this call was a no-op+ // (already confirmed). Used only to flavor the rendered page.+ let result: "confirmed" | "already_confirmed" | "already_unsubscribed";+ if (row.status === "unsubscribed") {+ result = "already_unsubscribed";+ } else if (+ row.confirmed_at !== null &&+ new Date().getTime() - new Date(row.confirmed_at).getTime() > 5_000+ ) {+ result = "already_confirmed";+ } else {+ result = "confirmed";+ }++ const body: EmailActionResponse = {+ success: true,+ result,+ email: row.email,+ monitorName,+ };+ return res.status(200).json(body);+ } catch (error) {+ logger.error("Failed to confirm monitor email recipient", { error });+ const body: EmailActionResponse = {+ success: false,+ error: "internal_error",+ };+ return res.status(500).json(body);+ }+}++export async function unsubscribeMonitorEmailController(+ req: { body?: unknown },+ res: Response,+) {+ const token = parseTokenFromRequest(req);+ if (!token) {+ const body: EmailActionResponse = {+ success: false,+ error: "invalid_token",+ };+ return res.status(400).json(body);+ }++ try {+ const row = await unsubscribeRecipientByToken(token);+ if (!row) {+ const body: EmailActionResponse = {+ success: false,+ error: "not_found",+ };+ return res.status(404).json(body);+ }++ const monitorName = await getMonitorNameById(row.monitor_id);++ const result: "unsubscribed" | "already_unsubscribed" =+ row.unsubscribed_at !== null &&+ new Date().getTime() - new Date(row.unsubscribed_at).getTime() > 5_000+ ? "already_unsubscribed"+ : "unsubscribed";++ const body: EmailActionResponse = {+ success: true,+ result,+ email: row.email,+ monitorName,+ };+ return res.status(200).json(body);+ } catch (error) {+ logger.error("Failed to unsubscribe monitor email recipient", { error });+ const body: EmailActionResponse = {+ success: false,+ error: "internal_error",+ };+ return res.status(500).json(body);+ }+}diff --git a/apps/api/src/routes/v2.ts b/apps/api/src/routes/v2.tsindex e7b6e9e35..77e8f57e3 100644--- a/apps/api/src/routes/v2.ts+++ b/apps/api/src/routes/v2.ts@@ -68,6 +68,7 @@ import {scrapeStopInteractiveBrowserController,} from "../controllers/v2/scrape-browser";import {+ confirmMonitorEmailController,createMonitorController,deleteMonitorController,getMonitorCheckController,@@ -75,6 +76,7 @@ import {listMonitorChecksController,listMonitorsController,runMonitorController,+ unsubscribeMonitorEmailController,updateMonitorController,} from "../controllers/v2/monitor";@@ -484,6 +486,14 @@ v2Router.get(wrap(listMonitorsController),);+// Public, unauthenticated β token in body is the credential. Registered+// before /monitor/:monitorId so "email" isn't parsed as a monitor UUID.+v2Router.post("/monitor/email/confirm", wrap(confirmMonitorEmailController));+v2Router.post(+ "/monitor/email/unsubscribe",+ wrap(unsubscribeMonitorEmailController),+);+v2Router.get("/monitor/:monitorId",authMiddleware(RateLimiterMode.CrawlStatus),diff --git a/apps/api/src/services/monitoring/email_recipients.test.ts b/apps/api/src/services/monitoring/email_recipients.test.tsnew file mode 100644index 000000000..8e7b60e2d--- /dev/null+++ b/apps/api/src/services/monitoring/email_recipients.test.ts@@ -0,0 +1,313 @@+type QueryResult = { data: unknown; error: unknown };+type ChainOp = "select" | "insert" | "update" | "delete" | "unknown";+type ClientKind = "primary" | "rr";++type CallRecord = { client: ClientKind; op: ChainOp };++const fromPrimary = jest.fn();+const fromRR = jest.fn();+const calls: CallRecord[] = [];++// Each test queues responses in the order the code under test will execute+// queries. The fluent chain swallows any sequence of select/insert/update/+// eq/neq calls and resolves at .maybeSingle() / .single() with the next+// queued result. Tests stay explicit about query order without coupling to+// the precise method chain shape.+type QueuedResponse = (+ client: ClientKind,+ op: ChainOp,+) => Promise<QueryResult>;+let queue: QueuedResponse[] = [];++function queueResponses(responses: QueuedResponse[]): void {+ queue = [...responses];+}++function makeChain(client: ClientKind): any {+ let op: ChainOp | null = null;+ const setOp = (next: ChainOp) => {+ if (op === null) op = next;+ };+ const resolve = (): Promise<QueryResult> => {+ const finalOp = op ?? "unknown";+ calls.push({ client, op: finalOp });+ const next = queue.shift();+ if (!next) {+ throw new Error(+ `No queued Supabase response for client=${client} op=${finalOp} (queue exhausted)`,+ );+ }+ return next(client, finalOp);+ };+ const builder: any = {+ select: () => {+ setOp("select");+ return builder;+ },+ insert: () => {+ setOp("insert");+ return builder;+ },+ update: () => {+ setOp("update");+ return builder;+ },+ delete: () => {+ setOp("delete");+ return builder;+ },+ eq: () => builder,+ neq: () => builder,+ in: () => builder,+ maybeSingle: resolve,+ single: resolve,+ };+ return builder;+}++jest.mock("../supabase", () => ({+ supabase_service: {+ from: (...args: unknown[]) => fromPrimary(...args),+ },+ supabase_rr_service: {+ from: (...args: unknown[]) => fromRR(...args),+ },+}));++import {+ confirmRecipientByToken,+ ensureMonitorEmailRecipient,+ unsubscribeRecipientByToken,+} from "./email_recipients";++beforeEach(() => {+ queue = [];+ calls.length = 0;+ fromPrimary.mockReset();+ fromRR.mockReset();+ fromPrimary.mockImplementation(() => makeChain("primary"));+ fromRR.mockImplementation(() => makeChain("rr"));+});++function recipientRow(overrides: Record<string, unknown> = {}) {+ return {+ id: "rec-1",+ monitor_id: "monitor-1",+ team_id: "team-1",+ email: "[email protected]",+ status: "pending",+ token: "tok-1",+ source: "opt_in",+ confirmation_sent_at: null,+ confirmed_at: null,+ unsubscribed_at: null,+ last_notified_at: null,+ created_at: "now",+ updated_at: "now",+ ...overrides,+ };+}++const baseEnsureInput = {+ monitorId: "monitor-1",+ teamId: "team-1",+ input: {+ email: "[email protected]",+ source: "opt_in" as const,+ status: "pending" as const,+ },+};++const ok = (data: unknown): QueuedResponse => () =>+ Promise.resolve({ data, error: null });+const fail = (error: unknown): QueuedResponse => () =>+ Promise.resolve({ data: null, error });++describe("ensureMonitorEmailRecipient", () => {+ it("returns existing row when the recipient already exists (no insert)", async () => {+ const existing = recipientRow({ status: "confirmed", source: "team" });+ queueResponses([ok(existing)]);++ const result = await ensureMonitorEmailRecipient(baseEnsureInput);++ expect(result).toEqual({ row: existing, created: false });+ expect(queue.length).toBe(0);+ });++ it("inserts and returns created=true when no row exists", async () => {+ const inserted = recipientRow();+ queueResponses([ok(null), ok(inserted)]);++ const result = await ensureMonitorEmailRecipient(baseEnsureInput);++ expect(result).toEqual({ row: inserted, created: true });+ });++ it("treats a concurrent-insert unique violation as not-created (no throw)", async () => {+ const winnerRow = recipientRow({ id: "rec-winner" });+ queueResponses([+ ok(null),+ fail({ code: "23505", message: "duplicate key" }),+ ok(winnerRow),+ ]);++ const result = await ensureMonitorEmailRecipient(baseEnsureInput);++ expect(result).toEqual({ row: winnerRow, created: false });+ // The race-recovery re-fetch MUST hit the primary; the read replica may+ // not yet have the row the concurrent writer just committed.+ expect(calls.map(c => ({ client: c.client, op: c.op }))).toEqual([+ { client: "rr", op: "select" },+ { client: "primary", op: "insert" },+ { client: "primary", op: "select" },+ ]);+ });++ it("rethrows non-unique insert errors", async () => {+ queueResponses([+ ok(null),+ fail({ code: "42501", message: "permission denied" }),+ ]);++ await expect(ensureMonitorEmailRecipient(baseEnsureInput)).rejects.toThrow(+ /permission denied/,+ );+ });++ it("rethrows unique violations when no winning row can be re-fetched", async () => {+ queueResponses([+ ok(null),+ fail({ code: "23505", message: "duplicate key" }),+ ok(null),+ ]);++ await expect(ensureMonitorEmailRecipient(baseEnsureInput)).rejects.toThrow(+ /duplicate key/,+ );+ });+});++describe("confirmRecipientByToken", () => {+ it("transitions pending β confirmed when no race", async () => {+ const pending = recipientRow({ status: "pending" });+ const confirmed = recipientRow({+ status: "confirmed",+ confirmed_at: "now",+ });+ queueResponses([ok(pending), ok(confirmed)]);++ const result = await confirmRecipientByToken("tok-1");++ expect(result).toEqual(confirmed);+ });++ it("returns the row unchanged when status is already confirmed (no UPDATE)", async () => {+ const confirmed = recipientRow({+ status: "confirmed",+ confirmed_at: "now",+ });+ queueResponses([ok(confirmed)]);++ const result = await confirmRecipientByToken("tok-1");++ expect(result).toEqual(confirmed);+ });++ it("returns the row unchanged when status is unsubscribed (no UPDATE)", async () => {+ const unsubscribed = recipientRow({+ status: "unsubscribed",+ unsubscribed_at: "now",+ });+ queueResponses([ok(unsubscribed)]);++ const result = await confirmRecipientByToken("tok-1");++ expect(result).toEqual(unsubscribed);+ });++ it("does NOT overwrite a racing unsubscribe β refetches and returns it", async () => {+ // SELECT sees pending, but between SELECT and our conditional UPDATE+ // another caller unsubscribed the row. The UPDATE WHERE status='pending'+ // affects 0 rows, and we re-fetch to discover the unsubscribed state.+ const pending = recipientRow({ status: "pending" });+ const unsubscribed = recipientRow({+ status: "unsubscribed",+ unsubscribed_at: "now",+ });+ queueResponses([ok(pending), ok(null), ok(unsubscribed)]);++ const result = await confirmRecipientByToken("tok-1");++ expect(result).toEqual(unsubscribed);+ expect(result?.status).toBe("unsubscribed");+ // The post-UPDATE re-fetch MUST hit primary so we don't get a stale+ // 'pending' from the read replica right after our conditional write.+ expect(calls[calls.length - 1]).toEqual({+ client: "primary",+ op: "select",+ });+ });+});++describe("unsubscribeRecipientByToken", () => {+ it("transitions pending β unsubscribed when no race", async () => {+ const pending = recipientRow({ status: "pending" });+ const unsubscribed = recipientRow({+ status: "unsubscribed",+ unsubscribed_at: "now",+ });+ queueResponses([ok(pending), ok(unsubscribed)]);++ const result = await unsubscribeRecipientByToken("tok-1");++ expect(result).toEqual(unsubscribed);+ });++ it("transitions confirmed β unsubscribed when no race", async () => {+ const confirmed = recipientRow({+ status: "confirmed",+ confirmed_at: "now",+ });+ const unsubscribed = recipientRow({+ status: "unsubscribed",+ unsubscribed_at: "now",+ });+ queueResponses([ok(confirmed), ok(unsubscribed)]);++ const result = await unsubscribeRecipientByToken("tok-1");++ expect(result).toEqual(unsubscribed);+ });++ it("returns the row unchanged when already unsubscribed (no UPDATE)", async () => {+ const unsubscribed = recipientRow({+ status: "unsubscribed",+ unsubscribed_at: "now",+ });+ queueResponses([ok(unsubscribed)]);++ const result = await unsubscribeRecipientByToken("tok-1");++ expect(result).toEqual(unsubscribed);+ });++ it("handles a racing unsubscribe by re-fetching the terminal state", async () => {+ // SELECT sees pending; concurrent caller unsubscribes; our conditional+ // UPDATE WHERE status != 'unsubscribed' affects 0 rows. Re-fetch+ // confirms the terminal state.+ const pending = recipientRow({ status: "pending" });+ const alreadyUnsub = recipientRow({+ status: "unsubscribed",+ unsubscribed_at: "now",+ });+ queueResponses([ok(pending), ok(null), ok(alreadyUnsub)]);++ const result = await unsubscribeRecipientByToken("tok-1");++ expect(result).toEqual(alreadyUnsub);+ expect(calls[calls.length - 1]).toEqual({+ client: "primary",+ op: "select",+ });+ });+});diff --git a/apps/api/src/services/monitoring/email_recipients.ts b/apps/api/src/services/monitoring/email_recipients.tsnew file mode 100644index 000000000..b46186b98--- /dev/null+++ b/apps/api/src/services/monitoring/email_recipients.ts@@ -0,0 +1,317 @@+import { randomBytes } from "crypto";+import { logger as _logger } from "../../lib/logger";+import { supabase_rr_service, supabase_service } from "../supabase";++const logger = _logger.child({ module: "monitor-email-recipients" });++const POSTGRES_UNIQUE_VIOLATION = "23505";++export type MonitorEmailRecipientStatus =+ | "pending"+ | "confirmed"+ | "unsubscribed";++export type MonitorEmailRecipientSource = "team" | "opt_in" | "legacy";++export type MonitorEmailRecipientRow = {+ id: string;+ monitor_id: string;+ team_id: string;+ email: string;+ status: MonitorEmailRecipientStatus;+ token: string;+ source: MonitorEmailRecipientSource;+ confirmation_sent_at: string | null;+ confirmed_at: string | null;+ unsubscribed_at: string | null;+ last_notified_at: string | null;+ created_at: string;+ updated_at: string;+};++export function normalizeRecipientEmail(email: string): string {+ return email.trim().toLowerCase();+}++// 32 bytes β 43 chars base64url, no padding. 256 bits of entropy.+export function generateRecipientToken(): string {+ return randomBytes(32).toString("base64url");+}++function throwIfError(error: any, message: string): void {+ if (error) {+ throw new Error(`${message}: ${error.message ?? JSON.stringify(error)}`);+ }+}++export async function listMonitorEmailRecipients(+ monitorId: string,+): Promise<MonitorEmailRecipientRow[]> {+ const { data, error } = await supabase_rr_service+ .from("monitor_email_recipients")+ .select("*")+ .eq("monitor_id", monitorId);++ throwIfError(error, "Failed to list monitor email recipients");+ return (data ?? []) as MonitorEmailRecipientRow[];+}++export async function getRecipientByToken(+ token: string,+): Promise<MonitorEmailRecipientRow | null> {+ const trimmed = token.trim();+ if (!trimmed) return null;++ const { data, error } = await supabase_rr_service+ .from("monitor_email_recipients")+ .select("*")+ .eq("token", trimmed)+ .maybeSingle();++ throwIfError(error, "Failed to look up monitor email recipient by token");+ return (data ?? null) as MonitorEmailRecipientRow | null;+}++export async function getMonitorNameById(+ monitorId: string,+): Promise<string | null> {+ const { data, error } = await supabase_rr_service+ .from("monitors")+ .select("name")+ .eq("id", monitorId)+ .maybeSingle();++ if (error) {+ logger.warn("Failed to load monitor name for opt-in response", {+ error,+ monitorId,+ });+ return null;+ }+ return (data?.name as string | undefined) ?? null;+}++// Team members are auto-confirmed; they already have dashboard access.+export async function getTeamMemberEmails(+ teamId: string,+ emails: string[],+): Promise<Set<string>> {+ if (emails.length === 0) return new Set();++ const { data, error } = await supabase_rr_service+ .from("user_teams")+ .select("users(email)")+ .eq("team_id", teamId);++ if (error) {+ logger.warn("Failed to load team member emails for recipient sync", {+ error,+ teamId,+ });+ return new Set();+ }++ const wanted = new Set(emails.map(normalizeRecipientEmail));+ const matches = new Set<string>();+ for (const row of data ?? []) {+ const email = (row as any).users?.email;+ if (typeof email === "string") {+ const normalized = normalizeRecipientEmail(email);+ if (wanted.has(normalized)) matches.add(normalized);+ }+ }+ return matches;+}++export type RecipientUpsertInput = {+ email: string;+ source: MonitorEmailRecipientSource;+ status: MonitorEmailRecipientStatus;+};++export type RecipientUpsertResult = {+ row: MonitorEmailRecipientRow;+ created: boolean;+};++async function fetchRecipientByMonitorEmail(+ monitorId: string,+ email: string,+): Promise<MonitorEmailRecipientRow | null> {+ const { data, error } = await supabase_rr_service+ .from("monitor_email_recipients")+ .select("*")+ .eq("monitor_id", monitorId)+ .eq("email", email)+ .maybeSingle();+ throwIfError(error, "Failed to look up monitor email recipient");+ return (data ?? null) as MonitorEmailRecipientRow | null;+}++// Read replicas can lag behind a freshly-committed INSERT, which is exactly+// the moment this re-fetch runs (the concurrent writer just won the unique+// race). Reading from the primary guarantees we see their row.+async function fetchRecipientByMonitorEmailPrimary(+ monitorId: string,+ email: string,+): Promise<MonitorEmailRecipientRow | null> {+ const { data, error } = await supabase_service+ .from("monitor_email_recipients")+ .select("*")+ .eq("monitor_id", monitorId)+ .eq("email", email)+ .maybeSingle();+ throwIfError(error, "Failed to look up monitor email recipient");+ return (data ?? null) as MonitorEmailRecipientRow | null;+}++// Same rationale as ...Primary above: a conditional UPDATE just landed, so+// the replica may not have caught up yet when we re-read.+async function fetchRecipientByIdPrimary(+ id: string,+): Promise<MonitorEmailRecipientRow | null> {+ const { data, error } = await supabase_service+ .from("monitor_email_recipients")+ .select("*")+ .eq("id", id)+ .maybeSingle();+ throwIfError(error, "Failed to look up monitor email recipient by id");+ return (data ?? null) as MonitorEmailRecipientRow | null;+}++// Idempotent: existing rows are returned unchanged so prior unsubscribe+// decisions persist across monitor edits. The unique (monitor_id, email)+// constraint is the source of truth β a TOCTOU between the SELECT and the+// INSERT below is caught via the unique-violation handler so concurrent+// syncs of the same monitor return the same row instead of 500ing.+export async function ensureMonitorEmailRecipient(params: {+ monitorId: string;+ teamId: string;+ input: RecipientUpsertInput;+}): Promise<RecipientUpsertResult> {+ const email = normalizeRecipientEmail(params.input.email);++ const existing = await fetchRecipientByMonitorEmail(params.monitorId, email);+ if (existing) {+ return { row: existing, created: false };+ }++ const now = new Date().toISOString();+ const insert = {+ monitor_id: params.monitorId,+ team_id: params.teamId,+ email,+ status: params.input.status,+ token: generateRecipientToken(),+ source: params.input.source,+ confirmation_sent_at: params.input.status === "pending" ? now : null,+ confirmed_at: params.input.status === "confirmed" ? now : null,+ created_at: now,+ updated_at: now,+ };++ const { data, error } = await supabase_service+ .from("monitor_email_recipients")+ .insert(insert)+ .select("*")+ .maybeSingle();++ if (error) {+ if ((error as { code?: string }).code === POSTGRES_UNIQUE_VIOLATION) {+ const winner = await fetchRecipientByMonitorEmailPrimary(+ params.monitorId,+ email,+ );+ if (winner) {+ return { row: winner, created: false };+ }+ }+ throwIfError(error, "Failed to insert monitor email recipient");+ }++ return { row: data as MonitorEmailRecipientRow, created: true };+}++export async function markRecipientConfirmationSent(+ id: string,+): Promise<void> {+ const now = new Date().toISOString();+ const { error } = await supabase_service+ .from("monitor_email_recipients")+ .update({ confirmation_sent_at: now, updated_at: now })+ .eq("id", id);++ throwIfError(error, "Failed to mark recipient confirmation sent");+}++export async function confirmRecipientByToken(+ token: string,+): Promise<MonitorEmailRecipientRow | null> {+ const row = await getRecipientByToken(token);+ if (!row) return null;+ if (row.status === "confirmed") return row;++ // Unsubscribe is permanent β never let a confirm link reverse it.+ if (row.status === "unsubscribed") return row;++ // Conditional UPDATE: only transition pending β confirmed. If status flips+ // (e.g. concurrent unsubscribe) between our SELECT and this UPDATE we+ // affect 0 rows; re-fetch and return the actual current state so an+ // in-flight confirm can't silently overwrite a terminal unsubscribe.+ const now = new Date().toISOString();+ const { data, error } = await supabase_service+ .from("monitor_email_recipients")+ .update({ status: "confirmed", confirmed_at: now, updated_at: now })+ .eq("id", row.id)+ .eq("status", "pending")+ .select("*")+ .maybeSingle();++ throwIfError(error, "Failed to confirm monitor email recipient");+ if (data) return data as MonitorEmailRecipientRow;++ return await fetchRecipientByIdPrimary(row.id);+}++export async function unsubscribeRecipientByToken(+ token: string,+): Promise<MonitorEmailRecipientRow | null> {+ const row = await getRecipientByToken(token);+ if (!row) return null;+ if (row.status === "unsubscribed") return row;++ // Conditional UPDATE: only writes when the row isn't already unsubscribed,+ // so two racing unsubscribes don't double-write timestamps. 0 rows here+ // means a concurrent call beat us to the terminal state.+ const now = new Date().toISOString();+ const { data, error } = await supabase_service+ .from("monitor_email_recipients")+ .update({ status: "unsubscribed", unsubscribed_at: now, updated_at: now })+ .eq("id", row.id)+ .neq("status", "unsubscribed")+ .select("*")+ .maybeSingle();++ throwIfError(error, "Failed to unsubscribe monitor email recipient");+ if (data) return data as MonitorEmailRecipientRow;++ return await fetchRecipientByIdPrimary(row.id);+}++export async function touchRecipientsNotified(+ ids: string[],+): Promise<void> {+ if (ids.length === 0) return;+ const now = new Date().toISOString();+ const { error } = await supabase_service+ .from("monitor_email_recipients")+ .update({ last_notified_at: now, updated_at: now })+ .in("id", ids);++ if (error) {+ logger.warn("Failed to update last_notified_at on recipients", {+ error,+ ids,+ });+ }+}diff --git a/apps/api/src/services/monitoring/email_recipients_sync.test.ts b/apps/api/src/services/monitoring/email_recipients_sync.test.tsnew file mode 100644index 000000000..4f38d06a2--- /dev/null+++ b/apps/api/src/services/monitoring/email_recipients_sync.test.ts@@ -0,0 +1,224 @@+jest.mock("../supabase", () => ({+ supabase_service: {},+ supabase_rr_service: {},+}));++const mockEnsureRecipient = jest.fn();+const mockListRecipients = jest.fn();+const mockGetTeamMemberEmails = jest.fn();++jest.mock("./email_recipients", () => {+ const actual = jest.requireActual("./email_recipients");+ return {+ ...actual,+ ensureMonitorEmailRecipient: (...args: unknown[]) =>+ mockEnsureRecipient(...args),+ listMonitorEmailRecipients: (...args: unknown[]) =>+ mockListRecipients(...args),+ getTeamMemberEmails: (...args: unknown[]) =>+ mockGetTeamMemberEmails(...args),+ };+});++const mockSendConfirmationEmail = jest.fn();+jest.mock("../notification/monitoring_email", () => ({+ sendMonitoringConfirmationEmail: (...args: unknown[]) =>+ mockSendConfirmationEmail(...args),+}));++import { syncMonitorEmailRecipients } from "./email_recipients_sync";++beforeEach(() => {+ mockEnsureRecipient.mockReset();+ mockListRecipients.mockReset();+ mockGetTeamMemberEmails.mockReset();+ mockSendConfirmationEmail.mockReset();+ mockSendConfirmationEmail.mockResolvedValue({+ attempted: true,+ success: true,+ });+});++function recipientRow(+ email: string,+ status: "pending" | "confirmed" | "unsubscribed",+ source: "team" | "opt_in" | "legacy",+) {+ return {+ id: `rec-${email}`,+ monitor_id: "monitor-1",+ team_id: "team-1",+ email,+ status,+ token: `tok-${email}`,+ 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(),+ };+}++function monitor(recipients: string[]): any {+ return {+ id: "monitor-1",+ team_id: "team-1",+ name: "Test monitor",+ notification: {+ email: { enabled: true, recipients },+ },+ };+}++describe("syncMonitorEmailRecipients", () => {+ it("returns nothing when there are no configured recipients", async () => {+ const result = await syncMonitorEmailRecipients({+ monitor: monitor([]),+ });+ expect(result.recipients).toEqual([]);+ expect(mockEnsureRecipient).not.toHaveBeenCalled();+ });++ it("auto-confirms team members without sending confirmation email", async () => {+ mockListRecipients.mockResolvedValue([]);+ mockGetTeamMemberEmails.mockResolvedValue(new Set(["[email protected]"]));+ mockEnsureRecipient.mockImplementation(async ({ input }) => ({+ row: recipientRow(input.email, "confirmed", "team"),+ created: true,+ }));++ const result = await syncMonitorEmailRecipients({+ monitor: monitor(["[email protected]"]),+ });++ expect(mockEnsureRecipient).toHaveBeenCalledWith({+ monitorId: "monitor-1",+ teamId: "team-1",+ input: { email: "[email protected]", source: "team", status: "confirmed" },+ });+ expect(mockSendConfirmationEmail).not.toHaveBeenCalled();+ expect(result.recipients[0]).toMatchObject({+ email: "[email protected]",+ status: "confirmed",+ source: "team",+ created: true,+ });+ });++ it("sends a confirmation email to brand new external recipients", async () => {+ mockListRecipients.mockResolvedValue([]);+ mockGetTeamMemberEmails.mockResolvedValue(new Set());+ mockEnsureRecipient.mockImplementation(async ({ input }) => ({+ row: recipientRow(input.email, "pending", "opt_in"),+ created: true,+ }));++ const result = await syncMonitorEmailRecipients({+ monitor: monitor(["[email protected]"]),+ });++ expect(mockEnsureRecipient).toHaveBeenCalledWith({+ monitorId: "monitor-1",+ teamId: "team-1",+ input: {+ email: "[email protected]",+ source: "opt_in",+ status: "pending",+ },+ });+ expect(mockSendConfirmationEmail).toHaveBeenCalledTimes(1);+ expect(result.recipients[0]).toMatchObject({+ email: "[email protected]",+ status: "pending",+ source: "opt_in",+ confirmationEmailSent: true,+ created: true,+ });+ });++ it("does not re-send a confirmation email for an existing pending recipient", async () => {+ mockListRecipients.mockResolvedValue([+ recipientRow("[email protected]", "pending", "opt_in"),+ ]);+ mockGetTeamMemberEmails.mockResolvedValue(new Set());++ const result = await syncMonitorEmailRecipients({+ monitor: monitor(["[email protected]"]),+ });++ expect(mockEnsureRecipient).not.toHaveBeenCalled();+ expect(mockSendConfirmationEmail).not.toHaveBeenCalled();+ expect(result.recipients[0]).toMatchObject({+ email: "[email protected]",+ status: "pending",+ created: false,+ });+ });++ it("preserves prior unsubscribe when the same email is re-added later", async () => {+ mockListRecipients.mockResolvedValue([+ recipientRow("[email protected]", "unsubscribed", "opt_in"),+ ]);+ mockGetTeamMemberEmails.mockResolvedValue(new Set());++ const result = await syncMonitorEmailRecipients({+ monitor: monitor(["[email protected]"]),+ });++ expect(mockEnsureRecipient).not.toHaveBeenCalled();+ expect(mockSendConfirmationEmail).not.toHaveBeenCalled();+ expect(result.recipients[0]).toMatchObject({+ email: "[email protected]",+ status: "unsubscribed",+ });+ });++ it("normalizes emails (lowercases, trims, dedupes) before reconciling", async () => {+ mockListRecipients.mockResolvedValue([]);+ mockGetTeamMemberEmails.mockResolvedValue(new Set(["[email protected]"]));+ mockEnsureRecipient.mockImplementation(async ({ input }) => ({+ row: recipientRow(input.email, "confirmed", "team"),+ created: true,+ }));++ const result = await syncMonitorEmailRecipients({+ monitor: monitor([+ "[email protected]",+ " [email protected] ",+ "[email protected]",+ ]),+ });++ expect(mockEnsureRecipient).toHaveBeenCalledTimes(1);+ expect(result.recipients).toHaveLength(1);+ expect(result.recipients[0].email).toBe("[email protected]");+ });++ it("handles a mix of team members and externals in one sync", async () => {+ mockListRecipients.mockResolvedValue([]);+ mockGetTeamMemberEmails.mockResolvedValue(new Set(["[email protected]"]));+ mockEnsureRecipient.mockImplementation(async ({ input }) => ({+ row: recipientRow(+ input.email,+ input.status,+ input.source,+ ),+ created: true,+ }));++ const result = await syncMonitorEmailRecipients({+ monitor: monitor(["[email protected]", "[email protected]"]),+ });++ expect(mockSendConfirmationEmail).toHaveBeenCalledTimes(1);+ const emailedTo = mockSendConfirmationEmail.mock.calls[0][0].recipient.email;+ expect(emailedTo).toBe("[email protected]");++ const byEmail = new Map(result.recipients.map(r => [r.email, r]));+ expect(byEmail.get("[email protected]")?.status).toBe("confirmed");+ expect(byEmail.get("[email protected]")?.status).toBe("pending");+ });+});diff --git a/apps/api/src/services/monitoring/email_recipients_sync.ts b/apps/api/src/services/monitoring/email_recipients_sync.tsnew file mode 100644index 000000000..939165752--- /dev/null+++ b/apps/api/src/services/monitoring/email_recipients_sync.ts@@ -0,0 +1,103 @@+import { logger as _logger } from "../../lib/logger";+import { sendMonitoringConfirmationEmail } from "../notification/monitoring_email";+import {+ ensureMonitorEmailRecipient,+ getTeamMemberEmails,+ listMonitorEmailRecipients,+ normalizeRecipientEmail,+ type MonitorEmailRecipientRow,+} from "./email_recipients";+import type { MonitorRow } from "./types";++const logger = _logger.child({ module: "monitor-email-recipients-sync" });++export type SyncedRecipient = {+ email: string;+ status: MonitorEmailRecipientRow["status"];+ source: MonitorEmailRecipientRow["source"];+ confirmationEmailSent: boolean;+ created: boolean;+};++export type SyncResult = {+ recipients: SyncedRecipient[];+};++// Team members β auto-confirmed. External addresses β pending + confirmation+// email. Existing rows are preserved (so a quick remove-then-re-add doesn't+// undo a prior unsubscribe or re-send a confirmation).+export async function syncMonitorEmailRecipients(params: {+ monitor: MonitorRow;+}): Promise<SyncResult> {+ const configured = params.monitor.notification?.email?.recipients ?? [];+ const normalized = Array.from(+ new Set(+ configured+ .map(normalizeRecipientEmail)+ .filter(email => email.length > 0),+ ),+ );++ if (normalized.length === 0) {+ return { recipients: [] };+ }++ const [existingRows, teamMatches] = await Promise.all([+ listMonitorEmailRecipients(params.monitor.id),+ getTeamMemberEmails(params.monitor.team_id, normalized),+ ]);+ const existingByEmail = new Map(existingRows.map(r => [r.email, r]));++ const results: SyncedRecipient[] = [];++ for (const email of normalized) {+ const existing = existingByEmail.get(email);+ if (existing) {+ results.push({+ email: existing.email,+ status: existing.status,+ source: existing.source,+ confirmationEmailSent: existing.confirmation_sent_at !== null,+ created: false,+ });+ continue;+ }++ const isTeamMember = teamMatches.has(email);+ const { row, created } = await ensureMonitorEmailRecipient({+ monitorId: params.monitor.id,+ teamId: params.monitor.team_id,+ input: {+ email,+ source: isTeamMember ? "team" : "opt_in",+ status: isTeamMember ? "confirmed" : "pending",+ },+ });++ let confirmationEmailSent = false;+ if (created && !isTeamMember && row.status === "pending") {+ const sendResult = await sendMonitoringConfirmationEmail({+ recipient: row,+ monitorName: params.monitor.name,+ }).catch(error => {+ logger.warn("Confirmation email send threw", {+ error,+ recipientId: row.id,+ monitorId: params.monitor.id,+ });+ return { attempted: true, success: false } as const;+ });+ confirmationEmailSent = sendResult.attempted && sendResult.success;+ }++ results.push({+ email: row.email,+ status: row.status,+ source: row.source,+ confirmationEmailSent,+ created,+ });+ }++ return { recipients: results };+}diff --git a/apps/api/src/services/notification/monitoring_email.test.ts b/apps/api/src/services/notification/monitoring_email.test.tsindex 22877e0a8..a568abf0d 100644--- a/apps/api/src/services/notification/monitoring_email.test.ts+++ b/apps/api/src/services/notification/monitoring_email.test.ts@@ -1,21 +1,86 @@jest.mock("../supabase", () => ({supabase_service: {},+ supabase_rr_service: {},}));+const mockEnsureRecipient = jest.fn();+const mockListRecipients = jest.fn();+const mockTouchNotified = jest.fn();+const mockMarkConfirmationSent = jest.fn();++jest.mock("../monitoring/email_recipients", () => {+ const actual = jest.requireActual("../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),+ };+});++const mockResendSend = jest.fn();jest.mock("resend", () => ({Resend: jest.fn().mockImplementation(() => ({- emails: { send: jest.fn() },+ emails: { send: mockResendSend },})),}));import {+ buildConfirmationHtml,buildHtml,buildMonitoringCheckDashboardUrl,+ buildRecipientConfirmationUrl,+ buildRecipientUnsubscribeUrl,+ sendMonitoringConfirmationEmail,sendMonitoringEmailSummary,type MonitoringEmailPayload,} from "./monitoring_email";-describe("monitoring email", () => {+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);+ process.env.RESEND_API_KEY = "test-key";+});++afterAll(() => {+ delete process.env.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(@@ -30,7 +95,19 @@ describe("monitoring email", () => {);});- it("includes the dashboard check link in the email html", () => {+ 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",@@ -57,55 +134,144 @@ describe("monitoring email", () => {},],creditsUsed: 1,+ unsubscribeUrl:+ "https://www.firecrawl.dev/monitoring/email/unsubscribe?token=tok123",};- expect(buildHtml(payload)).toContain(+ 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("sendMonitoringEmailSummary β judgment gating", () => {- function buildArgs(opts: {- goal?: string | null;- emailEnabled?: boolean;- pages: Array<{- status: string;- meaningful?: boolean | null;- }>;- }) {- return {- monitor: {- id: "monitor-1",- team_id: "team-1",- name: "Test",- goal: opts.goal ?? null,- judge_enabled: Boolean(opts.goal),- notification: opts.emailEnabled- ? { email: { enabled: true, 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: `https://example.com/${i}`,- status: p.status,- judgment:- p.meaningful === null || p.meaningful === undefined- ? null- : {- meaningful: p.meaningful,- confidence: "high" as const,- reason: "test",- fields: [],- },- })),- };- }+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("<script>");+ });+});++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;+ }>;+ }) {+ return {+ monitor: {+ id: "monitor-1",+ team_id: "team-1",+ name: "Test",+ goal: opts.goal ?? null,+ judge_enabled: 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: `https://example.com/${i}`,+ status: p.status,+ judgment:+ p.meaningful === null || p.meaningful === undefined+ ? null+ : {+ meaningful: p.meaningful,+ confidence: "high" as const,+ 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(@@ -182,4 +348,112 @@ describe("monitoring email", () => {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 result = await sendMonitoringEmailSummary(+ buildArgs({+ emailEnabled: true,+ recipients: ["[email protected]"],+ pages: [{ status: "changed" }],+ }),+ );+ 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();+ });+ });});diff --git a/apps/api/src/services/notification/monitoring_email.ts b/apps/api/src/services/notification/monitoring_email.tsindex 2670879a5..7b8a8a446 100644--- a/apps/api/src/services/notification/monitoring_email.ts+++ b/apps/api/src/services/notification/monitoring_email.ts@@ -4,9 +4,20 @@ import { config } from "../../config";import { logger as _logger } from "../../lib/logger";import { supabase_service } from "../supabase";import type { MonitorCheckRow, MonitorRow } from "../monitoring/types";+import {+ ensureMonitorEmailRecipient,+ listMonitorEmailRecipients,+ markRecipientConfirmationSent,+ normalizeRecipientEmail,+ touchRecipientsNotified,+ type MonitorEmailRecipientRow,+} from "../monitoring/email_recipients";const logger = _logger.child({ module: "monitoring-email" });+const FROM_ADDRESS = "Firecrawl <[email protected]>";+const REPLY_TO_ADDRESS = "[email protected]";+type MonitoringEmailPage = {url: string;status: string;@@ -72,6 +83,8 @@ export type MonitoringEmailPayload = {};pages: MonitoringEmailPage[];creditsUsed: number | null;+ // When omitted, the footer drops the unsubscribe row.+ unsubscribeUrl?: string;};async function getTeamEmails(teamId: string): Promise<string[]> {@@ -122,6 +135,33 @@ export function buildMonitoringCheckDashboardUrl(return url.toString();}+function buildPublicWebUrl(path: string, token: string): string {+ const base = config.FIRECRAWL_DASHBOARD_URL.trim();+ const url = new URL(path, base);+ url.searchParams.set("token", token);+ return url.toString();+}++// Email links land on the firecrawl-web pages, which POST the token to the+// API. Keeps branding consistent and stops passive link scanners (Outlook+// Safe Links, etc.) from accidentally consuming tokens with bare GETs.+export function buildRecipientConfirmationUrl(token: string): string {+ return buildPublicWebUrl("/monitoring/email/confirm", token);+}++export function buildRecipientUnsubscribeUrl(token: string): string {+ return buildPublicWebUrl("/monitoring/email/unsubscribe", token);+}++function buildUnsubscribeFooter(unsubscribeUrl: string): string {+ const safe = escapeHtml(unsubscribeUrl);+ return `<hr style="border:none;border-top:1px solid #e5e7eb;margin:24px 0 12px;" />+<p style="color:#6b7280;font-size:12px;line-height:1.6;margin:0;">+You're receiving this because you opted in to Firecrawl monitor alerts at this address.+<a href="${safe}" style="color:#6b7280;text-decoration:underline;">Unsubscribe from this monitor</a>.+</p>`;+}+export function buildHtml(payload: MonitoringEmailPayload): string {const sortedPages = [...payload.pages].sort((a, b) => {const aMeaningful = a.judgment?.meaningful === true ? 0 : 1;@@ -179,9 +219,216 @@ ${pageItems ? `<p>Top pages:</p><ul>${pageItems}</ul>` : ""}<p><a href="${dashboardUrl}">View this check in the dashboard</a></p><p>Check ID: <code>${escapeHtml(payload.checkId)}</code></p><p>Credits used: ${payload.creditsUsed ?? "unknown"}</p>+<br/>Thanks,<br/>Firecrawl Team<br/>+${payload.unsubscribeUrl ? buildUnsubscribeFooter(payload.unsubscribeUrl) : ""}`;+}++export function buildConfirmationHtml(params: {+ monitorName: string;+ recipientEmail: string;+ confirmUrl: string;+ unsubscribeUrl: string;+}): string {+ const monitorName = escapeHtml(params.monitorName);+ const recipientEmail = escapeHtml(params.recipientEmail);+ const confirmUrl = escapeHtml(params.confirmUrl);+ const unsubscribeUrl = escapeHtml(params.unsubscribeUrl);++ return `Hey there,<br/>+<p>A Firecrawl user added <strong>${recipientEmail}</strong> as a notification recipient for the monitor <strong>${monitorName}</strong>.</p>+<p>If you'd like to receive change-detection emails for this monitor, please confirm:</p>+<p style="margin:24px 0;">+ <a href="${confirmUrl}"+ style="display:inline-block;padding:10px 18px;background:#fa5d19;color:#ffffff;text-decoration:none;border-radius:8px;font-weight:600;">+ Confirm subscription+ </a>+</p>+<p style="color:#6b7280;font-size:13px;line-height:1.6;">+ If that button doesn't work, copy and paste this link into your browser:<br/>+ <a href="${confirmUrl}" style="color:#fa5d19;word-break:break-all;">${confirmUrl}</a>+</p>+<p style="color:#6b7280;font-size:13px;line-height:1.6;">+ You will not receive any monitor notifications at this address until you click the link above. If you didn't expect this email you can safely ignore it, or+ <a href="${unsubscribeUrl}" style="color:#6b7280;text-decoration:underline;">block all future emails from this monitor</a>.+</p><br/>Thanks,<br/>Firecrawl Team<br/>`;}+function getResendClient(): Resend | null {+ const key = config.RESEND_API_KEY?.trim();+ if (!key) return null;+ return new Resend(key);+}++export async function sendMonitoringConfirmationEmail(params: {+ recipient: MonitorEmailRecipientRow;+ monitorName: string;+}): Promise<{ attempted: boolean; success: boolean; error?: string }> {+ const resend = getResendClient();+ if (!resend) {+ logger.warn(+ "Skipping monitor opt-in email; RESEND_API_KEY is not set",+ {+ monitorId: params.recipient.monitor_id,+ recipientId: params.recipient.id,+ },+ );+ return { attempted: false, success: true };+ }++ const confirmUrl = buildRecipientConfirmationUrl(params.recipient.token);+ const unsubscribeUrl = buildRecipientUnsubscribeUrl(params.recipient.token);+ const html = buildConfirmationHtml({+ monitorName: params.monitorName,+ recipientEmail: params.recipient.email,+ confirmUrl,+ unsubscribeUrl,+ });++ try {+ const { error } = await resend.emails.send({+ from: FROM_ADDRESS,+ to: params.recipient.email,+ reply_to: REPLY_TO_ADDRESS,+ subject: `Confirm subscription: Firecrawl monitor "${params.monitorName}"`,+ html,+ });++ if (error) {+ logger.warn("Failed to send monitor confirmation email", {+ error,+ recipientId: params.recipient.id,+ monitorId: params.recipient.monitor_id,+ });+ return {+ attempted: true,+ success: false,+ error: typeof error === "string" ? error : JSON.stringify(error),+ };+ }++ await markRecipientConfirmationSent(params.recipient.id);+ logger.info("Sent monitor confirmation email", {+ recipientId: params.recipient.id,+ monitorId: params.recipient.monitor_id,+ });+ return { attempted: true, success: true };+ } catch (error) {+ logger.warn("Exception sending monitor confirmation email", {+ error,+ recipientId: params.recipient.id,+ });+ return {+ attempted: true,+ success: false,+ error: error instanceof Error ? error.message : String(error),+ };+ }+}++type ResolvedRecipients = {+ confirmedRecipients: MonitorEmailRecipientRow[];+ pending: number;+ unsubscribed: number;+ total: number;+};++async function resolveSendableRecipients(+ monitor: MonitorRow,+): Promise<ResolvedRecipients> {+ const configEmail = monitor.notification?.email;+ const explicitConfigured = Array.isArray(configEmail?.recipients)+ ? (configEmail!.recipients as string[])+ .map(normalizeRecipientEmail)+ .filter(Boolean)+ : [];++ if (explicitConfigured.length > 0) {+ let rows = await listMonitorEmailRecipients(monitor.id);++ // Legacy monitors (configured pre-opt-in) have zero rows; bootstrap them+ // as confirmed so existing alerts keep flowing without a DB backfill.+ // Partial-row monitors keep strict gating β missing addresses stay+ // pending rather than getting auto-confirmed.+ if (rows.length === 0) {+ const legacyRows = await Promise.all(+ explicitConfigured.map(async email => {+ const { row } = await ensureMonitorEmailRecipient({+ monitorId: monitor.id,+ teamId: monitor.team_id,+ input: {+ email,+ source: "legacy",+ status: "confirmed",+ },+ });+ return row;+ }),+ );+ rows = legacyRows;+ logger.info("Bootstrapped legacy monitor recipients without DB backfill", {+ monitorId: monitor.id,+ recipients: explicitConfigured,+ });+ }++ const rowsByEmail = new Map(rows.map(r => [r.email, r]));++ const confirmedRecipients: MonitorEmailRecipientRow[] = [];+ let pending = 0;+ let unsubscribed = 0;++ for (const email of explicitConfigured) {+ const row = rowsByEmail.get(email);+ if (!row) {+ // Recipient appears in JSONB but has no opt-in row β treat as+ // pending so we never send without an explicit record.+ pending += 1;+ continue;+ }+ if (row.status === "confirmed") {+ confirmedRecipients.push(row);+ } else if (row.status === "unsubscribed") {+ unsubscribed += 1;+ } else {+ pending += 1;+ }+ }++ return {+ confirmedRecipients,+ pending,+ unsubscribed,+ total: explicitConfigured.length,+ };+ }++ // Fallback: team members (auto-confirmed; getTeamEmails still applies+ // their global notification_preferences).+ const teamEmails = await getTeamEmails(monitor.team_id);+ const syntheticRows: MonitorEmailRecipientRow[] = await Promise.all(+ teamEmails.map(async email => {+ const { row } = await ensureMonitorEmailRecipient({+ monitorId: monitor.id,+ teamId: monitor.team_id,+ input: {+ email,+ source: "team",+ status: "confirmed",+ },+ });+ return row;+ }),+ );++ return {+ confirmedRecipients: syntheticRows.filter(r => r.status === "confirmed"),+ pending: 0,+ unsubscribed: syntheticRows.filter(r => r.status === "unsubscribed").length,+ total: teamEmails.length,+ };+}+export async function sendMonitoringEmailSummary(params: {monitor: MonitorRow;check: MonitorCheckRow;@@ -190,6 +437,8 @@ export async function sendMonitoringEmailSummary(params: {attempted: boolean;success: boolean;recipients: string[];+ pendingRecipients?: number;+ unsubscribedRecipients?: number;error?: string;}> {const configEmail = params.monitor.notification?.email;@@ -222,9 +471,8 @@ export async function sendMonitoringEmailSummary(params: {return { attempted: false, success: true, recipients: [] };}- // Caller may pass a paginated subset; only trust the judgment-based- // suppression when changedPages covers the full changed_count. A missed- // meaningful alert is worse than an extra noisy email.+ // Trust judgment-based suppression only when the changed page list is+ // complete (a missed meaningful alert is worse than a noisy one).if (params.monitor.judge_enabled && params.monitor.goal) {const changedPages = params.pages.filter(p => p.status === "changed");const nonChangedActivity = params.pages.some(@@ -264,91 +512,147 @@ export async function sendMonitoringEmailSummary(params: {}}- const explicitRecipients = configEmail.recipients ?? [];- const teamRecipients =- explicitRecipients.length > 0- ? []- : await getTeamEmails(params.monitor.team_id);- const recipients = [...new Set([...explicitRecipients, ...teamRecipients])];- if (recipients.length === 0) {- logger.info("Skipping monitoring email summary; no recipients configured", {- monitorId: params.monitor.id,- checkId: params.check.id,- });- return { attempted: false, success: true, recipients };+ const resolved = await resolveSendableRecipients(params.monitor);+ if (resolved.confirmedRecipients.length === 0) {+ logger.info(+ "Skipping monitoring email summary; no confirmed recipients",+ {+ monitorId: params.monitor.id,+ checkId: params.check.id,+ configured: resolved.total,+ pending: resolved.pending,+ unsubscribed: resolved.unsubscribed,+ },+ );+ return {+ attempted: false,+ success: true,+ recipients: [],+ pendingRecipients: resolved.pending,+ unsubscribedRecipients: resolved.unsubscribed,+ };}- const resendApiKey = config.RESEND_API_KEY?.trim();- if (!resendApiKey) {+ const resend = getResendClient();+ if (!resend) {logger.warn("Skipping monitoring email summary; RESEND_API_KEY is not set",{monitorId: params.monitor.id,checkId: params.check.id,- recipients,+ recipients: resolved.confirmedRecipients.map(r => r.email),},);- return { attempted: false, success: true, recipients };+ return {+ attempted: false,+ success: true,+ recipients: resolved.confirmedRecipients.map(r => r.email),+ pendingRecipients: resolved.pending,+ unsubscribedRecipients: resolved.unsubscribed,+ };}- const payload: MonitoringEmailPayload = {+ const dashboardUrl = buildMonitoringCheckDashboardUrl({monitorId: params.monitor.id,- monitorName: params.monitor.name,checkId: params.check.id,- dashboardUrl: buildMonitoringCheckDashboardUrl({- monitorId: params.monitor.id,- checkId: params.check.id,- }),- summary: {- changed: params.check.changed_count,- new: params.check.new_count,- removed: params.check.removed_count,- error: params.check.error_count,- totalPages: params.check.total_pages,- },- pages: params.pages,- creditsUsed: params.check.actual_credits,- };-- const resend = new Resend(resendApiKey);- try {- const { error } = await resend.emails.send({- from: "Firecrawl <[email protected]>",- to: recipients,- reply_to: "[email protected]",- subject: `Monitor changes detected: ${params.monitor.name}`,- html: buildHtml(payload),- });+ });- if (error) {- logger.warn("Monitoring email summary send failed", {+ // One email per recipient: unique unsubscribe links + no recipient leakage.+ const sendResults = await Promise.all(+ resolved.confirmedRecipients.map(async recipient => {+ const payload: MonitoringEmailPayload = {monitorId: params.monitor.id,+ monitorName: params.monitor.name,checkId: params.check.id,- recipients,- error,- });- return {- attempted: true,- success: false,- recipients,- error: typeof error === "string" ? error : JSON.stringify(error),+ dashboardUrl,+ summary: {+ changed: params.check.changed_count,+ new: params.check.new_count,+ removed: params.check.removed_count,+ error: params.check.error_count,+ totalPages: params.check.total_pages,+ },+ pages: params.pages,+ creditsUsed: params.check.actual_credits,+ unsubscribeUrl: buildRecipientUnsubscribeUrl(recipient.token),};- }- logger.info("Monitoring email summary sent", {+ try {+ const { error } = await resend.emails.send({+ from: FROM_ADDRESS,+ to: recipient.email,+ reply_to: REPLY_TO_ADDRESS,+ subject: `Monitor changes detected: ${params.monitor.name}`,+ html: buildHtml(payload),+ });+ if (error) {+ return {+ recipient,+ success: false,+ error:+ typeof error === "string" ? error : JSON.stringify(error),+ };+ }+ return { recipient, success: true };+ } catch (error) {+ return {+ recipient,+ success: false,+ error: error instanceof Error ? error.message : String(error),+ };+ }+ }),+ );++ const succeededIds = sendResults+ .filter(r => r.success)+ .map(r => r.recipient.id);+ const failures = sendResults.filter(r => !r.success);+ const allRecipientEmails = resolved.confirmedRecipients.map(r => r.email);++ if (succeededIds.length > 0) {+ await touchRecipientsNotified(succeededIds);+ }++ if (failures.length === allRecipientEmails.length) {+ const errorSummary = failures+ .map(f => `${f.recipient.email}: ${f.error}`)+ .join("; ");+ logger.warn("Monitor email summary failed for all recipients", {monitorId: params.monitor.id,checkId: params.check.id,- recipients,+ failures: errorSummary,});-- return { attempted: true, success: true, recipients };- } catch (error) {- logger.warn("Failed to send monitoring email summary", { error });return {attempted: true,success: false,- recipients,- error: error instanceof Error ? error.message : String(error),+ recipients: allRecipientEmails,+ pendingRecipients: resolved.pending,+ unsubscribedRecipients: resolved.unsubscribed,+ error: errorSummary,};}++ if (failures.length > 0) {+ logger.warn("Monitor email summary partially failed", {+ monitorId: params.monitor.id,+ checkId: params.check.id,+ delivered: succeededIds.length,+ failed: failures.length,+ });+ } else {+ logger.info("Monitor email summary sent", {+ monitorId: params.monitor.id,+ checkId: params.check.id,+ recipients: allRecipientEmails,+ });+ }++ return {+ attempted: true,+ success: true,+ recipients: allRecipientEmails,+ pendingRecipients: resolved.pending,+ unsubscribedRecipients: resolved.unsubscribed,+ };}diff --git a/apps/js-sdk/firecrawl/src/v2/types.ts b/apps/js-sdk/firecrawl/src/v2/types.tsindex 6709fd0e1..863c9b72e 100644--- a/apps/js-sdk/firecrawl/src/v2/types.ts+++ b/apps/js-sdk/firecrawl/src/v2/types.ts@@ -660,6 +660,25 @@ export interface MonitorEmailNotification {includeDiffs?: boolean;}+/**+ * Per-recipient opt-in state for monitor email notifications.+ *+ * External recipients (not members of the team that owns the monitor) must+ * confirm their subscription via a one-time email before they receive any+ * monitor notifications. Team members are auto-confirmed.+ *+ * - `pending` β confirmation email sent, no notifications yet+ * - `confirmed` β notifications enabled+ * - `unsubscribed` β recipient opted out and cannot be re-added without a new+ * confirmation flow+ */+export interface MonitorEmailRecipientSubscription {+ email: string;+ status: "pending" | "confirmed" | "unsubscribed";+ source: "team" | "opt_in" | "legacy";+ confirmationEmailSent?: boolean;+}+export interface MonitorNotification {email?: MonitorEmailNotification;}@@ -731,6 +750,13 @@ export interface Monitor {targets: MonitorTarget[];webhook?: MonitorWebhookConfig | null;notification?: MonitorNotification | null;+ /**+ * Present on create/update/get responses. Reflects the opt-in state of every+ * email recipient currently configured on the monitor. Absent when the API+ * has not reconciled recipients (e.g. team-default delivery with no+ * explicit recipients).+ */+ emailRecipientSubscriptions?: MonitorEmailRecipientSubscription[];retentionDays: number;estimatedCreditsPerMonth?: number | null;lastCheckSummary?: MonitorSummary | null;diff --git a/apps/python-sdk/firecrawl/v2/types.py b/apps/python-sdk/firecrawl/v2/types.pyindex 41965c01a..aef032208 100644--- a/apps/python-sdk/firecrawl/v2/types.py+++ b/apps/python-sdk/firecrawl/v2/types.py@@ -874,6 +874,30 @@ class MonitorNotification(BaseModel):email: Optional[MonitorEmailNotification] = None+class MonitorEmailRecipientSubscription(BaseModel):+ """Per-recipient opt-in state for monitor email notifications.++ External recipients (not members of the team that owns the monitor) must+ confirm their subscription via a one-time email before they receive any+ monitor notifications. Team members are auto-confirmed.++ Statuses:+ - ``pending`` - confirmation email sent, no notifications yet+ - ``confirmed`` - notifications enabled+ - ``unsubscribed`` - recipient opted out and cannot be re-added without+ a new confirmation flow+ """++ model_config = {"populate_by_name": True}++ email: str+ status: Literal["pending", "confirmed", "unsubscribed"]+ source: Literal["team", "opt_in", "legacy"]+ confirmation_email_sent: Optional[bool] = Field(+ default=None, alias="confirmationEmailSent"+ )++class MonitorTarget(BaseModel):"""A scrape or crawl target stored on a monitor."""@@ -938,6 +962,12 @@ class Monitor(BaseModel):targets: List[Dict[str, Any]]webhook: Optional[Dict[str, Any]] = Nonenotification: Optional[Dict[str, Any]] = None+ # Present on create/update/get when the API has reconciled email+ # recipients (i.e. notification.email.recipients is non-empty). Each+ # entry reports a recipient's opt-in status.+ email_recipient_subscriptions: Optional[List[MonitorEmailRecipientSubscription]] = (+ Field(default=None, alias="emailRecipientSubscriptions")+ )retention_days: int = Field(alias="retentionDays")estimated_credits_per_month: Optional[int] = Field(default=None, alias="estimatedCreditsPerMonth")last_check_summary: Optional[MonitorSummary] = Field(default=None, alias="lastCheckSummary")