@c9up/rover 0.1.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 C9up
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,91 @@
+# @c9up/rover
+
+Mail transport for Ream — SMTP, log, and pluggable transports (Mailgun, SendGrid, SES, Resend), plus class-based mailers (`BaseMail`), async templating (`htmlView`), in-process retry with exponential backoff, and an optional queue path via `@c9up/bay`.
+
+## Quick start
+
+```ts
+import { Mail } from '@c9up/rover'
+import '@c9up/rover/transports/mailgun' // opt-in side-effect registration
+
+const mail = new Mail({
+  default: 'mailgun',
+  from: 'noreply@acme.com',
+  transports: {
+    mailgun: { transport: 'mailgun', apiKey: process.env.MAILGUN_KEY!, domain: 'mg.acme.com' },
+  },
+})
+
+await mail.send((m) => m.to('user@example.com').subject('Welcome').html('<p>Hi</p>'))
+```
+
+## Webhooks
+
+Providers push delivery events (`delivered`, `bounced`, `failed`) to a URL you configure. Rover ships signature-verifying middleware for Mailgun, SendGrid, and Resend that emit canonical `mail.*` events into your event bus.
+
+```ts
+import { createMailgunWebhookHandler } from '@c9up/rover/webhooks/mailgun'
+import { Emitter } from '@c9up/ream/events'
+
+const emitter = app.container.resolve(Emitter)
+
+router.post(
+  '/webhooks/mailgun',
+  createMailgunWebhookHandler({
+    signingKey: process.env.MAILGUN_SIGNING_KEY!,
+    emitter,
+    // maxAgeSeconds: 300 (default) — rejects replayed-old signatures
+  }),
+)
+```
+
+The handler verifies the HMAC over `timestamp + token`, enforces a ±5 minute replay window, and emits `mail.delivered` / `mail.bounced` / `mail.failed` on the bus. Invalid / stale / missing signatures return `401` without leaking internals.
+
+SendGrid (Ed25519 via `x-twilio-email-event-webhook-signature`) and Resend (Svix HMAC via `svix-signature`) use the same API shape:
+
+```ts
+import { createSendGridWebhookHandler } from '@c9up/rover/webhooks/sendgrid'
+import { createResendWebhookHandler } from '@c9up/rover/webhooks/resend'
+
+router.post('/webhooks/sendgrid', createSendGridWebhookHandler({
+  publicKey: process.env.SENDGRID_WEBHOOK_PUBLIC_KEY!,
+  emitter,
+}))
+
+router.post('/webhooks/resend', createResendWebhookHandler({
+  secret: process.env.RESEND_WEBHOOK_SECRET!, // accepts both `whsec_...` and raw base64
+  emitter,
+}))
+```
+
+### `rawBody()` contract
+
+All three handlers rely on `ctx.request.rawBody()` returning the exact bytes the provider signed. If your framework re-parses the body into JSON before the handler sees it and your `rawBody()` returns a re-serialised copy, bytes differ and every signature fails. Mount these handlers on a route where the raw body is preserved (e.g. skip the JSON body parser on `/webhooks/**`).
+
+## Queue / `sendLater`
+
+Register `@c9up/bay`'s `QueueManager` in your container and Rover will pick it up automatically:
+
+```ts
+import '@c9up/rover/transports/mailgun'
+import { QueueManager, MemoryDriver } from '@c9up/bay'
+
+app.container.singleton('QueueManager', () => new QueueManager(new MemoryDriver()))
+
+// Then in a request handler:
+await mail.sendLater((m) => m.to('user@acme.com').subject('Welcome').html('<p>Hi</p>'))
+// returns a job id string; the actual send runs on the Bay worker.
+```
+
+Without a `QueueManager` wired, `sendLater` throws `MAIL_QUEUE_REQUIRED`.
+
+## Testing
+
+```ts
+import '@c9up/rover/transports/mailgun' // register whatever transports your app uses
+
+const fake = mail.fake()
+await userRegistration({ email: 'user@acme.com' })
+fake.assertSent({ to: 'user@acme.com', subject: 'Welcome' })
+mail.restore()
+```

package/dist/BaseMail.d.ts

@@ -0,0 +1,28 @@
+import { type MailMessage, MessageBuilder } from "./MessageBuilder.js";
+export type MailAddress = string | {
+    address: string;
+    name: string;
+};
+/**
+ * Abstract base for class-based mail messages (Adonis parity).
+ *
+ *   class WelcomeMail extends BaseMail {
+ *     from = { address: "noreply@acme.com", name: "Acme" };
+ *     subject = "Welcome!";
+ *     constructor(private user: User) { super(); }
+ *     async prepare() {
+ *       this.message.to(this.user.email).html(...);
+ *     }
+ *   }
+ *
+ *   await mail.send(new WelcomeMail(user));
+ */
+export declare abstract class BaseMail {
+    protected readonly message: MessageBuilder;
+    from?: MailAddress;
+    subject?: string;
+    constructor();
+    abstract prepare(): void | Promise<void>;
+    build(): Promise<MailMessage>;
+}
+//# sourceMappingURL=BaseMail.d.ts.map

