@owlmeans/server-mailer-mailgun 0.1.6 → 0.1.8

package/README.md

@@ -0,0 +1,54 @@
+# @owlmeans/server-mailer-mailgun
+
+Mailgun production email transport for OwlMeans — implements `MailerService` via the Mailgun HTTP API.
+
+## Overview
+
+- `makeMailgunMailer()` — creates a `MailerService` that sends via the Mailgun v3 REST API
+- `MAILGUN_MAILER` constant — context alias for registration and lookup
+- `MailgunConfig` — extends `ServerConfig` with `{ apiKey, domain, from, baseUrl? }`
+- Zero extra runtime dependencies — uses the global `fetch()` (Node 18+)
+- Swap in for the default console transport by registering this service in your server context
+
+## Installation
+
+```bash
+bun add @owlmeans/server-mailer-mailgun
+```
+
+## Usage
+
+```typescript
+import { makeMailgunMailer, MAILGUN_MAILER } from '@owlmeans/server-mailer-mailgun'
+
+// Register in your server context
+context.registerService(makeMailgunMailer())
+
+// Config section (in your server config object)
+const config = {
+  mailgun: {
+    apiKey: process.env.MAILGUN_API_KEY!,
+    domain: 'mg.example.com',
+    from: 'OwlMeans Platform <noreply@mg.example.com>',
+  },
+}
+```
+
+The service is resolved at runtime via `context.service<MailerService>(MAILGUN_MAILER)` — or automatically by code that resolves `MAILER_SERVICE` from `@owlmeans/mailer` when this service is registered under that alias.
+
+<!-- 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/server-mailer-mailgun.instructions.md

@@ -0,0 +1,48 @@
+---
+description: "How to use @owlmeans/server-mailer-mailgun — Mailgun production email transport. Use when configuring the production MailerService."
+applyTo: "**/context.ts, **/config.ts"
+---
+<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
+
+# Using `@owlmeans/server-mailer-mailgun`
+
+Production Mailgun transport implementing `@owlmeans/mailer`'s `MailerService` interface. Reads config from `ctx.cfg.mailgun`.
+
+## Public API surface
+
+| Symbol | Kind | Purpose |
+|--------|------|---------|
+| `makeMailgunMailerService(alias?)` | fn | Service factory |
+| `MailgunConfig` | interface | Extends `ServerConfig` with `mailgun: { apiKey, domain, from, baseUrl? }` |
+| `MAILGUN_MAILER` | const | Default alias `'mailgun-mailer'` |
+
+## Config shape
+
+```ts
+import type { MailgunConfig } from '@owlmeans/server-mailer-mailgun'
+
+cfg.mailgun = {
+  apiKey: process.env.MAILGUN_API_KEY!,
+  domain: process.env.MAILGUN_DOMAIN!,          // e.g. 'mg.example.com'
+  from: process.env.MAILGUN_FROM!,              // e.g. 'OwlMeans <no-reply@mg.example.com>'
+  baseUrl: 'https://api.eu.mailgun.net/v3',     // optional, default 'https://api.mailgun.net/v3'
+}
+```
+
+## Registration
+
+```ts
+import { makeMailgunMailerService } from '@owlmeans/server-mailer-mailgun'
+import { MAILER_SERVICE } from '@owlmeans/mailer'
+
+context.registerService(makeMailgunMailerService(MAILER_SERVICE))
+```
+
+Register under `MAILER_SERVICE` so platform code (OTP service, etc.) can resolve it without knowing the concrete transport.
+
+## Rules
+
+- For EU region, set `baseUrl: 'https://api.eu.mailgun.net/v3'`.
+- The service reads `ctx.cfg.mailgun` at call time — the config must be on the context's `cfg` object.
+- Throws a plain `Error` with the Mailgun status code and body if the API call fails; callers should wrap in a domain error if needed.
+- Never use this in tests — use `makeConsoleMailerService` instead.

package/agent-meta/manifest.json

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

package/package.json

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