@growth-operations/ui-shared 1.17.2 → 1.19.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@growth-operations/ui-shared",
-  "version": "1.17.2",
+  "version": "1.19.0",
   "description": "Shared HubSpot UI-extension modules (Home, Billing) for Growth Operations apps.",
   "license": "MIT",
   "private": false,

package/src/billing/BillingTab.jsx

@@ -8,6 +8,7 @@ import {
   Button,
   Alert,
   Input,
+  Link,
   LoadingSpinner,
   Table,
   TableHead,
@@ -22,7 +23,7 @@ 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";
+import { getInvoices, 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
@@ -477,6 +478,124 @@ function TopUpHistory({ context, appKey }) {
   );
 }
 
+// Invoice status -> label (Stripe's vocabulary: paid / open / void /
+// uncollectible; drafts and $0 voids are filtered server-side).
+const INVOICE_STATUS_LABELS = {
+  paid: "Paid",
+  open: "Open",
+  void: "Void",
+  uncollectible: "Uncollectible",
+};
+
+// The invoice-history table itself — pure rendering (exported for tests);
+// fetch/loading/error live in InvoiceHistory below.
+export function InvoiceHistoryTable({ invoices }) {
+  return (
+    <Table>
+      <TableHead>
+        <TableRow>
+          <TableHeader>Date</TableHeader>
+          <TableHeader>Description</TableHeader>
+          <TableHeader>Amount</TableHeader>
+          <TableHeader>Status</TableHeader>
+          <TableHeader>Receipt</TableHeader>
+        </TableRow>
+      </TableHead>
+      <TableBody>
+        {invoices.map((invoice, i) => (
+          <TableRow key={`${invoice.id ?? invoice.date}-${i}`}>
+            <TableCell>{fmtDate(invoice.date)}</TableCell>
+            <TableCell>{invoice.description}</TableCell>
+            <TableCell>{fmtMoney(invoice.amount_cents, invoice.currency)}</TableCell>
+            <TableCell>
+              {INVOICE_STATUS_LABELS[invoice.status] ?? invoice.status ?? "—"}
+            </TableCell>
+            <TableCell>
+              {invoice.hosted_invoice_url ? (
+                <Link href={{ url: invoice.hosted_invoice_url, external: true }}>
+                  Receipt
+                </Link>
+              ) : (
+                "—"
+              )}
+            </TableCell>
+          </TableRow>
+        ))}
+      </TableBody>
+    </Table>
+  );
+}
+
+// "Invoice history" — every Stripe invoice on the portal's customer
+// (subscription renewals, one-off charges, top-up bands — including VOIDED
+// top-ups, which tell the decline story), from the billing service's
+// GET /v1/billing/invoices (newest first, capped at 24). Loading, error, and
+// empty states mirror TopUpHistory.
+//
+// Auth is the billing action token (the claim scopes the response to THIS
+// portal's Stripe customer). BillingTab re-mints the token set every 3
+// minutes; depending on the token means the list also quietly refreshes on
+// that cadence while the tab stays open — a top-up that completes mid-session
+// shows up without a reload.
+//
+// Two "render nothing" degradations: no billing_base_url / token yet (an
+// older backend that doesn't mint them — same "hidden until token exists"
+// posture as the restart link), and a 404 from a billing service that
+// predates the invoices route (hide the section instead of erroring forever
+// until the service's next deploy).
+function InvoiceHistory({ billingBaseUrl, billingActionToken }) {
+  const [status, setStatus] = useState("loading"); // loading | ready | error | unsupported
+  const [invoices, setInvoices] = useState([]);
+
+  useStrictModeEffect(
+    async ({ mounted }) => {
+      try {
+        const res = await getInvoices({
+          billingBaseUrl,
+          token: billingActionToken,
+        });
+        if (mounted.current) {
+          setInvoices(res?.invoices ?? []);
+          setStatus("ready");
+        }
+      } catch (e) {
+        if (mounted.current) {
+          setStatus(e?.statusCode === 404 ? "unsupported" : "error");
+        }
+      }
+    },
+    [billingBaseUrl, billingActionToken]
+  );
+
+  if (!billingBaseUrl || !billingActionToken || status === "unsupported") {
+    return null;
+  }
+  if (status === "loading") {
+    return <LoadingSpinner showLabel label="Loading invoices…" />;
+  }
+  if (status === "error") {
+    return (
+      <Alert title="Couldn't load invoice history" variant="warning">
+        <Text>Refresh the page to try again.</Text>
+      </Alert>
+    );
+  }
+
+  return (
+    <Flex direction="column" gap="small">
+      <Heading>Invoice history</Heading>
+      {invoices.length === 0 ? (
+        <Text format={{ fontStyle: "italic" }}>
+          No invoices yet. Subscription renewals, one-off charges, and credit
+          top-ups are listed here.
+        </Text>
+      ) : (
+        <InvoiceHistoryTable invoices={invoices} />
+      )}
+    </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
@@ -699,6 +818,14 @@ export function CreditsBilling({ context, state, appKey, openIframe = null }) {
         {state?.entitlement?.billing_model === "topup" && (
           <>
             <TopUpHistory context={context} appKey={appKey} />
+            {/* Directly below Top-up history (Andrew's ask). `state` here is
+                BillingTab's interval-refreshed copy, so the token is re-minted
+                every 3 minutes; InvoiceHistory hides itself when the backend
+                or billing service predates the pieces it needs. */}
+            <InvoiceHistory
+              billingBaseUrl={base}
+              billingActionToken={state?.billing_action_tokens?.portal ?? null}
+            />
             <BillingLimitControl
               context={context}
               appKey={appKey}

package/src/home/CreditMeter.jsx

@@ -9,16 +9,30 @@ import { resolveCreditMeter } from "../lib/creditDisplay";
 // `credit_meter` block (CONTRACT.md). Renders nothing when there is no credit
 // data to show.
 //
-// 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.
+// All branch math (number precedence, threshold_state → tag/alert/bar
+// variants, 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.
+// Stacked-bars bank display: an account with top-up bank credits left (topup
+// billing model) gets TWO bars, one per bucket, and NO combined headline (the
+// combined pool+bank denominator read as one big confusing allowance):
+//   1. Monthly plan credits — a DEPLETION meter (value = pool used of the
+//      period grant), colored by the POOL'S OWN fill level: success under
+//      80% used, warning at >=80%, danger at >=95% (view.poolBarVariant —
+//      mirrors the ~80/95 low-credit alert ladder).
+//   2. Additional credits — a LEVEL gauge (value = bank remaining of the
+//      bank's granted total: the bank is cumulative and never expires, so a
+//      used-of-granted bar would drift to permanently-near-full over multiple
+//      purchases; the remaining level refills on purchase and drains on
+//      spend), colored by ITS OWN level: success above 50% full, warning at
+//      20–50%, danger at <=20% (view.bankBarVariant).
+// Each bar colors by its own fill, NOT the account's threshold state — the
+// StatusTag keeps the account-state colors. Hosts whose backend predates
+// top_up_bank_granted degrade gracefully: the bank renders as a text-only
+// line (no bar, never "of 0"). An account with NO bank credits left (never
+// topped up, or the bank is spent) renders exactly the legacy view — the
+// "{remaining} of {granted} credits left" headline plus the single
+// fill-colored bar.
 //
 // Props:
 //   entitlement  — the /v1/home entitlement union (uses the credits arm).
@@ -27,7 +41,7 @@ export function CreditMeter({ entitlement, creditMeter }) {
   const view = resolveCreditMeter(entitlement, creditMeter);
   if (!view) return null;
 
-  const { granted, used, remaining, bank, tagVariant, tagLabel, alert } = view;
+  const { granted, used, remaining, bank, tagVariant, tagLabel, poolBarVariant, bankBarVariant, alert } = view;
   const grantDaysLeft = view.grantExpiresAt ? daysUntil(view.grantExpiresAt) : null;
 
   return (
@@ -38,42 +52,64 @@ export function CreditMeter({ entitlement, creditMeter }) {
           <StatusTag variant={tagVariant}>{tagLabel}</StatusTag>
         </Flex>
 
-        {/* PRIMARY signal — large and obvious. */}
-        <Text format={{ fontWeight: "bold", fontSize: "lg" }}>
-          {remaining} of {granted} credits left
-        </Text>
-
         {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}
-            />
+            {/* Pool — depletion meter over the period grant. */}
             <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>
+              <ProgressBar
+                title={`${bank.poolUsed} of ${bank.poolGrant} used`}
+                value={bank.poolUsed}
+                maxValue={bank.poolGrant > 0 ? bank.poolGrant : 1}
+                showPercentage={true}
+                variant={poolBarVariant}
+              />
             </Flex>
+            {bank.bankGranted > 0 ? (
+              // Bank — level gauge over the granted total (refills on
+              // purchase, drains on spend; never expires).
+              <Flex direction="column" gap="extra-small">
+                <Text>
+                  Additional credits (never expire): {bank.bankRemaining} of{" "}
+                  {bank.bankGranted} left
+                </Text>
+                <ProgressBar
+                  title={`${bank.bankRemaining} of ${bank.bankGranted} left`}
+                  value={bank.bankRemaining}
+                  maxValue={bank.bankGranted > 0 ? bank.bankGranted : 1}
+                  showPercentage={true}
+                  variant={bankBarVariant}
+                />
+              </Flex>
+            ) : (
+              // Graceful degradation: the host's backend predates
+              // top_up_bank_granted, so the bank total is unknown — text
+              // only, no bar (never divide by zero, never "of 0").
+              <Flex direction="column" gap="extra-small">
+                <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}
-          />
+          <>
+            {/* 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}
+              variant={poolBarVariant}
+            />
+          </>
         )}
 
         {/* Free-grant countdown: "100 free credits — N days left". */}

package/src/index.js

@@ -72,6 +72,7 @@ export {
   getAlerts,
   dismissAlert,
   getTopUps,
+  getInvoices,
   setBillingLimit,
   getSettings,
   updateSettings,

package/src/lib/creditDisplay.js

@@ -26,9 +26,10 @@
 //   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.
+// True when the account has (or ever had) a top-up bank. Note the CreditMeter
+// bank section renders only while the bank HAS credits left (bankRemaining >
+// 0 — see resolveCreditMeter); this predicate stays the looser "ever had one"
+// for consumers that render history/summary surfaces.
 export function hasTopUpBank(ent) {
   if (!ent) return false;
   return (ent.top_up_bank_remaining ?? 0) > 0 || ent.last_top_up_at != null;
@@ -38,14 +39,53 @@ export function hasTopUpBank(ent) {
 // 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
+//   bank                 — { bankRemaining, bankGranted, poolGrant,
+//                          poolRemaining, poolUsed } when the account has bank
+//                          credits LEFT (bankRemaining > 0), else null — a
+//                          zero bank renders the plain single-pool bar (with
+//                          bankRemaining 0 the combined numbers ARE the pool
+//                          numbers). bankGranted is the bank's lifetime
+//                          granted total (the bank bar's denominator); 0 on
+//                          backends that predate top_up_bank_granted — the
+//                          component degrades to a text-only bank line.
 //   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
+//   tagVariant/tagLabel  — StatusTag rendering (ACCOUNT state — unchanged)
+//   poolBarVariant       — ProgressBar sentiment for the pool bar (and the
+//                          no-bank legacy single bar), colored by the POOL'S
+//                          OWN fill level, not the account state
+//   bankBarVariant       — same for the bank level gauge (null when there is
+//                          no bank section)
 //   alert                — { variant, title, message } or null
 //   grantExpiresAt       — pass-through for the free-grant countdown
+//
+// BAR COLORS ARE PER-BAR FILL LEVELS (Jasper 2026-10): a pool at 99% used
+// with a full bank must NOT render green just because the account is healthy
+// — each bar colors by its own level; the StatusTag keeps the account-state
+// colors. Thresholds mirror the backend's ~80/95 low-credit alert ladder
+// (common.entitlements LOW/DEPLETED banding). Comparisons are integer
+// cross-multiplications — no float fuzz at the 80/95/50/20 boundaries.
+//
+//   pool (DEPLETION meter, value = poolUsed of poolGrant):
+//     success when used < 80%, warning at >= 80%, danger at >= 95%.
+//   bank (LEVEL gauge, value = bankRemaining of bankGranted):
+//     success above 50% full, warning at 20–50%, danger at <= 20%
+//     ("running out") — a draining bank is warning-worthy even though it
+//     never expires.
+function poolBarVariantFor(poolUsed, poolGrant) {
+  if (!(poolGrant > 0)) return "success"; // no grant: nothing to deplete
+  if (poolUsed * 100 >= 95 * poolGrant) return "danger";
+  if (poolUsed * 100 >= 80 * poolGrant) return "warning";
+  return "success";
+}
+
+function bankBarVariantFor(bankRemaining, bankGranted) {
+  if (!(bankGranted > 0)) return "success"; // degraded text-only line renders no bar
+  if (bankRemaining * 100 <= 20 * bankGranted) return "danger";
+  if (bankRemaining * 100 <= 50 * bankGranted) return "warning";
+  return "success";
+}
 export function resolveCreditMeter(entitlement, creditMeter) {
   const ent = entitlement?.mode === "credits" ? entitlement : null;
   const meter = creditMeter ?? null;
@@ -82,13 +122,23 @@ export function resolveCreditMeter(entitlement, creditMeter) {
   // 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.
+  //
+  // The bank section renders ONLY while the bank has credits left
+  // (bankRemaining > 0): a zero bank — never topped up, or fully burned —
+  // renders the plain single-pool bar, and with bankRemaining 0 the combined
+  // numbers ARE the pool numbers (granted == poolGrant, remaining ==
+  // poolRemaining), so nothing is lost.
   let bank = null;
-  if (hasTopUpBank(ent)) {
-    const bankRemaining = Math.max(0, ent?.top_up_bank_remaining ?? 0);
+  const bankRemaining = Math.max(0, ent?.top_up_bank_remaining ?? 0);
+  if (bankRemaining > 0) {
     const poolGrant = Math.max(granted - bankRemaining, 0);
     const poolRemaining = Math.min(Math.max(remaining - bankRemaining, 0), poolGrant);
     bank = {
       bankRemaining,
+      // The bank's lifetime granted total — the bank bar's denominator. 0 on
+      // backends that predate top_up_bank_granted (the component degrades to
+      // a text-only bank line; never divide by zero, never "of 0").
+      bankGranted: Math.max(0, ent?.top_up_bank_granted ?? 0),
       poolGrant,
       poolRemaining,
       poolUsed: poolGrant - poolRemaining,
@@ -120,6 +170,17 @@ export function resolveCreditMeter(entitlement, creditMeter) {
     tagLabel = "Healthy";
   }
 
+  // ProgressBar sentiments — each bar colored by ITS OWN fill level (see the
+  // header block). The pool bar (and the no-bank legacy single bar) reads the
+  // pool's depletion ratio; the bank bar reads the bank's remaining level.
+  const poolBarVariant = poolBarVariantFor(
+    bank ? bank.poolUsed : used,
+    bank ? bank.poolGrant : granted
+  );
+  const bankBarVariant = bank
+    ? bankBarVariantFor(bank.bankRemaining, bank.bankGranted)
+    : null;
+
   // 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;
@@ -171,6 +232,8 @@ export function resolveCreditMeter(entitlement, creditMeter) {
     low,
     tagVariant,
     tagLabel,
+    poolBarVariant,
+    bankBarVariant,
     alert,
     grantExpiresAt: ent?.grant_expires_at ?? null,
   };

package/src/sdk/app/topUps.js

@@ -4,7 +4,13 @@
 // 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";
+//
+// EXCEPTION: getInvoices below hits the BILLING service
+// (growth-ops-apps-app at state.billing_base_url), not base — it holds the
+// Stripe keys and serves every app's billing. Token-auth bare hubspot.fetch,
+// same as refreshBillingActionTokens (../billing).
+import { hubspot } from "@hubspot/ui-extensions";
+import { callAppApi, AppApiError } from "./base";
 
 function billingPath(appKey, suffix, portalId, { token } = {}) {
   const path = `/v1/hubspot/app_pages/${encodeURIComponent(appKey)}/billing/${suffix}`;
@@ -22,6 +28,42 @@ export async function getTopUps(context, { appKey, portalId } = {}) {
   return callAppApi(context, billingPath(appKey, "top-ups", portalId), "GET");
 }
 
+// GET {billingBaseUrl}/v1/billing/invoices?token=... ->
+//   { invoices: [{ id, date, description, amount_cents, currency, status,
+//                  hosted_invoice_url, kind }] }  (newest first, capped at 24)
+//
+// The billing service (growth-ops-apps-app), NOT base — see the header note.
+// Auth is the signed billing-action `token` query param
+// (common.billing.action_token): the endpoint is read-only and accepts any
+// action; BillingTab passes the (interval-refreshed)
+// state.billing_action_tokens.portal. The claim carries app_key + portal_id,
+// so the response is scoped to THIS portal's Stripe customer — never a
+// stranger's invoices.
+//
+// Throws AppApiError on failure, with the FastAPI {"detail": ...} string as
+// the message — a 404 means the billing service predates the invoices route
+// (the caller hides the section rather than erroring forever).
+export async function getInvoices({ billingBaseUrl, token } = {}) {
+  const url = `${billingBaseUrl}/v1/billing/invoices?token=${encodeURIComponent(token)}`;
+  const response = await hubspot.fetch(url, { timeout: 10000, method: "GET" });
+  if (!response.ok) {
+    const errorText = await response.text();
+    // FastAPI errors come back as {"detail": "..."} — surface just the detail
+    // string (same convention as callAppApi).
+    let message = errorText;
+    try {
+      const parsed = JSON.parse(errorText);
+      if (parsed && typeof parsed.detail === "string") {
+        message = parsed.detail;
+      }
+    } catch {
+      // body wasn't JSON; keep the raw text
+    }
+    throw new AppApiError(message, response.status, errorText);
+  }
+  return response.json();
+}
+
 // 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

package/src/sdk/index.js

@@ -4,7 +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 { getTopUps, getInvoices, setBillingLimit } from "./app/topUps";
 export { getSettings, updateSettings, makeSettingsApi } from "./app/settings";
 export {
   strToBase64,