@mostajs/notifications 0.1.0

package/README.md

@@ -0,0 +1,444 @@
+# @mostajs/notifications
+
+**Auteur** : Dr Hamid MADANI <drmdh@msn.com>
+**License** : AGPL-3.0-or-later
+**Version** : 0.1.0
+
+Moteur **générique** de notifications pour l'écosystème `@mostajs/*` — découple le **dispatch** (mailer + i18n + templating + idempotence) du **domaine métier** (booking, media-sfu, custom apps). Tout domaine peut envoyer des notifications en appelant `engine.notify(kind, context)` ; les adapters spécifiques (`@mostajs/booking-notifications`, `@mostajs/media-sfu-notifications`, …) sont de fins glues qui mappent leurs events internes en kinds génériques.
+
+📊 **Étude état de l'art** (Knock, Courier, Novu, SendGrid, Postmark, Resend, Customer.io, …) → [`docs/STATE-OF-THE-ART.md`](./docs/STATE-OF-THE-ART.md)
+
+---
+
+## Table des matières
+
+1. [Pourquoi un moteur générique](#1-pourquoi-un-moteur-générique)
+2. [Architecture](#2-architecture)
+3. [Quick start — how to use](#3-quick-start--how-to-use)
+4. [API détaillée](#4-api-détaillée)
+5. [Templates — patterns recommandés](#5-templates--patterns-recommandés)
+6. [Implémentation — how to impl](#6-implémentation--how-to-impl)
+7. [I18n & locales](#7-i18n--locales)
+8. [Idempotence](#8-idempotence)
+9. [Tests](#9-tests)
+10. [Modules liés](#10-modules-liés)
+
+---
+
+## 1. Pourquoi un moteur générique
+
+Avant ce module, chaque domaine `@mostajs/*` qui voulait envoyer un mail dupliquait :
+- Templates locale (FR / EN / AR)
+- Dispatch via `@mostajs/mailer`
+- Idempotence (`messageId`)
+- Retry / fallback / callbacks
+
+Avec ce module :
+- `@mostajs/booking-notifications` : 100 LOC de glue (subscribe events booking → notify)
+- `@mostajs/media-sfu-notifications` (futur) : 80 LOC de glue (subscribe events SFU → notify)
+- `@mostajs/orphan-care-notifications` (futur) : idem
+- Plomberie commune (templates registry, mailer, i18n, idempotence) : **un seul code à maintenir**
+
+Cas où ne PAS utiliser ce module :
+- App très simple avec 1 seul mail à envoyer → utilise `@mostajs/mailer` directement
+- Domaine très spécifique avec templates DB-driven (CMS-like) → roll your own avec `@mostajs/mailer`
+
+---
+
+## 2. Architecture
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│  App / Adapter consumer                                       │
+│   - subscribe events @mostajs/booking, @mostajs/media-sfu, … │
+│   - map event → { kind: 'booking.reservation.created',       │
+│                    context: { reservation, slot, ... } }     │
+│   - appelle engine.notify(...)                                │
+└──────────────────────────────────┬───────────────────────────┘
+                                   │
+                                   ▼
+┌──────────────────────────────────────────────────────────────┐
+│  @mostajs/notifications  — NotificationEngine                 │
+│                                                              │
+│   ┌──────────────────┐   ┌──────────────────┐                │
+│   │ Templates        │   │ Locale picker    │                │
+│   │ registry         │ ◀─│ ctx.locale →     │                │
+│   │ (kind → tpl)     │   │ variant FR/EN/AR │                │
+│   └────────┬─────────┘   └──────────────────┘                │
+│            ▼                                                  │
+│   ┌──────────────────┐   ┌──────────────────┐                │
+│   │ render(ctx)      │ → │ Mail (subject,   │                │
+│   │ → RenderedMail   │   │ to, html, text)  │                │
+│   └────────┬─────────┘   └────────┬─────────┘                │
+│            ▼                       ▼                          │
+│   ┌──────────────────────────────────────────┐               │
+│   │ Idempotence (messageId)                   │               │
+│   │ Callbacks (onSent / onError)              │               │
+│   └────────────────────┬─────────────────────┘               │
+└────────────────────────┼─────────────────────────────────────┘
+                         │
+                         ▼
+┌──────────────────────────────────────────────────────────────┐
+│  @mostajs/mailer  — driver-based dispatch                     │
+│   SMTP / Resend / Postmark / SES / Brevo / Console / Mock     │
+└──────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 3. Quick start — how to use
+
+### Installation
+
+```bash
+npm install @mostajs/notifications @mostajs/mailer
+```
+
+### Bootstrap minimal
+
+```ts
+import { createNotificationEngine, simpleTemplate, localizedTemplate } from '@mostajs/notifications'
+import { createMailer, createConsoleDriver } from '@mostajs/mailer'
+
+const mailer = createMailer({ driver: createConsoleDriver() })
+
+const engine = createNotificationEngine({
+  mailer,
+  defaultFrom: 'noreply@example.com',
+  defaultLocale: 'fr',
+  templates: {
+    'welcome': simpleTemplate({
+      to:      ctx => (ctx.user as any)?.email ?? null,
+      subject: ctx => `Bienvenue ${(ctx.user as any)?.name}`,
+      html:    ctx => `<h1>Bonjour ${(ctx.user as any)?.name}</h1><p>Heureux de vous accueillir !</p>`,
+    }),
+  },
+})
+
+await engine.notify('welcome', {
+  user: { name: 'Amina', email: 'amina@example.com' },
+})
+```
+
+### Template multi-locale (FR + EN + AR)
+
+```ts
+engine.register('appointment.reminder', localizedTemplate({
+  fr: {
+    subject: ctx => `Rappel : votre rendez-vous ${formatDate(ctx.startAt)}`,
+    html:    ctx => `<p>Bonjour, n'oubliez pas votre rendez-vous demain à <strong>${formatDate(ctx.startAt)}</strong>.</p>`,
+  },
+  en: {
+    subject: ctx => `Reminder: your appointment ${formatDate(ctx.startAt)}`,
+    html:    ctx => `<p>Hi, don't forget your appointment tomorrow at <strong>${formatDate(ctx.startAt)}</strong>.</p>`,
+  },
+  ar: {
+    subject: ctx => `تذكير: موعدكم ${formatDate(ctx.startAt)}`,
+    html:    ctx => `<p>تذكير بموعدكم غداً في <strong>${formatDate(ctx.startAt)}</strong>.</p>`,
+  },
+}, ctx => (ctx.user as any)?.email,
+   ctx => `appt-reminder-${(ctx as any).reservationId}-24h`,  // idempotence
+))
+
+// L'app envoie selon la locale du user :
+await engine.notify('appointment.reminder', {
+  user: { email: 'patient@example.com' },
+  startAt: Date.now() + 86400_000,
+  reservationId: 'res-123',
+  locale: 'ar',
+})
+```
+
+### Dans un adapter domain (@mostajs/booking-notifications, etc.)
+
+```ts
+// @mostajs/booking-notifications fait :
+manager.onEvent = async (ev) => {
+  if (ev.type !== 'reservation.created') return
+  const r = await manager.findReservation(ev.reservationId!)
+  const slot = await manager.findSlot(r.slotId)
+  await engine.notify('booking.reservation.created', {
+    reservation: r, slot, locale: r.metadata?.locale,
+  })
+}
+```
+
+---
+
+## 4. API détaillée
+
+### `createNotificationEngine(opts) → NotificationEngine`
+
+```ts
+interface NotificationEngineOptions {
+  mailer: { send: (mail: any) => Promise<{ messageId: string }> }
+  templates?: Record<string, NotificationTemplate>
+  defaultLocale?: string
+  defaultFrom?: string
+  disabled?: string[]
+  onSent?:  (kind, context, result) => void | Promise<void>
+  onError?: (kind, context, error)  => void | Promise<void>
+}
+
+interface NotificationEngine {
+  register(kind: string, template: NotificationTemplate): void
+  unregister(kind: string): void
+  registeredKinds(): string[]
+  setEnabled(kind: string, enabled: boolean): void
+
+  notify(kind: string, context: NotificationContext): Promise<{ messageId: string } | null>
+  notifyBatch(items: Array<{ kind, context }>): Promise<Array<{ messageId: string } | null>>
+}
+```
+
+### `NotificationTemplate`
+
+```ts
+interface NotificationTemplate {
+  render(context: NotificationContext): Promise<RenderedMail | null> | RenderedMail | null
+}
+
+interface RenderedMail {
+  to: string                 // requis (sinon skip)
+  cc?: string | string[]
+  bcc?: string | string[]
+  from?: string              // override defaultFrom
+  subject: string
+  text?: string
+  html?: string
+  messageId?: string         // idempotence (mailer skip si déjà sent)
+  metadata?: Record<string, unknown>
+}
+```
+
+### Helpers
+
+- `simpleTemplate({ to, subject, text?, html?, messageId? })` — factory function-based
+- `localizedTemplate(variants, resolveTo, resolveMessageId?)` — multi-locale avec fallback fr → en
+
+---
+
+## 5. Templates — patterns recommandés
+
+### Pattern 1 — Templates inline (mini app)
+
+```ts
+templates: {
+  'welcome': simpleTemplate({
+    to: ctx => (ctx.user as any).email,
+    subject: () => 'Bienvenue',
+    html: ctx => `<h1>Hello ${(ctx.user as any).name}</h1>`,
+  }),
+}
+```
+
+### Pattern 2 — Templates dans des fichiers séparés
+
+```
+my-app/
+├── lib/
+│   └── notifications.ts        ← createNotificationEngine + register
+└── templates/
+    ├── welcome.ts
+    ├── booking-created.ts
+    └── ...
+```
+
+```ts
+// templates/welcome.ts
+import { localizedTemplate } from '@mostajs/notifications'
+export const welcomeTemplate = localizedTemplate({
+  fr: { subject: 'Bienvenue', html: ctx => `<h1>Hello ${(ctx.user as any).name}</h1>` },
+  en: { subject: 'Welcome',   html: ctx => `<h1>Hello ${(ctx.user as any).name}</h1>` },
+}, ctx => (ctx.user as any).email)
+```
+
+```ts
+// lib/notifications.ts
+import { welcomeTemplate } from '../templates/welcome.js'
+const engine = createNotificationEngine({ mailer, templates: { welcome: welcomeTemplate } })
+```
+
+### Pattern 3 — Templates DB-driven (CMS)
+
+Pour permettre à des non-devs d'éditer les templates :
+
+```ts
+const engine = createNotificationEngine({ mailer })
+
+async function loadTemplates() {
+  const rows = await db.select().from('notification_templates')
+  for (const row of rows) {
+    engine.register(row.kind, simpleTemplate({
+      to: ctx => evalExpr(row.toExpr, ctx),
+      subject: ctx => interpolate(row.subject, ctx),
+      html: ctx => interpolate(row.htmlBody, ctx),
+    }))
+  }
+}
+
+await loadTemplates()
+db.on('change:notification_templates', loadTemplates)  // hot-reload
+```
+
+### Pattern 4 — Moteur de template externe (Handlebars, EJS)
+
+```ts
+import Handlebars from 'handlebars'
+
+const subjectTpl = Handlebars.compile('Rappel : {{appointmentName}} le {{startAt}}')
+const htmlTpl    = Handlebars.compile(htmlTemplate)
+
+engine.register('reminder', simpleTemplate({
+  to:      ctx => (ctx.user as any).email,
+  subject: ctx => subjectTpl(ctx),
+  html:    ctx => htmlTpl(ctx),
+}))
+```
+
+---
+
+## 6. Implémentation — how to impl
+
+### Adapter pour un domaine (pattern type)
+
+```ts
+// my-domain-notifications.ts
+import type { NotificationEngine } from '@mostajs/notifications'
+import { localizedTemplate } from '@mostajs/notifications'
+import type { MyManager, MyEvent } from '@mostajs/my-domain'
+
+export function createMyDomainNotifications(opts: {
+  engine: NotificationEngine
+  manager: MyManager
+  /** Prefix pour les kinds : 'my-domain' → 'my-domain.event-x'. Default = nom du domain. */
+  kindPrefix?: string
+}) {
+  const prefix = opts.kindPrefix ?? 'my-domain'
+
+  // 1. Enregistrer les templates par défaut du domaine
+  opts.engine.register(`${prefix}.welcome`, localizedTemplate({
+    fr: { subject: 'Bienvenue dans mon domaine', html: ctx => `...` },
+    en: { subject: 'Welcome',                    html: ctx => `...` },
+  }, ctx => (ctx.entity as any)?.email))
+
+  // 2. Subscribe aux events du manager → notify
+  opts.manager.onEvent = async (ev: MyEvent) => {
+    switch (ev.type) {
+      case 'entity.created':
+        const e = await opts.manager.findEntity(ev.entityId!)
+        await opts.engine.notify(`${prefix}.welcome`, { entity: e, locale: e.locale })
+        break
+      // ...
+    }
+  }
+
+  return {
+    /** Permet à l'app d'override les templates par défaut. */
+    setTemplate(kind: string, template: NotificationTemplate) {
+      opts.engine.register(`${prefix}.${kind}`, template)
+    },
+  }
+}
+```
+
+### Routes admin (Next.js)
+
+```ts
+// app/api/admin/notifications/test/route.ts
+import { engine } from '@/lib/notifications'
+
+export async function POST(req: Request) {
+  const { kind, context } = await req.json()
+  const result = await engine.notify(kind, context)
+  return Response.json({ sent: !!result, messageId: result?.messageId })
+}
+
+// app/api/admin/notifications/kinds/route.ts
+export async function GET() {
+  return Response.json({ kinds: engine.registeredKinds() })
+}
+```
+
+---
+
+## 7. I18n & locales
+
+Le `context.locale` détermine quel template variant est choisi. Helper `localizedTemplate(variants, ...)` :
+- Cherche `variants[locale]` (ex. `fr-DZ`)
+- Fallback sur `variants[locale.split('-')[0]]` (ex. `fr`)
+- Fallback final sur `variants.fr` puis `variants.en`
+
+**Résolution de la locale** : c'est à l'app de mettre `ctx.locale` (depuis `user.locale` DB, `Accept-Language` header, ou subdomain `fr.app.com`).
+
+```ts
+await engine.notify('reminder', {
+  user: u,
+  locale: u.locale ?? extractFromHeaders(req) ?? 'fr',
+})
+```
+
+---
+
+## 8. Idempotence
+
+Pour éviter d'envoyer **2× le même reminder 24h** si un cron retrigger :
+- Le template doit fournir un `messageId` déterministe : `reminder-24h-${reservation.id}`
+- `@mostajs/mailer` (Phase 2 MailLog) persistera ce messageId en DB → 2e send avec même ID = no-op silencieux
+
+```ts
+localizedTemplate(
+  { fr: { subject: 'Rappel', html: ... } },
+  ctx => (ctx.user as any).email,
+  ctx => `reminder-24h-${(ctx.reservation as any).id}`,   // messageId
+)
+```
+
+---
+
+## 9. Tests
+
+```ts
+// tests/engine.test.ts
+import { createNotificationEngine, simpleTemplate } from '@mostajs/notifications'
+
+describe('NotificationEngine', () => {
+  it('dispatch template registered', async () => {
+    const sent: any[] = []
+    const mailer = { send: async (m: any) => { sent.push(m); return { messageId: 'x-1' } } }
+    const engine = createNotificationEngine({ mailer })
+    engine.register('welcome', simpleTemplate({
+      to:      _ => 'user@x.com',
+      subject: _ => 'Hello',
+      text:    _ => 'Welcome!',
+    }))
+
+    const r = await engine.notify('welcome', { user: 'x' })
+    expect(r?.messageId).toBe('x-1')
+    expect(sent[0]).toMatchObject({ to: 'user@x.com', subject: 'Hello' })
+  })
+
+  it('skip if template absent', async () => {
+    const engine = createNotificationEngine({ mailer: { send: async () => ({ messageId: '' }) } })
+    expect(await engine.notify('unknown', {})).toBeNull()
+  })
+
+  it('locale fallback', async () => {
+    // ... test localizedTemplate avec variant manquante
+  })
+})
+```
+
+---
+
+## 10. Modules liés
+
+- [`@mostajs/mailer`](../mosta-mailer) — peer dep, dispatch SMTP/Resend/SES/etc.
+- [`@mostajs/booking-notifications`](../mosta-booking-stack/mosta-booking-notifications) — adapter booking events → notifications
+- (futur) `@mostajs/media-sfu-notifications` — adapter SFU events
+- [`@mostajs/url`](../mosta-url) — pour construire des liens dans les templates (`signedUrl` pour invite tokens)
+
+---
+
+**License** : AGPL-3.0-or-later
+**Auteur** : Dr Hamid MADANI <drmdh@msn.com>

package/dist/index.d.ts

@@ -0,0 +1,98 @@
+export type Locale = string;
+export interface NotificationContext {
+    /** Locale du destinataire — détermine quel template variant utiliser. */
+    locale?: Locale;
+    /** Champs libres consommés par le template (reservation, slot, session, etc.). */
+    [key: string]: unknown;
+}
+export interface RenderedMail {
+    to: string;
+    cc?: string | string[];
+    bcc?: string | string[];
+    from?: string;
+    subject: string;
+    text?: string;
+    html?: string;
+    /** Idempotence : mailer skip si déjà sent avec ce messageId. */
+    messageId?: string;
+    /** Metadata libre persistée dans MailLog. */
+    metadata?: Record<string, unknown>;
+}
+/** Template = fonction qui produit un Mail à partir du contexte.
+ *  Retour null → skip (template applicable mais l'app a décidé de pas envoyer). */
+export interface NotificationTemplate {
+    render(context: NotificationContext): Promise<RenderedMail | null> | RenderedMail | null;
+}
+export interface NotificationEngineOptions {
+    /** Instance @mostajs/mailer (ou compatible : tout objet avec `.send(mail)`). */
+    mailer: {
+        send: (mail: any) => Promise<{
+            messageId: string;
+        }>;
+    };
+    /** Templates initialement enregistrés (kind → template). */
+    templates?: Record<string, NotificationTemplate>;
+    /** Locale par défaut si le contexte n'en spécifie pas. */
+    defaultLocale?: Locale;
+    /** Default `from` (peut être overridé par chaque template). */
+    defaultFrom?: string;
+    /** Désactive certains kinds (e.g. mode dégradé). */
+    disabled?: string[];
+    /** Callback succès. */
+    onSent?: (kind: string, context: NotificationContext, result: {
+        messageId: string;
+    }) => void | Promise<void>;
+    /** Callback erreur. */
+    onError?: (kind: string, context: NotificationContext, error: Error) => void | Promise<void>;
+}
+export interface NotificationEngine {
+    /** Enregistre / override un template. */
+    register(kind: string, template: NotificationTemplate): void;
+    /** Retire un template. */
+    unregister(kind: string): void;
+    /** Liste les kinds enregistrés. */
+    registeredKinds(): string[];
+    /** Désactive ou réactive un kind sans le supprimer. */
+    setEnabled(kind: string, enabled: boolean): void;
+    /** Notifie : render + dispatch via mailer. Retourne le résultat (null = skipped). */
+    notify(kind: string, context: NotificationContext): Promise<{
+        messageId: string;
+    } | null>;
+    /** Notifie en parallèle plusieurs (kind, context). */
+    notifyBatch(items: Array<{
+        kind: string;
+        context: NotificationContext;
+    }>): Promise<Array<{
+        messageId: string;
+    } | null>>;
+}
+export declare function createNotificationEngine(opts: NotificationEngineOptions): NotificationEngine;
+/**
+ * Template simple — function-based. Pas de moteur de template (pas de mustache,
+ * pas de handlebars). L'app peut construire ses chaines manuellement OU importer
+ * son moteur préféré (ejs, handlebars, etc.) et le wraper dans cette interface.
+ */
+export declare function simpleTemplate(spec: {
+    to: (ctx: NotificationContext) => string | null;
+    subject: (ctx: NotificationContext) => string;
+    text?: (ctx: NotificationContext) => string;
+    html?: (ctx: NotificationContext) => string;
+    messageId?: (ctx: NotificationContext) => string;
+}): NotificationTemplate;
+/**
+ * Template multi-locale : utilise `ctx.locale` pour choisir la variant.
+ * Si la locale n'est pas dans les variants, fallback sur 'fr' puis 'en'.
+ */
+export declare function localizedTemplate(variants: {
+    [locale: string]: {
+        subject: string | ((ctx: NotificationContext) => string);
+        text?: string | ((ctx: NotificationContext) => string);
+        html?: string | ((ctx: NotificationContext) => string);
+    };
+}, resolveTo: (ctx: NotificationContext) => string | null, resolveMessageId?: (ctx: NotificationContext) => string): NotificationTemplate;
+export declare const moduleInfo: {
+    name: string;
+    version: string;
+    scope: string;
+};
+//# 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":"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"}

package/dist/index.js

@@ -0,0 +1,118 @@
+// @mostajs/notifications — Generic notification engine
+// Author: Dr Hamid MADANI <drmdh@msn.com>
+//
+// Domain-agnostic : accepte n'importe quel `kind: string` (namespacé par convention
+// `<domain>.<event>` : 'booking.reservation.created', 'media.session.started', etc.)
+// et n'importe quel `context: Record<string, unknown>`. Les adapters spécifiques
+// (booking-notifications, media-sfu-notifications) traduisent leurs events
+// internes en `kind + context` et appellent `engine.notify(...)`.
+// ─── Engine ────────────────────────────────────────────────────────────
+export function createNotificationEngine(opts) {
+    const templates = new Map(Object.entries(opts.templates ?? {}));
+    const disabled = new Set(opts.disabled ?? []);
+    const defaultLocale = opts.defaultLocale ?? 'fr';
+    async function doNotify(kind, context) {
+        if (disabled.has(kind))
+            return null;
+        const tpl = templates.get(kind);
+        if (!tpl)
+            return null;
+        const ctx = { ...context, locale: context.locale ?? defaultLocale };
+        let rendered;
+        try {
+            rendered = await Promise.resolve(tpl.render(ctx));
+        }
+        catch (e) {
+            await Promise.resolve(opts.onError?.(kind, ctx, e));
+            return null;
+        }
+        if (!rendered)
+            return null;
+        if (!rendered.to) {
+            await Promise.resolve(opts.onError?.(kind, ctx, new Error('Template returned no `to` address')));
+            return null;
+        }
+        const mail = {
+            ...rendered,
+            from: rendered.from ?? opts.defaultFrom,
+            metadata: { ...(rendered.metadata ?? {}), kind, locale: ctx.locale },
+        };
+        try {
+            const result = await opts.mailer.send(mail);
+            await Promise.resolve(opts.onSent?.(kind, ctx, result));
+            return result;
+        }
+        catch (e) {
+            await Promise.resolve(opts.onError?.(kind, ctx, e));
+            return null;
+        }
+    }
+    return {
+        register(kind, template) { templates.set(kind, template); },
+        unregister(kind) { templates.delete(kind); },
+        registeredKinds() { return Array.from(templates.keys()); },
+        setEnabled(kind, enabled) {
+            if (enabled)
+                disabled.delete(kind);
+            else
+                disabled.add(kind);
+        },
+        notify: doNotify,
+        async notifyBatch(items) {
+            return Promise.all(items.map(it => doNotify(it.kind, it.context)));
+        },
+    };
+}
+// ─── Built-in template helpers ─────────────────────────────────────────
+/**
+ * Template simple — function-based. Pas de moteur de template (pas de mustache,
+ * pas de handlebars). L'app peut construire ses chaines manuellement OU importer
+ * son moteur préféré (ejs, handlebars, etc.) et le wraper dans cette interface.
+ */
+export function simpleTemplate(spec) {
+    return {
+        render(ctx) {
+            const to = spec.to(ctx);
+            if (!to)
+                return null;
+            return {
+                to,
+                subject: spec.subject(ctx),
+                text: spec.text?.(ctx),
+                html: spec.html?.(ctx),
+                messageId: spec.messageId?.(ctx),
+            };
+        },
+    };
+}
+/**
+ * Template multi-locale : utilise `ctx.locale` pour choisir la variant.
+ * Si la locale n'est pas dans les variants, fallback sur 'fr' puis 'en'.
+ */
+export function localizedTemplate(variants, resolveTo, resolveMessageId) {
+    return {
+        render(ctx) {
+            const to = resolveTo(ctx);
+            if (!to)
+                return null;
+            const loc = ctx.locale ?? 'fr';
+            const v = variants[loc] ?? variants[loc.split('-')[0]] ?? variants.fr ?? variants.en;
+            if (!v)
+                return null;
+            const resolve = (s) => typeof s === 'function' ? s(ctx) : s;
+            return {
+                to,
+                subject: resolve(v.subject),
+                text: resolve(v.text),
+                html: resolve(v.html),
+                messageId: resolveMessageId?.(ctx),
+            };
+        },
+    };
+}
+export const moduleInfo = {
+    name: '@mostajs/notifications',
+    version: '0.1.0',
+    scope: 'Generic notification engine — domain-agnostic templating + mailer dispatch',
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@mostajs/notifications",
+  "version": "0.1.0",
+  "description": "Generic notification engine for @mostajs/* — domain-agnostic templating + i18n + mailer dispatch + idempotence. Consume any event kind from any source (booking, media-sfu, custom apps). Plug-and-play with @mostajs/mailer.",
+  "author": "Dr Hamid MADANI <drmdh@msn.com>",
+  "license": "AGPL-3.0-or-later",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "@mostajs/mailer": "^0.1.1"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "typescript": "^6.0.3"
+  }
+}