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

package/src/presence/types.ts

@@ -1,27 +1,199 @@
 import {type SanityClient} from '@sanity/client'
+import {type Path} from '@sanity/types'
 import {type Observable} from 'rxjs'
 
+import {type PerspectiveHandle} from '../config/sanityConfig'
 import {type SanityUser} from '../users/types'
 
-/** @public */
+/**
+ * One end of a text selection: a Portable Text path plus a character offset
+ * within the span it addresses.
+ * @public
+ */
+export interface PresenceSelectionPoint {
+  path: Path
+  offset: number
+}
+
+/**
+ * A Portable Text caret or selected range, as exchanged with the Studio.
+ *
+ * Structurally identical to `EditorSelection` from `@portabletext/editor`, and
+ * declared separately so that `@sanity/sdk` stays free of React dependencies. A
+ * value from the editor can be passed straight through, and vice versa.
+ *
+ * `offset` is a character offset within the span that `path` addresses.
+ * @public
+ */
+export type PresenceSelection = {
+  anchor: PresenceSelectionPoint
+  focus: PresenceSelectionPoint
+  backward?: boolean
+} | null
+
+/**
+ * Somewhere a participant is, as it arrives over the wire.
+ *
+ * Prefer {@link DocumentPresence} from `getDocumentPresence`, which is scoped to one
+ * document, flattened for rendering, and types `path` accurately.
+ * @public
+ */
 export interface PresenceLocation {
   type: 'document'
+  /**
+   * The specific document the participant is in, so a draft, published, or version
+   * id rather than a bare document id.
+   */
   documentId: string
+  /**
+   * The focused field path, empty when they are in the document but not a field.
+   *
+   * Declared as `string[]`, but segments can also be numbers or `{_key: string}`
+   * objects when the focus is inside an array or a Portable Text field, because
+   * that is what other clients send. Guard for those rather than assuming strings.
+   * Widening the declared type is a breaking change, so it waits for the next major;
+   * {@link DocumentPresence.path} is typed correctly today.
+   */
   path: string[]
+  /**
+   * When the participant said they were last active, on *their* clock.
+   *
+   * Fine for display, unreliable for deciding whether someone is still here: it is
+   * subject to clock skew between machines. Presence already drops participants that
+   * stop announcing, so a session appearing here is one the SDK still considers
+   * live.
+   */
   lastActiveAt: string
+  /** A Portable Text caret, when the focused field is a Portable Text field. */
+  selection?: PresenceSelection
 }
 
