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

package/src/hooks/applications/useUpdateApplication.test-d.ts

@@ -0,0 +1,12 @@
+import {type Application, type UpdateApplicationInput} from '@sanity/sdk'
+import {expectTypeOf, test} from 'vitest'
+
+import {type MutationHookResult} from '../helpers/createMutationHook'
+import {useUpdateApplication} from './useUpdateApplication'
+
+test('useUpdateApplication — returns the mutation envelope', () => {
+  const result = useUpdateApplication()
+  expectTypeOf(result).toEqualTypeOf<MutationHookResult<UpdateApplicationInput, Application>>()
+  expectTypeOf(result.mutate).parameter(0).toEqualTypeOf<UpdateApplicationInput>()
+  expectTypeOf(result.data).toEqualTypeOf<Application | undefined>()
+})

package/src/hooks/applications/useUpdateApplication.ts

@@ -0,0 +1,11 @@
+import {updateApplication} from '@sanity/sdk'
+
+import {createMutationHook} from '../helpers/createMutationHook'
+
+/**
+ * Updates an application's mutable properties (title, icon, visibility).
+ *
+ * @internal
+ * @returns The mutation envelope `{mutate, isPending, error, data, reset}`.
+ */
+export const useUpdateApplication = createMutationHook(updateApplication)

package/src/hooks/applications/useUpdateUserApplication.test-d.ts

@@ -0,0 +1,14 @@
+import {type UpdateUserApplicationInput, type UserApplication} from '@sanity/sdk'
+import {expectTypeOf, test} from 'vitest'
+
+import {type MutationHookResult} from '../helpers/createMutationHook'
+import {useUpdateUserApplication} from './useUpdateUserApplication'
+
+test('useUpdateUserApplication — returns the mutation envelope', () => {
+  const result = useUpdateUserApplication()
+  expectTypeOf(result).toEqualTypeOf<
+    MutationHookResult<UpdateUserApplicationInput, UserApplication>
+  >()
+  expectTypeOf(result.mutate).parameter(0).toEqualTypeOf<UpdateUserApplicationInput>()
+  expectTypeOf(result.data).toEqualTypeOf<UserApplication | undefined>()
+})

package/src/hooks/applications/useUpdateUserApplication.ts

@@ -0,0 +1,11 @@
+import {updateUserApplication} from '@sanity/sdk'
+
+import {createMutationHook} from '../helpers/createMutationHook'
+
+/**
+ * Updates a user application.
+ *
+ * @internal
+ * @returns The mutation envelope `{mutate, isPending, error, data, reset}`.
+ */
+export const useUpdateUserApplication = createMutationHook(updateUserApplication)

package/src/hooks/applications/useUserApplication.test-d.ts

@@ -0,0 +1,11 @@
+import {type UserApplication} from '@sanity/sdk'
+import {expectTypeOf, test} from 'vitest'
+
+import {type FetcherHookResult} from '../helpers/createFetcherHook'
+import {useUserApplication} from './useUserApplication'
+
+test('useUserApplication — returns a single user application in the result envelope', () => {
+  const result = useUserApplication('user_app_1')
+  expectTypeOf(result).toEqualTypeOf<FetcherHookResult<UserApplication>>()
+  expectTypeOf(result.data).toEqualTypeOf<UserApplication>()
+})

package/src/hooks/applications/useUserApplication.ts

@@ -0,0 +1,14 @@
+import {userApplication} from '@sanity/sdk'
+
+import {createFetcherHook} from '../helpers/createFetcherHook'
+
+/**
+ * Returns a single user application by id.
+ *
+ * The hook suspends until the first fetch succeeds, so `data` is always present.
+ *
+ * @public
+ * @param userApplicationId - The user application id.
+ * @returns The result envelope `{data, isFetching, error, refetch}`.
+ */
+export const useUserApplication = createFetcherHook(userApplication)

package/src/hooks/applications/useUserApplications.test-d.ts

@@ -0,0 +1,11 @@
+import {type UserApplication} from '@sanity/sdk'
+import {expectTypeOf, test} from 'vitest'
+
+import {type FetcherHookResult} from '../helpers/createFetcherHook'
+import {useUserApplications} from './useUserApplications'
+
+test('useUserApplications — returns the user applications in the result envelope', () => {
+  const result = useUserApplications({organizationId: 'org_1'})
+  expectTypeOf(result).toEqualTypeOf<FetcherHookResult<UserApplication[]>>()
+  expectTypeOf(result.data).toEqualTypeOf<UserApplication[]>()
+})

