@tipchatteam/react

React hooks and context provider for integrating TipChat into React applications.

Installation

npm install @tipchatteam/react @tipchat/core

react and react-dom (>=18.0.0) are required as peer dependencies.

Quick Start

1. Create a client and wrap your app

import { TipChatClient } from '@tipchat/core';
import { TipChatProvider } from '@tipchatteam/react';

const client = new TipChatClient({
  baseUrl: 'https://tipchat-api.onrender.com',
  tenantId: 'your-tenant-id',
  walletProvider: {
    getAddress: () => wallet.address,
    signMessage: (msg) => wallet.signMessage(msg),
  },
});

function App() {
  return (
    <TipChatProvider value={client}>
      <ChatPage />
    </TipChatProvider>
  );
}

2. Use hooks in your components

import { useChat } from '@tipchatteam/react';

function ChatRoom({ conversationId }: { conversationId: string }) {
  const {
    messages,
    loading,
    send,
    retry,
    dismiss,
    sending,
    typingUsers,
    sendTyping,
  } = useChat(conversationId, {
    cache: true,       // localStorage caching with stale-while-revalidate
    optimistic: true,  // instant UI feedback before server confirms
    realtime: true,    // SSE subscription with polling fallback
  });

  const handleSend = async (text: string) => {
    await send({ content: text, messageType: 'text' });
  };

  return (
    <div>
      {messages.map((msg) => (
        <div key={msg.id}>{msg.content}</div>
      ))}
      {typingUsers.length > 0 && (
        <p>{typingUsers.map(u => u.displayName || u.walletAddress).join(', ')} typing...</p>
      )}
      <input
        onChange={() => sendTyping()}
        onKeyDown={(e) => {
          if (e.key === 'Enter') handleSend(e.currentTarget.value);
        }}
      />
    </div>
  );
}

Hooks

useChat(conversationId, options?) -- Recommended

The all-in-one chat hook. Combines messages, sending, optimistic updates, caching, real-time subscription, and typing indicators into a single hook.

| Return Value | Type | Description | |-------------|------|-------------| | messages | (Message \| OptimisticMessage)[] | All messages sorted chronologically, including pending optimistic ones | | loading | boolean | Whether the initial fetch is in progress | | error | string \| null | Current error message, if any | | send | (payload) => Promise<Message> | Send a message (optimistic if enabled) | | retry | (localId) => Promise<Message> | Retry a failed optimistic message | | dismiss | (localId) => void | Remove a failed optimistic message from the list | | sending | boolean | Whether a message is currently being sent | | pendingCount | number | Number of pending optimistic messages | | typingUsers | TypingUser[] | Users currently typing (excludes self) | | sendTyping | () => void | Broadcast typing status (debounced internally) | | refresh | () => Promise<void> | Force re-fetch messages from server | | walletAddress | string | Current user's resolved wallet address |

Options:

| Option | Type | Default | Description | |--------|------|---------|-------------| | cache | boolean | true | Enable localStorage caching | | optimistic | boolean | true | Enable optimistic message updates | | realtime | boolean | true | Enable SSE/polling real-time subscription | | pollMs | number | 1500 | Polling interval fallback in milliseconds | | limit | number | 100 | Number of messages to fetch initially |

useConversations(limit?, offset?)

Fetch the list of conversations for the current wallet.

| Return Value | Type | Description | |-------------|------|-------------| | data | ListConversationsResponse \| null | Conversations with metadata | | loading | boolean | Loading state | | error | string \| null | Error message | | refresh | () => Promise<void> | Re-fetch conversations |

useMessages(conversationId, options?)

Fetch messages for a conversation with optional polling.

| Return Value | Type | Description | |-------------|------|-------------| | data | ListMessagesResponse \| null | Messages with pagination | | loading | boolean | Loading state | | error | string \| null | Error message | | refresh | () => Promise<void> | Re-fetch messages |

useSendMessage()

Send a message to a conversation.

| Return Value | Type | Description | |-------------|------|-------------| | send | (conversationId, payload) => Promise<Message> | Send function | | sending | boolean | Whether a send is in flight | | error | string \| null | Error message |

useSendTipMessage()

Execute an on-chain tip and post the corresponding tip message.

| Return Value | Type | Description | |-------------|------|-------------| | sendTipMessage | (input) => Promise<{ txHash?, messageId }> | Send tip function | | sending | boolean | Whether a tip is in flight | | error | string \| null | Error message |

useRealtimeMessages(conversationId, onMessage, intervalMs?)

Subscribe to real-time messages via SSE/polling. Automatically cleans up on unmount.

useTypingIndicator(conversationId, options?)

Standalone typing indicator hook for when you want typing indicators without the full useChat hook.

| Return Value | Type | Description | |-------------|------|-------------| | typingUsers | TypingUser[] | Users currently typing | | sendTyping | () => void | Broadcast typing (debounced) |

TipChatProvider

React context provider that makes the TipChatClient available to all hooks.

useTipChatClient()

Access the TipChatClient instance from context. Throws if no provider is found.

Documentation

Full documentation and guides are available at tipchat.dev.

License

MIT