@checkstack/notification-backend 1.0.5 → 1.1.0

package/CHANGELOG.md

@@ -1,5 +1,45 @@
 # @checkstack/notification-backend
 
+## 1.1.0
+
+### Minor Changes
+
+- a06b899: Dead-code audit cleanup and a small platform of shared notification helpers.
+
+  **Removed (dead code)**
+
+  - `core/backend/src/plugin-manager/deregistration-guard.ts` deleted. The exported `assertCanDeregister()` was never called and was a less-complete version of the dependents+isUninstallable checks already done inline by `previewUninstallOriginator` / `uninstallOriginator` in `plugin-manager-orchestrator.ts`.
+  - `createMockQueueFactory` deprecated alias removed from `@checkstack/test-utils-backend`. Use `createMockQueueManager` directly.
+
+  **New shared helpers**
+
+  - `@checkstack/backend-api` now exports `requestTimeoutMs()` — a Zod field builder for outbound HTTP request timeouts (1s..60s, default 10s). Replaces hand-rolled `configNumber({}).min(1000).max(60_000).default(10_000)` in `integration-webhook-backend`, `integration-script-backend`, and `healthcheck-script-backend`'s inline collector.
+  - `@checkstack/notification-common` now exports `SubjectStatusSchema` / `SubjectStatus`, mirroring the existing `ImportanceSchema`.
+  - `@checkstack/notification-backend` now exports:
+    - `SUBJECT_STATUS_EMOJI` / `IMPORTANCE_EMOJI` — the shared status / importance emoji maps that Discord, Slack, Teams, Webex and Telegram previously each redefined inline.
+    - `postJson(opts)` — a timeout-bounded `fetch` wrapper that handles non-2xx logging and error mapping for webhook-style POSTs. Returns `{ ok: true, response } | { ok: false, error }`.
+
+  **Migrated to shared helpers**
+
+  - Discord, Slack, Gotify, Pushover notification backends now use `postJson`. Outer try/catch + per-plugin error mapping deleted (~140 LOC).
+  - Discord, Slack, Teams, Telegram, Webex notification backends now use `IMPORTANCE_EMOJI`. Discord, Slack, Teams use `SUBJECT_STATUS_EMOJI`.
+  - Teams, Webex, Backstage, Telegram kept their inline fetch/Bot logic: their error strings surface server response bodies to operators, or the transport isn't raw `fetch` (Telegram uses `grammy`'s `Bot`).
+
+  **API surface tightening**
+
+  - Per-plugin test-only re-exports in 6 notification backends (Pushover, Gotify, Backstage, Slack, Discord, Teams) and the `CertificateInfo` interface in `healthcheck-tls-backend/strategy.ts` are now JSDoc-tagged `@internal`. No behaviour change; signals that downstream consumers must not depend on them.
+
+### Patch Changes
+
+- Updated dependencies [a06b899]
+- Updated dependencies [a06b899]
+  - @checkstack/backend-api@0.16.0
+  - @checkstack/notification-common@1.1.1
+  - @checkstack/auth-backend@0.4.28
+  - @checkstack/cache-api@0.3.3
+  - @checkstack/queue-api@0.3.3
+  - @checkstack/cache-utils@0.2.8
+
 ## 1.0.5
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/notification-backend",
-  "version": "1.0.5",
+  "version": "1.1.0",
   "license": "Elastic-2.0",
   "type": "module",
   "main": "src/index.ts",
@@ -16,12 +16,12 @@
   },
   "dependencies": {
     "@checkstack/notification-common": "1.1.0",
-    "@checkstack/backend-api": "0.15.2",
-    "@checkstack/cache-api": "0.3.1",
-    "@checkstack/cache-utils": "0.2.6",
+    "@checkstack/backend-api": "0.15.3",
+    "@checkstack/cache-api": "0.3.2",
+    "@checkstack/cache-utils": "0.2.7",
     "@checkstack/signal-common": "0.2.3",
-    "@checkstack/queue-api": "0.3.1",
-    "@checkstack/auth-backend": "0.4.26",
+    "@checkstack/queue-api": "0.3.2",
+    "@checkstack/auth-backend": "0.4.27",
     "@checkstack/auth-common": "0.7.0",
     "drizzle-orm": "^0.45.0",
     "zod": "^4.2.1",
@@ -32,7 +32,7 @@
     "@checkstack/drizzle-helper": "0.0.5",
     "@checkstack/scripts": "0.3.2",
     "@checkstack/tsconfig": "0.0.7",
-    "@checkstack/test-utils-backend": "0.1.26",
+    "@checkstack/test-utils-backend": "0.1.27",
     "@types/node": "^20.0.0",
     "drizzle-kit": "^0.31.10",
     "typescript": "^5.0.0"

package/src/index.ts

@@ -46,6 +46,14 @@ export const notificationStrategyExtensionPoint =
     "notification.strategyExtensionPoint"
   );
 
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Shared render helpers for notification strategies
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+export { SUBJECT_STATUS_EMOJI, IMPORTANCE_EMOJI } from "./render";
+export { postJson } from "./post-json";
+export type { PostJsonOptions, PostJsonResult } from "./post-json";
+
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 // Registry Implementation
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

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: "🚨",
+};