@sanity/sdk 2.5.0 → 2.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanity/sdk",
-  "version": "2.5.0",
+  "version": "2.6.0",
   "private": false,
   "description": "Sanity SDK",
   "keywords": [
@@ -51,7 +51,7 @@
     "@sanity/json-match": "^1.0.5",
     "@sanity/message-protocol": "^0.18.0",
     "@sanity/mutate": "^0.12.4",
-    "@sanity/types": "^3.83.0",
+    "@sanity/types": "^5.2.0",
     "groq": "3.88.1-typegen-experimental.0",
     "groq-js": "^1.19.0",
     "lodash-es": "^4.17.21",
@@ -72,10 +72,10 @@
     "vite": "^6.3.4",
     "vitest": "^3.2.4",
     "@repo/config-eslint": "0.0.0",
-    "@repo/config-test": "0.0.1",
     "@repo/package.bundle": "3.82.0",
+    "@repo/tsconfig": "0.0.1",
     "@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

@@ -76,13 +76,25 @@ export {
   createProjectHandle,
 } from '../config/handles'
 export {
-  canvasSource,
+  configureLogging,
+  type InstanceContext,
+  type LogContext,
+  type Logger,
+  type LoggerConfig,
+  type LogLevel,
+  type LogNamespace,
+} from '../config/loggingConfig'
+export {
+  type CanvasSource,
   type DatasetHandle,
-  datasetSource,
+  type DatasetSource,
   type DocumentHandle,
   type DocumentSource,
   type DocumentTypeHandle,
-  mediaLibrarySource,
+  isCanvasSource,
+  isDatasetSource,
+  isMediaLibrarySource,
+  type MediaLibrarySource,
   type PerspectiveHandle,
   type ProjectHandle,
   type ReleasePerspective,

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

@@ -31,6 +31,16 @@ export interface PerspectiveHandle {
 export interface DatasetHandle<TDataset extends string = string, TProjectId extends string = string>
   extends ProjectHandle<TProjectId>, PerspectiveHandle {
   dataset?: TDataset
+  /**
+   * @beta
+   * The name of the source to use for this operation.
+   */
+  sourceName?: string
+  /**
+   * @beta
+   * Explicit source object to use for this operation.
+   */
+  source?: DocumentSource
 }
 
 /**
@@ -85,45 +95,54 @@ export interface SanityConfig extends DatasetHandle, PerspectiveHandle {
   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
+
+/**
+ * @beta
+ */
+export type DatasetSource = {projectId: string; dataset: string}
+
+/**
+ * @beta
+ */
+export type MediaLibrarySource = {mediaLibraryId: string}
 
 /**
- * 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 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/query/queryStore.ts

@@ -58,7 +58,9 @@ export interface QueryOptions<
   TQuery extends string = string,
   TDataset extends string = string,
   TProjectId extends string = string,
-> extends Pick<ResponseQueryOptions, 'useCdn' | 'cache' | 'next' | 'cacheMode' | 'tag'>,
+>
+  extends
+    Pick<ResponseQueryOptions, 'useCdn' | 'cache' | 'next' | 'cacheMode' | 'tag'>,
     DatasetHandle<TDataset, TProjectId> {
   query: TQuery
   params?: Record<string, unknown>

package/src/store/createActionBinder.ts

@@ -1,4 +1,9 @@
-import {type DocumentSource, SOURCE_ID} from '../config/sanityConfig'
+import {
+  type DocumentSource,
+  isCanvasSource,
+  isDatasetSource,
+  isMediaLibrarySource,
+} from '../config/sanityConfig'
 import {type SanityInstance} from './createSanityInstance'
 import {createStoreInstance, type StoreInstance} from './createStoreInstance'
 import {type StoreState} from './createStoreState'
@@ -157,12 +162,18 @@ export const bindActionBySource = createActionBinder<
   [{source?: DocumentSource}, ...unknown[]]
 >((instance, {source}) => {
   if (source) {
-    const id = source[SOURCE_ID]
-    if (!id) throw new Error('Invalid source (missing ID information)')
-    if (Array.isArray(id)) return {name: id.join(':')}
-    return {name: `${id.projectId}.${id.dataset}`}
-  }
+    let id: string | undefined
+    if (isDatasetSource(source)) {
+      id = `${source.projectId}.${source.dataset}`
+    } else if (isMediaLibrarySource(source)) {
+      id = `media-library:${source.mediaLibraryId}`
+    } else if (isCanvasSource(source)) {
+      id = `canvas:${source.canvasId}`
+    }
 
+    if (!id) throw new Error(`Received invalid source: ${JSON.stringify(source)}`)
+    return {name: id}
+  }
   const {projectId, dataset} = instance.config
 
   if (!projectId || !dataset) {

package/src/store/createSanityInstance.test.ts

@@ -1,5 +1,6 @@
-import {describe, expect, it, vi} from 'vitest'
+import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest'
 
+import {configureLogging, type LogHandler, resetLogging} from '../utils/logger'
 import {createSanityInstance} from './createSanityInstance'
 
 describe('createSanityInstance', () => {
@@ -81,4 +82,87 @@ describe('createSanityInstance', () => {
     const child = parent.createChild({auth: {token: 'my-token'}})
     expect(child.config.auth).toEqual({apiHost: 'api.sanity.work', token: 'my-token'})
   })
+
+  describe('logging', () => {
+    const mockHandler: LogHandler = {
+      error: vi.fn(),
+      warn: vi.fn(),
+      info: vi.fn(),
+      debug: vi.fn(),
+      trace: vi.fn(),
+    }
+
+    beforeEach(() => {
+      vi.clearAllMocks()
+      configureLogging({
+        level: 'debug',
+        namespaces: ['sdk'],
+        handler: mockHandler,
+      })
+    })
+
+    afterEach(() => {
+      resetLogging()
+    })
+
+    it('should log instance creation at info level', () => {
+      createSanityInstance({projectId: 'test-proj', dataset: 'test-ds'})
+
+      expect(mockHandler.info).toHaveBeenCalledWith(
+        expect.stringContaining('[INFO] [sdk]'),
+        expect.objectContaining({
+          hasProjectId: true,
+          hasDataset: true,
+        }),
+      )
+    })
+
+    it('should log configuration details at debug level', () => {
+      createSanityInstance({projectId: 'test-proj', dataset: 'test-ds'})
+
+      expect(mockHandler.debug).toHaveBeenCalledWith(
+        expect.stringContaining('[DEBUG] [sdk]'),
+        expect.objectContaining({
+          projectId: 'test-proj',
+          dataset: 'test-ds',
+        }),
+      )
+    })
+
+    it('should log instance disposal', () => {
+      const instance = createSanityInstance({projectId: 'test-proj'})
+      vi.clearAllMocks() // Clear creation logs
+
+      instance.dispose()
+
+      expect(mockHandler.info).toHaveBeenCalledWith(
+        expect.stringContaining('Instance disposed'),
+        expect.anything(),
+      )
+    })
+
+    it('should log child instance creation at debug level', () => {
+      const parent = createSanityInstance({projectId: 'parent-proj'})
+      vi.clearAllMocks() // Clear parent creation logs
+
+      parent.createChild({dataset: 'child-ds'})
+
+      expect(mockHandler.debug).toHaveBeenCalledWith(
+        expect.stringContaining('Creating child instance'),
+        expect.objectContaining({
+          overridingDataset: true,
+        }),
+      )
+    })
+
+    it('should include instance context in logs', () => {
+      createSanityInstance({projectId: 'my-project', dataset: 'my-dataset'})
+
+      // Check that logs include the instance context (project and dataset)
+      expect(mockHandler.info).toHaveBeenCalledWith(
+        expect.stringMatching(/\[project:my-project\].*\[dataset:my-dataset\]/),
+        expect.anything(),
+      )
+    })
+  })
 })