@sanity/sdk 2.11.1 → 2.12.0

package/src/telemetry/initTelemetry.test.ts

@@ -1,12 +1,13 @@
 import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest'
 
+import {getTokenState} from '../auth/authStore'
 import {createSanityInstance} from '../store/createSanityInstance'
-import {isDevMode} from './devMode'
+import {getTelemetryEnvironment} from './environment'
 import {getTelemetryManager, initTelemetry, trackHookMounted} from './initTelemetry'
 import {createTelemetryManager} from './telemetryManager'
 
-vi.mock('./devMode', () => ({
-  isDevMode: vi.fn(() => false),
+vi.mock('./environment', () => ({
+  getTelemetryEnvironment: vi.fn(() => null),
 }))
 
 vi.mock('./telemetryManager', () => ({
@@ -14,7 +15,7 @@ vi.mock('./telemetryManager', () => ({
     checkConsent: vi.fn(() => Promise.resolve(true)),
     logSessionStarted: vi.fn(),
     logHookFirstUsed: vi.fn(),
-    logDevError: vi.fn(),
+    logError: vi.fn(),
     endSession: vi.fn(),
     dispose: vi.fn(),
     hooksUsed: new Set(),
@@ -32,6 +33,53 @@ vi.mock('../auth/authStore', () => ({
   })),
 }))
 
+type TokenSubscriber = (token: string | null) => void
+
+/**
+ * Mimics the real token state: a BehaviorSubject-like observable that
+ * remembers the latest value and lets the test push new ones. The real
+ * `getTokenState(instance).observable` is `shareReplay({bufferSize: 1, refCount: true})`,
+ * so we also model the option to emit synchronously on subscribe.
+ */
+function createControlledTokenState(
+  options: {
+    initial?: string | null
+    /** If set, the observable emits this value synchronously on subscribe. */
+    emitOnSubscribe?: string | null
+  } = {},
+) {
+  const subscribers = new Set<TokenSubscriber>()
+  let current: string | null = options.initial ?? null
+
+  const tokenState = {
+    getCurrent: vi.fn(() => current),
+    subscribe: vi.fn(() => () => {}),
+    observable: {
+      subscribe: vi.fn((cb: TokenSubscriber) => {
+        subscribers.add(cb)
+        if (options.emitOnSubscribe !== undefined) {
+          current = options.emitOnSubscribe
+          cb(current)
+        }
+        return {
+          unsubscribe: vi.fn(() => {
+            subscribers.delete(cb)
+          }),
+        }
+      }),
+    },
+  } as unknown as ReturnType<typeof getTokenState>
+
+  return {
+    tokenState,
+    emit(token: string | null) {
+      current = token
+      for (const cb of [...subscribers]) cb(token)
+    },
+    subscriberCount: () => subscribers.size,
+  }
+}
+
 /**
  * Flush the microtask queue so the dynamic imports in initTelemetry
  * have time to resolve before assertions run.
@@ -47,8 +95,8 @@ describe('initTelemetry', () => {
     vi.restoreAllMocks()
   })
 
-  it('does nothing when dev mode is disabled', async () => {
-    vi.mocked(isDevMode).mockReturnValue(false)
+  it('does nothing when the environment is not eligible', async () => {
+    vi.mocked(getTelemetryEnvironment).mockReturnValue(null)
 
     const instance = createSanityInstance()
 
@@ -60,7 +108,7 @@ describe('initTelemetry', () => {
   })
 
   it('does nothing when no projectId is provided', async () => {
-    vi.mocked(isDevMode).mockReturnValue(true)
+    vi.mocked(getTelemetryEnvironment).mockReturnValue('development')
 
     const instance = createSanityInstance()
     initTelemetry(instance, '')
@@ -70,8 +118,8 @@ describe('initTelemetry', () => {
     instance.dispose()
   })
 
-  it('initializes telemetry in dev mode with a projectId', async () => {
-    vi.mocked(isDevMode).mockReturnValue(true)
+  it('initializes telemetry in development mode with a projectId', async () => {
+    vi.mocked(getTelemetryEnvironment).mockReturnValue('development')
 
     const instance = createSanityInstance()
 
@@ -82,6 +130,7 @@ describe('initTelemetry', () => {
       expect.objectContaining({
         sessionId: instance.instanceId,
         projectId: 'abc123',
+        environment: 'development',
       }),
     )
 
@@ -96,8 +145,27 @@ describe('initTelemetry', () => {
     instance.dispose()
   })
 
+  it('initializes telemetry in production mode on a Sanity-controlled domain', async () => {
+    vi.mocked(getTelemetryEnvironment).mockReturnValue('production')
+
+    const instance = createSanityInstance()
+
+    initTelemetry(instance, 'abc123')
+    await flushPromises()
+
+    expect(createTelemetryManager).toHaveBeenCalledWith(
+      expect.objectContaining({
+        sessionId: instance.instanceId,
+        projectId: 'abc123',
+        environment: 'production',
+      }),
+    )
+
+    instance.dispose()
+  })
+
   it('registers manager in the WeakMap', async () => {
-    vi.mocked(isDevMode).mockReturnValue(true)
+    vi.mocked(getTelemetryEnvironment).mockReturnValue('development')
 
     const instance = createSanityInstance()
 
@@ -110,7 +178,7 @@ describe('initTelemetry', () => {
   })
 
   it('does not initialize if instance is already disposed', async () => {
-    vi.mocked(isDevMode).mockReturnValue(true)
+    vi.mocked(getTelemetryEnvironment).mockReturnValue('development')
 
     const instance = createSanityInstance()
 
@@ -125,7 +193,7 @@ describe('initTelemetry', () => {
   })
 
   it('calls endSession and removes manager on instance dispose', async () => {
-    vi.mocked(isDevMode).mockReturnValue(true)
+    vi.mocked(getTelemetryEnvironment).mockReturnValue('development')
 
     const instance = createSanityInstance()
 
@@ -142,7 +210,7 @@ describe('initTelemetry', () => {
   })
 
   it('skips telemetry entirely when user has not opted in', async () => {
-    vi.mocked(isDevMode).mockReturnValue(true)
+    vi.mocked(getTelemetryEnvironment).mockReturnValue('development')
 
     const instance = createSanityInstance()
 
@@ -150,7 +218,7 @@ describe('initTelemetry', () => {
       checkConsent: vi.fn(() => Promise.resolve(false)),
       logSessionStarted: vi.fn(),
       logHookFirstUsed: vi.fn(),
-      logDevError: vi.fn(),
+      logError: vi.fn(),
       endSession: vi.fn(),
       dispose: vi.fn(),
       hooksUsed: new Set(),
@@ -171,7 +239,7 @@ describe('initTelemetry', () => {
   })
 
   it('uses perspective from config when available', async () => {
-    vi.mocked(isDevMode).mockReturnValue(true)
+    vi.mocked(getTelemetryEnvironment).mockReturnValue('development')
 
     const instance = createSanityInstance({perspective: 'previewDrafts'})
 
@@ -189,7 +257,7 @@ describe('initTelemetry', () => {
   })
 
   it('flushes hooks buffered before manager is ready', async () => {
-    vi.mocked(isDevMode).mockReturnValue(true)
+    vi.mocked(getTelemetryEnvironment).mockReturnValue('development')
 
     const instance = createSanityInstance()
 
@@ -205,4 +273,160 @@ describe('initTelemetry', () => {
 
     instance.dispose()
   })
+
+  it('does not buffer hooks when the environment is not eligible', async () => {
+    vi.mocked(getTelemetryEnvironment).mockReturnValue(null)
+
+    const instance = createSanityInstance()
+
+    trackHookMounted(instance, 'useQuery')
+
+    vi.mocked(getTelemetryEnvironment).mockReturnValue('production')
+    initTelemetry(instance, 'abc123')
+    await flushPromises()
+
+    const manager = vi.mocked(createTelemetryManager).mock.results[0].value
+    expect(manager.logHookFirstUsed).not.toHaveBeenCalled()
+
+    instance.dispose()
+  })
+
+  describe('auth token wait', () => {
+    beforeEach(() => {
+      vi.mocked(getTelemetryEnvironment).mockReturnValue('development')
+    })
+
+    it('defers initialization until the token observable emits', async () => {
+      const handle = createControlledTokenState({initial: null})
+      vi.mocked(getTokenState).mockReturnValue(handle.tokenState)
+
+      const instance = createSanityInstance()
+      initTelemetry(instance, 'abc123')
+      await flushPromises()
+
+      // No token yet — manager construction must not have happened.
+      expect(createTelemetryManager).not.toHaveBeenCalled()
+      expect(handle.subscriberCount()).toBe(1)
+
+      handle.emit('real-token')
+      await flushPromises()
+
+      expect(createTelemetryManager).toHaveBeenCalledWith(
+        expect.objectContaining({projectId: 'abc123', environment: 'development'}),
+      )
+      const manager = vi.mocked(createTelemetryManager).mock.results[0].value
+      expect(manager.logSessionStarted).toHaveBeenCalled()
+
+      instance.dispose()
+    })
+
+    it('ignores empty token emissions and keeps waiting', async () => {
+      const handle = createControlledTokenState({initial: null})
+      vi.mocked(getTokenState).mockReturnValue(handle.tokenState)
+
+      const instance = createSanityInstance()
+      initTelemetry(instance, 'abc123')
+      await flushPromises()
+
+      // Empty/falsy emissions should not be treated as a real token.
+      handle.emit(null)
+      handle.emit('')
+      await flushPromises()
+
+      expect(createTelemetryManager).not.toHaveBeenCalled()
+      expect(handle.subscriberCount()).toBe(1)
+
+      handle.emit('real-token')
+      await flushPromises()
+
+      expect(createTelemetryManager).toHaveBeenCalledTimes(1)
+
+      instance.dispose()
+    })
+
+    it('unsubscribes from the token observable once a token arrives', async () => {
+      const handle = createControlledTokenState({initial: null})
+      vi.mocked(getTokenState).mockReturnValue(handle.tokenState)
+
+      const instance = createSanityInstance()
+      initTelemetry(instance, 'abc123')
+      await flushPromises()
+
+      expect(handle.subscriberCount()).toBe(1)
+      handle.emit('real-token')
+      await flushPromises()
+
+      expect(handle.subscriberCount()).toBe(0)
+
+      instance.dispose()
+    })
+
+    it('aborts and unsubscribes when the instance is disposed during the wait', async () => {
+      const handle = createControlledTokenState({initial: null})
+      vi.mocked(getTokenState).mockReturnValue(handle.tokenState)
+
+      const instance = createSanityInstance()
+      initTelemetry(instance, 'abc123')
+      await flushPromises()
+
+      expect(handle.subscriberCount()).toBe(1)
+
+      instance.dispose()
+      await flushPromises()
+
+      expect(createTelemetryManager).not.toHaveBeenCalled()
+      expect(handle.subscriberCount()).toBe(0)
+      expect(getTelemetryManager(instance)).toBeUndefined()
+    })
+
+    it('does not re-subscribe to the token observable after a disposed-wait abort', async () => {
+      // Regression guard: if initInFlight isn't cleared on the dispose-abort
+      // branch, a follow-up initTelemetry call on the same instance would be
+      // silently dropped instead of bailing on the env/projectId check.
+      const handle = createControlledTokenState({initial: null})
+      vi.mocked(getTokenState).mockReturnValue(handle.tokenState)
+
+      const instance = createSanityInstance()
+      initTelemetry(instance, 'abc123')
+      await flushPromises()
+
+      instance.dispose()
+      await flushPromises()
+
+      // A second call against the same (disposed) instance should be a no-op
+      // and must not leave dangling subscriptions.
+      initTelemetry(instance, 'abc123')
+      await flushPromises()
+
+      expect(handle.subscriberCount()).toBe(0)
+      expect(createTelemetryManager).not.toHaveBeenCalled()
+    })
+
+    it('handles a synchronous token emission on subscribe without crashing', async () => {
+      // The real `getTokenState(instance).observable` is shareReplay({bufferSize: 1}),
+      // which means a subscribe call can deliver a buffered value synchronously
+      // before `subscribe()` itself returns. If `getCurrent()` saw `null` but the
+      // token landed in the buffer in the gap before `.subscribe(cb)`, the callback
+      // fires with a real token while `sub` is still in the TDZ. The init flow must
+      // not crash in that race.
+      const handle = createControlledTokenState({
+        initial: null,
+        emitOnSubscribe: 'sync-token',
+      })
+      vi.mocked(getTokenState).mockReturnValue(handle.tokenState)
+
+      const instance = createSanityInstance()
+      initTelemetry(instance, 'abc123')
+
+      // Must resolve without an unhandled rejection.
+      await flushPromises()
+
+      expect(createTelemetryManager).toHaveBeenCalledWith(
+        expect.objectContaining({projectId: 'abc123'}),
+      )
+      expect(handle.subscriberCount()).toBe(0)
+
+      instance.dispose()
+    })
+  })
 })

package/src/telemetry/initTelemetry.ts

@@ -1,6 +1,6 @@
 import {type SanityInstance} from '../store/createSanityInstance'
 import {createLogger} from '../utils/logger'
-import {isDevMode} from './devMode'
+import {getTelemetryEnvironment} from './environment'
 import {type TelemetryManager} from './telemetryManager'
 
 const DEFAULT_TELEMETRY_API_VERSION = '2024-11-12'
@@ -20,10 +20,23 @@ const pendingHooks = new WeakMap<SanityInstance, Set<string>>()
 const initInFlight = new WeakSet<SanityInstance>()
 
 /**
- * Initializes dev-mode telemetry for a SDK instance if the environment
- * qualifies. Both `telemetryManager` and `clientStore` are dynamically
- * imported to avoid circular dependencies and to keep telemetry code
- * out of production bundles via code splitting.
+ * Initializes telemetry for a SDK instance if the runtime environment
+ * qualifies. The environment is resolved by `getTelemetryEnvironment()`:
+ *
+ * - `'development'` — local dev servers (`localhost` / `127.0.0.1`, or
+ *   Node with `NODE_ENV=development`). This is the original opt-in
+ *   surface.
+ * - `'production'` — apps deployed to Sanity-controlled domains
+ *   (e.g. `*.sanity.studio`, the dashboard). End users are
+ *   authenticated Sanity users with Populus consent records, so we
+ *   apply the same consent gate as the Studio's `telemetry-sink`.
+ *
+ * Apps on customer-controlled domains return `null` and skip telemetry
+ * entirely.
+ *
+ * `telemetryManager` and `clientStore` are dynamically imported so the
+ * telemetry code path stays out of production bundles for apps that
+ * don't qualify. Only the lightweight environment check runs at boot.
  *
  * The `projectId` must be passed explicitly because the resource
  * configuration is typically set by the React layer after the
@@ -32,8 +45,9 @@ const initInFlight = new WeakSet<SanityInstance>()
  * @internal
  */
 export function initTelemetry(instance: SanityInstance, projectId: string): void {
-  if (!isDevMode()) {
-    logger.trace('initTelemetry skipped: not dev mode', {internal: true})
+  const environment = getTelemetryEnvironment()
+  if (!environment) {
+    logger.trace('initTelemetry skipped: environment not eligible', {internal: true})
     return
   }
   if (!projectId) {
@@ -45,7 +59,7 @@ export function initTelemetry(instance: SanityInstance, projectId: string): void
   }
   initInFlight.add(instance)
 
-  logger.debug('initializing telemetry', {projectId})
+  logger.debug('initializing telemetry', {projectId, environment})
 
   Promise.all([
     import('./telemetryManager'),
@@ -77,15 +91,23 @@ export function initTelemetry(instance: SanityInstance, projectId: string): void
             cleanup.unsubscribe()
             resolve(false)
           })
+          // The token observable is a `shareReplay({bufferSize: 1, refCount: true})`
+          // (see `createStateSourceAction`), so it can deliver a buffered value
+          // synchronously while we're still inside `.subscribe(cb)`. At that
+          // moment `sub` is in the TDZ, so the callback can't reach it. We
+          // gate on a `received` flag and let the post-subscribe block do the
+          // unsubscribe in the sync-emission case.
+          let received = false
           const sub = getTokenState(instance).observable.subscribe((t) => {
-            if (t) {
-              logger.debug('auth token received')
-              sub.unsubscribe()
-              unsub()
-              resolve(true)
-            }
+            if (received || !t) return
+            received = true
+            logger.debug('auth token received')
+            unsub()
+            resolve(true)
+            cleanup.unsubscribe()
           })
           cleanup.unsubscribe = () => sub.unsubscribe()
+          if (received) cleanup.unsubscribe()
         })
         if (!hasToken || instance.isDisposed()) {
           initInFlight.delete(instance)
@@ -98,6 +120,7 @@ export function initTelemetry(instance: SanityInstance, projectId: string): void
         sessionId: instance.instanceId,
         getClient: () => getClient(instance, {apiVersion: DEFAULT_TELEMETRY_API_VERSION}),
         projectId,
+        environment,
       })
 
       const consented = await manager.checkConsent()
@@ -128,7 +151,7 @@ export function initTelemetry(instance: SanityInstance, projectId: string): void
           ? 'studio'
           : 'default'
 
-      logger.info('telemetry session started', {projectId, perspective, authMethod})
+      logger.info('telemetry session started', {projectId, perspective, authMethod, environment})
       manager.logSessionStarted({
         projectId,
         perspective,
@@ -165,7 +188,7 @@ export function getTelemetryManager(instance: SanityInstance): TelemetryManager
  * @internal
  */
 export function trackHookMounted(instance: SanityInstance, hookName: string): void {
-  if (!isDevMode()) return
+  if (!getTelemetryEnvironment()) return
 
   const manager = findManager(instance)
   if (manager) {