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

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[]
+  }>()
+})

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

@@ -0,0 +1,63 @@
+import {type Organizations, organizations, 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 {useOrganizations} from './useOrganizations'
+
+vi.mock('@sanity/sdk', async (importOriginal) => {
+  const original = await importOriginal<typeof import('@sanity/sdk')>()
+  return {...original, organizations: {getState: vi.fn(), resolveState: vi.fn(), refetch: vi.fn()}}
+})
+
+const stateSource = (
+  current: Organizations | undefined,
+): StateSource<FetcherSnapshot<Organizations>> => {
+  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<Organizations>>
+}
+
+const sanityInstance = expect.objectContaining({config: expect.any(Object)})
+
+describe('useOrganizations', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    vi.mocked(organizations.getState).mockReturnValue(
+      stateSource([{id: 'org_1'}] as unknown as Organizations),
+    )
+  })
+
+  it('reads the organizations fetcher with the passed options', () => {
+    renderHook(() => useOrganizations({includeMembers: true}))
+    expect(organizations.getState).toHaveBeenCalledWith(sanityInstance, {includeMembers: true})
+  })
+
+  it('returns the fetcher data in the result envelope', () => {
+    const {result} = renderHook(() => useOrganizations())
+    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 organizations fetcher until data is available', () => {
+    vi.mocked(organizations.getState).mockReturnValue(stateSource(undefined))
+    vi.mocked(organizations.resolveState).mockReturnValue(new Promise(() => {}))
+    renderHook(() => useOrganizations())
+    expect(organizations.resolveState).toHaveBeenCalled()
+  })
+})

package/src/hooks/organizations/useOrganizations.ts

@@ -0,0 +1,39 @@
+import {type Organizations, organizations, type OrganizationsOptions} from '@sanity/sdk'
+
+import {createFetcherHook, type FetcherHookResult} from '../helpers/createFetcherHook'
+
+/**
+ * Returns metadata for each organisation the current user has access to.
+ *
+ * @category Organizations
+ * @param options - Configuration options
+ * @returns A {@link FetcherHookResult} whose `data` is an array of organisation
+ *   metadata. `members` is included only when `includeMembers: true`; `features`
+ *   is included only when `includeFeatures: true`.
+ * @example
+ * ```tsx
+ * const {data: organizations} = useOrganizations()
+ *
+ * return (
+ *   <select>
+ *     {organizations.map((organization) => (
+ *       <option key={organization.id}>{organization.name}</option>
+ *     ))}
+ *   </select>
+ * )
+ * ```
+ * @example
+ * ```tsx
+ * const {data: organizationsWithMembers} = useOrganizations({includeMembers: true})
+ * const {data: organizationsWithFeatures} = useOrganizations({includeFeatures: true})
+ * const {data: organizationsIncludingImplicit} = useOrganizations({includeImplicitMemberships: true})
+ * ```
+ * @public
+ * @function
+ */
+export const useOrganizations = createFetcherHook(organizations) as <
+  IncludeMembers extends boolean = false,
+  IncludeFeatures extends boolean = false,
+>(
+  options?: OrganizationsOptions<IncludeMembers, IncludeFeatures>,
+) => FetcherHookResult<Organizations<IncludeMembers, IncludeFeatures>>

package/src/hooks/paginatedDocuments/usePaginatedDocuments.test.tsx

@@ -1,14 +1,20 @@
-import {type DatasetResource} from '@sanity/sdk'
+import {act, renderHook} from '@testing-library/react'
 import {evaluateSync, parse, toJS} from 'groq-js'
 import {describe, vi} from 'vitest'
 
