@mobilizehub/payload-plugin 0.0.1 → 0.2.0

package/dist/tasks/sendBroadcastsTask.js

@@ -0,0 +1,196 @@
+import z from 'zod';
+/**
+ * Schema for validating broadcast documents before processing.
+ */ const BroadcastSchema = z.object({
+    id: z.number(),
+    content: z.any().refine((val)=>val !== undefined && val !== null, {
+        message: 'Broadcast content is missing'
+    }),
+    fromAddress: z.email({
+        message: 'Invalid from address email format'
+    }),
+    fromName: z.string().min(1, {
+        message: 'From name is required'
+    }),
+    meta: z.object({
+        contactsCount: z.number().min(0),
+        lastProcessedContactId: z.number().min(0).default(0),
+        processedCount: z.number().min(0)
+    }),
+    subject: z.string().min(1, {
+        message: 'Subject is required'
+    }),
+    tags: z.array(z.any()).optional(),
+    to: z.literal('all').or(z.literal('tags'))
+});
+/**
+ * Validates a broadcast document against the schema.
+ * Returns typed data on success, or flattened field errors on failure.
+ */ function safeParseBroadcast(broadcast) {
+    const result = BroadcastSchema.safeParse(broadcast);
+    if (!result.success) {
+        return {
+            data: null,
+            errors: z.flattenError(result.error).fieldErrors,
+            success: false
+        };
+    }
+    return {
+        data: result.data,
+        success: true
+    };
+}
+/**
+ * Builds the where clause for fetching the next batch of contacts.
+ * Uses cursor-based pagination (id > lastProcessedContactId) for consistent
+ * ordering and efficient queries at scale.
+ */ function buildContactsWhereClause(broadcast, rawBroadcast) {
+    const conditions = [
+        {
+            emailOptIn: {
+                equals: true
+            }
+        },
+        {
+            id: {
+                greater_than: broadcast.meta.lastProcessedContactId
+            }
+        }
+    ];
+    // Tags may be populated objects or raw IDs depending on query depth
+    if (broadcast.to === 'tags' && Array.isArray(rawBroadcast.tags) && rawBroadcast.tags.length > 0) {
+        const tagIds = rawBroadcast.tags.map((t)=>typeof t === 'object' ? t.id : t);
+        conditions.push({
+            tags: {
+                in: tagIds
+            }
+        });
+    }
+    return {
+        and: conditions
+    };
+}
+/**
+ * Extracts a numeric ID from a contact, handling string IDs from some database adapters.
+ */ function getLastContactId(contact) {
+    return typeof contact.id === 'number' ? contact.id : parseInt(contact.id, 10);
+}
+/**
+ * Creates the send-broadcasts scheduled task.
+ *
+ * Processes broadcasts by polling for documents with status 'sending' and
+ * queuing batches of send-email jobs. Each invocation processes one broadcast
+ * and one batch of contacts, allowing the task to be distributed across
+ * multiple schedule intervals.
+ */ export const createSendBroadcastsTask = (pluginConfig)=>{
+    const BATCH_SIZE = pluginConfig.broadcastConfig?.batchSize || 100;
+    const TASK_SCHEDULE = pluginConfig.broadcastConfig?.taskSchedule || '*/5 * * * *';
+    const QUEUE_NAME = pluginConfig.broadcastConfig?.broadcastQueueName || 'send-broadcasts';
+    return {
+        slug: 'send-broadcasts',
+        handler: async ({ req })=>{
+            const { payload } = req;
+            const logger = payload.logger;
+            logger.info('Send Broadcast task handler called');
+            const { docs } = await payload.find({
+                collection: 'broadcasts',
+                limit: 1,
+                sort: 'id',
+                where: {
+                    status: {
+                        equals: 'sending'
+                    }
+                }
+            });
+            const rawBroadcast = docs[0];
+            if (!rawBroadcast) {
+                logger.info('No broadcasts with status "sending" found');
+                return {
+                    output: {
+                        success: true
+                    }
+                };
+            }
+            const parsed = safeParseBroadcast(rawBroadcast);
+            if (!parsed.success) {
+                logger.error({
+                    errors: parsed.errors
+                }, `Broadcast ${rawBroadcast.id} validation failed`);
+                await payload.update({
+                    id: rawBroadcast.id,
+                    collection: 'broadcasts',
+                    data: {
+                        status: 'failed'
+                    }
+                });
+                return {
+                    output: {
+                        success: false
+                    }
+                };
+            }
+            const broadcast = parsed.data;
+            const whereClause = buildContactsWhereClause(broadcast, rawBroadcast);
+            const { docs: contacts } = await payload.find({
+                collection: 'contacts',
+                limit: BATCH_SIZE,
+                sort: 'id',
+                where: whereClause
+            });
+            if (contacts.length === 0) {
+                logger.info(`Broadcast ${broadcast.id} complete. ` + `Processed: ${broadcast.meta.processedCount}, Expected: ${broadcast.meta.contactsCount}`);
+                await payload.update({
+                    id: broadcast.id,
+                    collection: 'broadcasts',
+                    data: {
+                        status: 'sent'
+                    }
+                });
+                return {
+                    output: {
+                        success: true
+                    }
+                };
+            }
+            await Promise.all(contacts.map((contact)=>payload.jobs.queue({
+                    input: {
+                        broadcastId: broadcast.id,
+                        contactId: contact.id
+                    },
+                    queue: 'send-emails',
+                    task: 'send-email'
+                })));
+            await payload.update({
+                id: broadcast.id,
+                collection: 'broadcasts',
+                data: {
+                    meta: {
+                        lastProcessedContactId: getLastContactId(contacts[contacts.length - 1]),
+                        processedCount: broadcast.meta.processedCount + contacts.length
+                    }
+                }
+            });
+            logger.info(`Broadcast ${broadcast.id}: queued ${contacts.length} emails, ` + `total processed: ${broadcast.meta.processedCount + contacts.length}`);
+            return {
+                output: {
+                    success: true
+                }
+            };
+        },
+        outputSchema: [
+            {
+                name: 'success',
+                type: 'checkbox'
+            }
+        ],
+        retries: 3,
+        schedule: [
+            {
+                cron: TASK_SCHEDULE,
+                queue: QUEUE_NAME
+            }
+        ]
+    };
+};
+
+//# sourceMappingURL=sendBroadcastsTask.js.map

