@web-ts-toolkit/moo 0.37.0 → 0.38.0

package/README.md

@@ -11,13 +11,16 @@ pnpm add mongoose @web-ts-toolkit/moo
 Peer dependencies:
 
 - `mongoose >= 8`
+- `@egose/keycloak-fluent ^0.7` only when using `@web-ts-toolkit/moo/plugins/keycloak-user-sync`
 
 ## Highlights
 
 - partial-index helpers for nullable or empty-string fields
 - strict `isObjectId(...)` guard
 - model-function plugin
+- new-document plugin
 - cascade-delete plugin
+- optional Keycloak user-sync plugin through a dedicated subpath
 
 ## Quick Start
 
@@ -37,6 +40,7 @@ Root entrypoint (`@web-ts-toolkit/moo`):
 
 - schema helpers such as `uniqueNullableString(...)`
 - `isObjectId(...)`
+- document plugins except Keycloak user sync
 
 Subpath entrypoints:
 
@@ -46,6 +50,10 @@ Subpath entrypoints:
 - `@web-ts-toolkit/moo/plugins` — plugin entrypoint
 - `@web-ts-toolkit/moo/plugins/cascade-delete` — cascade-delete plugin
 - `@web-ts-toolkit/moo/plugins/model-function` — model-function plugin
+- `@web-ts-toolkit/moo/plugins/new-document` — new-document plugin
+- `@web-ts-toolkit/moo/plugins/keycloak-user-sync` — Keycloak user-sync plugin
+
+The Keycloak plugin is intentionally not re-exported from the root or grouped `@web-ts-toolkit/moo/plugins` entrypoints. Non-Keycloak consumers only need `mongoose`; Keycloak consumers should install `@egose/keycloak-fluent` and import `keycloakUserSyncPlugin` from the direct subpath.
 
 ### Subpath import example
 
@@ -58,9 +66,136 @@ const userSchema = new Schema({
   email: uniqueEmptiableString('email'),
 });
 
