vintasend 0.6.2 → 0.7.1

package/README.md

@@ -244,8 +244,92 @@ One-off notifications are stored in the same table as regular notifications usin
 - **Regular notifications**: Have `userId` set, `emailOrPhone` is null
 - **One-off notifications**: Have `emailOrPhone` set, `userId` is null
 
+## Git Commit SHA Tracking
+
+VintaSend can persist which source-code version executed each notification send/render flow.
+
+### Field behavior
+
+- Persisted notifications include `gitCommitSha: string | null`
+- Notification input/resend payloads do not accept this field (`gitCommitSha` is system-managed)
+- The SHA is resolved at execution time (send/render), not creation time
+
+### Configuring a provider
+
+Use `BaseGitCommitShaProvider` with `VintaSendFactory.create(...)`.
+
+Preferred factory style (object parameter):
+
+```typescript
+import { VintaSendFactory, type BaseGitCommitShaProvider } from 'vintasend';
+
+const gitCommitShaProvider: BaseGitCommitShaProvider = {
+  getCurrentGitCommitSha: () => process.env.GIT_COMMIT_SHA ?? null,
+};
+
+const vintaSend = new VintaSendFactory<NotificationTypeConfig>().create({
+  adapters: [adapter],
+  backend,
+  logger,
+  contextGeneratorsMap,
+  gitCommitShaProvider,
+});
+```
+
+> Positional `create(...)` parameters are still supported for backward compatibility, but object-style configuration is recommended.
+
+### Provider examples
+
+Environment variable (CI/CD injected):
+
+```typescript
+const envProvider: BaseGitCommitShaProvider = {
+  getCurrentGitCommitSha: () => process.env.GIT_COMMIT_SHA ?? null,
+};
+```
+
+Shell command (async):
+
+```typescript
+import { execSync } from 'node:child_process';
+
+const shellProvider: BaseGitCommitShaProvider = {
+  getCurrentGitCommitSha: async () => {
+    try {
+      return execSync('git rev-parse HEAD', { encoding: 'utf-8' }).trim() || null;
+    } catch {
+      return null;
+    }
+  },
+};
+```
+
+Static provider (for deterministic environments):
+
+```typescript
+const staticProvider: BaseGitCommitShaProvider = {
+  getCurrentGitCommitSha: () => '0123456789abcdef0123456789abcdef01234567',
+};
+```
+
 ### Migration Guides
 
+#### Migrating to v0.7.0 (Git Commit SHA Tracking)
+
+This migration is only needed if you're using the Prisma backend.
+
+`gitCommitSha` is now persisted on notifications (regular and one-off) as a nullable, system-managed field.
+
+1. Update your Prisma schema (`Notification` model):
+  - Add `gitCommitSha String?`
+  - Add `@@index([gitCommitSha])`
+2. Run a migration in your app:
+  ```bash
+  prisma migrate dev --name add-notification-git-commit-sha
+  ```
+3. Optionally configure a `BaseGitCommitShaProvider` in `VintaSendFactory`.
+4. Do not add `gitCommitSha` to notification create/resend input payloads (it is provider-managed).
+
 #### Migrating to v0.4.0 (Attachment Support)
 
 Version 0.4.0 introduces file attachment support with a **breaking change** to the `VintaSendFactory.create()` method signature.

package/dist/index.d.ts

@@ -1,10 +1,11 @@
 export { BaseAttachmentManager } from './services/attachment-manager/base-attachment-manager';
 export type { LocalFileAttachmentManagerConfig } from './services/attachment-manager/local-file-attachment-manager';
 export { LocalFileAttachmentManager } from './services/attachment-manager/local-file-attachment-manager';
+export type { BaseGitCommitShaProvider } from './services/git-commit-sha/base-git-commit-sha-provider';
 export { BaseNotificationAdapter, isOneOffNotification, } from './services/notification-adapters/base-notification-adapter';
 export type { BaseNotificationBackend } from './services/notification-backends/base-notification-backend';
 export { supportsAttachments, isFieldFilter } from './services/notification-backends/base-notification-backend';
-export type { NotificationFilter, NotificationFilterFields, DateRange, NotificationFilterCapabilities } 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 { VintaSend } from './services/notification-service';
 export { VintaSendFactory } from './services/notification-service';

package/dist/index.js

