@sanity/sdk 2.8.0 → 2.9.0

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

package/src/telemetry/telemetryManager.ts

@@ -0,0 +1,187 @@
+import {type SanityClient} from '@sanity/client'
+import {
+  type ConsentStatus,
+  createBatchedStore,
+  type SessionId,
+  type TelemetryEvent,
+  type TelemetryLogger,
+  type TelemetryStore,
+} from '@sanity/telemetry'
+
+import {createLogger} from '../utils/logger'
+import {CORE_SDK_VERSION} from '../version'
+import {
+  SDKDevError,
+  SDKDevSessionEnded,
+  SDKDevSessionStarted,
+  SDKHookMounted,
+} from './__telemetry__/sdk.telemetry'
+
+const FLUSH_INTERVAL_MS = 30_000
+const CONSENT_TAG = 'telemetry-consent.sdk'
+const BATCH_TAG = 'telemetry.batch'
+
+const log = createLogger('telemetry')
+
+/**
+ * Manages dev-mode telemetry for a single SDK instance.
+ *
+ * Wraps `@sanity/telemetry`'s batched store with SDK-specific concerns:
+ * consent caching, session lifecycle events, and hook usage tracking.
+ *
+ * @internal
+ */
+export interface TelemetryManager {
+  /**
+   * Eagerly resolve and cache the user's consent status.
+   * Returns true only when the user has explicitly opted in (`granted`).
+   * Call this before logging any events to avoid buffering events that
+   * will be dropped on the first flush.
+   */
+  checkConsent(): Promise<boolean>
+
+  /** Log a "SDK Dev Session Started" event */
+  logSessionStarted(data: {projectId: string; perspective: string; authMethod: string}): void
+
+  /** Log a "SDK Hook First Used" event (deduplicated per hook name) */
+  logHookFirstUsed(hookName: string): void
+
+  /** Log a "SDK Dev Error" event */
+  logDevError(errorType: string, hookName: string): void
+
+  /** Log a "SDK Dev Session Ended" event and tear down the store */
+  endSession(): void
+
+  /** Tear down the store without logging a session-end event */
+  dispose(): void
+
+  /** The set of hook names used during this session */
+  readonly hooksUsed: ReadonlySet<string>
+}
+
+interface TelemetryManagerOptions {
+  sessionId: string
+  getClient: () => SanityClient
+  projectId: string
+}
+
+/**
+ * Creates a telemetry manager for a single SDK instance session.
+ *
+ * The manager initializes a `createBatchedStore` from `@sanity/telemetry`,
+ * caches the consent check for the lifetime of the session, and provides
+ * typed methods for each SDK telemetry event.
+ *
+ * @internal
+ */
+export function createTelemetryManager(options: TelemetryManagerOptions): TelemetryManager {
+  const {sessionId, getClient, projectId} = options
+  const startedAt = Date.now()
+  const emittedHooks = new Set<string>()
+
+  let cachedConsent: {status: ConsentStatus} | null = null
+
+  const resolveConsent = async (): Promise<{status: ConsentStatus}> => {
+    if (cachedConsent) return cachedConsent
+    try {
+      const client = getClient()
+      const result = await client.request<{status: ConsentStatus}>({
+        uri: '/intake/telemetry-status',
+        tag: CONSENT_TAG,
+      })
+      cachedConsent = result
+    } catch {
+      cachedConsent = {status: 'undetermined'}
+    }
+    return cachedConsent
+  }
+
+  const enrichBatch = (batch: TelemetryEvent[]) =>
+    batch.map((event) => ({
+      ...event,
+      context: {
+        version: CORE_SDK_VERSION,
+        environment: 'development' as const,
+        origin: typeof window !== 'undefined' ? window.location.origin : 'node',
+      },
+    }))
+
+  const sendEvents = async (batch: TelemetryEvent[]): Promise<unknown> => {
+    const client = getClient()
+    log.debug('sending event batch', {batchSize: batch.length})
+    return client.request({
+      uri: '/intake/batch',
+      method: 'POST',
+      body: {projectId, batch: enrichBatch(batch)},
+      tag: BATCH_TAG,
+    })
+  }
+
+  const store: TelemetryStore<Record<string, unknown>> = createBatchedStore(
+    sessionId as SessionId,
+    {
+      flushInterval: FLUSH_INTERVAL_MS,
+      resolveConsent,
+      sendEvents,
+    },
+  )
+
+  const logger: TelemetryLogger<Record<string, unknown>> = store.logger
+
+  return {
+    async checkConsent() {
+      const {status} = await resolveConsent()
+      return status === 'granted'
+    },
+
+    logSessionStarted(data) {
+      log.debug('event: SDK Dev Session Started', {
+        projectId: data.projectId,
+        perspective: data.perspective,
+        authMethod: data.authMethod,
+        version: CORE_SDK_VERSION,
+      })
+      logger.log(SDKDevSessionStarted, {
+        version: CORE_SDK_VERSION,
+        ...data,
+      })
+    },
+
+    logHookFirstUsed(hookName: string) {
+      if (emittedHooks.has(hookName)) return
+      emittedHooks.add(hookName)
+      log.debug('event: SDK Hook Mounted', {hookName})
+      logger.log(SDKHookMounted, {hookName})
+    },
+
+    logDevError(errorType: string, hookName: string) {
+      log.debug('event: SDK Dev Error', {errorType, hookName})
+      logger.log(SDKDevError, {errorType, hookName})
+    },
+
+    endSession() {
+      const durationSeconds = Math.round((Date.now() - startedAt) / 1000)
+      log.debug('event: SDK Dev Session Ended', {
+        durationSeconds,
+        hooksUsed: [...emittedHooks],
+      })
+      logger.log(SDKDevSessionEnded, {
+        durationSeconds,
+        hooksUsed: [...emittedHooks],
+      })
+
+      store.flush().catch(() => {
+        // Best-effort flush on dispose; swallow errors
+      })
+      store.end()
+    },
+
+    dispose() {
+      store.end()
+    },
+
+    get hooksUsed(): ReadonlySet<string> {
+      return emittedHooks
+    },
+  }
+}

