@tipchatteam/core

Chat infrastructure for web3 applications. Send messages, react with emoji, tip with crypto -- all authenticated by wallet signature.

Installation

npm install @tipchatteam/core

Quick Start

import { TipChatClient, createEip1193TipExecutor } from '@tipchatteam/core';

// Initialize the client
const client = new TipChatClient({
  baseUrl: 'https://tipchat-api.onrender.com',
  tenantId: 'your-tenant-id',
  walletProvider: {
    getAddress: () => wallet.address,
    signMessage: (msg) => wallet.signMessage(msg),
  },
  tipExecutor: createEip1193TipExecutor({
    provider: window.ethereum,
    chainId: 8453, // Base
  }),
});

// Authenticate (wallet signature)
await client.authenticate();

// List conversations
const { conversations } = await client.listConversations();

// Send a message
const { message } = await client.sendMessage(conversationId, {
  content: 'Hello from web3!',
});

// Send a message with optimistic update
const { optimistic, confirmed } = client.sendMessageOptimistic(conversationId, {
  content: 'This appears instantly',
});
// `optimistic` is available immediately for UI rendering
// `confirmed` resolves when the server acknowledges the message

// Send a tip
const result = await client.sendTipMessage({
  conversationId,
  recipientWalletAddress: '0x...',
  amount: 1.0,
  currency: 'USDC',
});

// Watch for new messages (SSE with polling fallback)
const unsubscribe = client.watchMessages(conversationId, (message) => {
  console.log('New message:', message.content);
}, {
  onTyping: (event) => {
    console.log(`${event.walletAddress} is ${event.type === 'started' ? 'typing' : 'idle'}`);
  },
});

// Clean up
unsubscribe();

Features

• Wallet Authentication -- Sign-in with Ethereum (SIWE) style nonce-based auth
• Conversations -- Direct messages, group chats, and market-linked discussions
• Real-time Messaging -- Server-Sent Events with automatic polling fallback
• Optimistic Updates -- Instant UI feedback with server confirmation
• On-chain Tipping -- Send USDC, ETH, or SOL tips directly in chat
• Gasless Tipping -- Paymaster-sponsored transactions via smart wallets
• Typing Indicators -- Real-time typing status for all participants
• Reactions -- Emoji reactions on messages
• Message Moderation -- Built-in content filtering with web3 trust scoring
• Caching -- CacheManager with stale-while-revalidate for offline-friendly UX
• Multi-chain -- Adapters for EIP-1193, Privy, WalletConnect, and Solana wallets

Wallet Adapters

| Adapter | Import | Use Case | |---------|--------|----------| | createEip1193TipExecutor | @tipchatteam/core | MetaMask, Rabby, any EIP-1193 provider | | createPrivyWalletAdapter / createPrivyTipExecutor | @tipchatteam/core | Privy embedded wallets | | createWalletConnectWalletAdapter / createWalletConnectTipExecutor | @tipchatteam/core | WalletConnect v2 | | createSolanaWalletAdapter / createSolanaTipExecutor | @tipchatteam/core | Phantom, Solflare, etc. | | createGaslessTipExecutor | @tipchatteam/core | Paymaster-sponsored (zero gas) |

API Reference

TipChatClient

| Method | Description | |--------|-------------| | authenticate() | Perform wallet signature auth and obtain a session token | | listConversations(limit?, offset?) | List conversations for the authenticated wallet | | createDirectConversation(input) | Start a 1:1 conversation | | createGroupConversation(input) | Start a group conversation | | listMessages(conversationId, options?) | Fetch paginated messages | | sendMessage(conversationId, request) | Send a message | | sendMessageOptimistic(conversationId, request) | Send with instant optimistic result | | sendTipMessage(input) | Execute an on-chain tip and post the tip message | | addReaction(messageId, request) | Add an emoji reaction | | removeReaction(messageId, emoji) | Remove an emoji reaction | | markConversationRead(conversationId) | Mark a conversation as read | | sendTypingIndicator(conversationId) | Broadcast typing status | | watchMessages(conversationId, onMessage, options?) | Subscribe to real-time messages (returns unsubscribe fn) |

Chain Utilities

| Export | Description | |--------|-------------| | CHAINS | Registry of supported chains (Base, Ethereum, Optimism, etc.) | | getChain(name) | Look up chain config by name | | getSupportedChains() | List all supported chains | | explorerTxUrl(chainName, txHash) | Build a block explorer link |

Moderation

| Export | Description | |--------|-------------| | ModerationService / createModerationService(config) | Content moderation with configurable rules | | DEFAULT_MODERATION_CONFIG | Sensible defaults for content filtering |

Billing

Pass one of:

• apiKey -- sends X-TipChat-Api-Key header
• billingToken -- sends Authorization: Bearer ... header (can be a string or async function)

Documentation

Full documentation and guides are available at tipchat.dev.

License

MIT