@latte-macchiat-io/latte-payload 1.0.1

package/src/types/index.ts

@@ -0,0 +1,15 @@
+/**
+ * Supported locales for the Latte Payload package
+ * Extend this type if you need additional locales
+ */
+export type Locale = 'en' | 'fr' | 'nl';
+
+/**
+ * Email template codes
+ */
+export type EmailTemplateCode = 'verify-email' | 'password-lost' | string;
+
+/**
+ * Queued email status
+ */
+export type QueuedEmailStatus = 'pending' | 'sending' | 'sent' | 'failed';

package/src/types/slug.ts

@@ -0,0 +1,11 @@
+import { slugField as payLoadSlugField } from 'payload';
+import { slugify } from '../utils/slugify';
+
+export const slugField = payLoadSlugField({
+  name: 'slug',
+  useAsSlug: 'name',
+  position: 'sidebar',
+  required: true,
+  localized: true,
+  slugify: ({ valueToSlugify, req }) => slugify(valueToSlugify, { locale: req.locale ?? undefined }),
+});

package/src/utils/database-dates.ts

@@ -0,0 +1,6 @@
+import { TZDate } from '@date-fns/tz';
+
+export function toDatabaseTZDate(date: TZDate | string): string {
+  if (typeof date === 'string') return date;
+  return date.toISOString();
+}

package/src/utils/email/generate-email-html.ts

@@ -0,0 +1,63 @@
+'use server';
+
+import { convertLexicalToHTML } from '@payloadcms/richtext-lexical/html';
+import { BasePayload } from 'payload';
+import fs from 'node:fs';
+import path from 'path';
+import { getEmailTemplateByCode } from './get-email-template';
+import { EmailTemplateCode, Locale } from '../../types';
+
+/**
+ * Generate email HTML from a template stored in the database
+ *
+ * @param payload - Payload instance
+ * @param emailCode - Email template code
+ * @param variables - Variables to replace in the template (e.g., { name: 'John', url: 'https://...' })
+ * @param locale - Locale for the email
+ * @param emailTemplateHtmlPath - Optional path to the HTML template file (default: './emails/template.html')
+ * @returns Object with subject and body HTML
+ */
+export async function generateEmailHtmlFromTemplate({
+  payload,
+  emailCode,
+  variables,
+  locale,
+  emailTemplateHtmlPath = './emails/template.html',
+}: {
+  payload: BasePayload;
+  emailCode: EmailTemplateCode;
+  variables: Record<string, string>;
+  locale: Locale;
+  emailTemplateHtmlPath?: string;
+}): Promise<{ subject: string; body: string } | undefined> {
+  const emailTemplate = fs.readFileSync(path.resolve(emailTemplateHtmlPath), 'utf8');
+
+  const templateContent = await getEmailTemplateByCode({
+    locale: locale,
+    code: emailCode,
+    payload: payload,
+  });
+
+  if (!templateContent) {
+    payload.logger.error(`Email template with code ${emailCode} not found`);
+    return;
+  }
+  const emailContentAsHtml = convertLexicalToHTML({ data: templateContent.body });
+
+  // Replace {{variable}} by the actual value
+  const emailContent = emailContentAsHtml.replaceAll(/{{\s*([^}]+)\s*}}/g, (_match, p1) => variables[p1]);
+
+  // Quick fix to replace clickable links {escapeHTML(node.url)} with the variable url value
+  // This is a workaround until we have a better solution to handle links in emails
+  // TODO check if still needed after Payload CMS Rich Text Editor improvements
+  const emailContentWithLinks = emailContent.replace(/href={escapeHTML\(node\.(\w+)\)}/g, (_match, p1) => `href="${variables[p1]}"`);
+
+  const finalEmailBody = emailTemplate
+    .replaceAll('{{ emailContent }}', emailContentWithLinks)
+    .replaceAll('{{ emailSubject }}', templateContent.subject);
+
+  return {
+    subject: templateContent.subject,
+    body: finalEmailBody,
+  };
+}

package/src/utils/email/get-email-template.ts

@@ -0,0 +1,18 @@
+import { BasePayload } from 'payload';
+import { Locale } from '../../types';
+
+export async function getEmailTemplateByCode({ locale, code, payload }: { locale: Locale; code: string; payload: BasePayload }) {
+  const emailContentTemplateDocs = await payload.find({
+    collection: 'email-templates',
+    where: { code: { equals: code } },
+    limit: 1,
+    locale: locale,
+  });
+
+  if (!emailContentTemplateDocs || emailContentTemplateDocs.totalDocs === 0) {
+    payload.logger.error(`Email template with code ${code} not found`);
+    return null;
+  }
+
+  return emailContentTemplateDocs.docs[0];
+}

