@lumiastream/lumia-types 3.9.0 → 3.9.2

package/dist/custom-code/custom-actions.md

@@ -69,4 +69,67 @@ These are the built-in `type` values for each system base.
 
 > Tip: most of the `lumia` and `overlay` actions already have dedicated helper functions (`tts`, `chatbot`, `overlaySetTextContent`, etc.) in `helper-functions.md`. Reach for `actions()` mainly when you need an integration action that does not have a helper yet.
 
+### Common `lumia` action examples
+
+Most `lumia` actions have a dedicated helper already (`chatbot`, `tts`, `playAudio`, `setVariable`, etc.) — prefer those. Reach for `actions()` for the engagement / system features that have no helper. The `value` fields are not uniform across types, so if you need a type not shown here, set that action up once in the normal action editor to read off its fields. Verified examples:
+
+```js
+async function() {
+    // Song requests
+    await actions([{ base: "lumia", type: "addSongRequest", value: { value: "never gonna give you up" } }]); // a search term or url
+    await actions([{ base: "lumia", type: "skipSongRequest" }]);
+
+    // Raffle (ends_after is in seconds; raffleStop / raffleEnd take no value)
+    await actions([{ base: "lumia", type: "raffleStart", value: { title: "My Raffle", auto_end: true, ends_after: 120 } }]);
+
+    // Viewer queue
+    await actions([{ base: "lumia", type: "viewerQueueEntry", value: { value: "{{username}}" } }]);
+
+    // Stream mode and connections
+    await actions([{ base: "lumia", type: "setStreamMode", value: { on: true } }]);
+    await actions([{ base: "lumia", type: "setConnection", value: { value: "obs", on: true } }]); // on:true enables, false disables
+
+    // Counter (operator is one of + - * /)
+    await actions([{ base: "lumia", type: "updateCounter", value: { value: "deaths", message: "1", operator: "+" } }]);
+    done();
+}
+```
+
+### OBS (v5) actions
+
+OBS has a dedicated helper, so you do **not** need `actions()` for it: pass any OBS websocket v5 request to `sendRawObsJson({ "request-type": "...", ...params })` (see `helper-functions.md`). The `request-type` and fields are exactly the same ones Lumia's OBS action editor uses. Common ones:
+
+```js
+async function() {
+    // Scenes
+    sendRawObsJson({ "request-type": "SetCurrentProgramScene", "sceneName": "My Scene" });
+    sendRawObsJson({ "request-type": "SetCurrentPreviewScene", "sceneName": "My Scene" });
+
+    // Source visibility (by name — Lumia resolves the scene item id for you)
+    sendRawObsJson({ "request-type": "SetSceneItemEnabled", "sceneName": "My Scene", "inputName": "My Source", "sceneItemEnabled": true });
+    sendRawObsJson({ "request-type": "SetSourceFilterEnabled", "sourceName": "My Source", "filterName": "My Filter", "filterEnabled": true });
+
+    // Audio
+    sendRawObsJson({ "request-type": "SetInputMute", "inputName": "Mic/Aux", "inputMuted": true });
+    sendRawObsJson({ "request-type": "ToggleInputMute", "inputName": "Mic/Aux" });
+    sendRawObsJson({ "request-type": "SetInputVolume", "inputName": "Mic/Aux", "inputVolumeMul": 1 });
+
+    // Source settings (url / text / file / image / media)
+    sendRawObsJson({ "request-type": "SetInputSettings", "inputName": "Browser", "inputSettings": { "url": "https://lumiastream.com" } });
+
+    // Media, transitions, screenshot
+    sendRawObsJson({ "request-type": "TriggerMediaInputAction", "inputName": "My Video", "mediaAction": "OBS_WEBSOCKET_MEDIA_INPUT_ACTION_RESTART" });
+    sendRawObsJson({ "request-type": "SetCurrentSceneTransition", "transitionName": "Fade" });
+
+    // Recording / streaming / replay buffer / virtual cam (no params)
+    sendRawObsJson({ "request-type": "StartRecord" });
+    sendRawObsJson({ "request-type": "ToggleStream" });
+    sendRawObsJson({ "request-type": "SaveReplayBuffer" });
+    sendRawObsJson({ "request-type": "StartVirtualCam" });
+    done();
+}
+```
+
+Other available request-types include `SetCurrentProfile`, `SetCurrentSceneCollection`, `CreateInput`, `RemoveInput`, `SetSceneItemTransform`, `SetSceneItemBlendMode`, `SetInputAudioMonitorType`, `TriggerHotkeyByName`, `SetStudioModeEnabled`, `SendStreamCaption`, and the `Start/Stop/Toggle` variants for recording, streaming, replay buffer and virtual cam — the same list as the OBS action editor.
+
 This documentation can get extremely broad for every integration, so if you get stuck please visit our [**Discord**](https://discord.gg/R8rCaKb) to ask us any questions.

package/dist/custom-code/examples/roll-dice.md

@@ -27,3 +27,31 @@ async function() {
 **code blocks** like the one above 👆 have a copy button on the **top right corner** click it then paste in Lumia stream
 
 :::
+
+## Show an OBS source and play a sound
+
+You can drive OBS and audio straight from the code with the built-in helpers — there is no need to make a separate command and call it by an id. This rolls a dice, shows the matching `Dice1`–`Dice6` source in your scene, plays a sound on a 6, then hides the source again.
+
+```js
+async function() {
+    const roll = Math.ceil(Math.random() * 6);
+    const sceneName = "IN-GAME ACTION";
+    const sourceName = "Dice" + roll;
+
+    chatbot({ message: "{{username}} rolled a " + roll + "!" });
+
+    // Show the matching dice source. Lumia finds the source's id from its name for you
+    sendRawObsJson({ "request-type": "SetSceneItemEnabled", "sceneName": sceneName, "inputName": sourceName, "sceneItemEnabled": true });
+
+    // Play a celebration sound only on a 6
+    if (roll === 6) {
+        playAudio({ path: "C:\\sounds\\gold.mp3", volume: 100 });
+    }
+
+    // Leave it on screen for 6 seconds, then hide it again
+    await delay(6000);
+    sendRawObsJson({ "request-type": "SetSceneItemEnabled", "sceneName": sceneName, "inputName": sourceName, "sceneItemEnabled": false });
+
+    done();
+}
+```

package/dist/custom-code/gpt-instructions.md

@@ -41,6 +41,16 @@ You generate **Lumia Stream Custom Code**: JavaScript snippets that a streamer p
 8. For `callAlert`, the `name` must be a valid alert key from the list in `helper-functions.md` (e.g. `twitch-subscriber`, `kick-follower`, `kofi-donation`). Do not guess keys that aren't on that list.
 9. If a capability is not documented, say so clearly and offer a documented alternative rather than fabricating an API.
 
+## Use built-in helpers directly — never command IDs
+
+Run actions straight from the code with the documented helpers. Do **not** tell the streamer to first build a separate Lumia Command/Alert and then call it by an ID, and never output placeholder IDs like `REPLACE_WITH_..._COMMAND_ID`. There is **no** `executeCommand` global. `callCommand`, `callChatbotCommand` and `callAlert` take a **name** and only trigger something the streamer has *already* created — they are not a way to change scenes or play sounds.
+
+- **OBS scene change:** `sendRawObsJson({ "request-type": "SetCurrentProgramScene", "sceneName": "My Scene" })`
+- **OBS show/hide a source (by name):** `sendRawObsJson({ "request-type": "SetSceneItemEnabled", "sceneName": "My Scene", "inputName": "My Source", "sceneItemEnabled": true })` — set `sceneItemEnabled: false` to hide. Lumia looks up the source's id from the name for you, so you never need a numeric `sceneItemId`.
+- **Any other OBS request:** the same pattern through `sendRawObsJson` (for example `SetInputMute`, `TriggerMediaInputAction`, `SetCurrentSceneTransition`).
+- **Play audio:** `playAudio({ path: "C:\\sounds\\gold.mp3", volume: 100 })` — a URL works too and `playSound` is an alias. Use `await playAudio({ ..., waitForAudioToStop: true })` to wait for it to finish.
+- For an integration action that has no dedicated helper, use `actions([...])` (see `custom-actions.md`).
+
 ## Quality checklist before returning code
 
 - Wrapped in `async function() { ... }` and calls `done()` once.

package/dist/custom-code/helper-functions.md

@@ -456,16 +456,21 @@ async function() {
 
 ### Send Raw OBS JSON
 
-`sendRawObsJson(value: { request-type: string; sceneName?: string; sceneItemId?: number; [key: string]: any })`: You can send raw JSON to OBS that will automatically handle the context id. Just send end the request type and your other parameters and Lumia Stream will take care of the rest
+`sendRawObsJson(value: { request-type: string; sceneName?: string; inputName?: string; sceneItemId?: number; [key: string]: any })`: You can send raw JSON to OBS that will automatically handle the context id. Just send the request type and your other parameters and Lumia Stream will take care of the rest. This is the simplest way to drive OBS from custom code — you do not need to build a separate OBS command or alert and call it by id.
 
 ```js
 async function() {
-    sendRawObsJson({
-        "request-type": "SetSceneItemEnabled",
-        "sceneItemEnabled": true,
-        "sceneItemId": 1,
-        "sceneName": "Scene 1"
-    });
+    // Change the active scene
+    sendRawObsJson({ "request-type": "SetCurrentProgramScene", "sceneName": "My Scene" });
+
+    // Show a source by its name. Lumia resolves the scene item id from the name for you, so no numeric id is needed
+    sendRawObsJson({ "request-type": "SetSceneItemEnabled", "sceneName": "My Scene", "inputName": "My Source", "sceneItemEnabled": true });
+
+    // Hide that same source again by passing false
+    sendRawObsJson({ "request-type": "SetSceneItemEnabled", "sceneName": "My Scene", "inputName": "My Source", "sceneItemEnabled": false });
+
+    // You can still target a source by its numeric sceneItemId if you already know it
+    sendRawObsJson({ "request-type": "SetSceneItemEnabled", "sceneName": "Scene 1", "sceneItemId": 1, "sceneItemEnabled": true });
 }
 ```
 

package/dist/esm/index.js

@@ -1,5 +1,6 @@
 export { LumiaStreamingSites, LumiaActivityCommandTypes, LumiaExternalActivityCommandTypes, LumiaAlertValues, LumiaAlertFriendlyValues, LumiaActivityOriginTypes, LumiaActivityApiValueType, LumiaActivityNoValueTypes, LumiaActivityTestType, } from './activity.types.js';
 export { LumiaVariationConditions, LumiaVariationCurrency, VariationCurrencySymbol, LumiaRedemptionCurrency, LumiaRedemptionCurrencySymbol, LumiaAlertConfigs, } from './alert.types.js';
+export { checkAlertVariation, resetVariationCumulativeTracking, sanitizeVariationVariableReference, } from './variation.helpers.js';
 export { LumiaIntegrations, LumiaEventTypes, } from './event.types.js';
 export { LumiaEventListTypes, LumiaMapAlertTypeToEventListType, AlertsToFilter, PlatformsToFilter, LumiaEventListTypeColors, getEventListCategoryColor } from './eventlist.types.js';
 export { SystemVariables, ReservedVariables, AllVariables, getAcceptedVariableName, getAcceptedVariableNames, } from './variables.types.js';

package/dist/esm/variation.helpers.js

@@ -0,0 +1,432 @@
+import { LumiaVariationConditions, LumiaVariationCurrency } from './alert.types.js';
+const lastCountMultipleIdxByKey = new Map();
+const subscriptionOrderNumbers = {
+    [LumiaVariationConditions.GIFT_SUB_EQUAL]: 1,
+    [LumiaVariationConditions.GIFT_SUB_GREATER]: 2,
+    [LumiaVariationConditions.IS_GIFT]: 3,
+    [LumiaVariationConditions.SUBSCRIBED_MONTHS_EQUAL]: 4,
+    [LumiaVariationConditions.SUBSCRIBED_MONTHS_GREATER]: 5,
+    [LumiaVariationConditions.IS_PRIME]: 6,
+    [LumiaVariationConditions.EQUAL_SELECTION]: 7,
+    [LumiaVariationConditions.RANDOM]: 8,
+};
+const variationBucketTypes = {
+    equals: [
+        LumiaVariationConditions.EQUAL_NUMBER,
+        LumiaVariationConditions.EQUAL_VARIABLE,
+        LumiaVariationConditions.EQUAL_CURRENCY_NUMBER,
+        LumiaVariationConditions.EQUAL_SELECTION,
+        LumiaVariationConditions.EQUAL_STRING,
+        LumiaVariationConditions.EQUAL_USERNAME,
+        LumiaVariationConditions.EQUAL_USER_LEVEL,
+        LumiaVariationConditions.SUBSCRIBED_MONTHS_EQUAL,
+        LumiaVariationConditions.GIFT_SUB_EQUAL,
+        LumiaVariationConditions.COUNT_IS_MULTIPLE_OF,
+    ],
+    greaters: [
+        LumiaVariationConditions.GREATER_NUMBER,
+        LumiaVariationConditions.GREATER_CURRENCY_NUMBER,
+        LumiaVariationConditions.SUBSCRIBED_MONTHS_GREATER,
+        LumiaVariationConditions.GIFT_SUB_GREATER,
+    ],
+    lessers: [LumiaVariationConditions.LESS_NUMBER],
+    checks: [LumiaVariationConditions.IS_GIFT, LumiaVariationConditions.IS_PRIME],
+    randoms: [LumiaVariationConditions.RANDOM],
+};
+export const sanitizeVariationVariableReference = (value) => (value ? value.trim().replace(/[={}]/g, '') : '');
+const isVariationOnly = (config) => Boolean(config.onlyVariation || config.disableBaseAlert);
+const isBaseAlertEnabled = (config, options) => { var _a, _b; return (_b = (_a = options.isBaseAlertEnabled) === null || _a === void 0 ? void 0 : _a.call(options, config)) !== null && _b !== void 0 ? _b : !isVariationOnly(config); };
+const isVariationEnabled = (variation, config, options) => { var _a, _b; return (_b = (_a = options.isVariationEnabled) === null || _a === void 0 ? void 0 : _a.call(options, variation, config)) !== null && _b !== void 0 ? _b : variation.on !== false; };
+const safeParse = (value, floor = false) => {
+    if (typeof value === 'number') {
+        return floor ? Math.floor(value) : value;
+    }
+    if (typeof value === 'boolean' || value === undefined || value === null) {
+        return value;
+    }
+    if (value.includes('.')) {
+        const parsedValue = parseFloat(value);
+        return floor ? Math.floor(parsedValue) : parsedValue;
+    }
+    const parsedValue = parseInt(value);
+    return floor ? Math.floor(parsedValue) : parsedValue;
+};
+const toFiniteNumber = (value) => {
+    if (typeof value === 'number') {
+        return Number.isFinite(value) ? value : undefined;
+    }
+    if (typeof value === 'string') {
+        const trimmedValue = value.trim();
+        if (!trimmedValue.length) {
+            return undefined;
+        }
+        const parsedValue = Number(trimmedValue);
+        return Number.isFinite(parsedValue) ? parsedValue : undefined;
+    }
+    return undefined;
+};
+const getRandomNumber = (min = 0, max = 255, random = Math.random) => Math.floor(random() * (max - min + 1) + min);
+const rollChance = (percent = 100, random = Math.random) => getRandomNumber(0, 100, random) < percent;
+const shuffle = (array, random = Math.random) => {
+    const newArray = [...array];
+    const startIndex = newArray.length;
+    let randomIndex = Math.floor(random() * startIndex);
+    for (let currentIndex = startIndex - 1; currentIndex >= 1; currentIndex--) {
+        [newArray[currentIndex], newArray[randomIndex]] = [newArray[randomIndex], newArray[currentIndex]];
+        randomIndex = Math.floor(random() * currentIndex);
+    }
+    return newArray;
+};
+const compareVariationValue = ({ expected, actual, caseSensitive }) => {
+    if (expected === undefined || expected === null || (typeof expected === 'string' && expected.trim().length === 0)) {
+        return actual !== undefined && actual !== null;
+    }
+    const expectedNumber = toFiniteNumber(expected);
+    const actualNumber = toFiniteNumber(actual);
+    if (expectedNumber !== undefined && actualNumber !== undefined) {
+        return expectedNumber === actualNumber;
+    }
+    const expectedString = `${expected}`;
+    const actualString = actual === undefined || actual === null ? '' : `${actual}`;
+    if (caseSensitive ? expectedString === actualString : expectedString.toLowerCase() === actualString.toLowerCase()) {
+        return true;
+    }
+    return expected == actual;
+};
+const getVariableValueFromCondition = (condition, variableReference, options) => {
+    var _a;
+    const normalizedVariableName = sanitizeVariationVariableReference(variableReference);
+    if (!normalizedVariableName) {
+        return undefined;
+    }
+    const conditionRecord = condition;
+    if (conditionRecord[normalizedVariableName] !== undefined) {
+        return conditionRecord[normalizedVariableName];
+    }
+    if (variableReference && conditionRecord[variableReference] !== undefined) {
+        return conditionRecord[variableReference];
+    }
+    return (_a = options.getVariableValue) === null || _a === void 0 ? void 0 : _a.call(options, { condition, variableReference, normalizedVariableName });
+};
+const toSortableCondition = (condition) => (typeof condition !== 'boolean' ? safeParse(condition) : condition);
+const compareVariationCondition = (a, b, bucketKey) => {
+    const aCondition = toSortableCondition(a.condition);
+    const bCondition = toSortableCondition(b.condition);
+    if (aCondition === bCondition) {
+        return 0;
+    }
+    if (bucketKey === 'lessers') {
+        return aCondition <= bCondition ? -1 : 1;
+    }
+    return aCondition >= bCondition ? -1 : 1;
+};
+const getVariationBucketKey = (conditionType) => {
+    var _a;
+    if (!conditionType) {
+        return undefined;
+    }
+    return (_a = Object.entries(variationBucketTypes).find(([, conditionTypes]) => conditionTypes.includes(conditionType))) === null || _a === void 0 ? void 0 : _a[0];
+};
+const compareSubscriptionOrder = (currentVariation, previousVariation) => {
+    if (typeof currentVariation.conditionType === 'undefined' || typeof previousVariation.conditionType === 'undefined') {
+        return 0;
+    }
+    const currentOrder = subscriptionOrderNumbers[currentVariation.conditionType];
+    const previousOrder = subscriptionOrderNumbers[previousVariation.conditionType];
+    if (currentOrder === previousOrder) {
+        const currentBucketKey = getVariationBucketKey(currentVariation.conditionType);
+        const previousBucketKey = getVariationBucketKey(previousVariation.conditionType);
+        if (currentBucketKey && currentBucketKey === previousBucketKey) {
+            return compareVariationCondition(currentVariation, previousVariation, currentBucketKey);
+        }
+        return 0;
+    }
+    return currentOrder > previousOrder ? 1 : -1;
+};
+export const resetVariationCumulativeTracking = (logger = console) => {
+    lastCountMultipleIdxByKey.clear();
+    logger.debug('Cumulative tracking reset for new stream session');
+};
+const getBaseAlertFallback = (config, options) => {
+    var _a;
+    if (!isBaseAlertEnabled(config, options)) {
+        (_a = options.logger) === null || _a === void 0 ? void 0 : _a.debug('No variation found. Only accepting variations');
+        return null;
+    }
+    return { ...config };
+};
+const isEmptyVariationCondition = (variation) => {
+    const condition = variation.condition;
+    if (condition === undefined || condition === null) {
+        return true;
+    }
+    if (typeof condition === 'string') {
+        return condition.trim().length === 0;
+    }
+    if (typeof condition === 'number') {
+        return Number.isNaN(condition);
+    }
+    return false;
+};
+const evaluateVariationMatch = ({ variation, condition, config, options, }) => {
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r, _s, _t, _u, _v;
+    try {
+        if (!condition && variation.conditionType !== LumiaVariationConditions.RANDOM) {
+            return false;
+        }
+        if (config.matchEmptyCondition &&
+            isEmptyVariationCondition(variation) &&
+            variation.conditionType &&
+            [
+                LumiaVariationConditions.EQUAL_NUMBER,
+                LumiaVariationConditions.EQUAL_VARIABLE,
+                LumiaVariationConditions.EQUAL_STRING,
+                LumiaVariationConditions.EQUAL_SELECTION,
+                LumiaVariationConditions.GREATER_NUMBER,
+                LumiaVariationConditions.LESS_NUMBER,
+            ].includes(variation.conditionType)) {
+            return true;
+        }
+        switch (variation.conditionType) {
+            case LumiaVariationConditions.EQUAL_NUMBER:
+                return typeof variation.condition !== 'undefined' && safeParse(variation.condition) === safeParse(condition === null || condition === void 0 ? void 0 : condition.value);
+            case LumiaVariationConditions.EQUAL_SELECTION: {
+                let variationCondition = variation.condition;
+                let value = (_a = condition === null || condition === void 0 ? void 0 : condition.name) !== null && _a !== void 0 ? _a : condition === null || condition === void 0 ? void 0 : condition.value;
+                if (typeof variationCondition === 'string') {
+                    variationCondition = variationCondition.toLowerCase();
+                }
+                if (typeof value === 'string') {
+                    value = value.toLowerCase();
+                }
+                return variationCondition == value;
+            }
+            case LumiaVariationConditions.EQUAL_STRING: {
+                const name = (_b = condition === null || condition === void 0 ? void 0 : condition.name) !== null && _b !== void 0 ? _b : condition === null || condition === void 0 ? void 0 : condition.value;
+                if (config.caseSensitive) {
+                    return ((_c = variation.condition) === null || _c === void 0 ? void 0 : _c.toString()) === (name === null || name === void 0 ? void 0 : name.toString());
+                }
+                return ((_e = (_d = variation.condition) === null || _d === void 0 ? void 0 : _d.toString()) === null || _e === void 0 ? void 0 : _e.toLowerCase()) == ((_f = name === null || name === void 0 ? void 0 : name.toString()) === null || _f === void 0 ? void 0 : _f.toLowerCase());
+            }
+            case LumiaVariationConditions.EQUAL_VARIABLE: {
+                const variableValue = condition ? getVariableValueFromCondition(condition, (_g = variation.conditionExtra) === null || _g === void 0 ? void 0 : _g.toString(), options) : undefined;
+                return compareVariationValue({ expected: variation.condition, actual: variableValue, caseSensitive: config.caseSensitive });
+            }
+            case LumiaVariationConditions.EQUAL_USERNAME: {
+                const name = (_h = condition === null || condition === void 0 ? void 0 : condition.username) !== null && _h !== void 0 ? _h : condition === null || condition === void 0 ? void 0 : condition.value;
+                return ((_k = (_j = variation.condition) === null || _j === void 0 ? void 0 : _j.toString()) === null || _k === void 0 ? void 0 : _k.toLowerCase()) == ((_l = name === null || name === void 0 ? void 0 : name.toString()) === null || _l === void 0 ? void 0 : _l.toLowerCase());
+            }
+            case LumiaVariationConditions.EQUAL_USER_LEVEL:
+                return Boolean((_m = condition === null || condition === void 0 ? void 0 : condition.lumiauserlevels) === null || _m === void 0 ? void 0 : _m.includes(safeParse(variation.condition)));
+            case LumiaVariationConditions.GREATER_NUMBER:
+                return typeof variation.condition !== 'undefined' && safeParse(condition === null || condition === void 0 ? void 0 : condition.value) >= safeParse(variation.condition);
+            case LumiaVariationConditions.LESS_NUMBER:
+                return typeof variation.condition !== 'undefined' && safeParse(condition === null || condition === void 0 ? void 0 : condition.value) <= safeParse(variation.condition);
+            case LumiaVariationConditions.EQUAL_CURRENCY_NUMBER: {
+                if (typeof variation.condition === 'undefined' || safeParse(variation.condition) !== safeParse(condition === null || condition === void 0 ? void 0 : condition.value)) {
+                    return false;
+                }
+                const checkCurrency = (_p = (_o = condition === null || condition === void 0 ? void 0 : condition.currency) === null || _o === void 0 ? void 0 : _o.toUpperCase()) !== null && _p !== void 0 ? _p : condition === null || condition === void 0 ? void 0 : condition.currency;
+                return variation.conditionExtra === checkCurrency || variation.conditionExtra === LumiaVariationCurrency.NONE || !variation.conditionExtra;
+            }
+            case LumiaVariationConditions.GREATER_CURRENCY_NUMBER: {
+                const checkCurrency = (_r = (_q = condition === null || condition === void 0 ? void 0 : condition.currency) === null || _q === void 0 ? void 0 : _q.toUpperCase()) !== null && _r !== void 0 ? _r : condition === null || condition === void 0 ? void 0 : condition.currency;
+                if (typeof variation.condition !== 'undefined' && safeParse(condition === null || condition === void 0 ? void 0 : condition.value) >= safeParse(variation.condition)) {
+                    return variation.conditionExtra === checkCurrency || variation.conditionExtra === LumiaVariationCurrency.NONE || !variation.conditionExtra;
+                }
+                return false;
+            }
+            case LumiaVariationConditions.GIFT_SUB_EQUAL:
+                return typeof variation.condition !== 'undefined' && safeParse(variation.condition) === safeParse(condition === null || condition === void 0 ? void 0 : condition.giftAmount);
+            case LumiaVariationConditions.GIFT_SUB_GREATER:
+                return typeof variation.condition !== 'undefined' && safeParse(condition === null || condition === void 0 ? void 0 : condition.giftAmount) >= safeParse(variation.condition);
+            case LumiaVariationConditions.IS_GIFT:
+                return Boolean((condition === null || condition === void 0 ? void 0 : condition.isGift) || (condition === null || condition === void 0 ? void 0 : condition.giftAmount));
+            case LumiaVariationConditions.IS_PRIME:
+                return Boolean((condition === null || condition === void 0 ? void 0 : condition.isPrime) || (condition === null || condition === void 0 ? void 0 : condition.value) === 'Prime');
+            case LumiaVariationConditions.SUBSCRIBED_MONTHS_EQUAL:
+                return typeof variation.condition !== 'undefined' && safeParse(variation.condition) === safeParse(condition === null || condition === void 0 ? void 0 : condition.subMonths);
+            case LumiaVariationConditions.SUBSCRIBED_MONTHS_GREATER:
+                return typeof variation.condition !== 'undefined' && safeParse(condition === null || condition === void 0 ? void 0 : condition.subMonths) >= safeParse(variation.condition);
+            case LumiaVariationConditions.RANDOM:
+                return rollChance((_u = (_t = (_s = options.getRandomChance) === null || _s === void 0 ? void 0 : _s.call(options, variation)) !== null && _t !== void 0 ? _t : variation.randomChance) !== null && _u !== void 0 ? _u : variation.condition, options.random);
+            case LumiaVariationConditions.COUNT_IS_MULTIPLE_OF:
+                return evaluateCountIsMultipleOf({ variation, condition, options });
+            default:
+                return false;
+        }
+    }
+    catch (error) {
+        (_v = options.logger) === null || _v === void 0 ? void 0 : _v.error('Error in variationCheck', error, variation, condition);
+        return false;
+    }
+};
+const evaluateCountIsMultipleOf = ({ variation, condition, options, }) => {
+    if (variation.condition === undefined || condition === undefined || condition === null) {
+        return false;
+    }
+    const step = safeParse(variation.condition);
+    const totalSource = condition.total !== undefined ? condition.total : options.useConditionValueForCountTotal ? condition.value : undefined;
+    const total = safeParse(totalSource);
+    const previousTotal = condition.previousTotal === undefined ? undefined : safeParse(condition.previousTotal);
+    const key = `${variation.id || 'unknown'}:${variation.name || 'variation'}`;
+    const numericStep = Number(step);
+    const numericTotal = Number(total);
+    if (!Number.isFinite(numericTotal) || !Number.isFinite(numericStep) || numericStep <= 0) {
+        return false;
+    }
+    const currIdx = Math.floor(numericTotal / numericStep);
+    const storedIdx = lastCountMultipleIdxByKey.get(key);
+    const hasPrevTotal = previousTotal !== undefined;
+    const shouldCommit = !options.skipVariationUpdates;
+    if (storedIdx !== undefined && currIdx < storedIdx) {
+        if (shouldCommit) {
+            lastCountMultipleIdxByKey.set(key, currIdx);
+        }
+        return false;
+    }
+    let baseIdx = storedIdx;
+    if (baseIdx === undefined) {
+        if (hasPrevTotal) {
+            const numericPreviousTotal = Number(previousTotal);
+            if (numericPreviousTotal > numericTotal) {
+                if (shouldCommit) {
+                    lastCountMultipleIdxByKey.set(key, currIdx);
+                }
+                return false;
+            }
+            baseIdx = Math.floor(numericPreviousTotal / numericStep);
+        }
+        else {
+            if (shouldCommit) {
+                lastCountMultipleIdxByKey.set(key, currIdx);
+            }
+            return false;
+        }
+    }
+    const crossed = currIdx > baseIdx;
+    if (crossed) {
+        if (shouldCommit) {
+            lastCountMultipleIdxByKey.set(key, currIdx);
+        }
+        return true;
+    }
+    if (storedIdx === undefined && shouldCommit) {
+        lastCountMultipleIdxByKey.set(key, baseIdx);
+    }
+    return false;
+};
+const variationCheck = ({ variation, condition, config, options, }) => {
+    var _a, _b, _c;
+    if (variation.triggerOncePerStream && ((_a = options.hasTriggeredOnce) === null || _a === void 0 ? void 0 : _a.call(options, variation, config))) {
+        (_b = options.logger) === null || _b === void 0 ? void 0 : _b.debug('Variation already triggered this stream', variation.name);
+        return false;
+    }
+    const matched = evaluateVariationMatch({ variation, condition, config, options });
+    if (matched && variation.triggerOncePerStream && !options.skipVariationUpdates) {
+        (_c = options.markTriggeredOnce) === null || _c === void 0 ? void 0 : _c.call(options, variation, config);
+    }
+    return matched;
+};
+const checkByOrder = (config, condition, options) => {
+    var _a;
+    if (typeof config.variations === 'undefined') {
+        return undefined;
+    }
+    const variations = config.variations.filter((variation) => isVariationEnabled(variation, config, options)).sort(compareSubscriptionOrder);
+    let foundVariation;
+    let randoms = [];
+    variations.some((variation) => {
+        if (typeof variation.conditionType !== 'undefined' && variationBucketTypes.randoms.includes(variation.conditionType)) {
+            randoms.push(variation);
+            return false;
+        }
+        if (variationCheck({ variation, condition, config, options })) {
+            foundVariation = variation;
+            return true;
+        }
+        return false;
+    });
+    if (typeof foundVariation === 'undefined' && randoms.length) {
+        randoms = shuffle(randoms, options.random);
+        randoms.some((variation) => {
+            if (variationCheck({ variation, condition, config, options })) {
+                foundVariation = variation;
+                return true;
+            }
+            return false;
+        });
+        if (!foundVariation && ((_a = options.shouldUseRandomFallback) === null || _a === void 0 ? void 0 : _a.call(options, config))) {
+            foundVariation = randoms[0];
+        }
+    }
+    return foundVariation;
+};
+const checkByPriorities = (config, condition, options) => {
+    if (typeof config.variations === 'undefined') {
+        return undefined;
+    }
+    const variationBucket = {
+        equals: [],
+        greaters: [],
+        lessers: [],
+        checks: [],
+        randoms: [],
+    };
+    config.variations.forEach((variation) => {
+        if (!isVariationEnabled(variation, config, options) || typeof variation.conditionType === 'undefined') {
+            return;
+        }
+        if (variationBucketTypes.equals.includes(variation.conditionType)) {
+            variationBucket.equals.push(variation);
+        }
+        else if (variationBucketTypes.greaters.includes(variation.conditionType)) {
+            variationBucket.greaters.push(variation);
+        }
+        else if (variationBucketTypes.lessers.includes(variation.conditionType)) {
+            variationBucket.lessers.push(variation);
+        }
+        else if (variationBucketTypes.checks.includes(variation.conditionType)) {
+            variationBucket.checks.push(variation);
+        }
+        else if (variationBucketTypes.randoms.includes(variation.conditionType)) {
+            variationBucket.randoms.push(variation);
+        }
+    });
+    Object.keys(variationBucket).forEach((bucketKey) => {
+        variationBucket[bucketKey].sort((a, b) => compareVariationCondition(a, b, bucketKey));
+    });
+    let foundVariation;
+    const bucketKeys = ['equals', 'greaters', 'lessers', 'checks', 'randoms'];
+    bucketKeys.some((bucketKey) => {
+        var _a;
+        if (!variationBucket[bucketKey].length) {
+            return false;
+        }
+        const variations = bucketKey === 'randoms' ? shuffle(variationBucket[bucketKey], options.random) : variationBucket[bucketKey];
+        variations.some((variation) => {
+            if (variationCheck({ variation, condition, config, options })) {
+                foundVariation = variation;
+                return true;
+            }
+            return false;
+        });
+        if (!foundVariation && bucketKey === 'randoms' && ((_a = options.shouldUseRandomFallback) === null || _a === void 0 ? void 0 : _a.call(options, config))) {
+            foundVariation = variations[0];
+        }
+        return Boolean(foundVariation);
+    });
+    return foundVariation;
+};
+export const checkAlertVariation = (config, condition, options = {}) => {
+    var _a, _b;
+    if (!config.variations) {
+        return getBaseAlertFallback(config, options);
+    }
+    const foundVariation = ((_a = options.shouldUseSubscriptionOrder) === null || _a === void 0 ? void 0 : _a.call(options, config, condition)) ? checkByOrder(config, condition, options) : checkByPriorities(config, condition, options);
+    if (foundVariation) {
+        (_b = options.logger) === null || _b === void 0 ? void 0 : _b.debug('Found variation: ', foundVariation === null || foundVariation === void 0 ? void 0 : foundVariation.name);
+        return foundVariation;
+    }
+    return getBaseAlertFallback(config, options);
+};

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export { LumiaStreamingSites, LumiaActivityCommandTypes, LumiaExternalActivityCommandTypes, LumiaAlertValues, LumiaAlertFriendlyValues, LumiaActivityOriginTypes, LumiaActivityApiValueType, LumiaActivityNoValueTypes, LumiaActivityTestType, } from './activity.types';
 export { LumiaVariationConditions, LumiaVariationCurrency, VariationCurrencySymbol, LumiaRedemptionCurrency, LumiaRedemptionCurrencySymbol, LumiaAlertConfigs, LumiaDynamicCondition, type LumiaSelectionOption, } from './alert.types';
+export { checkAlertVariation, resetVariationCumulativeTracking, sanitizeVariationVariableReference, type LumiaVariationCheckerOptions, type LumiaVariationConfigLike, type LumiaVariationLike, type LumiaVariationLogger, } from './variation.helpers';
 export { ILumiaSendPack, ILumiaEvent, ILumiaEventChatCommandBody, ILumiaEventChatBody, ILumiaEventAlertBody, ILumiaEventStateBody, ILumiaLight, LumiaIntegrations, LumiaEventTypes, } from './event.types';
 export { LumiaEventListTypes, LumiaMapAlertTypeToEventListType, AlertsToFilter, PlatformsToFilter, LumiaEventListTypeColors, getEventListCategoryColor } from './eventlist.types';
 export { SystemVariables, ReservedVariables, AllVariables, getAcceptedVariableName, getAcceptedVariableNames, type LumiaAcceptedVariable, type LumiaAcceptedVariableDefinition, type CountableVariableValue, type DonatorVariableValue, } from './variables.types';

package/dist/index.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SongRequestPlaybackTarget = exports.SongRequestProvider = exports.SongRequestSource = exports.SongRequestStatus = exports.VIEWER_PROFILE_ACHIEVEMENTS = exports.YoutubeSuperstickerImageSelections = exports.YoutubeSuperstickersData = exports.TiktokGiftImageSelections = exports.TiktokGiftsData = exports.BLANK_OVERLAY_TEMPLATE_ID = exports.KickKicksImageSelections = exports.KickKicksData = exports.syncLinkedVariableFields = exports.isRedundantInputField = exports.aliasContentImageFromLegacy = exports.coerceNumericAlertFields = exports.buildExampleAlertVariables = exports.getExampleAlertVariableValue = exports.EMULATE_EXAMPLE_AVATAR_URL = exports.formatCondition = exports.getVariableExamples = exports.VARIABLE_EXAMPLES = exports.getAcceptedVariableNames = exports.getAcceptedVariableName = exports.AllVariables = exports.ReservedVariables = exports.SystemVariables = exports.getEventListCategoryColor = exports.LumiaEventListTypeColors = exports.PlatformsToFilter = exports.AlertsToFilter = exports.LumiaMapAlertTypeToEventListType = exports.LumiaEventListTypes = exports.LumiaEventTypes = exports.LumiaIntegrations = exports.LumiaAlertConfigs = exports.LumiaRedemptionCurrencySymbol = exports.LumiaRedemptionCurrency = exports.VariationCurrencySymbol = exports.LumiaVariationCurrency = exports.LumiaVariationConditions = exports.LumiaActivityTestType = exports.LumiaActivityNoValueTypes = exports.LumiaActivityApiValueType = exports.LumiaActivityOriginTypes = exports.LumiaAlertFriendlyValues = exports.LumiaAlertValues = exports.LumiaExternalActivityCommandTypes = exports.LumiaActivityCommandTypes = exports.LumiaStreamingSites = void 0;
+exports.SongRequestStatus = exports.VIEWER_PROFILE_ACHIEVEMENTS = exports.YoutubeSuperstickerImageSelections = exports.YoutubeSuperstickersData = exports.TiktokGiftImageSelections = exports.TiktokGiftsData = exports.BLANK_OVERLAY_TEMPLATE_ID = exports.KickKicksImageSelections = exports.KickKicksData = exports.syncLinkedVariableFields = exports.isRedundantInputField = exports.aliasContentImageFromLegacy = exports.coerceNumericAlertFields = exports.buildExampleAlertVariables = exports.getExampleAlertVariableValue = exports.EMULATE_EXAMPLE_AVATAR_URL = exports.formatCondition = exports.getVariableExamples = exports.VARIABLE_EXAMPLES = exports.getAcceptedVariableNames = exports.getAcceptedVariableName = exports.AllVariables = exports.ReservedVariables = exports.SystemVariables = exports.getEventListCategoryColor = exports.LumiaEventListTypeColors = exports.PlatformsToFilter = exports.AlertsToFilter = exports.LumiaMapAlertTypeToEventListType = exports.LumiaEventListTypes = exports.LumiaEventTypes = exports.LumiaIntegrations = exports.sanitizeVariationVariableReference = exports.resetVariationCumulativeTracking = exports.checkAlertVariation = exports.LumiaAlertConfigs = exports.LumiaRedemptionCurrencySymbol = exports.LumiaRedemptionCurrency = exports.VariationCurrencySymbol = exports.LumiaVariationCurrency = exports.LumiaVariationConditions = exports.LumiaActivityTestType = exports.LumiaActivityNoValueTypes = exports.LumiaActivityApiValueType = exports.LumiaActivityOriginTypes = exports.LumiaAlertFriendlyValues = exports.LumiaAlertValues = exports.LumiaExternalActivityCommandTypes = exports.LumiaActivityCommandTypes = exports.LumiaStreamingSites = void 0;
+exports.SongRequestPlaybackTarget = exports.SongRequestProvider = exports.SongRequestSource = void 0;
 var activity_types_1 = require("./activity.types");
 Object.defineProperty(exports, "LumiaStreamingSites", { enumerable: true, get: function () { return activity_types_1.LumiaStreamingSites; } });
 Object.defineProperty(exports, "LumiaActivityCommandTypes", { enumerable: true, get: function () { return activity_types_1.LumiaActivityCommandTypes; } });
@@ -18,6 +19,10 @@ Object.defineProperty(exports, "VariationCurrencySymbol", { enumerable: true, ge
 Object.defineProperty(exports, "LumiaRedemptionCurrency", { enumerable: true, get: function () { return alert_types_1.LumiaRedemptionCurrency; } });
 Object.defineProperty(exports, "LumiaRedemptionCurrencySymbol", { enumerable: true, get: function () { return alert_types_1.LumiaRedemptionCurrencySymbol; } });
 Object.defineProperty(exports, "LumiaAlertConfigs", { enumerable: true, get: function () { return alert_types_1.LumiaAlertConfigs; } });
+var variation_helpers_1 = require("./variation.helpers");
+Object.defineProperty(exports, "checkAlertVariation", { enumerable: true, get: function () { return variation_helpers_1.checkAlertVariation; } });
+Object.defineProperty(exports, "resetVariationCumulativeTracking", { enumerable: true, get: function () { return variation_helpers_1.resetVariationCumulativeTracking; } });
+Object.defineProperty(exports, "sanitizeVariationVariableReference", { enumerable: true, get: function () { return variation_helpers_1.sanitizeVariationVariableReference; } });
 var event_types_1 = require("./event.types");
 Object.defineProperty(exports, "LumiaIntegrations", { enumerable: true, get: function () { return event_types_1.LumiaIntegrations; } });
 Object.defineProperty(exports, "LumiaEventTypes", { enumerable: true, get: function () { return event_types_1.LumiaEventTypes; } });

package/dist/variation.helpers.d.ts

@@ -0,0 +1,48 @@
+import { type LumiaDynamicCondition, LumiaVariationConditions, LumiaVariationCurrency } from './alert.types';
+export interface LumiaVariationLike {
+    id?: string | number;
+    name?: string;
+    on?: boolean;
+    condition?: string | number | boolean | null;
+    conditionType?: LumiaVariationConditions;
+    conditionExtra?: LumiaVariationCurrency | string | number | null;
+    randomChance?: number;
+    triggerOncePerStream?: boolean;
+    settings?: {
+        enabled?: boolean;
+    };
+}
+export interface LumiaVariationConfigLike<TVariation extends LumiaVariationLike> {
+    variations?: TVariation[];
+    onlyVariation?: boolean;
+    disableBaseAlert?: boolean;
+    subgift?: boolean;
+    on?: boolean;
+    matchEmptyCondition?: boolean;
+    caseSensitive?: boolean;
+    settings?: {
+        enabled?: boolean;
+    };
+}
+export type LumiaVariationLogger = Pick<Console, 'debug' | 'error'>;
+export interface LumiaVariationCheckerOptions<TConfig extends LumiaVariationConfigLike<TVariation>, TVariation extends LumiaVariationLike> {
+    getRandomChance?: (variation: TVariation) => unknown;
+    getVariableValue?: (params: {
+        condition: LumiaDynamicCondition;
+        variableReference?: string;
+        normalizedVariableName: string;
+    }) => unknown;
+    hasTriggeredOnce?: (variation: TVariation, config: TConfig) => boolean;
+    isBaseAlertEnabled?: (config: TConfig) => boolean;
+    isVariationEnabled?: (variation: TVariation, config: TConfig) => boolean;
+    logger?: LumiaVariationLogger;
+    markTriggeredOnce?: (variation: TVariation, config: TConfig) => void;
+    random?: () => number;
+    shouldUseRandomFallback?: (config: TConfig) => boolean;
+    shouldUseSubscriptionOrder?: (config: TConfig, condition: LumiaDynamicCondition | undefined | null) => boolean;
+    skipVariationUpdates?: boolean;
+    useConditionValueForCountTotal?: boolean;
+}
+export declare const sanitizeVariationVariableReference: (value?: string) => string;
+export declare const resetVariationCumulativeTracking: (logger?: LumiaVariationLogger) => void;
+export declare const checkAlertVariation: <TConfig extends LumiaVariationConfigLike<TVariation>, TVariation extends LumiaVariationLike>(config: TConfig, condition: LumiaDynamicCondition | undefined | null, options?: LumiaVariationCheckerOptions<TConfig, TVariation>) => TVariation | TConfig | null;

package/dist/variation.helpers.js

@@ -0,0 +1,438 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkAlertVariation = exports.resetVariationCumulativeTracking = exports.sanitizeVariationVariableReference = void 0;
+const alert_types_1 = require("./alert.types");
+const lastCountMultipleIdxByKey = new Map();
+const subscriptionOrderNumbers = {
+    [alert_types_1.LumiaVariationConditions.GIFT_SUB_EQUAL]: 1,
+    [alert_types_1.LumiaVariationConditions.GIFT_SUB_GREATER]: 2,
+    [alert_types_1.LumiaVariationConditions.IS_GIFT]: 3,
+    [alert_types_1.LumiaVariationConditions.SUBSCRIBED_MONTHS_EQUAL]: 4,
+    [alert_types_1.LumiaVariationConditions.SUBSCRIBED_MONTHS_GREATER]: 5,
+    [alert_types_1.LumiaVariationConditions.IS_PRIME]: 6,
+    [alert_types_1.LumiaVariationConditions.EQUAL_SELECTION]: 7,
+    [alert_types_1.LumiaVariationConditions.RANDOM]: 8,
+};
+const variationBucketTypes = {
+    equals: [
+        alert_types_1.LumiaVariationConditions.EQUAL_NUMBER,
+        alert_types_1.LumiaVariationConditions.EQUAL_VARIABLE,
+        alert_types_1.LumiaVariationConditions.EQUAL_CURRENCY_NUMBER,
+        alert_types_1.LumiaVariationConditions.EQUAL_SELECTION,
+        alert_types_1.LumiaVariationConditions.EQUAL_STRING,
+        alert_types_1.LumiaVariationConditions.EQUAL_USERNAME,
+        alert_types_1.LumiaVariationConditions.EQUAL_USER_LEVEL,
+        alert_types_1.LumiaVariationConditions.SUBSCRIBED_MONTHS_EQUAL,
+        alert_types_1.LumiaVariationConditions.GIFT_SUB_EQUAL,
+        alert_types_1.LumiaVariationConditions.COUNT_IS_MULTIPLE_OF,
+    ],
+    greaters: [
+        alert_types_1.LumiaVariationConditions.GREATER_NUMBER,
+        alert_types_1.LumiaVariationConditions.GREATER_CURRENCY_NUMBER,
+        alert_types_1.LumiaVariationConditions.SUBSCRIBED_MONTHS_GREATER,
+        alert_types_1.LumiaVariationConditions.GIFT_SUB_GREATER,
+    ],
+    lessers: [alert_types_1.LumiaVariationConditions.LESS_NUMBER],
+    checks: [alert_types_1.LumiaVariationConditions.IS_GIFT, alert_types_1.LumiaVariationConditions.IS_PRIME],
+    randoms: [alert_types_1.LumiaVariationConditions.RANDOM],
+};
+const sanitizeVariationVariableReference = (value) => (value ? value.trim().replace(/[={}]/g, '') : '');
+exports.sanitizeVariationVariableReference = sanitizeVariationVariableReference;
+const isVariationOnly = (config) => Boolean(config.onlyVariation || config.disableBaseAlert);
+const isBaseAlertEnabled = (config, options) => { var _a, _b; return (_b = (_a = options.isBaseAlertEnabled) === null || _a === void 0 ? void 0 : _a.call(options, config)) !== null && _b !== void 0 ? _b : !isVariationOnly(config); };
+const isVariationEnabled = (variation, config, options) => { var _a, _b; return (_b = (_a = options.isVariationEnabled) === null || _a === void 0 ? void 0 : _a.call(options, variation, config)) !== null && _b !== void 0 ? _b : variation.on !== false; };
+const safeParse = (value, floor = false) => {
+    if (typeof value === 'number') {
+        return floor ? Math.floor(value) : value;
+    }
+    if (typeof value === 'boolean' || value === undefined || value === null) {
+        return value;
+    }
+    if (value.includes('.')) {
+        const parsedValue = parseFloat(value);
+        return floor ? Math.floor(parsedValue) : parsedValue;
+    }
+    const parsedValue = parseInt(value);
+    return floor ? Math.floor(parsedValue) : parsedValue;
+};
+const toFiniteNumber = (value) => {
+    if (typeof value === 'number') {
+        return Number.isFinite(value) ? value : undefined;
+    }
+    if (typeof value === 'string') {
+        const trimmedValue = value.trim();
+        if (!trimmedValue.length) {
+            return undefined;
+        }
+        const parsedValue = Number(trimmedValue);
+        return Number.isFinite(parsedValue) ? parsedValue : undefined;
+    }
+    return undefined;
+};
+const getRandomNumber = (min = 0, max = 255, random = Math.random) => Math.floor(random() * (max - min + 1) + min);
+const rollChance = (percent = 100, random = Math.random) => getRandomNumber(0, 100, random) < percent;
+const shuffle = (array, random = Math.random) => {
+    const newArray = [...array];
+    const startIndex = newArray.length;
+    let randomIndex = Math.floor(random() * startIndex);
+    for (let currentIndex = startIndex - 1; currentIndex >= 1; currentIndex--) {
+        [newArray[currentIndex], newArray[randomIndex]] = [newArray[randomIndex], newArray[currentIndex]];
+        randomIndex = Math.floor(random() * currentIndex);
+    }
+    return newArray;
+};
+const compareVariationValue = ({ expected, actual, caseSensitive }) => {
+    if (expected === undefined || expected === null || (typeof expected === 'string' && expected.trim().length === 0)) {
+        return actual !== undefined && actual !== null;
+    }
+    const expectedNumber = toFiniteNumber(expected);
+    const actualNumber = toFiniteNumber(actual);
+    if (expectedNumber !== undefined && actualNumber !== undefined) {
+        return expectedNumber === actualNumber;
+    }
+    const expectedString = `${expected}`;
+    const actualString = actual === undefined || actual === null ? '' : `${actual}`;
+    if (caseSensitive ? expectedString === actualString : expectedString.toLowerCase() === actualString.toLowerCase()) {
+        return true;
+    }
+    return expected == actual;
+};
+const getVariableValueFromCondition = (condition, variableReference, options) => {
+    var _a;
+    const normalizedVariableName = (0, exports.sanitizeVariationVariableReference)(variableReference);
+    if (!normalizedVariableName) {
+        return undefined;
+    }
+    const conditionRecord = condition;
+    if (conditionRecord[normalizedVariableName] !== undefined) {
+        return conditionRecord[normalizedVariableName];
+    }
+    if (variableReference && conditionRecord[variableReference] !== undefined) {
+        return conditionRecord[variableReference];
+    }
+    return (_a = options.getVariableValue) === null || _a === void 0 ? void 0 : _a.call(options, { condition, variableReference, normalizedVariableName });
+};
+const toSortableCondition = (condition) => (typeof condition !== 'boolean' ? safeParse(condition) : condition);
+const compareVariationCondition = (a, b, bucketKey) => {
+    const aCondition = toSortableCondition(a.condition);
+    const bCondition = toSortableCondition(b.condition);
+    if (aCondition === bCondition) {
+        return 0;
+    }
+    if (bucketKey === 'lessers') {
+        return aCondition <= bCondition ? -1 : 1;
+    }
+    return aCondition >= bCondition ? -1 : 1;
+};
+const getVariationBucketKey = (conditionType) => {
+    var _a;
+    if (!conditionType) {
+        return undefined;
+    }
+    return (_a = Object.entries(variationBucketTypes).find(([, conditionTypes]) => conditionTypes.includes(conditionType))) === null || _a === void 0 ? void 0 : _a[0];
+};
+const compareSubscriptionOrder = (currentVariation, previousVariation) => {
+    if (typeof currentVariation.conditionType === 'undefined' || typeof previousVariation.conditionType === 'undefined') {
+        return 0;
+    }
+    const currentOrder = subscriptionOrderNumbers[currentVariation.conditionType];
+    const previousOrder = subscriptionOrderNumbers[previousVariation.conditionType];
+    if (currentOrder === previousOrder) {
+        const currentBucketKey = getVariationBucketKey(currentVariation.conditionType);
+        const previousBucketKey = getVariationBucketKey(previousVariation.conditionType);
+        if (currentBucketKey && currentBucketKey === previousBucketKey) {
+            return compareVariationCondition(currentVariation, previousVariation, currentBucketKey);
+        }
+        return 0;
+    }
+    return currentOrder > previousOrder ? 1 : -1;
+};
+const resetVariationCumulativeTracking = (logger = console) => {
+    lastCountMultipleIdxByKey.clear();
+    logger.debug('Cumulative tracking reset for new stream session');
+};
+exports.resetVariationCumulativeTracking = resetVariationCumulativeTracking;
+const getBaseAlertFallback = (config, options) => {
+    var _a;
+    if (!isBaseAlertEnabled(config, options)) {
+        (_a = options.logger) === null || _a === void 0 ? void 0 : _a.debug('No variation found. Only accepting variations');
+        return null;
+    }
+    return { ...config };
+};
+const isEmptyVariationCondition = (variation) => {
+    const condition = variation.condition;
+    if (condition === undefined || condition === null) {
+        return true;
+    }
+    if (typeof condition === 'string') {
+        return condition.trim().length === 0;
+    }
+    if (typeof condition === 'number') {
+        return Number.isNaN(condition);
+    }
+    return false;
+};
+const evaluateVariationMatch = ({ variation, condition, config, options, }) => {
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r, _s, _t, _u, _v;
+    try {
+        if (!condition && variation.conditionType !== alert_types_1.LumiaVariationConditions.RANDOM) {
+            return false;
+        }
+        if (config.matchEmptyCondition &&
+            isEmptyVariationCondition(variation) &&
+            variation.conditionType &&
+            [
+                alert_types_1.LumiaVariationConditions.EQUAL_NUMBER,
+                alert_types_1.LumiaVariationConditions.EQUAL_VARIABLE,
+                alert_types_1.LumiaVariationConditions.EQUAL_STRING,
+                alert_types_1.LumiaVariationConditions.EQUAL_SELECTION,
+                alert_types_1.LumiaVariationConditions.GREATER_NUMBER,
+                alert_types_1.LumiaVariationConditions.LESS_NUMBER,
+            ].includes(variation.conditionType)) {
+            return true;
+        }
+        switch (variation.conditionType) {
+            case alert_types_1.LumiaVariationConditions.EQUAL_NUMBER:
+                return typeof variation.condition !== 'undefined' && safeParse(variation.condition) === safeParse(condition === null || condition === void 0 ? void 0 : condition.value);
+            case alert_types_1.LumiaVariationConditions.EQUAL_SELECTION: {
+                let variationCondition = variation.condition;
+                let value = (_a = condition === null || condition === void 0 ? void 0 : condition.name) !== null && _a !== void 0 ? _a : condition === null || condition === void 0 ? void 0 : condition.value;
+                if (typeof variationCondition === 'string') {
+                    variationCondition = variationCondition.toLowerCase();
+                }
+                if (typeof value === 'string') {
+                    value = value.toLowerCase();
+                }
+                return variationCondition == value;
+            }
+            case alert_types_1.LumiaVariationConditions.EQUAL_STRING: {
+                const name = (_b = condition === null || condition === void 0 ? void 0 : condition.name) !== null && _b !== void 0 ? _b : condition === null || condition === void 0 ? void 0 : condition.value;
+                if (config.caseSensitive) {
+                    return ((_c = variation.condition) === null || _c === void 0 ? void 0 : _c.toString()) === (name === null || name === void 0 ? void 0 : name.toString());
+                }
+                return ((_e = (_d = variation.condition) === null || _d === void 0 ? void 0 : _d.toString()) === null || _e === void 0 ? void 0 : _e.toLowerCase()) == ((_f = name === null || name === void 0 ? void 0 : name.toString()) === null || _f === void 0 ? void 0 : _f.toLowerCase());
+            }
+            case alert_types_1.LumiaVariationConditions.EQUAL_VARIABLE: {
+                const variableValue = condition ? getVariableValueFromCondition(condition, (_g = variation.conditionExtra) === null || _g === void 0 ? void 0 : _g.toString(), options) : undefined;
+                return compareVariationValue({ expected: variation.condition, actual: variableValue, caseSensitive: config.caseSensitive });
+            }
+            case alert_types_1.LumiaVariationConditions.EQUAL_USERNAME: {
+                const name = (_h = condition === null || condition === void 0 ? void 0 : condition.username) !== null && _h !== void 0 ? _h : condition === null || condition === void 0 ? void 0 : condition.value;
+                return ((_k = (_j = variation.condition) === null || _j === void 0 ? void 0 : _j.toString()) === null || _k === void 0 ? void 0 : _k.toLowerCase()) == ((_l = name === null || name === void 0 ? void 0 : name.toString()) === null || _l === void 0 ? void 0 : _l.toLowerCase());
+            }
+            case alert_types_1.LumiaVariationConditions.EQUAL_USER_LEVEL:
+                return Boolean((_m = condition === null || condition === void 0 ? void 0 : condition.lumiauserlevels) === null || _m === void 0 ? void 0 : _m.includes(safeParse(variation.condition)));
+            case alert_types_1.LumiaVariationConditions.GREATER_NUMBER:
+                return typeof variation.condition !== 'undefined' && safeParse(condition === null || condition === void 0 ? void 0 : condition.value) >= safeParse(variation.condition);
+            case alert_types_1.LumiaVariationConditions.LESS_NUMBER:
+                return typeof variation.condition !== 'undefined' && safeParse(condition === null || condition === void 0 ? void 0 : condition.value) <= safeParse(variation.condition);
+            case alert_types_1.LumiaVariationConditions.EQUAL_CURRENCY_NUMBER: {
+                if (typeof variation.condition === 'undefined' || safeParse(variation.condition) !== safeParse(condition === null || condition === void 0 ? void 0 : condition.value)) {
+                    return false;
+                }
+                const checkCurrency = (_p = (_o = condition === null || condition === void 0 ? void 0 : condition.currency) === null || _o === void 0 ? void 0 : _o.toUpperCase()) !== null && _p !== void 0 ? _p : condition === null || condition === void 0 ? void 0 : condition.currency;
+                return variation.conditionExtra === checkCurrency || variation.conditionExtra === alert_types_1.LumiaVariationCurrency.NONE || !variation.conditionExtra;
+            }
+            case alert_types_1.LumiaVariationConditions.GREATER_CURRENCY_NUMBER: {
+                const checkCurrency = (_r = (_q = condition === null || condition === void 0 ? void 0 : condition.currency) === null || _q === void 0 ? void 0 : _q.toUpperCase()) !== null && _r !== void 0 ? _r : condition === null || condition === void 0 ? void 0 : condition.currency;
+                if (typeof variation.condition !== 'undefined' && safeParse(condition === null || condition === void 0 ? void 0 : condition.value) >= safeParse(variation.condition)) {
+                    return variation.conditionExtra === checkCurrency || variation.conditionExtra === alert_types_1.LumiaVariationCurrency.NONE || !variation.conditionExtra;
+                }
+                return false;
+            }
+            case alert_types_1.LumiaVariationConditions.GIFT_SUB_EQUAL:
+                return typeof variation.condition !== 'undefined' && safeParse(variation.condition) === safeParse(condition === null || condition === void 0 ? void 0 : condition.giftAmount);
+            case alert_types_1.LumiaVariationConditions.GIFT_SUB_GREATER:
+                return typeof variation.condition !== 'undefined' && safeParse(condition === null || condition === void 0 ? void 0 : condition.giftAmount) >= safeParse(variation.condition);
+            case alert_types_1.LumiaVariationConditions.IS_GIFT:
+                return Boolean((condition === null || condition === void 0 ? void 0 : condition.isGift) || (condition === null || condition === void 0 ? void 0 : condition.giftAmount));
+            case alert_types_1.LumiaVariationConditions.IS_PRIME:
+                return Boolean((condition === null || condition === void 0 ? void 0 : condition.isPrime) || (condition === null || condition === void 0 ? void 0 : condition.value) === 'Prime');
+            case alert_types_1.LumiaVariationConditions.SUBSCRIBED_MONTHS_EQUAL:
+                return typeof variation.condition !== 'undefined' && safeParse(variation.condition) === safeParse(condition === null || condition === void 0 ? void 0 : condition.subMonths);
+            case alert_types_1.LumiaVariationConditions.SUBSCRIBED_MONTHS_GREATER:
+                return typeof variation.condition !== 'undefined' && safeParse(condition === null || condition === void 0 ? void 0 : condition.subMonths) >= safeParse(variation.condition);
+            case alert_types_1.LumiaVariationConditions.RANDOM:
+                return rollChance((_u = (_t = (_s = options.getRandomChance) === null || _s === void 0 ? void 0 : _s.call(options, variation)) !== null && _t !== void 0 ? _t : variation.randomChance) !== null && _u !== void 0 ? _u : variation.condition, options.random);
+            case alert_types_1.LumiaVariationConditions.COUNT_IS_MULTIPLE_OF:
+                return evaluateCountIsMultipleOf({ variation, condition, options });
+            default:
+                return false;
+        }
+    }
+    catch (error) {
+        (_v = options.logger) === null || _v === void 0 ? void 0 : _v.error('Error in variationCheck', error, variation, condition);
+        return false;
+    }
+};
+const evaluateCountIsMultipleOf = ({ variation, condition, options, }) => {
+    if (variation.condition === undefined || condition === undefined || condition === null) {
+        return false;
+    }
+    const step = safeParse(variation.condition);
+    const totalSource = condition.total !== undefined ? condition.total : options.useConditionValueForCountTotal ? condition.value : undefined;
+    const total = safeParse(totalSource);
+    const previousTotal = condition.previousTotal === undefined ? undefined : safeParse(condition.previousTotal);
+    const key = `${variation.id || 'unknown'}:${variation.name || 'variation'}`;
+    const numericStep = Number(step);
+    const numericTotal = Number(total);
+    if (!Number.isFinite(numericTotal) || !Number.isFinite(numericStep) || numericStep <= 0) {
+        return false;
+    }
+    const currIdx = Math.floor(numericTotal / numericStep);
+    const storedIdx = lastCountMultipleIdxByKey.get(key);
+    const hasPrevTotal = previousTotal !== undefined;
+    const shouldCommit = !options.skipVariationUpdates;
+    if (storedIdx !== undefined && currIdx < storedIdx) {
+        if (shouldCommit) {
+            lastCountMultipleIdxByKey.set(key, currIdx);
+        }
+        return false;
+    }
+    let baseIdx = storedIdx;
+    if (baseIdx === undefined) {
+        if (hasPrevTotal) {
+            const numericPreviousTotal = Number(previousTotal);
+            if (numericPreviousTotal > numericTotal) {
+                if (shouldCommit) {
+                    lastCountMultipleIdxByKey.set(key, currIdx);
+                }
+                return false;
+            }
+            baseIdx = Math.floor(numericPreviousTotal / numericStep);
+        }
+        else {
+            if (shouldCommit) {
+                lastCountMultipleIdxByKey.set(key, currIdx);
+            }
+            return false;
+        }
+    }
+    const crossed = currIdx > baseIdx;
+    if (crossed) {
+        if (shouldCommit) {
+            lastCountMultipleIdxByKey.set(key, currIdx);
+        }
+        return true;
+    }
+    if (storedIdx === undefined && shouldCommit) {
+        lastCountMultipleIdxByKey.set(key, baseIdx);
+    }
+    return false;
+};
+const variationCheck = ({ variation, condition, config, options, }) => {
+    var _a, _b, _c;
+    if (variation.triggerOncePerStream && ((_a = options.hasTriggeredOnce) === null || _a === void 0 ? void 0 : _a.call(options, variation, config))) {
+        (_b = options.logger) === null || _b === void 0 ? void 0 : _b.debug('Variation already triggered this stream', variation.name);
+        return false;
+    }
+    const matched = evaluateVariationMatch({ variation, condition, config, options });
+    if (matched && variation.triggerOncePerStream && !options.skipVariationUpdates) {
+        (_c = options.markTriggeredOnce) === null || _c === void 0 ? void 0 : _c.call(options, variation, config);
+    }
+    return matched;
+};
+const checkByOrder = (config, condition, options) => {
+    var _a;
+    if (typeof config.variations === 'undefined') {
+        return undefined;
+    }
+    const variations = config.variations.filter((variation) => isVariationEnabled(variation, config, options)).sort(compareSubscriptionOrder);
+    let foundVariation;
+    let randoms = [];
+    variations.some((variation) => {
+        if (typeof variation.conditionType !== 'undefined' && variationBucketTypes.randoms.includes(variation.conditionType)) {
+            randoms.push(variation);
+            return false;
+        }
+        if (variationCheck({ variation, condition, config, options })) {
+            foundVariation = variation;
+            return true;
+        }
+        return false;
+    });
+    if (typeof foundVariation === 'undefined' && randoms.length) {
+        randoms = shuffle(randoms, options.random);
+        randoms.some((variation) => {
+            if (variationCheck({ variation, condition, config, options })) {
+                foundVariation = variation;
+                return true;
+            }
+            return false;
+        });
+        if (!foundVariation && ((_a = options.shouldUseRandomFallback) === null || _a === void 0 ? void 0 : _a.call(options, config))) {
+            foundVariation = randoms[0];
+        }
+    }
+    return foundVariation;
+};
+const checkByPriorities = (config, condition, options) => {
+    if (typeof config.variations === 'undefined') {
+        return undefined;
+    }
+    const variationBucket = {
+        equals: [],
+        greaters: [],
+        lessers: [],
+        checks: [],
+        randoms: [],
+    };
+    config.variations.forEach((variation) => {
+        if (!isVariationEnabled(variation, config, options) || typeof variation.conditionType === 'undefined') {
+            return;
+        }
+        if (variationBucketTypes.equals.includes(variation.conditionType)) {
+            variationBucket.equals.push(variation);
+        }
+        else if (variationBucketTypes.greaters.includes(variation.conditionType)) {
+            variationBucket.greaters.push(variation);
+        }
+        else if (variationBucketTypes.lessers.includes(variation.conditionType)) {
+            variationBucket.lessers.push(variation);
+        }
+        else if (variationBucketTypes.checks.includes(variation.conditionType)) {
+            variationBucket.checks.push(variation);
+        }
+        else if (variationBucketTypes.randoms.includes(variation.conditionType)) {
+            variationBucket.randoms.push(variation);
+        }
+    });
+    Object.keys(variationBucket).forEach((bucketKey) => {
+        variationBucket[bucketKey].sort((a, b) => compareVariationCondition(a, b, bucketKey));
+    });
+    let foundVariation;
+    const bucketKeys = ['equals', 'greaters', 'lessers', 'checks', 'randoms'];
+    bucketKeys.some((bucketKey) => {
+        var _a;
+        if (!variationBucket[bucketKey].length) {
+            return false;
+        }
+        const variations = bucketKey === 'randoms' ? shuffle(variationBucket[bucketKey], options.random) : variationBucket[bucketKey];
+        variations.some((variation) => {
+            if (variationCheck({ variation, condition, config, options })) {
+                foundVariation = variation;
+                return true;
+            }
+            return false;
+        });
+        if (!foundVariation && bucketKey === 'randoms' && ((_a = options.shouldUseRandomFallback) === null || _a === void 0 ? void 0 : _a.call(options, config))) {
+            foundVariation = variations[0];
+        }
+        return Boolean(foundVariation);
+    });
+    return foundVariation;
+};
+const checkAlertVariation = (config, condition, options = {}) => {
+    var _a, _b;
+    if (!config.variations) {
+        return getBaseAlertFallback(config, options);
+    }
+    const foundVariation = ((_a = options.shouldUseSubscriptionOrder) === null || _a === void 0 ? void 0 : _a.call(options, config, condition)) ? checkByOrder(config, condition, options) : checkByPriorities(config, condition, options);
+    if (foundVariation) {
+        (_b = options.logger) === null || _b === void 0 ? void 0 : _b.debug('Found variation: ', foundVariation === null || foundVariation === void 0 ? void 0 : foundVariation.name);
+        return foundVariation;
+    }
+    return getBaseAlertFallback(config, options);
+};
+exports.checkAlertVariation = checkAlertVariation;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumiastream/lumia-types",
-  "version": "3.9.0",
+  "version": "3.9.2",
   "description": "",
   "main": "./dist/index.js",
   "module": "./dist/esm/index.js",
@@ -33,8 +33,8 @@
   "scripts": {
     "build": "npm run clean && tsc -p tsconfig.json && tsc -p tsconfig.esm.json && npm run sync:custom-overlays && npm run sync:custom-code && npm run sync:chatbot && node ./scripts/finalize-esm-build.mjs",
     "watch": "node ./scripts/watch.mjs",
-    "test": "node ./scripts/check-eventlist-alert-invariant.mjs",
-    "prepublishOnly": "npm run build && npm test",
+    "test": "npm run build && node ./scripts/check-eventlist-alert-invariant.mjs && node ./scripts/test-variation-helpers.mjs",
+    "prepublishOnly": "npm test",
     "lint": "tslint --project tsconfig.json \"src/**/*.ts\"",
     "lint:fix": "tslint --project tsconfig.json --fix \"src/**/*.ts\"",
     "clean": "rm -rf dist",