@djangocfg/centrifugo 1.0.1 → 1.0.3

package/README.md

@@ -1,6 +1,36 @@
 # @djangocfg/centrifugo
 
-WebSocket client package for Django-CFG + Centrifugo integration.
+Professional Centrifugo WebSocket client with React integration and comprehensive debugging 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
+- ⚛️ **React Integration** - Context providers and hooks for seamless integration
+- 🎯 **Type-Safe** - Full TypeScript support with comprehensive type definitions
+- 🏗️ **Platform-Agnostic Core** - Core modules can be used without React
+- 🎨 **Beautiful UI Components** - Pre-built components using shadcn/ui
+
+## 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
+│   └── 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
+```
 
 ## Installation
 
@@ -8,77 +38,358 @@ WebSocket client package for Django-CFG + Centrifugo integration.
 pnpm add @djangocfg/centrifugo
 ```
 
-## Usage
+## Quick Start
 
 ### 1. Wrap your app with CentrifugoProvider
 
 ```tsx
-import { CentrifugoProvider } from '@djangocfg/centrifugo';
+import { CentrifugoProvider, DebugPanel } from '@djangocfg/centrifugo';
 
 function App() {
   return (
-    <CentrifugoProvider auth={authContext} config={centrifugoConfig}>
+    <CentrifugoProvider
+      enabled={true}
+      autoConnect={true}
+    >
       <YourApp />
+
+      {/* Debug panel (only shows in development) */}
+      <DebugPanel />
     </CentrifugoProvider>
   );
 }
 ```
 
-### 2. Use hooks to interact with Centrifugo
+### 2. Use the connection in your components
 
 ```tsx
-import { useCentrifugo, useSubscription } from '@djangocfg/centrifugo';
+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>
+  );
+}
+```
+
+### 3. Subscribe to channels
 
