@bernierllc/email 1.0.0

package/.eslintrc.json

@@ -0,0 +1,112 @@
+//
+// Copyright (c) 2025 Bernier LLC
+//
+// This file is licensed to the client under a limited-use license.
+// The client may use and modify this code *only within the scope of the project it was delivered for*.
+// Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
+//
+{
+  "extends": [
+    "plugin:react/recommended",
+    "plugin:react-hooks/recommended",
+    "plugin:jsx-a11y/recommended",
+    "plugin:@typescript-eslint/recommended"
+  ],
+  "plugins": [
+    "react",
+    "react-hooks",
+    "jsx-a11y",
+    "@typescript-eslint"
+  ],
+  "rules": {
+    "no-object-rendering": "error",
+    "react/jsx-no-undef": "error",
+    "react/jsx-uses-react": "error",
+    "react/jsx-uses-vars": "error",
+    "react/no-unescaped-entities": "error",
+    "react/no-unknown-property": "error",
+    "react/self-closing-comp": "error",
+    "react/jsx-key": "error",
+    "react/jsx-no-duplicate-props": "error",
+    "react/jsx-no-target-blank": "error",
+    "react/jsx-pascal-case": "error",
+    "react/jsx-wrap-multilines": "error",
+    "react/jsx-curly-brace-presence": ["error", { "props": "never", "children": "never" }],
+    "@typescript-eslint/no-unused-vars": "error",
+    "@typescript-eslint/no-explicit-any": "warn",
+    "@typescript-eslint/explicit-function-return-type": "off",
+    "@typescript-eslint/explicit-module-boundary-types": "off",
+    "@typescript-eslint/no-non-null-assertion": "warn",
+    "react-hooks/rules-of-hooks": "error",
+    "react-hooks/exhaustive-deps": "warn",
+    "jsx-a11y/alt-text": "error",
+    "jsx-a11y/anchor-has-content": "error",
+    "jsx-a11y/anchor-is-valid": "error",
+    "jsx-a11y/aria-props": "error",
+    "jsx-a11y/aria-proptypes": "error",
+    "jsx-a11y/aria-unsupported-elements": "error",
+    "jsx-a11y/heading-has-content": "error",
+    "jsx-a11y/iframe-has-title": "error",
+    "jsx-a11y/img-redundant-alt": "error",
+    "jsx-a11y/no-access-key": "error",
+    "jsx-a11y/no-distracting-elements": "error",
+    "jsx-a11y/no-redundant-roles": "error",
+    "jsx-a11y/role-has-required-aria-props": "error",
+    "jsx-a11y/role-supports-aria-props": "error",
+    "jsx-a11y/scope": "error",
+    "jsx-a11y/label-has-associated-control": "error",
+    "jsx-a11y/control-has-associated-label": "error",
+    "jsx-a11y/click-events-have-key-events": "error",
+    "jsx-a11y/no-static-element-interactions": "error",
+    "jsx-a11y/interactive-supports-focus": "error",
+    "jsx-a11y/no-noninteractive-element-interactions": "error",
+    "jsx-a11y/no-noninteractive-tabindex": "error",
+    "jsx-a11y/tabindex-no-positive": "error",
+    "jsx-a11y/no-noninteractive-element-to-interactive-role": "error",
+    "jsx-a11y/media-has-caption": "error",
+    "jsx-a11y/no-autofocus": "error",
+    "no-console": "warn",
+    "no-debugger": "error",
+    "no-unused-vars": "off",
+    "prefer-const": "error",
+    "no-var": "error"
+  },
+  "settings": {
+    "react": {
+      "version": "detect"
+    }
+  },
+  "overrides": [
+    {
+      "files": ["**/*.ts", "**/*.tsx"],
+      "rules": {
+        "@typescript-eslint/no-unused-vars": ["error", { "argsIgnorePattern": "^_" }],
+        "@typescript-eslint/explicit-function-return-type": "off"
+      }
+    },
+    {
+      "files": ["**/forms/**/*.tsx", "**/*Form*.tsx", "**/*form*.tsx"],
+      "rules": {
+        "jsx-a11y/label-has-associated-control": "error",
+        "jsx-a11y/control-has-associated-label": "error",
+        "jsx-a11y/no-autofocus": "error"
+      }
+    },
+    {
+      "files": ["**/navigation/**/*.tsx", "**/*Nav*.tsx", "**/*nav*.tsx"],
+      "rules": {
+        "jsx-a11y/click-events-have-key-events": "error",
+        "jsx-a11y/no-static-element-interactions": "error",
+        "jsx-a11y/interactive-supports-focus": "error"
+      }
+    },
+    {
+      "files": ["**/modal/**/*.tsx", "**/*Modal*.tsx", "**/*modal*.tsx", "**/*Dialog*.tsx", "**/*dialog*.tsx"],
+      "rules": {
+        "jsx-a11y/no-autofocus": "error",
+        "jsx-a11y/click-events-have-key-events": "error",
+        "jsx-a11y/no-static-element-interactions": "error"
+      }
+    }
+  ]
+} 

