@sanity/sdk 2.3.1 → 2.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanity/sdk",
-  "version": "2.3.1",
+  "version": "2.4.0",
   "private": false,
   "description": "Sanity SDK",
   "keywords": [
@@ -61,20 +61,20 @@
   "devDependencies": {
     "@sanity/browserslist-config": "^1.0.5",
     "@sanity/pkg-utils": "^7.9.6",
-    "@sanity/prettier-config": "^1.0.3",
+    "@sanity/prettier-config": "^1.0.6",
     "@types/lodash-es": "^4.17.12",
-    "@vitest/coverage-v8": "3.1.2",
+    "@vitest/coverage-v8": "3.2.4",
     "eslint": "^9.22.0",
-    "prettier": "^3.5.3",
+    "prettier": "^3.7.3",
     "rollup-plugin-visualizer": "^5.14.0",
     "typescript": "^5.8.3",
     "vite": "^6.3.4",
-    "vitest": "^3.1.2",
-    "@repo/config-eslint": "0.0.0",
+    "vitest": "^3.2.4",
+    "@repo/config-test": "0.0.1",
     "@repo/package.bundle": "3.82.0",
-    "@repo/package.config": "0.0.1",
+    "@repo/config-eslint": "0.0.0",
     "@repo/tsconfig": "0.0.1",
-    "@repo/config-test": "0.0.1"
+    "@repo/package.config": "0.0.1"
   },
   "engines": {
     "node": ">=20.0.0"

package/src/_exports/index.ts

@@ -5,6 +5,25 @@ import {type SanityProject as _SanityProject} from '@sanity/client'
  */
 export type SanityProject = _SanityProject
 
+export type {
+  AgentGenerateOptions,
+  AgentGenerateResult,
+  AgentPatchOptions,
+  AgentPatchResult,
+  AgentPromptOptions,
+  AgentPromptResult,
+  AgentTransformOptions,
+  AgentTransformResult,
+  AgentTranslateOptions,
+  AgentTranslateResult,
+} from '../agent/agentActions'
+export {
+  agentGenerate,
+  agentPatch,
+  agentPrompt,
+  agentTransform,
+  agentTranslate,
+} from '../agent/agentActions'
 export {AuthStateType} from '../auth/authStateType'
 export {
   type AuthState,
@@ -24,6 +43,13 @@ export {
 export {observeOrganizationVerificationState} from '../auth/getOrganizationVerificationState'
 export {handleAuthCallback} from '../auth/handleAuthCallback'
 export {logout} from '../auth/logout'
+export {
+  type ApiErrorBody,
+  getClientErrorApiBody,
+  getClientErrorApiDescription,
+  getClientErrorApiType,
+  isProjectUserNotFoundClientError,
+} from '../auth/utils'
 export type {ClientStoreState as ClientState} from '../client/clientStore'
 export {type ClientOptions, getClient, getClientState} from '../client/clientStore'
 export {
@@ -50,9 +76,13 @@ export {
   createProjectHandle,
 } from '../config/handles'
 export {
+  canvasSource,
   type DatasetHandle,
+  datasetSource,
   type DocumentHandle,
+  type DocumentSource,
   type DocumentTypeHandle,
+  mediaLibrarySource,
   type PerspectiveHandle,
   type ProjectHandle,
   type ReleasePerspective,

package/src/agent/agentActions.test.ts

@@ -0,0 +1,81 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import {firstValueFrom, of} from 'rxjs'
+import {beforeEach, describe, expect, it, vi} from 'vitest'
+
+import {
+  agentGenerate,
+  agentPatch,
+  agentPrompt,
+  agentTransform,
+  agentTranslate,
+} from './agentActions'
+
+let mockClient: any
+
+vi.mock('../client/clientStore', () => {
+  return {
+    getClientState: () => ({observable: of(mockClient)}),
+  }
+})
+
+describe('agent actions', () => {
+  beforeEach(() => {
+    mockClient = {
+      observable: {
+        agent: {
+          action: {
+            generate: vi.fn(),
+            transform: vi.fn(),
+            translate: vi.fn(),
+          },
+        },
+      },
+      agent: {
+        action: {
+          prompt: vi.fn(),
+          patch: vi.fn(),
+        },
+      },
+    }
+  })
+
+  it('agentGenerate returns observable from client', async () => {
+    mockClient.observable.agent.action.generate.mockReturnValue(of('gen'))
+    const instance = {config: {projectId: 'p', dataset: 'd'}} as any
+    const value = await firstValueFrom(agentGenerate(instance, {foo: 'bar'} as any))
+    expect(value).toBe('gen')
+    expect(mockClient.observable.agent.action.generate).toHaveBeenCalledWith({foo: 'bar'})
+  })
+
+  it('agentTransform returns observable from client', async () => {
+    mockClient.observable.agent.action.transform.mockReturnValue(of('xform'))
+    const instance = {config: {projectId: 'p', dataset: 'd'}} as any
+    const value = await firstValueFrom(agentTransform(instance, {a: 1} as any))
+    expect(value).toBe('xform')
+    expect(mockClient.observable.agent.action.transform).toHaveBeenCalledWith({a: 1})
+  })
+
+  it('agentTranslate returns observable from client', async () => {
+    mockClient.observable.agent.action.translate.mockReturnValue(of('xlate'))
+    const instance = {config: {projectId: 'p', dataset: 'd'}} as any
+    const value = await firstValueFrom(agentTranslate(instance, {b: 2} as any))
+    expect(value).toBe('xlate')
+    expect(mockClient.observable.agent.action.translate).toHaveBeenCalledWith({b: 2})
+  })
+
+  it('agentPrompt wraps promise into observable', async () => {
+    mockClient.agent.action.prompt.mockResolvedValue('prompted')
+    const instance = {config: {projectId: 'p', dataset: 'd'}} as any
+    const value = await firstValueFrom(agentPrompt(instance, {p: true} as any))
+    expect(value).toBe('prompted')
+    expect(mockClient.agent.action.prompt).toHaveBeenCalledWith({p: true})
+  })
+
+  it('agentPatch wraps promise into observable', async () => {
+    mockClient.agent.action.patch.mockResolvedValue('patched')
+    const instance = {config: {projectId: 'p', dataset: 'd'}} as any
+    const value = await firstValueFrom(agentPatch(instance, {q: false} as any))
+    expect(value).toBe('patched')
+    expect(mockClient.agent.action.patch).toHaveBeenCalledWith({q: false})
+  })
+})

package/src/agent/agentActions.ts

@@ -0,0 +1,139 @@
+import {type SanityClient} from '@sanity/client'
+import {from, Observable, switchMap} from 'rxjs'
+
+import {getClientState} from '../client/clientStore'
+import {type SanityInstance} from '../store/createSanityInstance'
+
+const API_VERSION = 'vX'
+
+/** @alpha */
+export type AgentGenerateOptions = Parameters<
+  SanityClient['observable']['agent']['action']['generate']
+>[0]
+
+/** @alpha */
+export type AgentTransformOptions = Parameters<
+  SanityClient['observable']['agent']['action']['transform']
+>[0]
+
+/** @alpha */
+export type AgentTranslateOptions = Parameters<
+  SanityClient['observable']['agent']['action']['translate']
+>[0]
+
+/** @alpha */
+export type AgentPromptOptions = Parameters<SanityClient['agent']['action']['prompt']>[0]
+
+/** @alpha */
+export type AgentPatchOptions = Parameters<SanityClient['agent']['action']['patch']>[0]
+
+/** @alpha */
+export type AgentGenerateResult = Awaited<
+  ReturnType<SanityClient['observable']['agent']['action']['generate']>
+>
+
+/** @alpha */
+export type AgentTransformResult = Awaited<
+  ReturnType<SanityClient['observable']['agent']['action']['transform']>
+>
+
+/** @alpha */
+export type AgentTranslateResult = Awaited<
+  ReturnType<SanityClient['observable']['agent']['action']['translate']>
+>
+
+/** @alpha */
+export type AgentPromptResult = Awaited<ReturnType<SanityClient['agent']['action']['prompt']>>
+
+/** @alpha */
+export type AgentPatchResult = Awaited<ReturnType<SanityClient['agent']['action']['patch']>>
+
+/**
+ * Generates a new document using the agent.
+ * @param instance - The Sanity instance.
+ * @param options - The options for the agent generate action. See the [Agent Actions API](https://www.sanity.io/docs/agent-actions/introduction) for more details.
+ * @returns An Observable emitting the result of the agent generate action.
+ * @alpha
+ */
+export function agentGenerate(
+  instance: SanityInstance,
+  options: AgentGenerateOptions,
+): AgentGenerateResult {
+  return getClientState(instance, {
+    apiVersion: API_VERSION,
+    projectId: instance.config.projectId,
+    dataset: instance.config.dataset,
+  }).observable.pipe(switchMap((client) => client.observable.agent.action.generate(options)))
+}
+
+/**
+ * Transforms a document using the agent.
+ * @param instance - The Sanity instance.
+ * @param options - The options for the agent transform action. See the [Agent Actions API](https://www.sanity.io/docs/agent-actions/introduction) for more details.
+ * @returns An Observable emitting the result of the agent transform action.
+ * @alpha
+ */
+export function agentTransform(
+  instance: SanityInstance,
+  options: AgentTransformOptions,
+): AgentTransformResult {
+  return getClientState(instance, {
+    apiVersion: API_VERSION,
+    projectId: instance.config.projectId,
+    dataset: instance.config.dataset,
+  }).observable.pipe(switchMap((client) => client.observable.agent.action.transform(options)))
+}
+
+/**
+ * Translates a document using the agent.
+ * @param instance - The Sanity instance.
+ * @param options - The options for the agent translate action. See the [Agent Actions API](https://www.sanity.io/docs/agent-actions/introduction) for more details.
+ * @returns An Observable emitting the result of the agent translate action.
+ * @alpha
+ */
+export function agentTranslate(
+  instance: SanityInstance,
+  options: AgentTranslateOptions,
+): AgentTranslateResult {
+  return getClientState(instance, {
+    apiVersion: API_VERSION,
+    projectId: instance.config.projectId,
+    dataset: instance.config.dataset,
+  }).observable.pipe(switchMap((client) => client.observable.agent.action.translate(options)))
+}
+
+/**
+ * Prompts the agent using the same instruction template format as the other actions, but returns text or json instead of acting on a document.
+ * @param instance - The Sanity instance.
+ * @param options - The options for the agent prompt action. See the [Agent Actions API](https://www.sanity.io/docs/agent-actions/introduction) for more details.
+ * @returns An Observable emitting the result of the agent prompt action.
+ * @alpha
+ */
+export function agentPrompt(
+  instance: SanityInstance,
+  options: AgentPromptOptions,
+): Observable<AgentPromptResult> {
+  return getClientState(instance, {
+    apiVersion: API_VERSION,
+    projectId: instance.config.projectId,
+    dataset: instance.config.dataset,
+  }).observable.pipe(switchMap((client) => from(client.agent.action.prompt(options))))
+}
+
+/**
+ * Patches a document using the agent.
+ * @param instance - The Sanity instance.
+ * @param options - The options for the agent patch action. See the [Agent Actions API](https://www.sanity.io/docs/agent-actions/introduction) for more details.
+ * @returns An Observable emitting the result of the agent patch action.
+ * @alpha
+ */
+export function agentPatch(
+  instance: SanityInstance,
+  options: AgentPatchOptions,
+): Observable<AgentPatchResult> {
+  return getClientState(instance, {
+    apiVersion: API_VERSION,
+    projectId: instance.config.projectId,
+    dataset: instance.config.dataset,
+  }).observable.pipe(switchMap((client) => from(client.agent.action.patch(options))))
+}

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/config/sanityConfig.ts

@@ -81,3 +81,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]}
+}