@igniter-js/mail 0.1.0 → 0.1.1

package/AGENTS.md

@@ -1,7 +1,7 @@
 # @igniter-js/mail - AI Agent Instructions
 
-> **Package Version:** 0.1.0  
-> **Last Updated:** 2025-01-13  
+> **Package Version:** 0.1.1  
+> **Last Updated:** 2025-01-22  
 > **Status:** Ready for Publication
 
 ---
@@ -15,7 +15,8 @@
 ### Core Features
 - Type-safe email templates with React Email components
 - Runtime validation with StandardSchema support  
-- Multiple provider adapters (Resend, Postmark, SendGrid, SMTP, Webhook)
+- Multiple provider adapters (Resend, Postmark, SendGrid, SMTP)
+- Mock adapter for unit testing
 - Queue integration for async email delivery
 - Lifecycle hooks for monitoring and logging
 - Builder pattern for fluent configuration
@@ -56,42 +57,46 @@ 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
+│   │   ├── index.ts                    # Adapters barrel
+│   │   ├── mock.adapter.ts             # In-memory mock adapter
+│   │   ├── mock.adapter.spec.ts        # Mock adapter tests
 │   │   ├── postmark.adapter.ts         # Postmark provider
+│   │   ├── postmark.adapter.spec.ts    # Postmark adapter tests
+│   │   ├── resend.adapter.ts           # Resend provider
+│   │   ├── resend.adapter.spec.ts      # Resend adapter tests
 │   │   ├── sendgrid.adapter.ts         # SendGrid provider
+│   │   ├── sendgrid.adapter.spec.ts    # SendGrid adapter tests
 │   │   ├── smtp.adapter.ts             # SMTP provider
-│   │   ├── webhook.adapter.ts          # Webhook testing adapter
-│   │   └── test.adapter.ts             # In-memory test adapter
+│   │   └── smtp.adapter.spec.ts        # SMTP adapter tests
 │   │
-│   ├── errors/
-│   │   ├── igniter-mail.error.ts       # Main error class
-│   │   └── mail-provider.error.ts      # Provider-specific errors
+│   ├── builders/
+│   │   ├── main.builder.ts             # Main builder
+│   │   ├── main.builder.spec.ts        # Builder tests
+│   │   ├── template.builder.ts         # Template builder
+│   │   └── template.builder.spec.ts    # Template builder tests
 │   │
-│   ├── interfaces/
-│   │   ├── adapter.interface.ts        # Adapter contract (deprecated)
-│   │   └── provider.interface.ts       # Provider contract (deprecated)
+│   ├── core/
+│   │   ├── manager.tsx                 # Core runtime logic
+│   │   └── manager.spec.tsx            # Core tests
+│   │
+│   ├── errors/
+│   │   └── mail.error.ts               # Main error class
 │   │
 │   ├── types/
 │   │   ├── adapter.ts                  # Adapter types
 │   │   ├── provider.ts                 # Provider types
+│   │   ├── telemetry.ts                # Telemetry types
 │   │   └── templates.ts                # Template types
 │   │
+│   ├── telemetry/
+│   │   └── index.ts                    # Telemetry events
+│   │
 │   ├── utils/
-│   │   ├── get-adapter.ts              # Adapter resolution utility
-│   │   └── validate-standard-schema-input.ts # Schema validation
+│   │   ├── schema.ts                   # StandardSchema utilities
+│   │   └── schema.spec.ts              # Schema tests
 │   │
-│   ├── mail.provider.tsx               # Legacy provider (deprecated)
-│   ├── igniter-mail.spec.ts            # Unit tests
-│   └── adapters.spec.ts                # Adapter tests
+│   └── shim.ts                         # Browser/client shim
 │
 ├── package.json
 ├── tsconfig.json
@@ -113,9 +118,10 @@ The core class handles:
 - Template data validation using StandardSchema
 - React Email rendering (HTML + plain text)
 - Adapter orchestration
-- Queue integration for scheduled sends
+- Queue integration for scheduled sends (requires queue adapter)
 - Lifecycle hooks (onSendStarted, onSendSuccess, onSendError)
 - Error handling and normalization
+- Telemetry emission via `IgniterMailTelemetryEvents`
 
 **Key Invariants:**
 - All templates must have a `subject`, `schema`, and `render` function
