@sanity/sdk 2.9.0 → 2.11.0

package/src/presence/presenceStore.ts

@@ -1,20 +1,45 @@
-import {type SanityClient} from '@sanity/client'
 import {createSelector} from 'reselect'
-import {combineLatest, distinctUntilChanged, filter, map, of, Subscription, switchMap} from 'rxjs'
+import {
+  catchError,
+  combineLatest,
+  distinctUntilChanged,
+  EMPTY,
+  filter,
+  first,
+  map,
+  type Observable,
+  of,
+  Subscription,
+  switchMap,
+} from 'rxjs'
 
 import {getTokenState} from '../auth/authStore'
 import {getClient} from '../client/clientStore'
-import {bindActionByDataset, type BoundDatasetKey} from '../store/createActionBinder'
-import {createStateSourceAction, type SelectorContext} from '../store/createStateSourceAction'
+import {
+  type DocumentResource,
+  isCanvasResource,
+  isDatasetResource,
+  isMediaLibraryResource,
+} from '../config/sanityConfig'
+import {bindActionByResource, type BoundResourceKey} from '../store/createActionBinder'
+import {type SanityInstance} from '../store/createSanityInstance'
+import {
+  createStateSourceAction,
+  type SelectorContext,
+  type StateSource,
+} from '../store/createStateSourceAction'
 import {defineStore, type StoreContext} from '../store/defineStore'
 import {type SanityUser} from '../users/types'
 import {getUserState} from '../users/usersStore'
 import {createBifurTransport} from './bifurTransport'
 import {type PresenceLocation, type TransportEvent, type UserPresence} from './types'
 
