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

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

@@ -0,0 +1,58 @@
+import { EXPIRES_AT_KEY } from '../constants.ts';
+import type { AppConnectContext } from '../types.ts';
+
+interface StoreExpiresAtOptions {
+  context: AppConnectContext;
+  expiresAtMs: number;
+}
+
+/**
+ * Persists the access-token `expiresAt` (Unix epoch milliseconds) to
+ * both the in-memory store and `sessionStorage` so it survives
+ * full-page navigations within the same tab.
+ */
+export function storeExpiresAt(options: StoreExpiresAtOptions): void {
+  const { context, expiresAtMs } = options;
+  context.store.setState({ expiresAt: expiresAtMs });
+  context.sessionStorage.setItem(EXPIRES_AT_KEY, String(expiresAtMs));
+}
+
+/**
+ * Reads the persisted `expiresAt` from `sessionStorage`. Removes the
+ * value (and returns `null`) if it is malformed or already expired,
+ * so a stale entry never reactivates a dead session.
+ */
+export function getExpiresAtFromSessionStorage(
+  context: AppConnectContext
+): number | null {
+  const raw = context.sessionStorage.getItem(EXPIRES_AT_KEY);
+  if (!raw) return null;
+  const val = parseInt(raw, 10);
+  if (isNaN(val)) {
+    context.sessionStorage.removeItem(EXPIRES_AT_KEY);
+    return null;
+  }
+  if (Date.now() > val) {
+    context.sessionStorage.removeItem(EXPIRES_AT_KEY);
+    return null;
+  }
+  return val;
+}
+
+/**
+ * Clears the persisted session-storage state. Called on disconnect.
+ */
+export function clearSessionStorage(context: AppConnectContext): void {
+  context.sessionStorage.removeItem(EXPIRES_AT_KEY);
+}
+
+/**
+ * Returns `true` when the controller has an `expiresAt` whose value
+ * is still in the future. Used both to drive the UI status and to
+ * decide whether the refresh scheduler should run.
+ */
+export function isClientSessionActive(context: AppConnectContext): boolean {
+  const state = context.store.getSnapshot();
+  const expiresAt = state.expiresAt;
+  return expiresAt !== null && Date.now() < expiresAt;
+}

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

