@sanity/sdk 2.10.0 → 2.11.0

package/src/project/project.test.ts

@@ -1,25 +1,31 @@
 import {type SanityClient} from '@sanity/client'
 import {of} from 'rxjs'
-import {describe, it} from 'vitest'
+import {afterEach, beforeEach, describe, it} from 'vitest'
 
 import {getClientState} from '../client/clientStore'
-import {createSanityInstance} from '../store/createSanityInstance'
+import {createSanityInstance, type SanityInstance} from '../store/createSanityInstance'
 import {type StateSource} from '../store/createStateSourceAction'
-import {resolveProject} from './project'
+import {getProjectCacheKey, resolveProject} from './project'
 
 vi.mock('../client/clientStore')
 
 describe('project', () => {
-  it('calls the `client.observable.projects.getById` method on the client and returns the result', async () => {
-    const instance = createSanityInstance({projectId: 'p', dataset: 'd'})
+  let instance: SanityInstance
 
+  beforeEach(() => {
+    instance = createSanityInstance({projectId: 'p', dataset: 'd'})
+  })
+
+  afterEach(() => {
+    instance.dispose()
+  })
+
+  it('calls `client.observable.request` against `/projects/<id>` and returns the result', async () => {
     const project = {id: 'a'}
-    const getById = vi.fn().mockReturnValue(of(project))
+    const request = vi.fn().mockReturnValue(of(project))
 
     const mockClient = {
-      observable: {
-        projects: {getById} as unknown as SanityClient['observable']['projects'],
-      },
+      observable: {request} as unknown as SanityClient['observable'],
     } as SanityClient
 
     vi.mocked(getClientState).mockReturnValue({
@@ -28,6 +34,98 @@ describe('project', () => {
 
     const result = await resolveProject(instance, {projectId: 'a'})
     expect(result).toEqual(project)
-    expect(getById).toHaveBeenCalledWith('a')
+    expect(request).toHaveBeenCalledWith({
+      uri: '/projects/a',
+      query: {includeMembers: 'true', includeFeatures: 'true'},
+      tag: 'project.get',
+    })
+  })
+
+  it('serializes query params (booleans → strings) and respects flags', async () => {
+    const request = vi.fn().mockReturnValue(of({id: 'a'}))
+    const mockClient = {
+      observable: {request} as unknown as SanityClient['observable'],
+    } as SanityClient
+
+    vi.mocked(getClientState).mockReturnValue({
+      observable: of(mockClient),
+    } as StateSource<SanityClient>)
+
+    await resolveProject(instance, {
+      projectId: 'a',
+      includeMembers: false,
+      includeFeatures: false,
+    })
+
+    expect(request).toHaveBeenCalledWith({
+      uri: '/projects/a',
+      query: {
+        includeMembers: 'false',
+        includeFeatures: 'false',
+      },
+      tag: 'project.get',
+    })
+  })
+
+  it('falls back to the instance projectId when none is provided in options', async () => {
+    const request = vi.fn().mockReturnValue(of({id: 'p'}))
+    const mockClient = {
+      observable: {request} as unknown as SanityClient['observable'],
+    } as SanityClient
+
+    vi.mocked(getClientState).mockReturnValue({
+      observable: of(mockClient),
+    } as StateSource<SanityClient>)
+
+    await resolveProject(instance)
+    expect(request).toHaveBeenCalledWith({
+      uri: '/projects/p',
+      query: {includeMembers: 'true', includeFeatures: 'true'},
+      tag: 'project.get',
+    })
+  })
+})
+
+describe('project cache key generation', () => {
+  const mockInstance = {config: {projectId: 'p'}} as SanityInstance
+
+  it('default call includes :members and :features (both default-true)', () => {
+    expect(getProjectCacheKey(mockInstance)).toBe('project:p:members:features')
+  })
+
+  it('treats undefined and the matching default as the same key', () => {
+    expect(getProjectCacheKey(mockInstance)).toBe(
+      getProjectCacheKey(mockInstance, {includeMembers: true, includeFeatures: true}),
+    )
+  })
+
+  it('explicit includeFeatures: false drops the :features segment', () => {
+    expect(getProjectCacheKey(mockInstance, {includeFeatures: false})).toBe('project:p:members')
+  })
+
+  it('explicit includeMembers: false drops the :members segment', () => {
+    expect(getProjectCacheKey(mockInstance, {includeMembers: false})).toBe('project:p:features')
+  })
+
+  it('combines all segments in order', () => {
+    expect(
+      getProjectCacheKey(mockInstance, {
+        projectId: 'a',
+        includeMembers: true,
+        includeFeatures: true,
+      }),
+    ).toBe('project:a:members:features')
+  })
+
+  it('produces distinct keys for each meaningful option permutation', () => {
+    const keys = new Set([
+      getProjectCacheKey(mockInstance),
+      getProjectCacheKey(mockInstance, {includeMembers: false}),
+      getProjectCacheKey(mockInstance, {includeFeatures: false}),
+      getProjectCacheKey(mockInstance, {includeMembers: false, includeFeatures: false}),
+      getProjectCacheKey(mockInstance, {projectId: 'a'}),
+      getProjectCacheKey(mockInstance, {projectId: 'b'}),
+    ])
+    expect(keys.size).toBe(6)
   })
 })

package/src/project/project.ts

@@ -2,40 +2,166 @@ import {switchMap} from 'rxjs'
 
 import {getClientState} from '../client/clientStore'
 import {type ProjectHandle} from '../config/sanityConfig'
+import {type SanityInstance} from '../store/createSanityInstance'
+import {type StateSource} from '../store/createStateSourceAction'
 import {createFetcherStore} from '../utils/createFetcherStore'
 
 const API_VERSION = 'v2025-02-19'
 
+/** @public */
+export interface ProjectMemberRole {
+  name: string
+  title: string
+  description: string
+}
+
+/** @public */
+export interface ProjectMember {
+  id: string
+  createdAt: string
+  updatedAt: string
+  isCurrentUser: boolean
+  isRobot: boolean
+  roles: ProjectMemberRole[]
+}
+
+/** @public */
+export interface ProjectMetadata {
+  color?: string
+  externalStudioHost?: string
+  initialTemplate?: string
+  cliInitializedAt?: string
+  integration: 'manage' | 'cli'
+}
+
+/**
+ * The base fields returned from `/projects` for every project.
+ * @public
+ */
+export interface ProjectBase {
+  id: string
+  displayName: string
+  studioHost: string | null
+  organizationId: string
+  metadata: ProjectMetadata
+  isBlocked: boolean
+  isDisabled: boolean
+  isDisabledByUser: boolean
+  activityFeedEnabled: boolean
+  createdAt: string
+  updatedAt: string
+}
+
+/**
+ * A `Project` with `members` and/or `features` conditionally included
+ * based on the query options used to fetch it.
+ * @public
+ */
+export type Project<
+  IncludeMembers extends boolean = true,
+  IncludeFeatures extends boolean = true,
+> = ProjectBase &
+  // `boolean extends T` is non-distributive — true only when T is the wide
+  // `boolean`, in which case the field is optional. Literal `true`/`false`
+  // fall through to the strict branch.
+  (boolean extends IncludeMembers
+    ? {members?: ProjectMember[]}
+    : IncludeMembers extends true
+      ? {members: ProjectMember[]}
+      : unknown) &
+  (boolean extends IncludeFeatures
+    ? {features?: string[]}
+    : IncludeFeatures extends true
+      ? {features: string[]}
+      : unknown)
+
+/** @public */
+export interface ProjectOptions<
+  IncludeMembers extends boolean = true,
+  IncludeFeatures extends boolean = true,
+> extends ProjectHandle {
+  includeMembers?: IncludeMembers
+  includeFeatures?: IncludeFeatures
+}
+
+function normalizeProjectOptions(options?: ProjectOptions<boolean, boolean>) {
+  return {
+    includeMembers: options?.includeMembers ?? true,
+    includeFeatures: options?.includeFeatures ?? true,
+  }
+}
+
+function resolveProjectId(instance: SanityInstance, options?: ProjectOptions<boolean, boolean>) {
+  const projectId = options?.projectId ?? instance.config.projectId
+  if (!projectId) {
+    throw new Error('A projectId is required to use the project API.')
+  }
+  return projectId
+}
+
+/** @internal */
+export function getProjectCacheKey(
+  instance: SanityInstance,
+  options?: ProjectOptions<boolean, boolean>,
+): string {
+  const projectId = resolveProjectId(instance, options)
+  const {includeMembers, includeFeatures} = normalizeProjectOptions(options)
+  const membersKey = includeMembers ? ':members' : ''
+  const featuresKey = includeFeatures ? ':features' : ''
+  return `project:${projectId}${membersKey}${featuresKey}`
+}
+
 const project = createFetcherStore({
   name: 'Project',
-  getKey: (instance, options?: ProjectHandle) => {
-    const projectId = options?.projectId ?? instance.config.projectId
-    if (!projectId) {
-      throw new Error('A projectId is required to use the project API.')
-    }
-    return projectId
+  getKey: getProjectCacheKey,
+  fetcher: (instance) => (options?: ProjectOptions<boolean, boolean>) => {
+    const projectId = resolveProjectId(instance, options)
+
+    return getClientState(instance, {
+      apiVersion: API_VERSION,
+      scope: 'global',
+    }).observable.pipe(
+      switchMap((client) => {
+        const normalized = normalizeProjectOptions(options)
+        const query = Object.fromEntries(
+          Object.entries(normalized)
+            .filter(([, value]) => value !== undefined)
+            .map(([key, value]) => [key, String(value)]),
+        )
+
+        return client.observable.request({
+          uri: `/projects/${projectId}`,
+          query,
+          tag: 'project.get',
+        })
+      }),
+    )
   },
-  fetcher:
-    (instance) =>
-    (options: ProjectHandle = {}) => {
-      const projectId = options.projectId ?? instance.config.projectId
-
-      return getClientState(instance, {
-        apiVersion: API_VERSION,
-        scope: 'global',
-        projectId,
-      }).observable.pipe(
-        switchMap((client) =>
-          client.observable.projects.getById(
-            // non-null assertion is fine with the above throwing
-            (projectId ?? instance.config.projectId)!,
-          ),
-        ),
-      )
-    },
 })
 
+/**
+ * Public signature for the project state source. The conditional generics
+ * cannot flow through `BoundStoreAction`, so we declare the signature here
+ * and assign the (already-correct) runtime function to it.
+ */
+type GetProjectState = <
+  IncludeMembers extends boolean = true,
+  IncludeFeatures extends boolean = true,
+>(
+  instance: SanityInstance,
+  options?: ProjectOptions<IncludeMembers, IncludeFeatures>,
+) => StateSource<Project<IncludeMembers, IncludeFeatures> | undefined>
+
+type ResolveProject = <
+  IncludeMembers extends boolean = true,
+  IncludeFeatures extends boolean = true,
+>(
+  instance: SanityInstance,
+  options?: ProjectOptions<IncludeMembers, IncludeFeatures>,
+) => Promise<Project<IncludeMembers, IncludeFeatures>>
+
 /** @public */
-export const getProjectState = project.getState
+export const getProjectState: GetProjectState = project.getState
+
 /** @public */
-export const resolveProject = project.resolveState
+export const resolveProject: ResolveProject = project.resolveState

package/src/projection/subscribeToStateAndFetchBatches.ts

@@ -16,7 +16,6 @@ import {
   tap,
 } from 'rxjs'
 
-import {isDatasetResource} from '../config/sanityConfig'
 import {getQueryState, resolveQuery} from '../query/queryStore'
 import {type BoundPerspectiveKey} from '../store/createActionBinder'
 import {type StoreContext} from '../store/defineStore'
@@ -113,8 +112,7 @@ export const subscribeToStateAndFetchBatches = ({
               tag: PROJECTION_TAG,
               perspective,
             },
-            // temporary guard here until we're ready for everything to be queried via global API
-            ...(resource && !isDatasetResource(resource) ? {resource} : {}),
+            resource,
           })
 
           const querySource$ = defer(() => {
@@ -128,8 +126,7 @@ export const subscribeToStateAndFetchBatches = ({
                     signal: controller.signal,
                     perspective,
                   },
-                  // temporary guard here until we're ready for everything to be queried via global API in v3
-                  ...(resource && !isDatasetResource(resource) ? {resource} : {}),
+                  resource,
                 }),
               ).pipe(switchMap(() => observable))
             }
@@ -154,8 +151,7 @@ export const subscribeToStateAndFetchBatches = ({
               tag: PROJECTION_TAG,
               perspective: 'raw',
             },
-            // temporary guard here until we're ready for everything to be queried via global API
-            ...(resource && !isDatasetResource(resource) ? {resource} : {}),
+            resource,
           })
 
           const statusQuerySource$ = defer(() => {
@@ -169,8 +165,7 @@ export const subscribeToStateAndFetchBatches = ({
                     signal: controller.signal,
                     perspective: 'raw',
                   },
-                  // temporary guard here until we're ready for everything to be queried via global API
-                  ...(resource && !isDatasetResource(resource) ? {resource} : {}),
+                  resource,
                 }),
               ).pipe(switchMap(() => observable))
             }

package/src/projects/projects.test-d.ts

@@ -0,0 +1,38 @@
+import {expectTypeOf, test} from 'vitest'
+
+import {type Project, type ProjectMember} from '../project/project'
+import {type SanityInstance} from '../store/createSanityInstance'
+import {type StateSource} from '../store/createStateSourceAction'
+import {getProjectsState, resolveProjects} from './projects'
+
+const instance = {} as SanityInstance
+
+test('resolveProjects — default call: features included, members omitted', () => {
+  expectTypeOf(resolveProjects(instance)).resolves.toEqualTypeOf<Project<false, true>[]>()
+})
+
+test('resolveProjects — includeMembers: true adds members to the type', () => {
+  expectTypeOf(resolveProjects(instance, {includeMembers: true})).resolves.toEqualTypeOf<
+    Project<true, true>[]
+  >()
+  type Result = Awaited<ReturnType<typeof resolveProjects<true, true>>>
+  expectTypeOf<Result[number]['members']>().toEqualTypeOf<ProjectMember[]>()
+})
+
+test('resolveProjects — includeFeatures: false drops features from the type', () => {
+  expectTypeOf(resolveProjects(instance, {includeFeatures: false})).resolves.toEqualTypeOf<
+    Project<false, false>[]
+  >()
+})
+
+test('resolveProjects — organizationId alone does not change the data shape', () => {
+  expectTypeOf(resolveProjects(instance, {organizationId: 'org_123'})).resolves.toEqualTypeOf<
+    Project<false, true>[]
+  >()
+})
+
+test('getProjectsState — default call returns features-only StateSource', () => {
+  expectTypeOf(getProjectsState(instance)).toEqualTypeOf<
+    StateSource<Project<false, true>[] | undefined>
+  >()
+})

package/src/projects/projects.test.ts

@@ -5,7 +5,7 @@ import {afterEach, beforeEach, describe, it} from 'vitest'
 import {getClientState} from '../client/clientStore'
 import {createSanityInstance, type SanityInstance} from '../store/createSanityInstance'
 import {type StateSource} from '../store/createStateSourceAction'
-import {resolveProjects} from './projects'
+import {getProjectsCacheKey, resolveProjects} from './projects'
 
 vi.mock('../client/clientStore')
 
@@ -20,14 +20,12 @@ describe('projects', () => {
     instance.dispose()
   })
 
-  it('calls the `client.observable.projects.list` method on the client and returns the result', async () => {
+  it('calls `client.observable.request` against `/projects` and returns the result', async () => {
     const projects = [{id: 'a'}, {id: 'b'}]
-    const list = vi.fn().mockReturnValue(of(projects))
+    const request = vi.fn().mockReturnValue(of(projects))
 
     const mockClient = {
-      observable: {
-        projects: {list} as unknown as SanityClient['observable']['projects'],
-      },
+      observable: {request} as unknown as SanityClient['observable'],
     } as SanityClient
 
     vi.mocked(getClientState).mockReturnValue({
@@ -36,41 +34,109 @@ describe('projects', () => {
 
     const result = await resolveProjects(instance)
     expect(result).toEqual(projects)
-    expect(list).toHaveBeenCalledWith({includeMembers: false, organizationId: undefined})
+    expect(request).toHaveBeenCalledWith({
+      uri: '/projects',
+      query: {includeMembers: 'false', includeFeatures: 'true', onlyExplicitMembership: 'false'},
+      tag: 'projects.get',
+    })
   })
-})
 
-describe('projects cache key generation', () => {
-  it('generates correct cache keys for different parameter combinations', async () => {
-    // Test the getKey function directly by creating a mock store
-    const mockGetKey = (
-      _instance: SanityInstance,
-      options?: {organizationId?: string; includeMembers?: boolean},
-    ) => {
-      const orgKey = options?.organizationId ? `:org:${options.organizationId}` : ''
-      const membersKey = options?.includeMembers === false ? ':no-members' : ''
-      return `projects${orgKey}${membersKey}`
-    }
-
-    const mockInstance = {} as SanityInstance
-
-    // Test default behavior (no options)
-    const defaultKey = mockGetKey(mockInstance)
-    expect(defaultKey).toBe('projects')
-
-    // Test with organizationId only
-    const orgKey = mockGetKey(mockInstance, {organizationId: 'org123'})
-    expect(orgKey).toBe('projects:org:org123')
-
-    // Test with includeMembers: false only
-    const noMembersKey = mockGetKey(mockInstance, {includeMembers: false})
-    expect(noMembersKey).toBe('projects:no-members')
-
-    // Test with both parameters
-    const bothKey = mockGetKey(mockInstance, {
+  it('serializes query params (booleans → strings) and omits undefined values', async () => {
+    const request = vi.fn().mockReturnValue(of([]))
+    const mockClient = {
+      observable: {request} as unknown as SanityClient['observable'],
+    } as SanityClient
+
+    vi.mocked(getClientState).mockReturnValue({
+      observable: of(mockClient),
+    } as StateSource<SanityClient>)
+
+    await resolveProjects(instance, {
       organizationId: 'org123',
-      includeMembers: false,
+      includeMembers: true,
+      includeFeatures: false,
     })
-    expect(bothKey).toBe('projects:org:org123:no-members')
+
+    expect(request).toHaveBeenCalledWith({
+      uri: '/projects',
+      query: {
+        organizationId: 'org123',
+        includeMembers: 'true',
+        includeFeatures: 'false',
+        onlyExplicitMembership: 'false',
+      },
+      tag: 'projects.get',
+    })
+  })
+})
+
+describe('projects cache key generation', () => {
+  let instance: SanityInstance
+
+  beforeEach(() => {
+    instance = createSanityInstance({projectId: 'p', dataset: 'd'})
+  })
+
+  afterEach(() => {
+    instance.dispose()
+  })
+
+  it('default call includes :features (default-true) and excludes :members (default-false)', () => {
+    expect(getProjectsCacheKey(instance)).toBe('projects:features')
+  })
+
+  it('treats undefined and the matching default as the same key', () => {
+    expect(getProjectsCacheKey(instance)).toBe(
+      getProjectsCacheKey(instance, {includeMembers: false, includeFeatures: true}),
+    )
+  })
+
+  it('treats raw and explicit defaults equivalently', () => {
+    expect(getProjectsCacheKey(instance, {organizationId: 'org123'})).toBe(
+      getProjectsCacheKey(instance, {
+        organizationId: 'org123',
+        includeMembers: false,
+        includeFeatures: true,
+        onlyExplicitMembership: false,
+      }),
+    )
+  })
+
+  it('explicit includeFeatures: false drops the :features segment', () => {
+    expect(getProjectsCacheKey(instance, {includeFeatures: false})).toBe('projects')
+  })
+
+  it('appends an org segment when organizationId is set', () => {
+    expect(getProjectsCacheKey(instance, {organizationId: 'org123'})).toBe(
+      'projects:org:org123:features',
+    )
+  })
+
+  it('appends :members when includeMembers is true', () => {
+    expect(getProjectsCacheKey(instance, {includeMembers: true})).toBe('projects:members:features')
+  })
+
+  it('combines all segments in order', () => {
+    expect(
+      getProjectsCacheKey(instance, {
+        organizationId: 'org123',
+        includeMembers: true,
+        includeFeatures: true,
+        onlyExplicitMembership: true,
+      }),
+    ).toBe('projects:org:org123:members:features:explicit')
+  })
+
+  it('produces distinct keys for each meaningful option permutation', () => {
+    const keys = new Set([
+      getProjectsCacheKey(instance),
+      getProjectsCacheKey(instance, {includeMembers: true}),
+      getProjectsCacheKey(instance, {includeFeatures: false}),
+      getProjectsCacheKey(instance, {includeMembers: true, includeFeatures: false}),
+      getProjectsCacheKey(instance, {onlyExplicitMembership: true}),
+      getProjectsCacheKey(instance, {organizationId: 'a'}),
+      getProjectsCacheKey(instance, {organizationId: 'b'}),
+    ])
+    expect(keys.size).toBe(7)
   })
 })