@latte-macchiat-io/latte-payload 1.0.1

package/.claude/settings.local.json

@@ -0,0 +1,9 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(npx tsc:*)",
+      "Bash(pnpm test:unit:*)",
+      "Bash(pnpm test:coverage:*)"
+    ]
+  }
+}

package/.env.example

@@ -0,0 +1,29 @@
+# Database
+DATABASE_URI=postgresql://user:password@localhost:5432/dbname
+
+# Payload
+PAYLOAD_SECRET=your-secret-key-here
+
+# Email Configuration
+ENABLE_EMAILS_SENDING=true
+
+# Production Email (Resend)
+RESEND_API_KEY=re_your_api_key_here
+
+# Development Email (Nodemailer + Mailpit)
+SMTP_HOST=localhost
+SMTP_PORT=1025
+SMTP_USER=
+SMTP_PASS=
+SMTP_FROM_ADDRESS=noreply@yourdomain.com
+
+# Contact Form
+EMAIL_DEFAULT_CONTACT_ADDRESS=contact@yourdomain.com
+
+# S3 Storage (optional)
+S3_ENDPOINT=https://s3.amazonaws.com
+S3_REGION=us-east-1
+S3_ACCESS_KEY_ID=your_access_key
+S3_SECRET_ACCESS_KEY=your_secret_key
+S3_BUCKET=your-bucket-name
+S3_FORCE_PATH_STYLE=false

package/.github/workflows/ci.yml

@@ -0,0 +1,160 @@
+name: CI - Pull Request Validation
+
+on:
+  pull_request:
+    branches:
+      - main
+    paths:
+      - 'src/**'
+      - 'tests/**'
+      - 'package.json'
+      - 'pnpm-lock.yaml'
+      - 'tsconfig.json'
+      - 'vitest.config.ts'
+      - 'vitest.integration.config.ts'
+      - '.github/workflows/ci.yml'
+
+permissions:
+  contents: read
+  pull-requests: write # For posting coverage comments
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '24'
+          cache: 'pnpm'
+
+      - name: Install Dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Run ESLint
+        run: pnpm lint
+
+      - name: Run Prettier Check
+        run: pnpm prettier
+
+  test:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '24'
+          cache: 'pnpm'
+
+      - name: Install Dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Run Unit Tests
+        run: pnpm test:unit
+
+      - name: Generate Coverage Report
+        run: pnpm test:coverage
+
+      - name: Upload Coverage Reports
+        uses: codecov/codecov-action@v4
+        if: always()
+        with:
+          files: ./coverage/lcov.info
+          fail_ci_if_error: false
+          token: ${{ secrets.CODECOV_TOKEN }}
+
+      - name: Comment Coverage on PR
+        if: github.event_name == 'pull_request'
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const fs = require('fs');
+
+            // Read coverage summary
+            let coverageSummary;
+            try {
+              coverageSummary = JSON.parse(fs.readFileSync('./coverage/coverage-summary.json', 'utf8'));
+            } catch (error) {
+              console.log('No coverage summary found');
+              return;
+            }
+
+            const { lines, statements, functions, branches } = coverageSummary.total;
+
+            const comment = `## 📊 Test Coverage Report
+
+            | Metric | Coverage | Status |
+            |--------|----------|--------|
+            | Lines | ${lines.pct.toFixed(2)}% | ${lines.pct >= 60 ? '✅' : '⚠️'} |
+            | Statements | ${statements.pct.toFixed(2)}% | ${statements.pct >= 60 ? '✅' : '⚠️'} |
+            | Functions | ${functions.pct.toFixed(2)}% | ${functions.pct >= 60 ? '✅' : '⚠️'} |
+            | Branches | ${branches.pct.toFixed(2)}% | ${branches.pct >= 60 ? '✅' : '⚠️'} |
+
+            **Target:** 60% minimum on all metrics
+
+            <details>
+            <summary>View detailed coverage</summary>
+
+            \`\`\`
+            Lines:      ${lines.covered}/${lines.total}
+            Statements: ${statements.covered}/${statements.total}
+            Functions:  ${functions.covered}/${functions.total}
+            Branches:   ${branches.covered}/${branches.total}
+            \`\`\`
+            </details>
+            `;
+
+            github.rest.issues.createComment({
+              issue_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              body: comment
+            });
+
+  build:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '24'
+          cache: 'pnpm'
+
+      - name: Install Dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build TypeScript
+        run: pnpm build
+
+      - name: Verify Build Output
+        run: |
+          echo "Checking dist/ directory..."
+          ls -la dist/
+          echo "Verifying .d.ts files exist..."
+          find dist -name "*.d.ts" | wc -l
+          echo "Verifying .js files exist..."
+          find dist -name "*.js" | wc -l

