payload-plugin-newsletter 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2025-06-15
+
+### Added
+- Initial release of Payload Newsletter Plugin
+- Subscribers collection with comprehensive field schema
+- Email settings global for admin UI configuration
+- Magic link authentication system (separate from Payload auth)
+- Email service providers: Resend and Broadcast
+- Newsletter scheduling for any collection
+- Automatic markdown generation from rich text fields
+- Customizable email templates using React Email
+- React components: NewsletterForm, PreferencesForm, MagicLinkVerify
+- useNewsletterAuth hook for client-side state management
+- API endpoints for subscription, authentication, and preferences
+- Full TypeScript support with comprehensive types
+- Internationalization support
+- UTM tracking and analytics data collection
+- Lead magnet support
+- Rate limiting and security features
+
+### Security
+- JWT-based authentication for magic links
+- Session token management
+- Rate limiting by IP address
+- Domain restriction options
+- Input validation and sanitization
+
+[0.1.0]: https://github.com/aniketpanjwani/payload-plugin-email-newsletter/releases/tag/v0.1.0

package/CLAUDE.md

@@ -0,0 +1,110 @@
+# Claude Development Guidelines
+
+This file contains development guidelines and reference information for Claude when working on the Payload Newsletter Plugin.
+
+## Important Security Guidelines
+
+**NEVER include any of the following in the repository:**
+- API keys or tokens (use environment variables)
+- Email addresses or personal information
+- Specific company/project names (keep everything generic)
+- Production URLs or endpoints
+- Any credentials or sensitive configuration
+
+## Reference Repositories
+
+These local repositories contain reference implementations and examples:
+
+1. **Medellin Newsletter Implementation** (source for newsletter logic):
+   - Location: `/Users/aniketpanjwani/Projects/medellin_newsletter/medellin_insider`
+   - Use for: Understanding newsletter implementation patterns
+   - DO NOT: Copy any specific business logic, API keys, or Medellin-specific references
+
+2. **Payload CMS Source**:
+   - Location: `/Users/aniketpanjwani/Projects/reference_repos/payload`
+   - Docs: `/Users/aniketpanjwani/Projects/reference_repos/payload/docs`
+   - Templates: `/Users/aniketpanjwani/Projects/reference_repos/payload/templates`
+   - Use for: Understanding Payload patterns and best practices
+
+3. **Official Payload Plugins** (examples to follow):
+   - SEO Plugin: `/Users/aniketpanjwani/Projects/reference_repos/payload/packages/plugin-seo`
+   - Form Builder: `/Users/aniketpanjwani/Projects/reference_repos/payload/packages/plugin-form-builder`
+   - Use for: Plugin architecture patterns and conventions
+
+## Development Setup
+
+This project uses **Bun** as the preferred package manager and runtime.
+
+### Available Commands
+- `bun install` - Install dependencies
+- `bun typecheck` - Run TypeScript type checking
+- `bun generate:types` - Generate TypeScript declarations
+- `bun build` - Build the project (JS + types)
+- `bun dev` - Watch mode for development
+- `bun lint` - Run ESLint
+- `bun clean` - Clean build artifacts
+
+## Development Guidelines
+
+### Code Style
+- Follow Payload's patterns from official plugins
+- Use TypeScript for everything
+- No comments unless specifically requested
+- Keep implementations generic and reusable
+
+### Plugin Design Principles
+1. **Generic by Default**: Everything should work for any Payload project
+2. **Configuration Over Code**: Use config options rather than hardcoded values
+3. **Follow Payload Patterns**: Match the style of official plugins
+4. **User-Friendly**: Clear documentation and intuitive defaults
+
+### Testing Approach
+- Test with generic data only
+- Use example.com for email addresses
+- Use placeholder text for content
+- Never use real API keys in tests
+
+### Documentation
+- Keep README focused on user needs
+- Include clear examples
+- Document all configuration options
+- Link to FEEDBACK.md for design decisions
+
+## Common Tasks
+
+### When Adding New Features
+1. Check reference implementations for patterns
+2. Keep everything configurable
+3. Add TypeScript types
+4. Update documentation
+5. Make progressive commits
+
+### When Reviewing Reference Code
+- Extract patterns, not implementations
+- Generalize any specific logic
+- Remove all identifying information
+- Focus on the architecture
+
+## Environment Variables
+
+When documenting environment variables, always use generic examples:
+```bash
+RESEND_API_KEY=your_resend_api_key_here
+BROADCAST_TOKEN=your_broadcast_token_here
+JWT_SECRET=your_jwt_secret_here
+```
+
+## Git Workflow
+
+1. Make small, focused commits
+2. Use conventional commit messages (feat:, fix:, docs:, etc.)
+3. Push regularly to: https://github.com/aniketpanjwani/payload-plugin-email-newsletter
+4. Keep sensitive information in gitignored directories
+
+## Questions to Always Consider
+
+Before implementing any feature, ask:
+1. Is this generic enough for any Payload project?
+2. Are there any hardcoded values that should be configurable?
+3. Does this follow Payload's established patterns?
+4. Is this well-documented for users?

