@crowbartools/firebot-types 5.67.0-alpha2 → 5.67.0-alpha20

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@crowbartools/firebot-types",
-  "version": "5.67.0-alpha2",
-  "description": "Type definitions and script API for Firebot custom scripts and plugins.",
+  "version": "5.67.0-alpha20",
+  "description": "Type definitions and plugin API for Firebot plugins.",
   "main": "index.js",
   "types": "index.d.ts",
   "exports": {
@@ -20,6 +20,9 @@
     "index.js",
     "index.d.ts",
     "types/**/*.d.ts",
+    "backend/**/*.d.ts",
+    "server/**/*.d.ts",
+    "shared/**/*.d.ts",
     "README.md",
     "LICENSE"
   ],
@@ -39,6 +42,10 @@
   "author": "The Streaming Community",
   "license": "GPL-3.0",
   "peerDependencies": {
-    "@types/node": "*"
+    "@types/express": "^5.0.5",
+    "@types/node": "^24.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
   }
 }

package/server/http-server-manager.d.ts

@@ -0,0 +1,70 @@
+import { EventEmitter } from "events";
+import { Express, Request, Response, Router } from "express";
+import http from "http";
+import type { HttpMethod, CustomHttpRoute, PluginHttpRouteDefinition, CustomWebSocketHandler, Awaitable } from "../types";
+interface ServerInstance {
+    name: string;
+    port: number;
+    server: http.Server;
+}
+interface RegisteredPlugin {
+    name: string;
+    routes: Array<CustomHttpRoute>;
+}
+interface CustomRoute {
+    prefix: string;
+    route: string;
+    fullRoute: string;
+    method: HttpMethod;
+    callback: (req: Request, res: Response) => Awaitable<void>;
+}
+declare class HttpServerManager extends EventEmitter {
+    private logger;
+    serverInstances: ServerInstance[];
+    defaultServerInstance: Express;
+    defaultHttpServer: http.Server;
+    overlayServer: http.Server;
+    isDefaultServerStarted: boolean;
+    overlayHasClients: boolean;
+    registeredPlugins: Record<string, RegisteredPlugin>;
+    pluginRootRouter: Router;
+    pluginRouters: Record<string, Router>;
+    customRoutes: CustomRoute[];
+    customRouteRouter: Router;
+    constructor();
+    start(): void;
+    createDefaultServerInstance(): Express;
+    startDefaultHttpServer(): void;
+    sendToOverlay(eventName: string, meta?: Record<string, unknown>, overlayInstance?: string): void;
+    refreshAllOverlays(): void;
+    /**
+     * Refresh a specific overlay instance
+     * @param overlayInstance the instance to refresh, leave undefined to refresh default
+     */
+    refreshOverlayInstance(overlayInstance?: string): void;
+    sendToControlDecks(eventName: string, data?: unknown): void;
+    triggerCustomWebSocketEvent(eventType: string, payload: object): void;
+    createServerInstance(): Express;
+    startHttpServer(name: string, port: number, instance: Express): http.Server;
+    stopHttpServer(name: any): boolean;
+    private getFullPluginRoute;
+    registerPlugin(plugin: {
+        name: string;
+        definition: PluginHttpRouteDefinition;
+    }): boolean;
+    unregisterPlugin(prefix: string): boolean;
+    registerCustomRoute(prefix: string, route: string, method: string, callback: CustomRoute["callback"]): boolean;
+    unregisterCustomRoute(prefix: string, route: string, method: string): boolean;
+    buildCustomRouteParameters(prefix: string, route: string, method: string): {
+        normalizedPrefix: string;
+        normalizedRoute: string;
+        normalizedMethod: HttpMethod;
+        fullRoute: string;
+    };
+    private getCustomRoutePathFromRoot;
+    private removeCustomRoute;
+    registerCustomWebSocketListener(pluginName: string, handler: CustomWebSocketHandler["handler"]): boolean;
+    unregisterCustomWebSocketListener(pluginName: string): boolean;
+}
+declare const manager: HttpServerManager;
+export { manager as HttpServerManager };

package/server/websocket-client.d.ts

