@sanity/sdk 2.3.1 → 2.5.0

package/src/auth/utils.ts

@@ -1,3 +1,4 @@
+import {type ClientError} from '@sanity/client'
 import {EMPTY, fromEvent, Observable} from 'rxjs'
 
 import {AUTH_CODE_PARAM, DEFAULT_BASE} from './authConstants'
@@ -134,3 +135,38 @@ export function getCleanedUrl(locationUrl: string): string {
   loc.searchParams.delete('url')
   return loc.toString()
 }
+
+// -----------------------------------------------------------------------------
+// ClientError helpers (shared)
+// -----------------------------------------------------------------------------
+
+/** @internal */
+export type ApiErrorBody = {
+  error?: {type?: string; description?: string}
+  type?: string
+  description?: string
+  message?: string
+}
+
+/** @internal Extracts the structured API error body from a ClientError, if present. */
+export function getClientErrorApiBody(error: ClientError): ApiErrorBody | undefined {
+  const body: unknown = (error as ClientError).response?.body
+  return body && typeof body === 'object' ? (body as ApiErrorBody) : undefined
+}
+
+/** @internal Returns the error type string from an API error body, if available. */
+export function getClientErrorApiType(error: ClientError): string | undefined {
+  const body = getClientErrorApiBody(error)
+  return body?.error?.type ?? body?.type
+}
+
+/** @internal Returns the error description string from an API error body, if available. */
+export function getClientErrorApiDescription(error: ClientError): string | undefined {
+  const body = getClientErrorApiBody(error)
+  return body?.error?.description ?? body?.description
+}
+
+/** @internal True if the error represents a projectUserNotFoundError. */
+export function isProjectUserNotFoundClientError(error: ClientError): boolean {
+  return getClientErrorApiType(error) === 'projectUserNotFoundError'
+}

package/src/client/clientStore.test.ts

@@ -3,6 +3,7 @@ import {Subject} from 'rxjs'
 import {beforeEach, describe, expect, it, vi} from 'vitest'
 
 import {getAuthMethodState, getTokenState} from '../auth/authStore'
+import {canvasSource, datasetSource, mediaLibrarySource} from '../config/sanityConfig'
 import {createSanityInstance, type SanityInstance} from '../store/createSanityInstance'
 import {getClient, getClientState} from './clientStore'
 
@@ -75,6 +76,20 @@ describe('clientStore', () => {
       ).toThrowError(/unsupported properties: illegalKey/)
     })
 
+    it('should throw a helpful error when called without options', () => {
+      expect(() =>
+        // @ts-expect-error Testing missing options
+        getClient(instance, undefined),
+      ).toThrowError(/requires a configuration object with at least an "apiVersion" property/)
+    })
+
+    it('should throw a helpful error when called with null options', () => {
+      expect(() =>
+        // @ts-expect-error Testing null options
+        getClient(instance, null),
+      ).toThrowError(/requires a configuration object with at least an "apiVersion" property/)
+    })
+
     it('should reuse clients with identical configurations', () => {
       const options = {apiVersion: '2024-11-12', useCdn: true}
       const client1 = getClient(instance, options)
@@ -158,4 +173,140 @@ describe('clientStore', () => {
       subscription.unsubscribe()
     })
   })
