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

package/src/hooks/helpers/useNormalizedResourceOptions.ts

@@ -1,18 +1,23 @@
 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' | '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`.
@@ -23,22 +28,23 @@ export type WithResourceNameSupport<T> = Omit<T, 'resource'> & {
 
 /**
  * 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
+    projectId?: string
+    dataset?: string
     perspective?: unknown
   },
 >(
@@ -46,70 +52,87 @@ 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, projectId, dataset, ...rest} = options
+  const resource = options.resource
 
-  if (resourceName && Object.hasOwn(options, 'resource')) {
+  if (resourceName && resource) {
     throw new Error(
-      `Resource name ${JSON.stringify(resourceName)} and resource ${JSON.stringify(options.resource)} cannot be used together.`,
+      `Resource name ${JSON.stringify(resourceName)} and resource ${JSON.stringify(resource)} cannot be used together.`,
     )
   }
 
-  let resolvedResource: DocumentResource | undefined = options.resource
+  let resolvedResource: DocumentResource | undefined
 
-  if (!resolvedResource && resourceName) {
+  // Tier (a): explicit resource object or resourceName lookup
+  if (resource) {
+    resolvedResource = resource
+  } else if (resourceName) {
     if (!Object.hasOwn(resources, resourceName)) {
       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(resourceName)} in context. Please use <ResourceProvider>.`,
       )
     }
     resolvedResource = resources[resourceName]
   }
 
-  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.
- *
- * 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.
+ * 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).
  *
