@numoteq/emdash-plugin-jetemail 0.1.0 → 0.2.0

package/README.md

@@ -17,6 +17,34 @@ If the domain publishes JetEmail Domain Security (`_jm` TXT), add the API key's
 
 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.
 
+## 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:
+
+```js
+import { jetEmail } from "@numoteq/emdash-plugin-jetemail/native";
+
+emdash({
+	plugins: [jetEmail({ from: { email: "noreply@example.com", name: "Example" } })],
+});
+```
+
+```sh
+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:
+
+```ts
+import { deliverWithJetEmail } from "@numoteq/emdash-plugin-jetemail/client";
+
+await deliverWithJetEmail(
+	fetch,
+	{ apiToken, fromName: "Example", fromEmail: "noreply@example.com" },
+	message,
+);
+```
+
 ## Development
 
 ```sh

package/dist/client.d.mts

@@ -0,0 +1,21 @@
+//#region src/client.d.ts
+interface JetEmailSender {
+  apiToken: string;
+  fromName: string;
+  fromEmail: string;
+}
+interface JetEmailMessage {
+  to: string | string[];
+  cc?: string[];
+  replyTo?: string;
+  subject: string;
+  text?: string;
+  html?: string;
+}
+type FetchFn = (url: string, init?: RequestInit) => Promise<Response>;
+declare function formatSender(name: string, email: string): string;
+declare function deliverWithJetEmail(fetchFn: FetchFn, sender: JetEmailSender, message: JetEmailMessage): Promise<{
+  id?: string;
+}>;
+//#endregion
+export { FetchFn, JetEmailMessage, JetEmailSender, deliverWithJetEmail, formatSender };

package/dist/client.mjs

@@ -0,0 +1,33 @@
+//#region src/client.ts
+const API_URL = "https://api.jetemail.com/email";
+function formatSender(name, email) {
+	return `${name.replace(/[<>"\r\n]/g, "").trim()} <${email}>`;
+}
+async function deliverWithJetEmail(fetchFn, sender, message) {
+	const body = {
+		from: formatSender(sender.fromName, sender.fromEmail),
+		to: message.to,
+		subject: message.subject
+	};
+	if (message.text) body.text = message.text;
+	if (message.html) body.html = message.html;
+	if (message.cc?.length) body.cc = message.cc;
+	if (message.replyTo) body.reply_to = message.replyTo;
+	const response = await fetchFn(API_URL, {
+		method: "POST",
+		headers: {
+			Authorization: `Bearer ${sender.apiToken}`,
+			"Content-Type": "application/json"
+		},
+		body: JSON.stringify(body)
+	});
+	if (!response.ok) {
+		const detail = (await response.text()).slice(0, 500);
+		throw new Error(`JetEmail rejected the message with HTTP ${response.status}${detail ? `: ${detail}` : ""}`);
+	}
+	const result = await response.json().catch(() => ({}));
+	return typeof result.id === "string" ? { id: result.id } : {};
+}
+
+//#endregion
+export { deliverWithJetEmail, formatSender };

package/dist/config-Bdqx5Bs6.mjs

@@ -0,0 +1,9 @@
+//#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 };

package/dist/config-DcMo9a49.d.mts

@@ -0,0 +1,14 @@
+//#region src/native/config.d.ts
+interface JetEmailConfig {
+  /** Sender. The domain must be verified in JetEmail and allowed for the API key. */
+  from: {
+    email: string;
+    name: string;
+  };
+  /** Reply-To used when the message sets none. */
+  replyTo?: string;
+  /** Name of the Worker secret that holds the transactional API key. @default "JETEMAIL_API_KEY" */
+  secret?: string;
+}
+//#endregion
+export { JetEmailConfig as t };

package/dist/env-DnAfk4Vp.mjs

@@ -0,0 +1,3 @@
+import { env } from "cloudflare:workers";
+
+export { env };

package/dist/index.mjs

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

package/dist/manifest.json

