@sanity/sdk 3.0.0-rc.1 → 3.0.0

package/src/document/util.ts

@@ -1,8 +1,44 @@
-import {DocumentId, getPublishedId, getVersionId} from '@sanity/id-utils'
+import {DocumentId, getDraftId, getPublishedId, getVersionId} from '@sanity/id-utils'
 
 import {type DocumentHandle} from '../config/sanityConfig'
 import {isReleasePerspective} from '../releases/utils/isReleasePerspective'
 
+/**
+ * The id of the specific document a user is editing under a given perspective:
+ * the draft, the published document, or a release version.
+ *
+ * Distinct from {@link getEffectiveDocumentId}, which resolves the canonical key a
+ * document's state is stored under and so collapses a draft onto its published id.
+ * This one keeps them apart, because some things compare the exact id. Presence is
+ * the motivating case: the Studio's field indicators match the id its form is on,
+ * exactly, so an app reporting the published id shows up in the Studio at document
+ * level while never lighting up a single field.
+ *
+ * @remarks
+ * Resolved from the handle alone, which is right whenever a draft or version
+ * exists, so for any document actually being edited. The Studio additionally falls
+ * back to whichever document exists, so for a published document nobody has edited
+ * yet its form sits on the published id where this returns the draft id. Matching
+ * that would mean reading document state, which presence deliberately does not
+ * depend on.
+ *
+ * @internal
+ */
+export function getEditingDocumentId(
+  doc: Pick<DocumentHandle, 'documentId' | 'liveEdit' | 'perspective'>,
+): string {
+  if (doc.liveEdit) {
+    return getPublishedId(DocumentId(doc.documentId))
+  }
+  if (isReleasePerspective(doc.perspective)) {
+    return getVersionId(DocumentId(doc.documentId), doc.perspective.releaseName)
+  }
+  if (doc.perspective === 'published') {
+    return getPublishedId(DocumentId(doc.documentId))
+  }
+  return getDraftId(DocumentId(doc.documentId))
+}
+
 export function getEffectiveDocumentId(doc: DocumentHandle): string {
   if (doc.liveEdit) {
     return doc.documentId

package/src/favorites/favorites.test.ts

@@ -1,12 +1,12 @@
 import {type Node} from '@sanity/comlink'
-import {firstValueFrom, of, Subject} from 'rxjs'
+import {of, Subject} from 'rxjs'
 import {describe, expect, it, type Mock, vi} from 'vitest'
 
 import {getNodeState, type NodeState} from '../comlink/node/getNodeState'
 import {type FrameMessage, type WindowMessage} from '../comlink/types'
 import {createSanityInstance, type SanityInstance} from '../store/createSanityInstance'
 import {type StateSource} from '../store/createStateSourceAction'
-import {getFavoritesState, resolveFavoritesState} from './favorites'
+import {favorites, setFavorite} from './favorites'
 
 vi.mock('../comlink/node/getNodeState', () => ({
   getNodeState: vi.fn(),
@@ -62,8 +62,8 @@ describe('favoritesStore', () => {
     it('creates different keys for different contexts with schema name', async () => {
       setupMockStateSource()
       // Make two fetches with different document IDs
-      await resolveFavoritesState(instance!, mockContext)
-      await resolveFavoritesState(instance!, {
+      await favorites.resolveState(instance!, mockContext)
+      await favorites.resolveState(instance!, {
         ...mockContext,
         documentId: 'different',
       })
@@ -79,8 +79,8 @@ describe('favoritesStore', () => {
     it('creates different keys for contexts without schema name', async () => {
       setupMockStateSource()
       // Make two fetches with different document IDs
-      await resolveFavoritesState(instance!, mockContextNoSchema)
-      await resolveFavoritesState(instance!, {
+      await favorites.resolveState(instance!, mockContextNoSchema)
+      await favorites.resolveState(instance!, {
         ...mockContextNoSchema,
         documentId: 'different',
       })
@@ -110,7 +110,7 @@ describe('favoritesStore', () => {
     it('fetches favorite status and handles success', async () => {
       const mockResponse = {isFavorited: true}
       setupMockStateSource({fetchImpl: vi.fn().mockResolvedValue(mockResponse)})
-      const result = await resolveFavoritesState(instance!, mockContext)
+      const result = await favorites.resolveState(instance!, mockContext)
       expect(result).toEqual(mockResponse)
       expect(mockFetch).toHaveBeenCalledWith('dashboard/v1/events/favorite/query', {
         document: {
@@ -128,7 +128,7 @@ describe('favoritesStore', () => {
     it('handles error and returns default response', async () => {
       const consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
       setupMockStateSource({fetchImpl: vi.fn().mockRejectedValue(new Error('Failed to fetch'))})
-      const result = await resolveFavoritesState(instance!, mockContext)
+      const result = await favorites.resolveState(instance!, mockContext)
       expect(result).toEqual({isFavorited: false})
       expect(consoleErrorSpy).toHaveBeenCalledWith(
         'Favorites service connection error',
@@ -137,25 +137,19 @@ describe('favoritesStore', () => {
       consoleErrorSpy.mockRestore()
     })
 
-    it('shares observable between multiple subscribers and cleans up', async () => {
+    it('serves subsequent reads within staleTime from the cache', async () => {
       const mockResponse = {isFavorited: true}
       setupMockStateSource({fetchImpl: vi.fn().mockResolvedValue(mockResponse)})
-      const state = getFavoritesState(instance!, mockContext)
-      // First subscriber
-      const sub1 = state.subscribe()
-      await firstValueFrom(state.observable)
+      const first = await favorites.resolveState(instance!, mockContext)
+      expect(first).toEqual(mockResponse)
       expect(mockFetch).toHaveBeenCalledTimes(1)
-      // Second subscriber should use cached response
-      const state2 = getFavoritesState(instance!, mockContext)
-      const sub2 = state2.subscribe()
-      await firstValueFrom(state2.observable)
+      // Second read is fresh (within staleTime) — no second fetch
+      const second = await favorites.resolveState(instance!, mockContext)
+      expect(second).toEqual(mockResponse)
       expect(mockFetch).toHaveBeenCalledTimes(1)
-      // Cleanup
-      sub1()
-      sub2()
     })
 
-    it('reuses active fetch via createFetcherStore/shareReplay when called again while pending', async () => {
+    it('dedupes against the in-flight fetch when called again while pending', async () => {
       vi.useFakeTimers()
       let resolveFetch: (value: {isFavorited: boolean}) => void
       const fetchPromise = new Promise<{isFavorited: boolean}>((resolve) => {
@@ -175,13 +169,15 @@ describe('favoritesStore', () => {
       } as unknown as StateSource<NodeState>
       vi.mocked(getNodeState).mockReturnValue(mockStateSource)
       // Call 1: Triggers the actual fetch
-      const promise1 = resolveFavoritesState(instance!, mockContext)
+      const promise1 = favorites.resolveState(instance!, mockContext)
+      // Let the deferred fetch start and subscribe to the node state
+      await vi.advanceTimersByTimeAsync(1)
       // Simulate node becoming connected
       subject.next({node: mockNode, status: 'connected'})
       await vi.advanceTimersByTimeAsync(1)
       expect(fetchSpy).toHaveBeenCalledTimes(1)
-      // Call 2: Should reuse the pending fetch via createFetcherStore/shareReplay
-      const promise2 = resolveFavoritesState(instance!, mockContext)
+      // Call 2: Should reuse the pending fetch
+      const promise2 = favorites.resolveState(instance!, mockContext)
       await vi.advanceTimersByTimeAsync(1)
       expect(fetchSpy).toHaveBeenCalledTimes(1)
       // Resolve the underlying fetch
@@ -195,4 +191,48 @@ describe('favoritesStore', () => {
       vi.useRealTimers()
     })
   })
+
+  describe('setFavorite', () => {
+    beforeEach(() => {
+      vi.resetAllMocks()
+      instance = createSanityInstance({projectId: 'p', dataset: 'd'})
+      setupMockStateSource({fetchImpl: vi.fn().mockResolvedValue({success: true})})
+    })
+
+    afterEach(() => {
+      instance?.dispose()
+    })
+
+    it('sends the added event with schemaName and resolves to the new state', async () => {
+      const result = await setFavorite(instance!, {...mockContext, isFavorited: true})
+      expect(result.data).toEqual({isFavorited: true})
+      expect(mockFetch).toHaveBeenCalledWith('dashboard/v1/events/favorite/mutate', {
+        eventType: 'added',
+        document: {
+          id: mockContext.documentId,
+          type: mockContext.documentType,
+          resource: {
+            id: mockContext.resourceId,
+            type: mockContext.resourceType,
+            schemaName: mockContext.schemaName,
+          },
+        },
+      })
+    })
+
+    it('sends the removed event and omits schemaName when absent', async () => {
+      const result = await setFavorite(instance!, {...mockContextNoSchema, isFavorited: false})
+      expect(result.data).toEqual({isFavorited: false})
+      const payload = mockFetch.mock.calls[0][1]
+      expect(payload.eventType).toBe('removed')
+      expect(payload.document.resource).not.toHaveProperty('schemaName')
+    })
+
+    it('rejects when the server reports failure', async () => {
+      setupMockStateSource({fetchImpl: vi.fn().mockResolvedValue({success: false})})
+      await expect(setFavorite(instance!, {...mockContext, isFavorited: true})).rejects.toThrow(
+        'Failed to update favorite status',
+      )
+    })
+  })
 })

package/src/favorites/favorites.ts

@@ -5,12 +5,12 @@ import {
   SDK_NODE_NAME,
   type StudioResource,
 } from '@sanity/message-protocol'
-import {catchError, filter, from, map, Observable, of, shareReplay, switchMap} from 'rxjs'
+import {catchError, first, from, map, type Observable, of, switchMap} from 'rxjs'
 
 import {getNodeState} from '../comlink/node/getNodeState'
 import {type DocumentHandle} from '../config/sanityConfig'
 import {type SanityInstance} from '../store/createSanityInstance'
-import {createFetcherStore} from '../utils/createFetcherStore'
+import {defineFetcher, defineMutation} from '../store/fetcherStore'
 
 /**
  * @public
@@ -22,7 +22,7 @@ export interface FavoriteStatusResponse {
 /**
  * @public
  */
-interface FavoriteDocumentContext extends DocumentHandle {
+export interface FavoriteDocumentContext extends DocumentHandle {
   resourceId: string
   resourceType: StudioResource['type'] | MediaResource['type'] | CanvasResource['type']
   schemaName?: string
@@ -35,12 +35,19 @@ function createFavoriteKey(context: FavoriteDocumentContext): string {
   }`
 }
 
-const favorites = createFetcherStore<[FavoriteDocumentContext], FavoriteStatusResponse>({
-  name: 'Favorites',
-  getKey: (_instance: SanityInstance, context: FavoriteDocumentContext) => {
-    return createFavoriteKey(context)
-  },
-  fetcher: (instance: SanityInstance) => {
+/**
+ * Fetcher for a document's favorite status, read from the dashboard over
+ * comlink, on the shared fetcher cache.
+ *
+ * @internal
+ */
+export const favorites = defineFetcher<[context: FavoriteDocumentContext], FavoriteStatusResponse>({
+  name: 'favorites',
+  getKey: (_instance: SanityInstance, context: FavoriteDocumentContext) =>
+    createFavoriteKey(context),
+  // Tag each entry with its key so `setFavorite` can invalidate exactly it.
+  tags: (_data, context) => [{type: 'favorite', id: createFavoriteKey(context)}],
+  fetch: (instance) => {
     return (context: FavoriteDocumentContext): Observable<FavoriteStatusResponse> => {
       const nodeStateSource = getNodeState(instance, {
         name: SDK_NODE_NAME,
@@ -59,8 +66,8 @@ const favorites = createFetcherStore<[FavoriteDocumentContext], FavoriteStatusRe
       }
 
       return nodeStateSource.observable.pipe(
-        filter((nodeState) => !!nodeState), // Only proceed when connected
-        shareReplay(1),
+        // Wait until connected, then complete after the single fetch settles.
+        first((nodeState) => !!nodeState),
         switchMap((nodeState) => {
           const node = nodeState!.node
           return from(
@@ -84,19 +91,63 @@ const favorites = createFetcherStore<[FavoriteDocumentContext], FavoriteStatusRe
 })
 
 /**
- * Gets a StateSource for the favorite status of a document.
- * @param instance - The Sanity instance.
- * @param context - The document context including ID, type, and resource information.
- * @returns A StateSource emitting `{ isFavorited: boolean }`.
+ * Input for {@link setFavorite}: the document context plus the desired state.
+ *
  * @public
  */
-export const getFavoritesState = favorites.getState
+export type SetFavoriteInput = FavoriteDocumentContext & {
+  /** The favorite state to move to: `true` to favorite, `false` to unfavorite. */
+  isFavorited: boolean
+}
 
 /**
- * Resolves the favorite status for a document.
- * @param instance - The Sanity instance.
- * @param context - The document context including ID, type, and resource information.
- * @returns A Promise resolving to `{ isFavorited: boolean }`.
- * @public
+ * Sets a document's favorite state over comlink, then invalidates the cached
+ * {@link favorites} status for that document so active readers reconverge on
+ * server truth. The write-side counterpart to {@link favorites}.
+ *
+ * @internal
  */
-export const resolveFavoritesState = favorites.resolveState
+export const setFavorite = defineMutation<SetFavoriteInput, FavoriteStatusResponse>({
+  name: 'setFavorite',
+  mutationFn: (instance) => {
+    return ({isFavorited, ...context}: SetFavoriteInput): Observable<FavoriteStatusResponse> => {
+      const nodeStateSource = getNodeState(instance, {
+        name: SDK_NODE_NAME,
+        connectTo: SDK_CHANNEL_NAME,
+      })
+      const payload = {
+        eventType: isFavorited ? 'added' : 'removed',
+        document: {
+          id: context.documentId,
+          type: context.documentType,
+          resource: {
+            id: context.resourceId,
+            type: context.resourceType,
+            ...(context.schemaName ? {schemaName: context.schemaName} : {}),
+          },
+        },
+      }
+
+      return nodeStateSource.observable.pipe(
+        // Wait until connected, then complete after the single mutation settles.
+        first((nodeState) => !!nodeState),
+        switchMap((nodeState) => {
+          const node = nodeState!.node
+          return from(
+            node.fetch(
+              // @ts-expect-error -- getOrCreateNode should be refactored to take type arguments
+              'dashboard/v1/events/favorite/mutate',
+              payload,
+            ) as Promise<{success: boolean}>,
+          ).pipe(
+            map((response) => {
+              if (!response.success) throw new Error('Failed to update favorite status')
+              return {isFavorited}
+            }),
+          )
+        }),
+      )
+    }
+  },
+  invalidates: (_result, input) => [{type: 'favorite', id: createFavoriteKey(input)}],
+})

package/src/installations/installations.test-d.ts

@@ -29,6 +29,11 @@ test('Installation — no includes: only the base shape', () => {
   expectTypeOf<Extract<keyof Installation, IncludeKeys>>().toEqualTypeOf<never>()
 })
 
+test('InstallationBase — the application sub-object carries name and reference', () => {
+  expectTypeOf<InstallationBase['application']['name']>().toEqualTypeOf<string>()
+  expectTypeOf<InstallationBase['application']['reference']>().toEqualTypeOf<string>()
+})
+
 test('Installation — each token adds its top-level field, required, others absent', () => {
   expectTypeOf<Installation<'access'>['access']>().toEqualTypeOf<InstallationAccess[]>()
   expectTypeOf<

package/src/installations/installations.ts

@@ -79,6 +79,10 @@ export interface InstallationBase {
   updatedAt: string
   application: {
     title: string
+    /** Stable, immutable identity of the installed singleton, distinct from `slug`. */
+    name: string
+    /** Qualified, globally-unique handle of the installed singleton (e.g. `sanity/<name>`). */
+    reference: string
     slug: string | null
   }
 }

package/src/presence/bifurTransport.test.ts

@@ -1,7 +1,7 @@
 import {fromUrl} from '@sanity/bifur-client'
 import {type SanityClient} from '@sanity/client'
-import {of, Subject} from 'rxjs'
-import {beforeEach, describe, expect, it, type Mock, vi} from 'vitest'
+import {type Observable, of, Subject} from 'rxjs'
+import {afterEach, beforeEach, describe, expect, it, type Mock, vi} from 'vitest'
 
 import {createBifurTransport} from './bifurTransport'
 import {type PresenceLocation, type TransportEvent} from './types'
@@ -39,16 +39,20 @@ describe('createBifurTransport', () => {
   let mockBifurClient: {
     listen: Mock
     request: Mock
+    heartbeats: Observable<Date>
   }
   let mockSanityClient: SanityClient
   let token$: Subject<string | null>
+  let heartbeats$: Subject<Date>
 
   beforeEach(() => {
     vi.useFakeTimers()
     vi.clearAllMocks()
+    heartbeats$ = new Subject<Date>()
     mockBifurClient = {
       listen: vi.fn(() => new Subject<never>()),
       request: vi.fn(() => of(undefined)),
+      heartbeats: heartbeats$.asObservable(),
     }
     fromUrlMock.mockReturnValue(mockBifurClient)
 
@@ -130,6 +134,8 @@ describe('createBifurTransport', () => {
 
     const receivedEvents: TransportEvent[] = []
     incomingEvents$.subscribe((event) => receivedEvents.push(event))
+    // The listener is established per live connection, so bring one up first.
+    heartbeats$.next(new Date())
 
     incomingBifurEvents$.next({
       type: 'rollCall',
@@ -161,6 +167,8 @@ describe('createBifurTransport', () => {
 
     const receivedEvents: TransportEvent[] = []
     incomingEvents$.subscribe((event) => receivedEvents.push(event))
+    // The listener is established per live connection, so bring one up first.
+    heartbeats$.next(new Date())
 
     const locations: PresenceLocation[] = [
       {type: 'document', documentId: 'doc1', path: ['a'], lastActiveAt: new Date().toISOString()},
@@ -200,6 +208,8 @@ describe('createBifurTransport', () => {
 
     const receivedEvents: TransportEvent[] = []
     incomingEvents$.subscribe((event) => receivedEvents.push(event))
+    // The listener is established per live connection, so bring one up first.
+    heartbeats$.next(new Date())
 
     incomingBifurEvents$.next({
       type: 'disconnect',
@@ -233,6 +243,7 @@ describe('createBifurTransport', () => {
     incomingEvents$.subscribe({
       error: (err) => errors.push(err),
     })
+    heartbeats$.next(new Date())
 
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     incomingBifurEvents$.next({type: 'unknown'} as any)
@@ -242,7 +253,148 @@ describe('createBifurTransport', () => {
     expect(errors[0].message).toContain('Got unknown presence event')
   })
 
-  describe('dispatchMessage', () => {
+  describe('connections', () => {
+    it('emits an incrementing generation each time the socket becomes live', () => {
+      const [, , connections$] = createBifurTransport({
+        client: mockSanityClient,
+        token$,
+        sessionId: 'my-session',
+      })
+
+      const generations: number[] = []
+      connections$.subscribe((generation) => generations.push(generation))
+
+      // Several heartbeats on one live socket are a single generation.
+      heartbeats$.next(new Date())
+      heartbeats$.next(new Date())
+      expect(generations).toEqual([1])
+
+      // bifur-client errors the stream when the socket closes. The transport is
+      // expected to reconnect rather than give up for the life of the page.
+      const reconnected$ = new Subject<Date>()
+      mockBifurClient.heartbeats = reconnected$.asObservable()
+      heartbeats$.error(new Error('WebSocket connection error'))
+
+      // First retry is scheduled 200ms out (2 ** 1 * 100).
+      vi.advanceTimersByTime(200)
+      reconnected$.next(new Date())
+
+      expect(generations).toEqual([1, 2])
+    })
+
+    it('does not resubscribe before the backoff has elapsed', () => {
+      const [, , connections$] = createBifurTransport({
+        client: mockSanityClient,
+        token$,
+        sessionId: 'my-session',
+      })
+
+      const generations: number[] = []
+      connections$.subscribe((generation) => generations.push(generation))
+      heartbeats$.next(new Date())
+
+      const reconnected$ = new Subject<Date>()
+      mockBifurClient.heartbeats = reconnected$.asObservable()
+      heartbeats$.error(new Error('WebSocket connection error'))
+
+      vi.advanceTimersByTime(199)
+      reconnected$.next(new Date())
+      expect(generations).toEqual([1])
+    })
+  })
+
+  describe('incoming events across a reconnect', () => {
+    it('keeps delivering presence after the socket drops', () => {
+      // bifur errors every stream on the same socket close, the inbound listener
+      // included. If only the heartbeat stream recovers, this client re-announces
+      // itself to peers while permanently ceasing to see any of them.
+      const firstListen$ = new Subject<IncomingBifurEvent>()
+      const secondListen$ = new Subject<IncomingBifurEvent>()
+      mockBifurClient.listen.mockReturnValueOnce(firstListen$).mockReturnValueOnce(secondListen$)
+
+      const [incomingEvents$, , connections$] = createBifurTransport({
+        client: mockSanityClient,
+        token$,
+        sessionId: 'my-session',
+      })
+
+      const received: TransportEvent[] = []
+      incomingEvents$.subscribe({
+        next: (event) => received.push(event),
+        error: () => received.push({type: 'rollCall', userId: 'STREAM_DIED', sessionId: ''}),
+      })
+      connections$.subscribe()
+
+      heartbeats$.next(new Date())
+      firstListen$.next({type: 'rollCall', i: 'user-1', session: 'before'})
+      expect(received.map((e) => e.sessionId)).toEqual(['before'])
+
+      // Socket closes: both streams error.
+      const reconnectedHeartbeats$ = new Subject<Date>()
+      mockBifurClient.heartbeats = reconnectedHeartbeats$.asObservable()
+      firstListen$.error(new Error('WebSocket connection error'))
+      heartbeats$.error(new Error('WebSocket connection error'))
+
+      vi.advanceTimersByTime(200)
+      reconnectedHeartbeats$.next(new Date())
+
+      // Peers answer the roll call we send on reconnect. We have to be listening.
+      secondListen$.next({type: 'rollCall', i: 'user-1', session: 'after'})
+
+      expect(received.map((e) => e.sessionId)).toEqual(['before', 'after'])
+    })
+  })
+
+  describe('unload', () => {
+    afterEach(() => {
+      vi.unstubAllGlobals()
+    })
+
+    it('emits on beforeunload and pagehide, and removes its listeners', () => {
+      // These tests run in Node, so stand in a bare EventTarget for `window`.
+      const fakeWindow = new EventTarget()
+      vi.stubGlobal('window', fakeWindow)
+
+      const [, , , unload$] = createBifurTransport({
+        client: mockSanityClient,
+        token$,
+        sessionId: 'my-session',
+      })
+
+      let emissions = 0
+      const subscription = unload$.subscribe(() => {
+        emissions += 1
+      })
+
+      fakeWindow.dispatchEvent(new Event('beforeunload'))
+      expect(emissions).toBe(1)
+
+      // `pagehide` matters on its own: iOS Safari and pages entering the
+      // back/forward cache never fire `beforeunload`.
+      fakeWindow.dispatchEvent(new Event('pagehide'))
+      expect(emissions).toBe(2)
+
+      // The listeners belong to the subscription, so unsubscribing removes them
+      // instead of leaking one per transport for the life of the page.
+      subscription.unsubscribe()
+      fakeWindow.dispatchEvent(new Event('beforeunload'))
+      expect(emissions).toBe(2)
+    })
+
+    it('is inert when there is no window', () => {
+      const [, , , unload$] = createBifurTransport({
+        client: mockSanityClient,
+        token$,
+        sessionId: 'my-session',
+      })
+
+      let completed = false
+      unload$.subscribe({complete: () => (completed = true)})
+      expect(completed).toBe(true)
+    })
+  })
+
+  describe('dispatch', () => {
     it('sends a "rollCall" message', () => {
       const [, dispatchMessage] = createBifurTransport({
         client: mockSanityClient,