fix(billing): clarify org usage vs personal spend on Plan & usage

The Plan & usage page showed an org-level usage meter directly above a
user-level spend analysis with no cue that the two have different scopes,
so the spend numbers could read as the whole organization's.

- Label the usage meter "Organization usage" with a caption noting it's
  shared across the whole organization (and "Your usage" for the per-user
  free-tier valve fallback).
- Rename "Spend analysis" to "Your spend analysis" with a caption noting
  it covers only the signed-in user's usage.
- Reword the org billing-period countdown from "Resets …" to
  "Billing period ends …" via an optional label on formatResetTime; kept
  "Resets" for the per-user free-tier valve windows, which really do reset.

Generated-By: PostHog Code
Task-Id: d69678da-415c-450b-aafe-3d834d0bc557

Author: adboio

packages/core/src/billing/usageDisplay.test.ts

@@ -186,11 +186,27 @@ describe("formatResetTime", () => {
       expected: "Resets shortly",
     },
   ])("$name", ({ resetAt, expected }) => {
-    const result = formatResetTime(resetAt, NOW);
+    const result = formatResetTime(resetAt, { now: NOW });
     if (expected instanceof RegExp) {
       expect(result).toMatch(expected);
     } else {
       expect(result).toBe(expected);
     }
   });
+
+  it("swaps the leading phrase when a custom label is given", () => {
+    const opts = { now: NOW, label: "Billing period ends" };
+    expect(formatResetTime(isoAt(30 * 60 * 1000), opts)).toBe(
+      "Billing period ends in 30m",
+    );
+    expect(formatResetTime(isoAt(4 * 3600 * 1000), opts)).toBe(
+      "Billing period ends in 4h",
+    );
+    expect(formatResetTime(isoAt(-60_000), opts)).toBe(
+      "Billing period ends shortly",
+    );
+    expect(formatResetTime(isoAt(30 * 86400 * 1000), opts)).toMatch(
+      /^Billing period ends [A-Za-z]+ \d+ at /,
+    );
+  });
 });

packages/core/src/billing/usageDisplay.ts

@@ -57,16 +57,22 @@ export function isUsageExceeded(usage: UsageOutput): boolean {
   );
 }
 
+/**
+ * Renders a countdown to `resetAtIso` as a short phrase. `label` is the leading
+ * verb phrase (default "Resets") so callers pick wording that matches what the
+ * timestamp actually is — e.g. "Billing period ends" for an org's
+ * `billing_period_end`, "Resets" for a per-user free-tier valve window.
+ */
 export function formatResetTime(
   resetAtIso: string,
-  now: number = Date.now(),
+  { now = Date.now(), label = "Resets" }: { now?: number; label?: string } = {},
 ): string {
   const parsed = Date.parse(resetAtIso);
   const ms = Number.isNaN(parsed) ? 0 : Math.max(0, parsed - now);
 
   const totalMinutes = Math.ceil(ms / 60_000);
-  if (totalMinutes <= 0) return "Resets shortly";
-  if (totalMinutes < 60) return `Resets in ${totalMinutes}m`;
+  if (totalMinutes <= 0) return `${label} shortly`;
+  if (totalMinutes < 60) return `${label} in ${totalMinutes}m`;
 
   const totalHours = ms / 3_600_000;
   if (totalHours < 24) {
@@ -77,8 +83,8 @@ export function formatResetTime(
       minutes = 0;
     }
     return minutes === 0
-      ? `Resets in ${hours}h`
-      : `Resets in ${hours}h ${minutes}m`;
+      ? `${label} in ${hours}h`
+      : `${label} in ${hours}h ${minutes}m`;
   }
 
   const target = new Date(now + ms);
@@ -91,5 +97,5 @@ export function formatResetTime(
     minute: "2-digit",
     timeZoneName: "short",
   });
-  return `Resets ${date} at ${time}`;
+  return `${label} ${date} at ${time}`;
 }

