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

package/src/browser/app-connect-controller/connect-start.test.ts

@@ -0,0 +1,157 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { noopLogger } from '../../shared/logger.ts';
+import { startHubSpotConnection } from './connect-start.ts';
+import type {
+  AppConnectContext,
+  AppConnectInternalState,
+  SessionStorage,
+} from './types.ts';
+import { createStore } from './utils/store-utils.ts';
+
+const HUBSPOT_CONNECT_BASE_URL =
+  'https://edge.example.com/functions/v1/hubspot-connect';
+
+function createInMemorySessionStorage(): SessionStorage {
+  const map = new Map<string, string>();
+  return {
+    getItem: (key) => map.get(key) ?? null,
+    setItem: (key, value) => {
+      map.set(key, value);
+    },
+    removeItem: (key) => {
+      map.delete(key);
+    },
+  };
+}
+
+function createTestContext(
+  oauthConnectMode?: AppConnectContext['config']['oauthConnectMode']
+): AppConnectContext {
+  const initialState: AppConnectInternalState = {
+    isInitComplete: true,
+    isConnectInFlight: true,
+    isSessionConnected: false,
+    isDisconnectInFlight: false,
+    error: null,
+    expiresAt: null,
+    whoami: null,
+  };
+  return {
+    config: {
+      hubSpotConnectBaseUrl: HUBSPOT_CONNECT_BASE_URL,
+      ...(oauthConnectMode !== undefined ? { oauthConnectMode } : {}),
+    },
+    logger: noopLogger,
+    sessionStorage: createInMemorySessionStorage(),
+    store: createStore<AppConnectInternalState>(initialState),
+  };
+}
+
+describe('startHubSpotConnection', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.restoreAllMocks();
+    vi.useRealTimers();
+  });
+
+  it('redirects the browser when oauthConnectMode is redirect', async () => {
+    const top = {};
+    const location = {
+      origin: 'https://app.example.com',
+      pathname: '/dashboard',
+      search: '?tab=1',
+      href: '',
+    };
+    vi.stubGlobal('window', {
+      self: top,
+      top,
+      location,
+      open: vi.fn(),
+      addEventListener: vi.fn(),
+      removeEventListener: vi.fn(),
+    });
+    vi.spyOn(globalThis, 'fetch').mockResolvedValue(
+      new Response(
+        JSON.stringify({
+          authorization_url: 'https://auth.example/authorize',
+        }),
+        { status: 200 }
+      )
+    );
+
+    const context = createTestContext('redirect');
+    const connectPromise = startHubSpotConnection(context);
+    await vi.advanceTimersByTimeAsync(500);
+    await connectPromise;
+
+    expect(location.href).toBe('https://auth.example/authorize');
+    expect(window.open).not.toHaveBeenCalled();
+  });
+
+  it('opens a popup when oauthConnectMode is popup', async () => {
+    const top = {};
+    const popup = { closed: false, close: vi.fn() };
+    const messageListeners: Array<(event: MessageEvent) => void> = [];
+
+    vi.stubGlobal('window', {
+      self: top,
+      top,
+      location: {
+        origin: 'https://app.example.com',
+        pathname: '/dashboard',
+        search: '',
+      },
+      open: vi.fn(() => popup),
+      addEventListener: (
+        type: string,
+        listener: (event: MessageEvent) => void
+      ) => {
+        if (type === 'message') messageListeners.push(listener);
+      },
+      removeEventListener: vi.fn(),
+    });
+    const expiresAt = Date.now() + 1800 * 1000;
+    vi.spyOn(globalThis, 'fetch')
+      .mockResolvedValueOnce(
+        new Response(
+          JSON.stringify({
+            authorization_url: 'https://auth.example/authorize',
+          }),
+          { status: 200 }
+        )
+      )
+      .mockResolvedValueOnce(
+        new Response(
+          JSON.stringify({ expires_at: expiresAt, return_path: '/dashboard' }),
+          { status: 200 }
+        )
+      );
+
+    const context = createTestContext('popup');
+    const connectPromise = startHubSpotConnection(context);
+    await vi.advanceTimersByTimeAsync(500);
+
+    expect(window.open).toHaveBeenCalledWith(
+      'https://auth.example/authorize',
+      expect.any(String),
+      expect.stringContaining('popup=yes')
+    );
+
+    messageListeners[0]!({
+      origin: 'https://app.example.com',
+      data: {
+        type: 'hubspot-app-connect:oauth-callback',
+        code: 'auth-code',
+        state: 'auth-state',
+      },
+    } as MessageEvent);
+
+    await connectPromise;
+    expect(context.store.getSnapshot().expiresAt).toBe(expiresAt);
+  });
+});

