@growth-operations/ui-shared 1.0.0

package/src/home/FeatureNudges.jsx

@@ -0,0 +1,38 @@
+import React from "react";
+import { Flex, Tile, Text, Link, Button } from "@hubspot/ui-extensions";
+
+// Mode B: "get more from <app>" — surfaces unused/under-used capabilities the
+// backend detected (/v1/home nudges block). Each nudge is app-specific copy
+// computed server-side (e.g. sparkfly: "turn on bidirectional sync",
+// "map more fields"). Renders nothing when there are no nudges.
+//
+// `onNavigate(route)` lets a nudge deep-link to an in-app route; cta_url is an
+// external/settings deep link.
+export function FeatureNudges({ nudges, onNavigate, title = "Get more from this app" }) {
+  if (!Array.isArray(nudges) || nudges.length === 0) return null;
+
+  return (
+    <Tile>
+      <Flex direction="column" gap="small">
+        <Text format={{ fontWeight: "bold" }}>{title}</Text>
+        {nudges.map((n) => (
+          <Flex key={n.key} direction="column" gap="extra-small">
+            <Text format={{ fontWeight: "demibold" }}>{n.title}</Text>
+            <Text>{n.message}</Text>
+            {n.cta_url ? (
+              <Link href={{ url: n.cta_url, external: true }}>
+                {n.cta_label ?? "Set it up"} →
+              </Link>
+            ) : n.cta_route && onNavigate ? (
+              <Button variant="secondary" onClick={() => onNavigate(n.cta_route)}>
+                {n.cta_label ?? "Set it up"}
+              </Button>
+            ) : null}
+          </Flex>
+        ))}
+      </Flex>
+    </Tile>
+  );
+}
+
+export default FeatureNudges;

package/src/home/HealthHero.jsx

@@ -0,0 +1,95 @@
+import React from "react";
+import { Flex, Heading, Alert, Text } from "@hubspot/ui-extensions";
+import { humanizeStatus, statusVariant } from "../lib/format";
+
+const HEALTH_VARIANT = { healthy: "success", attention: "warning", critical: "error" };
+const HEALTH_TITLE = {
+  healthy: "Everything looks healthy",
+  attention: "Needs attention",
+  critical: "Action required",
+};
+
+// The activated-state hero at the top of Home: a glanceable, color-coded health
+// verdict (computed server-side in /v1/home, the `health` block). The
+// install-time activation progress is handled separately by InstallProgress, so
+// this focuses purely on steady-state health. When no health block is present it
+// falls back to a color-coded verdict derived from the entitlement union
+// (CONTRACT.md): trial_subscription -> the AppInstallStatus; credits -> a
+// remaining/depleted verdict.
+export function HealthHero({ appName, state }) {
+  if (!state) return null;
+
+  const health = state.health;
+  const name = appName ?? state.app?.name;
+
+  if (health?.level) {
+    return (
+      <Flex direction="column" gap="small">
+        {name && <Heading>{name}</Heading>}
+        <Alert
+          title={HEALTH_TITLE[health.level] ?? "Status"}
+          variant={HEALTH_VARIANT[health.level] ?? "info"}
+        >
+          <Flex direction="column" gap="extra-small">
+            {(health.reasons ?? []).map((r, i) => (
+              <Text key={i}>{r}</Text>
+            ))}
+          </Flex>
+        </Alert>
+      </Flex>
+    );
+  }
+
+  // No health block — fall back to an entitlement-derived verdict.
+  const ent = state.entitlement;
+  if (!ent) {
+    return name ? (
+      <Flex direction="column" gap="small">
+        <Heading>{name}</Heading>
+      </Flex>
+    ) : null;
+  }
+
+  if (ent.mode === "credits") {
+    const remaining = ent.remaining ?? 0;
+    const depleted = ent.depleted === true || remaining <= 0;
+    const low = !depleted && remaining <= (ent.low_threshold ?? 0);
+    const variant = depleted ? "error" : low ? "warning" : "success";
+    const title = depleted
+      ? "You're out of credits"
+      : low
+      ? "Running low on credits"
+      : `${remaining} credits remaining`;
+    return (
+      <Flex direction="column" gap="small">
+        {name && <Heading>{name}</Heading>}
+        <Alert title={title} variant={variant}>
+          {(depleted || low) && (
+            <Text>
+              {depleted
+                ? "Pick a plan in Billing to keep going."
+                : "You're getting close to your limit — consider a plan in Billing."}
+            </Text>
+          )}
+        </Alert>
+      </Flex>
+    );
+  }
+
+  // trial_subscription (and any other status-bearing arm).
+  return (
+    <Flex direction="column" gap="small">
+      {name && <Heading>{name}</Heading>}
+      <Alert title={humanizeStatus(ent.status)} variant={statusVariant(ent.status)}>
+        {ent.entitled === false && (
+          <Text>
+            This install isn't on an active plan. Open Billing to choose a plan
+            and resume syncing.
+          </Text>
+        )}
+      </Alert>
+    </Flex>
+  );
+}
+
+export default HealthHero;

