feat: PlainClient docs - task [EXT-4924] (#2181)

* feat: PlainClient docs - task [EXT-4924] * improving examples * jareds nits (ty jared) * cleaning up javascript examples * refactoring create or update * fixing build * fixing build * attempting to fix codeclimate * attempting to fix codeclimate * attempting to fix codeclimate
contentful · Feb 21, 2024 · 9c8603f · 9c8603f
1 parent 9a651ec
commit 9c8603f
Show file tree

Hide file tree

Showing 9 changed files with 179 additions and 71 deletions.
diff --git a/lib/plain/common-types.ts b/lib/plain/common-types.ts
@@ -22,8 +22,6 @@ import {
   QueryParams,
   GetBulkActionParams,
   GetReleaseParams,
-  GetTaskParams,
-  GetEntryParams,
   CursorPaginatedCollectionProp,
   GetWorkflowDefinitionParams,
   GetEnvironmentTemplateParams,
@@ -102,14 +100,6 @@ import {
   ReleaseValidatePayload,
 } from '../entities/release'
 import { ReleaseActionProps, ReleaseActionQueryOptions } from '../entities/release-action'
-import {
-  CreateTaskParams,
-  CreateTaskProps,
-  DeleteTaskParams,
-  TaskProps,
-  UpdateTaskParams,
-  UpdateTaskProps,
-} from '../entities/task'
 import {
   CreateWorkflowDefinitionParams,
   CreateWorkflowDefinitionProps,
@@ -161,6 +151,7 @@ import { AppEventSubscriptionPlainClientAPI } from './entities/app-event-subscri
 import { AppKeyPlainClientAPI } from './entities/app-key'
 import { UserPlainClientAPI } from './entities/user'
 import { UploadPlainClientAPI } from './entities/upload'
+import { TaskPlainClientAPI } from './entities/task'
 import { OrganizationPlainClientAPI } from './entities/organization'
 import { LocalePlainClientAPI } from './entities/locale'
 
@@ -758,23 +749,7 @@ export type PlainClientAPI = {
     ): Promise<SpaceMembershipProps>
     delete(params: OptionalDefaults<GetSpaceMembershipProps>): Promise<any>
   }
-  task: {
-    get(params: OptionalDefaults<GetTaskParams>): Promise<TaskProps>
-    getMany(
-      params: OptionalDefaults<GetEntryParams & QueryParams>
-    ): Promise<CollectionProp<TaskProps>>
-    create(
-      params: OptionalDefaults<CreateTaskParams>,
-      rawData: CreateTaskProps,
-      headers?: RawAxiosRequestHeaders
-    ): Promise<TaskProps>
-    update(
-      params: OptionalDefaults<UpdateTaskParams>,
-      rawData: UpdateTaskProps,
-      headers?: RawAxiosRequestHeaders
-    ): Promise<TaskProps>
-    delete(params: OptionalDefaults<DeleteTaskParams>): Promise<void>
-  }
+  task: TaskPlainClientAPI
   team: {
     get(params: OptionalDefaults<GetTeamParams>): Promise<TeamProps>
     getMany(

diff --git a/lib/plain/entities/app-definition.ts b/lib/plain/entities/app-definition.ts
@@ -1,4 +1,3 @@
-import { RawAxiosRequestHeaders } from 'axios'
 import {
   CollectionProp,
   GetAppDefinitionParams,
@@ -11,6 +10,8 @@ import {
   CreateAppDefinitionProps,
 } from '../../entities/app-definition'
 import { OptionalDefaults } from '../wrappers/wrap'
+import { CreateOrUpdate } from './base'
+import { Get } from 'type-fest'
 
 export type AppDefinitionPlainClientAPI = {
   /**
@@ -69,10 +70,7 @@ export type AppDefinitionPlainClientAPI = {
    * );
    * ```
    */
-  create(
-    params: OptionalDefaults<GetOrganizationParams>,
-    rawData: CreateAppDefinitionProps
-  ): Promise<AppDefinitionProps>
+  create: CreateOrUpdate<GetOrganizationParams, CreateAppDefinitionProps, AppDefinitionProps>
   /**
    * Update an App Definition
    * @param params entity IDs to identify the App Definition
@@ -93,11 +91,7 @@ export type AppDefinitionPlainClientAPI = {
    * );
    * ```
    */
-  update(
-    params: OptionalDefaults<GetAppDefinitionParams>,
-    rawData: AppDefinitionProps,
-    headers?: RawAxiosRequestHeaders
-  ): Promise<AppDefinitionProps>
+  update: CreateOrUpdate<GetAppDefinitionParams, AppDefinitionProps, AppDefinitionProps>
   /**
    * Delete an App Definition
    * @param params entity IDs to identify the App Definition

diff --git a/lib/plain/entities/base.ts b/lib/plain/entities/base.ts
@@ -0,0 +1,8 @@
+import { RawAxiosRequestHeaders } from 'axios'
+import { OptionalDefaults } from '../wrappers/wrap'
+
+export type CreateOrUpdate<T, Props, ReturnProps> = (
+  params: OptionalDefaults<T>,
+  rawData: Props,
+  headers: RawAxiosRequestHeaders
+) => Promise<ReturnProps>
diff --git a/lib/plain/entities/extension.ts b/lib/plain/entities/extension.ts
@@ -1,4 +1,3 @@
-import { RawAxiosRequestHeaders } from 'axios'
 import {
   CollectionProp,
   GetExtensionParams,
@@ -7,6 +6,7 @@ import {
 } from '../../common-types'
 import { CreateExtensionProps, ExtensionProps } from '../../entities/extension'
 import { OptionalDefaults } from '../wrappers/wrap'
+import { CreateOrUpdate } from './base'
 
 export type ExtensionPlainClientAPI = {
   /**
@@ -69,11 +69,7 @@ export type ExtensionPlainClientAPI = {
    * );
    * ```
    */
-  create(
-    params: OptionalDefaults<GetSpaceEnvironmentParams>,
-    rawData: CreateExtensionProps,
-    headers?: RawAxiosRequestHeaders
-  ): Promise<ExtensionProps>
+  create: CreateOrUpdate<GetSpaceEnvironmentParams, CreateExtensionProps, ExtensionProps>
   /**
    * Creates a new Extension with a given ID
    * @param params entity IDs to identify the Environment in which to create the Extension
@@ -104,11 +100,7 @@ export type ExtensionPlainClientAPI = {
    * );
    * ```
    */
-  createWithId(
-    params: OptionalDefaults<GetExtensionParams>,
-    rawData: CreateExtensionProps,
-    headers?: RawAxiosRequestHeaders
-  ): Promise<ExtensionProps>
+  createWithId: CreateOrUpdate<GetExtensionParams, CreateExtensionProps, ExtensionProps>
   /**
    * Updates an Extension
    * @param params entity IDs to identify the Extension
@@ -155,11 +147,7 @@ export type ExtensionPlainClientAPI = {
    * );
    * ```
    */
-  update(
-    params: OptionalDefaults<GetExtensionParams>,
-    rawData: ExtensionProps,
-    headers?: RawAxiosRequestHeaders
-  ): Promise<ExtensionProps>
+  update: CreateOrUpdate<GetExtensionParams, ExtensionProps, ExtensionProps>
   /**
    * Deletes the Extension
    * @param params entity IDs to identity the Extension

diff --git a/lib/plain/entities/task.ts b/lib/plain/entities/task.ts
@@ -0,0 +1,129 @@
+import {
+  CreateTaskParams,
+  DeleteTaskParams,
+  UpdateTaskParams,
+  UpdateTaskProps,
+} from '../../entities/task'
+import {
+  CollectionProp,
+  CreateTaskProps,
+  GetEntryParams,
+  GetTaskParams,
+  QueryParams,
+  TaskProps,
+} from '../../export-types'
+import { OptionalDefaults } from '../wrappers/wrap'
+import { CreateOrUpdate } from './base'
+
+export type TaskPlainClientAPI = {
+  /** Fetches a task
+   *
+   * @param params Space ID, Entry ID, Environment ID, and Task ID
+   * @returns the task
+   * @throws if the request fails or the task is not found
+   * @example
+   * ```javascript
+   * const task = await client.task.get({
+   *  spaceId: '<space_id>',
+   *  entryId: '<entry_id>',
+   *  environmentId: '<environment_id>',
+   *  taskId: '<task_id>',
+   * });
+   * ```
+   */
+  get(params: OptionalDefaults<GetTaskParams>): Promise<TaskProps>
+  /** Fetches all tasks
+   *
+   * @param params Space ID, Entry ID, Environment ID, and query parameters
+   * @returns a collection of tasks
+   * @throws if the request fails or the tasks are not found
+   * @example
+   * ```javascript
+   * const tasks = await client.task.getMany({
+   *  spaceId: '<space_id>',
+   *  entryId: '<entry_id>',
+   *  environmentId: '<environment_id>',
+   *  query: {
+   *   limit: 100,
+   *  }
+   * });
+   * ```
+   */
+  getMany(
+    params: OptionalDefaults<GetEntryParams & QueryParams>
+  ): Promise<CollectionProp<TaskProps>>
+  /** Creates a task
+   *
+   * @param params Space ID, Entry ID, Environment ID, and query parameters
+   * @param rawData the task
+   * @returns the task
+   * @throws if the request fails or the task is not found
+   * @example
+   * ```javascript
+   * const task = await client.task.create(
+   *  {
+   *    spaceId: '<space_id>',
+   *    entryId: '<entry_id>',
+   *    environmentId: '<environment_id>',
+   *  },
+   *  {
+   *    body: "Review Translation",
+   *    status: "active",
+   *    assignedTo: {
+   *      sys: {
+   *        type: "Link",
+   *         linkType: "User",
+   *         id: <user_id>
+   *      }
+   *    }
+   *  }
+   * );
+   * ```
+   */
+  create: CreateOrUpdate<CreateTaskParams, CreateTaskProps, TaskProps>
+  /** Updates a task
+   *
+   * @param params Space ID, Entry ID, Environment ID, and Task ID
+   * @param rawData the task
+   * @returns the task
+   * @throws if the request fails or the task is not found
+   * @example
+   * ```javascript
+   * const task = await client.task.update(
+   *  {
+   *    spaceId: '<space_id>',
+   *    entryId: '<entry_id>',
+   *    environmentId: '<environment_id>',
+   *    taskId: '<task_id>',
+   *  },
+   *  {
+   *    body: "Review Translation",
+   *    status: "active",
+   *    assignedTo: {
+   *      sys: {
+   *        type: "Link",
+   *         linkType: "User",
+   *         id: <user_id>
+   *      }
+   *    }
+   *  }
+   * );
+   * ```
+   */
+  update: CreateOrUpdate<UpdateTaskParams, UpdateTaskProps, TaskProps>
+  /** Deletes a task
+   *
+   * @param params Space ID, Entry ID, Environment ID, and Task ID
+   * @throws if the request fails or the task is not found
+   * @example
+   * ```javascript
+   * await client.task.delete({
+   *  spaceId: '<space_id>',
+   *  entryId: '<entry_id>',
+   *  environmentId: '<environment_id>',
+   *  taskId: '<task_id>',
+   * });
+   * ```
+   */
+  delete(params: OptionalDefaults<DeleteTaskParams>): Promise<void>
+}
diff --git a/lib/plain/entities/user.ts b/lib/plain/entities/user.ts
@@ -17,7 +17,9 @@ export type UserPlainClientAPI = {
    * ```javascript
    * const users = await client.user.getManyForSpace({
    *  spaceId: '<space_id>',
-   *  limit: 100,
+   *  query: {
+   *   limit: 100,
+   *  }
    * });
    * ```
    */
@@ -74,7 +76,9 @@ export type UserPlainClientAPI = {
    * ```javascript
    * const users = await client.user.getManyForOrganization({
    *   organizationId: '<organization_id>',
-   *   limit: 100,
+   *   query: {
+   *    limit: 100,
+   *   }
    * });
    * ```
    */

diff --git a/lib/plain/entities/webhook.ts b/lib/plain/entities/webhook.ts
@@ -18,6 +18,7 @@ import {
   WebhookSigningSecretProps,
 } from '../../entities/webhook'
 import { OptionalDefaults } from '../wrappers/wrap'
+import { CreateOrUpdate } from './base'
 
 export type WebhookPlainClientAPI = {
   // Webhooks
@@ -70,11 +71,7 @@ export type WebhookPlainClientAPI = {
    * );
    * ```
    */
-  create(
-    params: OptionalDefaults<GetSpaceParams>,
-    rawData: CreateWebhooksProps,
-    headers?: RawAxiosRequestHeaders
-  ): Promise<WebhookProps>
+  create: CreateOrUpdate<GetSpaceParams, CreateWebhooksProps, WebhookProps>
   /**
    * Creates the Webhook
    * @param params entity IDs to identify the Webhook to update

diff --git a/lib/plain/plain-client-test.ts b/lib/plain/plain-client-test.ts
@@ -8,8 +8,23 @@ import { CommentNode, RichTextCommentDocument } from '../entities/comment'
 chai.should()
 chai.use(sinonChai)
 
+type Props = {
+  commentId: string
+  entryId: string
+  bodyFormat: string
+  spaceId: string
+  environmentId: string
+}
+
 describe('Plain Client', () => {
   const stub = Sinon.stub()
+  const defaultProps: Props = {
+    commentId: '123',
+    entryId: '123',
+    bodyFormat: 'plain-text',
+    spaceId: '123',
+    environmentId: '123',
+  }
 
   beforeEach(() => stub.reset())
 
@@ -23,11 +38,10 @@ describe('Plain Client', () => {
 
   describe('Comment', () => {
     describe('when body is plain text', () => {
-      const props: { commentId: string; entryId: string; bodyFormat: 'plain-text' } = {
-        commentId: '123',
-        entryId: '123',
+      const props = {
+        ...defaultProps,
         bodyFormat: 'plain-text',
-      }
+      } as any
       const updateText = 'My new text'
 
       it('should create a get object', async () => {
@@ -148,11 +162,10 @@ describe('Plain Client', () => {
         ],
       }
 
-      const props: { commentId: string; entryId: string; bodyFormat: 'rich-text' } = {
-        commentId: '123',
-        entryId: '123',
+      const props = {
+        ...defaultProps,
         bodyFormat: 'rich-text',
-      }
+      } as any
 
       it('should create a get object', async () => {
         await plainClient.comment.get(props)

diff --git a/lib/plain/wrappers/wrap.ts b/lib/plain/wrappers/wrap.ts
@@ -10,9 +10,9 @@ export type DefaultParams = {
  * @private
  */
 export type OptionalDefaults<T> = Omit<T, keyof DefaultParams> &
-  ('organizationId' extends keyof T ? { organizationId?: string } : Record<string, unknown>) &
-  ('spaceId' extends keyof T ? { spaceId?: string } : Record<string, unknown>) &
-  ('environmentId' extends keyof T ? { environmentId?: string } : Record<string, unknown>)
+  ('organizationId' extends keyof T ? { organizationId: string } : Record<string, unknown>) &
+  ('spaceId' extends keyof T ? { spaceId: string } : Record<string, unknown>) &
+  ('environmentId' extends keyof T ? { environmentId: string } : Record<string, unknown>)
 
 /**
  * @private