OddSockets React Native SDK

Official React Native SDK for the OddSockets real-time messaging platform.

Installation

npm install oddsockets-react-native
# or
yarn add oddsockets-react-native

Quick Start

import OddSockets from 'oddsockets-react-native';

// Initialize the client
const client = new OddSockets({
  apiKey: 'your-api-key-here',
  userId: 'user-123'
});

// Get a channel
const channel = client.channel('my-channel');

// Subscribe to messages
await channel.subscribe((message) => {
  console.log('Received message:', message);
});

// Publish a message
await channel.publish('Hello, World!');

Features

• ✅ Real-time messaging - Send and receive messages instantly
• ✅ Channel-based communication - Organize messages into channels
• ✅ Presence tracking - See who's online in channels
• ✅ Message history - Retrieve past messages
• ✅ Automatic reconnection - Handles network interruptions gracefully
• ✅ TypeScript support - Full type definitions included
• ✅ Enhanced surface - Reactions, typing, threads, DMs, presence and more
• ✅ React Native optimized - Built specifically for React Native

API Reference

OddSockets Client

Constructor

const client = new OddSockets({
  apiKey: string,           // Required: Your OddSockets API key
  userId?: string,          // Optional: User identifier
  autoConnect?: boolean,    // Optional: Auto-connect on instantiation (default: true)
  options?: {               // Optional: Additional connection options
    timeout?: number,
    transports?: string[],
    // ... other socket.io options
  }
});

Methods

• connect() - Connect to the OddSockets platform
• disconnect() - Disconnect from the platform
• channel(name) - Get or create a channel
• getState() - Get current connection state
• getWorkerInfo() - Get assigned worker information
• publishBulk(messages) - Publish multiple messages at once

Events

client.on('connecting', () => console.log('Connecting...'));
client.on('connected', () => console.log('Connected!'));
client.on('disconnected', (reason) => console.log('Disconnected:', reason));
client.on('error', (error) => console.error('Error:', error));
client.on('reconnecting', (event) => console.log('Reconnecting...', event));
client.on('worker_assigned', (info) => console.log('Worker assigned:', info));

Channel

Methods

• subscribe(callback, options?) - Subscribe to channel messages
• unsubscribe() - Unsubscribe from the channel
• publish(message, options?) - Publish a message
• getHistory(options?) - Get message history
• getPresence() - Get current presence information
• updateState(state) - Update user state
• isSubscribed() - Check subscription status
• getName() - Get channel name

Events

channel.on('message', (data) => console.log('Message:', data));
channel.on('presence', (data) => console.log('Presence:', data));
channel.on('presence_change', (data) => console.log('Presence change:', data));

Examples

Basic Chat Application

import React, { useState, useEffect } from 'react';
import { View, Text, TextInput, TouchableOpacity, FlatList } from 'react-native';
import OddSockets from 'oddsockets-react-native';

const ChatApp = () => {
  const [client] = useState(() => new OddSockets({
    apiKey: 'your-api-key',
    userId: 'user-123'
  }));
  
  const [channel] = useState(() => client.channel('general'));
  const [messages, setMessages] = useState([]);
  const [inputText, setInputText] = useState('');

  useEffect(() => {
    const setupChannel = async () => {
      await channel.subscribe((message) => {
        setMessages(prev => [...prev, message]);
      });
    };

    setupChannel();

    return () => {
      channel.unsubscribe();
      client.disconnect();
    };
  }, []);

  const sendMessage = async () => {
    if (inputText.trim()) {
      await channel.publish({
        text: inputText,
        timestamp: new Date().toISOString()
      });
      setInputText('');
    }
  };

  return (
    <View style={{ flex: 1, padding: 20 }}>
      <FlatList
        data={messages}
        keyExtractor={(item, index) => index.toString()}
        renderItem={({ item }) => (
          <Text>{item.message.text}</Text>
        )}
      />
      <View style={{ flexDirection: 'row' }}>
        <TextInput
          value={inputText}
          onChangeText={setInputText}
          placeholder="Type a message..."
          style={{ flex: 1, borderWidth: 1, padding: 10 }}
        />
        <TouchableOpacity onPress={sendMessage}>
          <Text>Send</Text>
        </TouchableOpacity>
      </View>
    </View>
  );
};

export default ChatApp;

Enhanced Features

