vintasend 0.8.2 → 0.9.0

package/README.md

@@ -126,7 +126,7 @@ const vintasend = new VintaSendFactory<NotificationTypeConfig>().create({
 
 ### How It Works
 
-- **Writes**: VintaSend writes to the primary backend first, then replicates to additional backends on a best-effort basis.
+- **Writes**: VintaSend writes to the primary backend first, then replicates to additional backends either inline (default) or through a per-backend replication queue.
 - **Reads**: Read methods use the primary backend by default, but support optional backend targeting by identifier.
 
 ```typescript
@@ -153,11 +153,71 @@ if (!report.synced) {
 const backendStats = await vintasend.getBackendSyncStats();
 ```
 
+### Asynchronous Replication Queue (Per Backend)
+
+VintaSend supports asynchronous replication to additional backends with one queued task per destination backend.
+
+#### Replication mode
+
+Use `replicationMode: 'queued'` to enqueue replication instead of replicating inline in the request path.
+
+```typescript
+const vintasend = new VintaSendFactory<NotificationTypeConfig>().create({
+  adapters,
+  backend: primaryBackend,
+  additionalBackends: [replicaA, replicaB],
+  logger,
+  contextGeneratorsMap,
+  replicationQueueService,
+  options: {
+    raiseErrorOnFailedSend: false,
+    replicationMode: 'queued',
+  },
+});
+```
+
+#### Replication queue contract
+
+The replication queue service receives both the notification id and the target backend identifier:
+
+```typescript
+export interface BaseNotificationReplicationQueueService<Config extends BaseNotificationTypeConfig> {
+  enqueueReplication(notificationId: Config['NotificationIdType'], backendIdentifier: string): Promise<void>;
+}
+```
+
+When queued replication is enabled, VintaSend enqueues one replication task for each additional backend.
+
+#### Worker processing
+
+Workers should process replication with a backend target to apply replication only for the queued destination:
+
+```typescript
+await vintasend.processReplication(notificationId, backendIdentifier);
+```
+
+You can still call `processReplication(notificationId)` without a target to process all additional backends.
+
+#### Ordering and idempotency safety
+
+To reduce out-of-order replication issues, backends can optionally implement conditional apply:
+
+```typescript
+applyReplicationSnapshotIfNewer?(snapshot): Promise<{ applied: boolean }>;
+```
+
+- If destination state is newer/equal, replication is skipped (`applied: false`).
+- If destination is older, snapshot is applied.
+- Duplicate-create race conditions are handled with create→update fallback in worker replication flow.
+
+Official backends `vintasend-prisma` and `vintasend-medplum` implement this conditional apply behavior.
+
 ### 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.
+- In queued mode, enqueue failures fall back to inline replication for affected backends.
+- This keeps primary workflows available while still enabling redundancy and eventual consistency.
 
 ## Filtering and Ordering Notifications
 

package/dist/index.d.ts

@@ -7,6 +7,7 @@ export type { BaseNotificationBackend } from './services/notification-backends/b
 export { supportsAttachments, isFieldFilter } from './services/notification-backends/base-notification-backend';
 export type { NotificationFilter, NotificationFilterFields, DateRange, NotificationFilterCapabilities, StringFilterLookup, StringFieldFilter, } from './services/notification-backends/base-notification-backend';
 export type { BaseNotificationQueueService } from './services/notification-queue-service/base-notification-queue-service';
+export type { BaseNotificationReplicationQueueService } from './services/notification-queue-service/base-notification-replication-queue-service';
 export type { VintaSend } from './services/notification-service';
 export { VintaSendFactory } from './services/notification-service';
 export type { BaseEmailTemplateRenderer } from './services/notification-template-renderers/base-email-template-renderer';

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

@@ -118,6 +118,16 @@ export interface BaseNotificationBackend<Config extends BaseNotificationTypeConf
     getNotifications(page: number, pageSize: number): Promise<AnyDatabaseNotification<Config>[]>;
     bulkPersistNotifications(notifications: Omit<AnyNotification<Config>, 'id'>[]): Promise<Config['NotificationIdType'][]>;
     persistNotificationUpdate(notificationId: Config['NotificationIdType'], notification: Partial<Omit<Notification<Config>, 'id'>>): Promise<DatabaseNotification<Config>>;
+    /**
+     * Applies a replication snapshot only when the destination state is older.
+     *
+     * This is used to mitigate out-of-order async replication deliveries.
+     * Implementations should return `applied: false` when the destination notification
+     * is already newer or equal to the snapshot.
+     */
+    applyReplicationSnapshotIfNewer?(snapshot: AnyDatabaseNotification<Config>): Promise<{
+        applied: boolean;
+    }>;
     markAsSent(notificationId: Config['NotificationIdType'], checkIsPending: boolean): Promise<AnyDatabaseNotification<Config>>;
     markAsFailed(notificationId: Config['NotificationIdType'], checkIsPending: boolean): Promise<AnyDatabaseNotification<Config>>;
     markAsRead(notificationId: Config['NotificationIdType'], checkIsSent: boolean): Promise<DatabaseNotification<Config>>;

package/dist/services/notification-queue-service/base-notification-replication-queue-service.d.ts

@@ -0,0 +1,4 @@
+import type { BaseNotificationTypeConfig } from '../../types/notification-type-config';
+export interface BaseNotificationReplicationQueueService<Config extends BaseNotificationTypeConfig> {
+    enqueueReplication(notificationId: Config['NotificationIdType'], backendIdentifier: string): Promise<void>;
+}

package/dist/services/notification-queue-service/base-notification-replication-queue-service.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

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

@@ -8,10 +8,12 @@ import type { BaseLogger } from './loggers/base-logger';
 import { type BaseNotificationAdapter } from './notification-adapters/base-notification-adapter';
 import { type BaseNotificationBackend, type NotificationFilterFields, type NotificationOrderBy } from './notification-backends/base-notification-backend';
 import type { BaseNotificationQueueService } from './notification-queue-service/base-notification-queue-service';
+import type { BaseNotificationReplicationQueueService } from './notification-queue-service/base-notification-replication-queue-service';
 import type { EmailTemplate, EmailTemplateContent } from './notification-template-renderers/base-email-template-renderer';
 import type { BaseNotificationTemplateRenderer } from './notification-template-renderers/base-notification-template-renderer';
 type VintaSendOptions = {
     raiseErrorOnFailedSend: boolean;
+    replicationMode?: 'inline' | 'queued';
 };
 type RenderEmailTemplateContextInput<Config extends BaseNotificationTypeConfig> = {
     context: JsonObject;
@@ -26,6 +28,7 @@ type VintaSendFactoryCreateParams<Config extends BaseNotificationTypeConfig, Ada
     logger: Logger;
     contextGeneratorsMap: BaseNotificationTypeConfig['ContextMap'];
     queueService?: QueueService;
+    replicationQueueService?: BaseNotificationReplicationQueueService<Config>;
     attachmentManager?: AttachmentMgr;
     options?: VintaSendOptions;
     gitCommitShaProvider?: BaseGitCommitShaProvider;
@@ -61,7 +64,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, additionalBackends?: Backend[]): 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[], replicationQueueService?: BaseNotificationReplicationQueueService<Config>): 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,6 +74,7 @@ export declare class VintaSend<Config extends BaseNotificationTypeConfig, Adapte
     private attachmentManager?;
     private options;
     private gitCommitShaProvider?;
+    private replicationQueueService?;
     private contextGeneratorsMap;
     private backends;
     private primaryBackendIdentifier;
@@ -82,7 +86,7 @@ export declare class VintaSend<Config extends BaseNotificationTypeConfig, Adapte
      * - 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[]);