package/FEEDBACK.md

@@ -0,0 +1,148 @@
+# Feedback & Design Decisions
+
+We'd love your feedback on the Payload Newsletter Plugin! This document outlines key design decisions we've made and areas where community input would be especially valuable.
+
+## 🤔 Design Decisions We'd Like Feedback On
+
+### 1. Magic Link Authentication Approach
+
+**Current Design**: We've implemented a custom JWT-based magic link system that's completely separate from Payload's built-in authentication.
+
+**Rationale**: 
+- Newsletter subscribers typically don't need full CMS access
+- Passwordless is more user-friendly for newsletter management
+- Keeps subscriber auth separate from admin auth
+
+**Questions for the Community**:
+- Would you prefer an option to integrate with Payload's auth system?
+- Is the current token expiration (7 days) appropriate?
+- Should we support other passwordless methods (OTP, social login)?
+
+### 2. Email Provider Architecture
+
+**Current Design**: We support Resend and Broadcast with a provider-agnostic interface.
+
+**Questions for the Community**:
+- Which other email providers should we prioritize? (SendGrid, Mailgun, AWS SES, Postmark?)
+- Should we support multiple providers simultaneously (e.g., failover)?
+- Is the current provider interface flexible enough for your needs?
+
+### 3. Newsletter Scheduling Integration
+
+**Current Design**: We inject fields into your existing articles collection rather than creating a separate newsletter collection.
+
+**Rationale**:
+- Leverages existing content
+- Avoids duplication
+- Simpler mental model
+
+**Questions for the Community**:
+- Would you prefer a dedicated newsletters collection?
+- Should we support scheduling multiple article types (not just articles)?
+- What additional scheduling features would be valuable?
+
+### 4. Component Library Approach
+
+**Current Design**: React-only components using Payload's UI library.
+
+**Questions for the Community**:
+- Would you like vanilla JS examples for non-React frontends?
+- Should we provide more component variants (embedded, modal, etc.)?
+- What styling/theming options would be most useful?
+
+### 5. Data Collection & Analytics
+
+**Current Design**: We collect UTM parameters and basic metadata but don't include analytics dashboards.
+
+**Questions for the Community**:
+- What analytics would be most valuable to track?
+- Should we integrate with analytics platforms (GA, Plausible, etc.)?
+- Would you want a built-in analytics dashboard?
+
+### 6. Default Field Schema
+
+**Current Design**: We include a comprehensive set of fields (name, locale, preferences, segments, etc.).
+
+**Questions for the Community**:
+- Are there fields we should add or remove by default?
+- Should some fields be opt-in rather than default?
+- How can we better support custom field requirements?
+
+## 💡 Feature Requests
+
+We're considering these features for future releases:
+
+1. **Double opt-in workflow** - Email confirmation before activation
+2. **A/B testing** - Test subject lines and content
+3. **Automation workflows** - Welcome series, drip campaigns
+4. **Segmentation UI** - Visual segment builder
+5. **Template marketplace** - Share email templates
+6. **Import/Export tools** - Migrate from other platforms
+7. **Webhook support** - Notify external services of events
+8. **Email preview** - See how emails look before sending
+
+**What features would you prioritize?**
+
+## 🐛 Known Limitations
+
+Current limitations we're aware of:
+
+1. No built-in unsubscribe page (API only)
+2. No email bounce handling
+3. No GDPR compliance features (by design, but reconsidering)
+4. Limited email template customization
+5. No support for attachments
+
+**Which limitations affect you most?**
+
+## 📝 How to Provide Feedback
+
+We welcome all feedback! Here's how to contribute:
+
+1. **GitHub Issues**: For bugs and feature requests
+   - [Create an issue](https://github.com/aniketpanjwani/payload-plugin-email-newsletter/issues)
+
+2. **GitHub Discussions**: For design discussions and questions
+   - [Start a discussion](https://github.com/aniketpanjwani/payload-plugin-email-newsletter/discussions)
+
+3. **Pull Requests**: For direct contributions
+   - Fork the repo and submit a PR
+   - Include tests for new features
+   - Update documentation as needed
+
+4. **Discord**: For quick questions and community discussion
+   - Join the [Payload Discord](https://discord.gg/payload)
+   - Find us in #plugins channel
+
+## 🚀 Roadmap Influence
+
+Your feedback directly influences our roadmap. We review all feedback monthly and prioritize based on:
+
+1. Community votes/reactions
+2. Implementation complexity
+3. Alignment with Payload patterns
+4. Benefit to most users
+
+## Example Use Cases
+
+We'd love to hear about your use cases! Some we've considered:
+
+- **SaaS applications**: Product updates and announcements
+- **Content sites**: Weekly digests and new post notifications
+- **E-commerce**: Order updates and promotional emails
+- **Communities**: Event notifications and member updates
+- **Educational**: Course updates and learning resources
+
+**What's your use case?**
+
+## Contributing Code
+
+If you'd like to contribute:
+
+1. Check existing issues/discussions first
+2. Propose significant changes via discussion before implementing
+3. Follow Payload's coding standards
+4. Include tests and documentation
+5. Keep PRs focused on a single feature/fix
+
+Thank you for helping make this plugin better for everyone! 🙏

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Aniket Panjwani
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README-DEVELOPMENT.md

@@ -0,0 +1,80 @@
+# Development Guide
+
+## Quick Start
+
+This project uses Bun as the preferred package manager and runtime.
+
+### Install Dependencies
+
+```bash
+bun install
+```
+
+### Type Checking
+
+Run TypeScript type checking without emitting files:
+
+```bash
+bun typecheck
+```
+
+### Generate Type Definitions
+
+Generate TypeScript declaration files:
+
+```bash
+bun generate:types
+```
+
+### Build
+
+Build the project (both JavaScript and type definitions):
+
+```bash
+bun build
+```
+
+### Development Mode
+
+Watch for changes and rebuild:
+
+```bash
+bun dev
+```
+
+### Linting
+
+Run ESLint on the source code:
+
+```bash
+bun lint
+```
+
+### Clean Build Artifacts
+
+Remove the dist directory:
+
+```bash
+bun clean
+```
+
+## Common TypeScript Issues
+
+If you encounter TypeScript errors during build:
+
+1. **Module Resolution**: The project uses ESM modules. Import statements should include file extensions for relative imports.
+2. **Type Errors**: Run `bun typecheck` to see all TypeScript errors without building.
+3. **Missing Types**: Some Payload types might need explicit imports or type assertions.
+
+## Publishing
+
+Before publishing to npm:
+
+1. Ensure all tests pass (when tests are added)
+2. Run `bun typecheck` to ensure no TypeScript errors
+3. Update version in package.json
+4. Update CHANGELOG.md
+5. Run `bun build` to ensure it builds successfully
+6. Tag the release: `git tag v0.x.x`
+7. Push tags: `git push --tags`
+8. Publish: `npm publish`