@pixels-online/pixels-client-js-sdk 1.0.2 → 1.2.0

package/README.md

@@ -1 +1,338 @@
-# pixels-buildon-client-js-sdk
+# Pixels BuildOn Client JS SDK
+
+A powerful TypeScript SDK for integrating Pixels BuildOn offerwall functionality into web applications and games. This SDK provides real-time offer management, player progression tracking, and reward handling capabilities.
+
+## 🚀 Features
+
+- **Real-time Offer Management** - Live updates via Server-Sent Events (SSE)
+- **Player Progression Tracking** - Monitor player stats, achievements, and conditions
+- **Reward System Integration** - Handle various reward types (coins, items, exp, etc.)
+- **Event-Driven Architecture** - React to offer events and player actions
+- **TypeScript Support** - Full type safety and IntelliSense support
+- **Flexible Configuration** - Customizable asset resolution and hooks
+- **Multi-Environment Support** - Local, Test, staging, and production environments
+- **Auto-Reconnection** - Robust connection management with retry logic
+
+## 📦 Installation
+
+```bash
+npm install @pixels-online/pixels-client-js-sdk
+```
+
+## 🔧 Quick Start
+
+### 1. Basic Setup
+
+```typescript
+import { OfferwallClient } from '@pixels-online/pixels-client-js-sdk';
+
+const client = new OfferwallClient({
+  env: 'test', // or 'live' for production
+  tokenProvider: async () => {
+    // Fetch JWT token from your server. We recommend using our server-side SDK on your server for JWT creation
+    const response = await fetch('/api/auth/pixels-token', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+    });
+    const data = await response.json();
+    return data.token;
+  },
+  assetResolver: (_, id: string) => {
+    return {
+      name: exampleGameLib[id]?.name || 'Unknown2',
+      image: exampleGameLib[id]?.image,
+    };
+  },
+  fallbackRewardImage: 'https://example.com/default-reward.png',
+  hooks: {
+    onOfferSurfaced: (offer) => {
+      var random = Math.random() < 0.5;
+      return random; // 50% chance to show the offer
+    },
+  },
+  autoConnect: true,
+});
+```
+
+### 2. Initialize and Connect
+
+```typescript
+// Initialize the client
+await client.initialize();
+
+// Listen for offers
+client.on('offersUpdated', (offers) => {
+  console.log('Available offers:', offers);
+  displayOffersInUI(offers);
+});
+
+// Listen for player updates
+client.on('playerUpdated', (player) => {
+  console.log('Player data updated:', player);
+  updatePlayerStatsUI(player);
+});
+```
+
+### 3. Claim Offers
+
+```typescript
+// Claim an offer
+try {
+  const result = await client.claimOffer(offerId);
+  console.log('Offer claimed successfully:', result);
+} catch (error) {
+  console.error('Failed to claim offer:', error);
+}
+```
+
+## 🎯 Configuration Options
+
+### OfferwallConfig
+
+```typescript
+interface OfferwallConfig {
+  /** Environment: 'test' | 'live' | custom endpoint */
+  env: 'test' | 'live' | (string & {});
+
+  /** Auto-connect on initialization (default: false) */
+  autoConnect?: boolean;
+
+  /** Enable auto-reconnection (default: true) */
+  reconnect?: boolean;
+
+  /** Reconnection delay in ms (default: 1000) */
+  reconnectDelay?: number;
+
+  /** Max reconnection attempts (default: 5) */
+  maxReconnectAttempts?: number;
+
+  /** Enable debug logging (default: false) */
+  debug?: boolean;
+
+  /** Event hooks for custom logic */
+  hooks?: Partial<OfferwallHooks>;
+
+  /** Custom asset resolver for rewards */
+  assetResolver?: AssetResolver;
+
+  /** Fallback image for unknown rewards */
+  fallbackRewardImage: string;
+
+  /** JWT token provider function */
+  tokenProvider: TokenProvider;
+}
+```
+
+## 🎨 Asset Resolution
+
+Customize how rewards are displayed in your game:
+
+```typescript
+const gameAssets = {
+  gems: { name: 'Gems', image: '/assets/gems.png' },
+  gold: { name: 'Gold Coins', image: '/assets/gold.png' },
+  sword_1: { name: 'Iron Sword', image: '/assets/sword_iron.png' },
+};
+
+const client = new OfferwallClient({
+  // ... other config
+  assetResolver: (reward, assetId) => {
+    const asset = gameAssets[assetId];
+    if (asset) {
+      return { name: asset.name, image: asset.image };
+    }
+    return { name: `Unknown Item (${assetId})`, image: null };
+  },
+});
+```
+
+## 🎣 Event Hooks
+
+Implement custom logic with event hooks:
+
+```typescript
+const client = new OfferwallClient({
+  // ... other config
+  hooks: {
+    // Control which offers to show
+    onOfferSurfaced: (offer) => {
+      // Custom logic to determine if offer should be shown
+      return player.level >= offer.minLevel;
+    },
+
+    // Handle successful offer claims
+    onOfferClaimed: async (offer, rewards) => {
+      console.log('Offer completed!', { offer, rewards });
+      // Award rewards in your game
+      await showConfetti(rewards);
+    },
+
+    // Handle connection events
+    onConnect: () => {
+      console.log('Connected to Pixels BuildOn');
+      showConnectionStatus('connected');
+    },
+
+    onDisconnect: () => {
+      console.log('Disconnected from Pixels BuildOn');
+      showConnectionStatus('disconnected');
+    },
+  },
+});
+```
+
+## 📡 Events
+
+Listen to various events emitted by the client:
+
+```typescript
+// Offer-related events
+client.on('offersUpdated', (offers) => {
+  /* Handle offers update */
+});
+client.on('offerAdded', (offer) => {
+  /* Handle new offer */
+});
+client.on('offerRemoved', (offerId) => {
+  /* Handle offer removal */
+});
+client.on('offerUpdated', (offer) => {
+  /* Handle offer changes */
+});
+
+// Player-related events
+client.on('playerUpdated', (player) => {
+  /* Handle player data changes */
+});
+
+// Connection events
+client.on('connected', () => {
+  /* Handle connection */
+});
+client.on('disconnected', () => {
+  /* Handle disconnection */
+});
+client.on('reconnecting', (attempt) => {
+  /* Handle reconnection attempts */
+});
+
+// Error events
+client.on('error', (error) => {
+  /* Handle errors */
+});
+```
+
+## 🏗️ API Reference
+
+### OfferwallClient Methods
+
+#### `initialize(): Promise<void>`
+
+Initialize the client and establish connection.
+
+#### `disconnect(): Promise<void>`
+
+Disconnect from the service.
+
+#### `getOffers(): IClientOffer[]`
+
+Get all current offers.
+
+#### `getOffer(offerId: string): IClientOffer | null`
+
+Get a specific offer by ID.
+
+#### `claimOffer(offerId: string): Promise<ClaimResult>`
+
+Claim an offer and receive rewards.
+
+#### `getPlayer(): IClientPlayerSnapshot | null`
+
+Get current player data.
+
+#### `getConnectionState(): ConnectionState`
+
+Get current connection status.
+
+### Utility Functions
+
+```typescript
+import { meetsConditions, AssetHelper } from '@pixels-online/pixels-client-js-sdk';
+
+// Check if player meets offer conditions
+const canClaim = meetsConditions(player, offer.surfacingConditions);
+
+// Asset helper utilities
+const assetHelper = new AssetHelper(assetResolver, fallbackImage);
+const rewardAsset = assetHelper.resolveRewardAsset(reward, assetId);
+```
+
+## 🧪 Testing
+
+The SDK includes comprehensive test coverage:
+
+```bash
+# Run all tests
+npm test
+
+# Run unit tests
+npm run test:unit
+
+# Run integration tests
+npm run test:integration
+
+# Run e2e tests
+npm run test:e2e
+
+# Run with coverage
+npm run test:coverage
+
+# Watch mode
+npm run test:watch
+```
+
+## 🌍 Environments
+
+The SDK supports multiple environments:
+
+- **`test`** - Sandbox environment for development
+- **`live`** - Production environment
+- **`staging`** - Staging environment
+- **`preview`** - Preview environment
+- **`dev`** - Development environment
+- **Custom URL** - Provide your own endpoint
+
+## 📋 Requirements
+
+- Node.js 16+
+- TypeScript 4.5+ (if using TypeScript)
+- Modern browser with EventSource support
+
+## 🤝 Contributing
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## 📄 License
+
+This project is licensed under the AGPLv3 License - see the [LICENSE.md](LICENSE.md) file for details.
+
+## 🔗 Links
+
+- [GitLab Repository](https://gitlab.com/pixels-online-oss/pixels-buildon-client-js-sdk)
+- [Issue Tracker](https://gitlab.com/pixels-online-oss/pixels-buildon-client-js-sdk/issues)
+- [Pixels BuildOn Documentation](https://docs.pixels.xyz)
+
+## 📞 Support
+
+For support and questions:
+
+- Create an issue on [GitLab](https://gitlab.com/pixels-online-oss/pixels-buildon-client-js-sdk/issues)
+- Contact the Pixels team
+
+---
+
+Made with ❤️ by the Pixels team

package/dist/core/OfferwallClient.d.ts

@@ -3,8 +3,10 @@ import { OfferStore } from './OfferStore';
 import { AssetHelper } from '../utils/assets';
 import { OfferwallConfig } from '../types';
 import { ConnectionState } from '../types/connection';
+export declare const mapEnvToBuildOnApiUrl: (env: "test" | "live" | (string & {})) => "https://api.pixels.xyz" | "https://api.sandbox.pixels.xyz" | "https://api.staging.pixels.xyz" | "https://api.preview.pixels.xyz" | "https://api.dev.pixels.xyz";
 export declare class OfferwallClient {
     private config;
+    private endpoint;
     private eventEmitter;
     private sseConnection;
     private offerStore;

package/dist/core/SSEConnection.d.ts

@@ -7,6 +7,7 @@ export declare class SSEConnection {
     private eventEmitter;
     private tokenManager;
     private eventSource;
+    private endpoint;
     private reconnectAttempts;
     private reconnectTimeout;
     private isConnecting;

package/dist/index.esm.js

@@ -344,6 +344,7 @@ class SSEConnection {
         this.connectionState = ConnectionState.DISCONNECTED;
         this.serverSuggestedRetryTime = null;
         this.logger = createLogger(config, 'SSEConnection');
+        this.endpoint = mapEnvToBuildOnApiUrl(config.env);
     }
     /**
      * Get current connection state
@@ -364,7 +365,7 @@ class SSEConnection {
             previousState,
             error,
             attempt: this.reconnectAttempts,
-            maxAttempts: this.config.maxReconnectAttempts
+            maxAttempts: this.config.maxReconnectAttempts,
         });
     }
     connect() {
@@ -384,13 +385,13 @@ class SSEConnection {
             this.logger.log('Connecting to SSE endpoint...');
             try {
                 // Create SSE URL
-                const url = new URL(this.config.endpoint + '/sse/connect');
+                const url = new URL(this.endpoint + '/v1/sse/connect');
                 const token = await this.tokenManager.getTokenForConnection();
                 // Use CustomEventSource with Authorization Bearer header
                 this.eventSource = new CustomEventSource(url.toString(), {
                     headers: {
-                        'Authorization': `Bearer ${token}`,
-                    }
+                        Authorization: `Bearer ${token}`,
+                    },
                 });
                 // Listen for server-suggested retry time updates
                 this.eventSource.onRetryUpdate = (retryTime) => {
@@ -409,11 +410,14 @@ class SSEConnection {
                     this.logger.log('SSE connection error', error);
                     this.isConnecting = false;
                     // Check if it's an auth error
-                    if (error?.detail?.isAuthError || error?.message === 'jwt-expired' || error?.message === 'jwt-invalid') {
+                    if (error?.detail?.isAuthError ||
+                        error?.message === 'jwt-expired' ||
+                        error?.message === 'jwt-invalid') {
                         this.tokenManager.clearToken();
                         this.setConnectionState(ConnectionState.DISCONNECTED);
                         // Try to reconnect with fresh token if reconnect is enabled
-                        if (this.config.reconnect && this.reconnectAttempts < (this.config.maxReconnectAttempts || 5)) {
+                        if (this.config.reconnect &&
+                            this.reconnectAttempts < (this.config.maxReconnectAttempts || 5)) {
                             this.logger.log('JWT invalid/expired, attempting reconnect with fresh token');
                             this.handleReconnect();
                             resolve(); // Resolve instead of reject to allow reconnection
@@ -424,21 +428,22 @@ class SSEConnection {
                             return;
                         }
                     }
-                    const errorMsg = this.eventSource?.getReadyState() === ReadyState.CLOSED ?
-                        'Connection closed' : 'Connection error';
+                    const errorMsg = this.eventSource?.getReadyState() === ReadyState.CLOSED
+                        ? 'Connection closed'
+                        : 'Connection error';
                     const connectionError = new Error(errorMsg);
                     this.setConnectionState(ConnectionState.ERROR, connectionError);
                     if (this.eventSource?.getReadyState() === ReadyState.CLOSED) {
                         this.eventEmitter.emit(OfferEvent.CONNECTION_ERROR, {
                             error: connectionError,
-                            timestamp: new Date()
+                            timestamp: new Date(),
                         });
                         this.handleReconnect();
                     }
                     else {
                         this.eventEmitter.emit(OfferEvent.CONNECTION_ERROR, {
                             error: connectionError,
-                            timestamp: new Date()
+                            timestamp: new Date(),
                         });
                         reject(connectionError);
                     }
@@ -543,7 +548,7 @@ class SSEConnection {
             this.logger.log('Error parsing SSE message:', error);
             this.eventEmitter.emit(OfferEvent.ERROR, {
                 error: error,
-                context: 'sse_message_parse'
+                context: 'sse_message_parse',
             });
         }
     }
@@ -558,7 +563,7 @@ class SSEConnection {
             this.disconnect();
             this.eventEmitter.emit(OfferEvent.DISCONNECTED, {
                 reason: 'max_reconnect_attempts',
-                timestamp: new Date()
+                timestamp: new Date(),
             });
             return;
         }
@@ -587,7 +592,7 @@ class SSEConnection {
             this.setConnectionState(ConnectionState.DISCONNECTED);
             this.eventEmitter.emit(OfferEvent.DISCONNECTED, {
                 reason: 'manual',
-                timestamp: new Date()
+                timestamp: new Date(),
             });
         }
         this.isConnecting = false;
@@ -837,18 +842,35 @@ class AssetHelper {
     }
 }
 
+const mapEnvToBuildOnApiUrl = (env) => {
+    switch (env) {
+        case 'live':
+            return 'https://api.pixels.xyz';
+        case 'test':
+            return 'https://api.sandbox.pixels.xyz';
+        case 'staging':
+            return 'https://api.staging.pixels.xyz';
+        case 'preview':
+            return 'https://api.preview.pixels.xyz';
+        case 'dev':
+        case 'development':
+            return 'https://api.dev.pixels.xyz';
+        default:
+            return 'https://api.sandbox.pixels.xyz';
+    }
+};
 class OfferwallClient {
     constructor(config) {
         this.isInitializing = false;
         this.config = {
-            endpoint: config.endpoint || 'https://api.buildon.pixels.xyz',
             autoConnect: config.autoConnect ?? false,
             reconnect: config.reconnect ?? true,
             reconnectDelay: config.reconnectDelay ?? 1000,
             maxReconnectAttempts: config.maxReconnectAttempts ?? 5,
             debug: config.debug ?? false,
-            ...config
+            ...config,
         };
+        this.endpoint = mapEnvToBuildOnApiUrl(config.env);
         this.hooks = this.config.hooks || {};
         this.logger = createLogger(this.config, 'OfferwallClient');
         this.eventEmitter = new EventEmitter(this.config);
@@ -858,7 +880,7 @@ class OfferwallClient {
         this.sseConnection = new SSEConnection(this.config, this.eventEmitter, this.tokenManager);
         this.setupInternalListeners();
         if (this.config.autoConnect) {
-            this.initialize().catch(err => {
+            this.initialize().catch((err) => {
                 this.logger.error('Auto-initialization failed:', err);
             });
         }
@@ -910,7 +932,7 @@ class OfferwallClient {
         }
         const token = await this.tokenManager.getTokenForConnection();
         if (this.hooks.beforeConnect) {
-            await this.hooks.beforeConnect({ jwt: token, endpoint: this.config.endpoint });
+            await this.hooks.beforeConnect({ jwt: token, endpoint: this.endpoint });
         }
         try {
             await this.sseConnection.connect();
@@ -959,7 +981,7 @@ class OfferwallClient {
         }
         try {
             const response = await this.claimOfferAPI(instanceId);
-            const updatedOffer = { ...offer, status: 'claimed', };
+            const updatedOffer = { ...offer, status: 'claimed' };
             this.offerStore.upsertOffer(updatedOffer);
             this.eventEmitter.emit(OfferEvent.OFFER_CLAIMED, {
                 instanceId,
@@ -1023,11 +1045,11 @@ class OfferwallClient {
      */
     async postWithAuth(endpoint, body, retry = false) {
         const token = await this.tokenManager.getTokenForConnection();
-        const response = await fetch(`${this.config.endpoint}${endpoint}`, {
+        const response = await fetch(`${this.endpoint}${endpoint}`, {
             method: 'POST',
             headers: {
-                'Authorization': `Bearer ${token}`,
-                'Content-Type': 'application/json'
+                Authorization: `Bearer ${token}`,
+                'Content-Type': 'application/json',
             },
             body: body ? JSON.stringify(body) : undefined,
         });
@@ -1045,7 +1067,10 @@ class OfferwallClient {
         return response.json();
     }
     async claimOfferAPI(instanceId) {
-        return this.postWithAuth('/client/reward/claim', { instanceId, kind: 'offer' });
+        return this.postWithAuth('/v1/client/reward/claim', {
+            instanceId,
+            kind: 'offer',
+        });
     }
     async refreshOffersAndSnapshot() {
         try {
@@ -1061,7 +1086,9 @@ class OfferwallClient {
         }
     }
     async getOffersAndSnapshot() {
-        const data = await this.postWithAuth('/client/player/campaigns', { viewingCampaigns: true });
+        const data = await this.postWithAuth('/v1/client/player/campaigns', {
+            viewingCampaigns: true,
+        });
         if (!data.offers || !Array.isArray(data.offers)) {
             throw new Error('No offers returned from offers endpoint');
         }
@@ -1071,7 +1098,7 @@ class OfferwallClient {
         return data;
     }
     async getAuthLinkToken() {
-        const data = await this.postWithAuth('/auth/one_time_token/generate');
+        const data = await this.postWithAuth('/v1/auth/one_time_token/generate');
         if (!data.token) {
             throw new Error('No token returned from auth link endpoint');
         }