@djangocfg/centrifugo 2.1.53 → 2.1.55

package/README.md

@@ -30,10 +30,18 @@ Professional Centrifugo WebSocket client with React integration, composable UI c
 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, namedRPCNoWait)
+│   │   ├── version.ts              # API version checking
+│   │   ├── types.ts                # Type definitions
+│   │   └── index.ts                # Exports
 │   ├── 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
@@ -443,6 +451,112 @@ interface UseNamedRPCResult {
 
 > **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.
 
+### 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', {
+      session_id: 'abc-123',
+      data: btoa(key)
+    });
+  };
+
+  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 |
+
+### 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.
@@ -807,16 +921,28 @@ function CustomLogsView() {
 import { CentrifugoRPCClient, createLogger } from '@djangocfg/centrifugo';
 
 const logger = createLogger('MyApp');
-const client = new CentrifugoRPCClient(
-  'ws://localhost:8000/ws',
-  'your-token',
-  'user-id',
-  30000, // timeout
-  (entry) => logger.info(entry.message, entry.data)
-);
+
+// 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);
@@ -877,6 +1003,12 @@ The package is fully typed with comprehensive TypeScript definitions:
 
 ```typescript
 import type {
+  // Client Options
+  CentrifugoClientOptions,
+  RPCOptions,
+  RetryOptions,
+  VersionCheckResult,
+
   // Connection
   ConnectionState,
   CentrifugoToken,
@@ -909,6 +1041,85 @@ import type {
 } 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:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/centrifugo",
-  "version": "2.1.53",
+  "version": "2.1.55",
   "description": "Production-ready Centrifugo WebSocket client for React with real-time subscriptions, RPC patterns, and connection state management",
   "keywords": [
     "centrifugo",
@@ -51,9 +51,9 @@
     "centrifuge": "^5.2.2"
   },
   "peerDependencies": {
-    "@djangocfg/api": "^2.1.53",
-    "@djangocfg/ui-nextjs": "^2.1.53",
-    "@djangocfg/layouts": "^2.1.53",
+    "@djangocfg/api": "^2.1.55",
+    "@djangocfg/ui-nextjs": "^2.1.55",
+    "@djangocfg/layouts": "^2.1.55",
     "consola": "^3.4.2",
     "lucide-react": "^0.545.0",
     "moment": "^2.30.1",
@@ -61,7 +61,7 @@
     "react-dom": "^19.1.0"
   },
   "devDependencies": {
-    "@djangocfg/typescript-config": "^2.1.53",
+    "@djangocfg/typescript-config": "^2.1.55",
     "@types/react": "^19.1.0",
     "@types/react-dom": "^19.1.0",
     "moment": "^2.30.1",