package/src/home/InstallProgress.jsx

@@ -0,0 +1,102 @@
+import React from "react";
+import {
+  Flex,
+  Tile,
+  Text,
+  ProgressBar,
+  Alert,
+  Button,
+  LoadingSpinner,
+} from "@hubspot/ui-extensions";
+
+// THE standard install-status module — every Growth Operations app uses this
+// for the post-install activation experience. Baselined on the Anvil
+// Installation page (client_code/Pages/Installation) which handled: a step
+// progress bar, a success/final-output state, a non-fatal WARNINGS panel, and a
+// FAILED + retry panel. We carry all of those into the new (Stripe/Firestore)
+// world, driven by the /v1/home `activation` block (CONTRACT.md).
+//
+// State machine (from activation.status + activation.step):
+//   RUNNING / PENDING  -> determinate progress bar (step / total) + label
+//   FAILED             -> error alert + Retry button (onRetry)
+//   COMPLETED w/ warnings -> success + a warnings callout
+//   COMPLETED clean    -> render nothing (install is done; Home shows health)
+//
+// Props:
+//   state    — the /v1/home payload. Reads the nested `activation` block:
+//              activation.status, activation.step, activation.total,
+//              activation.label, activation.complete, activation.warnings.
+//   onRetry  — optional () => void to re-trigger activation (re-publishes the
+//              activation Pub/Sub message via an app endpoint). If omitted, the
+//              FAILED state still renders guidance, just no button.
+export function InstallProgress({ state, onRetry }) {
+  const activation = state?.activation;
+  // No activation block => nothing to show (Home's health hero takes over).
+  if (!activation) return null;
+
+  const status = activation.status;
+  const step = activation.step ?? 0;
+  const total = activation.total ?? 5;
+  const warnings = activation.warnings ?? [];
+  const complete = activation.complete === true || status === "completed";
+
+  // FAILED — surface the error and let the user retry (Pub/Sub also retries
+  // server-side, but an explicit retry beats a silent stall).
+  if (status === "failed") {
+    return (
+      <Alert title="Setup didn't finish" variant="error">
+        <Flex direction="column" gap="small">
+          <Text>
+            We hit a problem finishing your install. This often clears itself on
+            the next automatic retry; if it persists, retry now or contact
+            support.
+          </Text>
+          {warnings.length > 0 &&
+            warnings.map((w, i) => <Text key={i}>• {w}</Text>)}
+          {onRetry && (
+            <Button variant="primary" onClick={onRetry}>
+              Retry setup
+            </Button>
+          )}
+        </Flex>
+      </Alert>
+    );
+  }
+
+  // RUNNING / PENDING — determinate progress while activation provisions assets.
+  if (!complete) {
+    return (
+      <Tile>
+        <Flex direction="column" gap="small">
+          <Text format={{ fontWeight: "bold" }}>Setting up your install…</Text>
+          <ProgressBar
+            title={activation.label ?? "Finishing up…"}
+            value={step}
+            maxValue={total}
+            showPercentage={true}
+          />
+          <LoadingSpinner label="This usually takes under a minute." showLabel />
+        </Flex>
+      </Tile>
+    );
+  }
+
+  // COMPLETED with non-fatal warnings — let the user know setup finished but
+  // something needs a look (mirrors the Anvil warnings panel).
+  if (complete && warnings.length > 0) {
+    return (
+      <Alert title="Setup finished with warnings" variant="warning">
+        <Flex direction="column" gap="extra-small">
+          {warnings.map((w, i) => (
+            <Text key={i}>• {w}</Text>
+          ))}
+        </Flex>
+      </Alert>
+    );
+  }
+
+  // COMPLETED clean — nothing to show; Home's health hero takes over.
+  return null;
+}
+
+export default InstallProgress;

