@owlmeans/mailer 0.1.18-rc.8 → 0.1.18

package/README.md

@@ -1,33 +1,140 @@
 # @owlmeans/mailer
 
-Provider-agnostic email dispatch interface for the OwlMeans framework — `MailerService` abstraction and console/dev transport.
-
-## Overview
-
-- `MailerService` — `InitializedService` with a single `send(message)` method; implementations are swapped per environment
-- `MailMessage` — `{ to, subject, text?, html? }` shape accepted by all transports
-- `MAILER_SERVICE` constant — context alias for registering and resolving the mailer service
-- Default transport logs to console (suitable for development and unit tests)
-- Production transports provided by `@owlmeans/server-mailer-mailgun` and similar packages
+Provider-agnostic email dispatch: the `MailerService` contract every transport implements, the
+`MailMessage` / `MailAttachment` shapes, `mailAttachmentHelper` for decoding and describing
+attachments, and the one transport of its own — a console transport for development and tests.
+Domain code imports it to type the mailer it resolves under `MAILER_SERVICE` and to build messages;
+tests register the console transport and read what it captured. It does not deliver real mail:
+register `@owlmeans/mailer-smtp` (any SMTP relay) or `@owlmeans/server-mailer-mailgun` (Mailgun's
+HTTP API) under the same alias for that.
 
 ## Installation
 
 ```bash
-bun add @owlmeans/mailer@^0.1.18-rc.7
+bun add @owlmeans/mailer@^0.1.18
 ```
 
+## Concepts
+
+- **Transport** — a `MailerService` (an `InitializedService` with `send(message)`), built with
+  `createService` from `@owlmeans/context`. Every transport registers under `MAILER_SERVICE`, so
+  swapping one changes no caller.
+- **Message** — `MailMessage`: `to`, `subject`, `text?` / `html?`, and per-message overrides
+  `from?`, `replyTo?`, `headers?`, plus `attachments?`. Overrides are the smallest common contract —
+  a transport that cannot carry `headers` ignores them.
+- **Attachment** — `MailAttachment`: `filename`, `content` as raw bytes or a string in `encoding`
+  (`base64`, `hex`, `latin1`/`binary`, UTF-8 by default), `contentType?`.
+- **Console transport** — delivers by logging the envelope and keeps every message in `captured`.
+  It never throws, which makes it the right test double.
+
 ## Usage
 
+### Send a message
+
 ```typescript
 import { MAILER_SERVICE } from '@owlmeans/mailer'
-import type { MailerService, MailMessage } from '@owlmeans/mailer'
+import type { MailerService } from '@owlmeans/mailer'
 
-// Resolve from context and send
 const mailer = context.service<MailerService>(MAILER_SERVICE)
-await mailer.send({ to: 'user@example.com', subject: 'Welcome', text: 'Hello!' })
+
+await mailer.send({
+  to: 'user@example.com',
+  subject: 'Your report',
+  text: 'The monthly report is attached.',
+  replyTo: 'support@example.com',
+  attachments: [{ filename: 'report.csv', content: csvText, contentType: 'text/csv' }],
+})
 ```
 
