@sharadox/email-web-library 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sharadox
+
+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,68 @@
-# Temporary Holding Version
+# @sharadox/email-web-library
 
-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.
+Send email from web applications — contact forms, notifications, receipts — through **any SMTP server**: your existing mailbox provider (Proton, Google Workspace, Microsoft 365, Fastmail…) or a sending service (Amazon SES, Postmark, Resend…). No provider SDK, no cloud account; switching provider is a change of four environment variables.
+
+- Checks every message before it leaves: valid addresses, a one-line subject, a body — so form input can't inject extra headers or recipients.
+- One error type, `EmailError`, whose `code` says whose problem it is: `configuration`, `invalid-message` or `delivery`.
+- One short connection per message, which suits serverless functions (Next.js server actions, Vercel functions).
+- Typed, tested against a real SMTP server, ESM only. The SMTP protocol work is done by [Nodemailer](https://nodemailer.com).
+
+## Install
+
+```sh
+pnpm add @sharadox/email-web-library
+```
+
+## Use
+
+Set the server in the environment:
+
+| Variable                | Example                   | Notes                                                                                           |
+| ----------------------- | ------------------------- | ----------------------------------------------------------------------------------------------- |
+| `EMAIL_SERVER_HOST`     | `smtp.protonmail.ch`      |                                                                                                 |
+| `EMAIL_SERVER_PORT`     | `587`                     | Optional, 587 by default                                                                        |
+| `EMAIL_SERVER_USERNAME` | `website@example.com`     |                                                                                                 |
+| `EMAIL_SERVER_PASSWORD` | an SMTP token or password | Keep it in your host's secret store, never in the repository                                    |
+| `EMAIL_SERVER_SECURITY` | `starttls`                | Optional: `starttls` (default), `tls` (default on port 465) or `none` (local test servers only) |
+
+```ts
+"use server";
+import { createEmailSender, EmailError, readEmailServerConfiguration } from "@sharadox/email-web-library";
+
+export async function sendContact(name: string, email: string, text: string) {
+  try {
+    const sender = createEmailSender(readEmailServerConfiguration());
+    await sender.send({
+      from: { name: "Website", address: "website@example.com" }, // usually must be the login address or an alias
+      to: "inbox@example.com",
+      replyTo: { name, address: email }, // replying goes straight to the visitor
+      subject: `New message from ${name}`,
+      text,
+    });
+    return { sent: true };
+  } catch (error) {
+    if (error instanceof EmailError && error.code === "invalid-message")
+      return { sent: false, reason: "check-the-form" };
+    console.error(error); // configuration or delivery: tell the visitor to write directly
+    return { sent: false, reason: "unavailable" };
+  }
+}
+```
+
+`sender.verify()` logs in without sending, handy for a health check. `checkEmailMessage` and `checkEmailAddress` are exported for validating input before you get as far as sending.
+
+## Development
+
+Built on the Sharadox engineering standard: TypeScript in `source/` (one thing per folder: `index.ts`, `type.ts`, `unit-test.ts`, `benchmark-test.ts`), Turborepo, ESLint, Prettier, Vitest, TypeDoc, Husky.
+
+```sh
+pnpm install
+pnpm verify          # format, lint, types, unit and benchmark tests, build
+pnpm documentation   # API reference in documentation/
+```
+
+Branches: `index` is released, `pre-production` gathers finished work, and each change lives on `<thing>.development`. Releases are a `v<version>` tag on `index`; the publish workflow releases to npm with provenance.
+
+## License
+
+[MIT](LICENSE) © Sharadox

package/distribution/email-address/index.d.ts

@@ -0,0 +1,4 @@
+import type { EmailAddress } from "./type.ts";
+/** Checks an address (and its display name) and returns it unchanged; throws `invalid-message` otherwise. */
+export declare function checkEmailAddress(value: EmailAddress, field: string): EmailAddress;
+//# sourceMappingURL=index.d.ts.map

package/distribution/email-address/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../source/email-address/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAM9C,6GAA6G;AAC7G,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,GAAG,YAAY,CASlF"}

package/distribution/email-address/index.js

@@ -0,0 +1,16 @@
+import { EmailError } from "../email-error/index.js";
+/** One address: a local part, an @, and a domain with at least one dot; no spaces, angle brackets or line breaks. */
+const ADDRESS = /^[^\s@<>()[\]\\,;:"]+@[^\s@<>()[\]\\,;:"]+\.[^\s@<>()[\]\\,;:"]+$/;
+const LINE_BREAK = /[\r\n]/;
+/** Checks an address (and its display name) and returns it unchanged; throws `invalid-message` otherwise. */
+export function checkEmailAddress(value, field) {
+    const address = typeof value === "string" ? value : value.address;
+    if (address.length > 254 || !ADDRESS.test(address)) {
+        throw new EmailError("invalid-message", `${field} is not a valid email address`);
+    }
+    if (typeof value !== "string" && (LINE_BREAK.test(value.name) || value.name.length > 200)) {
+        throw new EmailError("invalid-message", `${field} has an invalid display name`);
+    }
+    return value;
+}
+//# sourceMappingURL=index.js.map

package/distribution/email-address/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../source/email-address/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAGrD,qHAAqH;AACrH,MAAM,OAAO,GAAG,mEAAmE,CAAC;AACpF,MAAM,UAAU,GAAG,QAAQ,CAAC;AAE5B,6GAA6G;AAC7G,MAAM,UAAU,iBAAiB,CAAC,KAAmB,EAAE,KAAa;IAClE,MAAM,OAAO,GAAG,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC;IAClE,IAAI,OAAO,CAAC,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;QACnD,MAAM,IAAI,UAAU,CAAC,iBAAiB,EAAE,GAAG,KAAK,+BAA+B,CAAC,CAAC;IACnF,CAAC;IACD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,KAAK,CAAC,IAAI,CAAC,MAAM,GAAG,GAAG,CAAC,EAAE,CAAC;QAC1F,MAAM,IAAI,UAAU,CAAC,iBAAiB,EAAE,GAAG,KAAK,8BAA8B,CAAC,CAAC;IAClF,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/distribution/email-address/type.d.ts

@@ -0,0 +1,6 @@
+/** An address as text (`"person@example.com"`) or with a display name. */
+export type EmailAddress = string | {
+    name: string;
+    address: string;
+};
+//# sourceMappingURL=type.d.ts.map

package/distribution/email-address/type.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"type.d.ts","sourceRoot":"","sources":["../../source/email-address/type.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC"}

package/distribution/email-address/type.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=type.js.map

package/distribution/email-address/type.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"type.js","sourceRoot":"","sources":["../../source/email-address/type.ts"],"names":[],"mappings":""}

package/distribution/email-error/index.d.ts

@@ -0,0 +1,9 @@
+import type { EmailErrorCode } from "./type.ts";
+/** The only error this library throws; `code` says whose problem it is. */
+export declare class EmailError extends Error {
+    readonly code: EmailErrorCode;
+    constructor(code: EmailErrorCode, message: string, options?: {
+        cause?: unknown;
+    });
+}
+//# sourceMappingURL=index.d.ts.map

package/distribution/email-error/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../source/email-error/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAEhD,2EAA2E;AAC3E,qBAAa,UAAW,SAAQ,KAAK;IACnC,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;gBAElB,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAKjF"}

package/distribution/email-error/index.js

@@ -0,0 +1,10 @@
+/** The only error this library throws; `code` says whose problem it is. */
+export class EmailError extends Error {
+    code;
+    constructor(code, message, options) {
+        super(message, options);
+        this.name = "EmailError";
+        this.code = code;
+    }
+}
+//# sourceMappingURL=index.js.map

package/distribution/email-error/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../source/email-error/index.ts"],"names":[],"mappings":"AAEA,2EAA2E;AAC3E,MAAM,OAAO,UAAW,SAAQ,KAAK;IAC1B,IAAI,CAAiB;IAE9B,YAAY,IAAoB,EAAE,OAAe,EAAE,OAA6B;QAC9E,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,YAAY,CAAC;QACzB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF"}

package/distribution/email-error/type.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Why sending failed:
+ * - `configuration`: the email server settings are missing or invalid (fix the environment).
+ * - `invalid-message`: the message itself is wrong, for example a malformed address (fix the input).
+ * - `delivery`: the server could not be reached, refused the login or rejected the message (retry or alert).
+ */
+export type EmailErrorCode = "configuration" | "invalid-message" | "delivery";
+//# sourceMappingURL=type.d.ts.map

package/distribution/email-error/type.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"type.d.ts","sourceRoot":"","sources":["../../source/email-error/type.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GAAG,eAAe,GAAG,iBAAiB,GAAG,UAAU,CAAC"}

package/distribution/email-error/type.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=type.js.map

package/distribution/email-error/type.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"type.js","sourceRoot":"","sources":["../../source/email-error/type.ts"],"names":[],"mappings":""}

