@growth-operations/ui-shared 1.16.0 → 1.17.1

package/README.md

@@ -127,6 +127,9 @@ Built on top of `callAppApi`:
 - `getAlerts(context, params)` / `dismissAlert(context, alertId)` — the generic
   `/api/v1/alerts` surface (`offset`, `limit`, `orderBy`, `orderDirection`,
   `filterField`, `filterValue`).
+- `getTopUps(context, { appKey, portalId })` / `setBillingLimit(context, { appKey, portalId, limitCents })` —
+  the base service's top-up billing routes (`/v1/hubspot/app_pages/{app}/billing/top-ups`
+  and `/billing/limit`; see CONTRACT.md).
 
 ### HubSpot public API — `callHubSpotApi`
 
@@ -186,7 +189,7 @@ only in a CRM-card context.
 ### SDK exports
 
 `callAppApi`, `AppApiError`, `getSettings`, `updateSettings`, `makeSettingsApi`,
-`getAlerts`, `dismissAlert`, `callHubSpotApi`, `buildHubSpotUrl`,
+`getAlerts`, `dismissAlert`, `getTopUps`, `setBillingLimit`, `callHubSpotApi`, `buildHubSpotUrl`,
 `HubSpotApiError`, `getObjectProperties`, `getProperties`, `updateProperties`,
 `getForms`, `getLists`, `getPipelines`, `getPipelineStages`,
 `computeStageChanges`, `getShortLivedToken`, `isTokenExpired`, `TokenProvider`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@growth-operations/ui-shared",
-  "version": "1.16.0",
+  "version": "1.17.1",
   "description": "Shared HubSpot UI-extension modules (Home, Billing) for Growth Operations apps.",
   "license": "MIT",
   "private": false,
@@ -12,6 +12,9 @@
   "publishConfig": {
     "access": "public"
   },
+  "scripts": {
+    "test": "vitest run"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/growth-operations/ui-shared.git"
@@ -19,5 +22,9 @@
   "peerDependencies": {
     "@hubspot/ui-extensions": ">=0.13.0",
     "react": ">=18.0.0"
+  },
+  "devDependencies": {
+    "react": "^18.3.1",
+    "vitest": "^5.0.3"
   }
 }

package/src/billing/BillingBanner.jsx

@@ -1,24 +1,30 @@
 import React from "react";
 import { Flex, Text, Alert, Button } from "@hubspot/ui-extensions";
+import { resolveBillingBanner } from "../lib/creditDisplay";
 
 // Shared app-wide billing banner for the credit archetype (CreditState.
 // to_entitlement's credits arm). Meant to sit in the app's layout/shell
 // (rendered above every route), NOT inside the Billing tab itself — it's the
 // "surface this everywhere, not just on the Billing page" nudge.
 //
-// A paid plan is never blocked or "running low" the way the free tier is —
-// exceeding the included bucket is overage, not an emergency (see
-// common.entitlements.credits.to_entitlement's `over_included` field). Only
-// the free tier gets the blocking/urgent banners; a paid account in overage
-// gets a calm informational one instead.
+// Driven by the entitlement arm's `threshold_state` (the top-up/"bank"
+// billing model):
+//   top_up_pending -> calm info ("Adding credits automatically…"), no CTA
+//   top_up_failed  -> error, "Update payment method" CTA out to the Stripe
+//                     billing-portal entry point (/v1/billing/portal/start)
+//   limit_reached  -> warning, "Raise your billing limit" CTA into the
+//                     Billing tab's limit control
+//   depleted       -> error, BLOCKING wording — on the topup model a PAID
+//                     plan blocks at true zero (pool + bank empty, no
+//                     successful top-up): actions are paused until the next
+//                     billing period or a successful top-up.
 //
-// Originally copy-pasted per app (a local `billingBannerFor` in each
-// Pages.jsx) — moved here after the SAME bug (independently re-deriving
-// urgency from raw `remaining`, no plan-awareness) had to be hand-fixed in
-// 3 places (confirmed live 2026-09-02, file-attachment-manager: a paid
-// account correctly kept working while this banner still showed the
-// blocking "out of credits" copy). Consume this instead of re-implementing
-// it — the next app in the wave should need zero new banner code.
+// Legacy metered accounts are unchanged: they only ever see threshold_state
+// "healthy"/"depleted" with over_included doing the talking — overage is
+// "paying overage, not blocked" (the 2026-09-02 incident: a paid account
+// correctly kept working while a banner showed blocking "out of credits"
+// copy). The branch logic lives in ../lib/creditDisplay (unit-tested) —
+// consume this instead of re-implementing it.
 //
 // Props:
 //   state       — the /v1/home payload (entitlement union). Renders nothing
@@ -26,60 +32,60 @@ import { Flex, Text, Alert, Button } from "@hubspot/ui-extensions";
 //   actionLabel — short gerund phrase for the depleted message, e.g.
 //                 "attaching and updating files" / "completing, reassigning,
 //                 and deleting tasks". Falls back to "going" if omitted.
