@trstudios/discord-notify 1.1.0 → 1.3.0

package/README.md

@@ -48,6 +48,7 @@ const result = await sendMail(
     from: { address: "noreply@example.com", name: "Example" },
     to: [{ address: "someone@example.com" }],
     bcc: [{ address: "audit@example.com" }], // optional, as is cc
+    attachments: [{ filename: "report.pdf", content: pdfBytes, contentType: "application/pdf" }], // optional
     replyTo: { address: "help@example.com" },
     subject: "Your report is ready",
     html: "<p>…</p>",
@@ -77,6 +78,36 @@ if (!result.ok) {
 
 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.
 
+### Check delivery and alerts
+
+`sendTestMail` sends a short test email through the same path as real mail. With `fail: true`, it uses a deliberately invalid token instead, so the send fails and the failure alert fires. That checks the alert path without changing any configuration.
+
+`secretMatches` compares a request header with a configured secret in constant time. It returns `false` when either value is missing.
+
+Here's an example route, shown with Next.js, protected by an admin secret. It sends only to an address from configuration:
+
+```ts
+import { secretMatches, sendTestMail } from "@trstudios/discord-notify";
+
+export async function POST(request: Request) {
+  if (!secretMatches(request.headers.get("x-admin-token"), process.env.ADMIN_TOKEN)) {
+    return Response.json({ error: "Not allowed" }, { status: 403 });
+  }
+  const to = process.env.TEST_EMAIL_TO;
+  if (!to) return Response.json({ error: "TEST_EMAIL_TO is not set" }, { status: 500 });
+
+  const result = await sendTestMail({
+    from: { address: "noreply@example.com", name: "Example" },
+    to: [{ address: to }],
+    source: "example.com",
+    fail: new URL(request.url).searchParams.get("fail") === "1",
+  });
+  return Response.json(result, { status: result.ok ? 200 : 500 });
+}
+```
+
+Never take the recipient from the request. Otherwise anyone holding the admin secret could use the route to send mail to arbitrary addresses.
+
 ## Safety notes
 
 - **No pings:** alerts are posted with mentions disabled, so text in a message can't ping `@everyone` or a role.
@@ -96,7 +127,7 @@ npm run typecheck
 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 stages the release on npm through Trusted Publishing, with provenance. A maintainer approves it on npmjs.com to publish it.
+GitHub Actions then publishes it to npm through Trusted Publishing, with provenance.
 
 ## License
 

package/dist/notify.d.ts

@@ -39,6 +39,14 @@ export interface Address {
     address: string;
     name?: string;
 }
+export interface Attachment {
+    /** File name shown to the recipient, e.g. "report.pdf". */
+    filename: string;
+    /** The file's bytes. Strings are taken as already base64-encoded. */
+    content: Uint8Array | string;
+    /** MIME type, e.g. "application/pdf". */
+    contentType: string;
+}
 export interface Mail {
     from: Address;
     to: Address[];
@@ -48,6 +56,7 @@ export interface Mail {
     subject: string;
     text?: string;
     html?: string;
+    attachments?: Attachment[];
 }
 /**
  * How much of a failed message goes into the alert.
@@ -85,4 +94,24 @@ export declare function failureAlert(mail: Mail, error: string, level: AlertCont
  * still answer its own request.
  */
 export declare function sendMail(mail: Mail, options?: SendOptions): Promise<SendResult>;
+/**
+ * Compares a secret from a request header with the expected value in constant
+ * time. Returns false when either is missing, so an unset secret never matches.
+ */
+export declare function secretMatches(given: string | null | undefined, expected: string | undefined): boolean;
+export interface TestMailOptions extends SendOptions {
+    from: Address;
+    /** Where the test goes. Take it from configuration, never from the request. */
+    to: Address[];
+    /**
+     * Send with a deliberately invalid token, so the send fails and the failure
+     * alert fires. Checks the alert path without changing any configuration.
+     */
+    fail?: boolean;
+}
+/**
+ * Sends a short test email through the same path as real mail, to check
+ * delivery (or, with `fail`, the failure alert). Never throws.
+ */
+export declare function sendTestMail(options: TestMailOptions): Promise<SendResult>;
 export {};

package/dist/notify.js

@@ -2,7 +2,8 @@
 // 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).
+// No dependencies; needs a global fetch and node:crypto (Node 18+, Bun, Deno).
+import { createHash, timingSafeEqual } from "node:crypto";
 // Discord's limits for one embed.
 const TITLE_MAX = 256;
 const FIELD_NAME_MAX = 256;
@@ -73,6 +74,7 @@ export function maskEmail(address) {
     return `${address[0]}***${address.slice(at)}`;
 }
 const formatAddress = (a) => (a.name ? `${a.name} <${a.address}>` : a.address);
+const base64 = (content) => typeof content === "string" ? content : Buffer.from(content).toString("base64");
 const recipients = (list) => list.map((a) => ({ email_address: { address: a.address, name: a.name } }));
 function zeptoBody(mail) {
     return {
@@ -84,6 +86,9 @@ function zeptoBody(mail) {
         subject: mail.subject,
         textbody: mail.text,
         htmlbody: mail.html,
+        attachments: mail.attachments?.length
+            ? mail.attachments.map((a) => ({ name: a.filename, mime_type: a.contentType, content: base64(a.content) }))
+            : undefined,
     };
 }
 /** Turns HTML into readable text for the alert when there is no text version. */
@@ -119,6 +124,9 @@ export function failureAlert(mail, error, level, source) {
         fields.Bcc = mail.bcc.map(formatAddress).join(", ");
     fields["Reply-To"] = mail.replyTo && formatAddress(mail.replyTo);
     fields.Subject = mail.subject;
+    if (mail.attachments?.length) {
+        fields.Attachments = mail.attachments.map((a) => `${a.filename} (${a.contentType})`).join(", ");
+    }
     if (level === "summary")
         return { title: "Email failed to send", fields };
     const body = mail.text ?? (mail.html ? htmlToText(mail.html) : undefined);
@@ -180,3 +188,38 @@ export async function sendMail(mail, options = {}) {
     });
     return { ok: false, error };
 }
+// ---------------------------------------------------------------------------
+// Delivery checks
+// ---------------------------------------------------------------------------
+/**
+ * Compares a secret from a request header with the expected value in constant
+ * time. Returns false when either is missing, so an unset secret never matches.
+ */
+export function secretMatches(given, expected) {
+    if (!given || !expected)
+        return false;
+    const a = createHash("sha256").update(given).digest();
+    const b = createHash("sha256").update(expected).digest();
+    return timingSafeEqual(a, b);
+}
+/**
+ * Sends a short test email through the same path as real mail, to check
+ * delivery (or, with `fail`, the failure alert). Never throws.
+ */
+export async function sendTestMail(options) {
+    const { from, to, fail, ...send } = options;
+    const when = new Date().toISOString();
+    const what = fail ? "Failure alert test" : "Delivery test";
+    return sendMail({
+        from,
+        to,
+        subject: `${what}${send.source ? ` (${send.source})` : ""}: ${when}`,
+        text: fail
+            ? `This send used a deliberately invalid token, so it should fail and raise an alert.\n\nSent ${when}.`
+            : `If you can read this, email from ${from.address} is being delivered.\n\nSent ${when}.`,
+    }, {
+        alertContent: "summary",
+        ...send,
+        ...(fail && { token: "invalid-token-for-failure-test" }),
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trstudios/discord-notify",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "Discord alerts for server-side failures, with a ZeptoMail sender that reports failed sends. No dependencies.",
   "keywords": [
     "discord",