groundmail 0.0.0-stage → 0.14.1

package/README.md

@@ -1,3 +1,49 @@
-# Temporary Holding Version
+# groundmail
 
-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.
+Official Node.js / TypeScript client for the [Groundmail](https://groundmail.dev) transactional email API.
+
+```bash
+npm install groundmail
+```
+
+```bash
+export GROUNDMAIL_API_KEY=gm_your_key_here
+```
+
+```ts
+import { Groundmail } from 'groundmail'
+
+const tx = new Groundmail(process.env.GROUNDMAIL_API_KEY!)
+
+const email = await tx.emails.send({
+  from: 'ops@yourdomain.com',
+  to: 'user@example.com',
+  subject: 'Your receipt',
+  html: '<p>Thanks for your purchase.</p>',
+})
+
+console.log(email.id, email.status)
+```
+
+## Adapters
+
+Optional entry points (install peer deps as needed):
+
+| Import | Package / peer |
+|--------|----------------|
+| `groundmail/nodemailer` | [groundmail-nodemailer](https://www.npmjs.com/package/groundmail-nodemailer) + `nodemailer` |
+| `groundmail/better-auth` | [groundmail-better-auth](https://www.npmjs.com/package/groundmail-better-auth) |
+| `groundmail/authjs` | [groundmail-authjs](https://www.npmjs.com/package/groundmail-authjs) |
+| `groundmail/clerk` | [groundmail-clerk](https://www.npmjs.com/package/groundmail-clerk) |
+| `groundmail/payload` | [groundmail-payload](https://www.npmjs.com/package/groundmail-payload) |
+
+## Docs
+
+- Quickstart: https://docs.groundmail.dev/quickstart
+- Node / Nodemailer: https://docs.groundmail.dev/frameworks/node
+- API reference: https://docs.groundmail.dev/api/emails
+- Product: https://groundmail.dev
+
+## License
+
+MIT

package/dist/authjs.d.ts

@@ -0,0 +1,72 @@
+import { G as Groundmail } from './client-DdrSVDkA.js';
+
+/** Subset of Auth.js theme used for the default magic-link email. */
+type AuthjsTheme = {
+    brandColor?: string;
+    buttonText?: string;
+};
+/**
+ * Minimal Auth.js email-provider config shape.
+ * Compatible with `next-auth` / `@auth/core` `EmailConfig` without requiring those packages at build time.
+ */
+type AuthjsEmailConfig = {
+    id: string;
+    type: 'email';
+    name: string;
+    from: string;
+    maxAge: number;
+    apiKey?: string;
+    sendVerificationRequest: (params: {
+        identifier: string;
+        url: string;
+        expires: Date;
+        provider: AuthjsEmailConfig;
+        token: string;
+        theme: AuthjsTheme;
+        request: Request;
+    }) => Promise<void>;
+    options: GroundmailAuthjsOptions;
+};
+type GroundmailAuthjsOptions = {
+    /** Verified sender, e.g. `Auth <noreply@yourdomain.com>`. Defaults to a placeholder that you must override for production. */
+    from?: string;
+    /** Groundmail API key (`gm_…`). Falls back to `AUTH_GROUNDMAIL_KEY` then `GROUNDMAIL_API_KEY`. */
+    apiKey?: string;
+    /** Override API base URL (tests / self-hosted). */
+    baseUrl?: string;
+    /** Injected client (tests). */
+    client?: Groundmail;
+    /** Token lifetime in seconds (Auth.js default is 24h). */
+    maxAge?: number;
+    /** Override the default HTML/text templates. */
+    sendVerificationRequest?: AuthjsEmailConfig['sendVerificationRequest'];
+    /** Provider id in Auth.js (default `groundmail`). */
+    id?: string;
+    /** Display name in Auth.js (default `Groundmail`). */
+    name?: string;
+};
+/**
+ * Auth.js / NextAuth email provider for Groundmail.
+ *
+ * Drop-in for magic-link sign-in. Requires a database adapter (Auth.js stores
+ * verification tokens).
+ *
+ * @example
+ * ```ts
+ * import NextAuth from 'next-auth'
+ * import Groundmail from 'groundmail-authjs'
+ *
+ * export const { handlers, auth, signIn, signOut } = NextAuth({
+ *   adapter: ...,
+ *   providers: [
+ *     Groundmail({
+ *       from: 'noreply@yourdomain.com',
+ *       // apiKey: process.env.GROUNDMAIL_API_KEY, // or AUTH_GROUNDMAIL_KEY
+ *     }),
+ *   ],
+ * })
+ * ```
+ */
+declare function GroundmailAuthjs(config?: GroundmailAuthjsOptions): AuthjsEmailConfig;
+
+export { type AuthjsEmailConfig, type AuthjsTheme, GroundmailAuthjs, type GroundmailAuthjsOptions, GroundmailAuthjs as default };

package/dist/authjs.js

@@ -0,0 +1,101 @@
+import {
+  DEFAULT_API_BASE_URL,
+  Groundmail
+} from "./chunk-IZYE7HGT.js";
+
+// src/authjs.ts
+function escapeHtml(value) {
+  return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;");
+}
+function signInHtml(params) {
+  const { url, host, theme } = params;
+  const escapedHost = escapeHtml(host.replace(/\./g, ".\u200B"));
+  const brandColor = theme.brandColor || "#0f766e";
+  const buttonText = theme.buttonText || "#fff";
+  const safeUrl = escapeHtml(url);
+  return `
+<body style="background:#f8fafc;">
+  <table width="100%" border="0" cellspacing="20" cellpadding="0"
+    style="background:#ffffff; max-width:600px; margin:auto; border-radius:10px;">
+    <tr>
+      <td align="center"
+        style="padding:10px 0; font-size:22px; font-family:Helvetica,Arial,sans-serif; color:#334155;">
+        Sign in to <strong>${escapedHost}</strong>
+      </td>
+    </tr>
+    <tr>
+      <td align="center" style="padding:20px 0;">
+        <a href="${safeUrl}" target="_blank"
+          style="font-size:18px; font-family:Helvetica,Arial,sans-serif; color:${buttonText}; text-decoration:none; border-radius:5px; padding:10px 20px; border:1px solid ${brandColor}; display:inline-block; font-weight:bold; background:${brandColor};">
+          Sign in
+        </a>
+      </td>
+    </tr>
+    <tr>
+      <td align="center"
+        style="padding:0 0 10px; font-size:16px; line-height:22px; font-family:Helvetica,Arial,sans-serif; color:#64748b;">
+        If you did not request this email you can safely ignore it.
+      </td>
+    </tr>
+  </table>
+</body>
+`;
+}
+function signInText(params) {
+  return `Sign in to ${params.host}
+${params.url}
+
+`;
+}
+function resolveApiKey(options) {
+  return options.apiKey ?? (typeof process !== "undefined" ? process.env.AUTH_GROUNDMAIL_KEY ?? process.env.GROUNDMAIL_API_KEY : void 0);
+}
+function GroundmailAuthjs(config = {}) {
+  const apiKey = resolveApiKey(config);
+  const from = (config.from ?? "Groundmail <noreply@mail.groundmail.dev>").trim();
+  if (!from) {
+    throw new Error("GroundmailAuthjs requires a non-empty `from` address");
+  }
+  const provider = {
+    id: config.id ?? "groundmail",
+    type: "email",
+    name: config.name ?? "Groundmail",
+    from,
+    maxAge: config.maxAge ?? 24 * 60 * 60,
+    apiKey,
+    options: config,
+    async sendVerificationRequest(params) {
+      if (config.sendVerificationRequest) {
+        await config.sendVerificationRequest(params);
+        return;
+      }
+      const { identifier: to, provider: prov, url, theme } = params;
+      const client = config.client ?? (() => {
+        const key = prov.apiKey ?? resolveApiKey(config);
+        if (!key) {
+          throw new Error(
+            "Groundmail Auth.js provider requires `apiKey`, AUTH_GROUNDMAIL_KEY, or GROUNDMAIL_API_KEY"
+          );
+        }
+        return new Groundmail(key, {
+          baseUrl: config.baseUrl ?? DEFAULT_API_BASE_URL
+        });
+      })();
+      const { host } = new URL(url);
+      await client.emails.send({
+        from: prov.from,
+        to,
+        subject: `Sign in to ${host}`,
+        html: signInHtml({ url, host, theme }),
+        text: signInText({ url, host }),
+        tags: [{ name: "auth", value: "authjs-magic-link" }]
+      });
+    }
+  };
+  return provider;
+}
+var authjs_default = GroundmailAuthjs;
+export {
+  GroundmailAuthjs,
+  authjs_default as default
+};

package/dist/better-auth.d.ts

@@ -0,0 +1,122 @@
+import { S as SendEmailResult, G as Groundmail } from './client-DdrSVDkA.js';
+
+type BetterAuthEmailUser = {
+    email: string;
+    name?: string | null;
+    id?: string;
+};
+type BetterAuthEmailContext = {
+    user: BetterAuthEmailUser;
+    url: string;
+    token?: string;
+};
+type BetterAuthMagicLinkContext = {
+    email: string;
+    url: string;
+    token?: string;
+    metadata?: unknown;
+};
+type BetterAuthEmailOtpType = 'sign-in' | 'email-verification' | 'forget-password' | string;
+type BetterAuthEmailOtpContext = {
+    email: string;
+    otp: string;
+    type: BetterAuthEmailOtpType;
+};
+type BetterAuthInvitationContext = {
+    email: string;
+    id?: string;
+    role?: string;
+    organization?: {
+        name?: string | null;
+    };
+    inviter?: {
+        user?: {
+            name?: string | null;
+            email?: string | null;
+        };
+    };
+    invitation?: {
+        id?: string;
+    };
+};
+type BetterAuthEmailOptions = {
+    /** Verified sender, e.g. `noreply@yourdomain.com`. */
+    from: string;
+    apiKey?: string;
+    baseUrl?: string;
+    /** Prebuilt client (tests / advanced wiring). */
+    client?: Groundmail;
+    /**
+     * When true (default), callbacks do not await the API call so Better Auth
+     * request timing is less coupled to delivery. Errors are logged.
+     */
+    fireAndForget?: boolean;
+    /** Base URL used to build organization invite links when only an id is provided. */
+    appUrl?: string;
+};
+type BetterAuthEmailHelpers = {
+    /** Low-level send used by the Better Auth callbacks. */
+    sendAuthEmail: (params: {
+        to: string;
+        subject: string;
+        html: string;
+        text?: string;
+        tag?: string;
+    }) => Promise<SendEmailResult>;
+    /** Core: `emailVerification.sendVerificationEmail` */
+    sendVerificationEmail: (ctx: BetterAuthEmailContext, request?: unknown) => Promise<void>;
+    /** Core: `emailAndPassword.sendResetPassword` */
+    sendResetPassword: (ctx: BetterAuthEmailContext, request?: unknown) => Promise<void>;
+    /** Plugin: `magicLink({ sendMagicLink })` — see https://www.better-auth.com/docs/plugins/magic-link */
+    sendMagicLink: (ctx: BetterAuthMagicLinkContext, request?: unknown) => Promise<void>;
+    /** Plugin: `emailOTP({ sendVerificationOTP })` — see https://better-auth.com/docs/plugins/email-otp */
+    sendVerificationOTP: (ctx: BetterAuthEmailOtpContext, request?: unknown) => Promise<void>;
+    /** Plugin: `organization({ sendInvitationEmail })` */
+    sendInvitationEmail: (ctx: BetterAuthInvitationContext, request?: unknown) => Promise<void>;
+    /**
+     * Generic link email for custom flows.
+     * Pass your own subject + tag.
+     */
+    sendLinkEmail: (ctx: BetterAuthEmailContext & {
+        subject: string;
+        tag?: string;
+    }, request?: unknown) => Promise<void>;
+};
+/**
+ * Groundmail helpers for Better Auth email callbacks.
+ *
+ * Better Auth’s [plugin catalog](https://better-auth.com/docs/plugins) covers
+ * Magic Link, Email OTP, Organization, etc. There is no third-party “email
+ * provider” plugin slot. Delivery is always a callback you supply on core
+ * config and on those plugins. This helper returns those callbacks.
+ *
+ * @example
+ * ```ts
+ * import { betterAuth } from 'better-auth'
+ * import { magicLink } from 'better-auth/plugins'
+ * import { emailOTP } from 'better-auth/plugins'
+ * import { createBetterAuthEmail } from 'groundmail-better-auth'
+ *
+ * const email = createBetterAuthEmail({
+ *   from: 'noreply@yourdomain.com',
+ *   apiKey: process.env.GROUNDMAIL_API_KEY!,
+ * })
+ *
+ * export const auth = betterAuth({
+ *   emailVerification: {
+ *     sendVerificationEmail: email.sendVerificationEmail,
+ *   },
+ *   emailAndPassword: {
+ *     enabled: true,
+ *     sendResetPassword: email.sendResetPassword,
+ *   },
+ *   plugins: [
+ *     magicLink({ sendMagicLink: email.sendMagicLink }),
+ *     emailOTP({ sendVerificationOTP: email.sendVerificationOTP }),
+ *   ],
+ * })
+ * ```
+ */
+declare function createBetterAuthEmail(options: BetterAuthEmailOptions): BetterAuthEmailHelpers;
+
+export { type BetterAuthEmailContext, type BetterAuthEmailHelpers, type BetterAuthEmailOptions, type BetterAuthEmailOtpContext, type BetterAuthEmailOtpType, type BetterAuthEmailUser, type BetterAuthInvitationContext, type BetterAuthMagicLinkContext, createBetterAuthEmail };

package/dist/better-auth.js

@@ -0,0 +1,148 @@
+import {
+  DEFAULT_API_BASE_URL,
+  Groundmail
+} from "./chunk-IZYE7HGT.js";
+
+// src/better-auth.ts
+function linkHtml(label, url) {
+  const safe = escapeHtml(url);
+  return `<p>${escapeHtml(label)}: <a href="${safe}">${safe}</a></p>`;
+}
+function escapeHtml(value) {
+  return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;");
+}
+function otpSubject(type) {
+  switch (type) {
+    case "sign-in":
+      return "Your sign-in code";
+    case "email-verification":
+      return "Your verification code";
+    case "forget-password":
+      return "Your password reset code";
+    default:
+      return "Your verification code";
+  }
+}
+function createBetterAuthEmail(options) {
+  const from = options.from.trim();
+  if (!from) {
+    throw new Error("createBetterAuthEmail requires a non-empty `from` address");
+  }
+  let client = options.client;
+  if (!client) {
+    const apiKey = options.apiKey ?? process.env.GROUNDMAIL_API_KEY;
+    if (!apiKey) {
+      throw new Error("createBetterAuthEmail requires `apiKey` or GROUNDMAIL_API_KEY");
+    }
+    client = new Groundmail(apiKey, {
+      baseUrl: options.baseUrl ?? DEFAULT_API_BASE_URL
+    });
+  }
+  const fireAndForget = options.fireAndForget !== false;
+  const appUrl = options.appUrl?.replace(/\/$/, "");
+  const sendAuthEmail = async (params) => {
+    return client.emails.send({
+      from,
+      to: params.to,
+      subject: params.subject,
+      html: params.html,
+      text: params.text,
+      tags: params.tag ? [{ name: "auth", value: params.tag }] : [{ name: "auth", value: "transactional" }]
+    });
+  };
+  const run = async (work) => {
+    if (!fireAndForget) {
+      await work();
+      return;
+    }
+    void work().catch((error) => {
+      console.error("[groundmail/better-auth] failed to send auth email", error);
+    });
+  };
+  const sendLinkEmail = async (ctx) => {
+    const to = ctx.user.email?.trim();
+    if (!to) throw new Error("Better Auth user is missing an email address");
+    await run(
+      () => sendAuthEmail({
+        to,
+        subject: ctx.subject,
+        html: linkHtml(ctx.subject, ctx.url),
+        text: `${ctx.subject}: ${ctx.url}`,
+        tag: ctx.tag
+      })
+    );
+  };
+  return {
+    sendAuthEmail,
+    sendVerificationEmail: async (ctx) => {
+      await sendLinkEmail({
+        ...ctx,
+        subject: "Verify your email",
+        tag: "verify"
+      });
+    },
+    sendResetPassword: async (ctx) => {
+      await sendLinkEmail({
+        ...ctx,
+        subject: "Reset your password",
+        tag: "reset"
+      });
+    },
+    sendMagicLink: async (ctx) => {
+      const to = ctx.email?.trim();
+      if (!to) throw new Error("Magic link email is missing");
+      await run(
+        () => sendAuthEmail({
+          to,
+          subject: "Your sign-in link",
+          html: linkHtml("Sign in", ctx.url),
+          text: `Sign in: ${ctx.url}`,
+          tag: "magic-link"
+        })
+      );
+    },
+    sendVerificationOTP: async (ctx) => {
+      const to = ctx.email?.trim();
+      if (!to) throw new Error("OTP email is missing");
+      const subject = otpSubject(ctx.type);
+      const otp = String(ctx.otp ?? "").trim();
+      if (!otp) throw new Error("OTP value is missing");
+      await run(
+        () => sendAuthEmail({
+          to,
+          subject,
+          html: `<p>Your code is <strong>${escapeHtml(otp)}</strong></p>`,
+          text: `Your code is ${otp}`,
+          tag: `otp-${ctx.type}`
+        })
+      );
+    },
+    sendInvitationEmail: async (ctx) => {
+      const to = ctx.email?.trim();
+      if (!to) throw new Error("Invitation email is missing");
+      const inviteId = ctx.id ?? ctx.invitation?.id;
+      const inviteLink = inviteId && appUrl ? `${appUrl}/accept-invitation/${inviteId}` : inviteId ? `/accept-invitation/${inviteId}` : null;
+      if (!inviteLink) {
+        throw new Error(
+          "sendInvitationEmail needs an invitation id (and ideally `appUrl` on createBetterAuthEmail)"
+        );
+      }
+      const org = ctx.organization?.name?.trim() || "the organization";
+      const inviter = ctx.inviter?.user?.name?.trim() || ctx.inviter?.user?.email?.trim() || "A teammate";
+      const subject = `Join ${org}`;
+      await run(
+        () => sendAuthEmail({
+          to,
+          subject,
+          html: `<p>${escapeHtml(inviter)} invited you to join <strong>${escapeHtml(org)}</strong>.</p>${linkHtml("Accept invitation", inviteLink)}`,
+          text: `${inviter} invited you to join ${org}. Accept: ${inviteLink}`,
+          tag: "invite"
+        })
+      );
+    },
+    sendLinkEmail
+  };
+}
+export {
+  createBetterAuthEmail
+};