@@ -155,18 +161,21 @@ Adapters **must**:
 
 ### Testing Strategy
 
-**Unit Tests** (`igniter-mail.spec.ts`):
-- Use `TestMailAdapter` for isolated core testing
+**Unit Tests** (`src/core/manager.spec.tsx`):
+- Use `MockMailAdapter` for isolated core testing
 - Test template validation (valid and invalid schemas)
 - Test hooks lifecycle (started, success, error)
-- Test queue integration (enqueue vs immediate send)
+- Test queue integration (enqueue)
 
-**Adapter Tests** (`adapters.spec.ts`):
-- Test each adapter's builder and configuration
+**Adapter Tests** (`src/adapters/*.spec.ts`):
+- Test mock adapter tracking behavior
 - Mock provider APIs
 - Test error handling
 
-**Type Tests** (future):
+**Builder Tests** (`src/builders/*.spec.ts`):
+- Test chaining, hooks, and template builder validation
+
+**Type Tests** (in manager spec):
 - Verify template key type inference
 - Verify payload type inference
 - Verify builder fluent API type safety
@@ -230,7 +239,7 @@ npm run test
 npm run test:watch
 
 # Run specific test file
-npm run test -- igniter-mail.spec.ts
+npm run test -- src/core/manager.spec.tsx
 ```
 
 ### Building
@@ -271,10 +280,10 @@ While the package doesn't directly read environment variables, adapters typicall
 - `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
+- Uses a connection URL passed via adapter credentials (e.g., `smtps://user:pass@host:465`)
+
+**Validation:**
+- Supports any validation library that implements `StandardSchemaV1` (Zod 3.23+ or compatible)
 
 ---
 
