@djangocfg/centrifugo 1.0.3 → 1.0.4

package/README.md

@@ -1,41 +1,57 @@
 # @djangocfg/centrifugo
 
-Professional Centrifugo WebSocket client with React integration and comprehensive debugging tools.
+Professional Centrifugo WebSocket client with React integration, composable UI components, and comprehensive monitoring tools.
 
 ## Features
 
 - 🔌 **Robust WebSocket Connection** - Auto-reconnect, error handling, and connection state management
-- 📊 **Advanced Logging System** - Circular buffer with dual output (console + in-memory accumulation)
-- 🐛 **Debug UI** - Development-only debug panel with bash-like logs viewer
+- 🔄 **RPC Pattern Support** - Request-response via correlation ID for synchronous-like communication
+- 📊 **Advanced Logging System** - Circular buffer with dual output (consola + in-memory accumulation)
+- 🧩 **Composable UI Components** - Flexible, reusable components for any use case
+- 🐛 **Monitoring Tools** - Real-time connection status, message feed, and subscriptions list
 - ⚛️ **React Integration** - Context providers and hooks for seamless integration
-- 🎯 **Type-Safe** - Full TypeScript support with comprehensive type definitions
+- 🎯 **Type-Safe** - Full TypeScript support with proper Centrifuge types
 - 🏗️ **Platform-Agnostic Core** - Core modules can be used without React
-- 🎨 **Beautiful UI Components** - Pre-built components using shadcn/ui
+- 🎨 **Beautiful UI** - Pre-built components using shadcn/ui
+- 📅 **Moment.js Integration** - Consistent UTC time handling throughout
 
 ## Architecture
 
 ```
 src/
-├── core/              # Platform-agnostic (no React dependencies)
-│   ├── client/        # CentrifugoRPCClient - WebSocket client
-│   ├── logger/        # Logging system with circular buffer
-│   └── types/         # TypeScript type definitions
-├── providers/         # React Context providers
-│   ├── CentrifugoProvider/  # Main connection provider
+├── core/                    # Platform-agnostic (no React dependencies)
+│   ├── client/              # CentrifugoRPCClient - WebSocket client
+│   ├── logger/              # Logging system with circular buffer
+│   │   ├── createLogger.ts  # Logger factory (supports string prefix)
+│   │   └── LogsStore.ts     # In-memory logs accumulation
+│   └── types/               # TypeScript type definitions
+├── providers/               # React Context providers
+│   ├── CentrifugoProvider/  # Main connection provider (no auto-FAB)
 │   └── LogsProvider/        # Logs accumulation provider
-├── hooks/             # React hooks
-│   └── useSubscription.ts   # Channel subscription hook
-└── debug/             # Development-only debug UI (lazy loaded)
-    ├── DebugPanel/          # Main debug panel with FAB button
-    ├── ConnectionTab/       # Connection status and controls
-    ├── LogsTab/             # Bash-like logs viewer
-    └── SubscriptionsTab/    # Active subscriptions list
+├── hooks/                   # React hooks
+│   ├── useSubscription.ts   # Channel subscription hook
+│   └── useRPC.ts            # RPC request-response hook
+└── components/              # Composable UI components
+    ├── ConnectionStatus/    # Connection status display
+    │   ├── ConnectionStatus.tsx        # Badge/inline/detailed variants
+    │   └── ConnectionStatusCard.tsx    # Card wrapper for dashboards
+    ├── MessagesFeed/        # Real-time message feed
+    │   ├── MessagesFeed.tsx            # Main feed component
+    │   ├── MessageFilters.tsx          # Filtering controls
+    │   └── types.ts                    # Message types
+    ├── SubscriptionsList/   # Active subscriptions list
+    │   └── SubscriptionsList.tsx       # List with controls
+    └── CentrifugoMonitor/   # Main monitoring component
+        ├── CentrifugoMonitor.tsx       # Composable monitor
+        ├── CentrifugoMonitorDialog.tsx # Modal variant
+        ├── CentrifugoMonitorFAB.tsx    # FAB variant (manual)
+        └── CentrifugoMonitorWidget.tsx # Dashboard widget
 ```
 
 ## Installation
 
 ```bash
-pnpm add @djangocfg/centrifugo
+pnpm add @djangocfg/centrifugo moment
 ```
 
 ## Quick Start