@@ -1,6 +1,6 @@
 {
   "id": "jetemail",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "declaredAccess": {
     "network": {
       "request": {

package/dist/native/index.d.mts

@@ -0,0 +1,11 @@
+import { t as JetEmailConfig } from "../config-DcMo9a49.mjs";
+import { PluginDescriptor } from "emdash";
+
+//#region src/native/index.d.ts
+/**
+ * JetEmail transport for the emdash() integration's `plugins` array. The API key is read at
+ * delivery time from a Worker secret (default `JETEMAIL_API_KEY`), so nothing is configured in the admin.
+ */
+declare function jetEmail(config: JetEmailConfig): PluginDescriptor<JetEmailConfig>;
+//#endregion
+export { type JetEmailConfig, jetEmail as default, jetEmail };

package/dist/native/index.mjs

@@ -0,0 +1,21 @@
+import { n as PLUGIN_VERSION, r as assertValidConfig, t as PLUGIN_ID } from "../config-Bdqx5Bs6.mjs";
+
+//#region src/native/index.ts
+/**
+* JetEmail transport for the emdash() integration's `plugins` array. The API key is read at
+* delivery time from a Worker secret (default `JETEMAIL_API_KEY`), so nothing is configured in the admin.
+*/
+function jetEmail(config) {
+	assertValidConfig(config);
+	return {
+		id: PLUGIN_ID,
+		version: PLUGIN_VERSION,
+		entrypoint: "@numoteq/emdash-plugin-jetemail/native/plugin",
+		format: "native",
+		options: config,
+		capabilities: ["hooks.email-transport:register"]
+	};
+}
+
+//#endregion
+export { jetEmail as default, jetEmail };

package/dist/native/plugin.d.mts

@@ -0,0 +1,12 @@
+import { t as JetEmailConfig } from "../config-DcMo9a49.mjs";
+import * as emdash from "emdash";
+import { EmailDeliverEvent, PluginContext } from "emdash/plugin";
+
+//#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>;
+/** Called by EmDash with the options of the {@link jetEmail} descriptor. */
+declare function createPlugin(config: JetEmailConfig): emdash.ResolvedPlugin<emdash.PluginStorageConfig>;
+//#endregion
+export { createJetEmailDeliver, createPlugin };

package/dist/native/plugin.mjs

@@ -0,0 +1,51 @@
+import { deliverWithJetEmail } from "../client.mjs";
+import { n as PLUGIN_VERSION, r as assertValidConfig, t as PLUGIN_ID } from "../config-Bdqx5Bs6.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";
+	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
+		});
+		ctx.log.info("Email delivered via JetEmail", {
+			to: message.to,
+			subject: message.subject,
+			id: result.id
+		});
+	};
+}
+/** Called by EmDash with the options of the {@link jetEmail} descriptor. */
+function createPlugin(config) {
+	assertValidConfig(config);
+	return definePlugin({
+		id: PLUGIN_ID,
+		version: PLUGIN_VERSION,
+		capabilities: ["hooks.email-transport:register"],
+		hooks: { "email:deliver": {
+			exclusive: true,
+			handler: createJetEmailDeliver(config)
+		} }
+	});
+}
+
+//#endregion
+export { createJetEmailDeliver, createPlugin };

package/dist/plugin.d.mts

@@ -1,22 +1,26 @@
 import { SandboxedPlugin } from "emdash/plugin";
 
