Merge pull request #43 from xtr-dev/dev

Remove verbose initialization logs

DEVELOPMENT.md

@@ -126,9 +126,10 @@ When you start the dev server, look for these messages:
 🎯 Test interface will be available at: /mailing-test
 
 ✅ Example email templates created successfully
-PayloadCMS Mailing Plugin initialized successfully
 ```
 
+**Note**: The plugin initializes silently on success (no "initialized successfully" message). If you see no errors, the plugin loaded correctly.
+
 ## Troubleshooting
 
 ### Server won't start

README.md

@@ -380,9 +380,9 @@ await processEmails(payload)
 await retryFailedEmails(payload)
 ```
 
-## PayloadCMS Task Integration
+## PayloadCMS Integration
 
-The plugin provides a ready-to-use PayloadCMS task for queuing template emails:
+The plugin provides PayloadCMS tasks for email processing:
 
 ### 1. Add the task to your Payload config
 
@@ -455,6 +455,27 @@ The task can also be triggered from the Payload admin panel with a user-friendly
 - ✅ **Error Handling**: Comprehensive error reporting
 - ✅ **Queue Management**: Leverage Payload's job queue system
 
+### Immediate Processing
+
+The send email task now supports immediate processing. Enable the `processImmediately` option to send emails instantly:
+
+```typescript
+await payload.jobs.queue({
+  task: 'send-email',
+  input: {
+    processImmediately: true, // Send immediately (default: false)
+    templateSlug: 'welcome-email',
+    to: ['user@example.com'],
+    variables: { name: 'John' }
+  }
+})
+```
+
+**Benefits**:
+- No separate workflow needed
+- Unified task interface
+- Optional immediate processing when needed
+
 ## Job Processing
 
 The plugin automatically adds a unified email processing job to PayloadCMS:

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xtr-dev/payload-mailing",
-  "version": "0.2.0",
+  "version": "0.4.3",
   "description": "Template-based email system with scheduling and job processing for PayloadCMS",
   "type": "module",
   "main": "dist/index.js",

src/index.ts

@@ -27,3 +27,6 @@ export {
   retryFailedEmails,
   parseAndValidateEmails,
 } from './utils/helpers.js'
+
+// Email processing utilities
+export { processEmailById, processAllEmails } from './utils/emailProcessor.js'

src/jobs/index.ts

@@ -1,35 +1,14 @@
-import { processEmailsJob, ProcessEmailsJobData } from './processEmailsJob.js'
+import { processEmailsJob } from './processEmailsTask.js'
 import { sendEmailJob } from './sendEmailTask.js'
-import { MailingService } from '../services/MailingService.js'
 
+/**
+ * All mailing-related jobs that get registered with Payload
+ */
 export const mailingJobs = [
-  {
+  processEmailsJob,
-    slug: 'processEmails',
-    handler: async ({ job, req }: { job: any; req: any }) => {
-      // Get mailing context from payload
-      const payload = (req as any).payload
-      const mailingContext = payload.mailing
-      if (!mailingContext) {
-        throw new Error('Mailing plugin not properly initialized')
-      }
-
-      // Use the existing mailing service from context
-      await processEmailsJob(
-        job as { data: ProcessEmailsJobData },
-        { req, mailingService: mailingContext.service }
-      )
-
-      return {
-        output: {
-          success: true,
-          message: 'Email queue processing completed successfully'
-        }
-      }
-    },
-    interfaceName: 'ProcessEmailsJob',
-  },
   sendEmailJob,
 ]
 
-export * from './processEmailsJob.js'
+// Re-export everything from individual job files
+export * from './processEmailsTask.js'
 export * from './sendEmailTask.js'

src/jobs/processEmailsJob.ts