@@ -43,7 +59,7 @@ pnpm add @djangocfg/centrifugo
 ### 1. Wrap your app with CentrifugoProvider
 
 ```tsx
-import { CentrifugoProvider, DebugPanel } from '@djangocfg/centrifugo';
+import { CentrifugoProvider } from '@djangocfg/centrifugo';
 
 function App() {
   return (
@@ -52,15 +68,42 @@ function App() {
       autoConnect={true}
     >
       <YourApp />
+    </CentrifugoProvider>
+  );
+}
+```
+
+### 2. Add Monitoring FAB (Optional)
+
+The FAB is **not** automatically included. You control when and where to show it:
+
+```tsx
+import { CentrifugoProvider, CentrifugoMonitorFAB } from '@djangocfg/centrifugo';
+import { useAuth } from '@djangocfg/layouts';
+
+function CentrifugoMonitor() {
+  const { isAdminUser } = useAuth();
+  const isDevelopment = process.env.NODE_ENV === 'development';
+  
+  // Show FAB only for admins or in development
+  if (!isDevelopment && !isAdminUser) {
+    return null;
+  }
+  
+  return <CentrifugoMonitorFAB variant="full" />;
+}
 
-      {/* Debug panel (only shows in development) */}
-      <DebugPanel />
+function App() {
+  return (
+    <CentrifugoProvider enabled={true} autoConnect={true}>
+      <YourApp />
+      <CentrifugoMonitor />
     </CentrifugoProvider>
   );
 }
 ```
 
-### 2. Use the connection in your components
+### 3. Use the connection in your components
 
 ```tsx
 import { useCentrifugo } from '@djangocfg/centrifugo';
@@ -78,7 +121,7 @@ function YourComponent() {
 }
 ```
 
-### 3. Subscribe to channels
+### 4. Subscribe to channels
 
 ```tsx
 import { useSubscription } from '@djangocfg/centrifugo';
@@ -185,65 +228,305 @@ interface UseSubscriptionOptions<T> {
 }
 ```
 
-### LogsProvider
+### useRPC()
+
+Hook for making RPC calls using correlation ID pattern.
+
+**What is RPC Pattern?**
 
-Provider for accessing accumulated logs.
+Centrifugo is pub/sub (fire-and-forget) and doesn't support RPC natively. We implement request-response pattern using **correlation ID** to match requests with responses:
+
+```
+1. Client generates unique correlation_id
+2. Client subscribes to personal reply channel (user#{userId})
+3. Client publishes request with correlation_id to rpc#{method}
+4. Backend processes and publishes response with same correlation_id
+5. Client matches response by correlation_id and resolves Promise
+```
+
+**Basic Usage:**
 
 ```tsx
-const {
-  logs,          // All logs
-  filteredLogs,  // Filtered logs
-  count,         // Total count
-  filter,        // Current filter
-  setFilter,     // Update filter
-  clearLogs,     // Clear all logs
-} = useLogs();
+import { useRPC } from '@djangocfg/centrifugo';
+
+function MyComponent() {
+  const { call, isLoading, error } = useRPC();
+
+  const handleGetStats = async () => {
+    try {
+      const result = await call('tasks.get_stats', { bot_id: '123' });
+      console.log('Stats:', result);
+    } catch (error) {
+      console.error('RPC failed:', error);
+    }
+  };
+
+  return (
+    <button onClick={handleGetStats} disabled={isLoading}>
+      {isLoading ? 'Loading...' : 'Get Stats'}
+    </button>
+  );
+}
 ```
 