-For production email via Mailgun, register `@owlmeans/server-mailer-mailgun` in your server context.
+### Use the console transport in development and tests
+
+```typescript
+import { MAILER_SERVICE, makeDefaultConsoleMailerService } from '@owlmeans/mailer'
+import type { MailerService } from '@owlmeans/mailer'
+
+const mailer = makeDefaultConsoleMailerService()    // registered under MAILER_SERVICE
+context.registerService(mailer)
+await context.configure().init()
+
+// ...code under test sends through context.service(MAILER_SERVICE)
+await context.service<MailerService>(MAILER_SERVICE).send({ to: 'user@example.com', subject: 'Code', text: '123456' })
+
+expect(mailer.captured[0].text).toBe('123456')      // read the body from captured, never from the log
+```
+
+### Select the transport on config
+
+```typescript
+import { makeConsoleMailerService, MAILER_SERVICE } from '@owlmeans/mailer'
+import { makeMailgunMailerService } from '@owlmeans/server-mailer-mailgun'
+
+context.registerService(cfg.mailgun != null
+  ? makeMailgunMailerService(MAILER_SERVICE)
+  : makeConsoleMailerService(MAILER_SERVICE))
+```
+
+### Write a transport
+
+```typescript
+import { createService } from '@owlmeans/context'
+import { mailAttachmentHelper } from '@owlmeans/mailer'
+import type { MailerService, MailMessage } from '@owlmeans/mailer'
+
+export const makeMyMailerService = (alias = 'my-mailer'): MailerService =>
+  createService<MailerService>(alias, {
+    send: async (message: MailMessage): Promise<void> => {
+      const files = (message.attachments ?? []).map(file => ({
+        name: file.filename, bytes: mailAttachmentHelper.bytesOf(file), type: file.contentType,
+      }))
+      // reach the provider; log only mailAttachmentHelper.describe(message.attachments)
+    },
+  })
+```
+
+## API
+
+| Symbol | Kind | Purpose |
+|---|---|---|
+| `MailerService` | interface | `InitializedService` + `send(message): Promise<void>` |
+| `ConsoleMailerService` | interface | `MailerService` + `captured: MailMessage[]` |
+| `MailMessage` | interface | `{ to, subject, text?, html?, from?, replyTo?, headers?, attachments? }` |
+| `MailAttachment` | interface | `{ filename, content: Uint8Array \| string, encoding?, contentType? }` |
+| `MailAttachmentSummary` | interface | `{ filename, size, contentType? }` — what a log may carry |
+| `MailAttachmentHelper` | interface | `bytesOf`, `sizeOf`, `describe` |
+| `mailAttachmentHelper` (`createMailAttachmentHelper()`) | helper | `bytesOf(a)` decodes a string `content` by `encoding`; `sizeOf(a)` byte size; `describe(list?)` summaries for logs |
+| `makeConsoleMailerService(alias = CONSOLE_MAILER)` | function | console transport under the given alias |
+| `makeDefaultConsoleMailerService()` | function | `makeConsoleMailerService(MAILER_SERVICE)` |
+| `MAILER_SERVICE` | const | `'mailer-service'` — the alias every caller resolves |
+| `CONSOLE_MAILER` | const | `'console-mailer'` — default alias of the console transport |
+
+## Console transport logging
+
+- The envelope (`from` when set, `to`, `subject`, attachment summaries) is logged at `info` under
+  scope `mailer`, event `mail.console`.
+- The body is a second record, `debug` `Mail body` (event `mail.console.body`), written only while
+  the `mailer` scope logs at debug — a development level or `cfg.log.debug: 'mailer'`.
+- Attachment content never reaches a log; `bytesOf` throws `SyntaxError('mailer:attachment:hex')`
+  on malformed hex.
+
+## Common pitfalls
+
+- `makeConsoleMailerService()` without an argument registers under `'console-mailer'`, not
+  `MAILER_SERVICE`; callers resolving `MAILER_SERVICE` will not find it. Use
+  `makeDefaultConsoleMailerService()` or pass the alias.
+- Never register the console transport where real mail must be sent — it only logs.
+- Domain services resolve the mailer by alias; they never import a concrete transport.
+- Supply `text`, `html` or both; neither is required by the type.
+- No transport caps attachment size — limits are the caller's.
+
+## Related packages
+
+- [`@owlmeans/mailer-smtp`](../mailer-smtp) — SMTP transport and its `cfg.smtp` block
+- [`@owlmeans/server-mailer-mailgun`](../server-mailer-mailgun) — Mailgun HTTP transport and its `cfg.mailgun` block
+- [`@owlmeans/server-auth-otp`](../server-auth-otp) — sends login codes through `MAILER_SERVICE`
+- [`@owlmeans/context`](../context) — `createService` and the service lifecycle
+- [`@owlmeans/log`](../log) — the logger the console transport writes through
+
+The `mailer` skill covers the same contract for agents.
 
 <!-- owlmeans:agent-guidance:start -->
 ## Agent guidance
@@ -37,7 +144,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@^0.1.18-rc.12
+npx @owlmeans/agent-skills@^0.1.18
 ```
 
 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,
+  "schemaVersion": 3,
   "package": "@owlmeans/mailer",
-  "version": "0.1.18-rc.8",
-  "generatedAt": "2026-09-04T22:43:25.448Z",
+  "version": "0.1.18",
+  "generatedAt": "2026-10-28T00:31:34.757Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {

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

@@ -8,7 +8,7 @@ metadata:
 
 # Using `@owlmeans/mailer`
 
-**Install:** `"@owlmeans/mailer": "^0.1.18-rc.8"` in `dependencies`
+**Install:** `"@owlmeans/mailer": "^0.1.18"` 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:
@@ -20,7 +20,9 @@ transport of its own — the console/dev one. Real delivery is a separate packag
 | Symbol | Kind | Purpose |
 |--------|------|---------|
 | `MailerService` | interface | Extends `InitializedService` (`@owlmeans/context`) with `send(message): Promise<void>` |
-| `MailMessage` | interface | `{ to, subject, text?, html?, from?, replyTo?, headers? }` |
+| `MailMessage` | interface | `{ to, subject, text?, html?, from?, replyTo?, headers?, attachments? }` |
+| `MailAttachment` | interface | `{ filename, content: Uint8Array \| string, encoding?, contentType? }` |
+| `mailAttachmentHelper` | helper | `bytesOf(a)` (decodes a string `content` by `encoding`: `base64`, `hex`, `latin1`/`binary`, default UTF-8), `sizeOf(a)`, `describe(list)` → `{ filename, size, contentType? }[]` for logs |
 | `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)` |
@@ -40,7 +42,8 @@ console.log(mailer.captured[0].text) // '123456'
 ```
 
 The console transport:
-- Logs to `console.log` (not `console.error`) — safe to use in tests without noise.
+- Writes each message's envelope through `@owlmeans/log` at `info`, scope `mailer`, event `mail.console`: `from` (when set), `to`, `subject`, attachments — visible at the default level, since printing the mail IS its delivery. The text (a login code, a person's message) is personal content: it is a second record, `debug` `Mail body` (event `mail.console.body`), written only while the `mailer` scope logs at debug — a development level or `cfg.log.debug: 'mailer'`. Silenced by `configureLog({ level: 'warn' })` in a noisy test; a test reads the text from `mailer.captured`, never from the log. Never register it where real mail is sent.
+- Logs attachments as `attachments: [{ filename, size, contentType? }]` — names and sizes only, never their content.
 - Accumulates all sent messages in `mailer.captured: MailMessage[]`.
 - Never throws: it has no transport to fail, which is what makes it the right double in a test.
 
