@crowbartools/firebot-types 5.67.0-alpha1.3 → 5.67.0-alpha11

package/types/http-server.d.ts

@@ -0,0 +1,31 @@
+import type { Request, Response } from "express";
+import type { Awaitable } from "./util-types";
+
+export type HttpMethod =
+    | "GET"
+    | "POST"
+    | "PUT"
+    | "PATCH"
+    | "DELETE"
+    | "HEAD"
+    | "CONNECT"
+    | "OPTIONS"
+    | "TRACE";
+
+export interface CustomHttpRoute {
+    path: string;
+    method: HttpMethod;
+    handler: (req: Request, res: Response) => Awaitable<void>;
+}
+
+/**
+ * Defines custom HTTP routes that plugins can add to the internal Firebot HTTP server.
+ * Paths can contain multiple levels and parameters (e.g. `/item/:id`).
+ * Full routes are built as follows (default Firebot hostname/port used as an example):
+ *
+ * `{method} http://localhost:7472/plugins/{prefix}/{path}`
+ */
+export interface PluginHttpRouteDefinition {
+    prefix: string;
+    routes: Array<CustomHttpRoute>;
+}

package/types/index.d.ts

@@ -12,13 +12,17 @@ export * from "./expressionish";
 export * from "./games";
 export * from "./goals";
 export * from "./hotkeys";
+export * from "./http-server";
 export * from "./icons";
 export * from "./import";
 export * from "./integrations";
 export * from "./moderation";
 export * from "./modules";
+export * from "./notifications";
 export * from "./overlay-widgets";
 export * from "./parameters";
+export * from "./plugins";
+export * from "./power-ups";
 export * from "./pronouns";
 export * from "./quick-actions";
 export * from "./quotes";
@@ -31,10 +35,10 @@ 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";
 export * from "./viewers";
 export * from "./webhooks";
-export * from "./websocket";
-export * from "./plugins";
+export * from "./websocket";

package/types/notifications.d.ts

@@ -0,0 +1,33 @@
+export type NotificationSource = "external" | "internal" | "script";
+
+export type NotificationType = "info" | "tip" | "update" | "alert";
+
+export type ExternalNotification = {
+    id: string;
+    title: string;
+    message: string;
+    type: NotificationType;
+};
+
+export type NotificationBase = {
+    title: string;
+    message: string;
+    type: NotificationType;
+    source?: NotificationSource;
+    scriptName?: string;
+    externalId?: string;
+    metadata?: Record<string, unknown>;
+};
+
+export type Notification = NotificationBase & {
+    id: string;
+    timestamp: Date;
+    saved: boolean;
+    read: boolean;
+};
+
+export interface NotificationCache {
+    dbVersion?: string;
+    notifications: Notification[];
+    knownExternalIds: string[];
+}

package/types/plugins.d.ts

@@ -1,13 +1,18 @@
-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";
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import type { EffectInstance, EffectList, EffectType } from "./effects";
+import type { Trigger } from "./triggers";
+import type { Awaitable } from "./util-types";
+import type { 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";
 
 type NoResult = Awaitable<void>;
 
@@ -26,6 +31,7 @@ export type ScriptContext<Params extends FirebotParams = FirebotParams> = {
     parameters: Params;
 };
 
+type DynamicObject<T> = T | ((context: ScriptContext) => Awaitable<T>);
 type DynamicArray<T> = Array<T | ((context: ScriptContext) => Awaitable<T>)>;
 
 export type ScriptType = "script" | "plugin";
@@ -47,21 +53,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;
 }
 
@@ -77,46 +104,42 @@ export interface ScriptBase<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
+    /**
+     * Automatically handles registration with appropriate managers for definitions
+     * when the script 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>;
     };
 
-    // Called when the script is loaded
+    /** Called when the plugin is loaded */
     onLoad?: (context: ScriptContext<Params>, isInstalling?: boolean) => NoResult;
 
