@checkstack/notification-backend 1.0.5 → 1.2.0

package/src/post-json.test.ts

@@ -0,0 +1,133 @@
+import { describe, it, expect, mock } from "bun:test";
+import type { Logger } from "@checkstack/backend-api";
+import { postJson } from "./post-json";
+
+function makeLogger(): Logger {
+  return {
+    info: mock(() => {}),
+    error: mock(() => {}),
+    warn: mock(() => {}),
+    debug: mock(() => {}),
+  };
+}
+
+describe("postJson", () => {
+  it("returns ok:true with the response on 2xx", async () => {
+    const responses: string[] = [];
+    const originalFetch = globalThis.fetch;
+    globalThis.fetch = mock(async (url: RequestInfo | URL) => {
+      responses.push(String(url));
+      return new Response(null, { status: 204 });
+    }) as unknown as typeof fetch;
+    try {
+      const logger = makeLogger();
+      const result = await postJson({
+        url: "https://example.test/hook",
+        body: { hello: "world" },
+        serviceName: "Test",
+        logger,
+      });
+      expect(result.ok).toBe(true);
+      if (result.ok) {
+        expect(result.response.status).toBe(204);
+      }
+      expect(responses).toEqual(["https://example.test/hook"]);
+      expect(logger.error).not.toHaveBeenCalled();
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+
+  it("returns ok:false with a service-tagged error on non-2xx", async () => {
+    const originalFetch = globalThis.fetch;
+    globalThis.fetch = mock(async () =>
+      new Response("Bad request body", { status: 400 }),
+    ) as unknown as typeof fetch;
+    try {
+      const logger = makeLogger();
+      const result = await postJson({
+        url: "https://example.test/hook",
+        body: { hello: "world" },
+        serviceName: "Discord",
+        logger,
+      });
+      expect(result.ok).toBe(false);
+      if (!result.ok) {
+        expect(result.error).toBe("Failed to send Discord message: 400");
+      }
+      expect(logger.error).toHaveBeenCalledTimes(1);
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+
+  it("returns ok:false when fetch rejects (network / timeout)", async () => {
+    const originalFetch = globalThis.fetch;
+    globalThis.fetch = mock(async () => {
+      throw new Error("ECONNREFUSED");
+    }) as unknown as typeof fetch;
+    try {
+      const logger = makeLogger();
+      const result = await postJson({
+        url: "https://example.test/hook",
+        body: {},
+        serviceName: "Slack",
+        logger,
+      });
+      expect(result.ok).toBe(false);
+      if (!result.ok) {
+        expect(result.error).toBe(
+          "Failed to send Slack notification: ECONNREFUSED",
+        );
+      }
+      expect(logger.error).toHaveBeenCalledTimes(1);
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+
+  it("merges caller headers on top of the default Content-Type", async () => {
+    let observedHeaders: Headers | undefined;
+    const originalFetch = globalThis.fetch;
+    globalThis.fetch = mock(async (_url: RequestInfo | URL, init?: RequestInit) => {
+      observedHeaders = new Headers(init?.headers);
+      return new Response(null, { status: 200 });
+    }) as unknown as typeof fetch;
+    try {
+      await postJson({
+        url: "https://example.test/hook",
+        body: {},
+        headers: { Authorization: "Bearer token" },
+        serviceName: "Webex",
+        logger: makeLogger(),
+      });
+      expect(observedHeaders?.get("content-type")).toBe("application/json");
+      expect(observedHeaders?.get("authorization")).toBe("Bearer token");
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+
+  it("truncates long error bodies in the log payload", async () => {
+    const longBody = "x".repeat(2_000);
+    const originalFetch = globalThis.fetch;
+    globalThis.fetch = mock(async () =>
+      new Response(longBody, { status: 500 }),
+    ) as unknown as typeof fetch;
+    try {
+      const logger = makeLogger();
+      await postJson({
+        url: "https://example.test/hook",
+        body: {},
+        serviceName: "Gotify",
+        logger,
+      });
+      const errorCall = (logger.error as ReturnType<typeof mock>).mock
+        .calls[0];
+      const meta = errorCall?.[1] as { error: string } | undefined;
+      expect(meta?.error.length).toBe(500);
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+});

package/src/post-json.ts

@@ -0,0 +1,86 @@
+import type { Logger } from "@checkstack/backend-api";
+import { extractErrorMessage } from "@checkstack/common";
+
+/**
+ * Outcome of a [[postJson]] call. Discriminated on `ok`:
+ * - `ok: true` carries the raw `Response` so callers can read service-specific
+ *   success payloads (e.g. Pushover's `receipt`).
+ * - `ok: false` carries a human-readable error string already suitable for
+ *   surfacing back to operators via `NotificationDeliveryResult.error`.
+ */
+export type PostJsonResult =
+  | { ok: true; response: Response }
+  | { ok: false; error: string };
+
+export interface PostJsonOptions {
+  /** Absolute URL to POST to. */
+  url: string;
+  /** Body, JSON-stringified for you. */
+  body: unknown;
+  /**
+   * Headers merged on top of `Content-Type: application/json`. Provide auth
+   * tokens here (e.g. `Bearer ...`).
+   */
+  headers?: Record<string, string>;
+  /** Request timeout. Defaults to 10s, matching the platform-wide default. */
+  timeoutMs?: number;
+  /**
+   * Short, human-readable service label used to build log messages and the
+   * returned error string. Example: `"Discord"`, `"Slack webhook"`.
+   */
+  serviceName: string;
+  logger: Logger;
+}
+
+/**
+ * Shared POST helper for notification strategies. Centralises the
+ * timeout-bounded fetch, non-2xx logging, and error mapping that every
+ * webhook-style notification plugin (Discord, Slack, Teams, Webex, Telegram,
+ * Gotify, Pushover, ...) was previously re-implementing inline.
+ *
+ * Plugins remain responsible for building the request body and interpreting
+ * a successful `Response` (some services return JSON receipts; most return
+ * 204 No Content).
+ */
+export async function postJson(
+  options: PostJsonOptions,
+): Promise<PostJsonResult> {
+  const {
+    url,
+    body,
+    headers = {},
+    timeoutMs = 10_000,
+    serviceName,
+    logger,
+  } = options;
+
+  try {
+    const response = await fetch(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", ...headers },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      logger.error(`Failed to send ${serviceName} message`, {
+        status: response.status,
+        error: errorText.slice(0, 500),
+      });
+      return {
+        ok: false,
+        error: `Failed to send ${serviceName} message: ${response.status}`,
+      };
+    }
+
+    return { ok: true, response };
+  } catch (error) {
+    const message = extractErrorMessage(error, `Unknown ${serviceName} error`);
+    logger.error(`${serviceName} request error`, { error: message });
+    return {
+      ok: false,
+      error: `Failed to send ${serviceName} notification: ${message}`,
+    };
+  }
+}

package/src/render.ts

@@ -0,0 +1,29 @@
+import type {
+  Importance,
+  SubjectStatus,
+} from "@checkstack/notification-common";
+
+/**
+ * Emoji used to prefix an affected subject in a rendered notification, keyed
+ * by the subject's health status. Plugins that render notifications in
+ * plain-text channels (Slack, Discord, Teams, Telegram, Webex, etc.) should
+ * use this map instead of redefining their own so operators see a consistent
+ * visual language across destinations.
+ */
+export const SUBJECT_STATUS_EMOJI: Record<SubjectStatus, string> = {
+  healthy: "🟢",
+  degraded: "🟡",
+  unhealthy: "🔴",
+  unknown: "⚪",
+};
+
+/**
+ * Emoji used to prefix a notification's title in a rendered message, keyed
+ * by the notification's importance level. Plugins should use this map rather
+ * than redefining their own.
+ */
+export const IMPORTANCE_EMOJI: Record<Importance, string> = {
+  info: "ℹ️",
+  warning: "⚠️",
+  critical: "🚨",
+};