@sanity/client 8.6.2 → 8.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanity/client",
-  "version": "8.6.2",
+  "version": "8.8.0",
   "description": "Client for retrieving, creating and patching data from Sanity.io",
   "keywords": [
     "api",
@@ -43,14 +43,15 @@
       },
       "default": "./dist/index.js"
     },
+    "./collaboration": "./dist/collaboration.js",
     "./csm": "./dist/csm.js",
     "./stega": "./dist/stega.js",
     "./media-library": "./dist/media-library.js",
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "eventsource": "^5.1.1",
-    "get-it": "^9.5.4",
+    "eventsource": "^5.1.2",
+    "get-it": "^9.5.7",
     "obug": "^3.0.0",
     "rxjs": "^7.8.2"
   },

package/src/collaboration/comments.ts

@@ -1,7 +1,7 @@
-import {getPublishedId} from '@sanity/client/csm'
 import {type Observable, throwError} from 'rxjs'
 import {map} from 'rxjs/operators'
 
+import {version} from '../../package.json'
 import {_requestObservable, getQuerySizeLimit} from '../data/dataMethods'
 import {encodeQueryString} from '../data/encodeQueryString'
 import {
@@ -21,9 +21,13 @@ import type {
 } from '../types'
 import defaults from '../util/defaults'
 import {pick} from '../util/pick'
+import {type CommentResource, getCommentTargetDocumentRef} from './getCommentTargetDocumentRef'
 import {
+  type CollaborationCommentAnchor,
   type CollaborationCommentCreate,
   type CollaborationCommentDocument,
+  type CollaborationCommentFieldValue,
+  type CollaborationCommentRange,
   type CollaborationCommentReactionShortName,
   type CollaborationCommentsListenOptions,
   type CollaborationCommentsRequestOptions,
@@ -42,7 +46,7 @@ function commentUrl(id: string): string {
   return `/collaboration/comments/${encodeURIComponent(id)}`
 }
 
-function resolveCommentResource(client: Client): {type: string; id: string} {
+function resolveCommentResource(client: Client): CommentResource {
   const {resource, projectId, dataset} = client.config()
 
   if (resource) {
@@ -86,9 +90,7 @@ export function _getTargetDocumentRef(
     throw new Error('Document ID must be provided')
   }
 
-  const resource = resolveCommentResource(client)
-
-  return `${resource.type}:${resource.id}:${getPublishedId(documentId)}`
+  return getCommentTargetDocumentRef(resolveCommentResource(client), documentId)
 }
 
 type WriteArgs = [
@@ -133,6 +135,8 @@ function write<T>(
     body,
     query: {
       ...resourceQuery(client),
+      // Records the client version for telemetry (writes only).
+      clientVersion: version,
       ...(options.transactionId ? {transactionId: options.transactionId} : {}),
     },
     ...pick(options, possibleRequestOptions),
@@ -170,6 +174,25 @@ function writeMutationResult(...args: WriteArgs): Observable<MultipleMutationRes
   )
 }
 
+/**
+ * Moves the deprecated `range` + `fieldValue` onto a `portable-text` `anchor`.
+ * Anything else passes through unchanged, and invalid combinations are left
+ * for the API to reject.
+ */
+function withAnchor(input: {
+  anchor?: CollaborationCommentAnchor | null
+  range?: CollaborationCommentRange | null
+  fieldValue?: CollaborationCommentFieldValue
+}) {
+  const {range, fieldValue, ...rest} = input
+
+  if (range === undefined || input.anchor !== undefined) return input
+
+  if (range === null) return fieldValue ? input : {...rest, anchor: null}
+
+  return {...rest, anchor: {type: 'portable-text', ...range, ...(fieldValue && {fieldValue})}}
+}
+
 /** @internal */
 export function _create(
   client: Client,
@@ -183,7 +206,7 @@ export function _create(
     httpRequest,
     'POST',
     '/collaboration/comments',
-    body,
+    body.target ? {...body, target: withAnchor(body.target)} : body,
     options,
   )
 }
@@ -196,7 +219,7 @@ export function _update(
   body: CollaborationCommentUpdate,
   options?: CollaborationCommentsWriteOptions,
 ): Observable<CollaborationCommentDocument> {
-  return writeDocument(id, client, httpRequest, 'PATCH', commentUrl(id), body, options)
+  return writeDocument(id, client, httpRequest, 'PATCH', commentUrl(id), withAnchor(body), options)
 }
 
 /** @internal */

package/src/collaboration/getCommentTargetDocumentRef.ts

@@ -0,0 +1,45 @@
+import {getPublishedId} from '@sanity/client/csm'
+
+import type {ClientConfig} from '../types'
+import type {CollaborationCommentDocument} from './types'
+
+/**
+ * The resource comments are stored against: one of the client's resource configurations.
+ *
+ * @internal
+ */
+export type CommentResource = NonNullable<ClientConfig['resource']>
+
+/**
+ * Build the global document reference a comment stores in `target.document._ref`,
+ * without a client.
+ *
+ * `client.collaboration.comments.getTargetDocumentRef` reads the resource off the
+ * client's configuration and calls this. Use this directly when the resource is
+ * already at hand and no client should be involved, for example inside a state
+ * selector that has to stay free of side effects.
+ *
+ * The reference always names the published document: a draft or version ID is
+ * reduced to its published form first.
+ *
+ * @example
+ * ```ts
+ * getCommentTargetDocumentRef({type: 'dataset', id: 'abc123.production'}, 'drafts.doc-1')
+ * // 'dataset:abc123.production:doc-1'
+ * ```
+ *
+ * @param resource - The resource the comments are stored against, as `ClientConfig['resource']` takes it
+ * @param documentId - Document ID, in published, draft or version form
+ * @returns Global document reference, of the form `resourceType:resourceId:documentId`
+ * @alpha
+ */
+export function getCommentTargetDocumentRef(
+  resource: CommentResource,
+  documentId: string,
+): CollaborationCommentDocument['target']['document']['_ref'] {
+  if (!documentId) {
+    throw new Error('Document ID must be provided')
+  }
+
+  return `${resource.type}:${resource.id}:${getPublishedId(documentId)}`
+}

package/src/collaboration/index.ts

@@ -0,0 +1 @@
+export {getCommentTargetDocumentRef} from './getCommentTargetDocumentRef'

package/src/collaboration/types.ts

@@ -154,6 +154,7 @@ export interface CollaborationCommentDocument extends SanityDocument {
  * Each endpoint pairs the `_key` of a Portable Text block with a character
  * offset into that block's plain text.
  *
+ * @deprecated Use {@link CollaborationCommentAnchor}.
  * @alpha
  */
 export interface CollaborationCommentRange {
@@ -162,8 +163,8 @@ export interface CollaborationCommentRange {
 }
 
 /**
- * Portable Text covering a comment `range`. Callers can send just the blocks
- * from the `range` start `_key` through end `_key`, or the full field.
+ * Portable Text covering an inline comment anchor. Callers can send just the
+ * blocks from the anchor start `_key` through end `_key`, or the full field.
  *
  * @alpha
  */
@@ -173,16 +174,33 @@ export type CollaborationCommentFieldValue = Array<{
   [key: string]: Any
 }>
 
+/**
+ * Where in `path` a comment is anchored.
+ *
+ * For `portable-text`, each endpoint pairs the `_key` of a Portable Text
+ * block with a character offset into that block's plain text. An optional
+ * `fieldValue` is Portable Text covering the anchor. When set, the selection
+ * is resolved from those blocks instead of from the live document.
+ *
+ * @alpha
+ */
+export type CollaborationCommentAnchor = {
+  type: 'portable-text'
+  start: {_key: string; offset: number}
+  end: {_key: string; offset: number}
+  fieldValue?: CollaborationCommentFieldValue
+}
+
 /**
  * Target for a top-level comment. Inline selections require both `path` and
- * `range`; field-level comments may set `path` alone.
+ * `anchor`; field-level comments may set `path` alone.
  *
  * The created comment stores this in a different shape: `path` becomes
- * `target.path.field`, and `range` is resolved against the document into
+ * `target.path.field`, and `anchor` is resolved against the document into
  * `target.path.selection` and `contentSnapshot` rather than being stored.
  *
- * An optional `fieldValue` is Portable Text covering the `range`. When set,
- * the `range` is resolved from those blocks instead of from the live document.
+ * Deprecated `range` + top-level `fieldValue` are still accepted and converted
+ * to a `portable-text` `anchor` before the request is sent.
  *
  * @alpha
  */
@@ -194,17 +212,43 @@ export type CollaborationCommentTarget = {
   | {
       /** Path to the field containing the inline comment selection */
       path: string
+      anchor: CollaborationCommentAnchor
+      /**
+       * @deprecated Use `anchor`.
+       */
+      range?: never
+      /**
+       * @deprecated Use `anchor.fieldValue`.
+       */
+      fieldValue?: never
+    }
+  | {
+      /** Path to the field containing the inline comment selection */
+      path: string
+      /**
+       * @deprecated Use `anchor`.
+       */
       range: CollaborationCommentRange
       /**
-       * Portable Text covering the `range`. When set, the `range` is resolved
+       * Portable Text covering the `range`. When set, the selection is resolved
        * from these blocks instead of from the live document.
+       *
+       * @deprecated Use `anchor.fieldValue`.
        */
       fieldValue?: CollaborationCommentFieldValue
+      anchor?: never
     }
   | {
       /** Path to the commented field */
       path?: string
+      anchor?: never
+      /**
+       * @deprecated Use `anchor`.
+       */
       range?: never
+      /**
+       * @deprecated Use `anchor.fieldValue`.
+       */
       fieldValue?: never
     }
 )
@@ -234,7 +278,11 @@ export type CollaborationCommentTarget = {
  *     documentId: 'doc-1',
  *     documentType: 'article',
  *     path: 'body',
- *     range: {start: {_key: 'block-1', offset: 0}, end: {_key: 'block-1', offset: 5}},
+ *     anchor: {
+ *       type: 'portable-text',
+ *       start: {_key: 'block-1', offset: 0},
+ *       end: {_key: 'block-1', offset: 5},
+ *     },
  *   },
  * })
  * ```
@@ -270,11 +318,13 @@ export type CollaborationCommentCreate = {
 /**
  * Fields that can be updated on an existing comment.
  *
- * A `range` re-anchors the comment within the field it already targets.
+ * An `anchor` re-anchors the comment within the field it already targets.
  * Pass `null` to remove the selection and leave a field-level comment.
- * An optional `fieldValue` is Portable Text covering that `range`; when set,
- * the `range` is resolved from those blocks instead of from the live document.
- * `fieldValue` cannot be sent alone or together with `range: null`.
+ * An optional `fieldValue` on a `portable-text` anchor is resolved from those
+ * blocks instead of from the live document.
+ *
+ * Deprecated `range` + top-level `fieldValue` (and `range: null`) are still
+ * accepted and converted to `anchor` before the request is sent.
  *
  * @alpha
  */
@@ -285,19 +335,61 @@ export type CollaborationCommentUpdate = {
   status?: CollaborationCommentStatus
 } & (
   | {
+      anchor: CollaborationCommentAnchor
+      /**
+       * @deprecated Use `anchor`.
+       */
+      range?: never
+      /**
+       * @deprecated Use `anchor.fieldValue`.
+       */
+      fieldValue?: never
+    }
+  | {
+      anchor: null
+      /**
+       * @deprecated Use `anchor`.
+       */
+      range?: never
+      /**
+       * @deprecated Use `anchor.fieldValue`.
+       */
+      fieldValue?: never
+    }
+  | {
+      /**
+       * @deprecated Use `anchor`.
+       */
       range: CollaborationCommentRange
       /**
-       * Portable Text covering the `range`. When set, the `range` is resolved
+       * Portable Text covering the `range`. When set, the selection is resolved
        * from these blocks instead of from the live document.
+       *
+       * @deprecated Use `anchor.fieldValue`.
        */
       fieldValue?: CollaborationCommentFieldValue
+      anchor?: never
     }
   | {
+      /**
+       * @deprecated Use `anchor: null`.
+       */
       range: null
+      /**
+       * @deprecated Use `anchor.fieldValue`.
+       */
       fieldValue?: never
+      anchor?: never
     }
   | {
+      anchor?: undefined
+      /**
+       * @deprecated Use `anchor`.
+       */
       range?: undefined
+      /**
+       * @deprecated Use `anchor.fieldValue`.
+       */
       fieldValue?: never
     }
 )