@growth-operations/ui-shared 1.18.0 → 1.19.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@growth-operations/ui-shared",
-  "version": "1.18.0",
+  "version": "1.19.1",
   "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

@@ -17,19 +17,25 @@ import { resolveCreditMeter } from "../lib/creditDisplay";
 // 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), color-coded by the account's depletion state: success
-//      when healthy, warning at/below the low threshold, danger when
-//      depleted (view.barVariant).
+//      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), always success: 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.
-// 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 color-coded bar.
+//      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
+//      <=50% (view.bankBarVariant). NO danger on this bar — HubSpot's
+//      ProgressBar paints the whole track red in danger, so a low gauge
+//      would read as FULL; at <=20% a warning "Running low" StatusTag rides
+//      the line instead (bank.bankLow).
+// 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).
@@ -38,7 +44,7 @@ export function CreditMeter({ entitlement, creditMeter }) {
   const view = resolveCreditMeter(entitlement, creditMeter);
   if (!view) return null;
 
-  const { granted, used, remaining, bank, tagVariant, tagLabel, barVariant, alert } = view;
+  const { granted, used, remaining, bank, tagVariant, tagLabel, poolBarVariant, bankBarVariant, alert } = view;
   const grantDaysLeft = view.grantExpiresAt ? daysUntil(view.grantExpiresAt) : null;
 
   return (
@@ -62,23 +68,28 @@ export function CreditMeter({ entitlement, creditMeter }) {
                 value={bank.poolUsed}
                 maxValue={bank.poolGrant > 0 ? bank.poolGrant : 1}
                 showPercentage={true}
-                variant={barVariant}
+                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>
+                <Flex direction="row" gap="extra-small" align="center">
+                  <Text>
+                    Additional credits (never expire): {bank.bankRemaining} of{" "}
+                    {bank.bankGranted} left
+                  </Text>
+                  {bank.bankLow && (
+                    <StatusTag variant="warning">Running low</StatusTag>
+                  )}
+                </Flex>
                 <ProgressBar
                   title={`${bank.bankRemaining} of ${bank.bankGranted} left`}
                   value={bank.bankRemaining}
                   maxValue={bank.bankGranted > 0 ? bank.bankGranted : 1}
                   showPercentage={true}
-                  variant="success"
+                  variant={bankBarVariant}
                 />
               </Flex>
             ) : (
@@ -104,7 +115,7 @@ export function CreditMeter({ entitlement, creditMeter }) {
               value={used}
               maxValue={granted > 0 ? granted : 1}
               showPercentage={true}
-              variant={barVariant}
+              variant={poolBarVariant}
             />
           </>
         )}

package/src/index.js

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

package/src/lib/creditDisplay.js

@@ -51,15 +51,43 @@ export function hasTopUpBank(ent) {
 //   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
-//   barVariant           — ProgressBar sentiment for the pool/single bar:
-//                          the tag's depletion mapping minus "info"
-//                          (ProgressBar only takes success/warning/danger;
-//                          top_up_pending is calm/positive, so success).
-//                          The bank bar is always "success" (a never-expiring
-//                          balance has no negative direction).
+//   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 <= 50%. NO danger variant:
+//     HubSpot's ProgressBar paints the WHOLE TRACK red in danger (not just
+//     the filled portion), so a low level gauge would read as a full bar
+//     (caught in Jasper's 2026-10-04 screenshot review). Urgency at <= 20%
+//     rides the "Running low" tag (bank.bankLow) instead of the bar color.
+//     danger stays on the pool bar, where near-full is the truth.
+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 <= 50 * bankGranted) return "warning";
+  return "success";
+}
 export function resolveCreditMeter(entitlement, creditMeter) {
   const ent = entitlement?.mode === "credits" ? entitlement : null;
   const meter = creditMeter ?? null;
@@ -117,6 +145,10 @@ export function resolveCreditMeter(entitlement, creditMeter) {
       poolRemaining,
       poolUsed: poolGrant - poolRemaining,
     };
+    // "Running low" tag at <= 20% of the granted total (the bar itself caps
+    // at warning — see the header block). False when the total is unknown.
+    bank.bankLow =
+      bank.bankGranted > 0 && bankRemaining * 100 <= 20 * bank.bankGranted;
   }
 
   let tagVariant;
@@ -144,12 +176,16 @@ export function resolveCreditMeter(entitlement, creditMeter) {
     tagLabel = "Healthy";
   }
 
-  // ProgressBar sentiment for the pool bar (and the no-bank single bar):
-  // color-coded by depletion — success when healthy, warning at/below the
-  // low threshold (and for the other warning-level states), danger when
-  // depleted/top-up-failed. ProgressBar has no "info" variant, so the calm
-  // top_up_pending state renders success.
-  const barVariant = tagVariant === "info" ? "success" : tagVariant;
+  // 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.
@@ -202,7 +238,8 @@ export function resolveCreditMeter(entitlement, creditMeter) {
     low,
     tagVariant,
     tagLabel,
-    barVariant,
+    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,