@sanity/sdk 2.9.0 → 2.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanity/sdk",
-  "version": "2.9.0",
+  "version": "2.10.0",
   "private": false,
   "description": "Sanity SDK",
   "keywords": [
@@ -49,29 +49,27 @@
   "prettier": "@sanity/prettier-config",
   "dependencies": {
     "@sanity/bifur-client": "^0.4.1",
-    "@sanity/client": "^7.14.1",
-    "@sanity/comlink": "^3.0.4",
+    "@sanity/client": "^7.22.0",
+    "@sanity/comlink": "^3.1.1",
     "@sanity/diff-match-patch": "^3.2.0",
     "@sanity/diff-patch": "^6.0.0",
     "@sanity/id-utils": "^1.0.0",
     "@sanity/image-url": "^2.0.3",
     "@sanity/json-match": "^1.0.5",
-    "@sanity/message-protocol": "^0.18.0",
+    "@sanity/message-protocol": "^0.23.0",
     "@sanity/mutate": "^0.16.1",
-    "@sanity/telemetry": "^1.0.0",
+    "@sanity/telemetry": "^1.1.0",
     "@sanity/types": "^5.2.0",
     "groq": "3.88.1-typegen-experimental.0",
     "groq-js": "^1.19.0",
-    "lodash-es": "^4.17.21",
     "reselect": "^5.1.1",
     "rxjs": "^7.8.2",
-    "zustand": "^5.0.4"
+    "zustand": "^5.0.12"
   },
   "devDependencies": {
     "@sanity/browserslist-config": "^1.0.5",
     "@sanity/pkg-utils": "^8.1.29",
     "@sanity/prettier-config": "^1.0.6",
-    "@types/lodash-es": "^4.17.12",
     "@vitest/coverage-v8": "3.2.4",
     "eslint": "^9.22.0",
     "prettier": "^3.7.3",
@@ -80,10 +78,10 @@
     "vite": "^7.0.0",
     "vitest": "^3.2.4",
     "@repo/config-eslint": "0.0.0",
-    "@repo/config-test": "0.0.1",
+    "@repo/tsconfig": "0.0.1",
     "@repo/package.bundle": "3.82.0",
     "@repo/package.config": "0.0.1",
-    "@repo/tsconfig": "0.0.1"
+    "@repo/config-test": "0.0.1"
   },
   "engines": {
     "node": ">=20.19"

package/src/_exports/index.ts

@@ -86,15 +86,22 @@ export {
   type LogNamespace,
 } from '../config/loggingConfig'
 export {
+  type CanvasResource,
   type CanvasSource,
   type DatasetHandle,
+  type DatasetResource,
   type DatasetSource,
   type DocumentHandle,
+  type DocumentResource,
   type DocumentSource,
   type DocumentTypeHandle,
+  isCanvasResource,
   isCanvasSource,
+  isDatasetResource,
   isDatasetSource,
+  isMediaLibraryResource,
   isMediaLibrarySource,
+  type MediaLibraryResource,
   type MediaLibrarySource,
   type PerspectiveHandle,
   type ProjectHandle,
@@ -212,6 +219,7 @@ export {type FetcherStore, type FetcherStoreState} from '../utils/createFetcherS
 export {createGroqSearchFilter} from '../utils/createGroqSearchFilter'
 export {defineIntent, type Intent, type IntentFilter} from '../utils/defineIntent'
 export {getCorsErrorProjectId} from '../utils/getCorsErrorProjectId'
+export {isImportError} from '../utils/isImportError'
 export {CORE_SDK_VERSION} from '../version'
 export {
   getIndexForKey,

package/src/client/clientStore.test.ts

@@ -190,17 +190,17 @@ describe('clientStore', () => {
     })
   })
 
-  describe('source handling', () => {
-    it('should create client when source is provided', () => {
+  describe('resource handling', () => {
+    it('should create client when resource is provided', () => {
       const client = getClient(instance, {
         apiVersion: '2024-11-12',
-        source: {projectId: 'source-project', dataset: 'source-dataset'},
+        resource: {projectId: 'source-project', dataset: 'source-dataset'},
       })
 
       expect(vi.mocked(createClient)).toHaveBeenCalledWith(
         expect.objectContaining({
-          'apiVersion': '2024-11-12',
-          '~experimental_resource': {type: 'dataset', id: 'source-project.source-dataset'},
+          apiVersion: '2024-11-12',
+          resource: {type: 'dataset', id: 'source-project.source-dataset'},
         }),
       )
       // Client should be projectless - no projectId/dataset in config
@@ -208,21 +208,21 @@ describe('clientStore', () => {
       expect(client.config()).not.toHaveProperty('dataset')
       expect(client.config()).toEqual(
         expect.objectContaining({
-          '~experimental_resource': {type: 'dataset', id: 'source-project.source-dataset'},
+          resource: {type: 'dataset', id: 'source-project.source-dataset'},
         }),
       )
     })
 
-    it('should create resource when source has array sourceId and be projectless', () => {
+    it('should create resource when resource has array resourceId and be projectless', () => {
       const client = getClient(instance, {
         apiVersion: '2024-11-12',
-        source: {mediaLibraryId: 'media-lib-123'},
+        resource: {mediaLibraryId: 'media-lib-123'},
       })
 
       expect(vi.mocked(createClient)).toHaveBeenCalledWith(
         expect.objectContaining({
-          '~experimental_resource': {type: 'media-library', id: 'media-lib-123'},
-          'apiVersion': '2024-11-12',
+          resource: {type: 'media-library', id: 'media-lib-123'},
+          apiVersion: '2024-11-12',
         }),
       )
       // Client should be projectless - no projectId/dataset in config
@@ -230,21 +230,21 @@ describe('clientStore', () => {
       expect(client.config()).not.toHaveProperty('dataset')
       expect(client.config()).toEqual(
         expect.objectContaining({
-          '~experimental_resource': {type: 'media-library', id: 'media-lib-123'},
+          resource: {type: 'media-library', id: 'media-lib-123'},
         }),
       )
     })
 
-    it('should create resource when canvas source is provided and be projectless', () => {
+    it('should create resource when canvas resource is provided and be projectless', () => {
       const client = getClient(instance, {
         apiVersion: '2024-11-12',
-        source: {canvasId: 'canvas-123'},
+        resource: {canvasId: 'canvas-123'},
       })
 
       expect(vi.mocked(createClient)).toHaveBeenCalledWith(
         expect.objectContaining({
-          '~experimental_resource': {type: 'canvas', id: 'canvas-123'},
-          'apiVersion': '2024-11-12',
+          resource: {type: 'canvas', id: 'canvas-123'},
+          apiVersion: '2024-11-12',
         }),
       )
       // Client should be projectless - no projectId/dataset in config
@@ -252,38 +252,38 @@ describe('clientStore', () => {
       expect(client.config()).not.toHaveProperty('dataset')
       expect(client.config()).toEqual(
         expect.objectContaining({
-          '~experimental_resource': {type: 'canvas', id: 'canvas-123'},
+          resource: {type: 'canvas', id: 'canvas-123'},
         }),
       )
     })
 
-    it('should create projectless client when source is provided, ignoring instance config', () => {
+    it('should create projectless client when resource is provided, ignoring instance config', () => {
       const client = getClient(instance, {
         apiVersion: '2024-11-12',
-        source: {projectId: 'source-project', dataset: 'source-dataset'},
+        resource: {projectId: 'source-project', dataset: 'source-dataset'},
       })
 
-      // Client should be projectless - source takes precedence, instance config is ignored
+      // Client should be projectless - resource takes precedence, instance config is ignored
       expect(client.config()).not.toHaveProperty('projectId')
       expect(client.config()).not.toHaveProperty('dataset')
       expect(client.config()).toEqual(
         expect.objectContaining({
-          '~experimental_resource': {type: 'dataset', id: 'source-project.source-dataset'},
+          resource: {type: 'dataset', id: 'source-project.source-dataset'},
         }),
       )
     })
 
-    it('should warn when both source and explicit projectId/dataset are provided', () => {
+    it('should warn when both resource and explicit projectId/dataset are provided', () => {
       const consoleSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
       const client = getClient(instance, {
         apiVersion: '2024-11-12',
-        source: {projectId: 'source-project', dataset: 'source-dataset'},
+        resource: {projectId: 'source-project', dataset: 'source-dataset'},
         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.',
+        'Both resource and explicit projectId/dataset are provided. The resource will be used and projectId/dataset will be ignored.',
       )
       // Client should still be projectless despite explicit projectId/dataset
       expect(client.config()).not.toHaveProperty('projectId')
@@ -291,18 +291,18 @@ describe('clientStore', () => {
       consoleSpy.mockRestore()
     })
 
-    it('should create different clients for different sources', () => {
+    it('should create different clients for different resources', () => {
       const client1 = getClient(instance, {
         apiVersion: '2024-11-12',
-        source: {projectId: 'source-project', dataset: 'source-dataset'},
+        resource: {projectId: 'source-project', dataset: 'source-dataset'},
       })
       const client2 = getClient(instance, {
         apiVersion: '2024-11-12',
-        source: {mediaLibraryId: 'media-lib-123'},
+        resource: {mediaLibraryId: 'media-lib-123'},
       })
       const client3 = getClient(instance, {
         apiVersion: '2024-11-12',
-        source: {canvasId: 'canvas-123'},
+        resource: {canvasId: 'canvas-123'},
       })
 
       expect(client1).not.toBe(client2)
@@ -311,14 +311,14 @@ describe('clientStore', () => {
       expect(vi.mocked(createClient)).toHaveBeenCalledTimes(3)
     })
 
-    it('should reuse clients with identical source configurations', () => {
+    it('should reuse clients with identical resource configurations', () => {
       const client1 = getClient(instance, {
         apiVersion: '2024-11-12',
-        source: {projectId: 'source-project', dataset: 'source-dataset'},
+        resource: {projectId: 'source-project', dataset: 'source-dataset'},
       })
       const client2 = getClient(instance, {
         apiVersion: '2024-11-12',
-        source: {projectId: 'source-project', dataset: 'source-dataset'},
+        resource: {projectId: 'source-project', dataset: 'source-dataset'},
       })
 
       expect(client1).toBe(client2)

package/src/client/clientStore.ts

@@ -1,17 +1,17 @@
 import {type ClientConfig, createClient, type SanityClient} from '@sanity/client'
-import {pick} from 'lodash-es'
 
 import {getAuthMethodState, getTokenState} from '../auth/authStore'
 import {
-  type DocumentSource,
-  isCanvasSource,
-  isDatasetSource,
-  isMediaLibrarySource,
+  type DocumentResource,
+  isCanvasResource,
+  isDatasetResource,
+  isMediaLibraryResource,
 } from '../config/sanityConfig'
 import {bindActionGlobally} from '../store/createActionBinder'
 import {createStateSourceAction} from '../store/createStateSourceAction'
 import {defineStore, type StoreContext} from '../store/defineStore'
 import {getStagingApiHost} from '../utils/getStagingApiHost'
+import {pickProperties} from '../utils/object'
 
 const DEFAULT_API_VERSION = '2024-11-12'
 const DEFAULT_REQUEST_TAG_PREFIX = 'sanity.sdk'
@@ -31,22 +31,21 @@ type AllowedClientConfigKey =
   | 'useProjectHostname'
 
 const allowedKeys = Object.keys({
-  'apiHost': null,
-  'useCdn': null,
-  'token': null,
-  'perspective': null,
-  'proxy': null,
-  'withCredentials': null,
-  'timeout': null,
-  'maxRetries': null,
-  'dataset': null,
-  'projectId': null,
-  'scope': null,
-  'apiVersion': null,
-  'requestTagPrefix': null,
-  'useProjectHostname': null,
-  '~experimental_resource': null,
-  'source': null,
+  apiHost: null,
+  useCdn: null,
+  token: null,
+  perspective: null,
+  proxy: null,
+  withCredentials: null,
+  timeout: null,
+  maxRetries: null,
+  dataset: null,
+  projectId: null,
+  scope: null,
+  apiVersion: null,
+  requestTagPrefix: null,
+  useProjectHostname: null,
+  resource: null,
 } satisfies Record<keyof ClientOptions, null>) as (keyof ClientOptions)[]
 
 const DEFAULT_CLIENT_CONFIG: ClientConfig = {
@@ -67,11 +66,6 @@ export interface ClientStoreState {
   authMethod?: 'localstorage' | 'cookie'
 }
 
-interface ClientResource {
-  type: 'dataset' | 'media-library' | 'canvas'
-  id: string
-}
-
 /**
  * Options used when retrieving a client instance from the client store.
  *
@@ -94,20 +88,17 @@ export interface ClientOptions extends Pick<ClientConfig, AllowedClientConfigKey
    * and the global client ('global'). When set to `'global'`, the global client
    * is used.
    */
-  'scope'?: 'default' | 'global'
+  scope?: 'default' | 'global'
   /**
    * A required string indicating the API version for the client.
    */
-  'apiVersion': string
-  /**
-   * @internal
-   */
-  '~experimental_resource'?: ClientConfig['~experimental_resource']
+  apiVersion: string
 
   /**
    * @internal
+   * The SDK resource to use for the client -- this will get transformed into a ClientConfig resource.
    */
-  'source'?: DocumentSource
+  resource?: DocumentResource
 }
 
 const clientStore = defineStore<ClientStoreState>({
@@ -144,7 +135,13 @@ const listenToAuthMethod = ({instance, state}: StoreContext<ClientStoreState>) =
   })
 }
 
-const getClientConfigKey = (options: ClientOptions) => JSON.stringify(pick(options, ...allowedKeys))
+type ClientInstanceCacheKeyInput = ClientConfig &
+  Partial<Pick<ClientOptions, 'scope'>> & {
+    apiVersion: string
+  }
+
+const getClientConfigKey = (options: ClientInstanceCacheKeyInput) =>
+  JSON.stringify(pickProperties(options, allowedKeys))
 
 /**
  * Retrieves a Sanity client instance configured with the provided options.
@@ -182,15 +179,18 @@ export const getClient = bindActionGlobally(
     const tokenFromState = state.get().token
     const {clients, authMethod} = state.get()
 
-    let resource: ClientResource | undefined
+    let resource: ClientConfig['resource'] | undefined
 
-    if (options.source) {
-      if (isDatasetSource(options.source)) {
-        resource = {type: 'dataset', id: `${options.source.projectId}.${options.source.dataset}`}
-      } else if (isMediaLibrarySource(options.source)) {
-        resource = {type: 'media-library', id: options.source.mediaLibraryId}
-      } else if (isCanvasSource(options.source)) {
-        resource = {type: 'canvas', id: options.source.canvasId}
+    if (options.resource) {
+      if (isDatasetResource(options.resource)) {
+        resource = {
+          type: 'dataset',
+          id: `${options.resource.projectId}.${options.resource.dataset}`,
+        }
+      } else if (isMediaLibraryResource(options.resource)) {
+        resource = {type: 'media-library', id: options.resource.mediaLibraryId}
+      } else if (isCanvasResource(options.resource)) {
+        resource = {type: 'canvas', id: options.resource.canvasId}
       }
     }
 
@@ -198,25 +198,25 @@ export const getClient = bindActionGlobally(
     const dataset = options.dataset ?? instance.config.dataset
     const apiHost = options.apiHost ?? instance.config.auth?.apiHost ?? getStagingApiHost()
 
-    const effectiveOptions: ClientOptions = {
+    const effectiveOptions: ClientConfig & {apiVersion: string} = {
       ...DEFAULT_CLIENT_CONFIG,
       ...((options.scope === 'global' || !projectId || resource) && {useProjectHostname: false}),
       token: authMethod === 'cookie' ? undefined : (tokenFromState ?? undefined),
       ...options,
       ...(projectId && {projectId}),
       ...(dataset && {dataset}),
+      ...(resource ? {resource} : {resource: undefined}),
       ...(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.
+    // When a resource is provided, don't use projectId/dataset - the client should be "projectless"
+    // The client code itself will ignore the non-resource 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 (resource) {
       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.',
+          'Both resource and explicit projectId/dataset are provided. The resource will be used and projectId/dataset will be ignored.',
         )
       }
       delete effectiveOptions.projectId

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

@@ -1,7 +1,7 @@
 import {type ChannelInput, type ChannelInstance} from '@sanity/comlink'
-import {isEqual} from 'lodash-es'
 
 import {type StoreContext} from '../../../store/defineStore'
+import {isDeepEqual} from '../../../utils/object'
 import {type FrameMessage, type WindowMessage} from '../../types'
 import {type ComlinkControllerState} from '../comlinkControllerStore'
 
@@ -25,7 +25,7 @@ export const getOrCreateChannel = (
 
   // limit channels to one per name
   if (existing) {
-    if (!isEqual(existing.options, options)) {
+    if (!isDeepEqual(existing.options, options)) {
       throw new Error(`Channel "${options.name}" already exists with different options`)
     }
 

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

@@ -1,7 +1,7 @@
 import {createNode, type Node, type NodeInput} from '@sanity/comlink'
-import {isEqual} from 'lodash-es'
 
 import {type StoreContext} from '../../../store/defineStore'
+import {isDeepEqual} from '../../../utils/object'
 import {type FrameMessage, type WindowMessage} from '../../types'
 import {type ComlinkNodeState} from '../comlinkNodeStore'
 
@@ -14,7 +14,7 @@ export const getOrCreateNode = (
 
   // limit nodes to one per name
   if (existing) {
-    if (!isEqual(existing.options, options)) {
+    if (!isDeepEqual(existing.options, options)) {
       throw new Error(`Node "${options.name}" already exists with different options`)
     }
 

package/src/config/sanityConfig.ts

@@ -73,9 +73,14 @@ export interface DatasetHandle<TDataset extends string = string, TProjectId exte
   dataset?: TDataset
   /**
    * @beta
-   * Explicit source object to use for this operation.
+   * Explicit resource object to use for this operation.
    */
-  source?: DocumentSource
+  resource?: DocumentResource
+  /**
+   * @deprecated Use `resource` instead.
+   * @beta
+   */
+  source?: DocumentResource
 }
 
 /**
@@ -145,51 +150,106 @@ export interface SanityConfig extends DatasetHandle, PerspectiveHandle {
 
   /**
    * @beta
-   * A list of named sources to use for this instance.
+   * A list of named resources to use for this instance.
+   */
+  resources?: Record<string, DocumentResource>
+  /**
+   * @deprecated Use `resources` instead.
+   * @beta
    */
-  sources?: Record<string, DocumentSource>
+  sources?: Record<string, DocumentResource>
 }
 
 /**
- * A document source can be used for querying.
+ * A document resource can be used for querying.
  * This will soon be the default way to identify where you are querying from.
  *
  * @beta
  */
-export type DocumentSource = DatasetSource | MediaLibrarySource | CanvasSource
+export type DocumentResource = DatasetResource | MediaLibraryResource | CanvasResource
+
+/**
+ * @beta
+ */
+export type DatasetResource = {projectId: string; dataset: string}
+
+/**
+ * @beta
+ */
+export type MediaLibraryResource = {mediaLibraryId: string}
+
+/**
+ * @beta
+ */
+export type CanvasResource = {canvasId: string}
+
+/**
+ * @beta
+ */
+export function isDatasetResource(resource: DocumentResource): resource is DatasetResource {
+  return 'projectId' in resource && 'dataset' in resource
+}
+
+/**
+ * @beta
+ */
+export function isMediaLibraryResource(
+  resource: DocumentResource,
+): resource is MediaLibraryResource {
+  return 'mediaLibraryId' in resource
+}
+
+/**
+ * @beta
+ */
+export function isCanvasResource(resource: DocumentResource): resource is CanvasResource {
+  return 'canvasId' in resource
+}
+
+/**
+ * @deprecated Use `DocumentResource` instead.
+ * @beta
+ */
+export type DocumentSource = DocumentResource
 
 /**
+ * @deprecated Use `DatasetResource` instead.
  * @beta
  */
-export type DatasetSource = {projectId: string; dataset: string}
+export type DatasetSource = DatasetResource
 
 /**
+ * @deprecated Use `MediaLibraryResource` instead.
  * @beta
  */
-export type MediaLibrarySource = {mediaLibraryId: string}
+export type MediaLibrarySource = MediaLibraryResource
 
 /**
+ * @deprecated Use `CanvasResource` instead.
  * @beta
  */
-export type CanvasSource = {canvasId: string}
+export type CanvasSource = CanvasResource
 
 /**
+ * @deprecated Use `isDatasetResource` instead.
  * @beta
  */
 export function isDatasetSource(source: DocumentSource): source is DatasetSource {
-  return 'projectId' in source && 'dataset' in source
+  return isDatasetResource(source)
 }
 
 /**
+ * @deprecated Use `isMediaLibraryResource` instead.
  * @beta
  */
 export function isMediaLibrarySource(source: DocumentSource): source is MediaLibrarySource {
-  return 'mediaLibraryId' in source
+  return isMediaLibraryResource(source)
 }
 
 /**
+ * @deprecated Use `isCanvasResource` instead.
  * @beta
  */
 export function isCanvasSource(source: DocumentSource): source is CanvasSource {
-  return 'canvasId' in source
+  return isCanvasResource(source)
 }

package/src/document/applyDocumentActions.test.ts

@@ -2,7 +2,7 @@ import {type SanityDocument} from '@sanity/types'
 import {Subject} from 'rxjs'
 import {describe, expect, it} from 'vitest'
 
-import {bindActionBySource} from '../store/createActionBinder'
+import {bindActionByResource} from '../store/createActionBinder'
 import {createSanityInstance, type SanityInstance} from '../store/createSanityInstance'
 import {createStoreState, type StoreState} from '../store/createStoreState'
 import {type DocumentAction} from './actions'
@@ -12,7 +12,7 @@ import {type AppliedTransaction, type OutgoingTransaction} from './reducers'
 
 vi.mock('../store/createActionBinder', async (importOriginal) => ({
   ...(await importOriginal<typeof import('../store/createActionBinder')>()),
-  bindActionBySource: vi.fn(),
+  bindActionByResource: vi.fn(),
 }))
 
 type TestState = Pick<
@@ -46,9 +46,9 @@ describe('applyDocumentActions', () => {
     }
     state = createStoreState(initialState)
     instance = createSanityInstance({projectId: 'p', dataset: 'd'})
-    const key = {name: 'p.d', source: {projectId: 'p', dataset: 'd'}}
+    const key = {name: 'p.d', resource: {projectId: 'p', dataset: 'd'}}
 
-    vi.mocked(bindActionBySource).mockImplementation(
+    vi.mocked(bindActionByResource).mockImplementation(
       (_storeDef, action) => (instanceParam: SanityInstance, options) =>
         action({instance: instanceParam, state, key}, options),
     )
@@ -73,7 +73,7 @@ describe('applyDocumentActions', () => {
     const applyPromise = applyDocumentActions(instance, {
       actions: [action],
       transactionId: 'txn-success',
-      source: {projectId: 'p', dataset: 'd'},
+      resource: {projectId: 'p', dataset: 'd'},
     })
 
     const appliedTx: AppliedTransaction = {
@@ -131,7 +131,7 @@ describe('applyDocumentActions', () => {
     const applyPromise = applyDocumentActions(instance, {
       actions: [action],
       transactionId: 'txn-error',
-      source: {projectId: 'p', dataset: 'd'},
+      resource: {projectId: 'p', dataset: 'd'},
     })
 
     const errorEvent: DocumentEvent = {
@@ -165,7 +165,7 @@ describe('applyDocumentActions', () => {
     const applyPromise = applyDocumentActions(childInstance, {
       actions: [action],
       transactionId: 'txn-child-match',
-      source: {projectId: 'p', dataset: 'd'},
+      resource: {projectId: 'p', dataset: 'd'},
     })
 
     // Simulate an applied transaction on the parent's instance