-userSchema.plugin(cascadeDeletePlugin, { foreignKey: 'parentRef' });
+userSchema.plugin(cascadeDeletePlugin, {
+  model: 'Session',
+  localField: '_id',
+  foreignField: 'userId',
+});
+```
+
+## New Document Plugin
+
+```ts
+import { Schema } from 'mongoose';
+import { newDocumentPlugin } from '@web-ts-toolkit/moo/plugins/new-document';
+
+const userSchema = new Schema({
+  email: String,
+});
+
+userSchema.plugin(newDocumentPlugin, {
+  async fn(user) {
+    await sendWelcomeEmail(user.email);
+  },
+});
 ```
 
+The plugin runs `fn` after the first successful `save()` of a new document. Later saves of the same document do not run it.
+
+## Keycloak User Sync
+
+Install the optional Keycloak peer before using this entrypoint:
+
+```sh
+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';
+
+const keycloak = new KeycloakAdminClientFluent({
+  baseUrl: process.env.KEYCLOAK_URL,
+  realmName: 'master',
+});
+
+await keycloak.simpleAuth({
+  clientId: process.env.KEYCLOAK_CLIENT_ID,
+  clientSecret: process.env.KEYCLOAK_CLIENT_SECRET,
+});
+
+const userSchema = new Schema({
+  providerId: String,
+  username: String,
+  email: String,
+  emailVerified: Boolean,
+  firstName: String,
+  lastName: String,
+  archived: Boolean,
+  roles: [String],
+  pendingPassword: String,
+});
+
+userSchema.plugin(keycloakUserSyncPlugin, {
+  client: keycloak,
+  realm: 'application',
+  identifyBy: ['providerId', 'username', 'email'],
+  managedRoles: ['admin', 'editor', 'viewer'],
+  managedAttributes: ['tenantId', 'plan'],
+  paths: {
+    password: 'pendingPassword', // pragma: allowlist secret
+  },
+  syncFields: {
+    firstName: true,
+    lastName: true,
+    email: true,
+    roles: true,
+    attributes: true,
+    password: true,
+  },
+  passwordTemporary: true,
+  mapPassword(document) {
+    return document.get('pendingPassword') as string | undefined;
+  },
+  attributePaths: ['tenantId', 'subscription.plan'],
+  mapAttributes(document) {
+    return {
+      tenantId: document.get('tenantId'),
+      plan: document.get('subscription.plan'),
+    };
+  },
+  onError(error, context) {
+    reportKeycloakSyncError({ error, context });
+  },
+});
+```
+
+The plugin:
+
+- creates or updates a Keycloak user after a document `save()`
+- deletes the Keycloak user before a document `deleteOne()`
+- stores the Keycloak user ID in `providerId` by default
+- resets `emailVerified` and sends a verification email when an existing email changes and email-verification syncing is enabled
+- creates desired realm roles by default and removes assigned roles only within `managedRoles`
+- syncs Keycloak user attributes from an `attributes` path or a custom `mapAttributes` function
+- can update the Keycloak password when `syncFields.password` is explicitly enabled
+- reads `archived` as the inverse of Keycloak `enabled`, falling back to an `enabled` field
+
+Configuration is validated when `schema.plugin(...)` runs. `realm`, configured paths, managed role/attribute names, and attribute trigger paths are trimmed and must be non-empty. `identifyBy` accepts one identity or a non-empty ordered list containing only `providerId`, `username`, and `email`. Built-in synced field paths must exist in the Mongoose schema; mapper-driven `attributePaths` can name dynamic fields that the mapper reads. Register the plugin only once per schema.
+
+The plugin snapshots its options at registration, so later mutation of the caller's options object does not change sync behavior. `providerId` is server-controlled after persistence: applications may set it while creating a new document to link an existing Keycloak user, but changing it later is rejected before any remote call so ordinary document updates cannot redirect synchronization to another Keycloak account.
+
+When the realm allows duplicate emails, the plugin always prioritizes configured `providerId` and `username` identities before email. An email lookup proceeds only when it has exactly one match; multiple matches are reported as an error, and no user is changed or deleted.
+
+Use `paths` to map different Mongoose path names. Use `syncFields` to disable profile fields, role syncing, or attribute syncing. Use `mapRoles` to translate application roles. Role sync is additive-only by default: desired local roles are assigned, but unrelated existing Keycloak realm roles are preserved. Set `managedRoles` to the exact role names this plugin owns; only those roles may be removed when omitted from an explicit local roles array. An absent or non-array roles value is treated as no role-sync intent. An empty array intentionally removes currently assigned managed roles while preserving unmanaged roles. `ensureRoles` defaults to `true`, so desired missing roles are created before assignment; set it to `false` if typos or insufficient administrative privileges should fail instead of creating roles. `maxRolesPerSync` defaults to `100` and rejects larger desired role arrays before role lookup or mapping requests, bounding caller-controlled remote work.
+
+Email comparison is case-insensitive. Linking a new local document to an existing Keycloak user with the same email preserves the remote `emailVerified` value and does not send a verification email. A persisted local email change, or a detected remote email drift corrected back to the local value, resets `emailVerified` to `false` and sends VERIFY_EMAIL by default. Set `sendVerificationEmailOnChange: false` to skip the email action. Set `syncFields.emailVerified: false` to disable all email-verification writes, including forced revocation and VERIFY_EMAIL sends.
+
+For existing Keycloak users, owned string profile fields (`username`, `email`, `firstName`, and `lastName`) are updated when their local value is a non-empty string. Set a synced field to `null`, an empty string, or a whitespace-only string to clear the remote value. Leave it `undefined`, set `syncFields.<field>: false`, or omit the schema path from change detection to preserve unmanaged remote profile data. New-user creation omits clearing values because there is no stale remote value to remove.
+
+Attributes are normalized to Keycloak string arrays. Use `mapAttributes` for dynamic key/value mappings and `attributePaths` to list the Mongoose fields that should trigger an attribute resync. Existing unmanaged Keycloak attributes are preserved, including when a user is resolved by email. Set `managedAttributes` to the keys this plugin owns; managed keys are replaced by the mapper result and removed when omitted, returned as `null`/`undefined`, returned as an empty array, or mapped to unsupported object values. Attribute keys named `__proto__`, `prototype`, or `constructor` are rejected.
+
+Password sync is disabled by default to avoid sending stored password hashes to Keycloak. Enable it only when the mapped value is the plaintext password intended for Keycloak, such as a short-lived `pendingPassword` field. Passwords are never included in user-create or profile-update payloads; both newly created users and existing users are updated through Keycloak's reset-password endpoint with the configured `passwordTemporary` value. The plugin stores a newly resolved Keycloak user ID before optional password, role, and verification-email work so a later retry can converge on the same remote user instead of creating a duplicate. The application owns the lifecycle of plaintext password fields: keep them short-lived and prevent them from being persisted, logged, traced, or sent to error reporters beyond the intended Keycloak operation.
+
+Errors are logged to `console.error` and rethrown by default. The default logger context is redacted to safe metadata such as `operation` and `localDocumentId`; it never includes the Mongoose document, profile payload, email address, or password. `onError` receives the same safe context by default. Set `includeDocumentInErrorContext: true` only for private handlers that are allowed to receive the full Mongoose document, which can contain plaintext passwords, email addresses, attributes, and arbitrary application fields. Logger and `onError` failures do not replace the original Keycloak sync error; with `throwOnError: false`, those observer failures are best-effort and are swallowed.
+
+Only document `save()` and document `deleteOne()` are intercepted. Query operations such as `updateOne()`, `findOneAndUpdate()`, and query `deleteOne()` bypass the plugin. The selected delivery contract is direct, non-atomic hooks: Keycloak work is not part of the MongoDB commit, and the plugin rejects documents saved or deleted with a Mongoose session or transaction. Applications that need transactional delivery should write their own outbox intent in the MongoDB transaction and process it after commit.
+
+For saves, a Keycloak failure after MongoDB persistence cannot roll back the local write. With `throwOnError: true`, the original error is rethrown after the post-save hook; with `throwOnError: false`, logging and `onError` make the failure observable and the application must retry by changing/saving the document or by running its own repair job. For deletes, remote deletion runs before local deletion. If the remote delete fails, the local document deletion is blocked even when `throwOnError: false`, leaving the same provider ID available for an idempotent retry.
+
+Remote work is field-specific after identity resolution. A single owned profile or attribute change resolves the user and performs one update, without password reset or role reconciliation. A new user with no role-sync intent skips role mapping calls. Role reconciliation is sequential and deterministic; it performs one ensure/get pair per desired owned role plus one mapping list and optional add/remove calls. Realm metadata is fetched for each sync instead of cached, so duplicate-email policy changes are observed without an invalidation API.
+
 ## Documentation
 
 Full package documentation lives in `website/docs/packages/moo.md`.

package/index.d.mts

@@ -1,5 +1,6 @@
 export { ModelDocument, ModelFunctionInstanceMethods, ModelFunctionPluginOptions, ModelFunctionStaticMethods, modelFunctionPlugin } from './plugins/model-function.mjs';
 export { CascadeDeleteDependencyMap, CascadeDeleteDocumentMethods, CascadeDeleteModelStatics, CascadeDeletePluginOptions, FilterResolver, QueryFilter, cascadeDeletePlugin } from './plugins/cascade-delete.mjs';
+export { NewDocumentPluginOptions, newDocumentPlugin } from './plugins/new-document.mjs';
 export { uniqueEmptiableString, uniqueNullableString } from './schema.mjs';
 export { isObjectId } from './is.mjs';
 import 'mongoose';

package/index.d.ts

@@ -1,5 +1,6 @@
 export { ModelDocument, ModelFunctionInstanceMethods, ModelFunctionPluginOptions, ModelFunctionStaticMethods, modelFunctionPlugin } from './plugins/model-function.js';
 export { CascadeDeleteDependencyMap, CascadeDeleteDocumentMethods, CascadeDeleteModelStatics, CascadeDeletePluginOptions, FilterResolver, QueryFilter, cascadeDeletePlugin } from './plugins/cascade-delete.js';
+export { NewDocumentPluginOptions, newDocumentPlugin } from './plugins/new-document.js';
 export { uniqueEmptiableString, uniqueNullableString } from './schema.js';
 export { isObjectId } from './is.js';
 import 'mongoose';

package/index.js

@@ -33,6 +33,7 @@ __export(index_exports, {
   cascadeDeletePlugin: () => cascadeDeletePlugin,
   isObjectId: () => isObjectId,
   modelFunctionPlugin: () => modelFunctionPlugin,
+  newDocumentPlugin: () => newDocumentPlugin,
   uniqueEmptiableString: () => uniqueEmptiableString,
   uniqueNullableString: () => uniqueNullableString
 });
@@ -199,6 +200,19 @@ function cascadeDeletePlugin(schema, options) {
   });
 }
 
+// src/plugins/new-document.ts
+var stateKey = "newDocumentPlugin";
+function newDocumentPlugin(schema, options) {
+  schema.pre("save", function newDocumentPluginPreSave() {
+    this.$locals[stateKey] = { wasNew: this.isNew };
+  });
+  schema.post("save", async function newDocumentPluginPostSave(document) {
+    const state = this.$locals[stateKey];
+    if (!state?.wasNew) return;
+    await options.fn.call(this, document);
+  });
+}
+
 // src/schema.ts
 var uniqueNullableString = (field, options = {}) => ({
   type: String,
@@ -239,6 +253,7 @@ function isObjectId(value) {
   cascadeDeletePlugin,
   isObjectId,
   modelFunctionPlugin,
+  newDocumentPlugin,
   uniqueEmptiableString,
   uniqueNullableString
 });

package/index.mjs

@@ -159,6 +159,19 @@ function cascadeDeletePlugin(schema, options) {
   });
 }
 
+// src/plugins/new-document.ts
+var stateKey = "newDocumentPlugin";
+function newDocumentPlugin(schema, options) {
+  schema.pre("save", function newDocumentPluginPreSave() {
+    this.$locals[stateKey] = { wasNew: this.isNew };
+  });
+  schema.post("save", async function newDocumentPluginPostSave(document) {
+    const state = this.$locals[stateKey];
+    if (!state?.wasNew) return;
+    await options.fn.call(this, document);
+  });
+}
+
 // src/schema.ts
 var uniqueNullableString = (field, options = {}) => ({
   type: String,
@@ -198,6 +211,7 @@ export {
   cascadeDeletePlugin,
   isObjectId,
   modelFunctionPlugin,
+  newDocumentPlugin,
   uniqueEmptiableString,
   uniqueNullableString
 };

package/llms.txt

@@ -29,7 +29,11 @@ Cascade-delete plugin:
 ```ts
 import { cascadeDeletePlugin } from '@web-ts-toolkit/moo/plugins/cascade-delete';
 