-/** @public */
+/**
+ * A location as it travels over the wire. Identical in shape to
+ * {@link PresenceLocation}, except `path` is a full `Path`, which is what is
+ * really exchanged. See the note on {@link PresenceLocation.path}.
+ *
+ * Internal: nothing in the public API accepts or returns this. Apps describe
+ * where they are with {@link ReportPresenceOptions} and read presence as
+ * {@link PresenceLocation}.
+ * @internal
+ */
+export interface WirePresenceLocation extends Omit<PresenceLocation, 'path'> {
+  path: Path
+}
+
+/**
+ * Which specific document a presence id resolves to.
+ *
+ * Presence compares exact document ids, so a client in a draft and a client in the
+ * published document are in different places even for the same `documentId`. Pass
+ * the perspective you are editing under and the SDK resolves it; the React hooks
+ * take it from `ResourceProvider` when you do not pass one.
+ * @public
+ */
+export interface PresencePerspectiveOptions extends PerspectiveHandle {
+  /** Live-edit documents have no draft, so presence resolves to the published id. */
+  liveEdit?: boolean
+}
+
+/**
+ * What an app reports about where the current user is.
+ *
+ * Omit `path` for document-level presence, or pass one for field-level presence.
+ * @public
+ */
+export interface ReportPresenceOptions extends PresencePerspectiveOptions {
+  /**
+   * The document the user is in.
+   *
+   * Pass the plain document id; the perspective decides which specific document that
+   * resolves to. An already-specific id is accepted and re-resolved, so passing
+   * `drafts.abc` while the perspective is `published` reports the published document.
+   */
+  documentId: string
+  /**
+   * The focused field path. Supports keyed and numeric segments, so array items
+   * and Portable Text spans can be addressed.
+   */
+  path?: Path
+  /** A Portable Text caret, when the focused field is a Portable Text field. */
+  selection?: PresenceSelection
+}
+
+/**
+ * One participant's session and everywhere it currently is.
+ *
+ * Keyed by session, not by user: the same person in two tabs is two entries with
+ * the same `user`.
+ * @public
+ */
 export interface UserPresence {
   user: SanityUser
   locations: PresenceLocation[]
+  /** Identifies one tab. Stable while that tab is open, and not reused. */
+  sessionId: string
+}
+
+/**
+ * One participant at one location within a single document, flattened so it can
+ * be rendered directly against a field.
+ *
+ * Unlike {@link PresenceLocation.path}, `path` here is typed as a full `Path`, so
+ * keyed and numeric segments are described rather than cast away.
+ * @beta
+ */
+export interface DocumentPresence {
+  user: SanityUser
+  /** Identifies one tab, so the same person in two tabs appears twice. */
   sessionId: string
+  /**
+   * The specific document id this participant is in: a draft, published, or
+   * version id, depending on which perspective they are editing.
+   */
+  documentId: string
+  /** The focused field path. Empty when they are in the document but no field. */
+  path: Path
+  /**
+   * When they said they were last active, on *their* clock. Fine for display,
+   * unreliable for liveness. See {@link PresenceLocation.lastActiveAt}.
+   */
+  lastActiveAt: string
+  /** The Portable Text caret, when they are focused in a Portable Text field. */
+  selection?: PresenceSelection
+}
+
+/** @beta */
+export interface DocumentPresenceOptions extends PresencePerspectiveOptions {
+  /**
+   * The document to look at. Resolved through the perspective exactly as
+   * {@link ReportPresenceOptions.documentId} is, so reads match writes.
+   */
+  documentId: string
+  /**
+   * Narrows to participants at or below this field path. Omit it for everyone in
+   * the document.
+   */
+  path?: Path
+  /**
+   * By default a draft, its published version, and any release versions are
+   * treated as the same document, which is what document lists want. Set this to
+   * compare ids exactly, which is what field-level indicators want so that a
+   * draft and a release version do not bleed into each other.
+   */
+  excludeVersions?: boolean
 }
 
 /** @public */
 export type PresenceTransport = [
   incomingEvents$: Observable<TransportEvent>,
   dispatchMessage: (message: TransportMessage) => Observable<void>,
+  /**
+   * Emits an incrementing generation number each time the connection becomes
+   * live. Reconnects with backoff, and subscribing keeps the connection alive.
+   */
+  connections$: Observable<number>,
+  /** Emits when the page is going away, so a disconnect can be announced. */
+  unload$: Observable<void>,
 ]
 
 /** @public */