package/distribution/email-message/index.d.ts

@@ -0,0 +1,11 @@
+import type { EmailMessage } from "./type.ts";
+/** Longest subject accepted, in characters. */
+export declare const SUBJECT_LIMIT = 300;
+/** Most recipients accepted in one message. */
+export declare const RECIPIENT_LIMIT = 50;
+/**
+ * Checks a message before it reaches the server: valid addresses, a one-line subject (no header injection), at
+ * least one recipient and a body. Returns the message unchanged; throws `invalid-message` otherwise.
+ */
+export declare function checkEmailMessage(message: EmailMessage): EmailMessage;
+//# sourceMappingURL=index.d.ts.map

package/distribution/email-message/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../source/email-message/index.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAE9C,+CAA+C;AAC/C,eAAO,MAAM,aAAa,MAAM,CAAC;AACjC,+CAA+C;AAC/C,eAAO,MAAM,eAAe,KAAK,CAAC;AAElC;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,YAAY,GAAG,YAAY,CAerE"}

package/distribution/email-message/index.js

@@ -0,0 +1,28 @@
+import { checkEmailAddress } from "../email-address/index.js";
+import { EmailError } from "../email-error/index.js";
+/** Longest subject accepted, in characters. */
+export const SUBJECT_LIMIT = 300;
+/** Most recipients accepted in one message. */
+export const RECIPIENT_LIMIT = 50;
+/**
+ * Checks a message before it reaches the server: valid addresses, a one-line subject (no header injection), at
+ * least one recipient and a body. Returns the message unchanged; throws `invalid-message` otherwise.
+ */
+export function checkEmailMessage(message) {
+    checkEmailAddress(message.from, "from");
+    const recipients = Array.isArray(message.to) ? message.to : [message.to];
+    if (recipients.length === 0 || recipients.length > RECIPIENT_LIMIT) {
+        throw new EmailError("invalid-message", `to needs between 1 and ${RECIPIENT_LIMIT} recipients`);
+    }
+    recipients.forEach((recipient, index) => checkEmailAddress(recipient, `to[${index}]`));
+    if (message.replyTo !== undefined)
+        checkEmailAddress(message.replyTo, "replyTo");
+    if (!message.subject.trim() || /[\r\n]/.test(message.subject) || message.subject.length > SUBJECT_LIMIT) {
+        throw new EmailError("invalid-message", `subject must be one line of 1 to ${SUBJECT_LIMIT} characters`);
+    }
+    if (!message.text?.trim() && !message.html?.trim()) {
+        throw new EmailError("invalid-message", "the message needs a text or html body");
+    }
+    return message;
+}
+//# sourceMappingURL=index.js.map

