@spfn/notification 0.1.0-beta.16 → 0.1.0-beta.18

package/README.md

@@ -22,8 +22,8 @@ pnpm add @spfn/notification
 Install providers as needed:
 
 ```bash
-# For AWS SES (Email)
-pnpm add @aws-sdk/client-ses
+# For AWS SES v2 (Email)
+pnpm add @aws-sdk/client-sesv2
 
 # For AWS SNS (SMS)
 pnpm add @aws-sdk/client-sns
@@ -131,11 +131,16 @@ await sendEmail({
     html: '<h1>HTML content</h1>',
 });
 
-// Bulk send
+// Bulk send (in-process, parallel)
 await sendEmailBulk([
     { to: 'user1@example.com', template: 'welcome', data: { name: 'John' } },
     { to: 'user2@example.com', template: 'welcome', data: { name: 'Jane' } },
-]);
+], { concurrency: 20 });
+
+// Bulk send (distributed across instances via pg-boss)
+const result = await sendEmailBulk(items, { distributed: true });
+// result.batchId — UUID for tracking this batch
+// Actual sending happens in background via pg-boss workers
 ```
 
 ### SMS
@@ -183,6 +188,47 @@ import { cancelNotification } from '@spfn/notification/server';
 await cancelNotification(result.notificationId);
 ```
 
+## Bulk Sending
+
+All channels support bulk sending with two modes:
+
+### In-Process Mode (default)
+
+Sends all items in the current process with concurrency control.
+Suitable for single-instance deployments or smaller batches.
+
+```typescript
+import { sendEmailBulk, sendSMSBulk, sendSlackBulk } from '@spfn/notification/server';
+
+const result = await sendEmailBulk(items, { concurrency: 20 });
+// result.results — SendResult[] in same order as input
+// result.successCount / result.failureCount
+// result.batchId — UUID for this batch
+```
+
+### Distributed Mode
+
+Enqueues items to pg-boss for processing across multiple instances.
+Each instance's worker fetches 50 items at a time and processes them in parallel.
+Failed items are individually retried by pg-boss.
+
+```typescript
+const result = await sendEmailBulk(items, { distributed: true });
+// Returns immediately with pending results
+// result.results[i].messageId === 'pending:{batchId}'
+```
+
+**Distributed mode flow:**
+1. Validates and renders templates
+2. Batch inserts notification records (single query)
+3. Applies tracking (email only)
+4. Bulk inserts pg-boss jobs via `sendBatch()`
+5. Returns immediately — workers process in background
+
+**Requirements:**
+- `notificationJobRouter` must be registered (see Job Router Setup below)
+- pg-boss must be initialized
+
 ### Job Router Setup
 
 Register the notification job router with your server:
@@ -493,16 +539,22 @@ export {
     sendEmail,
     sendEmailBulk,
     registerEmailProvider,
+    type BulkEmailResult,
+    type BulkEmailOptions,
 
     // SMS
     sendSMS,
     sendSMSBulk,
     registerSMSProvider,
+    type BulkSMSResult,
+    type BulkSMSOptions,
 
     // Slack
     sendSlack,
     sendSlackBulk,
     registerSlackProvider,
+    type BulkSlackResult,
+    type BulkSlackOptions,
 
     // Scheduling
     scheduleEmail,
@@ -528,6 +580,9 @@ export {
 
     // Jobs
     notificationJobRouter,
+    sendBulkEmailItemJob,
+    sendBulkSmsItemJob,
+    sendBulkSlackItemJob,
 };
 ```
 

package/dist/server.d.ts

@@ -20,13 +20,37 @@ declare function registerEmailProvider(provider: EmailProvider): void;
  */
 declare function sendEmail(params: SendEmailParams): Promise<SendResult>;
 /**
- * Send bulk emails
+ * Bulk email result
  */
-declare function sendEmailBulk(items: SendEmailParams[]): Promise<{
+interface BulkEmailResult {
     results: SendResult[];
     successCount: number;
     failureCount: number;
-}>;
+    batchId: string;
+}
+/**
+ * Bulk email options
+ */
+interface BulkEmailOptions {
+    /**
+     * Max parallel sends when processing in-process (default: 10)
+     */
+    concurrency?: number;
+    /**
+     * When true, enqueue to pg-boss for distributed processing across instances.
+     * Returns immediately with pending results — actual sending happens in background.
+     * Requires notificationJobRouter to be registered.
+     * @default false
+     */
+    distributed?: boolean;
+}
+/**
+ * Send bulk emails with batch DB insert and concurrent sending.
+ *
+ * @param items - Email items to send
+ * @param options - concurrency, distributed
+ */
+declare function sendEmailBulk(items: SendEmailParams[], options?: BulkEmailOptions): Promise<BulkEmailResult>;
 
 /**
  * @spfn/notification - SMS Channel
@@ -41,13 +65,28 @@ declare function registerSMSProvider(provider: SMSProvider): void;
  */
 declare function sendSMS(params: SendSMSParams): Promise<SendResult>;
 /**
- * Send bulk SMS
+ * Bulk SMS result
  */
