playe-developer-sdk 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,68 @@
+# Changelog
+
+All notable changes to the Playe Developer SDK will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2024-08-04
+
+### Added
+- Initial release of the Playe Developer SDK
+- Core game session management functionality
+  - Initialize, start, update progress, and complete game sessions
+  - Automatic heartbeat mechanism for session validation
+  - Session abandonment with cleanup
+- Campaign integration features
+  - Campaign status retrieval
+  - Live leaderboards with player rankings
+  - Player attempt history and statistics
+- Anti-cheat and validation systems
+  - Game session validation
+  - Score validation with basic cheat detection
+  - Device fingerprinting and information collection
+- Developer tools and utilities
+  - Test game session creation for development
+  - Debug mode with comprehensive logging
+  - Device feature detection and capability checking
+- Browser optimization
+  - Lightweight bundle size
+  - Native fetch API usage
+  - Custom event emission for tracking
+  - Automatic retry mechanism with exponential backoff
+- Comprehensive TypeScript support
+  - Full type definitions for all interfaces
+  - Strongly typed API responses
+  - Generic error handling with specific error types
+- Examples and documentation
+  - Basic usage examples in TypeScript
+  - Interactive browser example with HTML/JavaScript
+  - Comprehensive README with API documentation
+  - Error handling patterns and best practices
+
+### Features
+- **Game Session Management**: Complete lifecycle management of game sessions from initialization to completion
+- **Campaign Integration**: Support for all campaign styles (SingleWinner, FixedPool, Leaderboard, RewardForAll)
+- **Real-time Updates**: Live progress tracking and leaderboard updates
+- **Anti-cheat Protection**: Built-in validation mechanisms and heartbeat monitoring
+- **Device Detection**: Automatic device information gathering and fingerprinting
+- **Error Handling**: Comprehensive error types with context and debugging information
+- **Browser Events**: Custom DOM events for game lifecycle tracking
+- **Offline Support**: Configurable offline mode for development and testing
+
+### Technical Details
+- Built with TypeScript 5.9 for modern JavaScript features and type safety
+- Uses native Fetch API for HTTP requests with automatic retries
+- Implements exponential backoff for failed requests
+- Supports both ESM and CommonJS module formats
+- Includes source maps and declaration files for debugging
+- Zero external dependencies for core functionality
+- Browser compatibility: Chrome 60+, Firefox 55+, Safari 12+, Edge 79+
+
+### Developer Experience
+- Comprehensive TypeScript definitions
+- Debug mode with detailed logging
+- Interactive browser example for testing
+- Clear error messages with context
+- Automatic cleanup and resource management
+- Configurable timeout and retry settings

package/README.md