@@ -84,6 +87,11 @@ 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).
+- `attachments` carry files: raw bytes, or a string in `encoding`. Every transport decodes them
+  through `mailAttachmentHelper.bytesOf`, so a file reaches the provider byte-exact whatever form it
+  was given in; `contentType` is sent as declared (a transport may fall back to
+  `application/octet-stream`). Content never reaches a log — `mailAttachmentHelper.describe` is what
+  a log line may carry. Size limits are the caller's: no transport caps them.
 - `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

package/build/attachment.d.ts

@@ -0,0 +1,4 @@
+import type { MailAttachmentHelper } from './types.js';
+export declare const createMailAttachmentHelper: () => MailAttachmentHelper;
+export declare const mailAttachmentHelper: MailAttachmentHelper;
+//# sourceMappingURL=attachment.d.ts.map

package/build/attachment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attachment.d.ts","sourceRoot":"","sources":["../src/attachment.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAkB,oBAAoB,EAAyB,MAAM,YAAY,CAAA;AAE7F,eAAO,MAAM,0BAA0B,QAAO,oBAmD7C,CAAA;AAED,eAAO,MAAM,oBAAoB,sBAA+B,CAAA"}

package/build/attachment.js

@@ -0,0 +1,47 @@
+export const createMailAttachmentHelper = () => {
+    const fromBase64 = (text) => {
+        const binary = atob(text.replace(/\s+/g, ''));
+        const bytes = new Uint8Array(binary.length);
+        for (let i = 0; i < binary.length; i++)
+            bytes[i] = binary.charCodeAt(i);
+        return bytes;
+    };
+    const fromHex = (text) => {
+        const clean = text.replace(/\s+/g, '');
+        if (clean.length % 2 !== 0 || /[^0-9a-f]/i.test(clean)) {
+            throw new SyntaxError('mailer:attachment:hex');
+        }
+        const bytes = new Uint8Array(clean.length / 2);
+        for (let i = 0; i < bytes.length; i++)
+            bytes[i] = parseInt(clean.slice(i * 2, i * 2 + 2), 16);
+        return bytes;
+    };
+    const fromLatin1 = (text) => {
+        const bytes = new Uint8Array(text.length);
+        for (let i = 0; i < text.length; i++)
+            bytes[i] = text.charCodeAt(i) & 0xff;
+        return bytes;
+    };
+    const bytesOf = (attachment) => {
+        const { content } = attachment;
+        if (typeof content !== 'string') {
+            return content;
+        }
+        switch (attachment.encoding?.toLowerCase()) {
+            case 'base64': return fromBase64(content);
+            case 'hex': return fromHex(content);
+            case 'latin1':
+            case 'binary': return fromLatin1(content);
+            default: return new TextEncoder().encode(content);
+        }
+    };
+    const sizeOf = (attachment) => bytesOf(attachment).byteLength;
+    const describe = (attachments) => (attachments ?? []).map(attachment => ({
+        filename: attachment.filename,
+        size: sizeOf(attachment),
+        ...(attachment.contentType != null ? { contentType: attachment.contentType } : {}),
+    }));
+    return { bytesOf, sizeOf, describe };
+};
+export const mailAttachmentHelper = createMailAttachmentHelper();
+//# sourceMappingURL=attachment.js.map

package/build/attachment.js.map

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

package/build/consts.d.ts

@@ -1,2 +1,3 @@
 export declare const MAILER_SERVICE = "mailer-service";
+export declare const CONSOLE_MAILER = "console-mailer";
 //# sourceMappingURL=consts.d.ts.map

package/build/consts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"consts.d.ts","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,cAAc,mBAAmB,CAAA"}
+{"version":3,"file":"consts.d.ts","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,cAAc,mBAAmB,CAAA;AAE9C,eAAO,MAAM,cAAc,mBAAmB,CAAA"}

package/build/consts.js

@@ -1,2 +1,3 @@
 export const MAILER_SERVICE = 'mailer-service';
+export const CONSOLE_MAILER = 'console-mailer';
 //# sourceMappingURL=consts.js.map

package/build/consts.js.map

@@ -1 +1 @@
-{"version":3,"file":"consts.js","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,cAAc,GAAG,gBAAgB,CAAA"}
+{"version":3,"file":"consts.js","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,cAAc,GAAG,gBAAgB,CAAA;AAE9C,MAAM,CAAC,MAAM,cAAc,GAAG,gBAAgB,CAAA"}

package/build/index.d.ts

@@ -1,4 +1,5 @@
 export type * from './types.js';
 export * from './consts.js';
+export * from './attachment.js';
 export * from './service.js';
 //# sourceMappingURL=index.d.ts.map

package/build/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,mBAAmB,YAAY,CAAA;AAC/B,cAAc,aAAa,CAAA;AAC3B,cAAc,cAAc,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,mBAAmB,YAAY,CAAA;AAC/B,cAAc,aAAa,CAAA;AAC3B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,cAAc,CAAA"}

package/build/index.js

@@ -1,3 +1,4 @@
 export * from './consts.js';
+export * from './attachment.js';
 export * from './service.js';
 //# sourceMappingURL=index.js.map

package/build/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,aAAa,CAAA;AAC3B,cAAc,cAAc,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,aAAa,CAAA;AAC3B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,cAAc,CAAA"}

package/build/service.d.ts

@@ -1,12 +1,8 @@
-import type { MailerService, MailMessage } from './types.js';
-export declare const CONSOLE_MAILER = "console-mailer";
+import type { ConsoleMailerService } from './types.js';
 /** Dev/test transport: logs the message to console and stores it for inspection. */
-export declare const makeConsoleMailerService: (alias?: string) => MailerService & {
-    /** Messages captured since the service was created (use in tests). */
-    captured: MailMessage[];
-};
+export declare const makeConsoleMailerService: (alias?: string) => ConsoleMailerService;
 /** Alias of makeConsoleMailerService registered under the default MAILER_SERVICE alias.
  *  Useful as a drop-in replacement during development and integration tests.
  */
-export declare const makeDefaultConsoleMailerService: () => ReturnType<typeof makeConsoleMailerService>;
+export declare const makeDefaultConsoleMailerService: () => ConsoleMailerService;
 //# sourceMappingURL=service.d.ts.map

package/build/service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAG5D,eAAO,MAAM,cAAc,mBAAmB,CAAA;AAE9C,oFAAoF;AACpF,eAAO,MAAM,wBAAwB,sBAA6B,aAAa,GAAG;IAChF,sEAAsE;IACtE,QAAQ,EAAE,WAAW,EAAE,CAAA;CAexB,CAAA;AAED;;GAEG;AACH,eAAO,MAAM,+BAA+B,QAAO,UAAU,CAAC,OAAO,wBAAwB,CACnD,CAAA"}
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,oBAAoB,EAA8B,MAAM,YAAY,CAAA;AAOlF,oFAAoF;AACpF,eAAO,MAAM,wBAAwB,sBAA6B,oBA2BjE,CAAA;AAED;;GAEG;AACH,eAAO,MAAM,+BAA+B,QAAO,oBACT,CAAA"}

package/build/service.js

@@ -1,15 +1,30 @@
 import { createService } from '@owlmeans/context';
-import { MAILER_SERVICE } from './consts.js';
-export const CONSOLE_MAILER = 'console-mailer';
+import { MAILER_SERVICE, CONSOLE_MAILER } from './consts.js';
+import { mailAttachmentHelper } from './attachment.js';
+import { logger } from '@owlmeans/log';
+const log = logger('mailer');
 /** Dev/test transport: logs the message to console and stores it for inspection. */
 export const makeConsoleMailerService = (alias = CONSOLE_MAILER) => {
     const captured = [];
     const service = createService(alias, {
         send: async (message) => {
             captured.push(message);
-            const from = message.from != null ? ` from=${message.from}` : '';
-            console.log(`[console-mailer]${from} to=${message.to} subject="${message.subject}"`);
-            console.log(`[console-mailer] body=${message.text ?? message.html ?? ''}`);
+            // The explicit dev transport: printing the mail IS its delivery, so its envelope — sender,
+            // recipient, subject, attachment names and sizes — is written at `info` under the scope
+            // `mailer`. The text (a login code, a person's message) is personal content: it is written
+            // only while `mailer` logs at debug (a development level, or `cfg.log.debug: 'mailer'`).
+            // Attachment content never reaches a log. Never register it where real mail is sent.
+            const attachments = mailAttachmentHelper.describe(message.attachments);
+            const envelope = {
+                ...(message.from != null ? { from: message.from } : {}),
+                to: message.to, subject: message.subject,
+            };
+            log.info('Mail written to the console', {
+                ...envelope, ...(attachments.length > 0 ? { attachments } : {}),
+            }, { event: 'mail.console' });
+            if (log.enabled('debug')) {
+                log.debug('Mail body', { ...envelope, body: message.text ?? message.html ?? '' }, { event: 'mail.console.body' });
+            }
         },
     });
     service.captured = captured;

package/build/service.js.map

@@ -1 +1 @@
-{"version":3,"file":"service.js","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AAEjD,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAE5C,MAAM,CAAC,MAAM,cAAc,GAAG,gBAAgB,CAAA;AAE9C,oFAAoF;AACpF,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,KAAK,GAAG,cAAc,EAG7D,EAAE;IACF,MAAM,QAAQ,GAAkB,EAAE,CAAA;IAElC,MAAM,OAAO,GAAG,aAAa,CAAgB,KAAK,EAAE;QAClD,IAAI,EAAE,KAAK,EAAE,OAAoB,EAAiB,EAAE;YAClD,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;YACtB,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,IAAI,CAAC,CAAC,CAAC,SAAS,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAA;YAChE,OAAO,CAAC,GAAG,CAAC,mBAAmB,IAAI,OAAO,OAAO,CAAC,EAAE,aAAa,OAAO,CAAC,OAAO,GAAG,CAAC,CAAA;YACpF,OAAO,CAAC,GAAG,CAAC,yBAAyB,OAAO,CAAC,IAAI,IAAI,OAAO,CAAC,IAAI,IAAI,EAAE,EAAE,CAAC,CAAA;QAC5E,CAAC;KACF,CAAgD,CAAA;IAEjD,OAAO,CAAC,QAAQ,GAAG,QAAQ,CAAA;IAC3B,OAAO,OAAO,CAAA;AAChB,CAAC,CAAA;AAED;;GAEG;AACH,MAAM,CAAC,MAAM,+BAA+B,GAAG,GAAgD,EAAE,CAC/F,wBAAwB,CAAC,cAAc,CAAC,CAAA"}
+{"version":3,"file":"service.js","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AAEjD,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAC5D,OAAO,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAA;AACtD,OAAO,EAAE,MAAM,EAAE,MAAM,eAAe,CAAA;AAEtC,MAAM,GAAG,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAA;AAE5B,oFAAoF;AACpF,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,KAAK,GAAG,cAAc,EAAwB,EAAE;IACvF,MAAM,QAAQ,GAAkB,EAAE,CAAA;IAElC,MAAM,OAAO,GAAG,aAAa,CAAgB,KAAK,EAAE;QAClD,IAAI,EAAE,KAAK,EAAE,OAAoB,EAAiB,EAAE;YAClD,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;YACtB,2FAA2F;YAC3F,wFAAwF;YACxF,2FAA2F;YAC3F,yFAAyF;YACzF,qFAAqF;YACrF,MAAM,WAAW,GAAG,oBAAoB,CAAC,QAAQ,CAAC,OAAO,CAAC,WAAW,CAAC,CAAA;YACtE,MAAM,QAAQ,GAAG;gBACf,GAAG,CAAC,OAAO,CAAC,IAAI,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBACvD,EAAE,EAAE,OAAO,CAAC,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO;aACzC,CAAA;YACD,GAAG,CAAC,IAAI,CAAC,6BAA6B,EAAE;gBACtC,GAAG,QAAQ,EAAE,GAAG,CAAC,WAAW,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aAChE,EAAE,EAAE,KAAK,EAAE,cAAc,EAAE,CAAC,CAAA;YAC7B,IAAI,GAAG,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;gBACzB,GAAG,CAAC,KAAK,CAAC,WAAW,EAAE,EAAE,GAAG,QAAQ,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,IAAI,OAAO,CAAC,IAAI,IAAI,EAAE,EAAE,EAAE,EAAE,KAAK,EAAE,mBAAmB,EAAE,CAAC,CAAA;YACnH,CAAC;QACH,CAAC;KACF,CAAyB,CAAA;IAE1B,OAAO,CAAC,QAAQ,GAAG,QAAQ,CAAA;IAC3B,OAAO,OAAO,CAAA;AAChB,CAAC,CAAA;AAED;;GAEG;AACH,MAAM,CAAC,MAAM,+BAA+B,GAAG,GAAyB,EAAE,CACxE,wBAAwB,CAAC,cAAc,CAAC,CAAA"}

package/build/types.d.ts

@@ -1,4 +1,18 @@
 import type { InitializedService } from '@owlmeans/context';
+/** A file carried by a message. */
+export interface MailAttachment {
+    /** The name the recipient sees; the transport never derives a path from it. */
+    filename: string;
+    /**
+     * The file itself: raw bytes, or text in `encoding` (UTF-8 when `encoding` is absent). A
+     * transport may hand the bytes to its provider, never to a log.
+     */
+    content: Uint8Array | string;
+    /** How a string `content` is encoded — `base64`, `hex`, `latin1`/`binary` or `utf8` (default). */
+    encoding?: string;
+    /** The MIME type the file is sent with; absent = the transport's own guess from the name. */
+    contentType?: string;
+}
 export interface MailMessage {
     to: string;
     subject: string;
@@ -9,9 +23,31 @@ export interface MailMessage {
     replyTo?: string;
     /** Extra headers. A transport that cannot carry them ignores the field. */
     headers?: Record<string, string>;
+    /** Files sent with the message, in order. */
+    attachments?: MailAttachment[];
 }
 /** Provider-agnostic email dispatch service */
 export interface MailerService extends InitializedService {
     send: (message: MailMessage) => Promise<void>;
 }
+/** The dev/test transport: delivers by logging, and keeps what it sent for inspection. */
+export interface ConsoleMailerService extends MailerService {
+    /** Messages captured since the service was created (use in tests). */
+    captured: MailMessage[];
+}
+/** What every transport needs to know about an attachment without reading it into a log. */
+export interface MailAttachmentHelper {
+    /** The attachment's bytes, decoded from a string `content` by its `encoding`. */
+    bytesOf: (attachment: MailAttachment) => Uint8Array;
+    /** The attachment's size in bytes. */
+    sizeOf: (attachment: MailAttachment) => number;
+    /** What a log may say about the attachments: their names and sizes, never their content. */
+    describe: (attachments?: MailAttachment[]) => MailAttachmentSummary[];
+}
+/** One attachment as a log line carries it. */
+export interface MailAttachmentSummary {
+    filename: string;
+    size: number;
+    contentType?: string;
+}
 //# sourceMappingURL=types.d.ts.map

package/build/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAA;AAE3D,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAA;IACV,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,0EAA0E;IAC1E,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,2EAA2E;IAC3E,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CACjC;AAED,+CAA+C;AAC/C,MAAM,WAAW,aAAc,SAAQ,kBAAkB;IACvD,IAAI,EAAE,CAAC,OAAO,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CAC9C"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAA;AAE3D,mCAAmC;AACnC,MAAM,WAAW,cAAc;IAC7B,+EAA+E;IAC/E,QAAQ,EAAE,MAAM,CAAA;IAChB;;;OAGG;IACH,OAAO,EAAE,UAAU,GAAG,MAAM,CAAA;IAC5B,kGAAkG;IAClG,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,6FAA6F;IAC7F,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAA;IACV,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,0EAA0E;IAC1E,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,2EAA2E;IAC3E,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAChC,6CAA6C;IAC7C,WAAW,CAAC,EAAE,cAAc,EAAE,CAAA;CAC/B;AAED,+CAA+C;AAC/C,MAAM,WAAW,aAAc,SAAQ,kBAAkB;IACvD,IAAI,EAAE,CAAC,OAAO,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CAC9C;AAED,0FAA0F;AAC1F,MAAM,WAAW,oBAAqB,SAAQ,aAAa;IACzD,sEAAsE;IACtE,QAAQ,EAAE,WAAW,EAAE,CAAA;CACxB;AAED,4FAA4F;AAC5F,MAAM,WAAW,oBAAoB;IACnC,iFAAiF;IACjF,OAAO,EAAE,CAAC,UAAU,EAAE,cAAc,KAAK,UAAU,CAAA;IACnD,sCAAsC;IACtC,MAAM,EAAE,CAAC,UAAU,EAAE,cAAc,KAAK,MAAM,CAAA;IAC9C,4FAA4F;IAC5F,QAAQ,EAAE,CAAC,WAAW,CAAC,EAAE,cAAc,EAAE,KAAK,qBAAqB,EAAE,CAAA;CACtE;AAED,+CAA+C;AAC/C,MAAM,WAAW,qBAAqB;IACpC,QAAQ,EAAE,MAAM,CAAA;IAChB,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB"}

package/package.json

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

package/src/attachment.ts

@@ -0,0 +1,56 @@
+import type { MailAttachment, MailAttachmentHelper, MailAttachmentSummary } from './types.js'
+
+export const createMailAttachmentHelper = (): MailAttachmentHelper => {
+  const fromBase64 = (text: string): Uint8Array => {
+    const binary = atob(text.replace(/\s+/g, ''))
+    const bytes = new Uint8Array(binary.length)
+    for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i)
+
+    return bytes
+  }
+
+  const fromHex = (text: string): Uint8Array => {
+    const clean = text.replace(/\s+/g, '')
+    if (clean.length % 2 !== 0 || /[^0-9a-f]/i.test(clean)) {
+      throw new SyntaxError('mailer:attachment:hex')
+    }
+    const bytes = new Uint8Array(clean.length / 2)
+    for (let i = 0; i < bytes.length; i++) bytes[i] = parseInt(clean.slice(i * 2, i * 2 + 2), 16)
+
+    return bytes
+  }
+
+  const fromLatin1 = (text: string): Uint8Array => {
+    const bytes = new Uint8Array(text.length)
+    for (let i = 0; i < text.length; i++) bytes[i] = text.charCodeAt(i) & 0xff
+
+    return bytes
+  }
+
+  const bytesOf = (attachment: MailAttachment): Uint8Array => {
+    const { content } = attachment
+    if (typeof content !== 'string') {
+      return content
+    }
+    switch (attachment.encoding?.toLowerCase()) {
+      case 'base64': return fromBase64(content)
+      case 'hex': return fromHex(content)
+      case 'latin1':
+      case 'binary': return fromLatin1(content)
+      default: return new TextEncoder().encode(content)
+    }
+  }
+
+  const sizeOf = (attachment: MailAttachment): number => bytesOf(attachment).byteLength
+
+  const describe = (attachments?: MailAttachment[]): MailAttachmentSummary[] =>
+    (attachments ?? []).map(attachment => ({
+      filename: attachment.filename,
+      size: sizeOf(attachment),
+      ...(attachment.contentType != null ? { contentType: attachment.contentType } : {}),
+    }))
+
+  return { bytesOf, sizeOf, describe }
+}
+
+export const mailAttachmentHelper = createMailAttachmentHelper()

package/src/consts.ts

@@ -1 +1,3 @@
 export const MAILER_SERVICE = 'mailer-service'
+
+export const CONSOLE_MAILER = 'console-mailer'

package/src/index.ts

@@ -1,3 +1,4 @@
 export type * from './types.js'
 export * from './consts.js'
+export * from './attachment.js'
 export * from './service.js'

package/src/service.ts

@@ -1,24 +1,36 @@
 import { createService } from '@owlmeans/context'
-import type { MailerService, MailMessage } from './types.js'
-import { MAILER_SERVICE } from './consts.js'
+import type { ConsoleMailerService, MailerService, MailMessage } from './types.js'
+import { MAILER_SERVICE, CONSOLE_MAILER } from './consts.js'
+import { mailAttachmentHelper } from './attachment.js'
+import { logger } from '@owlmeans/log'
 
-export const CONSOLE_MAILER = 'console-mailer'
+const log = logger('mailer')
 
 /** Dev/test transport: logs the message to console and stores it for inspection. */
-export const makeConsoleMailerService = (alias = CONSOLE_MAILER): MailerService & {
-  /** Messages captured since the service was created (use in tests). */
-  captured: MailMessage[]
-} => {
+export const makeConsoleMailerService = (alias = CONSOLE_MAILER): ConsoleMailerService => {
   const captured: MailMessage[] = []
 
   const service = createService<MailerService>(alias, {
     send: async (message: MailMessage): Promise<void> => {
       captured.push(message)
-      const from = message.from != null ? ` from=${message.from}` : ''
-      console.log(`[console-mailer]${from} to=${message.to} subject="${message.subject}"`)
-      console.log(`[console-mailer] body=${message.text ?? message.html ?? ''}`)
+      // The explicit dev transport: printing the mail IS its delivery, so its envelope — sender,
+      // recipient, subject, attachment names and sizes — is written at `info` under the scope
+      // `mailer`. The text (a login code, a person's message) is personal content: it is written
+      // only while `mailer` logs at debug (a development level, or `cfg.log.debug: 'mailer'`).
+      // Attachment content never reaches a log. Never register it where real mail is sent.
+      const attachments = mailAttachmentHelper.describe(message.attachments)
+      const envelope = {
+        ...(message.from != null ? { from: message.from } : {}),
+        to: message.to, subject: message.subject,
+      }
+      log.info('Mail written to the console', {
+        ...envelope, ...(attachments.length > 0 ? { attachments } : {}),
+      }, { event: 'mail.console' })
+      if (log.enabled('debug')) {
+        log.debug('Mail body', { ...envelope, body: message.text ?? message.html ?? '' }, { event: 'mail.console.body' })
+      }
     },
-  }) as MailerService & { captured: MailMessage[] }
+  }) as ConsoleMailerService
 
   service.captured = captured
   return service
@@ -27,5 +39,5 @@ export const makeConsoleMailerService = (alias = CONSOLE_MAILER): MailerService
 /** Alias of makeConsoleMailerService registered under the default MAILER_SERVICE alias.
  *  Useful as a drop-in replacement during development and integration tests.
  */
-export const makeDefaultConsoleMailerService = (): ReturnType<typeof makeConsoleMailerService> =>
+export const makeDefaultConsoleMailerService = (): ConsoleMailerService =>
   makeConsoleMailerService(MAILER_SERVICE)

package/src/types.ts

@@ -1,5 +1,20 @@
 import type { InitializedService } from '@owlmeans/context'
 
+/** A file carried by a message. */
+export interface MailAttachment {
+  /** The name the recipient sees; the transport never derives a path from it. */
+  filename: string
+  /**
+   * The file itself: raw bytes, or text in `encoding` (UTF-8 when `encoding` is absent). A
+   * transport may hand the bytes to its provider, never to a log.
+   */
+  content: Uint8Array | string
+  /** How a string `content` is encoded — `base64`, `hex`, `latin1`/`binary` or `utf8` (default). */
+  encoding?: string
+  /** The MIME type the file is sent with; absent = the transport's own guess from the name. */
+  contentType?: string
+}
+
 export interface MailMessage {
   to: string
   subject: string
@@ -10,9 +25,34 @@ export interface MailMessage {
   replyTo?: string
   /** Extra headers. A transport that cannot carry them ignores the field. */
   headers?: Record<string, string>
+  /** Files sent with the message, in order. */
+  attachments?: MailAttachment[]
 }
 
 /** Provider-agnostic email dispatch service */
 export interface MailerService extends InitializedService {
   send: (message: MailMessage) => Promise<void>
 }
+
+/** The dev/test transport: delivers by logging, and keeps what it sent for inspection. */
+export interface ConsoleMailerService extends MailerService {
+  /** Messages captured since the service was created (use in tests). */
+  captured: MailMessage[]
+}
+
+/** What every transport needs to know about an attachment without reading it into a log. */
+export interface MailAttachmentHelper {
+  /** The attachment's bytes, decoded from a string `content` by its `encoding`. */
+  bytesOf: (attachment: MailAttachment) => Uint8Array
+  /** The attachment's size in bytes. */
+  sizeOf: (attachment: MailAttachment) => number
+  /** What a log may say about the attachments: their names and sizes, never their content. */
+  describe: (attachments?: MailAttachment[]) => MailAttachmentSummary[]
+}
+
+/** One attachment as a log line carries it. */
+export interface MailAttachmentSummary {
+  filename: string
+  size: number
+  contentType?: string
+}

package/tests/console.spec.ts

@@ -0,0 +1,126 @@
+import { describe, expect, test } from 'bun:test'
+import { AppType, makeBasicContext } from '@owlmeans/context'
+import type { BasicConfig } from '@owlmeans/context'
+import { addLogPlugin, configureLog, logConfig, memoryPlugin } from '@owlmeans/log'
+import {
+  CONSOLE_MAILER, MAILER_SERVICE, mailAttachmentHelper, makeConsoleMailerService, makeDefaultConsoleMailerService,
+} from '../src/index.js'
+import type { MailerService } from '../src/index.js'
+
+/** Registered and initialized the way an application does it, then looked up by alias. */
+const booted = async (service: MailerService) => {
+  const ctx = makeBasicContext<BasicConfig>({ ready: false, service: 'mailer-tests', type: AppType.Backend })
+  ctx.registerService(service)
+  ctx.configure()
+  await ctx.init()
+
+  return ctx
+}
+
+describe('@owlmeans/mailer — console transport', () => {
+  test('is registered under its own alias unless told otherwise', () => {
+    expect(makeConsoleMailerService().alias).toBe(CONSOLE_MAILER)
+    expect(makeConsoleMailerService('outbox').alias).toBe('outbox')
+  })
+
+  test('the default variant answers the alias every consumer looks the mailer up by', async () => {
+    const mailer = makeDefaultConsoleMailerService()
+    const ctx = await booted(mailer)
+
+    expect(ctx.service<MailerService>(MAILER_SERVICE)).toBe(mailer)
+  })
+
+  test('captures every message as sent, in order, without touching it', async () => {
+    const mailer = makeConsoleMailerService()
+    await booted(mailer)
+    const first = { to: 'a@example.com', subject: 'Code', text: '123456' }
+    const second = {
+      to: 'b@example.com', subject: 'Report', html: '<b>done</b>', from: 'Ops <ops@example.com>',
+      replyTo: 'help@example.com', headers: { 'X-Run': '7' },
+    }
+
+    await mailer.send(first)
+    await mailer.send(second)
+
+    expect(mailer.captured).toEqual([first, second])
+  })
+
+  test('writes the envelope at info and the text only at debug', async () => {
+    const memory = memoryPlugin('mailer-body')
+    const remove = addLogPlugin(memory)
+    const level = logConfig().level
+    try {
+      const mailer = makeConsoleMailerService()
+      const message = { to: 'a@example.com', subject: 'Code', text: 'your code is 482913' }
+
+      configureLog({ level: 'info' })
+      await mailer.send(message)
+      expect(memory.records.map(r => [r.level, r.message, r.data])).toEqual([
+        ['info', 'Mail written to the console', { to: 'a@example.com', subject: 'Code' }],
+      ])
+      expect(JSON.stringify(memory.records)).not.toContain('482913')
+
+      memory.clear()
+      configureLog({ level: 'debug' })
+      await mailer.send(message)
+      expect(memory.records.map(r => [r.level, r.message])).toEqual([
+        ['info', 'Mail written to the console'], ['debug', 'Mail body'],
+      ])
+      expect((memory.records[1].data as { body: string }).body).toBe('your code is 482913')
+    } finally {
+      configureLog({ level })
+      remove()
+    }
+  })
+
+  test('each instance keeps its own outbox', async () => {
+    const one = makeConsoleMailerService('one')
+    const two = makeConsoleMailerService('two')
+    await one.send({ to: 'a@example.com', subject: 'only one' })
+
+    expect(one.captured).toHaveLength(1)
+    expect(two.captured).toHaveLength(0)
+  })
+})
+
+describe('@owlmeans/mailer — attachments', () => {
+  const png = new Uint8Array([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])
+
+  test('the console transport names and sizes attachments, never logs their content', async () => {
+    const memory = memoryPlugin('mailer-attachments')
+    const remove = addLogPlugin(memory)
+    try {
+      const mailer = makeConsoleMailerService()
+      await mailer.send({
+        to: 'a@example.com', subject: 'Report', text: 'see attached',
+        attachments: [
+          { filename: 'shot.png', content: png, contentType: 'image/png' },
+          { filename: 'notes.txt', content: 'c2VjcmV0LWNvbnRlbnQ=', encoding: 'base64' },
+        ],
+      })
+
+      const record = memory.records.find(r => r.message === 'Mail written to the console')
+      expect(record).toBeDefined()
+      expect((record!.data as { attachments: unknown }).attachments).toEqual([
+        { filename: 'shot.png', size: 8, contentType: 'image/png' },
+        { filename: 'notes.txt', size: 14 },
+      ])
+      expect(JSON.stringify(record!.data)).not.toContain('c2VjcmV0LWNvbnRlbnQ=')
+      expect(JSON.stringify(record!.data)).not.toContain('secret-content')
+      expect(mailer.captured[0].attachments).toHaveLength(2)
+    } finally {
+      remove()
+    }
+  })
+
+  test('decodes string content by its encoding', () => {
+    const text = (bytes: Uint8Array) => new TextDecoder().decode(bytes)
+
+    expect(mailAttachmentHelper.bytesOf({ filename: 'a', content: png })).toBe(png)
+    expect(text(mailAttachmentHelper.bytesOf({ filename: 'a', content: 'aGVsbG8=', encoding: 'base64' }))).toBe('hello')
+    expect(text(mailAttachmentHelper.bytesOf({ filename: 'a', content: '68656c6c6f', encoding: 'hex' }))).toBe('hello')
+    expect(mailAttachmentHelper.sizeOf({ filename: 'a', content: 'żółw' })).toBe(7)
+    expect(mailAttachmentHelper.sizeOf({ filename: 'a', content: 'abc', encoding: 'latin1' })).toBe(3)
+    expect(() => mailAttachmentHelper.bytesOf({ filename: 'a', content: 'abc', encoding: 'hex' })).toThrow()
+  })
+})