-declare function sendSMSBulk(items: SendSMSParams[]): Promise<{
+interface BulkSMSResult {
     results: SendResult[];
     successCount: number;
     failureCount: number;
-}>;
+    batchId: string;
+}
+/**
+ * Bulk SMS options
+ */
+interface BulkSMSOptions {
+    concurrency?: number;
+    distributed?: boolean;
+}
+/**
+ * Send bulk SMS with batch DB insert and concurrent sending.
+ *
+ * @param items - SMS items to send
+ * @param options - concurrency, distributed
+ */
+declare function sendSMSBulk(items: SendSMSParams[], options?: BulkSMSOptions): Promise<BulkSMSResult>;
 
 /**
  * @spfn/notification - Slack Channel
@@ -62,13 +101,28 @@ declare function registerSlackProvider(provider: SlackProvider): void;
  */
 declare function sendSlack(params: SendSlackParams): Promise<SendResult>;
 /**
- * Send bulk Slack messages
+ * Bulk Slack result
  */
-declare function sendSlackBulk(items: SendSlackParams[]): Promise<{
+interface BulkSlackResult {
     results: SendResult[];
     successCount: number;
     failureCount: number;
-}>;
+    batchId: string;
+}
+/**
+ * Bulk Slack options
+ */
+interface BulkSlackOptions {
+    concurrency?: number;
+    distributed?: boolean;
+}
+/**
+ * Send bulk Slack messages with batch DB insert and concurrent sending.
+ *
+ * @param items - Slack items to send
+ * @param options - concurrency, distributed
+ */
+declare function sendSlackBulk(items: SendSlackParams[], options?: BulkSlackOptions): Promise<BulkSlackResult>;
 
 /**
  * @spfn/notification - Schedule Service
@@ -807,17 +861,17 @@ declare function cancelNotificationsByReference(referenceType: string, reference
  * Scheduled email sending job
  */
 declare const sendScheduledEmailJob: _spfn_core_job.JobDef<{
-    from?: string | undefined;
-    subject?: string | undefined;
-    html?: string | undefined;
-    text?: string | undefined;
     data?: {
         [x: string]: unknown;
     } | undefined;
-    template?: string | undefined;
+    subject?: string | undefined;
+    from?: string | undefined;
+    html?: string | undefined;
+    text?: string | undefined;
     replyTo?: string | undefined;
-    to: string | string[];
+    template?: string | undefined;
     notificationId: number;
+    to: string | string[];
 }, void>;
 
 /**
@@ -827,13 +881,56 @@ declare const sendScheduledEmailJob: _spfn_core_job.JobDef<{
  * Scheduled SMS sending job
  */
 declare const sendScheduledSmsJob: _spfn_core_job.JobDef<{
-    message?: string | undefined;
     data?: {
         [x: string]: unknown;
     } | undefined;
+    message?: string | undefined;
     template?: string | undefined;
+    notificationId: number;
     to: string | string[];
+}, void>;
+
+/**
+ * @spfn/notification - Bulk Email Item Job
+ *
+ * Processes a single email item from a distributed bulk send.
+ * Notification record and tracking are already applied by sendEmailBulk().
+ * This job just sends via provider and updates history.
+ *
+ * Uses batchSize so pg-boss workers fetch multiple items at once
+ * and process them in parallel across instances.
+ */
+declare const sendBulkEmailItemJob: _spfn_core_job.JobDef<{
+    html?: string | undefined;
+    text?: string | undefined;
+    replyTo?: string | undefined;
+    subject: string;
+    notificationId: number;
+    to: string[];
+    from: string;
+}, void>;
+
+/**
+ * @spfn/notification - Bulk SMS Item Job
+ *
+ * Processes a single SMS item from a distributed bulk send.
+ */
+declare const sendBulkSmsItemJob: _spfn_core_job.JobDef<{
     notificationId: number;
+    to: string;
+    message: string;
+}, void>;
+
+/**
+ * @spfn/notification - Bulk Slack Item Job
+ *
+ * Processes a single Slack item from a distributed bulk send.
+ */
+declare const sendBulkSlackItemJob: _spfn_core_job.JobDef<{
+    text?: string | undefined;
+    blocks?: unknown[] | undefined;
+    notificationId: number;
+    webhookUrl: string;
 }, void>;
 
 /**
@@ -858,26 +955,46 @@ declare const sendScheduledSmsJob: _spfn_core_job.JobDef<{
  */
 declare const notificationJobRouter: _spfn_core_job.JobRouter<{
     sendScheduledEmail: _spfn_core_job.JobDef<{
-        from?: string | undefined;
-        subject?: string | undefined;
-        html?: string | undefined;
-        text?: string | undefined;
         data?: {
             [x: string]: unknown;
         } | undefined;
-        template?: string | undefined;
+        subject?: string | undefined;
+        from?: string | undefined;
+        html?: string | undefined;
+        text?: string | undefined;
         replyTo?: string | undefined;
-        to: string | string[];
+        template?: string | undefined;
         notificationId: number;
+        to: string | string[];
     }, void>;
     sendScheduledSms: _spfn_core_job.JobDef<{
-        message?: string | undefined;
         data?: {
             [x: string]: unknown;
         } | undefined;
+        message?: string | undefined;
         template?: string | undefined;
+        notificationId: number;
         to: string | string[];
+    }, void>;
+    sendBulkEmailItem: _spfn_core_job.JobDef<{
+        html?: string | undefined;
+        text?: string | undefined;
+        replyTo?: string | undefined;
+        subject: string;
+        notificationId: number;
+        to: string[];
+        from: string;
+    }, void>;
+    sendBulkSmsItem: _spfn_core_job.JobDef<{
+        notificationId: number;
+        to: string;
+        message: string;
+    }, void>;
+    sendBulkSlackItem: _spfn_core_job.JobDef<{
+        text?: string | undefined;
+        blocks?: unknown[] | undefined;
         notificationId: number;
+        webhookUrl: string;
     }, void>;
 }>;
 
