adonisjs-groundmail 0.0.0-stage → 0.1.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Groundmail
+
+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

@@ -1,3 +1,128 @@
-# Temporary Holding Version
+<p align="center">
+  <a href="https://groundmail.dev">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://app.groundmail.dev/images/github/readme-logo-dark.png">
+      <img alt="Groundmail" src="https://app.groundmail.dev/images/github/readme-logo-light.png" height="44">
+    </picture>
+  </a>
+</p>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<h1 align="center">Groundmail for AdonisJS</h1>
+
+<p align="center">
+  An <a href="https://docs.adonisjs.com/guides/digging-deeper/mail">AdonisJS mail</a> transport for the Groundmail transactional email API.<br>
+  Keep <code>mail.send()</code> and your mail classes; deliver through Groundmail.
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/adonisjs-groundmail"><img alt="npm" src="https://img.shields.io/npm/v/adonisjs-groundmail?color=a3461f&label=npm"></a>
+  <a href="./LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-b48f62"></a>
+</p>
+
+<p align="center">
+  <a href="https://docs.groundmail.dev/frameworks/adonisjs">Docs</a> ·
+  <a href="https://app.groundmail.dev/signup">Get a free account</a> ·
+  <a href="https://groundmail.dev">groundmail.dev</a>
+</p>
+
+---
+
+Works with `@adonisjs/mail` 9 (AdonisJS 6) and 10 (AdonisJS 7).
+
+## Install
+
+```bash
+npm install adonisjs-groundmail
+```
+
+```bash
+GROUNDMAIL_API_KEY=gm_your_key_here
+```
+
+## Configure
+
+```ts
+// config/mail.ts
+import env from '#start/env'
+import { defineConfig } from '@adonisjs/mail'
+import { groundmailTransport } from 'adonisjs-groundmail'
+
+const mailConfig = defineConfig({
+  default: 'groundmail',
+  mailers: {
+    groundmail: groundmailTransport({
+      apiKey: env.get('GROUNDMAIL_API_KEY'),
+    }),
+  },
+})
+
+export default mailConfig
+
+declare module '@adonisjs/mail/types' {
+  export interface MailersList extends InferMailers<typeof mailConfig> {}
+}
+```
+
+Add `GROUNDMAIL_API_KEY: Env.schema.string()` to `start/env.ts`.
+
+## Send
+
+```ts
+import mail from '@adonisjs/mail/services/main'
+
+await mail.send((message) => {
+  message
+    .from('noreply@yourdomain.com')
+    .to(user.email)
+    .subject('Verify your email address')
+    .htmlView('emails/verify_email', { user })
+})
+```
+
+Attachments from `message.attach()`, `attachData()` and `embed()` are read and sent with the message. Queued mail (`mail.sendLater`) works the same way.
+
+## Groundmail headers
+
+```ts
+message.header('X-Groundmail-Tag', 'flow=signup')
+message.header('X-Groundmail-Idempotency-Key', `verify-${user.id}`)
+```
+
+| Header | Purpose |
+|--------|---------|
+| `X-Groundmail-Tag` | `name=value` tag (repeatable) |
+| `X-Groundmail-Idempotency-Key` | Send once, even when your code retries |
+| `X-Groundmail-Scheduled-At` | ISO 8601 time to send later |
+
+## Contributing
+
+Found a bug or want something added? [Open an issue](https://github.com/Groundmail/adonisjs-groundmail/issues). This code is published here on each release, so we port fixes rather than merging pull requests directly. The HTTP client itself is the [`groundmail`](https://www.npmjs.com/package/groundmail) package.
+
+## Why Groundmail
+
+- **Our own mail servers and IP space.** Your password resets and receipts don't share a pool with bulk marketing senders.
+- **Transactional email only.** No newsletters or cold outreach on the platform, which keeps the sending reputation clean.
+- **Start free.** 3,000 emails a month on the Free plan; Pro is 50,000 emails for $20/month. Dedicated IPs on Scale.
+- **Built for code and for agents.** REST API, SMTP, SDKs for Node, Python, Go, PHP and Ruby, a CLI, and an MCP server for Claude, ChatGPT and Cursor.
+
+## All Groundmail libraries
+
+| Use | Package |
+|-----|---------|
+| Node.js / TypeScript | [`groundmail`](https://www.npmjs.com/package/groundmail) on npm |
+| Python (Django), Go, Ruby (Rails Action Mailer) | [Groundmail/groundmail-sdks](https://github.com/Groundmail/groundmail-sdks) |
+| PHP | [Groundmail/groundmail-php](https://github.com/Groundmail/groundmail-php) |
+| Laravel | [Groundmail/groundmail-laravel](https://github.com/Groundmail/groundmail-laravel) |
+| Symfony Mailer | [Groundmail/groundmail-symfony-mailer](https://github.com/Groundmail/groundmail-symfony-mailer) |
+| Nodemailer | [Groundmail/groundmail-nodemailer](https://github.com/Groundmail/groundmail-nodemailer) |
+| NestJS | [Groundmail/nestjs-groundmail](https://github.com/Groundmail/nestjs-groundmail) |
+| Strapi | [Groundmail/strapi-provider-email-groundmail](https://github.com/Groundmail/strapi-provider-email-groundmail) |
+| Medusa | [Groundmail/medusa-notification-groundmail](https://github.com/Groundmail/medusa-notification-groundmail) |
+| AdonisJS | [Groundmail/adonisjs-groundmail](https://github.com/Groundmail/adonisjs-groundmail) |
+| Phoenix (Swoosh) | [Groundmail/swoosh_groundmail](https://github.com/Groundmail/swoosh_groundmail) |
+| CLI | [`groundmail-cli`](https://www.npmjs.com/package/groundmail-cli) on npm |
+| MCP server (Claude, ChatGPT, Cursor) | [Groundmail/groundmail-mcp](https://github.com/Groundmail/groundmail-mcp) |
+| Agent skills and Claude Code plugin | [Groundmail/groundmail-skills](https://github.com/Groundmail/groundmail-skills) |
+| Email templates (React Email, MJML, HTML) | [Groundmail/email-templates](https://github.com/Groundmail/email-templates) |
+
+[Website](https://groundmail.dev) · [Docs](https://docs.groundmail.dev) · [Pricing](https://groundmail.dev/pricing) · [Sign up free](https://app.groundmail.dev/signup)

package/dist/index.d.ts

@@ -0,0 +1,37 @@
+import { MailResponse } from '@adonisjs/mail';
+import { MailTransportContract, NodeMailerMessage, MailManagerTransportFactory } from '@adonisjs/mail/types';
+import { GroundmailTransportOptions } from 'groundmail-nodemailer';
+
+type GroundmailConfig = {
+    /** Groundmail API key (`gm_…`). Falls back to `GROUNDMAIL_API_KEY`. */
+    apiKey?: string;
+    /** Override the API base URL. */
+    baseUrl?: string;
+    /** Prebuilt client (tests, shared clients). */
+    client?: GroundmailTransportOptions['client'];
+};
+type GroundmailSentMessageInfo = {
+    messageId: string;
+    envelope: {
+        from: string | false;
+        to: string[];
+    };
+    accepted: string[];
+    response: string;
+};
+/** AdonisJS mail transport that sends through the Groundmail HTTP API. */
+declare class GroundmailTransport implements MailTransportContract {
+    private readonly config;
+    constructor(config?: GroundmailConfig);
+    send(message: NodeMailerMessage, config?: GroundmailConfig): Promise<MailResponse<GroundmailSentMessageInfo>>;
+}
+/**
+ * Define a Groundmail mailer in `config/mail.ts`:
+ *
+ * ```ts
+ * mailers: { groundmail: groundmailTransport({ apiKey: env.get('GROUNDMAIL_API_KEY') }) }
+ * ```
+ */
+declare function groundmailTransport(config?: GroundmailConfig): MailManagerTransportFactory;
+
+export { type GroundmailConfig, type GroundmailSentMessageInfo, GroundmailTransport, groundmailTransport };

package/dist/index.js

@@ -0,0 +1,52 @@
+// src/transport.ts
+import { createTransport } from "nodemailer";
+import { MailResponse } from "@adonisjs/mail";
+import { createGroundmailTransport } from "groundmail-nodemailer";
+function resolvingTransport(inner) {
+  return {
+    name: inner.name,
+    version: inner.version,
+    send(mail, callback) {
+      const attachments = mail.data.attachments ?? [];
+      Promise.all(
+        attachments.map(async (attachment) => {
+          if (Buffer.isBuffer(attachment.content) || typeof attachment.content === "string") {
+            if (!attachment.path && !attachment.href) return;
+          }
+          const source = attachment.path ? { path: attachment.path } : attachment.href ? { href: attachment.href } : attachment.content;
+          attachment.content = await mail.resolveContent({ content: source }, "content");
+          delete attachment.path;
+          delete attachment.href;
+        })
+      ).then(
+        () => inner.send(mail, callback),
+        (error) => callback(error, void 0)
+      );
+    }
+  };
+}
+var GroundmailTransport = class {
+  constructor(config = {}) {
+    this.config = config;
+  }
+  config;
+  async send(message, config) {
+    const options = { ...this.config, ...config };
+    const apiKey = options.apiKey || process.env.GROUNDMAIL_API_KEY;
+    if (!options.client && !apiKey) {
+      throw new Error("Groundmail API key is missing. Set apiKey in config/mail.ts or GROUNDMAIL_API_KEY.");
+    }
+    const transport = createTransport(
+      resolvingTransport(createGroundmailTransport({ apiKey: apiKey ?? "", baseUrl: options.baseUrl, client: options.client }))
+    );
+    const info = await transport.sendMail(message);
+    return new MailResponse(info.messageId, info.envelope, info);
+  }
+};
+function groundmailTransport(config = {}) {
+  return () => new GroundmailTransport(config);
+}
+export {
+  GroundmailTransport,
+  groundmailTransport
+};

package/package.json

@@ -1,6 +1,67 @@
 {
   "name": "adonisjs-groundmail",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.3",
+  "description": "AdonisJS mail transport for Groundmail transactional email (@adonisjs/mail)",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Groundmail/adonisjs-groundmail.git"
+  },
+  "homepage": "https://docs.groundmail.dev/frameworks/adonisjs",
+  "bugs": {
+    "url": "https://github.com/Groundmail/adonisjs-groundmail/issues"
+  },
+  "keywords": [
+    "adonisjs",
+    "adonis",
+    "adonisjs-mail",
+    "adonis-mail",
+    "mail-transport",
+    "email",
+    "transactional-email",
+    "groundmail"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20.6.0"
+  },
+  "peerDependencies": {
+    "@adonisjs/mail": "^9.0.0 || ^10.0.0"
+  },
+  "dependencies": {
+    "groundmail": ">=0.14.5 <1.0.0",
+    "groundmail-nodemailer": ">=0.14.5 <1.0.0",
+    "nodemailer": ">=6.9.0"
+  },
+  "devDependencies": {
+    "@adonisjs/core": "^7.0.0",
+    "@adonisjs/mail": "^10.4.0",
+    "@types/node": "^22",
+    "@types/nodemailer": "^8.0.1",
+    "tsup": "^8.5.0",
+    "typescript": "^5",
+    "vitest": "^3.2.4"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --target node20 --clean",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  }
+}