Package Exports

@evup/game-sdk
@evup/game-sdk/react
@evup/game-sdk/svelte
@evup/game-sdk/vite-plugin
@evup/game-sdk/vue
@evup/game-sdk/web-component

Readme

@evup/game-sdk

Official TypeScript SDK for integrating with EvUp game configuration service. This SDK provides type-safe access to game configurations, custom fields, and app settings from your EvUp dashboard.

🚀 Features

Type-safe: Full TypeScript support with complete type definitions
Lightweight: Built with modern tooling (UnJS) for minimal bundle size
Caching: Intelligent caching to reduce API calls
Error handling: Comprehensive error types for better debugging
Flexible: Support for nested configuration values and custom fields
Framework agnostic: Works with any JavaScript/TypeScript project

📦 Installation

npm install @evup/game-sdk

yarn add @evup/game-sdk

pnpm add @evup/game-sdk

Framework Dependencies

For framework-specific features, install the corresponding framework:

# For React hooks
npm install react

# For Vue composables  
npm install vue

# For Svelte stores
npm install svelte

Framework Imports

Each framework has its own optimized entry point:

// Vanilla JavaScript/TypeScript
import { EvUpGameSDK } from '@evup/game-sdk'

// React hooks
import { useEvUpGameSDK, useGameConfig } from '@evup/game-sdk/react'

// Vue composables
import { useEvUpGameSDK, useGameConfig } from '@evup/game-sdk/vue'

// Svelte stores
import { createEvUpGameSDK, createGameConfigStore } from '@evup/game-sdk/svelte'

🛠️ Quick Start

1. Initialize the SDK

import { EvUpGameSDK } from '@evup/game-sdk'

const sdk = new EvUpGameSDK({
  baseUrl: 'https://evup.vn', // or 'http://localhost:4000' for development
  apiKey: 'gep_your_api_key_here',
  gameId: 'your_game_id',
  version: 'latest', // optional, defaults to 'latest'
  debug: false // optional, enables debug logging
})

2. Fetch Game Configuration

// Get complete configuration
const config = await sdk.getConfig()

// Get only app configuration
const appConfig = await sdk.getAppConfig()

// Get custom configuration
const customConfig = await sdk.getCustomConfig()

3. Access Custom Values

// Get a specific custom value
const primaryColor = await sdk.getCustomValue('colors.primary', '#000000')

// Get custom data object
const customData = await sdk.getCustomData()

// Check if a field exists
const hasTheme = await sdk.hasCustomField('theme')

📋 API Reference

Constructor Options

Parameter	Type	Required	Default	Description
`baseUrl`	`string`	✅	-	EvUp server URL (e.g., `https://evup.vn`)
`apiKey`	`string`	✅	-	Game API key from EvUp dashboard
`gameId`	`string`	✅	-	Game ID from EvUp dashboard
`version`	`string`	❌	`'latest'`	Config version to fetch
`timeout`	`number`	❌	`10000`	Request timeout in milliseconds
`debug`	`boolean`	❌	`false`	Enable debug logging

Core Methods

Method	Return Type	Description
`getConfig(force?)`	`Promise<GameConfig>`	Get complete game configuration
`getAppConfig(force?)`	`Promise<GameAppConfig>`	Get application configuration
`getCustomConfig(force?)`	`Promise<CustomConfig>`	Get custom configuration
`getCustomData(force?)`	`Promise<Record<string, any>>`	Get custom field data
`getCustomValue<T>(key, default?, force?)`	`Promise<T>`	Get specific custom value
`getGameInfo(force?)`	`Promise<GameInfo>`	Get game information
`getViewportConfig(force?)`	`Promise<GameViewportConfig>`	Get viewport configuration

Utility Methods

Method	Return Type	Description
`hasCustomField(key, force?)`	`Promise<boolean>`	Check if custom field exists
`getCustomFieldKeys(force?)`	`Promise<string[]>`	Get all custom field keys
`clearCache()`	`void`	Clear cached configuration
`isCached()`	`boolean`	Check if config is cached
`getSDKInfo()`	`object`	Get SDK version and info

Configuration Types

Type	Description
`GameConfig`	Complete game configuration object
`GameAppConfig`	Application configuration (name, description, keywords)
`GameViewportConfig`	Viewport settings (width, height)
`GameInfo`	Game metadata from server
`CustomConfig`	Custom fields schema and data
`CustomFieldSchema`	Individual field schema definition