package/src/hooks/applications/useUserApplications.ts

@@ -0,0 +1,14 @@
+import {userApplications} from '@sanity/sdk'
+
+import {createFetcherHook} from '../helpers/createFetcherHook'
+
+/**
+ * Returns the current user's applications for the given organisation.
+ *
+ * The hook suspends until the first fetch succeeds, so `data` is always present.
+ *
+ * @public
+ * @param options - Options identifying the organisation.
+ * @returns The result envelope `{data, isFetching, error, refetch}`.
+ */
+export const useUserApplications = createFetcherHook(userApplications)

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

@@ -0,0 +1,180 @@
+import {createSanityInstance} from '@sanity/sdk'
+import {defineFetcher, type Fetcher, type FetcherSnapshot} from '@sanity/sdk/_internal'
+import {renderHook} from '@testing-library/react'
+import {of, throwError} from 'rxjs'
+import {beforeEach, describe, expect, it, vi} from 'vitest'
+
+import {useSanityInstance} from '../context/useSanityInstance'
+import {createFetcherHook} from './createFetcherHook'
+
+vi.mock('../context/useSanityInstance', () => ({
+  useSanityInstance: vi.fn(),
+}))
+
+const instance = createSanityInstance({projectId: 'p', dataset: 'd'})
+
+const makeFetcher = (snapshot: FetcherSnapshot<string>): Fetcher<[id: string], string> => {
+  const fetcher = {
+    getState: vi.fn(() => ({
+      subscribe: vi.fn(() => () => {}),
+      getCurrent: () => snapshot,
+      observable: throwError(() => new Error('unexpected usage of observable')),
+    })),
+    resolveState: vi.fn(() => Promise.resolve('resolved')),
+    refetch: vi.fn(() => Promise.resolve('refetched')),
+    invalidate: vi.fn(),
+    invalidateAll: vi.fn(),
+    setData: vi.fn(() => ({undo: vi.fn()})),
+  }
+  return fetcher as unknown as Fetcher<[id: string], string>
+}
+
+const success: FetcherSnapshot<string> = {
+  status: 'success',
+  data: 'DATA',
+  error: undefined,
+  isFetching: false,
+  dataUpdatedAt: 1,
+}
+
+describe('createFetcherHook', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    vi.mocked(useSanityInstance).mockReturnValue(instance)
+  })
+
+  it('returns {data, isFetching, error, refetch} from a success snapshot', () => {
+    const fetcher = makeFetcher(success)
+    const useThing = createFetcherHook(fetcher)
+    const {result} = renderHook(() => useThing('a'))
+
+    expect(result.current.data).toBe('DATA')
+    expect(result.current.isFetching).toBe(false)
+    expect(result.current.error).toBeUndefined()
+    expect(typeof result.current.refetch).toBe('function')
+  })
+
+  it('surfaces isFetching and the background error on the success arm', () => {
+    const boom = new Error('background')
+    const fetcher = makeFetcher({...success, isFetching: true, error: boom})
+    const useThing = createFetcherHook(fetcher)
+    const {result} = renderHook(() => useThing('a'))
+
+    expect(result.current.isFetching).toBe(true)
+    expect(result.current.error).toBe(boom)
+  })
+
+  it('refetch() calls the fetcher with the instance and params', () => {
+    const fetcher = makeFetcher(success)
+    const useThing = createFetcherHook(fetcher)
+    const {result} = renderHook(() => useThing('a'))
+
+    const returned = result.current.refetch()
+
+    expect(fetcher.refetch).toHaveBeenCalledWith(instance, 'a')
+    expect(returned).toBeInstanceOf(Promise)
+  })
+
+  it('suspends on a pending snapshot by throwing resolveState', () => {
+    const fetcher = makeFetcher({
+      status: 'pending',
+      data: undefined,
+      error: undefined,
+      isFetching: true,
+      dataUpdatedAt: undefined,
+    })
+    const useThing = createFetcherHook(fetcher)
+    const {result} = renderHook(() => {
+      try {
+        return useThing('a')
+      } catch (thrown) {
+        return thrown
+      }
+    })
+
+    expect(fetcher.resolveState).toHaveBeenCalledWith(instance, 'a')
+    expect(result.current).toBe(vi.mocked(fetcher.resolveState).mock.results[0]!.value)
+  })
+
+  it('throws the error arm to the error boundary', () => {
+    const boom = new Error('fatal')
+    const fetcher = makeFetcher({
+      status: 'error',
+      data: undefined,
+      error: boom,
+      isFetching: false,
+      dataUpdatedAt: undefined,
+    })
+    const useThing = createFetcherHook(fetcher)
+    const {result} = renderHook(() => {
+      try {
+        return useThing('a')
+      } catch (thrown) {
+        return thrown
+      }
+    })
+
+    expect(result.current).toBe(boom)
+  })
+
+  // Regression: the mocked fetcher above can never reproduce the real bug — its
+  // `getCurrent` returns a fixed snapshot object. A real fetcher store replaces
+  // the cache entry on every (un)subscribe, so `getCurrent` yields a new snapshot
+  // reference each time. Feeding that straight through `useSyncExternalStore`
+  // makes React see the store "change" on every commit and re-render forever
+  // ("Maximum update depth exceeded", React #185).
+  it('does not re-render forever over a real fetcher store (SDK-1448)', () => {
+    const fetcher = defineFetcher<[id: string], string>({
+      name: `regression-loop-${Math.random().toString(36).slice(2)}`,
+      getKey: (_instance, id) => id,
+      fetch: () => (id) => of(`DATA:${id}`),
+    })
+    // Seed a success entry so we skip Suspense and land in useSyncExternalStore.
+    fetcher.setData(instance, ['a'], 'DATA:a')
+
+    const useThing = createFetcherHook(fetcher)
+
+    let renders = 0
+    const {result} = renderHook(() => {
+      renders += 1
+      if (renders > 25) throw new Error(`infinite render loop: ${renders} renders`)
+      return useThing('a')
+    })
+
+    expect(result.current.data).toBe('DATA:a')
+    expect(renders).toBeLessThan(25)
+  })
+
+  // The realistic case: `data` is an object, not a primitive. The store hands
+  // back a fresh snapshot object on every (un)subscribe, so the dedup must keep
+  // returning the *same* `data` reference while the entry is unchanged —
+  // otherwise consumers that key off `data` identity (memo deps, effects)
+  // re-render on every commit even though nothing changed. This is the property
+  // the snapshot-equality check guards.
+  it('keeps a stable object data reference across re-renders (SDK-1448)', () => {
+    const data = {id: 'a', title: 'Thing', tags: ['x', 'y']}
+    const fetcher = defineFetcher<[id: string], typeof data>({
+      name: `regression-object-${Math.random().toString(36).slice(2)}`,
+      getKey: (_instance, id) => id,
+      fetch: () => () => of(data),
+    })
+    fetcher.setData(instance, ['a'], data)
+
+    const useThing = createFetcherHook(fetcher)
+
+    let renders = 0
+    const seen: unknown[] = []
+    const {result} = renderHook(() => {
+      renders += 1
+      if (renders > 25) throw new Error(`infinite render loop: ${renders} renders`)
+      const value = useThing('a')
+      seen.push(value.data)
+      return value
+    })
+
+    expect(result.current.data).toBe(data)
+    expect(renders).toBeLessThan(25)
+    // Every commit observed the identical object — no churn from fresh snapshots.
+    expect(seen.every((d) => d === data)).toBe(true)
+  })
+})

