@djangocfg/centrifugo 2.1.231 → 2.1.233

package/README.md

@@ -1,3 +1,9 @@
+<div align="center">
+
+![@djangocfg/centrifugo](https://raw.githubusercontent.com/markolofsen/assets/main/libs/djangocfg/centrifugo.webp)
+
+</div>
+
 # @djangocfg/centrifugo
 
 > Production-ready Centrifugo WebSocket client for React with real-time subscriptions, RPC patterns, and connection state management
@@ -5,73 +11,9 @@
 [![npm version](https://img.shields.io/npm/v/@djangocfg/centrifugo.svg)](https://www.npmjs.com/package/@djangocfg/centrifugo)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 
-**Part of [DjangoCFG](https://djangocfg.com)** — a modern Django framework for building production-ready SaaS applications. All `@djangocfg/*` packages are designed to work together, providing type-safe configuration, real-time features, and beautiful admin interfaces out of the box.
-
----
-
-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
-- 👁️ **Page Visibility Handling** - Auto-reconnect when tab becomes active, pause reconnects when hidden (saves battery)
-- 🔄 **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 proper Centrifuge types
-- 🏗️ **Platform-Agnostic Core** - Core modules can be used without React
-- 🎨 **Beautiful UI** - Pre-built components using shadcn/ui
-- 📅 **Moment.js Integration** - Consistent UTC time handling throughout
+**Part of [DjangoCFG](https://djangocfg.com)** — a modern Django framework for building production-ready SaaS applications.
 
-## Architecture
-
-```
-src/
-├── core/                    # Platform-agnostic (no React dependencies)
-│   ├── client/              # CentrifugoRPCClient - WebSocket client
-│   │   ├── CentrifugoRPCClient.ts  # Main facade (~165 lines)
-│   │   ├── connection.ts           # Connection lifecycle
-│   │   ├── subscriptions.ts        # Channel subscriptions
-│   │   ├── rpc.ts                  # RPC methods (namedRPC, namedRPCWithRetry, namedRPCNoWait)
-│   │   ├── version.ts              # API version checking
-│   │   ├── types.ts                # Type definitions
-│   │   └── index.ts                # Exports
-│   ├── errors/              # Error handling with retry logic
-│   │   ├── RPCError.ts      # Typed RPC errors (isRetryable, userMessage)
-│   │   └── RPCRetryHandler.ts # Exponential backoff retry
-│   ├── logger/              # Logging system with circular buffer
-│   │   ├── createLogger.ts  # Logger factory (supports string prefix)
-│   │   └── LogsStore.ts     # In-memory logs accumulation
-│   └── types/               # TypeScript type definitions
-├── events.ts                # Unified event system (single 'centrifugo' event)
-├── providers/               # React Context providers
-│   ├── CentrifugoProvider/  # Main connection provider (no auto-FAB)
-│   └── LogsProvider/        # Logs accumulation provider
-├── hooks/                   # React hooks
-│   ├── useSubscription.ts   # Channel subscription hook
-│   ├── useRPC.ts            # RPC request-response hook
-│   ├── useNamedRPC.ts       # Native Centrifugo RPC hook
-│   └── usePageVisibility.ts # Browser tab visibility tracking
-└── 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
+## Install
 
 ```bash
 pnpm add @djangocfg/centrifugo moment
@@ -84,49 +26,16 @@ pnpm add @djangocfg/centrifugo moment
 ```tsx
 import { CentrifugoProvider } from '@djangocfg/centrifugo';
 
-function App() {
-  return (
-    <CentrifugoProvider
-      enabled={true}
-      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" />;
-}
-
 function App() {
   return (
     <CentrifugoProvider enabled={true} autoConnect={true}>
       <YourApp />
-      <CentrifugoMonitor />
     </CentrifugoProvider>
   );
 }
 ```
 
-### 3. Use the connection in your components
+### 2. Use the connection
 
 ```tsx
 import { useCentrifugo } from '@djangocfg/centrifugo';
@@ -134,1333 +43,83 @@ import { useCentrifugo } from '@djangocfg/centrifugo';
 function YourComponent() {
   const { isConnected, connectionState, uptime } = useCentrifugo();
 
-  return (
-    <div>
-      <p>Status: {isConnected ? 'Connected' : 'Disconnected'}</p>
-      <p>State: {connectionState}</p>
-      <p>Uptime: {uptime}s</p>
-    </div>
-  );
+  return <p>Status: {isConnected ? 'Connected' : 'Disconnected'}</p>;
 }
 ```
 
-### 4. Subscribe to channels
+### 3. Subscribe to channels
 
 ```tsx
 import { useSubscription } from '@djangocfg/centrifugo';
 
-function NotificationsComponent() {
+function Notifications() {
   const { data, isSubscribed } = useSubscription({
     channel: 'notifications',
     enabled: true,
-    onPublication: (data) => {
-      console.log('New notification:', data);
-    },
-    onError: (error) => {
-      console.error('Subscription error:', error);
-    },
+    onPublication: (data) => console.log('New:', data),
   });
 
-  return (
-    <div>
-      <p>Subscribed: {isSubscribed ? 'Yes' : 'No'}</p>
-      {data && <pre>{JSON.stringify(data, null, 2)}</pre>}
-    </div>
-  );
+  return <p>Subscribed: {isSubscribed ? 'Yes' : 'No'}</p>;
 }
 ```
 
-## Core APIs
-
-### CentrifugoProvider
-
-Main provider that manages the WebSocket connection.
-
-**Props:**
-- `enabled?: boolean` - Enable/disable the connection (default: `false`)
-- `url?: string` - WebSocket URL (falls back to user.centrifugo.centrifugo_url)
-- `autoConnect?: boolean` - Auto-connect when authenticated (default: `true`)
-
-**Context Value:**
-```typescript
-interface CentrifugoContextValue {
-  // Client
-  client: CentrifugoRPCClient | null;
-
-  // Connection State
-  isConnected: boolean;
-  isConnecting: boolean;
-  error: Error | null;
-  connectionState: 'disconnected' | 'connecting' | 'connected' | 'error';
-
-  // Connection Info
-  uptime: number; // seconds
-  subscriptions: string[];
-  activeSubscriptions: ActiveSubscription[];
-
-  // Controls
-  connect: () => Promise<void>;
-  disconnect: () => void;
-  reconnect: () => Promise<void>;
-  unsubscribe: (channel: string) => void;
-
-  // Config
-  enabled: boolean;
-}
-```
-
-### useCentrifugo()
-
-Hook to access the Centrifugo connection context.
-
-```tsx
-const {
-  client,
-  isConnected,
-  connectionState,
-  connect,
-  disconnect,
-  reconnect,
-} = useCentrifugo();
-```
-
-### useSubscription()
-
-Hook to subscribe to a channel with auto-cleanup.
-
-```tsx
-const { data, isSubscribed, error } = useSubscription({
-  channel: 'my-channel',
-  enabled: true, // optional
-  onPublication: (data) => {
-    // Handle new data
-  },
-  onError: (error) => {
-    // Handle error
-  },
-});
-```
-
-**Options:**
-```typescript
-interface UseSubscriptionOptions<T> {
-  channel: string;
-  enabled?: boolean;
-  onPublication?: (data: T) => void;
-  onError?: (error: Error) => void;
-}
-```
-
-### useRPC()
-
-Hook for making RPC calls using correlation ID pattern.
-
-**What is RPC Pattern?**
-
-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
-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>
-  );
-}
-```
-
-**With Type Safety:**
-
-```tsx
-interface GetStatsRequest {
-  bot_id: string;
-}
-
-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:**
-
-```tsx
-const { call, isLoading, error, reset } = useRPC({
-  timeout: 30000, // 30 seconds
-  onError: (error) => {
-    toast.error(`RPC failed: ${error.message}`);
-  },
-});
-
-// 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;
-}
-```
-
-### useNamedRPC() - Native Centrifugo RPC
-
-Hook for making **native Centrifugo RPC calls** via RPC proxy.
-
-**This is the recommended approach** for request-response patterns. It uses Centrifugo's built-in RPC mechanism which proxies requests to Django.
-
-**Flow:**
-```
-1. Client calls namedRPC('terminal.input', data)
-2. Centrifuge.js sends RPC over WebSocket
-3. Centrifugo proxies to Django: POST /centrifugo/rpc/
-4. Django routes to @websocket_rpc handler
-5. Response returned to client
-```
-
-**Basic Usage:**
+### 4. Make RPC calls
 
 ```tsx
 import { useNamedRPC } from '@djangocfg/centrifugo';
 
-function TerminalInput() {
-  const { call, isLoading, error } = useNamedRPC();
-
-  const handleSendInput = async (input: string) => {
-    try {
-      const result = await call('terminal.input', {
-        session_id: 'abc-123',
-        data: btoa(input)  // Base64 encode
-      });
-      console.log('Result:', result);
-    } catch (error) {
-      console.error('RPC failed:', error);
-    }
-  };
-
-  return (
-    <button onClick={() => handleSendInput('ls -la')} disabled={isLoading}>
-      {isLoading ? 'Sending...' : 'Send Command'}
-    </button>
-  );
-}
-```
-
-**With Type Safety:**
-
-```tsx
-interface TerminalInputRequest {
-  session_id: string;
-  data: string;  // Base64 encoded
-}
-
-interface TerminalInputResponse {
-  success: boolean;
-  message?: string;
-}
-
-const { call } = useNamedRPC();
-
-const result = await call<TerminalInputRequest, TerminalInputResponse>(
-  'terminal.input',
-  { session_id: 'abc-123', data: btoa('ls -la') }
-);
-
-console.log(result.success); // Type-safe!
-```
-
-**Backend Handler:**
-
-```python
-# Django backend with @websocket_rpc decorator
-from pydantic import BaseModel, Field
-from django_cfg.apps.integrations.centrifugo.decorators import websocket_rpc
+function Terminal() {
+  const { call, isLoading } = useNamedRPC();
 
-class TerminalInputParams(BaseModel):
-    session_id: str = Field(..., description="Session UUID")
-    data: str = Field(..., description="Base64 encoded input")
-
-class SuccessResult(BaseModel):
-    success: bool
-    message: str = ""
-
-@websocket_rpc("terminal.input")
-async def terminal_input(conn, params: TerminalInputParams) -> SuccessResult:
-    """Handle terminal input from browser."""
-    # Forward to gRPC/Electron terminal
-    await forward_to_terminal(params.session_id, base64.b64decode(params.data))
-    return SuccessResult(success=True, message="Input sent")
-```
-
-**Options:**
-```typescript
-interface UseNamedRPCOptions {
-  onError?: (error: Error) => void;
-}
-
-interface UseNamedRPCResult {
-  call: <TRequest, TResponse>(
-    method: string,
-    data: TRequest
-  ) => Promise<TResponse>;
-  isLoading: boolean;
-  error: Error | null;
-  reset: () => void;
-}
-```
-
-> **Note:** `useNamedRPC` uses native Centrifugo RPC which requires RPC proxy to be configured in Centrifugo server. See the [Setup Guide](https://djangocfg.com/docs/features/integrations/centrifugo/client-generation/) for configuration details.
-
-### usePageVisibility()
-
-Hook for tracking browser tab visibility. Built into `CentrifugoProvider` for automatic reconnection handling.
-
-**Built-in Behavior (CentrifugoProvider):**
-
-The provider automatically handles visibility changes:
-- **Tab hidden**: Pauses reconnect attempts (saves battery)
-- **Tab visible**: Triggers reconnect if connection was lost
-
-**Standalone Usage:**
-
-```tsx
-import { usePageVisibility } from '@djangocfg/centrifugo';
-
-function MyComponent() {
-  const { isVisible, wasHidden, hiddenDuration } = usePageVisibility({
-    onVisible: () => {
-      console.log('Tab is now visible');
-      // Refresh data, resume animations, etc.
-    },
-    onHidden: () => {
-      console.log('Tab is now hidden');
-      // Pause expensive operations
-    },
-    onChange: (isVisible) => {
-      console.log('Visibility changed:', isVisible);
-    },
-  });
-
-  return (
-    <div>
-      <p>Tab visible: {isVisible ? 'Yes' : 'No'}</p>
-      <p>Was hidden: {wasHidden ? 'Yes' : 'No'}</p>
-      {hiddenDuration > 0 && (
-        <p>Was hidden for: {Math.round(hiddenDuration / 1000)}s</p>
-      )}
-    </div>
-  );
-}
-```
-
-**Return Value:**
-```typescript
-interface UsePageVisibilityResult {
-  /** Whether the page is currently visible */
-  isVisible: boolean;
-  /** Whether the page was ever hidden during this session */
-  wasHidden: boolean;
-  /** Timestamp when page became visible */
-  visibleSince: number | null;
-  /** How long the page was hidden (ms) */
-  hiddenDuration: number;
-  /** Force check visibility state */
-  checkVisibility: () => boolean;
-}
-```
-
-**Options:**
-```typescript
-interface UsePageVisibilityOptions {
-  /** Callback when page becomes visible */
-  onVisible?: () => void;
-  /** Callback when page becomes hidden */
-  onHidden?: () => void;
-  /** Callback with visibility state change */
-  onChange?: (isVisible: boolean) => void;
-}
-```
-
-**Use Cases:**
-- Pause/resume WebSocket reconnection attempts
-- Refresh stale data when tab becomes active
-- Pause expensive animations or timers
-- Track user engagement metrics
-
-### namedRPCNoWait() - Fire-and-Forget RPC
-
-For latency-sensitive operations (like terminal input), use the fire-and-forget variant that returns immediately without waiting for a response.
-
-**When to use:**
-- Terminal input (user typing)
-- Real-time cursor position updates
-- Any operation where you don't need the response
-
-**Direct Client Usage:**
-
-```tsx
-import { useCentrifugo } from '@djangocfg/centrifugo';
-
-function TerminalInput() {
-  const { client } = useCentrifugo();
-
-  const handleKeyPress = (key: string) => {
-    // Fire-and-forget: returns immediately, doesn't wait for response
-    client?.namedRPCNoWait('terminal.input', {
+  const send = async (input: string) => {
+    const result = await call('terminal.input', {
       session_id: 'abc-123',
-      data: btoa(key)
+      data: btoa(input),
     });
   };
-
-  return <input onKeyPress={(e) => handleKeyPress(e.key)} />;
-}
-```
-
-**Backend Handler (Django):**
-
-```python
-@websocket_rpc("terminal.input", no_wait=True)
-async def terminal_input(conn, params: TerminalInputParams) -> SuccessResult:
-    """Handle terminal input (fire-and-forget)."""
-    import asyncio
-
-    # Spawn background task, return immediately
-    asyncio.create_task(_send_input_to_agent(params.session_id, params.data))
-
-    return SuccessResult(success=True, message="Input queued")
-```
-
-**Retry Logic with Exponential Backoff:**
-
-`namedRPCNoWait` includes automatic retry with exponential backoff:
-
-```tsx
-// Default: 3 retries, 100ms base delay, 2000ms max delay
-client?.namedRPCNoWait('terminal.input', { session_id, data });
-
-// Custom retry options
-client?.namedRPCNoWait('terminal.input', { session_id, data }, {
-  maxRetries: 5,      // Max retry attempts (default: 3)
-  baseDelayMs: 100,   // Base delay for exponential backoff (default: 100)
-  maxDelayMs: 3000,   // Max delay cap (default: 2000)
-});
-```
-
-**Retry sequence:** 100ms → 200ms → 400ms → 800ms → 1600ms (capped at maxDelayMs)
-
-**Performance comparison:**
-
-| Method | Latency | Use Case |
-|--------|---------|----------|
-| `namedRPC()` | ~800-1800ms | Commands that need response |
-| `namedRPCNoWait()` | ~10-30ms | Real-time input, fire-and-forget |
-
-### namedRPCWithRetry() - RPC with Timeout and Retry
-
-For operations that need both timeout protection and automatic retry on transient failures.
-
-```tsx
-import { useCentrifugo } from '@djangocfg/centrifugo';
-
-function FileList() {
-  const { client } = useCentrifugo();
-
-  const loadFiles = async () => {
-    // Automatically retries on timeout/network errors
-    const files = await client?.namedRPCWithRetry('files.list',
-      { path: '/home' },
-      {
-        timeout: 5000,      // 5 second timeout per attempt
-        maxRetries: 3,      // Up to 3 retries
-        baseDelayMs: 1000,  // Start with 1s delay
-        maxDelayMs: 10000,  // Cap at 10s
-        onRetry: (attempt, error, delay) => {
-          console.log(`Retry ${attempt}: ${error.userMessage}, waiting ${delay}ms`);
-        }
-      }
-    );
-    return files;
-  };
-}
-```
-
-### RPCError - Typed Error Handling
-
-All RPC methods now throw `RPCError` with classification for better error handling:
-
-```tsx
-import { RPCError } from '@djangocfg/centrifugo';
-
-try {
-  await client.namedRPC('files.list', { path: '/' });
-} catch (error) {
-  if (error instanceof RPCError) {
-    // Error classification
-    console.log(error.code);           // 'timeout' | 'network_error' | 'server_error' | ...
-    console.log(error.isRetryable);    // true for transient errors
-    console.log(error.userMessage);    // User-friendly message
-    console.log(error.suggestedRetryDelay); // Recommended delay in ms
-
-    // Show user-friendly message
-    toast.error(error.userMessage);
-
-    // Decide if retry makes sense
-    if (error.isRetryable) {
-      // Schedule retry
-    }
-  }
-}
-```
-
-**Error Codes:**
-
-| Code | Retryable | Description |
-|------|-----------|-------------|
-| `timeout` | ✅ | Request timed out |
-| `network_error` | ✅ | Network connectivity issue |
-| `connection_failed` | ✅ | WebSocket connection failed |
-| `websocket_error` | ✅ | WebSocket protocol error |
-| `server_error` | ✅ (5xx only) | Server returned error |
-| `not_connected` | ❌ | Client not connected |
-| `encoding_error` | ❌ | Failed to encode request |
-| `decoding_error` | ❌ | Failed to decode response |
-| `cancelled` | ❌ | Request was cancelled |
-
-### withRetry() - Generic Retry Utility
-
-For custom retry logic outside of RPC:
-
-```tsx
-import { withRetry, RPCError } from '@djangocfg/centrifugo';
-
-const result = await withRetry(
-  () => fetchSomething(),
-  {
-    maxRetries: 3,
-    baseDelayMs: 1000,
-    maxDelayMs: 10000,
-    jitterFactor: 0.2,  // ±20% randomization
-  },
-  (state, delay) => {
-    console.log(`Retry ${state.attempt}, waiting ${delay}ms`);
-  }
-);
-```
-
-### checkApiVersion() - API Contract Validation
-
-Validates that the client API version matches the server. Useful for detecting when the frontend needs to refresh after a backend deployment.
-
-```tsx
-import { API_VERSION } from '@/_ws';  // Generated client exports version hash
-
-// Check version after connect
-const result = await client.checkApiVersion(API_VERSION);
-
-if (!result.compatible) {
-  // Versions don't match - show refresh prompt
-  toast.warning('New version available. Please refresh the page.');
 }
 ```
 
-**Unified Event Handling:**
-
-Version mismatch automatically dispatches a `'centrifugo'` event:
-
-```tsx
-// Listen globally for version mismatch
-window.addEventListener('centrifugo', (e: CustomEvent) => {
-  if (e.detail.type === 'version_mismatch') {
-    const { clientVersion, serverVersion, message } = e.detail.data;
-    toast.warning(message);
-  }
-});
-```
-
-**How Version Hash Works:**
-
-The version hash is computed from:
-- All `@websocket_rpc` method signatures (name, params, return type)
-- All Pydantic model schemas used in handlers
-
-When any handler or model changes, the hash changes, triggering a version mismatch.
-
-## Auto-Generated Type-Safe Clients
-
-Django-CFG can auto-generate TypeScript clients from your `@websocket_rpc` handlers, providing full type safety and eliminating manual RPC calls.
-
-### Generate Clients
-
-```bash
-# Generate TypeScript client from @websocket_rpc handlers
-python manage.py generate_centrifugo_clients --typescript --output ./clients
-
-# Generate and auto-copy to Next.js app (recommended)
-python manage.py generate_centrifugo_clients --typescript
-# Outputs to: openapi/centrifuge/typescript/
-```
-
-This generates type-safe clients with:
-
-```
-typescript/
-├── client.ts       # Type-safe API methods
-├── types.ts        # Pydantic models → TypeScript interfaces
-├── index.ts        # Exports
-└── rpc-client.ts   # Low-level RPC client (optional)
-```
-
-**Copy to your app:**
-
-```bash
-# Manual copy
-cp -r openapi/centrifuge/typescript/* apps/web/app/_ws/
-
-# Or create a custom command for your project
-# See: core/management/commands/generate_centrifuge_web.py
-```
-
-### Using Generated Clients
-
-**Before (manual RPC):**
-```tsx
-// ❌ No type safety, easy to make mistakes
-const result = await client.namedRPC('ai_chat.get_messages', {
-  session_id: sessionId,
-  limit: 50,
-  before_id: beforeId,  // Could typo: beforeID
-});
-```
+### 5. Add monitoring (optional)
 
-**After (generated client):**
-```tsx
-import { APIClient, type MessageListResult } from '@/_ws';
-
-const apiClient = useMemo(() =>
-  client ? new APIClient(client) : null,
-  [client]
-);
-
-// ✅ Full type safety with autocomplete
-const result: MessageListResult = await apiClient.aiChatGetMessages({
-  session_id: sessionId,  // ✓ Autocomplete
-  limit: 50,              // ✓ Type checking
-  before_id: beforeId,    // ✓ Typo protection
-});
-```
-
-### How It Works
-
-1. **Backend** - Define RPC handlers with Pydantic models:
-
-```python
-from pydantic import BaseModel
-from django_cfg.apps.integrations.centrifugo.decorators import websocket_rpc
-
-class GetMessagesParams(BaseModel):
-    session_id: str
-    limit: int = 50
-    before_id: str | None = None
-
-class MessageListResult(BaseModel):
-    messages: list[MessageData]
-    total: int
-    has_more: bool
-
-@websocket_rpc("ai_chat.get_messages")
-async def ai_chat_get_messages(conn, params: GetMessagesParams) -> MessageListResult:
-    # Implementation
-    return MessageListResult(...)
-```
-
-2. **Generate** - Run generation command:
-
-```bash
-python manage.py generate_centrifuge_web
-# Discovers all @websocket_rpc handlers
-# Converts Pydantic models to TypeScript
-# Generates type-safe APIClient
-```
-
-3. **Frontend** - Use generated client:
-
-```tsx
-const apiClient = new APIClient(client);
-const result = await apiClient.aiChatGetMessages({
-  session_id: "uuid",
-  limit: 50,
-});
-// TypeScript knows result is MessageListResult!
-```
-
-### Benefits
-
-- ✅ **Type Safety** - Compile-time errors for invalid parameters
-- ✅ **Autocomplete** - IDE suggests available methods and parameters
-- ✅ **Sync with Backend** - Regenerate when backend changes
-- ✅ **No Manual Updates** - Types automatically match Pydantic models
-- ✅ **Documentation** - Docstrings from backend appear in IDE
-
-### Available Methods
-
-All `@websocket_rpc` handlers are auto-generated:
-
-```tsx
-// Terminal RPC
-await apiClient.terminalInput({ session_id, data });
-await apiClient.terminalResize({ session_id, cols, rows });
-await apiClient.terminalClose({ session_id });
-
-// AI Chat RPC
-await apiClient.aiChatCreateSession({ workspace_id, title });
-await apiClient.aiChatSendMessage({ session_id, message, stream });
-await apiClient.aiChatGetMessages({ session_id, limit, before_id });
-```
-
-> **Tip:** Run `python manage.py generate_centrifugo_clients --typescript` after adding new RPC handlers to update types.
-
-## 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
-- `dot` - Minimal dot indicator with popover on click (ideal for toolbars)
-
-```tsx
-import { ConnectionStatus } from '@djangocfg/centrifugo';
-
-// Badge variant
-<ConnectionStatus variant="badge" />
-
-// Dot variant - minimal indicator with popover (best for headers/toolbars)
-<ConnectionStatus variant="dot" dotSize="md" />
-
-// 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 (
-    <>
-      <button onClick={() => setOpen(true)}>Open Monitor</button>
-      <CentrifugoMonitorDialog 
-        open={open} 
-        onOpenChange={setOpen}
-        defaultTab="status"
-      />
-    </>
-  );
-}
-```
-
-**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** - 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: 'client', // 'client' | 'provider' | 'subscription' | 'system'
-  tag: 'MyComponent',
-  isDevelopment: true,
-});
-
-logger.debug('Debug message', { extra: 'data' });
-logger.info('Info message');
-logger.success('Success message');
-logger.warning('Warning message');
-logger.error('Error message', error);
-```
-
-**Accessing Logs:**
-
-```typescript
-import { getGlobalLogsStore } from '@djangocfg/centrifugo';
-
-const logsStore = getGlobalLogsStore();
-
-// Get all logs
-const logs = logsStore.getAll();
-
-// Subscribe to changes
-const unsubscribe = logsStore.subscribe((logs) => {
-  console.log('Logs updated:', logs);
-});
-
-// Clear 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)
-
-```typescript
-import { CentrifugoRPCClient, createLogger } from '@djangocfg/centrifugo';
-
-const logger = createLogger('MyApp');
-
-// Recommended: Options-based constructor
-const client = new CentrifugoRPCClient({
-  url: 'ws://localhost:8000/ws',
-  token: 'your-token',
-  userId: 'user-id',
-  timeout: 30000,
-  logger,
-  // Auto-refresh token on expiration
-  getToken: async () => {
-    const response = await fetch('/api/auth/refresh-token');
-    const { token } = await response.json();
-    return token;
-  },
-});
-
-await client.connect();
-
-// Check API version after connect
-import { API_VERSION } from '@/_ws';
-await client.checkApiVersion(API_VERSION);
-
-// 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 Dashboard Integration
-
-```tsx
-import {
-  ConnectionStatusCard,
-  MessagesFeed,
-  SubscriptionsList,
-} from '@djangocfg/centrifugo';
-
-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 className="container mx-auto p-6">
-      <h1>WebSocket Monitoring</h1>
-      <CentrifugoMonitor defaultTab="messages" />
-    </div>
-  );
-}
-```
-
-## TypeScript Support
-
-The package is fully typed with comprehensive TypeScript definitions:
-
-```typescript
-import type {
-  // Client Options
-  CentrifugoClientOptions,
-  RPCOptions,
-  RetryOptions,
-  VersionCheckResult,
-  NamedRPCWithRetryOptions,
-
-  // Errors
-  RPCErrorCode,
-  RetryConfig,
-  RetryState,
-
-  // Connection
-  ConnectionState,
-  CentrifugoToken,
-  User,
-
-  // Logs
-  LogLevel,
-  LogEntry,
-
-  // Subscriptions
-  ActiveSubscription,
-
-  // Client
-  CentrifugoClientConfig,
-  CentrifugoClientState,
-
-  // Provider
-  CentrifugoProviderProps,
-  CentrifugoContextValue,
-
-  // Hooks
-  UseSubscriptionOptions,
-  UseSubscriptionResult,
-  UsePageVisibilityOptions,
-  UsePageVisibilityResult,
-  PageVisibilityState,
-
-  // Components
-  ConnectionStatusProps,
-  MessagesFeedProps,
-  SubscriptionsListProps,
-  CentrifugoMonitorProps,
-} from '@djangocfg/centrifugo';
-
-// Error classes
-import { RPCError, withRetry, createRetryHandler } from '@djangocfg/centrifugo';
-```
-
-## Unified Event System
-
-All Centrifugo events use a single `'centrifugo'` CustomEvent with a type discriminator. This simplifies event handling and reduces the number of event listeners needed.
-
-**Event Types:**
-
-| Type | Description | Data |
-|------|-------------|------|
-| `error` | RPC call failed | `{ method, error, code, data }` |
-| `version_mismatch` | API version mismatch | `{ clientVersion, serverVersion, message }` |
-| `connected` | Successfully connected | `{ userId }` |
-| `disconnected` | Connection lost | `{ userId, reason }` |
-| `reconnecting` | Attempting to reconnect | `{ userId, attempt, reason }` |
-
-**Listening to Events:**
-
-```tsx
-// Listen to all Centrifugo events
-window.addEventListener('centrifugo', (e: CustomEvent) => {
-  const { type, data, timestamp } = e.detail;
-
-  switch (type) {
-    case 'error':
-      console.error('RPC error:', data.method, data.error);
-      break;
-    case 'version_mismatch':
-      toast.warning('Please refresh the page');
-      break;
-    case 'connected':
-      console.log('Connected as', data.userId);
-      break;
-    case 'disconnected':
-      console.log('Disconnected:', data.reason);
-      break;
-    case 'reconnecting':
-      console.log('Reconnecting, attempt', data.attempt);
-      break;
-  }
-});
-```
-
-**Dispatching Events (for custom integrations):**
-
-```tsx
-import {
-  dispatchCentrifugoError,
-  dispatchVersionMismatch,
-  dispatchConnected,
-  dispatchDisconnected,
-  dispatchReconnecting,
-} from '@djangocfg/centrifugo';
-
-// Dispatch error
-dispatchCentrifugoError({
-  method: 'terminal.input',
-  error: 'Connection timeout',
-  code: 408,
-});
-
-// Dispatch version mismatch
-dispatchVersionMismatch({
-  clientVersion: 'abc123',
-  serverVersion: 'def456',
-  message: 'API version mismatch',
-});
-```
-
-**Integration with ErrorsTracker:**
-
-The `@djangocfg/layouts` package's `ErrorTrackingProvider` automatically listens to `'centrifugo'` events with `type: 'error'` and displays toast notifications.
-
-```tsx
-import { ErrorTrackingProvider } from '@djangocfg/layouts';
-
-<ErrorTrackingProvider centrifugo={{ enabled: true, showToast: true }}>
-  <App />
-</ErrorTrackingProvider>
-```
-
-**Proper Centrifuge Types:**
-
-The package now uses proper types from the `centrifuge` library:
-
-```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 { DebugPanel } from '@djangocfg/centrifugo';
-
-// Auto-shown in development
-<CentrifugoProvider>
-  <App />
-</CentrifugoProvider>
-```
-
-**After:**
 ```tsx
 import { CentrifugoMonitorFAB } from '@djangocfg/centrifugo';
 
