@numoteq/emdash-plugin-jetemail 0.3.0 → 0.4.0

package/README.md

@@ -11,21 +11,22 @@ pnpm add @numoteq/emdash-plugin-jetemail
 Register the package in the site's sandboxed plugin configuration, activate it, then select **JetEmail** under **Settings > Email**. Open the plugin settings and enter:
 
 - A JetEmail transactional API key (`transactional_…`) allowed to send from the sender's domain.
-- The sender name and email. The sender domain must be verified in JetEmail.
+- The sender email. The sender domain must be verified in JetEmail.
+- Optionally the sender name (defaults to the site title) and a Reply-To address.
 
 If the domain publishes JetEmail Domain Security (`_jm` TXT), add the API key's UUID to it, otherwise JetEmail rejects the message.
 
-The key is stored in the plugin-scoped KV store and is sent only to `https://api.jetemail.com/email`. The plugin requests only the fixed-host network and email transport registration capabilities. Recipients, CC and reply-to are passed through; EmDash email has no attachments.
+The key is stored in the plugin-scoped KV store and is sent only to `https://api.jetemail.com/email`. The plugin requests only the fixed-host network and email transport registration capabilities. Recipients, CC and reply-to are passed through; a message's own reply-to wins over the configured one. EmDash email has no attachments.
 
 ## Native use (Cloudflare Workers sites)
 
-Sites that configure EmDash in code can register the transport in `astro.config.mjs` instead; the API key then lives in a Worker secret and nothing is set in the admin:
+Sites that configure EmDash in code register the transport in `astro.config.mjs` instead; the API key lives in a Worker secret and nothing is set in the admin:
 
 ```js
 import { jetEmail } from "@numoteq/emdash-plugin-jetemail/native";
 
 emdash({
-	plugins: [jetEmail({ from: { email: "noreply@example.com", name: "Example" } })],
+	plugins: [jetEmail({ from: { email: "noreply@example.com" }, replyTo: "info@example.com" })],
 });
 ```
 
