@sanity/sdk 2.9.0 → 2.11.0

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/getProjectionState.ts

@@ -1,9 +1,8 @@
 import {DocumentId, getPublishedId} from '@sanity/id-utils'
 import {type SanityProjectionResult} from 'groq'
-import {omit} from 'lodash-es'
 
 import {type DocumentHandle} from '../config/sanityConfig'
-import {bindActionBySourceAndPerspective} from '../store/createActionBinder'
+import {bindActionByResourceAndPerspective} from '../store/createActionBinder'
 import {type SanityInstance} from '../store/createSanityInstance'
 import {
   createStateSourceAction,
@@ -12,6 +11,7 @@ import {
 } from '../store/createStateSourceAction'
 import {hashString} from '../utils/hashString'
 import {insecureRandomId} from '../utils/ids'
+import {omitProperty} from '../utils/object'
 import {setCleanupTimeout} from '../utils/setCleanupTimeout'
 import {projectionStore} from './projectionStore'
 import {type ProjectionStoreState, type ProjectionValuePending} from './types'
@@ -72,7 +72,7 @@ export function getProjectionState(
 /**
  * @beta
  */
-export const _getProjectionState = bindActionBySourceAndPerspective(
+export const _getProjectionState = bindActionByResourceAndPerspective(
   projectionStore,
   createStateSourceAction({
     selector: (
@@ -113,7 +113,7 @@ export const _getProjectionState = bindActionBySourceAndPerspective(
       return () => {
         setCleanupTimeout(() => {
           state.set('removeSubscription', (prev): Partial<ProjectionStoreState> => {
-            const documentSubscriptionsForHash = omit(
+            const documentSubscriptionsForHash = omitProperty(
               prev.subscriptions[documentId]?.[projectionHash],
               subscriptionId,
             )

package/src/projection/projectionStore.test.ts

@@ -30,7 +30,7 @@ describe('projectionStore', () => {
       instance,
       {
         name: 'p.d',
-        source: {projectId: 'p', dataset: 'd'},
+        resource: {projectId: 'p', dataset: 'd'},
         perspective: 'drafts',
       },
       projectionStore,
@@ -42,7 +42,7 @@ describe('projectionStore', () => {
       state,
       key: {
         name: 'p.d',
-        source: {projectId: 'p', dataset: 'd'},
+        resource: {projectId: 'p', dataset: 'd'},
         perspective: 'drafts',
       },
     })

package/src/projection/resolveProjection.ts

@@ -1,7 +1,7 @@
 import {type SanityProjectionResult} from 'groq'
 import {filter, firstValueFrom} from 'rxjs'
 
-import {bindActionBySourceAndPerspective} from '../store/createActionBinder'
+import {bindActionByResourceAndPerspective} from '../store/createActionBinder'
 import {type SanityInstance} from '../store/createSanityInstance'
 import {getProjectionState, type ProjectionOptions} from './getProjectionState'
 import {projectionStore} from './projectionStore'
@@ -38,7 +38,7 @@ export function resolveProjection(
 /**
  * @beta
  */
-const _resolveProjection = bindActionBySourceAndPerspective(
+const _resolveProjection = bindActionByResourceAndPerspective(
   projectionStore,
   (
     {instance}: {instance: SanityInstance},

package/src/projection/subscribeToStateAndFetchBatches.test.ts

@@ -17,7 +17,7 @@ describe('subscribeToStateAndFetchBatches', () => {
   let state: StoreState<ProjectionStoreState>
   const key = {
     name: 'test.test:drafts',
-    source: {projectId: 'test', dataset: 'test'},
+    resource: {projectId: 'test', dataset: 'test'},
     perspective: 'drafts' as const,
   }
 

package/src/projection/subscribeToStateAndFetchBatches.ts

@@ -1,4 +1,4 @@
-import {isEqual} from 'lodash-es'
+import {DocumentId} from '@sanity/id-utils'
 import {
   combineLatest,
   debounceTime,
@@ -16,10 +16,10 @@ import {
   tap,
 } from 'rxjs'
 
-import {isDatasetSource} from '../config/sanityConfig'
 import {getQueryState, resolveQuery} from '../query/queryStore'
 import {type BoundPerspectiveKey} from '../store/createActionBinder'
 import {type StoreContext} from '../store/defineStore'
+import {isDeepEqual} from '../utils/object'
 import {
   createProjectionQuery,
   processProjectionQuery,
@@ -42,22 +42,22 @@ interface StatusQueryResult {
 export const subscribeToStateAndFetchBatches = ({
   state,
   instance,
-  key: {source, perspective},
+  key: {resource, perspective},
 }: StoreContext<ProjectionStoreState, BoundPerspectiveKey>): Subscription => {
   const documentProjections$ = state.observable.pipe(
     map((s) => s.documentProjections),
-    distinctUntilChanged(isEqual),
+    distinctUntilChanged(isDeepEqual),
   )
 
   const activeDocumentIds$ = state.observable.pipe(
-    map(({subscriptions}) => new Set(Object.keys(subscriptions))),
+    map(({subscriptions}) => new Set(Object.keys(subscriptions).map((id) => DocumentId(id)))),
     distinctUntilChanged(isSetEqual),
   )
 
   const pendingUpdateSubscription = activeDocumentIds$
     .pipe(
       debounceTime(BATCH_DEBOUNCE_TIME),
-      startWith(new Set<string>()),
+      startWith(new Set<DocumentId>()),
       pairwise(),
       tap(([prevIds, currIds]) => {
         const newIds = [...currIds].filter((id) => !prevIds.has(id))
@@ -89,7 +89,7 @@ export const subscribeToStateAndFetchBatches = ({
 
   const queryTrigger$ = combineLatest([activeDocumentIds$, documentProjections$]).pipe(
     debounceTime(BATCH_DEBOUNCE_TIME),
-    distinctUntilChanged(isEqual),
+    distinctUntilChanged(isDeepEqual),
   )
 
   const queryExecutionSubscription = queryTrigger$
@@ -112,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
-            ...(source && !isDatasetSource(source) ? {source} : {}),
+            resource,
           })
 
           const querySource$ = defer(() => {
@@ -127,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
-                  ...(source && !isDatasetSource(source) ? {source} : {}),
+                  resource,
                 }),
               ).pipe(switchMap(() => observable))
             }
@@ -153,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
-            ...(source && !isDatasetSource(source) ? {source} : {}),
+            resource,
           })
 
           const statusQuerySource$ = defer(() => {
@@ -168,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
-                  ...(source && !isDatasetSource(source) ? {source} : {}),
+                  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)
   })
 })