@web-ts-toolkit/moo 0.39.0 → 0.40.0

package/README.md

@@ -101,16 +101,12 @@ pnpm add @egose/keycloak-fluent
 ```
 
 ```ts
-import KeycloakAdminClientFluent from '@egose/keycloak-fluent';
 import { Schema } from 'mongoose';
-import { keycloakUserSyncPlugin } from '@web-ts-toolkit/moo/plugins/keycloak-user-sync';
+import { createManagedKeycloakClient, keycloakUserSyncPlugin } from '@web-ts-toolkit/moo/plugins/keycloak-user-sync';
 
-const keycloak = new KeycloakAdminClientFluent({
+const keycloak = createManagedKeycloakClient({
   baseUrl: process.env.KEYCLOAK_URL,
-  realmName: 'master',
-});
-
-await keycloak.simpleAuth({
+  authRealm: 'master',
   clientId: process.env.KEYCLOAK_CLIENT_ID,
   clientSecret: process.env.KEYCLOAK_CLIENT_SECRET,
 });
@@ -161,6 +157,8 @@ userSchema.plugin(keycloakUserSyncPlugin, {
 });
 ```
 
+`createManagedKeycloakClient` is provided by `@egose/keycloak-fluent` and re-exported here for convenience. It authenticates lazily, shares one authentication attempt across concurrent requests, and creates no timer, so the same client can be declared outside a serverless handler and reused by warm invocations. The default mode is `client_credentials`; pass `authMode: 'user_credentials'` with lazy `username` and `password` resolvers when direct user credentials are required. Service accounts remain recommended for background synchronization.
+
 The plugin:
 
 - creates or updates a Keycloak user after a document `save()`

package/llms.txt

@@ -64,10 +64,19 @@ userSchema.plugin(newDocumentPlugin, {
 Keycloak user-sync plugin:
 
 ```ts
-import { keycloakUserSyncPlugin } from '@web-ts-toolkit/moo/plugins/keycloak-user-sync';
+import {
+  createManagedKeycloakClient,
+  keycloakUserSyncPlugin,
+} from '@web-ts-toolkit/moo/plugins/keycloak-user-sync';
+
+const keycloak = createManagedKeycloakClient({
+  baseUrl: process.env.KEYCLOAK_URL!,
+  clientId: process.env.KEYCLOAK_CLIENT_ID!,
+  clientSecret: process.env.KEYCLOAK_CLIENT_SECRET!,
+});
 
 userSchema.plugin(keycloakUserSyncPlugin, {
-  client: authenticatedKeycloakFluentClient,
+  client: keycloak,
   realm: 'application',
   identifyBy: ['providerId', 'username', 'email'],
   managedRoles: ['admin', 'editor', 'viewer'],
@@ -91,6 +100,7 @@ userSchema.plugin(keycloakUserSyncPlugin, {
 - optional peer dependency: `@egose/keycloak-fluent ^0.7` only for `@web-ts-toolkit/moo/plugins/keycloak-user-sync`
 - root entrypoint exports schema helpers, `isObjectId`, and non-Keycloak plugins; dedicated plugin subpaths are also available
 - Keycloak user sync is not re-exported from root or `@web-ts-toolkit/moo/plugins`; import it from the direct subpath
+- `createManagedKeycloakClient` lazily uses `client_credentials`, renews on demand without timers, and deduplicates concurrent authentication; construct a client directly for custom grants
 - `isObjectId(...)` is a strict guard: it rejects strings that `ObjectId.isValid` accepts but that don't round-trip back to the same string
 - `uniqueNullableString`/`uniqueEmptiableString` return partial-index field definitions, not full schemas
 - new-document plugin runs its callback only after the first successful `save()` of a newly inserted document
@@ -112,7 +122,7 @@ userSchema.plugin(keycloakUserSyncPlugin, {
 - `@web-ts-toolkit/moo/plugins/cascade-delete` — `cascadeDeletePlugin`
 - `@web-ts-toolkit/moo/plugins/model-function` — `modelFunctionPlugin`
 - `@web-ts-toolkit/moo/plugins/new-document` — `newDocumentPlugin`
-- `@web-ts-toolkit/moo/plugins/keycloak-user-sync` — `keycloakUserSyncPlugin`
+- `@web-ts-toolkit/moo/plugins/keycloak-user-sync` — `createManagedKeycloakClient`, `keycloakUserSyncPlugin`
 
 ## Pointers
 

package/package.json

@@ -2,7 +2,7 @@
   "name": "@web-ts-toolkit/moo",
   "description": "Mongoose helpers for schema fields, ObjectId checks, and document plugins",
   "homepage": "https://web-ts-toolkit.pages.dev/docs/packages/moo",
-  "version": "0.39.0",
+  "version": "0.40.0",
   "sideEffects": false,
   "keywords": [
     "mongoose",
@@ -74,7 +74,7 @@
     "node": ">=22"
   },
   "peerDependencies": {
-    "@egose/keycloak-fluent": "^0.7.0",
+    "@egose/keycloak-fluent": "^0.12.0",
     "mongoose": ">=8.0.0"
   },
   "peerDependenciesMeta": {
@@ -83,7 +83,7 @@
     }
   },
   "dependencies": {
-    "@web-ts-toolkit/utils": "0.39.0"
+    "@web-ts-toolkit/utils": "0.40.0"
   },
   "files": [
     "**/*",

package/plugins/keycloak-user-sync.d.mts

@@ -1,6 +1,8 @@
-import KeycloakAdminClientFluent from '@egose/keycloak-fluent';
+import KeycloakAdminClientFluent, { ManagedKeycloakCredential } from '@egose/keycloak-fluent';
+export { ManagedKeycloakClientOptions, createManagedKeycloakClient } from '@egose/keycloak-fluent';
 import { Schema } from 'mongoose';
 
+type ManagedKeycloakClientSecret = ManagedKeycloakCredential;
 type KeycloakUserIdentityField = 'providerId' | 'username' | 'email';
 type KeycloakUserSyncField = 'username' | 'email' | 'emailVerified' | 'firstName' | 'lastName' | 'enabled' | 'roles' | 'attributes' | 'password';
 interface KeycloakUserSyncPaths {
@@ -32,7 +34,7 @@ interface KeycloakUserSyncDocument {
     get(path: string): unknown;
 }
 interface KeycloakUserSyncPluginOptions {
-    /** An authenticated client. Authentication and token refresh remain the application's responsibility. */
+    /** A client that can provide admin access tokens. Use createManagedKeycloakClient for lazy managed authentication. */
     client: KeycloakAdminClientFluent;
     realm: string;
     /**
@@ -85,4 +87,4 @@ interface KeycloakUserSyncPluginOptions {
  */
 declare function keycloakUserSyncPlugin(schema: Schema, rawOptions: KeycloakUserSyncPluginOptions): void;
 
-export { type KeycloakUserIdentityField, type KeycloakUserSyncDocument, type KeycloakUserSyncErrorContext, type KeycloakUserSyncField, type KeycloakUserSyncLogger, type KeycloakUserSyncPaths, type KeycloakUserSyncPluginOptions, type KeycloakUserSyncSensitiveErrorContext, keycloakUserSyncPlugin };
+export { type KeycloakUserIdentityField, type KeycloakUserSyncDocument, type KeycloakUserSyncErrorContext, type KeycloakUserSyncField, type KeycloakUserSyncLogger, type KeycloakUserSyncPaths, type KeycloakUserSyncPluginOptions, type KeycloakUserSyncSensitiveErrorContext, type ManagedKeycloakClientSecret, keycloakUserSyncPlugin };

package/plugins/keycloak-user-sync.d.ts

@@ -1,6 +1,8 @@
-import KeycloakAdminClientFluent from '@egose/keycloak-fluent';
+import KeycloakAdminClientFluent, { ManagedKeycloakCredential } from '@egose/keycloak-fluent';
+export { ManagedKeycloakClientOptions, createManagedKeycloakClient } from '@egose/keycloak-fluent';
 import { Schema } from 'mongoose';
 
+type ManagedKeycloakClientSecret = ManagedKeycloakCredential;
 type KeycloakUserIdentityField = 'providerId' | 'username' | 'email';
 type KeycloakUserSyncField = 'username' | 'email' | 'emailVerified' | 'firstName' | 'lastName' | 'enabled' | 'roles' | 'attributes' | 'password';
 interface KeycloakUserSyncPaths {
@@ -32,7 +34,7 @@ interface KeycloakUserSyncDocument {
     get(path: string): unknown;
 }
 interface KeycloakUserSyncPluginOptions {
-    /** An authenticated client. Authentication and token refresh remain the application's responsibility. */
+    /** A client that can provide admin access tokens. Use createManagedKeycloakClient for lazy managed authentication. */
     client: KeycloakAdminClientFluent;
     realm: string;
     /**
@@ -85,4 +87,4 @@ interface KeycloakUserSyncPluginOptions {
  */
 declare function keycloakUserSyncPlugin(schema: Schema, rawOptions: KeycloakUserSyncPluginOptions): void;
 
-export { type KeycloakUserIdentityField, type KeycloakUserSyncDocument, type KeycloakUserSyncErrorContext, type KeycloakUserSyncField, type KeycloakUserSyncLogger, type KeycloakUserSyncPaths, type KeycloakUserSyncPluginOptions, type KeycloakUserSyncSensitiveErrorContext, keycloakUserSyncPlugin };
+export { type KeycloakUserIdentityField, type KeycloakUserSyncDocument, type KeycloakUserSyncErrorContext, type KeycloakUserSyncField, type KeycloakUserSyncLogger, type KeycloakUserSyncPaths, type KeycloakUserSyncPluginOptions, type KeycloakUserSyncSensitiveErrorContext, type ManagedKeycloakClientSecret, keycloakUserSyncPlugin };

package/plugins/keycloak-user-sync.js

@@ -20,60 +20,11 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/plugins/keycloak-user-sync.ts
 var keycloak_user_sync_exports = {};
 __export(keycloak_user_sync_exports, {
+  createManagedKeycloakClient: () => import_keycloak_fluent.createManagedKeycloakClient,
   keycloakUserSyncPlugin: () => keycloakUserSyncPlugin
 });
 module.exports = __toCommonJS(keycloak_user_sync_exports);
-
-// src/plugins/keycloak-user-sync/adapter.ts
-var createKeycloakUserSyncAdapter = (client, realm) => {
-  const supportedClient = client;
-  const realmHandle = () => supportedClient.realm(realm);
-  const users = supportedClient.core.users;
-  return {
-    async getRealm() {
-      return realmHandle().get();
-    },
-    async getUserById(username, id) {
-      return realmHandle().user(username).getById(id);
-    },
-    async getUserByUsername(username) {
-      return realmHandle().user(username).get();
-    },
-    async findUsersByEmail(email) {
-      return users.find({ realm, email, exact: true, first: 0, max: 2 });
-    },
-    async createUser(username, payload) {
-      return realmHandle().user(username).create(payload);
-    },
-    async updateUser(id, payload) {
-      await users.update({ realm, id }, payload);
-    },
-    async deleteUser(id) {
-      await users.del({ realm, id });
-    },
-    async sendVerifyEmail(id) {
-      await users.sendVerifyEmail({ realm, id });
-    },
-    async resetPassword(id, value, temporary) {
-      await users.resetPassword({ realm, id, credential: { temporary, type: "password", value } });
-    },
-    async ensureRole(name) {
-      await realmHandle().role(name).ensure({});
-    },
-    async getRole(name) {
-      return realmHandle().role(name).get();
-    },
-    async listRealmRoleMappings(id) {
-      return users.listRealmRoleMappings({ realm, id });
-    },
-    async addRealmRoleMappings(id, roles) {
-      await users.addRealmRoleMappings({ realm, id, roles });
-    },
-    async delRealmRoleMappings(id, roles) {
-      await users.delRealmRoleMappings({ realm, id, roles });
-    }
-  };
-};
+var import_keycloak_fluent = require("@egose/keycloak-fluent");
 
 // src/plugins/keycloak-user-sync/planner.ts
 var dangerousAttributeKeys = /* @__PURE__ */ new Set(["__proto__", "prototype", "constructor"]);
@@ -222,18 +173,6 @@ var planEmailVerification = ({
     initialLinkSameEmail
   };
 };
-var planRoleDiff = (desiredNames, assignedRoles, desiredRoles, managedRoles) => {
-  const managedNames = managedRoles ? new Set(managedRoles) : null;
-  const effectiveDesiredNames = managedNames ? desiredNames.filter((name) => managedNames.has(name)) : desiredNames;
-  const assignedNames = new Set(assignedRoles.map((role) => role.name).filter((name) => Boolean(name)));
-  const desiredNameSet = new Set(effectiveDesiredNames);
-  return {
-    desiredNames,
-    effectiveDesiredNames,
-    toAdd: desiredRoles.filter((role) => role.name && !assignedNames.has(role.name)),
-    toRemove: managedNames ? assignedRoles.filter((role) => role.name && !desiredNameSet.has(role.name) && managedNames.has(role.name)) : []
-  };
-};
 
 // src/plugins/keycloak-user-sync.ts
 var syncStateKey = "keycloakUserSync";
@@ -413,7 +352,7 @@ function keycloakUserSyncPlugin(schema, rawOptions) {
   const paths = options.paths;
   const syncFields = options.syncFields;
   const identities = options.identifyBy;
-  const adapter = createKeycloakUserSyncAdapter(options.client, options.realm);
+  const realmHandle = options.client.realm(options.realm);
   const trackedPaths = buildTrackedPaths(options);
   const buildSafeErrorContext = (operation, document) => ({
     operation,
@@ -437,13 +376,13 @@ function keycloakUserSyncPlugin(schema, rawOptions) {
   const getPreviousValue = (previous, field) => getPathValue(previous, paths[field]);
   const getUsername = (document) => stringValue(readDocumentValue(document, "username")) ?? stringValue(readDocumentValue(document, "email"));
   const resolveUser = async (document, previous) => {
-    const realm = await adapter.getRealm();
+    const realm = await realmHandle.get();
     if (!realm) throw new Error(`Keycloak realm "${options.realm}" was not found`);
     const duplicateEmailsAllowed = realm.duplicateEmailsAllowed === true;
     const orderedIdentities = duplicateEmailsAllowed ? ["providerId", "username", "email"].filter((identity) => identities.includes(identity)) : identities;
     const getCompleteUserById = async (user) => {
       if (!user.id) return user;
-      return await adapter.getUserById(user.username ?? user.id, user.id) ?? user;
+      return await realmHandle.userById(user.id).get() ?? user;
     };
     for (const identity of orderedIdentities) {
       if (identity === "providerId") {
@@ -451,7 +390,7 @@ function keycloakUserSyncPlugin(schema, rawOptions) {
           readDocumentValue(document, "providerId"),
           getPreviousValue(previous, "providerId")
         ])) {
-          const user = await adapter.getUserById(getUsername(document) ?? providerId, providerId);
+          const user = await realmHandle.userById(providerId).get();
           if (user) return { user, duplicateEmailsAllowed };
         }
       }
@@ -460,7 +399,7 @@ function keycloakUserSyncPlugin(schema, rawOptions) {
           readDocumentValue(document, "username"),
           getPreviousValue(previous, "username")
         ])) {
-          const user = await adapter.getUserByUsername(username);
+          const user = await realmHandle.user(username).get();
           if (user) return { user, duplicateEmailsAllowed };
         }
       }
@@ -469,9 +408,7 @@ function keycloakUserSyncPlugin(schema, rawOptions) {
           readDocumentValue(document, "email"),
           getPreviousValue(previous, "email")
         ])) {
-          const matches = (await adapter.findUsersByEmail(email)).filter(
-            (user) => normalizeEmail(user.email) === normalizeEmail(email)
-          );
+          const matches = (await realmHandle.searchUsers(email, { attribute: "email", exact: true, first: 0, max: 2 })).filter((user) => normalizeEmail(user.email) === normalizeEmail(email));
           if (matches.length > 1) {
             throw new Error("Cannot identify a unique Keycloak user for the configured email identity");
           }
@@ -482,17 +419,15 @@ function keycloakUserSyncPlugin(schema, rawOptions) {
     return { user: null, duplicateEmailsAllowed };
   };
   const resolveCreatedUser = async (document, username) => {
-    const userByUsername = await adapter.getUserByUsername(username);
+    const userByUsername = await realmHandle.user(username).get();
     if (userByUsername) return userByUsername;
     const email = stringValue(readDocumentValue(document, "email"));
     if (!email) return null;
-    const matches = (await adapter.findUsersByEmail(email)).filter(
-      (user) => normalizeEmail(user.email) === normalizeEmail(email)
-    );
+    const matches = (await realmHandle.searchUsers(email, { attribute: "email", exact: true, first: 0, max: 2 })).filter((user) => normalizeEmail(user.email) === normalizeEmail(email));
     if (matches.length > 1) throw new Error("Cannot identify a unique Keycloak user for the configured email identity");
     const match = matches[0];
     if (!match?.id) return match ?? null;
-    return await adapter.getUserById(match.username ?? match.id, match.id) ?? match;
+    return await realmHandle.userById(match.id).get() ?? match;
   };
   const syncRoles = async (user, document) => {
     if (!syncFields.roles || !user.id) return;
@@ -502,24 +437,12 @@ function keycloakUserSyncPlugin(schema, rawOptions) {
     if (desiredNames.length > maxRolesPerSync) {
       throw new Error(`keycloakUserSyncPlugin supports at most ${maxRolesPerSync} desired roles per sync operation`);
     }
-    const managedNames = options.managedRoles ? new Set(options.managedRoles) : null;
-    const effectiveDesiredNames = managedNames ? desiredNames.filter((name) => managedNames.has(name)) : desiredNames;
-    if (effectiveDesiredNames.length === 0 && !managedNames) return;
-    const desiredRoles = [];
-    for (const roleName of effectiveDesiredNames) {
-      if (options.ensureRoles !== false) await adapter.ensureRole(roleName);
-      const role = await adapter.getRole(roleName);
-      if (!role?.id) throw new Error(`Keycloak realm role "${roleName}" was not found`);
-      desiredRoles.push(role);
-    }
-    const assignedRoles = await adapter.listRealmRoleMappings(user.id);
-    const { toAdd, toRemove } = planRoleDiff(desiredNames, assignedRoles, desiredRoles, options.managedRoles);
-    if (toAdd.length) {
-      await adapter.addRealmRoleMappings(user.id, toAdd);
-    }
-    if (toRemove.length) {
-      await adapter.delRealmRoleMappings(user.id, toRemove);
-    }
+    if (desiredNames.length === 0 && !options.managedRoles) return;
+    await realmHandle.userById(user.id).reconcileRealmRoles(desiredNames, {
+      ensureMissing: options.ensureRoles !== false,
+      managedRoleNames: options.managedRoles,
+      maxRoles: maxRolesPerSync
+    });
   };
   const persistProviderId = async (document, providerId) => {
     if (options.persistProviderId === false || readDocumentValue(document, "providerId") === providerId) return;
@@ -546,14 +469,20 @@ function keycloakUserSyncPlugin(schema, rawOptions) {
       if (!username) throw new Error("Cannot create a Keycloak user without a username or email");
       payload.attributes = mergeAttributes(null, document, options);
       try {
-        user = await adapter.createUser(username, payload) ?? null;
+        user = await realmHandle.user(username).create({
+          ...payload,
+          ...desiredPassword && {
+            password: desiredPassword,
+            passwordTemporary: options.passwordTemporary ?? false
+          }
+        }) ?? null;
+        created = true;
       } catch (error) {
         if (identities.length === 0) throw error;
         const recoveredUser = await resolveCreatedUser(document, username);
         if (!recoveredUser) throw error;
         user = recoveredUser;
       }
-      created = true;
     }
     if (!user?.id) throw new Error("Keycloak did not return a user ID");
     const userId = user.id;
@@ -576,21 +505,21 @@ function keycloakUserSyncPlugin(schema, rawOptions) {
       }
       if (shouldSyncAttributes) payload.attributes = mergeAttributes(user, document, options);
       if (Object.keys(payload).length > 0) {
-        await adapter.updateUser(userId, payload);
+        await realmHandle.userById(userId).update(payload);
         user = { ...user, ...payload };
       }
     }
-    if ((created || state.passwordChanged) && desiredPassword) {
-      await adapter.resetPassword(userId, desiredPassword, options.passwordTemporary ?? false);
+    if (!created && state.passwordChanged && desiredPassword) {
+      await realmHandle.userById(userId).resetPassword(desiredPassword, { temporary: options.passwordTemporary ?? false });
     }
     if (created || state.changedFields.has("roles")) await syncRoles(user, document);
     if (emailVerificationPlan.changed && options.sendVerificationEmailOnChange !== false) {
-      await adapter.sendVerifyEmail(userId);
+      await realmHandle.userById(userId).sendVerifyEmail();
     }
   };
   const deleteDocument = async (document) => {
     const { user } = await resolveUser(document);
-    if (user?.id) await adapter.deleteUser(user.id);
+    if (user?.id) await realmHandle.userById(user.id).delete();
   };
   schema.pre("save", async function keycloakUserSyncPreSave() {
     assertNoDocumentSession(this, "save");
@@ -640,5 +569,6 @@ function keycloakUserSyncPlugin(schema, rawOptions) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  createManagedKeycloakClient,
   keycloakUserSyncPlugin
 });

package/plugins/keycloak-user-sync.mjs

@@ -1,53 +1,7 @@
-// src/plugins/keycloak-user-sync/adapter.ts
-var createKeycloakUserSyncAdapter = (client, realm) => {
-  const supportedClient = client;
-  const realmHandle = () => supportedClient.realm(realm);
-  const users = supportedClient.core.users;
-  return {
-    async getRealm() {
-      return realmHandle().get();
-    },
-    async getUserById(username, id) {
-      return realmHandle().user(username).getById(id);
-    },
-    async getUserByUsername(username) {
-      return realmHandle().user(username).get();
-    },
-    async findUsersByEmail(email) {
-      return users.find({ realm, email, exact: true, first: 0, max: 2 });
-    },
-    async createUser(username, payload) {
-      return realmHandle().user(username).create(payload);
-    },
-    async updateUser(id, payload) {
-      await users.update({ realm, id }, payload);
-    },
-    async deleteUser(id) {
-      await users.del({ realm, id });
-    },
-    async sendVerifyEmail(id) {
-      await users.sendVerifyEmail({ realm, id });
-    },
-    async resetPassword(id, value, temporary) {
-      await users.resetPassword({ realm, id, credential: { temporary, type: "password", value } });
-    },
-    async ensureRole(name) {
-      await realmHandle().role(name).ensure({});
-    },
-    async getRole(name) {
-      return realmHandle().role(name).get();
-    },
-    async listRealmRoleMappings(id) {
-      return users.listRealmRoleMappings({ realm, id });
-    },
-    async addRealmRoleMappings(id, roles) {
-      await users.addRealmRoleMappings({ realm, id, roles });
-    },
-    async delRealmRoleMappings(id, roles) {
-      await users.delRealmRoleMappings({ realm, id, roles });
-    }
-  };
-};
+// src/plugins/keycloak-user-sync.ts
+import {
+  createManagedKeycloakClient
+} from "@egose/keycloak-fluent";
 
 // src/plugins/keycloak-user-sync/planner.ts
 var dangerousAttributeKeys = /* @__PURE__ */ new Set(["__proto__", "prototype", "constructor"]);
@@ -196,18 +150,6 @@ var planEmailVerification = ({
     initialLinkSameEmail
   };
 };
-var planRoleDiff = (desiredNames, assignedRoles, desiredRoles, managedRoles) => {
-  const managedNames = managedRoles ? new Set(managedRoles) : null;
-  const effectiveDesiredNames = managedNames ? desiredNames.filter((name) => managedNames.has(name)) : desiredNames;
-  const assignedNames = new Set(assignedRoles.map((role) => role.name).filter((name) => Boolean(name)));
-  const desiredNameSet = new Set(effectiveDesiredNames);
-  return {
-    desiredNames,
-    effectiveDesiredNames,
-    toAdd: desiredRoles.filter((role) => role.name && !assignedNames.has(role.name)),
-    toRemove: managedNames ? assignedRoles.filter((role) => role.name && !desiredNameSet.has(role.name) && managedNames.has(role.name)) : []
-  };
-};
 
 // src/plugins/keycloak-user-sync.ts
 var syncStateKey = "keycloakUserSync";
@@ -387,7 +329,7 @@ function keycloakUserSyncPlugin(schema, rawOptions) {
   const paths = options.paths;
   const syncFields = options.syncFields;
   const identities = options.identifyBy;
-  const adapter = createKeycloakUserSyncAdapter(options.client, options.realm);
+  const realmHandle = options.client.realm(options.realm);
   const trackedPaths = buildTrackedPaths(options);
   const buildSafeErrorContext = (operation, document) => ({
     operation,
@@ -411,13 +353,13 @@ function keycloakUserSyncPlugin(schema, rawOptions) {
   const getPreviousValue = (previous, field) => getPathValue(previous, paths[field]);
   const getUsername = (document) => stringValue(readDocumentValue(document, "username")) ?? stringValue(readDocumentValue(document, "email"));
   const resolveUser = async (document, previous) => {
-    const realm = await adapter.getRealm();
+    const realm = await realmHandle.get();
     if (!realm) throw new Error(`Keycloak realm "${options.realm}" was not found`);
     const duplicateEmailsAllowed = realm.duplicateEmailsAllowed === true;
     const orderedIdentities = duplicateEmailsAllowed ? ["providerId", "username", "email"].filter((identity) => identities.includes(identity)) : identities;
     const getCompleteUserById = async (user) => {
       if (!user.id) return user;
-      return await adapter.getUserById(user.username ?? user.id, user.id) ?? user;
+      return await realmHandle.userById(user.id).get() ?? user;
     };
     for (const identity of orderedIdentities) {
       if (identity === "providerId") {
@@ -425,7 +367,7 @@ function keycloakUserSyncPlugin(schema, rawOptions) {
           readDocumentValue(document, "providerId"),
           getPreviousValue(previous, "providerId")
         ])) {
-          const user = await adapter.getUserById(getUsername(document) ?? providerId, providerId);
+          const user = await realmHandle.userById(providerId).get();
           if (user) return { user, duplicateEmailsAllowed };
         }
       }
@@ -434,7 +376,7 @@ function keycloakUserSyncPlugin(schema, rawOptions) {
           readDocumentValue(document, "username"),
           getPreviousValue(previous, "username")
         ])) {
-          const user = await adapter.getUserByUsername(username);
+          const user = await realmHandle.user(username).get();
           if (user) return { user, duplicateEmailsAllowed };
         }
       }
@@ -443,9 +385,7 @@ function keycloakUserSyncPlugin(schema, rawOptions) {
           readDocumentValue(document, "email"),
           getPreviousValue(previous, "email")
         ])) {
-          const matches = (await adapter.findUsersByEmail(email)).filter(
-            (user) => normalizeEmail(user.email) === normalizeEmail(email)
-          );
+          const matches = (await realmHandle.searchUsers(email, { attribute: "email", exact: true, first: 0, max: 2 })).filter((user) => normalizeEmail(user.email) === normalizeEmail(email));
           if (matches.length > 1) {
             throw new Error("Cannot identify a unique Keycloak user for the configured email identity");
           }
@@ -456,17 +396,15 @@ function keycloakUserSyncPlugin(schema, rawOptions) {
     return { user: null, duplicateEmailsAllowed };
   };
   const resolveCreatedUser = async (document, username) => {
-    const userByUsername = await adapter.getUserByUsername(username);
+    const userByUsername = await realmHandle.user(username).get();
     if (userByUsername) return userByUsername;
     const email = stringValue(readDocumentValue(document, "email"));
     if (!email) return null;
-    const matches = (await adapter.findUsersByEmail(email)).filter(
-      (user) => normalizeEmail(user.email) === normalizeEmail(email)
-    );
+    const matches = (await realmHandle.searchUsers(email, { attribute: "email", exact: true, first: 0, max: 2 })).filter((user) => normalizeEmail(user.email) === normalizeEmail(email));
     if (matches.length > 1) throw new Error("Cannot identify a unique Keycloak user for the configured email identity");
     const match = matches[0];
     if (!match?.id) return match ?? null;
-    return await adapter.getUserById(match.username ?? match.id, match.id) ?? match;
+    return await realmHandle.userById(match.id).get() ?? match;
   };
   const syncRoles = async (user, document) => {
     if (!syncFields.roles || !user.id) return;
@@ -476,24 +414,12 @@ function keycloakUserSyncPlugin(schema, rawOptions) {
     if (desiredNames.length > maxRolesPerSync) {
       throw new Error(`keycloakUserSyncPlugin supports at most ${maxRolesPerSync} desired roles per sync operation`);
     }
-    const managedNames = options.managedRoles ? new Set(options.managedRoles) : null;
-    const effectiveDesiredNames = managedNames ? desiredNames.filter((name) => managedNames.has(name)) : desiredNames;
-    if (effectiveDesiredNames.length === 0 && !managedNames) return;
-    const desiredRoles = [];
-    for (const roleName of effectiveDesiredNames) {
-      if (options.ensureRoles !== false) await adapter.ensureRole(roleName);
-      const role = await adapter.getRole(roleName);
-      if (!role?.id) throw new Error(`Keycloak realm role "${roleName}" was not found`);
-      desiredRoles.push(role);
-    }
-    const assignedRoles = await adapter.listRealmRoleMappings(user.id);
-    const { toAdd, toRemove } = planRoleDiff(desiredNames, assignedRoles, desiredRoles, options.managedRoles);
-    if (toAdd.length) {
-      await adapter.addRealmRoleMappings(user.id, toAdd);
-    }
-    if (toRemove.length) {
-      await adapter.delRealmRoleMappings(user.id, toRemove);
-    }
+    if (desiredNames.length === 0 && !options.managedRoles) return;
+    await realmHandle.userById(user.id).reconcileRealmRoles(desiredNames, {
+      ensureMissing: options.ensureRoles !== false,
+      managedRoleNames: options.managedRoles,
+      maxRoles: maxRolesPerSync
+    });
   };
   const persistProviderId = async (document, providerId) => {
     if (options.persistProviderId === false || readDocumentValue(document, "providerId") === providerId) return;
@@ -520,14 +446,20 @@ function keycloakUserSyncPlugin(schema, rawOptions) {
       if (!username) throw new Error("Cannot create a Keycloak user without a username or email");
       payload.attributes = mergeAttributes(null, document, options);
       try {
-        user = await adapter.createUser(username, payload) ?? null;
+        user = await realmHandle.user(username).create({
+          ...payload,
+          ...desiredPassword && {
+            password: desiredPassword,
+            passwordTemporary: options.passwordTemporary ?? false
+          }
+        }) ?? null;
+        created = true;
       } catch (error) {
         if (identities.length === 0) throw error;
         const recoveredUser = await resolveCreatedUser(document, username);
         if (!recoveredUser) throw error;
         user = recoveredUser;
       }
-      created = true;
     }
     if (!user?.id) throw new Error("Keycloak did not return a user ID");
     const userId = user.id;
@@ -550,21 +482,21 @@ function keycloakUserSyncPlugin(schema, rawOptions) {
       }
       if (shouldSyncAttributes) payload.attributes = mergeAttributes(user, document, options);
       if (Object.keys(payload).length > 0) {
-        await adapter.updateUser(userId, payload);
+        await realmHandle.userById(userId).update(payload);
         user = { ...user, ...payload };
       }
     }
-    if ((created || state.passwordChanged) && desiredPassword) {
-      await adapter.resetPassword(userId, desiredPassword, options.passwordTemporary ?? false);
+    if (!created && state.passwordChanged && desiredPassword) {
+      await realmHandle.userById(userId).resetPassword(desiredPassword, { temporary: options.passwordTemporary ?? false });
     }
     if (created || state.changedFields.has("roles")) await syncRoles(user, document);
     if (emailVerificationPlan.changed && options.sendVerificationEmailOnChange !== false) {
-      await adapter.sendVerifyEmail(userId);
+      await realmHandle.userById(userId).sendVerifyEmail();
     }
   };
   const deleteDocument = async (document) => {
     const { user } = await resolveUser(document);
-    if (user?.id) await adapter.deleteUser(user.id);
+    if (user?.id) await realmHandle.userById(user.id).delete();
   };
   schema.pre("save", async function keycloakUserSyncPreSave() {
     assertNoDocumentSession(this, "save");
@@ -613,5 +545,6 @@ function keycloakUserSyncPlugin(schema, rawOptions) {
   );
 }
 export {
+  createManagedKeycloakClient,
   keycloakUserSyncPlugin
 };