feat(rest-api-client): add plugin.getPlugins, getRequiredPlugins, and…

… getApps (#2896)

Co-authored-by: tasshi / Masaharu Tashiro <33759872+tasshi-me@users.noreply.github.com>
Co-authored-by: mariko hisamatsu <83929890+hisasami@users.noreply.github.com>

packages/rest-api-client/docs/plugin.md

@@ -0,0 +1,98 @@
+# Plug-in
+
+- [getPlugins](#getPlugins)
+- [getRequiredPlugins](#getRequiredPlugins)
+- [getApps](#getApps)
+
+## Overview
+
+```ts
+const client = new KintoneRestAPIClient();
+
+(async () => {
+  try {
+    console.log(await client.plugin.getPlugins({ offset: 1, limit: 10 }));
+  } catch (error) {
+    console.log(error);
+  }
+})();
+```
+
+- All methods are defined on the `plugin` property.
+- This method returns a Promise object that is resolved with an object having properties in each `Returns` section.
+
+## Methods
+
+### getPlugins
+
+Gets the list of plug-ins imported into Kintone.
+
+#### Parameters
+
+| Name   |  Type  | Required | Description                                                                                                |
+| ------ | :----: | :------: | ---------------------------------------------------------------------------------------------------------- |
+| offset | Number |          | The number of plug-ins to skip from the list of installed plug-ins.<br />If ignored, this value is 0.      |
+| limit  | Number |          | The maximum number of plug-ins to retrieve.<br />Must be between 1 and 100.The default<br />number is 100. |
+
+#### Returns
+
+| Name                     |  Type   | Description                                                                                                                                                                                          |
+| ------------------------ | :-----: | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| plugins                  |  Array  | A list of Plug-ins added to the App.<br />Plug-ins are listed in descending order of the datetime they are added.                                                                                    |
+| plugins[].id             | String  | The Plugin ID.                                                                                                                                                                                       |
+| plugins[].name           | String  | The name of the Plugin.                                                                                                                                                                              |
+| plugins[].isMarketPlugin | Boolean | States whether or not the plug-in is a Marketplace plug-in.<br /><strong>true</strong>: The plug-in is a Marketplace plug-in.<br /><strong>false</strong>: The plug-in is not a Marketplace plug-in. |
+| plugins[].version        | String  | The version number of the plug-in                                                                                                                                                                    |
+
+#### Reference
+
+- https://kintone.dev/en/docs/kintone/rest-api/plugins/get-installed-plugins/
+
+### getRequiredPlugins
+
+Gets the list of plug-ins that have been deleted from Kintone, but have already been added to Apps.
+This can occur when a plug-in is installed, added to an App, and then proceeded to be uninstalled from the Kintone environment.
+
+#### Parameters
+
+| Name   |  Type  | Required | Description                                                                                                |
+| ------ | :----: | :------: | ---------------------------------------------------------------------------------------------------------- |
+| offset | Number |          | The number of plug-ins to skip from the list of required plug-ins.<br />If ignored, this value is 0.       |
+| limit  | Number |          | The maximum number of plug-ins to retrieve.<br />Must be between 1 and 100.The default<br />number is 100. |
+
+#### Returns
+
+| Name                     |  Type   | Description                                                                                                                                                                                          |
+| ------------------------ | :-----: | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| plugins                  |  Array  | A list of Plug-ins that needs to be installed.                                                                                                                                                       |
+| plugins[].id             | String  | The Plugin ID.                                                                                                                                                                                       |
+| plugins[].name           | String  | The name of the Plugin.                                                                                                                                                                              |
+| plugins[].isMarketPlugin | Boolean | States whether or not the plug-in is a Marketplace plug-in.<br /><strong>true</strong>: The plug-in is a Marketplace plug-in.<br /><strong>false</strong>: The plug-in is not a Marketplace plug-in. |
+
+#### Reference
+
+- https://kintone.dev/en/docs/kintone/rest-api/plugins/get-required-plugins/
+
+### getApps
+
+Gets Apps that have the specified plug-in added.
+
+#### Parameters
+
+| Name   |  Type  | Required | Description                                                                                            |
+| ------ | :----: | :------: | ------------------------------------------------------------------------------------------------------ |
+| id     | String |   Yes    | The ID of the plug-in.                                                                                 |
+| offset | Number |          | The number of apps to skip from the list of app.<br />If ignored, this value is 0.                     |
+| limit  | Number |          | The maximum number of apps to retrieve.<br />Must be between 1 and 500.The default<br />number is 100. |
+
+#### Returns
+
+| Name        |  Type  | Description                                                                                                    |
+| ----------- | :----: | -------------------------------------------------------------------------------------------------------------- |
+| apps        | Array  | A list of objects containing the App ID and name.<br />Objects are listed in ascending order of their App IDs. |
+| apps[].id   | String | The App ID.                                                                                                    |
+| apps[].name | String | The name of the App.                                                                                           |
+
+#### Reference
+
+- https://kintone.dev/en/docs/kintone/rest-api/plugins/get-plugin-apps/

packages/rest-api-client/src/KintoneRestAPIClient.ts

@@ -4,6 +4,7 @@ import { AppClient } from "./client/AppClient";
 import { RecordClient } from "./client/RecordClient";
 import { SpaceClient } from "./client/SpaceClient";
 import { FileClient } from "./client/FileClient";
+import { PluginClient } from "./client/PluginClient";
 import { DefaultHttpClient } from "./http/";
 import type { ProxyConfig } from "./http/HttpClientInterface";
 import type { BasicAuth, DiscriminatedAuth } from "./types/auth";
@@ -66,6 +67,7 @@ export class KintoneRestAPIClient {
   app: AppClient;
   space: SpaceClient;
   file: FileClient;
+  plugin: PluginClient;
   private bulkRequest_: BulkRequestClient;
   private baseUrl?: string;
 
@@ -97,6 +99,7 @@ export class KintoneRestAPIClient {
     this.app = new AppClient(httpClient, guestSpaceId);
     this.space = new SpaceClient(httpClient, guestSpaceId);
     this.file = new FileClient(httpClient, guestSpaceId);
+    this.plugin = new PluginClient(httpClient);
   }
 
   public static get version() {

packages/rest-api-client/src/client/PluginClient.ts

@@ -0,0 +1,30 @@
+import { BaseClient } from "./BaseClient";
+import type {
+  GetAppsForRequest,
+  GetAppsForResponse,
+  GetPluginsForRequest,
+  GetPluginsForResponse,
+  GetRequiredPluginsForRequest,
+  GetRequiredPluginsForResponse,
+} from "./types/plugin";
+
+export class PluginClient extends BaseClient {
+  public getPlugins(
+    params: GetPluginsForRequest,
+  ): Promise<GetPluginsForResponse> {
+    const path = this.buildPath({ endpointName: "plugins" });
+    return this.client.get(path, params);
+  }
+
+  public getRequiredPlugins(
+    params: GetRequiredPluginsForRequest,
+  ): Promise<GetRequiredPluginsForResponse> {
+    const path = this.buildPath({ endpointName: "plugins/required" });
+    return this.client.get(path, params);
+  }
+
+  public getApps(params: GetAppsForRequest): Promise<GetAppsForResponse> {
+    const path = this.buildPath({ endpointName: "plugin/apps" });
+    return this.client.get(path, params);
+  }
+}

packages/rest-api-client/src/client/__tests__/PluginClient.test.ts

@@ -0,0 +1,80 @@
+import type { MockClient } from "../../http/MockClient";
+import { buildMockClient } from "../../http/MockClient";
+import { KintoneRequestConfigBuilder } from "../../KintoneRequestConfigBuilder";
+import { PluginClient } from "../PluginClient";
+
+describe("PluginClient", () => {
+  let mockClient: MockClient;
+  let pluginClient: PluginClient;
+
+  beforeEach(() => {
+    const requestConfigBuilder = new KintoneRequestConfigBuilder({
+      baseUrl: "https://example.cybozu.com",
+      auth: {
+        type: "password",
+        username: "hoge",
+        password: "foo",
+      },
+    });
+    mockClient = buildMockClient(requestConfigBuilder);
+    pluginClient = new PluginClient(mockClient);
+  });
+
+  describe("getPlugins", () => {
+    const params = {
+      offset: 1,
+      limit: 2,
+    };
+    beforeEach(async () => {
+      await pluginClient.getPlugins(params);
+    });
+    it("should pass the path to the http client", () => {
+      expect(mockClient.getLogs()[0].path).toBe("/k/v1/plugins.json");
+    });
+    it("should send a GET request", () => {
+      expect(mockClient.getLogs()[0].method).toBe("get");
+    });
+    it("should pass the param to the http client", () => {
+      expect(mockClient.getLogs()[0].params).toEqual(params);
+    });
+  });
+
+  describe("getRequiredPlugins", () => {
+    const params = {
+      offset: 1,
+      limit: 2,
+    };
+    beforeEach(async () => {
+      await pluginClient.getRequiredPlugins(params);
+    });
+    it("should pass the path to the http client", () => {
+      expect(mockClient.getLogs()[0].path).toBe("/k/v1/plugins/required.json");
+    });
+    it("should send a GET request", () => {
+      expect(mockClient.getLogs()[0].method).toBe("get");
+    });
+    it("should pass the param to the http client", () => {
+      expect(mockClient.getLogs()[0].params).toEqual(params);
+    });
+  });
+
+  describe("getApps", () => {
+    const params = {
+      id: "pluginId",
+      offset: 1,
+      limit: 2,
+    };
+    beforeEach(async () => {
+      await pluginClient.getApps(params);
+    });
+    it("should pass the path to the http client", () => {
+      expect(mockClient.getLogs()[0].path).toBe("/k/v1/plugin/apps.json");
+    });
+    it("should send a GET request", () => {
+      expect(mockClient.getLogs()[0].method).toBe("get");
+    });
+    it("should pass the param to the http client", () => {
+      expect(mockClient.getLogs()[0].params).toEqual(params);
+    });
+  });
+});

packages/rest-api-client/src/client/__tests__/SpaceClient.test.ts

@@ -15,7 +15,11 @@ describe("SpaceClient", () => {
   beforeEach(() => {
     const requestConfigBuilder = new KintoneRequestConfigBuilder({
       baseUrl: "https://example.cybozu.com",
-      auth: { type: "apiToken", apiToken: "foo" },
+      auth: {
+        type: "password",
+        username: "hoge",
+        password: "foo",
+      },
     });
     mockClient = buildMockClient(requestConfigBuilder);
     spaceClient = new SpaceClient(mockClient);

packages/rest-api-client/src/client/types/index.ts

@@ -5,7 +5,9 @@ export type SpaceID = string | number;
 export type SpaceTemplateID = string | number;
 export type GuestSpaceID = string | number;
 export type ThreadID = string | number;
+export type PluginID = string;
 
 export * from "./record";
 export * from "./app";
 export * from "./space";
+export * from "./plugin";

packages/rest-api-client/src/client/types/plugin/index.ts

@@ -0,0 +1,38 @@
+import type { PluginID } from "..";
+
+type Plugin = {
+  id: string;
+  name: string;
+  isMarketPlugin: boolean;
+  version: string;
+};
+
+type RequiredPlugin = Omit<Plugin, "revision">;
+
+export type GetPluginsForRequest = {
+  offset?: number;
+  limit?: number;
+};
+
+export type GetPluginsForResponse = {
+  plugins: Plugin[];
+};
+
+export type GetRequiredPluginsForRequest = {
+  offset?: number;
+  limit?: number;
+};
+
+export type GetRequiredPluginsForResponse = {
+  plugins: RequiredPlugin[];
+};
+
+export type GetAppsForRequest = {
+  id: PluginID;
+  offset?: number;
+  limit?: number;
+};
+
+export type GetAppsForResponse = {
+  apps: Array<{ id: string; name: string }>;
+};