@sanity/sdk 3.0.0-rc.1 → 3.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanity/sdk",
-  "version": "3.0.0-rc.1",
+  "version": "3.0.0",
   "private": false,
   "description": "Sanity SDK",
   "keywords": [
@@ -33,34 +33,28 @@
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
-    ".": {
-      "source": "./src/_exports/index.ts",
-      "import": "./dist/index.js",
-      "default": "./dist/index.js"
-    },
+    ".": "./dist/index.js",
     "./package.json": "./package.json",
-    "./_internal": {
-      "source": "./src/_exports/_internal.ts",
-      "import": "./dist/_exports/_internal.js",
-      "default": "./dist/_exports/_internal.js"
-    }
+    "./_internal": "./dist/_exports/_internal.js",
+    "./agent": "./dist/_exports/agent.js",
+    "./comlink": "./dist/_exports/comlink.js"
   },
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
     "@sanity/bifur-client": "^1.0.0",
-    "@sanity/client": "^7.23.2",
-    "@sanity/comlink": "^4.0.1",
+    "@sanity/client": "^7.26.2",
+    "@sanity/comlink": "^4.0.3",
     "@sanity/diff-match-patch": "^3.2.0",
     "@sanity/diff-patch": "^6.0.0",
     "@sanity/id-utils": "^1.0.0",
     "@sanity/image-url": "^2.1.1",
     "@sanity/json-match": "^1.0.5",
-    "@sanity/message-protocol": "^0.23.0",
+    "@sanity/message-protocol": "^0.24.0",
     "@sanity/mutate": "^0.18.1",
     "@sanity/telemetry": "^1.1.0",
-    "@sanity/types": "^6.5.0",
+    "@sanity/types": "^6.9.1",
     "groq": "3.88.1-typegen-experimental.0",
     "groq-js": "^2.0.0",
     "reselect": "^5.1.1",
