@trstudios/discord-notify 1.1.0 → 1.2.1

package/README.md

@@ -77,6 +77,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 : 502 });
+}
+```
+
+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 +126,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

@@ -85,4 +85,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;
@@ -180,3 +181,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.2.1",
   "description": "Discord alerts for server-side failures, with a ZeptoMail sender that reports failed sends. No dependencies.",
   "keywords": [
     "discord",