- * @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, resource: configResource} = instance?.config ?? {}
+
+  return useMemo(() => {
+    if (contextResource) return contextResource
+    if (configResource) return configResource
+    if (projectId && dataset) return {projectId, dataset}
+    return undefined
+  }, [contextResource, configResource, 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 +140,19 @@ export function useNormalizedResourceOptions<
   T extends {
     resource?: DocumentResource
     resourceName?: string
-    perspective?: unknown
+    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>>

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

package/src/hooks/organizations/useOrganization.test-d.ts

@@ -0,0 +1,60 @@
+import {type Organization, type OrganizationMember} from '@sanity/sdk'
+import {expectTypeOf, test} from 'vitest'
+
+import {useOrganization} from './useOrganization'
+
+test('useOrganization — no flags: members and features both omitted', () => {
+  expectTypeOf(useOrganization({organizationId: 'org_1'}).data).toEqualTypeOf<
+    Organization<false, false>
+  >()
+})
+
+test('useOrganization — returns the FetcherHookResult envelope', () => {
+  const result = useOrganization({organizationId: 'org_1'})
+  expectTypeOf(result.isFetching).toEqualTypeOf<boolean>()
+  expectTypeOf(result.error).toEqualTypeOf<unknown>()
+  expectTypeOf(result.refetch).toEqualTypeOf<() => Promise<Organization<false, false>>>()
+})
+
+test('useOrganization — includeMembers: true adds members to the type', () => {
+  expectTypeOf(useOrganization({organizationId: 'org_1', includeMembers: true}).data).toEqualTypeOf<
+    Organization<true, false>
+  >()
+  type Result = ReturnType<typeof useOrganization<true, false>>
+  expectTypeOf<Result['data']['members']>().toEqualTypeOf<OrganizationMember[]>()
+})
+
+test('useOrganization — includeFeatures: true adds features to the type', () => {
+  expectTypeOf(
+    useOrganization({organizationId: 'org_1', includeFeatures: true}).data,
+  ).toEqualTypeOf<Organization<false, true>>()
+})
+
+test('useOrganization — both flags true → both arrays present', () => {
+  expectTypeOf(
+    useOrganization({organizationId: 'org_1', includeMembers: true, includeFeatures: true}).data,
+  ).toEqualTypeOf<Organization<true, true>>()
+})
+
+test('useOrganization — both flags false → bare base shape', () => {
+  expectTypeOf(
+    useOrganization({organizationId: 'org_1', includeMembers: false, includeFeatures: false}).data,
+  ).toEqualTypeOf<Organization<false, false>>()
+  type Result = ReturnType<typeof useOrganization<false, false>>
+  expectTypeOf<Result['data']['id']>().toEqualTypeOf<string>()
+})
+
+test('useOrganization — rejects non-boolean flag values', () => {
+  // @ts-expect-error — includeMembers must be a boolean
+  void useOrganization({organizationId: 'org_1', includeMembers: 'yes'})
+})
+
+test('useOrganization — non-literal boolean flag makes members optional', () => {
+  const includeMembers = false as boolean
+  expectTypeOf(useOrganization({organizationId: 'org_1', includeMembers}).data).toEqualTypeOf<
+    Organization<boolean, false>
+  >()
+  type Result = ReturnType<typeof useOrganization<boolean, false>>
+  expectTypeOf<Result['data']['members']>().toEqualTypeOf<OrganizationMember[] | undefined>()
+  expectTypeOf<Pick<Result['data'], 'members'>>().toEqualTypeOf<{members?: OrganizationMember[]}>()
+})

package/src/hooks/organizations/useOrganization.test.ts

@@ -0,0 +1,63 @@
+import {type Organization, organization, type StateSource} from '@sanity/sdk'
+import {type FetcherSnapshot} from '@sanity/sdk/_internal'
+import {type Observable} from 'rxjs'
+import {beforeEach, describe, expect, it, vi} from 'vitest'
+
+import {renderHook} from '../../../test/test-utils'
+import {useOrganization} from './useOrganization'
+
+vi.mock('@sanity/sdk', async (importOriginal) => {
+  const original = await importOriginal<typeof import('@sanity/sdk')>()
+  return {...original, organization: {getState: vi.fn(), resolveState: vi.fn(), refetch: vi.fn()}}
+})
+
+const stateSource = (
+  current: Organization | undefined,
+): StateSource<FetcherSnapshot<Organization>> => {
+  const snapshot = current
+    ? {status: 'success', data: current, error: undefined, isFetching: false, dataUpdatedAt: 1}
+    : {
+        status: 'pending',
+        data: undefined,
+        error: undefined,
+        isFetching: true,
+        dataUpdatedAt: undefined,
+      }
+  return {
+    getCurrent: vi.fn(() => snapshot),
+    subscribe: vi.fn(() => () => {}),
+    get observable(): Observable<unknown> {
+      throw new Error('Not implemented')
+    },
+  } as unknown as StateSource<FetcherSnapshot<Organization>>
+}
+
+const sanityInstance = expect.objectContaining({config: expect.any(Object)})
+
+describe('useOrganization', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    vi.mocked(organization.getState).mockReturnValue(
+      stateSource({id: 'org_1'} as unknown as Organization),
+    )
+  })
+
+  it('reads the organization fetcher with the passed options', () => {
+    renderHook(() => useOrganization({organizationId: 'org_1'}))
+    expect(organization.getState).toHaveBeenCalledWith(sanityInstance, {organizationId: 'org_1'})
+  })
+
+  it('returns the fetcher data in the result envelope', () => {
+    const {result} = renderHook(() => useOrganization({organizationId: 'org_1'}))
+    expect(result.current.data).toEqual({id: 'org_1'})
+    expect(result.current.isFetching).toBe(false)
+    expect(typeof result.current.refetch).toBe('function')
+  })
+
+  it('suspends via the organization fetcher until data is available', () => {
+    vi.mocked(organization.getState).mockReturnValue(stateSource(undefined))
+    vi.mocked(organization.resolveState).mockReturnValue(new Promise(() => {}))
+    renderHook(() => useOrganization({organizationId: 'org_1'}))
+    expect(organization.resolveState).toHaveBeenCalled()
+  })
+})

package/src/hooks/organizations/useOrganization.ts