-## Debug Panel
+**With Type Safety:**
 
-The debug panel is a development-only UI that provides:
+```tsx
+interface GetStatsRequest {
+  bot_id: string;
+}
 
-1. **Connection Tab** - View connection status, uptime, and controls
-2. **Logs Tab** - Bash-like logs viewer with:
-   - Filter by level (debug/info/success/warning/error)
-   - Filter by source (client/provider/subscription/system)
-   - Search functionality with debounce
-   - Auto-scroll toggle
-   - Expandable JSON data with syntax highlighting
-3. **Subscriptions Tab** - View and manage active subscriptions
+interface GetStatsResponse {
+  total_tasks: number;
+  completed: number;
+  failed: number;
+}
+
+const { call } = useRPC();
+
+const result = await call<GetStatsRequest, GetStatsResponse>(
+  'tasks.get_stats',
+  { bot_id: '123' }
+);
+
+console.log(result.total_tasks); // Type-safe!
+```
+
+**With Custom Options:**
 
-**Usage:**
 ```tsx
-import { DebugPanel } from '@djangocfg/centrifugo';
+const { call, isLoading, error, reset } = useRPC({
+  timeout: 30000, // 30 seconds
+  onError: (error) => {
+    toast.error(`RPC failed: ${error.message}`);
+  },
+});
 
-function App() {
+// Reset state
+reset();
+```
+
+**Options:**
+```typescript
+interface UseRPCOptions {
+  timeout?: number;           // Default: 10000ms
+  replyChannel?: string;      // Default: user#{userId}
+  onError?: (error: Error) => void;
+}
+
+interface UseRPCResult {
+  call: <TRequest, TResponse>(
+    method: string,
+    params: TRequest,
+    options?: UseRPCOptions
+  ) => Promise<TResponse>;
+  isLoading: boolean;
+  error: Error | null;
+  reset: () => void;
+}
+```
+
+**Backend Implementation:**
+
+The backend should subscribe to `rpc#{method}` channels and publish responses:
+
+```python
+# Django backend example
+from django_cfg.apps.integrations.centrifugo import get_centrifugo_publisher
+
+publisher = get_centrifugo_publisher()
+
+# Listen to RPC requests (via Centrifugo subscription)
+async def handle_rpc_request(data):
+    correlation_id = data['correlation_id']
+    method = data['method']
+    params = data['params']
+    reply_to = data['reply_to']
+    
+    try:
+        # Process request
+        result = await process_task_stats(params['bot_id'])
+        
+        # Send response
+        await publisher.publish(
+            channel=reply_to,
+            data={
+                'correlation_id': correlation_id,
+                'result': result,
+            }
+        )
+    except Exception as e:
+        # Send error response
+        await publisher.publish(
+            channel=reply_to,
+            data={
+                'correlation_id': correlation_id,
+                'error': {'message': str(e)},
+            }
+        )
+```
+
+## UI Components
+
+All components are composable and can be used independently or together.
+
+### ConnectionStatus
+
+Display connection status in various formats.
+
+**Variants:**
+- `badge` - Compact badge with status indicator
+- `inline` - Inline text with icon
+- `detailed` - Detailed view with uptime and subscriptions
+
+```tsx
+import { ConnectionStatus } from '@djangocfg/centrifugo';
+
+// Badge variant
+<ConnectionStatus variant="badge" />
+
+// Detailed variant with uptime and subscriptions
+<ConnectionStatus 
+  variant="detailed" 
+  showUptime={true}
+  showSubscriptions={true}
+/>
+```
+
+**ConnectionStatusCard** - Card wrapper for dashboards:
+
+```tsx
+import { ConnectionStatusCard } from '@djangocfg/centrifugo';
+
+<ConnectionStatusCard />
+```
+
+### MessagesFeed
+
+Real-time feed of Centrifugo messages with filtering and export.
+
+```tsx
+import { MessagesFeed } from '@djangocfg/centrifugo';
+
+<MessagesFeed
+  maxMessages={100}
+  showFilters={true}
+  showControls={true}
+  autoScroll={true}
+  onMessageClick={(msg) => console.log(msg)}
+/>
+```
+
+**Features:**
+- Filter by type, level, channel
+- Search functionality
+- Pause/play auto-scroll
+- Download messages as JSON
+- Clear messages
+
+### SubscriptionsList
+
+List of active subscriptions with management controls.
+
+```tsx
+import { SubscriptionsList } from '@djangocfg/centrifugo';
+
+<SubscriptionsList
+  showControls={true}
+  onSubscriptionClick={(channel) => console.log(channel)}
+/>
+```
+
+**Features:**
+- Real-time subscription updates
+- Unsubscribe from channels
+- Click to view channel details
+
+### CentrifugoMonitor
+
+Main monitoring component with multiple variants.
+
+**Basic Usage:**
+
+```tsx
+import { CentrifugoMonitor } from '@djangocfg/centrifugo';
+
+// Embedded in a page
+<CentrifugoMonitor defaultTab="messages" />
+```
+
+**Dialog Variant:**
+
+```tsx
+import { CentrifugoMonitorDialog } from '@djangocfg/centrifugo';
+
+function MyComponent() {
+  const [open, setOpen] = useState(false);
+  
   return (
     <>
-      <YourApp />
-      <DebugPanel />
+      <button onClick={() => setOpen(true)}>Open Monitor</button>
+      <CentrifugoMonitorDialog 
+        open={open} 
+        onOpenChange={setOpen}
+        defaultTab="status"
+      />
     </>
   );
 }
 ```
 
