docs: add inline docs for the plain client App Installation interface [EXT-4729]

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<GetSpaceParams & { apiKeyId: string }>): Promise<any>
   }
   appDefinition: AppDefinitionPlainClientAPI
-  appInstallation: {
-    get(params: OptionalDefaults<GetAppInstallationParams>): Promise<AppInstallationProps>
-    getMany(
-      params: OptionalDefaults<GetSpaceEnvironmentParams & PaginationQueryParams>
-    ): Promise<CollectionProp<AppInstallationProps>>
-    getForOrganization(
-      params: OptionalDefaults<GetAppDefinitionParams>
-    ): Promise<AppInstallationsForOrganizationProps>
-    upsert(
-      params: OptionalDefaults<GetAppInstallationParams>,
-      rawData: CreateAppInstallationProps,
-      headers?: RawAxiosRequestHeaders
-    ): Promise<AppInstallationProps>
-    delete(params: OptionalDefaults<GetAppInstallationParams>): Promise<any>
-  }
+  appInstallation: AppInstallationPlainClientAPI
   extension: {
     get(params: OptionalDefaults<GetExtensionParams & QueryParams>): Promise<ExtensionProps>
     getMany(

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<GetAppActionsForEnvParams & QueryParams>
   ): Promise<CollectionProp<AppActionProps>>
   /**
-   * 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

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<GetAppDefinitionParams & QueryParams>
   ): Promise<CollectionProp<AppBundleProps>>
   /**
-   * 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

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<AppDetailsProps>
   /**
-   * 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<GetAppDefinitionParams>): Promise<AppDetailsProps>
   /**
-   * 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

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: '<space_id>',
+   *   environmentId: '<environment_id>',
+   *   appDefinitionId: '<app_definition_id>'
+   * });
+   * ```
+   */
+  get(params: OptionalDefaults<GetAppInstallationParams>): Promise<AppInstallationProps>
+  /**
+   * 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: "<org_id>",
+   *   appDefinitionId: "<app_definition_id>",
+   * });
+   * ```
+   */
+  getMany(
+    params: OptionalDefaults<GetSpaceEnvironmentParams & PaginationQueryParams>
+  ): Promise<CollectionProp<AppInstallationProps>>
+  /**
+   * 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: '<organization_id>',
+   *   appDefinitionId: '<app_definition_id>',
+   * });
+   * ```
+   */
+  getForOrganization(
+    params: OptionalDefaults<GetAppDefinitionParams>
+  ): Promise<AppInstallationsForOrganizationProps>
+  /**
+   * 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: '<space_id>',
+   *     environmentId: '<environment_id>',
+   *     appDefinitionId: '<app_definition_id>',
+   *   },
+   *   {
+   *     parameters: {
+   *       // freeform parameters
+   *     },
+   *   }
+   * );
+   * ```
+   */
+  upsert(
+    params: OptionalDefaults<GetAppInstallationParams>,
+    rawData: CreateAppInstallationProps,
+    headers?: RawAxiosRequestHeaders
+  ): Promise<AppInstallationProps>
+  /**
+   * 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: '<space_id>',
+   *   environmentId: '<environment_id>',
+   *   appDefinitionId: '<app_definition_id>',
+   * });
+   * ```
+   */
+  delete(params: OptionalDefaults<GetAppInstallationParams>): Promise<any>
+}

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<GetAppUploadParams>): Promise<AppUploadProps>
   /**
-   * 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<GetAppUploadParams>): Promise<void>
   /**
    * 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