package/src/utils/email/index.ts

@@ -0,0 +1,3 @@
+export { getEmailTemplateByCode } from './get-email-template';
+export { generateEmailHtmlFromTemplate } from './generate-email-html';
+export { queueEmail } from './queue-email';

package/src/utils/email/queue-email.ts

@@ -0,0 +1,109 @@
+'use server';
+
+import { BasePayload } from 'payload';
+import { generateEmailHtmlFromTemplate } from './generate-email-html';
+import { EmailTemplateCode, Locale } from '../../types';
+
+/**
+ * Queue an email to be sent by the email processor job.
+ * This function generates the email HTML from template and stores it in the queued-emails collection.
+ * The email will be picked up and sent by the process-email-queue job.
+ *
+ * @param payload - Payload instance
+ * @param to - Recipient email address
+ * @param cc - Optional CC email addresses
+ * @param emailCode - Email template code (e.g., 'verify-email', 'password-lost')
+ * @param variables - Variables to replace in the template
+ * @param locale - Locale for the email
+ * @param maxAttempts - Maximum number of retry attempts (default: 5)
+ * @param idempotencyKey - Optional unique key to prevent duplicate emails (e.g., "order-confirmation-123")
+ * @param emailTemplateHtmlPath - Optional path to the HTML template file (default: './emails/template.html')
+ */
+export async function queueEmail({
+  payload,
+  to,
+  cc,
+  emailCode,
+  variables,
+  locale,
+  maxAttempts = 5,
+  idempotencyKey,
+  emailTemplateHtmlPath,
+}: {
+  payload: BasePayload;
+  to: string;
+  cc?: string[];
+  emailCode: EmailTemplateCode;
+  variables: Record<string, string>;
+  locale: Locale;
+  maxAttempts?: number;
+  idempotencyKey?: string;
+  emailTemplateHtmlPath?: string;
+}) {
+  try {
+    // Check for existing email with the same idempotency key (if provided)
+    if (idempotencyKey) {
+      const existingEmails = await payload.find({
+        collection: 'queued-emails',
+        where: {
+          idempotencyKey: { equals: idempotencyKey },
+        },
+        limit: 1,
+      });
+
+      if (existingEmails.docs.length > 0) {
+        const existingEmail = existingEmails.docs[0];
+        // If email is pending, sending, or sent, skip creating a duplicate
+        if (existingEmail.status === 'pending' || existingEmail.status === 'sending' || existingEmail.status === 'sent') {
+          payload.logger.info(
+            `Email ${emailCode} with idempotency key "${idempotencyKey}" already exists (status: ${existingEmail.status}). Skipping duplicate.`
+          );
+          return;
+        }
+        // If email failed, we'll allow retry by creating a new one (old one stays for debugging)
+        payload.logger.info(`Email ${emailCode} with idempotency key "${idempotencyKey}" previously failed. Creating new attempt.`);
+      }
+    }
+
+    // Generate the email content from template
+    const emailContent = await generateEmailHtmlFromTemplate({
+      emailCode: emailCode,
+      locale: locale,
+      payload: payload,
+      variables: variables,
+      emailTemplateHtmlPath,
+    });
+
+    if (!emailContent) {
+      const error = `Email template with code ${emailCode} not found`;
+      payload.logger.error(error);
+      throw new Error(error);
+    }
+
+    payload.logger.info(`Queueing email ${emailCode} to ${to} with subject "${emailContent.subject}"`);
+
+    // Create a record in the queued-emails collection
+    await payload.create({
+      collection: 'queued-emails',
+      data: {
+        idempotencyKey: idempotencyKey || null,
+        status: 'pending',
+        code: emailCode,
+        recipient: to,
+        cc: cc?.join(', '),
+        subject: emailContent.subject,
+        htmlBody: emailContent.body,
+        attemptCount: 0,
+        maxAttempts: maxAttempts,
+        lastAttemptAt: null,
+        sentAt: null,
+        lastError: null,
+      },
+    });
+
+    payload.logger.info(`Email ${emailCode} queued successfully for ${to}`);
+  } catch (error) {
+    payload.logger.error(`Error queueing email ${emailCode} to ${to}: ${error}`);
+    throw error;
+  }
+}

package/src/utils/get-global.ts

