@sanity/sdk 2.8.0 → 2.10.0

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/reducers.ts

@@ -1,6 +1,5 @@
-import {omit} from 'lodash-es'
-
 import {type SanityInstance} from '../store/createSanityInstance'
+import {omitProperty} from '../utils/object'
 import {type GetUsersOptions, type SanityUserResponse, type UsersStoreState} from './types'
 import {DEFAULT_USERS_BATCH_SIZE} from './usersConstants'
 
@@ -48,7 +47,7 @@ export const removeSubscription =
     const group = prev.users[key]
     if (!group) return prev
     const subscriptions = group.subscriptions.filter((id) => id !== subscriptionId)
-    if (!subscriptions.length) return {...prev, users: omit(prev.users, key)}
+    if (!subscriptions.length) return {...prev, users: omitProperty(prev.users, key)}
     return {...prev, users: {...prev.users, [key]: {...group, subscriptions}}}
   }
 
@@ -83,7 +82,7 @@ export const cancelRequest =
     const group = prev.users[key]
     if (!group) return prev
     if (group.subscriptions.length) return prev
-    return {...prev, users: omit(prev.users, key)}
+    return {...prev, users: omitProperty(prev.users, key)}
   }
 
 export const initializeRequest =

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,
         )

package/src/utils/createFetcherStore.test.ts

