@syncular/console 0.0.0

package/src/hooks/useInstanceContext.ts

@@ -0,0 +1,31 @@
+import { useMemo } from 'react';
+import { useLocalStorage } from './useLocalStorage';
+
+interface InstanceContext {
+  instanceId: string | undefined;
+  rawInstanceId: string;
+  setInstanceId: (value: string) => void;
+  clearInstanceId: () => void;
+}
+
+const INSTANCE_STORAGE_KEY = 'console:instance-id';
+
+export function useInstanceContext(): InstanceContext {
+  const [rawInstanceId, setRawInstanceId] = useLocalStorage<string>(
+    INSTANCE_STORAGE_KEY,
+    ''
+  );
+
+  const normalizedInstanceId = rawInstanceId.trim();
+
+  return useMemo(
+    () => ({
+      instanceId:
+        normalizedInstanceId.length > 0 ? normalizedInstanceId : undefined,
+      rawInstanceId,
+      setInstanceId: setRawInstanceId,
+      clearInstanceId: () => setRawInstanceId(''),
+    }),
+    [normalizedInstanceId, rawInstanceId, setRawInstanceId]
+  );
+}

package/src/hooks/useLiveEvents.ts

@@ -0,0 +1,267 @@
+/**
+ * Hook for WebSocket live events from the console API
+ */
+
+import { useCallback, useEffect, useRef, useState } from 'react';
+import type { LiveEvent } from '../lib/types';
+import { useConnection } from './ConnectionContext';
+import { useInstanceContext } from './useInstanceContext';
+
+interface UseLiveEventsOptions {
+  /** Maximum number of events to keep in the buffer */
+  maxEvents?: number;
+  /** Whether to connect automatically */
+  enabled?: boolean;
+  /** Mark socket stale when no control/data messages are received in this window */
+  staleAfterMs?: number;
+  /** Maximum number of server replayed events per reconnect (1-500) */
+  replayLimit?: number;
+  /** Optional partition filter for emitted events */
+  partitionId?: string;
+  /** Optional instance filter for emitted events */
+  instanceId?: string;
+}
+
+interface UseLiveEventsResult {
+  /** Recent events (newest first) */
+  events: LiveEvent[];
+  /** Whether currently connected to the WebSocket */
+  isConnected: boolean;
+  /** Connection lifecycle state */
+  connectionState: 'connecting' | 'connected' | 'stale' | 'disconnected';
+  /** Any error that occurred */
+  error: Error | null;
+  /** Clear all events from the buffer */
+  clearEvents: () => void;
+}
+
+export function useLiveEvents(
+  options: UseLiveEventsOptions = {}
+): UseLiveEventsResult {
+  const {
+    maxEvents = 100,
+    enabled = true,
+    staleAfterMs = 65_000,
+    replayLimit = 100,
+    partitionId,
+    instanceId,
+  } = options;
+  const { config, isConnected: apiConnected } = useConnection();
+  const { instanceId: selectedInstanceId } = useInstanceContext();
+  const effectiveInstanceId = instanceId ?? selectedInstanceId;
+  const [events, setEvents] = useState<LiveEvent[]>([]);
+  const [isConnected, setIsConnected] = useState(false);
+  const [connectionState, setConnectionState] = useState<
+    'connecting' | 'connected' | 'stale' | 'disconnected'
+  >('disconnected');
+  const [error, setError] = useState<Error | null>(null);
+  const wsRef = useRef<WebSocket | null>(null);
+  const reconnectTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(
+    null
+  );
+  const staleCheckIntervalRef = useRef<ReturnType<typeof setInterval> | null>(
+    null
+  );
+  const reconnectAttemptsRef = useRef(0);
+  const lastActivityAtRef = useRef(0);
+  const lastEventTimestampRef = useRef<string | null>(null);
+
+  const clearEvents = useCallback(() => {
+    setEvents([]);
+    lastEventTimestampRef.current = null;
+  }, []);
+
+  useEffect(() => {
+    if (!enabled || !apiConnected || !config?.serverUrl || !config?.token) {
+      return;
+    }
+
+    let isCleanedUp = false;
+    const normalizedReplayLimit = Number.isFinite(replayLimit)
+      ? Math.max(1, Math.min(500, Math.floor(replayLimit)))
+      : 100;
+
+    const clearReconnectTimeout = () => {
+      if (!reconnectTimeoutRef.current) return;
+      clearTimeout(reconnectTimeoutRef.current);
+      reconnectTimeoutRef.current = null;
+    };
+
+    const clearStaleInterval = () => {
+      if (!staleCheckIntervalRef.current) return;
+      clearInterval(staleCheckIntervalRef.current);
+      staleCheckIntervalRef.current = null;
+    };
+
+    const scheduleReconnect = () => {
+      if (isCleanedUp || reconnectTimeoutRef.current) return;
+      reconnectAttemptsRef.current += 1;
+      const baseDelayMs = Math.min(
+        30_000,
+        1_000 * 2 ** Math.max(0, reconnectAttemptsRef.current - 1)
+      );
+      const jitterMs = Math.floor(baseDelayMs * 0.2 * Math.random());
+      const delayMs = baseDelayMs + jitterMs;
+      reconnectTimeoutRef.current = setTimeout(() => {
+        reconnectTimeoutRef.current = null;
+        if (!isCleanedUp) {
+          connect();
+        }
+      }, delayMs);
+    };
+
+    const markActivity = () => {
+      lastActivityAtRef.current = Date.now();
+      setIsConnected(true);
+      setConnectionState('connected');
+    };
+
+    const connect = () => {
+      if (isCleanedUp) return;
+      setConnectionState('connecting');
+      clearReconnectTimeout();
+
+      const wsUrl = (() => {
+        const baseUrl = new URL(config.serverUrl, window.location.origin);
+        baseUrl.protocol = baseUrl.protocol === 'https:' ? 'wss:' : 'ws:';
+        const normalizedPath = baseUrl.pathname.endsWith('/')
+          ? baseUrl.pathname.slice(0, -1)
+          : baseUrl.pathname;
+        baseUrl.pathname = `${normalizedPath}/console/events/live`;
+        baseUrl.search = '';
+        baseUrl.searchParams.set('token', config.token);
+        if (lastEventTimestampRef.current) {
+          baseUrl.searchParams.set('since', lastEventTimestampRef.current);
+        }
+        baseUrl.searchParams.set('replayLimit', String(normalizedReplayLimit));
+        if (partitionId) {
+          baseUrl.searchParams.set('partitionId', partitionId);
+        }
+        if (effectiveInstanceId) {
+          baseUrl.searchParams.set('instanceId', effectiveInstanceId);
+        }
+        return baseUrl.toString();
+      })();
+
+      const ws = new WebSocket(wsUrl);
+      wsRef.current = ws;
+
+      ws.onopen = () => {
+        if (isCleanedUp) {
+          ws.close();
+          return;
+        }
+        reconnectAttemptsRef.current = 0;
+        markActivity();
+        setError(null);
+
+        clearStaleInterval();
+        staleCheckIntervalRef.current = setInterval(() => {
+          const socket = wsRef.current;
+          if (!socket || socket.readyState !== WebSocket.OPEN) return;
+          const lastActivityAt = lastActivityAtRef.current;
+          if (!lastActivityAt) return;
+          const elapsedMs = Date.now() - lastActivityAt;
+          if (elapsedMs <= staleAfterMs) return;
+
+          setIsConnected(false);
+          setConnectionState('stale');
+          socket.close();
+        }, 1000);
+      };
+
+      ws.onclose = () => {
+        if (isCleanedUp) return;
+        setIsConnected(false);
+        setConnectionState('disconnected');
+        clearStaleInterval();
+        scheduleReconnect();
+      };
+
+      ws.onerror = () => {
+        if (isCleanedUp) return;
+        setError(new Error('WebSocket connection failed'));
+      };
+
+      ws.onmessage = (event: MessageEvent) => {
+        try {
+          const data = JSON.parse(event.data);
+          const eventType = data.type;
+          markActivity();
+
+          // Skip control events
+          if (eventType === 'connected' || eventType === 'heartbeat') {
+            return;
+          }
+
+          const liveEvent: LiveEvent = {
+            type: eventType as LiveEvent['type'],
+            timestamp: data.timestamp || new Date().toISOString(),
+            data,
+          };
+
+          if (partitionId && liveEvent.data.partitionId !== partitionId) {
+            return;
+          }
+          if (
+            effectiveInstanceId &&
+            liveEvent.data.instanceId !== effectiveInstanceId
+          ) {
+            return;
+          }
+
+          const lastEventTimestampMs = Date.parse(
+            lastEventTimestampRef.current ?? ''
+          );
+          const liveEventTimestampMs = Date.parse(liveEvent.timestamp);
+          if (
+            Number.isFinite(liveEventTimestampMs) &&
+            (!Number.isFinite(lastEventTimestampMs) ||
+              liveEventTimestampMs > lastEventTimestampMs)
+          ) {
+            lastEventTimestampRef.current = liveEvent.timestamp;
+          }
+
+          setEvents((prev) => {
+            const newEvents = [liveEvent, ...prev];
+            return newEvents.slice(0, maxEvents);
+          });
+        } catch {
+          // Ignore parse errors
+        }
+      };
+    };
+
+    connect();
+
+    return () => {
+      isCleanedUp = true;
+      clearReconnectTimeout();
+      clearStaleInterval();
+      if (wsRef.current) {
+        wsRef.current.close();
+        wsRef.current = null;
+      }
+      setIsConnected(false);
+      setConnectionState('disconnected');
+    };
+  }, [
+    enabled,
+    apiConnected,
+    config?.serverUrl,
+    config?.token,
+    maxEvents,
+    partitionId,
+    effectiveInstanceId,
+    replayLimit,
+    staleAfterMs,
+  ]);
+
+  return {
+    events,
+    isConnected,
+    connectionState,
+    error,
+    clearEvents,
+  };
+}

