@growth-operations/ui-shared 1.0.0

package/src/sdk/app/encryption.js

@@ -0,0 +1,98 @@
+// CRM-card field encryption helpers.
+//
+// Used to encrypt small values (e.g. a token or secret) before storing them on a
+// CRM record property, deriving the key from the record's own identity so the
+// ciphertext is scoped to that record. These are generic Web Crypto helpers and
+// are ported as-is — no app-specific names. The PBKDF2 salt is a fixed constant
+// ("hubspot-ats"); it only needs to be stable across encrypt/decrypt, not secret.
+//
+// getKeyFromContext derives the key from `${context.extension.objectTypeId}-${context.crm.objectId}`,
+// so this is only usable in a CRM-card context where context.crm.objectId exists.
+
+// Convert string to base64 (UTF-8 safe).
+export function strToBase64(str) {
+  return btoa(
+    encodeURIComponent(str).replace(/%([0-9A-F]{2})/g, function toSolidBytes(match, p1) {
+      return String.fromCharCode("0x" + p1);
+    })
+  );
+}
+
+// Convert base64 to string (UTF-8 safe).
+export function base64ToStr(str) {
+  return decodeURIComponent(
+    atob(str)
+      .split("")
+      .map(function (c) {
+        return "%" + ("00" + c.charCodeAt(0).toString(16)).slice(-2);
+      })
+      .join("")
+  );
+}
+
+// Convert string to Uint8Array.
+function strToUint8Array(str) {
+  return Uint8Array.from(str.split("").map((ch) => ch.charCodeAt(0)));
+}
+
+// Derive an AES-GCM key bound to the current CRM record.
+export async function getKeyFromContext(context) {
+  const keyMaterial = await crypto.subtle.importKey(
+    "raw",
+    strToUint8Array(`${context.extension.objectTypeId}-${context.crm.objectId}`),
+    { name: "PBKDF2" },
+    false,
+    ["deriveBits", "deriveKey"]
+  );
+
+  return crypto.subtle.deriveKey(
+    {
+      name: "PBKDF2",
+      salt: strToUint8Array("hubspot-ats"),
+      iterations: 100000,
+      hash: "SHA-256",
+    },
+    keyMaterial,
+    { name: "AES-GCM", length: 256 },
+    true,
+    ["encrypt", "decrypt"]
+  );
+}
+
+export async function encrypt(data, context) {
+  const key = await getKeyFromContext(context);
+  const iv = crypto.getRandomValues(new Uint8Array(12));
+  const encodedData = strToUint8Array(JSON.stringify(data));
+
+  const encryptedContent = await crypto.subtle.encrypt(
+    { name: "AES-GCM", iv: iv },
+    key,
+    encodedData
+  );
+
+  // Combine IV and encrypted content.
+  const encryptedArray = new Uint8Array(iv.length + encryptedContent.byteLength);
+  encryptedArray.set(iv);
+  encryptedArray.set(new Uint8Array(encryptedContent), iv.length);
+
+  // Convert to base64 for storage.
+  return strToBase64(String.fromCharCode.apply(null, encryptedArray));
+}
+
+export async function decrypt(encryptedData, context) {
+  const key = await getKeyFromContext(context);
+
+  // Convert from base64 and split IV and content.
+  const encryptedArray = strToUint8Array(base64ToStr(encryptedData));
+  const iv = encryptedArray.slice(0, 12);
+  const content = encryptedArray.slice(12);
+
+  const decryptedContent = await crypto.subtle.decrypt(
+    { name: "AES-GCM", iv: iv },
+    key,
+    content
+  );
+
+  const decoder = new TextDecoder();
+  return JSON.parse(decoder.decode(decryptedContent));
+}

package/src/sdk/app/settings.js

