keycloak-api-manager 6.0.1 → 6.0.3

package/docs/api/client-scopes.md

@@ -2,7 +2,17 @@
 
 Manage client scopes, protocol mappers, and role scope mappings.
 
-**Namespace:** `KeycloakManager.clientScopes`
+Namespace: KeycloakManager.clientScopes
+
+## Overview
+
+Client scopes are reusable bundles of:
+
+- Protocol mappers (claims in tokens/userinfo).
+- Realm role mappings.
+- Client role mappings.
+
+This handler covers full CRUD for scopes and all mapper/mapping operations.
 
 ## Scope CRUD
 
@@ -12,28 +22,33 @@ Manage client scopes, protocol mappers, and role scope mappings.
 - **Returns**: Promise<object>
 
 ### find(filter)
-- **Optional**: `search`, `first`, `max`
+- **Optional**: `search`, `first`, `max`, `realm`
 - **Returns**: Promise<Array<ClientScopeRepresentation>>
 
 ### findOne(filter)
 - **Required**: `filter.id` (scope id)
+- **Optional**: `filter.realm`
 - **Returns**: Promise<ClientScopeRepresentation>
 
 ### findOneByName(filter)
 - **Required**: `filter.name` (scope name)
+- **Optional**: `filter.realm`
 - **Returns**: Promise<ClientScopeRepresentation|null>
 
 ### update(filter, scopeRepresentation)
 - **Required**: `filter.id` (scope id)
+- **Optional**: `filter.realm`
 - **Required**: `scopeRepresentation` (partial)
 - **Returns**: Promise<void>
 
 ### del(filter)
 - **Required**: `filter.id` (scope id)
+- **Optional**: `filter.realm`
 - **Returns**: Promise<void>
 
 ### delByName(filter)
 - **Required**: `filter.name` (scope name)
+- **Optional**: `filter.realm`
 - **Returns**: Promise<void>
 
 ## Realm Default Scopes
@@ -44,10 +59,12 @@ Manage client scopes, protocol mappers, and role scope mappings.
 
 ### addDefaultClientScope(filter)
 - **Required**: `filter.id` (scope id)
+- **Optional**: `filter.realm`
 - **Returns**: Promise<void>
 
 ### delDefaultClientScope(filter)
 - **Required**: `filter.id` (scope id)
+- **Optional**: `filter.realm`
 - **Returns**: Promise<void>
 
 ### listDefaultOptionalClientScopes(filter)
@@ -56,35 +73,42 @@ Manage client scopes, protocol mappers, and role scope mappings.
 
 ### addDefaultOptionalClientScope(filter)
 - **Required**: `filter.id` (scope id)
+- **Optional**: `filter.realm`
 - **Returns**: Promise<void>
 
 ### delDefaultOptionalClientScope(filter)
 - **Required**: `filter.id` (scope id)
+- **Optional**: `filter.realm`
 - **Returns**: Promise<void>
 
 ## Protocol Mappers
 
 ### listProtocolMappers(filter)
 - **Required**: `filter.id` (scope id)
+- **Optional**: `filter.realm`
 - **Returns**: Promise<Array<ProtocolMapperRepresentation>>
 
 ### findProtocolMapper(filter)
 - **Required**: `filter.id` (scope id)
 - **Required**: `filter.mapperId` (mapper id)
+- **Optional**: `filter.realm`
 - **Returns**: Promise<ProtocolMapperRepresentation>
 
 ### findProtocolMapperByName(filter)
 - **Required**: `filter.id` (scope id)
 - **Required**: `filter.name` (mapper name)
+- **Optional**: `filter.realm`
 - **Returns**: Promise<ProtocolMapperRepresentation>
 
 ### findProtocolMappersByProtocol(filter)
 - **Required**: `filter.id` (scope id)
 - **Required**: `filter.protocol` (`openid-connect` or `saml`)
+- **Optional**: `filter.realm`
 - **Returns**: Promise<Array<ProtocolMapperRepresentation>>
 
 ### addProtocolMapper(filter, protocolMapper)
 - **Required**: `filter.id` (scope id)
+- **Optional**: `filter.realm`
 - **Required**: `protocolMapper.name`
 - **Required**: `protocolMapper.protocol`
 - **Required**: `protocolMapper.protocolMapper`
