@sanity/sdk 2.7.0 → 3.0.0-rc.0

package/src/presence/presenceStore.test.ts

@@ -69,7 +69,7 @@ describe('presenceStore', () => {
     mockGetUserState = vi.fn(() => of(mockUser))
     vi.mocked(getUserState).mockImplementation(mockGetUserState)
 
-    instance = createSanityInstance({projectId: 'test-project', dataset: 'test-dataset'})
+    instance = createSanityInstance()
   })
 
   afterEach(() => {
@@ -77,8 +77,9 @@ describe('presenceStore', () => {
   })
 
   describe('getPresence', () => {
+    const key = {resource: {projectId: 'test-project', dataset: 'test-dataset'}}
     it('creates bifur transport with correct parameters', () => {
-      getPresence(instance)
+      getPresence(instance, key)
 
       expect(createBifurTransport).toHaveBeenCalledWith({
         client: mockClient,
@@ -88,18 +89,18 @@ describe('presenceStore', () => {
     })
 
     it('sends rollCall message on initialization', () => {
-      getPresence(instance)
+      getPresence(instance, key)
 
       expect(mockDispatchMessage).toHaveBeenCalledWith({type: 'rollCall'})
     })
 
     it('returns empty array when no users present', () => {
-      const source = getPresence(instance)
+      const source = getPresence(instance, key)
       expect(source.getCurrent()).toEqual([])
     })
 
     it('handles state events from other users', async () => {
-      const source = getPresence(instance)
+      const source = getPresence(instance, key)
 
       // Subscribe to initialize the store
       const unsubscribe = source.subscribe(() => {})
@@ -136,7 +137,7 @@ describe('presenceStore', () => {
     })
 
     it('ignores events from own session', async () => {
-      const source = getPresence(instance)
+      const source = getPresence(instance, key)
       const unsubscribe = source.subscribe(() => {})
 
       await firstValueFrom(of(null).pipe(delay(10)))
@@ -158,7 +159,7 @@ describe('presenceStore', () => {
     })
 
     it('handles disconnect events', async () => {
-      const source = getPresence(instance)
+      const source = getPresence(instance, key)
       const unsubscribe = source.subscribe(() => {})
 
       await firstValueFrom(of(null).pipe(delay(10)))
@@ -190,7 +191,7 @@ describe('presenceStore', () => {
     })
 
     it('fetches user data for present users', async () => {
-      const source = getPresence(instance)
+      const source = getPresence(instance, key)
       const unsubscribe = source.subscribe(() => {})
 
       await firstValueFrom(of(null).pipe(delay(10)))
@@ -222,7 +223,7 @@ describe('presenceStore', () => {
     })
 
     it('handles presence events correctly', async () => {
-      const source = getPresence(instance)
+      const source = getPresence(instance, key)
       const unsubscribe = source.subscribe(() => {})
 
       await firstValueFrom(of(null).pipe(delay(10)))
@@ -243,5 +244,29 @@ describe('presenceStore', () => {
 
       unsubscribe()
     })
+
+    it('should throw an error when initialized with a media library resource', () => {
+      const mediaLibraryResource = {mediaLibraryId: 'ml123'}
+
+      expect(() => {
+        getPresence(instance, {resource: mediaLibraryResource})
+      }).toThrow('Presence is not supported for media library resources')
+    })
+
+    it('should throw an error when initialized with a canvas resource', () => {
+      const canvasResource = {canvasId: 'canvas123'}
+
+      expect(() => {
+        getPresence(instance, {resource: canvasResource})
+      }).toThrow('Presence is not supported for canvas resources')
+    })
+
+    it('should work with a dataset resource', () => {
+      const datasetResource = {projectId: 'test-project', dataset: 'test-dataset'}
+
+      expect(() => {
+        getPresence(instance, {resource: datasetResource})
+      }).not.toThrow()
+    })
   })
 })

package/src/presence/presenceStore.ts

@@ -1,10 +1,10 @@
-import {type SanityClient} from '@sanity/client'
 import {createSelector} from 'reselect'
 import {combineLatest, distinctUntilChanged, filter, map, of, Subscription, switchMap} from 'rxjs'
 
 import {getTokenState} from '../auth/authStore'
 import {getClient} from '../client/clientStore'
-import {bindActionByDataset, type BoundDatasetKey} from '../store/createActionBinder'
+import {isCanvasResource, isDatasetResource, isMediaLibraryResource} from '../config/sanityConfig'
+import {bindActionByResource, type BoundResourceKey} from '../store/createActionBinder'
 import {createStateSourceAction, type SelectorContext} from '../store/createStateSourceAction'
 import {defineStore, type StoreContext} from '../store/defineStore'
 import {type SanityUser} from '../users/types'
@@ -23,27 +23,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
+
+    // Presence is only supported for dataset resources
+    if (isMediaLibraryResource(resource)) {
+      throw new Error(
+        'Presence is not supported for media library resources. Presence tracking requires a dataset resource with a projectId.',
+      )
+    }
+
+    if (isCanvasResource(resource)) {
+      throw new Error(
+        'Presence is not supported for canvas resources. Presence tracking requires a dataset resource with a projectId.',
+      )
+    }
+
     const sessionId = crypto.randomUUID()
 
     const client = getClient(instance, {
       apiVersion: '2022-06-30',
-      projectId,
-      dataset,
+      resource,
     })
 
     const token$ = getTokenState(instance).observable.pipe(distinctUntilChanged())
 
     const [incomingEvents$, dispatch] = createBifurTransport({
-      client: client as SanityClient,
+      client,
       token$,
       sessionId,
     })
@@ -114,13 +127,13 @@ const selectPresence = createSelector(
   },
 )
 
-/** @public */
-export const getPresence = bindActionByDataset(
+/** @beta */
+export 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 userIds$ = context.state.observable.pipe(
         map((state) =>
           Array.from(state.locations.values())
@@ -140,7 +153,10 @@ export const getPresence = bindActionByDataset(
               getUserState(context.instance, {
                 userId,
                 resourceType: 'project',
-                projectId: context.key.projectId,
+                projectId:
+                  context.key.resource && isDatasetResource(context.key.resource)
+                    ? context.key.resource.projectId
+                    : undefined,
               }).pipe(filter((v): v is NonNullable<typeof v> => !!v)),
             )
             return combineLatest(userObservables)

package/src/preview/previewProjectionUtils.test.ts

@@ -0,0 +1,192 @@
+import {type SanityClient} from '@sanity/client'
+import {beforeEach, describe, expect, it, vi} from 'vitest'
+
+import {createSanityInstance} from '../store/createSanityInstance'
+import {normalizeMedia, transformProjectionToPreview} from './previewProjectionUtils'
+import {type PreviewQueryResult} from './types'
+
+// Mock the getClient function
+vi.mock('../client/clientStore', () => ({
+  getClient: vi.fn(),
+}))
+
+const mockClient = {
+  config: () => ({projectId: 'test-project', dataset: 'test-dataset'}),
+} as unknown as SanityClient
+
+describe('normalizeMedia', () => {
+  beforeEach(async () => {
+    vi.clearAllMocks()
+  })
+
+  it('returns null if media is null or undefined', () => {
+    expect(normalizeMedia(null, mockClient)).toBeNull()
+    expect(normalizeMedia(undefined, mockClient)).toBeNull()
+  })
+
+  it('returns null if media does not have a valid asset', () => {
+    const invalidMedia1 = {media: {_ref: 'image-abc123-200x200-png'}} // Missing `asset` property
+    const invalidMedia2 = {asset: {ref: 'image-abc123-200x200-png'}} // Incorrect property name `ref`
+    expect(normalizeMedia(invalidMedia1, mockClient)).toBeNull()
+    expect(normalizeMedia(invalidMedia2, mockClient)).toBeNull()
+  })
+
+  it('returns null if media is not an object', () => {
+    expect(normalizeMedia(123, mockClient)).toBeNull()
+    expect(normalizeMedia('invalid', mockClient)).toBeNull()
+  })
+
+  it('returns a normalized URL for valid image asset objects', () => {
+    const validMedia = {type: 'image-asset', _ref: 'image-abc123-200x200-png'}
+    const result = normalizeMedia(validMedia, mockClient)
+    expect(result).toEqual({
+      type: 'image-asset',
+      _ref: 'image-abc123-200x200-png',
+      url: 'https://cdn.sanity.io/images/test-project/test-dataset/abc123-200x200.png',
+    })
+  })
+
+  it('handles image assets with expected URL format', () => {
+    const media = {type: 'image-asset', _ref: 'image-xyz456-400x400-jpg'}
+    const result = normalizeMedia(media, mockClient)
+    expect(result).toEqual({
+      type: 'image-asset',
+      _ref: 'image-xyz456-400x400-jpg',
+      url: 'https://cdn.sanity.io/images/test-project/test-dataset/xyz456-400x400.jpg',
+    })
+  })
+})
+
+describe('transformProjectionToPreview', () => {
+  const instance = createSanityInstance()
+
+  beforeEach(async () => {
+    vi.clearAllMocks()
+
+    // Mock getClient to return our mock client
+    const {getClient} = await import('../client/clientStore')
+    vi.mocked(getClient).mockReturnValue(mockClient)
+  })
+
+  it('transforms projection result with title and subtitle', () => {
+    const projectionResult: PreviewQueryResult = {
+      _id: 'doc1',
+      _type: 'article',
+      _updatedAt: '2026-01-01',
+      titleCandidates: {title: 'My Title'},
+      subtitleCandidates: {description: 'My Description'},
+      media: null,
+    }
+
+    const result = transformProjectionToPreview(
+      instance,
+      {projectId: 'p', dataset: 'd'},
+      projectionResult,
+    )
+
+    expect(result).toEqual({
+      title: 'My Title',
+      subtitle: 'My Description',
+      media: null,
+    })
+  })
+
+  it('uses fallback title when no title candidates exist', () => {
+    const projectionResult: PreviewQueryResult = {
+      _id: 'doc1',
+      _type: 'article',
+      _updatedAt: '2026-01-01',
+      titleCandidates: {},
+      subtitleCandidates: {},
+      media: null,
+    }
+
+    const result = transformProjectionToPreview(
+      instance,
+      {projectId: 'p', dataset: 'd'},
+      projectionResult,
+    )
+
+    expect(result.title).toBe('article: doc1')
+    expect(result.subtitle).toBeUndefined()
+  })
+
+  it('transforms projection result with media', () => {
+    const projectionResult: PreviewQueryResult = {
+      _id: 'doc1',
+      _type: 'article',
+      _updatedAt: '2026-01-01',
+      titleCandidates: {title: 'My Title'},
+      subtitleCandidates: {},
+      media: {type: 'image-asset', _ref: 'image-abc123-200x200-png', url: ''},
+    }
+
+    const result = transformProjectionToPreview(
+      instance,
+      {projectId: 'p', dataset: 'd'},
+      projectionResult,
+    )
+
+    expect(result).toEqual({
+      title: 'My Title',
+      subtitle: undefined,
+      media: {
+        type: 'image-asset',
+        _ref: 'image-abc123-200x200-png',
+        url: 'https://cdn.sanity.io/images/test-project/test-dataset/abc123-200x200.png',
+      },
+    })
+  })
+
+  it('includes status when provided', () => {
+    const projectionResult: PreviewQueryResult = {
+      _id: 'doc1',
+      _type: 'article',
+      _updatedAt: '2026-01-01',
+      titleCandidates: {title: 'My Title'},
+      subtitleCandidates: {},
+      media: null,
+      _status: {
+        lastEditedPublishedAt: '2026-01-01',
+        lastEditedDraftAt: '2026-01-02',
+      },
+    }
+
+    const result = transformProjectionToPreview(
+      instance,
+      {projectId: 'p', dataset: 'd'},
+      projectionResult,
+    )
+
+    expect(result).toEqual({
+      title: 'My Title',
+      subtitle: undefined,
+      media: null,
+      _status: {
+        lastEditedPublishedAt: '2026-01-01',
+        lastEditedDraftAt: '2026-01-02',
+      },
+    })
+  })
+
+  it('calls getClient with the provided resource', async () => {
+    const projectionResult: PreviewQueryResult = {
+      _id: 'doc1',
+      _type: 'article',
+      _updatedAt: '2026-01-01',
+      titleCandidates: {title: 'My Title'},
+      subtitleCandidates: {},
+      media: null,
+    }
+
+    const resource = {mediaLibraryId: 'test-library'}
+
+    transformProjectionToPreview(instance, resource, projectionResult)
+
+    const {getClient} = await import('../client/clientStore')
+    expect(getClient).toHaveBeenCalledWith(instance, {
+      apiVersion: 'v2025-05-06',
+      resource,
+    })
+  })
+})

package/src/preview/previewProjectionUtils.ts

@@ -0,0 +1,88 @@
+import {type SanityClient} from '@sanity/client'
+import {createImageUrlBuilder} from '@sanity/image-url'
+import {isObject} from 'lodash-es'
+
+import {getClient} from '../client/clientStore'
+import {type DocumentResource} from '../config/sanityConfig'
+import {type SanityInstance} from '../store/createSanityInstance'
+import {SUBTITLE_CANDIDATES, TITLE_CANDIDATES} from './previewConstants'
+import {type PreviewQueryResult, type PreviewValue} from './types'
+
+const API_VERSION = 'v2025-05-06'
+
+/**
+ * Checks if the provided value has `_ref` property that is a string and starts with `image-`
+ */
+function hasImageRef<T>(value: unknown): value is T & {_ref: string} {
+  return isObject(value) && '_ref' in value && typeof (value as {_ref: unknown})._ref === 'string'
+}
+
+/**
+ * Normalizes a media asset to a preview value.
+ * Adds a url to a media asset reference using `@sanity/image-url`.
+ *
+ * @internal
+ */
+export function normalizeMedia(media: unknown, client: SanityClient): PreviewValue['media'] {
+  if (!media) return null
+  if (!hasImageRef(media)) return null
+
+  const builder = createImageUrlBuilder(client)
+  const url = builder.image({_ref: media._ref}).url()
+
+  return {
+    type: 'image-asset',
+    _ref: media._ref,
+    url,
+  }
+}
+
+/**
+ * Finds a single field value from a set of candidates based on a priority list of field names.
+ * Returns the first non-empty string value found from the candidates matching the priority list order.
+ *
+ * @internal
+ */
+function findFirstDefined(
+  fieldsToSearch: string[],
+  candidates: Record<string, unknown>,
+  exclude?: unknown,
+): string | undefined {
+  if (!candidates) return undefined
+
+  for (const field of fieldsToSearch) {
+    const value = candidates[field]
+    if (typeof value === 'string' && value.trim() !== '' && value !== exclude) {
+      return value
+    }
+  }
+
+  return undefined
+}
+
+/**
+ * Transforms a projection result (with titleCandidates, subtitleCandidates, media)
+ * into a PreviewValue (with title, subtitle, media).
+ *
+ * @param projectionResult - The raw projection result from GROQ
+ * @param instance - The Sanity instance to use for client configuration
+ * @param resource - Data resource for the preview
+ * @internal
+ */
+export function transformProjectionToPreview(
+  instance: SanityInstance,
+  resource: DocumentResource,
+  projectionResult: PreviewQueryResult,
+): PreviewValue {
+  const title = findFirstDefined(TITLE_CANDIDATES, projectionResult.titleCandidates)
+  const subtitle = findFirstDefined(SUBTITLE_CANDIDATES, projectionResult.subtitleCandidates, title)
+
+  const client = getClient(instance, {apiVersion: API_VERSION, resource})
+
+  return {
+    title: String(title || `${projectionResult._type}: ${projectionResult._id}`),
+    subtitle: subtitle || undefined,
+    media: normalizeMedia(projectionResult.media, client),
+    ...(projectionResult._status && {_status: projectionResult._status}),
+  }
+}

package/src/preview/{previewStore.ts → types.ts}

@@ -1,7 +1,9 @@
-import {type BoundDatasetKey} from '../store/createActionBinder'
-import {defineStore} from '../store/defineStore'
-import {subscribeToStateAndFetchBatches} from './subscribeToStateAndFetchBatches'
+import {type DocumentStatus} from '../projection/types'
 
+/**
+ *
+ * @internal
+ */
 export interface PreviewQueryResult {
   _id: string
   _type: string
@@ -9,6 +11,7 @@ export interface PreviewQueryResult {
   titleCandidates: Record<string, unknown>
   subtitleCandidates: Record<string, unknown>
   media?: PreviewMedia | null
+  _status?: DocumentStatus
 }
 
 /**
@@ -71,25 +74,3 @@ export type ValuePending<T> = {
   data: T | null
   isPending: boolean
 }
-
-/**
- * @public
- */
-export interface PreviewStoreState {
-  values: {[TDocumentId in string]?: ValuePending<PreviewValue>}
-  subscriptions: {[TDocumentId in string]?: {[TSubscriptionId in string]?: true}}
-}
-
-export const previewStore = defineStore<PreviewStoreState, BoundDatasetKey>({
-  name: 'Preview',
-  getInitialState() {
-    return {
-      subscriptions: {},
-      values: {},
-    }
-  },
-  initialize: (context) => {
-    const subscription = subscribeToStateAndFetchBatches(context)
-    return () => subscription.unsubscribe
-  },
-})

package/src/project/project.test.ts

@@ -11,7 +11,7 @@ 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'})
+    const instance = createSanityInstance()
 
     const project = {id: 'a'}
     const getById = vi.fn().mockReturnValue(of(project))

package/src/project/project.ts

@@ -1,38 +1,32 @@
 import {switchMap} from 'rxjs'
 
 import {getClientState} from '../client/clientStore'
-import {type ProjectHandle} from '../config/sanityConfig'
 import {createFetcherStore} from '../utils/createFetcherStore'
 
 const API_VERSION = 'v2025-02-19'
 
+/** @public */
+export type ProjectHandle = {
+  projectId: string
+}
 const project = createFetcherStore({
   name: 'Project',
-  getKey: (instance, options?: ProjectHandle) => {
-    const projectId = options?.projectId ?? instance.config.projectId
+  getKey: (_instance, options: ProjectHandle) => {
+    const projectId = options?.projectId
     if (!projectId) {
       throw new Error('A projectId is required to use the project API.')
     }
     return projectId
   },
-  fetcher:
-    (instance) =>
-    (options: ProjectHandle = {}) => {
-      const projectId = options.projectId ?? instance.config.projectId
+  fetcher: (instance) => (options: ProjectHandle) => {
+    const projectId = options.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)!,
-          ),
-        ),
-      )
-    },
+    return getClientState(instance, {
+      apiVersion: API_VERSION,
+      scope: 'global',
+      projectId,
+    }).observable.pipe(switchMap((client) => client.observable.projects.getById(projectId!)))
+  },
 })
 
 /** @public */

package/src/projection/getProjectionState.test.ts

@@ -1,6 +1,7 @@
 import {NEVER} from 'rxjs'
 import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest'
 
+import {type DocumentResource} from '../config/sanityConfig'
 import {createSanityInstance, type SanityInstance} from '../store/createSanityInstance'
 import {type StoreState} from '../store/createStoreState'
 import {hashString} from '../utils/hashString'
@@ -30,7 +31,8 @@ vi.mock('./subscribeToStateAndFetchBatches.ts')
 
 describe('getProjectionState', () => {
   let instance: SanityInstance
-  const docHandle = {documentId: 'exampleId', documentType: 'exampleType'}
+  const resource: DocumentResource = {projectId: 'p', dataset: 'd'}
+  const docHandle = {documentId: 'exampleId', documentType: 'exampleType', resource}
   const projection1 = '{exampleProjection1}'
   const hash1 = hashString(projection1)
   const projection2 = '{exampleProjection2}'
@@ -48,7 +50,7 @@ describe('getProjectionState', () => {
       return NEVER.subscribe()
     })
 
-    instance = createSanityInstance({projectId: 'exampleProject', dataset: 'exampleDataset'})
+    instance = createSanityInstance()
     vi.useFakeTimers() // Enable fake timers for each test
   })
 

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,
@@ -25,24 +24,6 @@ export interface ProjectionOptions<
   projection: TProjection
 }
 
-/**
- * @beta
- */
-export function getProjectionState<
-  TProjection extends string = string,
-  TDocumentType extends string = string,
-  TDataset extends string = string,
-  TProjectId extends string = string,
->(
-  instance: SanityInstance,
-  options: ProjectionOptions<TProjection, TDocumentType, TDataset, TProjectId>,
-): StateSource<
-  | ProjectionValuePending<
-      SanityProjectionResult<TProjection, TDocumentType, `${TProjectId}.${TDataset}`>
-    >
-  | undefined
->
-
 /**
  * @beta
  */
@@ -71,7 +52,7 @@ export function getProjectionState(
 /**
  * @beta
  */
-export const _getProjectionState = bindActionBySourceAndPerspective(
+export const _getProjectionState = bindActionByResourceAndPerspective(
   projectionStore,
   createStateSourceAction({
     selector: (

package/src/projection/projectionQuery.ts

@@ -1,7 +1,6 @@
-import {type ClientPerspective} from '@sanity/client'
 import {DocumentId} from '@sanity/id-utils'
 
-import {type ReleasePerspective} from '../config/sanityConfig'
+import {type PerspectiveHandle} from '../config/sanityConfig'
 import {getPublishedId} from '../utils/ids'
 import {
   type DocumentProjections,
@@ -68,7 +67,7 @@ interface ProcessProjectionQueryOptions {
   ids: Set<string>
   results: ProjectionQueryResult[]
   documentStatuses?: ProjectionStoreState['documentStatuses']
-  perspective: ClientPerspective | ReleasePerspective
+  perspective: NonNullable<PerspectiveHandle['perspective']>
 }
 
 export function processProjectionQuery({