@series-inc/venus-sdk 2.2.0

package/README.md

@@ -0,0 +1,716 @@
+# 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.
+
+## Installation
+
+```bash
+npm install venus-sdk
+```
+
+## Architecture
+
+The Venus SDK is built on a client-server RPC architecture:
+
+- **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
+
+### Core Components
+
+```typescript
+import { createHost, VenusAPI } from 'venus-sdk'
+
+// Create Venus API instance
+const venusApi = new VenusAPI()
+await venusApi.initializeAsync()
+
+// Create Host (false = remote, true = mock)
+const host = createHost(venusApi, false)
+await host.initialize()
+```
+
+## API Reference
+
+### Simulation API
+
+The Simulation API manages game state, recipe execution, and slot systems.
+
+#### State Management
+
+```typescript
+// Get current simulation state
+const state = await host.simulation.getStateAsync(roomId?)
+// Returns: { entities, inventory, currencies, timers, etc. }
+
+// Get simulation configuration
+const config = await host.simulation.getConfigAsync(roomId?)
+```
+
+#### Recipe Execution
+
+Recipes are server-authoritative game actions (crafting, battles, upgrades, etc.):
+
+```typescript
+// Execute a recipe
+const result = await host.simulation.executeRecipeAsync(
+  'craft_sword',
+  { materials: ['iron', 'wood'] },
+  { skipNotification: false }
+)
+
+// Execute a scoped recipe (entity-specific)
+const result = await host.simulation.executeScopedRecipeAsync(
+  'upgrade_weapon',
+  'sword_123',
+  { level: 5 }
+)
+
+// Get active recipe runs (for time-based recipes)
+const runs = await host.simulation.getActiveRunsAsync()
+
+// Collect completed recipe
+const result = await host.simulation.collectRecipeAsync(runId)
+
+// Trigger recipe chain
+await host.simulation.triggerRecipeChainAsync('battle_complete')
+```
+
+#### Recipe Requirements
+
+```typescript
+// Check requirements for a single recipe
+const requirements = await host.simulation.getRecipeRequirementsAsync({
+  recipeId: 'craft_sword',
+  entity: 'player',
+  amount: 1
+})
+// Returns: { canAfford, costs, rewards }
+
+// Batch check multiple recipes
+const results = await host.simulation.getBatchRecipeRequirementsAsync([
+  { recipeId: 'craft_sword', amount: 1 },
+  { recipeId: 'craft_shield', amount: 2 }
+])
+
+// Get available recipes
+const recipes = await host.simulation.getAvailableRecipesAsync({
+  roomId: 'room_123',
+  includeActorRecipes: true
+})
+```
+
+#### Slot Management
+
+Slots represent equipment, loadouts, teams, or any item container system:
+
+```typescript
+// Get all slot containers
+const containers = await host.simulation.getSlotContainersAsync()
+// Returns: [{ id: 'equipment', slots: [...] }, { id: 'team', slots: [...] }]
+
+// Get slot assignments for a container
+const assignments = await host.simulation.getSlotAssignmentsAsync('equipment')
+// Returns: [{ slotId: 'weapon', itemId: 'sword_123' }, ...]
+
+// Assign item to slot
+await host.simulation.assignItemToSlotAsync('equipment', 'weapon', 'sword_123')
+
+// Remove item from slot
+await host.simulation.removeItemFromSlotAsync('equipment', 'weapon')
+
+// Get available items for a slot
+const items = await host.simulation.getAvailableItemsAsync('equipment', 'weapon')
+
+// Preview power calculation before assignment
+const preview = await host.simulation.calculatePowerPreviewAsync(
+  'equipment',
+  'weapon',
+  'sword_456'
+)
+// Returns: { currentPower: 100, newPower: 150, delta: +50 }
+
+// Validate slot assignment
+const valid = await host.simulation.validateSlotAssignmentAsync(
+  'equipment',
+  'weapon',
+  'shield_123' // Wrong type
+)
+// Returns: { valid: false, reason: 'Type mismatch' }
+
+// Batch operations (atomic)
+await host.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 host.simulation.resolveFieldValueAsync(
+  'player_123',
+  'stats.power',
+  'player'
+)
+
+// Get entity metadata
+const metadata = await host.simulation.getEntityMetadataAsync('sword_123')
+```
+
+#### Utility Methods
+
+```typescript
+// Sum stat contributions
+const totalPower = host.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 host.deviceCache.set('lastUserId', '12345')
+const userId = await host.deviceCache.get('lastUserId')
+
+// App Storage - app-specific persistent storage
+await host.appStorage.set('highScore', 1000)
+await host.appStorage.set('playerData', { level: 5, gold: 1000 })
+
+// Global Storage - shared across all apps for the user
+await host.globalStorage.set('preferences', { theme: 'dark' })
+
+// All storage APIs support:
+const value = await storage.get(key, defaultValue?)
+await storage.set(key, value)
+await storage.remove(key)
+await storage.clear()
+const count = await storage.length()
+const keyName = await storage.key(index)
+```
+
+---
+
+### Profile API
+
+```typescript
+// Get current user profile
+const profile = await host.profile.getCurrentProfile()
+// Returns: { id, name, username }
+```
+
+---
+
+### Ads API
+
+```typescript
+// Check ad readiness
+const interstitialReady = await host.ads.isInterstitialReady()
+const rewardedReady = await host.ads.isRewardedReady()
+
+// Show interstitial ad
+await host.ads.showInterstitial()
+
+// Show rewarded video ad
+const watched = await host.ads.showRewarded()
+if (watched) {
+  // User watched the full video, grant reward
+}
+```
+
+---
+
+### Haptics API
+
+Trigger haptic feedback on supported devices:
+
+```typescript
+// Available haptic types: 'light', 'medium', 'heavy', 'success', 'warning', 'error'
+await host.haptics.trigger('success')
+await host.haptics.trigger('warning')
+await host.haptics.trigger('heavy')
+```
+
+---
+
+### Popups API
+
+Display native-style UI popups:
+
+```typescript
+// Toast messages
+await host.popups.showToast('Game saved!', {
+  duration: 3000,
+  variant: 'success',
+  action: { label: 'Undo' }
+})
+
+// Alert dialog
+await host.popups.showAlert({
+  title: 'Warning',
+  message: 'This action cannot be undone',
+  buttonText: 'OK'
+})
+
+// Confirm dialog
+const confirmed = await host.popups.showConfirm({
+  title: 'Delete Item',
+  message: 'Are you sure you want to delete this item?',
+  confirmText: 'Delete',
+  cancelText: 'Cancel'
+})
+
+if (confirmed) {
+  // User confirmed
+}
+
+// Action sheet
+const selected = await host.popups.showActionSheet({
+  title: 'Choose Action',
+  options: [
+    { id: 'edit', label: 'Edit', variant: 'default' },
+    { id: 'share', label: 'Share', variant: 'default' },
+    { id: 'delete', label: 'Delete', variant: 'destructive' }
+  ],
+  cancelText: 'Cancel'
+})
+
+if (selected === 'delete') {
+  // User selected delete
+}
+```
+
+---
+
+### Navigation API
+
+Stack-based navigation system:
+
+```typescript
+// Get current stack information
+const stack = await host.navigation.getStackInfo()
+// Returns: { depth, currentApp, history }
+
+// Push new app to stack
+await host.navigation.push({
+  appId: 'bird-flap',
+  context: { level: 5, difficulty: 'hard' }
+})
+
+// Pop from stack (returns to previous app)
+await host.navigation.pop()
+```
+
+---
+
+### Post API
+
+Social interaction APIs for posts:
+
+```typescript
+// Get post interaction data
+const interactions = await host.post.getInteractions()
+// Returns: { postId, isLiked, isFollowing, likeCount, commentCount }
+
+// Toggle like
+await host.post.toggleLike()
+
+// Toggle follow
+await host.post.toggleFollow()
+
+// Open comments UI
+await host.post.openComments()
+
+// Share post
+await host.post.share({
+  message: 'Check this out!',
+  recipientIds: ['user1', 'user2']
+})
+```
+
+---
+
+### AI API
+
+LLM integration for chat completions:
+
+```typescript
+// Get available models
+const models = await host.ai.getAvailableModels()
+// Returns: ['gpt-4', 'gpt-3.5-turbo', 'claude-3-opus', ...]
+
+// Chat completion
+const response = await host.ai.chatCompletion({
+  messages: [
+    { role: 'system', content: 'You are a helpful game assistant' },
+    { role: 'user', content: 'What is the best strategy for this level?' }
+  ],
+  model: 'gpt-4',
+  temperature: 0.7,
+  max_tokens: 500
+})
+
+console.log(response.choices[0].message.content)
+```
+
+---
+
+### Analytics API
+
+```typescript
+// Log custom event
+await host.analytics.logEvent('level_complete', {
+  level: 5,
+  score: 1000,
+  timeElapsed: 120
+})
+
+// Set user properties
+await host.analytics.setUserProperty('vip_status', 'gold')
+```
+
+---
+
+### Avatar 3D API
+
+```typescript
+// Get current avatar configuration
+const avatar = await host.avatar3d.get()
+
+// Show avatar editor
+const result = await host.avatar3d.showEditor({
+  allowSave: true,
+  enableSharing: true
+})
+
+if (result.saved) {
+  console.log('Avatar updated:', result.avatarId)
+}
+
+// Delete avatar
+await host.avatar3d.delete()
+
+// Get shared avatar
+const sharedAvatar = await host.avatar3d.getSharedAvatar('avatar_123')
+
+// Download avatar manifest
+const manifest = await host.avatar3d.downloadManifest('avatar_123')
+```
+
+---
+
+### Rooms API
+
+Multi-user room management:
+
+```typescript
+// Get current room
+const room = await host.rooms.getCurrentRoom()
+// Returns: { id, name, participants, metadata }
+
+// Join room
+await host.rooms.join('room_123')
+
+// Leave room
+await host.rooms.leave()
+
+// Send room message
+await host.rooms.sendMessage({
+  type: 'game_action',
+  data: { action: 'move', x: 10, y: 20 }
+})
+```
+
+---
+
+### Notifications API
+
+Local push notifications:
+
+```typescript
+// Schedule notification
+await host.notifications.schedule({
+  id: 'energy_full',
+  title: 'Energy Restored!',
+  body: 'Your energy is now full. Come back to play!',
+  trigger: { type: 'time', seconds: 3600 } // 1 hour
+})
+
+// Cancel notification
+await host.notifications.cancel('energy_full')
+
+// Get all scheduled notifications
+const scheduled = await host.notifications.getAllScheduled()
+
+// Check if notifications are enabled
+const enabled = await host.notifications.isEnabled()
+
+// Enable/disable notifications
+await host.notifications.setEnabled(true)
+```
+
+---
+
+### Time API
+
+Server time synchronization and formatting:
+
+```typescript
+// Get server time
+const serverTime = await host.time.getServerTime()
+// Returns: { timestamp, timezone, formatted }
+
+// Format time with locale
+const formatted = host.time.format(Date.now(), {
+  locale: 'en-US',
+  format: 'full' // 'full', 'long', 'medium', 'short'
+})
+
+// Format number with locale
+const formatted = host.time.formatNumber(1234567.89, {
+  locale: 'en-US',
+  style: 'currency',
+  currency: 'USD'
+})
+```
+
+---
+
+### CDN API
+
+```typescript
+// Get CDN URL for an asset
+const url = await host.cdn.getAssetUrl('images/logo.png')
+
+// Upload to CDN
+const uploadUrl = await host.cdn.upload(file)
+```
+
+---
+
+### Features API
+
+Feature flags, experiments, and A/B testing:
+
+```typescript
+// Get feature flag value
+const enabled = await host.features.getFeatureFlag('new_ui_enabled')
+
+// Get feature gate (boolean flag)
+const canAccess = await host.features.getFeatureGate('beta_features')
+
+// Get experiment variant
+const experiment = await host.features.getExperiment('checkout_flow')
+// Returns: { variant: 'control' | 'variant_a' | 'variant_b', ... }
+```
+
+---
+
+### IAP API
+
+In-app purchases and virtual currency:
+
+```typescript
+// Get wallet balance
+const wallet = await host.iap.getWallet()
+// Returns: { coins: 1000, gems: 50 }
+
+// Spend currency
+const result = await host.iap.spendCurrency('coins', 100)
+if (result.success) {
+  console.log('Purchase successful')
+}
+
+// Listen for wallet updates
+host.iap.onWalletUpdate((wallet) => {
+  console.log('Wallet updated:', wallet)
+})
+```
+
+---
+
+### Lifecycle API
+
+App lifecycle event handlers:
+
+```typescript
+// Register lifecycle callbacks
+host.lifecycle.onReady(() => {
+  console.log('App ready')
+})
+
+host.lifecycle.onShow((context) => {
+  console.log('App shown', context.hudInsets)
+})
+
+host.lifecycle.onPlay((context) => {
+  console.log('App playing', context.hudInsets)
+})
+
+host.lifecycle.onPause(() => {
+  console.log('App paused')
+})
+
+host.lifecycle.onResume(() => {
+  console.log('App resumed')
+})
+
+host.lifecycle.onHidden(() => {
+  console.log('App hidden')
+})
+
+host.lifecycle.onQuit(() => {
+  console.log('App quitting')
+})
+
+// Quit the app
+await host.lifecycle.quit()
+```
+
+---
+
+### Logging API
+
+```typescript
+// Log messages
+host.logging.log('Info message', { data: 'value' })
+host.logging.error('Error message', error)
+host.logging.debug('Debug info')
+```
+
+---
+
+## Mock Mode
+
+All APIs have complete mock implementations for local development:
+
+```typescript
+import { createHost, VenusAPI } from 'venus-sdk'
+
+const venusApi = new VenusAPI()
+await venusApi.initializeAsync({ mock: true })
+
+const host = createHost(venusApi, true) // true = mock mode
+await host.initialize()
+
+// All APIs work the same, but with simulated responses
+const state = await host.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
+
+---
+
+## Related
+
+- [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)
+