@hubspot/app-connect-sdk 1.0.0-alpha.1

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

@@ -0,0 +1,45 @@
+import type { InitSessionResponse } from '../../shared/wire-types.ts';
+import type { AppConnectContext } from './types.ts';
+import { delay } from './utils/timeout-utils.ts';
+
+/** Extra wait before redirect so the connect progress UI is visible; set to `0` to disable. */
+const ARTIFICIAL_CONNECT_REDIRECT_DELAY_MS = 500;
+
+/**
+ * Begins the OAuth connect flow:
+ *
+ * 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).
+ *
+ * The `return_path` is the current path + query so the user lands
+ * back where they started after authorizing.
+ *
+ * Throws when the init call fails. Does not return after the redirect
+ * begins because the page is unloaded.
+ */
+export async function startHubSpotConnection(
+  context: AppConnectContext
+): Promise<void> {
+  const { config } = context;
+
+  const returnPath = `${window.location.pathname}${window.location.search}`;
+
+  const initUrl = new URL(
+    `${config.hubSpotConnectBaseUrl}/auth/init-session`,
+    window.location.origin
+  );
+  initUrl.searchParams.set('return_path', returnPath);
+
+  const initResponse = await fetch(initUrl.toString(), {
+    credentials: 'include',
+  });
+  if (!initResponse.ok)
+    throw new Error(`Failed to init session: ${initResponse.status}`);
+  const { authorization_url: authorizationUrl } =
+    (await initResponse.json()) as InitSessionResponse;
+
+  await delay(ARTIFICIAL_CONNECT_REDIRECT_DELAY_MS);
+
+  window.location.href = authorizationUrl;
+}

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

@@ -0,0 +1,15 @@
+export { EXPIRES_AT_URL_PARAM } from '../../shared/constants.ts';
+
+/**
+ * Key the controller persists the access-token `expiresAt` (Unix
+ * epoch milliseconds) under in `sessionStorage`. Survives full-page
+ * navigations within the same tab.
+ */
+export const EXPIRES_AT_KEY = 'hubspot_token_expires_at';
+
+/**
+ * Number of milliseconds before `expiresAt` that the refresh
+ * scheduler attempts to mint a new access token. 60s is comfortably
+ * larger than typical network latency without burning lifetime.
+ */
+export const REFRESH_BUFFER_MS = 60_000;

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

