@ceedcv-maya/shared-realtime-react 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Maya-AQSS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@ceedcv-maya/shared-realtime-react",
+  "version": "0.5.0",
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "peerDependencies": {
+    "@tanstack/react-query": "^5.0.0",
+    "laravel-echo": "^2.0.0",
+    "pusher-js": "^8.0.0",
+    "react": "^18.0.0 || ^19.0.0"
+  },
+  "devDependencies": {
+    "@tanstack/react-query": "^5.100.0",
+    "@types/react": "^19.0.0",
+    "laravel-echo": "^2.2.0",
+    "pusher-js": "^8.4.0",
+    "react": "^19.0.0",
+    "typescript": "^5.6.0"
+  },
+  "scripts": {
+    "build": "tsc --noEmit",
+    "test": "echo \"no tests yet\" && exit 0",
+    "typecheck": "tsc --noEmit",
+    "lint": "echo \"no linter configured\""
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Maya-AQSS/maya_platform.git",
+    "directory": "packages/js/shared-realtime-react"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "Reverb/Echo realtime client for the Maya ecosystem: createEcho() factory + useRealtimeNotifications hook.",
+  "sideEffects": false
+}

package/src/createEcho.ts

@@ -0,0 +1,114 @@
+import Echo from 'laravel-echo';
+import Pusher from 'pusher-js';
+
+declare global {
+  interface Window {
+    Pusher: typeof Pusher;
+    Echo: Echo<'reverb'> | undefined;
+  }
+}
+
+export interface ReverbBootstrapConfig {
+  /** Reverb app key — VITE_REVERB_APP_KEY. Required. */
+  appKey: string;
+  /** Reverb host the browser connects to (Traefik-fronted hostname). */
+  host: string;
+  /** Public TLS port — typically 443 in production, 8080 in plain dev. */
+  port: number;
+  /** 'http' falls back to ws://, 'https' to wss://. */
+  scheme: 'http' | 'https';
+  /** Absolute URL to POST /broadcasting/auth at — must include /api/v1 prefix. */
+  authEndpoint: string;
+  /**
+   * Resolver for the bearer JWT sent to authEndpoint. Called per authorize
+   * request so the client always sends a fresh token (handles silent refresh).
+   * Return null to deny the channel without making the request.
+   */
+  getBearerToken: () => string | null | undefined;
+}
+
+let instance: Echo<'reverb'> | null = null;
+let pusherInstalled = false;
+
+/**
+ * Build (or return) the singleton Echo client wired to a Reverb server.
+ *
+ * Singleton on purpose: every component that needs realtime in the same app
+ * shares the same WebSocket. Call disconnectEcho() on full logout/teardown
+ * if you want to drop the connection.
+ *
+ * Channel authorization uses the bearer token from getBearerToken() because
+ * the Maya ecosystem authenticates against Keycloak JWT (Authorization
+ * header) and the default Echo authorizer assumes a session cookie.
+ */
+export function createEcho(config: ReverbBootstrapConfig): Echo<'reverb'> {
+  if (instance) return instance;
+
+  if (!config.appKey?.trim()) {
+    throw new Error('createEcho: appKey is required to bootstrap the Reverb client');
+  }
+
+  if (!pusherInstalled) {
+    window.Pusher = Pusher;
+    pusherInstalled = true;
+  }
+
+  instance = new Echo({
+    broadcaster: 'reverb',
+    key: config.appKey,
+    wsHost: config.host,
+    wsPort: config.port,
+    wssPort: config.port,
+    forceTLS: config.scheme === 'https',
+    enabledTransports: ['ws', 'wss'],
+    authEndpoint: config.authEndpoint,
+    auth: {
+      headers: {
+        Accept: 'application/json',
+      },
+    },
+    authorizer: (channel) => ({
+      authorize: (socketId, callback) => {
+        const token = config.getBearerToken();
+        if (!token) {
+          callback(new Error('no_bearer_token'), null);
+          return;
+        }
+        fetch(config.authEndpoint, {
+          method: 'POST',
+          headers: {
+            Accept: 'application/json',
+            'Content-Type': 'application/json',
+            Authorization: `Bearer ${token}`,
+          },
+          body: JSON.stringify({ socket_id: socketId, channel_name: channel.name }),
+        })
+          .then(async (response) => {
+            if (!response.ok) {
+              callback(new Error(`broadcasting_auth_${response.status}`), null);
+              return;
+            }
+            callback(null, await response.json());
+          })
+          .catch((err: unknown) => {
+            callback(err instanceof Error ? err : new Error('broadcasting_auth_failed'), null);
+          });
+      },
+    }),
+  });
+
+  window.Echo = instance;
+  return instance;
+}
+
+export function getEchoInstance(): Echo<'reverb'> | null {
+  return instance;
+}
+
+export function disconnectEcho(): void {
+  if (instance) {
+    instance.disconnect();
+    instance = null;
+    window.Echo = undefined;
+  }
+}