-The panel only renders in development mode (`NODE_ENV === 'development'`). It appears as a floating action button (FAB) in the bottom-left corner.
+**FAB Variant:**
+
+```tsx
+import { CentrifugoMonitorFAB } from '@djangocfg/centrifugo';
+
+// Full variant with all tabs
+<CentrifugoMonitorFAB variant="full" />
+
+// Compact variant (status only)
+<CentrifugoMonitorFAB variant="compact" />
+```
+
+**Widget Variant (for Dashboards):**
+
+```tsx
+import { CentrifugoMonitorWidget } from '@djangocfg/centrifugo';
+
+<CentrifugoMonitorWidget defaultTab="subscriptions" />
+```
+
+**Props:**
+```typescript
+interface CentrifugoMonitorProps {
+  defaultTab?: 'status' | 'messages' | 'subscriptions';
+  className?: string;
+}
+```
 
 ## Logging System
 
 The package includes a sophisticated logging system with:
 
 - **Circular Buffer** - Stores up to 500 logs (configurable)
-- **Dual Output** - Console (dev only) + in-memory store (always)
+- **Dual Output** - Consola (dev only) + in-memory store (always)
 - **Structured Logs** - Timestamp, level, source, message, and optional data
 - **Real-time Updates** - Subscribe to log changes for React updates
+- **Prefixed Output** - Logger name appears as `[YourComponent]` in console
 
 **Creating a Logger:**
+
 ```typescript
 import { createLogger } from '@djangocfg/centrifugo';
 
+// Simple usage with string prefix
+const logger = createLogger('MyComponent');
+
+// Advanced usage with full config
 const logger = createLogger({
-  source: 'my-module', // or 'client' | 'provider' | 'subscription' | 'system'
+  source: 'client', // 'client' | 'provider' | 'subscription' | 'system'
+  tag: 'MyComponent',
+  isDevelopment: true,
 });
 
 logger.debug('Debug message', { extra: 'data' });
@@ -254,6 +537,7 @@ logger.error('Error message', error);
 ```
 
 **Accessing Logs:**
+
 ```typescript
 import { getGlobalLogsStore } from '@djangocfg/centrifugo';
 
@@ -271,6 +555,39 @@ const unsubscribe = logsStore.subscribe((logs) => {
 logsStore.clear();
 ```
 