-// Manual control
-<CentrifugoProvider>
-  <App />
-  <CentrifugoMonitorFAB variant="full" />
-</CentrifugoProvider>
+// Show only for admins or in dev
+{shouldShowMonitor && <CentrifugoMonitorFAB variant="full" />}
 ```
 
-### From date-fns to moment
-
-**Before:**
-```typescript
-import { format } from 'date-fns';
+## Documentation
 
-const formatted = format(new Date(), 'yyyy-MM-dd HH:mm:ss');
-```
+| Document | Description |
+|----------|-------------|
+| [@docs/overview.md](@docs/overview.md) | Features, architecture, how it connects |
+| [@docs/api-reference.md](@docs/api-reference.md) | Providers, hooks, core client, TypeScript types |
+| [@docs/rpc.md](@docs/rpc.md) | useNamedRPC, useRPC, namedRPCNoWait, RPCError, retry |
+| [@docs/components.md](@docs/components.md) | ConnectionStatus, MessagesFeed, Monitor, dashboard examples |
+| [@docs/codegen.md](@docs/codegen.md) | Auto-generated type-safe clients from @websocket_rpc |
+| [@docs/events.md](@docs/events.md) | Unified event system, ErrorsTracker integration |
+| [@docs/logging.md](@docs/logging.md) | Logger, LogsProvider, in-memory store |
+| [@docs/migration.md](@docs/migration.md) | Migration from DebugPanel, date-fns to moment |
 
-**After:**
-```typescript
-import moment from 'moment';
+## Requirements
 
