@sanity/sdk 2.11.1 → 2.12.0

package/src/telemetry/telemetryManager.test.ts

@@ -38,6 +38,13 @@ describe('createTelemetryManager', () => {
 
   const getClient = () => mockClient as never
 
+  const baseOptions = {
+    sessionId: 'test-session-id',
+    getClient,
+    projectId: 'abc123',
+    environment: 'development' as const,
+  }
+
   beforeEach(() => {
     vi.clearAllMocks()
   })
@@ -47,11 +54,7 @@ describe('createTelemetryManager', () => {
   })
 
   it('creates a batched store with the given session ID', () => {
-    createTelemetryManager({
-      sessionId: 'test-session-id',
-      getClient,
-      projectId: 'abc123',
-    })
+    createTelemetryManager(baseOptions)
 
     expect(createBatchedStore).toHaveBeenCalledWith(
       'test-session-id',
@@ -62,11 +65,7 @@ describe('createTelemetryManager', () => {
   })
 
   it('logs session started with SDK version and provided data', () => {
-    const manager = createTelemetryManager({
-      sessionId: 'test-session-id',
-      getClient,
-      projectId: 'abc123',
-    })
+    const manager = createTelemetryManager(baseOptions)
 
     const storeInstance = vi.mocked(createBatchedStore).mock.results[0].value
     const logger = storeInstance.logger
@@ -78,7 +77,7 @@ describe('createTelemetryManager', () => {
     })
 
     expect(logger.log).toHaveBeenCalledWith(
-      expect.objectContaining({name: 'SDK Dev Session Started'}),
+      expect.objectContaining({name: 'SDK Session Started'}),
       expect.objectContaining({
         version: '2.8.0-test',
         projectId: 'abc123',
@@ -89,11 +88,7 @@ describe('createTelemetryManager', () => {
   })
 
   it('deduplicates hook first-used events by name', () => {
-    const manager = createTelemetryManager({
-      sessionId: 'test-session-id',
-      getClient,
-      projectId: 'abc123',
-    })
+    const manager = createTelemetryManager(baseOptions)
 
     const storeInstance = vi.mocked(createBatchedStore).mock.results[0].value
     const logger = storeInstance.logger
@@ -111,11 +106,7 @@ describe('createTelemetryManager', () => {
   })
 
   it('tracks hooksUsed set', () => {
-    const manager = createTelemetryManager({
-      sessionId: 'test-session-id',
-      getClient,
-      projectId: 'abc123',
-    })
+    const manager = createTelemetryManager(baseOptions)
 
     manager.logHookFirstUsed('useQuery')
     manager.logHookFirstUsed('useDocument')
@@ -123,19 +114,15 @@ describe('createTelemetryManager', () => {
     expect(manager.hooksUsed).toEqual(new Set(['useQuery', 'useDocument']))
   })
 
-  it('logs dev error events', () => {
-    const manager = createTelemetryManager({
-      sessionId: 'test-session-id',
-      getClient,
-      projectId: 'abc123',
-    })
+  it('logs error events', () => {
+    const manager = createTelemetryManager(baseOptions)
 
     const storeInstance = vi.mocked(createBatchedStore).mock.results[0].value
     const logger = storeInstance.logger
 
-    manager.logDevError('TypeError', 'documentStore')
+    manager.logError('TypeError', 'documentStore')
 
-    expect(logger.log).toHaveBeenCalledWith(expect.objectContaining({name: 'SDK Dev Error'}), {
+    expect(logger.log).toHaveBeenCalledWith(expect.objectContaining({name: 'SDK Error'}), {
       errorType: 'TypeError',
       hookName: 'documentStore',
     })
@@ -144,11 +131,7 @@ describe('createTelemetryManager', () => {
   it('logs session ended with duration and hooksUsed on endSession', () => {
     vi.useFakeTimers()
 
-    const manager = createTelemetryManager({
-      sessionId: 'test-session-id',
-      getClient,
-      projectId: 'abc123',
-    })
+    const manager = createTelemetryManager(baseOptions)
 
     const storeInstance = vi.mocked(createBatchedStore).mock.results[0].value
     const logger = storeInstance.logger
@@ -160,7 +143,7 @@ describe('createTelemetryManager', () => {
     manager.endSession()
 
     expect(logger.log).toHaveBeenCalledWith(
-      expect.objectContaining({name: 'SDK Dev Session Ended'}),
+      expect.objectContaining({name: 'SDK Session Ended'}),
       expect.objectContaining({
         durationSeconds: 5,
         hooksUsed: ['useQuery'],
@@ -170,13 +153,114 @@ describe('createTelemetryManager', () => {
     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({
-        sessionId: 'test-session-id',
-        getClient,
-        projectId: 'abc123',
-      })
+      const manager = createTelemetryManager(baseOptions)
 
       const storeInstance = vi.mocked(createBatchedStore).mock.results[0].value
 
@@ -191,11 +275,7 @@ describe('createTelemetryManager', () => {
     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 manager = createTelemetryManager(baseOptions)
 
       const result = await manager.checkConsent()
       expect(result).toBe(true)
@@ -207,11 +287,7 @@ describe('createTelemetryManager', () => {
     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',
-      })
+      const manager = createTelemetryManager(baseOptions)
 
       expect(await manager.checkConsent()).toBe(false)
     })
@@ -219,11 +295,7 @@ describe('createTelemetryManager', () => {
     it('checkConsent returns false when consent is unset', async () => {
       mockClient.request.mockResolvedValue({status: 'unset'})
 
-      const manager = createTelemetryManager({
-        sessionId: 'test-session-id',
-        getClient,
-        projectId: 'abc123',
-      })
+      const manager = createTelemetryManager(baseOptions)
 
       expect(await manager.checkConsent()).toBe(false)
     })
@@ -231,11 +303,7 @@ describe('createTelemetryManager', () => {
     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',
-      })
+      const manager = createTelemetryManager(baseOptions)
 
       expect(await manager.checkConsent()).toBe(false)
     })
@@ -243,11 +311,7 @@ describe('createTelemetryManager', () => {
     it('caches consent after the first call', async () => {
       mockClient.request.mockResolvedValue({status: 'granted'})
 
-      createTelemetryManager({
-        sessionId: 'test-session-id',
-        getClient,
-        projectId: 'abc123',
-      })
+      createTelemetryManager(baseOptions)
 
       const storeOptions = vi.mocked(createBatchedStore).mock.calls[0][1]
       const resolveConsent = storeOptions.resolveConsent

package/src/telemetry/telemetryManager.ts

@@ -10,12 +10,8 @@ import {
 
 import {createLogger} from '../utils/logger'
 import {CORE_SDK_VERSION} from '../version'
-import {
-  SDKDevError,
-  SDKDevSessionEnded,
-  SDKDevSessionStarted,
-  SDKHookMounted,
-} from './__telemetry__/sdk.telemetry'
+import {type TelemetryEnvironment} from './environment'
+import {SDKError, SDKHookMounted, SDKSessionEnded, SDKSessionStarted} from './events'
 
 const FLUSH_INTERVAL_MS = 30_000
 const CONSENT_TAG = 'telemetry-consent.sdk'
@@ -24,10 +20,13 @@ const BATCH_TAG = 'telemetry.batch'
 const log = createLogger('telemetry')
 
 /**
- * Manages dev-mode telemetry for a single SDK instance.
+ * Manages 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.
+ * The `environment` is captured at construction time and recorded in
+ * the event context so downstream pipelines can distinguish dev and
+ * production sessions.
  *
  * @internal
  */
@@ -40,16 +39,16 @@ export interface TelemetryManager {
    */
   checkConsent(): Promise<boolean>
 
-  /** Log a "SDK Dev Session Started" event */
+  /** Log a "SDK Session Started" event */
   logSessionStarted(data: {projectId: string; perspective: string; authMethod: string}): void
 
-  /** Log a "SDK Hook First Used" event (deduplicated per hook name) */
+  /** Log a "SDK Hook Mounted" event (deduplicated per hook name) */
   logHookFirstUsed(hookName: string): void
 
-  /** Log a "SDK Dev Error" event */
-  logDevError(errorType: string, hookName: string): void
+  /** Log a "SDK Error" event */
+  logError(errorType: string, hookName: string): void
 
-  /** Log a "SDK Dev Session Ended" event and tear down the store */
+  /** Log a "SDK Session Ended" event and tear down the store */
   endSession(): void
 
   /** Tear down the store without logging a session-end event */
@@ -63,6 +62,7 @@ interface TelemetryManagerOptions {
   sessionId: string
   getClient: () => SanityClient
   projectId: string
+  environment: TelemetryEnvironment
 }
 
 /**
@@ -75,7 +75,7 @@ interface TelemetryManagerOptions {
  * @internal
  */
 export function createTelemetryManager(options: TelemetryManagerOptions): TelemetryManager {
-  const {sessionId, getClient, projectId} = options
+  const {sessionId, getClient, projectId, environment} = options
   const startedAt = Date.now()
   const emittedHooks = new Set<string>()
 
@@ -97,18 +97,28 @@ export function createTelemetryManager(options: TelemetryManagerOptions): Teleme
   }
 
   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',
-      },
-    }))
+    batch.map((event) => {
+      // Trace events (`trace.start` / `trace.log` / `trace.error` /
+      // `trace.complete`) arrive with their own caller-provided `context`.
+      // Log / userProperties events don't. Narrow via `in` so `event`
+      // stays typed as `TelemetryEvent`, then merge so we don't drop the
+      // trace context. SDK-owned fields below win on conflict.
+      const existing =
+        'context' in event ? (event.context as Record<string, unknown> | undefined) : undefined
+      return {
+        ...event,
+        context: {
+          ...existing,
+          version: CORE_SDK_VERSION,
+          environment,
+          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})
+    log.debug('sending event batch', {batchSize: batch.length, environment})
     return client.request({
       uri: '/intake/batch',
       method: 'POST',
@@ -135,13 +145,14 @@ export function createTelemetryManager(options: TelemetryManagerOptions): Teleme
     },
 
     logSessionStarted(data) {
-      log.debug('event: SDK Dev Session Started', {
+      log.debug('event: SDK Session Started', {
         projectId: data.projectId,
         perspective: data.perspective,
         authMethod: data.authMethod,
         version: CORE_SDK_VERSION,
+        environment,
       })
-      logger.log(SDKDevSessionStarted, {
+      logger.log(SDKSessionStarted, {
         version: CORE_SDK_VERSION,
         ...data,
       })
@@ -154,18 +165,19 @@ export function createTelemetryManager(options: TelemetryManagerOptions): Teleme
       logger.log(SDKHookMounted, {hookName})
     },
 
-    logDevError(errorType: string, hookName: string) {
-      log.debug('event: SDK Dev Error', {errorType, hookName})
-      logger.log(SDKDevError, {errorType, hookName})
+    logError(errorType: string, hookName: string) {
+      log.debug('event: SDK Error', {errorType, hookName})
+      logger.log(SDKError, {errorType, hookName})
     },
 
     endSession() {
       const durationSeconds = Math.round((Date.now() - startedAt) / 1000)
-      log.debug('event: SDK Dev Session Ended', {
+      log.debug('event: SDK Session Ended', {
         durationSeconds,
         hooksUsed: [...emittedHooks],
+        environment,
       })
-      logger.log(SDKDevSessionEnded, {
+      logger.log(SDKSessionEnded, {
         durationSeconds,
         hooksUsed: [...emittedHooks],
       })

package/src/telemetry/devMode.test.ts

@@ -1,60 +0,0 @@
-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 true on localhost even when NODE_ENV is production', () => {
-    vi.stubEnv('NODE_ENV', 'production')
-    vi.stubGlobal('window', {
-      location: {href: 'http://localhost: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

@@ -1,41 +0,0 @@
-/**
- * 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 for the
- * SDK consumer (i.e. a developer building an app with `@sanity/sdk`).
- *
- * Browser: returns true only when the URL is `localhost` or `127.0.0.1`.
- * The URL check is the primary signal because consumer bundlers may or
- * may not forward `NODE_ENV` to the browser reliably.
- *
- * Node (scripts / non-browser): falls back to `NODE_ENV === 'development'`.
- *
- * Bracket-notation `process.env['NODE_ENV']` is used to avoid bundler
- * dead-code replacement.
- *
- * @returns True if the SDK is running in a development environment
- * @internal
- */
-export function isDevMode(): boolean {
-  if (typeof window !== 'undefined') {
-    return isLocalUrl(window)
-  }
-
-  return typeof process !== 'undefined' && process.env?.['NODE_ENV'] === 'development'
-}