@growth-operations/ui-shared 1.0.0

package/README.md

@@ -0,0 +1,209 @@
+# @growth-operations/ui-shared
+
+Shared HubSpot UI-extension components for Growth Operations apps. One component
+library serves all three app archetypes — `big_app` (toast, sparkfly), `ats`,
+and `credit` — by rendering a single payload contract and branching on
+`entitlement.mode`.
+
+The components are **presentational**: every app-specific decision (onboarding
+steps, nudges, health verdict, credit thresholds) is computed server-side and
+delivered in the payload. The package never hardcodes app logic, an `app_key`,
+or an app name.
+
+## The /v1/home contract
+
+Every app exposes `GET /api/v1/home?portalId={id}` (verify_hubspot) returning the
+single payload these components render. The authoritative shape lives in
+[CONTRACT.md](./CONTRACT.md) — read it first.
+
+The one field every consumer gates on is the discriminated `entitlement` union:
+
+```jsonc
+// Arm A — big_app + ATS (maps onto common.entitlements.is_entitled)
+{ "mode": "trial_subscription", "entitled": true, "status": "trialing", ... }
+
+// Arm B — credit apps (net-new balance model)
+{ "mode": "credits", "entitled": true, "granted": 100, "used": 37, "remaining": 63, ... }
+```
+
+`entitlement.entitled` is the only gate the UI/features read. Optional blocks
+(`health`, `onboarding`, `nudges`, `sync_pulse`, `credit_meter`, `pipeline`,
+`activation`) may be absent — each component renders nothing when its block is
+missing.
+
+## Consuming the package
+
+Add the dependency (pin the exact version — see Versioning):
+
+```jsonc
+// project/app/app.functions/package.json (or the extension's package.json)
+{ "dependencies": { "@growth-operations/ui-shared": "1.0.0" } }
+```
+
+Install into the HubSpot project so the bundler picks it up:
+
+```bash
+hs project install-deps
+```
+
+Render Home with the single opinionated component:
+
+```jsx
+import { AppHome } from "@growth-operations/ui-shared";
+
+function Home({ context }) {
+  const [state, setState] = useState(null); // GET /api/v1/home
+  return (
+    <AppHome
+      state={state}
+      appName="Sparkfly Sync"
+      onNavigate={(route) => actions.openIframeModal(/* or your router */)}
+    />
+  );
+}
+```
+
+`AppHome` composes the lifecycle: loading spinner → `InstallProgress` (until
+activation completes) → the activated cockpit (`HealthHero` + onboarding +
+the archetype tile + nudges).
+
+Render the shared Billing tab (pass the Stripe `app_key` as a prop — never
+hardcoded in the package):
+
+```jsx
+import { BillingTab } from "@growth-operations/ui-shared";
+
+<BillingTab context={context} state={state} appKey="hubspot_sparkfly" />;
+```
+
+`BillingTab` branches on `entitlement.mode`: `trial_subscription` shows the
+Stripe Customer Portal link + color-coded status panel; `credits` shows the
+`CreditMeter` + a "pick a plan / buy credits" CTA.
+
+### Individual exports
+
+`AppHome`, `InstallProgress`, `HealthHero`, `OnboardingChecklist`, `SyncPulse`,
+`FeatureNudges`, `CreditMeter`, `BillingTab`, plus the lib helpers `fmtDate`,
+`daysUntil`, `humanizeStatus`, `statusVariant`, and `useStrictModeEffect`.
+
+## SDK
+
+`src/sdk/` is the Growth Ops HubSpot app SDK: the token + API utility layer that
+every token-using app used to reimplement. Use it instead of hand-rolling
+`hubspot.fetch` calls in each app. Everything is re-exported from the package
+root, so `import { callAppApi } from "@growth-operations/ui-shared"` works.
+
+### `hubspot.fetch` rules (why this SDK exists)
+
+These two rules have repeatedly cost real debugging time; the SDK enforces both
+so callers never have to remember them:
+
+1. **Body is a plain object — never `JSON.stringify` it.** `hubspot.fetch`
+   serializes the body for you; a pre-stringified body is rejected/mangled. Pass
+   `{ foo: "bar" }`, not `'{"foo":"bar"}'`.
+2. **No custom headers.** The platform injects `Authorization` for calls to your
+   own backend, so `callAppApi` sends no headers at all. For direct HubSpot API
+   calls, `Authorization: Bearer <token>` is the *one* permitted client header —
+   `callHubSpotApi` sends only that.
+
+### App backend — `callAppApi`
+
+Calls your app's own Cloud Run backend at `context.variables.BASE_URL`:
+
+```js
+import { callAppApi, AppApiError } from "@growth-operations/ui-shared";
+
+// body is a plain object (NOT JSON.stringify'd)
+const result = await callAppApi(context, "/api/v1/settings", "PUT", { foo: 1 });
+// throws AppApiError(message, statusCode, responseText) on non-2xx;
+// FastAPI {"detail": "..."} bodies are unwrapped into the message.
+```
+
+Built on top of `callAppApi`:
+
+- `getSettings(context, { force })` / `updateSettings(context, body)` — module-cached
+  settings client (`force: true` bypasses the cache, e.g. when polling). Use
+  `makeSettingsApi({ path })` for a client with its own cache or a different path.
+- `getAlerts(context, params)` / `dismissAlert(context, alertId)` — the generic
+  `/api/v1/alerts` surface (`offset`, `limit`, `orderBy`, `orderDirection`,
+  `filterField`, `filterValue`).
+
+### HubSpot public API — `callHubSpotApi`
+
+Direct calls to `api.hubapi.com` with a short-lived OAuth token:
+
+```js
+import { callHubSpotApi, buildHubSpotUrl, HubSpotApiError } from "@growth-operations/ui-shared";
+
+const url = buildHubSpotUrl("crm/v3/properties/contacts");
+const data = await callHubSpotApi(url, token); // GET
+// POST/PATCH bodies are plain objects too:
+await callHubSpotApi(url, token, "POST", { query: "x", count: 100 });
+```
+
+Resource fetchers built on it (all take `(context, token, ...)`):
+`getObjectProperties(context, token, objectType)` (picker-shaped, filtered),
+`getProperties` (raw), `updateProperties(context, token, properties)`,
+`getForms`, `getLists(context, token, query)`,
+`getPipelines` / `getPipelineStages` / `computeStageChanges`.
+
+### Token lifecycle — `getShortLivedToken` / `TokenProvider`
+
+`getShortLivedToken(context)` fetches a short-lived HubSpot OAuth token from the
+app backend (`GET /api/v1/tokens/short-lived?portalId=...`) and returns the token
+string. For React trees, wrap with `TokenProvider` and read the token via
+`useToken()`, which caches by `expires_at` at module level (survives remounts, no
+re-renders):
+
+```jsx
+import { TokenProvider, useToken, callHubSpotApi, buildHubSpotUrl } from "@growth-operations/ui-shared";
+
+function Root({ context }) {
+  return (
+    <TokenProvider context={context}>
+      <Mapper />
+    </TokenProvider>
+  );
+}
+
+function Mapper() {
+  const { ensureValidToken, invalidateToken } = useToken();
+  async function load() {
+    const token = await ensureValidToken(); // fetches/refreshes as needed
+    return callHubSpotApi(buildHubSpotUrl("marketing/v3/forms"), token);
+  }
+  // ...
+}
+```
+
+### CRM-card encryption
+
+`encrypt(data, context)` / `decrypt(ciphertext, context)` plus the primitives
+`strToBase64`, `base64ToStr`, `getKeyFromContext`. AES-GCM keyed to the current
+CRM record (`context.extension.objectTypeId` + `context.crm.objectId`), so usable
+only in a CRM-card context.
+
+### SDK exports
+
+`callAppApi`, `AppApiError`, `getSettings`, `updateSettings`, `makeSettingsApi`,
+`getAlerts`, `dismissAlert`, `callHubSpotApi`, `buildHubSpotUrl`,
+`HubSpotApiError`, `getObjectProperties`, `getProperties`, `updateProperties`,
+`getForms`, `getLists`, `getPipelines`, `getPipelineStages`,
+`computeStageChanges`, `getShortLivedToken`, `isTokenExpired`, `TokenProvider`,
+`useToken`, `TokenContext`, `encrypt`, `decrypt`, `strToBase64`, `base64ToStr`,
+`getKeyFromContext`.
+
+## Peer dependencies
+
+`react` and `@hubspot/ui-extensions` are **peer dependencies** — they are
+provided by the consuming HubSpot app, not bundled here. The package imports
+from them but never ships its own copy, so a single React/UI-extensions runtime
+is shared.
+
+## Versioning
+
+Pin **exact** versions in consuming apps (`"1.0.0"`, not `"^1.0.0"`). These
+components render a shared contract across multiple apps; an unexpected minor
+bump should be an explicit, reviewed change, not an automatic upgrade. Publishing
+is automated: pushing a `v*` tag runs `.github/workflows/publish.yml`, which
+`npm publish --access public`.

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@growth-operations/ui-shared",
+  "version": "1.0.0",
+  "description": "Shared HubSpot UI-extension modules (Home, Billing) for Growth Operations apps.",
+  "license": "MIT",
+  "private": false,
+  "main": "src/index.js",
+  "module": "src/index.js",
+  "files": [
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/growth-operations/ui-shared.git"
+  },
+  "peerDependencies": {
+    "@hubspot/ui-extensions": ">=0.13.0",
+    "react": ">=18.0.0"
+  }
+}

