Open source alternative to Semrush and Ahrefs
TypeScript backlink-analysisgoogle-search-console-mcpkeyword-researchmcpseoseo-agentseo-auditseo-automationseo-skillsseo-toolssite-audit
import { createServerFn } from "@tanstack/react-start";
import { waitUntil } from "cloudflare:workers";
import { RankTrackingRepository } from "@/server/features/rank-tracking/repositories/RankTrackingRepository";
import { RankTrackingService } from "@/server/features/rank-tracking/services/RankTrackingService";
import { RankTrackingKeywordService } from "@/server/features/rank-tracking/services/RankTrackingKeywordService";
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,
createConfigSchema,
updateConfigSchema,
triggerCheckSchema,
getLatestResultsSchema,
getLatestRunSchema,
estimateCostSchema,
addKeywordsSchema,
removeKeywordsSchema,
setKeywordsPinnedSchema,
refreshMetricsSchema,
getKeywordHistorySchema,
getConfigTrendSchema,
getPositionMatrixSchema,
} from "@/types/schemas/rank-tracking";
export interface RankKeywordHistoryPoint {
device: "desktop" | "mobile";
checkedAt: string;
position: number | null;
}
interface RankConfigTrendPoint {
runId: string;
checkedAt: string;
top3: number;
top4to10: number;
top11to20: number;
notRanking: number;
notChecked: number;
}
export interface RankPositionMatrixCell {
runId: string;
checkedAt: string;
trackingKeywordId: string;
position: number | null;
}
async function requireConfig(configId: string, projectId: string) {
const config = await RankTrackingRepository.getConfigById({
configId,
projectId,
});
if (!config) {
throw new AppError("INTERNAL_ERROR", "Rank tracking config not found");
}
return config;
}
export const getRankTrackingConfigs = createServerFn({ method: "POST" })
.middleware(requireProjectContext)
.validator(getConfigsSchema)
.handler(async ({ context }) => {
return RankTrackingRepository.getConfigsForProject(context.projectId);
});
export const getRankTrackingConfigSummaries = createServerFn({ method: "POST" })
.middleware(requireProjectContext)
.validator(getConfigsSchema)
.handler(async ({ context }) => {
return RankTrackingRepository.getConfigSummaries(context.projectId);
});
export const createRankTrackingConfig = createServerFn({ method: "POST" })
.middleware(requireProjectContext)
.validator(createConfigSchema)
.handler(async ({ data, context }) => {
const result = await RankTrackingService.createConfig({
projectId: context.projectId,
projectMarket: context.project,
domain: data.domain,
locationCode: data.locationCode,
languageCode: data.languageCode,
locationName: data.locationName,
devices: data.devices,
serpDepth: data.serpDepth,
scheduleInterval: data.scheduleInterval,
scheduleTime: data.scheduleTime,
});
// Re-adding an archived domain keeps its keywords, and the keyword step
// then adds nothing new — so this is the only place its check can start.
await runAutoCheck({
configId: result.id,
projectId: context.projectId,
billingCustomer: context,
});
await markOnboardingMilestone(context, "rankTrackingSetUp");
waitUntil(
captureServerEvent({
distinctId: context.userId,
event: "rank_tracking:config_create",
organizationId: context.organizationId,
properties: {
project_id: context.projectId,
devices: data.devices ?? "both",
schedule: data.scheduleInterval ?? "weekly",
},
}),
);
return result;
});
export const updateRankTrackingConfig = createServerFn({ method: "POST" })
.middleware(requireProjectContext)
.validator(updateConfigSchema)
.handler(async ({ data, context }) => {
await RankTrackingService.updateConfig(data.configId, context.projectId, {
domain: data.domain,
locationCode: data.locationCode,
languageCode: data.languageCode,
locationName: data.locationName,
devices: data.devices,
serpDepth: data.serpDepth,
scheduleInterval: data.scheduleInterval,
scheduleTime: data.scheduleTime,
isActive: data.isActive,
});
return { success: true };
});
export const triggerRankCheck = createServerFn({ method: "POST" })
.middleware(requireProjectContext)
.validator(triggerCheckSchema)
.handler(async ({ data, context }) => {
const result = await RankTrackingService.triggerCheck({
configId: data.configId,
projectId: context.projectId,
billingCustomer: context,
keywordIds: data.keywordIds,
});
if (result.ok) {
waitUntil(
captureServerEvent({
distinctId: context.userId,
event: "rank_tracking:check_trigger",
organizationId: context.organizationId,
properties: {
project_id: context.projectId,
config_id: data.configId,
run_id: result.runId,
},
}),
);
}
return result;
});
export const getLatestRankResults = createServerFn({ method: "POST" })
.middleware(requireProjectContext)
.validator(getLatestResultsSchema)
.handler(async ({ data, context }) => {
return getLatestResults(
data.configId,
context.projectId,
data.comparePeriod,
);
});
export const getLatestRankRun = createServerFn({ method: "POST" })
.middleware(requireProjectContext)
.validator(getLatestRunSchema)
.handler(async ({ data, context }) => {
return RankTrackingService.getLatestRun(data.configId, context.projectId);
});
export const estimateRankCheckCost = createServerFn({ method: "POST" })
.middleware(requireProjectContext)
.validator(estimateCostSchema)
.handler(async ({ data, context }) => {
return RankTrackingService.estimateCost(data.configId, context.projectId);
});
function logAutoActionFailure(action: string, err: unknown) {
const appErr = asAppError(err);
if (appErr?.code === "PAYMENT_REQUIRED") {
console.info(`[rank-tracking] ${action} skipped: paid plan required`);
} else if (appErr?.code === "INSUFFICIENT_CREDITS") {
console.info(`[rank-tracking] ${action} skipped: insufficient credits`);
} else {
console.error(`[rank-tracking] ${action} failed:`, err);
}
}
async function runAutoCheck(
input: Parameters<typeof RankTrackingService.triggerAutoCheck>[0],
) {
try {
const result = await RankTrackingService.triggerAutoCheck(input);
if (!result.ok && result.reason !== "no_keywords") {
console.info("[rank-tracking] auto-check skipped: %s", result.reason);
}
return result;
} catch (err) {
logAutoActionFailure("auto-check", err);
return null;
}
}
export const addTrackingKeywords = createServerFn({ method: "POST" })
.middleware(requireProjectContext)
.validator(addKeywordsSchema)
.handler(async ({ data, context }) => {
const result = await RankTrackingService.addKeywords(
data.configId,
context.projectId,
data.keywords,
{ kind: "direct_user_action" },
data.matchCase,
);
const autoCheck =
result.addedIds.length > 0
? await runAutoCheck({
configId: data.configId,
projectId: context.projectId,
billingCustomer: context,
keywordIds: result.addedIds,
})
: null;
// Fetch keyword metrics (awaited so they're in the DB before client re-fetches)
if (result.added > 0) {
try {
await RankTrackingService.refreshKeywordMetrics(
data.configId,
context.projectId,
context,
);
} catch (err) {
logAutoActionFailure("auto-metrics-refresh", err);
}
}
return {
...result,
checkTriggered: autoCheck?.ok ?? false,
checkScheduledSoon:
autoCheck?.ok === false && autoCheck.reason === "scheduled_soon",
};
});
export const removeTrackingKeywords = createServerFn({ method: "POST" })
.middleware(requireProjectContext)
.validator(removeKeywordsSchema)
.handler(async ({ data, context }) => {
return RankTrackingService.removeKeywords(
data.configId,
context.projectId,
data.keywordIds,
);
});
export const setTrackingKeywordsPinned = createServerFn({ method: "POST" })
.middleware(requireProjectContext)
.validator(setKeywordsPinnedSchema)
.handler(async ({ data, context }) => {
return RankTrackingKeywordService.setKeywordsPinned(
data.configId,
context.projectId,
data.keywordIds,
data.pinned,
);
});
export const refreshTrackingKeywordMetrics = createServerFn({ method: "POST" })
.middleware(requireProjectContext)
.validator(refreshMetricsSchema)
.handler(async ({ data, context }) => {
const result = await RankTrackingService.refreshKeywordMetrics(
data.configId,
context.projectId,
context,
);
waitUntil(
captureServerEvent({
distinctId: context.userId,
event: "rank_tracking:metrics_refresh",
organizationId: context.organizationId,
properties: {
project_id: context.projectId,
config_id: data.configId,
updated: result.updated,
},
}),
);
return result;
});
export const getRankKeywordHistory = createServerFn({ method: "POST" })
.middleware(requireProjectContext)
.validator(getKeywordHistorySchema)
.handler(async ({ data, context }): Promise<RankKeywordHistoryPoint[]> => {
await requireConfig(data.configId, context.projectId);
return RankTrackingRepository.getKeywordHistory(
data.configId,
data.trackingKeywordId,
data.sinceDays,
);
});
export const getRankConfigTrend = createServerFn({ method: "POST" })
.middleware(requireProjectContext)
.validator(getConfigTrendSchema)
.handler(async ({ data, context }): Promise<RankConfigTrendPoint[]> => {
await requireConfig(data.configId, context.projectId);
const rows = await RankTrackingRepository.getConfigTrend(
data.configId,
data.device,
data.sinceDays,
);
// SQLite sum()/count() can return strings; coerce and derive "not ranking"
// (position > 20 or null) as the remainder of the checked keywords, and
// "not checked" (the check failed, so no row) as the remainder of the
// run's keywords, so the buckets cover every tracked keyword.
return rows.map((row) => {
const top3 = Number(row.top3) || 0;
const top4to10 = Number(row.top4to10) || 0;
const top11to20 = Number(row.top11to20) || 0;
const total = Number(row.total) || 0;
return {
runId: row.runId,
checkedAt: row.checkedAt,
top3,
top4to10,
top11to20,
notRanking: Math.max(0, total - top3 - top4to10 - top11to20),
notChecked: Math.max(0, row.keywordsTotal - total),
};
});
});
export const getRankPositionMatrix = createServerFn({ method: "POST" })
.middleware(requireProjectContext)
.validator(getPositionMatrixSchema)
.handler(async ({ data, context }): Promise<RankPositionMatrixCell[]> => {
await requireConfig(data.configId, context.projectId);
return RankTrackingRepository.getPositionMatrix(
data.configId,
data.device,
data.runLimit,
);
});