@djangocfg/centrifugo 2.1.101 → 2.1.102

package/dist/hooks.d.mts

@@ -0,0 +1,128 @@
+/**
+ * useSubscription Hook
+ *
+ * Subscribe to Centrifugo channel with auto-cleanup.
+ *
+ * Best practices:
+ * - Callbacks are stored in refs to avoid re-subscriptions
+ * - Proper error handling in callbacks (as recommended by centrifuge-js)
+ * - Cleanup on unmount
+ * - Stable unsubscribe function
+ */
+interface UseSubscriptionOptions<T = any> {
+    channel: string;
+    enabled?: boolean;
+    onPublication?: (data: T) => void;
+    onError?: (error: Error) => void;
+}
+interface UseSubscriptionResult<T = any> {
+    data: T | null;
+    error: Error | null;
+    isSubscribed: boolean;
+    unsubscribe: () => void;
+}
+declare function useSubscription<T = any>(options: UseSubscriptionOptions<T>): UseSubscriptionResult<T>;
+
+/**
+ * useRPC Hook
+ *
+ * React hook for making RPC calls via Centrifugo using correlation ID pattern.
+ * Provides type-safe request-response communication over WebSocket.
+ *
+ * Pattern:
+ * 1. Client sends request with correlation_id to rpc#{method}
+ * 2. Backend processes and sends response to user#{userId} with same correlation_id
+ * 3. Client matches response by correlation_id and resolves Promise
+ *
+ * @example
+ * const { call, isLoading, error } = useRPC();
+ *
+ * const handleGetStats = async () => {
+ *   const result = await call('tasks.get_stats', { bot_id: '123' });
+ *   console.log('Stats:', result);
+ * };
+ */
+interface UseRPCOptions {
+    timeout?: number;
+    replyChannel?: string;
+    onError?: (error: Error) => void;
+}
+interface UseRPCResult {
+    call: <TRequest = any, TResponse = any>(method: string, params: TRequest, options?: UseRPCOptions) => Promise<TResponse>;
+    isLoading: boolean;
+    error: Error | null;
+    reset: () => void;
+}
+declare function useRPC(defaultOptions?: UseRPCOptions): UseRPCResult;
+
+/**
+ * useNamedRPC Hook
+ *
+ * React hook for making native Centrifugo RPC calls via RPC proxy.
+ * Uses Centrifugo's built-in RPC mechanism which proxies 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
+ *
+ * @example
+ * const { call, isLoading, error } = useNamedRPC();
+ *
+ * const handleSendInput = async () => {
+ *   const result = await call('terminal.input', {
+ *     session_id: 'abc-123',
+ *     data: btoa('ls -la')
+ *   });
+ *   console.log('Result:', result);
+ * };
+ */
+interface UseNamedRPCOptions {
+    onError?: (error: Error) => void;
+}
+interface UseNamedRPCResult {
+    call: <TRequest = any, TResponse = any>(method: string, data: TRequest) => Promise<TResponse>;
+    isLoading: boolean;
+    error: Error | null;
+    reset: () => void;
+}
+declare function useNamedRPC(defaultOptions?: UseNamedRPCOptions): UseNamedRPCResult;
+
+/**
+ * usePageVisibility Hook
+ *
+ * Tracks browser tab visibility state using the Page Visibility API.
+ * Returns true when the page is visible, false when hidden.
+ *
+ * Use cases:
+ * - Pause/resume WebSocket connections
+ * - Pause expensive operations when tab is inactive
+ * - Trigger data sync when tab becomes visible
+ */
+interface PageVisibilityState {
+    /** Whether the page is currently visible */
+    isVisible: boolean;
+    /** Whether the page was ever hidden during this session */
+    wasHidden: boolean;
+    /** Timestamp when page became visible (for uptime tracking) */
+    visibleSince: number | null;
+    /** How long the page was hidden (ms), reset when visible */
+    hiddenDuration: number;
+}
+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;
+}
+interface UsePageVisibilityResult extends PageVisibilityState {
+    /** Force check visibility state */
+    checkVisibility: () => boolean;
+}
+declare function usePageVisibility(options?: UsePageVisibilityOptions): UsePageVisibilityResult;
+
+export { type PageVisibilityState, type UseNamedRPCOptions, type UseNamedRPCResult, type UsePageVisibilityOptions, type UsePageVisibilityResult, type UseRPCOptions, type UseRPCResult, type UseSubscriptionOptions, type UseSubscriptionResult, useNamedRPC, usePageVisibility, useRPC, useSubscription };

