@growth-operations/ui-shared 1.1.0 → 1.3.0

package/package.json

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

package/src/alerts/AlertsTab.jsx

@@ -0,0 +1,246 @@
+// AlertsTab — the shared customer alerts table, extensible per app.
+//
+// Every Growth Ops app surfaces the same base Alert shape ({ id, level, title,
+// message, created_at, dismissable, action_name, action_url }) from the same
+// serve/dismiss contract (common.alerts + the app's alerts router). This owns
+// the shared chrome — level filter, pagination, fetch, and per-row dismiss —
+// and exposes two extension points so apps with richer alert shapes (sparkfly's
+// merge / replace-email / skip; toast's connection-lost retry) keep one table
+// instead of forking it:
+//
+//   - renderRowActions(alert, { context, refresh }) -> node
+//       Extra action UI rendered in the actions cell ALONGSIDE Dismiss. Use for
+//       app-specific buttons that act on the alert then refresh the table.
+//   - renderRow(alert, { context, refresh, dismiss, fetchOptions }) -> <TableRow>
+//       Full per-row override (escape hatch) for apps whose row needs custom
+//       layout — expandable merge panels, inline inputs, extra columns. When
+//       provided it replaces the default row entirely; the app owns the cells.
+//
+// Omit both -> default rows (level tag, title/message + action link, time,
+// Dismiss). Self-hosted apps (sparkfly, toast) call with default getAlerts/
+// dismissAlert paths; base-hosted apps pass `basePath` + `portalId` so the SDK
+// targets the base alerts route.
+import React, { useState, useEffect } from "react";
+import {
+  Alert,
+  EmptyState,
+  Text,
+  Link,
+  Button,
+  Table,
+  TableHead,
+  TableHeader,
+  TableBody,
+  TableRow,
+  TableCell,
+  Select,
+  Tag,
+  Flex,
+  LoadingSpinner,
+} from "@hubspot/ui-extensions";
+
+import { getAlerts, dismissAlert } from "../sdk/app/alerts";
+import { fmtDate } from "../lib/format";
+
+const PAGE_SIZE = 10;
+
+const LEVEL_OPTIONS = [
+  { label: "All Levels", value: "all" },
+  { label: "Info", value: "info" },
+  { label: "Warning", value: "warning" },
+  { label: "Error", value: "error" },
+  { label: "Critical", value: "critical" },
+];
+
+// Alert level -> HubSpot Tag variant.
+const LEVEL_VARIANT = {
+  info: "default",
+  warning: "warning",
+  error: "error",
+  critical: "error",
+};
+
+function DefaultAlertRow({
+  context,
+  alert,
+  refresh,
+  fetchOptions,
+  renderRowActions,
+}) {
+  const [dismissing, setDismissing] = useState(false);
+
+  const dismiss = async () => {
+    setDismissing(true);
+    try {
+      await dismissAlert(context, alert.id, fetchOptions);
+      await refresh();
+    } finally {
+      setDismissing(false);
+    }
+  };
+
+  return (
+    <TableRow>
+      <TableCell>
+        <Tag variant={LEVEL_VARIANT[alert.level] || "default"}>
+          {alert.level}
+        </Tag>
+      </TableCell>
+      <TableCell>
+        <Flex direction="column" gap="extra-small">
+          <Text format={{ fontWeight: "bold" }}>{alert.title}</Text>
+          <Text>{alert.message}</Text>
+          {alert.action_url && alert.action_name && (
+            <Link href={alert.action_url}>{alert.action_name}</Link>
+          )}
+        </Flex>
+      </TableCell>
+      <TableCell>{fmtDate(alert.created_at)}</TableCell>
+      <TableCell>
+        <Flex direction="row" gap="small" align="center">
+          {/* App-specific actions render before Dismiss. */}
+          {renderRowActions && renderRowActions(alert, { context, refresh })}
+          {alert.dismissable && (
+            <Button
+              variant="secondary"
+              size="xs"
+              disabled={dismissing}
+              onClick={dismiss}
+            >
+              {dismissing ? "Dismissing…" : "Dismiss"}
+            </Button>
+          )}
+        </Flex>
+      </TableCell>
+    </TableRow>
+  );
+}
+
+// context: extension context. basePath/portalId: forwarded to getAlerts/
+// dismissAlert (base-hosted apps pass both; self-hosted apps omit them).
+// renderRowActions / renderRow: per-app extension points (see file header).
+export function AlertsTab({
+  context,
+  basePath,
+  portalId,
+  renderRowActions,
+  renderRow,
+}) {
+  const [alerts, setAlerts] = useState([]);
+  const [total, setTotal] = useState(0);
+  const [page, setPage] = useState(1);
+  const [level, setLevel] = useState("all");
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState(null);
+
+  // The options the SDK needs to target the right backend (base vs self-hosted).
+  const fetchOptions = { basePath, portalId };
+
+  const load = async (pageNumber, levelValue) => {
+    setLoading(true);
+    try {
+      const response = await getAlerts(context, {
+        offset: (pageNumber - 1) * PAGE_SIZE,
+        limit: PAGE_SIZE,
+        orderBy: "created_at",
+        orderDirection: "DESCENDING",
+        filterField: levelValue !== "all" ? "level" : undefined,
+        filterValue: levelValue !== "all" ? levelValue : undefined,
+        ...fetchOptions,
+      });
+      setAlerts(response.alerts || []);
+      setTotal(response.total || 0);
+      setPage(pageNumber);
+      setError(null);
+    } catch (err) {
+      setError(err.message);
+      setAlerts([]);
+      setTotal(0);
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  useEffect(() => {
+    load(1, level);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [context]);
+
+  const onLevelChange = (value) => {
+    setLevel(value);
+    load(1, value);
+  };
+
+  if (error) {
+    return (
+      <Alert title="Couldn't load alerts" variant="error">
+        {error}
+      </Alert>
+    );
+  }
+
+  return (
+    <Flex direction="column" gap="medium">
+      <Select
+        label="Filter by level"
+        name="levelFilter"
+        options={LEVEL_OPTIONS}
+        value={level}
+        onChange={onLevelChange}
+      />
+      {loading ? (
+        <LoadingSpinner showLabel label="Loading alerts…" />
+      ) : !alerts.length ? (
+        <EmptyState title="No alerts" layout="vertical">
+          <Text>There are currently no alerts that need your attention.</Text>
+        </EmptyState>
+      ) : (
+        <Table
+          paginated={total > PAGE_SIZE}
+          page={page}
+          pageCount={Math.ceil(total / PAGE_SIZE)}
+          onPageChange={(p) => load(p, level)}
+        >
+          <TableHead>
+            <TableHeader width="min">Level</TableHeader>
+            <TableHeader width="max">Alert</TableHeader>
+            <TableHeader width="min">Time</TableHeader>
+            <TableHeader width="min"></TableHeader>
+          </TableHead>
+          <TableBody>
+            {alerts.map((alert) => {
+              const refresh = () => load(page, level);
+              // Full-row override escape hatch: the app owns the cells.
+              if (renderRow) {
+                const dismiss = () =>
+                  dismissAlert(context, alert.id, fetchOptions).then(refresh);
+                return (
+                  <React.Fragment key={alert.id}>
+                    {renderRow(alert, {
+                      context,
+                      refresh,
+                      dismiss,
+                      fetchOptions,
+                    })}
+                  </React.Fragment>
+                );
+              }
+              return (
+                <DefaultAlertRow
+                  key={alert.id}
+                  context={context}
+                  alert={alert}
+                  fetchOptions={fetchOptions}
+                  refresh={refresh}
+                  renderRowActions={renderRowActions}
+                />
+              );
+            })}
+          </TableBody>
+        </Table>
+      )}
+    </Flex>
+  );
+}
+
+export default AlertsTab;

package/src/index.js

@@ -18,9 +18,16 @@ export { HelpfulLinks } from "./home/HelpfulLinks";
 export { BillingTab } from "./billing/BillingTab";
 export { PlanGrid } from "./billing/PlanGrid";
 
+// Alerts — the shared customer alerts table (level filter, sort, dismiss).
+export { AlertsTab } from "./alerts/AlertsTab";
+
+// Usage — the shared credit usage view (per-day LineChart + window stats).
+export { UsageTab } from "./usage/UsageTab";
+
 // Lib helpers.
 export {
   fmtDate,
+  fmtDateTime,
   fmtMoney,
   daysUntil,
   humanizeStatus,

package/src/lib/format.js

@@ -14,6 +14,20 @@ export function fmtDate(value) {
   });
 }
 
+// Date + time, for logs where multiple events share a day (usage history). "—"
+// when null/unparseable.
+export function fmtDateTime(value) {
+  if (value == null) return "—";
+  const d = value instanceof Date ? value : new Date(value);
+  if (Number.isNaN(d.getTime())) return "—";
+  return d.toLocaleString(undefined, {
+    month: "short",
+    day: "numeric",
+    hour: "numeric",
+    minute: "2-digit",
+  });
+}
+
 // Whole days from now until `value` (negative = past). null if unparseable.
 export function daysUntil(value) {
   if (value == null) return null;

package/src/sdk/app/alerts.js

@@ -1,13 +1,24 @@
 // 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.
+// Two backend shapes share this client:
+//   - SELF-HOSTED apps (sparkfly, toast) serve /api/v1/alerts from their OWN
+//     service and resolve portalId from the verified token. Default basePath,
+//     no portalId needed.
+//   - BASE-HOSTED credit apps (line-item, …) serve from the base service at
+//     /v1/hubspot/app_pages/{app}/alerts and require ?portalId=. Pass
+//     `basePath` + `portalId` to target that route.
+//
 // Goes through callAppApi, so it inherits the hubspot.fetch rules (object body,
-// no custom headers).
+// no custom headers). BASE_URL (the app's own service, or base for base-hosted
+// apps) comes from context.variables.
 import { callAppApi } from "./base";
 
+const DEFAULT_BASE_PATH = "/api/v1/alerts";
+
 // context: extension context. params: { offset, limit, orderBy, orderDirection,
-// filterField, filterValue }. Returns the backend's alerts response.
+// filterField, filterValue, basePath, portalId }. basePath defaults to the
+// self-hosted /api/v1/alerts; portalId is appended when set (base-hosted apps).
+// Returns the backend's alerts response.
 export async function getAlerts(context, params = {}) {
   const {
     offset = 0,
@@ -16,6 +27,8 @@ export async function getAlerts(context, params = {}) {
     orderDirection,
     filterField,
     filterValue,
+    basePath = DEFAULT_BASE_PATH,
+    portalId,
   } = params;
   const queryParams = new URLSearchParams();
   queryParams.append("offset", offset);
@@ -31,11 +44,19 @@ export async function getAlerts(context, params = {}) {
     queryParams.append("filter_field", filterField);
     queryParams.append("filter_value", filterValue);
   }
-  const path = `/api/v1/alerts?${queryParams.toString()}`;
+  if (portalId != null) {
+    queryParams.append("portalId", portalId);
+  }
+  const path = `${basePath}?${queryParams.toString()}`;
   return callAppApi(context, path, "GET");
 }
 
-export async function dismissAlert(context, alertId) {
-  const path = `/api/v1/alerts/${alertId}/dismiss`;
+// context, alertId, options: { basePath, portalId }. basePath defaults to the
+// self-hosted /api/v1/alerts; portalId is appended when set (base-hosted apps).
+export async function dismissAlert(context, alertId, options = {}) {
+  const { basePath = DEFAULT_BASE_PATH, portalId } = options;
+  const query =
+    portalId != null ? `?portalId=${encodeURIComponent(portalId)}` : "";
+  const path = `${basePath}/${alertId}/dismiss${query}`;
   return callAppApi(context, path, "POST");
 }

package/src/usage/UsageTab.jsx

@@ -0,0 +1,141 @@
+// UsageTab — the shared in-app credit usage view for credit apps.
+//
+// The off-Anvil answer to "show usage directly in-app", chart-first (matches
+// the sparkfly/toast usage tabs): a LineChart of credits used per day over a
+// window + headline Statistics (used in window / remaining / granted). Fed by
+// the backend usage series at {basePath}/usage?portalId=&days= — credit_meter
+// .recent on the home payload is only the last ~20 events, so the chart reads
+// the dedicated, zero-filled, server-bucketed series instead.
+//
+// Self-hosted apps (sparkfly/toast) serve /api/v1/usage from their own service;
+// base-hosted credit apps (line-item) pass `basePath` + `portalId` to hit base's
+// /v1/hubspot/app_pages/{app}/usage. Trial/non-credit apps don't render this.
+import React, { useState } from "react";
+import {
+  hubspot,
+  Flex,
+  Heading,
+  Text,
+  Tile,
+  Statistics,
+  StatisticsItem,
+  LineChart,
+  Select,
+  LoadingSpinner,
+  Alert,
+  EmptyState,
+} from "@hubspot/ui-extensions";
+
+import { useStrictModeEffect } from "../lib/useStrictModeEffect";
+
+const DEFAULT_BASE_PATH = "/api/v1/usage";
+
+const WINDOW_OPTIONS = [
+  { label: "Last 7 days", value: "7" },
+  { label: "Last 30 days", value: "30" },
+  { label: "Last 90 days", value: "90" },
+];
+
+// context: extension context. basePath/portalId: target the right backend
+// (base-hosted apps pass both). appName: chart copy.
+export function UsageTab({
+  context,
+  basePath = DEFAULT_BASE_PATH,
+  portalId,
+  appName = "this app",
+}) {
+  const [data, setData] = useState(null);
+  const [days, setDays] = useState("30");
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState(null);
+
+  useStrictModeEffect(
+    async ({ mounted }) => {
+      setLoading(true);
+      try {
+        const base = context.variables?.BASE_URL ?? "";
+        const pid = portalId ?? context.portal.id;
+        const url = `${base}${basePath}?portalId=${pid}&days=${days}`;
+        const res = await hubspot
+          .fetch(url, { method: "GET", timeout: 15000 })
+          .then((r) => r.json());
+        if (mounted.current) {
+          setData(res);
+          setError(null);
+        }
+      } catch (err) {
+        if (mounted.current) setError(String(err));
+      } finally {
+        if (mounted.current) setLoading(false);
+      }
+    },
+    [context, days]
+  );
+
+  if (loading) return <LoadingSpinner showLabel label="Loading usage…" />;
+
+  if (error) {
+    return (
+      <Flex direction="column" gap="medium">
+        <Heading>Usage</Heading>
+        <Alert title="Couldn't load usage" variant="warning">
+          <Text>{error}</Text>
+        </Alert>
+      </Flex>
+    );
+  }
+
+  const series = data?.series ?? [];
+  const usedInWindow = data?.used_in_window ?? 0;
+  const remaining = data?.remaining ?? 0;
+  const granted = data?.granted ?? 0;
+  const hasActivity = usedInWindow > 0;
+
+  return (
+    <Flex direction="column" gap="medium">
+      <Flex direction="row" justify="between" align="end">
+        <Heading>Usage</Heading>
+        <Select
+          label="Window"
+          name="window"
+          options={WINDOW_OPTIONS}
+          value={days}
+          onChange={setDays}
+        />
+      </Flex>
+
+      <Tile>
+        <Statistics>
+          <StatisticsItem label="Credits used (window)" number={usedInWindow} />
+          <StatisticsItem label="Remaining" number={remaining} />
+          <StatisticsItem label="Granted" number={granted} />
+        </Statistics>
+      </Tile>
+
+      {!hasActivity ? (
+        <EmptyState title="No usage yet" layout="vertical">
+          <Text>
+            Once you run a metered {appName} action, your credit usage shows here
+            over time.
+          </Text>
+        </EmptyState>
+      ) : (
+        <Tile>
+          <Flex direction="column" gap="small">
+            <Text format={{ fontWeight: "bold" }}>Credits used per day</Text>
+            <LineChart
+              data={series}
+              axes={{
+                x: { field: "date", fieldType: "datetime", label: "Day" },
+                y: { field: "credits", fieldType: "linear", label: "Credits" },
+              }}
+              options={{ showTooltips: true }}
+            />
+          </Flex>
+        </Tile>
+      )}
+    </Flex>
+  );
+}
+
+export default UsageTab;