-    // Called when firebot is closing or plugin is disabled / removed
+    /** 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
+    /** Called when the user updates plugin-specific parameters */
     onParameterUpdate?: (context: ScriptContext<Params>) => NoResult;
 }
 
@@ -128,11 +151,10 @@ export type InstalledPlugin = {
 };
 
 /* Legacy types */
-
 type LegacyScriptParameters = Record<
     string,
     {
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+
         type: any;
         title?: string;
         description?: string;
@@ -177,6 +199,7 @@ type LegacyCustomScriptManifest = {
     author: string;
     website?: string;
     startupOnly?: boolean;
+    initBeforeShowingParams?: boolean;
     firebotVersion?: "5";
 };
 

package/types/script-api.d.ts

@@ -1,10 +1,17 @@
 /// <reference types="node" />
 
 // Public contract types for the Firebot Script API.
-//
 // Everything a custom script can touch via `require("@crowbartools/firebot-types")`
 // should be defined here
 
+import type { TriggeredEvent } from "./events";
+import type { RunEffectsContext } from "./effects";
+import type { TwitchApi } from "../backend/streaming-platforms/twitch/api";
+import type { Notification } from "./notifications";
+import type { FirebotAccount } from "./accounts";
+import type { FirebotSettingsTypes } from "./settings";
+import type { InstalledPlugin } from "./plugins";
+
 export type ScriptLogMethod = (message: string, ...meta: unknown[]) => void;
 
 export interface ScriptLoggerApi {
@@ -45,51 +52,182 @@ export interface ScriptWebhooksApi {
     onReceived(handler: ScriptWebhookEventHandler): () => void;
 }
 
-export interface ScriptFsDirEntry {
-    /** File or directory name */
-    name: string;
-    /** Path relative to the script's data dir */
-    relativePath: string;
-    isFile: boolean;
-    isDirectory: boolean;
+/**
+ * Simple per-script storage scoped to the script's data directory.
+ * Provides helpers for storing/loading JSON values
+ * plus generic file read/write for anything else.
+ */
+export interface ScriptStorageApi {
+    /** Absolute path to this script's data directory. */
+    readonly path: string;
+
+    /** Save a value as JSON under the given key. The key becomes the filename with a `.json` extension. */
+    setJson(key: string, value: unknown): Promise<void>;
+    /**
+     * Load a JSON value previously saved with `setJson`. Returns `null` if
+     * nothing has been stored under this key.
+     */
+    getJson<T = unknown>(key: string): Promise<T | null>;
+    /** Delete the JSON value stored under the given key. No-op if missing. */
+    deleteJson(key: string): Promise<void>;
+
+    /** Check whether a file exists in the data directory. */
+    fileExists(name: string): Promise<boolean>;
+    /** Read a file's raw bytes. Returns `null` if it doesn't exist. */
+    readFile(name: string): Promise<Buffer | null>;
+    /** Read a file as text. Returns `null` if it doesn't exist. */
+    readTextFile(name: string, encoding?: BufferEncoding): Promise<string | null>;
+    /** Write contents to a file, creating any missing parent directories. */
+    writeFile(name: string, contents: string | Buffer | Uint8Array): Promise<void>;
+    /** Delete a file. No-op if it doesn't exist. */
+    deleteFile(name: string): Promise<void>;
+}
+
+export type ScriptEventHandler = (event: TriggeredEvent) => void;
+
+export interface ScriptEventsApi {
+    /**
+     * Subscribe to all Firebot events as they trigger. Returns an `unsubscribe`
+     * function.
+     */
+    onTriggered(handler: ScriptEventHandler): () => void;
+
+    /**
+     * Manually trigger a Firebot event.
+     */
+    trigger(
+        sourceId: string,
+        eventId: string,
+        meta?: Record<string, unknown>
+    ): Promise<void>;
+}
+
+export interface ScriptEffectsApi {
+    /**
+     * Register an existing effect to be available for an event.
+     * Useful for surfacing built-in effects on script provided events.
+     */
+    addEventToEffect(effectId: string, eventSourceId: string, eventId: string): void;
+
+    /** Reverse of `addEventToEffect`. */
+    removeEventFromEffect(effectId: string, eventSourceId: string, eventId: string): void;
+
+    /**
+     * Run an effect list. Respects the list's run mode and effect queue, if any.
+     * Resolves once the effects have been run (queued lists resolve
+     * immediately).
+     */
+    processEffects(context: RunEffectsContext): Promise<unknown>;
 }
 
-export interface ScriptFsApi {
-    /** Absolute path to this script's data directory. Read-only. */
-    readonly dataDir: string;
+export interface ScriptTwitchApi {
+    /** The full Twitch API surface. See {@linkcode TwitchApi}. */
+    api: typeof TwitchApi;
+}
+
+/**
+ * Access to this plugin's saved parameter values (the settings configured by
+ * the user)
+ */
+export interface ScriptParametersApi {
+    getAll<T extends Record<string, unknown> = Record<string, unknown>>(): T;
+}
+
+export interface ScriptNotificationsApi {
+    /**
+     * Create a new notification. Pass `permanentlySave` as `true` to persist it
+     * across restarts.
+     */
+    add(notification: Pick<Notification, "title" | "message" | "type" | "metadata">, permanentlySave?: boolean): Notification;
+    /** Look up one of this script's notifications by id. */
+    get(id: string): Notification | null;
+    /** All notifications owned by this script. */
+    getAll(): Notification[];
+    /** Delete one of this script's notifications by id. */
+    delete(id: string): void;
+    /** Delete all of this script's notifications. */
+    clearAll(): void;
+}
 
-    /** Resolve a sandboxed relative path to an absolute one. Throws on escape. */
-    resolve(relativePath: string): string;
+export interface ScriptFrontendCommunicatorApi {
+    /** Send a synchronous event to the frontend. */
+    send<ExpectedArg = unknown>(eventName: string, data?: ExpectedArg): void;
 
-    exists(relativePath: string): Promise<boolean>;
+    /**
+     * 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>;
 
-    readText(relativePath: string, encoding?: BufferEncoding): Promise<string>;
-    writeText(relativePath: string, contents: string, encoding?: BufferEncoding): Promise<void>;
+    /**
+     * 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;
 
-    readBytes(relativePath: string): Promise<Buffer>;
-    writeBytes(relativePath: string, contents: Buffer | Uint8Array): Promise<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;
+}
 
-    /** Read JSON. Returns `null` if the file doesn't exist. */
-    readJson(relativePath: string): Promise<unknown>;
-    /** Write JSON pretty-printed with 2-space indent. */
-    writeJson(relativePath: string, value: unknown): Promise<void>;
+export interface ScriptSettingsApi {
+    /**
+     * Get a Firebot setting value or its default
+     *
+     * @param settingName Name of the setting to get
+     * @returns Setting value, or the default if one isn't explicitly set
+     */
+    getSetting<SettingName extends keyof FirebotSettingsTypes>(settingName: SettingName): FirebotSettingsTypes[SettingName];
+}
 
-    /** Create a directory (and any missing parents). */
-    mkdir(relativePath: string): Promise<void>;
-    /** Delete a file or directory recursively. No-op if it doesn't exist. */
-    remove(relativePath: string): Promise<void>;
+export interface ScriptPluginsApi {
+    /**
+     * Get a list of currently installed plugins installed by the user
+     */
+    getInstalledPlugins(): Promise<Array<InstalledPlugin>>;
+}
 
-    /** List immediate children of a directory (defaults to the data dir root). */
-    list(relativePath?: string): Promise<ScriptFsDirEntry[]>;
+export interface Accounts {
+    streamer: FirebotAccount;
+    bot: FirebotAccount;
 }
 
 export interface FirebotScriptApi {
-    /** Running Firebot version, e.g. `"5.65.0"`. */
+    /** Running Firebot version, e.g. `"5.67.0"`. */
     version: string;
+    /** The streamer and bot accounts currently in use. */
+    accounts: Accounts;
     /** Scoped logger. */
     logger: ScriptLoggerApi;
+    /** Access to Firebot settings. */
+    settings: ScriptSettingsApi;
     /** Webhooks owned by this script. */
     webhooks: ScriptWebhooksApi;
-    /** Sandboxed filesystem rooted at this script's data directory. */
-    fs: ScriptFsApi;
+    /** Simple persistent storage rooted at this script's data directory. */
+    storage: ScriptStorageApi;
+    /** Subscribe to and trigger Firebot events + register event sources. */
+    events: ScriptEventsApi;
+    /** Run effect lists. */
+    effects: ScriptEffectsApi;
+    /** Access to Firebot's Twitch API wrappers (Helix, chat, auth, etc). */
+    twitch: ScriptTwitchApi;
+    /** This plugin's saved parameter values. */
+    parameters: ScriptParametersApi;
+    /** Two-way messaging between the script and the frontend. */
+    frontendCommunicator: ScriptFrontendCommunicatorApi;
+    /** Notifications owned by this script. */
+    notifications: ScriptNotificationsApi;
+    /** Access to installed plugins. */
+    plugins: ScriptPluginsApi;
 }

package/types/settings.d.ts

@@ -1,19 +1,22 @@
-export declare enum FirebotAutoUpdateLevel {
+export enum FirebotAutoUpdateLevel {
     Off = 0,
     Bugfix = 1,
     Feature = 2,
     MajorRelease = 3,
     Betas = 4
 }
+
 export type FirebotAudioDevice = {
     label: string;
     deviceId: string;
 };
+
 export type FirebotGlobalValue = {
     name: string;
     secret?: boolean;
     value: string;
 };
+
 export type FirebotSettingsTypes = {
     ActiveChatUserListTimeout: number;
     ActiveProfiles: string[];
@@ -48,10 +51,7 @@ export type FirebotSettingsTypes = {
     ChatShowFfzEmotes: boolean;
     ChatShowSevenTvEmotes: boolean;
     ChatShowSharedChatInfo: boolean;
-    ChatTaggedNotificationSound: {
-        name: string;
-        path?: string | undefined;
-    };
+    ChatTaggedNotificationSound: { name: string, path?: string | undefined };
     ChatTaggedNotificationVolume: number;
     ChatTimestamps: boolean;
     ClearChatFeedMode: "never" | "onlyStreamer" | "always";
@@ -73,7 +73,7 @@ export type FirebotSettingsTypes = {
     EventSetSettings: Record<string, {
         position: number;
     }>;
-    EventSettings: object;
+    EventSettings: object; // Pretty sure this is no longer used
     FirstTimeUse: boolean;
     ForceOverlayEffectsToContinueOnRefresh: boolean;
     GlobalValues: Array<FirebotGlobalValue>;
@@ -83,6 +83,7 @@ export type FirebotSettingsTypes = {
     LegacySortTagsImported: boolean;
     LoggedInProfile: string;
     MaxBackupCount: number | "All";
+    MigratedLegacyStartUpScriptsToPlugins: boolean;
     MinimizeToTray: boolean;
     NotifyOnBeta: boolean;
     OpenEffectQueueMonitorOnLaunch: boolean;
@@ -124,8 +125,4 @@ export type FirebotSettingsTypes = {
     WebServerPort: number;
     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/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[];
+    };
+};

package/types/websocket.d.ts

@@ -62,7 +62,7 @@ interface InvokePluginMessage extends InvokeMessage {
 
 interface CustomWebSocketHandler {
     pluginName: string;
-    callback: (data: unknown | unknown[]) => Awaitable<void>;
+    handler: (data: unknown) => Awaitable<void>;
 }
 
 export type OverlayConnectedData = {