feat: enhance comment endpoint to support workflows as parent entity …

…[HOMER-1455] (#1544) * feat: enhance comment entity to support workflows as parent entity feat: enhance comment entity to support workflows as parent entity * feat: export new TS definitions and use new interface already in entry api * fix: use new types in plain comment types as well * fix: readd space and env id for integration test * fix: remove test isolation and fix lint warning regarding ts-ignore * feat: make parent version optional for fetching workflow comments * fix: use versions instead of version Co-authored-by: Felix Boenke <FLoppix@users.noreply.github.com> Co-authored-by: Felix Boenke <felixboenke@googlemail.com>
contentful · Dec 7, 2022 · bc0c6ae · bc0c6ae
1 parent 9f7488c
commit bc0c6ae
Show file tree

Hide file tree

Showing 9 changed files with 88 additions and 28 deletions.
diff --git a/lib/adapters/REST/endpoints/comment.ts b/lib/adapters/REST/endpoints/comment.ts
@@ -5,6 +5,7 @@ import {
   CollectionProp,
   GetEntryParams,
   GetCommentParams,
+  GetSpaceEnvironmentParams,
   QueryParams,
 } from '../../../common-types'
 import {
@@ -13,40 +14,57 @@ import {
   DeleteCommentParams,
   CommentProps,
   UpdateCommentProps,
+  GetManyCommentsParams,
 } from '../../../entities/comment'
 import { RestEndpoint } from '../types'
 import * as raw from './raw'
 import { normalizeSelect } from './utils'
 
-const getBaseUrl = (params: GetEntryParams) =>
-  `/spaces/${params.spaceId}/environments/${params.environmentId}/entries/${params.entryId}/comments`
-const getCommentUrl = (params: GetCommentParams) => `${getBaseUrl(params)}/${params.commentId}`
+const getSpaceEnvBaseUrl = (params: GetSpaceEnvironmentParams) =>
+  `/spaces/${params.spaceId}/environments/${params.environmentId}`
+const getEntryBaseUrl = (params: GetEntryParams) =>
+  `${getSpaceEnvBaseUrl(params)}/entries/${params.entryId}/comments`
+const getEntryCommentUrl = (params: GetCommentParams) =>
+  `${getEntryBaseUrl(params)}/${params.commentId}`
+
+/**
+ * Comments can be added to either an entry or a workflow. The latter one requires a version
+ * to be set as part of the URL path. Workflow comments only support `create` (with
+ * versionized URL) and `getMany` (without version). The API might support more methods
+ * in the future with new use cases being discovered.
+ */
+const getEntityBaseUrl = (params: GetEntryParams | GetManyCommentsParams) => {
+  if ('entryId' in params) {
+    return getEntryBaseUrl(params)
+  }
+  const { parentEntityId, parentEntityType } = params
+  // No need for mapping or switch-case as long as there are only two supported cases
+  const parentPlural = parentEntityType === 'Workflow' ? 'workflows' : 'entries'
+  const versionPath =
+    'parentEntityVersion' in params ? `/versions/${params.parentEntityVersion}` : ''
+  return `${getSpaceEnvBaseUrl(params)}/${parentPlural}/${parentEntityId}${versionPath}/comments`
+}
 
 export const get: RestEndpoint<'Comment', 'get'> = (
   http: AxiosInstance,
   params: GetCommentParams
-) => raw.get<CommentProps>(http, getCommentUrl(params))
+) => raw.get<CommentProps>(http, getEntryCommentUrl(params))
 
 export const getMany: RestEndpoint<'Comment', 'getMany'> = (
   http: AxiosInstance,
-  params: GetEntryParams & QueryParams
+  params: GetManyCommentsParams & QueryParams
 ) =>
-  raw.get<CollectionProp<CommentProps>>(http, getBaseUrl(params), {
+  raw.get<CollectionProp<CommentProps>>(http, getEntityBaseUrl(params), {
     params: normalizeSelect(params.query),
   })
 
-/**
- * @deprecated use `getMany` instead. `getAll` may never be removed for app compatibility reasons.
- */
-export const getAll: RestEndpoint<'Comment', 'getAll'> = getMany
-
 export const create: RestEndpoint<'Comment', 'create'> = (
   http: AxiosInstance,
   params: CreateCommentParams,
   rawData: CreateCommentProps
 ) => {
   const data = copy(rawData)
-  return raw.post<CommentProps>(http, getBaseUrl(params), data)
+  return raw.post<CommentProps>(http, getEntityBaseUrl(params), data)
 }
 
 export const update: RestEndpoint<'Comment', 'update'> = (
@@ -58,7 +76,7 @@ export const update: RestEndpoint<'Comment', 'update'> = (
   const data: SetOptional<typeof rawData, 'sys'> = copy(rawData)
   delete data.sys
 
-  return raw.put<CommentProps>(http, getCommentUrl(params), data, {
+  return raw.put<CommentProps>(http, getEntryCommentUrl(params), data, {
     headers: {
       'X-Contentful-Version': rawData.sys.version ?? 0,
       ...headers,
@@ -70,5 +88,11 @@ export const del: RestEndpoint<'Comment', 'delete'> = (
   http: AxiosInstance,
   { version, ...params }: DeleteCommentParams
 ) => {
-  return raw.del(http, getCommentUrl(params), { headers: { 'X-Contentful-Version': version } })
+  return raw.del(http, getEntryCommentUrl(params), { headers: { 'X-Contentful-Version': version } })
 }
+
+// Add a deprecation notive. But `getAll` may never be removed for app compatibility reasons.
+/**
+ * @deprecated use `getMany` instead.
+ */
+export const getAll: RestEndpoint<'Comment', 'getAll'> = getMany
diff --git a/lib/common-types.ts b/lib/common-types.ts
@@ -21,6 +21,7 @@ import {
   CommentProps,
   UpdateCommentParams,
   UpdateCommentProps,
+  GetManyCommentsParams,
 } from './entities/comment'
 import { EditorInterfaceProps } from './entities/editor-interface'
 import { CreateEntryProps, EntryProps, EntryReferenceProps } from './entities/entry'
@@ -896,11 +897,11 @@ export type MRActions = {
   Comment: {
     get: { params: GetCommentParams; return: CommentProps }
     getMany: {
-      params: GetEntryParams & QueryParams
+      params: GetManyCommentsParams & QueryParams
       return: CollectionProp<CommentProps>
     }
     getAll: {
-      params: GetEntryParams & QueryParams
+      params: GetManyCommentsParams & QueryParams
       return: CollectionProp<CommentProps>
     }
     create: { params: CreateCommentParams; payload: CreateCommentProps; return: CommentProps }

diff --git a/lib/create-entry-api.ts b/lib/create-entry-api.ts
@@ -1,6 +1,6 @@
 import type { OpPatch } from 'json-patch'
 import { MakeRequest } from './common-types'
-import { CreateCommentProps } from './entities/comment'
+import { CreateCommentParams, CreateCommentProps } from './entities/comment'
 import { Entry, EntryProps, EntryReferenceOptionsProps } from './entities/entry'
 import { CreateTaskProps } from './entities/task'
 import * as checks from './plain/checks'
@@ -323,7 +323,12 @@ export default function createEntryApi(makeRequest: MakeRequest) {
       return makeRequest({
         entityType: 'Comment',
         action: 'create',
-        params,
+        params: {
+          spaceId: params.spaceId,
+          environmentId: params.environmentId,
+          parentEntityId: params.entryId,
+          parentEntityType: 'Entry',
+        } as CreateCommentParams,
         payload: data,
       }).then((data) => wrapComment(makeRequest, data))
     },

diff --git a/lib/entities/comment.ts b/lib/entities/comment.ts
@@ -5,21 +5,33 @@ import {
   DefaultElements,
   GetCommentParams,
   GetEntryParams,
+  GetSpaceEnvironmentParams,
   Link,
   MakeRequest,
+  PaginationQueryOptions,
   SysLink,
 } from '../common-types'
 import { wrapCollection } from '../common-utils'
 import enhanceWithMethods from '../enhance-with-methods'
 
+export interface LinkWithRef<T extends string> {
+  sys: {
+    type: 'Link'
+    linkType: T
+    id: string
+    // Selected `ref` over explicit `version` for the future (e.g. `fields.de-DE.foo`)
+    ref?: `versions.${number}`
+  }
+}
+
 export type CommentSysProps = Pick<
   BasicMetaSysProps,
   'id' | 'version' | 'createdAt' | 'createdBy' | 'updatedAt' | 'updatedBy'
 > & {
   type: 'Comment'
   space: SysLink
   environment: SysLink
-  parentEntity: Link<'Entry'>
+  parentEntity: Link<'Entry'> | LinkWithRef<'Workflow'>
 }
 
 export type CommentProps = {
@@ -32,7 +44,21 @@ export type UpdateCommentProps = Omit<CommentProps, 'sys'> & {
   sys: Pick<CommentSysProps, 'version'>
 }
 
-export type CreateCommentParams = GetEntryParams
+// We keep this type as explicit as possible until we open up the comments entity further
+export type GetCommentParentEntityParams = GetSpaceEnvironmentParams &
+  (
+    | {
+        parentEntityType: 'Entry'
+        parentEntityId: string
+      }
+    | {
+        parentEntityType: 'Workflow'
+        parentEntityId: string
+        parentEntityVersion?: number
+      }
+  )
+export type GetManyCommentsParams = GetEntryParams | GetCommentParentEntityParams
+export type CreateCommentParams = GetEntryParams | GetCommentParentEntityParams
 export type UpdateCommentParams = GetCommentParams
 export type DeleteCommentParams = GetCommentParams & { version: number }
 

diff --git a/lib/export-types.ts b/lib/export-types.ts
@@ -69,6 +69,10 @@ export type {
   CommentProps,
   CreateCommentProps,
   UpdateCommentProps,
+  DeleteCommentParams,
+  GetCommentParentEntityParams,
+  GetManyCommentsParams,
+  LinkWithRef,
 } from './entities/comment'
 export type {
   ContentType,

diff --git a/lib/plain/common-types.ts b/lib/plain/common-types.ts
@@ -63,6 +63,7 @@ import {
   CommentProps,
   UpdateCommentParams,
   UpdateCommentProps,
+  GetManyCommentsParams,
 } from '../entities/comment'
 import { ContentTypeProps, CreateContentTypeProps } from '../entities/content-type'
 import { EditorInterfaceProps } from '../entities/editor-interface'
@@ -385,7 +386,7 @@ export type PlainClientAPI = {
   comment: {
     get(params: OptionalDefaults<GetCommentParams>): Promise<CommentProps>
     getMany(
-      params: OptionalDefaults<GetEntryParams & QueryParams>
+      params: OptionalDefaults<GetManyCommentsParams & QueryParams>
     ): Promise<CollectionProp<CommentProps>>
     create(
       params: OptionalDefaults<CreateCommentParams>,

diff --git a/test/unit/adapters/REST/endpoints/workflow-definition-test.ts b/test/unit/adapters/REST/endpoints/workflow-definition-test.ts
@@ -6,7 +6,7 @@ import {
   WorkflowDefinitionProps,
   wrapWorkflowDefinition,
 } from '../../../../../lib/entities/workflow-definition'
-import { MakeRequest } from '../../../../../lib/export-types'
+import { MakeRequest, MakeRequestOptions } from '../../../../../lib/export-types'
 
 function setup(params = {}) {
   const entityMock: WorkflowDefinitionProps = cloneMock('workflowDefinition')
@@ -22,8 +22,7 @@ describe('Rest Workflow Definition', () => {
     const { httpMock, adapterMock, entityMock } = setup()
     entityMock.sys.version = 2
     const entity = wrapWorkflowDefinition(
-      // @ts-ignore
-      ((...args) => adapterMock.makeRequest(...args)) as MakeRequest,
+      ((...args: [MakeRequestOptions]) => adapterMock.makeRequest(...args)) as MakeRequest,
       entityMock
     )
     entity.description = 'new description'
@@ -49,8 +48,7 @@ describe('Rest Workflow Definition', () => {
     const { httpMock, adapterMock, entityMock } = setup()
     entityMock.sys.version = 2
     const entity = wrapWorkflowDefinition(
-      // @ts-ignore
-      ((...args) => adapterMock.makeRequest(...args)) as MakeRequest,
+      ((...args: [MakeRequestOptions]) => adapterMock.makeRequest(...args)) as MakeRequest,
       entityMock
     )
     return entity.delete().then(() => {

diff --git a/test/unit/entities/comment-test.js → test/unit/entities/comment-test.ts b/test/unit/entities/comment-test.js → test/unit/entities/comment-test.ts
diff --git a/test/unit/mocks/entities.js b/test/unit/mocks/entities.js
@@ -658,9 +658,10 @@ const commentMock = {
     },
     parentEntity: {
       sys: {
-        id: 'entry-id',
+        id: 'workflow-id',
         type: 'Link',
-        linkType: 'Entry',
+        linkType: 'Workflow',
+        ref: 'versions.3',
       },
     },
   },