-//   actionsNoun — short noun phrase for the running-low message, e.g.
-//                 "file actions" / "task actions". Falls back to "actions".
+//   actionsNoun — short noun phrase for the running-low / paused messages,
+//                 e.g. "file actions" / "task actions". Falls back to
+//                 "actions".
 //   onNavigate  — in-app PageLink-equivalent callback (the host owns the
 //                 router — see ui-shared's OnboardingChecklist for the same
-//                 pattern). Renders a "Go to Billing" button when provided;
-//                 omit it to render the banner with no button.
-export function BillingBanner({ state, actionLabel, actionsNoun, onNavigate }) {
-  const ent = state?.entitlement;
-  if (!ent || ent.mode !== "credits" || ent.status === "not_installed") {
-    return null;
-  }
-
-  const onPaidPlan = !!ent.plan;
-  let banner = null;
+//                 pattern). Renders the in-app Billing CTA when provided;
+//                 omit it to render the banner with no in-app button.
+//   context     — the UI-extension serverless context (optional; only used
+//                 for the portal link's return URL portal id).
+export function BillingBanner({ state, actionLabel, actionsNoun, onNavigate, context }) {
+  const banner = resolveBillingBanner(state?.entitlement, {
+    actionLabel,
+    actionsNoun,
+  });
+  if (!banner) return null;
 
-  if (!onPaidPlan && (ent.depleted === true || ent.entitled === false)) {
-    banner = {
-      variant: "error",
-      title: "You're out of credits",
-      message: `Your credits are used up. Choose a plan in Billing to keep ${actionLabel ?? "going"}.`,
-    };
-  } else if (onPaidPlan && ent.over_included === true) {
-    banner = {
-      variant: "warning",
-      title: "You've used your included credits",
-      message:
-        "Extra usage this period is billed as overage at your plan's per-credit rate.",
-    };
-  } else if (
-    !onPaidPlan &&
-    typeof ent.remaining === "number" &&
-    typeof ent.low_threshold === "number" &&
-    ent.remaining <= ent.low_threshold
-  ) {
-    banner = {
-      variant: "warning",
-      title: "Running low on credits",
-      message: `You're almost out of credits. Pick a plan in Billing so your ${
-        actionsNoun ?? "actions"
-      } don't get interrupted.`,
-    };
+  // "Update payment method" links out to the billing service's
+  // GET /v1/billing/portal/start (resolves the customer + creates the Stripe
+  // Customer Portal session server-side, 303s to Stripe in the opened tab) —
+  // the same entry point BillingTab's "Manage subscription" uses. Built only
+  // when the portal CTA is in play; null until billing_base_url + the signed
+  // action token are both known, in which case the CTA falls back to the
+  // in-app Billing tab (which renders the same portal link once loaded).
+  let portalStartUrl = null;
+  if (banner.cta?.kind === "portal") {
+    const base = state?.billing_base_url ?? null;
+    const portalToken = state?.billing_action_tokens?.portal ?? null;
+    if (base && portalToken) {
+      const returnUrl = state?.app_id
+        ? `https://app.hubspot.com/app/${context?.portal?.id}/${state.app_id}/billing`
+        : "https://app.hubspot.com/";
+      portalStartUrl =
+        `${base}/v1/billing/portal/start` +
+        `?token=${encodeURIComponent(portalToken)}` +
+        `&return_url=${encodeURIComponent(returnUrl)}`;
+    }
   }
 
-  if (!banner) return null;
-
   return (
     <Alert title={banner.title} variant={banner.variant}>
       <Flex direction="column" gap="extra-small">
         <Text>{banner.message}</Text>
-        {onNavigate && (
+        {banner.cta?.kind === "portal" && portalStartUrl ? (
+          <Button
+            variant="secondary"
+            href={{ url: portalStartUrl, external: true }}
+          >
+            {banner.cta.label}
+          </Button>
+        ) : banner.cta && onNavigate ? (
           <Button variant="secondary" onClick={() => onNavigate("/billing")}>
-            Go to Billing →
+            {banner.cta.kind === "portal" ? "Go to Billing →" : banner.cta.label}
           </Button>
-        )}
+        ) : null}
       </Flex>
     </Alert>
   );

package/src/billing/BillingTab.jsx

@@ -7,11 +7,22 @@ import {
   LoadingButton,
   Button,
   Alert,
+  Input,
+  LoadingSpinner,
+  Table,
+  TableHead,
+  TableHeader,
+  TableBody,
+  TableRow,
+  TableCell,
 } from "@hubspot/ui-extensions";
-import { fmtDate, daysUntil } from "../lib/format";
+import { fmtDate, fmtMoney, daysUntil } from "../lib/format";
+import { parseLimitInput } from "../lib/creditDisplay";
+import { useStrictModeEffect } from "../lib/useStrictModeEffect";
 import { CreditMeter } from "../home/CreditMeter";
 import { PlanGrid } from "./PlanGrid";
 import { refreshBillingActionTokens } from "../sdk/billing";
+import { getTopUps, setBillingLimit } from "../sdk/app/topUps";
 
 // Billing action tokens (see common.billing.action_token) are signed with a
 // 5-minute TTL — short enough that a customer who opens the tab and comes
@@ -381,7 +392,230 @@ function TrialSubscriptionBilling({ context, state, appKey, openIframe = null })
   );
 }
 
-function CreditsBilling({ context, state, appKey, openIframe = null }) {
+// The top-up purchase table itself — pure rendering (exported for tests);
+// fetch/loading/error live in TopUpHistory below.
+export function TopUpHistoryTable({ topUps }) {
+  return (
+    <>
+      <Table>
+        <TableHead>
+          <TableRow>
+            <TableHeader>Date</TableHeader>
+            <TableHeader>Credits</TableHeader>
+            <TableHeader>Price</TableHeader>
+            <TableHeader>Note</TableHeader>
+          </TableRow>
+        </TableHead>
+        <TableBody>
+          {topUps.map((topUp, i) => (
+            <TableRow key={`${topUp.at}-${i}`}>
+              <TableCell>{fmtDate(topUp.at)}</TableCell>
+              <TableCell>{topUp.credits}</TableCell>
+              <TableCell>{fmtMoney(topUp.price_cents)}</TableCell>
+              <TableCell>Does not expire</TableCell>
+            </TableRow>
+          ))}
+        </TableBody>
+      </Table>
+      <Text format={{ fontStyle: "italic" }}>
+        Additional credits don't expire — they draw down only after your
+        monthly plan credits.
+      </Text>
+    </>
+  );
+}
+
+// "Top-up history" — the credit app's prepaid top-up purchases (the
+// never-expiring bank), from the base service's
+// GET /v1/hubspot/app_pages/{app}/billing/top-ups (newest first). Loading,
+// error, and empty states; the table mirrors AlertsTab's shape.
+function TopUpHistory({ context, appKey }) {
+  const [status, setStatus] = useState("loading"); // loading | ready | error
+  const [topUps, setTopUps] = useState([]);
+
+  useStrictModeEffect(
+    async ({ mounted }) => {
+      try {
+        const res = await getTopUps(context, {
+          appKey,
+          portalId: context?.portal?.id,
+        });
+        if (mounted.current) {
+          setTopUps(res?.top_ups ?? []);
+          setStatus("ready");
+        }
+      } catch {
+        if (mounted.current) setStatus("error");
+      }
+    },
+    [context, appKey]
+  );
+
+  if (status === "loading") {
+    return <LoadingSpinner showLabel label="Loading top-ups…" />;
+  }
+  if (status === "error") {
+    return (
+      <Alert title="Couldn't load top-up history" variant="warning">
+        <Text>Refresh the page to try again.</Text>
+      </Alert>
+    );
+  }
+
+  return (
+    <Flex direction="column" gap="small">
+      <Heading>Top-up history</Heading>
+      {topUps.length === 0 ? (
+        <Text format={{ fontStyle: "italic" }}>
+          No top-ups yet. Additional credits you purchase are listed here —
+          they don't expire.
+        </Text>
+      ) : (
+        <TopUpHistoryTable topUps={topUps} />
+      )}
+    </Flex>
+  );
+}
+
+// "Billing limit" — the per-period spend cap on automatic top-ups. Shows the
+// current limit (when the entitlement arm carries billing_limit_cents), sets
+// a new one (USD input -> cents), or clears it, via the base service's
+// POST /v1/hubspot/app_pages/{app}/billing/limit. Success/error feedback is an
+// inline Alert, consistent with the rest of this tab.
+//
+// The POST requires a billing action token (?token=) on top of verify_hubspot
+// — billingActionToken should be the (interval-refreshed)
+// state.billing_action_tokens.portal. Without it (an older backend serving
+// /v1/home without minted tokens) the set/clear buttons stay disabled rather
+// than failing with a 401 — the same "hidden until token exists" posture as
+// the restart link.
+function BillingLimitControl({
+  context,
+  appKey,
+  currentLimitCents = null,
+  billingActionToken = null,
+}) {
+  const [limitCents, setLimitCents] = useState(currentLimitCents ?? null);
+  const [value, setValue] = useState("");
+  const [saving, setSaving] = useState(false);
+  const [notice, setNotice] = useState(null); // { variant, text }
+
+  // The entitlement arrives with /v1/home; adopt a changed server-side limit.
+  useEffect(() => {
+    setLimitCents(currentLimitCents ?? null);
+  }, [currentLimitCents]);
+
+  const canSubmit = !saving && !!billingActionToken;
+
+  const save = async () => {
+    const parsed = parseLimitInput(value);
+    if (!parsed.ok) {
+      setNotice({ variant: "error", text: parsed.error });
+      return;
+    }
+    setSaving(true);
+    setNotice(null);
+    try {
+      await setBillingLimit(context, {
+        appKey,
+        portalId: context?.portal?.id,
+        limitCents: parsed.limitCents,
+        token: billingActionToken,
+      });
+      setLimitCents(parsed.limitCents);
+      setValue("");
+      setNotice({
+        variant: "success",
+        text: `Billing limit set to ${fmtMoney(parsed.limitCents)} per billing period.`,
+      });
+    } catch (e) {
+      setNotice({
+        variant: "error",
+        text: e?.message ?? "Couldn't update the billing limit.",
+      });
+    } finally {
+      setSaving(false);
+    }
+  };
+
+  const clear = async () => {
+    setSaving(true);
+    setNotice(null);
+    try {
+      await setBillingLimit(context, {
+        appKey,
+        portalId: context?.portal?.id,
+        limitCents: null,
+        token: billingActionToken,
+      });
+      setLimitCents(null);
+      setNotice({
+        variant: "success",
+        text: "Billing limit cleared — automatic top-ups are uncapped.",
+      });
+    } catch (e) {
+      setNotice({
+        variant: "error",
+        text: e?.message ?? "Couldn't clear the billing limit.",
+      });
+    } finally {
+      setSaving(false);
+    }
+  };
+
+  return (
+    <Flex direction="column" gap="small">
+      <Heading>Billing limit</Heading>
+      <Text>
+        Cap how much automatic credit top-ups can spend each billing period.
+      </Text>
+      <Text format={{ fontWeight: "bold" }}>
+        {limitCents != null
+          ? `Current limit: ${fmtMoney(limitCents)} per billing period`
+          : "No limit set — automatic top-ups are uncapped."}
+      </Text>
+      <Flex direction="row" gap="small" align="end">
+        <Input
+          label="Limit (USD)"
+          name="billing-limit"
+          placeholder="e.g. 100.00"
+          value={value}
+          onChange={setValue}
+        />
+        <LoadingButton
+          variant="primary"
+          loading={saving}
+          disabled={!canSubmit || !value.trim()}
+          onClick={save}
+        >
+          Set limit
+        </LoadingButton>
+        {limitCents != null && (
+          <Button variant="secondary" disabled={!canSubmit} onClick={clear}>
+            Clear limit
+          </Button>
+        )}
+      </Flex>
+      {!billingActionToken && (
+        <Text format={{ fontStyle: "italic" }}>
+          Preparing billing… the limit controls unlock in a moment. Refresh the
+          page if this persists.
+        </Text>
+      )}
+      {notice && (
+        <Alert
+          variant={notice.variant}
+          title={notice.variant === "success" ? "Saved" : "Couldn't save"}
+        >
+          <Text>{notice.text}</Text>
+        </Alert>
+      )}
+    </Flex>
+  );
+}
+
+// Exported for tests (the billing_model gating of the top-up sections).
+export function CreditsBilling({ context, state, appKey, openIframe = null }) {
   const onPaidPlan = !!state?.entitlement?.plan;
 
   // Direct external link to the billing service's GET /v1/billing/portal/start,
@@ -457,6 +691,28 @@ function CreditsBilling({ context, state, appKey, openIframe = null }) {
             Growth Operations apps.
           </Text>
         )}
+        {/* Top-up ("bank") model surfaces — gated on the entitlement arm's
+            billing_model discriminator. "metered" accounts never top up, so
+            the sections would be permanently empty; backends that predate the
+            field don't have the endpoints at all. Both cases hide the
+            sections (the safe direction — no dead UI). */}
+        {state?.entitlement?.billing_model === "topup" && (
+          <>
+            <TopUpHistory context={context} appKey={appKey} />
+            <BillingLimitControl
+              context={context}
+              appKey={appKey}
+              // Populated for all accounts on the current contract
+              // (int cents | null; absent on older backends = no cap).
+              currentLimitCents={state?.entitlement?.billing_limit_cents ?? null}
+              // The limit POST's second auth dep (see setBillingLimit). `state`
+              // here is BillingTab's interval-refreshed copy, so this token is
+              // re-minted every 3 minutes — a long-open tab never POSTs an
+              // expired one.
+              billingActionToken={state?.billing_action_tokens?.portal ?? null}
+            />
+          </>
+        )}
       </Flex>
     );
   }