+
+  describe('source handling', () => {
+    it('should create client when source is provided', () => {
+      const source = datasetSource('source-project', 'source-dataset')
+      const client = getClient(instance, {apiVersion: '2024-11-12', source})
+
+      expect(vi.mocked(createClient)).toHaveBeenCalledWith(
+        expect.objectContaining({
+          apiVersion: '2024-11-12',
+          source: expect.objectContaining({
+            __sanity_internal_sourceId: {
+              projectId: 'source-project',
+              dataset: 'source-dataset',
+            },
+          }),
+        }),
+      )
+      // Client should be projectless - no projectId/dataset in config
+      expect(client.config()).not.toHaveProperty('projectId')
+      expect(client.config()).not.toHaveProperty('dataset')
+      expect(client.config()).toEqual(
+        expect.objectContaining({
+          source: expect.objectContaining({
+            __sanity_internal_sourceId: {
+              projectId: 'source-project',
+              dataset: 'source-dataset',
+            },
+          }),
+        }),
+      )
+    })
+
+    it('should create resource when source has array sourceId and be projectless', () => {
+      const source = mediaLibrarySource('media-lib-123')
+      const client = getClient(instance, {apiVersion: '2024-11-12', source})
+
+      expect(vi.mocked(createClient)).toHaveBeenCalledWith(
+        expect.objectContaining({
+          '~experimental_resource': {type: 'media-library', id: 'media-lib-123'},
+          'apiVersion': '2024-11-12',
+        }),
+      )
+      // Client should be projectless - no projectId/dataset in config
+      expect(client.config()).not.toHaveProperty('projectId')
+      expect(client.config()).not.toHaveProperty('dataset')
+      expect(client.config()).toEqual(
+        expect.objectContaining({
+          '~experimental_resource': {type: 'media-library', id: 'media-lib-123'},
+        }),
+      )
+    })
+
+    it('should create resource when canvas source is provided and be projectless', () => {
+      const source = canvasSource('canvas-123')
+      const client = getClient(instance, {apiVersion: '2024-11-12', source})
+
+      expect(vi.mocked(createClient)).toHaveBeenCalledWith(
+        expect.objectContaining({
+          '~experimental_resource': {type: 'canvas', id: 'canvas-123'},
+          'apiVersion': '2024-11-12',
+        }),
+      )
+      // Client should be projectless - no projectId/dataset in config
+      expect(client.config()).not.toHaveProperty('projectId')
+      expect(client.config()).not.toHaveProperty('dataset')
+      expect(client.config()).toEqual(
+        expect.objectContaining({
+          '~experimental_resource': {type: 'canvas', id: 'canvas-123'},
+        }),
+      )
+    })
+
+    it('should create projectless client when source is provided, ignoring instance config', () => {
+      const source = datasetSource('source-project', 'source-dataset')
+      const client = getClient(instance, {apiVersion: '2024-11-12', source})
+
+      // Client should be projectless - source takes precedence, instance config is ignored
+      expect(client.config()).not.toHaveProperty('projectId')
+      expect(client.config()).not.toHaveProperty('dataset')
+      expect(client.config()).toEqual(
+        expect.objectContaining({
+          source: expect.objectContaining({
+            __sanity_internal_sourceId: {
+              projectId: 'source-project',
+              dataset: 'source-dataset',
+            },
+          }),
+        }),
+      )
+    })
+
+    it('should warn when both source and explicit projectId/dataset are provided', () => {
+      const consoleSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+      const source = datasetSource('source-project', 'source-dataset')
+      const client = getClient(instance, {
+        apiVersion: '2024-11-12',
+        source,
+        projectId: 'explicit-project',
+        dataset: 'explicit-dataset',
+      })
+
+      expect(consoleSpy).toHaveBeenCalledWith(
+        'Both source and explicit projectId/dataset are provided. The source will be used and projectId/dataset will be ignored.',
+      )
+      // Client should still be projectless despite explicit projectId/dataset
+      expect(client.config()).not.toHaveProperty('projectId')
+      expect(client.config()).not.toHaveProperty('dataset')
+      consoleSpy.mockRestore()
+    })
+
+    it('should create different clients for different sources', () => {
+      const source1 = datasetSource('project-1', 'dataset-1')
+      const source2 = datasetSource('project-2', 'dataset-2')
+      const source3 = mediaLibrarySource('media-lib-1')
+
+      const client1 = getClient(instance, {apiVersion: '2024-11-12', source: source1})
+      const client2 = getClient(instance, {apiVersion: '2024-11-12', source: source2})
+      const client3 = getClient(instance, {apiVersion: '2024-11-12', source: source3})
+
+      expect(client1).not.toBe(client2)
+      expect(client2).not.toBe(client3)
+      expect(client1).not.toBe(client3)
+      expect(vi.mocked(createClient)).toHaveBeenCalledTimes(3)
+    })
+
+    it('should reuse clients with identical source configurations', () => {
+      const source = datasetSource('same-project', 'same-dataset')
+      const options = {apiVersion: '2024-11-12', source}
+
+      const client1 = getClient(instance, options)
+      const client2 = getClient(instance, options)
+
+      expect(client1).toBe(client2)
+      expect(vi.mocked(createClient)).toHaveBeenCalledTimes(1)
+    })
+  })
 })

