@dotcms/ai 26.8.19-3 → 26.8.28-1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dotcms/ai",
-  "version": "26.08.19-03",
+  "version": "26.08.28-01",
   "description": "The dotCMS agentic runtime — run model-written or human-written code safely against a dotCMS instance, with auth and policy owned in one place.",
   "repository": {
     "type": "git",

package/spec.cjs.js

@@ -4965,7 +4965,7 @@ var paths = {
 	},
 	"/api/v1/roles/{roleid}/users": {
 		"delete": {
-			description: "Bulk-removes the DIRECT membership of the given users from the role. The batch has PARTIAL-SUCCESS semantics: it never fails as a whole once the role resolves — every removable membership is removed and every other entry is reported in the skipped list with a reason: not_found (no user matches the id), inherited (the user is not a direct member — the membership is inherited through the role hierarchy, or the user is not a member at all; inherited membership can only be revoked by removing the user from the ancestor role that grants it), or error (unexpected per-user failure, logged server-side). Removals are committed per user, so entries already processed stay removed regardless of later entries.",
+			description: "Bulk-removes the DIRECT membership of the given users from the role. The batch has PARTIAL-SUCCESS semantics: it never fails as a whole once the role resolves — every removable membership is removed and every other entry is reported in the skipped list with a reason: not_found (no user matches the id), inherited (the user is not a direct member — the membership is inherited through the role hierarchy, or the user is not a member at all; inherited membership can only be revoked by removing the user from the ancestor role that grants it), or error (unexpected per-user failure, logged server-side). Removals are committed per user, so entries already processed stay removed regardless of later entries. Only user-assignable roles (editUsers=true) accept membership changes: a role whose editUsers flag is false — e.g. a user's individual role or a system role — is rejected with 403 for the whole request, mirroring the grant endpoint.",
 			operationId: "removeUsersFromRole",
 			parameters: [
 				{
@@ -5019,7 +5019,7 @@ var paths = {
 						"application/json": {
 						}
 					},
-					description: "Forbidden - admin permissions required"
+					description: "Forbidden - admin permissions required, or the role's editUsers flag is false"
 				},
 				"404": {
 					content: {
@@ -5033,6 +5033,110 @@ var paths = {
 			tags: [
 				"Roles"
 			]
+		},
+		get: {
+			description: "Returns the paginated list of users directly granted the given role, using the standard user serialization (email address included). Grants inherited through the role hierarchy are not included.",
+			operationId: "loadUsersByRoleId",
+			parameters: [
+				{
+					description: "Id of the role to list users for",
+					"in": "path",
+					name: "roleid",
+					required: true,
+					schema: {
+						type: "string"
+					}
+				},
+				{
+					description: "Filter matching user id, first name, last name, email or full name",
+					"in": "query",
+					name: "filter",
+					schema: {
+						type: "string"
+					}
+				},
+				{
+					description: "Page number for pagination",
+					"in": "query",
+					name: "page",
+					schema: {
+						type: "integer",
+						format: "int32",
+						"default": 1
+					}
+				},
+				{
+					description: "Number of items per page",
+					"in": "query",
+					name: "per_page",
+					schema: {
+						type: "integer",
+						format: "int32",
+						"default": 40
+					}
+				},
+				{
+					description: "Column name for sorting results",
+					"in": "query",
+					name: "orderby",
+					schema: {
+						type: "string"
+					}
+				},
+				{
+					description: "Sorting direction: ASC or DESC",
+					"in": "query",
+					name: "direction",
+					schema: {
+						type: "string",
+						"default": "ASC"
+					}
+				}
+			],
+			responses: {
+				"200": {
+					content: {
+						"application/json": {
+							schema: {
+								$ref: "#/components/schemas/ResponseEntityPaginatedDataView"
+							}
+						}
+					},
+					description: "Users retrieved successfully"
+				},
+				"400": {
+					content: {
+						"application/json": {
+						}
+					},
+					description: "Bad request - invalid pagination or sorting parameters"
+				},
+				"401": {
+					content: {
+						"application/json": {
+						}
+					},
+					description: "Unauthorized - authentication required"
+				},
+				"403": {
+					content: {
+						"application/json": {
+						}
+					},
+					description: "Forbidden - roles portlet access required"
+				},
+				"404": {
+					content: {
+						"application/json": {
+						}
+					},
+					description: "Role not found"
+				}
+			},
+			summary: "Get the users directly granted a role",
+			tags: [
+				"Roles"
+			]
 		}
 	},
 	"/api/v1/roles/{roleid}/users/{userId}": {
@@ -7502,7 +7606,7 @@ var paths = {
 			]
 		},
 		put: {
-			description: "Updates an existing user's information including personal details, roles, and account settings. Only admin users or users with appropriate portlet access can perform this operation.",
+			description: "Updates an existing user's information including personal details, roles, and account settings. Only admin users or users with appropriate portlet access can perform this operation. The optional roles list carries role KEYS and is the user's complete desired set of user-assignable roles (editUsers=true): omit the field to leave roles untouched, send a non-empty list to replace the user-assignable role set, or send an empty list to remove all of the user's user-assignable roles. System-managed memberships (e.g. the user's individual role) are never modified, keys that resolve to no role are ignored, and null or blank entries are rejected with 400. Note that roles without a key cannot be expressed in this list — manage those through the role-centric /v1/roles/{roleId}/users endpoints instead.",
 			operationId: "updateUser",
 			requestBody: {
 				content: {
@@ -7512,7 +7616,7 @@ var paths = {
 						}
 					}
 				},
-				description: "User update data including personal information, roles, and account settings",
+				description: "User update data including personal information, roles, and account settings. The roles list (role keys) is the complete desired set of user-assignable roles: absent = untouched, empty = remove all user-assignable roles, non-empty = replace.",
 				required: true
 			},
 			responses: {
@@ -20504,6 +20608,13 @@ var components = {
 		RoleView: {
 			type: "object",
 			properties: {
+				childCount: {
+					type: "integer",
+					format: "int32",
+					description: "Number of direct child roles, independent of children hydration",
+					example: 3,
+					minimum: 0
+				},
 				dbfqn: {
 					type: "string"
 				},
@@ -20545,8 +20656,19 @@ var components = {
 				},
 				system: {
 					type: "boolean"
+				},
+				userCount: {
+					type: "integer",
+					format: "int32",
+					description: "Number of users directly granted this role, matching the totals of the role users listing: inherited grants and hidden users (system, anonymous, default, flagged for deletion) are not included",
+					example: 12,
+					minimum: 0
 				}
-			}
+			},
+			required: [
+				"childCount",
+				"userCount"
+			]
 		},
 		RunningId: {
 			type: "object",
@@ -22403,8 +22525,15 @@ var components = {
 				},
 				roles: {
 					type: "array",
+					description: "Role keys or role IDs (roles created without a key can only be referenced by ID). On update: field absent = roles untouched; [] = remove all user-assignable roles; otherwise the complete user-assignable role set. On create: absent or empty = default Front-end User role. Unknown entries are ignored.",
+					example: [
+						"DOTCMS_BACK_END_USER",
+						"48190c8c-42c4-46af-8d1a-0cd5db894797"
+					],
 					items: {
-						type: "string"
+						type: "string",
+						description: "Role keys or role IDs (roles created without a key can only be referenced by ID). On update: field absent = roles untouched; [] = remove all user-assignable roles; otherwise the complete user-assignable role set. On create: absent or empty = default Front-end User role. Unknown entries are ignored.",
+						example: "[\"DOTCMS_BACK_END_USER\",\"48190c8c-42c4-46af-8d1a-0cd5db894797\"]"
 					}
 				},
 				timeZoneId: {

package/spec.esm.js

@@ -4963,7 +4963,7 @@ var paths = {
 	},
 	"/api/v1/roles/{roleid}/users": {
 		"delete": {
-			description: "Bulk-removes the DIRECT membership of the given users from the role. The batch has PARTIAL-SUCCESS semantics: it never fails as a whole once the role resolves — every removable membership is removed and every other entry is reported in the skipped list with a reason: not_found (no user matches the id), inherited (the user is not a direct member — the membership is inherited through the role hierarchy, or the user is not a member at all; inherited membership can only be revoked by removing the user from the ancestor role that grants it), or error (unexpected per-user failure, logged server-side). Removals are committed per user, so entries already processed stay removed regardless of later entries.",
+			description: "Bulk-removes the DIRECT membership of the given users from the role. The batch has PARTIAL-SUCCESS semantics: it never fails as a whole once the role resolves — every removable membership is removed and every other entry is reported in the skipped list with a reason: not_found (no user matches the id), inherited (the user is not a direct member — the membership is inherited through the role hierarchy, or the user is not a member at all; inherited membership can only be revoked by removing the user from the ancestor role that grants it), or error (unexpected per-user failure, logged server-side). Removals are committed per user, so entries already processed stay removed regardless of later entries. Only user-assignable roles (editUsers=true) accept membership changes: a role whose editUsers flag is false — e.g. a user's individual role or a system role — is rejected with 403 for the whole request, mirroring the grant endpoint.",
 			operationId: "removeUsersFromRole",
 			parameters: [
 				{
@@ -5017,7 +5017,7 @@ var paths = {
 						"application/json": {
 						}
 					},
-					description: "Forbidden - admin permissions required"
+					description: "Forbidden - admin permissions required, or the role's editUsers flag is false"
 				},
 				"404": {
 					content: {
@@ -5031,6 +5031,110 @@ var paths = {
 			tags: [
 				"Roles"
 			]
+		},
+		get: {
+			description: "Returns the paginated list of users directly granted the given role, using the standard user serialization (email address included). Grants inherited through the role hierarchy are not included.",
+			operationId: "loadUsersByRoleId",
+			parameters: [
+				{
+					description: "Id of the role to list users for",
+					"in": "path",
+					name: "roleid",
+					required: true,
+					schema: {
+						type: "string"
+					}
+				},
+				{
+					description: "Filter matching user id, first name, last name, email or full name",
+					"in": "query",
+					name: "filter",
+					schema: {
+						type: "string"
+					}
+				},
+				{
+					description: "Page number for pagination",
+					"in": "query",
+					name: "page",
+					schema: {
+						type: "integer",
+						format: "int32",
+						"default": 1
+					}
+				},
+				{
+					description: "Number of items per page",
+					"in": "query",
+					name: "per_page",
+					schema: {
+						type: "integer",
+						format: "int32",
+						"default": 40
+					}
+				},
+				{
+					description: "Column name for sorting results",
+					"in": "query",
+					name: "orderby",
+					schema: {
+						type: "string"
+					}
+				},
+				{
+					description: "Sorting direction: ASC or DESC",
+					"in": "query",
+					name: "direction",
+					schema: {
+						type: "string",
+						"default": "ASC"
+					}
+				}
+			],
+			responses: {
+				"200": {
+					content: {
+						"application/json": {
+							schema: {
+								$ref: "#/components/schemas/ResponseEntityPaginatedDataView"
+							}
+						}
+					},
+					description: "Users retrieved successfully"
+				},
+				"400": {
+					content: {
+						"application/json": {
+						}
+					},
+					description: "Bad request - invalid pagination or sorting parameters"
+				},
+				"401": {
+					content: {
+						"application/json": {
+						}
+					},
+					description: "Unauthorized - authentication required"
+				},
+				"403": {
+					content: {
+						"application/json": {
+						}
+					},
+					description: "Forbidden - roles portlet access required"
+				},
+				"404": {
+					content: {
+						"application/json": {
+						}
+					},
+					description: "Role not found"
+				}
+			},
+			summary: "Get the users directly granted a role",
+			tags: [
+				"Roles"
+			]
 		}
 	},
 	"/api/v1/roles/{roleid}/users/{userId}": {
@@ -7500,7 +7604,7 @@ var paths = {
 			]
 		},
 		put: {
-			description: "Updates an existing user's information including personal details, roles, and account settings. Only admin users or users with appropriate portlet access can perform this operation.",
+			description: "Updates an existing user's information including personal details, roles, and account settings. Only admin users or users with appropriate portlet access can perform this operation. The optional roles list carries role KEYS and is the user's complete desired set of user-assignable roles (editUsers=true): omit the field to leave roles untouched, send a non-empty list to replace the user-assignable role set, or send an empty list to remove all of the user's user-assignable roles. System-managed memberships (e.g. the user's individual role) are never modified, keys that resolve to no role are ignored, and null or blank entries are rejected with 400. Note that roles without a key cannot be expressed in this list — manage those through the role-centric /v1/roles/{roleId}/users endpoints instead.",
 			operationId: "updateUser",
 			requestBody: {
 				content: {
@@ -7510,7 +7614,7 @@ var paths = {
 						}
 					}
 				},
-				description: "User update data including personal information, roles, and account settings",
+				description: "User update data including personal information, roles, and account settings. The roles list (role keys) is the complete desired set of user-assignable roles: absent = untouched, empty = remove all user-assignable roles, non-empty = replace.",
 				required: true
 			},
 			responses: {
@@ -20502,6 +20606,13 @@ var components = {
 		RoleView: {
 			type: "object",
 			properties: {
+				childCount: {
+					type: "integer",
+					format: "int32",
+					description: "Number of direct child roles, independent of children hydration",
+					example: 3,
+					minimum: 0
+				},
 				dbfqn: {
 					type: "string"
 				},
@@ -20543,8 +20654,19 @@ var components = {
 				},
 				system: {
 					type: "boolean"
+				},
+				userCount: {
+					type: "integer",
+					format: "int32",
+					description: "Number of users directly granted this role, matching the totals of the role users listing: inherited grants and hidden users (system, anonymous, default, flagged for deletion) are not included",
+					example: 12,
+					minimum: 0
 				}
-			}
+			},
+			required: [
+				"childCount",
+				"userCount"
+			]
 		},
 		RunningId: {
 			type: "object",
@@ -22401,8 +22523,15 @@ var components = {
 				},
 				roles: {
 					type: "array",
+					description: "Role keys or role IDs (roles created without a key can only be referenced by ID). On update: field absent = roles untouched; [] = remove all user-assignable roles; otherwise the complete user-assignable role set. On create: absent or empty = default Front-end User role. Unknown entries are ignored.",
+					example: [
+						"DOTCMS_BACK_END_USER",
+						"48190c8c-42c4-46af-8d1a-0cd5db894797"
+					],
 					items: {
-						type: "string"
+						type: "string",
+						description: "Role keys or role IDs (roles created without a key can only be referenced by ID). On update: field absent = roles untouched; [] = remove all user-assignable roles; otherwise the complete user-assignable role set. On create: absent or empty = default Front-end User role. Unknown entries are ignored.",
+						example: "[\"DOTCMS_BACK_END_USER\",\"48190c8c-42c4-46af-8d1a-0cd5db894797\"]"
 					}
 				},
 				timeZoneId: {