@series-inc/venus-sdk 3.0.4 → 3.0.6

package/README.md

@@ -1,23 +1,21 @@
 # Venus SDK API
 
-The core API package for the Venus SDK, providing comprehensive, type-safe interfaces for building H5 games and applications on the Venus platform.
+Build connected HTML5 games that integrate deeply with the Venus platform. This package provides the client SDK used by hosted games as well as the local mock environment for development.
 
-## Installation
+## Highlights
 
-```bash
-npm install venus-sdk
-```
+- Typed APIs for Venus platform services (simulation, rooms, analytics, ads, and more)
+- Host-aware tooling including lifecycle hooks, safe-area utilities, and asset loading helpers
 
-## Architecture
+## Quick Start
 
-The Venus SDK is built on a client-server RPC architecture:
+### Installation
 
-- **Host Interface** - Main entry point grouping all APIs
-- **RPC Transport** - Message-based communication with Venus platform
-- **Mock Implementations** - Complete mock APIs for local development
-- **Venus API** - Low-level platform interface
+```bash
+npm install @series-inc/venus-sdk@latest
+```
 
-### Usage
+### Initialize
 
 ```typescript
 import { default as VenusAPI } from '@series-inc/venus-sdk/api'
@@ -26,973 +24,10 @@ import { default as VenusAPI } from '@series-inc/venus-sdk/api'
 await VenusAPI.initializeAsync()
 ```
 