@@ -0,0 +1,137 @@
+import { noopLogger, type Logger } from '../../shared/logger.ts';
+import type {
+  AppConnectBrowserConfig,
+  AppConnectController,
+  AppConnectState,
+} from '../types.ts';
+import { startHubSpotConnection } from './connect-start.ts';
+import { createDefaultSessionStorage } from './default-session-storage.ts';
+import { disconnectFromHubSpot as runDisconnectFromHubSpot } from './disconnect.ts';
+import { initAppConnect } from './init.ts';
+import { startRefreshScheduler } from './refresh.ts';
+import type {
+  AppConnectContext,
+  AppConnectInternalState,
+  AppConnectStore,
+} from './types.ts';
+import { memoizeLast } from './utils/memoize-utils.ts';
+import {
+  getExpiresAtFromSessionStorage,
+  isClientSessionActive,
+} from './utils/session-utils.ts';
+import { createStore } from './utils/store-utils.ts';
+import { getDerivedStatus, SERVER_VIEW } from './view-state.ts';
+
+/**
+ * Options accepted by {@link createAppConnectController}.
+ */
+export interface CreateAppConnectControllerOptions {
+  /** Runtime configuration; see {@link AppConnectBrowserConfig}. */
+  config: AppConnectBrowserConfig;
+  /** Logger the controller uses for status/debug messages. */
+  logger?: Logger;
+}
+
+/**
+ * Creates an `AppConnectController`. Exactly one controller should be
+ * shared by the entire app — the React provider takes the controller
+ * as a prop and exposes it via context.
+ *
+ * The returned controller is inert until `start()` is called: nothing
+ * is read from session storage, no refresh timer is scheduled, and no
+ * fetches are issued. Tests can construct a controller and inspect
+ * its initial snapshot without triggering side effects.
+ */
+export function createAppConnectController(
+  options: CreateAppConnectControllerOptions
+): AppConnectController {
+  const { config, logger = noopLogger } = options;
+  const sessionStorage = createDefaultSessionStorage();
+  const store: AppConnectStore = createStore<AppConnectInternalState>({
+    isInitComplete: false,
+    isConnectInFlight: false,
+    isDisconnectInFlight: false,
+    isSessionConnected: false,
+    error: null,
+    expiresAt: null,
+  });
+  const context: AppConnectContext = {
+    config,
+    logger,
+    sessionStorage,
+    store,
+  };
+
+  store.setState({ expiresAt: getExpiresAtFromSessionStorage(context) });
+
+  let hasStarted = false;
+
+  const connectToHubSpot = async () => {
+    logger.info('connectToHubSpot: starting');
+    store.setState({ error: null, isConnectInFlight: true });
+    try {
+      await startHubSpotConnection(context);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : 'Connection failed';
+      logger.error('connectToHubSpot: failed', err);
+      store.setState({ error: message });
+    } finally {
+      logger.debug(
+        'connectToHubSpot: connect flow step finished (may redirect to HubSpot)'
+      );
+      store.setState({ isConnectInFlight: false });
+    }
+  };
+  const disconnectFromHubSpot = () => runDisconnectFromHubSpot(context);
+
+  const getViewStateMemoized = memoizeLast<
+    Readonly<AppConnectInternalState>,
+    AppConnectState
+  >((storeState) => ({
+    status: getDerivedStatus(storeState),
+    error: storeState.error,
+    connectToHubSpot,
+    disconnectFromHubSpot,
+  }));
+
+  function getSnapshot() {
+    return getViewStateMemoized(store.getSnapshot());
+  }
+
+  return {
+    start() {
+      if (hasStarted) {
+        logger.debug('start skipped (already started)');
+        return;
+      }
+      hasStarted = true;
+      startRefreshScheduler(context);
+
+      logger.info('start: initSdk (OAuth return handling if applicable)');
+      void (async () => {
+        try {
+          await initAppConnect(context);
+          logger.info('initSdk: completed without error');
+        } catch (err) {
+          logger.error('initSdk: failed', err);
+          store.setState({
+            error:
+              err instanceof Error
+                ? err.message
+                : 'App Connect initialization failed',
+          });
+        } finally {
+          const sessionActive = isClientSessionActive(context);
+          logger.info('start: init complete, session active:', sessionActive);
+          store.setState({
+            isInitComplete: true,
+            isSessionConnected: sessionActive,
+          });
+        }
+      })();
+    },
+    subscribe: (fn) => store.subscribe(fn),
+    getSnapshot,
+    getServerSnapshot: () => SERVER_VIEW,
+  };
+}

package/src/browser/app-connect-controller/default-session-storage.ts

@@ -0,0 +1,21 @@
+import type { SessionStorage } from './types.ts';
+
+/**
+ * Builds a `SessionStorage` adapter that delegates to the global
+ * `sessionStorage` object exposed by browsers. The controller uses
+ * this when no custom storage is supplied (e.g. for tests or non-DOM
+ * environments).
+ */
+export function createDefaultSessionStorage(): SessionStorage {
+  return {
+    setItem: (key, value) => {
+      sessionStorage.setItem(key, value);
+    },
+    getItem: (key) => {
+      return sessionStorage.getItem(key);
+    },
+    removeItem: (key) => {
+      sessionStorage.removeItem(key);
+    },
+  };
+}

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

