@lumiastream/lumia-types 2.8.2 → 2.8.3

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

@@ -0,0 +1,35 @@
+---
+sidebar_position: 3
+title: Custom actions
+description: Custom Actions allow you to tap into how Lumia Stream calls actions from the inside
+---
+
+`Custom Actions` allow you to tap into how Lumia Stream calls actions from the inside.
+`Custom Actions` are mainly meant for things that we haven't added as a `Helper function` yet. For instance, actions for Spotify, Twitch, Streamer.Bot etc are all actions that we do not have a have helper functions for. This is where an action will step in.
+
+You can use actions by just passing in one object, or an array of objects.
+If you pass in an array of actions then any action that can be awaited will be wait until the promise has been resolved.
+
+This documentation for every action we use in Lumia can get extremely broad, so we will give examples for different actions, but if you get stuck please visit our [**Discord**](https://discord.gg/R8rCaKb) to ask us any questions.
+
+Let's get started:
+
+### Generic Action
+
+`actions([ { base: "lumia", type: "tts", value: { message: "Hello" }, variables: {} } ]);`:
+
+#### Before we begin, let's dissect this.
+
+`base`: will be the base of actions that can be used with Custom Code. The different bases are:
+`delay, lumia, overlay, api, websocket, commandRunner, inputEvent, obs, slobs, twitch, twitter, streamerbot, midi, osc, artnet, mqtt, serial, broadlink, spotify, vlc, voicemod`
+
+`type`: Every base has different action types. For instance, the base `lumia` has: `chatbot, tts, setStreamMode, toggleStreamMode` and much more.
+To find the list of types that each base has below. Check in the side bar to quickly get to the base you're interested in.
+
+`value`: can sometimes be an object and sometimes a string, it all depends on the `base` and `type`
+
+`variables`: allows you to send in different variables for each action. But do note that the variables that are already on the command/alert will also be spread on to this variables object. Variables are not required
+
+There are more fields that are sometimes used in actions. We will try to list out as many common examples down below along with the schema for them
+
+#### More documentation coming soon

package/dist/custom-code/examples/create-counter.md

@@ -0,0 +1,40 @@
+---
+sidebar_position: 1
+title: Create counter
+---
+
+You can set up a manual counter so that you can trigger multiple things based on the counter value
+
+e.g. the code below will trigger a command named **'money-12'** when the **counter = 12**
+
+```js
+async function() {
+
+    // You can get your variable's value that you just set here
+    let redeemCount = await getVariable('redeemCount');
+
+    if (!redeemCount) {
+        // If variable does not exist it will create it
+        redeemCount = await setVariable({ name: 'redeemCount', value: 10 });
+    }
+
+    redeemCount++;
+    await setVariable({ name: 'redeemCount', value: redeemCount });
+
+    if (redeemCount === 12) {
+            // call the command named money-12
+            callCommand({ name: 'money-12' });
+            // show a popup message in the Lumia stream app with '{{username}} is the 12th redeemer' inside
+            showToast({ message: '{{username}} is the 12th redeemer' });
+    }
+
+    // always make sure this is the last line in the code otherwise your computer may get slower due to memory leaks
+    done();
+}
+```
+
+:::tip
+
+**code blocks** like the one above 👆 have a copy button on the **top right corner** click it then paste in Lumia stream
+
+:::

package/dist/custom-code/examples/global-store.md

@@ -0,0 +1,36 @@
+---
+sidebar_position: 6
+title: Global Store (Persistent Storage)
+---
+
+# Storing data for Custom Code
+
+We expose a global store that you can use with your custom code to store any data type that you need to and it will be persisted. This is useful to store things like arrays and objects without needing to store them in variables.
+
+There are 4 different functions that you can use with the Store:
+
+```md
+- getStore()
+- getStoreItem(name: string)
+- setStore({ name: string; value: any })
+- resetStore()
+```
+
+```js
+async function() {
+	let tempUsers = await getStoreItem('users');
+	if (!tempUsers) {
+		tempUsers = [];
+	}
+	tempUsers.push("{{username}}");
+	await setStore({ name: 'users', value: tempUsers });
+	showToast({ message: tempUsers.length, time: 10000 });
+	done();
+}
+```
+
+:::tip
+
+**code blocks** like the one above 👆 have a copy button on the **top right corner** click it then paste in Lumia stream
+
+:::

package/dist/custom-code/examples/random-twitch-clip.md

@@ -0,0 +1,38 @@
+---
+sidebar_position: 2
+title: Random Twitch Clip
+---
+
+# Randomly getting the latest Twitch Clip from a user
+
+You can call requests from integrations that we support that have an access token. You can also pass in variable values when calling other commands/alerts to pass in extra data that you may need in that command.
+
+```js
+async function() {
+	try {
+		const twitchToken = await getToken('twitch');
+		const twitchClientId = await getClientId('twitch');
+
+		// userId is a variable that comes from chat commands. This will get the clips of the user who's chatting
+		const clipsRes = await fetch('https://api.twitch.tv/helix/clips?broadcaster_id={{userId}}', {
+			headers: {
+				Authorization: `Bearer ${twitchToken}`,
+				'Client-ID': twitchClientId
+			}
+		});
+		const clips = (await clipsRes.json())?.data;
+		const randomClip = clips[Math.floor(Math.random() * clips.length)];
+		chatbot({ message: `${randomClip.title}: ${randomClip.url}` });
+	} catch (err) {
+		showToast({ message: 'error: ' + err.message });
+	}
+
+	done({ variables: { user_clip_title: randomClip.title, user_clip: randomClip.url } });
+}
+```
+
+:::tip
+
+**code blocks** like the one above 👆 have a copy button on the **top right corner** click it then paste in Lumia stream
+
+:::

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

@@ -0,0 +1,29 @@
+---
+sidebar_position: 3
+title: Roll dice
+---
+
+# Roll a dice with Text To Speech
+
+You can use Javascript to randomly pick a number and if it lands on your chosen number the user will get a special Text To Speech shoutout
+
+```js
+async function() {
+	const diceRoll = Math.ceil(Math.random()*6);
+
+	if (diceRoll === 3) {
+			tts({ message: "Congratulations {{username}}! You rolled a 3", voice: "default", volume: 100 })
+			// you can switch between all the tts option that we support
+			// tts({ message: "Congratulations {{username}}! You rolled a 3", voice: "Brian", volume: 100 })
+	}
+
+	// always make sure this is the last line in the code otherwise your computer may get slower due to memory leaks
+	done();
+}
+```
+
+:::tip
+
+**code blocks** like the one above 👆 have a copy button on the **top right corner** click it then paste in Lumia stream
+
+:::

package/dist/custom-code/examples/send-different-chatbot-for-userlevel.md

@@ -0,0 +1,41 @@
+---
+sidebar_position: 4
+title: Different Chatbot message for user levels
+---
+
+# Different Chatbot message for user levels
+
+You can check the different userlevels for the person chatting and do different things based on their user level.
+In this example we'll be sending different chatbot messages based on the users level.
+
+```js
+async function() {
+	// {{userLevelsRaw}} returns an object with the various user levels on it. Since we want the original object here we're using getVariable instead of using template variables
+	const userLevels = await getVariable('userLevelsRaw');
+
+	if (!userLevels) {
+		chatbot({ message: `Thanks for lurking in my stream {{username}}. You triggered {{command}}!` });
+	} else if (userLevels.isSelf) {
+		chatbot({ message: "Don't worry it's just me triggering a command named !{{command}}" });
+	} else if (userLevels.subscriber || userLevels.tier3 || userLevels.tier2 || userLevels.tier1) {
+		chatbot({ message: "Wow, you're a subscriber? Thanks for triggering {{command}}. Have a nice day!" });
+	} else if (userLevels.mod) {
+		chatbot({ message: 'Thank you for being a wonderful mod. My mod {{username}} triggered {{command}}!' });
+	} else if (userLevels.vip) {
+		chatbot({ message: 'VIPS raise the roof! {{username}}, the real VIP, triggered {{command}}!' });
+	} else if (userLevels.follower) {
+		chatbot({ message: `Thanks for being a loyal follower {{username}}. You triggered {{command}}!` });
+	} else {
+		chatbot({ message: `Thanks for lurking in my stream {{username}}. You triggered {{command}}!` });
+	}
+
+	// always make sure this is the last line in the code otherwise your computer may get slower due to memory leaks
+	done();
+}
+```
+
+:::tip
+
+**code blocks** like the one above 👆 have a copy button on the **top right corner** click it then paste in Lumia stream
+
+:::

package/dist/custom-code/examples/track-subscribers.md

@@ -0,0 +1,30 @@
+---
+sidebar_position: 5
+title: Track subscribers
+---
+
+# Read/Write to a file to keep track of subscribers
+
+You can read from a file and get values from it as well as write to a file.
+This can be very useful if other apps are reading and writing to a text file. An example of this is OBS text sources
+
+```js
+async function() {
+	// You have the ability to overwrite the whole file by setting append to false, or appending to the file in case you would like to keep a log of things
+	await writeFile({ path: 'C:	\\Users\\Lumia\\Desktop\\lastSubscriber.txt', message: '{{username}}\n', append: true });
+
+	// You can get your variable's value that you just set here
+	const lastSubscribers = await readFile('C:\\Users\\Lumia\\Desktop\\lastSubscriber.txt');
+
+	showToast({ message: 'The last subscribers were: ' + lastSubscribers });
+
+	// always make sure this is the last line in the code otherwise your computer may get slower due to memory leaks
+	done();
+}
+```
+
+:::tip
+
+**code blocks** like the one above 👆 have a copy button on the **top right corner** click it then paste in Lumia stream
+
+:::

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

@@ -0,0 +1,29 @@
+# Lumia Stream Custom Code GPT Instructions
+
+Use this with the Custom Code docs:
+- `what-is-custom-javascript.md`
+- `important-notes.md`
+- `helper-functions.md`
+- `custom-actions.md`
+- `examples/*.md`
+
+## Required Output Rules
+
+1. Always generate JavaScript (not TypeScript).
+2. Prefer returning a full Lumia Custom Code wrapper:
+
+```js
+async function() {
+  // logic
+
+  // Make sure you call done() to avoid memory leaks
+  done();
+}
+```
+
+3. Always call `done()` exactly once before finishing the function, unless the user explicitly asks for a partial snippet.
+4. Do not output markdown fences or prose when the caller expects code-only output.
+5. Use helper functions documented in `helper-functions.md` instead of inventing undocumented APIs.
+6. Keep examples compatible with Lumia variable syntax (e.g. `{{username}}`).
+7. When accessing numeric variables, parse values safely before math/comparisons.
+8. If a capability is not documented, state that clearly and provide a safe alternative.

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

@@ -0,0 +1,561 @@
+---
+sidebar_position: 2
+title: Helper functions
+description: Helper functions are a premade code that helps you build your custom scripts
+---
+
+These helper functions are premade code that we setup that you can use to help you build your custom code. You will find `use case examples` in the each section as well.
+
+### Done
+
+`done({ shouldStop?: boolean; actionsToStop?: Array<string>; variables?: {[key: string]: string | number }}?)`: Done tell Lumia Stream that the script is complete and that the thread is safe to close now. You can also stop the command/alert in it's track by passing shouldStop true into the parameters.
+If you would like to modify/add variables that other actions could use, you can return them in the variables parameter.
+
+You can also choose to only stop some actions rather than stopping the whole command by using actionsToStop.
+The different actionsToStop keys relate to the action. The keys are:
+`devices, tts, chatbot, hfx, lumia, overlay, voicemod, streamerbot, obs, slobs, midi, osc, mqtt, serial, broadlink, websocket, twitter, twitch, spotify, vlc, artnet, api, commandRunner, inputEvent`
+
+```js
+// Basic done
+async function() {
+    done();
+}
+// Should stop
+async function() {
+    done({ shouldStop: true, actionsToStop: [] });
+}
+// Should stop certain actions like tts and chatbot
+async function() {
+    done({ shouldStop: true, actionsToStop: ['tts', 'chatbot'] });
+}
+// Passing variables
+async function() {
+    done({ variables: { message: "Message changed" } });
+}
+```
+
+:::tip
+
+**code blocks** like the one above 👆 have a copy button on the **top right corner** click it then paste in Lumia stream
+
+:::
+
+### Add Log to both Toast and Dashboard
+
+`log(message: any)`: The best way to log what's going on is to either use `log` or `console.log`. These will show a toast as well as add a log to the dashboard in case you need to reference it later.
+
+```js
+async function() {
+    log({ data: "my data" });
+    // Or using console.log
+    console.log({ data: "my data" });
+}
+```
+
+### Show Toast
+
+`showToast({ message: string; time?: number })`: Show toast will show a popup message notification in Lumia. The time for how long it shows is in milliseconds. Leave it 0 to show forever
+
+```js
+async function() {
+	// shows a message popup saying command used for 200 milliseconds and the popup will close
+    showToast({ message: "command used", time: 200 });
+
+	// doing the same as the above but the popup does not close automatically
+    showToast({ message: "command used", time: 0 });
+
+	// you can also just send the message which by default the popup does not close automatically
+    showToast({ message: "command used" });
+}
+```
+
+### Add Log to Dashboard
+
+`addLog(message: string)`: Show a log in the dashboard to keep track of things
+
+```js
+async function() {
+	//shows in the logs section when this command is executed
+    addLog('log this command used');
+}
+```
+
+### Delay
+
+`delay(time: number)`: You can delay your code with our helper function that returns a promise. The time is in milliseconds.
+
+```js
+async function() {
+    // Waits for 2 seconds
+    await delay(2000);
+}
+```
+
+### Get Variable
+
+`getVariable(name: string)`: Retrieve a variables value based on it's name
+
+```js
+async function() {
+	//so if you have a variable named "my variable" in the variable page this code will get it's value. Notice that you need to await the result since getVariable returns a promise
+    const myVar = await getVariable('my variable');
+}
+```
+
+### Set Variable
+
+`setVariable({ name: string; value: string | number })`: Creates/Updates a variable with name and value provided. If the variable doesn't exist it will create it
+
+```js
+async function() {
+	// This creates a variable named "coins" with the value of 3
+    setVariable({ name: 'coins', value: 3 });
+}
+```
+
+### Delete Variable
+
+`deleteVariable(name: string | Array<string>)`: Delete a variable or multiple variables. If the variable doesn't exist it will still return as successful
+
+```js
+async function() {
+    deleteVariable('coins');
+    // Or you can pass in an array of variables
+    deleteVariable(['coins', 'myVar', 'other variable']);
+}
+```
+
+### Get All Variables
+
+`getAllVariables()`: Ability to get all local and global variables with one easy call
+
+```js
+async function() {
+    let variables = await getAllVariables();
+    showToast({ message: JSON.stringify(variables) , time: 10000});
+
+    // always make sure this is the last line in the code otherwise your computer may get slower due to memory leaks
+    done();
+}
+```
+
+### Get Persisted Store
+
+`getStore()`: Retrieves the complete custom code store. This store is a persisted storage throughout all of your custom code and can assign any data type like string, numbers, arrays, and objects
+
+```js
+async function() {
+	//Notice that you need to await the result since getStore returns a promise
+    const store = await getStore();
+}
+```
+
+### Get Persisted Store Item
+
+`getStoreItem(name: string)`: Get's one item from the custom code store
+
+```js
+async function() {
+	//Notice that you need to await the result since getStoreItem returns a promise
+    const users = await getStoreItem('users');
+}
+```
+
+### Set Persisted Store Item
+
+`setStore({ name: string; value: any })`: Sets an item in the store. You can use any data type as your value
+
+```js
+async function() {
+    await setStore({ name: 'users', value: [] });
+}
+```
+
+### Reset Persisted Store
+
+`resetStore()`: Resets the store removing all items inside of it
+
+```js
+async function() {
+	//Notice that you need to await the result since resetStore returns a promise
+    await resetStore();
+}
+```
+
+### Get Lights
+
+`getLights()`: Get the list of lights the streamer has along with it's type and id. The type and id is required to send color or power to specific lights
+
+```js
+async function() {
+    const lights = await getLights()
+}
+```
+
+### Send Color To Lights
+
+`sendColor({ color?: string | { r: number; g: number; b: number }; power?: boolean; brightness?: number; transition?: number; lights?: Array<{ id: string | number; type: string }> })`: Send a color or power to either all lights or a set of lights. Do not send the `lights` array when you want to target every lights. Every parameter is optional. The type and id is required to send color or power to specific lights
+
+```js
+async function() {
+    // Send hex color to all lights
+    sendColor({ color: "#FF4076", brightness: 100 });
+
+    // Send rgb color to all lights
+    sendColor({ color: { r: 0, g: 0, b: 255 }, brightness: 100 });
+
+    // Send power to all lights
+    sendColor({ power: true });
+
+    // Send to specific lights
+    sendColor({ color: "#FF4076", brightness: 100, transition: 0, lights: [{ type: "hue", id: "1" }, { type: "lifx", id: "abc" }] });
+
+    // For Nanoleaf lights, ensure id values are integers without quotation marks (e.g., 14608). Quoted string IDs will not work for Nanoleaf.
+    sendColor({ color: "#FF4076", brightness: 100, transition: 0, lights: [{ type: "nanoleaf", id: 14608 }] });
+
+
+    // Send to an overlay virtual light
+    sendColor({ color: "#FF4076", brightness: 100, lights: [{ type: "virtuallights", id: "abc-123-520" }] });
+}
+```
+
+### Get API Options
+
+`getApiOptions()`: Contains information like commands, types, connections, and more
+
+```js
+async function() {
+    const lights = await getApiOptions()
+}
+```
+
+### Call Alert
+
+`callAlert({ name: string; variation?: string; variableValues?: {[key: string]: string|number } })`: Call an alert based on your conditions. You can also call a variation given it's name. When calling an alert/command from custom code the variableValues will be inherited from the parent, but you can also override variable values by passing it in to the call function.
+
+The valid alert keys are:
+
+```
+lumia-redemption, twitch-streamLive, twitch-streamOffline, twitch-follower, twitch-subscriber, twitch-giftSubscription, twitch-host, twitch-raid, twitch-bits, twitch-redemption, twitch-hypetrainStarted, twitch-hypetrainProgressed, twitch-hypetrainLevelProgressed, twitch-hypetrainEnded, twitch-pollStarted, twitch-pollProgressed, twitch-pollEnded, twitch-predictionStarted, twitch-predictionProgressed, twitch-predictionLocked, twitch-predictionEnded, twitch-goalStarted, twitch-goalProgressed, twitch-goalEnded, twitch-categoryChanged, twitch-clip, youtube-member, youtube-subscriber, youtube-superchat, youtube-supersticker, facebook-follower, facebook-reaction, facebook-star, facebook-support, facebook-subscriptionGift, facebook-share, facebook-fan, tiktok-follower, tiktok-like, tiktok-gift, tiktok-subscriber, tiktok-share, tiktok-streamEnd, streamlabs-donation, streamlabs-charity, streamlabs-merch, streamlabs-redemption, streamlabs-primegift, streamelements-donation,  extralife-donation, donordrive-donation, tiltify-campaignDonation, tipeeestream-donation, treatstream-treat, patreon-pledge, obs-switchProfile, obs-switchScene, obs-sceneItemVisibility, obs-sceneItemHidden, obs-switchTransition, obs-transitionBegin, obs-transitionEnd, obs-streamStarting, obs-streamStopping, obs-recordingStarting, obs-recordingStopping, slobs-switchSceneCollection, slobs-switchScene, slobs-sceneItemVisibility, slobs-sceneItemHidden, spotify-switchSong, spotify-songPlayed, spotify-songPaused, vlc-switchSong, vlc-songPlayed, vlc-songPaused, pulse-heartrate, pulse-calories, twitter-follower, twitter-like, twitter-retweet, woocommerce-order, kofi-donation, kofi-subscription, kofi-commission, kofi-shopOrder, streamerbot-action
+```
+
+```js
+async function() {
+	// This will call alert 'twitch-subscriber' and call the variation of it named 'gift3' and change the variable named siren to 3
+    callAlert({ name: 'twitch-subscriber', variation: 'gift3', variableValues: {'message': 'Big gift' } })
+}
+```
+
+### Call Command
+
+`callCommand({ name: string; variableValues?: {[key: string]: string|number } })`: Call a command based on your conditions. When calling an alert/command from custom code the variableValues will be inherited from the parent, but you can also override variable values by passing it in to the call function.
+
+```js
+async function() {
+	// This will call command called 'cheers' and change the variable named "message" to the value "you are awesome"
+    callCommand({ name: 'cheers', variableValues: {'message': 'you are awesome' } })
+}
+```
+
+### Call Twitch Point Command
+
+`callTwitchPoint({ name: string; variableValues?: {[key: string]: string|number } })`: Call a twitch point command based on your conditions. When calling an alert/command from custom code the variableValues will be inherited from the parent, but you can also override variable values by passing it in to the call function.
+
+```js
+async function() {
+	// This will call Twitch Point called 'point' and change the variable named "message" to the value "you are awesome"
+    callTwitchPoint({ name: 'point', variableValues: {'message': "you are awesome" } });
+}
+```
+
+### Call Twitch Extension Command
+
+`callTwitchExtension({ name: string; variableValues?: {[key: string]: string|number } })`: Call a twitch extension command based on your conditions. When calling an alert/command from custom code the variableValues will be inherited from the parent, but you can also override variable values by passing it in to the call function.
+
+```js
+async function() {
+	// This will call Twitch Extension called 'point' and change the variable named "message" to the value "you are awesome"
+    callTwitchExtension({ name: 'point', variableValues: {'message': "you are awesome" } });
+}
+```
+
+
+### Read File
+
+`readFile(path: string)`: Read from a file on your local computer to get the contents of it to be displayed in your code. This is useful for other Apps that write and read to files so you can combine the usage of them in Lumia. To keep things consistent, try to use an absolute file path
+
+```js
+async function() {
+	// This will read the file from this path. Returns a promise so await is needed
+    const fileText = await readFile('C:\\Documents\\Lumiastream\\helper.txt');
+}
+```
+
+### Write File
+
+`writeFile({ path: string; message: string | number; append?: boolean })`: Write to a file on your local computer to update the contents of it. This is useful for other Apps that write and read to files so you can combine the usage of them in Lumia. OBS Text source is a great exmaple of this. You can optionally pass in an `append` to append to a text file instead of overwriting the whole file. When using append you can create a new line by starting with a blank line
+
+```js
+async function() {
+	// This will create a new file in the 'C:\Documents\Lumiastream\' named helper.txt and add the text "text inside this file" inside that file
+	await writeFile({ path: 'C:\\Documents\\Lumiastream\\helper.txt', value: 'text inside this file', append: true });
+}
+```
+
+### Text To Speech (TTS)
+
+`tts({ message: string; voice?: string; volume?: number })`: You can trigger Text To Speech directly inside of your code. You can even choose the voice and set the volume optionally
+
+```js
+async function() {
+	// This will read the message with text to speach using the voice that you added with the volume 60%
+    tts({ message: 'Lumia stream loves you',voice: 'Brian', volume: 60 });
+}
+```
+
+### Chat Bot
+
+`chatbot({ message: string; site?: 'twitch' | 'youtube' | 'facebook'; color?: string; chatAsSelf?: boolean })`: You can trigger a Chat bot directly inside of your code. You can even change the color of the message, whether to chat as your self or the bot, and the ability to change the site. Site can now be an array or a regular string.
+
+```js
+async function() {
+	//this will send a custom chatbot message "hello from Lumia Stream" to twitch colored with this hex code "#F57FAE" shown in the chat as your self
+    chatbot({ message: 'hello from Lumia Stream', site: "twitch", color:"#F57FAE", chatAsSelf:true });
+
+    // Send to multiple sites at once
+    chatbot({ message: 'hello from Lumia Stream', site: ["twitch", "youtube", "facebook"], color:"#F57FAE",chatAsSelf:true });
+}
+```
+
+### Play Audio
+
+`playAudio({ path: string | string[]; volume?: number; waitForAudioToStop?: boolean })`: You can play an audio file from either a URL or from a local path on your computer inside of your code. You can even wait for the audio to stop playing before the code continues by setting an await before while also setting waitForAudioToStop to true. You can also allow Lumia Stream to randomly play an audio file from a selection by passing an array of strings to path
+
+```js
+async function() {
+	playAudio({ path: "C:\\Documents\\Lumiastream\\lumiajam.mp3", volume: 100, waitForAudioToStop: false });
+
+    // Or you can await the sound to stop playing first
+    await playAudio({ path: "C:\\Documents\\Lumiastream\\lumiajam.mp3", volume: 100, waitForAudioToStop: true });
+
+    // You can also play multiple files by passing an array to path
+    await playAudio({ path: ["C:\\Documents\\Lumiastream\\lumiajam.mp3", "C:\\Documents\\Lumiastream\\lumiasecond.mp3"], volume: 100 });
+}
+```
+
+### 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
+
+```js
+async function() {
+    sendRawObsJson({
+        "request-type": "SetSceneItemEnabled",
+        "sceneItemEnabled": true,
+        "sceneItemId": 1,
+        "sceneName": "Scene 1"
+    });
+}
+```
+
+### Execute Shell Command
+
+`execShellCommand(command: string)`: You can execute shell commands and wait for their return value. It will send the stdout if successfull or the stderr if it fails. It will not reject the promise though
+
+```js
+async function() {
+    await execShellCommand("say wow");
+}
+```
+
+### Get Token
+
+`getToken(connection: "twitch" | "twitchChatbot" | "youtube" | "facebook" | "streamlabs" | "streamelements" | "treatstream" | "tipeeestream" | "tiltify" | "patreon" | "woocommerce" | "discord" | "twitter" | "spotify" | "pulsoid" | "wyze" | "homeassistant" | "govee" | "wled" )`: When you need to call a request that we don't directly support you can get the access token from Lumia before making the call. This is helpful for things where you need to call for instance the Twitch API, but you don't want to handle tokens and refreshing inside of your scripts. More examples of this below
+
+```js
+async function() {
+	// This will get the access token for your user on Twitch
+    const token = await getToken('twitch');
+}
+```
+
+### Get Client ID For Twitch
+
+`getClientId(connection: "twitch")`: When calling requests with Twitch's API you will need to pass in a Client-ID to the headers. We provide a Client ID that you can use to call the different api's with the permissions the user has selected. Check out [Twitch's developers docs](https://dev.twitch.tv/docs/api/reference) to learn what you can do
+
+```js
+async function() {
+	// This will get the client id for Twitch
+    const token = await getClientId('twitch');
+}
+```
+
+## Overlay Actions
+
+Note: When using layers you can call them by the layers name. But if you have multiple layers named the same thing in different overlays it may not trigger on the correct overlay. Make sure you give your layers a unique name so that you do not have any issues triggering the correct layer. We do not check for unique Overlay names and unique Layer names at this time since under the hood we use ID's
+
+### Overlay Alert Trigger
+
+`overlayAlertTrigger({ layer: string, firstMessage: string" })`: You can trigger a generic alert layer that you've created on your overlays. This will only trigger the generic alert though. To fire an alert that isn't the generic one you will need to use `callAlert`.
+`firstMessage` is the message that will show for the alert
+
+```js
+async function() {
+    overlayAlertTrigger({ layer: "my unique layer name", firstMessage: "{{message}}" });
+}
+```
+
+### Overlay Set Visibility
+
+`overlaySetVisibility({ overlay: string, on: boolean })`: You can set the visibility of the full overlay using this function. You should make sure all of your overlays have unique names. We do not check for unique names since under the hood we use ID's
+
+```js
+async function() {
+    overlaySetVisibility({ overlay: "my cool overlay", on: false });
+}
+```
+
+### Overlay Set Layer Visibility
+
+`overlaySetLayerVisibility({ layer: string, on: boolean })`: You can set the visibility of an overlay layer using this function. You should make sure all of your layers have unique names. We do not check for unique names since under the hood we use ID's
+
+```js
+async function() {
+    overlaySetLayerVisibility({ layer: "My layer", on: false });
+}
+```
+
+### Overlay Set Layer Position (X and Y)
+
+`overlaySetLayerPosition({ layer: string, content: string })`: You can set the x and y position of an overlay layer using this function. `content` is just a string that will correspond to the x and y position separated by a comma. Our overlay is also fast enough to handle interpolation in case you want to move things in a smooth way.
+
+```js
+async function() {
+    overlaySetLayerPosition({ layer: "My layer", content: "100,100" });
+}
+```
+
+### Overlay Set Text Content
+
+`overlaySetTextContent({ layer: string, content: string })`: You can set the text content of a text layer using this function. `content` is just a string that will correspond to the text that you want to set it to.
+
+```js
+async function() {
+    overlaySetTextContent({ layer: "My layer", content: "" });
+}
+```
+
+### Overlay Set Image Content
+
+`overlaySetImageContent({ layer: string, content: string })`: You can set the image content of an image layer using this function. `content` is just a string that will correspond to the image name or url that you want to set it to. If you use a name it will try to find the name of an asset that you have in your overlay library. So if you have an asset named `lumia_logo.gif` you can set the content to the exact name with or without the file extension. This can be useful to allow chat to change the media using a \{\{message\}\} variable. After the content is changed it will automatically make the layer visibile and start playing
+
+```js
+async function() {
+    overlaySetImageContent({ layer: "My layer", content: "lumia_logo.gif" });
+    // Without file extension
+    overlaySetImageContent({ layer: "My layer", content: "lumia_logo" });
+    // Or using a url
+    overlaySetImageContent({ layer: "My layer", content: "https://lumiastream.com/favicon.ico" });
+}
+```
+
+### Overlay Set Video Content
+
+`overlaySetVideoContent({ layer: string, content: string })`: You can set the video content of an video layer using this function. `content` is just a string that will correspond to the video name or url that you want to set it to. If you use a name it will try to find the name of an asset that you have in your overlay library. So if you have an asset named `lumia_video.webm` you can set the content to the exact name with or without the file extension. This can be useful to allow chat to change the media using a \{\{message\}\} variable. After the content is changed it will automatically make the layer visibile and start playing
+
+```js
+async function() {
+    overlaySetVideoContent({ layer: "My layer", content: "lumia_video.webm" });
+    // Without file extension
+    overlaySetVideoContent({ layer: "My layer", content: "lumia_video" });
+    // Or using a url
+    overlaySetVideoContent({ layer: "My layer", content: "https://lumiastream.com/video.webm" });
+}
+```
+
+### Overlay Set Audio Content
+
+`overlaySetAudioContent({ layer: string, content: string })`: You can set the audio content of an audio layer using this function. `content` is just a string that will correspond to the audio name or url that you want to set it to. If you use a name it will try to find the name of an asset that you have in your overlay library. So if you have an asset named `lumia_land.mp3` you can set the content to the exact name with or without the file extension. This can be useful to allow chat to change the media using a \{\{message\}\} variable. After the content is changed it will automatically make the layer visibile and start playing
+
+```js
+async function() {
+    overlaySetAudioContent({ layer: "My layer", content: "lumia_land.mp3" });
+    // Without file extension
+    overlaySetAudioContent({ layer: "My layer", content: "lumia_land" });
+    // Or using a url
+    overlaySetAudioContent({ layer: "My layer", content: "https://lumiastream.com/lumia_land.mp3" });
+}
+```
+
+### Overlay Set Media Volume
+
+`overlaySetVolume({ layer: string, volume: number })`: You can set the volume of a media layer using this function. `volume` is a number between 0 and 1 that will correspond to the volume url that you want to set it to. 1 is equal to 100, 0.5 is equal to 50%, and 0 is equal to 0%.
+
+```js
+async function() {
+    overlaySetVolume({ layer: "My layer", volume: .5 });
+}
+```
+
+### Overlay Play/Pause Media
+
+`overlayPlayPauseMedia({ layer: string, volume: number })`: You can play/pause a media layer using this function. `on` is a boolean that will correspond to the state of the media. `true` plays the media and `false` pauses the media.
+
+```js
+async function() {
+    overlayPlayPauseMedia({ layer: "My layer", on: false });
+}
+```
+
+### Overlay Send HFX
+
+`overlaySendHfx({ content: string, playAudio: boolean })`: You can directly trigger a HFX as well as play the audio or not using this function. No layer is needed here since HFX is always meant to have only one layer per overlay and will trigger any and all HFX video layers. `content` is a string that will correspond to the HFX name that you want to trigger. To see the list of names, please visit the HUDFX tab in the sidebar of Lumia Stream. Since these are updated weekly we will not store them in the documentation.
+
+```js
+async function() {
+    overlaySendHfx({ content: "ghost-talk", playAudio: true });
+}
+```
+
+### Overlay Set Timer
+
+`overlayTimer({ layer: string, content: string })`: You can update a timer layer using this function. `content` is a string that will correspond to the time to set the timer to. After the timer is changed it will automatically make the layer visibile and start playing. You can use math here and short wording. The operators can all be used: `(+, -, /, *)` followed by the number and then the unit of time `(s, m, h, d)`.
+You can also combine multiple values as well. Like `+1m10s` would increase the timer by 1 minute and 10 seconds. `=5m` would set the timer exactly at 5 minutes and will start running immediately.
+
+```js
+async function() {
+    overlayTimer({ layer: "My layer", content: "+5s" });
+}
+```
+
+### Overlay Shoutout
+
+`overlayShoutout({ layer: string, clipType: "clipFromTarget" | "clipFromSender" | "clipFromStreamer", clipRandom: boolean, clipLimit: number, clipMaxTime: string })`: You can send a shoutout directly to a shoutout layer using this function. `clipType` has three types. `clipFromTarget` will take a clip from the user who was tagged in the \{\{message\}\} variable. So you can use @lumiastream in the message and it will take a clip from that channel. `clipFromSender` will take a clip from the person who triggered the command. This normally corresponds to the \{\{user\}\} variable. `clipFromStreamer` will take a clip from your channel and send it over. You can decide to take a random clip by setting `clipRandom` to true. Or if you would like to take the first clip that matched the `clipMaxTime` given in milliseconds then you can set `clipRandom` to false. `clipLimit` will determing how many of the newest clips should be brought in to determine which clip should be selected. After a clip is selected it will start running immediately
+
+```js
+async function() {
+    // A random clip from the person who was tagged in the message that has a max clip time of 60 seconds and will only take in the newest 100 clips
+    overlayShoutout({ layer: "My layer", clipType: "clipFromTarget", clipRandom: true, clipLimit: 100, clipMaxTime: "60000" });
+
+    // The newest clip from the person who was tagged in the message that is under 20 seconds and will only take in the newest 20 clips
+    overlayShoutout({ layer: "My layer", clipType: "clipFromTarget", clipRandom: false, clipLimit: 20, clipMaxTime: "20000" });
+
+    // The newest clip from the person who triggered the command that is under 20 seconds and will only take in the newest 20 clips
+    overlayShoutout({ layer: "My layer", clipType: "clipFromSender", clipRandom: false, clipLimit: 20, clipMaxTime: "20000" });
+}
+```
+
+### Overlay Send To Custom Overlay
+
+`overlaySendCustomContent({ codeId: string, content: string, layer?: string })`: You can send a content directly to custom overlays. `codeId` is the id of the code that created the custom overlay and will only send to overlays with this codeId. `content` is a string, but you can also pass in strigified json and then parse it in the custom overlay js code.
+This function is useful for sending messages from a command or alert to your custom overlay without needing to rely on listening to events like chat and alerts. `layer` is not requred nor is it recommended to use if you will be sharing this command with your custom code.
+
+```js
+async function() {
+    // A regular string message that can be sent to your custom overlay
+    overlaySendCustomContent({ codeId: "myoverlay", content: "blue" });
+
+    // A strigified json string that can then be parsed on the custom overlay js side. Add a key to your json so you konw this data belongs to your overlay
+    overlaySendCustomContent({ codeId: "myoverlay", content: '{"key": "myoverlay", "color":"blue","age":5,"name":"user"}' });
+}
+```

package/dist/custom-code/important-notes.md

@@ -0,0 +1,22 @@
+---
+sidebar_position: 4
+title: Important notes
+---
+
+# Important notes
+
+- You can use variables inside of your script that are replaced with the variables before the script is even ran. So if you do `tts({ message: "{{username}}" })`, it will replace the `"{{username}}"` with whoever is calling the command before the script is even ran. Take note that the variable is wrapped in quotes to be used as a string since when it is replaced it does not automatically add the quotes.
+
+- By default variable values from the command/alert will be passed to the command/alert that you call. You can bypass those values as well as add new ones by passing in `variableValues` into the command. e.g: `callCommand({ value: 'cool-people', variableValues: { 'username': 'lumia' }})`
+
+- If you are attempting to use this inside of Chat Command, Twitch Points, or Twitch Extension we expose a new variable called `{{userLevelsRaw}}`. This variable will contain an object with the different userlevels this user has.
+  The different options are: `isSelf, mod, vip, tier3, tier2, tier1, subscriber, follower`.
+  In your code you should use `const levels = await getVariable('userLevelsRaw');` and then you can check a level with `if (levels.subscriber) {}` since these are all booleans
+
+- To quickly log out information for easier debugging, use `log("")`. You can also use `console.log` which will do the same thing. This will popup a toast message with what you are trying to log as well as add it to the logs in the dashboard
+
+- Everything ran is in a safe JavaScript worker thread away from the Lumia Stream thread so no need to worry about scripts slowing down the app. Make sure you do avoid memory leaks by calling `done()` when you're done with your script
+
+**Share your code** with our community in [**Discord**](https://discord.gg/R8rCaKb) and help **extending Lumia's functionality**
+
+**Checkout the use case examples in the next section**

package/dist/custom-code/what-is-custom-javascript.md

@@ -0,0 +1,40 @@
+---
+sidebar_position: 1
+title: What is custom javascript?
+description: Custom Code allows you to extend Lumia Stream functionality by adding your own scenarios to commands and alerts with code all using JavaScript
+---
+
+Custom Javascript will allow you to extend Lumia Stream's functionality by adding conditions to what you want to happen. You can even make your own scenarios that trigger other commands/alerts with code.
+
+Before we begin while being a coder helps, we will try to give as many examples for you to copy and paste so that you won't need to be a coder to do cool things. Let's begin
+
+There are two areas within Lumia Stream which allow for custom javascript code to be run. Alerts and Commands. Both of them contain an "Advanced" category when editing where custom code can be utilized. The following is an example utilizing Commands.
+
+Open Lumia Stream and head to `Commands` > `Chat` then `edit` or `add a new command` that you want to activate javascript code on.
+
+![Add Command](/img/code/add-command.jpg)
+
+Next on the tabs at the top click on `Custom Javascript`
+
+![Custom Code Tab](/img/code/custom-code-tab.jpg)
+
+You'll see an input where you can put all the code that you copy from the sections below like this
+
+![Code Input](/img/code/code-prompt.jpg)
+
+:::tip
+
+**code blocks** like the one below 👇 have a copy button on the **top right corner** click it then paste in Lumia stream
+
+:::
+
+```js
+async function() {
+
+    // put your code inside here
+
+    // always make sure this is the last line in the code otherwise your computer may get slower due to memory leaks
+    done();
+
+}
+```

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

@@ -117,9 +117,6 @@ type TwitchBits = BaseAlert<
 		/** Optional message accompanying the cheer. */
 		message: string | null;
 		/** Raw message string from the platform. */
-		rawMessage: string;
-		/** Full message (Lumia-computed, if present). */
-		full_message: string;
 		/** Channel views at time of alert. */
 		channelViews: number;
 		/** Channel description text. */
@@ -207,9 +204,6 @@ type TwitchPowerup = BaseAlert<
 		/** Vendor amount (mirrors value). */
 		amount: number;
 		/** Raw chat message, if present. */
-		rawMessage: string | null;
-		/** Full message (Lumia-computed), if present. */
-		full_message: string | null;
 		/** Channel views at time of alert. */
 		channelViews: number;
 		/** Channel description text. */
@@ -251,8 +245,6 @@ type TwitchExtension = BaseAlert<
 		platform: 'twitch';
 		/** Channel views at time of alert (string|number to match vendor inconsistencies). */
 		channelViews: string | number;
-		/** Full message (Lumia-computed), if present. */
-		full_message: string;
 		/** Channel description text. */
 		channelDescription: string;
 	}
@@ -319,7 +311,6 @@ type KickPoints = BaseAlert<
 		/** Platform discriminator. */
 		platform: 'kick';
 		/** Raw message (not parsed). */
-		rawMessage: string | null;
 		/** Amount type echo. */
 		amount_type: 'points';
 		/** Currency symbol (if set). */

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

@@ -1,11 +1,6 @@
 # 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.
+This GPT helps users build and debug Lumia custom overlays (HTML/CSS/JS + Configs + Data) and plugin+overlay integrations.
 
 ---
 
@@ -25,25 +20,7 @@ It prioritizes accuracy, clarity, and practical solutions tailored to Lumia Stre
 - 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);
-});
-```
+- Use `Overlay.on` listeners for `chat`, `alert`, `hfx`, `virtuallight`, and `overlaycontent`.
 
 3. Ask for clarification when needed
 - If requirements are ambiguous, ask targeted follow-up questions.

package/dist/variables.types.js

@@ -666,14 +666,12 @@ exports.ReservedVariables = [
     'variables',
     'username',
     'displayname',
-    'full_message',
     'userId',
     'value',
     'site',
     'command',
     'merch',
     'message',
-    'rawMessage',
     'messageWithoutEmotes',
     'rawMessageWithoutEmotes',
     'userColor',
@@ -868,7 +866,6 @@ exports.AllVariables = {
                 'command',
                 'message',
                 'messageId',
-                'rawMessage',
                 'messageWithoutEmotes',
                 'rawMessageWithoutEmotes',
                 'userColor',
@@ -893,7 +890,6 @@ exports.AllVariables = {
                 'command',
                 'message',
                 'messageId',
-                'rawMessage',
                 'messageWithoutEmotes',
                 'rawMessageWithoutEmotes',
                 'userColor',
@@ -914,7 +910,6 @@ exports.AllVariables = {
                 'command',
                 'prompt',
                 'message',
-                'rawMessage',
                 'messageWithoutEmotes',
                 'rawMessageWithoutEmotes',
                 'points',
@@ -931,7 +926,6 @@ exports.AllVariables = {
                 'command',
                 'prompt',
                 'message',
-                'rawMessage',
                 'messageWithoutEmotes',
                 'rawMessageWithoutEmotes',
                 'points',
@@ -970,7 +964,6 @@ exports.AllVariables = {
                 'command',
                 'message',
                 'messageId',
-                'rawMessage',
                 'messageWithoutEmotes',
                 'rawMessageWithoutEmotes',
                 'userColor',
@@ -1016,7 +1009,6 @@ exports.AllVariables = {
                 'command',
                 'message',
                 'messageId',
-                'rawMessage',
                 'userColor',
                 'platform',
                 'badgesRaw',
@@ -1038,7 +1030,6 @@ exports.AllVariables = {
                 'command',
                 'message',
                 'messageId',
-                'rawMessage',
                 'userColor',
                 'platform',
                 'badgesRaw',
@@ -1060,7 +1051,6 @@ exports.AllVariables = {
                 'command',
                 'message',
                 'messageId',
-                'rawMessage',
                 'userColor',
                 'platform',
                 'badgesRaw',
@@ -1082,7 +1072,6 @@ exports.AllVariables = {
                 'command',
                 'message',
                 'messageId',
-                'rawMessage',
                 'userColor',
                 'platform',
                 'badgesRaw',
@@ -1108,7 +1097,6 @@ exports.AllVariables = {
                 'command',
                 'message',
                 'messageId',
-                'rawMessage',
                 'userColor',
                 'platform',
                 'badgesRaw',
@@ -1132,7 +1120,6 @@ exports.AllVariables = {
                 'command',
                 'message',
                 'messageId',
-                'rawMessage',
                 'userColor',
                 'platform',
                 'badgesRaw',
@@ -1159,7 +1146,6 @@ exports.AllVariables = {
                 'command',
                 'message',
                 'messageId',
-                'rawMessage',
                 'userColor',
                 'platform',
                 'badgesRaw',
@@ -1183,7 +1169,6 @@ exports.AllVariables = {
                 'command',
                 'message',
                 'messageId',
-                'rawMessage',
                 'userColor',
                 'platform',
                 'badgesRaw',
@@ -1214,7 +1199,6 @@ exports.AllVariables = {
                 'command',
                 'message',
                 'messageId',
-                'rawMessage',
                 'userColor',
                 'platform',
                 'badgesRaw',
@@ -1241,7 +1225,6 @@ exports.AllVariables = {
                 'command',
                 'message',
                 'messageId',
-                'rawMessage',
                 'userColor',
                 'platform',
                 'badgesRaw',
@@ -1662,8 +1645,8 @@ exports.AllVariables = {
             sessionSubs: ['total', 'previousTotal'],
             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'],
+            bits: ['username', 'avatar', 'amount', 'message'],
+            bitsCombo: ['username', 'avatar', 'amount', 'bitsType', 'message'],
             sessionBits: ['total', 'previousTotal'],
             raid: ['username', 'avatar', 'viewers'],
             raidOut: ['username', 'avatar', 'viewers'],
@@ -1765,8 +1748,8 @@ exports.AllVariables = {
             shoutoutReceive: ['username', 'userId', 'displayname', 'avatar', 'viewer_count', 'started_at'],
             adStarted: ['length', 'is_automatic', 'started_at', 'twitch_next_ad'],
             adStopped: ['length', 'is_automatic', 'started_at', 'twitch_next_ad'],
-            powerups: ['username', 'avatar', 'type', 'amount', 'message', 'rawMessage', 'full_message'],
-            powerupsPoints: ['username', 'avatar', 'type', 'amount', 'message', 'rawMessage', 'full_message'],
+            powerups: ['username', 'avatar', 'type', 'amount', 'message'],
+            powerupsPoints: ['username', 'avatar', 'type', 'amount', 'message'],
         },
     },
     twitter: {

package/package.json

@@ -1,18 +1,19 @@
 {
   "name": "@lumiastream/lumia-types",
-  "version": "2.8.2",
+  "version": "2.8.3",
   "description": "",
   "main": "./dist/index.js",
   "files": [
     "/dist"
   ],
   "scripts": {
-    "build": "npm run clean && tsc && npm run sync:custom-overlays",
+    "build": "npm run clean && tsc && npm run sync:custom-overlays && npm run sync:custom-code",
     "prepublishOnly": "npm run build",
     "lint": "tslint --project tsconfig.json \"src/**/*.ts\"",
     "lint:fix": "tslint --project tsconfig.json --fix \"src/**/*.ts\"",
     "clean": "rm -rf dist",
     "sync:custom-overlays": "node ./scripts/sync-custom-overlay-types.mjs",
+    "sync:custom-code": "node ./scripts/sync-custom-code-docs.mjs",
     "postpublish": "npm cache clean --force && node ./scripts/postpublish-install.mjs"
   },
   "keywords": [],