feat(webapp): show the billing limit on the usage page, with docs and tests

kathiekiwi · kathiekiwi · commit cb90d64d86e4 · 2026-06-22T11:01:42.000+02:00
Add the usage-bar marker, documentation, and test coverage.
diff --git a/apps/webapp/app/components/layout/AppLayout.tsx b/apps/webapp/app/components/layout/AppLayout.tsx
@@ -1,3 +1,4 @@
+import { forwardRef } from "react";
 import { cn } from "~/utils/cn";
 
 /** This container is used to surround the entire app, it correctly places the nav bar */
@@ -34,17 +35,17 @@ export function PageContainer({
   );
 }
 
-export function PageBody({
-  children,
-  scrollable = true,
-  className,
-}: {
-  children: React.ReactNode;
-  scrollable?: boolean;
-  className?: string;
-}) {
+export const PageBody = forwardRef<
+  HTMLDivElement,
+  {
+    children: React.ReactNode;
+    scrollable?: boolean;
+    className?: string;
+  }
+>(function PageBody({ children, scrollable = true, className }, ref) {
   return (
     <div
+      ref={ref}
       className={cn(
         scrollable
           ? "overflow-y-auto p-3 scrollbar-thin scrollbar-track-transparent scrollbar-thumb-charcoal-600"
@@ -55,7 +56,7 @@ export function PageBody({
       {children}
     </div>
   );
-}
+});
 
 export function MainCenteredContainer({
   children,
diff --git a/apps/webapp/app/hooks/useScrollContainerToTop.ts b/apps/webapp/app/hooks/useScrollContainerToTop.ts
@@ -0,0 +1,14 @@
+import { useLocation } from "@remix-run/react";
+import { useEffect, useRef } from "react";
+
+/** Scroll a page body container back to the top when navigating to a route. */
+export function useScrollContainerToTop<T extends HTMLElement>() {
+  const ref = useRef<T>(null);
+  const location = useLocation();
+
+  useEffect(() => {
+    ref.current?.scrollTo(0, 0);
+  }, [location.key]);
+
+  return ref;
+}
diff --git a/apps/webapp/app/routes/_app.orgs.$organizationSlug.settings.usage/route.tsx b/apps/webapp/app/routes/_app.orgs.$organizationSlug.settings.usage/route.tsx
@@ -6,6 +6,7 @@ import { Suspense, useMemo } from "react";
 import { redirect, typeddefer, useTypedLoaderData } from "remix-typedjson";
 import { URL } from "url";
 import { UsageBar } from "~/components/billing/UsageBar";
+import { getUsageBarBillingLimitDollars } from "~/components/billing/billingAlertsFormat";
 import { PageBody, PageContainer } from "~/components/layout/AppLayout";
 import { Card } from "~/components/primitives/charts/Card";
 import type { ChartConfig } from "~/components/primitives/charts/Chart";
@@ -30,6 +31,7 @@ import { useSearchParams } from "~/hooks/useSearchParam";
 import { UsagePresenter, type UsageSeriesData } from "~/presenters/v3/UsagePresenter.server";
 import { requireUserId } from "~/services/session.server";
 import { formatCurrency, formatCurrencyAccurate, formatNumber } from "~/utils/numberFormatter";
+import { useBillingLimit } from "~/hooks/useOrganizations";
 import { OrganizationParamsSchema, organizationPath } from "~/utils/pathBuilder";
 import { useCurrentPlan } from "../_app.orgs.$organizationSlug/route";
 
@@ -96,6 +98,11 @@ const monthDateFormatter = new Intl.DateTimeFormat("en-US", {
 export default function Page() {
   const { usage, tasks, months, isCurrentMonth } = useTypedLoaderData<typeof loader>();
   const currentPlan = useCurrentPlan();
+  const billingLimit = useBillingLimit();
+  const planLimitCents = currentPlan?.v3Subscription?.plan?.limits.includedUsage ?? 0;
+  const billingLimitDollars = isCurrentMonth
+    ? getUsageBarBillingLimitDollars(billingLimit, planLimitCents)
+    : undefined;
   const { value, replace } = useSearchParams();
 
   const month = value("month") ?? months[0].toISOString();
@@ -156,10 +163,9 @@ export default function Page() {
                         current={usage.overall.current}
                         isPaying={currentPlan?.v3Subscription?.isPaying ?? false}
                         tierLimit={
-                          isCurrentMonth
-                            ? (currentPlan?.v3Subscription?.plan?.limits.includedUsage ?? 0) / 100
-                            : undefined
+                          isCurrentMonth ? planLimitCents / 100 : undefined
                         }
+                        billingLimit={billingLimitDollars}
                       />
                     </div>
                   )}
diff --git a/apps/webapp/app/v3/services/billingLimit/runBillingLimitReconcileTick.server.ts b/apps/webapp/app/v3/services/billingLimit/runBillingLimitReconcileTick.server.ts
@@ -0,0 +1,72 @@
+import type { BillingLimitsPendingResolvesResult } from "~/services/billingLimit.schemas";
+import { runPendingBillingLimitResolves } from "./billingLimitPendingResolveCoordinator.server";
+import type { PendingBillingLimitResolve } from "./billingLimitPendingResolve.types";
+import type { OrgReconcileTarget } from "./billingLimitReconciliation.server";
+import type { reconcileBillingLimitTarget } from "./billingLimitReconcileTarget.server";
+
+export type RunBillingLimitReconcileTickDeps = {
+  getPendingResolves?: () => Promise<BillingLimitsPendingResolvesResult | undefined>;
+  runPendingResolves?: (
+    pendingResolves: PendingBillingLimitResolve[]
+  ) => Promise<Set<string>>;
+  collectOrgs?: (options?: { excludeOrgIds?: Set<string> }) => Promise<{
+    targets: OrgReconcileTarget[];
+    queuedOrgIds: string[];
+  }>;
+  reconcileTarget?: typeof reconcileBillingLimitTarget;
+  clearProcessedQueue?: (
+    queuedOrgIds: string[],
+    processedOrgIds: string[]
+  ) => Promise<void>;
+  bustCaches?: (organizationId: string) => void;
+  enqueueConverge?: (
+    organizationId: string,
+    targetState: OrgReconcileTarget["targetState"]
+  ) => Promise<void>;
+};
+
+export async function runBillingLimitReconcileTick(
+  deps: RunBillingLimitReconcileTickDeps = {}
+): Promise<void> {
+  const getPendingResolves =
+    deps.getPendingResolves ??
+    (await import("~/services/platform.v3.server")).getPendingBillingLimitResolves;
+  const runPendingResolves = deps.runPendingResolves ?? runPendingBillingLimitResolves;
+  const collectOrgs =
+    deps.collectOrgs ??
+    (await import("./billingLimitReconciliation.server")).collectOrgsToReconcile;
+  const reconcileTarget =
+    deps.reconcileTarget ??
+    (await import("./billingLimitReconcileTarget.server")).reconcileBillingLimitTarget;
+  const clearProcessedQueue =
+    deps.clearProcessedQueue ??
+    (await import("./billingLimitReconciliation.server")).clearProcessedReconcileQueueEntries;
+  const bustCaches =
+    deps.bustCaches ?? (await import("~/services/platform.v3.server")).bustBillingLimitCaches;
+
+  const pendingResolves = (await getPendingResolves())?.orgs ?? [];
+  const stillPendingOrgIds = await runPendingResolves(pendingResolves);
+
+  const { targets, queuedOrgIds } = await collectOrgs({
+    excludeOrgIds: stillPendingOrgIds,
+  });
+
+  const enqueueConverge =
+    deps.enqueueConverge ??
+    (async (organizationId, targetState) => {
+      const { enqueueBillingLimitConverge } = await import("~/v3/billingLimitWorker.server");
+      await enqueueBillingLimitConverge(organizationId, targetState);
+    });
+
+  for (const target of targets) {
+    await reconcileTarget(target, {
+      bustCaches,
+      enqueueConverge,
+    });
+  }
+
+  await clearProcessedQueue(
+    queuedOrgIds,
+    targets.map((target) => target.organizationId)
+  );
+}
diff --git a/apps/webapp/server.ts b/apps/webapp/server.ts
@@ -103,6 +103,10 @@ if (ENABLE_CLUSTER && cluster.isPrimary) {
 
   // Remix fingerprints its assets so we can cache forever.
   app.use("/build", express.static("public/build", { immutable: true, maxAge: "1y" }));
+  // Stale dev builds can request an old hashed manifest; don't fall through to Remix.
+  app.use("/build", (_req, res) => {
+    res.status(404).end();
+  });
 
   // Everything else (like favicon.ico) is cached for an hour. You may want to be
   // more aggressive with this caching.
diff --git a/apps/webapp/test/billingLimitEnvCreatePause.test.ts b/apps/webapp/test/billingLimitEnvCreatePause.test.ts
@@ -0,0 +1,70 @@
+import { EnvironmentPauseSource } from "@trigger.dev/database";
+import { describe, expect, it } from "vitest";
+import type { BillingLimitResult } from "~/services/billingLimit.schemas";
+import { getInitialEnvPauseStateForBillingLimit } from "~/v3/services/billingLimit/getInitialEnvPauseStateForBillingLimit.server";
+
+function configuredLimit(
+  status: "grace" | "rejected" | "ok"
+): BillingLimitResult {
+  const hitAt = "2026-06-16T12:00:00.000Z";
+  const graceEndsAt = "2026-06-17T12:00:00.000Z";
+
+  return {
+    isConfigured: true,
+    mode: "custom",
+    amountCents: 50_000,
+    cancelInProgressRuns: false,
+    effectiveAmountCents: 50_000,
+    gracePeriodMs: 86_400_000,
+    limitState:
+      status === "ok"
+        ? { status: "ok" }
+        : { status, hitAt, graceEndsAt },
+  };
+}
+
+describe("getInitialEnvPauseStateForBillingLimit", () => {
+  it("pauses billable environments when org is in grace", async () => {
+    const result = await getInitialEnvPauseStateForBillingLimit("org_123", "PRODUCTION", {
+      getBillingLimit: async () => configuredLimit("grace"),
+    });
+
+    expect(result).toEqual({
+      paused: true,
+      pauseSource: EnvironmentPauseSource.BILLING_LIMIT,
+    });
+  });
+
+  it("pauses billable environments when org is rejected", async () => {
+    const result = await getInitialEnvPauseStateForBillingLimit("org_123", "STAGING", {
+      getBillingLimit: async () => configuredLimit("rejected"),
+    });
+
+    expect(result).toEqual({
+      paused: true,
+      pauseSource: EnvironmentPauseSource.BILLING_LIMIT,
+    });
+  });
+
+  it("does not pause development environments", async () => {
+    const result = await getInitialEnvPauseStateForBillingLimit("org_123", "DEVELOPMENT", {
+      getBillingLimit: async () => configuredLimit("rejected"),
+    });
+
+    expect(result).toEqual({
+      paused: false,
+      pauseSource: null,
+    });
+  });
+
+  it("does not pause when billing limit is ok", async () => {
+    const result = await getInitialEnvPauseStateForBillingLimit("org_123", "PRODUCTION", {
+      getBillingLimit: async () => configuredLimit("ok"),
+    });
+
+    expect(result).toEqual({
+      paused: false,
+      pauseSource: null,
+    });
+  });
+});
diff --git a/apps/webapp/test/billingLimitReconcileTick.test.ts b/apps/webapp/test/billingLimitReconcileTick.test.ts
@@ -0,0 +1,77 @@
+import { describe, expect, it } from "vitest";
+import { runBillingLimitReconcileTick } from "~/v3/services/billingLimit/runBillingLimitReconcileTick.server";
+import type { PendingBillingLimitResolve } from "~/v3/services/billingLimit/billingLimitPendingResolve.types";
+
+describe("runBillingLimitReconcileTick", () => {
+  const pending: PendingBillingLimitResolve = {
+    organizationId: "org_pending",
+    resumeMode: "queue",
+    resolvedAt: "2026-06-17T12:00:00.000Z",
+  };
+
+  it("runs pending resolves before collecting orgs and excludes still-pending orgs", async () => {
+    const order: string[] = [];
+
+    await runBillingLimitReconcileTick({
+      getPendingResolves: async () => ({ orgs: [pending] }),
+      runPendingResolves: async (pendingResolves) => {
+        order.push(`pending:${pendingResolves.map((row) => row.organizationId).join(",")}`);
+        return new Set(["org_pending"]);
+      },
+      collectOrgs: async (options) => {
+        order.push(`collect:${[...options?.excludeOrgIds ?? []].join(",")}`);
+        return {
+          targets: [{ organizationId: "org_active", targetState: "grace" }],
+          queuedOrgIds: ["org_active"],
+        };
+      },
+      reconcileTarget: async (target) => {
+        order.push(`reconcile:${target.organizationId}:${target.targetState}`);
+      },
+      clearProcessedQueue: async (queuedOrgIds, processedOrgIds) => {
+        order.push(`clear:${queuedOrgIds.join(",")}:${processedOrgIds.join(",")}`);
+      },
+      bustCaches: () => {},
+      enqueueConverge: async () => undefined,
+    });
+
+    expect(order).toEqual([
+      "pending:org_pending",
+      "collect:org_pending",
+      "reconcile:org_active:grace",
+      "clear:org_active:org_active",
+    ]);
+  });
+
+  it("reconciles collected targets when no pending resolves remain", async () => {
+    const reconciled: Array<{ organizationId: string; targetState: string }> = [];
+
+    await runBillingLimitReconcileTick({
+      getPendingResolves: async () => ({ orgs: [] }),
+      runPendingResolves: async () => new Set(),
+      collectOrgs: async () => ({
+        targets: [
+          { organizationId: "org_grace", targetState: "grace" },
+          { organizationId: "org_ok", targetState: "ok" },
+        ],
+        queuedOrgIds: ["org_grace", "org_ok"],
+      }),
+      reconcileTarget: async (target, deps) => {
+        reconciled.push(target);
+        await deps.enqueueConverge(target.organizationId, target.targetState);
+      },
+      clearProcessedQueue: async () => undefined,
+      bustCaches: () => {},
+      enqueueConverge: async (organizationId, targetState) => {
+        reconciled.push({ organizationId, targetState: `enqueued:${targetState}` });
+      },
+    });
+
+    expect(reconciled).toEqual([
+      { organizationId: "org_grace", targetState: "grace" },
+      { organizationId: "org_grace", targetState: "enqueued:grace" },
+      { organizationId: "org_ok", targetState: "ok" },
+      { organizationId: "org_ok", targetState: "enqueued:ok" },
+    ]);
+  });
+});