-userSchema.plugin(cascadeDeletePlugin, { foreignKey: 'parentRef' });
+userSchema.plugin(cascadeDeletePlugin, {
+  model: 'Session',
+  localField: '_id',
+  foreignField: 'userId',
+});
 ```
 
 Model-function plugin:
@@ -45,12 +49,59 @@ userSchema.plugin(modelFunctionPlugin, {
 // static + instance methods `fullName` and `fullNameById` are now available on the model
 ```
 
+New-document plugin:
+
+```ts
+import { newDocumentPlugin } from '@web-ts-toolkit/moo/plugins/new-document';
+
+userSchema.plugin(newDocumentPlugin, {
+  fn: async (doc) => {
+    await sendWelcomeEmail(doc.get('email'));
+  },
+});
+```
+
+Keycloak user-sync plugin:
+
+```ts
+import { keycloakUserSyncPlugin } from '@web-ts-toolkit/moo/plugins/keycloak-user-sync';
+
+userSchema.plugin(keycloakUserSyncPlugin, {
+  client: authenticatedKeycloakFluentClient,
+  realm: 'application',
+  identifyBy: ['providerId', 'username', 'email'],
+  managedRoles: ['admin', 'editor', 'viewer'],
+  managedAttributes: ['tenantId', 'plan'],
+  paths: { password: 'pendingPassword' }, // pragma: allowlist secret
+  syncFields: { email: true, firstName: true, lastName: true, roles: true, attributes: true, password: true },
+  passwordTemporary: true,
+  mapPassword: (doc) => doc.get('pendingPassword') as string | undefined,
+  attributePaths: ['tenantId', 'subscription.plan'],
+  mapAttributes: (doc) => ({
+    tenantId: doc.get('tenantId'),
+    plan: doc.get('subscription.plan'),
+  }),
+  onError: reportSyncError,
+});
+```
+
 ## Gotchas
 
 - peer dependency: `mongoose >= 8`
