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

package/src/presence/presenceStore.ts

@@ -1,20 +1,45 @@
 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 {isCanvasResource, isDatasetResource, isMediaLibraryResource} from '../config/sanityConfig'
+import {
+  type DocumentResource,
+  isCanvasResource,
+  isDatasetResource,
+  isMediaLibraryResource,
+} from '../config/sanityConfig'
 import {bindActionByResource, type BoundResourceKey} from '../store/createActionBinder'
-import {createStateSourceAction, type SelectorContext} from '../store/createStateSourceAction'
+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 => ({
@@ -33,25 +58,25 @@ export const presenceStore = defineStore<PresenceStoreState, BoundResourceKey>({
       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.',
-      )
+      throw new Error('Presence is not supported for media library resources.')
     }
 
     const sessionId = crypto.randomUUID()
 
-    const client = getClient(instance, {
-      apiVersion: '2022-06-30',
-      resource,
-    })
+    // 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())
 
@@ -94,6 +119,22 @@ export const presenceStore = defineStore<PresenceStoreState, BoundResourceKey>({
 
     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()
@@ -127,13 +168,13 @@ const selectPresence = createSelector(
   },
 )
 
-/** @beta */
-export const getPresence = bindActionByResource(
+const _getPresence = bindActionByResource(
   presenceStore,
   createStateSourceAction({
     selector: (context: SelectorContext<PresenceStoreState>): UserPresence[] =>
       selectPresence(context.state),
     onSubscribe: (context: StoreContext<PresenceStoreState, BoundResourceKey>) => {
+      const resource = context.key.resource
       const userIds$ = context.state.observable.pipe(
         map((state) =>
           Array.from(state.locations.values())
@@ -143,29 +184,34 @@ export const getPresence = bindActionByResource(
         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.resource && isDatasetResource(context.key.resource)
-                    ? context.key.resource.projectId
-                    : undefined,
+                ...(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: {
@@ -183,3 +229,13 @@ export const getPresence = bindActionByResource(
     },
   }),
 )
+
+/** @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.test.ts

@@ -0,0 +1,137 @@
+import {of} from 'rxjs'
+import {beforeEach, describe, expect, it, vi} from 'vitest'
+
+import {getProjectionState} from '../projection/getProjectionState'
+import {type ProjectionValuePending} from '../projection/types'
+import {createSanityInstance} from '../store/createSanityInstance'
+import {type StateSource} from '../store/createStateSourceAction'
+import {getPreviewState} from './getPreviewState'
+import {type PreviewQueryResult} from './types'
+
+vi.mock('../projection/getProjectionState')
+
+describe('getPreviewState', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  it('transforms projection result to preview format', () => {
+    const mockProjectionResult: PreviewQueryResult = {
+      _id: 'doc1',
+      _type: 'article',
+      _updatedAt: '2024-01-01',
+      titleCandidates: {title: 'Test Title'},
+      subtitleCandidates: {description: 'Test Description'},
+      media: null,
+    }
+
+    const mockProjectionState = {
+      getCurrent: vi.fn().mockReturnValue({
+        data: mockProjectionResult,
+        isPending: false,
+      } as ProjectionValuePending<PreviewQueryResult>),
+      subscribe: vi.fn(),
+      observable: of({
+        data: mockProjectionResult,
+        isPending: false,
+      } as ProjectionValuePending<PreviewQueryResult>),
+    }
+
+    vi.mocked(getProjectionState).mockReturnValue(
+      mockProjectionState as unknown as StateSource<
+        ProjectionValuePending<Record<string, unknown>> | undefined
+      >,
+    )
+
+    const instance = createSanityInstance({
+      projectId: 'test-project',
+      dataset: 'test-dataset',
+    })
+    const previewState = getPreviewState(instance, {
+      documentId: 'doc1',
+      documentType: 'article',
+    })
+
+    const result = previewState.getCurrent()
+
+    expect(result.data).toEqual({
+      title: 'Test Title',
+      subtitle: 'Test Description',
+      media: null,
+    })
+    expect(result.isPending).toBe(false)
+  })
+
+  it('returns null data when projection result is null', () => {
+    const mockProjectionState = {
+      getCurrent: vi.fn().mockReturnValue({
+        data: null,
+        isPending: true,
+      }),
+      subscribe: vi.fn(),
+      observable: of({data: null, isPending: true}),
+    }
+
+    vi.mocked(getProjectionState).mockReturnValue(mockProjectionState)
+
+    const instance = createSanityInstance({
+      projectId: 'test-project',
+      dataset: 'test-dataset',
+    })
+    const previewState = getPreviewState(instance, {
+      documentId: 'doc1',
+      documentType: 'article',
+    })
+
+    const result = previewState.getCurrent()
+
+    expect(result.data).toBeNull()
+    expect(result.isPending).toBe(true)
+  })
+
+  it('uses fallback title when no title candidates exist', () => {
+    const mockProjectionResult: PreviewQueryResult = {
+      _id: 'doc1',
+      _type: 'article',
+      _updatedAt: '2024-01-01',
+      titleCandidates: {},
+      subtitleCandidates: {},
+      media: null,
+    }
+
+    const mockProjectionState = {
+      getCurrent: vi.fn().mockReturnValue({
+        data: mockProjectionResult,
+        isPending: false,
+      } as ProjectionValuePending<PreviewQueryResult>),
+      subscribe: vi.fn(),
+      observable: of({
+        data: mockProjectionResult,
+        isPending: false,
+      } as ProjectionValuePending<PreviewQueryResult>),
+    }
+
+    vi.mocked(getProjectionState).mockReturnValue(
+      mockProjectionState as unknown as StateSource<
+        ProjectionValuePending<Record<string, unknown>> | undefined
+      >,
+    )
+
+    const instance = createSanityInstance({
+      projectId: 'test-project',
+      dataset: 'test-dataset',
+    })
+    const previewState = getPreviewState(instance, {
+      documentId: 'doc1',
+      documentType: 'article',
+    })
+
+    const result = previewState.getCurrent()
+
+    expect(result.data).toEqual({
+      title: 'article: doc1',
+      subtitle: undefined,
+      media: null,
+    })
+  })
+})

package/src/preview/getPreviewState.ts

@@ -0,0 +1,69 @@
+import {map} from 'rxjs'
+
+import {type DocumentHandle} from '../config/sanityConfig'
+import {getProjectionState} from '../projection/getProjectionState'
+import {type SanityInstance} from '../store/createSanityInstance'
+import {type StateSource} from '../store/createStateSourceAction'
+import {PREVIEW_PROJECTION} from './previewConstants'
+import {transformProjectionToPreview} from './previewProjectionUtils'
+import {type PreviewQueryResult, type PreviewValue, type ValuePending} from './types'
+
+/**
+ * @beta
+ * @deprecated This type is deprecated and will be removed in a future release.
+ */
+export type GetPreviewStateOptions = DocumentHandle
+
+/**
+ * @beta
+ * @deprecated This function is deprecated and will be removed in a future release.
+ */
+export function getPreviewState<TResult extends object>(
+  instance: SanityInstance,
+  options: GetPreviewStateOptions,
+): StateSource<ValuePending<TResult>>
+/**
+ * @beta
+ * @deprecated This function is deprecated and will be removed in a future release.
+ */
+export function getPreviewState(
+  instance: SanityInstance,
+  options: GetPreviewStateOptions,
+): StateSource<ValuePending<PreviewValue>>
+/**
+ * @beta
+ * @deprecated This function is deprecated and will be removed in a future release.
+ */
+export function getPreviewState(
+  instance: SanityInstance,
+  options: GetPreviewStateOptions,
+): StateSource<ValuePending<PreviewValue>> {
+  // Get the projection state
+  const projectionState = getProjectionState<PreviewQueryResult>(instance, {
+    ...options,
+    projection: PREVIEW_PROJECTION,
+  })
+
+  // Transform helper to convert projection result to preview format
+  const transformResult = (
+    current: ReturnType<typeof projectionState.getCurrent>,
+  ): ValuePending<PreviewValue> => {
+    if (!current || current.data === null) {
+      return {data: null, isPending: current?.isPending ?? false}
+    }
+
+    const previewValue = transformProjectionToPreview(instance, current.data, options.resource)
+
+    return {
+      data: previewValue,
+      isPending: current.isPending,
+    }
+  }
+
+  // Wrap the state source to transform projection results to preview format
+  return {
+    getCurrent: () => transformResult(projectionState.getCurrent()),
+    subscribe: (callback) => projectionState.subscribe(callback),
+    observable: projectionState.observable.pipe(map(transformResult)),
+  }
+}

package/src/preview/previewProjectionUtils.test.ts

@@ -58,7 +58,10 @@ describe('normalizeMedia', () => {
 })
 
 describe('transformProjectionToPreview', () => {
-  const instance = createSanityInstance()
+  const instance = createSanityInstance({
+    projectId: 'test-project',
+    dataset: 'test-dataset',
+  })
 
   beforeEach(async () => {
     vi.clearAllMocks()
@@ -78,11 +81,7 @@ describe('transformProjectionToPreview', () => {
       media: null,
     }
 
-    const result = transformProjectionToPreview(
-      instance,
-      {projectId: 'p', dataset: 'd'},
-      projectionResult,
-    )
+    const result = transformProjectionToPreview(instance, projectionResult)
 
     expect(result).toEqual({
       title: 'My Title',
@@ -101,11 +100,7 @@ describe('transformProjectionToPreview', () => {
       media: null,
     }
 
-    const result = transformProjectionToPreview(
-      instance,
-      {projectId: 'p', dataset: 'd'},
-      projectionResult,
-    )
+    const result = transformProjectionToPreview(instance, projectionResult)
 
     expect(result.title).toBe('article: doc1')
     expect(result.subtitle).toBeUndefined()
@@ -121,11 +116,7 @@ describe('transformProjectionToPreview', () => {
       media: {type: 'image-asset', _ref: 'image-abc123-200x200-png', url: ''},
     }
 
-    const result = transformProjectionToPreview(
-      instance,
-      {projectId: 'p', dataset: 'd'},
-      projectionResult,
-    )
+    const result = transformProjectionToPreview(instance, projectionResult)
 
     expect(result).toEqual({
       title: 'My Title',
@@ -152,11 +143,7 @@ describe('transformProjectionToPreview', () => {
       },
     }
 
-    const result = transformProjectionToPreview(
-      instance,
-      {projectId: 'p', dataset: 'd'},
-      projectionResult,
-    )
+    const result = transformProjectionToPreview(instance, projectionResult)
 
     expect(result).toEqual({
       title: 'My Title',
@@ -181,7 +168,7 @@ describe('transformProjectionToPreview', () => {
 
     const resource = {mediaLibraryId: 'test-library'}
 
-    transformProjectionToPreview(instance, resource, projectionResult)
+    transformProjectionToPreview(instance, projectionResult, resource)
 
     const {getClient} = await import('../client/clientStore')
     expect(getClient).toHaveBeenCalledWith(instance, {

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 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'
 
@@ -71,13 +71,17 @@ function findFirstDefined(
  */
 export function transformProjectionToPreview(
   instance: SanityInstance,
-  resource: DocumentResource,
   projectionResult: PreviewQueryResult,
+  resource?: DocumentResource,
 ): PreviewValue {
   const title = findFirstDefined(TITLE_CANDIDATES, projectionResult.titleCandidates)
   const subtitle = findFirstDefined(SUBTITLE_CANDIDATES, projectionResult.subtitleCandidates, title)
 
-  const client = getClient(instance, {apiVersion: API_VERSION, resource})
+  // Get a client for the resource (if provided) or use the instance config
+  const client = getClient(instance, {
+    apiVersion: API_VERSION,
+    resource,
+  })
 
   return {
     title: String(title || `${projectionResult._type}: ${projectionResult._id}`),

package/src/preview/resolvePreview.test.ts

@@ -0,0 +1,64 @@
+import {beforeEach, describe, expect, it, vi} from 'vitest'
+
+import {resolveProjection} from '../projection/resolveProjection'
+import {type ProjectionValuePending} from '../projection/types'
+import {createSanityInstance, type SanityInstance} from '../store/createSanityInstance'
+import {resolvePreview} from './resolvePreview'
+import {type PreviewQueryResult} from './types'
+
+vi.mock('../projection/resolveProjection')
+
+describe('resolvePreview', () => {
+  let instance: SanityInstance
+  beforeEach(() => {
+    vi.clearAllMocks()
+    instance = createSanityInstance({projectId: 'p', dataset: 'd'})
+  })
+
+  afterEach(() => {
+    instance.dispose()
+  })
+
+  it('resolves and transforms projection result to preview format', async () => {
+    const mockProjectionResult: PreviewQueryResult = {
+      _id: 'doc1',
+      _type: 'article',
+      _updatedAt: '2024-01-01',
+      titleCandidates: {title: 'Resolved Title'},
+      subtitleCandidates: {description: 'Resolved Description'},
+      media: null,
+    }
+
+    vi.mocked(resolveProjection).mockResolvedValue({
+      data: mockProjectionResult,
+      isPending: false,
+    } as ProjectionValuePending<PreviewQueryResult>)
+
+    const result = await resolvePreview(instance, {
+      documentId: 'doc1',
+      documentType: 'article',
+    })
+
+    expect(result.data).toEqual({
+      title: 'Resolved Title',
+      subtitle: 'Resolved Description',
+      media: null,
+    })
+    expect(result.isPending).toBe(false)
+  })
+
+  it('returns null data when projection resolves with null', async () => {
+    vi.mocked(resolveProjection).mockResolvedValue({
+      data: null,
+      isPending: false,
+    })
+
+    const result = await resolvePreview(instance, {
+      documentId: 'doc1',
+      documentType: 'article',
+    })
+
+    expect(result.data).toBeNull()
+    expect(result.isPending).toBe(false)
+  })
+})

package/src/preview/resolvePreview.ts

@@ -0,0 +1,43 @@
+import {type DocumentHandle} from '../config/sanityConfig'
+import {resolveProjection} from '../projection/resolveProjection'
+import {type SanityInstance} from '../store/createSanityInstance'
+import {PREVIEW_PROJECTION} from './previewConstants'
+import {transformProjectionToPreview} from './previewProjectionUtils'
+import {type PreviewQueryResult, type PreviewValue, type ValuePending} from './types'
+
+/**
+ * @beta
+ * @deprecated This type is deprecated and will be removed in a future release.
+ */
+export type ResolvePreviewOptions = DocumentHandle
+
+/**
+ * @beta
+ * @deprecated This function is deprecated and will be removed in a future release.
+ */
+export async function resolvePreview(
+  instance: SanityInstance,
+  options: ResolvePreviewOptions,
+): Promise<ValuePending<PreviewValue>> {
+  // Resolve the projection
+  const projectionResult = await resolveProjection<PreviewQueryResult>(instance, {
+    ...options,
+    projection: PREVIEW_PROJECTION,
+  })
+
+  if (!projectionResult.data) {
+    return {data: null, isPending: projectionResult.isPending}
+  }
+
+  // Transform to preview format
+  const previewValue = transformProjectionToPreview(
+    instance,
+    projectionResult.data,
+    options.resource,
+  )
+
+  return {
+    data: previewValue,
+    isPending: projectionResult.isPending,
+  }
+}

package/src/preview/types.ts

@@ -74,3 +74,13 @@ export type ValuePending<T> = {
   data: T | null
   isPending: boolean
 }
+
+/**
+ * @public
+ * @deprecated This interface is kept for backwards compatibility but is no longer used internally.
+ * Preview state is now stored in the projection store.
+ */
+export interface PreviewStoreState {
+  values: {[TDocumentId in string]?: ValuePending<PreviewValue>}
+  subscriptions: {[TDocumentId in string]?: {[TSubscriptionId in string]?: true}}
+}

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

@@ -0,0 +1,37 @@
+import {expectTypeOf, test} from 'vitest'
+
+import {type SanityInstance} from '../store/createSanityInstance'
+import {type StateSource} from '../store/createStateSourceAction'
+import {type FetcherSnapshot} from '../store/fetcherStore'
+import {type Project, project, type ProjectMember} from './project'
+
+const instance = {} as SanityInstance
+
+test('project.resolveState — resolves the wide-boolean detail shape', () => {
+  expectTypeOf(project.resolveState(instance, {projectId: 'p'})).resolves.toEqualTypeOf<
+    Project<boolean, boolean>
+  >()
+})
+
+test('Project — literal flags narrow members and features', () => {
+  expectTypeOf<Project<true, true>['members']>().toEqualTypeOf<ProjectMember[]>()
+  expectTypeOf<Project<true, true>['features']>().toEqualTypeOf<string[]>()
+  expectTypeOf<keyof Project<false, false> & ('members' | 'features')>().toEqualTypeOf<never>()
+})
+
+test('Project<boolean, boolean> — members and features are optional', () => {
+  type Item = Project<boolean, boolean>
+  expectTypeOf<Item['members']>().toEqualTypeOf<ProjectMember[] | undefined>()
+  expectTypeOf<Item['features']>().toEqualTypeOf<string[] | undefined>()
+})
+
+test('project.getState — exposes the snapshot envelope', () => {
+  expectTypeOf(project.getState(instance, {projectId: 'p'})).toEqualTypeOf<
+    StateSource<FetcherSnapshot<Project<boolean, boolean>>>
+  >()
+})
+
+test('project — rejects non-boolean flag values', () => {
+  // @ts-expect-error includeMembers must be a boolean
+  void project.resolveState(instance, {includeMembers: 'yes'})
+})