Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

12.8 KB
Raw Blame
import { useEffect, useRef, useCallback, useState } from 'react';
import { io, Socket } from 'socket.io-client';
import { API_ORIGIN } from '../services/api';
import { resolveSocketUrl, warnIfInsecureHttpUrl } from '../utils/urlSecurity';

interface SessionStatusEvent {
  sessionId: string;
  status: string;
  timestamp: string;
}

interface QRCodeEvent {
  sessionId: string;
  qrCode: string;
  timestamp: string;
}

interface MessageEvent {
  sessionId: string;
  message: Record<string, unknown>;
  timestamp: string;
}

interface MessageAckEvent {
  sessionId: string;
  id: string;
  messageId: string;
  // Neutral delivery status emitted by the backend (engine-agnostic), not a raw wwebjs ack integer.
  status: 'pending' | 'sent' | 'delivered' | 'read' | 'failed';
  // Deprecated legacy numeric ack kept for backward compatibility; prefer `status`.
  ack?: number;
  timestamp?: string;
}

interface MessageReactionEvent {
  sessionId: string;
  messageId: string;
  chatId: string;
  reaction: string;
  senderId: string;
  /**
   * The post-apply snapshot of every reaction on the message. ABSENT when the gateway holds no
   * stored copy of the message to compute it from, which it says by omitting the key rather than
   * sending an empty object — absent means "unknown", `{}` means "there are none left". Keep it
   * optional: normalising the absence away here is what makes a consumer's own fallback dead code.
   */
  reactions?: Record<string, string>;
  timestamp: string;
}

interface MessageEditedEvent {
  sessionId: string;
  messageId: string;
  chatId: string;
  body: string;
  timestamp: number;
}

interface MessageRevokedEvent {
  sessionId: string;
  id: string;
  /**
   * Id of the ORIGINAL deleted message. Optional: whatsapp-web.js can only resolve it when the
   * original is still in its local store, and Baileys sets it identical to `id`.
   */
  revokedId?: string;
  chatId: string;
  from: string;
  to: string;
  body: string;
  type: string;
  timestamp: number;
}

/** A freshly ingested contact status (story) — the dashboard uses it purely as a refetch signal. */
interface StatusReceivedEvent {
  sessionId: string;
  timestamp: string;
}

/** A restriction imposed or lifted — the dashboard uses it purely as a refetch signal for the badge. */
interface SessionRestrictionEvent {
  sessionId: string;
  timestamp: string;
}

/** Ack frame answering a client `subscribe` request (`{type: 'subscribed'}`). */
interface SubscribedEvent {
  sessionId: string;
  events: string[];
}

/** Error frame answering a client request (`{type: 'error'}`), e.g. FORBIDDEN_SESSION. */
interface ServerErrorEvent {
  code: string;
  message: string;
}

interface WebSocketEvents {
  onSessionStatus?: (event: SessionStatusEvent) => void;
  onQRCode?: (event: QRCodeEvent) => void;
  onMessage?: (event: MessageEvent) => void;
  onMessageAck?: (event: MessageAckEvent) => void;
  onMessageReaction?: (event: MessageReactionEvent) => void;
  onMessageRevoked?: (event: MessageRevokedEvent) => void;
  onMessageEdited?: (event: MessageEditedEvent) => void;
  onStatusReceived?: (event: StatusReceivedEvent) => void;
  onSessionRestriction?: (event: SessionRestrictionEvent) => void;
  onSubscribed?: (event: SubscribedEvent) => void;
  onServerError?: (event: ServerErrorEvent) => void;
}

// Shape of the server -> client event envelope produced by the NestJS gateway.
// `type` is the 'event' literal so the frame union below narrows on it.
interface ServerEventEnvelope {
  type: 'event';
  timestamp: string;
  payload?: {
    event: string;
    sessionId: string;
    data: Record<string, unknown>;
  };
}

// The gateway also answers client requests (subscribe/unsubscribe/ping) with ack frames
// (`subscribed` / `unsubscribed` / `pong`) and error frames (`error`) on the same 'message'
// channel. Routing them to the UI matters: a scoped key's rejected wildcard subscribe must be
// visible so the caller can fall back to per-session rooms instead of waiting forever.
interface ServerAckFrame {
  type: 'subscribed' | 'unsubscribed' | 'pong';
  sessionId?: string;
  events?: string[];
}

