@web-ts-toolkit/message-service 0.28.0 → 0.29.0

package/README.md

@@ -15,8 +15,8 @@ Peer dependencies:
 
 ## Highlights
 
-- **Message & MessageArchive schemas** — drop-in Mongoose schemas with timestamps, indexes, and archiving
-- **Schema factories** — `buildMessageSchema(config?)` and `buildMessageArchiveSchema()` for per-app configuration
+- **Message persistence schemas** — `Message`, `MessageArchive`, and `MessageRequest` schemas with timestamps, indexes, archiving, and idempotency reservations
+- **Schema factories** — `buildMessageSchema(config?)`, `buildMessageArchiveSchema()`, and `buildMessageRequestSchema()` for per-app configuration
 - **Template engine** — Handlebars interpolation for sender/receiver content
 - **Template registry** — register and lookup templates by `templateCd` (per-instance or global)
 - **Action system** — validate permissions, run handlers, archive messages, send notifications
@@ -29,10 +29,24 @@ Peer dependencies:
 
 ```typescript
 import mongoose from 'mongoose';
-import { createMessageRoutes, defaultRegistry, MessageTemplate } from '@web-ts-toolkit/message-service';
+import {
+  buildMessageArchiveSchema,
+  buildMessageRequestSchema,
+  buildMessageSchema,
+  createMessageRoutes,
+  defaultRegistry,
+  MESSAGE_ARCHIVE_MODEL_NAME,
+  MESSAGE_MODEL_NAME,
+  MESSAGE_REQUEST_MODEL_NAME,
+  MessageTemplate,
+} from '@web-ts-toolkit/message-service';
 
 await mongoose.connect('mongodb://localhost/mydb');
 
+mongoose.model(MESSAGE_MODEL_NAME, buildMessageSchema());
+mongoose.model(MESSAGE_ARCHIVE_MODEL_NAME, buildMessageArchiveSchema());
+mongoose.model(MESSAGE_REQUEST_MODEL_NAME, buildMessageRequestSchema());
+
 const myTemplate: MessageTemplate = {
   /* ... */
 };
@@ -133,14 +147,30 @@ registry.clear();
 ### Schema factories
 
 ```typescript
-import { buildMessageSchema, buildMessageArchiveSchema, MESSAGE_MODEL_NAME } from '@web-ts-toolkit/message-service';
+import {
+  buildMessageSchema,
+  buildMessageArchiveSchema,
+  buildMessageRequestSchema,
+  MESSAGE_MODEL_NAME,
+  MESSAGE_ARCHIVE_MODEL_NAME,
+  MESSAGE_REQUEST_MODEL_NAME,
+} from '@web-ts-toolkit/message-service';
 
 const Message = mongoose.model(MESSAGE_MODEL_NAME, buildMessageSchema());
-const MessageArchive = mongoose.model('MessageArchive', buildMessageArchiveSchema());
+const MessageArchive = mongoose.model(MESSAGE_ARCHIVE_MODEL_NAME, buildMessageArchiveSchema());
+const MessageRequest = mongoose.model(MESSAGE_REQUEST_MODEL_NAME, buildMessageRequestSchema());
 ```
 
 `buildMessageSchema({ emailNotifier, emailNotificationExclusions, userModelName, archiveModelName })` lets you opt in to email notifications with per-template exclusions. When `emailNotifier` is `null` (the default), no pre-save hook is registered.
 
+When you use `clientRequestId`, register all three models. `MessageRequest` stores the reservation record that prevents duplicate side effects during concurrent duplicate requests.
+
+### Idempotent create notes
+
+- `clientRequestId` is safe for concurrent retries only when `MessageRequest` is registered.
+- The winning request reserves the idempotency key before template preparation or payment-session creation runs.
+- Losing requests wait for the winning request to finish, then return the same created messages or the same empty result.
+
 ### Typed errors
 
 ```typescript

package/index.d.mts

@@ -214,6 +214,8 @@ interface IBaseMessage {
     paymentCd: string;
     payload: Record<string, unknown>;
     display: Record<string, unknown>;
+    clientRequestId: string | null;
+    clientRequestItemIndex: number | null;
     createdAt: Date;
     updatedAt: Date;
 }