@@ -0,0 +1,5 @@
+import WebSocket from "ws";
+export declare class WebSocketClient extends WebSocket {
+    registrationTimeout: ReturnType<typeof setTimeout>;
+    type?: "overlay" | "events" | "control-deck";
+}

package/server/websocket-events-handler.d.ts

@@ -0,0 +1 @@
+export declare function createComponentEventListeners(): void;

package/server/websocket-server-manager.d.ts

@@ -0,0 +1,22 @@
+import { EventEmitter } from "events";
+import http from "http";
+import type { CustomWebSocketHandler, WidgetOverlayEvent } from "../types";
+declare class WebSocketServerManager extends EventEmitter {
+    private logger;
+    overlayHasClients: boolean;
+    private server;
+    private customHandlers;
+    constructor();
+    createServer(httpServer: http.Server): void;
+    sendToOverlay(eventName: string, meta?: Record<string, unknown>, overlayInstance?: string): void;
+    sendWidgetEventToOverlay(event: WidgetOverlayEvent): void;
+    refreshAllOverlays(): void;
+    sendToControlDecks(eventName: string, data?: unknown): void;
+    triggerEvent(eventType: string, payload: unknown): void;
+    reportClientsToFrontend(isDefaultServerStarted: boolean): void;
+    getNumberOfOverlayClients(): number;
+    registerCustomWebSocketListener(pluginName: string, handler: CustomWebSocketHandler["handler"]): boolean;
+    unregisterCustomWebSocketListener(pluginName: string): boolean;
+}
+declare const manager: WebSocketServerManager;
+export { manager as WebSocketServerManager };

package/types/accounts.d.ts

@@ -1,5 +1,4 @@
 import type { AuthDetails } from "./auth";
-
 export type FirebotAccount = {
     username: string;
     displayName?: string;
@@ -10,4 +9,4 @@ export type FirebotAccount = {
     broadcasterType?: string;
     auth?: AuthDetails;
     loggedIn?: boolean;
-};
+};

package/types/auth.d.ts

@@ -1,5 +1,4 @@
 import type ClientOAuth2 from "client-oauth2";