@@ -0,0 +1,341 @@
+# Playe Developer SDK
+
+A comprehensive browser-based SDK for integrating games with the Playe platform. This SDK provides easy-to-use APIs for game session management, campaign integration, leaderboards, and anti-cheat validation.
+
+## Features
+
+- 🎮 **Game Session Management** - Initialize, start, update, and complete game sessions
+- 🏆 **Campaign Integration** - Access campaign information, leaderboards, and player attempts
+- 🛡️ **Anti-Cheat Protection** - Built-in validation and heartbeat mechanisms
+- 📱 **Device Detection** - Automatic device information and fingerprinting
+- 🔧 **Developer Tools** - Test game sessions and debugging utilities
+- 📊 **Real-time Updates** - Progress tracking and live leaderboards
+- ⚡ **Browser Optimized** - Lightweight and fast for web games
+
+## Installation
+
+### NPM (Recommended)
+```bash
+npm install playe-developer-sdk
+# or
+yarn add playe-developer-sdk
+# or
+pnpm add playe-developer-sdk
+```
+
+### CDN (No build tools required)
+```html
+<!-- For production -->
+<script src="https://unpkg.com/playe-developer-sdk@latest/dist/playe-sdk.umd.min.js"></script>
+
+<!-- Alternative CDN -->
+<script src="https://cdn.jsdelivr.net/npm/playe-developer-sdk@latest/dist/playe-sdk.umd.min.js"></script>
+```
+
+### Workspace (Internal development)
+```json
+{
+  "dependencies": {
+    "@workspace/playe-developer-sdk": "workspace:*"
+  }
+}
+```
+
+## Quick Start
+
+### NPM Usage
+```typescript
+import { createPlayeSDK } from 'playe-developer-sdk';
+
+// Initialize the SDK
+const sdk = createPlayeSDK({
+  apiBaseUrl: 'https://api.playe.com',
+  apiKey: 'your-api-key',
+  enableDebugMode: true, // Enable for development
+});
+
+// Initialize a game session
+const session = await sdk.initializeGameSession({
+  campaignId: 'campaign-123',
+  gameId: 'game-456',
+  playerFingerprint: 'unique-player-fingerprint',
+  playerEmail: 'player@example.com',
+});
+
+// Start the game
+await sdk.startGameSession(session.sessionId);
+
+// Update progress during gameplay
+await sdk.updateGameProgress(session.sessionId, {
+  currentScore: 1500,
+  elapsedTime: 120, // seconds
+  gameState: { level: 3, lives: 2 },
+});
+
+// Complete the game
+const result = await sdk.completeGame(session.sessionId, {
+  finalScore: 2500,
+  gameMetrics: {
+    totalPlayTime: 300,
+    actionsPerformed: 150,
+    powerUpsUsed: 5,
+    levelsCompleted: 5,
+  },
+});
+
+console.log('Game completed!', {
+  isWinner: result.isWinner,
+  finalRank: result.finalRank,
+  prizeAmount: result.prizeAmount,
+});
+```
+
+### CDN Usage
+```html
+<script src="https://unpkg.com/playe-developer-sdk@latest/dist/playe-sdk.umd.min.js"></script>
+<script>
+// SDK is available as global PlayeSDK
+const sdk = PlayeSDK.createPlayeSDK({
+  apiBaseUrl: 'https://api.playe.com',
+  apiKey: 'your-api-key',
+  enableDebugMode: true,
+});
+
+// All utilities are available
+const fingerprint = PlayeSDK.DeviceUtils.generateFingerprint();
+
+// Same API as NPM version
+const session = await sdk.initializeGameSession({
+  campaignId: 'campaign-123',
+  gameId: 'game-456',
+  playerFingerprint: fingerprint,
+});
+</script>
+```
+
+## API Reference
+
+### SDK Configuration
+
+```typescript
+interface SDKConfig {
+  apiBaseUrl: string;           // Required: API base URL
+  apiKey?: string;             // Optional: API key for authentication
+  enableDebugMode?: boolean;   // Optional: Enable debug logging
+  retryAttempts?: number;      // Optional: Number of retry attempts (default: 3)
+  timeoutMs?: number;          // Optional: Request timeout in ms (default: 30000)
+  enableOfflineMode?: boolean; // Optional: Enable offline mode (default: false)
+}
+```
+
+### Core Methods
+
+#### Game Session Management
+
+```typescript
+// Initialize a new game session
+await sdk.initializeGameSession({
+  campaignId: string;
+  gameId: string;
+  playerFingerprint: string;
+  playerEmail?: string;
+  deviceInfo?: DeviceInfo;
+  receiptImage?: string;        // Base64 encoded
+  geolocationData?: GeolocationData;
+});
+
+// Start the game session
+await sdk.startGameSession(sessionId: string, config?: Record<string, any>);
+
+// Update game progress
+await sdk.updateGameProgress(sessionId: string, {
+  currentScore: number;
+  gameState?: Record<string, any>;
+  elapsedTime: number;
+  achievements?: Achievement[];
+  clientTimestamp?: string;
+});
+
+// Complete the game
+await sdk.completeGame(sessionId: string, {
+  finalScore: number;
+  gameMetrics?: GameMetrics;
+  finalGameState?: Record<string, any>;
+});
+
+// Abandon the game
+await sdk.abandonGame(sessionId: string, reason?: string, lastKnownScore?: number);
+```
+
+#### Campaign Information
+
+```typescript
+// Get campaign status
+await sdk.getCampaignStatus(campaignId: string, playerId?: string);
+
+// Get leaderboard
+await sdk.getLeaderboard(campaignId: string, limit?: number, playerId?: string);
+
+// Get player attempts
+await sdk.getPlayerAttempts(campaignId: string, playerId: string);
+```
+
+#### Validation & Anti-Cheat
+
+```typescript
+// Validate game session
+await sdk.validateGameSession(sessionId: string, validationData?: Record<string, any>);
+
+// Send heartbeat (usually handled automatically)
+await sdk.sendHeartbeat(sessionId: string, currentScore?: number);
+```
+
+### Utility Methods
+
+```typescript
+// Test SDK functionality
+sdk.test('Custom test message');
+
+// Check if running in demo mode
+const isDemoMode = sdk.isDemo();
+
+// Game lifecycle events
+sdk.gameLoadingStart();
+sdk.gameLoadingFinished();
+sdk.gamePlayStop();
+
+// Clean up resources
+sdk.destroy();
+```
+
+### Device Utilities
+
+```typescript
+import { DeviceUtils } from '@workspace/playe-developer-sdk';
+
+// Get device information
+const deviceInfo = DeviceUtils.getDeviceInfo();
+
+// Get geolocation
+const location = await DeviceUtils.getGeolocationData();
+
+// Generate fingerprint
+const fingerprint = DeviceUtils.generateFingerprint();
+
+// Check browser support
+const isSupported = DeviceUtils.isBrowser();
+const features = DeviceUtils.getFeatureSupport();
+```
+
+### Error Handling
+
+```typescript
+import { 
+  PlayeSDKError, 
+  ValidationError, 
+  NetworkError, 
+  AuthenticationError,
+  GameSessionError 
+} from '@workspace/playe-developer-sdk';
+
+try {
+  await sdk.initializeGameSession(params);
+} catch (error) {
+  if (error instanceof ValidationError) {
+    console.error('Validation failed:', error.message);
+  } else if (error instanceof NetworkError) {
+    console.error('Network error:', error.message);
+  } else if (error instanceof AuthenticationError) {
+    console.error('Authentication failed:', error.message);
+  } else if (error instanceof PlayeSDKError) {
+    console.error('SDK error:', error.toJSON());
+  }
+}
+```
+
+## Campaign Styles
+
+The SDK supports different campaign styles:
+
+- **SingleWinner**: One winner takes all
+- **FixedPool**: Fixed number of winners
+- **Leaderboard**: Winners based on ranking
+- **RewardForAll**: Everyone gets rewards
+
+## Events
+
+The SDK emits custom browser events for tracking:
+
+```typescript
+// Listen for SDK events
+window.addEventListener('playe:game-loading-start', () => {
+  console.log('Game loading started');
+});
+
+window.addEventListener('playe:game-loading-finished', () => {
+  console.log('Game loading finished');
+});
+
+window.addEventListener('playe:game-play-stop', () => {
+  console.log('Game play stopped');
+});
+```
+
+## Development
+
+### Testing
+
+```typescript
+// Create a test game session for development
+const testSession = await sdk.createTestGameSession({
+  mockCampaign: true,
+  mockPlayers: 10,
+  testScenario: 'leaderboard',
+});
+```
+
+### Debug Mode
+
+Enable debug mode to see detailed logging:
+
+```typescript
+const sdk = createPlayeSDK({
+  apiBaseUrl: 'https://api.playe.com',
+  enableDebugMode: true, // This will log all API calls and responses
+});
+```
+
+## Browser Compatibility
+
+- Chrome 60+
+- Firefox 55+
+- Safari 12+
+- Edge 79+
+
+## Distribution
+
+The SDK is available in multiple formats:
+
+- **NPM Package**: `npm install playe-developer-sdk`
+- **CDN (UMD)**: `https://unpkg.com/playe-developer-sdk@latest/dist/playe-sdk.umd.min.js`
+- **Workspace**: `@workspace/playe-developer-sdk` (internal development)
+
+### Bundle Sizes
+- ESM: 27.3KB (8KB gzipped)
+- CommonJS: 27.6KB (8KB gzipped)  
+- UMD: 30.8KB (9KB gzipped)
+- UMD Minified: 13.7KB (5KB gzipped)
+
+For detailed distribution information, see [DISTRIBUTION.md](./DISTRIBUTION.md).
+
+## TypeScript Support
+
+This SDK is written in TypeScript and includes full type definitions. No additional `@types` packages are needed.
+
+## License
+
+MIT License - see LICENSE file for details.
+
+## Support
+
+For support, please contact the Playe development team or create an issue in the repository.