feat(rest-api-client): add get and update methods for admin notes (#2849

)

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

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

@@ -36,6 +36,8 @@
 - [updateReports](#updateReports)
 - [getAppActions](#getAppActions)
 - [updateAppActions](#updateAppActions)
+- [getAdminNotes](#getAdminNotes)
+- [updateAdminNotes](#updateAdminNotes)
 - [move](#move)
 - [getPlugins](#getPlugins)
 
@@ -1356,6 +1358,52 @@ Updates the [Action](https://get.kintone.help/k/en/user/app_settings/appaction/s
 
 - https://kintone.dev/en/docs/kintone/rest-api/apps/update-action-settings/
 
+### getAdminNotes
+
+Gets notes for app administrators and their settings.
+
+#### Parameters
+
+| Name    |       Type       | Required | Description                                                     |
+| ------- | :--------------: | :------: | --------------------------------------------------------------- |
+| app     | Number or String |   Yes    | The App ID.                                                     |
+| preview |     Boolean      |          | A flag whether to get the app actions for pre-live environment. |
+
+#### Returns
+
+| Name                           |  Type   | Description                                                                  |
+| ------------------------------ | :-----: | ---------------------------------------------------------------------------- |
+| content                        | String  | The content of the notes. If not set, an empty string is returned.           |
+| includeInTemplateAndDuplicates | Boolean | The permission settings to include this note in app templates or duplicates. |
+| revision                       | String  | The revision number of the App settings.                                     |
+
+#### Reference
+
+- https://kintone.dev/en/docs/kintone/rest-api/apps/get-app-admin-notes/
+
+### updateAdminNotes
+
+Updates the notes for App administrators and their settings.
+
+#### Parameters
+
+| Name                           |       Type       | Required | Description                                                                                                                                      |
+| ------------------------------ | :--------------: | :------: | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| app                            | Number or String |   Yes    | The App ID.                                                                                                                                      |
+| content                        |      String      |          | The content of the notes.<br />The content must be between 0 to 10000 characters.<br />If the parameter is omitted, the content will not change. |
+| includeInTemplateAndDuplicates |     Boolean      |          | The permission settings to include this note in app templates or duplicates.                                                                     |
+| revision                       |      String      |          | The revision number of the App settings.                                                                                                         |
+
+#### Returns
+
+| Name     |  Type  | Description                                          |
+| -------- | :----: | ---------------------------------------------------- |
+| revision | String | The revision number after changing the app settings. |
+
+#### Reference
+
+- https://kintone.dev/en/docs/kintone/rest-api/apps/update-app-admin-notes/
+
 ### move
 
 Changes the Space to which an App belongs.

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

@@ -33,6 +33,8 @@ import type {
   ReportForResponse,
   AppActionsForParameter,
   AppActionsForResponse,
+  AdminNotes,
+  AdminNotesForParameter,
   SpaceID,
   PluginLocale,
 } from "./types";
@@ -620,6 +622,29 @@ export class AppClient extends BaseClient {
     return this.client.put(path, params);
   }
 
+  public getAdminNotes(params: { app: AppID; preview?: boolean }): Promise<
+    AdminNotes & {
+      revision: string;
+    }
+  > {
+    const { preview, ...rest } = params;
+    const path = this.buildPathWithGuestSpaceId({
+      endpointName: "app/adminNotes",
+      preview,
+    });
+    return this.client.get(path, rest);
+  }
+
+  public updateAdminNotes(
+    params: AdminNotesForParameter,
+  ): Promise<{ revision: string }> {
+    const path = this.buildPathWithGuestSpaceId({
+      endpointName: "app/adminNotes",
+      preview: true,
+    });
+    return this.client.put(path, params);
+  }
+
   public move(params: { app: AppID; space: SpaceID | null }): Promise<{}> {
     const path = this.buildPath({
       endpointName: "app/move",

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

@@ -1312,6 +1312,73 @@ describe("AppClient", () => {
   });
 });
 
+describe("AppClient: AdminNotes", () => {
+  let mockClient: MockClient;
+  let appClient: AppClient;
+
+  beforeEach(() => {
+    const requestConfigBuilder = new KintoneRequestConfigBuilder({
+      baseUrl: "https://example.cybozu.com",
+      auth: { type: "apiToken", apiToken: "foo" },
+    });
+    mockClient = buildMockClient(requestConfigBuilder);
+    appClient = new AppClient(mockClient);
+  });
+  describe("getAdminNotes", () => {
+    const params = { app: APP_ID } as const;
+    describe("without preview", () => {
+      beforeEach(async () => {
+        await appClient.getAdminNotes(params);
+      });
+      it("should pass the path to the http client", () => {
+        expect(mockClient.getLogs()[0].path).toBe("/k/v1/app/adminNotes.json");
+      });
+      it("should send a get request", () => {
+        expect(mockClient.getLogs()[0].method).toBe("get");
+      });
+      it("should pass app as a param to the http client", () => {
+        expect(mockClient.getLogs()[0].params).toEqual(params);
+      });
+    });
+    describe("preview: true", () => {
+      beforeEach(async () => {
+        await appClient.getAdminNotes({
+          ...params,
+          preview: true,
+        });
+      });
+      it("should pass the path to the http client", () => {
+        expect(mockClient.getLogs()[0].path).toBe(
+          "/k/v1/preview/app/adminNotes.json",
+        );
+      });
+      it("should send a get request", () => {
+        expect(mockClient.getLogs()[0].method).toBe("get");
+      });
+      it("should pass app as a param to the http client", () => {
+        expect(mockClient.getLogs()[0].params).toEqual(params);
+      });
+    });
+  });
+  describe("updateAdminNotes", () => {
+    const params = { app: APP_ID } as const;
+    beforeEach(async () => {
+      await appClient.updateAdminNotes(params);
+    });
+    it("should pass the path to the http client", () => {
+      expect(mockClient.getLogs()[0].path).toBe(
+        "/k/v1/preview/app/adminNotes.json",
+      );
+    });
+    it("should send a put request", () => {
+      expect(mockClient.getLogs()[0].method).toBe("put");
+    });
+    it("should pass app, content, includeInTemplateAndDuplicates, and revision as a param to the http client", () => {
+      expect(mockClient.getLogs()[0].params).toEqual(params);
+    });
+  });
+});
+
 describe("AppClient: move", () => {
   let mockClient: MockClient;
   let appClient: AppClient;
@@ -1362,9 +1429,6 @@ describe("AppClient: plugins", () => {
       it("should pass the path to the http client", () => {
         expect(mockClient.getLogs()[0].path).toBe("/k/v1/app/plugins.json");
       });
-      it("should send a get request", () => {
-        expect(mockClient.getLogs()[0].method).toBe("get");
-      });
       it("should pass app and lang as a param to the http client", () => {
         expect(mockClient.getLogs()[0].params).toEqual(params);
       });

packages/rest-api-client/src/client/types/app/adminNotes.ts

@@ -0,0 +1,11 @@
+import type { AppID, Revision } from "..";
+
+export type AdminNotes = {
+  content: string;
+  includeInTemplateAndDuplicates: boolean;
+};
+
+export type AdminNotesForParameter = Partial<AdminNotes> & {
+  app: AppID;
+  revision?: Revision;
+};

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

@@ -27,3 +27,4 @@ export * from "./customize";
 export * from "./notification";
 export * from "./report";
 export * from "./action";
+export * from "./adminNotes";