Refactor and clean up job organization

- Properly encapsulate processEmailsJob in its own file with handler and definition
- Clean up index.ts to remove duplicate code and just export job definitions
- Add comprehensive JSDoc comments for better documentation
- Separate job handler logic from job definition for clarity
- Fix job scheduling to use correct field names
- Bump version to 0.2.1

package.json

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

src/jobs/index.ts

@@ -1,35 +1,14 @@
-import { processEmailsJob, ProcessEmailsJobData } from './processEmailsJob.js'
+import { processEmailsJob } from './processEmailsJob.js'
 import { sendEmailJob } from './sendEmailTask.js'
-import { MailingService } from '../services/MailingService.js'
 
+/**
+ * All mailing-related jobs that get registered with Payload
+ */
 export const mailingJobs = [
-  {
-    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',
-  },
+  processEmailsJob,
   sendEmailJob,
 ]
 
+// Re-export everything from individual job files
 export * from './processEmailsJob.js'
-export * from './sendEmailTask.js'
+export * from './sendEmailTask.js'

src/jobs/processEmailsJob.ts

@@ -1,11 +1,18 @@
-import type { PayloadRequest } from 'payload'
-import { MailingService } from '../services/MailingService.js'
+import type { PayloadRequest, Payload } from 'payload'
+import type { MailingService } from '../services/MailingService.js'
 
+/**
+ * Data passed to the process emails job
+ */
 export interface ProcessEmailsJobData {
-  // No type needed - always processes both pending and failed emails
+  // Currently no data needed - always processes both pending and failed emails
 }
 
-export const processEmailsJob = async (
+/**
+ * Handler function for processing emails
+ * Used internally by the job definition
+ */
+export const processEmailsJobHandler = async (
   job: { data: ProcessEmailsJobData },
   context: { req: PayloadRequest; mailingService: MailingService }
 ) => {
@@ -20,15 +27,50 @@ export const processEmailsJob = async (
     // Then retry failed emails
     await mailingService.retryFailedEmails()
 
-    console.log('✅ Email queue processing completed successfully (pending and failed emails)')
+    console.log('✅ Email queue processing completed successfully')
   } catch (error) {
     console.error('❌ Email queue processing failed:', error)
     throw error
   }
 }
 
+/**
+ * Job definition for processing emails
+ * This is what gets registered with Payload's job system
+ */
+export const processEmailsJob = {
+  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 existing mailing service from context
+    await processEmailsJobHandler(
+      job as { data: ProcessEmailsJobData },
+      { req, mailingService: mailingContext.service }
+    )
+
+    return {
+      output: {
+        success: true,
+        message: 'Email queue processing completed successfully'
+      }
+    }
+  },
+  interfaceName: 'ProcessEmailsJob',
+}
+
+/**
+ * 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: any,
+  payload: Payload,
   queueName: string,
   delay?: number
 ) => {
@@ -40,10 +82,10 @@ export const scheduleEmailsJob = async (
   try {
     await payload.jobs.queue({
       queue: queueName,
-      task: 'processEmails',
+      workflow: '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

@@ -64,6 +64,10 @@ 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',