@sanity/sdk 2.8.0 → 2.10.0

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()
+  })
+})

package/src/telemetry/initTelemetry.ts

@@ -0,0 +1,205 @@
+import {type SanityInstance} from '../store/createSanityInstance'
+import {createLogger} from '../utils/logger'
+import {isDevMode} from './devMode'
+import {type TelemetryManager} from './telemetryManager'
+
+const DEFAULT_TELEMETRY_API_VERSION = '2024-11-12'
+
+const logger = createLogger('telemetry')
+
+/**
+ * Per-instance map of active telemetry managers. Allows the React
+ * package (and other consumers) to look up the manager for a given
+ * instance and log hook usage / errors without importing the full
+ * telemetry module themselves.
+ *
+ * @internal
+ */
+const telemetryManagers = new WeakMap<SanityInstance, TelemetryManager>()
+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.
+ *
+ * The `projectId` must be passed explicitly because the resource
+ * configuration is typically set by the React layer after the
+ * instance has already been created.
+ *
+ * @internal
+ */
+export function initTelemetry(instance: SanityInstance, projectId: string): void {
+  if (!isDevMode()) {
+    logger.trace('initTelemetry skipped: not dev mode', {internal: true})
+    return
+  }
+  if (!projectId) {
+    logger.trace('initTelemetry skipped: no projectId', {internal: true})
+    return
+  }
+  if (telemetryManagers.has(instance) || initInFlight.has(instance)) {
+    return
+  }
+  initInFlight.add(instance)
+
+  logger.debug('initializing telemetry', {projectId})
+
+  Promise.all([
+    import('./telemetryManager'),
+    import('../client/clientStore'),
+    import('../auth/authStore'),
+  ])
+    .then(async ([{createTelemetryManager}, {getClient}, {getTokenState}]) => {
+      if (instance.isDisposed()) {
+        initInFlight.delete(instance)
+        logger.debug('telemetry skipped: instance disposed before imports resolved')
+        return
+      }
+
+      // Wait for the auth store to resolve a token. The client needs a
+      // Bearer token for the consent check and batch POSTs. If the token
+      // is already available (e.g. static token config), this resolves
+      // immediately. For OAuth/localStorage discovery it waits for the
+      // first emission. For unauthenticated apps the promise never
+      // resolves, which is fine since telemetry requires auth anyway.
+      const token = getTokenState(instance).getCurrent()
+      logger.trace('auth token check', {tokenPresent: !!token, internal: true})
+
+      if (!token) {
+        logger.debug('waiting for auth token')
+        const hasToken = await new Promise<boolean>((resolve) => {
+          if (instance.isDisposed()) return resolve(false)
+          const cleanup = {unsubscribe: () => {}}
+          const unsub = instance.onDispose(() => {
+            cleanup.unsubscribe()
+            resolve(false)
+          })
+          const sub = getTokenState(instance).observable.subscribe((t) => {
+            if (t) {
+              logger.debug('auth token received')
+              sub.unsubscribe()
+              unsub()
+              resolve(true)
+            }
+          })
+          cleanup.unsubscribe = () => sub.unsubscribe()
+        })
+        if (!hasToken || instance.isDisposed()) {
+          initInFlight.delete(instance)
+          logger.debug('telemetry skipped: no token resolved or instance disposed')
+          return
+        }
+      }
+
+      const manager = createTelemetryManager({
+        sessionId: instance.instanceId,
+        getClient: () => getClient(instance, {apiVersion: DEFAULT_TELEMETRY_API_VERSION}),
+        projectId,
+      })
+
+      const consented = await manager.checkConsent()
+      logger.debug('consent check complete', {consented})
+      if (!consented || instance.isDisposed()) {
+        initInFlight.delete(instance)
+        manager.dispose()
+        return
+      }
+
+      initInFlight.delete(instance)
+      telemetryManagers.set(instance, manager)
+
+      const buffered = pendingHooks.get(instance)
+      if (buffered) {
+        logger.debug('flushing buffered hooks', {hooks: Array.from(buffered)})
+        for (const hookName of buffered) {
+          manager.logHookFirstUsed(hookName)
+        }
+        pendingHooks.delete(instance)
+      }
+
+      const config = instance.config
+      const perspective = typeof config.perspective === 'string' ? config.perspective : 'published'
+      const authMethod = config.auth?.token
+        ? 'token'
+        : config.studio?.auth?.token
+          ? 'studio'
+          : 'default'
+
+      logger.info('telemetry session started', {projectId, perspective, authMethod})
+      manager.logSessionStarted({
+        projectId,
+        perspective,
+        authMethod,
+      })
+
+      instance.onDispose(() => {
+        manager.endSession()
+        telemetryManagers.delete(instance)
+        logger.debug('telemetry session ended')
+      })
+    })
+    .catch((err) => {
+      initInFlight.delete(instance)
+      logger.warn('telemetry init failed', {error: err})
+    })
+}
+
+/**
+ * Retrieves the telemetry manager for an instance, if one exists.
+ * Returns undefined when telemetry is disabled or not yet initialized.
+ *
+ * @internal
+ */
+export function getTelemetryManager(instance: SanityInstance): TelemetryManager | undefined {
+  return telemetryManagers.get(instance)
+}
+
+/**
+ * Record a hook name for an instance. If the telemetry manager is
+ * already initialized the event is logged immediately. Otherwise
+ * the name is buffered and flushed when init completes.
+ *
+ * @internal
+ */
+export function trackHookMounted(instance: SanityInstance, hookName: string): void {
+  if (!isDevMode()) return
+
+  const manager = findManager(instance)
+  if (manager) {
+    logger.trace('hook mounted (logged)', {hookName, internal: true})
+    manager.logHookFirstUsed(hookName)
+    return
+  }
+
+  const root = getRootInstance(instance)
+  let hooks = pendingHooks.get(root)
+  if (!hooks) {
+    hooks = new Set()
+    pendingHooks.set(root, hooks)
+  }
+  if (!hooks.has(hookName)) {
+    logger.trace('hook mounted (buffered)', {hookName, internal: true})
+  }
+  hooks.add(hookName)
+}
+
+function findManager(instance: SanityInstance): TelemetryManager | undefined {
+  let current: SanityInstance | undefined = instance
+  while (current) {
+    const manager = telemetryManagers.get(current)
+    if (manager) return manager
+    current = typeof current.getParent === 'function' ? current.getParent() : undefined
+  }
+  return undefined
+}
+
+function getRootInstance(instance: SanityInstance): SanityInstance {
+  let current = instance
+  while (typeof current.getParent === 'function' && current.getParent()) {
+    current = current.getParent()!
+  }
+  return current
+}

