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

package/src/telemetry/environment.test.ts

@@ -0,0 +1,119 @@
+import {afterEach, describe, expect, it, vi} from 'vitest'
+
+import {getTelemetryEnvironment, isTelemetryEnabled} from './environment'
+
+describe('getTelemetryEnvironment', () => {
+  afterEach(() => {
+    vi.unstubAllEnvs()
+    vi.unstubAllGlobals()
+  })
+
+  describe('browser', () => {
+    it('returns "development" on localhost', () => {
+      vi.stubGlobal('window', {location: {hostname: 'localhost'}})
+      expect(getTelemetryEnvironment()).toBe('development')
+    })
+
+    it('returns "development" on 127.0.0.1', () => {
+      vi.stubGlobal('window', {location: {hostname: '127.0.0.1'}})
+      expect(getTelemetryEnvironment()).toBe('development')
+    })
+
+    it('returns "production" on *.sanity.studio', () => {
+      vi.stubGlobal('window', {location: {hostname: 'myapp.sanity.studio'}})
+      expect(getTelemetryEnvironment()).toBe('production')
+    })
+
+    it('returns "production" on www.sanity.io (dashboard)', () => {
+      vi.stubGlobal('window', {location: {hostname: 'www.sanity.io'}})
+      expect(getTelemetryEnvironment()).toBe('production')
+    })
+
+    it('returns null on *.sanity.work (staging is intentionally not allowlisted)', () => {
+      vi.stubGlobal('window', {location: {hostname: 'www.sanity.work'}})
+      expect(getTelemetryEnvironment()).toBeNull()
+    })
+
+    it('returns null on *.sanity.dev (preview hosts are intentionally not allowlisted)', () => {
+      vi.stubGlobal('window', {location: {hostname: 'preview-123.sanity.dev'}})
+      expect(getTelemetryEnvironment()).toBeNull()
+    })
+
+    it('is case-insensitive on hostname', () => {
+      vi.stubGlobal('window', {location: {hostname: 'MyApp.Sanity.Studio'}})
+      expect(getTelemetryEnvironment()).toBe('production')
+    })
+
+    it('returns null on a customer-controlled domain', () => {
+      vi.stubGlobal('window', {location: {hostname: 'myapp.customer.com'}})
+      expect(getTelemetryEnvironment()).toBeNull()
+    })
+
+    it('returns null on a lookalike subdomain (suffix match requires a leading dot)', () => {
+      // `evilsanity.studio` ends in `sanity.studio` but not `.sanity.studio`,
+      // so the suffix check rejects it.
+      vi.stubGlobal('window', {location: {hostname: 'evilsanity.studio'}})
+      expect(getTelemetryEnvironment()).toBeNull()
+    })
+
+    it('returns null on the bare apex hostname (sanity.studio with no subdomain)', () => {
+      // The allowlist intentionally only matches subdomains (the leading
+      // `.` in `.sanity.studio` means the apex `sanity.studio` is excluded).
+      vi.stubGlobal('window', {location: {hostname: 'sanity.studio'}})
+      expect(getTelemetryEnvironment()).toBeNull()
+    })
+
+    it('returns null when hostname is missing', () => {
+      vi.stubGlobal('window', {location: {}})
+      expect(getTelemetryEnvironment()).toBeNull()
+    })
+
+    it('returns "development" on localhost even when NODE_ENV is production', () => {
+      vi.stubEnv('NODE_ENV', 'production')
+      vi.stubGlobal('window', {location: {hostname: 'localhost'}})
+      expect(getTelemetryEnvironment()).toBe('development')
+    })
+  })
+
+  describe('node', () => {
+    it('returns "development" when NODE_ENV=development and no window', () => {
+      vi.stubEnv('NODE_ENV', 'development')
+      vi.stubGlobal('window', undefined)
+      expect(getTelemetryEnvironment()).toBe('development')
+    })
+
+    it('returns null when NODE_ENV=production and no window', () => {
+      vi.stubEnv('NODE_ENV', 'production')
+      vi.stubGlobal('window', undefined)
+      expect(getTelemetryEnvironment()).toBeNull()
+    })
+
+    it('returns null when NODE_ENV=test and no window', () => {
+      vi.stubEnv('NODE_ENV', 'test')
+      vi.stubGlobal('window', undefined)
+      expect(getTelemetryEnvironment()).toBeNull()
+    })
+  })
+})
+
+describe('isTelemetryEnabled', () => {
+  afterEach(() => {
+    vi.unstubAllEnvs()
+    vi.unstubAllGlobals()
+  })
+
+  it('returns true on a Sanity-controlled domain', () => {
+    vi.stubGlobal('window', {location: {hostname: 'app.sanity.studio'}})
+    expect(isTelemetryEnabled()).toBe(true)
+  })
+
+  it('returns true on localhost', () => {
+    vi.stubGlobal('window', {location: {hostname: 'localhost'}})
+    expect(isTelemetryEnabled()).toBe(true)
+  })
+
+  it('returns false on a customer domain', () => {
+    vi.stubGlobal('window', {location: {hostname: 'myapp.example.com'}})
+    expect(isTelemetryEnabled()).toBe(false)
+  })
+})