+    constructor(adapters: AdaptersList, backend: Backend, logger: Logger, contextGeneratorsMap: Config['ContextMap'], queueService?: QueueService | undefined, attachmentManager?: AttachmentMgr | undefined, options?: VintaSendOptions, gitCommitShaProvider?: BaseGitCommitShaProvider | undefined, additionalBackends?: Backend[], replicationQueueService?: BaseNotificationReplicationQueueService<Config> | undefined);
     private getBackendIdentifier;
     private getBackend;
     private getAdditionalBackends;
@@ -92,6 +96,7 @@ export declare class VintaSend<Config extends BaseNotificationTypeConfig, Adapte
     hasBackend(identifier: string): boolean;
     private executeMultiBackendWrite;
     registerQueueService(queueService: QueueService): void;
+    registerReplicationQueueService(replicationQueueService: BaseNotificationReplicationQueueService<Config>): void;
     private normalizeGitCommitSha;
     private resolveGitCommitShaForExecution;
     private persistGitCommitShaForExecution;
@@ -196,6 +201,7 @@ export declare class VintaSend<Config extends BaseNotificationTypeConfig, Adapte
     delayedSend(notificationId: Config['NotificationIdType']): Promise<void>;
     bulkPersistNotifications(notifications: Omit<AnyNotification<Config>, 'id'>[]): Promise<Config['NotificationIdType'][]>;
     private normalizeValueForSyncComparison;