package/distribution/email-message/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../source/email-message/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAC9D,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAGrD,+CAA+C;AAC/C,MAAM,CAAC,MAAM,aAAa,GAAG,GAAG,CAAC;AACjC,+CAA+C;AAC/C,MAAM,CAAC,MAAM,eAAe,GAAG,EAAE,CAAC;AAElC;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAAqB;IACrD,iBAAiB,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACxC,MAAM,UAAU,GAAG,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IACzE,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,IAAI,UAAU,CAAC,MAAM,GAAG,eAAe,EAAE,CAAC;QACnE,MAAM,IAAI,UAAU,CAAC,iBAAiB,EAAE,0BAA0B,eAAe,aAAa,CAAC,CAAC;IAClG,CAAC;IACD,UAAU,CAAC,OAAO,CAAC,CAAC,SAAS,EAAE,KAAK,EAAE,EAAE,CAAC,iBAAiB,CAAC,SAAS,EAAE,MAAM,KAAK,GAAG,CAAC,CAAC,CAAC;IACvF,IAAI,OAAO,CAAC,OAAO,KAAK,SAAS;QAAE,iBAAiB,CAAC,OAAO,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;IACjF,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,OAAO,CAAC,OAAO,CAAC,MAAM,GAAG,aAAa,EAAE,CAAC;QACxG,MAAM,IAAI,UAAU,CAAC,iBAAiB,EAAE,oCAAoC,aAAa,aAAa,CAAC,CAAC;IAC1G,CAAC;IACD,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE,CAAC;QACnD,MAAM,IAAI,UAAU,CAAC,iBAAiB,EAAE,uCAAuC,CAAC,CAAC;IACnF,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/distribution/email-message/type.d.ts

