@growth-operations/ui-shared 1.13.2 → 1.15.0

package/package.json

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

package/src/billing/BillingBanner.jsx

@@ -0,0 +1,88 @@
+import React from "react";
+import { Flex, Text, Alert, Button } from "@hubspot/ui-extensions";
+
+// 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.
+//
+// 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.
+//
+// Props:
+//   state       — the /v1/home payload (entitlement union). Renders nothing
+//                 outside the credits archetype or before install completes.
+//   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".
+//   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;
+
+  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.`,
+    };
+  }
+
+  if (!banner) return null;
+
+  return (
+    <Alert title={banner.title} variant={banner.variant}>
+      <Flex direction="column" gap="extra-small">
+        <Text>{banner.message}</Text>
+        {onNavigate && (
+          <Button variant="secondary" onClick={() => onNavigate("/billing")}>
+            Go to Billing →
+          </Button>
+        )}
+      </Flex>
+    </Alert>
+  );
+}
+
+export default BillingBanner;

package/src/billing/BillingTab.jsx

@@ -122,6 +122,27 @@ function StatusPanel({ entitlement }) {
   }
 
   if (status === "active") {
+    // Scheduled-cancel (cancel_at_period_end) is a WARNING, not a success:
+    // access ends at the period boundary unless the customer acts. The "Keep
+    // my subscription" button lives beside this panel (TrialSubscriptionBilling
+    // has the billing_base_url + restart token; StatusPanel only sees the
+    // entitlement).
+    if (cancel_at_period_end) {
+      return (
+        <Alert variant="warning">
+          <Flex direction="column" gap="extra-small">
+            <Text format={{ fontWeight: "bold" }}>
+              Your subscription is set to cancel
+            </Text>
+            <Text>
+              It stays active until {fmtDate(current_period_end)}, then your
+              data stops syncing. Changed your mind? Keep it below — no
+              re-checkout needed.
+            </Text>
+          </Flex>
+        </Alert>
+      );
+    }
     return (
       <Alert variant="success">
         <Flex direction="column" gap="extra-small">
@@ -130,11 +151,6 @@ function StatusPanel({ entitlement }) {
             Your subscription is active. Next renewal:{" "}
             {fmtDate(current_period_end)}.
           </Text>
-          {cancel_at_period_end && (
-            <Text format={{ fontStyle: "italic" }}>
-              Cancels at the end of the current period.
-            </Text>
-          )}
         </Flex>
       </Alert>
     );
@@ -182,7 +198,7 @@ function StatusPanel({ entitlement }) {
     const resumeCta =
       mode === "credits"
         ? "Choose a plan below to start a new subscription."
-        : "Choose a plan below to start a new subscription and resume syncing your data.";
+        : "Restart your previous plan below in one click, or choose a different one — either way your data starts syncing again.";
     return (
       <Alert variant="warning">
         <Flex direction="column" gap="extra-small">
@@ -245,6 +261,20 @@ function TrialSubscriptionBilling({ context, state, appKey, openIframe = null })
         `&return_url=${encodeURIComponent(returnUrl)}`
       : null;
 
+  // "Keep my subscription" for a sub flagged cancel_at_period_end: hits
+  // /v1/billing/restart/start with NO price_id — the uncancel branch flips the
+  // flag off in place (the one true resume Stripe supports) and 303s back
+  // here. Null (button hidden, not disabled) until the restart token exists —
+  // an older backend that doesn't mint it simply doesn't show the button; the
+  // Stripe portal still offers the same renewal as a fallback.
+  const restartToken = state?.billing_action_tokens?.restart ?? null;
+  const keepSubscriptionUrl =
+    base && restartToken
+      ? `${base}/v1/billing/restart/start` +
+        `?token=${encodeURIComponent(restartToken)}` +
+        `&return_url=${encodeURIComponent(returnUrl)}`
+      : null;
+
   // Tier picker — every status needs ONE of two distinct modes, never both:
   //   trialing                    -> UPGRADE mode: a trialing sub already
   //     exists, so a higher-tier click swaps its item in place
@@ -261,8 +291,8 @@ function TrialSubscriptionBilling({ context, state, appKey, openIframe = null })
   // (upgrade) or doesn't (checkout) — showing the upgrade endpoint with no
   // real subscription behind it would 404/error at click time.
   const isTrialing = ent.status === "trialing";
-  const needsCheckout =
-    ent.status === "pending_purchase" || ent.status === "canceled";
+  const isCanceled = ent.status === "canceled";
+  const needsCheckout = ent.status === "pending_purchase" || isCanceled;
   const plans = state?.plans ?? [];
   const currentOrder = isTrialing
     ? plans.find((p) => p.current)?.tier_order
@@ -291,6 +321,16 @@ function TrialSubscriptionBilling({ context, state, appKey, openIframe = null })
 
       <StatusPanel entitlement={state?.entitlement} />
 
+      {/* Scheduled-cancel on an ACTIVE sub: one click flips
+          cancel_at_period_end off in place (no re-checkout, no new sub) —
+          the /v1/billing/restart/start uncancel branch. Rendered only when
+          the restart token exists (see keepSubscriptionUrl above). */}
+      {ent.status === "active" && ent.cancel_at_period_end && keepSubscriptionUrl && (
+        <Button href={{ url: keepSubscriptionUrl, external: true }} variant="primary">
+          Keep my subscription
+        </Button>
+      )}
+
       <Text format={{ fontStyle: "italic" }}>
         {needsCheckout
           ? "Choose a plan below to resume. Once you have an active subscription, use the link above to manage payment methods or view invoices."
@@ -313,12 +353,27 @@ function TrialSubscriptionBilling({ context, state, appKey, openIframe = null })
           currentOrder={currentOrder}
           endpoint={needsCheckout ? "checkout/start" : "upgrade/start"}
           ctaLabel={needsCheckout ? "Choose" : "Upgrade to"}
-          heading={needsCheckout ? "Choose a plan to resume" : "Your plan"}
+          heading={
+            isCanceled
+              ? "Resume your subscription"
+              : needsCheckout
+                ? "Choose a plan to resume"
+                : "Your plan"
+          }
           footnote={
-            needsCheckout
-              ? "Choose a plan to start a new subscription and resume syncing your data."
-              : "Upgrade any time during your trial — your trial end date stays the same, and the new tier applies when it converts. To move to a lower tier, talk to sales."
+            isCanceled
+              ? "Restart charges your card on file and resumes syncing immediately — no checkout page. If the card needs updating, we'll send you to Stripe to finish. You can also switch to a different plan or billing interval."
+              : needsCheckout
+                ? "Choose a plan to start a new subscription and resume syncing your data."
+                : "Upgrade any time during your trial — your trial end date stays the same, and the new tier applies when it converts. To move to a lower tier, talk to sales."
           }
+          // Canceled only: the account's last tier is still stamped
+          // `current` (account.plan persists after cancel), so its card
+          // becomes the one-click "Restart <plan>" CTA (/v1/billing/
+          // restart/start — recreate off-session on the saved card, with a
+          // hosted-Checkout fallback server-side) instead of a disabled
+          // "Current plan" marker. Other tiers stay plain checkout.
+          resumeCurrentPlan={isCanceled}
           openIframe={openIframe}
         />
       )}

package/src/billing/PlanGrid.jsx

@@ -72,6 +72,17 @@ function PlanCard({
   // can't read whether the external meetings page is CSP-frameable, so the modal
   // is best-effort; the href fallback always works.
   openIframe = null,
+  // Canceled-account checkout grid (BillingTab passes this only for status
+  // "canceled"): the account's LAST tier is still stamped plan.current, so its
+  // card becomes the one-click "Restart <plan>" CTA targeting
+  // /v1/billing/restart/start (off-session recreate on the saved card, hosted
+  // Checkout fallback server-side) instead of the disabled "Current plan"
+  // marker, and the tag reads "Previous plan". The card's interval toggle stays
+  // live — restarting onto the OTHER interval is a legitimate switch (the old
+  // sub is gone; there is no in-place swap, so isIntervalSwitch is suppressed
+  // in this mode). If the backend doesn't mint a restart token (older common),
+  // the card degrades to the plain checkout CTA — same recovery, one extra page.
+  resumeCurrentPlan = false,
 }) {
   // Default this card to annual when it offers annual (cheaper-per-month story);
   // monthly-only tiers default to monthly. Both legs → show the toggle. The
@@ -107,10 +118,17 @@ function PlanCard({
   // a downgrade card is fully read-only.
   const canToggle = hasMonthly && hasAnnual && !isDowngrade;
   const [interval, setInterval] = useState(defaultInterval);
+  // Resume mode (canceled account): this card IS the restart CTA. The old
+  // subscription is gone, so the in-place interval-switch concept doesn't
+  // apply — toggling the interval just picks which price the restart creates.
+  // talk_to_sales tiers are excluded: they have no price to restart onto
+  // (custom pricing goes through sales regardless of account state).
+  const isResumeCard = resumeCurrentPlan && plan.current && !plan.talk_to_sales;
   // On the current card, toggling to a DIFFERENT interval than what's actually
   // billed is the in-place monthly<->annual switch; toggling back to the same
   // interval (or current_interval being unknown) is just "Current plan".
   const isIntervalSwitch =
+    !isResumeCard &&
     plan.current &&
     plan.current_interval != null &&
     ((interval === "annual" && plan.current_interval !== "year") ||
@@ -168,6 +186,20 @@ function PlanCard({
         `&return_url=${encodeURIComponent(returnUrl ?? "")}`
       : null;
 
+  // Resume mode: the restart endpoint recreates the canceled sub off-session
+  // on the card on file (falling back to hosted Checkout server-side when
+  // there's no usable card) — so this card's CTA can ALWAYS point at
+  // restart/start; the degradation when the backend predates the restart
+  // action is just the plain checkout CTA below.
+  const restartToken = billingActionTokens?.restart ?? null;
+  const restartUrl =
+    isResumeCard && billingBaseUrl && restartToken && leg?.price_id
+      ? `${billingBaseUrl}/v1/billing/restart/start` +
+        `?token=${encodeURIComponent(restartToken)}` +
+        `&price_id=${encodeURIComponent(leg.price_id)}` +
+        `&return_url=${encodeURIComponent(returnUrl ?? "")}`
+      : null;
+
   const features = plan.features ?? [];
   // Align the CTA buttons across cards. HubSpot's column Flex does NOT stretch
   // to the Tile height (AutoGrid equalizes the card height but flex={1}/justify
@@ -184,7 +216,9 @@ function PlanCard({
         <Flex direction="row" gap="small" align="center">
           <Heading>{plan.name ?? plan.tier}</Heading>
           {plan.current && (
-            <StatusTag variant="success">Current plan</StatusTag>
+            <StatusTag variant={isResumeCard ? "default" : "success"}>
+              {isResumeCard ? "Previous plan" : "Current plan"}
+            </StatusTag>
           )}
         </Flex>
 
@@ -239,7 +273,36 @@ function PlanCard({
             (lower than current, trial picker) => disabled + Talk-to-sales (not
             self-serve). talk_to_sales tier => contact link. Otherwise
             pre-create-then-link checkout/upgrade for the selected interval. */}
-        {plan.current && !isIntervalSwitch ? (
+        {isResumeCard && restartUrl ? (
+          // One-click restart: recreate the canceled sub on the saved card
+          // (off-session) via /v1/billing/restart/start — no checkout page.
+          // The selected interval's price is what gets restarted onto.
+          <Button
+            href={{ url: restartUrl, external: true }}
+            variant="primary"
+          >
+            Restart {plan.name ?? plan.tier}
+          </Button>
+        ) : isResumeCard && !restartUrl && !leg ? (
+          // Resume mode but no price for the selected interval and no restart
+          // URL to fall back on — same guidance as the generic no-leg case.
+          <Text format={{ fontStyle: "italic" }}>
+            Not available {interval === "annual" ? "annually" : "monthly"}
+          </Text>
+        ) : isResumeCard && !restartUrl ? (
+          // Backend predates the restart action (no restart token minted) —
+          // degrade to the plain checkout CTA; same recovery, one extra page.
+          <Button
+            href={startUrl ? { url: startUrl, external: true } : undefined}
+            disabled={!startUrl}
+            variant="primary"
+          >
+            {ctaLabel} {plan.name ?? plan.tier}
+          </Button>
+        ) : plan.current && !isIntervalSwitch && !resumeCurrentPlan ? (
+          // Inert "Current plan" marker — suppressed in resume mode, where a
+          // canceled account's previous tier must stay actionable (restart
+          // above, checkout fallback, or Talk-to-sales for custom tiers).
           <Button disabled>Current plan</Button>
         ) : plan.current && isIntervalSwitch ? (
           <Button
@@ -335,6 +398,11 @@ export function PlanGrid({
   // actions.openIframeModal (from the hosting card root) — lets a talk_to_sales
   // tier open its meetings_url scheduler in an in-card modal. Optional.
   openIframe = null,
+  // Canceled-account grid (BillingTab, status "canceled" only): the account's
+  // last tier (still stamped `current`) renders as a one-click "Restart
+  // <plan>" CTA via /v1/billing/restart/start instead of the disabled
+  // "Current plan" marker. See PlanCard.
+  resumeCurrentPlan = false,
 }) {
   const plans = plansOverride ?? state?.plans ?? [];
 
@@ -377,6 +445,7 @@ export function PlanGrid({
             ctaLabel={ctaLabel}
             currentOrder={currentOrder}
             openIframe={openIframe}
+            resumeCurrentPlan={resumeCurrentPlan}
           />
         ))}
       </AutoGrid>

package/src/index.js

@@ -17,6 +17,7 @@ export { HelpfulLinks } from "./home/HelpfulLinks";
 // Billing.
 export { BillingTab } from "./billing/BillingTab";
 export { PlanGrid } from "./billing/PlanGrid";
+export { BillingBanner } from "./billing/BillingBanner";
 
 // Alerts — the shared customer alerts table (level filter, sort, dismiss).
 export { AlertsTab } from "./alerts/AlertsTab";

package/src/sdk/billing.js

@@ -11,8 +11,8 @@
 // token these endpoints don't expect).
 import { hubspot, logger } from "@hubspot/ui-extensions";
 
-// Re-mint a fresh { portal, checkout, upgrade } token set from a still-valid
-// one. See billing.py's /v1/billing/refresh-tokens: it verifies `token`
+// Re-mint a fresh { portal, checkout, upgrade, restart } token set from a
+// still-valid one. See billing.py's /v1/billing/refresh-tokens: it verifies `token`
 // (whichever action it authorizes — BillingTab always holds/passes `portal`)
 // and returns a brand-new set signed for the same app_key/portal_id. Throws
 // on a 401 (token already expired) — the caller's next /v1/home load is the