@web-ts-toolkit/message-service 0.40.1 → 0.41.0

package/index.d.mts

@@ -25,6 +25,13 @@ interface PrepareResult {
 interface ActionContext {
     message: IMessage | IMessageArchive;
     user: MessageUser;
+    /**
+     * Stable, persisted idempotency key for this action attempt. Handlers that
+     * call external systems must pass this key to those systems or otherwise
+     * deduplicate by it; the service cannot make arbitrary external side effects
+     * exactly-once.
+     */
+    actionAttemptId?: string;
     getModel: (name: string) => mongoose.Model<unknown>;
     expireSession?: (sessionId: string) => Promise<void>;
     refundPayment?: (sessionId: string) => Promise<void>;
@@ -111,10 +118,19 @@ interface InterpolationResult {
  */
 type Usertype = 'sender' | 'receiver';
 
+declare class TemplateRegistryValidationError extends Error {
+    static [Symbol.hasInstance](value: unknown): boolean;
+    constructor(message: string);
+}
 /**
- * In-memory registry for message templates.
+ * In-memory registry for trusted message-template code.
  * Templates are looked up by their `templateCd`.
  *
+ * The registry validates action metadata and stores a frozen shallow snapshot of
+ * authorization/action-critical structure. Function fields keep their original
+ * identity, but mutating the object passed to `register()` later cannot change
+ * registered action authorization or handlers accidentally.
+ *
  * Recommended: create one `TemplateRegistry` per app and pass it to
  * `MessageService({ registry })`. Use the `defaultRegistry` only for
  * simple cases or quick experiments.
@@ -154,9 +170,6 @@ declare class TemplateRegistry {
      */
     clear(): void;
 }
-/**
- * Default global registry instance.
- */
 declare const defaultRegistry: TemplateRegistry;
 /**
  * Check if a given actionCd exists in a registered template.
@@ -177,6 +190,8 @@ interface IMessageContent {
  */
 type MessageType = 'notification' | 'request' | 'reminder' | 'approval' | (string & {});
 type UserId = mongoose.Types.ObjectId | string;
+type ActionLifecycleState = 'active' | 'processing' | 'retryable';
+type ActionNotificationState = 'none' | 'pending' | 'sent' | 'failed';
 /**
  * Minimal user shape accepted by MessageService methods.
  * `displayName` is optional but templates that interpolate `{{displayName}}`
@@ -188,9 +203,11 @@ interface MessageUser {
     roles?: string[];
     displayName?: string;
 }
-interface IMessageMethods {
+interface IMessageRelationshipMethods {
     isSender(user: MessageUser): boolean;
     isReceiver(user: MessageUser): boolean;
+}
+interface IMessageMethods extends IMessageRelationshipMethods {
     archive(actionCd: string, archivedBy: UserId, registry: TemplateRegistry): Promise<void>;
 }
 /**
@@ -215,7 +232,15 @@ interface IBaseMessage {
     payload: Record<string, unknown>;
     display: Record<string, unknown>;
     clientRequestId: string | null;
+    clientRequestOwnerId: string | null;
     clientRequestItemIndex: number | null;
+    actionState: ActionLifecycleState;
+    actionCd: string | null;
+    actionAttemptId: string | null;
+    actionClaimedBy: string | null;
+    actionClaimedAt: Date | null;
+    actionLeaseExpiresAt: Date | null;
+    actionFailureMessage: string | null;
     createdAt: Date;
     updatedAt: Date;
 }
@@ -223,12 +248,16 @@ type MongooseQueryHelpers = Record<string, unknown>;
 type IMessage = mongoose.Document<unknown, MongooseQueryHelpers, IMessageMethods> & IBaseMessage & IMessageMethods & {
     __v?: number;
 };
-type IMessageArchive = mongoose.Document<unknown, MongooseQueryHelpers, IMessageMethods> & IBaseMessage & {
+type IMessageArchive = mongoose.Document<unknown, MongooseQueryHelpers, IMessageRelationshipMethods> & IBaseMessage & {
     actionCd: string;
     archivedBy: UserId;
     archivedAt: Date;
+    actionAttemptId: string | null;
+    actionNotificationState: ActionNotificationState;
+    actionNotificationError: string | null;
+    actionNotificationAttemptedAt: Date | null;
     __v?: number;
-} & IMessageMethods;
+} & IMessageRelationshipMethods;
 
 /** Model name constants — use these when calling mongoose.model() or getModel() */
 declare const MESSAGE_MODEL_NAME = "Message";
@@ -279,19 +308,34 @@ declare const MessageContentSchema: mongoose.Schema<any, mongoose.Model<any, any
 declare const BaseMessageFields: Record<string, mongoose.SchemaTypeOptions<unknown>>;
 
 type EmailNotifier = (email: string, title: string, message: string) => Promise<void> | void;
+type EmailDeliveryFailureStage = 'recipientLookup' | 'notifier';
+interface EmailDeliveryFailureEvent {
+    stage: EmailDeliveryFailureStage;
+    error: unknown;
+    messageId: unknown;
+    recipientId: UserId;
+    title: string;
+}
 interface MessageSchemaConfig {
     /**
-     * Called on every message save (unless excluded) to send an email
-     * notification to the recipient. Pass `null` (the default) to disable.
+     * Called for newly created, non-transactional messages (unless excluded) to
+     * send a best-effort email notification to the recipient. Pass `null` (the
+     * default) to disable.
      *
      * When `null`, no pre-save hook is registered at all.
      */
     emailNotifier?: EmailNotifier | null;
     /**
-     * Message titles (lowercased, after trim) that should NOT trigger email
-     * notifications. Comparison is case-insensitive and matches the *compiled*
-     * title — i.e. the interpolated result. Use this to suppress emails for
-     * low-priority messages.
+     * Called when recipient lookup or notifier delivery fails. The message save
+     * has already succeeded and is not rolled back. If this hook throws, that
+     * secondary failure is swallowed to preserve the best-effort delivery
+     * contract.
+     */
+    onEmailDeliveryFailure?: (event: EmailDeliveryFailureEvent) => void | Promise<void>;
+    /**
+     * Message titles that should NOT trigger email notifications. Exclusions and
+     * rendered titles are compared with the same trim + lowercase normalization
+     * against the compiled title — i.e. the interpolated result.
      */
     emailNotificationExclusions?: string[];
     /**
@@ -303,12 +347,19 @@ interface MessageSchemaConfig {
      * `buildMessageSchema` does a sanity check to give a clear error if not.
      */
     userModelName?: string;
+    /**
+     * Connection used for eager model-registration checks when configuring
+     * connection-local schemas. Runtime document methods and hooks still use the
+     * hydrated document's own connection.
+     */
+    connection?: mongoose.Connection;
     /**
      * Name of the Mongoose model used for archived messages.
      * Defaults to `'MessageArchive'`. Used by the `archive()` instance method.
      */
     archiveModelName?: string;
 }
+type MessageModel = mongoose.Model<IBaseMessage, object, IMessageMethods>;
 /**
  * Build a fresh Message schema with the given configuration.
  * Prefer this over the default `MessageSchema` export when you need
@@ -318,28 +369,904 @@ interface MessageSchemaConfig {
  * be registered with Mongoose before calling this function. The schema
  * factory checks this eagerly to fail fast.
  */
-declare function buildMessageSchema(config?: MessageSchemaConfig): mongoose.Schema;
+declare function buildMessageSchema(config?: MessageSchemaConfig): mongoose.Schema<IBaseMessage, MessageModel, IMessageMethods>;
 /**
  * Default Message schema with no email notifier and no pre-save hook.
  * Provided for backwards compatibility and simple use cases.
  * Use `buildMessageSchema(config)` when you need custom behavior.
  */
-declare const MessageSchema: mongoose.Schema;
+declare const MessageSchema: mongoose.Schema<IBaseMessage, MessageModel, IMessageMethods, {}, {}, {}, mongoose.DefaultSchemaOptions, IBaseMessage, mongoose.Document<unknown, {}, IBaseMessage, {
+    id: string;
+}, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
+    _id: mongoose.Types.ObjectId;
+} & {
+    __v: number;
+}, "id" | keyof IMessageMethods> & mongoose.HydratedDocumentOverrides<{
+    id: string;
+} & IMessageMethods>, {
+    templateCd?: mongoose.SchemaDefinitionProperty<string, IBaseMessage, mongoose.Document<unknown, {}, IBaseMessage, {
+        id: string;
+    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
+        _id: mongoose.Types.ObjectId;
+    } & {
+        __v: number;
+    }, "id" | keyof IMessageMethods> & mongoose.HydratedDocumentOverrides<{
+        id: string;
+    } & IMessageMethods>> | undefined;
+    type?: mongoose.SchemaDefinitionProperty<MessageType, IBaseMessage, mongoose.Document<unknown, {}, IBaseMessage, {
+        id: string;
+    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
+        _id: mongoose.Types.ObjectId;
+    } & {
+        __v: number;
+    }, "id" | keyof IMessageMethods> & mongoose.HydratedDocumentOverrides<{
+        id: string;
+    } & IMessageMethods>> | undefined;
+    fromUser?: mongoose.SchemaDefinitionProperty<UserId | null, IBaseMessage, mongoose.Document<unknown, {}, IBaseMessage, {
+        id: string;
+    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
+        _id: mongoose.Types.ObjectId;
+    } & {
+        __v: number;
+    }, "id" | keyof IMessageMethods> & mongoose.HydratedDocumentOverrides<{
+        id: string;
+    } & IMessageMethods>> | undefined;
+    toUser?: mongoose.SchemaDefinitionProperty<UserId | null, IBaseMessage, mongoose.Document<unknown, {}, IBaseMessage, {
+        id: string;
+    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
+        _id: mongoose.Types.ObjectId;
+    } & {
+        __v: number;
+    }, "id" | keyof IMessageMethods> & mongoose.HydratedDocumentOverrides<{
+        id: string;
+    } & IMessageMethods>> | undefined;
+    toRoles?: mongoose.SchemaDefinitionProperty<string[], IBaseMessage, mongoose.Document<unknown, {}, IBaseMessage, {
+        id: string;
+    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
+        _id: mongoose.Types.ObjectId;
+    } & {
+        __v: number;
+    }, "id" | keyof IMessageMethods> & mongoose.HydratedDocumentOverrides<{
+        id: string;
+    } & IMessageMethods>> | undefined;
+    senderContent?: mongoose.SchemaDefinitionProperty<IMessageContent, IBaseMessage, mongoose.Document<unknown, {}, IBaseMessage, {
+        id: string;
+    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
+        _id: mongoose.Types.ObjectId;
+    } & {
+        __v: number;
+    }, "id" | keyof IMessageMethods> & mongoose.HydratedDocumentOverrides<{
+        id: string;
+    } & IMessageMethods>> | undefined;
+    receiverContent?: mongoose.SchemaDefinitionProperty<IMessageContent, IBaseMessage, mongoose.Document<unknown, {}, IBaseMessage, {
+        id: string;
+    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
+        _id: mongoose.Types.ObjectId;
+    } & {
+        __v: number;
+    }, "id" | keyof IMessageMethods> & mongoose.HydratedDocumentOverrides<{
+        id: string;
+    } & IMessageMethods>> | undefined;
+    documents?: mongoose.SchemaDefinitionProperty<mongoose.Types.ObjectId[], IBaseMessage, mongoose.Document<unknown, {}, IBaseMessage, {
+        id: string;
+    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
+        _id: mongoose.Types.ObjectId;
+    } & {
+        __v: number;
+    }, "id" | keyof IMessageMethods> & mongoose.HydratedDocumentOverrides<{
+        id: string;
+    } & IMessageMethods>> | undefined;
+    paymentSession?: mongoose.SchemaDefinitionProperty<string | null, IBaseMessage, mongoose.Document<unknown, {}, IBaseMessage, {
+        id: string;
+    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
+        _id: mongoose.Types.ObjectId;
+    } & {
+        __v: number;
+    }, "id" | keyof IMessageMethods> & mongoose.HydratedDocumentOverrides<{
+        id: string;
+    } & IMessageMethods>> | undefined;
+    paymentCd?: mongoose.SchemaDefinitionProperty<string, IBaseMessage, mongoose.Document<unknown, {}, IBaseMessage, {
+        id: string;
+    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
+        _id: mongoose.Types.ObjectId;
+    } & {
+        __v: number;
+    }, "id" | keyof IMessageMethods> & mongoose.HydratedDocumentOverrides<{
+        id: string;
+    } & IMessageMethods>> | undefined;
+    payload?: mongoose.SchemaDefinitionProperty<Record<string, unknown>, IBaseMessage, mongoose.Document<unknown, {}, IBaseMessage, {
+        id: string;
+    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
+        _id: mongoose.Types.ObjectId;
+    } & {
+        __v: number;
+    }, "id" | keyof IMessageMethods> & mongoose.HydratedDocumentOverrides<{
+        id: string;
+    } & IMessageMethods>> | undefined;
+    display?: mongoose.SchemaDefinitionProperty<Record<string, unknown>, IBaseMessage, mongoose.Document<unknown, {}, IBaseMessage, {
+        id: string;
+    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
+        _id: mongoose.Types.ObjectId;
+    } & {
+        __v: number;
+    }, "id" | keyof IMessageMethods> & mongoose.HydratedDocumentOverrides<{
+        id: string;
+    } & IMessageMethods>> | undefined;
+    clientRequestId?: mongoose.SchemaDefinitionProperty<string | null, IBaseMessage, mongoose.Document<unknown, {}, IBaseMessage, {
+        id: string;
+    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
+        _id: mongoose.Types.ObjectId;
+    } & {
+        __v: number;
+    }, "id" | keyof IMessageMethods> & mongoose.HydratedDocumentOverrides<{
+        id: string;
+    } & IMessageMethods>> | undefined;
+    clientRequestOwnerId?: mongoose.SchemaDefinitionProperty<string | null, IBaseMessage, mongoose.Document<unknown, {}, IBaseMessage, {
+        id: string;
+    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
+        _id: mongoose.Types.ObjectId;
+    } & {
+        __v: number;
+    }, "id" | keyof IMessageMethods> & mongoose.HydratedDocumentOverrides<{
+        id: string;
+    } & IMessageMethods>> | undefined;
+    clientRequestItemIndex?: mongoose.SchemaDefinitionProperty<number | null, IBaseMessage, mongoose.Document<unknown, {}, IBaseMessage, {
+        id: string;
+    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
+        _id: mongoose.Types.ObjectId;
+    } & {
+        __v: number;
+    }, "id" | keyof IMessageMethods> & mongoose.HydratedDocumentOverrides<{
+        id: string;
+    } & IMessageMethods>> | undefined;
+    actionState?: mongoose.SchemaDefinitionProperty<ActionLifecycleState, IBaseMessage, mongoose.Document<unknown, {}, IBaseMessage, {
+        id: string;
+    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
+        _id: mongoose.Types.ObjectId;
+    } & {
+        __v: number;
+    }, "id" | keyof IMessageMethods> & mongoose.HydratedDocumentOverrides<{
+        id: string;
+    } & IMessageMethods>> | undefined;
+    actionCd?: mongoose.SchemaDefinitionProperty<string | null, IBaseMessage, mongoose.Document<unknown, {}, IBaseMessage, {
+        id: string;
+    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
+        _id: mongoose.Types.ObjectId;
+    } & {
+        __v: number;
+    }, "id" | keyof IMessageMethods> & mongoose.HydratedDocumentOverrides<{
+        id: string;
+    } & IMessageMethods>> | undefined;
+    actionAttemptId?: mongoose.SchemaDefinitionProperty<string | null, IBaseMessage, mongoose.Document<unknown, {}, IBaseMessage, {
+        id: string;
+    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
+        _id: mongoose.Types.ObjectId;
+    } & {
+        __v: number;
+    }, "id" | keyof IMessageMethods> & mongoose.HydratedDocumentOverrides<{
+        id: string;
+    } & IMessageMethods>> | undefined;
+    actionClaimedBy?: mongoose.SchemaDefinitionProperty<string | null, IBaseMessage, mongoose.Document<unknown, {}, IBaseMessage, {
+        id: string;
+    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
+        _id: mongoose.Types.ObjectId;
+    } & {
+        __v: number;
+    }, "id" | keyof IMessageMethods> & mongoose.HydratedDocumentOverrides<{
+        id: string;
+    } & IMessageMethods>> | undefined;
+    actionClaimedAt?: mongoose.SchemaDefinitionProperty<Date | null, IBaseMessage, mongoose.Document<unknown, {}, IBaseMessage, {
+        id: string;
+    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
+        _id: mongoose.Types.ObjectId;
+    } & {
+        __v: number;
+    }, "id" | keyof IMessageMethods> & mongoose.HydratedDocumentOverrides<{
+        id: string;
+    } & IMessageMethods>> | undefined;
+    actionLeaseExpiresAt?: mongoose.SchemaDefinitionProperty<Date | null, IBaseMessage, mongoose.Document<unknown, {}, IBaseMessage, {
+        id: string;
+    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
+        _id: mongoose.Types.ObjectId;
+    } & {
+        __v: number;
+    }, "id" | keyof IMessageMethods> & mongoose.HydratedDocumentOverrides<{
+        id: string;
+    } & IMessageMethods>> | undefined;
+    actionFailureMessage?: mongoose.SchemaDefinitionProperty<string | null, IBaseMessage, mongoose.Document<unknown, {}, IBaseMessage, {
+        id: string;
+    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
+        _id: mongoose.Types.ObjectId;
+    } & {
+        __v: number;
+    }, "id" | keyof IMessageMethods> & mongoose.HydratedDocumentOverrides<{
+        id: string;
+    } & IMessageMethods>> | undefined;
+    createdAt?: mongoose.SchemaDefinitionProperty<Date, IBaseMessage, mongoose.Document<unknown, {}, IBaseMessage, {
+        id: string;
+    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
+        _id: mongoose.Types.ObjectId;
+    } & {
+        __v: number;
+    }, "id" | keyof IMessageMethods> & mongoose.HydratedDocumentOverrides<{
+        id: string;
+    } & IMessageMethods>> | undefined;
+    updatedAt?: mongoose.SchemaDefinitionProperty<Date, IBaseMessage, mongoose.Document<unknown, {}, IBaseMessage, {
+        id: string;
+    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
+        _id: mongoose.Types.ObjectId;
+    } & {
+        __v: number;
+    }, "id" | keyof IMessageMethods> & mongoose.HydratedDocumentOverrides<{
+        id: string;
+    } & IMessageMethods>> | undefined;
+}, IBaseMessage>;
 
+type MessageArchiveSchemaFields = IBaseMessage & {
+    actionCd: string;
+    archivedBy: unknown;
+    archivedAt: Date;
+    actionAttemptId: string | null;
+    actionNotificationState: 'none' | 'pending' | 'sent' | 'failed';
+    actionNotificationError: string | null;
+    actionNotificationAttemptedAt: Date | null;
+};
+type MessageArchiveModel = mongoose.Model<MessageArchiveSchemaFields, object, IMessageRelationshipMethods>;
 /**
  * Build a fresh MessageArchive schema.
  * Mirrors the default Message schema but adds archive-specific fields
  * (actionCd, archivedBy, archivedAt) and no pre-save email hook.
  */
-declare function buildMessageArchiveSchema(): mongoose.Schema;
+declare function buildMessageArchiveSchema(): mongoose.Schema<MessageArchiveSchemaFields, MessageArchiveModel, IMessageRelationshipMethods>;
 /**
  * Default MessageArchive schema. Provided for backwards compatibility.
  * Use `buildMessageArchiveSchema()` if you need a fresh instance.
  */
-declare const MessageArchiveSchema: mongoose.Schema;
+declare const MessageArchiveSchema: mongoose.Schema<MessageArchiveSchemaFields, MessageArchiveModel, IMessageRelationshipMethods, {}, {}, {}, mongoose.DefaultSchemaOptions, MessageArchiveSchemaFields, mongoose.Document<unknown, {}, MessageArchiveSchemaFields, {
+    id: string;
+}, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
+    actionCd: string;
+    archivedBy: unknown;
+    archivedAt: Date;
+    actionAttemptId: string | null;
+    actionNotificationState: "none" | "pending" | "sent" | "failed";
+    actionNotificationError: string | null;
+    actionNotificationAttemptedAt: Date | null;
+} & {
+    _id: mongoose.Types.ObjectId;
+} & {
+    __v: number;
+}, "id" | keyof IMessageRelationshipMethods> & mongoose.HydratedDocumentOverrides<{
+    id: string;
+} & IMessageRelationshipMethods>, {
+    templateCd?: mongoose.SchemaDefinitionProperty<string, MessageArchiveSchemaFields, mongoose.Document<unknown, {}, MessageArchiveSchemaFields, {
+        id: string;
+    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
+        actionCd: string;
+        archivedBy: unknown;
+        archivedAt: Date;
+        actionAttemptId: string | null;
+        actionNotificationState: "none" | "pending" | "sent" | "failed";
+        actionNotificationError: string | null;
+        actionNotificationAttemptedAt: Date | null;
+    } & {
+        _id: mongoose.Types.ObjectId;
+    } & {
+        __v: number;
+    }, "id" | keyof IMessageRelationshipMethods> & mongoose.HydratedDocumentOverrides<{
+        id: string;
+    } & IMessageRelationshipMethods>> | undefined;
+    type?: mongoose.SchemaDefinitionProperty<MessageType, MessageArchiveSchemaFields, mongoose.Document<unknown, {}, MessageArchiveSchemaFields, {
+        id: string;
+    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
+        actionCd: string;
+        archivedBy: unknown;
+        archivedAt: Date;
+        actionAttemptId: string | null;
+        actionNotificationState: "none" | "pending" | "sent" | "failed";
+        actionNotificationError: string | null;
+        actionNotificationAttemptedAt: Date | null;
+    } & {
+        _id: mongoose.Types.ObjectId;
+    } & {
+        __v: number;
+    }, "id" | keyof IMessageRelationshipMethods> & mongoose.HydratedDocumentOverrides<{
+        id: string;
+    } & IMessageRelationshipMethods>> | undefined;
+    fromUser?: mongoose.SchemaDefinitionProperty<UserId | null, MessageArchiveSchemaFields, mongoose.Document<unknown, {}, MessageArchiveSchemaFields, {
+        id: string;
+    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
+        actionCd: string;
+        archivedBy: unknown;
+        archivedAt: Date;
+        actionAttemptId: string | null;
+        actionNotificationState: "none" | "pending" | "sent" | "failed";
+        actionNotificationError: string | null;
+        actionNotificationAttemptedAt: Date | null;
+    } & {
+        _id: mongoose.Types.ObjectId;
+    } & {
+        __v: number;
+    }, "id" | keyof IMessageRelationshipMethods> & mongoose.HydratedDocumentOverrides<{
+        id: string;
+    } & IMessageRelationshipMethods>> | undefined;
+    toUser?: mongoose.SchemaDefinitionProperty<UserId | null, MessageArchiveSchemaFields, mongoose.Document<unknown, {}, MessageArchiveSchemaFields, {
+        id: string;
+    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
+        actionCd: string;
+        archivedBy: unknown;
+        archivedAt: Date;
+        actionAttemptId: string | null;
+        actionNotificationState: "none" | "pending" | "sent" | "failed";
+        actionNotificationError: string | null;
+        actionNotificationAttemptedAt: Date | null;
+    } & {
+        _id: mongoose.Types.ObjectId;
+    } & {
+        __v: number;
+    }, "id" | keyof IMessageRelationshipMethods> & mongoose.HydratedDocumentOverrides<{
+        id: string;
+    } & IMessageRelationshipMethods>> | undefined;
+    toRoles?: mongoose.SchemaDefinitionProperty<string[], MessageArchiveSchemaFields, mongoose.Document<unknown, {}, MessageArchiveSchemaFields, {
+        id: string;
+    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
+        actionCd: string;
+        archivedBy: unknown;
+        archivedAt: Date;
+        actionAttemptId: string | null;
+        actionNotificationState: "none" | "pending" | "sent" | "failed";
+        actionNotificationError: string | null;
+        actionNotificationAttemptedAt: Date | null;
+    } & {
+        _id: mongoose.Types.ObjectId;
+    } & {
+        __v: number;
+    }, "id" | keyof IMessageRelationshipMethods> & mongoose.HydratedDocumentOverrides<{
+        id: string;
+    } & IMessageRelationshipMethods>> | undefined;
+    senderContent?: mongoose.SchemaDefinitionProperty<IMessageContent, MessageArchiveSchemaFields, mongoose.Document<unknown, {}, MessageArchiveSchemaFields, {
+        id: string;
+    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
+        actionCd: string;
+        archivedBy: unknown;
+        archivedAt: Date;
+        actionAttemptId: string | null;
+        actionNotificationState: "none" | "pending" | "sent" | "failed";
+        actionNotificationError: string | null;
+        actionNotificationAttemptedAt: Date | null;
+    } & {
+        _id: mongoose.Types.ObjectId;
+    } & {
+        __v: number;
+    }, "id" | keyof IMessageRelationshipMethods> & mongoose.HydratedDocumentOverrides<{
+        id: string;
+    } & IMessageRelationshipMethods>> | undefined;
+    receiverContent?: mongoose.SchemaDefinitionProperty<IMessageContent, MessageArchiveSchemaFields, mongoose.Document<unknown, {}, MessageArchiveSchemaFields, {
+        id: string;
+    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
+        actionCd: string;
+        archivedBy: unknown;
+        archivedAt: Date;
+        actionAttemptId: string | null;
+        actionNotificationState: "none" | "pending" | "sent" | "failed";
+        actionNotificationError: string | null;
+        actionNotificationAttemptedAt: Date | null;
+    } & {
+        _id: mongoose.Types.ObjectId;
+    } & {
+        __v: number;
+    }, "id" | keyof IMessageRelationshipMethods> & mongoose.HydratedDocumentOverrides<{
+        id: string;
+    } & IMessageRelationshipMethods>> | undefined;
+    documents?: mongoose.SchemaDefinitionProperty<mongoose.Types.ObjectId[], MessageArchiveSchemaFields, mongoose.Document<unknown, {}, MessageArchiveSchemaFields, {
+        id: string;
+    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
+        actionCd: string;
+        archivedBy: unknown;
+        archivedAt: Date;
+        actionAttemptId: string | null;
+        actionNotificationState: "none" | "pending" | "sent" | "failed";
+        actionNotificationError: string | null;
+        actionNotificationAttemptedAt: Date | null;
+    } & {
+        _id: mongoose.Types.ObjectId;
+    } & {
+        __v: number;
+    }, "id" | keyof IMessageRelationshipMethods> & mongoose.HydratedDocumentOverrides<{
+        id: string;
+    } & IMessageRelationshipMethods>> | undefined;
+    paymentSession?: mongoose.SchemaDefinitionProperty<string | null, MessageArchiveSchemaFields, mongoose.Document<unknown, {}, MessageArchiveSchemaFields, {
+        id: string;
+    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
+        actionCd: string;
+        archivedBy: unknown;
+        archivedAt: Date;
+        actionAttemptId: string | null;
+        actionNotificationState: "none" | "pending" | "sent" | "failed";
+        actionNotificationError: string | null;
+        actionNotificationAttemptedAt: Date | null;
+    } & {
+        _id: mongoose.Types.ObjectId;
+    } & {
+        __v: number;
+    }, "id" | keyof IMessageRelationshipMethods> & mongoose.HydratedDocumentOverrides<{
+        id: string;
+    } & IMessageRelationshipMethods>> | undefined;
+    paymentCd?: mongoose.SchemaDefinitionProperty<string, MessageArchiveSchemaFields, mongoose.Document<unknown, {}, MessageArchiveSchemaFields, {
+        id: string;
+    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
+        actionCd: string;
+        archivedBy: unknown;
+        archivedAt: Date;
+        actionAttemptId: string | null;
+        actionNotificationState: "none" | "pending" | "sent" | "failed";
+        actionNotificationError: string | null;
+        actionNotificationAttemptedAt: Date | null;
+    } & {
+        _id: mongoose.Types.ObjectId;
+    } & {
+        __v: number;
+    }, "id" | keyof IMessageRelationshipMethods> & mongoose.HydratedDocumentOverrides<{
+        id: string;
+    } & IMessageRelationshipMethods>> | undefined;
+    payload?: mongoose.SchemaDefinitionProperty<Record<string, unknown>, MessageArchiveSchemaFields, mongoose.Document<unknown, {}, MessageArchiveSchemaFields, {
+        id: string;
+    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
+        actionCd: string;
+        archivedBy: unknown;
+        archivedAt: Date;
+        actionAttemptId: string | null;
+        actionNotificationState: "none" | "pending" | "sent" | "failed";
+        actionNotificationError: string | null;
+        actionNotificationAttemptedAt: Date | null;
+    } & {
+        _id: mongoose.Types.ObjectId;
+    } & {
+        __v: number;
+    }, "id" | keyof IMessageRelationshipMethods> & mongoose.HydratedDocumentOverrides<{
+        id: string;
+    } & IMessageRelationshipMethods>> | undefined;
+    display?: mongoose.SchemaDefinitionProperty<Record<string, unknown>, MessageArchiveSchemaFields, mongoose.Document<unknown, {}, MessageArchiveSchemaFields, {
+        id: string;
+    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
+        actionCd: string;
+        archivedBy: unknown;
+        archivedAt: Date;
+        actionAttemptId: string | null;
+        actionNotificationState: "none" | "pending" | "sent" | "failed";
+        actionNotificationError: string | null;
+        actionNotificationAttemptedAt: Date | null;
+    } & {
+        _id: mongoose.Types.ObjectId;
+    } & {
+        __v: number;
+    }, "id" | keyof IMessageRelationshipMethods> & mongoose.HydratedDocumentOverrides<{
+        id: string;
+    } & IMessageRelationshipMethods>> | undefined;
+    clientRequestId?: mongoose.SchemaDefinitionProperty<string | null, MessageArchiveSchemaFields, mongoose.Document<unknown, {}, MessageArchiveSchemaFields, {
+        id: string;
+    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
+        actionCd: string;
+        archivedBy: unknown;
+        archivedAt: Date;
+        actionAttemptId: string | null;
+        actionNotificationState: "none" | "pending" | "sent" | "failed";
+        actionNotificationError: string | null;
+        actionNotificationAttemptedAt: Date | null;
+    } & {
+        _id: mongoose.Types.ObjectId;
+    } & {
+        __v: number;
+    }, "id" | keyof IMessageRelationshipMethods> & mongoose.HydratedDocumentOverrides<{
+        id: string;
+    } & IMessageRelationshipMethods>> | undefined;
+    clientRequestOwnerId?: mongoose.SchemaDefinitionProperty<string | null, MessageArchiveSchemaFields, mongoose.Document<unknown, {}, MessageArchiveSchemaFields, {
+        id: string;
+    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
+        actionCd: string;
+        archivedBy: unknown;
+        archivedAt: Date;
+        actionAttemptId: string | null;
+        actionNotificationState: "none" | "pending" | "sent" | "failed";
+        actionNotificationError: string | null;
+        actionNotificationAttemptedAt: Date | null;
+    } & {
+        _id: mongoose.Types.ObjectId;
+    } & {
+        __v: number;
+    }, "id" | keyof IMessageRelationshipMethods> & mongoose.HydratedDocumentOverrides<{
+        id: string;
+    } & IMessageRelationshipMethods>> | undefined;
+    clientRequestItemIndex?: mongoose.SchemaDefinitionProperty<number | null, MessageArchiveSchemaFields, mongoose.Document<unknown, {}, MessageArchiveSchemaFields, {
+        id: string;
+    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
+        actionCd: string;
+        archivedBy: unknown;
+        archivedAt: Date;
+        actionAttemptId: string | null;
+        actionNotificationState: "none" | "pending" | "sent" | "failed";
+        actionNotificationError: string | null;
+        actionNotificationAttemptedAt: Date | null;
+    } & {
+        _id: mongoose.Types.ObjectId;
+    } & {
+        __v: number;
+    }, "id" | keyof IMessageRelationshipMethods> & mongoose.HydratedDocumentOverrides<{
+        id: string;
+    } & IMessageRelationshipMethods>> | undefined;
+    actionState?: mongoose.SchemaDefinitionProperty<ActionLifecycleState, MessageArchiveSchemaFields, mongoose.Document<unknown, {}, MessageArchiveSchemaFields, {
+        id: string;
+    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
+        actionCd: string;
+        archivedBy: unknown;
+        archivedAt: Date;
+        actionAttemptId: string | null;
+        actionNotificationState: "none" | "pending" | "sent" | "failed";
+        actionNotificationError: string | null;
+        actionNotificationAttemptedAt: Date | null;
+    } & {
+        _id: mongoose.Types.ObjectId;
+    } & {
+        __v: number;
+    }, "id" | keyof IMessageRelationshipMethods> & mongoose.HydratedDocumentOverrides<{
+        id: string;
+    } & IMessageRelationshipMethods>> | undefined;
+    actionCd?: mongoose.SchemaDefinitionProperty<string, MessageArchiveSchemaFields, mongoose.Document<unknown, {}, MessageArchiveSchemaFields, {
+        id: string;
+    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
+        actionCd: string;
+        archivedBy: unknown;
+        archivedAt: Date;
+        actionAttemptId: string | null;
+        actionNotificationState: "none" | "pending" | "sent" | "failed";
+        actionNotificationError: string | null;
+        actionNotificationAttemptedAt: Date | null;
+    } & {
+        _id: mongoose.Types.ObjectId;
+    } & {
+        __v: number;
+    }, "id" | keyof IMessageRelationshipMethods> & mongoose.HydratedDocumentOverrides<{
+        id: string;
+    } & IMessageRelationshipMethods>> | undefined;
+    actionAttemptId?: mongoose.SchemaDefinitionProperty<string | null, MessageArchiveSchemaFields, mongoose.Document<unknown, {}, MessageArchiveSchemaFields, {
+        id: string;
+    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
+        actionCd: string;
+        archivedBy: unknown;
+        archivedAt: Date;
+        actionAttemptId: string | null;
+        actionNotificationState: "none" | "pending" | "sent" | "failed";
+        actionNotificationError: string | null;
+        actionNotificationAttemptedAt: Date | null;
+    } & {
+        _id: mongoose.Types.ObjectId;
+    } & {
+        __v: number;
+    }, "id" | keyof IMessageRelationshipMethods> & mongoose.HydratedDocumentOverrides<{
+        id: string;
+    } & IMessageRelationshipMethods>> | undefined;
+    actionClaimedBy?: mongoose.SchemaDefinitionProperty<string | null, MessageArchiveSchemaFields, mongoose.Document<unknown, {}, MessageArchiveSchemaFields, {
+        id: string;
+    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
+        actionCd: string;
+        archivedBy: unknown;
+        archivedAt: Date;
+        actionAttemptId: string | null;
+        actionNotificationState: "none" | "pending" | "sent" | "failed";
+        actionNotificationError: string | null;
+        actionNotificationAttemptedAt: Date | null;
+    } & {
+        _id: mongoose.Types.ObjectId;
+    } & {
+        __v: number;
+    }, "id" | keyof IMessageRelationshipMethods> & mongoose.HydratedDocumentOverrides<{
+        id: string;
+    } & IMessageRelationshipMethods>> | undefined;
+    actionClaimedAt?: mongoose.SchemaDefinitionProperty<Date | null, MessageArchiveSchemaFields, mongoose.Document<unknown, {}, MessageArchiveSchemaFields, {
+        id: string;
+    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
+        actionCd: string;
+        archivedBy: unknown;
+        archivedAt: Date;
+        actionAttemptId: string | null;
+        actionNotificationState: "none" | "pending" | "sent" | "failed";
+        actionNotificationError: string | null;
+        actionNotificationAttemptedAt: Date | null;
+    } & {
+        _id: mongoose.Types.ObjectId;
+    } & {
+        __v: number;
+    }, "id" | keyof IMessageRelationshipMethods> & mongoose.HydratedDocumentOverrides<{
+        id: string;
+    } & IMessageRelationshipMethods>> | undefined;
+    actionLeaseExpiresAt?: mongoose.SchemaDefinitionProperty<Date | null, MessageArchiveSchemaFields, mongoose.Document<unknown, {}, MessageArchiveSchemaFields, {
+        id: string;
+    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
+        actionCd: string;
+        archivedBy: unknown;
+        archivedAt: Date;
+        actionAttemptId: string | null;
+        actionNotificationState: "none" | "pending" | "sent" | "failed";
+        actionNotificationError: string | null;
+        actionNotificationAttemptedAt: Date | null;
+    } & {
+        _id: mongoose.Types.ObjectId;
+    } & {
+        __v: number;
+    }, "id" | keyof IMessageRelationshipMethods> & mongoose.HydratedDocumentOverrides<{
+        id: string;
+    } & IMessageRelationshipMethods>> | undefined;
+    actionFailureMessage?: mongoose.SchemaDefinitionProperty<string | null, MessageArchiveSchemaFields, mongoose.Document<unknown, {}, MessageArchiveSchemaFields, {
+        id: string;
+    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
+        actionCd: string;
+        archivedBy: unknown;
+        archivedAt: Date;
+        actionAttemptId: string | null;
+        actionNotificationState: "none" | "pending" | "sent" | "failed";
+        actionNotificationError: string | null;
+        actionNotificationAttemptedAt: Date | null;
+    } & {
+        _id: mongoose.Types.ObjectId;
+    } & {
+        __v: number;
+    }, "id" | keyof IMessageRelationshipMethods> & mongoose.HydratedDocumentOverrides<{
+        id: string;
+    } & IMessageRelationshipMethods>> | undefined;
+    createdAt?: mongoose.SchemaDefinitionProperty<Date, MessageArchiveSchemaFields, mongoose.Document<unknown, {}, MessageArchiveSchemaFields, {
+        id: string;
+    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
+        actionCd: string;
+        archivedBy: unknown;
+        archivedAt: Date;
+        actionAttemptId: string | null;
+        actionNotificationState: "none" | "pending" | "sent" | "failed";
+        actionNotificationError: string | null;
+        actionNotificationAttemptedAt: Date | null;
+    } & {
+        _id: mongoose.Types.ObjectId;
+    } & {
+        __v: number;
+    }, "id" | keyof IMessageRelationshipMethods> & mongoose.HydratedDocumentOverrides<{
+        id: string;
+    } & IMessageRelationshipMethods>> | undefined;
+    updatedAt?: mongoose.SchemaDefinitionProperty<Date, MessageArchiveSchemaFields, mongoose.Document<unknown, {}, MessageArchiveSchemaFields, {
+        id: string;
+    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
+        actionCd: string;
+        archivedBy: unknown;
+        archivedAt: Date;
+        actionAttemptId: string | null;
+        actionNotificationState: "none" | "pending" | "sent" | "failed";
+        actionNotificationError: string | null;
+        actionNotificationAttemptedAt: Date | null;
+    } & {
+        _id: mongoose.Types.ObjectId;
+    } & {
+        __v: number;
+    }, "id" | keyof IMessageRelationshipMethods> & mongoose.HydratedDocumentOverrides<{
+        id: string;
+    } & IMessageRelationshipMethods>> | undefined;
+    archivedBy?: mongoose.SchemaDefinitionProperty<unknown, MessageArchiveSchemaFields, mongoose.Document<unknown, {}, MessageArchiveSchemaFields, {
+        id: string;
+    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
+        actionCd: string;
+        archivedBy: unknown;
+        archivedAt: Date;
+        actionAttemptId: string | null;
+        actionNotificationState: "none" | "pending" | "sent" | "failed";
+        actionNotificationError: string | null;
+        actionNotificationAttemptedAt: Date | null;
+    } & {
+        _id: mongoose.Types.ObjectId;
+    } & {
+        __v: number;
+    }, "id" | keyof IMessageRelationshipMethods> & mongoose.HydratedDocumentOverrides<{
+        id: string;
+    } & IMessageRelationshipMethods>> | undefined;
+    archivedAt?: mongoose.SchemaDefinitionProperty<Date, MessageArchiveSchemaFields, mongoose.Document<unknown, {}, MessageArchiveSchemaFields, {
+        id: string;
+    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
+        actionCd: string;
+        archivedBy: unknown;
+        archivedAt: Date;
+        actionAttemptId: string | null;
+        actionNotificationState: "none" | "pending" | "sent" | "failed";
+        actionNotificationError: string | null;
+        actionNotificationAttemptedAt: Date | null;
+    } & {
+        _id: mongoose.Types.ObjectId;
+    } & {
+        __v: number;
+    }, "id" | keyof IMessageRelationshipMethods> & mongoose.HydratedDocumentOverrides<{
+        id: string;
+    } & IMessageRelationshipMethods>> | undefined;
+    actionNotificationState?: mongoose.SchemaDefinitionProperty<"none" | "pending" | "sent" | "failed", MessageArchiveSchemaFields, mongoose.Document<unknown, {}, MessageArchiveSchemaFields, {
+        id: string;
+    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
+        actionCd: string;
+        archivedBy: unknown;
+        archivedAt: Date;
+        actionAttemptId: string | null;
+        actionNotificationState: "none" | "pending" | "sent" | "failed";
+        actionNotificationError: string | null;
+        actionNotificationAttemptedAt: Date | null;
+    } & {
+        _id: mongoose.Types.ObjectId;
+    } & {
+        __v: number;
+    }, "id" | keyof IMessageRelationshipMethods> & mongoose.HydratedDocumentOverrides<{
+        id: string;
+    } & IMessageRelationshipMethods>> | undefined;
+    actionNotificationError?: mongoose.SchemaDefinitionProperty<string | null, MessageArchiveSchemaFields, mongoose.Document<unknown, {}, MessageArchiveSchemaFields, {
+        id: string;
+    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
+        actionCd: string;
+        archivedBy: unknown;
+        archivedAt: Date;
+        actionAttemptId: string | null;
+        actionNotificationState: "none" | "pending" | "sent" | "failed";
+        actionNotificationError: string | null;
+        actionNotificationAttemptedAt: Date | null;
+    } & {
+        _id: mongoose.Types.ObjectId;
+    } & {
+        __v: number;
+    }, "id" | keyof IMessageRelationshipMethods> & mongoose.HydratedDocumentOverrides<{
+        id: string;
+    } & IMessageRelationshipMethods>> | undefined;
+    actionNotificationAttemptedAt?: mongoose.SchemaDefinitionProperty<Date | null, MessageArchiveSchemaFields, mongoose.Document<unknown, {}, MessageArchiveSchemaFields, {
+        id: string;
+    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
+        actionCd: string;
+        archivedBy: unknown;
+        archivedAt: Date;
+        actionAttemptId: string | null;
+        actionNotificationState: "none" | "pending" | "sent" | "failed";
+        actionNotificationError: string | null;
+        actionNotificationAttemptedAt: Date | null;
+    } & {
+        _id: mongoose.Types.ObjectId;
+    } & {
+        __v: number;
+    }, "id" | keyof IMessageRelationshipMethods> & mongoose.HydratedDocumentOverrides<{
+        id: string;
+    } & IMessageRelationshipMethods>> | undefined;
+}, MessageArchiveSchemaFields>;
 
