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

package/dist/offerwall-sdk.umd.js

@@ -896,6 +896,7 @@
     class OfferwallClient {
         constructor(config) {
             this.isInitializing = false;
+            this.pendingStackedToken = null;
             this.config = {
                 autoConnect: config.autoConnect ?? false,
                 reconnect: config.reconnect ?? true,
@@ -913,12 +914,24 @@
             this.assetHelper = new AssetHelper(this.config);
             this.sseConnection = new SSEConnection(this.config, this.eventEmitter, this.tokenManager);
             this.setupInternalListeners();
+            this.setupStackedLinkDetection();
             if (this.config.autoConnect) {
                 this.initialize().catch((err) => {
                     this.logger.error('Auto-initialization failed:', err);
                 });
             }
         }
+        setupStackedLinkDetection() {
+            if (!this.config.stackedLink?.autoConsume) {
+                return;
+            }
+            const token = this.detectStackedLinkToken();
+            if (token) {
+                this.logger.log('Detected stackedToken in URL');
+                this.pendingStackedToken = token;
+                this.clearStackedTokenFromUrl();
+            }
+        }
         /**
          * Get the offer store instance
          */
@@ -949,9 +962,19 @@
                 this.isInitializing = true;
                 await this.refreshOffersAndPlayer();
                 await this.connect();
+                // Process pending Stacked link token if exists and autoConsume is enabled
+                if (this.pendingStackedToken && this.config.stackedLink?.autoConsume) {
+                    this.logger.log('Processing pending Stacked link token');
+                    const result = await this.consumeStackedLinkToken(this.pendingStackedToken);
+                    this.pendingStackedToken = null;
+                    if (this.config.stackedLink?.onComplete) {
+                        this.config.stackedLink.onComplete(result);
+                    }
+                }
                 this.isInitializing = false;
             }
             catch (error) {
+                this.isInitializing = false;
                 this.handleError(error, 'initialize');
                 throw error;
             }
@@ -1167,6 +1190,91 @@
                 return null;
             return `${dashboardBaseUrl}/auth/enter?token=${token}&gameId=${gameId}`;
         }
+        // ==================== Stacked Link Methods ====================
+        /**
+         * Detect if there's a Stacked link token in the current URL
+         * @returns The token string if found, null otherwise
+         */
+        detectStackedLinkToken() {
+            if (typeof window === 'undefined')
+                return null;
+            try {
+                const params = new URLSearchParams(window.location.search);
+                const token = params.get('stackedToken');
+                if (token && token.length > 0) {
+                    return token;
+                }
+                // for SPA routers that use hash routing
+                if (window.location.hash) {
+                    const hashQuery = window.location.hash.split('?')[1];
+                    if (hashQuery) {
+                        const hashParams = new URLSearchParams(hashQuery);
+                        const hashToken = hashParams.get('stackedToken');
+                        if (hashToken && hashToken.length > 0) {
+                            return hashToken;
+                        }
+                    }
+                }
+                return null;
+            }
+            catch (error) {
+                this.logger.error('Error detecting stacked token:', error);
+                return null;
+            }
+        }
+        /**
+         * Clear the stackedToken from the URL without page reload
+         */
+        clearStackedTokenFromUrl() {
+            if (typeof window === 'undefined')
+                return;
+            try {
+                const url = new URL(window.location.href);
+                url.searchParams.delete('stackedToken');
+                window.history.replaceState({}, '', url.toString());
+                this.logger.log('Cleared stackedToken from URL');
+            }
+            catch (error) {
+                this.logger.error('Error clearing stacked token from URL:', error);
+            }
+        }
+        /**
+         * Consume a Stacked link token to link the current game player
+         * to a Stacked unified user account.
+         *
+         * IMPORTANT: The player must be authenticated (have a valid JWT from tokenProvider)
+         * before calling this method.
+         *
+         * @param token The Stacked link token from the URL
+         * @returns Promise resolving to the link result
+         */
+        async consumeStackedLinkToken(token) {
+            try {
+                const data = await this.postWithAuth('/v1/auth/stacked_link/exchange', { stackedToken: token });
+                return {
+                    linked: data.linked,
+                    alreadyLinked: data.alreadyLinked,
+                };
+            }
+            catch (error) {
+                this.logger.error('Error consuming stacked link token:', error);
+                return {
+                    linked: false,
+                };
+            }
+        }
+        /**
+         * Detects the token from URL, consumes it if player is authenticated.
+         * @returns Promise resolving to the link result, or null if no token found
+         */
+        async processStackedLinkToken() {
+            const token = this.detectStackedLinkToken();
+            if (!token) {
+                return null;
+            }
+            this.clearStackedTokenFromUrl();
+            return this.consumeStackedLinkToken(token);
+        }
         handleError(error, context) {
             this.logger.error(`Error in ${context}:`, error);
             if (this.hooks.onError) {
@@ -1175,6 +1283,19 @@
         }
     }
 
