payload-plugin-newsletter 0.25.11 → 0.25.13

package/dist/server.d.ts

@@ -1,4 +1,5 @@
-import { Field, Block, RichTextField, Config, Endpoint, CollectionConfig, GlobalConfig } from 'payload';
+import { Field, Block, RichTextField, Payload, Config, Endpoint, CollectionConfig, GlobalConfig } from 'payload';
+import { SerializedEditorState } from 'lexical';
 
 /**
  * Core types for broadcast management functionality
@@ -632,6 +633,96 @@ interface SurveyQuestion {
     required?: boolean;
 }
 
+/**
+ * Recursively populates media fields in Lexical content.
+ * Resolves Media IDs to full media objects with URLs.
+ *
+ * @param content - Lexical editor state content
+ * @param payload - Payload instance for database queries
+ * @param config - Newsletter plugin configuration
+ * @returns Populated content with resolved media objects
+ */
+declare function populateMediaFields(content: unknown, payload: Payload, config: NewsletterPluginConfig): Promise<unknown>;
+
+/**
+ * Options for generating broadcast preview HTML
+ */
+interface PreviewOptions {
+    /** Email subject line */
+    subject: string;
+    /** Email preheader text (preview text in inbox) */
+    preheader?: string;
+    /** Whether to wrap content in email template (default: true) */
+    wrapInTemplate?: boolean;
+    /** Base URL for media files (optional, derived from payload.config.serverURL if not provided) */
+    mediaUrl?: string;
+    /** Additional document data to pass to custom wrapper */
+    documentData?: Record<string, unknown>;
+}
+/**
+ * Result from preview generation
+ */
+interface PreviewResult {
+    /** Generated HTML content */
+    html: string;
+    /** Subject line used */
+    subject: string;
+    /** Preheader text used (null if not provided) */
+    preheader: string | null;
+}
+/**
+ * Generates preview HTML from broadcast content.
+ *
+ * This utility handles the full preview generation pipeline:
+ * 1. Populates media fields (resolves Media IDs to full objects with URLs)
+ * 2. Converts Lexical content to email-safe HTML
+ * 3. Optionally wraps in email template
+ *
+ * @param content - Lexical editor state content from broadcast
+ * @param payload - Payload instance for database queries
+ * @param config - Newsletter plugin configuration
+ * @param options - Preview generation options
+ * @returns Preview result with HTML, subject, and preheader
+ *
+ * @example
+ * ```typescript
+ * import { generateBroadcastPreviewHtml } from 'payload-plugin-newsletter'
+ *
+ * const preview = await generateBroadcastPreviewHtml(
+ *   broadcast.content,
+ *   payload,
+ *   pluginConfig,
+ *   {
+ *     subject: broadcast.subject,
+ *     preheader: broadcast.preheader,
+ *     wrapInTemplate: true,
+ *   }
+ * )
+ *
+ * // preview.html contains the rendered email HTML
+ * ```
+ */
+declare function generateBroadcastPreviewHtml(content: SerializedEditorState | null | undefined, payload: Payload, config: NewsletterPluginConfig, options: PreviewOptions): Promise<PreviewResult>;
+
+/**
+ * Converts Lexical editor state to email-safe HTML
+ */
+declare function convertToEmailSafeHtml(editorState: SerializedEditorState | undefined | null, options?: {
+    wrapInTemplate?: boolean;
+    preheader?: string;
+    mediaUrl?: string;
+    customBlockConverter?: (node: any, mediaUrl?: string) => Promise<string>;
+    payload?: any;
+    populateFields?: string[] | ((blockType: string) => string[]);
+    customWrapper?: (content: string, options?: {
+        preheader?: string;
+        subject?: string;
+        documentData?: Record<string, any>;
+    }) => string | Promise<string>;
+    subject?: string;
+    documentData?: Record<string, any>;
+}): Promise<string>;
+
 declare module 'payload' {
     interface BasePayload {
         newsletterEmailService?: any;
@@ -710,4 +801,4 @@ declare class BroadcastProvider implements EmailProvider {
     removeContact(email: string): Promise<void>;
 }
 
-export { BroadcastProvider, type NewsletterPluginConfig, ResendProvider, type Subscriber, createBroadcastsCollection, createNewsletterSettingsGlobal, createPreferencesEndpoint, createSubscribeEndpoint, createSubscribersCollection, createUnsubscribeEndpoint, createVerifyMagicLinkEndpoint, newsletterPlugin };
+export { BroadcastProvider, type NewsletterPluginConfig, type PreviewOptions, type PreviewResult, ResendProvider, type Subscriber, convertToEmailSafeHtml, createBroadcastsCollection, createNewsletterSettingsGlobal, createPreferencesEndpoint, createSubscribeEndpoint, createSubscribersCollection, createUnsubscribeEndpoint, createVerifyMagicLinkEndpoint, generateBroadcastPreviewHtml, newsletterPlugin, populateMediaFields };

package/dist/server.js

@@ -4289,25 +4289,28 @@ var createTestBroadcastEndpoint = (config, collectionSlug) => {
   };
 };
 
-// src/endpoints/broadcasts/preview.ts
+// src/utils/mediaPopulation.ts
 async function populateMediaFields(content, payload, config) {
   if (!content || typeof content !== "object") return content;
-  if (content.root?.children) {
-    for (const child of content.root.children) {
+  const typedContent = content;
+  if (typedContent.root?.children) {
+    for (const child of typedContent.root.children) {
       await populateBlockMediaFields(child, payload, config);
     }
   }
   return content;
 }
 async function populateBlockMediaFields(node, payload, config) {
-  if (node.type === "block" && node.fields) {
-    const blockType = node.fields.blockType || node.fields.blockName;
+  if (!node || typeof node !== "object") return;
+  const typedNode = node;
+  if (typedNode.type === "block" && typedNode.fields) {
+    const blockType = typedNode.fields.blockType || typedNode.fields.blockName;
     const customBlocks = config.customizations?.broadcasts?.customBlocks || [];
     const blockConfig = customBlocks.find((b) => b.slug === blockType);
     if (blockConfig && blockConfig.fields) {
       for (const field of blockConfig.fields) {
-        if (field.type === "upload" && field.relationTo && node.fields[field.name]) {
-          const fieldValue = node.fields[field.name];
+        if (field.type === "upload" && field.relationTo && typedNode.fields[field.name]) {
+          const fieldValue = typedNode.fields[field.name];
           const collectionName = Array.isArray(field.relationTo) ? field.relationTo[0] : field.relationTo;
           if (typeof fieldValue === "string" && fieldValue.match(/^[a-f0-9]{24}$/i)) {
             try {
@@ -4317,26 +4320,33 @@ async function populateBlockMediaFields(node, payload, config) {
                 depth: 0
               });
               if (media) {
-                node.fields[field.name] = media;
-                payload.logger?.info({
-                  mediaId: fieldValue,
-                  mediaUrl: media.url,
-                  filename: media.filename
-                }, `Populated ${field.name} for block ${blockType}`);
+                typedNode.fields[field.name] = media;
+                payload.logger?.info(
+                  {
+                    mediaId: fieldValue,
+                    mediaUrl: media.url,
+                    filename: media.filename
+                  },
+                  `Populated ${field.name} for block ${blockType}`
+                );
               }
             } catch (error) {
-              payload.logger?.error({ error: String(error) }, `Failed to populate ${field.name} for block ${blockType}`);
+              payload.logger?.error(
+                { error: String(error) },
+                `Failed to populate ${field.name} for block ${blockType}`
+              );
             }
           }
         }
         if (field.type === "array" && field.fields) {
-          const arrayValue = node.fields[field.name];
+          const arrayValue = typedNode.fields[field.name];
           if (Array.isArray(arrayValue)) {
             for (const arrayItem of arrayValue) {
               if (arrayItem && typeof arrayItem === "object") {
+                const typedArrayItem = arrayItem;
                 for (const arrayField of field.fields) {
-                  if (arrayField.type === "upload" && arrayField.relationTo && arrayItem[arrayField.name]) {
-                    const arrayFieldValue = arrayItem[arrayField.name];
+                  if (arrayField.type === "upload" && arrayField.relationTo && typedArrayItem[arrayField.name]) {
+                    const arrayFieldValue = typedArrayItem[arrayField.name];
                     const arrayCollectionName = Array.isArray(arrayField.relationTo) ? arrayField.relationTo[0] : arrayField.relationTo;
                     if (typeof arrayFieldValue === "string" && arrayFieldValue.match(/^[a-f0-9]{24}$/i)) {
                       try {
@@ -4346,15 +4356,21 @@ async function populateBlockMediaFields(node, payload, config) {
                           depth: 0
                         });
                         if (media) {
-                          arrayItem[arrayField.name] = media;
-                          payload.logger?.info({
-                            mediaId: arrayFieldValue,
-                            mediaUrl: media.url,
-                            filename: media.filename
-                          }, `Populated array ${arrayField.name} for block ${blockType}`);
+                          typedArrayItem[arrayField.name] = media;
+                          payload.logger?.info(
+                            {
+                              mediaId: arrayFieldValue,
+                              mediaUrl: media.url,
+                              filename: media.filename
+                            },
+                            `Populated array ${arrayField.name} for block ${blockType}`
+                          );
                         }
                       } catch (error) {
-                        payload.logger?.error({ error: String(error) }, `Failed to populate array ${arrayField.name} for block ${blockType}`);
+                        payload.logger?.error(
+                          { error: String(error) },
+                          `Failed to populate array ${arrayField.name} for block ${blockType}`
+                        );
                       }
                     }
                   }
@@ -4363,23 +4379,24 @@ async function populateBlockMediaFields(node, payload, config) {
             }
           }
         }
-        if (field.type === "richText" && node.fields[field.name]) {
-          await populateRichTextUploads(node.fields[field.name], payload);
+        if (field.type === "richText" && typedNode.fields[field.name]) {
+          await populateRichTextUploads(typedNode.fields[field.name], payload);
           payload.logger?.info(`Processed rich text field ${field.name} for upload nodes`);
         }
       }
     }
   }
-  if (node.children) {
-    for (const child of node.children) {
+  if (typedNode.children) {
+    for (const child of typedNode.children) {
       await populateBlockMediaFields(child, payload, config);
     }
   }
 }
 async function populateRichTextUploads(content, payload) {
   if (!content || typeof content !== "object") return;
-  if (content.root?.children) {
-    await processNodeArray(content.root.children);
+  const typedContent = content;
+  if (typedContent.root?.children) {
+    await processNodeArray(typedContent.root.children);
   }
   if (Array.isArray(content)) {
     await processNodeArray(content);
@@ -4389,33 +4406,42 @@ async function populateRichTextUploads(content, payload) {
   }
   async function processNode(node) {
     if (!node || typeof node !== "object") return;
-    if (node.type === "upload" && node.relationTo === "media" && typeof node.value === "string" && node.value.match(/^[a-f0-9]{24}$/i)) {
+    const typedNode = node;
+    if (typedNode.type === "upload" && typedNode.relationTo === "media" && typeof typedNode.value === "string" && typedNode.value.match(/^[a-f0-9]{24}$/i)) {
       try {
         const media = await payload.findByID({
           collection: "media",
-          id: node.value,
+          id: typedNode.value,
           depth: 0
         });
         if (media) {
-          node.value = media;
-          payload.logger?.info({
-            mediaId: node.value,
-            mediaUrl: media.url,
-            filename: media.filename
-          }, "Populated rich text upload node");
+          typedNode.value = media;
+          payload.logger?.info(
+            {
+              mediaId: typedNode.value,
+              mediaUrl: media.url,
+              filename: media.filename
+            },
+            "Populated rich text upload node"
+          );
         }
       } catch (error) {
-        payload.logger?.error({ error: String(error) }, `Failed to populate rich text upload ${node.value}`);
+        payload.logger?.error(
+          { error: String(error) },
+          `Failed to populate rich text upload ${typedNode.value}`
+        );
       }
     }
-    if (node.children && Array.isArray(node.children)) {
-      await processNodeArray(node.children);
+    if (typedNode.children && Array.isArray(typedNode.children)) {
+      await processNodeArray(typedNode.children);
     }
-    if (node.root?.children && Array.isArray(node.root.children)) {
-      await processNodeArray(node.root.children);
+    if (typedNode.root?.children && Array.isArray(typedNode.root.children)) {
+      await processNodeArray(typedNode.root.children);
     }
   }
 }
+
+// src/endpoints/broadcasts/preview.ts
 var createBroadcastPreviewEndpoint = (config, _collectionSlug) => {
   return {
     path: "/preview",
@@ -5263,6 +5289,28 @@ var setPluginConfig = (config) => {
 // src/utilities/session.ts
 import jwt2 from "jsonwebtoken";
 
+// src/utils/preview.ts
+async function generateBroadcastPreviewHtml(content, payload, config, options) {
+  const mediaUrl = options.mediaUrl ?? (payload.config.serverURL ? `${payload.config.serverURL}/api/media` : "/api/media");
+  const emailPreviewConfig = config.customizations?.broadcasts?.emailPreview;
+  payload.logger?.info("Populating media fields for preview generation...");
+  const populatedContent = await populateMediaFields(content, payload, config);
+  const html = await convertToEmailSafeHtml(populatedContent, {
+    wrapInTemplate: options.wrapInTemplate ?? emailPreviewConfig?.wrapInTemplate ?? true,
+    preheader: options.preheader,
+    subject: options.subject,
+    mediaUrl,
+    documentData: options.documentData,
+    customBlockConverter: config.customizations?.broadcasts?.customBlockConverter,
+    customWrapper: emailPreviewConfig?.customWrapper
+  });
+  return {
+    html,
+    subject: options.subject,
+    preheader: options.preheader ?? null
+  };
+}
+
 // src/index.ts
 var newsletterPlugin = (pluginConfig) => (incomingConfig) => {
   const config = {
@@ -5417,6 +5465,7 @@ var newsletterPlugin = (pluginConfig) => (incomingConfig) => {
 export {
   BroadcastProvider,
   ResendProvider,
+  convertToEmailSafeHtml,
   createBroadcastsCollection,
   createNewsletterSettingsGlobal,
   createPreferencesEndpoint,
@@ -5424,5 +5473,7 @@ export {
   createSubscribersCollection,
   createUnsubscribeEndpoint,
   createVerifyMagicLinkEndpoint,
-  newsletterPlugin
+  generateBroadcastPreviewHtml,
+  newsletterPlugin,
+  populateMediaFields
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "payload-plugin-newsletter",
-  "version": "0.25.11",
+  "version": "0.25.13",
   "description": "Complete newsletter management plugin for Payload CMS with subscriber management, magic link authentication, and email service integration",
   "type": "module",
   "main": "./dist/index.js",