Error Types

Error	Code	Description
`EvUpSDKError`	`INVALID_OPTIONS`	Invalid initialization options
`EvUpAuthError`	`AUTH_ERROR`	Invalid API key or unauthorized
`EvUpNetworkError`	`NETWORK_ERROR`	Network request failed
`EvUpConfigNotFoundError`	`CONFIG_NOT_FOUND`	Configuration not found

💡 Usage Examples

Basic Configuration Access

import { EvUpGameSDK } from '@evup/game-sdk'

const sdk = new EvUpGameSDK({
  baseUrl: 'https://evup.vn',
  apiKey: 'gep_your_api_key',
  gameId: 'your_game_id'
})

// Get app information
const app = await sdk.getAppConfig()
console.log(`Game: ${app.name}`)
console.log(`Description: ${app.description}`)

// Get viewport settings
const viewport = await sdk.getViewportConfig()
console.log(`Size: ${viewport.width}x${viewport.height}`)

Working with Custom Fields

// Get theme configuration
const theme = await sdk.getCustomValue('theme', 'light')

// Get nested color values
const primaryColor = await sdk.getCustomValue('colors.primary', '#007bff')
const secondaryColor = await sdk.getCustomValue('colors.secondary', '#6c757d')

// Get game settings
const maxPlayers = await sdk.getCustomValue('game.maxPlayers', 4)
const difficulty = await sdk.getCustomValue('game.difficulty', 'normal')

// Check if features are enabled
const hasMultiplayer = await sdk.getCustomValue('features.multiplayer', false)
const hasAudio = await sdk.getCustomValue('features.audio', true)

Error Handling

import { 
  EvUpGameSDK, 
  EvUpAuthError, 
  EvUpNetworkError,
  EvUpConfigNotFoundError 
} from '@evup/game-sdk'

try {
  const config = await sdk.getConfig()
  // Use configuration...
} catch (error) {
  if (error instanceof EvUpAuthError) {
    console.error('Authentication failed:', error.message)
    // Handle invalid API key
  } else if (error instanceof EvUpNetworkError) {
    console.error('Network error:', error.message)
    // Handle connection issues
  } else if (error instanceof EvUpConfigNotFoundError) {
    console.error('Config not found:', error.message)
    // Handle missing configuration
  } else {
    console.error('Unknown error:', error.message)
  }
}

Caching and Performance

// Force refresh (bypass cache)
const freshConfig = await sdk.getConfig(true)

// Check cache status
if (sdk.isCached()) {
  console.log('Using cached configuration')
} else {
  console.log('Will fetch from server')
}

// Clear cache manually
sdk.clearCache()

// Get SDK information
const info = sdk.getSDKInfo()
console.log('SDK Version:', info.version)
console.log('Last fetch:', info.lastFetchTime)

Framework Integration

The SDK includes built-in integrations for React, Vue, and Svelte with optimized hooks, composables, and stores.

React Hooks

import { 
  useEvUpGameSDK, 
  useGameConfig, 
  useCustomValue,
  useEvUpGame 
} from '@evup/game-sdk/react'

function GameComponent() {
  // Initialize SDK
  const sdk = useEvUpGameSDK({
    baseUrl: 'https://evup.vn',
    apiKey: 'gep_your_api_key',
    gameId: 'your_game_id'
  })

  // Get game configuration
  const { config, loading, error, refetch } = useGameConfig(sdk)

  // Get custom values with type safety
  const { value: theme } = useCustomValue<string>(sdk, 'theme', 'light')
  const { value: maxPlayers } = useCustomValue<number>(sdk, 'game.maxPlayers', 4)

  // Combined hook for all game data
  const { appConfig, viewportConfig, customData } = useEvUpGame({
    baseUrl: 'https://evup.vn',
    apiKey: 'gep_your_api_key',
    gameId: 'your_game_id'
  })

  if (loading) return <div>Loading...</div>
  if (error) return <div>Error: {error.message}</div>

  return (
    <div>
      <h1>{appConfig?.name}</h1>
      <p>Theme: {theme}</p>
      <p>Max Players: {maxPlayers}</p>
    </div>
  )
}

Vue Composables

<script setup lang="ts">
import { 
  useEvUpGameSDK,
  useGameConfig,
  useCustomValue,
  useEvUpGame
} from '@evup/game-sdk/vue'