+    const keyPattern = /\{([a-zA-Z_][a-zA-Z0-9_]*)\}/g;
+    // renders template by replacing {keyName} with values from dynamic
+    function renderTemplate(template, dynamic) {
+        if (!template)
+            return '';
+        return template.replace(keyPattern, (match, key) => {
+            if (dynamic && dynamic[key] !== undefined) {
+                return String(dynamic[key]);
+            }
+            return '{?}'; // indicate missing key
+        });
+    }
+
     const meetsBaseConditions = ({ conditions, playerSnap, addDetails, }) => {
         const conditionData = [];
         let isValid = true;
@@ -1500,6 +1621,92 @@
                 }
             }
         }
+        // Validate link count conditions
+        if (conditions?.links && 'entityLinks' in playerSnap) {
+            for (const [linkType, constraint] of Object.entries(conditions.links)) {
+                const linkCount = playerSnap.entityLinks?.filter((link) => link.kind === linkType).length || 0;
+                if (constraint.min !== undefined) {
+                    const isDisqualify = linkCount < constraint.min;
+                    if (addDetails) {
+                        conditionData.push({
+                            isMet: !isDisqualify,
+                            kind: 'links',
+                            trackerAmount: linkCount,
+                            text: `At least ${constraint.min} ${linkType} link(s)`,
+                        });
+                        if (isDisqualify)
+                            isValid = false;
+                    }
+                    else {
+                        if (isDisqualify)
+                            return { isValid: false };
+                    }
+                }
+                if (constraint.max !== undefined) {
+                    const isDisqualify = linkCount > constraint.max;
+                    if (addDetails) {
+                        conditionData.push({
+                            isMet: !isDisqualify,
+                            kind: 'links',
+                            trackerAmount: linkCount,
+                            text: `At most ${constraint.max} ${linkType} link(s)`,
+                        });
+                        if (isDisqualify)
+                            isValid = false;
+                    }
+                    else {
+                        if (isDisqualify)
+                            return { isValid: false };
+                    }
+                }
+            }
+        }
+        // Evaluate dynamic conditions
+        if (conditions?.dynamic?.conditions?.length) {
+            const dynamicResult = meetsDynamicConditions(playerSnap.dynamic || {}, conditions.dynamic);
+            if (addDetails) {
+                conditionData.push({
+                    isMet: dynamicResult,
+                    kind: 'dynamic',
+                    text: renderTemplate(conditions.dynamic.template, playerSnap.dynamic) ||
+                        'Dynamic conditions',
+                });
+                if (!dynamicResult)
+                    isValid = false;
+            }
+            else {
+                if (!dynamicResult)
+                    return { isValid: false };
+            }
+        }
+        if (conditions?.identifiers?.platforms?.length && 'identifiers' in playerSnap) {
+            const playerPlatforms = new Set(playerSnap.identifiers?.map((i) => i.platform.toLowerCase()) || []);
+            const isAndBehaviour = conditions.identifiers.behaviour === 'AND';
+            const platformsToCheck = conditions.identifiers.platforms;
+            let isMet;
+            let displayText;
+            if (isAndBehaviour) {
+                isMet = platformsToCheck.every((platform) => playerPlatforms.has(platform.toLowerCase()));
+                displayText = `Link all: ${platformsToCheck.join(', ')}`;
+            }
+            else {
+                isMet = platformsToCheck.some((platform) => playerPlatforms.has(platform.toLowerCase()));
+                displayText = `Link any: ${platformsToCheck.join(', ')}`;
+            }
+            if (addDetails) {
+                conditionData.push({
+                    isMet,
+                    kind: 'identifiers',
+                    text: displayText,
+                });
+                if (!isMet)
+                    isValid = false;
+            }
+            else {
+                if (!isMet)
+                    return { isValid: false };
+            }
+        }
         return { isValid, conditionData: addDetails ? conditionData : undefined };
     };
     const meetsSurfacingConditions = ({ surfacingConditions, playerSnap, context, playerOffers, }) => {
@@ -1508,6 +1715,13 @@
             // context is not in the list of surfacing contexts, so we don't want to surface this offer
             return { isValid: false };
         }