@@ -1,50 +0,0 @@
-import type { PayloadRequest } from 'payload'
-import { MailingService } from '../services/MailingService.js'
-
-export interface ProcessEmailsJobData {
-  // No type needed - always processes both pending and failed emails
-}
-
-export const processEmailsJob = async (
-  job: { data: ProcessEmailsJobData },
-  context: { req: PayloadRequest; mailingService: MailingService }
-) => {
-  const { mailingService } = context
-
-  try {
-    console.log('🔄 Processing email queue (pending + failed emails)...')
-
-    // Process pending emails first
-    await mailingService.processEmails()
-
-    // Then retry failed emails
-    await mailingService.retryFailedEmails()
-
-    console.log('✅ Email queue processing completed successfully (pending and failed emails)')
-  } catch (error) {
-    console.error('❌ Email queue processing failed:', error)
-    throw error
-  }
-}
-
-export const scheduleEmailsJob = async (
-  payload: any,
-  queueName: string,
-  delay?: number
-) => {
-  if (!payload.jobs) {
-    console.warn('PayloadCMS jobs not configured - emails will not be processed automatically')
-    return
-  }
-
-  try {
-    await payload.jobs.queue({
-      queue: queueName,
-      task: 'processEmails',
-      input: {},
-      waitUntil: delay ? new Date(Date.now() + delay) : undefined,
-    })
-  } catch (error) {
-    console.error('Failed to schedule email processing job:', error)
-  }
-}

src/jobs/processEmailsTask.ts

@@ -0,0 +1,93 @@
+import type { PayloadRequest, Payload } from 'payload'
+import { processAllEmails } from '../utils/emailProcessor.js'
+
+/**
+ * Data passed to the process emails task
+ */
+export interface ProcessEmailsTaskData {
+  // Currently no data needed - always processes both pending and failed emails
+}
+
+/**
+ * Handler function for processing emails
+ * Used internally by the task definition
+ */
+export const processEmailsTaskHandler = async (
+  job: { data: ProcessEmailsTaskData },
+  context: { req: PayloadRequest }
+) => {
+  const { req } = context
+  const payload = (req as any).payload
+
+  try {
+    console.log('🔄 Processing email queue (pending + failed emails)...')
+
+    // Use the shared email processing logic
+    await processAllEmails(payload)
+
+    console.log('✅ Email queue processing completed successfully')
+  } catch (error) {
+    console.error('❌ Email queue processing failed:', error)
+    throw error
+  }
+}
+
+/**
+ * Task definition for processing emails
+ * This is what gets registered with Payload's job system
+ */
+export const processEmailsTask = {
+  slug: 'process-emails',
+  handler: async ({ job, req }: { job: any; req: any }) => {
+    // Get mailing context from payload
+    const payload = (req as any).payload
+    const mailingContext = payload.mailing
+
+    if (!mailingContext) {
+      throw new Error('Mailing plugin not properly initialized')
+    }
+
+    // Use the task handler
+    await processEmailsTaskHandler(
+      job as { data: ProcessEmailsTaskData },
+      { req }
+    )
+
+    return {
+      output: {
+        success: true,
+        message: 'Email queue processing completed successfully'
+      }
+    }
+  },
+  interfaceName: 'ProcessEmailsTask',
+}
+
+// For backward compatibility, export as processEmailsJob
+export const processEmailsJob = processEmailsTask
+
+/**
+ * Helper function to schedule an email processing job
+ * Used by the plugin during initialization and can be used by developers
+ */
+export const scheduleEmailsJob = async (
+  payload: Payload,
+  queueName: string,
+  delay?: number
+) => {
+  if (!payload.jobs) {
+    console.warn('PayloadCMS jobs not configured - emails will not be processed automatically')
+    return
+  }
+
+  try {
+    await payload.jobs.queue({
+      queue: queueName,
+      task: 'process-emails',
+      input: {},
+      waitUntil: delay ? new Date(Date.now() + delay) : undefined,
+    } as any)
+  } catch (error) {
+    console.error('Failed to schedule email processing job:', error)
+  }
+}