@@ -0,0 +1,65 @@
+// Settings API client with a module-level cache.
+//
+// Two ways to use this:
+//   1. The default getSettings/updateSettings exports — hit /api/v1/settings and
+//      share one module-level cache. Good for the common case.
+//   2. makeSettingsApi({ path }) — build an isolated client with its own cache,
+//      for apps whose settings live at a different path, or that want a cache not
+//      shared with other importers.
+//
+// getSettings accepts { force } to bypass the cache (e.g. polling for live sync
+// status, which a stale cache would otherwise mask). updateSettings invalidates
+// the cache on write.
+//
+// All requests go through callAppApi → hubspot.fetch rules apply (object body,
+// no custom headers).
+import { callAppApi } from "./base";
+
+// Build an isolated settings client with its own module-level cache.
+// path: backend settings endpoint (default "/api/v1/settings").
+export function makeSettingsApi({ path = "/api/v1/settings" } = {}) {
+  let cachedSettings = null;
+  let settingsPromise = null;
+
+  async function getSettings(context, { force = false } = {}) {
+    // Return cached settings if available — unless the caller forces a fresh
+    // read (the cache would otherwise mask live changes).
+    if (!force && cachedSettings) {
+      return cachedSettings;
+    }
+
+    // Return existing in-flight fetch (don't share it with a forced read).
+    if (!force && settingsPromise) {
+      return settingsPromise;
+    }
+
+    const fetchPromise = (async () => {
+      try {
+        const settings = await callAppApi(context, path, "GET");
+        cachedSettings = settings;
+        settingsPromise = null;
+        return settings;
+      } catch (error) {
+        settingsPromise = null;
+        throw error;
+      }
+    })();
+
+    if (!force) settingsPromise = fetchPromise;
+    return fetchPromise;
+  }
+
+  async function updateSettings(context, settings) {
+    const result = await callAppApi(context, path, "PUT", settings);
+    // Invalidate cache when settings are updated.
+    cachedSettings = null;
+    return result;
+  }
+
+  return { getSettings, updateSettings };
+}
+
+// Default client at /api/v1/settings.
+const defaultSettingsApi = makeSettingsApi();
+export const getSettings = defaultSettingsApi.getSettings;
+export const updateSettings = defaultSettingsApi.updateSettings;

package/src/sdk/hubspot/base.js

@@ -0,0 +1,67 @@
+// callHubSpotApi / buildHubSpotUrl — direct calls to HubSpot's public API.
+//
+// For calls that go straight to api.hubapi.com using a short-lived OAuth token
+// (see ../token/getShortLivedToken), rather than through the app's own backend.
+//
+// hubspot.fetch rules enforced here:
+//   - Authorization: Bearer {token} is the ONE client header hubspot.fetch
+//     permits. We send only that.
+//   - `payload` is passed as a plain OBJECT. NEVER JSON.stringify it — hubspot.fetch
+//     serializes it. (This was a latent bug in some app copies, which did
+//     `body: JSON.stringify(payload)` against api.hubapi.com; fixed here.)
+import { hubspot, logger } from "@hubspot/ui-extensions";
+
+export class HubSpotApiError extends Error {
+  constructor(message, statusCode, responseText) {
+    super(message);
+    this.statusCode = statusCode;
+    this.responseText = responseText;
+    this.name = "HubSpotApiError";
+  }
+}
+
+// url:     full HubSpot URL, build with buildHubSpotUrl()
+// token:   short-lived OAuth access token string
+// method:  HTTP method (default "GET")
+// payload: plain object — NOT a JSON string (see header)
+export async function callHubSpotApi(url, token, method = "GET", payload = null) {
+  logger.debug(`[HubSpotApi] ${method} ${url}`);
+
+  const response = await hubspot.fetch(url, {
+    timeout: 30000,
+    method,
+    // Authorization is the only permitted client header.
+    headers: { Authorization: `Bearer ${token}` },
+    // body must be a plain object — hubspot.fetch serializes it. Do NOT
+    // JSON.stringify here.
+    ...(payload && { body: payload }),
+  });
+
+  if (!response.ok) {
+    const errorText = await response.text();
+    logger.error(`[HubSpotApi] Error: ${method} ${url} - Status ${response.status}`);
+
+    // Surface expired-token failures distinctly so callers can refresh + retry.
+    try {
+      const errorJson = JSON.parse(errorText);
+      if (errorJson.category === "EXPIRED_AUTHENTICATION") {
+        logger.warn("[HubSpotApi] Token expired");
+        throw new HubSpotApiError("TOKEN_EXPIRED", response.status, errorText);
+      }
+    } catch (e) {
+      if (e instanceof HubSpotApiError) {
+        throw e;
+      }
+      // body wasn't JSON; fall through to the generic error below
+    }
+    throw new HubSpotApiError(errorText, response.status, errorText);
+  }
+
+  return response.json();
+}
+
+// Build a HubSpot public API URL from an endpoint path, e.g.
+// buildHubSpotUrl("crm/v3/properties/contacts").
+export function buildHubSpotUrl(endpoint) {
+  return `https://api.hubapi.com/${endpoint}`;
+}

