FindMe WebSocket API

Overview

The FindMe WebSocket API provides real-time communication capabilities for the FindMe application using Socket.IO. The API is organized into four namespaces:

• /presence - User online/offline status and activity tracking
• /chat - Real-time messaging and conversations
• /location - Location updates and sharing
• /interactions - User interactions (waves, connections, nearby users, profiles)

Authentication

All WebSocket connections require JWT authentication. Pass the token in the connection handshake:

const socket = io('/presence', {
  auth: {
    token: 'Bearer YOUR_JWT_TOKEN'
  }
});

Or via headers:

const socket = io('/presence', {
  extraHeaders: {
    Authorization: 'Bearer YOUR_JWT_TOKEN'
  }
});

Namespaces Overview

Presence Namespace /presence

Tracks user online/offline status globally across the application.

Connection

const presenceSocket = io('/presence', {
  auth: { token: 'Bearer YOUR_JWT_TOKEN' }
});

Events

Example

// Ping to keep alive
presenceSocket.emit('ping');

presenceSocket.on('pong', (data) => {
  console.log('Server time:', data.timestamp);
});

// Listen for other users' presence
presenceSocket.on('user:online', ({ userId, status }) => {
  console.log(`User ${userId} is now ${status}`);
});

Chat Namespace /chat

Handles all messaging functionality including direct messages, group conversations, typing indicators, and message receipts.

Connection

const chatSocket = io('chat', {
  auth: { token: 'Bearer YOUR_JWT_TOKEN' }
});

Conversation Events

Message Events

Receipt Events

Typing Events

Schemas

Location Namespace /location

Handles location updates and sharing.

Connection

const locationSocket = io('/location', {
  auth: { token: 'Bearer YOUR_JWT_TOKEN' }
});

Events

Example

// Update location
locationSocket.emit('updateLocation', {
  latitude: 37.7749,
  longitude: -122.4194
});

locationSocket.on('locationUpdated', (user) => {
  console.log('Location updated for:', user.email);
});

Interactions Namespace /interactions

Handles user interactions including waves, connection requests, nearby user discovery, and profile viewing.

Connection

const interactionsSocket = io('/interactions', {
  auth: {
    token: 'Bearer YOUR_JWT_TOKEN'
  }
});

Events

Example

// Get nearby users
interactionsSocket.emit('nearbyUsers:get', {
  latitude: '37.7749',
  longitude: '-122.4194',
  radius: '5',
  page: 1,
  limit: 10
});

interactionsSocket.on('nearbyUsers:list', (response) => {
  console.log('Nearby users:', response.data);
});

// Send a wave
interactionsSocket.emit('wave:send', {
  targetUserId: 'user-uuid-here'
});

interactionsSocket.on('wave:sent', (data) => {
  console.log('Wave sent:', data);
});

// Listen for received waves
interactionsSocket.on('wave:received', (data) => {
  console.log('Received wave from:', data.from);
});

// Send connection request
interactionsSocket.emit('connection:request', {
  targetUserId: 'user-uuid-here'
});

interactionsSocket.on('connection:requested', (data) => {
  console.log('Connection requested:', data);
});

// Listen for connection accepted by other user
interactionsSocket.on('connection:acceptedByUser', (data) => {
  console.log('User accepted your connection:', data);
});

Usage Examples

Complete Chat Flow

// 1. Connect to chat namespace
const chatSocket = io('chat', {
  auth: { token: 'Bearer YOUR_JWT_TOKEN' }
});

// 2. Create a conversation
chatSocket.emit('conversation:create', {
  type: 'direct',
  participantIds: ['user-uuid-here']
});

chatSocket.on('conversation:created', ({ conversation }) => {
  // 3. Join the conversation
  chatSocket.emit('conversation:join', {
    conversationId: conversation.id
  });
});

// 4. Send a message
chatSocket.emit('message:send', {
  conversationId: 'conv-uuid-here',
  content: 'Hello!',
  messageType: 'text'
});

// 5. Receive messages
chatSocket.on('message:new', ({ message, conversationId }) => {
  console.log(`New message: ${message.content}`);
});

// 6. Typing indicators
chatSocket.emit('typing:start', { conversationId: 'conv-uuid-here' });

chatSocket.on('typing:started', ({ conversationId, userId }) => {
  console.log(`User ${userId} is typing...`);
});

Error Handling

chatSocket.on('error', (error) => {
  console.error('Chat error:', error.message);
});