-- root entrypoint exports schema helpers and `isObjectId`; plugins and utils live under subpaths
+- 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
 - `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
+- Keycloak sync covers document `save()` and document `deleteOne()`, not query updates/deletes
+- Keycloak sync errors are logged and rethrown by default; MongoDB saves have already committed when post-save sync runs
+- duplicate-email realms prioritize providerId/username; email lookup is rejected when more than one exact match exists
+- Keycloak attributes sync from the `attributes` path or `mapAttributes`; values become string arrays
+- use `managedAttributes` for keys the plugin may remove; unmanaged remote attributes are preserved
+- use `attributePaths` when `mapAttributes` reads dynamic paths outside the default `attributes` path
+- password sync is opt-in with `syncFields.password: true`; map a plaintext pending password, not a stored hash
+- password updates use Keycloak reset-password; `passwordTemporary` defaults to false
 
 ## Subpaths
 
@@ -60,6 +111,8 @@ userSchema.plugin(modelFunctionPlugin, {
 - `@web-ts-toolkit/moo/plugins` — re-exports all plugins
 - `@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`
 
 ## 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.37.0",
+  "version": "0.38.0",
   "sideEffects": false,
   "keywords": [
     "mongoose",
@@ -56,16 +56,34 @@
       "import": "./plugins/model-function.mjs",
       "require": "./plugins/model-function.js",
       "default": "./plugins/model-function.js"
+    },
+    "./plugins/new-document": {
+      "types": "./plugins/new-document.d.ts",
+      "import": "./plugins/new-document.mjs",
+      "require": "./plugins/new-document.js",
+      "default": "./plugins/new-document.js"
+    },
+    "./plugins/keycloak-user-sync": {
+      "types": "./plugins/keycloak-user-sync.d.ts",
+      "import": "./plugins/keycloak-user-sync.mjs",
+      "require": "./plugins/keycloak-user-sync.js",
+      "default": "./plugins/keycloak-user-sync.js"
     }
   },
   "engines": {
     "node": ">=22"
   },
   "peerDependencies": {
+    "@egose/keycloak-fluent": "^0.7.0",
     "mongoose": ">=8.0.0"
   },
+  "peerDependenciesMeta": {
+    "@egose/keycloak-fluent": {
+      "optional": true
+    }
+  },
   "dependencies": {
-    "@web-ts-toolkit/utils": "0.37.0"
+    "@web-ts-toolkit/utils": "0.38.0"
   },
   "files": [
     "**/*",

package/plugins/index.d.mts

@@ -1,3 +1,4 @@
 export { ModelDocument, ModelFunctionInstanceMethods, ModelFunctionPluginOptions, ModelFunctionStaticMethods, modelFunctionPlugin } from './model-function.mjs';
 export { CascadeDeleteDependencyMap, CascadeDeleteDocumentMethods, CascadeDeleteModelStatics, CascadeDeletePluginOptions, FilterResolver, QueryFilter, cascadeDeletePlugin } from './cascade-delete.mjs';
+export { NewDocumentPluginOptions, newDocumentPlugin } from './new-document.mjs';
 import 'mongoose';

package/plugins/index.d.ts

@@ -1,3 +1,4 @@
 export { ModelDocument, ModelFunctionInstanceMethods, ModelFunctionPluginOptions, ModelFunctionStaticMethods, modelFunctionPlugin } from './model-function.js';
 export { CascadeDeleteDependencyMap, CascadeDeleteDocumentMethods, CascadeDeleteModelStatics, CascadeDeletePluginOptions, FilterResolver, QueryFilter, cascadeDeletePlugin } from './cascade-delete.js';
+export { NewDocumentPluginOptions, newDocumentPlugin } from './new-document.js';
 import 'mongoose';

package/plugins/index.js

@@ -31,7 +31,8 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var plugins_exports = {};
 __export(plugins_exports, {
   cascadeDeletePlugin: () => cascadeDeletePlugin,
-  modelFunctionPlugin: () => modelFunctionPlugin
+  modelFunctionPlugin: () => modelFunctionPlugin,
+  newDocumentPlugin: () => newDocumentPlugin
 });
 module.exports = __toCommonJS(plugins_exports);
 
@@ -195,8 +196,22 @@ function cascadeDeletePlugin(schema, options) {
     return mergeResults(previousResults, model, currentResults);
   });
 }
+
+// src/plugins/new-document.ts
+var stateKey = "newDocumentPlugin";
+function newDocumentPlugin(schema, options) {
+  schema.pre("save", function newDocumentPluginPreSave() {
+    this.$locals[stateKey] = { wasNew: this.isNew };
+  });
+  schema.post("save", async function newDocumentPluginPostSave(document) {
+    const state = this.$locals[stateKey];
+    if (!state?.wasNew) return;
+    await options.fn.call(this, document);
+  });
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   cascadeDeletePlugin,
-  modelFunctionPlugin
+  modelFunctionPlugin,
+  newDocumentPlugin
 });

package/plugins/index.mjs

@@ -158,7 +158,21 @@ function cascadeDeletePlugin(schema, options) {
     return mergeResults(previousResults, model, currentResults);
   });
 }
+
+// src/plugins/new-document.ts
+var stateKey = "newDocumentPlugin";
+function newDocumentPlugin(schema, options) {
+  schema.pre("save", function newDocumentPluginPreSave() {
+    this.$locals[stateKey] = { wasNew: this.isNew };
+  });
+  schema.post("save", async function newDocumentPluginPostSave(document) {
+    const state = this.$locals[stateKey];
+    if (!state?.wasNew) return;
+    await options.fn.call(this, document);
+  });
+}
 export {
   cascadeDeletePlugin,
-  modelFunctionPlugin
+  modelFunctionPlugin,
+  newDocumentPlugin
 };

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

@@ -0,0 +1,88 @@
+import KeycloakAdminClientFluent from '@egose/keycloak-fluent';
+import { Schema } from 'mongoose';
+
+type KeycloakUserIdentityField = 'providerId' | 'username' | 'email';
+type KeycloakUserSyncField = 'username' | 'email' | 'emailVerified' | 'firstName' | 'lastName' | 'enabled' | 'roles' | 'attributes' | 'password';
+interface KeycloakUserSyncPaths {
+    providerId: string;
+    username: string;
+    email: string;
+    emailVerified: string;
+    firstName: string;
+    lastName: string;
+    enabled: string;
+    archived: string;
+    roles: string;
+    attributes: string;
+    password: string;
+}
+interface KeycloakUserSyncErrorContext {
+    operation: 'save' | 'delete';
+    localDocumentId?: string;
+}
+interface KeycloakUserSyncSensitiveErrorContext extends KeycloakUserSyncErrorContext {
+    document: unknown;
+}
+interface KeycloakUserSyncLogger {
+    error(message: string, context: KeycloakUserSyncErrorContext & {
+        error: unknown;
+    }): void | Promise<void>;
+}
+interface KeycloakUserSyncDocument {
+    get(path: string): unknown;
+}
+interface KeycloakUserSyncPluginOptions {
+    /** An authenticated client. Authentication and token refresh remain the application's responsibility. */
+    client: KeycloakAdminClientFluent;
+    realm: string;
+    /**
+     * Identity fields to use. Must be non-empty. Defaults to providerId, username, then email.
+     * `providerId` is treated as server-controlled after persistence and cannot be reassigned by ordinary saves.
+     */
+    identifyBy?: KeycloakUserIdentityField | readonly KeycloakUserIdentityField[];
+    /** Override the Mongoose path used for each application-user property. Built-in synced fields must exist in the schema. */
+    paths?: Partial<KeycloakUserSyncPaths>;
+    /** Set a field to false to exclude it from change detection and Keycloak updates. */
+    syncFields?: Partial<Record<KeycloakUserSyncField, boolean>>;
+    /** Convert the configured roles path into Keycloak realm-role names. Role removals are limited by `managedRoles`. */
+    mapRoles?: (roles: unknown, document: KeycloakUserSyncDocument) => readonly string[];
+    /** Convert document state into Keycloak user attributes. Values are normalized to string arrays and unsafe keys are rejected. */
+    mapAttributes?: (document: KeycloakUserSyncDocument) => Record<string, unknown> | null | undefined;
+    /** Convert document state into a plaintext Keycloak password. Only used when syncFields.password is true. */
+    mapPassword?: (document: KeycloakUserSyncDocument) => string | null | undefined;
+    /** Mongoose paths that should trigger attribute syncing when mapAttributes reads dynamic fields. */
+    attributePaths?: readonly string[];
+    /** Attribute keys owned by this plugin. Only managed keys are removed when missing from the mapper result. */
+    managedAttributes?: readonly string[];
+    /** Role names this plugin owns. Role removal is limited to this set; without it, role sync is additive-only. */
+    managedRoles?: readonly string[];
+    /** Create missing desired realm roles before assigning them. Defaults to true; disable to fail on unknown roles. */
+    ensureRoles?: boolean;
+    /** Maximum desired role names accepted for one sync operation. Defaults to 100. */
+    maxRolesPerSync?: number;
+    /** Save a newly resolved Keycloak ID to the providerId path. Defaults to true. The providerId path is immutable after persistence. */
+    persistProviderId?: boolean;
+    /** Send VERIFY_EMAIL after changing an existing user's email when emailVerified syncing is enabled. Defaults to true. */
+    sendVerificationEmailOnChange?: boolean;
+    /** Mark reset-password credentials for created and existing users as temporary. Defaults to false. */
+    passwordTemporary?: boolean;
+    /**
+     * Called after a sync error. By default the context contains only safe metadata.
+     * Enable includeDocumentInErrorContext only for private handlers that can receive sensitive document state.
+     */
+    onError?: (error: unknown, context: KeycloakUserSyncErrorContext | KeycloakUserSyncSensitiveErrorContext) => void | Promise<void>;
+    /** Include the full Mongoose document in onError context. The document may contain plaintext passwords and PII. */
+    includeDocumentInErrorContext?: boolean;
+    /** Set to false to disable logging or provide a structured logger. Defaults to console. */
+    logger?: KeycloakUserSyncLogger | false;
+    /** Set to false to let document saves succeed after a Keycloak error. Deletes still block on remote delete failure. Defaults to true. */
+    throwOnError?: boolean;
+}
+/**
+ * Synchronizes document saves and document `deleteOne()` calls with a Keycloak user.
+ * Query updates and query deletes are intentionally not intercepted because they do not provide a document identity.
+ * Direct hooks are non-atomic with MongoDB and reject Mongoose sessions/transactions; use an application outbox for transactional delivery.
+ */
+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 };

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

@@ -0,0 +1,88 @@
+import KeycloakAdminClientFluent from '@egose/keycloak-fluent';
+import { Schema } from 'mongoose';
+
+type KeycloakUserIdentityField = 'providerId' | 'username' | 'email';
+type KeycloakUserSyncField = 'username' | 'email' | 'emailVerified' | 'firstName' | 'lastName' | 'enabled' | 'roles' | 'attributes' | 'password';
+interface KeycloakUserSyncPaths {
+    providerId: string;
+    username: string;
+    email: string;
+    emailVerified: string;
+    firstName: string;
+    lastName: string;
+    enabled: string;
+    archived: string;
+    roles: string;
+    attributes: string;
+    password: string;
+}
+interface KeycloakUserSyncErrorContext {
+    operation: 'save' | 'delete';
+    localDocumentId?: string;
+}
+interface KeycloakUserSyncSensitiveErrorContext extends KeycloakUserSyncErrorContext {
+    document: unknown;
+}
+interface KeycloakUserSyncLogger {
+    error(message: string, context: KeycloakUserSyncErrorContext & {
+        error: unknown;
+    }): void | Promise<void>;
+}
+interface KeycloakUserSyncDocument {
+    get(path: string): unknown;
+}
+interface KeycloakUserSyncPluginOptions {
+    /** An authenticated client. Authentication and token refresh remain the application's responsibility. */
+    client: KeycloakAdminClientFluent;
+    realm: string;
+    /**
+     * Identity fields to use. Must be non-empty. Defaults to providerId, username, then email.
+     * `providerId` is treated as server-controlled after persistence and cannot be reassigned by ordinary saves.
+     */
+    identifyBy?: KeycloakUserIdentityField | readonly KeycloakUserIdentityField[];
+    /** Override the Mongoose path used for each application-user property. Built-in synced fields must exist in the schema. */
+    paths?: Partial<KeycloakUserSyncPaths>;
+    /** Set a field to false to exclude it from change detection and Keycloak updates. */
+    syncFields?: Partial<Record<KeycloakUserSyncField, boolean>>;
+    /** Convert the configured roles path into Keycloak realm-role names. Role removals are limited by `managedRoles`. */
+    mapRoles?: (roles: unknown, document: KeycloakUserSyncDocument) => readonly string[];
+    /** Convert document state into Keycloak user attributes. Values are normalized to string arrays and unsafe keys are rejected. */
+    mapAttributes?: (document: KeycloakUserSyncDocument) => Record<string, unknown> | null | undefined;
+    /** Convert document state into a plaintext Keycloak password. Only used when syncFields.password is true. */
+    mapPassword?: (document: KeycloakUserSyncDocument) => string | null | undefined;
+    /** Mongoose paths that should trigger attribute syncing when mapAttributes reads dynamic fields. */
+    attributePaths?: readonly string[];
+    /** Attribute keys owned by this plugin. Only managed keys are removed when missing from the mapper result. */
+    managedAttributes?: readonly string[];
+    /** Role names this plugin owns. Role removal is limited to this set; without it, role sync is additive-only. */
+    managedRoles?: readonly string[];
+    /** Create missing desired realm roles before assigning them. Defaults to true; disable to fail on unknown roles. */
+    ensureRoles?: boolean;
+    /** Maximum desired role names accepted for one sync operation. Defaults to 100. */
+    maxRolesPerSync?: number;
+    /** Save a newly resolved Keycloak ID to the providerId path. Defaults to true. The providerId path is immutable after persistence. */
+    persistProviderId?: boolean;
+    /** Send VERIFY_EMAIL after changing an existing user's email when emailVerified syncing is enabled. Defaults to true. */
+    sendVerificationEmailOnChange?: boolean;
+    /** Mark reset-password credentials for created and existing users as temporary. Defaults to false. */
+    passwordTemporary?: boolean;
+    /**
+     * Called after a sync error. By default the context contains only safe metadata.
+     * Enable includeDocumentInErrorContext only for private handlers that can receive sensitive document state.
+     */
+    onError?: (error: unknown, context: KeycloakUserSyncErrorContext | KeycloakUserSyncSensitiveErrorContext) => void | Promise<void>;
+    /** Include the full Mongoose document in onError context. The document may contain plaintext passwords and PII. */
+    includeDocumentInErrorContext?: boolean;
+    /** Set to false to disable logging or provide a structured logger. Defaults to console. */
+    logger?: KeycloakUserSyncLogger | false;
+    /** Set to false to let document saves succeed after a Keycloak error. Deletes still block on remote delete failure. Defaults to true. */
+    throwOnError?: boolean;
+}
+/**
+ * Synchronizes document saves and document `deleteOne()` calls with a Keycloak user.
+ * Query updates and query deletes are intentionally not intercepted because they do not provide a document identity.
+ * Direct hooks are non-atomic with MongoDB and reject Mongoose sessions/transactions; use an application outbox for transactional delivery.
+ */
+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 };