keycloak-api-manager 6.0.1 → 6.0.3

package/docs/api/groups.md

@@ -2,38 +2,55 @@
 
 Group CRUD, subgroup tree navigation, role mappings, and fine-grained group permissions.
 
-**Namespace:** `KeycloakManager.groups`
+Namespace: KeycloakManager.groups
+
+## Overview
+
+This handler supports:
+
+- Group CRUD and hierarchy.
+- Realm/client role mappings on groups.
+- Fine-grained group permissions APIs.
+
+The wrapper supports creating child groups in a single call by passing parentId to create().
 
 ## CRUD and Structure
 
 ### create(groupRepresentation)
 - **Required**: `groupRepresentation.name` (string)
-- **Optional**: `path`, `attributes`, `subGroups`, `realmRoles`, `clientRoles`
+- **Optional**: `parentId`, `path`, `attributes`, `subGroups`, `realmRoles`, `clientRoles`
 - **Returns**: Promise<object>
 
+Notes:
+
+- If parentId is provided, the wrapper calls child-group creation endpoint.
+
 ### find(filter)
-- **Optional**: `search`, `first`, `max`, `briefRepresentation`, `exact`, `populateHierarchy`
+- **Optional**: `search`, `first`, `max`, `briefRepresentation`, `exact`, `populateHierarchy`, `realm`
 - **Returns**: Promise<Array<GroupRepresentation>>
 
 ### findOne(filter)
 - **Required**: `filter.id` (string, group id)
+- **Optional**: `filter.realm`
 - **Returns**: Promise<GroupRepresentation>
 
 ### update(filter, groupRepresentation)
 - **Required**: `filter.id` (string)
+- **Optional**: `filter.realm`
 - **Required**: `groupRepresentation` (partial)
 - **Returns**: Promise<void>
 
 ### del(filter)
 - **Required**: `filter.id` (string)
+- **Optional**: `filter.realm`
 - **Returns**: Promise<void>
 
 ### count(filter)
-- **Optional**: `search`, `top`
+- **Optional**: `search`, `top`, `realm`
 - **Returns**: Promise<number>
 
 ### listSubGroups(filter)
-- **Required**: `filter.id` (string, parent group id)
+- **Required**: one of `filter.parentId` or `filter.id` (parent group id)
 - **Optional**: `search`, `first`, `max`, `briefRepresentation`
 - **Returns**: Promise<Array<GroupRepresentation>>
 
@@ -42,27 +59,33 @@ Group CRUD, subgroup tree navigation, role mappings, and fine-grained group perm
 ### addRealmRoleMappings(role_mapping)
 - **Required**: `role_mapping.id` (group id)
 - **Required**: `role_mapping.roles` (Array<{id,name}>)
+- **Optional**: `role_mapping.realm`
 - **Returns**: Promise<void>
 
 ### delRealmRoleMappings(filters)
 - **Required**: `filters.id` (group id)
 - **Required**: `filters.roles` (Array<{id,name}>)
+- **Optional**: `filters.realm`
 - **Returns**: Promise<void>
 
 ### listRoleMappings(filters)
 - **Required**: `filters.id` (group id)
+- **Optional**: `filters.realm`
 - **Returns**: Promise<object>
 
 ### listRealmRoleMappings(filters)
 - **Required**: `filters.id` (group id)
+- **Optional**: `filters.realm`
 - **Returns**: Promise<Array<RoleRepresentation>>
 
 ### listAvailableRealmRoleMappings(filters)
 - **Required**: `filters.id` (group id)
+- **Optional**: `filters.realm`
 - **Returns**: Promise<Array<RoleRepresentation>>
 
 ### listCompositeRealmRoleMappings(filters)
 - **Required**: `filters.id` (group id)
+- **Optional**: `filters.realm`
 - **Returns**: Promise<Array<RoleRepresentation>>
 
 ## Client Role Mappings
@@ -71,27 +94,32 @@ Group CRUD, subgroup tree navigation, role mappings, and fine-grained group perm
 - **Required**: `filters.id` (group id)
 - **Required**: `filters.clientUniqueId` (client UUID)
 - **Required**: `filters.roles` (Array<{id,name}>)
+- **Optional**: `filters.realm`
 - **Returns**: Promise<void>
 
 ### delClientRoleMappings(filters)
 - **Required**: `filters.id` (group id)
 - **Required**: `filters.clientUniqueId` (client UUID)
 - **Required**: `filters.roles` (Array<{id,name}>)