package/src/home/OnboardingChecklist.jsx

@@ -0,0 +1,58 @@
+import React from "react";
+import { Flex, Tile, Text, ProgressBar, Link, Button } from "@hubspot/ui-extensions";
+
+// Lifecycle Mode A: the setup checklist for new/not-yet-activated installs.
+// Each step's `done` is computed server-side (/v1/home onboarding block) from
+// the account doc, so the list self-checks. A single "next best action" button
+// points at the first incomplete step. Steps carry either a cta_route (an
+// in-app PageLink target) or a cta_url (external/deep link).
+//
+// `onNavigate(route)` is supplied by the host app (PageLink can't be created
+// here without the router); cta_url renders as an external Link.
+export function OnboardingChecklist({ onboarding, onNavigate }) {
+  if (!onboarding || !Array.isArray(onboarding.steps) || onboarding.steps.length === 0) {
+    return null;
+  }
+
+  const steps = onboarding.steps;
+  const doneCount = steps.filter((s) => s.done).length;
+  const total = steps.length;
+  const next = steps.find((s) => !s.done);
+
+  return (
+    <Tile>
+      <Flex direction="column" gap="small">
+        <Text format={{ fontWeight: "bold", fontSize: "lg" }}>
+          Get started ({doneCount} of {total})
+        </Text>
+        <ProgressBar value={doneCount} maxValue={total} showPercentage={true} />
+
+        <Flex direction="column" gap="extra-small">
+          {steps.map((s) => (
+            <Text key={s.key} format={{ fontWeight: s.done ? "regular" : "demibold" }}>
+              {s.done ? "✓" : "○"} {s.label}
+            </Text>
+          ))}
+        </Flex>
+
+        {next && (
+          <Flex direction="row" gap="small" align="center">
+            {next.cta_url ? (
+              <Link href={{ url: next.cta_url, external: true }} variant="primary">
+                {next.cta_label ?? `Next: ${next.label}`} →
+              </Link>
+            ) : next.cta_route && onNavigate ? (
+              <Button variant="primary" onClick={() => onNavigate(next.cta_route)}>
+                {next.cta_label ?? `Next: ${next.label}`}
+              </Button>
+            ) : (
+              <Text format={{ fontWeight: "demibold" }}>Next: {next.label}</Text>
+            )}
+          </Flex>
+        )}
+      </Flex>
+    </Tile>
+  );
+}
+
+export default OnboardingChecklist;

package/src/home/SyncPulse.jsx

