@hubspot/app-connect-sdk 1.0.0-alpha.2 → 1.0.0-alpha.21

package/src/browser/app-connect-controller/utils/session-utils.test.ts

@@ -1,7 +1,8 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
 import { noopLogger } from '../../../shared/logger.ts';
-import { EXPIRES_AT_KEY } from '../constants.ts';
+import type { AuthCompleteWhoami } from '../../../shared/wire-types.ts';
+import { SESSION_STORAGE_KEY } from '../constants.ts';
 import type {
   AppConnectContext,
   AppConnectInternalState,
@@ -9,9 +10,10 @@ import type {
 } from '../types.ts';
 import {
   clearSessionStorage,
-  getExpiresAtFromSessionStorage,
+  getSessionFromSessionStorage,
   isClientSessionActive,
   storeExpiresAt,
+  storeSession,
 } from './session-utils.ts';
 import { createStore } from './store-utils.ts';
 
@@ -36,6 +38,7 @@ function createTestContext(): AppConnectContext {
     isDisconnectInFlight: false,
     error: null,
     expiresAt: null,
+    whoami: null,
   };
   return {
     config: { hubSpotConnectBaseUrl: '/functions/v1/hubspot-connect' },
@@ -45,6 +48,14 @@ function createTestContext(): AppConnectContext {
   };
 }
 
+const MOCK_WHOAMI: AuthCompleteWhoami = {
+  user: { id: '99', email: 'demo@example.com', firstName: 'Demo' },
+  hub: {
+    id: 42,
+    uiDomain: 'app.hubspot.com',
+  },
+};
+
 describe('session-utils', () => {
   const FIXED_NOW = 1_700_000_000_000;
 
@@ -57,52 +68,92 @@ describe('session-utils', () => {
     vi.useRealTimers();
   });
 
+  describe('storeSession', () => {
+    it('writes expiresAt and whoami to both store and session storage', () => {
+      const context = createTestContext();
+      storeSession({
+        context,
+        expiresAtMs: FIXED_NOW + 60_000,
+        whoami: MOCK_WHOAMI,
+      });
+
+      expect(context.store.getSnapshot().expiresAt).toBe(FIXED_NOW + 60_000);
+      expect(context.store.getSnapshot().whoami).toEqual(MOCK_WHOAMI);
+      const stored = JSON.parse(
+        context.sessionStorage.getItem(SESSION_STORAGE_KEY)!
+      );
+      expect(stored.expiresAt).toBe(FIXED_NOW + 60_000);
+      expect(stored.whoami).toEqual(MOCK_WHOAMI);
+    });
+  });
+
   describe('storeExpiresAt', () => {
-    it('writes both the store and session storage', () => {
+    it('updates expiresAt in store and storage while preserving existing whoami', () => {
       const context = createTestContext();
+      context.store.setState({ whoami: MOCK_WHOAMI });
+
       storeExpiresAt({ context, expiresAtMs: FIXED_NOW + 60_000 });
 
       expect(context.store.getSnapshot().expiresAt).toBe(FIXED_NOW + 60_000);
-      expect(context.sessionStorage.getItem(EXPIRES_AT_KEY)).toBe(
-        String(FIXED_NOW + 60_000)
+      expect(context.store.getSnapshot().whoami).toEqual(MOCK_WHOAMI);
+      const stored = JSON.parse(
+        context.sessionStorage.getItem(SESSION_STORAGE_KEY)!
       );
+      expect(stored.expiresAt).toBe(FIXED_NOW + 60_000);
+      expect(stored.whoami).toEqual(MOCK_WHOAMI);
     });
   });
 
-  describe('getExpiresAtFromSessionStorage', () => {
+  describe('getSessionFromSessionStorage', () => {
     it('returns null when nothing is stored', () => {
       const context = createTestContext();
-      expect(getExpiresAtFromSessionStorage(context)).toBeNull();
+      expect(getSessionFromSessionStorage(context)).toBeNull();
     });
 
-    it('returns the stored value when in the future', () => {
+    it('returns the stored session when expiresAt is in the future', () => {
       const context = createTestContext();
-      const expiresAt = FIXED_NOW + 60_000;
-      context.sessionStorage.setItem(EXPIRES_AT_KEY, String(expiresAt));
-      expect(getExpiresAtFromSessionStorage(context)).toBe(expiresAt);
+      const session = { expiresAt: FIXED_NOW + 60_000, whoami: MOCK_WHOAMI };
+      context.sessionStorage.setItem(
+        SESSION_STORAGE_KEY,
+        JSON.stringify(session)
+      );
+      expect(getSessionFromSessionStorage(context)).toEqual(session);
     });
 
-    it('clears and returns null on malformed input', () => {
+    it('clears and returns null on malformed JSON', () => {
       const context = createTestContext();
-      context.sessionStorage.setItem(EXPIRES_AT_KEY, 'not-a-number');
-      expect(getExpiresAtFromSessionStorage(context)).toBeNull();
-      expect(context.sessionStorage.getItem(EXPIRES_AT_KEY)).toBeNull();
+      context.sessionStorage.setItem(SESSION_STORAGE_KEY, 'not-json');
+      expect(getSessionFromSessionStorage(context)).toBeNull();
+      expect(context.sessionStorage.getItem(SESSION_STORAGE_KEY)).toBeNull();
     });
 
-    it('clears and returns null on already-expired values', () => {
+    it('clears and returns null when expiresAt is not a number', () => {
       const context = createTestContext();
-      context.sessionStorage.setItem(EXPIRES_AT_KEY, String(FIXED_NOW - 1));
-      expect(getExpiresAtFromSessionStorage(context)).toBeNull();
-      expect(context.sessionStorage.getItem(EXPIRES_AT_KEY)).toBeNull();
+      context.sessionStorage.setItem(
+        SESSION_STORAGE_KEY,
+        JSON.stringify({ expiresAt: 'bad', whoami: null })
+      );
+      expect(getSessionFromSessionStorage(context)).toBeNull();
+      expect(context.sessionStorage.getItem(SESSION_STORAGE_KEY)).toBeNull();
+    });
+
+    it('clears and returns null when the session is already expired', () => {
+      const context = createTestContext();
+      context.sessionStorage.setItem(
+        SESSION_STORAGE_KEY,
+        JSON.stringify({ expiresAt: FIXED_NOW - 1, whoami: null })
+      );
+      expect(getSessionFromSessionStorage(context)).toBeNull();
+      expect(context.sessionStorage.getItem(SESSION_STORAGE_KEY)).toBeNull();
     });
   });
 
   describe('clearSessionStorage', () => {
-    it('removes the persisted expiresAt key', () => {
+    it('removes the session storage key', () => {
       const context = createTestContext();
-      context.sessionStorage.setItem(EXPIRES_AT_KEY, '123');
+      context.sessionStorage.setItem(SESSION_STORAGE_KEY, '{}');
       clearSessionStorage(context);
-      expect(context.sessionStorage.getItem(EXPIRES_AT_KEY)).toBeNull();
+      expect(context.sessionStorage.getItem(SESSION_STORAGE_KEY)).toBeNull();
     });
   });
 

package/src/browser/app-connect-controller/utils/session-utils.ts

@@ -1,55 +1,96 @@
-import { EXPIRES_AT_KEY } from '../constants.ts';
+import type { AuthCompleteWhoami } from '../../../shared/wire-types.ts';
+import { SESSION_STORAGE_KEY } from '../constants.ts';
 import type { AppConnectContext } from '../types.ts';
 
-interface StoreExpiresAtOptions {
-  context: AppConnectContext;
-  expiresAtMs: number;
+interface StoredSession {
+  expiresAt: number;
+  whoami: AuthCompleteWhoami | null;
+}
+
+function readStoredSession(context: AppConnectContext): StoredSession | null {
+  const raw = context.sessionStorage.getItem(SESSION_STORAGE_KEY);
+  if (!raw) return null;
+  let parsed: StoredSession;
+  try {
+    parsed = JSON.parse(raw) as StoredSession;
+  } catch {
+    context.sessionStorage.removeItem(SESSION_STORAGE_KEY);
+    return null;
+  }
+  if (typeof parsed.expiresAt !== 'number' || isNaN(parsed.expiresAt)) {
+    context.sessionStorage.removeItem(SESSION_STORAGE_KEY);
+    return null;
+  }
+  if (Date.now() > parsed.expiresAt) {
+    context.sessionStorage.removeItem(SESSION_STORAGE_KEY);
+    return null;
+  }
+  return parsed;
+}
+
+function writeStoredSession(
+  context: AppConnectContext,
+  session: StoredSession
+): void {
+  context.sessionStorage.setItem(SESSION_STORAGE_KEY, JSON.stringify(session));
 }
 
 /**
- * Persists the access-token `expiresAt` (Unix epoch milliseconds) to
- * both the in-memory store and `sessionStorage` so it survives
- * full-page navigations within the same tab.
+ * Reads the persisted session blob from `sessionStorage`. Returns
+ * `null` (and auto-removes the entry) if the blob is missing,
+ * malformed, or already expired.
  */
-export function storeExpiresAt(options: StoreExpiresAtOptions): void {
-  const { context, expiresAtMs } = options;
-  context.store.setState({ expiresAt: expiresAtMs });
-  context.sessionStorage.setItem(EXPIRES_AT_KEY, String(expiresAtMs));
+export function getSessionFromSessionStorage(
+  context: AppConnectContext
+): StoredSession | null {
+  return readStoredSession(context);
 }
 
 /**
- * Reads the persisted `expiresAt` from `sessionStorage`. Removes the
- * value (and returns `null`) if it is malformed or already expired,
- * so a stale entry never reactivates a dead session.
+ * Persists both `expiresAt` and `whoami` to the in-memory store and
+ * `sessionStorage` as a single JSON blob. Called from `init.ts` after
+ * a successful OAuth token exchange.
  */
-export function getExpiresAtFromSessionStorage(
-  context: AppConnectContext
-): number | null {
-  const raw = context.sessionStorage.getItem(EXPIRES_AT_KEY);
-  if (!raw) return null;
-  const val = parseInt(raw, 10);
-  if (isNaN(val)) {
-    context.sessionStorage.removeItem(EXPIRES_AT_KEY);
-    return null;
-  }
-  if (Date.now() > val) {
-    context.sessionStorage.removeItem(EXPIRES_AT_KEY);
-    return null;
-  }
-  return val;
+export function storeSession(options: {
+  context: AppConnectContext;
+  expiresAtMs: number;
+  whoami: AuthCompleteWhoami;
+}): void {
+  const { context, expiresAtMs, whoami } = options;
+  context.store.setState({ expiresAt: expiresAtMs, whoami });
+  writeStoredSession(context, { expiresAt: expiresAtMs, whoami });
+}
+
+/**
+ * Updates only `expiresAt` in both the store and `sessionStorage`,
+ * preserving the existing `whoami` from in-memory store state. Called
+ * from `refresh.ts` after a successful token refresh.
+ */
+export function storeExpiresAt(options: {
+  context: AppConnectContext;
+  expiresAtMs: number;
+}): void {
+  const { context, expiresAtMs } = options;
+  const currentWhoami = context.store.getSnapshot().whoami;
+  context.store.setState({ expiresAt: expiresAtMs });
+  writeStoredSession(context, {
+    expiresAt: expiresAtMs,
+    whoami: currentWhoami,
+  });
 }
 
 /**
- * Clears the persisted session-storage state. Called on disconnect.
+ * Removes the single session-storage key, clearing all persisted
+ * session state. Called on disconnect and on auth-complete errors.
  */
 export function clearSessionStorage(context: AppConnectContext): void {
-  context.sessionStorage.removeItem(EXPIRES_AT_KEY);
+  context.sessionStorage.removeItem(SESSION_STORAGE_KEY);
 }
 
 /**
  * Returns `true` when the controller has an `expiresAt` whose value
- * is still in the future. Used both to drive the UI status and to
- * decide whether the refresh scheduler should run.
+ * is still in the future. Used to drive the UI status and the refresh
+ * scheduler.
  */
 export function isClientSessionActive(context: AppConnectContext): boolean {
   const state = context.store.getSnapshot();

package/src/browser/app-connect-controller/view-state.test.ts

@@ -13,6 +13,7 @@ function makeState(
     isDisconnectInFlight: false,
     error: null,
     expiresAt: null,
+    whoami: null,
     ...overrides,
   };
 }

package/src/browser/app-connect-controller/view-state.ts

@@ -11,6 +11,7 @@ const noop = (): Promise<void> => Promise.resolve();
 export const SERVER_VIEW: AppConnectState = {
   status: 'initializing',
   error: null,
+  whoami: null,
   connectToHubSpot: noop,
   disconnectFromHubSpot: noop,
 };

package/src/browser/index.ts

@@ -10,4 +10,5 @@ export {
   type AppConnectController,
   type AppConnectState,
   type AppConnectStatus,
+  type OAuthConnectMode,
 } from './types.ts';

package/src/browser/react/components/AppConnectHeader/AppConnectHeader.tsx

@@ -9,34 +9,14 @@ import { LogoutIcon } from '../icons/LogoutIcon.tsx';
 import { ShareButton } from '../ShareButton/ShareButton.tsx';
 import { styles } from './AppConnectHeader.css.ts';
 
-interface FakeUser {
-  firstName: string;
-  lastName: string;
-  email: string;
-}
-
-const FAKE_USER: FakeUser = {
-  firstName: 'Gabby',
-  lastName: 'Martinez',
-  email: 'gabby.martinez@acmecorp.com',
-};
-
-function getUserInitials(user: FakeUser): string {
-  const first = user.firstName.charAt(0).toUpperCase();
-  const last = user.lastName.charAt(0).toUpperCase();
-  return `${first}${last}`;
-}
-
-function getFullName(user: FakeUser): string {
-  return `${user.firstName} ${user.lastName}`;
-}
-
 interface AppConnectHeaderProps {
   title: string;
 }
 
 export function AppConnectHeader({ title }: AppConnectHeaderProps) {
   const { status } = useHubSpotAppConnect();
+  const connectButton =
+    status === 'initializing' ? null : <ConnectButton variant="secondary" />;
   return (
     <header className={styles.header}>
       <div className={styles.titleRow}>
@@ -48,16 +28,14 @@ export function AppConnectHeader({ title }: AppConnectHeaderProps) {
           {status === 'connected' ? <ViewingHubSpotContextRow /> : null}
         </div>
       </div>
-      {status === 'connected' ? (
-        <UserMenu />
-      ) : (
-        <ConnectButton variant="secondary" />
-      )}
+      {status === 'connected' ? <UserMenu /> : connectButton}
     </header>
   );
 }
 
 function ViewingHubSpotContextRow() {
+  const { whoami } = useHubSpotAppConnect();
+  const hubLabel = whoami?.hub?.domain ?? whoami?.hub?.id ?? 'HubSpot';
   return (
     <div className={styles.contextRow}>
       <HubSpotDataSourceIcon className={styles.contextIcon} />
@@ -69,7 +47,7 @@ function ViewingHubSpotContextRow() {
           event.preventDefault();
         }}
       >
-        Acme Corp · HubSpot
+        {hubLabel}
         <ExternalLinkIcon className={styles.contextExternalIcon} />
       </a>
     </div>
@@ -77,9 +55,16 @@ function ViewingHubSpotContextRow() {
 }
 
 function UserMenu() {
-  const { disconnectFromHubSpot } = useHubSpotAppConnect();
-  const initials = getUserInitials(FAKE_USER);
-  const fullName = getFullName(FAKE_USER);
+  const { whoami, disconnectFromHubSpot } = useHubSpotAppConnect();
+  const user = whoami?.user;
+  const nameParts = [user?.firstName, user?.lastName].filter(
+    (p): p is string => typeof p === 'string' && p.length > 0
+  );
+  const initials =
+    nameParts.map((n) => n[0]!.toUpperCase()).join('') ||
+    user?.email?.[0]?.toUpperCase() ||
+    '?';
+  const displayName = nameParts.join(' ') || user?.email || 'HubSpot User';
 
   return (
     <Menu.Root modal={false}>
@@ -90,7 +75,7 @@ function UserMenu() {
         >
           {initials}
         </span>
-        <span className={styles.triggerName}>{fullName}</span>
+        <span className={styles.triggerName}>{displayName}</span>
         <ChevronDownIcon className={styles.chevron} />
       </Menu.Trigger>
       <Menu.Portal>
@@ -104,8 +89,10 @@ function UserMenu() {
                 {initials}
               </span>
               <div className={styles.userInfoText}>
-                <span className={styles.userInfoName}>{fullName}</span>
-                <span className={styles.userInfoEmail}>{FAKE_USER.email}</span>
+                <span className={styles.userInfoName}>{displayName}</span>
+                {user?.email ? (
+                  <span className={styles.userInfoEmail}>{user.email}</span>
+                ) : null}
               </div>
             </div>
             <Menu.Separator className={styles.separator} />

package/src/browser/react/components/ConnectButton/ConnectButton.tsx

@@ -20,7 +20,7 @@ export function ConnectButton({
   className,
 }: ConnectButtonProps) {
   const { status, connectToHubSpot } = useHubSpotAppConnect();
-  const isConnecting = status === 'connecting';
+  const isConnecting = status === 'connecting' || status === 'initializing';
   const composedClassName = [root, className].filter(Boolean).join(' ');
   const labelClassName = isConnecting ? `${label} ${labelMuted}` : label;
   return (

package/src/browser/react/lovable/LovableHubSpotAppConnect.tsx

@@ -1,7 +1,7 @@
 import { useRef, type ReactNode } from 'react';
 
 import { createAppConnectController } from '../../app-connect-controller/create.ts';
-import type { AppConnectController } from '../../types.ts';
+import type { AppConnectController, OAuthConnectMode } from '../../types.ts';
 import { HubSpotAppConnect } from '../components/HubSpotAppConnect/HubSpotAppConnect.tsx';
 
 /**
@@ -17,6 +17,12 @@ export interface LovableHubSpotAppConnectProps {
    * @example `${import.meta.env.VITE_SUPABASE_URL}/functions/v1/hubspot-connect`
    */
   hubSpotConnectBaseUrl: string;
+  /**
+   * How connect navigates to HubSpot OAuth. Defaults to `'auto'` (popup
+   * when embedded in an iframe). Set to `'popup'` to test the popup flow
+   * without embedding.
+   */
+  oauthConnectMode?: OAuthConnectMode;
   /** Title text rendered in the standard SDK header. */
   title: string;
   /** Content rendered when the controller is in the `connected` state. */
@@ -38,6 +44,7 @@ export interface LovableHubSpotAppConnectProps {
  */
 export function LovableHubSpotAppConnect({
   hubSpotConnectBaseUrl,
+  oauthConnectMode,
   title,
   connected,
   disconnectedMessage,
@@ -50,7 +57,10 @@ export function LovableHubSpotAppConnect({
   const controllerRef = useRef<AppConnectController | null>(null);
   if (controllerRef.current === null) {
     controllerRef.current = createAppConnectController({
-      config: { hubSpotConnectBaseUrl },
+      config: {
+        hubSpotConnectBaseUrl,
+        oauthConnectMode: oauthConnectMode || 'auto',
+      },
     });
   }
   return (

package/src/browser/types.ts

@@ -1,3 +1,11 @@
+import type { AuthCompleteWhoami } from '../shared/wire-types.ts';
+
+/**
+ * How the browser navigates to HubSpot's OAuth authorize endpoint when
+ * the user calls `connectToHubSpot`.
+ */
+export type OAuthConnectMode = 'auto' | 'redirect' | 'popup';
+
 /**
  * Runtime configuration for an `AppConnectController`. The browser
  * controller uses these URLs to talk to the SDK's server-side OAuth
@@ -11,6 +19,15 @@ export interface AppConnectBrowserConfig {
    * @example '/functions/v1/hubspot-connect'
    */
   hubSpotConnectBaseUrl: string;
+  /**
+   * Controls whether connect uses a full-page redirect or a popup.
+   *
+   * - `'auto'` (default): popup when the app is embedded in an iframe,
+   *   full-page redirect otherwise.
+   * - `'redirect'`: always full-page redirect.
+   * - `'popup'`: always open a popup (useful for local iframe testing).
+   */
+  oauthConnectMode?: OAuthConnectMode;
 }
 
 /**
@@ -19,8 +36,7 @@ export interface AppConnectBrowserConfig {
  *
  * - `initializing`: the controller hasn't finished `start()` yet.
  * - `disconnected`: no active session, ready to call `connectToHubSpot`.
- * - `connecting`: a connect flow is in flight (the browser is about
- *   to redirect to HubSpot).
+ * - `connecting`: a connect flow is in flight (redirect or OAuth popup).
  * - `connected`: a refresh-token cookie is present and the access
  *   token is being refreshed in the background.
  * - `disconnecting`: a `disconnectFromHubSpot()` call is in flight.
@@ -42,9 +58,18 @@ export interface AppConnectState {
   /** Last error message that occurred, or `null` if no error. */
   error: string | null;
   /**
-   * Begins the OAuth connect flow. On success the browser redirects
-   * to HubSpot's authorize endpoint; the promise resolves before the
-   * redirect.
+   * Identity of the connected HubSpot user and their account. Populated
+   * after a successful OAuth flow on a best-effort basis (fields may be
+   * absent if the access token lacked the required scopes). `null` before
+   * connect or after disconnect.
+   */
+  whoami: AuthCompleteWhoami | null;
+  /**
+   * Begins the OAuth connect flow. On success the browser either
+   * redirects to HubSpot's authorize endpoint or opens it in a popup
+   * (when embedded in an iframe or when `oauthConnectMode` is
+   * `'popup'`). The promise resolves when the popup flow completes, or
+   * just before a full-page redirect begins.
    */
   connectToHubSpot: () => Promise<void>;
   /**