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

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

@@ -0,0 +1,238 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { OAUTH_POPUP_CALLBACK_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('POSTs auth/complete on the opener when the popup relays code and state', 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 fetchSpy = vi
+      .spyOn(globalThis, 'fetch')
+      .mockResolvedValue(
+        new Response(
+          JSON.stringify({ expires_at: expiresAt, return_path: '/dashboard' }),
+          { status: 200 }
+        )
+      );
+
+    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_CALLBACK_MESSAGE_TYPE,
+        code: 'auth-code',
+        state: 'auth-state',
+      },
+    } as MessageEvent);
+
+    await expect(waitPromise).resolves.toBeUndefined();
+    expect(fetchSpy).toHaveBeenCalledTimes(1);
+    const [calledUrl, calledInit] = fetchSpy.mock.calls[0]!;
+    const url = new URL(calledUrl as string);
+    expect(url.pathname).toContain('/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);
+    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('succeeds when popup closes immediately after relaying code and state', 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),
+    });
+
+    vi.spyOn(globalThis, 'fetch').mockResolvedValue(
+      new Response(
+        JSON.stringify({ expires_at: expiresAt, return_path: '/dashboard' }),
+        { status: 200 }
+      )
+    );
+
+    const context = createTestContext();
+    const waitPromise = waitForHubSpotOAuthPopup({
+      context,
+      authorizationUrl: 'https://auth.example/authorize',
+    });
+
+    messageListeners[0]!({
+      origin: 'https://app.example.com',
+      data: {
+        type: OAUTH_POPUP_CALLBACK_MESSAGE_TYPE,
+        code: 'auth-code',
+        state: 'auth-state',
+      },
+    } as MessageEvent);
+
+    popup.closed = true;
+    await vi.advanceTimersByTimeAsync(300);
+
+    await expect(waitPromise).resolves.toBeUndefined();
+    expect(context.store.getSnapshot().isSessionConnected).toBe(true);
+  });
+
+  it('ignores postMessage from a foreign origin', async () => {
+    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 fetchSpy = vi.spyOn(globalThis, 'fetch');
+    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_CALLBACK_MESSAGE_TYPE,
+        code: 'auth-code',
+        state: 'auth-state',
+      },
+    } as MessageEvent);
+
+    popup.closed = true;
+    await vi.advanceTimersByTimeAsync(300);
+
+    await rejection;
+    expect(fetchSpy).not.toHaveBeenCalled();
+    expect(context.store.getSnapshot().expiresAt).toBeNull();
+  });
+});

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

@@ -0,0 +1,160 @@
+import { OAUTH_POPUP_CALLBACK_MESSAGE_TYPE } from '../../shared/constants.ts';
+import { completeHubSpotOAuthSession } from './oauth-complete.ts';
+import type { AppConnectContext } from './types.ts';
+import { storeExpiresAt } from './utils/session-utils.ts';
+
+export const OAUTH_POPUP_WINDOW_NAME = 'hubspot-app-connect-oauth';
+const OAUTH_POPUP_POLL_INTERVAL_MS = 300;
+
+interface OAuthPopupCallbackMessage {
+  type: typeof OAUTH_POPUP_CALLBACK_MESSAGE_TYPE;
+  code: string;
+  state: string;
+}
+
+interface WaitForHubSpotOAuthPopupOptions {
+  context: AppConnectContext;
+  authorizationUrl: string;
+}
+
+interface RelayOAuthCallbackToOpenerOptions {
+  code: string;
+  state: string;
+}
+
+function isOAuthPopupCallbackMessage(
+  data: unknown
+): data is OAuthPopupCallbackMessage {
+  if (typeof data !== 'object' || data === null) return false;
+  const record = data as Record<string, unknown>;
+  return (
+    record.type === OAUTH_POPUP_CALLBACK_MESSAGE_TYPE &&
+    typeof record.code === 'string' &&
+    record.code.length > 0 &&
+    typeof record.state === 'string' &&
+    record.state.length > 0
+  );
+}
+
+/**
+ * Opens HubSpot's authorize URL in a popup and waits for the callback
+ * page to relay `code` + `state` back. The opener POSTs to
+ * `auth/complete` so credentialed cookies use the same CHIPS partition
+ * as `auth/init-session`.
+ */
+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;
+    let isCallbackReceived = 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 (!isOAuthPopupCallbackMessage(event.data)) return;
+
+      if (isCallbackReceived) return;
+      isCallbackReceived = true;
+
+      void (async () => {
+        try {
+          const body = await completeHubSpotOAuthSession(context, {
+            code: event.data.code,
+            state: event.data.state,
+          });
+          settleSuccess(body.expires_at);
+        } catch (err) {
+          const message =
+            err instanceof Error ? err.message : 'HubSpot OAuth failed';
+          settleFailure(message);
+        }
+      })();
+    };
+
+    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 && !isCallbackReceived) {
+        settleFailure('Connect to HubSpot was cancelled.');
+      }
+    }, OAUTH_POPUP_POLL_INTERVAL_MS);
+  });
+}
+
+/**
+ * Called from the OAuth callback page inside the popup. Relays `code`
+ * and `state` to the opener (which runs `auth/complete`) and closes.
+ */
+export function relayOAuthCallbackToOpener(
+  options: RelayOAuthCallbackToOpenerOptions
+): boolean {
+  const { code, state } = options;
+  const opener = window.opener;
+  if (!opener || opener.closed) return false;
+
+  const message: OAuthPopupCallbackMessage = {
+    type: OAUTH_POPUP_CALLBACK_MESSAGE_TYPE,
+    code,
+    state,
+  };
+  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;
+  }
+}
+
+export function isOAuthPopupCallback(): boolean {
+  return window.name === OAUTH_POPUP_WINDOW_NAME && hasOAuthPopupOpener();
+}

package/src/browser/app-connect-controller/utils/iframe-utils.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 './iframe-utils.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';

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

@@ -37,6 +37,8 @@ interface AppConnectHeaderProps {
 
 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,11 +50,7 @@ export function AppConnectHeader({ title }: AppConnectHeaderProps) {
           {status === 'connected' ? <ViewingHubSpotContextRow /> : null}
         </div>
       </div>
-      {status === 'connected' ? (
-        <UserMenu />
-      ) : (
-        <ConnectButton variant="secondary" />
-      )}
+      {status === 'connected' ? <UserMenu /> : connectButton}
     </header>
   );
 }

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,9 @@
+/**
+ * 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 +17,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 +34,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 +56,11 @@ 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.
+   * 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>;
   /**