@sanity/sdk 2.5.0 → 2.7.0

package/src/client/clientStore.test.ts

@@ -3,7 +3,6 @@ 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'
 
@@ -34,7 +33,10 @@ beforeEach(() => {
   vi.mocked(createClient).mockImplementation(
     (clientConfig) => ({config: () => clientConfig}) as SanityClient,
   )
-  instance = createSanityInstance({projectId: 'test-project', dataset: 'test-dataset'})
+  instance = createSanityInstance({
+    projectId: 'test-project',
+    dataset: 'test-dataset',
+  })
 })
 
 afterEach(() => {
@@ -176,18 +178,15 @@ describe('clientStore', () => {
 
   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})
+      const client = getClient(instance, {
+        apiVersion: '2024-11-12',
+        source: {projectId: 'source-project', dataset: 'source-dataset'},
+      })
 
       expect(vi.mocked(createClient)).toHaveBeenCalledWith(
         expect.objectContaining({
-          apiVersion: '2024-11-12',
-          source: expect.objectContaining({
-            __sanity_internal_sourceId: {
-              projectId: 'source-project',
-              dataset: 'source-dataset',
-            },
-          }),
+          'apiVersion': '2024-11-12',
+          '~experimental_resource': {type: 'dataset', id: 'source-project.source-dataset'},
         }),
       )
       // Client should be projectless - no projectId/dataset in config
@@ -195,19 +194,16 @@ describe('clientStore', () => {
       expect(client.config()).not.toHaveProperty('dataset')
       expect(client.config()).toEqual(
         expect.objectContaining({
-          source: expect.objectContaining({
-            __sanity_internal_sourceId: {
-              projectId: 'source-project',
-              dataset: 'source-dataset',
-            },
-          }),
+          '~experimental_resource': {type: 'dataset', id: 'source-project.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})
+      const client = getClient(instance, {
+        apiVersion: '2024-11-12',
+        source: {mediaLibraryId: 'media-lib-123'},
+      })
 
       expect(vi.mocked(createClient)).toHaveBeenCalledWith(
         expect.objectContaining({
@@ -226,8 +222,10 @@ describe('clientStore', () => {
     })
 
     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})
+      const client = getClient(instance, {
+        apiVersion: '2024-11-12',
+        source: {canvasId: 'canvas-123'},
+      })
 
       expect(vi.mocked(createClient)).toHaveBeenCalledWith(
         expect.objectContaining({
@@ -246,30 +244,26 @@ describe('clientStore', () => {
     })
 
     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})
+      const client = getClient(instance, {
+        apiVersion: '2024-11-12',
+        source: {projectId: 'source-project', dataset: 'source-dataset'},
+      })
 
       // 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',
-            },
-          }),
+          '~experimental_resource': {type: 'dataset', id: 'source-project.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,
+        source: {projectId: 'source-project', dataset: 'source-dataset'},
         projectId: 'explicit-project',
         dataset: 'explicit-dataset',
       })
@@ -284,13 +278,18 @@ describe('clientStore', () => {
     })
 
     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})
+      const client1 = getClient(instance, {
+        apiVersion: '2024-11-12',
+        source: {projectId: 'source-project', dataset: 'source-dataset'},
+      })
+      const client2 = getClient(instance, {
+        apiVersion: '2024-11-12',
+        source: {mediaLibraryId: 'media-lib-123'},
+      })
+      const client3 = getClient(instance, {
+        apiVersion: '2024-11-12',
+        source: {canvasId: 'canvas-123'},
+      })
 
       expect(client1).not.toBe(client2)
       expect(client2).not.toBe(client3)
@@ -299,11 +298,14 @@ describe('clientStore', () => {
     })
 
     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)
+      const client1 = getClient(instance, {
+        apiVersion: '2024-11-12',
+        source: {projectId: 'source-project', dataset: 'source-dataset'},
+      })
+      const client2 = getClient(instance, {
+        apiVersion: '2024-11-12',
+        source: {projectId: 'source-project', dataset: 'source-dataset'},
+      })
 
       expect(client1).toBe(client2)
       expect(vi.mocked(createClient)).toHaveBeenCalledTimes(1)

package/src/client/clientStore.ts

@@ -2,7 +2,12 @@ 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 {
+  type DocumentSource,
+  isCanvasSource,
+  isDatasetSource,
+  isMediaLibrarySource,
+} from '../config/sanityConfig'
 import {bindActionGlobally} from '../store/createActionBinder'
 import {createStateSourceAction} from '../store/createStateSourceAction'
 import {defineStore, type StoreContext} from '../store/defineStore'
@@ -61,6 +66,11 @@ 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.
  *
@@ -170,13 +180,17 @@ 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
+    let resource: ClientResource | 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}
+      }
     }
 
     const projectId = options.projectId ?? instance.config.projectId
