@checkstack/signal-common 0.0.2

package/CHANGELOG.md

@@ -0,0 +1,61 @@
+# @checkstack/signal-common
+
+## 0.0.2
+
+### Patch Changes
+
+- d20d274: Initial release of all @checkstack packages. Rebranded from Checkmate to Checkstack with new npm organization @checkstack and domain checkstack.dev.
+- Updated dependencies [d20d274]
+  - @checkstack/common@0.0.2
+
+## 0.1.1
+
+### Patch Changes
+
+- Updated dependencies [a65e002]
+  - @checkstack/common@0.2.0
+
+## 0.1.0
+
+### Minor Changes
+
+- b55fae6: Added realtime Signal Service for backend-to-frontend push notifications via WebSockets.
+
+  ## New Packages
+
+  - **@checkstack/signal-common**: Shared types including `Signal`, `SignalService`, `createSignal()`, and WebSocket protocol messages
+  - **@checkstack/signal-backend**: `SignalServiceImpl` with EventBus integration and Bun WebSocket handler using native pub/sub
+  - **@checkstack/signal-frontend**: React `SignalProvider` and `useSignal()` hook for consuming typed signals
+
+  ## Changes
+
+  - **@checkstack/backend-api**: Added `coreServices.signalService` reference for plugins to emit signals
+  - **@checkstack/backend**: Integrated WebSocket server at `/api/signals/ws` with session-based authentication
+
+  ## Usage
+
+  Backend plugins can emit signals:
+
+  ```typescript
+  import { coreServices } from "@checkstack/backend-api";
+  import { NOTIFICATION_RECEIVED } from "@checkstack/notification-common";
+
+  const signalService = context.signalService;
+  await signalService.sendToUser(NOTIFICATION_RECEIVED, userId, { ... });
+  ```
+
+  Frontend components subscribe to signals:
+
+  ```tsx
+  import { useSignal } from "@checkstack/signal-frontend";
+  import { NOTIFICATION_RECEIVED } from "@checkstack/notification-common";
+
+  useSignal(NOTIFICATION_RECEIVED, (payload) => {
+    // Handle realtime notification
+  });
+  ```
+
+### Patch Changes
+
+- Updated dependencies [ffc28f6]
+  - @checkstack/common@0.1.0

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@checkstack/signal-common",
+  "version": "0.0.2",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./src/index.ts"
+    }
+  },
+  "dependencies": {
+    "@checkstack/common": "workspace:*",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.2",
+    "@checkstack/tsconfig": "workspace:*",
+    "@checkstack/scripts": "workspace:*"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "bun run lint:code",
+    "lint:code": "eslint . --max-warnings 0"
+  }
+}

package/src/index.test.ts

