@sanity/client 8.1.0 → 8.2.0

package/src/collaboration/comments.ts

@@ -0,0 +1,313 @@
+import {getPublishedId} from '@sanity/client/csm'
+import {type Observable, throwError} from 'rxjs'
+import {map} from 'rxjs/operators'
+
+import {_requestObservable, getQuerySizeLimit} from '../data/dataMethods'
+import {encodeQueryString} from '../data/encodeQueryString'
+import {
+  _connectListenEventSource,
+  defaultOptions as defaultListenOptions,
+  type ListenEventFromOptions,
+  MAX_URL_LENGTH,
+  possibleOptions as possibleListenOptions,
+} from '../data/listen'
+import type {ObservableSanityClient, SanityClient} from '../SanityClient'
+import type {
+  HttpRequest,
+  MultipleMutationResult,
+  MutationOperation,
+  QueryParams,
+  ResumableListenEventNames,
+} from '../types'
+import defaults from '../util/defaults'
+import {pick} from '../util/pick'
+import {
+  type CollaborationCommentCreate,
+  type CollaborationCommentDocument,
+  type CollaborationCommentReactionShortName,
+  type CollaborationCommentsListenOptions,
+  type CollaborationCommentsRequestOptions,
+  type CollaborationCommentsWriteOptions,
+  type CollaborationCommentUpdate,
+  possibleRequestOptions,
+} from './types'
+
+type Client = SanityClient | ObservableSanityClient
+
+function commentUrl(id: string): string {
+  if (!id) {
+    throw new Error('Comment ID must be provided')
+  }
+
+  return `/collaboration/comments/${encodeURIComponent(id)}`
+}
+
+function resolveCommentResource(client: Client): {type: string; id: string} {
+  const {resource, projectId, dataset} = client.config()
+
+  if (resource) {
+    return resource
+  }
+
+  if (projectId && dataset) {
+    return {type: 'dataset', id: `${projectId}.${dataset}`}
+  }
+
+  throw new Error(
+    '`resource` or `projectId` and `dataset` must be configured to use collaboration comments',
+  )
+}
+
+function resourceQuery(client: Client): Record<string, string> {
+  const {collaboration} = client.config()
+  const organizationId = collaboration?.organizationId
+
+  if (!organizationId) {
+    throw new Error(
+      '`collaboration.organizationId` must be configured to use collaboration comments',
+    )
+  }
+
+  const resource = resolveCommentResource(client)
+
+  return {
+    organizationId,
+    resourceId: resource.id,
+    resourceType: resource.type,
+  }
+}
+
+/** @internal */
+export function _getTargetDocumentRef(
+  client: Client,
+  documentId: string,
+): CollaborationCommentDocument['target']['document']['_ref'] {
+  if (!documentId) {
+    throw new Error('Document ID must be provided')
+  }
+
+  const resource = resolveCommentResource(client)
+
+  return `${resource.type}:${resource.id}:${getPublishedId(documentId)}`
+}
+
+type WriteArgs = [
+  client: Client,
+  httpRequest: HttpRequest,
+  method: 'POST' | 'PATCH' | 'DELETE',
+  url: string,
+  body: unknown,
+  options?: CollaborationCommentsWriteOptions,
+]
+
+/**
+ * The write endpoints pass the mutation response through as-is, mirroring
+ * `client.mutate`.
+ */
+interface CommentMutationResponse {
+  transactionId: string
+  results: {id: string; operation: MutationOperation}[]
+}
+
+/**
+ * Writes that return a comment come back with the document, since the API
+ * requests documents from the org store and 404s when nothing matched. A
+ * status update carries one result per cascaded reply on top of the comment
+ * itself.
+ */
+interface CommentDocumentMutationResponse extends CommentMutationResponse {
+  results: {id: string; operation: MutationOperation; document: CollaborationCommentDocument}[]
+}
+
+function write<T>(
+  client: Client,
+  httpRequest: HttpRequest,
+  method: 'POST' | 'PATCH' | 'DELETE',
+  url: string,
+  body: unknown,
+  options: CollaborationCommentsWriteOptions = {},
+): Observable<T> {
+  return _requestObservable<T>(client, httpRequest, {
+    method,
+    url,
+    body,
+    query: {
+      ...resourceQuery(client),
+      ...(options.transactionId ? {transactionId: options.transactionId} : {}),
+    },
+    ...pick(options, possibleRequestOptions),
+  })
+}
+
+/**
+ * `commentId` picks the written comment out of the results: a status update
+ * cascades to the comment's replies, and the API leaves the results unordered.
+ * Creates pass the requested `_id`, which is undefined when the API assigns
+ * one, and always come back with a single result.
+ */
+function writeDocument(
+  commentId: string | undefined,
+  ...args: WriteArgs
+): Observable<CollaborationCommentDocument> {
+  return write<CommentDocumentMutationResponse>(...args).pipe(
+    map(({results}) => {
+      const result = commentId ? results.find(({id}) => id === commentId) : results[0]
+      if (!result?.document) {
+        throw new Error('Comment write did not return a comment document')
+      }
+      return result.document
+    }),
+  )
+}
+
+function writeMutationResult(...args: WriteArgs): Observable<MultipleMutationResult> {
+  return write<CommentMutationResponse>(...args).pipe(
+    map(({transactionId, results}) => ({
+      transactionId,
+      documentIds: results.map((result) => result.id),
+      results,
+    })),
+  )
+}
+
+/** @internal */
+export function _create(
+  client: Client,
+  httpRequest: HttpRequest,
+  body: CollaborationCommentCreate,
+  options?: CollaborationCommentsWriteOptions,
+): Observable<CollaborationCommentDocument> {
+  return writeDocument(
+    body._id,
+    client,
+    httpRequest,
+    'POST',
+    '/collaboration/comments',
+    body,
+    options,
+  )
+}
+
+/** @internal */
+export function _update(
+  client: Client,
+  httpRequest: HttpRequest,
+  id: string,
+  body: CollaborationCommentUpdate,
+  options?: CollaborationCommentsWriteOptions,
+): Observable<CollaborationCommentDocument> {
+  return writeDocument(id, client, httpRequest, 'PATCH', commentUrl(id), body, options)
+}
+
+/** @internal */
+export function _delete(
+  client: Client,
+  httpRequest: HttpRequest,
+  id: string,
+  options?: CollaborationCommentsWriteOptions,
+): Observable<MultipleMutationResult> {
+  return writeMutationResult(client, httpRequest, 'DELETE', commentUrl(id), undefined, options)
+}
+
+/** @internal */
+export function _addReaction(
+  client: Client,
+  httpRequest: HttpRequest,
+  id: string,
+  shortName: CollaborationCommentReactionShortName,
+  options?: CollaborationCommentsWriteOptions,
+): Observable<CollaborationCommentDocument> {
+  return writeDocument(
+    id,
+    client,
+    httpRequest,
+    'POST',
+    `${commentUrl(id)}/reactions`,
+    {shortName},
+    options,
+  )
+}
+
+/** @internal */
+export function _removeReaction(
+  client: Client,
+  httpRequest: HttpRequest,
+  id: string,
+  shortName: CollaborationCommentReactionShortName,
+  options?: CollaborationCommentsWriteOptions,
+): Observable<CollaborationCommentDocument> {
+  return writeDocument(
+    id,
+    client,
+    httpRequest,
+    'DELETE',
+    `${commentUrl(id)}/reactions/${encodeURIComponent(shortName)}`,
+    undefined,
+    options,
+  )
+}
+
+/** @internal */
+export function _fetch<R>(
+  client: Client,
+  httpRequest: HttpRequest,
+  query: string,
+  params?: QueryParams,
+  options?: CollaborationCommentsRequestOptions,
+): Observable<R> {
+  const search = resourceQuery(client)
+
+  // Mirrors `client.fetch`: GET while the query fits in the URL, POST beyond that.
+  const useGet = encodeQueryString({query, params}).length < getQuerySizeLimit
+  const request = useGet
+    ? {
+        method: 'GET',
+        url: `/collaboration/comments/query${encodeQueryString({query, params, options: search})}`,
+      }
+    : {
+        method: 'POST',
+        url: '/collaboration/comments/query',
+        query: search,
+        body: {query, params: params ?? {}},
+      }
+
+  return _requestObservable<{result: R}>(client, httpRequest, {
+    ...request,
+    ...pick(options || {}, possibleRequestOptions),
+  }).pipe(map((response) => response.result))
+}
+
+/** @internal */
+export function _listen<
+  Opts extends CollaborationCommentsListenOptions = CollaborationCommentsListenOptions,
+>(
+  client: Client,
+  query: string,
+  params?: QueryParams,
+  options?: Opts,
+): Observable<ListenEventFromOptions<CollaborationCommentDocument, Opts>> {
+  const opts: CollaborationCommentsListenOptions = options ?? {}
+
+  // Mirrors `_listen` in data/listen.ts, but against the comments listen endpoint
+  const {requestTagPrefix} = client.config()
+  const tag = opts.tag && requestTagPrefix ? [requestTagPrefix, opts.tag].join('.') : opts.tag
+  const listenOpts = pick({...defaults(opts, defaultListenOptions), tag}, possibleListenOptions)
+  const qs = encodeQueryString({
+    query,
+    params,
+    options: {...listenOpts, ...resourceQuery(client)},
+  })
+
+  const uri = `${client.getUrl('/collaboration/comments/listen')}${qs}`
+  if (uri.length > MAX_URL_LENGTH) {
+    return throwError(() => new Error('Query too large for listener'))
+  }
+
+  const events: ResumableListenEventNames[] = opts.events ? opts.events : ['mutation']
+
+  return _connectListenEventSource<ListenEventFromOptions<CollaborationCommentDocument, Opts>>(
+    client,
+    uri,
+    events,
+  )
+}

