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

package/README.md

@@ -500,6 +500,95 @@ const shareResult = await VenusAPI.post.sharePostAsync({
 
 ---
 
+### 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
@@ -575,24 +664,26 @@ await VenusAPI.rooms.sendMessage({
 
 ### Time API
 
-Server time synchronization and formatting:
+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 with locale
+// Format time (locale is automatically determined from user settings)
 const formatted = VenusAPI.time.formatTime(Date.now(), {
-  locale: 'en-US',
-  format: 'full' // 'full', 'long', 'medium', 'short'
+  dateStyle: 'full', // 'full', 'long', 'medium', 'short'
+  timeStyle: 'medium',
+  hour12: true
 })
 
-// Format number with locale
+// Format number (locale is automatically determined from user settings)
 const formattedNumber = VenusAPI.time.formatNumber(1234567.89, {
-  locale: 'en-US',
   style: 'currency',
-  currency: 'USD'
+  currency: 'USD',
+  minimumFractionDigits: 2,
+  maximumFractionDigits: 2
 })
 
 // Get future time
@@ -692,151 +783,221 @@ VenusAPI.logging.debug('Debug info')
 
 ### Leaderboard API (BETA)
 
-Competitive leaderboards with anti-cheat, multiple modes, and time periods.
+Competitive leaderboards with three security levels. Choose based on your game's requirements.
 
-#### 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 }
+#### 🟢 Simple Mode (Default - Casual Games)
 
-// Submit a score (within 1 hour of starting session)
+Submit scores directly without tokens:
+
+```typescript
+// One call - no token needed!
 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)
+  duration: 120,
+  mode: 'classic',
+  metadata: {
     levelCompleted: 10,
     powerUpsUsed: 3
   },
-  telemetry: { // Optional: anti-cheat data (max 2KB, primitives only)
+  telemetry: {
     clickCount: 245,
     avgReactionTime: 0.32
-  },
-  hash: computedHash // Required if leaderboard uses hash verification
+  }
+})
+
+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: { 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: { 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,
 })
-// 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({
+```
+
+**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',
-  topCount: 3,        // Top N players (podium)
-  contextAhead: 4,    // Players ahead of you
-  contextBehind: 2    // Players behind you
+  limit: 50,
+  cursor: nextCursor
 })
-// 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({
+
+// 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'
 })
-// Returns: {
-//   rank: 42,
-//   score: 1500,
-//   totalPlayers: 150,
-//   percentile: 0.72,  // 72nd percentile
-//   trustScore: 85,
-//   periodInstance: 'daily_2025-11-04'
-// }
 ```
 
-#### Configuration
+---
+
+#### Configuration Reference
 
 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,
+    // 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": "Classic Mode"
-      },
-      "hard": {
-        "displayName": "Hard Mode",
-        "minDurationSec": 5,
-        "maxDurationSec": 300
-      }
+      "default": { "displayName": "Normal" },
+      "hard": { "displayName": "Hard Mode" }
     },
+    
+    // Time periods
     "periods": {
-      "daily": {
-        "displayName": "Daily",
-        "type": "daily"
-      },
-      "alltime": {
-        "displayName": "All Time",
-        "type": "alltime"
-      }
+      "daily": { "displayName": "Daily", "type": "daily" },
+      "alltime": { "displayName": "All Time", "type": "alltime" }
     },
+    
+    // Anti-cheat
     "antiCheat": {
-      "enableZScoreDetection": false,
-      "zScoreThreshold": 3,
       "enableRateLimit": true,
       "minTimeBetweenSubmissionsSec": 60,
       "trustScoreDecayPerFlag": 10,
-      "shadowBanThreshold": 20
+      "shadowBanThreshold": 20,
+      "enableZScoreDetection": false,
+      "zScoreThreshold": 3
     },
+    
+    // Display
     "displaySettings": {
       "maxEntriesPerPage": 50
     },
+    
+    // Seed data (optional)
     "seedEntries": {
       "default": {
         "daily": [
           {
             "score": 18500,
             "username": "ProPlayer",
-            "avatarUrl": null,
-            "durationSec": 180
+            "duration": 180
           },
           {
             "score": 15200,
             "username": "Challenger",
-            "avatarUrl": null,
-            "durationSec": 210
+            "duration": 210
           }
         ]
       }
@@ -845,34 +1006,18 @@ Add a `leaderboard` object to your game's `config.json` file:
 }
 ```
 
-**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:**
+- **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**: 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
+- **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
 
-**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
 
 ---
 
@@ -984,9 +1129,65 @@ Tests are written using Jest with JSDOM environment for browser API simulation.
 
 ---
 
-## License
+## 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
+```
 
-MIT
+See `embeddedLibrariesManifest.ts` for library definitions and `webviewLibraryShimSource.ts` for the full shim (used on mobile).
 
 ---