@latte-macchiat-io/latte-payload 1.0.1

package/src/collections/Users/index.ts

@@ -0,0 +1,201 @@
+import type { CollectionConfig } from 'payload';
+
+import {
+  createForgotPasswordEmailGenerator,
+  createForgotPasswordEmailSubjectGenerator,
+  type ForgotPasswordEmailConfig,
+  generateForgotPasswordEmailHtmlFromTemplate,
+  generateForgotPasswordEmailSubjectFromTemplate,
+} from './auth-emails/forgot-password-email';
+import {
+  createVerifyEmailGenerator,
+  createVerifyEmailSubjectGenerator,
+  generateVerifyEmailHtmlFromTemplate,
+  generateVerifyEmailSubjectFromTemplate,
+  type VerifyEmailConfig,
+} from './auth-emails/verify-email';
+import { ensureFirstUserIsAdmin } from './hooks/ensureFirstUserIsAdmin';
+import { adminsFieldLevel } from '../../access/admins';
+import { authenticatedAccessOnly } from '../../access/authenticatedAccessOnly';
+import type { Locale } from '../../types';
+
+export interface UsersCollectionConfig {
+  /**
+   * User roles
+   * @default ['admin', 'user']
+   */
+  roles?: Array<{ label: { fr: string; nl: string; en: string }; value: string }>;
+
+  /**
+   * Available locales for users
+   * @default [{ label: { fr: 'Anglais', nl: 'Engels', en: 'English' }, value: 'en' }, ...]
+   */
+  locales?: Array<{ label: { fr: string; nl: string; en: string }; value: Locale }>;
+
+  /**
+   * Default locale
+   * @default 'en'
+   */
+  defaultLocale?: Locale;
+
+  /**
+   * Token expiration in seconds
+   * @default 60 * 60 * 24 * 365 (1 year)
+   */
+  tokenExpiration?: number;
+
+  /**
+   * Maximum login attempts before lockout
+   * @default 10
+   */
+  maxLoginAttempts?: number;
+
+  /**
+   * Lockout time in milliseconds
+   * @default 1000 * 60 * 10 (10 minutes)
+   */
+  lockTime?: number;
+
+  /**
+   * Forgot password expiration in milliseconds
+   * @default 1000 * 60 * 60 * 24 * 10 (10 days)
+   */
+  forgotPasswordExpiration?: number;
+
+  /**
+   * Configuration for verify email
+   */
+  verifyEmailConfig?: VerifyEmailConfig;
+
+  /**
+   * Configuration for forgot password email
+   */
+  forgotPasswordEmailConfig?: ForgotPasswordEmailConfig;
+}
+
+/**
+ * Create Users collection with optional configuration
+ *
+ * @param config - Optional configuration for the Users collection
+ * @returns CollectionConfig for Users
+ */
+export function createUsersCollection(config?: UsersCollectionConfig): CollectionConfig {
+  const roles = config?.roles || [
+    {
+      label: { fr: 'Administrateur', nl: 'Beheerder', en: 'Admin' },
+      value: 'admin',
+    },
+    {
+      label: { fr: 'User', nl: 'Gebruiker', en: 'User' },
+      value: 'user',
+    },
+  ];
+
+  const locales = config?.locales || [
+    {
+      label: { fr: 'Anglais', nl: 'Engels', en: 'English' },
+      value: 'en' as Locale,
+    },
+    {
+      label: { fr: 'Français', nl: 'Frans', en: 'French' },
+      value: 'fr' as Locale,
+    },
+    {
+      label: { fr: 'Néerlandais', nl: 'Nederlands', en: 'Dutch' },
+      value: 'nl' as Locale,
+    },
+  ];
+
+  return {
+    slug: 'users',
+    labels: {
+      singular: { fr: 'Utilisateur', en: 'User', nl: 'Gebruiker' },
+      plural: { fr: 'Utilisateurs', en: 'Users', nl: 'Gebruikers' },
+    },
+    admin: {
+      useAsTitle: 'email',
+      hideAPIURL: true,
+      group: { fr: 'Utilisateurs', nl: 'Gebruikers', en: 'Users' },
+    },
+    access: authenticatedAccessOnly,
+    auth: {
+      tokenExpiration: config?.tokenExpiration ?? 60 * 60 * 24 * 365, // In seconds, 1 year
+      maxLoginAttempts: config?.maxLoginAttempts ?? 10,
+      lockTime: config?.lockTime ?? 1000 * 60 * 10, // In milliseconds, 10 minutes
+
+      verify: {
+        generateEmailHTML: config?.verifyEmailConfig ? createVerifyEmailGenerator(config.verifyEmailConfig) : generateVerifyEmailHtmlFromTemplate,
+        generateEmailSubject: config?.verifyEmailConfig
+          ? createVerifyEmailSubjectGenerator(config.verifyEmailConfig)
+          : generateVerifyEmailSubjectFromTemplate,
+      },
+      forgotPassword: {
+        expiration: config?.forgotPasswordExpiration ?? 1000 * 60 * 60 * 24 * 10, // In milliseconds, 10 days
+        generateEmailHTML: config?.forgotPasswordEmailConfig
+          ? createForgotPasswordEmailGenerator(config.forgotPasswordEmailConfig)
+          : generateForgotPasswordEmailHtmlFromTemplate,
+        generateEmailSubject: config?.forgotPasswordEmailConfig
+          ? createForgotPasswordEmailSubjectGenerator(config.forgotPasswordEmailConfig)
+          : generateForgotPasswordEmailSubjectFromTemplate,
+      },
+    },
+
+    fields: [
+      // Email added by default
+      // Add more fields as needed
+
+      {
+        type: 'row',
+        fields: [
+          {
+            name: 'name',
+            label: { fr: 'Nom', nl: 'Naam', en: 'Name' },
+            type: 'text',
+            required: false,
+          },
+
+          {
+            name: 'locale',
+            label: { fr: 'Langue', nl: 'Taal', en: 'Language' },
+            type: 'select',
+            hasMany: false,
+            defaultValue: config?.defaultLocale || 'en',
+            options: locales,
+          },
+        ],
+      },
+
+      {
+        name: 'roles',
+        label: { fr: 'Rôles', nl: 'Rollen', en: 'Roles' },
+        type: 'select',
+        hasMany: true,
+        defaultValue: ['user'],
+        options: roles,
+        hooks: {
+          beforeChange: [ensureFirstUserIsAdmin],
+        },
+        access: {
+          read: adminsFieldLevel,
+          create: adminsFieldLevel,
+          update: adminsFieldLevel,
+        },
+      },
+    ],
+  };
+}
+
+/**
+ * Default Users collection
+ */
+export const Users = createUsersCollection();
+
+// Re-export auth email generators for customization
+export {
+  createVerifyEmailGenerator,
+  createVerifyEmailSubjectGenerator,
+  createForgotPasswordEmailGenerator,
+  createForgotPasswordEmailSubjectGenerator,
+  type VerifyEmailConfig,
+  type ForgotPasswordEmailConfig,
+};

