@growth-operations/ui-shared 1.19.0 → 1.21.0

package/package.json

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

package/src/alerts/AlertsTab.jsx

@@ -60,6 +60,13 @@ const LEVEL_VARIANT = {
   critical: "error",
 };
 
+// The level bubble is display copy — capitalize the backend's lowercase
+// level ("warning" -> "Warning").
+function capitalizeLevel(level) {
+  if (!level) return "";
+  return level.charAt(0).toUpperCase() + level.slice(1);
+}
+
 function DefaultAlertRow({
   context,
   alert,
@@ -86,7 +93,7 @@ function DefaultAlertRow({
     <TableRow>
       <TableCell>
         <Tag variant={LEVEL_VARIANT[alert.level] || "default"}>
-          {alert.level}
+          {capitalizeLevel(alert.level)}
         </Tag>
       </TableCell>
       <TableCell>

package/src/billing/AutoProvisionToggle.jsx

@@ -0,0 +1,139 @@
+import React, { useEffect, useReducer, useState } from "react";
+import { Alert, Button, Flex, Heading, Text, Toggle } from "@hubspot/ui-extensions";
+import {
+  AUTO_PROVISION_CONFIRM_NO,
+  AUTO_PROVISION_CONFIRM_YES,
+  AUTO_PROVISION_IDLE,
+  AUTO_PROVISION_TITLE,
+  autoProvisionConfirmBody,
+  autoProvisionReducer,
+  autoProvisionSubtext,
+} from "../lib/autoProvision";
+import { setAutoProvision } from "../sdk/app/topUps";
+
+// "Add Additional Credits Automatically" — the auto-provision toggle on the
+// Billing tab (REPLACES the old billing-limit control). ON (the default) buys
+// another pack of additional credits when monthly credits run out; OFF means
+// no purchase and workflow actions start failing the entitlement gate.
+//
+// The ON→OFF direction is dangerous, so it parks in an inline confirmation
+// panel (Andrew's exact copy + buttons) instead of saving on click; OFF→ON
+// saves immediately — no confirmation to turn protection back ON. The flow
+// itself is a unit-tested reducer (../lib/autoProvision); this component is
+// the wiring: controlled Toggle + the POST to the base service's
+// /v1/hubspot/app_pages/{app}/billing/auto-provision (see setAutoProvision).
+//
+// Props:
+//   context            — the UI-extension serverless context
+//                        (context.portal.id).
+//   appKey             — the billing app_key for THIS app.
+//   enabled            — the resolved flag (resolveAutoProvision; true when
+//                        the state.auto_provision block is absent).
+//   appName            — display name templated into the copy.
+//   billingActionToken — the (interval-refreshed)
+//                        state.billing_action_tokens.portal. Without it the
+//                        toggle stays read-only — the same "hidden/disabled
+//                        until token exists" posture as the other billing
+//                        controls.
+export function AutoProvisionToggle({
+  context,
+  appKey,
+  enabled: enabledProp,
+  appName = "this app",
+  billingActionToken = null,
+}) {
+  const [enabled, setEnabled] = useState(enabledProp !== false);
+  const [ui, dispatch] = useReducer(autoProvisionReducer, AUTO_PROVISION_IDLE);
+
+  // The flag arrives with /v1/home; adopt a changed server-side value (the
+  // payload refetches after install/refresh).
+  useEffect(() => {
+    setEnabled(enabledProp !== false);
+  }, [enabledProp]);
+
+  const ready = !!billingActionToken;
+  const busy = ui.phase === "saving";
+
+  const save = async (next) => {
+    try {
+      await setAutoProvision(context, {
+        appKey,
+        portalId: context?.portal?.id,
+        token: billingActionToken,
+        enabled: next,
+      });
+      setEnabled(next);
+      dispatch({ type: "saved" });
+    } catch (e) {
+      dispatch({
+        type: "failed",
+        message: e?.message ?? "Couldn't update automatic credit provisioning.",
+      });
+    }
+  };
+
+  const onToggle = (checked) => {
+    if (!ready || busy) return;
+    dispatch({ type: "request", enabled: checked });
+    if (checked) save(true); // turning protection back ON needs no confirmation
+  };
+
+  return (
+    <Flex direction="column" gap="small">
+      <Heading>{AUTO_PROVISION_TITLE}</Heading>
+      <Text>{autoProvisionSubtext(appName)}</Text>
+      <Toggle
+        label={AUTO_PROVISION_TITLE}
+        labelDisplay="hidden"
+        name="auto-provision"
+        checked={enabled}
+        readOnly={!ready || busy}
+        onChange={onToggle}
+      />
+      {!ready && (
+        <Text variant="microcopy">
+          Preparing billing… this control unlocks in a moment. Refresh the page
+          if this persists.
+        </Text>
+      )}
+
+      {/* The ON→OFF confirmation (the toggle stays checked while this is up;
+          cancel snaps back to idle with the flag untouched). */}
+      {ui.phase === "confirming" && (
+        <Alert variant="warning" title="Disable automatic credit provisioning?">
+          <Flex direction="column" gap="small">
+            <Text>{autoProvisionConfirmBody(appName)}</Text>
+            <Flex direction="row" gap="small">
+              <Button
+                variant="destructive"
+                onClick={() => {
+                  dispatch({ type: "confirm" });
+                  save(false);
+                }}
+              >
+                {AUTO_PROVISION_CONFIRM_YES}
+              </Button>
+              <Button
+                variant="secondary"
+                onClick={() => dispatch({ type: "cancel" })}
+              >
+                {AUTO_PROVISION_CONFIRM_NO}
+              </Button>
+            </Flex>
+          </Flex>
+        </Alert>
+      )}
+
+      {ui.notice && (
+        <Alert
+          variant={ui.notice.variant}
+          title={ui.notice.variant === "success" ? "Saved" : "Couldn't save"}
+        >
+          <Text>{ui.notice.text}</Text>
+        </Alert>
+      )}
+    </Flex>
+  );
+}
+
+export default AutoProvisionToggle;

package/src/billing/BillingTab.jsx

@@ -7,7 +7,6 @@ import {
   LoadingButton,
   Button,
   Alert,
-  Input,
   Link,
   LoadingSpinner,
   Table,
@@ -18,12 +17,13 @@ import {
   TableCell,
 } from "@hubspot/ui-extensions";
 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 { AutoProvisionToggle } from "./AutoProvisionToggle";
+import { resolveAutoProvision } from "../lib/autoProvision";
 import { refreshBillingActionTokens } from "../sdk/billing";
-import { getInvoices, getTopUps, setBillingLimit } from "../sdk/app/topUps";
+import { getInvoices } 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
@@ -393,91 +393,6 @@ function TrialSubscriptionBilling({ 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>
-  );
-}
-
 // Invoice status -> label (Stripe's vocabulary: paid / open / void /
 // uncollectible; drafts and $0 voids are filtered server-side).
 const INVOICE_STATUS_LABELS = {
@@ -527,10 +442,13 @@ export function InvoiceHistoryTable({ invoices }) {
 }
 
 // "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.
+// (subscription renewals, one-off charges, additional-credit purchases —
+// including VOIDED top-ups, which tell the decline story), from the billing
+// service's GET /v1/billing/invoices (newest first, capped at 24). This is
+// the one purchase history surface now — the old Top-Up History section is
+// gone (Andrew's 2026-10 feedback); the base service keeps its deprecated
+// GET billing/top-ups empty-list stub so OLD released clients degrade
+// silently.
 //
 // 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
@@ -586,8 +504,8 @@ function InvoiceHistory({ billingBaseUrl, billingActionToken }) {
       <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.
+          No invoices yet. Subscription renewals, one-off charges, and
+          additional-credit purchases are listed here.
         </Text>
       ) : (
         <InvoiceHistoryTable invoices={invoices} />
@@ -596,143 +514,6 @@ function InvoiceHistory({ billingBaseUrl, billingActionToken }) {
   );
 }
 
-// "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;
@@ -817,8 +598,8 @@ export function CreditsBilling({ context, state, appKey, openIframe = null }) {
             sections (the safe direction — no dead UI). */}
         {state?.entitlement?.billing_model === "topup" && (
           <>
-            <TopUpHistory context={context} appKey={appKey} />
-            {/* Directly below Top-up history (Andrew's ask). `state` here is
+            {/* Invoice history is the one purchase list now (Top-Up History
+                is deleted — Andrew's 2026-10 feedback). `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. */}
@@ -826,13 +607,16 @@ export function CreditsBilling({ context, state, appKey, openIframe = null }) {
               billingBaseUrl={base}
               billingActionToken={state?.billing_action_tokens?.portal ?? null}
             />
-            <BillingLimitControl
+            {/* "Add Additional Credits Automatically" — REPLACES the old
+                billing-limit control. The flag resolves from
+                state.auto_provision (default ON); the ON→OFF direction parks
+                in Andrew's exact confirmation copy. */}
+            <AutoProvisionToggle
               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`
+              enabled={resolveAutoProvision(state?.auto_provision).enabled}
+              appName={state?.app?.name ?? "this app"}
+              // The POST's second auth dep (see setAutoProvision). `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.

package/src/home/AppHome.jsx

@@ -4,7 +4,10 @@ import { InstallProgress } from "./InstallProgress";
 import { HealthHero } from "./HealthHero";
 import { OnboardingChecklist } from "./OnboardingChecklist";
 import { SyncPulse } from "./SyncPulse";
-import { CreditMeter } from "./CreditMeter";
+import { FeatureUsage } from "./FeatureUsage";
+import { TrialBanner } from "./TrialBanner";
+import { PlanFitBanner } from "./PlanFitBanner";
+import { PeriodComparison } from "./PeriodComparison";
 import { FeatureNudges } from "./FeatureNudges";
 import { HelpfulLinks } from "./HelpfulLinks";
 
@@ -44,17 +47,11 @@ function PipelineTile({ pipeline }) {
 }
 
 // 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.
+// sync_pulse -> SyncPulse; pipeline -> PipelineTile. The credit meter is
+// deliberately NOT on Home anymore (Andrew's 2026-10 feedback) — it lives at
+// the top of the Usage tab; Home's credit story is the trial banner plus the
+// post-checklist period comparison. Renders nothing when no tile applies.
 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;
@@ -66,9 +63,17 @@ function ArchetypeTile({ state }) {
 // Lifecycle composition:
 //   no state            -> LoadingSpinner (still fetching /v1/home)
 //   activation pending  -> <InstallProgress> (install isn't finished yet)
-//   activated cockpit   -> <HealthHero>
+//   activated cockpit   -> <TrialBanner> (credit apps on the free grant)
+//                          + <HealthHero> (+ "...on the right plan" when
+//                            plan_fit says so)
+//                          + <PlanFitBanner> (upgrade_recommended only)
 //                          + <OnboardingChecklist> (only if not complete)
-//                          + the archetype activity tile (sync/credit/pipeline)
+//                          + the archetype activity tile (sync/pipeline)
+//                          + <PeriodComparison> (post-checklist, when the
+//                            backend has a full closed period)
+//                          + <FeatureUsage> (once the non-billing setup steps
+//                            are done; needs the backend's state.feature_usage
+//                            block)
 //                          + <FeatureNudges>
 //
 // Props:
@@ -111,20 +116,53 @@ export function AppHome({ state, onNavigate, appName, onRetry, helpfulLinks }) {
 
   const onboardingComplete = state.onboarding?.complete === true;
 
+  // FeatureUsage gate: render once every NON-BILLING onboarding step is done.
+  // Every registry app marks its Choose-a-plan step paid-gated (key "plan",
+  // routing to /billing, done only once the subscription is ACTIVE), so gating
+  // on onboarding.complete would hide these sections from free/trial installs
+  // forever — exactly the audience "Recommended to explore" is for. A fresh
+  // install still has its install/workflow steps open, so setup comes first.
+  // With no step model (older backends), fall back to the block-level flag.
+  const isBillingStep = (s) => s?.key === "plan" || s?.cta_route === "/billing";
+  const onboardingSteps = state.onboarding?.steps;
+  const setupStepsComplete =
+    Array.isArray(onboardingSteps) && onboardingSteps.length > 0
+      ? onboardingSteps.every((s) => s.done === true || isBillingStep(s))
+      : onboardingComplete;
+
   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} />
 
+      {/* Trial states (active countdown / ended / out of credits) fly above
+          the hero — they're the strongest call to action a free account
+          has. Renders null for paid plans and non-credits modes. */}
+      <TrialBanner state={state} appName={appName} />
+
       <HealthHero appName={appName} state={state} />
 
+      {/* plan_fit upgrade_recommended — the savings banner. */}
+      <PlanFitBanner state={state} />
+
       {state.onboarding && !onboardingComplete && (
         <OnboardingChecklist onboarding={state.onboarding} onNavigate={onNavigate} />
       )}
 
       <ArchetypeTile state={state} />
 
+      {/* Post-checklist: the period-over-period comparison (null until the
+          install has one full closed period). */}
+      {onboardingComplete && <PeriodComparison state={state} />}
+
+      {/* Most used / recommended-to-explore (state.feature_usage) — renders
+          nothing on backends without the block or for legacy installs. Gated
+          on the non-billing setup steps (NOT the paid-gated plan step) so a
+          fresh install sees setup first but free/trial installs aren't
+          locked out. */}
+      {setupStepsComplete && <FeatureUsage state={state} />}
+
       <FeatureNudges nudges={state.nudges} onNavigate={onNavigate} />
 
       {helpfulLinksEl}