@bernierllc/email 1.0.1 → 1.1.0

package/README.md

@@ -1,232 +1,91 @@
-# Email Template Manager - Universal Email Management Component
+# @bernierllc/email
 
-## Overview
+> **⚠️ DEPRECATED**: This package is deprecated as of v1.1.0. Please migrate to **[@bernierllc/email-service](../email-service)** for continued support and new features.
+>
+> **Migration Guide**: See [email-service/MIGRATION.md](../email-service/MIGRATION.md) for step-by-step migration instructions.
+>
+> **Why migrate?**
+> - All features from `@bernierllc/email` are available in `@bernierllc/email-service`
+> - Additional production features: database persistence, delivery tracking, subscriber management, webhooks
+> - Active development and support
+>
+> **Timeline**: This package will receive critical bug fixes only. New features will be added to `@bernierllc/email-service`.
 
-A framework-agnostic email management library that provides template creation, scheduling, and delivery capabilities with support for React, Next.js, and Python applications. Extracted from the Event Venue Platform project to serve as a reusable component for any application requiring sophisticated email automation.
+A comprehensive email service that orchestrates sending, templates, authentication, and retry logic using BernierLLC's core packages.
 
-## Core Features
-
-### 🎨 Template Management
-
-- **Visual Template Editor** - Rich HTML/text editor with live preview
-- **Liquid Template Engine** - Dynamic content with `{{variable}}` syntax
-- **Multi-format Support** - HTML and plain text versions
-- **Template Versioning** - Track changes and rollback capabilities
-- **Theme Support** - Customizable styling per application/tenant
-
-### 📅 Email Scheduling
-
-- **Event-based Triggers** - Schedule emails relative to dates/events
-- **Batch Processing** - Queue and send multiple emails efficiently
-- **Retry Logic** - Automatic retry with exponential backoff
-- **Pause/Resume** - Admin control over scheduled campaigns
-- **Delivery Tracking** - Monitor sent, opened, clicked, bounced
-
-### 🔐 Authentication & Security
-
-- **Magic Link Generation** - Secure token-based authentication
-- **Token Expiration** - Configurable expiry times
-- **One-time Use** - Prevent token reuse
-- **Rate Limiting** - Protect against abuse
-- **Encryption** - Secure token storage and transmission
-
-### 🚀 Multi-platform Support
-
-- **React Components** - Pre-built UI components for template management
-- **Python SDK** - FastAPI/Django integration with ORM models
-- **REST API** - Framework-agnostic HTTP interface
-- **TypeScript Support** - Full type definitions included
-- **Database Agnostic** - Supports PostgreSQL, MySQL, SQLite
-
-## Project Structure
-
-```
-email-template-manager/
-├── packages/
-│   ├── core/              # Core TypeScript/JavaScript library
-│   ├── react/             # React components and hooks
-│   ├── python/            # Python SDK and FastAPI integration
-│   └── api/               # Standalone REST API server
-├── examples/
-│   ├── nextjs-example/    # Next.js integration example
-│   ├── react-example/     # React app example
-│   ├── fastapi-example/   # FastAPI backend example
-│   └── django-example/    # Django integration example
-├── docs/                  # Documentation website
-├── scripts/               # Build and deployment scripts
-└── tests/                 # End-to-end test suites
-```
-
-## Quick Start
-
-### npm/yarn Installation
-
-```bash
-# For React/Next.js projects
-npm install @email-template-manager/react
-npm install @email-template-manager/core
-
-# For Node.js backends
-npm install @email-template-manager/api
-```
-
-### pip Installation
+## Installation
 
 ```bash
-# For Python projects
-pip install email-template-manager[fastapi]
-pip install email-template-manager[django]
+npm install @bernierllc/email
 ```
 