@@ -0,0 +1,45 @@
+import React from "react";
+import { Flex, Tile, Text, StatusTag } from "@hubspot/ui-extensions";
+import { fmtDate } from "../lib/format";
+
+// Mode B health tile: the most recent sync at a glance. Driven by the
+// /v1/home sync_pulse block (app-specific: sparkfly = contact-sync/member
+// import counters; toast = order/menu sync). Renders nothing when the app
+// has no sync pulse to report.
+export function SyncPulse({ syncPulse }) {
+  if (!syncPulse) return null;
+
+  const { last_sync_at, records_synced, records_failed, label } = syncPulse;
+  const failed = records_failed ?? 0;
+
+  return (
+    <Tile>
+      <Flex direction="column" gap="small">
+        <Flex direction="row" gap="small" align="center">
+          <Text format={{ fontWeight: "bold" }}>{label ?? "Sync activity"}</Text>
+          {failed > 0 ? (
+            <StatusTag variant="warning">{failed} failed</StatusTag>
+          ) : (
+            <StatusTag variant="success">Healthy</StatusTag>
+          )}
+        </Flex>
+        <Flex direction="row" gap="large">
+          <Flex direction="column" gap="extra-small">
+            <Text format={{ fontWeight: "demibold" }}>Records synced</Text>
+            <Text>{records_synced ?? 0}</Text>
+          </Flex>
+          <Flex direction="column" gap="extra-small">
+            <Text format={{ fontWeight: "demibold" }}>Failed</Text>
+            <Text>{failed}</Text>
+          </Flex>
+          <Flex direction="column" gap="extra-small">
+            <Text format={{ fontWeight: "demibold" }}>Last sync</Text>
+            <Text>{last_sync_at ? fmtDate(last_sync_at) : "Never"}</Text>
+          </Flex>
+        </Flex>
+      </Flex>
+    </Tile>
+  );
+}
+
+export default SyncPulse;

package/src/index.js

@@ -0,0 +1,64 @@
+// @growth-operations/ui-shared — shared HubSpot UI-extension modules.
+// Presentational components that render the /v1/home contract (see CONTRACT.md),
+// branching on entitlement.mode ("trial_subscription" | "credits").
+
+// The opinionated one-line Home integration.
+export { AppHome, default as AppHomeDefault } from "./home/AppHome";
+
+// Home building blocks.
+export { InstallProgress } from "./home/InstallProgress";
+export { HealthHero } from "./home/HealthHero";
+export { OnboardingChecklist } from "./home/OnboardingChecklist";
+export { SyncPulse } from "./home/SyncPulse";
+export { FeatureNudges } from "./home/FeatureNudges";
+export { CreditMeter } from "./home/CreditMeter";
+
+// Billing.
+export { BillingTab } from "./billing/BillingTab";
+
+// Lib helpers.
+export {
+  fmtDate,
+  daysUntil,
+  humanizeStatus,
+  statusVariant,
+  STATUS_LABELS,
+  STATUS_VARIANT,
+} from "./lib/format";
+export { useStrictModeEffect } from "./lib/useStrictModeEffect";
+
+// SDK — the token + API utility layer (see README "SDK" section and src/sdk/).
+export {
+  // App backend
+  callAppApi,
+  AppApiError,
+  getAlerts,
+  dismissAlert,
+  getSettings,
+  updateSettings,
+  makeSettingsApi,
+  // Encryption
+  strToBase64,
+  base64ToStr,
+  getKeyFromContext,
+  encrypt,
+  decrypt,
+  // HubSpot public API
+  callHubSpotApi,
+  buildHubSpotUrl,
+  HubSpotApiError,
+  getObjectProperties,
+  getProperties,
+  updateProperties,
+  getForms,
+  getLists,
+  getPipelines,
+  getPipelineStages,
+  computeStageChanges,
+  // Token lifecycle
+  getShortLivedToken,
+  isTokenExpired,
+  TokenProvider,
+  useToken,
+  TokenContext,
+} from "./sdk/index";

package/src/lib/format.js