@@ -93,75 +117,89 @@ Manage client scopes, protocol mappers, and role scope mappings.
 
 ### addMultipleProtocolMappers(filter, protocolMappers)
 - **Required**: `filter.id` (scope id)
+- **Optional**: `filter.realm`
 - **Required**: `protocolMappers` (Array<ProtocolMapperRepresentation>)
 - **Returns**: Promise<void>
 
 ### updateProtocolMapper(filter, protocolMapper)
 - **Required**: `filter.id` (scope id)
 - **Required**: `filter.mapperId` (mapper id)
+- **Optional**: `filter.realm`
 - **Required**: `protocolMapper` (updated representation)
 - **Returns**: Promise<void>
 
 ### delProtocolMapper(filter)
 - **Required**: `filter.id` (scope id)
 - **Required**: `filter.mapperId` (mapper id)
+- **Optional**: `filter.realm`
 - **Returns**: Promise<void>
 
 ## Client Scope Role Mappings (for one client scope)
 
 ### listScopeMappings(filter)
 - **Required**: `filter.id` (scope id)
+- **Optional**: `filter.realm`
 - **Returns**: Promise<object>
 
 ### listAvailableClientScopeMappings(filter)
 - **Required**: `filter.id` (scope id)
 - **Required**: `filter.clientUniqueId` (client UUID)
+- **Optional**: `filter.realm`
 - **Returns**: Promise<Array<RoleRepresentation>>
 
 ### addClientScopeMappings(filter, roleRepresentation)
 - **Required**: `filter.id` (scope id)
 - **Required**: `filter.clientUniqueId` (client UUID)
+- **Optional**: `filter.realm`
 - **Required**: `roleRepresentation` (Array<{id,name}> or role-like object depending on endpoint)
 - **Returns**: Promise<void>
 
 ### delClientScopeMappings(filter, roleRepresentation)
 - **Required**: `filter.id` (scope id)
 - **Required**: `filter.clientUniqueId` (client UUID)
+- **Optional**: `filter.realm`
 - **Required**: `roleRepresentation`
 - **Returns**: Promise<void>
 
 ### listClientScopeMappings(filter)
 - **Required**: `filter.id` (scope id)
 - **Required**: `filter.clientUniqueId` (client UUID)
+- **Optional**: `filter.realm`
 - **Returns**: Promise<Array<RoleRepresentation>>
 
 ### listCompositeClientScopeMappings(filter)
 - **Required**: `filter.id` (scope id)
 - **Required**: `filter.clientUniqueId` (client UUID)
+- **Optional**: `filter.realm`
 - **Returns**: Promise<Array<RoleRepresentation>>
 
 ## Realm Scope Mappings (for one client scope)
 
 ### listAvailableRealmScopeMappings(filter)
 - **Required**: `filter.id` (scope id)
+- **Optional**: `filter.realm`
 - **Returns**: Promise<Array<RoleRepresentation>>
 
 ### addRealmScopeMappings(filter, roleRepresentation)
 - **Required**: `filter.id` (scope id)
+- **Optional**: `filter.realm`
 - **Required**: `roleRepresentation`
 - **Returns**: Promise<void>
 
-### delRealmScopeMappings(filter, RoleRepresentation)
+### delRealmScopeMappings(filter, roleRepresentation)
 - **Required**: `filter.id` (scope id)
-- **Required**: `RoleRepresentation`
+- **Optional**: `filter.realm`
+- **Required**: `roleRepresentation`
 - **Returns**: Promise<void>
 
 ### listRealmScopeMappings(filter)
 - **Required**: `filter.id` (scope id)
+- **Optional**: `filter.realm`
 - **Returns**: Promise<Array<RoleRepresentation>>
 
 ### listCompositeRealmScopeMappings(filter)
 - **Required**: `filter.id` (scope id)
+- **Optional**: `filter.realm`
 - **Returns**: Promise<Array<RoleRepresentation>>
 
 ## Example
@@ -187,6 +225,16 @@ await KeycloakManager.clientScopes.addProtocolMapper(
     }
   }
 );
