@web-ts-toolkit/message-service 0.6.0

package/index.d.ts

@@ -0,0 +1,607 @@
+import mongoose from 'mongoose';
+import JsonRouter from '@web-ts-toolkit/express-json-router';
+import { Request, Response, NextFunction } from 'express';
+
+interface PrepareContext {
+    user: MessageUser;
+    roles: string[];
+    identity: Record<string, unknown>;
+    permissions: Record<string, boolean>;
+    payload: Record<string, unknown>;
+    getModel: (name: string) => mongoose.Model<unknown>;
+    req?: unknown;
+}
+interface PrepareResult {
+    type?: string;
+    templateData?: Record<string, unknown>;
+    fromUser?: UserId;
+    toUser?: UserId;
+    toRoles?: string[];
+    payload?: Record<string, unknown>;
+    display?: Record<string, unknown>;
+    paymentCd?: string;
+    priceArgs?: Record<string, unknown>;
+}
+interface ActionContext {
+    message: IMessage | IMessageArchive;
+    user: MessageUser;
+    getModel: (name: string) => mongoose.Model<unknown>;
+    expireSession?: (sessionId: string) => Promise<void>;
+    refundPayment?: (sessionId: string) => Promise<void>;
+    req?: unknown;
+}
+interface SenderNotificationContent {
+    title?: string;
+    long: string;
+    short?: string;
+    documents?: mongoose.Types.ObjectId[];
+}
+interface ActionConfirmation {
+    title: string;
+    message: string;
+    notesLabel?: string;
+    requireNotes?: boolean;
+    documents?: boolean;
+}
+interface MessageAction {
+    actionCd: string;
+    name: string;
+    variant: string;
+    isDefault?: boolean;
+    sender: boolean;
+    receiver: boolean;
+    permission?: string;
+    condition?: (message: IMessage) => boolean;
+    confirmation?: ActionConfirmation;
+    payload?: Record<string, unknown>;
+    senderNotification?: string | ((ctx: ActionContext) => Promise<string | SenderNotificationContent>);
+    runHandler: (ctx: ActionContext) => Promise<unknown>;
+}
+type UiTemplate = string | {
+    sender?: string;
+    receiver?: string;
+};
+interface MessageTemplate {
+    templateCd: string;
+    type: string;
+    description: string;
+    senderContent: {
+        title: string;
+        long: string;
+        short: string;
+    };
+    receiverContent: {
+        title: string;
+        long: string;
+        short: string;
+    };
+    uiTemplate: UiTemplate;
+    paymentCd?: string;
+    prepareMessage: (ctx: PrepareContext) => Promise<PrepareResult | PrepareResult[] | null>;
+    actions: MessageAction[];
+}
+interface InterpolatedContent {
+    title: string;
+    long: string;
+    short: string;
+}
+interface InterpolatedAction {
+    actionCd: string;
+    name: string;
+    variant: string;
+    /**
+     * When multiple actions are available, the UI may auto-submit or pre-select
+     * the one with `isDefault: true`. Templates should set this on at most one
+     * action per usertype.
+     */
+    isDefault?: boolean;
+    confirmation?: ActionConfirmation;
+    payload?: Record<string, unknown>;
+}
+interface InterpolationResult {
+    senderContent: InterpolatedContent;
+    receiverContent: InterpolatedContent;
+    uiTemplate: UiTemplate;
+    actions: InterpolatedAction[];
+}
+/**
+ * The role a user plays with respect to a message.
+ * `'sender'` is the user who created the message; `'receiver'` is the
+ * intended recipient (a direct user or a member of one of the `toRoles`).
+ */
+type Usertype = 'sender' | 'receiver';
+
+/**
+ * In-memory registry for message templates.
+ * Templates are looked up by their `templateCd`.
+ *
+ * Recommended: create one `TemplateRegistry` per app and pass it to
+ * `MessageService({ registry })`. Use the `defaultRegistry` only for
+ * simple cases or quick experiments.
+ */
+declare class TemplateRegistry {
+    private templates;
+    /**
+     * Register a template. Overwrites if templateCd already exists.
+     */
+    register(template: MessageTemplate): void;
+    /**
+     * Register multiple templates at once.
+     */
+    registerAll(templates: MessageTemplate[]): void;
+    /**
+     * Find a template by its templateCd.
+     */
+    find(templateCd: string): MessageTemplate | undefined;
+    /**
+     * Check if a template exists.
+     */
+    has(templateCd: string): boolean;
+    /**
+     * Get all registered template codes.
+     */
+    getTemplateCodes(): string[];
+    /**
+     * Get all registered templates.
+     */
+    getAll(): MessageTemplate[];
+    /**
+     * Remove a template by templateCd.
+     */
+    unregister(templateCd: string): boolean;
+    /**
+     * Clear all templates.
+     */
+    clear(): void;
+}
+/**
+ * Default global registry instance.
+ */
+declare const defaultRegistry: TemplateRegistry;
+/**
+ * Check if a given actionCd exists in a registered template.
+ * Used by the Message model's archive() method.
+ */
+declare function includesAction(templateCd: string, actionCd: string, registry: TemplateRegistry): boolean;
+
+interface IMessageContent {
+    title: string;
+    long: string;
+    short: string;
+}
+/**
+ * The high-level category of a message. Common values are 'notification',
+ * 'request', 'reminder', 'approval'. Templates can use any string; the
+ * `(string & {})` trick preserves the literal types in autocomplete while
+ * still allowing arbitrary strings.
+ */
+type MessageType = 'notification' | 'request' | 'reminder' | 'approval' | (string & {});
+type UserId = mongoose.Types.ObjectId | string;
+/**
+ * Minimal user shape accepted by MessageService methods.
+ * `displayName` is optional but templates that interpolate `{{displayName}}`
+ * will fall back to an empty string if it is absent.
+ */
+interface MessageUser {
+    _id: UserId;
+    id?: string;
+    roles?: string[];
+    displayName?: string;
+}
+interface IMessageMethods {
+    isSender(user: MessageUser): boolean;
+    isReceiver(user: MessageUser): boolean;
+    archive(actionCd: string, archivedBy: UserId, registry: TemplateRegistry): Promise<void>;
+}
+/**
+ * Base fields shared between IMessage and IMessageArchive.
+ *
+ * `display` is stored as-is from the template's `PrepareResult.display` —
+ * unlike `senderContent` and `receiverContent`, it is NOT interpolated at
+ * create time. Use it for static per-message configuration (priority,
+ * category, etc.) rather than user-facing text.
+ */
+interface IBaseMessage {
+    templateCd: string;
+    type: MessageType;
+    fromUser: UserId | null;
+    toUser: UserId | null;
+    toRoles: string[];
+    senderContent: IMessageContent;
+    receiverContent: IMessageContent;
+    documents: mongoose.Types.ObjectId[];
+    paymentSession: string | null;
+    paymentCd: string;
+    payload: Record<string, unknown>;
+    display: Record<string, unknown>;
+    createdAt: Date;
+    updatedAt: Date;
+}
+type MongooseQueryHelpers = Record<string, unknown>;
+type IMessage = mongoose.Document<unknown, MongooseQueryHelpers, IMessageMethods> & IBaseMessage & IMessageMethods & {
+    __v?: number;
+};
+type IMessageArchive = mongoose.Document<unknown, MongooseQueryHelpers, IMessageMethods> & IBaseMessage & {
+    actionCd: string;
+    archivedBy: UserId;
+    archivedAt: Date;
+    __v?: number;
+} & IMessageMethods;
+
+/** 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 MessageContentSchema: mongoose.Schema<any, mongoose.Model<any, any, any, any, any, any, any>, {}, {}, {}, {}, {
+    _id: false;
+}, {
+    title: string;
+    long: string;
+    short: string;
+}, mongoose.Document<unknown, {}, {
+    title: string;
+    long: string;
+    short: string;
+}, {
+    id: string;
+}, Omit<mongoose.DefaultSchemaOptions, "_id"> & {
+    _id: false;
+}> & Omit<{
+    title: string;
+    long: string;
+    short: string;
+} & {
+    _id: mongoose.Types.ObjectId;
+} & {
+    __v: number;
+}, "id"> & {
+    id: string;
+}, unknown, {
+    title: string;
+    long: string;
+    short: string;
+} & {
+    _id: mongoose.Types.ObjectId;
+} & {
+    __v: number;
+}>;
+/**
+ * Base message fields shared between Message and MessageArchive.
+ *
+ * All ObjectId fields use generic refs — consumers should configure
+ * their own Mongoose populate paths for their domain models.
+ *
+ * Consumers can extend this object with additional fields (e.g. toOrg, toOrgAdmin)
+ * by spreading it into their own schema definition.
+ */
+declare const BaseMessageFields: Record<string, mongoose.SchemaTypeOptions<unknown>>;
+
+type EmailNotifier = (email: string, title: string, message: string) => Promise<void> | void;
+interface MessageSchemaConfig {
+    /**
+     * Called on every message save (unless excluded) to send an 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.
+     */
+    emailNotificationExclusions?: string[];
+    /**
+     * Name of the Mongoose model that holds the recipient user records.
+     * Defaults to `'User'`. The pre-save hook uses `mongoose.model(name)`
+     * to look up the recipient's email address.
+     *
+     * The model MUST be registered with Mongoose before the first save —
+     * `buildMessageSchema` does a sanity check to give a clear error if not.
+     */
+    userModelName?: string;
+    /**
+     * Name of the Mongoose model used for archived messages.
+     * Defaults to `'MessageArchive'`. Used by the `archive()` instance method.
+     */
+    archiveModelName?: string;
+}
+/**
+ * Build a fresh Message schema with the given configuration.
+ * Prefer this over the default `MessageSchema` export when you need
+ * an email notifier, exclusions, or custom model names.
+ *
+ * Note: when `emailNotifier` is set, the configured `userModelName` MUST
+ * be registered with Mongoose before calling this function. The schema
+ * factory checks this eagerly to fail fast.
+ */
+declare function buildMessageSchema(config?: MessageSchemaConfig): mongoose.Schema;
+/**
+ * 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;
+
+/**
+ * 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;
+/**
+ * Default MessageArchive schema. Provided for backwards compatibility.
+ * Use `buildMessageArchiveSchema()` if you need a fresh instance.
+ */
+declare const MessageArchiveSchema: 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)
+ * and the server-side action handler (for authorization).
+ *
+ * The `name` and confirmation `title`/`message`/`notesLabel` strings are
+ * compiled against the same `data` passed to `interpolateTemplate`.
+ */
+declare function filterActions(actions: MessageAction[], usertype: Usertype, options?: {
+    permissions?: Record<string, boolean>;
+    message?: Record<string, unknown>;
+    data?: Record<string, unknown>;
+}): InterpolatedAction[];
+/**
+ * Check if the given user is allowed to execute the action on the given message.
+ * Returns true if the action is permitted, false otherwise.
+ * Mirrors the `filterActions` logic exactly so the UI and the server agree.
+ */
+declare function isActionAllowed(action: MessageAction, user: MessageUser, message: IMessage | IMessageArchive, options?: {
+    permissions?: Record<string, boolean>;
+}): boolean;
+/**
+ * Interpolate a template's sender/receiver content and filter actions
+ * for the given usertype (sender or receiver).
+ */
+declare function interpolateTemplate(template: MessageTemplate, data: Record<string, unknown>, usertype: Usertype, options?: {
+    permissions?: Record<string, boolean>;
+    message?: Record<string, unknown>;
+}): InterpolationResult;
+
+/**
+ * Email provider interface.
+ * Host app implements this to send email notifications.
+ */
+interface EmailProvider {
+    sendNotification(to: string, title: string, body: string): Promise<void>;
+}
+/**
+ * No-op email provider that silently discards emails.
+ * Useful for testing or when email is not needed.
+ */
+declare class NoopEmailProvider implements EmailProvider {
+    sendNotification(_to: string, _title: string, _body: string): Promise<void>;
+}
+
+/**
+ * Payment provider interface.
+ *
+ * Host apps implement this to handle payment sessions for messages
+ * that require payment (e.g. Stripe, Adyen, Paddle).
+ *
+ * `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.
+ */
+interface PaymentProvider {
+    /**
+     * Create a checkout/session for the given user and pricing code.
+     * Return the session id, or `null` to indicate the session could not
+     * be created (the message creation flow will throw in that case).
+     */
+    createSession(user: UserId, code: string, priceArgs?: Record<string, unknown>): Promise<string | null>;
+    /**
+     * Expire a session that was never completed.
+     * Should be idempotent.
+     */
+    expireSession(sessionId: string): Promise<void>;
+    /**
+     * Refund a completed payment.
+     * Should be idempotent.
+     */
+    refundPayment(sessionId: string): Promise<void>;
+}
+/**
+ * No-op payment provider that returns null for session creation
+ * and does nothing for expire/refund. Useful for apps that don't use payments
+ * or for tests.
+ */
+declare class NoopPaymentProvider implements PaymentProvider {
+    createSession(_user: UserId, _code: string, _priceArgs?: Record<string, unknown>): Promise<string | null>;
+    expireSession(_sessionId: string): Promise<void>;
+    refundPayment(_sessionId: string): Promise<void>;
+}
+
+interface MessageServiceOptions {
+    getModel: (name: string) => mongoose.Model<unknown>;
+    paymentProvider?: PaymentProvider | null;
+    adminRoles?: string[];
+    registry?: TemplateRegistry;
+    /**
+     * Maximum number of messages returned by `listMessages` when no explicit
+     * limit is provided. Defaults to 50.
+     */
+    defaultListLimit?: number;
+    /**
+     * Hard upper bound for `listMessages` limit to prevent abuse. Defaults to 100.
+     */
+    maxListLimit?: number;
+}
+/**
+ * The `templateCd` used for generic notifications created via
+ * `createNotification`. These messages have no actions, so
+ * `getActions` returns an empty list for them.
+ */
+declare const GENERIC_NOTIFICATION_TEMPLATE_CD = "__generic-notification__";
+declare class MessageNotFoundError extends Error {
+    constructor(messageId: string);
+}
+declare class MessageArchivedError extends Error {
+    constructor(messageId: string);
+}
+declare class TemplateNotFoundError extends Error {
+    constructor(templateCd: string);
+}
+declare class ActionNotFoundError extends Error {
+    constructor(templateCd: string, actionCd: string);
+}
+declare class ActionNotAllowedError extends Error {
+    constructor();
+}
+/**
+ * Core message service for creating messages, getting actions, and handling actions.
+ *
+ * @example
+ * const service = new MessageService({ getModel: mongoose.model.bind(mongoose) });
+ */
+declare class MessageService {
+    private getModel;
+    private paymentProvider;
+    private expirePaymentSession?;
+    private refundPaymentSession?;
+    private adminRoles;
+    private registry;
+    private defaultListLimit;
+    private maxListLimit;
+    constructor(options: MessageServiceOptions);
+    /**
+     * Find a message by id, falling back to the archive. Returns null if
+     * the message does not exist in either collection.
+     */
+    findMessage(messageId: string, options?: {
+        populate?: string | string[] | mongoose.PopulateOptions | mongoose.PopulateOptions[];
+        select?: string | Record<string, 0 | 1 | boolean>;
+    }): Promise<IMessage | IMessageArchive | null>;
+    findMessageOrThrow(messageId: string, options?: {
+        populate?: string | string[] | mongoose.PopulateOptions | mongoose.PopulateOptions[];
+        select?: string | Record<string, 0 | 1 | boolean>;
+    }): Promise<IMessage | IMessageArchive>;
+    createMessage(params: {
+        templateCd: string;
+        user: MessageUser;
+        roles?: string[];
+        identity?: Record<string, unknown>;
+        permissions?: Record<string, boolean>;
+        payload?: Record<string, unknown>;
+        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.
+         */
+        clientRequestId?: string;
+    }): Promise<IMessage[]>;
+    createNotification(params: {
+        fromUser?: UserId | null;
+        toUser?: UserId | null;
+        toRoles?: string[];
+        receiverContent: {
+            title: string;
+            long: string;
+            short?: string;
+        };
+        senderContent?: {
+            title: string;
+            long: string;
+            short?: string;
+        };
+        documents?: mongoose.Types.ObjectId[];
+    }): Promise<IMessage>;
+    /**
+     * Build a Mongoose filter for messages visible to the given user.
+     * Exposed so callers can use the same visibility rules for custom
+     * queries (e.g. with `populate`).
+     */
+    buildVisibilityFilter(user: MessageUser): Record<string, unknown>;
+    /**
+     * List active (non-archived) messages visible to a user.
+     * Returns messages where the user is the sender, the receiver,
+     * or matches one of the recipient's roles.
+     */
+    listMessages(params: {
+        user: MessageUser;
+        limit?: number;
+        skip?: number;
+        populate?: string | string[] | mongoose.PopulateOptions | mongoose.PopulateOptions[];
+    }): Promise<IMessage[]>;
+    /**
+     * Count active (non-archived) messages visible to a user.
+     * Useful for badge indicators ("3 new messages").
+     */
+    countMessages(user: MessageUser): Promise<number>;
+    getActions(messageId: string, usertype: Usertype, options?: {
+        permissions?: Record<string, boolean>;
+        message?: IMessage | IMessageArchive;
+        user?: MessageUser;
+        isAdmin?: boolean;
+        populate?: string | string[] | mongoose.PopulateOptions | mongoose.PopulateOptions[];
+    }): Promise<{
+        uiTemplate: UiTemplate;
+        actions: InterpolatedAction[];
+    } | null>;
+    handleAction(templateCd: string, actionCd: string, data: {
+        message: IMessage | IMessageArchive;
+        user: MessageUser;
+        permissions?: Record<string, boolean>;
+        req?: unknown;
+    }): Promise<unknown>;
+    private persistItem;
+    private buildActionContext;
+    private runSenderNotification;
+    private findByClientRequestId;
+    private isArchivedMessage;
+    private applyPopulate;
+    private findByIdWithOptions;
+}
+
+interface MessageRoutesOptions {
+    /** Mongoose model getter */
+    getModel: (name: string) => mongoose.Model<unknown>;
+    /** Payment provider (optional — enables payment session handling) */
+    paymentProvider?: PaymentProvider | null;
+    /** Admin roles that receive messages when no toUser/toRoles specified */
+    adminRoles?: string[];
+    /**
+     * Custom template registry. Use this to isolate templates per app or test
+     * instead of relying on the global `defaultRegistry`. Pass the same registry
+     * instance to `MessageService` if you also construct one directly.
+     */
+    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) */
+    getUser?: (req: Request) => MessageUser | undefined;
+    /** Extract permissions from request (default: req._permissions || {}) */
+    getPermissions?: (req: Request) => Record<string, boolean>;
+    /** Extract identity from request (default: req._identity || {}) */
+    getIdentity?: (req: Request) => Record<string, unknown>;
+    /**
+     * Permission key that, when truthy, makes `getActions` return an empty
+     * action list (read-only view). Defaults to `'is.admin'`.
+     */
+    adminPermissionKey?: string;
+}
+/**
+ * Create a JsonRouter with the message template routes.
+ * Mount via `router.original` and apply your own auth/permission middleware.
+ *
+ * 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)
+ */
+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, 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 };