-declare function buildMessageRequestSchema(): mongoose.Schema;
-declare const MessageRequestSchema: mongoose.Schema;
+interface MessageRequestSchemaFields {
+    clientRequestId: string;
+    clientRequestOwnerId: string;
+    templateCd: string;
+    state: 'pending' | 'completed' | 'failed';
+    itemCount: number | null;
+    leaseOwnerId: string | null;
+    leaseExpiresAt: Date | null;
+    completedAt: Date | null;
+    failedAt: Date | null;
+    failureMessage: string | null;
+    createdAt: Date;
+    updatedAt: Date;
+}
+declare function buildMessageRequestSchema(): mongoose.Schema<MessageRequestSchemaFields>;
+declare const MessageRequestSchema: mongoose.Schema<MessageRequestSchemaFields, mongoose.Model<MessageRequestSchemaFields, any, any, any, any, any, MessageRequestSchemaFields>, {}, {}, {}, {}, mongoose.DefaultSchemaOptions, MessageRequestSchemaFields, mongoose.Document<unknown, {}, MessageRequestSchemaFields, {
+    id: string;
+}, mongoose.DefaultSchemaOptions> & Omit<MessageRequestSchemaFields & {
+    _id: mongoose.Types.ObjectId;
+} & {
+    __v: number;
+}, "id"> & mongoose.HydratedDocumentOverrides<{
+    id: string;
+}>, {
+    clientRequestId?: mongoose.SchemaDefinitionProperty<string, MessageRequestSchemaFields, mongoose.Document<unknown, {}, MessageRequestSchemaFields, {
+        id: string;
+    }, mongoose.DefaultSchemaOptions> & Omit<MessageRequestSchemaFields & {
+        _id: mongoose.Types.ObjectId;
+    } & {
+        __v: number;
+    }, "id"> & mongoose.HydratedDocumentOverrides<{
+        id: string;
+    }>> | undefined;
+    clientRequestOwnerId?: mongoose.SchemaDefinitionProperty<string, MessageRequestSchemaFields, mongoose.Document<unknown, {}, MessageRequestSchemaFields, {
+        id: string;
+    }, mongoose.DefaultSchemaOptions> & Omit<MessageRequestSchemaFields & {
+        _id: mongoose.Types.ObjectId;
+    } & {
+        __v: number;
+    }, "id"> & mongoose.HydratedDocumentOverrides<{
+        id: string;
+    }>> | undefined;
+    templateCd?: mongoose.SchemaDefinitionProperty<string, MessageRequestSchemaFields, mongoose.Document<unknown, {}, MessageRequestSchemaFields, {
+        id: string;
+    }, mongoose.DefaultSchemaOptions> & Omit<MessageRequestSchemaFields & {
+        _id: mongoose.Types.ObjectId;
+    } & {
+        __v: number;
+    }, "id"> & mongoose.HydratedDocumentOverrides<{
+        id: string;
+    }>> | undefined;
+    state?: mongoose.SchemaDefinitionProperty<"pending" | "failed" | "completed", MessageRequestSchemaFields, mongoose.Document<unknown, {}, MessageRequestSchemaFields, {
+        id: string;
+    }, mongoose.DefaultSchemaOptions> & Omit<MessageRequestSchemaFields & {
+        _id: mongoose.Types.ObjectId;
+    } & {
+        __v: number;
+    }, "id"> & mongoose.HydratedDocumentOverrides<{
+        id: string;
+    }>> | undefined;
+    itemCount?: mongoose.SchemaDefinitionProperty<number | null, MessageRequestSchemaFields, mongoose.Document<unknown, {}, MessageRequestSchemaFields, {
+        id: string;
+    }, mongoose.DefaultSchemaOptions> & Omit<MessageRequestSchemaFields & {
+        _id: mongoose.Types.ObjectId;
+    } & {
+        __v: number;
+    }, "id"> & mongoose.HydratedDocumentOverrides<{
+        id: string;
+    }>> | undefined;
+    leaseOwnerId?: mongoose.SchemaDefinitionProperty<string | null, MessageRequestSchemaFields, mongoose.Document<unknown, {}, MessageRequestSchemaFields, {
+        id: string;
+    }, mongoose.DefaultSchemaOptions> & Omit<MessageRequestSchemaFields & {
+        _id: mongoose.Types.ObjectId;
+    } & {
+        __v: number;
+    }, "id"> & mongoose.HydratedDocumentOverrides<{
+        id: string;
+    }>> | undefined;
+    leaseExpiresAt?: mongoose.SchemaDefinitionProperty<Date | null, MessageRequestSchemaFields, mongoose.Document<unknown, {}, MessageRequestSchemaFields, {
+        id: string;
+    }, mongoose.DefaultSchemaOptions> & Omit<MessageRequestSchemaFields & {
+        _id: mongoose.Types.ObjectId;
+    } & {
+        __v: number;
+    }, "id"> & mongoose.HydratedDocumentOverrides<{
+        id: string;
+    }>> | undefined;
+    completedAt?: mongoose.SchemaDefinitionProperty<Date | null, MessageRequestSchemaFields, mongoose.Document<unknown, {}, MessageRequestSchemaFields, {
+        id: string;
+    }, mongoose.DefaultSchemaOptions> & Omit<MessageRequestSchemaFields & {
+        _id: mongoose.Types.ObjectId;
+    } & {
+        __v: number;
+    }, "id"> & mongoose.HydratedDocumentOverrides<{
+        id: string;
+    }>> | undefined;
+    failedAt?: mongoose.SchemaDefinitionProperty<Date | null, MessageRequestSchemaFields, mongoose.Document<unknown, {}, MessageRequestSchemaFields, {
+        id: string;
+    }, mongoose.DefaultSchemaOptions> & Omit<MessageRequestSchemaFields & {
+        _id: mongoose.Types.ObjectId;
+    } & {
+        __v: number;
+    }, "id"> & mongoose.HydratedDocumentOverrides<{
+        id: string;
+    }>> | undefined;
+    failureMessage?: mongoose.SchemaDefinitionProperty<string | null, MessageRequestSchemaFields, mongoose.Document<unknown, {}, MessageRequestSchemaFields, {
+        id: string;
+    }, mongoose.DefaultSchemaOptions> & Omit<MessageRequestSchemaFields & {
+        _id: mongoose.Types.ObjectId;
+    } & {
+        __v: number;
+    }, "id"> & mongoose.HydratedDocumentOverrides<{
+        id: string;
+    }>> | undefined;
+    createdAt?: mongoose.SchemaDefinitionProperty<Date, MessageRequestSchemaFields, mongoose.Document<unknown, {}, MessageRequestSchemaFields, {
+        id: string;
+    }, mongoose.DefaultSchemaOptions> & Omit<MessageRequestSchemaFields & {
+        _id: mongoose.Types.ObjectId;
+    } & {
+        __v: number;
+    }, "id"> & mongoose.HydratedDocumentOverrides<{
+        id: string;
+    }>> | undefined;
+    updatedAt?: mongoose.SchemaDefinitionProperty<Date, MessageRequestSchemaFields, mongoose.Document<unknown, {}, MessageRequestSchemaFields, {
+        id: string;
+    }, mongoose.DefaultSchemaOptions> & Omit<MessageRequestSchemaFields & {
+        _id: mongoose.Types.ObjectId;
+    } & {
+        __v: number;
+    }, "id"> & mongoose.HydratedDocumentOverrides<{
+        id: string;
+    }>> | undefined;
+}, MessageRequestSchemaFields>;
 
 /**
  * Apply the standard set of action filters (usertype match, permission, condition).
@@ -392,6 +1319,14 @@ declare class NoopEmailProvider implements EmailProvider {
  * Host apps implement this to handle payment sessions for messages
  * that require payment (e.g. Stripe, Adyen, Paddle).
  *
+ * Message creation may create external sessions before MongoDB commit. If the
+ * message write or idempotent batch transaction fails, `MessageService` calls
+ * `expireSession()` for every newly created uncommitted session. Providers must
+ * make expiration idempotent because callers may retry cleanup after ambiguous
+ * network or provider failures. If expiration itself fails, message creation
+ * fails with `PaymentSessionCompensationError` and the optional service hook is
+ * invoked for observability.
+ *
  * `priceArgs` is intentionally a free-form `Record<string, unknown>` so
  * providers can accept their own metadata (currency, line items, etc.).
  * Templates should document what they pass.
@@ -404,13 +1339,13 @@ interface PaymentProvider {
      */
     createSession(user: UserId, code: string, priceArgs?: Record<string, unknown>): Promise<string | null>;
     /**
-     * Expire a session that was never completed.
-     * Should be idempotent.
+     * Expire a session that was never committed to a usable message.
+     * Must be idempotent.
      */
     expireSession(sessionId: string): Promise<void>;
     /**
      * Refund a completed payment.
-     * Should be idempotent.
+     * Must be idempotent.
      */
     refundPayment(sessionId: string): Promise<void>;
 }