@@ -6,6 +6,7 @@ var base_attachment_manager_1 = require("./services/attachment-manager/base-atta
 Object.defineProperty(exports, "BaseAttachmentManager", { enumerable: true, get: function () { return base_attachment_manager_1.BaseAttachmentManager; } });
 var local_file_attachment_manager_1 = require("./services/attachment-manager/local-file-attachment-manager");
 Object.defineProperty(exports, "LocalFileAttachmentManager", { enumerable: true, get: function () { return local_file_attachment_manager_1.LocalFileAttachmentManager; } });
+// Notification Adapters and Backends
 var base_notification_adapter_1 = require("./services/notification-adapters/base-notification-adapter");
 Object.defineProperty(exports, "BaseNotificationAdapter", { enumerable: true, get: function () { return base_notification_adapter_1.BaseNotificationAdapter; } });
 Object.defineProperty(exports, "isOneOffNotification", { enumerable: true, get: function () { return base_notification_adapter_1.isOneOffNotification; } });

package/dist/services/git-commit-sha/base-git-commit-sha-provider.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Base interface for Git commit SHA providers.
+ *
+ * Implementations of this interface can resolve the current Git commit SHA
+ * at runtime, allowing VintaSend to automatically track which version of code
+ * produced each notification render.
+ *
+ * @example
+ * ```typescript
+ * // Environment variable provider
+ * class EnvGitCommitShaProvider implements BaseGitCommitShaProvider {
+ *   getCurrentGitCommitSha(): string | null {
+ *     return process.env.GIT_COMMIT_SHA || null;
+ *   }
+ * }
+ *
+ * // Shell command provider (for development)
+ * class ShellGitCommitShaProvider implements BaseGitCommitShaProvider {
+ *   async getCurrentGitCommitSha(): Promise<string | null> {
+ *     try {
+ *       const { execSync } = require('child_process');
+ *       const sha = execSync('git rev-parse HEAD', { encoding: 'utf-8' }).trim();
+ *       return sha || null;
+ *     } catch {
+ *       return null;
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export interface BaseGitCommitShaProvider {
+    /**
+     * Resolve the current Git commit SHA.
+     *
+     * Must return:
+     * - Full 40-character hex SHA (will be normalized to lowercase)
+     * - null if SHA cannot be determined
+     *
+     * May return synchronously or asynchronously.
+     * Invalid SHA formats will be rejected at notification creation boundary.
+     *
+     * @returns The current Git commit SHA, or null if unavailable
+     */
+    getCurrentGitCommitSha(): string | Promise<string | null> | null;
+}

package/dist/services/git-commit-sha/base-git-commit-sha-provider.js

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

package/dist/services/git-commit-sha/index.d.ts

@@ -0,0 +1 @@
+export type { BaseGitCommitShaProvider } from './base-git-commit-sha-provider';

package/dist/services/git-commit-sha/index.js

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

package/dist/services/notification-adapters/base-notification-adapter.d.ts

@@ -1,8 +1,9 @@
 import type { StoredAttachment } from '../../types/attachment';
-import type { JsonValue } from '../../types/json-values';
+import type { JsonObject, JsonValue } from '../../types/json-values';
 import type { AnyDatabaseNotification, DatabaseOneOffNotification } from '../../types/notification';
 import type { NotificationType } from '../../types/notification-type';
 import type { BaseNotificationTypeConfig } from '../../types/notification-type-config';
+import type { EmailTemplate, EmailTemplateContent } from '../notification-template-renderers/base-email-template-renderer';
 import type { BaseLogger } from '../loggers/base-logger';
 import type { BaseNotificationBackend } from '../notification-backends/base-notification-backend';
 import type { BaseNotificationTemplateRenderer } from '../notification-template-renderers/base-notification-template-renderer';
@@ -45,4 +46,5 @@ export declare abstract class BaseNotificationAdapter<TemplateRenderer extends B
     };
     injectBackend(backend: BaseNotificationBackend<Config>): void;
     injectLogger(logger: BaseLogger): void;
+    renderFromTemplateContent(notification: AnyDatabaseNotification<Config>, templateContent: EmailTemplateContent, context: JsonObject): Promise<EmailTemplate>;
 }

package/dist/services/notification-adapters/base-notification-adapter.js

@@ -90,5 +90,12 @@ class BaseNotificationAdapter {
     injectLogger(logger) {
         this.logger = logger;
     }
+    async renderFromTemplateContent(notification, templateContent, context) {
+        if (typeof this.templateRenderer.renderFromTemplateContent !== 'function') {
+            throw new Error('Template renderer does not support renderFromTemplateContent.');
+        }
+        const rendered = await this.templateRenderer.renderFromTemplateContent(notification, templateContent, context);
+        return rendered;
+    }
 }
 exports.BaseNotificationAdapter = BaseNotificationAdapter;

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

@@ -12,6 +12,12 @@ export type DateRange = {
     from?: Date;
     to?: Date;
 };
+export type StringFilterLookup = {
+    lookup: 'exact' | 'startsWith' | 'endsWith' | 'includes';
+    value: string;
+    caseSensitive?: boolean;
+};
+export type StringFieldFilter = string | StringFilterLookup;
 /**
  * Flat dotted key capability map describing which filter features a backend supports.
  * Use flat dotted keys for logical operators, fields, and negations:
@@ -35,9 +41,9 @@ export type NotificationFilterFields<Config extends BaseNotificationTypeConfig>
     notificationType?: NotificationType | NotificationType[];
     adapterUsed?: string | string[];
     userId?: Config['UserIdType'];
-    bodyTemplate?: string;
-    subjectTemplate?: string;
-    contextName?: string;
+    bodyTemplate?: StringFieldFilter;
+    subjectTemplate?: StringFieldFilter;
+    contextName?: StringFieldFilter;
     sendAfterRange?: DateRange;
     createdAtRange?: DateRange;
     sentAtRange?: DateRange;
@@ -75,6 +81,10 @@ export declare const DEFAULT_BACKEND_FILTER_CAPABILITIES: {
     'negation.sendAfterRange': boolean;
     'negation.createdAtRange': boolean;
     'negation.sentAtRange': boolean;
+    'stringLookups.startsWith': boolean;
+    'stringLookups.endsWith': boolean;
+    'stringLookups.includes': boolean;
+    'stringLookups.caseInsensitive': boolean;
 };
 export interface BaseNotificationBackend<Config extends BaseNotificationTypeConfig> {
     getAllPendingNotifications(): Promise<AnyDatabaseNotification<Config>[]>;
@@ -178,6 +188,7 @@ export interface BaseNotificationBackend<Config extends BaseNotificationTypeConf
  * Type guard to check if a filter is a field filter (leaf node).
  */
 export declare function isFieldFilter<Config extends BaseNotificationTypeConfig>(filter: NotificationFilter<Config>): filter is NotificationFilterFields<Config>;
+export declare function isStringFilterLookup(value: StringFieldFilter): value is StringFilterLookup;
 /**
  * Type guard to check if backend supports attachment operations
  */

package/dist/services/notification-backends/base-notification-backend.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DEFAULT_BACKEND_FILTER_CAPABILITIES = void 0;
 exports.isFieldFilter = isFieldFilter;
+exports.isStringFilterLookup = isStringFilterLookup;
 exports.supportsAttachments = supportsAttachments;
 exports.DEFAULT_BACKEND_FILTER_CAPABILITIES = {
     'logical.and': true,
@@ -21,6 +22,10 @@ exports.DEFAULT_BACKEND_FILTER_CAPABILITIES = {
     'negation.sendAfterRange': true,
     'negation.createdAtRange': true,
     'negation.sentAtRange': true,
+    'stringLookups.startsWith': true,
+    'stringLookups.endsWith': true,
+    'stringLookups.includes': true,
+    'stringLookups.caseInsensitive': true,
 };
 /**
  * Type guard to check if a filter is a field filter (leaf node).
@@ -28,6 +33,9 @@ exports.DEFAULT_BACKEND_FILTER_CAPABILITIES = {
 function isFieldFilter(filter) {
     return !('and' in filter) && !('or' in filter) && !('not' in filter);
 }
+function isStringFilterLookup(value) {
+    return typeof value === 'object' && value !== null && 'lookup' in value && 'value' in value;
+}
 /**
  * Type guard to check if backend supports attachment operations
  */

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

@@ -3,14 +3,32 @@ import type { AnyDatabaseNotification, AnyNotification, DatabaseNotification, Da
 import type { BaseNotificationTypeConfig } from '../types/notification-type-config';
 import type { OneOffNotificationInput } from '../types/one-off-notification';
 import type { BaseAttachmentManager } from './attachment-manager/base-attachment-manager';
+import type { BaseGitCommitShaProvider } from './git-commit-sha/base-git-commit-sha-provider';
 import type { BaseLogger } from './loggers/base-logger';
 import { type BaseNotificationAdapter } from './notification-adapters/base-notification-adapter';
 import { type BaseNotificationBackend, type NotificationFilterFields } from './notification-backends/base-notification-backend';
 import type { BaseNotificationQueueService } from './notification-queue-service/base-notification-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;
 };
+type RenderEmailTemplateContextInput<Config extends BaseNotificationTypeConfig> = {
+    context: JsonObject;
+} | {
+    contextName: string & keyof Config['ContextMap'];
+    contextParameters: JsonObject;
+};
+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;
+    logger: Logger;
+    contextGeneratorsMap: BaseNotificationTypeConfig['ContextMap'];
+    queueService?: QueueService;
+    attachmentManager?: AttachmentMgr;
+    options?: VintaSendOptions;
+    gitCommitShaProvider?: BaseGitCommitShaProvider;
+};
 export declare class VintaSendFactory<Config extends BaseNotificationTypeConfig> {
     /**
      * Creates a new VintaSend notification service instance
@@ -38,7 +56,11 @@ export declare class VintaSendFactory<Config extends BaseNotificationTypeConfig>
      * @since v0.4.0 - BREAKING CHANGE: attachmentManager parameter added before options
      * @see https://github.com/vintasoftware/vintasend-ts/blob/main/README.md#migrating-to-v040-attachment-support
      */
-    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): 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>(params: VintaSendFactoryCreateParams<Config, AdaptersList, Backend, Logger, QueueService, AttachmentMgr>): VintaSend<Config, AdaptersList, Backend, Logger, QueueService, AttachmentMgr>;
+    /**
+     * @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>;
 }
 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;
@@ -47,9 +69,14 @@ export declare class VintaSend<Config extends BaseNotificationTypeConfig, Adapte
     private queueService?;
     private attachmentManager?;
     private options;
+    private gitCommitShaProvider?;
     private contextGeneratorsMap;
-    constructor(adapters: AdaptersList, backend: Backend, logger: Logger, contextGeneratorsMap: Config['ContextMap'], queueService?: QueueService | undefined, attachmentManager?: AttachmentMgr | undefined, options?: VintaSendOptions);
+    constructor(adapters: AdaptersList, backend: Backend, logger: Logger, contextGeneratorsMap: Config['ContextMap'], queueService?: QueueService | undefined, attachmentManager?: AttachmentMgr | undefined, options?: VintaSendOptions, gitCommitShaProvider?: BaseGitCommitShaProvider | undefined);
     registerQueueService(queueService: QueueService): void;
+    private normalizeGitCommitSha;
+    private resolveGitCommitShaForExecution;
+    private persistGitCommitShaForExecution;
+    private resolveAndPersistGitCommitShaForExecution;
     send(notification: AnyDatabaseNotification<Config>): Promise<void>;
     createNotification(notification: Omit<Notification<Config>, 'id'>): Promise<DatabaseNotification<Config>>;
     updateNotification(notificationId: Config['NotificationIdType'], notification: Partial<Omit<Notification<Config>, 'id'>>): Promise<DatabaseNotification<Config>>;
@@ -81,6 +108,7 @@ export declare class VintaSend<Config extends BaseNotificationTypeConfig, Adapte
     getFutureNotificationsFromUser(userId: Config['NotificationIdType'], page: number, pageSize: number): Promise<DatabaseNotification<Config>[]>;
     getFutureNotifications(page: number, pageSize: number): 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>[]>;
@@ -105,6 +133,10 @@ export declare class VintaSend<Config extends BaseNotificationTypeConfig, Adapte
         'negation.sendAfterRange': boolean;
         'negation.createdAtRange': boolean;
         'negation.sentAtRange': boolean;
+        'stringLookups.startsWith': boolean;
+        'stringLookups.endsWith': boolean;
+        'stringLookups.includes': boolean;
+        'stringLookups.caseInsensitive': boolean;
     }>;
     /**
      * Gets a one-off notification by ID.

package/dist/services/notification-service.js

@@ -5,36 +5,16 @@ const base_notification_adapter_1 = require("./notification-adapters/base-notifi
 const base_notification_backend_1 = require("./notification-backends/base-notification-backend");
 const notification_context_generators_map_1 = require("./notification-context-generators-map");
 class VintaSendFactory {
-    /**
-     * Creates a new VintaSend notification service instance
-     *
-     * @param adapters - Array of notification adapters (email, SMS, push, etc.)
-     * @param backend - Notification storage backend
-     * @param logger - Logger instance
-     * @param contextGeneratorsMap - Map of context generators for notification rendering
-     * @param queueService - Optional queue service for background notification processing
-     * @param attachmentManager - Optional attachment manager for file handling
-     * @param options - Optional configuration options
-     *
-     * @example
-     * // Without attachments or options
-     * factory.create(adapters, backend, logger, contextGeneratorsMap);
-     *
-     * @example
-     * // With queue service and options (note: pass undefined for attachmentManager)
-     * factory.create(adapters, backend, logger, contextGeneratorsMap, queueService, undefined, { raiseErrorOnFailedSend: true });
-     *
-     * @example
-     * // With attachments and options
-     * factory.create(adapters, backend, logger, contextGeneratorsMap, queueService, attachmentManager, { raiseErrorOnFailedSend: true });
-     *
-     * @since v0.4.0 - BREAKING CHANGE: attachmentManager parameter added before options
-     * @see https://github.com/vintasoftware/vintasend-ts/blob/main/README.md#migrating-to-v040-attachment-support
-     */
-    create(adapters, backend, logger, contextGeneratorsMap, queueService, attachmentManager, options = {
+    create(adaptersOrParams, backend, logger, contextGeneratorsMap, queueService, attachmentManager, options = {
         raiseErrorOnFailedSend: false,
-    }) {
-        return new VintaSend(adapters, backend, logger, contextGeneratorsMap, queueService, attachmentManager, options);
+    }, gitCommitShaProvider) {
+        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);
+        }
+        return new VintaSend(adaptersOrParams, backend, logger, contextGeneratorsMap, queueService, attachmentManager, options, gitCommitShaProvider);
     }
 }
 exports.VintaSendFactory = VintaSendFactory;
@@ -47,13 +27,14 @@ function hasAttachmentManagerInjection(backend) {
 class VintaSend {
     constructor(adapters, backend, logger, contextGeneratorsMap, queueService, attachmentManager, options = {
         raiseErrorOnFailedSend: false,
-    }) {
+    }, gitCommitShaProvider) {
         this.adapters = adapters;
         this.backend = backend;
         this.logger = logger;
         this.queueService = queueService;
         this.attachmentManager = attachmentManager;
         this.options = options;
+        this.gitCommitShaProvider = gitCommitShaProvider;
         this.contextGeneratorsMap = new notification_context_generators_map_1.NotificationContextGeneratorsMap(contextGeneratorsMap);
         for (const adapter of adapters) {
             adapter.injectBackend(backend);
@@ -77,17 +58,56 @@ class VintaSend {
     registerQueueService(queueService) {
         this.queueService = queueService;
     }
+    normalizeGitCommitSha(gitCommitSha) {
+        const normalizedSha = gitCommitSha.trim().toLowerCase();
+        if (!/^[a-f0-9]{40}$/.test(normalizedSha)) {
+            throw new Error('Invalid gitCommitSha resolved by provider. Expected a 40-character hexadecimal SHA.');
+        }
+        return normalizedSha;
+    }
+    async resolveGitCommitShaForExecution() {
+        if (!this.gitCommitShaProvider) {
+            return null;
+        }
+        const resolvedGitCommitSha = await this.gitCommitShaProvider.getCurrentGitCommitSha();
+        if (resolvedGitCommitSha === null) {
+            return null;
+        }
+        return this.normalizeGitCommitSha(resolvedGitCommitSha);
+    }
+    async persistGitCommitShaForExecution(notification, gitCommitSha) {
+        var _a;
+        const currentGitCommitSha = (_a = notification.gitCommitSha) !== null && _a !== void 0 ? _a : null;
+        if (currentGitCommitSha === gitCommitSha) {
+            return notification;
+        }
+        if ((0, base_notification_adapter_1.isOneOffNotification)(notification)) {
+            const oneOffNotificationUpdate = {
+                gitCommitSha,
+            };
+            return this.backend.persistOneOffNotificationUpdate(notification.id, oneOffNotificationUpdate);
+        }
+        const notificationUpdate = {
+            gitCommitSha,
+        };
+        return this.backend.persistNotificationUpdate(notification.id, notificationUpdate);
+    }
+    async resolveAndPersistGitCommitShaForExecution(notification) {
+        const gitCommitSha = await this.resolveGitCommitShaForExecution();
+        return this.persistGitCommitShaForExecution(notification, gitCommitSha);
+    }
     async send(notification) {
         var _a;
-        const adaptersOfType = this.adapters.filter((adapter) => adapter.notificationType === notification.notificationType);
+        const notificationWithExecutionGitCommitSha = await this.resolveAndPersistGitCommitShaForExecution(notification);
+        const adaptersOfType = this.adapters.filter((adapter) => adapter.notificationType === notificationWithExecutionGitCommitSha.notificationType);
         if (adaptersOfType.length === 0) {
-            this.logger.error(`No adapter found for notification type ${notification.notificationType}`);
+            this.logger.error(`No adapter found for notification type ${notificationWithExecutionGitCommitSha.notificationType}`);
             if (this.options.raiseErrorOnFailedSend) {
-                throw new Error(`No adapter found for notification type ${notification.notificationType}`);
+                throw new Error(`No adapter found for notification type ${notificationWithExecutionGitCommitSha.notificationType}`);
             }
             return;
         }
-        if (!notification.id) {
+        if (!notificationWithExecutionGitCommitSha.id) {
             throw new Error("Notification wasn't created in the database. Please create it first");
         }
         for (const adapter of adaptersOfType) {
@@ -97,27 +117,27 @@ class VintaSend {
                     continue;
                 }
                 try {
-                    this.logger.info(`Enqueuing notification ${notification.id} with adapter ${adapter.key}`);
-                    await this.queueService.enqueueNotification(notification.id);
-                    this.logger.info(`Enqueued notification ${notification.id} with adapter ${adapter.key} successfully`);
+                    this.logger.info(`Enqueuing notification ${notificationWithExecutionGitCommitSha.id} with adapter ${adapter.key}`);
+                    await this.queueService.enqueueNotification(notificationWithExecutionGitCommitSha.id);
+                    this.logger.info(`Enqueued notification ${notificationWithExecutionGitCommitSha.id} with adapter ${adapter.key} successfully`);
                     continue;
                 }
                 catch (enqueueError) {
-                    this.logger.error(`Error enqueuing notification ${notification.id}: ${enqueueError} with adapter ${adapter.key}`);
+                    this.logger.error(`Error enqueuing notification ${notificationWithExecutionGitCommitSha.id}: ${enqueueError} with adapter ${adapter.key}`);
                     continue;
                 }
             }
             let context = null;
-            if (notification.contextUsed) {
-                context = notification.contextUsed;
+            if (notificationWithExecutionGitCommitSha.contextUsed) {
+                context = notificationWithExecutionGitCommitSha.contextUsed;
             }
             else {
                 try {
-                    context = await this.getNotificationContext(notification.contextName, notification.contextParameters);
-                    this.logger.info(`Generated context for notification ${notification.id}`);
+                    context = await this.getNotificationContext(notificationWithExecutionGitCommitSha.contextName, notificationWithExecutionGitCommitSha.contextParameters);
+                    this.logger.info(`Generated context for notification ${notificationWithExecutionGitCommitSha.id}`);
                 }
                 catch (contextError) {
-                    this.logger.error(`Error getting context for notification ${notification.id}: ${contextError}`);
+                    this.logger.error(`Error getting context for notification ${notificationWithExecutionGitCommitSha.id}: ${contextError}`);
                     if (this.options.raiseErrorOnFailedSend) {
                         throw contextError;
                     }
@@ -125,31 +145,31 @@ class VintaSend {
                 }
             }
             try {
-                this.logger.info(`Sending notification ${notification.id} with adapter ${adapter.key}`);
-                await adapter.send(notification, context);
-                this.logger.info(`Sent notification ${notification.id} with adapter ${adapter.key} successfully`);
+                this.logger.info(`Sending notification ${notificationWithExecutionGitCommitSha.id} with adapter ${adapter.key}`);
+                await adapter.send(notificationWithExecutionGitCommitSha, context);
+                this.logger.info(`Sent notification ${notificationWithExecutionGitCommitSha.id} with adapter ${adapter.key} successfully`);
             }
             catch (sendError) {
-                this.logger.error(`Error sending notification ${notification.id} with adapter ${adapter.key}: ${sendError}`);
+                this.logger.error(`Error sending notification ${notificationWithExecutionGitCommitSha.id} with adapter ${adapter.key}: ${sendError}`);
                 try {
-                    await this.backend.markAsFailed(notification.id, true);
+                    await this.backend.markAsFailed(notificationWithExecutionGitCommitSha.id, true);
                 }
                 catch (markFailedError) {
-                    this.logger.error(`Error marking notification ${notification.id} as failed: ${markFailedError}`);
+                    this.logger.error(`Error marking notification ${notificationWithExecutionGitCommitSha.id} as failed: ${markFailedError}`);
                 }
                 continue;
             }
             try {
-                await this.backend.markAsSent(notification.id, true);
+                await this.backend.markAsSent(notificationWithExecutionGitCommitSha.id, true);
             }
             catch (markSentError) {
-                this.logger.error(`Error marking notification ${notification.id} as sent: ${markSentError}`);
+                this.logger.error(`Error marking notification ${notificationWithExecutionGitCommitSha.id} as sent: ${markSentError}`);
             }
             try {
-                await this.backend.storeAdapterAndContextUsed(notification.id, (_a = adapter.key) !== null && _a !== void 0 ? _a : 'unknown', context !== null && context !== void 0 ? context : {});
+                await this.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 ${notification.id}: ${storeContextError}`);
+                this.logger.error(`Error storing adapter and context for notification ${notificationWithExecutionGitCommitSha.id}: ${storeContextError}`);
             }
         }
     }
