nolo-cli 0.1.26 → 0.1.29

package/auth/server/emailProvider.ts

@@ -0,0 +1,277 @@
+import {
+  sendBatchEmails as sendResendBatchEmails,
+  sendMarketingBroadcast as sendResendMarketingBroadcast,
+  sendEmail as sendResendEmail,
+  type ResendBatchEmailOptions,
+  type ResendEmailOptions,
+  type ResendMarketingBroadcastOptions,
+} from "../../integrations/resend";
+
+export type EmailProviderName = "resend" | "cloudflare";
+
+export type EmailSendOptions = ResendEmailOptions;
+export type EmailBatchSendOptions = ResendBatchEmailOptions;
+export type EmailMarketingBroadcastOptions = ResendMarketingBroadcastOptions;
+
+interface EmailProvider {
+  name: EmailProviderName;
+  sendEmail(options: EmailSendOptions): Promise<unknown>;
+  sendBatchEmails(options: EmailBatchSendOptions[]): Promise<unknown>;
+  sendMarketingBroadcast?(options: EmailMarketingBroadcastOptions): Promise<unknown>;
+}
+
+const CLOUDFLARE_EMAIL_API_BASE_URL = "https://api.cloudflare.com/client/v4";
+const DEFAULT_TIMEOUT_MS = 10_000;
+const DEFAULT_MAX_RETRY_ATTEMPTS = 3;
+const DEFAULT_RETRY_BASE_DELAY_MS = 500;
+const EMAIL_PATTERN = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+
+const parseNumber = (value: string | undefined, fallback: number, min = 1) => {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed)) return fallback;
+  return Math.max(min, Math.floor(parsed));
+};
+
+const sleep = (ms: number) =>
+  ms > 0 ? new Promise((resolve) => setTimeout(resolve, ms)) : Promise.resolve();
+
+const createTimeoutSignal = (timeoutMs: number) =>
+  typeof AbortSignal !== "undefined" &&
+  typeof (AbortSignal as any).timeout === "function"
+    ? (AbortSignal as any).timeout(timeoutMs)
+    : undefined;
+
+const parseResponsePayload = async (response: Response) => {
+  const payloadText = await response.text();
+  if (!payloadText) return {};
+  try {
+    return JSON.parse(payloadText);
+  } catch {
+    return { message: payloadText };
+  }
+};
+
+const normalizeRecipients = (to: string | string[]) => {
+  const recipients = (Array.isArray(to) ? to : [to]).map((item) =>
+    String(item || "").trim()
+  );
+  if (recipients.length === 0) {
+    throw new Error("At least one recipient email address is required");
+  }
+  for (const recipient of recipients) {
+    if (!EMAIL_PATTERN.test(recipient)) {
+      throw new Error("Invalid recipient email address");
+    }
+  }
+  return recipients;
+};
+
+const normalizeProviderName = (value: string | undefined): EmailProviderName => {
+  const normalized = String(value || "cloudflare").trim().toLowerCase();
+  if (normalized === "cloudflare" || normalized === "cf" || normalized === "cloudflare-email") {
+    return "cloudflare";
+  }
+  return "resend";
+};
+
+export const getEmailProviderName = () =>
+  normalizeProviderName(process.env.EMAIL_PROVIDER || process.env.EMAIL_DELIVERY_PROVIDER);
+
+const getCloudflareErrorMessage = (result: any) => {
+  const firstError = Array.isArray(result?.errors) ? result.errors[0] : null;
+  return firstError?.message || result?.message || "Unknown Cloudflare Email error";
+};
+
+const getCloudflareApiUrl = () => {
+  const accountId = String(
+    process.env.CLOUDFLARE_EMAIL_ACCOUNT_ID || process.env.CLOUDFLARE_ACCOUNT_ID || ""
+  ).trim();
+  if (!accountId) {
+    throw new Error("CLOUDFLARE_EMAIL_ACCOUNT_ID or CLOUDFLARE_ACCOUNT_ID is not defined");
+  }
+  const baseUrl = String(
+    process.env.CLOUDFLARE_EMAIL_API_BASE_URL || CLOUDFLARE_EMAIL_API_BASE_URL
+  ).replace(/\/+$/, "");
+  return `${baseUrl}/accounts/${encodeURIComponent(accountId)}/email/sending/send`;
+};
+
+const getCloudflareApiToken = () => {
+  const token = String(
+    process.env.CLOUDFLARE_EMAIL_API_TOKEN || process.env.CLOUDFLARE_API_TOKEN || ""
+  ).trim();
+  if (!token) {
+    throw new Error("CLOUDFLARE_EMAIL_API_TOKEN or CLOUDFLARE_API_TOKEN is not defined");
+  }
+  return token;
+};
+
+const getCloudflareSender = (from?: string) => {
+  const sender = String(
+    from ||
+      process.env.CLOUDFLARE_EMAIL_FROM ||
+      process.env.EMAIL_FROM ||
+      process.env.RESEND_FROM_EMAIL ||
+      ""
+  ).trim();
+  if (!sender) {
+    throw new Error("CLOUDFLARE_EMAIL_FROM, EMAIL_FROM, or RESEND_FROM_EMAIL is not defined");
+  }
+  return sender;
+};
+
+const isRetryableStatus = (status: number) => status === 429 || status >= 500;
+
+const getRetryAfterMs = (retryAfter: string | null) => {
+  if (!retryAfter) return null;
+  const seconds = Number(retryAfter);
+  if (Number.isFinite(seconds)) return Math.max(0, Math.floor(seconds * 1000));
+  const timestamp = Date.parse(retryAfter);
+  if (!Number.isNaN(timestamp)) return Math.max(0, timestamp - Date.now());
+  return null;
+};
+
+const requestCloudflareEmail = async (body: Record<string, unknown>) => {
+  const url = getCloudflareApiUrl();
+  const token = getCloudflareApiToken();
+  const timeoutMs = parseNumber(
+    process.env.CLOUDFLARE_EMAIL_TIMEOUT_MS,
+    DEFAULT_TIMEOUT_MS,
+    1_000
+  );
+  const maxRetryAttempts = parseNumber(
+    process.env.CLOUDFLARE_EMAIL_MAX_RETRY_ATTEMPTS,
+    DEFAULT_MAX_RETRY_ATTEMPTS,
+    1
+  );
+  const retryBaseDelayMs = parseNumber(
+    process.env.CLOUDFLARE_EMAIL_RETRY_BASE_DELAY_MS,
+    DEFAULT_RETRY_BASE_DELAY_MS,
+    100
+  );
+
+  let lastError: unknown = null;
+  for (let attempt = 1; attempt <= maxRetryAttempts; attempt += 1) {
+    try {
+      const response = await fetch(url, {
+        method: "POST",
+        signal: createTimeoutSignal(timeoutMs),
+        headers: {
+          Authorization: `Bearer ${token}`,
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify(body),
+      });
+      const result = await parseResponsePayload(response);
+      if (response.ok && (result as any)?.success !== false) {
+        return result;
+      }
+
+      const canRetry = isRetryableStatus(response.status) && attempt < maxRetryAttempts;
+      if (canRetry) {
+        const retryAfterMs = getRetryAfterMs(response.headers.get("retry-after"));
+        await sleep(retryAfterMs ?? retryBaseDelayMs * Math.pow(2, attempt - 1));
+        continue;
+      }
+
+      throw new Error(
+        `Cloudflare Email error (${response.status}): ${getCloudflareErrorMessage(result)}`
+      );
+    } catch (error: any) {
+      lastError = error;
+      const isTransientNetworkError =
+        error?.name === "AbortError" || error instanceof TypeError;
+      if (isTransientNetworkError && attempt < maxRetryAttempts) {
+        await sleep(retryBaseDelayMs * Math.pow(2, attempt - 1));
+        continue;
+      }
+      throw error;
+    }
+  }
+
+  if (lastError instanceof Error) throw lastError;
+  throw new Error("Cloudflare Email request failed after retries");
+};
+
+const assertCloudflareDeliveryAccepted = (result: any, recipients: string[]) => {
+  const permanentBounces = Array.isArray(result?.result?.permanent_bounces)
+    ? result.result.permanent_bounces.map((item: unknown) => String(item || "").trim())
+    : [];
+  const bouncedRecipients = permanentBounces.filter((email: string) =>
+    recipients.includes(email)
+  );
+  if (bouncedRecipients.length > 0) {
+    throw new Error(`Cloudflare Email permanent bounce: ${bouncedRecipients.join(", ")}`);
+  }
+};
+
+const cloudflareSendEmail = async ({
+  from,
+  to,
+  subject,
+  textBody,
+  htmlBody,
+  tag,
+}: EmailSendOptions) => {
+  if (!textBody && !htmlBody) {
+    throw new Error("Either textBody or htmlBody is required");
+  }
+  const recipients = normalizeRecipients(to);
+  const result = await requestCloudflareEmail({
+    from: getCloudflareSender(from),
+    to: Array.isArray(to) ? recipients : recipients[0],
+    subject,
+    text: textBody,
+    html: htmlBody,
+    headers: tag ? { "X-Campaign-ID": tag } : undefined,
+  });
+  assertCloudflareDeliveryAccepted(result, recipients);
+  return result;
+};
+
+const cloudflareProvider: EmailProvider = {
+  name: "cloudflare",
+  sendEmail: cloudflareSendEmail,
+  async sendBatchEmails(emails) {
+    if (!Array.isArray(emails) || emails.length === 0) {
+      throw new Error("Batch emails payload is empty");
+    }
+
+    const data: unknown[] = [];
+    const errors: Array<{ index: number; message: string }> = [];
+    for (let index = 0; index < emails.length; index += 1) {
+      try {
+        data[index] = await cloudflareSendEmail(emails[index]);
+      } catch (error: any) {
+        errors.push({ index, message: error?.message || String(error) });
+      }
+    }
+    return errors.length > 0 ? { data, errors } : { data };
+  },
+};
+
+const resendProvider: EmailProvider = {
+  name: "resend",
+  sendEmail: sendResendEmail,
+  sendBatchEmails: sendResendBatchEmails,
+  sendMarketingBroadcast: sendResendMarketingBroadcast,
+};
+
+export const getEmailProvider = (): EmailProvider =>
+  getEmailProviderName() === "cloudflare" ? cloudflareProvider : resendProvider;
+
+export const sendProviderEmail = (options: EmailSendOptions) =>
+  getEmailProvider().sendEmail(options);
+
+export const sendProviderBatchEmails = (options: EmailBatchSendOptions[]) =>
+  getEmailProvider().sendBatchEmails(options);
+
+export const sendProviderMarketingBroadcast = (options: EmailMarketingBroadcastOptions) => {
+  const provider = getEmailProvider();
+  if (!provider.sendMarketingBroadcast) {
+    throw new Error(`Email provider ${provider.name} does not support marketing broadcast`);
+  }
+  return provider.sendMarketingBroadcast(options);
+};
+
+export const emailProviderSupportsMarketingBroadcast = () =>
+  Boolean(getEmailProvider().sendMarketingBroadcast);

package/auth/server/emailReport.ts

@@ -0,0 +1,439 @@
+import { DB_PREFIX } from "../../database/keys";
+import serverDb from "../../database/server/db";
+import {
+  checkAdminPermission,
+  createErrorResponse,
+  createSuccessResponse,
+  handleOptionsRequest,
+  logger,
+} from "./shared";
+import {
+  getEmailDeliveryReport,
+  processEmailRetryQueue,
+  sendManagedEmailBatch,
+} from "./emailDelivery";
+import { balanceLockManager } from "./locks";
+import { canSendEmailToUser } from "./emailPolicy";
+import {
+  getReengagementConfig,
+  shouldUseReengagementMarketingDelivery,
+} from "./emailAutomationConfig";
+import {
+  buildFlowInterruptionEmail,
+  buildLowBalanceReminderEmail,
+  buildOnboardingEmail,
+  buildReengagementEmail,
+  buildWelcomeEmail,
+} from "./emailAutomationTemplates";
+import { UserEmailRecord } from "./emailAutomationTypes";
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+const parseSafeInt = (value: string | null, fallback: number, min: number, max: number) => {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed)) return fallback;
+  return Math.max(min, Math.min(max, Math.floor(parsed)));
+};
+
+const parseRecentLimit = (
+  value: string | null,
+  fallback: number,
+  min: number,
+  max: number
+) => {
+  const raw = String(value || "").trim().toLowerCase();
+  if (raw === "all") return 0;
+  return parseSafeInt(value, fallback, min, max);
+};
+
+const parseUserIdFilter = (value: unknown, max = 50_000): Set<string> | null => {
+  if (!Array.isArray(value)) return null;
+  const userIds = value
+    .map((item) => String(item || "").trim())
+    .filter(Boolean)
+    .slice(0, max);
+  return userIds.length > 0 ? new Set(userIds) : null;
+};
+
+const parseUserIdFilterFromQuery = (value: string | null, max = 50_000): Set<string> | null => {
+  const raw = String(value || "").trim();
+  if (!raw) return null;
+  const userIds = raw
+    .split(",")
+    .map((item) => item.trim())
+    .filter(Boolean)
+    .slice(0, max);
+  return userIds.length > 0 ? new Set(userIds) : null;
+};
+
+const sleep = (ms: number) =>
+  ms > 0 ? new Promise((resolve) => setTimeout(resolve, ms)) : Promise.resolve();
+
+const parseEnvNumber = (value: string | undefined, fallback: number, min = 1) => {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed)) return fallback;
+  return Math.max(min, Math.floor(parsed));
+};
+
+const supportedReplayTags = new Set([
+  "signup-welcome",
+  "onboarding-guide",
+  "reengagement",
+  "flow-interruption",
+  "low-balance-reminder",
+]);
+
+const isSupportedReplayTag = (tag: string): tag is
+  | "signup-welcome"
+  | "onboarding-guide"
+  | "reengagement"
+  | "flow-interruption"
+  | "low-balance-reminder" => supportedReplayTags.has(tag);
+
+const buildReplayEmailPayload = (
+  tag: string,
+  user: UserEmailRecord,
+  config: ReturnType<typeof getReengagementConfig>
+) => {
+  if (tag === "signup-welcome") {
+    return buildWelcomeEmail(user.username);
+  }
+  if (tag === "onboarding-guide") {
+    return buildOnboardingEmail(user.username);
+  }
+  if (tag === "reengagement") {
+    return buildReengagementEmail(
+      config.inactiveDays,
+      shouldUseReengagementMarketingDelivery() ? undefined : user.username
+    );
+  }
+  if (tag === "flow-interruption") {
+    return buildFlowInterruptionEmail(user.username);
+  }
+  if (tag === "low-balance-reminder") {
+    return buildLowBalanceReminderEmail(
+      Number(user.balance || 0),
+      config.lowBalanceThreshold,
+      user.username
+    );
+  }
+  return null;
+};
+
+const isWithinReplayCooldown = (
+  tag: string,
+  user: UserEmailRecord,
+  now: number,
+  config: ReturnType<typeof getReengagementConfig>
+) => {
+  if (tag !== "reengagement") return false;
+  const lastSentAt = Number(user.lastReengagementEmailAt || 0);
+  if (!Number.isFinite(lastSentAt) || lastSentAt <= 0) return false;
+  return now - lastSentAt < config.cooldownDays * DAY_MS;
+};
+
+const buildReplayUserPatch = (
+  tag: string,
+  user: UserEmailRecord,
+  deliveredAt: number
+): Record<string, any> | null => {
+  if (tag === "signup-welcome") {
+    return { welcomeEmailSentAt: deliveredAt };
+  }
+  if (tag === "onboarding-guide") {
+    return { onboardingGuideSentAt: deliveredAt };
+  }
+  if (tag === "reengagement") {
+    return {
+      lastReengagementEmailAt: deliveredAt,
+      reengagementEmailCount: Number(user.reengagementEmailCount || 0) + 1,
+    };
+  }
+  if (tag === "flow-interruption") {
+    return { flowInterruptionNudgeSentAt: deliveredAt };
+  }
+  if (tag === "low-balance-reminder") {
+    return { lastLowBalanceReminderAt: deliveredAt };
+  }
+  return null;
+};
+
+const markReplayDeliveryByTag = async (userId: string, tag: string, deliveredAt: number) => {
+  const key = `${DB_PREFIX.USER}${userId}`;
+  const lock = balanceLockManager.getLock(userId);
+  await lock.runExclusive(async () => {
+    const user = (await serverDb.get(key).catch(() => null)) as UserEmailRecord | null;
+    if (!user || typeof user !== "object") return;
+    const patch = buildReplayUserPatch(tag, user, deliveredAt);
+    if (!patch) return;
+    await serverDb.put(key, {
+      ...user,
+      ...patch,
+    });
+  });
+};
+
+export async function handleGetEmailReport(req: Request) {
+  if (req.method === "OPTIONS") {
+    return handleOptionsRequest();
+  }
+
+  const user = (req as any).user;
+  if (!user?.userId) {
+    return createErrorResponse("Unauthorized", 401);
+  }
+
+  const permissionError = checkAdminPermission(user.userId);
+  if (permissionError) return permissionError;
+
+  const url = new URL(req.url);
+  const days = parseSafeInt(url.searchParams.get("days"), 7, 1, 90);
+  const recentLimit = parseRecentLimit(url.searchParams.get("recent"), 20, 0, 2_000);
+
+  const report = await getEmailDeliveryReport(days, recentLimit);
+  return createSuccessResponse(report);
+}
+
+export async function handleRunEmailRetry(req: Request) {
+  if (req.method === "OPTIONS") {
+    return handleOptionsRequest();
+  }
+
+  const user = (req as any).user;
+  if (!user?.userId) {
+    return createErrorResponse("Unauthorized", 401);
+  }
+
+  const permissionError = checkAdminPermission(user.userId);
+  if (permissionError) return permissionError;
+
+  const result = await processEmailRetryQueue();
+  return createSuccessResponse({
+    message: "Email retry run completed",
+    ...result,
+  });
+}
+
+export async function handleReplayFailedAutomationEmails(req: Request) {
+  if (req.method === "OPTIONS") {
+    return handleOptionsRequest();
+  }
+
+  const user = (req as any).user;
+  if (!user?.userId) {
+    return createErrorResponse("Unauthorized", 401);
+  }
+
+  const permissionError = checkAdminPermission(user.userId);
+  if (permissionError) return permissionError;
+
+  const url = new URL(req.url);
+  const body = ((req as any).body || {}) as { userIds?: unknown };
+  const days = parseSafeInt(url.searchParams.get("days"), 30, 1, 90);
+  const recentLimit = parseRecentLimit(url.searchParams.get("recent"), 0, 0, 50_000);
+  const userIdFilter =
+    parseUserIdFilter(body.userIds) || parseUserIdFilterFromQuery(url.searchParams.get("userIds"));
+  const tagFilterRaw = String(url.searchParams.get("tags") || "").trim();
+  const selectedTags = tagFilterRaw
+    ? new Set(
+        tagFilterRaw
+          .split(",")
+          .map((item) => item.trim().toLowerCase())
+          .filter((item) => isSupportedReplayTag(item))
+      )
+    : null;
+  const report = await getEmailDeliveryReport(days, recentLimit);
+  const config = getReengagementConfig();
+  const broadcastBatchSize = Math.min(
+    100,
+    parseEnvNumber(process.env.EMAIL_BROADCAST_BATCH_SIZE, 20, 1)
+  );
+  const broadcastBatchDelayMs = parseEnvNumber(
+    process.env.EMAIL_BROADCAST_BATCH_DELAY_MS,
+    500,
+    0
+  );
+
+  const recent = Array.isArray((report as any)?.recent) ? ((report as any).recent as any[]) : [];
+  const latestByTagUser = new Map<string, any>();
+
+  for (const record of recent) {
+    const tag = String(record?.tag || "").trim().toLowerCase();
+    const userId = String(record?.userId || "").trim();
+    if (!tag || !userId) continue;
+    const key = `${tag}::${userId}`;
+    const existing = latestByTagUser.get(key);
+    const recordTime = Number(record?.timestamp || 0);
+    const existingTime = Number(existing?.timestamp || 0);
+    const recordStatus = String(record?.status || "");
+    const existingStatus = String(existing?.status || "");
+    if (
+      !existing ||
+      recordTime > existingTime ||
+      (recordTime === existingTime &&
+        recordStatus === "sent" &&
+        existingStatus !== "sent") ||
+      (recordTime === existingTime &&
+        recordStatus === existingStatus &&
+        String(record?.id || "") > String(existing?.id || ""))
+    ) {
+      latestByTagUser.set(key, record);
+    }
+  }
+
+  const failureCandidates = new Map(
+    Array.from(latestByTagUser.entries()).filter(
+      ([, record]) => String(record?.status || "") === "failed"
+    )
+  );
+
+  let skippedUnsupportedTag = 0;
+  let skippedByTagFilter = 0;
+  let skippedByUserFilter = 0;
+  let skippedMissingUser = 0;
+  let skippedByPolicy = 0;
+  let skippedByReplayCooldown = 0;
+  let skippedMissingEmail = 0;
+  const replayNow = Date.now();
+  const replayPayloads: Array<{
+    userId: string;
+    to: string;
+    subject: string;
+    textBody: string;
+    htmlBody: string;
+    tag: string;
+    metadata: Record<string, any>;
+  }> = [];
+
+  for (const item of failureCandidates.values()) {
+    const tag = String(item?.tag || "").trim();
+    if (!isSupportedReplayTag(tag)) {
+      skippedUnsupportedTag += 1;
+      continue;
+    }
+    if (selectedTags && !selectedTags.has(tag.toLowerCase())) {
+      skippedByTagFilter += 1;
+      continue;
+    }
+
+    const userId = String(item?.userId || "").trim();
+    if (!userId) {
+      skippedMissingUser += 1;
+      continue;
+    }
+    if (userIdFilter && !userIdFilter.has(userId)) {
+      skippedByUserFilter += 1;
+      continue;
+    }
+
+    const userRecord = (await serverDb.get(`${DB_PREFIX.USER}${userId}`).catch(() => null)) as
+      | UserEmailRecord
+      | null;
+    if (!userRecord || typeof userRecord !== "object") {
+      skippedMissingUser += 1;
+      continue;
+    }
+
+    const decision = canSendEmailToUser(userRecord, tag);
+    if (!decision.allowed) {
+      skippedByPolicy += 1;
+      continue;
+    }
+    if (isWithinReplayCooldown(tag, userRecord, replayNow, config)) {
+      skippedByReplayCooldown += 1;
+      continue;
+    }
+
+    const targetEmail = String(userRecord.email || "").trim();
+    if (!targetEmail) {
+      skippedMissingEmail += 1;
+      continue;
+    }
+
+    const replayEmail = buildReplayEmailPayload(tag, userRecord, config);
+    if (!replayEmail) {
+      skippedUnsupportedTag += 1;
+      continue;
+    }
+
+    replayPayloads.push({
+      userId,
+      to: targetEmail,
+      subject: replayEmail.subject,
+      textBody: replayEmail.textBody,
+      htmlBody: replayEmail.htmlBody,
+      tag,
+      metadata: {
+        replayFromFailureId: item?.id,
+        replayFromFailedSample: true,
+      },
+    });
+  }
+
+  let replayed = 0;
+  let queued = 0;
+  let failed = 0;
+  let suppressed = 0;
+
+  for (let start = 0; start < replayPayloads.length; start += broadcastBatchSize) {
+    const batch = replayPayloads.slice(start, start + broadcastBatchSize);
+    const batchResults = await sendManagedEmailBatch(batch, { enqueueOnFail: true });
+
+    for (let index = 0; index < batchResults.length; index += 1) {
+      const result = batchResults[index];
+      const payload = batch[index];
+      if (result.suppressed) {
+        suppressed += 1;
+        continue;
+      }
+      if (result.success) {
+        replayed += 1;
+        if (payload?.userId) {
+          await markReplayDeliveryByTag(payload.userId, payload.tag, Date.now()).catch((error) => {
+            logger.warn(
+              { userId: payload.userId, tag: payload.tag, error },
+              "Failed to mark replay delivery on user record"
+            );
+          });
+        }
+      } else if (result.queued) {
+        queued += 1;
+        if (payload?.userId) {
+          await markReplayDeliveryByTag(payload.userId, payload.tag, Date.now()).catch((error) => {
+            logger.warn(
+              { userId: payload.userId, tag: payload.tag, error },
+              "Failed to mark queued replay delivery on user record"
+            );
+          });
+        }
+      } else {
+        failed += 1;
+      }
+    }
+
+    if (start + broadcastBatchSize < replayPayloads.length) {
+      await sleep(broadcastBatchDelayMs);
+    }
+  }
+
+  return createSuccessResponse({
+    message: "Replay failed automation emails completed",
+    scannedRecent: recent.length,
+    replayCandidates: failureCandidates.size,
+    replayPrepared: replayPayloads.length,
+    replayed,
+    queued,
+    failed,
+    suppressed,
+    skippedUnsupportedTag,
+    skippedByTagFilter,
+    skippedByUserFilter,
+    skippedMissingUser,
+    skippedByPolicy,
+    skippedByReplayCooldown,
+    skippedMissingEmail,
+    selectedTags: selectedTags ? Array.from(selectedTags) : Array.from(supportedReplayTags),
+    batchSize: broadcastBatchSize,
+    batchDelayMs: broadcastBatchDelayMs,
+  });
+}