@@ -0,0 +1,14 @@
+import type { EmailAddress } from "../email-address/type.ts";
+/** An email to send. Give `text`, `html` or both (text is the fallback for clients that don't show html). */
+export interface EmailMessage {
+    /** Sender. Most servers only accept the address you log in with (or an alias of it). */
+    from: EmailAddress;
+    /** One or more recipients. */
+    to: EmailAddress | EmailAddress[];
+    /** Where replies go, for example the visitor who filled a contact form. */
+    replyTo?: EmailAddress;
+    subject: string;
+    text?: string;
+    html?: string;
+}
+//# sourceMappingURL=type.d.ts.map

package/distribution/email-message/type.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"type.d.ts","sourceRoot":"","sources":["../../source/email-message/type.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAE7D,6GAA6G;AAC7G,MAAM,WAAW,YAAY;IAC3B,wFAAwF;IACxF,IAAI,EAAE,YAAY,CAAC;IACnB,8BAA8B;IAC9B,EAAE,EAAE,YAAY,GAAG,YAAY,EAAE,CAAC;IAClC,2EAA2E;IAC3E,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;CACf"}

package/distribution/email-message/type.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=type.js.map

package/distribution/email-message/type.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"type.js","sourceRoot":"","sources":["../../source/email-message/type.ts"],"names":[],"mappings":""}

package/distribution/email-sender/index.d.ts

@@ -0,0 +1,11 @@
+import type { EmailServerConfiguration } from "../email-server-configuration/type.ts";
+import type { EmailSender } from "./type.ts";
+/**
+ * Creates a sender for one SMTP server. Each `send` opens its own short connection, which suits serverless
+ * functions (nothing to close, nothing kept between invocations).
+ *
+ * The SMTP protocol work (STARTTLS, login, MIME, encoding of non-English text) is done by Nodemailer; this library
+ * adds the configuration, the message checks and one error type.
+ */
+export declare function createEmailSender(configuration: EmailServerConfiguration): EmailSender;
+//# sourceMappingURL=index.d.ts.map

package/distribution/email-sender/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../source/email-sender/index.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,uCAAuC,CAAC;AACtF,OAAO,KAAK,EAAgB,WAAW,EAAE,MAAM,WAAW,CAAC;AAI3D;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,aAAa,EAAE,wBAAwB,GAAG,WAAW,CAuDtF"}

package/distribution/email-sender/index.js