package/src/hooks/helpers/createFetcherHook.ts

@@ -0,0 +1,69 @@
+import {type Fetcher, type FetcherSnapshot, isDeepEqual} from '@sanity/sdk/_internal'
+import {useRef, useSyncExternalStore} from 'react'
+
+import {useSanityInstance} from '../context/useSanityInstance'
+
+/**
+ * The value returned by a fetcher-backed hook. The hook suspends until the
+ * first fetch succeeds, so `data` is always present once your component renders.
+ *
+ * @public
+ */
+export interface FetcherHookResult<TData> {
+  /** The resolved data. Guaranteed present — the hook suspends until the first fetch succeeds. */
+  data: TData
+  /** A fetch for this entry is in flight (background revalidation or a `refetch()`). */
+  isFetching: boolean
+  /** The most recent background-fetch failure while data still renders; cleared by the next success. */
+  error: unknown
+  /** Imperatively refetch, bypassing staleness. Resolves with the refreshed data. */
+  refetch: () => Promise<TData>
+}
+
+/**
+ * Builds a Suspense hook over a {@link Fetcher}: it suspends until the first
+ * success via the snapshot's `status`, throws the error arm to the nearest error
+ * boundary, and returns the live `{data, isFetching, error, refetch}` envelope.
+ *
+ * @internal
+ */
+export function createFetcherHook<TParams extends unknown[], TData>(
+  fetcher: Fetcher<TParams, TData>,
+): (...params: TParams) => FetcherHookResult<TData> {
+  return function useFetcherHook(...params: TParams): FetcherHookResult<TData> {
+    const instance = useSanityInstance()
+    const source = fetcher.getState(instance, ...params)
+
+    // No entry/data yet — suspend on the first fetch (matches an 'error' below never reaching here).
+    if (source.getCurrent().status === 'pending') {
+      throw fetcher.resolveState(instance, ...params)
+    }
+
+    // The store replaces its cache entry on every (un)subscribe (it bumps a
+    // subscription counter), so `getCurrent()` hands back a fresh snapshot object
+    // with identical fields on each commit. Passed raw to `useSyncExternalStore`
+    // — which compares by `Object.is` — that reads as a perpetual change and
+    // re-renders forever. Reuse the previous snapshot while its fields are
+    // unchanged so React sees a stable reference.
+    const previous = useRef<FetcherSnapshot<TData> | null>(null)
+    const snapshot = useSyncExternalStore(source.subscribe, () => {
+      const next = source.getCurrent()
+      const prev = previous.current
+      if (prev && isDeepEqual(prev, next)) return prev
+      previous.current = next
+      return next
+    })
+
+    if (snapshot.status !== 'success') {
+      // 'pending' already suspended above; 'error' surfaces to the error boundary.
+      throw snapshot.status === 'error' ? snapshot.error : fetcher.resolveState(instance, ...params)
+    }
+
+    return {
+      data: snapshot.data,
+      isFetching: snapshot.isFetching,
+      error: snapshot.error,
+      refetch: () => fetcher.refetch(instance, ...params),
+    }
+  }
+}

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

