payload-plugin-newsletter 0.15.0 → 0.16.0

package/CHANGELOG.md

@@ -1,3 +1,75 @@
+## [0.16.0] - 2025-07-27
+
+### Changed
+- **Send = Publish Workflow** - Simplified broadcast sending to use Payload's native draft/publish system
+  - Publishing a broadcast now automatically sends it via the configured email provider
+  - Removed custom Send/Schedule modal in favor of Payload's built-in UI
+  - Scheduled publishing supported via Payload's Jobs Queue system
+  - Breaking: Removed `SendBroadcastModal` and `ActionsCell` components
+- **Streamlined UI** - Removed custom action buttons from broadcasts list view
+  - Users now use standard Payload publish/schedule functionality
+  - Cleaner interface that follows Payload's patterns
+  - Less code to maintain while providing better integration
+
+### Added
+- **Automatic Send on Publish** - New `afterChange` hook that sends broadcasts when published
+  - Checks if broadcast is transitioning to published status
+  - Automatically calls provider's send method
+  - Updates broadcast status to "sending" after successful send
+  - Handles failures gracefully with status update to "failed"
+- **Jobs Queue Documentation** - Added comprehensive setup instructions for scheduled publishing
+  - Vercel Cron configuration example
+  - Security setup with CRON_SECRET
+  - Step-by-step guide for enabling scheduled broadcasts
+
+### Removed
+- **Custom UI Components** (Breaking Change)
+  - `SendBroadcastModal` - Custom send/schedule modal
+  - `ActionsCell` - Custom action buttons in list view
+  - `actions` field from Broadcasts collection
+  - These are replaced by Payload's native publish/schedule functionality
+
+### Technical
+- Enabled `versions` configuration on Broadcasts collection with drafts and scheduled publishing
+- Updated default columns to show both `_status` (Draft/Published) and `status` (send status)
+- Improved TypeScript exports by removing deleted component references
+- All tests passing with minor version upgrade
+
+### Migration Guide
+If you were using the custom Send/Schedule modal:
+1. The functionality is now built into Payload's publish system
+2. To send immediately: Click "Publish"
+3. To schedule: Click "Schedule" (requires Jobs Queue setup)
+4. Remove any imports of `SendBroadcastModal` or `ActionsCell` from your code
+
+## [0.15.1] - 2025-07-27
+
+### Fixed
+- **Email-Compatible Block Editor** - Resolved Next.js serialization errors with custom blocks
+  - Custom blocks are now processed server-side using Lexical's proven BlocksFeature pattern
+  - Prevents "Functions cannot be passed directly to Client Components" errors
+  - Maintains full email compatibility while enabling custom block functionality
+- **Block Validation System** - Added validation utilities for email compatibility
+  - `validateEmailBlocks()` warns about potentially incompatible block types
+  - `createEmailSafeBlocks()` processes blocks for email-safe configurations
+  - Automatic detection of complex field types that may not render in email clients
+
+### Improved
+- **Server-Side Block Processing** - Enhanced `createEmailLexicalEditor()` function
+  - Processes custom blocks into Lexical editor configuration before client serialization
+  - Clean separation between email-compatible and web-only content blocks
+  - Better performance through pre-configured editor instances
+- **Enhanced Documentation** - Updated extension points guide with new approach
+  - Examples showing both legacy and new server-side processing methods
+  - Block validation utilities documentation
+  - Email compatibility best practices
+
+### Technical
+- Added `createEmailLexicalEditor()` for server-side editor configuration
+- Enhanced `createEmailContentField()` to accept pre-configured editors
+- New utility exports: `validateEmailBlocks`, `createEmailSafeBlocks`
+- Improved TypeScript support for custom block configurations
+
 ## [0.15.0] - 2025-07-27
 
 ### Added

package/README.md

@@ -241,6 +241,50 @@ This adds a `broadcasts` collection with:
 - Custom email blocks (buttons, dividers)
 - Inline email preview with React Email
 - Automatic sync with your email provider
