@lumiastream/lumia-types 3.9.1 → 3.9.3

package/dist/activity.types.js

@@ -685,7 +685,7 @@ exports.LumiaAlertFriendlyValues = {
     [LumiaAlertValues.YOUTUBE_SUBSCRIBER]: 'Youtube Subscriber',
     [LumiaAlertValues.YOUTUBE_SUPERCHAT]: 'Youtube Superchat',
     [LumiaAlertValues.YOUTUBE_SUPERSTICKER]: 'Youtube Supersticker',
-    [LumiaAlertValues.YOUTUBE_GIFTS]: 'Youtube Gifts',
+    [LumiaAlertValues.YOUTUBE_GIFTS]: 'Youtube Gifts (Jewels)',
     [LumiaAlertValues.YOUTUBE_SESSION_GIFTS]: 'Youtube Session Gifts',
     [LumiaAlertValues.YOUTUBE_ENTRANCE]: 'Youtube Entrance',
     [LumiaAlertValues.YOUTUBE_LIKE]: 'Youtube Like',

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

@@ -95,6 +95,242 @@ async function() {
 }
 ```
 
+### Engagement & system `lumia` actions
+
+These `lumia` actions drive Lumia's engagement features (raffles, tournaments, viewer queue, song requests) and system controls. None of them has a dedicated helper, so call them through `actions()`. The action shape is `{ base: "lumia", type: "<type>", value: { ... } }` — the fields in the tables below go **inside the inner `value` object**. Text fields accept template tokens like `{{username}}`.
+
+#### Enable / disable commands, alerts, folders & automations
+
+`on: true` enables, `on: false` disables.
+
+| type | `value` | targets |
+| --- | --- | --- |
+| `setCommand` | `{ value: "<command name>", on: true }` | a chat command |
+| `setChatbotCommand` | `{ value: "<command name>", on: true }` | a chatbot command |
+| `setTwitchPointsCommand` | `{ value: "<command name>", on: true }` | a Twitch channel-points reward command |
+| `setTwitchExtensionCommand` | `{ value: "<command name>", on: true }` | a Twitch extension command |
+| `setKickPointsCommand` | `{ value: "<command name>", on: true }` | a Kick points command |
+| `setChatMatchCommand` | `{ value: "<chat-match id>", on: true }` | a chat-match command (by id) |
+| `setAlert` | `{ value: "<alert key>", on: true }` | an alert (its `pathKey`) |
+| `setAlertVariation` | `{ value: "<alert key>", variation: "<variation id>", on: true }` | one variation of an alert |
+| `setFolder` | `{ value: "<folder id>", on: true }` | a command/alert folder |
+| `setAutomation` | `{ value: "<automation name>", on: true }` | an automation/timer (matched by name) |
+| `setVoicecommands` | `{ on: true }` | the voice-commands input as a whole |
+| `setFuzeAudioSensitivity` | `{ value: 50 }` | Fuze audio sensitivity (number) |
+
+#### Variables, local storage & files
+
+| type | `value` | notes |
+| --- | --- | --- |
+| `appendToVariable` | `{ value: "<variable name>", message: "<item>", unique: true }` | append an item to a list variable; `unique` skips it if already present |
+| `unappendFromVariable` | `{ value: "<variable name>", message: "<item>" }` | remove an item from a list variable |
+| `saveLocal` | `{ value: "<key>", message: "<value>" }` | persist a value (same store as the `{{save_local}}` / `{{load_local}}` chat functions) |
+| `writeToFile` | `{ value: "<file path>", message: "<content>", on: true }` | write text to a file; `on: true` appends instead of overwriting |
+
+> For plain variables prefer the `setVariable` / `getVariable` / `deleteVariable` helpers in `helper-functions.md`.
+
+#### Userlevels & restrictions
+
+| type | `value` | notes |
+| --- | --- | --- |
+| `addToUserlevel` | `{ value: "<userlevel id>", message: "<username>" }` | add a user to a userlevel |
+| `removeFromUserlevel` | `{ value: "<userlevel id>", message: "<username>" }` | remove a user from a userlevel |
+| `addToRestrictionsList` | `{ message: "<username>" }` | restrict a user (no `value`) |
+| `removeFromRestrictionsList` | `{ message: "<username>" }` | unrestrict a user |
+
+#### Raffles
+
+| type | `value` | notes |
+| --- | --- | --- |
+| `raffleStart` | `{ title: "<title>", preset: "<raffle id>", auto_end: true, ends_after: 5 }` | all optional; `preset` seeds from a saved raffle, `ends_after` is in **minutes** (default 30), `auto_end` turns on the timer |
+| `raffleEntry` | `{ value: "<username>" }` | needs a started raffle |
+| `raffleRemoveEntry` | `{ value: "<username>" }` | |
+| `raffleStop` | `{}` | stop accepting entries |
+| `raffleGetWinner` | `{}` | pick a winner (raffle must be stopped first) |
+| `raffleEnd` | `{}` | end the raffle |
+
+#### Tournaments
+
+| type | `value` | notes |
+| --- | --- | --- |
+| `tournamentStart` | `{ preset: "<tournament id>" }` | start from a preset, or a new tournament if omitted |
+| `tournamentEntry` | `{ message: "<username>", value: "<avatar url>", extra: "<team>", platform: "twitch" }` | `message` is the username; needs a running tournament with signups open |
+| `tournamentRemoveEntry` | `{ message: "<username>", platform: "twitch" }` | |
+| `tournamentUpdatePoints` | `{ message: "<username>", points: "+100" }` | `points` uses the modifier syntax (`+ - * / =`); defaults to `=` (set) when no modifier |
+| `tournamentEnd` | `{}` | |
+
+#### Viewer queue
+
+| type | `value` | notes |
+| --- | --- | --- |
+| `viewerQueueEntry` | `{ value: "<username>" }` | needs a started queue |
+| `viewerQueueLeave` | `{ value: "<username>" }` | |
+| `viewerQueuePickPlayer` | `{ value: 1, mode: "single" }` | pick N players; `mode` is `single`, `bulkfirst`, or `bulkrandom` (default `single`, 1 player) |
+| `viewerQueuePlayPause` | `{ on: true }` | `true` plays, `false` pauses |
+| `viewerQueueEndQueue` | `{}` | |
+
+#### Song requests
+
+| type | `value` | notes |
+| --- | --- | --- |
+| `addSongRequest` | `{ value: "<search term or url>", requesterUsername: "{{username}}", skipApproval: true }` | `skipApproval` (or `forceApprove`) bypasses the approval queue |
+| `skipSongRequest` | `{}` | |
+| `clearSongRequestQueue` | `{}` | |
+
+#### Queue, cooldowns & session (no `value` needed)
+
+| type | what it does |
+| --- | --- |
+| `pauseQueue` / `resumeQueue` | pause / resume the action queue |
+| `removeCurrentQueueItem` | drop the item currently running |
+| `runLastQueueItem` | re-run the last completed queue item |
+| `clearQueue` | empty the queue |
+| `clearCooldowns` | clear all command cooldowns |
+| `resetSession` | reset session variables (session counts) |
+| `cleanAll` | clear queue + cooldowns and send lights to default |
+| `backToDefault` | send lights back to their default |
+| `refreshSettings` | hard-refresh Lumia's settings |
+| `replayLastEventListEvent` | replay the most recent event-list event |
+
+Call these with no inner value, e.g. `await actions([{ base: "lumia", type: "clearQueue" }]);`
+
+#### Other command calls & webhooks
+
+| type | `value` | notes |
+| --- | --- | --- |
+| `callRandomCommand` | `{ options: ["cmdA", "cmdB", "cmdC"], addToEndOfQueue: false }` | run one of the listed commands at random |
+| `toggleStreamMode` | `{}` | flip stream mode on/off (use `setStreamMode { on }` to set it explicitly) |
+| `sendToWebhook` | `{ value: "<url>", message: "<json string>" }` | `message` must be valid JSON — it is parsed and POSTed as the request body |
+| `sendToDiscordWebhook` | `{ value: "<discord webhook url>", message: "<text>" }` | posts text to a Discord webhook |
+| `sendToDiscordWithMediaWebhook` | `{ value: "<discord webhook url>", message: "<text>", file: "<local file path>" }` | posts text + an uploaded file |
+| `sendToPrinter` | `{ value: "<IP:port or usb://vendor:product>", type: "image", message: "<image path>" }` | `type` is `image` (default) or `text`; for `text`, `message` is the text to print |
+
+```js
+async function() {
+    // Start a 5-minute raffle, then enter the running viewer
+    await actions([
+        { base: "lumia", type: "raffleStart", value: { title: "Giveaway", auto_end: true, ends_after: 5 } },
+        { base: "lumia", type: "raffleEntry", value: { value: "{{username}}" } },
+    ]);
+
+    // Disable a command and clear the queue
+    await actions([
+        { base: "lumia", type: "setCommand", value: { value: "!hug", on: false } },
+        { base: "lumia", type: "clearQueue" },
+    ]);
+    done();
+}
+```
+
+### Points, loyalty & currency actions
+
+Several `lumia` actions change a point value, and they all share the same **modifier** syntax on the amount you pass in:
+
+| You pass | Result |
+| --- | --- |
+| `+100` | add 100 |
+| `-100` | subtract 100 |
+| `*2` | multiply by 2 |
+| `/2` | divide by 2 |
+| `=300` | set the exact value to 300 |
+
+A bare number with **no** modifier falls back to each action's own default (noted per action below). The same `+ - * / =` modifiers also work on the `updateCounter` and `updateVariable` actions.
+
+#### `setUserLoyaltyPoint` — change a viewer's loyalty balance
+
+| Field | Meaning |
+| --- | --- |
+| `value.value` | the amount (with optional modifier) |
+| `value.message` | the username to target — defaults to the command's own `{{username}}` |
+| `value.platform` | optional; defaults to the event's platform, then `twitch` |
+
+**Default modifier: `+`** — a bare number *adds* points.
+
+```js
+async function() {
+    // Give the viewer who triggered this 100 points
+    await actions([{ base: "lumia", type: "setUserLoyaltyPoint", value: { value: "100", message: "{{username}}" } }]);
+
+    // Take 50 points from a specific user on YouTube
+    await actions([{ base: "lumia", type: "setUserLoyaltyPoint", value: { value: "-50", message: "someviewer", platform: "youtube" } }]);
+
+    // Set an exact balance of 500
+    await actions([{ base: "lumia", type: "setUserLoyaltyPoint", value: { value: "=500", message: "{{username}}" } }]);
+    done();
+}
+```
+
+#### `setLoyaltyPointValue` — change the loyalty-points **cost** of one of your commands
+
+| Field | Meaning |
+| --- | --- |
+| `value.value` | the command name whose cost you are changing |
+| `value.points` | the new cost (with optional modifier) |
+
+**Default modifier: `=`** — a bare number *sets* the cost.
+
+```js
+async function() {
+    await actions([{ base: "lumia", type: "setLoyaltyPointValue", value: { value: "myredeem", points: "250" } }]); // cost becomes 250
+    await actions([{ base: "lumia", type: "setLoyaltyPointValue", value: { value: "myredeem", points: "+50" } }]);  // cost goes up by 50
+    done();
+}
+```
+
+#### `setTwitchPointValue` / `setTwitchExtensionBitsValue` — change a Twitch reward's cost
+
+Both take the same `{ value: "<commandName>", points: "<amount>" }` shape as `setLoyaltyPointValue` and also **default to `=`**. `setTwitchPointValue` updates a channel-points reward's cost; `setTwitchExtensionBitsValue` updates a Twitch-extension command's Bits cost.
+
+```js
+async function() {
+    await actions([{ base: "lumia", type: "setTwitchPointValue", value: { value: "myreward", points: "1000" } }]);
+    await actions([{ base: "lumia", type: "setTwitchExtensionBitsValue", value: { value: "myextcommand", points: "100" } }]);
+    done();
+}
+```
+
+### Overlay actions without a helper
+
+These `base: "overlay"` actions don't have a dedicated helper yet. Their inner `value` targets a layer with `layer` (add `overlay: "<overlay name>"` to disambiguate which overlay the layer belongs to). `content` fields accept template tokens.
+
+#### Spin wheel
+
+| type | `value` | notes |
+| --- | --- | --- |
+| `spinwheelAddItem` | `{ layer: "<layer>", content: "<item title>", image: "<image url>" }` | adds an item (max 60); `image` is optional |
+| `spinwheelRemoveItem` | `{ layer: "<layer>", content: "<item title>" }` | removes a matching item |
+| `spinwheelReset` | `{ layer: "<layer>", removeItems: true }` | `removeItems: true` wipes all items; otherwise it just resets the wheel |
+
+#### Polls / trigger games
+
+| type | `value` | notes |
+| --- | --- | --- |
+| `pollStart` | `{ layer: "<layer>" }` | start the poll |
+| `pollTrigger` | `{ layer: "<layer>" }` | trigger using the caller's username/message |
+| `pollAddItem` | `{ layer: "<layer>", content: "<option title>", trigger: "<keyword>" }` | `trigger` defaults to the next option number |
+| `pollRemoveItem` | `{ layer: "<layer>", content: "<option title>" }` | |
+| `pollResetVotes` | `{ layer: "<layer>" }` | |
+| `pollSetTimer` | `{ layer: "<layer>", content: "30" }` | `content` is the timer duration in seconds |
+
+#### Game overlays, content & screenshots
+
+| type | `value` | notes |
+| --- | --- | --- |
+| `sendGameTrigger` | `{ layer: "<layer>", content: "<value>" }` | targets the player from the caller's context |
+| `sendGameUpdate` | `{ layer: "<layer>", content: "<value>" }` | |
+| `setContent` | `{ layer: "<layer>", content: "<text>" }` | same as the `overlaySetTextContent` helper |
+| `alertEvent` | `{ value: "<alert id>", variation: "<variation>", duration: 5000 }` | fire an overlay alert event; `duration` in ms |
+| `takeScreenshot` | `{ value: "<overlay id>", format: "png", conversion: "original" }` | `format` is `png` or `jpeg`; `conversion` is `original`, `thermal`, `grayscale`, `invert`, or `binary`; resolves to the saved image path |
+
+#### HUD
+
+| type | `value` | notes |
+| --- | --- | --- |
+| `hudToggle` | `{}` | toggle the HUD |
+| `hudOverlayChange` | `{ value: "<overlay>" }` | switch the HUD overlay |
+| `hudVolumeSet` | `{ volume: 50 }` | set HUD volume |
+| `hudOpacitySet` | `{ volume: 80 }` | set HUD opacity — note the value goes in the `volume` field |
+
 ### 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:
@@ -132,4 +368,325 @@ async function() {
 
 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.
 
+### Integration actions
+
+Every connected integration is also a valid `base` (`spotify`, `discord`, `vtubestudio`, `midi`, `osc`, and the rest listed at the top). An integration action only runs if that integration is **connected and enabled** — otherwise it is silently skipped. The exact `type` and `value` vary per integration; the common ones are below. To find anything not listed, set the action up once in the normal action editor and read off its fields.
+
+**Wrapper styles differ per integration** — each subsection states which it uses:
+
+- **`value` object** — `{ base, type, value: { ... } }`: Discord, VTube Studio, Twitch, YouTube, Kick, TikTok, Meld, SwitchBot, Wave Link, Camera Hub, StreamFog.
+- **scalar `value`** — `{ base, type, value: "..." }`: Spotify, VLC, YouTube Music, Voicemod, Streamer.bot.
+- **flat fields** — `{ base, type, ...fields }` with no `value` wrapper: MIDI, OSC, OBS, MQTT, WebSocket, Serial, Art-Net, Broadlink (SLOBS is a special case, noted below).
+
+Every integration also supports a delay step: `{ base: "<integration>", type: "delay", delay: <ms> }`. String fields generally resolve `{{template}}` tokens (Art-Net is the exception).
+
+> **Lights** (Hue, LIFX, Govee, Nanoleaf, WLED, Elgato key lights, etc.) have **no** action `base` — control them with the `sendColor` helper (see `helper-functions.md`), not through `actions()`.
+
+#### Spotify (`base: "spotify"`)
+
+Spotify actions take a single scalar `value` (not an object). Playback control needs an active Spotify device.
+
+| type | `value` | notes |
+| --- | --- | --- |
+| `setPlayState` | `"play"` / `"pause"` / `"toggle"` | |
+| `skipToNext` / `skipToPrevious` | — | no value needed |
+| `setVolume` | `0`–`100` | percent |
+| `seek` | `<milliseconds>` | |
+| `setShuffle` | `"true"` / `"false"` / `"toggle"` | |
+| `setRepeat` | `"track"` / `"context"` / `"off"` | |
+| `searchAndPlay` | `"<query or track url>"` | queues the match then skips to it |
+| `searchAndPlayImmediately` | `"<query or track url>"` | plays it right away |
+| `searchAndAddToQueue` | `"<query or track url>"` | adds to the queue |
+| `searchAndAddToPlaylist` | `"<query or track url>"` + top-level `target: "<playlist id>"` | |
+
+```js
+async function() {
+    await actions([{ base: "spotify", type: "setVolume", value: 40 }]);
+    await actions([{ base: "spotify", type: "searchAndAddToQueue", value: "never gonna give you up" }]);
+    await actions([{ base: "spotify", type: "searchAndAddToPlaylist", value: "yesterday", target: "37i9dQZF1DXcBWIGoYBM5M" }]);
+    done();
+}
+```
+
+#### Discord (`base: "discord"`)
+
+Discord actions take a `value` object and post through your connected Discord.
+
+| type | `value` | notes |
+| --- | --- | --- |
+| `sendMessage` | `{ value: "<message>", target: "<channel id>", file: "<local path>", embeds: "<json string>", on: false }` | the message text is `value.value`; `target` defaults to your primary channel; `on: true` sends it as TTS; `embeds` is a JSON-array string |
+| `addMemberRole` | `{ value: "<username>", target: "<role id>" }` | |
+| `removeMemberRole` | `{ value: "<username>", target: "<role id>" }` | |
+| `kickMember` | `{ value: "<username>" }` | |
+
+```js
+async function() {
+    await actions([{ base: "discord", type: "sendMessage", value: { value: "Stream is live! {{twitch_channel_title}}" } }]);
+    done();
+}
+```
+
+#### VTube Studio (`base: "vtubestudio"`)
+
+VTube Studio actions take a `value` object; the identifier (model / hotkey / expression) goes in the inner `value.value`.
+
+| type | `value` | notes |
+| --- | --- | --- |
+| `loadModel` | `{ value: "<model name or id>" }` | |
+| `hotkeyTrigger` | `{ value: "<hotkey id>" }` | |
+| `expressionTrigger` | `{ value: "<expression name>", on: true }` | `on` activates / deactivates |
+| `moveModel` | `{ positionX: "0", positionY: "0.5", rotation: "0", timeInSeconds: 1, valuesAreRelativeToModel: false }` | position/rotation are numbers or numeric strings |
+| `resizeModel` | `{ size: "-22.5", timeInSeconds: 1, valuesAreRelativeToModel: false }` | `size` ranges -100 (smallest) to 100 (biggest); applied through MoveModelRequest |
+
+```js
+async function() {
+    await actions([{ base: "vtubestudio", type: "hotkeyTrigger", value: { value: "MyHotkey" } }]);
+    done();
+}
+```
+
+#### MIDI (`base: "midi"`) and OSC (`base: "osc"`)
+
+MIDI and OSC read their fields **flat on the action object** — there is no `value` wrapper.
+
+```js
+async function() {
+    // MIDI: send a note (channel 1-16, note name like "C3", velocity 0-127)
+    await actions([{ base: "midi", type: "note-on", port: 0, channel: 1, note: "C3", velocity: 127 }]);
+
+    // OSC: send a typed message. type is "s" (string), "f" (float), or "i" (int).
+    await actions([{ base: "osc", type: "f", name: "/track/1/volume", sendPort: "9000", value: 0.8 }]);
+    done();
+}
+```
+
+#### Twitch (`base: "twitch"`)
+
+Twitch actions take a `value` object. Most string inputs — usernames, message ids, comma-separated option lists — go in `value.message`. Each action needs the matching Twitch permission to be granted on your connection.
+
+Stream & engagement:
+
+| type | `value` | notes |
+| --- | --- | --- |
+| `changeStreamTitle` | `{ message: "<title>" }` | |
+| `changeCurrentCategory` | `{ message: "<game/category>" }` | matched by name |
+| `clip` | `{ title: "<title>", duration: 30 }` | `duration` 5–60s; sets `{{twitch_last_clip_url}}` |
+| `createStreamMarker` | `{ message: "<description>" }` | |
+| `runCommercial` | `{ duration: 60 }` | one of 30/60/90/120/150/180 |
+| `changeUserColor` | `{ color: "blue" }` | named color (Prime/Turbo can use hex) |
+| `shoutout` | `{ message: "<username>" }` | runs your shoutout command |
+| `raid` | `{ message: "<channel>" }` | |
+| `sendAnnouncement` | `{ message: "<text>", color: "primary" }` | color: primary/blue/green/orange/purple |
+| `createPoll` | `{ title: "<title>", message: "opt1,opt2", duration: 60 }` | options comma-separated; `duration` seconds |
+| `endPoll` | `{ reason: "ARCHIVED" }` | `ARCHIVED` or `TERMINATED` |
+| `createPrediction` | `{ title: "<title>", message: "outcome1,outcome2", duration: 60 }` | |
+| `endPrediction` | `{ reason: "RESOLVED", message: "<winning outcome>" }` | `RESOLVED`/`CANCELED`/`LOCKED`; `message` is the winning outcome text |
+| `updateRedemptionStatus` | `{ status: "FULFILLED" }` | `FULFILLED` or `CANCELED`; applies to pending redemptions |
+
+Chat modes (`on: true` enables):
+
+| type | `value` |
+| --- | --- |
+| `setSubscriberMode` / `setEmotesMode` / `setUniqueChatMode` | `{ on: true }` |
+| `setFollowMode` | `{ on: true, duration: 0 }` (`duration` in **minutes**) |
+| `setSlowMode` | `{ on: true, duration: 30 }` (`duration` in **seconds**) |
+| `clearChat` | `{}` |
+
+Moderation:
+
+| type | `value` | notes |
+| --- | --- | --- |
+| `banUser` | `{ message: "<username>", reason: "" }` | |
+| `unbanUser` | `{ message: "<username>" }` | |
+| `timeoutUser` | `{ message: "<username>", duration: 600, reason: "" }` | `duration` in seconds |
+| `deleteMessage` | `{ message: "<message id>" }` | |
+| `pinMessage` | `{ message: "<text>", duration: 0 }` | sends then pins; `duration` 0 = no expiry, else 30–1800s |
+| `unpinMessage` | `{}` | |
+| `addModerator` / `removeModerator` / `addVip` / `removeVip` | `{ message: "<username>" }` | |
+| `warnUser` | `{ message: "<username>", reason: "" }` | |
+| `blockUser` / `unblockUser` | `{ message: "<username>" }` | |
+| `addBlockedWord` / `removeBlockedWord` | `{ message: "<word>" }` | |
+| `shieldModeOn` / `shieldModeOff` | `{}` | |
+| `setSuspiciousUserStatus` | `{ message: "<username>", status: "ACTIVE_MONITORING" }` | `ACTIVE_MONITORING` or `RESTRICTED` |
+| `removeSuspiciousUserStatus` | `{ message: "<username>" }` | |
+
+```js
+async function() {
+    await actions([{ base: "twitch", type: "clip", value: { title: "Clutch!", duration: 30 } }]);
+    await actions([{ base: "twitch", type: "sendAnnouncement", value: { message: "Raid incoming!", color: "purple" } }]);
+    done();
+}
+```
+
+#### YouTube (`base: "youtube"`)
+
+`value` object. Usernames go in `value.message`.
+
+| type | `value` | notes |
+| --- | --- | --- |
+| `changeStreamTitle` | `{ title: "<title>", message: "<description>" }` | note: `message` is the **description** |
+| `banUser` | `{ message: "<username>" }` | permanent |
+| `unbanUser` | `{ message: "<username>" }` | |
+| `timeoutUser` | `{ message: "<username>", duration: 300 }` | `duration` in seconds |
+| `deleteMessage` | `{ message: "<message id>" }` | |
+| `shoutout` | `{ message: "<username>" }` | |
+
+#### Kick (`base: "kick"`)
+
+`value` object. Usernames and the stream title both go in `value.message`. No poll or send-message action (chat goes through the chatbot).
+
+| type | `value` | notes |
+| --- | --- | --- |
+| `changeStreamTitle` | `{ message: "<title>" }` | |
+| `changeCurrentCategory` | `{ message: "<category>" }` | matched by name |
+| `shoutout` | `{ message: "<username>" }` | |
+| `banUser` | `{ message: "<username>", reason: "" }` | |
+| `unbanUser` | `{ message: "<username>" }` | |
+| `timeoutUser` | `{ message: "<username>", duration: 600, reason: "" }` | `duration` in seconds |
+
+#### TikTok (`base: "tiktok"`)
+
+`value` object. TikTok actions are **video upload only** (everything else is inbound events).
+
+| type | `value` | notes |
+| --- | --- | --- |
+| `uploadDraftVideo` | `{ media: "<local file path>" }` | uploads to your TikTok inbox to finish/publish manually |
+| `uploadAndPublishVideo` | `{ media: "<local file path>", title: "<title>", privacy_level: "PUBLIC_TO_EVERYONE", disable_comment: false, disable_duet: false, disable_stitch: false }` | `privacy_level`: `PUBLIC_TO_EVERYONE` / `MUTUAL_FOLLOW_FRIENDS` / `SELF_ONLY` |
+
+#### OBS (`base: "obs"`)
+
+For OBS, prefer the **`sendRawObsJson`** helper documented above — the `actions()` OBS path uses the same OBS-websocket-v5 `request-type` values and fields. Reach for `base: "obs"` only to batch OBS in one ordered `actions([...])` array with other bases, or to use Lumia's convenience source types.
+
+OBS fields are **flat** on the action object (the type key is `request-type`, hyphenated):
+
+```js
+async function() {
+    await actions([
+        { base: "obs", "request-type": "SetCurrentProgramScene", sceneName: "Starting Soon" },
+        { base: "obs", "request-type": "SetInputMute", inputName: "Mic/Aux", inputMuted: true },
+    ]);
+    done();
+}
+```
+
+Convenience source types (Lumia builds the `inputSettings` for you): `SetSourceText` (`{ inputName, text }`), `SetGenericUrlSource` / `SetSourceUrl` (`{ inputName, url }`), `SetGenericFileSource` / `SetImageFileSource` / `SetMediaFileSource` (`{ inputName, file }`). All other request-types match the OBS v5 API exactly.
+
+#### Streamlabs Desktop (`base: "slobs"`)
+
+SLOBS uses JSON-RPC, so an action carries both a `type` (for delay routing) and an RPC `method` + `params`. Only a few types are exposed:
+
+| type | shape | notes |
+| --- | --- | --- |
+| `SetCurrentScene` | `{ base: "slobs", type: "SetCurrentScene", method: "makeSceneActive", params: { resource: "ScenesService", args: ["<sceneId>"] } }` | switch scene |
+| `SetCurrentSceneCollection` | `{ ..., type: "SetCurrentSceneCollection", method: "load", params: { resource: "SceneCollectionsService", args: ["<collectionId>"] } }` | |
+| `SetSourceRender` | `{ ..., type: "SetSourceRender", method: "setVisibility", params: { resource: "<sceneItemId>", args: [true] } }` | scene-item visibility |
+
+#### Meld Studio (`base: "meld"`)
+
+`value` object; scene/layer/track/effect targets accept the friendly name or id.
+
+| type | `value` | notes |
+| --- | --- | --- |
+| `SetScene` | `{ value: "<scene>" }` | show a scene |
+| `SetStagedScene` | `{ value: "<scene>" }` | set the staged (preview) scene |
+| `ShowStagedScene` | `{}` | promote staged to live |
+| `SetLayerVisibility` | `{ value: "<layer>", on: true }` | |
+| `SetLayerEffect` | `{ parent: "<layer>", value: "<effect>", on: true }` | |
+| `SetAudioTrackMute` | `{ value: "<track>", on: true }` | `on: true` = muted |
+| `StartRecord` / `StopRecord` / `StartStream` / `StopStream` | `{}` | |
+| `Clip` / `Screenshot` | `{}` | |
+| `SendCommand` | `{ value: "meld.<command>" }` | raw command, e.g. `meld.toggleStreamingAction` |
+
+#### VLC (`base: "vlc"`)
+
+Scalar `value`.
+
+| type | `value` | notes |
+| --- | --- | --- |
+| `setPlayState` | `"play"` / `"pause"` / `"toggle"` | |
+| `playlistNext` / `playlistPrevious` | — | |
+| `setVolume` | `0`–`125` | percent |
+| `seek` | `"+30"` / `"-30"` / `"50%"` / `"120"` | VLC seek syntax |
+| `setShuffle` / `setRepeat` / `setLoop` | `"true"` / `"false"` / `"toggle"` | |
+| `addToQueueAndPlay` | `"<uri or path>"` | |
+| `addToQueue` | `"<uri or path>"` | |
+| `playlistEmpty` | — | clears the playlist |
+
+#### YouTube Music (`base: "youtubemusic"`)
+
+Scalar `value`; most types take no value.
+
+| type | `value` | notes |
+| --- | --- | --- |
+| `setPlayState` | `"play"` / `"pause"` / `"toggle"` | |
+| `skipToNext` / `skipToPrevious` | — | |
+| `toggleShuffle` / `toggleRepeat` | — | |
+| `thumbsUp` / `thumbsDown` | — | |
+| `setVolumeUp` / `setVolumeDown` | — | |
+| `searchAndPlayImmediately` | `"<url, videoId, or playlistId>"` | YTMDesktop app only |
+
+#### Voicemod (`base: "voicemod"`)
+
+Scalar `value` (voice/sound name) for the lookups; the on/off toggles take no value.
+
+| type | `value` | notes |
+| --- | --- | --- |
+| `voice` | `"<voice name>"` | load a specific voice |
+| `random_voice` / `random_voice_favorite` | — | random voice (favorites only for the latter) |
+| `sound` / `soundboard` | `"<sound name>"` | play a meme sound |
+| `random_sound` / `random_soundboard` | — | random sound |
+| `stop_all_sounds` | — | |
+| `on` / `off` / `on_off` | — | voice changer on / off / toggle |
+| `hear_my_voice_on` / `hear_my_voice_off` / `hear_my_voice_on_off` | — | |
+| `background_on_off` / `mic_on_off` | — | toggle background effects / mute mic |
+
+#### Streamer.bot (`base: "streamerbot"`)
+
+Scalar `value` is the action name; `args` is a flat top-level JSON string.
+
+```js
+async function() {
+    await actions([{ base: "streamerbot", type: "action", value: "My SB Action", args: '{"user":"{{username}}","amount":5}' }]);
+    done();
+}
+```
+
+#### Protocols — MQTT, WebSocket, Serial, Art-Net, Broadlink
+
+These read their fields **flat** on the action object (no `value` wrapper).
+
+```js
+async function() {
+    // MQTT: publish to a topic on a configured broker (host = the broker's host)
+    await actions([{ base: "mqtt", type: "send", host: "192.168.1.50", topic: "home/light", value: "ON" }]);
+
+    // WebSocket: send to one connection by its id
+    await actions([{ base: "websocket", type: "data", device: "<websocketId>", value: "hello" }]);
+
+    // Serial: write raw data to a port (9600 baud)
+    await actions([{ base: "serial", type: "write", port: "COM3", value: "L1\n" }]);
+
+    // Art-Net: set DMX channels on a universe (values 0-255; no template tokens here)
+    await actions([{ base: "artnet", type: "artnet", universe: 0, values: [{ channel: 1, value: 255 }, { channel: 2, value: 128 }] }]);
+
+    // Broadlink: send a learned IR/RF code by its library id or name to a device
+    await actions([{ base: "broadlink", type: "ir", device: "<deviceId>", value: "TV Power" }]);
+    done();
+}
+```
+
+#### Devices — SwitchBot, Wave Link, Camera Hub, StreamFog
+
+All take a `value` object.
+
+| base | type | `value` | notes |
+| --- | --- | --- | --- |
+| `switchbot` | `turnOn` / `turnOff` / `toggle` | `{ deviceId: "<id>" }` | |
+| `wavelink` | `SET_INPUT_VOLUME` | `{ inputId: "<id>", volume: 50, mixerID: "com.elgato.mix.local" }` | volume 0–100; mixer `local`/`stream`/`all` |
+| `wavelink` | `MUTE_INPUT` | `{ inputId: "<id>", muted: true, mixerID: "com.elgato.mix.local" }` | |
+| `wavelink` | `SET_OUTPUT_VOLUME` / `MUTE_OUTPUT` | `{ volume: 50, mixerID: "com.elgato.mix.local" }` | |
+| `wavelink3` | same types as `wavelink` | same shapes | Wave Link 3.0 uses base `wavelink3`; some legacy filter/mic types are unsupported on v3 |
+| `camerahub` | `SET_WEBCAM_PROPERTY` | `{ propertyID: "Brightness", propertyValue: 60 }` | also `SELECT_DEVICE`, `SET_NVIDIA_VIDEO_EFFECT`, `SET_LUT_EFFECT`, `SET_PROMPTER_PROPERTY` |
+| `streamfog` | `activateLens` | `{ lensId: "<id or name>", duration: 10 }` | `lensId: "random"` picks one; also `activateOutfit` (`{ outfit, duration }`) and `disableLens` (`{}`) |
+
 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/helper-functions.md

@@ -93,7 +93,7 @@ async function() {
 
 ### Get Variable
 
-`getVariable(name: string)`: Retrieve a variables value based on it's name
+`getVariable(name: string)`: Retrieve a variables value based on it's name. Returns the raw stored value (string / number / …), or `undefined` if it isn't set. A command's runtime variable takes priority over the saved one of the same name.
 
 ```js
 async function() {
@@ -127,7 +127,7 @@ async function() {
 
 ### Get All Variables
 
-`getAllVariables()`: Ability to get all local and global variables with one easy call
+`getAllVariables()`: Ability to get all local and global variables with one easy call. Returns a flat `{ name: value }` map of every saved variable merged with the command's runtime variables (runtime values win on a name clash).
 
 ```js
 async function() {
@@ -197,6 +197,8 @@ async function() {
 
 `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
 
+Returns an array of `{ id, name, alias, type }`. `type` is the integration key (e.g. `hue`, `govee`, `wled`, `elgato`, `virtuallights`), `alias` is your custom label, and `name` is the device's original name. Pass `{ id, type }` objects to `sendColor`'s `lights` array to target specific lights. Disconnected or disabled integrations are omitted, so an empty array means nothing is connected.
+
 ```js
 async function() {
     const lights = await getLights()
@@ -246,6 +248,8 @@ async function() {
 
 `getApiOptions()`: Contains information like commands, types, connections, and more
 
+Returns `{ types, options }`. `types` is the list of every API command type (e.g. `setColor`, `setBrightness`, `alert`, `tts`, `chatCommand`, `chatbotCommand`, `twitchPoints`, `kickPoints`, studio scene/theme/animation, plus value-less system ops). `options` is keyed by those same types: value-less ops are `null`, while the command/alert/tts/studio types carry a `{ values: [...] }` list of the names you can use.
+
 ```js
 async function() {
     const lights = await getApiOptions()
@@ -254,7 +258,7 @@ async function() {
 
 ### Get Commands
 
-`getCommands({ formatted?: boolean; onlyOn?: boolean; onlyUser?: boolean })`: Returns the list of chat command names. Pass `onlyOn: true` to only include commands that are enabled and shown in the commands list, `onlyUser: true` to only include commands the current user has access to (based on their user levels), and `formatted: true` to get a single comma separated string instead of an array
+`getCommands({ formatted?: boolean; onlyOn?: boolean; onlyUser?: boolean })`: Returns the list of chat and chatbot command names. Pass `onlyOn: true` to only include commands that are enabled and shown in the commands list, `onlyUser: true` to only include commands the current user has access to (based on their user levels), and `formatted: true` to get a single comma separated string instead of an array
 
 ```js
 async function() {
@@ -486,7 +490,7 @@ async function() {
 
 ### 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
+`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. Returns the access-token string, or `null` / `undefined` if that connection isn't authorized.
 
 ```js
 async function() {
@@ -497,7 +501,7 @@ async function() {
 
 ### 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
+`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. Returns the Twitch Client-ID string; only `"twitch"` is supported and any other value returns `null`.
 
 ```js
 async function() {

package/dist/esm/activity.types.js

@@ -682,7 +682,7 @@ export const LumiaAlertFriendlyValues = {
     [LumiaAlertValues.YOUTUBE_SUBSCRIBER]: 'Youtube Subscriber',
     [LumiaAlertValues.YOUTUBE_SUPERCHAT]: 'Youtube Superchat',
     [LumiaAlertValues.YOUTUBE_SUPERSTICKER]: 'Youtube Supersticker',
-    [LumiaAlertValues.YOUTUBE_GIFTS]: 'Youtube Gifts',
+    [LumiaAlertValues.YOUTUBE_GIFTS]: 'Youtube Gifts (Jewels)',
     [LumiaAlertValues.YOUTUBE_SESSION_GIFTS]: 'Youtube Session Gifts',
     [LumiaAlertValues.YOUTUBE_ENTRANCE]: 'Youtube Entrance',
     [LumiaAlertValues.YOUTUBE_LIKE]: 'Youtube Like',