vintasend 0.2.3 → 0.3.0

package/README.md

@@ -5,9 +5,10 @@ A flexible package for implementing transactional notifications in TypeScript.
 ## Features
 
 * **Storing notifications in a Database**: This package relies on a data store to record all the notifications that will be sent. It also keeps its state column up to date.
+* **One-off notifications**: Send notifications directly to email addresses or phone numbers without requiring a user account. Perfect for prospects, guests, or external contacts.
 * **Scheduling notifications**: Storing notifications to be sent in the future. The notification's context for rendering the template is only evaluated at the moment the notification is sent due to the lib's context generation registry.
 * **Notification context fetched at send time**: On scheduled notifications, the package only gets the notification context (information to render the templates) at the send time, so we always get the most up-to-date information.
-* **Flexible backend**: Your project's database is getting slow after you created the first million notifications? You can migrate to a faster no-sql database with a blink of an eye without affecting how you send the notifications.
+* **Flexible backend**: Your project's database is getting slow after you created the first million notifications? You can migrate to a faster NoSQL database in the blink of an eye without affecting how you send the notifications.
 * **Flexible adapters**: Your project probably will need to change how it sends notifications over time. This package allows you to change the adapter without having to change how notification templates are rendered or how the notification themselves are stored.
 * **Flexible template renderers**: Wanna start managing your templates with a third party tool (so non-technical people can help maintain them)? Or even choose a more powerful rendering engine? You can do it independently of how you send the notifications or store them in the database.
 * **Sending notifications in background jobs**: This package supports using job queues to send notifications from separate processes. This may be helpful to free up the HTTP server of processing heavy notifications during the request time.
