@djangocfg/centrifugo 2.1.26 → 2.1.28

package/README.md

@@ -441,7 +441,141 @@ 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/features/integrations/centrifugo/setup) for configuration details.
+> **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.
+
+## 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
+});
+```
+
+**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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/centrifugo",
-  "version": "2.1.26",
+  "version": "2.1.28",
   "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.26",
-    "@djangocfg/ui-nextjs": "^2.1.26",
-    "@djangocfg/layouts": "^2.1.26",
+    "@djangocfg/api": "^2.1.28",
+    "@djangocfg/ui-nextjs": "^2.1.28",
+    "@djangocfg/layouts": "^2.1.28",
     "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.26",
+    "@djangocfg/typescript-config": "^2.1.28",
     "@types/react": "^19.1.0",
     "@types/react-dom": "^19.1.0",
     "moment": "^2.30.1",

package/src/components/ConnectionStatus/ConnectionStatus.tsx

@@ -12,9 +12,9 @@ import { Badge } from '@djangocfg/ui-nextjs';
 import { Wifi, WifiOff, Radio, Clock } from 'lucide-react';
 import moment from 'moment';
 import { useCentrifugo } from '../../providers/CentrifugoProvider';
-import { createLogger } from '../../core/logger/createLogger';
+import { getConsolaLogger } from '../../core/logger/consolaLogger';
 
-const logger = createLogger('ConnectionStatus');
+const logger = getConsolaLogger('ConnectionStatus');
 
 // ─────────────────────────────────────────────────────────────────────────
 // Types

package/src/components/SubscriptionsList/SubscriptionsList.tsx

@@ -19,9 +19,9 @@ import {
 import { Radio, RefreshCw, Trash2 } from 'lucide-react';
 import { Subscription, SubscriptionState } from 'centrifuge';
 import { useCentrifugo } from '../../providers/CentrifugoProvider';
-import { createLogger } from '../../core/logger/createLogger';
+import { getConsolaLogger } from '../../core/logger/consolaLogger';
 
-const logger = createLogger('SubscriptionsList');
+const logger = getConsolaLogger('SubscriptionsList');
 
 // ─────────────────────────────────────────────────────────────────────────
 // Types

package/src/core/client/CentrifugoRPCClient.ts

@@ -7,7 +7,20 @@
 
 import { Centrifuge } from 'centrifuge';
 import type { Logger } from '../logger';
-import { createLogger } from '../logger';
+import { getConsolaLogger } from '../logger/consolaLogger';
+
+export interface CentrifugoClientOptions {
+  url: string;
+  token: string;
+  userId: string;
+  timeout?: number;
+  logger?: Logger;
+  /**
+   * Callback to get fresh token when current token expires.
+   * Centrifuge-js calls this automatically on token expiration.
+   */
+  getToken?: () => Promise<string>;
+}
 
 export class CentrifugoRPCClient {
   private centrifuge: Centrifuge;
@@ -19,21 +32,73 @@ export class CentrifugoRPCClient {
   private readonly timeout: number;
   private readonly logger: Logger;
 
+  constructor(options: CentrifugoClientOptions);
+  /** @deprecated Use options object instead */
   constructor(
     url: string,
     token: string,
     userId: string,
+    timeout?: number,
+    logger?: Logger
+  );
+  constructor(
+    urlOrOptions: string | CentrifugoClientOptions,
+    token?: string,
+    userId?: string,
     timeout: number = 30000,
     logger?: Logger
   ) {
-    this.userId = userId;
-    this.replyChannel = `user#${userId}`;
-    this.timeout = timeout;
-    this.logger = logger || createLogger({ source: 'client' });
+    // Handle both old and new API
+    let url: string;
+    let actualToken: string;
+    let actualUserId: string;
+    let actualTimeout: number;
+    let actualLogger: Logger | undefined;
+    let getToken: (() => Promise<string>) | undefined;
+
+    if (typeof urlOrOptions === 'object') {
+      // New options-based API
+      url = urlOrOptions.url;
+      actualToken = urlOrOptions.token;
+      actualUserId = urlOrOptions.userId;
+      actualTimeout = urlOrOptions.timeout ?? 30000;
+      actualLogger = urlOrOptions.logger;
+      getToken = urlOrOptions.getToken;
+    } else {
+      // Legacy positional arguments API
+      url = urlOrOptions;
+      actualToken = token!;
+      actualUserId = userId!;
+      actualTimeout = timeout;
+      actualLogger = logger;
+    }
 
