@sanity/sdk 2.4.0 → 2.6.0

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

@@ -49,7 +49,7 @@ describe('getOrCreateChannel', () => {
   it('should create a new channel using the controller', () => {
     const createChannelSpy = vi.spyOn(mockController, 'createChannel')
 
-    const channel = getOrCreateChannel({state, instance}, channelConfig)
+    const channel = getOrCreateChannel({state, instance, key: null}, channelConfig)
 
     expect(createChannelSpy).toHaveBeenCalledWith(channelConfig)
     expect(channel.on).toBeDefined()
@@ -70,17 +70,17 @@ describe('getOrCreateChannel', () => {
       channels: new Map(),
     })
 
-    expect(() => getOrCreateChannel({state, instance}, channelConfig)).toThrow(
+    expect(() => getOrCreateChannel({state, instance, key: null}, channelConfig)).toThrow(
       'Controller must be initialized before using or creating channels',
     )
   })
 
   it('should retrieve channel directly from store once created', () => {
-    const createdChannel = getOrCreateChannel({state, instance}, channelConfig)
+    const createdChannel = getOrCreateChannel({state, instance, key: null}, channelConfig)
     vi.clearAllMocks() // Clear call counts
 
     // Retrieve channel again
-    const retrievedChannel = getOrCreateChannel({state, instance}, channelConfig)
+    const retrievedChannel = getOrCreateChannel({state, instance, key: null}, channelConfig)
     expect(retrievedChannel).toBeDefined()
     expect(retrievedChannel).toBe(createdChannel)
 
@@ -95,10 +95,10 @@ describe('getOrCreateChannel', () => {
   })
 
   it('should throw error when trying to create channel with different options', () => {
-    getOrCreateChannel({state, instance}, channelConfig)
+    getOrCreateChannel({state, instance, key: null}, channelConfig)
 
     expect(() =>
-      getOrCreateChannel({state, instance}, {...channelConfig, connectTo: 'window'}),
+      getOrCreateChannel({state, instance, key: null}, {...channelConfig, connectTo: 'window'}),
     ).toThrow('Channel "test" already exists with different options')
   })
 })

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

@@ -43,7 +43,7 @@ describe('getOrCreateController', () => {
     const controllerSpy = vi.spyOn(comlink, 'createController')
     const targetOrigin = 'https://test.sanity.dev'
 
-    const controller = getOrCreateController({state, instance}, targetOrigin)
+    const controller = getOrCreateController({state, instance, key: null}, targetOrigin)
 
     expect(controllerSpy).toHaveBeenCalledWith({targetOrigin})
     expect(controller).toBeDefined()
@@ -56,8 +56,8 @@ describe('getOrCreateController', () => {
     const controllerSpy = vi.spyOn(comlink, 'createController')
     const targetOrigin = 'https://test.sanity.dev'
 
-    const firstController = getOrCreateController({state, instance}, targetOrigin)
-    const secondController = getOrCreateController({state, instance}, targetOrigin)
+    const firstController = getOrCreateController({state, instance, key: null}, targetOrigin)
+    const secondController = getOrCreateController({state, instance, key: null}, targetOrigin)
 
     expect(controllerSpy).toHaveBeenCalledTimes(1)
     expect(firstController).toBe(secondController)
@@ -68,9 +68,9 @@ describe('getOrCreateController', () => {
     const targetOrigin = 'https://test.sanity.dev'
     const targetOrigin2 = 'https://test2.sanity.dev'
 
-    const firstController = getOrCreateController({state, instance}, targetOrigin)
+    const firstController = getOrCreateController({state, instance, key: null}, targetOrigin)
     const destroySpy = vi.spyOn(firstController, 'destroy')
-    const secondController = getOrCreateController({state, instance}, targetOrigin2)
+    const secondController = getOrCreateController({state, instance, key: null}, targetOrigin2)
 
     expect(controllerSpy).toHaveBeenCalledTimes(2)
     expect(destroySpy).toHaveBeenCalled()

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

@@ -21,7 +21,7 @@ export const getOrCreateController = (
   // if the target origin has changed, we'll create a new controller,
   // but need to clean up first
   if (controller) {
-    destroyController({state, instance})
+    destroyController({state, instance, key: undefined})
   }
 
   const newController = createController({targetOrigin})

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

@@ -19,6 +19,7 @@ const channelConfig = {
 describe('releaseChannel', () => {
   let instance: SanityInstance
   let store: StoreInstance<ComlinkControllerState>
+  const key = {name: 'global', projectId: 'test-project-id', dataset: 'test-dataset'}
 
   let getOrCreateChannel: (
     inst: SanityInstance,
@@ -29,14 +30,14 @@ describe('releaseChannel', () => {
 
   beforeEach(() => {
     instance = createSanityInstance({projectId: 'test-project-id', dataset: 'test-dataset'})
-    store = createStoreInstance(instance, comlinkControllerStore)
+    store = createStoreInstance(instance, key, comlinkControllerStore)
 
     const bind =
       <TParams extends unknown[], TReturn>(
         action: StoreAction<ComlinkControllerState, TParams, TReturn>,
       ) =>
       (inst: SanityInstance, ...params: TParams) =>
-        action({instance: inst, state: store.state}, ...params)
+        action({instance: inst, state: store.state, key}, ...params)
 
     getOrCreateChannel = bind(unboundGetOrCreateChannel)
     getOrCreateController = bind(unboundGetOrCreateController)

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

@@ -31,7 +31,7 @@ describe('comlinkControllerStore', () => {
 
     // Create store state directly
     const state = createStoreState<ComlinkControllerState>(
-      comlinkControllerStore.getInitialState(instance),
+      comlinkControllerStore.getInitialState(instance, null),
     )
 
     const initialState = state.get()
@@ -56,13 +56,13 @@ describe('comlinkControllerStore', () => {
     vi.mocked(bindActionGlobally).mockImplementation(
       (_storeDef, action) =>
         (inst: SanityInstance, ...params: unknown[]) =>
-          action({instance: inst, state}, ...params),
+          action({instance: inst, state, key: {name: 'global'}}, ...params),
     )
 
     const {comlinkControllerStore} = await import('./comlinkControllerStore')
 
     // Get the cleanup function from the store
-    const dispose = comlinkControllerStore.initialize?.({state, instance})
+    const dispose = comlinkControllerStore.initialize?.({state, instance, key: null})
 
     // Run cleanup
     dispose?.()
@@ -82,7 +82,7 @@ describe('comlinkControllerStore', () => {
     })
 
     // Get the cleanup function
-    const cleanup = comlinkControllerStore.initialize?.({state, instance})
+    const cleanup = comlinkControllerStore.initialize?.({state, instance, key: null})
 
     // Should not throw when no controller exists
     expect(() => cleanup?.()).not.toThrow()

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

@@ -40,24 +40,24 @@ describe('getOrCreateNode', () => {
   })
 
   it('should create and start a node', () => {
-    const node = getOrCreateNode({state, instance}, nodeConfig)
+    const node = getOrCreateNode({state, instance, key: null}, nodeConfig)
 
     expect(comlink.createNode).toHaveBeenCalledWith(nodeConfig)
     expect(node.start).toHaveBeenCalled()
   })
 
   it('should store the node in nodeStore', () => {
-    const node = getOrCreateNode({state, instance}, nodeConfig)
+    const node = getOrCreateNode({state, instance, key: null}, nodeConfig)
 
-    expect(getOrCreateNode({state, instance}, nodeConfig)).toBe(node)
+    expect(getOrCreateNode({state, instance, key: null}, nodeConfig)).toBe(node)
   })
 
   it('should throw error when trying to create node with different options', () => {
-    getOrCreateNode({state, instance}, nodeConfig)
+    getOrCreateNode({state, instance, key: null}, nodeConfig)
 
     expect(() =>
       getOrCreateNode(
-        {state, instance},
+        {state, instance, key: null},
         {
           ...nodeConfig,
           connectTo: 'window',
@@ -74,7 +74,7 @@ describe('getOrCreateNode', () => {
       return statusUnsubMock
     })
 
-    getOrCreateNode({state, instance}, nodeConfig)
+    getOrCreateNode({state, instance, key: null}, nodeConfig)
 
     expect(mockNode.onStatus).toHaveBeenCalled()
     expect(state.get().nodes.get(nodeConfig.name)?.statusUnsub).toBe(statusUnsubMock)
@@ -92,7 +92,7 @@ describe('getOrCreateNode', () => {
       return statusUnsubMock
     })
 
-    getOrCreateNode({state, instance}, nodeConfig)
+    getOrCreateNode({state, instance, key: null}, nodeConfig)
 
     // Remove the node entry before triggering the status callback
     state.get().nodes.delete(nodeConfig.name)

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

@@ -47,7 +47,7 @@ describe('releaseNode', () => {
     expect(state.get().nodes.has('test-node')).toBe(true)
 
     // Release the node
-    releaseNode({state, instance}, 'test-node')
+    releaseNode({state, instance, key: null}, 'test-node')
 
     // Check node is removed
     expect(mockNode.stop).toHaveBeenCalled()
@@ -64,7 +64,7 @@ describe('releaseNode', () => {
     })
     state.set('setup', {nodes})
 
-    releaseNode({state, instance}, 'test-node')
+    releaseNode({state, instance, key: null}, 'test-node')
 
     expect(statusUnsub).toHaveBeenCalled()
   })

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

@@ -14,7 +14,7 @@ describe('nodeStore', () => {
   })
 
   it('should have correct initial state', () => {
-    const initialState = comlinkNodeStore.getInitialState(instance)
+    const initialState = comlinkNodeStore.getInitialState(instance, null)
 
     expect(initialState.nodes).toBeInstanceOf(Map)
     expect(initialState.nodes.size).toBe(0)
@@ -25,16 +25,17 @@ describe('nodeStore', () => {
       stop: vi.fn(),
     } as unknown as Node<WindowMessage, FrameMessage>
 
-    const initialState = comlinkNodeStore.getInitialState(instance)
+    const initialState = comlinkNodeStore.getInitialState(instance, null)
     initialState.nodes.set('test-node', {
       options: {name: 'test-node', connectTo: 'parent'},
       node: mockNode,
-      refCount: 1,
+      status: 'idle',
     })
 
     const cleanup = comlinkNodeStore.initialize?.({
       instance,
       state: createStoreState(initialState),
+      key: null,
     })
 
     cleanup?.()

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

@@ -29,15 +29,24 @@ export interface PerspectiveHandle {
  * @public
  */
 export interface DatasetHandle<TDataset extends string = string, TProjectId extends string = string>
-  extends ProjectHandle<TProjectId>,
-    PerspectiveHandle {
+  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
 }
 
 /**
  * Identifies a specific document type within a Sanity dataset and project.
  * Includes `projectId`, `dataset`, and `documentType`.
- * Optionally includes a `documentId`, useful for referencing a specific document type context, potentially without a specific document ID.
+ * Optionally includes a `documentId` and `liveEdit` flag.
  * @public
  */
 export interface DocumentTypeHandle<
@@ -47,6 +56,12 @@ export interface DocumentTypeHandle<
 > extends DatasetHandle<TDataset, TProjectId> {
   documentId?: string
   documentType: TDocumentType
+  /**
+   * Indicates whether this document uses liveEdit mode.
+   * When `true`, the document does not use the draft/published model and edits are applied directly to the document.
+   * @see https://www.sanity.io/docs/content-lake/drafts#ca0663a8f002
+   */
+  liveEdit?: boolean
 }
 
 /**
@@ -80,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/document/actions.ts

@@ -143,7 +143,9 @@ export function createDocument<
   return {
     type: 'document.create',
     ...doc,
-    ...(doc.documentId && {documentId: getPublishedId(doc.documentId)}),
+    ...(doc.documentId && {
+      documentId: doc.liveEdit ? doc.documentId : getPublishedId(doc.documentId),
+    }),
     ...(initialValue && {initialValue}),
   }
 }
@@ -164,7 +166,7 @@ export function deleteDocument<
   return {
     type: 'document.delete',
     ...doc,
-    documentId: getPublishedId(doc.documentId),
+    documentId: doc.liveEdit ? doc.documentId : getPublishedId(doc.documentId),
   }
 }
 
@@ -228,12 +230,14 @@ export function editDocument<
   doc: DocumentHandle<TDocumentType, TDataset, TProjectId>,
   patches?: PatchOperations | PatchOperations[] | SanityMutatePatchMutation,
 ): EditDocumentAction<TDocumentType, TDataset, TProjectId> {
+  const documentId = doc.liveEdit ? doc.documentId : getPublishedId(doc.documentId)
+
   if (isSanityMutatePatch(patches)) {
     const converted = convertSanityMutatePatch(patches) ?? []
     return {
       ...doc,
       type: 'document.edit',
-      documentId: getPublishedId(doc.documentId),
+      documentId,
       patches: converted,
     }
   }
@@ -241,7 +245,7 @@ export function editDocument<
   return {
     ...doc,
     type: 'document.edit',
-    documentId: getPublishedId(doc.documentId),
+    documentId,
     ...(patches && {patches: Array.isArray(patches) ? patches : [patches]}),
   }
 }
@@ -262,7 +266,7 @@ export function publishDocument<
   return {
     type: 'document.publish',
     ...doc,
-    documentId: getPublishedId(doc.documentId),
+    documentId: doc.liveEdit ? doc.documentId : getPublishedId(doc.documentId),
   }
 }
 
@@ -282,7 +286,7 @@ export function unpublishDocument<
   return {
     type: 'document.unpublish',
     ...doc,
-    documentId: getPublishedId(doc.documentId),
+    documentId: doc.liveEdit ? doc.documentId : getPublishedId(doc.documentId),
   }
 }
 
@@ -302,6 +306,6 @@ export function discardDocument<
   return {
     type: 'document.discard',
     ...doc,
-    documentId: getPublishedId(doc.documentId),
+    documentId: doc.liveEdit ? doc.documentId : getPublishedId(doc.documentId),
   }
 }

package/src/document/applyDocumentActions.test.ts

@@ -48,11 +48,11 @@ describe('applyDocumentActions', () => {
     }
     state = createStoreState(initialState)
     instance = createSanityInstance({projectId: 'p', dataset: 'd'})
+    const key = {name: 'p.d', projectId: 'p', dataset: 'd'}
 
     vi.mocked(bindActionByDataset).mockImplementation(
-      (_storeDef, action) =>
-        (instanceParam: SanityInstance, ...params: unknown[]) =>
-          action({instance: instanceParam, state}, ...params),
+      (_storeDef, action) => (instanceParam: SanityInstance, options) =>
+        action({instance: instanceParam, state, key}, options),
     )
     // Import dynamically to ensure mocks are set up before the module under test is loaded
     const module = await import('./applyDocumentActions')
@@ -72,7 +72,8 @@ describe('applyDocumentActions', () => {
     }
 
     // Call applyDocumentActions with a fixed transactionId for reproducibility.
-    const applyPromise = applyDocumentActions(instance, action, {
+    const applyPromise = applyDocumentActions(instance, {
+      actions: [action],
       transactionId: 'txn-success',
     })
 
@@ -128,7 +129,8 @@ describe('applyDocumentActions', () => {
     }
 
     // Call applyDocumentActions with a fixed transactionId.
-    const applyPromise = applyDocumentActions(instance, action, {
+    const applyPromise = applyDocumentActions(instance, {
+      actions: [action],
       transactionId: 'txn-error',
     })
 
@@ -160,7 +162,8 @@ describe('applyDocumentActions', () => {
       dataset: 'd',
     }
     // Call applyDocumentActions with the context using childInstance, but with action requiring parent's config
-    const applyPromise = applyDocumentActions(childInstance, action, {
+    const applyPromise = applyDocumentActions(childInstance, {
+      actions: [action],
       transactionId: 'txn-child-match',
     })