+- **Optional**: `filters.realm`
 - **Returns**: Promise<void>
 
 ### listClientRoleMappings(filters)
 - **Required**: `filters.id` (group id)
 - **Required**: `filters.clientUniqueId` (client UUID)
+- **Optional**: `filters.realm`
 - **Returns**: Promise<Array<RoleRepresentation>>
 
 ### listAvailableClientRoleMappings(filters)
 - **Required**: `filters.id` (group id)
 - **Required**: `filters.clientUniqueId` (client UUID)
+- **Optional**: `filters.realm`
 - **Returns**: Promise<Array<RoleRepresentation>>
 
 ### listCompositeClientRoleMappings(filters)
 - **Required**: `filters.id` (group id)
 - **Required**: `filters.clientUniqueId` (client UUID)
+- **Optional**: `filters.realm`
 - **Returns**: Promise<Array<RoleRepresentation>>
 
 ## Fine-Grained Group Permissions (Wrapper Enhancement)
@@ -101,11 +129,13 @@ These methods wrap Keycloak management-permission endpoints used for group admin
 ### setPermissions(filters, permissionRepresentation)
 - **Required**: `filters.id` (group id)
 - **Required**: `permissionRepresentation.enabled` (boolean)
+- **Optional**: `filters.realm`
 - **Optional**: additional permission fields returned by Keycloak
 - **Returns**: Promise<object>
 
 ### listPermissions(filters)
 - **Required**: `filters.id` (group id)
+- **Optional**: `filters.realm`
 - **Returns**: Promise<object>
 
 ### Feature Requirement
@@ -119,6 +149,17 @@ Use Keycloak with:
 
 ```js
 const group = await KeycloakManager.groups.create({ name: 'engineering' });
+
+const child = await KeycloakManager.groups.create({
+	name: 'engineering-platform',
+	parentId: group.id,
+});
+
+await KeycloakManager.groups.addRealmRoleMappings({
+	id: group.id,
+	roles: [{ id: realmRole.id, name: realmRole.name }],
+});
+
 await KeycloakManager.groups.setPermissions({ id: group.id }, { enabled: true });
 const permissions = await KeycloakManager.groups.listPermissions({ id: group.id });
 ```

package/docs/api/identity-providers.md

@@ -2,7 +2,16 @@
 
 Manage identity providers (OIDC/SAML/social), mappers, import, and permissions.
 
-**Namespace:** `KeycloakManager.identityProviders`
+Namespace: KeycloakManager.identityProviders
+
+## Overview
+
+This handler covers:
+
+- Provider CRUD.
+- Provider factory discovery and metadata import.
+- Mapper CRUD.
+- Fine-grained permissions on provider resources.
 
 ## Provider CRUD
 
@@ -17,15 +26,18 @@ Manage identity providers (OIDC/SAML/social), mappers, import, and permissions.
 
 ### findOne(filter)
 - **Required**: `filter.alias`
+- **Optional**: `filter.realm`
 - **Returns**: Promise<IdentityProviderRepresentation>
 
 ### update(filter, identityProviderRepresentation)
 - **Required**: `filter.alias`
+- **Optional**: `filter.realm`
 - **Required**: updated representation
 - **Returns**: Promise<void>
 
 ### del(filter)
 - **Required**: `filter.alias`
+- **Optional**: `filter.realm`
 - **Returns**: Promise<void>
 
 ## Factory and Discovery
@@ -35,35 +47,47 @@ Manage identity providers (OIDC/SAML/social), mappers, import, and permissions.
 - **Returns**: Promise<object>
 
 ### importFromUrl(filter)
-- **Required**: provider-specific request payload (typically metadata URL fields)
+- **Required**: `filter.fromUrl`
+- **Required**: `filter.providerId`
+- **Optional**: `filter.alias`, `filter.trustEmail`, other provider-specific fields
 - **Returns**: Promise<object>
 
 ## Mappers
 
 ### createMapper(mapperParams)
-- **Required**: `mapperParams.identityProviderAlias`
-- **Required**: `mapperParams.name`, `mapperParams.identityProviderMapper`
-- **Optional**: `mapperParams.config`
+- **Required**: `mapperParams.alias` (identity provider alias)
+- **Required**: `mapperParams.identityProviderMapper` (mapper representation object)
 - **Returns**: Promise<object>
 
+Typical mapper representation fields:
+
+- name (string, required)
+- identityProviderAlias (string, required)
+- identityProviderMapper (string, required)
+- config (object, optional)
+
 ### findMappers(filter)
 - **Required**: `filter.alias` (identity provider alias)