@@ -0,0 +1,75 @@
+import { createTransport } from "nodemailer";
+import { EmailError } from "../email-error/index.js";
+import { checkEmailMessage } from "../email-message/index.js";
+const addressText = (entry) => (typeof entry === "string" ? entry : entry.address);
+/**
+ * Creates a sender for one SMTP server. Each `send` opens its own short connection, which suits serverless
+ * functions (nothing to close, nothing kept between invocations).
+ *
+ * The SMTP protocol work (STARTTLS, login, MIME, encoding of non-English text) is done by Nodemailer; this library
+ * adds the configuration, the message checks and one error type.
+ */
+export function createEmailSender(configuration) {
+    const security = configuration.security ?? (configuration.port === 465 ? "tls" : "starttls");
+    const timeout = configuration.timeout ?? 10_000;
+    const transport = createTransport({
+        host: configuration.host,
+        port: configuration.port,
+        secure: security === "tls",
+        requireTLS: security === "starttls",
+        ignoreTLS: security === "none",
+        auth: { user: configuration.username, pass: configuration.password },
+        connectionTimeout: timeout,
+        greetingTimeout: timeout,
+        socketTimeout: timeout * 2,
+    });
+    return {
+        async send(message) {
+            checkEmailMessage(message);
+            try {
+                const info = await transport.sendMail({
+                    from: message.from,
+                    to: message.to,
+                    replyTo: message.replyTo,
+                    subject: message.subject,
+                    text: message.text,
+                    html: message.html,
+                    disableFileAccess: true,
+                    disableUrlAccess: true,
+                });
+                const receipt = {
+                    messageId: info.messageId,
+                    accepted: info.accepted.map(addressText),
+                    rejected: info.rejected.map(addressText),
+                };
+                if (receipt.accepted.length === 0) {
+                    throw new EmailError("delivery", `the server refused every recipient (${receipt.rejected.join(", ")})`);
+                }
+                return receipt;
+            }
+            catch (error) {
+                if (error instanceof EmailError)
+                    throw error;
+                throw new EmailError("delivery", `sending through ${configuration.host} failed: ${describe(error)}`, {
+                    cause: error,
+                });
+            }
+        },
+        async verify() {
+            try {
+                await transport.verify();
+            }
+            catch (error) {
+                throw new EmailError("delivery", `logging in to ${configuration.host} failed: ${describe(error)}`, {
+                    cause: error,
+                });
+            }
+        },
+    };
+}
+/** A short reason without the password or message content. */
+function describe(error) {
+    const { code, responseCode, message } = (error ?? {});
+    return [code, responseCode, message?.split("\n")[0]].filter(Boolean).join(" ") || "unknown error";
+}
+//# sourceMappingURL=index.js.map

package/distribution/email-sender/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../source/email-sender/index.ts"],"names":[],"mappings":"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"}

package/distribution/email-sender/type.d.ts

@@ -0,0 +1,18 @@
+import type { EmailMessage } from "../email-message/type.ts";
+/** What the server said when it took the message. */
+export interface EmailReceipt {
+    /** The Message-ID header, useful to find the message in logs. */
+    messageId: string;
+    /** Recipients the server accepted. */
+    accepted: string[];
+    /** Recipients the server refused (the message still went to the accepted ones). */
+    rejected: string[];
+}
+/** Sends email through one SMTP server. */
+export interface EmailSender {
+    /** Checks the message, then sends it. Throws `EmailError` with code `invalid-message` or `delivery`. */
+    send(message: EmailMessage): Promise<EmailReceipt>;
+    /** Connects and logs in without sending, to check the configuration. Throws `EmailError` (`delivery`). */
+    verify(): Promise<void>;
+}
+//# sourceMappingURL=type.d.ts.map

package/distribution/email-sender/type.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"type.d.ts","sourceRoot":"","sources":["../../source/email-sender/type.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAE7D,qDAAqD;AACrD,MAAM,WAAW,YAAY;IAC3B,iEAAiE;IACjE,SAAS,EAAE,MAAM,CAAC;IAClB,sCAAsC;IACtC,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,mFAAmF;IACnF,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,2CAA2C;AAC3C,MAAM,WAAW,WAAW;IAC1B,wGAAwG;IACxG,IAAI,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IACnD,0GAA0G;IAC1G,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACzB"}

