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

package/src/telemetry/telemetryManager.ts

@@ -0,0 +1,199 @@
+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 {type TelemetryEnvironment} from './environment'
+import {SDKError, SDKHookMounted, SDKSessionEnded, SDKSessionStarted} from './events'
+
+const FLUSH_INTERVAL_MS = 30_000
+const CONSENT_TAG = 'telemetry-consent.sdk'
+const BATCH_TAG = 'telemetry.batch'
+
+const log = createLogger('telemetry')
+
+/**
+ * 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
+ */
+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 Session Started" event */
+  logSessionStarted(data: {projectId: string; perspective: string; authMethod: string}): void
+
+  /** Log a "SDK Hook Mounted" event (deduplicated per hook name) */
+  logHookFirstUsed(hookName: string): void
+
+  /** Log a "SDK Error" event */
+  logError(errorType: string, hookName: string): void
+
+  /** Log a "SDK 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
+  environment: TelemetryEnvironment
+}
+
+/**
+ * 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, environment} = 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) => {
+      // 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, environment})
+    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 Session Started', {
+        projectId: data.projectId,
+        perspective: data.perspective,
+        authMethod: data.authMethod,
+        version: CORE_SDK_VERSION,
+        environment,
+      })
+      logger.log(SDKSessionStarted, {
+        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})
+    },
+
+    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 Session Ended', {
+        durationSeconds,
+        hooksUsed: [...emittedHooks],
+        environment,
+      })
+      logger.log(SDKSessionEnded, {
+        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.test.ts

@@ -19,7 +19,9 @@ describe('Users Reducers', () => {
   // Mock SanityInstance for testing
   const mockInstance: SanityInstance = {
     instanceId: 'test-instance-id',
-    config: {},
+    config: {
+      projectId: 'test-project-id',
+    },
     isDisposed: () => false,
     dispose: () => {},
     onDispose: () => () => {},

package/src/users/reducers.ts

@@ -1,17 +1,16 @@
-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'
 
 /** @internal */
 export const getUsersKey = (
-  _instance: SanityInstance,
+  instance: SanityInstance,
   {
     resourceType,
     organizationId,
     batchSize = DEFAULT_USERS_BATCH_SIZE,
-    projectId,
+    projectId = instance.config.projectId,
     userId,
   }: GetUsersOptions = {},
 ): string =>
@@ -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/types.ts

@@ -1,3 +1,5 @@
+import {type ProjectHandle} from '../config/sanityConfig'
+
 /**
  * @public
  */