package/.github/workflows/publish.yml

@@ -0,0 +1,126 @@
+name: Publish Components
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'src/**' # Trigger on any source file changes
+      - 'package.json' # Trigger on package.json changes
+      - 'pnpm-lock.yaml' # Trigger on lockfile changes
+      - '.github/workflows/publish.yml' # Trigger on workflow changes
+
+permissions:
+  contents: write # Write is required to tag the release
+  packages: write
+  attestations: write
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    timeout-minutes: 3
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # Important for version calculation
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          # version: 9 # Version is taken from package.json
+          run_install: false
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: '24'
+          registry-url: 'https://registry.npmjs.org'
+          always-auth: 'true'
+          cache: 'pnpm'
+
+      - name: Upgrade npm for OIDC support (pnpm uses npm internally)
+        run: npm install -g npm@latest
+        # pnpm publish uses npm's registry client - npm 11.5.1+ required for OIDC trusted publishing
+
+      - name: Install Dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Run Linting
+        run: pnpm lint
+
+      - name: Run Unit Tests
+        run: pnpm test:unit
+
+      - name: Build Package
+        run: pnpm build
+
+      - name: Get previous version
+        id: prev_version
+        run: |
+          PREV_VERSION=$(pnpm pkg get version | tr -d '"')
+          echo "prev_version=$PREV_VERSION" >> $GITHUB_OUTPUT
+
+      - name: Calculate new version
+        id: version
+        run: |
+          # Get last tag
+          LAST_TAG=$(git describe --tags --abbrev=0)
+          
+          # Check for changes in the same paths that trigger the workflow
+          CHANGES=$(git diff --name-only $LAST_TAG HEAD | grep -E '^(src/|package.json|pnpm-lock.yaml|.github/workflows/publish.yml)' || true)
+          
+          # Read current version
+          CURRENT_VERSION=${{ steps.prev_version.outputs.prev_version }}
+          
+          # Split version into parts
+          IFS='.' read -r MAJOR MINOR PATCH <<< "$CURRENT_VERSION"
+          
+          if [ -n "$CHANGES" ]; then
+            echo "Detected changes in relevant paths:"
+            echo "$CHANGES"
+            NEW_VERSION="$MAJOR.$MINOR.$((PATCH + 1))"
+          else
+            echo "No relevant changes detected since last tag."
+            NEW_VERSION="$CURRENT_VERSION"
+          fi
+          
+          echo "new_version=$NEW_VERSION" >> $GITHUB_OUTPUT
+
+      - name: Update version in package.json
+        if: steps.version.outputs.new_version != steps.prev_version.outputs.prev_version
+        run: pnpm version ${{ steps.version.outputs.new_version }} --no-git-tag-version
+
+      - name: Verify package contents
+        run: |
+          echo "Verifying source files will be published..."
+          echo "Files that will be included in the package:"
+          npm pack --dry-run
+          echo ""
+          echo "Source TypeScript files found:"
+          find src -name "*.ts" | wc -l
+          echo "Source CSS.TS files found:"
+          find src -name "*.css.ts" | wc -l
+
+      - name: Commit package.json changes
+        if: steps.version.outputs.new_version != steps.prev_version.outputs.prev_version
+        run: |
+          git config --local user.email "github-actions[bot]@users.noreply.github.com"
+          git config --local user.name "github-actions[bot]"
+          git add package.json
+          git commit -m "chore: bump version to v${{ steps.version.outputs.new_version }}"
+          git push
+
+      - name: Publish to npm (Trusted Publisher)
+        if: steps.version.outputs.new_version != steps.prev_version.outputs.prev_version
+        run: pnpm publish --access public --no-git-checks # no-git-checks required -> https://github.com/pnpm/pnpm/issues/5894
+        # Using OIDC Trusted Publishing - configured on npmjs.com
+        # No token needed! Authentication via id-token: write permission
+        # Note: --provenance flag removed because GitHub repo is private (provenance requires public repos)
+
+      - name: Create Git tag
+        if: steps.version.outputs.new_version != steps.prev_version.outputs.prev_version
+        run: |
+          git config --local user.email "github-actions[bot]@users.noreply.github.com"
+          git config --local user.name "github-actions[bot]"
+          git tag -a v${{ steps.version.outputs.new_version }} -m "Release v${{ steps.version.outputs.new_version }}"
+          git push origin v${{ steps.version.outputs.new_version }}