package/dist/hooks.d.ts

@@ -0,0 +1,128 @@
+/**
+ * useSubscription Hook
+ *
+ * Subscribe to Centrifugo channel with auto-cleanup.
+ *
+ * Best practices:
+ * - Callbacks are stored in refs to avoid re-subscriptions
+ * - Proper error handling in callbacks (as recommended by centrifuge-js)
+ * - Cleanup on unmount
+ * - Stable unsubscribe function
+ */
+interface UseSubscriptionOptions<T = any> {
+    channel: string;
+    enabled?: boolean;
+    onPublication?: (data: T) => void;
+    onError?: (error: Error) => void;
+}
+interface UseSubscriptionResult<T = any> {
+    data: T | null;
+    error: Error | null;
+    isSubscribed: boolean;
+    unsubscribe: () => void;
+}
+declare function useSubscription<T = any>(options: UseSubscriptionOptions<T>): UseSubscriptionResult<T>;
+
+/**
+ * useRPC Hook
+ *
+ * React hook for making RPC calls via Centrifugo using correlation ID pattern.
+ * Provides type-safe request-response communication over WebSocket.
+ *
+ * Pattern:
+ * 1. Client sends request with correlation_id to rpc#{method}
+ * 2. Backend processes and sends response to user#{userId} with same correlation_id
+ * 3. Client matches response by correlation_id and resolves Promise
+ *
+ * @example
+ * const { call, isLoading, error } = useRPC();
+ *
+ * const handleGetStats = async () => {
+ *   const result = await call('tasks.get_stats', { bot_id: '123' });
+ *   console.log('Stats:', result);
+ * };
+ */
+interface UseRPCOptions {
+    timeout?: number;
+    replyChannel?: string;
+    onError?: (error: Error) => void;
+}
+interface UseRPCResult {
+    call: <TRequest = any, TResponse = any>(method: string, params: TRequest, options?: UseRPCOptions) => Promise<TResponse>;
+    isLoading: boolean;
+    error: Error | null;
+    reset: () => void;
+}
+declare function useRPC(defaultOptions?: UseRPCOptions): UseRPCResult;
+
+/**
+ * useNamedRPC Hook
+ *
+ * React hook for making native Centrifugo RPC calls via RPC proxy.
+ * Uses Centrifugo's built-in RPC mechanism which proxies 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
+ *
+ * @example
+ * const { call, isLoading, error } = useNamedRPC();
+ *
+ * const handleSendInput = async () => {
+ *   const result = await call('terminal.input', {
+ *     session_id: 'abc-123',
+ *     data: btoa('ls -la')
+ *   });
+ *   console.log('Result:', result);
+ * };
+ */
+interface UseNamedRPCOptions {
+    onError?: (error: Error) => void;
+}
+interface UseNamedRPCResult {
+    call: <TRequest = any, TResponse = any>(method: string, data: TRequest) => Promise<TResponse>;
+    isLoading: boolean;
+    error: Error | null;
+    reset: () => void;
+}
+declare function useNamedRPC(defaultOptions?: UseNamedRPCOptions): UseNamedRPCResult;
+
+/**
+ * usePageVisibility Hook
+ *
+ * Tracks browser tab visibility state using the Page Visibility API.
+ * Returns true when the page is visible, false when hidden.
+ *
+ * Use cases:
+ * - Pause/resume WebSocket connections
+ * - Pause expensive operations when tab is inactive
+ * - Trigger data sync when tab becomes visible
+ */
+interface PageVisibilityState {
+    /** Whether the page is currently visible */
+    isVisible: boolean;
+    /** Whether the page was ever hidden during this session */
+    wasHidden: boolean;
+    /** Timestamp when page became visible (for uptime tracking) */
+    visibleSince: number | null;
+    /** How long the page was hidden (ms), reset when visible */
+    hiddenDuration: number;
+}
+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;
+}
+interface UsePageVisibilityResult extends PageVisibilityState {
+    /** Force check visibility state */
+    checkVisibility: () => boolean;
+}
+declare function usePageVisibility(options?: UsePageVisibilityOptions): UsePageVisibilityResult;
+
+export { type PageVisibilityState, type UseNamedRPCOptions, type UseNamedRPCResult, type UsePageVisibilityOptions, type UsePageVisibilityResult, type UseRPCOptions, type UseRPCResult, type UseSubscriptionOptions, type UseSubscriptionResult, useNamedRPC, usePageVisibility, useRPC, useSubscription };