@@ -0,0 +1,162 @@
+import { describe, it, expect } from "bun:test";
+import { createSignal, type Signal, type SignalMessage } from "../src/index";
+import { z } from "zod";
+
+describe("createSignal", () => {
+  it("should create a signal with the given id and schema", () => {
+    const schema = z.object({ message: z.string() });
+    const signal = createSignal("test.signal", schema);
+
+    expect(signal.id).toBe("test.signal");
+    expect(signal.payloadSchema).toBe(schema);
+  });
+
+  it("should create signals with different payload types", () => {
+    const stringSignal = createSignal("string.signal", z.string());
+    const numberSignal = createSignal("number.signal", z.number());
+    const objectSignal = createSignal(
+      "object.signal",
+      z.object({
+        id: z.string(),
+        count: z.number(),
+        active: z.boolean(),
+      })
+    );
+
+    expect(stringSignal.id).toBe("string.signal");
+    expect(numberSignal.id).toBe("number.signal");
+    expect(objectSignal.id).toBe("object.signal");
+  });
+
+  it("should validate payload against schema", () => {
+    const signal = createSignal(
+      "notification.received",
+      z.object({
+        id: z.string(),
+        title: z.string(),
+        importance: z.enum(["info", "warning", "critical"]),
+      })
+    );
+
+    // Valid payload
+    const validPayload = {
+      id: "n-123",
+      title: "Test Notification",
+      importance: "info" as const,
+    };
+    const validResult = signal.payloadSchema.safeParse(validPayload);
+    expect(validResult.success).toBe(true);
+
+    // Invalid payload - missing required field
+    const invalidPayload = {
+      id: "n-123",
+      title: "Test",
+    };
+    const invalidResult = signal.payloadSchema.safeParse(invalidPayload);
+    expect(invalidResult.success).toBe(false);
+
+    // Invalid payload - wrong enum value
+    const wrongEnumPayload = {
+      id: "n-123",
+      title: "Test",
+      importance: "urgent",
+    };
+    const wrongEnumResult = signal.payloadSchema.safeParse(wrongEnumPayload);
+    expect(wrongEnumResult.success).toBe(false);
+  });
+
+  it("should support nested object schemas", () => {
+    const signal = createSignal(
+      "complex.signal",
+      z.object({
+        user: z.object({
+          id: z.string(),
+          name: z.string(),
+        }),
+        metadata: z.record(z.string(), z.string()),
+        tags: z.array(z.string()),
+      })
+    );
+
+    const payload = {
+      user: { id: "u-1", name: "Test User" },
+      metadata: { source: "api" },
+      tags: ["important", "system"],
+    };
+
+    const result = signal.payloadSchema.safeParse(payload);
+    expect(result.success).toBe(true);
+  });
+
+  it("should support optional fields in schema", () => {
+    const signal = createSignal(
+      "optional.signal",
+      z.object({
+        required: z.string(),
+        optional: z.string().optional(),
+      })
+    );
+
+    // With optional field
+    const withOptional = signal.payloadSchema.safeParse({
+      required: "value",
+      optional: "optional value",
+    });
+    expect(withOptional.success).toBe(true);
+
+    // Without optional field
+    const withoutOptional = signal.payloadSchema.safeParse({
+      required: "value",
+    });
+    expect(withoutOptional.success).toBe(true);
+  });
+});
+
+describe("Signal type inference", () => {
+  it("should correctly infer payload type from schema", () => {
+    const signal = createSignal(
+      "typed.signal",
+      z.object({
+        count: z.number(),
+        name: z.string(),
+      })
+    );
+
+    // TypeScript should infer that payload is { count: number, name: string }
+    type InferredPayload = z.infer<typeof signal.payloadSchema>;
+
+    // This test ensures the types compile correctly
+    const payload: InferredPayload = { count: 42, name: "test" };
+    expect(payload.count).toBe(42);
+    expect(payload.name).toBe("test");
+  });
+});
+
+describe("SignalMessage structure", () => {
+  it("should have correct message envelope structure", () => {
+    const message: SignalMessage<{ text: string }> = {
+      signalId: "test.message",
+      payload: { text: "Hello" },
+      timestamp: new Date().toISOString(),
+    };
+
+    expect(message.signalId).toBe("test.message");
+    expect(message.payload.text).toBe("Hello");
+    expect(typeof message.timestamp).toBe("string");
+  });
+});
+
+describe("Signal ID conventions", () => {
+  it("should follow dot-notation naming convention", () => {
+    const signals = [
+      createSignal("notification.received", z.string()),
+      createSignal("notification.read", z.string()),
+      createSignal("system.maintenance.scheduled", z.string()),
+      createSignal("healthcheck.status.changed", z.string()),
+    ];
+
+    for (const signal of signals) {
+      expect(signal.id).toMatch(/^[a-z]+(\.[a-z]+)+$/);
+    }
+  });
+});

package/src/index.ts