Beyond core pub/sub, OddSockets ships a Slack-like enhanced surface — reactions, typing indicators, threads, read receipts, presence/status, notifications, DMs, channel management, message editing and search. It lives on client.enhanced. The pattern is always the same:

1. Send an action with a client.enhanced.* method (camelCase).
2. Receive the paired broadcast with client.on('<event>', handler) — the worker forwards every enhanced broadcast onto the client event surface.

import OddSockets from 'oddsockets-react-native';

const client = new OddSockets({ apiKey: 'YOUR_API_KEY', userId: 'alice' });

const channel = client.channel('room-42');
await channel.subscribe(() => {}, { enablePresence: true });

// Receive-path: broadcasts from other users on the channel
client.on('user_typing',    (data) => console.log(`${data.userId} is typing`));
client.on('reaction_added', (data) => console.log(`${data.userId} reacted ${data.emoji}`));
client.on('thread_reply',   (data) => console.log('new thread reply', data));

// Send-path: enhanced actions over the live socket
client.enhanced.startTyping('alice', 'room-42');
client.enhanced.addReaction({
  messageId: 'msg-1', channel: 'room-42', emoji: ':thumbsup:',
  userId: 'alice', userName: 'Alice',
});
await client.enhanced.threadReply({
  channel: 'room-42', parentMessageId: 'msg-1',
  message: 'Replying in the thread', userId: 'alice', userName: 'Alice',
});

Each area exposes methods on client.enhanced; the worker broadcasts the paired events which you handle with client.on(...). Query methods (get*, search*) return a Promise that resolves with the worker response.

Area	Requests (client.enhanced.*)	Broadcast events (client.on)
Typing	startTyping, stopTyping	user_typing, user_stopped_typing
Reactions	addReaction, removeReaction, getReactions	reaction_added, reaction_removed
Threads	threadReply, getThread, subscribeThread, followThread, unfollowThread, markThreadRead	thread_reply, thread_subscribed, thread_followed, thread_read_updated
Read receipts	markRead, markAllRead, getUnreadCounts	user_read, unread_count_updated, all_marked_read
Messages	editMessage, deleteMessage, pinMessage, unpinMessage, getPinnedMessages	message_edited, message_deleted, message_pinned, message_unpinned
Presence & status	setStatus, setCustomStatus, clearCustomStatus, setDND, clearDND, getUserPresence	user_status_changed, custom_status_updated, dnd_status_changed
Channels	createChannel, updateChannel, archiveChannel, inviteToChannel, joinChannel, leaveChannel, getChannelMembers	channel_created, channel_updated, user_invited, user_joined_channel, user_left_channel
DMs	createDM, sendDM, getDMConversations	dm_created, dm_received
Notifications	subscribeNotifications, getNotifications, markNotificationRead, clearNotifications	notification, notification_read, notifications_cleared
Search	searchMessages, searchInChannel, searchByUser, filterMessages	(query results returned via Promise)

For any worker event not wrapped above, subscribe with the raw client.on('<event>', handler) API — all enhanced broadcasts are forwarded onto the client surface.

Configuration

Environment Setup

For React Native development, make sure you have:

1. React Native development environment set up
2. Node.js 16+ installed
3. Your OddSockets API key

TypeScript Support

This SDK is written in TypeScript and includes full type definitions. No additional setup is required for TypeScript projects.

Error Handling

try {
  await channel.publish('Hello');
} catch (error) {
  console.error('Failed to publish:', error);
}

// Or using event listeners
client.on('error', (error) => {
  console.error('Client error:', error);
});

Message Size Limits

Messages are limited to 32KB (32,768 bytes) to ensure optimal performance and compatibility with industry standards.

Get a Free API Key

curl -X POST https://oddsockets.com/api/agent-signup \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "agentName": "my-agent", "platform": "react-native"}'
curl -X POST https://oddsockets.com/api/agent-signup/verify \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "code": "123456", "agentName": "my-agent"}'

Plans

	Free	Starter	Pro
Price	$0/mo	$49.99/mo	$299/mo
MAU	100	1,000	50,000
Concurrent connections	50	1,000	Unlimited
Messages/day	10,000	4,320,000	Unlimited
Channels	10	Unlimited	Unlimited
Storage	100MB (24h)	50GB (6 months)	Unlimited

Support

• Documentation
• Issue Tracker
• Email Support

License

MIT License - Copyright (c) 2026 Joe Wee, Tyga.Cloud Ltd. See LICENSE for details.