@@ -231,6 +233,7 @@ type IMessageArchive = mongoose.Document<unknown, MongooseQueryHelpers, IMessage
 /** Model name constants — use these when calling mongoose.model() or getModel() */
 declare const MESSAGE_MODEL_NAME = "Message";
 declare const MESSAGE_ARCHIVE_MODEL_NAME = "MessageArchive";
+declare const MESSAGE_REQUEST_MODEL_NAME = "MessageRequest";
 declare const MessageContentSchema: mongoose.Schema<any, mongoose.Model<any, any, any, any, any, any, any>, {}, {}, {}, {}, {
     _id: false;
 }, {
@@ -335,6 +338,9 @@ declare function buildMessageArchiveSchema(): mongoose.Schema;
  */
 declare const MessageArchiveSchema: mongoose.Schema;
 
+declare function buildMessageRequestSchema(): mongoose.Schema;
+declare const MessageRequestSchema: mongoose.Schema;
+
 /**
  * Apply the standard set of action filters (usertype match, permission, condition).
  * This is the single source of truth used by both the template engine (for UI)
@@ -499,6 +505,8 @@ declare class MessageService {
          */
         clientRequestId?: string;
     }): Promise<IMessage[]>;
+    private createMessageWithReservation;
+    private createPreparedMessageBatch;
     createNotification(params: {
         fromUser?: UserId | null;
         toUser?: UserId | null;
@@ -557,6 +565,13 @@ declare class MessageService {
     private buildActionContext;
     private runSenderNotification;
     private findByClientRequestId;
+    private waitForClientRequestOutcome;
+    private tryCreateClientRequestReservation;
+    private findClientRequestReservation;
+    private completeClientRequestReservation;
+    private releaseClientRequestReservation;
+    private isDuplicateKeyError;
+    private delay;
     private isArchivedMessage;
     private applyPopulate;
     private findByIdWithOptions;
@@ -604,4 +619,4 @@ declare function createMessageRoutes(options: MessageRoutesOptions): {
     service: MessageService;
 };
 
-export { type ActionConfirmation, type ActionContext, ActionNotAllowedError, ActionNotFoundError, BaseMessageFields, type EmailNotifier, type EmailProvider, GENERIC_NOTIFICATION_TEMPLATE_CD, type IBaseMessage, type IMessage, type IMessageArchive, type IMessageContent, type IMessageMethods, type InterpolatedAction, type InterpolatedContent, type InterpolationResult, MESSAGE_ARCHIVE_MODEL_NAME, MESSAGE_MODEL_NAME, type MessageAction, MessageArchiveSchema, MessageArchivedError, MessageContentSchema, MessageNotFoundError, type MessageRoutesOptions, MessageSchema, type MessageSchemaConfig, MessageService, type MessageServiceOptions, type MessageTemplate, type MessageType, type MessageUser, NoopEmailProvider, NoopPaymentProvider, type PaymentProvider, type PrepareContext, type PrepareResult, type SenderNotificationContent, TemplateNotFoundError, TemplateRegistry, type UiTemplate, type Usertype, buildMessageArchiveSchema, buildMessageSchema, createMessageRoutes, defaultRegistry, filterActions, includesAction, interpolateTemplate, isActionAllowed };
+export { type ActionConfirmation, type ActionContext, ActionNotAllowedError, ActionNotFoundError, BaseMessageFields, type EmailNotifier, type EmailProvider, GENERIC_NOTIFICATION_TEMPLATE_CD, type IBaseMessage, type IMessage, type IMessageArchive, type IMessageContent, type IMessageMethods, type InterpolatedAction, type InterpolatedContent, type InterpolationResult, MESSAGE_ARCHIVE_MODEL_NAME, MESSAGE_MODEL_NAME, MESSAGE_REQUEST_MODEL_NAME, type MessageAction, MessageArchiveSchema, MessageArchivedError, MessageContentSchema, MessageNotFoundError, MessageRequestSchema, type MessageRoutesOptions, MessageSchema, type MessageSchemaConfig, MessageService, type MessageServiceOptions, type MessageTemplate, type MessageType, type MessageUser, NoopEmailProvider, NoopPaymentProvider, type PaymentProvider, type PrepareContext, type PrepareResult, type SenderNotificationContent, TemplateNotFoundError, TemplateRegistry, type UiTemplate, type Usertype, buildMessageArchiveSchema, buildMessageRequestSchema, buildMessageSchema, createMessageRoutes, defaultRegistry, filterActions, includesAction, interpolateTemplate, isActionAllowed };

package/index.d.ts

@@ -214,6 +214,8 @@ interface IBaseMessage {
     paymentCd: string;
     payload: Record<string, unknown>;
     display: Record<string, unknown>;
+    clientRequestId: string | null;
+    clientRequestItemIndex: number | null;
     createdAt: Date;
     updatedAt: Date;
 }
@@ -231,6 +233,7 @@ type IMessageArchive = mongoose.Document<unknown, MongooseQueryHelpers, IMessage
 /** Model name constants — use these when calling mongoose.model() or getModel() */
 declare const MESSAGE_MODEL_NAME = "Message";
 declare const MESSAGE_ARCHIVE_MODEL_NAME = "MessageArchive";
+declare const MESSAGE_REQUEST_MODEL_NAME = "MessageRequest";
 declare const MessageContentSchema: mongoose.Schema<any, mongoose.Model<any, any, any, any, any, any, any>, {}, {}, {}, {}, {
     _id: false;
 }, {
@@ -335,6 +338,9 @@ declare function buildMessageArchiveSchema(): mongoose.Schema;
  */
 declare const MessageArchiveSchema: mongoose.Schema;
 
+declare function buildMessageRequestSchema(): mongoose.Schema;
+declare const MessageRequestSchema: mongoose.Schema;
+
 /**
  * Apply the standard set of action filters (usertype match, permission, condition).
  * This is the single source of truth used by both the template engine (for UI)
@@ -499,6 +505,8 @@ declare class MessageService {
          */
         clientRequestId?: string;
     }): Promise<IMessage[]>;
+    private createMessageWithReservation;
+    private createPreparedMessageBatch;
     createNotification(params: {
         fromUser?: UserId | null;
         toUser?: UserId | null;
@@ -557,6 +565,13 @@ declare class MessageService {
     private buildActionContext;
     private runSenderNotification;
     private findByClientRequestId;
+    private waitForClientRequestOutcome;
+    private tryCreateClientRequestReservation;
+    private findClientRequestReservation;
+    private completeClientRequestReservation;
+    private releaseClientRequestReservation;
+    private isDuplicateKeyError;
+    private delay;
     private isArchivedMessage;
     private applyPopulate;
     private findByIdWithOptions;
@@ -604,4 +619,4 @@ declare function createMessageRoutes(options: MessageRoutesOptions): {
     service: MessageService;
 };
 
-export { type ActionConfirmation, type ActionContext, ActionNotAllowedError, ActionNotFoundError, BaseMessageFields, type EmailNotifier, type EmailProvider, GENERIC_NOTIFICATION_TEMPLATE_CD, type IBaseMessage, type IMessage, type IMessageArchive, type IMessageContent, type IMessageMethods, type InterpolatedAction, type InterpolatedContent, type InterpolationResult, MESSAGE_ARCHIVE_MODEL_NAME, MESSAGE_MODEL_NAME, type MessageAction, MessageArchiveSchema, MessageArchivedError, MessageContentSchema, MessageNotFoundError, type MessageRoutesOptions, MessageSchema, type MessageSchemaConfig, MessageService, type MessageServiceOptions, type MessageTemplate, type MessageType, type MessageUser, NoopEmailProvider, NoopPaymentProvider, type PaymentProvider, type PrepareContext, type PrepareResult, type SenderNotificationContent, TemplateNotFoundError, TemplateRegistry, type UiTemplate, type Usertype, buildMessageArchiveSchema, buildMessageSchema, createMessageRoutes, defaultRegistry, filterActions, includesAction, interpolateTemplate, isActionAllowed };
+export { type ActionConfirmation, type ActionContext, ActionNotAllowedError, ActionNotFoundError, BaseMessageFields, type EmailNotifier, type EmailProvider, GENERIC_NOTIFICATION_TEMPLATE_CD, type IBaseMessage, type IMessage, type IMessageArchive, type IMessageContent, type IMessageMethods, type InterpolatedAction, type InterpolatedContent, type InterpolationResult, MESSAGE_ARCHIVE_MODEL_NAME, MESSAGE_MODEL_NAME, MESSAGE_REQUEST_MODEL_NAME, type MessageAction, MessageArchiveSchema, MessageArchivedError, MessageContentSchema, MessageNotFoundError, MessageRequestSchema, type MessageRoutesOptions, MessageSchema, type MessageSchemaConfig, MessageService, type MessageServiceOptions, type MessageTemplate, type MessageType, type MessageUser, NoopEmailProvider, NoopPaymentProvider, type PaymentProvider, type PrepareContext, type PrepareResult, type SenderNotificationContent, TemplateNotFoundError, TemplateRegistry, type UiTemplate, type Usertype, buildMessageArchiveSchema, buildMessageRequestSchema, buildMessageSchema, createMessageRoutes, defaultRegistry, filterActions, includesAction, interpolateTemplate, isActionAllowed };

package/index.js

@@ -36,10 +36,12 @@ __export(index_exports, {
   GENERIC_NOTIFICATION_TEMPLATE_CD: () => GENERIC_NOTIFICATION_TEMPLATE_CD,
   MESSAGE_ARCHIVE_MODEL_NAME: () => MESSAGE_ARCHIVE_MODEL_NAME,
   MESSAGE_MODEL_NAME: () => MESSAGE_MODEL_NAME,
+  MESSAGE_REQUEST_MODEL_NAME: () => MESSAGE_REQUEST_MODEL_NAME,
   MessageArchiveSchema: () => MessageArchiveSchema,
   MessageArchivedError: () => MessageArchivedError,
   MessageContentSchema: () => MessageContentSchema,
   MessageNotFoundError: () => MessageNotFoundError,
+  MessageRequestSchema: () => MessageRequestSchema,
   MessageSchema: () => MessageSchema,
   MessageService: () => MessageService,
   NoopEmailProvider: () => NoopEmailProvider,
@@ -47,6 +49,7 @@ __export(index_exports, {
   TemplateNotFoundError: () => TemplateNotFoundError,
   TemplateRegistry: () => TemplateRegistry,
   buildMessageArchiveSchema: () => buildMessageArchiveSchema,
+  buildMessageRequestSchema: () => buildMessageRequestSchema,
   buildMessageSchema: () => buildMessageSchema,
   createMessageRoutes: () => createMessageRoutes,
   defaultRegistry: () => defaultRegistry,
@@ -61,6 +64,7 @@ module.exports = __toCommonJS(index_exports);
 var import_mongoose = __toESM(require("mongoose"));
 var MESSAGE_MODEL_NAME = "Message";
 var MESSAGE_ARCHIVE_MODEL_NAME = "MessageArchive";
+var MESSAGE_REQUEST_MODEL_NAME = "MessageRequest";
 var MessageContentSchema = new import_mongoose.default.Schema(
   {
     title: { type: String, default: "" },
@@ -85,7 +89,8 @@ var BaseMessageFields = {
   paymentCd: { type: String, default: "" },
   payload: { type: import_mongoose.default.Schema.Types.Mixed, default: {} },
   display: { type: import_mongoose.default.Schema.Types.Mixed, default: {} },
-  clientRequestId: { type: String, default: null }
+  clientRequestId: { type: String, default: null },
+  clientRequestItemIndex: { type: Number, default: null }
 };
 
 // src/schemas/message.ts
@@ -228,6 +233,16 @@ function buildMessageSchema(config) {
   });
   schema.index({ createdAt: 1 });
   schema.index({ clientRequestId: 1 }, { sparse: true });
+  schema.index(
+    { clientRequestId: 1, clientRequestItemIndex: 1 },
+    {
+      unique: true,
+      partialFilterExpression: {
+        clientRequestId: { $type: "string" },
+        clientRequestItemIndex: { $type: "number" }
+      }
+    }
+  );
   schema.methods.isSender = isSender;
   schema.methods.isReceiver = isReceiver;
   schema.methods.archive = createArchiveMethod({ archiveModelName: resolved.archiveModelName });
@@ -266,6 +281,25 @@ function buildMessageArchiveSchema() {
 }
 var MessageArchiveSchema = buildMessageArchiveSchema();
 
+// src/schemas/message-request.ts
+var import_mongoose4 = __toESM(require("mongoose"));
+function buildMessageRequestSchema() {
+  const schema = new import_mongoose4.default.Schema(
+    {
+      clientRequestId: { type: String, required: true },
+      state: { type: String, enum: ["pending", "completed"], default: "pending" },
+      itemCount: { type: Number, default: null }
+    },
+    {
+      timestamps: true
+    }
+  );
+  schema.index({ clientRequestId: 1 }, { unique: true });
+  schema.index({ updatedAt: 1 });
+  return schema;
+}
+var MessageRequestSchema = buildMessageRequestSchema();
+
 // src/template-engine.ts
 var import_handlebars = __toESM(require("handlebars"));
 var compiledTemplates = /* @__PURE__ */ new Map();
@@ -354,6 +388,9 @@ var NoopPaymentProvider = class {
 var import_utils = require("@web-ts-toolkit/utils");
 var DEFAULT_LIST_LIMIT = 50;
 var MAX_LIST_LIMIT = 100;
+var DUPLICATE_KEY_ERROR_CODE = 11e3;
+var CLIENT_REQUEST_BATCH_RETRY_COUNT = 20;
+var CLIENT_REQUEST_BATCH_RETRY_DELAY_MS = 10;
 var GENERIC_NOTIFICATION_TEMPLATE_CD = "__generic-notification__";
 var MessageNotFoundError = class extends Error {
   constructor(messageId) {
@@ -437,9 +474,55 @@ var MessageService = class {
       clientRequestId
     } = params;
     if (clientRequestId) {
-      const existing = await this.findByClientRequestId(clientRequestId);
-      if (existing) return existing;
+      return this.createMessageWithReservation({
+        templateCd,
+        user,
+        roles,
+        identity,
+        permissions,
+        payload,
+        payerUser,
+        req,
+        clientRequestId
+      });
+    }
+    return this.createPreparedMessageBatch({
+      templateCd,
+      user,
+      roles,
+      identity,
+      permissions,
+      payload,
+      payerUser,
+      req
+    });
+  }
+  async createMessageWithReservation(params) {
+    while (true) {
+      const existing = await this.findByClientRequestId(params.clientRequestId);
+      if (existing) {
+        return existing;
+      }
+      const acquired = await this.tryCreateClientRequestReservation(params.clientRequestId);
+      if (acquired) {
+        break;
+      }
+      const waited = await this.waitForClientRequestOutcome(params.clientRequestId);
+      if (waited !== null) {
+        return waited;
+      }
     }
+    try {
+      const results = await this.createPreparedMessageBatch(params);
+      await this.completeClientRequestReservation(params.clientRequestId, results.length);
+      return results;
+    } catch (error) {
+      await this.releaseClientRequestReservation(params.clientRequestId);
+      throw error;
+    }
+  }
+  async createPreparedMessageBatch(params) {
+    const { templateCd, user, roles, identity, permissions, payload, payerUser, req, clientRequestId } = params;
     const template = this.registry.find(templateCd);
     if (!template) throw new TemplateNotFoundError(templateCd);
     const messageData = await template.prepareMessage({
@@ -455,8 +538,9 @@ var MessageService = class {
     const ctx = { user, roles, identity, permissions, payload, payerUser, req };
     const items = Array.isArray(messageData) ? messageData : [messageData];
     const results = [];
-    for (const m of items) {
-      results.push(await this.persistItem(template, m, ctx, clientRequestId));
+    for (let index = 0; index < items.length; index++) {
+      const item = items[index];
+      results.push(await this.persistItem(template, item, ctx, clientRequestId, clientRequestId ? index : null));
     }
     return results;
   }
@@ -564,7 +648,7 @@ var MessageService = class {
   // -------------------------------------------------------------------------
   // Private helpers
   // -------------------------------------------------------------------------
-  async persistItem(template, m, ctx, clientRequestId) {
+  async persistItem(template, m, ctx, clientRequestId, clientRequestItemIndex) {
     const toUser = m.toUser ?? null;
     const toRoles = (m.toRoles && m.toRoles.length > 0 ? m.toRoles : this.adminRoles).slice();
     const type = m.type || template.type || "notification";
@@ -593,7 +677,8 @@ var MessageService = class {
       paymentCd,
       payload: m.payload || ctx.payload,
       display: m.display,
-      clientRequestId: clientRequestId ?? null
+      clientRequestId: clientRequestId ?? null,
+      clientRequestItemIndex
     });
   }
   buildActionContext(data) {
@@ -634,6 +719,61 @@ var MessageService = class {
     const docs = await Message.find({ clientRequestId }).sort({ createdAt: 1, _id: 1 }).limit(Number.MAX_SAFE_INTEGER);
     return docs.length > 0 ? docs : null;
   }
+  async waitForClientRequestOutcome(clientRequestId) {
+    for (let attempt = 0; attempt < CLIENT_REQUEST_BATCH_RETRY_COUNT; attempt++) {
+      const docs2 = await this.findByClientRequestId(clientRequestId);
+      if (docs2) {
+        return docs2;
+      }
+      const reservation2 = await this.findClientRequestReservation(clientRequestId);
+      if (!reservation2) {
+        return null;
+      }
+      if (reservation2.state === "completed") {
+        return [];
+      }
+      await this.delay(CLIENT_REQUEST_BATCH_RETRY_DELAY_MS);
+    }
+    const docs = await this.findByClientRequestId(clientRequestId);
+    if (docs) {
+      return docs;
+    }
+    const reservation = await this.findClientRequestReservation(clientRequestId);
+    if (reservation?.state === "completed") {
+      return [];
+    }
+    return null;
+  }
+  async tryCreateClientRequestReservation(clientRequestId) {
+    const MessageRequest = this.getModel(MESSAGE_REQUEST_MODEL_NAME);
+    try {
+      await MessageRequest.create({ clientRequestId, state: "pending", itemCount: null });
+      return true;
+    } catch (error) {
+      if (this.isDuplicateKeyError(error)) {
+        return false;
+      }
+      throw error;
+    }
+  }
+  async findClientRequestReservation(clientRequestId) {
+    const MessageRequest = this.getModel(MESSAGE_REQUEST_MODEL_NAME);
+    return await MessageRequest.findOne({ clientRequestId });
+  }
+  async completeClientRequestReservation(clientRequestId, itemCount) {
+    const MessageRequest = this.getModel(MESSAGE_REQUEST_MODEL_NAME);
+    await MessageRequest.updateOne({ clientRequestId }, { state: "completed", itemCount });
+  }
+  async releaseClientRequestReservation(clientRequestId) {
+    const MessageRequest = this.getModel(MESSAGE_REQUEST_MODEL_NAME);
+    await MessageRequest.deleteOne({ clientRequestId });
+  }
+  isDuplicateKeyError(error) {
+    return error instanceof Error && "code" in error && error.code === DUPLICATE_KEY_ERROR_CODE;
+  }
+  delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
   isArchivedMessage(message) {
     return "archivedAt" in message;
   }
@@ -781,10 +921,12 @@ function defaultGetIdentity(req) {
   GENERIC_NOTIFICATION_TEMPLATE_CD,
   MESSAGE_ARCHIVE_MODEL_NAME,
   MESSAGE_MODEL_NAME,
+  MESSAGE_REQUEST_MODEL_NAME,
   MessageArchiveSchema,
   MessageArchivedError,
   MessageContentSchema,
   MessageNotFoundError,
+  MessageRequestSchema,
   MessageSchema,
   MessageService,
   NoopEmailProvider,
@@ -792,6 +934,7 @@ function defaultGetIdentity(req) {
   TemplateNotFoundError,
   TemplateRegistry,
   buildMessageArchiveSchema,
+  buildMessageRequestSchema,
   buildMessageSchema,
   createMessageRoutes,
   defaultRegistry,

package/index.mjs

@@ -2,6 +2,7 @@
 import mongoose from "mongoose";
 var MESSAGE_MODEL_NAME = "Message";
 var MESSAGE_ARCHIVE_MODEL_NAME = "MessageArchive";
+var MESSAGE_REQUEST_MODEL_NAME = "MessageRequest";
 var MessageContentSchema = new mongoose.Schema(
   {
     title: { type: String, default: "" },
@@ -26,7 +27,8 @@ var BaseMessageFields = {
   paymentCd: { type: String, default: "" },
   payload: { type: mongoose.Schema.Types.Mixed, default: {} },
   display: { type: mongoose.Schema.Types.Mixed, default: {} },
-  clientRequestId: { type: String, default: null }
+  clientRequestId: { type: String, default: null },
+  clientRequestItemIndex: { type: Number, default: null }
 };
 
 // src/schemas/message.ts
@@ -169,6 +171,16 @@ function buildMessageSchema(config) {
   });
   schema.index({ createdAt: 1 });
   schema.index({ clientRequestId: 1 }, { sparse: true });
+  schema.index(
+    { clientRequestId: 1, clientRequestItemIndex: 1 },
+    {
+      unique: true,
+      partialFilterExpression: {
+        clientRequestId: { $type: "string" },
+        clientRequestItemIndex: { $type: "number" }
+      }
+    }
+  );
   schema.methods.isSender = isSender;
   schema.methods.isReceiver = isReceiver;
   schema.methods.archive = createArchiveMethod({ archiveModelName: resolved.archiveModelName });
@@ -207,6 +219,25 @@ function buildMessageArchiveSchema() {
 }
 var MessageArchiveSchema = buildMessageArchiveSchema();
 
+// src/schemas/message-request.ts
+import mongoose4 from "mongoose";
+function buildMessageRequestSchema() {
+  const schema = new mongoose4.Schema(
+    {
+      clientRequestId: { type: String, required: true },
+      state: { type: String, enum: ["pending", "completed"], default: "pending" },
+      itemCount: { type: Number, default: null }
+    },
+    {
+      timestamps: true
+    }
+  );
+  schema.index({ clientRequestId: 1 }, { unique: true });
+  schema.index({ updatedAt: 1 });
+  return schema;
+}
+var MessageRequestSchema = buildMessageRequestSchema();
+
 // src/template-engine.ts
 import Handlebars from "handlebars";
 var compiledTemplates = /* @__PURE__ */ new Map();
@@ -295,6 +326,9 @@ var NoopPaymentProvider = class {
 import { isString } from "@web-ts-toolkit/utils";
 var DEFAULT_LIST_LIMIT = 50;
 var MAX_LIST_LIMIT = 100;
+var DUPLICATE_KEY_ERROR_CODE = 11e3;
+var CLIENT_REQUEST_BATCH_RETRY_COUNT = 20;
+var CLIENT_REQUEST_BATCH_RETRY_DELAY_MS = 10;
 var GENERIC_NOTIFICATION_TEMPLATE_CD = "__generic-notification__";
 var MessageNotFoundError = class extends Error {
   constructor(messageId) {
@@ -378,9 +412,55 @@ var MessageService = class {
       clientRequestId
     } = params;
     if (clientRequestId) {
-      const existing = await this.findByClientRequestId(clientRequestId);
-      if (existing) return existing;
+      return this.createMessageWithReservation({
+        templateCd,
+        user,
+        roles,
+        identity,
+        permissions,
+        payload,
+        payerUser,
+        req,
+        clientRequestId
+      });
+    }
+    return this.createPreparedMessageBatch({
+      templateCd,
+      user,
+      roles,
+      identity,
+      permissions,
+      payload,
+      payerUser,
+      req
+    });
+  }
+  async createMessageWithReservation(params) {
+    while (true) {
+      const existing = await this.findByClientRequestId(params.clientRequestId);
+      if (existing) {
+        return existing;
+      }
+      const acquired = await this.tryCreateClientRequestReservation(params.clientRequestId);
+      if (acquired) {
+        break;
+      }
+      const waited = await this.waitForClientRequestOutcome(params.clientRequestId);
+      if (waited !== null) {
+        return waited;
+      }
     }
+    try {
+      const results = await this.createPreparedMessageBatch(params);
+      await this.completeClientRequestReservation(params.clientRequestId, results.length);
+      return results;
+    } catch (error) {
+      await this.releaseClientRequestReservation(params.clientRequestId);
+      throw error;
+    }
+  }
+  async createPreparedMessageBatch(params) {
+    const { templateCd, user, roles, identity, permissions, payload, payerUser, req, clientRequestId } = params;
     const template = this.registry.find(templateCd);
     if (!template) throw new TemplateNotFoundError(templateCd);
     const messageData = await template.prepareMessage({
@@ -396,8 +476,9 @@ var MessageService = class {
     const ctx = { user, roles, identity, permissions, payload, payerUser, req };
     const items = Array.isArray(messageData) ? messageData : [messageData];
     const results = [];
-    for (const m of items) {
-      results.push(await this.persistItem(template, m, ctx, clientRequestId));
+    for (let index = 0; index < items.length; index++) {
+      const item = items[index];
+      results.push(await this.persistItem(template, item, ctx, clientRequestId, clientRequestId ? index : null));
     }
     return results;
   }
@@ -505,7 +586,7 @@ var MessageService = class {
   // -------------------------------------------------------------------------
   // Private helpers
   // -------------------------------------------------------------------------
-  async persistItem(template, m, ctx, clientRequestId) {
+  async persistItem(template, m, ctx, clientRequestId, clientRequestItemIndex) {
     const toUser = m.toUser ?? null;
     const toRoles = (m.toRoles && m.toRoles.length > 0 ? m.toRoles : this.adminRoles).slice();
     const type = m.type || template.type || "notification";
@@ -534,7 +615,8 @@ var MessageService = class {
       paymentCd,
       payload: m.payload || ctx.payload,
       display: m.display,
-      clientRequestId: clientRequestId ?? null
+      clientRequestId: clientRequestId ?? null,
+      clientRequestItemIndex
     });
   }
   buildActionContext(data) {
@@ -575,6 +657,61 @@ var MessageService = class {
     const docs = await Message.find({ clientRequestId }).sort({ createdAt: 1, _id: 1 }).limit(Number.MAX_SAFE_INTEGER);
     return docs.length > 0 ? docs : null;
   }
+  async waitForClientRequestOutcome(clientRequestId) {
+    for (let attempt = 0; attempt < CLIENT_REQUEST_BATCH_RETRY_COUNT; attempt++) {
+      const docs2 = await this.findByClientRequestId(clientRequestId);
+      if (docs2) {
+        return docs2;
+      }
+      const reservation2 = await this.findClientRequestReservation(clientRequestId);
+      if (!reservation2) {
+        return null;
+      }
+      if (reservation2.state === "completed") {
+        return [];
+      }
+      await this.delay(CLIENT_REQUEST_BATCH_RETRY_DELAY_MS);
+    }
+    const docs = await this.findByClientRequestId(clientRequestId);
+    if (docs) {
+      return docs;
+    }
+    const reservation = await this.findClientRequestReservation(clientRequestId);
+    if (reservation?.state === "completed") {
+      return [];
+    }
+    return null;
+  }
+  async tryCreateClientRequestReservation(clientRequestId) {
+    const MessageRequest = this.getModel(MESSAGE_REQUEST_MODEL_NAME);
+    try {
+      await MessageRequest.create({ clientRequestId, state: "pending", itemCount: null });
+      return true;
+    } catch (error) {
+      if (this.isDuplicateKeyError(error)) {
+        return false;
+      }
+      throw error;
+    }
+  }
+  async findClientRequestReservation(clientRequestId) {
+    const MessageRequest = this.getModel(MESSAGE_REQUEST_MODEL_NAME);
+    return await MessageRequest.findOne({ clientRequestId });
+  }
+  async completeClientRequestReservation(clientRequestId, itemCount) {
+    const MessageRequest = this.getModel(MESSAGE_REQUEST_MODEL_NAME);
+    await MessageRequest.updateOne({ clientRequestId }, { state: "completed", itemCount });
+  }
+  async releaseClientRequestReservation(clientRequestId) {
+    const MessageRequest = this.getModel(MESSAGE_REQUEST_MODEL_NAME);
+    await MessageRequest.deleteOne({ clientRequestId });
+  }
+  isDuplicateKeyError(error) {
+    return error instanceof Error && "code" in error && error.code === DUPLICATE_KEY_ERROR_CODE;
+  }
+  delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
   isArchivedMessage(message) {
     return "archivedAt" in message;
   }
@@ -721,10 +858,12 @@ export {
   GENERIC_NOTIFICATION_TEMPLATE_CD,
   MESSAGE_ARCHIVE_MODEL_NAME,
   MESSAGE_MODEL_NAME,
+  MESSAGE_REQUEST_MODEL_NAME,
   MessageArchiveSchema,
   MessageArchivedError,
   MessageContentSchema,
   MessageNotFoundError,
+  MessageRequestSchema,
   MessageSchema,
   MessageService,
   NoopEmailProvider,
@@ -732,6 +871,7 @@ export {
   TemplateNotFoundError,
   TemplateRegistry,
   buildMessageArchiveSchema,
+  buildMessageRequestSchema,
   buildMessageSchema,
   createMessageRoutes,
   defaultRegistry,

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.28.0",
+  "version": "0.29.0",
   "sideEffects": [
     "./dist/schemas/message.js",
     "./dist/schemas/message-archive.js"
@@ -30,8 +30,8 @@
     "node": ">=20"
   },
   "dependencies": {
-    "@web-ts-toolkit/express-json-router": "0.28.0",
-    "@web-ts-toolkit/utils": "0.28.0",
+    "@web-ts-toolkit/express-json-router": "0.29.0",
+    "@web-ts-toolkit/utils": "0.29.0",
     "handlebars": "^4.7.8"
   },
   "peerDependencies": {