@growth-operations/ui-shared 1.6.14 → 1.6.16

package/package.json

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

package/src/billing/BillingTab.jsx

@@ -117,10 +117,17 @@ function StatusPanel({ entitlement }) {
   }
 
   if (status === "pending_purchase") {
+    // No active subscription — has_payment_method describes a CARD on file
+    // (from a prior/lapsed sub), not whether one's usable here: there's
+    // nothing for it to auto-charge. So unlike `trialing` (where a card on
+    // file means "nothing to do"), every pending_purchase account needs the
+    // SAME next step — pick a plan below — the copy just says so plainly
+    // rather than repeating the stale "add a payment method" ask when a
+    // card may already exist.
     const resumeCta =
       mode === "credits"
-        ? "Choose a plan in Stripe to resume."
-        : "Add a payment method in Stripe to resume syncing your data.";
+        ? "Choose a plan below to resume."
+        : "Choose a plan below to resume syncing your data.";
     return (
       <Alert variant="warning">
         <Flex direction="column" gap="extra-small">
@@ -131,6 +138,21 @@ function StatusPanel({ entitlement }) {
     );
   }
 
+  if (status === "canceled") {
+    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.";
+    return (
+      <Alert variant="warning">
+        <Flex direction="column" gap="extra-small">
+          <Text format={{ fontWeight: "bold" }}>Your subscription was canceled</Text>
+          <Text>{resumeCta}</Text>
+        </Flex>
+      </Alert>
+    );
+  }
+
   return (
     <Tile>
       <Text format={{ fontWeight: "bold" }}>Status: {status ?? "Unknown"}</Text>
@@ -166,45 +188,63 @@ function TrialSubscriptionBilling({ context, state, appKey, openIframe = null })
   // OPENED TAB. No in-iframe portal-session fetch (that round trip hit the billing
   // service's cold-start/CPU stall → the iframe's 15s "Gateway took too long").
   // Same pattern as the credits arm + PlanGrid's /checkout/start. null (button
-  // disabled) until billing_base_url is known.
+  // disabled) until billing_base_url + the signed action token are both known.
+  // The endpoint no longer accepts a bare app_key/portal_id (that was an
+  // unauthenticated portal-hijack vector) — it requires the `token` the app's
+  // own /v1/home minted with its client_secret (state.billing_action_tokens).
   const base = state?.billing_base_url ?? null;
   const portalId = context?.portal?.id;
+  const portalToken = state?.billing_action_tokens?.portal ?? null;
   const returnUrl = state?.app_id
     ? `https://app.hubspot.com/app/${portalId}/${state.app_id}/billing`
     : "https://app.hubspot.com/";
   const portalStartUrl =
-    base && appKey && portalId
+    base && portalToken
       ? `${base}/v1/billing/portal/start` +
-        `?app_key=${encodeURIComponent(appKey)}` +
-        `&portal_id=${encodeURIComponent(String(portalId))}` +
+        `?token=${encodeURIComponent(portalToken)}` +
         `&return_url=${encodeURIComponent(returnUrl)}`
       : null;
 
-  // Tier picker — shown ONLY while trialing (the lifecycle: trial starts on the
-  // entry tier at install; while trialing the customer may upgrade to a higher
-  // tier in-app; once active, plan changes go through support). We show the FULL
-  // ladder for context so the customer sees where they sit:
-  //   current tier  -> "Current plan" (disabled marker; PlanCard keys off
-  //                    plan.current, stamped server-side on the account's tier).
-  //   higher tiers  -> the actionable upgrade (CTA targets /v1/billing/upgrade/
-  //                    start, swapping the trialing sub's item — no new sub).
-  //   lower tiers   -> shown disabled with a Talk-to-sales CTA (downgrades aren't
-  //                    self-serve). PlanCard derives this from currentOrder.
+  // 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
+  //     (/v1/billing/upgrade/start) rather than starting a second
+  //     subscription. Lower tiers show disabled (Talk-to-sales; downgrades
+  //     aren't self-serve). currentOrder is REQUIRED here so PlanCard can
+  //     tell upgrade from downgrade.
+  //   pending_purchase / canceled -> CHECKOUT mode: there is NO active
+  //     subscription to swap — every tier is a genuinely fresh purchase
+  //     (/v1/billing/checkout/start, PlanGrid's default). currentOrder is
+  //     intentionally omitted (undefined) so no tier reads as a downgrade;
+  //     with nothing active, every tier is just a plan to start.
+  // Never both at once: a customer either has a subscription to adjust
+  // (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 plans = state?.plans ?? [];
-  const currentOrder = plans.find((p) => p.current)?.tier_order;
-  // Render the picker only while trialing AND once we know the current tier
-  // (currentOrder drives upgrade-vs-downgrade per card).
-  const showPicker = isTrialing && currentOrder != null && plans.length > 0;
+  const currentOrder = isTrialing
+    ? plans.find((p) => p.current)?.tier_order
+    : undefined;
+  // Trialing: only once we know the current tier (currentOrder drives
+  // upgrade-vs-downgrade per card). Checkout: as soon as there's a catalog
+  // to pick from — there's no "current tier" gate to wait on.
+  const showPicker =
+    (isTrialing && currentOrder != null && plans.length > 0) ||
+    (needsCheckout && plans.length > 0);
 
   return (
     <Flex direction="column" gap="medium">
-      {/* PRIMARY CTA at the top. Direct external link to the billing-service
-          redirect (opens a new tab); no in-iframe pre-create fetch. */}
+      {/* PRIMARY CTA when there's an existing subscription to manage
+          (trialing/active/past_due). For pending_purchase/canceled there is
+          nothing for the Stripe Customer Portal to manage — the plan picker
+          below is the actual recovery path, so this becomes a secondary
+          link rather than the primary action. */}
       <LoadingButton
         href={portalStartUrl ? { url: portalStartUrl, external: true } : undefined}
         disabled={!portalStartUrl}
-        variant="primary"
+        variant={needsCheckout ? "secondary" : "primary"}
       >
         {portalStartUrl ? "Manage billing in Stripe" : "Preparing billing…"}
       </LoadingButton>
@@ -212,15 +252,18 @@ function TrialSubscriptionBilling({ context, state, appKey, openIframe = null })
       <StatusPanel entitlement={state?.entitlement} />
 
       <Text format={{ fontStyle: "italic" }}>
-        Billing is managed in Stripe across all Growth Operations apps. Use the
-        link above to update your plan, payment method, or view invoices.
+        {needsCheckout
+          ? "Choose a plan below to resume. Once you have an active subscription, use the link above to manage payment methods or view invoices."
+          : "Billing is managed in Stripe across all Growth Operations apps. Use the link above to update your plan, payment method, or view invoices."}
       </Text>
 
-      {/* Trial-only tier ladder: current (marked), higher (upgradeable), lower
-          (disabled, Talk-to-sales). Hidden once active. Upgrading swaps the
-          trialing sub onto the higher tier, keeping the trial end date. The full
-          `plans` list is passed; PlanCard decides each card's state from
-          plan.current + currentOrder. */}
+      {/* Trialing: current (marked), higher (upgradeable), lower (disabled,
+          Talk-to-sales) — upgrading swaps the trialing sub onto the higher
+          tier, keeping the trial end date. pending_purchase/canceled: every
+          tier plain-actionable (fresh checkout, PlanGrid's default props/
+          endpoint) — no currentOrder means PlanCard never marks a downgrade.
+          The full `plans` list is passed either way; PlanCard decides each
+          card's state from plan.current + currentOrder. */}
       {showPicker && (
         <PlanGrid
           context={context}
@@ -228,10 +271,14 @@ function TrialSubscriptionBilling({ context, state, appKey, openIframe = null })
           appKey={appKey}
           plans={plans}
           currentOrder={currentOrder}
-          endpoint="upgrade/start"
-          ctaLabel="Upgrade to"
-          heading="Your plan"
-          footnote="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."
+          endpoint={needsCheckout ? "checkout/start" : "upgrade/start"}
+          ctaLabel={needsCheckout ? "Choose" : "Upgrade to"}
+          heading={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."
+          }
           openIframe={openIframe}
         />
       )}
@@ -248,17 +295,18 @@ function CreditsBilling({ context, state, appKey, openIframe = null }) {
   // (that round trip hit the billing service's cold-start/CPU stall and surfaced
   // as the iframe's 15s "Gateway took too long" error). Same pattern as
   // PlanGrid's /checkout/start "Choose" button. null (button disabled) until
-  // billing_base_url is known.
+  // billing_base_url + the signed action token are both known — the endpoint no
+  // longer accepts a bare app_key/portal_id (state.billing_action_tokens).
   const base = state?.billing_base_url ?? null;
   const portalId = context?.portal?.id;
+  const portalToken = state?.billing_action_tokens?.portal ?? null;
   const returnUrl = state?.app_id
     ? `https://app.hubspot.com/app/${portalId}/${state.app_id}/billing`
     : "https://app.hubspot.com/";
   const portalStartUrl =
-    base && appKey && portalId
+    base && portalToken
       ? `${base}/v1/billing/portal/start` +
-        `?app_key=${encodeURIComponent(appKey)}` +
-        `&portal_id=${encodeURIComponent(String(portalId))}` +
+        `?token=${encodeURIComponent(portalToken)}` +
         `&return_url=${encodeURIComponent(returnUrl)}`
       : null;
 

package/src/billing/PlanGrid.jsx

@@ -49,8 +49,7 @@ import { fmtMoney } from "../lib/format";
 function PlanCard({
   plan,
   billingBaseUrl,
-  appKey,
-  portalId,
+  billingActionTokens,
   returnUrl,
   supportUrl,
   maxFeatures = 0,
@@ -137,19 +136,25 @@ function PlanCard({
       : 0;
 
   // Direct one-click link to the billing service's redirect endpoint. Null
-  // until we have everything (billing host, appKey, portal, this interval's
-  // price) — the button is disabled until then. The current card's in-place
-  // interval switch is ALWAYS upgrade/start (swap the existing sub's item),
-  // regardless of what `endpoint` this grid instance was given — it can never
-  // be a first-time checkout/start, since plan.current + a real
-  // current_interval only happens with an existing subscription already in
-  // place. Getting this wrong would double-bill (a second Checkout session).
+  // until we have everything (billing host, a signed token for the target
+  // action, this interval's price) — the button is disabled until then. The
+  // current card's in-place interval switch is ALWAYS upgrade/start (swap the
+  // existing sub's item), regardless of what `endpoint` this grid instance was
+  // given — it can never be a first-time checkout/start, since plan.current +
+  // a real current_interval only happens with an existing subscription already
+  // in place. Getting this wrong would double-bill (a second Checkout session).
+  // The endpoint no longer accepts a bare app_key/portal_id (unauthenticated
+  // portal-hijack vector) — it requires the `token` the app's own /v1/home
+  // minted with its client_secret (billingActionTokens), keyed by ACTION
+  // ("checkout" or "upgrade") since a single card's target action can differ
+  // from the grid's default via the interval-switch case above.
   const startEndpoint = isIntervalSwitch ? "upgrade/start" : endpoint;
+  const startAction = startEndpoint === "upgrade/start" ? "upgrade" : "checkout";
+  const startToken = billingActionTokens?.[startAction] ?? null;
   const startUrl =
-    billingBaseUrl && appKey && portalId && leg?.price_id
+    billingBaseUrl && startToken && leg?.price_id
       ? `${billingBaseUrl}/v1/billing/${startEndpoint}` +
-        `?app_key=${encodeURIComponent(appKey)}` +
-        `&portal_id=${encodeURIComponent(portalId)}` +
+        `?token=${encodeURIComponent(startToken)}` +
         `&price_id=${encodeURIComponent(leg.price_id)}` +
         `&return_url=${encodeURIComponent(returnUrl ?? "")}`
       : null;
@@ -322,6 +327,7 @@ export function PlanGrid({
 
   const supportUrl = state?.helpful_links?.supportUrl ?? null;
   const billingBaseUrl = state?.billing_base_url ?? null;
+  const billingActionTokens = state?.billing_action_tokens ?? null;
   const portalId = context?.portal?.id;
   // Where Stripe sends the customer back after pay/cancel — the app's Billing
   // tab. The card builds the one-click /checkout/start link from these.
@@ -348,8 +354,7 @@ export function PlanGrid({
             key={plan.tier}
             plan={plan}
             billingBaseUrl={billingBaseUrl}
-            appKey={appKey}
-            portalId={portalId}
+            billingActionTokens={billingActionTokens}
             returnUrl={returnUrl}
             supportUrl={supportUrl}
             maxFeatures={maxFeatures}

package/src/sandbox/SandboxInstall.jsx

@@ -2,24 +2,38 @@
 //
 // The one sanctioned path to a sandbox install (a customer can't self-install on
 // a sandbox from the marketplace — the backend rejects that). From a prod
-// portal, this asks the app's mint endpoint for a signed sandbox install link
-// (which carries sandbox=true + the prod customer to link), then surfaces it for
-// the user to open on their sandbox account.
+// portal, this first GETs the account's existing linked sandboxes + limit, then
+// — only when still under the limit — mints a signed sandbox install link
+// (carrying sandbox=true + the prod customer to link) THE MOMENT THE COMPONENT
+// MOUNTS, so the link is a single, ordinary click — open it on the sandbox
+// account you want to install on, no separate "generate" step first. HubSpot's
+// Link/Button href must be a static value at render time (can't be set from an
+// async result in the same click), so minting on mount rather than on click is
+// what makes one-click possible at all.
+//
+// Always shows what's already linked (previously this rendered the mint action
+// unconditionally with no signal a sandbox already existed, and a customer
+// could keep minting more with zero visibility). At the limit, shows the
+// linked list + a "X of Y used" indicator with no mint action underneath —
+// not a disabled/dead button, just nothing to click.
 //
 // Extensible per app: the caller passes the mint `path` on its OWN backend
 // (base-hosted apps -> /v1/hubspot/app_pages/... no; the install mint lives at
 // /v2/hubspot/install/{app}/sandbox-link on base; self-hosted apps serve their
-// own), plus the portalId. callAppApi targets context.variables.BASE_URL, so
-// each app's BASE_URL routes to the right service. Apps not allowlisted get a
-// 403 from the endpoint, surfaced as a calm message.
-import React, { useState } from "react";
-import { Flex, Heading, Text, Button, Link, Alert } from "@hubspot/ui-extensions";
+// own), plus the portalId. The SAME path is used for both the GET (status) and
+// POST (mint) — the backend distinguishes by HTTP method. callAppApi targets
+// context.variables.BASE_URL, so each app's BASE_URL routes to the right
+// service. Apps not allowlisted get a 403 from the endpoint, surfaced as a
+// calm message.
+import React, { useEffect, useState } from "react";
+import { Flex, Heading, Text, Link, Alert, StatusTag } from "@hubspot/ui-extensions";
 
 import { callAppApi, AppApiError } from "../sdk/app/base";
 
-// context: extension context. path: the mint endpoint on the app's backend
-// (e.g. `/v2/hubspot/install/${appKey}/sandbox-link`). portalId: the prod portal
-// minting the link. appName: copy. heading/description: optional overrides.
+// context: extension context. path: the status+mint endpoint on the app's
+// backend (e.g. `/v2/hubspot/install/${appKey}/sandbox-link`). portalId: the
+// prod portal minting the link. appName: copy. heading/description: optional
+// overrides.
 export function SandboxInstall({
   context,
   path,
@@ -28,34 +42,67 @@ export function SandboxInstall({
   heading = "Install on a sandbox",
   description,
 }) {
+  const [linkedSandboxes, setLinkedSandboxes] = useState([]);
+  const [limit, setLimit] = useState(1);
   const [installUrl, setInstallUrl] = useState(null);
-  const [loading, setLoading] = useState(false);
+  const [loading, setLoading] = useState(true);
   const [error, setError] = useState(null);
 
-  const mint = async () => {
-    setLoading(true);
-    setError(null);
-    try {
-      const pid = portalId ?? context.portal.id;
-      const sep = path.includes("?") ? "&" : "?";
-      const res = await callAppApi(context, `${path}${sep}portalId=${pid}`, "POST");
-      setInstallUrl(res?.install_url ?? null);
-    } catch (err) {
-      // The backend 403s apps that don't allow sandbox installs — show its
-      // message rather than a generic failure.
-      setError(err instanceof AppApiError ? err.message : String(err));
-    } finally {
-      setLoading(false);
-    }
-  };
+  useEffect(() => {
+    let cancelled = false;
+    (async () => {
+      try {
+        const pid = portalId ?? context.portal.id;
+        const sep = path.includes("?") ? "&" : "?";
+        const qs = `${path}${sep}portalId=${pid}`;
+        const status = await callAppApi(context, qs, "GET");
+        if (cancelled) return;
+        const linked = status?.linked_sandboxes ?? [];
+        const cap = status?.limit ?? 1;
+        setLinkedSandboxes(linked);
+        setLimit(cap);
+        // Only mint (and offer) a NEW link while still under the limit — at
+        // the limit, the linked list above is the whole story; there's
+        // nothing else to click.
+        if (linked.length < cap) {
+          const res = await callAppApi(context, qs, "POST");
+          if (!cancelled) setInstallUrl(res?.install_url ?? null);
+        }
+      } catch (err) {
+        // The backend 403s apps that don't allow sandbox installs — show its
+        // message rather than a generic failure.
+        if (!cancelled) {
+          setError(err instanceof AppApiError ? err.message : String(err));
+        }
+      } finally {
+        if (!cancelled) setLoading(false);
+      }
+    })();
+    return () => {
+      cancelled = true;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [path, portalId]);
+
+  const atLimit = linkedSandboxes.length >= limit;
 
   return (
     <Flex direction="column" gap="small">
-      <Heading>{heading}</Heading>
+      <Flex direction="row" gap="small" align="center">
+        <Heading>{heading}</Heading>
+        {!loading && !error && (
+          // At the limit is the NORMAL end state for the common case (limit
+          // defaults to 1) — reaching it isn't a problem, so this reads
+          // success/neutral either way, never a warning color.
+          <StatusTag variant="success">
+            {linkedSandboxes.length} of {limit} used
+          </StatusTag>
+        )}
+      </Flex>
       <Text>
         {description ??
           `Spin up ${appName} on a HubSpot sandbox account, linked to your billing. ` +
-            `Generate a link, then open it on the sandbox account you want to install on.`}
+            `Open the link below on the sandbox account you want to install on.`}
       </Text>
 
       {error && (
@@ -64,26 +111,36 @@ export function SandboxInstall({
         </Alert>
       )}
 
-      {installUrl ? (
+      {linkedSandboxes.length > 0 && (
+        <Flex direction="column" gap="extra-small">
+          <Text format={{ fontWeight: "bold" }}>Already linked</Text>
+          {linkedSandboxes.map((s) => (
+            <Text key={s.portal_id}>
+              {s.name || s.portal_id} — {s.status}
+            </Text>
+          ))}
+        </Flex>
+      )}
+
+      {installUrl && (
         <Flex direction="column" gap="extra-small">
           <Link href={{ url: installUrl, external: true }}>
-            Open the sandbox install →
+            Install on a sandbox →
           </Link>
           <Text variant="microcopy">
-            Clicking this link opens HubSpot's install screen for the
-            sandbox account you choose — you don't need to switch accounts
-            first.
+            Opens HubSpot's install screen for the sandbox account you
+            choose — you don't need to switch accounts first.
           </Text>
         </Flex>
-      ) : (
-        <Button
-          variant="secondary"
-          disabled={loading}
-          onClick={mint}
-        >
-          {loading ? "Generating…" : "Generate sandbox install link"}
-        </Button>
       )}
+
+      {!loading && !error && atLimit && linkedSandboxes.length > 0 && (
+        <Text variant="microcopy">
+          Need another sandbox linked? Contact us.
+        </Text>
+      )}
+
+      {loading && !error && <Text variant="microcopy">Checking your sandbox installs…</Text>}
     </Flex>
   );
 }