package/src/collaboration/types.ts

@@ -0,0 +1,252 @@
+import type {
+  Any,
+  ListenOptions,
+  RequestOptions,
+  ResumableListenOptions,
+  SanityDocument,
+} from '../types'
+
+/** @internal */
+export const possibleRequestOptions = ['headers', 'signal', 'tag', 'timeout', 'token'] as const
+
+/**
+ * Request options honored by the collaboration comments methods.
+ *
+ * @alpha
+ */
+export type CollaborationCommentsRequestOptions = Pick<
+  RequestOptions,
+  (typeof possibleRequestOptions)[number]
+>
+
+/**
+ * Options for collaboration comments write methods.
+ *
+ * @alpha
+ */
+export type CollaborationCommentsWriteOptions = CollaborationCommentsRequestOptions & {
+  /** Transaction ID to associate the write with */
+  transactionId?: string
+}
+
+/**
+ * Listener options for `collaboration.comments.listen`.
+ *
+ * `includeAllVersions` is left out: comments are stored as `sanity.comment`
+ * documents with no drafts or versions, so it would never make a difference.
+ *
+ * @alpha
+ */
+export type CollaborationCommentsListenOptions =
+  | Omit<ListenOptions, 'includeAllVersions'>
+  | Omit<ResumableListenOptions, 'includeAllVersions'>
+
+/**
+ * Status of a comment thread. Replies always share the status of their parent comment.
+ *
+ * @alpha
+ */
+export type CollaborationCommentStatus = 'open' | 'resolved'
+
+/**
+ * Emoji short names that can be used as comment reactions.
+ *
+ * @alpha
+ */
+export type CollaborationCommentReactionShortName =
+  | ':-1:'
+  | ':+1:'
+  | ':eyes:'
+  | ':heart:'
+  | ':heavy_plus_sign:'
+  | ':rocket:'
+
+/**
+ * A single Portable Text block, as used in comment messages and content snapshots.
+ *
+ * @alpha
+ */
+export interface CollaborationCommentPortableTextBlock {
+  _type: string
+  children: Array<{_type: string; [key: string]: Any}>
+  [key: string]: Any
+}
+
+/**
+ * Comment message, as an array of Portable Text blocks.
+ *
+ * @alpha
+ */
+export type CollaborationCommentMessage = CollaborationCommentPortableTextBlock[]
+
+/**
+ * The text an inline comment was anchored to, resolved by the API when the
+ * comment was created.
+ *
+ * Holds one entry per Portable Text block the selection spans, keyed by the
+ * block it came from. `text` is the plain text of that block with the selected
+ * part wrapped in the marker characters `\uF000` (start) and `\uF001` (end).
+ *
+ * @alpha
+ */
+export interface CollaborationCommentSelection {
+  type: 'text'
+  value: {_key: string; text: string}[]
+}
+
+/**
+ * A comment document, as stored by the Comments API.
+ *
+ * @alpha
+ */
+export interface CollaborationCommentDocument extends SanityDocument {
+  _type: 'sanity.comment'
+  _system?: {
+    /** ID of the user that created the comment */
+    createdBy?: string
+  }
+  /** ID shared by a top-level comment and all of its replies */
+  threadId?: string
+  /** Set on replies, pointing to the comment being replied to */
+  parentCommentId?: string
+  message: CollaborationCommentMessage
+  reactions: {
+    _key: string
+    shortName: CollaborationCommentReactionShortName
+    userId: string
+    addedAt: string
+  }[]
+  /** Arbitrary metadata stored with the comment by the creating application */
+  context?: Record<string, unknown>
+  target: {
+    /** Global document reference (`resourceType:resourceId:documentId`, using the published document ID) */
+    document: {
+      _ref: `${string}:${string}:${string}`
+      _type: 'globalDocumentReference'
+      _weak: true
+    }
+    documentType: string
+    /** The exact document ID the comment was created against, e.g. a draft or version ID */
+    sourceDocumentId: string
+    documentRevisionId?: string
+    /**
+     * Set for field and inline comments. `field` is the `path` the comment was
+     * created with; `selection` is set for inline comments only.
+     */
+    path?: {
+      field: string
+      selection?: CollaborationCommentSelection
+    }
+  }
+  /**
+   * Copy of the commented content, as it looked when the comment was created.
+   * Set for inline comments only, and holds just the selected fragment of each
+   * Portable Text block the selection spans.
+   */
+  contentSnapshot?: CollaborationCommentPortableTextBlock[]
+  status: CollaborationCommentStatus
+  /** Set when the message has been updated after creation */
+  lastEditedAt?: string
+}
+
+/**
+ * Inline text selection within a Portable Text field.
+ * Each endpoint pairs the `_key` of a Portable Text block with a character
+ * offset into that block's plain text.
+ *
+ * @alpha
+ */
+export interface CollaborationCommentRange {
+  start: {_key: string; offset: number}
+  end: {_key: string; offset: number}
+}
+
+/**
+ * Target for a top-level comment. Inline selections require both `path` and
+ * `range`; 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.selection` and `contentSnapshot` rather than being stored.
+ *
+ * @alpha
+ */
+export type CollaborationCommentTarget = {
+  documentId: string
+  documentType: string
+  documentRevisionId?: string
+} & (
+  | {
+      /** Path to the field containing the inline comment selection */
+      path: string
+      range: CollaborationCommentRange
+    }
+  | {
+      /** Path to the commented field */
+      path?: string
+      range?: never
+    }
+)
+
+/**
+ * Comment to create with `collaboration.comments.create`.
+ *
+ * A top-level comment requires `target`; a reply requires `parentCommentId` (never both).
+ * Replies inherit `target`, `status`, and `threadId` from the parent comment.
+ *
+ * ### Examples
+ *
+ * #### Top-level comment
+ * ```ts
+ * // `message` is an array of Portable Text blocks
+ * await client.collaboration.comments.create({
+ *   message,
+ *   target: {documentId: 'doc-1', documentType: 'article'},
+ * })
+ * ```
+ *
+ * #### Reply
+ * ```ts
+ * await client.collaboration.comments.create({
+ *   message,
+ *   parentCommentId: 'comment-1',
+ * })
+ * ```
+ *
+ * @alpha
+ */
+export type CollaborationCommentCreate = {
+  /** Provide to control the ID of the created comment document */
+  _id?: string
+  message: CollaborationCommentMessage
+  context?: Record<string, unknown>
+} & (
+  | {
+      target: CollaborationCommentTarget
+      threadId?: string
+      parentCommentId?: never
+    }
+  | {
+      parentCommentId: string
+      target?: never
+      threadId?: never
+    }
+)
+
+/**
+ * Fields that can be updated on an existing comment.
+ *
+ * @alpha
+ */
+export interface CollaborationCommentUpdate {
+  /** Replaces the current message */
+  message?: CollaborationCommentMessage
+  /** Cascades to the comment's replies */
+  status?: CollaborationCommentStatus
+  /**
+   * Re-anchors the comment within the field and source document it already
+   * targets. Pass `null` to remove the selection and leave a field-level
+   * comment.
+   */
+  range?: CollaborationCommentRange | null
+}