package/src/browser/app-connect-controller/connect-start.ts

@@ -1,5 +1,7 @@
 import type { InitSessionResponse } from '../../shared/wire-types.ts';
+import { waitForHubSpotOAuthPopup } from './oauth-popup.ts';
 import type { AppConnectContext } from './types.ts';
+import { resolveOAuthConnectMode } from './utils/resolve-oauth-connect-mode.ts';
 import { delay } from './utils/timeout-utils.ts';
 
 /** Extra wait before redirect so the connect progress UI is visible; set to `0` to disable. */
@@ -10,12 +12,14 @@ const ARTIFICIAL_CONNECT_REDIRECT_DELAY_MS = 500;
  *
  * 1. Calls the SDK's `auth/init-session` route to mint a fresh PKCE
  *    verifier + state and obtain HubSpot's `authorize` URL.
- * 2. Navigates the browser to that URL (full-page redirect).
+ * 2. Navigates to that URL via full-page redirect, or opens it in a
+ *    popup when embedded in an iframe or when `oauthConnectMode` is
+ *    `'popup'`.
  *
  * The `return_path` is the current path + query so the user lands
- * back where they started after authorizing.
+ * back where they started after authorizing (redirect mode only).
  *
- * Throws when the init call fails. Does not return after the redirect
+ * Throws when the init call fails. Does not return after a redirect
  * begins because the page is unloaded.
  */
 export async function startHubSpotConnection(
@@ -41,5 +45,16 @@ export async function startHubSpotConnection(
 
   await delay(ARTIFICIAL_CONNECT_REDIRECT_DELAY_MS);
 
+  const connectMode = resolveOAuthConnectMode(
+    config.oauthConnectMode !== undefined
+      ? { oauthConnectMode: config.oauthConnectMode }
+      : {}
+  );
+
+  if (connectMode === 'popup') {
+    await waitForHubSpotOAuthPopup({ context, authorizationUrl });
+    return;
+  }
+
   window.location.href = authorizationUrl;
 }

package/src/browser/app-connect-controller/constants.ts

@@ -1,11 +1,13 @@
 export { EXPIRES_AT_URL_PARAM } from '../../shared/constants.ts';
 
 /**
- * Key the controller persists the access-token `expiresAt` (Unix
- * epoch milliseconds) under in `sessionStorage`. Survives full-page
- * navigations within the same tab.
+ * Key under which the controller persists the entire session blob
+ * (expiresAt + whoami) as a single JSON string in `sessionStorage`.
+ * Using one key makes logout trivially correct — one `removeItem` call
+ * clears all session state. Survives full-page navigations within the
+ * same tab.
  */
-export const EXPIRES_AT_KEY = 'hubspot_token_expires_at';
+export const SESSION_STORAGE_KEY = 'hubspot_connect_session';
 
 /**
  * Number of milliseconds before `expiresAt` that the refresh

package/src/browser/app-connect-controller/create.ts

@@ -16,7 +16,7 @@ import type {
 } from './types.ts';
 import { memoizeLast } from './utils/memoize-utils.ts';
 import {
-  getExpiresAtFromSessionStorage,
+  getSessionFromSessionStorage,
   isClientSessionActive,
 } from './utils/session-utils.ts';
 import { createStore } from './utils/store-utils.ts';
@@ -54,6 +54,7 @@ export function createAppConnectController(
     isSessionConnected: false,
     error: null,
     expiresAt: null,
+    whoami: null,
   });
   const context: AppConnectContext = {
     config,
@@ -62,7 +63,11 @@ export function createAppConnectController(
     store,
   };
 
-  store.setState({ expiresAt: getExpiresAtFromSessionStorage(context) });
+  const storedSession = getSessionFromSessionStorage(context);
+  store.setState({
+    expiresAt: storedSession?.expiresAt ?? null,
+    whoami: storedSession?.whoami ?? null,
+  });
 
   let hasStarted = false;
 
@@ -90,6 +95,7 @@ export function createAppConnectController(
   >((storeState) => ({
     status: getDerivedStatus(storeState),
     error: storeState.error,
+    whoami: storeState.whoami,
     connectToHubSpot,
     disconnectFromHubSpot,
   }));

package/src/browser/app-connect-controller/disconnect.ts

@@ -1,4 +1,3 @@
-import type { LogoutResponse } from '../../shared/wire-types.ts';
 import type { AppConnectContext } from './types.ts';
 import { clearSessionStorage } from './utils/session-utils.ts';
 
@@ -8,8 +7,8 @@ import { clearSessionStorage } from './utils/session-utils.ts';
  * 1. Calls the SDK's `auth/logout` route to revoke the upstream token
  *    and clear the refresh-token cookie.
  * 2. Clears the local session-storage `expiresAt` entry.
- * 3. Updates the controller state to `disconnected` and navigates the
- *    browser to the URL the server returned in `redirect_to`.
+ * 3. Updates the controller state to `disconnected` so the UI re-renders
+ *    without a page reload.
  *
  * Errors are caught, logged, and surfaced via the controller's
  * `error` field so the UI can show a retry state.
@@ -32,17 +31,16 @@ export async function disconnectFromHubSpot(
     if (!response.ok) {
       throw new Error(`Logout failed: ${response.status}`);
     }
-    const { redirect_to: redirectTo } =
-      (await response.json()) as LogoutResponse;
+    await response.body?.cancel();
 
     store.setState({
       expiresAt: null,
+      whoami: null,
       isSessionConnected: false,
       isDisconnectInFlight: false,
     });
 
-    window.location.href = redirectTo;
-    logger.info('disconnectFromHubSpot: redirecting');
+    logger.info('disconnectFromHubSpot: complete');
   } catch (err) {
     const message = err instanceof Error ? err.message : 'Disconnect failed';
     logger.error('disconnectFromHubSpot: failed', err);

package/src/browser/app-connect-controller/init.test.ts

@@ -0,0 +1,275 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import {
+  OAUTH_CALLBACK_PATH,
+  OAUTH_POPUP_CALLBACK_MESSAGE_TYPE,
+} from '../../shared/constants.ts';
+import { noopLogger } from '../../shared/logger.ts';
+import { SESSION_STORAGE_KEY } from './constants.ts';
+import { initAppConnect } from './init.ts';
+import { OAUTH_POPUP_WINDOW_NAME } from './oauth-popup.ts';
+import type {
+  AppConnectContext,
+  AppConnectInternalState,
+  SessionStorage,
+} from './types.ts';
+import { createStore } from './utils/store-utils.ts';
+
+const HUBSPOT_CONNECT_BASE_URL =
+  'https://edge.example.com/functions/v1/hubspot-connect';
+
+function createInMemorySessionStorage(): SessionStorage {
+  const map = new Map<string, string>();
+  return {
+    getItem: (key) => map.get(key) ?? null,
+    setItem: (key, value) => {
+      map.set(key, value);
+    },
+    removeItem: (key) => {
+      map.delete(key);
+    },
+  };
+}
+
+function createTestContext(): AppConnectContext {
+  const initialState: AppConnectInternalState = {
+    isInitComplete: false,
+    isConnectInFlight: false,
+    isSessionConnected: false,
+    isDisconnectInFlight: false,
+    error: null,
+    expiresAt: null,
+    whoami: null,
+  };
+  return {
+    config: { hubSpotConnectBaseUrl: HUBSPOT_CONNECT_BASE_URL },
+    logger: noopLogger,
+    sessionStorage: createInMemorySessionStorage(),
+    store: createStore<AppConnectInternalState>(initialState),
+  };
+}
+
+interface FakeWindowOptions {
+  href: string;
+  name?: string;
+  opener?: { closed: boolean; postMessage: ReturnType<typeof vi.fn> };
+}
+
+interface FakeWindow {
+  history: { calls: Array<[unknown, string, string]> };
+  windowProxy: {
+    location: Pick<Location, 'pathname' | 'search' | 'origin'>;
+  };
+  close: ReturnType<typeof vi.fn>;
+  openerPostMessage: ReturnType<typeof vi.fn> | undefined;
+}
+
+function installFakeWindow(options: FakeWindowOptions): FakeWindow {
+  const url = new URL(options.href);
+  const calls: Array<[unknown, string, string]> = [];
+  const close = vi.fn();
+  const openerPostMessage = options.opener?.postMessage;
+  const fakeWindow = {
+    location: {
+      pathname: url.pathname,
+      search: url.search,
+      origin: url.origin,
+    },
+    name: options.name ?? '',
+    opener: options.opener,
+    close,
+  };
+  const fakeHistory = {
+    replaceState: (state: unknown, title: string, newUrl: string) => {
+      calls.push([state, title, newUrl]);
+      const replaced = new URL(newUrl, url.origin);
+      fakeWindow.location.pathname = replaced.pathname;
+      fakeWindow.location.search = replaced.search;
+    },
+  };
+  vi.stubGlobal('window', fakeWindow);
+  vi.stubGlobal('history', fakeHistory);
+  return {
+    history: { calls },
+    windowProxy: fakeWindow,
+    close,
+    openerPostMessage,
+  };
+}
+
+describe('initAppConnect', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date(1_700_000_000_000));
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.restoreAllMocks();
+    vi.useRealTimers();
+  });
+
+  it('is a no-op on a normal page (no callback path, no expires_at param)', async () => {
+    installFakeWindow({ href: 'https://app.example.com/dashboard' });
+    const fetchSpy = vi.spyOn(globalThis, 'fetch');
+    const context = createTestContext();
+
+    await initAppConnect(context);
+
+    expect(fetchSpy).not.toHaveBeenCalled();
+    expect(context.store.getSnapshot().expiresAt).toBeNull();
+  });
+
+  it('POSTs to /auth/complete on the OAuth callback path and persists expires_at + return_path', async () => {
+    const expiresAt = Date.now() + 1800 * 1000;
+    installFakeWindow({
+      href: `https://app.example.com${OAUTH_CALLBACK_PATH}?code=auth-code&state=auth-state`,
+    });
+    const fetchSpy = vi.spyOn(globalThis, 'fetch').mockResolvedValue(
+      new Response(
+        JSON.stringify({
+          expires_at: expiresAt,
+          return_path: '/dashboard',
+          whoami: {},
+        }),
+        { status: 200 }
+      )
+    );
+    const context = createTestContext();
+
+    await initAppConnect(context);
+
+    expect(fetchSpy).toHaveBeenCalledTimes(1);
+    const [calledUrl, calledInit] = fetchSpy.mock.calls[0]!;
+    const url = new URL(calledUrl as string);
+    expect(url.origin + url.pathname).toBe(
+      `${HUBSPOT_CONNECT_BASE_URL}/auth/complete`
+    );
+    expect(url.searchParams.get('code')).toBe('auth-code');
+    expect(url.searchParams.get('state')).toBe('auth-state');
+    expect((calledInit as RequestInit).method).toBe('POST');
+    expect((calledInit as RequestInit).credentials).toBe('include');
+
+    expect(context.store.getSnapshot().expiresAt).toBe(expiresAt);
+    const stored = JSON.parse(
+      context.sessionStorage.getItem(SESSION_STORAGE_KEY)!
+    );
+    expect(stored.expiresAt).toBe(expiresAt);
+    expect(window.location.pathname).toBe('/dashboard');
+  });
+
+  it('throws and clears session storage when /auth/complete returns a non-OK response', async () => {
+    installFakeWindow({
+      href: `https://app.example.com${OAUTH_CALLBACK_PATH}?code=auth-code&state=bad-state`,
+    });
+    vi.spyOn(globalThis, 'fetch').mockResolvedValue(
+      new Response('{"error":"State mismatch"}', {
+        status: 403,
+        statusText: 'Forbidden',
+      })
+    );
+    const context = createTestContext();
+    context.sessionStorage.setItem(
+      SESSION_STORAGE_KEY,
+      '{"expiresAt":999,"whoami":null}'
+    );
+
+    await expect(initAppConnect(context)).rejects.toThrow(/Failed to complete/);
+    expect(context.sessionStorage.getItem(SESSION_STORAGE_KEY)).toBeNull();
+  });
+
+  it('relays code and state to the opener without calling auth/complete when in an OAuth popup', async () => {
+    const openerPostMessage = vi.fn();
+    const fake = installFakeWindow({
+      href: `https://app.example.com${OAUTH_CALLBACK_PATH}?code=auth-code&state=auth-state`,
+      name: OAUTH_POPUP_WINDOW_NAME,
+      opener: { closed: false, postMessage: openerPostMessage },
+    });
+    const fetchSpy = vi.spyOn(globalThis, 'fetch');
+    const context = createTestContext();
+
+    await initAppConnect(context);
+
+    expect(fetchSpy).not.toHaveBeenCalled();
+    expect(openerPostMessage).toHaveBeenCalledWith(
+      {
+        type: OAUTH_POPUP_CALLBACK_MESSAGE_TYPE,
+        code: 'auth-code',
+        state: 'auth-state',
+      },
+      'https://app.example.com'
+    );
+    expect(fake.close).toHaveBeenCalled();
+    expect(fake.history.calls).toHaveLength(0);
+    expect(context.store.getSnapshot().expiresAt).toBeNull();
+    expect(window.location.pathname).toBe(OAUTH_CALLBACK_PATH);
+  });
+
+  it('falls through to redirect flow when window.opener is set but window.name does not match the popup name', async () => {
+    const expiresAt = Date.now() + 1800 * 1000;
+    const openerPostMessage = vi.fn();
+    const fake = installFakeWindow({
+      href: `https://app.example.com${OAUTH_CALLBACK_PATH}?code=auth-code&state=auth-state`,
+      name: '',
+      opener: { closed: false, postMessage: openerPostMessage },
+    });
+    vi.spyOn(globalThis, 'fetch').mockResolvedValue(
+      new Response(
+        JSON.stringify({
+          expires_at: expiresAt,
+          return_path: '/dashboard',
+          whoami: {},
+        }),
+        { status: 200 }
+      )
+    );
+    const context = createTestContext();
+
+    await initAppConnect(context);
+
+    expect(openerPostMessage).not.toHaveBeenCalled();
+    expect(fake.close).not.toHaveBeenCalled();
+    expect(context.store.getSnapshot().expiresAt).toBe(expiresAt);
+    expect(window.location.pathname).toBe('/dashboard');
+  });
+
+  it('falls through to redirect flow when the popup relay fails because the opener is closed', async () => {
+    const expiresAt = Date.now() + 1800 * 1000;
+    const openerPostMessage = vi.fn();
+    const fake = installFakeWindow({
+      href: `https://app.example.com${OAUTH_CALLBACK_PATH}?code=auth-code&state=auth-state`,
+      name: OAUTH_POPUP_WINDOW_NAME,
+      opener: { closed: true, postMessage: openerPostMessage },
+    });
+    vi.spyOn(globalThis, 'fetch').mockResolvedValue(
+      new Response(
+        JSON.stringify({
+          expires_at: expiresAt,
+          return_path: '/dashboard',
+          whoami: {},
+        }),
+        { status: 200 }
+      )
+    );
+    const context = createTestContext();
+
+    await initAppConnect(context);
+
+    expect(openerPostMessage).not.toHaveBeenCalled();
+    expect(fake.close).not.toHaveBeenCalled();
+    expect(context.store.getSnapshot().expiresAt).toBe(expiresAt);
+    expect(window.location.pathname).toBe('/dashboard');
+  });
+
+  it('skips the callback step on the callback path when code or state are missing', async () => {
+    installFakeWindow({
+      href: `https://app.example.com${OAUTH_CALLBACK_PATH}`,
+    });
+    const fetchSpy = vi.spyOn(globalThis, 'fetch');
+    const context = createTestContext();
+
+    await initAppConnect(context);
+
+    expect(fetchSpy).not.toHaveBeenCalled();
+  });
+});

package/src/browser/app-connect-controller/init.ts

@@ -1,35 +1,60 @@
-import { EXPIRES_AT_KEY, EXPIRES_AT_URL_PARAM } from './constants.ts';
+import {
+  AUTH_COMPLETE_CODE_PARAM,
+  AUTH_COMPLETE_STATE_PARAM,
+  OAUTH_CALLBACK_PATH,
+} from '../../shared/constants.ts';
+import { completeHubSpotOAuthSession } from './oauth-complete.ts';
+import {
+  isOAuthPopupCallback,
+  relayOAuthCallbackToOpener,
+} from './oauth-popup.ts';
 import type { AppConnectContext } from './types.ts';
+import { storeSession } from './utils/session-utils.ts';
 
 /**
- * Picks up the `__hs_expires_at` parameter the OAuth callback adds to
- * the redirect URL, persists it to the controller, and strips it from
- * the address bar so it's not logged or bookmarked.
+ * On `controller.start()`:
  *
- * Called once by `controller.start()`. A no-op when the parameter
- * isn't present (e.g. on every page load other than the OAuth return
- * trip).
+ * 1. If the browser has been redirected back to the SDK's frontend
+ *    OAuth callback path (`/__hubspot_oauth_callback`) with `?code` +
+ *    `?state`:
+ *    - **Redirect flow** (no `window.opener`): POST to `auth/complete`
+ *      from this window, persist `expires_at`, and `history.replaceState`
+ *      to `return_path`.
+ *    - **Popup flow** (`window.opener` present): relay `code` + `state`
+ *      to the opener via `postMessage` and close. The opener POSTs to
+ *      `auth/complete` so partitioned cookies match `init-session`.
+ * 2. Pick up `?__hs_expires_at` from `window.location` (refresh hop),
+ *    persist it, and strip it from the address bar.
+ *
+ * A no-op when neither set of parameters is present.
  */
 export async function initAppConnect(
   context: AppConnectContext
 ): Promise<void> {
+  await consumeOAuthCallback(context);
+}
+
+async function consumeOAuthCallback(context: AppConnectContext): Promise<void> {
+  if (window.location.pathname !== OAUTH_CALLBACK_PATH) return;
+
   const params = new URLSearchParams(window.location.search);
-  const expiresAtStr = params.get(EXPIRES_AT_URL_PARAM);
-  if (!expiresAtStr) return;
+  const code = params.get(AUTH_COMPLETE_CODE_PARAM);
+  const state = params.get(AUTH_COMPLETE_STATE_PARAM);
+  if (!code || !state) return;
 
-  const expiresAt = parseInt(expiresAtStr, 10);
-  if (isNaN(expiresAt)) return;
+  if (isOAuthPopupCallback() && relayOAuthCallbackToOpener({ code, state })) {
+    return;
+  }
 
-  params.delete(EXPIRES_AT_URL_PARAM);
-  const cleanSearch = params.toString();
+  const body = await completeHubSpotOAuthSession(context, { code, state });
+  const { expires_at: expiresAt, return_path: returnPath } = body;
+
+  storeSession({ context, expiresAtMs: expiresAt, whoami: body.whoami });
+
+  const targetUrl = new URL(returnPath, window.location.origin);
   history.replaceState(
     null,
     '',
-    cleanSearch
-      ? `${window.location.pathname}?${cleanSearch}`
-      : window.location.pathname
+    `${targetUrl.pathname}${targetUrl.search}${targetUrl.hash}`
   );
-
-  context.store.setState({ expiresAt });
-  context.sessionStorage.setItem(EXPIRES_AT_KEY, String(expiresAt));
 }