feat: fix comment types & support parentEntityReference, replies & st…

…atus (#2027)

* test: typescriptify integration test

* fix: tweak comment types

* fix: parent entity ref is only supported by ct & entry

* fix: handle missing `parentEntityReference` for workflows

* test: reply & parent ref

* test: wrong assertion

* test: parent entity reference format

* test: adjust assertion

* test: `parentEntityReference` value

* feat: add comment status

* feat: comment status

* feat: filter by status

lib/adapters/REST/endpoints/comment.ts

@@ -23,7 +23,10 @@ import { RestEndpoint } from '../types'
 import * as raw from './raw'
 import { normalizeSelect } from './utils'
 
+const VERSION_HEADER = 'X-Contentful-Version'
 const BODY_FORMAT_HEADER = 'x-contentful-comment-body-format'
+const PARENT_ENTITY_REFERENCE_HEADER = 'x-contentful-parent-entity-reference'
+const PARENT_COMMENT_ID_HEADER = 'x-contentful-parent-id'
 
 const getSpaceEnvBaseUrl = (params: GetSpaceEnvironmentParams) =>
   `/spaces/${params.spaceId}/environments/${params.environmentId}`
@@ -99,12 +102,13 @@ export const create: RestEndpoint<'Comment', 'create'> = (
 ) => {
   const data = copy(rawData)
   return raw.post<CommentProps>(http, getEntityBaseUrl(params), data, {
-    headers:
-      typeof rawData.body !== 'string'
-        ? {
-            [BODY_FORMAT_HEADER]: 'rich-text',
-          }
-        : {},
+    headers: {
+      ...(typeof rawData.body !== 'string' ? { [BODY_FORMAT_HEADER]: 'rich-text' } : {}),
+      ...('parentEntityReference' in params && params.parentEntityReference
+        ? { [PARENT_ENTITY_REFERENCE_HEADER]: params.parentEntityReference }
+        : {}),
+      ...(params.parentCommentId ? { [PARENT_COMMENT_ID_HEADER]: params.parentCommentId } : {}),
+    },
   })
 }
 
@@ -119,12 +123,8 @@ export const update: RestEndpoint<'Comment', 'update'> = (
 
   return raw.put<CommentProps>(http, getEntityCommentUrl(params), data, {
     headers: {
-      'X-Contentful-Version': rawData.sys.version ?? 0,
-      ...(typeof rawData.body !== 'string'
-        ? {
-            [BODY_FORMAT_HEADER]: 'rich-text',
-          }
-        : {}),
+      [VERSION_HEADER]: rawData.sys.version ?? 0,
+      ...(typeof rawData.body !== 'string' ? { [BODY_FORMAT_HEADER]: 'rich-text' } : {}),
       ...headers,
     },
   })
@@ -135,7 +135,7 @@ export const del: RestEndpoint<'Comment', 'delete'> = (
   { version, ...params }: DeleteCommentParams
 ) => {
   return raw.del(http, getEntityCommentUrl(params), {
-    headers: { 'X-Contentful-Version': version },
+    headers: { [VERSION_HEADER]: version },
   })
 }
 

lib/common-types.ts

@@ -30,6 +30,7 @@ import {
   RichTextCommentProps,
   PlainTextBodyFormat,
   RichTextCommentBodyPayload,
+  GetCommentParentEntityParams,
 } from './entities/comment'
 import { EditorInterfaceProps } from './entities/editor-interface'
 import { CreateEntryProps, EntryProps, EntryReferenceProps } from './entities/entry'
@@ -1857,7 +1858,9 @@ export type GetAppInstallationsForOrgParams = GetOrganizationParams & {
 }
 export type GetAppInstallationParams = GetSpaceEnvironmentParams & { appDefinitionId: string }
 export type GetBulkActionParams = GetSpaceEnvironmentParams & { bulkActionId: string }
-export type GetCommentParams = GetEntryParams & { commentId: string }
+export type GetCommentParams = (GetEntryParams | GetCommentParentEntityParams) & {
+  commentId: string
+}
 export type GetContentTypeParams = GetSpaceEnvironmentParams & { contentTypeId: string }
 export type GetEditorInterfaceParams = GetSpaceEnvironmentParams & { contentTypeId: string }
 export type GetEntryParams = GetSpaceEnvironmentParams & { entryId: string }

lib/entities/comment.ts

@@ -15,6 +15,8 @@ import {
 import { wrapCollection } from '../common-utils'
 import enhanceWithMethods from '../enhance-with-methods'
 
+// PROPS //
+
 interface LinkWithReference<T extends string> extends Link<T> {
   sys: Link<T>['sys'] & {
     ref: string
@@ -30,6 +32,7 @@ export type CommentSysProps = Pick<
   environment: SysLink
   parentEntity:
     | Link<'ContentType'>
+    | LinkWithReference<'ContentType'>
     | Link<'Entry'>
     | LinkWithReference<'Entry'>
     | VersionedLink<'Workflow'>
@@ -42,12 +45,15 @@ export type RichTextBodyProperty = 'rich-text'
 export type RichTextBodyFormat = { bodyFormat: RichTextBodyProperty }
 export type PlainTextBodyFormat = { bodyFormat?: PlainTextBodyProperty }
 
+export type CommentStatus = 'active' | 'resolved'
+
 export type CommentProps = {
   sys: CommentSysProps
   body: string
+  status: CommentStatus
 }
 
-export type CreateCommentProps = Omit<CommentProps, 'sys'>
+export type CreateCommentProps = Omit<CommentProps, 'sys' | 'status'> & { status?: CommentStatus }
 export type UpdateCommentProps = Omit<CommentProps, 'sys'> & {
   sys: Pick<CommentSysProps, 'version'>
 }
@@ -81,27 +87,40 @@ export type RichTextCommentBodyPayload = { body: RichTextCommentDocument }
 
 export type RichTextCommentProps = Omit<CommentProps, 'body'> & RichTextCommentBodyPayload
 
+// PARAMS //
+
 // We keep this type as explicit as possible until we open up the comments entity further
 export type GetCommentParentEntityParams = GetSpaceEnvironmentParams &
   (
     | {
         parentEntityType: 'ContentType'
         parentEntityId: string
+        parentEntityReference?: string
       }
     | {
         parentEntityType: 'Entry'
         parentEntityId: string
+        parentEntityReference?: string
       }
     | {
         parentEntityType: 'Workflow'
         parentEntityId: string
         parentEntityVersion?: number
       }
   )
-export type GetManyCommentsParams = GetEntryParams | GetCommentParentEntityParams
-export type CreateCommentParams = GetEntryParams | GetCommentParentEntityParams
+
+export type GetManyCommentsParams = (GetEntryParams | GetCommentParentEntityParams) & {
+  status?: CommentStatus
+}
+export type CreateCommentParams = (GetEntryParams | GetCommentParentEntityParams) & {
+  parentCommentId?: string
+}
 export type UpdateCommentParams = GetCommentParams
-export type DeleteCommentParams = GetCommentParams & { version: number }
+export type DeleteCommentParams = GetCommentParams & {
+  version: number
+}
+
+// NESTED CLIENT //
 
 type CommentApi = {
   update(): Promise<Comment | RichTextComment>
@@ -128,29 +147,28 @@ export default function createCommentApi(makeRequest: MakeRequest): CommentApi {
   })
 
   return {
-    update: function () {
+    update: async function () {
       const raw = this.toPlainObject() as CommentProps
 
-      return makeRequest({
+      const data = await makeRequest({
         entityType: 'Comment',
         action: 'update',
         params: getParams(raw),
         payload: raw,
-      }).then((data) => wrapComment(makeRequest, data))
+      })
+      return wrapComment(makeRequest, data)
     },
 
-    delete: function () {
+    delete: async function () {
       const raw = this.toPlainObject() as CommentProps
 
-      return makeRequest({
+      await makeRequest({
         entityType: 'Comment',
         action: 'delete',
         params: {
           ...getParams(raw),
           version: raw.sys.version,
         },
-      }).then(() => {
-        // noop
       })
     },
   }

lib/plain/plain-client-test.ts

@@ -64,7 +64,11 @@ describe('Plain Client', () => {
       })
 
       it('should create a update object', async () => {
-        await plainClient.comment.update(props, { body: updateText, sys: { version: 2 } })
+        await plainClient.comment.update(props, {
+          body: updateText,
+          sys: { version: 2 },
+          status: 'active',
+        })
         expect(stub).to.have.been.calledWithMatch({
           entityType: 'Comment',
           action: 'update',
@@ -162,18 +166,22 @@ describe('Plain Client', () => {
           entityType: 'Comment',
           action: 'create',
           params: props,
-          payload: { body: richTextBody },
+          payload: { body: richTextBody, status: 'active' },
           headers: undefined,
         })
       })
 
       it('should create a update object', async () => {
-        await plainClient.comment.update(props, { body: richTextBody, sys: { version: 2 } })
+        await plainClient.comment.update(props, {
+          body: richTextBody,
+          sys: { version: 2 },
+          status: 'active',
+        })
         expect(stub).to.have.been.calledWithMatch({
           entityType: 'Comment',
           action: 'update',
           params: props,
-          payload: { body: richTextBody },
+          payload: { body: richTextBody, status: 'active' },
           headers: undefined,
         })
       })