@sanity/sdk-react 3.0.0-rc.0 → 3.0.0-rc.1

package/src/hooks/helpers/useNormalizedResourceOptions.test.tsx

@@ -0,0 +1,253 @@
+import {createSanityInstance, type DocumentHandle} from '@sanity/sdk'
+import {type ReactNode} from 'react'
+import {describe, expect, it} from 'vitest'
+
+import {renderHook, resources} from '../../../test/test-utils'
+import {ResourceProvider} from '../../context/ResourceProvider'
+import {ResourcesContext} from '../../context/ResourcesContext'
+import {SanityInstanceContext} from '../../context/SanityInstanceContext'
+import {useNormalizedResourceOptions} from './useNormalizedResourceOptions'
+
+// Wrapper that sets ResourceContext via the `resource` prop (tier 3).
+// Includes ResourcesContext so resourceName resolution also works in these tests.
+function ResourceContextWrapper({
+  children,
+  resource,
+}: {
+  children: ReactNode
+  resource: {projectId: string; dataset: string}
+}) {
+  return (
+    <ResourceProvider resource={resource} fallback={null}>
+      <ResourcesContext.Provider value={resources}>{children}</ResourcesContext.Provider>
+    </ResourceProvider>
+  )
+}
+
+// Wrapper that provides an instance with no projectId/dataset and no ResourceContext (tier 5).
+const bareInstance = createSanityInstance({})
+function NoResourceWrapper({children}: {children: ReactNode}) {
+  return (
+    <SanityInstanceContext.Provider value={bareInstance}>{children}</SanityInstanceContext.Provider>
+  )
+}
+
+describe('useNormalizedResourceOptions', () => {
+  describe('tier 1 — explicit options', () => {
+    it('uses an explicit dataset resource object', () => {
+      const {result} = renderHook(() =>
+        useNormalizedResourceOptions({resource: {projectId: 'explicit', dataset: 'explicit-ds'}}),
+      )
+      expect(result.current.resource).toEqual({projectId: 'explicit', dataset: 'explicit-ds'})
+    })
+
+    it('uses an explicit media-library resource object', () => {
+      const {result} = renderHook(() =>
+        useNormalizedResourceOptions({resource: {mediaLibraryId: 'ml-123'}}),
+      )
+      expect(result.current.resource).toEqual({mediaLibraryId: 'ml-123'})
+    })
+
+    it('uses an explicit canvas resource object', () => {
+      const {result} = renderHook(() =>
+        useNormalizedResourceOptions({resource: {canvasId: 'canvas-123'}}),
+      )
+      expect(result.current.resource).toEqual({canvasId: 'canvas-123'})
+    })
+
+    it('resolves resourceName to a named dataset resource', () => {
+      const {result} = renderHook(() => useNormalizedResourceOptions({resourceName: 'dataset'}))
+      expect(result.current.resource).toEqual({
+        projectId: 'resource-project-id',
+        dataset: 'resource-dataset',
+      })
+    })
+
+    it('resolves resourceName to a named media-library resource', () => {
+      const {result} = renderHook(() =>
+        useNormalizedResourceOptions({resourceName: 'media-library'}),
+      )
+      expect(result.current.resource).toEqual({mediaLibraryId: 'media-library-id'})
+    })
+
+    it('resolves resourceName to a named canvas resource', () => {
+      const {result} = renderHook(() => useNormalizedResourceOptions({resourceName: 'canvas'}))
+      expect(result.current.resource).toEqual({canvasId: 'canvas-id'})
+    })
+
+    it('throws when resourceName is not registered', () => {
+      expect(() =>
+        renderHook(() => useNormalizedResourceOptions({resourceName: 'unknown'})),
+      ).toThrow(/no resource named/i)
+    })
+
+    it('throws when both resource and resourceName are provided', () => {
+      expect(() =>
+        renderHook(() =>
+          useNormalizedResourceOptions({
+            resource: {projectId: 'p', dataset: 'd'},
+            resourceName: 'dataset',
+          }),
+        ),
+      ).toThrow()
+    })
+
+    it('resolves deprecated `source` as `resource`', () => {
+      const {result} = renderHook(() =>
+        useNormalizedResourceOptions({source: {projectId: 'src', dataset: 'src-ds'}}),
+      )
+      expect(result.current.resource).toEqual({projectId: 'src', dataset: 'src-ds'})
+    })
+
+    it('resolves deprecated `sourceName` as `resourceName`', () => {
+      const {result} = renderHook(() => useNormalizedResourceOptions({sourceName: 'dataset'}))
+      expect(result.current.resource).toEqual({
+        projectId: 'resource-project-id',
+        dataset: 'resource-dataset',
+      })
+    })
+  })
+
+  describe('tier 2 — bare projectId/dataset in options', () => {
+    it('synthesizes a resource from projectId + dataset', () => {
+      const {result} = renderHook(() =>
+        useNormalizedResourceOptions({projectId: 'opt', dataset: 'opt-ds'}),
+      )
+      expect(result.current.resource).toEqual({projectId: 'opt', dataset: 'opt-ds'})
+    })
+
+    it('falls through to context when only projectId is provided (no dataset)', () => {
+      // Only projectId is not enough to synthesize — should fall back to context resource
+      const {result} = renderHook(() => useNormalizedResourceOptions({projectId: 'opt'}))
+      // Default test-utils: ResourceProvider projectId="test" dataset="test" → tier-3 via config synthesis
+      expect(result.current.resource).toEqual({projectId: 'test', dataset: 'test'})
+    })
+  })
+
+  describe('tier 3 — ResourceContext', () => {
+    it('uses ResourceContext set via ResourceProvider `resource` prop', () => {
+      const contextResource = {projectId: 'ctx-project', dataset: 'ctx-dataset'}
+      const {result} = renderHook(() => useNormalizedResourceOptions({}), {
+        wrapper: ({children}) => (
+          <ResourceContextWrapper resource={contextResource}>{children}</ResourceContextWrapper>
+        ),
+      })
+      expect(result.current.resource).toEqual(contextResource)
+    })
+
+    it('uses ResourceContext synthesized from ResourceProvider projectId/dataset', () => {
+      // ResourceProvider with projectId/dataset (no explicit resource prop) synthesizes ResourceContext
+      const {result} = renderHook(() => useNormalizedResourceOptions({}))
+      // Default test-utils: ResourceProvider projectId="test" dataset="test"
+      expect(result.current.resource).toEqual({projectId: 'test', dataset: 'test'})
+    })
+
+    it('explicit resource in options takes precedence over ResourceContext', () => {
+      const {result} = renderHook(
+        () =>
+          useNormalizedResourceOptions({resource: {projectId: 'explicit', dataset: 'explicit-ds'}}),
+        {
+          wrapper: ({children}) => (
+            <ResourceContextWrapper resource={{projectId: 'ctx-project', dataset: 'ctx-dataset'}}>
+              {children}
+            </ResourceContextWrapper>
+          ),
+        },
+      )
+      expect(result.current.resource).toEqual({projectId: 'explicit', dataset: 'explicit-ds'})
+    })
+  })
+
+  describe('tier 4 — SanityInstance config fallback', () => {
+    it('falls back to instance projectId/dataset when ResourceContext is not set', () => {
+      // Bare SanityInstanceContext with config — no ResourceProvider, so no ResourceContext
+      const instanceWithConfig = createSanityInstance({projectId: 'inst', dataset: 'inst-ds'})
+      const {result} = renderHook(() => useNormalizedResourceOptions({}), {
+        wrapper: ({children}) => (
+          <SanityInstanceContext.Provider value={instanceWithConfig}>
+            {children}
+          </SanityInstanceContext.Provider>
+        ),
+      })
+      expect(result.current.resource).toEqual({projectId: 'inst', dataset: 'inst-ds'})
+    })
+  })
+
+  describe('tier 5 — no resource available', () => {
+    it('returns no resource when neither options, context, nor instance config provide one', () => {
+      const {result} = renderHook(() => useNormalizedResourceOptions({}), {
+        wrapper: NoResourceWrapper,
+      })
+      expect(result.current).not.toHaveProperty('resource')
+    })
+  })
+
+  describe('perspective resolution', () => {
+    it('uses explicit perspective from options', () => {
+      const {result} = renderHook(() => useNormalizedResourceOptions({perspective: 'published'}))
+      expect(result.current.perspective).toBe('published')
+    })
+
+    it('falls back to PerspectiveContext when no perspective in options', () => {
+      const {result} = renderHook(() => useNormalizedResourceOptions({}), {
+        wrapper: ({children}) => (
+          <ResourceProvider perspective="previewDrafts" fallback={null}>
+            {children}
+          </ResourceProvider>
+        ),
+      })
+      expect(result.current.perspective).toBe('previewDrafts')
+    })
+
+    it('explicit perspective overrides PerspectiveContext', () => {
+      const {result} = renderHook(() => useNormalizedResourceOptions({perspective: 'published'}), {
+        wrapper: ({children}) => (
+          <ResourceProvider perspective="previewDrafts" fallback={null}>
+            {children}
+          </ResourceProvider>
+        ),
+      })
+      expect(result.current.perspective).toBe('published')
+    })
+
+    it('omits perspective from result when not set', () => {
+      const {result} = renderHook(() => useNormalizedResourceOptions({}), {
+        wrapper: NoResourceWrapper,
+      })
+      expect(result.current).not.toHaveProperty('perspective')
+    })
+  })
+
+  describe('field stripping', () => {
+    it('strips resourceName from the result', () => {
+      const {result} = renderHook(() => useNormalizedResourceOptions({resourceName: 'dataset'}))
+      expect(result.current).not.toHaveProperty('resourceName')
+    })
+
+    it('strips projectId and dataset from the result when synthesized into resource', () => {
+      const {result} = renderHook(() =>
+        useNormalizedResourceOptions({projectId: 'p', dataset: 'd'}),
+      )
+      expect(result.current).not.toHaveProperty('projectId')
+      expect(result.current).not.toHaveProperty('dataset')
+    })
+
+    it('strips deprecated source from the result', () => {
+      const {result} = renderHook(() =>
+        useNormalizedResourceOptions({source: {projectId: 'src', dataset: 'src-ds'}}),
+      )
+      expect(result.current).not.toHaveProperty('source')
+    })
+
+    it('strips deprecated sourceName from the result', () => {
+      const {result} = renderHook(() => useNormalizedResourceOptions({sourceName: 'dataset'}))
+      expect(result.current).not.toHaveProperty('sourceName')
+    })
+
+    it('preserves unrelated fields', () => {
+      const opts: DocumentHandle = {documentId: 'doc-1', documentType: 'article'}
+      const {result} = renderHook(() => useNormalizedResourceOptions(opts))
+      expect(result.current).toMatchObject({documentId: 'doc-1', documentType: 'article'})
+    })
+  })
+})