@@ -0,0 +1,125 @@
+import {createSanityInstance} from '@sanity/sdk'
+import {type MutationResult} from '@sanity/sdk/_internal'
+import {act, renderHook} from '@testing-library/react'
+import {beforeEach, describe, expect, it, vi} from 'vitest'
+
+import {useSanityInstance} from '../context/useSanityInstance'
+import {createMutationHook} from './createMutationHook'
+
+vi.mock('../context/useSanityInstance', () => ({
+  useSanityInstance: vi.fn(),
+}))
+
+const instance = createSanityInstance({projectId: 'p', dataset: 'd'})
+
+const settled = <T,>(data: T): MutationResult<T> => ({data, invalidated: Promise.resolve()})
+
+describe('createMutationHook', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    vi.mocked(useSanityInstance).mockReturnValue(instance)
+  })
+
+  it('starts idle', () => {
+    const useThing = createMutationHook(vi.fn())
+    const {result} = renderHook(() => useThing())
+
+    expect(result.current.isPending).toBe(false)
+    expect(result.current.data).toBeUndefined()
+    expect(result.current.error).toBeUndefined()
+  })
+
+  it('calls the mutation with the instance and resolves with the server data', async () => {
+    const mutation = vi.fn((_instance, input: string) =>
+      Promise.resolve(settled(`created:${input}`)),
+    )
+    const useThing = createMutationHook(mutation)
+    const {result} = renderHook(() => useThing())
+
+    let resolved: string | undefined
+    await act(async () => {
+      resolved = await result.current.mutate('a')
+    })
+
+    expect(mutation).toHaveBeenCalledWith(instance, 'a')
+    expect(resolved).toBe('created:a')
+    expect(result.current.data).toBe('created:a')
+    expect(result.current.error).toBeUndefined()
+    expect(result.current.isPending).toBe(false)
+  })
+
+  it('reports isPending while the mutation is in flight', async () => {
+    let release!: (value: MutationResult<string>) => void
+    const mutation = vi.fn(
+      () => new Promise<MutationResult<string>>((resolve) => (release = resolve)),
+    )
+    const useThing = createMutationHook(mutation)
+    const {result} = renderHook(() => useThing())
+
+    act(() => {
+      void result.current.mutate('a')
+    })
+    expect(result.current.isPending).toBe(true)
+
+    await act(async () => {
+      release(settled('done'))
+    })
+    expect(result.current.isPending).toBe(false)
+    expect(result.current.data).toBe('done')
+  })
+
+  it('rejects on failure and captures the error in state', async () => {
+    const boom = new Error('nope')
+    const mutation = vi.fn(() => Promise.reject(boom))
+    const useThing = createMutationHook(mutation)
+    const {result} = renderHook(() => useThing())
+
+    await act(async () => {
+      await expect(result.current.mutate('a')).rejects.toBe(boom)
+    })
+
+    expect(result.current.error).toBe(boom)
+    expect(result.current.data).toBeUndefined()
+    expect(result.current.isPending).toBe(false)
+  })
+
+  it('reset() returns to idle', async () => {
+    const mutation = vi.fn((_instance, input: string) => Promise.resolve(settled(input)))
+    const useThing = createMutationHook(mutation)
+    const {result} = renderHook(() => useThing())
+
+    await act(async () => {
+      await result.current.mutate('a')
+    })
+    expect(result.current.data).toBe('a')
+
+    act(() => result.current.reset())
+    expect(result.current.data).toBeUndefined()
+    expect(result.current.error).toBeUndefined()
+    expect(result.current.isPending).toBe(false)
+  })
+
+  it('only the latest call writes state, so a stale call cannot clobber it', async () => {
+    const releases: Array<(value: MutationResult<string>) => void> = []
+    const mutation = vi.fn(
+      () => new Promise<MutationResult<string>>((resolve) => releases.push(resolve)),
+    )
+    const useThing = createMutationHook(mutation)
+    const {result} = renderHook(() => useThing())
+
+    let first!: Promise<string>
+    let second!: Promise<string>
+    act(() => {
+      first = result.current.mutate('first')
+      second = result.current.mutate('second')
+    })
+
+    await act(async () => {
+      releases[1]!(settled('second-result')) // latest resolves first
+      releases[0]!(settled('first-result')) // stale resolves after
+      await Promise.all([first, second])
+    })
+
+    expect(result.current.data).toBe('second-result')
+  })
+})