package/src/collections/index.ts

@@ -0,0 +1,23 @@
+// Collections
+export { Users, createUsersCollection, type UsersCollectionConfig } from './Users';
+export { Media } from './Media';
+export { ContactMessages, createContactMessagesCollection, type ContactMessagesConfig } from './ContactMessages';
+export { EmailTemplates, createEmailTemplatesCollection, type EmailTemplatesConfig } from './EmailTemplates';
+export { QueuedEmails } from './QueuedEmails';
+
+// Users auth emails
+export {
+  createVerifyEmailGenerator,
+  createVerifyEmailSubjectGenerator,
+  createForgotPasswordEmailGenerator,
+  createForgotPasswordEmailSubjectGenerator,
+  type VerifyEmailConfig,
+  type ForgotPasswordEmailConfig,
+} from './Users';
+
+// ContactMessages hooks
+export { createSendEmailNotificationHook, type SendEmailNotificationConfig } from './ContactMessages';
+
+// QueuedEmails components
+export { HTMLViewer } from './QueuedEmails/components/HtmlViewer';
+export { RetryEmailButtons } from './QueuedEmails/components/RetryEmailButtons';

package/src/components/index.ts

@@ -0,0 +1,3 @@
+// Re-export components from collections for backward compatibility
+export { HTMLViewer } from '../collections/QueuedEmails/components/HtmlViewer';
+export { RetryEmailButtons } from '../collections/QueuedEmails/components/RetryEmailButtons';

package/src/forms/states.ts

@@ -0,0 +1,23 @@
+export function createSuccessFormState<T>(previousState: T): { success: true } & T {
+  return {
+    ...previousState,
+    success: true,
+  };
+}
+
+// TODO createErrorFormState
+
+export function extractFormDataToReturn<T extends Record<string, unknown>>({
+  formData,
+  excludes,
+}: {
+  formData: FormData;
+  excludes?: (keyof T)[];
+}): T {
+  const data = Object.fromEntries(formData.entries()) as T;
+  excludes?.forEach((field) => {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    (data as any)[field] = '';
+  });
+  return data;
+}

package/src/forms/translate-errors.ts

