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

package/types/plugins.d.ts

@@ -1,18 +1,20 @@
-import { EffectInstance, EffectList, EffectType } from "./effects";
-import { Trigger } from "./triggers";
-import { Awaitable } from "./util-types";
-import { ReplaceVariable } from "./variables";
-import { EventFilter, EventSource } from "./events";
-import { SystemCommand } from "./commands";
-import { RestrictionType } from "./restrictions";
-import { FirebotParams, FirebotParameterArray } from "./parameters";
-import { FirebotGame } from "./games";
-import { Integration } from "./integrations";
-
+import type { EffectType, PluginAdditionalEffectEvents } from "./effects";
+import type { Trigger } from "./triggers";
+import type { Awaitable } from "./util-types";
+import type { PluginAdditionalVariableEvents, ReplaceVariable } from "./variables";
+import type { EventFilter, EventSource } from "./events";
+import type { SystemCommand } from "./commands";
+import type { RestrictionType } from "./restrictions";
+import type { FirebotParams, FirebotParameterArray } from "./parameters";
+import type { FirebotGame } from "./games";
+import type { Integration } from "./integrations";
+import type { UIExtension } from "./ui-extensions";
+import type { OverlayWidgetType } from "./overlay-widgets";
+import type { PluginHttpRouteDefinition } from "./http-server";
+import type { CustomWebSocketHandler } from "./websocket";
+import type { PluginWebhooks } from "./webhooks";
 type NoResult = Awaitable<void>;
-
 type GenericParameters = Record<string, unknown>;
-
 export type InstalledPluginConfig<Params extends GenericParameters = GenericParameters> = {
     id: string;
     fileName: string;
@@ -20,140 +22,140 @@ export type InstalledPluginConfig<Params extends GenericParameters = GenericPara
     legacyImport?: boolean;
     parameters: Params;
 };