-### CDN Usage
-
-```html
-<!-- For vanilla JavaScript -->
-<script src="https://unpkg.com/@email-template-manager/core@latest/dist/index.js"></script>
+## Usage
+
+```typescript
+import { EmailService } from '@bernierllc/email';
+
+const emailService = new EmailService({
+  provider: {
+    type: 'sendgrid',
+    config: {
+      apiKey: process.env.SENDGRID_API_KEY
+    }
+  },
+  defaults: {
+    from: 'noreply@yourdomain.com',
+    replyTo: 'support@yourdomain.com'
+  },
+  templates: {
+    engine: 'liquid',
+    templateDir: './email-templates',
+    cache: true
+  },
+  magicLink: {
+    secret: process.env.MAGIC_LINK_SECRET,
+    expirationMinutes: 60,
+    issuer: 'YourApp'
+  },
+  retry: {
+    maxRetries: 3,
+    initialDelayMs: 1000,
+    maxDelayMs: 30000,
+    jitter: true,
+    enableMetrics: true
+  }
+});
+
+// Send a basic email
+const result = await emailService.send({
+  to: 'user@example.com',
+  subject: 'Welcome!',
+  html: '<h1>Welcome to our service!</h1>',
+  text: 'Welcome to our service!'
+});
+
+console.log('Email sent:', result.success);
 ```
 
-## Package Management & Distribution
-
-### NPM Packages
-
-- `@email-template-manager/core` - Core functionality
-- `@email-template-manager/react` - React components
-- `@email-template-manager/api` - Node.js API server
-
-### Python Packages
-
-- `email-template-manager` - Main Python package
-- `email-template-manager[fastapi]` - FastAPI extras
-- `email-template-manager[django]` - Django extras
-
-### Docker Images
-
-- `email-template-manager/api` - Standalone API server
-- `email-template-manager/worker` - Background job processor
-
-## Open Source Setup
-
-### Repository Structure
-
-- **Monorepo** - All packages in single repository with Lerna/Nx
-- **MIT License** - Permissive open source license
-- **Contributing Guidelines** - Clear contribution process
-- **Code of Conduct** - Community standards
-- **Issue Templates** - Bug reports and feature requests
-
-### Development Tools
+## Features
 
-- **TypeScript** - Type safety across all packages
-- **Jest** - Unit and integration testing
-- **ESLint/Prettier** - Code formatting and linting
-- **Husky** - Git hooks for quality control
-- **Semantic Release** - Automated versioning and publishing
+- Multi-provider email sending (SMTP, SendGrid, SES, Mailgun, Postmark)
+- Template rendering (Liquid/Handlebars)  
+- Magic link authentication
+- Reliable delivery with retry logic
+- Performance metrics and analytics
+- Bulk email operations
+- Rate limiting and batch processing
 
-### CI/CD Pipeline
+## Dependencies
 
-- **GitHub Actions** - Automated testing and deployment
-- **Test Coverage** - Minimum 80% coverage requirement
-- **Security Scanning** - Automated vulnerability detection
-- **Performance Testing** - Load testing for API endpoints
-
-## Supported Integrations
-
-### Email Providers
-
-- **SendGrid** - Primary provider with full feature support
-- **AWS SES** - Cost-effective option for high volume
-- **Mailgun** - Developer-friendly API
-- **Postmark** - Transactional email specialist
-- **SMTP** - Generic SMTP server support
-
-### Databases
-
-- **PostgreSQL** - Recommended for production
-- **MySQL** - Wide compatibility
-- **SQLite** - Development and testing
-- **MongoDB** - Document-based storage option
-
-### Frontend Frameworks
-
-- **React** - Full component library
-- **Next.js** - SSR and API routes integration
-- **Vue.js** - Vue 3 composition API support
-- **Angular** - Angular 12+ compatibility
-- **Svelte** - Lightweight integration
-
-### Backend Frameworks
-
-- **FastAPI** - Python async framework
-- **Django** - Django 3.2+ with admin integration
-- **Express.js** - Node.js middleware
-- **NestJS** - TypeScript decorators support
-- **Spring Boot** - Java integration (community)
-
-## Getting Started Checklist
-
-### For Package Publishing
-
-- [ ] Set up NPM organization (`@email-template-manager`)
-- [ ] Configure automated publishing with semantic-release
-- [ ] Set up PyPI account and package publishing
-- [ ] Create Docker Hub organization for container images
-- [ ] Set up CDN distribution for browser packages
-
-### For Open Source
-
-- [ ] Create GitHub organization
-- [ ] Set up repository with proper README and documentation
-- [ ] Configure issue and PR templates
-- [ ] Set up community health files (CONTRIBUTING.md, CODE_OF_CONDUCT.md)
-- [ ] Enable GitHub Discussions for community support
-- [ ] Set up GitHub Sponsors for project sustainability
-
-### For Documentation
-
-- [ ] Create documentation website (Docusaurus/GitBook)
-- [ ] Write comprehensive API documentation
-- [ ] Create integration guides for each framework
-- [ ] Record video tutorials for common use cases
-- [ ] Set up interactive playground/demo
-
-## License and Legal
-
-- **MIT License** - Permissive open source license allowing commercial use
-- **Contributor License Agreement** - Ensure proper IP assignment
-- **Trademark Guidelines** - Protect project name and logo
-- **Privacy Policy** - For any hosted services or telemetry
-
-## Community and Support
-
-### Communication Channels
-
-- **GitHub Discussions** - Community Q&A and feature requests
-- **Discord Server** - Real-time chat and support
-- **Twitter Account** - Updates and announcements
-- **Blog/Newsletter** - Technical articles and release notes
-
-### Contribution Types
-
-- **Code Contributions** - Bug fixes and new features
-- **Documentation** - Tutorials, guides, and API docs
-- **Testing** - Test cases and bug reports
-- **Translations** - Internationalization support
-- **Design** - UI/UX improvements and assets
-
-## Monorepo Workspaces & Dependency Management
-
-This package is part of a monorepo using npm workspaces. All dependencies are hoisted to the root. Always run `npm install` from the root directory.
-
-## React 19 and Testing Library Compatibility
-
-This package uses React 19.1.0. If you see peer dependency warnings with Testing Library, use:
-
-```bash
-npm install --legacy-peer-deps
-```
+This package orchestrates the following BernierLLC core packages:
 
-This is a temporary workaround until official support is released.
+- [`@bernierllc/email-sender`](../core/email-sender) - Multi-provider email sending
+- [`@bernierllc/magic-link`](../core/magic-link) - Secure token generation
+- [`@bernierllc/template-engine`](../core/template-engine) - Template rendering
+- [`@bernierllc/retry-policy`](../core/retry-policy) - Retry algorithms
+- [`@bernierllc/retry-state`](../core/retry-state) - Retry state management
+- [`@bernierllc/retry-metrics`](../core/retry-metrics) - Performance metrics
 
----
+## License
 
-This specification provides the foundation for creating a world-class, open source email management solution that can be adopted by developers across multiple platforms and use cases.
+Copyright (c) 2025 Bernier LLC. All rights reserved.

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { EmailService } from './simple-email-service';
+export * from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AACtD,cAAc,SAAS,CAAC"}

package/dist/index.js

@@ -0,0 +1,28 @@
+"use strict";
+/*
+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.
+*/
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EmailService = void 0;
+var simple_email_service_1 = require("./simple-email-service");
+Object.defineProperty(exports, "EmailService", { enumerable: true, get: function () { return simple_email_service_1.EmailService; } });
+__exportStar(require("./types"), exports);
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;EAME;;;;;;;;;;;;;;;;;AAEF,+DAAsD;AAA7C,oHAAA,YAAY,OAAA;AACrB,0CAAwB"}

package/dist/simple-email-service.d.ts

@@ -0,0 +1,58 @@
+import { EmailServiceConfig, EmailMessage, TemplateEmailMessage, MagicLinkEmail, EmailResult, BulkEmailResult, MagicLinkResult, EmailMetrics, EmailDeliveryInfo, TemplateValidationResult, IEmailService } from './types';
+/**
+ * Simplified email service demonstrating service layer orchestration pattern
+ * This implementation focuses on the service architecture rather than full integration
+ */
+export declare class EmailService implements IEmailService {
+    private readonly config;
+    private readonly retryStorage;
+    constructor(config: EmailServiceConfig);
+    /**
+     * Send a single email with retry logic
+     */
+    send(message: EmailMessage): Promise<EmailResult>;
+    /**
+     * Send an email using a template
+     */
+    sendTemplate(message: TemplateEmailMessage): Promise<EmailResult>;
+    /**
+     * Send a magic link email
+     */
+    sendMagicLink(config: MagicLinkEmail): Promise<MagicLinkResult>;
+    /**
+     * Send multiple emails
+     */
+    sendBulk(messages: EmailMessage[]): Promise<BulkEmailResult>;
+    /**
+     * Validate template syntax
+     */
+    validateTemplate(template: string): Promise<TemplateValidationResult>;
+    /**
+     * Get email delivery metrics
+     */
+    getMetrics(): Promise<EmailMetrics>;
+    /**
+     * Get delivery status
+     */
+    getDeliveryStatus(messageId: string): Promise<EmailDeliveryInfo | null>;
+    /**
+     * Test configuration
+     */
+    testConfiguration(): Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    private normalizeConfig;
+    private applyDefaults;
+    private validateMessage;
+    private sendWithRetry;
+    private renderTemplate;
+    private generateMagicLink;
+    private extractTokenFromLink;
+    private createMagicLinkHtml;
+    private createMagicLinkText;
+    private extractTemplateVariables;
+    private generateMessageId;
+    private delay;
+}
+//# sourceMappingURL=simple-email-service.d.ts.map

package/dist/simple-email-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"simple-email-service.d.ts","sourceRoot":"","sources":["../src/simple-email-service.ts"],"names":[],"mappings":"AAWA,OAAO,EACL,kBAAkB,EAClB,YAAY,EACZ,oBAAoB,EACpB,cAAc,EACd,WAAW,EACX,eAAe,EACf,eAAe,EACf,YAAY,EACZ,iBAAiB,EACjB,wBAAwB,EAGxB,aAAa,EACd,MAAM,SAAS,CAAC;AAEjB;;;GAGG;AACH,qBAAa,YAAa,YAAW,aAAa;IAChD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA+B;IACtD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA0B;gBAE3C,MAAM,EAAE,kBAAkB;IAKtC;;OAEG;IACG,IAAI,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC;IAgCvD;;OAEG;IACG,YAAY,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,WAAW,CAAC;IAsBvE;;OAEG;IACG,aAAa,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,CAAC;IAiCrE;;OAEG;IACG,QAAQ,CAAC,QAAQ,EAAE,YAAY,EAAE,GAAG,OAAO,CAAC,eAAe,CAAC;IA4ClE;;OAEG;IACG,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,wBAAwB,CAAC;IAwB3E;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,YAAY,CAAC;IAezC;;OAEG;IACG,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC;IAyB7E;;OAEG;IACG,iBAAiB,IAAI,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAsBxE,OAAO,CAAC,eAAe;IAgCvB,OAAO,CAAC,aAAa;IAUrB,OAAO,CAAC,eAAe;YAkBT,aAAa;IAyD3B,OAAO,CAAC,cAAc;IAgBtB,OAAO,CAAC,iBAAiB;IAWzB,OAAO,CAAC,oBAAoB;IAK5B,OAAO,CAAC,mBAAmB;IAe3B,OAAO,CAAC,mBAAmB;IAW3B,OAAO,CAAC,wBAAwB;IAUhC,OAAO,CAAC,iBAAiB;YAIX,KAAK;CAGpB"}