@@ -0,0 +1,34 @@
+import {type Organization, organization, type OrganizationOptions} from '@sanity/sdk'
+
+import {createFetcherHook, type FetcherHookResult} from '../helpers/createFetcherHook'
+
+/**
+ * Returns metadata for a given organisation.
+ *
+ * @category Organizations
+ * @param options - Configuration options
+ * @returns A {@link FetcherHookResult} whose `data` is the metadata for the
+ *   organisation. `members` is included only when `includeMembers: true`;
+ *   `features` is included only when `includeFeatures: true`.
+ * @example
+ * ```tsx
+ * function OrganizationName({organizationId}: {organizationId: string}) {
+ *   const {data: organization} = useOrganization({organizationId})
+ *
+ *   return <h1>{organization.name}</h1>
+ * }
+ * ```
+ * @example
+ * ```tsx
+ * const {data: organizationWithMembers} = useOrganization({organizationId, includeMembers: true})
+ * const {data: organizationWithFeatures} = useOrganization({organizationId, includeFeatures: true})
+ * ```
+ * @public
+ * @function
+ */
+export const useOrganization = createFetcherHook(organization) as <
+  IncludeMembers extends boolean = false,
+  IncludeFeatures extends boolean = false,
+>(
+  options: OrganizationOptions<IncludeMembers, IncludeFeatures>,
+) => FetcherHookResult<Organization<IncludeMembers, IncludeFeatures>>

package/src/hooks/organizations/useOrganizations.test-d.ts

@@ -0,0 +1,68 @@
+import {type OrganizationMember, type Organizations} from '@sanity/sdk'
+import {expectTypeOf, test} from 'vitest'
+
+import {useOrganizations} from './useOrganizations'
+
+test('useOrganizations — no args: members and features both omitted', () => {
+  expectTypeOf(useOrganizations().data).toEqualTypeOf<Organizations<false, false>>()
+})
+
+test('useOrganizations — returns the FetcherHookResult envelope', () => {
+  const result = useOrganizations()
+  expectTypeOf(result.isFetching).toEqualTypeOf<boolean>()
+  expectTypeOf(result.error).toEqualTypeOf<unknown>()
+  expectTypeOf(result.refetch).toEqualTypeOf<() => Promise<Organizations<false, false>>>()
+})
+
+test('useOrganizations — includeMembers: true adds members to the type', () => {
+  expectTypeOf(useOrganizations({includeMembers: true}).data).toEqualTypeOf<
+    Organizations<true, false>
+  >()
+  type Result = ReturnType<typeof useOrganizations<true, false>>
+  expectTypeOf<Result['data'][number]['members']>().toEqualTypeOf<OrganizationMember[]>()
+})
+
+test('useOrganizations — includeFeatures: true adds features to the type', () => {
+  expectTypeOf(useOrganizations({includeFeatures: true}).data).toEqualTypeOf<
+    Organizations<false, true>
+  >()
+})
+
+test('useOrganizations — both flags true → both arrays present', () => {
+  expectTypeOf(useOrganizations({includeMembers: true, includeFeatures: true}).data).toEqualTypeOf<
+    Organizations<true, true>
+  >()
+})
+
+test('useOrganizations — both flags false → bare base shape', () => {
+  expectTypeOf(
+    useOrganizations({includeMembers: false, includeFeatures: false}).data,
+  ).toEqualTypeOf<Organizations<false, false>>()
+  type Result = ReturnType<typeof useOrganizations<false, false>>
+  expectTypeOf<Result['data'][number]['id']>().toEqualTypeOf<string>()
+})
+
+test('useOrganizations — rejects non-boolean flag values', () => {
+  // @ts-expect-error — includeMembers must be a boolean
+  void useOrganizations({includeMembers: 'yes'})
+})
+
+test('useOrganizations — includeImplicitMemberships does not change the data shape', () => {
+  expectTypeOf(useOrganizations({includeImplicitMemberships: true}).data).toEqualTypeOf<
+    Organizations<false, false>
+  >()
+})
+
+test('useOrganizations — non-literal boolean flag makes members optional', () => {
+  const includeMembers = false as boolean
+  expectTypeOf(useOrganizations({includeMembers}).data).toEqualTypeOf<
+    Organizations<boolean, false>
+  >()
+  type Result = ReturnType<typeof useOrganizations<boolean, false>>
+  expectTypeOf<Result['data'][number]['members']>().toEqualTypeOf<
+    OrganizationMember[] | undefined
+  >()
+  expectTypeOf<Pick<Result['data'][number], 'members'>>().toEqualTypeOf<{
+    members?: OrganizationMember[]
+  }>()
+})