vintasend 0.7.1 → 0.8.0

package/README.md

@@ -106,6 +106,59 @@ export function sendWelcomeEmail(userId: number) {
 } 
 ```
 
+## Multi-Backend Configuration
+
+VintaSend supports configuring multiple backends for redundancy, data distribution, and migration use cases.
+
+### Basic Setup
+
+```typescript
+import { VintaSendFactory } from 'vintasend';
+
+const vintasend = new VintaSendFactory<NotificationTypeConfig>().create({
+  adapters,
+  backend: primaryBackend,
+  additionalBackends: [replicaBackend],
+  logger,
+  contextGeneratorsMap,
+});
+```
+
+### How It Works
+
+- **Writes**: VintaSend writes to the primary backend first, then replicates to additional backends on a best-effort basis.
+- **Reads**: Read methods use the primary backend by default, but support optional backend targeting by identifier.
+
+```typescript
+// Read from primary backend (default)
+const notification = await vintasend.getNotification(notificationId);
+
+// Read from a specific backend
+const notificationFromReplica = await vintasend.getNotification(
+  notificationId,
+  false,
+  'replica-backend',
+);
+```
+
+### Backend Management Operations
+
+```typescript
+const report = await vintasend.verifyNotificationSync(notificationId);
+
+if (!report.synced) {
+  await vintasend.replicateNotification(notificationId);
+}
+
+const backendStats = await vintasend.getBackendSyncStats();
+```
+
+### Failure Handling
+
+- Primary backend failures fail the operation.
+- Additional backend replication failures are logged and do not fail the primary operation.
+- This keeps primary workflows available while still enabling redundancy.
+
 ## Attachment Support
 
 VintaSend supports file attachments for notifications with an extensible architecture that allows you to choose your preferred storage backend.

package/dist/services/notification-backends/base-notification-backend.d.ts

@@ -87,13 +87,22 @@ export declare const DEFAULT_BACKEND_FILTER_CAPABILITIES: {
     'stringLookups.caseInsensitive': boolean;
 };
 export interface BaseNotificationBackend<Config extends BaseNotificationTypeConfig> {
+    /**
+     * Get a unique identifier for this backend instance.
+     *
+     * Used to distinguish between multiple backend instances in a multi-backend setup.
+     * When not implemented, callers should use a fallback identifier strategy.
+     */
+    getBackendIdentifier?(): string;
     getAllPendingNotifications(): Promise<AnyDatabaseNotification<Config>[]>;
     getPendingNotifications(page: number, pageSize: number): Promise<AnyDatabaseNotification<Config>[]>;
     getAllFutureNotifications(): Promise<AnyDatabaseNotification<Config>[]>;
     getFutureNotifications(page: number, pageSize: number): Promise<AnyDatabaseNotification<Config>[]>;
     getAllFutureNotificationsFromUser(userId: Config['UserIdType']): Promise<DatabaseNotification<Config>[]>;
     getFutureNotificationsFromUser(userId: Config['UserIdType'], page: number, pageSize: number): Promise<DatabaseNotification<Config>[]>;
-    persistNotification(notification: Omit<Notification<Config>, 'id'>): Promise<DatabaseNotification<Config>>;
+    persistNotification(notification: Omit<Notification<Config>, 'id'> & {
+        id?: Config['NotificationIdType'];
+    }): Promise<DatabaseNotification<Config>>;
     getAllNotifications(): Promise<AnyDatabaseNotification<Config>[]>;
     getNotifications(page: number, pageSize: number): Promise<AnyDatabaseNotification<Config>[]>;
     bulkPersistNotifications(notifications: Omit<AnyNotification<Config>, 'id'>[]): Promise<Config['NotificationIdType'][]>;
@@ -107,7 +116,9 @@ export interface BaseNotificationBackend<Config extends BaseNotificationTypeConf
     filterInAppUnreadNotifications(userId: Config['UserIdType'], page: number, pageSize: number): Promise<DatabaseNotification<Config>[]>;
     getUserEmailFromNotification(notificationId: Config['NotificationIdType']): Promise<string | undefined>;
     storeAdapterAndContextUsed(notificationId: Config['NotificationIdType'], adapterKey: string, context: InputJsonValue): Promise<void>;
-    persistOneOffNotification(notification: Omit<OneOffNotificationInput<Config>, 'id'>): Promise<DatabaseOneOffNotification<Config>>;
+    persistOneOffNotification(notification: Omit<OneOffNotificationInput<Config>, 'id'> & {
+        id?: Config['NotificationIdType'];
+    }): Promise<DatabaseOneOffNotification<Config>>;
     persistOneOffNotificationUpdate(notificationId: Config['NotificationIdType'], notification: Partial<Omit<OneOffNotificationInput<Config>, 'id'>>): Promise<DatabaseOneOffNotification<Config>>;
     getOneOffNotification(notificationId: Config['NotificationIdType'], forUpdate: boolean): Promise<DatabaseOneOffNotification<Config> | null>;
     getAllOneOffNotifications(): Promise<DatabaseOneOffNotification<Config>[]>;

package/dist/services/notification-service.d.ts

@@ -22,6 +22,7 @@ type RenderEmailTemplateContextInput<Config extends BaseNotificationTypeConfig>
 type VintaSendFactoryCreateParams<Config extends BaseNotificationTypeConfig, AdaptersList extends BaseNotificationAdapter<BaseNotificationTemplateRenderer<Config>, Config>[], Backend extends BaseNotificationBackend<Config>, Logger extends BaseLogger, QueueService extends BaseNotificationQueueService<Config>, AttachmentMgr extends BaseAttachmentManager> = {
     adapters: AdaptersList;
     backend: Backend;
+    additionalBackends?: Backend[];
     logger: Logger;
     contextGeneratorsMap: BaseNotificationTypeConfig['ContextMap'];
     queueService?: QueueService;
@@ -60,7 +61,7 @@ export declare class VintaSendFactory<Config extends BaseNotificationTypeConfig>
     /**
      * @deprecated Use the object parameter overload instead.
      */
-    create<AdaptersList extends BaseNotificationAdapter<BaseNotificationTemplateRenderer<Config>, Config>[], Backend extends BaseNotificationBackend<Config>, Logger extends BaseLogger, QueueService extends BaseNotificationQueueService<Config>, AttachmentMgr extends BaseAttachmentManager>(adapters: AdaptersList, backend: Backend, logger: Logger, contextGeneratorsMap: BaseNotificationTypeConfig['ContextMap'], queueService?: QueueService, attachmentManager?: AttachmentMgr, options?: VintaSendOptions, gitCommitShaProvider?: BaseGitCommitShaProvider): VintaSend<Config, AdaptersList, Backend, Logger, QueueService, AttachmentMgr>;
+    create<AdaptersList extends BaseNotificationAdapter<BaseNotificationTemplateRenderer<Config>, Config>[], Backend extends BaseNotificationBackend<Config>, Logger extends BaseLogger, QueueService extends BaseNotificationQueueService<Config>, AttachmentMgr extends BaseAttachmentManager>(adapters: AdaptersList, backend: Backend, logger: Logger, contextGeneratorsMap: BaseNotificationTypeConfig['ContextMap'], queueService?: QueueService, attachmentManager?: AttachmentMgr, options?: VintaSendOptions, gitCommitShaProvider?: BaseGitCommitShaProvider, additionalBackends?: Backend[]): VintaSend<Config, AdaptersList, Backend, Logger, QueueService, AttachmentMgr>;
 }
 export declare class VintaSend<Config extends BaseNotificationTypeConfig, AdaptersList extends BaseNotificationAdapter<BaseNotificationTemplateRenderer<Config>, Config>[], Backend extends BaseNotificationBackend<Config>, Logger extends BaseLogger, QueueService extends BaseNotificationQueueService<Config>, AttachmentMgr extends BaseAttachmentManager> {
     private adapters;
@@ -71,7 +72,25 @@ export declare class VintaSend<Config extends BaseNotificationTypeConfig, Adapte
     private options;
     private gitCommitShaProvider?;
     private contextGeneratorsMap;
-    constructor(adapters: AdaptersList, backend: Backend, logger: Logger, contextGeneratorsMap: Config['ContextMap'], queueService?: QueueService | undefined, attachmentManager?: AttachmentMgr | undefined, options?: VintaSendOptions, gitCommitShaProvider?: BaseGitCommitShaProvider | undefined);
+    private backends;
+    private primaryBackendIdentifier;
+    /**
+     * Creates a VintaSend instance with one primary backend and optional additional backends.
+     *
+     * In multi-backend mode:
+     * - writes execute on the primary backend first
+     * - additional backends receive best-effort replication
+     * - reads default to primary unless a backend identifier is provided
+     */
+    constructor(adapters: AdaptersList, backend: Backend, logger: Logger, contextGeneratorsMap: Config['ContextMap'], queueService?: QueueService | undefined, attachmentManager?: AttachmentMgr | undefined, options?: VintaSendOptions, gitCommitShaProvider?: BaseGitCommitShaProvider | undefined, additionalBackends?: Backend[]);
+    private getBackendIdentifier;
+    private getBackend;
+    private getAdditionalBackends;
+    getPrimaryBackendIdentifier(): string;
+    getAllBackendIdentifiers(): string[];
+    getAdditionalBackendIdentifiers(): string[];
+    hasBackend(identifier: string): boolean;
+    private executeMultiBackendWrite;
     registerQueueService(queueService: QueueService): void;
     private normalizeGitCommitSha;
     private resolveGitCommitShaForExecution;
@@ -103,19 +122,34 @@ export declare class VintaSend<Config extends BaseNotificationTypeConfig, Adapte
      * @throws Error if the format is invalid
      */
     private validateEmailOrPhone;
-    getAllFutureNotifications(): Promise<AnyDatabaseNotification<Config>[]>;
-    getAllFutureNotificationsFromUser(userId: Config['NotificationIdType']): Promise<DatabaseNotification<Config>[]>;
-    getFutureNotificationsFromUser(userId: Config['NotificationIdType'], page: number, pageSize: number): Promise<DatabaseNotification<Config>[]>;
-    getFutureNotifications(page: number, pageSize: number): Promise<AnyDatabaseNotification<Config>[]>;
+    getAllFutureNotifications(backendIdentifier?: string): Promise<AnyDatabaseNotification<Config>[]>;
+    getAllFutureNotificationsFromUser(userId: Config['NotificationIdType'], backendIdentifier?: string): Promise<DatabaseNotification<Config>[]>;
+    getFutureNotificationsFromUser(userId: Config['NotificationIdType'], page: number, pageSize: number, backendIdentifier?: string): Promise<DatabaseNotification<Config>[]>;
+    getFutureNotifications(page: number, pageSize: number, backendIdentifier?: string): Promise<AnyDatabaseNotification<Config>[]>;
     getNotificationContext<ContextName extends string & keyof Config['ContextMap']>(contextName: ContextName, parameters: Parameters<ReturnType<typeof this.contextGeneratorsMap.getContextGenerator<ContextName>>['generate']>[0]): Promise<JsonObject>;
     renderEmailTemplateFromContent(notification: AnyDatabaseNotification<Config>, templateContent: EmailTemplateContent, contextInput: RenderEmailTemplateContextInput<Config>): Promise<EmailTemplate>;
     sendPendingNotifications(): Promise<void>;
-    getPendingNotifications(page: number, pageSize: number): Promise<AnyDatabaseNotification<Config>[]>;
-    getNotifications(page: number, pageSize: number): Promise<AnyDatabaseNotification<Config>[]>;
-    getOneOffNotifications(page: number, pageSize: number): Promise<DatabaseOneOffNotification<Config>[]>;
-    getNotification(notificationId: Config['NotificationIdType'], forUpdate?: boolean): Promise<AnyDatabaseNotification<Config> | null>;
-    filterNotifications(filter: NotificationFilterFields<Config>, page: number, pageSize: number): Promise<AnyDatabaseNotification<Config>[]>;
-    getBackendSupportedFilterCapabilities(): Promise<{
+    /**
+     * Gets pending notifications from the primary backend by default or from a specific backend.
+     */
+    getPendingNotifications(page: number, pageSize: number, backendIdentifier?: string): Promise<AnyDatabaseNotification<Config>[]>;
+    /**
+     * Gets notifications from the primary backend by default or from a specific backend.
+     */
+    getNotifications(page: number, pageSize: number, backendIdentifier?: string): Promise<AnyDatabaseNotification<Config>[]>;
+    getOneOffNotifications(page: number, pageSize: number, backendIdentifier?: string): Promise<DatabaseOneOffNotification<Config>[]>;
+    /**
+     * Gets a notification by ID from the primary backend by default or from a specific backend.
+     */
+    getNotification(notificationId: Config['NotificationIdType'], forUpdate?: boolean, backendIdentifier?: string): Promise<AnyDatabaseNotification<Config> | null>;
+    /**
+     * Filters notifications in the primary backend by default or in a specific backend.
+     */
+    filterNotifications(filter: NotificationFilterFields<Config>, page: number, pageSize: number, backendIdentifier?: string): Promise<AnyDatabaseNotification<Config>[]>;
+    /**
+     * Returns the effective filter capabilities for the primary backend by default or for a specific backend.
+     */
+    getBackendSupportedFilterCapabilities(backendIdentifier?: string): Promise<{
         'logical.and': boolean;
         'logical.or': boolean;
         'logical.not': boolean;
@@ -143,15 +177,65 @@ export declare class VintaSend<Config extends BaseNotificationTypeConfig, Adapte
      *
      * @param notificationId - The ID of the one-off notification to retrieve
      * @param forUpdate - Whether the notification is being retrieved for update (default: false)
+      * @param backendIdentifier - Optional backend identifier. When omitted, the primary backend is used.
      * @returns The one-off notification or null if not found
      */
-    getOneOffNotification(notificationId: Config['NotificationIdType'], forUpdate?: boolean): Promise<DatabaseOneOffNotification<Config> | null>;
+    getOneOffNotification(notificationId: Config['NotificationIdType'], forUpdate?: boolean, backendIdentifier?: string): Promise<DatabaseOneOffNotification<Config> | null>;
     markRead(notificationId: Config['NotificationIdType'], checkIsSent?: boolean): Promise<DatabaseNotification<Config>>;
-    getInAppUnread(userId: Config['NotificationIdType']): Promise<DatabaseNotification<Config>[]>;
+    /**
+     * Gets unread in-app notifications from the primary backend by default or from a specific backend.
+     */
+    getInAppUnread(userId: Config['NotificationIdType'], backendIdentifier?: string): Promise<DatabaseNotification<Config>[]>;
     cancelNotification(notificationId: Config['NotificationIdType']): Promise<void>;
     resendNotification(notificationId: Config['NotificationIdType'], useStoredContextIfAvailable?: boolean): Promise<DatabaseNotification<Config> | undefined>;
     delayedSend(notificationId: Config['NotificationIdType']): Promise<void>;
     bulkPersistNotifications(notifications: Omit<AnyNotification<Config>, 'id'>[]): Promise<Config['NotificationIdType'][]>;
-    migrateToBackend<DestinationBackend extends BaseNotificationBackend<Config>>(destinationBackend: DestinationBackend, batchSize?: number): Promise<void>;
+    private normalizeValueForSyncComparison;
+    /**
+     * Verifies whether a notification is synchronized across all configured backends.
+     *
+     * The report includes backend-level existence/errors and field-level discrepancies
+     * when comparing additional backends against the primary backend.
+     */
+    verifyNotificationSync(notificationId: Config['NotificationIdType']): Promise<{
+        synced: boolean;
+        backends: Record<string, {
+            exists: boolean;
+            notification?: AnyDatabaseNotification<Config>;
+            error?: string;
+        }>;
+        discrepancies: string[];
+    }>;
+    /**
+     * Replicates one notification from the primary backend to all additional backends.
+     *
+     * If a notification already exists in an additional backend, it is updated.
+     * Otherwise, it is created.
+     */
+    replicateNotification(notificationId: Config['NotificationIdType']): Promise<{
+        successes: string[];
+        failures: {
+            backend: string;
+            error: string;
+        }[];
+    }>;
+    /**
+     * Returns a lightweight health snapshot for each configured backend.
+     */
+    getBackendSyncStats(): Promise<{
+        backends: Record<string, {
+            totalNotifications: number;
+            status: 'healthy' | 'error';
+            error?: string;
+        }>;
+    }>;
+    /**
+     * Migrates notifications from a source backend (primary by default) to a destination backend.
+     *
+     * @param destinationBackend - Backend receiving migrated records
+     * @param batchSize - Page size used while iterating source records
+     * @param sourceBackendIdentifier - Optional source backend identifier. Defaults to primary backend.
+     */
+    migrateToBackend<DestinationBackend extends BaseNotificationBackend<Config>>(destinationBackend: DestinationBackend, batchSize?: number, sourceBackendIdentifier?: string): Promise<void>;
 }
 export {};

package/dist/services/notification-service.js

@@ -7,14 +7,14 @@ const notification_context_generators_map_1 = require("./notification-context-ge
 class VintaSendFactory {
     create(adaptersOrParams, backend, logger, contextGeneratorsMap, queueService, attachmentManager, options = {
         raiseErrorOnFailedSend: false,
-    }, gitCommitShaProvider) {
+    }, gitCommitShaProvider, additionalBackends) {
         var _a;
         if (!Array.isArray(adaptersOrParams)) {
             return new VintaSend(adaptersOrParams.adapters, adaptersOrParams.backend, adaptersOrParams.logger, adaptersOrParams.contextGeneratorsMap, adaptersOrParams.queueService, adaptersOrParams.attachmentManager, (_a = adaptersOrParams.options) !== null && _a !== void 0 ? _a : {
                 raiseErrorOnFailedSend: false,
-            }, adaptersOrParams.gitCommitShaProvider);
+            }, adaptersOrParams.gitCommitShaProvider, adaptersOrParams.additionalBackends);
         }
-        return new VintaSend(adaptersOrParams, backend, logger, contextGeneratorsMap, queueService, attachmentManager, options, gitCommitShaProvider);
+        return new VintaSend(adaptersOrParams, backend, logger, contextGeneratorsMap, queueService, attachmentManager, options, gitCommitShaProvider, additionalBackends);
     }
 }
 exports.VintaSendFactory = VintaSendFactory;
@@ -25,9 +25,17 @@ function hasAttachmentManagerInjection(backend) {
         typeof backend.injectAttachmentManager === 'function');
 }
 class VintaSend {
+    /**
+     * Creates a VintaSend instance with one primary backend and optional additional backends.
+     *
+     * In multi-backend mode:
+     * - writes execute on the primary backend first
+     * - additional backends receive best-effort replication
+     * - reads default to primary unless a backend identifier is provided
+     */
     constructor(adapters, backend, logger, contextGeneratorsMap, queueService, attachmentManager, options = {
         raiseErrorOnFailedSend: false,
-    }, gitCommitShaProvider) {
+    }, gitCommitShaProvider, additionalBackends = []) {
         this.adapters = adapters;
         this.backend = backend;
         this.logger = logger;
@@ -36,6 +44,25 @@ class VintaSend {
         this.options = options;
         this.gitCommitShaProvider = gitCommitShaProvider;
         this.contextGeneratorsMap = new notification_context_generators_map_1.NotificationContextGeneratorsMap(contextGeneratorsMap);
+        this.backends = new Map();
+        this.primaryBackendIdentifier = this.getBackendIdentifier(backend);
+        this.backends.set(this.primaryBackendIdentifier, backend);
+        for (const additionalBackend of additionalBackends) {
+            const additionalBackendIdentifier = this.getBackendIdentifier(additionalBackend);
+            if (this.backends.has(additionalBackendIdentifier)) {
+                throw new Error(`Duplicate backend identifier: ${additionalBackendIdentifier}`);
+            }
+            this.backends.set(additionalBackendIdentifier, additionalBackend);
+            if (typeof additionalBackend.injectLogger === 'function') {
+                additionalBackend.injectLogger(logger);
+            }
+            if (this.attachmentManager && hasAttachmentManagerInjection(additionalBackend)) {
+                additionalBackend.injectAttachmentManager(this.attachmentManager);
+            }
+        }
+        if (this.getAdditionalBackends().length !== additionalBackends.length) {
+            throw new Error('Invalid additional backends configuration');
+        }
         for (const adapter of adapters) {
             adapter.injectBackend(backend);
             adapter.injectLogger(logger);
@@ -55,6 +82,56 @@ class VintaSend {
             backend.injectAttachmentManager(this.attachmentManager);
         }
     }
+    getBackendIdentifier(backend) {
+        if (typeof backend.getBackendIdentifier === 'function') {
+            return backend.getBackendIdentifier();
+        }
+        return `backend-${this.backends.size}`;
+    }
+    getBackend(identifier) {
+        if (!identifier) {
+            return this.backend;
+        }
+        const backend = this.backends.get(identifier);
+        if (!backend) {
+            throw new Error(`Backend not found: ${identifier}`);
+        }
+        return backend;
+    }
+    getAdditionalBackends() {
+        return Array.from(this.backends.entries())
+            .filter(([identifier]) => identifier !== this.primaryBackendIdentifier)
+            .map(([, backend]) => backend);
+    }
+    getPrimaryBackendIdentifier() {
+        return this.primaryBackendIdentifier;
+    }
+    getAllBackendIdentifiers() {
+        return Array.from(this.backends.keys());
+    }
+    getAdditionalBackendIdentifiers() {
+        return this.getAllBackendIdentifiers().filter((identifier) => identifier !== this.primaryBackendIdentifier);
+    }
+    hasBackend(identifier) {
+        return this.backends.has(identifier);
+    }
+    async executeMultiBackendWrite(operation, primaryWrite, additionalWrite) {
+        const primaryResult = await primaryWrite(this.backend);
+        if (!additionalWrite) {
+            return primaryResult;
+        }
+        for (const additionalBackend of this.getAdditionalBackends()) {
+            const backendIdentifier = this.getBackendIdentifier(additionalBackend);
+            try {
+                await additionalWrite(additionalBackend, primaryResult);
+                this.logger.info(`${operation} replicated to backend ${backendIdentifier}`);
+            }
+            catch (replicationError) {
+                this.logger.error(`Failed to replicate ${operation} to backend ${backendIdentifier}: ${replicationError}`);
+            }
+        }
+        return primaryResult;
+    }
     registerQueueService(queueService) {
         this.queueService = queueService;
     }
@@ -85,19 +162,26 @@ class VintaSend {
             const oneOffNotificationUpdate = {
                 gitCommitSha,
             };
-            return this.backend.persistOneOffNotificationUpdate(notification.id, oneOffNotificationUpdate);
+            return this.executeMultiBackendWrite('persistOneOffNotificationGitCommitSha', async (backend) => {
+                return backend.persistOneOffNotificationUpdate(notification.id, oneOffNotificationUpdate);
+            }, async (backend) => {
+                await backend.persistOneOffNotificationUpdate(notification.id, oneOffNotificationUpdate);
+            });
         }
         const notificationUpdate = {
             gitCommitSha,
         };
-        return this.backend.persistNotificationUpdate(notification.id, notificationUpdate);
+        return this.executeMultiBackendWrite('persistNotificationGitCommitSha', async (backend) => {
+            return backend.persistNotificationUpdate(notification.id, notificationUpdate);
+        }, async (backend) => {
+            await backend.persistNotificationUpdate(notification.id, notificationUpdate);
+        });
     }
     async resolveAndPersistGitCommitShaForExecution(notification) {
         const gitCommitSha = await this.resolveGitCommitShaForExecution();
         return this.persistGitCommitShaForExecution(notification, gitCommitSha);
     }
     async send(notification) {
-        var _a;
         const notificationWithExecutionGitCommitSha = await this.resolveAndPersistGitCommitShaForExecution(notification);
         const adaptersOfType = this.adapters.filter((adapter) => adapter.notificationType === notificationWithExecutionGitCommitSha.notificationType);
         if (adaptersOfType.length === 0) {
@@ -152,7 +236,11 @@ class VintaSend {
             catch (sendError) {
                 this.logger.error(`Error sending notification ${notificationWithExecutionGitCommitSha.id} with adapter ${adapter.key}: ${sendError}`);
                 try {
-                    await this.backend.markAsFailed(notificationWithExecutionGitCommitSha.id, true);
+                    await this.executeMultiBackendWrite('markAsFailed', async (backend) => {
+                        return backend.markAsFailed(notificationWithExecutionGitCommitSha.id, true);
+                    }, async (backend) => {
+                        await backend.markAsFailed(notificationWithExecutionGitCommitSha.id, true);
+                    });
                 }
                 catch (markFailedError) {
                     this.logger.error(`Error marking notification ${notificationWithExecutionGitCommitSha.id} as failed: ${markFailedError}`);
@@ -160,13 +248,23 @@ class VintaSend {
                 continue;
             }
             try {
-                await this.backend.markAsSent(notificationWithExecutionGitCommitSha.id, true);
+                await this.executeMultiBackendWrite('markAsSent', async (backend) => {
+                    return backend.markAsSent(notificationWithExecutionGitCommitSha.id, true);
+                }, async (backend) => {
+                    await backend.markAsSent(notificationWithExecutionGitCommitSha.id, true);
+                });
             }
             catch (markSentError) {
                 this.logger.error(`Error marking notification ${notificationWithExecutionGitCommitSha.id} as sent: ${markSentError}`);
             }
             try {
-                await this.backend.storeAdapterAndContextUsed(notificationWithExecutionGitCommitSha.id, (_a = adapter.key) !== null && _a !== void 0 ? _a : 'unknown', context !== null && context !== void 0 ? context : {});
+                await this.executeMultiBackendWrite('storeAdapterAndContextUsed', async (backend) => {
+                    var _a;
+                    await backend.storeAdapterAndContextUsed(notificationWithExecutionGitCommitSha.id, (_a = adapter.key) !== null && _a !== void 0 ? _a : 'unknown', context !== null && context !== void 0 ? context : {});
+                }, async (backend) => {
+                    var _a;
+                    await backend.storeAdapterAndContextUsed(notificationWithExecutionGitCommitSha.id, (_a = adapter.key) !== null && _a !== void 0 ? _a : 'unknown', context !== null && context !== void 0 ? context : {});
+                });
             }
             catch (storeContextError) {
                 this.logger.error(`Error storing adapter and context for notification ${notificationWithExecutionGitCommitSha.id}: ${storeContextError}`);
@@ -174,7 +272,14 @@ class VintaSend {
         }
     }
     async createNotification(notification) {
-        const createdNotification = await this.backend.persistNotification(notification);
+        const createdNotification = await this.executeMultiBackendWrite('createNotification', async (backend) => {
+            return backend.persistNotification(notification);
+        }, async (backend, primaryResult) => {
+            await backend.persistNotification({
+                ...notification,
+                id: primaryResult.id,
+            });
+        });
         this.logger.info(`Notification ${createdNotification.id} created`);
         if (!notification.sendAfter || notification.sendAfter <= new Date()) {
             this.logger.info(`Notification ${createdNotification.id} sent immediately because sendAfter is null or in the past`);
@@ -186,7 +291,11 @@ class VintaSend {
         return createdNotification;
     }
     async updateNotification(notificationId, notification) {
-        const updatedNotification = this.backend.persistNotificationUpdate(notificationId, notification);
+        const updatedNotification = this.executeMultiBackendWrite('updateNotification', async (backend) => {
+            return backend.persistNotificationUpdate(notificationId, notification);
+        }, async (backend) => {
+            await backend.persistNotificationUpdate(notificationId, notification);
+        });
         this.logger.info(`Notification ${notificationId} updated`);
         return updatedNotification;
     }
@@ -200,7 +309,14 @@ class VintaSend {
     async createOneOffNotification(notification) {
         // Validate email or phone format
         this.validateEmailOrPhone(notification.emailOrPhone);
-        const createdNotification = await this.backend.persistOneOffNotification(notification);
+        const createdNotification = await this.executeMultiBackendWrite('createOneOffNotification', async (backend) => {
+            return backend.persistOneOffNotification(notification);
+        }, async (backend, primaryResult) => {
+            await backend.persistOneOffNotification({
+                ...notification,
+                id: primaryResult.id,
+            });
+        });
         this.logger.info(`One-off notification ${createdNotification.id} created`);
         if (!notification.sendAfter || notification.sendAfter <= new Date()) {
             this.logger.info(`One-off notification ${createdNotification.id} sent immediately`);
@@ -223,7 +339,11 @@ class VintaSend {
         if (notification.emailOrPhone !== undefined) {
             this.validateEmailOrPhone(notification.emailOrPhone);
         }
-        const updatedNotification = await this.backend.persistOneOffNotificationUpdate(notificationId, notification);
+        const updatedNotification = await this.executeMultiBackendWrite('updateOneOffNotification', async (backend) => {
+            return backend.persistOneOffNotificationUpdate(notificationId, notification);
+        }, async (backend) => {
+            await backend.persistOneOffNotificationUpdate(notificationId, notification);
+        });
         this.logger.info(`One-off notification ${notificationId} updated`);
         if (!updatedNotification.sendAfter || updatedNotification.sendAfter <= new Date()) {
             this.logger.info(`One-off notification ${notificationId} sent after update`);
@@ -250,17 +370,17 @@ class VintaSend {
             throw new Error('Invalid email or phone format');
         }
     }
-    async getAllFutureNotifications() {
-        return this.backend.getAllFutureNotifications();
+    async getAllFutureNotifications(backendIdentifier) {
+        return this.getBackend(backendIdentifier).getAllFutureNotifications();
     }
-    async getAllFutureNotificationsFromUser(userId) {
-        return this.backend.getAllFutureNotificationsFromUser(userId);
+    async getAllFutureNotificationsFromUser(userId, backendIdentifier) {
+        return this.getBackend(backendIdentifier).getAllFutureNotificationsFromUser(userId);
     }
-    async getFutureNotificationsFromUser(userId, page, pageSize) {
-        return this.backend.getFutureNotificationsFromUser(userId, page, pageSize);
+    async getFutureNotificationsFromUser(userId, page, pageSize, backendIdentifier) {
+        return this.getBackend(backendIdentifier).getFutureNotificationsFromUser(userId, page, pageSize);
     }
-    async getFutureNotifications(page, pageSize) {
-        return this.backend.getFutureNotifications(page, pageSize);
+    async getFutureNotifications(page, pageSize, backendIdentifier) {
+        return this.getBackend(backendIdentifier).getFutureNotifications(page, pageSize);
     }
     async getNotificationContext(contextName, parameters) {
         const context = this.contextGeneratorsMap.getContextGenerator(contextName).generate(parameters);
@@ -281,48 +401,78 @@ class VintaSend {
         return adapter.renderFromTemplateContent(notification, templateContent, context);
     }
     async sendPendingNotifications() {
-        const pendingNotifications = await this.backend.getAllPendingNotifications();
+        const pendingNotifications = await this.getBackend().getAllPendingNotifications();
         await Promise.all(pendingNotifications.map((notification) => this.send(notification)));
     }
-    async getPendingNotifications(page, pageSize) {
-        return this.backend.getPendingNotifications(page, pageSize);
+    /**
+     * Gets pending notifications from the primary backend by default or from a specific backend.
+     */
+    async getPendingNotifications(page, pageSize, backendIdentifier) {
+        return this.getBackend(backendIdentifier).getPendingNotifications(page, pageSize);
     }
-    async getNotifications(page, pageSize) {
-        return this.backend.getNotifications(page, pageSize);
+    /**
+     * Gets notifications from the primary backend by default or from a specific backend.
+     */
+    async getNotifications(page, pageSize, backendIdentifier) {
+        return this.getBackend(backendIdentifier).getNotifications(page, pageSize);
     }
-    async getOneOffNotifications(page, pageSize) {
-        return this.backend.getOneOffNotifications(page, pageSize);
+    async getOneOffNotifications(page, pageSize, backendIdentifier) {
+        return this.getBackend(backendIdentifier).getOneOffNotifications(page, pageSize);
     }
-    async getNotification(notificationId, forUpdate = false) {
-        return this.backend.getNotification(notificationId, forUpdate);
+    /**
+     * Gets a notification by ID from the primary backend by default or from a specific backend.
+     */
+    async getNotification(notificationId, forUpdate = false, backendIdentifier) {
+        return this.getBackend(backendIdentifier).getNotification(notificationId, forUpdate);
     }
-    async filterNotifications(filter, page, pageSize) {
-        return this.backend.filterNotifications(filter, page, pageSize);
+    /**
+     * Filters notifications in the primary backend by default or in a specific backend.
+     */
+    async filterNotifications(filter, page, pageSize, backendIdentifier) {
+        return this.getBackend(backendIdentifier).filterNotifications(filter, page, pageSize);
     }
-    async getBackendSupportedFilterCapabilities() {
+    /**
+     * Returns the effective filter capabilities for the primary backend by default or for a specific backend.
+     */
+    async getBackendSupportedFilterCapabilities(backendIdentifier) {
         var _a, _b, _c;
-        return { ...base_notification_backend_1.DEFAULT_BACKEND_FILTER_CAPABILITIES, ...((_c = (_b = (_a = this.backend).getFilterCapabilities) === null || _b === void 0 ? void 0 : _b.call(_a)) !== null && _c !== void 0 ? _c : {}) };
+        return {
+            ...base_notification_backend_1.DEFAULT_BACKEND_FILTER_CAPABILITIES,
+            ...((_c = (_b = (_a = this.getBackend(backendIdentifier)).getFilterCapabilities) === null || _b === void 0 ? void 0 : _b.call(_a)) !== null && _c !== void 0 ? _c : {}),
+        };
     }
     /**
      * Gets a one-off notification by ID.
      *
      * @param notificationId - The ID of the one-off notification to retrieve
      * @param forUpdate - Whether the notification is being retrieved for update (default: false)
+      * @param backendIdentifier - Optional backend identifier. When omitted, the primary backend is used.
      * @returns The one-off notification or null if not found
      */
-    async getOneOffNotification(notificationId, forUpdate = false) {
-        return this.backend.getOneOffNotification(notificationId, forUpdate);
+    async getOneOffNotification(notificationId, forUpdate = false, backendIdentifier) {
+        return this.getBackend(backendIdentifier).getOneOffNotification(notificationId, forUpdate);
     }
     async markRead(notificationId, checkIsSent = true) {
-        const notification = await this.backend.markAsRead(notificationId, checkIsSent);
+        const notification = await this.executeMultiBackendWrite('markRead', async (backend) => {
+            return backend.markAsRead(notificationId, checkIsSent);
+        }, async (backend) => {
+            await backend.markAsRead(notificationId, checkIsSent);
+        });
         this.logger.info(`Notification ${notificationId} marked as read`);
         return notification;
     }
-    async getInAppUnread(userId) {
-        return this.backend.filterAllInAppUnreadNotifications(userId);
+    /**
+     * Gets unread in-app notifications from the primary backend by default or from a specific backend.
+     */
+    async getInAppUnread(userId, backendIdentifier) {
+        return this.getBackend(backendIdentifier).filterAllInAppUnreadNotifications(userId);
     }
     async cancelNotification(notificationId) {
-        await this.backend.cancelNotification(notificationId);
+        await this.executeMultiBackendWrite('cancelNotification', async (backend) => {
+            await backend.cancelNotification(notificationId);
+        }, async (backend) => {
+            await backend.cancelNotification(notificationId);
+        });
         this.logger.info(`Notification ${notificationId} cancelled`);
     }
     async resendNotification(notificationId, useStoredContextIfAvailable = false) {
@@ -415,32 +565,222 @@ class VintaSend {
             catch (sendError) {
                 this.logger.error(`Error sending notification ${notificationWithExecutionGitCommitSha.id} with adapter ${adapter.key}: ${sendError}`);
                 try {
-                    await this.backend.markAsFailed(notificationWithExecutionGitCommitSha.id, true);
+                    await this.executeMultiBackendWrite('markAsFailed', async (backend) => {
+                        return backend.markAsFailed(notificationWithExecutionGitCommitSha.id, true);
+                    }, async (backend) => {
+                        await backend.markAsFailed(notificationWithExecutionGitCommitSha.id, true);
+                    });
                 }
                 catch (markFailedError) {
                     this.logger.error(`Error marking notification ${notificationWithExecutionGitCommitSha.id} as failed: ${markFailedError}`);
                 }
             }
             try {
-                await this.backend.markAsSent(notificationWithExecutionGitCommitSha.id, true);
+                await this.executeMultiBackendWrite('markAsSent', async (backend) => {
+                    return backend.markAsSent(notificationWithExecutionGitCommitSha.id, true);
+                }, async (backend) => {
+                    await backend.markAsSent(notificationWithExecutionGitCommitSha.id, true);
+                });
             }
             catch (markSentError) {
                 this.logger.error(`Error marking notification ${notificationWithExecutionGitCommitSha.id} as sent: ${markSentError}`);
             }
         }
         try {
-            await this.backend.storeAdapterAndContextUsed(notificationWithExecutionGitCommitSha.id, lastAdapterKey, context);
+            await this.executeMultiBackendWrite('storeAdapterAndContextUsed', async (backend) => {
+                await backend.storeAdapterAndContextUsed(notificationWithExecutionGitCommitSha.id, lastAdapterKey, context);
+            }, async (backend) => {
+                await backend.storeAdapterAndContextUsed(notificationWithExecutionGitCommitSha.id, lastAdapterKey, context);
+            });
         }
         catch (storeContextError) {
             this.logger.error(`Error storing adapter and context for notification ${notificationWithExecutionGitCommitSha.id}: ${storeContextError}`);
         }
     }
     async bulkPersistNotifications(notifications) {
-        return this.backend.bulkPersistNotifications(notifications);
+        return this.executeMultiBackendWrite('bulkPersistNotifications', async (backend) => {
+            return backend.bulkPersistNotifications(notifications);
+        }, async (backend, createdIds) => {
+            const notificationsWithIds = notifications.map((notification, index) => {
+                return {
+                    ...notification,
+                    id: createdIds[index],
+                };
+            });
+            await backend.bulkPersistNotifications(notificationsWithIds);
+        });
+    }
+    normalizeValueForSyncComparison(value) {
+        if (value === null) {
+            return 'null';
+        }
+        if (value === undefined) {
+            return 'undefined';
+        }
+        if (value instanceof Date) {
+            return value.toISOString();
+        }
+        if (typeof value === 'object') {
+            try {
+                return JSON.stringify(value);
+            }
+            catch (_a) {
+                return '[unserializable-object]';
+            }
+        }
+        return String(value);
+    }
+    /**
+     * Verifies whether a notification is synchronized across all configured backends.
+     *
+     * The report includes backend-level existence/errors and field-level discrepancies
+     * when comparing additional backends against the primary backend.
+     */
+    async verifyNotificationSync(notificationId) {
+        var _a, _b, _c;
+        const report = {
+            synced: true,
+            backends: {},
+            discrepancies: [],
+        };
+        for (const [identifier, backend] of this.backends.entries()) {
+            try {
+                const notification = await backend.getNotification(notificationId, false);
+                report.backends[identifier] = {
+                    exists: notification !== null,
+                    notification: notification !== null && notification !== void 0 ? notification : undefined,
+                };
+            }
+            catch (error) {
+                report.backends[identifier] = {
+                    exists: false,
+                    error: String(error),
+                };
+                report.discrepancies.push(`Backend ${identifier}: ${String(error)}`);
+                report.synced = false;
+            }
+        }
+        const primaryNotification = (_a = report.backends[this.primaryBackendIdentifier]) === null || _a === void 0 ? void 0 : _a.notification;
+        if (!primaryNotification) {
+            report.synced = false;
+            report.discrepancies.push('Notification not found in primary backend');
+            return report;
+        }
+        for (const [identifier, backendReport] of Object.entries(report.backends)) {
+            if (identifier === this.primaryBackendIdentifier) {
+                continue;
+            }
+            if (!backendReport.exists) {
+                report.synced = false;
+                report.discrepancies.push(`Notification missing in backend: ${identifier}`);
+                continue;
+            }
+            if (((_b = backendReport.notification) === null || _b === void 0 ? void 0 : _b.status) !== primaryNotification.status) {
+                report.synced = false;
+                report.discrepancies.push(`Status mismatch in ${identifier}: ${String((_c = backendReport.notification) === null || _c === void 0 ? void 0 : _c.status)} vs ${String(primaryNotification.status)}`);
+            }
+            const primaryNotificationRecord = primaryNotification;
+            const backendNotificationRecord = backendReport.notification;
+            const fieldsToCompare = [
+                'notificationType',
+                'title',
+                'bodyTemplate',
+                'subjectTemplate',
+                'contextName',
+                'contextParameters',
+                'contextUsed',
+                'extraParams',
+                'adapterUsed',
+                'sendAfter',
+                'sentAt',
+                'readAt',
+                'createdAt',
+                'updatedAt',
+                'gitCommitSha',
+            ];
+            for (const fieldName of fieldsToCompare) {
+                const primaryValue = this.normalizeValueForSyncComparison(primaryNotificationRecord[fieldName]);
+                const backendValue = this.normalizeValueForSyncComparison(backendNotificationRecord[fieldName]);
+                if (primaryValue !== backendValue) {
+                    report.synced = false;
+                    report.discrepancies.push(`Field mismatch in ${identifier} for ${fieldName}: ${backendValue} vs ${primaryValue}`);
+                }
+            }
+        }
+        return report;
+    }
+    /**
+     * Replicates one notification from the primary backend to all additional backends.
+     *
+     * If a notification already exists in an additional backend, it is updated.
+     * Otherwise, it is created.
+     */
+    async replicateNotification(notificationId) {
+        const primaryNotification = await this.backend.getNotification(notificationId, false);
+        if (!primaryNotification) {
+            throw new Error(`Notification ${String(notificationId)} not found in primary backend`);
+        }
+        const result = {
+            successes: [],
+            failures: [],
+        };
+        for (const backend of this.getAdditionalBackends()) {
+            const backendIdentifier = this.getBackendIdentifier(backend);
+            try {
+                const existingNotification = await backend.getNotification(notificationId, false);
+                if (existingNotification) {
+                    await backend.persistNotificationUpdate(notificationId, primaryNotification);
+                }
+                else {
+                    await backend.persistNotification(primaryNotification);
+                }
+                result.successes.push(backendIdentifier);
+            }
+            catch (error) {
+                result.failures.push({
+                    backend: backendIdentifier,
+                    error: String(error),
+                });
+            }
+        }
+        return result;
     }
-    async migrateToBackend(destinationBackend, batchSize = 5000) {
+    /**
+     * Returns a lightweight health snapshot for each configured backend.
+     */
+    async getBackendSyncStats() {
+        const stats = {
+            backends: {},
+        };
+        for (const [identifier, backend] of this.backends.entries()) {
+            try {
+                const notifications = await backend.getAllNotifications();
+                stats.backends[identifier] = {
+                    totalNotifications: notifications.length,
+                    status: 'healthy',
+                };
+            }
+            catch (error) {
+                stats.backends[identifier] = {
+                    totalNotifications: 0,
+                    status: 'error',
+                    error: String(error),
+                };
+            }
+        }
+        return stats;
+    }
+    /**
+     * Migrates notifications from a source backend (primary by default) to a destination backend.
+     *
+     * @param destinationBackend - Backend receiving migrated records
+     * @param batchSize - Page size used while iterating source records
+     * @param sourceBackendIdentifier - Optional source backend identifier. Defaults to primary backend.
+     */
+    async migrateToBackend(destinationBackend, batchSize = 5000, sourceBackendIdentifier) {
+        const sourceBackend = this.getBackend(sourceBackendIdentifier);
         let pageNumber = 0;
-        let allNotifications = await this.backend.getNotifications(pageNumber, batchSize);
+        let allNotifications = await sourceBackend.getNotifications(pageNumber, batchSize);
         while (allNotifications.length > 0) {
             pageNumber += 1;
             const notificationsWithoutId = allNotifications.map((notification) => {
@@ -448,7 +788,7 @@ class VintaSend {
                 return notificationWithoutId;
             });
             await destinationBackend.bulkPersistNotifications(notificationsWithoutId);
-            allNotifications = await this.backend.getNotifications(pageNumber, batchSize);
+            allNotifications = await sourceBackend.getNotifications(pageNumber, batchSize);
         }
     }
 }

package/dist/types/notification.d.ts

@@ -6,6 +6,7 @@ import type { BaseNotificationTypeConfig } from './notification-type-config';
 import type { DatabaseOneOffNotification, OneOffNotification, OneOffNotificationInput } from './one-off-notification';
 export type { DatabaseOneOffNotification, OneOffNotification, OneOffNotificationInput, OneOffNotificationResendWithContextInput, } from './one-off-notification';
 export type NotificationInput<Config extends BaseNotificationTypeConfig> = {
+    id?: Config['NotificationIdType'];
     userId: Config['UserIdType'];
     notificationType: NotificationType;
     title: string | null;
@@ -19,6 +20,7 @@ export type NotificationInput<Config extends BaseNotificationTypeConfig> = {
     attachments?: NotificationAttachment[];
 };
 export type NotificationResendWithContextInput<Config extends BaseNotificationTypeConfig> = {
+    id?: Config['NotificationIdType'];
     userId: Config['UserIdType'];
     notificationType: NotificationType;
     title: string | null;

package/dist/types/one-off-notification.d.ts

@@ -8,6 +8,7 @@ import type { BaseNotificationTypeConfig } from './notification-type-config';
  * One-off notifications are sent directly to an email/phone without requiring a user account.
  */
 export type OneOffNotificationInput<Config extends BaseNotificationTypeConfig> = {
+    id?: Config['NotificationIdType'];
     emailOrPhone: string;
     firstName: string;
     lastName: string;
@@ -27,6 +28,7 @@ export type OneOffNotificationInput<Config extends BaseNotificationTypeConfig> =
  * Similar to OneOffNotificationInput but includes the contextUsed field.
  */
 export type OneOffNotificationResendWithContextInput<Config extends BaseNotificationTypeConfig> = {
+    id?: Config['NotificationIdType'];
     emailOrPhone: string;
     firstName: string;
     lastName: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vintasend",
-  "version": "0.7.1",
+  "version": "0.8.0",
   "main": "dist/index.js",
   "files": [
     "dist"