Skip to content

Open source alternative to Semrush and Ahrefs

Send onboarding milestones and first audit results to Loops (#974)

Carter Smith2358bfcc18cd
diff --git a/src/server.ts b/src/server.ts
index b7cac9ed..0e1344bf 100644
--- a/src/server.ts
+++ b/src/server.ts
@@ -9,6 +9,7 @@ import { SamSessionRepository } from "@/server/features/sam/SamSessionRepository
import { runScheduledRankChecks } from "@/server/features/rank-tracking/services/scheduledRankChecks";
import { SCHEDULED_RANK_CHECKS_PAUSED } from "@/shared/rank-tracking-pause";
import { reconcileStaleAudits } from "@/server/features/audit/services/auditReconciler";
+import { sendFirstAuditEmails } from "@/server/features/audit/services/firstAuditEmails";
import { getOrCreateOrganizationCustomer } from "@/server/billing/subscription";
import { isHostedServerAuthMode } from "@/server/lib/runtime-env";
import { getAuthMode, isHostedAuthMode } from "@/lib/auth-mode";
@@ -260,6 +261,7 @@ export default {
await import("@/server/features/ai-visibility/services/scheduledAiVisibility");
await runScheduledAiVisibility();
}),
+ withPgClient(() => sendFirstAuditEmails()),
]);
for (const result of checks)
if (result.status === "rejected") throw result.reason;
diff --git a/src/server/billing/subscription.ts b/src/server/billing/subscription.ts
index 43621f12..23a2fb4f 100644
--- a/src/server/billing/subscription.ts
+++ b/src/server/billing/subscription.ts
@@ -11,6 +11,7 @@ import {
import type { CreditFeature } from "@/shared/billing-credit-features";
import { autumn, AUTUMN_TRACK_RETRY_OPTIONS } from "@/server/billing/autumn";
import { captureServerEvent } from "@/server/lib/posthog";
+import { sendCreditsExhaustedEvent } from "@/server/email/onboarding-drip";
import { AppError } from "@/server/lib/errors";
export type BillingCustomerContext = Pick<
@@ -201,6 +202,7 @@ export async function checkUsageCreditsDepleted(
topup_remaining: confirmed.topupRemaining,
},
});
+ await sendCreditsExhaustedEvent(customer);
return { depleted: true, monthlyRemaining: check.monthlyRemaining };
}
diff --git a/src/server/email/onboarding-drip.ts b/src/server/email/onboarding-drip.ts
new file mode 100644
index 00000000..b619b5cc
--- /dev/null
+++ b/src/server/email/onboarding-drip.ts
@@ -0,0 +1,77 @@
+import { waitUntil } from "cloudflare:workers";
+import {
+ sendLoopsEvent,
+ updateLoopsContact,
+} from "@/server/email/loops-client";
+import { getOptionalEnvValue } from "@/server/lib/runtime-env";
+
+/**
+ * Server half of the onboarding email drip. Loops owns the timing, filters and
+ * copy; the server only reports what a user has done. Milestones land as
+ * contact properties the drip's emails filter on, and emails that react to
+ * something happening are sent as events (the first audit's results go from
+ * firstAuditEmails.ts). Every send is best-effort: a Loops outage must never
+ * fail the action that triggered it.
+ */
+
+type OnboardingRecipient = { userId: string; userEmail: string };
+
+type OnboardingMilestone =
+ | "auditStarted"
+ | "gscConnected"
+ | "rankTrackingSetUp"
+ | "mcpConnected";
+
+export async function markOnboardingMilestone(
+ recipient: OnboardingRecipient,
+ milestone: OnboardingMilestone,
+) {
+ await sendOnce(`${milestone}:${recipient.userId}`, (apiKey) =>
+ updateLoopsContact({
+ apiKey,
+ payload: {
+ email: recipient.userEmail,
+ userId: recipient.userId,
+ [milestone]: true,
+ },
+ logContext: { action: "onboarding-milestone", milestone },
+ }),
+ );
+}
+
+export async function sendCreditsExhaustedEvent(
+ recipient: OnboardingRecipient,
+) {
+ const key = `credits_exhausted:${recipient.userId}:${new Date().toISOString().slice(0, 10)}`;
+ await sendOnce(key, (apiKey) =>
+ sendLoopsEvent({
+ apiKey,
+ idempotencyKey: key,
+ payload: {
+ email: recipient.userEmail,
+ userId: recipient.userId,
+ eventName: "credits_exhausted",
+ },
+ }),
+ );
+}
+
+// Some callers are hot paths (every API-key MCP request, every request
+// refused for credits), and Loops rate-limits the whole team, transactional
+// emails included. So each isolate sends each update once.
+const sentKeys = new Set<string>();
+
+async function sendOnce(
+ key: string,
+ send: (apiKey: string) => Promise<unknown>,
+) {
+ if (sentKeys.has(key)) return;
+ const apiKey = await getOptionalEnvValue("LOOPS_API_KEY");
+ if (!apiKey) return;
+ sentKeys.add(key);
+ waitUntil(
+ send(apiKey).catch((error: unknown) => {
+ console.error(`onboarding drip: ${key} failed`, error);
+ }),
+ );
+}
diff --git a/src/server/features/audit/repositories/auditSummaryQueries.ts b/src/server/features/audit/repositories/auditSummaryQueries.ts
index 6ac6bb93..7d5d48ac 100644
--- a/src/server/features/audit/repositories/auditSummaryQueries.ts
+++ b/src/server/features/audit/repositories/auditSummaryQueries.ts
@@ -1,6 +1,6 @@
-import { countDistinct, eq } from "drizzle-orm";
+import { and, countDistinct, eq, gte, lt } from "drizzle-orm";
import { db } from "@/db";
-import { auditIssues } from "@/db/schema";
+import { auditIssues, audits, user } from "@/db/schema";
/**
* Distinct-page counts per issue type for one audit — link-level issues
@@ -19,3 +19,35 @@ export async function getIssueTypePageCountsForAudit(auditId: string) {
.where(eq(auditIssues.auditId, auditId))
.groupBy(auditIssues.issueType, auditIssues.severity);
}
+
+// completedAt is ISO text in both dialects, so string comparison orders it.
+export async function getAuditsCompletedSince(since: string) {
+ return db
+ .select({
+ id: audits.id,
+ projectId: audits.projectId,
+ startUrl: audits.startUrl,
+ pagesCrawled: audits.pagesCrawled,
+ completedAt: audits.completedAt,
+ userId: user.id,
+ email: user.email,
+ })
+ .from(audits)
+ .innerJoin(user, eq(user.id, audits.startedByUserId))
+ .where(and(eq(audits.status, "completed"), gte(audits.completedAt, since)));
+}
+
+export async function hasCompletedAuditBefore(userId: string, before: string) {
+ const rows = await db
+ .select({ id: audits.id })
+ .from(audits)
+ .where(
+ and(
+ eq(audits.startedByUserId, userId),
+ eq(audits.status, "completed"),
+ lt(audits.completedAt, before),
+ ),
+ )
+ .limit(1);
+ return rows.length > 0;
+}
diff --git a/src/server/features/audit/services/AuditService.crawlerAccess.test.ts b/src/server/features/audit/services/AuditService.crawlerAccess.test.ts
index ebe960a8..0e95bd9b 100644
--- a/src/server/features/audit/services/AuditService.crawlerAccess.test.ts
+++ b/src/server/features/audit/services/AuditService.crawlerAccess.test.ts
@@ -30,6 +30,9 @@ vi.mock("@/server/lib/runtime-env", () => ({
isHostedServerAuthMode: vi.fn().mockResolvedValue(false),
getOptionalEnvValue: vi.fn().mockResolvedValue(SECRET),
}));
+vi.mock("@/server/email/onboarding-drip", () => ({
+ markOnboardingMilestone: vi.fn(),
+}));
vi.mock("@/server/billing/subscription", () => ({
customerHasManagedAccess: vi.fn(),
customerHasPaidPlan: vi.fn(),
diff --git a/src/server/features/audit/services/AuditService.ts b/src/server/features/audit/services/AuditService.ts
index 05238edd..07fc69bc 100644
--- a/src/server/features/audit/services/AuditService.ts
+++ b/src/server/features/audit/services/AuditService.ts
@@ -1,3 +1,4 @@
+import { markOnboardingMilestone } from "@/server/email/onboarding-drip";
import { isAuditRenderingAllowed } from "@/server/lib/audit/rendering-policy";
import {
lockRenderingCredits,
@@ -191,6 +192,7 @@ async function startAudit(input: {
throw error;
}
+ await markOnboardingMilestone(input.billingCustomer, "auditStarted");
return { auditId };
}
diff --git a/src/server/features/audit/services/firstAuditEmails.test.ts b/src/server/features/audit/services/firstAuditEmails.test.ts
new file mode 100644
index 00000000..fa7ea646
--- /dev/null
+++ b/src/server/features/audit/services/firstAuditEmails.test.ts
@@ -0,0 +1,97 @@
+import { beforeEach, expect, it, vi } from "vitest";
+import type { sendLoopsEvent } from "@/server/email/loops-client";
+import { sendFirstAuditEmails } from "./firstAuditEmails";
+
+const mocks = vi.hoisted(() => ({
+ getAuditsCompletedSince: vi.fn(),
+ hasCompletedAuditBefore: vi.fn(),
+ getIssueTypePageCountsForAudit: vi.fn(),
+ countPagesByFetchClass: vi.fn(),
+ sendLoopsEvent: vi.fn<typeof sendLoopsEvent>(),
+}));
+
+vi.mock("cloudflare:workers", () => ({
+ env: {
+ LOOPS_API_KEY: "loops-key",
+ BETTER_AUTH_URL: "https://app.openseo.so",
+ },
+ waitUntil: vi.fn(),
+}));
+vi.mock("@/server/features/audit/repositories/auditSummaryQueries", () => ({
+ getAuditsCompletedSince: mocks.getAuditsCompletedSince,
+ hasCompletedAuditBefore: mocks.hasCompletedAuditBefore,
+ getIssueTypePageCountsForAudit: mocks.getIssueTypePageCountsForAudit,
+}));
+vi.mock("@/server/features/audit/repositories/AuditRepository", () => ({
+ AuditRepository: { countPagesByFetchClass: mocks.countPagesByFetchClass },
+}));
+vi.mock("@/server/email/loops-client", () => ({
+ sendLoopsEvent: mocks.sendLoopsEvent,
+}));
+
+beforeEach(() => {
+ mocks.getAuditsCompletedSince.mockResolvedValue([
+ {
+ id: "audit-1",
+ projectId: "project-1",
+ startUrl: "https://example.com",
+ pagesCrawled: 50,
+ completedAt: "2026-10-15T12:00:00.000Z",
+ userId: "user-1",
+ email: "[email protected]",
+ },
+ ]);
+ mocks.hasCompletedAuditBefore.mockResolvedValue(false);
+ mocks.countPagesByFetchClass.mockResolvedValue(0);
+ mocks.getIssueTypePageCountsForAudit.mockResolvedValue([
+ { issueType: "missing-meta-description", severity: "warning", pages: 9 },
+ { issueType: "broken-internal-link", severity: "critical", pages: 2 },
+ { issueType: "missing-title", severity: "critical", pages: 4 },
+ ]);
+ mocks.sendLoopsEvent.mockResolvedValue({ duplicate: false });
+});
+
+// The event name and properties are the contract with the Loops templates.
+it("emails a user the summary of their first completed audit", async () => {
+ await sendFirstAuditEmails();
+
+ expect(mocks.sendLoopsEvent).toHaveBeenCalledWith(
+ expect.objectContaining({
+ idempotencyKey: "first_audit:audit-1",
+ payload: {
+ email: "[email protected]",
+ userId: "user-1",
+ eventName: "first_audit_completed",
+ eventProperties: {
+ domain: "example.com",
+ pagesCrawled: 50,
+ criticalIssues: 6,
+ warningIssues: 9,
+ infoIssues: 0,
+ topIssue1: "Missing title tag",
+ topIssue2: "Broken internal link",
+ topIssue3: "Missing meta description",
+ auditUrl: "https://app.openseo.so/p/project-1/audit?auditId=audit-1",
+ },
+ },
+ }),
+ );
+});
+
+it("sends the blocked-crawler email when most pages were blocked", async () => {
+ mocks.countPagesByFetchClass.mockResolvedValue(30);
+
+ await sendFirstAuditEmails();
+
+ expect(mocks.sendLoopsEvent.mock.calls[0]?.[0].payload.eventName).toBe(
+ "first_audit_blocked",
+ );
+});
+
+it("does not email users who completed an audit before", async () => {
+ mocks.hasCompletedAuditBefore.mockResolvedValue(true);
+
+ await sendFirstAuditEmails();
+
+ expect(mocks.sendLoopsEvent).not.toHaveBeenCalled();
+});
diff --git a/src/server/features/audit/services/firstAuditEmails.ts b/src/server/features/audit/services/firstAuditEmails.ts
new file mode 100644
index 00000000..24ada26f
--- /dev/null
+++ b/src/server/features/audit/services/firstAuditEmails.ts
@@ -0,0 +1,92 @@
+import { sort } from "remeda";
+import { sendLoopsEvent } from "@/server/email/loops-client";
+import { AuditRepository } from "@/server/features/audit/repositories/AuditRepository";
+import {
+ getAuditsCompletedSince,
+ getIssueTypePageCountsForAudit,
+ hasCompletedAuditBefore,
+} from "@/server/features/audit/repositories/auditSummaryQueries";
+import { getOptionalEnvValue } from "@/server/lib/runtime-env";
+import {
+ getIssueDescriptor,
+ ISSUE_SEVERITY_ORDER,
+} from "@/shared/audit-issues";
+
+// Audits finish on the audit worker, which deliberately holds no Loops key,
+// so the app worker's 5-minute cron picks up newly finished audits instead.
+// The lookback spans several ticks so one failed tick loses no email; the
+// per-audit idempotency key (Loops dedupes for 24 hours) stops repeats.
+const FIRST_AUDIT_LOOKBACK_MS = 30 * 60_000;
+
+/** Emails each user the results of the first audit they complete. Most
+ * start it by adding their website during onboarding. When the crawler was
+ * blocked on most pages the email is a different one: how to let it in. */
+export async function sendFirstAuditEmails() {
+ const apiKey = await getOptionalEnvValue("LOOPS_API_KEY");
+ const baseUrl = await getOptionalEnvValue("BETTER_AUTH_URL");
+ if (!apiKey || !baseUrl) return;
+
+ const since = new Date(Date.now() - FIRST_AUDIT_LOOKBACK_MS).toISOString();
+ for (const audit of await getAuditsCompletedSince(since)) {
+ try {
+ if (
+ !audit.completedAt ||
+ (await hasCompletedAuditBefore(audit.userId, audit.completedAt))
+ ) {
+ continue;
+ }
+
+ const blockedPages = await AuditRepository.countPagesByFetchClass(
+ audit.id,
+ "blocked",
+ );
+ const issues = sort(
+ (await getIssueTypePageCountsForAudit(audit.id)).map((row) => ({
+ ...row,
+ title: getIssueDescriptor(row.issueType)?.title ?? row.issueType,
+ })),
+ (a, b) =>
+ ISSUE_SEVERITY_ORDER[a.severity] - ISSUE_SEVERITY_ORDER[b.severity] ||
+ b.pages - a.pages,
+ );
+ const countFor = (severity: string) =>
+ issues
+ .filter((issue) => issue.severity === severity)
+ .reduce((total, issue) => total + issue.pages, 0);
+
+ await sendLoopsEvent({
+ apiKey,
+ idempotencyKey: `first_audit:${audit.id}`,
+ payload: {
+ email: audit.email,
+ userId: audit.userId,
+ eventName:
+ blockedPages * 2 >= audit.pagesCrawled
+ ? "first_audit_blocked"
+ : "first_audit_completed",
+ eventProperties: {
+ domain: new URL(audit.startUrl).hostname,
+ pagesCrawled: audit.pagesCrawled,
+ criticalIssues: countFor("critical"),
+ warningIssues: countFor("warning"),
+ infoIssues: countFor("info"),
+ topIssue1: issues[0]?.title ?? "",
+ topIssue2: issues[1]?.title ?? "",
+ topIssue3: issues[2]?.title ?? "",
+ auditUrl: new URL(
+ `/p/${audit.projectId}/audit?auditId=${audit.id}`,
+ baseUrl,
+ ).href,
+ },
+ },
+ logContext: { action: "first-audit-email", auditId: audit.id },
+ });
+ } catch (error) {
+ // One bad audit must not stop the sweep.
+ console.error("onboarding drip: first audit email failed", {
+ auditId: audit.id,
+ error,
+ });
+ }
+ }
+}
diff --git a/src/server/mcp/api-key-auth.test.ts b/src/server/mcp/api-key-auth.test.ts
index beb8ba7f..df5244d1 100644
--- a/src/server/mcp/api-key-auth.test.ts
+++ b/src/server/mcp/api-key-auth.test.ts
@@ -37,6 +37,9 @@ vi.mock("@/server/features/activation/mcpActivation", () => ({
recordMcpAuthorized: mocks.recordMcpAuthorized,
}));
+vi.mock("@/server/email/onboarding-drip", () => ({
+ markOnboardingMilestone: vi.fn(),
+}));
vi.mock("@/server/mcp/transport", () => ({
handleAuthenticatedOpenSeoMcpRequest:
mocks.handleAuthenticatedOpenSeoMcpRequest,
diff --git a/src/server/mcp/api-key-auth.ts b/src/server/mcp/api-key-auth.ts
index 001b24a1..8772d9df 100644
--- a/src/server/mcp/api-key-auth.ts
+++ b/src/server/mcp/api-key-auth.ts
@@ -4,6 +4,7 @@ import { MCP_OAUTH_SCOPES } from "@/lib/oauth-resource";
import { resolveExistingActiveHostedOrganization } from "@/server/auth/default-hosted-organization";
import { AuthRepository } from "@/server/auth/repositories/AuthRepository";
import { recordMcpAuthorized } from "@/server/features/activation/mcpActivation";
+import { markOnboardingMilestone } from "@/server/email/onboarding-drip";
import { createWorkersOAuthMcpProps, MCP_ROUTE } from "@/server/mcp/context";
function getApiKey(request: Request) {
@@ -154,6 +155,10 @@ export async function handleMcpApiKeyRequest(
});
await recordMcpAuthorized(organizationId);
+ await markOnboardingMilestone(
+ { userId, userEmail: user.email },
+ "mcpConnected",
+ );
const { handleAuthenticatedOpenSeoMcpRequest } =
await import("@/server/mcp/transport");
diff --git a/src/server/mcp/oauth-provider.ts b/src/server/mcp/oauth-provider.ts
index 803fbd47..ed726796 100644
--- a/src/server/mcp/oauth-provider.ts
+++ b/src/server/mcp/oauth-provider.ts
@@ -16,6 +16,7 @@ import {
} from "@/lib/oauth-resource";
import { asAppError } from "@/server/lib/errors";
import { recordMcpAuthorized } from "@/server/features/activation/mcpActivation";
+import { markOnboardingMilestone } from "@/server/email/onboarding-drip";
import { captureServerEvent } from "@/server/lib/posthog";
import {
createWorkersOAuthMcpProps,
@@ -356,6 +357,7 @@ async function handleOAuthConsentResponse(
});
await recordMcpAuthorized(context.organizationId);
+ await markOnboardingMilestone(context, "mcpConnected");
waitUntil(
captureServerEvent({
diff --git a/src/server/mcp/tools/create-rank-tracker.ts b/src/server/mcp/tools/create-rank-tracker.ts
index e8a7f31c..9439411f 100644
--- a/src/server/mcp/tools/create-rank-tracker.ts
+++ b/src/server/mcp/tools/create-rank-tracker.ts
@@ -3,6 +3,7 @@ import { z } from "zod";
import { RankTrackingService } from "@/server/features/rank-tracking/services/RankTrackingService";
import { AppError } from "@/server/lib/errors";
import { captureServerEvent } from "@/server/lib/posthog";
+import { markOnboardingMilestone } from "@/server/email/onboarding-drip";
import { buildProjectMeta } from "@/server/mcp/context";
import { mcpResponse } from "@/server/mcp/formatters";
import {
@@ -104,6 +105,7 @@ export const createRankTrackerTool = {
scheduleInterval: args.scheduleInterval ?? "manual",
scheduleTime: args.scheduleTime,
});
+ await markOnboardingMilestone(context.auth, "rankTrackingSetUp");
waitUntil(
captureServerEvent({
distinctId: context.auth.userId,
diff --git a/src/serverFunctions/gsc.ts b/src/serverFunctions/gsc.ts
index 0d195e25..7b2a4b8a 100644
--- a/src/serverFunctions/gsc.ts
+++ b/src/serverFunctions/gsc.ts
@@ -11,6 +11,7 @@ import {
import { hasOrgPermission } from "@/lib/org-permissions";
import { requireOrgPermission } from "@/server/auth/org-gate";
import { captureServerEvent } from "@/server/lib/posthog";
+import { markOnboardingMilestone } from "@/server/email/onboarding-drip";
import { getPublicOrigin } from "@/server/mcp/public-origin";
import {
requireAuthenticatedContext,
@@ -107,6 +108,7 @@ export const setGscSite = createServerFn({ method: "POST" })
siteUrl: data.siteUrl,
userId: context.userId,
});
+ await markOnboardingMilestone(context, "gscConnected");
waitUntil(
captureServerEvent({
distinctId: context.userId,
diff --git a/src/serverFunctions/rank-tracking.ts b/src/serverFunctions/rank-tracking.ts
index 2cdb48fe..71ea878d 100644
--- a/src/serverFunctions/rank-tracking.ts
+++ b/src/serverFunctions/rank-tracking.ts
@@ -6,6 +6,7 @@ import { RankTrackingKeywordService } from "@/server/features/rank-tracking/serv
import { getLatestResults } from "@/server/features/rank-tracking/services/rankTrackingResults";
import { AppError, asAppError } from "@/server/lib/errors";
import { captureServerEvent } from "@/server/lib/posthog";
+import { markOnboardingMilestone } from "@/server/email/onboarding-drip";
import { requireProjectContext } from "@/serverFunctions/middleware";
import {
getConfigsSchema,
@@ -97,6 +98,7 @@ export const createRankTrackingConfig = createServerFn({ method: "POST" })
billingCustomer: context,
});
+ await markOnboardingMilestone(context, "rankTrackingSetUp");
waitUntil(
captureServerEvent({
distinctId: context.userId,