@sanity/sdk 3.0.0-rc.0 → 3.0.0-rc.2

package/src/telemetry/initTelemetry.ts

@@ -0,0 +1,218 @@
+import {type SanityInstance} from '../store/createSanityInstance'
+import {createLogger} from '../utils/logger'
+import {getTelemetryEnvironment} from './environment'
+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 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
+ * instance has already been created.
+ *
+ * @internal
+ */
+export function initTelemetry(instance: SanityInstance, projectId: string): void {
+  const environment = getTelemetryEnvironment()
+  if (!environment) {
+    logger.trace('initTelemetry skipped: environment not eligible', {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, environment})
+
+  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)
+          })
+          // 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 (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)
+          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,
+        environment,
+      })
+
+      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, environment})
+      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 (!getTelemetryEnvironment()) 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 {
+  return telemetryManagers.get(instance)
+}
+
+function getRootInstance(instance: SanityInstance): SanityInstance {
+  return instance
+}

package/src/telemetry/telemetryManager.test.ts

@@ -0,0 +1,327 @@
+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
+
+  const baseOptions = {
+    sessionId: 'test-session-id',
+    getClient,
+    projectId: 'abc123',
+    environment: 'development' as const,
+  }
+
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  afterEach(() => {
+    vi.restoreAllMocks()
+  })
+
+  it('creates a batched store with the given session ID', () => {
+    createTelemetryManager(baseOptions)
+
+    expect(createBatchedStore).toHaveBeenCalledWith(
+      'test-session-id',
+      expect.objectContaining({
+        flushInterval: 30_000,
+      }),
+    )
+  })
+
+  it('logs session started with SDK version and provided data', () => {
+    const manager = createTelemetryManager(baseOptions)
+
+    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 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(baseOptions)
+
+    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(baseOptions)
+
+    manager.logHookFirstUsed('useQuery')
+    manager.logHookFirstUsed('useDocument')
+
+    expect(manager.hooksUsed).toEqual(new Set(['useQuery', 'useDocument']))
+  })
+
+  it('logs error events', () => {
+    const manager = createTelemetryManager(baseOptions)
+
+    const storeInstance = vi.mocked(createBatchedStore).mock.results[0].value
+    const logger = storeInstance.logger
+
+    manager.logError('TypeError', 'documentStore')
+
+    expect(logger.log).toHaveBeenCalledWith(expect.objectContaining({name: 'SDK Error'}), {
+      errorType: 'TypeError',
+      hookName: 'documentStore',
+    })
+  })
+
+  it('logs session ended with duration and hooksUsed on endSession', () => {
+    vi.useFakeTimers()
+
+    const manager = createTelemetryManager(baseOptions)
+
+    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 Session Ended'}),
+      expect.objectContaining({
+        durationSeconds: 5,
+        hooksUsed: ['useQuery'],
+      }),
+    )
+
+    vi.useRealTimers()
+  })
+
+  describe('environment context', () => {
+    type EnrichedContext = {
+      environment?: string
+      version?: string
+      origin?: string
+      traceCorrelationId?: string
+    }
+    type EnrichedEvent = {
+      type?: string
+      name?: string
+      version?: number
+      traceId?: string
+      sessionId?: string
+      createdAt?: string
+      data?: unknown
+      context: EnrichedContext
+    }
+    const getRequestBody = () => {
+      const [args] = mockClient.request.mock.calls as unknown as Array<
+        [{body: {batch: EnrichedEvent[]}}]
+      >
+      return args[0].body
+    }
+
+    it('records "development" in the enriched batch context and preserves the event payload', async () => {
+      createTelemetryManager({...baseOptions, environment: 'development'})
+
+      const storeOptions = vi.mocked(createBatchedStore).mock.calls[0][1]
+      await storeOptions.sendEvents([
+        {
+          type: 'log',
+          version: 1,
+          name: 'SDK Session Started',
+          sessionId: 'test-session-id',
+          createdAt: '2026-01-01T00:00:00Z',
+          data: {projectId: 'p1'},
+        } as never,
+      ])
+
+      const [event] = getRequestBody().batch
+      expect(event.context.environment).toBe('development')
+      expect(event.type).toBe('log')
+      expect(event.name).toBe('SDK Session Started')
+      expect(event.version).toBe(1)
+      expect(event.sessionId).toBe('test-session-id')
+      expect(event.data).toEqual({projectId: 'p1'})
+    })
+
+    it('records "production" in the enriched batch context', async () => {
+      createTelemetryManager({...baseOptions, environment: 'production'})
+
+      const storeOptions = vi.mocked(createBatchedStore).mock.calls[0][1]
+      await storeOptions.sendEvents([
+        {
+          type: 'log',
+          version: 1,
+          name: 'SDK Session Started',
+          sessionId: 'test-session-id',
+          createdAt: '2026-01-01T00:00:00Z',
+          data: {},
+        } as never,
+      ])
+
+      expect(getRequestBody().batch[0].context.environment).toBe('production')
+    })
+
+    it('preserves pre-existing context fields from trace events and lets SDK fields take precedence on conflict', async () => {
+      // Trace events from `@sanity/telemetry` arrive with a top-level
+      // `context` (see `TelemetryTraceStartEvent`, etc.). Replacing rather
+      // than merging would silently drop those fields. The SDK-managed
+      // fields (`version`, `environment`, `origin`) should also win on key
+      // collision so they remain authoritative. The rest of the trace
+      // event (`type`, `name`, `traceId`, `sessionId`, `createdAt`) must
+      // survive — downstream consumers (Rudderstack via telemetry-sink)
+      // read those fields directly off each batch entry.
+      createTelemetryManager({...baseOptions, environment: 'production'})
+
+      const storeOptions = vi.mocked(createBatchedStore).mock.calls[0][1]
+      await storeOptions.sendEvents([
+        {
+          type: 'trace.start',
+          name: 'some.trace',
+          version: 1,
+          traceId: 't1',
+          sessionId: 'test-session-id',
+          createdAt: '2026-01-01T00:00:00Z',
+          context: {
+            traceCorrelationId: 'abc-123',
+            environment: 'should-be-overwritten',
+          },
+        } as never,
+      ])
+
+      const [event] = getRequestBody().batch
+      expect(event.context.traceCorrelationId).toBe('abc-123')
+      expect(event.context.environment).toBe('production')
+      expect(event.context.version).toBe('2.8.0-test')
+      expect(event.type).toBe('trace.start')
+      expect(event.name).toBe('some.trace')
+      expect(event.traceId).toBe('t1')
+      expect(event.sessionId).toBe('test-session-id')
+      expect(event.createdAt).toBe('2026-01-01T00:00:00Z')
+    })
+  })
+
+  describe('endSession teardown', () => {
+    it('always uses flush + end (no sendBeacon due to auth header limitation)', () => {
+      const manager = createTelemetryManager(baseOptions)
+
+      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(baseOptions)
+
+      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(baseOptions)
+
+      expect(await manager.checkConsent()).toBe(false)
+    })
+
+    it('checkConsent returns false when consent is unset', async () => {
+      mockClient.request.mockResolvedValue({status: 'unset'})
+
+      const manager = createTelemetryManager(baseOptions)
+
+      expect(await manager.checkConsent()).toBe(false)
+    })
+
+    it('checkConsent returns false on network failure', async () => {
+      mockClient.request.mockRejectedValue(new Error('Network error'))
+
+      const manager = createTelemetryManager(baseOptions)
+
+      expect(await manager.checkConsent()).toBe(false)
+    })
+
+    it('caches consent after the first call', async () => {
+      mockClient.request.mockResolvedValue({status: 'granted'})
+
+      createTelemetryManager(baseOptions)
+
+      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)
+    })
+  })
+})