-import {act, renderHook} from '../../../test/test-utils'
+import {ResourceProvider} from '../../context/ResourceProvider'
 import {useQuery} from '../query/useQuery'
 import {usePaginatedDocuments} from './usePaginatedDocuments'
 
 vi.mock('../query/useQuery')
 
 describe('usePaginatedDocuments', () => {
+  const wrapper = ({children}: {children: React.ReactNode}) => (
+    <ResourceProvider projectId="p" dataset="d" fallback={null}>
+      {children}
+    </ResourceProvider>
+  )
+
   beforeEach(() => {
     const dataset = [
       {
@@ -77,14 +83,16 @@ describe('usePaginatedDocuments', () => {
 
   it('should respect custom page size', () => {
     const customPageSize = 2
-    const {result} = renderHook(() => usePaginatedDocuments({pageSize: customPageSize}))
+    const {result} = renderHook(() => usePaginatedDocuments({pageSize: customPageSize}), {wrapper})
 
     expect(result.current.pageSize).toBe(customPageSize)
     expect(result.current.data.length).toBeLessThanOrEqual(customPageSize)
   })
 
   it('should filter by document type', () => {
-    const {result} = renderHook(() => usePaginatedDocuments({filter: '_type == "movie"'}))
+    const {result} = renderHook(() => usePaginatedDocuments({filter: '_type == "movie"'}), {
+      wrapper,
+    })
 
     expect(result.current.data.every((doc) => doc.documentType === 'movie')).toBe(true)
     expect(result.current.count).toBe(5) // 5 movies in the dataset
@@ -92,18 +100,20 @@ describe('usePaginatedDocuments', () => {
 
   // groq-js doesn't support search filters yet
   it.skip('should apply search filter', () => {
-    const {result} = renderHook(() => usePaginatedDocuments({search: 'inter'}))
+    const {result} = renderHook(() => usePaginatedDocuments({search: 'inter'}), {wrapper})
 
     // Should match "Interstellar"
     expect(result.current.data.some((doc) => doc.documentId === 'movie3')).toBe(true)
   })
 
   it('should apply ordering', () => {
-    const {result} = renderHook(() =>
-      usePaginatedDocuments({
-        filter: '_type == "movie"',
-        orderings: [{field: 'releaseYear', direction: 'desc'}],
-      }),
+    const {result} = renderHook(
+      () =>
+        usePaginatedDocuments({
+          filter: '_type == "movie"',
+          orderings: [{field: 'releaseYear', direction: 'desc'}],
+        }),
+      {wrapper},
     )
 
     // First item should be the most recent movie (Interstellar, 2014)
@@ -112,7 +122,7 @@ describe('usePaginatedDocuments', () => {
 
   it('should calculate pagination values correctly', () => {
     const pageSize = 2
-    const {result} = renderHook(() => usePaginatedDocuments({pageSize}))
+    const {result} = renderHook(() => usePaginatedDocuments({pageSize}), {wrapper})
 
     expect(result.current.currentPage).toBe(1)
     expect(result.current.totalPages).toBe(3) // 6 items with page size 2
@@ -123,7 +133,7 @@ describe('usePaginatedDocuments', () => {
 
   it('should navigate to next page', () => {
     const pageSize = 2
-    const {result} = renderHook(() => usePaginatedDocuments({pageSize}))
+    const {result} = renderHook(() => usePaginatedDocuments({pageSize}), {wrapper})
 
     expect(result.current.currentPage).toBe(1)
     expect(result.current.data.length).toBe(pageSize)
@@ -139,7 +149,7 @@ describe('usePaginatedDocuments', () => {
 
   it('should navigate to previous page', () => {
     const pageSize = 2
-    const {result} = renderHook(() => usePaginatedDocuments({pageSize}))
+    const {result} = renderHook(() => usePaginatedDocuments({pageSize}), {wrapper})
 
     // Go to page 2 first
     act(() => {
@@ -159,7 +169,7 @@ describe('usePaginatedDocuments', () => {
 
   it('should navigate to first page', () => {
     const pageSize = 2
-    const {result} = renderHook(() => usePaginatedDocuments({pageSize}))
+    const {result} = renderHook(() => usePaginatedDocuments({pageSize}), {wrapper})
 
     // Go to last page first
     act(() => {
@@ -179,7 +189,7 @@ describe('usePaginatedDocuments', () => {
 
   it('should navigate to last page', () => {
     const pageSize = 2
-    const {result} = renderHook(() => usePaginatedDocuments({pageSize}))
+    const {result} = renderHook(() => usePaginatedDocuments({pageSize}), {wrapper})
 
     act(() => {
       result.current.lastPage()
@@ -191,7 +201,7 @@ describe('usePaginatedDocuments', () => {
 
   it('should navigate to specific page', () => {
     const pageSize = 2
-    const {result} = renderHook(() => usePaginatedDocuments({pageSize}))
+    const {result} = renderHook(() => usePaginatedDocuments({pageSize}), {wrapper})
 
     act(() => {
       result.current.goToPage(2) // Go to page 2
@@ -216,7 +226,7 @@ describe('usePaginatedDocuments', () => {
 
   it('should set page availability flags correctly', () => {
     const pageSize = 2
-    const {result} = renderHook(() => usePaginatedDocuments({pageSize}))
+    const {result} = renderHook(() => usePaginatedDocuments({pageSize}), {wrapper})
     // On first page
     expect(result.current.hasFirstPage).toBe(false)
     expect(result.current.hasPreviousPage).toBe(false)
@@ -244,6 +254,7 @@ describe('usePaginatedDocuments', () => {
   it('should reset current page when filter changes', () => {
     const {result, rerender} = renderHook((props) => usePaginatedDocuments(props), {
       initialProps: {pageSize: 2, filter: ''},
+      wrapper,
     })
     // Initially, current page should be 1
     expect(result.current.currentPage).toBe(1)
@@ -259,19 +270,15 @@ describe('usePaginatedDocuments', () => {
   })
 
   it('should add projectId and dataset to document handles', () => {
-    const {result} = renderHook(() => usePaginatedDocuments({}))
+    const {result} = renderHook(() => usePaginatedDocuments({}), {wrapper})
 
     // Check that the first document handle has the projectId and dataset
-    expect((result.current.data[0].resource as DatasetResource).projectId).toBe('test')
-    expect((result.current.data[0].resource as DatasetResource).dataset).toBe('test')
+    expect(result.current.data[0].projectId).toBe('p')
+    expect(result.current.data[0].dataset).toBe('d')
 
     // Verify all document handles have these properties
-    expect(
-      result.current.data.every(
-        (doc) =>
-          (doc.resource as DatasetResource).projectId === 'test' &&
-          (doc.resource as DatasetResource).dataset === 'test',
-      ),
-    ).toBe(true)
+    expect(result.current.data.every((doc) => doc.projectId === 'p' && doc.dataset === 'd')).toBe(
+      true,
+    )
   })
 })