package/src/home/CreditMeter.jsx

@@ -1,6 +1,7 @@
 import React from "react";
 import { Flex, Tile, Text, ProgressBar, StatusTag, Alert } from "@hubspot/ui-extensions";
 import { daysUntil } from "../lib/format";
+import { resolveCreditMeter } from "../lib/creditDisplay";
 
 // THE credit-archetype activity tile + hero signal. For credit apps, "credits
 // remaining" is the primary glanceable signal the way "trial days left" is for
@@ -8,49 +9,26 @@ import { daysUntil } from "../lib/format";
 // `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.
+// All branch math (number precedence, threshold_state → tag/alert, the
+// pool+bank split) lives in ../lib/creditDisplay so it's unit-testable — this
+// component is pure rendering.
+//
+// Two-segment bank display: accounts with a top-up bank (topup billing model)
+// get the combined marker bar — `${used} of ${granted}` over the combined
+// pool+bank denominator, so after a period reset with bank left it reads e.g.
+// "0 of 1,700" while the bank segment shows what's left — plus the
+// pool/bank breakdown lines. Accounts with NO bank (top_up_bank_remaining 0
+// AND never a top-up) render exactly the legacy single-segment bar.
 //
 // 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);
-
-  // A paid plan is NEVER blocked — exceeding the included bucket is overage,
-  // not depletion (action_allowed_by_portal/consume_credits never gate a
-  // paid plan; see common.entitlements.credits.to_entitlement). So `depleted`
-  // must not fall back to raw `remaining <= 0` on a paid plan the way it does
-  // on the free tier — that raw check is exactly what showed a paying,
-  // already-subscribed customer a blocking "Depleted"/"out of credits" panel
-  // (confirmed live 2026-09-02). `over_included` is the distinct paid-plan
-  // signal for "you've used your included credits, extra usage is overage".
-  const onPaidPlan = !!ent?.plan;
-  const lowThreshold = ent?.low_threshold ?? 0;
-  const depleted = !onPaidPlan && (ent?.depleted === true || remaining <= 0);
-  const overIncluded =
-    onPaidPlan && (ent?.over_included === true || used > granted);
-  const low = !depleted && !overIncluded && remaining <= lowThreshold;
+  const view = resolveCreditMeter(entitlement, creditMeter);
+  if (!view) return null;
 