package/src/telemetry/telemetryManager.test.ts

@@ -0,0 +1,263 @@
+import {createBatchedStore} from '@sanity/telemetry'
+import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest'
+
+import {createTelemetryManager} from './telemetryManager'
+
+vi.mock('@sanity/telemetry', () => {
+  const mockLogger = {
+    log: vi.fn(),
+    updateUserProperties: vi.fn(),
+    resume: vi.fn(),
+    trace: vi.fn(),
+  }
+  return {
+    createBatchedStore: vi.fn(() => ({
+      logger: mockLogger,
+      end: vi.fn(),
+      flush: vi.fn(() => Promise.resolve()),
+    })),
+    defineEvent: vi.fn((opts) => ({
+      type: 'log' as const,
+      name: opts.name,
+      version: opts.version,
+      description: opts.description,
+      schema: undefined as never,
+    })),
+  }
+})
+
+vi.mock('../version', () => ({
+  CORE_SDK_VERSION: '2.8.0-test',
+}))
+
+describe('createTelemetryManager', () => {
+  const mockClient = {
+    request: vi.fn((): Promise<unknown> => Promise.resolve()),
+    getUrl: vi.fn((path: string) => `https://abc123.api.sanity.io/v2024-11-12${path}`),
+  }
+
+  const getClient = () => mockClient as never
+
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  afterEach(() => {
+    vi.restoreAllMocks()
+  })
+
+  it('creates a batched store with the given session ID', () => {
+    createTelemetryManager({
+      sessionId: 'test-session-id',
+      getClient,
+      projectId: 'abc123',
+    })
+
+    expect(createBatchedStore).toHaveBeenCalledWith(
+      'test-session-id',
+      expect.objectContaining({
+        flushInterval: 30_000,
+      }),
+    )
+  })
+
+  it('logs session started with SDK version and provided data', () => {
+    const manager = createTelemetryManager({
+      sessionId: 'test-session-id',
+      getClient,
+      projectId: 'abc123',
+    })
+
+    const storeInstance = vi.mocked(createBatchedStore).mock.results[0].value
+    const logger = storeInstance.logger
+
+    manager.logSessionStarted({
+      projectId: 'abc123',
+      perspective: 'published',
+      authMethod: 'token',
+    })
+
+    expect(logger.log).toHaveBeenCalledWith(
+      expect.objectContaining({name: 'SDK Dev Session Started'}),
+      expect.objectContaining({
+        version: '2.8.0-test',
+        projectId: 'abc123',
+        perspective: 'published',
+        authMethod: 'token',
+      }),
+    )
+  })
+
+  it('deduplicates hook first-used events by name', () => {
+    const manager = createTelemetryManager({
+      sessionId: 'test-session-id',
+      getClient,
+      projectId: 'abc123',
+    })
+
+    const storeInstance = vi.mocked(createBatchedStore).mock.results[0].value
+    const logger = storeInstance.logger
+
+    manager.logHookFirstUsed('useQuery')
+    manager.logHookFirstUsed('useQuery')
+    manager.logHookFirstUsed('useDocument')
+
+    const hookCalls = vi
+      .mocked(logger.log)
+      .mock.calls.filter(([event]: [{name: string}]) => event.name === 'SDK Hook Mounted')
+    expect(hookCalls).toHaveLength(2)
+    expect(hookCalls[0][1]).toEqual({hookName: 'useQuery'})
+    expect(hookCalls[1][1]).toEqual({hookName: 'useDocument'})
+  })
+
+  it('tracks hooksUsed set', () => {
+    const manager = createTelemetryManager({
+      sessionId: 'test-session-id',
+      getClient,
+      projectId: 'abc123',
+    })
+
+    manager.logHookFirstUsed('useQuery')
+    manager.logHookFirstUsed('useDocument')
+
+    expect(manager.hooksUsed).toEqual(new Set(['useQuery', 'useDocument']))
+  })
+
+  it('logs dev error events', () => {
+    const manager = createTelemetryManager({
+      sessionId: 'test-session-id',
+      getClient,
+      projectId: 'abc123',
+    })
+
+    const storeInstance = vi.mocked(createBatchedStore).mock.results[0].value
+    const logger = storeInstance.logger
+
+    manager.logDevError('TypeError', 'documentStore')
+
+    expect(logger.log).toHaveBeenCalledWith(expect.objectContaining({name: 'SDK Dev Error'}), {
+      errorType: 'TypeError',
+      hookName: 'documentStore',
+    })
+  })
+
+  it('logs session ended with duration and hooksUsed on endSession', () => {
+    vi.useFakeTimers()
+
+    const manager = createTelemetryManager({
+      sessionId: 'test-session-id',
+      getClient,
+      projectId: 'abc123',
+    })
+
+    const storeInstance = vi.mocked(createBatchedStore).mock.results[0].value
+    const logger = storeInstance.logger
+
+    manager.logHookFirstUsed('useQuery')
+
+    vi.advanceTimersByTime(5000)
+
+    manager.endSession()
+
+    expect(logger.log).toHaveBeenCalledWith(
+      expect.objectContaining({name: 'SDK Dev Session Ended'}),
+      expect.objectContaining({
+        durationSeconds: 5,
+        hooksUsed: ['useQuery'],
+      }),
+    )
+
+    vi.useRealTimers()
+  })
+
+  describe('endSession teardown', () => {
+    it('always uses flush + end (no sendBeacon due to auth header limitation)', () => {
+      const manager = createTelemetryManager({
+        sessionId: 'test-session-id',
+        getClient,
+        projectId: 'abc123',
+      })
+
+      const storeInstance = vi.mocked(createBatchedStore).mock.results[0].value
+
+      manager.endSession()
+
+      expect(storeInstance.flush).toHaveBeenCalled()
+      expect(storeInstance.end).toHaveBeenCalled()
+    })
+  })
+
+  describe('consent resolution', () => {
+    it('checkConsent returns true when user has opted in', async () => {
+      mockClient.request.mockResolvedValue({status: 'granted'})
+
+      const manager = createTelemetryManager({
+        sessionId: 'test-session-id',
+        getClient,
+        projectId: 'abc123',
+      })
+
+      const result = await manager.checkConsent()
+      expect(result).toBe(true)
+      expect(mockClient.request).toHaveBeenCalledWith(
+        expect.objectContaining({uri: '/intake/telemetry-status'}),
+      )
+    })
+
+    it('checkConsent returns false when user has denied telemetry', async () => {
+      mockClient.request.mockResolvedValue({status: 'denied'})
+
+      const manager = createTelemetryManager({
+        sessionId: 'test-session-id',
+        getClient,
+        projectId: 'abc123',
+      })
+
+      expect(await manager.checkConsent()).toBe(false)
+    })
+
+    it('checkConsent returns false when consent is unset', async () => {
+      mockClient.request.mockResolvedValue({status: 'unset'})
+
+      const manager = createTelemetryManager({
+        sessionId: 'test-session-id',
+        getClient,
+        projectId: 'abc123',
+      })
+
+      expect(await manager.checkConsent()).toBe(false)
+    })
+
+    it('checkConsent returns false on network failure', async () => {
+      mockClient.request.mockRejectedValue(new Error('Network error'))
+
+      const manager = createTelemetryManager({
+        sessionId: 'test-session-id',
+        getClient,
+        projectId: 'abc123',
+      })
+
+      expect(await manager.checkConsent()).toBe(false)
+    })
+
+    it('caches consent after the first call', async () => {
+      mockClient.request.mockResolvedValue({status: 'granted'})
+
+      createTelemetryManager({
+        sessionId: 'test-session-id',
+        getClient,
+        projectId: 'abc123',
+      })
+
+      const storeOptions = vi.mocked(createBatchedStore).mock.calls[0][1]
+      const resolveConsent = storeOptions.resolveConsent
+
+      const first = await resolveConsent()
+      const second = await resolveConsent()
+
+      expect(first).toEqual({status: 'granted'})
+      expect(second).toEqual({status: 'granted'})
+      expect(mockClient.request).toHaveBeenCalledTimes(1)
+    })
+  })
+})