package/distribution/email-sender/type.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=type.js.map

package/distribution/email-sender/type.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"type.js","sourceRoot":"","sources":["../../source/email-sender/type.ts"],"names":[],"mappings":""}

package/distribution/email-server-configuration/index.d.ts

@@ -0,0 +1,9 @@
+import type { EmailServerConfiguration } from "./type.ts";
+/**
+ * Reads the email server settings from environment variables:
+ * `EMAIL_SERVER_HOST`, `EMAIL_SERVER_PORT` (default 587), `EMAIL_SERVER_USERNAME`, `EMAIL_SERVER_PASSWORD` and the
+ * optional `EMAIL_SERVER_SECURITY` (`starttls`, `tls` or `none`). Pass another `prefix` to keep several servers.
+ * Throws `configuration` naming every missing or invalid variable.
+ */
+export declare function readEmailServerConfiguration(environment?: Record<string, string | undefined>, prefix?: string): EmailServerConfiguration;
+//# sourceMappingURL=index.d.ts.map

package/distribution/email-server-configuration/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../source/email-server-configuration/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,wBAAwB,EAAuB,MAAM,WAAW,CAAC;AAI/E;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAC1C,WAAW,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAe,EAC7D,MAAM,SAAkB,GACvB,wBAAwB,CAwB1B"}

package/distribution/email-server-configuration/index.js

@@ -0,0 +1,35 @@
+import { EmailError } from "../email-error/index.js";
+const SECURITIES = ["starttls", "tls", "none"];
+/**
+ * Reads the email server settings from environment variables:
+ * `EMAIL_SERVER_HOST`, `EMAIL_SERVER_PORT` (default 587), `EMAIL_SERVER_USERNAME`, `EMAIL_SERVER_PASSWORD` and the
+ * optional `EMAIL_SERVER_SECURITY` (`starttls`, `tls` or `none`). Pass another `prefix` to keep several servers.
+ * Throws `configuration` naming every missing or invalid variable.
+ */
+export function readEmailServerConfiguration(environment = process.env, prefix = "EMAIL_SERVER_") {
+    const read = (name) => environment[`${prefix}${name}`]?.trim() || undefined;
+    const host = read("HOST");
+    const username = read("USERNAME");
+    const password = read("PASSWORD");
+    const port = Number(read("PORT") ?? 587);
+    const security = read("SECURITY");
+    const problems = [
+        ...["HOST", "USERNAME", "PASSWORD"]
+            .filter((name) => !read(name))
+            .map((name) => `${prefix}${name} is missing`),
+        ...(Number.isInteger(port) && port > 0 && port < 65536 ? [] : [`${prefix}PORT must be a port number`]),
+        ...(security === undefined || SECURITIES.includes(security)
+            ? []
+            : [`${prefix}SECURITY must be one of ${SECURITIES.join(", ")}`]),
+    ];
+    if (problems.length)
+        throw new EmailError("configuration", problems.join("; "));
+    return {
+        host: host,
+        port,
+        username: username,
+        password: password,
+        ...(security ? { security: security } : {}),
+    };
+}
+//# sourceMappingURL=index.js.map

