@sanity/sdk-react 3.4.0 → 3.5.0-next.20260922190712

package/src/hooks/auth/useOAuthTokens.tsx

@@ -0,0 +1,104 @@
+import {
+  getOAuthTokensState,
+  type OAuthTokens,
+  refreshOAuthTokens,
+  revokeOAuthTokens,
+  type SanityInstance,
+} from '@sanity/sdk'
+
+import {createCallbackHook} from '../helpers/createCallbackHook'
+import {createStateSourceHook} from '../helpers/createStateSourceHook'
+
+/**
+ * The current OAuth token state, plus actions to refresh and revoke it.
+ *
+ * @public
+ */
+export interface UseOAuthTokensResult {
+  /**
+   * The stored OAuth tokens, or `null` when not logged in via OAuth. The
+   * refresh token is omitted — core retains it internally for `refresh`.
+   */
+  tokens: Omit<OAuthTokens, 'refreshToken'> | null
+  /**
+   * Returns whether the access token has expired, comparing the latest stored
+   * `expiresAt` against the current time at the moment it is called. Both the
+   * tokens and the clock are read at call time, so a reference captured in an
+   * earlier render stays accurate after a `refresh`. Reading the clock does not
+   * trigger a re-render, so call this in an event handler or effect rather than
+   * during render. Returns `false` when there are no tokens.
+   */
+  isExpired: () => boolean
+  /**
+   * Refresh via the OAuth `refresh_token` grant. When there is no refresh token,
+   * core clears the stored tokens, logs the user out, and this resolves `null`.
+   * Rejects on transient failures (network, 5xx, 408, 429), leaving tokens
+   * unchanged so the call can be retried. Also rejects when the server rejects
+   * the refresh token itself (other 4xx); core clears the tokens and logs out
+   * first, so check `tokens` before retrying.
+   */
+  refresh: () => Promise<Omit<OAuthTokens, 'refreshToken'> | null>
+  /** Revoke the tokens at the OAuth server, clear them locally, and log out. */
+  revoke: () => Promise<void>
+}
+
+const useOAuthTokensState = createStateSourceHook(getOAuthTokensState)
+const useRefreshOAuthTokens = createCallbackHook(refreshOAuthTokens)
+const useRevokeOAuthTokens = createCallbackHook(revokeOAuthTokens)
+
+// Reads core's state source directly rather than the render-time `tokens`
+// snapshot, so a reference captured in an earlier render (e.g. in an event
+// handler that awaits `refresh()`) still reflects the latest tokens.
+const useIsOAuthTokenExpired = createCallbackHook((instance: SanityInstance): boolean => {
+  const tokens = getOAuthTokensState(instance).getCurrent()
+  return tokens ? tokens.expiresAt.getTime() <= Date.now() : false
+})
+
+/**
+ * A React hook that exposes the stored OAuth token state along with `refresh`
+ * and `revoke` actions.
+ *
+ * @remarks
+ * The token view is a synchronous read over core's token state source, so the
+ * hook re-renders whenever tokens change — including changes made in another
+ * tab, which core propagates via `storage` events.
+ *
+ * @returns The current {@link UseOAuthTokensResult}
+ *
+ * @example
+ * ```tsx
+ * function TokenStatus() {
+ *   const {tokens, isExpired, refresh, revoke} = useOAuthTokens()
+ *
+ *   if (!tokens) return <div>Not signed in</div>
+ *
+ *   const handleRefresh = async () => {
+ *     if (!isExpired()) return
+ *     try {
+ *       await refresh()
+ *     } catch {
+ *       // Transient failure (tokens unchanged, retry later) or the refresh
+ *       // token was rejected (tokens now null, user is logged out).
+ *     }
+ *   }
+ *
+ *   return (
+ *     <div>
+ *       <p>Expires at {tokens.expiresAt.toLocaleTimeString()}</p>
+ *       <button onClick={handleRefresh}>Refresh if expired</button>
+ *       <button onClick={() => revoke()}>Revoke tokens</button>
+ *     </div>
+ *   )
+ * }
+ * ```
+ *
+ * @public
+ */
+export function useOAuthTokens(): UseOAuthTokensResult {
+  return {
+    tokens: useOAuthTokensState(),
+    isExpired: useIsOAuthTokenExpired(),
+    refresh: useRefreshOAuthTokens(),
+    revoke: useRevokeOAuthTokens(),
+  }
+}

