From 9c8603fff48cdc1173bb226324f5734b70557d91 Mon Sep 17 00:00:00 2001 From: david-shibley-contentful <149433784+david-shibley-contentful@users.noreply.github.com> Date: Wed, 21 Feb 2024 10:20:40 -0700 Subject: [PATCH] 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 --- lib/plain/common-types.ts | 29 +----- lib/plain/entities/app-definition.ts | 14 +-- lib/plain/entities/base.ts | 8 ++ lib/plain/entities/extension.ts | 20 +---- lib/plain/entities/task.ts | 129 +++++++++++++++++++++++++++ lib/plain/entities/user.ts | 8 +- lib/plain/entities/webhook.ts | 7 +- lib/plain/plain-client-test.ts | 29 ++++-- lib/plain/wrappers/wrap.ts | 6 +- 9 files changed, 179 insertions(+), 71 deletions(-) create mode 100644 lib/plain/entities/base.ts create mode 100644 lib/plain/entities/task.ts diff --git a/lib/plain/common-types.ts b/lib/plain/common-types.ts index c62f71b862..b63e484c33 100644 --- 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 delete(params: OptionalDefaults): Promise } - task: { - get(params: OptionalDefaults): Promise - getMany( - params: OptionalDefaults - ): Promise> - create( - params: OptionalDefaults, - rawData: CreateTaskProps, - headers?: RawAxiosRequestHeaders - ): Promise - update( - params: OptionalDefaults, - rawData: UpdateTaskProps, - headers?: RawAxiosRequestHeaders - ): Promise - delete(params: OptionalDefaults): Promise - } + task: TaskPlainClientAPI team: { get(params: OptionalDefaults): Promise getMany( diff --git a/lib/plain/entities/app-definition.ts b/lib/plain/entities/app-definition.ts index 6eb0ed7fa0..29ca9de8c2 100644 --- 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, - rawData: CreateAppDefinitionProps - ): Promise + create: CreateOrUpdate /** * Update an App Definition * @param params entity IDs to identify the App Definition @@ -93,11 +91,7 @@ export type AppDefinitionPlainClientAPI = { * ); * ``` */ - update( - params: OptionalDefaults, - rawData: AppDefinitionProps, - headers?: RawAxiosRequestHeaders - ): Promise + update: CreateOrUpdate /** * 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 new file mode 100644 index 0000000000..e1d84b8f79 --- /dev/null +++ b/lib/plain/entities/base.ts @@ -0,0 +1,8 @@ +import { RawAxiosRequestHeaders } from 'axios' +import { OptionalDefaults } from '../wrappers/wrap' + +export type CreateOrUpdate = ( + params: OptionalDefaults, + rawData: Props, + headers: RawAxiosRequestHeaders +) => Promise diff --git a/lib/plain/entities/extension.ts b/lib/plain/entities/extension.ts index 76d7006597..d2a717ea28 100644 --- 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, - rawData: CreateExtensionProps, - headers?: RawAxiosRequestHeaders - ): Promise + create: CreateOrUpdate /** * 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, - rawData: CreateExtensionProps, - headers?: RawAxiosRequestHeaders - ): Promise + createWithId: CreateOrUpdate /** * Updates an Extension * @param params entity IDs to identify the Extension @@ -155,11 +147,7 @@ export type ExtensionPlainClientAPI = { * ); * ``` */ - update( - params: OptionalDefaults, - rawData: ExtensionProps, - headers?: RawAxiosRequestHeaders - ): Promise + update: CreateOrUpdate /** * 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 new file mode 100644 index 0000000000..1ac2f1ac01 --- /dev/null +++ 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: '', + * entryId: '', + * environmentId: '', + * taskId: '', + * }); + * ``` + */ + get(params: OptionalDefaults): Promise + /** 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: '', + * entryId: '', + * environmentId: '', + * query: { + * limit: 100, + * } + * }); + * ``` + */ + getMany( + params: OptionalDefaults + ): Promise> + /** 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: '', + * entryId: '', + * environmentId: '', + * }, + * { + * body: "Review Translation", + * status: "active", + * assignedTo: { + * sys: { + * type: "Link", + * linkType: "User", + * id: + * } + * } + * } + * ); + * ``` + */ + create: CreateOrUpdate + /** 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: '', + * entryId: '', + * environmentId: '', + * taskId: '', + * }, + * { + * body: "Review Translation", + * status: "active", + * assignedTo: { + * sys: { + * type: "Link", + * linkType: "User", + * id: + * } + * } + * } + * ); + * ``` + */ + update: CreateOrUpdate + /** 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: '', + * entryId: '', + * environmentId: '', + * taskId: '', + * }); + * ``` + */ + delete(params: OptionalDefaults): Promise +} diff --git a/lib/plain/entities/user.ts b/lib/plain/entities/user.ts index cbc753b5b9..07ceb709b3 100644 --- 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: '', - * limit: 100, + * query: { + * limit: 100, + * } * }); * ``` */ @@ -74,7 +76,9 @@ export type UserPlainClientAPI = { * ```javascript * const users = await client.user.getManyForOrganization({ * organizationId: '', - * limit: 100, + * query: { + * limit: 100, + * } * }); * ``` */ diff --git a/lib/plain/entities/webhook.ts b/lib/plain/entities/webhook.ts index 581a1011a0..c92ea8ab01 100644 --- 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, - rawData: CreateWebhooksProps, - headers?: RawAxiosRequestHeaders - ): Promise + create: CreateOrUpdate /** * 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 index dd303c986f..790fd6dff1 100644 --- 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 index 78cc1c4303..02e1997bba 100644 --- a/lib/plain/wrappers/wrap.ts +++ b/lib/plain/wrappers/wrap.ts @@ -10,9 +10,9 @@ export type DefaultParams = { * @private */ export type OptionalDefaults = Omit & - ('organizationId' extends keyof T ? { organizationId?: string } : Record) & - ('spaceId' extends keyof T ? { spaceId?: string } : Record) & - ('environmentId' extends keyof T ? { environmentId?: string } : Record) + ('organizationId' extends keyof T ? { organizationId: string } : Record) & + ('spaceId' extends keyof T ? { spaceId: string } : Record) & + ('environmentId' extends keyof T ? { environmentId: string } : Record) /** * @private