package/.flake8

@@ -0,0 +1,18 @@
+[flake8]
+# Disable checks for:
+# E501: line too long
+# E201/E202: whitespace after/before '(', '[', or '{'
+# E203: whitespace before ':'
+# E211: whitespace before '('
+# E221/E222/E223/E224/E225/E226/E227/E228: multiple spacing errors
+# E231/E241/E242: missing or extra whitespace after/before comma
+# E261/E262: spaces before inline comment
+# E301/E302/E303/E304: blank line related
+# W291/W292/W293: trailing whitespace and newline issues
+# W391: blank line at end of file
+# Add more codes as needed
+
+ignore = E201,E202,E203,E211,E221,E222,E223,E224,E225,E226,E227,E228,E231,E241,E242,E261,E262,E301,E302,E303,E304,E501,W291,W292,W293,W391
+
+# Optionally, you can also raise the line length limit to avoid triggering it in other tools
+max-line-length = 999

package/.github/workflows/ci.yml

@@ -0,0 +1,300 @@
+name: CI/CD Pipeline
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main, develop]
+
+jobs:
+  # Python package testing
+  python-test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: [3.8, 3.9, "3.10", "3.11", "3.12"]
+    
+    services:
+      postgres:
+        image: postgres:14
+        env:
+          POSTGRES_PASSWORD: postgres
+          POSTGRES_DB: email_templates_test
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+        ports:
+          - 5432:5432
+    
+    steps:
+    - uses: actions/checkout@v4
+    
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v4
+      with:
+        python-version: ${{ matrix.python-version }}
+    
+    - name: Cache pip dependencies
+      uses: actions/cache@v3
+      with:
+        path: ~/.cache/pip
+        key: ${{ runner.os }}-pip-${{ hashFiles('packages/python/requirements*.txt') }}
+        restore-keys: |
+          ${{ runner.os }}-pip-
+    
+    - name: Install dependencies
+      run: |
+        cd packages/python
+        python -m pip install --upgrade pip
+        pip install -e .[dev,sendgrid,fastapi,all]
+    
+    - name: Run linting
+      run: |
+        cd packages/python
+        black --check .
+        isort --check-only .
+        mypy .
+    
+    - name: Run tests
+      env:
+        DATABASE_URL: postgresql://postgres:postgres@localhost:5432/email_templates_test
+        SENDGRID_API_KEY: ${{ secrets.SENDGRID_API_KEY_TEST }}
+      run: |
+        cd packages/python
+        pytest --cov=email_template_manager --cov-report=xml
+    
+    - name: Upload coverage to Codecov
+      uses: codecov/codecov-action@v3
+      with:
+        file: packages/python/coverage.xml
+        flags: python
+        name: python-${{ matrix.python-version }}
+
+  # Node.js package testing
+  node-test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [16, 18, 20]
+    
+    steps:
+    - uses: actions/checkout@v4
+    
+    - name: Use Node.js ${{ matrix.node-version }}
+      uses: actions/setup-node@v4
+      with:
+        node-version: ${{ matrix.node-version }}
+        cache: 'npm'
+    
+    - name: Install dependencies
+      run: npm ci
+    
+    - name: Run linting
+      run: npm run lint
+    
+    - name: Run type checking
+      run: npm run type-check
+    
+    - name: Run tests
+      env:
+        SENDGRID_API_KEY: ${{ secrets.SENDGRID_API_KEY_TEST }}
+      run: npm run test:coverage
+    
+    - name: Build packages
+      run: npm run build
+    
+    - name: Upload coverage to Codecov
+      uses: codecov/codecov-action@v3
+      with:
+        file: coverage/lcov.info
+        flags: javascript
+        name: node-${{ matrix.node-version }}
+
+  # Integration tests
+  integration-test:
+    runs-on: ubuntu-latest
+    needs: [python-test, node-test]
+    
+    services:
+      postgres:
+        image: postgres:14
+        env:
+          POSTGRES_PASSWORD: postgres
+          POSTGRES_DB: email_templates_test
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+        ports:
+          - 5432:5432
+    
+    steps:
+    - uses: actions/checkout@v4
+    
+    - name: Set up Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: "3.11"
+    
+    - name: Set up Node.js
+      uses: actions/setup-node@v4
+      with:
+        node-version: 18
+        cache: 'npm'
+    
+    - name: Install Python dependencies
+      run: |
+        cd packages/python
+        pip install -e .[all]
+    
+    - name: Install Node.js dependencies
+      run: npm ci
+    
+    - name: Build Node.js packages
+      run: npm run build
+    
+    - name: Run FastAPI example
+      env:
+        DATABASE_URL: postgresql://postgres:postgres@localhost:5432/email_templates_test
+        SENDGRID_API_KEY: ${{ secrets.SENDGRID_API_KEY_TEST }}
+      run: |
+        cd examples/fastapi-example
+        pip install -r requirements.txt
+        python -m pytest test_integration.py || true
+    
+    - name: Run Next.js example build
+      env:
+        DATABASE_URL: postgresql://postgres:postgres@localhost:5432/email_templates_test
+        SENDGRID_API_KEY: ${{ secrets.SENDGRID_API_KEY_TEST }}
+      run: |
+        cd examples/nextjs-example
+        npm install
+        npm run build
+
+  # Security scanning
+  security:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+    
+    - name: Run Python security scan
+      run: |
+        cd packages/python
+        pip install safety bandit
+        safety check
+        bandit -r email_template_manager/
+    
+    - name: Run Node.js security scan
+      run: |
+        npm audit --audit-level moderate
+
+  # Python package publishing
+  publish-python:
+    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+    needs: [python-test, integration-test, security]
+    runs-on: ubuntu-latest
+    
+    steps:
+    - uses: actions/checkout@v4
+    
+    - name: Set up Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: "3.11"
+    
+    - name: Install build dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install build twine
+    
+    - name: Build package
+      run: |
+        cd packages/python
+        python -m build
+    
+    - name: Check package
+      run: |
+        cd packages/python
+        twine check dist/*
+    
+    - name: Publish to PyPI
+      env:
+        TWINE_USERNAME: __token__
+        TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
+      run: |
+        cd packages/python
+        twine upload dist/* --skip-existing
+
+  # NPM package publishing
+  publish-npm:
+    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+    needs: [node-test, integration-test, security]
+    runs-on: ubuntu-latest
+    
+    steps:
+    - uses: actions/checkout@v4
+    
+    - name: Set up Node.js
+      uses: actions/setup-node@v4
+      with:
+        node-version: 18
+        cache: 'npm'
+        registry-url: 'https://registry.npmjs.org'
+    
+    - name: Install dependencies
+      run: npm ci
+    
+    - name: Build packages
+      run: npm run build
+    
+    - name: Create release pull request or publish
+      id: changesets
+      uses: changesets/action@v1
+      with:
+        publish: npm run release
+        commit: "chore: release packages"
+        title: "chore: release packages"
+      env:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+  # Docker image building
+  docker:
+    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+    needs: [python-test, node-test]
+    runs-on: ubuntu-latest
+    
+    steps:
+    - uses: actions/checkout@v4
+    
+    - name: Set up Docker Buildx
+      uses: docker/setup-buildx-action@v3
+    
+    - name: Login to Docker Hub
+      uses: docker/login-action@v3
+      with:
+        username: ${{ secrets.DOCKERHUB_USERNAME }}
+        password: ${{ secrets.DOCKERHUB_TOKEN }}
+    
+    - name: Build and push API server image
+      uses: docker/build-push-action@v5
+      with:
+        context: .
+        file: docker/api.Dockerfile
+        push: true
+        tags: |
+          email-template-manager/api:latest
+          email-template-manager/api:${{ github.sha }}
+    
+    - name: Build and push worker image
+      uses: docker/build-push-action@v5
+      with:
+        context: .
+        file: docker/worker.Dockerfile
+        push: true
+        tags: |
+          email-template-manager/worker:latest
+          email-template-manager/worker:${{ github.sha }} 

package/EXTRACTION_SUMMARY.md

@@ -0,0 +1,265 @@
+# Email Template Manager - Extraction Summary
+
+## Overview
+
+This document summarizes the email management functionality extracted from the Event Venue Platform and shows how it can be packaged as a standalone, reusable component library.
+
+## Extracted Functionality
+
+### From the Original Venue Platform
+
+The following email-related features were identified and extracted from the existing venue platform specifications:
+
+#### 1. **Email Template Management** (from `plans/backoffice/data_and_api.md`)
+
+- **EmailTemplate Model**: Template storage with HTML/text content, variables, and metadata
+- **Template CRUD Operations**: Create, read, update, delete templates
+- **Variable System**: Liquid-style template variables with type validation
+- **Template Rendering**: Dynamic content generation with variable substitution
+
+#### 2. **Email Scheduling** (from `plans/backoffice/data_and_api.md`)
+
+- **ScheduledEmail Model**: Queue system for timed email delivery
+- **Trigger Types**: Immediate, relative (days before/after event), and absolute scheduling
+- **Background Processing**: Cron-based email processing with retry logic
+- **Batch Operations**: Send multiple emails efficiently
+
+#### 3. **Magic Link Authentication** (from `plans/backoffice/data_and_api.md`)
+
+- **MagicLink Model**: Secure, expiring tokens for passwordless authentication
+- **Token Management**: Generation, validation, usage, and expiration
+- **Payload Support**: Embed custom data in magic links
+- **Security**: Token hashing and encryption
+
+#### 4. **Admin UI Components** (from `plans/backoffice/ui_specification.md`)
+
+- **Template Editor**: Rich HTML editor with live preview
+- **Template List**: Sortable, filterable template management
+- **Email Queue Management**: View and control scheduled emails
+- **Variable Manager**: Define and edit template variables
+
+#### 5. **SendGrid Integration** (from `plans/architecture.md`)
+
+- **Provider Abstraction**: Support multiple email providers
+- **Webhook Handling**: Process delivery status updates
+- **Error Handling**: Retry logic and failure tracking
+
+## New Component Architecture
+
+### Core Packages
+
+#### `@email-template-manager/core` (TypeScript/JavaScript)
+
+```typescript
+import {
+  EmailTemplateManager,
+  EmailScheduler,
+  MagicLinkManager,
+} from "@email-template-manager/core";
+
+const manager = new EmailTemplateManager(config);
+const scheduler = new EmailScheduler(manager, emailProvider);
+const magicLinks = new MagicLinkManager(config);
+```
+
+#### `@email-template-manager/react` (React Components)
+
+```typescript
+import {
+  EmailTemplateEditor,
+  EmailTemplateList,
+  ScheduledEmailsManager,
+} from "@email-template-manager/react";
+
+<EmailTemplateProvider config={config}>
+  <EmailTemplateEditor onSave={handleSave} />
+  <EmailTemplateList templates={templates} />
+</EmailTemplateProvider>;
+```
+
+#### `email-template-manager` (Python SDK)
+
+```python
+from email_template_manager import EmailTemplateManager, EmailScheduler, SendGridProvider
+
+manager = EmailTemplateManager("postgresql://...")
+provider = SendGridProvider({"api_key": "...", "from_email": "..."})
+scheduler = EmailScheduler(manager, provider)
+```
+
+### Framework Integrations
+
+#### **FastAPI Integration**
+
+- Ready-to-use router with all CRUD endpoints
+- Background task integration for email processing
+- Pydantic models for request/response validation
+- Async/await support throughout
+
+#### **React Integration**
+
+- Complete UI component library
+- Hooks for data management (`useEmailTemplates`, `useScheduledEmails`)
+- Theme provider for customization
+- TypeScript support
+
+#### **Next.js Integration**
+
+- SSR-compatible components
+- API route helpers
+- Database connection management
+- Environment variable configuration
+
+## Migration Benefits
+
+### 1. **Reusability**
+
+- Use the same email functionality across multiple projects
+- Consistent API and behavior across different frameworks
+- Reduced development time for new projects
+
+### 2. **Maintainability**
+
+- Single codebase for email template management
+- Centralized bug fixes and feature updates
+- Better testing and documentation
+
+### 3. **Scalability**
+
+- Framework-agnostic core allows adoption in any environment
+- Plugin architecture for email providers
+- Horizontal scaling with queue-based processing
+
+### 4. **Community Benefits**
+
+- Open source project can gather community contributions
+- Multiple teams can benefit from shared functionality
+- Documentation and examples improve over time
+
+## Implementation Roadmap
+
+### Phase 1: Core Library (Weeks 1-4)
+
+- [ ] Extract core TypeScript library from venue platform specs
+- [ ] Implement email template management
+- [ ] Add scheduling and magic link functionality
+- [ ] Create email provider abstractions
+- [ ] Add comprehensive tests
+
+### Phase 2: React Components (Weeks 3-6)
+
+- [ ] Build React component library based on backoffice UI specs
+- [ ] Create hooks for data management
+- [ ] Add theme support and customization
+- [ ] Build Storybook documentation
+
+### Phase 3: Python SDK (Weeks 5-8)
+
+- [ ] Implement Python version using FastAPI patterns from venue platform
+- [ ] Add SQLAlchemy models and database management
+- [ ] Create framework integrations (FastAPI, Django, Flask)
+- [ ] Add CLI tools for management
+
+### Phase 4: Documentation & Examples (Weeks 7-10)
+
+- [ ] Create comprehensive documentation website
+- [ ] Build integration examples for each framework
+- [ ] Add interactive playground and demos
+- [ ] Write migration guides
+
+### Phase 5: Open Source Launch (Weeks 9-12)
+
+- [ ] Set up GitHub organization and repositories
+- [ ] Configure CI/CD and package publishing
+- [ ] Create community guidelines and contribution docs
+- [ ] Launch marketing campaign
+
+## Package Publishing Strategy
+
+### NPM Packages
+
+```bash
+@email-template-manager/core      # Core TypeScript library
+@email-template-manager/react     # React components
+@email-template-manager/api       # Node.js API server
+```
+
+### Python Package
+
+```bash
+email-template-manager             # Main Python package
+email-template-manager[fastapi]    # FastAPI extras
+email-template-manager[django]     # Django extras
+```
+
+### Docker Images
+
+```bash
+email-template-manager/api         # Standalone API server
+email-template-manager/worker      # Background email processor
+```
+
+## Success Metrics
+
+### Adoption Metrics
+
+- NPM download count
+- PyPI download statistics
+- GitHub stars and forks
+- Documentation page views
+
+### Quality Metrics
+
+- Test coverage (target: 90%+)
+- Build success rate
+- Security vulnerability count
+- Performance benchmarks
+
+### Community Metrics
+
+- GitHub issues and PRs
+- Discord/community engagement
+- Blog post shares
+- Integration showcases
+
+## Risk Assessment & Mitigation
+
+### Technical Risks
+
+- **Database compatibility**: Mitigate with adapter pattern
+- **Email provider limits**: Implement rate limiting and queuing
+- **Security vulnerabilities**: Regular audits and dependency updates
+
+### Community Risks
+
+- **Low adoption**: Strong documentation and examples
+- **Maintenance burden**: Clear contributor guidelines and team
+- **Competition**: Focus on superior developer experience
+
+### Business Risks
+
+- **Funding sustainability**: GitHub Sponsors and corporate support
+- **Legal issues**: Clear licensing and contribution agreements
+- **Trademark conflicts**: Research and register appropriate names
+
+## Next Steps
+
+1. **Immediate Actions**
+
+   - [ ] Register package names on NPM and PyPI
+   - [ ] Set up GitHub organization and main repository
+   - [ ] Create initial project structure and documentation
+
+2. **Week 1 Goals**
+
+   - [ ] Complete core library specification
+   - [ ] Set up development environment and tooling
+   - [ ] Begin implementation of core functionality
+
+3. **Month 1 Goals**
+   - [ ] Alpha release of core packages
+   - [ ] Basic React components functional
+   - [ ] Python SDK with FastAPI integration
+   - [ ] Initial documentation website
+
+This extraction transforms venue-specific email functionality into a powerful, reusable library that can benefit the entire developer community while maintaining all the sophisticated features designed for the original platform.