-
 export interface AuthProviderDefinition {
     id: string;
     name: string;
@@ -17,7 +16,6 @@ export interface AuthProviderDefinition {
     redirectUriHost?: string;
     scopes?: string[] | string | undefined;
 }
-
 export interface AuthProvider {
     id: string;
     oauthClient: ClientOAuth2;
@@ -26,26 +24,19 @@ export interface AuthProvider {
     tokenUri: string;
     details: AuthProviderDefinition;
 }
-
 export interface AuthDetails {
     /** The access token */
     access_token: string;
-
     /** The type of access token */
     token_type: string;
-
     /** OAuth scopes of the access token */
     scope: string[];
-
     /** When the token was obtained, in epoch timestamp format */
     obtainment_timestamp?: number;
-
     /** How many seconds before the token expires */
     expires_in?: number;
-
     /** JSON representation of when access token expires */
     expires_at?: Date;
-
     /** The refresh token */
     refresh_token?: string;
-}
+}

package/types/channel-rewards.d.ts

@@ -1,12 +1,10 @@
 import type { EffectList } from "./effects";
 import type { RestrictionData } from "./restrictions";
-
 export interface CustomRewardImageSet {
     url1x: string;
     url2x: string;
     url4x: string;
 }
-
 export interface CustomReward {
     broadcasterId: string;
     broadcasterLogin: string;
@@ -38,7 +36,6 @@ export interface CustomReward {
     redemptionsRedeemedCurrentStream?: number;
     cooldownExpiresAt?: Date;
 }
-
 export type SavedChannelReward = {
     id: string;
     twitchData: CustomReward;
@@ -49,7 +46,6 @@ export type SavedChannelReward = {
     restrictionData?: RestrictionData;
     autoApproveRedemptions?: boolean;
 };
-
 export type RewardRedemptionMetadata = {
     username: string;
     userId: string;
@@ -60,4 +56,4 @@ export type RewardRedemptionMetadata = {
     rewardImage: string;
     rewardName: string;
     rewardCost: number;
-};
+};

package/types/chat.d.ts

@@ -1,36 +1,25 @@
-type FirebotChatMessagePartType =
-    | "text"
-    | "link"
-    | "emote"
-    | "third-party-emote"
-    | "cheermote"
-    | "mention";
-
+type FirebotChatMessagePartType = "text" | "link" | "emote" | "third-party-emote" | "cheermote" | "mention";
 type FirebotChatMessagePartBase = {
     type: FirebotChatMessagePartType;
     id?: string;
     text: string;
 };
-
-type FirebotChatMessageTextPart = FirebotChatMessagePartBase & {
+export type FirebotChatMessageTextPart = FirebotChatMessagePartBase & {
     type: "text";
     flagged?: boolean;
 };
-
-type FirebotChatMessageLinkPart = FirebotChatMessagePartBase & {
+export type FirebotChatMessageLinkPart = FirebotChatMessagePartBase & {
     type: "link";
     url: string;
 };
-
-type FirebotChatMessageEmotePart = FirebotChatMessagePartBase & {
+export type FirebotChatMessageEmotePart = FirebotChatMessagePartBase & {
     type: "emote" | "third-party-emote";
     name: string;
     origin: string;
     url: string;
     animatedUrl?: string;
 };
-
-type FirebotChatMessageCheermotePart = FirebotChatMessagePartBase & {
+export type FirebotChatMessageCheermotePart = FirebotChatMessagePartBase & {
     type: "cheermote";
     name: string;
     url: string;
@@ -38,21 +27,13 @@ type FirebotChatMessageCheermotePart = FirebotChatMessagePartBase & {
     amount: number;
     color: string;
 };
-
-type FirebotChatMessageMentionPart = FirebotChatMessagePartBase & {
+export type FirebotChatMessageMentionPart = FirebotChatMessagePartBase & {
     type: "mention";
     username: string;
     userId: string;
     userDisplayName: string;
 };
-
-export type FirebotChatMessagePart =
-    | FirebotChatMessageTextPart
-    | FirebotChatMessageLinkPart
-    | FirebotChatMessageEmotePart
-    | FirebotChatMessageCheermotePart
-    | FirebotChatMessageMentionPart;
-
+export type FirebotChatMessagePart = FirebotChatMessageTextPart | FirebotChatMessageLinkPart | FirebotChatMessageEmotePart | FirebotChatMessageCheermotePart | FirebotChatMessageMentionPart;
 export type FirebotParsedMessagePart = {
     type: string;
     id?: string;
@@ -67,7 +48,6 @@ export type FirebotParsedMessagePart = {
     amount?: number;
     color?: string;
 };
-
 export type FirebotChatMessage = {
     id: string;
     timestamp?: number;
@@ -135,14 +115,12 @@ export type FirebotChatMessage = {
     };
     isGigantified?: boolean;
 };
-
 export type FirebotEmote = {
     url: string;
     animatedUrl: string;
     origin: string;
     code: string;
 };
-
 export type FirebotCheermoteInstance = {
     name: string;
     amount: number;
@@ -150,10 +128,10 @@ export type FirebotCheermoteInstance = {
     animatedUrl: string;
     color: string;
 };
-
 export type SharedChatParticipant = {
     broadcasterId: string;
     broadcasterName: string;
     broadcasterDisplayName: string;
     profilePictureUrl: string;
-};
+};
+export {};

package/types/commands.d.ts

@@ -3,10 +3,8 @@ import type { EffectList } from "./effects";
 import type { RestrictionData } from "./restrictions";
 import type { ParametersConfig } from "./parameters";
 import type { Awaitable } from "./util-types";
-
 export type CommandType = "system" | "custom";
-
-type Cooldown = {
+export type Cooldown = {
     /**
      * Global cooldown to use a command in seconds.
      */
@@ -16,7 +14,6 @@ type Cooldown = {
      */
     user: number | undefined;
 };
-
 export type SubCommand = {
     arg: string;
     usage: string;
@@ -34,7 +31,6 @@ export type SubCommand = {
     effects?: EffectList;
     hidden?: boolean;
 };
-
 export type CommandDefinition<OptionsModel = any> = {
     id?: string;
     name?: string;
@@ -96,8 +92,7 @@ export type CommandDefinition<OptionsModel = any> = {
     };
     allowTriggerBySharedChat?: boolean | "inherit" | undefined;
 };
-
-type UserCommand = {
+export type UserCommand = {
     trigger: string;
     args: string[];
     triggeredSubcmd?: SubCommand;
@@ -107,32 +102,17 @@ type UserCommand = {
     commandSender: string;
     senderRoles: string[];
 };
-
-type BasicCommandDefinition = Omit<
-    CommandDefinition,
-    | "type"
-    | "createdBy"
-    | "createdAt"
-    | "lastEditBy"
-    | "lastEditAt"
-    | "count"
-    | "simple"
->;
-
 export type SystemCommandDefinition<OptionsModel = any> = CommandDefinition<OptionsModel> & {
     hideCooldowns?: boolean;
 };
-
 export type SystemCommand<OptionsModel = any> = {
     definition: SystemCommandDefinition<OptionsModel>;
-    onTriggerEvent: (
-        event: {
-            command: SystemCommand<OptionsModel>['definition'];
-            userCommand: UserCommand;
-            chatMessage: FirebotChatMessage;
-            commandOptions?: {
-                [x in keyof OptionsModel]: OptionsModel[x]
-            };
-        }
-    ) => Awaitable<boolean | void>;
-};
+    onTriggerEvent: (event: {
+        command: SystemCommand<OptionsModel>['definition'];
+        userCommand: UserCommand;
+        chatMessage: FirebotChatMessage;
+        commandOptions?: {
+            [x in keyof OptionsModel]: OptionsModel[x];
+        };
+    }) => Awaitable<boolean | void>;
+};

package/types/control-deck.d.ts

@@ -0,0 +1,146 @@
+import type { EffectList } from "./effects";
+/**
+ * Reserved page id for the "Pinned" shadow page. Buttons with this pageId are
+ * replicated onto every real page (unless a page button overrides the slot)
+ */
+export declare const CONTROL_DECK_PINNED_PAGE_ID = "pinned";
+export type ControlDeckControlType = "button" | "folder";
+/** An image icon — either a local file path or a URL. */
+export type ControlDeckImageIcon = {
+    type: "image";
+    /** Whether `path` is a local file path or a URL */
+    source: "local" | "url";
+    /** Local file path (source "local") or URL (source "url") */
+    path: string;
+};
+/** A Lucide icon referenced by name. */
+export type ControlDeckGlyphIcon = {
+    type: "glyph";
+    /** The Lucide icon name */
+    name: string;
+    /** Optional CSS color; defaults to the control's text color */
+    color?: string;
+};
+export type ControlDeckNoneIcon = {
+    type: "none";
+};
+/** An emoji icon referenced by its unicode character. */
+export type ControlDeckEmojiIcon = {
+    type: "emoji";
+    /** The emoji character (eg "🔥") */
+    emoji: string;
+};
+export type ControlDeckIcon = ControlDeckImageIcon | ControlDeckGlyphIcon | ControlDeckEmojiIcon | ControlDeckNoneIcon;
+export type ControlDeckInputType = "text" | "number" | "toggle" | "preset";
+type ControlDeckInputBase = {
+    /** Unique name of the input, used to access the value in effects */
+    name: string;
+    description?: string;
+};
+export type ControlDeckTextInput = ControlDeckInputBase & {
+    type: "text";
+};
+export type ControlDeckNumberInput = ControlDeckInputBase & {
+    type: "number";
+};
+export type ControlDeckToggleInput = ControlDeckInputBase & {
+    type: "toggle";
+};
+export type ControlDeckPresetInput = ControlDeckInputBase & {
+    type: "preset";
+    options: string[];
+};
+export type ControlDeckUserInput = ControlDeckInputBase & {
+    type: "user";
+};
+export type ControlDeckControlInput = ControlDeckTextInput | ControlDeckNumberInput | ControlDeckToggleInput | ControlDeckPresetInput | ControlDeckUserInput;
+export type ControlDeckControlPosition = {
+    col: number;
+    row: number;
+};
+export type ControlDeckControlSize = {
+    /** Number of grid columns the control spans (default 1) */
+    width: number;
+    /** Number of grid rows the control spans (default 1) */
+    height: number;
+};
+export type ControlDeckControl = {
+    id: string;
+    name: string;
+    type: ControlDeckControlType;
+    /** The page this control belongs to */
+    pageId: string;
+    /** The parent folder control id, or null when placed at the page root */
+    parentId: string | null;
+    /** The icon shown on the control */
+    icon: ControlDeckIcon;
+    backgroundColor?: string;
+    /** Placement within the deck's grid */
+    position?: ControlDeckControlPosition;
+    /** How many grid cells the control spans (default 1x1) */
+    size?: ControlDeckControlSize;
+    /** Effects to run when the control is pressed. Only used when type is "button" */
+    effectList?: EffectList;
+    /**
+     * Inputs the user is prompted for when the control is pressed on the hosted
+     * page. The provided values are sent with the press and are available to
+     * effects via $controlDeckInput
+     */
+    inputs?: ControlDeckControlInput[];
+    /**
+     * Whether a folder control should automatically return to the parent page after a button within it is pressed. Only used when type is "folder".
+     */
+    autoReturn?: boolean;
+};
+export type ControlDeckGrid = {
+    cols: number;
+    rows: number;
+};
+export type ControlDeckPage = {
+    id: string;
+    name: string;
+};
+export type ControlDeck = {
+    id: string;
+    name: string;
+    grid: ControlDeckGrid;
+    /** Ordered list of pages. A deck always has at least one page. */
+    pages: ControlDeckPage[];
+    controls: ControlDeckControl[];
+};
+export type ControlDeckOrientationMode = "dynamic" | "fixed";
+export type ControlDeckSettings = {
+    enabled: boolean;
+    /** Optional global PIN required to access the hosted page and trigger controls */
+    pin?: string;
+    /**
+     * How the hosted grid responds to device rotation.
+     * - "fixed": grid keeps its designed dimensions regardless of orientation
+     * - "dynamic": grid rotates to best fill the screen for the current orientation
+     */
+    orientationMode?: ControlDeckOrientationMode;
+};
+export type ControlDeckResolvedIcon = {
+    type: "image";
+    url: string;
+} | {
+    type: "glyph";
+    name: string;
+    color?: string;
+} | {
+    type: "emoji";
+    emoji: string;
+};
+/**
+ * A control as projected to the hosted Control Deck page. Server-only fields
+ * (the raw effect list and local icon path) are removed, and the resolved
+ * `icon` the page should render is added.
+ */
+export type ControlDeckControlView = Omit<ControlDeckControl, "icon" | "effectList"> & {
+    icon?: ControlDeckResolvedIcon;
+};
+/** A deck as projected to the hosted Control Deck page. */
+export type ControlDeckView = Omit<ControlDeck, "controls"> & {
+    controls: ControlDeckControlView[];
+};
+export {};

package/types/counters.d.ts

@@ -1,5 +1,4 @@
 import type { EffectList } from "./effects";
-
 export type Counter = {
     id?: string;
     name: string;
@@ -10,4 +9,4 @@ export type Counter = {
     updateEffects?: EffectList;
     minimumEffects?: EffectList;
     maximumEffects?: EffectList;
-};
+};

package/types/currency.d.ts

@@ -6,10 +6,8 @@ export type Currency = {
     transfer: "Allow" | "Disallow";
     interval: number;
     payout: number;
-
     /** Offline payout */
     offline?: number | string;
-
     /** Maps user role IDs to the amount of bonus payout they receive. */
     bonus: Record<string, number>;
-};
+};

package/types/discord.d.ts

@@ -1,4 +1,4 @@
-export type CustomEmbed = {
+export type DiscordCustomEmbed = {
     title?: string;
     url?: string;
     description?: string;
@@ -6,5 +6,4 @@ export type CustomEmbed = {
     authorIconUrl?: string;
     imageUrl?: string;
 };
-
-export type EmbedType = "channel" | "stream" | "custom";
+export type DiscordEmbedType = "channel" | "stream" | "custom";