-const formatted = moment.utc().format('YYYY-MM-DD HH:mm:ss');
-```
+- React 18+
+- `@djangocfg/ui-nextjs` — UI components (shadcn/ui)
+- `@djangocfg/layouts` — layout components
+- `centrifuge` — WebSocket client library
+- `moment` — date manipulation
+- `consola` — console logging
 
 ## Development
 
 ```bash
-# Install dependencies
-pnpm install
-
-# Build the package
-pnpm build
-
-# Type check
-pnpm check
-
-# Run in development mode
-pnpm dev
+pnpm install    # Install dependencies
+pnpm build      # Build
+pnpm check      # Type check
+pnpm dev        # Watch mode
 ```
 
-## Requirements
-
-- React 18+
-- `@djangocfg/ui-nextjs` - UI components (shadcn/ui based)
-- `@djangocfg/layouts` - Layout components
-- `centrifuge` - WebSocket client library
-- `moment` - Date manipulation library
-- `consola` - Beautiful console logging
-
-## Documentation
-
-Full documentation available at [djangocfg.com](https://djangocfg.com)
-
-## Contributing
-
-Issues and pull requests are welcome at [GitHub](https://github.com/markolofsen/django-cfg)
-
 ## License
 
-MIT - see [LICENSE](./LICENSE) for details
+MIT