@@ -54,7 +226,7 @@ export interface DisconnectEvent {
 /** @public */
 export type TransportMessage =
   | {type: 'rollCall'}
-  | {type: 'state'; locations: PresenceLocation[]}
+  | {type: 'state'; locations: WirePresenceLocation[]}
   | {type: 'disconnect'}
 
 /** @public */

package/src/preview/previewProjectionUtils.test.ts

@@ -58,7 +58,10 @@ describe('normalizeMedia', () => {
 })
 
 describe('transformProjectionToPreview', () => {
-  const instance = createSanityInstance()
+  const instance = createSanityInstance({
+    projectId: 'test-project',
+    dataset: 'test-dataset',
+  })
 
   beforeEach(async () => {
     vi.clearAllMocks()
@@ -78,11 +81,7 @@ describe('transformProjectionToPreview', () => {
       media: null,
     }
 
-    const result = transformProjectionToPreview(
-      instance,
-      {projectId: 'p', dataset: 'd'},
-      projectionResult,
-    )
+    const result = transformProjectionToPreview(instance, projectionResult)
 
     expect(result).toEqual({
       title: 'My Title',
@@ -101,11 +100,7 @@ describe('transformProjectionToPreview', () => {
       media: null,
     }
 
-    const result = transformProjectionToPreview(
-      instance,
-      {projectId: 'p', dataset: 'd'},
-      projectionResult,
-    )
+    const result = transformProjectionToPreview(instance, projectionResult)
 
     expect(result.title).toBe('article: doc1')
     expect(result.subtitle).toBeUndefined()
@@ -121,11 +116,7 @@ describe('transformProjectionToPreview', () => {
       media: {type: 'image-asset', _ref: 'image-abc123-200x200-png', url: ''},
     }
 
-    const result = transformProjectionToPreview(
-      instance,
-      {projectId: 'p', dataset: 'd'},
-      projectionResult,
-    )
+    const result = transformProjectionToPreview(instance, projectionResult)
 
     expect(result).toEqual({
       title: 'My Title',
@@ -152,11 +143,7 @@ describe('transformProjectionToPreview', () => {
       },
     }
 
-    const result = transformProjectionToPreview(
-      instance,
-      {projectId: 'p', dataset: 'd'},
-      projectionResult,
-    )
+    const result = transformProjectionToPreview(instance, projectionResult)
 
     expect(result).toEqual({
       title: 'My Title',
@@ -181,7 +168,7 @@ describe('transformProjectionToPreview', () => {
 
     const resource = {mediaLibraryId: 'test-library'}
 
-    transformProjectionToPreview(instance, resource, projectionResult)
+    transformProjectionToPreview(instance, projectionResult, resource)
 
     const {getClient} = await import('../client/clientStore')
     expect(getClient).toHaveBeenCalledWith(instance, {

package/src/preview/previewProjectionUtils.ts

@@ -1,10 +1,10 @@
 import {type SanityClient} from '@sanity/client'
 import {createImageUrlBuilder} from '@sanity/image-url'
-import {isObject} from 'lodash-es'
 
 import {getClient} from '../client/clientStore'
 import {type DocumentResource} from '../config/sanityConfig'
 import {type SanityInstance} from '../store/createSanityInstance'
+import {isObject} from '../utils/object'
 import {SUBTITLE_CANDIDATES, TITLE_CANDIDATES} from './previewConstants'
 import {type PreviewQueryResult, type PreviewValue} from './types'
 
@@ -71,13 +71,17 @@ function findFirstDefined(
  */
 export function transformProjectionToPreview(
   instance: SanityInstance,
-  resource: DocumentResource,
   projectionResult: PreviewQueryResult,
+  resource?: DocumentResource,
 ): PreviewValue {
   const title = findFirstDefined(TITLE_CANDIDATES, projectionResult.titleCandidates)
   const subtitle = findFirstDefined(SUBTITLE_CANDIDATES, projectionResult.subtitleCandidates, title)
 
-  const client = getClient(instance, {apiVersion: API_VERSION, resource})
+  // Get a client for the resource (if provided) or use the instance config
+  const client = getClient(instance, {
+    apiVersion: API_VERSION,
+    resource,
+  })
 
   return {
     title: String(title || `${projectionResult._type}: ${projectionResult._id}`),

package/src/preview/types.ts

@@ -59,18 +59,3 @@ export interface PreviewValue {
     lastEditedDraftAt?: string
   }
 }
-
-/**
- * Represents the current state of a preview value along with a flag indicating whether
- * the preview data is still being fetched or is fully resolved.
- *
- * The tuple contains a preview value or null, and a boolean indicating if the data is
- * pending. A `true` value means a fetch is ongoing; `false` indicates that the
- * currently provided preview value is up-to-date.
- *
- * @public
- */
-export type ValuePending<T> = {
-  data: T | null
-  isPending: boolean
-}

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

@@ -0,0 +1,37 @@
+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 Project, project, type ProjectMember} from './project'
+
+const instance = {} as SanityInstance
+
+test('project.resolveState — resolves the wide-boolean detail shape', () => {
+  expectTypeOf(project.resolveState(instance, {projectId: 'p'})).resolves.toEqualTypeOf<
+    Project<boolean, boolean>
+  >()
+})
+
+test('Project — literal flags narrow members and features', () => {
+  expectTypeOf<Project<true, true>['members']>().toEqualTypeOf<ProjectMember[]>()
+  expectTypeOf<Project<true, true>['features']>().toEqualTypeOf<string[]>()
+  expectTypeOf<keyof Project<false, false> & ('members' | 'features')>().toEqualTypeOf<never>()
+})
+
+test('Project<boolean, boolean> — members and features are optional', () => {
+  type Item = Project<boolean, boolean>
+  expectTypeOf<Item['members']>().toEqualTypeOf<ProjectMember[] | undefined>()
+  expectTypeOf<Item['features']>().toEqualTypeOf<string[] | undefined>()
+})
+
+test('project.getState — exposes the snapshot envelope', () => {
+  expectTypeOf(project.getState(instance, {projectId: 'p'})).toEqualTypeOf<
+    StateSource<FetcherSnapshot<Project<boolean, boolean>>>
+  >()
+})
+
+test('project — rejects non-boolean flag values', () => {
+  // @ts-expect-error includeMembers must be a boolean
+  void project.resolveState(instance, {includeMembers: 'yes'})
+})

package/src/project/project.test.ts

@@ -1,33 +1,178 @@
 import {type SanityClient} from '@sanity/client'
 import {of} from 'rxjs'
-import {describe, it} from 'vitest'
+import {afterEach, beforeEach, describe, it} from 'vitest'
 
 import {getClientState} from '../client/clientStore'
-import {createSanityInstance} from '../store/createSanityInstance'
+import {projects} from '../projects/projects'
+import {createSanityInstance, type SanityInstance} from '../store/createSanityInstance'
 import {type StateSource} from '../store/createStateSourceAction'
-import {resolveProject} from './project'
+import {getProjectCacheKey, project} from './project'
 
 vi.mock('../client/clientStore')
 
 describe('project', () => {
-  it('calls the `client.observable.projects.getById` method on the client and returns the result', async () => {
-    const instance = createSanityInstance()
+  let instance: SanityInstance
 
-    const project = {id: 'a'}
-    const getById = vi.fn().mockReturnValue(of(project))
+  beforeEach(() => {
+    instance = createSanityInstance({projectId: 'p', dataset: 'd'})
+  })
+
+  afterEach(() => {
+    instance.dispose()
+  })
+
+  it('calls `client.observable.request` against `/projects/<id>` and returns the result', async () => {
+    const detail = {id: 'a'}
+    const request = vi.fn().mockReturnValue(of(detail))
 
     const mockClient = {
-      observable: {
-        projects: {getById} as unknown as SanityClient['observable']['projects'],
+      observable: {request} as unknown as SanityClient['observable'],
+    } as SanityClient
+
+    vi.mocked(getClientState).mockReturnValue({
+      observable: of(mockClient),
+    } as StateSource<SanityClient>)
+
+    const result = await project.resolveState(instance, {projectId: 'a'})
+    expect(result).toEqual(detail)
+    expect(request).toHaveBeenCalledWith({
+      uri: '/projects/a',
+      query: {includeMembers: 'true', includeFeatures: 'true'},
+      tag: 'projects.get',
+    })
+  })
+
+  it('serializes query params (booleans → strings) and respects flags', async () => {
+    const request = vi.fn().mockReturnValue(of({id: 'a'}))
+    const mockClient = {
+      observable: {request} as unknown as SanityClient['observable'],
+    } as SanityClient
+
+    vi.mocked(getClientState).mockReturnValue({
+      observable: of(mockClient),
+    } as StateSource<SanityClient>)
+
+    await project.resolveState(instance, {
+      projectId: 'a',
+      includeMembers: false,
+      includeFeatures: false,
+    })
+
+    expect(request).toHaveBeenCalledWith({
+      uri: '/projects/a',
+      query: {
+        includeMembers: 'false',
+        includeFeatures: 'false',
       },
+      tag: 'projects.get',
+    })
+  })
+
+  it('falls back to the instance projectId when none is provided in options', async () => {
+    const request = vi.fn().mockReturnValue(of({id: 'p'}))
+    const mockClient = {
+      observable: {request} as unknown as SanityClient['observable'],
+    } as SanityClient
+
+    vi.mocked(getClientState).mockReturnValue({
+      observable: of(mockClient),
+    } as StateSource<SanityClient>)
+
+    await project.resolveState(instance)
+    expect(request).toHaveBeenCalledWith({
+      uri: '/projects/p',
+      query: {includeMembers: 'true', includeFeatures: 'true'},
+      tag: 'projects.get',
+    })
+  })
+
+  it('pre-seeds a memberless detail read from the cached default list without fetching', async () => {
+    const request = vi.fn().mockReturnValue(
+      of([
+        {id: 'p1', displayName: 'One'},
+        {id: 'p2', displayName: 'Two'},
+      ]),
+    )
+    const mockClient = {
+      observable: {request} as unknown as SanityClient['observable'],
     } as SanityClient
 
     vi.mocked(getClientState).mockReturnValue({
       observable: of(mockClient),
     } as StateSource<SanityClient>)
 
-    const result = await resolveProject(instance, {projectId: 'a'})
-    expect(result).toEqual(project)
-    expect(getById).toHaveBeenCalledWith('a')
+    await projects.resolveState(instance)
+    expect(request).toHaveBeenCalledTimes(1)
+
+    const source = project.getState(instance, {projectId: 'p1', includeMembers: false})
+    const unsubscribe = source.subscribe()
+    await new Promise((resolve) => setTimeout(resolve, 0))
+
+    expect(source.getCurrent()).toMatchObject({status: 'success', data: {id: 'p1'}})
+    expect(request).toHaveBeenCalledTimes(1)
+    unsubscribe()
+  })
+
+  it('does not pre-seed a detail read that includes members', async () => {
+    const list = [{id: 'p1', displayName: 'One'}]
+    const detail = {id: 'p1', displayName: 'One', members: []}
+    const request = vi.fn().mockReturnValueOnce(of(list)).mockReturnValueOnce(of(detail))
+    const mockClient = {
+      observable: {request} as unknown as SanityClient['observable'],
+    } as SanityClient
+
+    vi.mocked(getClientState).mockReturnValue({
+      observable: of(mockClient),
+    } as StateSource<SanityClient>)
+
+    await projects.resolveState(instance)
+
+    const result = await project.resolveState(instance, {projectId: 'p1'})
+    expect(result).toEqual(detail)
+    expect(request).toHaveBeenCalledTimes(2)
+  })
+})
+
+describe('project cache key generation', () => {
+  const mockInstance = {config: {projectId: 'p'}} as SanityInstance
+
+  it('default call includes :members and :features (both default-true)', () => {
+    expect(getProjectCacheKey(mockInstance)).toBe('project:p:members:features')
+  })
+
+  it('treats undefined and the matching default as the same key', () => {
+    expect(getProjectCacheKey(mockInstance)).toBe(
+      getProjectCacheKey(mockInstance, {includeMembers: true, includeFeatures: true}),
+    )
+  })
+
+  it('explicit includeFeatures: false drops the :features segment', () => {
+    expect(getProjectCacheKey(mockInstance, {includeFeatures: false})).toBe('project:p:members')
+  })
+
+  it('explicit includeMembers: false drops the :members segment', () => {
+    expect(getProjectCacheKey(mockInstance, {includeMembers: false})).toBe('project:p:features')
+  })
+
+  it('combines all segments in order', () => {
+    expect(
+      getProjectCacheKey(mockInstance, {
+        projectId: 'a',
+        includeMembers: true,
+        includeFeatures: true,
+      }),
+    ).toBe('project:a:members:features')
+  })
+
+  it('produces distinct keys for each meaningful option permutation', () => {
+    const keys = new Set([
+      getProjectCacheKey(mockInstance),
+      getProjectCacheKey(mockInstance, {includeMembers: false}),
+      getProjectCacheKey(mockInstance, {includeFeatures: false}),
+      getProjectCacheKey(mockInstance, {includeMembers: false, includeFeatures: false}),
+      getProjectCacheKey(mockInstance, {projectId: 'a'}),
+      getProjectCacheKey(mockInstance, {projectId: 'b'}),
+    ])
+    expect(keys.size).toBe(6)
   })
 })