@sanity/sdk 2.19.0 → 2.20.0

package/src/comments/reducers.ts

@@ -0,0 +1,316 @@
+import {omitProperty} from '../utils/object'
+import {type CommentPostPayload, type StoredComment} from './types'
+
+interface CommentsEntry {
+  /** `undefined` until the first snapshot arrives, which is what suspends readers. */
+  comments?: Record<string, StoredComment>
+  error?: unknown
+  subscribers: string[]
+}
+
+export interface CommentsStoreState {
+  entries: {[key: string]: CommentsEntry | undefined}
+  /** Comment creates that have not been confirmed by the server yet. */
+  pendingCreates: {[commentId: string]: true | undefined}
+  /**
+   * The most recent transaction this client started per comment, held only
+   * while the write is in flight.
+   *
+   * The listener echoes our own writes back. Without this, an echo from an
+   * earlier transaction could arrive after a later one and undo it on screen.
+   * Cleared as soon as the write settles: applying our own echo after that is
+   * harmless, because it carries the same data we already show.
+   */
+  pendingTransactions: {[commentId: string]: string | undefined}
+  error?: unknown
+}
+
+export interface CommentsKeyParts {
+  documentId: string
+  documentVersionId?: string
+}
+
+export function getCommentsKey({documentId, documentVersionId}: CommentsKeyParts): string {
+  return JSON.stringify([documentId, documentVersionId ?? null])
+}
+
+export function parseCommentsKey(key: string): CommentsKeyParts {
+  const [documentId, documentVersionId] = JSON.parse(key) as [string, string | null]
+  return {documentId, ...(documentVersionId ? {documentVersionId} : {})}
+}
+
+export const addSubscriber =
+  (key: string, subscriptionId: string) =>
+  (prev: CommentsStoreState): CommentsStoreState => {
+    const entry = prev.entries[key]
+    const subscribers = [...(entry?.subscribers ?? []), subscriptionId]
+    return {...prev, entries: {...prev.entries, [key]: {...entry, subscribers}}}
+  }
+
+export const removeSubscriber =
+  (key: string, subscriptionId: string) =>
+  (prev: CommentsStoreState): CommentsStoreState => {
+    const entry = prev.entries[key]
+    if (!entry) return prev
+    const subscribers = entry.subscribers.filter((id) => id !== subscriptionId)
+    if (!subscribers.length) {
+      const pendingCreates = {...prev.pendingCreates}
+      const pendingTransactions = {...prev.pendingTransactions}
+
+      for (const commentId of Object.keys(entry.comments ?? {})) {
+        delete pendingCreates[commentId]
+        delete pendingTransactions[commentId]
+      }
+
+      return {
+        ...prev,
+        entries: omitProperty(prev.entries, key),
+        pendingCreates,
+        pendingTransactions,
+      }
+    }
+    return {...prev, entries: {...prev.entries, [key]: {...entry, subscribers}}}
+  }
+
+/** Replaces an entry's contents with a freshly fetched snapshot. */
+export const setComments =
+  (key: string, comments: StoredComment[]) =>
+  (prev: CommentsStoreState): CommentsStoreState => {
+    const entry = prev.entries[key]
+    if (!entry) return prev
+    const byId = Object.fromEntries(comments.map((comment) => [comment._id, comment]))
+    const pendingCreates = {...prev.pendingCreates}
+
+    for (const [commentId, localComment] of Object.entries(entry.comments ?? {})) {
+      if (Object.hasOwn(byId, commentId)) {
+        delete pendingCreates[commentId]
+      } else if (Object.hasOwn(pendingCreates, commentId) || localComment._state) {
+        // A snapshot can race an in-flight create. Failed creates are also local
+        // drafts and must remain available for retry.
+        byId[commentId] = localComment
+      }
+    }
+
+    return {
+      ...prev,
+      entries: {...prev.entries, [key]: {...entry, comments: byId, error: undefined}},
+      pendingCreates,
+    }
+  }
+
+export const setCommentsError =
+  (key: string, error: unknown) =>
+  (prev: CommentsStoreState): CommentsStoreState => {
+    const entry = prev.entries[key]
+    if (!entry) return prev
+    return {...prev, entries: {...prev.entries, [key]: {...entry, error}}}
+  }
+
+/** A comment as it arrived from the server, replacing whatever we held. */
+export const receiveComment =
+  (key: string, comment: StoredComment) =>
+  (prev: CommentsStoreState): CommentsStoreState => {
+    const entry = prev.entries[key]
+    const pendingCreates = omitProperty(prev.pendingCreates, comment._id)
+    if (!entry) return {...prev, pendingCreates}
+    return {
+      ...prev,
+      pendingCreates,
+      entries: {
+        ...prev.entries,
+        [key]: {...entry, comments: {...entry.comments, [comment._id]: comment}},
+      },
+    }
+  }
+
+/**
+ * A comment we just wrote, shown before the server confirms it.
+ *
+ * `_createdAt` is assigned by the server, but the list sorts on it, so an
+ * optimistic comment needs a stand-in until the real value arrives.
+ */
+type OptimisticComment = CommentPostPayload & {_createdAt?: string; _rev?: string}
+
+/** A create that already failed once is being retried, not written fresh. */
+function isRetryingCreate(existing: StoredComment | undefined): boolean {
+  const state = existing?._state?.type
+  return state === 'createError' || state === 'createRetrying'
+}
+
+function mergeOptimisticComment(
+  existing: StoredComment | undefined,
+  comment: OptimisticComment,
+): StoredComment {
+  return {
+    ...existing,
+    ...comment,
+    _createdAt: comment._createdAt ?? existing?._createdAt ?? new Date().toISOString(),
+    _rev: comment._rev ?? existing?._rev ?? '',
+    ...(isRetryingCreate(existing) ? {_state: {type: 'createRetrying'} as const} : {}),
+  }
+}
+
+export const addComment =
+  (key: string, comment: OptimisticComment) =>
+  (prev: CommentsStoreState): CommentsStoreState => {
+    const entry = prev.entries[key]
+    if (!entry) return prev
+
+    const existing =
+      entry.comments && Object.hasOwn(entry.comments, comment._id)
+        ? entry.comments[comment._id]
+        : undefined
+
+    return {
+      ...prev,
+      pendingCreates: {...prev.pendingCreates, [comment._id]: true},
+      entries: {
+        ...prev.entries,
+        [key]: {
+          ...entry,
+          comments: {
+            ...entry.comments,
+            [comment._id]: mergeOptimisticComment(existing, comment),
+          },
+        },
+      },
+    }
+  }
+
+/**
+ * Merges a partial update into whichever entry holds the comment.
+ *
+ * Comment ids are unique, so this touches one entry in practice. Searching by
+ * id rather than taking a key means callers editing a comment do not have to
+ * say which document it belongs to.
+ */
+export const applyCommentUpdate =
+  (commentId: string, patch: Partial<StoredComment>) =>
+  (prev: CommentsStoreState): CommentsStoreState => {
+    const entries = {...prev.entries}
+    let changed = false
+
+    for (const [key, entry] of Object.entries(prev.entries)) {
+      const comment = entry?.comments?.[commentId]
+      if (!entry || !comment) continue
+      changed = true
+      entries[key] = {
+        ...entry,
+        comments: {...entry.comments, [commentId]: {...comment, ...patch}},
+      }
+    }
+
+    return changed ? {...prev, entries} : prev
+  }
+
+/** Removes a comment and, when it is a thread parent, its replies. */
+export const removeCommentById =
+  (commentId: string) =>
+  (prev: CommentsStoreState): CommentsStoreState => {
+    const entries = {...prev.entries}
+    const removedIds = new Set<string>()
+    let changed = false
+
+    for (const [key, entry] of Object.entries(prev.entries)) {
+      if (!entry?.comments) continue
+
+      const remaining = Object.fromEntries(
+        Object.entries(entry.comments).filter(([id, comment]) => {
+          const keep = id !== commentId && comment.parentCommentId !== commentId
+          if (!keep) removedIds.add(id)
+          return keep
+        }),
+      )
+
+      if (Object.keys(remaining).length === Object.keys(entry.comments).length) continue
+
+      changed = true
+      entries[key] = {...entry, comments: remaining}
+    }
+
+    if (!changed) return prev
+
+    const pendingCreates = {...prev.pendingCreates}
+    const pendingTransactions = {...prev.pendingTransactions}
+    for (const id of removedIds) {
+      delete pendingCreates[id]
+      delete pendingTransactions[id]
+    }
+
+    return {...prev, entries, pendingCreates, pendingTransactions}
+  }
+
+export const setPendingTransaction =
+  (commentId: string, transactionId: string) =>
+  (prev: CommentsStoreState): CommentsStoreState => ({
+    ...prev,
+    pendingTransactions: {...prev.pendingTransactions, [commentId]: transactionId},
+  })
+
+export const clearPendingTransaction =
+  (commentId: string) =>
+  (prev: CommentsStoreState): CommentsStoreState => ({
+    ...prev,
+    pendingTransactions: omitProperty(prev.pendingTransactions, commentId),
+  })
+
+/** Marks a pending create as failed, unless another request already confirmed it. */
+export const setCommentCreateError =
+  (commentId: string, error: Error) =>
+  (prev: CommentsStoreState): CommentsStoreState => {
+    if (!Object.hasOwn(prev.pendingCreates, commentId)) return prev
+    const next = applyCommentUpdate(commentId, {_state: {type: 'createError', error}})(prev)
+    return {...next, pendingCreates: omitProperty(next.pendingCreates, commentId)}
+  }
+
+/** Restores an optimistic edit if the failed transaction is still current. */
+export const rollbackCommentUpdate =
+  (commentId: string, transactionId: string, previous: StoredComment) =>
+  (prev: CommentsStoreState): CommentsStoreState => {
+    if (
+      !Object.hasOwn(prev.pendingTransactions, commentId) ||
+      prev.pendingTransactions[commentId] !== transactionId
+    ) {
+      return prev
+    }
+
+    const entries = Object.fromEntries(
+      Object.entries(prev.entries).map(([key, entry]) => {
+        if (!entry?.comments?.[commentId]) return [key, entry]
+        return [key, {...entry, comments: {...entry.comments, [commentId]: previous}}]
+      }),
+    )
+
+    return {
+      ...prev,
+      entries,
+      pendingTransactions: omitProperty(prev.pendingTransactions, commentId),
+    }
+  }
+
+/** Restores comments removed optimistically when the server delete fails. */
+export const restoreComments =
+  (removed: Array<{key: string; comments: StoredComment[]}>) =>
+  (prev: CommentsStoreState): CommentsStoreState => {
+    const entries = {...prev.entries}
+    let changed = false
+
+    for (const {key, comments} of removed) {
+      const entry = entries[key]
+      if (!entry) continue
+      const missing = comments.filter(
+        (comment) => !Object.hasOwn(entry.comments ?? {}, comment._id),
+      )
+      if (!missing.length) continue
+      changed = true
+      entries[key] = {
+        ...entry,
+        comments: Object.fromEntries([
+          ...Object.entries(entry.comments ?? {}),
+          ...missing.map((comment) => [comment._id, comment] as const),
+        ]),
+      }
+    }
+
+    return changed ? {...prev, entries} : prev
+  }