+
+await KeycloakManager.clientScopes.addRealmScopeMappings(
+  { id: scope.id },
+  [{ id: realmRole.id, name: realmRole.name }]
+);
+
+await KeycloakManager.clientScopes.addClientScopeMappings(
+  { id: scope.id, clientUniqueId: client.id },
+  [{ id: clientRole.id, name: clientRole.name }]
+);
 ```
 
 ## See Also

package/docs/api/components.md

@@ -2,39 +2,108 @@
 
 Manage Keycloak components (LDAP providers, Kerberos, user federation, storage mappers, and subcomponents).
 
-**Namespace:** `KeycloakManager.components`
+Namespace: KeycloakManager.components
+
+## Overview
+
+Components represent pluggable server-side modules in Keycloak (for example user federation providers and their mappers).
+This handler supports full CRUD plus sub-component listing.
 
 ## Methods
 
 ### create(componentRepresentation)
-- **Required**: `componentRepresentation.name`
-- **Required**: `componentRepresentation.providerId`
-- **Required**: `componentRepresentation.providerType`
-- **Optional**: `parentId`, `config`, `subType`
-- **Returns**: Promise<object>
+
+Create a component.
+
+Parameters:
+
+- componentRepresentation (object, required): component payload.
+
+Common fields:
+
+- name (string, required): component name.
+- providerId (string, required): provider implementation id (for example ldap).
+- providerType (string, required): provider class/type.
+- parentId (string, optional): usually realm id or parent component id.
+- config (object, optional): provider config map (Keycloak convention often uses arrays of strings).
+- subType (string, optional): subtype where applicable.
+
+Returns:
+
+- Promise<object>: creation response (usually includes id).
 
 ### find(filter)
-- **Optional**: `parent`, `type`, `name`
-- **Returns**: Promise<Array<ComponentRepresentation>>
+
+List components.
+
+Parameters:
+
+- filter (object, optional):
+- parent (string, optional): parent id.
+- type (string, optional): provider type filter.
+- name (string, optional): name filter.
+- first (number, optional): pagination offset.
+- max (number, optional): pagination limit.
+
+Returns:
+
+- Promise<Array<ComponentRepresentation>>
 
 ### findOne(filter)
-- **Required**: `filter.id` (component id)
-- **Returns**: Promise<ComponentRepresentation>
+
+Get a single component by id.
+
+Parameters:
+
+- filter (object, required):
+- id (string, required): component id.
+
+Returns:
+
+- Promise<ComponentRepresentation>
 
 ### update(filter, componentRepresentation)
-- **Required**: `filter.id`
-- **Required**: `componentRepresentation`
-- **Returns**: Promise<void>
+
+Update an existing component.
+
+Parameters:
+
+- filter (object, required):
+- id (string, required): component id.
+- componentRepresentation (object, required): updated payload.
+
+Returns:
+
+- Promise<void>
 
 ### del(filter)
-- **Required**: `filter.id`
-- **Returns**: Promise<void>
+
+Delete a component by id.
+
+Parameters:
+
+- filter (object, required):
+- id (string, required): component id.
+
+Returns:
+
+- Promise<void>
 
 ### listSubComponents(filter)
-- **Required**: `filter.id` (parent component id)
-- **Required**: `filter.type` (provider type)
-- **Optional**: `filter.first`, `filter.max`
-- **Returns**: Promise<Array<ComponentRepresentation>>
+
+List sub-components for a parent component.
+
+Parameters:
+
+- filter (object, required):
+- id (string, required): parent component id.
+- type (string, required): sub-component provider type.
+- first (number, optional): pagination offset.
+- max (number, optional): pagination limit.
+
+Returns:
+
+- Promise<Array<ComponentRepresentation>>
 
 ## Example
 
@@ -50,6 +119,25 @@ const ldapComponent = await KeycloakManager.components.create({
     bindDn: ['cn=admin,dc=company,dc=local']
   }
 });
+
+const allLdapProviders = await KeycloakManager.components.find({
+  type: 'org.keycloak.storage.UserStorageProvider',
+});
+
+const firstProvider = allLdapProviders[0];
+
+if (firstProvider) {
+  await KeycloakManager.components.update(
+    { id: firstProvider.id },
+    {
+      ...firstProvider,
+      config: {
+        ...(firstProvider.config || {}),
+        editMode: ['READ_ONLY'],
+      },
+    }
+  );
+}
 ```
 
 ## See Also