// Initialize SDK
const { sdk } = useEvUpGameSDK({
  baseUrl: 'https://evup.vn',
  apiKey: 'gep_your_api_key',
  gameId: 'your_game_id'
})

// Get game configuration
const { config, loading, error, refetch } = useGameConfig(sdk)

// Get custom values
const { value: theme } = useCustomValue<string>(sdk, 'theme', 'light')
const { value: maxPlayers } = useCustomValue<number>(sdk, 'game.maxPlayers', 4)

// Combined composable
const gameData = useEvUpGame({
  baseUrl: 'https://evup.vn',
  apiKey: 'gep_your_api_key',
  gameId: 'your_game_id'
})
</script>

<template>
  <div v-if="loading">Loading...</div>
  <div v-else-if="error">Error: {{ error.message }}</div>
  <div v-else>
    <h1>{{ gameData.appConfig?.name }}</h1>
    <p>Theme: {{ theme }}</p>
    <p>Max Players: {{ maxPlayers }}</p>
    <button @click="refetch()">Refresh</button>
  </div>
</template>

Svelte Stores

<script lang="ts">
  import { 
    createEvUpGameSDK,
    createGameConfigStore,
    createCustomValueStore,
    createEvUpGameStore
  } from '@evup/game-sdk/svelte'

  // Create SDK store
  const sdkStore = createEvUpGameSDK({
    baseUrl: 'https://evup.vn',
    apiKey: 'gep_your_api_key',
    gameId: 'your_game_id'
  })

  // Create individual stores
  const configStore = createGameConfigStore(sdkStore)
  const themeStore = createCustomValueStore(sdkStore, 'theme', 'light')

  // Or use combined store
  const gameStore = createEvUpGameStore({
    baseUrl: 'https://evup.vn',
    apiKey: 'gep_your_api_key',
    gameId: 'your_game_id'
  })

  // Access reactive values
  $: config = $gameStore.config
  $: loading = $gameStore.loading
  $: error = $gameStore.error
</script>

{#if $loading}
  <div>Loading...</div>
{:else if $error}
  <div>Error: {$error.message}</div>
{:else}
  <div>
    <h1>{$gameStore.appConfig?.name}</h1>
    <p>Theme: {$themeStore.value}</p>
    <button on:click={() => gameStore.refetchAll()}>Refresh All</button>
  </div>
{/if}

🔧 Advanced Configuration

Custom Validation

import { validateCustomConfig } from '@evup/game-sdk'

const config = await sdk.getConfig()
const validation = validateCustomConfig(config)

if (!validation.valid) {
  console.error('Configuration validation failed:')
  validation.errors.forEach(({ field, error }) => {
    console.error(`- ${field}: ${error}`)
  })
}

Configuration Merging

import { mergeConfigs } from '@evup/game-sdk'

const defaultSettings = {
  theme: 'light',
  colors: { primary: '#007bff', secondary: '#6c757d' },
  features: { audio: true, multiplayer: false }
}

const customData = await sdk.getCustomData()
const finalSettings = mergeConfigs(defaultSettings, customData)

🛡️ Best Practices

1. Environment Configuration

// Use environment variables for different environments
const sdk = new EvUpGameSDK({
  baseUrl: process.env.EVUP_BASE_URL || 'https://evup.vn',
  apiKey: process.env.EVUP_API_KEY!,
  gameId: process.env.EVUP_GAME_ID!,
  debug: process.env.NODE_ENV === 'development'
})

2. Error Boundaries

// Always wrap SDK calls in try-catch blocks
async function getGameTheme() {
  try {
    return await sdk.getCustomValue('theme', 'light')
  } catch (error) {
    console.error('Failed to get theme:', error)
    return 'light' // fallback
  }
}

3. Type Safety

// Use generic types for better type safety
interface GameSettings {
  maxPlayers: number
  difficulty: 'easy' | 'normal' | 'hard'
  enablePowerUps: boolean
}

const settings = await sdk.getCustomValue<GameSettings>('gameSettings', {
  maxPlayers: 4,
  difficulty: 'normal',
  enablePowerUps: true
})

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

📄 License

MIT License - see LICENSE for details.

🆘 Support

📧 Email: support@evup.vn
🌐 Website: https://evup.vn
📖 Documentation: https://docs.evup.vn
🐛 Issues: GitHub Issues

Made with ❤️ by the EvUp Team