@@ -0,0 +1,58 @@
+// Shared formatting + status helpers for Growth Operations app UIs.
+// Framework-agnostic (no React) so they can be unit-reasoned and reused.
+
+// ISO datetime string (or ms epoch) -> "Mon DD, YYYY", null-safe.
+// new Date(NaN).toLocaleDateString() would throw, so guard it.
+export function fmtDate(value) {
+  if (value == null) return "—";
+  const d = value instanceof Date ? value : new Date(value);
+  if (Number.isNaN(d.getTime())) return "—";
+  return d.toLocaleDateString(undefined, {
+    year: "numeric",
+    month: "short",
+    day: "numeric",
+  });
+}
+
+// Whole days from now until `value` (negative = past). null if unparseable.
+export function daysUntil(value) {
+  if (value == null) return null;
+  const ms = value instanceof Date ? value.getTime() : new Date(value).getTime();
+  if (Number.isNaN(ms)) return null;
+  return Math.ceil((ms - Date.now()) / (1000 * 60 * 60 * 24));
+}
+
+// Friendly labels for the AppInstallStatus enum (shared across apps).
+export const STATUS_LABELS = {
+  trialing: "Free trial",
+  active: "Active",
+  pending_purchase: "Trial ended — choose a plan",
+  past_due: "Payment past due",
+  paused: "Paused",
+  canceled: "Canceled",
+  uninstalled: "Uninstalled",
+  sandbox_trial: "Sandbox trial",
+  sandbox_linked: "Sandbox",
+  not_installed: "Not installed",
+};
+
+export function humanizeStatus(status) {
+  return STATUS_LABELS[status] ?? (status ? String(status) : "Unknown");
+}
+
+// Color-code status so it reads at a glance: green = good standing,
+// yellow = needs attention soon, red = action required.
+export const STATUS_VARIANT = {
+  active: "success",
+  trialing: "warning",
+  sandbox_trial: "warning",
+  sandbox_linked: "success",
+  pending_purchase: "warning",
+  past_due: "error",
+  paused: "warning",
+  canceled: "error",
+};
+
+export function statusVariant(status) {
+  return STATUS_VARIANT[status] ?? "info";
+}

package/src/lib/useStrictModeEffect.js