@@ -69,12 +63,12 @@
   },
   "devDependencies": {
     "@sanity/browserslist-config": "^1.0.5",
-    "@sanity/pkg-utils": "^10.9.2",
+    "@sanity/pkg-utils": "^12.1.0",
     "@types/node": "^24.13.3",
     "@vitest/coverage-v8": "^4.1.10",
     "eslint": "^10.6.0",
     "oxfmt": "^0.58.0",
-    "rollup-plugin-visualizer": "^7.0.1",
+    "rolldown": "^1.2.3",
     "typescript": "^6.0.3",
     "vite": "^8.1.5",
     "vitest": "^4.1.10",

package/src/_exports/_internal.ts

@@ -6,6 +6,7 @@ export {
   getClientErrorApiType,
   isProjectUserNotFoundClientError,
 } from '../auth/utils'
+export {getCommentsOptionsKey, parseCommentsOptionsKey} from '../comments/commentsStore' // only used for memoizing in React, not needed for actual functionality
 export {PREVIEW_PROJECTION} from '../preview/previewConstants'
 export {transformProjectionToPreview} from '../preview/previewProjectionUtils'
 export {getQueryKey, parseQueryKey} from '../query/queryStore' // only used for memoizing in React, not needed for actual functionality

package/src/_exports/agent.ts

@@ -0,0 +1,19 @@
+export type {
+  AgentGenerateOptions,
+  AgentGenerateResult,
+  AgentPatchOptions,
+  AgentPatchResult,
+  AgentPromptOptions,
+  AgentPromptResult,
+  AgentTransformOptions,
+  AgentTransformResult,
+  AgentTranslateOptions,
+  AgentTranslateResult,
+} from '../agent/agentActions'
+export {
+  agentGenerate,
+  agentPatch,
+  agentPrompt,
+  agentTransform,
+  agentTranslate,
+} from '../agent/agentActions'

package/src/_exports/comlink.ts

@@ -0,0 +1,16 @@
+export {
+  type ComlinkControllerState,
+  destroyController,
+  getOrCreateChannel,
+  getOrCreateController,
+  releaseChannel,
+} from '../comlink/controller/comlinkControllerStore'
+export type {ComlinkNodeState} from '../comlink/node/comlinkNodeStore'
+export {getOrCreateNode, releaseNode} from '../comlink/node/comlinkNodeStore'
+export {getNodeState, type NodeState} from '../comlink/node/getNodeState'
+export {
+  type FrameMessage,
+  type NewTokenResponseMessage,
+  type RequestNewTokenMessage,
+  type WindowMessage,
+} from '../comlink/types'

package/src/_exports/index.ts

@@ -7,25 +7,6 @@ export type SanityProject = _SanityProject
 
 export {checkPermissions} from '../access/checkPermissions'
 export {type AccessResourceType} from '../access/checkPermissions'
-export type {
-  AgentGenerateOptions,
-  AgentGenerateResult,
-  AgentPatchOptions,
-  AgentPatchResult,
-  AgentPromptOptions,
-  AgentPromptResult,
-  AgentTransformOptions,
-  AgentTransformResult,
-  AgentTranslateOptions,
-  AgentTranslateResult,
-} from '../agent/agentActions'
-export {
-  agentGenerate,
-  agentPatch,
-  agentPrompt,
-  agentTransform,
-  agentTranslate,
-} from '../agent/agentActions'
 export {
   application,
   applications,
@@ -48,23 +29,6 @@ export {
   type DeletedResult,
   type UpdateApplicationInput,
 } from '../applications/applications'
-export {
-  createUserApplication,
-  deleteUserApplication,
-  updateUserApplication,
-  userApplication,
-  userApplications,
-} from '../applications/userApplications'
-export {
-  type CreateUserApplicationInput,
-  type DeleteUserApplicationInput,
-  type UpdateUserApplicationInput,
-  type UserApplication,
-  type UserApplicationDeployment,
-  type UserApplicationsOptions,
-  type UserApplicationWriteFields,
-} from '../applications/userApplications'
-export {isStudioConfig} from '../auth/authMode'
 export {AuthStateType} from '../auth/authStateType'
 export {
   type AuthState,
@@ -84,31 +48,38 @@ export {
 export {observeOrganizationVerificationState} from '../auth/getOrganizationVerificationState'
 export {handleAuthCallback} from '../auth/handleAuthCallback'
 export {logout} from '../auth/logout'
-export {
-  type ApiErrorBody,
-  getClientErrorApiBody,
-  getClientErrorApiDescription,
-  getClientErrorApiType,
-  isProjectUserNotFoundClientError,
-} from '../auth/utils'
 export type {ClientStoreState as ClientState} from '../client/clientStore'
 export {type ClientOptions, getClient, getClientState} from '../client/clientStore'
 export {
-  type ComlinkControllerState,
-  destroyController,
-  getOrCreateChannel,
-  getOrCreateController,
-  releaseChannel,
-} from '../comlink/controller/comlinkControllerStore'
-export type {ComlinkNodeState} from '../comlink/node/comlinkNodeStore'
-export {getOrCreateNode, releaseNode} from '../comlink/node/comlinkNodeStore'
-export {getNodeState, type NodeState} from '../comlink/node/getNodeState'
+  createComment,
+  type CreateCommentOptions,
+  removeComment,
+  type RemoveCommentOptions,
+  replyToComment,
+  type ReplyToCommentOptions,
+  setCommentStatus,
+  type SetCommentStatusOptions,
+  updateComment,
+  type UpdateCommentOptions,
+} from '../comments/commentActions'
 export {
-  type FrameMessage,
-  type NewTokenResponseMessage,
-  type RequestNewTokenMessage,
-  type WindowMessage,
-} from '../comlink/types'
+  type CommentsOptions,
+  getCommentsState,
+  getCommentThreadsState,
+  resolveComments,
+  type ResolveCommentsOptions,
+  resolveCommentThreads,
+} from '../comments/commentsStore'
+export {
+  type Comment,
+  type CommentLocalState,
+  type CommentMessage,
+  type CommentReaction,
+  type CommentStatus,
+  type CommentTextSelection,
+  type CommentTextSelectionItem,
+  type CommentThread,
+} from '../comments/types'
 export {type AuthConfig, type AuthProvider} from '../config/authConfig'
 export {
   createDatasetHandle,
@@ -127,22 +98,15 @@ export {
 } 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,
   type ReleaseHandle,
@@ -151,7 +115,7 @@ export {
   type StudioConfig,
   type TokenSource,
 } from '../config/sanityConfig'
-export {getDatasetsState, resolveDatasets} from '../datasets/datasets'
+export {datasets} from '../datasets/datasets'
 export {
   type Action,
   archiveRelease,
@@ -217,8 +181,12 @@ export {
 export {type JsonMatch} from '../document/patchOperations'
 export {type DocumentPermissionsResult, type PermissionDeniedReason} from '../document/permissions'
 export {getReleaseDocumentId} from '../document/processActions/releaseUtil'
-export type {FavoriteStatusResponse} from '../favorites/favorites'
-export {getFavoritesState, resolveFavoritesState} from '../favorites/favorites'
+export type {
+  FavoriteDocumentContext,
+  FavoriteStatusResponse,
+  SetFavoriteInput,
+} from '../favorites/favorites'
+export {favorites, setFavorite} from '../favorites/favorites'
 export {installation, installations} from '../installations/installations'
 export {
   type Installation,
@@ -239,26 +207,22 @@ export {
 } from '../organization/organization'
 export {organizations} from '../organizations/organizations'
 export {type Organizations, type OrganizationsOptions} from '../organizations/organizations'
-export {getPresence} from '../presence/presenceStore'
+export {getDocumentPresence, getPresence, reportPresence} from '../presence/presenceStore'
 export type {
   DisconnectEvent,
+  DocumentPresence,
+  DocumentPresenceOptions,
   PresenceLocation,
+  PresencePerspectiveOptions,
+  PresenceSelection,
+  PresenceSelectionPoint,
+  ReportPresenceOptions,
   RollCallEvent,
   StateEvent,
   TransportEvent,
   UserPresence,
 } from '../presence/types'
-export {getPreviewState, type GetPreviewStateOptions} from '../preview/getPreviewState'
-export {PREVIEW_PROJECTION} from '../preview/previewConstants'
-export {transformProjectionToPreview} from '../preview/previewProjectionUtils'
-export {resolvePreview, type ResolvePreviewOptions} from '../preview/resolvePreview'
-export type {
-  PreviewMedia,
-  PreviewQueryResult,
-  PreviewStoreState,
-  PreviewValue,
-  ValuePending,
-} from '../preview/types'
+export type {PreviewMedia, PreviewQueryResult, PreviewValue} from '../preview/types'
 export {type OrgVerificationResult} from '../project/organizationVerification'
 export {project} from '../project/project'
 export {
@@ -271,22 +235,15 @@ export {
 } from '../project/project'
 export {getProjectionState} from '../projection/getProjectionState'
 export {resolveProjection} from '../projection/resolveProjection'
-export {type ProjectionValuePending, type ValidProjection} from '../projection/types'
+export {type ProjectionValuePending} from '../projection/types'
 export {projects} from '../projects/projects'
 export {type ProjectsOptions} from '../projects/projects'
-export {
-  getQueryKey,
-  getQueryState,
-  parseQueryKey,
-  type QueryOptions,
-  resolveQuery,
-} from '../query/queryStore'
+export {getQueryState, type QueryOptions, resolveQuery} from '../query/queryStore'
 export {getPerspectiveState} from '../releases/getPerspectiveState'
 export type {ReleaseState} from '../releases/releasesStore'
 export {getActiveReleasesState, getAllReleasesState} from '../releases/releasesStore'
 export {createSanityInstance, type SanityInstance} from '../store/createSanityInstance'
 export {type Selector, type StateSource} from '../store/createStateSourceAction'
-export {getUsersKey, parseUsersKey} from '../users/reducers'
 export {
   type GetUserOptions,
   type GetUsersOptions,
@@ -306,8 +263,6 @@ export {
   resolveUser,
   resolveUsers,
 } from '../users/usersStore'
-export {type FetcherStore, type FetcherStoreState} from '../utils/createFetcherStore'
-export {createGroqSearchFilter} from '../utils/createGroqSearchFilter'
 export {getCorsErrorProjectId} from '../utils/getCorsErrorProjectId'
 export {isImportError} from '../utils/isImportError'
 export {CORE_SDK_VERSION} from '../version'

package/src/applications/applications.test-d.ts

@@ -30,6 +30,11 @@ test('Application — no includes: only the base shape, no config or activeDeplo
   expectTypeOf<Extract<keyof Application, ChildKeys>>().toEqualTypeOf<never>()
 })
 
+test('ApplicationBase — carries name and reference as strings', () => {
+  expectTypeOf<ApplicationBase['name']>().toEqualTypeOf<string>()
+  expectTypeOf<ApplicationBase['reference']>().toEqualTypeOf<string>()
+})
+
 test('Application — config.studio adds a required config.studio', () => {
   expectTypeOf<
     Application<'config.studio'>['config']['studio']

package/src/applications/applications.ts

@@ -120,6 +120,10 @@ export interface ApplicationBase {
   id: string
   type: 'studio' | 'coreApp'
   title: string
+  /** Stable, immutable identity, distinct from the mutable `slug` address. */
+  name: string
+  /** Qualified, globally-unique handle: `sanity/<name>` for singletons, `<organizationId>/<name>` otherwise. */
+  reference: string
   icon: string | null
   isSingleton: boolean
   visibility: 'default' | 'unlisted' | 'disabled'
@@ -280,8 +284,7 @@ export interface DeletedResult {
 }
 
 /**
- * Dashboard visibility for an application. The same set of values backs a user
- * application's `dashboardStatus`.
+ * Dashboard visibility for an application.
  *
  * @see https://www.sanity.io/docs/http-reference/applications-api
  * @internal

package/src/auth/authMode.test.ts

@@ -9,11 +9,6 @@ describe('resolveAuthMode', () => {
     expect(resolveAuthMode(config, 'https://example.com')).toBe('studio')
   })
 
-  it('returns "studio" when deprecated studioMode.enabled is true', () => {
-    const config: SanityConfig = {studioMode: {enabled: true}}
-    expect(resolveAuthMode(config, 'https://example.com')).toBe('studio')
-  })
-
   it('returns "dashboard" when _context URL param has a non-empty JSON object', () => {
     const context = encodeURIComponent(JSON.stringify({orgId: '123'}))
     const href = `https://example.com?_context=${context}`
@@ -23,14 +18,6 @@ describe('resolveAuthMode', () => {
   it('returns "standalone" by default', () => {
     expect(resolveAuthMode({}, 'https://example.com')).toBe('standalone')
   })
-
-  it('prefers studio config over studioMode', () => {
-    const config: SanityConfig = {
-      studio: {},
-      studioMode: {enabled: true},
-    }
-    expect(resolveAuthMode(config, 'https://example.com')).toBe('studio')
-  })
 })
 
 describe('isStudioConfig', () => {
@@ -38,19 +25,7 @@ describe('isStudioConfig', () => {
     expect(isStudioConfig({studio: {}})).toBe(true)
   })
 
-  it('returns true when deprecated studioMode.enabled is true', () => {
-    expect(isStudioConfig({studioMode: {enabled: true}})).toBe(true)
-  })
-
-  it('returns false when studioMode.enabled is false', () => {
-    expect(isStudioConfig({studioMode: {enabled: false}})).toBe(false)
-  })
-
   it('returns false for empty config', () => {
     expect(isStudioConfig({})).toBe(false)
   })
-
-  it('returns true when both studio and studioMode are present', () => {
-    expect(isStudioConfig({studio: {}, studioMode: {enabled: true}})).toBe(true)
-  })
 })

package/src/auth/authMode.ts

@@ -20,9 +20,8 @@ type AuthMode = 'studio' | 'dashboard' | 'standalone'
  *
  * Priority:
  * 1. `studio` config provided → `'studio'`
- * 2. `studioMode.enabled` in config (deprecated) → `'studio'`
- * 3. Dashboard context detected (`_context` URL param with content) → `'dashboard'`
- * 4. Otherwise → `'standalone'`
+ * 2. Dashboard context detected (`_context` URL param with content) → `'dashboard'`
+ * 3. Otherwise → `'standalone'`
  *
  * @internal
  */
@@ -34,13 +33,11 @@ export function resolveAuthMode(config: SanityConfig, locationHref: string): Aut
 
 /**
  * Returns `true` when the config indicates the SDK is running inside a Studio.
- * Checks the new `studio` field first, then falls back to the deprecated
- * `studioMode.enabled` for backwards compatibility.
  *
  * @internal
  */
 export function isStudioConfig(config: SanityConfig): boolean {
-  return !!config.studio || !!config.studioMode?.enabled
+  return !!config.studio
 }
 
 /**

package/src/auth/authStore.test.ts

@@ -654,7 +654,7 @@ describe('authStore', () => {
       instance = createSanityInstance({
         projectId,
         dataset: 'd',
-        studioMode: {enabled: true},
+        studio: {},
         auth: {storageArea: mockStorage},
       })
 

package/src/auth/authStore.ts

@@ -110,7 +110,6 @@ export const authStore = defineStore<AuthStoreState>({
       hasCustomProviders: !!(
         instance.config.auth?.providers && instance.config.auth.providers.length > 0
       ),
-      studioMode: instance.config.studioMode?.enabled ?? false,
     })
 
     const {

package/src/comments/addonDatasetStore.test.ts

@@ -0,0 +1,215 @@
+import {type SanityClient} from '@sanity/client'
+import {BehaviorSubject, firstValueFrom, NEVER, of, throwError} from 'rxjs'
+import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest'
+
+import {getClient, getClientState} from '../client/clientStore'
+import {createSanityInstance, type SanityInstance} from '../store/createSanityInstance'
+import {type StateSource} from '../store/createStateSourceAction'
+import {
+  getAddonDatasetState,
+  observeAddonDatasetClient,
+  provisionAddonDataset,
+} from './addonDatasetStore'
+
+vi.mock('../client/clientStore', () => ({
+  getClient: vi.fn(),
+  getClientState: vi.fn(),
+}))
+
+let instance: SanityInstance
+let observableRequest: ReturnType<typeof vi.fn>
+let request: ReturnType<typeof vi.fn>
+
+function mockClient() {
+  observableRequest = vi.fn()
+  request = vi.fn()
+  const client = {observable: {request: observableRequest}, request} as unknown as SanityClient
+
+  vi.mocked(getClient).mockReturnValue(client)
+  vi.mocked(getClientState).mockReturnValue({
+    observable: of(client),
+    getCurrent: () => client,
+    subscribe: () => () => {},
+  } as unknown as StateSource<SanityClient>)
+
+  return client
+}
+
+/** Waits for discovery, which runs asynchronously when the store initializes. */
+function resolvedAddonDataset() {
+  return firstValueFrom(getAddonDatasetState(instance, {}).observable.pipe())
+}
+
+beforeEach(() => {
+  vi.resetAllMocks()
+  instance = createSanityInstance({projectId: 'p', dataset: 'd'})
+  mockClient()
+})
+
+afterEach(() => {
+  instance.dispose()
+})
+
+describe('getAddonDatasetState', () => {
+  it('reports the dataset name once discovery answers', async () => {
+    observableRequest.mockReturnValue(of([{name: 'd-comments'}]))
+
+    await vi.waitFor(() =>
+      expect(getAddonDatasetState(instance, {}).getCurrent()).toBe('d-comments'),
+    )
+
+    expect(observableRequest).toHaveBeenCalledWith({
+      uri: '/projects/p/datasets?datasetProfile=comments&addonFor=d',
+      tag: 'comments.addon-dataset.list',
+    })
+  })
+
+  it('reports null when the project has no comments dataset', async () => {
+    observableRequest.mockReturnValue(of([]))
+
+    await vi.waitFor(() => expect(getAddonDatasetState(instance, {}).getCurrent()).toBe(null))
+  })
+
+  it('reports null rather than erroring when discovery is forbidden', async () => {
+    // A member without access to the addon dataset gets a 403. There is nothing
+    // for them to read, which is the same outcome as the dataset not existing.
+    observableRequest.mockReturnValue(throwError(() => ({statusCode: 403})))
+
+    await vi.waitFor(() => expect(getAddonDatasetState(instance, {}).getCurrent()).toBe(null))
+  })
+
+  it('recovers when a new authenticated client arrives after a transient failure', async () => {
+    const firstClient = {
+      observable: {request: vi.fn(() => throwError(() => ({statusCode: 500})))},
+    } as unknown as SanityClient
+    const secondClient = {
+      observable: {request: vi.fn(() => of([{name: 'd-comments'}]))},
+    } as unknown as SanityClient
+    const clients = new BehaviorSubject(firstClient)
+
+    vi.mocked(getClientState).mockReturnValue({
+      observable: clients,
+      getCurrent: () => clients.getValue(),
+      subscribe: () => () => {},
+    } as unknown as StateSource<SanityClient>)
+
+    const state = getAddonDatasetState(instance, {})
+    expect(state.getCurrent()).toBe(undefined)
+
+    clients.next(secondClient)
+
+    await vi.waitFor(() => expect(state.getCurrent()).toBe('d-comments'))
+  })
+
+  it('stays undefined while discovery is in flight', () => {
+    observableRequest.mockReturnValue(NEVER)
+    expect(getAddonDatasetState(instance, {}).getCurrent()).toBe(undefined)
+  })
+
+  it('throws for a resource that is not a dataset', () => {
+    expect(() => getAddonDatasetState(instance, {resource: {mediaLibraryId: 'ml-1'}})).toThrow(
+      /only supported for dataset resources/,
+    )
+  })
+})
+
+describe('provisionAddonDataset', () => {
+  it('returns the existing dataset without writing anything', async () => {
+    observableRequest.mockReturnValue(of([{name: 'd-comments'}]))
+    await resolvedAddonDataset()
+
+    await expect(provisionAddonDataset(instance, {})).resolves.toBe('d-comments')
+    expect(request).not.toHaveBeenCalled()
+  })
+
+  it('re-checks before creating, and adopts a dataset another user just made', async () => {
+    // Discovery said missing when this client started, but someone else has
+    // provisioned it since. Creating it again would fail.
+    observableRequest.mockReturnValueOnce(of([])).mockReturnValueOnce(of([{name: 'd-comments'}]))
+    await resolvedAddonDataset()
+
+    await expect(provisionAddonDataset(instance, {})).resolves.toBe('d-comments')
+    expect(request).not.toHaveBeenCalled()
+  })
+
+  it('creates the dataset when the re-check confirms it is missing', async () => {
+    observableRequest.mockReturnValue(of([]))
+    request.mockResolvedValue({datasetName: 'd-comments'})
+    await resolvedAddonDataset()
+
+    await expect(provisionAddonDataset(instance, {})).resolves.toBe('d-comments')
+    expect(request).toHaveBeenCalledWith({
+      uri: '/comments/d/setup',
+      method: 'POST',
+      tag: 'comments.addon-dataset.setup',
+    })
+    expect(getAddonDatasetState(instance, {}).getCurrent()).toBe('d-comments')
+  })
+
+  it('issues one POST for concurrent callers', async () => {
+    observableRequest.mockReturnValue(of([]))
+    request.mockResolvedValue({datasetName: 'd-comments'})
+    await resolvedAddonDataset()
+
+    const results = await Promise.all([
+      provisionAddonDataset(instance, {}),
+      provisionAddonDataset(instance, {}),
+      provisionAddonDataset(instance, {}),
+    ])
+
+    expect(results).toEqual(['d-comments', 'd-comments', 'd-comments'])
+    expect(request).toHaveBeenCalledTimes(1)
+  })
+
+  it('throws when setup returns no dataset name', async () => {
+    observableRequest.mockReturnValue(of([]))
+    request.mockResolvedValue({})
+    await resolvedAddonDataset()
+
+    await expect(provisionAddonDataset(instance, {})).rejects.toThrow(/no dataset name/)
+  })
+
+  it('allows a retry after a failure', async () => {
+    observableRequest.mockReturnValue(of([]))
+    request.mockRejectedValueOnce(new Error('boom')).mockResolvedValue({datasetName: 'd-comments'})
+    await resolvedAddonDataset()
+
+    await expect(provisionAddonDataset(instance, {})).rejects.toThrow('boom')
+    await expect(provisionAddonDataset(instance, {})).resolves.toBe('d-comments')
+  })
+})
+
+describe('observeAddonDatasetClient', () => {
+  it('does not report a missing dataset while discovery is still in flight', () => {
+    observableRequest.mockReturnValue(NEVER)
+    const values: Array<SanityClient | null> = []
+
+    const subscription = observeAddonDatasetClient(instance, {}).subscribe((value) =>
+      values.push(value),
+    )
+
+    expect(values).toEqual([])
+    subscription.unsubscribe()
+  })
+
+  it('emits null while the project has no comments dataset', async () => {
+    observableRequest.mockReturnValue(of([]))
+
+    await expect(firstValueFrom(observeAddonDatasetClient(instance, {}))).resolves.toBe(null)
+  })
+
+  it('emits a client once the dataset is known', async () => {
+    const client = mockClient()
+    observableRequest.mockReturnValue(of([{name: 'd-comments'}]))
+
+    await vi.waitFor(async () =>
+      expect(await firstValueFrom(observeAddonDatasetClient(instance, {}))).toBe(client),
+    )
+
+    expect(getClientState).toHaveBeenCalledWith(instance, {
+      apiVersion: 'v2025-05-06',
+      projectId: 'p',
+      dataset: 'd-comments',
+    })
+  })
+})