@@ -0,0 +1,54 @@
+import type { LogoutResponse } from '../../shared/wire-types.ts';
+import type { AppConnectContext } from './types.ts';
+import { clearSessionStorage } from './utils/session-utils.ts';
+
+/**
+ * Disconnect flow:
+ *
+ * 1. Calls the SDK's `auth/logout` route to revoke the upstream token
+ *    and clear the refresh-token cookie.
+ * 2. Clears the local session-storage `expiresAt` entry.
+ * 3. Updates the controller state to `disconnected` and navigates the
+ *    browser to the URL the server returned in `redirect_to`.
+ *
+ * Errors are caught, logged, and surfaced via the controller's
+ * `error` field so the UI can show a retry state.
+ */
+export async function disconnectFromHubSpot(
+  context: AppConnectContext
+): Promise<void> {
+  const { config, logger, store } = context;
+  logger.info('disconnectFromHubSpot: starting');
+  store.setState({ error: null, isDisconnectInFlight: true });
+  const { hubSpotConnectBaseUrl: appConnectBaseUrl } = config;
+
+  try {
+    clearSessionStorage(context);
+
+    const response = await fetch(`${appConnectBaseUrl}/auth/logout`, {
+      method: 'POST',
+      credentials: 'include',
+    });
+    if (!response.ok) {
+      throw new Error(`Logout failed: ${response.status}`);
+    }
+    const { redirect_to: redirectTo } =
+      (await response.json()) as LogoutResponse;
+
+    store.setState({
+      expiresAt: null,
+      isSessionConnected: false,
+      isDisconnectInFlight: false,
+    });
+
+    window.location.href = redirectTo;
+    logger.info('disconnectFromHubSpot: redirecting');
+  } catch (err) {
+    const message = err instanceof Error ? err.message : 'Disconnect failed';
+    logger.error('disconnectFromHubSpot: failed', err);
+    store.setState({
+      error: message,
+      isDisconnectInFlight: false,
+    });
+  }
+}

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

@@ -0,0 +1,35 @@
+import { EXPIRES_AT_KEY, EXPIRES_AT_URL_PARAM } from './constants.ts';
+import type { AppConnectContext } from './types.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.
+ *
+ * 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).
+ */
+export async function initAppConnect(
+  context: AppConnectContext
+): Promise<void> {
+  const params = new URLSearchParams(window.location.search);
+  const expiresAtStr = params.get(EXPIRES_AT_URL_PARAM);
+  if (!expiresAtStr) return;
+
+  const expiresAt = parseInt(expiresAtStr, 10);
+  if (isNaN(expiresAt)) return;
+
+  params.delete(EXPIRES_AT_URL_PARAM);
+  const cleanSearch = params.toString();
+  history.replaceState(
+    null,
+    '',
+    cleanSearch
+      ? `${window.location.pathname}?${cleanSearch}`
+      : window.location.pathname
+  );
+
+  context.store.setState({ expiresAt });
+  context.sessionStorage.setItem(EXPIRES_AT_KEY, String(expiresAt));
+}

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