+    private isLikelyDuplicateReplicationConflict;
     /**
      * Verifies whether a notification is synchronized across all configured backends.
      *
@@ -211,6 +217,18 @@ export declare class VintaSend<Config extends BaseNotificationTypeConfig, Adapte
         }>;
         discrepancies: string[];
     }>;
+    /**
+     * Worker-facing replication entrypoint.
+     *
+     * Reads the notification from the primary backend and upserts into additional backends.
+     */
+    processReplication(notificationId: Config['NotificationIdType'], targetBackendIdentifier?: string): Promise<{
+        successes: string[];
+        failures: {
+            backend: string;
+            error: string;
+        }[];
+    }>;
     /**
      * Replicates one notification from the primary backend to all additional backends.
      *

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, additionalBackends) {
+    }, gitCommitShaProvider, additionalBackends, replicationQueueService) {
         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.additionalBackends);
+            }, adaptersOrParams.gitCommitShaProvider, adaptersOrParams.additionalBackends, adaptersOrParams.replicationQueueService);
         }
-        return new VintaSend(adaptersOrParams, backend, logger, contextGeneratorsMap, queueService, attachmentManager, options, gitCommitShaProvider, additionalBackends);
+        return new VintaSend(adaptersOrParams, backend, logger, contextGeneratorsMap, queueService, attachmentManager, options, gitCommitShaProvider, additionalBackends, replicationQueueService);
     }
 }
 exports.VintaSendFactory = VintaSendFactory;
@@ -35,7 +35,7 @@ class VintaSend {
      */
     constructor(adapters, backend, logger, contextGeneratorsMap, queueService, attachmentManager, options = {
         raiseErrorOnFailedSend: false,
-    }, gitCommitShaProvider, additionalBackends = []) {
+    }, gitCommitShaProvider, additionalBackends = [], replicationQueueService) {
         this.adapters = adapters;
         this.backend = backend;
         this.logger = logger;
@@ -43,6 +43,7 @@ class VintaSend {
         this.attachmentManager = attachmentManager;
         this.options = options;
         this.gitCommitShaProvider = gitCommitShaProvider;
+        this.replicationQueueService = replicationQueueService;
         this.contextGeneratorsMap = new notification_context_generators_map_1.NotificationContextGeneratorsMap(contextGeneratorsMap);
         this.backends = new Map();
         this.primaryBackendIdentifier = this.getBackendIdentifier(backend);
@@ -115,26 +116,97 @@ class VintaSend {
     hasBackend(identifier) {
         return this.backends.has(identifier);
     }
-    async executeMultiBackendWrite(operation, primaryWrite, additionalWrite) {
+    async executeMultiBackendWrite(operation, primaryWrite, additionalWrite, replicationNotificationId) {
         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}`);
+        const additionalBackends = this.getAdditionalBackends();
+        if (additionalBackends.length === 0) {
+            return primaryResult;
+        }
+        const resolveReplicationNotificationId = () => {
+            if (typeof replicationNotificationId === 'function') {
+                return replicationNotificationId(primaryResult);
+            }
+            if (replicationNotificationId !== undefined) {
+                return replicationNotificationId;
+            }
+            const idFromPrimaryResult = primaryResult.id;
+            return idFromPrimaryResult;
+        };
+        const executeInlineReplication = async () => {
+            for (const additionalBackend of additionalBackends) {
+                const backendIdentifier = this.getBackendIdentifier(additionalBackend);
+                try {
+                    await additionalWrite(additionalBackend, primaryResult);
+                    this.logger.info(`${operation} replicated to backend ${backendIdentifier} in inline mode`);
+                }
+                catch (replicationError) {
+                    this.logger.error(`Failed to replicate ${operation} to backend ${backendIdentifier}: ${replicationError}`);
+                }
+            }
+        };
+        if (this.options.replicationMode === 'queued') {
+            const notificationIdToReplicate = resolveReplicationNotificationId();
+            if (!notificationIdToReplicate) {
+                this.logger.warn(`Replication mode is queued, but no notification id was resolved for ${operation}. Falling back to inline replication.`);
+                await executeInlineReplication();
+                return primaryResult;
+            }
+            if (!this.replicationQueueService) {
+                this.logger.warn(`Replication mode is queued, but no replication queue service is registered for ${operation}. Falling back to inline replication.`);
+                await executeInlineReplication();
+                return primaryResult;
+            }
+            const enqueueResults = await Promise.all(additionalBackends.map(async (additionalBackend) => {
+                var _a;
+                const backendIdentifier = this.getBackendIdentifier(additionalBackend);
+                try {
+                    await ((_a = this.replicationQueueService) === null || _a === void 0 ? void 0 : _a.enqueueReplication(notificationIdToReplicate, backendIdentifier));
+                    return {
+                        backendIdentifier,
+                        backend: additionalBackend,
+                        error: null,
+                    };
+                }
+                catch (enqueueReplicationError) {
+                    return {
+                        backendIdentifier,
+                        backend: additionalBackend,
+                        error: String(enqueueReplicationError),
+                    };
+                }
+            }));
+            const failedEnqueues = enqueueResults.filter((enqueueResult) => enqueueResult.error);
+            if (failedEnqueues.length === 0) {
+                this.logger.info(`${operation} replication enqueued for notification ${String(notificationIdToReplicate)} to ${additionalBackends.length} backend(s) in queued mode`);
+                return primaryResult;
+            }
+            for (const failedEnqueue of failedEnqueues) {
+                this.logger.error(`Failed to enqueue replication for ${operation}, notification ${String(notificationIdToReplicate)} and backend ${failedEnqueue.backendIdentifier}: ${failedEnqueue.error}`);
             }
-            catch (replicationError) {
-                this.logger.error(`Failed to replicate ${operation} to backend ${backendIdentifier}: ${replicationError}`);
+            this.logger.warn(`Falling back to inline replication for ${operation} in ${failedEnqueues.length} backend(s) after queue enqueue failure.`);
+            for (const failedEnqueue of failedEnqueues) {
+                try {
+                    await additionalWrite(failedEnqueue.backend, primaryResult);
+                    this.logger.info(`${operation} replicated to backend ${failedEnqueue.backendIdentifier} in inline fallback mode`);
+                }
+                catch (replicationError) {
+                    this.logger.error(`Failed to replicate ${operation} to backend ${failedEnqueue.backendIdentifier} in inline fallback mode: ${replicationError}`);
+                }
             }
+            return primaryResult;
         }
+        await executeInlineReplication();
         return primaryResult;
     }
     registerQueueService(queueService) {
         this.queueService = queueService;
     }
+    registerReplicationQueueService(replicationQueueService) {
+        this.replicationQueueService = replicationQueueService;
+    }
     normalizeGitCommitSha(gitCommitSha) {
         const normalizedSha = gitCommitSha.trim().toLowerCase();
         if (!/^[a-f0-9]{40}$/.test(normalizedSha)) {
@@ -166,7 +238,7 @@ class VintaSend {
                 return backend.persistOneOffNotificationUpdate(notification.id, oneOffNotificationUpdate);
             }, async (backend) => {
                 await backend.persistOneOffNotificationUpdate(notification.id, oneOffNotificationUpdate);
-            });
+            }, notification.id);
         }
         const notificationUpdate = {
             gitCommitSha,
@@ -175,7 +247,7 @@ class VintaSend {
             return backend.persistNotificationUpdate(notification.id, notificationUpdate);
         }, async (backend) => {
             await backend.persistNotificationUpdate(notification.id, notificationUpdate);
-        });
+        }, notification.id);
     }
     async resolveAndPersistGitCommitShaForExecution(notification) {
         const gitCommitSha = await this.resolveGitCommitShaForExecution();
@@ -240,7 +312,7 @@ class VintaSend {
                         return backend.markAsFailed(notificationWithExecutionGitCommitSha.id, true);
                     }, async (backend) => {
                         await backend.markAsFailed(notificationWithExecutionGitCommitSha.id, true);
-                    });
+                    }, notificationWithExecutionGitCommitSha.id);
                 }
                 catch (markFailedError) {
                     this.logger.error(`Error marking notification ${notificationWithExecutionGitCommitSha.id} as failed: ${markFailedError}`);
@@ -252,7 +324,7 @@ class VintaSend {
                     return backend.markAsSent(notificationWithExecutionGitCommitSha.id, true);
                 }, async (backend) => {
                     await backend.markAsSent(notificationWithExecutionGitCommitSha.id, true);
-                });
+                }, notificationWithExecutionGitCommitSha.id);
             }
             catch (markSentError) {
                 this.logger.error(`Error marking notification ${notificationWithExecutionGitCommitSha.id} as sent: ${markSentError}`);
@@ -264,7 +336,7 @@ class VintaSend {
                 }, async (backend) => {
                     var _a;
                     await backend.storeAdapterAndContextUsed(notificationWithExecutionGitCommitSha.id, (_a = adapter.key) !== null && _a !== void 0 ? _a : 'unknown', context !== null && context !== void 0 ? context : {});
-                });
+                }, notificationWithExecutionGitCommitSha.id);
             }
             catch (storeContextError) {
                 this.logger.error(`Error storing adapter and context for notification ${notificationWithExecutionGitCommitSha.id}: ${storeContextError}`);
@@ -295,7 +367,7 @@ class VintaSend {
             return backend.persistNotificationUpdate(notificationId, notification);
         }, async (backend) => {
             await backend.persistNotificationUpdate(notificationId, notification);
-        });
+        }, notificationId);
         this.logger.info(`Notification ${notificationId} updated`);
         return updatedNotification;
     }
@@ -343,7 +415,7 @@ class VintaSend {
             return backend.persistOneOffNotificationUpdate(notificationId, notification);
         }, async (backend) => {
             await backend.persistOneOffNotificationUpdate(notificationId, notification);
-        });
+        }, notificationId);
         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`);
@@ -457,7 +529,7 @@ class VintaSend {
             return backend.markAsRead(notificationId, checkIsSent);
         }, async (backend) => {
             await backend.markAsRead(notificationId, checkIsSent);
-        });
+        }, notificationId);
         this.logger.info(`Notification ${notificationId} marked as read`);
         return notification;
     }
