@gala-chain/launchpad-sdk 5.0.2-beta.1 → 5.0.4-beta.0

package/EXAMPLES.md

@@ -15,6 +15,7 @@ Practical code examples for common SDK operations organized by category. For com
 - [DEX Leaderboard & Volume Analytics](#dex-leaderboard--volume-analytics)
 - [Fee Generation & Collection](#fee-generation--collection)
 - [Real-Time Monitoring](#real-time-monitoring)
+- [Streaming & Chat](#streaming--chat)
 - [Utilities](#utilities)
 - [Error Handling](#error-handling)
 
@@ -761,6 +762,121 @@ setTimeout(() => {
 
 ---
 
+## Streaming & Chat
+
+Live streaming and real-time chat features for token communities.
+
+### Basic Stream Management
+
+```typescript
+const sdk = createLaunchpadSDK({
+  environment: 'production',
+  privateKey: process.env.WALLET_PRIVATE_KEY,
+  streamWebSocketUrl: 'wss://stream.example.com'
+});
+
+// Get stream info for a token
+const streamInfo = await sdk.getStreamInfo('mytoken');
+console.log(`Status: ${streamInfo.status}`);
+console.log(`Is Live: ${streamInfo.isLive}`);
+
+// Check global streaming status
+const globalStatus = await sdk.getGlobalStreamingStatus();
+console.log(`Streaming enabled globally: ${globalStatus.enabled}`);
+```
+
+### Engagement Statistics
+
+```typescript
+// Get engagement metrics for analytics dashboards
+const stats = await sdk.getEngagementStats({ tokenName: 'mytoken' });
+
+console.log('Chat Statistics (Current/Last Session):');
+console.log(`  Message Count: ${stats.chat.messageCount}`);
+console.log(`  Unique Chatters: ${stats.chat.uniqueChatters}`);
+console.log(`  Session Since: ${stats.chat.since || 'N/A'}`);
+
+console.log('Comment Statistics (All-Time):');
+console.log(`  Total Comments: ${stats.comments.count}`);
+console.log(`  Unique Commenters: ${stats.comments.uniqueCommenters}`);
+```
+
+### Real-Time Chat with WebSocket
+
+```typescript
+// Connect to stream WebSocket with event handlers
+await sdk.connectStreamWebSocket({
+  onTypingIndicator: (event) => {
+    const count = event.typingUsers.length;
+    if (count === 1) {
+      console.log(`${event.typingUsers[0].fullName} is typing...`);
+    } else if (count > 1) {
+      console.log(`${count} people are typing...`);
+    }
+  },
+  onChatMessage: (event) => {
+    console.log(`[${event.message.user?.fullName}]: ${event.message.content}`);
+  }
+});
+
+// Subscribe to a stream
+await sdk.subscribeToStream('mytoken');
+
+// Send typing indicators
+sdk.sendTypingStart('mytoken');
+// ... user types ...
+sdk.sendTypingStop('mytoken');
+
+// Send a message via WebSocket
+await sdk.sendStreamChatViaWebSocket('mytoken', 'Hello everyone!');
+
+// Cleanup
+await sdk.unsubscribeFromStream('mytoken');
+await sdk.disconnectStreamWebSocket();
+```
+
+### Typing Indicators
+
+```typescript
+// Typing indicators are ephemeral (not persisted)
+// Auto-expire after 5 seconds of inactivity
+
+// Start typing indicator
+sdk.sendTypingStart('mytoken');
+
+// Stop typing indicator (or wait for auto-expire)
+sdk.sendTypingStop('mytoken');
+
+// Handle typing events from other users
+await sdk.connectStreamWebSocket({
+  onTypingIndicator: (event) => {
+    // event.typingUsers: TypingUser[]
+    // Each user has: userAddress, fullName, profileImage?
+    const names = event.typingUsers.map(u => u.fullName);
+    if (names.length === 0) {
+      console.log('No one is typing');
+    } else if (names.length === 1) {
+      console.log(`${names[0]} is typing...`);
+    } else if (names.length === 2) {
+      console.log(`${names[0]} and ${names[1]} are typing...`);
+    } else {
+      console.log('Several people are typing...');
+    }
+  }
+});
+```
+
+**Streaming & Chat Demos (5 total):**
+- `npm run demo:streaming` - Basic stream management
+- `npm run demo:streaming:recordings` - Recording management
+- `npm run demo:streaming:simulcast` - Simulcast target management
+- `npm run demo:streaming:engagement` - Engagement statistics
+- `npm run demo:chat` - REST chat operations
+- `npm run demo:chat:websocket` - WebSocket real-time chat
+- `npm run demo:chat:typing-indicators` - Typing indicator demo
+
+---
+
 ## Utilities
 
 ### Portfolio & Balances
@@ -957,28 +1073,46 @@ See the `examples/` directory for complete working demos organized by category:
 
 ```
 examples/
-├── core/              # 5 demos - SDK fundamentals
+├── api-keys/          # 2 demos - API key management
+├── bans/              # 1 demo - User ban management
 ├── bonding-curve/     # 8 demos - Pre-graduation trading
-├── liquidity/         # 12 demos - LP position management
+├── bridge/            # 23 demos - Cross-chain bridging
+├── chat/              # 3 demos - REST & WebSocket chat
+├── content-flags/     # 1 demo - Content flag management
+├── core/              # 6 demos - SDK fundamentals
 ├── dex/               # 8 demos - DEX trading & leaderboard
 ├── fees/              # 5 demos - Fee workflows
+├── liquidity/         # 12 demos - LP position management
+├── locks/             # 2 demos - Token locking
+├── moderators/        # 1 demo - Moderator invites
 ├── monitoring/        # 11 demos - Real-time events
+├── overseers/         # 1 demo - Overseer management
+├── streaming/         # 4 demos - Stream management & engagement
 ├── swap-monitoring/   # 4 demos - DEX swap watchers
-├── utilities/         # 5 demos - Helper operations
+├── utilities/         # 7 demos - Helper operations
 └── debug/             # 5 tools - Development utilities (not in npm scripts)
 ```
 
-**Total:** 65 demos covering all major SDK features
+**Total:** 99 demos covering all major SDK features (+ 5 debug tools)
 
 **Category Breakdown:**
-- **Core Operations**: 5 demos covering SDK setup, configuration, and multi-wallet testing
+- **API Key Management**: 2 demos for API key CRUD operations
+- **Ban Management**: 1 demo for user ban/unban workflows
 - **Bonding Curve Trading**: 8 demos for pre-graduation token trading (orchestrator + 7 specialized)
-- **Liquidity Management**: 12 demos for LP positions (orchestrator + 11 specialized)
+- **Cross-Chain Bridge**: 23 demos for GalaChain ↔ Ethereum/Solana bridging
+- **Chat**: 3 demos for REST chat, WebSocket chat, and typing indicators
+- **Content Flags**: 1 demo for content flag/report management
+- **Core Operations**: 6 demos covering SDK setup, configuration, and multi-wallet testing
 - **DEX Trading**: 8 demos for swaps, pools, leaderboard, and volume analytics
 - **Fee Management**: 5 demos for fee generation and collection workflows
+- **Liquidity Management**: 12 demos for LP positions (orchestrator + 11 specialized)
+- **Token Locking**: 2 demos for lock/unlock workflows
+- **Moderators**: 1 demo for moderator invite management
 - **Real-Time Monitoring**: 11 demos for pool/token creation watchers
+- **Overseers**: 1 demo for overseer management
+- **Streaming**: 4 demos for stream management, recordings, simulcast, and engagement stats
 - **Swap Monitoring**: 4 demos for DEX swap event tracking
-- **Utilities**: 5 demos for balances, cache, supply, and price history
+- **Utilities**: 7 demos for balances, cache, supply, and price history
 - **Debug Tools**: 5 development utilities (not exposed as npm scripts)
 
 For migration from old demo structure, see [docs/DEMO_MIGRATION_GUIDE.md](./docs/DEMO_MIGRATION_GUIDE.md).

package/README.md

@@ -1,6 +1,6 @@
 # Gala Launchpad SDK
 
-**Version: 4.0.17-beta.2 (Latest)**
+**Version: 5.0.3 (Latest)**
 
 A comprehensive TypeScript SDK for the Gala Launchpad Backend API, providing type-safe authentication, trading, and real-time features for DeFi applications.
 
@@ -51,9 +51,9 @@ console.log(`Last updated: ${balance.lastUpdated.toISOString()}`); // Date objec
 ```typescript
 // Get pools with direct property access
 const pools = await sdk.fetchPools({ type: 'recent' });
-console.log(pools.pools); // Direct access to pool array
-console.log(pools.total); // Immediate pagination info
-console.log(pools.hasNext); // Computed convenience properties
+console.log(pools.items); // Direct access to pool array
+console.log(pools.meta.total); // Immediate pagination info
+console.log(pools.meta.page < pools.meta.totalPages); // Has more pages
 ```
 
 ## Key Features
@@ -75,6 +75,12 @@ console.log(pools.hasNext); // Computed convenience properties
 - **Price History**: Fetch historical price data for DEX tokens with pagination (Node.js only)
 - **Cross-Chain Bridging**: Transfer tokens between GalaChain, Ethereum, and Solana with fee estimation
 - **External Wallet Balances**: Query Ethereum and Solana wallet balances (single-token or full portfolio)
+- **Live Streaming**: Start/stop streams, manage recordings and simulcast targets for token pools (v5.1.0+)
+- **Stream Chat**: Real-time chat messaging via REST and WebSocket with admin controls (v5.1.0+)
+- **Overseer System**: Global platform oversight with CCTV dashboard, invite management, and platform summary (v5.9.0+)
+- **Moderator System**: Token-scoped moderation with magic link invites (v5.7.0+)
+- **Content Flags**: Report and manage flagged content with two-tier review system (v5.8.0+)
+- **User Bans**: Per-token and global user banning with active user tracking (v5.5.0+)
 - **Comprehensive Validation**: Input validation and error handling for all operations
 - **Multi-Environment Support**: Production, staging, and custom backend URLs
 
@@ -558,8 +564,8 @@ const pools = await sdk.fetchDexPools({
   limit: 10                 // Results per page (default: 10, max: 20)
 });
 
-console.log(`Found ${pools.total} total pools`);
-console.log(`Showing ${pools.pools.length} pools on page ${pools.page}`);
+console.log(`Found ${pools.meta.total} total pools`);
+console.log(`Showing ${pools.items.length} pools on page ${pools.meta.page}`);
 
 // Fetch ALL pools with automatic pagination
 const allPools = await sdk.fetchAllDexPools({
@@ -568,7 +574,7 @@ const allPools = await sdk.fetchAllDexPools({
   sortOrder: 'asc'
 });
 
-console.log(`Retrieved ${allPools.pools.length} total pools`);
+console.log(`Retrieved ${allPools.items.length} total pools`);
 ```
 
 ### Pool Data Structure
@@ -606,7 +612,7 @@ const highVolumePoolsAsc = await sdk.fetchAllDexPools({
   sortOrder: 'desc'
 });
 
-const topPool = highVolumePoolsAsc.pools[0];
+const topPool = highVolumePoolsAsc.items[0];
 console.log(`Highest volume pair: ${topPool.poolPair}`);
 console.log(`24h Volume: $${topPool.volume1d}`);
 console.log(`APR: ${topPool.apr1d.toFixed(2)}%`);
@@ -620,7 +626,7 @@ const galaPools = await sdk.fetchDexPools({
   limit: 20
 });
 
-galaPools.pools.forEach(pool => {
+galaPools.items.forEach(pool => {
   console.log(`${pool.poolPair}: $${pool.tvl.toLocaleString()} TVL`);
 });
 ```
@@ -633,7 +639,7 @@ const liquidityOpportunities = await sdk.fetchAllDexPools({
 });
 
 // Find pools with highest APR
-const bestAprPools = liquidityOpportunities.pools.slice(0, 10);
+const bestAprPools = liquidityOpportunities.items.slice(0, 10);
 bestAprPools.forEach(pool => {
   console.log(`${pool.poolPair}: ${pool.apr1d.toFixed(2)}% APR`);
 });
@@ -654,13 +660,13 @@ The SDK enforces a **maximum of 20 items per page** (backend limit). Use `fetchA
 ```typescript
 // Page-by-page discovery (20 max per page)
 const page1 = await sdk.fetchDexPools({ page: 1, limit: 20 });
-console.log(`Page 1: ${page1.pools.length} pools`);
-console.log(`Total pages: ${page1.totalPages}`);
-console.log(`Has next: ${page1.hasNext}`);
+console.log(`Page 1: ${page1.items.length} pools`);
+console.log(`Total pages: ${page1.meta.totalPages}`);
+console.log(`Has next: ${page1.meta.page < page1.meta.totalPages}`);
 
 // Automatic pagination - get all at once
 const allAtOnce = await sdk.fetchAllDexPools();
-console.log(`All pools: ${allAtOnce.pools.length}`);
+console.log(`All pools: ${allAtOnce.items.length}`);
 ```
 
 ### Development vs Production Environments
@@ -811,7 +817,7 @@ claude mcp add "galachain-launchpad-readonly" -- env ENVIRONMENT=development npx
 - `DEBUG` - Enable debug logging: `true` | `false` (default: false)
 - `TIMEOUT` - Request timeout in milliseconds (default: 30000)
 
-**Features**: 57 tools for complete Gala Launchpad operations including:
+**Features**: 224 tools for complete Gala Launchpad operations including:
 - Pool management, pricing, and token discovery
 - Token trading with slippage protection
 - Token creation and management
@@ -835,7 +841,7 @@ See: [MCP Server Documentation](../../mcp-server/README.md)
 Need help with SDK integration, trading bots, or MCP server development?
 
 Ask **[@agent-galachain-launchpad-developer](../../@agent-galachain-launchpad-developer.md)** - a specialized AI agent with expertise in:
-- Complete SDK API (59 methods)
+- Complete SDK API (230+ methods)
 - Optional wallet configuration and dual operational modes
 - Trading patterns and DeFi best practices
 - MCP server architecture
@@ -892,14 +898,14 @@ console.log(`Transaction ID: ${buyResult.transactionId}`);
 
 // Data & Analytics - Clean pagination
 const trades = await sdk.fetchTrades({ tokenName: 'dragnrkti' });
-console.log(`Found ${trades.total} trades`);
-console.log(`Page ${trades.page} of ${trades.totalPages}`);
-trades.trades.forEach(trade => {
+console.log(`Found ${trades.meta.total} trades`);
+console.log(`Page ${trades.meta.page} of ${trades.meta.totalPages}`);
+trades.items.forEach(trade => {
   console.log(`Trade: ${trade.tradeType} ${trade.tokenAmount} at ${trade.createdAt.toISOString()}`);
 });
 
 const comments = await sdk.fetchComments({ tokenName: 'dragnrkti' });
-console.log(`${comments.total} comments found`);
+console.log(`${comments.meta.total} comments found`);
 
 // User Operations - Direct balance access
 const galaBalance = await sdk.fetchGalaBalance();
@@ -939,22 +945,22 @@ const sdk = createLaunchpadSDK({
 // MODE 1: Single Page (backward compatible)
 // Limit <= 20: Single API call
 const recent = await sdk.fetchPools({ type: 'recent', limit: 20 });
-console.log(`Fetched ${recent.pools.length} pools in one request`);
+console.log(`Fetched ${recent.items.length} pools in one request`);
 
 // MODE 2: Multi-Page Auto-Fetch
 // Limit > 20: Automatic concurrent multi-page fetching
 const large = await sdk.fetchPools({ type: 'popular', limit: 100 });
-console.log(`Fetched ${large.pools.length} pools across multiple pages`);
+console.log(`Fetched ${large.items.length} pools across multiple pages`);
 // Internally fetches 5 pages concurrently: 20+20+20+20+20 = 100 pools
 
 // MODE 3: Infinite Fetch
 // Limit = 0: Fetches ALL available pools
 const all = await sdk.fetchPools({ limit: 0 });
-console.log(`Fetched all ${all.pools.length} pools from the platform`);
+console.log(`Fetched all ${all.items.length} pools from the platform`);
 
 // Convenience method for "fetch all" pattern
 const allRecent = await sdk.fetchAllPools({ type: 'recent' });
-console.log(`Total pools: ${allRecent.total}`);
+console.log(`Total pools: ${allRecent.meta.total}`);
 ```
 
 ### Concurrency Configuration
@@ -1005,10 +1011,10 @@ async function scanEntireMarket() {
   // Fetch all pools at once (auto-pagination handles everything)
   const allPools = await sdk.fetchAllPools({ type: 'popular' });
 
-  console.log(`Scanning ${allPools.total} pools...`);
+  console.log(`Scanning ${allPools.meta.total} pools...`);
 
   // Filter for interesting opportunities
-  const highVolume = allPools.pools.filter(pool =>
+  const highVolume = allPools.items.filter(pool =>
     parseFloat(pool.volumeGala) > 10000
   );
 
@@ -1038,6 +1044,34 @@ const specific = await sdk.fetchAllPools({ tokenName: 'anime' });
 const all = await sdk.fetchAllPools();
 ```
 
+### Stream Filtering (v5.7.0+)
+
+Filter pools by streaming activity and language:
+
+```typescript
+// Find pools with upcoming scheduled shows
+const upcomingShows = await sdk.fetchPools({ hasUpcomingShows: true });
+
+// Find pools that recently went live (last 24 hours)
+const recentlyLive = await sdk.fetchPools({ recentlyStreamed: 24 });
+
+// Find active streaming communities (last week)
+const activeCommunities = await sdk.fetchAllPools({ recentlyStreamed: 168 });
+
+// Filter by stream language (ISO 639-1 codes)
+const englishPools = await sdk.fetchPools({ language: 'en' });
+const spanishPools = await sdk.fetchPools({ language: 'es' });
+
+// Pool data includes stream stats
+const pools = await sdk.fetchPools({ type: 'popular' });
+pools.items.forEach(pool => {
+  console.log(`${pool.tokenName}:`);
+  console.log(`  Viewers: ${pool.currentViewerCount || 0}`);
+  console.log(`  Peak viewers: ${pool.peakViewerCount || 0}`);
+  console.log(`  Last streamed: ${pool.lastStreamedAt || 'Never'}`);
+});
+```
+
 ### Manual SDK Creation (Alternative)
 
 ```typescript
@@ -1076,8 +1110,8 @@ const pools = await sdk.fetchPools({
   limit: 10
 });
 
-console.log(`Found ${pools.total} pools across ${pools.totalPages} pages`);
-pools.pools.forEach(pool => {
+console.log(`Found ${pools.meta.total} pools across ${pools.meta.totalPages} pages`);
+pools.items.forEach(pool => {
   console.log(`Pool: ${pool.tokenName} created at ${pool.createdAt}`);
 });
 
@@ -1105,10 +1139,10 @@ console.log(`Transaction submitted: ${buyResult.transactionId}`);
 
 // 5. Check trade history - clean pagination
 const trades = await sdk.fetchTrades({ tokenName: 'tinyevil' });
-console.log(`Found ${trades.total} trades on page ${trades.page}`);
-console.log(`Has more pages: ${trades.hasNext}`);
+console.log(`Found ${trades.meta.total} trades on page ${trades.meta.page}`);
+console.log(`Has more pages: ${trades.meta.page < trades.meta.totalPages}`);
 
-trades.trades.forEach(trade => {
+trades.items.forEach(trade => {
   console.log(`${trade.tradeType}: ${trade.tokenAmount} at ${trade.createdAt.toISOString()}`);
 });
 
@@ -2656,11 +2690,9 @@ npm run lint
 
 ## Documentation
 
-- [SDK Method Reference](./SDK-METHOD-GRAPH.md) - Complete flat API reference
-- [Clean Result Types Migration Guide](./docs/CLEAN_RESULT_TYPES_MIGRATION.md) - Migration guide for clean result types
-- [Service Architecture Migration Guide](./docs/SERVICE_ARCHITECTURE_MIGRATION.md) - Guide for v3.1.0 service-based architecture
-- [API Reference](./docs/API-REFERENCE.md) - Complete reference for all 72 SDK methods with examples
+- [API Reference](./docs/API-REFERENCE.md) - Complete reference for all SDK methods with examples
 - [Examples](./examples/) - Code examples and demos
+- [AI Agent Guide](./docs/AI-AGENT-GUIDE.md) - Building AI agents with the Launchpad SDK
 
 ### GSwap Liquidity Operations
 
@@ -3027,7 +3059,7 @@ Please read [CONTRIBUTING.md](../../CONTRIBUTING.md) for guidelines on contribut
 
 - GitHub Issues: [Report bugs and request features](https://github.com/gala-chain/launchpad-sdk/issues)
 - Documentation: [Full documentation and examples](./docs/)
-- API Status: All 45 methods working and tested
+- API Status: All methods working and tested
 
 ---