@sanity/sdk 2.8.0 → 2.9.0

package/src/releases/releasesStore.test.ts

@@ -30,6 +30,21 @@ describe('releasesStore', () => {
     instance.dispose()
   })
 
+  it('supports calls without options', () => {
+    const state = getActiveReleasesState(instance)
+
+    expect(state.getCurrent()).toBeUndefined()
+    expect(getQueryState).toHaveBeenCalledWith(
+      instance,
+      expect.objectContaining({
+        query: 'releases::all()',
+        perspective: 'raw',
+        source: undefined,
+        tag: 'releases',
+      }),
+    )
+  })
+
   it('should set active releases state when the releases query emits', async () => {
     const teardown = vi.fn()
     const subscriber = vi
@@ -58,7 +73,7 @@ describe('releasesStore', () => {
       } as ReleaseDocument,
     ]
 
-    const state = getActiveReleasesState(instance)
+    const state = getActiveReleasesState(instance, {source: {projectId: 'test', dataset: 'test'}})
 
     const [observer] = subscriber.mock.lastCall!
 
@@ -77,7 +92,7 @@ describe('releasesStore', () => {
       observable: releasesSubject.asObservable(),
     } as StateSource<ReleaseDocument[] | undefined>)
 
-    const state = getActiveReleasesState(instance)
+    const state = getActiveReleasesState(instance, {source: {projectId: 'test', dataset: 'test'}})
 
     // Initial state should be default
     expect(state.getCurrent()).toBeUndefined() // Default initial state
@@ -124,7 +139,7 @@ describe('releasesStore', () => {
       observable: of([]),
     } as StateSource<ReleaseDocument[] | undefined>)
 
-    const state = getActiveReleasesState(instance)
+    const state = getActiveReleasesState(instance, {source: {projectId: 'test', dataset: 'test'}})
 
     await new Promise((resolve) => setTimeout(resolve, 0))
 
@@ -138,7 +153,7 @@ describe('releasesStore', () => {
       getCurrent: () => null as unknown as ReleaseDocument[] | undefined,
       observable: of(null as unknown as ReleaseDocument[] | undefined),
     } as StateSource<ReleaseDocument[] | undefined>)
-    const state = getActiveReleasesState(instance)
+    const state = getActiveReleasesState(instance, {source: {projectId: 'test', dataset: 'test'}})
     await new Promise((resolve) => setTimeout(resolve, 0))
     expect(state.getCurrent()).toEqual([])
 
@@ -160,7 +175,7 @@ describe('releasesStore', () => {
       observable: subject.asObservable(),
     } as StateSource<ReleaseDocument[] | undefined>)
 
-    const state = getActiveReleasesState(instance)
+    const state = getActiveReleasesState(instance, {source: {projectId: 'test', dataset: 'test'}})
 
     subject.error(new Error('Query failed'))
 

package/src/releases/releasesStore.ts

@@ -1,6 +1,7 @@
 import {type SanityDocument} from '@sanity/types'
 import {map} from 'rxjs'
 
+import {type DocumentSource, isDatasetSource} from '../config/sanityConfig'
 /*
  * Although this is an import dependency cycle, it is not a logical cycle:
  * 1. releasesStore uses queryStore as a data source
@@ -10,8 +11,9 @@ import {map} from 'rxjs'
  */
 // eslint-disable-next-line import/no-cycle
 import {getQueryState} from '../query/queryStore'
-import {bindActionByDataset, type BoundDatasetKey} from '../store/createActionBinder'
-import {createStateSourceAction} from '../store/createStateSourceAction'
+import {bindActionBySource, type BoundSourceKey} from '../store/createActionBinder'
+import {type SanityInstance} from '../store/createSanityInstance'
+import {createStateSourceAction, type StateSource} from '../store/createStateSourceAction'
 import {defineStore, type StoreContext} from '../store/defineStore'
 import {sortReleases} from './utils/sortReleases'
 
@@ -39,7 +41,7 @@ export interface ReleasesStoreState {
   error?: unknown
 }
 
-export const releasesStore = defineStore<ReleasesStoreState, BoundDatasetKey>({
+export const releasesStore = defineStore<ReleasesStoreState, BoundSourceKey>({
   name: 'Releases',
   getInitialState: (): ReleasesStoreState => ({
     activeReleases: undefined,
@@ -54,25 +56,35 @@ export const releasesStore = defineStore<ReleasesStoreState, BoundDatasetKey>({
  * Get the active releases from the store.
  * @internal
  */
-export const getActiveReleasesState = bindActionByDataset(
+const _getActiveReleasesState = bindActionBySource(
   releasesStore,
   createStateSourceAction({
     selector: ({state}, _?) => state.activeReleases,
   }),
 )
 
+/**
+ * Get the active releases from the store.
+ * @internal
+ */
+export const getActiveReleasesState = (
+  instance: SanityInstance,
+  options?: {source?: DocumentSource},
+): StateSource<ReleaseDocument[] | undefined> =>
+  // bindActionBySource keyFn destructures { source } from the first param, so pass {} when no options
+  _getActiveReleasesState(instance, options ?? {})
+
 const RELEASES_QUERY = 'releases::all()'
 
 const subscribeToReleases = ({
   instance,
   state,
-  key: {projectId, dataset},
-}: StoreContext<ReleasesStoreState, BoundDatasetKey>) => {
+  key: {source},
+}: StoreContext<ReleasesStoreState, BoundSourceKey>) => {
   const {observable: releases$} = getQueryState<ReleaseDocument[]>(instance, {
     query: RELEASES_QUERY,
     perspective: 'raw',
-    projectId,
-    dataset,
+    source: source && !isDatasetSource(source) ? source : undefined,
     tag: 'releases',
   })
   return releases$

package/src/store/createStateSourceAction.test.ts

@@ -1,3 +1,4 @@
+import {filter, firstValueFrom, timeout} from 'rxjs'
 import {beforeEach, describe, expect, it, vi} from 'vitest'
 
 import {createSanityInstance, type SanityInstance} from './createSanityInstance'
@@ -194,4 +195,65 @@ describe('createStateSourceAction', () => {
     expect(context1.instance).toBe(instance)
     expect(context2.instance).toBe(secondInstance)
   })
+
+  it('correctly observes values defined in the onSubscribe', async () => {
+    const selector = vi.fn(({state: s}: SelectorContext<CountStoreState>) => s.count)
+    const source = createStateSourceAction({
+      selector: selector,
+      onSubscribe() {
+        state.set('update', {count: 1})
+      },
+    })({state, instance, key: null})
+
+    const value = await firstValueFrom(
+      source.observable.pipe(
+        filter((i) => i === 1),
+        timeout(10),
+      ),
+    )
+    expect(value).toBe(1)
+  })
+
+  it('only invokes selector once on changes', () => {
+    const selector = vi.fn(({state: s}: SelectorContext<CountStoreState>) => s.count)
+    const source = createStateSourceAction({selector: selector})({state, instance, key: null})
+
+    expect(selector).toBeCalledTimes(0)
+
+    // Now it should be called once:
+    const sub = source.observable.subscribe()
+    expect(selector).toBeCalledTimes(1)
+
+    // The observable should be shared so this shouldn't invoke it first.
+    const sub2 = source.observable.subscribe()
+    expect(selector).toBeCalledTimes(1)
+
+    // Updating the value should only invoke it once:
+    state.set('update', {count: 1})
+    expect(selector).toBeCalledTimes(2)
+
+    sub2.unsubscribe()
+    sub.unsubscribe()
+
+    // Once everyone has unsubscribed it should be invoked again.
+    const sub3 = source.observable.subscribe()
+    expect(selector).toBeCalledTimes(3)
+    sub3.unsubscribe()
+  })
+
+  it('only subscribes once when mixing subscribe/observable', () => {
+    const selector = vi.fn(({state: s}: SelectorContext<CountStoreState>) => s.count)
+    const source = createStateSourceAction({selector: selector})({state, instance, key: null})
+
+    expect(selector).toBeCalledTimes(0)
+
+    const sub = source.observable.subscribe()
+    expect(selector).toBeCalledTimes(1)
+
+    const sub2 = source.subscribe()
+    expect(selector).toBeCalledTimes(1)
+
+    sub.unsubscribe()
+    sub2()
+  })
 })

package/src/store/createStateSourceAction.ts

@@ -1,4 +1,4 @@
-import {distinctUntilChanged, map, Observable, share, skip} from 'rxjs'
+import {defer, distinctUntilChanged, finalize, map, Observable, shareReplay, skip} from 'rxjs'
 
 import {type StoreAction} from './createActionBinder'
 import {type SanityInstance} from './createSanityInstance'
@@ -187,8 +187,7 @@ export function createStateSourceAction<TState, TParams extends unknown[], TRetu
   function stateSourceAction(context: StoreContext<TState, TKey>, ...params: TParams) {
     const {state, instance} = context
 
-    const getCurrent = () => {
-      const currentState = state.get()
+    const getCurrent = (currentState: TState) => {
       if (typeof currentState !== 'object' || currentState === null) {
         throw new Error(
           `Expected store state to be an object but got "${typeof currentState}" instead`,
@@ -208,53 +207,49 @@ export function createStateSourceAction<TState, TParams extends unknown[], TRetu
       return selector(selectorContext, ...params)
     }
 
-    // Subscription manager handles both RxJS and direct subscriptions
-    const subscribe = (onStoreChanged?: () => void) => {
-      // Run setup handler if provided
-      const cleanup = subscribeHandler?.(context, ...params)
+    // `state.observable` will emit the current value immediately and
+    // hence we inherit the same behavior here.
+    let values = state.observable.pipe(map(getCurrent), distinctUntilChanged(isEqual))
 
-      // Set up state change subscription
-      const subscription = state.observable
-        .pipe(
-          // Derive value from current state
-          map(getCurrent),
-          // Filter unchanged values using custom equality check
-          distinctUntilChanged(isEqual),
-          // Skip initial emission since we only want changes
-          skip(1),
-        )
-        .subscribe({
-          next: () => onStoreChanged?.(),
-          // Propagate selector errors to both subscription types
-          error: () => onStoreChanged?.(),
-        })
+    if (subscribeHandler) {
+      values = withSubscribeHook(values, () => subscribeHandler(context, ...params))
+    }
+
+    // Share but replay the latest value so every subscriber gets an
+    // initial synchronous emission, matching `state.observable`. That keeps
+    // `skip(1)` in `subscribe()` aligned with "skip current snapshot" rather than
+    // silently eating the first real update after multicasting.
+    const sharedValues = values.pipe(shareReplay({bufferSize: 1, refCount: true}))
+
+    const subscribe = (onStoreChanged?: () => void) => {
+      const subscription = sharedValues.pipe(skip(1)).subscribe({
+        next: () => onStoreChanged?.(),
+        // Propagate selector errors to both subscription types
+        error: () => onStoreChanged?.(),
+      })
 
       return () => {
         subscription.unsubscribe()
-        cleanup?.()
       }
     }
 
-    // Create shared observable that handles multiple subscribers efficiently
-    const observable = new Observable<TReturn>((observer) => {
-      const emitCurrent = () => {
-        try {
-          observer.next(getCurrent())
-        } catch (error) {
-          observer.error(error)
-        }
-      }
-      // Emit immediately on subscription
-      emitCurrent()
-      return subscribe(emitCurrent)
-    }).pipe(share())
-
     return {
-      getCurrent,
+      getCurrent: () => getCurrent(state.get()),
       subscribe,
-      observable,
+      observable: sharedValues,
     }
   }
 
   return stateSourceAction
 }
+
+/**
+ * Creates a new Observable which wraps an existing Observable which will invoke
+ * the function when a new subscriber appears.
+ */
+function withSubscribeHook<T>(obs: Observable<T>, fn: () => void | (() => void)): Observable<T> {
+  return defer(() => {
+    const cleanup = fn()
+    return cleanup ? obs.pipe(finalize(() => cleanup())) : obs
+  })
+}

package/src/telemetry/__telemetry__/sdk.telemetry.ts

@@ -0,0 +1,42 @@
+import {defineEvent} from '@sanity/telemetry'
+
+/** @internal */
+export const SDKDevSessionStarted = defineEvent<{
+  version: string
+  projectId: string
+  perspective: string
+  authMethod: string
+}>({
+  name: 'SDK Dev Session Started',
+  version: 1,
+  description: 'SDK instance created in development mode',
+})
+
+/** @internal */
+export const SDKHookMounted = defineEvent<{
+  hookName: string
+}>({
+  name: 'SDK Hook Mounted',
+  version: 1,
+  description: 'An SDK hook was mounted for the first time in this session',
+})
+
+/** @internal */
+export const SDKDevSessionEnded = defineEvent<{
+  durationSeconds: number
+  hooksUsed: string[]
+}>({
+  name: 'SDK Dev Session Ended',
+  version: 1,
+  description: 'SDK instance disposed in development mode',
+})
+
+/** @internal */
+export const SDKDevError = defineEvent<{
+  errorType: string
+  hookName: string
+}>({
+  name: 'SDK Dev Error',
+  version: 1,
+  description: 'Runtime error caught during SDK development',
+})

package/src/telemetry/devMode.test.ts

@@ -0,0 +1,52 @@
+import {afterEach, describe, expect, it, vi} from 'vitest'
+
+import {isDevMode} from './devMode'
+
+describe('isDevMode', () => {
+  afterEach(() => {
+    vi.unstubAllEnvs()
+    vi.unstubAllGlobals()
+  })
+
+  it('returns false when NODE_ENV is production', () => {
+    vi.stubEnv('NODE_ENV', 'production')
+    vi.stubGlobal('window', undefined)
+    expect(isDevMode()).toBe(false)
+  })
+
+  it('returns true when running on localhost', () => {
+    vi.stubEnv('NODE_ENV', 'development')
+    vi.stubGlobal('window', {
+      location: {href: 'http://localhost:3000/'},
+    })
+    expect(isDevMode()).toBe(true)
+  })
+
+  it('returns true when running on 127.0.0.1', () => {
+    vi.stubEnv('NODE_ENV', 'development')
+    vi.stubGlobal('window', {
+      location: {href: 'http://127.0.0.1:3000/'},
+    })
+    expect(isDevMode()).toBe(true)
+  })
+
+  it('returns false for a non-local URL', () => {
+    vi.stubEnv('NODE_ENV', 'test')
+    vi.stubGlobal('window', {
+      location: {href: 'https://myapp.sanity.studio/'},
+    })
+    expect(isDevMode()).toBe(false)
+  })
+
+  it('returns true when NODE_ENV is development and no window', () => {
+    vi.stubEnv('NODE_ENV', 'development')
+    vi.stubGlobal('window', undefined)
+    expect(isDevMode()).toBe(true)
+  })
+
+  it('returns false when NODE_ENV is test and no window', () => {
+    vi.stubEnv('NODE_ENV', 'test')
+    vi.stubGlobal('window', undefined)
+    expect(isDevMode()).toBe(false)
+  })
+})

package/src/telemetry/devMode.ts

@@ -0,0 +1,40 @@
+/**
+ * Checks whether the current URL points to a local development server.
+ *
+ * @param win - The window object to check
+ * @returns True if running on localhost or 127.0.0.1
+ * @internal
+ */
+function isLocalUrl(win: Window): boolean {
+  const url = win.location?.href
+  if (!url) return false
+  return (
+    url.startsWith('http://localhost') ||
+    url.startsWith('https://localhost') ||
+    url.startsWith('http://127.0.0.1') ||
+    url.startsWith('https://127.0.0.1')
+  )
+}
+
+/**
+ * Determines whether the SDK should enable dev-mode telemetry.
+ *
+ * Combines a browser URL check (localhost/127.0.0.1) with a Node.js
+ * environment variable check (`NODE_ENV === 'development'`). Returns
+ * false in production environments so bundlers can tree-shake the
+ * telemetry code path entirely.
+ *
+ * @returns True if the SDK is running in a development environment
+ * @internal
+ */
+export function isDevMode(): boolean {
+  if (typeof process !== 'undefined' && process.env?.['NODE_ENV'] === 'production') {
+    return false
+  }
+
+  if (typeof window !== 'undefined') {
+    return isLocalUrl(window)
+  }
+
+  return typeof process !== 'undefined' && process.env?.['NODE_ENV'] === 'development'
+}

package/src/telemetry/initTelemetry.test.ts

@@ -0,0 +1,225 @@
+import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest'
+
+import {createSanityInstance} from '../store/createSanityInstance'
+import {isDevMode} from './devMode'
+import {getTelemetryManager, initTelemetry, trackHookMounted} from './initTelemetry'
+import {createTelemetryManager} from './telemetryManager'
+
+vi.mock('./devMode', () => ({
+  isDevMode: vi.fn(() => false),
+}))
+
+vi.mock('./telemetryManager', () => ({
+  createTelemetryManager: vi.fn(() => ({
+    checkConsent: vi.fn(() => Promise.resolve(true)),
+    logSessionStarted: vi.fn(),
+    logHookFirstUsed: vi.fn(),
+    logDevError: vi.fn(),
+    endSession: vi.fn(),
+    dispose: vi.fn(),
+    hooksUsed: new Set(),
+  })),
+}))
+
+vi.mock('../client/clientStore', () => ({
+  getClient: vi.fn(() => ({})),
+}))
+
+vi.mock('../auth/authStore', () => ({
+  getTokenState: vi.fn(() => ({
+    getCurrent: vi.fn(() => 'mock-token'),
+    observable: {subscribe: vi.fn()},
+  })),
+}))
+
+/**
+ * Flush the microtask queue so the dynamic imports in initTelemetry
+ * have time to resolve before assertions run.
+ */
+const flushPromises = () => new Promise<void>((r) => setTimeout(r, 0))
+
+describe('initTelemetry', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  afterEach(() => {
+    vi.restoreAllMocks()
+  })
+
+  it('does nothing when dev mode is disabled', async () => {
+    vi.mocked(isDevMode).mockReturnValue(false)
+
+    const instance = createSanityInstance()
+
+    initTelemetry(instance, 'abc123')
+    await flushPromises()
+
+    expect(createTelemetryManager).not.toHaveBeenCalled()
+    instance.dispose()
+  })
+
+  it('does nothing when no projectId is provided', async () => {
+    vi.mocked(isDevMode).mockReturnValue(true)
+
+    const instance = createSanityInstance()
+    initTelemetry(instance, '')
+    await flushPromises()
+
+    expect(createTelemetryManager).not.toHaveBeenCalled()
+    instance.dispose()
+  })
+
+  it('initializes telemetry in dev mode with a projectId', async () => {
+    vi.mocked(isDevMode).mockReturnValue(true)
+
+    const instance = createSanityInstance()
+
+    initTelemetry(instance, 'abc123')
+    await flushPromises()
+
+    expect(createTelemetryManager).toHaveBeenCalledWith(
+      expect.objectContaining({
+        sessionId: instance.instanceId,
+        projectId: 'abc123',
+      }),
+    )
+
+    const manager = vi.mocked(createTelemetryManager).mock.results[0].value
+    expect(manager.logSessionStarted).toHaveBeenCalledWith(
+      expect.objectContaining({
+        projectId: 'abc123',
+        perspective: 'published',
+      }),
+    )
+
+    instance.dispose()
+  })
+
+  it('registers manager in the WeakMap', async () => {
+    vi.mocked(isDevMode).mockReturnValue(true)
+
+    const instance = createSanityInstance()
+
+    initTelemetry(instance, 'abc123')
+    await flushPromises()
+
+    expect(getTelemetryManager(instance)).toBeDefined()
+
+    instance.dispose()
+  })
+
+  it('does not initialize if instance is already disposed', async () => {
+    vi.mocked(isDevMode).mockReturnValue(true)
+
+    const instance = createSanityInstance()
+
+    instance.dispose()
+    initTelemetry(instance, 'abc123')
+    await flushPromises()
+
+    const manager = vi.mocked(createTelemetryManager).mock.results[0]?.value
+    if (manager) {
+      expect(manager.logSessionStarted).not.toHaveBeenCalled()
+    }
+  })
+
+  it('calls endSession and removes manager on instance dispose', async () => {
+    vi.mocked(isDevMode).mockReturnValue(true)
+
+    const instance = createSanityInstance()
+
+    initTelemetry(instance, 'abc123')
+    await flushPromises()
+
+    const manager = vi.mocked(createTelemetryManager).mock.results[0].value
+    expect(getTelemetryManager(instance)).toBeDefined()
+
+    instance.dispose()
+
+    expect(manager.endSession).toHaveBeenCalled()
+    expect(getTelemetryManager(instance)).toBeUndefined()
+  })
+
+  it('skips telemetry entirely when user has not opted in', async () => {
+    vi.mocked(isDevMode).mockReturnValue(true)
+
+    const instance = createSanityInstance()
+
+    vi.mocked(createTelemetryManager).mockReturnValueOnce({
+      checkConsent: vi.fn(() => Promise.resolve(false)),
+      logSessionStarted: vi.fn(),
+      logHookFirstUsed: vi.fn(),
+      logDevError: vi.fn(),
+      endSession: vi.fn(),
+      dispose: vi.fn(),
+      hooksUsed: new Set(),
+    })
+
+    initTelemetry(instance, 'abc123')
+    await flushPromises()
+
+    expect(createTelemetryManager).toHaveBeenCalled()
+    const manager = vi.mocked(createTelemetryManager).mock.results[0].value
+
+    expect(manager.logSessionStarted).not.toHaveBeenCalled()
+    expect(manager.dispose).toHaveBeenCalled()
+    expect(manager.endSession).not.toHaveBeenCalled()
+    expect(getTelemetryManager(instance)).toBeUndefined()
+
+    instance.dispose()
+  })
+
+  it('uses perspective from config when available', async () => {
+    vi.mocked(isDevMode).mockReturnValue(true)
+
+    const instance = createSanityInstance({perspective: 'previewDrafts'})
+
+    initTelemetry(instance, 'abc123')
+    await flushPromises()
+
+    const manager = vi.mocked(createTelemetryManager).mock.results[0].value
+    expect(manager.logSessionStarted).toHaveBeenCalledWith(
+      expect.objectContaining({
+        perspective: 'previewDrafts',
+      }),
+    )
+
+    instance.dispose()
+  })
+
+  it('flushes hooks buffered before manager is ready', async () => {
+    vi.mocked(isDevMode).mockReturnValue(true)
+
+    const instance = createSanityInstance()
+
+    trackHookMounted(instance, 'useQuery')
+    trackHookMounted(instance, 'useDocument')
+
+    initTelemetry(instance, 'abc123')
+    await flushPromises()
+
+    const manager = vi.mocked(createTelemetryManager).mock.results[0].value
+    expect(manager.logHookFirstUsed).toHaveBeenCalledWith('useQuery')
+    expect(manager.logHookFirstUsed).toHaveBeenCalledWith('useDocument')
+
+    instance.dispose()
+  })
+
+  it('finds manager through parent-child instance chain', async () => {
+    vi.mocked(isDevMode).mockReturnValue(true)
+
+    const root = createSanityInstance()
+    const child = root.createChild({})
+
+    initTelemetry(root, 'abc123')
+    await flushPromises()
+
+    trackHookMounted(child, 'useUsers')
+
+    const manager = vi.mocked(createTelemetryManager).mock.results[0].value
+    expect(manager.logHookFirstUsed).toHaveBeenCalledWith('useUsers')
+
+    root.dispose()
+  })
+})