Skip to content

Supercharge your AI agents with data from the web and beyond. Building the library for superintelligence. 🔥

feat(billing): rewrite balance usage endpoints to use Autumn API (#3272)

firecrawl-spring[bot]043cfb789af7
diff --git a/apps/api/src/controllers/v1/credit-usage.ts b/apps/api/src/controllers/v1/credit-usage.ts
index 7ce1e0f22..4f869cb70 100644
--- a/apps/api/src/controllers/v1/credit-usage.ts
+++ b/apps/api/src/controllers/v1/credit-usage.ts
@@ -1,7 +1,6 @@
import { Response } from "express";
import { ErrorResponse, RequestWithAuth } from "./types";
-import { getACUCTeam } from "../auth";
-import { RateLimiterMode } from "../../types";
+import { getTeamBalance } from "../../services/autumn/usage";
interface CreditUsageResponse {
success: true;
@@ -17,10 +16,9 @@ export async function creditUsageController(
req: RequestWithAuth,
res: Response<CreditUsageResponse | ErrorResponse>,
): Promise<void> {
- const chunk =
- req.acuc ??
- (await getACUCTeam(req.auth.team_id, false, false, RateLimiterMode.Scrape));
- if (!chunk) {
+ const balance = await getTeamBalance(req.auth.team_id);
+
+ if (!balance) {
res.status(404).json({
success: false,
error: "Could not find credit usage information",
@@ -31,10 +29,10 @@ export async function creditUsageController(
res.json({
success: true,
data: {
- remaining_credits: chunk.remaining_credits,
- plan_credits: chunk.price_credits,
- billing_period_start: chunk.sub_current_period_start,
- billing_period_end: chunk.sub_current_period_end,
+ remaining_credits: balance.remaining,
+ plan_credits: balance.planCredits,
+ billing_period_start: balance.periodStart,
+ billing_period_end: balance.periodEnd,
},
});
}
diff --git a/apps/api/src/controllers/v1/token-usage.ts b/apps/api/src/controllers/v1/token-usage.ts
index f88b9e352..60deda6e5 100644
--- a/apps/api/src/controllers/v1/token-usage.ts
+++ b/apps/api/src/controllers/v1/token-usage.ts
@@ -1,7 +1,8 @@
import { Response } from "express";
import { ErrorResponse, RequestWithAuth } from "./types";
-import { getACUCTeam } from "../auth";
-import { RateLimiterMode } from "../../types";
+import { getTeamBalance } from "../../services/autumn/usage";
+
+const TOKENS_PER_CREDIT = 15;
interface TokenUsageResponse {
success: true;
@@ -17,15 +18,9 @@ export async function tokenUsageController(
req: RequestWithAuth,
res: Response<TokenUsageResponse | ErrorResponse>,
): Promise<void> {
- const chunk =
- req.acuc ??
- (await getACUCTeam(
- req.auth.team_id,
- false,
- false,
- RateLimiterMode.Extract,
- ));
- if (!chunk) {
+ const balance = await getTeamBalance(req.auth.team_id);
+
+ if (!balance) {
res.status(404).json({
success: false,
error: "Could not find token usage information",
@@ -36,10 +31,10 @@ export async function tokenUsageController(
res.json({
success: true,
data: {
- remaining_tokens: chunk.remaining_credits,
- plan_tokens: chunk.price_credits,
- billing_period_start: chunk.sub_current_period_start,
- billing_period_end: chunk.sub_current_period_end,
+ remaining_tokens: balance.remaining * TOKENS_PER_CREDIT,
+ plan_tokens: balance.planCredits * TOKENS_PER_CREDIT,
+ billing_period_start: balance.periodStart,
+ billing_period_end: balance.periodEnd,
},
});
}
diff --git a/apps/api/src/controllers/v2/credit-usage.ts b/apps/api/src/controllers/v2/credit-usage.ts
index b47ed88f4..56f9a95c4 100644
--- a/apps/api/src/controllers/v2/credit-usage.ts
+++ b/apps/api/src/controllers/v2/credit-usage.ts
@@ -1,7 +1,6 @@
import { Response } from "express";
import { ErrorResponse, RequestWithAuth } from "./types";
-import { getACUCTeam } from "../auth";
-import { RateLimiterMode } from "../../types";
+import { getTeamBalance } from "../../services/autumn/usage";
interface CreditUsageResponse {
success: true;
@@ -17,11 +16,9 @@ export async function creditUsageController(
req: RequestWithAuth,
res: Response<CreditUsageResponse | ErrorResponse>,
): Promise<void> {
- const chunk =
- req.acuc ??
- (await getACUCTeam(req.auth.team_id, false, false, RateLimiterMode.Scrape));
+ const balance = await getTeamBalance(req.auth.team_id);
- if (!chunk) {
+ if (!balance) {
res.status(404).json({
success: false,
error: "Could not find credit usage information",
@@ -32,10 +29,10 @@ export async function creditUsageController(
res.json({
success: true,
data: {
- remainingCredits: chunk.remaining_credits,
- planCredits: chunk.price_credits,
- billingPeriodStart: chunk.sub_current_period_start,
- billingPeriodEnd: chunk.sub_current_period_end,
+ remainingCredits: balance.remaining,
+ planCredits: balance.planCredits,
+ billingPeriodStart: balance.periodStart,
+ billingPeriodEnd: balance.periodEnd,
},
});
}
diff --git a/apps/api/src/controllers/v2/token-usage.ts b/apps/api/src/controllers/v2/token-usage.ts
index ec5034cd8..e85cfe05b 100644
--- a/apps/api/src/controllers/v2/token-usage.ts
+++ b/apps/api/src/controllers/v2/token-usage.ts
@@ -1,7 +1,8 @@
import { Response } from "express";
import { ErrorResponse, RequestWithAuth } from "./types";
-import { getACUCTeam } from "../auth";
-import { RateLimiterMode } from "../../types";
+import { getTeamBalance } from "../../services/autumn/usage";
+
+const TOKENS_PER_CREDIT = 15;
interface TokenUsageResponse {
success: true;
@@ -17,16 +18,9 @@ export async function tokenUsageController(
req: RequestWithAuth,
res: Response<TokenUsageResponse | ErrorResponse>,
): Promise<void> {
- const chunk =
- req.acuc ??
- (await getACUCTeam(
- req.auth.team_id,
- false,
- false,
- RateLimiterMode.Extract,
- ));
+ const balance = await getTeamBalance(req.auth.team_id);
- if (!chunk) {
+ if (!balance) {
res.status(404).json({
success: false,
error: "Could not find token usage information",
@@ -37,10 +31,10 @@ export async function tokenUsageController(
res.json({
success: true,
data: {
- remainingTokens: chunk.remaining_credits,
- planTokens: chunk.price_credits,
- billingPeriodStart: chunk.sub_current_period_start,
- billingPeriodEnd: chunk.sub_current_period_end,
+ remainingTokens: balance.remaining * TOKENS_PER_CREDIT,
+ planTokens: balance.planCredits * TOKENS_PER_CREDIT,
+ billingPeriodStart: balance.periodStart,
+ billingPeriodEnd: balance.periodEnd,
},
});
}
diff --git a/apps/api/src/services/autumn/usage.ts b/apps/api/src/services/autumn/usage.ts
new file mode 100644
index 000000000..d4936fa57
--- /dev/null
+++ b/apps/api/src/services/autumn/usage.ts
@@ -0,0 +1,127 @@
+import { logger } from "../../lib/logger";
+import { supabase_rr_service } from "../supabase";
+import { autumnClient } from "./client";
+
+const CREDITS_FEATURE_ID = "CREDITS";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+interface TeamBalance {
+ remaining: number;
+ granted: number;
+ planCredits: number;
+ usage: number;
+ unlimited: boolean;
+ periodStart: string | null;
+ periodEnd: string | null;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+async function lookupOrgId(teamId: string): Promise<string> {
+ const { data, error } = await supabase_rr_service
+ .from("teams")
+ .select("org_id")
+ .eq("id", teamId)
+ .single();
+
+ if (error) throw error;
+ if (!data?.org_id) {
+ throw new Error(`Missing org_id for team ${teamId}`);
+ }
+ return data.org_id;
+}
+
+// ---------------------------------------------------------------------------
+// Balance (current billing period)
+// ---------------------------------------------------------------------------
+
+/**
+ * Fetches a team's credit balance and billing period from Autumn.
+ *
+ * Tries entity-scoped balance first (team as entity under org customer),
+ * then falls back to customer-level balance.
+ */
+export async function getTeamBalance(
+ teamId: string,
+): Promise<TeamBalance | null> {
+ if (!autumnClient) {
+ throw new Error("Autumn client is not configured (AUTUMN_SECRET_KEY missing)");
+ }
+
+ const orgId = await lookupOrgId(teamId);
+
+ // Try entity-scoped balance first
+ let balances: Record<string, any> | undefined;
+ let subscriptions: Array<any> | undefined;
+
+ try {
+ const entity = await autumnClient.entities.get({
+ customerId: orgId,
+ entityId: teamId,
+ });
+ balances = entity?.balances;
+ subscriptions = entity?.subscriptions;
+ } catch (err: any) {
+ const status = err?.statusCode ?? err?.status ?? err?.response?.status;
+ if (status !== 404) throw err;
+ // Entity not found — fall through to customer-level
+ }
+
+ // Fall back to customer-level balance if CREDITS feature not present
+ if (!balances?.[CREDITS_FEATURE_ID]) {
+ const customer = await autumnClient.customers.getOrCreate({
+ customerId: orgId,
+ autoEnablePlanId: "free",
+ });
+ balances = customer?.balances;
+ subscriptions = customer?.subscriptions;
+ }
+
+ const creditBalance = balances?.[CREDITS_FEATURE_ID];
+
+ if (!creditBalance) {
+ return null;
+ }
+
+ // Find the active subscription's billing period
+ const activeSub = subscriptions?.find(
+ (s: any) =>
+ s.status === "active" ||
+ s.status === "trialing" ||
+ s.status === "past_due",
+ );
+
+ const periodStartEpoch = activeSub?.currentPeriodStart;
+ const periodEndEpoch = activeSub?.currentPeriodEnd;
+
+ // Extract plan-only credits from the breakdown (excludes credit packs,
+ // auto-recharge, etc.) to preserve backwards compatibility with the old
+ // planCredits field semantics.
+ let planCredits = creditBalance?.granted ?? 0;
+ const breakdowns: Array<any> | undefined = creditBalance?.breakdown;
+ if (breakdowns?.length) {
+ planCredits = breakdowns.reduce(
+ (sum: number, b: any) => sum + (b.includedGrant ?? 0),
+ 0,
+ );
+ }
+
+ return {
+ remaining: creditBalance?.remaining ?? 0,
+ granted: creditBalance?.granted ?? 0,
+ planCredits,
+ usage: creditBalance?.usage ?? 0,
+ unlimited: creditBalance?.unlimited ?? false,
+ periodStart: periodStartEpoch
+ ? new Date(periodStartEpoch * 1000).toISOString()
+ : null,
+ periodEnd: periodEndEpoch
+ ? new Date(periodEndEpoch * 1000).toISOString()
+ : null,
+ };
+}