package/src/hooks/dashboard/useApplications.test.tsx

@@ -1,5 +1,16 @@
+import {
+  type Application,
+  type ApplicationInclude,
+  type Installation,
+  type InstallationInclude,
+} from '@sanity/sdk'
 import {installMessageBus, resetMessageBus} from '@sanity/sdk/_internal'
-import {type MessageBusHost, TopicError, type ValueOf} from '@sanity/sdk/dashboard'
+import {
+  type LocalApplication,
+  type MessageBusHost,
+  TopicError,
+  type ValueOf,
+} from '@sanity/sdk/dashboard'
 import {Suspense} from 'react'
 import {ErrorBoundary} from 'react-error-boundary'
 import {afterEach, beforeEach, describe, expect, expectTypeOf, it, vi} from 'vitest'
@@ -62,7 +73,7 @@ const application = {
         title: 'Summary',
         version: '1',
         moduleId: 'views/summary',
-        metadata: null,
+        metadata: {size: 'small'},
       },
       {
         id: 'asset-source-1',
@@ -84,7 +95,7 @@ const application = {
       },
     ],
   },
-}
+} satisfies Application<ApplicationInclude>
 
 const nonFederatedApplication = {
   ...application,
@@ -95,7 +106,7 @@ const nonFederatedApplication = {
   title: 'Legacy',
   isSingleton: false,
   config: {},
-}
+} satisfies Application<ApplicationInclude>
 
 const nonSingletonApplication = {
   ...application,
@@ -105,7 +116,7 @@ const nonSingletonApplication = {
   slug: 'canvas',
   title: 'Canvas',
   isSingleton: false,
-}
+} satisfies Application<ApplicationInclude>
 
 const externalApplication = {
   ...application,
@@ -113,7 +124,57 @@ const externalApplication = {
   name: 'external',
   slug: null,
   externalUrl: 'https://apps.example.com/external/index.html',
-}
+} satisfies Application<ApplicationInclude>
+
+// The workbench synthesises a dev-server app into the deployed shape and marks it with `local`.
+const localApplication = {
+  ...application,
+  id: 'application-5',
+  name: 'dev',
+  slug: null,
+  isSingleton: false,
+  externalUrl: 'http://localhost:3333',
+  organizationId: 'local',
+  local: {host: 'localhost', port: 3333},
+} satisfies LocalApplication
+
+const installation = {
+  id: 'installation-1',
+  applicationId: 'app-remote-1',
+  organizationId: 'organization-1',
+  installedBy: 'user-1',
+  createdAt: '2026-01-01T00:00:00.000Z',
+  updatedAt: '2026-01-02T00:00:00.000Z',
+  application: {
+    title: 'Remote App',
+    name: 'remote',
+    reference: 'sanity/remote',
+    slug: 'remote',
+    icon: null,
+    // Distinct from the installing org: the bundle is hosted under the publisher's org.
+    organizationId: 'organization-publisher',
+  },
+  interfaces: [
+    {
+      id: 'remote-view-1',
+      type: 'app',
+      name: 'remote',
+      title: 'Remote App',
+      version: '1',
+      moduleId: 'App',
+      metadata: null,
+    },
+    {
+      id: 'remote-panel-1',
+      type: 'panel',
+      name: 'remote-panel',
+      title: 'Remote Panel',
+      version: '1',
+      moduleId: 'views/panel',
+      metadata: null,
+    },
+  ],
+} satisfies Installation<InstallationInclude>
 
 const emitApplications = (value: unknown[]) =>
   host.connections.subscribe((client) =>
@@ -140,8 +201,12 @@ describe('useApplications', () => {
     const {result} = renderHook(() => useApplications())
 
     expectTypeOf(result.current).toEqualTypeOf<DashboardApplication[]>()
+    // The application member keeps its raw deployment fields; the union also admits installations.
     expectTypeOf<
-      Extract<keyof DashboardApplication, 'activeDeployment' | 'config'>
+      Extract<
+        keyof Exclude<DashboardApplication, {type: 'installation'}>,
+        'activeDeployment' | 'config'
+      >
     >().toEqualTypeOf<'activeDeployment' | 'config'>()
     const [federated, nonFederated, nonSingleton] = result.current
     expect(federated).toMatchObject({
@@ -180,6 +245,99 @@ describe('useApplications', () => {
     ])
     expect(nonFederated).toMatchObject({views: [], webWorkers: []})
     expect(nonSingleton?.views[0]?.module.entry).toBe('https://canvas.sanity.studio')
+    expect(result.current.map(({isLocal}) => isLocal)).toEqual([false, false, false])
+  })
+
+  it('marks dev-server applications local and loads their modules from the dev server', () => {
+    emitApplications([application, localApplication, installation])
+
+    const {result} = renderHook(() => useApplications())
+
+    expect(result.current.map(({id, isLocal}) => [id, isLocal])).toEqual([
+      ['application-1', false],
+      ['application-5', true],
+      ['installation-1', false],
+    ])
+    const local = result.current[1]
+    expect(local).toMatchObject({type: 'coreApp', local: {host: 'localhost', port: 3333}})
+    expect(local?.views[0]?.module.entry).toBe('http://localhost:3333')
+    expect(local?.views[0]?.application).toMatchObject({id: 'application-5', isLocal: true})
+  })
+
+  it('shapes installations alongside applications in one consistent shape', () => {
+    emitApplications([application, installation])
+
+    const {result} = renderHook(() => useApplications())
+
+    const shaped = result.current.find(({id}) => id === 'installation-1')
+    expect(shaped).toMatchObject({
+      id: 'installation-1',
+      type: 'installation',
+      title: 'Remote App',
+      name: 'remote',
+      reference: 'sanity/remote',
+      slug: 'remote',
+      icon: null,
+      isSingleton: true,
+      visibility: 'default',
+      externalUrl: null,
+      organizationId: 'organization-publisher',
+      createdAt: '2026-01-01T00:00:00.000Z',
+      updatedAt: '2026-01-02T00:00:00.000Z',
+      installation,
+    })
+    // Raw record fields must not leak onto the shaped entry, nor the raw record onto its views.
+    expect(shaped).not.toHaveProperty('applicationId')
+    expect(shaped).not.toHaveProperty('installedBy')
+    expect(shaped?.views[0]?.application).not.toHaveProperty('installation')
+    expect(shaped?.views).toEqual([
+      expect.objectContaining({
+        name: 'remote',
+        surface: 'window',
+        module: {
+          entry: 'https://remote-apps-organization-publisher.sanity.run',
+          moduleId: 'installation-1/App',
+          version: '1',
+        },
+      }),
+      expect.objectContaining({
+        name: 'remote-panel',
+        surface: 'panel',
+        module: expect.objectContaining({moduleId: 'installation-1/views/panel'}),
+      }),
+    ])
+    expect(shaped?.webWorkers).toEqual([])
+  })
+
+  it('exposes no views for an installation without interfaces', () => {
+    const {interfaces: _interfaces, ...withoutInterfaces} = installation
+    emitApplications([withoutInterfaces])
+
+    const {result} = renderHook(() => useApplications())
+
+    expect(result.current[0]).toMatchObject({id: 'installation-1', views: [], webWorkers: []})
+  })
+
+  it('exposes no views for an installation without a slug to derive an origin from', () => {
+    emitApplications([{...installation, application: {...installation.application, slug: null}}])
+
+    const {result} = renderHook(() => useApplications())
+
+    expect(result.current[0]).toMatchObject({id: 'installation-1', views: [], webWorkers: []})
+  })
+
+  it('loads a dev-server application without a module federation manifest', () => {
+    const {config: _config, ...withoutManifest} = localApplication
+    emitApplications([withoutManifest])
+
+    const {result} = renderHook(() => useApplications())
+
+    expect(result.current[0]?.views.map(({name}) => name)).toEqual([
+      'inbox',
+      'notifications',
+      'summary',
+      'library',
+    ])
   })
 
   it('follows topic updates without remapping unchanged lists', () => {

package/src/hooks/dashboard/useApplications.ts

@@ -1,62 +1,94 @@
-import {type ApplicationBase} from '@sanity/sdk'
+import {type ApplicationBase, type Installation, type InstallationInclude} from '@sanity/sdk'
 import {getApplicationOrigin} from '@sanity/sdk/_internal'
 import {type RemoteModuleRef, type ValueOf} from '@sanity/sdk/dashboard'
 import {useMemo} from 'react'
 
 import {useTopic} from './useTopic'
 
-type DashboardTopicApplication = Extract<
+type DashboardTopicEntry = Extract<
   NonNullable<ValueOf<'applications.list'>>,
   {ok: true}
 >['value'][number]
+// The published union distinguishes an `Application` (has `type`) from an `Installation` (has not).
+type DashboardTopicApplication = Extract<DashboardTopicEntry, {type: unknown}>
+type DashboardTopicInstallation = Exclude<DashboardTopicEntry, {type: unknown}>
 type DashboardApplicationInterface = NonNullable<
   NonNullable<DashboardTopicApplication['activeDeployment']>['interfaces']
 >[number]
 type ViewInterface = Exclude<DashboardApplicationInterface, {type: 'worker'}>
 
 /**
- * A dashboard view exposed by an application.
+ * The shared identity fields attached to each {@link DashboardView.application} and
+ * {@link DashboardWebWorker.application}, and the input to module loading. Widens
+ * {@link ApplicationBase} so `type` also covers installations.
+ * @public
+ */
+export type DashboardApplicationBase = Omit<ApplicationBase, 'type'> & {
+  readonly type: ApplicationBase['type'] | 'installation'
+  /** Served by a CLI dev server rather than a deployment. */
+  readonly isLocal: boolean
+}
+
+/**
+ * A dashboard view exposed by an application or installation.
  * @public
  */
 export type DashboardView = {
   [Type in ViewInterface['type']]: Omit<Extract<ViewInterface, {type: Type}>, 'type'> & {
-    readonly application: ApplicationBase
+    readonly application: DashboardApplicationBase
     readonly module: RemoteModuleRef
     readonly surface: Type extends 'app' ? 'window' : Type
   }
 }[ViewInterface['type']]
 
 /**
- * A web worker exposed by an application.
+ * A web worker exposed by an application or installation.
  * @public
  */
 export type DashboardWebWorker = Extract<DashboardApplicationInterface, {type: 'worker'}> & {
-  readonly application: ApplicationBase
+  readonly application: DashboardApplicationBase
   readonly module: RemoteModuleRef
 }
 
 /**
- * The minimal Brett application fields with its loadable views and web workers.
+ * An installation shaped into the shared application base, with its raw record kept under
+ * `installation` for consumers that need the full record.
  * @public
  */
-export type DashboardApplication = DashboardTopicApplication & {
-  readonly views: DashboardView[]
-  readonly webWorkers: DashboardWebWorker[]
+export type DashboardInstallation = Omit<DashboardApplicationBase, 'type'> & {
+  readonly type: 'installation'
+  readonly installation: Installation<InstallationInclude>
 }
 
+/**
+ * A dashboard entry — an application or an installation — in one consistent shape, with its
+ * loadable views and web workers. `type` distinguishes the kinds and `isLocal` marks dev-server
+ * applications; render a list without branching.
+ * @public
+ */
+export type DashboardApplication = (DashboardTopicApplication | DashboardInstallation) &
+  Pick<DashboardApplicationBase, 'isLocal'> & {
+    readonly views: DashboardView[]
+    readonly webWorkers: DashboardWebWorker[]
+  }
+
 // Only a federated deployment (one with a module federation manifest) exposes loadable modules.
-const loadableInterfaces = ({
-  activeDeployment,
-  config,
-}: DashboardTopicApplication): readonly DashboardApplicationInterface[] =>
-  config?.mfManifest === undefined ? [] : (activeDeployment?.interfaces ?? [])
+// A dev server is always federated, whether or not the workbench synthesised a manifest for it.
+const loadableInterfaces = (
+  {activeDeployment, config}: DashboardTopicApplication,
+  isLocal: boolean,
+): readonly DashboardApplicationInterface[] =>
+  isLocal || config?.mfManifest !== undefined ? (activeDeployment?.interfaces ?? []) : []
 
-const toApplication = (application: DashboardTopicApplication): DashboardApplication => {
-  const {activeDeployment: _activeDeployment, config: _config, ...applicationBase} = application
-  const interfaces = loadableInterfaces(application)
+// Turns an interface list into views and web workers loaded from `base`'s origin. Shared by
+// applications and installations so the surface mapping lives in one place.
+const loadModules = (
+  base: DashboardApplicationBase,
+  interfaces: readonly DashboardApplicationInterface[],
+): {views: DashboardView[]; webWorkers: DashboardWebWorker[]} => {
   // Nothing to load without interfaces or an origin to load them from.
-  const entry = interfaces.length === 0 ? null : getApplicationOrigin(applicationBase)
-  if (entry === null) return {...application, views: [], webWorkers: []}
+  const entry = interfaces.length === 0 ? null : getApplicationOrigin(base)
+  if (entry === null) return {views: [], webWorkers: []}
 
   const views: DashboardView[] = []
   const webWorkers: DashboardWebWorker[] = []
@@ -64,12 +96,12 @@ const toApplication = (application: DashboardTopicApplication): DashboardApplica
   for (const extension of interfaces) {
     const module: RemoteModuleRef = {
       entry,
-      moduleId: `${applicationBase.id}/${extension.moduleId}`,
+      moduleId: `${base.id}/${extension.moduleId}`,
       version: extension.version,
     }
 
     if (extension.type === 'worker') {
-      webWorkers.push({...extension, application: applicationBase, module})
+      webWorkers.push({...extension, application: base, module})
       continue
     }
 
@@ -78,20 +110,66 @@ const toApplication = (application: DashboardTopicApplication): DashboardApplica
     // cast is checked by the `DashboardView` mapping above and the surface assertions in the tests.
     views.push({
       ...view,
-      application: applicationBase,
+      application: base,
       module,
       surface: type === 'app' ? 'window' : type,
     } as DashboardView)
   }
 
-  return {...application, views, webWorkers}
+  return {views, webWorkers}
+}
+
+const toApplication = (application: DashboardTopicApplication): DashboardApplication => {
+  const {activeDeployment: _activeDeployment, config: _config, ...applicationBase} = application
+  const isLocal = 'local' in application
+  return {
+    ...application,
+    isLocal,
+    ...loadModules({...applicationBase, isLocal}, loadableInterfaces(application, isLocal)),
+  }
+}
+
+const toInstallation = (installation: DashboardTopicInstallation): DashboardApplication => {
+  const {application} = installation
+  // `id` is the installation record's id, not its `applicationId`, so two installs of one app never
+  // collide. `organizationId` is the publisher's: the singleton bundle is hosted under the org that
+  // published it, and `isSingleton: true` with `externalUrl: null` routes the origin through
+  // `getApplicationOrigin`'s singleton branch (`https://<slug>-apps-<publisherOrgId>.sanity.run`).
+  // The installing org stays on the raw record. The workbench always serves installations
+  // federated, so their interfaces are never gated.
+  const base: DashboardApplicationBase = {
+    id: installation.id,
+    type: 'installation',
+    isLocal: false,
+    title: application.title,
+    name: application.name,
+    reference: application.reference,
+    icon: application.icon,
+    isSingleton: true,
+    visibility: 'default',
+    slug: application.slug,
+    externalUrl: null,
+    organizationId: application.organizationId,
+    createdAt: installation.createdAt,
+    updatedAt: installation.updatedAt,
+  }
+  // The raw record rides only the entry, not every view's `application`.
+  return {
+    ...base,
+    type: 'installation',
+    installation,
+    ...loadModules(base, installation.interfaces ?? []),
+  }
 }
 
 /**
- * Returns the applications available in the dashboard.
+ * Returns the applications and installations available in the dashboard, in one consistent shape.
  *
- * Suspends until the dashboard publishes its application list; a cleared list is empty. Throws a
- * `TopicError` to the nearest error boundary when the dashboard fails to load applications.
+ * Suspends until the dashboard publishes its list; a cleared list is empty. Throws a `TopicError`
+ * to the nearest error boundary when the dashboard fails to load. Every entry exposes the same base
+ * fields plus `views` and `webWorkers`; `type` distinguishes applications (`'studio' | 'coreApp'`)
+ * from installations (`'installation'`), which also carry the raw record under `installation`.
+ * `isLocal` marks applications served by a CLI dev server.
  *
  * @example
  * ```tsx
@@ -105,5 +183,11 @@ const toApplication = (application: DashboardTopicApplication): DashboardApplica
  */
 export function useApplications(): DashboardApplication[] {
   const applications = useTopic('applications.list')
-  return useMemo(() => applications?.map(toApplication) ?? [], [applications])
+  return useMemo(
+    () =>
+      applications?.map((entry) =>
+        'type' in entry ? toApplication(entry) : toInstallation(entry),
+      ) ?? [],
+    [applications],
+  )
 }

package/src/hooks/dashboard/useStudioWorkspacesByProjectIdDataset.test.tsx

@@ -305,7 +305,22 @@ describe('useStudioWorkspacesByProjectIdDataset (message bus)', () => {
   })
 
   it('maps studio workspaces to resources keyed by projectId:dataset', () => {
-    emitApplications([studio, coreApp])
+    // An installation (no `type`) shares the topic; the hook must tolerate it and map only studios.
+    const installation = {id: 'installation-1', applicationId: 'app-remote-1'}
+    // A dev-server studio is still a studio, addressed by its dev server.
+    const localStudio = {
+      ...studio,
+      id: 'studio-local',
+      slug: null,
+      externalUrl: 'http://localhost:3333',
+      local: {host: 'localhost', port: 3333},
+      activeDeployment: {
+        ...deployment,
+        applicationId: 'studio-local',
+        workspaces: [{...workspace, id: 'workspace-local', projectId: 'project3'}],
+      },
+    }
+    emitApplications([studio, coreApp, installation, localStudio])
 
     const {result} = renderHookWithInstance(() => useStudioWorkspacesByProjectIdDataset())
 
@@ -327,6 +342,13 @@ describe('useStudioWorkspacesByProjectIdDataset (message bus)', () => {
         expect.objectContaining({id: 'workspace-2', title: 'My Studio', basePath: ''}),
       ],
       'project2:dataset2': [expect.objectContaining({id: 'workspace-3'})],
+      'project3:dataset1': [
+        expect.objectContaining({
+          id: 'workspace-local',
+          userApplicationId: 'studio-local',
+          url: 'http://localhost:3333',
+        }),
+      ],
     })
   })
 

package/src/hooks/dashboard/useStudioWorkspacesByProjectIdDataset.ts

@@ -79,7 +79,8 @@ export function useStudioWorkspacesByProjectIdDataset(): StudioWorkspacesResult
 // The legacy Comlink protocol models studios at the workspace level, so each workspace of a
 // studio's active deployment becomes one resource, addressed by the studio's origin.
 function toResources(application: DashboardApplications[number]): DashboardResource[] {
-  if (application.type !== 'studio') return []
+  // Installations join the topic union without a `type`; only studios yield workspace resources.
+  if (!('type' in application) || application.type !== 'studio') return []
   const url = getApplicationOrigin(application) ?? ''
   return (application.activeDeployment?.workspaces ?? []).map((workspace) => ({
     id: workspace.id,