@@ -249,6 +269,17 @@ class VintaSend {
         }
         return Promise.resolve(context);
     }
+    async renderEmailTemplateFromContent(notification, templateContent, contextInput) {
+        const adaptersOfType = this.adapters.filter((adapter) => adapter.notificationType === notification.notificationType);
+        if (adaptersOfType.length === 0) {
+            throw new Error(`No adapter found for notification type ${notification.notificationType}`);
+        }
+        const adapter = adaptersOfType[0];
+        const context = 'context' in contextInput
+            ? contextInput.context
+            : await this.getNotificationContext(contextInput.contextName, contextInput.contextParameters);
+        return adapter.renderFromTemplateContent(notification, templateContent, context);
+    }
     async sendPendingNotifications() {
         const pendingNotifications = await this.backend.getAllPendingNotifications();
         await Promise.all(pendingNotifications.map((notification) => this.send(notification)));
@@ -373,34 +404,35 @@ class VintaSend {
             }
             return;
         }
-        const context = await this.getNotificationContext(notification.contextName, notification.contextParameters);
+        const notificationWithExecutionGitCommitSha = await this.resolveAndPersistGitCommitShaForExecution(notification);
+        const context = await this.getNotificationContext(notificationWithExecutionGitCommitSha.contextName, notificationWithExecutionGitCommitSha.contextParameters);
         let lastAdapterKey = 'unknown';
         for (const adapter of enqueueNotificationsAdapters) {
             lastAdapterKey = (_a = adapter.key) !== null && _a !== void 0 ? _a : 'unknown';
             try {
-                await adapter.send(notification, context);
+                await adapter.send(notificationWithExecutionGitCommitSha, context);
             }
             catch (sendError) {
-                this.logger.error(`Error sending notification ${notification.id} with adapter ${adapter.key}: ${sendError}`);
+                this.logger.error(`Error sending notification ${notificationWithExecutionGitCommitSha.id} with adapter ${adapter.key}: ${sendError}`);
                 try {
-                    await this.backend.markAsFailed(notification.id, true);
+                    await this.backend.markAsFailed(notificationWithExecutionGitCommitSha.id, true);
                 }
                 catch (markFailedError) {
-                    this.logger.error(`Error marking notification ${notification.id} as failed: ${markFailedError}`);
+                    this.logger.error(`Error marking notification ${notificationWithExecutionGitCommitSha.id} as failed: ${markFailedError}`);
                 }
             }
             try {
-                await this.backend.markAsSent(notification.id, true);
+                await this.backend.markAsSent(notificationWithExecutionGitCommitSha.id, true);
             }
             catch (markSentError) {
-                this.logger.error(`Error marking notification ${notification.id} as sent: ${markSentError}`);
+                this.logger.error(`Error marking notification ${notificationWithExecutionGitCommitSha.id} as sent: ${markSentError}`);
             }
         }
         try {
-            await this.backend.storeAdapterAndContextUsed(notification.id, lastAdapterKey, context);
+            await this.backend.storeAdapterAndContextUsed(notificationWithExecutionGitCommitSha.id, lastAdapterKey, context);
         }
         catch (storeContextError) {
-            this.logger.error(`Error storing adapter and context for notification ${notification.id}: ${storeContextError}`);
+            this.logger.error(`Error storing adapter and context for notification ${notificationWithExecutionGitCommitSha.id}: ${storeContextError}`);
         }
     }
     async bulkPersistNotifications(notifications) {

package/dist/services/notification-template-renderers/base-email-template-renderer.d.ts

@@ -9,8 +9,13 @@ export type EmailTemplate = {
     subject: string;
     body: string;
 };
+export type EmailTemplateContent = {
+    subject: string | null;
+    body: string;
+};
 export interface BaseEmailTemplateRenderer<Config extends BaseNotificationTypeConfig> extends BaseNotificationTemplateRenderer<Config, EmailTemplate> {
     render(notification: AnyNotification<Config>, context: JsonObject): Promise<EmailTemplate>;
+    renderFromTemplateContent(notification: AnyNotification<Config>, templateContent: EmailTemplateContent, context: JsonObject): Promise<EmailTemplate>;
     /**
      * Inject logger into the template renderer (optional - called by VintaSend when logger exists)
      */

package/dist/services/notification-template-renderers/base-notification-template-renderer.d.ts

@@ -3,4 +3,5 @@ import type { AnyNotification } from '../../types/notification';
 import type { BaseNotificationTypeConfig } from '../../types/notification-type-config';
 export interface BaseNotificationTemplateRenderer<Config extends BaseNotificationTypeConfig, T = unknown> {
     render(notification: AnyNotification<Config>, context: JsonObject): Promise<T>;
+    renderFromTemplateContent(notification: AnyNotification<Config>, templateContent: unknown, context: JsonObject): Promise<T>;
 }

package/dist/types/notification.d.ts

@@ -15,6 +15,7 @@ export type NotificationInput<Config extends BaseNotificationTypeConfig> = {
     sendAfter: Date | null;
     subjectTemplate: string | null;
     extraParams: InputJsonValue | null;
+    gitCommitSha?: never;
     attachments?: NotificationAttachment[];
 };
 export type NotificationResendWithContextInput<Config extends BaseNotificationTypeConfig> = {
@@ -28,6 +29,7 @@ export type NotificationResendWithContextInput<Config extends BaseNotificationTy
     sendAfter: Date | null;
     subjectTemplate: string | null;
     extraParams: InputJsonValue | null;
+    gitCommitSha?: never;
     attachments?: NotificationAttachment[];
 };
 export type DatabaseNotification<Config extends BaseNotificationTypeConfig> = {
@@ -48,6 +50,7 @@ export type DatabaseNotification<Config extends BaseNotificationTypeConfig> = {
     readAt: Date | null;
     createdAt?: Date;
     updatedAt?: Date;
+    gitCommitSha: string | null;
     attachments?: StoredAttachment[];
 };
 export type Notification<Config extends BaseNotificationTypeConfig> = NotificationInput<Config> | NotificationResendWithContextInput<Config> | DatabaseNotification<Config>;

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

@@ -19,6 +19,7 @@ export type OneOffNotificationInput<Config extends BaseNotificationTypeConfig> =
     sendAfter: Date | null;
     subjectTemplate: string | null;
     extraParams: InputJsonValue | null;
+    gitCommitSha?: never;
     attachments?: NotificationAttachment[];
 };
 /**
@@ -38,6 +39,7 @@ export type OneOffNotificationResendWithContextInput<Config extends BaseNotifica
     sendAfter: Date | null;
     subjectTemplate: string | null;
     extraParams: InputJsonValue | null;
+    gitCommitSha?: never;
     attachments?: NotificationAttachment[];
 };
 /**
@@ -64,6 +66,7 @@ export type DatabaseOneOffNotification<Config extends BaseNotificationTypeConfig
     readAt: Date | null;
     createdAt?: Date;
     updatedAt?: Date;
+    gitCommitSha: string | null;
     attachments?: StoredAttachment[];
 };
 /**

package/package.json

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