@owlmeans/mailer 0.1.18-rc.2 → 0.1.18-rc.20

package/README.md

@@ -13,7 +13,7 @@ Provider-agnostic email dispatch interface for the OwlMeans framework — `Maile
 ## Installation
 
 ```bash
-bun add @owlmeans/mailer
+bun add @owlmeans/mailer@^0.1.18-rc.19
 ```
 
 ## Usage
@@ -37,7 +37,7 @@ This package ships embedded agent skills under `agent-meta/`. After installing y
 your project's skill store (`.agents/skills/`):
 
 ```sh
-npx @owlmeans/agent-skills
+npx @owlmeans/agent-skills@^0.1.18-rc.24
 ```
 
 The embedded files are version-matched to this package release. Do not edit them

package/agent-meta/manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 2,
   "package": "@owlmeans/mailer",
-  "version": "0.1.18-rc.0",
-  "generatedAt": "2026-08-16T22:20:50.511Z",
+  "version": "0.1.18-rc.20",
+  "generatedAt": "2026-09-15T12:59:01.060Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {

package/agent-meta/skills/mailer/SKILL.md

@@ -8,14 +8,19 @@ metadata:
 
 # Using `@owlmeans/mailer`
 
-Provider-agnostic email dispatch service. Defines the `MailerService` interface implemented by concrete transports (`@owlmeans/server-mailer-mailgun` for production, `makeConsoleMailerService` for dev/tests).
+**Install:** `"@owlmeans/mailer": "^0.1.18-rc.20"` in `dependencies`
+
+Provider-agnostic email dispatch service. It defines the `MailerService` interface and ships one
+transport of its own — the console/dev one. Real delivery is a separate package:
+`@owlmeans/mailer-smtp` (SMTP, works against any relay) or `@owlmeans/server-mailer-mailgun`
+(Mailgun's HTTP API).
 
 ## Public API surface
 
 | Symbol | Kind | Purpose |
 |--------|------|---------|
-| `MailerService` | interface | `{ send(message): Promise<void> }` |
-| `MailMessage` | interface | `{ to, subject, text?, html? }` |
+| `MailerService` | interface | Extends `InitializedService` (`@owlmeans/context`) with `send(message): Promise<void>` |
+| `MailMessage` | interface | `{ to, subject, text?, html?, from?, replyTo?, headers? }` |
 | `MAILER_SERVICE` | const | Default service alias `'mailer-service'` |
 | `makeConsoleMailerService(alias?)` | fn | Dev transport: logs to console and stores messages in `.captured[]` |
 | `makeDefaultConsoleMailerService()` | fn | Alias of `makeConsoleMailerService(MAILER_SERVICE)` |
@@ -37,16 +42,40 @@ console.log(mailer.captured[0].text) // '123456'
 The console transport:
 - Logs to `console.log` (not `console.error`) — safe to use in tests without noise.
 - Accumulates all sent messages in `mailer.captured: MailMessage[]`.
-- Never throws unless context is not initialized.
+- Never throws: it has no transport to fail, which is what makes it the right double in a test.
+
+## Writing a transport
+
+The package's whole purpose is a contract other packages implement. A transport is a service built
+with `createService` from `@owlmeans/context` under the alias the caller asks for, whose one
+required member is `send`:
+
+```ts
+import { createService } from '@owlmeans/context'
+import type { MailerService, MailMessage } from '@owlmeans/mailer'
+
+export const makeMyMailerService = (alias = 'my-mailer'): MailerService =>
+  createService<MailerService>(alias, {
+    send: async (message: MailMessage): Promise<void> => { /* reach the provider */ },
+  })
+```
+
+`MailerService` extends `InitializedService`, so the context runs the service's lifecycle like any
+other; a transport that has to be torn down declares its own members on top (see the SMTP one's
+`verify()` / `close()`).
 
 ## Production wiring
 
-Use `@owlmeans/server-mailer-mailgun` for production. The `MAILER_SERVICE` alias is the same — swap transports without changing callers:
+Every transport registers under the same `MAILER_SERVICE` alias, so swapping one for another
+changes no caller. Select on config rather than on a build flag, so one image serves every
+environment:
 
 ```ts
-// Dev:
+// Dev / tests:
 context.registerService(makeConsoleMailerService(MAILER_SERVICE))
-// Prod:
+// Production, SMTP relay:
+context.registerService(makeSmtpMailerService(MAILER_SERVICE))
+// Production, Mailgun HTTP API:
 context.registerService(makeMailgunMailerService(MAILER_SERVICE))
 ```
 
@@ -55,3 +84,12 @@ context.registerService(makeMailgunMailerService(MAILER_SERVICE))
 - Register under `MAILER_SERVICE` alias when called from `OtpService` or other platform code.
 - Never import a concrete transport directly in domain services — always inject via the alias.
 - The `MailMessage.html` field is optional; supply either `text` or `html` (or both).
+- `from`, `replyTo` and `headers` are per-message overrides of whatever the transport was
+  configured with. A transport that cannot carry headers ignores the field rather than failing —
+  the contract is the smallest thing every transport can honour, so nothing here is guaranteed to
+  reach the wire.
+
+## Related
+
+- [[mailer-smtp]] — the SMTP transport and its `cfg.smtp` block
+- [[server-mailer-mailgun]] — the Mailgun HTTP transport and its `cfg.mailgun` block

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmeans/mailer",
-  "version": "0.1.18-rc.2",
+  "version": "0.1.18-rc.20",
   "license": "MIT",
   "type": "module",
   "scripts": {
@@ -22,12 +22,12 @@
     }
   },
   "dependencies": {
-    "@owlmeans/context": "^0.1.18-rc.2",
-    "@owlmeans/error": "^0.1.18-rc.2"
+    "@owlmeans/context": "^0.1.18-rc.20",
+    "@owlmeans/error": "^0.1.18-rc.20"
   },
   "devDependencies": {
     "@owlmeans/dep-config": "workspace:*",
-    "@types/bun": "^1.3.14",
+    "@types/bun": "^1.4.0",
     "nodemon": "^3.1.14",
     "typescript": "^7.0.2"
   },