@@ -0,0 +1,25 @@
+'use server';
+
+import { unstable_cache } from 'next/cache';
+import type { Config, GlobalSlug } from 'payload';
+import { getPayloadClient } from './payload-client';
+
+async function getGlobal<TSlug extends GlobalSlug>(slug: TSlug, config: Promise<Config> | Config, depth = 0): Promise<unknown> {
+  const payload = await getPayloadClient(config);
+
+  return payload.findGlobal({
+    slug,
+    depth,
+  });
+}
+
+/**
+ * Strongly typed cached global fetcher
+ */
+export async function getCachedGlobal<TSlug extends GlobalSlug>(slug: TSlug, config: Promise<Config> | Config, depth = 0): Promise<unknown> {
+  const cachedFn = unstable_cache(() => getGlobal(slug, config, depth), [slug], {
+    tags: [`global_${slug}`],
+  }) as () => Promise<unknown>;
+
+  return cachedFn();
+}

package/src/utils/id-from-payload.ts

@@ -0,0 +1,11 @@
+export function getId(idOrObject: number | { id: number }): number {
+  if (typeof idOrObject === 'number') {
+    return idOrObject;
+  }
+
+  if (typeof idOrObject === 'object' && idOrObject !== null) {
+    return idOrObject.id;
+  }
+
+  throw new Error('Invalid ID or object');
+}

package/src/utils/index.ts

@@ -0,0 +1,3 @@
+export * from './email';
+export { toDatabaseTZDate } from './database-dates';
+export { getPayloadClient } from './payload-client';

package/src/utils/migrations.ts

@@ -0,0 +1,18 @@
+export const toRichText = (text: string | null) =>
+  text
+    ? JSON.stringify({
+        root: {
+          type: 'root',
+          children: [
+            {
+              type: 'paragraph',
+              children: [
+                {
+                  text,
+                },
+              ],
+            },
+          ],
+        },
+      })
+    : null;

package/src/utils/payload-client.ts

@@ -0,0 +1,16 @@
+'use server';
+
+import { getPayload } from 'payload';
+import type { Config } from 'payload';
+
+/**
+ * Get Payload client instance
+ * This is a wrapper around Payload's getPayload function
+ *
+ * @param config - Your Payload configuration object
+ * @returns Payload client instance
+ */
+export async function getPayloadClient(config: Promise<Config> | Config) {
+  // @ts-expect-error - getPayload accepts Config but types show SanitizedConfig
+  return getPayload({ config });
+}

package/src/utils/slugify.ts

