{"_id":"@amsom-habitat/mailer-sender","name":"@amsom-habitat/mailer-sender","dist-tags":{"latest":"1.0.1"},"versions":{"1.0.1":{"name":"@amsom-habitat/mailer-sender","version":"1.0.1","description":"Connecteur vers l'API Mail interne : envoi par template ou en corps libre, avec garde-fou anti-spam hors production (portage Node du package PHP amsom-habitat/mailer-sender).","keywords":["mail","mailer","api-mail","nestjs","amsom"],"license":"UNLICENSED","author":{"name":"Amsom Habitat"},"repository":{"type":"git","url":"git+https://gitlab.com/amsom-package/mailer-sender-node.git","directory":"package_src"},"main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","require":"./dist/index.js","default":"./dist/index.js"},"./nest":{"types":"./dist/nest/index.d.ts","require":"./dist/nest/index.js","default":"./dist/nest/index.js"}},"engines":{"node":">=18"},"scripts":{"build":"tsc","lint":"eslint","lint:fix":"eslint --fix","test":"jest","prepublishOnly":"npm run build"},"peerDependencies":{"@nestjs/common":"^10.0.0 || ^11.0.0"},"peerDependenciesMeta":{"@nestjs/common":{"optional":true}},"devDependencies":{"@eslint/js":"^9.39.0","@nestjs/common":"^11.1.28","@types/jest":"^30.0.0","@types/node":"^26.1.1","eslint":"^9.39.0","globals":"^15.15.0","jest":"^30.4.2","reflect-metadata":"^0.2.2","rxjs":"^7.8.2","ts-jest":"^29.4.12","typescript":"^5.9.3","typescript-eslint":"^8.65.0"},"_id":"@amsom-habitat/mailer-sender@1.0.1","gitHead":"03e32fac3511bdad44452351ec2ab2d6ae645777","bugs":{"url":"https://gitlab.com/amsom-package/mailer-sender-node/issues"},"homepage":"https://gitlab.com/amsom-package/mailer-sender-node#readme","_nodeVersion":"24.20.0","_npmVersion":"11.5.2","dist":{"integrity":"sha512-s0ZHyBJItyh+nYTiGL55XWzqMjPnSV9D7Sb6m0jwUvpDFjnvJM4ziMFGXX3C+lTTT3EOMLV3SQnAk6r4Z6/6KA==","shasum":"4c7191fbf3d5aace56fcefdf4c94694ffa373356","tarball":"https://registry.npmjs.org/@amsom-habitat/mailer-sender/-/mailer-sender-1.0.1.tgz","fileCount":22,"unpackedSize":38101,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDBLn2/5J/03o9qgyuTpXmrh+9Bq6Wmk/7MSlGzv80EHAIhAMnJxqvqmSiqzAqng7FSW64djKpQ7N/Swdz9QnQ8uiZi"}]},"_npmUser":{"name":"amsom-habitat","email":"dev@amsom-habitat.fr"},"directories":{},"maintainers":[{"name":"amsom-habitat","email":"dev@amsom-habitat.fr"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mailer-sender_1.0.1_1788443271498_0.5128994260887876"},"_hasShrinkwrap":false}},"time":{"created":"2026-09-03T13:47:51.315Z","1.0.1":"2026-09-03T13:47:51.649Z","modified":"2026-09-03T13:47:51.895Z"},"maintainers":[{"name":"amsom-habitat","email":"dev@amsom-habitat.fr"}],"description":"Connecteur vers l'API Mail interne : envoi par template ou en corps libre, avec garde-fou anti-spam hors production (portage Node du package PHP amsom-habitat/mailer-sender).","homepage":"https://gitlab.com/amsom-package/mailer-sender-node#readme","keywords":["mail","mailer","api-mail","nestjs","amsom"],"repository":{"type":"git","url":"git+https://gitlab.com/amsom-package/mailer-sender-node.git","directory":"package_src"},"author":{"name":"Amsom Habitat"},"bugs":{"url":"https://gitlab.com/amsom-package/mailer-sender-node/issues"},"license":"UNLICENSED","readme":"# @amsom-habitat/mailer-sender\n\nConnecteur vers l'**API Mail** interne : envoi par template nommé ou en corps libre, garde-fou anti-spam\nhors production, erreurs typées.\n\nPortage Node du package Composer [`amsom-habitat/mailer-sender`](https://gitlab.com/amsom-package/mailersender).\nLà où la version PHP s'appuyait sur `MailerInterface`/Twig de Symfony, cette version se contente d'appeler\nl'API Mail en HTTP : **aucune dépendance runtime**, `fetch` natif (Node ≥ 18).\n\n## Installation\n\n```sh\nnpm install @amsom-habitat/mailer-sender\n```\n\n`@nestjs/common` est une peerDependency **optionnelle**, requise seulement pour le sous-export `/nest`.\n\n## Configuration\n\n| Option | Type | Défaut | Rôle |\n|---|---|---|---|\n| `baseUrl` | `string` | — | base URL de l'API Mail, sans slash final (**obligatoire**) |\n| `env` | `string` | `undefined` | tout ce qui n'est pas `'prod'` active le garde-fou |\n| `devRecipient` | `string` | `dev@amsom-habitat.fr` | destinataire de repli hors production |\n| `fetch` | `typeof fetch` | `globalThis.fetch` | implémentation à utiliser (tests, proxy, instrumentation) |\n| `logger` | `{ warn(msg) }` | aucun | journal des réponses en erreur |\n\n### Garde-fou anti-spam\n\nHors production, **tous** les mails partent vers `devRecipient` — jamais vers le vrai destinataire. La règle\nest dans le package précisément pour ne pas être réécrite (ni oubliée) dans chaque application :\n\n```ts\nnew MailerSender({ baseUrl, env: 'prod' }).resolveRecipient('client@x.fr')  // client@x.fr\nnew MailerSender({ baseUrl, env: 'dev'  }).resolveRecipient('client@x.fr')  // dev@amsom-habitat.fr\n```\n\nUn `devRecipient` défini mais **vide** retombe sur le défaut, plutôt que d'envoyer à une adresse vide.\n\n## Utilisation\n\n### Node « nu »\n\n```ts\nimport { MailerSender } from '@amsom-habitat/mailer-sender'\n\nconst mailer = new MailerSender({\n  baseUrl: process.env.API_MAIL_URL!,\n  env: process.env.MAIL_ENV,\n  devRecipient: process.env.MAIL_DEV_RECIPIENT,\n  logger: console,\n})\n\n// 1. template nommé — POST {baseUrl}/send_prelevement_auto\nawait mailer.send('send_prelevement_auto', {\n  emailDestinataire: 'client@exemple.fr',\n  subject: 'Votre prélèvement automatique',\n  body: { nom: 'DUPONT', montant: '345,20 €' },\n  cc: 'gestion@amsom-habitat.fr',\n})\n\n// 2. corps libre — POST {baseUrl}/send_custom\nawait mailer.sendCustom({\n  emailDestinataire: 'client@exemple.fr',\n  subject: 'Suivi de votre demande',\n  body: { message: '<p>Votre demande a bien été enregistrée.</p>' },\n  templateConfig: { logo: 'logoAmsomEtMoi' },\n})\n```\n\n### NestJS\n\n```ts\n// app.module.ts\nimport { MailerModule } from '@amsom-habitat/mailer-sender/nest'\n\n@Module({\n  imports: [\n    MailerModule.forRootAsync({\n      isGlobal: true,\n      inject: [ConfigService],\n      useFactory: (config: ConfigService) => ({\n        baseUrl: config.getOrThrow('API_MAIL_URL'),\n        env: config.get('MAIL_ENV'),\n        devRecipient: config.get('MAIL_DEV_RECIPIENT'),\n      }),\n    }),\n  ],\n})\nexport class AppModule {}\n```\n\n```ts\nimport { MailService } from '@amsom-habitat/mailer-sender/nest'\n\n@Injectable()\nexport class SollicitationService {\n  constructor(private readonly mail: MailService) {}\n\n  notifier(email: string, message: string) {\n    return this.mail.sendCustom({\n      emailDestinataire: email,\n      subject: 'Votre sollicitation',\n      body: { message },\n    })\n  }\n}\n```\n\n## Payload envoyé\n\nLes deux méthodes construisent le corps attendu par l'API Mail, avec les noms de champs de celle-ci\n(`sujet`, `attachement`…). Les champs absents sont explicitement à `null`, comme le faisait la version PHP.\n\n`sendCustom` ajoute le bloc de mise en forme, dont les défauts maison : `logo: 'logoAmsomEtMoi'`,\n`bonjour: true`, `showFooter: true`, `showRemerciement: true`. `templateConfig` permet de surcharger\nn'importe lequel de ces réglages ; les autres gardent leur défaut.\n\n## Erreurs\n\n| Cas | Erreur | `status` |\n|---|---|---|\n| API injoignable (échec réseau) | `HttpClientError` | `503` |\n| Réponse non-2xx | `HttpClientError` | statut amont |\n\nLe corps d'erreur renvoyé par l'API Mail est **journalisé, jamais exposé** : certaines API maison renvoient\nune trace complète qu'il ne faut pas laisser fuiter vers un client.\n\nCôté NestJS, `MailService` traduit ces erreurs en exceptions Nest\n(`httpClientErrorToHttpException` : 503 → `ServiceUnavailableException`, sinon `HttpException` du statut\namont). L'option `mapError` permet de fournir sa propre traduction.\n\n## API publique\n\n### `@amsom-habitat/mailer-sender`\n\n| Export | Rôle |\n|---|---|\n| `MailerSender` | `send(template, params)`, `sendCustom(params)`, `resolveRecipient(email)` |\n| `HttpClientError` | erreur d'appel (`status`, `label`, `body`) |\n| `fetchOk(url, init, label, deps?)` | helper HTTP réutilisable pour d'autres clients d'API internes |\n| `MailerSenderOptions`, `MailResult`, `SendMailParams`, `SendMailCustomParams`, `TemplateConfig` | types |\n\n### `@amsom-habitat/mailer-sender/nest`\n\n| Export | Rôle |\n|---|---|\n| `MailerModule.forRoot(options)` / `forRootAsync(options)` | module fournissant `MailService` |\n| `MailService` | version injectable, erreurs traduites en exceptions Nest |\n| `httpClientErrorToHttpException(err)` | traduction par défaut |\n| `MAILER_MODULE_OPTIONS` | jeton d'injection des options |\n\n## Développement\n\n```sh\nnpm install\nnpm run build   # tsc → dist/ (CommonJS + .d.ts)\nnpm run lint\nnpm test        # jest\n```\n\nLe package est publié en **CommonJS** : les API NestJS maison sont en CJS, un paquet ESM-only n'y serait\npas importable. La carte `exports` du `package.json` laisse la place à un build ESM ultérieur.\n\n## Versionnage\n\nSemVer, une entrée par version dans [`changelog.md`](./changelog.md) (`## VX.Y.Z - JJ/MM/AAAA`).\n`check-version.sh` refuse une publication dont la version n'est pas décrite dans le changelog, ou qui porte\nun suffixe de pré-release.\n\n```sh\nmake publish        # main : lint + build + test + check-version + tag git + npm publish\nmake alpha_publish  # dev  : publication d'une beta\n```\n","readmeFilename":"README.md","_rev":"1-29ae1faadfe4988cc4e94911f97c9ee6"}