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

package/src/document/resourceRules.ts

@@ -0,0 +1,117 @@
+import {DocumentId, getPublishedId} from '@sanity/id-utils'
+
+import {
+  type DocumentResource,
+  isCanvasResource,
+  isMediaLibraryResource,
+} from '../config/sanityConfig'
+import {isReleasePerspective} from '../releases/utils/isReleasePerspective'
+import {type Action, type DocumentAction} from './actions'
+import {getEffectiveDocumentId} from './util'
+
+export interface EffectiveDocModel {
+  /**
+   * If this is `undefined`, the resource has no opinion and the handle's `liveEdit`
+   * flag should be respected.
+   */
+  liveEdit: boolean | undefined
+  /**
+   * When `false`, the resource does not support release perspectives. Callers
+   * should drop any release perspective and fall back to the standard path.
+   */
+  supportsReleases: boolean
+}
+
+const MEDIA_LIBRARY_DRAFTED_TYPES = new Set(['sanity.asset'])
+
+/**
+ * Different resources have different "default" editing models.
+ *
+ * Canvas uses a liveEdit model.
+ * Medial Library is mostly liveEdit except for `sanity.asset`, which retains the
+ * draft/published model. Neither resource supports release perspectives.
+ */
+export function getEffectiveDocumentModel(
+  resource: DocumentResource | undefined,
+  documentType: string | undefined,
+): EffectiveDocModel {
+  if (!resource) {
+    return {liveEdit: undefined, supportsReleases: true}
+  }
+  if (isCanvasResource(resource)) {
+    return {liveEdit: true, supportsReleases: false}
+  }
+  if (isMediaLibraryResource(resource)) {
+    const isDrafted = documentType ? MEDIA_LIBRARY_DRAFTED_TYPES.has(documentType) : false
+    return {liveEdit: !isDrafted, supportsReleases: false}
+  }
+  return {liveEdit: undefined, supportsReleases: true}
+}
+
+function describeResource(resource: DocumentResource | undefined): string {
+  if (resource && isCanvasResource(resource)) return 'Canvas'
+  if (resource && isMediaLibraryResource(resource)) return 'Media Library'
+  return 'this resource'
+}
+
+/**
+ * Rewrites edit actions to match the editing model of the bound resource.
+ *
+ * Canvas and Media Library resources do not support release perspectives, and
+ * Canvas (plus most Media Library types) does not have a draft/published
+ * model. When an edit action arrives with a release perspective for a resource
+ * that doesn't support it, the perspective is stripped and a single warning
+ * is logged. When the resource forces liveEdit, the action's `liveEdit` flag
+ * is set so the dispatcher takes the liveEdit branch.
+ *
+ * Only `document.edit` actions are normalized today — other action types
+ * (publish, unpublish, release actions, etc.) pass through unchanged.
+ *
+ * @internal
+ */
+export function normalizeActionsForResource(
+  actions: Action[],
+  resource: DocumentResource | undefined,
+): Action[] {
+  // collect actions that may have changed in unexpected ways
+  const stripped: Array<{documentType: string; documentId: string}> = []
+
+  const normalized = actions.map((action) => {
+    if (action.type !== 'document.edit') return action
+
+    const {liveEdit: forcedLiveEdit, supportsReleases} = getEffectiveDocumentModel(
+      resource,
+      action.documentType,
+    )
+    const shouldRemovePerspective = isReleasePerspective(action.perspective) && !supportsReleases
+    const shouldForceLiveEdit = forcedLiveEdit === true && !action.liveEdit
+
+    if (!shouldRemovePerspective && !shouldForceLiveEdit) return action
+
+    const corrected: DocumentAction = {...action}
+    if (shouldForceLiveEdit) corrected.liveEdit = true
+    if (shouldRemovePerspective) corrected.perspective = undefined
+
+    // ensure we're using the right document ID for the corrected model
+    corrected.documentId = getEffectiveDocumentId({
+      ...corrected,
+      documentId: getPublishedId(DocumentId(corrected.documentId)),
+    })
+
+    if (shouldRemovePerspective) {
+      stripped.push({documentType: action.documentType, documentId: corrected.documentId})
+    }
+
+    return corrected
+  })
+
+  if (stripped.length > 0) {
+    const docs = stripped.map((e) => `${e.documentType} (${e.documentId})`).join(', ')
+    // eslint-disable-next-line no-console
+    console.warn(
+      `[sanity-sdk] ${describeResource(resource)} does not support release perspectives — falling back to the standard editing path for: ${docs}`,
+    )
+  }
+
+  return normalized
+}