@@ -0,0 +1,21 @@
+import slugifyPlugin from 'slugify';
+
+// Custom slugify utility with configurable options
+// Default options: trimming, lowercase conversion, and removal of special characters
+export const slugify = (
+  val: string = '', // Default to empty string if no value is provided
+  options: {
+    trim?: boolean;
+    locale?: string;
+    lower?: boolean;
+    remove?: RegExp; // Allow custom removal of special characters
+  } = { trim: true, lower: true } // Default options
+) => {
+  return slugifyPlugin(val, {
+    trim: options.trim ?? true, // Always trim leading/trailing spaces, fallback to true
+    lower: options.lower ?? true, // Always convert to lowercase, fallback to true
+    locale: options.locale ?? undefined, // Optional locale parameter
+    remove: /[*+~.()'"!:@¿¡©®—`^?;,<>/&|=#%$§]/g, // Default regex now includes "?"
+    ...options, // Merge provided options with defaults
+  });
+};

package/tests/fixtures/email-template.html

@@ -0,0 +1,58 @@
+<!DOCTYPE html>
+<html lang="{{locale}}">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>{{subject}}</title>
+  <style>
+    body {
+      font-family: Arial, sans-serif;
+      line-height: 1.6;
+      color: #333;
+      max-width: 600px;
+      margin: 0 auto;
+      padding: 20px;
+    }
+    .header {
+      background-color: #f4f4f4;
+      padding: 20px;
+      text-align: center;
+    }
+    .content {
+      padding: 20px;
+    }
+    .footer {
+      background-color: #f4f4f4;
+      padding: 10px;
+      text-align: center;
+      font-size: 12px;
+      color: #666;
+    }
+    .button {
+      display: inline-block;
+      padding: 10px 20px;
+      background-color: #007bff;
+      color: #ffffff;
+      text-decoration: none;
+      border-radius: 5px;
+    }
+  </style>
+</head>
+<body>
+  <div class="header">
+    <h1>Test Email Template</h1>
+  </div>
+  <div class="content">
+    <p>Hello {{name}},</p>
+    <p>{{message}}</p>
+    {{#if actionUrl}}
+    <p>
+      <a href="{{actionUrl}}" class="button">{{actionText}}</a>
+    </p>
+    {{/if}}
+  </div>
+  <div class="footer">
+    <p>&copy; {{year}} Latte Macchiat.io. All rights reserved.</p>
+  </div>
+</body>
+</html>

package/tests/fixtures/sample-data.ts

@@ -0,0 +1,56 @@
+import type { Locale } from '../../src/types';
+
+export const sampleUsers = [
+  {
+    email: 'user1@example.com',
+    password: 'password123',
+    roles: ['user'],
+    name: 'User One',
+    locale: 'en' as Locale,
+  },
+  {
+    email: 'user2@example.com',
+    password: 'password123',
+    roles: ['user'],
+    name: 'User Two',
+    locale: 'fr' as Locale,
+  },
+  {
+    email: 'admin@example.com',
+    password: 'admin123',
+    roles: ['admin', 'user'],
+    name: 'Admin User',
+    locale: 'en' as Locale,
+  },
+];
+
+export const sampleEmailTemplates = [
+  {
+    code: 'welcome',
+    subject: {
+      en: 'Welcome to our platform!',
+      fr: 'Bienvenue sur notre plateforme!',
+      nl: 'Welkom op ons platform!',
+    },
+    html: '<h1>Welcome {{name}}!</h1><p>Thank you for joining us.</p>',
+  },
+  {
+    code: 'test-template',
+    subject: {
+      en: 'Test Email',
+      fr: 'Email de test',
+      nl: 'Test email',
+    },
+    html: '<p>This is a test email for {{name}}</p>',
+  },
+];
+
+export const sampleQueuedEmail = {
+  recipient: 'test@example.com',
+  subject: 'Test Email Subject',
+  htmlContent: '<p>Test email content</p>',
+  status: 'pending' as const,
+  locale: 'en' as Locale,
+  idempotencyKey: 'test-idempotency-key-123',
+  retries: 0,
+};

package/tests/helpers/create-test-user.ts

@@ -0,0 +1,37 @@
+import type { Payload } from 'payload';
+
+export interface CreateTestUserParams {
+  email?: string;
+  password?: string;
+  roles?: string[];
+  name?: string;
+}
+
+/**
+ * Helper to create a test user
+ */
+export async function createTestUser(payload: Payload, params: CreateTestUserParams = {}): Promise<any> {
+  const { email = 'test@example.com', password = 'password123', roles = ['user'], name = 'Test User' } = params;
+
+  return await payload.create({
+    collection: 'users',
+    data: {
+      email,
+      password,
+      roles,
+      name,
+    },
+  });
+}
+
+/**
+ * Helper to create an admin test user
+ */
+export async function createTestAdmin(payload: Payload): Promise<any> {
+  return await createTestUser(payload, {
+    email: 'admin@example.com',
+    password: 'admin123',
+    roles: ['admin'],
+    name: 'Admin User',
+  });
+}

package/tests/helpers/init-payload.ts

@@ -0,0 +1,59 @@
+import { sqliteAdapter } from '@payloadcms/db-sqlite';
+import { lexicalEditor } from '@payloadcms/richtext-lexical';
+import { Config, getPayload, type Payload } from 'payload';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+import { createEmailTemplatesCollection } from '../../src/collections/EmailTemplates/index.js';
+import { createQueuedEmailsCollection } from '../../src/collections/QueuedEmails/index.js';
+import { createUsersCollection } from '../../src/collections/Users/index.js';
+
+const filename = fileURLToPath(import.meta.url);
+const dirname = path.dirname(filename);
+
+let cachedPayload: Payload | null = null;
+
+/**
+ * Initialize Payload with SQLite for integration tests
+ * Follows PayloadCMS testing pattern
+ */
+export async function initPayloadInt(): Promise<Payload> {
+  // Return cached instance if available
+  if (cachedPayload) {
+    return cachedPayload;
+  }
+
+  // Minimal test configuration
+  const config: Config = {
+    secret: process.env.PAYLOAD_SECRET || 'test-secret-key',
+    db: sqliteAdapter({
+      client: {
+        url: process.env.DATABASE_URI || ':memory:',
+      },
+    }),
+    editor: lexicalEditor(),
+    collections: [createUsersCollection(), createEmailTemplatesCollection(), createQueuedEmailsCollection()],
+    globals: [],
+    typescript: {
+      outputFile: path.resolve(dirname, '../payload-types.ts'),
+    },
+    onInit: async (payload) => {
+      payload.logger.info('Payload initialized for testing');
+    },
+  };
+
+  const payload = await getPayload({ config });
+
+  cachedPayload = payload;
+  return payload;
+}
+
+/**
+ * Cleanup Payload instance
+ */
+export async function cleanupPayload(): Promise<void> {
+  if (cachedPayload?.db?.destroy) {
+    await cachedPayload.db.destroy();
+  }
+  cachedPayload = null;
+}

package/tests/setup.integration.ts

@@ -0,0 +1,9 @@
+import { config } from 'dotenv';
+
+// Load test environment variables
+config({ path: '.env.test' });
+
+// Set test-specific environment variables
+process.env.PAYLOAD_DROP_DATABASE = 'true';
+process.env.PAYLOAD_DISABLE_ADMIN = 'true';
+process.env.NODE_ENV = 'test';

package/tests/setup.ts

@@ -0,0 +1,4 @@
+import { expect } from 'vitest';
+
+// Export vitest globals for test files
+export { expect };

package/tests/unit/access/adminAccessOnly.spec.ts

@@ -0,0 +1,117 @@
+import { describe, expect, it } from 'vitest';
+import { adminAccessOnly } from '@/access/adminAccessOnly';
+
+describe('adminAccessOnly access control', () => {
+  describe('admin property', () => {
+    it('should return true for users with admin role', () => {
+      const req = { user: { roles: ['admin'] } } as any;
+      expect(adminAccessOnly.admin({ req })).toBe(true);
+    });
+
+    it('should return false for users without admin role', () => {
+      const req = { user: { roles: ['user'] } } as any;
+      expect(adminAccessOnly.admin({ req })).toBe(false);
+    });
+
+    it('should return false for unauthenticated users', () => {
+      const req = { user: null } as any;
+      expect(adminAccessOnly.admin({ req })).toBe(false);
+    });
+  });
+
+  describe('create property', () => {
+    it('should return true for admin users', () => {
+      const req = { user: { roles: ['admin'] } } as any;
+      expect(adminAccessOnly.create({ req })).toBe(true);
+    });
+
+    it('should return false for non-admin users', () => {
+      const req = { user: { roles: ['user'] } } as any;
+      expect(adminAccessOnly.create({ req })).toBe(false);
+    });
+  });
+
+  describe('read property', () => {
+    it('should return true for admin users', () => {
+      const req = { user: { roles: ['admin'] } } as any;
+      expect(adminAccessOnly.read({ req })).toBe(true);
+    });
+
+    it('should return false for non-admin users', () => {
+      const req = { user: { roles: ['user'] } } as any;
+      expect(adminAccessOnly.read({ req })).toBe(false);
+    });
+  });
+
+  describe('update property', () => {
+    it('should return true for admin users', () => {
+      const req = { user: { roles: ['admin'] } } as any;
+      expect(adminAccessOnly.update({ req })).toBe(true);
+    });
+
+    it('should return false for non-admin users', () => {
+      const req = { user: { roles: ['user'] } } as any;
+      expect(adminAccessOnly.update({ req })).toBe(false);
+    });
+  });
+
+  describe('delete property', () => {
+    it('should return true for admin users', () => {
+      const req = { user: { roles: ['admin'] } } as any;
+      expect(adminAccessOnly.delete({ req })).toBe(true);
+    });
+
+    it('should return false for non-admin users', () => {
+      const req = { user: { roles: ['user'] } } as any;
+      expect(adminAccessOnly.delete({ req })).toBe(false);
+    });
+  });
+
+  describe('readVersions property', () => {
+    it('should return true for admin users', () => {
+      const req = { user: { roles: ['admin'] } } as any;
+      expect(adminAccessOnly.readVersions({ req })).toBe(true);
+    });
+
+    it('should return false for non-admin users', () => {
+      const req = { user: { roles: ['user'] } } as any;
+      expect(adminAccessOnly.readVersions({ req })).toBe(false);
+    });
+  });
+
+  describe('unlock property', () => {
+    it('should return true for admin users', () => {
+      const req = { user: { roles: ['admin'] } } as any;
+      expect(adminAccessOnly.unlock({ req })).toBe(true);
+    });
+
+    it('should return false for non-admin users', () => {
+      const req = { user: { roles: ['user'] } } as any;
+      expect(adminAccessOnly.unlock({ req })).toBe(false);
+    });
+  });
+
+  describe('all properties with unauthenticated user', () => {
+    const req = { user: null } as any;
+
+    it('should return false for admin', () => {
+      expect(adminAccessOnly.admin({ req })).toBe(false);
+    });
+
+    it('should return false for create', () => {
+      expect(adminAccessOnly.create({ req })).toBe(false);
+    });
+
+    it('should return false for read', () => {
+      expect(adminAccessOnly.read({ req })).toBe(false);
+    });
+
+    it('should return false for update', () => {
+      expect(adminAccessOnly.update({ req })).toBe(false);
+    });
+
+    it('should return false for delete', () => {
+      expect(adminAccessOnly.delete({ req })).toBe(false);
+    });
+  });
+});