@series-inc/venus-sdk 3.0.6 → 3.1.0-beta.0

package/README.md

@@ -1,21 +1,23 @@
 # Venus SDK API
 
-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.
+The core API package for the Venus SDK, providing comprehensive, type-safe interfaces for building H5 games and applications on the Venus platform.
 
-## Highlights
+## Installation
 
-- 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
+```bash
+npm install venus-sdk
+```
 
-## Quick Start
+## Architecture
 
-### Installation
+The Venus SDK is built on a client-server RPC architecture:
 
-```bash
-npm install @series-inc/venus-sdk@latest
-```
+- **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
 
-### Initialize
+### Usage
 
 ```typescript
 import { default as VenusAPI } from '@series-inc/venus-sdk/api'
@@ -24,10 +26,1174 @@ import { default as VenusAPI } from '@series-inc/venus-sdk/api'
 await VenusAPI.initializeAsync()
 ```
 
-## Documentation
+## 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? }
+```
+
+---
+
+### Social API (BETA)
+
+Share links and QR codes for challenges and UGC (user-generated content):
+
+```typescript
+// Share a high score challenge - automatically opens share dialog!
+const { shareUrl } = await VenusAPI.social.shareLinkAsync({
+  launchParams: {
+    challengeType: 'highscore',
+    scoreTobeat: '1500',
+    challengerId: VenusAPI.profile.getCurrentProfile().id
+  },
+  metadata: {
+    title: 'Beat my score!',
+    description: 'Can you beat 1500 points in Word Search?',
+    imageUrl: 'https://cdn.example.com/share-highscore.png'
+  }
+})
+// This function automatically triggers the share UI:
+// - iOS/Android: Opens native share sheet
+// - Web: Uses navigator.share() if available, otherwise copies to clipboard
+// The returned shareUrl is the generated link that was shared
+
+// Generate QR code for in-person challenges (does NOT open share dialog)
+const { shareUrl, qrCode } = await VenusAPI.social.createQRCodeAsync({
+  launchParams: {
+    challengeType: 'daily',
+    dailyPuzzleId: '2024-11-04',
+    invitedBy: VenusAPI.profile.getCurrentProfile().username
+  },
+  metadata: {
+    title: 'Daily Challenge',
+    description: 'Scan to play today\'s puzzle with me!'
+  },
+  qrOptions: {
+    size: 512,      // Size in pixels (default: 256)
+    margin: 4,      // Margin in modules (default: 2)
+    format: 'png'   // 'png' or 'svg'
+  }
+})
+// This only generates the QR code - you control how to display it
+
+// Display the QR code in your UI
+const img = document.createElement('img')
+img.src = qrCode // Data URL (e.g., 'data:image/png;base64,...')
+document.body.appendChild(img)
+
+// Handle incoming challenge when app opens from share
+const launchParams = VenusAPI.getLaunchParams()
+if (launchParams.challengeType === 'highscore') {
+  const targetScore = parseInt(launchParams.scoreTobeat, 10)
+  const challengerId = launchParams.challengerId
+  startHighScoreChallenge(targetScore, challengerId)
+}
+
+// Handle daily puzzle invites
+if (launchParams.challengeType === 'daily') {
+  const puzzleId = launchParams.dailyPuzzleId
+  const inviter = launchParams.invitedBy
+  loadDailyPuzzle(puzzleId, inviter)
+}
+
+// Referral system example
+if (launchParams.referredBy) {
+  await rewardReferrer(launchParams.referredBy)
+  showMessage(`You were invited by ${launchParams.referredBy}!`)
+}
+```
+
+**Launch Parameters:**
+
+Launch parameters are completely arbitrary - define whatever your game needs:
+
+Examples from the code above:
+- `challengeType`, `scoreTobeat`, `challengerId` - For beat-my-score challenges
+- `dailyPuzzleId`, `invitedBy` - For daily puzzle invites
+- `referredBy` - For referral tracking
+- `levelId`, `replayId`, `customMapId` - For UGC content
+
+All parameters are custom game data - no reserved or required fields.
+
+**Size Limits:**
+
+- **Max total size**: Keep `launchParams` under ~100KB (share data stored in Firestore with 1MB document limit)
+- **Use compact formats**: IDs and short strings work best
+- **Best practice**: Store large UGC separately and only pass an ID in `launchParams`
+
+---
+
+### 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 with automatic locale detection:
+
+```typescript
+// Get server time
+const serverTimeData = await VenusAPI.time.requestTimeAsync()
+// Returns: { serverTime, localTime, timezoneOffset, formattedTime, locale }
+
+// Format time (locale is automatically determined from user settings)
+const formatted = VenusAPI.time.formatTime(Date.now(), {
+  dateStyle: 'full', // 'full', 'long', 'medium', 'short'
+  timeStyle: 'medium',
+  hour12: true
+})
+
+// Format number (locale is automatically determined from user settings)
+const formattedNumber = VenusAPI.time.formatNumber(1234567.89, {
+  style: 'currency',
+  currency: 'USD',
+  minimumFractionDigits: 2,
+  maximumFractionDigits: 2
+})
+
+// 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 three security levels. Choose based on your game's requirements.
+
+---
+
+#### 🟢 Simple Mode (Default - Casual Games)
+
+Submit scores directly without tokens:
+
+```typescript
+// One call - no token needed!
+const result = await VenusAPI.leaderboard.submitScoreAsync({
+  score: 1500,
+  duration: 120,
+  mode: 'classic',
+  metadata: {
+    levelCompleted: 10,
+    powerUpsUsed: 3
+  },
+  telemetry: {
+    clickCount: 245,
+    avgReactionTime: 0.32
+  }
+})
+
+console.log(`Your rank: ${result.rank}`)
+```
+
+**Configuration:** None needed (uses defaults)
+
+**Security provided:**
+- ✅ Score/duration bounds validation
+- ✅ Rate limiting (60 second cooldown per player)
+- ✅ Trust scores & shadow banning for repeat offenders
+- ❌ No session replay protection
+- ❌ No tamper protection
+
+**Best for:** Simple integration
+
+---
+
+#### 🟡 Token Mode (Competitive Games)
+
+Add session validation for replay protection:
+
+```typescript
+// Step 1: Create score token
+const scoreToken = await VenusAPI.leaderboard.createScoreTokenAsync({
+  mode: 'ranked'
+})
+// Returns: { token, startTime, expiresAt, mode }
+
+// Step 2: Play game...
+
+// Step 3: Submit with token
+const result = await VenusAPI.leaderboard.submitScoreAsync({
+  token: scoreToken.token,
+  score: 1500,
+  duration: 120,
+  metadata: { ... }
+})
+```
+
+**Configuration:**
+```json
+{
+  "leaderboard": {
+    "requiresToken": true
+  }
+}
+```
+
+**Additional security:**
+- ✅ All simple mode security
+- ✅ Session validation (tokens expire in 1 hour)
+- ✅ Replay attack prevention (one-time use)
+- ✅ Mode locking (token locks game mode)
+- ❌ No tamper protection
+
+**Best for:** Preventing replay attacks
+
+---
+
+#### 🔴 Score Sealing Mode (High-Stakes Games)
+
+Add cryptographic tamper protection:
+
+```typescript
+// Step 1: Create score token (sealing data included automatically if enabled)
+const scoreToken = await VenusAPI.leaderboard.createScoreTokenAsync({
+  mode: 'tournament'
+})
+// Returns: { token, sealingNonce, sealingSecret, ... }
+
+// Step 2: Play game...
+
+// Step 3: Submit score - SDK auto-computes hash internally!
+const result = await VenusAPI.leaderboard.submitScoreAsync({
+  token: scoreToken.token,
+  score: 1500,
+  duration: 120,
+})
+```
+
+**Configuration:**
+```json
+{
+  "leaderboard": {
+    "requiresToken": true,
+    "enableScoreSealing": true,
+    "scoreSealingSecret": "your-secret-key-change-in-production"
+  }
+}
+```
+
+**Note:** Hash computation is handled internally by the SDK using Web Crypto API (HMAC-SHA256). Games never need to implement cryptographic hashing manually. The hash always includes: `score`, `duration`, and `token`.
+
+**Maximum security:**
+- ✅ All token mode security
+- ✅ Tamper-proof scores (HMAC-SHA256 verification)
+- ✅ Client-side cheat detection
+- ✅ Automatic hash computation (no crypto code needed in games)
+
+**Best for:** Reduced hacking
+
+---
+
+#### Query Methods (Same for All Modes)
+
+All query methods work identically regardless of security mode:
+
+```typescript
+// Get paginated scores
+const pagedScores = await VenusAPI.leaderboard.getPagedScoresAsync({
+  mode: 'classic',
+  period: 'daily',
+  limit: 50,
+  cursor: nextCursor
+})
+
+// Get podium + player context
+const podiumScores = await VenusAPI.leaderboard.getPodiumScoresAsync({
+  mode: 'classic',
+  period: 'daily',
+  topCount: 3,
+  contextAhead: 4,
+  contextBehind: 2
+})
+
+// Get my rank
+const rank = await VenusAPI.leaderboard.getMyRankAsync({
+  mode: 'classic',
+  period: 'daily'
+})
+```
+
+---
+
+#### Configuration Reference
+
+Add a `leaderboard` object to your game's `config.json` file:
+
+```json
+{
+  "leaderboard": {
+    // Basic settings
+    "minScore": 0,
+    "maxScore": 999999999,
+    "minDurationSec": 10,
+    "maxDurationSec": 600,
+    
+    // Security (progressive levels)
+    "requiresToken": false,           // Simple mode (default)
+    "enableScoreSealing": false,      // Requires requiresToken=true
+    "scoreSealingSecret": "secret",   // Required if enableScoreSealing=true
+    
+    // Game modes
+    "modes": {
+      "default": { "displayName": "Normal" },
+      "hard": { "displayName": "Hard Mode" }
+    },
+    
+    // Time periods
+    "periods": {
+      "daily": { "displayName": "Daily", "type": "daily" },
+      "alltime": { "displayName": "All Time", "type": "alltime" }
+    },
+    
+    // Anti-cheat
+    "antiCheat": {
+      "enableRateLimit": true,
+      "minTimeBetweenSubmissionsSec": 60,
+      "trustScoreDecayPerFlag": 10,
+      "shadowBanThreshold": 20,
+      "enableZScoreDetection": false,
+      "zScoreThreshold": 3
+    },
+    
+    // Display
+    "displaySettings": {
+      "maxEntriesPerPage": 50
+    },
+    
+    // Seed data (optional)
+    "seedEntries": {
+      "default": {
+        "daily": [
+          {
+            "score": 18500,
+            "username": "ProPlayer",
+            "duration": 180
+          },
+          {
+            "score": 15200,
+            "username": "Challenger",
+            "duration": 210
+          }
+        ]
+      }
+    }
+  }
+}
+```
+
+
+
+
+**Features:**
+- **Three Security Levels**: Simple, Token, Sealed - choose based on game stakes
+- **Multiple Modes**: Support different game modes (classic, hard, etc.)
+- **Time Periods**: Daily, weekly, monthly, and all-time leaderboards
+- **Anti-Cheat**: Rate limiting, trust scores, shadow banning, optional session validation & sealing
+- **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
+
+
+---
+
+## 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.
+
+---
+
+## Embedded Libraries (Vite)
+
+For **Vite projects**, use the included plugin to automatically reduce bundle size by using embedded libraries:
+
+```bash
+npm install @series-inc/venus-sdk
+```
+
+```typescript
+// vite.config.ts
+import { venusLibrariesPlugin } from '@series-inc/venus-sdk/vite';
+
+export default defineConfig({
+  plugins: [venusLibrariesPlugin({ appName: 'my-game' })],
+  build: { target: 'es2022' } // Required for top-level await
+});
+```
+
+**Build commands:**
+- `npm run build` → Embedded libraries (default, optimal)
+- `VENUS_DISABLE_EMBEDDED_LIBS=true npm run build` → Bundled (standalone)
+
+**Supported libraries:** Phaser, React, ReactDOM, Three.js, Matter.js, inkjs, Zustand
+
+See `src/vite/README.md` for details.
+
+### For Non-Vite Bundlers
+
+The Vite plugin does three things you can recreate in any bundler:
+
+**1. Externalize library imports** - Replace imports with virtual modules:
+```javascript
+// Input: import Phaser from 'phaser';
+// Output: const lib = await (async () => {
+//   await window.__venusLibraryShim.ready();
+//   return window.__venusLibraryExports['phaser@3.90.0'];
+// })();
+// export default lib;
+```
+
+**2. Inject config into HTML `<head>`:**
+```html
+<script>
+  window.__venusLibrariesConfig = {
+    enabled: true,
+    required: ["phaser@3.90.0"],
+    manifest: { "phaser@3.90.0": { cdnPath: "...", globalVar: "Phaser" } },
+    cdnBase: "https://venus-static-01293ak.web.app/libs/"
+  };
+</script>
+```
+
+**3. Inject minimal shim** (loads from CDN, resolves `ready()` promise):
+```javascript
+window.__venusLibraryShim = { ready: () => Promise };
+// Fetch libraries from CDN, evaluate, register in __venusLibraryExports
+```
+
+See `embeddedLibrariesManifest.ts` for library definitions and `webviewLibraryShimSource.ts` for the full shim (used on mobile).
+
+---
 
-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.
+## Related
 
-## Support & Links
+- [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)
 
-- [Join our Discord!](https://discord.gg/NcjhKQHx)