vintasend 0.2.3 → 0.4.0

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

@@ -1,6 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.BaseNotificationAdapter = void 0;
+exports.isOneOffNotification = isOneOffNotification;
+/**
+ * Type guard to check if a notification is a one-off notification
+ */
+function isOneOffNotification(notification) {
+    return ('emailOrPhone' in notification && 'firstName' in notification && 'lastName' in notification);
+}
 class BaseNotificationAdapter {
     constructor(templateRenderer, notificationType, enqueueNotifications) {
         this.templateRenderer = templateRenderer;
@@ -8,18 +15,80 @@ class BaseNotificationAdapter {
         this.enqueueNotifications = enqueueNotifications;
         this.key = null;
         this.backend = null;
+        this.logger = null;
     }
-    ;
-    send(notification, context) {
+    send(_notification, _context) {
         if (this.backend === null) {
             return Promise.reject(new Error('Backend not injected'));
         }
         return Promise.resolve();
     }
-    ;
+    /**
+     * Check if this adapter supports attachments
+     */
+    get supportsAttachments() {
+        return false;
+    }
+    /**
+     * Prepare attachments for sending
+     * Override in adapters that support attachments
+     */
+    async prepareAttachments(attachments) {
+        var _a, _b;
+        if (this.supportsAttachments && attachments.length > 0) {
+            (_b = (_a = this.logger) === null || _a === void 0 ? void 0 : _a.warn) === null || _b === void 0 ? void 0 : _b.call(_a, `Adapter ${this.key} claims to support attachments but prepareAttachments is not implemented`);
+        }
+        return null;
+    }
+    /**
+     * Get the recipient email address from a notification.
+     * For one-off notifications, returns the emailOrPhone field directly.
+     * For regular notifications, fetches the email from the user via backend.
+     */
+    async getRecipientEmail(notification) {
+        if (isOneOffNotification(notification)) {
+            return notification.emailOrPhone;
+        }
+        // Regular notification - get from user via backend
+        if (!this.backend) {
+            throw new Error('Backend not injected');
+        }
+        const userEmail = await this.backend.getUserEmailFromNotification(notification.id);
+        if (!userEmail) {
+            throw new Error(`User email not found for notification ${notification.id}`);
+        }
+        return userEmail;
+    }
+    /**
+     * Get the recipient name from a notification.
+     * For one-off notifications, returns the firstName and lastName fields directly.
+     * For regular notifications, attempts to extract from context or returns empty strings.
+     */
+    getRecipientName(notification, context) {
+        if (isOneOffNotification(notification)) {
+            return {
+                firstName: notification.firstName,
+                lastName: notification.lastName,
+            };
+        }
+        // Regular notification - try to get from context
+        if (context && typeof context === 'object' && !Array.isArray(context)) {
+            const jsonContext = context;
+            return {
+                firstName: (typeof jsonContext.firstName === 'string' ? jsonContext.firstName : '') || '',
+                lastName: (typeof jsonContext.lastName === 'string' ? jsonContext.lastName : '') || '',
+            };
+        }
+        return {
+            firstName: '',
+            lastName: '',
+        };
+    }
     injectBackend(backend) {
         this.backend = backend;
     }
-    ;
+    injectLogger(logger) {
+        this.logger = logger;
+    }
 }
 exports.BaseNotificationAdapter = BaseNotificationAdapter;

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

@@ -1,25 +1,68 @@
+import type { AttachmentFileRecord, StoredAttachment } from '../../types/attachment';
 import type { InputJsonValue } from '../../types/json-values';
-import type { DatabaseNotification, Notification } from '../../types/notification';
+import type { AnyDatabaseNotification, AnyNotification, DatabaseNotification, DatabaseOneOffNotification, Notification, OneOffNotificationInput } from '../../types/notification';
 import type { BaseNotificationTypeConfig } from '../../types/notification-type-config';
 export interface BaseNotificationBackend<Config extends BaseNotificationTypeConfig> {
-    getAllPendingNotifications(): Promise<DatabaseNotification<Config>[]>;
-    getPendingNotifications(page: number, pageSize: number): Promise<DatabaseNotification<Config>[]>;
-    getAllFutureNotifications(): Promise<DatabaseNotification<Config>[]>;
-    getFutureNotifications(page: number, pageSize: number): Promise<DatabaseNotification<Config>[]>;
+    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>>;
-    getAllNotifications(): Promise<DatabaseNotification<Config>[]>;
-    getNotifications(page: number, pageSize: number): Promise<DatabaseNotification<Config>[]>;
-    bulkPersistNotifications(notifications: Omit<Notification<Config>, 'id'>[]): Promise<Config['NotificationIdType'][]>;
+    getAllNotifications(): Promise<AnyDatabaseNotification<Config>[]>;
+    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>>;
-    markAsSent(notificationId: Config['NotificationIdType'], checkIsPending: boolean): Promise<DatabaseNotification<Config>>;
-    markAsFailed(notificationId: Config['NotificationIdType'], checkIsPending: boolean): Promise<DatabaseNotification<Config>>;
+    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>>;
     cancelNotification(notificationId: Config['NotificationIdType']): Promise<void>;
-    getNotification(notificationId: Config['NotificationIdType'], forUpdate: boolean): Promise<DatabaseNotification<Config> | null>;
+    getNotification(notificationId: Config['NotificationIdType'], forUpdate: boolean): Promise<AnyDatabaseNotification<Config> | null>;
     filterAllInAppUnreadNotifications(userId: Config['UserIdType']): Promise<DatabaseNotification<Config>[]>;
     filterInAppUnreadNotifications(userId: Config['UserIdType'], page: number, pageSize: number): Promise<DatabaseNotification<Config>[]>;
     getUserEmailFromNotification(notificationId: Config['NotificationIdType']): Promise<string | undefined>;
     storeContextUsed(notificationId: Config['NotificationIdType'], context: InputJsonValue): Promise<void>;
+    persistOneOffNotification(notification: Omit<OneOffNotificationInput<Config>, 'id'>): 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>[]>;
+    getOneOffNotifications(page: number, pageSize: number): Promise<DatabaseOneOffNotification<Config>[]>;
+    /**
+     * Get an attachment file record by ID
+     */
+    getAttachmentFile?(fileId: string): Promise<AttachmentFileRecord | null>;
+    /**
+     * Find an attachment file by checksum for deduplication.
+     * Backend queries its database for files with matching checksums.
+     * Used during file upload to avoid storing duplicate files.
+     */
+    findAttachmentFileByChecksum?(checksum: string): Promise<AttachmentFileRecord | null>;
+    /**
+     * Delete an attachment file (only if not referenced by any notifications)
+     */
+    deleteAttachmentFile?(fileId: string): Promise<void>;
+    /**
+     * Get all attachment files not referenced by any notifications (for cleanup)
+     */
+    getOrphanedAttachmentFiles?(): Promise<AttachmentFileRecord[]>;
+    /**
+     * Get all attachments for a specific notification
+     */
+    getAttachments?(notificationId: Config['NotificationIdType']): Promise<StoredAttachment[]>;
+    /**
+     * Delete a specific attachment from a notification
+     */
+    deleteNotificationAttachment?(notificationId: Config['NotificationIdType'], attachmentId: string): Promise<void>;
 }
+/**
+ * Type guard to check if backend supports attachment operations
+ */
+export declare function supportsAttachments<Config extends BaseNotificationTypeConfig>(backend: BaseNotificationBackend<Config>): backend is BaseNotificationBackend<Config> & {
+    getAttachmentFile(fileId: string): Promise<AttachmentFileRecord | null>;
+    findAttachmentFileByChecksum(checksum: string): Promise<AttachmentFileRecord | null>;
+    deleteAttachmentFile(fileId: string): Promise<void>;
+    getOrphanedAttachmentFiles(): Promise<AttachmentFileRecord[]>;
+    getAttachments(notificationId: Config['NotificationIdType']): Promise<StoredAttachment[]>;
+    deleteNotificationAttachment(notificationId: Config['NotificationIdType'], attachmentId: string): Promise<void>;
+};

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

@@ -1,2 +1,14 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.supportsAttachments = supportsAttachments;
+/**
+ * Type guard to check if backend supports attachment operations
+ */
+function supportsAttachments(backend) {
+    return (typeof backend.getAttachmentFile === 'function' &&
+        typeof backend.findAttachmentFileByChecksum === 'function' &&
+        typeof backend.deleteAttachmentFile === 'function' &&
+        typeof backend.getOrphanedAttachmentFiles === 'function' &&
+        typeof backend.getAttachments === 'function' &&
+        typeof backend.deleteNotificationAttachment === 'function');
+}

package/dist/services/notification-context-generators-map.d.ts

@@ -1,4 +1,4 @@
-import type { ContextGenerator } from "../types/notification-context-generators";
+import type { ContextGenerator } from '../types/notification-context-generators';
 export declare class NotificationContextGeneratorsMap<ContextMapType extends {
     [key: string]: ContextGenerator;
 }> {

package/dist/services/notification-context-registry.d.ts

@@ -1,14 +1,19 @@
 import type { JsonObject, JsonPrimitive } from '../types/json-values';
 export interface ContextGenerator {
-    generate(params: Record<string, JsonPrimitive>): JsonObject | Promise<JsonObject>;
+  generate(params: Record<string, JsonPrimitive>): JsonObject | Promise<JsonObject>;
 }
 export declare class NotificationContextRegistry<T extends Record<string, ContextGenerator>> {
-    private static instance;
-    private readonly contexts;
-    private constructor();
-    static initialize<T extends Record<string, ContextGenerator>>(contexts: T): NotificationContextRegistry<T>;
-    static getInstance<T extends Record<string, ContextGenerator>>(): NotificationContextRegistry<T>;
-    static resetInstance(): void;
-    getContext<K extends keyof T>(key: K, parameters: Parameters<T[K]['generate']>[0]): Promise<JsonObject>;
-    getAvailableContexts(): (keyof T)[];
+  private static instance;
+  private readonly contexts;
+  private constructor();
+  static initialize<T extends Record<string, ContextGenerator>>(
+    contexts: T,
+  ): NotificationContextRegistry<T>;
+  static getInstance<T extends Record<string, ContextGenerator>>(): NotificationContextRegistry<T>;
+  static resetInstance(): void;
+  getContext<K extends keyof T>(
+    key: K,
+    parameters: Parameters<T[K]['generate']>[0],
+  ): Promise<JsonObject>;
+  getAvailableContexts(): (keyof T)[];
 }

package/dist/services/notification-context-registry.js

@@ -1,40 +1,39 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
+Object.defineProperty(exports, '__esModule', { value: true });
 exports.NotificationContextRegistry = void 0;
 class NotificationContextRegistry {
-    constructor(contexts) {
-        this.contexts = contexts;
+  constructor(contexts) {
+    this.contexts = contexts;
+  }
+  static initialize(contexts) {
+    if (NotificationContextRegistry.instance) {
+      throw new Error('NotificationContextRegistry already initialized');
     }
-    static initialize(contexts) {
-        if (NotificationContextRegistry.instance) {
-            throw new Error('NotificationContextRegistry already initialized');
-        }
-        NotificationContextRegistry.instance = new NotificationContextRegistry(contexts);
-        return NotificationContextRegistry.instance;
+    NotificationContextRegistry.instance = new NotificationContextRegistry(contexts);
+    return NotificationContextRegistry.instance;
+  }
+  static getInstance() {
+    if (!NotificationContextRegistry.instance) {
+      throw new Error('NotificationContextRegistry not initialized');
     }
-    static getInstance() {
-        if (!NotificationContextRegistry.instance) {
-            throw new Error('NotificationContextRegistry not initialized');
-        }
-        return NotificationContextRegistry.instance;
+    return NotificationContextRegistry.instance;
+  }
+  static resetInstance() {
+    NotificationContextRegistry.instance = null;
+  }
+  async getContext(key, parameters) {
+    const contextGenerator = this.contexts[key];
+    if (!contextGenerator) {
+      throw new Error(`Context generator not found for context: ${key}`);
     }
-    static resetInstance() {
-        NotificationContextRegistry.instance = null;
-    }
-    async getContext(key, parameters) {
-        const contextGenerator = this.contexts[key];
-        if (!contextGenerator) {
-            throw new Error(`Context generator not found for context: ${key}`);
-        }
-        const result = contextGenerator.generate(parameters);
-        if (result instanceof Promise) {
-            return await result;
-        }
-        return result;
-    }
-    getAvailableContexts() {
-        return Object.keys(this.contexts);
+    const result = contextGenerator.generate(parameters);
+    if (result instanceof Promise) {
+      return await result;
     }
+    return result;
+  }
+  getAvailableContexts() {
+    return Object.keys(this.contexts);
+  }
 }
 exports.NotificationContextRegistry = NotificationContextRegistry;
 // biome-ignore lint/suspicious/noExplicitAny: This won't be used since we'll always initialize the registry

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

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

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

@@ -1,43 +1,103 @@
-import type { DatabaseNotification, Notification } from '../types/notification';
 import type { JsonObject } from '../types/json-values';
+import type { AnyDatabaseNotification, AnyNotification, DatabaseNotification, DatabaseOneOffNotification, Notification } from '../types/notification';
 import type { BaseNotificationTypeConfig } from '../types/notification-type-config';
-import type { BaseNotificationAdapter } from './notification-adapters/base-notification-adapter';
-import type { BaseNotificationTemplateRenderer } from './notification-template-renderers/base-notification-template-renderer';
-import type { BaseNotificationBackend } from './notification-backends/base-notification-backend';
+import type { OneOffNotificationInput } from '../types/one-off-notification';
+import type { BaseAttachmentManager } from './attachment-manager/base-attachment-manager';
 import type { BaseLogger } from './loggers/base-logger';
+import { type BaseNotificationAdapter } from './notification-adapters/base-notification-adapter';
+import type { BaseNotificationBackend } from './notification-backends/base-notification-backend';
 import type { BaseNotificationQueueService } from './notification-queue-service/base-notification-queue-service';
+import type { BaseNotificationTemplateRenderer } from './notification-template-renderers/base-notification-template-renderer';
 type VintaSendOptions = {
     raiseErrorOnFailedSend: boolean;
 };
 export declare class VintaSendFactory<Config extends BaseNotificationTypeConfig> {
-    create<AdaptersList extends BaseNotificationAdapter<BaseNotificationTemplateRenderer<Config>, Config>[], Backend extends BaseNotificationBackend<Config>, Logger extends BaseLogger, QueueService extends BaseNotificationQueueService<Config>>(adapters: AdaptersList, backend: Backend, logger: Logger, contextGeneratorsMap: BaseNotificationTypeConfig['ContextMap'], queueService?: QueueService, options?: VintaSendOptions): VintaSend<Config, AdaptersList, Backend, Logger, QueueService>;
+    /**
+     * 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<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>;
 }
-export declare class VintaSend<Config extends BaseNotificationTypeConfig, AdaptersList extends BaseNotificationAdapter<BaseNotificationTemplateRenderer<Config>, Config>[], Backend extends BaseNotificationBackend<Config>, Logger extends BaseLogger, QueueService extends BaseNotificationQueueService<Config>> {
+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;
     private backend;
     private logger;
     private queueService?;
+    private attachmentManager?;
     private options;
     private contextGeneratorsMap;
-    constructor(adapters: AdaptersList, backend: Backend, logger: Logger, contextGeneratorsMap: Config['ContextMap'], queueService?: QueueService | undefined, options?: VintaSendOptions);
+    constructor(adapters: AdaptersList, backend: Backend, logger: Logger, contextGeneratorsMap: Config['ContextMap'], queueService?: QueueService | undefined, attachmentManager?: AttachmentMgr | undefined, options?: VintaSendOptions);
     registerQueueService(queueService: QueueService): void;
-    send(notification: DatabaseNotification<Config>): Promise<void>;
+    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>>;
-    getAllFutureNotifications(): Promise<DatabaseNotification<Config>[]>;
+    /**
+     * Creates and sends a one-off notification.
+     * One-off notifications are sent directly to an email/phone without requiring a user account.
+     *
+     * @param notification - The one-off notification to create (without id)
+     * @returns The created database notification
+     */
+    createOneOffNotification(notification: Omit<OneOffNotificationInput<Config>, 'id'>): Promise<DatabaseOneOffNotification<Config>>;
+    /**
+     * Updates a one-off notification and re-sends it if the sendAfter date is in the past.
+     *
+     * @param notificationId - The ID of the notification to update
+     * @param notification - The partial notification data to update
+     * @returns The updated database notification
+     */
+    updateOneOffNotification(notificationId: Config['NotificationIdType'], notification: Partial<Omit<OneOffNotificationInput<Config>, 'id'>>): Promise<DatabaseOneOffNotification<Config>>;
+    /**
+     * Validates that an email or phone number has a basic valid format.
+     *
+     * @param emailOrPhone - The email or phone string to validate
+     * @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<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>;
     sendPendingNotifications(): Promise<void>;
-    getPendingNotifications(page: number, pageSize: number): Promise<DatabaseNotification<Config>[]>;
-    getNotification(notificationId: Config['NotificationIdType'], forUpdate?: boolean): Promise<DatabaseNotification<Config> | null>;
+    getPendingNotifications(page: number, pageSize: number): Promise<AnyDatabaseNotification<Config>[]>;
+    getNotification(notificationId: Config['NotificationIdType'], forUpdate?: boolean): Promise<AnyDatabaseNotification<Config> | null>;
+    /**
+     * 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)
+     * @returns The one-off notification or null if not found
+     */
+    getOneOffNotification(notificationId: Config['NotificationIdType'], forUpdate?: boolean): Promise<DatabaseOneOffNotification<Config> | null>;
     markRead(notificationId: Config['NotificationIdType'], checkIsSent?: boolean): Promise<DatabaseNotification<Config>>;
     getInAppUnread(userId: Config['NotificationIdType']): 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<Notification<Config>, 'id'>[]): Promise<Config['NotificationIdType'][]>;
+    bulkPersistNotifications(notifications: Omit<AnyNotification<Config>, 'id'>[]): Promise<Config['NotificationIdType'][]>;
     migrateToBackend<DestinationBackend extends BaseNotificationBackend<Config>>(destinationBackend: DestinationBackend, batchSize?: number): Promise<void>;
 }
 export {};

package/dist/services/notification-service.js

@@ -1,27 +1,66 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VintaSend = exports.VintaSendFactory = void 0;
+const base_notification_adapter_1 = require("./notification-adapters/base-notification-adapter");
 const notification_context_generators_map_1 = require("./notification-context-generators-map");
 class VintaSendFactory {
-    create(adapters, backend, logger, contextGeneratorsMap, queueService, options = {
+    /**
+     * 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 = {
         raiseErrorOnFailedSend: false,
     }) {
-        return new VintaSend(adapters, backend, logger, contextGeneratorsMap, queueService, options);
+        return new VintaSend(adapters, backend, logger, contextGeneratorsMap, queueService, attachmentManager, options);
     }
 }
 exports.VintaSendFactory = VintaSendFactory;
+// Type guard to check if backend has attachment manager injection support
+function hasAttachmentManagerInjection(backend) {
+    return ('injectAttachmentManager' in backend &&
+        // biome-ignore lint/suspicious/noExplicitAny:: this is a necessary check
+        typeof backend.injectAttachmentManager === 'function');
+}
 class VintaSend {
-    constructor(adapters, backend, logger, contextGeneratorsMap, queueService, options = {
+    constructor(adapters, backend, logger, contextGeneratorsMap, queueService, attachmentManager, options = {
         raiseErrorOnFailedSend: false,
     }) {
         this.adapters = adapters;
         this.backend = backend;
         this.logger = logger;
         this.queueService = queueService;
+        this.attachmentManager = attachmentManager;
         this.options = options;
         this.contextGeneratorsMap = new notification_context_generators_map_1.NotificationContextGeneratorsMap(contextGeneratorsMap);
         for (const adapter of adapters) {
             adapter.injectBackend(backend);
+            adapter.injectLogger(logger);
+        }
+        // Inject attachment manager into backend if both exist
+        if (this.attachmentManager && hasAttachmentManagerInjection(backend)) {
+            backend.injectAttachmentManager(this.attachmentManager);
         }
     }
     registerQueueService(queueService) {
@@ -119,6 +158,66 @@ class VintaSend {
         this.logger.info(`Notification ${notificationId} updated`);
         return updatedNotification;
     }
+    /**
+     * Creates and sends a one-off notification.
+     * One-off notifications are sent directly to an email/phone without requiring a user account.
+     *
+     * @param notification - The one-off notification to create (without id)
+     * @returns The created database notification
+     */
+    async createOneOffNotification(notification) {
+        // Validate email or phone format
+        this.validateEmailOrPhone(notification.emailOrPhone);
+        const createdNotification = await this.backend.persistOneOffNotification(notification);
+        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`);
+            await this.send(createdNotification);
+        }
+        else {
+            this.logger.info(`One-off notification ${createdNotification.id} scheduled for ${notification.sendAfter}`);
+        }
+        return createdNotification;
+    }
+    /**
+     * Updates a one-off notification and re-sends it if the sendAfter date is in the past.
+     *
+     * @param notificationId - The ID of the notification to update
+     * @param notification - The partial notification data to update
+     * @returns The updated database notification
+     */
+    async updateOneOffNotification(notificationId, notification) {
+        // Validate email or phone format if provided
+        if (notification.emailOrPhone !== undefined) {
+            this.validateEmailOrPhone(notification.emailOrPhone);
+        }
+        const updatedNotification = await this.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`);
+            await this.send(updatedNotification);
+        }
+        return updatedNotification;
+    }
+    /**
+     * Validates that an email or phone number has a basic valid format.
+     *
+     * @param emailOrPhone - The email or phone string to validate
+     * @throws Error if the format is invalid
+     */
+    validateEmailOrPhone(emailOrPhone) {
+        // Basic non-empty check
+        if (emailOrPhone === '' || emailOrPhone.trim() === '') {
+            throw new Error('emailOrPhone cannot be empty');
+        }
+        // Check if it's an email (has @ with characters before and after)
+        const isEmail = /^.+@.+\..+$/.test(emailOrPhone);
+        // Check if it's a phone (10-15 digits, optionally starting with +)
+        const isPhone = /^\+?[0-9]{10,15}$/.test(emailOrPhone);
+        if (!isEmail && !isPhone) {
+            throw new Error('Invalid email or phone format');
+        }
+    }
     async getAllFutureNotifications() {
         return this.backend.getAllFutureNotifications();
     }
@@ -148,6 +247,16 @@ class VintaSend {
     async getNotification(notificationId, forUpdate = false) {
         return this.backend.getNotification(notificationId, forUpdate);
     }
+    /**
+     * 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)
+     * @returns The one-off notification or null if not found
+     */
+    async getOneOffNotification(notificationId, forUpdate = false) {
+        return this.backend.getOneOffNotification(notificationId, forUpdate);
+    }
     async markRead(notificationId, checkIsSent = true) {
         const notification = await this.backend.markAsRead(notificationId, checkIsSent);
         this.logger.info(`Notification ${notificationId} marked as read`);
@@ -169,6 +278,14 @@ class VintaSend {
             }
             return;
         }
+        // Check if this is a one-off notification (which cannot be resent this way)
+        if ((0, base_notification_adapter_1.isOneOffNotification)(notification)) {
+            this.logger.error(`Cannot resend one-off notification ${notificationId} using resendNotification. One-off notifications are not supported.`);
+            if (this.options.raiseErrorOnFailedSend) {
+                throw new Error(`Cannot resend one-off notification ${notificationId}. One-off notifications must be resent using a different method.`);
+            }
+            return;
+        }
         if (notification.sendAfter && notification.sendAfter > new Date()) {
             this.logger.error(`Notification ${notificationId} is scheduled for the future`);
             if (this.options.raiseErrorOnFailedSend) {
@@ -263,15 +380,15 @@ class VintaSend {
     }
     async migrateToBackend(destinationBackend, batchSize = 5000) {
         let pageNumber = 0;
-        let notifications = await this.backend.getNotifications(pageNumber, batchSize);
-        while (notifications.length > 0) {
+        let allNotifications = await this.backend.getNotifications(pageNumber, batchSize);
+        while (allNotifications.length > 0) {
             pageNumber += 1;
-            const notificationsWitoutId = notifications.map((notification) => {
+            const notificationsWithoutId = allNotifications.map((notification) => {
                 const { id, ...notificationWithoutId } = notification;
                 return notificationWithoutId;
             });
-            await destinationBackend.bulkPersistNotifications(notificationsWitoutId);
-            notifications = await this.backend.getNotifications(pageNumber, batchSize);
+            await destinationBackend.bulkPersistNotifications(notificationsWithoutId);
+            allNotifications = await this.backend.getNotifications(pageNumber, batchSize);
         }
     }
 }

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

@@ -1,13 +1,13 @@
-import type { BaseNotificationTemplateRenderer } from './base-notification-template-renderer';
-import type { Notification } from '../../types/notification';
 import type { Buffer } from 'node:buffer';
 import type { JsonObject } from '../../types/json-values';
+import type { AnyNotification } from '../../types/notification';
 import type { BaseNotificationTypeConfig } from '../../types/notification-type-config';
+import type { BaseNotificationTemplateRenderer } from './base-notification-template-renderer';
 export type Attachment = File | Buffer | string;
 export type EmailTemplate = {
     subject: string;
     body: string;
 };
 export interface BaseEmailTemplateRenderer<Config extends BaseNotificationTypeConfig> extends BaseNotificationTemplateRenderer<Config, EmailTemplate> {
-    render(notification: Notification<Config>, context: JsonObject): Promise<EmailTemplate>;
+    render(notification: AnyNotification<Config>, context: JsonObject): Promise<EmailTemplate>;
 }