feat(rest-api-client): add space.addSpaceFromTemplate() method (#2638)

kintone · Mar 27, 2024 · 4df57dd · 4df57dd
1 parent 64053a0
commit 4df57dd
Show file tree

Hide file tree

Showing 6 changed files with 145 additions and 2 deletions.
diff --git a/examples/rest-api-client-demo/src/space.ts b/examples/rest-api-client-demo/src/space.ts
@@ -1,6 +1,7 @@
 import type { KintoneRestAPIClient } from "@kintone/rest-api-client";
 
 const SPACE_ID = 8;
+const SPACE_TEMPLATE_ID = 1;
 const GUEST_SPACE_ID = 9;
 const THREAD_ID = 8;
 
@@ -174,4 +175,43 @@ export class Space {
       console.log(error);
     }
   }
+
+  public async addSpaceFromTemplate() {
+    const spaceTemplate = {
+      id: SPACE_TEMPLATE_ID,
+      name: "New Space from Template",
+      members: [
+        {
+          entity: {
+            code: "cybozu",
+            type: "USER" as const,
+          },
+          isAdmin: true,
+        },
+        {
+          entity: {
+            code: "user1",
+            type: "USER" as const,
+          },
+          isAdmin: false,
+        },
+        {
+          entity: {
+            code: "group1",
+            type: "GROUP" as const,
+          },
+          isAdmin: false,
+          includeSubs: true,
+        },
+      ],
+      isPrivate: false,
+      isGuest: false,
+    };
+
+    try {
+      console.log(await this.client.space.addSpaceFromTemplate(spaceTemplate));
+    } catch (error) {
+      console.log(error);
+    }
+  }
 }
