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

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

@@ -0,0 +1,260 @@
+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 { EXPIRES_AT_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,
+  };
+  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' }),
+          { 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);
+    expect(context.sessionStorage.getItem(EXPIRES_AT_KEY)).toBe(
+      String(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(EXPIRES_AT_KEY, '999');
+
+    await expect(initAppConnect(context)).rejects.toThrow(/Failed to complete/);
+    expect(context.sessionStorage.getItem(EXPIRES_AT_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' }),
+        { 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' }),
+        { 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 { storeExpiresAt } 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;
+
+  storeExpiresAt({ context, expiresAtMs: expiresAt });
+
+  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));
 }

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

@@ -0,0 +1,106 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { noopLogger } from '../../shared/logger.ts';
+import { EXPIRES_AT_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,
+  };
+  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(EXPIRES_AT_KEY, '999');
+
+    await expect(
+      completeHubSpotOAuthSession(context, {
+        code: 'code',
+        state: 'bad-state',
+      })
+    ).rejects.toThrow(/Failed to complete/);
+    expect(context.sessionStorage.getItem(EXPIRES_AT_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;
+}