@@ -127,8 +127,9 @@ describe('createFetcherStore', () => {
     expect(fetchSpy).toHaveBeenCalledTimes(1)
 
     // Second subscription within throttle interval
-    const sub2 = stateSource.subscribe()
-    await firstValueFrom(stateSource.observable)
+    const stateSource2 = store.getState(instance, 1)
+    const sub2 = stateSource2.subscribe()
+    await firstValueFrom(stateSource2.observable)
     expect(fetchSpy).toHaveBeenCalledTimes(1)
 
     // Advance past throttle interval
@@ -136,8 +137,9 @@ describe('createFetcherStore', () => {
     await vi.advanceTimersByTimeAsync(1000)
 
     // Third subscription after throttle interval
-    const sub3 = stateSource.subscribe()
-    await firstValueFrom(stateSource.observable)
+    const stateSource3 = store.getState(instance, 1)
+    const sub3 = stateSource3.subscribe()
+    await firstValueFrom(stateSource3.observable)
     expect(fetchSpy).toHaveBeenCalledTimes(2)
 
     sub1()

package/src/utils/createFetcherStore.ts

@@ -1,4 +1,3 @@
-import {omit} from 'lodash-es'
 import {asapScheduler, EMPTY, firstValueFrom, from, Observable} from 'rxjs'
 import {
   catchError,
@@ -23,6 +22,8 @@ import {
 } from '../store/createStateSourceAction'
 import {defineStore, type StoreContext} from '../store/defineStore'
 import {insecureRandomId} from '../utils/ids'
+import {omitProperty} from '../utils/object'
+import {setCleanupTimeout} from './setCleanupTimeout'
 
 interface CreateFetcherStoreOptions<TParams extends unknown[], TData> {
   /**
@@ -182,8 +183,10 @@ export function createFetcherStore<TParams extends unknown[], TData>({
                     stateByParams: {
                       ...prev.stateByParams,
                       [entry.key]: {
-                        ...omit(entry, 'error'),
-                        ...omit(prev.stateByParams[entry.key], 'error'),
+                        ...omitProperty(entry, 'error'),
+                        ...(prev.stateByParams[entry.key]
+                          ? omitProperty(prev.stateByParams[entry.key], 'error')
+                          : {}),
                         data,
                       },
                     },
@@ -247,14 +250,14 @@ export function createFetcherStore<TParams extends unknown[], TData>({
         }))
 
         return () => {
-          setTimeout(() => {
+          setCleanupTimeout(() => {
             state.set('removeSubscription', (prev: FetcherStoreState<TParams, TData>) => {
               const entry = prev.stateByParams[key]
               if (!entry) return prev
 
               const newSubs = (entry.subscriptions || []).filter((id) => id !== subscriptionId)
               if (newSubs.length === 0) {
-                return {stateByParams: omit(prev.stateByParams, key)}
+                return {stateByParams: omitProperty(prev.stateByParams, key)}
               }
 
               return {

package/src/utils/getStagingApiHost.test.ts

@@ -0,0 +1,21 @@
+import {describe, expect, it, vi} from 'vitest'
+
+import {getStagingApiHost} from './getStagingApiHost'
+
+describe('getStagingApiHost', () => {
+  it('returns staging host when __SANITY_STAGING__ is true', () => {
+    vi.stubGlobal('__SANITY_STAGING__', true)
+    expect(getStagingApiHost()).toBe('https://api.sanity.work')
+    vi.unstubAllGlobals()
+  })
+
+  it('returns undefined when __SANITY_STAGING__ is false', () => {
+    vi.stubGlobal('__SANITY_STAGING__', false)
+    expect(getStagingApiHost()).toBeUndefined()
+    vi.unstubAllGlobals()
+  })
+
+  it('returns undefined when __SANITY_STAGING__ is not defined', () => {
+    expect(getStagingApiHost()).toBeUndefined()
+  })
+})

package/src/utils/getStagingApiHost.ts

@@ -0,0 +1,14 @@
+declare const __SANITY_STAGING__: boolean | undefined
+
+/**
+ * Returns the staging API host if the `__SANITY_STAGING__` build-time flag is
+ * set to `true` (mirroring how Sanity Studio detects staging builds).
+ *
+ * @internal
+ */
+export function getStagingApiHost(): string | undefined {
+  if (typeof __SANITY_STAGING__ !== 'undefined' && __SANITY_STAGING__ === true) {
+    return 'https://api.sanity.work'
+  }
+  return undefined
+}

package/src/utils/ids.test.ts

@@ -1,34 +1,6 @@
 import {describe, expect, it} from 'vitest'
 
-import {getDraftId, getPublishedId, insecureRandomId} from './ids'
-
-describe('getDraftId', () => {
-  it('should add drafts prefix to non-draft ids', () => {
-    expect(getDraftId('abc123')).toBe('drafts.abc123')
-  })
-
-  it('should not modify ids that already have drafts prefix', () => {
-    expect(getDraftId('drafts.abc123')).toBe('drafts.abc123')
-  })
-
-  it('should handle empty string', () => {
-    expect(getDraftId('')).toBe('drafts.')
-  })
-})
-
-describe('getPublishedId', () => {
-  it('should remove drafts prefix from draft ids', () => {
-    expect(getPublishedId('drafts.abc123')).toBe('abc123')
-  })
-
-  it('should not modify ids that dont have drafts prefix', () => {
-    expect(getPublishedId('abc123')).toBe('abc123')
-  })
-
-  it('should handle empty string', () => {
-    expect(getPublishedId('')).toBe('')
-  })
-})
+import {insecureRandomId} from './ids'
 
 describe('insecureRandomId', () => {
   it('should generate 16-character string', () => {

package/src/utils/ids.ts

@@ -1,13 +1,3 @@
-export function getPublishedId(id: string): string {
-  const draftsPrefix = 'drafts.'
-  return id.startsWith(draftsPrefix) ? id.slice(draftsPrefix.length) : id
-}
-
-export function getDraftId(id: string): string {
-  const draftsPrefix = 'drafts.'
-  return id.startsWith(draftsPrefix) ? id : `${draftsPrefix}${id}`
-}
-
 export function insecureRandomId(): string {
   return Array.from({length: 16}, () => Math.floor(Math.random() * 16).toString(16)).join('')
 }

package/src/utils/isImportError.test.ts

@@ -0,0 +1,72 @@
+import {describe, expect, test} from 'vitest'
+
+import {isImportError} from './isImportError'
+
+describe('isImportError', () => {
+  test('returns false for non-Error values', () => {
+    expect(isImportError(null)).toBe(false)
+    expect(isImportError(undefined)).toBe(false)
+    expect(isImportError('Loading chunk 5 failed.')).toBe(false)
+    expect(isImportError({message: 'Loading chunk 5 failed.'})).toBe(false)
+    expect(isImportError(42)).toBe(false)
+  })
+
+  test('returns false for unrelated Error instances', () => {
+    expect(isImportError(new Error('Something else went wrong'))).toBe(false)
+    expect(isImportError(new TypeError('Cannot read properties of undefined'))).toBe(false)
+  })
+
+  test('detects webpack ChunkLoadError by name', () => {
+    const err = new Error('arbitrary message')
+    err.name = 'ChunkLoadError'
+    expect(isImportError(err)).toBe(true)
+  })
+
+  test('detects webpack numeric chunk failure messages', () => {
+    expect(isImportError(new Error('Loading chunk 5 failed.'))).toBe(true)
+    expect(
+      isImportError(new Error('Loading chunk 42 failed. (missing: https://x.com/42.abc.js)')),
+    ).toBe(true)
+  })
+
+  test('detects webpack named chunk failure messages', () => {
+    expect(isImportError(new Error('Loading chunk vendors-foo failed.'))).toBe(true)
+    expect(isImportError(new Error('Loading chunk react_vendors failed.'))).toBe(true)
+  })
+
+  test('detects Vite "Failed to fetch dynamically imported module"', () => {
+    expect(
+      isImportError(
+        new TypeError(
+          'Failed to fetch dynamically imported module: https://example.com/assets/Home-abc123.js',
+        ),
+      ),
+    ).toBe(true)
+  })
+
+  test('detects Firefox "error loading dynamically imported module"', () => {
+    expect(
+      isImportError(
+        new TypeError(
+          'error loading dynamically imported module: http://localhost:8080/src/views/Dashboard/index.vue',
+        ),
+      ),
+    ).toBe(true)
+  })
+
+  test('detects Safari module-script failures with and without the "ing" suffix', () => {
+    expect(isImportError(new TypeError('Importing a module script failed.'))).toBe(true)
+    expect(isImportError(new TypeError('Import a module script failed.'))).toBe(true)
+  })
+
+  test('detects Vite CSS preload failures', () => {
+    expect(isImportError(new Error('Unable to preload CSS for /assets/App-BBLnt7oG.css'))).toBe(
+      true,
+    )
+  })
+
+  test('matches case-insensitively', () => {
+    expect(isImportError(new Error('loading chunk 1 FAILED'))).toBe(true)
+    expect(isImportError(new Error('FAILED TO FETCH DYNAMICALLY IMPORTED MODULE'))).toBe(true)
+  })
+})

package/src/utils/isImportError.ts

@@ -0,0 +1,34 @@
+/**
+ * Returns true when the given error looks like a dynamic-import or
+ * code-split chunk-loading failure.
+ *
+ * These errors typically surface when a user has a tab open against a
+ * previously-deployed version of an app and the JavaScript or CSS chunk
+ * filenames have since changed: a fresh deployment removes the hashed assets
+ * the open tab still references. Detecting them lets the SDK trigger an
+ * automatic reload so the user gets the new build without manual intervention.
+ *
+ * Recognized shapes (webpack ChunkLoadError, Vite "Failed to fetch
+ * dynamically imported module", Firefox "error loading dynamically imported
+ * module", Safari "Importing a module script failed", and Vite "Unable to
+ * preload CSS").
+ *
+ * @param error - The value to inspect. Anything that is not an Error
+ *   instance returns false.
+ * @returns True if the error matches a known import/chunk-load failure.
+ *
+ * @public
+ */
+export function isImportError(error: unknown): boolean {
+  if (!(error instanceof Error)) return false
+  if (error.name === 'ChunkLoadError') return true
+
+  const message = error.message || ''
+  return (
+    /Loading chunk [\w-]+ failed/i.test(message) ||
+    /Failed to fetch dynamically imported module/i.test(message) ||
+    /error loading dynamically imported module/i.test(message) ||
+    /Import(?:ing)? a module script failed/i.test(message) ||
+    /Unable to preload CSS/i.test(message)
+  )
+}

package/src/utils/object.test.ts

@@ -0,0 +1,95 @@
+import {describe, expect, it} from 'vitest'
+
+import {isDeepEqual, isObject, omitProperty, pickProperties} from './object'
+
+describe('object utils', () => {
+  describe('isObject', () => {
+    it('returns true for objects and false for primitives', () => {
+      expect(isObject({foo: 'bar'})).toBe(true)
+      expect(isObject(null)).toBe(false)
+      expect(isObject('hello')).toBe(false)
+    })
+  })
+
+  describe('omitProperty', () => {
+    it('removes a property from an object copy', () => {
+      expect(omitProperty({foo: 'bar', baz: 1}, 'foo')).toEqual({baz: 1})
+    })
+
+    it('returns an empty object for undefined input', () => {
+      expect(omitProperty<{foo: string}, 'foo'>(undefined, 'foo')).toEqual({})
+    })
+  })
+
+  describe('pickProperties', () => {
+    it('copies only the requested own properties', () => {
+      expect(pickProperties({foo: 'bar', baz: 1}, ['foo'])).toEqual({foo: 'bar'})
+    })
+  })
+
+  describe('isDeepEqual', () => {
+    it('matches nested plain objects and arrays', () => {
+      expect(
+        isDeepEqual({foo: [{bar: 'baz'}], qux: {count: 2}}, {foo: [{bar: 'baz'}], qux: {count: 2}}),
+      ).toBe(true)
+    })
+
+    it('returns false for unequal nested plain objects and arrays', () => {
+      expect(
+        isDeepEqual(
+          {foo: [{bar: 'baz'}], qux: {count: 2}},
+          {foo: [{bar: 'nope'}], qux: {count: 2}},
+        ),
+      ).toBe(false)
+      expect(isDeepEqual([1, {foo: 'bar'}], [1, {foo: 'baz'}])).toBe(false)
+    })
+
+    it('matches sets and maps with equal contents', () => {
+      expect(isDeepEqual(new Set([{foo: 'bar'}, 'baz']), new Set(['baz', {foo: 'bar'}]))).toBe(true)
+
+      expect(
+        isDeepEqual(
+          new Map<string, unknown>([
+            ['foo', {bar: 'baz'}],
+            ['count', 2],
+          ]),
+          new Map<string, unknown>([
+            ['foo', {bar: 'baz'}],
+            ['count', 2],
+          ]),
+        ),
+      ).toBe(true)
+    })
+
+    it('compares dates by timestamp', () => {
+      expect(isDeepEqual(new Date('2024-01-01'), new Date('2024-01-01'))).toBe(true)
+      expect(isDeepEqual(new Date('2024-01-01'), new Date('2024-01-02'))).toBe(false)
+    })
+
+    it('compares regular expressions by source and flags', () => {
+      expect(isDeepEqual(/foo/gi, /foo/gi)).toBe(true)
+      expect(isDeepEqual(/foo/g, /foo/i)).toBe(false)
+      expect(isDeepEqual(/foo/g, /bar/g)).toBe(false)
+    })
+
+    it('returns false for cross-shape mismatches', () => {
+      expect(isDeepEqual({foo: 'bar'}, ['foo', 'bar'] as unknown as {foo: string})).toBe(false)
+      expect(
+        isDeepEqual(
+          new Map<string, unknown>([['foo', 'bar']]) as unknown as object,
+          new Set(['foo', 'bar']) as unknown as object,
+        ),
+      ).toBe(false)
+    })
+
+    it('treats non-plain objects as unequal unless they are the same reference', () => {
+      class Example {
+        constructor(public value: string) {}
+      }
+
+      expect(isDeepEqual(new Example('a'), new Example('a'))).toBe(false)
+      const instance = new Example('a')
+      expect(isDeepEqual(instance, instance)).toBe(true)
+    })
+  })
+})