diff --git a/packages/rest-api-client/docs/space.md b/packages/rest-api-client/docs/space.md
@@ -10,6 +10,7 @@
 - [addGuests](#addGuests)
 - [deleteGuests](#deleteGuests)
 - [updateSpaceGuests](#updateSpaceGuests)
+- [addSpaceFromTemplate](#addSpaceFromTemplate)
 
 ## Overview
 
@@ -291,3 +292,33 @@ An empty object.
 #### Reference
 
 - https://kintone.dev/en/docs/kintone/rest-api/spaces/update-guest-members/
+
+### addSpaceFromTemplate
+
+Creates a Space from a Space template.
+
+#### Parameters
+
+| Name                  |       Type       |  Required   | Description                                                                                                                                                                                                                                                                                                                                                |
+| --------------------- | :--------------: | :---------: | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| id                    | Number or String |     Yes     | The Space Template ID.<br />[Check here](https://get.kintone.help/k/en/admin/space_admin/manage_spacetemplate/add_spacetemplate.html) for instructions on creating Space Templates.<br />The Space Template ID is listed on the Space Templates list page, found under https://{domainname}.kintone.com/k/admin/system/spacetemplate/                      |
+| name                  |      String      |     Yes     | The new name of the Space.                                                                                                                                                                                                                                                                                                                                 |
+| members               |      Array       |     Yes     | A list of members of the Space.<br />At least one Space Administrator must be specified.<br />Inactive and deleted users cannot be specified.                                                                                                                                                                                                              |
+| members[].entity      |      Object      |     Yes     | The entity information of the Space member.<br />Guest users cannot be specified.                                                                                                                                                                                                                                                                          |
+| members[].entity.type |      String      |     Yes     | The entity type of the Space member.<br />- **USER**: User<br />- **Group**: Group<br />- **ORGANIZATION**: Department                                                                                                                                                                                                                                     |
+| members[].entity.code |      String      |     Yes     | The code of the entity.                                                                                                                                                                                                                                                                                                                                    |
+| members[].isAdmin     |     Boolean      | Conditional | The Space Administration settings of the user.<br />- **true**: The member will be the Administrator of the Space.<br />- **false**: The member will not be the Administrator of the Space.<br />At least 1 Space Administrator is required to be set in the API call.<br/>If ignored, this value is **false**.                                            |
+| members[].includeSubs |     Boolean      |             | The "**Include Affiliated Departments**" settings of the department.<br />- **true**: Affiliated departments will be included.<br />- **false**: Affiliated departments will not be included.<br />If ignored, this value is **false**.                                                                                                                    |
+| isPrivate             |     Boolean      |             | The "Private" settings of the Space.<br />- **true**: The Space will be Private.<br />- **false**: The Space will not be Private.<br />If the isGuest parameter is set to **true**, this value is also **true**.<br />If ignored, this value is **false**.                                                                                                 |
+| isGuest               |     Boolean      |             | The Guest Space settings of the Space.<br />- **true**: The Space will be a Guest Space<br />- **false**: The Space will be a normal Space.<br />If ignored, this value is **false**.                                                                                                                                                                      |
+| fixedMember           |     Boolean      |             | The "**Block users from joining or leaving the space and following or unfollowing the threads.\***" settings of the Space.<br />- **true**: Users will not be able to join/leave the Space or follow/unfollow threads.<br />- **false**: Users will be able to join/leave the Space and follow/unfollow threads.<br />If ignored, this value is **false**. |
+
+#### Returns
+
+| Name |  Type  | Description                        |
+| ---- | :----: | ---------------------------------- |
+| id   | String | The Space ID of the created Space. |
+
+#### Reference
+
+- https://kintone.dev/en/docs/kintone/rest-api/spaces/add-space/
diff --git a/packages/rest-api-client/src/client/BaseClient.ts b/packages/rest-api-client/src/client/BaseClient.ts
@@ -19,4 +19,14 @@ export abstract class BaseClient {
       guestSpaceId: this.guestSpaceId,
     });
   }
+
+  /**
+   * This method is used to build the endpoint for the API that does not support the guest space URL.
+   * Otherwise, please use `buildPathWithGuestSpaceId` instead.
+   * @param params
+   * @protected
+   */
+  protected buildPath(params: { endpointName: string; preview?: boolean }) {
+    return buildPath(params);
+  }
 }
diff --git a/packages/rest-api-client/src/client/SpaceClient.ts b/packages/rest-api-client/src/client/SpaceClient.ts
@@ -7,6 +7,7 @@ import type {
   SpaceMemberForRequest,
   GuestSpaceID,
   Guest,
+  SpaceTemplateID,
 } from "./types";
 import { BaseClient } from "./BaseClient";
 
@@ -70,14 +71,14 @@ export class SpaceClient extends BaseClient {
   }
 
   public addGuests(params: { guests: Guest[] }): Promise<{}> {
-    const path = this.buildPathWithGuestSpaceId({
+    const path = this.buildPath({
       endpointName: "guests",
     });
     return this.client.post(path, params);
   }
 
   public deleteGuests(params: { guests: string[] }): Promise<{}> {
-    const path = this.buildPathWithGuestSpaceId({
+    const path = this.buildPath({
       endpointName: "guests",
     });
     return this.client.delete(path, params);
@@ -92,4 +93,18 @@ export class SpaceClient extends BaseClient {
     });
     return this.client.put(path, params);
   }
+
+  public addSpaceFromTemplate(params: {
+    id: SpaceTemplateID;
+    name: string;
+    members: SpaceMemberForRequest[];
+    isPrivate?: boolean;
+    isGuest?: boolean;
+    fixedMember?: boolean;
+  }): Promise<{ id: SpaceID }> {
+    const path = this.buildPath({
+      endpointName: "template/space",
+    });
+    return this.client.post(path, params);
+  }
 }
diff --git a/packages/rest-api-client/src/client/__tests__/SpaceClient.test.ts b/packages/rest-api-client/src/client/__tests__/SpaceClient.test.ts
@@ -5,6 +5,7 @@ import { KintoneRequestConfigBuilder } from "../../KintoneRequestConfigBuilder";
 import type { ThreadComment } from "../types";
 
 const SPACE_ID = 1;
+const SPACE_TEMPLATE_ID = 1;
 const THREAD_ID = 1;
 
 describe("SpaceClient", () => {
@@ -258,6 +259,51 @@ describe("SpaceClient", () => {
       expect(mockClient.getLogs()[0].params).toEqual(params);
     });
   });
+
+  describe("addSpaceFromTemplate", () => {
+    const params = {
+      id: SPACE_TEMPLATE_ID,
+      name: "Space from Template",
+      members: [
+        {
+          entity: {
+            code: "user1",
+            type: "USER" as const,
+          },
+          isAdmin: true,
+        },
+        {
+          entity: {
+            code: "user2",
+            type: "USER" as const,
+          },
+          isAdmin: false,
+        },
+        {
+          entity: {
+            code: "group1",
+            type: "GROUP" as const,
+          },
+          isAdmin: false,
+          includeSubs: true,
+        },
+      ],
+      isPrivate: true,
+      isGuest: false,
+    };
+    beforeEach(async () => {
+      await spaceClient.addSpaceFromTemplate(params);
+    });
+    it("should pass the path to the http client", () => {
+      expect(mockClient.getLogs()[0].path).toBe("/k/v1/template/space.json");
+    });
+    it("should send a POST request", () => {
+      expect(mockClient.getLogs()[0].method).toBe("post");
+    });
+    it("should pass correct parameters to the http client", () => {
+      expect(mockClient.getLogs()[0].params).toEqual(params);
+    });
+  });
 });
 
 describe("SpaceClient with guestSpaceId", () => {

diff --git a/packages/rest-api-client/src/client/types/index.ts b/packages/rest-api-client/src/client/types/index.ts
@@ -2,6 +2,7 @@ export type AppID = string | number;
 export type RecordID = string | number;
 export type Revision = string | number;
 export type SpaceID = string | number;
+export type SpaceTemplateID = string | number;
 export type GuestSpaceID = string | number;
 export type ThreadID = string | number;