Skip to content

Open source alternative to Semrush and Ahrefs

11.2 KB
Raw Blame
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,
    );
  });