@cx3/sdk

React SDK for CX3 - Customer Experience Platform.

Installation

npm install @cx3/sdk
# or
pnpm add @cx3/sdk

Quick Start

import { ChatWidget } from '@cx3/sdk';

function App() {
  return (
    <ChatWidget
      config={{
        serverUrl: 'https://api.cx3.inddev.org',
        tenantId: 'your_tenant_id',
        userId: 'current_user',
        userRole: 'customer',
        recipientId: 'provider_123',
        getToken: async () => fetchTokenFromYourBackend(),
      }}
    />
  );
}

User Metadata Resolution

The SDK supports resolving user metadata (display names, avatars) via a callback. This provides Agora/Sendbird-like DX without CX3 storing user data.

import { ChatWidget } from '@cx3/sdk';

function App() {
  return (
    <ChatWidget
      config={{
        serverUrl: 'https://api.cx3.inddev.org',
        tenantId: 'your_tenant_id',
        userId: 'user_123',
        userRole: 'customer',
        recipientId: 'astro_456',
        getToken: async () => fetchTokenFromYourBackend(),
        // NEW: Resolve user metadata for display
        resolveUser: async (userId) => {
          // Fetch from your backend
          if (userId.startsWith('astro_')) {
            const res = await api.get(`/astrologer/${userId.replace('astro_', '')}`);
            return {
              displayName: res.data.name,
              avatar: res.data.picture,
              subtitle: res.data.specialization, // e.g., "Vedic Astrologer"
            };
          } else {
            const res = await api.get(`/user/${userId.replace('user_', '')}`);
            return {
              displayName: res.data.name,
              avatar: res.data.picture,
            };
          }
        },
      }}
    />
  );
}

UserMetadata Interface

interface UserMetadata {
  displayName: string;  // Required: shown in header and messages
  avatar?: string;      // Optional: avatar URL
  subtitle?: string;    // Optional: shown below name in header
}

How It Works

1. Auto-resolution: SDK automatically calls resolveUser for the recipient on connect
2. Message senders: SDK resolves senders from incoming messages
3. Caching: Results are cached to avoid repeated calls
4. Loading states: UI shows loading indicator while resolving
5. Fallback: Falls back to raw userId if resolveUser not provided or fails

Using with useChat Hook

import { useChat } from '@cx3/sdk';

function CustomChat() {
  const chat = useChat({
    serverUrl: 'https://api.cx3.inddev.org',
    tenantId: 'your_tenant_id',
    userId: 'user_123',
    userRole: 'customer',
    recipientId: 'astro_456',
    getToken: async () => fetchToken(),
    resolveUser: async (userId) => ({ displayName: 'Name', avatar: 'url' }),
  });

  // Access resolved metadata
  const recipientMeta = chat.getResolvedUser('astro_456');
  // { displayName: 'Pandit Sharma', avatar: '...', subtitle: 'Vedic Astrologer' }

  // Check if still resolving
  const isLoading = chat.isResolvingUser('astro_456');

  // Manually resolve users (e.g., for chat list)
  await chat.resolveUsers(['user_1', 'user_2', 'user_3']);

  // All resolved users
  console.log(chat.resolvedUsers);
  // { 'astro_456': { displayName: '...', ... }, ... }
}

Features

Chat Module ✅

• Real-time messaging via WebSocket
• User metadata resolution (display names, avatars)
• Read receipts
• Typing indicators
• Online presence
• Unread counts
• Message history with pagination
• Ready-to-use components (ChatWidget, ChatList)
• Flexible hooks (useChat, useChatList)

Coins Module 🔜

• Prepaid credits system
• Balance management
• Transaction history

Calendrella Module 🔜

• Booking and scheduling
• Availability management
• Calendar sync

API Reference

ChatConfig

interface ChatConfig {
  serverUrl: string;
  tenantId: string;
  userId: string;
  userRole: 'customer' | 'provider' | 'admin';
  recipientId?: string;
  chatId?: string;
  autoConnect?: boolean;
  token?: string;
  getToken?: () => Promise<string>;
  resolveUser?: (userId: string) => Promise<UserMetadata>;
}

UseChatReturn

interface UseChatReturn {
  // Connection
  isConnected: boolean;
  isConnecting: boolean;
  connect: () => Promise<void>;
  disconnect: () => void;
  
  // Messages
  messages: ChatMessage[];
  sendMessage: (content: string) => boolean;
  loadOlderMessages: () => Promise<ChatMessage[]>;
  
  // Typing & Presence
  typingUsers: TypingUser[];
  sendTypingIndicator: (isTyping: boolean) => boolean;
  isUserOnline: (userId: string) => boolean;
  
  // Read receipts
  markAsRead: (messageId?: string) => boolean;
  
  // Unread counts
  unreadCounts: UnreadCount[];
  getUnreadCount: (chatId: string) => number;
  totalUnread: number;
  
  // User metadata resolution
  resolvedUsers: Record<string, UserMetadata>;
  getResolvedUser: (userId: string) => UserMetadata | undefined;
  isResolvingUser: (userId: string) => boolean;
  resolveUsers: (userIds: string[]) => Promise<void>;
}

Documentation

See Integration Guide for detailed documentation.

License

MIT © Inddev Innovation Studio Pvt Ltd