-//#region src/plugin.d.ts
-interface JetEmailSettings {
+//#region src/client.d.ts
+interface JetEmailSender {
   apiToken: string;
   fromName: string;
   fromEmail: string;
 }
 interface JetEmailMessage {
-  to: string;
+  to: string | string[];
   cc?: string[];
   replyTo?: string;
   subject: string;
-  text: string;
+  text?: string;
   html?: string;
 }
 type FetchFn = (url: string, init?: RequestInit) => Promise<Response>;
 declare function formatSender(name: string, email: string): string;
-declare function deliverWithJetEmail(fetchFn: FetchFn, settings: JetEmailSettings, message: JetEmailMessage): Promise<void>;
+declare function deliverWithJetEmail(fetchFn: FetchFn, sender: JetEmailSender, message: JetEmailMessage): Promise<{
+  id?: string;
+}>;
+//#endregion
+//#region src/plugin.d.ts
 declare const plugin: SandboxedPlugin;
 //#endregion
 export { plugin as default, deliverWithJetEmail, formatSender };

package/dist/plugin.mjs

@@ -1 +1 @@
-function e(e,t){return`${e.replace(/[<>"\r\n]/g,``).trim()} <${t}>`}async function t(t,n,r){let i={from:e(n.fromName,n.fromEmail),to:r.to,subject:r.subject,text:r.text};r.html&&(i.html=r.html),r.cc?.length&&(i.cc=r.cc),r.replyTo&&(i.reply_to=r.replyTo);let a=await t(`https://api.jetemail.com/email`,{method:`POST`,headers:{Authorization:`Bearer ${n.apiToken}`,"Content-Type":`application/json`},body:JSON.stringify(i)});if(!a.ok){let e=(await a.text()).slice(0,500);throw Error(`JetEmail rejected the message with HTTP ${a.status}${e?`: ${e}`:``}`)}}async function n(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 r(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 i(e){return{blocks:[{type:`banner`,style:`error`,text:e}],toast:{message:e,type:`error`}}}async function a(e,t){let n=typeof t.fromName==`string`?t.fromName.trim():``,a=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(a)?o&&!o.startsWith(`transactional_`)?i(`Use a JetEmail transactional API key (transactional_…).`):(await e.kv.set(`settings:fromName`,n),await e.kv.set(`settings:fromEmail`,a),o&&await e.kv.set(`settings:apiToken`,o),{...await r(e),toast:{message:`JetEmail settings saved`,type:`success`}}):i(`Enter a valid sender email.`):i(`Enter a sender name.`)}const o={hooks:{"email:deliver":{exclusive:!0,timeout:3e4,handler:async(e,r)=>{if(!r.http)throw Error(`JetEmail requires network access.`);let i=await n(r);await t(r.http.fetch.bind(r.http),i,e.message),r.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`?r(t):n.type===`form_submit`&&n.action_id===`save_settings`?a(t,n.values??{}):{blocks:[]}}}}};export{o as default,t as deliverWithJetEmail,e as formatSender};
+function e(e,t){return`${e.replace(/[<>"\r\n]/g,``).trim()} <${t}>`}async function t(t,n,r){let i={from:e(n.fromName,n.fromEmail),to:r.to,subject:r.subject};r.text&&(i.text=r.text),r.html&&(i.html=r.html),r.cc?.length&&(i.cc=r.cc),r.replyTo&&(i.reply_to=r.replyTo);let a=await t(`https://api.jetemail.com/email`,{method:`POST`,headers:{Authorization:`Bearer ${n.apiToken}`,"Content-Type":`application/json`},body:JSON.stringify(i)});if(!a.ok){let e=(await a.text()).slice(0,500);throw Error(`JetEmail rejected the message with HTTP ${a.status}${e?`: ${e}`:``}`)}let o=await a.json().catch(()=>({}));return typeof o.id==`string`?{id:o.id}:{}}async function n(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 r(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 i(e){return{blocks:[{type:`banner`,style:`error`,text:e}],toast:{message:e,type:`error`}}}async function a(e,t){let n=typeof t.fromName==`string`?t.fromName.trim():``,a=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(a)?o&&!o.startsWith(`transactional_`)?i(`Use a JetEmail transactional API key (transactional_…).`):(await e.kv.set(`settings:fromName`,n),await e.kv.set(`settings:fromEmail`,a),o&&await e.kv.set(`settings:apiToken`,o),{...await r(e),toast:{message:`JetEmail settings saved`,type:`success`}}):i(`Enter a valid sender email.`):i(`Enter a sender name.`)}const o={hooks:{"email:deliver":{exclusive:!0,timeout:3e4,handler:async(e,r)=>{if(!r.http)throw Error(`JetEmail requires network access.`);let i=await n(r);await t(r.http.fetch.bind(r.http),i,e.message),r.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`?r(t):n.type===`form_submit`&&n.action_id===`save_settings`?a(t,n.values??{}):{blocks:[]}}}}};export{o as default,t as deliverWithJetEmail,e as formatSender};

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@numoteq/emdash-plugin-jetemail",
-	"version": "0.1.0",
+	"version": "0.2.0",
 	"description": "JetEmail transport provider for EmDash",
 	"keywords": [
 		"email",
@@ -37,13 +37,25 @@
 			"import": "./dist/index.mjs",
 			"types": "./dist/index.d.mts"
 		},
-		"./sandbox": "./dist/plugin.mjs"
+		"./sandbox": "./dist/plugin.mjs",
+		"./native": {
+			"import": "./dist/native/index.mjs",
+			"types": "./dist/native/index.d.mts"
+		},
+		"./native/plugin": {
+			"import": "./dist/native/plugin.mjs",
+			"types": "./dist/native/plugin.d.mts"
+		},
+		"./client": {
+			"import": "./dist/client.mjs",
+			"types": "./dist/client.d.mts"
+		}
 	},
 	"publishConfig": {
 		"access": "public"
 	},
 	"scripts": {
-		"build": "emdash-plugin validate && emdash-plugin build",
+		"build": "emdash-plugin validate && emdash-plugin build && tsdown",
 		"dev": "emdash-plugin dev",
 		"test": "vitest run",
 		"typecheck": "tsc --noEmit"
@@ -51,6 +63,7 @@
 	"devDependencies": {
 		"@emdash-cms/plugin-cli": "0.13.2",
 		"emdash": "1.1.0",
+		"tsdown": "0.20.3",
 		"typescript": "6.0.3",
 		"vitest": "5.0.2"
 	},