@latte-macchiat-io/latte-payload 1.0.1

package/src/collections/QueuedEmails/components/RetryEmailButtons.tsx

@@ -0,0 +1,115 @@
+'use client';
+
+import { useDocumentInfo, useFormFields } from '@payloadcms/ui';
+import { useState } from 'react';
+
+export const RetryEmailButtons: React.FC = () => {
+  const { id } = useDocumentInfo();
+  const [isRetrying, setIsRetrying] = useState(false);
+  const [message, setMessage] = useState<{ type: 'success' | 'error'; text: string } | null>(null);
+
+  const attemptCount = useFormFields(([fields]) => fields.attemptCount?.value as number);
+  const maxAttempts = useFormFields(([fields]) => fields.maxAttempts?.value as number);
+  const status = useFormFields(([fields]) => fields.status?.value as string);
+
+  // Only show if email has failed and reached max attempts
+  if (status !== 'failed' || attemptCount < maxAttempts) {
+    return null;
+  }
+
+  const handleRetry = async (additionalAttempts: number) => {
+    if (!id) return;
+
+    setIsRetrying(true);
+    setMessage(null);
+
+    try {
+      const response = await fetch(`/api/queued-emails/${id}`, {
+        method: 'PATCH',
+        headers: {
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({
+          maxAttempts: maxAttempts + additionalAttempts,
+          status: 'pending', // Reset to pending so job picks it up
+        }),
+      });
+
+      if (!response.ok) {
+        throw new Error(`Failed to update email: ${response.statusText}`);
+      }
+
+      setMessage({
+        type: 'success',
+        text: `Email réinitialisé avec succès. ${additionalAttempts} tentative(s) supplémentaire(s) ajoutée(s). Le job va réessayer l'envoi.`,
+      });
+
+      // Reload the page after 2 seconds to show updated data
+      setTimeout(() => {
+        window.location.reload();
+      }, 2000);
+    } catch (error) {
+      setMessage({
+        type: 'error',
+        text: `Erreur lors de la réinitialisation: ${error instanceof Error ? error.message : 'Unknown error'}`,
+      });
+    } finally {
+      setIsRetrying(false);
+    }
+  };
+
+  return (
+    <div style={{ marginBottom: '1rem', padding: '1rem', backgroundColor: '#f9f9f9', borderRadius: '4px' }}>
+      <div style={{ marginBottom: '0.5rem', fontWeight: 600 }}>Réessayer l'envoi de l'email</div>
+      <div style={{ marginBottom: '1rem', fontSize: '0.9rem', color: '#666' }}>
+        Cet email a atteint le nombre maximum de tentatives ({maxAttempts}). Vous pouvez ajouter des tentatives supplémentaires pour réessayer
+        l'envoi.
+      </div>
+      <div style={{ display: 'flex', gap: '0.5rem' }}>
+        <button
+          type="button"
+          onClick={() => handleRetry(1)}
+          disabled={isRetrying}
+          style={{
+            padding: '0.5rem 1rem',
+            backgroundColor: '#0070f3',
+            color: 'white',
+            border: 'none',
+            borderRadius: '4px',
+            cursor: isRetrying ? 'not-allowed' : 'pointer',
+            opacity: isRetrying ? 0.6 : 1,
+          }}>
+          {isRetrying ? 'Traitement...' : '+1 tentative'}
+        </button>
+        <button
+          type="button"
+          onClick={() => handleRetry(5)}
+          disabled={isRetrying}
+          style={{
+            padding: '0.5rem 1rem',
+            backgroundColor: '#0070f3',
+            color: 'white',
+            border: 'none',
+            borderRadius: '4px',
+            cursor: isRetrying ? 'not-allowed' : 'pointer',
+            opacity: isRetrying ? 0.6 : 1,
+          }}>
+          {isRetrying ? 'Traitement...' : '+5 tentatives'}
+        </button>
+      </div>
+      {message && (
+        <div
+          style={{
+            marginTop: '1rem',
+            padding: '0.75rem',
+            backgroundColor: message.type === 'success' ? '#d4edda' : '#f8d7da',
+            color: message.type === 'success' ? '#155724' : '#721c24',
+            borderRadius: '4px',
+            fontSize: '0.9rem',
+          }}>
+          {message.text}
+        </div>
+      )}
+    </div>
+  );
+};

package/src/collections/QueuedEmails/index.ts

@@ -0,0 +1,246 @@
+import { CollectionConfig } from 'payload';
+import { admins } from '../../access/admins';
+
+export const QueuedEmails: CollectionConfig = {
+  slug: 'queued-emails',
+  labels: {
+    singular: { fr: 'Email en file', nl: 'E-mail in wachtrij', en: 'Queued Email' },
+    plural: { fr: 'Emails en file', nl: 'E-mails in wachtrij', en: 'Queued Emails' },
+  },
+  admin: {
+    description: { fr: "File d'attente des emails à envoyer", nl: 'Wachtrij van te verzenden e-mails', en: 'Queue of emails to send' },
+    group: '✉️ Communication',
+    defaultColumns: ['status', 'code', 'recipient', 'createdAt', 'sentAt'],
+    hideAPIURL: true,
+  },
+  access: {
+    create: () => false, // Only created programmatically
+    delete: admins, // Allow admins to clean up old emails
+    read: admins,
+    update: admins, // Allow admins to manually retry failed emails
+    admin: admins,
+  },
+  fields: [
+    {
+      name: 'idempotencyKey',
+      label: { fr: "Clé d'idempotence", nl: 'Idempotentiesleutel', en: 'Idempotency Key' },
+      type: 'text',
+      required: false,
+      unique: true,
+      index: true,
+      admin: {
+        readOnly: true,
+        description: {
+          fr: 'Clé unique pour éviter les doublons',
+          nl: 'Unieke sleutel om duplicaten te voorkomen',
+          en: 'Unique key to prevent duplicates',
+        },
+      },
+    },
+    {
+      type: 'row',
+      fields: [
+        {
+          name: 'status',
+          label: { fr: 'Statut', nl: 'Status', en: 'Status' },
+          type: 'select',
+          required: true,
+          defaultValue: 'pending',
+          options: [
+            { label: { fr: 'En attente', nl: 'In afwachting', en: 'Pending' }, value: 'pending' },
+            { label: { fr: 'Envoi en cours', nl: 'Verzenden', en: 'Sending' }, value: 'sending' },
+            { label: { fr: 'Envoyé', nl: 'Verzonden', en: 'Sent' }, value: 'sent' },
+            { label: { fr: 'Échec', nl: 'Mislukt', en: 'Failed' }, value: 'failed' },
+          ],
+          admin: {
+            readOnly: true,
+          },
+        },
+        {
+          name: 'code',
+          label: { fr: 'Identifiant', nl: 'Identificatie', en: 'Code' },
+          type: 'text',
+          required: true,
+          admin: {
+            readOnly: true,
+          },
+        },
+      ],
+    },
+    {
+      name: 'retryActions',
+      type: 'ui',
+      admin: {
+        components: {
+          Field: '@latte-macchiat-io/latte-payload/collections/QueuedEmails/components/RetryEmailButtons#RetryEmailButtons',
+        },
+        condition: (data) => data.status === 'failed' && data.attemptCount >= data.maxAttempts,
+      },
+    },
+    {
+      type: 'row',
+      fields: [
+        {
+          name: 'recipient',
+          label: { fr: 'Destinataire', nl: 'Ontvanger', en: 'Recipient' },
+          type: 'text',
+          required: true,
+          admin: {
+            readOnly: true,
+          },
+        },
+        {
+          name: 'cc',
+          label: { fr: 'CC', nl: 'CC', en: 'CC' },
+          type: 'text',
+          required: false,
+          admin: {
+            readOnly: true,
+          },
+        },
+      ],
+    },
+    {
+      name: 'subject',
+      label: { fr: "Sujet de l'email", nl: 'Onderwerp van de e-mail', en: 'Email subject' },
+      type: 'text',
+      required: true,
+      admin: {
+        readOnly: true,
+      },
+    },
+    {
+      name: 'htmlBody',
+      label: { fr: "Contenu de l'email", nl: 'Inhoud van de e-mail', en: 'Email content' },
+      type: 'textarea',
+      required: true,
+      admin: {
+        readOnly: true,
+        components: {
+          Field: '@latte-macchiat-io/latte-payload/collections/QueuedEmails/components/HtmlViewer#HTMLViewer',
+        },
+      },
+    },
+    {
+      type: 'row',
+      fields: [
+        {
+          name: 'attemptCount',
+          label: { fr: 'Nombre de tentatives', nl: 'Aantal pogingen', en: 'Attempt count' },
+          type: 'number',
+          required: true,
+          defaultValue: 0,
+          admin: {
+            readOnly: true,
+          },
+        },
+        {
+          name: 'maxAttempts',
+          label: { fr: 'Tentatives maximales', nl: 'Maximaal aantal pogingen', en: 'Max attempts' },
+          type: 'number',
+          required: true,
+          defaultValue: 5,
+          admin: {
+            readOnly: true,
+          },
+        },
+      ],
+    },
+    {
+      name: 'lastError',
+      label: { fr: 'Dernière erreur', nl: 'Laatste fout', en: 'Last error' },
+      type: 'textarea',
+      required: false,
+      admin: {
+        readOnly: true,
+        condition: (data) => data.status === 'failed',
+      },
+    },
+    {
+      name: 'errorHistory',
+      label: { fr: 'Historique des erreurs', nl: 'Foutengeschiedenis', en: 'Error history' },
+      type: 'array',
+      required: false,
+      admin: {
+        readOnly: true,
+        condition: (data) => data.errorHistory && data.errorHistory.length > 0,
+        description: {
+          fr: 'Liste complète de toutes les erreurs rencontrées',
+          nl: 'Volledige lijst van alle fouten',
+          en: 'Complete list of all errors encountered',
+        },
+      },
+      fields: [
+        {
+          name: 'timestamp',
+          label: { fr: 'Date', nl: 'Datum', en: 'Timestamp' },
+          type: 'date',
+          required: true,
+          timezone: true,
+          admin: {
+            readOnly: true,
+            date: {
+              pickerAppearance: 'dayAndTime',
+              timeFormat: 'HH:mm:ss',
+              displayFormat: 'dd/MM/yyyy HH:mm:ss',
+            },
+          },
+        },
+        {
+          name: 'attemptNumber',
+          label: { fr: 'Tentative n°', nl: 'Poging nr.', en: 'Attempt #' },
+          type: 'number',
+          required: true,
+          admin: {
+            readOnly: true,
+          },
+        },
+        {
+          name: 'error',
+          label: { fr: "Message d'erreur", nl: 'Foutmelding', en: 'Error message' },
+          type: 'textarea',
+          required: true,
+          admin: {
+            readOnly: true,
+          },
+        },
+      ],
+    },
+    {
+      type: 'row',
+      fields: [
+        {
+          name: 'lastAttemptAt',
+          label: { fr: 'Dernière tentative', nl: 'Laatste poging', en: 'Last attempt' },
+          type: 'date',
+          required: false,
+          timezone: true,
+          admin: {
+            readOnly: true,
+            date: {
+              pickerAppearance: 'dayAndTime',
+              timeFormat: 'HH:mm:ss',
+              displayFormat: 'dd/MM/yyyy HH:mm:ss',
+            },
+          },
+        },
+        {
+          name: 'sentAt',
+          label: { fr: "Date d'envoi", nl: 'Verzenddatum', en: 'Sent at' },
+          type: 'date',
+          required: false,
+          timezone: true,
+          admin: {
+            readOnly: true,
+            date: {
+              pickerAppearance: 'dayAndTime',
+              timeFormat: 'HH:mm:ss',
+              displayFormat: 'dd/MM/yyyy HH:mm:ss',
+            },
+            condition: (data) => data.status === 'sent',
+          },
+        },
+      ],
+    },
+  ],
+};

package/src/collections/Users/auth-emails/forgot-password-email.ts

@@ -0,0 +1,135 @@
+import { TZDate } from '@date-fns/tz';
+import { headers } from 'next/headers';
+import { PayloadRequest, TypedUser } from 'payload';
+import type { EmailTemplateCode, Locale } from '../../../types';
+import { generateEmailHtmlFromTemplate, toDatabaseTZDate } from '../../../utils';
+
+const emailCode: EmailTemplateCode = 'password-lost';
+
+export interface ForgotPasswordEmailConfig {
+  /**
+   * Default locale to use if user has no locale set
+   * @default 'en'
+   */
+  defaultLocale?: Locale;
+
+  /**
+   * Function to generate the password reset URL
+   * @param token - The reset token
+   * @param user - The user object
+   * @returns The full password reset URL
+   */
+  generateResetUrl?: (token: string, user: TypedUser) => Promise<string> | string;
+
+  /**
+   * Timezone for logging email send time
+   * @default 'Europe/Brussels'
+   */
+  timezone?: string;
+}
+
+/**
+ * Create forgot password email HTML generator with custom configuration
+ */
+export function createForgotPasswordEmailGenerator(config?: ForgotPasswordEmailConfig) {
+  const defaultLocale = config?.defaultLocale || 'en';
+  const timezone = config?.timezone || 'Europe/Brussels';
+
+  return async function generateForgotPasswordEmailHtmlFromTemplate(args?: {
+    req?: PayloadRequest;
+    token?: string;
+    user?: TypedUser;
+  }): Promise<string> {
+    if (!args || !args.req || !args.token || !args.user) {
+      throw new Error(`generateForgotPasswordEmailHtmlFromTemplate > Missing required parameters`);
+    }
+
+    const payload = args.req.payload;
+
+    // Generate reset URL
+    let resetUrl: string;
+    if (config?.generateResetUrl) {
+      resetUrl = await config.generateResetUrl(args.token, args.user);
+    } else {
+      // Default URL generation
+      const headersList = await headers();
+      const requestDomain = headersList.get('host') || 'localhost:3000';
+      const protocol = requestDomain.includes('localhost') ? 'http' : 'https';
+      resetUrl = `${protocol}://${requestDomain}/reset-password?token=${args.token}`;
+    }
+
+    const emailContent = await generateEmailHtmlFromTemplate({
+      payload: payload,
+      emailCode: emailCode,
+      locale: args.user.locale || defaultLocale,
+      variables: {
+        name: args.user.name || '',
+        token: args.token,
+        url: resetUrl,
+      },
+    });
+
+    console.log(`Sending email to ${args.user.email} with subject ${emailContent?.subject}`);
+
+    // Log the email in queued-emails as 'sent' for tracking (Payload sends this directly)
+    try {
+      await payload.create({
+        collection: 'queued-emails',
+        data: {
+          status: 'sent',
+          code: emailCode,
+          recipient: args.user.email || '',
+          subject: emailContent?.subject || '',
+          htmlBody: emailContent?.body || '',
+          attemptCount: 1,
+          maxAttempts: 1,
+          sentAt: toDatabaseTZDate(TZDate.tz(timezone)),
+          // No idempotencyKey to allow multiple password reset emails
+        },
+      });
+    } catch (error) {
+      payload.logger.error(`Error logging sent email in queued-emails: ${error}`);
+    }
+
+    return emailContent?.body || `Template ${emailCode} not found`;
+  };
+}
+
+/**
+ * Create forgot password email subject generator with custom configuration
+ */
+export function createForgotPasswordEmailSubjectGenerator(config?: ForgotPasswordEmailConfig) {
+  const defaultLocale = config?.defaultLocale || 'en';
+
+  return async function generateForgotPasswordEmailSubjectFromTemplate(args?: {
+    req?: PayloadRequest;
+    token?: string;
+    user?: TypedUser;
+  }): Promise<string> {
+    if (!args || !args.req || !args.user) {
+      throw new Error(`generateForgotPasswordEmailSubjectFromTemplate > Missing required parameters`);
+    }
+
+    const payload = args.req.payload;
+
+    const emailContentTemplateDocs = await payload.find({
+      collection: 'email-templates',
+      where: { code: { equals: emailCode } },
+      limit: 1,
+      locale: args.user.locale || defaultLocale,
+    });
+
+    if (!emailContentTemplateDocs || emailContentTemplateDocs.totalDocs === 0) {
+      payload.logger.error(`Email template with code ${emailCode} not found`);
+      return `Template "${emailCode}" not found`;
+    }
+
+    return emailContentTemplateDocs.docs[0]?.subject || `Template "${emailCode}" not found`;
+  };
+}
+
+/**
+ * Default forgot password email generators
+ */
+export const generateForgotPasswordEmailHtmlFromTemplate = createForgotPasswordEmailGenerator();
+export const generateForgotPasswordEmailSubjectFromTemplate = createForgotPasswordEmailSubjectGenerator();

package/src/collections/Users/auth-emails/verify-email.ts

@@ -0,0 +1,123 @@
+import { TZDate } from '@date-fns/tz';
+import { headers } from 'next/headers';
+import { PayloadRequest, TypedUser } from 'payload';
+import type { EmailTemplateCode, Locale } from '../../../types';
+import { generateEmailHtmlFromTemplate, getEmailTemplateByCode, toDatabaseTZDate } from '../../../utils';
+
+const emailCode: EmailTemplateCode = 'verify-email';
+
+export interface VerifyEmailConfig {
+  /**
+   * Default locale to use if user has no locale set
+   * @default 'en'
+   */
+  defaultLocale?: Locale;
+
+  /**
+   * Function to generate the verification URL
+   * @param token - The verification token
+   * @param user - The user object
+   * @returns The full verification URL
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  generateVerifyUrl?: (token: string, user: any) => Promise<string> | string;
+
+  /**
+   * Timezone for logging email send time
+   * @default 'Europe/Brussels'
+   */
+  timezone?: string;
+}
+
+/**
+ * Create verify email HTML generator with custom configuration
+ */
+export function createVerifyEmailGenerator(config?: VerifyEmailConfig) {
+  const defaultLocale = config?.defaultLocale || 'en';
+  const timezone = config?.timezone || 'Europe/Brussels';
+
+  return async function generateVerifyEmailHtmlFromTemplate({
+    req,
+    token,
+    user,
+  }: {
+    req: PayloadRequest;
+    token: string;
+    user: TypedUser;
+  }): Promise<string> {
+    const payload = req.payload;
+
+    // Generate verification URL
+    let verifyUrl: string;
+    if (config?.generateVerifyUrl) {
+      verifyUrl = await config.generateVerifyUrl(token, user);
+    } else {
+      // Default URL generation
+      const headersList = await headers();
+      const requestDomain = headersList.get('host') || 'localhost:3000';
+      const protocol = requestDomain.includes('localhost') ? 'http' : 'https';
+      verifyUrl = `${protocol}://${requestDomain}/verify-email?token=${token}`;
+    }
+
+    const emailContent = await generateEmailHtmlFromTemplate({
+      payload: payload,
+      emailCode: emailCode,
+      locale: user.locale || defaultLocale,
+      variables: {
+        name: user.name || '',
+        token: token,
+        url: verifyUrl,
+      },
+    });
+
+    payload.logger.debug(`Sending email to ${user.email} with subject ${emailContent?.subject}`);
+
+    // Log the email in queued-emails as 'sent' for tracking (Payload sends this directly)
+    try {
+      await payload.create({
+        collection: 'queued-emails',
+        data: {
+          idempotencyKey: `${emailCode}-${user.id}`,
+          status: 'sent',
+          code: emailCode,
+          recipient: user.email || '',
+          subject: emailContent?.subject || '',
+          htmlBody: emailContent?.body || '',
+          attemptCount: 1,
+          maxAttempts: 1,
+          sentAt: toDatabaseTZDate(TZDate.tz(timezone)),
+        },
+      });
+    } catch (error) {
+      payload.logger.error(`Error logging sent email in queued-emails: ${error}`);
+    }
+
+    return emailContent?.body || 'Template "verify-email" not found';
+  };
+}
+
+/**
+ * Create verify email subject generator with custom configuration
+ */
+export function createVerifyEmailSubjectGenerator(config?: VerifyEmailConfig) {
+  const defaultLocale = config?.defaultLocale || 'en';
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  return async function generateVerifyEmailSubjectFromTemplate({ req, user }: { req: PayloadRequest; token: string; user: any }): Promise<string> {
+    const payload = req.payload;
+
+    const template = await getEmailTemplateByCode({
+      locale: user.locale || defaultLocale,
+      code: emailCode,
+      payload,
+    });
+
+    return template?.subject || `Template "${emailCode}" not found`;
+  };
+}
+
+/**
+ * Default verify email generators
+ */
+export const generateVerifyEmailHtmlFromTemplate = createVerifyEmailGenerator();
+export const generateVerifyEmailSubjectFromTemplate = createVerifyEmailSubjectGenerator();

package/src/collections/Users/hooks/ensureFirstUserIsAdmin.ts

@@ -0,0 +1,22 @@
+import type { FieldHook } from 'payload';
+
+// ensure the first user created is an admin
+// 1. lookup a single user on create as succinctly as possible
+// 2. if there are no users found, append `admin` to the roles array
+// access control is already handled by this fields `access` property
+// it ensures that only admins can create and update the `roles` field
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export const ensureFirstUserIsAdmin: FieldHook<any> = async ({ req, operation, value }) => {
+  if (operation === 'create') {
+    const users = await req.payload.find({ collection: 'users', limit: 0, depth: 0 });
+    if (users.totalDocs === 0) {
+      // if `admin` not in array of values, add it
+      if (!(value || []).includes('admin')) {
+        return [...(value || []), 'admin'];
+      }
+    }
+  }
+
+  return value;
+};