package/src/hooks/helpers/useNormalizedResourceOptions.ts

@@ -1,44 +1,57 @@
 import {type DocumentResource, type PerspectiveHandle} from '@sanity/sdk'
-import {useContext} from 'react'
+import {useContext, useMemo} from 'react'
 
 import {ResourceContext} from '../../context/DefaultResourceContext'
 import {PerspectiveContext} from '../../context/PerspectiveContext'
 import {ResourcesContext} from '../../context/ResourcesContext'
+import {SanityInstanceContext} from '../../context/SanityInstanceContext'
+
+type NormalizedResourceFields = 'resourceName' | 'source' | 'sourceName' | 'projectId' | 'dataset'
 
 /**
- * You should generally prefer to use the React-layer handle types (ResourceHandle, DocumentHandle) from '\@sanity/sdk-react' instead.
- * This type is useful for non-handles (like document actions) that we still want to resolve resources for.
  * Adds React hook support (resourceName resolution) to core types.
- * @internal
+ * Prefer using the React-layer handle types (ResourceHandle, DocumentHandle)
+ * from `@sanity/sdk-react` — this wrapper is kept for cases where overloads
+ * don't fit (e.g. non-handle options objects).
+ *
+ * @typeParam T - The core type to extend (must have optional `resource` field)
+ * @beta
  */