package/src/hooks/useLocalStorage.ts

@@ -0,0 +1,40 @@
+import { useCallback, useEffect, useState } from 'react';
+
+export function useLocalStorage<T>(
+  key: string,
+  defaultValue: T
+): [T, (value: T | ((prev: T) => T)) => void] {
+  const [value, setValue] = useState<T>(() => {
+    if (typeof window === 'undefined') return defaultValue;
+
+    try {
+      const item = window.localStorage.getItem(key);
+      if (item === null) return defaultValue;
+      return JSON.parse(item) as T;
+    } catch {
+      return defaultValue;
+    }
+  });
+
+  useEffect(() => {
+    try {
+      if (value === null || value === undefined) {
+        window.localStorage.removeItem(key);
+      } else {
+        window.localStorage.setItem(key, JSON.stringify(value));
+      }
+    } catch {
+      // Ignore write errors
+    }
+  }, [key, value]);
+
+  const setValueWrapper = useCallback((newValue: T | ((prev: T) => T)) => {
+    setValue((prev) =>
+      typeof newValue === 'function'
+        ? (newValue as (prev: T) => T)(prev)
+        : newValue
+    );
+  }, []);
+
+  return [value, setValueWrapper];
+}

package/src/hooks/usePartitionContext.ts

@@ -0,0 +1,31 @@
+import { useMemo } from 'react';
+import { useLocalStorage } from './useLocalStorage';
+
+interface PartitionContext {
+  partitionId: string | undefined;
+  rawPartitionId: string;
+  setPartitionId: (value: string) => void;
+  clearPartitionId: () => void;
+}
+
+const PARTITION_STORAGE_KEY = 'console:partition-id';
+
+export function usePartitionContext(): PartitionContext {
+  const [rawPartitionId, setRawPartitionId] = useLocalStorage<string>(
+    PARTITION_STORAGE_KEY,
+    ''
+  );
+
+  const normalizedPartitionId = rawPartitionId.trim();
+
+  return useMemo(
+    () => ({
+      partitionId:
+        normalizedPartitionId.length > 0 ? normalizedPartitionId : undefined,
+      rawPartitionId,
+      setPartitionId: setRawPartitionId,
+      clearPartitionId: () => setRawPartitionId(''),
+    }),
+    [normalizedPartitionId, rawPartitionId, setRawPartitionId]
+  );
+}