+- Draft/publish system with scheduled publishing support
+
+### Send = Publish Workflow
+
+The plugin integrates seamlessly with Payload's draft/publish system:
+
+- **Draft**: Create and edit broadcasts without sending
+- **Publish**: Publishing a broadcast automatically sends it via your configured email provider
+- **Schedule**: Use Payload's scheduled publishing to send broadcasts at a future time
+
+**How it works:**
+1. Create a broadcast and save as draft
+2. When ready, click "Publish" to send immediately
+3. Or use "Schedule" to publish (and send) at a specific date/time
+
+**Important**: Scheduled publishing requires configuring Payload's Jobs Queue. For Vercel deployments, add this to your `vercel.json`:
+
+```json
+{
+  "crons": [
+    {
+      "path": "/api/payload-jobs/run",
+      "schedule": "*/5 * * * *"
+    }
+  ]
+}
+```
+
+And secure the endpoint in your `payload.config.ts`:
+
+```typescript
+export default buildConfig({
+  // ... other config
+  jobs: {
+    access: {
+      run: ({ req }) => {
+        if (req.user) return true
+        const authHeader = req.headers.get('authorization')
+        return authHeader === `Bearer ${process.env.CRON_SECRET}`
+      },
+    },
+  },
+})
+```
 
 ### Custom Email Templates (v0.12.0+)
 
