@growth-operations/ui-shared 1.0.7 → 1.0.9

package/package.json

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

package/src/billing/BillingTab.jsx

@@ -145,6 +145,11 @@ function usePortalSession({ context, state, appKey }) {
   const [loading, setLoading] = useState(true);
   const [error, setError] = useState(null);
   const [portalUrl, setPortalUrl] = useState(null);
+  // "Not ready" = the install hasn't been provisioned with a Stripe customer
+  // yet (fresh/old account: no entitlement.status, or the portal endpoint 409s
+  // with "no Stripe customer"). That's an expected pre-purchase state, not an
+  // error — the UI shows a calm "finish setup" message instead of a red alert.
+  const [notReady, setNotReady] = useState(false);
 
   // Pre-create on mount so the link is one real click (Stripe can't be iframed;
   // UI Extensions have no open-URL action — only Link, whose href must exist
@@ -162,6 +167,17 @@ function usePortalSession({ context, state, appKey }) {
         resetOnUnmount();
         return;
       }
+      // No Stripe customer yet → don't even try to open a portal. An install
+      // that hasn't been provisioned (no entitlement, or status null/
+      // not_installed) has nothing to manage; show the calm "not ready" state.
+      const status = state?.entitlement?.status;
+      if (!state.entitlement || status == null || status === "not_installed") {
+        if (mounted.current) {
+          setNotReady(true);
+          setLoading(false);
+        }
+        return;
+      }
       try {
         const base = state.billing_base_url;
         if (!base) throw new Error("Billing service not configured");
@@ -187,25 +203,54 @@ function usePortalSession({ context, state, appKey }) {
         });
         if (!res.ok) {
           const text = await res.text();
-          throw new Error(`Billing portal request failed (${res.status}): ${text}`);
+          // 409 "no Stripe customer yet" is the not-provisioned case, not a
+          // failure — surface it as the calm not-ready state.
+          if (res.status === 409 && /no stripe customer/i.test(text)) {
+            if (mounted.current) setNotReady(true);
+          } else {
+            throw new Error(`Billing portal request failed (${res.status}): ${text}`);
+          }
+        } else {
+          const { url } = await res.json();
+          if (!url) throw new Error("No billing portal URL returned");
+          if (mounted.current) setPortalUrl(url);
         }
-        const { url } = await res.json();
-        if (!url) throw new Error("No billing portal URL returned");
-        if (mounted.current) setPortalUrl(url);
       } catch (perr) {
         if (mounted.current) setError(String(perr));
       } finally {
         if (mounted.current) setLoading(false);
       }
     },
-    [context, appKey, state?.billing_base_url, state?.app_id]
+    [context, appKey, state?.billing_base_url, state?.app_id, state?.entitlement?.status]
   );
 
-  return { portalUrl, loading, error };
+  return { portalUrl, loading, error, notReady };
 }
 
 function TrialSubscriptionBilling({ context, state, appKey }) {
-  const { portalUrl, loading, error } = usePortalSession({ context, state, appKey });
+  const { portalUrl, loading, error, notReady } = usePortalSession({
+    context,
+    state,
+    appKey,
+  });
+
+  // Install not provisioned with a Stripe customer yet — calm "finish setup"
+  // state, not a red error. (Old/stale installs, or before the install flow's
+  // provision_trial_install has run.)
+  if (notReady) {
+    return (
+      <Flex direction="column" gap="medium">
+        <Alert title="Billing isn't set up yet" variant="info">
+          <Text>
+            Your trial and billing are still being set up for this install. Once
+            setup completes, manage your plan and payment method here. If this
+            persists, reinstall the app from the HubSpot marketplace to complete
+            sign-in.
+          </Text>
+        </Alert>
+      </Flex>
+    );
+  }
 
   return (
     <Flex direction="column" gap="medium">

package/src/home/HelpfulLinks.jsx

@@ -0,0 +1,67 @@
+import React from "react";
+import { Flex, Text, Link, Divider } from "@hubspot/ui-extensions";
+
+// Build the in-app app-pages deep link (the app's Home/tabs live under /app).
+function appPagesUrl(portalId, appId, pagePath = "") {
+  const suffix = pagePath ? `/${pagePath.replace(/^\//, "")}` : "";
+  return `https://app.hubspot.com/app/${portalId}/${appId}${suffix}`;
+}
+
+// HelpfulLinks — a standard "Helpful Links" section for every Growth Operations
+// app. Renders a labeled list of links: optionally an "Open <app>" deep link
+// back to the app pages (so the settings extension isn't a dead end), docs +
+// support from the app config, and any app-specific extras.
+//
+// Props:
+//   portalId   — context.portal.id (number/string).
+//   appId      — this app's HubSpot app id (per-env). Needed for the app-pages
+//                deep link; omit to hide that link.
+//   appName    — display name, e.g. "Sparkfly" (used in the deep-link label).
+//   appPages   — when true (default) and appId is set, show "Open <appName> →"
+//                linking to the app pages. Set the page path via appPagesPath.
+//   appPagesPath — optional pages route to deep-link into (default: Home).
+//   docsUrl, supportUrl — external help links (omit to hide).
+//   links      — app-specific extras: [{ label, url }]. Rendered after the
+//                standard links.
+//   title      — section heading (default "Helpful Links").
+export function HelpfulLinks({
+  portalId,
+  appId,
+  appName = "the app",
+  appPages = true,
+  appPagesPath = "",
+  docsUrl,
+  supportUrl,
+  links = [],
+  title = "Helpful Links",
+}) {
+  const items = [];
+
+  if (appPages && appId && portalId != null) {
+    items.push({
+      label: `Open ${appName} →`,
+      url: appPagesUrl(portalId, appId, appPagesPath),
+    });
+  }
+  if (docsUrl) items.push({ label: "Documentation", url: docsUrl });
+  if (supportUrl) items.push({ label: "Support", url: supportUrl });
+  for (const l of links) {
+    if (l && l.url && l.label) items.push({ label: l.label, url: l.url });
+  }
+
+  if (items.length === 0) return null;
+
+  return (
+    <Flex direction="column" gap="small">
+      <Text format={{ fontWeight: "bold" }}>{title}</Text>
+      <Divider />
+      {items.map((item) => (
+        <Link key={item.url} href={{ url: item.url, external: true }}>
+          {item.label}
+        </Link>
+      ))}
+    </Flex>
+  );
+}
+
+export default HelpfulLinks;

package/src/index.js

@@ -12,6 +12,7 @@ export { OnboardingChecklist } from "./home/OnboardingChecklist";
 export { SyncPulse } from "./home/SyncPulse";
 export { FeatureNudges } from "./home/FeatureNudges";
 export { CreditMeter } from "./home/CreditMeter";
+export { HelpfulLinks } from "./home/HelpfulLinks";
 
 // Billing.
 export { BillingTab } from "./billing/BillingTab";