-    this.centrifuge = new Centrifuge(url, {
-      token,
-    });
+    this.userId = actualUserId;
+    this.replyChannel = `user#${actualUserId}`;
+    this.timeout = actualTimeout;
+    this.logger = actualLogger || getConsolaLogger('client');
+
+    // Build Centrifuge options
+    const centrifugeOptions: any = {
+      token: actualToken,
+    };
+
+    // Add getToken callback for automatic token refresh
+    if (getToken) {
+      centrifugeOptions.getToken = async () => {
+        this.logger.info('Token expired, refreshing...');
+        try {
+          const newToken = await getToken();
+          this.logger.success('Token refreshed successfully');
+          return newToken;
+        } catch (error) {
+          this.logger.error('Failed to refresh token', error);
+          throw error;
+        }
+      };
+    }
+
+    this.centrifuge = new Centrifuge(url, centrifugeOptions);
 
     this.centrifuge.on('disconnected', (ctx) => {
       // Reject all pending requests

package/src/core/client/index.ts

@@ -3,3 +3,4 @@
  */
 
 export { CentrifugoRPCClient } from './CentrifugoRPCClient';
+export type { CentrifugoClientOptions } from './CentrifugoRPCClient';

package/src/core/logger/consolaLogger.ts

@@ -0,0 +1,37 @@
+/**
+ * Shared Consola Logger
+ *
+ * Single consola instance used across the package for development logging.
+ */
+
+import { createConsola } from 'consola';
+import type { Logger } from './createLogger';
+
+const isDevelopment = process.env.NODE_ENV === 'development';
+
+/**
+ * Shared consola logger for Centrifugo package
+ */
+export const consolaLogger = createConsola({
+  level: isDevelopment ? 4 : 3,
+  formatOptions: {
+    colors: true,
+    date: false,
+    compact: !isDevelopment,
+  },
+}).withTag('[Centrifugo]');
+
+/**
+ * Get a consola logger with custom tag wrapped to match Logger interface
+ */
+export function getConsolaLogger(tag: string): Logger {
+  const consola = consolaLogger.withTag(`[${tag}]`);
+
+  return {
+    debug: (message: string, data?: unknown) => consola.debug(message, data || ''),
+    info: (message: string, data?: unknown) => consola.info(message, data || ''),
+    success: (message: string, data?: unknown) => consola.success(message, data || ''),
+    warning: (message: string, data?: unknown) => consola.warn(message, data || ''),
+    error: (message: string, error?: Error | unknown) => consola.error(message, error || ''),
+  };
+}

package/src/core/utils/devTips.ts

@@ -0,0 +1,74 @@
+/**
+ * Development Tips
+ *
+ * Shows helpful development tips once per session.
+ * Used across the package to educate developers about features.
+ */
+
+import { getConsolaLogger } from '../logger/consolaLogger';
+
+const logger = getConsolaLogger('DevTips');
+const shownTips = new Set<string>();
+
+/**
+ * Show a development tip once per session
+ *
+ * @param id - Unique identifier for the tip
+ * @param message - Tip message
+ * @param details - Optional details (shown as second parameter)
+ *
+ * @example
+ * showDevTip('codegen', 'Generate type-safe clients:', 'python manage.py ...');
+ */
+export function showDevTip(id: string, message: string, details?: string): void {
+  if (process.env.NODE_ENV !== 'development') return;
+  if (shownTips.has(id)) return;
+
+  shownTips.add(id);
+  logger.info(message, details);
+}
+
+/**
+ * Predefined tips
+ */
+export const DevTips = {
+  /**
+   * Show tip about generating type-safe clients
+   */
+  codegenClients: () => {
+    showDevTip(
+      'codegen-clients',
+      '💡 Generate type-safe clients from @websocket_rpc handlers:',
+      '\n\npython manage.py generate_centrifugo_clients --typescript\n\nLearn more: https://djangocfg.com/centrifugo/codegen'
+    );
+  },
+
+  /**
+   * Show tip about using generated client instead of manual RPC
+   */
+  useGeneratedClient: () => {
+    showDevTip(
+      'use-generated-client',
+      '💡 Consider using auto-generated APIClient for type safety:',
+      '\n\nimport { APIClient } from \'@/_ws\';\nconst apiClient = new APIClient(client);\nawait apiClient.aiChatGetMessages({ ... });\n\nGenerate: python manage.py generate_centrifugo_clients --typescript'
+    );
+  },
+
+  /**
+   * Show tip about RPC proxy configuration
+   */
+  rpcProxyConfig: () => {
+    showDevTip(
+      'rpc-proxy-config',
+      '💡 Using namedRPC requires Centrifugo RPC proxy configuration:',
+      '\n\nSee: https://djangocfg.com/features/integrations/centrifugo/setup'
+    );
+  },
+};
+
+/**
+ * Reset shown tips (useful for testing)
+ */
+export function resetDevTips(): void {
+  shownTips.clear();
+}

package/src/hooks/useCodegenTip.ts

@@ -0,0 +1,39 @@
+/**
+ * useCodegenTip Hook
+ *
+ * Shows development tip about client generation once per session.
+ */
+
+import { useEffect, useRef } from 'react';
+import { consolaLogger } from '../core/logger/consolaLogger';
+
+const isDevelopment = process.env.NODE_ENV === 'development';
+let tipShown = false; // Global flag to show tip once across all components
+
+/**
+ * Show dev tip about generating type-safe clients from @websocket_rpc handlers
+ *
+ * @example
+ * function MyComponent() {
+ *   useCodegenTip();
+ *   // ... rest of component
+ * }
+ */
+export function useCodegenTip() {
+  const mountedRef = useRef(false);
+
+  useEffect(() => {
+    if (!isDevelopment) return;
+    if (tipShown) return;
+    if (mountedRef.current) return;
+
+    mountedRef.current = true;
+    tipShown = true;
+
+    consolaLogger.info(
+      '💡 Generate type-safe clients from @websocket_rpc handlers:\n\n' +
+      'python manage.py generate_centrifugo_clients --typescript\n\n' +
+      'Learn more: https://djangocfg.com/docs/features/integrations/centrifugo/client-generation/'
+    );
+  }, []);
+}

package/src/hooks/useNamedRPC.ts

@@ -27,7 +27,7 @@
 
 import { useState, useCallback, useRef } from 'react';
 import { useCentrifugo } from '../providers/CentrifugoProvider';
-import { createLogger } from '../core/logger';
+import { getConsolaLogger } from '../core/logger/consolaLogger';
 
 export interface UseNamedRPCOptions {
   onError?: (error: Error) => void;
@@ -50,7 +50,7 @@ export function useNamedRPC(
   const [isLoading, setIsLoading] = useState(false);
   const [error, setError] = useState<Error | null>(null);
 
-  const logger = useRef(createLogger('useNamedRPC')).current;
+  const logger = useRef(getConsolaLogger('useNamedRPC')).current;
 
   const reset = useCallback(() => {
     setIsLoading(false);

package/src/hooks/useRPC.ts

@@ -22,7 +22,7 @@
 
 import { useState, useCallback, useRef } from 'react';
 import { useCentrifugo } from '../providers/CentrifugoProvider';
-import { createLogger } from '../core/logger';
+import { getConsolaLogger } from '../core/logger/consolaLogger';
 
 export interface UseRPCOptions {
   timeout?: number;
@@ -45,8 +45,8 @@ export function useRPC(defaultOptions: UseRPCOptions = {}): UseRPCResult {
   const { client, isConnected } = useCentrifugo();
   const [isLoading, setIsLoading] = useState(false);
   const [error, setError] = useState<Error | null>(null);
-  
-  const logger = useRef(createLogger('useRPC')).current;
+
+  const logger = useRef(getConsolaLogger('useRPC')).current;
   const abortControllerRef = useRef<AbortController | null>(null);
 
   const reset = useCallback(() => {

package/src/hooks/useSubscription.ts

@@ -14,7 +14,7 @@
 
 import { useEffect, useCallback, useRef, useState } from 'react';
 import { useCentrifugo } from '../providers/CentrifugoProvider';
-import { createLogger } from '../core/logger';
+import { getConsolaLogger } from '../core/logger/consolaLogger';
 import { logChannelWarnings } from '../core/utils/channelValidator';
 
 export interface UseSubscriptionOptions<T = any> {
@@ -42,7 +42,7 @@ export function useSubscription<T = any>(
   const [isSubscribed, setIsSubscribed] = useState(false);
 
   const unsubscribeRef = useRef<(() => void) | null>(null);
-  const logger = useRef(createLogger('useSubscription')).current;
+  const logger = useRef(getConsolaLogger('useSubscription')).current;
   
   // Store callbacks in refs to avoid re-subscriptions when they change
   const onPublicationRef = useRef(onPublication);

package/src/index.ts

@@ -53,6 +53,7 @@ export type { Subscription } from 'centrifuge';
 
 export { CentrifugoRPCClient } from './core/client/CentrifugoRPCClient';
 export { createLogger, getGlobalLogsStore } from './core/logger';
+export { consolaLogger, getConsolaLogger } from './core/logger/consolaLogger';
 export type {
   // Connection
   ConnectionState,
@@ -92,6 +93,8 @@ export type {
   UseSubscriptionResult,
 } from './hooks/useSubscription';
 
+export { useCodegenTip } from './hooks/useCodegenTip';
+
 // ─────────────────────────────────────────────────────────────────────────
 // Configuration
 // ─────────────────────────────────────────────────────────────────────────

package/src/providers/CentrifugoProvider/CentrifugoProvider.tsx

@@ -10,11 +10,12 @@
 import { createContext, useContext, useState, useEffect, useCallback, useRef, useMemo, type ReactNode } from 'react';
 import { useAuth } from '@djangocfg/api/auth';
 import { CentrifugoRPCClient } from '../../core/client';
-import { createLogger } from '../../core/logger';
+import { getConsolaLogger } from '../../core/logger/consolaLogger';
 import type { ConnectionState, CentrifugoToken, ActiveSubscription } from '../../core/types';
 import { LogsProvider } from '../LogsProvider';
 import { isStaticBuild, isDevelopment, reconnectConfig } from '../../config';
 import { CentrifugoMonitorDialog } from '../../components/CentrifugoMonitor/CentrifugoMonitorDialog';
+import { useCodegenTip } from '../../hooks/useCodegenTip';
 
 // ─────────────────────────────────────────────────────────────────────────
 // Context
@@ -56,6 +57,18 @@ export interface CentrifugoProviderProps {
   enabled?: boolean;
   url?: string;
   autoConnect?: boolean;
+  /**
+   * Callback to refresh the Centrifugo token when it expires.
+   * If provided, centrifuge-js will automatically call this when token expires.
+   * Should return a fresh JWT token string.
+   *
+   * @example
+   * onTokenRefresh={async () => {
+   *   const response = await getCentrifugoAuthTokenRetrieve();
+   *   return response.token;
+   * }}
+   */
+  onTokenRefresh?: () => Promise<string>;
 }
 
 // ─────────────────────────────────────────────────────────────────────────
@@ -67,6 +80,7 @@ function CentrifugoProviderInner({
   enabled = false,
   url,
   autoConnect: autoConnectProp = true,
+  onTokenRefresh,
 }: CentrifugoProviderProps) {
   const { isAuthenticated, isLoading, user } = useAuth();
 
@@ -79,15 +93,18 @@ function CentrifugoProviderInner({
   const [subscriptions, setSubscriptions] = useState<string[]>([]);
   const [activeSubscriptions, setActiveSubscriptions] = useState<ActiveSubscription[]>([]);
 
-  const logger = useMemo(() => createLogger({ source: 'provider' }), []);
+  const logger = useMemo(() => getConsolaLogger('provider'), []);
+
+  // Show dev tip about client generation
+  useCodegenTip();
 
   const reconnectTimeoutRef = useRef<NodeJS.Timeout | null>(null);
   const hasConnectedRef = useRef(false);
   const isConnectingRef = useRef(false);
   const isMountedRef = useRef(true);
   const reconnectAttemptRef = useRef(0);
-  const devWarningShownRef = useRef(false);
   const reconnectStoppedRef = useRef(false); // Track if we should stop reconnecting
+  const devWarningShownRef = useRef(false); // Track if server unavailable warning was shown
   const connectRef = useRef<(() => Promise<void>) | null>(null);
   const disconnectRef = useRef<(() => void) | null>(null);
 
@@ -215,7 +232,14 @@ function CentrifugoProviderInner({
         }
       }
 
-      const rpcClient = new CentrifugoRPCClient(wsUrl, token, userId, 30000, logger);
+      const rpcClient = new CentrifugoRPCClient({
+        url: wsUrl,
+        token,
+        userId,
+        timeout: 30000,
+        logger,
+        getToken: onTokenRefresh,
+      });
       await rpcClient.connect();
 
       if (!isMountedRef.current) {
@@ -304,7 +328,7 @@ function CentrifugoProviderInner({
     } finally {
       setIsConnecting(false);
     }
-  }, [wsUrl, centrifugoToken, user, logger, isConnecting, isConnected, getReconnectDelay]);
+  }, [wsUrl, centrifugoToken, user, logger, isConnecting, isConnected, getReconnectDelay, onTokenRefresh]);
 
   // Disconnect function
   const disconnect = useCallback(() => {