@lumiastream/lumia-types 2.8.1 → 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.