@gala-chain/launchpad-sdk 5.0.4-beta.6 → 5.0.4-beta.61

package/CHANGELOG.md

@@ -1,5 +1,87 @@
 # Changelog
 
+## 6.0.0
+
+### BREAKING CHANGES
+
+- **`getStreamInfo()` method REMOVED** - Consolidated into `fetchToken()`
+  - **Removed**: v6.0.0
+  - **Status**: No longer available (previously worked in v5.x)
+  - **Replacement**: `fetchToken(tokenName)` - Returns PoolData with streaming fields
+  - **Why**: Eliminated redundant API method. Streaming fields now consolidated in PoolData response. Single `fetchToken()` call provides all token data (pool metrics + streaming info) instead of separate calls.
+  - **Impact**: MUST update code before upgrading to v6.0.0
+
+  **Migration Path:**
+  ```typescript
+  // ❌ REMOVED in v6.0.0 - NO LONGER WORKS
+  const info = await sdk.getStreamInfo('mytoken');
+  console.log(`Live: ${info.isLive}, Viewers: ${info.viewerCount}`);
+
+  // ✅ NEW (v6.0.0+) - Use fetchToken instead
+  const pool = await sdk.fetchToken('mytoken');
+  console.log(`Status: ${pool.muxStreamStatus}`); // 'IDLE' | 'ACTIVE' | 'DISABLED'
+  console.log(`Viewers: ${pool.currentViewerCount}`);
+  console.log(`Playback: ${pool.playbackId}`);
+  console.log(`Aspect Ratio: ${pool.aspectRatio}`);
+  ```
+
+  **Streaming Fields Now in PoolData**:
+  - `playbackId`: string | null (viewer playback ID)
+  - `aspectRatio`: string (e.g., "16:9", "9:16")
+  - `muxStreamStatus`: 'IDLE' | 'ACTIVE' | 'DISABLED'
+  - `nextLiveStreamAt`: string | null (ISO 8601 scheduled time)
+  - `language`: string (ISO 639-1 code, e.g., "en", "es")
+  - `streamEnabled`: boolean
+  - `currentViewerCount`: number (live viewers, v5.7.0+)
+  - `peakViewerCount`: number (peak in session, v5.7.0+)
+  - `streamStartedAt`: string | null (when stream became active, v5.7.0+)
+  - `lastStreamedAt`: string | null (last streaming timestamp, v5.7.0+)
+  - `recordingsCount`: number (total recordings, v5.8.0+)
+  - `totalSecondsStreamed`: number (cumulative duration, v5.8.0+)
+
+### New Features
+
+- **`fetchToken(tokenName)` method** - Unified token data retrieval with streaming
+  - Returns complete PoolData object with all token and streaming information
+  - Replaces separate getStreamInfo() call
+  - Single API request for all token data
+  - All streaming fields consolidated in response
+  - Streaming data always available (no separate call needed)
+  - Example: `const pool = await sdk.fetchToken('mytoken')`
+
+- **`validateToken(options)` method** - Token name/symbol validation for creation
+  - Real-time form validation support
+  - Checks name and/or symbol availability
+  - Returns blocklist status and validation errors
+  - Use cases: token creation workflows, form validation, pre-launch checks
+  - Example: `const result = await sdk.validateToken({ tokenName: 'mytoken', symbol: 'MYT' })`
+
+### Benefits
+
+- **Reduced API calls**: One `fetchToken()` call provides all data (previously required separate pool + streaming calls)
+- **Cleaner architecture**: No redundant getStreamInfo() method
+- **Better DX**: All token data in single PoolData object with type safety
+- **Form validation**: New `validateToken()` enables real-time validation for token creation
+- **Unified response**: Streaming fields integrated into standard PoolData response structure
+
+### Migration Checklist
+
+- [ ] Replace all `getStreamInfo()` calls with `fetchToken()`
+- [ ] Update streaming field access patterns (muxStreamStatus, playbackId, etc.)
+- [ ] Test pool data access for all streaming fields
+- [ ] Add `validateToken()` for token creation form validation if needed
+- [ ] Run full test suite against v6.0.0
+- [ ] Update any documentation/guides referencing old methods
+
+### Expected Impact
+
+- **Bundle size**: Minimal change (removed getStreamInfo method, added fetchToken + validateToken)
+- **API calls**: Reduced (consolidated streaming into pool fetch)
+- **Code maintenance**: Improved (unified response structure)
+- **Developer experience**: Enhanced (single method for all token data, real-time validation)
+
+---
+
 ## 4.0.0
 
 ### BREAKING CHANGES

package/EXAMPLES.md

@@ -6,6 +6,7 @@ Practical code examples for common SDK operations organized by category. For com
 
 ## Table of Contents
 
