keycloak-api-manager 6.0.2 → 6.0.3

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/test-configuration.md

@@ -19,13 +19,31 @@ The active section is selected by `NODE_ENV` (defaults to `test` in suite bootst
 - `test.keycloak.password` (typically in `secrets.json`)
 - `test.keycloak.grantType`
 
+## Recommended Local Setup
+
+1. Keep non-sensitive defaults in `default.json`.
+2. Put secrets in `secrets.json`.
+3. Override per-machine host/ports in `local.json`.
+
+Example `local.json` for local Docker Keycloak:
+
+```json
+{
+  "test": {
+    "keycloak": {
+      "baseUrl": "http://127.0.0.1:8080"
+    }
+  }
+}
+```
+
 ## Example `secrets.json`
 
 ```json
 {
   "test": {
     "keycloak": {
-      "password": "admin"
+      "password": "your-admin-password-here"
     },
     "realm": {
       "user": {

package/docs/testing.md

@@ -2,6 +2,75 @@
 
 The test suite validates the package against a real Keycloak server.
 
+## Quick Start (End-to-End)
+
+Use these steps to create the test environment, start it, and run the suite.
+
+### 1) Install dependencies
+
+```bash
+npm install
+npm --prefix test install
+```
+
+### 2) Prepare local test config
+
+Create local override files from examples:
+
+```bash
+cp test/config/local.json.example test/config/local.json
+cp test/config/secrets.json.example test/config/secrets.json
+```
+
+Then edit:
+
+- `test/config/local.json` to set the Keycloak URL you can reach locally.
+- `test/config/secrets.json` to set admin credentials.
+
+For local Docker on default HTTP port, a common value is:
+
+```json
+{
+  "test": {
+    "keycloak": {
+      "baseUrl": "http://127.0.0.1:8080",
+      "password": "admin"
+    }
+  }
+}
+```
+
+### 3) Start Keycloak for tests
+
+```bash
+docker compose -f test/docker-keycloak/docker-compose.yml up -d
+```
+
+Wait until ready:
+
+```bash
+docker compose -f test/docker-keycloak/docker-compose.yml ps
+curl -f http://127.0.0.1:8080/health/ready
+```
+
+### 4) Run tests
+
+```bash
+npm test
+```
+
+### 5) Stop environment (optional but recommended)
+
+```bash
+docker compose -f test/docker-keycloak/docker-compose.yml down
+```
+
+If you want to remove container volumes too:
+
+```bash
+docker compose -f test/docker-keycloak/docker-compose.yml down -v
+```
+
 ## Test Architecture
 
 The suite uses a shared realm strategy:
@@ -40,6 +109,21 @@ npm --prefix test test -- --grep "Organizations Handler Tests"
 npm --prefix test test -- --grep "Matrix -"
 ```
 
+## HTTPS Variant
+
+For HTTPS-like environments use the dedicated compose file:
+
+```bash
+export KEYCLOAK_CERT_PATH=/absolute/path/to/certs
+export KEYCLOAK_HOSTNAME=keycloak.local
+docker compose -f test/docker-keycloak/docker-compose-https.yml up -d
+```
+
+The cert directory must contain:
+
+- `keycloak.crt`
+- `keycloak.key`
+
 ## Setup Flow
 
 `test/support/setup.js` runs before all suites and executes `test/support/enableServerFeatures.js` to provision:
@@ -52,6 +136,8 @@ npm --prefix test test -- --grep "Matrix -"
 - client scope
 - fine-grained permissions (when feature-enabled)
 
+The same bootstrap also performs cleanup in global teardown by deleting the shared test realm.
+
 ## Writing New Tests
 
 - Import config from `test/testConfig.js`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "keycloak-api-manager",
-  "version": "6.0.2",
+  "version": "6.0.3",
   "description": "Enhanced Node.js wrapper for Keycloak Admin REST API. Professional alternative to @keycloak/keycloak-admin-client with advanced features, bug fixes, automatic token refresh, Organizations API support, fine-grained permissions, and comprehensive resource management. Battle-tested with 113+ integration tests.",
   "main": "index.js",
   "scripts": {

package/test/config/secrets.json.example

@@ -1,7 +1,7 @@
 {
   "test": {
     "keycloak": {
-      "adminPassword": "your-admin-password-here"
+      "password": "your-admin-password-here"
     }
   }
 }