package/src/billing/BillingTab.jsx

@@ -0,0 +1,246 @@
+import React, { useState } from "react";
+import {
+  hubspot,
+  Flex,
+  Heading,
+  Text,
+  Tile,
+  Link,
+  LoadingSpinner,
+  Alert,
+} from "@hubspot/ui-extensions";
+import { useStrictModeEffect } from "../lib/useStrictModeEffect";
+import { fmtDate, daysUntil } from "../lib/format";
+import { CreditMeter } from "../home/CreditMeter";
+
+// The shared Billing tab for all Growth Operations apps. Branches on the
+// entitlement union (CONTRACT.md):
+//   trial_subscription -> the toast/sparkfly-proven Stripe Customer Portal
+//                         pattern: pre-create a portal session on mount, a
+//                         primary "Manage billing in Stripe →" link at the top,
+//                         and a color-coded status panel (per Andrew's feedback;
+//                         no invoice LineChart for flat-rate plans).
+//   credits            -> the CreditMeter + a "Pick a plan" / "Buy credits" CTA.
+//
+// Props:
+//   context — the UI-extension serverless context (context.portal.id).
+//   state   — the /v1/home payload (entitlement union, billing_base_url, app_id).
+//   appKey  — the Stripe/billing app_key for THIS app (e.g. "hubspot_toast").
+//             Always a prop — never hardcoded in the shared package.
+
+// Color-coded account-status panel (per Andrew's billing feedback): trial =>
+// yellow + days left + end date; active => green + next renewal; past_due =>
+// red + warning. Replaces the low-value flat-rate invoice chart.
+function StatusPanel({ entitlement }) {
+  if (!entitlement) return null;
+  const {
+    status,
+    current_period_end,
+    trial_ends_at,
+    sandbox_trial_expires_at,
+    cancel_at_period_end,
+  } = entitlement;
+
+  if (status === "trialing") {
+    const trialEnd = trial_ends_at || current_period_end || sandbox_trial_expires_at;
+    const left = daysUntil(trialEnd);
+    const leftLabel =
+      left == null
+        ? "Free trial active"
+        : left <= 0
+        ? "Your free trial ends today"
+        : `${left} day${left === 1 ? "" : "s"} left in your free trial`;
+    return (
+      <Alert title={leftLabel} variant="warning">
+        <Text>
+          Trial ends {fmtDate(trialEnd)}. Add a plan in Stripe before then to
+          keep syncing.
+        </Text>
+      </Alert>
+    );
+  }
+
+  if (status === "active") {
+    return (
+      <Alert title="You're all set" variant="success">
+        <Flex direction="column" gap="extra-small">
+          <Text>Your subscription is active.</Text>
+          <Text>Next renewal: {fmtDate(current_period_end)}</Text>
+          {cancel_at_period_end && (
+            <Text format={{ fontStyle: "italic" }}>
+              Cancels at the end of the current period.
+            </Text>
+          )}
+        </Flex>
+      </Alert>
+    );
+  }
+
+  if (status === "past_due") {
+    return (
+      <Alert title="Your subscription is past due" variant="error">
+        <Text>
+          We couldn't process your latest payment. Update your payment method in
+          Stripe to avoid losing access.
+        </Text>
+      </Alert>
+    );
+  }
+
+  if (status === "pending_purchase") {
+    return (
+      <Alert title="Your free trial has ended" variant="warning">
+        <Text>Choose a plan in Stripe to resume syncing your data.</Text>
+      </Alert>
+    );
+  }
+
+  return (
+    <Tile>
+      <Text format={{ fontWeight: "bold" }}>Status: {status ?? "Unknown"}</Text>
+    </Tile>
+  );
+}
+
+// Pre-creates a Stripe billing/checkout portal session on mount and returns
+// { portalUrl, loading, error }. Shared by both arms — the credits arm reuses
+// the same portal endpoint for v1 (see note in CreditsBilling below).
+function usePortalSession({ context, state, appKey }) {
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState(null);
+  const [portalUrl, setPortalUrl] = useState(null);
+
+  // Pre-create on mount so the link is one real click (Stripe can't be iframed;
+  // UI Extensions have no open-URL action — only Link, whose href must exist
+  // before render).
+  useStrictModeEffect(
+    async ({ mounted }) => {
+      try {
+        const base = state?.billing_base_url;
+        if (!base) throw new Error("Billing service not configured");
+        if (!appKey) throw new Error("Missing appKey for billing portal");
+        const portalId = context?.portal?.id;
+
+        // Return to THIS app's Billing page after Stripe (named app-page deep
+        // link /app/{portalId}/{appId}/{pagePath}); fall back to HubSpot home.
+        const returnUrl = state?.app_id
+          ? `https://app.hubspot.com/app/${portalId}/${state.app_id}/billing`
+          : "https://app.hubspot.com/";
+
+        // hubspot.fetch: body must be a plain OBJECT (HubSpot serializes it),
+        // NOT a JSON string, and only Authorization survives as a header —
+        // do not set Content-Type or any other header.
+        const res = await hubspot.fetch(`${base}/v1/billing/portal`, {
+          method: "POST",
+          body: {
+            app_key: appKey,
+            portal_id: String(portalId),
+            return_url: returnUrl,
+          },
+        });
+        if (!res.ok) {
+          const text = await res.text();
+          throw new Error(`Billing portal request failed (${res.status}): ${text}`);
+        }
+        const { url } = await res.json();
+        if (!url) throw new Error("No billing portal URL returned");
+        if (mounted.current) setPortalUrl(url);
+      } catch (perr) {
+        if (mounted.current) setError(String(perr));
+      } finally {
+        if (mounted.current) setLoading(false);
+      }
+    },
+    [context, appKey, state?.billing_base_url, state?.app_id]
+  );
+
+  return { portalUrl, loading, error };
+}
+
+function TrialSubscriptionBilling({ context, state, appKey }) {
+  const { portalUrl, loading, error } = usePortalSession({ context, state, appKey });
+
+  return (
+    <Flex direction="column" gap="medium">
+      {/* PRIMARY CTA at the very top, large and obvious (per billing feedback). */}
+      {portalUrl ? (
+        <Link href={{ url: portalUrl, external: true }} variant="primary">
+          <Text format={{ fontWeight: "bold", fontSize: "lg" }}>
+            Manage billing in Stripe →
+          </Text>
+        </Link>
+      ) : loading ? (
+        <LoadingSpinner showLabel label="Preparing billing…" />
+      ) : (
+        error && (
+          <Alert title="Couldn't open billing" variant="danger">
+            <Text>{error}</Text>
+          </Alert>
+        )
+      )}
+
+      <StatusPanel entitlement={state?.entitlement} />
+
+      <Text format={{ fontStyle: "italic" }}>
+        Billing is managed in Stripe across all Growth Operations apps. Use the
+        link above to update your plan, payment method, or view invoices.
+      </Text>
+    </Flex>
+  );
+}
+
+function CreditsBilling({ context, state, appKey }) {
+  // NOTE: the credit-pack / paid-allowance checkout backend is net-new and
+  // pending. For v1 the "Pick a plan" / "Buy credits" CTA reuses the same
+  // Stripe portal session pattern (routes to the portal); swap the endpoint to
+  // the credit checkout once that backend lands.
+  const { portalUrl, loading, error } = usePortalSession({ context, state, appKey });
+
+  return (
+    <Flex direction="column" gap="medium">
+      <CreditMeter
+        entitlement={state?.entitlement}
+        creditMeter={state?.credit_meter}
+      />
+
+      {/* PRIMARY CTA at top: pick a plan / buy credits. */}
+      {portalUrl ? (
+        <Link href={{ url: portalUrl, external: true }} variant="primary">
+          <Text format={{ fontWeight: "bold", fontSize: "lg" }}>
+            Pick a plan / Buy credits →
+          </Text>
+        </Link>
+      ) : loading ? (
+        <LoadingSpinner showLabel label="Preparing checkout…" />
+      ) : (
+        error && (
+          <Alert title="Couldn't open checkout" variant="danger">
+            <Text>{error}</Text>
+          </Alert>
+        )
+      )}
+
+      <Text format={{ fontStyle: "italic" }}>
+        Top up or move to a paid monthly allowance to keep going. Billing is
+        managed in Stripe across all Growth Operations apps.
+      </Text>
+    </Flex>
+  );
+}
+
+export function BillingTab({ context, state, appKey }) {
+  const mode = state?.entitlement?.mode;
+
+  return (
+    <Flex direction="column" gap="medium">
+      <Heading>Billing</Heading>
+      {mode === "credits" ? (
+        <CreditsBilling context={context} state={state} appKey={appKey} />
+      ) : (
+        <TrialSubscriptionBilling context={context} state={state} appKey={appKey} />
+      )}
+    </Flex>
+  );
+}
+
+export default BillingTab;