@@ -0,0 +1,124 @@
+import type { RefreshTokenResponse } from '../../shared/wire-types.ts';
+import { REFRESH_BUFFER_MS } from './constants.ts';
+import type { AppConnectContext } from './types.ts';
+import {
+  isClientSessionActive,
+  storeExpiresAt,
+} from './utils/session-utils.ts';
+
+/**
+ * Tear-down handle returned by {@link startRefreshScheduler}. Calling
+ * `stop()` clears any pending refresh timer and unsubscribes from the
+ * store so the controller can be garbage-collected.
+ */
+export interface RefreshSchedulerHandle {
+  stop: () => void;
+}
+
+async function refreshAccessToken(context: AppConnectContext): Promise<void> {
+  const { config } = context;
+
+  const refreshResponse = await fetch(
+    `${config.hubSpotConnectBaseUrl}/auth/refresh`,
+    {
+      method: 'POST',
+      credentials: 'include',
+    }
+  );
+  if (!refreshResponse.ok) {
+    throw new Error(`Refresh failed: ${refreshResponse.status}`);
+  }
+  const { expires_in: expiresInSeconds } =
+    (await refreshResponse.json()) as RefreshTokenResponse;
+  if (
+    typeof expiresInSeconds !== 'number' ||
+    !Number.isFinite(expiresInSeconds) ||
+    expiresInSeconds <= 0
+  ) {
+    throw new Error('Refresh response missing or invalid expires_in');
+  }
+  const expiresAtMs = Date.now() + expiresInSeconds * 1000;
+
+  storeExpiresAt({ context, expiresAtMs });
+}
+
+/**
+ * Subscribes to store changes and (re)schedules a token refresh
+ * whenever `expiresAt` moves. Returns a handle that the caller can
+ * use to stop the scheduler when the controller is destroyed.
+ */
+export function startRefreshScheduler(
+  context: AppConnectContext
+): RefreshSchedulerHandle {
+  const { logger, store } = context;
+
+  let refreshTimer: ReturnType<typeof setTimeout> | null = null;
+  let stopped = false;
+
+  const scheduleRefresh = () => {
+    if (refreshTimer) {
+      clearTimeout(refreshTimer);
+      refreshTimer = null;
+    }
+    if (stopped) return;
+
+    const state = store.getSnapshot();
+    if (!state.isInitComplete || !state.isSessionConnected) {
+      return;
+    }
+
+    const expiresAt = state.expiresAt;
+    if (!expiresAt) {
+      logger.debug('scheduleRefresh: no expiresAt, skipping');
+      return;
+    }
+    const delayMs = Math.max(0, expiresAt - Date.now() - REFRESH_BUFFER_MS);
+    logger.debug(
+      'scheduleRefresh: next refresh in ',
+      (delayMs / 1000).toFixed(1),
+      's',
+      {
+        expiresAt,
+      }
+    );
+    refreshTimer = setTimeout(() => {
+      logger.debug('scheduleRefresh: timer fired, refreshing token');
+      refreshTimer = null;
+      if (stopped) return;
+
+      void (async () => {
+        try {
+          await refreshAccessToken(context);
+          if (stopped) return;
+          if (isClientSessionActive(context)) {
+            logger.info('token refresh: success, session still active');
+          } else {
+            logger.warn(
+              'token refresh: success but no active session in storage'
+            );
+            store.setState({ isSessionConnected: false });
+          }
+        } catch (err) {
+          logger.error('token refresh: failed', err);
+          if (stopped) return;
+          store.setState({ isSessionConnected: false });
+        }
+      })();
+    }, delayMs);
+  };
+
+  const unsubscribe = store.subscribe(() => {
+    scheduleRefresh();
+  });
+
+  return {
+    stop: () => {
+      stopped = true;
+      unsubscribe();
+      if (refreshTimer) {
+        clearTimeout(refreshTimer);
+        refreshTimer = null;
+      }
+    },
+  };
+}

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

@@ -0,0 +1,48 @@
+import type { Logger } from '../index.ts';
+import type { AppConnectBrowserConfig } from '../types.ts';
+import type { Store } from './utils/store-utils.ts';
+
+/**
+ * Subset of the browser `Storage` interface the controller relies on.
+ * Lets tests substitute an in-memory implementation without spinning
+ * up a DOM.
+ */
+export interface SessionStorage {
+  setItem: (key: string, value: string) => void;
+  getItem: (key: string) => string | null;
+  removeItem: (key: string) => void;
+}
+
+/**
+ * Internal state of the controller. The publicly visible
+ * `AppConnectState` is derived from this via `view-state.ts`.
+ */
+export interface AppConnectInternalState {
+  /** True after `start()` has finished its init step. */
+  isInitComplete: boolean;
+  /** True while `connectToHubSpot()` is in flight. */
+  isConnectInFlight: boolean;
+  /** True when `expiresAt` is in the future (i.e. the user is logged in). */
+  isSessionConnected: boolean;
+  /** True while `disconnectFromHubSpot()` is in flight. */
+  isDisconnectInFlight: boolean;
+  /** Last error message from any flow, or `null`. */
+  error: string | null;
+  /** Access-token expiry (Unix epoch milliseconds), or `null` if unknown. */
+  expiresAt: number | null;
+}
+
+/** Convenience alias for the typed store used by the controller. */
+export type AppConnectStore = Store<AppConnectInternalState>;
+
+/**
+ * Bag of dependencies the per-controller flows need. Constructed
+ * once inside `createAppConnectController` and passed around so
+ * helpers don't have to take six positional arguments.
+ */
+export interface AppConnectContext {
+  config: AppConnectBrowserConfig;
+  logger: Logger;
+  sessionStorage: SessionStorage;
+  store: AppConnectStore;
+}