+**Using LogsProvider:**
+
+```tsx
+import { useLogs } from '@djangocfg/centrifugo';
+
+function CustomLogsView() {
+  const { logs, setFilter, clearLogs } = useLogs();
+
+  return (
+    <div>
+      <button onClick={() => setFilter({ level: 'error' })}>
+        Show Errors Only
+      </button>
+      <button onClick={() => setFilter({ source: 'client' })}>
+        Show Client Logs
+      </button>
+      <button onClick={() => setFilter({ search: 'WebSocket' })}>
+        Search "WebSocket"
+      </button>
+      <button onClick={clearLogs}>
+        Clear All
+      </button>
+      
+      <ul>
+        {logs.map(log => (
+          <li key={log.id}>{log.message}</li>
+        ))}
+      </ul>
+    </div>
+  );
+}
+```
+
 ## Advanced Usage
 
 ### Using the Core Client (without React)
@@ -278,41 +595,66 @@ logsStore.clear();
 ```typescript
 import { CentrifugoRPCClient, createLogger } from '@djangocfg/centrifugo';
 
-const logger = createLogger({ source: 'client' });
+const logger = createLogger('MyApp');
 const client = new CentrifugoRPCClient(
   'ws://localhost:8000/ws',
   'your-token',
   'user-id',
   30000, // timeout
-  logger
+  (entry) => logger.info(entry.message, entry.data)
 );
 
 await client.connect();
-await client.subscribe('channel-name');
+
+// Subscribe to channel
+const unsubscribe = client.subscribe('channel-name', (data) => {
+  console.log('Message:', data);
+});
+
+// Get native Centrifuge client for low-level access
+const centrifuge = client.getCentrifuge();
+centrifuge.on('connected', () => console.log('Connected'));
 ```
 
-### Custom Log Filters
+### Custom Dashboard Integration
 
 ```tsx
-import { useLogs } from '@djangocfg/centrifugo';
+import {
+  ConnectionStatusCard,
+  MessagesFeed,
+  SubscriptionsList,
+} from '@djangocfg/centrifugo';
 
-function CustomLogsView() {
-  const { logs, setFilter } = useLogs();
+function Dashboard() {
+  return (
+    <div className="grid grid-cols-3 gap-4">
+      <ConnectionStatusCard />
+      
+      <div className="col-span-2">
+        <MessagesFeed 
+          maxMessages={50}
+          showFilters={false}
+        />
+      </div>
+      
+      <div className="col-span-3">
+        <SubscriptionsList showControls={true} />
+      </div>
+    </div>
+  );
+}
+```
+
+### Embedded Monitor in Page
+
+```tsx
+import { CentrifugoMonitor } from '@djangocfg/centrifugo';
 
+function MonitoringPage() {
   return (
-    <div>
-      <button onClick={() => setFilter({ level: 'error' })}>
-        Show Errors Only
-      </button>
-      <button onClick={() => setFilter({ source: 'client' })}>
-        Show Client Logs
-      </button>
-      <button onClick={() => setFilter({ search: 'WebSocket' })}>
-        Search "WebSocket"
-      </button>
-      <button onClick={() => setFilter({})}>
-        Clear Filters
-      </button>
+    <div className="container mx-auto p-6">
+      <h1>WebSocket Monitoring</h1>
+      <CentrifugoMonitor defaultTab="messages" />
     </div>
   );
 }
@@ -347,37 +689,144 @@ import type {
   // Hooks
   UseSubscriptionOptions,
   UseSubscriptionResult,
+
+  // Components
+  ConnectionStatusProps,
+  MessagesFeedProps,
+  SubscriptionsListProps,
+  CentrifugoMonitorProps,
 } from '@djangocfg/centrifugo';
 ```
 
-## Migration from Old Version
+**Proper Centrifuge Types:**
 
-If you're migrating from `src_old`, the main changes are:
+The package now uses proper types from the `centrifuge` library:
 