package/src/comments/types.ts

@@ -0,0 +1,249 @@
+import {type PortableTextBlock} from '@sanity/types'
+
+/**
+ * Whether a thread is still being discussed or has been closed out.
+ * @beta
+ */
+export type CommentStatus = 'open' | 'resolved'
+
+/**
+ * The body of a comment, as Portable Text.
+ *
+ * Mentions appear here as inline objects of type `mention` carrying a `userId`.
+ * The SDK stores and returns them untouched, so a mention written in the Studio
+ * survives a round trip, but there is no API for composing one yet.
+ * @beta
+ */
+export type CommentMessage = PortableTextBlock[] | null
+
+/**
+ * One block touched by a text selection, and that block's text with the
+ * selection boundaries marked.
+ *
+ * `text` is the block's *entire* plain text with two private-use sentinel
+ * characters (U+F000 and U+F001) inserted where the selection starts and ends.
+ * Storing marked-up text rather than character offsets is what lets a highlight
+ * survive edits elsewhere in the same block.
+ * @beta
+ */
+export interface CommentTextSelectionItem {
+  _key: string
+  text: string
+}
+
+/**
+ * A comment anchored to a run of text inside a Portable Text field.
+ *
+ * The SDK passes this through untouched. Resolving it back to a position in a
+ * live editor needs the editor's current value, so that lives in
+ * `@portabletext/plugin-sdk-value` rather than here.
+ * @beta
+ */
+export interface CommentTextSelection {
+  type: 'text'
+  value: CommentTextSelectionItem[]
+}
+
+/**
+ * An emoji reaction on a comment.
+ *
+ * Read only for now: a reaction added in the Studio shows up here, but there is
+ * no action for adding or removing one.
+ * @beta
+ */
+export interface CommentReaction {
+  shortName: string
+  userId: string
+  addedAt: string
+}
+
+/**
+ * Why a comment is not yet on the server.
+ *
+ * Local only, never written. Present on a comment whose create request failed,
+ * so an app can offer a retry.
+ * @beta
+ */
+export type CommentLocalState = {type: 'createError'; error: Error} | {type: 'createRetrying'}
+
+/**
+ * A single comment.
+ *
+ * Deliberately not the stored document. Comments are moving from per-dataset
+ * addon datasets to an organization-level store, and the two disagree on the
+ * document type, on how the commented document is referenced, and on where the
+ * author is recorded. Everything here reads the same on both sides, so an app
+ * written against this survives the move.
+ *
+ * Threads are flat: every comment in a thread shares a `threadId`, the thread's
+ * first comment has no `parentCommentId`, and replies carry that first comment's
+ * `id`. Use {@link CommentThread} to work with them grouped.
+ *
+ * @beta
+ */
+export interface Comment {
+  id: string
+  createdAt: string
+  /**
+   * Who wrote it.
+   *
+   * Absent when the server carries the author instead of the document. The
+   * Studio's comments dataset stores it on the document, so it is present on
+   * everything written today, but an agent-authored comment records
+   * attribution elsewhere. Render a fallback rather than assuming a user id.
+   */
+  authorId?: string
+  message: CommentMessage
+  threadId: string
+  /** Absent on the comment that starts a thread. */
+  parentCommentId?: string
+  status: CommentStatus
+  /** Set once the message has been rewritten. */
+  lastEditedAt?: string
+  /** The document the thread hangs on, always the published id. */
+  documentId: string
+  documentType: string
+  /** The field the thread hangs off, for example `title`. */
+  fieldPath: string
+  /** Set when the comment is anchored to a run of text in a Portable Text field. */
+  selection?: CommentTextSelection
+  /** A copy of the content the comment was written about. */
+  contentSnapshot?: unknown
+  reactions: CommentReaction[]
+  /** Local only. Present while a create is failing or being retried. */
+  state?: CommentLocalState
+}
+
+/**
+ * A thread: one comment plus its replies.
+ *
+ * Unlike the Studio, the SDK returns every thread it finds. The Studio hides
+ * threads whose field is gone from the schema or hidden by a conditional, which
+ * it can do because it has the schema. Check `fieldPath` yourself if your app
+ * needs the same behaviour.
+ * @beta
+ */
+export interface CommentThread {
+  threadId: string
+  /** The field the thread hangs off, taken from its first comment. */
+  fieldPath: string
+  parentComment: Comment
+  /** Oldest first. */
+  replies: Comment[]
+  /** The parent plus its replies. */
+  commentsCount: number
+  /** Taken from the parent comment; replies follow it. */
+  status: CommentStatus
+  /** `createdAt` of the most recent comment in the thread. */
+  lastActivityAt: string
+}
+
+/**
+ * Where in a document a thread hangs, as stored.
+ * @internal
+ */
+interface StoredCommentPath {
+  field: string
+  selection?: CommentTextSelection
+}
+
+/**
+ * Ambient information the Studio records about where a comment was written.
+ *
+ * Written for the notification backend and read by nothing in the Studio UI.
+ * Not surfaced on {@link Comment}: the organization-level store types this as a
+ * free-form object, so nothing about the shape is worth promising.
+ *
+ * @internal
+ */
+interface StoredCommentContext {
+  tool: string
+  payload?: Record<string, unknown>
+  notification?: {
+    documentTitle: string
+    url?: string
+    workspaceTitle: string
+    workspaceName: string
+    currentThreadLength?: number
+    subscribers?: string[]
+  }
+  intent?: {
+    title: string
+    name: string
+    params: Record<string, unknown>
+  }
+}
+
+/**
+ * A reaction as stored, including the array key.
+ * @internal
+ */
+interface StoredCommentReaction extends CommentReaction {
+  _key: string
+}
+
+/**
+ * What a stored comment points at.
+ *
+ * Comments live in a separate addon dataset, so `document` is a
+ * `crossDatasetReference` back into the dataset holding the commented document.
+ * It is deliberately weak: a strong reference would stop Content Lake deleting
+ * the document it points at.
+ *
+ * @internal
+ */
+interface StoredCommentTarget {
+  path?: StoredCommentPath
+  documentRevisionId?: string
+  documentVersionId?: string
+  documentType: string
+  document:
+    | {
+        _dataset: string
+        _projectId: string
+        _ref: string
+        _type: 'crossDatasetReference'
+        _weak: boolean
+      }
+    | {
+        _ref: string
+        _type: 'reference'
+        _weak: boolean
+      }
+}
+
+/**
+ * A comment exactly as the Studio stores it.
+ *
+ * Internal on purpose. This is the addon dataset's shape, and it changes when
+ * comments move to the organization-level store. {@link Comment} is what
+ * consumers get.
+ *
+ * @internal
+ */
+export interface StoredComment {
+  _type: 'comment'
+  _id: string
+  _createdAt: string
+  _rev: string
+
+  /** Local only. Never written to the server. */
+  _state?: CommentLocalState
+
+  authorId: string
+  message: CommentMessage
+  threadId: string
+  parentCommentId?: string
+  status: CommentStatus
+  lastEditedAt?: string
+  reactions: StoredCommentReaction[] | null
+  context?: StoredCommentContext
+  contentSnapshot?: unknown
+  target: StoredCommentTarget
+}
+
+/**
+ * What gets written when a comment is created.
+ * @internal
+ */
+export type CommentPostPayload = Omit<StoredComment, '_rev' | '_createdAt' | '_state'>

