Open source alternative to Semrush and Ahrefs
TypeScript backlink-analysisgoogle-search-console-mcpkeyword-researchmcpseoseo-agentseo-auditseo-automationseo-skillsseo-toolssite-audit
Send onboarding milestones and first audit results to Loops (#974)
Carter Smith2358bfcc18cd
diff --git a/src/server.ts b/src/server.tsindex b7cac9ed..0e1344bf 100644--- a/src/server.ts+++ b/src/server.ts@@ -9,6 +9,7 @@ import { SamSessionRepository } from "@/server/features/sam/SamSessionRepositoryimport { 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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/servimport { 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,