package/src/data/dataMethods.ts

@@ -73,7 +73,13 @@ const indexBy = (docs: Any[], attr: Any) =>
     return indexed
   }, Object.create(null))
 
-const getQuerySizeLimit = 11264
+/**
+ * Encoded query strings longer than this are sent as a `POST` body rather than
+ * in the request URL.
+ *
+ * @internal
+ */
+export const getQuerySizeLimit = 11264
 
 /**
  * Resolve the effective stega config, cleaned params, response mapper and

package/src/data/listen.ts

@@ -29,9 +29,11 @@ import {resolveEventSourceFetch} from './resolveEventSourceFetch'
 // Limit is 16K for a _request_, eg including headers. Have to account for an
 // unknown range of headers, but an average EventSource request from Chrome seems
 // to have around 700 bytes of cruft, so let us account for 1.2K to be "safe"
-const MAX_URL_LENGTH = 16000 - 1200
+/** @internal */
+export const MAX_URL_LENGTH = 16000 - 1200
 
-const possibleOptions = [
+/** @internal */
+export const possibleOptions = [
   'includePreviousRevision',
   'includeResult',
   'includeMutations',
@@ -42,7 +44,8 @@ const possibleOptions = [
   'tag',
 ]
 
-const defaultOptions = {
+/** @internal */
+export const defaultOptions = {
   includeResult: true,
 }
 
@@ -137,7 +140,7 @@ export function _listen<
   opts: Opts = {} as Opts,
 ): Observable<ListenEventFromOptions<R, Opts>> {
   const config = this.config()
-  const {url, token, withCredentials, requestTagPrefix, headers: configHeaders} = config
+  const {url, requestTagPrefix} = config
   const tag = opts.tag && requestTagPrefix ? [requestTagPrefix, opts.tag].join('.') : opts.tag
   const options = {...defaults(opts, defaultOptions), tag}
   const listenOpts = pick(options, possibleOptions)
@@ -150,6 +153,18 @@ export function _listen<
 
   const listenFor = (options.events ? options.events : ['mutation']) satisfies Opts['events']
 
+  return _connectListenEventSource<ListenEventFromOptions<R, Opts>>(this, uri, listenFor)
+}
+
+/** @internal */
+export function _connectListenEventSource<TEvent extends {type: string}>(
+  client: SanityClient | ObservableSanityClient,
+  uri: string,
+  listenFor: string[],
+): Observable<TEvent> {
+  const config = client.config()
+  const {token, withCredentials, headers: configHeaders} = config
+
   const headers: Record<string, string> = {}
   if (token) {
     headers.Authorization = `Bearer ${token}`
@@ -173,5 +188,5 @@ export function _listen<
       type: event.type,
       ...('data' in event ? (event.data as object) : {}),
     })),
-  ) as Observable<ListenEventFromOptions<R, Opts>>
+  ) as Observable<TEvent>
 }