-function MyComponent() {
-  const { isConnected, baseClient } = useCentrifugo();
+```tsx
+import { useSubscription } from '@djangocfg/centrifugo';
 
-  const { data, isLoading, error } = useSubscription({
+function NotificationsComponent() {
+  const { data, isSubscribed } = useSubscription({
     channel: 'notifications',
-    onPublication: (data) => console.log('New message:', data),
+    enabled: true,
+    onPublication: (data) => {
+      console.log('New notification:', data);
+    },
+    onError: (error) => {
+      console.error('Subscription error:', error);
+    },
   });
 
-  return <div>Connected: {isConnected ? 'Yes' : 'No'}</div>;
+  return (
+    <div>
+      <p>Subscribed: {isSubscribed ? 'Yes' : 'No'}</p>
+      {data && <pre>{JSON.stringify(data, null, 2)}</pre>}
+    </div>
+  );
 }
 ```
 
-### 3. Debug connection (development only)
+## 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
-import { CentrifugoDebug } from '@djangocfg/centrifugo/components';
+const {
+  client,
+  isConnected,
+  connectionState,
+  connect,
+  disconnect,
+  reconnect,
+} = useCentrifugo();
+```
+
+### useSubscription()
+
+Hook to subscribe to a channel with auto-cleanup.
 
-function DevTools() {
-  return <CentrifugoDebug auth={authContext} config={centrifugoConfig} />;
+```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;
 }
 ```
 
-## Exports
+### LogsProvider
 
-### Context & Provider
-- `CentrifugoProvider` - WebSocket connection provider
-- `useCentrifugo` - Access connection state and client
+Provider for accessing accumulated logs.
 
-### Hooks
-- `useCentrifugoLogger` - Consola logger for debugging
-- `useSubscription` - Subscribe to Centrifugo channels
+```tsx
+const {
+  logs,          // All logs
+  filteredLogs,  // Filtered logs
+  count,         // Total count
+  filter,        // Current filter
+  setFilter,     // Update filter
+  clearLogs,     // Clear all logs
+} = useLogs();
+```
 
-### Components
-- `CentrifugoDebug` - Development debug panel
+## Debug Panel
 
-### Types
-- `CentrifugoConfig` - Configuration interface
-- `CentrifugoToken` - JWT token structure
-- `User` - User type with Centrifugo data
-- `AuthContext` - Authentication context interface
-- `CentrifugoProviderProps` - Provider props
-- `CentrifugoContextValue` - Context value type
+The debug panel is a development-only UI that provides:
 
-## Architecture
+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
+
+**Usage:**
+```tsx
+import { DebugPanel } from '@djangocfg/centrifugo';
+
+function App() {
+  return (
+    <>
+      <YourApp />
+      <DebugPanel />
+    </>
+  );
+}
+```
+
+The panel only renders in development mode (`NODE_ENV === 'development'`). It appears as a floating action button (FAB) in the bottom-left corner.
+
+## Logging System
+
+The package includes a sophisticated logging system with:
 
-This package provides universal WebSocket logic that can be used across multiple Django-CFG admin applications. The generated RPC client is imported separately from your app's generated code.
+- **Circular Buffer** - Stores up to 500 logs (configurable)
+- **Dual Output** - Console (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
+
+**Creating a Logger:**
+```typescript
+import { createLogger } from '@djangocfg/centrifugo';
+
+const logger = createLogger({
+  source: 'my-module', // or 'client' | 'provider' | 'subscription' | 'system'
+});
+
+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();
+```
+
+## Advanced Usage
+
+### Using the Core Client (without React)
+
+```typescript
+import { CentrifugoRPCClient, createLogger } from '@djangocfg/centrifugo';
+
+const logger = createLogger({ source: 'client' });
+const client = new CentrifugoRPCClient(
+  'ws://localhost:8000/ws',
+  'your-token',
+  'user-id',
+  30000, // timeout
+  logger
+);
+
+await client.connect();
+await client.subscribe('channel-name');
+```
+
+### Custom Log Filters
+
+```tsx
+import { useLogs } from '@djangocfg/centrifugo';
+
+function CustomLogsView() {
+  const { logs, setFilter } = 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={() => setFilter({})}>
+        Clear Filters
+      </button>
+    </div>
+  );
+}
+```
+
+## TypeScript Support
+
+The package is fully typed with comprehensive TypeScript definitions:
+
+```typescript
+import type {
+  // Connection
+  ConnectionState,
+  CentrifugoToken,
+  User,
+
+  // Logs
+  LogLevel,
+  LogEntry,
+
+  // Subscriptions
+  ActiveSubscription,
+
+  // Client
+  CentrifugoClientConfig,
+  CentrifugoClientState,
+
+  // Provider
+  CentrifugoProviderProps,
+  CentrifugoContextValue,
+
+  // Hooks
+  UseSubscriptionOptions,
+  UseSubscriptionResult,
+} from '@djangocfg/centrifugo';
+```
+
+## Migration from Old Version
+
+If you're migrating from `src_old`, the main changes are:
+
+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
+
+**Before:**
+```tsx
+import { WSRPCContext } from './rpc/WSRPCContext';
+```
+
+**After:**
+```tsx
+import { CentrifugoProvider, useCentrifugo } from '@djangocfg/centrifugo';
+```
+
+## Development
+
+```bash
+# Build the package
+pnpm build
+
+# Type check
+pnpm exec tsc --noEmit
+
+# Run in development mode
+pnpm dev
+```
 
 ## Requirements
 
-- React 19+
+- React 18+
 - `@djangocfg/ui` - UI components
 - `@djangocfg/layouts` - Layout components
 - `centrifuge` - WebSocket client library
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/centrifugo",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "WebSocket RPC client for Django-CFG + Centrifugo integration",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -19,17 +19,19 @@
     "centrifuge": "^5.2.2"
   },
   "peerDependencies": {
-    "@djangocfg/ui": "^1.2.26",
-    "@djangocfg/layouts": "^1.2.26",
+    "@djangocfg/ui": "^1.2.28",
+    "@djangocfg/layouts": "^1.2.28",
     "consola": "^3.4.2",
     "lucide-react": "^0.468.0",
+    "moment": "^2.30.1",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@djangocfg/typescript-config": "^1.2.26",
+    "@djangocfg/typescript-config": "^1.2.28",
     "@types/react": "^19.0.6",
     "@types/react-dom": "^19.0.2",
+    "moment": "^2.30.1",
     "typescript": "^5.7.3"
   }
 }

package/src/config.ts

@@ -4,7 +4,7 @@
 
 export const isDevelopment = process.env.NODE_ENV === 'development';
 export const isProduction = !isDevelopment;
-export const isStaticBuild = process.env.NEXT_PUBLIC_STATIC_BUILD === 'true';
+export const isStaticBuild = process.env.NEXT_PHASE === 'phase-production-build';
 
 const showDebugPanel = isDevelopment && !isStaticBuild;