package/src/sdk/hubspot/forms.js

@@ -0,0 +1,12 @@
+// HubSpot forms fetcher (for form-selection pickers).
+//
+// Goes through callHubSpotApi → hubspot.fetch rules apply.
+import { buildHubSpotUrl, callHubSpotApi } from "./base";
+
+// context is accepted for signature consistency with the other fetchers (so
+// callers can always pass (context, token, ...)), though forms needs no
+// context fields.
+export async function getForms(context, token) {
+  const url = buildHubSpotUrl("marketing/v3/forms");
+  return callHubSpotApi(url, token);
+}

package/src/sdk/hubspot/lists.js

@@ -0,0 +1,31 @@
+// HubSpot contact-list fetcher (for list-selection pickers).
+//
+// Paginates crm/v3/lists/search until all DYNAMIC lists are collected. The POST
+// body is a plain OBJECT — callHubSpotApi sends it as-is (NEVER JSON.stringify).
+import { buildHubSpotUrl, callHubSpotApi } from "./base";
+
+// context is accepted for signature consistency. query: optional name filter.
+export async function getLists(context, token, query = "") {
+  const url = buildHubSpotUrl("crm/v3/lists/search");
+  const allLists = [];
+  let offset = 0;
+  let hasMore = true;
+  const count = 100; // Max count per request.
+
+  while (hasMore) {
+    const payload = {
+      query: query,
+      count: count,
+      offset: offset,
+      processingTypes: ["DYNAMIC"],
+    };
+
+    const response = await callHubSpotApi(url, token, "POST", payload);
+    allLists.push(...response.lists);
+
+    hasMore = response.hasMore;
+    offset = response.offset;
+  }
+
+  return { lists: allLists };
+}

package/src/sdk/hubspot/pipeline.js

@@ -0,0 +1,103 @@
+// HubSpot pipeline + stage fetchers and a stage-diffing helper.
+//
+// Goes through callHubSpotApi → hubspot.fetch rules apply.
+//
+// Generalization note: the source hardcoded the pipeline object type as
+// `a${context.extension.appId}_application` (an app-specific custom object).
+// Here the object type is a parameter that DEFAULTS to that convention, so
+// existing apps keep working while others can pass their own object type.
+import { buildHubSpotUrl, callHubSpotApi } from "./base";
+
+// Default pipeline object type: the app's "<app>_application" custom object,
+// derived from context.extension.appId (the historical convention).
+function defaultPipelineObjectType(context) {
+  return `a${context.extension.appId}_application`;
+}
+
+export async function getPipelines(context, token, objectType = defaultPipelineObjectType(context)) {
+  const url = buildHubSpotUrl(`crm/v3/pipelines/${objectType}`);
+  return callHubSpotApi(url, token);
+}
+
+export async function getPipelineStages(
+  context,
+  token,
+  pipelineId,
+  objectType = defaultPipelineObjectType(context)
+) {
+  const url = buildHubSpotUrl(`crm/v3/pipelines/${objectType}/${pipelineId}/stages`);
+  return callHubSpotApi(url, token);
+}
+
+// Diff the app's stored stages against HubSpot's current pipeline stages and
+// describe the changes (init / update / null when nothing changed).
+//
+// `makeNewStage` builds the record for a stage that exists in HubSpot but not in
+// the app's stored config. It defaults to { stage_id, name } only; apps that
+// attach extra per-stage data (e.g. a children array) can pass their own factory.
+export function computeStageChanges(
+  currentStages,
+  newPipelineStages,
+  makeNewStage = (stage) => ({ stage_id: stage.id, name: stage.label })
+) {
+  if (!currentStages) {
+    return {
+      type: "init",
+      changes: newPipelineStages.map(makeNewStage),
+    };
+  }
+
+  const existingStagesMap = new Map(
+    currentStages.map((stage) => [stage.stage_id, stage])
+  );
+  const pipelineStagesMap = new Map(
+    newPipelineStages.map((stage) => [stage.id, stage])
+  );
+
+  const stagesToRemove = currentStages.filter(
+    (stage) => !pipelineStagesMap.has(stage.stage_id)
+  );
+
+  const stagesToAdd = [];
+  const stagesToUpdate = [];
+  let hasChanges = false;
+
+  newPipelineStages.forEach((pipelineStage) => {
+    const existingStage = existingStagesMap.get(pipelineStage.id);
+
+    if (existingStage) {
+      if (existingStage.name !== pipelineStage.label) {
+        stagesToUpdate.push({
+          ...existingStage,
+          name: pipelineStage.label,
+          oldName: existingStage.name,
+        });
+        hasChanges = true;
+      }
+    } else {
+      stagesToAdd.push(makeNewStage(pipelineStage));
+      hasChanges = true;
+    }
+  });
+
+  if (stagesToRemove.length > 0 || hasChanges) {
+    return {
+      type: "update",
+      stagesToRemove,
+      stagesToAdd,
+      stagesToUpdate,
+      finalStages: newPipelineStages.map((pipelineStage) => {
+        const existingStage = existingStagesMap.get(pipelineStage.id);
+        if (existingStage) {
+          return {
+            ...existingStage,
+            name: pipelineStage.label,
+          };
+        }
+        return makeNewStage(pipelineStage);
+      }),
+    };
+  }
+
+  return null;
+}