@@ -0,0 +1,102 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { createStore } from './store-utils.ts';
+
+interface TestState {
+  count: number;
+  name: string;
+}
+
+describe('createStore', () => {
+  it('returns the initial state from getSnapshot', () => {
+    const store = createStore<TestState>({ count: 1, name: 'a' });
+    expect(store.getSnapshot()).toEqual({ count: 1, name: 'a' });
+  });
+
+  it('does not share references with the initial state', () => {
+    const initial: TestState = { count: 1, name: 'a' };
+    const store = createStore(initial);
+    initial.count = 99;
+    expect(store.getSnapshot().count).toBe(1);
+  });
+
+  describe('setState', () => {
+    it('merges partial updates', () => {
+      const store = createStore<TestState>({ count: 1, name: 'a' });
+      store.setState({ count: 2 });
+      expect(store.getSnapshot()).toEqual({ count: 2, name: 'a' });
+    });
+
+    it('accepts updater functions', () => {
+      const store = createStore<TestState>({ count: 1, name: 'a' });
+      store.setState((prev) => ({ count: prev.count + 1 }));
+      expect(store.getSnapshot().count).toBe(2);
+    });
+
+    it('notifies subscribers on real changes', () => {
+      const store = createStore<TestState>({ count: 1, name: 'a' });
+      const listener = vi.fn();
+      store.subscribe(listener);
+      store.setState({ count: 2 });
+      expect(listener).toHaveBeenCalledTimes(1);
+    });
+
+    it('does not notify when nothing changed (shallow compare)', () => {
+      const store = createStore<TestState>({ count: 1, name: 'a' });
+      const listener = vi.fn();
+      store.subscribe(listener);
+      store.setState({ count: 1 });
+      store.setState({ name: 'a' });
+      expect(listener).not.toHaveBeenCalled();
+    });
+
+    it('changes the snapshot reference on a real update', () => {
+      const store = createStore<TestState>({ count: 1, name: 'a' });
+      const before = store.getSnapshot();
+      store.setState({ count: 2 });
+      expect(store.getSnapshot()).not.toBe(before);
+    });
+  });
+
+  describe('subscribe', () => {
+    it('returns an unsubscribe function', () => {
+      const store = createStore<TestState>({ count: 1, name: 'a' });
+      const listener = vi.fn();
+      const unsubscribe = store.subscribe(listener);
+      unsubscribe();
+      store.setState({ count: 2 });
+      expect(listener).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('set', () => {
+    it('writes a single key and notifies listeners', () => {
+      const store = createStore<TestState>({ count: 1, name: 'a' });
+      const listener = vi.fn();
+      store.subscribe(listener);
+      store.set('count', 2);
+      expect(store.get('count')).toBe(2);
+      expect(listener).toHaveBeenCalledTimes(1);
+    });
+
+    it('skips notification when the value is unchanged', () => {
+      const store = createStore<TestState>({ count: 1, name: 'a' });
+      const listener = vi.fn();
+      store.subscribe(listener);
+      store.set('count', 1);
+      expect(listener).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('destroy', () => {
+    it('clears listeners and silences future writes', () => {
+      const store = createStore<TestState>({ count: 1, name: 'a' });
+      const listener = vi.fn();
+      store.subscribe(listener);
+      store.destroy();
+      store.setState({ count: 2 });
+      store.set('name', 'b');
+      expect(listener).not.toHaveBeenCalled();
+    });
+  });
+});

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

@@ -0,0 +1,119 @@
+/**
+ * Tiny external store used by the controller. Shaped to be compatible
+ * with React's `useSyncExternalStore` while remaining usable outside
+ * React.
+ */
+export interface Store<TState extends object> {
+  /** Returns the current state. The reference changes on every update. */
+  getSnapshot: () => Readonly<TState>;
+  /**
+   * Subscribes to state changes. Returns an unsubscribe function the
+   * caller can invoke at teardown.
+   */
+  subscribe: (onChange: () => void) => () => void;
+  /**
+   * Merges `update` into the current state. When `update` is a
+   * function, it receives the current state and returns a partial.
+   * Listeners are only notified when at least one key actually
+   * changed (shallow compare).
+   */
+  setState: (
+    update:
+      | Partial<TState>
+      | ((prev: Readonly<TState>) => Partial<TState> | TState)
+  ) => void;
+  /** Reads a single key from the current state. */
+  get: <K extends keyof TState>(key: K) => TState[K];
+  /** Writes a single key. Listeners only fire when the value changes. */
+  set: <K extends keyof TState>(key: K, value: TState[K]) => void;
+  /**
+   * Drops every listener and prevents future `setState`/`set` calls
+   * from notifying. Used by `controller.destroy()`.
+   */
+  destroy: () => void;
+}
+
+function shallowEqualState<TState extends object>(
+  a: TState,
+  b: TState
+): boolean {
+  const keys = new Set([
+    ...Object.keys(a),
+    ...Object.keys(b),
+  ] as (keyof TState)[]);
+  for (const k of keys) {
+    if (!Object.is(a[k], b[k])) {
+      return false;
+    }
+  }
+  return true;
+}
+
+function mergeState<TState extends object>(
+  prev: TState,
+  partial: Partial<TState>
+): TState {
+  return { ...prev, ...partial } as TState;
+}
+
+/**
+ * Creates a new {@link Store}. The store starts with a shallow copy
+ * of `initialState`; subsequent mutations never touch the caller's
+ * object.
+ */
+export function createStore<TState extends object>(
+  initialState: TState
+): Store<TState> {
+  let state: TState = { ...initialState };
+  const listeners = new Set<() => void>();
+  let destroyed = false;
+
+  const notify = () => {
+    for (const listener of listeners) {
+      listener();
+    }
+  };
+
+  return {
+    getSnapshot() {
+      return state as Readonly<TState>;
+    },
+    subscribe(onChange) {
+      listeners.add(onChange);
+      return () => {
+        listeners.delete(onChange);
+      };
+    },
+    setState(update) {
+      if (destroyed) return;
+      const patch =
+        typeof update === 'function'
+          ? update(state as Readonly<TState>)
+          : update;
+      if (typeof patch !== 'object' || patch == null) {
+        return;
+      }
+      const next = mergeState(state, patch as Partial<TState>);
+      if (shallowEqualState(state, next)) {
+        return;
+      }
+      state = next;
+      notify();
+    },
+    get(key) {
+      return state[key];
+    },
+    set(key, value) {
+      if (destroyed) return;
+      if (Object.is(state[key], value)) {
+        return;
+      }
+      state = { ...state, [key]: value } as TState;
+      notify();
+    },
+    destroy() {
+      destroyed = true;
+      listeners.clear();
+    },
+  };
+}

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

@@ -0,0 +1,8 @@
+export function delay(ms: number): Promise<void> {
+  if (ms <= 0) {
+    return Promise.resolve();
+  }
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}

package/src/browser/app-connect-controller/view-state.test.ts

@@ -0,0 +1,70 @@
+import { describe, expect, it } from 'vitest';
+
+import type { AppConnectInternalState } from './types.ts';
+import { getDerivedStatus } from './view-state.ts';
+
+function makeState(
+  overrides: Partial<AppConnectInternalState> = {}
+): AppConnectInternalState {
+  return {
+    isInitComplete: true,
+    isConnectInFlight: false,
+    isSessionConnected: false,
+    isDisconnectInFlight: false,
+    error: null,
+    expiresAt: null,
+    ...overrides,
+  };
+}
+
+describe('getDerivedStatus', () => {
+  it('returns "initializing" before init is complete', () => {
+    expect(getDerivedStatus(makeState({ isInitComplete: false }))).toBe(
+      'initializing'
+    );
+  });
+
+  it('returns "disconnecting" while disconnect is in flight', () => {
+    expect(
+      getDerivedStatus(
+        makeState({
+          isDisconnectInFlight: true,
+          isConnectInFlight: true,
+          isSessionConnected: true,
+        })
+      )
+    ).toBe('disconnecting');
+  });
+
+  it('returns "connecting" when only connect is in flight', () => {
+    expect(getDerivedStatus(makeState({ isConnectInFlight: true }))).toBe(
+      'connecting'
+    );
+  });
+
+  it('returns "connected" when the session is active and idle', () => {
+    expect(getDerivedStatus(makeState({ isSessionConnected: true }))).toBe(
+      'connected'
+    );
+  });
+
+  it('returns "disconnected" when init is complete with no session', () => {
+    expect(getDerivedStatus(makeState())).toBe('disconnected');
+  });
+
+  it('disconnect-in-flight outranks connect-in-flight', () => {
+    expect(
+      getDerivedStatus(
+        makeState({ isDisconnectInFlight: true, isConnectInFlight: true })
+      )
+    ).toBe('disconnecting');
+  });
+
+  it('connect-in-flight outranks an existing session', () => {
+    expect(
+      getDerivedStatus(
+        makeState({ isConnectInFlight: true, isSessionConnected: true })
+      )
+    ).toBe('connecting');
+  });
+});

package/src/browser/app-connect-controller/view-state.ts

@@ -0,0 +1,40 @@
+import type { AppConnectState, AppConnectStatus } from '../types.ts';
+import type { AppConnectInternalState } from './types.ts';
+
+const noop = (): Promise<void> => Promise.resolve();
+
+/**
+ * Snapshot returned by `getServerSnapshot` for SSR. Has stable
+ * references and inert connect/disconnect actions because actions are
+ * meaningless before hydration.
+ */
+export const SERVER_VIEW: AppConnectState = {
+  status: 'initializing',
+  error: null,
+  connectToHubSpot: noop,
+  disconnectFromHubSpot: noop,
+};
+
+/**
+ * Reduces the boolean lifecycle flags into the user-facing
+ * `AppConnectStatus` enum value. The order of checks matters:
+ * disconnect-in-flight beats connect-in-flight (a transitional logout
+ * shouldn't show a "connecting" spinner), and connected beats default.
+ */
+export function getDerivedStatus(
+  state: AppConnectInternalState
+): AppConnectStatus {
+  const {
+    isInitComplete,
+    isConnectInFlight,
+    isSessionConnected,
+    isDisconnectInFlight,
+  } = state;
+  if (!isInitComplete) {
+    return 'initializing';
+  }
+  if (isDisconnectInFlight) return 'disconnecting';
+  if (isConnectInFlight) return 'connecting';
+  if (isSessionConnected) return 'connected';
+  return 'disconnected';
+}

package/src/browser/index.ts

@@ -0,0 +1,13 @@
+export {
+  createAppConnectController,
+  type CreateAppConnectControllerOptions,
+} from './app-connect-controller/create.ts';
+
+export { themeClass, themeVars } from './theme.css.ts';
+export { createLogger, type Logger } from '../shared/logger.ts';
+export {
+  type AppConnectBrowserConfig as AppConnectBrowserConfig,
+  type AppConnectController,
+  type AppConnectState,
+  type AppConnectStatus,
+} from './types.ts';

package/src/browser/react/components/AppConnectHeader/AppConnectHeader.css.ts

@@ -0,0 +1,231 @@
+import { style } from '@vanilla-extract/css';
+
+import { themeVars } from '../../../theme.css.ts';
+
+const avatarOrange = themeVars.fill.brand.default;
+const avatarTextColor = themeVars.text.primary.default;
+
+export const styles = {
+  header: style({
+    display: 'flex',
+    alignItems: 'center',
+    justifyContent: 'space-between',
+    gap: themeVars.space[300],
+    paddingBottom: themeVars.space[300],
+    borderBottomWidth: 1,
+    borderBottomStyle: 'solid',
+    borderBottomColor: themeVars.border.core.subtle.default,
+  }),
+  titleRow: style({
+    display: 'flex',
+    alignItems: 'center',
+    flex: 1,
+    minWidth: 0,
+  }),
+  leftStack: style({
+    display: 'flex',
+    flexDirection: 'column',
+    alignItems: 'flex-start',
+    gap: themeVars.space[200],
+    minWidth: 0,
+    flex: 1,
+  }),
+  contextRow: style({
+    display: 'flex',
+    alignItems: 'center',
+    gap: 6,
+    fontSize: 14,
+    lineHeight: 1.35,
+    color: themeVars.text.core.subtle,
+    minWidth: 0,
+  }),
+  contextIcon: style({
+    width: 16,
+    height: 16,
+    flexShrink: 0,
+    color: themeVars.text.core.subtle,
+  }),
+  contextPrefix: style({
+    flexShrink: 0,
+  }),
+  contextLink: style({
+    display: 'inline-flex',
+    alignItems: 'center',
+    gap: 4,
+    color: themeVars.fill.brand.default,
+    textDecoration: 'none',
+    fontWeight: 500,
+    selectors: {
+      '&:hover': {
+        textDecoration: 'underline',
+      },
+    },
+  }),
+  contextExternalIcon: style({
+    width: 14,
+    height: 14,
+    flexShrink: 0,
+  }),
+  titleCluster: style({
+    display: 'flex',
+    alignItems: 'center',
+    gap: themeVars.space[200],
+    width: 'max-content',
+    maxWidth: '100%',
+    minWidth: 0,
+  }),
+  title: style({
+    flex: '0 1 auto',
+    fontSize: 20,
+    fontWeight: 600,
+    margin: 0,
+    color: themeVars.text.core.default,
+    minWidth: 0,
+    overflow: 'hidden',
+    textOverflow: 'ellipsis',
+    whiteSpace: 'nowrap',
+  }),
+  userTrigger: style({
+    appearance: 'none',
+    WebkitAppearance: 'none',
+    margin: 0,
+    font: 'inherit',
+    lineHeight: 1,
+    cursor: 'pointer',
+    display: 'inline-flex',
+    alignItems: 'center',
+    gap: themeVars.space[200],
+    padding: `6px ${themeVars.space[300]} 6px 6px`,
+    backgroundColor: themeVars.fill.surface.default.default,
+    color: themeVars.text.core.default,
+    borderWidth: 1,
+    borderStyle: 'solid',
+    borderColor: themeVars.border.core.default,
+    borderRadius: 999,
+    transition: 'background-color 120ms ease, border-color 120ms ease',
+    selectors: {
+      '&:hover': {
+        backgroundColor: '#f7f7f7',
+      },
+      '&[data-popup-open]': {
+        backgroundColor: '#f7f7f7',
+      },
+    },
+  }),
+  triggerName: style({
+    fontWeight: 500,
+    fontSize: 14,
+  }),
+  chevron: style({
+    width: 14,
+    height: 14,
+    color: themeVars.text.core.subtle,
+    transition: 'transform 150ms ease',
+    selectors: {
+      '[data-popup-open] &': {
+        transform: 'rotate(180deg)',
+      },
+    },
+  }),
+  avatar: style({
+    display: 'inline-flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+    backgroundColor: avatarOrange,
+    color: avatarTextColor,
+    fontWeight: 600,
+    flexShrink: 0,
+    borderRadius: '50%',
+    userSelect: 'none',
+  }),
+  avatarSm: style({
+    width: 28,
+    height: 28,
+    fontSize: 11,
+  }),
+  avatarLg: style({
+    width: 40,
+    height: 40,
+    fontSize: 14,
+  }),
+  popup: style({
+    minWidth: 240,
+    backgroundColor: themeVars.fill.surface.default.default,
+    color: themeVars.text.core.default,
+    borderWidth: 1,
+    borderStyle: 'solid',
+    borderColor: themeVars.border.core.subtle.default,
+    borderRadius: themeVars.borderRadius[300],
+    boxShadow:
+      '0 6px 16px rgba(17, 17, 17, 0.08), 0 2px 6px rgba(17, 17, 17, 0.04)',
+    padding: `${themeVars.space[200]} 0`,
+    outline: 'none',
+    transformOrigin: 'top right',
+    opacity: 0,
+    transform: 'scale(0.96)',
+    transition: 'opacity 120ms ease, transform 120ms ease',
+    selectors: {
+      '&[data-starting-style]': {
+        opacity: 0,
+        transform: 'scale(0.96)',
+      },
+      '&[data-open]': {
+        opacity: 1,
+        transform: 'scale(1)',
+      },
+    },
+  }),
+  userInfo: style({
+    display: 'flex',
+    alignItems: 'center',
+    gap: themeVars.space[300],
+    padding: `${themeVars.space[200]} ${themeVars.space[300]}`,
+  }),
+  userInfoText: style({
+    display: 'flex',
+    flexDirection: 'column',
+    minWidth: 0,
+  }),
+  userInfoName: style({
+    fontWeight: 600,
+    fontSize: 14,
+    color: themeVars.text.core.default,
+    whiteSpace: 'nowrap',
+    overflow: 'hidden',
+    textOverflow: 'ellipsis',
+  }),
+  userInfoEmail: style({
+    fontSize: 13,
+    color: themeVars.text.core.subtle,
+    whiteSpace: 'nowrap',
+    overflow: 'hidden',
+    textOverflow: 'ellipsis',
+  }),
+  separator: style({
+    height: 1,
+    margin: `${themeVars.space[200]} 0`,
+    backgroundColor: themeVars.border.core.subtle.default,
+    border: 'none',
+  }),
+  disconnectItem: style({
+    display: 'flex',
+    alignItems: 'center',
+    gap: themeVars.space[200],
+    padding: `${themeVars.space[200]} ${themeVars.space[300]}`,
+    color: themeVars.text.alert.default,
+    fontSize: 14,
+    fontWeight: 500,
+    cursor: 'pointer',
+    outline: 'none',
+    userSelect: 'none',
+    selectors: {
+      '&[data-highlighted]': {
+        backgroundColor: themeVars.fill.accent.red.subtle.default,
+      },
+    },
+  }),
+  disconnectIcon: style({
+    width: 16,
+    height: 16,
+  }),
+} as const;