@@ -40,8 +42,7 @@ export interface UserProfile {
 /**
  * @public
  */
-export interface GetUsersOptions {
-  projectId?: string
+export interface GetUsersOptions extends ProjectHandle {
   resourceType?: 'organization' | 'project'
   batchSize?: number
   organizationId?: string
@@ -87,8 +88,7 @@ export interface ResolveUsersOptions extends GetUsersOptions {
 /**
  * @public
  */
-export interface GetUserOptions {
-  projectId?: string
+export interface GetUserOptions extends ProjectHandle {
   userId: string
   resourceType?: 'organization' | 'project'
   organizationId?: string

package/src/users/usersStore.test.ts

@@ -87,7 +87,7 @@ describe('usersStore', () => {
   })
 
   it('initializes users state and cleans up after unsubscribe', async () => {
-    const instance = createSanityInstance()
+    const instance = createSanityInstance({projectId: 'test', dataset: 'test'})
     const state = getUsersState(instance, {
       resourceType: 'project',
       projectId: 'project1',
@@ -122,7 +122,7 @@ describe('usersStore', () => {
   })
 
   it('maintains state when multiple subscribers exist', async () => {
-    const instance = createSanityInstance()
+    const instance = createSanityInstance({projectId: 'test', dataset: 'test'})
     const state = getUsersState(instance, {
       resourceType: 'project',
       projectId: 'project1',
@@ -165,7 +165,7 @@ describe('usersStore', () => {
   })
 
   it('resolveUsers works without affecting subscriber cleanup', async () => {
-    const instance = createSanityInstance()
+    const instance = createSanityInstance({projectId: 'test', dataset: 'test'})
     const options: GetUsersOptions = {resourceType: 'project', projectId: 'project1'}
 
     const state = getUsersState(instance, options)
@@ -198,7 +198,7 @@ describe('usersStore', () => {
   })
 
   it('handles abort signal in resolveUsers', async () => {
-    const instance = createSanityInstance()
+    const instance = createSanityInstance({projectId: 'test', dataset: 'test'})
     const options: GetUsersOptions = {resourceType: 'project', projectId: 'project1'}
     const abortController = new AbortController()
 
@@ -221,7 +221,7 @@ describe('usersStore', () => {
   })
 
   it('loads more users when loadMoreUsers is called', async () => {
-    const instance = createSanityInstance()
+    const instance = createSanityInstance({projectId: 'test', dataset: 'test'})
     const options: GetUsersOptions = {resourceType: 'project', projectId: 'project1'}
 
     // First response has nextCursor
@@ -291,7 +291,7 @@ describe('usersStore', () => {
   })
 
   it('throws error when loadMoreUsers is called without initial data', async () => {
-    const instance = createSanityInstance()
+    const instance = createSanityInstance({projectId: 'test', dataset: 'test'})
 
     // Expect loadMoreUsers to throw when no data is loaded
     await expect(
@@ -302,7 +302,7 @@ describe('usersStore', () => {
   })
 
   it('throws error when loadMoreUsers is called with no more data available', async () => {
-    const instance = createSanityInstance()
+    const instance = createSanityInstance({projectId: 'test', dataset: 'test'})
     const options: GetUsersOptions = {resourceType: 'project', projectId: 'project1'}
 
     // Response with no nextCursor
@@ -325,7 +325,7 @@ describe('usersStore', () => {
   })
 
   it('handles errors in users fetching', async () => {
-    const instance = createSanityInstance()
+    const instance = createSanityInstance({projectId: 'test', dataset: 'test'})
     const errorMessage = 'Failed to fetch users'
 
     // Override request to simulate error
@@ -351,7 +351,7 @@ describe('usersStore', () => {
   })
 
   it('delays users state removal after unsubscribe', async () => {
-    const instance = createSanityInstance()
+    const instance = createSanityInstance({projectId: 'test', dataset: 'test'})
     const options: GetUsersOptions = {resourceType: 'project', projectId: 'project1'}
     const state = getUsersState(instance, options)
     const unsubscribe = state.subscribe()
@@ -370,7 +370,7 @@ describe('usersStore', () => {
   })
 
   it('preserves users state if a new subscriber subscribes before cleanup delay', async () => {
-    const instance = createSanityInstance()
+    const instance = createSanityInstance({projectId: 'test', dataset: 'test'})
     const state = getUsersState(instance, {
       resourceType: 'project',
       projectId: 'project1',
@@ -412,7 +412,7 @@ describe('usersStore', () => {
     })
 
     it('fetches a single user with a project-scoped ID', async () => {
-      const instance = createSanityInstance()
+      const instance = createSanityInstance({projectId: 'test', dataset: 'test'})
       const projectUserId = 'p12345'
       const mockProjectUser: PatchedSanityUserFromClient = {
         id: projectUserId,
@@ -451,6 +451,7 @@ describe('usersStore', () => {
       expect(specificRequest).toHaveBeenCalledWith({
         method: 'GET',
         uri: `/users/${projectUserId}`,
+        tag: 'users.get',
       })
 
       const expectedUser: SanityUser = {
@@ -476,7 +477,10 @@ describe('usersStore', () => {
     })
 
     it('fetches a single user with a global-scoped ID', async () => {
-      const instance = createSanityInstance()
+      const instance = createSanityInstance({
+        projectId: 'test',
+        dataset: 'test',
+      })
       const globalUserId = 'g12345'
       const mockGlobalUser: SanityUser = {
         sanityUserId: globalUserId,

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/buildQuery.test.ts

@@ -0,0 +1,14 @@
+import {describe, expect, it} from 'vitest'
+
+import {buildQuery} from './buildQuery'
+
+describe('buildQuery', () => {
+  it('stringifies scalars, drops undefined, and passes string arrays through', () => {
+    expect(buildQuery({a: true, b: 0, c: 'x', d: undefined, e: ['p', 'q']})).toEqual({
+      a: 'true',
+      b: '0',
+      c: 'x',
+      e: ['p', 'q'],
+    })
+  })
+})

package/src/utils/buildQuery.ts

@@ -0,0 +1,17 @@
+/**
+ * Serialises store options into a `@sanity/client` request query object.
+ * Scalars are stringified and `undefined` values dropped; string arrays pass
+ * through untouched so the client serialises them as repeated keys
+ * (`permissions=a&permissions=b`).
+ *
+ * @internal
+ */
+export function buildQuery(
+  params: Record<string, string | number | boolean | string[] | undefined>,
+): Record<string, string | string[]> {
+  return Object.fromEntries(
+    Object.entries(params)
+      .filter(([, value]) => value !== undefined)
+      .map(([key, value]) => [key, Array.isArray(value) ? value : String(value)]),
+  )
+}

package/src/utils/createFetcherStore.test.ts

@@ -9,7 +9,7 @@ describe('createFetcherStore', () => {
   let instance: SanityInstance
 
   beforeEach(() => {
-    instance = createSanityInstance()
+    instance = createSanityInstance({projectId: 'p', dataset: 'd'})
     vi.useRealTimers()
   })
 
@@ -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/includeShape.ts

@@ -0,0 +1,36 @@
+/**
+ * A response field that the API embeds only when its `include` token was
+ * requested. Given the full set of tokens `All`, the token `Key` this field
+ * maps to, and the tokens actually `Requested`, it resolves to:
+ *
+ * - `unknown` (field absent) when nothing — or nothing matching `Key` — was requested
+ * - `Field` (present, as declared) when a literal request list contains `Key`
+ * - `Partial<Field>` (optional) when `Requested` is the wide `All` union, i.e.
+ *   an `include` array whose members aren't known at the type level
+ *
+ * Absent arms return `unknown` so they vanish under intersection. Mirrors the
+ * `boolean extends Flag` trick the organization/project types use, but for an
+ * include-token union rather than a boolean flag.
+ *
+ * @internal
+ */
+export type Included<All extends string, Key extends All, Requested extends All, Field> = [
+  All,
+] extends [Requested]
+  ? Partial<Field>
+  : [Key] extends [Requested]
+    ? Field
+    : unknown
+
+/**
+ * Whether the requested include tokens intersect a given set — used to decide
+ * whether a parent field (e.g. an application's `activeDeployment`) is present,
+ * when requesting any of several tokens forces it in.
+ *
+ * @internal
+ */
+export type IncludesAny<Requested extends string, Set extends string> = [Requested & Set] extends [
+  never,
+]
+  ? false
+  : true