package/src/sdk/hubspot/properties.js

@@ -0,0 +1,50 @@
+// HubSpot property fetchers/writers for field-mapping pickers.
+//
+// All calls go through callHubSpotApi with a short-lived token → hubspot.fetch
+// rules apply (object body, Authorization-only header). The PATCH body is passed
+// as a plain object (NOT JSON.stringify'd).
+import { buildHubSpotUrl, callHubSpotApi } from "./base";
+
+// List the writable properties for a HubSpot object type, shaped for a mapping
+// picker: [{ name, label, type }] sorted by label. Excludes hidden, archived,
+// calculated, and read-only-value properties (a custom mapping can't write to a
+// calculated/read-only property).
+//
+// objectType: the HubSpot CRM object type used in the API path, e.g. "contacts",
+// "orders", "line_items", "products", or a custom object's fully-qualified id.
+export async function getObjectProperties(context, token, objectType) {
+  if (!objectType) return [];
+  const url = buildHubSpotUrl(`crm/v3/properties/${objectType}`);
+  const response = await callHubSpotApi(url, token);
+  return (response.results || [])
+    .filter(
+      (prop) =>
+        !prop.hidden &&
+        !prop.archived &&
+        !prop.calculated &&
+        !prop.modificationMetadata?.readOnlyValue
+    )
+    .map((prop) => ({
+      name: prop.name,
+      label: prop.label || prop.name,
+      type: prop.type,
+    }))
+    .sort((a, b) => a.label.localeCompare(b.label));
+}
+
+// Raw property list for an object type (unfiltered) — when you need the full
+// HubSpot response rather than the picker-shaped subset.
+export async function getProperties(context, token, objectType) {
+  const url = buildHubSpotUrl(`crm/v3/properties/${objectType}`);
+  return callHubSpotApi(url, token, "GET");
+}
+
+// PATCH properties onto the current CRM record (CRM-card context only — relies
+// on context.crm.objectTypeId / context.crm.objectId).
+export async function updateProperties(context, token, properties) {
+  const url = buildHubSpotUrl(
+    `crm/v3/objects/${context.crm.objectTypeId}/${context.crm.objectId}`
+  );
+  // properties is wrapped in a plain object — callHubSpotApi sends it as-is.
+  return callHubSpotApi(url, token, "PATCH", { properties });
+}

package/src/sdk/index.js

@@ -0,0 +1,33 @@
+// Growth Ops HubSpot app SDK — the token + API utility layer every token-using
+// app reimplements, generalized to be app-agnostic. See README "SDK" section.
+
+// App backend (context.variables.BASE_URL) via hubspot.fetch.
+export { callAppApi, AppApiError } from "./app/base";
+export { getAlerts, dismissAlert } from "./app/alerts";
+export { getSettings, updateSettings, makeSettingsApi } from "./app/settings";
+export {
+  strToBase64,
+  base64ToStr,
+  getKeyFromContext,
+  encrypt,
+  decrypt,
+} from "./app/encryption";
+
+// HubSpot public API (api.hubapi.com) via a short-lived OAuth token.
+export { callHubSpotApi, buildHubSpotUrl, HubSpotApiError } from "./hubspot/base";
+export {
+  getObjectProperties,
+  getProperties,
+  updateProperties,
+} from "./hubspot/properties";
+export { getForms } from "./hubspot/forms";
+export { getLists } from "./hubspot/lists";
+export {
+  getPipelines,
+  getPipelineStages,
+  computeStageChanges,
+} from "./hubspot/pipeline";
+
+// Token lifecycle.
+export { getShortLivedToken, isTokenExpired } from "./token/getShortLivedToken";
+export { TokenProvider, useToken, TokenContext } from "./token/TokenContext";

