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

package/dist/server/shared/constants.js.map

@@ -1 +1 @@
-{"version":3,"file":"constants.js","names":[],"sources":["../../../src/shared/constants.ts"],"sourcesContent":["/**\n * Constants whose values are part of the contract between the browser\n * controller and the server-side hubspot-connect routes. Both halves\n * import from this module so the wire format stays in sync.\n */\n\n/**\n * Query parameter on the OAuth return URL that carries the new access\n * token's expiry (Unix epoch milliseconds). The browser controller\n * sets this in the URL after a successful `auth/complete` call and\n * then strips it during `initAppConnect` via `history.replaceState`.\n */\nexport const EXPIRES_AT_URL_PARAM = '__hs_expires_at';\n\n/**\n * Path the browser visits after HubSpot's authorize endpoint\n * redirects back to the app. Mounted on the **frontend** origin (not\n * the SDK's edge function host) so all OAuth-related cookies live in\n * the `(frontend, edge)` CHIPS partition.\n *\n * The SDK's `auth/init-session` builds the OAuth `redirect_uri` as\n * `${requestOrigin}${HUBSPOT_FRONTEND_CALLBACK_PATH}`. The browser\n * controller, on `start()`, recognizes this path on `window.location`\n * and forwards `?code` + `?state` to the SDK's `auth/complete`\n * endpoint via a credentialed cross-site fetch. The host app must\n * register `${app_origin}${HUBSPOT_FRONTEND_CALLBACK_PATH}` as a\n * redirect URI in its HubSpot app settings.\n */\nexport const OAUTH_CALLBACK_PATH = '/__hubspot_oauth_callback';\n\n/**\n * Query parameter on the `auth/complete` POST request carrying the\n * authorization `code` HubSpot returned to the frontend callback.\n */\nexport const AUTH_COMPLETE_CODE_PARAM = 'code';\n\n/**\n * Query parameter on the `auth/complete` POST request carrying the\n * OAuth `state` HubSpot echoed back to the frontend callback.\n */\nexport const AUTH_COMPLETE_STATE_PARAM = 'state';\n"],"mappings":";;;;;;;;;;;;;;;AA4BA,MAAa,sBAAsB;;;;;AAMnC,MAAa,2BAA2B;;;;;AAMxC,MAAa,4BAA4B"}
+{"version":3,"file":"constants.js","names":[],"sources":["../../../src/shared/constants.ts"],"sourcesContent":["/**\n * Constants whose values are part of the contract between the browser\n * controller and the server-side hubspot-connect routes. Both halves\n * import from this module so the wire format stays in sync.\n */\n\n/**\n * Query parameter on the OAuth return URL that carries the new access\n * token's expiry (Unix epoch milliseconds). The browser controller\n * sets this in the URL after a successful `auth/complete` call and\n * then strips it during `initAppConnect` via `history.replaceState`.\n */\nexport const EXPIRES_AT_URL_PARAM = '__hs_expires_at';\n\n/**\n * Path the browser visits after HubSpot's authorize endpoint\n * redirects back to the app. Mounted on the **frontend** origin (not\n * the SDK's edge function host) so all OAuth-related cookies live in\n * the `(frontend, edge)` CHIPS partition.\n *\n * The SDK's `auth/init-session` builds the OAuth `redirect_uri` as\n * `${requestOrigin}${HUBSPOT_FRONTEND_CALLBACK_PATH}`. The browser\n * controller, on `start()`, recognizes this path on `window.location`\n * and forwards `?code` + `?state` to the SDK's `auth/complete`\n * endpoint via a credentialed cross-site fetch. The host app must\n * register `${app_origin}${HUBSPOT_FRONTEND_CALLBACK_PATH}` as a\n * redirect URI in its HubSpot app settings.\n */\nexport const OAUTH_CALLBACK_PATH = '/__hubspot_oauth_callback';\n\n/**\n * Query parameter on the `auth/complete` POST request carrying the\n * authorization `code` HubSpot returned to the frontend callback.\n */\nexport const AUTH_COMPLETE_CODE_PARAM = 'code';\n\n/**\n * Query parameter on the `auth/complete` POST request carrying the\n * OAuth `state` HubSpot echoed back to the frontend callback.\n */\nexport const AUTH_COMPLETE_STATE_PARAM = 'state';\n\n/**\n * `postMessage` `data.type` value the OAuth popup sends to its opener\n * with the authorization `code` and `state` from the callback URL. The\n * opener POSTs them to `auth/complete` so credentialed cookies stay in\n * the same CHIPS partition as `auth/init-session`.\n */\nexport const OAUTH_POPUP_CALLBACK_MESSAGE_TYPE =\n  'hubspot-app-connect:oauth-callback';\n"],"mappings":";;;;;;;;;;;;;;;AA4BA,MAAa,sBAAsB;;;;;AAMnC,MAAa,2BAA2B;;;;;AAMxC,MAAa,4BAA4B"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hubspot/app-connect-sdk",
-  "version": "1.0.0-alpha.13",
+  "version": "1.0.0-alpha.15",
   "description": "HubSpot App Connect SDK (alpha release). Documentation and integration guidance forthcoming.",
   "type": "module",
   "exports": {
@@ -45,8 +45,8 @@
     "typescript": "6.0.3",
     "vitest": "4.1.6",
     "@private/eslint-config": "0.1.0",
-    "@private/tsconfig": "0.1.0",
-    "@private/prettier-config": "0.1.0"
+    "@private/prettier-config": "0.1.0",
+    "@private/tsconfig": "0.1.0"
   },
   "scripts": {
     "clean": "rm -rf dist build *.tsbuildinfo node_modules .turbo",

package/src/browser/app-connect-controller/README.md

@@ -57,8 +57,11 @@ flowchart TD
 ## Module map
 
 - [create.ts](./create.ts) — factory; the only file [`../index.ts`](../index.ts) imports from. Wires the context, defines `connectToHubSpot` / `disconnectFromHubSpot`, and applies `memoizeLast` to `getSnapshot`.
-- [init.ts](./init.ts) — runs once on `start()`. Reads `?__hs_expires_at=…` from `window.location`, persists it via [`utils/session-utils.ts`](./utils/session-utils.ts), and scrubs the parameter from the address bar with `history.replaceState`.
-- [connect-start.ts](./connect-start.ts) — `GET`s the SDK's `/auth/init-session` route, then full-page redirects to HubSpot's `authorize` URL. The `return_path` is the current path + query so the user lands back where they started.
+- [init.ts](./init.ts) — runs once on `start()`. Redirect flow: POSTs `code` + `state` to `/auth/complete`, persists `expires_at`, `history.replaceState`s to `return_path`. Popup flow (`window.opener`): relays `code` + `state` to the opener and closes (no `auth/complete` in the popup).
+- [connect-start.ts](./connect-start.ts) — `GET`s `/auth/init-session`, then redirects or opens a popup per `config.oauthConnectMode` (`auto` uses a popup when embedded in an iframe). See [oauth-popup.ts](./oauth-popup.ts).
+- [oauth-popup.ts](./oauth-popup.ts) — opener waits for popup `postMessage` with `code` + `state`, then POSTs `/auth/complete`.
+- [oauth-complete.ts](./oauth-complete.ts) — shared credentialed `POST /auth/complete` used by redirect init and the opener popup handler.
+- [utils/resolve-oauth-connect-mode.ts](./utils/resolve-oauth-connect-mode.ts) / [utils/iframe-utils.ts](./utils/iframe-utils.ts) — map `oauthConnectMode` + iframe detection to redirect vs popup.
 - [disconnect.ts](./disconnect.ts) — `POST`s `/auth/logout`, clears local session storage, and redirects to the server-supplied `redirect_to`. Errors are caught and surfaced via `state.error`.
 - [refresh.ts](./refresh.ts) — subscribes to the store and (re)schedules a `/auth/refresh` call whenever `expiresAt` changes. Exposes `RefreshSchedulerHandle.stop()` for teardown.
 - [view-state.ts](./view-state.ts) — `getDerivedStatus` and `SERVER_VIEW` (the SSR snapshot returned by `getServerSnapshot`).

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

@@ -0,0 +1,156 @@
+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(),
+    });
+    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/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_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';
@@ -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,32 @@ describe('initAppConnect', () => {
     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`,
+      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('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

@@ -3,32 +3,30 @@ import {
   AUTH_COMPLETE_STATE_PARAM,
   OAUTH_CALLBACK_PATH,
 } from '../../shared/constants.ts';
-import type { AuthCompleteResponse } from '../../shared/wire-types.ts';
-import { EXPIRES_AT_KEY } from './constants.ts';
+import { completeHubSpotOAuthSession } from './oauth-complete.ts';
+import {
+  hasOAuthPopupOpener,
+  relayOAuthCallbackToOpener,
+} from './oauth-popup.ts';
 import type { AppConnectContext } from './types.ts';
-import { clearSessionStorage } from './utils/session-utils.ts';
+import { storeExpiresAt } from './utils/session-utils.ts';
 
 /**
  * On `controller.start()`:
  *
  * 1. If the browser has been redirected back to the SDK's frontend
- *    OAuth callback path (`HUBSPOT_FRONTEND_CALLBACK_PATH`) with
- *    `?code` + `?state`, POST those values to the SDK's
- *    `auth/complete` endpoint to finish the token exchange. The
- *    server sets the durable session cookies on the response (in the
- *    same `(frontend, edge)` CHIPS partition the SDK reads them from
- *    on subsequent API fetches) and returns `{ expires_at,
- *    return_path }`. Replace the URL with `${return_path}?
- *    ${EXPIRES_AT_URL_PARAM}=${expires_at}` so the rest of init
- *    runs against the page the user actually started the connect
- *    flow from.
- * 2. Pick up `?__hs_expires_at` from `window.location` (placed there
- *    by step 1, or by an in-progress refresh hop), persist it to the
- *    controller's store + sessionStorage, and strip it from the
- *    address bar so it isn't logged or bookmarked.
+ *    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 (every page
- * load other than the OAuth return trip).
+ * A no-op when neither set of parameters is present.
  */
 export async function initAppConnect(
   context: AppConnectContext
@@ -44,38 +42,15 @@ async function consumeOAuthCallback(context: AppConnectContext): Promise<void> {
   const state = params.get(AUTH_COMPLETE_STATE_PARAM);
   if (!code || !state) return;
 
-  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 (hasOAuthPopupOpener()) {
+    relayOAuthCallbackToOpener({ code, state });
+    return;
   }
 
-  if (!response.ok) {
-    clearSessionStorage(context);
-    throw new Error(
-      `Failed to complete HubSpot OAuth: ${response.status} ${response.statusText}`
-    );
-  }
-
-  const body = (await response.json()) as AuthCompleteResponse;
-
+  const body = await completeHubSpotOAuthSession(context, { code, state });
   const { expires_at: expiresAt, return_path: returnPath } = body;
-  context.store.setState({ expiresAt });
-  context.sessionStorage.setItem(EXPIRES_AT_KEY, String(expiresAt));
+
+  storeExpiresAt({ context, expiresAtMs: expiresAt });
 
   const targetUrl = new URL(returnPath, window.location.origin);
   history.replaceState(

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