+- **Optional**: `filter.realm`
 - **Returns**: Promise<Array<object>>
 
 ### findOneMapper(filter)
 - **Required**: `filter.alias`
 - **Required**: `filter.id` (mapper id)
+- **Optional**: `filter.realm`
 - **Returns**: Promise<object>
 
 ### updateMapper(filter, mapperRepresentation)
 - **Required**: `filter.alias`
 - **Required**: `filter.id`
+- **Optional**: `filter.realm`
 - **Required**: mapper representation
 - **Returns**: Promise<void>
 
 ### delMapper(filter)
 - **Required**: `filter.alias`
 - **Required**: `filter.id`
+- **Optional**: `filter.realm`
 - **Returns**: Promise<void>
 
 ## Permissions
@@ -71,10 +95,12 @@ Manage identity providers (OIDC/SAML/social), mappers, import, and permissions.
 ### updatePermission(filter, permissionRepresentation)
 - **Required**: `filter.alias`
 - **Required**: `permissionRepresentation.enabled` (boolean)
+- **Optional**: `filter.realm`
 - **Returns**: Promise<object>
 
 ### listPermissions(filter)
 - **Required**: `filter.alias`
+- **Optional**: `filter.realm`
 - **Returns**: Promise<object>
 
 ## Example
@@ -91,6 +117,25 @@ await KeycloakManager.identityProviders.create({
 });
 
 const mappers = await KeycloakManager.identityProviders.findMappers({ alias: 'google' });
+
+const createdMapper = await KeycloakManager.identityProviders.createMapper({
+  alias: 'google',
+  identityProviderMapper: {
+    name: 'email-claim-mapper',
+    identityProviderAlias: 'google',
+    identityProviderMapper: 'oidc-user-attribute-idp-mapper',
+    config: {
+      claim: 'email',
+      'user.attribute': 'email',
+      syncMode: 'INHERIT',
+    },
+  },
+});
+
+await KeycloakManager.identityProviders.updatePermission(
+  { alias: 'google' },
+  { enabled: true }
+);
 ```
 
 ## See Also

package/docs/api/roles.md

@@ -2,7 +2,12 @@
 
 Realm and client role management, including composite roles.
 
-**Namespace:** `KeycloakManager.roles`
+Namespace: KeycloakManager.roles
+
+## Overview
+
+This handler manages realm roles and composite relationships.
+It covers CRUD, user-role lookup, and composite role operations for realm and client roles.
 
 ## Role CRUD
 
@@ -16,25 +21,28 @@ Create a realm role.
 ### find(filters)
 List realm roles.
 
-- **Optional**: `first`, `max`, `search`, `briefRepresentation`
+- **Optional**: `first`, `max`, `search`, `briefRepresentation`, `realm`
 - **Returns**: Promise<Array<RoleRepresentation>>
 
 ### findOneByName(filters)
 Get role by name.
 
 - **Required**: `filters.name` (string)
+- **Optional**: `filters.realm` (string)
 - **Returns**: Promise<RoleRepresentation>
 
 ### findOneById(filters)
 Get role by id.
 
 - **Required**: `filters.id` (string)
+- **Optional**: `filters.realm` (string)
 - **Returns**: Promise<RoleRepresentation>
 
 ### updateByName(filters, role_dictionary)
 Update role by name.
 
 - **Required**: `filters.name` (string)
+- **Optional**: `filters.realm` (string)
 - **Required**: `role_dictionary` (partial role)
 - **Returns**: Promise<void>
 
@@ -42,6 +50,7 @@ Update role by name.
 Update role by id.
 
 - **Required**: `filters.id` (string)
+- **Optional**: `filters.realm` (string)
 - **Required**: `role_dictionary` (partial role)
 - **Returns**: Promise<void>
 
@@ -49,6 +58,7 @@ Update role by id.
 Delete role by name.
 
 - **Required**: `filters.name` (string)
+- **Optional**: `filters.realm` (string)
 - **Returns**: Promise<void>
 
 ## Composite Roles
@@ -56,27 +66,31 @@ Delete role by name.
 ### createComposite(filters, roles)
 Add composites to a realm role.
 
-- **Required**: `filters.roleName` (string)
+- **Required**: `filters.roleId` (string)
+- **Optional**: `filters.realm` (string)
 - **Required**: `roles` (Array<{id,name}>), realm or client roles
 - **Returns**: Promise<void>
 
 ### getCompositeRoles(filters)
 Get all composites for a role.
 
-- **Required**: `filters.roleName` (string)
+- **Required**: `filters.id` (string)
+- **Optional**: `filters.realm` (string)
 - **Returns**: Promise<Array<RoleRepresentation>>
 
 ### getCompositeRolesForRealm(filters)
 Get realm-level composites.
 
-- **Required**: `filters.roleName` (string)
+- **Required**: `filters.id` (string)
+- **Optional**: `filters.realm` (string)
 - **Returns**: Promise<Array<RoleRepresentation>>
 
 ### getCompositeRolesForClient(filters)
 Get client-level composites.
 
-- **Required**: `filters.roleName` (string)
-- **Required**: `filters.clientUniqueId` (client UUID)
+- **Required**: `filters.id` (string)
+- **Required**: `filters.clientId` (string, client UUID)
+- **Optional**: `filters.realm` (string)
 - **Returns**: Promise<Array<RoleRepresentation>>
 
 ## Users with Role
@@ -85,6 +99,7 @@ Get client-level composites.
 List users that have a specific realm role.
 
 - **Required**: `filters.name` (role name)
+- **Optional**: `filters.realm` (string)
 - **Optional**: `first`, `max`
 - **Returns**: Promise<Array<UserRepresentation>>
 
@@ -94,6 +109,21 @@ List users that have a specific realm role.
 await KeycloakManager.roles.create({ name: 'realm-admin' });
 const role = await KeycloakManager.roles.findOneByName({ name: 'realm-admin' });
 const users = await KeycloakManager.roles.findUsersWithRole({ name: 'realm-admin' });
+
+// Composite role with one realm role and one client role
+await KeycloakManager.roles.createComposite(
+	{ roleId: compositeRoleId },
+	[
+		{ id: realmRoleId, name: 'test-role-1' },
+		{ id: clientRoleId, name: 'client-role-a', clientRole: true, containerId: clientUuid }
+	]
+);
+
+const realmComposites = await KeycloakManager.roles.getCompositeRolesForRealm({ id: compositeRoleId });
+const clientComposites = await KeycloakManager.roles.getCompositeRolesForClient({
+	id: compositeRoleId,
+	clientId: clientUuid,
+});
 ```
 
 ## See Also