package/src/users/usersStore.test.ts

@@ -451,6 +451,7 @@ describe('usersStore', () => {
       expect(specificRequest).toHaveBeenCalledWith({
         method: 'GET',
         uri: `/users/${projectUserId}`,
+        tag: 'users.get',
       })
 
       const expectedUser: SanityUser = {

package/src/users/usersStore.ts

@@ -31,6 +31,7 @@ import {createStateSourceAction, type SelectorContext} from '../store/createStat
 import {type StoreState} from '../store/createStoreState'
 import {defineStore, type StoreContext} from '../store/defineStore'
 import {insecureRandomId} from '../utils/ids'
+import {setCleanupTimeout} from '../utils/setCleanupTimeout'
 import {
   addSubscription,
   cancelRequest,
@@ -130,6 +131,7 @@ const listenForLoadMoreAndFetch = ({state, instance}: StoreContext<UsersStoreSta
                   .request<PatchedSanityUserFromClient>({
                     method: 'GET',
                     uri: `/users/${userId}`,
+                    tag: 'users.get',
                   })
                   .pipe(
                     map((user) => {
@@ -183,6 +185,7 @@ const listenForLoadMoreAndFetch = ({state, instance}: StoreContext<UsersStoreSta
                 .request<SanityUser | SanityUserResponse>({
                   method: 'GET',
                   uri: `access/${resourceType}/${resourceId}/users/${userId}`,
+                  tag: 'users.get',
                 })
                 .pipe(
                   map((response) => {
@@ -251,6 +254,7 @@ const listenForLoadMoreAndFetch = ({state, instance}: StoreContext<UsersStoreSta
                 client.observable.request<SanityUserResponse>({
                   method: 'GET',
                   uri: `access/${resource.type}/${resource.id}/users`,
+                  tag: 'users.list',
                   query: cursor
                     ? {nextCursor: cursor, limit: batchSize.toString()}
                     : {limit: batchSize.toString()},
@@ -310,7 +314,7 @@ export const getUsersState = bindActionGlobally(
       const key = getUsersKey(instance, options)
       state.set('addSubscription', addSubscription(subscriptionId, key))
       return () => {
-        setTimeout(
+        setCleanupTimeout(
           () => state.set('removeSubscription', removeSubscription(subscriptionId, key)),
           USERS_STATE_CLEAR_DELAY,
         )