package/src/hooks/helpers/createMutationHook.tsx

@@ -0,0 +1,93 @@
+import {type SanityInstance} from '@sanity/sdk'
+import {type MutationResult} from '@sanity/sdk/_internal'
+import {useCallback, useRef, useState} from 'react'
+
+import {useSanityInstance} from '../context/useSanityInstance'
+
+/**
+ * The value returned by a mutation-backed hook. The write-side counterpart to
+ * {@link FetcherHookResult}: local `{mutate, isPending, error, data, reset}`
+ * state around a core mutation action.
+ *
+ * @public
+ */
+export interface MutationHookResult<TInput, TResult> {
+  /**
+   * Runs the mutation. Resolves with the server response; rejects on failure
+   * (the failure is also captured in {@link MutationHookResult.error}, so a
+   * fire-and-forget caller should read `error` and an `await`ing caller should
+   * `try`/`catch`).
+   */
+  mutate: (input: TInput) => Promise<TResult>
+  /** A mutation is currently in flight. */
+  isPending: boolean
+  /** The most recent failure; cleared by the next `mutate` or `reset`. */
+  error: unknown
+  /** The last successful server response, or `undefined` before the first success. */
+  data: TResult | undefined
+  /** Clears state back to idle and abandons any in-flight result. */
+  reset: () => void
+}
+
+type MutationState<TResult> =
+  | {status: 'idle'; data: undefined; error: undefined}
+  | {status: 'pending'; data: TResult | undefined; error: undefined}
+  | {status: 'success'; data: TResult; error: undefined}
+  | {status: 'error'; data: TResult | undefined; error: unknown}
+
+/**
+ * Builds a hook over a core mutation action (the result of `defineMutation`).
+ * The write-side counterpart to {@link createFetcherHook}: it binds the action
+ * to the current {@link SanityInstance} and tracks `{isPending, error, data}`
+ * locally. `mutate` resolves with the server response only — the mutation's
+ * `invalidated` promise is intentionally not exposed, since cache
+ * reconciliation is handled by the fetcher stores.
+ *
+ * @internal
+ */
+export function createMutationHook<TInput, TResult>(
+  mutation: (instance: SanityInstance, input: TInput) => Promise<MutationResult<TResult>>,
+): () => MutationHookResult<TInput, TResult> {
+  const idle: MutationState<TResult> = {status: 'idle', data: undefined, error: undefined}
+
+  return function useMutationHook(): MutationHookResult<TInput, TResult> {
+    const instance = useSanityInstance()
+    const [state, setState] = useState<MutationState<TResult>>(idle)
+    // Increments per call; only the latest call is allowed to write state, so an
+    // earlier in-flight mutation can't clobber a later one (or a `reset`).
+    const callId = useRef(0)
+
+    const mutate = useCallback(
+      (input: TInput): Promise<TResult> => {
+        const id = ++callId.current
+        setState((prev) => ({status: 'pending', data: prev.data, error: undefined}))
+        return mutation(instance, input).then(
+          ({data}) => {
+            if (id === callId.current) setState({status: 'success', data, error: undefined})
+            return data
+          },
+          (error: unknown) => {
+            if (id === callId.current) {
+              setState((prev) => ({status: 'error', data: prev.data, error}))
+            }
+            throw error
+          },
+        )
+      },
+      [instance],
+    )
+
+    const reset = useCallback(() => {
+      callId.current++ // abandon any in-flight response so it can't revive stale state
+      setState(idle)
+    }, [])
+
+    return {
+      mutate,
+      isPending: state.status === 'pending',
+      error: state.error,
+      data: state.data,
+      reset,
+    }
+  }
+}

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>>

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