package/src/client/clientStore.ts

@@ -2,6 +2,7 @@ import {type ClientConfig, createClient, type SanityClient} from '@sanity/client
 import {pick} from 'lodash-es'
 
 import {getAuthMethodState, getTokenState} from '../auth/authStore'
+import {type DocumentSource, SOURCE_ID} from '../config/sanityConfig'
 import {bindActionGlobally} from '../store/createActionBinder'
 import {createStateSourceAction} from '../store/createStateSourceAction'
 import {defineStore, type StoreContext} from '../store/defineStore'
@@ -39,6 +40,7 @@ const allowedKeys = Object.keys({
   'requestTagPrefix': null,
   'useProjectHostname': null,
   '~experimental_resource': null,
+  'source': null,
 } satisfies Record<keyof ClientOptions, null>) as (keyof ClientOptions)[]
 
 const DEFAULT_CLIENT_CONFIG: ClientConfig = {
@@ -90,6 +92,11 @@ export interface ClientOptions extends Pick<ClientConfig, AllowedClientConfigKey
    * @internal
    */
   '~experimental_resource'?: ClientConfig['~experimental_resource']
+
+  /**
+   * @internal
+   */
+  'source'?: DocumentSource
 }
 
 const clientStore = defineStore<ClientStoreState>({
@@ -142,6 +149,13 @@ const getClientConfigKey = (options: ClientOptions) => JSON.stringify(pick(optio
 export const getClient = bindActionGlobally(
   clientStore,
   ({state, instance}, options: ClientOptions) => {
+    if (!options || typeof options !== 'object') {
+      throw new Error(
+        'getClient() requires a configuration object with at least an "apiVersion" property. ' +
+          'Example: getClient(instance, { apiVersion: "2024-11-12" })',
+      )
+    }
+
     // Check for disallowed keys
     const providedKeys = Object.keys(options) as (keyof ClientOptions)[]
     const disallowedKeys = providedKeys.filter((key) => !allowedKeys.includes(key))
@@ -156,18 +170,42 @@ export const getClient = bindActionGlobally(
 
     const tokenFromState = state.get().token
     const {clients, authMethod} = state.get()
+    const hasSource = !!options.source
+    let sourceId = options.source?.[SOURCE_ID]
+
+    let resource
+    if (Array.isArray(sourceId)) {
+      resource = {type: sourceId[0], id: sourceId[1]}
+      sourceId = undefined
+    }
+
     const projectId = options.projectId ?? instance.config.projectId
     const dataset = options.dataset ?? instance.config.dataset
     const apiHost = options.apiHost ?? instance.config.auth?.apiHost
 
     const effectiveOptions: ClientOptions = {
       ...DEFAULT_CLIENT_CONFIG,
-      ...((options.scope === 'global' || !projectId) && {useProjectHostname: false}),
+      ...((options.scope === 'global' || !projectId || hasSource) && {useProjectHostname: false}),
       token: authMethod === 'cookie' ? undefined : (tokenFromState ?? undefined),
       ...options,
       ...(projectId && {projectId}),
       ...(dataset && {dataset}),
       ...(apiHost && {apiHost}),
+      ...(resource && {'~experimental_resource': resource}),
+    }
+
+    // When a source is provided, don't use projectId/dataset - the client should be "projectless"
+    // The client code itself will ignore the non-source config, so we do this to prevent confusing the user.
+    // (ref: https://github.com/sanity-io/client/blob/5c23f81f5ab93a53f5b22b39845c867988508d84/src/data/dataMethods.ts#L691)
+    if (hasSource) {
+      if (options.projectId || options.dataset) {
+        // eslint-disable-next-line no-console
+        console.warn(
+          'Both source and explicit projectId/dataset are provided. The source will be used and projectId/dataset will be ignored.',
+        )
+      }
+      delete effectiveOptions.projectId
+      delete effectiveOptions.dataset
     }
 
     if (effectiveOptions.token === null || typeof effectiveOptions.token === 'undefined') {

package/src/comlink/controller/actions/destroyController.test.ts

@@ -39,7 +39,7 @@ describe('destroyController', () => {
     })
 
     // Execute action
-    destroyController({state, instance})
+    destroyController({state, instance, key: null})
 
     // Verify controller was destroyed and state was cleared
     expect(mockController.destroy).toHaveBeenCalled()
@@ -49,7 +49,7 @@ describe('destroyController', () => {
 
   it('should do nothing if no controller exists', () => {
     // State already has null controller, so just execute action
-    expect(() => destroyController({state, instance})).not.toThrow()
+    expect(() => destroyController({state, instance, key: null})).not.toThrow()
 
     // State should remain unchanged
     expect(state.get().controller).toBeNull()

package/src/comlink/controller/actions/getOrCreateChannel.test.ts

@@ -49,7 +49,7 @@ describe('getOrCreateChannel', () => {
   it('should create a new channel using the controller', () => {
     const createChannelSpy = vi.spyOn(mockController, 'createChannel')
 
-    const channel = getOrCreateChannel({state, instance}, channelConfig)
+    const channel = getOrCreateChannel({state, instance, key: null}, channelConfig)
 
     expect(createChannelSpy).toHaveBeenCalledWith(channelConfig)
     expect(channel.on).toBeDefined()
@@ -70,17 +70,17 @@ describe('getOrCreateChannel', () => {
       channels: new Map(),
     })
 
-    expect(() => getOrCreateChannel({state, instance}, channelConfig)).toThrow(
+    expect(() => getOrCreateChannel({state, instance, key: null}, channelConfig)).toThrow(
       'Controller must be initialized before using or creating channels',
     )
   })
 
   it('should retrieve channel directly from store once created', () => {
-    const createdChannel = getOrCreateChannel({state, instance}, channelConfig)
+    const createdChannel = getOrCreateChannel({state, instance, key: null}, channelConfig)
     vi.clearAllMocks() // Clear call counts
 
     // Retrieve channel again
-    const retrievedChannel = getOrCreateChannel({state, instance}, channelConfig)
+    const retrievedChannel = getOrCreateChannel({state, instance, key: null}, channelConfig)
     expect(retrievedChannel).toBeDefined()
     expect(retrievedChannel).toBe(createdChannel)
 
@@ -95,10 +95,10 @@ describe('getOrCreateChannel', () => {
   })
 
   it('should throw error when trying to create channel with different options', () => {
-    getOrCreateChannel({state, instance}, channelConfig)
+    getOrCreateChannel({state, instance, key: null}, channelConfig)
 
     expect(() =>
-      getOrCreateChannel({state, instance}, {...channelConfig, connectTo: 'window'}),
+      getOrCreateChannel({state, instance, key: null}, {...channelConfig, connectTo: 'window'}),
     ).toThrow('Channel "test" already exists with different options')
   })
 })

package/src/comlink/controller/actions/getOrCreateController.test.ts

@@ -43,7 +43,7 @@ describe('getOrCreateController', () => {
     const controllerSpy = vi.spyOn(comlink, 'createController')
     const targetOrigin = 'https://test.sanity.dev'
 
-    const controller = getOrCreateController({state, instance}, targetOrigin)
+    const controller = getOrCreateController({state, instance, key: null}, targetOrigin)
 
     expect(controllerSpy).toHaveBeenCalledWith({targetOrigin})
     expect(controller).toBeDefined()
@@ -56,8 +56,8 @@ describe('getOrCreateController', () => {
     const controllerSpy = vi.spyOn(comlink, 'createController')
     const targetOrigin = 'https://test.sanity.dev'
 
-    const firstController = getOrCreateController({state, instance}, targetOrigin)
-    const secondController = getOrCreateController({state, instance}, targetOrigin)
+    const firstController = getOrCreateController({state, instance, key: null}, targetOrigin)
+    const secondController = getOrCreateController({state, instance, key: null}, targetOrigin)
 
     expect(controllerSpy).toHaveBeenCalledTimes(1)
     expect(firstController).toBe(secondController)
@@ -68,9 +68,9 @@ describe('getOrCreateController', () => {
     const targetOrigin = 'https://test.sanity.dev'
     const targetOrigin2 = 'https://test2.sanity.dev'
 
-    const firstController = getOrCreateController({state, instance}, targetOrigin)
+    const firstController = getOrCreateController({state, instance, key: null}, targetOrigin)
     const destroySpy = vi.spyOn(firstController, 'destroy')
-    const secondController = getOrCreateController({state, instance}, targetOrigin2)
+    const secondController = getOrCreateController({state, instance, key: null}, targetOrigin2)
 
     expect(controllerSpy).toHaveBeenCalledTimes(2)
     expect(destroySpy).toHaveBeenCalled()

package/src/comlink/controller/actions/getOrCreateController.ts

@@ -21,7 +21,7 @@ export const getOrCreateController = (
   // if the target origin has changed, we'll create a new controller,
   // but need to clean up first
   if (controller) {
-    destroyController({state, instance})
+    destroyController({state, instance, key: undefined})
   }
 
   const newController = createController({targetOrigin})

package/src/comlink/controller/actions/releaseChannel.test.ts

@@ -19,6 +19,7 @@ const channelConfig = {
 describe('releaseChannel', () => {
   let instance: SanityInstance
   let store: StoreInstance<ComlinkControllerState>
+  const key = {name: 'global', projectId: 'test-project-id', dataset: 'test-dataset'}
 
   let getOrCreateChannel: (
     inst: SanityInstance,
@@ -29,14 +30,14 @@ describe('releaseChannel', () => {
 
   beforeEach(() => {
     instance = createSanityInstance({projectId: 'test-project-id', dataset: 'test-dataset'})
-    store = createStoreInstance(instance, comlinkControllerStore)
+    store = createStoreInstance(instance, key, comlinkControllerStore)
 
     const bind =
       <TParams extends unknown[], TReturn>(
         action: StoreAction<ComlinkControllerState, TParams, TReturn>,
       ) =>
       (inst: SanityInstance, ...params: TParams) =>
-        action({instance: inst, state: store.state}, ...params)
+        action({instance: inst, state: store.state, key}, ...params)
 
     getOrCreateChannel = bind(unboundGetOrCreateChannel)
     getOrCreateController = bind(unboundGetOrCreateController)

package/src/comlink/controller/comlinkControllerStore.test.ts

@@ -31,7 +31,7 @@ describe('comlinkControllerStore', () => {
 
     // Create store state directly
     const state = createStoreState<ComlinkControllerState>(
-      comlinkControllerStore.getInitialState(instance),
+      comlinkControllerStore.getInitialState(instance, null),
     )
 
     const initialState = state.get()
@@ -56,13 +56,13 @@ describe('comlinkControllerStore', () => {
     vi.mocked(bindActionGlobally).mockImplementation(
       (_storeDef, action) =>
         (inst: SanityInstance, ...params: unknown[]) =>
-          action({instance: inst, state}, ...params),
+          action({instance: inst, state, key: {name: 'global'}}, ...params),
     )
 
     const {comlinkControllerStore} = await import('./comlinkControllerStore')
 
     // Get the cleanup function from the store
-    const dispose = comlinkControllerStore.initialize?.({state, instance})
+    const dispose = comlinkControllerStore.initialize?.({state, instance, key: null})
 
     // Run cleanup
     dispose?.()
@@ -82,7 +82,7 @@ describe('comlinkControllerStore', () => {
     })
 
     // Get the cleanup function
-    const cleanup = comlinkControllerStore.initialize?.({state, instance})
+    const cleanup = comlinkControllerStore.initialize?.({state, instance, key: null})
 
     // Should not throw when no controller exists
     expect(() => cleanup?.()).not.toThrow()

package/src/comlink/node/actions/getOrCreateNode.test.ts

@@ -40,24 +40,24 @@ describe('getOrCreateNode', () => {
   })
 
   it('should create and start a node', () => {
-    const node = getOrCreateNode({state, instance}, nodeConfig)
+    const node = getOrCreateNode({state, instance, key: null}, nodeConfig)
 
     expect(comlink.createNode).toHaveBeenCalledWith(nodeConfig)
     expect(node.start).toHaveBeenCalled()
   })
 
   it('should store the node in nodeStore', () => {
-    const node = getOrCreateNode({state, instance}, nodeConfig)
+    const node = getOrCreateNode({state, instance, key: null}, nodeConfig)
 
-    expect(getOrCreateNode({state, instance}, nodeConfig)).toBe(node)
+    expect(getOrCreateNode({state, instance, key: null}, nodeConfig)).toBe(node)
   })
 
   it('should throw error when trying to create node with different options', () => {
-    getOrCreateNode({state, instance}, nodeConfig)
+    getOrCreateNode({state, instance, key: null}, nodeConfig)
 
     expect(() =>
       getOrCreateNode(
-        {state, instance},
+        {state, instance, key: null},
         {
           ...nodeConfig,
           connectTo: 'window',
@@ -74,7 +74,7 @@ describe('getOrCreateNode', () => {
       return statusUnsubMock
     })
 
-    getOrCreateNode({state, instance}, nodeConfig)
+    getOrCreateNode({state, instance, key: null}, nodeConfig)
 
     expect(mockNode.onStatus).toHaveBeenCalled()
     expect(state.get().nodes.get(nodeConfig.name)?.statusUnsub).toBe(statusUnsubMock)
@@ -92,7 +92,7 @@ describe('getOrCreateNode', () => {
       return statusUnsubMock
     })
 
-    getOrCreateNode({state, instance}, nodeConfig)
+    getOrCreateNode({state, instance, key: null}, nodeConfig)
 
     // Remove the node entry before triggering the status callback
     state.get().nodes.delete(nodeConfig.name)

package/src/comlink/node/actions/releaseNode.test.ts

@@ -47,7 +47,7 @@ describe('releaseNode', () => {
     expect(state.get().nodes.has('test-node')).toBe(true)
 
     // Release the node
-    releaseNode({state, instance}, 'test-node')
+    releaseNode({state, instance, key: null}, 'test-node')
 
     // Check node is removed
     expect(mockNode.stop).toHaveBeenCalled()
@@ -64,7 +64,7 @@ describe('releaseNode', () => {
     })
     state.set('setup', {nodes})
 
-    releaseNode({state, instance}, 'test-node')
+    releaseNode({state, instance, key: null}, 'test-node')
 
     expect(statusUnsub).toHaveBeenCalled()
   })

package/src/comlink/node/comlinkNodeStore.test.ts

@@ -14,7 +14,7 @@ describe('nodeStore', () => {
   })
 
   it('should have correct initial state', () => {
-    const initialState = comlinkNodeStore.getInitialState(instance)
+    const initialState = comlinkNodeStore.getInitialState(instance, null)
 
     expect(initialState.nodes).toBeInstanceOf(Map)
     expect(initialState.nodes.size).toBe(0)
@@ -25,16 +25,17 @@ describe('nodeStore', () => {
       stop: vi.fn(),
     } as unknown as Node<WindowMessage, FrameMessage>
 
-    const initialState = comlinkNodeStore.getInitialState(instance)
+    const initialState = comlinkNodeStore.getInitialState(instance, null)
     initialState.nodes.set('test-node', {
       options: {name: 'test-node', connectTo: 'parent'},
       node: mockNode,
-      refCount: 1,
+      status: 'idle',
     })
 
     const cleanup = comlinkNodeStore.initialize?.({
       instance,
       state: createStoreState(initialState),
+      key: null,
     })
 
     cleanup?.()

package/src/config/sanityConfig.ts

@@ -29,15 +29,14 @@ export interface PerspectiveHandle {
  * @public
  */
 export interface DatasetHandle<TDataset extends string = string, TProjectId extends string = string>
-  extends ProjectHandle<TProjectId>,
-    PerspectiveHandle {
+  extends ProjectHandle<TProjectId>, PerspectiveHandle {
   dataset?: TDataset
 }
 
 /**
  * Identifies a specific document type within a Sanity dataset and project.
  * Includes `projectId`, `dataset`, and `documentType`.
- * Optionally includes a `documentId`, useful for referencing a specific document type context, potentially without a specific document ID.
+ * Optionally includes a `documentId` and `liveEdit` flag.
  * @public
  */
 export interface DocumentTypeHandle<
@@ -47,6 +46,12 @@ export interface DocumentTypeHandle<
 > extends DatasetHandle<TDataset, TProjectId> {
   documentId?: string
   documentType: TDocumentType
+  /**
+   * Indicates whether this document uses liveEdit mode.
+   * When `true`, the document does not use the draft/published model and edits are applied directly to the document.
+   * @see https://www.sanity.io/docs/content-lake/drafts#ca0663a8f002
+   */
+  liveEdit?: boolean
 }
 
 /**
@@ -81,3 +86,44 @@ export interface SanityConfig extends DatasetHandle, PerspectiveHandle {
     enabled: boolean
   }
 }
+
+export const SOURCE_ID = '__sanity_internal_sourceId'
+
+/**
+ * A document source can be used for querying.
+ *
+ * @beta
+ * @see datasetSource Construct a document source for a given projectId and dataset.
+ * @see mediaLibrarySource Construct a document source for a mediaLibraryId.
+ * @see canvasSource Construct a document source for a canvasId.
+ */
+export type DocumentSource = {
+  [SOURCE_ID]: ['media-library', string] | ['canvas', string] | {projectId: string; dataset: string}
+}
+
+/**
+ * Returns a document source for a projectId and dataset.
+ *
+ * @beta
+ */
+export function datasetSource(projectId: string, dataset: string): DocumentSource {
+  return {[SOURCE_ID]: {projectId, dataset}}
+}
+
+/**
+ * Returns a document source for a Media Library.
+ *
+ * @beta
+ */
+export function mediaLibrarySource(id: string): DocumentSource {
+  return {[SOURCE_ID]: ['media-library', id]}
+}
+
+/**
+ * Returns a document source for a Canvas.
+ *
+ * @beta
+ */
+export function canvasSource(id: string): DocumentSource {
+  return {[SOURCE_ID]: ['canvas', id]}
+}

package/src/document/actions.test.ts

@@ -42,6 +42,40 @@ describe('document actions', () => {
         documentType: typeHandle.documentType,
       })
     })
+
+    it('creates a document action with initial values', () => {
+      const initialValue = {
+        title: 'Test Title',
+        author: 'John Doe',
+        count: 42,
+      }
+      const action = createDocument(dummyDocHandle, initialValue)
+      expect(action).toEqual({
+        type: 'document.create',
+        documentId: 'abc123',
+        documentType: dummyDocHandle.documentType,
+        initialValue,
+      })
+    })
+
+    it('creates a document action without initialValue when not provided', () => {
+      const action = createDocument(dummyDocHandle, undefined)
+      expect(action).toEqual({
+        type: 'document.create',
+        documentId: 'abc123',
+        documentType: dummyDocHandle.documentType,
+      })
+    })
+
+    it('creates a document action with empty initialValue object', () => {
+      const action = createDocument(dummyDocHandle, {})
+      expect(action).toEqual({
+        type: 'document.create',
+        documentId: 'abc123',
+        documentType: dummyDocHandle.documentType,
+        initialValue: {},
+      })
+    })
   })
 
   describe('deleteDocument', () => {