@@ -1052,4 +1169,4 @@ interface ClickDetail {
  */
 declare function getClickDetails(notificationId: number): Promise<ClickDetail[]>;
 
-export { type CancelResult, type ClickDetail, EmailProvider, type EngagementStats, type ErrorSlackOptions, type FindNotificationsOptions, NOTIFICATION_CHANNELS, NOTIFICATION_STATUSES, type NewNotification, type Notification, NotificationChannel$1 as NotificationChannel, type NotificationStats, type NotificationStatus, SMSProvider, type ScheduleOptions, type ScheduleResult, SendEmailParams, SendResult, SendSMSParams, SendSlackParams, SlackProvider, TRACKING_EVENT_TYPES, TemplateData, TemplateDefinition, type TrackingEvent, type TrackingEventType, type TrackingStats, cancelNotification, cancelNotificationsByReference, cancelScheduledNotification, countNotifications, createErrorSlackNotifier, createNotificationRecord, createScheduledNotification, findNotificationByJobId, findNotifications, findScheduledNotifications, getClickDetails, getEngagementStats, getNotificationStats, getTemplate, getTemplateNames, getTrackingStats, hasTemplate, markNotificationFailed, markNotificationPending, markNotificationSent, notificationJobRouter, notifications, processTrackingHtml, registerBuiltinTemplates, registerEmailProvider, registerFilter, registerSMSProvider, registerSlackProvider, registerTemplate, renderTemplate, scheduleEmail, scheduleSMS, sendEmail, sendEmailBulk, sendSMS, sendSMSBulk, sendScheduledEmailJob, sendScheduledSmsJob, sendSlack, sendSlackBulk, trackingEvents, trackingRouter, updateNotificationJobId };
+export { type BulkEmailOptions, type BulkEmailResult, type BulkSMSOptions, type BulkSMSResult, type BulkSlackOptions, type BulkSlackResult, type CancelResult, type ClickDetail, EmailProvider, type EngagementStats, type ErrorSlackOptions, type FindNotificationsOptions, NOTIFICATION_CHANNELS, NOTIFICATION_STATUSES, type NewNotification, type Notification, NotificationChannel$1 as NotificationChannel, type NotificationStats, type NotificationStatus, SMSProvider, type ScheduleOptions, type ScheduleResult, SendEmailParams, SendResult, SendSMSParams, SendSlackParams, SlackProvider, TRACKING_EVENT_TYPES, TemplateData, TemplateDefinition, type TrackingEvent, type TrackingEventType, type TrackingStats, cancelNotification, cancelNotificationsByReference, cancelScheduledNotification, countNotifications, createErrorSlackNotifier, createNotificationRecord, createScheduledNotification, findNotificationByJobId, findNotifications, findScheduledNotifications, getClickDetails, getEngagementStats, getNotificationStats, getTemplate, getTemplateNames, getTrackingStats, hasTemplate, markNotificationFailed, markNotificationPending, markNotificationSent, notificationJobRouter, notifications, processTrackingHtml, registerBuiltinTemplates, registerEmailProvider, registerFilter, registerSMSProvider, registerSlackProvider, registerTemplate, renderTemplate, scheduleEmail, scheduleSMS, sendBulkEmailItemJob, sendBulkSlackItemJob, sendBulkSmsItemJob, sendEmail, sendEmailBulk, sendSMS, sendSMSBulk, sendScheduledEmailJob, sendScheduledSmsJob, sendSlack, sendSlackBulk, trackingEvents, trackingRouter, updateNotificationJobId };