@@ -0,0 +1,13 @@
+import { getTranslations } from 'next-intl/server';
+import { z } from 'zod';
+
+// Utility to translate error keys using i18n
+export async function translateFormErrors<T extends z.ZodTypeAny>(errors: z.inferFlattenedErrors<T>) {
+  const t = await getTranslations();
+  const translate = (messages?: string[]) => messages?.map((msg) => t(msg)) ?? [];
+
+  return {
+    fieldErrors: Object.fromEntries(Object.entries(errors.fieldErrors).map(([field, msgs]) => [field, translate(msgs as string[])])),
+    formErrors: translate(errors.formErrors),
+  };
+}

package/src/forms/validators.ts

@@ -0,0 +1,33 @@
+import { z } from 'zod';
+
+export const requiredString = (message: string) =>
+  z
+    .string({ errorMap: () => ({ message }) }) // Same error message for all errors
+    .trim()
+    .nonempty();
+
+export const requiredPasswordString = (minLength: number, requiredMessage: string, minLengthMessage: string) =>
+  z
+    .string({ errorMap: () => ({ message: requiredMessage }) }) // Same error message for all errors
+    .trim()
+    .nonempty()
+    .pipe(
+      z.string().min(minLength, { message: minLengthMessage }) // Ensure password is at least 12 characters long
+    );
+
+export const requiredEmailString = ({ required, email }: { required: string; email: string }) =>
+  z
+    .string() // Same error message for all errors
+    .trim()
+    .nonempty({ message: required })
+    .pipe(z.string().email({ message: email })); // “email” runs only if nonempty passed
+
+export const validHoneyPot = (message: string) =>
+  z
+    .string({ errorMap: () => ({ message }) }) // Same error message for all errors
+    .refine((val) => val.length === 0); // Must be empty
+
+export const requiredCheckbox = (message: string) =>
+  z
+    .boolean({ errorMap: () => ({ message }) }) // Same error message for all errors
+    .refine((val) => val); // Must be true

package/src/globals/PrivacyPolicy/hooks/revalidate-cache.ts

@@ -0,0 +1,5 @@
+import { revalidatePath } from 'next/cache';
+
+export const revalidateCache = async () => {
+  revalidatePath('/', 'layout');
+};

package/src/globals/PrivacyPolicy/index.ts

@@ -0,0 +1,33 @@
+import type { GlobalConfig } from 'payload';
+
+import { revalidateCache } from './hooks/revalidate-cache';
+import { authenticatedAccessOnly } from '../../access/authenticatedAccessOnly';
+
+export const PrivacyPolicy: GlobalConfig = {
+  slug: 'privacy-policy',
+  label: { fr: 'Politique de confidentialité', nl: 'Privacybeleid', en: 'Privacy Policy' },
+  admin: {
+    group: { fr: 'Légal', nl: 'Juridisch', en: 'Legal' },
+    hideAPIURL: true,
+  },
+  access: authenticatedAccessOnly,
+  hooks: {
+    afterChange: [revalidateCache],
+  },
+  fields: [
+    {
+      name: 'title',
+      label: { fr: 'Titre', nl: 'Titel', en: 'Title' },
+      type: 'text',
+      required: true,
+      localized: true,
+    },
+    {
+      name: 'content',
+      label: { fr: 'Contenu', nl: 'Inhoud', en: 'Content' },
+      type: 'richText',
+      required: true,
+      localized: true,
+    },
+  ],
+};

package/src/globals/TermsOfUse/hooks/revalidate-cache.ts

@@ -0,0 +1,5 @@
+import { revalidatePath } from 'next/cache';
+
+export const revalidateCache = async () => {
+  revalidatePath('/', 'layout');
+};

package/src/globals/TermsOfUse/index.ts

@@ -0,0 +1,33 @@
+import type { GlobalConfig } from 'payload';
+
+import { revalidateCache } from './hooks/revalidate-cache';
+import { authenticatedAccessOnly } from '../../access/authenticatedAccessOnly';
+
+export const TermsOfUse: GlobalConfig = {
+  slug: 'terms-of-use',
+  label: { fr: "Conditions d'utilisation", nl: 'Gebruiksvoorwaarden', en: 'Terms of Use' },
+  admin: {
+    group: { fr: 'Légal', nl: 'Juridisch', en: 'Legal' },
+    hideAPIURL: true,
+  },
+  access: authenticatedAccessOnly,
+  hooks: {
+    afterChange: [revalidateCache],
+  },
+  fields: [
+    {
+      name: 'title',
+      label: { fr: 'Titre', nl: 'Titel', en: 'Title' },
+      type: 'text',
+      required: true,
+      localized: true,
+    },
+    {
+      name: 'content',
+      label: { fr: 'Contenu', nl: 'Inhoud', en: 'Content' },
+      type: 'richText',
+      required: true,
+      localized: true,
+    },
+  ],
+};