interface ServerErrorFrame {
  type: 'error';
  code?: string;
  message?: string;
}

// The origin of VITE_WS_URL when set, else of VITE_API_URL (a split-origin build names the API there), else the
// page's own origin (the single-container setup, or nginx proxying /socket.io in Docker).
const SOCKET_URL = resolveSocketUrl(import.meta.env.VITE_WS_URL, API_ORIGIN, window.location.origin);
// Warn when VITE_WS_URL is an insecure http:// or ws:// URL on a non-localhost host; api.ts already warns
// about VITE_API_URL under its own name.
if (import.meta.env.VITE_WS_URL) warnIfInsecureHttpUrl(SOCKET_URL, 'VITE_WS_URL');

export function useWebSocket(events: WebSocketEvents = {}) {
  const socketRef = useRef<Socket | null>(null);
  const [isConnected, setIsConnected] = useState(false);
  // True when the connection is dead until the user retries: Socket.IO either exhausted its
  // reconnection attempts, or the server itself closed the socket (rate limit, auth rejection,
  // key eviction — a server-initiated close sets skipReconnect, so no auto-reconnect runs and
  // `reconnect_failed` never fires). Lets the UI show a "connection lost" indicator + a manual
  // retry instead of silently going stale.
  const [connectionFailed, setConnectionFailed] = useState(false);
  // Bumped every time connect() creates a NEW socket instance. The envelope-handler effect below
  // captures socketRef.current when it runs; without this epoch in its deps, a manual reconnect()
  // (which swaps in a fresh socket) leaves the new socket with NO 'message' listener while
  // isConnected still reports true - realtime events stop arriving with no signal anywhere.
  const [socketEpoch, setSocketEpoch] = useState(0);

  const connect = useCallback(() => {
    if (socketRef.current?.connected) return;

    // Get API key from sessionStorage (same as api.ts)
    const apiKey = sessionStorage.getItem('openwa_api_key');

    if (!apiKey) {
      console.warn('[WebSocket] No API key found, skipping connection');
      return;
    }

    setSocketEpoch(epoch => epoch + 1);
    socketRef.current = io(`${SOCKET_URL}/events`, {
      autoConnect: true,
      reconnection: true,
      reconnectionAttempts: 5,
      reconnectionDelay: 1000,
      // Send the key via `auth` (and a header for proxies). NOT via `query` — a key in the
      // handshake URL leaks into access logs / Referer. The gateway reads auth first.
      auth: {
        apiKey,
      },
      extraHeaders: {
        'X-API-Key': apiKey,
      },
    });

    socketRef.current.on('connect', () => {
      setIsConnected(true);
      setConnectionFailed(false);
    });

    socketRef.current.on('disconnect', reason => {
      setIsConnected(false);
      // A server-initiated close (handshake rate limit, auth rejection, key eviction) sets
      // Socket.IO's skipReconnect: no auto-reconnect runs, so `reconnect_failed` never fires
      // and without this the tab would silently stop receiving events. Surface the same
      // recoverable failure state — the banner's manual retry opens a fresh socket, which
      // skipReconnect does not block.
      if (reason === 'io server disconnect') {
        setConnectionFailed(true);
      }
    });

    socketRef.current.on('connect_error', error => {
      console.warn('[WebSocket] Connection error:', error.message);
    });

    // `reconnect_failed` is emitted on the Manager once all reconnectionAttempts are exhausted.
    socketRef.current.io.on('reconnect_failed', () => {
      console.warn('[WebSocket] Reconnection failed after max attempts');
      setConnectionFailed(true);
    });
  }, []);

  // Manual retry after the socket permanently gave up: tear down the dead socket and reconnect.
  const reconnect = useCallback(() => {
    setConnectionFailed(false);
    if (socketRef.current) {
      socketRef.current.disconnect();
      socketRef.current = null;
    }
    connect();
  }, [connect]);

  const subscribe = useCallback((sessionId: string, eventsList: string[]) => {
    if (socketRef.current?.connected) {
      socketRef.current.emit('message', {
        type: 'subscribe',
        sessionId,
        events: eventsList,
      });
    }
  }, []);

  const unsubscribe = useCallback((sessionId: string) => {
    if (socketRef.current?.connected) {
      socketRef.current.emit('message', {
        type: 'unsubscribe',
        sessionId,
      });
    }
  }, []);

  useEffect(() => {
    connect();

    return () => {
      if (socketRef.current) {
        socketRef.current.disconnect();
        socketRef.current = null;
      }
    };
  }, [connect]);

  // Register the single envelope handler and fan out to the typed callbacks.
  useEffect(() => {
    if (!socketRef.current) return;

    const socket = socketRef.current;

    const handleIncomingMessage = (msg: ServerEventEnvelope | ServerAckFrame | ServerErrorFrame) => {
      if (!msg || typeof msg.type !== 'string') return;

      if (msg.type === 'error') {
        events.onServerError?.({ code: String(msg.code ?? ''), message: String(msg.message ?? '') });
        return;
      }
      if (msg.type === 'subscribed') {
        events.onSubscribed?.({
          sessionId: String(msg.sessionId ?? ''),
          events: Array.isArray(msg.events) ? msg.events : [],
        });
        return;
      }
      if (msg.type !== 'event' || !msg.payload) return;

      const { event, sessionId, data } = msg.payload;

      switch (event) {
        case 'session.status':
          events.onSessionStatus?.({ sessionId, status: String(data.status), timestamp: msg.timestamp });
          break;
        case 'session.qr':
          events.onQRCode?.({ sessionId, qrCode: String(data.qrCode), timestamp: msg.timestamp });
          break;
        case 'message.received':
        case 'message.sent':
          events.onMessage?.({ sessionId, message: data, timestamp: msg.timestamp });
          break;
        case 'status.received':
          events.onStatusReceived?.({ sessionId, timestamp: msg.timestamp });
          break;
        case 'session.restriction':
          events.onSessionRestriction?.({ sessionId, timestamp: msg.timestamp });
          break;
        case 'message.ack':
          events.onMessageAck?.({
            sessionId,
            id: String(data.id),
            messageId: String(data.messageId),
            status: data.status as MessageAckEvent['status'],
            ack: typeof data.ack === 'number' ? data.ack : undefined,
            timestamp: msg.timestamp,
          });
          break;
        case 'message.reaction':
          events.onMessageReaction?.({
            sessionId,
            messageId: String(data.messageId),
            chatId: String(data.chatId),
            reaction: String(data.reaction),
            senderId: String(data.senderId),
            // Carried through as-is, including absent: `|| {}` here would tell every consumer that
            // the message has no reactions left, which is a different claim from "we do not know".
            reactions: data.reactions as Record<string, string> | undefined,
            timestamp: msg.timestamp,
          });
          break;
        case 'message.revoked':
          events.onMessageRevoked?.({
            sessionId,
            id: String(data.id),
            // Not String()-coerced like its neighbours: the field is optional on the wire, and
            // String(undefined) would yield the truthy literal "undefined" and defeat the fallback.
            revokedId: typeof data.revokedId === 'string' ? data.revokedId : undefined,
            chatId: String(data.chatId),
            from: String(data.from),
            to: String(data.to),
            body: String(data.body ?? ''),
            type: String(data.type),
            timestamp: Number(data.timestamp),
          });
          break;
        case 'message.edited':
          // Keep optional/malformed wire fields from becoming the truthy strings "undefined"/"null"
          // and accidentally matching an unrelated cached row.
          if (
            typeof data.messageId !== 'string' ||
            !data.messageId ||
            typeof data.chatId !== 'string' ||
            typeof data.body !== 'string'
          ) {
            break;
          }
          events.onMessageEdited?.({
            sessionId,
            messageId: data.messageId,
            chatId: data.chatId,
            body: data.body,
            timestamp: Number(data.timestamp),
          });
          break;
        default:
          break;
      }
    };

    socket.on('message', handleIncomingMessage);

    return () => {
      socket.off('message', handleIncomingMessage);
    };
    // socketEpoch re-runs this effect for the socket a manual reconnect() swapped in; the cleanup
    // above detaches the handler from the dead instance first.
  }, [events, socketEpoch]);

  return { isConnected, connectionFailed, reconnect, subscribe, unsubscribe };
}