package/dist/hooks.mjs

@@ -0,0 +1,374 @@
+import { createContext, useState, useRef, useCallback, useEffect, useContext } from 'react';
+import { createConsola } from 'consola';
+import '@djangocfg/api/auth';
+import 'lucide-react';
+import '@djangocfg/ui-core/hooks';
+import '@djangocfg/ui-nextjs';
+import 'moment';
+import 'react/jsx-runtime';
+import 'centrifuge';
+
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+var consolaLogger = createConsola({
+  level: 4 ,
+  formatOptions: {
+    colors: true,
+    date: false,
+    compact: false
+  }
+}).withTag("[Centrifugo]");
+function getConsolaLogger(tag) {
+  const consola = consolaLogger.withTag(`[${tag}]`);
+  return {
+    debug: /* @__PURE__ */ __name((message, data) => consola.debug(message, data || ""), "debug"),
+    info: /* @__PURE__ */ __name((message, data) => consola.info(message, data || ""), "info"),
+    success: /* @__PURE__ */ __name((message, data) => consola.success(message, data || ""), "success"),
+    warning: /* @__PURE__ */ __name((message, data) => consola.warn(message, data || ""), "warning"),
+    error: /* @__PURE__ */ __name((message, error) => consola.error(message, error || ""), "error")
+  };
+}
+__name(getConsolaLogger, "getConsolaLogger");
+
+// src/core/utils/channelValidator.ts
+function validateChannelName(channel) {
+  const hashCount = (channel.match(/#/g) || []).length;
+  if (hashCount >= 2) {
+    const parts = channel.split("#");
+    const [namespace, possibleUserId, ...rest] = parts;
+    const isNumericUserId = /^\d+$/.test(possibleUserId);
+    if (!isNumericUserId && possibleUserId) {
+      const suggestion = channel.replace(/#/g, ":");
+      return {
+        valid: false,
+        warning: `Channel "${channel}" uses '#' separator which Centrifugo interprets as user-limited channel boundary. The part "${possibleUserId}" will be treated as user_id, which may cause permission errors if not in JWT token.`,
+        suggestion: `Use ':' for namespace separation: "${suggestion}"`
+      };
+    }
+    if (isNumericUserId) {
+      return {
+        valid: true,
+        warning: `Channel "${channel}" appears to be a user-limited channel (user_id: ${possibleUserId}). Make sure your JWT token's "sub" field matches "${possibleUserId}".`
+      };
+    }
+  }
+  if (hashCount === 1) {
+    const [namespace, userId] = channel.split("#");
+    if (userId && !/^\d+$/.test(userId) && userId !== "*") {
+      const suggestion = channel.replace("#", ":");
+      return {
+        valid: false,
+        warning: `Channel "${channel}" uses '#' but "${userId}" doesn't look like a user_id. This might cause permission issues.`,
+        suggestion: `Consider using ':' instead: "${suggestion}"`
+      };
+    }
+  }
+  return { valid: true };
+}
+__name(validateChannelName, "validateChannelName");
+function logChannelWarnings(channel, logger3) {
+  const result = validateChannelName(channel);
+  if (!result.valid && result.warning) {
+    const message = `[Centrifugo Channel Warning]
+${result.warning}${result.suggestion ? `
+\u{1F4A1} Suggestion: ${result.suggestion}` : ""}`;
+    if (logger3?.warning) {
+      logger3.warning(message);
+    } else {
+      console.warn(message);
+    }
+  } else if (result.warning) {
+    if (logger3?.warning) {
+      logger3.warning(`[Centrifugo] ${result.warning}`);
+    }
+  }
+}
+__name(logChannelWarnings, "logChannelWarnings");
+getConsolaLogger("ConnectionStatus");
+getConsolaLogger("SubscriptionsList");
+
+// src/config.ts
+process.env.NEXT_PUBLIC_STATIC_BUILD === "true";
+function getVisibilityState() {
+  if (typeof document === "undefined") return true;
+  return document.visibilityState === "visible";
+}
+__name(getVisibilityState, "getVisibilityState");
+function usePageVisibility(options = {}) {
+  const { onVisible, onHidden, onChange } = options;
+  const [state, setState] = useState(() => ({
+    isVisible: getVisibilityState(),
+    wasHidden: false,
+    visibleSince: getVisibilityState() ? Date.now() : null,
+    hiddenDuration: 0
+  }));
+  const onVisibleRef = useRef(onVisible);
+  const onHiddenRef = useRef(onHidden);
+  const onChangeRef = useRef(onChange);
+  const hiddenAtRef = useRef(null);
+  onVisibleRef.current = onVisible;
+  onHiddenRef.current = onHidden;
+  onChangeRef.current = onChange;
+  const checkVisibility = useCallback(() => {
+    return getVisibilityState();
+  }, []);
+  useEffect(() => {
+    if (typeof document === "undefined") return;
+    const handleVisibilityChange = /* @__PURE__ */ __name(() => {
+      const isNowVisible = getVisibilityState();
+      setState((prev) => {
+        let hiddenDuration = prev.hiddenDuration;
+        if (isNowVisible && hiddenAtRef.current !== null) {
+          hiddenDuration = Date.now() - hiddenAtRef.current;
+          hiddenAtRef.current = null;
+        }
+        if (!isNowVisible) {
+          hiddenAtRef.current = Date.now();
+        }
+        return {
+          isVisible: isNowVisible,
+          wasHidden: prev.wasHidden || !isNowVisible,
+          visibleSince: isNowVisible ? prev.visibleSince ?? Date.now() : null,
+          hiddenDuration
+        };
+      });
+      onChangeRef.current?.(isNowVisible);
+      if (isNowVisible) {
+        onVisibleRef.current?.();
+      } else {
+        onHiddenRef.current?.();
+      }
+    }, "handleVisibilityChange");
+    document.addEventListener("visibilitychange", handleVisibilityChange);
+    return () => {
+      document.removeEventListener("visibilitychange", handleVisibilityChange);
+    };
+  }, []);
+  return {
+    ...state,
+    checkVisibility
+  };
+}
+__name(usePageVisibility, "usePageVisibility");
+createContext(void 0);
+var CentrifugoContext = createContext(void 0);
+function useCentrifugo() {
+  const context = useContext(CentrifugoContext);
+  if (context === void 0) {
+    throw new Error("useCentrifugo must be used within a CentrifugoProvider");
+  }
+  return context;
+}
+__name(useCentrifugo, "useCentrifugo");
+
+// src/hooks/useSubscription.ts
+function useSubscription(options) {
+  const { client, isConnected } = useCentrifugo();
+  const { channel, enabled = true, onPublication, onError } = options;
+  const [data, setData] = useState(null);
+  const [error, setError] = useState(null);
+  const [isSubscribed, setIsSubscribed] = useState(false);
+  const unsubscribeRef = useRef(null);
+  const logger3 = useRef(getConsolaLogger("useSubscription")).current;
+  const onPublicationRef = useRef(onPublication);
+  const onErrorRef = useRef(onError);
+  useEffect(() => {
+    onPublicationRef.current = onPublication;
+    onErrorRef.current = onError;
+  }, [onPublication, onError]);
+  const unsubscribe2 = useCallback(() => {
+    if (unsubscribeRef.current) {
+      try {
+        unsubscribeRef.current();
+        unsubscribeRef.current = null;
+        setIsSubscribed(false);
+        logger3.info(`Unsubscribed from channel: ${channel}`);
+      } catch (err) {
+        logger3.error(`Error during unsubscribe from ${channel}`, err);
+      }
+    }
+  }, [channel, logger3]);
+  useEffect(() => {
+    if (!client || !isConnected || !enabled) {
+      if (!isConnected && isSubscribed) {
+        setIsSubscribed(false);
+      }
+      return;
+    }
+    logChannelWarnings(channel, logger3);
+    logger3.info(`Subscribing to channel: ${channel}`);
+    try {
+      const unsub = client.subscribe(channel, (receivedData) => {
+        try {
+          setData(receivedData);
+          setError(null);
+          onPublicationRef.current?.(receivedData);
+        } catch (callbackError) {
+          logger3.error(`Error in onPublication callback for ${channel}`, callbackError);
+        }
+      });
+      unsubscribeRef.current = unsub;
+      setIsSubscribed(true);
+      logger3.success(`Subscribed to channel: ${channel}`);
+    } catch (err) {
+      const subscriptionError = err instanceof Error ? err : new Error("Subscription failed");
+      setError(subscriptionError);
+      try {
+        onErrorRef.current?.(subscriptionError);
+      } catch (callbackError) {
+        logger3.error(`Error in onError callback for ${channel}`, callbackError);
+      }
+      logger3.error(`Subscription failed: ${channel}`, subscriptionError);
+    }
+    return () => {
+      unsubscribe2();
+    };
+  }, [client, isConnected, enabled, channel, unsubscribe2, logger3, isSubscribed]);
+  return {
+    data,
+    error,
+    isSubscribed,
+    unsubscribe: unsubscribe2
+  };
+}
+__name(useSubscription, "useSubscription");
+function useRPC(defaultOptions = {}) {
+  const { client, isConnected } = useCentrifugo();
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState(null);
+  const logger3 = useRef(getConsolaLogger("useRPC")).current;
+  const abortControllerRef = useRef(null);
+  const reset = useCallback(() => {
+    setIsLoading(false);
+    setError(null);
+    if (abortControllerRef.current) {
+      abortControllerRef.current.abort();
+      abortControllerRef.current = null;
+    }
+  }, []);
+  const call2 = useCallback(
+    async (method, params, options = {}) => {
+      if (!client) {
+        const error2 = new Error("Centrifugo client not available");
+        setError(error2);
+        throw error2;
+      }
+      if (!isConnected) {
+        const error2 = new Error("Not connected to Centrifugo");
+        setError(error2);
+        throw error2;
+      }
+      setError(null);
+      setIsLoading(true);
+      const abortController = new AbortController();
+      abortControllerRef.current = abortController;
+      try {
+        const mergedOptions = {
+          ...defaultOptions,
+          ...options
+        };
+        logger3.info(`RPC call: ${method}`, { params });
+        const result = await client.rpc(
+          method,
+          params,
+          {
+            timeout: mergedOptions.timeout,
+            replyChannel: mergedOptions.replyChannel
+          }
+        );
+        if (abortController.signal.aborted) {
+          throw new Error("RPC call aborted");
+        }
+        logger3.success(`RPC success: ${method}`);
+        setIsLoading(false);
+        return result;
+      } catch (err) {
+        const rpcError = err instanceof Error ? err : new Error("RPC call failed");
+        if (!abortController.signal.aborted) {
+          setError(rpcError);
+          logger3.error(`RPC failed: ${method}`, rpcError);
+          const onError = options.onError || defaultOptions.onError;
+          if (onError) {
+            try {
+              onError(rpcError);
+            } catch (callbackError) {
+              logger3.error("Error in onError callback", callbackError);
+            }
+          }
+        }
+        setIsLoading(false);
+        throw rpcError;
+      } finally {
+        if (abortControllerRef.current === abortController) {
+          abortControllerRef.current = null;
+        }
+      }
+    },
+    [client, isConnected, defaultOptions, logger3]
+  );
+  return {
+    call: call2,
+    isLoading,
+    error,
+    reset
+  };
+}
+__name(useRPC, "useRPC");
+function useNamedRPC(defaultOptions = {}) {
+  const { client, isConnected } = useCentrifugo();
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState(null);
+  const logger3 = useRef(getConsolaLogger("useNamedRPC")).current;
+  const reset = useCallback(() => {
+    setIsLoading(false);
+    setError(null);
+  }, []);
+  const call2 = useCallback(
+    async (method, data) => {
+      if (!client) {
+        const error2 = new Error("Centrifugo client not available");
+        setError(error2);
+        throw error2;
+      }
+      if (!isConnected) {
+        const error2 = new Error("Not connected to Centrifugo");
+        setError(error2);
+        throw error2;
+      }
+      setError(null);
+      setIsLoading(true);
+      try {
+        logger3.info(`Native RPC call: ${method}`, { data });
+        const result = await client.namedRPC(method, data);
+        logger3.success(`Native RPC success: ${method}`);
+        setIsLoading(false);
+        return result;
+      } catch (err) {
+        const rpcError = err instanceof Error ? err : new Error("Native RPC call failed");
+        setError(rpcError);
+        logger3.error(`Native RPC failed: ${method}`, rpcError);
+        if (defaultOptions.onError) {
+          try {
+            defaultOptions.onError(rpcError);
+          } catch (callbackError) {
+            logger3.error("Error in onError callback", callbackError);
+          }
+        }
+        setIsLoading(false);
+        throw rpcError;
+      }
+    },
+    [client, isConnected, defaultOptions, logger3]
+  );
+  return {
+    call: call2,
+    isLoading,
+    error,
+    reset
+  };
+}
+__name(useNamedRPC, "useNamedRPC");
+
+export { useNamedRPC, usePageVisibility, useRPC, useSubscription };
+//# sourceMappingURL=hooks.mjs.map
+//# sourceMappingURL=hooks.mjs.map