package/src/comments/weakenReferences.test.ts

@@ -0,0 +1,47 @@
+import {describe, expect, it} from 'vitest'
+
+import {weakenReferencesInContentSnapshot} from './weakenReferences'
+
+describe('weakenReferencesInContentSnapshot', () => {
+  it('weakens a reference at the top level', () => {
+    expect(weakenReferencesInContentSnapshot({_ref: 'abc', _type: 'reference'})).toEqual({
+      _ref: 'abc',
+      _type: 'reference',
+      _weak: true,
+    })
+  })
+
+  it('weakens references nested in objects and arrays', () => {
+    expect(
+      weakenReferencesInContentSnapshot({
+        title: 'foo',
+        author: {_ref: 'bar', _type: 'reference'},
+        blocks: [{_key: 'a', tag: {_ref: 'baz', _type: 'reference'}}],
+      }),
+    ).toEqual({
+      title: 'foo',
+      author: {_ref: 'bar', _type: 'reference', _weak: true},
+      blocks: [{_key: 'a', tag: {_ref: 'baz', _type: 'reference', _weak: true}}],
+    })
+  })
+
+  it('leaves an already weak reference weak', () => {
+    expect(weakenReferencesInContentSnapshot({_ref: 'abc', _weak: true})).toEqual({
+      _ref: 'abc',
+      _weak: true,
+    })
+  })
+
+  it('passes primitives and null through', () => {
+    expect(weakenReferencesInContentSnapshot('foo')).toBe('foo')
+    expect(weakenReferencesInContentSnapshot(42)).toBe(42)
+    expect(weakenReferencesInContentSnapshot(null)).toBe(null)
+    expect(weakenReferencesInContentSnapshot(undefined)).toBe(undefined)
+  })
+
+  it('does not mutate its input', () => {
+    const snapshot = {author: {_ref: 'bar'}}
+    weakenReferencesInContentSnapshot(snapshot)
+    expect(snapshot).toEqual({author: {_ref: 'bar'}})
+  })
+})