@@ -185,7 +199,7 @@ export const getClient = bindActionGlobally(
 
     const effectiveOptions: ClientOptions = {
       ...DEFAULT_CLIENT_CONFIG,
-      ...((options.scope === 'global' || !projectId || hasSource) && {useProjectHostname: false}),
+      ...((options.scope === 'global' || !projectId || resource) && {useProjectHostname: false}),
       token: authMethod === 'cookie' ? undefined : (tokenFromState ?? undefined),
       ...options,
       ...(projectId && {projectId}),
@@ -197,7 +211,7 @@ export const getClient = bindActionGlobally(
     // 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 (resource) {
       if (options.projectId || options.dataset) {
         // eslint-disable-next-line no-console
         console.warn(

package/src/config/loggingConfig.ts

@@ -0,0 +1,149 @@
+/**
+ * Public API for configuring SDK logging
+ *
+ * @module loggingConfig
+ */
+
+import {configureLogging as _configureLogging, type LoggerConfig} from '../utils/logger'
+
+/**
+ * Configure logging for the Sanity SDK
+ *
+ * This function allows you to control what logs are output by the SDK,
+ * making it easier to debug issues in development or production.
+ *
+ * @remarks
+ * **Zero-Config via Environment Variable (Recommended):**
+ *
+ * The SDK automatically reads the `DEBUG` environment variable, making it
+ * easy to enable logging without code changes:
+ *
+ * ```bash
+ * # Enable all SDK logging at debug level
+ * DEBUG=sanity:* npm start
+ *
+ * # Enable specific namespaces
+ * DEBUG=sanity:auth,sanity:document npm start
+ *
+ * # Enable trace level for all namespaces
+ * DEBUG=sanity:trace:* npm start
+ *
+ * # Enable internal/maintainer logs
+ * DEBUG=sanity:*:internal npm start
+ * ```
+ *
+ * This matches the pattern used by Sanity CLI and Studio, making it familiar
+ * and easy for support teams to help troubleshoot issues.
+ *
+ * **Programmatic Configuration (Advanced):**
+ *
+ * For more control (custom handlers, dynamic configuration), call this function
+ * explicitly. Programmatic configuration overrides environment variables.
+ *
+ * **For Application Developers:**
+ * Use `info`, `warn`, or `error` levels to see high-level SDK activity
+ * without being overwhelmed by internal details.
+ *
+ * **For SDK Maintainers:**
+ * Use `debug` or `trace` levels with `internal: true` to see detailed
+ * information about store operations, RxJS streams, and state transitions.
+ *
+ * **Instance Context:**
+ * Logs automatically include instance information (projectId, dataset, instanceId)
+ * when available, making it easier to debug multi-instance scenarios:
+ * ```
+ * [INFO] [auth] [project:abc] [dataset:production] User logged in
+ * ```
+ *
+ * **Available Namespaces:**
+ * - `sdk` - SDK initialization, configuration, and lifecycle
+ * - `auth` - Authentication and authorization (when instrumented in the future)
+ * - And more as logging is added to modules
+ *
+ * @example Zero-config via environment variable (recommended for debugging)
+ * ```bash
+ * # Just set DEBUG and run your app - no code changes needed!
+ * DEBUG=sanity:* npm start
+ * ```
+ *
+ * @example Programmatic configuration (application developer)
+ * ```ts
+ * import {configureLogging} from '@sanity/sdk'
+ *
+ * // Log warnings and errors for auth and document operations
+ * configureLogging({
+ *   level: 'warn',
+ *   namespaces: ['auth', 'document']
+ * })
+ * ```
+ *
+ * @example Programmatic configuration (SDK maintainer)
+ * ```ts
+ * import {configureLogging} from '@sanity/sdk'
+ *
+ * // Enable all logs including internal traces
+ * configureLogging({
+ *   level: 'trace',
+ *   namespaces: ['*'],
+ *   internal: true
+ * })
+ * ```
+ *
+ * @example Custom handler (for testing)
+ * ```ts
+ * import {configureLogging} from '@sanity/sdk'
+ *
+ * const logs: string[] = []
+ * configureLogging({
+ *   level: 'info',
+ *   namespaces: ['*'],
+ *   handler: {
+ *     error: (msg) => logs.push(msg),
+ *     warn: (msg) => logs.push(msg),
+ *     info: (msg) => logs.push(msg),
+ *     debug: (msg) => logs.push(msg),
+ *     trace: (msg) => logs.push(msg),
+ *   }
+ * })
+ * ```
+ *
+ * @public
+ */
+export function configureLogging(config: LoggerConfig): void {
+  _configureLogging(config)
+
+  // Always log configuration (bypasses namespace filtering)
+  // This ensures users see the message regardless of which namespaces they enable
+  const configLevel = config.level || 'warn'
+  const shouldLog = ['info', 'debug', 'trace'].includes(configLevel) || configLevel === 'warn'
+
+  if (shouldLog && config.handler?.info) {
+    config.handler.info(`[${new Date().toISOString()}] [INFO] [sdk] Logging configured`, {
+      level: configLevel,
+      namespaces: config.namespaces || [],
+      internal: config.internal || false,
+      source: 'programmatic',
+    })
+  } else if (shouldLog) {
+    // eslint-disable-next-line no-console
+    console.info(`[${new Date().toISOString()}] [INFO] [sdk] Logging configured`, {
+      level: configLevel,
+      namespaces: config.namespaces || [],
+      internal: config.internal || false,
+      source: 'programmatic',
+    })
+  }
+}
+
+/**
+ * Re-export types for public API
+ * @public
+ */
+export type {
+  InstanceContext,
+  LogContext,
+  Logger,
+  LoggerConfig,
+  LogLevel,
+  LogNamespace,
+} from '../utils/logger'

package/src/config/sanityConfig.ts

@@ -2,6 +2,40 @@ import {type ClientPerspective, type StackablePerspective} from '@sanity/client'
 
 import {type AuthConfig} from './authConfig'
 
+/**
+ * A minimal Observable-compatible interface for subscribing to token changes.
+ * Any object with a `subscribe` method that follows this contract will work,
+ * including RxJS Observables. This avoids coupling the SDK to a specific
+ * reactive library.
+ *
+ * @public
+ */
+export interface TokenSource {
+  /** Subscribe to token emissions. Emits `null` when logged out. */
+  subscribe(observer: {next: (token: string | null) => void}): {unsubscribe(): void}
+}
+
+/**
+ * Studio-specific configuration for the SDK.
+ * When present, the SDK operates in studio mode and derives auth from the
+ * provided token source instead of discovering tokens independently.
+ *
+ * @public
+ */
+export interface StudioConfig {
+  /** Reactive auth token source from the Studio's auth store. */
+  auth?: {
+    /**
+     * A reactive token source. The SDK subscribes and stays in sync — the
+     * Studio is the single authority for auth and handles token refresh.
+     *
+     * Optional because older Studios may not expose it. When absent, the
+     * SDK falls back to localStorage/cookie discovery.
+     */
+    token?: TokenSource
+  }
+}
+
 /**
  * Represents the minimal configuration required to identify a Sanity project.
  * @public
@@ -31,6 +65,11 @@ export interface PerspectiveHandle {
 export interface DatasetHandle<TDataset extends string = string, TProjectId extends string = string>
   extends ProjectHandle<TProjectId>, PerspectiveHandle {
   dataset?: TDataset
+  /**
+   * @beta
+   * Explicit source object to use for this operation.
+   */
+  source?: DocumentSource
 }
 
 /**
@@ -79,51 +118,72 @@ export interface SanityConfig extends DatasetHandle, PerspectiveHandle {
    */
   auth?: AuthConfig
   /**
-   * Studio mode configuration for use of the SDK in a Sanity Studio
-   * @remarks Controls whether studio mode features are enabled
+   * Studio configuration provided by a Sanity Studio workspace.
+   * When present, the SDK operates in studio mode and derives auth from the
+   * workspace's reactive token source — no manual configuration needed.
+   *
+   * @remarks Typically set automatically by `SanityApp` when it detects an
+   * `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
   }
-}
 
-export const SOURCE_ID = '__sanity_internal_sourceId'
+  /**
+   * @beta
+   * A list of named sources to use for this instance.
+   */
+  sources?: Record<string, DocumentSource>
+}
 
 /**
  * A document source can be used for querying.
+ * This will soon be the default way to identify where you are querying from.
  *
  * @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}
-}
+export type DocumentSource = DatasetSource | MediaLibrarySource | CanvasSource
 
 /**
- * Returns a document source for a projectId and dataset.
- *
  * @beta
  */
-export function datasetSource(projectId: string, dataset: string): DocumentSource {
-  return {[SOURCE_ID]: {projectId, dataset}}
+export type DatasetSource = {projectId: string; dataset: string}
+
+/**
+ * @beta
+ */
+export type MediaLibrarySource = {mediaLibraryId: string}
+
+/**
+ * @beta
+ */
+export type CanvasSource = {canvasId: string}
+
+/**
+ * @beta
+ */
+export function isDatasetSource(source: DocumentSource): source is DatasetSource {
+  return 'projectId' in source && 'dataset' in source
 }
 
 /**
- * Returns a document source for a Media Library.
- *
  * @beta
  */
-export function mediaLibrarySource(id: string): DocumentSource {
-  return {[SOURCE_ID]: ['media-library', id]}
+export function isMediaLibrarySource(source: DocumentSource): source is MediaLibrarySource {
+  return 'mediaLibraryId' in source
 }
 
 /**
- * Returns a document source for a Canvas.
- *
  * @beta
  */
-export function canvasSource(id: string): DocumentSource {
-  return {[SOURCE_ID]: ['canvas', id]}
+export function isCanvasSource(source: DocumentSource): source is CanvasSource {
+  return 'canvasId' in source
 }

package/src/projection/getProjectionState.ts

@@ -1,8 +1,9 @@
+import {DocumentId, getPublishedId} from '@sanity/id-utils'
 import {type SanityProjectionResult} from 'groq'
 import {omit} from 'lodash-es'
 
 import {type DocumentHandle} from '../config/sanityConfig'
-import {bindActionByDataset} from '../store/createActionBinder'
+import {bindActionBySourceAndPerspective} from '../store/createActionBinder'
 import {type SanityInstance} from '../store/createSanityInstance'
 import {
   createStateSourceAction,
@@ -10,7 +11,7 @@ import {
   type StateSource,
 } from '../store/createStateSourceAction'
 import {hashString} from '../utils/hashString'
-import {getPublishedId, insecureRandomId} from '../utils/ids'
+import {insecureRandomId} from '../utils/ids'
 import {projectionStore} from './projectionStore'
 import {type ProjectionStoreState, type ProjectionValuePending} from './types'
 import {PROJECTION_STATE_CLEAR_DELAY, STABLE_EMPTY_PROJECTION, validateProjection} from './util'
@@ -70,21 +71,21 @@ export function getProjectionState(
 /**
  * @beta
  */
-export const _getProjectionState = bindActionByDataset(
+export const _getProjectionState = bindActionBySourceAndPerspective(
   projectionStore,
   createStateSourceAction({
     selector: (
       {state}: SelectorContext<ProjectionStoreState>,
       options: ProjectionOptions<string, string, string, string>,
     ): ProjectionValuePending<object> | undefined => {
-      const documentId = getPublishedId(options.documentId)
+      const documentId = getPublishedId(DocumentId(options.documentId))
       const projectionHash = hashString(options.projection)
       return state.values[documentId]?.[projectionHash] ?? STABLE_EMPTY_PROJECTION
     },
     onSubscribe: ({state}, options: ProjectionOptions<string, string, string, string>) => {
       const {projection, ...docHandle} = options
       const subscriptionId = insecureRandomId()
-      const documentId = getPublishedId(docHandle.documentId)
+      const documentId = getPublishedId(DocumentId(docHandle.documentId))
       const validProjection = validateProjection(projection)
       const projectionHash = hashString(validProjection)