src/jobs/sendEmailTask.ts

@@ -1,5 +1,6 @@
 import { sendEmail } from '../sendEmail.js'
 import { BaseEmailDocument } from '../types/index.js'
+import { processEmailById } from '../utils/emailProcessor.js'
 
 export interface SendEmailTaskInput {
   // Template mode fields
@@ -20,6 +21,7 @@ export interface SendEmailTaskInput {
   replyTo?: string
   scheduledAt?: string | Date // ISO date string or Date object
   priority?: number
+  processImmediately?: boolean // If true, process the email immediately instead of waiting for the queue
 
   // Allow any additional fields that users might have in their email collection
   [key: string]: any
@@ -44,8 +46,8 @@ function transformTaskInputToSendEmailOptions(taskInput: SendEmailTaskInput) {
   // Standard email fields that should be copied to data
   const standardFields = ['to', 'cc', 'bcc', 'from', 'fromName', 'replyTo', 'subject', 'html', 'text', 'scheduledAt', 'priority']
 
-  // Template-specific fields that should not be copied to data
+  // Fields that should not be copied to data
-  const templateFields = ['templateSlug', 'variables']
+  const excludedFields = ['templateSlug', 'variables', 'processImmediately']
 
   // Copy standard fields to data
   standardFields.forEach(field => {
@@ -54,9 +56,9 @@ function transformTaskInputToSendEmailOptions(taskInput: SendEmailTaskInput) {
     }
   })
 
-  // Copy any additional custom fields that aren't template or standard fields
+  // Copy any additional custom fields that aren't excluded or standard fields
   Object.keys(taskInput).forEach(key => {
-    if (!templateFields.includes(key) && !standardFields.includes(key)) {
+    if (!excludedFields.includes(key) && !standardFields.includes(key)) {
       sendEmailOptions.data[key] = taskInput[key]
     }
   })
@@ -64,10 +66,23 @@ function transformTaskInputToSendEmailOptions(taskInput: SendEmailTaskInput) {
   return sendEmailOptions
 }
 
+/**
+ * Job definition for sending emails
+ * Can be used through Payload's job queue system to send emails programmatically
+ */
 export const sendEmailJob = {
   slug: 'send-email',
   label: 'Send Email',
   inputSchema: [
+    {
+      name: 'processImmediately',
+      type: 'checkbox' as const,
+      label: 'Process Immediately',
+      defaultValue: false,
+      admin: {
+        description: 'Process and send the email immediately instead of waiting for the queue processor'
+      }
+    },
     {
       name: 'templateSlug',
       type: 'text' as const,
@@ -167,7 +182,8 @@ export const sendEmailJob = {
       type: 'date' as const,
       label: 'Schedule For',
       admin: {
-        description: 'Optional date/time to schedule email for future delivery'
+        description: 'Optional date/time to schedule email for future delivery',
+        condition: (data: any) => !data.processImmediately
       }
     },
     {
@@ -191,6 +207,7 @@ export const sendEmailJob = {
   handler: async ({ input, payload }: any) => {
     // Cast input to our expected type
     const taskInput = input as SendEmailTaskInput
+    const shouldProcessImmediately = taskInput.processImmediately || false
 
     try {
       // Transform task input into sendEmail options using helper function
@@ -199,22 +216,38 @@ export const sendEmailJob = {
       // Use the sendEmail helper to create the email
       const email = await sendEmail<BaseEmailDocument>(payload, sendEmailOptions)
 
+      // If processImmediately is true, process the email now
+      if (shouldProcessImmediately) {
+        console.log(`⚡ Processing email ${email.id} immediately...`)
+        await processEmailById(payload, String(email.id))
+        console.log(`✅ Email ${email.id} processed and sent immediately`)
+
         return {
           output: {
             success: true,
             id: email.id,
+            status: 'sent',
+            processedImmediately: true
+          }
+        }
+      }
+
+      return {
+        output: {
+          success: true,
+          id: email.id,
+          status: 'queued',
+          processedImmediately: false
         }
       }
 
     } catch (error) {
+      // Re-throw Error instances to preserve stack trace and error context
       if (error instanceof Error) {
-        // Preserve original error and stack trace
+        throw error
-        const wrappedError = new Error(`Failed to queue email: ${error.message}`)
-        wrappedError.stack = error.stack
-        wrappedError.cause = error
-        throw wrappedError
       } else {
-        throw new Error(`Failed to queue email: ${String(error)}`)
+        // Only wrap non-Error values
+        throw new Error(`Failed to process email: ${String(error)}`)
       }
     }
   }

src/plugin.ts

@@ -106,12 +106,9 @@ export const mailingPlugin = (pluginConfig: MailingPluginConfig) => (config: Con
         },
       } as MailingContext
 
-      console.log('PayloadCMS Mailing Plugin initialized successfully')
-
       // Schedule the initial email processing job
       try {
         await scheduleEmailsJob(payload, queueName, 60000) // Schedule in 1 minute
-        console.log(`🔄 Scheduled initial email processing job in queue: ${queueName}`)
       } catch (error) {
         console.error('Failed to schedule email processing job:', error)
       }

src/services/MailingService.ts

@@ -225,7 +225,7 @@ export class MailingService implements IMailingService {
     }
   }
 
-  private async processEmailItem(emailId: string): Promise<void> {
+  async processEmailItem(emailId: string): Promise<void> {
     try {
       await this.payload.update({
         collection: this.emailsCollection as any,

src/types/index.ts

@@ -111,6 +111,7 @@ export interface TemplateVariables {
 
 export interface MailingService {
   processEmails(): Promise<void>
+  processEmailItem(emailId: string): Promise<void>
   retryFailedEmails(): Promise<void>
   renderTemplate(templateSlug: string, variables: TemplateVariables): Promise<{ html: string; text: string; subject: string }>
 }

src/utils/emailProcessor.ts

@@ -0,0 +1,61 @@
+import type { Payload } from 'payload'
+
+/**
+ * Processes a single email by ID using the mailing service
+ * @param payload Payload instance
+ * @param emailId The ID of the email to process
+ * @returns Promise that resolves when email is processed
+ */
+export async function processEmailById(payload: Payload, emailId: string): Promise<void> {
+  // Get mailing context from payload
+  const mailingContext = (payload as any).mailing
+
+  if (!mailingContext) {
+    throw new Error(
+      'Mailing plugin not found on payload instance. ' +
+      'Ensure the mailingPlugin is properly configured in your Payload config plugins array.'
+    )
+  }
+
+  if (!mailingContext.service) {
+    throw new Error(
+      'Mailing service not available. ' +
+      'The plugin may not have completed initialization. ' +
+      'Check that email configuration is properly set up in your Payload config.'
+    )
+  }
+
+  // Process the specific email
+  await mailingContext.service.processEmailItem(emailId)
+}
+
+/**
+ * Processes all pending and failed emails using the mailing service
+ * @param payload Payload instance
+ * @returns Promise that resolves when all emails are processed
+ */
+export async function processAllEmails(payload: Payload): Promise<void> {
+  // Get mailing context from payload
+  const mailingContext = (payload as any).mailing
+
+  if (!mailingContext) {
+    throw new Error(
+      'Mailing plugin not found on payload instance. ' +
+      'Ensure the mailingPlugin is properly configured in your Payload config plugins array.'
+    )
+  }
+
+  if (!mailingContext.service) {
+    throw new Error(
+      'Mailing service not available. ' +
+      'The plugin may not have completed initialization. ' +
+      'Check that email configuration is properly set up in your Payload config.'
+    )
+  }
+
+  // Process pending emails first
+  await mailingContext.service.processEmails()
+
+  // Then retry failed emails
+  await mailingContext.service.retryFailedEmails()
+}