package/src/telemetry/environment.ts

@@ -0,0 +1,92 @@
+/**
+ * Telemetry environment classification.
+ *
+ * - `'development'` — the SDK is running on the local developer's machine
+ *   (`localhost` / `127.0.0.1` in the browser, or `NODE_ENV=development`
+ *   in Node). These are the original dev-only telemetry sessions.
+ *
+ * - `'production'` — the SDK is running on a production Sanity-controlled
+ *   domain (Studio deployments on `*.sanity.studio`, the dashboard on
+ *   `*.sanity.io`) where end users are authenticated Sanity users with
+ *   Populus consent records. Production telemetry is gated to this
+ *   allowlist; SDK apps deployed to customer-controlled domains do not
+ *   emit telemetry. Staging (`*.sanity.work`) and preview
+ *   (`*.sanity.dev`) hosts are deliberately excluded.
+ *
+ * @internal
+ */
+export type TelemetryEnvironment = 'development' | 'production'
+
+/**
+ * Hostname suffixes that count as Sanity-controlled for the purposes of
+ * production telemetry. A user reaching one of these hosts in the
+ * browser is authenticated against Sanity and has a Populus consent
+ * record, so we apply the same telemetry rules as the Studio's
+ * `telemetry-sink`.
+ *
+ * The leading `.` is required: it ensures suffix matches hit a real
+ * subdomain boundary, so apex matches (`sanity.io`, `sanity.studio`)
+ * and lookalikes (`evilsanity.studio`) are excluded. Only production
+ * hosts are listed; staging (`*.sanity.work`) and preview
+ * (`*.sanity.dev`) hosts are excluded by omission.
+ *
+ * @internal
+ */
+const SANITY_CONTROLLED_HOST_SUFFIXES = ['.sanity.studio', '.sanity.io'] as const
+
+function getBrowserHostname(win: Window): string | null {
+  const hostname = win.location?.hostname
+  return typeof hostname === 'string' && hostname.length > 0 ? hostname.toLowerCase() : null
+}
+
+function isLocalHostname(hostname: string): boolean {
+  return hostname === 'localhost' || hostname === '127.0.0.1'
+}
+
+function isSanityControlledHostname(hostname: string): boolean {
+  return SANITY_CONTROLLED_HOST_SUFFIXES.some((suffix) => hostname.endsWith(suffix))
+}
+
+/**
+ * Returns the telemetry environment for the current runtime, or `null`
+ * when telemetry should not run at all.
+ *
+ * Browser:
+ * - `localhost` / `127.0.0.1` → `'development'`
+ * - host matches the Sanity-controlled allowlist → `'production'`
+ * - anything else (customer domains, unknown contexts) → `null`
+ *
+ * Node (scripts, SSR, tests):
+ * - `NODE_ENV=development` → `'development'`
+ * - otherwise → `null`. Production-side server runtimes don't carry the
+ *   browser-authenticated user/consent assumption, so we don't enable
+ *   them under the production gate.
+ *
+ * Bracket-notation `process.env['NODE_ENV']` is used to avoid bundler
+ * dead-code replacement.
+ *
+ * @internal
+ */
+export function getTelemetryEnvironment(): TelemetryEnvironment | null {
+  if (typeof window !== 'undefined') {
+    const hostname = getBrowserHostname(window)
+    if (!hostname) return null
+    if (isLocalHostname(hostname)) return 'development'
+    if (isSanityControlledHostname(hostname)) return 'production'
+    return null
+  }
+
+  if (typeof process !== 'undefined' && process.env?.['NODE_ENV'] === 'development') {
+    return 'development'
+  }
+  return null
+}
+
+/**
+ * Convenience predicate for "telemetry can run in this environment".
+ *
+ * @internal
+ */
+export function isTelemetryEnabled(): boolean {
+  return getTelemetryEnvironment() !== null
+}