@@ -0,0 +1,179 @@
+import { z } from "zod";
+import type { Permission, PluginMetadata } from "@checkstack/common";
+
+// =============================================================================
+// SIGNAL DEFINITION
+// =============================================================================
+
+/**
+ * A Signal is a typed event that can be broadcast from backend to frontend.
+ * Similar to the Hook pattern but for realtime WebSocket communication.
+ */
+export interface Signal<T = unknown> {
+  id: string;
+  payloadSchema: z.ZodType<T>;
+}
+
+/**
+ * Factory function for creating type-safe signals.
+ *
+ * @example
+ * ```typescript
+ * const NOTIFICATION_RECEIVED = createSignal(
+ *   "notification.received",
+ *   z.object({ id: z.string(), title: z.string() })
+ * );
+ * ```
+ */
+export function createSignal<T>(
+  id: string,
+  payloadSchema: z.ZodType<T>
+): Signal<T> {
+  return { id, payloadSchema };
+}
+
+// =============================================================================
+// SIGNAL MESSAGE ENVELOPE
+// =============================================================================
+
+/**
+ * The message envelope sent over WebSocket containing a signal payload.
+ */
+export interface SignalMessage<T = unknown> {
+  signalId: string;
+  payload: T;
+  timestamp: string;
+}
+
+// =============================================================================
+// CHANNEL TYPES
+// =============================================================================
+
+/**
+ * Signal channels determine who receives the signal.
+ */
+export type SignalChannel =
+  | { type: "broadcast" }
+  | { type: "user"; userId: string };
+
+// =============================================================================
+// WEBSOCKET PROTOCOL MESSAGES
+// =============================================================================
+
+/**
+ * Messages sent from client to server over WebSocket.
+ */
+export type ClientToServerMessage = { type: "ping" };
+
+/**
+ * Messages sent from server to client over WebSocket.
+ */
+export type ServerToClientMessage =
+  | { type: "pong" }
+  | { type: "connected"; userId: string }
+  | { type: "signal"; signalId: string; payload: unknown; timestamp: string }
+  | { type: "error"; message: string };
+
+// =============================================================================
+// SIGNAL SERVICE INTERFACE
+// =============================================================================
+
+/**
+ * SignalService provides methods to emit signals to connected clients.
+ *
+ * Signals are pushed via WebSocket to connected frontends in realtime.
+ * The service coordinates across backend instances via the EventBus.
+ */
+export interface SignalService {
+  /**
+   * Emit a broadcast signal to all connected clients.
+   *
+   * @example
+   * ```typescript
+   * await signalService.broadcast(SYSTEM_STATUS_CHANGED, { status: "maintenance" });
+   * ```
+   */
+  broadcast<T>(signal: Signal<T>, payload: T): Promise<void>;
+
+  /**
+   * Emit a signal to a specific user.
+   * Only WebSocket connections authenticated as this user will receive it.
+   *
+   * @example
+   * ```typescript
+   * await signalService.sendToUser(NOTIFICATION_RECEIVED, userId, { title: "New message" });
+   * ```
+   */
+  sendToUser<T>(signal: Signal<T>, userId: string, payload: T): Promise<void>;
+
+  /**
+   * Emit a signal to multiple users.
+   *
+   * @example
+   * ```typescript
+   * await signalService.sendToUsers(NOTIFICATION_RECEIVED, [user1, user2], { title: "Alert" });
+   * ```
+   */
+  sendToUsers<T>(
+    signal: Signal<T>,
+    userIds: string[],
+    payload: T
+  ): Promise<void>;
+
+  /**
+   * Emit a signal only to users from the provided list who have the required permission.
+   * Uses S2S RPC to filter users via AuthApi before sending.
+   *
+   * @param signal - The signal to emit
+   * @param userIds - List of user IDs to potentially send to
+   * @param payload - Signal payload
+   * @param pluginMetadata - The plugin metadata (for constructing fully-qualified permission ID)
+   * @param permission - Permission object with native ID (will be prefixed with pluginId)
+   *
+   * @example
+   * ```typescript
+   * import { pluginMetadata, permissions } from "@checkstack/healthcheck-common";
+   *
+   * await signalService.sendToAuthorizedUsers(
+   *   HEALTH_STATE_CHANGED,
+   *   subscriberUserIds,
+   *   { systemId, newState: "degraded" },
+   *   pluginMetadata,
+   *   permissions.healthcheckStatusRead
+   * );
+   * ```
+   */
+  sendToAuthorizedUsers<T>(
+    signal: Signal<T>,
+    userIds: string[],
+    payload: T,
+    pluginMetadata: PluginMetadata,
+    permission: Permission
+  ): Promise<void>;
+}
+
+// =============================================================================
+// CORE PLUGIN LIFECYCLE SIGNALS
+// =============================================================================
+
+/**
+ * Broadcast to all frontends when a plugin has been fully installed on the backend.
+ * Frontends should dynamically load the plugin's UI assets.
+ */
+export const PLUGIN_INSTALLED = createSignal(
+  "core.plugin.installed",
+  z.object({
+    pluginId: z.string(),
+  })
+);
+
+/**
+ * Broadcast to all frontends when a plugin has been deregistered from the backend.
+ * Frontends should remove the plugin's extensions and routes.
+ */
+export const PLUGIN_DEREGISTERED = createSignal(
+  "core.plugin.deregistered",
+  z.object({
+    pluginId: z.string(),
+  })
+);

package/tsconfig.json

@@ -0,0 +1,6 @@
+{
+  "extends": "@checkstack/tsconfig/common.json",
+  "include": [
+    "src"
+  ]
+}