package/src/document/sharedListener.test.ts

@@ -16,7 +16,7 @@ import {createSanityInstance} from '../store/createSanityInstance'
 import {type StateSource} from '../store/createStateSourceAction'
 import {createFetchDocument, createSharedListener} from './sharedListener'
 
-const instance = createSanityInstance()
+const instance = createSanityInstance({projectId: 'p', dataset: 'd'})
 
 vi.mock('../client/clientStore.ts', () => ({getClientState: vi.fn()}))
 vi.mock('@sanity/mutate/_unstable_store', () => ({createDocumentLoaderFromClient: vi.fn()}))
@@ -43,14 +43,16 @@ describe('createSharedListener', () => {
   })
 
   it('should call client.listen with the expected parameters', () => {
-    createSharedListener(instance, {projectId: 'p', dataset: 'd'}).events.subscribe()
+    createSharedListener(instance).events.subscribe()
     expect(fakeClient.listen).toHaveBeenCalledTimes(1)
     expect(fakeClient.listen).toHaveBeenCalledWith(
       '*',
       {},
       {
-        events: ['mutation', 'welcome', 'reconnect'],
+        events: ['mutation', 'welcome', 'welcomeback', 'reconnect', 'reset'],
+        enableResume: true,
         includeResult: false,
+        includeAllVersions: true,
         tag: 'document-listener',
       },
     )
@@ -62,7 +64,7 @@ describe('createSharedListener', () => {
     const mutationEvent: MutationEvent = {type: 'mutation'} as MutationEvent
     const reconnectEvent: ReconnectEvent = {type: 'reconnect'} as ReconnectEvent
 
-    const sharedListener = createSharedListener(instance, {projectId: 'p', dataset: 'd'})
+    const sharedListener = createSharedListener(instance)
     // Start collecting the emitted events.
     const eventsPromise = lastValueFrom(sharedListener.events.pipe(toArray()))
 
@@ -80,7 +82,7 @@ describe('createSharedListener', () => {
   it('should replay the welcome event for new subscribers', async () => {
     const welcomeEvent: WelcomeEvent = {type: 'welcome', listenerName: 'listener'}
 
-    const sharedListener = createSharedListener(instance, {projectId: 'p', dataset: 'd'})
+    const sharedListener = createSharedListener(instance)
     // First subscription: emit welcome and complete.
     const firstPromise = lastValueFrom(sharedListener.events.pipe(toArray()))
     fakeListenSubject.next(welcomeEvent)
@@ -97,7 +99,7 @@ describe('createSharedListener', () => {
     const mutationEvent = {type: 'mutation'} as MutationEvent
     const reconnectEvent = {type: 'reconnect'} as ReconnectEvent
 
-    const sharedListener = createSharedListener(instance, {projectId: 'p', dataset: 'd'})
+    const sharedListener = createSharedListener(instance)
     const eventsPromise = lastValueFrom(sharedListener.events.pipe(toArray()))
     fakeListenSubject.next(mutationEvent)
     fakeListenSubject.next(reconnectEvent)
@@ -110,7 +112,7 @@ describe('createSharedListener', () => {
     const welcomeEvent = {type: 'welcome'} as WelcomeEvent
     const mutationEvent = {type: 'mutation'} as MutationEvent
 
-    const sharedListener = createSharedListener(instance, {projectId: 'p', dataset: 'd'})
+    const sharedListener = createSharedListener(instance)
 
     // Subscribe two observers concurrently.
     const subscriber1 = sharedListener.events.pipe(bufferTime(0))
@@ -133,7 +135,7 @@ describe('createSharedListener', () => {
 
   it('should propagate errors from the underlying client.listen observable', async () => {
     const errorMessage = 'Test error'
-    const sharedListener = createSharedListener(instance, {projectId: 'p', dataset: 'd'})
+    const sharedListener = createSharedListener(instance)
 
     const error$ = sharedListener.events.pipe(
       toArray(),
@@ -149,7 +151,7 @@ describe('createSharedListener', () => {
   it('should stop emitting events after calling dispose', async () => {
     const welcomeEvent: WelcomeEvent = {type: 'welcome', listenerName: 'listener'}
     const mutationEvent: MutationEvent = {type: 'mutation'} as MutationEvent
-    const sharedListener = createSharedListener(instance, {projectId: 'p', dataset: 'd'})
+    const sharedListener = createSharedListener(instance)
 
     const events: ListenEvent<SanityDocument>[] = []
     const subscription = sharedListener.events.subscribe((event) => {
@@ -187,7 +189,7 @@ describe('createFetchDocument', () => {
   })
 
   it('should call createDocumentLoaderFromClient with the fetched client', async () => {
-    const fetchDocument = createFetchDocument(instance, {projectId: 'p', dataset: 'd'})
+    const fetchDocument = createFetchDocument(instance)
     const accessibleResult = {
       id: 'doc1',
       document: {_id: 'doc1', _rev: 'rev1'},
@@ -201,7 +203,7 @@ describe('createFetchDocument', () => {
   })
 
   it('should return the document when it is accessible', async () => {
-    const fetchDocument = createFetchDocument(instance, {projectId: 'p', dataset: 'd'})
+    const fetchDocument = createFetchDocument(instance)
     const accessibleResult = {
       id: 'doc1',
       document: {_id: 'doc1', _rev: 'rev1', title: 'Test Document'},
@@ -214,7 +216,7 @@ describe('createFetchDocument', () => {
   })
 
   it('should return null when the document is inaccessible due to existence', async () => {
-    const fetchDocument = createFetchDocument(instance, {projectId: 'p', dataset: 'd'})
+    const fetchDocument = createFetchDocument(instance)
     const inaccessibleResult = {
       accessible: false,
       id: 'doc1',
@@ -227,7 +229,7 @@ describe('createFetchDocument', () => {
   })
 
   it('should throw an error when the document is inaccessible due to permissions', async () => {
-    const fetchDocument = createFetchDocument(instance, {projectId: 'p', dataset: 'd'})
+    const fetchDocument = createFetchDocument(instance)
     const inaccessibleResult = {
       accessible: false,
       id: 'doc1',
@@ -241,7 +243,7 @@ describe('createFetchDocument', () => {
   })
 
   it('should propagate errors from the loadDocument observable', async () => {
-    const fetchDocument = createFetchDocument(instance, {projectId: 'p', dataset: 'd'})
+    const fetchDocument = createFetchDocument(instance)
     const errorMessage = 'Load document failed'
     fakeLoadDocument.mockReturnValue(throwError(() => new Error(errorMessage)))
 

package/src/document/sharedListener.ts

@@ -16,6 +16,7 @@ import {
 import {getClientState} from '../client/clientStore'
 import {type DocumentResource} from '../config/sanityConfig'
 import {type SanityInstance} from '../store/createSanityInstance'
+import {dedupeListenerEvents, groupTransactionEvents} from './listenerEventOperators'
 
 const API_VERSION = 'v2025-05-06'
 
@@ -26,12 +27,12 @@ export interface SharedListener {
 
 export function createSharedListener(
   instance: SanityInstance,
-  resource: DocumentResource,
+  resource?: DocumentResource,
 ): SharedListener {
   const dispose$ = new Subject<void>()
   const events$ = getClientState(instance, {
     apiVersion: API_VERSION,
-    ...(resource ? {resource} : {}),
+    resource,
   }).observable.pipe(
     switchMap((client) =>
       // TODO: it seems like the client.listen method is not emitting disconnected
@@ -41,8 +42,15 @@ export function createSharedListener(
         '*',
         {},
         {
-          events: ['mutation', 'welcome', 'reconnect'],
+          // with `enableResume`, a reconnect replays the events missed while
+          // offline (emitting `welcomeback`) instead of forcing a refetch of
+          // every subscribed document. when the backend cannot resume, it
+          // emits `welcome` or `reset`, both of which trigger a refetch
+          events: ['mutation', 'welcome', 'welcomeback', 'reconnect', 'reset'],
+          enableResume: true,
           includeResult: false,
+          // the document store handles version documents, so we need to include all versions
+          includeAllVersions: true,
           tag: 'document-listener',
           // // from manual testing, it seems like mendoza patches may be
           // // causing some ambiguity/wonkiness
@@ -51,6 +59,11 @@ export function createSharedListener(
         },
       ),
     ),
+    // resumed events are delivered at-least-once, so drop replayed duplicates
+    dedupeListenerEvents(),
+    // hold multi-document transactions (e.g. publish) until complete so
+    // per-document processing never observes half a transaction
+    groupTransactionEvents(),
     takeUntil(dispose$),
     share(),
   )
@@ -67,13 +80,16 @@ export function createSharedListener(
   }
 }
 
-export function createFetchDocument(instance: SanityInstance, resource: DocumentResource) {
+export function createFetchDocument(instance: SanityInstance, resource?: DocumentResource) {
   return function (documentId: string): Observable<SanityDocument | null> {
-    return getClientState(instance, {apiVersion: API_VERSION, resource}).observable.pipe(
+    return getClientState(instance, {
+      apiVersion: API_VERSION,
+      resource,
+    }).observable.pipe(
       switchMap((client) => {
-        // TODO: remove this once the client is updated to v7 the new type is available in @sanity/mutate/_unstable_store
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        const loadDocument = createDocumentLoaderFromClient(client as any)
+        // creates a observable request to the /doc/{documentId} endpoint for a given document id
+        // should work across all kinds of document IDs (drafts.**, version.**., etc.)
+        const loadDocument = createDocumentLoaderFromClient(client)
         return loadDocument(documentId)
       }),
       map((result) => {

package/src/document/util.ts

@@ -0,0 +1,14 @@
+import {DocumentId, getPublishedId, getVersionId} from '@sanity/id-utils'
+
+import {type DocumentHandle} from '../config/sanityConfig'
+import {isReleasePerspective} from '../releases/utils/isReleasePerspective'
+
+export function getEffectiveDocumentId(doc: DocumentHandle): string {
+  if (doc.liveEdit) {
+    return doc.documentId
+  } else if (isReleasePerspective(doc.perspective)) {
+    return getVersionId(DocumentId(doc.documentId), doc.perspective.releaseName)
+  } else {
+    return getPublishedId(DocumentId(doc.documentId))
+  }
+}

package/src/favorites/favorites.test.ts

@@ -39,7 +39,6 @@ describe('favoritesStore', () => {
     resourceId: 'res456',
     resourceType: 'studio' as const,
     schemaName: 'movieSchema',
-    resource: {projectId: 'p', dataset: 'd'},
   }
 
   const mockContextNoSchema = {
@@ -47,13 +46,12 @@ describe('favoritesStore', () => {
     documentType: 'movie',
     resourceId: 'res456',
     resourceType: 'studio' as const,
-    resource: {projectId: 'p', dataset: 'd'},
   }
 
   describe('createFavoriteKey', () => {
     beforeEach(() => {
       vi.resetAllMocks()
-      instance = createSanityInstance()
+      instance = createSanityInstance({projectId: 'p', dataset: 'd'})
       setupMockStateSource()
     })
 
@@ -101,7 +99,7 @@ describe('favoritesStore', () => {
   describe('fetcher', () => {
     beforeEach(() => {
       vi.resetAllMocks()
-      instance = createSanityInstance()
+      instance = createSanityInstance({projectId: 'p', dataset: 'd'})
       setupMockStateSource()
     })
 
@@ -148,8 +146,9 @@ describe('favoritesStore', () => {
       await firstValueFrom(state.observable)
       expect(mockFetch).toHaveBeenCalledTimes(1)
       // Second subscriber should use cached response
-      const sub2 = state.subscribe()
-      await firstValueFrom(state.observable)
+      const state2 = getFavoritesState(instance!, mockContext)
+      const sub2 = state2.subscribe()
+      await firstValueFrom(state2.observable)
       expect(mockFetch).toHaveBeenCalledTimes(1)
       // Cleanup
       sub1()

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

@@ -0,0 +1,68 @@
+import {expectTypeOf, test} from 'vitest'
+
+import {type SanityInstance} from '../store/createSanityInstance'
+import {type StateSource} from '../store/createStateSourceAction'
+import {type FetcherSnapshot} from '../store/fetcherStore'
+import {
+  type Installation,
+  installation,
+  type InstallationAccess,
+  type InstallationActiveConfig,
+  type InstallationBase,
+  type InstallationInclude,
+  type InstallationInterface,
+  installations,
+  type InstallationsResponse,
+} from './installations'
+
+const instance = {} as SanityInstance
+
+type IncludeKeys = 'activeConfig' | 'access' | 'interfaces'
+
+// Whether key `K` of `T` is optional, without an `{}`-based check.
+type KeyModifier<T, K extends keyof T> =
+  Pick<T, K> extends Required<Pick<T, K>> ? 'required' : 'optional'
+
+test('Installation — no includes: only the base shape', () => {
+  expectTypeOf<Installation>().toEqualTypeOf<InstallationBase>()
+  expectTypeOf<Installation<never>>().toEqualTypeOf<InstallationBase>()
+  expectTypeOf<Extract<keyof Installation, IncludeKeys>>().toEqualTypeOf<never>()
+})
+
+test('Installation — each token adds its top-level field, required, others absent', () => {
+  expectTypeOf<Installation<'access'>['access']>().toEqualTypeOf<InstallationAccess[]>()
+  expectTypeOf<
+    Extract<keyof Installation<'access'>, 'activeConfig' | 'interfaces'>
+  >().toEqualTypeOf<never>()
+
+  expectTypeOf<Installation<'interfaces'>['interfaces']>().toEqualTypeOf<InstallationInterface[]>()
+  expectTypeOf<
+    Installation<'activeConfig'>['activeConfig']
+  >().toEqualTypeOf<InstallationActiveConfig | null>()
+})
+
+test('Installation — multiple tokens add each field', () => {
+  type Both = Installation<'access' | 'interfaces'>
+  expectTypeOf<Both['access']>().toEqualTypeOf<InstallationAccess[]>()
+  expectTypeOf<Both['interfaces']>().toEqualTypeOf<InstallationInterface[]>()
+  expectTypeOf<Extract<keyof Both, 'activeConfig'>>().toEqualTypeOf<never>()
+})
+
+test('Installation — a wide include array makes the fields optional', () => {
+  type Wide = Installation<InstallationInclude>
+  expectTypeOf<KeyModifier<Wide, 'access'>>().toEqualTypeOf<'optional'>()
+  expectTypeOf<KeyModifier<Wide, 'interfaces'>>().toEqualTypeOf<'optional'>()
+  expectTypeOf<KeyModifier<Wide, 'activeConfig'>>().toEqualTypeOf<'optional'>()
+})
+
+test('installations.resolveState — resolves the wide list envelope', () => {
+  expectTypeOf(
+    installations.resolveState(instance, {organizationId: 'org_1'}),
+  ).resolves.toEqualTypeOf<InstallationsResponse<InstallationInclude>>()
+})
+
+test('installation.getState — exposes the snapshot envelope', () => {
+  expectTypeOf(installation.getState(instance, 'inst_1')).toEqualTypeOf<
+    StateSource<FetcherSnapshot<Installation<InstallationInclude>>>
+  >()
+})

package/src/installations/installations.test.ts

@@ -0,0 +1,62 @@
+import {type SanityClient} from '@sanity/client'
+import {of} from 'rxjs'
+import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest'
+
+import {getClientState} from '../client/clientStore'
+import {createSanityInstance, type SanityInstance} from '../store/createSanityInstance'
+import {type StateSource} from '../store/createStateSourceAction'
+import {installation, installations} from './installations'
+
+vi.mock('../client/clientStore')
+
+describe('installations', () => {
+  let instance: SanityInstance
+  const request = vi.fn()
+
+  beforeEach(() => {
+    instance = createSanityInstance({projectId: 'p', dataset: 'd'})
+    request.mockReset()
+    vi.mocked(getClientState).mockReturnValue({
+      observable: of({observable: {request}} as unknown as SanityClient),
+    } as StateSource<SanityClient>)
+  })
+
+  afterEach(() => {
+    instance.dispose()
+  })
+
+  it('lists installations for an organization on the global client', async () => {
+    const response = {nextCursor: null, data: [{id: 'inst1'}]}
+    request.mockReturnValue(of(response))
+
+    const result = await installations.resolveState(instance, {
+      organizationId: 'org1',
+      include: ['interfaces'],
+    })
+
+    expect(result).toEqual(response)
+    expect(getClientState).toHaveBeenCalledWith(instance, {
+      apiVersion: 'vX',
+      scope: 'global',
+    })
+    expect(request).toHaveBeenCalledWith({
+      uri: '/installations',
+      query: {organizationId: 'org1', include: 'interfaces'},
+      tag: 'installations.list',
+    })
+  })
+
+  it('fetches a single installation by id', async () => {
+    const inst = {id: 'inst1', applicationId: 'app1'}
+    request.mockReturnValue(of(inst))
+
+    const result = await installation.resolveState(instance, 'inst1')
+
+    expect(result).toEqual(inst)
+    expect(request).toHaveBeenCalledWith({
+      uri: '/installations/inst1',
+      query: {},
+      tag: 'installations.get',
+    })
+  })
+})