package/src/globals/index.ts

@@ -0,0 +1,2 @@
+export { PrivacyPolicy } from './PrivacyPolicy';
+export { TermsOfUse } from './TermsOfUse';

package/src/index.ts

@@ -0,0 +1,26 @@
+/**
+ * @latte-macchiat-io/latte-payload
+ *
+ * Reusable Payload CMS collections, utilities, and components for Latte projects
+ */
+
+// Collections
+export * from './collections';
+
+// Globals
+export * from './globals';
+
+// Access Control
+export * from './access';
+
+// Tasks
+export * from './tasks';
+
+// Utilities
+export * from './utils';
+
+// Components
+export * from './components';
+
+// Types
+export * from './types';

package/src/tasks/index.ts

@@ -0,0 +1,7 @@
+export {
+  processEmailQueueTaskConfig,
+  createProcessEmailQueueTask,
+  processEmailQueueName,
+  processEmailQueueAutoRunConfig,
+  type ProcessEmailQueueConfig,
+} from './process-email-queue';

package/src/tasks/process-email-queue.ts

@@ -0,0 +1,261 @@
+import { TZDate } from '@date-fns/tz';
+import { TaskConfig } from 'payload';
+import { toDatabaseTZDate } from '../utils';
+
+export const processEmailQueueName = 'process-email-queue';
+
+export const processEmailQueueAutoRunConfig = {
+  queue: processEmailQueueName,
+  cron: '* * * * *', // Every minute
+};
+
+// Utility function to add delay between emails to respect rate limits
+const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
+
+export interface ProcessEmailQueueConfig {
+  /**
+   * Timezone for email timestamps
+   * @default 'Europe/Brussels'
+   */
+  timezone?: string;
+
+  /**
+   * Maximum number of emails to process per run
+   * @default 100
+   */
+  maxEmailsPerRun?: number;
+
+  /**
+   * Delay between sending emails in milliseconds (for rate limiting)
+   * @default 1000 (1 second - respects Resend's 2 requests/second limit)
+   */
+  delayBetweenEmails?: number;
+
+  /**
+   * Default "from" email address
+   * Falls back to process.env.SMTP_FROM_ADDRESS
+   */
+  defaultFromAddress?: string;
+
+  /**
+   * Optional error reporter (e.g., Sentry)
+   */
+  errorReporter?: {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    captureException: (error: Error, context?: any) => void;
+  };
+}
+
+/**
+ * Create process-email-queue task with custom configuration
+ *
+ * @param config - Optional configuration
+ * @returns TaskConfig for process-email-queue
+ */
+export function createProcessEmailQueueTask(config?: ProcessEmailQueueConfig): TaskConfig<'process-email-queue'> {
+  const timezone = config?.timezone || 'Europe/Brussels';
+  const maxEmailsPerRun = config?.maxEmailsPerRun || 100;
+  const delayBetweenEmails = config?.delayBetweenEmails || 1000;
+
+  return {
+    slug: 'process-email-queue',
+    label: 'Process Email Queue',
+    retries: {
+      attempts: 3,
+      backoff: { delay: 2000, type: 'exponential' },
+    },
+    inputSchema: undefined, // No input - auto-triggered by cron
+    outputSchema: [
+      {
+        name: 'processedCount',
+        type: 'number',
+        required: true,
+      },
+      {
+        name: 'sentCount',
+        type: 'number',
+        required: true,
+      },
+      {
+        name: 'failedCount',
+        type: 'number',
+        required: true,
+      },
+    ],
+
+    // Auto-enqueue to run following the cron schedule
+    schedule: [
+      {
+        queue: processEmailQueueAutoRunConfig.queue,
+        cron: processEmailQueueAutoRunConfig.cron,
+      },
+    ],
+
+    handler: async ({ req }) => {
+      const { payload } = req;
+      payload.logger.info(`[(Task)ProcessEmailQueue] Task started`);
+
+      let processedCount = 0;
+      let sentCount = 0;
+      let failedCount = 0;
+
+      try {
+        // Find all emails that need to be sent (pending or failed with retries remaining)
+        // Note: We can't directly compare attemptCount < maxAttempts in the query,
+        // so we fetch all pending/failed emails and filter them in code
+        const allPendingOrFailed = await payload.find({
+          collection: 'queued-emails',
+          where: {
+            or: [
+              {
+                status: { equals: 'pending' },
+              },
+              {
+                status: { equals: 'failed' },
+              },
+            ],
+          },
+          sort: 'createdAt', // Process oldest emails first
+          limit: 200, // Fetch more to filter down to maxEmailsPerRun eligible
+          pagination: false,
+        });
+
+        // Filter emails that still have retries remaining
+        const emailsToSend = {
+          docs: allPendingOrFailed.docs.filter((email) => email.attemptCount < email.maxAttempts).slice(0, maxEmailsPerRun),
+        };
+
+        payload.logger.info(`[(Task)ProcessEmailQueue] Found ${emailsToSend.docs.length} emails to process`);
+
+        if (emailsToSend.docs.length === 0) {
+          return {
+            output: {
+              processedCount: 0,
+              sentCount: 0,
+              failedCount: 0,
+            },
+          };
+        }
+
+        // Process each email
+        for (const email of emailsToSend.docs) {
+          processedCount++;
+
+          try {
+            payload.logger.info(
+              `[(Task)ProcessEmailQueue] Processing email ${email.id} (${email.code}) to ${email.recipient} (attempt ${email.attemptCount + 1}/${email.maxAttempts})`
+            );
+
+            // Mark as sending to prevent duplicate processing
+            await payload.update({
+              collection: 'queued-emails',
+              id: email.id,
+              data: {
+                status: 'sending',
+                lastAttemptAt: toDatabaseTZDate(TZDate.tz(timezone)),
+              },
+            });
+
+            // Parse CC if it exists
+            const ccArray = email.cc ? email.cc.split(',').map((e: string) => e.trim()) : undefined;
+
+            const fromAddress = config?.defaultFromAddress || process.env.SMTP_FROM_ADDRESS;
+
+            // Send the email using Payload's email service
+            await payload.sendEmail({
+              from: fromAddress,
+              to: email.recipient,
+              cc: ccArray,
+              subject: email.subject,
+              html: email.htmlBody,
+            });
+
+            // Mark as sent
+            await payload.update({
+              collection: 'queued-emails',
+              id: email.id,
+              data: {
+                status: 'sent',
+                sentAt: toDatabaseTZDate(TZDate.tz(timezone)),
+                attemptCount: email.attemptCount + 1,
+                lastError: null,
+              },
+            });
+
+            sentCount++;
+            payload.logger.info(`[(Task)ProcessEmailQueue] Successfully sent email ${email.id} to ${email.recipient}`);
+
+            // Add delay between emails to respect rate limits
+            // Only delay if there are more emails to process
+            if (processedCount < emailsToSend.docs.length) {
+              await sleep(delayBetweenEmails);
+            }
+          } catch (error) {
+            failedCount++;
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            const now = toDatabaseTZDate(TZDate.tz(timezone));
+            const newAttemptCount = email.attemptCount + 1;
+
+            payload.logger.error(`[(Task)ProcessEmailQueue] Failed to send email ${email.id} to ${email.recipient}: ${errorMessage}`);
+
+            // Append to error history
+            const errorHistory = email.errorHistory || [];
+            errorHistory.push({
+              timestamp: now,
+              timestamp_tz: timezone,
+              attemptNumber: newAttemptCount,
+              error: errorMessage,
+            });
+
+            // Update email status to failed with error message
+            await payload.update({
+              collection: 'queued-emails',
+              id: email.id,
+              data: {
+                status: 'failed',
+                attemptCount: newAttemptCount,
+                lastError: errorMessage,
+                lastAttemptAt: now,
+                errorHistory: errorHistory,
+              },
+            });
+
+            // Report to error tracker if configured
+            if (config?.errorReporter && error instanceof Error) {
+              config.errorReporter.captureException(error, {
+                extra: {
+                  emailId: email.id,
+                  emailCode: email.code,
+                  recipient: email.recipient,
+                  attemptCount: newAttemptCount,
+                  maxAttempts: email.maxAttempts,
+                },
+              });
+            }
+          }
+        }
+
+        payload.logger.info(`[(Task)ProcessEmailQueue] Task completed - Processed: ${processedCount}, Sent: ${sentCount}, Failed: ${failedCount}`);
+
+        return {
+          output: {
+            processedCount,
+            sentCount,
+            failedCount,
+          },
+        };
+      } catch (error) {
+        payload.logger.error(`[(Task)ProcessEmailQueue] Critical error: ${error}`);
+        if (config?.errorReporter && error instanceof Error) {
+          config.errorReporter.captureException(error);
+        }
+        throw error;
+      }
+    },
+  };
+}
+
+/**
+ * Default process-email-queue task
+ */
+export const processEmailQueueTaskConfig = createProcessEmailQueueTask();