@@ -327,6 +336,7 @@ npm publish --access public
 | `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_QUEUE_NOT_CONFIGURED` | Queue adapter is required |
 | `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 |
@@ -352,11 +362,14 @@ By design, this package does NOT:
 | File | Purpose |
 |------|---------|
 | `src/index.ts` | Public exports |
-| `src/core/igniter-mail.tsx` | Core runtime logic |
-| `src/builders/igniter-mail.builder.ts` | Builder API |
+| `src/core/manager.tsx` | Core runtime logic |
+| `src/builders/main.builder.ts` | Builder API |
+| `src/builders/template.builder.ts` | Template builder |
 | `src/adapters/*.adapter.ts` | Provider adapters |
+| `src/telemetry/index.ts` | Telemetry events |
+| `src/shim.ts` | Browser/client shim |
 | `src/types/*.ts` | Public types |
-| `src/errors/*.ts` | Error classes |
+| `src/errors/mail.error.ts` | Error classes |
 
 ### Key Commands
 
@@ -387,7 +400,7 @@ When working on this package:
 ### 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)
+- Multiple adapters (Resend, Postmark, SendGrid, SMTP) and mock adapter for tests
 - Queue integration for scheduled sends
 - Lifecycle hooks
 - Builder pattern API

package/CHANGELOG.md

@@ -5,13 +5,13 @@ 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
+## [0.1.1] - 2025-12-22
 
-### 🎉 Initial Release
+### Initial Release
 
 First public release of `@igniter-js/mail` - a type-safe email library for Igniter.js with React Email templates.
 
-### ✨ Features
+### Features
 
 #### Core Functionality
 - **Type-Safe Templates** - Full TypeScript support with compile-time inference
@@ -33,8 +33,7 @@ First public release of `@igniter-js/mail` - a type-safe email library for Ignit
 - **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
+- **Mock Adapter** - In-memory adapter for unit tests
 
 #### Developer Experience
 - **Comprehensive Error Handling** - Typed `IgniterMailError` with stable error codes
@@ -49,14 +48,14 @@ First public release of `@igniter-js/mail` - a type-safe email library for Ignit
 - **Hook System** - Extensible hooks for monitoring and analytics
 - **Legacy API Support** - Backwards compatibility with older initialization
 
-### 📦 Package Configuration
+### Package Configuration
 - ESM and CJS exports
 - TypeScript declaration files
 - Tree-shakeable exports
 - Peer dependencies for adapters (optional)
 - Source maps included
 
-### 📚 Documentation
+### Documentation
 - Comprehensive README with examples
 - API reference documentation
 - Adapter configuration guides
@@ -65,7 +64,7 @@ First public release of `@igniter-js/mail` - a type-safe email library for Ignit
 - Type inference guide
 - AGENTS.md for AI agent development
 
-### 🧪 Testing
+### Testing
 - Unit tests for core functionality
 - Adapter-specific tests
 - Template validation tests

package/README.md

@@ -9,8 +9,10 @@ Type-safe email library for Igniter.js applications with React Email templates a
 
 - ✅ **Type-Safe Templates** - Full TypeScript inference with template payload validation
 - ✅ **React Email** - Build beautiful emails with React components
-- ✅ **Multiple Providers** - Resend, Postmark, SendGrid, SMTP, Webhook
-- ✅ **Schema Validation** - Runtime validation with StandardSchema support
+- ✅ **Multiple Providers** - Resend, Postmark, SendGrid, SMTP
+- ✅ **Mock Adapter** - In-memory adapter for unit testing
+- ✅ **Schema Validation** - Runtime validation with StandardSchema (Zod 3.23+ or any StandardSchemaV1-compatible lib)
+- ✅ **Telemetry Ready** - Optional integration with `@igniter-js/telemetry`
 - ✅ **Queue Integration** - Schedule emails with BullMQ or custom queues
 - ✅ **Lifecycle Hooks** - React to send events (started, success, error)
 - ✅ **Builder Pattern** - Fluent API for configuration
@@ -41,19 +43,21 @@ Install the adapter you need:
 npm install resend
 ```
 
-**Postmark:**
+**SMTP:**
 ```bash
-npm install postmark
+npm install nodemailer @types/nodemailer
 ```
 
-**SendGrid:**
+### Optional Dependencies
+
+**Telemetry:**
 ```bash
-npm install sendgrid
+npm install @igniter-js/telemetry
 ```
 
-**SMTP:**
+**Validation (StandardSchemaV1-compatible):**
 ```bash
-npm install nodemailer @types/nodemailer
+npm install zod
 ```
 
 ## Quick Start
@@ -117,7 +121,7 @@ await mail.send({
   },
 })
 
-// Schedule for later
+// Schedule for later (requires withQueue configured)
 await mail.schedule(
   {
     to: 'user@example.com',
@@ -143,7 +147,7 @@ import { z } from 'zod'
 
 const mail = IgniterMail.create()
   .withFrom('no-reply@example.com')
-  .withAdapter('resend', process.env.RESEND_API_KEY!)
+  .withAdapter('resend', process.env.IGNITER_MAIL_SECRET!)
   .addTemplate('resetPassword', {
     subject: 'Reset Your Password',
     schema: z.object({
@@ -197,7 +201,7 @@ await mail.send({
 
 ### Schema Validation
 
-Templates support StandardSchema for runtime validation:
+Templates support StandardSchemaV1 for runtime validation (Zod 3.23+ or any compatible library):
 
 ```typescript
 import { z } from 'zod'
@@ -269,8 +273,6 @@ const mail = IgniterMail.create()
 ### Postmark
 
 ```typescript
-import { PostmarkMailAdapterBuilder } from '@igniter-js/mail'
-
 const mail = IgniterMail.create()
   .withFrom('no-reply@example.com')
   .withAdapter('postmark', process.env.POSTMARK_SERVER_TOKEN!)
@@ -303,25 +305,14 @@ const mail = IgniterMail.create()
   .build()
 ```
 
-### Webhook
-
-For testing or custom integrations:
-
-```typescript
-const mail = IgniterMail.create()
-  .withFrom('no-reply@example.com')
-  .withAdapter('webhook', 'https://webhook.site/your-unique-url')
-  .build()
-```
-
-### Test Adapter
+### Mock Adapter
 
 For unit tests:
 
 ```typescript
-import { TestMailAdapter } from '@igniter-js/mail'
+import { MockMailAdapter } from '@igniter-js/mail/adapters'
 
-const adapter = new TestMailAdapter()
+const adapter = MockMailAdapter.create()
 
 const mail = IgniterMail.create()
   .withFrom('no-reply@example.com')
@@ -356,8 +347,8 @@ const mail = IgniterMail.create()
   .withFrom('no-reply@example.com')
   .withAdapter('resend', process.env.RESEND_API_KEY!)
   .withQueue(queueAdapter, {
-    namespace: 'mail',
-    task: 'send',
+    queue: 'mail',
+    job: 'send',
     attempts: 3,
     removeOnComplete: true,
   })
@@ -383,20 +374,39 @@ React to email sending events:
 const mail = IgniterMail.create()
   .withFrom('no-reply@example.com')
   .withAdapter('resend', process.env.RESEND_API_KEY!)
-  .withOnSendStarted(async (params) => {
+  .onSendStarted(async (params) => {
     console.log('Starting to send email:', params.template)
   })
-  .withOnSendSuccess(async (params) => {
+  .onSendSuccess(async (params) => {
     console.log('Email sent successfully:', params.template)
     // Log to analytics, update database, etc.
   })
-  .withOnSendError(async (params, error) => {
+  .onSendError(async (params, error) => {
     console.error('Failed to send email:', error)
     // Log error, send alert, etc.
   })
   .build()
 ```
 
+## Telemetry Integration
+
+Use `@igniter-js/telemetry` to capture mail events with a typed schema:
+
+```typescript
+import { IgniterTelemetry } from '@igniter-js/telemetry'
+import { IgniterMailTelemetryEvents } from '@igniter-js/mail/telemetry'
+
+const telemetry = IgniterTelemetry.create()
+  .withService('my-api')
+  .addEvents(IgniterMailTelemetryEvents)
+  .build()
+
+const mail = IgniterMail.create()
+  .withTelemetry(telemetry)
+  // ...
+  .build()
+```
+
 ## API Reference
 
 ### IgniterMail
@@ -420,7 +430,7 @@ await mail.send({
 
 ##### `schedule(params, date)`
 
-Schedules an email for a future date. Uses queue if configured, otherwise `setTimeout`.
+Schedules an email for a future date. Requires a queue adapter.
 
 ```typescript
 await mail.schedule(
@@ -482,8 +492,8 @@ Enables queue-based delivery.
 
 ```typescript
 builder.withQueue(queueAdapter, {
-  namespace: 'mail',
-  task: 'send',
+  queue: 'mail',
+  job: 'send',
   attempts: 3,
 })
 ```
@@ -500,32 +510,32 @@ builder.addTemplate('welcome', {
 })
 ```
 
-##### `withOnSendStarted(hook)`
+##### `onSendStarted(hook)`
 
 Registers a hook for send start events.
 
 ```typescript
-builder.withOnSendStarted(async (params) => {
+builder.onSendStarted(async (params) => {
   console.log('Sending:', params.template)
 })
 ```
 
-##### `withOnSendSuccess(hook)`
+##### `onSendSuccess(hook)`
 
 Registers a hook for send success events.
 
 ```typescript
-builder.withOnSendSuccess(async (params) => {
+builder.onSendSuccess(async (params) => {
   console.log('Sent:', params.template)
 })
 ```
 
-##### `withOnSendError(hook)`
+##### `onSendError(hook)`
 
 Registers a hook for send error events.
 
 ```typescript
-builder.withOnSendError(async (params, error) => {
+builder.onSendError(async (params, error) => {
   console.error('Failed:', error)
 })
 ```
@@ -560,6 +570,7 @@ try {
 - `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_QUEUE_NOT_CONFIGURED` - Queue adapter is required for scheduling
 - `MAIL_PROVIDER_SCHEDULE_FAILED` - Failed to schedule email
 - `MAIL_ADAPTER_CONFIGURATION_INVALID` - Adapter configuration error
 
@@ -591,7 +602,7 @@ type SendInput = typeof mail.$Infer.SendInput // Union of all send params
 2. **Use Schema Validation** - Always provide schemas for runtime safety
 3. **Leverage Hooks** - Use hooks for logging, analytics, and error tracking
 4. **Queue Heavy Loads** - Use queue integration for high-volume sending
-5. **Test Adapter First** - Use TestAdapter in unit tests before deploying
+5. **Mock Adapter First** - Use MockMailAdapter in unit tests before deploying
 6. **Environment Variables** - Store API keys and secrets in environment variables
 7. **Preview Emails** - Use React Email's preview feature during development
 
@@ -649,8 +660,8 @@ const mail = IgniterMail.create()
   .withFrom('orders@example.com')
   .withAdapter('postmark', process.env.POSTMARK_TOKEN!)
   .withQueue(queueAdapter, {
-    namespace: 'mail',
-    task: 'send',
+    queue: 'mail',
+    job: 'send',
     attempts: 5,
     priority: 10,
   })

package/dist/adapter-BhnIsrlh.d.mts

@@ -0,0 +1,60 @@
+/**
+ * Parameters used by a mail adapter to send an email.
+ *
+ * @example
+ * ```ts
+ * await adapter.send({
+ *   to: 'user@example.com',
+ *   subject: 'Welcome',
+ *   html: '<p>Hello</p>',
+ *   text: 'Hello',
+ * })
+ * ```
+ */
+interface IgniterMailAdapterSendParams {
+    /** Recipient email address. */
+    to: string;
+    /** Email subject. */
+    subject: string;
+    /** HTML body. */
+    html: string;
+    /** Plain-text body. */
+    text: string;
+    /** Optional provider-level scheduled send date. */
+    scheduledAt?: Date;
+}
+/**
+ * Credentials required by mail adapters.
+ *
+ * @example
+ * ```ts
+ * const credentials = { secret: process.env.RESEND_API_KEY, from: 'no-reply@acme.com' }
+ * ```
+ */
+interface IgniterMailAdapterCredentials {
+    /** Provider secret, token, or connection URL. */
+    secret?: string;
+    /** Default FROM address used by the provider. */
+    from?: string;
+}
+/**
+ * Adapter interface used by {@link IgniterMail}.
+ *
+ * Adapters will eventually be imported from `@igniter-js/mail/adapters`.
+ */
+interface IgniterMailAdapter {
+    /**
+     * Sends an email using the underlying provider.
+     *
+     * @param params - Normalized send parameters.
+     * @returns A promise that resolves when the provider accepts the email.
+     * @throws IgniterMailError When configuration is invalid or provider call fails.
+     * @example
+     * ```ts
+     * await adapter.send({ to: 'a@b.com', subject: 'Hi', html: '<p>x</p>', text: 'x' })
+     * ```
+     */
+    send: (params: IgniterMailAdapterSendParams) => Promise<void>;
+}
+
+export type { IgniterMailAdapter as I, IgniterMailAdapterSendParams as a, IgniterMailAdapterCredentials as b };

