@checkstack/signal-frontend 0.0.2

package/CHANGELOG.md

@@ -0,0 +1,60 @@
+# @checkstack/signal-frontend
+
+## 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/signal-common@0.0.2
+
+## 0.1.1
+
+### Patch Changes
+
+- @checkstack/signal-common@0.1.1
+
+## 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 [b55fae6]
+  - @checkstack/signal-common@0.1.0

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@checkstack/signal-frontend",
+  "version": "0.0.2",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./src/index.ts"
+    }
+  },
+  "peerDependencies": {
+    "react": "^18.0.0"
+  },
+  "dependencies": {
+    "@checkstack/signal-common": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/react": "^18.0.0",
+    "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/SignalProvider.tsx

@@ -0,0 +1,180 @@
+import {
+  createContext,
+  useContext,
+  useEffect,
+  useRef,
+  useState,
+  useCallback,
+} from "react";
+import type {
+  Signal,
+  ServerToClientMessage,
+} from "@checkstack/signal-common";
+
+// =============================================================================
+// CONTEXT TYPES
+// =============================================================================
+
+interface SignalContextValue {
+  /** Whether the WebSocket connection is established */
+  isConnected: boolean;
+  /** Subscribe to a signal. Returns an unsubscribe function. */
+  subscribe<T>(signal: Signal<T>, callback: (payload: T) => void): () => void;
+}
+
+const SignalContext = createContext<SignalContextValue | undefined>(undefined);
+
+// =============================================================================
+// SIGNAL PROVIDER
+// =============================================================================
+
+interface SignalProviderProps {
+  children: React.ReactNode;
+  /** Backend URL (defaults to VITE_BACKEND_URL environment variable) */
+  backendUrl?: string;
+}
+
+/**
+ * Provider component that manages the WebSocket connection for signals.
+ *
+ * Should be rendered inside AuthProvider, and only when a user is authenticated.
+ *
+ * @example
+ * ```tsx
+ * // In your app layout (only render when authenticated)
+ * {user && (
+ *   <SignalProvider>
+ *     <AuthenticatedContent />
+ *   </SignalProvider>
+ * )}
+ * ```
+ */
+export const SignalProvider: React.FC<SignalProviderProps> = ({
+  children,
+  backendUrl,
+}) => {
+  const [isConnected, setIsConnected] = useState(false);
+  const wsRef = useRef<WebSocket | undefined>(undefined);
+  const listenersRef = useRef<Map<string, Set<(payload: unknown) => void>>>(
+    new Map()
+  );
+  const reconnectTimeoutRef = useRef<ReturnType<typeof setTimeout> | undefined>(
+    undefined
+  );
+  const reconnectAttemptsRef = useRef(0);
+
+  useEffect(() => {
+    // Determine WebSocket URL - use provided backendUrl or VITE_API_BASE_URL
+    const baseUrl = backendUrl ?? import.meta.env.VITE_API_BASE_URL;
+
+    if (!baseUrl) {
+      console.warn(
+        "SignalProvider: No backend URL configured. WebSocket connection disabled."
+      );
+      return;
+    }
+
+    const wsUrl = baseUrl.replace(/^http/, "ws") + "/api/signals/ws";
+
+    const connect = () => {
+      if (wsRef.current?.readyState === WebSocket.OPEN) return;
+
+      const ws = new WebSocket(wsUrl);
+      wsRef.current = ws;
+
+      ws.addEventListener("open", () => {
+        setIsConnected(true);
+        reconnectAttemptsRef.current = 0;
+      });
+
+      ws.addEventListener("close", () => {
+        setIsConnected(false);
+
+        // Reconnect with exponential backoff
+        const delay = Math.min(
+          1000 * Math.pow(2, reconnectAttemptsRef.current),
+          30_000
+        );
+        reconnectAttemptsRef.current++;
+
+        reconnectTimeoutRef.current = setTimeout(connect, delay);
+      });
+
+      ws.addEventListener("error", (event) => {
+        console.error("SignalProvider: WebSocket error", event);
+      });
+
+      ws.addEventListener("message", (event: MessageEvent<string>) => {
+        try {
+          const message: ServerToClientMessage = JSON.parse(event.data);
+
+          if (message.type === "signal") {
+            const listeners = listenersRef.current.get(message.signalId);
+            if (listeners) {
+              for (const callback of listeners) {
+                callback(message.payload);
+              }
+            }
+          }
+          // Ignore "connected" and "pong" messages
+        } catch (error) {
+          console.error("SignalProvider: Failed to parse message", error);
+        }
+      });
+    };
+
+    connect();
+
+    return () => {
+      if (reconnectTimeoutRef.current) {
+        clearTimeout(reconnectTimeoutRef.current);
+      }
+      wsRef.current?.close();
+    };
+  }, [backendUrl]);
+
+  const subscribe = useCallback(
+    <T,>(signal: Signal<T>, callback: (payload: T) => void) => {
+      const signalId = signal.id;
+
+      if (!listenersRef.current.has(signalId)) {
+        listenersRef.current.set(signalId, new Set());
+      }
+      listenersRef.current
+        .get(signalId)!
+        .add(callback as (payload: unknown) => void);
+
+      // Return unsubscribe function
+      return () => {
+        listenersRef.current
+          .get(signalId)
+          ?.delete(callback as (payload: unknown) => void);
+      };
+    },
+    []
+  );
+
+  const value: SignalContextValue = {
+    isConnected,
+    subscribe,
+  };
+
+  return (
+    <SignalContext.Provider value={value}>{children}</SignalContext.Provider>
+  );
+};
+
+// =============================================================================
+// CONTEXT HOOK
+// =============================================================================
+
+/**
+ * Access the SignalContext. Must be used within a SignalProvider.
+ */
+export const useSignalContext = () => {
+  const context = useContext(SignalContext);
+  if (!context) {
+    throw new Error("useSignalContext must be used within a SignalProvider");
+  }
+  return context;
+};

package/src/index.ts

@@ -0,0 +1,5 @@
+// Provider component
+export { SignalProvider, useSignalContext } from "./SignalProvider";
+
+// Hooks
+export { useSignal, useSignalConnection } from "./useSignal";

package/src/useSignal.ts

@@ -0,0 +1,57 @@
+import { useEffect, useCallback } from "react";
+import type { Signal } from "@checkstack/signal-common";
+import { useSignalContext } from "./SignalProvider";
+
+/**
+ * Subscribe to a signal and receive typed payloads.
+ *
+ * The callback will be invoked whenever the signal is received.
+ * Subscriptions are automatically cleaned up on unmount.
+ *
+ * @example
+ * ```tsx
+ * import { NOTIFICATION_RECEIVED } from "@checkstack/notification-common";
+ *
+ * function NotificationHandler() {
+ *   useSignal(NOTIFICATION_RECEIVED, (payload) => {
+ *     console.log("New notification:", payload.title);
+ *   });
+ *
+ *   return null;
+ * }
+ * ```
+ */
+export function useSignal<T>(
+  signal: Signal<T>,
+  callback: (payload: T) => void
+): void {
+  const { subscribe } = useSignalContext();
+
+  // Memoize callback to prevent unnecessary resubscriptions
+  const stableCallback = useCallback(callback, [callback]);
+
+  useEffect(() => {
+    return subscribe(signal, stableCallback);
+  }, [signal, stableCallback, subscribe]);
+}
+
+/**
+ * Get the WebSocket connection status.
+ *
+ * @example
+ * ```tsx
+ * function ConnectionIndicator() {
+ *   const { isConnected } = useSignalConnection();
+ *
+ *   return (
+ *     <div className={isConnected ? "text-green-500" : "text-red-500"}>
+ *       {isConnected ? "Connected" : "Disconnected"}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export function useSignalConnection(): { isConnected: boolean } {
+  const { isConnected } = useSignalContext();
+  return { isConnected };
+}

package/tsconfig.json

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