package/src/home/AppHome.jsx

@@ -0,0 +1,115 @@
+import React from "react";
+import { Flex, Tile, Text, LoadingSpinner } from "@hubspot/ui-extensions";
+import { InstallProgress } from "./InstallProgress";
+import { HealthHero } from "./HealthHero";
+import { OnboardingChecklist } from "./OnboardingChecklist";
+import { SyncPulse } from "./SyncPulse";
+import { CreditMeter } from "./CreditMeter";
+import { FeatureNudges } from "./FeatureNudges";
+
+// Minimal inline ATS tile (the `pipeline` block). Kept tiny here rather than a
+// separate file — it's the simplest of the three archetype tiles. Renders
+// nothing when there's no pipeline block.
+function PipelineTile({ pipeline }) {
+  if (!pipeline) return null;
+  const byStage = pipeline.applications_by_stage ?? {};
+  return (
+    <Tile>
+      <Flex direction="column" gap="small">
+        <Text format={{ fontWeight: "bold" }}>Pipeline</Text>
+        <Flex direction="row" gap="large">
+          <Flex direction="column" gap="extra-small">
+            <Text format={{ fontWeight: "demibold" }}>Open jobs</Text>
+            <Text>{pipeline.open_jobs ?? 0}</Text>
+          </Flex>
+          <Flex direction="column" gap="extra-small">
+            <Text format={{ fontWeight: "demibold" }}>Outstanding scorecards</Text>
+            <Text>{pipeline.outstanding_scorecards ?? 0}</Text>
+          </Flex>
+        </Flex>
+        {Object.keys(byStage).length > 0 && (
+          <Flex direction="row" gap="medium">
+            {Object.entries(byStage).map(([stage, count]) => (
+              <Flex key={stage} direction="column" gap="extra-small">
+                <Text format={{ fontWeight: "demibold" }}>{stage}</Text>
+                <Text>{count}</Text>
+              </Flex>
+            ))}
+          </Flex>
+        )}
+      </Flex>
+    </Tile>
+  );
+}
+
+// Picks the single archetype activity tile (CONTRACT: at most ONE present).
+// credit_meter / credits mode -> CreditMeter; sync_pulse -> SyncPulse;
+// pipeline -> PipelineTile. Renders nothing when none apply.
+function ArchetypeTile({ state }) {
+  if (state.credit_meter || state.entitlement?.mode === "credits") {
+    return (
+      <CreditMeter
+        entitlement={state.entitlement}
+        creditMeter={state.credit_meter}
+      />
+    );
+  }
+  if (state.sync_pulse) return <SyncPulse syncPulse={state.sync_pulse} />;
+  if (state.pipeline) return <PipelineTile pipeline={state.pipeline} />;
+  return null;
+}
+
+// The opinionated one-line Home integration. An app's Pages.jsx Home route can
+// render just <AppHome state={homePayload} onNavigate={fn} appName={...} />.
+//
+// Lifecycle composition:
+//   no state            -> LoadingSpinner (still fetching /v1/home)
+//   activation pending  -> <InstallProgress> (install isn't finished yet)
+//   activated cockpit   -> <HealthHero>
+//                          + <OnboardingChecklist> (only if not complete)
+//                          + the archetype activity tile (sync/credit/pipeline)
+//                          + <FeatureNudges>
+//
+// Props:
+//   state      — the /v1/home payload (null while loading).
+//   onNavigate — (route) => void, threaded to onboarding + nudges for in-app
+//                PageLink navigation (the host owns the router).
+//   appName    — display name override; defaults to state.app.name.
+//   onRetry    — optional, passed to InstallProgress for the failed state.
+export function AppHome({ state, onNavigate, appName, onRetry }) {
+  if (!state) {
+    return <LoadingSpinner showLabel label="Loading…" />;
+  }
+
+  const activation = state.activation;
+  const activationComplete =
+    !activation || activation.complete === true || activation.status === "completed";
+
+  // Install isn't finished (running / failed / completed-with-warnings) — show
+  // the install experience instead of the cockpit.
+  if (!activationComplete) {
+    return <InstallProgress state={state} onRetry={onRetry} />;
+  }
+
+  const onboardingComplete = state.onboarding?.complete === true;
+
+  return (
+    <Flex direction="column" gap="medium">
+      {/* A completed-with-warnings activation still surfaces its warnings
+          callout above the cockpit; InstallProgress renders null when clean. */}
+      <InstallProgress state={state} onRetry={onRetry} />
+
+      <HealthHero appName={appName} state={state} />
+
+      {state.onboarding && !onboardingComplete && (
+        <OnboardingChecklist onboarding={state.onboarding} onNavigate={onNavigate} />
+      )}
+
+      <ArchetypeTile state={state} />
+
+      <FeatureNudges nudges={state.nudges} onNavigate={onNavigate} />
+    </Flex>
+  );
+}
+
+export default AppHome;