package/src/telemetry/events.ts

@@ -0,0 +1,42 @@
+import {defineEvent} from '@sanity/telemetry'
+
+/** @internal */
+export const SDKSessionStarted = defineEvent<{
+  version: string
+  projectId: string
+  perspective: string
+  authMethod: string
+}>({
+  name: 'SDK Session Started',
+  version: 1,
+  description: 'SDK instance created (environment is recorded in the event context)',
+})
+
+/** @internal */
+export const SDKHookMounted = defineEvent<{
+  hookName: string
+}>({
+  name: 'SDK Hook Mounted',
+  version: 1,
+  description: 'An SDK hook was mounted for the first time in this session',
+})
+
+/** @internal */
+export const SDKSessionEnded = defineEvent<{
+  durationSeconds: number
+  hooksUsed: string[]
+}>({
+  name: 'SDK Session Ended',
+  version: 1,
+  description: 'SDK instance disposed (environment is recorded in the event context)',
+})
+
+/** @internal */
+export const SDKError = defineEvent<{
+  errorType: string
+  hookName: string
+}>({
+  name: 'SDK Error',
+  version: 1,
+  description: 'Runtime error caught in the SDK',
+})

package/src/telemetry/initTelemetry.test.ts

@@ -0,0 +1,432 @@
+import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest'
+
+import {getTokenState} from '../auth/authStore'
+import {createSanityInstance} from '../store/createSanityInstance'
+import {getTelemetryEnvironment} from './environment'
+import {getTelemetryManager, initTelemetry, trackHookMounted} from './initTelemetry'
+import {createTelemetryManager} from './telemetryManager'
+
+vi.mock('./environment', () => ({
+  getTelemetryEnvironment: vi.fn(() => null),
+}))
+
+vi.mock('./telemetryManager', () => ({
+  createTelemetryManager: vi.fn(() => ({
+    checkConsent: vi.fn(() => Promise.resolve(true)),
+    logSessionStarted: vi.fn(),
+    logHookFirstUsed: vi.fn(),
+    logError: 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()},
+  })),
+}))
+
+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.
+ */
+const flushPromises = () => new Promise<void>((r) => setTimeout(r, 0))
+
+describe('initTelemetry', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  afterEach(() => {
+    vi.restoreAllMocks()
+  })
+
+  it('does nothing when the environment is not eligible', async () => {
+    vi.mocked(getTelemetryEnvironment).mockReturnValue(null)
+
+    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(getTelemetryEnvironment).mockReturnValue('development')
+
+    const instance = createSanityInstance()
+    initTelemetry(instance, '')
+    await flushPromises()
+
+    expect(createTelemetryManager).not.toHaveBeenCalled()
+    instance.dispose()
+  })
+
+  it('initializes telemetry in development mode with a projectId', async () => {
+    vi.mocked(getTelemetryEnvironment).mockReturnValue('development')
+
+    const instance = createSanityInstance()
+
+    initTelemetry(instance, 'abc123')
+    await flushPromises()
+
+    expect(createTelemetryManager).toHaveBeenCalledWith(
+      expect.objectContaining({
+        sessionId: instance.instanceId,
+        projectId: 'abc123',
+        environment: 'development',
+      }),
+    )
+
+    const manager = vi.mocked(createTelemetryManager).mock.results[0].value
+    expect(manager.logSessionStarted).toHaveBeenCalledWith(
+      expect.objectContaining({
+        projectId: 'abc123',
+        perspective: 'published',
+      }),
+    )
+
+    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(getTelemetryEnvironment).mockReturnValue('development')
+
+    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(getTelemetryEnvironment).mockReturnValue('development')
+
+    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(getTelemetryEnvironment).mockReturnValue('development')
+
+    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(getTelemetryEnvironment).mockReturnValue('development')
+
+    const instance = createSanityInstance()
+
+    vi.mocked(createTelemetryManager).mockReturnValueOnce({
+      checkConsent: vi.fn(() => Promise.resolve(false)),
+      logSessionStarted: vi.fn(),
+      logHookFirstUsed: vi.fn(),
+      logError: 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(getTelemetryEnvironment).mockReturnValue('development')
+
+    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(getTelemetryEnvironment).mockReturnValue('development')
+
+    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('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()
+    })
+  })
+})