package/docs/api/server-info.md

@@ -2,37 +2,62 @@
 
 Read Keycloak server capabilities and runtime metadata.
 
-**Namespace:** `KeycloakManager.serverInfo`
+Namespace: KeycloakManager.serverInfo
+
+## Overview
+
+Use this handler to inspect server capabilities before enabling advanced features in automation.
+It is useful for diagnostics and compatibility checks in CI pipelines.
 
 ## Methods
 
 ### getInfo()
-Get full server-info payload.
 
-- **Params**: none
-- **Returns**: Promise<object>
+Fetch the full server-info payload from the configured realm context.
+
+Parameters:
+
+- none
+
+Returns:
+
+- Promise<object>: full server info payload.
+
+Common top-level sections returned by Keycloak include:
 
-The payload typically includes:
-- `systemInfo`
-- `memoryInfo`
-- `profileInfo`
-- `themes`
-- `providers`
-- `componentTypes`
-- `passwordPolicies`
-- `protocolMapperTypes`
-- `clientInstallations`
-- `enums`
+- systemInfo
+- memoryInfo
+- profileInfo
+- themes
+- providers
+- componentTypes
+- passwordPolicies
+- protocolMapperTypes
+- clientInstallations
+- enums
 
-## Example
+Example: basic inspection
 
 ```js
 const info = await KeycloakManager.serverInfo.getInfo();
 
 console.log('Keycloak version:', info.systemInfo?.version);
 console.log('Available themes:', Object.keys(info.themes || {}));
-console.log('Available provider categories:', Object.keys(info.providers || {}));
+console.log('Provider categories:', Object.keys(info.providers || {}));
+```
+
+Example: feature guard before workflow
+
+```js
+const info = await KeycloakManager.serverInfo.getInfo();
+const hasOrganizationFeature = Boolean(info.profileInfo?.features?.organization);
+
+if (!hasOrganizationFeature) {
+	throw new Error('Organization feature is not enabled on this Keycloak server.');
+}
 ```
 
 ## See Also
+
 - [API Reference](../api-reference.md)
+- [Keycloak Setup and Feature Flags](../keycloak-setup.md)

package/docs/api/user-profile.md

