@startsimpli/billing 0.4.12 → 0.4.15

package/src/components/SubscriptionManager.tsx

@@ -12,11 +12,15 @@
  *   />
  */
 
-import React from "react";
+import React, { useEffect, useRef } from "react";
 import { useSubscription } from "../hooks/useSubscription";
 import { useProduct } from "../hooks/useProduct";
 import { usePortal } from "../hooks/usePortal";
-import type { ProductOffer } from "../types";
+import { useCheckout } from "../hooks/useCheckout";
+import { useUsage } from "../hooks/useUsage";
+import { useSuccessSync } from "../hooks/useSuccessSync";
+import type { OfferFeature, ProductOffer } from "../types";
+import { CurrentPlanCard } from "./CurrentPlanCard";
 
 export interface SubscriptionManagerProps {
   /** Product slug (e.g., "raise-simpli") */
@@ -32,6 +36,78 @@ export interface SubscriptionManagerProps {
   statusMessage?: "success" | "cancelled" | "activating" | null;
 }
 
+/** Render one OfferFeature row. Skips boolean-false (the plan _doesn't_ have
+ * that feature so we don't pretend it does). Numeric limits surface as
+ * "Unlimited X" (-1) / "Up to N X" / "X" (no limit attribute).
+ * startsim-o7u — kills the blank gap between price and CTA on plan cards. */
+function FeatureRow({ feature }: { feature: OfferFeature }) {
+  const v = feature.value;
+  if (v === false) return null;
+
+  let label = feature.name;
+  if (typeof v === "number" || typeof feature.limit === "number") {
+    const limit = typeof feature.limit === "number" ? feature.limit
+                : typeof v === "number" ? v : null;
+    if (limit === -1) label = `Unlimited ${feature.name.toLowerCase()}`;
+    else if (limit !== null && limit > 0) label = `Up to ${limit} ${feature.name.toLowerCase()}`;
+  }
+
+  return (
+    <li className="flex items-start gap-2 text-sm text-gray-700">
+      <svg className="w-4 h-4 text-green-600 mt-0.5 shrink-0" fill="none" viewBox="0 0 24 24"
+           stroke="currentColor" strokeWidth={2.5} aria-hidden="true">
+        <path strokeLinecap="round" strokeLinejoin="round" d="M5 13l4 4L19 7" />
+      </svg>
+      <span>{label}</span>
+    </li>
+  );
+}
+
+function PlanFeatureList({ features }: { features: OfferFeature[] }) {
+  if (!features || features.length === 0) return null;
+  return (
+    <ul data-testid="plan-features" className="space-y-1.5 mb-4">
+      {features.map((f) => <FeatureRow key={f.key} feature={f} />)}
+    </ul>
+  );
+}
+
+/** Subtle trial copy below the price block on offers that ship a trial.
+ * startsim-pih — so users know "Start Free Trial" actually IS a free trial. */
+function TrialCopy({ trialDays }: { trialDays: number }) {
+  if (!trialDays || trialDays <= 0) return null;
+  return (
+    <p data-testid="trial-copy" className="-mt-1 mb-3 text-xs text-gray-500">
+      {trialDays}-day free trial · no card required
+    </p>
+  );
+}
+
+/** Layout-matching skeleton block for SubscriptionManager loading state.
+ * startsim-z6f — replaces the bare "Loading subscription…" text. */
+function PlanSkeleton({ testId, tall = false }: { testId: string; tall?: boolean }) {
+  return (
+    <div data-testid={testId} className={`rounded-xl border border-gray-200 bg-white shadow-sm ${tall ? "p-8" : "p-6"} animate-pulse`}>
+      <div className="flex items-center justify-between mb-4">
+        <div className="h-6 w-24 bg-gray-200 rounded" />
+        <div className="h-5 w-16 bg-gray-100 rounded-full" />
+      </div>
+      <div className="h-9 w-32 bg-gray-200 rounded mb-6" />
+      {tall && (
+        <div className="space-y-3">
+          {[0, 1, 2, 3].map((i) => (
+            <div key={i} className="flex items-center gap-3">
+              <div className="h-4 w-4 bg-gray-200 rounded" />
+              <div className="h-4 flex-1 bg-gray-100 rounded" />
+            </div>
+          ))}
+        </div>
+      )}
+      <div className={`${tall ? "mt-6" : "mt-4"} h-9 w-full bg-gray-100 rounded-xl`} />
+    </div>
+  );
+}
+
 function formatDate(iso: string): string {
   const d = new Date(iso);
   const year = d.getUTCFullYear();
@@ -96,33 +172,138 @@ export function SubscriptionManager({
   onPlanChange,
   statusMessage,
 }: SubscriptionManagerProps) {
-  const { subscription, loading: subLoading, error: subError } = useSubscription();
-  const { product, loading: productLoading } = useProduct(productId);
+  const { subscription, loading: subLoading, error: subError, refetch: refetchSubscription } = useSubscription();
+  const { product, loading: productLoading, error: productError, refetch: refetchProduct } = useProduct(productId);
   const { openPortal, loading: portalLoading } = usePortal();
+  const { subscribeFree } = useCheckout();
+  const { usage } = useUsage(productId);
+  const { sync: successSync } = useSuccessSync();
 
-  const loading = subLoading || productLoading;
+  // startsim-ngw — when the user lands on ?status=success (just back from
+  // Stripe checkout), POST /billing/success-sync/ ONCE to populate the cache
+  // from Stripe so the UI flips to Trialing/Active without waiting for the
+  // webhook, then refetch the subscription. The ref guard prevents the effect
+  // re-firing on React StrictMode double-invokes.
+  const successSyncedRef = useRef(false);
+  useEffect(() => {
+    if (statusMessage === "success" && !successSyncedRef.current) {
+      successSyncedRef.current = true;
+      (async () => {
+        try {
+          await successSync();
+        } finally {
+          await refetchSubscription();
+        }
+      })();
+    }
+  }, [statusMessage, successSync, refetchSubscription]);
 
-  if (loading) {
+  // startsim-z6f: skeleton matching the final layout (current-plan box +
+  // 2-card grid) so the transition from loading → loaded doesn't reflow.
+  // startsim-mtv: tolerate partial loads — sub-loaded-but-product-not is
+  // common (the two endpoints fetch independently), and crashing the page
+  // during that window is worse than rendering only the half that's ready.
+  if (subLoading && productLoading) {
     return (
-      <div data-testid="subscription-manager" className="max-w-3xl mx-auto px-6 py-12">
-        <p className="text-center text-gray-500">Loading subscription...</p>
+      <div data-testid="subscription-manager" className="max-w-3xl mx-auto px-6 py-12 space-y-8">
+        <PlanSkeleton testId="skeleton-current-plan" tall />
+        <div className="grid gap-4 sm:grid-cols-2 lg:grid-cols-3">
+          <PlanSkeleton testId="skeleton-plan-card" />
+          <PlanSkeleton testId="skeleton-plan-card" />
+        </div>
       </div>
     );
   }
 
-  if (subError) {
+  // Subscription-fetch error gets a tight inline message instead of nuking the
+  // entire page — users can still see plan cards (once product loads) and try
+  // a refresh. startsim-c0r is the product-side equivalent below.
+  if (subError && !subscription) {
     return (
       <div data-testid="subscription-manager" className="max-w-3xl mx-auto px-6 py-12">
-        <div className="text-center text-red-600">
-          <p className="font-semibold">Something went wrong</p>
-          <p className="text-sm mt-1">{subError.message}</p>
+        <div data-testid="error-subscription" className="rounded-xl border border-red-200 bg-red-50 p-4 text-sm text-red-800">
+          Couldn&apos;t load your subscription. {subError.message}
         </div>
       </div>
     );
   }
 
-  const currentOfferId = subscription?.offer?.id ?? null;
-  const availableOffers = product?.offers.filter((o) => o.id !== currentOfferId) ?? [];
+  // A subscription is only renderable if it carries a nested `offer` object —
+  // the cache-path payload (offerId/offerSlug, no `offer`) is normalized away in
+  // BillingApiClient, but guard here too so CurrentPlanCard can never deref
+  // `subscription.offer.*` on undefined and white-screen the page.
+  const usableSubscription = subscription?.offer ? subscription : null;
+  const currentOfferId = usableSubscription?.offer?.id ?? null;
+  const currentOffer = usableSubscription?.offer ?? null;
+  // Show ALL offers in the Change Plan grid (not just non-current ones) so users
+  // can compare and see what they have. The card matching their current sub
+  // gets a "Current Plan" badge + disabled CTA. startsim-1f1.
+  const allOffers = product?.offers ?? [];
+
+  /** Per-card direction relative to the current subscription:
+   * - "current"   → user is on this exact offer → "Current Plan" badge, no action
+   * - "upgrade"   → card is a higher tier (paid vs current free, or higher sortOrder)
+   * - "downgrade" → card is a lower tier (free when current is paid, or lower sortOrder)
+   * startsim-21f. */
+  type Direction = "current" | "upgrade" | "downgrade";
+  function directionFor(cardOffer: ProductOffer): Direction {
+    if (!currentOffer) return "upgrade"; // legacy: no sub → every card is an upgrade
+    if (cardOffer.id === currentOffer.id) return "current";
+    // Free vs Paid: paid is always an upgrade, free is always a downgrade.
+    if (cardOffer.isFree && !currentOffer.isFree) return "downgrade";
+    if (!cardOffer.isFree && currentOffer.isFree) return "upgrade";
+    // Both paid → compare sortOrder (apps order their tiers low → high).
+    return cardOffer.sortOrder > currentOffer.sortOrder ? "upgrade" : "downgrade";
+  }
+
+  /** Visible CTA label for the card, branching on direction. The default
+   * `offer.ctaText` (e.g. "Start Free Trial") is for UPGRADE only — using it
+   * on a Free card when a Pro user is looking is the bug startsim-21f closes. */
+  function ctaLabelFor(cardOffer: ProductOffer, direction: Direction): string {
+    if (direction === "current") return "Current Plan";
+    if (direction === "downgrade") return `Downgrade to ${cardOffer.name}`;
+    return cardOffer.ctaText || `Upgrade to ${cardOffer.name}`;
+  }
+
+  // Branch the offer CTA internally so apps don't reinvent it:
+  // - Free offers → POST /billing/subscribe-free/ then refetch subscription
+  //   (no Stripe round-trip needed for $0 plans — startsim-6vk).
+  // - Paid offers → app-supplied onPlanChange (typically a Stripe checkout
+  //   redirect via useCheckout).
+  const handleOfferClick = async (offer: ProductOffer) => {
+    // Non-owner viewers can SEE the plans but can't change them — startsim-wo9.
+    if (subscription?.viewerIsOwner === false) return;
+    if (offer.isFree) {
+      try {
+        await subscribeFree(offer.id);
+        await refetchSubscription();
+      } catch {
+        /* Error captured by hook state — banner not added here yet. */
+      }
+      return;
+    }
+    onPlanChange?.(offer);
+  };
+
+  // The "Upgrade" CTA on the current-plan card points at the NEXT tier above
+  // the user's current sub. With a current sub we ONLY consider strictly
+  // higher tiers — never the user's current plan or below. startsim-y34.
+  // Without a sub (legacy / unauthenticated preview) we fall back to the
+  // featured paid plan or the first paid plan. Returns null when the user is
+  // already on the top tier OR the product has no paid offer at all (free-
+  // only apps), so the Upgrade CTA simply doesn't render — startsim-ft2.
+  const featuredPaidOffer: ProductOffer | null = (() => {
+    if (!product) return null;
+    if (currentOffer) {
+      const above = product.offers.filter((o) => !o.isFree && o.sortOrder > currentOffer.sortOrder);
+      return above.find((o) => o.isFeatured) ?? above[0] ?? null;
+    }
+    return (
+      product.offers.find((o) => !o.isFree && o.isFeatured) ??
+      product.offers.find((o) => !o.isFree) ??
+      null
+    );
+  })();
 
   const handlePortalClick = async () => {
     try {
@@ -163,37 +344,41 @@ export function SubscriptionManager({
         </div>
       )}
 
-      {subscription ? (
-        <div data-testid="current-plan" className="rounded-2xl border border-gray-200 bg-white shadow-sm p-8">
-          <div className="flex items-center justify-between mb-4">
-            <h2 className="text-xl font-bold text-gray-900">{subscription.offer.name}</h2>
-            <StatusBadge status={subscription.status} trialEnd={subscription.trialEnd} />
-          </div>
-
-          <div className="mb-4">
-            {subscription.offer.isFree ? (
-              <span aria-label="Free">
-                <span aria-hidden="true" className="text-3xl font-extrabold text-gray-900">Free</span>
-              </span>
-            ) : (
-              <span aria-label={`${Math.floor(parseFloat(subscription.offer.unitPrice) || 0)} dollars ${subscription.offer.intervalDisplay}`}>
-                <span aria-hidden="true" className="text-3xl font-extrabold text-gray-900">
-                  ${Math.floor(parseFloat(subscription.offer.unitPrice) || 0)}
-                </span>
-                <span aria-hidden="true" className="text-base text-gray-500 ml-1">
-                  {subscription.offer.intervalDisplay}
-                </span>
-              </span>
-            )}
-          </div>
-
-          {subscription.currentPeriodStart && subscription.currentPeriodEnd && (
-            <p className="text-sm text-gray-500">
-              Billing period: {formatDate(subscription.currentPeriodStart)} to{" "}
-              {formatDate(subscription.currentPeriodEnd)}
-            </p>
+      {usableSubscription ? (
+        <>
+          {/* Non-owner team members get a clear read-only callout. The OWNER
+              gates that follow (Upgrade CTA, portal button, plan-change CTAs)
+              all flip off when viewerIsOwner === false. startsim-wo9. */}
+          {usableSubscription.viewerIsOwner === false && (
+            <div
+              data-testid="non-owner-billing-notice"
+              className="rounded-lg border border-blue-100 bg-blue-50 p-4 text-sm text-blue-900"
+              role="status"
+            >
+              You&apos;re viewing your team&apos;s billing.{" "}
+              {usableSubscription.ownerEmail
+                ? <>The team owner <span className="font-medium">{usableSubscription.ownerEmail}</span> manages plan changes.</>
+                : <>The team owner manages plan changes.</>
+              }
+            </div>
           )}
-        </div>
+          <CurrentPlanCard
+            subscription={usableSubscription}
+            usage={usage}
+            onPortalClick={usableSubscription.viewerIsOwner === false ? undefined : handlePortalClick}
+            upgradeCta={
+              usableSubscription.viewerIsOwner !== false && usableSubscription.offer.isFree && featuredPaidOffer ? (
+                <button
+                  data-testid="upgrade-cta-current-plan"
+                  onClick={() => handleOfferClick(featuredPaidOffer)}
+                  className="inline-flex items-center gap-2 px-5 py-2.5 text-sm font-bold rounded-xl bg-blue-600 text-white hover:bg-blue-700 cursor-pointer transition-colors"
+                >
+                  Upgrade to {featuredPaidOffer.name} →
+                </button>
+              ) : null
+            }
+          />
+        </>
       ) : (
         <div className="text-center py-8">
           <p className="text-lg text-gray-600">No active subscription</p>
@@ -201,56 +386,127 @@ export function SubscriptionManager({
         </div>
       )}
 
-      {availableOffers.length > 0 && (
+      {/* Product loading while sub already rendered: show plan-grid skeletons
+          rather than empty space — startsim-mtv. */}
+      {productLoading && (
+        <div data-testid="available-plans-loading" className="space-y-4">
+          <h3 className="text-lg font-semibold text-gray-900">
+            {subscription ? "Change Plan" : "Available Plans"}
+          </h3>
+          <div className="grid gap-4 sm:grid-cols-2 lg:grid-cols-3">
+            <PlanSkeleton testId="skeleton-plan-card" />
+            <PlanSkeleton testId="skeleton-plan-card" />
+          </div>
+        </div>
+      )}
+
+      {/* Product fetch error doesn't blank the page — startsim-c0r. Sub still
+          renders above; plans section becomes a recoverable inline error. */}
+      {!productLoading && productError && (
+        <div data-testid="error-product" className="rounded-xl border border-red-200 bg-red-50 p-4 flex items-center justify-between gap-3">
+          <p className="text-sm text-red-800">
+            Couldn&apos;t load plans. {productError.message}
+          </p>
+          <button
+            data-testid="retry-product"
+            onClick={() => refetchProduct()}
+            className="shrink-0 text-sm font-semibold px-3 py-1.5 rounded-lg bg-red-600 text-white hover:bg-red-700 cursor-pointer"
+          >
+            Retry
+          </button>
+        </div>
+      )}
+
+      {/* Only render the Change Plan section when there are at least 2 offers
+          to show. Single-tier apps (just Free) skip it entirely — startsim-ft2. */}
+      {!productLoading && !productError && allOffers.length >= 2 && (
         <div data-testid="available-plans" className="space-y-4">
           <h3 className="text-lg font-semibold text-gray-900">
             {subscription ? "Change Plan" : "Available Plans"}
           </h3>
           <div className="grid gap-4 sm:grid-cols-2 lg:grid-cols-3">
-            {availableOffers.map((offer) => (
-              <div
-                key={offer.id}
-                className={`rounded-xl border p-6 ${
-                  offer.isFeatured
-                    ? "border-blue-600 shadow-md"
-                    : "border-gray-200 bg-white shadow-sm"
-                }`}
-              >
-                <h4 className="text-lg font-bold text-gray-900 mb-2">{offer.name}</h4>
-                <div className="mb-3">
-                  {offer.isFree ? (
-                    <span aria-label="Free">
-                      <span aria-hidden="true" className="text-2xl font-extrabold text-gray-900">Free</span>
+            {allOffers.map((offer) => {
+              const direction = directionFor(offer);
+              const isCurrent = direction === "current";
+              const isDowngrade = direction === "downgrade";
+              const ctaLabel = ctaLabelFor(offer, direction);
+
+              // Border: current = solid ring; featured upgrade = blue; else gray.
+              const cardBorder =
+                isCurrent ? "border-2 border-primary-600 ring-2 ring-primary-100 bg-white shadow-md"
+                : offer.isFeatured ? "border border-blue-600 shadow-md bg-white"
+                : "border border-gray-200 bg-white shadow-sm";
+
+              // CTA: current = disabled badge; downgrade = secondary gray;
+              // upgrade = blue (featured) or gray (non-featured).
+              const ctaClass =
+                isCurrent ? "bg-gray-100 text-gray-500 cursor-not-allowed"
+                : isDowngrade ? "bg-white text-gray-700 border border-gray-300 hover:bg-gray-50 cursor-pointer"
+                : offer.isFeatured ? "bg-blue-600 text-white hover:bg-blue-700 cursor-pointer"
+                : "bg-gray-100 text-gray-800 hover:bg-gray-200 cursor-pointer";
+
+              const isViewerNonOwner = subscription?.viewerIsOwner === false;
+
+              return (
+                <div
+                  key={offer.id}
+                  data-testid={`plan-card-${offer.slug}`}
+                  data-direction={direction}
+                  className={`relative rounded-xl p-6 transition-colors ${cardBorder}`}
+                >
+                  {isCurrent && (
+                    <span
+                      data-testid={`current-plan-badge-${offer.slug}`}
+                      className="absolute -top-2.5 right-4 inline-block bg-primary-600 text-white text-xs font-bold uppercase tracking-wide px-2.5 py-0.5 rounded-full"
+                    >
+                      Current Plan
                     </span>
-                  ) : (
-                    <span aria-label={`${Math.floor(parseFloat(offer.unitPrice) || 0)} dollars ${offer.intervalDisplay}`}>
-                      <span aria-hidden="true" className="text-2xl font-extrabold text-gray-900">
-                        ${Math.floor(parseFloat(offer.unitPrice) || 0)}
+                  )}
+                  <h4 className="text-lg font-bold text-gray-900 mb-2">{offer.name}</h4>
+                  <div className="mb-3">
+                    {offer.isFree ? (
+                      <span aria-label="Free">
+                        <span aria-hidden="true" className="text-2xl font-extrabold text-gray-900">Free</span>
                       </span>
-                      <span aria-hidden="true" className="text-sm text-gray-500 ml-1">
-                        {offer.intervalDisplay}
+                    ) : (
+                      <span aria-label={`${Math.floor(parseFloat(offer.unitPrice) || 0)} dollars ${offer.intervalDisplay}`}>
+                        <span aria-hidden="true" className="text-2xl font-extrabold text-gray-900">
+                          ${Math.floor(parseFloat(offer.unitPrice) || 0)}
+                        </span>
+                        <span aria-hidden="true" className="text-sm text-gray-500 ml-1">
+                          {offer.intervalDisplay}
+                        </span>
                       </span>
-                    </span>
-                  )}
+                    )}
+                  </div>
+                  {/* Trial copy is for prospective trialers only — once the
+                      user is on this offer or moving downward, drop the
+                      "14-day free trial" sales pitch. */}
+                  {direction === "upgrade" && <TrialCopy trialDays={offer.trialDays} />}
+                  <PlanFeatureList features={offer.features} />
+                  <button
+                    data-testid={`upgrade-cta-${offer.slug}`}
+                    onClick={() => !isCurrent && !isViewerNonOwner && handleOfferClick(offer)}
+                    disabled={isCurrent || isViewerNonOwner}
+                    aria-disabled={isCurrent || isViewerNonOwner || undefined}
+                    title={isViewerNonOwner ? "Only the team owner can change the plan" : undefined}
+                    className={`w-full py-2.5 px-4 text-sm font-bold rounded-xl transition-colors ${ctaClass} ${isViewerNonOwner ? "opacity-60 cursor-not-allowed" : ""}`}
+                  >
+                    {ctaLabel}
+                  </button>
                 </div>
-                <button
-                  data-testid={`upgrade-cta-${offer.slug}`}
-                  onClick={() => onPlanChange?.(offer)}
-                  className={`w-full py-2.5 px-4 text-sm font-bold rounded-xl cursor-pointer transition-colors ${
-                    offer.isFeatured
-                      ? "bg-blue-600 text-white hover:bg-blue-700"
-                      : "bg-gray-100 text-gray-800 hover:bg-gray-200"
-                  }`}
-                >
-                  {offer.ctaText}
-                </button>
-              </div>
-            ))}
+              );
+            })}
           </div>
         </div>
       )}
 
-      {subscription && subscription.status !== "cancelled" && (
+      {/* Manage-billing only when there's a real provider sub AND the viewer
+          is the team owner (non-owners get a read-only view — startsim-wo9).
+          Free-tier users (provider='none') have no Stripe customer, so the
+          portal call would 404 — they get the Upgrade CTA on the current-plan
+          card instead. startsim-b1z. */}
+      {usableSubscription && usableSubscription.status !== "cancelled" && !usableSubscription.offer.isFree && usableSubscription.viewerIsOwner !== false && (
         <div className="pt-4 border-t border-gray-100">
           <button
             data-testid="portal-button"

package/src/components/index.ts

@@ -12,3 +12,7 @@ export { SubscriptionManager } from "./SubscriptionManager";
 export type { SubscriptionManagerProps } from "./SubscriptionManager";
 export { PlanGate } from "./PlanGate";
 export type { PlanGateProps } from "./PlanGate";
+export { CurrentPlanCard } from "./CurrentPlanCard";
+export type { CurrentPlanCardProps } from "./CurrentPlanCard";
+export { LimitNudge } from "./LimitNudge";
+export type { LimitNudgeProps } from "./LimitNudge";

package/src/hooks/index.ts

@@ -5,3 +5,4 @@ export { useCheckout } from "./useCheckout";
 export { usePortal } from "./usePortal";
 export { useSubscription } from "./useSubscription";
 export { useSuccessSync } from "./useSuccessSync";
+export { useUsage, notifyUsageChanged, USAGE_CHANGED_EVENT } from "./useUsage";

package/src/hooks/useUsage.ts

@@ -0,0 +1,94 @@
+/**
+ * useUsage — Fetch per-product usage (startsim-h14).
+ *
+ * Reads from GET /api/v1/billing/usage/<slug>/ via the BillingProvider's
+ * configured fetcher + apiBaseUrl. The backend returns an empty object
+ * for any failure mode (no adapter, no subscription, adapter exception),
+ * so consumers must treat {} as "hide usage" rather than as an error.
+ *
+ * Re-fetches automatically:
+ *   - on mount / when slug changes
+ *   - when the tab regains visibility (`visibilitychange` event)
+ *   - when ANY code in the app dispatches a `billing:usage-changed`
+ *     CustomEvent on `window` — apps signal mutations that altered
+ *     usage (env create, env delete, secret create…) by calling
+ *     `notifyUsageChanged()` (exported below). This keeps usage live
+ *     without coupling useUsage to React Query or every app's data layer.
+ *
+ * Usage:
+ *   const { usage, loading, error, refetch } = useUsage("vault");
+ *   const envs = usage?.environments;  // { used, limit } | undefined
+ */
+
+import { useCallback, useEffect, useState } from "react";
+import type { UsageMap } from "../types";
+import { useBillingContext } from "./BillingProvider";
+
+interface UseUsageResult {
+  usage: UsageMap;
+  loading: boolean;
+  error: Error | null;
+  refetch: () => void;
+}
+
+/** Event name apps fire (and useUsage listens for) when something happened
+ * that could change usage counts — env created, secret deleted, etc. */
+export const USAGE_CHANGED_EVENT = "billing:usage-changed";
+
+/** Helper apps use to nudge every mounted useUsage hook to refetch.
+ * Safe to call from anywhere (no-ops outside the browser). */
+export function notifyUsageChanged(slug?: string): void {
+  if (typeof window === "undefined") return;
+  window.dispatchEvent(new CustomEvent(USAGE_CHANGED_EVENT, { detail: { slug } }));
+}
+
+export function useUsage(slug: string): UseUsageResult {
+  const { client } = useBillingContext();
+  const [usage, setUsage] = useState<UsageMap>({});
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<Error | null>(null);
+
+  const fetchUsage = useCallback(async () => {
+    if (!slug) {
+      setUsage({});
+      setLoading(false);
+      return;
+    }
+    setLoading(true);
+    setError(null);
+    try {
+      const data = await client.getUsage(slug);
+      setUsage(data ?? {});
+    } catch (e) {
+      // Usage MUST NOT break the page — record the error but still render {}.
+      setError(e instanceof Error ? e : new Error(String(e)));
+      setUsage({});
+    } finally {
+      setLoading(false);
+    }
+  }, [client, slug]);
+
+  useEffect(() => {
+    fetchUsage();
+  }, [fetchUsage]);
+
+  // Stay live: refetch on tab focus + on app-dispatched change events.
+  useEffect(() => {
+    if (typeof window === "undefined") return;
+    const onVis = () => {
+      if (document.visibilityState === "visible") fetchUsage();
+    };
+    const onChange = (ev: Event) => {
+      const target = (ev as CustomEvent<{ slug?: string }>).detail?.slug;
+      if (!target || target === slug) fetchUsage();
+    };
+    document.addEventListener("visibilitychange", onVis);
+    window.addEventListener(USAGE_CHANGED_EVENT, onChange);
+    return () => {
+      document.removeEventListener("visibilitychange", onVis);
+      window.removeEventListener(USAGE_CHANGED_EVENT, onChange);
+    };
+  }, [fetchUsage, slug]);
+
+  return { usage, loading, error, refetch: fetchUsage };
+}

package/src/index.ts

@@ -18,6 +18,9 @@ export {
   usePortal,
   useSubscription,
   useSuccessSync,
+  useUsage,
+  notifyUsageChanged,
+  USAGE_CHANGED_EVENT,
 } from "./hooks";
 export type { BillingProviderProps } from "./hooks";
 
@@ -33,10 +36,11 @@ export type {
   PaymentMethod,
   PortalResult,
   SubscriptionInfo,
+  UsageMap,
 } from "./types";
 
 // Components
-export { PricingPage, PricingSection, PricingDetailPage, UpgradeModal, ManageSubscription, SubscriptionManager, PlanGate } from "./components";
+export { PricingPage, PricingSection, PricingDetailPage, UpgradeModal, ManageSubscription, SubscriptionManager, PlanGate, CurrentPlanCard, LimitNudge } from "./components";
 export type {
   PricingPageProps,
   PricingSectionProps,
@@ -45,6 +49,8 @@ export type {
   ManageSubscriptionProps,
   SubscriptionManagerProps,
   PlanGateProps,
+  CurrentPlanCardProps,
+  LimitNudgeProps,
 } from "./components";
 
 // API client (for advanced usage)