Fix error handling and improve error messages

- Fix inconsistent error handling in sendEmailTask by re-throwing original Error instances
- Preserve stack traces and error context instead of creating new Error wrappers
- Improve generic error messages in emailProcessor utilities with specific details
- Add actionable guidance for common configuration issues
- Help developers understand what went wrong and how to fix it
- Bump version to 0.4.1

package.json

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

src/jobs/sendEmailTask.ts

@@ -242,9 +242,11 @@ export const sendEmailJob = {
       }
 
     } catch (error) {
+      // Re-throw Error instances to preserve stack trace and error context
       if (error instanceof Error) {
-        throw new Error(`Failed to process email: ${error.message}`, { cause: error })
+        throw error
       } else {
+        // Only wrap non-Error values
         throw new Error(`Failed to process email: ${String(error)}`)
       }
     }

src/utils/emailProcessor.ts

@@ -10,8 +10,19 @@ export async function processEmailById(payload: Payload, emailId: string): Promi
   // Get mailing context from payload
   const mailingContext = (payload as any).mailing
 
-  if (!mailingContext || !mailingContext.service) {
+  if (!mailingContext) {
-    throw new Error('Mailing plugin not properly initialized')
+    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
@@ -27,8 +38,19 @@ export async function processAllEmails(payload: Payload): Promise<void> {
   // Get mailing context from payload
   const mailingContext = (payload as any).mailing
 
-  if (!mailingContext || !mailingContext.service) {
+  if (!mailingContext) {
-    throw new Error('Mailing plugin not properly initialized')
+    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