package/src/home/CreditMeter.jsx

@@ -0,0 +1,85 @@
+import React from "react";
+import { Flex, Tile, Text, ProgressBar, StatusTag, Alert } from "@hubspot/ui-extensions";
+import { daysUntil } from "../lib/format";
+
+// THE credit-archetype activity tile + hero signal. For credit apps, "credits
+// remaining" is the primary glanceable signal the way "trial days left" is for
+// big apps. Driven by the entitlement union (mode === "credits") and/or the
+// `credit_meter` block (CONTRACT.md). Renders nothing when there is no credit
+// data to show.
+//
+// Numbers resolve from the credit_meter block first (richer: carries `recent`),
+// then fall back to the entitlement arm. Thresholds (low_threshold, depleted,
+// grant_expires_at) only live on the entitlement arm.
+//
+// Props:
+//   entitlement  — the /v1/home entitlement union (uses the credits arm).
+//   creditMeter  — the /v1/home credit_meter block (optional).
+export function CreditMeter({ entitlement, creditMeter }) {
+  const ent = entitlement?.mode === "credits" ? entitlement : null;
+  const meter = creditMeter ?? null;
+  if (!ent && !meter) return null;
+
+  const granted = meter?.granted ?? ent?.granted ?? 0;
+  const used = meter?.used ?? ent?.used ?? 0;
+  const remaining = meter?.remaining ?? ent?.remaining ?? Math.max(granted - used, 0);
+
+  const lowThreshold = ent?.low_threshold ?? 0;
+  const depleted = ent?.depleted === true || remaining <= 0;
+  const low = !depleted && remaining <= lowThreshold;
+
+  // healthy green / low yellow / depleted red.
+  const variant = depleted ? "error" : low ? "warning" : "success";
+  const tagVariant = depleted ? "danger" : low ? "warning" : "success";
+  const tagLabel = depleted ? "Depleted" : low ? "Running low" : "Healthy";
+
+  const grantDaysLeft = ent?.grant_expires_at ? daysUntil(ent.grant_expires_at) : null;
+
+  return (
+    <Tile>
+      <Flex direction="column" gap="small">
+        <Flex direction="row" gap="small" align="center">
+          <Text format={{ fontWeight: "bold" }}>Credits</Text>
+          <StatusTag variant={tagVariant}>{tagLabel}</StatusTag>
+        </Flex>
+
+        {/* PRIMARY signal — large and obvious. */}
+        <Text format={{ fontWeight: "bold", fontSize: "lg" }}>
+          {remaining} of {granted} credits left
+        </Text>
+
+        <ProgressBar
+          title={`${used} used`}
+          value={used}
+          maxValue={granted > 0 ? granted : 1}
+          showPercentage={true}
+        />
+
+        {/* Free-grant countdown: "100 free credits — N days left". */}
+        {ent?.grant_expires_at && grantDaysLeft != null && (
+          <Text format={{ fontStyle: "italic" }}>
+            {granted} free credits —{" "}
+            {grantDaysLeft <= 0
+              ? "grant expired"
+              : `${grantDaysLeft} day${grantDaysLeft === 1 ? "" : "s"} left`}
+          </Text>
+        )}
+
+        {(depleted || low) && (
+          <Alert
+            title={depleted ? "You're out of credits" : "Running low on credits"}
+            variant={variant}
+          >
+            <Text>
+              {depleted
+                ? "Pick a plan or buy more credits to keep going."
+                : "You're getting close to your limit — pick a plan to top up."}
+            </Text>
+          </Alert>
+        )}
+      </Flex>
+    </Tile>
+  );
+}
+
+export default CreditMeter;