-  // healthy green / low or overage yellow / depleted red.
-  const variant = depleted ? "error" : overIncluded || low ? "warning" : "success";
-  const tagVariant = depleted ? "danger" : overIncluded || low ? "warning" : "success";
-  const tagLabel = depleted
-    ? "Depleted"
-    : overIncluded
-      ? "Over included"
-      : low
-        ? "Running low"
-        : "Healthy";
-
-  const grantDaysLeft = ent?.grant_expires_at ? daysUntil(ent.grant_expires_at) : null;
+  const { granted, used, remaining, bank, tagVariant, tagLabel, alert } = view;
+  const grantDaysLeft = view.grantExpiresAt ? daysUntil(view.grantExpiresAt) : null;
 
   return (
     <Tile>
@@ -65,15 +43,41 @@ export function CreditMeter({ entitlement, creditMeter }) {
           {remaining} of {granted} credits left
         </Text>
 
-        <ProgressBar
-          title={`${used} used`}
-          value={used}
-          maxValue={granted > 0 ? granted : 1}
-          showPercentage={true}
-        />
+        {bank ? (
+          <>
+            {/* Current-position marker over the COMBINED pool+bank
+                denominator (used = granted - remaining). The HubSpot
+                ProgressBar is single-value, so the two segments are the
+                labeled breakdown below; this bar is the position within the
+                whole. */}
+            <ProgressBar
+              title={`${used} of ${granted} used`}
+              value={used}
+              maxValue={granted > 0 ? granted : 1}
+              showPercentage={true}
+            />
+            <Flex direction="column" gap="extra-small">
+              <Text>
+                Monthly plan credits: {bank.poolRemaining} of {bank.poolGrant}{" "}
+                left
+              </Text>
+              <Text>Additional credits: {bank.bankRemaining} left</Text>
+              <Text format={{ fontStyle: "italic" }}>
+                Additional credits don't expire.
+              </Text>
+            </Flex>
+          </>
+        ) : (
+          <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 && (
+        {view.grantExpiresAt && grantDaysLeft != null && (
           <Text format={{ fontStyle: "italic" }}>
             {granted} free credits —{" "}
             {grantDaysLeft <= 0
@@ -82,24 +86,9 @@ export function CreditMeter({ entitlement, creditMeter }) {
           </Text>
         )}
 
-        {(depleted || overIncluded || low) && (
-          <Alert
-            title={
-              depleted
-                ? "You're out of credits"
-                : overIncluded
-                  ? "You've used your included credits"
-                  : "Running low on credits"
-            }
-            variant={variant}
-          >
-            <Text>
-              {depleted
-                ? "Pick a plan or buy more credits to keep going."
-                : overIncluded
-                  ? "Extra usage this period is billed as overage at your plan's per-credit rate."
-                  : "You're getting close to your limit — pick a plan to top up."}
-            </Text>
+        {alert && (
+          <Alert title={alert.title} variant={alert.variant}>
+            <Text>{alert.message}</Text>
           </Alert>
         )}
       </Flex>

package/src/index.js

@@ -44,6 +44,12 @@ export {
   STATUS_VARIANT,
 } from "./lib/format";
 export { useStrictModeEffect } from "./lib/useStrictModeEffect";
+export {
+  hasTopUpBank,
+  resolveCreditMeter,
+  resolveBillingBanner,
+  parseLimitInput,
+} from "./lib/creditDisplay";
 
 // HubSpot URL builders (app.hubspot.com record/property/list links).
 export {
@@ -65,6 +71,8 @@ export {
   AppApiError,
   getAlerts,
   dismissAlert,
+  getTopUps,
+  setBillingLimit,
   getSettings,
   updateSettings,
   makeSettingsApi,

package/src/lib/creditDisplay.js

@@ -0,0 +1,299 @@
+// Pure display logic for the credits archetype's top-up ("bank") model —
+// framework-free (no React) so the branches are unit-testable and the
+// components stay thin. Source of truth for the semantics:
+// common.entitlements.credits.CreditState.to_entitlement.
+//
+// THE MODEL IN BRIEF
+//   Credit apps get two buckets: a monthly pool (resets each billing period,
+//   no rollover) and a never-expiring prepaid top-up bank that draws down
+//   ONLY after the pool. Under the "topup" billing model the entitlement
+//   arm's granted/used/remaining are a COMBINED display:
+//     granted   = period pool + bank remaining
+//     remaining = pool remaining + bank remaining
+//     used      = granted - remaining   (the current-position marker)
+//   so after a period reset with bank left the meter reads e.g. "0 of 1,700".
+//   Metered-model (legacy) paid accounts keep the RAW display (used grows
+//   past granted as overage) and only ever see threshold_state
+//   "healthy"/"depleted" with top_up_bank_remaining 0.
+//
+// BLOCKING (replaces the old "a paid plan is NEVER blocked" assumption):
+//   threshold_state === "depleted" is the ONLY hard-blocked state — a
+//   topup-model PAID plan DOES block at true zero (pool + bank empty, no
+//   successful top-up). A metered paid account in overage is NOT blocked:
+//   `over_included` always wins over a depleted reading (the backend mirrors
+//   this — metered overage keeps threshold_state "healthy" — and the UI
+//   double-guards so a stale/mixed payload can't regress the 2026-09-02
+//   incident where a paying, overage account was shown a blocking
+//   "Depleted"/"out of credits" panel).
+
+// True when the account has (or ever had) a top-up bank: the two-segment
+// meter renders only then — a zero bank with NO top-up ever (last_top_up_at
+// null) renders exactly the legacy single-segment bar.
+export function hasTopUpBank(ent) {
+  if (!ent) return false;
+  return (ent.top_up_bank_remaining ?? 0) > 0 || ent.last_top_up_at != null;
+}
+
+// Resolve every CreditMeter display decision from the /v1/home payload.
+// Returns null when there is no credit data to show (component renders
+// nothing). Otherwise:
+//   granted/used/remaining — combined (topup) or raw (legacy) display numbers
+//   bank                 — { bankRemaining, poolGrant, poolRemaining, poolUsed }
+//                          when the account has a bank, else null
+//   thresholdState       — the arm's threshold_state, or null on a backend
+//                          that predates it
+//   depleted/overIncluded/low — mutually-exclusive urgency flags
+//   tagVariant/tagLabel  — StatusTag rendering
+//   alert                — { variant, title, message } or null
+//   grantExpiresAt       — pass-through for the free-grant countdown
+export function resolveCreditMeter(entitlement, creditMeter) {
+  const ent = entitlement?.mode === "credits" ? entitlement : null;
+  const meter = creditMeter ?? null;
+  if (!ent && !meter) return null;
+
+  // Number precedence: once the entitlement arm carries the top-up fields it
+  // is authoritative — the credit_meter block stays RAW pool-only under the
+  // topup model, so reading meter-first would hide the bank. On older
+  // backends (no top-up fields) keep the historical meter-first precedence
+  // (the meter is the richer block: it carries `recent`).
+  const entHasTopUpFields =
+    ent != null && typeof ent.top_up_bank_remaining === "number";
+  const pick = (key) =>
+    entHasTopUpFields ? ent[key] ?? meter?.[key] : meter?.[key] ?? ent?.[key];
+
+  const granted = pick("granted") ?? 0;
+  const used = pick("used") ?? 0;
+  const remaining = pick("remaining") ?? Math.max(granted - used, 0);
+
+  const onPaidPlan = !!ent?.plan;
+  const lowThreshold = ent?.low_threshold ?? 0;
+  const thresholdState =
+    typeof ent?.threshold_state === "string" ? ent.threshold_state : null;
+
+  const overIncluded =
+    onPaidPlan &&
+    (ent?.over_included === true || (thresholdState == null && used > granted));
+  const depleted =
+    thresholdState != null
+      ? thresholdState === "depleted" && !overIncluded
+      : !onPaidPlan && (ent?.depleted === true || remaining <= 0);
+  const low = !depleted && !overIncluded && remaining <= lowThreshold;
+
+  // Bank split. Drawdown is monthly-first, so of the combined `remaining` the
+  // bank portion is bankRemaining and the rest is pool remaining; the pool
+  // segment's full size is the combined denominator minus the bank.
+  let bank = null;
+  if (hasTopUpBank(ent)) {
+    const bankRemaining = Math.max(0, ent?.top_up_bank_remaining ?? 0);
+    const poolGrant = Math.max(granted - bankRemaining, 0);
+    const poolRemaining = Math.min(Math.max(remaining - bankRemaining, 0), poolGrant);
+    bank = {
+      bankRemaining,
+      poolGrant,
+      poolRemaining,
+      poolUsed: poolGrant - poolRemaining,
+    };
+  }
+
+  let tagVariant;
+  let tagLabel;
+  if (depleted) {
+    tagVariant = "danger";
+    tagLabel = "Depleted";
+  } else if (thresholdState === "top_up_failed") {
+    tagVariant = "danger";
+    tagLabel = "Top-up failed";
+  } else if (thresholdState === "limit_reached") {
+    tagVariant = "warning";
+    tagLabel = "Limit reached";
+  } else if (thresholdState === "top_up_pending") {
+    tagVariant = "info";
+    tagLabel = "Adding credits";
+  } else if (overIncluded) {
+    tagVariant = "warning";
+    tagLabel = "Over included";
+  } else if (low) {
+    tagVariant = "warning";
+    tagLabel = "Running low";
+  } else {
+    tagVariant = "success";
+    tagLabel = "Healthy";
+  }
+
+  // The inline meter alert mirrors the banner's messaging at the point of
+  // glance. Legacy branches keep their pre-top-up copy byte-for-byte.
+  let alert = null;
+  if (depleted) {
+    alert = {
+      variant: "error",
+      title: "You're out of credits",
+      message: onPaidPlan
+        ? "Actions are paused until your next billing period or a successful top-up."
+        : "Choose a plan to resume your use.",
+    };
+  } else if (thresholdState === "top_up_failed") {
+    alert = {
+      variant: "error",
+      title: "We couldn't add credits",
+      message:
+        "The automatic top-up charge failed — update your payment method in Billing.",
+    };
+  } else if (thresholdState === "limit_reached") {
+    alert = {
+      variant: "warning",
+      title: "Billing limit reached",
+      message:
+        "Automatic top-ups are paused at your spending limit for this period. Raise your billing limit in Billing to resume them.",
+    };
+  } else if (overIncluded) {
+    alert = {
+      variant: "warning",
+      title: "You've used your included credits",
+      message:
+        "Extra usage this period is billed as overage at your plan's per-credit rate.",
+    };
+  } else if (low) {
+    alert = {
+      variant: "warning",
+      title: "Running low on credits",
+      message: "You're getting close to your limit — pick a plan to top up.",
+    };
+  }
+
+  return {
+    granted,
+    used,
+    remaining,
+    bank,
+    thresholdState,
+    depleted,
+    overIncluded,
+    low,
+    tagVariant,
+    tagLabel,
+    alert,
+    grantExpiresAt: ent?.grant_expires_at ?? null,
+  };
+}
+
+// Resolve the app-wide BillingBanner from the credits entitlement arm.
+// Returns null to render nothing (non-credits mode, pre-install, or healthy),
+// else { variant, title, message, cta } where cta is null or:
+//   { kind: "portal",  label } — link out to the Stripe billing-portal entry
+//                                point (payment-method fixes)
+//   { kind: "billing", label } — in-app navigate to the Billing tab
+//
+// Driven by threshold_state for the top-up model; the legacy metered branches
+// (free depleted / paid over_included / free running-low) are byte-identical
+// to the pre-top-up banner.
+export function resolveBillingBanner(entitlement, { actionLabel, actionsNoun } = {}) {
+  const ent = entitlement;
+  if (!ent || ent.mode !== "credits" || ent.status === "not_installed") {
+    return null;
+  }
+
+  const onPaidPlan = !!ent.plan;
+  const thresholdState =
+    typeof ent.threshold_state === "string" ? ent.threshold_state : null;
+  const label = actionLabel ?? "going";
+  const noun = actionsNoun ?? "actions";
+
+  // --- Top-up (bank) model states. The backend only emits these three for
+  // topup-model accounts; each maps to exactly one banner. ---
+  if (thresholdState === "top_up_pending") {
+    return {
+      variant: "info",
+      title: "Adding credits automatically",
+      message:
+        "Your monthly credits ran low, so we're adding more with your payment method on file. Nothing to do — this usually takes a moment.",
+      cta: null,
+    };
+  }
+  if (thresholdState === "top_up_failed") {
+    return {
+      variant: "error",
+      title: "We couldn't add credits",
+      message: `The automatic top-up charge failed. Update your payment method so your ${noun} aren't interrupted.`,
+      cta: { kind: "portal", label: "Update payment method" },
+    };
+  }
+  if (thresholdState === "limit_reached") {
+    return {
+      variant: "warning",
+      title: "Billing limit reached",
+      message:
+        "Automatic top-ups are paused — you've hit your spending limit for this billing period. Raise your billing limit to keep them going.",
+      cta: { kind: "billing", label: "Raise your billing limit" },
+    };
+  }
+
+  // --- Hard-blocked. threshold_state "depleted" is the ONLY blocking state
+  // (a topup-model paid plan blocks at true zero); `over_included` overrides
+  // a depleted reading so a metered paid account in overage is never shown as
+  // blocked. Backends that predate threshold_state fall back to the legacy
+  // derivation (only a non-paid account blocks at zero). ---
+  const overIncluded = onPaidPlan && ent.over_included === true;
+  const depleted =
+    thresholdState != null
+      ? thresholdState === "depleted" && !overIncluded
+      : !onPaidPlan && (ent.depleted === true || ent.entitled === false);
+
+  if (depleted) {
+    return {
+      variant: "error",
+      title: "You're out of credits",
+      message: onPaidPlan
+        ? `Your ${noun} are paused until your next billing period or a successful top-up.`
+        : `Your credits are used up. Choose a plan in Billing to keep ${label}.`,
+      cta: { kind: "billing", label: "Go to Billing →" },
+    };
+  }
+  if (overIncluded) {
+    return {
+      variant: "warning",
+      title: "You've used your included credits",
+      message:
+        "Extra usage this period is billed as overage at your plan's per-credit rate.",
+      cta: { kind: "billing", label: "Go to Billing →" },
+    };
+  }
+  if (
+    !onPaidPlan &&
+    typeof ent.remaining === "number" &&
+    typeof ent.low_threshold === "number" &&
+    ent.remaining <= ent.low_threshold
+  ) {
+    return {
+      variant: "warning",
+      title: "Running low on credits",
+      message: `You're almost out of credits. Pick a plan in Billing so your ${noun} don't get interrupted.`,
+      cta: { kind: "billing", label: "Go to Billing →" },
+    };
+  }
+
+  return null;
+}
+
+// Parse a USD billing-limit input ("$1,234.56", "50", "50.00") into cents.
+// Returns { ok: true, limitCents } or { ok: false, error } with a
+// customer-readable message. A limit must be a positive amount — clearing the
+// limit is a separate action (null), not "0".
+export function parseLimitInput(text) {
+  const cleaned = String(text ?? "")
+    .trim()
+    .replace(/[$,\s]/g, "");
+  if (!cleaned) {
+    return { ok: false, error: "Enter a dollar amount, e.g. 50 or 50.00." };
+  }
+  if (!/^\d+(\.\d{1,2})?$/.test(cleaned)) {
+    return {
+      ok: false,
+      error: "Enter a valid dollar amount (numbers only, up to 2 decimals).",
+    };
+  }
+  const limitCents = Math.round(parseFloat(cleaned) * 100);
+  if (!Number.isSafeInteger(limitCents) || limitCents <= 0) {
+    return { ok: false, error: "The limit must be more than $0." };
+  }
+  return { ok: true, limitCents };
+}

package/src/sdk/app/topUps.js

@@ -0,0 +1,48 @@
+// Top-up ("bank") billing endpoints — the base service's app-agnostic
+// /v1/hubspot/app_pages/{app}/billing/* routes (verify_hubspot; the platform
+// injects Authorization, so like every callAppApi caller we send NO custom
+// headers). Base-hosted credit apps reach base at context.variables.BASE_URL;
+// `portalId` rides as a query param — the same pattern as the base-hosted
+// alerts routes (see ./alerts).
+import { callAppApi } from "./base";
+
+function billingPath(appKey, suffix, portalId, { token } = {}) {
+  const path = `/v1/hubspot/app_pages/${encodeURIComponent(appKey)}/billing/${suffix}`;
+  const params = new URLSearchParams();
+  if (portalId != null) params.append("portalId", portalId);
+  if (token != null) params.append("token", token);
+  const query = params.toString();
+  return query ? `${path}?${query}` : path;
+}
+
+// GET /v1/hubspot/app_pages/{app}/billing/top-ups ->
+//   { top_ups: [{ at, credits, price_cents, period_key }] }  (newest first)
+// verify_hubspot only — no billing action token needed.
+export async function getTopUps(context, { appKey, portalId } = {}) {
+  return callAppApi(context, billingPath(appKey, "top-ups", portalId), "GET");
+}
+
+// POST /v1/hubspot/app_pages/{app}/billing/limit, body { limit_cents: int|null }
+// — set (or clear, with null) the per-period auto top-up spend cap. Body is a
+// plain object, never JSON.stringify'd (the hubspot.fetch rule callAppApi
+// enforces).
+//
+// The POST has a SECOND auth dep beyond verify_hubspot: a billing action
+// token (common.billing.action_token) as a REQUIRED `token` query param —
+// the same "recent, in-app access to THIS app's billing surface for THIS
+// portal" proof the billing service's /v1/billing/*/start endpoints require
+// (blocks the bare-portal_id hijack vector). Pass a fresh
+// state.billing_action_tokens.portal (any action in the vocabulary verifies);
+// BillingTab re-mints the set on an interval so a long-open tab never hands
+// over an expired one.
+export async function setBillingLimit(
+  context,
+  { appKey, portalId, limitCents, token } = {}
+) {
+  return callAppApi(
+    context,
+    billingPath(appKey, "limit", portalId, { token }),
+    "POST",
+    { limit_cents: limitCents ?? null }
+  );
+}

package/src/sdk/index.js

@@ -4,6 +4,7 @@
 // App backend (context.variables.BASE_URL) via hubspot.fetch.
 export { callAppApi, AppApiError } from "./app/base";
 export { getAlerts, dismissAlert } from "./app/alerts";
+export { getTopUps, setBillingLimit } from "./app/topUps";
 export { getSettings, updateSettings, makeSettingsApi } from "./app/settings";
 export {
   strToBase64,