@lumiastream/lumia-types 3.2.8 → 3.2.9

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

@@ -18,6 +18,7 @@ Runtime reminders:
 - Read Config/Data values from `Overlay.data`, not from a bare top-level `data` variable.
 - JS is already wrapped by Lumia in an async function, so top-level `await` is allowed.
 - Use literal listener names like `Overlay.on('chat', ...)` so Lumia can auto-subscribe to events.
+- For full event payload shapes, use the Overlay Type Definitions page or `custom-overlays.d.ts`.
 - Use `Overlay.deleteStorage`, not `Overlay.removeStorage`.
 
 ### `window.Overlay` interface

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

@@ -106,6 +106,57 @@ Overlay.on("chat", (data) => {
 	toast(`New chat message received from ${username}. They said ${message}`);
 });
 
+// Full chat payload shape.
+Overlay.on("chat", (data) => {
+	const {
+		origin, // Platform origin, such as "twitch", "youtube", "kick", "tiktok", or "facebook"
+		id, // Platform message id when available
+		username, // Account username/login
+		displayname, // Display name when available
+		channel, // Channel or room where the message was sent
+		avatar, // User avatar URL when available
+		message, // Chat message text
+		color, // User chat color, usually a hex value
+		badges, // Badge ids or badge image URLs
+		badgesLookup, // Badge id to image URL lookup map for some platforms
+		badgesRaw, // Raw platform badge string
+		emotesRaw, // Raw platform emote string
+		emotesPack, // Platform-specific emote metadata
+		isCheer, // Whether the message includes a cheer/bits event
+		reply, // Reply metadata: { username, body }
+		isPowerup, // Twitch Power-up flag
+		powerupType, // Twitch Power-up type
+		powerupName, // Twitch Power-up animation name
+		sharedMessage, // Twitch shared chat source metadata
+		lumiauserlevels, // Numeric Lumia user level ids
+		userLevels, // Boolean role map: isSelf, broadcaster, mod, vip, tier3, tier2, subscriber, regular, follower, anyone
+		time, // Local HH:mm:ss time generated by Lumia
+		timestamp, // Millisecond timestamp generated by Lumia
+	} = data;
+
+	console.log(origin, displayname || username, message, {
+		id,
+		channel,
+		avatar,
+		color,
+		badges,
+		badgesLookup,
+		badgesRaw,
+		emotesRaw,
+		emotesPack,
+		isCheer,
+		reply,
+		isPowerup,
+		powerupType,
+		powerupName,
+		sharedMessage,
+		lumiauserlevels,
+		userLevels,
+		time,
+		timestamp,
+	});
+});
+
 Overlay.on("alert", (data) => {
 	console.log("alert", data);
 	const settings = data.extraSettings || {};
@@ -199,6 +250,8 @@ Overlay.on('overlaycontent', (data) => {
 
 Lumia auto-detects event subscriptions from literal `Overlay.on("event", ...)` calls in the JS tab. Use direct string literals so the overlay subscribes to the needed events. The Data tab only needs an `events` array for legacy/manual cases.
 
+For full event payload shapes, see the [Overlay Type Definitions](/docs/custom-overlays/types). The raw declarations live in `custom-overlays.d.ts` as `ChatEvent`, `AlertEvent`, `HfxEvent`, `VirtualLightEvent`, and `CustomOverlayContentEvent`.
+
 ### OverlayListener types
 
 | Value          | Label                  |
@@ -210,7 +263,7 @@ Lumia auto-detects event subscriptions from literal `Overlay.on("event", ...)` c
 | overlaycontent | Custom Overlay Content |
 
 > 💡 Performance Tip: Only selected events are delivered to the overlay.
-> 💡 The TypeScript types for each alert are within the Types tab.
+> 💡 The TypeScript types for chat, alerts, HFX, virtual lights, and overlay content are within the Types tab.
 > 💡 `overlaycontent` sends custom content only to custom overlay layers with the matching `codeId`.
 
 ### Showing Toasts

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

@@ -1,6 +1,6 @@
 # Custom Overlays Examples
 
-> Need to inspect what an alert returns? Open the [alert explorer](/docs/variables#alert-explorer) on the Platform Variables page to browse `data.alert`, `data.extraSettings.*`, and the fields available for each alert.
+> Need to inspect what an alert returns? Open the [alert explorer](/docs/variables#alert-explorer) on the Platform Variables page to browse `data.alert`, `data.extraSettings.*`, and the fields available for each alert. For full `Overlay.on(...)` payload types, see [Overlay Type Definitions](/docs/custom-overlays/types).
 
 ## Index
 

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

@@ -48,6 +48,26 @@ export enum ConfigsFieldType {
  */
 export type OverlayListener = 'chat' | 'alert' | 'hfx' | 'virtuallight' | 'overlaycontent';
 
+export type ChatUserLevelKey = 'isSelf' | 'broadcaster' | 'mod' | 'vip' | 'tier3' | 'tier2' | 'subscriber' | 'regular' | 'follower' | 'anyone';
+
+export type ChatUserLevels = Record<ChatUserLevelKey, boolean>;
+
+export interface ChatReply {
+	/** Username of the message being replied to */
+	username: string;
+	/** Body of the message being replied to */
+	body: string;
+}
+
+export interface ChatSharedMessage {
+	/** Avatar for the source user/channel of the shared message */
+	avatar: string;
+	/** Display name for the source user/channel of the shared message */
+	displayname: string;
+	/** User ID for the source user/channel of the shared message */
+	userId: string;
+}
+
 /**
  * Chat message event data structure.
  * Fired when a chat message is received from any connected platform.
@@ -55,53 +75,50 @@ export type OverlayListener = 'chat' | 'alert' | 'hfx' | 'virtuallight' | 'overl
 export interface ChatEvent {
 	/** Platform origin (e.g., "twitch", "kick", "youtube", "tiktok") */
 	origin: string;
-	/** Unique message identifier */
-	id: string;
-	/** User's account username */
-	username: string;
+	/** Unique message identifier when the platform provides one */
+	id?: string;
+	/** User's account username/login */
+	username?: string;
 	/** User's display name (may differ from username) */
-	displayname: string;
+	displayname?: string;
 	/** Channel name where the message was sent */
-	channel: string;
+	channel?: string;
 	/** URL to the user's avatar image */
-	avatar: string;
+	avatar?: string | null;
 	/** The chat message content */
-	message: string;
+	message?: string;
 	/** User's chat color as hex code (e.g., "#00FF7F") */
-	color: string;
-	/** Array of badge image URLs */
-	badges: string[];
-	/** Raw badge data string (e.g., "broadcaster/1,sub/12,vip/1") */
-	badgesRaw: string;
-	/** Raw emotes data string */
-	emotesRaw: string;
-	/** Emote pack data structure */
-	emotesPack: Record<string, unknown>;
+	color?: string;
+	/** Badge identifiers or badge image URLs */
+	badges?: string[];
+	/** Lookup map used by some platforms to resolve badge identifiers to image URLs */
+	badgesLookup?: Record<string, string>;
+	/** Raw badge data string (e.g., "broadcaster/1,subscriber/12,vip/1") */
+	badgesRaw?: string;
+	/** Raw emotes data string from the platform */
+	emotesRaw?: string;
+	/** Emote pack data structure; shape varies by platform */
+	emotesPack?: Record<string, unknown>;
+	/** Whether the message contains a cheer/bits event */
+	isCheer?: boolean;
 	/** Reply data if this message is a reply to another */
-	reply: unknown | null;
+	reply?: ChatReply | null;
+	/** Whether this is a Twitch Power-up message */
+	isPowerup?: boolean;
+	/** Twitch Power-up message type */
+	powerupType?: 'animated-message' | 'gigantified-emote-message' | string | false;
+	/** Twitch Power-up animation name */
+	powerupName?: 'simmer' | 'rainbow-eclipse' | 'cosmic-abyss' | string | false;
+	/** Shared chat source metadata when Twitch shared chat provides it */
+	sharedMessage?: ChatSharedMessage;
 	/** Lumia-specific user level identifiers */
-	lumiauserlevels: number[];
+	lumiauserlevels?: number[];
 	/** User permission levels and roles */
-	userLevels: {
-		/** Whether this is the streamer's own message */
-		isSelf: boolean;
-		/** Whether the user is a moderator */
-		mod: boolean;
-		/** Whether the user is a VIP */
-		vip: boolean;
-		/** Whether the user is a tier 3 subscriber */
-		tier3: boolean;
-		/** Whether the user is a tier 2 subscriber */
-		tier2: boolean;
-		/** Whether the user is a subscriber (any tier) */
-		subscriber: boolean;
-		/** Whether the user is a regular viewer */
-		regular: boolean;
-		/** Whether the user is a follower */
-		follower: boolean;
-		/** Always true - indicates any user level */
-		anyone: boolean;
-	};
+	userLevels?: ChatUserLevels;
+	/** Local HH:mm:ss time string generated by Lumia */
+	time?: string;
+	/** Millisecond timestamp generated by Lumia */
+	timestamp?: number;
 }
 
 /**

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

@@ -52,6 +52,8 @@ In JS, wrap tokens in quotes: `const n = Number("{{twitch_session_bits_count}}")
 
 Valid listener names: `chat`, `alert`, `hfx`, `virtuallight`, `overlaycontent`.
 
+Full event payload shapes are in `custom-overlays.d.ts` and the Overlay Type Definitions page. Use `ChatEvent`, `AlertEvent`, `HfxEvent`, `VirtualLightEvent`, and `CustomOverlayContentEvent` there before guessing fields.
+
 Alert rules:
 
 - Branch on exact `data.alert` string equality. No `includes`, no `type`, no `platform` heuristics.

package/dist/custom-overlays.d.ts

@@ -48,6 +48,26 @@ export enum ConfigsFieldType {
  */
 export type OverlayListener = 'chat' | 'alert' | 'hfx' | 'virtuallight' | 'overlaycontent';
 
+export type ChatUserLevelKey = 'isSelf' | 'broadcaster' | 'mod' | 'vip' | 'tier3' | 'tier2' | 'subscriber' | 'regular' | 'follower' | 'anyone';
+
+export type ChatUserLevels = Record<ChatUserLevelKey, boolean>;
+
+export interface ChatReply {
+	/** Username of the message being replied to */
+	username: string;
+	/** Body of the message being replied to */
+	body: string;
+}
+
+export interface ChatSharedMessage {
+	/** Avatar for the source user/channel of the shared message */
+	avatar: string;
+	/** Display name for the source user/channel of the shared message */
+	displayname: string;
+	/** User ID for the source user/channel of the shared message */
+	userId: string;
+}
+
 /**
  * Chat message event data structure.
  * Fired when a chat message is received from any connected platform.
@@ -55,53 +75,50 @@ export type OverlayListener = 'chat' | 'alert' | 'hfx' | 'virtuallight' | 'overl
 export interface ChatEvent {
 	/** Platform origin (e.g., "twitch", "kick", "youtube", "tiktok") */
 	origin: string;
-	/** Unique message identifier */
-	id: string;
-	/** User's account username */
-	username: string;
+	/** Unique message identifier when the platform provides one */
+	id?: string;
+	/** User's account username/login */
+	username?: string;
 	/** User's display name (may differ from username) */
-	displayname: string;
+	displayname?: string;
 	/** Channel name where the message was sent */
-	channel: string;
+	channel?: string;
 	/** URL to the user's avatar image */
-	avatar: string;
+	avatar?: string | null;
 	/** The chat message content */
-	message: string;
+	message?: string;
 	/** User's chat color as hex code (e.g., "#00FF7F") */
-	color: string;
-	/** Array of badge image URLs */
-	badges: string[];
-	/** Raw badge data string (e.g., "broadcaster/1,sub/12,vip/1") */
-	badgesRaw: string;
-	/** Raw emotes data string */
-	emotesRaw: string;
-	/** Emote pack data structure */
-	emotesPack: Record<string, unknown>;
+	color?: string;
+	/** Badge identifiers or badge image URLs */
+	badges?: string[];
+	/** Lookup map used by some platforms to resolve badge identifiers to image URLs */
+	badgesLookup?: Record<string, string>;
+	/** Raw badge data string (e.g., "broadcaster/1,subscriber/12,vip/1") */
+	badgesRaw?: string;
+	/** Raw emotes data string from the platform */
+	emotesRaw?: string;
+	/** Emote pack data structure; shape varies by platform */
+	emotesPack?: Record<string, unknown>;
+	/** Whether the message contains a cheer/bits event */
+	isCheer?: boolean;
 	/** Reply data if this message is a reply to another */
-	reply: unknown | null;
+	reply?: ChatReply | null;
+	/** Whether this is a Twitch Power-up message */
+	isPowerup?: boolean;
+	/** Twitch Power-up message type */
+	powerupType?: 'animated-message' | 'gigantified-emote-message' | string | false;
+	/** Twitch Power-up animation name */
+	powerupName?: 'simmer' | 'rainbow-eclipse' | 'cosmic-abyss' | string | false;
+	/** Shared chat source metadata when Twitch shared chat provides it */
+	sharedMessage?: ChatSharedMessage;
 	/** Lumia-specific user level identifiers */
-	lumiauserlevels: number[];
+	lumiauserlevels?: number[];
 	/** User permission levels and roles */
-	userLevels: {
-		/** Whether this is the streamer's own message */
-		isSelf: boolean;
-		/** Whether the user is a moderator */
-		mod: boolean;
-		/** Whether the user is a VIP */
-		vip: boolean;
-		/** Whether the user is a tier 3 subscriber */
-		tier3: boolean;
-		/** Whether the user is a tier 2 subscriber */
-		tier2: boolean;
-		/** Whether the user is a subscriber (any tier) */
-		subscriber: boolean;
-		/** Whether the user is a regular viewer */
-		regular: boolean;
-		/** Whether the user is a follower */
-		follower: boolean;
-		/** Always true - indicates any user level */
-		anyone: boolean;
-	};
+	userLevels?: ChatUserLevels;
+	/** Local HH:mm:ss time string generated by Lumia */
+	time?: string;
+	/** Millisecond timestamp generated by Lumia */
+	timestamp?: number;
 }
 
 /**

package/package.json

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