@@ -426,8 +1361,15 @@ declare class NoopPaymentProvider implements PaymentProvider {
 }
 
 interface MessageServiceOptions {
-    getModel: (name: string) => mongoose.Model<unknown>;
+    getModel?: (name: string) => mongoose.Model<unknown>;
+    connection?: mongoose.Connection;
+    modelNames?: Partial<MessageServiceModelNames>;
     paymentProvider?: PaymentProvider | null;
+    /**
+     * Called when the service cannot expire an external payment session that was
+     * created for a message batch that did not commit.
+     */
+    onPaymentCompensationFailure?: (event: PaymentCompensationFailureEvent) => void | Promise<void>;
     adminRoles?: string[];
     registry?: TemplateRegistry;
     /**
@@ -439,7 +1381,40 @@ interface MessageServiceOptions {
      * Hard upper bound for `listMessages` limit to prevent abuse. Defaults to 100.
      */
     maxListLimit?: number;
+    /**
+     * How long a pending idempotent create reservation lease remains live before
+     * another caller may atomically take it over. Defaults to 30000 ms.
+     */
+    clientRequestLeaseMs?: number;
+    /**
+     * Maximum time a duplicate idempotent create waits for completion or stale
+     * lease takeover before raising `ClientRequestPendingError`. Defaults to 5000 ms.
+     */
+    clientRequestWaitMs?: number;
+    /** Poll interval while waiting for an idempotent create outcome. Defaults to 200 ms. */
+    clientRequestPollMs?: number;
+    /** Test hook for deterministic waiting; production uses `setTimeout`. */
+    clientRequestDelay?: (ms: number) => Promise<void>;
 }