-## API Overview
-
-### Profile API
-
-```typescript
-// Get current user profile (synchronous)
-const profile = VenusAPI.profile.getCurrentProfile()
-console.log(profile.name, profile.username)
-```
----
-
-### Safe Area & HUD Insets
-
-```typescript
-// Static safe area from initialization (baseline padding)
-const safeArea = VenusAPI.config.ui.safeArea
-layout.style.paddingTop = `${safeArea.top}px`
-layout.style.paddingBottom = `${safeArea.bottom}px`
-
-// Dynamic HUD insets arrive with lifecycle events
-VenusAPI.lifecycle.onShow(({ hudInsets }) => {
-  applyInsets(hudInsets, 'preview')
-})
-
-VenusAPI.lifecycle.onPlay(({ hudInsets }) => {
-  applyInsets(hudInsets, 'fullscreen')
-})
-
-function applyInsets(insets, mode) {
-  // Use whichever inset is larger to avoid overlap with host UI
-  const top = Math.max(VenusAPI.config.ui.safeArea.top, insets.top)
-  canvas.style.paddingTop = `${top}px`
-  canvas.dataset.mode = mode
-}
-```
-
-`safeArea` provides a static baseline defined at initialization. `hudInsets` reflect the live host UI chrome and differ between preview (`onShow`) and fullscreen (`onPlay`) contexts.
-
----
-
-### Ads API
-
-```typescript
-// Check if rewarded ad is ready
-const rewardedReady = await VenusAPI.ads.isRewardedAdReadyAsync()
-
-// Show interstitial ad
-const interstitialShown = await VenusAPI.ads.showInterstitialAd()
-if (interstitialShown) {
-  // Interstitial ad was displayed
-}
-
-// Show rewarded video ad
-const rewardEarned = await VenusAPI.ads.showRewardedAdAsync()
-if (rewardEarned) {
-  // User watched the full video and earned reward
-}
-```
----
-
-### Haptics API
-
-```typescript
-// Trigger haptic feedback
-await VenusAPI.haptics.triggerHapticAsync('success')
-await VenusAPI.haptics.triggerHapticAsync('warning')
-await VenusAPI.haptics.triggerHapticAsync('error')
-await VenusAPI.haptics.triggerHapticAsync('light')
-await VenusAPI.haptics.triggerHapticAsync('medium')
-await VenusAPI.haptics.triggerHapticAsync('heavy')
-```
----
-
-### Local Notifications API
-
-```typescript
-  // Schedule a delayed notification (minimal - required params only)
-  const id = await VenusApi.notifications.scheduleAsync(
-    'Notification Title',
-    'Notification Body',
-    60 // Delay in seconds
-  )
-  
-  // Schedule with optional notification ID
-  const id = await VenusApi.notifications.scheduleAsync(
-    'Notification Title',
-    'Notification Body',
-    60,
-    'custom-notification-id'
-  )
-  
-  // Schedule with all optional settings
-  const id = await VenusApi.notifications.scheduleAsync(
-    'Notification Title',
-    'Notification Body',
-    60,
-    'custom-notification-id',
-    {
-      priority: 100,          // 0-100, default 50
-      groupId: 'reminders',   // Group related notifications
-      payload: { key: 'value' } // Custom data
-    }
-  )
-  
-  // Cancel a notification
-  await VenusApi.notifications.cancelNotification(notificationId)
-  
-  // Get all scheduled notifications
-  await VenusApi.notifications.getAllScheduledLocalNotifications()
-```
----
-
-### Loader API
-
-The preloader is opt-in by default. In order to opt in, you must add 
-```typescript
-   await VenusAPI.initializeAsync({ usePreloader: true })
-```
-
-```typescript
-    // Activating and dismissing the preloader
-    await VenusApi.preloader.showLoadScreen()
-    await VenusApi.preloader.hideLoadScreen()
-```
----
-
-### Custom Funnel Events API
-
-```typescript
-  // Record a custom analytics event
-  await VenusApi.analytics.recordCustomEvent('level_completed', {
-    level: 5,
-    score: 1250,
-    time: 45.2
-  })
-  
-  // Track funnel step with optional funnel name
-  await VenusApi.analytics.trackFunnelStep(1, 'tutorial_started', 'onboarding')
-  await VenusApi.analytics.trackFunnelStep(2, 'tutorial_completed', 'onboarding')
-```
----
-
-### IAP API
-
-```typescript
-  // get VBucks/Hard Currency balance
-  await VenusApi.iap.getHardCurrencyBalance()
-  // Spend VBucks/Hard Currency
-  await VenusApi.iap.spendCurrency('yourProductID', 3)
-  // Open Venus Store
-  await VenusApi.iap.openStore()
-  // Get Currency Icon
-  await VenusApi.iap.getCurrencyIcon()
-```
----
-
-### Saves API
-
-```typescript
-  // Get an item from storage
-  await VenusApi.storage.getItem('playerData')
-  // Set an item in storage
-  await VenusApi.storage.setItem('playerData', JSON.stringify({ level: 10 }))
-  // Remove an item from storage
-  await VenusApi.storage.removeItem('playerData')
-  // Get storage length
-  await VenusApi.storage.length()
-  // Get key at specific index
-  await VenusApi.storage.key(0)
-  // Clear all items from storage
-  await VenusApi.storage.clear()
-  // Set multiple items at once
-  await VenusApi.storage.setMultipleItems([
-    { key: 'playerData', value: JSON.stringify({ level: 10 }) },
-    { key: 'settings', value: JSON.stringify({ sound: true }) }
-  ])
-  // Remove multiple items at once
-  await VenusApi.storage.removeMultipleItems(['playerData', 'settings'])
-  // Get all items from storage
-  await VenusApi.storage.getAllItems()
-```
----
-
-### LLM API
-
-```typescript
-  // Request chat completion from AI model
-  const response = await VenusApi.ai.requestChatCompletionAsync({
-    model: 'chatGPT',
-    messages: [
-      {
-        role: 'user',
-        content: 'What is the best strategy for this level?'
-      }
-    ]
-  })
-  
-  // Get available completion models
-  const models = await VenusApi.ai.getAvailableCompletionModels()
-```
-
-### Simulation API
-
-The Simulation API manages game state, recipe execution, and slot systems.
-
-#### State Management
-
-```typescript
-// Get current simulation state
-const state = await VenusAPI.simulation.getStateAsync(roomId?)
-// Returns: { entities, inventory, currencies, timers, etc. }
-
-// Get simulation configuration
-const config = await VenusAPI.simulation.getConfigAsync(roomId?)
-```
-
-#### Recipe Execution
-
-Recipes are server-authoritative game actions (crafting, battles, upgrades, etc.):
-
-```typescript
-// Execute a recipe
-const result = await VenusAPI.simulation.executeRecipeAsync(
-  'craft_sword',
-  { materials: ['iron', 'wood'] },
-  { skipNotification: false }
-)
-
-// Execute a scoped recipe (entity-specific)
-const result = await VenusAPI.simulation.executeScopedRecipeAsync(
-  'upgrade_weapon',
-  'sword_123',
-  { level: 5 }
-)
-
-// Get active recipe runs (for time-based recipes)
-const runs = await VenusAPI.simulation.getActiveRunsAsync()
-
-// Collect completed recipe
-const result = await VenusAPI.simulation.collectRecipeAsync(runId)
-
-// Trigger recipe chain
-await VenusAPI.simulation.triggerRecipeChainAsync('battle_complete')
-```
-
-#### Recipe Requirements
-
-```typescript
-// Check requirements for a single recipe
-const requirements = await VenusAPI.simulation.getRecipeRequirementsAsync(
-  'craft_sword',
-  'player',
-  1
-)
-// Returns: { recipeId, entity, amount?, inputs, canAfford, disabled }
-
-// Batch check multiple recipes
-const results = await VenusAPI.simulation.getBatchRecipeRequirementsAsync([
-  { recipeId: 'craft_sword', batchAmount: 1 },
-  { recipeId: 'craft_shield', batchAmount: 2 }
-])
-// Returns: { success, results, errors? }
-
-// Get available recipes
-const recipes = await VenusAPI.simulation.getAvailableRecipesAsync({
-  roomId: 'room_123',
-  includeActorRecipes: true
-})
-// Returns: { success, recipes }
-```
-
-#### Slot Management
-
-Slots represent equipment, loadouts, teams, or any item container system:
-
-```typescript
-// Get all slot containers
-const containers = await VenusAPI.simulation.getSlotContainersAsync()
-// Returns: [{ id: 'equipment', slots: [...] }, { id: 'team', slots: [...] }]
-
-// Get slot assignments for a container
-const assignments = await VenusAPI.simulation.getSlotAssignmentsAsync('equipment')
-// Returns: [{ slotId: 'weapon', itemId: 'sword_123' }, ...]
-
-// Assign item to slot
-await VenusAPI.simulation.assignItemToSlotAsync('equipment', 'weapon', 'sword_123')
-
-// Remove item from slot
-await VenusAPI.simulation.removeItemFromSlotAsync('equipment', 'weapon')
-
-// Get available items for a slot
-const items = await VenusAPI.simulation.getAvailableItemsAsync('equipment', 'weapon')
-
-// Preview power calculation before assignment
-const preview = await VenusAPI.simulation.calculatePowerPreviewAsync(
-  'equipment',
-  'weapon',
-  'sword_456'
-)
-// Returns: { currentPower: 100, newPower: 150, delta: +50 }
-
-// Validate slot assignment
-const valid = await VenusAPI.simulation.validateSlotAssignmentAsync(
-  'equipment',
-  'weapon',
-  'shield_123' // Wrong type
-)
-// Returns: { valid: false, reason: 'Type mismatch' }
-
-// Batch operations (atomic)
-await VenusAPI.simulation.executeBatchOperationsAsync([
-  { type: 'assign', containerId: 'equipment', slotId: 'weapon', itemId: 'sword' },
-  { type: 'assign', containerId: 'equipment', slotId: 'armor', itemId: 'plate' },
-  { type: 'remove', containerId: 'equipment', slotId: 'boots' }
-], false) // false = execute, true = validate only
-```
-
-#### Field Resolution & Metadata
-
-```typescript
-// Resolve dynamic field values
-const value = await VenusAPI.simulation.resolveFieldValueAsync(
-  'player_123',
-  'stats.power',
-  'player'
-)
-
-// Get entity metadata
-const metadata = await VenusAPI.simulation.getEntityMetadataAsync('sword_123')
-```
----
-
-#### Utility Methods
-
-```typescript
-// Sum stat contributions
-const totalPower = VenusAPI.simulation.sumContributions(
-  [{ power: 10 }, { power: 20 }, { power: 15 }],
-  'power'
-)
-// Returns: 45
-```
-
----
-
-### Storage API
-
-Three-tier storage system with different data scopes:
-
-```typescript
-// Device Cache - persists across all apps for the device
-await VenusAPI.deviceCache.setItem('lastUserId', '12345')
-const userId = await VenusAPI.deviceCache.getItem('lastUserId')
-
-// App Storage - app-specific persistent storage
-await VenusAPI.appStorage.setItem('highScore', JSON.stringify(1000))
-await VenusAPI.appStorage.setItem('playerData', JSON.stringify({ level: 5, gold: 1000 }))
-
-// Global Storage - shared across all apps for the user
-await VenusAPI.globalStorage.setItem('preferences', JSON.stringify({ theme: 'dark' }))
-
-// All storage APIs support:
-const value = await storage.getItem(key)
-await storage.setItem(key, value)
-await storage.removeItem(key)
-await storage.clear()
-const count = await storage.length()
-const keyName = await storage.key(index)
-```
-
----
-
-
-### Popups API
-
-Display native-style UI popups:
-
-```typescript
-// Toast messages
-await VenusAPI.popups.showToast('Game saved!', {
-  duration: 3000,
-  variant: 'success',
-  action: { label: 'Undo' }
-})
-
-// Alert dialog
-await VenusAPI.popups.showAlert(
-  'Warning',
-  'This action cannot be undone',
-  { buttonText: 'OK' }
-)
-
-// Confirm dialog
-const confirmed = await VenusAPI.popups.showConfirm(
-  'Delete Item',
-  'Are you sure you want to delete this item?',
-  { confirmText: 'Delete', cancelText: 'Cancel' }
-)
-
-if (confirmed) {
-  // User confirmed
-}
-
-// Action sheet
-const selected = await VenusAPI.popups.showActionSheet(
-  [
-    { id: 'edit', label: 'Edit' },
-    { id: 'share', label: 'Share' },
-    { id: 'delete', label: 'Delete' }
-  ],
-  {
-    title: 'Choose Action',
-    cancelButtonText: 'Cancel'
-  }
-)
-
-if (selected === 'delete') {
-  // User selected delete
-}
-```
-
----
-
-### Navigation API
-
-Stack-based navigation system:
-
-```typescript
-// Get current stack information (synchronous)
-const stack = VenusAPI.navigation.getStackInfo()
-// Returns: { isInStack, stackPosition, isTopOfStack, stackDepth, parentInstanceId }
-
-// Push new app to stack
-await VenusAPI.navigation.pushApp('bird-flap', {
-  contextData: { level: 5, difficulty: 'hard' }
-})
-
-// Pop from stack (returns to previous app)
-await VenusAPI.navigation.popApp()
-```
-
----
-
-### Post API
-
-Social interaction APIs for posts:
-
-```typescript
-// Get post interaction data
-const postInfo = await VenusAPI.post.getPostInfo()
-// Returns: { isLiked, isFollowing, likesCount, commentsCount }
-
-// Toggle like
-const likeResult = await VenusAPI.post.toggleLikeAsync()
-// Returns: { isLiked, likesCount, action: 'liked' | 'unliked' }
-
-// Toggle follow
-const followResult = await VenusAPI.post.toggleFollowAsync()
-// Returns: { isFollowing, action: 'followed' | 'unfollowed' }
-
-// Open comments UI
-const commentsResult = await VenusAPI.post.openCommentsAsync()
-// Returns: { opened, commentsCount }
-
-// Share post
-const shareResult = await VenusAPI.post.sharePostAsync({
-  message: 'Check this out!',
-  title: 'My Post'
-})
-// Returns: { shared, platform, customMessage? }
-```
-
----
-
-### Analytics API
-
-```typescript
-// Log custom event
-await VenusAPI.analytics.logEvent('level_complete', {
-  level: 5,
-  score: 1000,
-  timeElapsed: 120
-})
-
-// Set user properties
-await VenusAPI.analytics.setUserProperty('vip_status', 'gold')
-```
-
----
-
-### Avatar 3D API
-
-```typescript
-// Load current avatar configuration
-const avatar = await VenusAPI.avatar3d.loadAvatar()
-// Or load a specific avatar
-const avatarConfig = await VenusAPI.avatar3d.loadAvatar('avatar_123')
-
-// Show avatar editor
-const result = await VenusAPI.avatar3d.showEditor({
-  currentAvatar: avatarConfig,
-  contextData: { source: 'settings' }
-})
-
-if (result.wasChanged && result.savedAvatarId) {
-  console.log('Avatar updated:', result.savedAvatarId)
-}
-
-// Save avatar
-const avatarId = await VenusAPI.avatar3d.saveAvatar(avatarConfig)
-
-// Delete avatar
-await VenusAPI.avatar3d.deleteAvatar()
-
-// Download avatar manifest
-const manifest = await VenusAPI.avatar3d.downloadManifest()
-
-// Download asset paths
-const assetPaths = await VenusAPI.avatar3d.downloadAssetPaths()
-```
-
----
-
-### Rooms API
-
-Multi-user room management:
-
-```typescript
-// Get current room
-const room = await VenusAPI.rooms.getCurrentRoom()
-// Returns: { id, name, participants, metadata }
-
-// Join room
-await VenusAPI.rooms.join('room_123')
-
-// Leave room
-await VenusAPI.rooms.leave()
-
-// Send room message
-await VenusAPI.rooms.sendMessage({
-  type: 'game_action',
-  data: { action: 'move', x: 10, y: 20 }
-})
-```
-
----
-
-### Time API
-
-Server time synchronization and formatting:
-
-```typescript
-// Get server time
-const serverTimeData = await VenusAPI.time.requestTimeAsync()
-// Returns: { serverTime, localTime, timezoneOffset, formattedTime, locale }
-
-// Format time with locale
-const formatted = VenusAPI.time.formatTime(Date.now(), {
-  locale: 'en-US',
-  format: 'full' // 'full', 'long', 'medium', 'short'
-})
-
-// Format number with locale
-const formattedNumber = VenusAPI.time.formatNumber(1234567.89, {
-  locale: 'en-US',
-  style: 'currency',
-  currency: 'USD'
-})
-
-// Get future time
-const futureTime = await VenusAPI.time.getFutureTimeAsync({
-  days: 1,
-  hours: 2,
-  minutes: 30
-})
-```
-
----
-
-### CDN API
-
-```typescript
-// Resolve asset URLs (synchronous)
-const assetUrl = VenusAPI.cdn.resolveAssetUrl('images/logo.png')
-const avatarUrl = VenusAPI.cdn.resolveAvatarAssetUrl('avatars/model.glb')
-const libUrl = VenusAPI.cdn.resolveSharedLibUrl('libs/helper.js')
-
-// Get CDN base URL
-const baseUrl = VenusAPI.cdn.getAssetCdnBaseUrl()
-
-// Fetch from CDN
-const response = await VenusAPI.cdn.fetchFromCdn('https://cdn.example.com/file.json')
-const blob = await VenusAPI.cdn.fetchBlob('path/to/asset.png')
-```
-
----
-
-### Features API
-
-Feature flags, experiments, and A/B testing:
-
-```typescript
-// Get feature flag value (returns boolean)
-const enabled = await VenusAPI.features.getFeatureFlag('new_ui_enabled')
-
-// Get feature gate (returns boolean)
-const canAccess = await VenusAPI.features.getFeatureGate('beta_features')
-
-// Get experiment variant
-const experiment = await VenusAPI.features.getExperiment('checkout_flow')
-// Returns: { name, ruleID, value, groupName } | null
-```
-
-### Lifecycle API
-
-App lifecycle event handlers:
-
-```typescript
-// Register lifecycle callbacks
-VenusAPI.lifecycle.onReady(() => {
-  console.log('App ready')
-})
-
-VenusAPI.lifecycle.onShow((context) => {
-  console.log('App shown', context.hudInsets)
-})
-
-VenusAPI.lifecycle.onPlay((context) => {
-  console.log('App playing', context.hudInsets)
-})
-
-VenusAPI.lifecycle.onPause(() => {
-  console.log('App paused')
-})
-
-VenusAPI.lifecycle.onResume(() => {
-  console.log('App resumed')
-})
-
-VenusAPI.lifecycle.onHidden(() => {
-  console.log('App hidden')
-})
-
-VenusAPI.lifecycle.onQuit(() => {
-  console.log('App quitting')
-})
-
-// Quit the app
-await VenusAPI.lifecycle.quit()
-```
-
----
-
-### Logging API
-
-```typescript
-// Log messages
-VenusAPI.logging.log('Info message', { data: 'value' })
-VenusAPI.logging.error('Error message', error)
-VenusAPI.logging.debug('Debug info')
-```
-
----
-
-### Leaderboard API (BETA)
-
-Competitive leaderboards with anti-cheat, multiple modes, and time periods.
-
-#### API Methods
-
-```typescript
-// Start a leaderboard session
-const session = await VenusAPI.leaderboard.startRunAsync({
-  mode: 'classic' // Optional: 'classic', 'hard', etc. Defaults to 'default'
-})
-// Returns: { sessionId, startTime, expiresAt, hashNonce?, mode }
-
-// Submit a score (within 1 hour of starting session)
-const result = await VenusAPI.leaderboard.submitScoreAsync({
-  sessionId: session.sessionId,
-  score: 1500,
-  durationSec: 120,
-  mode: 'classic', // Optional: must match session mode
-  metadata: { // Optional: game-specific data (max 20KB)
-    levelCompleted: 10,
-    powerUpsUsed: 3
-  },
-  telemetry: { // Optional: anti-cheat data (max 2KB, primitives only)
-    clickCount: 245,
-    avgReactionTime: 0.32
-  },
-  hash: computedHash // Required if leaderboard uses hash verification
-})
-// Returns: { accepted, rank, zScore, isAnomaly }
-
-// Get leaderboard (paginated)
-const leaderboard = await VenusAPI.leaderboard.getLeaderboardAsync({
-  mode: 'classic',      // Optional: game mode
-  period: 'daily',      // Optional: 'daily', 'weekly', 'monthly', 'alltime'
-  periodDate: Date.now(), // Optional: specific period to view
-  limit: 50,            // Optional: entries per page (max 50)
-  cursor: nextCursor    // Optional: for pagination
-})
-// Returns: { 
-//   variant: 'standard',
-//   entries: [{ profileId, username, avatarUrl, score, rank, ... }],
-//   totalEntries: 1234,
-//   nextCursor: 'abc123...',
-//   playerRank: 42,
-//   periodInstance: 'daily_2025-11-04'
-// }
-
-// Get leaderboard highlight (top players + context around you)
-const highlight = await VenusAPI.leaderboard.getLeaderboardHighlightAsync({
-  mode: 'classic',
-  period: 'daily',
-  topCount: 3,        // Top N players (podium)
-  contextAhead: 4,    // Players ahead of you
-  contextBehind: 2    // Players behind you
-})
-// Returns: {
-//   variant: 'highlight',
-//   entries: [...],
-//   context: {
-//     topEntries: [...],      // Top 3
-//     beforePlayer: [...],    // 4 players ahead
-//     playerEntry: {...},     // Your entry
-//     afterPlayer: [...],     // 2 players behind
-//     omittedBefore: 35,      // Gap between top 3 and you
-//     omittedAfter: 100       // Players below you
-//   },
-//   playerRank: 42,
-//   totalEntries: 150
-// }
-
-// Get player stats
-const stats = await VenusAPI.leaderboard.getPlayerStatsAsync({
-  mode: 'classic',
-  period: 'daily'
-})
-// Returns: {
-//   rank: 42,
-//   score: 1500,
-//   totalPlayers: 150,
-//   percentile: 0.72,  // 72nd percentile
-//   trustScore: 85,
-//   periodInstance: 'daily_2025-11-04'
-// }
-```
-
-#### Configuration
-
-Add a `leaderboard` object to your game's `config.json` file:
-
-```json
-{
-  "leaderboard": {
-    "isDisabled": false,
-    "disabledMessage": "Leaderboards are temporarily unavailable.",
-    "requiresHash": true,
-    "hashSecret": "your-secret-key-change-in-production",
-    "scoringFields": ["score", "durationSec", "sessionId"],
-    "minDurationSec": 10,
-    "maxDurationSec": 600,
-    "minScore": 0,
-    "maxScore": 999999999,
-    "modes": {
-      "default": {
-        "displayName": "Classic Mode"
-      },
-      "hard": {
-        "displayName": "Hard Mode",
-        "minDurationSec": 5,
-        "maxDurationSec": 300
-      }
-    },
-    "periods": {
-      "daily": {
-        "displayName": "Daily",
-        "type": "daily"
-      },
-      "alltime": {
-        "displayName": "All Time",
-        "type": "alltime"
-      }
-    },
-    "antiCheat": {
-      "enableZScoreDetection": false,
-      "zScoreThreshold": 3,
-      "enableRateLimit": true,
-      "minTimeBetweenSubmissionsSec": 60,
-      "trustScoreDecayPerFlag": 10,
-      "shadowBanThreshold": 20
-    },
-    "displaySettings": {
-      "maxEntriesPerPage": 50
-    },
-    "seedEntries": {
-      "default": {
-        "daily": [
-          {
-            "score": 18500,
-            "username": "ProPlayer",
-            "avatarUrl": null,
-            "durationSec": 180
-          },
-          {
-            "score": 15200,
-            "username": "Challenger",
-            "avatarUrl": null,
-            "durationSec": 210
-          }
-        ]
-      }
-    }
-  }
-}
-```
-
-**Configuration Options:**
-
-- `isDisabled`: Globally disable leaderboards
-- `requiresHash`: Enable HMAC-based score verification (recommended for production)
-- `hashSecret`: Secret key for HMAC verification (keep this secure!)
-- `scoringFields`: Fields included in hash verification (can include nested fields like `metadata.level`)
-- `minDurationSec` / `maxDurationSec`: Valid gameplay duration range
-- `minScore` / `maxScore`: Valid score bounds
-- `modes`: Game modes (can override min/max values per mode)
-- `periods`: Time periods for leaderboards (`daily`, `weekly`, `monthly`, `alltime`)
-- `antiCheat`: Anti-cheat settings
-- `seedEntries`: Pre-populate leaderboards with NPC scores (nested by mode → period)
-
-**Features:**
-- **Multiple Modes**: Support different game modes (classic, hard, etc.)
-- **Time Periods**: Daily, weekly, monthly, and all-time leaderboards
-- **Anti-Cheat**: Session validation, rate limiting, hash verification, z-score anomaly detection
-- **Shadow Banning**: Cheaters see their own scores but are hidden from others
-- **Trust Scores**: Per-player reputation that decays with suspicious behavior
-- **Seed Entries**: Pre-populate leaderboards with NPC scores
-- **Pagination**: Cursor-based pagination for large leaderboards
-- **UTC-Based Periods**: All players globally compete in same daily/weekly/monthly periods
-
-**Security Notes:**
-- Session tokens expire after 1 hour and can only be used once to prevent replay attacks
-- Use `requiresHash: true` in production with a strong `hashSecret`
-- Keep `hashSecret` out of version control (use environment variables or local config)
-- Store `hashSecret` in `config.local.json` (gitignored) for local development
-
----
-
-## Mock Mode
-
-All APIs have complete mock implementations for local development:
-
-```typescript
-import { default as VenusAPI } from '@series-inc/venus-sdk/api'
-
-await VenusAPI.initializeAsync({ mock: true })
-
-// All APIs work the same, but with simulated responses
-const state = await VenusAPI.simulation.getStateAsync()
-```
-
-### Custom Mock Data
-
-```typescript
-await VenusAPI.initializeAsync({
-  mock: {
-    simulation: {
-      state: { customData: 'value' }
-    },
-    profile: {
-      name: 'Test User',
-      username: 'test_user'
-    }
-  }
-})
-```
-
----
-
-## RPC Transport
-
-The SDK uses an RPC (Remote Procedure Call) architecture for communication:
-
-```typescript
-import { RpcClient, VenusTransport } from 'venus-sdk'
-
-// Low-level RPC client
-const transport = new VenusTransport()
-const rpcClient = new RpcClient(transport)
-
-// Send request
-const response = await rpcClient.request({
-  method: 'simulation.getState',
-  params: { roomId: 'room_123' }
-})
-```
-
----
-
-## Build Configuration
-
-The package is built with `tsup` and provides multiple module formats:
-
-```json
-{
-  "main": "./dist/index.cjs",
-  "module": "./dist/index.mjs",
-  "types": "./dist/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.mjs",
-      "require": "./dist/index.cjs"
-    },
-    "./api": {
-      "types": "./dist/venus-api/index.d.ts",
-      "import": "./dist/venus-api/index.mjs",
-      "require": "./dist/venus-api/index.cjs"
-    }
-  }
-}
-```
-
----
-
-## TypeScript Configuration
-
-The package uses TypeScript 5.9+ with strict type checking:
-
-```json
-{
-  "compilerOptions": {
-    "strict": true,
-    "target": "ES2020",
-    "module": "ESNext",
-    "moduleResolution": "bundler"
-  }
-}
-```
-
----
-
-## Testing
-
-```bash
-# Run unit tests
-npm test
-
-# Run tests in watch mode
-npm test -- --watch
-```
-
-Tests are written using Jest with JSDOM environment for browser API simulation.
-
----
-
-## License
-
-MIT
-
----
+## Documentation
 
-## Related
+The complete Venus SDK manuals live on [Venus Docs](https://series-1.gitbook.io/getreel-docs). Start there for setup guides, API references, tutorials, and best practices.
 
-- [Main Repository](https://github.com/SeriesAI/venus-sdk)
-- [npm Package](https://www.npmjs.com/package/venus-sdk)
-- [Issue Tracker](https://github.com/SeriesAI/venus-sdk/issues)
+## Support & Links
 
+- [Join our Discord!](https://discord.gg/NcjhKQHx)