package/dist/BaseMail.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BaseMail.d.ts","sourceRoot":"","sources":["../src/BaseMail.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,WAAW,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAEvE,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAErE;;;;;;;;;;;;;GAaG;AACH,8BAAsB,QAAQ;IAC7B,SAAS,CAAC,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAwB;IAElE,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;;IAUjB,QAAQ,CAAC,OAAO,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAElC,KAAK,IAAI,OAAO,CAAC,WAAW,CAAC;CAUnC"}

package/dist/BaseMail.js

@@ -0,0 +1,42 @@
+import { MessageBuilder } from "./MessageBuilder.js";
+/**
+ * Abstract base for class-based mail messages (Adonis parity).
+ *
+ *   class WelcomeMail extends BaseMail {
+ *     from = { address: "noreply@acme.com", name: "Acme" };
+ *     subject = "Welcome!";
+ *     constructor(private user: User) { super(); }
+ *     async prepare() {
+ *       this.message.to(this.user.email).html(...);
+ *     }
+ *   }
+ *
+ *   await mail.send(new WelcomeMail(user));
+ */
+export class BaseMail {
+    message = new MessageBuilder();
+    from;
+    subject;
+    constructor() {
+        if (new.target === BaseMail) {
+            throw new Error("BaseMail is abstract and cannot be instantiated directly");
+        }
+    }
+    async build() {
+        if (this.from !== undefined) {
+            this.message.from(formatAddress(this.from));
+        }
+        if (this.subject !== undefined) {
+            this.message.subject(this.subject);
+        }
+        await this.prepare();
+        return this.message.build();
+    }
+}
+function formatAddress(addr) {
+    if (typeof addr === "string") {
+        return addr;
+    }
+    return `"${addr.name}" <${addr.address}>`;
+}
+//# sourceMappingURL=BaseMail.js.map

package/dist/BaseMail.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BaseMail.js","sourceRoot":"","sources":["../src/BaseMail.ts"],"names":[],"mappings":"AAAA,OAAO,EAAoB,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAIvE;;;;;;;;;;;;;GAaG;AACH,MAAM,OAAgB,QAAQ;IACV,OAAO,GAAmB,IAAI,cAAc,EAAE,CAAC;IAElE,IAAI,CAAe;IACnB,OAAO,CAAU;IAEjB;QACC,IAAI,GAAG,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;YAC7B,MAAM,IAAI,KAAK,CACd,0DAA0D,CAC1D,CAAC;QACH,CAAC;IACF,CAAC;IAID,KAAK,CAAC,KAAK;QACV,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;YAC7B,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;QAC7C,CAAC;QACD,IAAI,IAAI,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;YAChC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACpC,CAAC;QACD,MAAM,IAAI,CAAC,OAAO,EAAE,CAAC;QACrB,OAAO,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;IAC7B,CAAC;CACD;AAED,SAAS,aAAa,CAAC,IAAiB;IACvC,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC9B,OAAO,IAAI,CAAC;IACb,CAAC;IACD,OAAO,IAAI,IAAI,CAAC,IAAI,MAAM,IAAI,CAAC,OAAO,GAAG,CAAC;AAC3C,CAAC"}

package/dist/Mail.d.ts