-
-export type ScriptContext<Params extends FirebotParams = FirebotParams> = {
+export type PluginContext<Params extends FirebotParams = FirebotParams> = {
     trigger?: Trigger;
     parameters: Params;
 };
-
-type DynamicArray<T> = Array<T | ((context: ScriptContext) => Awaitable<T>)>;
-
-export type ScriptType = "script" | "plugin";
-
+type DynamicObject<T> = T | ((context: PluginContext) => Awaitable<T>);
+type DynamicArray<T> = Array<T | ((context: PluginContext) => Awaitable<T>)>;
+export type PluginType = "script" | "plugin";
 interface ManifestDescription {
     short: string;
     long?: string;
 }
-
 interface ManifestFirebotVersion {
     major: number;
     minor?: number;
     patch?: number;
 }
-
+type FontAwesomeIcon = {
+    type: "font-awesome";
+    /**
+     * A FontAwesome icon name shown in the UI (eg. "fa-cogs").
+     */
+    name: `fa-${string}`;
+    /**
+     * A css color value (eg. "#FF0000") used for the icon.
+     */
+    color?: string;
+};
+type CustomIcon = {
+    type: "custom";
+    url: string;
+    /**
+     * A css color value (eg. "#FF0000") used for the background of the icon.
+     */
+    backgroundColor?: string;
+};
+export type PluginIcon = FontAwesomeIcon | CustomIcon;
 export interface Manifest {
     name: string;
     version: string;
     author: string;
     description: string | ManifestDescription;
-
-    keywords?: string[];
-
+    /**
+     * An array of strings that describe or categorize your plugin
+     */
+    tags?: string[];
+    /**
+     * A link to the plugin's source code repository
+     */
     repo?: string;
-
-    // Note: autofilled if repo is assumed github and not specified
+    /**
+     * A link to the plugin's website
+     * If the repo is on GitHub and the website is not specified, it will default to the GitHub repo URL.
+     */
     website?: string;
-    report?: string;
-    source?: string;
-
+    /**
+     * A link to the plugin's issue tracker or support server (e.g. Discord).
+     * If the repo is on GitHub and support is not specified, it will default to the GitHub issues URL.
+     */
+    support?: string;
     minimumFirebotVersion?: ManifestFirebotVersion;
     maximumFirebotVersion?: ManifestFirebotVersion;
-
-    icon?: `fa-${string}`;
-    color?: string;
-
-    type: ScriptType;
+    /**
+     * The icon to be displayed for the plugin.
+     */
+    icon?: PluginIcon;
+    /**
+     * If true, the plugin will be initialized before parameters are shown to the user,
+     * allowing the plugin to provide custom parameter types that can be used in its own parametersSchema.
+     */
+    initBeforeShowingParams?: boolean;
 }
-
-type EffectScriptResult = {
-    success: boolean;
-    errorMessage?: string;
-    effects?: EffectList | Array<EffectInstance>;
-    onEffectsDone?: () => Awaitable<void>;
-};
-
-
-export interface ScriptBase<Params extends FirebotParams = FirebotParams> {
+export interface PluginBase<Params extends FirebotParams = FirebotParams> {
     manifest: Manifest;
-
     parametersSchema?: FirebotParameterArray<Params>;
-
-    // if uninstalled is true, the script is being removed by the user, thus the script should remove related data files/assets
-    // otherwise the script should assume firebot is closing or the script is being reloaded
-    onUnload?: (context: ScriptContext<Params>, isUninstalling?: boolean) => NoResult;
-}
-
-// Supplants the "Run Script" effect script functionality
-export interface EffectScript<Params extends FirebotParams = FirebotParams> extends ScriptBase<Params> {
-    run: (context: ScriptContext<Params>) => Awaitable<void | EffectScriptResult>;
 }
-
-// Supplants the "Start up" script functionality
-export interface Plugin<Params extends FirebotParams = FirebotParams> extends ScriptBase<Params> {
-    // Note: At least one is required: onLoad or registers.*
-    // if not met, the script will not be loaded and it should be logged the script does nothing
-
-    // Automatically handles registration with appropriate managers for definitions
-    // when the script is unloaded, definitions will automagically be unregistered
+export interface Plugin<Params extends FirebotParams = FirebotParams> extends PluginBase<Params> {
+    /**
+     * Automatically handles registration with appropriate managers for definitions
+     * when the plugin is unloaded, definitions will automagically be unregistered.
+     *
+     * Array entries can be direct definitions or functions that return definitions
+     * (or promises of definitions) for dynamic registration based on context (e.g. parameter values).
+     */
     registers?: {
-
-        // If value within array is a function, call said function to get definition
-        // If definition is or evaluates to promise, await promise
-        effects?: DynamicArray<EffectType>;
+        effects?: DynamicArray<EffectType<any, any>>;
         eventSources?: DynamicArray<EventSource>;
         variables?: DynamicArray<ReplaceVariable>;
-        // endpoints?: DynamicArray<HttpEndpoint>;
-        integrations?: DynamicArray<Integration>;
+        integrations?: DynamicArray<Integration<any>>;
         filters?: DynamicArray<EventFilter>;
-        restrictions?: DynamicArray<RestrictionType>;
-        systemCommands?: DynamicArray<SystemCommand>;
+        restrictions?: DynamicArray<RestrictionType<any>>;
+        systemCommands?: DynamicArray<SystemCommand<any>>;
         games?: DynamicArray<FirebotGame>;
+        uiExtensions?: DynamicArray<UIExtension>;
+        overlayWidgets?: DynamicArray<OverlayWidgetType<any, any>>;
+        httpRoutes?: DynamicObject<PluginHttpRouteDefinition>;
+        websocketListener?: DynamicObject<CustomWebSocketHandler>;
+        webhooks?: DynamicObject<PluginWebhooks>;
+        additionalEffectEvents?: DynamicArray<PluginAdditionalEffectEvents>;
+        additionalVariableEvents?: DynamicArray<PluginAdditionalVariableEvents>;
     };
-
-    // Called when the script is loaded
-    onLoad?: (context: ScriptContext<Params>, isInstalling?: boolean) => NoResult;
-
-    // Called when firebot is closing or plugin is disabled / removed
-    onUnload?: (context: ScriptContext<Params>, isUninstalling?: boolean) => NoResult;
-
-    // called when the user updates plugin-specific parameters
-    onParameterUpdate?: (context: ScriptContext<Params>) => NoResult;
+    /** Called when the plugin is loaded */
+    onLoad?: (context: PluginContext<Params>, isInstalling?: boolean) => NoResult;
+    /** Called when Firebot is closing or plugin is disabled / removed  */
+    onUnload?: (context: PluginContext<Params>, isUninstalling?: boolean) => NoResult;
+    /** Called when the user updates plugin-specific parameters */
+    onParameterUpdate?: (context: PluginContext<Params>) => NoResult;
 }
-
-export type ScriptDetails = Pick<ScriptBase, "manifest" | "parametersSchema">;
-
+export type PluginDetails = Pick<PluginBase, "manifest" | "parametersSchema">;
 export type InstalledPlugin = {
     config: InstalledPluginConfig;
-    details: ScriptDetails;
+    details: PluginDetails;
 };
-
-/* Legacy types */
-
-type LegacyScriptParameters = Record<
-    string,
-    {
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        type: any;
-        title?: string;
-        description?: string;
-        secondaryDescription?: string;
-        tip?: string;
-        showBottomHr?: boolean;
-        validation?: {
-            required?: boolean;
-        };
-        value?: unknown;
-        default?: unknown;
-    }
->;
-
+type LegacyScriptParameters = Record<string, {
+    type: any;
+    title?: string;
+    description?: string;
+    secondaryDescription?: string;
+    tip?: string;
+    showBottomHr?: boolean;
+    validation?: {
+        required?: boolean;
+    };
+    value?: unknown;
+    default?: unknown;
+}>;
 export type LegacyScriptReturnObject = {
     success: boolean;
     errorMessage?: string;
-    effects: unknown[] | { id: string, list: unknown[] };
+    effects: unknown[] | {
+        id: string;
+        list: unknown[];
+    };
     callback?: VoidFunction;
 };
-
 type LegacyRunRequest = {
     parameters: Record<string, unknown>;
     modules: Record<string, unknown>;
@@ -169,7 +171,6 @@ type LegacyRunRequest = {
     };
     trigger: Trigger;
 };
-
 type LegacyCustomScriptManifest = {
     name: string;
     description: string;
@@ -177,25 +178,21 @@ type LegacyCustomScriptManifest = {
     author: string;
     website?: string;
     startupOnly?: boolean;
+    initBeforeShowingParams?: boolean;
     firebotVersion?: "5";
 };
-
 export type LegacyScriptData = {
     id: string;
     name: string;
     scriptName: string;
     parameters: LegacyScriptParameters;
 };
-
 export type LegacyCustomScript = {
     getScriptManifest(): Awaitable<LegacyCustomScriptManifest>;
     getDefaultParameters?: () => LegacyScriptParameters;
-    run(
-        runRequest: LegacyRunRequest
-    ): Awaitable<void | LegacyScriptReturnObject>;
+    run(runRequest: LegacyRunRequest): Awaitable<void | LegacyScriptReturnObject>;
     parametersUpdated?: (parameters: Record<string, unknown>) => Awaitable<void>;
     stop?: () => Awaitable<void>;
 };
-
-export type FirebotScriptApi = import("./script-api").FirebotScriptApi;
-export type { ScriptLoggerApi, ScriptWebhooksApi, ScriptWebhook, ScriptWebhookEvent } from "./script-api";
+export type FirebotPluginApi = import("./plugin-api").FirebotPluginApi;
+export type { PluginLoggerApi as PluginLoggerApi, PluginWebhooksApi as PluginWebhooksApi } from "./plugin-api";

package/types/power-ups.d.ts

@@ -1,13 +1,11 @@
 import type { CustomPowerUp } from "../backend/streaming-platforms/twitch/api/resource/power-ups";
 import type { EffectList } from "./effects";
-
 export type SavedPowerUp = {
     id: string;
     twitchData: CustomPowerUp;
     effects?: EffectList;
     sortTags?: string[];
 };
-
 export type PowerUpRedemptionMetadata = {
     username: string;
     userId: string;

package/types/pronouns.d.ts

@@ -4,8 +4,7 @@ export type Pronoun = {
     object: string;
     singular: boolean;
 };
-
 export type UserPronoun = {
     primary: string;
     secondary?: string;
-};
+};

package/types/quick-actions.d.ts

@@ -1,6 +1,5 @@
 import type { EffectList } from "./effects";
 import type { Awaitable } from "./util-types";
-
 export type QuickActionDefinition = {
     id: string;
     name: string;
@@ -11,8 +10,7 @@ export type QuickActionDefinition = {
     promptForArgs?: boolean;
     effectList?: EffectList;
 };
-
 export type SystemQuickAction = {
     definition: QuickActionDefinition;
     onTriggerEvent(): Awaitable<void>;
-};
+};

package/types/quotes.d.ts

@@ -2,7 +2,6 @@ export type QuoteAutoid = {
     _id: "__autoid__";
     seq: number;
 };
-
 export type Quote = {
     _id?: number;
     createdAt?: string;
@@ -11,7 +10,6 @@ export type Quote = {
     originator: string;
     text: string;
 };
-
 export type FormattedQuote = Omit<Quote, "_id"> & {
     id: number;
-};
+};

package/types/ranks.d.ts

@@ -3,7 +3,6 @@ export type Rank = {
     name: string;
     value?: number;
 };
-
 export type RankLadder = {
     id: string;
     name: string;
@@ -20,4 +19,4 @@ export type RankLadder = {
         showBadgeInChat?: boolean;
     };
     ranks: Rank[];
-};
+};

package/types/restrictions.d.ts

@@ -1,15 +1,13 @@
+import type ng from "angular";
 import type { Trigger, TriggerType, TriggersObject } from "./triggers";
 import type { Awaitable } from "./util-types";
-
 interface RestrictionScope<RestrictionModel> extends ng.IScope {
     restriction: Restriction<RestrictionModel>;
     restrictionDefinition: RestrictionType<RestrictionModel>;
     restrictionMode: RestrictionMode;
     [x: string]: any;
 }
-
 export type RestrictionMode = "all" | "any" | "none";
-
 export type RestrictionType<RestrictionModel = unknown> = {
     definition: {
         id: string;
@@ -19,26 +17,11 @@ export type RestrictionType<RestrictionModel = unknown> = {
     };
     failedReasonWhenInverted?: string;
     optionsTemplate: string;
-    optionsController?: (
-        $scope: RestrictionScope<RestrictionModel>,
-        ...args: any[]
-    ) => void;
-    optionsValueDisplay?: (
-        restriction: RestrictionModel,
-        ...args: any[]
-    ) => string;
-    predicate(
-        triggerData: Trigger,
-        restrictionData: RestrictionModel,
-        inherited?: boolean
-    ): Awaitable<boolean>;
-    onSuccessful?: (
-        triggerData: Trigger,
-        restrictionData: RestrictionModel,
-        inherited?: boolean
-    ) => Awaitable<void>;
+    optionsController?: ($scope: RestrictionScope<RestrictionModel>, ...args: any[]) => void;
+    optionsValueDisplay?: (restriction: RestrictionModel, ...args: any[]) => string;
+    predicate(triggerData: Trigger, restrictionData: RestrictionModel, inherited?: boolean): Awaitable<boolean>;
+    onSuccessful?: (triggerData: Trigger, restrictionData: RestrictionModel, inherited?: boolean) => Awaitable<void>;
 };
-
 export type Restriction<RestrictionModel = unknown> = {
     id: string;
     type: string;
@@ -47,7 +30,6 @@ export type Restriction<RestrictionModel = unknown> = {
 } & {
     [x: string]: unknown;
 };
-
 export type RestrictionData = {
     /**
      * Sets the command to only trigger when all/any/none of the restrictions pass.
@@ -62,4 +44,5 @@ export type RestrictionData = {
     restrictions: Restriction[];
     sendAsReply?: boolean;
     invertCondition?: boolean;
-};
+};
+export {};

package/types/roles.d.ts

@@ -2,7 +2,6 @@ export interface FirebotRole {
     id: string;
     name: string;
 }
-
 export type CustomRole = {
     id: string;
     name: string;
@@ -13,9 +12,8 @@ export type CustomRole = {
     }>;
     showBadgeInChat?: boolean;
 };
-
 export type LegacyCustomRole = {
     id: string;
     name: string;
     viewers: string[];
-};
+};

package/types/settings.d.ts

@@ -57,6 +57,10 @@ export type FirebotSettingsTypes = {
     ClearChatFeedMode: "never" | "onlyStreamer" | "always";
     ClearCustomScriptCache: boolean;
     ConnectOnLaunch: boolean;
+    ControlDeckEnabled: boolean;
+    ControlDeckPin?: string;
+    ControlDeckOrientationMode: "dynamic" | "fixed";
+    ControlDeckDefaultDeckId?: string | null;
     CopiedOverlayVersion: string;
     DashboardLayout: {
         dashboardViewerList: string;
@@ -83,6 +87,7 @@ export type FirebotSettingsTypes = {
     LegacySortTagsImported: boolean;
     LoggedInProfile: string;
     MaxBackupCount: number | "All";
+    MigratedLegacyStartUpScriptsToPlugins: boolean;
     MinimizeToTray: boolean;
     NotifyOnBeta: boolean;
     OpenEffectQueueMonitorOnLaunch: boolean;
@@ -125,7 +130,3 @@ export type FirebotSettingsTypes = {
     WhileLoopEnabled: boolean;
     WysiwygBackground: "black" | "white";
 };
-export declare const FirebotGlobalSettings: Partial<Record<keyof FirebotSettingsTypes, boolean>>;
-export declare const FirebotSettingsDefaults: FirebotSettingsTypes;
-/** Anything in `SettingsTypes` not listed here will resolve to "/settings/settingName" (e.g. "/settings/autoFlagBots") */
-export declare const FirebotSettingsPaths: Partial<Record<keyof FirebotSettingsTypes, string>>;

package/types/setups.d.ts

@@ -11,16 +11,13 @@ import type { CustomRole, LegacyCustomRole } from "./roles";
 import type { FirebotGlobalValue } from "./settings";
 import type { ScheduledTask, Timer } from "./timers";
 import type { VariableMacro } from "./variable-macros";
-
 export type SetupImportQuestion = {
     replaceToken: string;
     answer: string;
 };
-
 type FirebotSetupGlobalValue = FirebotGlobalValue & {
     id: string;
 };
-
 export type FirebotSetup = {
     name: string;
     description: string;
@@ -46,4 +43,5 @@ export type FirebotSetup = {
         overlayWidgetConfigs: OverlayWidgetConfig[];
         globalValues: FirebotSetupGlobalValue[];
     };
-};
+};
+export {};

package/types/sort-tags.d.ts

@@ -1,4 +1,4 @@
 export interface SortTag {
     id: string;
     name: string;
-}
+}

package/types/timers.d.ts

@@ -1,7 +1,5 @@
 import type { DateTime } from "luxon";
-
 import type { EffectList } from "./effects";
-
 export type Timer = {
     id: string;
     name: string;
@@ -12,7 +10,6 @@ export type Timer = {
     effects: EffectList;
     sortTags: string[];
 };
-
 export type TimerIntervalTracker = {
     timerId: string;
     onlyWhenLive: boolean;
@@ -23,7 +20,6 @@ export type TimerIntervalTracker = {
     intervalId: number | NodeJS.Timeout;
     startedAt: DateTime;
 };
-
 export type ScheduledTask = {
     id: string;
     name: string;
@@ -33,4 +29,4 @@ export type ScheduledTask = {
     onlyWhenLive: boolean;
     effects: EffectList;
     sortTags: string[];
-};
+};

package/types/triggers.d.ts

@@ -1,28 +1,10 @@
 import type { FirebotChatMessage } from "./chat";
 import type { CommandDefinition, SubCommand } from "./commands";
-
-export type TriggerType =
-    | "command"
-    | "custom_script"
-    | "startup_script"
-    | "api"
-    | "event"
-    | "hotkey"
-    | "timer"
-    | "scheduled_task"
-    | "counter"
-    | "preset"
-    | "quick_action"
-    | "manual"
-    | "channel_reward"
-    | "power_up"
-    | "overlay_widget";
-
+export type TriggerType = "command" | "custom_script" | "startup_script" | "api" | "event" | "hotkey" | "timer" | "scheduled_task" | "counter" | "preset" | "quick_action" | "control_deck" | "manual" | "channel_reward" | "power_up" | "overlay_widget";
 export type TriggerMeta = {
     triggerId?: string;
     [x: string]: unknown;
 };
-
 export type Trigger = {
     type: TriggerType;
     metadata: {
@@ -37,8 +19,14 @@ export type Trigger = {
             subcommandId?: string;
         };
         chatMessage?: FirebotChatMessage;
-        event?: { id: string, name: string };
-        eventSource?: { id: string, name: string };
+        event?: {
+            id: string;
+            name: string;
+        };
+        eventSource?: {
+            id: string;
+            name: string;
+        };
         eventData?: {
             chatMessage?: FirebotChatMessage;
             [x: string]: unknown;
@@ -53,9 +41,10 @@ export type Trigger = {
         };
         [x: string]: unknown;
     };
-    effectOutputs?: { [key: string]: unknown };
+    effectOutputs?: {
+        [key: string]: unknown;
+    };
 };
-
 export type TriggersObject = {
     [T in TriggerType]?: T extends "event" ? string[] | boolean : boolean;
 };

package/types/ui/angular.d.ts

@@ -1,31 +1,10 @@
 import type angular from "angular";
-
 export type BindingsDefinition<Bindings> = {
-    [K in keyof Bindings]: {} extends Pick<Bindings, K>
-        ? Bindings[K] extends string
-            ? "@?" | "<?" | "=?" | `@?${string}` | `<?${string}` | `=?${string}`
-            : Bindings[K] extends boolean
-                ? "<?" | "=?" | `<?${string}` | `=?${string}`
-                : Bindings[K] extends number
-                    ? "<?" | "=?" | `<?${string}` | `=?${string}`
-                    : Bindings[K] extends (...args: any[]) => any
-                        ? "&?" | `&?${string}`
-                        : "<?" | "=?" | `<?${string}` | `=?${string}`
-        : Bindings[K] extends string
-            ? "@" | "<" | "=" | `@${string}` | `<${string}` | `=${string}`
-            : Bindings[K] extends boolean
-                ? "<" | "=" | `<${string}` | `=${string}`
-                : Bindings[K] extends number
-                    ? "<" | "=" | `<${string}` | `=${string}`
-                    : Bindings[K] extends (...args: any[]) => any
-                        ? "&" | `&${string}`
-                        : "<" | "=" | `<${string}` | `=${string}`;
+    [K in keyof Bindings]: {} extends Pick<Bindings, K> ? Bindings[K] extends string ? "@?" | "<?" | "=?" | `@?${string}` | `<?${string}` | `=?${string}` : Bindings[K] extends boolean ? "<?" | "=?" | `<?${string}` | `=?${string}` : Bindings[K] extends number ? "<?" | "=?" | `<?${string}` | `=?${string}` : Bindings[K] extends (...args: any[]) => any ? "&?" | `&?${string}` : "<?" | "=?" | `<?${string}` | `=?${string}` : Bindings[K] extends string ? "@" | "<" | "=" | `@${string}` | `<${string}` | `=${string}` : Bindings[K] extends boolean ? "<" | "=" | `<${string}` | `=${string}` : Bindings[K] extends number ? "<" | "=" | `<${string}` | `=${string}` : Bindings[K] extends (...args: any[]) => any ? "&" | `&${string}` : "<" | "=" | `<${string}` | `=${string}`;
 };
-
 export type FirebotComponent<Bindings, ExtraControllerProps = {}> = angular.IComponentOptions & {
     bindings: BindingsDefinition<Bindings>;
-    controller: (
-        this: angular.IController & Bindings & ExtraControllerProps & { [key: string]: unknown },
-        ...args: unknown[]
-    ) => void;
-};
+    controller: (this: angular.IController & Bindings & ExtraControllerProps & {
+        [key: string]: unknown;
+    }, ...args: unknown[]) => void;
+};

package/types/ui/effect-helper-service.d.ts

@@ -1,5 +1,4 @@
 import type { EffectType } from "../effects";
-
 export type EffectHelperService = {
     getAllEffectTypes: () => Promise<EffectType[]>;
-};
+};