@trstudios/discord-notify 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 discord-notify contributors
+
+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,102 @@
-# Temporary Holding Version
+# discord-notify
 
-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.
+Discord alerts for server-side failures, plus a [ZeptoMail](https://www.zoho.com/zeptomail/) sender that posts an alert whenever an email fails to send.
+
+No dependencies. Ships as an ES module with TypeScript types, and needs a global `fetch` (Node 18+, Bun or Deno).
+
+## Install
+
+```sh
+npm install @trstudios/discord-notify
+```
+
+**Server-side only.** It reads secrets from the environment, so never import it into browser or app bundles.
+
+## Configuration
+
+| Variable | Used by | Purpose |
+|---|---|---|
+| `ALERTS_DISCORD_WEBHOOK` | `notifyDiscord`, failed `sendMail` | A Discord channel webhook URL. If it's unset, alerts are logged instead. |
+| `ZEPTOMAIL_TOKEN` | `sendMail` | The mail agent's Send Mail token, with or without the `Zoho-enczapikey ` prefix |
+| `ZEPTOMAIL_API_URL` | `sendMail` (optional) | Overrides `https://api.zeptomail.com/v1.1/email`, e.g. for a regional data centre |
+
+Each option can also be passed in code instead of through the environment.
+
+## Usage
+
+### Send an alert
+
+```ts
+import { notifyDiscord } from "@trstudios/discord-notify";
+
+await notifyDiscord({
+  title: "Nightly export failed",
+  fields: { Job: "export", Error: String(err) },
+  body: "Optional longer text",
+});
+```
+
+`notifyDiscord` never throws. It returns `false` if the alert couldn't be sent and logs why.
+
+### Send an email
+
+```ts
+import { sendMail } from "@trstudios/discord-notify";
+
+const result = await sendMail(
+  {
+    from: { address: "noreply@example.com", name: "Example" },
+    to: [{ address: "someone@example.com" }],
+    replyTo: { address: "help@example.com" },
+    subject: "Your report is ready",
+    html: "<p>…</p>",
+  },
+  { source: "reports", alertContent: "summary" },
+);
+
+if (!result.ok) {
+  // Already logged, and alerted to Discord. Answer your own request as needed.
+}
+```
+
+`sendMail` never throws. When a send fails, because of a bad token, a rejected sender or IP, a network error or anything else, it:
+1. logs the error;
+2. posts a Discord alert;
+3. returns `{ ok: false, error }`.
+
+### How much a failure alert includes
+
+`alertContent` decides how much of the failed message goes to Discord:
+
+| Level | Includes |
+|---|---|
+| `"none"` (default) | Source, error, recipients masked as `j***@example.com` |
+| `"summary"` | Adds from, full recipients, reply-to and subject |
+| `"full"` | Adds the message body. If there's no text version, it's converted from the HTML. |
+
+Use `"none"` for messages that contain secrets, such as sign-in codes, password resets and invite links. Anyone who can read the alert channel can read whatever an alert includes.
+
+## Safety notes
+
+- **No pings:** alerts are posted with mentions disabled, so text in a message can't ping `@everyone` or a role.
+- **Discord's size limits:** long fields and bodies are cut off with a `(truncated)` marker.
+- **Timeouts:** requests time out after 5 seconds (Discord) and 15 seconds (ZeptoMail), so a hung service can't stall your request handler for long.
+
+## Development
+
+```sh
+npm install
+npm test
+npm run typecheck
+```
+
+## Releasing
+
+1. Bump `version` in `package.json` and commit.
+2. Push a matching tag, for example `git tag v1.0.1 && git push origin v1.0.1`.
+
+GitHub Actions then publishes to npm through Trusted Publishing, with provenance.
+
+## License
+
+MIT

package/dist/notify.d.ts

@@ -0,0 +1,86 @@
+type FetchFn = typeof fetch;
+export interface DiscordAlert {
+    /** One line saying what failed, e.g. "Nightly export failed". */
+    title: string;
+    /** Short labelled values (source, error, recipient...). */
+    fields?: Record<string, string | undefined>;
+    /** Longer free text, such as the content of a failed message. */
+    body?: string;
+}
+export interface NotifyOptions {
+    /** Defaults to the ALERTS_DISCORD_WEBHOOK environment variable. */
+    webhookUrl?: string;
+    fetch?: FetchFn;
+}
+export declare function truncate(text: string, max: number): string;
+/** Builds the webhook payload. Exported for tests. */
+export declare function discordPayload(alert: DiscordAlert): {
+    allowed_mentions: {
+        parse: string[];
+    };
+    embeds: {
+        title: string;
+        color: number;
+        fields: {
+            name: string;
+            value: string;
+            inline: boolean;
+        }[];
+        description: string | undefined;
+        timestamp: string;
+    }[];
+};
+/**
+ * Posts an alert to a Discord channel webhook. Never throws: it returns false
+ * when there is no webhook configured or Discord can't be reached, and logs why.
+ */
+export declare function notifyDiscord(alert: DiscordAlert, options?: NotifyOptions): Promise<boolean>;
+export interface Address {
+    address: string;
+    name?: string;
+}
+export interface Mail {
+    from: Address;
+    to: Address[];
+    replyTo?: Address;
+    subject: string;
+    text?: string;
+    html?: string;
+}
+/**
+ * How much of a failed message goes into the alert.
+ * - "none": recipients masked (j***@example.com), no subject or content. Use for
+ *   anything with secrets in it: sign-in codes, password resets, invites.
+ * - "summary": recipients and subject, no content.
+ * - "full": everything, including the message body.
+ */
+export type AlertContent = "none" | "summary" | "full";
+export interface SendOptions {
+    /** Defaults to ZEPTOMAIL_TOKEN. With or without the "Zoho-enczapikey " prefix. */
+    token?: string;
+    /** What the alert should include if this send fails. Defaults to "none". */
+    alertContent?: AlertContent;
+    /** Names the sender in the alert, e.g. "billing service". */
+    source?: string;
+    /** Defaults to https://api.zeptomail.com/v1.1/email (ZEPTOMAIL_API_URL overrides). */
+    apiUrl?: string;
+    /** Options for the failure alert. */
+    notify?: NotifyOptions;
+    fetch?: FetchFn;
+}
+export type SendResult = {
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+};
+export declare function maskEmail(address: string): string;
+/** Builds the failure alert at the requested level of detail. Exported for tests. */
+export declare function failureAlert(mail: Mail, error: string, level: AlertContent, source?: string): DiscordAlert;
+/**
+ * Sends one email through the ZeptoMail API. Never throws. On failure it posts a
+ * Discord alert (see AlertContent) and returns { ok: false }, so the caller can
+ * still answer its own request.
+ */
+export declare function sendMail(mail: Mail, options?: SendOptions): Promise<SendResult>;
+export {};

package/dist/notify.js

@@ -0,0 +1,171 @@
+// discord-notify — https://github.com/Traumatized-ink/discord-notify
+// Server-side only: it reads secrets from the environment. Never import it from
+// browser or app bundles.
+//
+// No dependencies; needs a global fetch (Node 18+, Bun, Deno).
+// Discord's limits for one embed.
+const TITLE_MAX = 256;
+const FIELD_NAME_MAX = 256;
+const FIELD_VALUE_MAX = 1024;
+const MAX_FIELDS = 25;
+const DESCRIPTION_MAX = 4096;
+const EMBED_TOTAL_MAX = 6000;
+const RED = 0xd93f3f;
+export function truncate(text, max) {
+    if (text.length <= max)
+        return text;
+    const note = "… (truncated)";
+    return text.slice(0, max - note.length) + note;
+}
+/** Builds the webhook payload. Exported for tests. */
+export function discordPayload(alert) {
+    const title = truncate(alert.title, TITLE_MAX);
+    const fields = Object.entries(alert.fields ?? {})
+        .filter((entry) => Boolean(entry[1]))
+        .slice(0, MAX_FIELDS)
+        .map(([name, value]) => ({
+        name: truncate(name, FIELD_NAME_MAX),
+        value: truncate(value, FIELD_VALUE_MAX),
+        inline: value.length <= 40,
+    }));
+    const used = title.length + fields.reduce((n, f) => n + f.name.length + f.value.length, 0);
+    const room = Math.min(DESCRIPTION_MAX, EMBED_TOTAL_MAX - used);
+    const description = alert.body && room > 20 ? truncate(alert.body, room) : undefined;
+    return {
+        // Alert text can contain user input; never let it ping @everyone or roles.
+        allowed_mentions: { parse: [] },
+        embeds: [{ title, color: RED, fields, description, timestamp: new Date().toISOString() }],
+    };
+}
+/**
+ * Posts an alert to a Discord channel webhook. Never throws: it returns false
+ * when there is no webhook configured or Discord can't be reached, and logs why.
+ */
+export async function notifyDiscord(alert, options = {}) {
+    const url = options.webhookUrl ?? process.env.ALERTS_DISCORD_WEBHOOK;
+    if (!url) {
+        console.warn(`[discord-notify] ALERTS_DISCORD_WEBHOOK is not set; alert not sent: ${alert.title}`);
+        return false;
+    }
+    try {
+        const res = await (options.fetch ?? fetch)(url, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(discordPayload(alert)),
+            signal: AbortSignal.timeout(5000),
+        });
+        if (!res.ok) {
+            console.error(`[discord-notify] Discord returned ${res.status}; alert not sent: ${alert.title}`);
+            return false;
+        }
+        return true;
+    }
+    catch (err) {
+        console.error(`[discord-notify] could not reach Discord; alert not sent: ${alert.title}`, err);
+        return false;
+    }
+}
+const PREFIX = "Zoho-enczapikey ";
+export function maskEmail(address) {
+    const at = address.lastIndexOf("@");
+    if (at < 1)
+        return "***";
+    return `${address[0]}***${address.slice(at)}`;
+}
+const formatAddress = (a) => (a.name ? `${a.name} <${a.address}>` : a.address);
+function zeptoBody(mail) {
+    return {
+        from: { address: mail.from.address, name: mail.from.name },
+        to: mail.to.map((a) => ({ email_address: { address: a.address, name: a.name } })),
+        reply_to: mail.replyTo ? [{ address: mail.replyTo.address, name: mail.replyTo.name }] : undefined,
+        subject: mail.subject,
+        textbody: mail.text,
+        htmlbody: mail.html,
+    };
+}
+/** Turns HTML into readable text for the alert when there is no text version. */
+function htmlToText(html) {
+    return html
+        .replace(/<(br|\/p|\/div|\/h\d|\/li|\/tr)\b[^>]*>/gi, "\n")
+        .replace(/<[^>]+>/g, "")
+        .replace(/&nbsp;/g, " ")
+        .replace(/&lt;/g, "<")
+        .replace(/&gt;/g, ">")
+        .replace(/&quot;/g, '"')
+        .replace(/&#39;/g, "'")
+        .replace(/&amp;/g, "&")
+        .replace(/\n\s*\n+/g, "\n\n")
+        .trim();
+}
+/** Builds the failure alert at the requested level of detail. Exported for tests. */
+export function failureAlert(mail, error, level, source) {
+    const fields = { Source: source, Error: error };
+    if (level === "none") {
+        fields.To = mail.to.map((a) => maskEmail(a.address)).join(", ");
+        return { title: "Email failed to send", fields };
+    }
+    fields.From = formatAddress(mail.from);
+    fields.To = mail.to.map(formatAddress).join(", ");
+    fields["Reply-To"] = mail.replyTo && formatAddress(mail.replyTo);
+    fields.Subject = mail.subject;
+    if (level === "summary")
+        return { title: "Email failed to send", fields };
+    const body = mail.text ?? (mail.html ? htmlToText(mail.html) : undefined);
+    return { title: "Email failed to send", fields, body };
+}
+async function describeFailure(res) {
+    const text = await res.text().catch(() => "");
+    try {
+        const err = JSON.parse(text)?.error;
+        if (err) {
+            const details = Array.isArray(err.details)
+                ? err.details.map((d) => [d.target, d.message].filter(Boolean).join(": ")).join("; ")
+                : "";
+            return [`HTTP ${res.status}`, err.code, err.message, details].filter(Boolean).join(" · ");
+        }
+    }
+    catch {
+        // Not JSON; fall through to the raw text.
+    }
+    return `HTTP ${res.status}${text ? ` · ${text.slice(0, 300)}` : ""}`;
+}
+/**
+ * Sends one email through the ZeptoMail API. Never throws. On failure it posts a
+ * Discord alert (see AlertContent) and returns { ok: false }, so the caller can
+ * still answer its own request.
+ */
+export async function sendMail(mail, options = {}) {
+    const level = options.alertContent ?? "none";
+    const raw = options.token ?? process.env.ZEPTOMAIL_TOKEN ?? "";
+    const key = raw.startsWith(PREFIX) ? raw.slice(PREFIX.length) : raw;
+    let error;
+    if (!key) {
+        error = "ZEPTOMAIL_TOKEN is not set";
+    }
+    else {
+        try {
+            const res = await (options.fetch ?? fetch)(options.apiUrl ?? process.env.ZEPTOMAIL_API_URL ?? "https://api.zeptomail.com/v1.1/email", {
+                method: "POST",
+                headers: {
+                    Accept: "application/json",
+                    "Content-Type": "application/json",
+                    Authorization: PREFIX + key,
+                },
+                body: JSON.stringify(zeptoBody(mail)),
+                signal: AbortSignal.timeout(15000),
+            });
+            if (res.ok)
+                return { ok: true };
+            error = await describeFailure(res);
+        }
+        catch (err) {
+            error = err instanceof Error ? `${err.name}: ${err.message}` : String(err);
+        }
+    }
+    console.error(`[discord-notify] email failed${options.source ? ` (${options.source})` : ""}: ${error}`);
+    await notifyDiscord(failureAlert(mail, error, level, options.source), {
+        ...options.notify,
+        fetch: options.notify?.fetch ?? options.fetch,
+    });
+    return { ok: false, error };
+}

package/package.json

@@ -1,6 +1,45 @@
 {
   "name": "@trstudios/discord-notify",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Discord alerts for server-side failures, with a ZeptoMail sender that reports failed sends. One file, no dependencies.",
+  "keywords": [
+    "discord",
+    "webhook",
+    "alerts",
+    "zeptomail",
+    "email"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Traumatized-ink/discord-notify.git"
+  },
+  "type": "module",
+  "main": "./dist/notify.js",
+  "types": "./dist/notify.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/notify.d.ts",
+      "default": "./dist/notify.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "node --test test/*.test.ts",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run typecheck && npm test && npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  }
+}