@sanity/sdk 2.6.0 → 2.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanity/sdk",
-  "version": "2.6.0",
+  "version": "2.7.0",
   "private": false,
   "description": "Sanity SDK",
   "keywords": [
@@ -44,10 +44,11 @@
   "prettier": "@sanity/prettier-config",
   "dependencies": {
     "@sanity/bifur-client": "^0.4.1",
-    "@sanity/client": "^7.12.0",
+    "@sanity/client": "^7.14.1",
     "@sanity/comlink": "^3.0.4",
     "@sanity/diff-match-patch": "^3.2.0",
     "@sanity/diff-patch": "^6.0.0",
+    "@sanity/id-utils": "^1.0.0",
     "@sanity/json-match": "^1.0.5",
     "@sanity/message-protocol": "^0.18.0",
     "@sanity/mutate": "^0.12.4",
@@ -72,10 +73,10 @@
     "vite": "^6.3.4",
     "vitest": "^3.2.4",
     "@repo/config-eslint": "0.0.0",
+    "@repo/config-test": "0.0.1",
     "@repo/package.bundle": "3.82.0",
-    "@repo/tsconfig": "0.0.1",
     "@repo/package.config": "0.0.1",
-    "@repo/config-test": "0.0.1"
+    "@repo/tsconfig": "0.0.1"
   },
   "engines": {
     "node": ">=20.19"

package/src/_exports/index.ts

@@ -24,6 +24,7 @@ export {
   agentTransform,
   agentTranslate,
 } from '../agent/agentActions'
+export {isStudioConfig} from '../auth/authMode'
 export {AuthStateType} from '../auth/authStateType'
 export {
   type AuthState,
@@ -99,6 +100,8 @@ export {
   type ProjectHandle,
   type ReleasePerspective,
   type SanityConfig,
+  type StudioConfig,
+  type TokenSource,
 } from '../config/sanityConfig'
 export {getDatasetsState, resolveDatasets} from '../datasets/datasets'
 export {

package/src/auth/authMode.test.ts

@@ -0,0 +1,56 @@
+import {describe, expect, it} from 'vitest'
+
+import {type SanityConfig} from '../config/sanityConfig'
+import {isStudioConfig, resolveAuthMode} from './authMode'
+
+describe('resolveAuthMode', () => {
+  it('returns "studio" when studio config is provided', () => {
+    const config: SanityConfig = {studio: {}}
+    expect(resolveAuthMode(config, 'https://example.com')).toBe('studio')
+  })
+
+  it('returns "studio" when deprecated studioMode.enabled is true', () => {
+    const config: SanityConfig = {studioMode: {enabled: true}}
+    expect(resolveAuthMode(config, 'https://example.com')).toBe('studio')
+  })
+
+  it('returns "dashboard" when _context URL param has a non-empty JSON object', () => {
+    const context = encodeURIComponent(JSON.stringify({orgId: '123'}))
+    const href = `https://example.com?_context=${context}`
+    expect(resolveAuthMode({}, href)).toBe('dashboard')
+  })
+
+  it('returns "standalone" by default', () => {
+    expect(resolveAuthMode({}, 'https://example.com')).toBe('standalone')
+  })
+
+  it('prefers studio config over studioMode', () => {
+    const config: SanityConfig = {
+      studio: {},
+      studioMode: {enabled: true},
+    }
+    expect(resolveAuthMode(config, 'https://example.com')).toBe('studio')
+  })
+})
+
+describe('isStudioConfig', () => {
+  it('returns true when studio config is provided', () => {
+    expect(isStudioConfig({studio: {}})).toBe(true)
+  })
+
+  it('returns true when deprecated studioMode.enabled is true', () => {
+    expect(isStudioConfig({studioMode: {enabled: true}})).toBe(true)
+  })
+
+  it('returns false when studioMode.enabled is false', () => {
+    expect(isStudioConfig({studioMode: {enabled: false}})).toBe(false)
+  })
+
+  it('returns false for empty config', () => {
+    expect(isStudioConfig({})).toBe(false)
+  })
+
+  it('returns true when both studio and studioMode are present', () => {
+    expect(isStudioConfig({studio: {}, studioMode: {enabled: true}})).toBe(true)
+  })
+})

package/src/auth/authMode.ts

@@ -0,0 +1,71 @@
+import {type SanityConfig} from '../config/sanityConfig'
+import {DEFAULT_BASE} from './authConstants'
+
+/**
+ * The runtime auth mode determines which authentication strategy the SDK uses.
+ *
+ * - `studio`     — Running inside Sanity Studio. Token is discovered from
+ *                  Studio's localStorage entry or via cookie auth.
+ * - `dashboard`  — Running inside the Sanity Dashboard iframe. Token is
+ *                  provided by the parent frame via Comlink.
+ * - `standalone` — Running as an independent app. Token comes from
+ *                  localStorage or the OAuth login flow.
+ *
+ * @internal
+ */
+type AuthMode = 'studio' | 'dashboard' | 'standalone'
+
+/**
+ * Determines the auth mode from instance config and environment.
+ *
+ * Priority:
+ * 1. `studio` config provided → `'studio'`
+ * 2. `studioMode.enabled` in config (deprecated) → `'studio'`
+ * 3. Dashboard context detected (`_context` URL param with content) → `'dashboard'`
+ * 4. Otherwise → `'standalone'`
+ *
+ * @internal
+ */
+export function resolveAuthMode(config: SanityConfig, locationHref: string): AuthMode {
+  if (isStudioConfig(config)) return 'studio'
+  if (detectDashboardContext(locationHref)) return 'dashboard'
+  return 'standalone'
+}
+
+/**
+ * Returns `true` when the config indicates the SDK is running inside a Studio.
+ * Checks the new `studio` field first, then falls back to the deprecated
+ * `studioMode.enabled` for backwards compatibility.
+ *
+ * @internal
+ */
+export function isStudioConfig(config: SanityConfig): boolean {
+  return !!config.studio || !!config.studioMode?.enabled
+}
+
+/**
+ * Checks whether the given location href contains a `_context` URL parameter
+ * with a non-empty JSON object, indicating the SDK is running inside the
+ * Sanity Dashboard.
+ *
+ * @internal
+ */
+function detectDashboardContext(locationHref: string): boolean {
+  try {
+    const parsedUrl = new URL(locationHref, DEFAULT_BASE)
+    const contextParam = parsedUrl.searchParams.get('_context')
+    if (!contextParam) return false
+
+    const parsed: unknown = JSON.parse(contextParam)
+    return (
+      typeof parsed === 'object' &&
+      parsed !== null &&
+      !Array.isArray(parsed) &&
+      Object.keys(parsed as Record<string, unknown>).length > 0
+    )
+  } catch (err) {
+    // eslint-disable-next-line no-console
+    console.error('Failed to parse dashboard context from initial location:', err)
+    return false
+  }
+}

package/src/auth/authStore.test.ts

@@ -153,6 +153,34 @@ describe('authStore', () => {
       errorSpy.mockRestore()
     })
 
+    it('rejects array _context and falls back to standalone mode', () => {
+      const initialLocationHref = `https://example.com/?_context=${encodeURIComponent(JSON.stringify(['a', 'b']))}`
+      instance = createSanityInstance({
+        projectId: 'p',
+        dataset: 'd',
+        auth: {initialLocationHref},
+      })
+
+      const {dashboardContext, authState} = authStore.getInitialState(instance, null)
+      // Array should not be treated as dashboard context — falls through to standalone
+      expect(dashboardContext).toStrictEqual({})
+      expect(authState.type).toBe(AuthStateType.LOGGED_OUT)
+    })
+
+    it('rejects empty object _context and falls back to standalone mode', () => {
+      const initialLocationHref = `https://example.com/?_context=${encodeURIComponent(JSON.stringify({}))}`
+      instance = createSanityInstance({
+        projectId: 'p',
+        dataset: 'd',
+        auth: {initialLocationHref},
+      })
+
+      const {dashboardContext, authState} = authStore.getInitialState(instance, null)
+      // Empty object not treated as dashboard — falls through to standalone
+      expect(dashboardContext).toStrictEqual({})
+      expect(authState.type).toBe(AuthStateType.LOGGED_OUT)
+    })
+
     it('sets to logged in if provided token is present (even in dashboard)', () => {
       const token = 'provided-token'
       const context = {mode: 'dashboard'}
@@ -234,7 +262,7 @@ describe('authStore', () => {
       expect(dashboardContext).toStrictEqual({})
     })
 
-    it('sets to logged in using studio token when studio mode is enabled and token exists', () => {
+    it('sets to logged in using studio token when studio config is provided and token exists', () => {
       const studioToken = 'studio-token'
       const projectId = 'studio-project'
       const studioStorageKey = `__studio_auth_token_${projectId}`
@@ -248,7 +276,7 @@ describe('authStore', () => {
       instance = createSanityInstance({
         projectId,
         dataset: 'd',
-        studioMode: {enabled: true},
+        studio: {},
         auth: {storageArea: mockStorage}, // Provide mock storage
       })
 
@@ -258,7 +286,7 @@ describe('authStore', () => {
       expect(options.authMethod).toBe('localstorage')
     })
 
-    it('checks for cookie auth during initialize when studio mode is enabled and no studio token exists', () => {
+    it('checks for cookie auth during initialize when studio config is provided and no studio token exists', () => {
       const projectId = 'studio-project'
       const studioStorageKey = `__studio_auth_token_${projectId}`
       const mockStorage = {
@@ -272,7 +300,7 @@ describe('authStore', () => {
       instance = createSanityInstance({
         projectId,
         dataset: 'd',
-        studioMode: {enabled: true},
+        studio: {},
         auth: {storageArea: mockStorage},
       })
 
@@ -287,6 +315,59 @@ describe('authStore', () => {
       expect(checkForCookieAuth).toHaveBeenCalledWith(projectId, expect.any(Function))
     })
 
+    it('starts in LOGGING_IN state when studio config with tokenSource is provided', () => {
+      const mockTokenSource = {
+        subscribe: vi.fn(() => ({unsubscribe: vi.fn()})),
+      }
+
+      instance = createSanityInstance({
+        projectId: 'studio-project',
+        dataset: 'production',
+        studio: {
+          auth: {token: mockTokenSource},
+        },
+      })
+
+      const {authState} = authStore.getInitialState(instance, null)
+      expect(authState.type).toBe(AuthStateType.LOGGING_IN)
+      // Should not try localStorage or cookie auth
+      expect(getStudioTokenFromLocalStorage).not.toHaveBeenCalled()
+    })
+
+    it('resolves to studio mode when studio config is provided (without studioMode flag)', () => {
+      instance = createSanityInstance({
+        projectId: 'studio-project',
+        dataset: 'production',
+        studio: {},
+      })
+
+      const {authState} = authStore.getInitialState(instance, null)
+      // Without tokenSource, falls back to localStorage discovery like studioMode
+      expect(authState.type).toBe(AuthStateType.LOGGED_OUT)
+      expect(getStudioTokenFromLocalStorage).toHaveBeenCalled()
+    })
+
+    it('subscribes to tokenSource during initialize when studio config is provided', () => {
+      const mockUnsubscribe = vi.fn()
+      const mockSubscribe = vi.fn(() => ({unsubscribe: mockUnsubscribe}))
+      const mockTokenSource = {subscribe: mockSubscribe}
+
+      instance = createSanityInstance({
+        projectId: 'studio-project',
+        dataset: 'production',
+        studio: {
+          auth: {token: mockTokenSource},
+        },
+      })
+
+      // Trigger store creation + initialize
+      getAuthState(instance)
+
+      expect(mockSubscribe).toHaveBeenCalledWith({next: expect.any(Function)})
+      // Should NOT start cookie auth or storage event subscriptions
+      expect(checkForCookieAuth).not.toHaveBeenCalled()
+    })
+
     it('falls back to default auth (storage token) when studio mode is disabled', () => {
       const storageToken = 'regular-storage-token'
       vi.mocked(getTokenFromStorage).mockReturnValue(storageToken)

package/src/auth/authStore.ts

@@ -1,24 +1,21 @@
 import {type ClientConfig, createClient, type SanityClient} from '@sanity/client'
 import {type CurrentUser} from '@sanity/types'
-import {type Subscription} from 'rxjs'
 
 import {type AuthConfig, type AuthProvider} from '../config/authConfig'
 import {bindActionGlobally} from '../store/createActionBinder'
 import {createStateSourceAction} from '../store/createStateSourceAction'
 import {defineStore} from '../store/defineStore'
+import {resolveAuthMode} from './authMode'
 import {AuthStateType} from './authStateType'
-import {refreshStampedToken} from './refreshStampedToken'
-import {checkForCookieAuth, getStudioTokenFromLocalStorage} from './studioModeAuth'
-import {subscribeToStateAndFetchCurrentUser} from './subscribeToStateAndFetchCurrentUser'
-import {subscribeToStorageEventsAndSetToken} from './subscribeToStorageEventsAndSetToken'
-import {
-  getAuthCode,
-  getCleanedUrl,
-  getDefaultLocation,
-  getDefaultStorage,
-  getTokenFromLocation,
-  getTokenFromStorage,
-} from './utils'
+import {type AuthStrategyOptions} from './authStrategy'
+import {getDashboardInitialState, initializeDashboardAuth} from './dashboardAuth'
+import {getStandaloneInitialState, initializeStandaloneAuth} from './standaloneAuth'
+import {getStudioInitialState, initializeStudioAuth} from './studioAuth'
+import {getCleanedUrl, getDefaultLocation} from './utils'
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
 
 /**
  * Represents the various states the authentication can be in.
@@ -96,8 +93,13 @@ export interface AuthStoreState {
   dashboardContext?: DashboardContext
 }
 
+// ---------------------------------------------------------------------------
+// Store definition — thin orchestrator
+// ---------------------------------------------------------------------------
+
 export const authStore = defineStore<AuthStoreState>({
   name: 'Auth',
+
   getInitialState(instance) {
     const {
       apiHost,
@@ -107,12 +109,11 @@ export const authStore = defineStore<AuthStoreState>({
       clientFactory = createClient,
       initialLocationHref = getDefaultLocation(),
     } = instance.config.auth ?? {}
-    let storageArea = instance.config.auth?.storageArea
 
-    let storageKey = `__sanity_auth_token`
-    const studioModeEnabled = instance.config.studioMode?.enabled
+    const authConfig = instance.config.auth ?? {}
 
-    // This login URL will only be used for local development
+    // Build login URL (used by standalone mode, but always computed for the
+    // public `getLoginUrlState` accessor)
     let loginDomain = 'https://www.sanity.io'
     try {
       if (apiHost && new URL(apiHost).hostname.endsWith('.sanity.work')) {
@@ -126,80 +127,33 @@ export const authStore = defineStore<AuthStoreState>({
     loginUrl.searchParams.set('type', 'stampedToken') // Token must be stamped to have an sid passed back
     loginUrl.searchParams.set('withSid', 'true')
 
-    // Check if running in dashboard context by parsing initialLocationHref
-    let dashboardContext: DashboardContext = {}
-    let isInDashboard = false
-    try {
-      const parsedUrl = new URL(initialLocationHref)
-      const contextParam = parsedUrl.searchParams.get('_context')
-      if (contextParam) {
-        const parsedContext = JSON.parse(contextParam)
-
-        // Consider it in dashboard if context is present and an object
-        if (
-          parsedContext &&
-          typeof parsedContext === 'object' &&
-          Object.keys(parsedContext).length > 0
-        ) {
-          // Explicitly remove the 'sid' property from the parsed object *before* assigning
-          delete parsedContext.sid
-
-          // Now assign the potentially modified object to dashboardContext
-          dashboardContext = parsedContext
-          isInDashboard = true
-        }
-      }
-    } catch (err) {
-      // eslint-disable-next-line no-console
-      console.error('Failed to parse dashboard context from initial location:', err)
-    }
-
-    if (!isInDashboard || studioModeEnabled) {
-      // If not in dashboard, use the storage area from the config
-      // If studio mode is enabled, use the local storage area (default)
-      storageArea = storageArea ?? getDefaultStorage()
-    }
+    // Resolve auth mode and delegate to the appropriate strategy
+    const mode = resolveAuthMode(instance.config, initialLocationHref)
 
-    let token: string | null
-    let authMethod: AuthMethodOptions
-    if (studioModeEnabled) {
-      // In studio mode, always use the studio-specific storage key and subscribe to it
-      const studioStorageKey = `__studio_auth_token_${instance.config.projectId ?? ''}`
-      storageKey = studioStorageKey
-      token = getStudioTokenFromLocalStorage(storageArea, studioStorageKey)
-      if (token) {
-        authMethod = 'localstorage'
-      }
-    } else {
-      token = getTokenFromStorage(storageArea, storageKey)
-      if (token) {
-        authMethod = 'localstorage'
-      }
+    const strategyOptions: AuthStrategyOptions = {
+      authConfig,
+      projectId: instance.config.projectId,
+      initialLocationHref,
+      clientFactory,
+      tokenSource: instance.config.studio?.auth?.token,
     }
 
-    let authState: AuthState
-    if (providedToken) {
-      authState = {type: AuthStateType.LOGGED_IN, token: providedToken, currentUser: null}
-    } else if (token && studioModeEnabled) {
-      authState = {type: AuthStateType.LOGGED_IN, token: token ?? '', currentUser: null}
-    } else if (
-      getAuthCode(callbackUrl, initialLocationHref) ||
-      getTokenFromLocation(initialLocationHref)
-    ) {
-      authState = {type: AuthStateType.LOGGING_IN, isExchangingToken: false}
-      // Note: dashboardContext from the callback URL can be set later in handleAuthCallback too
-    } else if (token && !isInDashboard && !studioModeEnabled) {
-      // Only use token from storage if NOT running in dashboard and studio mode is not enabled
-      authState = {type: AuthStateType.LOGGED_IN, token, currentUser: null}
-    } else {
-      // Default to logged out if no provided token, not handling callback,
-      // or if token exists but we ARE in dashboard mode.
-      authState = {type: AuthStateType.LOGGED_OUT, isDestroyingSession: false}
+    let result
+    switch (mode) {
+      case 'studio':
+        result = getStudioInitialState(strategyOptions)
+        break
+      case 'dashboard':
+        result = getDashboardInitialState(strategyOptions)
+        break
+      case 'standalone':
+        result = getStandaloneInitialState(strategyOptions)
+        break
     }
 
     return {
-      authState,
-      dashboardContext,
+      authState: result.authState,
+      dashboardContext: result.dashboardContext,
       options: {
         apiHost,
         loginUrl: loginUrl.toString(),
@@ -208,59 +162,43 @@ export const authStore = defineStore<AuthStoreState>({
         providedToken,
         clientFactory,
         initialLocationHref,
-        storageKey,
-        storageArea,
-        authMethod,
+        storageKey: result.storageKey,
+        storageArea: result.storageArea,
+        authMethod: result.authMethod,
       },
     }
   },
+
   initialize(context) {
-    const subscriptions: Subscription[] = []
-    subscriptions.push(subscribeToStateAndFetchCurrentUser(context))
-    const storageArea = context.state.get().options?.storageArea
-    if (storageArea) {
-      subscriptions.push(subscribeToStorageEventsAndSetToken(context))
-    }
+    const initialLocationHref =
+      context.state.get().options?.initialLocationHref ?? getDefaultLocation()
+    const mode = resolveAuthMode(context.instance.config, initialLocationHref)
 
-    // If in Studio mode with no local token, resolve cookie auth asynchronously
-    try {
-      const {instance, state} = context
-      const studioModeEnabled = !!instance.config.studioMode?.enabled
-      const token: string | null =
-        state.get().authState?.type === AuthStateType.LOGGED_IN
-          ? (state.get().authState as LoggedInAuthState).token
-          : null
-      if (studioModeEnabled && !token) {
-        const projectId = instance.config.projectId
-        const clientFactory = state.get().options.clientFactory
-        checkForCookieAuth(projectId, clientFactory).then((isCookieAuthEnabled) => {
-          if (!isCookieAuthEnabled) return
-          state.set('enableCookieAuth', (prev) => ({
-            options: {...prev.options, authMethod: 'cookie'},
-            authState:
-              prev.authState.type === AuthStateType.LOGGED_IN
-                ? prev.authState
-                : {type: AuthStateType.LOGGED_IN, token: '', currentUser: null},
-          }))
-        })
-      }
-    } catch {
-      // best-effort cookie detection
+    let initResult
+    switch (mode) {
+      case 'studio':
+        initResult = initializeStudioAuth(context, tokenRefresherRunning)
+        break
+      case 'dashboard':
+        initResult = initializeDashboardAuth(context, tokenRefresherRunning)
+        break
+      case 'standalone':
+        initResult = initializeStandaloneAuth(context, tokenRefresherRunning)
+        break
     }
 
-    if (!tokenRefresherRunning) {
+    if (initResult.tokenRefresherStarted) {
       tokenRefresherRunning = true
-      subscriptions.push(refreshStampedToken(context))
     }
 
-    return () => {
-      for (const subscription of subscriptions) {
-        subscription.unsubscribe()
-      }
-    }
+    return initResult.dispose
   },
 })
 
+// ---------------------------------------------------------------------------
+// Public bound actions
+// ---------------------------------------------------------------------------
+
 /**
  * @public
  */

package/src/auth/authStrategy.ts

@@ -0,0 +1,39 @@
+import {type ClientConfig, type SanityClient} from '@sanity/client'
+
+import {type AuthConfig} from '../config/authConfig'
+import {type TokenSource} from '../config/sanityConfig'
+import {type AuthMethodOptions, type AuthState, type DashboardContext} from './authStore'
+
+/**
+ * The result returned by each auth strategy's `getInitialState` function.
+ * Provides the auth store with the initial auth state and the options needed
+ * to run the store.
+ *
+ * @internal
+ */
+export interface AuthStrategyResult {
+  authState: AuthState
+  storageKey: string
+  storageArea: Storage | undefined
+  authMethod: AuthMethodOptions
+  dashboardContext: DashboardContext
+}
+
+/**
+ * Shared options that every auth strategy receives.
+ * Extracted from the instance config once and passed through.
+ *
+ * @internal
+ */
+export interface AuthStrategyOptions {
+  authConfig: AuthConfig
+  projectId: string | undefined
+  initialLocationHref: string
+  clientFactory: (config: ClientConfig) => SanityClient
+  /**
+   * Reactive token source from a Studio workspace. When provided, the studio
+   * auth strategy subscribes to it for ongoing token sync instead of
+   * discovering tokens from localStorage or cookies.
+   */
+  tokenSource?: TokenSource
+}