package/dist/adapter-BhnIsrlh.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Parameters used by a mail adapter to send an email.
+ *
+ * @example
+ * ```ts
+ * await adapter.send({
+ *   to: 'user@example.com',
+ *   subject: 'Welcome',
+ *   html: '<p>Hello</p>',
+ *   text: 'Hello',
+ * })
+ * ```
+ */
+interface IgniterMailAdapterSendParams {
+    /** Recipient email address. */
+    to: string;
+    /** Email subject. */
+    subject: string;
+    /** HTML body. */
+    html: string;
+    /** Plain-text body. */
+    text: string;
+    /** Optional provider-level scheduled send date. */
+    scheduledAt?: Date;
+}
+/**
+ * Credentials required by mail adapters.
+ *
+ * @example
+ * ```ts
+ * const credentials = { secret: process.env.RESEND_API_KEY, from: 'no-reply@acme.com' }
+ * ```
+ */
+interface IgniterMailAdapterCredentials {
+    /** Provider secret, token, or connection URL. */
+    secret?: string;
+    /** Default FROM address used by the provider. */
+    from?: string;
+}
+/**
+ * Adapter interface used by {@link IgniterMail}.
+ *
+ * Adapters will eventually be imported from `@igniter-js/mail/adapters`.
+ */
+interface IgniterMailAdapter {
+    /**
+     * Sends an email using the underlying provider.
+     *
+     * @param params - Normalized send parameters.
+     * @returns A promise that resolves when the provider accepts the email.
+     * @throws IgniterMailError When configuration is invalid or provider call fails.
+     * @example
+     * ```ts
+     * await adapter.send({ to: 'a@b.com', subject: 'Hi', html: '<p>x</p>', text: 'x' })
+     * ```
+     */
+    send: (params: IgniterMailAdapterSendParams) => Promise<void>;
+}
+
+export type { IgniterMailAdapter as I, IgniterMailAdapterSendParams as a, IgniterMailAdapterCredentials as b };