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

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

@@ -0,0 +1,110 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { noopLogger } from '../../shared/logger.ts';
+import { SESSION_STORAGE_KEY } from './constants.ts';
+import { completeHubSpotOAuthSession } from './oauth-complete.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: 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),
+  };
+}
+
+describe('completeHubSpotOAuthSession', () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.restoreAllMocks();
+  });
+
+  it('POSTs code and state to auth/complete with credentials', async () => {
+    const expiresAt = Date.now() + 1800 * 1000;
+    vi.stubGlobal('window', {
+      location: { origin: 'https://app.example.com' },
+    });
+    const fetchSpy = vi
+      .spyOn(globalThis, 'fetch')
+      .mockResolvedValue(
+        new Response(
+          JSON.stringify({ expires_at: expiresAt, return_path: '/home' }),
+          { status: 200 }
+        )
+      );
+    const context = createTestContext();
+
+    const body = await completeHubSpotOAuthSession(context, {
+      code: 'my-code',
+      state: 'my-state',
+    });
+
+    expect(body.expires_at).toBe(expiresAt);
+    expect(body.return_path).toBe('/home');
+    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('my-code');
+    expect(url.searchParams.get('state')).toBe('my-state');
+    expect((calledInit as RequestInit).method).toBe('POST');
+    expect((calledInit as RequestInit).credentials).toBe('include');
+  });
+
+  it('clears session storage when auth/complete fails', async () => {
+    vi.stubGlobal('window', {
+      location: { origin: 'https://app.example.com' },
+    });
+    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(
+      completeHubSpotOAuthSession(context, {
+        code: 'code',
+        state: 'bad-state',
+      })
+    ).rejects.toThrow(/Failed to complete/);
+    expect(context.sessionStorage.getItem(SESSION_STORAGE_KEY)).toBeNull();
+  });
+});

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

@@ -0,0 +1,53 @@
+import {
+  AUTH_COMPLETE_CODE_PARAM,
+  AUTH_COMPLETE_STATE_PARAM,
+} from '../../shared/constants.ts';
+import type { AuthCompleteResponse } from '../../shared/wire-types.ts';
+import type { AppConnectContext } from './types.ts';
+import { clearSessionStorage } from './utils/session-utils.ts';
+
+interface CompleteHubSpotOAuthSessionOptions {
+  code: string;
+  state: string;
+}
+
+/**
+ * Finishes the OAuth token exchange by POSTing `code` and `state` to the
+ * SDK's `auth/complete` route with credentialed cookies from the current
+ * browsing context (must match the partition used by `auth/init-session`).
+ */
+export async function completeHubSpotOAuthSession(
+  context: AppConnectContext,
+  options: CompleteHubSpotOAuthSessionOptions
+): Promise<AuthCompleteResponse> {
+  const { code, state } = options;
+
+  const completeUrl = new URL(
+    `${context.config.hubSpotConnectBaseUrl}/auth/complete`,
+    window.location.origin
+  );
+  completeUrl.searchParams.set(AUTH_COMPLETE_CODE_PARAM, code);
+  completeUrl.searchParams.set(AUTH_COMPLETE_STATE_PARAM, state);
+
+  let response: Response;
+  try {
+    response = await fetch(completeUrl.toString(), {
+      method: 'POST',
+      credentials: 'include',
+    });
+  } catch (err) {
+    clearSessionStorage(context);
+    throw new Error(
+      `Failed to complete HubSpot OAuth: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+
+  if (!response.ok) {
+    clearSessionStorage(context);
+    throw new Error(
+      `Failed to complete HubSpot OAuth: ${response.status} ${response.statusText}`
+    );
+  }
+
+  return (await response.json()) as AuthCompleteResponse;
+}

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

@@ -0,0 +1,239 @@
+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,
+    whoami: 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/types.ts

@@ -1,3 +1,4 @@
+import type { AuthCompleteWhoami } from '../../shared/wire-types.ts';
 import type { Logger } from '../index.ts';
 import type { AppConnectBrowserConfig } from '../types.ts';
 import type { Store } from './utils/store-utils.ts';
@@ -30,6 +31,8 @@ export interface AppConnectInternalState {
   error: string | null;
   /** Access-token expiry (Unix epoch milliseconds), or `null` if unknown. */
   expiresAt: number | null;
+  /** Identity of the connected user and their HubSpot account, or `null`. */
+  whoami: AuthCompleteWhoami | null;
 }
 
 /** Convenience alias for the typed store used by the controller. */

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';
+}