@@ -0,0 +1,166 @@
+import { BaseMail } from "./BaseMail.js";
+import { type MailAttachment, type MailMessage, MessageBuilder } from "./MessageBuilder.js";
+import { type BayQueueLike } from "./queue/MailJob.js";
+import { type RetryConfig } from "./retry.js";
+import { FakeMail } from "./testing/FakeMail.js";
+export type { MailAttachment, MailMessage };
+export { MessageBuilder };
+/**
+ * Mail — send emails via pluggable transports.
+ *
+ * Like AdonisJS Mail:
+ *   await mail.send((message) => {
+ *     message.to('user@example.com')
+ *     message.subject('Welcome')
+ *     message.html('<h1>Hello</h1>')
+ *   })
+ *
+ * Transports: SMTP, log (dev), custom.
+ * Configured via config/mail.ts.
+ */
+export interface MailSendResult {
+    /** Provider-returned message id (Mailgun `mg-abc`, SendGrid `X-Message-Id`, etc.). */
+    providerId?: string;
+}
+/**
+ * Return shape of `MailTransport.send`. Transports that don't surface a
+ * provider id may `return` nothing (implicit `undefined`); transports that
+ * do return `{ providerId }`. `undefined` rather than `void` in the union
+ * keeps the linter happy (`noConfusingVoidType`) while preserving the
+ * "no result" semantics.
+ */
+export type MailSendOutcome = MailSendResult | undefined;
+export interface MailTransport {
+    send(message: MailMessage): Promise<MailSendOutcome>;
+}
+/**
+ * Structural interface for the event bus `Emitter` — peer-dep friendly.
+ * Rover never hard-imports the event bus.
+ */
+export interface EmitterLike {
+    emit(event: string, data: unknown): void;
+}
+export interface MailSentEvent {
+    messageId: string;
+    to: string[];
+    cc: string[];
+    bcc: string[];
+    transportName: string;
+    timestamp: number;
+}
+export interface MailFailedEvent {
+    messageId: string;
+    to: string[];
+    cc: string[];
+    bcc: string[];
+    transportName: string;
+    error: {
+        code: string;
+        message: string;
+        upstreamStatus?: number;
+        upstreamStatusRaw?: string;
+        attempts: number;
+    };
+    timestamp: number;
+}
+export interface MailConfig {
+    default: string;
+    from: string;
+    transports: Record<string, {
+        transport: string;
+        retry?: RetryConfig;
+        [key: string]: unknown;
+    }>;
+    /** Root directory for `htmlView(path, data)` template lookups. Default: `"resources/views/emails"`. */
+    viewsRoot?: string;
+    /** Optional Bay queue tuning for `sendLater()`. */
+    queue?: {
+        name?: string;
+        maxAttempts?: number;
+    };
+    /** Process-wide retry defaults. Overridden per-transport via `transports[name].retry`. */
+    retry?: RetryConfig;
+}
+/**
+ * Event hooks invoked by the internal dispatch loop. Default implementations
+ * are no-ops; when an event-bus `EmitterLike` is wired, the hooks emit
+ * `mail.sent` / `mail.failed`. Tests inject spies.
+ */
+export interface MailHooks {
+    onSent?(event: MailSentEvent): void;
+    onFailed?(event: MailFailedEvent): void;
+}
+/**
+ * Message builder — fluent API for composing an email.
+ */
+/**
+ * SMTP transport — thin wrapper around `nodemailer`. Nodemailer handles
+ * the SMTP state machine, TLS / STARTTLS negotiation, AUTH LOGIN /
+ * PLAIN / XOAUTH2, dot-stuffing, MIME assembly, attachments, and address
+ * encoding for 10+ years. We forward the `MailMessage` shape and surface
+ * the `messageId` returned by the server.
+ */
+export declare class SmtpTransport implements MailTransport {
+    #private;
+    constructor(config: Record<string, unknown>);
+    send(message: MailMessage): Promise<MailSendOutcome>;
+}
+/**
+ * Log transport — logs emails to console (development).
+ */
+export declare class LogTransport implements MailTransport {
+    send(message: MailMessage): Promise<MailSendOutcome>;
+}
+export type MailTransportFactory = (config: Record<string, unknown>) => MailTransport;
+/**
+ * Register a custom transport factory globally.
+ *
+ * @example
+ *   registerTransport('mailgun', (config) => new MailgunTransport(config))
+ *   // Now config/mail.ts can reference `transport: 'mailgun'`
+ */
+export declare function registerTransport(name: string, factory: MailTransportFactory): void;
+/**
+ * Mail manager — send emails via configured transport.
+ */
+export declare class Mail {
+    #private;
+    constructor(config: MailConfig, options?: {
+        queue?: BayQueueLike;
+        hooks?: MailHooks;
+        emitter?: EmitterLike;
+    });
+    /** Send an email using the fluent message builder. */
+    send(callback: (message: MessageBuilder) => void, transport?: string): Promise<void>;
+    /** Send an email using a class-based `BaseMail` instance. */
+    send(instance: BaseMail, transport?: string): Promise<void>;
+    /**
+     * Enqueue a send onto the Bay queue. Returns the job id. Throws
+     * `MAIL_QUEUE_REQUIRED` if no `QueueManager` was wired through the
+     * constructor options.
+     */
+    sendLater(arg: ((message: MessageBuilder) => void) | BaseMail, options?: {
+        transport?: string;
+        queue?: string;
+    }): Promise<string>;
+    /**
+     * Shared transport-resolve-then-send helper used by `send()` and `MailJobHandler`.
+     * Applies in-process retry with exponential backoff per `RetryConfig` resolution
+     * (per-transport > global > library default). Fires `onSent` / `onFailed` hooks.
+     *
+     * `overrideRetry` (optional) wins over config-level retry; `MailJobHandler` passes
+     * `{ maxAttempts: 1 }` so queue-level and sync-level retries don't compound.
+     */
+    dispatchMessage(message: MailMessage, transportName?: string, overrideRetry?: RetryConfig): Promise<void>;
+    /** Get a specific transport. */
+    use(name: string): MailTransport;
+    /**
+     * Swap the default transport with a `FakeMail` that captures every send.
+     * Call `restore()` to re-install the original. Throws if a fake is already
+     * active — nested fakes always indicate a forgotten `restore()`.
+     */
+    fake(): FakeMail;
+    /** Undo the swap installed by `fake()`. No-op if no fake is active. */
+    restore(): void;
+}
+//# sourceMappingURL=Mail.d.ts.map

package/dist/Mail.d.ts.map

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