-1. **Import paths** - All imports now come from `@djangocfg/centrifugo`
-2. **Provider structure** - `CentrifugoProvider` now wraps `LogsProvider`
-3. **New hooks** - `useSubscription` replaces manual subscription management
-4. **Debug UI** - New `DebugPanel` component replaces old debugging
-5. **Logger API** - New `createLogger` with better structure
+```typescript
+import type { Subscription, SubscriptionState } from 'centrifuge';
+
+// No more 'as any' - fully type-safe!
+const centrifuge = client.getCentrifuge();
+const subs = centrifuge.subscriptions();
+
+for (const [channel, sub] of Object.entries(subs)) {
+  console.log(channel, sub.state); // SubscriptionState type
+}
+```
+
+## Best Practices
+
+### 1. Logger Usage
+
+Always use the logger instead of `console`:
+
+```typescript
+// ❌ Bad
+console.log('Message');
+
+// ✅ Good
+const logger = createLogger('MyComponent');
+logger.info('Message');
+```
+
+### 2. Date Handling
+
+Use `moment` with UTC for all date operations:
+
+```typescript
+import moment from 'moment';
+
+// ❌ Bad
+const now = new Date();
+const timestamp = Date.now();
+
+// ✅ Good
+const now = moment.utc();
+const timestamp = moment.utc().valueOf();
+const formatted = moment.utc().format('YYYY-MM-DD HH:mm:ss');
+```
+
+### 3. FAB Control
+
+Don't rely on auto-showing FAB. Control it explicitly:
+
+```typescript
+// ✅ Good - Developer has full control
+function App() {
+  return (
+    <CentrifugoProvider enabled={true}>
+      <YourApp />
+      {shouldShowMonitor && <CentrifugoMonitorFAB />}
+    </CentrifugoProvider>
+  );
+}
+```
+
+### 4. Component Composition
+
+Use individual components for custom layouts:
+
+```typescript
+// ✅ Good - Compose as needed
+<div className="monitoring-panel">
+  <ConnectionStatus variant="detailed" showUptime />
+  <MessagesFeed maxMessages={50} />
+  <SubscriptionsList />
+</div>
+```
+
+## Migration Guide
+
+### From Old DebugPanel
 
 **Before:**
 ```tsx
-import { WSRPCContext } from './rpc/WSRPCContext';
+import { DebugPanel } from '@djangocfg/centrifugo';
+
+// Auto-shown in development
+<CentrifugoProvider>
+  <App />
+</CentrifugoProvider>
 ```
 
 **After:**
 ```tsx
-import { CentrifugoProvider, useCentrifugo } from '@djangocfg/centrifugo';
+import { CentrifugoMonitorFAB } from '@djangocfg/centrifugo';
+
+// Manual control
+<CentrifugoProvider>
+  <App />
+  <CentrifugoMonitorFAB variant="full" />
+</CentrifugoProvider>
+```
+
+### From date-fns to moment
+
+**Before:**
+```typescript
+import { format } from 'date-fns';
+
+const formatted = format(new Date(), 'yyyy-MM-dd HH:mm:ss');
+```
+
+**After:**
+```typescript
+import moment from 'moment';
+
+const formatted = moment.utc().format('YYYY-MM-DD HH:mm:ss');
 ```
 
 ## Development
 
 ```bash
+# Install dependencies
+pnpm install
+
 # Build the package
 pnpm build
 
 # Type check
-pnpm exec tsc --noEmit
+pnpm check
 
 # Run in development mode
 pnpm dev
@@ -386,9 +835,11 @@ pnpm dev
 ## Requirements
 
 - React 18+
-- `@djangocfg/ui` - UI components
+- `@djangocfg/ui` - UI components (shadcn/ui based)
 - `@djangocfg/layouts` - Layout components
 - `centrifuge` - WebSocket client library
+- `moment` - Date manipulation library
+- `consola` - Beautiful console logging
 
 ## License