package/src/hooks/usePreferences.ts

@@ -0,0 +1,72 @@
+/**
+ * UI preferences hook with localStorage persistence
+ */
+
+import { useLocalStorage } from './useLocalStorage';
+
+interface ConsolePreferences {
+  /** Refresh interval for auto-updating data (in seconds) */
+  refreshInterval: number;
+  /** Time format: 'relative' (e.g., "5 minutes ago") or 'absolute' (e.g., "2024-01-15 10:30") */
+  timeFormat: 'relative' | 'absolute';
+  /** Show sparklines in stats cards */
+  showSparklines: boolean;
+  /** Number of items per page in tables */
+  pageSize: number;
+}
+
+const DEFAULT_PREFERENCES: ConsolePreferences = {
+  refreshInterval: 5,
+  timeFormat: 'relative',
+  showSparklines: true,
+  pageSize: 20,
+};
+
+export function usePreferences() {
+  const [preferences, setPreferences] = useLocalStorage<ConsolePreferences>(
+    'console:preferences',
+    DEFAULT_PREFERENCES
+  );
+
+  const updatePreference = <K extends keyof ConsolePreferences>(
+    key: K,
+    value: ConsolePreferences[K]
+  ) => {
+    setPreferences((prev) => ({
+      ...prev,
+      [key]: value,
+    }));
+  };
+
+  const resetPreferences = () => {
+    setPreferences(DEFAULT_PREFERENCES);
+  };
+
+  return {
+    preferences,
+    setPreferences,
+    updatePreference,
+    resetPreferences,
+  };
+}
+
+/**
+ * Available refresh interval options
+ */
+export const REFRESH_INTERVAL_OPTIONS = [
+  { value: 5, label: '5 seconds' },
+  { value: 10, label: '10 seconds' },
+  { value: 30, label: '30 seconds' },
+  { value: 60, label: '1 minute' },
+  { value: 0, label: 'Manual only' },
+];
+
+/**
+ * Available page size options
+ */
+export const PAGE_SIZE_OPTIONS = [
+  { value: 10, label: '10' },
+  { value: 20, label: '20' },
+  { value: 50, label: '50' },
+  { value: 100, label: '100' },
+];