@@ -104,40 +105,119 @@ export function sendWelcomeEmail(userId: number) {
 } 
 ```
 
+## One-Off Notifications
+
+One-off notifications allow you to send notifications directly to an email address or phone number without requiring a user account in your system. This is particularly useful for:
+
+- **Prospects**: Send welcome emails or marketing materials to potential customers
+- **Guests**: Invite external participants to events or meetings
+- **External Contacts**: Share information with partners or vendors
+- **Temporary Recipients**: Send one-time notifications without creating user accounts
+
+### Key Differences from Regular Notifications
+
+| Feature | Regular Notification | One-Off Notification |
+|---------|---------------------|----------------------|
+| **Recipient** | User ID (requires account) | Email/phone directly |
+| **User Data** | Fetched from user table | Provided inline (firstName, lastName) |
+| **Use Case** | Registered users | Prospects, guests, external contacts |
+| **Storage** | Same table with `userId` | Same table with `emailOrPhone` |
+
+### Creating One-Off Notifications
+
+```typescript
+// Send an immediate one-off notification
+const notification = await vintaSend.createOneOffNotification({
+  emailOrPhone: 'prospect@example.com',
+  firstName: 'John',
+  lastName: 'Doe',
+  notificationType: 'EMAIL',
+  title: 'Welcome!',
+  bodyTemplate: './templates/welcome.html',
+  subjectTemplate: 'Welcome to {{companyName}}!',
+  contextName: 'welcomeContext',
+  contextParameters: { companyName: 'Acme Corp' },
+  sendAfter: null, // Send immediately
+  extraParams: null,
+});
+```
+
+#### Using with Phone Numbers (SMS)
+
+```typescript
+// Send SMS to a phone number (requires SMS adapter)
+const smsNotification = await vintaSend.createOneOffNotification({
+  emailOrPhone: '+15551234567', // E.164 format recommended
+  firstName: 'John',
+  lastName: 'Doe',
+  notificationType: 'SMS',
+  title: 'Welcome SMS',
+  bodyTemplate: './templates/welcome-sms.txt',
+  subjectTemplate: null, // SMS doesn't use subjects
+  contextName: 'welcomeContext',
+  contextParameters: { companyName: 'Acme Corp' },
+  sendAfter: null,
+  extraParams: null,
+});
+```
+
+### Database Schema Considerations
+
+One-off notifications are stored in the same table as regular notifications using a unified approach:
+
+- **Regular notifications**: Have `userId` set, `emailOrPhone` is null
+- **One-off notifications**: Have `emailOrPhone` set, `userId` is null
+
+### Migration Guide
+
+If you're adding one-off notification support to an existing installation:
+
+1. **Update your Prisma schema** to make `userId` optional and add one-off fields:
+   ```bash
+   # Add the new fields to your schema.prisma
+   # Then run:
+   prisma migrate dev --name add-one-off-notification-support
+   ```
+
+2. **No code changes required** for existing functionality - all existing notifications continue to work as before.
+
+3. **Existing notifications are preserved** - they have `userId` set and `emailOrPhone` as null.
+
 ## Glossary
 
-* **Notification Backend**: It is a class that implements the methods necessary for VintaSend services to create, update, and retrieve Notifications from da database.
+* **Notification Backend**: It is a class that implements the methods necessary for VintaSend services to create, update, and retrieve Notifications from the database.
 * **Notification Adapter**: It is a class that implements the methods necessary for VintaSend services to send Notifications through email, SMS or even push/in-app notifications.
 * **Template Renderer**: It is a class that implements the methods necessary for VintaSend adapter to render the notification body.
 * **Notification Context**: It's the data passed to the templates to render the notification correctly. It's generated when the notification is sent, not on creation time
 * **Context generator**: It's a class defined by the user context generator map with a context name. That class has a `generate` method that, when called, generates the data necessary to render its respective notification.
 * **Context name**: The registered name of a context generator. It's stored in the notification so the context generator is called at the moment the notification will be sent.
 * **Context generators map**: It's an object defined by the user that maps context names to their respective context generators.
-* **Queue service**: Service for enqueueing notifications so they are send by an external service.
-* **Logger**: A class that allows the `NotificationService` to create logs following a format defined by its users.  
+* **Queue service**: Service for enqueueing notifications so they are sent by an external service.
+* **Logger**: A class that allows the `NotificationService` to create logs following a format defined by its users.
+* **One-off Notification**: A notification sent directly to an email address or phone number without requiring a user account. Used for prospects, guests, or external contacts.
+* **Regular Notification**: A notification associated with a user account (via userId). Used for registered users in your system.  
 
 
 ## Implementations
 
-
-## Community
+### Community
 
 VintaSend has many backend, adapter, and template renderer implementations. If you can't find something that fulfills your needs, the package has very clear interfaces you can implement and achieve the exact behavior you expect without loosing VintaSend's friendly API.
 
-### Officially supported packages 
+#### Officially supported packages 
 
-#### Backends
+##### Backends
 
 * **[vintasend-prisma](https://github.com/vintasoftware/vintasend-prisma/)**: Uses Prisma Client to manage the notifications in the database.
 
-#### Adapters
+##### Adapters
 
 * **[vintasend-nodemailer](https://github.com/vintasoftware/vintasend-nodemailer/)**: Uses nodemailer to send transactional emails to users. 
 
-#### Template Renderers
+##### Template Renderers
 * **[vintasend-pug](https://github.com/vintasoftware/vintasend-pug/)**: Renders emails using Pug.
 
-#### Loggers
+##### Loggers
 * **[vintasend-winston](https://github.com/vintasoftware/vintasend-winston/)**: Uses Winston to allow `NotificationService` to create log entries.
 
 ## Examples

package/dist/index.d.ts

@@ -1,8 +1,9 @@
 export { VintaSendFactory } from './services/notification-service';
 export type { VintaSend } from './services/notification-service';
-export type { Notification, DatabaseNotification, NotificationInput, NotificationResendWithContextInput, } from './types/notification';
+export type { Notification, DatabaseNotification, NotificationInput, NotificationResendWithContextInput, OneOffNotification, DatabaseOneOffNotification, OneOffNotificationInput, OneOffNotificationResendWithContextInput, AnyNotification, AnyDatabaseNotification, AnyNotificationInput, } from './types/notification';
 export type { ContextGenerator } from './types/notification-context-generators';
 export type { BaseNotificationTypeConfig } from './types/notification-type-config';
 export type { BaseNotificationQueueService } from './services/notification-queue-service/base-notification-queue-service';
 export type { BaseNotificationTemplateRenderer } from './services/notification-template-renderers/base-notification-template-renderer';
 export type { BaseEmailTemplateRenderer } from './services/notification-template-renderers/base-email-template-renderer';
+export { BaseNotificationAdapter, isOneOffNotification } from './services/notification-adapters/base-notification-adapter';

package/dist/index.js

@@ -1,5 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.VintaSendFactory = void 0;
+exports.isOneOffNotification = exports.BaseNotificationAdapter = exports.VintaSendFactory = void 0;
 var notification_service_1 = require("./services/notification-service");
 Object.defineProperty(exports, "VintaSendFactory", { enumerable: true, get: function () { return notification_service_1.VintaSendFactory; } });
+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/attachment-manager/base-attachment-manager.js

@@ -0,0 +1 @@
+"use strict";

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

@@ -1,9 +1,13 @@
 import type { NotificationType } from '../../types/notification-type';
-import type { DatabaseNotification } from '../../types/notification';
+import type { DatabaseOneOffNotification, AnyDatabaseNotification } from '../../types/notification';
 import type { BaseNotificationTemplateRenderer } from '../notification-template-renderers/base-notification-template-renderer';
 import type { JsonValue } from '../../types/json-values';
 import type { BaseNotificationTypeConfig } from '../../types/notification-type-config';
 import type { BaseNotificationBackend } from '../notification-backends/base-notification-backend';
+/**
+ * Type guard to check if a notification is a one-off notification
+ */
+export declare function isOneOffNotification<Config extends BaseNotificationTypeConfig>(notification: AnyDatabaseNotification<Config>): notification is DatabaseOneOffNotification<Config>;
 export declare abstract class BaseNotificationAdapter<TemplateRenderer extends BaseNotificationTemplateRenderer<Config>, Config extends BaseNotificationTypeConfig> {
     protected templateRenderer: TemplateRenderer;
     readonly notificationType: NotificationType;
@@ -11,6 +15,21 @@ export declare abstract class BaseNotificationAdapter<TemplateRenderer extends B
     key: string | null;
     backend: BaseNotificationBackend<Config> | null;
     constructor(templateRenderer: TemplateRenderer, notificationType: NotificationType, enqueueNotifications: boolean);
-    send(notification: DatabaseNotification<Config>, context: JsonValue): Promise<void>;
+    send(notification: AnyDatabaseNotification<Config>, context: JsonValue): Promise<void>;
+    /**
+     * 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.
+     */
+    protected getRecipientEmail(notification: AnyDatabaseNotification<Config>): Promise<string>;
+    /**
+     * 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.
+     */
+    protected getRecipientName(notification: AnyDatabaseNotification<Config>, context: JsonValue): {
+        firstName: string;
+        lastName: string;
+    };
     injectBackend(backend: BaseNotificationBackend<Config>): void;
 }

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;
@@ -17,6 +24,50 @@ class BaseNotificationAdapter {
         return Promise.resolve();
     }
     ;
+    /**
+     * 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;
     }

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

@@ -1,25 +1,30 @@
 import type { InputJsonValue } from '../../types/json-values';
-import type { DatabaseNotification, Notification } from '../../types/notification';
+import type { DatabaseNotification, Notification, DatabaseOneOffNotification, OneOffNotificationInput, AnyNotification, AnyDatabaseNotification } 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>[]>;
 }

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

@@ -1,7 +1,8 @@
-import type { DatabaseNotification, Notification } from '../types/notification';
+import type { DatabaseNotification, Notification, AnyNotification, AnyDatabaseNotification, DatabaseOneOffNotification } from '../types/notification';
+import type { OneOffNotificationInput } from '../types/one-off-notification';
 import type { JsonObject } from '../types/json-values';
 import type { BaseNotificationTypeConfig } from '../types/notification-type-config';
-import type { BaseNotificationAdapter } from './notification-adapters/base-notification-adapter';
+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 { BaseLogger } from './loggers/base-logger';
@@ -21,23 +22,54 @@ export declare class VintaSend<Config extends BaseNotificationTypeConfig, Adapte
     private contextGeneratorsMap;
     constructor(adapters: AdaptersList, backend: Backend, logger: Logger, contextGeneratorsMap: Config['ContextMap'], queueService?: QueueService | 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,6 +1,7 @@
 "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 = {
@@ -119,6 +120,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 +209,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 +240,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 +342,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,5 +1,5 @@
 import type { BaseNotificationTemplateRenderer } from './base-notification-template-renderer';
-import type { Notification } from '../../types/notification';
+import type { AnyNotification } from '../../types/notification';
 import type { Buffer } from 'node:buffer';
 import type { JsonObject } from '../../types/json-values';
 import type { BaseNotificationTypeConfig } from '../../types/notification-type-config';
@@ -9,5 +9,5 @@ export type EmailTemplate = {
     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>;
 }

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

@@ -1,6 +1,6 @@
 import type { JsonObject } from '../../types/json-values';
-import type { Notification } from '../../types/notification';
+import type { AnyNotification } from '../../types/notification';
 import type { BaseNotificationTypeConfig } from '../../types/notification-type-config';
 export interface BaseNotificationTemplateRenderer<Config extends BaseNotificationTypeConfig, T = unknown> {
-    render(notification: Notification<Config>, context: JsonObject): Promise<T>;
+    render(notification: AnyNotification<Config>, context: JsonObject): Promise<T>;
 }

package/dist/types/notification.d.ts

@@ -2,6 +2,8 @@ import type { InputJsonValue, JsonValue } from './json-values';
 import type { NotificationStatus } from './notification-status';
 import type { NotificationType } from './notification-type';
 import type { BaseNotificationTypeConfig } from './notification-type-config';
+import type { DatabaseOneOffNotification, OneOffNotification, OneOffNotificationInput } from './one-off-notification';
+export type { OneOffNotificationInput, OneOffNotificationResendWithContextInput, DatabaseOneOffNotification, OneOffNotification, } from './one-off-notification';
 export type NotificationInput<Config extends BaseNotificationTypeConfig> = {
     userId: Config['UserIdType'];
     notificationType: NotificationType;
@@ -45,3 +47,18 @@ export type DatabaseNotification<Config extends BaseNotificationTypeConfig> = {
     updatedAt?: Date;
 };
 export type Notification<Config extends BaseNotificationTypeConfig> = NotificationInput<Config> | NotificationResendWithContextInput<Config> | DatabaseNotification<Config>;
+/**
+ * Union type representing any notification type (regular or one-off).
+ * This is useful for methods that handle both notification types.
+ */
+export type AnyNotification<Config extends BaseNotificationTypeConfig> = Notification<Config> | OneOffNotification<Config>;
+/**
+ * Union type for database notifications only (regular or one-off).
+ * Useful for send methods and database queries.
+ */
+export type AnyDatabaseNotification<Config extends BaseNotificationTypeConfig> = DatabaseNotification<Config> | DatabaseOneOffNotification<Config>;
+/**
+ * Union type for notification inputs only (regular or one-off).
+ * Useful for creation methods.
+ */
+export type AnyNotificationInput<Config extends BaseNotificationTypeConfig> = NotificationInput<Config> | OneOffNotificationInput<Config>;

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

@@ -0,0 +1,68 @@
+import type { InputJsonValue, JsonValue } from './json-values';
+import type { NotificationStatus } from './notification-status';
+import type { NotificationType } from './notification-type';
+import type { BaseNotificationTypeConfig } from './notification-type-config';
+/**
+ * Input type for creating a one-off notification.
+ * One-off notifications are sent directly to an email/phone without requiring a user account.
+ */
+export type OneOffNotificationInput<Config extends BaseNotificationTypeConfig> = {
+    emailOrPhone: string;
+    firstName: string;
+    lastName: string;
+    notificationType: NotificationType;
+    title: string | null;
+    bodyTemplate: string;
+    contextName: string & keyof Config['ContextMap'];
+    contextParameters: Parameters<Config['ContextMap'][OneOffNotificationInput<Config>['contextName']]['generate']>[0];
+    sendAfter: Date | null;
+    subjectTemplate: string | null;
+    extraParams: InputJsonValue | null;
+};
+/**
+ * Input type for resending a one-off notification with stored context.
+ * Similar to OneOffNotificationInput but includes the contextUsed field.
+ */
+export type OneOffNotificationResendWithContextInput<Config extends BaseNotificationTypeConfig> = {
+    emailOrPhone: string;
+    firstName: string;
+    lastName: string;
+    notificationType: NotificationType;
+    title: string | null;
+    bodyTemplate: string;
+    contextName: string & keyof Config['ContextMap'];
+    contextParameters: Parameters<Config['ContextMap'][OneOffNotificationResendWithContextInput<Config>['contextName']]['generate']>[0];
+    contextUsed: ReturnType<Config['ContextMap'][OneOffNotificationResendWithContextInput<Config>['contextName']]['generate']> extends Promise<infer T> ? T : ReturnType<Config['ContextMap'][OneOffNotificationResendWithContextInput<Config>['contextName']]['generate']>;
+    sendAfter: Date | null;
+    subjectTemplate: string | null;
+    extraParams: InputJsonValue | null;
+};
+/**
+ * Database representation of a one-off notification.
+ * Includes all fields from input plus database-managed fields (id, status, timestamps, etc.)
+ */
+export type DatabaseOneOffNotification<Config extends BaseNotificationTypeConfig> = {
+    id: Config['NotificationIdType'];
+    emailOrPhone: string;
+    firstName: string;
+    lastName: string;
+    notificationType: NotificationType;
+    title: string | null;
+    bodyTemplate: string;
+    contextName: string & keyof Config['ContextMap'];
+    contextParameters: Parameters<Config['ContextMap'][DatabaseOneOffNotification<Config>['contextName']]['generate']>[0];
+    sendAfter: Date | null;
+    subjectTemplate: string | null;
+    status: NotificationStatus;
+    contextUsed: null | (ReturnType<Config['ContextMap'][DatabaseOneOffNotification<Config>['contextName']]['generate']> extends Promise<infer T> ? T : ReturnType<Config['ContextMap'][DatabaseOneOffNotification<Config>['contextName']]['generate']>);
+    extraParams: JsonValue;
+    adapterUsed: string | null;
+    sentAt: Date | null;
+    readAt: Date | null;
+    createdAt?: Date;
+    updatedAt?: Date;
+};
+/**
+ * Union type representing any one-off notification (input, resend, or database).
+ */
+export type OneOffNotification<Config extends BaseNotificationTypeConfig> = OneOffNotificationInput<Config> | OneOffNotificationResendWithContextInput<Config> | DatabaseOneOffNotification<Config>;

package/dist/types/one-off-notification.js

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

package/package.json

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