@hubspot/app-connect-sdk 1.0.0-alpha.13 → 1.0.0-alpha.14

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

@@ -0,0 +1,145 @@
+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,
+  };
+  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(),
+    });
+    vi.spyOn(globalThis, 'fetch').mockResolvedValue(
+      new Response(
+        JSON.stringify({
+          authorization_url: 'https://auth.example/authorize',
+        }),
+        { status: 200 }
+      )
+    );
+
+    const expiresAt = Date.now() + 1800 * 1000;
+    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-complete', expiresAt },
+    } 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/init.test.ts

@@ -1,6 +1,9 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
-import { OAUTH_CALLBACK_PATH } from '../../shared/constants.ts';
+import {
+  OAUTH_CALLBACK_PATH,
+  OAUTH_POPUP_MESSAGE_TYPE,
+} from '../../shared/constants.ts';
 import { noopLogger } from '../../shared/logger.ts';
 import { EXPIRES_AT_KEY } from './constants.ts';
 import { initAppConnect } from './init.ts';
@@ -46,6 +49,7 @@ function createTestContext(): AppConnectContext {
 
 interface FakeWindowOptions {
   href: string;
+  opener?: { closed: boolean; postMessage: ReturnType<typeof vi.fn> };
 }
 
 interface FakeWindow {
@@ -53,17 +57,23 @@ interface FakeWindow {
   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,
     },
+    opener: options.opener,
+    close,
   };
   const fakeHistory = {
     replaceState: (state: unknown, title: string, newUrl: string) => {
@@ -75,7 +85,12 @@ function installFakeWindow(options: FakeWindowOptions): FakeWindow {
   };
   vi.stubGlobal('window', fakeWindow);
   vi.stubGlobal('history', fakeHistory);
-  return { history: { calls }, windowProxy: fakeWindow };
+  return {
+    history: { calls },
+    windowProxy: fakeWindow,
+    close,
+    openerPostMessage,
+  };
 }
 
 describe('initAppConnect', () => {
@@ -153,6 +168,33 @@ describe('initAppConnect', () => {
     expect(context.sessionStorage.getItem(EXPIRES_AT_KEY)).toBeNull();
   });
 
+  it('notifies the opener and skips replaceState when running in an OAuth popup', 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`,
+      opener: { closed: false, postMessage: openerPostMessage },
+    });
+    vi.spyOn(globalThis, 'fetch').mockResolvedValue(
+      new Response(
+        JSON.stringify({ expires_at: expiresAt, return_path: '/dashboard' }),
+        { status: 200 }
+      )
+    );
+    const context = createTestContext();
+
+    await initAppConnect(context);
+
+    expect(openerPostMessage).toHaveBeenCalledWith(
+      { type: OAUTH_POPUP_MESSAGE_TYPE, expiresAt },
+      '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('skips the callback step on the callback path when code or state are missing', async () => {
     installFakeWindow({
       href: `https://app.example.com${OAUTH_CALLBACK_PATH}`,

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

@@ -4,9 +4,9 @@ import {
   OAUTH_CALLBACK_PATH,
 } from '../../shared/constants.ts';
 import type { AuthCompleteResponse } from '../../shared/wire-types.ts';
-import { EXPIRES_AT_KEY } from './constants.ts';
+import { hasOAuthPopupOpener, notifyOAuthPopupOpener } from './oauth-popup.ts';
 import type { AppConnectContext } from './types.ts';
-import { clearSessionStorage } from './utils/session-utils.ts';
+import { clearSessionStorage, storeExpiresAt } from './utils/session-utils.ts';
 
 /**
  * On `controller.start()`:
@@ -74,8 +74,13 @@ async function consumeOAuthCallback(context: AppConnectContext): Promise<void> {
   const body = (await response.json()) as AuthCompleteResponse;
 
   const { expires_at: expiresAt, return_path: returnPath } = body;
-  context.store.setState({ expiresAt });
-  context.sessionStorage.setItem(EXPIRES_AT_KEY, String(expiresAt));
+
+  if (hasOAuthPopupOpener()) {
+    notifyOAuthPopupOpener({ expiresAtMs: expiresAt });
+    return;
+  }
+
+  storeExpiresAt({ context, expiresAtMs: expiresAt });
 
   const targetUrl = new URL(returnPath, window.location.origin);
   history.replaceState(

package/src/browser/app-connect-controller/oauth-popup.test.ts

@@ -0,0 +1,166 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { OAUTH_POPUP_MESSAGE_TYPE } from '../../shared/constants.ts';
+import { noopLogger } from '../../shared/logger.ts';
+import { waitForHubSpotOAuthPopup } 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: true,
+    isConnectInFlight: true,
+    isSessionConnected: false,
+    isDisconnectInFlight: false,
+    error: null,
+    expiresAt: null,
+  };
+  return {
+    config: { hubSpotConnectBaseUrl: HUBSPOT_CONNECT_BASE_URL },
+    logger: noopLogger,
+    sessionStorage: createInMemorySessionStorage(),
+    store: createStore<AppConnectInternalState>(initialState),
+  };
+}
+
+describe('waitForHubSpotOAuthPopup', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.restoreAllMocks();
+    vi.useRealTimers();
+  });
+
+  it('resolves and persists expiresAt when a valid postMessage arrives', async () => {
+    const expiresAt = Date.now() + 1800 * 1000;
+    const popup = { closed: false, close: vi.fn() };
+    const messageListeners: Array<(event: MessageEvent) => void> = [];
+
+    vi.stubGlobal('window', {
+      location: { origin: 'https://app.example.com' },
+      addEventListener: (
+        type: string,
+        listener: (event: MessageEvent) => void
+      ) => {
+        if (type === 'message') messageListeners.push(listener);
+      },
+      removeEventListener: vi.fn(),
+      open: vi.fn(() => popup),
+    });
+
+    const context = createTestContext();
+    const waitPromise = waitForHubSpotOAuthPopup({
+      context,
+      authorizationUrl: 'https://auth.example/authorize',
+    });
+
+    const listener = messageListeners[0]!;
+    listener({
+      origin: 'https://app.example.com',
+      data: { type: OAUTH_POPUP_MESSAGE_TYPE, expiresAt },
+    } as MessageEvent);
+
+    await expect(waitPromise).resolves.toBeUndefined();
+    expect(context.store.getSnapshot().expiresAt).toBe(expiresAt);
+    expect(context.store.getSnapshot().isSessionConnected).toBe(true);
+  });
+
+  it('rejects when the popup is closed without completing OAuth', async () => {
+    const popup = { closed: false, close: vi.fn() };
+
+    vi.stubGlobal('window', {
+      location: { origin: 'https://app.example.com' },
+      addEventListener: vi.fn(),
+      removeEventListener: vi.fn(),
+      open: vi.fn(() => popup),
+    });
+
+    const context = createTestContext();
+    const waitPromise = waitForHubSpotOAuthPopup({
+      context,
+      authorizationUrl: 'https://auth.example/authorize',
+    });
+    const rejection = expect(waitPromise).rejects.toThrow(/cancelled/i);
+
+    popup.closed = true;
+    await vi.advanceTimersByTimeAsync(300);
+
+    await rejection;
+  });
+
+  it('rejects when window.open returns null', async () => {
+    vi.stubGlobal('window', {
+      location: { origin: 'https://app.example.com' },
+      addEventListener: vi.fn(),
+      removeEventListener: vi.fn(),
+      open: vi.fn(() => null),
+    });
+
+    const context = createTestContext();
+    await expect(
+      waitForHubSpotOAuthPopup({
+        context,
+        authorizationUrl: 'https://auth.example/authorize',
+      })
+    ).rejects.toThrow(/Popup blocked/i);
+  });
+
+  it('ignores postMessage from a foreign origin', async () => {
+    const expiresAt = Date.now() + 1800 * 1000;
+    const popup = { closed: false, close: vi.fn() };
+    const messageListeners: Array<(event: MessageEvent) => void> = [];
+
+    vi.stubGlobal('window', {
+      location: { origin: 'https://app.example.com' },
+      addEventListener: (
+        type: string,
+        listener: (event: MessageEvent) => void
+      ) => {
+        if (type === 'message') messageListeners.push(listener);
+      },
+      removeEventListener: vi.fn(),
+      open: vi.fn(() => popup),
+    });
+
+    const context = createTestContext();
+    const waitPromise = waitForHubSpotOAuthPopup({
+      context,
+      authorizationUrl: 'https://auth.example/authorize',
+    });
+    const rejection = expect(waitPromise).rejects.toThrow(/cancelled/i);
+
+    messageListeners[0]!({
+      origin: 'https://evil.example.com',
+      data: { type: OAUTH_POPUP_MESSAGE_TYPE, expiresAt },
+    } as MessageEvent);
+
+    popup.closed = true;
+    await vi.advanceTimersByTimeAsync(300);
+
+    await rejection;
+    expect(context.store.getSnapshot().expiresAt).toBeNull();
+  });
+});

package/src/browser/app-connect-controller/oauth-popup.ts

@@ -0,0 +1,132 @@
+import { OAUTH_POPUP_MESSAGE_TYPE } from '../../shared/constants.ts';
+import type { AppConnectContext } from './types.ts';
+import { storeExpiresAt } from './utils/session-utils.ts';
+
+const OAUTH_POPUP_WINDOW_NAME = 'hubspot-app-connect-oauth';
+const OAUTH_POPUP_POLL_INTERVAL_MS = 300;
+
+interface OAuthPopupCompleteMessage {
+  type: typeof OAUTH_POPUP_MESSAGE_TYPE;
+  expiresAt: number;
+}
+
+interface WaitForHubSpotOAuthPopupOptions {
+  context: AppConnectContext;
+  authorizationUrl: string;
+}
+
+function isOAuthPopupCompleteMessage(
+  data: unknown
+): data is OAuthPopupCompleteMessage {
+  if (typeof data !== 'object' || data === null) return false;
+  const record = data as Record<string, unknown>;
+  return (
+    record.type === OAUTH_POPUP_MESSAGE_TYPE &&
+    typeof record.expiresAt === 'number' &&
+    Number.isFinite(record.expiresAt) &&
+    record.expiresAt > 0
+  );
+}
+
+/**
+ * Opens HubSpot's authorize URL in a popup and waits for the OAuth
+ * callback page to post the session expiry back to this window.
+ */
+export async function waitForHubSpotOAuthPopup(
+  options: WaitForHubSpotOAuthPopupOptions
+): Promise<void> {
+  const { context, authorizationUrl } = options;
+  const targetOrigin = window.location.origin;
+
+  return new Promise<void>((resolve, reject) => {
+    let popup: Window | null = null;
+    let pollTimer: ReturnType<typeof setInterval> | undefined;
+    let isSettled = false;
+
+    const cleanup = () => {
+      window.removeEventListener('message', onMessage);
+      if (pollTimer !== undefined) clearInterval(pollTimer);
+    };
+
+    const settleSuccess = (expiresAtMs: number) => {
+      if (isSettled) return;
+      isSettled = true;
+      cleanup();
+      storeExpiresAt({ context, expiresAtMs });
+      context.store.setState({ isSessionConnected: true, error: null });
+      resolve();
+    };
+
+    const settleFailure = (message: string) => {
+      if (isSettled) return;
+      isSettled = true;
+      cleanup();
+      try {
+        popup?.close();
+      } catch {
+        // ignore close errors
+      }
+      reject(new Error(message));
+    };
+
+    const onMessage = (event: MessageEvent) => {
+      if (event.origin !== targetOrigin) return;
+      if (!isOAuthPopupCompleteMessage(event.data)) return;
+      settleSuccess(event.data.expiresAt);
+    };
+
+    window.addEventListener('message', onMessage);
+
+    popup = window.open(
+      authorizationUrl,
+      OAUTH_POPUP_WINDOW_NAME,
+      'popup=yes,width=600,height=700'
+    );
+    if (!popup) {
+      settleFailure('Popup blocked. Allow popups for this site and try again.');
+      return;
+    }
+
+    pollTimer = setInterval(() => {
+      if (popup?.closed) {
+        settleFailure('Connect to HubSpot was cancelled.');
+      }
+    }, OAUTH_POPUP_POLL_INTERVAL_MS);
+  });
+}
+
+interface NotifyOAuthPopupOpenerOptions {
+  expiresAtMs: number;
+}
+
+/**
+ * Called from the OAuth callback page running inside the popup after
+ * `auth/complete` succeeds. Notifies the opener and closes this window.
+ */
+export function notifyOAuthPopupOpener(
+  options: NotifyOAuthPopupOpenerOptions
+): boolean {
+  const { expiresAtMs } = options;
+  const opener = window.opener;
+  if (!opener || opener.closed) return false;
+
+  const message: OAuthPopupCompleteMessage = {
+    type: OAUTH_POPUP_MESSAGE_TYPE,
+    expiresAt: expiresAtMs,
+  };
+  opener.postMessage(message, window.location.origin);
+  try {
+    window.close();
+  } catch {
+    // ignore close errors
+  }
+  return true;
+}
+
+export function hasOAuthPopupOpener(): boolean {
+  try {
+    return Boolean(window.opener && !window.opener.closed);
+  } catch {
+    return false;
+  }
+}

package/src/browser/app-connect-controller/utils/is-app-embedded-in-iframe.ts

@@ -0,0 +1,12 @@
+/**
+ * Returns `true` when the app runs inside a parent frame (same-origin
+ * or cross-origin). Cross-origin parent access throws; treat that as
+ * embedded so OAuth uses a popup instead of a top-level redirect.
+ */
+export function isAppEmbeddedInIframe(): boolean {
+  try {
+    return window.self !== window.top;
+  } catch {
+    return true;
+  }
+}

package/src/browser/app-connect-controller/utils/resolve-oauth-connect-mode.test.ts

@@ -0,0 +1,35 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { resolveOAuthConnectMode } from './resolve-oauth-connect-mode.ts';
+
+describe('resolveOAuthConnectMode', () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.restoreAllMocks();
+  });
+
+  it('returns redirect when mode is redirect', () => {
+    vi.stubGlobal('window', { self: {}, top: {} });
+    expect(resolveOAuthConnectMode({ oauthConnectMode: 'redirect' })).toBe(
+      'redirect'
+    );
+  });
+
+  it('returns popup when mode is popup', () => {
+    vi.stubGlobal('window', { self: {}, top: {} });
+    expect(resolveOAuthConnectMode({ oauthConnectMode: 'popup' })).toBe(
+      'popup'
+    );
+  });
+
+  it('returns popup in auto mode when embedded in an iframe', () => {
+    vi.stubGlobal('window', { self: {}, top: { other: true } });
+    expect(resolveOAuthConnectMode({ oauthConnectMode: 'auto' })).toBe('popup');
+  });
+
+  it('returns redirect in auto mode when not embedded', () => {
+    const top = {};
+    vi.stubGlobal('window', { self: top, top });
+    expect(resolveOAuthConnectMode({})).toBe('redirect');
+  });
+});

package/src/browser/app-connect-controller/utils/resolve-oauth-connect-mode.ts

@@ -0,0 +1,21 @@
+import type { OAuthConnectMode } from '../../types.ts';
+import { isAppEmbeddedInIframe } from './is-app-embedded-in-iframe.ts';
+
+export type ResolvedOAuthConnectMode = 'redirect' | 'popup';
+
+interface ResolveOAuthConnectModeOptions {
+  oauthConnectMode?: OAuthConnectMode;
+}
+
+/**
+ * Maps the configured {@link OAuthConnectMode} to the concrete connect
+ * behavior for the current browsing context.
+ */
+export function resolveOAuthConnectMode(
+  options: ResolveOAuthConnectModeOptions
+): ResolvedOAuthConnectMode {
+  const mode = options.oauthConnectMode ?? 'auto';
+  if (mode === 'popup') return 'popup';
+  if (mode === 'redirect') return 'redirect';
+  return isAppEmbeddedInIframe() ? 'popup' : 'redirect';
+}

package/src/browser/index.ts

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