@@ -472,7 +544,7 @@ class VintaSend {
             await backend.cancelNotification(notificationId);
         }, async (backend) => {
             await backend.cancelNotification(notificationId);
-        });
+        }, notificationId);
         this.logger.info(`Notification ${notificationId} cancelled`);
     }
     async resendNotification(notificationId, useStoredContextIfAvailable = false) {
@@ -569,7 +641,7 @@ class VintaSend {
                         return backend.markAsFailed(notificationWithExecutionGitCommitSha.id, true);
                     }, async (backend) => {
                         await backend.markAsFailed(notificationWithExecutionGitCommitSha.id, true);
-                    });
+                    }, notificationWithExecutionGitCommitSha.id);
                 }
                 catch (markFailedError) {
                     this.logger.error(`Error marking notification ${notificationWithExecutionGitCommitSha.id} as failed: ${markFailedError}`);
@@ -580,7 +652,7 @@ class VintaSend {
                     return backend.markAsSent(notificationWithExecutionGitCommitSha.id, true);
                 }, async (backend) => {
                     await backend.markAsSent(notificationWithExecutionGitCommitSha.id, true);
-                });
+                }, notificationWithExecutionGitCommitSha.id);
             }
             catch (markSentError) {
                 this.logger.error(`Error marking notification ${notificationWithExecutionGitCommitSha.id} as sent: ${markSentError}`);
@@ -591,7 +663,7 @@ class VintaSend {
                 await backend.storeAdapterAndContextUsed(notificationWithExecutionGitCommitSha.id, lastAdapterKey, context);
             }, async (backend) => {
                 await backend.storeAdapterAndContextUsed(notificationWithExecutionGitCommitSha.id, lastAdapterKey, context);
-            });
+            }, notificationWithExecutionGitCommitSha.id);
         }
         catch (storeContextError) {
             this.logger.error(`Error storing adapter and context for notification ${notificationWithExecutionGitCommitSha.id}: ${storeContextError}`);
@@ -630,6 +702,13 @@ class VintaSend {
         }
         return String(value);
     }
