Open source alternative to Semrush and Ahrefs
TypeScript backlink-analysisgoogle-search-console-mcpkeyword-researchmcpseoseo-agentseo-auditseo-automationseo-skillsseo-toolssite-audit
Add per-feature usage breakdown to billing page (#232)
Ben Senescu06e15dc70f18
diff --git a/src/client/features/billing/BillingFeatureBreakdown.test.ts b/src/client/features/billing/BillingFeatureBreakdown.test.tsnew file mode 100644index 00000000..297d55fe--- /dev/null+++ b/src/client/features/billing/BillingFeatureBreakdown.test.ts@@ -0,0 +1,98 @@+import { describe, expect, it, vi } from "vitest";++vi.mock("@/serverFunctions/billing", () => ({+ getBillingUsageEvents: vi.fn(),+}));++import { getBillingFeatureBreakdownRows } from "./BillingFeatureBreakdown";++describe("getBillingFeatureBreakdownRows", () => {+ it("uses explicit creditFeature when present", () => {+ const rows = getBillingFeatureBreakdownRows([+ {+ value: 250,+ properties: {+ creditFeature: "rank_tracking",+ paths: ["v3/serp/google/organic/live/regular"],+ },+ },+ ]);++ expect(rows).toEqual([{ label: "Rank Tracking", usd: 0.25 }]);+ });++ it("supports raw Autumn property aliases", () => {+ const rows = getBillingFeatureBreakdownRows([+ {+ value: 200,+ properties: {+ credit_feature: "local_seo",+ path: "v3/backlinks/summary/live",+ },+ },+ ]);++ expect(rows).toEqual([{ label: "Local SEO", usd: 0.2 }]);+ });++ it("infers legacy events from DataForSEO paths", () => {+ const rows = getBillingFeatureBreakdownRows([+ {+ value: 500,+ properties: { paths: ["v3/backlinks/summary/live"] },+ },+ {+ value: 250,+ properties: {+ paths: ["v3/dataforseo_labs/google/domain_rank_overview/live"],+ },+ },+ {+ value: 125,+ properties: {+ paths: ["v3/ai_optimization/llm_mentions/search/live"],+ },+ },+ {+ value: 100,+ properties: { paths: ["backlinks/summary"] },+ },+ ]);++ expect(rows).toEqual([+ { label: "Backlinks", usd: 0.6 },+ { label: "Domain Overview", usd: 0.25 },+ { label: "AI Citations", usd: 0.125 },+ ]);+ });++ it("supports legacy JSON-encoded path groups", () => {+ const rows = getBillingFeatureBreakdownRows([+ {+ value: 300,+ properties: {+ paths: '["v3/ai_optimization/chat_gpt/llm_responses/live"]',+ },+ },+ {+ value: 200,+ properties: {+ paths: '["v3","ai_optimization","perplexity","llm_responses","live"]',+ },+ },+ ]);++ expect(rows).toEqual([{ label: "AI Prompt Responses", usd: 0.5 }]);+ });++ it("falls back to Other when neither feature nor path is available", () => {+ const rows = getBillingFeatureBreakdownRows([+ {+ value: 100,+ properties: {},+ },+ ]);++ expect(rows).toEqual([{ label: "Other", usd: 0.1 }]);+ });+});diff --git a/src/client/features/billing/BillingFeatureBreakdown.tsx b/src/client/features/billing/BillingFeatureBreakdown.tsxnew file mode 100644index 00000000..5f7cdfcc--- /dev/null+++ b/src/client/features/billing/BillingFeatureBreakdown.tsx@@ -0,0 +1,185 @@+import { useQuery } from "@tanstack/react-query";+import {+ AUTUMN_SEO_DATA_BALANCE_FEATURE_ID,+ AUTUMN_SEO_DATA_TOPUP_BALANCE_FEATURE_ID,+ autumnSeoDataCreditsToUsd,+} from "@/shared/billing";+import {+ creditFeatureLabel,+ mapDataforseoPathToCreditFeature,+} from "@/shared/billing-credit-features";+import {+ getBillingUsageEvents,+ type BillingUsageEvent,+} from "@/serverFunctions/billing";++const BILLING_USAGE_FEATURE_IDS: string[] = [+ AUTUMN_SEO_DATA_BALANCE_FEATURE_ID,+ AUTUMN_SEO_DATA_TOPUP_BALANCE_FEATURE_ID,+];++const THIRTY_DAYS_MS = 30 * 24 * 60 * 60 * 1000;++type BillingUsageEventProperties = {+ creditFeature?: unknown;+ credit_feature?: unknown;+ path?: unknown;+ paths?: unknown;+};++type BillingFeatureBreakdownRow = {+ label: string;+ usd: number;+};++type BillingUsageRange = {+ start: number;+ end: number;+};++function getLast30DayUsageRange(): BillingUsageRange {+ const end = Date.now();+ return {+ start: end - THIRTY_DAYS_MS,+ end,+ };+}++function isRecord(value: unknown): value is Record<string, unknown> {+ return typeof value === "object" && value !== null;+}++function getPathSegmentsFromProperties(+ properties: BillingUsageEventProperties,+): string[] | null {+ const paths = properties.paths ?? properties.path;+ if (Array.isArray(paths)) {+ const stringPaths = paths.filter(+ (value): value is string => typeof value === "string",+ );+ if (+ stringPaths.length > 1 &&+ stringPaths.every((segment) => !segment.includes("/"))+ ) {+ return stringPaths;+ }++ const path = stringPaths[0];+ if (!path) return null;++ const parsedPath = parseJsonEncodedPath(path);+ return parsedPath ?? path.split("/").filter(Boolean);+ }++ if (typeof paths !== "string") return null;++ const parsedPath = parseJsonEncodedPath(paths);+ return parsedPath ?? paths.split("/").filter(Boolean);+}++function parseJsonEncodedPath(path: string): string[] | null {+ if (!path.startsWith("[")) return null;++ try {+ const parsed: unknown = JSON.parse(path);+ if (!Array.isArray(parsed)) return null;+ const stringPaths = parsed.filter(+ (value): value is string => typeof value === "string",+ );+ if (+ stringPaths.length > 1 &&+ stringPaths.every((segment) => !segment.includes("/"))+ ) {+ return stringPaths;+ }++ const firstPath = stringPaths[0];+ return firstPath ? firstPath.split("/").filter(Boolean) : null;+ } catch {+ return null;+ }+}++function getCreditFeatureFromUsageEvent(+ event: BillingUsageEvent,+): string | null {+ const properties = isRecord(event.properties) ? event.properties : {};+ const explicitFeature = properties.creditFeature ?? properties.credit_feature;+ if (typeof explicitFeature === "string" && explicitFeature.length > 0) {+ return explicitFeature;+ }++ const path = getPathSegmentsFromProperties(properties);+ return path ? mapDataforseoPathToCreditFeature(path) : null;+}++export function getBillingFeatureBreakdownRows(+ events: BillingUsageEvent[],+): BillingFeatureBreakdownRow[] {+ const creditsByLabel = new Map<string, number>();++ for (const event of events) {+ const feature = getCreditFeatureFromUsageEvent(event);+ const label = feature ? creditFeatureLabel(feature) : "Other";+ creditsByLabel.set(label, (creditsByLabel.get(label) ?? 0) + event.value);+ }++ return [...creditsByLabel.entries()]+ .map(([label, credits]) => ({+ label,+ usd: autumnSeoDataCreditsToUsd(credits),+ }))+ .filter((row) => row.usd > 0)+ .toSorted((a, b) => b.usd - a.usd);+}++export function BillingFeatureBreakdown() {+ const eventsQuery = useQuery({+ queryKey: ["billing", "usage-events", BILLING_USAGE_FEATURE_IDS, "30d"],+ queryFn: () => getBillingUsageEvents({ data: getLast30DayUsageRange() }),+ staleTime: 60_000,+ });++ const rows = getBillingFeatureBreakdownRows(eventsQuery.data ?? []);+ const total = rows.reduce((sum, row) => sum + row.usd, 0);++ return (+ <div className="rounded-lg border border-base-300 bg-base-100 p-4 space-y-3">+ <div className="flex items-baseline justify-between gap-4">+ <span className="font-semibold">Usage by feature</span>+ <span className="text-xs text-base-content/50">Last 30 days</span>+ </div>++ {eventsQuery.isLoading ? (+ <div className="space-y-3">+ {[0, 1, 2, 3].map((i) => (+ <div key={i} className="skeleton h-4 w-full" />+ ))}+ </div>+ ) : rows.length === 0 ? (+ <div className="text-sm text-base-content/40">+ No usage recorded yet+ </div>+ ) : (+ <ul className="space-y-2.5">+ {rows.map((row) => (+ <li key={row.label} className="space-y-1">+ <div className="flex items-baseline justify-between gap-4 text-sm">+ <span>{row.label}</span>+ <span className="tabular-nums text-base-content/70">+ ${row.usd.toFixed(2)}+ </span>+ </div>+ <div className="h-1.5 w-full overflow-hidden rounded-full bg-base-200">+ <div+ className="h-full rounded-full bg-[#7c3aed]"+ style={{ width: `${(row.usd / total) * 100}%` }}+ />+ </div>+ </li>+ ))}+ </ul>+ )}+ </div>+ );+}diff --git a/src/routes/_app/billing.tsx b/src/routes/_app/billing.tsxindex dfb87c2d..704e4aaa 100644--- a/src/routes/_app/billing.tsx+++ b/src/routes/_app/billing.tsx@@ -6,6 +6,7 @@ import { isHostedClientAuthMode } from "@/lib/auth-mode";import { getStandardErrorMessage } from "@/client/lib/error-messages";import { getStoredRedditAttribution } from "@/client/lib/reddit-attribution";import { BillingUsageChart } from "@/client/features/billing/BillingUsageChart";+import { BillingFeatureBreakdown } from "@/client/features/billing/BillingFeatureBreakdown";import { parseTopUpAmount } from "@/client/features/billing/HostedBillingContentUtils";import { getBillingRouteState } from "@/client/features/billing/route-state";import { getCustomerPlanStatus } from "@/client/features/billing/plan-detection";@@ -310,6 +311,9 @@ function BillingPageContent() {{/* Usage chart */}<BillingUsageChart />+ {/* Per-feature usage breakdown */}+ <BillingFeatureBreakdown />+{error ? <p className="text-sm text-error">{error}</p> : null}<p className="text-xs text-base-content/40">diff --git a/src/server/lib/dataforseoClient.test.ts b/src/server/lib/dataforseoClient.test.tsindex 11e9d312..5062168e 100644--- a/src/server/lib/dataforseoClient.test.ts+++ b/src/server/lib/dataforseoClient.test.ts@@ -354,6 +354,9 @@ describe("mapDataforseoPathToCreditFeature", () => {expect(mapDataforseoPathToCreditFeature(["v3", "backlinks", "summary", "live"]),).toBe("backlinks");+ expect(mapDataforseoPathToCreditFeature(["backlinks", "summary"])).toBe(+ "backlinks",+ );expect(mapDataforseoPathToCreditFeature(["v3",@@ -376,7 +379,7 @@ describe("mapDataforseoPathToCreditFeature", () => {).toBe("site_audit");});- it("maps real ai_optimization paths to ai_search", () => {+ it("maps ai_optimization llm_mentions paths to ai_citations", () => {expect(mapDataforseoPathToCreditFeature(["v3",@@ -385,7 +388,7 @@ describe("mapDataforseoPathToCreditFeature", () => {"search","live",]),- ).toBe("ai_search");+ ).toBe("ai_citations");expect(mapDataforseoPathToCreditFeature(["v3",@@ -394,16 +397,30 @@ describe("mapDataforseoPathToCreditFeature", () => {"aggregated_metrics","live",]),- ).toBe("ai_search");+ ).toBe("ai_citations");expect(mapDataforseoPathToCreditFeature(["v3","ai_optimization",- "claude",- "llm_responses",+ "llm_mentions",+ "top_pages","live",]),- ).toBe("ai_search");+ ).toBe("ai_citations");+ });++ it("maps ai_optimization provider llm_responses paths to ai_prompt_responses", () => {+ for (const provider of ["chat_gpt", "claude", "gemini", "perplexity"]) {+ expect(+ mapDataforseoPathToCreditFeature([+ "v3",+ "ai_optimization",+ provider,+ "llm_responses",+ "live",+ ]),+ ).toBe("ai_prompt_responses");+ }});it("maps local and supporting paths to the intended credit features", () => {diff --git a/src/server/lib/dataforseoClient.ts b/src/server/lib/dataforseoClient.tsindex 1d1c522e..a1ac929d 100644--- a/src/server/lib/dataforseoClient.ts+++ b/src/server/lib/dataforseoClient.ts@@ -6,6 +6,10 @@ import {SEO_DATA_COST_MARKUP,roundUsdForBilling,} from "@/shared/billing";+import {+ type CreditFeature,+ mapDataforseoPathToCreditFeature,+} from "@/shared/billing-credit-features";import { autumn } from "@/server/billing/autumn";import { getOrCreateOrganizationCustomer } from "@/server/billing/subscription";import type { BillingCustomerContext } from "@/server/billing/subscription";@@ -60,55 +64,7 @@ import { AppError } from "@/server/lib/errors";import { captureServerEvent } from "@/server/lib/posthog";import { isHostedServerAuthMode } from "@/server/lib/runtime-env";-type CreditFeature =- | "keyword_research"- | "domain_overview"- | "backlinks"- | "site_audit"- | "rank_tracking"- | "ai_search"- | "local_seo";--/**- * Maps a DataForSEO API response path (e.g. ["v3", "dataforseo_labs", "google", "related_keywords", "live"])- * to a product feature for analytics. path[1] is the API module; for dataforseo_labs,- * path[3] distinguishes keyword vs domain endpoints.- */-export function mapDataforseoPathToCreditFeature(- path: string[],-): CreditFeature {- const module = path[1];-- switch (module) {- case "on_page":- return "site_audit";- case "backlinks":- return "backlinks";- case "serp":- return path[2] === "google" && ["maps", "local_finder"].includes(path[3])- ? "local_seo"- : "keyword_research";- case "ai_optimization":- return "ai_search";- case "business_data":- return "local_seo";- case "keywords_data":- return "keyword_research";- case "dataforseo_labs": {- const endpoint = path[3] ?? "";- if (- endpoint.startsWith("domain_") ||- endpoint === "ranked_keywords" ||- endpoint === "relevant_pages"- ) {- return "domain_overview";- }- return "keyword_research";- }- default:- return "site_audit";- }-}+export { mapDataforseoPathToCreditFeature };export function createDataforseoClient(customer: BillingCustomerContext) {return {@@ -457,10 +413,14 @@ async function trackDataforseoCost(args: {const monthlyDeduct = Math.min(args.monthlyRemaining, totalCostCredits);const topupDeduct = totalCostCredits - monthlyDeduct;+ const creditFeature =+ args.creditFeature ?? mapDataforseoPathToCreditFeature(args.billing.path);+const properties = {provider: "dataforseo",currency: "USD",paths: [args.billing.path.join("/")],+ creditFeature,totalCostUsd,totalCostCredits,fromCache: false,@@ -497,9 +457,7 @@ async function trackDataforseoCost(args: {organizationId: args.customer.organizationId,properties: {project_id: args.customer.projectId,- credit_feature:- args.creditFeature ??- mapDataforseoPathToCreditFeature(args.billing.path),+ credit_feature: creditFeature,monthly_credits: monthlyDeduct,topup_credits: topupDeduct,total_credits: totalCostCredits,diff --git a/src/serverFunctions/billing.ts b/src/serverFunctions/billing.tsnew file mode 100644index 00000000..329dc229--- /dev/null+++ b/src/serverFunctions/billing.ts@@ -0,0 +1,122 @@+import { createServerFn } from "@tanstack/react-start";+import { z } from "zod";+import {+ AUTUMN_SEO_DATA_BALANCE_FEATURE_ID,+ AUTUMN_SEO_DATA_TOPUP_BALANCE_FEATURE_ID,+} from "@/shared/billing";+import { AppError } from "@/server/lib/errors";+import {+ getRequiredEnvValue,+ isHostedServerAuthMode,+} from "@/server/lib/runtime-env";+import { requireAuthenticatedContext } from "@/serverFunctions/middleware";++const AUTUMN_EVENTS_LIST_URL = "https://api.useautumn.com/v1/events.list";+const EVENT_PAGE_LIMIT = 1000;+const BILLING_USAGE_FEATURE_IDS = [+ AUTUMN_SEO_DATA_BALANCE_FEATURE_ID,+ AUTUMN_SEO_DATA_TOPUP_BALANCE_FEATURE_ID,+] as const;++const billingUsageRangeSchema = z.object({+ start: z.number(),+ end: z.number(),+});++const billingUsagePropertySchema = z.json();++const autumnEventSchema = z+ .object({+ value: z.number(),+ properties: z+ .record(z.string(), billingUsagePropertySchema)+ .optional()+ .default({}),+ })+ .passthrough();++const autumnEventsListResponseSchema = z+ .object({+ list: z.array(autumnEventSchema),+ has_more: z.boolean().optional(),+ hasMore: z.boolean().optional(),+ })+ .passthrough();++export type BillingUsageEvent = {+ value: number;+ properties: Record<string, z.infer<typeof billingUsagePropertySchema>>;+};++export const getBillingUsageEvents = createServerFn({ method: "POST" })+ .middleware(requireAuthenticatedContext)+ .inputValidator((data: unknown) => billingUsageRangeSchema.parse(data))+ .handler(async ({ data, context }) => {+ if (!(await isHostedServerAuthMode())) {+ return [];+ }++ const events: BillingUsageEvent[] = [];+ let offset = 0;++ for (;;) {+ const page = await fetchAutumnEventsPage({+ customerId: context.organizationId,+ end: data.end,+ offset,+ start: data.start,+ });++ events.push(...page.list);++ if (!page.hasMore || page.list.length === 0) {+ return events;+ }++ offset += page.list.length;+ }+ });++async function fetchAutumnEventsPage(args: {+ customerId: string;+ end: number;+ offset: number;+ start: number;+}): Promise<{ list: BillingUsageEvent[]; hasMore: boolean }> {+ const secretKey = await getRequiredEnvValue("AUTUMN_SECRET_KEY");+ const response = await fetch(AUTUMN_EVENTS_LIST_URL, {+ method: "POST",+ headers: {+ Accept: "application/json",+ Authorization: `Bearer ${secretKey}`,+ "Content-Type": "application/json",+ },+ body: JSON.stringify({+ customer_id: args.customerId,+ custom_range: {+ end: args.end,+ start: args.start,+ },+ feature_id: BILLING_USAGE_FEATURE_IDS,+ limit: EVENT_PAGE_LIMIT,+ offset: args.offset,+ }),+ });++ if (!response.ok) {+ throw new AppError(+ "INTERNAL_ERROR",+ `Autumn events.list failed with status ${response.status}`,+ );+ }++ const parsed = autumnEventsListResponseSchema.parse(await response.json());++ return {+ hasMore: parsed.has_more ?? parsed.hasMore ?? false,+ list: parsed.list.map((event) => ({+ value: event.value,+ properties: event.properties,+ })),+ };+}diff --git a/src/shared/billing-credit-features.ts b/src/shared/billing-credit-features.tsnew file mode 100644index 00000000..e4bf93cd--- /dev/null+++ b/src/shared/billing-credit-features.ts@@ -0,0 +1,73 @@+export type CreditFeature =+ | "keyword_research"+ | "domain_overview"+ | "backlinks"+ | "site_audit"+ | "rank_tracking"+ | "ai_citations"+ | "ai_prompt_responses"+ | "local_seo";++const CREDIT_FEATURE_LABELS: Record<string, string> = {+ keyword_research: "Keyword Research",+ domain_overview: "Domain Overview",+ backlinks: "Backlinks",+ site_audit: "Site Audit",+ rank_tracking: "Rank Tracking",+ ai_citations: "AI Citations",+ ai_prompt_responses: "AI Prompt Responses",+ ai_search: "AI Search",+ local_seo: "Local SEO",+};++/**+ * Maps a DataForSEO API response path (e.g. ["v3", "dataforseo_labs", "google", "related_keywords", "live"])+ * to a product feature for analytics. path[1] is the API module; for dataforseo_labs,+ * path[3] distinguishes keyword vs domain endpoints.+ */+export function mapDataforseoPathToCreditFeature(+ path: readonly string[],+): CreditFeature {+ const normalizedPath = path[0] === "v3" ? path : ["v3", ...path];+ const module = normalizedPath[1];++ switch (module) {+ case "on_page":+ return "site_audit";+ case "backlinks":+ return "backlinks";+ case "serp":+ return normalizedPath[2] === "google" &&+ ["maps", "local_finder"].includes(normalizedPath[3])+ ? "local_seo"+ : "keyword_research";+ case "ai_optimization":+ // llm_mentions/* are brand-citation lookups; every other ai_optimization+ // endpoint is a provider /llm_responses prompt response (chat_gpt, claude,+ // gemini, perplexity).+ return normalizedPath[2] === "llm_mentions"+ ? "ai_citations"+ : "ai_prompt_responses";+ case "business_data":+ return "local_seo";+ case "keywords_data":+ return "keyword_research";+ case "dataforseo_labs": {+ const endpoint = normalizedPath[3] ?? "";+ if (+ endpoint.startsWith("domain_") ||+ endpoint === "ranked_keywords" ||+ endpoint === "relevant_pages"+ ) {+ return "domain_overview";+ }+ return "keyword_research";+ }+ default:+ return "site_audit";+ }+}++export function creditFeatureLabel(key: string) {+ return CREDIT_FEATURE_LABELS[key] ?? "Other";+}