+- [Token Format Decision Tree](#token-format-decision-tree) ⭐ **READ THIS FIRST**
 - [Quick Start](#quick-start)
 - [Recommended Learning Path](#recommended-learning-path)
 - [Core Operations](#core-operations)
@@ -21,6 +22,104 @@ Practical code examples for common SDK operations organized by category. For com
 
 ---
 
+## Token Format Decision Tree
+
+**The SDK uses TWO different token identifier formats. Using the wrong one causes errors.**
+
+### Which Format Should I Use?
+
+```
+Q: What operation am I performing?
+│
+├── Buying/selling tokens on bonding curve (pre-graduation)?
+│   └── Use tokenName: sdk.buy({ tokenName: 'anime', amount: '100', type: 'native' })
+│
+├── Swapping on DEX (GALA, GUSDC, graduated tokens)?
+│   └── Use tokenClassKey: sdk.executeSwap('GALA|Unit|none|none', 'GUSDC|Unit|none|eth:0xa0b...', ...)
+│
+├── Managing liquidity positions on DEX?
+│   └── Use tokenClassKey: sdk.addSwapLiquidityByPrice({ token0: 'GALA|Unit|none|none', ... })
+│
+├── Transferring tokens?
+│   ├── Launchpad token? → sdk.transferToken({ tokenName: 'anime', ... })
+│   └── Standard GalaChain token? → sdk.transferToken({ tokenId: 'GALA|Unit|none|none', ... })
+│
+├── Checking prices?
+│   └── Either works: sdk.fetchTokenPrice({ tokenName: 'anime' })
+│                  OR sdk.fetchTokenPrice({ tokenId: 'GALA|Unit|none|none' })
+│
+└── Graduating a token from bonding curve to DEX?
+    └── Use tokenName: sdk.graduateToken({ tokenName: 'anime' })
+```
+
+### Format Reference
+
+| Format | Pattern | Example | Used For |
+|--------|---------|---------|----------|
+| **tokenName** | Simple lowercase, 3-20 chars | `'anime'` | Bonding curve ops |
+| **tokenClassKey** | `collection\|category\|type\|additionalKey` | `'GALA\|Unit\|none\|none'` | DEX ops, LP, standard tokens |
+
+### Common Well-Known Tokens
+
+```typescript
+// Standard tokens (always use tokenClassKey format)
+const GALA = 'GALA|Unit|none|none';
+const GUSDC = 'GUSDC|Unit|none|eth:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48';
+const WETH = 'GETH|Unit|none|eth:0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2';
+```
+
+### Common Mistakes Table
+
+| ❌ Wrong | ✅ Correct | Why |
+|----------|------------|-----|
+| `sdk.executeSwap('GALA', ...)` | `sdk.executeSwap('GALA\|Unit\|none\|none', ...)` | DEX requires full tokenClassKey |
+| `sdk.buy({ tokenName: 'ANIME\|Unit\|...' })` | `sdk.buy({ tokenName: 'anime' })` | Bonding curve uses simple names |
+| `sdk.getSwapQuoteExactInput('anime', ...)` | Get tokenClassKey from pool, then use it | DEX needs resolved tokenClassKey |
+| Assuming `buy()` works for graduated tokens | Check `isGraduated`, use DEX if true | Graduated tokens are on DEX |
+
+### Detecting Graduation Status
+
+```typescript
+// Check if a token has graduated from bonding curve to DEX
+const pool = await sdk.fetchPools({ tokenName: 'anime' });
+const isGraduated = pool.items[0]?.isGraduated ?? false;
+
+if (isGraduated) {
+  // Token is on DEX - get its tokenClassKey for DEX operations
+  // ⚠️ IMPORTANT: Always query for tokenClassKey - never construct it!
+  // The symbol in tokenClassKey may differ from tokenName
+  const tokenClassKey = pool.items[0]?.tokenClassKey;
+  console.log(`Use tokenClassKey for DEX: ${tokenClassKey}`);
+} else {
+  // Token is still on bonding curve - use tokenName
+  console.log('Use tokenName for bonding curve: anime');
+}
+```
+
+### Full Method Reference
+
+| Method | tokenName | tokenClassKey | Notes |
+|--------|:---------:|:-------------:|-------|
+| `buy()` | ✅ | ❌ | Bonding curve only |
+| `sell()` | ✅ | ❌ | Bonding curve only |
+| `graduateToken()` | ✅ | ❌ | Triggers DEX migration |
+| `calculateBuyAmount()` | ✅ | ❌ | Pre-trade calculation |
+| `calculateSellAmount()` | ✅ | ❌ | Pre-trade calculation |
+| `fetchPools()` | ✅ | ❌ | Query bonding curve pools |
+| `executeSwap()` | ❌ | ✅ | DEX only |
+| `getSwapQuoteExactInput()` | ❌ | ✅ | DEX quotes |
+| `getSwapQuoteExactOutput()` | ❌ | ✅ | DEX quotes |
+| `addSwapLiquidityByPrice()` | ❌ | ✅ | LP operations |
+| `removeSwapLiquidity()` | ❌ | ✅ | LP operations |
+| `fetchTokenPrice()` | ✅ | ✅ | Smart router auto-detects |
+| `transferToken()` | ✅ | ✅ | Both work (different paths) |
+| `lockTokens()` | ✅ | ✅ | Both work |
+| `fetchTokenBalance()` | ✅ | ✅ | Both work |
+
+> **See Also:** For complete type definitions and utilities, see [`src/types/token.types.ts`](./src/types/token.types.ts)
+
+---
+
 ## Quick Start
 
 ### Installation