Open source alternative to Semrush and Ahrefs
TypeScript backlink-analysisgoogle-search-console-mcpkeyword-researchmcpseoseo-agentseo-auditseo-automationseo-skillsseo-toolssite-audit
import { RankTrackingRepository } from "@/server/features/rank-tracking/repositories/RankTrackingRepository";
import type { rankTrackingKeywords } from "@/db/schema";
import { AppError } from "@/server/lib/errors";
import {
devicesCount,
estimateRankCheckCredits,
estimateScheduledRankCheckCredits,
isScheduledRankTrackingInterval,
MAX_KEYWORDS_PER_CONFIG,
} from "@/shared/rank-tracking";
async function addKeywords(
configId: string,
projectId: string,
keywords: string[],
approval:
| { kind: "direct_user_action" }
| {
kind: "credit_ceiling";
maxEstimatedScheduledCheckCredits?: number;
},
// Keep the keyword exactly as typed instead of lowercasing it. "Nodex" and
// "nodex" are then two separately tracked (and separately billed) keywords.
matchCase = false,
) {
const config = await getValidatedConfig(configId, projectId);
const existing = await RankTrackingRepository.getKeywordsForConfig(configId);
if (existing.length >= MAX_KEYWORDS_PER_CONFIG) {
throw new AppError(
"INTERNAL_ERROR",
`Maximum ${MAX_KEYWORDS_PER_CONFIG} keywords per domain. Currently tracking ${existing.length}.`,
);
}
const existingKeywords = new Set(existing.map((kw) => kw.keyword));
const available = MAX_KEYWORDS_PER_CONFIG - existing.length;
const seen = new Set<string>();
const rows: (typeof rankTrackingKeywords.$inferInsert)[] = [];
for (const raw of keywords) {
if (rows.length >= available) break;
const trimmed = raw.trim();
const normalized = matchCase ? trimmed : trimmed.toLowerCase();
if (
normalized &&
!seen.has(normalized) &&
!existingKeywords.has(normalized)
) {
seen.add(normalized);
rows.push({
id: crypto.randomUUID(),
configId,
keyword: normalized,
matchCase,
});
}
}
const scheduleInterval = isScheduledRankTrackingInterval(
config.scheduleInterval,
)
? config.scheduleInterval
: null;
let scheduledEstimate:
| ReturnType<typeof estimateScheduledRankCheckCredits>
| undefined;
if (rows.length > 0 && scheduleInterval) {
scheduledEstimate = estimateScheduledRankCheckCredits(
[...existing, ...rows].map((kw) => kw.keyword),
config.devices,
config.serpDepth,
scheduleInterval,
);
if (
approval.kind === "credit_ceiling" &&
(approval.maxEstimatedScheduledCheckCredits == null ||
scheduledEstimate.costCredits >
approval.maxEstimatedScheduledCheckCredits)
) {
throw scheduledApprovalError(scheduleInterval, scheduledEstimate);
}
}
const addedIds =
rows.length > 0
? await RankTrackingRepository.addKeywordsToConfig(rows)
: [];
if (
scheduledEstimate &&
scheduleInterval &&
addedIds.length > 0 &&
approval.kind === "credit_ceiling"
) {
const persisted =
await RankTrackingRepository.getKeywordsForConfig(configId);
scheduledEstimate = estimateScheduledRankCheckCredits(
persisted.map((kw) => kw.keyword),
config.devices,
config.serpDepth,
scheduleInterval,
);
if (
approval.maxEstimatedScheduledCheckCredits == null ||
scheduledEstimate.costCredits > approval.maxEstimatedScheduledCheckCredits
) {
await RankTrackingRepository.removeKeywordsFromConfig(addedIds, configId);
throw scheduledApprovalError(scheduleInterval, scheduledEstimate);
}
}
return { added: addedIds.length, addedIds, scheduledEstimate };
}
async function removeKeywords(
configId: string,
projectId: string,
keywordIds: string[],
) {
await getValidatedConfig(configId, projectId);
const uniqueIds = [...new Set(keywordIds)];
const removedIds = await RankTrackingRepository.removeKeywordsFromConfig(
uniqueIds,
configId,
);
return { removed: removedIds.length, removedIds };
}
async function setKeywordsPinned(
configId: string,
projectId: string,
keywordIds: string[],
pinned: boolean,
) {
await getValidatedConfig(configId, projectId);
const updatedIds = await RankTrackingRepository.setKeywordsPinned(
[...new Set(keywordIds)],
configId,
pinned,
);
return { updated: updatedIds.length, updatedIds };
}
async function estimateCost(
configId: string,
projectId: string,
additionalKeywords: readonly string[] = [],
) {
const config = await getValidatedConfig(configId, projectId);
const existing = await RankTrackingRepository.getKeywordsForConfig(configId);
const existingKeywordCount = existing.length;
const keywords = [
...existing.map((kw) => kw.keyword),
...additionalKeywords,
].slice(0, Math.max(existingKeywordCount, MAX_KEYWORDS_PER_CONFIG));
const keywordCount = keywords.length;
const { costUsd, costCredits } = estimateRankCheckCredits(
keywords,
config.devices,
config.serpDepth,
"live",
);
const scheduleInterval = isScheduledRankTrackingInterval(
config.scheduleInterval,
)
? config.scheduleInterval
: null;
return {
costUsd,
costCredits,
keywordCount,
devicesCount: devicesCount(config.devices),
totalChecks: keywordCount * devicesCount(config.devices),
method: "live" as const,
existingKeywordCount,
additionalKeywordCount: keywordCount - existingKeywordCount,
scheduledEstimate: scheduleInterval
? estimateScheduledRankCheckCredits(
keywords,
config.devices,
config.serpDepth,
scheduleInterval,
)
: undefined,
};
}
async function getValidatedConfig(configId: string, projectId: string) {
const config = await RankTrackingRepository.getConfigById({
configId,
projectId,
});
if (!config) {
throw new AppError("NOT_FOUND", "Rank tracking config not found");
}
return config;
}
function scheduledApprovalError(
scheduleInterval: "daily" | "weekly" | "monthly",
estimate: ReturnType<typeof estimateScheduledRankCheckCredits>,
) {
return new AppError(
"VALIDATION_ERROR",
`Adding these keywords would make each ${scheduleInterval} scheduled check cost up to ${estimate.costCredits} credits including retries (~$${estimate.costUsd.toFixed(4)} per check; up to ~${estimate.monthlyCostCredits} credits/month). Call estimate_rank_tracker_cost with additionalKeywords, show the recurring estimate to the user, then retry with maxEstimatedScheduledCheckCredits set to the approved per-check estimate.`,
);
}
export const RankTrackingKeywordService = {
addKeywords,
removeKeywords,
setKeywordsPinned,
estimateCost,
};