-export type WithResourceNameSupport<T> = Omit<T, 'resource'> & {
-  resource?: DocumentResource
+export type WithResourceNameSupport<T extends {resource?: DocumentResource}> = T & {
   /**
    * Optional name of a resource to resolve from context.
    * If provided, will be resolved to a `DocumentResource` via `ResourcesContext`.
    * @beta
    */
   resourceName?: string
+  /**
+   * @deprecated Use `resourceName` instead.
+   * @beta
+   */
+  sourceName?: string
 }
 
 /**
  * Pure function that normalizes options by resolving `resourceName` to a `DocumentResource`
- * using the provided resources map, and injecting defaults from context when not provided.
- * Use this when options are only available at call time (e.g. inside a callback)
- * and you cannot call the {@link useNormalizedResourceOptions} hook.
+ * using the provided resources map. Use this when options are only available at call time
+ * (e.g. inside a callback) and you cannot call the {@link useNormalizedResourceOptions} hook.
  *
  * @typeParam T - The options type (must include optional resource field)
  * @param options - Options that may include `resourceName` and/or `resource`
  * @param resources - Map of resource names to DocumentResource (e.g. from ResourcesContext)
- * @param contextResource - Resource from context (injected by ResourceProvider)
- * @param contextPerspective - Perspective from context (injected by ResourceProvider)
- * @returns Normalized options with `resourceName` removed and defaults injected
+ * @param contextResource - Resource from context (from ResourceContext)
+ * @param contextPerspective - Perspective from context (from PerspectiveContext)
+ * @returns Normalized options with `resourceName` removed and `resource` resolved
  * @internal
  */
 export function normalizeResourceOptions<
   T extends {
     resource?: DocumentResource
     resourceName?: string
+    source?: DocumentResource
+    sourceName?: string
+    projectId?: string
+    dataset?: string
     perspective?: unknown
   },
 >(
@@ -46,70 +59,89 @@ export function normalizeResourceOptions<
   resources: Record<string, DocumentResource>,
   contextResource?: DocumentResource,
   contextPerspective?: PerspectiveHandle['perspective'],
-): Omit<T, 'resourceName' | 'resource'> & {resource: DocumentResource} {
-  const {resourceName, ...rest} = options
+): Omit<T, NormalizedResourceFields> {
+  const {resourceName, sourceName, source, projectId, dataset, ...rest} = options
+
+  // Coalesce deprecated aliases to their canonical equivalents
+  const effectiveResourceName = resourceName ?? sourceName
+  const effectiveResource = options.resource ?? source
 
-  if (resourceName && Object.hasOwn(options, 'resource')) {
+  if (effectiveResourceName && effectiveResource) {
     throw new Error(
-      `Resource name ${JSON.stringify(resourceName)} and resource ${JSON.stringify(options.resource)} cannot be used together.`,
+      `Resource name ${JSON.stringify(effectiveResourceName)} and resource ${JSON.stringify(effectiveResource)} cannot be used together.`,
     )
   }
 
-  let resolvedResource: DocumentResource | undefined = options.resource
+  let resolvedResource: DocumentResource | undefined
 
-  if (!resolvedResource && resourceName) {
-    if (!Object.hasOwn(resources, resourceName)) {
+  // Tier (a): explicit resource object or resourceName lookup
+  if (effectiveResource) {
+    resolvedResource = effectiveResource
+  } else if (effectiveResourceName) {
+    if (!Object.hasOwn(resources, effectiveResourceName)) {
       throw new Error(
-        `There's no resource named ${JSON.stringify(resourceName)} in context. ` +
-          'Register it via the resources prop on <SanityApp>.',
+        `There's no resource named ${JSON.stringify(effectiveResourceName)} in context. Please use <ResourceProvider>.`,
       )
     }
-    resolvedResource = resources[resourceName]
+    resolvedResource = resources[effectiveResourceName]
   }
 
-  if (!resolvedResource) {
-    resolvedResource = contextResource
+  // Tier (b): projectId or dataset in options → synthesize a resource
+  if (!resolvedResource && projectId && dataset) {
+    resolvedResource = {
+      projectId,
+      dataset,
+    }
   }
 
-  if (resolvedResource === undefined) {
-    throw new Error(
-      'A resource is required. Provide `resource`, `resourceName`, or ensure a default resource is available from context (e.g. via <ResourceProvider> or <SanityApp>).',
-    )
+  // Tier (c): fall back to whatever ResourceContext provides
+  if (!resolvedResource) {
+    resolvedResource = contextResource
   }
 
+  // Inject perspective from context when not explicitly provided in options
   const resolvedPerspective = Object.hasOwn(options, 'perspective')
     ? options.perspective
     : contextPerspective
 
   return {
     ...rest,
-    resource: resolvedResource,
+    ...(resolvedResource !== undefined && {resource: resolvedResource}),
     ...(resolvedPerspective !== undefined && {perspective: resolvedPerspective}),
-  } as Omit<T, 'resourceName' | 'resource'> & {resource: DocumentResource}
+  }
 }
 
 /**
- * Normalizes hook options by resolving `resourceName` to a `DocumentResource`
- * and injecting resource/perspective from context.
+ * Returns the effective context resource: the `ResourceContext` value if set,
+ * otherwise a resource synthesized from the current `SanityInstance` config
+ * (tier-d fallback — returns `undefined` for studio-style configs with no project).
  *
- * This hook ensures that options passed to core layer functions contain
- * the correct `resource` and `perspective` values, maintaining clean
- * separation between React and core layers.
- *
- * @typeParam T - The options type (must include optional resource field)
- * @param options - Hook options that may include `resourceName` and/or `resource`
- * @returns Normalized options with `resourceName` removed and defaults injected
+ * @internal
+ */
+export function useEffectiveContextResource(): DocumentResource | undefined {
+  const contextResource = useContext(ResourceContext)
+  const instance = useContext(SanityInstanceContext)
+  const {projectId, dataset} = instance?.config ?? {}
+
+  return useMemo(() => {
+    if (contextResource) return contextResource
+    if (projectId && dataset) return {projectId, dataset}
+    return undefined
+  }, [contextResource, projectId, dataset])
+}
+
+/**
+ * Normalizes hook options by resolving `resourceName` to a `DocumentResource`.
  *
- * @remarks
  * Resolution priority for resource:
- * 1. If both `resourceName` and `resource` are provided, throws an error
- * 2. If `resource` is provided, uses it directly
- * 3. If `resourceName` is provided, resolves it via `ResourcesContext`
- * 4. If neither is provided, injects the value from `ResourceContext`
+ * 1. Explicit `resource` or `resourceName` in options
+ * 2. Bare `projectId`/`dataset` pair in options → synthesized into a resource
+ * 3. `ResourceContext` value (set by `ResourceProvider` / `SDKProvider`)
+ * 4. Current `SanityInstance` config — falls back to `undefined` for studio configs
  *
  * Resolution priority for perspective:
- * 1. If `perspective` is explicitly provided in options, uses it
- * 2. Otherwise, injects the value from `PerspectiveContext`
+ * 1. Explicit `perspective` in options
+ * 2. `PerspectiveContext` value (set by `ResourceProvider`)
  *
  * @internal
  */
@@ -117,11 +149,21 @@ export function useNormalizedResourceOptions<
   T extends {
     resource?: DocumentResource
     resourceName?: string
-    perspective?: unknown
+    source?: DocumentResource
+    sourceName?: string
+    projectId?: string
+    dataset?: string
+    perspective?: PerspectiveHandle['perspective']
   },
->(options: T): Omit<T, 'resourceName' | 'resource'> & {resource: DocumentResource} {
+>(
+  options: T,
+): Omit<T, NormalizedResourceFields> & {
+  resource?: DocumentResource
+  perspective?: PerspectiveHandle['perspective']
+} {
   const resources = useContext(ResourcesContext)
-  const contextResource = useContext(ResourceContext)
+  const effectiveContextResource = useEffectiveContextResource()
   const contextPerspective = useContext(PerspectiveContext)
-  return normalizeResourceOptions(options, resources, contextResource, contextPerspective)
+
+  return normalizeResourceOptions(options, resources, effectiveContextResource, contextPerspective)
 }

package/src/hooks/helpers/useResolvedProjectId.test.tsx

@@ -0,0 +1,59 @@
+import {type DocumentResource} from '@sanity/sdk'
+import {renderHook} from '@testing-library/react'
+import {type ReactNode} from 'react'
+import {describe, expect, it} from 'vitest'
+
+import {ResourceContext} from '../../context/DefaultResourceContext'
+import {ProjectContext} from '../../context/ProjectContext'
+import {useResolvedProjectId} from './useResolvedProjectId'
+
+const datasetResource: DocumentResource = {projectId: 'resource-project', dataset: 'production'}
+
+describe('useResolvedProjectId', () => {
+  it('prefers an explicit projectId on the options', () => {
+    const {result} = renderHook(() => useResolvedProjectId({projectId: 'option-project'}), {
+      wrapper: ({children}: {children: ReactNode}) => (
+        <ResourceContext.Provider value={datasetResource}>
+          <ProjectContext.Provider value="context-project">{children}</ProjectContext.Provider>
+        </ResourceContext.Provider>
+      ),
+    })
+    expect(result.current).toBe('option-project')
+  })
+
+  it('falls back to the ambient project scope (ProjectContext) over the resource', () => {
+    const {result} = renderHook(() => useResolvedProjectId(), {
+      wrapper: ({children}: {children: ReactNode}) => (
+        <ResourceContext.Provider value={datasetResource}>
+          <ProjectContext.Provider value="context-project">{children}</ProjectContext.Provider>
+        </ResourceContext.Provider>
+      ),
+    })
+    expect(result.current).toBe('context-project')
+  })
+
+  it('falls back to the resolved resource projectId', () => {
+    const {result} = renderHook(() => useResolvedProjectId(), {
+      wrapper: ({children}: {children: ReactNode}) => (
+        <ResourceContext.Provider value={datasetResource}>{children}</ResourceContext.Provider>
+      ),
+    })
+    expect(result.current).toBe('resource-project')
+  })
+
+  it('ignores a non-dataset resource (e.g. media library)', () => {
+    const {result} = renderHook(() => useResolvedProjectId(), {
+      wrapper: ({children}: {children: ReactNode}) => (
+        <ResourceContext.Provider value={{mediaLibraryId: 'ml-id'}}>
+          {children}
+        </ResourceContext.Provider>
+      ),
+    })
+    expect(result.current).toBeUndefined()
+  })
+
+  it('returns undefined when nothing resolves', () => {
+    const {result} = renderHook(() => useResolvedProjectId())
+    expect(result.current).toBeUndefined()
+  })
+})

package/src/hooks/helpers/useResolvedProjectId.ts

@@ -0,0 +1,35 @@
+import {type DocumentResource, isDatasetResource} from '@sanity/sdk'
+import {useContext} from 'react'
+
+import {ProjectContext} from '../../context/ProjectContext'
+import {useNormalizedResourceOptions} from './useNormalizedResourceOptions'
+
+/**
+ * Resolves the effective `projectId` for project-scoped hooks (`useProject`,
+ * `useDatasets`, `useUsers`).
+ *
+ * Precedence:
+ * 1. an explicit `projectId` on the options
+ * 2. the ambient project scope (`ProjectContext`, e.g. a dataset-less
+ *    `<ResourceProvider projectId="…">`)
+ * 3. the resolved resource's projectId (`ResourceProvider`/`SDKProvider`)
+ *
+ * Returns `undefined` when none apply, letting callers fall back to core's
+ * `instance.config.projectId`.
+ *
+ * @internal
+ */
+export function useResolvedProjectId(options?: {
+  projectId?: string
+  dataset?: string
+  resource?: DocumentResource
+  resourceName?: string
+}): string | undefined {
+  const {resource} = useNormalizedResourceOptions(options ?? {})
+  const contextProjectId = useContext(ProjectContext)
+  return (
+    options?.projectId ??
+    contextProjectId ??
+    (resource && isDatasetResource(resource) ? resource.projectId : undefined)
+  )
+}

package/src/hooks/helpers/useTrackHookUsage.ts

@@ -0,0 +1,37 @@
+import {type SanityInstance} from '@sanity/sdk'
+import {trackHookMounted} from '@sanity/sdk/_internal'
+import {useRef} from 'react'
+
+import {useSanityInstance} from '../context/useSanityInstance'
+
+/**
+ * Tracks the first usage of a named hook per SDK session.
+ * If the telemetry manager hasn't initialized yet, the hook
+ * name is buffered and flushed when it becomes available.
+ *
+ * Uses a ref to ensure the tracking call only happens once per
+ * component mount, avoiding repeated WeakMap lookups on re-renders.
+ *
+ * Call at the top of any public hook whose adoption we want to measure.
+ *
+ * @internal
+ */
+export function useTrackHookUsage(hookName: string): void {
+  const instance = useSanityInstance()
+  const tracked = useRef<true | null>(null)
+  if (tracked.current === null) {
+    tracked.current = true
+    trackHookMounted(instance, hookName)
+  }
+}
+
+/**
+ * Non-hook variant for tracking hook usage when an instance is already
+ * available (avoids an extra `useSanityInstance` call in hooks that
+ * already have the instance).
+ *
+ * @internal
+ */
+export function trackHookUsage(instance: SanityInstance, hookName: string): void {
+  trackHookMounted(instance, hookName)
+}

package/src/hooks/installations/useInstallation.test-d.ts

@@ -0,0 +1,19 @@
+import {type Installation, type InstallationActiveConfig} from '@sanity/sdk'
+import {expectTypeOf, test} from 'vitest'
+
+import {type FetcherHookResult} from '../helpers/createFetcherHook'
+import {useInstallation} from './useInstallation'
+
+test('useInstallation — no include: the base installation', () => {
+  const result = useInstallation('inst_1')
+  expectTypeOf(result).toEqualTypeOf<FetcherHookResult<Installation<never>>>()
+  expectTypeOf<
+    Extract<keyof typeof result.data, 'activeConfig' | 'access' | 'interfaces'>
+  >().toEqualTypeOf<never>()
+})
+
+test('useInstallation — activeConfig include adds the config field', () => {
+  const result = useInstallation('inst_1', {include: ['activeConfig']})
+  expectTypeOf(result.data).toEqualTypeOf<Installation<'activeConfig'>>()
+  expectTypeOf(result.data.activeConfig).toEqualTypeOf<InstallationActiveConfig | null>()
+})

package/src/hooks/installations/useInstallation.ts

@@ -0,0 +1,22 @@
+import {type Installation, installation, type InstallationInclude} from '@sanity/sdk'
+
+import {createFetcherHook, type FetcherHookResult} from '../helpers/createFetcherHook'
+
+/**
+ * Returns a single installation by id.
+ *
+ * The hook suspends until the first fetch succeeds, so `data` is always present.
+ * The `include` tokens you pass shape `data`: each requested token adds its
+ * field, and omitted ones are absent from the type.
+ *
+ * @public
+ * @param installationId - The installation id.
+ * @param options - Optional `include` list to expand related resources.
+ * @returns The result envelope `{data, isFetching, error, refetch}`.
+ */
+export const useInstallation = createFetcherHook(installation) as <
+  Include extends InstallationInclude = never,
+>(
+  installationId: string,
+  options?: {include?: Include[]},
+) => FetcherHookResult<Installation<Include>>