@web-ts-toolkit/message-service 0.52.0 → 0.53.0

package/index.mjs

@@ -205,25 +205,32 @@ function includesAction(templateCd, actionCd, registry) {
 
 // src/schemas/methods.ts
 import { Types } from "mongoose";
+function isValidMessageUserRoles(roles) {
+  if (roles === void 0) return true;
+  if (!Array.isArray(roles)) return false;
+  for (const role of roles) {
+    if (typeof role !== "string") return false;
+  }
+  return true;
+}
 function isSender(user) {
-  const fromUser = normalizeStoredUserId(this.fromUser);
-  const userId = normalizeMessageUserId(user);
-  return fromUser !== null && userId !== null && fromUser === userId;
+  if (!isValidMessageUserRoles(user?.roles)) return false;
+  return matchesStoredUserId(this.fromUser, user);
 }
 function isReceiver(user) {
-  const toUser = normalizeStoredUserId(this.toUser);
-  const userId = normalizeMessageUserId(user);
-  return toUser !== null && userId !== null && toUser === userId || this.toRoles.some((r) => user.roles?.includes(r));
+  const roles = user?.roles;
+  if (!isValidMessageUserRoles(roles)) return false;
+  return matchesStoredUserId(this.toUser, user) || this.toRoles.some((r) => roles?.includes(r));
 }
-function normalizeMessageUserId(user) {
-  return normalizeId(user?._id);
-}
-function normalizeStoredUserId(value) {
-  if (value instanceof Types.ObjectId) return value.toHexString();
-  if (value !== null && typeof value === "object") {
-    return normalizeId(value._id);
-  }
-  return normalizeId(value);
+function matchesStoredUserId(value, user) {
+  const stored = value instanceof Types.ObjectId || value === null || typeof value !== "object" ? value : value._id;
+  const userId = normalizeId(user?._id);
+  if (userId === null) return false;
+  if (stored instanceof Types.ObjectId && /^[a-f\d]{24}$/i.test(userId)) {
+    return stored.toHexString() === userId.toLowerCase();
+  }
+  const storedId = normalizeId(stored);
+  return storedId !== null && storedId === userId;
 }
 function normalizeId(value) {
   if (typeof value === "string") {
@@ -233,6 +240,11 @@ function normalizeId(value) {
   return value instanceof Types.ObjectId ? value.toHexString() : null;
 }
 
+// src/user-id.ts
+function normalizeUserIdForStorage(id) {
+  return typeof id === "string" ? id.trim() : id;
+}
+
 // src/errors.ts
 var TRANSACTION_REQUIRED_MESSAGE = "message-service requires MongoDB replica set or sharded-cluster transactions for idempotent batch creation";
 var MessageNotFoundError = class extends Error {
@@ -285,6 +297,16 @@ var ActionNotAllowedError = class extends Error {
     markRuntimeError(this, this.name);
   }
 };
+var ActionInputValidationError = class extends Error {
+  static [Symbol.hasInstance](value) {
+    return isRuntimeError(value, "ActionInputValidationError");
+  }
+  constructor(message = "invalid action input") {
+    super(message);
+    this.name = "ActionInputValidationError";
+    markRuntimeError(this, this.name);
+  }
+};
 var InvalidMessageUserError = class extends Error {
   static [Symbol.hasInstance](value) {
     return isRuntimeError(value, "InvalidMessageUserError");
@@ -440,6 +462,16 @@ var MessageModelResolutionError = class extends Error {
     }
   }
 };
+var PaymentProviderRequiredError = class extends Error {
+  static [Symbol.hasInstance](value) {
+    return isRuntimeError(value, "PaymentProviderRequiredError");
+  }
+  constructor() {
+    super("paymentProvider is required for messages with a non-empty paymentCd");
+    this.name = "PaymentProviderRequiredError";
+    markRuntimeError(this, this.name);
+  }
+};
 var PaymentSessionCompensationError = class extends Error {
   static [Symbol.hasInstance](value) {
     return isRuntimeError(value, "PaymentSessionCompensationError") || isRuntimeError(value, "PaymentSessionCompensationAggregateError");
@@ -650,6 +682,9 @@ function requireMessageUserId(user) {
   if (!isValidMessageUserId(id)) {
     throw new InvalidMessageUserError();
   }
+  if (!isValidMessageUserRoles(user.roles)) {
+    throw new InvalidMessageUserError("user.roles must be an array of strings when provided");
+  }
   return typeof id === "string" ? id.trim() : String(id);
 }
 var MessageService = class {
@@ -689,7 +724,11 @@ var MessageService = class {
     );
     this.clientRequestDelay = options.clientRequestDelay ?? this.delay;
     this.clientRequestNow = options.clientRequestNow ?? (() => Date.now());
-    this.actionLeaseMs = ACTION_LEASE_MS;
+    this.actionLeaseMs = this.validateDurationOption(
+      "actionLeaseMs",
+      options.actionLeaseMs === void 0 ? ACTION_LEASE_MS : options.actionLeaseMs,
+      1
+    );
   }
   // -------------------------------------------------------------------------
   // Message lookup
@@ -735,10 +774,25 @@ var MessageService = class {
    *
    * User-facing entry point: `user` (and `payerUser` when provided) must
    * carry a valid principal id (non-empty string or ObjectId; numbers,
-   * arrays, and plain objects are rejected with `InvalidMessageUserError`)
+   * arrays, and plain objects are rejected with `InvalidMessageUserError`),
+   * and optional `roles` must be undefined or an array of strings,
    * before any template, provider, or model effect runs. Both the
    * idempotent (`clientRequestId`) and direct branches enforce this.
    *
+   * Each `PrepareResult.documents` selects that item's attachments; `[]` clears
+   * them. Omission/undefined retains the original caller `payload.documents`
+   * fallback, independently of the prepared business payload. Selected arrays
+   * are copied per item without mutating caller/preparation arrays.
+   *
+   * Each fresh item's `item.paymentCd || template.paymentCd || ''` requests a
+   * session when nonempty, independently of recipients. An empty item override
+   * inherits the template code. Absent/null providers throw
+   * `PaymentProviderRequiredError`; configured-provider rejections propagate and
+   * null/empty session returns throw `Error('payment session creation failed')`.
+   * The payer remains `(payerUser || user)._id`, not the prepared sender/recipient.
+   * Direct batches retain committed prefixes; idempotent batches commit atomically
+   * and compensate all known uncommitted sessions on failure.
+   *
    * Idempotent replay contract (MSGF-06): a completed same-scope replay
    * returns the current active/archive records merged from both collections
    * (`Array<IMessage | IMessageArchive>`), sorted by exact
@@ -906,15 +960,17 @@ var MessageService = class {
    * or matches one of the recipient's roles.
    *
    * User-facing operation: validates `user` via the shared principal
-   * contract. Returns `IMessage[]` ordered by `{ createdAt: -1, _id: -1 }`.
+   * contract before model resolution. Returns `IMessage[]` ordered by
+   * `{ createdAt: -1, _id: -1 }`.
    */
   async listMessages(params) {
     const { user, limit: rawLimit, skip: rawSkip, populate } = params;
     const limit = this.normalizeListLimit(rawLimit);
     const skip = this.normalizeListSkip(rawSkip);
+    const filter = this.buildVisibilityFilter(user);
     const Message = this.resolveModel("active");
     const query = this.applyPopulate(
-      Message.find(this.buildVisibilityFilter(user)).sort({ createdAt: -1, _id: -1 }).skip(skip).limit(limit),
+      Message.find(filter).sort({ createdAt: -1, _id: -1 }).skip(skip).limit(limit),
       populate
     );
     return query;
@@ -923,11 +979,13 @@ var MessageService = class {
    * Count active (non-archived) messages visible to a user.
    * Useful for badge indicators ("3 new messages").
    *
-   * User-facing operation: validates `user` via the shared principal contract.
+   * User-facing operation: validates `user` via the shared principal contract
+   * before model resolution.
    */
   async countMessages(user) {
+    const filter = this.buildVisibilityFilter(user);
     const Message = this.resolveModel("active");
-    return Message.countDocuments(this.buildVisibilityFilter(user));
+    return Message.countDocuments(filter);
   }
   // -------------------------------------------------------------------------
   // Get actions for a message
@@ -954,8 +1012,7 @@ var MessageService = class {
    * render empty), distinct from creation-time `templateData`.
    */
   async getActions(messageId, usertype, options) {
-    const user = requireMessageUserId(options?.user);
-    const authorizedUser = { ...options.user, _id: user };
+    const authorizedUser = this.buildAuthorizedUser(options?.user);
     const message = await this.findMessage(messageId);
     if (!message) return null;
     if (!options.isAdmin) {
@@ -989,18 +1046,33 @@ var MessageService = class {
    * Execute an action with a durable claim, stable handler attempt key,
    * transactional archive, and post-commit sender notification status.
    *
+   * `actionLeaseMs` controls when a same-action retry may take over. Expiry alone
+   * does not cancel the handler or reject a still-current owner; takeover fences
+   * stale completion/failure writes with `ActionConflictError`. There is no
+   * heartbeat or renewal; external effects must deduplicate by `actionAttemptId`.
+   *
    * User-facing operation: `data.user` is validated before any template or
-   * model effect. Authorization and handler selection bind to the persisted
+   * model effect. Handler users contain only the documented `MessageUser`
+   * fields, read explicitly (including getters), with a copied roles array;
+   * the caller's user and original `req` are not modified.
+   * Authorization and handler selection bind to the persisted
    * claim, not the caller-supplied `data.message` copy. Archived messages
    * are re-read by id on their owning connection and apply a stored
    * sender/receiver relationship gate before disclosing current attempt IDs
    * or notification state. A missing archive throws `MessageNotFoundError`.
+   * `data.input` is explicit submitted data, never inferred from `req`. The
+   * current claimed action's optional synchronous pure `parseInput` supplies
+   * `ctx.input` after authorization. Invalid input throws
+   * `ActionInputValidationError`; unexpected parser failures preserve their
+   * cause as server errors. Both use fenced pre-handler release: fresh claims
+   * return to active, retries retain their stable attempt/action as retryable.
+   * Hosts own input bounds, runtime validation, and durable command/result
+   * binding at first host reservation (not at package claim).
    * Returns the handler's value (`unknown`; templates
    * document their own shape).
    */
   async handleAction(templateCd, actionCd, data) {
-    const userId = this.requireUserId(data.user);
-    const authorizedUser = { ...data.user, _id: userId };
+    const authorizedUser = this.buildAuthorizedUser(data.user);
     if (this.isArchivedMessage(data.message)) {
       const archived = await this.resolveModel("archive", data.message).findById(
         data.message._id
@@ -1020,25 +1092,28 @@ var MessageService = class {
     }
     const claim = await this.claimAction(data.message, actionCd, authorizedUser);
     let authorizedAction;
+    let input;
     try {
       authorizedAction = this.authorizeClaimedAction(templateCd, actionCd, claim.message, authorizedUser, {
         permissions: data.permissions
       });
-    } catch (authError) {
+      input = this.parseActionInput(authorizedAction, data.input);
+    } catch (preHandlerError) {
       try {
-        await this.releaseDeniedActionClaim(claim, authError);
+        await this.releaseDeniedActionClaim(claim, preHandlerError);
       } catch (releaseError) {
         if (!(releaseError instanceof ActionConflictError)) {
           throw releaseError;
         }
       }
-      throw authError;
+      throw preHandlerError;
     }
     const ctx = this.buildActionContext({
       ...data,
       user: authorizedUser,
       message: claim.message,
-      actionAttemptId: claim.actionAttemptId
+      actionAttemptId: claim.actionAttemptId,
+      input
     });
     let result;
     try {
@@ -1159,13 +1234,14 @@ var MessageService = class {
     }
   }
   async buildMessageDocument(template, m, ctx, clientRequestScope, clientRequestItemIndex) {
-    const toUser = m.toUser ?? null;
-    const toRoles = (m.toRoles && m.toRoles.length > 0 ? m.toRoles : this.adminRoles).slice();
+    const toUser = m.toUser == null ? null : normalizeUserIdForStorage(m.toUser);
+    const toRoles = (m.toRoles && m.toRoles.length > 0 ? m.toRoles : toUser === null ? this.adminRoles : []).slice();
     const type = m.type || template.type || "notification";
     const paymentCd = m.paymentCd || template.paymentCd || "";
     let paymentSession = null;
     try {
-      if (paymentCd && this.paymentProvider && (toUser || toRoles.length > 0)) {
+      if (paymentCd) {
+        if (!this.paymentProvider) throw new PaymentProviderRequiredError();
         paymentSession = await this.paymentProvider.createSession(
           (ctx.payerUser || ctx.user)._id,
           paymentCd,
@@ -1177,12 +1253,12 @@ var MessageService = class {
       return {
         type,
         templateCd: template.templateCd,
-        fromUser: m.fromUser || ctx.user._id,
+        fromUser: normalizeUserIdForStorage(m.fromUser || ctx.user._id),
         toUser,
         toRoles,
         senderContent: interpolated.senderContent,
         receiverContent: interpolated.receiverContent,
-        documents: ctx.payload.documents || [],
+        documents: (m.documents !== void 0 ? m.documents : ctx.payload.documents || []).slice(),
         paymentSession,
         paymentCd,
         payload: m.payload || ctx.payload,
@@ -1292,12 +1368,36 @@ var MessageService = class {
       message: data.message,
       user: data.user,
       actionAttemptId: data.actionAttemptId,
+      input: data.input,
       getModel: this.getTemplateModelResolver(data.message),
       expireSession: this.expirePaymentSession,
       refundPayment: this.refundPaymentSession,
       req: data.req
     };
   }
+  parseActionInput(action, input) {
+    if (!action.parseInput) return input;
+    try {
+      const parsed = action.parseInput(input);
+      if (parsed !== null && (typeof parsed === "object" || typeof parsed === "function")) {
+        const then = parsed.then;
+        if (typeof then === "function") {
+          void Promise.resolve().then(() => {
+            const discarded = Reflect.apply(then, parsed, [() => {
+            }, () => {
+            }]);
+            return discarded === parsed ? void 0 : discarded;
+          }).catch(() => {
+          });
+          throw new Error("action.parseInput must be synchronous");
+        }
+      }
+      return parsed;
+    } catch (error) {
+      if (error instanceof ActionInputValidationError) throw error;
+      throw new Error("action.parseInput failed", { cause: error });
+    }
+  }
   async claimAction(message, actionCd, user) {
     const Message = this.resolveModel("active", message);
     const messageId = message._id;
@@ -1624,6 +1724,11 @@ var MessageService = class {
   requireUserId(user) {
     return requireMessageUserId(user);
   }
+  buildAuthorizedUser(user) {
+    const _id = this.requireUserId(user);
+    const { id, roles, displayName } = user;
+    return { _id, id, roles: roles?.slice(), displayName };
+  }
   async findByClientRequestScope(scope) {
     const Message = this.resolveModel("active");
     const docs = await Message.find(scope).sort({ clientRequestItemIndex: 1, _id: 1 }).limit(Number.MAX_SAFE_INTEGER);
@@ -1917,7 +2022,7 @@ function createArchiveMethod(ctx) {
       const archiveDoc = {
         ...source,
         actionCd,
-        archivedBy,
+        archivedBy: normalizeUserIdForStorage(archivedBy),
         archivedAt: /* @__PURE__ */ new Date(),
         actionNotificationState: "none",
         actionNotificationError: null,
@@ -1986,22 +2091,31 @@ function createPostSaveEmailHook(ctx) {
     if (!title || ctx.emailNotificationExclusions.includes(normalizeEmailTitle(title))) {
       return;
     }
-    let user;
+    let email;
     try {
-      const User = resolveDocumentModel(this, ctx.userModelName, "user");
-      user = await User.findById(this.toUser).select("email").lean();
+      if (ctx.emailRecipientResolver) {
+        email = await ctx.emailRecipientResolver({
+          recipientId: this.toUser,
+          connection: this.constructor.db,
+          message: this
+        });
+      } else {
+        const User = resolveDocumentModel(this, ctx.userModelName, "user");
+        const user = await User.findById(this.toUser).select("email").lean();
+        email = user?.email;
+      }
     } catch (error) {
       await reportEmailFailure(ctx, "recipientLookup", error, this, title);
       return;
     }
-    if (!user?.email) {
+    if (!email) {
       return;
     }
     const long = this.receiverContent.long || "";
     const short = this.receiverContent.short || "";
     const body = long.length > short.length ? long : short;
     try {
-      await ctx.emailNotifier(user.email, title, body);
+      await ctx.emailNotifier(email, title, body);
     } catch (error) {
       await reportEmailFailure(ctx, "notifier", error, this, title);
     }
@@ -2031,6 +2145,7 @@ function resolveConfig(config) {
   return {
     onTransactionCleanupFailure: config?.onTransactionCleanupFailure,
     emailNotifier: config?.emailNotifier ?? null,
+    emailRecipientResolver: config?.emailRecipientResolver,
     onEmailDeliveryFailure: config?.onEmailDeliveryFailure,
     emailNotificationExclusions: (config?.emailNotificationExclusions ?? []).map(normalizeEmailTitle),
     userModelName: config?.userModelName ?? "User",
@@ -2040,7 +2155,7 @@ function resolveConfig(config) {
 }
 function buildMessageSchema(config) {
   const resolved = resolveConfig(config);
-  if (resolved.emailNotifier) {
+  if (resolved.emailNotifier && !resolved.emailRecipientResolver) {
     assertModelRegistered(resolved.connection, resolved.userModelName, "user");
   }
   const schema = new mongoose3.Schema(BaseMessageFields, {
@@ -2091,6 +2206,7 @@ function buildMessageSchema(config) {
       "save",
       createPostSaveEmailHook({
         emailNotifier: resolved.emailNotifier,
+        emailRecipientResolver: resolved.emailRecipientResolver,
         onEmailDeliveryFailure: resolved.onEmailDeliveryFailure,
         emailNotificationExclusions: resolved.emailNotificationExclusions,
         userModelName: resolved.userModelName
@@ -2317,6 +2433,9 @@ function isMongooseCastError(error) {
   return !!error && typeof error === "object" && error.name === "CastError";
 }
 function mapServiceError(error) {
+  if (error instanceof ActionInputValidationError) {
+    throw new JsonRouter.clientErrors.BadRequestError("invalid action input");
+  }
   if (error instanceof MessageNotFoundError) {
     throw new JsonRouter.clientErrors.NotFoundError("message not found");
   }
@@ -2368,6 +2487,7 @@ var SERVICE_CONSTRUCTION_KEYS = [
   "registry",
   "defaultListLimit",
   "maxListLimit",
+  "actionLeaseMs",
   "clientRequestLeaseMs",
   "clientRequestWaitMs",
   "clientRequestPollMs",
@@ -2406,6 +2526,7 @@ function createMessageRoutes(options) {
       registry: construction.registry,
       defaultListLimit: construction.defaultListLimit,
       maxListLimit: construction.maxListLimit,
+      actionLeaseMs: construction.actionLeaseMs,
       clientRequestLeaseMs: construction.clientRequestLeaseMs,
       clientRequestWaitMs: construction.clientRequestWaitMs,
       clientRequestPollMs: construction.clientRequestPollMs,
@@ -2476,7 +2597,13 @@ function createMessageRoutes(options) {
     }
     const permissions = getPermissions(req);
     try {
-      return await service.handleAction(message.templateCd, actionCd, { message, user, permissions, req });
+      return await service.handleAction(message.templateCd, actionCd, {
+        message,
+        user,
+        permissions,
+        input: req.body,
+        req
+      });
     } catch (error) {
       if (error instanceof ActionNotificationPendingError) {
         return new JsonRouter.success.Accepted({ message: error.message, actionAttemptId: error.actionAttemptId });
@@ -2499,6 +2626,7 @@ function defaultGetIdentity(req) {
 }
 export {
   ActionConflictError,
+  ActionInputValidationError,
   ActionNotAllowedError,
   ActionNotFoundError,
   ActionNotificationPendingError,
@@ -2528,6 +2656,7 @@ export {
   MessageTransactionRequiredError,
   NoopEmailProvider,
   NoopPaymentProvider,
+  PaymentProviderRequiredError,
   PaymentSessionCompensationAggregateError,
   PaymentSessionCompensationError,
   TemplateNotFoundError,

package/package.json

@@ -2,7 +2,7 @@
   "name": "@web-ts-toolkit/message-service",
   "description": "Template-driven messaging core for Mongoose + Express applications",
   "homepage": "https://web-ts-toolkit.pages.dev/docs/packages/message-service",
-  "version": "0.52.0",
+  "version": "0.53.0",
   "keywords": [
     "mongoose",
     "messaging",
@@ -30,8 +30,8 @@
     "node": ">=22"
   },
   "dependencies": {
-    "@web-ts-toolkit/express-json-router": "0.52.0",
-    "@web-ts-toolkit/utils": "0.52.0",
+    "@web-ts-toolkit/express-json-router": "0.53.0",
+    "@web-ts-toolkit/utils": "0.53.0",
     "handlebars": "^4.7.8"
   },
   "peerDependencies": {