@@ -0,0 +1,84 @@
+import { useEffect, useRef } from 'react';
+
+/**
+ * A custom hook that handles React Strict Mode's double-mount pattern for async effects.
+ *
+ * This hook prevents duplicate API calls in development by:
+ * 1. Using a ref to track if the effect has already run
+ * 2. Properly resetting state when the component unmounts during async operations
+ * 3. Allowing the effect to run again when the component remounts
+ *
+ * @param {Function} effect - Async function to run. Will receive a cleanup object with:
+ *   - mounted: ref to check if component is still mounted
+ *   - resetOnUnmount: function to reset loading state and ref when unmounted
+ * @param {Array} dependencies - Dependency array for the effect
+ * @param {Object} options - Optional configuration
+ * @param {Function} options.setLoading - Function to set loading state (if applicable)
+ *
+ * @example
+ * useStrictModeEffect(
+ *   async ({ mounted, resetOnUnmount }) => {
+ *     const token = await getToken();
+ *     if (!mounted.current) {
+ *       resetOnUnmount();
+ *       return;
+ *     }
+ *     const data = await fetchData(token);
+ *     if (!mounted.current) {
+ *       resetOnUnmount();
+ *       return;
+ *     }
+ *     setData(data);
+ *   },
+ *   [dependency1, dependency2],
+ *   { setLoading }
+ * );
+ */
+export function useStrictModeEffect(effect, dependencies = [], options = {}) {
+  const fetchedRef = useRef(false);
+  const { setLoading } = options;
+
+  useEffect(() => {
+    // Prevent duplicate fetches in React Strict Mode
+    if (fetchedRef.current) return;
+
+    const mounted = { current: true };
+
+    const resetOnUnmount = () => {
+      fetchedRef.current = false;
+      if (setLoading) {
+        setLoading(false);
+      }
+    };
+
+    const runEffect = async () => {
+      // Mark as fetched BEFORE starting work to prevent race conditions
+      fetchedRef.current = true;
+
+      if (setLoading) {
+        setLoading(true);
+      }
+
+      try {
+        await effect({ mounted, resetOnUnmount });
+      } catch (error) {
+        // If there's an error, reset the ref so it can be retried
+        if (mounted.current) {
+          fetchedRef.current = false;
+        }
+        throw error;
+      } finally {
+        if (mounted.current && setLoading) {
+          setLoading(false);
+        }
+      }
+    };
+
+    runEffect();
+
+    return () => {
+      mounted.current = false;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, dependencies);
+}

package/src/sdk/app/alerts.js

@@ -0,0 +1,41 @@
+// getAlerts / dismissAlert — generic alerts API client.
+//
+// Every Growth Ops app exposes the same /api/v1/alerts surface (paginated,
+// orderable, filterable). This is already app-agnostic, so it's ported verbatim.
+// Goes through callAppApi, so it inherits the hubspot.fetch rules (object body,
+// no custom headers).
+import { callAppApi } from "./base";
+
+// context: extension context. params: { offset, limit, orderBy, orderDirection,
+// filterField, filterValue }. Returns the backend's alerts response.
+export async function getAlerts(context, params = {}) {
+  const {
+    offset = 0,
+    limit = 10,
+    orderBy,
+    orderDirection,
+    filterField,
+    filterValue,
+  } = params;
+  const queryParams = new URLSearchParams();
+  queryParams.append("offset", offset);
+  queryParams.append("limit", limit);
+
+  if (orderBy) {
+    queryParams.append("order_by_field", orderBy);
+  }
+  if (orderDirection) {
+    queryParams.append("order_by_direction", orderDirection);
+  }
+  if (filterField && filterValue) {
+    queryParams.append("filter_field", filterField);
+    queryParams.append("filter_value", filterValue);
+  }
+  const path = `/api/v1/alerts?${queryParams.toString()}`;
+  return callAppApi(context, path, "GET");
+}
+
+export async function dismissAlert(context, alertId) {
+  const path = `/api/v1/alerts/${alertId}/dismiss`;
+  return callAppApi(context, path, "POST");
+}

package/src/sdk/app/base.js

@@ -0,0 +1,57 @@
+// callAppApi — the single most-reused SDK helper.
+//
+// Wraps hubspot.fetch for calls to the APP's OWN backend (the Cloud Run service
+// behind context.variables.BASE_URL). Use this instead of reimplementing the
+// fetch dance in every app.
+//
+// hubspot.fetch rules enforced here (these bugs have cost real debugging time):
+//   - `body` is passed as a plain OBJECT. NEVER JSON.stringify it — hubspot.fetch
+//     serializes it for you, and a pre-stringified body is rejected/mangled.
+//   - NO custom headers. The platform injects Authorization automatically; adding
+//     any other header (Content-Type, etc.) causes hubspot.fetch to reject the
+//     request. So this helper sends none.
+import { hubspot } from "@hubspot/ui-extensions";
+
+export class AppApiError extends Error {
+  constructor(message, statusCode, responseText) {
+    super(message);
+    this.statusCode = statusCode;
+    this.responseText = responseText;
+    this.name = "AppApiError";
+  }
+}
+
+// context: the HubSpot extension context (must expose context.variables.BASE_URL)
+// path:    request path appended to BASE_URL, e.g. "/api/v1/settings"
+// method:  HTTP method (default "GET")
+// body:    plain object — NOT a JSON string (see header)
+export async function callAppApi(context, path, method = "GET", body = null) {
+  const url = `${context.variables.BASE_URL}${path}`;
+
+  const response = await hubspot.fetch(url, {
+    timeout: 30000,
+    method,
+    // body is a plain object; hubspot.fetch serializes it. No custom headers —
+    // Authorization is injected by the platform.
+    ...(body && { body }),
+  });
+
+  if (!response.ok) {
+    const errorText = await response.text();
+    // FastAPI errors come back as {"detail": "..."} — surface just the detail
+    // string so callers can show it directly in the UI without dragging the
+    // JSON wrapper into the message.
+    let message = errorText;
+    try {
+      const parsed = JSON.parse(errorText);
+      if (parsed && typeof parsed.detail === "string") {
+        message = parsed.detail;
+      }
+    } catch {
+      // body wasn't JSON; keep the raw text
+    }
+    throw new AppApiError(message, response.status, errorText);
+  }
+
+  return response.json();
+}