+interface MessageServiceModelNames {
+    active: string;
+    archive: string;
+    request: string;
+    user: string;
+}
+interface PaymentCompensationFailureEvent {
+    operation: 'expire';
+    sessionId: string;
+    error: unknown;
+    originalError: unknown;
+    clientRequestId?: string;
+    clientRequestOwnerId?: string;
+    templateCd?: string;
+}
+type HydratedModelSource = {
+    constructor: unknown;
+};
+type MessageModelRole = keyof MessageServiceModelNames;
 /**
  * The `templateCd` used for generic notifications created via
  * `createNotification`. These messages have no actions, so
@@ -447,20 +1422,88 @@ interface MessageServiceOptions {
  */
 declare const GENERIC_NOTIFICATION_TEMPLATE_CD = "__generic-notification__";
 declare class MessageNotFoundError extends Error {
+    static [Symbol.hasInstance](value: unknown): boolean;
     constructor(messageId: string);
 }
 declare class MessageArchivedError extends Error {
+    static [Symbol.hasInstance](value: unknown): boolean;
     constructor(messageId: string);
 }
 declare class TemplateNotFoundError extends Error {
+    static [Symbol.hasInstance](value: unknown): boolean;
     constructor(templateCd: string);
 }
 declare class ActionNotFoundError extends Error {
+    static [Symbol.hasInstance](value: unknown): boolean;
     constructor(templateCd: string, actionCd: string);
 }
 declare class ActionNotAllowedError extends Error {
+    static [Symbol.hasInstance](value: unknown): boolean;
     constructor();
 }
