@sanity/sdk 2.7.0 → 3.0.0-rc.0

package/src/client/clientStore.ts

@@ -1,12 +1,17 @@
-import {type ClientConfig, createClient, type SanityClient} from '@sanity/client'
+import {
+  type ClientConfig,
+  type ClientPerspective,
+  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'
@@ -45,16 +50,16 @@ const allowedKeys = Object.keys({
   'requestTagPrefix': null,
   'useProjectHostname': null,
   '~experimental_resource': null,
-  'source': null,
+  'resource': null,
 } satisfies Record<keyof ClientOptions, null>) as (keyof ClientOptions)[]
 
-const DEFAULT_CLIENT_CONFIG: ClientConfig = {
+const DEFAULT_CLIENT_CONFIG = {
   apiVersion: DEFAULT_API_VERSION,
   useCdn: false,
   ignoreBrowserTokenWarning: true,
   allowReconfigure: false,
   requestTagPrefix: DEFAULT_REQUEST_TAG_PREFIX,
-}
+} satisfies ClientConfig
 
 /**
  * States tracked by the client store
@@ -87,7 +92,15 @@ interface ClientResource {
  *
  * @public
  */
-export interface ClientOptions extends Pick<ClientConfig, AllowedClientConfigKey> {
+export interface ClientOptions extends Omit<
+  Pick<ClientConfig, AllowedClientConfigKey>,
+  'resource'
+> {
+  /**
+   * Narrows the inherited `perspective` to exclude stackable perspectives,
+   * which are not supported by the SDK.
+   */
+  'perspective'?: Exclude<ClientPerspective, readonly unknown[]>
   /**
    * An optional flag to choose between the default client (typically project-level)
    * and the global client ('global'). When set to `'global'`, the global client
@@ -106,7 +119,7 @@ export interface ClientOptions extends Pick<ClientConfig, AllowedClientConfigKey
   /**
    * @internal
    */
-  'source'?: DocumentSource
+  'resource'?: DocumentResource
 }
 
 const clientStore = defineStore<ClientStoreState>({
@@ -182,22 +195,27 @@ export const getClient = bindActionGlobally(
     const {clients, authMethod} = state.get()
 
     let resource: ClientResource | undefined
+    let projectId: string | undefined = options.projectId
+    let dataset: string | undefined = options.dataset
 
-    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 (isMediaLibraryResource(options.resource)) {
+        resource = {type: 'media-library', id: options.resource.mediaLibraryId}
+      } else if (isCanvasResource(options.resource)) {
+        resource = {type: 'canvas', id: options.resource.canvasId}
+      } else if (isDatasetResource(options.resource)) {
+        projectId = options.resource.projectId
+        dataset = options.resource.dataset
       }
+      // temporarily excluding dataset resource as a resource for now. Many of the global API endpoints require vX api version.
+      // When ready, remove the above check and uncomment the below check.
+      // } else if (isDatasetResource(options.resource)) {
+      //   resource = {type: 'dataset', id: `${options.resource.projectId}.${options.resource.dataset}`}
     }
 
-    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 = {
+    const effectiveOptions = {
       ...DEFAULT_CLIENT_CONFIG,
       ...((options.scope === 'global' || !projectId || resource) && {useProjectHostname: false}),
       token: authMethod === 'cookie' ? undefined : (tokenFromState ?? undefined),
@@ -206,20 +224,23 @@ export const getClient = bindActionGlobally(
       ...(dataset && {dataset}),
       ...(apiHost && {apiHost}),
       ...(resource && {'~experimental_resource': resource}),
-    }
+    } as ClientOptions
 
-    // 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 MediaLibrary or Canvas 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) {
+    // Note: DatasetResource is handled differently - it extracts projectId/dataset from the resource and uses those
+    if (options.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
-      delete effectiveOptions.dataset
+      if (resource) {
+        delete effectiveOptions.projectId
+        delete effectiveOptions.dataset
+      }
     }
 
     if (effectiveOptions.token === null || typeof effectiveOptions.token === 'undefined') {
@@ -231,11 +252,14 @@ export const getClient = bindActionGlobally(
       delete effectiveOptions.withCredentials
     }
 
+    // Don't pass our DocumentResource to createClient - we've already derived projectId/dataset or ~experimental_resource
+    const {resource: _omitResource, ...clientConfig} = effectiveOptions
+
     const key = getClientConfigKey(effectiveOptions)
 
     if (clients[key]) return clients[key]
 
-    const client = createClient(effectiveOptions)
+    const client = createClient(clientConfig as ClientConfig)
     state.set('addClient', (prev) => ({clients: {...prev.clients, [key]: client}}))
 
     return client

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

@@ -7,10 +7,7 @@ import {type ComlinkControllerState} from '../comlinkControllerStore'
 import {destroyController} from './destroyController'
 
 describe('destroyController', () => {
-  const instance = createSanityInstance({
-    projectId: 'test-project-id',
-    dataset: 'test-dataset',
-  })
+  const instance = createSanityInstance()
   let state: ReturnType<typeof createStoreState<ComlinkControllerState>>
   let mockController: {destroy: ReturnType<typeof vi.fn>}
 

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

@@ -13,10 +13,7 @@ const channelConfig = {
 }
 
 describe('getOrCreateChannel', () => {
-  const instance = createSanityInstance({
-    projectId: 'test-project-id',
-    dataset: 'test-dataset',
-  })
+  const instance = createSanityInstance()
   let state: ReturnType<typeof createStoreState<ComlinkControllerState>>
   let mockController: Partial<Controller>
   let mockChannel: Partial<ChannelInstance<FrameMessage, WindowMessage>>

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

@@ -21,10 +21,7 @@ describe('getOrCreateController', () => {
   let state: ReturnType<typeof createStoreState<ComlinkControllerState>>
 
   beforeEach(() => {
-    instance = createSanityInstance({
-      projectId: 'test-project-id',
-      dataset: 'test-dataset',
-    })
+    instance = createSanityInstance()
 
     state = createStoreState<ComlinkControllerState>({
       controller: null,

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

@@ -29,7 +29,7 @@ describe('releaseChannel', () => {
   let releaseChannel: (inst: SanityInstance, channelName: string) => void
 
   beforeEach(() => {
-    instance = createSanityInstance({projectId: 'test-project-id', dataset: 'test-dataset'})
+    instance = createSanityInstance()
     store = createStoreInstance(instance, key, comlinkControllerStore)
 
     const bind =

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

@@ -16,10 +16,7 @@ describe('comlinkControllerStore', () => {
   let instance: SanityInstance
   beforeEach(() => {
     vi.resetModules()
-    instance = createSanityInstance({
-      projectId: 'test-project-id',
-      dataset: 'test-dataset',
-    })
+    instance = createSanityInstance()
   })
 
   afterEach(() => {

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

@@ -22,10 +22,7 @@ const nodeConfig = {
 }
 
 describe('getOrCreateNode', () => {
-  const instance = createSanityInstance({
-    projectId: 'test-project-id',
-    dataset: 'test-dataset',
-  })
+  const instance = createSanityInstance()
   let state: ReturnType<typeof createStoreState<ComlinkNodeState>>
   let mockNode: Partial<Node<WindowMessage, FrameMessage>> & {
     start: ReturnType<typeof vi.fn>

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

@@ -22,10 +22,7 @@ describe('releaseNode', () => {
   }
 
   beforeEach(() => {
-    instance = createSanityInstance({
-      projectId: 'test-project-id',
-      dataset: 'test-dataset',
-    })
+    instance = createSanityInstance()
     mockNode = {start: vi.fn(), stop: vi.fn(), onStatus: vi.fn()}
     state = createStoreState<ComlinkNodeState>({nodes: new Map(), subscriptions: new Map()})
     vi.clearAllMocks()

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

@@ -1,5 +1,5 @@
 import {type Node} from '@sanity/comlink'
-import {beforeEach, describe, expect, it} from 'vitest'
+import {beforeEach, describe, expect, it, vi} from 'vitest'
 
 import {createSanityInstance, type SanityInstance} from '../../store/createSanityInstance'
 import {createStoreState} from '../../store/createStoreState'
@@ -10,7 +10,7 @@ describe('nodeStore', () => {
   let instance: SanityInstance
 
   beforeEach(() => {
-    instance = createSanityInstance({projectId: 'test-project-id', dataset: 'test-dataset'})
+    instance = createSanityInstance()
   })
 
   it('should have correct initial state', () => {

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

@@ -23,7 +23,7 @@ describe('getNodeState', () => {
   let instance: ReturnType<typeof createSanityInstance>
 
   beforeEach(() => {
-    instance = createSanityInstance({projectId: 'test', dataset: 'test'})
+    instance = createSanityInstance()
   })
 
   afterEach(() => {

package/src/config/__tests__/handles.test.ts

@@ -1,30 +1,24 @@
 import {describe, expect, it} from 'vitest'
 
-import {
-  createDatasetHandle,
-  createDocumentHandle,
-  createDocumentTypeHandle,
-  createProjectHandle,
-} from '../handles'
+import {createDocumentHandle, createDocumentTypeHandle, createResourceHandle} from '../handles'
 
 describe('handle creation functions', () => {
-  it('createProjectHandle returns input', () => {
-    const input = {projectId: 'test'}
-    expect(createProjectHandle(input)).toBe(input)
-  })
-
-  it('createDatasetHandle returns input', () => {
-    const input = {projectId: 'test', dataset: 'prod'}
-    expect(createDatasetHandle(input)).toBe(input)
-  })
-
   it('createDocumentTypeHandle returns input', () => {
-    const input = {documentType: 'movie'}
+    const input = {documentType: 'movie', resource: {projectId: 'p', dataset: 'd'}}
     expect(createDocumentTypeHandle(input)).toBe(input)
   })
 
   it('createDocumentHandle returns input', () => {
-    const input = {documentType: 'movie', documentId: '123'}
+    const input = {
+      documentType: 'movie',
+      documentId: '123',
+      resource: {projectId: 'p', dataset: 'd'},
+    }
     expect(createDocumentHandle(input)).toBe(input)
   })
+
+  it('createResourceHandle returns input', () => {
+    const input = {resource: {projectId: 'p', dataset: 'd'}}
+    expect(createResourceHandle(input)).toBe(input)
+  })
 })

package/src/config/handles.ts

@@ -1,9 +1,4 @@
-import {
-  type DatasetHandle,
-  type DocumentHandle,
-  type DocumentTypeHandle,
-  type ProjectHandle,
-} from './sanityConfig'
+import {type DocumentHandle, type DocumentTypeHandle, type ResourceHandle} from './sanityConfig'
 
 /**
  * Creates or validates a `DocumentHandle` object.
@@ -40,28 +35,15 @@ export function createDocumentTypeHandle<
 }
 
 /**
- * Creates or validates a `ProjectHandle` object.
- * Ensures the provided object conforms to the `ProjectHandle` interface.
- * @param handle - The object containing project identification properties.
- * @returns The validated `ProjectHandle` object.
+ * Creates or validates a `ResourceHandle` object.
+ * Ensures the provided object conforms to the `ResourceHandle` interface.
+ * @param handle - The object containing resource identification properties.
+ * @returns The validated `ResourceHandle` object.
  * @public
  */
-export function createProjectHandle<TProjectId extends string = string>(
-  handle: ProjectHandle<TProjectId>,
-): ProjectHandle<TProjectId> {
-  return handle
-}
-
-/**
- * Creates or validates a `DatasetHandle` object.
- * Ensures the provided object conforms to the `DatasetHandle` interface.
- * @param handle - The object containing dataset identification properties.
- * @returns The validated `DatasetHandle` object.
- * @public
- */
-export function createDatasetHandle<
+export function createResourceHandle<
   TDataset extends string = string,
   TProjectId extends string = string,
->(handle: DatasetHandle<TDataset, TProjectId>): DatasetHandle<TDataset, TProjectId> {
+>(handle: ResourceHandle<TProjectId, TDataset>): ResourceHandle<TProjectId, TDataset> {
   return handle
 }

package/src/config/sanityConfig.ts

@@ -23,6 +23,12 @@ export interface TokenSource {
  * @public
  */
 export interface StudioConfig {
+  /**
+   * Whether the Studio has already determined the user is authenticated.
+   * When `true` and the token source emits `null`, the SDK infers
+   * cookie-based auth is in use rather than transitioning to logged-out.
+   */
+  authenticated?: boolean
   /** Reactive auth token source from the Studio's auth store. */
   auth?: {
     /**
@@ -34,14 +40,12 @@ export interface StudioConfig {
      */
     token?: TokenSource
   }
-}
-
-/**
- * Represents the minimal configuration required to identify a Sanity project.
- * @public
- */
-export interface ProjectHandle<TProjectId extends string = string> {
-  projectId?: TProjectId
+  /**
+   * The project ID for this Studio workspace.
+   * Used to derive the localStorage key for studio auth token discovery
+   * (`__studio_auth_token_<projectId>`) and for project-specific API hostname requests.
+   */
+  projectId?: string
 }
 
 /**
@@ -56,20 +60,27 @@ export type ReleasePerspective = {
  * @public
  */
 export interface PerspectiveHandle {
-  perspective?: ClientPerspective | ReleasePerspective
+  /**
+   * The perspective to use for this operation.
+   * Note that the SDK stacks perspectives for you when querying.
+   * The SDK automatically fetches all of your content releases, and orders them the way the Sanity Studio does: usually by scheduled date, with ASAP releases coming first.
+   * @public
+   */
+  perspective?: Exclude<ClientPerspective, readonly unknown[]> | ReleasePerspective
 }
 
 /**
  * @public
  */
-export interface DatasetHandle<TDataset extends string = string, TProjectId extends string = string>
-  extends ProjectHandle<TProjectId>, PerspectiveHandle {
-  dataset?: TDataset
+export interface ResourceHandle<
+  TProjectId extends string = string,
+  TDataset extends string = string,
+> extends PerspectiveHandle {
   /**
-   * @beta
-   * Explicit source object to use for this operation.
+   * Explicit resource object to use for this operation.
+   * @public
    */
-  source?: DocumentSource
+  resource: DocumentResource<TProjectId, TDataset>
 }
 
 /**
@@ -82,7 +93,7 @@ export interface DocumentTypeHandle<
   TDocumentType extends string = string,
   TDataset extends string = string,
   TProjectId extends string = string,
-> extends DatasetHandle<TDataset, TProjectId> {
+> extends ResourceHandle<TDataset, TProjectId> {
   documentId?: string
   documentType: TDocumentType
   /**
@@ -108,13 +119,44 @@ export interface DocumentHandle<
 }
 
 /**
- * Represents the complete configuration for a Sanity SDK instance
+ * The key used to identify the default resource in a resources map.
+ * When no `resource` or `resourceName` is specified, the SDK resolves
+ * the resource registered under this name.
+ *
  * @public
  */
-export interface SanityConfig extends DatasetHandle, PerspectiveHandle {
+export const DEFAULT_RESOURCE_NAME = 'default'
+
+/**
+ * Represents the complete configuration for a Sanity SDK instance.
+ *
+ * Most apps configure resources via the `resources` prop on `SanityApp`:
+ *
+ * @example Typical React usage
+ * ```tsx
+ * <SanityApp
+ *   resources={{ default: { projectId: 'abc123', dataset: 'production' } }}
+ *   fallback={<Loading />}
+ * >
+ *   <App />
+ * </SanityApp>
+ * ```
+ *
+ * The `defaultResource` field is set automatically by the React layer from
+ * `resources['default']`. It can also be set directly when using the core
+ * SDK without React (e.g. in a Node.js script):
+ *
+ * @example Direct core usage (without React)
+ * ```ts
+ * const instance = createSanityInstance({
+ *   defaultResource: { projectId: 'abc123', dataset: 'production' },
+ * })
+ * ```
+ * @public
+ */
+export interface SanityConfig extends PerspectiveHandle {
   /**
    * Authentication configuration for the instance
-   * @remarks Merged with parent configurations when using createChild
    */
   auth?: AuthConfig
   /**
@@ -126,64 +168,69 @@ export interface SanityConfig extends DatasetHandle, PerspectiveHandle {
    * `SDKStudioContext` provider. Can also be set explicitly for programmatic use.
    */
   studio?: StudioConfig
-
-  /**
-   * Studio mode configuration for use of the SDK in a Sanity Studio.
-   * @remarks Controls whether studio mode features are enabled.
-   * @deprecated Use `studio` instead, which provides richer integration
-   * with the Studio's workspace (auth token sync, etc.).
-   */
-  studioMode?: {
-    enabled: boolean
-  }
-
   /**
-   * @beta
-   * A list of named sources to use for this instance.
+   * The default document resource for this instance. Used by bound actions
+   * when no explicit resource is provided.
+   *
+   * @public
    */
-  sources?: Record<string, DocumentSource>
+  defaultResource?: DocumentResource
 }
 
 /**
- * A document source can be used for querying.
- * This will soon be the default way to identify where you are querying from.
+ * A document resource identifies where data is stored and queried from.
+ * Can be a dataset (project + dataset pair), a media library, or a canvas.
  *
- * @beta
+ * @public
  */
-export type DocumentSource = DatasetSource | MediaLibrarySource | CanvasSource
+export type DocumentResource<
+  TProjectId extends string = string,
+  TDataset extends string = string,
+> = DatasetResource<TProjectId, TDataset> | MediaLibraryResource | CanvasResource
 
 /**
- * @beta
+ * A resource that targets a specific project and dataset.
+ * @public
  */
-export type DatasetSource = {projectId: string; dataset: string}
+export type DatasetResource<
+  TProjectId extends string = string,
+  TDataset extends string = string,
+> = {projectId: TProjectId; dataset: TDataset}
 
 /**
- * @beta
+ * A resource that targets a media library.
+ * @public
  */
-export type MediaLibrarySource = {mediaLibraryId: string}
+export type MediaLibraryResource = {mediaLibraryId: string}
 
 /**
- * @beta
+ * A resource that targets a canvas.
+ * @public
  */
-export type CanvasSource = {canvasId: string}
+export type CanvasResource = {canvasId: string}
 
 /**
- * @beta
+ * Type guard that checks whether a {@link DocumentResource} is a {@link DatasetResource}.
+ * @public
  */
-export function isDatasetSource(source: DocumentSource): source is DatasetSource {
-  return 'projectId' in source && 'dataset' in source
+export function isDatasetResource(resource: DocumentResource): resource is DatasetResource {
+  return 'projectId' in resource && 'dataset' in resource
 }
 
 /**
- * @beta
+ * Type guard that checks whether a {@link DocumentResource} is a {@link MediaLibraryResource}.
+ * @public
  */
-export function isMediaLibrarySource(source: DocumentSource): source is MediaLibrarySource {
-  return 'mediaLibraryId' in source
+export function isMediaLibraryResource(
+  resource: DocumentResource,
+): resource is MediaLibraryResource {
+  return 'mediaLibraryId' in resource
 }
 
 /**
- * @beta
+ * Type guard that checks whether a {@link DocumentResource} is a {@link CanvasResource}.
+ * @public
  */
-export function isCanvasSource(source: DocumentSource): source is CanvasSource {
-  return 'canvasId' in source
+export function isCanvasResource(resource: DocumentResource): resource is CanvasResource {
+  return 'canvasId' in resource
 }

package/src/datasets/datasets.test.ts

@@ -11,7 +11,7 @@ vi.mock('../client/clientStore')
 
 describe('datasets', () => {
   it('calls the `client.observable.datasets.list` method on the client and returns the result', async () => {
-    const instance = createSanityInstance({projectId: 'p', dataset: 'd'})
+    const instance = createSanityInstance()
     const datasets = [{id: 'a'}, {id: 'b'}]
     const list = vi.fn().mockReturnValue(of(datasets))
 
@@ -25,7 +25,7 @@ describe('datasets', () => {
       observable: of(mockClient),
     } as StateSource<SanityClient>)
 
-    const result = await resolveDatasets(instance)
+    const result = await resolveDatasets(instance, {projectId: 'p'})
     expect(result).toEqual(datasets)
     expect(list).toHaveBeenCalled()
   })

package/src/datasets/datasets.ts

@@ -1,7 +1,6 @@
 import {switchMap} from 'rxjs'
 
 import {getClientState} from '../client/clientStore'
-import {type ProjectHandle} from '../config/sanityConfig'
 import {createFetcherStore} from '../utils/createFetcherStore'
 
 const API_VERSION = 'v2025-02-19'
@@ -9,18 +8,13 @@ const API_VERSION = 'v2025-02-19'
 /** @public */
 export const datasets = createFetcherStore({
   name: 'Datasets',
-  getKey: (instance, options?: ProjectHandle) => {
-    const projectId = options?.projectId ?? instance.config.projectId
-    if (!projectId) {
-      throw new Error('A projectId is required to use the project API.')
-    }
-    return projectId
+  getKey: (_instance, options: {projectId: string}) => {
+    return options.projectId
   },
-  fetcher: (instance) => (options?: ProjectHandle) => {
+  fetcher: (instance) => (options: {projectId: string}) => {
     return getClientState(instance, {
       apiVersion: API_VERSION,
-      // non-null assertion is fine because we check above
-      projectId: (options?.projectId ?? instance.config.projectId)!,
+      projectId: options.projectId,
       useProjectHostname: true,
     }).observable.pipe(switchMap((client) => client.observable.datasets.list()))
   },