fix(core): add response bodies for organization user endpoints (#8626)

* fix(core, api): add respone bodies for organization user endpoints
- Added body to `/api/organizations/{id}/users`
- Added body to `/api/organizations/{id}/users/{userId}/roles`

* fix(core, api): add response bodies for organization user endpoints
- Added changeset

* fix(core, api): add response bodies for organization user endpoints
- Added unit tests

* fix(core, api): add response bodies for organization user endpoints
- Fixed changeset file
- Reorganized tests into two files

* fix(core): add response bodies for organization user endpoints - Review suggestions

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* fix(core, api): add response bodies for organization user endpoints
- review suggestions

* fix(core, api): add response bodies for organization user endpoints
- review suggestions

---------

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: konlanx

.changeset/bright-planes-dance.md

@@ -0,0 +1,9 @@
+---
+"@logto/integration-tests": patch
+"@logto/core": patch
+---
+
+return response bodies from organization user and role assignment APIs
+
+- POST `/organizations/:id/users` now returns `{ userIds: string[] }` echoing the user IDs that were sent with the request
+- POST `/organizations/:id/users/:userId/roles` now returns `{ organizationRoleIds: string[] }` with the final deduplicated role IDs that were assigned, resolved from any provided role names

packages/core/src/routes/organization/user/index.openapi.json

@@ -25,7 +25,23 @@
         },
         "responses": {
           "201": {
-            "description": "Users were added to the organization successfully."
+            "description": "Users were added to the organization successfully.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "userIds": {
+                      "type": "array",
+                      "items": {
+                        "type": "string"
+                      },
+                      "description": "An array of user IDs processed from the request. This may include IDs that were already members of the organization."
+                    }
+                  }
+                }
+              }
+            }
           },
           "422": {
             "description": "At least one of the IDs provided is not valid. For example, the organization ID or user ID does not exist."
@@ -180,7 +196,23 @@
         },
         "responses": {
           "201": {
-            "description": "Roles were assigned to the user successfully."
+            "description": "Roles were assigned to the user successfully.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "organizationRoleIds": {
+                      "type": "array",
+                      "items": {
+                        "type": "string"
+                      },
+                      "description": "An array of organization role IDs that were assigned to the user, deduplicated and resolved from any provided role names."
+                    }
+                  }
+                }
+              }
+            }
           },
           "422": {
             "description": "The user is not a member of the organization; or at least one of the IDs provided is not valid. For example, the organization ID or organization role ID does not exist; or at least one of the role names provided is not valid. For example, the organization role name does not exist."

packages/core/src/routes/organization/user/index.ts

@@ -54,6 +54,7 @@ export default function userRoutes(
     koaGuard({
       params: z.object({ id: z.string().min(1) }),
       body: z.object({ userIds: z.string().min(1).array().nonempty() }),
+      response: z.object({ userIds: z.string().min(1).array() }),
       status: [201, 403, 422],
     }),
     async (ctx, next) => {
@@ -72,6 +73,7 @@ export default function userRoutes(
         ...userIds.map((userId) => ({ organizationId: id, userId }))
       );
 
+      ctx.body = { userIds };
       ctx.status = 201;
 
       // Trigger hook event

packages/core/src/routes/organization/user/role-relations.ts

@@ -74,6 +74,7 @@ export default function userRoleRelationRoutes(
         organizationRoleIds: z.string().min(1).array().optional(),
         organizationRoleNames: z.string().min(1).array().optional(),
       }),
+      response: z.object({ organizationRoleIds: z.string().min(1).array() }),
       status: [201, 422],
     }),
     async (ctx, next) => {
@@ -110,6 +111,7 @@ export default function userRoleRelationRoutes(
         }))
       );
 
+      ctx.body = { organizationRoleIds: roleIds };
       ctx.status = 201;
       return next();
     }

packages/integration-tests/src/api/organization.ts

@@ -46,8 +46,10 @@ export class OrganizationApi extends ApiFactory<Organization, Omit<CreateOrganiz
     });
   }
 
-  async addUsers(id: string, userIds: string[]): Promise<void> {
-    await authedAdminApi.post(`${this.path}/${id}/users`, { json: { userIds } });
+  async addUsers(id: string, userIds: string[]): Promise<{ userIds: string[] }> {
+    return authedAdminApi
+      .post(`${this.path}/${id}/users`, { json: { userIds } })
+      .json<{ userIds: string[] }>();
   }
 
   async replaceUsers(id: string, userIds: string[]): Promise<void> {
@@ -71,10 +73,12 @@ export class OrganizationApi extends ApiFactory<Organization, Omit<CreateOrganiz
     userId: string,
     organizationRoleIds: string[],
     organizationRoleNames?: string[]
-  ): Promise<void> {
-    await authedAdminApi.post(`${this.path}/${id}/users/${userId}/roles`, {
-      json: { organizationRoleIds, organizationRoleNames },
-    });
+  ): Promise<{ organizationRoleIds: string[] }> {
+    return authedAdminApi
+      .post(`${this.path}/${id}/users/${userId}/roles`, {
+        json: { organizationRoleIds, organizationRoleNames },
+      })
+      .json<{ organizationRoleIds: string[] }>();
   }
 
   async replaceUserRoles(