@numoteq/emdash-plugin-jetemail 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NUMOTEQ s.r.o.
+
+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,56 @@
-# Temporary Holding Version
+# `@numoteq/emdash-plugin-jetemail`
 
-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.
+Sandbox-compatible [JetEmail](https://jetemail.com) transport provider for EmDash.
+
+## Install
+
+```sh
+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.
+
+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.
+
+## 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
+pnpm test
+pnpm typecheck
+pnpm build
+```
+
+`emdash-plugin build` creates the npm descriptor and sandbox bundle in `dist/`.

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.d.mts

@@ -0,0 +1,5 @@
+// Auto-generated by emdash-plugin build. Do not edit.
+import type { PluginDescriptor } from "emdash";
+
+declare const descriptor: PluginDescriptor;
+export default descriptor;

package/dist/index.mjs

@@ -0,0 +1,40 @@
+// Auto-generated by emdash-plugin build. Do not edit.
+// Source: emdash-plugin.jsonc + package.json
+//
+// Default-exports a sandboxed plugin descriptor. Pass it directly into
+// emdash's `plugins:` or `sandboxed:` array — no factory call needed.
+
+/** @type {import("emdash").PluginDescriptor} */
+const descriptor = Object.freeze({
+	"id": "jetemail",
+	"version": "0.2.0",
+	"format": "standard",
+	"entrypoint": "@numoteq/emdash-plugin-jetemail/sandbox",
+	"capabilities": [
+		"network:request",
+		"hooks.email-transport:register"
+	],
+	"allowedHosts": [
+		"api.jetemail.com"
+	],
+	"storage": {},
+	"hooks": [
+		{
+			"name": "email:deliver",
+			"exclusive": true,
+			"timeout": 30000
+		}
+	],
+	"routes": [
+		"admin"
+	],
+	"adminPages": [
+		{
+			"path": "/settings",
+			"label": "JetEmail",
+			"icon": "mail"
+		}
+	]
+});
+
+export default descriptor;

package/dist/manifest.json

@@ -0,0 +1,44 @@
+{
+  "id": "jetemail",
+  "version": "0.2.0",
+  "declaredAccess": {
+    "network": {
+      "request": {
+        "allowedHosts": [
+          "api.jetemail.com"
+        ]
+      }
+    },
+    "email": {
+      "transport": {}
+    }
+  },
+  "capabilities": [
+    "network:request",
+    "hooks.email-transport:register"
+  ],
+  "allowedHosts": [
+    "api.jetemail.com"
+  ],
+  "storage": {},
+  "hooks": [
+    {
+      "name": "email:deliver",
+      "exclusive": true,
+      "timeout": 30000
+    }
+  ],
+  "routes": [
+    "admin"
+  ],
+  "admin": {
+    "pages": [
+      {
+        "path": "/settings",
+        "label": "JetEmail",
+        "icon": "mail"
+      }
+    ],
+    "widgets": []
+  }
+}

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

@@ -0,0 +1,26 @@
+import { SandboxedPlugin } from "emdash/plugin";
+
+//#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
+//#region src/plugin.d.ts
+declare const plugin: SandboxedPlugin;
+//#endregion
+export { plugin as default, deliverWithJetEmail, formatSender };

package/dist/plugin.mjs

@@ -0,0 +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};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/emdash-plugin.jsonc

@@ -0,0 +1,22 @@
+{
+	"$schema": "./node_modules/@emdash-cms/plugin-cli/schemas/emdash-plugin.schema.json",
+	"slug": "jetemail",
+	"publisher": "did:plc:nna4pfpnegfsgaym44xqhawf", // numoteq.com
+	"license": "MIT",
+	"author": {
+		"name": "NUMOTEQ s.r.o.",
+		"url": "https://www.numoteq.com",
+		"email": "info@numoteq.com",
+	},
+	"security": { "email": "info@numoteq.com" },
+	"name": "JetEmail",
+	"description": "Delivers EmDash transactional email through the JetEmail API.",
+	"keywords": ["email", "transactional", "jetemail"],
+	"repo": "https://github.com/numoteq/emdash-plugins",
+	"capabilities": ["network:request", "hooks.email-transport:register"],
+	"allowedHosts": ["api.jetemail.com"],
+	"storage": {},
+	"admin": {
+		"pages": [{ "path": "/settings", "label": "JetEmail", "icon": "mail" }],
+	},
+}

package/package.json

@@ -1,6 +1,73 @@
 {
-  "name": "@numoteq/emdash-plugin-jetemail",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@numoteq/emdash-plugin-jetemail",
+	"version": "0.2.0",
+	"description": "JetEmail transport provider for EmDash",
+	"keywords": [
+		"email",
+		"emdash",
+		"emdash-plugin",
+		"jetemail"
+	],
+	"homepage": "https://github.com/numoteq/emdash-plugins/tree/main/packages/jetemail#readme",
+	"bugs": {
+		"url": "https://github.com/numoteq/emdash-plugins/issues"
+	},
+	"license": "MIT",
+	"author": {
+		"name": "NUMOTEQ s.r.o.",
+		"email": "info@numoteq.com",
+		"url": "https://www.numoteq.com"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/numoteq/emdash-plugins.git",
+		"directory": "packages/jetemail"
+	},
+	"files": [
+		"dist",
+		"emdash-plugin.jsonc",
+		"README.md",
+		"LICENSE"
+	],
+	"type": "module",
+	"sideEffects": false,
+	"main": "dist/index.mjs",
+	"exports": {
+		".": {
+			"import": "./dist/index.mjs",
+			"types": "./dist/index.d.mts"
+		},
+		"./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 && tsdown",
+		"dev": "emdash-plugin dev",
+		"test": "vitest run",
+		"typecheck": "tsc --noEmit"
+	},
+	"devDependencies": {
+		"@emdash-cms/plugin-cli": "0.13.2",
+		"emdash": "1.1.0",
+		"tsdown": "0.20.3",
+		"typescript": "6.0.3",
+		"vitest": "5.0.2"
+	},
+	"peerDependencies": {
+		"emdash": ">=1.0.0"
+	}
+}