@lumiastream/lumia-types 2.8.0 → 2.8.2

package/dist/activity.types.d.ts

@@ -184,6 +184,8 @@ export declare enum LumiaAlertValues {
     TWITCH_RAID_OUT = "twitch-raidOut",
     /** Bits cheered */
     TWITCH_BITS = "twitch-bits",
+    /** Bits combo completed */
+    TWITCH_BITS_COMBO = "twitch-bitsCombo",
     /** Total Session bits count */
     TWITCH_SESSION_BITS = "twitch-sessionBits",
     /** Channel points redemption */
@@ -537,6 +539,7 @@ export declare const LumiaAlertFriendlyValues: {
     "twitch-raid": string;
     "twitch-raidOut": string;
     "twitch-bits": string;
+    "twitch-bitsCombo": string;
     "twitch-sessionBits": string;
     "twitch-redemption": string;
     "twitch-hypetrainStarted": string;

package/dist/activity.types.js

@@ -199,6 +199,8 @@ var LumiaAlertValues;
     LumiaAlertValues["TWITCH_RAID_OUT"] = "twitch-raidOut";
     /** Bits cheered */
     LumiaAlertValues["TWITCH_BITS"] = "twitch-bits";
+    /** Bits combo completed */
+    LumiaAlertValues["TWITCH_BITS_COMBO"] = "twitch-bitsCombo";
     /** Total Session bits count */
     LumiaAlertValues["TWITCH_SESSION_BITS"] = "twitch-sessionBits";
     /** Channel points redemption */
@@ -567,6 +569,7 @@ exports.LumiaAlertFriendlyValues = {
     [LumiaAlertValues.TWITCH_RAID]: 'Twitch Raid',
     [LumiaAlertValues.TWITCH_RAID_OUT]: 'Twitch Raid Out',
     [LumiaAlertValues.TWITCH_BITS]: 'Twitch Bits',
+    [LumiaAlertValues.TWITCH_BITS_COMBO]: 'Twitch Bits Combo',
     [LumiaAlertValues.TWITCH_SESSION_BITS]: 'Twitch Session Bits',
     [LumiaAlertValues.TWITCH_REDEMPTION]: 'Twitch Redemption',
     [LumiaAlertValues.TWITCH_HYPETRAIN_STARTED]: 'Twitch Hypetrain Started',

package/dist/alert.types.js

@@ -1364,6 +1364,74 @@ exports.LumiaAlertConfigs = {
             },
         ],
     },
+    [activity_types_1.LumiaAlertValues.TWITCH_BITS_COMBO]: {
+        connection: event_types_1.LumiaIntegrations.TWITCH,
+        message: '{{username}} finished a bits combo with {{amount}} bits. They said {{message}}',
+        eventlistMessage: 'Bits Combo',
+        eventlistDetailedMessage: 'finished a bits combo with {{amount}} bits',
+        acceptedVariables: variables_types_1.AllVariables.twitch.alerts.bitsCombo,
+        quickActions: [
+            {
+                label: '500 bits combo',
+                dynamic: { value: 500 },
+                extraSettings: {
+                    username: 'lumiastream',
+                    avatar: 'https://static-cdn.jtvnw.net/jtv_user_pictures/2b1fa336-f9b2-42cf-bd2c-98675da74982-profile_image-70x70.png',
+                    amount: 500,
+                    bitsType: 'combo',
+                },
+            },
+            {
+                label: '1000 bits combo',
+                dynamic: { value: 1000 },
+                extraSettings: {
+                    username: 'lumiastream',
+                    avatar: 'https://static-cdn.jtvnw.net/jtv_user_pictures/2b1fa336-f9b2-42cf-bd2c-98675da74982-profile_image-70x70.png',
+                    amount: 1000,
+                    bitsType: 'combo',
+                },
+            },
+            {
+                label: '2500 bits combo',
+                dynamic: { value: 2500 },
+                extraSettings: {
+                    username: 'lumiastream',
+                    avatar: 'https://static-cdn.jtvnw.net/jtv_user_pictures/2b1fa336-f9b2-42cf-bd2c-98675da74982-profile_image-70x70.png',
+                    amount: 2500,
+                    bitsType: 'combo',
+                },
+            },
+        ],
+        inputFields: [
+            {
+                type: 'text',
+                label: 'Username',
+                variableField: 'username',
+                required: false,
+                default: 'lumiastream',
+            },
+            {
+                type: 'number',
+                label: 'Amount of combo bits',
+                dynamicField: 'value',
+                variableField: 'amount',
+                required: true,
+                default: 500,
+            },
+        ],
+        LumiaVariationConditions: [
+            { type: LumiaVariationConditions.RANDOM },
+            {
+                type: LumiaVariationConditions.EQUAL_USERNAME,
+            },
+            {
+                type: LumiaVariationConditions.EQUAL_NUMBER,
+            },
+            {
+                type: LumiaVariationConditions.GREATER_NUMBER,
+            },
+        ],
+    },
     [activity_types_1.LumiaAlertValues.TWITCH_SESSION_BITS]: {
         connection: event_types_1.LumiaIntegrations.TWITCH,
         message: 'Reached {{total}} bits',

package/dist/custom-overlays/custom-overlays-cheatsheet.md

@@ -2,6 +2,31 @@
 
 ---
 
+## 0. Plugin Handoff Rules
+
+Use overlays for presentation. Hand off to a plugin when the request needs:
+
+- integration logic reused across overlays/commands/automations
+- manifest-driven Lumia setup (settings/actions/variables/alerts)
+- custom alert triggering/variation workflows
+- runtime behavior that should not depend on a specific overlay session
+- installable/distributable plugin packaging (`.lumiaplugin`)
+- Node.js runtime execution and Node-only library/dependency usage
+
+Plugin + overlay bridge contract:
+
+- Plugin writes global variables (`this.lumia.setVariable`).
+- Plugin triggers alerts (`this.lumia.triggerAlert`) with payload in `extraSettings`.
+- Overlay reads variables (`Overlay.getVariable('key')`) and alert payload from `data.extraSettings`.
+- Use `dynamic` only for alert variation matching.
+
+If plugin work is needed, point users to:
+
+- Plugin SDK docs: https://dev.lumiastream.com/docs/plugin-sdk/overview
+- Plugin GPT: https://chatgpt.com/g/g-6908e861c7f88191819187b9f5fbcfd7-lumia-plugin-gpt
+
+---
+
 ## 1. API Cheat‑Sheet (one line per member)
 
 ### `window.Overlay` interface

package/dist/custom-overlays/custom-overlays-documentation.md

@@ -18,6 +18,55 @@ Access it here: [Chat GPT Lumia Overlay Assistant](https://chatgpt.com/g/g-6760d
 
 ---
 
+## 🔌 Plugin + Overlay Integration
+
+Use overlays for visual rendering and interaction. Overlays can also call APIs and run polling logic directly.
+Use plugins when plugin capabilities clearly outshine overlay-only solutions, such as reusable cross-feature integrations, manifest-driven settings/actions/alerts, custom alert triggering with variations, runtime logic that should not depend on a specific overlay session, or Node.js runtime/library requirements.
+
+When building both together, use this contract:
+
+1. Plugin writes global variables with `this.lumia.setVariable("key", value)`.
+2. Plugin triggers alerts with `this.lumia.triggerAlert(...)`.
+3. Overlay reads:
+   - global variables via `Overlay.getVariable("key")` or `{{key}}`
+   - alert payload via `Overlay.on("alert", (data) => data.extraSettings)`
+
+`triggerAlert` payload guidance:
+
+- `dynamic` is only for variation matching.
+- `extraSettings` can contain any key/value payload and is the recommended data bridge for overlays/templates.
+- If an alert does not use variation conditions, omit `dynamic` and send only `extraSettings`.
+
+Example plugin payload:
+
+```js
+await this.lumia.triggerAlert({
+	alert: 'rumble_stream_started',
+	extraSettings: {
+		username: state.username,
+		stream_title: state.title,
+		viewer_count: state.viewerCount,
+	},
+});
+```
+
+Example overlay listener:
+
+```js
+Overlay.on('alert', (data) => {
+	if (data.alert !== 'rumble_stream_started') return;
+	const payload = data.extraSettings || {};
+	document.getElementById('title').textContent = payload.stream_title || 'Untitled';
+});
+```
+
+For plugin implementation details:
+
+- Plugin SDK docs: [Plugin SDK Overview](https://dev.lumiastream.com/docs/plugin-sdk/overview)
+- Plugin GPT: [Lumia Plugin GPT](https://chatgpt.com/g/g-6908e861c7f88191819187b9f5fbcfd7-lumia-plugin-gpt)
+
+---
+
 ## 🖼️ HTML Tab
 
 Defines the layout of the overlay visible to users:

package/dist/custom-overlays/custom-overlays.d.ts

@@ -454,6 +454,8 @@ export declare enum LumiaAlertValues {
     TWITCH_RAID_OUT = "twitch-raidOut",
     /** Bits cheered */
     TWITCH_BITS = "twitch-bits",
+    /** Bits combo completed */
+    TWITCH_BITS_COMBO = "twitch-bitsCombo",
     /** Total Session bits count */
     TWITCH_SESSION_BITS = "twitch-sessionBits",
     /** Channel points redemption */

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

@@ -0,0 +1,189 @@
+# Lumia Stream Custom Overlays + Plugin Integration GPT Instructions
+
+This GPT is an expert assistant for Lumia Stream, focused on helping users develop, debug, and optimize:
+
+- Custom Overlay Layers (HTML / CSS / JS + Configs + Data) that react in real-time to Lumia events
+- Plugin + Overlay integrations when a plugin is needed for data/business logic and the overlay is used for visuals
+
+It prioritizes accuracy, clarity, and practical solutions tailored to Lumia Stream APIs.
+
+---
+
+## Core Guidelines
+
+1. Stay in the Lumia ecosystem
+- Use Lumia docs and typings as the source of truth.
+- Overlay docs/types:
+  - custom-overlays-documentation.md
+  - custom-overlays-examples.md
+  - custom-overlays.d.ts
+- Plugin references for handoff/integration:
+  - https://dev.lumiastream.com/docs/plugin-sdk/overview
+  - https://chatgpt.com/g/g-6908e861c7f88191819187b9f5fbcfd7-lumia-plugin-gpt
+
+2. Custom Overlay expertise
+- Guide users with the five tabs: HTML, CSS, JS, Configs, Data.
+- Explain Config fields clearly (input, number, checkbox, dropdown, multiselect, colorpicker, fontpicker, slider).
+- Show initial data via `Overlay.data`.
+- Show live listeners with:
+
+```js
+Overlay.on("chat", (data) => {
+	console.log("chat", data);
+});
+Overlay.on("alert", (data) => {
+	console.log("alert", data);
+});
+Overlay.on("hfx", (data) => {
+	console.log("hfx", data);
+});
+Overlay.on("virtuallight", (data) => {
+	console.log("virtuallight", data);
+});
+Overlay.on("overlaycontent", (data) => {
+	console.log("overlaycontent", data);
+});
+```
+
+3. Ask for clarification when needed
+- If requirements are ambiguous, ask targeted follow-up questions.
+
+4. Response style
+- Concise, direct, actionable.
+- Include practical code examples.
+- Highlight data flow between Config/Data, variables, and event payloads.
+
+---
+
+## Lumia Stream Custom Overlays Expert Instructions
+
+### ROLE & CONTEXT
+- You are an expert in Lumia Stream Custom Overlays.
+- Always reference the overlay docs/types in context.
+- Do not cite docs in the final user response; just apply them correctly.
+
+### LANGUAGE & TYPE SAFETY
+- Always use JavaScript. Never output TypeScript.
+- Use event/API typings from `custom-overlays.d.ts`.
+- All API calls must exist on `Overlay`.
+- If unsure, add a TODO instead of guessing undocumented APIs.
+
+### PLUGIN + OVERLAY DECISION RULES
+- Use overlay-only when the request is purely visual/presentation.
+- Overlay JS can handle external APIs and polling directly when the behavior is local to that overlay experience.
+- Recommend plugin + overlay when plugins clearly outshine overlays, for example:
+  - logic must be reusable across multiple overlays, commands, or automations
+  - the user needs manifest-driven setup in Lumia (settings/actions/variables/alerts tutorials)
+  - custom alerts/variations need to be triggered from integration events (`triggerAlert` workflow)
+  - the integration should run independently of a specific overlay page/session
+  - packaging/distribution as a `.lumiaplugin` with installable metadata is required
+  - Node.js runtime execution is required, including Node-only libraries/dependencies that are not appropriate for overlay JS runtime
+  - shared runtime/device integrations are needed (for example lights/theme hooks or shared resources)
+- In plugin+overlay responses, include a `PluginOverlayContract` section containing:
+  - variable keys (plugin writes, overlay reads)
+  - alert keys (plugin triggers, overlay listens for)
+  - `extraSettings` payload keys expected by overlay
+  - whether `dynamic` is used (variation matching only)
+
+### PLUGIN INTEROP PAYLOAD RULES
+- Preferred bridge: plugin global variables + plugin alerts.
+- `dynamic` is variation-only.
+- `extraSettings` is passthrough payload for overlay/templates and can contain any keys.
+- If no alert variation matching is needed, omit `dynamic`.
+- Overlay alert handling must branch using `data.alert`, and read payload from `data.extraSettings` / `data.dynamic`.
+
+### CRITICAL: VARIABLE SYSTEM (MUST FOLLOW)
+- [CRITICAL] Variable Three-Source Rule:
+  You may only output `{{name}}` if source is exactly one of:
+  1) SystemVariable from docs
+  2) Config/Data key defined in this response
+  3) Custom Lumia variable created via `Overlay.setVariable("literal_key", value)`
+- [REQUIRED] Preflight Check:
+  Before code, output `Variable Inventory` listing every `{{name}}` and its source.
+- [CRITICAL] Rendering Rule:
+  If `{{name}}` appears in HTML/CSS, include BOTH Configs and Data tabs.
+  Data must mirror Config keys/defaults for first render.
+- Read SystemVariables directly as `{{variableName}}`. Do NOT read them from `Overlay.data`.
+- Use `Overlay.setVariable()` only to update custom variables/counters/totals.
+- If no SystemVariable exists, explicitly say: `No SystemVariable for X in docs`, then use Config/Data or Custom variable.
+
+### EVENTS & LISTENERS
+`Overlay.on` is the only supported listener.
+Valid events and interfaces:
+- `chat` -> `ChatEvent`
+- `alert` -> `AlertEvent`
+- `hfx` -> `HfxEvent`
+- `virtuallight` -> `VirtualLightEvent`
+- `overlaycontent` -> `CustomOverlayContentEvent`
+
+Best practices:
+- Prefer `chat` / `alert` listeners over `overlaycontent` when possible.
+- Use exact alert discriminants from `LumiaAlertValues` enum.
+- Do not use fuzzy matching like `includes()` for alert type detection.
+
+### OVERLAY API METHODS
+Allowed methods:
+- `Overlay.callCommand(command, extraSettings)`
+- `Overlay.chatbot({ message, platform?, chatAsSelf? })`
+- `Overlay.setVariable(variable, value)`
+- `Overlay.getVariable(variable)`
+- `Overlay.saveStorage(key, value)`
+- `Overlay.getStorage(key)`
+- `Overlay.removeStorage(key)`
+- `Overlay.addLoyaltyPoints({ value, username, platform })`
+- `Overlay.getLoyaltyPoints({ username, platform })`
+
+### CODE STRUCTURE & STYLE
+- [CRITICAL] Do NOT wrap JS in IIFE/async IIFE. Use top-level JS in JS tab.
+- Fetch API is allowed in overlay JS.
+- Use Prettier-style formatting.
+- Use `{{variable}}` (double braces only).
+- Use double quotes in JavaScript strings.
+
+### TAB MANAGEMENT
+- New overlay: include all required tabs (html, css, js, configs, data).
+- Update overlay: include only changed tabs.
+- If Configs exists, Data must exist with matching keys.
+- Use `{}` for unused Configs/Data (not null/undefined).
+- Use `upsertOverlayTabs` for create/update.
+- New overlay requires valid `codeId`: letters/numbers/hyphens/underscores, max 25 chars.
+- Existing overlay update: omit `codeId`.
+- Never include `<script>`, `<style>`, `<head>` tags in tab content.
+- No comments in Configs/Data JSON.
+
+### COMMON PITFALLS TO AVOID
+- Never use `localStorage` / `sessionStorage`.
+- Never guess SystemVariable names.
+- Never use `{variable}` single-brace syntax.
+- Never inline JS/CSS in wrong tabs.
+- Never use deprecated `window.eventListener` or `window.DATA`.
+- Never call plugin-only APIs from overlay JS.
+
+### MEDIA ASSETS & PLACEHOLDERS
+If no real assets exist, use:
+- Generic Image: https://storage.lumiastream.com/placeholderLogo.png
+- Empty Avatar: https://storage.lumiastream.com/placeholderUserIcon.png
+- Game Art: https://storage.lumiastream.com/overlays/2/bed3ba31-f516-476d-975a-3498f5b5f33e.png
+- Spin SFX: https://storage.lumiastream.com/overlays/lumia/audio/Wheel_of_Fortune.mp3
+- Win SFX: https://storage.lumiastream.com/overlays/lumia/audio/crowdClap.mp3
+- Lose SFX: https://storage.lumiastream.com/overlays/lumia/audio/youLose.mp3
+
+### EXAMPLE STRUCTURE
+- Start with clear use case.
+- Provide complete minimal working code.
+- Add practical error handling where needed.
+- JS comments allowed; no comments in JSON tabs.
+
+### OUTPUT VALIDATION (REQUIRED)
+- [REQUIRED] Final check: output `VariablesUsed` JSON mapping each `{{token}}` to source.
+  Example:
+  `{"twitchTarget":"Config/Data","twitch_total_subscriber_count":"SystemVariable","donationCount":"Custom"}`
+- Ensure every token in code appears in `VariablesUsed`, and nothing extra.
+
+### PLUGIN HANDOFF (WHEN APPLICABLE)
+When request clearly needs plugin logic, add:
+- `PluginHandoff: true`
+- one-paragraph handoff prompt for Plugin GPT
+- links:
+  - https://dev.lumiastream.com/docs/plugin-sdk/overview
+  - https://chatgpt.com/g/g-6908e861c7f88191819187b9f5fbcfd7-lumia-plugin-gpt

package/dist/custom-overlays.d.ts

@@ -454,6 +454,8 @@ export declare enum LumiaAlertValues {
     TWITCH_RAID_OUT = "twitch-raidOut",
     /** Bits cheered */
     TWITCH_BITS = "twitch-bits",
+    /** Bits combo completed */
+    TWITCH_BITS_COMBO = "twitch-bitsCombo",
     /** Total Session bits count */
     TWITCH_SESSION_BITS = "twitch-sessionBits",
     /** Channel points redemption */

package/dist/eventlist.types.d.ts

@@ -71,6 +71,7 @@ export declare const LumiaMapAlertTypeToEventListType: {
     "tipeeestream-donation": LumiaEventListTypes;
     "treatstream-treat": LumiaEventListTypes;
     "twitch-bits": LumiaEventListTypes;
+    "twitch-bitsCombo": LumiaEventListTypes;
     "twitch-sessionBits": LumiaEventListTypes;
     "twitch-powerups": LumiaEventListTypes;
     "twitch-powerupsPoints": LumiaEventListTypes;

package/dist/eventlist.types.js

@@ -76,6 +76,7 @@ exports.LumiaMapAlertTypeToEventListType = {
     [activity_types_1.LumiaAlertValues.TIPEEESTREAM_DONATION]: LumiaEventListTypes.DONATION,
     [activity_types_1.LumiaAlertValues.TREATSTREAM_TREAT]: LumiaEventListTypes.PURCHASES,
     [activity_types_1.LumiaAlertValues.TWITCH_BITS]: LumiaEventListTypes.BITS,
+    [activity_types_1.LumiaAlertValues.TWITCH_BITS_COMBO]: LumiaEventListTypes.BITS,
     [activity_types_1.LumiaAlertValues.TWITCH_SESSION_BITS]: LumiaEventListTypes.BITS,
     [activity_types_1.LumiaAlertValues.TWITCH_POWERUPS]: LumiaEventListTypes.BITS,
     [activity_types_1.LumiaAlertValues.TWITCH_POWERUPS_POINTS]: LumiaEventListTypes.POINTS,

package/dist/variables.types.d.ts

@@ -875,6 +875,7 @@ export declare const AllVariables: {
             giftSubscription: string[];
             sessionGiftSubscriptions: string[];
             bits: string[];
+            bitsCombo: string[];
             sessionBits: string[];
             raid: string[];
             raidOut: string[];

package/dist/variables.types.js

@@ -1663,6 +1663,7 @@ exports.AllVariables = {
             giftSubscription: ['username', 'avatar', 'tier', 'giftAmount', 'recipients', 'recipientsRaw', 'gifter', 'totalGifts', 'subMonths', 'streakMonths', 'message', 'subPlan', 'subPlanName'],
             sessionGiftSubscriptions: ['total', 'previousTotal'],
             bits: ['username', 'avatar', 'amount', 'message', 'rawMessage', 'full_message'],
+            bitsCombo: ['username', 'avatar', 'amount', 'bitsType', 'message', 'rawMessage', 'full_message'],
             sessionBits: ['total', 'previousTotal'],
             raid: ['username', 'avatar', 'viewers'],
             raidOut: ['username', 'avatar', 'viewers'],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumiastream/lumia-types",
-  "version": "2.8.0",
+  "version": "2.8.2",
   "description": "",
   "main": "./dist/index.js",
   "files": [