package/distribution/email-server-configuration/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../source/email-server-configuration/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAGrD,MAAM,UAAU,GAAmC,CAAC,UAAU,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;AAE/E;;;;;GAKG;AACH,MAAM,UAAU,4BAA4B,CAC1C,cAAkD,OAAO,CAAC,GAAG,EAC7D,MAAM,GAAG,eAAe;IAExB,MAAM,IAAI,GAAG,CAAC,IAAY,EAAE,EAAE,CAAC,WAAW,CAAC,GAAG,MAAM,GAAG,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,IAAI,SAAS,CAAC;IACpF,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC;IAC1B,MAAM,QAAQ,GAAG,IAAI,CAAC,UAAU,CAAC,CAAC;IAClC,MAAM,QAAQ,GAAG,IAAI,CAAC,UAAU,CAAC,CAAC;IAClC,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,GAAG,CAAC,CAAC;IACzC,MAAM,QAAQ,GAAG,IAAI,CAAC,UAAU,CAAC,CAAC;IAClC,MAAM,QAAQ,GAAG;QACf,GAAI,CAAC,MAAM,EAAE,UAAU,EAAE,UAAU,CAAW;aAC3C,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;aAC7B,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,GAAG,MAAM,GAAG,IAAI,aAAa,CAAC;QAC/C,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,IAAI,GAAG,CAAC,IAAI,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,GAAG,MAAM,4BAA4B,CAAC,CAAC;QACtG,GAAG,CAAC,QAAQ,KAAK,SAAS,IAAI,UAAU,CAAC,QAAQ,CAAC,QAA+B,CAAC;YAChF,CAAC,CAAC,EAAE;YACJ,CAAC,CAAC,CAAC,GAAG,MAAM,2BAA2B,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;KACnE,CAAC;IACF,IAAI,QAAQ,CAAC,MAAM;QAAE,MAAM,IAAI,UAAU,CAAC,eAAe,EAAE,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IAChF,OAAO;QACL,IAAI,EAAE,IAAK;QACX,IAAI;QACJ,QAAQ,EAAE,QAAS;QACnB,QAAQ,EAAE,QAAS;QACnB,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,QAA+B,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACnE,CAAC;AACJ,CAAC"}

package/distribution/email-server-configuration/type.d.ts

@@ -0,0 +1,19 @@
+/**
+ * How the connection is protected:
+ * - `starttls`: connect in plain text, then upgrade with STARTTLS, which is required (port 587, the default).
+ * - `tls`: TLS from the first byte (port 465).
+ * - `none`: no encryption, only for a local test server.
+ */
+export type EmailServerSecurity = "starttls" | "tls" | "none";
+/** Where and how to log in to the SMTP server that sends the email. */
+export interface EmailServerConfiguration {
+    host: string;
+    port: number;
+    username: string;
+    password: string;
+    /** Defaults to `tls` on port 465 and `starttls` everywhere else. */
+    security?: EmailServerSecurity;
+    /** Milliseconds to wait for the server before failing with `delivery`. Defaults to 10 000. */
+    timeout?: number;
+}
+//# sourceMappingURL=type.d.ts.map

package/distribution/email-server-configuration/type.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"type.d.ts","sourceRoot":"","sources":["../../source/email-server-configuration/type.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,MAAM,mBAAmB,GAAG,UAAU,GAAG,KAAK,GAAG,MAAM,CAAC;AAE9D,uEAAuE;AACvE,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,oEAAoE;IACpE,QAAQ,CAAC,EAAE,mBAAmB,CAAC;IAC/B,8FAA8F;IAC9F,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB"}

package/distribution/email-server-configuration/type.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=type.js.map

package/distribution/email-server-configuration/type.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"type.js","sourceRoot":"","sources":["../../source/email-server-configuration/type.ts"],"names":[],"mappings":""}

package/distribution/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Send email from web applications through any SMTP server.
+ *
+ * ```ts
+ * import { createEmailSender, readEmailServerConfiguration } from "@sharadox/email-web-library";
+ *
+ * const sender = createEmailSender(readEmailServerConfiguration());
+ * await sender.send({ from: "website@example.com", to: "inbox@example.com", subject: "Hello", text: "Hi!" });
+ * ```
+ *
+ * @packageDocumentation
+ */
+export { checkEmailAddress } from "./email-address/index.ts";
+export type { EmailAddress } from "./email-address/type.ts";
+export { EmailError } from "./email-error/index.ts";
+export type { EmailErrorCode } from "./email-error/type.ts";
+export { checkEmailMessage, RECIPIENT_LIMIT, SUBJECT_LIMIT } from "./email-message/index.ts";
+export type { EmailMessage } from "./email-message/type.ts";
+export { createEmailSender } from "./email-sender/index.ts";
+export type { EmailReceipt, EmailSender } from "./email-sender/type.ts";
+export { readEmailServerConfiguration } from "./email-server-configuration/index.ts";
+export type { EmailServerConfiguration, EmailServerSecurity } from "./email-server-configuration/type.ts";
+//# sourceMappingURL=index.d.ts.map

