playe-developer-sdk 1.0.7 → 1.0.9

package/README.md

@@ -1,21 +1,26 @@
-# Playe Developer SDK
+# 🎮 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.
+[![Version](https://img.shields.io/npm/v/playe-developer-sdk)](https://npmjs.com/package/playe-developer-sdk)
+[![License](https://img.shields.io/npm/l/playe-developer-sdk)](https://github.com/playe/playe/blob/main/LICENSE)
+[![Bundle Size](https://img.shields.io/bundlephobia/min/playe-developer-sdk)](https://bundlephobia.com/package/playe-developer-sdk)
+[![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
 
-## Features
+A browser-based SDK for integrating games with the Playe platform. Provides game session management, campaign integration, leaderboards, and integrity verification.
+
+## ✨ Features
 
 - 🎮 **Game Session Management** - Initialize, start, update, and complete game sessions
-- 🛡️ **Integrity Verification** - Built-in session integrity with cryptographic hashing and validation
+- 🛡️ **Integrity Verification** - Built-in session integrity with cryptographic hashing
 - 🏆 **Campaign Integration** - Access campaign information, leaderboards, and player attempts
 - 🔄 **Anti-Cheat Protection** - Advanced validation, heartbeat mechanisms, and session monitoring
 - 📱 **Device Detection** - Automatic device information and fingerprinting
-- 🔧 **Developer Tools** - Test game sessions and comprehensive debugging utilities
+- 🔧 **Developer Tools** - Test game sessions and debugging utilities
 - 📊 **Real-time Updates** - Progress tracking and live leaderboards
 - ⚡ **Browser Optimized** - Lightweight and fast for web games with automatic retry logic
 
-## Installation
+## 🚀 Installation
 
-### NPM (Recommended)
+### NPM
 
 ```bash
 npm install playe-developer-sdk
@@ -25,17 +30,13 @@ yarn add playe-developer-sdk
 pnpm add playe-developer-sdk
 ```
 
-### CDN (No build tools required)
+### CDN
 
 ```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)
+### Workspace
 
 ```json
 {
@@ -45,39 +46,33 @@ pnpm add playe-developer-sdk
 }
 ```
 
-## Quick Start
+## 📖 Quick Start
 
 ### NPM Usage
 
 ```typescript
 import { createPlayeSDK } from "playe-developer-sdk";
 
-// Initialize the SDK
+// Initialize SDK
 const sdk = createPlayeSDK({
   apiBaseUrl: "https://api.playe.com",
   apiKey: "your-api-key",
-  enableDebugMode: true, // Enable for development
+  enableDebugMode: true,
 });
 
-// Initialize a game session (gets sessionId from URL query parameter)
+// Initialize game session (gets sessionId from URL)
 const session = await sdk.initializeGameSession();
 
-console.log("Game session initialized:", {
-  sessionId: session.sessionId,
-  campaignId: session.campaign.id,
-  playerId: session.player.id,
-});
-
-// Start the game
+// Start game
 await sdk.startGameSession({
   difficulty: "normal",
   mode: "classic",
 });
 
-// Update progress during gameplay (includes automatic integrity verification)
+// Update progress
 await sdk.updateGameProgress({
   currentScore: 1500,
-  elapsedTime: 120, // seconds
+  elapsedTime: 120,
   gameState: {
     level: 3,
     lives: 2,
@@ -92,7 +87,7 @@ await sdk.updateGameProgress({
   ],
 });
 
-// Complete the game (includes integrity verification)
+// Complete game
 const result = await sdk.completeGame({
   finalScore: 2500,
   validationChecksum: "client-checksum",
@@ -107,12 +102,6 @@ const result = await sdk.completeGame({
     finalLives: 1,
   },
 });
-
-console.log("Game completed!", {
-  isWinner: result.isWinner,
-  finalRank: result.finalRank,
-  prizeAmount: result.prizeAmount,
-});
 ```
 
 ### CDN Usage
@@ -120,24 +109,35 @@ console.log("Game completed!", {
 ```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(); // Gets sessionId from URL
-
+  const session = await sdk.initializeGameSession();
   console.log('Session initialized:', session.sessionId);
 </script>
 ```
 
-## API Reference
+## 📋 Table of Contents
+
+- [🎮 Playe Developer SDK](#-playe-developer-sdk)
+  - [✨ Features](#-features)
+  - [🚀 Installation](#-installation)
+  - [📖 Quick Start](#-quick-start)
+  - [📋 Table of Contents](#-table-of-contents)
+  - [🔧 API Reference](#-api-reference)
+  - [🔒 Security & Integrity](#-security--integrity)
+  - [🧪 Testing & Development](#-testing--development)
+  - [🚨 Error Handling](#-error-handling)
+  - [📚 Examples](#-examples)
+  - [🔄 Migration Guide](#-migration-guide)
+  - [🔧 Troubleshooting](#-troubleshooting)
+  - [🤝 Contributing](#-contributing)
+  - [📄 License](#-license)
+
+## 🔧 API Reference
 
 ### SDK Configuration
 
@@ -159,9 +159,11 @@ interface SDKConfig {
 ```typescript
 // Initialize game session (gets sessionId from URL query parameter)
 const session = await sdk.initializeGameSession(): Promise<GameSessionResponse>;
+// Returns: { sessionId, campaignId, gameId, status, campaign, player, createdAt, expiresAt }
 
-// Start the game session
+// Start game session
 await sdk.startGameSession(config?: Record<string, any>): Promise<GameSessionResponse>;
+// Returns: { sessionId, status, startTime }
 
 // Update game progress with integrity verification
 await sdk.updateGameProgress({
@@ -171,17 +173,20 @@ await sdk.updateGameProgress({
   achievements?: Achievement[];
   clientTimestamp?: string;
 }): Promise<ProgressUpdateResponse>;
+// Returns: { isValid, validationMessage, currentRank, isLeading, campaignStatus, warnings }
 
-// Complete the game with integrity verification
+// Complete game with integrity verification
 await sdk.completeGame({
   finalScore: number;
   validationChecksum: string;
   gameMetrics?: GameMetrics;
   finalGameState?: Record<string, any>;  // Automatically hashed for integrity
 }): Promise<GameCompletionResponse>;
+// Returns: { isWinner, prizeAmount, prizeType, finalRank, totalParticipants, winnerDetails, reward, campaignResult }
 
-// Abandon the game
+// Abandon game
 await sdk.abandonGame(reason?: string, lastKnownScore?: number): Promise<AbandonGameResponse>;
+// Returns: { success, message, gamepassRefunded, abandonedAt }
 ```
 
 #### Campaign Information
@@ -189,12 +194,19 @@ await sdk.abandonGame(reason?: string, lastKnownScore?: number): Promise<Abandon
 ```typescript
 // Get campaign status
 await sdk.getCampaignStatus(campaignId: string, playerId?: string): Promise<CampaignStatusResponse>;
+// Returns: { campaignId, status, campaignStyle, remainingGamepasses, totalParticipants, 
+//          totalPrizePool, endDate, playerStatus, topPlayers, prizeBreakdown }
 
 // Get leaderboard
 await sdk.getLeaderboard(campaignId: string, limit?: number, playerId?: string): Promise<LeaderboardResponse>;
+// Returns: { campaignId, entries, playerRank, lastUpdated, isLive }
+// entries: [{ rank, playerId, displayName, score, achievedAt, isCurrentPlayer, prizeAmount }]
 
 // Get player attempts
 await sdk.getPlayerAttempts(campaignId: string, playerId: string): Promise<PlayerAttemptsResponse>;
+// Returns: { playerId, campaignId, totalAttempts, remainingAttempts, attempts, stats }
+// attempts: [{ sessionId, score, playedAt, duration, status, wasWinner }]
+// stats: { bestScore, averageScore, totalPlayTime, firstAttempt, lastAttempt }
 ```
 
 #### Validation & Anti-Cheat
@@ -207,9 +219,11 @@ await sdk.validateGameSession({
   timingData?: unknown;
   behaviorMetrics?: unknown;
 }): Promise<ValidationResponse>;
+// Returns: { isValid, confidenceScore, validationIssues, warnings, requiresRevalidation, validatedAt }
 
 // Send heartbeat (usually handled automatically)
 await sdk.sendHeartbeat(currentScore?: number): Promise<HeartbeatResponse>;
+// Returns: { acknowledged, serverTimestamp, nextHeartbeatIn, campaignStillActive, message }
 ```
 
 #### Developer Tools
@@ -217,6 +231,7 @@ await sdk.sendHeartbeat(currentScore?: number): Promise<HeartbeatResponse>;
 ```typescript
 // Create test game session for development
 await sdk.createTestGameSession(testConfig?: Record<string, any>): Promise<TestGameResponse>;
+// Returns: { testSessionId, testScenario, mockCampaign, testData, expiresAt }
 ```
 
 ### Utility Methods
@@ -237,6 +252,77 @@ sdk.gamePlayStop(): void;         // Stop heartbeat and emit stop event
 sdk.destroy(): void;              // Clean up session artifacts and stop heartbeat
 ```
 
+### Response Types
+
+```typescript
+// Game Session Response
+interface GameSessionResponse {
+  sessionId: string;
+  campaignId: string;
+  gameId: string;
+  status: string;
+  campaign: CampaignInfo;
+  player: PlayerInfo;
+  createdAt: string;
+  expiresAt?: string;
+}
+
+// Progress Update Response
+interface ProgressUpdateResponse {
+  isValid: boolean;
+  validationMessage?: string;
+  currentRank: number;
+  isLeading: boolean;
+  campaignStatus?: CampaignStatusInfo;
+  warnings?: string[];
+}
+
+// Game Completion Response
+interface GameCompletionResponse {
+  isWinner: boolean;
+  prizeAmount?: number;
+  prizeType?: string;
+  finalRank: number;
+  totalParticipants: number;
+  winnerDetails?: WinnerInfo;
+  reward?: RewardInfo;
+  campaignResult?: CampaignResultInfo;
+}
+
+// Campaign Status Response
+interface CampaignStatusResponse {
+  campaignId: string;
+  status: string;
+  campaignStyle: string;
+  remainingGamepasses: number;
+  totalParticipants: number;
+  totalPrizePool: number;
+  endDate?: string;
+  playerStatus?: PlayerStatusInfo;
+  topPlayers?: TopPlayer[];
+  prizeBreakdown?: PrizeBreakdown;
+}
+
+// Leaderboard Response
+interface LeaderboardResponse {
+  campaignId: string;
+  entries: LeaderboardEntry[];
+  playerRank?: PlayerRankInfo;
+  lastUpdated: string;
+  isLive: boolean;
+}
+
+// Validation Response
+interface ValidationResponse {
+  isValid: boolean;
+  confidenceScore: number;
+  validationIssues: string[];
+  warnings: string[];
+  requiresRevalidation: boolean;
+  validatedAt: string;
+}
+```
+
 ### Integrity Verification Utilities
 
 ```typescript
@@ -294,35 +380,7 @@ try {
 }
 ```
 
-## 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");
-});
-```
-
-## Integrity Verification
+## 🔒 Security & Integrity
 
 The SDK includes built-in integrity verification to prevent cheating and ensure fair play:
 
@@ -356,43 +414,7 @@ if (!validation.isValid) {
 }
 ```
 
-## Running Examples
-
-### Flappy Bird Example
-
-The `examples/flappy-bird.html` provides a complete game integration example with player eligibility validation and score submission.
-
-#### Setup
-
-1. Build the SDK:
-```bash
-pnpm --filter playe-developer-sdk build
-```
-
-2. Open the example:
-```bash
-# Using any local server
-python -m http.server 8000
-# or
-npx serve
-```
-
-3. Navigate to: `http://localhost:8000/packages/playe-developer-sdk/examples/flappy-bird.html`
-
-#### Features Demonstrated
-
-- ✅ Player eligibility validation (attempts remaining, campaign status)
-- ✅ Game session initialization with SDK
-- ✅ Real-time progress tracking
-- ✅ Score submission with completion data
-- ✅ Graceful fallback to demo mode if SDK unavailable
-- ✅ Responsive game canvas with mobile support
-
-#### Demo Mode
-
-If the SDK is not available (e.g., not built), the game runs in demo mode without server integration. This allows testing game mechanics offline.
-
-## Development
+## 🧪 Testing & Development
 
 ### Testing
 
@@ -422,46 +444,186 @@ const sdk = createPlayeSDK({
 
 ### URL Requirements
 
-For `initializeGameSession()` to work, the page URL must include a `sessionId` query parameter:
+For `initializeGameSession()` to work, page URL must include a `sessionId` query parameter:
 
 ```
 https://yourgame.com/play?sessionId=abc123-def456-ghi789
 ```
 
-The SDK will automatically extract this sessionId and initialize the session.
+The SDK will automatically extract this sessionId and initialize session.
 
-## Browser Compatibility
+## 📚 Examples
 
-- Chrome 60+
-- Firefox 55+
-- Safari 12+
-- Edge 79+
+### Browser Example
 
-## Distribution
+The `examples/browser-example.html` provides a complete integration example with:
 
-The SDK is available in multiple formats:
+- SDK initialization and configuration
+- Session management (initialize, start, update, complete)
+- Progress tracking with integrity verification
+- Leaderboard fetching and display
+- Error handling and recovery
+- Debug mode logging
+- Device fingerprinting
 
-- **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)
+### Flappy Bird Example
 
-### Bundle Sizes
+The `examples/flappy-bird.html` provides a complete game integration example with:
 
-- ESM: 27.3KB (8KB gzipped)
-- CommonJS: 27.6KB (8KB gzipped)
-- UMD: 30.8KB (9KB gzipped)
-- UMD Minified: 13.7KB (5KB gzipped)
+- Player eligibility validation (attempts remaining, campaign status)
+- Game session initialization with SDK
+- Real-time progress tracking
+- Score submission with completion data
+- Graceful fallback to demo mode if SDK unavailable
+- Responsive game canvas with mobile support
 
-For detailed distribution information, see [DISTRIBUTION.md](./DISTRIBUTION.md).
+## 🔄 Migration Guide
 
-## TypeScript Support
+### Migrating from v0.x to v1.x
 
-This SDK is written in TypeScript and includes full type definitions. No additional `@types` packages are needed.
+#### Breaking Changes
 
-## License
+1. **SDK Initialization**
+```typescript
+// v0.x
+import { PlayeDeveloperSDK } from 'playe-developer-sdk';
+const sdk = new PlayeDeveloperSDK(config);
 
-MIT License - see LICENSE file for details.
+// v1.x
+import { createPlayeSDK } from 'playe-developer-sdk';
+const sdk = createPlayeSDK(config);
+```
+
+2. **Method Signatures**
+```typescript
+// v0.x - Callback-based
+sdk.initializeGameSession((error, session) => {
+  if (error) handleError(error);
+  else handleSuccess(session);
+});
+
+// v1.x - Promise-based
+try {
+  const session = await sdk.initializeGameSession();
+  handleSuccess(session);
+} catch (error) {
+  handleError(error);
+}
+```
+
+## 🚨 Error Handling
+
+### Error Types
+
+```typescript
+// Base SDK error
+PlayeSDKError {
+  name: string;
+  message: string;
+  originalError?: Error;
+  context?: string;
+  timestamp: string;
+}
+
+// Specific error types
+ValidationError extends PlayeSDKError; // Validation failures
+NetworkError extends PlayeSDKError;    // Network issues
+AuthenticationError extends PlayeSDKError; // Authentication failures
+GameSessionError extends PlayeSDKError; // Session-specific errors
+```
+
+### Error Recovery
+
+```typescript
+// Enable debug mode for detailed error information
+const sdk = createPlayeSDK({
+  apiBaseUrl: 'https://api.playe.com',
+  enableDebugMode: true,
+  retryAttempts: 3, // Configure retry behavior
+  timeoutMs: 30000, // Configure timeout
+});
+```
+
+## 🔧 Troubleshooting
+
+### Common Issues
 
-## Support
+#### "No sessionId found in URL" Error
+
+**Problem:** Getting an error when calling `initializeGameSession()`.
+
+**Solution:** Ensure your game URL includes a `sessionId` query parameter:
+```
+https://yourgame.com/play?sessionId=abc123-def456-ghi789
+```
+
+#### Network/Timeout Errors
+
+**Problem:** API calls failing with network errors.
+
+**Solutions:**
+1. Check API endpoint configuration
+2. Verify API key is correct
+3. Check network connectivity
+4. Increase timeout for slow networks
+
+#### Integrity Validation Failures
+
+**Problem:** Game completion failing with integrity validation errors.
+
+**Solutions:**
+1. Ensure game state is valid and serializable
+2. Check timing data is reasonable
+3. Use debug mode to inspect requests
+
+## 🤝 Contributing
+
+We welcome contributions to the Playe Developer SDK!
+
+### Development Setup
+
+```bash
+# Clone repository
+git clone https://github.com/playe/playe.git
+cd playe
+
+# Install dependencies
+pnpm install
+
+# Build SDK
+pnpm --filter playe-developer-sdk build
+
+# Run tests
+pnpm --filter playe-developer-sdk test
+```
+
+### Code Guidelines
+
+- Follow TypeScript best practices
+- Add tests for new functionality
+- Update documentation as needed
+- Ensure all tests pass
+
+## 📄 License
+
+MIT License - see LICENSE file for details.
 
-For support, please contact the Playe development team or create an issue in the repository.
+Copyright (c) 2024 Playe
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.cjs.js

@@ -196,14 +196,6 @@ class HttpClient {
         const jwtToken = this.getUrlParameter('accessToken');
         if (jwtToken) {
             headers['Authorization'] = `Bearer ${jwtToken}`;
-            // Debug logging for iframe contexts
-            if (this.config.enableDebugMode) {
-                console.log('[Playe SDK] Using GO session token in iframe context:', {
-                    hasToken: !!jwtToken,
-                    tokenLength: jwtToken?.length,
-                    tokenSource: jwtToken,
-                });
-            }
         }
         return headers;
     }
@@ -238,28 +230,16 @@ class HttpClient {
         let lastError;
         for (let attempt = 0; attempt <= retries; attempt++) {
             try {
-                if (this.config.enableDebugMode) {
-                    console.log(`[Playe SDK] ${options.method || 'GET'} ${url}`, {
-                        attempt: attempt + 1,
-                        body: options.body,
-                    });
-                }
                 const response = await fetch(url, requestOptions);
                 if (!response.ok) {
                     const errorText = await response.text();
                     throw new Error(`HTTP ${response.status}: ${errorText}`);
                 }
                 const data = await response.json();
-                if (this.config.enableDebugMode) {
-                    console.log(`[Playe SDK] Response:`, data);
-                }
                 return data;
             }
             catch (error) {
                 lastError = error;
-                if (this.config.enableDebugMode) {
-                    console.warn(`[Playe SDK] Request failed (attempt ${attempt + 1}/${retries + 1}):`, error);
-                }
                 // Don't retry on client errors (4xx)
                 if (error instanceof Error && error.message.includes('HTTP 4')) {
                     break;
@@ -558,7 +538,7 @@ class PlayeDeveloperSDK {
             }
             // Prepare request body
             const body = { ...progressData };
-            const response = await this.httpClient.put(`/developer/game/${this.sessionId}/progress`, body);
+            const response = await this.httpClient.put(`/game-session//${this.sessionId}/progress`, body);
             if (this.config.enableDebugMode) {
                 console.log('[Playe SDK] Progress updated:', {
                     score: progressData.currentScore,
@@ -633,7 +613,7 @@ class PlayeDeveloperSDK {
     async getCampaignStatus(campaignId, playerId) {
         try {
             const params = playerId ? `?playerId=${encodeURIComponent(playerId)}` : '';
-            return await this.httpClient.get(`/api/campaigns/${campaignId}/status${params}`);
+            return await this.httpClient.get(`/api/game-session/campaign/${campaignId}/status${params}`);
         }
         catch (error) {
             throw this.handleError(error, 'Failed to get campaign status');
@@ -647,7 +627,7 @@ class PlayeDeveloperSDK {
             if (playerId)
                 params.append('playerId', playerId);
             const queryString = params.toString() ? `?${params.toString()}` : '';
-            return await this.httpClient.get(`/api/campaigns/${campaignId}/leaderboard${queryString}`);
+            return await this.httpClient.get(`/api/game-session/campaign/${campaignId}/leaderboard${queryString}`);
         }
         catch (error) {
             throw this.handleError(error, 'Failed to get leaderboard');
@@ -655,7 +635,7 @@ class PlayeDeveloperSDK {
     }
     async getPlayerAttempts(campaignId, playerId) {
         try {
-            return await this.httpClient.get(`/api/campaigns/${campaignId}/players/${playerId}/attempts`);
+            return await this.httpClient.get(`/api/game-session/campaign/${campaignId}/players/${playerId}/attempts`);
         }
         catch (error) {
             throw this.handleError(error, 'Failed to get player attempts');
@@ -673,7 +653,7 @@ class PlayeDeveloperSDK {
                 timingData: request.timingData,
                 behaviorMetrics: request.behaviorMetrics
             };
-            return await this.httpClient.post(`/developer/game/${this.sessionId}/validate`, body);
+            return await this.httpClient.post(`/game-session/${this.sessionId}/validate`, body);
         }
         catch (error) {
             throw this.handleError(error, 'Failed to validate game session');