@pixels-online/pixels-client-js-sdk 1.14.0 → 1.16.0

package/dist/types/player.d.ts

@@ -1,4 +1,5 @@
-import { IBlockchainSyncStatus, ICryptoBalance } from './user_wallet';
+import { Stringable } from '.';
+import { IBlockchainSyncStatus } from './blockchain/user_wallet';
 export type IClientPlayer = {
     snapshot: Omit<IPlayerSnapshot, 'tags' | 'tagsLastUpdated'>;
     data?: IPlayerData | null;
@@ -7,10 +8,12 @@ export interface IPlayerSnapshot {
     _id: string;
     gameId: string;
     playerId: string;
+    /** when this was last linked to a unified user */
+    unifiedUserLinkedAt?: number;
+    /** when this was last unlinked to a unified user */
+    unifiedUserUnlinkedAt?: number;
     /** player that referred this player to this game */
     referredById?: string;
-    /** did this player complete referee and can claim rewards now? Store this here so we don't need to do another db lookup */
-    refereeRewardsClaimable?: boolean;
     username?: string;
     snapshotLastUpdated: number;
     offersLastChecked?: number;
@@ -56,20 +59,30 @@ export interface IPlayerSnapshot {
         expiresAt?: number;
         lastUpdated?: number;
     }>;
+    /** auth identifiers. like social tiktok or email or sms or whatever */
+    identifiers?: Array<{
+        /** id */
+        identifier: string;
+        /** sms/email/tiktok etc */
+        platform: string;
+        lastUpdated: number;
+    }>;
     cryptoWallets?: Array<{
         address: string;
         lastUpdated?: number;
     }>;
-    /** wallets that this player has sent on-chain rewards to */
-    rewardWallets?: Array<{
-        address: string;
-        /** list of chains that this wallet has received funds from */
-        chainIds: Array<number>;
-        /** list of contract IDs that this wallet has received funds from */
-        contractIds: Array<string>;
-    }>;
     tags?: Array<string>;
     tagsLastUpdated?: number;
+    entityKind?: string;
+    /**
+     * Links to other entities (players, pets, guilds, etc.)
+     */
+    entityLinks?: Array<{
+        /** if undefined, it means same game */
+        gameId?: string;
+        playerId: string;
+        kind?: string;
+    }>;
     /**
      * collection of information about IP address player connected from
      */
@@ -82,10 +95,30 @@ export type Restriction = {
     eventCount: number;
     message?: string;
 };
+export interface IPlayerDataCurrency {
+    /**
+     * balance held
+     */
+    balance: number;
+    /**
+     * total amount deposited
+     */
+    in?: number;
+    /**
+     * total amount withdrawn
+     */
+    out?: number;
+    /**
+     * last updated timestamp
+     * if not present, means never updated
+     */
+    lastUpdated?: number;
+}
 export interface IPlayerData {
+    _id?: Stringable;
     gameId: string;
     playerId: string;
-    currencies?: Record<string, ICryptoBalance>;
+    currencies?: Record<string, IPlayerDataCurrency>;
     blockchainSync?: Record<string, IBlockchainSyncStatus>;
     restriction?: Restriction;
 }
@@ -165,6 +198,26 @@ export interface IBaseCondition {
         /** if a min number of quest completions is required */
         completions?: number;
     }>;
+    /**
+     * For player snapshot entities that are linked to other player snap entities,
+     * what are the min and max number of links of a specific link kind?
+     * Keys are link kinds (e.g., "pet", "guild", "npc", etc.)
+     */
+    links?: Record<string, {
+        /** minimum number of links of this type required */
+        min?: number;
+        /** maximum number of links of this type allowed */
+        max?: number;
+    }>;
+    /** dynamic field conditions */
+    dynamic?: IDynamicGroup;
+    /** Auth platform identifiers condition */
+    identifiers?: {
+        /** List of auth platforms to check (e.g., 'tiktok', 'google', 'email') */
+        platforms: string[];
+        /** 'AND' = player must have ALL platforms, 'OR' = player must have ANY platform */
+        behaviour: 'AND' | 'OR';
+    };
 }
 export interface ISurfacingCondition extends IBaseCondition {
     /** number of days that the player has logged in-game. Not the absolute amount of time playing the game. But number of days they have logged in for.
@@ -177,8 +230,6 @@ export interface ISurfacingCondition extends IBaseCondition {
     orTags?: Array<string>;
     /** player cannot have any of these tags */
     notTags?: Array<string>;
-    /** dynamic field conditions for surfacing */
-    dynamic?: IDynamicGroup;
     /** minimum signup date (timestamp) - player must have signed up after this date */
     minDateSignedUp?: number;
     /** maximum signup date (timestamp) - player must have signed up before this date */
@@ -189,6 +240,8 @@ export interface ISurfacingCondition extends IBaseCondition {
     contexts?: Array<string>;
     /** if true, offer can only be surfaced programmatically (e.g., via spawnLinkedOffer) - never through normal auto-surfacing */
     programmatic?: boolean;
+    /** entity types that this offer can surface to - undefined or empty means only regular players. */
+    targetEntityTypes?: string[];
 }
 /** conditions that must be met for an already surfaced offer to be claimable */
 export interface ICompletionCondition extends IBaseCondition {
@@ -215,6 +268,8 @@ export interface ICompletionCondition extends IBaseCondition {
     };
     /** social media content condition - player must attach content meeting requirements */
     social?: {
+        /** 'attach' (default) = user attaches single content, 'accumulate' = auto-sum all matching content */
+        mode?: 'attach' | 'accumulate';
         /** platforms accepted (OR logic) - e.g., ['tiktok', 'instagram', 'youtube'] */
         platforms: string[];
         /** words that must ALL appear in video title or description (case-insensitive). Hashtags must match exactly including # */
@@ -235,6 +290,19 @@ export interface ICompletionCondition extends IBaseCondition {
         id: string;
         name: string;
     };
+    /**
+     * Linked completions - wait for N linked entities to complete their offers
+     */
+    linkedCompletions?: {
+        /** Number of linked entity completions required */
+        min: number;
+    };
+    /**
+     * Dynamic field tracker - tracks changes to dynamic fields AFTER offer surfacing.
+     * Unlike the base `dynamic` condition which checks snapshot totals,
+     * this tracks per-offer values since surfacing.
+     */
+    dynamicTracker?: IDynamicGroup;
 }
 /**
  * TypeScript interface for dynamicGroupSchema
@@ -252,6 +320,44 @@ export type DynamicConditionLink = 'AND' | 'OR' | 'AND NOT';
 export interface IDynamicGroup {
     conditions: Array<IDynamicCondition>;
     links?: Array<DynamicConditionLink>;
+    /** Display template using {keyName} syntax for referenced dynamic keys */
+    template?: string;
+}
+/** Social tracker for attach mode - user manually attaches a single piece of content */
+export interface ISocialTrackerAttach {
+    /** 'attach' or undefined = user-attached single content */
+    mode?: 'attach';
+    /** platform name - tiktok, instagram, or youtube */
+    platform: string;
+    /** video ID on the platform */
+    videoId: string;
+    /** platform specific user ID */
+    userId: string;
+    /** cached video title for display */
+    title?: string;
+    /** cached view count */
+    views: number;
+    /** cached like count */
+    likes?: number;
+    /** cached comment count */
+    comments?: number;
+    /** timestamp of last validation check (for 5-minute cache) */
+    lastChecked: Date;
+}
+/** Social tracker for accumulate mode - auto-sum all matching content */
+export interface ISocialTrackerAccumulate {
+    /** 'accumulate' = auto-sum all matching content */
+    mode: 'accumulate';
+    /** sum of view counts across all matching content */
+    views: number;
+    /** sum of like counts across all matching content */
+    likes?: number;
+    /** sum of comment counts across all matching content */
+    comments?: number;
+    /** timestamp of last validation check (for 5-minute cache) */
+    lastChecked: Date;
+    /** number of matching content items */
+    matchCount: number;
 }
 /** tracking the player's status for completing the conditions to claim the offer, if
  * required.
@@ -266,25 +372,19 @@ export interface ICompletionTrackers {
     /** the number of days that have been consecutively logged in at the time of surfacing this offer */
     currentLoginStreak?: number;
     /** tracks attached social media content and cached validation state */
-    social?: {
-        /** platform name - tiktok, instagram, or youtube */
-        platform: string;
-        /** video ID on the platform */
-        videoId: string;
-        /** cached video title for display */
-        title?: string;
-        /** cached view count */
-        views: number;
-        /** cached like count */
-        likes?: number;
-        /** cached comment count */
-        comments?: number;
-        /** timestamp of last validation check (for 1-hour cache) */
-        lastChecked: Date;
-        /** platform specific user ID */
-        userId: string;
-    };
+    social?: ISocialTrackerAttach | ISocialTrackerAccumulate;
     login?: boolean;
     /** completed context for this player */
     context?: string;
+    /**
+     * Count of linked entities that have completed their offers.
+     * For example a referrer refers 5 other referees that have all
+     * completed the referral criteria. this would then be a value of 5.
+     */
+    linkedCompletions?: number;
+    /**
+     * Tracked dynamic field values per key.
+     * Key = dynamic field key, Value = tracked value since offer surfaced
+     */
+    dynamicTracker?: Record<string, string | number>;
 }

package/dist/types/reward.d.ts

@@ -4,12 +4,6 @@ export interface IReward {
     /** if the trigger is type daily-login, which day is this reward for? */
     /** reward id for rewards of kind item, coins, exp or loyalty currency */
     rewardId?: string;
-    /** @deprecated in favour of rewardId */
-    skillId?: string;
-    /** @deprecated in favour of rewardId */
-    currencyId?: string;
-    /** @deprecated in favour of rewardId */
-    itemId?: string;
     /** amount of reward to give. If kind is discount, then this refers to the discount amount, as a fraction */
     amount: number;
     /** public facing name for this reward */
@@ -18,17 +12,24 @@ export interface IReward {
     image?: string;
 }
 export type RewardKind = (typeof rewardKinds)[number];
+/** for client side sdk */
 export interface IResolvedReward extends IReward {
     image?: string;
 }
-export declare const rewardKinds: readonly ["item", "coins", "exp", "trust_points", "loyalty_currency"];
+export declare const rewardKinds: readonly ["item", "coins", "exp", "trust_points", "loyalty_currency", "discount"];
 export declare const rewardSchema: {
     _id: boolean;
     kind: {
         type: StringConstructor;
-        enum: readonly ["item", "coins", "exp", "trust_points", "loyalty_currency"];
+        enum: readonly ["item", "coins", "exp", "trust_points", "loyalty_currency", "discount"];
+    };
+    rewardId: {
+        type: StringConstructor;
+        validate: {
+            validator: (this: IReward, value: string | undefined) => boolean;
+            message: string;
+        };
     };
-    rewardId: StringConstructor;
     skillId: StringConstructor;
     currencyId: StringConstructor;
     itemId: StringConstructor;

package/dist/utils/conditions.d.ts

@@ -1,9 +1,9 @@
 import { ISurfacingCondition, IPlayerSnapshot, ICompletionCondition, IBaseCondition, ICompletionTrackers } from '../types/player';
 import { IDynamicGroup } from '../types/player';
-import { IPlayerOffer } from '../types/offer';
+import { IOffer, IPlayerOffer, IPlayerOfferTrackers, IStrippedSnapshot } from '../types/offer';
 export declare const meetsBaseConditions: ({ conditions, playerSnap, addDetails, }: {
     conditions: IBaseCondition;
-    playerSnap: IPlayerSnapshot;
+    playerSnap: IPlayerSnapshot | IStrippedSnapshot;
     addDetails?: boolean;
 }) => {
     isValid: boolean;
@@ -38,7 +38,7 @@ export declare const hasConditions: (conditions: ICompletionCondition | ISurfaci
 export declare const meetsCompletionConditions: ({ completionConditions, completionTrackers, playerSnap, addDetails, }: {
     completionConditions: ICompletionCondition;
     completionTrackers?: ICompletionTrackers;
-    playerSnap: IPlayerSnapshot;
+    playerSnap: IPlayerSnapshot | IStrippedSnapshot;
     addDetails?: boolean;
 }) => {
     isValid: boolean;
@@ -52,6 +52,22 @@ export declare const meetsCompletionConditions: ({ completionConditions, complet
         text: string;
     }[];
 };
+/**
+ * Checks if completion conditions were met before a specific expiry time.
+ * Returns true if all relevant condition fields were updated before expiryTime.
+ *
+ * @param completionConditions - The completion conditions to check
+ * @param completionTrackers - The completion trackers (for buyItem, spendCurrency, etc.)
+ * @param playerSnap - The player snapshot with field timestamps
+ * @param expiryTime - The expiry timestamp in milliseconds
+ * @returns true if all conditions were met before expiry, false otherwise
+ */
+export declare const meetsCompletionConditionsBeforeExpiry: ({ completionConditions, completionTrackers, playerSnap, expiryTime, }: {
+    completionConditions: ICompletionCondition;
+    completionTrackers?: ICompletionTrackers;
+    playerSnap: IPlayerSnapshot;
+    expiryTime: number;
+}) => boolean;
 /**
  * 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.
@@ -59,3 +75,15 @@ export declare const meetsCompletionConditions: ({ completionConditions, complet
  * @returns true if the group evaluates to true, false otherwise.
  */
 export declare function meetsDynamicConditions(dynamicObj: Record<string, string | number>, dynamicGroup: IDynamicGroup): boolean;
+/**
+ * Checks if a PlayerOffer meets its claimable conditions (completed -> claimable transition).
+ * @param claimableConditions - The offer's claimableConditions (from IOffer)
+ * @param claimableTrackers - The player offer's claimableTrackers
+ */
+export declare function meetsClaimableConditions({ claimableConditions, playerOfferTrackers, claimableTrackers, }: {
+    claimableConditions?: IOffer['claimableConditions'];
+    playerOfferTrackers?: IPlayerOfferTrackers;
+    claimableTrackers?: IPlayerOffer['claimableTrackers'];
+}): {
+    isValid: boolean;
+};

package/dist/utils/template.d.ts

@@ -0,0 +1,2 @@
+export declare function extractTemplateKeys(template: string | undefined): Set<string>;
+export declare function renderTemplate(template: string | undefined, dynamic: Record<string, string | number> | undefined): string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pixels-online/pixels-client-js-sdk",
-  "version": "1.14.0",
+  "version": "1.16.0",
   "description": "Pixels Client JS SDK",
   "main": "dist/index.js",
   "module": "dist/index.esm.js",
@@ -67,6 +67,7 @@
     "prettier": "^3.6.2",
     "rimraf": "^6.0.1",
     "rollup": "^4.50.1",
+    "semantic-release": "25.0.2",
     "ts-jest": "^29.4.1",
     "ts-node": "^10.9.2",
     "tslib": "^2.8.1",