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

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

@@ -1,55 +1,96 @@
-import { EXPIRES_AT_KEY } from '../constants.ts';
+import type { AuthCompleteWhoami } from '../../../shared/wire-types.ts';
+import { SESSION_STORAGE_KEY } from '../constants.ts';
 import type { AppConnectContext } from '../types.ts';
 
-interface StoreExpiresAtOptions {
-  context: AppConnectContext;
-  expiresAtMs: number;
+interface StoredSession {
+  expiresAt: number;
+  whoami: AuthCompleteWhoami | null;
+}
+
+function readStoredSession(context: AppConnectContext): StoredSession | null {
+  const raw = context.sessionStorage.getItem(SESSION_STORAGE_KEY);
+  if (!raw) return null;
+  let parsed: StoredSession;
+  try {
+    parsed = JSON.parse(raw) as StoredSession;
+  } catch {
+    context.sessionStorage.removeItem(SESSION_STORAGE_KEY);
+    return null;
+  }
+  if (typeof parsed.expiresAt !== 'number' || isNaN(parsed.expiresAt)) {
+    context.sessionStorage.removeItem(SESSION_STORAGE_KEY);
+    return null;
+  }
+  if (Date.now() > parsed.expiresAt) {
+    context.sessionStorage.removeItem(SESSION_STORAGE_KEY);
+    return null;
+  }
+  return parsed;
+}
+
+function writeStoredSession(
+  context: AppConnectContext,
+  session: StoredSession
+): void {
+  context.sessionStorage.setItem(SESSION_STORAGE_KEY, JSON.stringify(session));
 }
 
 /**
- * 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.
+ * Reads the persisted session blob from `sessionStorage`. Returns
+ * `null` (and auto-removes the entry) if the blob is missing,
+ * malformed, or already expired.
  */
-export function storeExpiresAt(options: StoreExpiresAtOptions): void {
-  const { context, expiresAtMs } = options;
-  context.store.setState({ expiresAt: expiresAtMs });
-  context.sessionStorage.setItem(EXPIRES_AT_KEY, String(expiresAtMs));
+export function getSessionFromSessionStorage(
+  context: AppConnectContext
+): StoredSession | null {
+  return readStoredSession(context);
 }
 
 /**
- * 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.
+ * Persists both `expiresAt` and `whoami` to the in-memory store and
+ * `sessionStorage` as a single JSON blob. Called from `init.ts` after
+ * a successful OAuth token exchange.
  */
-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;
+export function storeSession(options: {
+  context: AppConnectContext;
+  expiresAtMs: number;
+  whoami: AuthCompleteWhoami;
+}): void {
+  const { context, expiresAtMs, whoami } = options;
+  context.store.setState({ expiresAt: expiresAtMs, whoami });
+  writeStoredSession(context, { expiresAt: expiresAtMs, whoami });
+}
+
+/**
+ * Updates only `expiresAt` in both the store and `sessionStorage`,
+ * preserving the existing `whoami` from in-memory store state. Called
+ * from `refresh.ts` after a successful token refresh.
+ */
+export function storeExpiresAt(options: {
+  context: AppConnectContext;
+  expiresAtMs: number;
+}): void {
+  const { context, expiresAtMs } = options;
+  const currentWhoami = context.store.getSnapshot().whoami;
+  context.store.setState({ expiresAt: expiresAtMs });
+  writeStoredSession(context, {
+    expiresAt: expiresAtMs,
+    whoami: currentWhoami,
+  });
 }
 
 /**
- * Clears the persisted session-storage state. Called on disconnect.
+ * Removes the single session-storage key, clearing all persisted
+ * session state. Called on disconnect and on auth-complete errors.
  */
 export function clearSessionStorage(context: AppConnectContext): void {
-  context.sessionStorage.removeItem(EXPIRES_AT_KEY);
+  context.sessionStorage.removeItem(SESSION_STORAGE_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.
+ * is still in the future. Used to drive the UI status and the refresh
+ * scheduler.
  */
 export function isClientSessionActive(context: AppConnectContext): boolean {
   const state = context.store.getSnapshot();

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

@@ -13,6 +13,7 @@ function makeState(
     isDisconnectInFlight: false,
     error: null,
     expiresAt: null,
+    whoami: null,
     ...overrides,
   };
 }

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

@@ -11,6 +11,7 @@ const noop = (): Promise<void> => Promise.resolve();
 export const SERVER_VIEW: AppConnectState = {
   status: 'initializing',
   error: null,
+  whoami: null,
   connectToHubSpot: noop,
   disconnectFromHubSpot: noop,
 };

package/src/browser/react/components/AppConnectHeader/AppConnectHeader.tsx

@@ -9,28 +9,6 @@ import { LogoutIcon } from '../icons/LogoutIcon.tsx';
 import { ShareButton } from '../ShareButton/ShareButton.tsx';
 import { styles } from './AppConnectHeader.css.ts';
 
-interface FakeUser {
-  firstName: string;
-  lastName: string;
-  email: string;
-}
-
-const FAKE_USER: FakeUser = {
-  firstName: 'Gabby',
-  lastName: 'Martinez',
-  email: 'gabby.martinez@acmecorp.com',
-};
-
-function getUserInitials(user: FakeUser): string {
-  const first = user.firstName.charAt(0).toUpperCase();
-  const last = user.lastName.charAt(0).toUpperCase();
-  return `${first}${last}`;
-}
-
-function getFullName(user: FakeUser): string {
-  return `${user.firstName} ${user.lastName}`;
-}
-
 interface AppConnectHeaderProps {
   title: string;
 }
@@ -56,6 +34,8 @@ export function AppConnectHeader({ title }: AppConnectHeaderProps) {
 }
 
 function ViewingHubSpotContextRow() {
+  const { whoami } = useHubSpotAppConnect();
+  const hubLabel = whoami?.hub?.domain ?? whoami?.hub?.id ?? 'HubSpot';
   return (
     <div className={styles.contextRow}>
       <HubSpotDataSourceIcon className={styles.contextIcon} />
@@ -67,7 +47,7 @@ function ViewingHubSpotContextRow() {
           event.preventDefault();
         }}
       >
-        Acme Corp · HubSpot
+        {hubLabel}
         <ExternalLinkIcon className={styles.contextExternalIcon} />
       </a>
     </div>
@@ -75,9 +55,16 @@ function ViewingHubSpotContextRow() {
 }
 
 function UserMenu() {
-  const { disconnectFromHubSpot } = useHubSpotAppConnect();
-  const initials = getUserInitials(FAKE_USER);
-  const fullName = getFullName(FAKE_USER);
+  const { whoami, disconnectFromHubSpot } = useHubSpotAppConnect();
+  const user = whoami?.user;
+  const nameParts = [user?.firstName, user?.lastName].filter(
+    (p): p is string => typeof p === 'string' && p.length > 0
+  );
+  const initials =
+    nameParts.map((n) => n[0]!.toUpperCase()).join('') ||
+    user?.email?.[0]?.toUpperCase() ||
+    '?';
+  const displayName = nameParts.join(' ') || user?.email || 'HubSpot User';
 
   return (
     <Menu.Root modal={false}>
@@ -88,7 +75,7 @@ function UserMenu() {
         >
           {initials}
         </span>
-        <span className={styles.triggerName}>{fullName}</span>
+        <span className={styles.triggerName}>{displayName}</span>
         <ChevronDownIcon className={styles.chevron} />
       </Menu.Trigger>
       <Menu.Portal>
@@ -102,8 +89,10 @@ function UserMenu() {
                 {initials}
               </span>
               <div className={styles.userInfoText}>
-                <span className={styles.userInfoName}>{fullName}</span>
-                <span className={styles.userInfoEmail}>{FAKE_USER.email}</span>
+                <span className={styles.userInfoName}>{displayName}</span>
+                {user?.email ? (
+                  <span className={styles.userInfoEmail}>{user.email}</span>
+                ) : null}
               </div>
             </div>
             <Menu.Separator className={styles.separator} />

package/src/browser/types.ts

@@ -1,3 +1,5 @@
+import type { AuthCompleteWhoami } from '../shared/wire-types.ts';
+
 /**
  * How the browser navigates to HubSpot's OAuth authorize endpoint when
  * the user calls `connectToHubSpot`.
@@ -55,6 +57,13 @@ export interface AppConnectState {
   status: AppConnectStatus;
   /** Last error message that occurred, or `null` if no error. */
   error: string | null;
+  /**
+   * Identity of the connected HubSpot user and their account. Populated
+   * after a successful OAuth flow on a best-effort basis (fields may be
+   * absent if the access token lacked the required scopes). `null` before
+   * connect or after disconnect.
+   */
+  whoami: AuthCompleteWhoami | null;
   /**
    * Begins the OAuth connect flow. On success the browser either
    * redirects to HubSpot's authorize endpoint or opens it in a popup

package/src/server/hono/hubspot-connect-routes/auth-complete.test.ts

@@ -78,6 +78,57 @@ function buildCompleteUrl(stateValue: string, code = 'test-auth-code'): string {
   return url.toString();
 }
 
+const MOCK_TOKEN_RESPONSE = {
+  access_token: 'new-access-token',
+  refresh_token: 'new-refresh-token',
+  expires_in: 1800,
+};
+
+const MOCK_INTROSPECT_RESPONSE = {
+  active: true,
+  token_use: 'access_token',
+  hub_id: 42,
+  user_id: 99,
+  app_id: 1,
+  client_id: 'test-client-id',
+  is_private_distribution: false,
+  scopes: ['crm.objects.contacts.read'],
+  signed_access_token: {},
+  token: 'new-access-token',
+  token_type: 'Bearer',
+};
+
+const MOCK_PORTAL_RESPONSE = {
+  portalId: 42,
+  uiDomain: 'app.hubspot.com',
+  accountType: 'STANDARD',
+  timeZone: 'UTC',
+  companyCurrency: 'USD',
+  dataHostingLocation: 'US',
+  utcOffset: '+00:00',
+  utcOffsetMilliseconds: 0,
+  additionalCurrencies: [],
+};
+
+const MOCK_USER_RESPONSE = {
+  id: '99',
+  email: 'user@example.com',
+  firstName: 'Pat',
+  lastName: 'Test',
+  roleIds: [],
+  superAdmin: false,
+};
+
+function mockFetchSequence(responses: unknown[]): ReturnType<typeof vi.spyOn> {
+  let spy = vi.spyOn(globalThis, 'fetch');
+  for (const body of responses) {
+    spy = spy.mockResolvedValueOnce(
+      new Response(JSON.stringify(body), { status: 200 })
+    );
+  }
+  return spy;
+}
+
 describe('handleAuthComplete', () => {
   afterEach(() => {
     vi.restoreAllMocks();
@@ -192,16 +243,12 @@ describe('handleAuthComplete', () => {
   });
 
   it('sends the OAuth token endpoint the same redirect_uri it advertised in init-session', async () => {
-    const fetchSpy = vi.spyOn(globalThis, 'fetch').mockResolvedValue(
-      new Response(
-        JSON.stringify({
-          access_token: 'at',
-          refresh_token: 'rt',
-          expires_in: 1800,
-        }),
-        { status: 200 }
-      )
-    );
+    const fetchSpy = mockFetchSequence([
+      { access_token: 'at', refresh_token: 'rt', expires_in: 1800 },
+      MOCK_INTROSPECT_RESPONSE,
+      MOCK_PORTAL_RESPONSE,
+      MOCK_USER_RESPONSE,
+    ]);
     const app = new Hono();
     app.post(`${BASE_PATH}/auth/complete`, (c) =>
       handleAuthComplete(c, buildOAuthRouteOptions())
@@ -223,16 +270,12 @@ describe('handleAuthComplete', () => {
 
   it('returns 200 with expires_at + return_path and sets durable cookies on success', async () => {
     const beforeMs = Date.now();
-    vi.spyOn(globalThis, 'fetch').mockResolvedValue(
-      new Response(
-        JSON.stringify({
-          access_token: 'new-access-token',
-          refresh_token: 'new-refresh-token',
-          expires_in: 1800,
-        }),
-        { status: 200 }
-      )
-    );
+    mockFetchSequence([
+      MOCK_TOKEN_RESPONSE,
+      MOCK_INTROSPECT_RESPONSE,
+      MOCK_PORTAL_RESPONSE,
+      MOCK_USER_RESPONSE,
+    ]);
     const app = new Hono();
     app.post(`${BASE_PATH}/auth/complete`, (c) =>
       handleAuthComplete(c, buildOAuthRouteOptions())
@@ -250,9 +293,19 @@ describe('handleAuthComplete', () => {
     const body = (await res.json()) as {
       expires_at: number;
       return_path: string;
+      whoami: { user?: { id: string; email: string }; hub?: { id: number } };
     };
     expect(body.return_path).toBe('/dashboard');
     expect(body.expires_at).toBeGreaterThanOrEqual(beforeMs + 1800 * 1000 - 50);
+    expect(body.whoami.user).toMatchObject({
+      id: '99',
+      email: 'user@example.com',
+      firstName: 'Pat',
+    });
+    expect(body.whoami.hub).toMatchObject({
+      id: 42,
+      uiDomain: 'app.hubspot.com',
+    });
 
     const setCookies = res.headers.getSetCookie();
 
@@ -282,4 +335,60 @@ describe('handleAuthComplete', () => {
     );
     expect(stateCleared).toContain('Max-Age=0');
   });
+
+  it('returns 200 with whoami.hub only when introspect fails', async () => {
+    vi.spyOn(globalThis, 'fetch')
+      .mockResolvedValueOnce(
+        new Response(JSON.stringify(MOCK_TOKEN_RESPONSE), { status: 200 })
+      )
+      .mockResolvedValueOnce(
+        new Response(JSON.stringify({ error: 'unauthorized_client' }), {
+          status: 401,
+        })
+      )
+      .mockResolvedValueOnce(
+        new Response(JSON.stringify(MOCK_PORTAL_RESPONSE), { status: 200 })
+      );
+    const app = new Hono();
+    app.post(`${BASE_PATH}/auth/complete`, (c) =>
+      handleAuthComplete(c, buildOAuthRouteOptions())
+    );
+    const { stateValue, cookieHeader } = buildCompleteFixture();
+    const res = await app.request(buildCompleteUrl(stateValue), {
+      method: 'POST',
+      headers: { Cookie: cookieHeader },
+    });
+
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as {
+      whoami: { user: unknown; hub?: { id: number } };
+    };
+    expect(body.whoami.user).toEqual({});
+    expect(body.whoami.hub).toMatchObject({ id: 42 });
+  });
+
+  it('returns 200 with empty whoami when all whoami calls fail', async () => {
+    vi.spyOn(globalThis, 'fetch')
+      .mockResolvedValueOnce(
+        new Response(JSON.stringify(MOCK_TOKEN_RESPONSE), { status: 200 })
+      )
+      .mockResolvedValueOnce(new Response('', { status: 500 }))
+      .mockResolvedValueOnce(new Response('', { status: 500 }));
+    const app = new Hono();
+    app.post(`${BASE_PATH}/auth/complete`, (c) =>
+      handleAuthComplete(c, buildOAuthRouteOptions())
+    );
+    const { stateValue, cookieHeader } = buildCompleteFixture();
+    const res = await app.request(buildCompleteUrl(stateValue), {
+      method: 'POST',
+      headers: { Cookie: cookieHeader },
+    });
+
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as {
+      whoami: { user: unknown; hub: unknown };
+    };
+    expect(body.whoami.user).toEqual({});
+    expect(body.whoami.hub).toEqual({});
+  });
 });

package/src/server/hono/hubspot-connect-routes/auth-complete.ts

@@ -4,6 +4,7 @@ import {
   AUTH_COMPLETE_CODE_PARAM,
   AUTH_COMPLETE_STATE_PARAM,
 } from '../../../shared/constants.ts';
+import type { AuthCompleteResponse } from '../../../shared/wire-types.ts';
 import {
   HUBSPOT_ACCESS_TOKEN_COOKIE_NAME,
   HUBSPOT_APP_ORIGIN_COOKIE_NAME,
@@ -31,6 +32,7 @@ import {
   isSafeReturnPath,
   parseAppOriginHeader,
 } from './utils.ts';
+import { fetchWhoami } from './whoami.ts';
 
 interface OAuthStatePayload {
   return_path?: string;
@@ -238,5 +240,10 @@ export async function handleAuthComplete(
   setResponseCookie({ c, value: clearTempCookie(TEMP_COOKIE_PKCE_VERIFIER) });
   setResponseCookie({ c, value: clearTempCookie(TEMP_COOKIE_OAUTH_STATE) });
 
-  return c.json({ expires_at: expiresAt, return_path: returnPath });
+  const whoami = await fetchWhoami(accessToken, hubspotConnectEnv);
+  return c.json({
+    expires_at: expiresAt,
+    return_path: returnPath,
+    whoami,
+  } satisfies AuthCompleteResponse);
 }

package/src/server/hono/hubspot-connect-routes/whoami.ts

@@ -0,0 +1,74 @@
+import type { AuthCompleteWhoami } from '../../../shared/wire-types.ts';
+import {
+  account,
+  authOauth,
+  createHubSpotClient,
+  settingsUsers,
+} from '../../api-client-core/index.ts';
+import { fetchTransportPlugin } from '../../api-client-core/plugins/fetch-transport.ts';
+import { getHubSpotApiOrigin } from '../../utils/env-utils.ts';
+import type { HubSpotConnectRoutesEnv } from './load-hubspot-connect-routes-env.ts';
+
+export async function fetchWhoami(
+  accessToken: string,
+  hubspotConnectEnv: HubSpotConnectRoutesEnv
+): Promise<AuthCompleteWhoami> {
+  const apiClient = createHubSpotClient({
+    plugins: [
+      fetchTransportPlugin({
+        getEndpoint: getHubSpotApiOrigin,
+        getAccessToken: () => accessToken,
+      }),
+    ],
+  });
+
+  const introspectInput = hubspotConnectEnv.isCimdEnabled
+    ? { token: accessToken }
+    : {
+        client_id: hubspotConnectEnv.hubspotClientId,
+        client_secret: hubspotConnectEnv.hubspotClientSecret,
+        token: accessToken,
+      };
+
+  // Introspect and account.get are independent — run in parallel.
+  // settingsUsers.get requires user_id from introspect, so it runs after.
+  const [introspectResult, hubResult] = await Promise.allSettled([
+    apiClient.send(authOauth.introspectToken(introspectInput)),
+    apiClient.send(account.get()),
+  ]);
+
+  const whoami: AuthCompleteWhoami = {
+    hub: {},
+    user: {},
+  };
+
+  if (hubResult.status === 'fulfilled') {
+    const portal = hubResult.value;
+    whoami.hub.id = portal.portalId;
+    whoami.hub.uiDomain = portal.uiDomain;
+  }
+
+  if (
+    introspectResult.status === 'fulfilled' &&
+    introspectResult.value.token_use === 'access_token'
+  ) {
+    whoami.hub.domain = introspectResult.value.hub_domain;
+
+    const userId = String(introspectResult.value.user_id);
+    const userResult = await apiClient
+      .send(settingsUsers.get({ userId, idProperty: 'USER_ID' }))
+      .then(
+        (u) => ({ ok: true as const, value: u }),
+        () => ({ ok: false as const })
+      );
+    if (userResult.ok) {
+      const u = userResult.value;
+      whoami.user.id = u.id;
+      whoami.user.email = u.email;
+      whoami.user.firstName = u.firstName;
+      whoami.user.lastName = u.lastName;
+    }
+  }
+
+  return whoami;
+}

package/src/shared/wire-types.ts

@@ -15,6 +15,30 @@ export interface InitSessionResponse {
   authorization_url: string;
 }
 
+export interface AuthCompleteWhoamiUser {
+  id?: string | undefined;
+  email?: string | undefined;
+  firstName?: string | undefined;
+  lastName?: string | undefined;
+}
+
+export interface AuthCompleteWhoamiHub {
+  id?: number | undefined;
+  domain?: string | undefined;
+  uiDomain?: string | undefined;
+}
+
+/**
+ * Identity information for the authenticated user and their HubSpot
+ * account. Both fields are optional because the access token may not
+ * carry the scopes needed to fetch each piece (`public-users-read` for
+ * `user`, `external-settings-access` for `hub`).
+ */
+export interface AuthCompleteWhoami {
+  user: AuthCompleteWhoamiUser;
+  hub: AuthCompleteWhoamiHub;
+}
+
 /**
  * Body returned by `POST /auth/complete` once the SDK has exchanged
  * the OAuth authorization code for an access + refresh token. The
@@ -32,6 +56,12 @@ export interface AuthCompleteResponse {
    * `/` and is restricted to safe internal paths.
    */
   return_path: string;
+  /**
+   * Identity of the authenticated user and their HubSpot account.
+   * Populated on a best-effort basis — fields are absent when the
+   * access token lacks the required scopes.
+   */
+  whoami: AuthCompleteWhoami;
 }
 
 /**