package/distribution/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../source/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,YAAY,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACpD,YAAY,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAC7F,YAAY,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC5D,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACxE,OAAO,EAAE,4BAA4B,EAAE,MAAM,uCAAuC,CAAC;AACrF,YAAY,EAAE,wBAAwB,EAAE,mBAAmB,EAAE,MAAM,sCAAsC,CAAC"}

package/distribution/index.js

@@ -0,0 +1,18 @@
+/**
+ * Send email from web applications through any SMTP server.
+ *
+ * ```ts
+ * import { createEmailSender, readEmailServerConfiguration } from "@sharadox/email-web-library";
+ *
+ * const sender = createEmailSender(readEmailServerConfiguration());
+ * await sender.send({ from: "website@example.com", to: "inbox@example.com", subject: "Hello", text: "Hi!" });
+ * ```
+ *
+ * @packageDocumentation
+ */
+export { checkEmailAddress } from "./email-address/index.js";
+export { EmailError } from "./email-error/index.js";
+export { checkEmailMessage, RECIPIENT_LIMIT, SUBJECT_LIMIT } from "./email-message/index.js";
+export { createEmailSender } from "./email-sender/index.js";
+export { readEmailServerConfiguration } from "./email-server-configuration/index.js";
+//# sourceMappingURL=index.js.map

package/distribution/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../source/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAE7D,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAEpD,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAE7F,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAE5D,OAAO,EAAE,4BAA4B,EAAE,MAAM,uCAAuC,CAAC"}

package/package.json

@@ -1,6 +1,76 @@
 {
   "name": "@sharadox/email-web-library",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Send email from web applications through any SMTP server, with message checks and clear errors.",
+  "license": "MIT",
+  "author": "Sharadox <email@sharadox.com>",
+  "homepage": "https://github.com/Sharadox/email-web-library#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Sharadox/email-web-library.git"
+  },
+  "bugs": "https://github.com/Sharadox/email-web-library/issues",
+  "keywords": [
+    "email",
+    "smtp",
+    "nextjs",
+    "server-actions",
+    "contact-form"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./distribution/index.d.ts",
+      "default": "./distribution/index.js"
+    }
+  },
+  "files": [
+    "distribution"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "lint-staged": {
+    "*.{ts,js,mjs,cjs}": [
+      "prettier --write",
+      "eslint --fix --max-warnings=0"
+    ],
+    "*.{json,md,yml,yaml}": "prettier --write"
+  },
+  "dependencies": {
+    "nodemailer": "^8.0.11"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.5",
+    "@types/node": "^24.19.2",
+    "@types/nodemailer": "^8.0.2",
+    "@types/smtp-server": "^3.5.13",
+    "eslint": "9.39.5",
+    "eslint-config-prettier": "^10.1.8",
+    "husky": "^9.1.7",
+    "lint-staged": "^17.6.0",
+    "prettier": "^3.9.10",
+    "smtp-server": "^3.21.3",
+    "turbo": "^2.11.10",
+    "typedoc": "^0.28.20",
+    "typescript": "6.0.3",
+    "typescript-eslint": "^8.72.1",
+    "vitest": "^5.1.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "lint": "eslint --max-warnings=0 .",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "type-check": "tsc --noEmit",
+    "test:unit": "vitest run",
+    "test:benchmark": "vitest bench --run --passWithNoTests",
+    "documentation": "typedoc",
+    "verify": "turbo run format:check lint type-check test:unit test:benchmark build"
+  }
 }