From 0903d976c91104a7ccf9fcd2095dc74ad0a2eb0e Mon Sep 17 00:00:00 2001 From: Tyler Collins Date: Wed, 20 Sep 2023 09:48:20 -0600 Subject: [PATCH 1/2] docs: add inline docs for the plain client App Installation interface [EXT-4729] --- lib/plain/common-types.ts | 19 +---- lib/plain/entities/app-installation.ts | 102 +++++++++++++++++++++++++ 2 files changed, 104 insertions(+), 17 deletions(-) create mode 100644 lib/plain/entities/app-installation.ts diff --git a/lib/plain/common-types.ts b/lib/plain/common-types.ts index 85ddca2472..aeaa389b7b 100644 --- a/lib/plain/common-types.ts +++ b/lib/plain/common-types.ts @@ -36,8 +36,6 @@ import { EnvironmentTemplateParams, } from '../common-types' import { ApiKeyProps, CreateApiKeyProps } from '../entities/api-key' -import { AppInstallationsForOrganizationProps } from '../entities/app-definition' -import { AppInstallationProps, CreateAppInstallationProps } from '../entities/app-installation' import { AssetFileProp, AssetProcessingForLocale, @@ -172,6 +170,7 @@ import { AppDefinitionPlainClientAPI } from './entities/app-definition' import { AppUploadPlainClientAPI } from './entities/app-upload' import { AppBundlePlainClientAPI } from './entities/app-bundle' import { AppDetailsPlainClientAPI } from './entities/app-details' +import { AppInstallationPlainClientAPI } from './entities/app-installation' export type PlainClientAPI = { raw: { @@ -704,21 +703,7 @@ export type PlainClientAPI = { delete(params: OptionalDefaults): Promise } appDefinition: AppDefinitionPlainClientAPI - appInstallation: { - get(params: OptionalDefaults): Promise - getMany( - params: OptionalDefaults - ): Promise> - getForOrganization( - params: OptionalDefaults - ): Promise - upsert( - params: OptionalDefaults, - rawData: CreateAppInstallationProps, - headers?: RawAxiosRequestHeaders - ): Promise - delete(params: OptionalDefaults): Promise - } + appInstallation: AppInstallationPlainClientAPI extension: { get(params: OptionalDefaults): Promise getMany( diff --git a/lib/plain/entities/app-installation.ts b/lib/plain/entities/app-installation.ts new file mode 100644 index 0000000000..cf81c3618b --- /dev/null +++ b/lib/plain/entities/app-installation.ts @@ -0,0 +1,102 @@ +import { RawAxiosRequestHeaders } from 'axios' +import { + CollectionProp, + GetAppDefinitionParams, + GetAppInstallationParams, + GetSpaceEnvironmentParams, + PaginationQueryParams, +} from '../../common-types' +import { AppInstallationsForOrganizationProps } from '../../entities/app-definition' +import { AppInstallationProps, CreateAppInstallationProps } from '../../entities/app-installation' +import { OptionalDefaults } from '../wrappers/wrap' + +export type AppInstallationPlainClientAPI = { + /** + * Fetches the App Installation + * @param params entity IDs to identify the App Installation + * @returns the App Installation + * @throws if the request fails, or the App Installation is not found + * @example + * ```javascript + * const appInstallation = await client.appInstallation.get({ + * spaceId: '', + * environmentId: '', + * appDefinitionId: '' + * }); + * ``` + */ + get(params: OptionalDefaults): Promise + /** + * Fetches all App Installations for the given App + * @param params entity IDs to identify the App + * @returns an object containing an array of App Installations + * @throws if the request fails, or the App is not found + * @example + * ```javascript + * const results = await client.appInstallation.getMany({ + * organizationId: "", + * appDefinitionId: "", + * }); + * ``` + */ + getMany( + params: OptionalDefaults + ): Promise> + /** + * Fetches all App Installations for the given Organization + * @param params entity IDs to identify the Organization + * @returns an object containing an array of App Installations + * @throws if the request fails, or the Organization is not found + * @example + * ```javascript + * const results = await client.appInstallation.getForOrganization({ + * organizationId: '', + * appDefinitionId: '', + * }); + * ``` + */ + getForOrganization( + params: OptionalDefaults + ): Promise + /** + * Creates or updates an App Installation + * @param params entity IDs to identify the App Installation to update, or the App to install + * @param rawData the App Installation + * @returns the created or updated App Installation and its metadata + * @throws if the request fails, the App or App Installation is not found, or the payload is malformed + * @example + * ```javascript + * const appInstallation = await client.appInstallation.upsert( + * { + * spaceId: '', + * environmentId: '', + * appDefinitionId: '', + * }, + * { + * parameters: { + * // freeform parameters + * }, + * } + * ); + * ``` + */ + upsert( + params: OptionalDefaults, + rawData: CreateAppInstallationProps, + headers?: RawAxiosRequestHeaders + ): Promise + /** + * Uninstalls the App + * @param params entity IDs to identify the App to uninstall + * @throws if the request fails, or the App Installation is not found + * @example + * ```javascript + * await client.appInstallation.delete({ + * spaceId: '', + * environmentId: '', + * appDefinitionId: '', + * }); + * ``` + */ + delete(params: OptionalDefaults): Promise +} From df1dcc8e9e5acfad98647b6f38f2889e051d2a34 Mon Sep 17 00:00:00 2001 From: Tyler Collins Date: Wed, 20 Sep 2023 09:50:15 -0600 Subject: [PATCH 2/2] refactor: clean up verbiage in other plain client docs --- lib/plain/entities/app-action.ts | 4 ++-- lib/plain/entities/app-bundle.ts | 4 ++-- lib/plain/entities/app-details.ts | 6 +++--- lib/plain/entities/app-upload.ts | 6 +++--- 4 files changed, 10 insertions(+), 10 deletions(-) diff --git a/lib/plain/entities/app-action.ts b/lib/plain/entities/app-action.ts index d8fc686698..9240b8e6f4 100644 --- a/lib/plain/entities/app-action.ts +++ b/lib/plain/entities/app-action.ts @@ -10,7 +10,7 @@ import { OptionalDefaults } from '../wrappers/wrap' export type AppActionPlainClientAPI = { /** - * Fetches the given App Action. + * Fetches the App Action * @param params entity IDs to identify the App Action * @returns the App Action * @throws if the request fails, or the App Action is not found @@ -57,7 +57,7 @@ export type AppActionPlainClientAPI = { params: OptionalDefaults ): Promise> /** - * Deletes the given App Action + * Deletes the App Action * @param params entity IDs to identify the App Action to delete * @returns void * @throws if the request fails, or the App Action is not found diff --git a/lib/plain/entities/app-bundle.ts b/lib/plain/entities/app-bundle.ts index bca367ce2a..7d6dae4118 100644 --- a/lib/plain/entities/app-bundle.ts +++ b/lib/plain/entities/app-bundle.ts @@ -9,7 +9,7 @@ import { OptionalDefaults } from '../wrappers/wrap' export type AppBundlePlainClientAPI = { /** - * Fetches the given App Bundle + * Fetches the App Bundle * @param params entity IDs to identify the App Bundle * @returns the App Bundle * @throws if the request fails, or the App Bundle is not found @@ -39,7 +39,7 @@ export type AppBundlePlainClientAPI = { params: OptionalDefaults ): Promise> /** - * Deletes the given App Bundle + * Deletes the App Bundle * @param params entity IDs to identify the App Bundle * @throws if the request fails, or the App Bundle is not found * @example diff --git a/lib/plain/entities/app-details.ts b/lib/plain/entities/app-details.ts index 585a57d230..ff53d07953 100644 --- a/lib/plain/entities/app-details.ts +++ b/lib/plain/entities/app-details.ts @@ -4,7 +4,7 @@ import { OptionalDefaults } from '../wrappers/wrap' export type AppDetailsPlainClientAPI = { /** - * Upserts an App Detail + * Creates or updates an App Detail * @param params entity IDs to identify the App Definition or App Details * @param payload the App Detail upsert * @returns the updated App Detail and its metadata @@ -31,7 +31,7 @@ export type AppDetailsPlainClientAPI = { payload: CreateAppDetailsProps ): Promise /** - * Fetches the requested App Detail + * Fetches the App Detail * @param params entity IDs to identify the App Detail * @returns the App Detail * @throws if the request fails, or the App Detail is not found @@ -45,7 +45,7 @@ export type AppDetailsPlainClientAPI = { */ get(params: OptionalDefaults): Promise /** - * Fetches the given App Detail + * Fetches the App Detail * @param params entity IDs to identify the App Detail * @throws if the request fails, or the App Detail is not found * @example diff --git a/lib/plain/entities/app-upload.ts b/lib/plain/entities/app-upload.ts index 37b8ffb8d3..fad19822d0 100644 --- a/lib/plain/entities/app-upload.ts +++ b/lib/plain/entities/app-upload.ts @@ -5,7 +5,7 @@ import { OptionalDefaults } from '../wrappers/wrap' export type AppUploadPlainClientAPI = { /** - * Fetches the given App Upload + * Fetches the App Upload * @param params entity IDs to identify the App Upload * @returns the App Upload * @throws if the request fails, or the App Upload is not found @@ -19,7 +19,7 @@ export type AppUploadPlainClientAPI = { */ get(params: OptionalDefaults): Promise /** - * Deletes the given App Upload + * Deletes the App Upload * @param params entity IDs to identify the App Upload * @throws if the request fails, or the App Upload is not found * @example @@ -33,7 +33,7 @@ export type AppUploadPlainClientAPI = { delete(params: OptionalDefaults): Promise /** * Creates an App Upload - * @param params entity IDs to identify the Organization to create the App Upload in + * @param params entity IDs to identify the Organization to upload the App to * @param payload the App Upload * @returns the App Upload * @throws if the request fails, or the Organization is not found