package/src/comments/weakenReferences.ts

@@ -0,0 +1,29 @@
+function weaken(node: unknown): unknown {
+  if (Array.isArray(node)) {
+    return node.map(weaken)
+  }
+
+  if (node && typeof node === 'object') {
+    if ('_ref' in node) {
+      return {...node, _weak: true}
+    }
+
+    return Object.fromEntries(Object.entries(node).map(([key, value]) => [key, weaken(value)]))
+  }
+
+  return node
+}
+
+/**
+ * Marks every reference in a content snapshot weak.
+ *
+ * A comment's snapshot is written into the addon dataset, but its references
+ * point at documents in the main one. Left strong, Content Lake would refuse to
+ * delete any document a snapshot happens to mention, so an old comment could
+ * pin a document forever.
+ *
+ * @internal
+ */
+export function weakenReferencesInContentSnapshot(snapshot: unknown): unknown {
+  return weaken(snapshot)
+}

package/src/document/documentConstants.ts

@@ -15,3 +15,11 @@ export const API_VERSION = 'v2025-05-06'
  */
 export const OUT_OF_SYNC_RETRY_BASE_DELAY = 500
 export const OUT_OF_SYNC_RETRY_MAX_DELAY = 10_000
+
+/**
+ * Base delay (ms) before retrying the dataset ACL fetch after a transient
+ * failure (a network error or 5xx response). Backoff doubles on each
+ * successive retry, capped at {@link ACL_RETRY_MAX_DELAY}.
+ */
+export const ACL_RETRY_BASE_DELAY = 500
+export const ACL_RETRY_MAX_DELAY = 10_000