@@ -0,0 +1,26 @@
+import {type Installation, type InstallationAccess, type InstallationsResponse} from '@sanity/sdk'
+import {expectTypeOf, test} from 'vitest'
+
+import {type FetcherHookResult} from '../helpers/createFetcherHook'
+import {useInstallations} from './useInstallations'
+
+test('useInstallations — no include: base items, no gated fields', () => {
+  const result = useInstallations({organizationId: 'org_1'})
+  expectTypeOf(result).toEqualTypeOf<FetcherHookResult<InstallationsResponse<never>>>()
+  type Item = (typeof result.data.data)[number]
+  expectTypeOf<
+    Extract<keyof Item, 'activeConfig' | 'access' | 'interfaces'>
+  >().toEqualTypeOf<never>()
+})
+
+test('useInstallations — include shapes each item', () => {
+  const result = useInstallations({organizationId: 'org_1', include: ['access']})
+  expectTypeOf(result.data.data).toEqualTypeOf<Installation<'access'>[]>()
+  type Item = (typeof result.data.data)[number]
+  expectTypeOf<Item['access']>().toEqualTypeOf<InstallationAccess[]>()
+})
+
+test('useInstallations — requires an organizationId', () => {
+  // @ts-expect-error — organizationId is required
+  void useInstallations({})
+})

package/src/hooks/installations/useInstallations.ts

@@ -0,0 +1,25 @@
+import {
+  type InstallationInclude,
+  installations,
+  type InstallationsOptions,
+  type InstallationsResponse,
+} from '@sanity/sdk'
+
+import {createFetcherHook, type FetcherHookResult} from '../helpers/createFetcherHook'
+
+/**
+ * Returns the installations matching the given options.
+ *
+ * The hook suspends until the first fetch succeeds, so `data` is always present.
+ * The `include` tokens you pass shape `data.data`: each requested token adds its
+ * field, and omitted ones are absent from the type.
+ *
+ * @public
+ * @param options - Filter and include options for the installations list.
+ * @returns The result envelope `{data, isFetching, error, refetch}`.
+ */
+export const useInstallations = createFetcherHook(installations) as <
+  Include extends InstallationInclude = never,
+>(
+  options: InstallationsOptions<Include>,
+) => FetcherHookResult<InstallationsResponse<Include>>