@sanity/client 8.0.0 → 8.2.0

package/src/collaboration/CollaborationCommentsClient.ts

@@ -0,0 +1,387 @@
+import {lastValueFrom, type Observable} from 'rxjs'
+
+import type {ListenEventFromOptions} from '../data/listen'
+import type {ObservableSanityClient, SanityClient} from '../SanityClient'
+import type {
+  HttpRequest,
+  ListenEvent,
+  MultipleMutationResult,
+  MutationEvent,
+  QueryParams,
+} from '../types'
+import {
+  _addReaction,
+  _create,
+  _delete,
+  _fetch,
+  _getTargetDocumentRef,
+  _listen,
+  _removeReaction,
+  _update,
+} from './comments'
+import type {
+  CollaborationCommentCreate,
+  CollaborationCommentDocument,
+  CollaborationCommentReactionShortName,
+  CollaborationCommentsListenOptions,
+  CollaborationCommentsRequestOptions,
+  CollaborationCommentsWriteOptions,
+  CollaborationCommentUpdate,
+} from './types'
+
+/**
+ * Comments on the configured organization resource.
+ *
+ * Requires `collaboration.organizationId`, plus either `resource` or `projectId` and `dataset`.
+ *
+ * @alpha
+ */
+export class ObservableCollaborationCommentsClient {
+  #client: ObservableSanityClient
+  #httpRequest: HttpRequest
+  constructor(client: ObservableSanityClient, httpRequest: HttpRequest) {
+    this.#client = client
+    this.#httpRequest = httpRequest
+  }
+
+  /**
+   * Create a comment or reply on the configured resource.
+   *
+   * A top-level comment requires `target`; a reply requires `parentCommentId` (never both).
+   * Replies inherit `target`, `status`, and `threadId` from the parent comment.
+   *
+   * @param body - Comment to create
+   * @param options - Optional request options
+   * @returns The created comment
+   */
+  create(
+    body: CollaborationCommentCreate,
+    options?: CollaborationCommentsWriteOptions,
+  ): Observable<CollaborationCommentDocument> {
+    return _create(this.#client, this.#httpRequest, body, options)
+  }
+
+  /**
+   * Update an existing comment.
+   *
+   * Updating `status` cascades to the comment's replies.
+   *
+   * @param id - Comment document ID
+   * @param body - Fields to update
+   * @param options - Optional request options
+   * @returns The updated comment
+   */
+  update(
+    id: string,
+    body: CollaborationCommentUpdate,
+    options?: CollaborationCommentsWriteOptions,
+  ): Observable<CollaborationCommentDocument> {
+    return _update(this.#client, this.#httpRequest, id, body, options)
+  }
+
+  /**
+   * Delete a comment and its replies.
+   *
+   * @param id - Comment document ID
+   * @param options - Optional request options
+   * @returns Mutation result, where `documentIds` covers the comment and every deleted reply
+   */
+  delete(
+    id: string,
+    options?: CollaborationCommentsWriteOptions,
+  ): Observable<MultipleMutationResult> {
+    return _delete(this.#client, this.#httpRequest, id, options)
+  }
+
+  /**
+   * Add the current user's reaction to a comment.
+   *
+   * @param id - Comment document ID
+   * @param shortName - Emoji short name, for example `:+1:`
+   * @param options - Optional request options
+   * @returns The comment, with the reaction applied
+   */
+  addReaction(
+    id: string,
+    shortName: CollaborationCommentReactionShortName,
+    options?: CollaborationCommentsWriteOptions,
+  ): Observable<CollaborationCommentDocument> {
+    return _addReaction(this.#client, this.#httpRequest, id, shortName, options)
+  }
+
+  /**
+   * Remove the current user's reaction from a comment.
+   *
+   * @param id - Comment document ID
+   * @param shortName - Emoji short name, for example `:+1:`
+   * @param options - Optional request options
+   * @returns The comment, with the reaction removed
+   */
+  removeReaction(
+    id: string,
+    shortName: CollaborationCommentReactionShortName,
+    options?: CollaborationCommentsWriteOptions,
+  ): Observable<CollaborationCommentDocument> {
+    return _removeReaction(this.#client, this.#httpRequest, id, shortName, options)
+  }
+
+  /**
+   * Build the global document reference used by `target.document._ref`, for use in
+   * queries and listeners.
+   *
+   * The reference is built from the configured `resource` and the published ID of
+   * the given document ID, since comment references always use published IDs.
+   *
+   * @example
+   * ```ts
+   * client.collaboration.comments.listen(
+   *   '*[_type == "sanity.comment" && target.document._ref == $ref]',
+   *   {ref: client.collaboration.comments.getTargetDocumentRef('doc-1')},
+   * )
+   * ```
+   *
+   * @param documentId - Document ID, in published, draft or version form
+   * @returns Global document reference, of the form `resourceType:resourceId:documentId`
+   */
+  getTargetDocumentRef(
+    documentId: string,
+  ): CollaborationCommentDocument['target']['document']['_ref'] {
+    return _getTargetDocumentRef(this.#client, documentId)
+  }
+
+  /**
+   * Fetch comments on the configured resource.
+   *
+   * Takes the same `query` and `params` as `client.fetch`, and switches from a
+   * GET to a POST for queries too large for the request URL in the same way,
+   * but queries the comments endpoint, which accepts none of the query options
+   * `client.fetch` does (`perspective`, `useCdn`, `filterResponse`,
+   * `resultSourceMap`, stega).
+   *
+   * The query runs against the organization store, which is not scoped to
+   * comments, so filter on `_type == "sanity.comment"`.
+   *
+   * @param query - GROQ-query to perform
+   * @param params - Optional query parameters
+   * @param options - Optional request options
+   */
+  fetch<R = unknown>(
+    query: string,
+    params?: QueryParams,
+    options?: CollaborationCommentsRequestOptions,
+  ): Observable<R> {
+    return _fetch<R>(this.#client, this.#httpRequest, query, params, options)
+  }
+
+  /**
+   * Listen for changes to comments on the configured resource.
+   *
+   * Mirrors `client.listen(query, params)`, and emits mutation events.
+   *
+   * @param query - GROQ-filter to listen to changes for
+   * @param params - Optional query parameters
+   */
+  listen(
+    query: string,
+    params?: QueryParams,
+  ): Observable<MutationEvent<CollaborationCommentDocument>>
+  /**
+   * Listen for changes to comments on the configured resource.
+   *
+   * Mirrors `client.listen(query, params, options)`.
+   *
+   * @param query - GROQ-filter to listen to changes for
+   * @param params - Optional query parameters
+   * @param options - The same listener options `client.listen` takes, forwarded
+   *   to the organization store's listener
+   */
+  listen<Opts extends CollaborationCommentsListenOptions>(
+    query: string,
+    params: QueryParams | undefined,
+    options: Opts,
+  ): Observable<ListenEventFromOptions<CollaborationCommentDocument, Opts>>
+  listen(
+    query: string,
+    params?: QueryParams,
+    options?: CollaborationCommentsListenOptions,
+  ): Observable<ListenEvent<CollaborationCommentDocument>> {
+    return _listen(this.#client, query, params, options)
+  }
+}
+
+/**
+ * Comments on the configured organization resource.
+ *
+ * Requires `collaboration.organizationId`, plus either `resource` or `projectId` and `dataset`.
+ *
+ * @alpha
+ */
+export class CollaborationCommentsClient {
+  #client: SanityClient
+  #httpRequest: HttpRequest
+  constructor(client: SanityClient, httpRequest: HttpRequest) {
+    this.#client = client
+    this.#httpRequest = httpRequest
+  }
+
+  /**
+   * Create a comment or reply on the configured resource.
+   *
+   * A top-level comment requires `target`; a reply requires `parentCommentId` (never both).
+   * Replies inherit `target`, `status`, and `threadId` from the parent comment.
+   *
+   * @param body - Comment to create
+   * @param options - Optional request options
+   * @returns The created comment
+   */
+  create(
+    body: CollaborationCommentCreate,
+    options?: CollaborationCommentsWriteOptions,
+  ): Promise<CollaborationCommentDocument> {
+    return lastValueFrom(_create(this.#client, this.#httpRequest, body, options))
+  }
+
+  /**
+   * Update an existing comment.
+   *
+   * Updating `status` cascades to the comment's replies.
+   *
+   * @param id - Comment document ID
+   * @param body - Fields to update
+   * @param options - Optional request options
+   * @returns The updated comment
+   */
+  update(
+    id: string,
+    body: CollaborationCommentUpdate,
+    options?: CollaborationCommentsWriteOptions,
+  ): Promise<CollaborationCommentDocument> {
+    return lastValueFrom(_update(this.#client, this.#httpRequest, id, body, options))
+  }
+
+  /**
+   * Delete a comment and its replies.
+   *
+   * @param id - Comment document ID
+   * @param options - Optional request options
+   * @returns Mutation result, where `documentIds` covers the comment and every deleted reply
+   */
+  delete(id: string, options?: CollaborationCommentsWriteOptions): Promise<MultipleMutationResult> {
+    return lastValueFrom(_delete(this.#client, this.#httpRequest, id, options))
+  }
+
+  /**
+   * Add the current user's reaction to a comment.
+   *
+   * @param id - Comment document ID
+   * @param shortName - Emoji short name, for example `:+1:`
+   * @param options - Optional request options
+   * @returns The comment, with the reaction applied
+   */
+  addReaction(
+    id: string,
+    shortName: CollaborationCommentReactionShortName,
+    options?: CollaborationCommentsWriteOptions,
+  ): Promise<CollaborationCommentDocument> {
+    return lastValueFrom(_addReaction(this.#client, this.#httpRequest, id, shortName, options))
+  }
+
+  /**
+   * Remove the current user's reaction from a comment.
+   *
+   * @param id - Comment document ID
+   * @param shortName - Emoji short name, for example `:+1:`
+   * @param options - Optional request options
+   * @returns The comment, with the reaction removed
+   */
+  removeReaction(
+    id: string,
+    shortName: CollaborationCommentReactionShortName,
+    options?: CollaborationCommentsWriteOptions,
+  ): Promise<CollaborationCommentDocument> {
+    return lastValueFrom(_removeReaction(this.#client, this.#httpRequest, id, shortName, options))
+  }
+
+  /**
+   * Build the global document reference used by `target.document._ref`, for use in
+   * queries and listeners.
+   *
+   * The reference is built from the configured `resource` and the published ID of
+   * the given document ID, since comment references always use published IDs.
+   *
+   * @example
+   * ```ts
+   * const comments = await client.collaboration.comments.fetch(
+   *   '*[_type == "sanity.comment" && target.document._ref == $ref]',
+   *   {ref: client.collaboration.comments.getTargetDocumentRef('doc-1')},
+   * )
+   * ```
+   *
+   * @param documentId - Document ID, in published, draft or version form
+   * @returns Global document reference, of the form `resourceType:resourceId:documentId`
+   */
+  getTargetDocumentRef(
+    documentId: string,
+  ): CollaborationCommentDocument['target']['document']['_ref'] {
+    return _getTargetDocumentRef(this.#client, documentId)
+  }
+
+  /**
+   * Fetch comments on the configured resource.
+   *
+   * Takes the same `query` and `params` as `client.fetch`, and switches from a
+   * GET to a POST for queries too large for the request URL in the same way,
+   * but queries the comments endpoint, which accepts none of the query options
+   * `client.fetch` does (`perspective`, `useCdn`, `filterResponse`,
+   * `resultSourceMap`, stega).
+   *
+   * The query runs against the organization store, which is not scoped to
+   * comments, so filter on `_type == "sanity.comment"`.
+   *
+   * @param query - GROQ-query to perform
+   * @param params - Optional query parameters
+   * @param options - Optional request options
+   */
+  fetch<R = unknown>(
+    query: string,
+    params?: QueryParams,
+    options?: CollaborationCommentsRequestOptions,
+  ): Promise<R> {
+    return lastValueFrom(_fetch<R>(this.#client, this.#httpRequest, query, params, options))
+  }
+
+  /**
+   * Listen for changes to comments on the configured resource.
+   *
+   * Mirrors `client.listen(query, params)`, and emits mutation events.
+   *
+   * @param query - GROQ-filter to listen to changes for
+   * @param params - Optional query parameters
+   */
+  listen(
+    query: string,
+    params?: QueryParams,
+  ): Observable<MutationEvent<CollaborationCommentDocument>>
+  /**
+   * Listen for changes to comments on the configured resource.
+   *
+   * Mirrors `client.listen(query, params, options)`.
+   *
+   * @param query - GROQ-filter to listen to changes for
+   * @param params - Optional query parameters
+   * @param options - The same listener options `client.listen` takes, forwarded
+   *   to the organization store's listener
+   */
+  listen<Opts extends CollaborationCommentsListenOptions>(
+    query: string,
+    params: QueryParams | undefined,
+    options: Opts,
+  ): Observable<ListenEventFromOptions<CollaborationCommentDocument, Opts>>
+  listen(
+    query: string,
+    params?: QueryParams,
+    options?: CollaborationCommentsListenOptions,
+  ): Observable<ListenEvent<CollaborationCommentDocument>> {
+    return _listen(this.#client, query, params, options)
+  }
+}

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,
+  )
+}