@@ -727,7 +771,7 @@ newsletterPlugin({
 
 ### Extending the Broadcasts Collection (v0.15.0+)
 
-You can extend the Broadcasts collection with additional fields and custom blocks:
+You can extend the Broadcasts collection with additional fields and custom email-compatible blocks:
 
 ```typescript
 import type { Block } from 'payload'
@@ -753,7 +797,7 @@ newsletterPlugin({
           admin: { position: 'sidebar' }
         }
       ],
-      customBlocks: [customBlock],
+      customBlocks: [customBlock], // Processed server-side for email compatibility
       fieldOverrides: {
         content: (defaultField) => ({
           ...defaultField,
@@ -768,6 +812,8 @@ newsletterPlugin({
 })
 ```
 
+**Note**: Custom blocks are processed server-side to ensure email compatibility and prevent Next.js serialization errors.
+
 For complete extensibility documentation, see the [Extension Points Guide](./docs/architecture/extension-points.md).
 
 ## Troubleshooting

package/dist/collections.cjs

@@ -542,6 +542,103 @@ init_types();
 
 // src/fields/emailContent.ts
 var import_richtext_lexical = require("@payloadcms/richtext-lexical");
+
+// src/utils/blockValidation.ts
+var EMAIL_INCOMPATIBLE_TYPES = [
+  "chart",
+  "dataTable",
+  "interactive",
+  "streamable",
+  "video",
+  "iframe",
+  "form",
+  "carousel",
+  "tabs",
+  "accordion",
+  "map"
+];
+var validateEmailBlocks = (blocks) => {
+  blocks.forEach((block) => {
+    if (EMAIL_INCOMPATIBLE_TYPES.includes(block.slug)) {
+      console.warn(`\u26A0\uFE0F  Block "${block.slug}" may not be email-compatible. Consider creating an email-specific version.`);
+    }
+    const hasComplexFields = block.fields?.some((field) => {
+      const complexTypes = ["code", "json", "richText", "blocks", "array"];
+      return complexTypes.includes(field.type);
+    });
+    if (hasComplexFields) {
+      console.warn(`\u26A0\uFE0F  Block "${block.slug}" contains complex field types that may not render consistently in email clients.`);
+    }
+  });
+};
+var createEmailSafeBlocks = (customBlocks = []) => {
+  validateEmailBlocks(customBlocks);
+  const baseBlocks = [
+    {
+      slug: "button",
+      fields: [
+        {
+          name: "text",
+          type: "text",
+          label: "Button Text",
+          required: true
+        },
+        {
+          name: "url",
+          type: "text",
+          label: "Button URL",
+          required: true,
+          admin: {
+            description: "Enter the full URL (including https://)"
+          }
+        },
+        {
+          name: "style",
+          type: "select",
+          label: "Button Style",
+          defaultValue: "primary",
+          options: [
+            { label: "Primary", value: "primary" },
+            { label: "Secondary", value: "secondary" },
+            { label: "Outline", value: "outline" }
+          ]
+        }
+      ],
+      interfaceName: "EmailButton",
+      labels: {
+        singular: "Button",
+        plural: "Buttons"
+      }
+    },
+    {
+      slug: "divider",
+      fields: [
+        {
+          name: "style",
+          type: "select",
+          label: "Divider Style",
+          defaultValue: "solid",
+          options: [
+            { label: "Solid", value: "solid" },
+            { label: "Dashed", value: "dashed" },
+            { label: "Dotted", value: "dotted" }
+          ]
+        }
+      ],
+      interfaceName: "EmailDivider",
+      labels: {
+        singular: "Divider",
+        plural: "Dividers"
+      }
+    }
+  ];
+  return [
+    ...baseBlocks,
+    ...customBlocks
+  ];
+};
+
+// src/fields/emailContent.ts
 var createEmailSafeFeatures = (additionalBlocks) => {
   const baseBlocks = [
     {
@@ -679,16 +776,89 @@ var createEmailSafeFeatures = (additionalBlocks) => {
     })
   ];
 };
+var createEmailLexicalEditor = (customBlocks = []) => {
+  const emailSafeBlocks = createEmailSafeBlocks(customBlocks);
+  return (0, import_richtext_lexical.lexicalEditor)({
+    features: [
+      // Toolbars
+      (0, import_richtext_lexical.FixedToolbarFeature)(),
+      (0, import_richtext_lexical.InlineToolbarFeature)(),
+      // Basic text formatting
+      (0, import_richtext_lexical.BoldFeature)(),
+      (0, import_richtext_lexical.ItalicFeature)(),
+      (0, import_richtext_lexical.UnderlineFeature)(),
+      (0, import_richtext_lexical.StrikethroughFeature)(),
+      // Links with enhanced configuration
+      (0, import_richtext_lexical.LinkFeature)({
+        fields: [
+          {
+            name: "url",
+            type: "text",
+            required: true,
+            admin: {
+              description: "Enter the full URL (including https://)"
+            }
+          },
+          {
+            name: "newTab",
+            type: "checkbox",
+            label: "Open in new tab",
+            defaultValue: false
+          }
+        ]
+      }),
+      // Lists
+      (0, import_richtext_lexical.OrderedListFeature)(),
+      (0, import_richtext_lexical.UnorderedListFeature)(),
+      // Headings - limited to h1, h2, h3 for email compatibility
+      (0, import_richtext_lexical.HeadingFeature)({
+        enabledHeadingSizes: ["h1", "h2", "h3"]
+      }),
+      // Basic paragraph and alignment
+      (0, import_richtext_lexical.ParagraphFeature)(),
+      (0, import_richtext_lexical.AlignFeature)(),
+      // Blockquotes
+      (0, import_richtext_lexical.BlockquoteFeature)(),
+      // Upload feature for images
+      (0, import_richtext_lexical.UploadFeature)({
+        collections: {
+          media: {
+            fields: [
+              {
+                name: "caption",
+                type: "text",
+                admin: {
+                  description: "Optional caption for the image"
+                }
+              },
+              {
+                name: "altText",
+                type: "text",
+                label: "Alt Text",
+                required: true,
+                admin: {
+                  description: "Alternative text for accessibility and when image cannot be displayed"
+                }
+              }
+            ]
+          }
+        }
+      }),
+      // Email-safe blocks (processed server-side)
+      (0, import_richtext_lexical.BlocksFeature)({
+        blocks: emailSafeBlocks
+      })
+    ]
+  });
+};
 var emailSafeFeatures = createEmailSafeFeatures();
 var createEmailContentField = (overrides) => {
-  const features = createEmailSafeFeatures(overrides?.additionalBlocks);
+  const editor = overrides?.editor || createEmailLexicalEditor(overrides?.additionalBlocks);
   return {
     name: "content",
     type: "richText",
     required: true,
-    editor: (0, import_richtext_lexical.lexicalEditor)({
-      features
-    }),
+    editor,
     admin: {
       description: "Email content with limited formatting for compatibility",
       ...overrides?.admin
@@ -998,6 +1168,12 @@ var createBroadcastsCollection = (pluginConfig) => {
   const customizations = pluginConfig.customizations?.broadcasts;
   return {
     slug: "broadcasts",
+    versions: {
+      drafts: {
+        autosave: true,
+        schedulePublish: true
+      }
+    },
     labels: {
       singular: "Broadcast",
       plural: "Broadcasts"
@@ -1005,7 +1181,7 @@ var createBroadcastsCollection = (pluginConfig) => {
     admin: {
       useAsTitle: "subject",
       description: "Individual email campaigns sent to subscribers",
-      defaultColumns: ["subject", "status", "sentAt", "recipientCount", "actions"]
+      defaultColumns: ["subject", "_status", "status", "sentAt", "recipientCount"]
     },
     fields: [
       {
@@ -1040,13 +1216,15 @@ var createBroadcastsCollection = (pluginConfig) => {
                 }
               },
               // Apply content field customization if provided
-              customizations?.fieldOverrides?.content ? customizations.fieldOverrides.content(createEmailContentField({
-                admin: { description: "Email content" },
-                additionalBlocks: customizations.customBlocks
-              })) : createEmailContentField({
-                admin: { description: "Email content" },
-                additionalBlocks: customizations?.customBlocks
-              })
+              // Process blocks server-side to avoid client serialization issues
+              (() => {
+                const emailEditor = createEmailLexicalEditor(customizations?.customBlocks);
+                const baseField = createEmailContentField({
+                  admin: { description: "Email content" },
+                  editor: emailEditor
+                });
+                return customizations?.fieldOverrides?.content ? customizations.fieldOverrides.content(baseField) : baseField;
+              })()
             ]
           },
           {
@@ -1216,18 +1394,6 @@ var createBroadcastsCollection = (pluginConfig) => {
           condition: () => false
           // Hidden by default
         }
-      },
-      // UI Field for custom actions in list view
-      {
-        name: "actions",
-        type: "ui",
-        admin: {
-          components: {
-            Cell: "payload-plugin-newsletter/components#ActionsCell",
-            Field: "payload-plugin-newsletter/components#EmptyField"
-          },
-          disableListColumn: false
-        }
       }
     ],
     hooks: {
@@ -1341,6 +1507,48 @@ var createBroadcastsCollection = (pluginConfig) => {
             req.payload.logger.error("Failed to delete broadcast from provider:", error);
           }
           return doc;
+        },
+        // Hook to send when published
+        async ({ doc, req }) => {
+          if (doc._status === "published" && doc.providerId) {
+            if (doc.status === "sent" || doc.status === "sending") {
+              return doc;
+            }
+            try {
+              const broadcastConfig = pluginConfig.providers?.broadcast;
+              const resendConfig = pluginConfig.providers?.resend;
+              if (!broadcastConfig && !resendConfig) {
+                req.payload.logger.error("No provider configured for sending");
+                return doc;
+              }
+              if (broadcastConfig) {
+                const { BroadcastApiProvider: BroadcastApiProvider2 } = await Promise.resolve().then(() => (init_broadcast2(), broadcast_exports));
+                const provider = new BroadcastApiProvider2(broadcastConfig);
+                await provider.send(doc.providerId);
+              }
+              await req.payload.update({
+                collection: "broadcasts",
+                id: doc.id,
+                data: {
+                  status: "sending" /* SENDING */,
+                  sentAt: (/* @__PURE__ */ new Date()).toISOString()
+                },
+                req
+              });
+              req.payload.logger.info(`Broadcast ${doc.id} sent successfully`);
+            } catch (error) {
+              req.payload.logger.error(`Failed to send broadcast ${doc.id}:`, error);
+              await req.payload.update({
+                collection: "broadcasts",
+                id: doc.id,
+                data: {
+                  status: "failed" /* FAILED */
+                },
+                req
+              });
+            }
+          }
+          return doc;
         }
       ]
     }