@@ -2,28 +2,72 @@
 
 Manage realm user-profile configuration and metadata.
 
-**Namespace:** `KeycloakManager.userProfile`
+Namespace: KeycloakManager.userProfile
+
+## Overview
+
+This handler manages declarative user-profile schema in a realm.
+It allows you to inspect current schema, update it, and read resolved metadata (validators, capabilities, attribute model).
+
+Note: endpoints are accessed through direct REST calls in the handler for compatibility across admin-client versions.
 
 ## Methods
 
 ### getConfiguration(filter)
-Get user-profile configuration for realm.
 
-- **Optional**: realm context fields
-- **Returns**: Promise<object>
+Get the current declarative user-profile configuration.
+
+Parameters:
+
+- filter (object, optional):
+- realm (string, optional): override target realm.
+
+Returns:
+
+- Promise<object>: current profile configuration.
 
 ### updateConfiguration(filter, userProfileConfig)
+
 Update user-profile configuration.
 
-- **Optional**: realm context fields
-- **Required**: `userProfileConfig` (full/partial config object)
-- **Returns**: Promise<void|object>
+Parameters:
+
+- filter (object, optional):
+- realm (string, optional): override target realm.
+- userProfileConfig (object, required): full or partial schema payload.
+
+Common top-level fields:
+
+- attributes (array): attribute definitions.
+- groups (array, optional): grouped attributes.
+- unmanagedAttributePolicy (string, optional)
+
+Common attribute fields:
+
+- name (string, required): attribute key.
+- displayName (string, optional)
+- required (object, optional): required rules.
+- permissions (object, optional): view/edit permissions.
+- validations (object, optional): validation rules.
+- annotations (object, optional): UI/metadata annotations.
+- multivalued (boolean, optional): enable list values.
+
+Returns:
+
+- Promise<void|object>: usually no content (204), or response payload if provided by server.
 
 ### getMetadata(filter)
-Get resolved user-profile metadata.
 
-- **Optional**: realm context fields
-- **Returns**: Promise<object>
+Get user-profile metadata resolved by the server.
+
+Parameters:
+
+- filter (object, optional):
+- realm (string, optional): override target realm.
+
+Returns:
+
+- Promise<object>: metadata payload (validators, resolved attributes, capabilities).
 
 ## Common User Profile Structure
 
@@ -56,6 +100,7 @@ await KeycloakManager.userProfile.updateConfiguration({}, {
 });
 
 const metadata = await KeycloakManager.userProfile.getMetadata();
+console.log('Available validators:', Object.keys(metadata.validators || {}));
 ```
 
 ## See Also

package/docs/api-reference.md

@@ -4,8 +4,8 @@ Complete API documentation for keycloak-api-manager.
 
 ## Table of Contents
 
-### Guides (Practical Implementation)
-- [PKCE Login Flow Guide](guides/PKCE-Login-Flow.md) - Step-by-step OAuth2 Authorization Code + PKCE implementation guide
+### Guides
+- [OIDC Migration Plan](../OIDC_MIGRATION_PLAN.md) - Deprecation status and migration notes to keycloak-express-middleware
 
 ### Core API
 - [Configuration & Authentication](api/configuration.md) - Setup, authentication, and lifecycle management
@@ -78,11 +78,11 @@ KeycloakManager.stop();
 |-----------|-------------|--------|
 | `configure()` | Authentication and setup | Core |
 | `setConfig()` | Runtime configuration | Core |
-| `getToken()` | Get current access token | Core |
-| `login()` | Preferred OIDC token grant/login endpoint wrapper | Core |
-| `generateAuthorizationUrl()` | Generate PKCE authorization URL and verifier pair | Core |
-| `loginPKCE()` | Authorization Code + PKCE token exchange helper | Core |
-| `auth()` | Backward-compatible alias of `login()` | Core |
+| `getToken()` | Get current access/refresh token pair | Core |
+| `login()` | Deprecated OIDC token endpoint wrapper (moved to keycloak-express-middleware) | Core |
+| `generateAuthorizationUrl()` | Deprecated PKCE helper (moved to keycloak-express-middleware) | Core |
+| `loginPKCE()` | Deprecated PKCE token exchange helper (moved to keycloak-express-middleware) | Core |
+| `auth()` | Deprecated backward-compatible alias of `login()` | Core |
 | `stop()` | Stop token refresh timer | Core |
 | `realms` | Realm management | realmsHandler |
 | `users` | User management | usersHandler |