package/src/browser/app-connect-controller/utils/crypto-utils.ts

@@ -0,0 +1 @@
+export { sha256base64url } from '../../../shared/encoding/sha256.ts';

package/src/browser/app-connect-controller/utils/encode-utils.ts

@@ -0,0 +1 @@
+export { base64url } from '../../../shared/encoding/base64.ts';

package/src/browser/app-connect-controller/utils/memoize-utils.test.ts

@@ -0,0 +1,48 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { memoizeLast } from './memoize-utils.ts';
+
+describe('memoizeLast', () => {
+  it('caches the most recent input/output pair', () => {
+    const inner = vi.fn((value: number) => value * 2);
+    const memoized = memoizeLast(inner);
+
+    expect(memoized(2)).toBe(4);
+    expect(memoized(2)).toBe(4);
+    expect(inner).toHaveBeenCalledTimes(1);
+  });
+
+  it('re-runs when the input changes', () => {
+    const inner = vi.fn((value: number) => value * 2);
+    const memoized = memoizeLast(inner);
+
+    memoized(2);
+    memoized(3);
+    expect(inner).toHaveBeenCalledTimes(2);
+  });
+
+  it('uses Object.is for comparison', () => {
+    const inner = vi.fn((arg: { x: number }) => arg.x);
+    const memoized = memoizeLast(inner);
+
+    const a = { x: 1 };
+    memoized(a);
+    memoized(a);
+    expect(inner).toHaveBeenCalledTimes(1);
+
+    memoized({ x: 1 });
+    expect(inner).toHaveBeenCalledTimes(2);
+  });
+
+  it('returns the cached output even when inner would error on re-call', () => {
+    let calls = 0;
+    const inner = (value: number): number => {
+      calls += 1;
+      if (calls > 1) throw new Error('should not be called twice');
+      return value;
+    };
+    const memoized = memoizeLast(inner);
+    expect(memoized(7)).toBe(7);
+    expect(memoized(7)).toBe(7);
+  });
+});

package/src/browser/app-connect-controller/utils/memoize-utils.ts

@@ -0,0 +1,26 @@
+/**
+ * Wraps `fn` so that calls with the same input (compared via
+ * `Object.is`) return the previous output without re-invoking `fn`.
+ * The cache holds at most one entry, so this is safe to use for
+ * derived view-state from a single store snapshot.
+ *
+ * Used by `getSnapshot` to keep the React state reference stable
+ * between unrelated store updates — `useSyncExternalStore` would
+ * otherwise re-render every consumer on every change.
+ */
+export function memoizeLast<TInput, TOutput>(
+  fn: (input: TInput) => TOutput
+): (input: TInput) => TOutput {
+  let lastInput: TInput;
+  let lastOutput: TOutput;
+  let hasValue = false;
+  return (input: TInput): TOutput => {
+    if (hasValue && Object.is(lastInput, input)) {
+      return lastOutput;
+    }
+    lastInput = input;
+    lastOutput = fn(input);
+    hasValue = true;
+    return lastOutput;
+  };
+}