@@ -33,18 +34,30 @@ emdash({
 wrangler secret put JETEMAIL_API_KEY
 ```
 
-Activate it under **Admin > Extensions** and select it under **Settings > Email**. Site code (contact forms) can send through the same client:
+- `from.name` is optional and defaults to the site title (Settings > General).
+- `replyTo` applies when a message sets none.
+- EmDash selects the provider automatically when it is the only one.
 
-```ts
-import { deliverWithJetEmail } from "@numoteq/emdash-plugin-jetemail/client";
+Site code (forms, Workflows) sends through the same sender with `sendEmail`, which also supports attachments. It throws on failure; a `JetEmailError` carries the HTTP status.
 
-await deliverWithJetEmail(
-	fetch,
-	{ apiToken, fromName: "Example", fromEmail: "noreply@example.com" },
-	message,
-);
+```ts
+import { sendEmail } from "@numoteq/emdash-plugin-jetemail/native";
+
+await sendEmail(mailConfig, {
+	to: "team@example.com",
+	replyTo: visitorEmail,
+	subject: "New enquiry",
+	text,
+	attachments: [{ filename: "offer.pdf", content: pdfBytes }],
+});
 ```
 
+Pass the same config object to `jetEmail()` and `sendEmail()`, for example from a shared `src/mail-config.ts`.
+
+### E2E and local runs without a key
+
+With the Worker variable `JETEMAIL_DRY_RUN` set to exactly `true`, nothing is sent: each message is logged as a warning (from, to, reply-to, subject) and reported as sent. Set it only in the E2E Wrangler config, never in production. Without it, a missing `JETEMAIL_API_KEY` fails the send.
+
 ## Development
 
 ```sh

package/dist/client.d.mts

@@ -19,9 +19,14 @@ interface JetEmailMessage {
   attachments?: JetEmailAttachment[];
 }
 type FetchFn = (url: string, init?: RequestInit) => Promise<Response>;
+/** JetEmail answered with a non-2xx status. HTTP 429 means the message was not accepted. */
+declare class JetEmailError extends Error {
+  readonly status: number;
+  constructor(message: string, status: number);
+}
 declare function formatSender(name: string, email: string): string;
 declare function deliverWithJetEmail(fetchFn: FetchFn, sender: JetEmailSender, message: JetEmailMessage): Promise<{
   id?: string;
 }>;
 //#endregion
-export { FetchFn, JetEmailAttachment, JetEmailMessage, JetEmailSender, deliverWithJetEmail, formatSender };
+export { FetchFn, JetEmailAttachment, JetEmailError, JetEmailMessage, JetEmailSender, deliverWithJetEmail, formatSender };

package/dist/client.mjs

@@ -1,5 +1,13 @@
 //#region src/client.ts
 const API_URL = "https://api.jetemail.com/email";
+/** JetEmail answered with a non-2xx status. HTTP 429 means the message was not accepted. */
+var JetEmailError = class extends Error {
+	constructor(message, status) {
+		super(message);
+		this.status = status;
+		this.name = "JetEmailError";
+	}
+};
 function formatSender(name, email) {
 	return `${name.replace(/[<>"\r\n]/g, "").trim()} <${email}>`;
 }
@@ -33,11 +41,11 @@ async function deliverWithJetEmail(fetchFn, sender, message) {
 	});
 	if (!response.ok) {
 		const detail = (await response.text()).slice(0, 500);
-		throw new Error(`JetEmail rejected the message with HTTP ${response.status}${detail ? `: ${detail}` : ""}`);
+		throw new JetEmailError(`JetEmail rejected the message with HTTP ${response.status}${detail ? `: ${detail}` : ""}`, response.status);
 	}
 	const result = await response.json().catch(() => ({}));
 	return typeof result.id === "string" ? { id: result.id } : {};
 }
 
 //#endregion
-export { deliverWithJetEmail, formatSender };
+export { JetEmailError, deliverWithJetEmail, formatSender };

package/dist/{config-DcMo9a49.d.mts → config-BaMQYoEl.d.mts}

@@ -1,9 +1,12 @@
 //#region src/native/config.d.ts
 interface JetEmailConfig {
-  /** Sender. The domain must be verified in JetEmail and allowed for the API key. */
+  /**
+   * Sender. The domain must be verified in JetEmail and allowed for the API key.
+   * The name defaults to the site title from EmDash settings.
+   */
   from: {
     email: string;
-    name: string;
+    name?: string;
   };
   /** Reply-To used when the message sets none. */
   replyTo?: string;

package/dist/index.mjs

@@ -7,7 +7,7 @@
 /** @type {import("emdash").PluginDescriptor} */
 const descriptor = Object.freeze({
 	"id": "jetemail",
-	"version": "0.3.0",
+	"version": "0.4.0",
 	"format": "standard",
 	"entrypoint": "@numoteq/emdash-plugin-jetemail/sandbox",
 	"capabilities": [

package/dist/manifest.json

@@ -1,6 +1,6 @@
 {
   "id": "jetemail",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "declaredAccess": {
     "network": {
       "request": {

package/dist/native/index.d.mts

@@ -1,4 +1,5 @@
-import { t as JetEmailConfig } from "../config-DcMo9a49.mjs";
+import { JetEmailAttachment, JetEmailError, JetEmailMessage } from "../client.mjs";
+import { t as JetEmailConfig } from "../config-BaMQYoEl.mjs";
 import { PluginDescriptor } from "emdash";
 
 //#region src/native/index.d.ts
@@ -7,5 +8,13 @@ import { PluginDescriptor } from "emdash";
  * delivery time from a Worker secret (default `JETEMAIL_API_KEY`), so nothing is configured in the admin.
  */
 declare function jetEmail(config: JetEmailConfig): PluginDescriptor<JetEmailConfig>;
+/**
+ * Sends a message from site code (forms, Workflows) with the same sender as {@link jetEmail}.
+ * Supports attachments, which EmDash email cannot carry. Throws on failure; a
+ * {@link JetEmailError} carries the HTTP status.
+ */
+declare function sendEmail(config: JetEmailConfig, message: JetEmailMessage): Promise<{
+  id?: string;
+}>;
 //#endregion
-export { type JetEmailConfig, jetEmail as default, jetEmail };
+export { type JetEmailAttachment, type JetEmailConfig, JetEmailError, type JetEmailMessage, jetEmail as default, jetEmail, sendEmail };

package/dist/native/index.mjs

@@ -1,4 +1,5 @@
-import { n as PLUGIN_VERSION, r as assertValidConfig, t as PLUGIN_ID } from "../config-Bdqx5Bs6.mjs";
+import { JetEmailError } from "../client.mjs";
+import { a as assertValidConfig, i as PLUGIN_VERSION, n as sendWithConfig, r as PLUGIN_ID, t as defaultDeps } from "../send-DoICK33S.mjs";
 
 //#region src/native/index.ts
 /**
@@ -16,6 +17,14 @@ function jetEmail(config) {
 		capabilities: ["hooks.email-transport:register"]
 	};
 }
+/**
+* Sends a message from site code (forms, Workflows) with the same sender as {@link jetEmail}.
+* Supports attachments, which EmDash email cannot carry. Throws on failure; a
+* {@link JetEmailError} carries the HTTP status.
+*/
+function sendEmail(config, message) {
+	return sendWithConfig(config, message, defaultDeps);
+}
 
 //#endregion
-export { jetEmail as default, jetEmail };
+export { JetEmailError, jetEmail as default, jetEmail, sendEmail };

package/dist/native/plugin.d.mts

@@ -1,11 +1,19 @@
-import { t as JetEmailConfig } from "../config-DcMo9a49.mjs";
+import { FetchFn } from "../client.mjs";
+import { t as JetEmailConfig } from "../config-BaMQYoEl.mjs";
 import * as emdash from "emdash";
 import { EmailDeliverEvent, PluginContext } from "emdash/plugin";
 
+//#region src/native/send.d.ts
+interface SendDeps {
+  env: () => Promise<Record<string, unknown>>;
+  siteTitle: () => Promise<string | undefined>;
+  fetch: FetchFn;
+  warn: (message: string, data: Record<string, unknown>) => void;
+}
+//#endregion
 //#region src/native/plugin.d.ts
-type LoadEnv = () => Promise<Record<string, unknown>>;
 /** @internal Exported for tests. */
-declare function createJetEmailDeliver(config: JetEmailConfig, loadEnv?: LoadEnv): (event: EmailDeliverEvent, ctx: PluginContext) => Promise<void>;
+declare function createJetEmailDeliver(config: JetEmailConfig, deps?: SendDeps): (event: EmailDeliverEvent, ctx: PluginContext) => Promise<void>;
 /** Called by EmDash with the options of the {@link jetEmail} descriptor. */
 declare function createPlugin(config: JetEmailConfig): emdash.ResolvedPlugin<emdash.PluginStorageConfig>;
 //#endregion

package/dist/native/plugin.mjs

@@ -1,32 +1,16 @@
-import { deliverWithJetEmail } from "../client.mjs";
-import { n as PLUGIN_VERSION, r as assertValidConfig, t as PLUGIN_ID } from "../config-Bdqx5Bs6.mjs";
+import { a as assertValidConfig, i as PLUGIN_VERSION, n as sendWithConfig, r as PLUGIN_ID, t as defaultDeps } from "../send-DoICK33S.mjs";
 import { definePlugin } from "emdash";
 
 //#region src/native/plugin.ts
-async function loadWorkerEnv() {
-	try {
-		const { env } = await import("../env-DnAfk4Vp.mjs");
-		return env;
-	} catch {
-		throw new Error("[jetemail] cloudflare:workers is not available; this provider runs only on Cloudflare Workers.");
-	}
-}
 /** @internal Exported for tests. */
-function createJetEmailDeliver(config, loadEnv = loadWorkerEnv) {
-	const secret = config.secret ?? "JETEMAIL_API_KEY";
+function createJetEmailDeliver(config, deps = defaultDeps) {
 	return async (event, ctx) => {
-		const apiToken = (await loadEnv())[secret];
-		if (typeof apiToken !== "string" || !apiToken) throw new Error(`[jetemail] Worker secret "${secret}" is not set (wrangler secret put ${secret}).`);
 		const { message } = event;
-		const result = await deliverWithJetEmail(fetch, {
-			apiToken,
-			fromName: config.from.name,
-			fromEmail: config.from.email
-		}, {
-			...message,
-			replyTo: message.replyTo ?? config.replyTo
+		const result = await sendWithConfig(config, message, {
+			...deps,
+			siteTitle: async () => await deps.siteTitle() || ctx.site.name
 		});
-		ctx.log.info("Email delivered via JetEmail", {
+		if (result.id) ctx.log.info("Email delivered via JetEmail", {
 			to: message.to,
 			subject: message.subject,
 			id: result.id

package/dist/plugin.mjs

@@ -1 +1 @@
-function e(e,t){return`${e.replace(/[<>"\r\n]/g,``).trim()} <${t}>`}function t(e){if(typeof e==`string`)return e;let t=``;for(let n=0;n<e.length;n+=32768)t+=String.fromCharCode(...e.subarray(n,n+32768));return btoa(t)}async function n(n,r,i){let a={from:e(r.fromName,r.fromEmail),to:i.to,subject:i.subject};i.text&&(a.text=i.text),i.html&&(a.html=i.html),i.cc?.length&&(a.cc=i.cc),i.replyTo&&(a.reply_to=i.replyTo),i.attachments?.length&&(a.attachments=i.attachments.map(e=>({filename:e.filename,data:t(e.content)})));let o=await n(`https://api.jetemail.com/email`,{method:`POST`,headers:{Authorization:`Bearer ${r.apiToken}`,"Content-Type":`application/json`},body:JSON.stringify(a)});if(!o.ok){let e=(await o.text()).slice(0,500);throw Error(`JetEmail rejected the message with HTTP ${o.status}${e?`: ${e}`:``}`)}let s=await o.json().catch(()=>({}));return typeof s.id==`string`?{id:s.id}:{}}async function r(e){let t=await e.kv.get(`settings:apiToken`),n=await e.kv.get(`settings:fromName`),r=await e.kv.get(`settings:fromEmail`);if(!t||!n||!r)throw Error(`JetEmail is not configured. Set the API key, sender name and sender email.`);return{apiToken:t,fromName:n,fromEmail:r}}async function i(e){let t=await e.kv.get(`settings:fromName`)??``,n=await e.kv.get(`settings:fromEmail`)??``,r=!!await e.kv.get(`settings:apiToken`);return{blocks:[{type:`header`,text:`JetEmail`},{type:`section`,text:`Deliver EmDash transactional email through the JetEmail API. The sender domain must be verified in JetEmail and allowed for the API key.`},{type:`form`,block_id:`jetemail-settings`,fields:[{type:`text_input`,action_id:`fromName`,label:`Sender name`,initial_value:t},{type:`text_input`,action_id:`fromEmail`,label:`Sender email`,initial_value:n},{type:`secret_input`,action_id:`apiToken`,label:r?`Transactional API key (leave blank to keep current)`:`Transactional API key`}],submit:{label:`Save settings`,action_id:`save_settings`}}]}}function a(e){return{blocks:[{type:`banner`,style:`error`,text:e}],toast:{message:e,type:`error`}}}async function o(e,t){let n=typeof t.fromName==`string`?t.fromName.trim():``,r=typeof t.fromEmail==`string`?t.fromEmail.trim():``,o=typeof t.apiToken==`string`?t.apiToken.trim():``;return n.replace(/[<>"\r\n]/g,``).trim()?/^[^\s@<>]+@[^\s@<>]+$/.test(r)?o&&!o.startsWith(`transactional_`)?a(`Use a JetEmail transactional API key (transactional_…).`):(await e.kv.set(`settings:fromName`,n),await e.kv.set(`settings:fromEmail`,r),o&&await e.kv.set(`settings:apiToken`,o),{...await i(e),toast:{message:`JetEmail settings saved`,type:`success`}}):a(`Enter a valid sender email.`):a(`Enter a sender name.`)}const s={hooks:{"email:deliver":{exclusive:!0,timeout:3e4,handler:async(e,t)=>{if(!t.http)throw Error(`JetEmail requires network access.`);let i=await r(t);await n(t.http.fetch.bind(t.http),i,e.message),t.log.info(`Email delivered via JetEmail`,{to:e.message.to,subject:e.message.subject})}}},routes:{admin:{handler:async(e,t)=>{let n=e.input;return n.type===`page_load`&&n.page===`/settings`?i(t):n.type===`form_submit`&&n.action_id===`save_settings`?o(t,n.values??{}):{blocks:[]}}}}};export{s as default,n as deliverWithJetEmail,e as formatSender};
+var e=class extends Error{constructor(e,t){super(e),this.status=t,this.name=`JetEmailError`}};function t(e,t){return`${e.replace(/[<>"\r\n]/g,``).trim()} <${t}>`}function n(e){if(typeof e==`string`)return e;let t=``;for(let n=0;n<e.length;n+=32768)t+=String.fromCharCode(...e.subarray(n,n+32768));return btoa(t)}async function r(r,i,a){let o={from:t(i.fromName,i.fromEmail),to:a.to,subject:a.subject};a.text&&(o.text=a.text),a.html&&(o.html=a.html),a.cc?.length&&(o.cc=a.cc),a.replyTo&&(o.reply_to=a.replyTo),a.attachments?.length&&(o.attachments=a.attachments.map(e=>({filename:e.filename,data:n(e.content)})));let s=await r(`https://api.jetemail.com/email`,{method:`POST`,headers:{Authorization:`Bearer ${i.apiToken}`,"Content-Type":`application/json`},body:JSON.stringify(o)});if(!s.ok){let t=(await s.text()).slice(0,500);throw new e(`JetEmail rejected the message with HTTP ${s.status}${t?`: ${t}`:``}`,s.status)}let c=await s.json().catch(()=>({}));return typeof c.id==`string`?{id:c.id}:{}}async function i(e){let t=await e.kv.get(`settings:apiToken`),n=await e.kv.get(`settings:fromName`)||e.site.name,r=await e.kv.get(`settings:fromEmail`),i=await e.kv.get(`settings:replyTo`)||void 0;if(!t||!n||!r)throw Error(`JetEmail is not configured. Set the API key and sender email.`);return{apiToken:t,fromName:n,fromEmail:r,replyTo:i}}async function a(e){let t=await e.kv.get(`settings:fromName`)??``,n=await e.kv.get(`settings:fromEmail`)??``,r=await e.kv.get(`settings:replyTo`)??``,i=!!await e.kv.get(`settings:apiToken`);return{blocks:[{type:`header`,text:`JetEmail`},{type:`section`,text:`Deliver EmDash transactional email through the JetEmail API. The sender domain must be verified in JetEmail and allowed for the API key.`},{type:`form`,block_id:`jetemail-settings`,fields:[{type:`text_input`,action_id:`fromName`,label:`Sender name (defaults to the site title)`,initial_value:t},{type:`text_input`,action_id:`fromEmail`,label:`Sender email`,initial_value:n},{type:`text_input`,action_id:`replyTo`,label:`Reply-To (optional)`,initial_value:r},{type:`secret_input`,action_id:`apiToken`,label:i?`Transactional API key (leave blank to keep current)`:`Transactional API key`}],submit:{label:`Save settings`,action_id:`save_settings`}}]}}const o=/^[^\s@<>]+@[^\s@<>]+$/;function s(e){return{blocks:[{type:`banner`,style:`error`,text:e}],toast:{message:e,type:`error`}}}async function c(e,t){let n=typeof t.fromName==`string`?t.fromName.trim():``,r=typeof t.fromEmail==`string`?t.fromEmail.trim():``,i=typeof t.replyTo==`string`?t.replyTo.trim():``,c=typeof t.apiToken==`string`?t.apiToken.trim():``;return o.test(r)?i&&!o.test(i)?s(`Enter a valid Reply-To email.`):c&&!c.startsWith(`transactional_`)?s(`Use a JetEmail transactional API key (transactional_…).`):(await e.kv.set(`settings:fromName`,n),await e.kv.set(`settings:fromEmail`,r),await e.kv.set(`settings:replyTo`,i),c&&await e.kv.set(`settings:apiToken`,c),{...await a(e),toast:{message:`JetEmail settings saved`,type:`success`}}):s(`Enter a valid sender email.`)}const l={hooks:{"email:deliver":{exclusive:!0,timeout:3e4,handler:async(e,t)=>{if(!t.http)throw Error(`JetEmail requires network access.`);let{replyTo:n,...a}=await i(t);await r(t.http.fetch.bind(t.http),a,{...e.message,replyTo:e.message.replyTo??n}),t.log.info(`Email delivered via JetEmail`,{to:e.message.to,subject:e.message.subject})}}},routes:{admin:{handler:async(e,t)=>{let n=e.input;return n.type===`page_load`&&n.page===`/settings`?a(t):n.type===`form_submit`&&n.action_id===`save_settings`?c(t,n.values??{}):{blocks:[]}}}}};export{l as default,r as deliverWithJetEmail,t as formatSender};

package/dist/send-DoICK33S.mjs

@@ -0,0 +1,70 @@
+import { deliverWithJetEmail, formatSender } from "./client.mjs";
+
+//#region package.json
+var version = "0.4.0";
+
+//#endregion
+//#region src/native/config.ts
+const PLUGIN_ID = "jetemail";
+const PLUGIN_VERSION = version;
+function assertValidConfig(config) {
+	if (!config.from?.email?.includes("@")) throw new Error("[jetemail] config.from needs an email, e.g. { from: { email: \"noreply@example.com\" } }");
+}
+
+//#endregion
+//#region src/native/send.ts
+async function loadWorkerEnv() {
+	try {
+		const { env } = await import("./env-DnAfk4Vp.mjs");
+		return env;
+	} catch {
+		throw new Error("[jetemail] cloudflare:workers is not available; this provider runs only on Cloudflare Workers.");
+	}
+}
+async function loadSiteTitle() {
+	try {
+		const { getSiteSetting } = await import("emdash");
+		return await getSiteSetting("title");
+	} catch {
+		return;
+	}
+}
+const defaultDeps = {
+	env: loadWorkerEnv,
+	siteTitle: loadSiteTitle,
+	fetch: (url, init) => fetch(url, init),
+	warn: (message, data) => console.warn(message, data)
+};
+/**
+* Sends one message with the configured sender. With the Worker variable `JETEMAIL_DRY_RUN=true`
+* the message is only logged; E2E runs use it because they have no API key.
+*/
+async function sendWithConfig(config, message, deps) {
+	const fromName = config.from.name?.trim() || (await deps.siteTitle())?.trim();
+	if (!fromName) throw new Error("[jetemail] No sender name: set config.from.name or the site title.");
+	const replyTo = message.replyTo ?? config.replyTo;
+	const env = await deps.env();
+	if (env.JETEMAIL_DRY_RUN === "true") {
+		deps.warn("[jetemail] JETEMAIL_DRY_RUN=true, email not sent", {
+			from: formatSender(fromName, config.from.email),
+			to: message.to,
+			replyTo,
+			subject: message.subject
+		});
+		return {};
+	}
+	const secret = config.secret ?? "JETEMAIL_API_KEY";
+	const apiToken = env[secret];
+	if (typeof apiToken !== "string" || !apiToken) throw new Error(`[jetemail] Worker secret "${secret}" is not set (wrangler secret put ${secret}).`);
+	return deliverWithJetEmail(deps.fetch, {
+		apiToken,
+		fromName,
+		fromEmail: config.from.email
+	}, {
+		...message,
+		replyTo
+	});
+}
+
+//#endregion
+export { assertValidConfig as a, PLUGIN_VERSION as i, sendWithConfig as n, PLUGIN_ID as r, defaultDeps as t };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@numoteq/emdash-plugin-jetemail",
-	"version": "0.3.0",
+	"version": "0.4.0",
 	"description": "JetEmail transport provider for EmDash",
 	"keywords": [
 		"email",

package/dist/config-Bdqx5Bs6.mjs

@@ -1,9 +0,0 @@
-//#region src/native/config.ts
-const PLUGIN_ID = "jetemail";
-const PLUGIN_VERSION = "1.0.0";
-function assertValidConfig(config) {
-	if (!config.from?.email?.includes("@") || !config.from.name?.trim()) throw new Error("[jetemail] config.from needs an email and a name, e.g. { from: { email: \"noreply@example.com\", name: \"Example\" } }");
-}
-
-//#endregion
-export { PLUGIN_VERSION as n, assertValidConfig as r, PLUGIN_ID as t };