+declare class InvalidMessageUserError extends Error {
+    static [Symbol.hasInstance](value: unknown): boolean;
+    constructor(message?: string);
+}
+declare class ActionTemplateMismatchError extends Error {
+    static [Symbol.hasInstance](value: unknown): boolean;
+    constructor(expectedTemplateCd: string, receivedTemplateCd: string);
+}
+declare class ActionConflictError extends Error {
+    static [Symbol.hasInstance](value: unknown): boolean;
+    constructor(messageId: string);
+}
+declare class ActionRetryableError extends Error {
+    static [Symbol.hasInstance](value: unknown): boolean;
+    actionAttemptId: string;
+    constructor(messageId: string, actionAttemptId: string, cause?: unknown);
+}
+declare class ActionNotificationPendingError extends Error {
+    static [Symbol.hasInstance](value: unknown): boolean;
+    actionAttemptId: string;
+    result: unknown;
+    constructor(messageId: string, actionAttemptId: string, result: unknown, cause?: unknown);
+}
+declare class InvalidClientRequestIdError extends Error {
+    static [Symbol.hasInstance](value: unknown): boolean;
+    constructor(message: string);
+}
+declare class InvalidPaginationValueError extends Error {
+    static [Symbol.hasInstance](value: unknown): boolean;
+    constructor(message: string);
+}
+declare class ClientRequestPendingError extends Error {
+    static [Symbol.hasInstance](value: unknown): boolean;
+    constructor(clientRequestId: string);
+}
+declare class ClientRequestFailedError extends Error {
+    static [Symbol.hasInstance](value: unknown): boolean;
+    constructor(clientRequestId: string, reason?: string | null);
+}
+declare class ClientRequestInconsistentStateError extends Error {
+    static [Symbol.hasInstance](value: unknown): boolean;
+    constructor(clientRequestId: string, message: string);
+}
+declare class MessageTransactionRequiredError extends Error {
+    static [Symbol.hasInstance](value: unknown): boolean;
+    constructor(cause?: unknown);
+}
+declare class MessageModelResolutionError extends Error {
+    static [Symbol.hasInstance](value: unknown): boolean;
+    role: MessageModelRole;
+    modelName: string;
+    connectionName: string;
+    constructor(role: MessageModelRole, modelName: string, connectionName: string, cause?: unknown);
+}
+declare class PaymentSessionCompensationError extends Error {
+    static [Symbol.hasInstance](value: unknown): boolean;
+    sessionId: string;
+    operation: 'expire';
+    compensationError: unknown;
+    originalError: unknown;
+    hookError?: unknown;
+    constructor(sessionId: string, operation: 'expire', compensationError: unknown, originalError: unknown, hookError?: unknown);
+}
 /**
  * Core message service for creating messages, getting actions, and handling actions.
  *
@@ -468,14 +1511,22 @@ declare class ActionNotAllowedError extends Error {
  * const service = new MessageService({ getModel: mongoose.model.bind(mongoose) });
  */
 declare class MessageService {
-    private getModel;
+    private getModel?;
+    private connection?;
+    private modelNames;
     private paymentProvider;
     private expirePaymentSession?;
     private refundPaymentSession?;
+    private onPaymentCompensationFailure?;
     private adminRoles;
     private registry;
     private defaultListLimit;
     private maxListLimit;
+    private clientRequestLeaseMs;
+    private clientRequestWaitMs;
+    private clientRequestPollMs;
+    private clientRequestDelay;
+    private actionLeaseMs;
     constructor(options: MessageServiceOptions);
     /**
      * Find a message by id, falling back to the archive. Returns null if
@@ -499,11 +1550,11 @@ declare class MessageService {
         payerUser?: MessageUser;
         req?: unknown;
         /**
-         * Optional client-supplied request id. If a message with this
-         * `clientRequestId` already exists, that message is returned instead
-         * of creating a duplicate. Useful for double-submit protection.
+         * Optional client-supplied request id. The service trims surrounding
+         * whitespace, preserves case, and requires a non-empty value up to 128
+         * characters. Replays are scoped to the requester identity and template.
          */
-        clientRequestId?: string;
+        clientRequestId?: unknown;
     }): Promise<IMessage[]>;
     private createMessageWithReservation;
     private createPreparedMessageBatch;
