@sanity/sdk 2.8.0 → 2.9.0

package/src/auth/studioAuth.ts

@@ -9,7 +9,7 @@ import {refreshStampedToken} from './refreshStampedToken'
 import {checkForCookieAuth, getStudioTokenFromLocalStorage} from './studioModeAuth'
 import {subscribeToStateAndFetchCurrentUser} from './subscribeToStateAndFetchCurrentUser'
 import {subscribeToStorageEventsAndSetToken} from './subscribeToStorageEventsAndSetToken'
-import {getDefaultStorage} from './utils'
+import {createLoggedInAuthState, getDefaultStorage} from './utils'
 
 /**
  * Resolves the initial auth state for Studio mode.
@@ -55,7 +55,7 @@ export function getStudioInitialState(options: AuthStrategyOptions): AuthStrateg
 
   if (providedToken) {
     return {
-      authState: {type: AuthStateType.LOGGED_IN, token: providedToken, currentUser: null},
+      authState: createLoggedInAuthState(providedToken, null),
       storageKey: studioStorageKey,
       storageArea,
       authMethod,
@@ -65,7 +65,7 @@ export function getStudioInitialState(options: AuthStrategyOptions): AuthStrateg
 
   if (token) {
     return {
-      authState: {type: AuthStateType.LOGGED_IN, token, currentUser: null},
+      authState: createLoggedInAuthState(token, null),
       storageKey: studioStorageKey,
       storageArea,
       authMethod: 'localstorage',
@@ -115,14 +115,29 @@ export function initializeStudioAuth(
 
 /**
  * Subscribe to a reactive token source from the Studio workspace.
- * The Studio is the single authority for auth — the SDK does not run
- * its own token refresher or cookie auth checks.
+ *
+ * When the token source emits a non-null token, the SDK uses it directly.
+ * When it emits `null`, the behavior depends on the `authenticated` flag
+ * from the Studio's workspace config:
+ *
+ * - `authenticated: true` — the Studio has already verified the user is
+ *   logged in (e.g. via cookie auth). The SDK treats the null token as
+ *   cookie-based auth and stays in the LOGGED_IN state.
+ *
+ * - `authenticated` absent/false — the user is genuinely not authenticated;
+ *   transition to LOGGED_OUT.
+ *
+ * No async cookie probing is needed here because this code path only runs
+ * when a Studio provides SDKStudioContext, and the Studio's Workspace type
+ * always includes `authenticated`. The async `checkForCookieAuth` fallback
+ * remains in `initializeWithFallback` for the non-Studio path.
  */
 function initializeWithTokenSource(
   context: StoreContext<AuthStoreState>,
   tokenSource: TokenSource,
 ): {dispose: () => void; tokenRefresherStarted: boolean} {
   const subscriptions: Subscription[] = []
+  const studioAuthenticated = context.instance.config.studio?.authenticated === true
 
   // Subscribe to the current user fetcher — runs whenever auth state changes
   subscriptions.push(subscribeToStateAndFetchCurrentUser(context, {useProjectHostname: true}))
@@ -132,11 +147,23 @@ function initializeWithTokenSource(
     next: (token) => {
       const {state} = context
       if (token) {
+        // Studio provided a real token — use it directly
         state.set('studioTokenSource', (prev) => ({
           options: {...prev.options, authMethod: undefined},
-          authState: {type: AuthStateType.LOGGED_IN, token, currentUser: null},
+          authState: createLoggedInAuthState(token, null),
+        }))
+      } else if (studioAuthenticated) {
+        // The Studio says the user is authenticated — null token means
+        // cookie-based auth is in use. Stay logged in with cookie method.
+        state.set('studioTokenSourceCookieAuth', (prev) => ({
+          options: {...prev.options, authMethod: 'cookie'},
+          authState:
+            prev.authState.type === AuthStateType.LOGGED_IN
+              ? prev.authState
+              : createLoggedInAuthState('', null),
         }))
       } else {
+        // No token and Studio doesn't confirm authentication — logged out
         state.set('studioTokenSourceLoggedOut', (prev) => ({
           options: {...prev.options, authMethod: undefined},
           authState: {type: AuthStateType.LOGGED_OUT, isDestroyingSession: false},
@@ -193,7 +220,7 @@ function initializeWithFallback(
           authState:
             prev.authState.type === AuthStateType.LOGGED_IN
               ? prev.authState
-              : {type: AuthStateType.LOGGED_IN, token: '', currentUser: null},
+              : createLoggedInAuthState('', null),
         }))
       })
     }

package/src/auth/studioModeAuth.ts

@@ -1,5 +1,6 @@
 import {type ClientConfig, type SanityClient} from '@sanity/client'
 
+import {REQUEST_TAG_PREFIX} from './authConstants'
 import {getTokenFromStorage} from './utils'
 
 /**
@@ -25,7 +26,7 @@ export async function checkForCookieAuth(
     const client = clientFactory({
       projectId,
       useCdn: false,
-      requestTagPrefix: 'sdk',
+      requestTagPrefix: REQUEST_TAG_PREFIX,
       timeout: COOKIE_AUTH_TIMEOUT_MS,
     })
     const user = await client.request({

package/src/auth/subscribeToStateAndFetchCurrentUser.test.ts

@@ -40,7 +40,11 @@ describe('subscribeToStateAndFetchCurrentUser', () => {
       useProjectHostname: false,
       useCdn: false,
     })
-    expect(mockRequest).toHaveBeenCalledWith({method: 'GET', uri: '/users/me'})
+    expect(mockRequest).toHaveBeenCalledWith({
+      method: 'GET',
+      uri: '/users/me',
+      tag: 'users.get-current',
+    })
 
     subscription.unsubscribe()
   })
@@ -76,7 +80,11 @@ describe('subscribeToStateAndFetchCurrentUser', () => {
       useProjectHostname: false,
       useCdn: false,
     })
-    expect(mockRequest).toHaveBeenCalledWith({method: 'GET', uri: '/users/me'})
+    expect(mockRequest).toHaveBeenCalledWith({
+      method: 'GET',
+      uri: '/users/me',
+      tag: 'users.get-current',
+    })
 
     subscription.unsubscribe()
   })

package/src/auth/subscribeToStateAndFetchCurrentUser.ts

@@ -60,7 +60,11 @@ export const subscribeToStateAndFetchCurrentUser = (
         }),
       ),
       switchMap((client) =>
-        client.observable.request<CurrentUser>({uri: '/users/me', method: 'GET'}),
+        client.observable.request<CurrentUser>({
+          uri: '/users/me',
+          method: 'GET',
+          tag: 'users.get-current',
+        }),
       ),
     )
 

package/src/auth/subscribeToStorageEventsAndSetToken.ts

@@ -3,7 +3,7 @@ import {defer, distinctUntilChanged, filter, map, type Subscription} from 'rxjs'
 import {type StoreContext} from '../store/defineStore'
 import {AuthStateType} from './authStateType'
 import {type AuthStoreState} from './authStore'
-import {getStorageEvents, getTokenFromStorage} from './utils'
+import {createLoggedInAuthState, getStorageEvents, getTokenFromStorage} from './utils'
 
 export const subscribeToStorageEventsAndSetToken = ({
   state,
@@ -22,7 +22,7 @@ export const subscribeToStorageEventsAndSetToken = ({
   return tokenFromStorage$.subscribe((token) => {
     state.set('updateTokenFromStorageEvent', {
       authState: token
-        ? {type: AuthStateType.LOGGED_IN, token, currentUser: null}
+        ? createLoggedInAuthState(token, null)
         : {type: AuthStateType.LOGGED_OUT, isDestroyingSession: false},
     })
   })

package/src/auth/utils.ts

@@ -1,7 +1,40 @@
 import {type ClientError} from '@sanity/client'
+import {type CurrentUser} from '@sanity/types'
 import {EMPTY, fromEvent, Observable} from 'rxjs'
 
 import {AUTH_CODE_PARAM, DEFAULT_BASE} from './authConstants'
+import {AuthStateType} from './authStateType'
+import {type LoggedInAuthState} from './authStore'
+
+/**
+ * Creates a properly initialized {@link LoggedInAuthState}.
+ *
+ * For stamped tokens (containing `"-st"`), `lastTokenRefresh` is set to
+ * `Date.now()` so that the visibility-change handler in
+ * {@link refreshStampedToken} does not trigger an unnecessary refresh the
+ * first time the tab becomes visible.
+ *
+ * @param token - The auth token.
+ * @param currentUser - The current user, or `null` if not yet fetched.
+ * @param existingLastTokenRefresh - An existing timestamp to preserve
+ *   (e.g. when updating a token while keeping the previous refresh time).
+ * @internal
+ */
+export function createLoggedInAuthState(
+  token: string,
+  currentUser: CurrentUser | null,
+  existingLastTokenRefresh?: number,
+): LoggedInAuthState {
+  const isStampedToken = token.includes('-st')
+  const lastTokenRefresh = existingLastTokenRefresh ?? (isStampedToken ? Date.now() : undefined)
+
+  return {
+    type: AuthStateType.LOGGED_IN,
+    token,
+    currentUser,
+    ...(lastTokenRefresh !== undefined && {lastTokenRefresh}),
+  }
+}
 
 export function getAuthCode(callbackUrl: string | undefined, locationHref: string): string | null {
   const loc = new URL(locationHref, DEFAULT_BASE)

package/src/client/clientStore.test.ts

@@ -68,6 +68,20 @@ describe('clientStore', () => {
       })
     })
 
+    it('should pass staging apiHost when __SANITY_STAGING__ is true and no explicit apiHost', () => {
+      vi.stubGlobal('__SANITY_STAGING__', true)
+
+      getClient(instance, {apiVersion: '2024-11-12'})
+
+      expect(vi.mocked(createClient)).toHaveBeenCalledWith(
+        expect.objectContaining({
+          apiHost: 'https://api.sanity.work',
+        }),
+      )
+
+      vi.unstubAllGlobals()
+    })
+
     it('should throw when using disallowed configuration keys', () => {
       expect(() =>
         getClient(instance, {

package/src/client/clientStore.ts

@@ -11,6 +11,7 @@ import {
 import {bindActionGlobally} from '../store/createActionBinder'
 import {createStateSourceAction} from '../store/createStateSourceAction'
 import {defineStore, type StoreContext} from '../store/defineStore'
+import {getStagingApiHost} from '../utils/getStagingApiHost'
 
 const DEFAULT_API_VERSION = '2024-11-12'
 const DEFAULT_REQUEST_TAG_PREFIX = 'sanity.sdk'
@@ -195,7 +196,7 @@ export const getClient = bindActionGlobally(
 
     const projectId = options.projectId ?? instance.config.projectId
     const dataset = options.dataset ?? instance.config.dataset
-    const apiHost = options.apiHost ?? instance.config.auth?.apiHost
+    const apiHost = options.apiHost ?? instance.config.auth?.apiHost ?? getStagingApiHost()
 
     const effectiveOptions: ClientOptions = {
       ...DEFAULT_CLIENT_CONFIG,

package/src/comlink/node/getNodeState.ts

@@ -3,6 +3,7 @@ import {createSelector} from 'reselect'
 
 import {bindActionGlobally} from '../../store/createActionBinder'
 import {createStateSourceAction, type SelectorContext} from '../../store/createStateSourceAction'
+import {setCleanupTimeout} from '../../utils/setCleanupTimeout'
 import {type FrameMessage, type WindowMessage} from '../types'
 import {
   type ComlinkNodeState,
@@ -57,7 +58,7 @@ export const getNodeState = bindActionGlobally(
       subs.add(subscriberId)
 
       return () => {
-        setTimeout(() => {
+        setCleanupTimeout(() => {
           const activeSubs = state.get().subscriptions.get(nodeName)
           if (activeSubs) {
             activeSubs.delete(subscriberId)

package/src/config/sanityConfig.ts

@@ -23,6 +23,12 @@ export interface TokenSource {
  * @public
  */
 export interface StudioConfig {
+  /**
+   * Whether the Studio has already determined the user is authenticated.
+   * When `true` and the token source emits `null`, the SDK infers
+   * cookie-based auth is in use rather than transitioning to logged-out.
+   */
+  authenticated?: boolean
   /** Reactive auth token source from the Studio's auth store. */
   auth?: {
     /**

package/src/document/actions.ts

@@ -4,7 +4,7 @@ import {type PatchMutation, type PatchOperations} from '@sanity/types'
 import {type SanityDocument} from 'groq'
 
 import {type DocumentHandle, type DocumentTypeHandle} from '../config/sanityConfig'
-import {getPublishedId} from '../utils/ids'
+import {getEffectiveDocumentId} from './util'
 
 const isSanityMutatePatch = (value: unknown): value is SanityMutatePatchMutation => {
   if (typeof value !== 'object' || !value) return false
@@ -140,12 +140,15 @@ export function createDocument<
     >
   >,
 ): CreateDocumentAction<TDocumentType, TDataset, TProjectId> {
+  // users may pass in an explicit documentId -- make sure we format it correctly for the action
+  let effectiveDocumentId
+  if (typeof doc.documentId === 'string') {
+    effectiveDocumentId = getEffectiveDocumentId({...doc, documentId: doc.documentId})
+  }
   return {
     type: 'document.create',
     ...doc,
-    ...(doc.documentId && {
-      documentId: doc.liveEdit ? doc.documentId : getPublishedId(doc.documentId),
-    }),
+    ...(effectiveDocumentId && {documentId: effectiveDocumentId}),
     ...(initialValue && {initialValue}),
   }
 }
@@ -163,10 +166,11 @@ export function deleteDocument<
 >(
   doc: DocumentHandle<TDocumentType, TDataset, TProjectId>,
 ): DeleteDocumentAction<TDocumentType, TDataset, TProjectId> {
+  const effectiveDocumentId = getEffectiveDocumentId(doc)
   return {
     type: 'document.delete',
     ...doc,
-    documentId: doc.liveEdit ? doc.documentId : getPublishedId(doc.documentId),
+    documentId: effectiveDocumentId,
   }
 }
 
@@ -230,14 +234,14 @@ export function editDocument<
   doc: DocumentHandle<TDocumentType, TDataset, TProjectId>,
   patches?: PatchOperations | PatchOperations[] | SanityMutatePatchMutation,
 ): EditDocumentAction<TDocumentType, TDataset, TProjectId> {
-  const documentId = doc.liveEdit ? doc.documentId : getPublishedId(doc.documentId)
+  const effectiveDocumentId = getEffectiveDocumentId(doc)
 
   if (isSanityMutatePatch(patches)) {
     const converted = convertSanityMutatePatch(patches) ?? []
     return {
       ...doc,
       type: 'document.edit',
-      documentId,
+      documentId: effectiveDocumentId,
       patches: converted,
     }
   }
@@ -245,7 +249,7 @@ export function editDocument<
   return {
     ...doc,
     type: 'document.edit',
-    documentId,
+    documentId: effectiveDocumentId,
     ...(patches && {patches: Array.isArray(patches) ? patches : [patches]}),
   }
 }
@@ -263,10 +267,11 @@ export function publishDocument<
 >(
   doc: DocumentHandle<TDocumentType, TDataset, TProjectId>,
 ): PublishDocumentAction<TDocumentType, TDataset, TProjectId> {
+  const effectiveDocumentId = getEffectiveDocumentId(doc)
   return {
     type: 'document.publish',
     ...doc,
-    documentId: doc.liveEdit ? doc.documentId : getPublishedId(doc.documentId),
+    documentId: effectiveDocumentId,
   }
 }
 
@@ -283,10 +288,11 @@ export function unpublishDocument<
 >(
   doc: DocumentHandle<TDocumentType, TDataset, TProjectId>,
 ): UnpublishDocumentAction<TDocumentType, TDataset, TProjectId> {
+  const effectiveDocumentId = getEffectiveDocumentId(doc)
   return {
     type: 'document.unpublish',
     ...doc,
-    documentId: doc.liveEdit ? doc.documentId : getPublishedId(doc.documentId),
+    documentId: effectiveDocumentId,
   }
 }
 
@@ -303,9 +309,10 @@ export function discardDocument<
 >(
   doc: DocumentHandle<TDocumentType, TDataset, TProjectId>,
 ): DiscardDocumentAction<TDocumentType, TDataset, TProjectId> {
+  const effectiveDocumentId = getEffectiveDocumentId(doc)
   return {
     type: 'document.discard',
     ...doc,
-    documentId: doc.liveEdit ? doc.documentId : getPublishedId(doc.documentId),
+    documentId: effectiveDocumentId,
   }
 }

package/src/document/applyDocumentActions.test.ts

@@ -1,11 +1,9 @@
-// applyDocumentActions.test.ts
 import {type SanityDocument} from '@sanity/types'
 import {Subject} from 'rxjs'
 import {describe, expect, it} from 'vitest'
 
-import {bindActionByDataset} from '../store/createActionBinder'
+import {bindActionBySource} from '../store/createActionBinder'
 import {createSanityInstance, type SanityInstance} from '../store/createSanityInstance'
-import {} from '../store/createStateSourceAction'
 import {createStoreState, type StoreState} from '../store/createStoreState'
 import {type DocumentAction} from './actions'
 import {type DocumentStoreState} from './documentStore'
@@ -14,7 +12,7 @@ import {type AppliedTransaction, type OutgoingTransaction} from './reducers'
 
 vi.mock('../store/createActionBinder', async (importOriginal) => ({
   ...(await importOriginal<typeof import('../store/createActionBinder')>()),
-  bindActionByDataset: vi.fn(),
+  bindActionBySource: vi.fn(),
 }))
 
 type TestState = Pick<
@@ -48,9 +46,9 @@ describe('applyDocumentActions', () => {
     }
     state = createStoreState(initialState)
     instance = createSanityInstance({projectId: 'p', dataset: 'd'})
-    const key = {name: 'p.d', projectId: 'p', dataset: 'd'}
+    const key = {name: 'p.d', source: {projectId: 'p', dataset: 'd'}}
 
-    vi.mocked(bindActionByDataset).mockImplementation(
+    vi.mocked(bindActionBySource).mockImplementation(
       (_storeDef, action) => (instanceParam: SanityInstance, options) =>
         action({instance: instanceParam, state, key}, options),
     )
@@ -75,6 +73,7 @@ describe('applyDocumentActions', () => {
     const applyPromise = applyDocumentActions(instance, {
       actions: [action],
       transactionId: 'txn-success',
+      source: {projectId: 'p', dataset: 'd'},
     })
 
     const appliedTx: AppliedTransaction = {
@@ -132,6 +131,7 @@ describe('applyDocumentActions', () => {
     const applyPromise = applyDocumentActions(instance, {
       actions: [action],
       transactionId: 'txn-error',
+      source: {projectId: 'p', dataset: 'd'},
     })
 
     const errorEvent: DocumentEvent = {
@@ -165,6 +165,7 @@ describe('applyDocumentActions', () => {
     const applyPromise = applyDocumentActions(childInstance, {
       actions: [action],
       transactionId: 'txn-child-match',
+      source: {projectId: 'p', dataset: 'd'},
     })
 
     // Simulate an applied transaction on the parent's instance

package/src/document/applyDocumentActions.ts

@@ -1,12 +1,13 @@
-import {type SanityClient} from '@sanity/client'
 import {type SanityDocument} from 'groq'
 import {distinctUntilChanged, filter, first, firstValueFrom, map, race} from 'rxjs'
 
-import {bindActionByDataset} from '../store/createActionBinder'
+import {type DocumentSource} from '../config/sanityConfig'
+import {bindActionBySource} from '../store/createActionBinder'
 import {type SanityInstance} from '../store/createSanityInstance'
 import {type StoreContext} from '../store/defineStore'
 import {type DocumentAction} from './actions'
 import {documentStore, type DocumentStoreState} from './documentStore'
+import {type DocumentTransactionSubmissionResult} from './events'
 import {type DocumentSet} from './processMutations'
 import {type AppliedTransaction, type QueuedTransaction, queueTransaction} from './reducers'
 
@@ -19,7 +20,7 @@ export interface ActionsResult<TDocument extends SanityDocument = SanityDocument
   appeared: string[]
   updated: string[]
   disappeared: string[]
-  submitted: () => ReturnType<SanityClient['action']>
+  submitted: () => Promise<DocumentTransactionSubmissionResult>
 }
 
 /** @beta */
@@ -29,6 +30,11 @@ export interface ApplyDocumentActionsOptions {
    */
   actions: DocumentAction[]
 
+  /**
+   * The source to which the documents being acted on belong.
+   */
+  source?: DocumentSource
+
   /**
    * Optionally provide an ID to be used as this transaction ID
    */
@@ -61,7 +67,7 @@ export function applyDocumentActions(
   return boundApplyDocumentActions(...args)
 }
 
-const boundApplyDocumentActions = bindActionByDataset(documentStore, _applyDocumentActions)
+const boundApplyDocumentActions = bindActionBySource(documentStore, _applyDocumentActions)
 
 /** @internal */
 async function _applyDocumentActions(