packages/ui/src/features/billing/UsageButton.tsx

@@ -67,9 +67,10 @@ export function UsageButton() {
     meter.kind === "dollars"
       ? `${formatUsdAmount(meter.usedUsd)} of ${formatUsdAmount(meter.limitUsd)} used`
       : `${percent}% used`;
-  const resetLabel = formatResetTime(
-    meter.kind === "dollars" ? meter.resetAt : meter.bucket.reset_at,
-  );
+  const resetLabel =
+    meter.kind === "dollars"
+      ? formatResetTime(meter.resetAt, { label: "Billing period ends" })
+      : formatResetTime(meter.bucket.reset_at);
 
   // Upgrade-prompt analytics only apply to free-tier orgs — a subscribed
   // org's meter is not an upgrade prompt.

packages/ui/src/features/settings/sections/PlanUsageSettings.tsx

@@ -66,6 +66,11 @@ export function PlanUsageSettings() {
   const subscribed = usage?.code_usage_subscribed === true;
   const orgLimitReached = usage?.ai_credits?.exhausted === true;
   const meter = codeUsageMeter(usage);
+  // The dollars meter tracks the whole organization's usage-based spend; only
+  // the free-tier valve bucket is a per-user allowance. Spell out which scope
+  // is on screen so this bar isn't misread as personal usage like the spend
+  // analysis (which really is just the signed-in user) further down the page.
+  const usageIsPerUser = meter.kind === "bucket";
 
   const openBilling = () => {
     if (billingUrl) window.open(billingUrl, "_blank");
@@ -163,7 +168,16 @@ export function PlanUsageSettings() {
           </Flex>
 
           <Flex direction="column" gap="3">
-            <Text className="font-medium text-(--gray-9) text-sm">Usage</Text>
+            <Flex direction="column" gap="1">
+              <Text className="font-medium text-(--gray-9) text-sm">
+                {usageIsPerUser ? "Your usage" : "Organization usage"}
+              </Text>
+              <Text className="text-(--gray-11) text-[13px]">
+                {usageIsPerUser
+                  ? "Your personal free-tier allowance for this period."
+                  : "Usage-based billing shared across your whole organization."}
+              </Text>
+            </Flex>
             {usageLoading ? (
               <Flex
                 align="center"
@@ -178,7 +192,7 @@ export function PlanUsageSettings() {
                 label={freeTier ? "Monthly free usage" : "Usage this period"}
                 percent={meter.percent}
                 valueLabel={`${formatUsdAmount(meter.usedUsd)} of ${formatUsdAmount(meter.limitUsd)}${freeTier ? " included" : ""}`}
-                detail={`${meter.exceeded ? "Limit exceeded. " : ""}${formatResetTime(meter.resetAt)}`}
+                detail={`${meter.exceeded ? "Limit exceeded. " : ""}${formatResetTime(meter.resetAt, { label: "Billing period ends" })}`}
                 color={meter.exceeded ? "red" : undefined}
               />
             ) : meter.kind === "bucket" ? (

packages/ui/src/features/usage/components/SpendAnalysisSection.tsx

@@ -36,10 +36,15 @@ export function SpendAnalysisSection() {
 
   return (
     <Flex direction="column" gap="3">
-      <Flex align="center" justify="between">
-        <Text className="font-medium text-(--gray-9) text-sm">
-          Spend analysis
-        </Text>
+      <Flex align="start" justify="between" gap="4">
+        <Flex direction="column" gap="1">
+          <Text className="font-medium text-(--gray-9) text-sm">
+            Your spend analysis
+          </Text>
+          <Text className="text-(--gray-11) text-[13px]">
+            Just your own usage, not your whole organization's.
+          </Text>
+        </Flex>
         <Flex align="center" gap="4">
           <WindowSelector value={spendWindow} onChange={setSpendWindow} />
           <Button