@@ -522,7 +1573,7 @@ declare class MessageService {
             short?: string;
         };
         documents?: mongoose.Types.ObjectId[];
-    }): Promise<IMessage>;
+    }, sourceDocument?: HydratedModelSource | null): Promise<IMessage>;
     /**
      * Build a Mongoose filter for messages visible to the given user.
      * Exposed so callers can use the same visibility rules for custom
@@ -561,16 +1612,38 @@ declare class MessageService {
         permissions?: Record<string, boolean>;
         req?: unknown;
     }): Promise<unknown>;
+    private resolveModel;
+    private getTemplateModelResolver;
+    private getDocumentConnection;
+    private getModelConnection;
+    private describeModelSource;
     private persistItem;
+    private buildMessageDocument;
+    private persistPreparedBatchTransaction;
+    private compensatePaymentSessions;
+    private compensatePaymentSession;
     private buildActionContext;
+    private claimAction;
+    private markActionRetryable;
+    private archiveClaimedMessage;
+    private markActionNotificationState;
     private runSenderNotification;
-    private findByClientRequestId;
-    private waitForClientRequestOutcome;
+    private normalizeClientRequestId;
+    private validatePositiveIntegerOption;
+    private normalizeListLimit;
+    private normalizeListSkip;
+    private buildClientRequestScope;
+    private requireUserId;
+    private findByClientRequestScope;
+    private findCompletedClientRequestReplay;
+    private acquireClientRequestStart;
+    private tryAcquireClientRequestLease;
     private tryCreateClientRequestReservation;
+    private tryTakeOverStaleClientRequestReservation;
     private findClientRequestReservation;
-    private completeClientRequestReservation;
-    private releaseClientRequestReservation;
+    private failClientRequestReservation;
     private isDuplicateKeyError;
+    private isTransactionSupportError;
     private delay;
     private isArchivedMessage;
     private applyPopulate;
@@ -582,6 +1655,8 @@ interface MessageRoutesOptions {
     getModel: (name: string) => mongoose.Model<unknown>;
     /** Payment provider (optional — enables payment session handling) */
     paymentProvider?: PaymentProvider | null;