package/src/index.ts

@@ -0,0 +1,11 @@
+export {
+  createEcho,
+  disconnectEcho,
+  getEchoInstance,
+  type ReverbBootstrapConfig,
+} from './createEcho';
+export {
+  useRealtimeNotifications,
+  type RealtimeNotificationPayload,
+  type UseRealtimeNotificationsOptions,
+} from './useRealtimeNotifications';

package/src/useRealtimeNotifications.ts

@@ -0,0 +1,67 @@
+import { useEffect } from 'react';
+import { useQueryClient } from '@tanstack/react-query';
+import { getEchoInstance } from './createEcho';
+
+export interface RealtimeNotificationPayload {
+  id?: number;
+  app?: string;
+  type?: string;
+  title?: string;
+  body?: string;
+  metadata?: Record<string, unknown>;
+  is_critical?: boolean;
+  scope?: 'user' | 'dashboard' | 'both';
+}
+
+export interface UseRealtimeNotificationsOptions {
+  /** Keycloak UUID of the listening user. When null/undefined the hook is a no-op. */
+  userId: string | null | undefined;
+  /** TanStack Query keys to invalidate when a notification arrives. */
+  queryKeys?: ReadonlyArray<readonly unknown[]>;
+  /** Optional side-effect callback (toast, sound, etc.). */
+  onNotification?: (payload: RealtimeNotificationPayload) => void;
+}
+
+const DEFAULT_QUERY_KEYS: ReadonlyArray<readonly unknown[]> = [['notifications']];
+
+/**
+ * Subscribe the current user to their private notifications channel.
+ *
+ * Listens for the canonical 'notification.created' broadcast and invalidates
+ * the configured TanStack Query keys so paginated lists / badges refetch
+ * immediately. The dot prefix on .listen() tells Echo to match the raw
+ * broadcast name (set by broadcastAs() in the backend event), not the PHP
+ * class name.
+ *
+ * Requires createEcho() to have been called at app boot — usually in the
+ * top-level layout component once the user is authenticated.
+ */
+export function useRealtimeNotifications({
+  userId,
+  queryKeys = DEFAULT_QUERY_KEYS,
+  onNotification,
+}: UseRealtimeNotificationsOptions): void {
+  const queryClient = useQueryClient();
+
+  useEffect(() => {
+    if (!userId) return;
+    const echo = getEchoInstance();
+    if (!echo) return;
+
+    const channelName = `notifications.${userId}`;
+    const channel = echo.private(channelName);
+    const handler = (payload: RealtimeNotificationPayload): void => {
+      for (const queryKey of queryKeys) {
+        queryClient.invalidateQueries({ queryKey: [...queryKey] });
+      }
+      onNotification?.(payload);
+    };
+
+    channel.listen('.notification.created', handler);
+
+    return () => {
+      channel.stopListening('.notification.created');
+      echo.leave(channelName);
+    };
+  }, [userId, queryClient, queryKeys, onNotification]);
+}

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2023",
+    "lib": ["ES2023", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "jsx": "react-jsx",
+    "strict": true,
+    "skipLibCheck": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true
+  },
+  "include": ["src"]
+}