@igniter-js/mail 0.1.0

package/AGENTS.md

@@ -0,0 +1,394 @@
+# @igniter-js/mail - AI Agent Instructions
+
+> **Package Version:** 0.1.0  
+> **Last Updated:** 2025-01-13  
+> **Status:** Ready for Publication
+
+---
+
+## Package Overview
+
+**Name:** `@igniter-js/mail`  
+**Purpose:** Type-safe email library for Igniter.js with React Email templates and multiple provider adapters  
+**Type:** Standalone Library (can be used independently or with Igniter.js)
+
+### Core Features
+- Type-safe email templates with React Email components
+- Runtime validation with StandardSchema support  
+- Multiple provider adapters (Resend, Postmark, SendGrid, SMTP, Webhook)
+- Queue integration for async email delivery
+- Lifecycle hooks for monitoring and logging
+- Builder pattern for fluent configuration
+- Server-first design (Node.js, Bun, Deno)
+
+---
+
+## Architecture
+
+### Design Principles
+
+1. **Type Safety First**
+   - End-to-end TypeScript inference from templates to send params
+   - Template payload validation with StandardSchema
+   - No `any` types in public APIs
+
+2. **React Email Integration**
+   - Templates are React components
+   - Automatic HTML and plain-text rendering
+   - Leverage React Email's component library
+
+3. **Adapter-Based Architecture**
+   - Core defines interfaces, adapters provide implementations
+   - Easy to add new email providers
+   - Adapters are peer dependencies (optional)
+
+4. **Builder Pattern**
+   - Fluent API for configuration
+   - Type-safe template registration
+   - Compile-time validation of configuration
+
+---
+
+## File Structure
+
+```
+packages/mail/
+├── src/
+│   ├── index.ts                         # Public exports
+│   │
+│   ├── core/
+│   │   └── igniter-mail.tsx            # Core runtime logic
+│   │
+│   ├── builders/
+│   │   ├── igniter-mail.builder.ts     # Main builder
+│   │   ├── mail-template.builder.ts    # Template builder
+│   │   └── mail-provider.builder.ts    # Provider builder
+│   │
+│   ├── adapters/
+│   │   ├── resend.adapter.ts           # Resend provider
+│   │   ├── postmark.adapter.ts         # Postmark provider
+│   │   ├── sendgrid.adapter.ts         # SendGrid provider
+│   │   ├── smtp.adapter.ts             # SMTP provider
+│   │   ├── webhook.adapter.ts          # Webhook testing adapter
+│   │   └── test.adapter.ts             # In-memory test adapter
+│   │
+│   ├── errors/
+│   │   ├── igniter-mail.error.ts       # Main error class
+│   │   └── mail-provider.error.ts      # Provider-specific errors
+│   │
+│   ├── interfaces/
+│   │   ├── adapter.interface.ts        # Adapter contract (deprecated)
+│   │   └── provider.interface.ts       # Provider contract (deprecated)
+│   │
+│   ├── types/
+│   │   ├── adapter.ts                  # Adapter types
+│   │   ├── provider.ts                 # Provider types
+│   │   └── templates.ts                # Template types
+│   │
+│   ├── utils/
+│   │   ├── get-adapter.ts              # Adapter resolution utility
+│   │   └── validate-standard-schema-input.ts # Schema validation
+│   │
+│   ├── mail.provider.tsx               # Legacy provider (deprecated)
+│   ├── igniter-mail.spec.ts            # Unit tests
+│   └── adapters.spec.ts                # Adapter tests
+│
+├── package.json
+├── tsconfig.json
+├── tsup.config.ts
+├── vitest.config.ts
+├── README.md
+├── AGENTS.md                            # This file
+└── CHANGELOG.md
+```
+
+---
+
+## Key Responsibilities
+
+### `IgniterMail` (Core Runtime)
+
+The core class handles:
+- Template registration and management
+- Template data validation using StandardSchema
+- React Email rendering (HTML + plain text)
+- Adapter orchestration
+- Queue integration for scheduled sends
+- Lifecycle hooks (onSendStarted, onSendSuccess, onSendError)
+- Error handling and normalization
+
+**Key Invariants:**
+- All templates must have a `subject`, `schema`, and `render` function
+- Template data is validated before rendering
+- All predictable failures throw `IgniterMailError` with stable `code`
+- Hooks are always invoked (started → success/error)
+
+### `MailAdapter` (Infrastructure-only)
+
+Adapters **must**:
+- Implement the `send` method with `MailAdapterSendParams`
+- Handle provider-specific API calls and authentication
+- NOT implement business logic (no validation, no hooks, no queuing)
+- Return cleanly or throw errors (which core will normalize)
+
+**Mental Model:**
+- **Core** decides *what* to send and *when*
+- **Adapter** executes *how* to talk to the provider
+
+---
+
+## Development Guidelines
+
+### Adding New Features
+
+1. **Business Logic → Core**
+   - If it's a rule or decision, it belongs in `IgniterMail`
+   - Examples: validation, hooks, queuing
+
+2. **Infrastructure Logic → Adapter**
+   - If it's provider-specific, it belongs in the adapter
+   - Examples: API calls, authentication, retry logic
+
+3. **Public API → Builder or Core**
+   - If users need to configure it, add to `IgniterMailBuilder`
+   - If users need to call it at runtime, add to `IgniterMail`
+
+### Testing Strategy
+
+**Unit Tests** (`igniter-mail.spec.ts`):
+- Use `TestMailAdapter` for isolated core testing
+- Test template validation (valid and invalid schemas)
+- Test hooks lifecycle (started, success, error)
+- Test queue integration (enqueue vs immediate send)
+
+**Adapter Tests** (`adapters.spec.ts`):
+- Test each adapter's builder and configuration
+- Mock provider APIs
+- Test error handling
+
+**Type Tests** (future):
+- Verify template key type inference
+- Verify payload type inference
+- Verify builder fluent API type safety
+
+### Code Style
+
+- Follow ESLint rules (`npm run lint`)
+- Use JSDoc comments for public APIs (in English)
+- Prefer explicit types over inference in public APIs
+- Use `readonly` for immutable properties
+- Use `async/await` over raw Promises
+
+### Error Handling
+
+- All predictable errors must throw `IgniterMailError`
+- Use stable error codes (e.g., `MAIL_PROVIDER_TEMPLATE_NOT_FOUND`)
+- Include relevant context in `error.metadata`
+
+### Commit Messages
+
+Follow Conventional Commits:
+```
+feat(mail): add SendGrid adapter
+fix(mail): handle schema validation errors correctly
+docs(mail): update README with queue examples
+test(mail): add tests for template validation
+```
+
+---
+
+## Adding a New Adapter
+
+1. Create new file in `src/adapters/` (e.g., `aws-ses.adapter.ts`)
+2. Create builder class extending pattern (e.g., `AwsSesMailAdapterBuilder`)
+3. Implement `send` method with provider API calls
+4. Export adapter and builder from `src/index.ts`
+5. Add provider to `IgniterMailBuilder.withAdapter()` shorthand (optional)
+6. Add tests for adapter-specific behavior
+7. Update README with adapter documentation
+8. Add peer dependency to `package.json`
+
+**Adapter Checklist:**
+- ✅ Implement `MailAdapter` interface
+- ✅ Handle provider authentication
+- ✅ Support `to`, `subject`, `html`, `text` fields
+- ✅ Optionally support `scheduledAt` if provider supports it
+- ✅ Throw descriptive errors
+- ✅ Export builder with `create()` factory
+
+---
+
+## Common Tasks
+
+### Running Tests
+
+```bash
+# Run all tests
+npm run test
+
+# Watch mode
+npm run test:watch
+
+# Run specific test file
+npm run test -- igniter-mail.spec.ts
+```
+
+### Building
+
+```bash
+# Build once
+npm run build
+
+# Build and watch
+npm run dev
+```
+
+### Type Checking
+
+```bash
+npm run typecheck
+```
+
+### Linting
+
+```bash
+npm run lint
+```
+
+---
+
+## Environment Variables
+
+While the package doesn't directly read environment variables, adapters typically require:
+
+**Resend:**
+- `RESEND_API_KEY` - Resend API key
+
+**Postmark:**
+- `POSTMARK_SERVER_TOKEN` - Postmark server token
+
+**SendGrid:**
+- `SENDGRID_API_KEY` - SendGrid API key
+
+**SMTP:**
+- `SMTP_HOST` - SMTP server host
+- `SMTP_PORT` - SMTP server port
+- `SMTP_USER` - SMTP username
+- `SMTP_PASS` - SMTP password
+
+---
+
+## Publishing Workflow
+
+### Pre-Publish Checklist
+
+- [ ] All tests passing (`npm run test`)
+- [ ] Build succeeds (`npm run build`)
+- [ ] TypeScript compiles (`npm run typecheck`)
+- [ ] Linting passes (`npm run lint`)
+- [ ] README.md is up-to-date
+- [ ] CHANGELOG.md is updated with version changes
+- [ ] Version in `package.json` is correct
+- [ ] All exports in `src/index.ts` are correct
+
+### Version Update Process
+
+**NEVER update version without user approval.**
+
+When changes are ready:
+1. Review changes made
+2. Suggest version bump options (patch/minor/major)
+3. Wait for user approval
+4. Update `package.json` version
+5. Update `CHANGELOG.md`
+6. Run quality checks
+7. Ask about publishing
+
+### Publishing
+
+```bash
+# Login to npm (if not already)
+npm login
+
+# Publish (from package directory)
+cd packages/mail
+npm publish --access public
+```
+
+---
+
+## Error Codes Reference
+
+| Code | Reason |
+|------|--------|
+| `MAIL_PROVIDER_ADAPTER_REQUIRED` | No adapter configured |
+| `MAIL_PROVIDER_TEMPLATES_REQUIRED` | No templates registered |
+| `MAIL_PROVIDER_TEMPLATE_NOT_FOUND` | Template key doesn't exist |
+| `MAIL_PROVIDER_TEMPLATE_DATA_INVALID` | Schema validation failed |
+| `MAIL_PROVIDER_SEND_FAILED` | Failed to send email |
+| `MAIL_PROVIDER_SCHEDULE_DATE_INVALID` | Schedule date is in the past |
+| `MAIL_PROVIDER_SCHEDULE_FAILED` | Failed to schedule email |
+| `MAIL_PROVIDER_FROM_REQUIRED` | FROM address not configured |
+| `MAIL_PROVIDER_ADAPTER_SECRET_REQUIRED` | Adapter secret not provided |
+| `MAIL_PROVIDER_ADAPTER_NOT_FOUND` | Unknown adapter provider |
+| `MAIL_ADAPTER_CONFIGURATION_INVALID` | Adapter configuration error |
+
+---
+
+## Non-Goals
+
+By design, this package does NOT:
+- Implement business rules in adapters (that's the core's job)
+- Provide browser-side email sending (server-first)
+- Bundle all adapter dependencies (they're peer dependencies)
+- Support synchronous email sending (always async)
+
+---
+
+## Quick Reference
+
+### Key Files
+
+| File | Purpose |
+|------|---------|
+| `src/index.ts` | Public exports |
+| `src/core/igniter-mail.tsx` | Core runtime logic |
+| `src/builders/igniter-mail.builder.ts` | Builder API |
+| `src/adapters/*.adapter.ts` | Provider adapters |
+| `src/types/*.ts` | Public types |
+| `src/errors/*.ts` | Error classes |
+
+### Key Commands
+
+| Command | Purpose |
+|---------|---------|
+| `npm run dev` | Build and watch |
+| `npm run build` | Build once |
+| `npm run test` | Run tests |
+| `npm run typecheck` | Check types |
+| `npm run lint` | Lint code |
+
+---
+
+## Support & Communication
+
+When working on this package:
+- **Read this file first** before making changes
+- **Follow existing patterns** - consistency is key
+- **Update documentation** after every code change
+- **Write tests** for new features and bug fixes
+- **Ask for clarification** if requirements are unclear
+- **Suggest improvements** to this AGENTS.md if needed
+
+---
+
+## Changelog History
+
+### v0.1.0 (Initial Release)
+- Core email functionality with React Email
+- Type-safe templates with StandardSchema validation
+- Multiple adapters (Resend, Postmark, SendGrid, SMTP, Webhook, Test)
+- Queue integration for scheduled sends
+- Lifecycle hooks
+- Builder pattern API
+- Comprehensive documentation

package/CHANGELOG.md

@@ -0,0 +1,95 @@
+# Changelog
+
+All notable changes to `@igniter-js/mail` 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).
+
+## [0.1.0] - 2025-01-13
+
+### 🎉 Initial Release
+
+First public release of `@igniter-js/mail` - a type-safe email library for Igniter.js with React Email templates.
+
+### ✨ Features
+
+#### Core Functionality
+- **Type-Safe Templates** - Full TypeScript support with compile-time inference
+- **React Email Integration** - Build beautiful emails with React components
+- **StandardSchema Validation** - Runtime validation of template payloads
+- **Builder Pattern** - Fluent API for configuration
+- **Queue Integration** - Schedule emails with BullMQ or custom queues
+- **Lifecycle Hooks** - React to send events (started, success, error)
+
+#### Email Operations
+- **`send()`** - Send emails immediately
+- **`schedule()`** - Schedule emails for future delivery
+- **Template Management** - Type-safe template registration
+- **Subject Override** - Per-send subject customization
+- **HTML + Plain Text** - Automatic generation of both formats
+
+#### Adapters
+- **Resend Adapter** - Official Resend integration
+- **Postmark Adapter** - Postmark email service
+- **SendGrid Adapter** - SendGrid email service
+- **SMTP Adapter** - Standard SMTP protocol support (Nodemailer)
+- **Webhook Adapter** - HTTP webhook for testing
+- **Test Adapter** - In-memory adapter for unit tests
+
+#### Developer Experience
+- **Comprehensive Error Handling** - Typed `IgniterMailError` with stable error codes
+- **Rich Type Definitions** - Complete TypeScript types for all APIs
+- **React Email Components** - Full access to @react-email/components
+- **Type Inference** - Template keys and payloads inferred at compile time
+- **Builder Validation** - Configuration errors caught at build time
+
+#### Integration Features
+- **Queue Integration** - Optional BullMQ integration for async delivery
+- **Logger Support** - Attach Igniter.js logger for debugging
+- **Hook System** - Extensible hooks for monitoring and analytics
+- **Legacy API Support** - Backwards compatibility with older initialization
+
+### 📦 Package Configuration
+- ESM and CJS exports
+- TypeScript declaration files
+- Tree-shakeable exports
+- Peer dependencies for adapters (optional)
+- Source maps included
+
+### 📚 Documentation
+- Comprehensive README with examples
+- API reference documentation
+- Adapter configuration guides
+- Queue integration examples
+- Error codes reference
+- Type inference guide
+- AGENTS.md for AI agent development
+
+### 🧪 Testing
+- Unit tests for core functionality
+- Adapter-specific tests
+- Template validation tests
+- Hook lifecycle tests
+- Queue integration tests
+
+---
+
+## Future Releases
+
+Planned features for upcoming versions:
+- AWS SES adapter
+- Mailgun adapter
+- SparkPost adapter
+- Email preview server
+- Template hot-reloading
+- Batch sending
+- Attachment support
+- Inline images
+- Email tracking/analytics
+- Template versioning
+- A/B testing support
+- Unsubscribe link management
+
+---
+
+[0.1.0]: https://github.com/felipebarcelospro/igniter-js/releases/tag/@igniter-js/mail@0.1.0