package/src/browser/app-connect-controller/utils/session-utils.test.ts

@@ -0,0 +1,127 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { noopLogger } from '../../../shared/logger.ts';
+import { EXPIRES_AT_KEY } from '../constants.ts';
+import type {
+  AppConnectContext,
+  AppConnectInternalState,
+  SessionStorage,
+} from '../types.ts';
+import {
+  clearSessionStorage,
+  getExpiresAtFromSessionStorage,
+  isClientSessionActive,
+  storeExpiresAt,
+} from './session-utils.ts';
+import { createStore } from './store-utils.ts';
+
+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: '/functions/v1/hubspot-connect' },
+    logger: noopLogger,
+    sessionStorage: createInMemorySessionStorage(),
+    store: createStore<AppConnectInternalState>(initialState),
+  };
+}
+
+describe('session-utils', () => {
+  const FIXED_NOW = 1_700_000_000_000;
+
+  beforeEach(() => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date(FIXED_NOW));
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  describe('storeExpiresAt', () => {
+    it('writes both the store and session storage', () => {
+      const context = createTestContext();
+      storeExpiresAt({ context, expiresAtMs: FIXED_NOW + 60_000 });
+
+      expect(context.store.getSnapshot().expiresAt).toBe(FIXED_NOW + 60_000);
+      expect(context.sessionStorage.getItem(EXPIRES_AT_KEY)).toBe(
+        String(FIXED_NOW + 60_000)
+      );
+    });
+  });
+
+  describe('getExpiresAtFromSessionStorage', () => {
+    it('returns null when nothing is stored', () => {
+      const context = createTestContext();
+      expect(getExpiresAtFromSessionStorage(context)).toBeNull();
+    });
+
+    it('returns the stored value when in the future', () => {
+      const context = createTestContext();
+      const expiresAt = FIXED_NOW + 60_000;
+      context.sessionStorage.setItem(EXPIRES_AT_KEY, String(expiresAt));
+      expect(getExpiresAtFromSessionStorage(context)).toBe(expiresAt);
+    });
+
+    it('clears and returns null on malformed input', () => {
+      const context = createTestContext();
+      context.sessionStorage.setItem(EXPIRES_AT_KEY, 'not-a-number');
+      expect(getExpiresAtFromSessionStorage(context)).toBeNull();
+      expect(context.sessionStorage.getItem(EXPIRES_AT_KEY)).toBeNull();
+    });
+
+    it('clears and returns null on already-expired values', () => {
+      const context = createTestContext();
+      context.sessionStorage.setItem(EXPIRES_AT_KEY, String(FIXED_NOW - 1));
+      expect(getExpiresAtFromSessionStorage(context)).toBeNull();
+      expect(context.sessionStorage.getItem(EXPIRES_AT_KEY)).toBeNull();
+    });
+  });
+
+  describe('clearSessionStorage', () => {
+    it('removes the persisted expiresAt key', () => {
+      const context = createTestContext();
+      context.sessionStorage.setItem(EXPIRES_AT_KEY, '123');
+      clearSessionStorage(context);
+      expect(context.sessionStorage.getItem(EXPIRES_AT_KEY)).toBeNull();
+    });
+  });
+
+  describe('isClientSessionActive', () => {
+    it('returns false when expiresAt is null', () => {
+      const context = createTestContext();
+      expect(isClientSessionActive(context)).toBe(false);
+    });
+
+    it('returns true when expiresAt is in the future', () => {
+      const context = createTestContext();
+      context.store.setState({ expiresAt: FIXED_NOW + 1_000 });
+      expect(isClientSessionActive(context)).toBe(true);
+    });
+
+    it('returns false when expiresAt is in the past', () => {
+      const context = createTestContext();
+      context.store.setState({ expiresAt: FIXED_NOW - 1 });
+      expect(isClientSessionActive(context)).toBe(false);
+    });
+  });
+});