package/.nvmrc

@@ -0,0 +1 @@
+24

package/.prettierignore

@@ -0,0 +1,2 @@
+.next
+node_modules

package/.prettierrc

@@ -0,0 +1,11 @@
+{
+  "singleQuote": true,
+  "arrowParens": "always",
+  "trailingComma": "es5",
+  "printWidth": 150,
+  "tabWidth": 2,
+  "bracketSpacing": true,
+  "bracketSameLine": true,
+  "endOfLine": "lf",
+  "semi": true
+}

package/CHANGELOG.md

@@ -0,0 +1,87 @@
+# 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).
+
+## [Unreleased]
+
+### Added
+- Comprehensive test suite with 189 unit tests
+- Test coverage for access control functions (100% coverage)
+- Test coverage for utility functions (100% coverage)
+- Test coverage for form validators (100% coverage)
+- Vitest testing framework with unit and integration test configurations
+- GitHub Actions CI workflow for PR validation
+- Test coverage reporting in PRs
+- TypeDoc API documentation generation
+- Enhanced JSDoc comments for better code documentation
+
+### Changed
+- Enhanced publish workflow to run tests before publishing
+- Updated .gitignore to exclude test and documentation artifacts
+
+### Fixed
+- None
+
+## [1.0.0] - 2024-12-26
+
+### Added
+- Initial release
+- **Collections:**
+  - Users collection with authentication and email verification
+  - Media collection with S3 storage support
+  - ContactMessages collection for contact form submissions
+  - EmailTemplates collection for managing email templates
+  - QueuedEmails collection with retry logic and status tracking
+- **Globals:**
+  - PrivacyPolicy global configuration
+  - TermsOfUse global configuration
+- **Access Control:**
+  - `admins` - Admin-only access control
+  - `authenticated` - Authenticated user access control
+  - `anyone` - Public access control
+  - `adminAccessOnly` - Full admin-only access object
+  - `authenticatedAccessOnly` - Full authenticated access object
+  - `publicReadAuthenticatedAccess` - Public read with authenticated write
+- **Utilities:**
+  - Email queueing system with `queueEmail` utility
+  - Email HTML generation from templates
+  - Email template retrieval utilities
+  - Database date conversion utilities
+  - Slugify utility for URL-safe strings
+  - ID extraction from PayloadCMS responses
+- **Tasks:**
+  - `process-email-queue` background task for async email processing
+  - Exponential backoff retry logic for failed emails
+- **Components:**
+  - HtmlViewer component for admin UI
+  - RetryEmailButtons component for manual email retry
+- **Forms:**
+  - Form validators: requiredString, requiredEmailString, requiredPasswordString
+  - Honeypot validator for bot detection
+  - Required checkbox validator
+  - Error translation utilities
+  - US states data
+- **TypeScript:**
+  - Full TypeScript support with strict mode
+  - Type exports for all collections, globals, and utilities
+  - Locale types (en, fr, nl)
+  - Email template code types
+- **Documentation:**
+  - Comprehensive README with usage examples
+  - Installation and setup instructions
+  - Environment variables documentation
+  - Type exports documentation
+
+### Technical Details
+- Built with PayloadCMS 3.64.0
+- Supports React 19 and Next.js 15
+- Node.js 22+ required
+- pnpm 10 package manager
+- ESLint and Prettier configured
+- Automated NPM publishing with OIDC
+
+[Unreleased]: https://github.com/latte-macchiat-io/latte-payload/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/latte-macchiat-io/latte-payload/releases/tag/v1.0.0