@wisemen/nestjs-mail 0.3.0 → 1.1.0

package/skills/getting-started/SKILL.md

@@ -19,18 +19,64 @@ import { MailClient } from '@wisemen/nestjs-mail'
 
 @Injectable()
 export class SendWelcomeMailUseCase {
-  constructor(private readonly mailClient: MailClient) {}
+  constructor (private readonly mailClient: MailClient) {}
 
-  async send(to: string): Promise<void> {
+  async send (to: string): Promise<void> {
     await this.mailClient.sendMail({
+      from: {
+        email: 'welcome@example.com',
+        name: 'Example Team',
+      },
       to,
       subject: 'Welcome',
-      text: 'Welcome to the platform'
+      text: 'Welcome to the platform',
+      metadata: {
+        kind: 'welcome',
+      },
     })
   }
 }
 ```
 
+`from` accepts either a string or `{ email, name? }`. `metadata` is exposed to
+delivery hooks but is never included in provider payloads. Metadata stored in a
+`SendHtmlMailJob` or `SendTemplateMailJob` must be JSON-serializable.
+
+## Observe Deliveries
+
+Configure one hooks object when the application needs to track successful or
+failed delivery attempts without replacing the package client or queue handlers.
+
+```ts
+MailModule.forRootAsync({
+  inject: [ConfigService, DeliveryTracker],
+  useFactory: (config: ConfigService, tracker: DeliveryTracker) => ({
+    client: {
+      type: 'send-grid',
+      apiToken: config.getOrThrow('SENDGRID_API_TOKEN'),
+      defaultFrom: {
+        email: 'hello@example.com',
+        name: 'Example Team',
+      },
+    },
+    queueName: 'mail',
+    deliveryHooks: {
+      async onSuccess ({ clientType, options, sentMails }) {
+        await tracker.sent(clientType, options.metadata, sentMails)
+      },
+      async onFailure ({ clientType, options, error }) {
+        await tracker.failed(clientType, options.metadata, error)
+      },
+    },
+  }),
+})
+```
+
+Hooks run for every configured client type, including MailPit and Mock. Hook
+failures are logged safely and swallowed: a success-hook failure cannot fail the
+job and a failure-hook failure cannot replace the original provider error. This
+prevents hook failures from causing duplicate-email retries.
+
 ## Render Handlebars Templates
 
 Use `HandlebarsRenderer` when the mail body should come from `.hbs` templates in
@@ -43,12 +89,12 @@ import { MailClient } from '@wisemen/nestjs-mail'
 
 @Injectable()
 export class SendTemplateMailUseCase {
-  constructor(
+  constructor (
     private readonly mailClient: MailClient,
     private readonly renderer: HandlebarsRenderer
   ) {}
 
-  async send(to: string, data: Record<string, unknown>): Promise<void> {
+  async send (to: string, data: Record<string, unknown>): Promise<void> {
     const [html, text] = await Promise.all([
       this.renderer.render('mail/templates/welcome.html.hbs', data),
       this.renderer.render('mail/templates/welcome.text.hbs', data)