+    isLikelyDuplicateReplicationConflict(error) {
+        const normalizedError = String(error).toLowerCase();
+        return (normalizedError.includes('duplicate') ||
+            normalizedError.includes('unique') ||
+            normalizedError.includes('already exists') ||
+            normalizedError.includes('conflict'));
+    }
     /**
      * Verifies whether a notification is synchronized across all configured backends.
      *
@@ -710,12 +789,11 @@ class VintaSend {
         return report;
     }
     /**
-     * Replicates one notification from the primary backend to all additional backends.
+     * Worker-facing replication entrypoint.
      *
-     * If a notification already exists in an additional backend, it is updated.
-     * Otherwise, it is created.
+     * Reads the notification from the primary backend and upserts into additional backends.
      */
-    async replicateNotification(notificationId) {
+    async processReplication(notificationId, targetBackendIdentifier) {
         const primaryNotification = await this.backend.getNotification(notificationId, false);
         if (!primaryNotification) {
             throw new Error(`Notification ${String(notificationId)} not found in primary backend`);
@@ -724,27 +802,83 @@ class VintaSend {
             successes: [],
             failures: [],
         };
-        for (const backend of this.getAdditionalBackends()) {
-            const backendIdentifier = this.getBackendIdentifier(backend);
+        const replicationTargets = this.getAdditionalBackends()
+            .map((backend) => {
+            return {
+                backend,
+                backendIdentifier: this.getBackendIdentifier(backend),
+            };
+        })
+            .filter(({ backendIdentifier }) => {
+            if (!targetBackendIdentifier) {
+                return true;
+            }
+            return backendIdentifier === targetBackendIdentifier;
+        });
+        if (targetBackendIdentifier && replicationTargets.length === 0) {
+            throw new Error(`Additional backend not found: ${targetBackendIdentifier}`);
+        }
+        const replicationTaskResults = await Promise.all(replicationTargets.map(async ({ backend, backendIdentifier }) => {
             try {
+                if (typeof backend.applyReplicationSnapshotIfNewer === 'function') {
+                    const conditionalApplyResult = await backend.applyReplicationSnapshotIfNewer(primaryNotification);
+                    if (!conditionalApplyResult.applied) {
+                        this.logger.info(`Skipped replication for notification ${String(notificationId)} on backend ${backendIdentifier} because destination state is newer or equal`);
+                    }
+                    return {
+                        backendIdentifier,
+                        error: null,
+                    };
+                }
                 const existingNotification = await backend.getNotification(notificationId, false);
                 if (existingNotification) {
                     await backend.persistNotificationUpdate(notificationId, primaryNotification);
                 }
                 else {
-                    await backend.persistNotification(primaryNotification);
+                    try {
+                        await backend.persistNotification(primaryNotification);
+                    }
+                    catch (createError) {
+                        if (!this.isLikelyDuplicateReplicationConflict(createError)) {
+                            throw createError;
+                        }
+                        this.logger.warn(`Detected duplicate replication create on backend ${backendIdentifier} for notification ${String(notificationId)}. Retrying as update for idempotency.`);
+                        await backend.persistNotificationUpdate(notificationId, primaryNotification);
+                    }
                 }
-                result.successes.push(backendIdentifier);
+                return {
+                    backendIdentifier,
+                    error: null,
+                };
             }
             catch (error) {
-                result.failures.push({
-                    backend: backendIdentifier,
+                return {
+                    backendIdentifier,
                     error: String(error),
+                };
+            }
+        }));
+        for (const taskResult of replicationTaskResults) {
+            if (taskResult.error) {
+                result.failures.push({
+                    backend: taskResult.backendIdentifier,
+                    error: taskResult.error,
                 });
+                continue;
             }
+            result.successes.push(taskResult.backendIdentifier);
         }
         return result;
     }
+    /**
+     * 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) {
+        return this.processReplication(notificationId);
+    }
     /**
      * Returns a lightweight health snapshot for each configured backend.
      */

package/package.json

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