@owlmeans/mailer 0.1.7 → 0.1.8

package/README.md

@@ -0,0 +1,47 @@
+# @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
+
+## Installation
+
+```bash
+bun add @owlmeans/mailer
+```
+
+## Usage
+
+```typescript
+import { MAILER_SERVICE } from '@owlmeans/mailer'
+import type { MailerService, MailMessage } 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!' })
+```
+
+For production email via Mailgun, register `@owlmeans/server-mailer-mailgun` in your server context.
+
+<!-- owlmeans:agent-guidance:start -->
+## Agent guidance
+
+This package ships embedded Claude Code skills and GitHub Copilot instructions under
+`agent-meta/`. After installing your `@owlmeans/*` packages, run the OwlMeans
+agent-skills installer to place them into your project's native locations
+(`.claude/skills/` and `.github/instructions/`):
+
+```sh
+npx @owlmeans/agent-skills
+```
+
+The embedded files are version-matched to this package release. Do not edit them
+directly — they are regenerated on each publish. To contribute guidance edits,
+open a PR against the source monorepo.
+<!-- owlmeans:agent-guidance:end -->

package/agent-meta/instructions/mailer.instructions.md

@@ -0,0 +1,55 @@
+---
+description: "How to use @owlmeans/mailer — MailerService interface + console/dev transport. Use when sending emails or setting up a mailer in tests."
+applyTo: "**/context.ts, **/services/mail*"
+---
+<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
+
+# 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).
+
+## Public API surface
+
+| Symbol | Kind | Purpose |
+|--------|------|---------|
+| `MailerService` | interface | `{ send(message): Promise<void> }` |
+| `MailMessage` | interface | `{ to, subject, text?, html? }` |
+| `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)` |
+| `CONSOLE_MAILER` | const | Default alias for the console transport `'console-mailer'` |
+
+## Console transport (dev & tests)
+
+```ts
+import { makeConsoleMailerService, MAILER_SERVICE } from '@owlmeans/mailer'
+
+const mailer = makeConsoleMailerService(MAILER_SERVICE)
+context.registerService(mailer)
+
+// In tests: inspect captured messages
+await mailer.send({ to: 'user@example.com', subject: 'Code', text: '123456' })
+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.
+
+## Production wiring
+
+Use `@owlmeans/server-mailer-mailgun` for production. The `MAILER_SERVICE` alias is the same — swap transports without changing callers:
+
+```ts
+// Dev:
+context.registerService(makeConsoleMailerService(MAILER_SERVICE))
+// Prod:
+context.registerService(makeMailgunMailerService(MAILER_SERVICE))
+```
+
+## Rules
+
+- 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).

package/agent-meta/manifest.json

@@ -0,0 +1,16 @@
+{
+  "schemaVersion": 1,
+  "package": "@owlmeans/mailer",
+  "version": "0.1.8",
+  "generatedAt": "2026-06-11T16:30:27.191Z",
+  "canonicalRepo": "https://github.com/owlmeans/common",
+  "entries": [
+    {
+      "kind": "instruction",
+      "name": "mailer",
+      "category": "package-specific",
+      "file": "instructions/mailer.instructions.md",
+      "canonicalPath": ".github/instructions/mailer.instructions.md"
+    }
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmeans/mailer",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "license": "MIT",
   "type": "module",
   "scripts": {
@@ -22,8 +22,8 @@
     }
   },
   "dependencies": {
-    "@owlmeans/context": "^0.1.7",
-    "@owlmeans/error": "^0.1.7"
+    "@owlmeans/context": "^0.1.8",
+    "@owlmeans/error": "^0.1.8"
   },
   "devDependencies": {
     "@owlmeans/dep-config": "workspace:*",