payload-plugin-newsletter 0.8.7 → 0.9.0

package/dist/types.d.ts

@@ -1,5 +1,590 @@
 import { Field } from 'payload';
 
+/**
+ * Core types for newsletter management functionality
+ */
+/**
+ * Represents a newsletter/broadcast in the system
+ */
+interface Newsletter {
+    id: string;
+    name: string;
+    subject: string;
+    preheader?: string;
+    content: string;
+    status: NewsletterStatus;
+    trackOpens: boolean;
+    trackClicks: boolean;
+    replyTo?: string;
+    recipientCount?: number;
+    sentAt?: Date;
+    scheduledAt?: Date;
+    createdAt: Date;
+    updatedAt: Date;
+    providerData?: Record<string, any>;
+    providerId?: string;
+    providerType?: 'broadcast' | 'resend';
+}
+/**
+ * Possible statuses for a newsletter
+ */
+declare enum NewsletterStatus {
+    DRAFT = "draft",
+    SCHEDULED = "scheduled",
+    SENDING = "sending",
+    SENT = "sent",
+    FAILED = "failed",
+    PAUSED = "paused",
+    CANCELED = "canceled"
+}
+/**
+ * Options for listing newsletters
+ */
+interface ListNewsletterOptions {
+    limit?: number;
+    offset?: number;
+    status?: NewsletterStatus;
+    sortBy?: 'createdAt' | 'updatedAt' | 'sentAt' | 'name';
+    sortOrder?: 'asc' | 'desc';
+}
+/**
+ * Response from listing newsletters
+ */
+interface ListNewsletterResponse<T = Newsletter> {
+    items: T[];
+    total: number;
+    limit: number;
+    offset: number;
+    hasMore: boolean;
+}
+/**
+ * Input for creating a new newsletter
+ */
+interface CreateNewsletterInput {
+    name: string;
+    subject: string;
+    preheader?: string;
+    content: string;
+    trackOpens?: boolean;
+    trackClicks?: boolean;
+    replyTo?: string;
+    audienceIds?: string[];
+}
+/**
+ * Input for updating an existing newsletter
+ */
+interface UpdateNewsletterInput {
+    name?: string;
+    subject?: string;
+    preheader?: string;
+    content?: string;
+    trackOpens?: boolean;
+    trackClicks?: boolean;
+    replyTo?: string;
+    audienceIds?: string[];
+}
+/**
+ * Options for sending a newsletter
+ */
+interface SendNewsletterOptions {
+    audienceIds?: string[];
+    testMode?: boolean;
+    testRecipients?: string[];
+}
+/**
+ * Analytics data for a newsletter
+ */
+interface NewsletterAnalytics {
+    sent: number;
+    delivered: number;
+    opened: number;
+    clicked: number;
+    bounced: number;
+    complained: number;
+    unsubscribed: number;
+    deliveryRate?: number;
+    openRate?: number;
+    clickRate?: number;
+    bounceRate?: number;
+}
+/**
+ * Capabilities that a newsletter provider supports
+ */
+interface NewsletterProviderCapabilities {
+    supportsScheduling: boolean;
+    supportsSegmentation: boolean;
+    supportsAnalytics: boolean;
+    supportsABTesting: boolean;
+    supportsTemplates: boolean;
+    supportsPersonalization: boolean;
+    maxRecipientsPerSend?: number;
+    editableStatuses: NewsletterStatus[];
+    supportedContentTypes: ('html' | 'text' | 'react')[];
+}
+/**
+ * Error types specific to newsletter operations
+ */
+declare class NewsletterProviderError extends Error {
+    code: NewsletterErrorCode;
+    provider: string;
+    details?: any | undefined;
+    constructor(message: string, code: NewsletterErrorCode, provider: string, details?: any | undefined);
+}
+declare enum NewsletterErrorCode {
+    NOT_SUPPORTED = "NOT_SUPPORTED",
+    INVALID_STATUS = "INVALID_STATUS",
+    PROVIDER_ERROR = "PROVIDER_ERROR",
+    VALIDATION_ERROR = "VALIDATION_ERROR",
+    NOT_FOUND = "NOT_FOUND",
+    PERMISSION_DENIED = "PERMISSION_DENIED",
+    RATE_LIMITED = "RATE_LIMITED",
+    CONFIGURATION_ERROR = "CONFIGURATION_ERROR"
+}
+/**
+ * Newsletter template for reusable content
+ */
+interface NewsletterTemplate {
+    id: string;
+    name: string;
+    description?: string;
+    content: string;
+    variables?: NewsletterTemplateVariable[];
+    createdAt: Date;
+    updatedAt: Date;
+}
+interface NewsletterTemplateVariable {
+    name: string;
+    type: 'text' | 'html' | 'image' | 'url';
+    defaultValue?: string;
+    required?: boolean;
+}
+
+/**
+ * Core types for broadcast management functionality
+ */
+/**
+ * Represents a broadcast (individual email campaign) in the system
+ */
+interface Broadcast {
+    id: string;
+    channelId: string;
+    name: string;
+    subject: string;
+    preheader?: string;
+    content: string;
+    status: BroadcastStatus;
+    trackOpens: boolean;
+    trackClicks: boolean;
+    replyTo?: string;
+    recipientCount?: number;
+    sentAt?: Date;
+    scheduledAt?: Date;
+    createdAt: Date;
+    updatedAt: Date;
+    providerData?: Record<string, any>;
+    providerId?: string;
+    providerType?: 'broadcast' | 'resend';
+}
+/**
+ * Possible statuses for a broadcast
+ */
+declare enum BroadcastStatus {
+    DRAFT = "draft",
+    SCHEDULED = "scheduled",
+    SENDING = "sending",
+    SENT = "sent",
+    FAILED = "failed",
+    PAUSED = "paused",
+    CANCELED = "canceled"
+}
+/**
+ * Options for listing broadcasts
+ */
+interface ListBroadcastOptions {
+    limit?: number;
+    offset?: number;
+    status?: BroadcastStatus;
+    channelId?: string;
+    sortBy?: 'createdAt' | 'updatedAt' | 'sentAt' | 'name';
+    sortOrder?: 'asc' | 'desc';
+}
+/**
+ * Response from listing broadcasts
+ */
+interface ListBroadcastResponse<T = Broadcast> {
+    items: T[];
+    total: number;
+    limit: number;
+    offset: number;
+    hasMore: boolean;
+}
+/**
+ * Input for creating a new broadcast
+ */
+interface CreateBroadcastInput {
+    channelId: string;
+    name: string;
+    subject: string;
+    preheader?: string;
+    content: string;
+    trackOpens?: boolean;
+    trackClicks?: boolean;
+    replyTo?: string;
+    audienceIds?: string[];
+}
+/**
+ * Input for updating an existing broadcast
+ */
+interface UpdateBroadcastInput {
+    name?: string;
+    subject?: string;
+    preheader?: string;
+    content?: string;
+    trackOpens?: boolean;
+    trackClicks?: boolean;
+    replyTo?: string;
+    audienceIds?: string[];
+}
+/**
+ * Options for sending a broadcast
+ */
+interface SendBroadcastOptions {
+    audienceIds?: string[];
+    testMode?: boolean;
+    testRecipients?: string[];
+}
+/**
+ * Analytics data for a broadcast
+ */
+interface BroadcastAnalytics {
+    sent: number;
+    delivered: number;
+    opened: number;
+    clicked: number;
+    bounced: number;
+    complained: number;
+    unsubscribed: number;
+    deliveryRate?: number;
+    openRate?: number;
+    clickRate?: number;
+    bounceRate?: number;
+}
+/**
+ * Capabilities that a broadcast provider supports
+ */
+interface BroadcastProviderCapabilities {
+    supportsScheduling: boolean;
+    supportsSegmentation: boolean;
+    supportsAnalytics: boolean;
+    supportsABTesting: boolean;
+    supportsTemplates: boolean;
+    supportsPersonalization: boolean;
+    maxRecipientsPerSend?: number;
+    editableStatuses: BroadcastStatus[];
+    supportedContentTypes: ('html' | 'text' | 'react')[];
+    supportsMultipleChannels: boolean;
+    supportsChannelSegmentation: boolean;
+}
+/**
+ * Error types specific to broadcast operations
+ */
+declare class BroadcastProviderError extends Error {
+    code: BroadcastErrorCode;
+    provider: string;
+    details?: any | undefined;
+    constructor(message: string, code: BroadcastErrorCode, provider: string, details?: any | undefined);
+}
+declare enum BroadcastErrorCode {
+    NOT_SUPPORTED = "NOT_SUPPORTED",
+    INVALID_STATUS = "INVALID_STATUS",
+    PROVIDER_ERROR = "PROVIDER_ERROR",
+    VALIDATION_ERROR = "VALIDATION_ERROR",
+    NOT_FOUND = "NOT_FOUND",
+    PERMISSION_DENIED = "PERMISSION_DENIED",
+    RATE_LIMITED = "RATE_LIMITED",
+    CONFIGURATION_ERROR = "CONFIGURATION_ERROR",
+    CHANNEL_NOT_FOUND = "CHANNEL_NOT_FOUND",
+    INVALID_CHANNEL = "INVALID_CHANNEL"
+}
+/**
+ * Broadcast template for reusable content
+ */
+interface BroadcastTemplate {
+    id: string;
+    channelId?: string;
+    name: string;
+    description?: string;
+    content: string;
+    variables?: BroadcastTemplateVariable[];
+    createdAt: Date;
+    updatedAt: Date;
+}
+interface BroadcastTemplateVariable {
+    name: string;
+    type: 'text' | 'html' | 'image' | 'url';
+    defaultValue?: string;
+    required?: boolean;
+}
+
+interface Channel {
+    id: string;
+    name: string;
+    description?: string;
+    fromName: string;
+    fromEmail: string;
+    replyTo?: string;
+    providerId: string;
+    providerType: 'broadcast' | 'resend';
+    subscriberCount?: number;
+    active: boolean;
+    createdAt: Date;
+    updatedAt: Date;
+}
+interface CreateChannelInput {
+    name: string;
+    description?: string;
+    fromName: string;
+    fromEmail: string;
+    replyTo?: string;
+}
+interface UpdateChannelInput {
+    name?: string;
+    description?: string;
+    fromName?: string;
+    fromEmail?: string;
+    replyTo?: string;
+    active?: boolean;
+}
+interface ListChannelsOptions {
+    limit?: number;
+    offset?: number;
+    active?: boolean;
+}
+interface ListChannelsResponse {
+    channels: Channel[];
+    total: number;
+    limit: number;
+    offset: number;
+}
+
+/**
+ * Provider interfaces for broadcast management
+ */
+
+/**
+ * Main interface for broadcast providers
+ */
+interface BroadcastProvider {
+    /**
+     * Get the provider name
+     */
+    readonly name: string;
+    /**
+     * List channels (newsletter types/publications)
+     */
+    listChannels(options?: ListChannelsOptions): Promise<ListChannelsResponse>;
+    /**
+     * Get a specific channel by ID
+     */
+    getChannel(id: string): Promise<Channel>;
+    /**
+     * Create a new channel
+     */
+    createChannel(data: CreateChannelInput): Promise<Channel>;
+    /**
+     * Update an existing channel
+     */
+    updateChannel(id: string, data: UpdateChannelInput): Promise<Channel>;
+    /**
+     * Delete a channel
+     */
+    deleteChannel(id: string): Promise<void>;
+    /**
+     * List broadcasts with pagination
+     */
+    list(options?: ListBroadcastOptions): Promise<ListBroadcastResponse<Broadcast>>;
+    /**
+     * Get a specific broadcast by ID
+     */
+    get(id: string): Promise<Broadcast>;
+    /**
+     * Create a new broadcast
+     */
+    create(data: CreateBroadcastInput): Promise<Broadcast>;
+    /**
+     * Update an existing broadcast
+     */
+    update(id: string, data: UpdateBroadcastInput): Promise<Broadcast>;
+    /**
+     * Delete a broadcast
+     */
+    delete(id: string): Promise<void>;
+    /**
+     * Send a broadcast immediately or to test recipients
+     */
+    send(id: string, options?: SendBroadcastOptions): Promise<Broadcast>;
+    /**
+     * Schedule a broadcast for future sending
+     */
+    schedule(id: string, scheduledAt: Date): Promise<Broadcast>;
+    /**
+     * Cancel a scheduled broadcast
+     */
+    cancelSchedule(id: string): Promise<Broadcast>;
+    /**
+     * Get analytics for a broadcast
+     */
+    getAnalytics(id: string): Promise<BroadcastAnalytics>;
+    /**
+     * Get provider capabilities
+     */
+    getCapabilities(): BroadcastProviderCapabilities;
+    /**
+     * Validate that the provider is properly configured
+     */
+    validateConfiguration(): Promise<boolean>;
+}
+/**
+ * Legacy newsletter provider interface for backwards compatibility
+ * @deprecated Use BroadcastProvider instead
+ */
+interface NewsletterProvider {
+    /**
+     * Get the provider name
+     */
+    readonly name: string;
+    /**
+     * List newsletters with pagination
+     */
+    list(options?: ListNewsletterOptions): Promise<ListNewsletterResponse<Newsletter>>;
+    /**
+     * Get a specific newsletter by ID
+     */
+    get(id: string): Promise<Newsletter>;
+    /**
+     * Create a new newsletter
+     */
+    create(data: CreateNewsletterInput): Promise<Newsletter>;
+    /**
+     * Update an existing newsletter
+     */
+    update(id: string, data: UpdateNewsletterInput): Promise<Newsletter>;
+    /**
+     * Delete a newsletter
+     */
+    delete(id: string): Promise<void>;
+    /**
+     * Send a newsletter immediately or to test recipients
+     */
+    send(id: string, options?: SendNewsletterOptions): Promise<Newsletter>;
+    /**
+     * Schedule a newsletter for future sending
+     */
+    schedule(id: string, scheduledAt: Date): Promise<Newsletter>;
+    /**
+     * Cancel a scheduled newsletter
+     */
+    cancelSchedule(id: string): Promise<Newsletter>;
+    /**
+     * Get analytics for a newsletter
+     */
+    getAnalytics(id: string): Promise<NewsletterAnalytics>;
+    /**
+     * Get provider capabilities
+     */
+    getCapabilities(): NewsletterProviderCapabilities;
+    /**
+     * Validate that the provider is properly configured
+     */
+    validateConfiguration(): Promise<boolean>;
+}
+/**
+ * Base abstract class for broadcast providers
+ */
+declare abstract class BaseBroadcastProvider implements BroadcastProvider {
+    protected config: any;
+    abstract readonly name: string;
+    constructor(config: any);
+    abstract listChannels(options?: ListChannelsOptions): Promise<ListChannelsResponse>;
+    abstract getChannel(id: string): Promise<Channel>;
+    abstract createChannel(data: CreateChannelInput): Promise<Channel>;
+    abstract updateChannel(id: string, data: UpdateChannelInput): Promise<Channel>;
+    abstract deleteChannel(id: string): Promise<void>;
+    abstract list(options?: ListBroadcastOptions): Promise<ListBroadcastResponse<Broadcast>>;
+    abstract get(id: string): Promise<Broadcast>;
+    abstract create(data: CreateBroadcastInput): Promise<Broadcast>;
+    abstract update(id: string, data: UpdateBroadcastInput): Promise<Broadcast>;
+    abstract delete(id: string): Promise<void>;
+    abstract send(id: string, options?: SendBroadcastOptions): Promise<Broadcast>;
+    abstract getCapabilities(): BroadcastProviderCapabilities;
+    abstract validateConfiguration(): Promise<boolean>;
+    /**
+     * Schedule a broadcast - default implementation throws not supported
+     */
+    schedule(id: string, scheduledAt: Date): Promise<Broadcast>;
+    /**
+     * Cancel scheduled broadcast - default implementation throws not supported
+     */
+    cancelSchedule(id: string): Promise<Broadcast>;
+    /**
+     * Get analytics - default implementation returns zeros
+     */
+    getAnalytics(id: string): Promise<BroadcastAnalytics>;
+    /**
+     * Helper method to validate required fields
+     */
+    protected validateRequiredFields(data: any, fields: string[]): void;
+    /**
+     * Helper method to check if a status transition is allowed
+     */
+    protected canEditInStatus(status: BroadcastStatus): boolean;
+    /**
+     * Helper to build pagination response
+     */
+    protected buildListResponse<T>(items: T[], total: number, options?: ListBroadcastOptions): ListBroadcastResponse<T>;
+}
+/**
+ * Base abstract class for newsletter providers
+ * @deprecated Use BaseBroadcastProvider instead
+ */
+declare abstract class BaseNewsletterProvider implements NewsletterProvider {
+    protected config: any;
+    abstract readonly name: string;
+    constructor(config: any);
+    abstract list(options?: ListNewsletterOptions): Promise<ListNewsletterResponse<Newsletter>>;
+    abstract get(id: string): Promise<Newsletter>;
+    abstract create(data: CreateNewsletterInput): Promise<Newsletter>;
+    abstract update(id: string, data: UpdateNewsletterInput): Promise<Newsletter>;
+    abstract delete(id: string): Promise<void>;
+    abstract send(id: string, options?: SendNewsletterOptions): Promise<Newsletter>;
+    abstract getCapabilities(): NewsletterProviderCapabilities;
+    abstract validateConfiguration(): Promise<boolean>;
+    /**
+     * Schedule a newsletter - default implementation throws not supported
+     */
+    schedule(id: string, scheduledAt: Date): Promise<Newsletter>;
+    /**
+     * Cancel scheduled newsletter - default implementation throws not supported
+     */
+    cancelSchedule(id: string): Promise<Newsletter>;
+    /**
+     * Get analytics - default implementation returns zeros
+     */
+    getAnalytics(id: string): Promise<NewsletterAnalytics>;
+    /**
+     * Helper method to validate required fields
+     */
+    protected validateRequiredFields(data: any, fields: string[]): void;
+    /**
+     * Helper method to check if a status transition is allowed
+     */
+    protected canEditInStatus(status: NewsletterStatus): boolean;
+    /**
+     * Helper to build pagination response
+     */
+    protected buildListResponse<T>(items: T[], total: number, options?: ListNewsletterOptions): ListNewsletterResponse<T>;
+}
+
 interface NewsletterPluginConfig {
     /**
      * Enable or disable the plugin
@@ -186,6 +771,36 @@ interface NewsletterPluginConfig {
              */
             queue?: string;
         };
