@crowbartools/firebot-types 5.67.0-alpha5 → 5.67.0-alpha6

package/backend/custom-scripts/executors/legacy-startup-script-executor.d.ts

@@ -1,12 +1,12 @@
 import { ScriptBase, LegacyCustomScript, InstalledPluginConfig, ScriptDetails } from "../../../types";
-import { IPluginExecutor, ScriptExecutionResult } from "./script-executor.interface";
+import { IPluginExecutor, PluginExecutionResult } from "./script-executor.interface";
 /**
  * Executor for legacy startup scripts (scripts that export a getScriptManifest function that returns an object with startupOnly: true)
  */
 export declare class LegacyStartUpScript extends IPluginExecutor {
     constructor();
     canHandle(script: ScriptBase | LegacyCustomScript): Promise<boolean>;
-    executePlugin(script: ScriptBase | LegacyCustomScript, config: InstalledPluginConfig): Promise<ScriptExecutionResult>;
+    executePlugin(script: ScriptBase | LegacyCustomScript, config: InstalledPluginConfig): Promise<PluginExecutionResult>;
     unloadPlugin(script: ScriptBase | LegacyCustomScript): Promise<void>;
     updateParameters(script: ScriptBase | LegacyCustomScript, config: InstalledPluginConfig): Promise<void>;
     getScriptDetails(script: ScriptBase | LegacyCustomScript): Promise<ScriptDetails>;

package/backend/custom-scripts/executors/plugin-executor.d.ts

@@ -1,5 +1,5 @@
 import { ScriptBase, LegacyCustomScript, Plugin, InstalledPluginConfig, ScriptDetails } from "../../../types";
-import { IPluginExecutor, PluginRegistrations, ScriptExecutionResult } from "./script-executor.interface";
+import { IPluginExecutor, PluginRegistrations, PluginExecutionResult } from "./script-executor.interface";
 /**
  * Executor for new-spec Plugins (manifest.type === "plugin")
  */
@@ -7,7 +7,7 @@ export declare class PluginExecutor extends IPluginExecutor {
     constructor();
     canHandle(script: ScriptBase | LegacyCustomScript): script is Plugin<import("../../../types").FirebotParams>;
     getScriptDetails(script: ScriptBase | LegacyCustomScript): ScriptDetails | null;
-    executePlugin(script: ScriptBase | LegacyCustomScript, config: InstalledPluginConfig, isInstalling?: boolean): Promise<ScriptExecutionResult>;
+    executePlugin(script: ScriptBase | LegacyCustomScript, config: InstalledPluginConfig, isInstalling?: boolean): Promise<PluginExecutionResult>;
     unloadPlugin(script: ScriptBase | LegacyCustomScript, config: InstalledPluginConfig, registrations?: PluginRegistrations, isUninstalling?: boolean): Promise<void>;
     updateParameters(script: ScriptBase | LegacyCustomScript, config: InstalledPluginConfig): Promise<void>;
     private registerAll;

package/backend/custom-scripts/executors/script-executor.interface.d.ts

@@ -3,10 +3,6 @@ declare abstract class IBaseScriptExecutor {
     abstract canHandle(script: ScriptBase | LegacyCustomScript): Awaitable<boolean>;
     abstract getScriptDetails(script: ScriptBase | LegacyCustomScript): Awaitable<ScriptDetails | null>;
 }
-/**
- * Bookkeeping of items a plugin registered with various managers so they
- * can be cleanly unregistered on unload.
- */
 export interface PluginRegistrations {
     effectIds?: string[];
     variableHandles?: string[];
@@ -16,8 +12,9 @@ export interface PluginRegistrations {
     restrictionIds?: string[];
     integrationIds?: string[];
     gameIds?: string[];
+    uiExtensionIds?: string[];
 }
-export type ScriptExecutionResult = {
+export type PluginExecutionResult = {
     success: true;
     registrations?: PluginRegistrations;
 } | {
@@ -25,7 +22,7 @@ export type ScriptExecutionResult = {
     error: string;
 };
 export declare abstract class IPluginExecutor extends IBaseScriptExecutor {
-    abstract executePlugin(script: ScriptBase | LegacyCustomScript, config: InstalledPluginConfig, isInstalling?: boolean): Awaitable<ScriptExecutionResult>;
+    abstract executePlugin(script: ScriptBase | LegacyCustomScript, config: InstalledPluginConfig, isInstalling?: boolean): Awaitable<PluginExecutionResult>;
     abstract unloadPlugin(script: ScriptBase | LegacyCustomScript, config: InstalledPluginConfig, registrations?: PluginRegistrations, isUninstalling?: boolean): Awaitable<void>;
     updateParameters?(script: ScriptBase | LegacyCustomScript, config: InstalledPluginConfig): Awaitable<void>;
 }

package/backend/custom-scripts/plugin-manifest-utils.d.ts

@@ -0,0 +1,8 @@
+import { Manifest } from "../../types";
+/**
+ * Resolves the external links (repo / website / support) for a plugin manifest.
+ *
+ * When the manifest `repo` points at a GitHub repository, `website` and `support`
+ *   are auto-populated when not explicitly provided.
+ */
+export declare function resolvePluginManifestLinks<T extends Manifest>(manifest: T): T;

package/backend/custom-scripts/script-api/namespaces/frontend-communicator.d.ts

@@ -0,0 +1,2 @@
+import type { ScriptFrontendCommunicatorApi } from "../../../../types/script-api";
+export declare const createFrontendCommunicatorApi: import("../internal/define-namespace").ScriptApiNamespaceFactory<ScriptFrontendCommunicatorApi>;

package/backend/custom-scripts/script-manager.d.ts

@@ -11,16 +11,22 @@ type GetScriptDetailsResult = {
 };
 declare class ScriptManager {
     private activePlugins;
-    private activePluginsByFileName;
     private pendingApiInstances;
     private effectScriptApiInstances;
+    private startingPlugins;
     private requireInterceptorInstalled;
     private pluginExecutors;
     private effectScriptExecutors;
     constructor();
     startPlugin(pluginConfig: InstalledPluginConfig, installing?: boolean): Promise<void>;
+    private doStartPlugin;
     startPlugins(): Promise<void>;
     stopPlugin(pluginId: string, uninstalling?: boolean): Promise<void>;
+    /**
+     * Convenience helper for hot-reloading. Finds an active plugin by its script file
+     * name and restarts it (stop then start). Does nothing if no active plugin matches.
+     */
+    restartPluginByFileName(fileName: string): Promise<void>;
     stopAllPlugins(): Promise<void>;
     /**
      * Handle a config change. Starts/stops as needed, and on a still-enabled plugin
@@ -50,14 +56,18 @@ declare class ScriptManager {
     cancelInstall(fileName: string): Promise<void>;
     /**
      * Called by PluginConfigManager when a config is deleted, so we can stop the
-     * plugin and remove the underlying script file if no other config references it.
+     * plugin.
      */
     onPluginConfigDeleted(pluginConfig: InstalledPluginConfig): Promise<void>;
+    deleteScriptFileIfUnreferenced(fileName: string): Promise<void>;
+    /**
+     * Remove an installed plugin. Stops the plugin and deletes its config, and
+     * optionally deletes the underlying script file from the scripts folder.
+     */
+    deletePlugin(pluginId: string, deleteScriptFile?: boolean): Promise<boolean>;
     /**
      * Replace the underlying script file for an existing plugin config with a new file
-     * chosen on disk. Fires `onUnload` for the previous version, clears its require cache,
-     * swaps the file (deleting the old one when the name changes), then re-starts the
-     * plugin so the new code is picked up dynamically.
+     * chosen on disk.
      */
     updatePluginFromPath(pluginId: string, sourcePath: string, overwrite?: boolean): Promise<GetScriptDetailsResult | {
         success: false;
@@ -70,6 +80,7 @@ declare class ScriptManager {
     }, trigger?: Trigger): Promise<EffectScriptExecutionResult | undefined>;
     private disposeEffectScriptApi;
     private getScriptFilePath;
+    private getActivePluginByFileName;
     private findPluginExecutor;
     private installRequireInterceptor;
     private createApiInstance;

package/backend/ui-extensions/ui-extension-manager.d.ts

@@ -1,4 +1,4 @@
-import type { UIExtension } from "./extension-types";
+import type { UIExtension } from "../../types";
 declare class UIExtensionManager {
     private _extensions;
     private uiReady;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crowbartools/firebot-types",
-  "version": "5.67.0-alpha5",
+  "version": "5.67.0-alpha6",
   "description": "Type definitions and script API for Firebot plugins and custom scripts.",
   "main": "index.js",
   "types": "index.d.ts",

package/types/index.d.ts

@@ -31,6 +31,7 @@ export * from "./sort-tags";
 export * from "./timers";
 export * from "./triggers";
 export * from "./ui";
+export * from "./ui-extensions";
 export * from "./util-types";
 export * from "./variable-macros";
 export * from "./variables";

package/types/plugins.d.ts

@@ -8,6 +8,7 @@ import { RestrictionType } from "./restrictions";
 import { FirebotParams, FirebotParameterArray } from "./parameters";
 import { FirebotGame } from "./games";
 import { Integration } from "./integrations";
+import { UIExtension } from "./ui-extensions";
 
 type NoResult = Awaitable<void>;
 
@@ -47,21 +48,42 @@ export interface Manifest {
     author: string;
     description: string | ManifestDescription;
 
-    keywords?: string[];
+    // keywords?: 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;
 
+    /**
+     * A FontAwesome icon name shown in the UI (eg. "fa-cogs").
+     */
     icon?: `fa-${string}`;
+    /**
+     * A hex color code (eg. "#FF0000") used for the icon.
+     */
     color?: string;
 
+    /**
+     * 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: ScriptType;
 }
 
@@ -102,12 +124,12 @@ export interface Plugin<Params extends FirebotParams = FirebotParams> extends Sc
         effects?: DynamicArray<EffectType>;
         eventSources?: DynamicArray<EventSource>;
         variables?: DynamicArray<ReplaceVariable>;
-        // endpoints?: DynamicArray<HttpEndpoint>;
         integrations?: DynamicArray<Integration>;
         filters?: DynamicArray<EventFilter>;
         restrictions?: DynamicArray<RestrictionType>;
         systemCommands?: DynamicArray<SystemCommand>;
         games?: DynamicArray<FirebotGame>;
+        uiExtensions?: DynamicArray<UIExtension>;
     };
 
     // Called when the script is loaded
@@ -177,6 +199,7 @@ type LegacyCustomScriptManifest = {
     author: string;
     website?: string;
     startupOnly?: boolean;
+    initBeforeShowingParams?: boolean;
     firebotVersion?: "5";
 };
 

package/types/script-api.d.ts

@@ -121,6 +121,38 @@ export interface ScriptTwitchApi {
     api: typeof TwitchApi;
 }
 
+export interface ScriptFrontendCommunicatorApi {
+    /** Send a synchronous event to the frontend. */
+    send<ExpectedArg = unknown>(eventName: string, data?: ExpectedArg): void;
+
+    /**
+     * Send an asynchronous event to the frontend and await the reply it sends
+     * back.
+     */
+    fireEventAsync<ReturnPayload = void, ExpectedArg = unknown>(
+        eventName: string,
+        data?: ExpectedArg
+    ): Promise<ReturnPayload>;
+
+    /**
+     * Handle a synchronous event triggered by the frontend. Returns an
+     * `unsubscribe` function.
+     */
+    on<ExpectedArgs extends Array<unknown> = [], ReturnPayload = void>(
+        eventName: string,
+        callback: (...args: ExpectedArgs) => ReturnPayload
+    ): () => void;
+
+    /**
+     * Handle an asynchronous event triggered by the frontend. Returns an
+     * `unsubscribe` function.
+     */
+    onAsync<ExpectedArgs extends Array<unknown> = [], ReturnPayload = void>(
+        eventName: string,
+        callback: (...args: ExpectedArgs) => Promise<ReturnPayload>
+    ): () => void;
+}
+
 export interface FirebotScriptApi {
     /** Running Firebot version, e.g. `"5.65.0"`. */
     version: string;
@@ -136,4 +168,6 @@ export interface FirebotScriptApi {
     effects: ScriptEffectsApi;
     /** Access to Firebot's Twitch API wrappers (Helix, chat, auth, etc). */
     twitch: ScriptTwitchApi;
+    /** Two-way messaging between the script and the frontend. */
+    frontendCommunicator: ScriptFrontendCommunicatorApi;
 }

package/types/settings.d.ts

@@ -83,6 +83,7 @@ export type FirebotSettingsTypes = {
     LegacySortTagsImported: boolean;
     LoggedInProfile: string;
     MaxBackupCount: number | "All";
+    MigratedLegacyStartUpScriptsToPlugins: boolean;
     MinimizeToTray: boolean;
     NotifyOnBeta: boolean;
     OpenEffectQueueMonitorOnLaunch: boolean;

package/types/ui-extensions.d.ts

@@ -0,0 +1,103 @@
+/* eslint-disable @typescript-eslint/no-unsafe-function-type */
+export type BasePage = {
+    id: string;
+    name: string;
+    icon: `fa-${string}`;
+    fullPage?: boolean;
+    disableScroll?: boolean;
+};
+
+export type AngularJsPage = BasePage & {
+    type: 'angularjs';
+    template: string;
+    controller: Function;
+};
+
+export type IframePage = BasePage & {
+    type: 'iframe';
+    // Other properties TBD
+};
+
+export type AngularJsFactory = {
+    name: string;
+    function: Function;
+};
+
+export type AngularJsComponent = {
+    name: string;
+    bindings: Record<string, string>;
+    template: string;
+    transclude?: boolean | string | { [slot: string]: string };
+    controller: Function;
+};
+
+
+/**
+ * A specialized AngularJS component for rendering Firebot parameters.
+ * These components will always have the following bindings:
+ * - `$ctrl.schema`: The parameter schema (any properties in the parameter object)
+ * - `$ctrl.value`: The current value of the parameter
+ * - `$ctrl.onInput`: A callback function to call when the parameter value changes
+ * - `$ctrl.onTouched`: A callback function to call when the parameter is touched
+ */
+export type AngularJsFirebotParameterComponent = {
+    parameterConfig: {
+        /**
+         * The type of parameter this component handles.
+         * This value is what will go in the "type" field of a parameter schema.
+         */
+        type: string;
+        hideTitle?: boolean;
+        hideDescription?: boolean;
+    };
+    template: string;
+    controller: Function;
+};
+
+export type AngularJsDirective = {
+    name: string;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    function: (...args: any[]) => {
+        compile?: Function;
+        controller?: Function;
+        link?: Function;
+        multiElement?: boolean;
+        name?: string;
+        priority?: number;
+        require?: string | string[] | { [controller: string]: string };
+        restrict?: string;
+        scope?: boolean | object;
+        template?: string;
+        terminal?: boolean;
+        transclude?: boolean | string | { [slot: string]: string };
+    };
+};
+
+export type AngularJsFilter = {
+    name: string;
+    function: {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        (...args: any[]): Function;
+    };
+};
+
+export type UIExtension = {
+    id: string;
+    /**
+     * Adds new sidebar entries under an "Extensions" category
+     */
+    pages?: AngularJsPage[];
+    /**
+     * Add your own AngularJS services, components, directives, filters
+     */
+    providers?: {
+        factories?: AngularJsFactory[];
+        components?: AngularJsComponent[];
+        directives?: AngularJsDirective[];
+        filters?: AngularJsFilter[];
+        /**
+         * Add your own parameter components for rendering custom parameter types
+         */
+        parameters?: AngularJsFirebotParameterComponent[];
+    };
+};