@pixels-online/pixels-client-js-sdk 1.4.0 → 1.5.0

package/README.md

@@ -68,7 +68,8 @@ client.on('offersUpdated', (offers) => {
 
 // Listen for player updates
 client.on('playerUpdated', (player) => {
-  console.log('Player data updated:', player);
+  console.log('Player snapshot updated:', player.snapshot);
+  console.log('Player data updated:', player.data);
   updatePlayerStatsUI(player);
 });
 ```
@@ -85,6 +86,36 @@ try {
 }
 ```
 
+## 📊 Player Data Structure
+
+The SDK provides player information through the `IClientPlayer` interface:
+
+```typescript
+interface IClientPlayer {
+  snapshot: IPlayerSnapshot; // Core player data (levels, currencies, achievements, etc.)
+  data?: IPlayerData | null; // Additional game-specific data
+}
+```
+
+### Accessing Player Information
+
+```typescript
+// Get the current player
+const player = client.getPlayer();
+
+if (player) {
+  // Access core player data
+  console.log('Player ID:', player.snapshot.playerId);
+  console.log('Player level:', player.snapshot.levels?.combat?.level);
+  console.log('Currency balance:', player.snapshot.currencies?.gold?.balance);
+
+  // Access additional player data (if available)
+  if (player.data) {
+    console.log('Additional currencies:', player.data.currencies);
+  }
+}
+```
+
 ## 🎯 Configuration Options
 
 ### OfferwallConfig
@@ -157,7 +188,8 @@ const client = new OfferwallClient({
     // Control which offers to show
     onOfferSurfaced: (offer) => {
       // Custom logic to determine if offer should be shown
-      return player.level >= offer.minLevel;
+      const currentPlayer = client.getPlayer();
+      return currentPlayer?.snapshot.levels?.overall?.level >= offer.minLevel;
     },
 
     // Handle successful offer claims
@@ -234,22 +266,14 @@ Initialize the client and establish connection.
 
 Disconnect from the service.
 
-#### `getOffers(): IClientOffer[]`
-
-Get all current offers.
+#### `refreshOffersAndPlayer(): { offers: IClientOffer[], player: IClientPlayer }`
 
-#### `getOffer(offerId: string): IClientOffer | null`
-
-Get a specific offer by ID.
+Refresh and get all current offers.
 
 #### `claimOffer(offerId: string): Promise<ClaimResult>`
 
 Claim an offer and receive rewards.
 
-#### `getPlayer(): IClientPlayerSnapshot | null`
-
-Get current player data.
-
 #### `getConnectionState(): ConnectionState`
 
 Get current connection status.
@@ -260,7 +284,7 @@ Get current connection status.
 import { meetsConditions, AssetHelper } from '@pixels-online/pixels-client-js-sdk';
 
 // Check if player meets offer conditions
-const canClaim = meetsConditions(player, offer.surfacingConditions);
+const canClaim = meetsConditions(player.snapshot, offer.surfacingConditions);
 
 // Asset helper utilities
 const assetHelper = new AssetHelper(assetResolver, fallbackImage);
@@ -302,7 +326,53 @@ The SDK supports multiple environments:
 - **`dev`** - Development environment
 - **Custom URL** - Provide your own endpoint
 
-## 📋 Requirements
+## � Migration Guide
+
+### v1.0.0+ Breaking Changes
+
+**Player Data Structure Update**
+
+The player data structure has been updated to provide better separation between core player data and additional game-specific data:
+
+- **Old**: `IClientPlayerSnapshot` (flat structure)
+- **New**: `IClientPlayer` (structured with `snapshot` and `data` properties)
+
+**Migration Steps:**
+
+```typescript
+// Before (v0.x)
+const player = client.getPlayer(); // IClientPlayerSnapshot
+const level = player.levels?.combat?.level;
+const gold = player.currencies?.gold?.balance;
+
+// After (v1.0+)
+const player = client.getPlayer(); // IClientPlayer
+const level = player.snapshot.levels?.combat?.level;
+const gold = player.snapshot.currencies?.gold?.balance;
+
+// Access additional data (new feature)
+const additionalCurrencies = player.data?.currencies;
+```
+
+**Event Handler Updates:**
+
+```typescript
+// Before
+client.on('playerUpdated', (playerSnapshot) => {
+  updateUI(playerSnapshot.currencies);
+});
+
+// After
+client.on('playerUpdated', (player) => {
+  updateUI(player.snapshot.currencies);
+  // Also handle additional data if needed
+  if (player.data) {
+    handleAdditionalData(player.data);
+  }
+});
+```
+
+## �📋 Requirements
 
 - Node.js 16+
 - TypeScript 4.5+ (if using TypeScript)

package/dist/core/OfferStore.d.ts

@@ -1,13 +1,13 @@
 import { OfferwallConfig } from '../types';
 import { IClientOffer, PlayerOfferStatus } from '../types/offer';
-import { IClientPlayerSnapshot } from '../types/player';
+import { IClientPlayer } from '../types/player';
 export declare class OfferStore {
     private offers;
-    private playerSnapshot;
+    private player;
     private logger;
     constructor(config: OfferwallConfig);
-    getSnapshot(): IClientPlayerSnapshot | null;
-    setSnapshot(snapshot: IClientPlayerSnapshot): void;
+    getPlayer(): IClientPlayer | null;
+    setPlayer(player: IClientPlayer): void;
     /**
      * Set all offers (replaces existing)
      */

package/dist/core/OfferwallClient.d.ts

@@ -1,9 +1,10 @@
 import { EventEmitter } from '../events/EventEmitter';
 import { OfferStore } from './OfferStore';
 import { AssetHelper } from '../utils/assets';
-import { OfferwallConfig } from '../types';
+import { OfferwallConfig } from '../types/index';
+import { IClientOffer } from '../types/offer';
 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";
+import { IClientPlayer } from '../types/player';
 export declare const mapEnvToOfferClientUrl: (env: "test" | "live" | (string & {})) => "https://offers.pixels.xyz" | "https://offers.sandbox.pixels.xyz" | "https://offers.staging.pixels.xyz" | "https://offers.preview.pixels.xyz" | "https://offers.dev.pixels.xyz";
 export declare class OfferwallClient {
     private config;
@@ -59,8 +60,10 @@ export declare class OfferwallClient {
      */
     private postWithAuth;
     private claimOfferAPI;
-    refreshOffersAndSnapshot(): Promise<void>;
-    private getOffersAndSnapshot;
+    getPlayer(): IClientPlayer | null;
+    getOffers(): IClientOffer[];
+    refreshOffersAndPlayer(): Promise<void>;
+    private getOffersAndPlayer;
     getAuthLinkToken(): Promise<string>;
     getGameId(): string | null;
     getDashboardRedirectUrl(): Promise<string | null>;

package/dist/core/SSEConnection.d.ts

@@ -1,5 +1,5 @@
 import { EventEmitter } from '../events/EventEmitter';
-import { OfferwallConfig } from '../types';
+import { OfferwallConfig } from '../types/index';
 import { ConnectionState } from '../types/connection';
 import { TokenManager } from './TokenManager';
 export declare class SSEConnection {

package/dist/index.esm.js

@@ -332,6 +332,24 @@ class CustomEventSource {
     }
 }
 
+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 SSEConnection {
     constructor(config, eventEmitter, tokenManager) {
         this.config = config;
@@ -606,22 +624,22 @@ class SSEConnection {
 class OfferStore {
     constructor(config) {
         this.offers = new Map();
-        this.playerSnapshot = null;
+        this.player = null;
         this.logger = createLogger(config, 'OfferStore');
     }
-    getSnapshot() {
-        return this.playerSnapshot;
+    getPlayer() {
+        return this.player || null;
     }
-    setSnapshot(snapshot) {
-        this.playerSnapshot = snapshot;
-        this.logger.log('Updated player snapshot:', snapshot);
+    setPlayer(player) {
+        this.player = player;
+        this.logger.log('Updated player:', player);
     }
     /**
      * Set all offers (replaces existing)
      */
     setOffers(offers) {
         this.offers.clear();
-        offers.forEach(offer => {
+        offers.forEach((offer) => {
             this.offers.set(offer.instanceId, offer);
         });
         this.logger.log(`Set ${offers.length} offers`);
@@ -661,16 +679,18 @@ class OfferStore {
      * Get offers filtered by status
      */
     getOffersByStatus(status) {
-        return this.getAllOffers().filter(offer => offer.status === status);
+        return this.getAllOffers().filter((offer) => offer.status === status);
     }
     /**
      * Get active offers (not expired, not claimed)
      */
     getActiveOffers() {
-        return this.getAllOffers().filter(offer => {
+        return this.getAllOffers().filter((offer) => {
             if (!offer.status)
                 return false; // Must have a status
-            return offer.status === 'surfaced' || offer.status === 'viewed' || offer.status === 'claimable';
+            return (offer.status === 'surfaced' ||
+                offer.status === 'viewed' ||
+                offer.status === 'claimable');
         });
     }
     /**
@@ -810,12 +830,11 @@ class AssetHelper {
             case 'exp':
                 id = reward.skillId;
                 break;
-            case 'on_chain':
-                id = reward.assetId;
-                break;
             case 'trust_points':
                 id = 'trust_points';
                 break;
+            case 'loyalty_currency':
+                id = reward.currencyId;
         }
         // Fallback to reward's built-in name, we should add 5x popberry etc
         const formattedName = reward.amount > 1 ? `${reward.amount}x ${reward.name}` : reward.name;
@@ -825,40 +844,23 @@ class AssetHelper {
             if (content) {
                 return {
                     name: content.name || formattedName,
-                    image: content.image || this.config.fallbackRewardImage
+                    image: content.image || this.config.fallbackRewardImage,
                 };
             }
         }
         return {
             name: formattedName,
-            image: this.config.fallbackRewardImage
+            image: this.config.fallbackRewardImage,
         };
     }
     resolveOfferRewards(offer) {
-        return offer.rewards.map(reward => ({
+        return offer.rewards.map((reward) => ({
             ...reward,
             ...this.resolveReward(reward),
         }));
     }
 }
 
-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';
-    }
-};
 const mapEnvToOfferClientUrl = (env) => {
     switch (env) {
         case 'live':
@@ -930,7 +932,7 @@ class OfferwallClient {
                 return;
             }
             this.isInitializing = true;
-            await this.refreshOffersAndSnapshot();
+            await this.refreshOffersAndPlayer();
             await this.connect();
             this.isInitializing = false;
         }
@@ -1089,28 +1091,34 @@ class OfferwallClient {
             kind: 'offer',
         });
     }
-    async refreshOffersAndSnapshot() {
+    getPlayer() {
+        return this.offerStore.getPlayer();
+    }
+    getOffers() {
+        return this.offerStore.getAllOffers();
+    }
+    async refreshOffersAndPlayer() {
         try {
-            const { offers, snapshot } = await this.getOffersAndSnapshot();
+            const { offers, player } = await this.getOffersAndPlayer();
             this.offerStore.setOffers(offers);
-            this.offerStore.setSnapshot(snapshot);
-            this.eventEmitter.emit(OfferEvent.REFRESH, { offers, playerSnapshot: snapshot });
+            this.offerStore.setPlayer(player);
+            this.eventEmitter.emit(OfferEvent.REFRESH, { offers, player: player });
             this.logger.log('Refreshed offers and player snapshot');
         }
         catch (error) {
-            this.handleError(error, 'refreshOffersAndSnapshot');
+            this.handleError(error, 'refreshOffersAndPlayer');
             throw error;
         }
     }
-    async getOffersAndSnapshot() {
+    async getOffersAndPlayer() {
         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');
         }
-        if (!data.snapshot) {
-            throw new Error('No player snapshot returned from offers endpoint');
+        if (!data.player) {
+            throw new Error('No player returned from offers endpoint');
         }
         return data;
     }
@@ -1477,6 +1485,93 @@ const meetsBaseConditions = ({ conditions, playerSnap, addDetails, }) => {
     }
     return { isValid, conditionData: addDetails ? conditionData : undefined };
 };
+const meetsSurfacingConditions = ({ surfacingContexts, surfacingConditions, playerSnap, context, }) => {
+    if (surfacingContexts?.length && !surfacingContexts.includes(context || '')) {
+        // context is not in the list of surfacing contexts, so we don't want to surface this offer
+        return { isValid: false };
+    }
+    const conditions = surfacingConditions;
+    if (conditions?.andTags?.length) {
+        // check if player has all of the tags
+        const hasAllTags = conditions.andTags.every((tag) => playerSnap.tags?.includes(tag));
+        if (!hasAllTags) {
+            return { isValid: false };
+        }
+    }
+    if (conditions?.orTags?.length) {
+        // check if player has any of the tags
+        const hasAnyTags = conditions.orTags.some((tag) => playerSnap.tags?.includes(tag));
+        if (!hasAnyTags) {
+            return { isValid: false };
+        }
+    }
+    if (conditions?.notTags?.length) {
+        // check if player has any of the tags
+        const hasAnyTags = conditions.notTags.some((tag) => playerSnap.tags?.includes(tag));
+        if (hasAnyTags) {
+            return { isValid: false };
+        }
+    }
+    if (conditions?.maxDaysInGame &&
+        (playerSnap.daysInGame || Infinity) > conditions.maxDaysInGame) {
+        return { isValid: false };
+    }
+    if (conditions.loginStreak && (playerSnap.loginStreak || 0) < conditions.loginStreak) {
+        return { isValid: false };
+    }
+    // Check dynamic conditions if present
+    if (conditions.dynamic?.conditions?.length) {
+        if (!meetsDynamicConditions(playerSnap.dynamic || {}, conditions.dynamic)) {
+            return { isValid: false };
+        }
+    }
+    return meetsBaseConditions({ conditions, playerSnap });
+};
+const hasConditions = (conditions) => {
+    if (!conditions)
+        return false;
+    if (Object.keys(conditions.currencies || {}).length > 0)
+        return true;
+    if (Object.keys(conditions.levels || {}).length > 0)
+        return true;
+    if (Object.keys(conditions.stakedTokens || {}).length > 0)
+        return true;
+    if (Object.keys(conditions.memberships || {}).length > 0)
+        return true;
+    if (Object.keys(conditions.quests || {}).length > 0)
+        return true;
+    if (conditions.minTrustScore)
+        return true;
+    if (conditions.maxTrustScore)
+        return true;
+    if (conditions.achievements)
+        return true;
+    if (conditions.minDaysInGame)
+        return true;
+    const surCond = conditions;
+    if (surCond.andTags?.length)
+        return true;
+    if (surCond.orTags?.length)
+        return true;
+    if (surCond.notTags?.length)
+        return true;
+    if (surCond.maxDaysInGame)
+        return true;
+    if (surCond.loginStreak)
+        return true;
+    const compCond = conditions;
+    if (compCond.buyItem)
+        return true;
+    if (compCond.spendCurrency)
+        return true;
+    if (compCond.depositCurrency)
+        return true;
+    if (compCond.login)
+        return true;
+    if (compCond.loginStreak)
+        return true;
+    return false;
+};
 const meetsCompletionConditions = ({ completionConditions, completionTrackers, playerSnap, addDetails = false, }) => {
     if (completionConditions) {
         const conditions = completionConditions;
@@ -1579,8 +1674,84 @@ const meetsCompletionConditions = ({ completionConditions, completionTrackers, p
     }
     return { isValid: true, conditionData: [] };
 };
+/**
+ * Checks if a dynamic object meets a set of dynamic field conditions.
+ * @param dynamicObj - The object with any key and string or number value.
+ * @param conditions - Array of conditions to check.
+ * @returns true if all conditions are met, false otherwise.
+ */
+/**
+ * Evaluates a single dynamic condition against the dynamic object.
+ */
+function evaluateDynamicCondition(dynamicObj, cond) {
+    const val = dynamicObj[cond.key];
+    if (val === undefined)
+        return false;
+    switch (cond.operator) {
+        case '==':
+            return val === cond.compareTo;
+        case '!=':
+            return val !== cond.compareTo;
+        case '>':
+            return (typeof val === 'number' &&
+                typeof cond.compareTo === 'number' &&
+                val > cond.compareTo);
+        case '>=':
+            return (typeof val === 'number' &&
+                typeof cond.compareTo === 'number' &&
+                val >= cond.compareTo);
+        case '<':
+            return (typeof val === 'number' &&
+                typeof cond.compareTo === 'number' &&
+                val < cond.compareTo);
+        case '<=':
+            return (typeof val === 'number' &&
+                typeof cond.compareTo === 'number' &&
+                val <= cond.compareTo);
+        case 'has':
+            return (typeof val === 'string' &&
+                typeof cond.compareTo === 'string' &&
+                val.includes(cond.compareTo));
+        case 'not_has':
+            return (typeof val === 'string' &&
+                typeof cond.compareTo === 'string' &&
+                !val.includes(cond.compareTo));
+        default:
+            return false;
+    }
+}
+/**
+ * Evaluates a group of dynamic conditions with logical links (AND, OR, AND NOT).
+ * @param dynamicObj - The player's dynamic object with any key and string or number value.
+ * @param dynamicGroup - The group of conditions and links to check.
+ * @returns true if the group evaluates to true, false otherwise.
+ */
+function meetsDynamicConditions(dynamicObj, dynamicGroup) {
+    const { conditions, links } = dynamicGroup;
+    if (!conditions || conditions.length === 0)
+        return true;
+    // If no links, treat as AND between all conditions
+    if (!links || links.length === 0) {
+        return conditions.every((cond) => evaluateDynamicCondition(dynamicObj, cond));
+    }
+    // Evaluate the first condition
+    let result = evaluateDynamicCondition(dynamicObj, conditions[0]);
+    for (let i = 0; i < links.length; i++) {
+        const nextCond = evaluateDynamicCondition(dynamicObj, conditions[i + 1]);
+        const link = links[i];
+        if (link === 'AND') {
+            result = result && nextCond;
+        }
+        else if (link === 'OR') {
+            result = result || nextCond;
+        }
+        else if (link === 'AND NOT') {
+            result = result && !nextCond;
+        }
+    }
+    return result;
+}
 
-// Taken from buildon_server/src/commons/types/offer.ts and merged into a single interface
 const PlayerOfferStatuses = [
     'inQueue',
     'surfaced',
@@ -1590,16 +1761,26 @@ const PlayerOfferStatuses = [
     'expired',
 ];
 
-// Taken from buildon_server/src/commons/types/reward.ts
 // Use a const assertion for the array and infer the union type directly
 const rewardKinds = [
     'item',
     'coins',
     'exp',
     'trust_points',
+    'loyalty_currency', // loyalty currency that the player can exchange for rewards like on-chain via withdraw, etc.
     /** on-chain rewards require the builder to send funds to a custodial wallet that we use to send to player wallets*/
-    'on_chain',
 ];
+const rewardSchema = {
+    _id: false,
+    kind: { type: String, enum: rewardKinds },
+    rewardId: String,
+    skillId: String,
+    currencyId: String, // could be a loyalty currency
+    itemId: String,
+    amount: Number,
+    name: String,
+    image: String,
+};
 
-export { AssetHelper, ConnectionState, EventEmitter, OfferEvent, OfferStore, OfferwallClient, PlayerOfferStatuses, SSEConnection, meetsBaseConditions, meetsCompletionConditions, rewardKinds };
+export { AssetHelper, ConnectionState, EventEmitter, OfferEvent, OfferStore, OfferwallClient, PlayerOfferStatuses, SSEConnection, hasConditions, meetsBaseConditions, meetsCompletionConditions, meetsDynamicConditions, meetsSurfacingConditions, rewardKinds, rewardSchema };
 //# sourceMappingURL=index.esm.js.map