+        /**
+         * Newsletter management configuration
+         */
+        newsletterManagement?: {
+            /**
+             * Enable newsletter management features
+             * @default false
+             */
+            enabled?: boolean;
+            /**
+             * Collection names for broadcast management
+             */
+            collections?: {
+                /**
+                 * Channels collection slug
+                 * @default 'channels'
+                 */
+                channels?: string;
+                /**
+                 * Broadcasts collection slug
+                 * @default 'broadcasts'
+                 */
+                broadcasts?: string;
+            };
+            /**
+             * Optional: Custom broadcast provider implementation
+             * If not provided, will use the default email provider
+             */
+            provider?: BroadcastProvider;
+        };
     };
     /**
      * Internationalization configuration
@@ -197,8 +812,10 @@ interface NewsletterPluginConfig {
 }
 interface ResendProviderConfig {
     apiKey: string;
+    fromEmail?: string;
     fromAddress?: string;
     fromName?: string;
+    replyTo?: string;
     audienceIds?: {
         [locale: string]: {
             production?: string;
@@ -212,8 +829,10 @@ interface BroadcastProviderConfig {
         production?: string;
         development?: string;
     };
+    fromEmail?: string;
     fromAddress?: string;
     fromName?: string;
+    replyTo?: string;
 }
 interface EmailProvider {
     send(params: SendEmailParams): Promise<void>;
@@ -427,4 +1046,4 @@ interface ExtendedPayloadRequest extends Request {
     };
 }
 
-export type { AfterSubscribeArgs, AfterUnsubscribeArgs, AfterUnsubscribeSyncArgs, BeforeSubscribeArgs, BeforeUnsubscribeArgs, BroadcastProviderConfig, EmailProvider, ExtendedPayloadRequest, MagicLinkEmailProps, NewsletterPluginConfig, PreferencesFormProps, ResendProviderConfig, SendEmailParams, SigninRequestData, SignupFormProps, SubscribeRequestData, Subscriber, SurveyQuestion, UnsubscribeRequestData, UpdatePreferencesRequestData, VerifyMagicLinkRequestData, WelcomeEmailProps };
+export { type AfterSubscribeArgs, type AfterUnsubscribeArgs, type AfterUnsubscribeSyncArgs, BaseBroadcastProvider, BaseNewsletterProvider, type BeforeSubscribeArgs, type BeforeUnsubscribeArgs, type Broadcast, type BroadcastAnalytics, BroadcastErrorCode, type BroadcastProvider, type BroadcastProviderCapabilities, type BroadcastProviderConfig, BroadcastProviderError, BroadcastStatus, type BroadcastTemplate, type BroadcastTemplateVariable, type Channel, type CreateBroadcastInput, type CreateChannelInput, type CreateNewsletterInput, type EmailProvider, type ExtendedPayloadRequest, type ListBroadcastOptions, type ListBroadcastResponse, type ListChannelsOptions, type ListChannelsResponse, type ListNewsletterOptions, type ListNewsletterResponse, type MagicLinkEmailProps, type Newsletter, type NewsletterAnalytics, NewsletterErrorCode, type NewsletterPluginConfig, type NewsletterProvider, type NewsletterProviderCapabilities, NewsletterProviderError, NewsletterStatus, type NewsletterTemplate, type NewsletterTemplateVariable, type PreferencesFormProps, type ResendProviderConfig, type SendBroadcastOptions, type SendEmailParams, type SendNewsletterOptions, type SigninRequestData, type SignupFormProps, type SubscribeRequestData, type Subscriber, type SurveyQuestion, type UnsubscribeRequestData, type UpdateBroadcastInput, type UpdateChannelInput, type UpdateNewsletterInput, type UpdatePreferencesRequestData, type VerifyMagicLinkRequestData, type WelcomeEmailProps };