package/src/sdk/token/TokenContext.jsx

@@ -0,0 +1,89 @@
+// TokenContext / TokenProvider / useToken — short-lived HubSpot token lifecycle.
+//
+// Wrap a tree in <TokenProvider context={context}> and any descendant can call
+// useToken().ensureValidToken() to get a valid short-lived OAuth token, fetching
+// a fresh one only when the cached one is missing or expired. The token data is
+// held at module level (not React state) so it survives remounts and never
+// triggers re-renders.
+//
+// The fetch goes through callAppApi (GET /api/v1/tokens/short-lived?portalId=...),
+// so the hubspot.fetch rules live in app/base.js. The backend returns a token
+// object exposing the access token as `token` (alias) / `access_token`, plus an
+// `expires_at` epoch-seconds field used for cache invalidation.
+import { createContext, useContext } from "react";
+import { callAppApi } from "../app/base";
+import { isTokenExpired } from "./getShortLivedToken";
+
+const TokenContext = createContext(null);
+
+// Module-level cache — doesn't cause re-renders, survives component remounts.
+let cachedTokenData = null;
+let tokenPromise = null;
+let appContext = null;
+
+// Fetch the full short-lived token object (token string + expires_at) for the
+// current portal.
+async function fetchTokenData(context) {
+  const portalId = context?.portal?.id;
+  const query = portalId ? `?portalId=${portalId}` : "";
+  return callAppApi(context, `/api/v1/tokens/short-lived${query}`, "GET");
+}
+
+// Return a valid access token string, fetching a fresh one if the cache is empty
+// or expired. Concurrent callers share one in-flight fetch.
+const ensureValidToken = async () => {
+  if (cachedTokenData && !isTokenExpired(cachedTokenData)) {
+    return cachedTokenData.token || cachedTokenData.access_token;
+  }
+
+  if (tokenPromise) return tokenPromise;
+
+  tokenPromise = (async () => {
+    try {
+      const freshTokenData = await fetchTokenData(appContext);
+      cachedTokenData = freshTokenData;
+      tokenPromise = null;
+      return freshTokenData.token || freshTokenData.access_token;
+    } catch (err) {
+      tokenPromise = null;
+      throw err;
+    }
+  })();
+
+  return tokenPromise;
+};
+
+// Force a refresh on the next ensureValidToken() call.
+const invalidateToken = () => {
+  cachedTokenData = null;
+  tokenPromise = null;
+};
+
+// Stable context value — never changes identity, so it won't re-render consumers.
+const stableValue = {
+  ensureValidToken,
+  invalidateToken,
+  token: null,
+  loading: false,
+  error: null,
+};
+
+export function useToken() {
+  const context = useContext(TokenContext);
+  if (!context) {
+    throw new Error("useToken must be used within a TokenProvider");
+  }
+  return context;
+}
+
+export function TokenProvider({ children, context }) {
+  // Stash the extension context at module level so the token functions (which
+  // live outside React) can reach it.
+  appContext = context;
+
+  return (
+    <TokenContext.Provider value={stableValue}>{children}</TokenContext.Provider>
+  );
+}
+
+export { TokenContext };

package/src/sdk/token/getShortLivedToken.js

@@ -0,0 +1,24 @@
+// getShortLivedToken — fetch a short-lived HubSpot OAuth token from the app
+// backend for the current portal.
+//
+// Hits GET /api/v1/tokens/short-lived?portalId=... via callAppApi (so the
+// hubspot.fetch rules are handled there). Returns the bare token string; the
+// backend's Token model exposes the access token as `token` (aliased), with
+// access_token as a fallback for safety.
+import { callAppApi } from "../app/base";
+
+export async function getShortLivedToken(context) {
+  const portalId = context?.portal?.id;
+  const query = portalId ? `?portalId=${portalId}` : "";
+  const result = await callAppApi(
+    context,
+    `/api/v1/tokens/short-lived${query}`,
+    "GET"
+  );
+  return result.token || result.access_token;
+}
+
+// Is a token-data object (with an `expires_at` epoch-seconds field) past expiry?
+export function isTokenExpired(tokenData) {
+  return Date.now() / 1000 > tokenData.expires_at;
+}