@growth-operations/ui-shared 1.0.9 → 1.1.0

package/package.json

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

package/src/billing/BillingTab.jsx

@@ -11,6 +11,7 @@ import {
 import { useStrictModeEffect } from "../lib/useStrictModeEffect";
 import { fmtDate, daysUntil } from "../lib/format";
 import { CreditMeter } from "../home/CreditMeter";
+import { PlanGrid } from "./PlanGrid";
 
 // The shared Billing tab for all Growth Operations apps. Branches on the
 // entitlement union (CONTRACT.md):
@@ -284,11 +285,17 @@ function TrialSubscriptionBilling({ context, state, appKey }) {
 }
 
 function CreditsBilling({ context, state, appKey }) {
-  // NOTE: the credit-pack / paid-allowance checkout backend is net-new and
-  // pending. For v1 the "Pick a plan" / "Buy credits" CTA reuses the same
-  // Stripe portal session pattern (routes to the portal); swap the endpoint to
-  // the credit checkout once that backend lands.
-  const { portalUrl, loading, error } = usePortalSession({ context, state, appKey });
+  // The Stripe portal session lets an EXISTING paid customer manage their plan
+  // / payment method / invoices (same pattern as the trial arm). NEW plan
+  // selection is the <PlanGrid> below, which pre-creates a per-tier checkout.
+  const { portalUrl, loading, error, notReady } = usePortalSession({
+    context,
+    state,
+    appKey,
+  });
+
+  const hasPlans = (state?.plans?.length ?? 0) > 0;
+  const onPaidPlan = !!state?.entitlement?.plan;
 
   return (
     <Flex direction="column" gap="medium">
@@ -297,26 +304,36 @@ function CreditsBilling({ context, state, appKey }) {
         creditMeter={state?.credit_meter}
       />
 
-      {/* PRIMARY CTA at top: pick a plan / buy credits. Button-with-href so it
-          reads as a real button; LoadingButton shows the prepared/loading state. */}
-      {error ? (
-        <Alert title="Couldn't open checkout" variant="danger">
-          <Text>{error}</Text>
-        </Alert>
-      ) : (
-        <LoadingButton
-          href={portalUrl ? { url: portalUrl, external: true } : undefined}
-          loading={loading}
-          disabled={!portalUrl}
-          variant="primary"
-        >
-          {portalUrl ? "Pick a plan or buy credits" : "Preparing checkout…"}
-        </LoadingButton>
-      )}
+      {/* The dynamically-rendered upgrade path (tiers from the Stripe catalog).
+          Renders nothing if no plans are mirrored yet. */}
+      <PlanGrid context={context} state={state} appKey={appKey} />
+
+      {/* Manage-billing link: relevant once the customer is on a paid plan
+          (change/cancel/invoices in Stripe). Hidden in the not-ready
+          (un-provisioned) state. When no plans are mirrored AND not on a paid
+          plan, fall back to the portal as the only CTA so the tab isn't empty. */}
+      {!notReady && (onPaidPlan || !hasPlans) &&
+        (error ? (
+          <Alert title="Couldn't open billing" variant="danger">
+            <Text>{error}</Text>
+          </Alert>
+        ) : (
+          <LoadingButton
+            href={portalUrl ? { url: portalUrl, external: true } : undefined}
+            loading={loading}
+            disabled={!portalUrl}
+            variant={onPaidPlan ? "secondary" : "primary"}
+          >
+            {portalUrl
+              ? onPaidPlan
+                ? "Manage billing in Stripe"
+                : "Buy credits in Stripe"
+              : "Preparing billing…"}
+          </LoadingButton>
+        ))}
 
       <Text format={{ fontStyle: "italic" }}>
-        Top up or move to a paid monthly allowance to keep going. Billing is
-        managed in Stripe across all Growth Operations apps.
+        Billing is managed in Stripe across all Growth Operations apps.
       </Text>
     </Flex>
   );

package/src/billing/PlanGrid.jsx

@@ -0,0 +1,208 @@
+import React, { useState } from "react";
+import {
+  hubspot,
+  Flex,
+  Tile,
+  Text,
+  Heading,
+  StatusTag,
+  LoadingButton,
+  Button,
+  Link,
+  Alert,
+  ToggleGroup,
+} from "@hubspot/ui-extensions";
+import { fmtMoney } from "../lib/format";
+
+// The credit-app upgrade path: a dynamically-rendered grid of the pickable
+// plans (tiers) a customer can move to, driven entirely by the backend `plans`
+// block (CONTRACT.md → common.billing.catalog.get_plans). The shared package is
+// presentational — it never hardcodes tiers/prices/features; everything comes
+// from the Stripe catalog mirror via the payload.
+//
+// Per-tier checkout follows the §5.3 UI-extension gotchas: Stripe can't be
+// iframed and there's no open-URL action — only <Link>/Button-with-href, whose
+// href must exist before render. So a tier's "Choose" click POSTs to the
+// billing service to PRE-CREATE a hosted checkout session for that price_id,
+// then renders the returned URL as an external link the customer clicks. The
+// extension can't read Stripe's redirect params (sandboxed iframe), so the
+// post-payment credit grant is server-side (Stripe webhook → grant_credits).
+//
+// Props:
+//   context — UI-extension serverless context (context.portal.id).
+//   state   — the /v1/home payload (plans[], billing_base_url, app_id).
+//   appKey  — the billing app_key for THIS app (always a prop, never hardcoded).
+
+// One plan card. Shows tier name, price for the selected interval, credits,
+// feature bullets, and a CTA: "Current" (disabled) for the active tier,
+// "Contact sales" for talk_to_sales tiers, else "Choose" which pre-creates a
+// checkout session for that tier's price in the selected interval.
+function PlanCard({ plan, interval, onChoose, choosing, checkoutUrl, supportUrl }) {
+  const leg = interval === "annual" ? plan.annual : plan.monthly;
+  const periodLabel = interval === "annual" ? "/yr" : "/mo";
+
+  const priceText = plan.talk_to_sales
+    ? "Custom"
+    : leg
+      ? `${fmtMoney(leg.unit_amount, leg.currency)}${periodLabel}`
+      : "Free";
+
+  return (
+    <Tile>
+      <Flex direction="column" gap="small">
+        <Flex direction="row" gap="small" align="center">
+          <Heading>{plan.name ?? plan.tier}</Heading>
+          {plan.current && <StatusTag variant="success">Current plan</StatusTag>}
+        </Flex>
+
+        <Text format={{ fontWeight: "bold", fontSize: "lg" }}>{priceText}</Text>
+
+        {plan.credits_per_period != null && (
+          <Text>
+            {plan.credits_per_period.toLocaleString()} credits / month
+          </Text>
+        )}
+
+        {(plan.features ?? []).map((f, i) => (
+          <Text key={i}>• {f}</Text>
+        ))}
+
+        {/* CTA. Current tier => disabled marker. talk_to_sales => contact link.
+            Otherwise pre-create-then-link checkout for the selected interval. */}
+        {plan.current ? (
+          <Button disabled>Current plan</Button>
+        ) : plan.talk_to_sales ? (
+          <Button
+            href={supportUrl ? { url: supportUrl, external: true } : undefined}
+            disabled={!supportUrl}
+            variant="secondary"
+          >
+            Contact sales
+          </Button>
+        ) : !leg ? (
+          // No price for the selected interval (e.g. annual not offered) — guide
+          // the customer to the other toggle rather than dead-ending.
+          <Text format={{ fontStyle: "italic" }}>
+            Not available {interval === "annual" ? "annually" : "monthly"}
+          </Text>
+        ) : checkoutUrl ? (
+          <Button href={{ url: checkoutUrl, external: true }} variant="primary">
+            Continue to checkout
+          </Button>
+        ) : (
+          <LoadingButton
+            loading={choosing}
+            onClick={() => onChoose(plan, leg)}
+            variant="primary"
+          >
+            Choose {plan.name ?? plan.tier}
+          </LoadingButton>
+        )}
+      </Flex>
+    </Tile>
+  );
+}
+
+export function PlanGrid({ context, state, appKey }) {
+  const plans = state?.plans ?? [];
+  // Default to annual only if EVERY paid plan offers it; else monthly.
+  const paid = plans.filter((p) => !p.talk_to_sales && (p.monthly || p.annual));
+  const annualAvailable =
+    paid.length > 0 && paid.every((p) => p.annual);
+  const [interval, setInterval] = useState(annualAvailable ? "annual" : "monthly");
+  const [choosingTier, setChoosingTier] = useState(null);
+  // Pre-created checkout URL keyed by `${tier}:${interval}` so a card only shows
+  // "Continue to checkout" for the exact price the customer picked.
+  const [checkoutUrls, setCheckoutUrls] = useState({});
+  const [error, setError] = useState(null);
+
+  if (plans.length === 0) return null;
+
+  const supportUrl = state?.helpful_links?.supportUrl ?? null;
+
+  async function choose(plan, leg) {
+    setError(null);
+    setChoosingTier(plan.tier);
+    try {
+      const base = state?.billing_base_url;
+      if (!base) throw new Error("Billing service not configured");
+      if (!appKey) throw new Error("Missing appKey for checkout");
+      const portalId = context?.portal?.id;
+
+      const returnUrl = state?.app_id
+        ? `https://app.hubspot.com/app/${portalId}/${state.app_id}/billing`
+        : "https://app.hubspot.com/";
+
+      // hubspot.fetch: body is a plain OBJECT (not a JSON string); only
+      // Authorization survives as a header — don't set Content-Type.
+      const res = await hubspot.fetch(`${base}/v1/billing/checkout`, {
+        method: "POST",
+        body: {
+          app_key: appKey,
+          portal_id: String(portalId),
+          price_id: leg.price_id,
+          return_url: returnUrl,
+        },
+      });
+      if (!res.ok) {
+        const text = await res.text();
+        throw new Error(`Checkout request failed (${res.status}): ${text}`);
+      }
+      const { url } = await res.json();
+      if (!url) throw new Error("No checkout URL returned");
+      setCheckoutUrls((prev) => ({ ...prev, [`${plan.tier}:${interval}`]: url }));
+    } catch (err) {
+      setError(String(err));
+    } finally {
+      setChoosingTier(null);
+    }
+  }
+
+  return (
+    <Flex direction="column" gap="medium">
+      <Flex direction="row" gap="medium" align="center" justify="start">
+        <Heading>Plans</Heading>
+        {annualAvailable && (
+          <ToggleGroup
+            name="billing-interval"
+            toggleType="radioButtonList"
+            inline={true}
+            value={interval}
+            onChange={(v) => v && setInterval(v)}
+            options={[
+              { label: "Monthly", value: "monthly" },
+              { label: "Annual", value: "annual" },
+            ]}
+          />
+        )}
+      </Flex>
+
+      {error && (
+        <Alert title="Couldn't start checkout" variant="danger">
+          <Text>{error}</Text>
+        </Alert>
+      )}
+
+      <Flex direction="row" gap="medium" wrap="wrap">
+        {plans.map((plan) => (
+          <PlanCard
+            key={plan.tier}
+            plan={plan}
+            interval={interval}
+            onChoose={choose}
+            choosing={choosingTier === plan.tier}
+            checkoutUrl={checkoutUrls[`${plan.tier}:${interval}`]}
+            supportUrl={supportUrl}
+          />
+        ))}
+      </Flex>
+
+      <Text format={{ fontStyle: "italic" }}>
+        Billing is managed in Stripe across all Growth Operations apps. Your new
+        credits are added as soon as payment completes.
+      </Text>
+    </Flex>
+  );
+}
+
+export default PlanGrid;

package/src/home/AppHome.jsx

@@ -6,6 +6,7 @@ import { OnboardingChecklist } from "./OnboardingChecklist";
 import { SyncPulse } from "./SyncPulse";
 import { CreditMeter } from "./CreditMeter";
 import { FeatureNudges } from "./FeatureNudges";
+import { HelpfulLinks } from "./HelpfulLinks";
 
 // Minimal inline ATS tile (the `pipeline` block). Kept tiny here rather than a
 // separate file — it's the simplest of the three archetype tiles. Renders
@@ -76,7 +77,13 @@ function ArchetypeTile({ state }) {
 //                PageLink navigation (the host owns the router).
 //   appName    — display name override; defaults to state.app.name.
 //   onRetry    — optional, passed to InstallProgress for the failed state.
-export function AppHome({ state, onNavigate, appName, onRetry }) {
+//   helpfulLinks — optional props for the standard HelpfulLinks section
+//                  (e.g. { portalId, appId, appName, docsUrl, supportUrl,
+//                  links }). Omit to hide the section. The host passes this
+//                  (it owns context.portal.id + the app's docs/support); it can
+//                  also come from a state.helpful_links block if the backend
+//                  builds one.
+export function AppHome({ state, onNavigate, appName, onRetry, helpfulLinks }) {
   if (!state) {
     return <LoadingSpinner showLabel label="Loading…" />;
   }
@@ -85,10 +92,21 @@ export function AppHome({ state, onNavigate, appName, onRetry }) {
   const activationComplete =
     !activation || activation.complete === true || activation.status === "completed";
 
+  // HelpfulLinks props: explicit prop wins, else a state.helpful_links block if
+  // the backend builds one. Shown in both the install and cockpit views so help
+  // is reachable even mid-setup.
+  const links = helpfulLinks ?? state.helpful_links ?? null;
+  const helpfulLinksEl = links ? <HelpfulLinks {...links} /> : null;
+
   // Install isn't finished (running / failed / completed-with-warnings) — show
   // the install experience instead of the cockpit.
   if (!activationComplete) {
-    return <InstallProgress state={state} onRetry={onRetry} />;
+    return (
+      <Flex direction="column" gap="medium">
+        <InstallProgress state={state} onRetry={onRetry} />
+        {helpfulLinksEl}
+      </Flex>
+    );
   }
 
   const onboardingComplete = state.onboarding?.complete === true;
@@ -108,6 +126,8 @@ export function AppHome({ state, onNavigate, appName, onRetry }) {
       <ArchetypeTile state={state} />
 
       <FeatureNudges nudges={state.nudges} onNavigate={onNavigate} />
+
+      {helpfulLinksEl}
     </Flex>
   );
 }

package/src/home/HelpfulLinks.jsx

@@ -35,18 +35,26 @@ export function HelpfulLinks({
   links = [],
   title = "Helpful Links",
 }) {
+  // external=false keeps navigation in the SAME tab. The app-pages deep link is
+  // an in-app HubSpot URL, so it must stay same-tab (external:true would force a
+  // new tab). Docs/support and app-specific extras are off-platform → external.
   const items = [];
 
   if (appPages && appId && portalId != null) {
     items.push({
       label: `Open ${appName} →`,
       url: appPagesUrl(portalId, appId, appPagesPath),
+      external: false,
     });
   }
-  if (docsUrl) items.push({ label: "Documentation", url: docsUrl });
-  if (supportUrl) items.push({ label: "Support", url: supportUrl });
+  if (docsUrl) items.push({ label: "Documentation", url: docsUrl, external: true });
+  if (supportUrl) items.push({ label: "Support", url: supportUrl, external: true });
   for (const l of links) {
-    if (l && l.url && l.label) items.push({ label: l.label, url: l.url });
+    if (l && l.url && l.label) {
+      // Default app-specific extras to external (they're usually HubSpot record
+      // URLs or off-platform), but let a link opt into same-tab via external:false.
+      items.push({ label: l.label, url: l.url, external: l.external !== false });
+    }
   }
 
   if (items.length === 0) return null;
@@ -56,7 +64,7 @@ export function HelpfulLinks({
       <Text format={{ fontWeight: "bold" }}>{title}</Text>
       <Divider />
       {items.map((item) => (
-        <Link key={item.url} href={{ url: item.url, external: true }}>
+        <Link key={item.url} href={{ url: item.url, external: item.external }}>
           {item.label}
         </Link>
       ))}

package/src/index.js

@@ -16,10 +16,12 @@ export { HelpfulLinks } from "./home/HelpfulLinks";
 
 // Billing.
 export { BillingTab } from "./billing/BillingTab";
+export { PlanGrid } from "./billing/PlanGrid";
 
 // Lib helpers.
 export {
   fmtDate,
+  fmtMoney,
   daysUntil,
   humanizeStatus,
   statusVariant,

package/src/lib/format.js

@@ -22,6 +22,23 @@ export function daysUntil(value) {
   return Math.ceil((ms - Date.now()) / (1000 * 60 * 60 * 24));
 }
 
+// Stripe amount (smallest currency unit, e.g. cents) -> "$29" / "€29.50".
+// Whole amounts drop the decimals; null/undefined -> "—". Currency defaults to
+// USD; falls back to an uppercased code prefix for currencies Intl can't symbol.
+export function fmtMoney(unitAmount, currency = "usd") {
+  if (unitAmount == null) return "—";
+  const amount = unitAmount / 100;
+  try {
+    return new Intl.NumberFormat(undefined, {
+      style: "currency",
+      currency: (currency || "usd").toUpperCase(),
+      minimumFractionDigits: Number.isInteger(amount) ? 0 : 2,
+    }).format(amount);
+  } catch {
+    return `${(currency || "usd").toUpperCase()} ${amount}`;
+  }
+}
+
 // Friendly labels for the AppInstallStatus enum (shared across apps).
 export const STATUS_LABELS = {
   trialing: "Free trial",