+    /** Optional hook called when expiring an uncommitted payment session fails. */
+    onPaymentCompensationFailure?: MessageServiceOptions['onPaymentCompensationFailure'];
     /** Admin roles that receive messages when no toUser/toRoles specified */
     adminRoles?: string[];
     /**
@@ -592,7 +1667,11 @@ interface MessageRoutesOptions {
     registry?: TemplateRegistry;
     /** Custom auth middleware applied to all routes */
     authMiddleware?: ((req: Request, res: Response, next: NextFunction) => void)[];
-    /** Extract user from request (default: req._user || req.user) */
+    /**
+     * Extract user from request (default: req._user || req.user). All routes
+     * require this extractor to return a user with a non-empty `_id` before any
+     * service, template, payment, model, or action side effect runs.
+     */
     getUser?: (req: Request) => MessageUser | undefined;
     /** Extract permissions from request (default: req._permissions || {}) */
     getPermissions?: (req: Request) => Record<string, boolean>;
@@ -611,12 +1690,15 @@ interface MessageRoutesOptions {
  * Routes:
  *   POST /new/:templateCd        — create message from template
  *   GET  /:id/actions/:usertype  — get available actions for a message
- *   GET  /:id/action/:actionCd   — execute an action (GET)
  *   POST /:id/action/:actionCd   — execute an action (POST)
+ *
+ * All routes require a resolved user with a non-empty `_id`. Route parameters
+ * are validated before service/model/template lookup, and mutating actions are
+ * intentionally POST-only.
  */
 declare function createMessageRoutes(options: MessageRoutesOptions): {
     router: JsonRouter;
     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, 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 };
+export { type ActionConfirmation, ActionConflictError, type ActionContext, type ActionLifecycleState, ActionNotAllowedError, ActionNotFoundError, ActionNotificationPendingError, type ActionNotificationState, ActionRetryableError, ActionTemplateMismatchError, BaseMessageFields, ClientRequestFailedError, ClientRequestInconsistentStateError, ClientRequestPendingError, type EmailDeliveryFailureEvent, type EmailDeliveryFailureStage, type EmailNotifier, type EmailProvider, GENERIC_NOTIFICATION_TEMPLATE_CD, type IBaseMessage, type IMessage, type IMessageArchive, type IMessageContent, type IMessageMethods, type InterpolatedAction, type InterpolatedContent, type InterpolationResult, InvalidClientRequestIdError, InvalidMessageUserError, InvalidPaginationValueError, MESSAGE_ARCHIVE_MODEL_NAME, MESSAGE_MODEL_NAME, MESSAGE_REQUEST_MODEL_NAME, type MessageAction, MessageArchiveSchema, MessageArchivedError, MessageContentSchema, MessageModelResolutionError, MessageNotFoundError, MessageRequestSchema, type MessageRoutesOptions, MessageSchema, type MessageSchemaConfig, MessageService, type MessageServiceModelNames, type MessageServiceOptions, type MessageTemplate, MessageTransactionRequiredError, type MessageType, type MessageUser, NoopEmailProvider, NoopPaymentProvider, type PaymentCompensationFailureEvent, type PaymentProvider, PaymentSessionCompensationError, type PrepareContext, type PrepareResult, type SenderNotificationContent, TemplateNotFoundError, TemplateRegistry, TemplateRegistryValidationError, type UiTemplate, type UserId, type Usertype, buildMessageArchiveSchema, buildMessageRequestSchema, buildMessageSchema, createMessageRoutes, defaultRegistry, filterActions, includesAction, interpolateTemplate, isActionAllowed };