package/src/hooks/useRequestEvents.ts

@@ -0,0 +1,35 @@
+/**
+ * React Query hooks for Request Events
+ */
+
+import { useMutation, useQueryClient } from '@tanstack/react-query';
+import { useApiClient, useConnection } from './ConnectionContext';
+import { useInstanceContext } from './useInstanceContext';
+
+export function useClearEventsMutation() {
+  const client = useApiClient();
+  const { config: connectionConfig } = useConnection();
+  const { instanceId } = useInstanceContext();
+  const queryClient = useQueryClient();
+
+  return useMutation<{ deletedCount: number }, Error, void>({
+    mutationFn: async () => {
+      if (!client || !connectionConfig) throw new Error('Not connected');
+      const queryString = new URLSearchParams();
+      if (instanceId) queryString.set('instanceId', instanceId);
+      const suffix = queryString.toString();
+      const response = await fetch(
+        `${connectionConfig.serverUrl}/console/events${suffix ? `?${suffix}` : ''}`,
+        {
+          method: 'DELETE',
+          headers: { Authorization: `Bearer ${connectionConfig.token}` },
+        }
+      );
+      if (!response.ok) throw new Error('Failed to clear events');
+      return response.json();
+    },
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ['console', 'events'] });
+    },
+  });
+}

package/src/hooks/useTimeRange.ts

@@ -0,0 +1,34 @@
+/**
+ * Global time range context for dashboard charts
+ */
+
+import { createContext } from 'react';
+import type { TimeseriesRange } from '../lib/types';
+import { useLocalStorage } from './useLocalStorage';
+
+interface TimeRangeContextValue {
+  /** Current time range */
+  range: TimeseriesRange;
+  /** Set the time range */
+  setRange: (range: TimeseriesRange) => void;
+}
+
+export const TimeRangeContext = createContext<TimeRangeContextValue | null>(
+  null
+);
+
+/**
+ * Hook to create time range state with localStorage persistence.
+ * Use this at the provider level.
+ */
+export function useTimeRangeState(): TimeRangeContextValue {
+  const [range, setRange] = useLocalStorage<TimeseriesRange>(
+    'console:time-range',
+    '24h'
+  );
+
+  return {
+    range,
+    setRange,
+  };
+}

package/src/index.ts

@@ -0,0 +1,8 @@
+export * from './App';
+export * from './hooks';
+export * from './layout';
+export * from './lib/api';
+export * from './mount';
+export * from './pages';
+export * from './routeTree';
+export * from './sentry';