+        if (surfacingConditions?.targetEntityTypes?.length) {
+            const playerTarget = playerSnap.entityKind || 'default';
+            // check if entity type is allowed
+            if (!surfacingConditions.targetEntityTypes.includes(playerTarget)) {
+                return { isValid: false };
+            }
+        }
         const conditions = surfacingConditions;
         if (conditions?.andTags?.length) {
             // check if player has all of the tags
@@ -1546,12 +1760,6 @@
             (!playerSnap.dateSignedUp || playerSnap.dateSignedUp > conditions.maxDateSignedUp)) {
             return { isValid: false };
         }
-        // Check dynamic conditions if present
-        if (conditions.dynamic?.conditions?.length) {
-            if (!meetsDynamicConditions(playerSnap.dynamic || {}, conditions.dynamic)) {
-                return { isValid: false };
-            }
-        }
         const completedOfferIds = new Set();
         for (const pOffer of playerOffers?.values() || []) {
             if (pOffer.status === 'claimed' || pOffer.status === 'claimable') {
@@ -1587,6 +1795,10 @@
             return true;
         if (conditions.minDaysInGame)
             return true;
+        if (conditions.dynamic?.conditions?.length)
+            return true;
+        if (conditions.identifiers?.platforms?.length)
+            return true;
         const surCond = conditions;
         if (surCond.contexts?.length)
             return true;
@@ -1606,6 +1818,12 @@
             return true;
         if (surCond.completedOffers?.length)
             return true;
+        if (surCond.programmatic)
+            return true;
+        if (surCond.targetEntityTypes?.length)
+            return true;
+        if (surCond.links && Object.keys(surCond.links).length > 0)
+            return true;
         const compCond = conditions;
         if (compCond.context)
             return true;
@@ -1621,6 +1839,10 @@
             return true;
         if (compCond.loginStreak)
             return true;
+        if (compCond.linkedCompletions)
+            return true;
+        if (compCond.dynamicTracker?.conditions?.length)
+            return true;
         return false;
     };
     const meetsCompletionConditions = ({ completionConditions, completionTrackers, playerSnap, addDetails = false, }) => {
@@ -1734,51 +1956,107 @@
                 }
             }
             if (conditions?.social) {
-                const hasAttachedContent = !!completionTrackers?.social?.videoId;
                 const tSocial = completionTrackers?.social;
                 const cSocial = completionConditions.social;
-                let isDisqualify = !hasAttachedContent;
-                if (cSocial?.minLikes && tSocial && (tSocial.likes || 0) < cSocial.minLikes) {
-                    isDisqualify = true;
-                }
-                if (cSocial?.minViews && tSocial && (tSocial.views || 0) < cSocial.minViews) {
-                    isDisqualify = true;
-                }
-                if (cSocial?.minComments && tSocial && (tSocial.comments || 0) < cSocial.minComments) {
+                const mode = cSocial?.mode || 'attach';
+                const hasContent = Boolean(mode === 'accumulate'
+                    ? tSocial?.mode === 'accumulate'
+                    : tSocial && tSocial.mode !== 'accumulate' && !!tSocial.videoId);
+                const minLikes = cSocial?.minLikes || 0;
+                const minViews = cSocial?.minViews || 0;
+                const minComments = cSocial?.minComments || 0;
+                const likes = tSocial?.likes || 0;
+                const views = tSocial?.views || 0;
+                const comments = tSocial?.comments || 0;
+                let isDisqualify = !hasContent;
+                if (likes < minLikes || views < minViews || comments < minComments) {
                     isDisqualify = true;
                 }
                 if (addDetails) {
-                    // Build detailed text about requirements
                     const platformMap = {
-                        'tiktok': 'TikTok',
-                        'instagram': 'Instagram',
-                        'youtube': 'YouTube',
+                        tiktok: 'TikTok',
+                        instagram: 'Instagram',
+                        youtube: 'YouTube',
                     };
-                    const platformText = conditions.social.platforms.map(platform => platformMap[platform]).join(' | ');
-                    let displayText = `Attach a ${platformText} post`;
-                    if (hasAttachedContent && tSocial) {
-                        let socialTexts = [];
-                        if (cSocial?.minLikes ?? 0 > 0) {
-                            socialTexts.push(`${cSocial.minLikes} Likes (${tSocial.likes}/${cSocial.minLikes})`);
-                        }
-                        if (cSocial?.minViews ?? 0 > 0) {
-                            socialTexts.push(`${cSocial.minViews} Views (${tSocial.views}/${cSocial.minViews})`);
-                        }
-                        if (cSocial?.minComments ?? 0 > 0) {
-                            socialTexts.push(`${cSocial.minComments} Comments (${tSocial.comments}/${cSocial.minComments})`);
-                        }
-                        displayText = `Reach:\n${socialTexts.join('\n')}`;
+                    const platformText = conditions.social.platforms
+                        .map((platform) => platformMap[platform])
+                        .join(' | ');
+                    const requiredWords = cSocial?.requiredWords ?? [];
+                    if (mode === 'accumulate') {
+                        const matchCount = (tSocial?.mode === 'accumulate' && tSocial.matchCount) || 0;
+                        conditionData.push({
+                            isMet: hasContent,
+                            kind: 'social',
+                            trackerAmount: matchCount,
+                            text: hasContent
+                                ? `Found ${matchCount} matching ${platformText} post${matchCount !== 1 ? 's' : ''}`
+                                : requiredWords.length > 0
+                                    ? `Post ${platformText} content with ${requiredWords.map((w) => `"${w}"`).join(', ')}`
+                                    : `Post ${platformText} content`,
+                        });
+                    }
+                    else {
+                        const title = (tSocial && tSocial.mode !== 'accumulate' && tSocial.title) || undefined;
+                        conditionData.push({
+                            isMet: hasContent,
+                            kind: 'social',
+                            trackerAmount: 0,
+                            text: !hasContent
+                                ? requiredWords.length > 0
+                                    ? `Attach a ${platformText} post with ${requiredWords.map((w) => `"${w}"`).join(', ')} in the title`
+                                    : `Attach a ${platformText} post`
+                                : `Attached: ${title}`,
+                        });
+                    }
+                    if (minLikes > 0) {
+                        conditionData.push({
+                            isMet: hasContent && likes >= minLikes,
+                            kind: 'social',
+                            trackerAmount: likes,
+                            text: mode === 'accumulate'
+                                ? `Combined ${minLikes} Likes`
+                                : `Reach ${minLikes} Likes`,
+                        });
+                    }
+                    if (minViews > 0) {
+                        conditionData.push({
+                            isMet: hasContent && views >= minViews,
+                            kind: 'social',
+                            trackerAmount: views,
+                            text: mode === 'accumulate'
+                                ? `Combined ${minViews} Views`
+                                : `Reach ${minViews} Views`,
+                        });
                     }
-                    const trackerAmount = (cSocial?.minViews ?? 0) > 0 && (tSocial?.likes ?? 0) < (cSocial.minLikes ?? 0)
-                        ? (tSocial?.likes ?? 0)
-                        : (cSocial?.minComments ?? 0) > 0 && (tSocial?.comments ?? 0) < (cSocial.minComments ?? 0)
-                            ? (tSocial?.comments ?? 0)
-                            : (tSocial?.views ?? 0);
+                    if (minComments > 0) {
+                        conditionData.push({
+                            isMet: hasContent && comments >= minComments,
+                            kind: 'social',
+                            trackerAmount: comments,
+                            text: mode === 'accumulate'
+                                ? `Combined ${minComments} Comments`
+                                : `Reach ${minComments} Comments`,
+                        });
+                    }
+                    if (isDisqualify)
+                        isValid = false;
+                }
+                else {
+                    if (isDisqualify)
+                        return { isValid: false };
+                }
+            }
+            // Linked completions - wait for N linked entities to complete
+            if (conditions?.linkedCompletions?.min) {
+                const currentCount = completionTrackers?.linkedCompletions || 0;
+                const requiredCount = conditions.linkedCompletions.min;
+                const isDisqualify = currentCount < requiredCount;
+                if (addDetails) {
                     conditionData.push({
-                        isMet: hasAttachedContent,
-                        kind: 'social',
-                        trackerAmount,
-                        text: displayText,
+                        isMet: !isDisqualify,
+                        kind: 'linkedCompletions',
+                        trackerAmount: currentCount,
+                        text: `Wait for ${requiredCount} linked ${requiredCount === 1 ? 'entity' : 'entities'} to complete`,
                     });
                     if (isDisqualify)
                         isValid = false;
@@ -1788,6 +2066,22 @@
                         return { isValid: false };
                 }
             }
+            if (conditions?.dynamicTracker?.conditions?.length) {
+                const dynamicResult = meetsDynamicConditions(completionTrackers?.dynamicTracker || {}, conditions.dynamicTracker);
+                if (addDetails) {
+                    conditionData.push({
+                        isMet: dynamicResult,
+                        kind: 'dynamic',
+                        text: renderTemplate(conditions.dynamicTracker.template, completionTrackers?.dynamicTracker) || 'Dynamic conditions',
+                    });
+                    if (!dynamicResult)
+                        isValid = false;
+                }
+                else {
+                    if (!dynamicResult)
+                        return { isValid: false };
+                }
+            }
             const r = meetsBaseConditions({
                 conditions,
                 playerSnap,
@@ -1799,6 +2093,136 @@
         }
         return { isValid: true, conditionData: [] };
     };
+    /**
+     * 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
+     */
+    const meetsCompletionConditionsBeforeExpiry = ({ completionConditions, completionTrackers, playerSnap, expiryTime, }) => {
+        if (!completionConditions)
+            return false;
+        // Check if there are actually any conditions to evaluate
+        if (!hasConditions(completionConditions))
+            return false;
+        // First check if conditions are actually met
+        const conditionsMet = meetsCompletionConditions({
+            completionConditions,
+            completionTrackers,
+            playerSnap,
+        });
+        if (!conditionsMet.isValid)
+            return false;
+        const lastSnapshotUpdate = new Date(playerSnap.snapshotLastUpdated).getTime();
+        /**
+         * Checks if a field was updated after the expiry time.
+         * Returns true if updated AFTER or AT expiry (violates grace period).
+         * Returns false if updated BEFORE expiry (allows grace period).
+         */
+        function wasUpdatedAfterExpiry(data) {
+            let lastUpdated;
+            if (typeof data === 'object' && data !== null && !(data instanceof Date)) {
+                // Object with optional lastUpdated field
+                lastUpdated = data.lastUpdated
+                    ? new Date(data.lastUpdated).getTime()
+                    : lastSnapshotUpdate;
+            }
+            else if (data instanceof Date) {
+                lastUpdated = data.getTime();
+            }
+            else if (typeof data === 'string' || typeof data === 'number') {
+                lastUpdated = new Date(data).getTime();
+            }
+            else {
+                // No data provided, use snapshot timestamp
+                lastUpdated = lastSnapshotUpdate;
+            }
+            return lastUpdated >= expiryTime;
+        }
+        if (completionConditions.currencies) {
+            for (const currencyId in completionConditions.currencies) {
+                const currency = playerSnap.currencies?.[currencyId];
+                if (!currency)
+                    continue;
+                if (wasUpdatedAfterExpiry(currency))
+                    return false;
+            }
+        }
+        if (completionConditions.levels) {
+            for (const skillId in completionConditions.levels) {
+                const level = playerSnap.levels?.[skillId];
+                if (!level)
+                    continue;
+                if (wasUpdatedAfterExpiry(level))
+                    return false;
+            }
+        }
+        if (completionConditions.quests) {
+            for (const questId in completionConditions.quests) {
+                const quest = playerSnap.quests?.[questId];
+                if (!quest)
+                    continue;
+                if (wasUpdatedAfterExpiry(quest))
+                    return false;
+            }
+        }
+        if (completionConditions.memberships) {
+            for (const membershipId in completionConditions.memberships) {
+                const membership = playerSnap.memberships?.[membershipId];
+                if (!membership)
+                    continue;
+                if (wasUpdatedAfterExpiry(membership))
+                    return false;
+            }
+        }
+        if (completionConditions.achievements) {
+            for (const achievementId in completionConditions.achievements) {
+                const achievement = playerSnap.achievements?.[achievementId];
+                if (!achievement)
+                    continue;
+                if (wasUpdatedAfterExpiry(achievement))
+                    return false;
+            }
+        }
+        if (completionConditions.stakedTokens) {
+            for (const tokenId in completionConditions.stakedTokens) {
+                const stakedToken = playerSnap.stakedTokens?.[tokenId];
+                if (!stakedToken)
+                    continue;
+                const lastStakeTime = new Date(stakedToken.lastStake ?? 0).getTime();
+                const lastUnstakeTime = new Date(stakedToken.lastUnstake ?? 0).getTime();
+                const lastUpdated = Math.max(lastStakeTime, lastUnstakeTime);
+                if (lastUpdated >= expiryTime)
+                    return false;
+            }
+        }
+        if (completionConditions.minTrustScore !== undefined ||
+            completionConditions.maxTrustScore !== undefined) {
+            if (wasUpdatedAfterExpiry(playerSnap.trustLastUpdated))
+                return false;
+        }
+        if (completionConditions.minDaysInGame !== undefined) {
+            if (wasUpdatedAfterExpiry(playerSnap.daysInGameLastUpdated))
+                return false;
+        }
+        if (completionConditions.login || completionConditions.loginStreak) {
+            if (wasUpdatedAfterExpiry())
+                return false;
+        }
+        if (completionConditions.social) {
+            // Check if social content was attached/validated after expiry
+            if (completionTrackers?.social?.lastChecked) {
+                if (wasUpdatedAfterExpiry(completionTrackers.social.lastChecked))
+                    return false;
+            }
+        }
+        // All conditions were met before expiry
+        return true;
+    };
     /**
      * Checks if a dynamic object meets a set of dynamic field conditions.
      * @param dynamicObj - The object with any key and string or number value.
@@ -1812,38 +2236,35 @@
         const val = dynamicObj[cond.key];
         if (val === undefined)
             return false;
+        const isNumber = typeof val === 'number';
+        const compareTo = isNumber ? Number(cond.compareTo) : String(cond.compareTo);
         switch (cond.operator) {
             case '==':
-                return val === cond.compareTo;
+                return val === 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;
+                return val !== compareTo;
         }
+        if (isNumber && typeof compareTo === 'number') {
+            switch (cond.operator) {
+                case '>':
+                    return val > compareTo;
+                case '>=':
+                    return val >= compareTo;
+                case '<':
+                    return val < compareTo;
+                case '<=':
+                    return val <= compareTo;
+            }
+        }
+        else if (!isNumber && typeof compareTo === 'string') {
+            switch (cond.operator) {
+                case 'has':
+                    return val.includes(compareTo);
+                case 'not_has':
+                    return !val.includes(compareTo);
+            }
+        }
+        return false;
     }
     /**
      * Evaluates a group of dynamic conditions with logical links (AND, OR, AND NOT).
@@ -1876,11 +2297,34 @@
         }
         return result;
     }
+    /**
+     * 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
+     */
+    function meetsClaimableConditions({ claimableConditions, playerOfferTrackers, claimableTrackers, }) {
+        if (!claimableConditions) {
+            return { isValid: true };
+        }
+        if (claimableConditions.siblingCompletions) {
+            const siblingCount = playerOfferTrackers?.siblingPlayerOffer_ids?.length ?? 0;
+            let completedCount = claimableTrackers?.siblingCompletions ?? 0;
+            if (completedCount == -1)
+                completedCount = siblingCount; // treat -1 as all completed
+            // if siblings exist but not all are completed, return false
+            if (siblingCount > 0 && completedCount < siblingCount) {
+                return { isValid: false };
+            }
+        }
+        return { isValid: true };
+    }
 
+    const offerListenerEvents = ['claim_offer'];
     const PlayerOfferStatuses = [
-        'inQueue',
+        // 'inQueue', // fuck this shit. just don't surface offers if their offer plate is full.
         'surfaced',
         'viewed',
+        'completed', // Individual completionConditions met, waiting for claimableConditions (e.g., siblings)
         'claimable',
         'claimed',
         'expired',
@@ -1893,12 +2337,26 @@
         'exp',
         'trust_points',
         'loyalty_currency', // loyalty currency that the player can exchange for rewards like on-chain via withdraw, etc.
+        'discount', // handled by the external dev, using the rewardId to identify what it is for in their system
         /** on-chain rewards require the builder to send funds to a custodial wallet that we use to send to player wallets*/
     ];
     const rewardSchema = {
         _id: false,
         kind: { type: String, enum: rewardKinds },
-        rewardId: String,
+        rewardId: {
+            type: String,
+            validate: {
+                validator: function (value) {
+                    // Require rewardId for item, coins, loyalty_currency, exp, and discount kinds
+                    const requiresRewardId = ['item', 'coins', 'loyalty_currency', 'exp', 'discount'].includes(this.kind);
+                    if (requiresRewardId) {
+                        return !!value;
+                    }
+                    return true;
+                },
+                message: 'rewardId is required for reward kinds: item, coins, loyalty_currency, exp, and discount',
+            },
+        },
         skillId: String,
         currencyId: String, // could be a loyalty currency
         itemId: String,
@@ -1915,9 +2373,12 @@
     exports.SSEConnection = SSEConnection;
     exports.hasConditions = hasConditions;
     exports.meetsBaseConditions = meetsBaseConditions;
+    exports.meetsClaimableConditions = meetsClaimableConditions;
     exports.meetsCompletionConditions = meetsCompletionConditions;
+    exports.meetsCompletionConditionsBeforeExpiry = meetsCompletionConditionsBeforeExpiry;
     exports.meetsDynamicConditions = meetsDynamicConditions;
     exports.meetsSurfacingConditions = meetsSurfacingConditions;
+    exports.offerListenerEvents = offerListenerEvents;
     exports.rewardKinds = rewardKinds;
     exports.rewardSchema = rewardSchema;