package/dist/tasks/sendBroadcastsTask.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/tasks/sendBroadcastsTask.ts"],"sourcesContent":["import type { TaskConfig, Where } from 'payload'\n\nimport z from 'zod'\n\nimport type { MobilizehubPluginConfig } from '../types/index.js'\n\n/**\n * Schema for validating broadcast documents before processing.\n */\nconst BroadcastSchema = z.object({\n  id: z.number(),\n  content: z.any().refine((val) => val !== undefined && val !== null, {\n    message: 'Broadcast content is missing',\n  }),\n  fromAddress: z.email({ message: 'Invalid from address email format' }),\n  fromName: z.string().min(1, { message: 'From name is required' }),\n  meta: z.object({\n    contactsCount: z.number().min(0),\n    lastProcessedContactId: z.number().min(0).default(0),\n    processedCount: z.number().min(0),\n  }),\n  subject: z.string().min(1, { message: 'Subject is required' }),\n  tags: z.array(z.any()).optional(),\n  to: z.literal('all').or(z.literal('tags')),\n})\n\ntype ParsedBroadcast = z.infer<typeof BroadcastSchema>\n\n/**\n * Validates a broadcast document against the schema.\n * Returns typed data on success, or flattened field errors on failure.\n */\nfunction safeParseBroadcast(broadcast: unknown) {\n  const result = BroadcastSchema.safeParse(broadcast)\n\n  if (!result.success) {\n    return {\n      data: null,\n      errors: z.flattenError(result.error).fieldErrors,\n      success: false as const,\n    }\n  }\n\n  return {\n    data: result.data,\n    success: true as const,\n  }\n}\n\n/**\n * Builds the where clause for fetching the next batch of contacts.\n * Uses cursor-based pagination (id > lastProcessedContactId) for consistent\n * ordering and efficient queries at scale.\n */\nfunction buildContactsWhereClause(\n  broadcast: ParsedBroadcast,\n  rawBroadcast: Record<string, unknown>,\n): Where {\n  const conditions: Where[] = [\n    { emailOptIn: { equals: true } },\n    { id: { greater_than: broadcast.meta.lastProcessedContactId } },\n  ]\n\n  // Tags may be populated objects or raw IDs depending on query depth\n  if (broadcast.to === 'tags' && Array.isArray(rawBroadcast.tags) && rawBroadcast.tags.length > 0) {\n    const tagIds = rawBroadcast.tags.map((t: { id: number | string } | number | string) =>\n      typeof t === 'object' ? t.id : t,\n    )\n    conditions.push({ tags: { in: tagIds } })\n  }\n\n  return { and: conditions }\n}\n\n/**\n * Extracts a numeric ID from a contact, handling string IDs from some database adapters.\n */\nfunction getLastContactId(contact: { id: number | string }): number {\n  return typeof contact.id === 'number' ? contact.id : parseInt(contact.id, 10)\n}\n\n/**\n * Creates the send-broadcasts scheduled task.\n *\n * Processes broadcasts by polling for documents with status 'sending' and\n * queuing batches of send-email jobs. Each invocation processes one broadcast\n * and one batch of contacts, allowing the task to be distributed across\n * multiple schedule intervals.\n */\nexport const createSendBroadcastsTask = (pluginConfig: MobilizehubPluginConfig): TaskConfig => {\n  const BATCH_SIZE = pluginConfig.broadcastConfig?.batchSize || 100\n  const TASK_SCHEDULE = pluginConfig.broadcastConfig?.taskSchedule || '*/5 * * * *'\n  const QUEUE_NAME = pluginConfig.broadcastConfig?.broadcastQueueName || 'send-broadcasts'\n\n  return {\n    slug: 'send-broadcasts',\n    handler: async ({ req }) => {\n      const { payload } = req\n      const logger = payload.logger\n\n      logger.info('Send Broadcast task handler called')\n\n      const { docs } = await payload.find({\n        collection: 'broadcasts',\n        limit: 1,\n        sort: 'id',\n        where: { status: { equals: 'sending' } },\n      })\n\n      const rawBroadcast = docs[0]\n\n      if (!rawBroadcast) {\n        logger.info('No broadcasts with status \"sending\" found')\n        return { output: { success: true } }\n      }\n\n      const parsed = safeParseBroadcast(rawBroadcast)\n\n      if (!parsed.success) {\n        logger.error({ errors: parsed.errors }, `Broadcast ${rawBroadcast.id} validation failed`)\n        await payload.update({\n          id: rawBroadcast.id,\n          collection: 'broadcasts',\n          data: { status: 'failed' },\n        })\n        return { output: { success: false } }\n      }\n\n      const broadcast = parsed.data\n      const whereClause = buildContactsWhereClause(\n        broadcast,\n        rawBroadcast as Record<string, unknown>,\n      )\n\n      const { docs: contacts } = await payload.find({\n        collection: 'contacts',\n        limit: BATCH_SIZE,\n        sort: 'id',\n        where: whereClause,\n      })\n\n      if (contacts.length === 0) {\n        logger.info(\n          `Broadcast ${broadcast.id} complete. ` +\n            `Processed: ${broadcast.meta.processedCount}, Expected: ${broadcast.meta.contactsCount}`,\n        )\n        await payload.update({\n          id: broadcast.id,\n          collection: 'broadcasts',\n          data: { status: 'sent' },\n        })\n        return { output: { success: true } }\n      }\n\n      await Promise.all(\n        contacts.map((contact) =>\n          payload.jobs.queue({\n            input: { broadcastId: broadcast.id, contactId: contact.id },\n            queue: 'send-emails',\n            task: 'send-email',\n          }),\n        ),\n      )\n\n      await payload.update({\n        id: broadcast.id,\n        collection: 'broadcasts',\n        data: {\n          meta: {\n            lastProcessedContactId: getLastContactId(contacts[contacts.length - 1]),\n            processedCount: broadcast.meta.processedCount + contacts.length,\n          },\n        },\n      })\n\n      logger.info(\n        `Broadcast ${broadcast.id}: queued ${contacts.length} emails, ` +\n          `total processed: ${broadcast.meta.processedCount + contacts.length}`,\n      )\n\n      return { output: { success: true } }\n    },\n    outputSchema: [\n      {\n        name: 'success',\n        type: 'checkbox',\n      },\n    ],\n    retries: 3,\n    schedule: [\n      {\n        cron: TASK_SCHEDULE,\n        queue: QUEUE_NAME,\n      },\n    ],\n  }\n}\n"],"names":["z","BroadcastSchema","object","id","number","content","any","refine","val","undefined","message","fromAddress","email","fromName","string","min","meta","contactsCount","lastProcessedContactId","default","processedCount","subject","tags","array","optional","to","literal","or","safeParseBroadcast","broadcast","result","safeParse","success","data","errors","flattenError","error","fieldErrors","buildContactsWhereClause","rawBroadcast","conditions","emailOptIn","equals","greater_than","Array","isArray","length","tagIds","map","t","push","in","and","getLastContactId","contact","parseInt","createSendBroadcastsTask","pluginConfig","BATCH_SIZE","broadcastConfig","batchSize","TASK_SCHEDULE","taskSchedule","QUEUE_NAME","broadcastQueueName","slug","handler","req","payload","logger","info","docs","find","collection","limit","sort","where","status","output","parsed","update","whereClause","contacts","Promise","all","jobs","queue","input","broadcastId","contactId","task","outputSchema","name","type","retries","schedule","cron"],"mappings":"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"}

package/dist/tasks/sendEmailTask.d.ts

@@ -0,0 +1,9 @@
+import type { TaskConfig } from 'payload';
+import type { MobilizehubPluginConfig } from '../types/index.js';
+/**
+ * Creates the send-email task configuration.
+ *
+ * Handles delivery of a single email for one contact within a broadcast.
+ * Queued by the send-broadcasts task, one job per contact.
+ */
+export declare const createSendEmailTask: (pluginConfig: MobilizehubPluginConfig) => TaskConfig;

package/dist/tasks/sendEmailTask.js

@@ -0,0 +1,167 @@
+import { formatFromAddress } from '../utils/email.js';
+import { parseLexicalContent } from '../utils/lexical.js';
+import { generateUnsubscribeToken } from '../utils/unsubscribe-token.js';
+/**
+ * Resolves collection slugs from plugin config, falling back to defaults.
+ */ function getCollectionSlugs(config) {
+    return {
+        broadcasts: config.broadcastsOverrides?.slug || 'broadcasts',
+        contacts: config.contactsOverrides?.slug || 'contacts',
+        emails: config.emailsOverrides?.slug || 'emails'
+    };
+}
+/**
+ * Checks if an email record already exists for a broadcast-contact pair.
+ */ async function checkEmailExists(payload, collection, broadcastId, contactId) {
+    const { docs } = await payload.find({
+        collection,
+        limit: 1,
+        where: {
+            and: [
+                {
+                    broadcast: {
+                        equals: broadcastId
+                    }
+                },
+                {
+                    contact: {
+                        equals: contactId
+                    }
+                }
+            ]
+        }
+    });
+    return docs[0] ?? null;
+}
+/**
+ * Creates the send-email task configuration.
+ *
+ * Handles delivery of a single email for one contact within a broadcast.
+ * Queued by the send-broadcasts task, one job per contact.
+ */ export const createSendEmailTask = (pluginConfig)=>{
+    const collections = getCollectionSlugs(pluginConfig);
+    return {
+        slug: 'send-email',
+        handler: async ({ input, req })=>{
+            const { payload } = req;
+            const logger = payload.logger;
+            const { broadcastId, contactId } = input;
+            // Skip if already processed (handles job retries)
+            const existingEmail = await checkEmailExists(payload, collections.emails, broadcastId, contactId);
+            if (existingEmail) {
+                logger.info(`Email already exists for broadcast ${broadcastId}, contact ${contactId} ` + `(email ID: ${existingEmail.id}, status: ${existingEmail.status})`);
+                return {
+                    output: {
+                        success: true
+                    }
+                };
+            }
+            const [contact, broadcast] = await Promise.all([
+                payload.findByID({
+                    id: contactId,
+                    collection: collections.contacts
+                }),
+                payload.findByID({
+                    id: broadcastId,
+                    collection: collections.broadcasts
+                })
+            ]);
+            if (!contact) {
+                throw new Error(`Contact ${contactId} not found`);
+            }
+            if (!broadcast) {
+                throw new Error(`Broadcast ${broadcastId} not found`);
+            }
+            const sender = pluginConfig.email({
+                payload
+            });
+            const fromAddress = formatFromAddress(broadcast.fromName, broadcast.fromAddress);
+            const tokenId = crypto.randomUUID();
+            const unsubscribeToken = generateUnsubscribeToken({
+                tokenId
+            });
+            const parsedContent = await parseLexicalContent(broadcast.content, payload.config);
+            const html = sender.render({
+                from: fromAddress,
+                html: parsedContent.html,
+                markdown: parsedContent.markdown,
+                plainText: parsedContent.plainText,
+                subject: broadcast.subject,
+                to: contact.email,
+                token: unsubscribeToken
+            });
+            const email = await payload.create({
+                collection: collections.emails,
+                data: {
+                    broadcast: broadcast.id,
+                    contact: contact.id,
+                    from: fromAddress,
+                    html,
+                    status: 'queued',
+                    subject: broadcast.subject,
+                    to: contact.email
+                }
+            });
+            await payload.create({
+                collection: 'emailUnsubscribeTokens',
+                data: {
+                    id: tokenId,
+                    emailId: email.id
+                }
+            });
+            const result = await sender.sendEmail({
+                from: fromAddress,
+                html,
+                idempotencyKey: `broadcast-${broadcastId}-contact-${contactId}`,
+                markdown: parsedContent.markdown,
+                plainText: parsedContent.plainText,
+                previewText: broadcast.previewText,
+                replyTo: broadcast.replyTo,
+                subject: broadcast.subject,
+                to: contact.email,
+                token: unsubscribeToken
+            });
+            await payload.update({
+                id: email.id,
+                collection: collections.emails,
+                data: {
+                    activity: [
+                        {
+                            type: 'sent',
+                            timestamp: new Date().toISOString()
+                        }
+                    ],
+                    providerId: result?.providerId,
+                    status: 'sent'
+                }
+            });
+            logger.info(`Sent email ${email.id} for broadcast ${broadcastId} to ${contact.email}`);
+            return {
+                output: {
+                    success: true
+                }
+            };
+        },
+        inputSchema: [
+            {
+                name: 'contactId',
+                type: 'number',
+                required: true
+            },
+            {
+                name: 'broadcastId',
+                type: 'number',
+                required: true
+            }
+        ],
+        outputSchema: [
+            {
+                name: 'success',
+                type: 'checkbox'
+            }
+        ],
+        retries: 3
+    };
+};
+
+//# sourceMappingURL=sendEmailTask.js.map

package/dist/tasks/sendEmailTask.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/tasks/sendEmailTask.ts"],"sourcesContent":["import type { SerializedEditorState } from '@payloadcms/richtext-lexical/lexical'\nimport type { BasePayload, TaskConfig } from 'payload'\n\nimport type { MobilizehubPluginConfig } from '../types/index.js'\n\nimport { formatFromAddress } from '../utils/email.js'\nimport { parseLexicalContent } from '../utils/lexical.js'\nimport { generateUnsubscribeToken } from '../utils/unsubscribe-token.js'\n\n/**\n * Resolves collection slugs from plugin config, falling back to defaults.\n */\nfunction getCollectionSlugs(config: MobilizehubPluginConfig) {\n  return {\n    broadcasts: config.broadcastsOverrides?.slug || 'broadcasts',\n    contacts: config.contactsOverrides?.slug || 'contacts',\n    emails: config.emailsOverrides?.slug || 'emails',\n  }\n}\n\n/**\n * Checks if an email record already exists for a broadcast-contact pair.\n */\nasync function checkEmailExists(\n  payload: BasePayload,\n  collection: string,\n  broadcastId: number | string,\n  contactId: number | string,\n) {\n  const { docs } = await payload.find({\n    collection,\n    limit: 1,\n    where: {\n      and: [{ broadcast: { equals: broadcastId } }, { contact: { equals: contactId } }],\n    },\n  })\n\n  return docs[0] ?? null\n}\n\n/**\n * Creates the send-email task configuration.\n *\n * Handles delivery of a single email for one contact within a broadcast.\n * Queued by the send-broadcasts task, one job per contact.\n */\nexport const createSendEmailTask = (pluginConfig: MobilizehubPluginConfig): TaskConfig => {\n  const collections = getCollectionSlugs(pluginConfig)\n\n  return {\n    slug: 'send-email',\n    handler: async ({ input, req }) => {\n      const { payload } = req\n      const logger = payload.logger\n\n      const { broadcastId, contactId } = input as { broadcastId: number; contactId: number }\n\n      // Skip if already processed (handles job retries)\n      const existingEmail = await checkEmailExists(\n        payload,\n        collections.emails,\n        broadcastId,\n        contactId,\n      )\n\n      if (existingEmail) {\n        logger.info(\n          `Email already exists for broadcast ${broadcastId}, contact ${contactId} ` +\n            `(email ID: ${existingEmail.id}, status: ${existingEmail.status})`,\n        )\n        return { output: { success: true } }\n      }\n\n      const [contact, broadcast] = await Promise.all([\n        payload.findByID({ id: contactId, collection: collections.contacts }),\n        payload.findByID({ id: broadcastId, collection: collections.broadcasts }),\n      ])\n\n      if (!contact) {\n        throw new Error(`Contact ${contactId} not found`)\n      }\n      if (!broadcast) {\n        throw new Error(`Broadcast ${broadcastId} not found`)\n      }\n\n      const sender = pluginConfig.email({ payload })\n      const fromAddress = formatFromAddress(broadcast.fromName, broadcast.fromAddress)\n\n      const tokenId = crypto.randomUUID()\n      const unsubscribeToken = generateUnsubscribeToken({ tokenId })\n\n      const parsedContent = await parseLexicalContent(\n        broadcast.content as SerializedEditorState,\n        payload.config,\n      )\n\n      const html = sender.render({\n        from: fromAddress,\n        html: parsedContent.html,\n        markdown: parsedContent.markdown,\n        plainText: parsedContent.plainText,\n        subject: broadcast.subject,\n        to: contact.email,\n        token: unsubscribeToken,\n      })\n\n      const email = await payload.create({\n        collection: collections.emails,\n        data: {\n          broadcast: broadcast.id,\n          contact: contact.id,\n          from: fromAddress,\n          html,\n          status: 'queued',\n          subject: broadcast.subject,\n          to: contact.email,\n        },\n      })\n\n      await payload.create({\n        collection: 'emailUnsubscribeTokens',\n        data: { id: tokenId, emailId: email.id },\n      })\n\n      const result = await sender.sendEmail({\n        from: fromAddress,\n        html,\n        idempotencyKey: `broadcast-${broadcastId}-contact-${contactId}`,\n        markdown: parsedContent.markdown,\n        plainText: parsedContent.plainText,\n        previewText: broadcast.previewText,\n        replyTo: broadcast.replyTo,\n        subject: broadcast.subject,\n        to: contact.email,\n        token: unsubscribeToken,\n      })\n\n      await payload.update({\n        id: email.id,\n        collection: collections.emails,\n        data: {\n          activity: [{ type: 'sent', timestamp: new Date().toISOString() }],\n          providerId: result?.providerId,\n          status: 'sent',\n        },\n      })\n\n      logger.info(`Sent email ${email.id} for broadcast ${broadcastId} to ${contact.email}`)\n\n      return { output: { success: true } }\n    },\n    inputSchema: [\n      { name: 'contactId', type: 'number', required: true },\n      { name: 'broadcastId', type: 'number', required: true },\n    ],\n    outputSchema: [{ name: 'success', type: 'checkbox' }],\n    retries: 3,\n  }\n}\n"],"names":["formatFromAddress","parseLexicalContent","generateUnsubscribeToken","getCollectionSlugs","config","broadcasts","broadcastsOverrides","slug","contacts","contactsOverrides","emails","emailsOverrides","checkEmailExists","payload","collection","broadcastId","contactId","docs","find","limit","where","and","broadcast","equals","contact","createSendEmailTask","pluginConfig","collections","handler","input","req","logger","existingEmail","info","id","status","output","success","Promise","all","findByID","Error","sender","email","fromAddress","fromName","tokenId","crypto","randomUUID","unsubscribeToken","parsedContent","content","html","render","from","markdown","plainText","subject","to","token","create","data","emailId","result","sendEmail","idempotencyKey","previewText","replyTo","update","activity","type","timestamp","Date","toISOString","providerId","inputSchema","name","required","outputSchema","retries"],"mappings":"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"}

package/dist/types/index.d.ts

@@ -0,0 +1,135 @@
+import type { BasePayload, CollectionConfig, Field, PayloadRequest } from 'payload';
+export type FieldsOverride = (args: {
+    defaultFields: Field[];
+}) => Field[];
+export type CollectionOverride = {
+    fields?: FieldsOverride;
+} & Partial<Omit<CollectionConfig, 'fields'>>;
+/**
+ * Contact type
+ */
+export type Contact = {
+    createdAt?: string;
+    email?: string;
+    emailOptIn: boolean;
+    firstName?: string;
+    id: number | string;
+    lastName?: string;
+    tags?: {
+        createdAt?: string;
+        id: number | string;
+        name?: string;
+        updatedAt?: string;
+    }[];
+    updatedAt?: string;
+};
+/**
+ * Unsubscribe token input structure
+ */
+export interface UnsubscribeTokenInput {
+    timestamp: number;
+    tokenId: string;
+}
+/**
+ * Unsubscribe token record structure
+ */
+export type UnsubscribeTokenRecord = {
+    emailId?: number | string;
+    expiresAt?: string;
+    id: string;
+};
+/**
+ * Email activity types
+ */
+export type EmailStatus = 'bounced' | 'complained' | 'delivered' | 'failed' | 'queued' | 'sent' | 'unsubscribed';
+/**
+ * Email activity types from providers
+ */
+export type EmailActivityType = 'bounced' | 'clicked' | 'complained' | 'delivered' | 'delivery_delayed' | 'failed' | 'opened' | 'received' | 'sent';
+/**
+ * Email message structure
+ */
+export type EmailMessage = {
+    from: string;
+    html: string;
+    idempotencyKey?: string;
+    markdown?: string;
+    plainText?: string;
+    previewText?: string;
+    replyTo?: string;
+    subject: string;
+    to: string;
+    token?: string;
+};
+/**
+ * Result of a webhook call
+ */
+export type WebhookResult = {
+    body?: unknown;
+    status: number;
+};
+/**
+ * Email adapter interface for sending emails
+ */
+export type EmailAdapter = ({ payload }: {
+    payload: BasePayload;
+}) => {
+    defaultFromAddress: string;
+    defaultFromName: string;
+    name: string;
+    render: (args: EmailMessage) => string;
+    sendEmail: (args: EmailMessage) => Promise<{
+        providerId: string;
+    } | void>;
+    webhookHandler?: (req: PayloadRequest) => Promise<void | WebhookResult>;
+};
+export type MobilizehubPluginConfig = {
+    broadcastConfig?: {
+        /**
+         * Batch size for processing contacts in the broadcasts task.
+         * Higher values process faster but use more memory.
+         * @default 100
+         */
+        batchSize?: number;
+        /**
+         * Optional custom queue name for the broadcasts task
+         * @default 'send-broadcasts'
+         */
+        broadcastQueueName?: string;
+        /**
+         * Optional custom queue name for the email sending task
+         * @default 'send-email'
+         */
+        emailQueueName?: string;
+        /**
+         * Cron schedule for the broadcasts task
+         * On schedule the task will run to process and send pending broadcasts
+         * @default '5 * * * *' (every 5 minutes)
+         */
+        taskSchedule?: string;
+    };
+    /**
+     * Overrides for the broadcasts collection
+     */
+    broadcastsOverrides?: CollectionOverride;
+    /**
+     * Overrides for the contacts collection
+     */
+    contactsOverrides?: CollectionOverride;
+    /**
+     * Disable the plugin
+     */
+    disabled?: boolean;
+    /**
+     * Email adapter for sending emails
+     */
+    email: EmailAdapter;
+    /**
+     * Overrides for the emails collection
+     */
+    emailsOverrides?: CollectionOverride;
+    /**
+     * Overrides for the tags collection
+     */
+    tagsOverrides?: CollectionOverride;
+};

package/dist/types/index.js

@@ -0,0 +1,3 @@
+export { };
+
+//# sourceMappingURL=index.js.map

package/dist/types/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/types/index.ts"],"sourcesContent":["import type { BasePayload, CollectionConfig, Field, PayloadRequest } from 'payload'\n\nexport type FieldsOverride = (args: { defaultFields: Field[] }) => Field[]\n\nexport type CollectionOverride = { fields?: FieldsOverride } & Partial<\n  Omit<CollectionConfig, 'fields'>\n>\n\n/**\n * Contact type\n */\nexport type Contact = {\n  createdAt?: string\n  email?: string\n  emailOptIn: boolean\n  firstName?: string\n  id: number | string\n  lastName?: string\n  tags?: {\n    createdAt?: string\n    id: number | string\n    name?: string\n    updatedAt?: string\n  }[]\n  updatedAt?: string\n}\n\n/**\n * Unsubscribe token input structure\n */\nexport interface UnsubscribeTokenInput {\n  timestamp: number\n  tokenId: string\n}\n\n/**\n * Unsubscribe token record structure\n */\nexport type UnsubscribeTokenRecord = {\n  emailId?: number | string\n  expiresAt?: string\n  id: string\n}\n\n/**\n * Email activity types\n */\nexport type EmailStatus =\n  | 'bounced'\n  | 'complained'\n  | 'delivered'\n  | 'failed'\n  | 'queued'\n  | 'sent'\n  | 'unsubscribed'\n\n/**\n * Email activity types from providers\n */\nexport type EmailActivityType =\n  | 'bounced'\n  | 'clicked'\n  | 'complained'\n  | 'delivered'\n  | 'delivery_delayed'\n  | 'failed'\n  | 'opened'\n  | 'received'\n  | 'sent'\n\n/**\n * Email message structure\n */\nexport type EmailMessage = {\n  from: string\n  html: string\n  idempotencyKey?: string\n  markdown?: string\n  plainText?: string\n  previewText?: string\n  replyTo?: string\n  subject: string\n  to: string\n  token?: string\n}\n\n/**\n * Result of a webhook call\n */\nexport type WebhookResult = {\n  body?: unknown\n  status: number\n}\n\n/**\n * Email adapter interface for sending emails\n */\nexport type EmailAdapter = ({ payload }: { payload: BasePayload }) => {\n  defaultFromAddress: string\n  defaultFromName: string\n  name: string\n  render: (args: EmailMessage) => string\n  sendEmail: (args: EmailMessage) => Promise<{ providerId: string } | void>\n  webhookHandler?: (req: PayloadRequest) => Promise<void | WebhookResult>\n}\n\nexport type MobilizehubPluginConfig = {\n  broadcastConfig?: {\n    /**\n     * Batch size for processing contacts in the broadcasts task.\n     * Higher values process faster but use more memory.\n     * @default 100\n     */\n    batchSize?: number\n    /**\n     * Optional custom queue name for the broadcasts task\n     * @default 'send-broadcasts'\n     */\n    broadcastQueueName?: string\n    /**\n     * Optional custom queue name for the email sending task\n     * @default 'send-email'\n     */\n    emailQueueName?: string\n    /**\n     * Cron schedule for the broadcasts task\n     * On schedule the task will run to process and send pending broadcasts\n     * @default '5 * * * *' (every 5 minutes)\n     */\n    taskSchedule?: string\n  }\n  /**\n   * Overrides for the broadcasts collection\n   */\n  broadcastsOverrides?: CollectionOverride\n\n  /**\n   * Overrides for the contacts collection\n   */\n  contactsOverrides?: CollectionOverride\n  /**\n   * Disable the plugin\n   */\n  disabled?: boolean\n  /**\n   * Email adapter for sending emails\n   */\n  email: EmailAdapter\n  /**\n   * Overrides for the emails collection\n   */\n  emailsOverrides?: CollectionOverride\n  /**\n   * Overrides for the tags collection\n   */\n  tagsOverrides?: CollectionOverride\n}\n"],"names":[],"mappings":"AA0GA,WAkDC"}

package/dist/utils/api-response.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Standard API success response format
+ * @template T - Type of the data payload
+ */
+export type ApiSuccessResponse<T = unknown> = {
+    data?: T;
+    success: true;
+};
+/**
+ * Standard API error response format
+ */
+export type ApiErrorResponse = {
+    error: {
+        /** Error code constant (e.g., 'BAD_REQUEST', 'UNAUTHORIZED') */
+        code: string;
+        /** Human-readable error message */
+        message: string;
+    };
+    success: false;
+};
+/**
+ * Union type for all API responses
+ * @template T - Type of the data payload for success responses
+ */
+export type ApiResponse<T = unknown> = ApiErrorResponse | ApiSuccessResponse<T>;
+/**
+ * Create a standardized success response
+ *
+ * @template T - Type of the response data
+ * @param data - Optional data payload to include in the response
+ * @param status - HTTP status code (default: 200)
+ * @returns Response object with JSON body
+ *
+ * @example
+ * ```typescript
+ * return successResponse({ message: 'Email sent successfully' }, 200)
+ * // Returns: { success: true, data: { message: 'Email sent successfully' } }
+ * ```
+ */
+export declare function successResponse<T>(data?: T, status?: number): Response;
+/**
+ * Create a standardized error response
+ *
+ * @param code - Error code from ErrorCodes constant
+ * @param message - Human-readable error message
+ * @param status - HTTP status code (default: 400)
+ * @returns Response object with JSON error body
+ *
+ * @example
+ * ```typescript
+ * return errorResponse(ErrorCodes.UNAUTHORIZED, 'You must be logged in', 401)
+ * // Returns: { success: false, error: { code: 'UNAUTHORIZED', message: '...' } }
+ * ```
+ */
+export declare function errorResponse(code: string, message: string, status?: number): Response;
+/**
+ * Standard error codes used across the MobilizeHub plugin API
+ */
+export declare const ErrorCodes: {
+    readonly BAD_REQUEST: "BAD_REQUEST";
+    readonly BROADCAST_INVALID_STATUS: "BROADCAST_INVALID_STATUS";
+    readonly BROADCAST_NOT_FOUND: "BROADCAST_NOT_FOUND";
+    readonly CONTACT_NOT_FOUND: "CONTACT_NOT_FOUND";
+    readonly EMAIL_SEND_FAILED: "EMAIL_SEND_FAILED";
+    readonly INTERNAL_ERROR: "INTERNAL_ERROR";
+    readonly NOT_FOUND: "NOT_FOUND";
+    readonly RATE_LIMITED: "RATE_LIMITED";
+    readonly TOKEN_EXPIRED: "TOKEN_EXPIRED";
+    readonly TOKEN_INVALID: "TOKEN_INVALID";
+    readonly UNAUTHORIZED: "UNAUTHORIZED";
+    readonly VALIDATION_ERROR: "VALIDATION_ERROR";
+};