+const PRESENCE_API_VERSION = '2026-03-30'
+
 type PresenceStoreState = {
   locations: Map<string, {userId: string; locations: PresenceLocation[]}>
   users: Record<string, SanityUser | undefined>
+  organizationId?: string
 }
 
 const getInitialState = (): PresenceStoreState => ({
@@ -23,27 +48,40 @@ const getInitialState = (): PresenceStoreState => ({
 })
 
 /** @public */
-export const presenceStore = defineStore<PresenceStoreState, BoundDatasetKey>({
+export const presenceStore = defineStore<PresenceStoreState, BoundResourceKey>({
   name: 'presence',
   getInitialState,
-  initialize: (context: StoreContext<PresenceStoreState, BoundDatasetKey>) => {
+  initialize: (context: StoreContext<PresenceStoreState, BoundResourceKey>) => {
     const {
       instance,
       state,
-      key: {projectId, dataset},
+      key: {resource},
     } = context
+
+    if (isMediaLibraryResource(resource)) {
+      throw new Error('Presence is not supported for media library resources.')
+    }
+
     const sessionId = crypto.randomUUID()
 
-    const client = getClient(instance, {
-      apiVersion: '2022-06-30',
-      projectId,
-      dataset,
-    })
+    // Dataset resources must use the project hostname so the socket URL is project-specific.
+    // Canvas resources use the global API endpoint via the resource config.
+    const client = isDatasetResource(resource)
+      ? getClient(instance, {
+          apiVersion: PRESENCE_API_VERSION,
+          projectId: resource.projectId,
+          dataset: resource.dataset,
+          useProjectHostname: true,
+        })
+      : getClient(instance, {
+          apiVersion: PRESENCE_API_VERSION,
+          resource,
+        })
 
     const token$ = getTokenState(instance).observable.pipe(distinctUntilChanged())
 
     const [incomingEvents$, dispatch] = createBifurTransport({
-      client: client as SanityClient,
+      client,
       token$,
       sessionId,
     })
@@ -81,6 +119,22 @@ export const presenceStore = defineStore<PresenceStoreState, BoundDatasetKey>({
 
     dispatch({type: 'rollCall'}).subscribe()
 
+    // Canvas resources need the organizationId to resolve users — fetch it once from the canvas endpoint
+    if (isCanvasResource(resource)) {
+      const globalClient = getClient(instance, {apiVersion: PRESENCE_API_VERSION})
+      subscription.add(
+        globalClient.observable
+          .request<{organizationId: string}>({
+            uri: `/canvases/${resource.canvasId}`,
+            tag: 'canvases.get',
+          })
+          .pipe(catchError(() => EMPTY))
+          .subscribe(({organizationId}) => {
+            state.set('presence/organizationId', (prev) => ({...prev, organizationId}))
+          }),
+      )
+    }
+
     return () => {
       dispatch({type: 'disconnect'}).subscribe()
       subscription.unsubscribe()
@@ -114,13 +168,13 @@ const selectPresence = createSelector(
   },
 )
 
-/** @public */
-export const getPresence = bindActionByDataset(
+const _getPresence = bindActionByResource(
   presenceStore,
   createStateSourceAction({
-    selector: (context: SelectorContext<PresenceStoreState>, _?): UserPresence[] =>
+    selector: (context: SelectorContext<PresenceStoreState>): UserPresence[] =>
       selectPresence(context.state),
-    onSubscribe: (context: StoreContext<PresenceStoreState, BoundDatasetKey>, _?) => {
+    onSubscribe: (context: StoreContext<PresenceStoreState, BoundResourceKey>) => {
+      const resource = context.key.resource
       const userIds$ = context.state.observable.pipe(
         map((state) =>
           Array.from(state.locations.values())
@@ -130,26 +184,34 @@ export const getPresence = bindActionByDataset(
         distinctUntilChanged((a, b) => a.length === b.length && a.every((v, i) => v === b[i])),
       )
 
-      const subscription = userIds$
+      // For canvas resources, wait for organizationId to be fetched and stored in state.
+      // For dataset resources, emit undefined immediately so the stream isn't blocked.
+      const organizationId$: Observable<string | undefined> = isCanvasResource(resource)
+        ? context.state.observable.pipe(
+            map((s) => s.organizationId),
+            filter((id): id is string => id !== undefined),
+            first(),
+          )
+        : of(undefined)
+
+      const subscription = combineLatest([userIds$, organizationId$])
         .pipe(
-          switchMap((userIds) => {
+          switchMap(([userIds, organizationId]) => {
             if (userIds.length === 0) {
               return of([])
             }
             const userObservables = userIds.map((userId) =>
               getUserState(context.instance, {
                 userId,
-                resourceType: 'project',
-                projectId: context.key.projectId,
+                ...(isDatasetResource(resource)
+                  ? {resourceType: 'project', projectId: resource.projectId}
+                  : {resourceType: 'organization', organizationId}),
               }).pipe(filter((v): v is NonNullable<typeof v> => !!v)),
             )
             return combineLatest(userObservables)
           }),
         )
         .subscribe((users) => {
-          if (!users) {
-            return
-          }
           context.state.set('presence/users', (prevState) => ({
             ...prevState,
             users: {
@@ -167,3 +229,13 @@ export const getPresence = bindActionByDataset(
     },
   }),
 )
+
+/** @beta */
+export function getPresence(
+  instance: SanityInstance,
+  params?: {resource?: DocumentResource},
+): StateSource<UserPresence[]> {
+  // bit of a hack to support the old bound action by dataset
+  // in reality, this will always be passed a resource
+  return _getPresence(instance, params ?? {})
+}

package/src/preview/getPreviewState.ts

@@ -52,7 +52,7 @@ export function getPreviewState(
       return {data: null, isPending: current?.isPending ?? false}
     }
 
-    const previewValue = transformProjectionToPreview(instance, current.data, options.source)
+    const previewValue = transformProjectionToPreview(instance, current.data, options.resource)
 
     return {
       data: previewValue,

package/src/preview/previewProjectionUtils.test.ts

@@ -156,7 +156,7 @@ describe('transformProjectionToPreview', () => {
     })
   })
 
-  it('calls getClient with the provided source', async () => {
+  it('calls getClient with the provided resource', async () => {
     const projectionResult: PreviewQueryResult = {
       _id: 'doc1',
       _type: 'article',
@@ -166,14 +166,14 @@ describe('transformProjectionToPreview', () => {
       media: null,
     }
 
-    const source = {mediaLibraryId: 'test-library'}
+    const resource = {mediaLibraryId: 'test-library'}
 
-    transformProjectionToPreview(instance, projectionResult, source)
+    transformProjectionToPreview(instance, projectionResult, resource)
 
     const {getClient} = await import('../client/clientStore')
     expect(getClient).toHaveBeenCalledWith(instance, {
       apiVersion: 'v2025-05-06',
-      source,
+      resource,
     })
   })
 })

package/src/preview/previewProjectionUtils.ts

@@ -1,10 +1,10 @@
 import {type SanityClient} from '@sanity/client'
 import {createImageUrlBuilder} from '@sanity/image-url'
-import {isObject} from 'lodash-es'
 
 import {getClient} from '../client/clientStore'
-import {type DocumentSource, isDatasetSource} from '../config/sanityConfig'
+import {type DocumentResource} from '../config/sanityConfig'
 import {type SanityInstance} from '../store/createSanityInstance'
+import {isObject} from '../utils/object'
 import {SUBTITLE_CANDIDATES, TITLE_CANDIDATES} from './previewConstants'
 import {type PreviewQueryResult, type PreviewValue} from './types'
 
@@ -66,22 +66,21 @@ function findFirstDefined(
  *
  * @param projectionResult - The raw projection result from GROQ
  * @param instance - The Sanity instance to use for client configuration
- * @param source - Data source for the preview
+ * @param resource - Data resource for the preview
  * @internal
  */
 export function transformProjectionToPreview(
   instance: SanityInstance,
   projectionResult: PreviewQueryResult,
-  source?: DocumentSource,
+  resource?: DocumentResource,
 ): PreviewValue {
   const title = findFirstDefined(TITLE_CANDIDATES, projectionResult.titleCandidates)
   const subtitle = findFirstDefined(SUBTITLE_CANDIDATES, projectionResult.subtitleCandidates, title)
 
-  // Get a client for the source (if provided) or use the instance config
+  // Get a client for the resource (if provided) or use the instance config
   const client = getClient(instance, {
     apiVersion: API_VERSION,
-    // TODO: remove in v3 when we're ready for everything to be queried via source
-    source: source && !isDatasetSource(source) ? source : undefined,
+    resource,
   })
 
   return {

package/src/preview/resolvePreview.ts

@@ -30,7 +30,11 @@ export async function resolvePreview(
   }
 
   // Transform to preview format
-  const previewValue = transformProjectionToPreview(instance, projectionResult.data, options.source)
+  const previewValue = transformProjectionToPreview(
+    instance,
+    projectionResult.data,
+    options.resource,
+  )
 
   return {
     data: previewValue,

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

@@ -0,0 +1,93 @@
+import {expectTypeOf, test} from 'vitest'
+
+import {type SanityInstance} from '../store/createSanityInstance'
+import {type StateSource} from '../store/createStateSourceAction'
+import {
+  getProjectState,
+  type Project,
+  type ProjectBase,
+  type ProjectMember,
+  resolveProject,
+} from './project'
+
+const instance = {} as SanityInstance
+
+test('resolveProject — default call: members and features both included by default', () => {
+  expectTypeOf(resolveProject(instance)).resolves.toEqualTypeOf<Project<true, true>>()
+  type Result = Awaited<ReturnType<typeof resolveProject<true, true>>>
+  expectTypeOf<Result['members']>().toEqualTypeOf<ProjectMember[]>()
+})
+
+test('resolveProject — includeMembers: false drops members from the type', () => {
+  expectTypeOf(resolveProject(instance, {includeMembers: false})).resolves.toEqualTypeOf<
+    Project<false, true>
+  >()
+})
+
+test('resolveProject — includeFeatures: false drops features from the type', () => {
+  expectTypeOf(resolveProject(instance, {includeFeatures: false})).resolves.toEqualTypeOf<
+    Project<true, false>
+  >()
+})
+
+test('resolveProject — both flags false → bare base shape', () => {
+  expectTypeOf(
+    resolveProject(instance, {includeMembers: false, includeFeatures: false}),
+  ).resolves.toEqualTypeOf<Project<false, false>>()
+  type Result = Awaited<ReturnType<typeof resolveProject<false, false>>>
+  expectTypeOf<Result['id']>().toEqualTypeOf<string>()
+})
+
+test('resolveProject — rejects non-boolean flag values', () => {
+  // @ts-expect-error — includeMembers must be a boolean
+  void resolveProject(instance, {includeMembers: 'yes'})
+})
+
+test('resolveProject — projectId alone does not change the data shape', () => {
+  expectTypeOf(resolveProject(instance, {projectId: 'p'})).resolves.toEqualTypeOf<
+    Project<true, true>
+  >()
+})
+
+test('resolveProject — non-literal boolean flag makes members optional', () => {
+  const includeMembers = false as boolean
+  expectTypeOf(resolveProject(instance, {includeMembers})).resolves.toEqualTypeOf<
+    Project<boolean, true>
+  >()
+})
+
+test('getProjectState — default call returns members + features StateSource', () => {
+  expectTypeOf(getProjectState(instance)).toEqualTypeOf<
+    StateSource<Project<true, true> | undefined>
+  >()
+})
+
+test('getProjectState — both flags false narrows to the bare base shape', () => {
+  expectTypeOf(
+    getProjectState(instance, {includeMembers: false, includeFeatures: false}),
+  ).toEqualTypeOf<StateSource<Project<false, false> | undefined>>()
+})
+
+test('Project — wide boolean for IncludeMembers makes members optional', () => {
+  expectTypeOf<Project<boolean, true>>().toEqualTypeOf<
+    ProjectBase & {members?: ProjectMember[]} & {features: string[]}
+  >()
+  expectTypeOf<Pick<Project<boolean, true>, 'members'>>().toEqualTypeOf<{
+    members?: ProjectMember[]
+  }>()
+})
+
+test('Project — wide boolean for IncludeFeatures makes features optional', () => {
+  expectTypeOf<Project<true, boolean>>().toEqualTypeOf<
+    ProjectBase & {members: ProjectMember[]} & {features?: string[]}
+  >()
+  expectTypeOf<Pick<Project<true, boolean>, 'features'>>().toEqualTypeOf<{
+    features?: string[]
+  }>()
+})
+
+test('Project — both wide booleans make both fields optional', () => {
+  expectTypeOf<Project<boolean, boolean>>().toEqualTypeOf<
+    ProjectBase & {members?: ProjectMember[]} & {features?: string[]}
+  >()
+})

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