@crowbartools/firebot-types 5.67.0-alpha27 → 5.67.0-alpha28

package/backend/effects/builtin/overlay-widgets/update-rotating-text.d.ts

@@ -0,0 +1,12 @@
+import type { EffectType } from "../../../../types";
+declare const model: EffectType<{
+    rotatingTextWidgetId: string;
+    action: "add" | "remove" | "set";
+    texts?: string[];
+    variableEvaluation?: "dynamic" | "onRun";
+    removeMode?: "first" | "last" | "position" | "matching";
+    removePosition?: number;
+    removeValue?: string;
+    removeExactMatch?: boolean;
+}>;
+export = model;

package/backend/overlay-widgets/builtin-types/index.d.ts

@@ -28,7 +28,7 @@ declare const _default: (import("../../../types").OverlayWidgetType<import("./ch
     fontOptions?: import("../../../types").FontOptions;
     horizontalAlignment: "left" | "center" | "right";
     verticalAlignment: "top" | "center" | "bottom";
-}, {}> | import("../../../types").OverlayWidgetType<{
+}, {}> | import("../../../types").OverlayWidgetType<import("./rotating-text/rotating-text").RotatingTextSettings, import("./rotating-text/rotating-text").RotatingTextState> | import("../../../types").OverlayWidgetType<{
     format?: string;
     fontOptions?: import("../../../types").FontOptions;
     horizontalAlignment: "left" | "center" | "right";

package/backend/overlay-widgets/builtin-types/rotating-text/rotating-text.d.ts

@@ -0,0 +1,18 @@
+import type { OverlayWidgetType, OverlayWidgetConfig, FontOptions, Animation } from "../../../../types";
+export declare const ROTATING_TEXT_TYPE_ID = "firebot:rotating-text";
+export type RotatingTextSettings = {
+    texts: string[];
+    intervalSeconds: number;
+    randomizeOrder: boolean;
+    fontOptions?: FontOptions;
+    horizontalAlignment: "left" | "center" | "right";
+    verticalAlignment: "top" | "center" | "bottom";
+    backgroundColor: string;
+    backgroundBorderRadius: number;
+    addDropShadow: boolean;
+    textEnterAnimation: Animation;
+    textExitAnimation: Animation;
+};
+export type RotatingTextState = Record<string, never>;
+export type RotatingTextWidgetConfig = OverlayWidgetConfig<RotatingTextSettings, RotatingTextState>;
+export declare const rotatingText: OverlayWidgetType<RotatingTextSettings, RotatingTextState>;

package/backend/plugins/executors/plugin-executor.interface.d.ts

@@ -1,4 +1,4 @@
-import { InstalledPluginConfig, LegacyCustomScript, PluginBase, Awaitable, PluginDetails, AdditionalVariableEvent, AdditionalEffectEvent } from "../../../types";
+import { InstalledPluginConfig, LegacyCustomScript, PluginBase, Awaitable, PluginDetails, AdditionalVariableEvent, AdditionalEffectEvent, AdditionalFilterEvent } from "../../../types";
 import type { PluginApiContext } from "../plugin-api";
 declare abstract class IBasePluginExecutor {
     abstract canHandle(plugin: PluginBase | LegacyCustomScript): Awaitable<boolean>;
@@ -24,6 +24,7 @@ export interface PluginRegistrations {
     websocketListenerName?: string;
     additionalVariableEvents?: AdditionalVariableEvent[];
     additionalEffectEvents?: AdditionalEffectEvent[];
+    additionalFilterEvents?: AdditionalFilterEvent[];
 }
 export type PluginExecutionResult = {
     success: true;

package/backend/streaming-platforms/twitch/api/eventsub/eventsub-client.d.ts

@@ -2,6 +2,7 @@ declare class TwitchEventSubClient {
     private logger;
     private _eventSubListener;
     private _subscriptions;
+    private ensureViewerExists;
     private createSubscriptions;
     createClient(): void;
     removeSubscriptions(): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crowbartools/firebot-types",
-  "version": "5.67.0-alpha27",
+  "version": "5.67.0-alpha28",
   "description": "Type definitions and plugin API for Firebot plugins.",
   "main": "index.js",
   "types": "index.d.ts",

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

@@ -1,7 +1,7 @@
 import { EventEmitter } from "events";
 import { Express, Request, Response, Router } from "express";
 import http from "http";
-import type { HttpMethod, CustomHttpRoute, PluginHttpRouteDefinition, CustomWebSocketHandler, Awaitable } from "../types";
+import type { HttpMethod, CustomHttpRoute, PluginHttpRouteDefinition, PluginWebSocketHandler, Awaitable } from "../types";
 interface ServerInstance {
     name: string;
     port: number;
@@ -63,7 +63,7 @@ declare class HttpServerManager extends EventEmitter {
     };
     private getCustomRoutePathFromRoot;
     private removeCustomRoute;
-    registerCustomWebSocketListener(pluginName: string, handler: CustomWebSocketHandler["handler"]): boolean;
+    registerCustomWebSocketListener(pluginName: string, handler: PluginWebSocketHandler["handler"]): boolean;
     unregisterCustomWebSocketListener(pluginName: string): boolean;
 }
 declare const manager: HttpServerManager;

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

@@ -1,11 +1,12 @@
 import { EventEmitter } from "events";
 import http from "http";
-import type { CustomWebSocketHandler, WidgetOverlayEvent } from "../types";
+import type { PluginWebSocketHandler, WidgetOverlayEvent, OverlayRequestWebSocketHandler } from "../types";
 declare class WebSocketServerManager extends EventEmitter {
     private logger;
     overlayHasClients: boolean;
     private server;
-    private customHandlers;
+    private pluginHandlers;
+    private overlayRequestHandlers;
     constructor();
     createServer(httpServer: http.Server): void;
     sendToOverlay(eventName: string, meta?: Record<string, unknown>, overlayInstance?: string): void;
@@ -15,8 +16,9 @@ declare class WebSocketServerManager extends EventEmitter {
     triggerEvent(eventType: string, payload: unknown): void;
     reportClientsToFrontend(isDefaultServerStarted: boolean): void;
     getNumberOfOverlayClients(): number;
-    registerCustomWebSocketListener(pluginName: string, handler: CustomWebSocketHandler["handler"]): boolean;
+    registerCustomWebSocketListener(pluginName: string, handler: PluginWebSocketHandler["handler"]): boolean;
     unregisterCustomWebSocketListener(pluginName: string): boolean;
+    registerOverlayRequestHandler<TData extends Record<string, unknown> = Record<string, unknown>, TResponse = unknown>(handler: OverlayRequestWebSocketHandler<TData, TResponse>): boolean;
 }
 declare const manager: WebSocketServerManager;
 export { manager as WebSocketServerManager };

package/types/events.d.ts

@@ -53,6 +53,15 @@ export type EventFilterData = {
     mode: "inclusive" | "exclusive";
     filters: FilterSettings[];
 };
+export type AdditionalFilterEvent = {
+    filterId: string;
+    eventSourceId: string;
+    eventId: string;
+};
+export type PluginAdditionalFilterEvents = {
+    filterId: string;
+    events: Array<EventSourceAndId>;
+};
 export type EventSettings = {
     id: string;
     type: string;

package/types/overlay-widgets.d.ts

@@ -276,6 +276,7 @@ export interface IOverlayWidgetEventUtils {
     stylesToString(styles: Record<string, string | number | undefined>): string;
     getFontOptionsStyles(fontOptions?: FontOptions): Record<string, string | number | undefined>;
     sendMessageToFirebot(messageName: string, messageData?: unknown): void;
+    invokeFirebotRequest<TData extends Record<string, unknown> = Record<string, unknown>, TResponse = unknown>(requestName: string, requestData?: TData): Promise<TResponse>;
 }
 export interface IOverlayWidgetInitUtils {
     getWidgetContainerElements(): NodeListOf<HTMLElement>;

package/types/parameters.d.ts

@@ -26,6 +26,7 @@ export type BaseParameter = {
         pattern?: string;
     };
     default?: unknown;
+    allowReplaceVariables?: boolean;
 };
 export type StringParameter = BaseParameter & {
     type: "string";

package/types/plugin-api.d.ts

@@ -10,58 +10,96 @@ import type { ReplaceVariable, VariableConfig } from "./variables";
 import type { FilterConfig, PresetFilterConfig, TextFilterConfig } from "../backend/events/filters/filter-factory";
 import type { FirebotViewer } from "./viewers";
 import type { Currency } from "./currency";
+export interface Accounts {
+    /** Streamer account information */
+    streamer: FirebotAccount;
+    /** Bot account information. May be null if user has not logged in with a bot account. */
+    bot: FirebotAccount;
+}
 export type PluginLogMethod = (message: string, ...meta: unknown[]) => void;
 export interface PluginLoggerApi {
+    /** Log a message at the debug log level. These may not appear in log files if the user has not enabled debug logging. */
     debug: PluginLogMethod;
+    /** Log a message at the info log level */
     info: PluginLogMethod;
+    /** Log a message at the warn log level */
     warn: PluginLogMethod;
+    /** Log a message at the error log level */
     error: PluginLogMethod;
 }
-export interface PluginWebhooksApi {
-    /** Look up a webhook by name. */
-    get(name: string): PluginWebhook | null;
-    /** All webhooks owned by this plugin. */
-    list(): PluginWebhook[];
-    /** Public URL for a webhook by name, or null if not found. */
-    getUrl(name: string): string | null;
+export interface PluginSettingsApi {
+    /**
+     * 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];
 }
-/**
- * Simple per-plugin storage scoped to the plugin's data directory.
- * Provides helpers for storing/loading JSON values
- * plus generic file read/write for anything else.
- */
 export interface PluginStorageApi {
     /** Absolute path to this plugin'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.
+     * Save a value as JSON under the given key. The key becomes the filename with a `.json` extension.
+     * @param key The name of the key to store
+     * @param value The value to store
      */
+    setJson(key: string, value: unknown): Promise<void>;
+    /**
+     * Load a JSON value previously saved with {@linkcode setJson}
+     * @param key The name of the key to get
+     * @returns A `Promise` with either the data of type `T` or `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. */
+    /**
+     * Delete the JSON value stored under the given key. No-op if missing.
+     * @param key The name of the key to delete
+     */
     deleteJson(key: string): Promise<void>;
-    /** Check whether a file exists in the data directory. */
+    /**
+     * Check whether a file exists in the data directory.
+     * @param name Name of the file to check
+     * @returns A `Promise<boolean>` indicating if the file exists
+     */
     fileExists(name: string): Promise<boolean>;
-    /** Read a file's raw bytes. Returns `null` if it doesn't exist. */
+    /**
+     * Read a file's raw bytes
+     * @param name Name of the file to read
+     * @returns A `Promise` with either a `Buffer` containing the file's contents, or `null` if the file doesn't exist
+     */
     readFile(name: string): Promise<Buffer | null>;
-    /** Read a file as text. Returns `null` if it doesn't exist. */
+    /**
+     * Read a file as text
+     * @param name Name of the file to read
+     * @param encoding Encoding to use when reading the file
+     * @returns A `Promise` with either a `string` containing the file's contents, or `null` if the file doesn't exist
+     */
     readTextFile(name: string, encoding?: BufferEncoding): Promise<string | null>;
-    /** Write contents to a file, creating any missing parent directories. */
+    /**
+     * Write contents to a file, creating any missing parent directories
+     * @param name Name of the file to write
+     * @param contents Data to store in the file
+     */
     writeFile(name: string, contents: string | Buffer | Uint8Array): Promise<void>;
-    /** Delete a file. No-op if it doesn't exist. */
+    /**
+     * Delete a file. No-op if it doesn't exist.
+     * @param name Name of the file to delete
+     */
     deleteFile(name: string): Promise<void>;
 }
 export type PluginEventHandler = (event: TriggeredEvent) => void;
 export interface PluginEventsApi {
     /**
-     * Subscribe to all Firebot events as they trigger. Returns an `unsubscribe`
-     * function.
+     * Subscribe to all Firebot events as they trigger
+     * @param hander Function to execute when an event is triggered
+     * @returns An `unsubscribe` function
      */
     onTriggered(handler: PluginEventHandler): () => void;
     /**
-     * Manually trigger a Firebot event.
+     * Manually trigger a Firebot event
+     * @param sourceId Event source ID
+     * @param eventId Event ID
+     * @param meta (Optional) Any metadata to include with the event
      */
     trigger(sourceId: string, eventId: string, meta?: Record<string, unknown>): Promise<void>;
 }
@@ -70,113 +108,22 @@ export interface PluginEffectsApi {
      * 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).
+     * @param context An object containing the context of the effects to run,
+     * including any trigger data and effect outputs.
      */
     processEffects(context: RunEffectsContext): Promise<unknown>;
 }
-export interface PluginTwitchApi {
-    /** 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 PluginParametersApi {
-    getAll<T extends Record<string, unknown> = Record<string, unknown>>(): T;
-}
-export interface PluginNotificationsApi {
-    /**
-     * 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 plugin's notifications by id. */
-    get(id: string): Notification | null;
-    /** All notifications owned by this plugin. */
-    getAll(): Notification[];
-    /** Delete one of this plugin's notifications by id. */
-    delete(id: string): void;
-    /** Delete all of this plugin's notifications. */
-    clearAll(): void;
-}
-export interface PluginFrontendCommunicatorApi {
-    /** 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>;
-}
-export interface PluginMessageEvent<TPayload = unknown> {
-    /** The pluginId of the plugin that sent the message. */
-    sender: string;
-    /** The provided payload. */
-    payload: TPayload;
-}
-/**
- * Plugin-to-plugin messaging. Supports both fire-and-forget (`emit`/`on`/`off`)
- * and request/response (`invoke`/`handle`) messaging over a shared event bus,
- * based on Electron's IPC
- */
-export interface ScopedIpc {
-    /** Broadcast a message on a channel. */
-    emit(channel: string, data: unknown): void;
-    /**
-     * Listen for messages on a channel.
-     * Returns an `unsubscribe` function.
-     */
-    on<TPayload = unknown>(channel: string, callback: (event: PluginMessageEvent<TPayload>) => void): () => void;
-    /** Remove a previously registered `on` listener. */
-    off(channel: string, callback: (...args: never[]) => void): void;
-    /**
-     * Send a request on a channel and await a response. Rejects if
-     * no handler responds within a 10s timeout or if the handler throws.
-     */
-    invoke<TRequestPayload = unknown, TResponseData = unknown>(channel: string, data?: TRequestPayload): Promise<TResponseData>;
-    /**
-     * Register the handler for a request channel.
-     */
-    handle<TRequestPayload = unknown, TResponseData = unknown>(channel: string, handlerFn: (payload: TRequestPayload, sender: string) => Promise<TResponseData> | TResponseData): void;
-}
-export interface PluginSettingsApi {
-    /**
-     * 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];
-}
-export interface PluginPluginsApi {
-    /**
-     * Get a list of currently installed plugins installed by the user
-     */
-    getInstalledPlugins(): Promise<Array<InstalledPlugin>>;
-}
-export interface Accounts {
-    streamer: FirebotAccount;
-    bot: FirebotAccount;
-}
-export interface PluginWebServerApi {
-    /**
-     * Send a custom event over the internal Firebot WebSocket server
-     * @param name Name of the event to send. Full event name will be `custom-event:{name}`
-     * @param data Any optional data you would like to send with the event
-     */
-    sendWebSocketEvent(name: string, data?: unknown): any;
-}
 export interface PluginViewersApi {
     /**
-     * Retrieve a Firebot user from the viewer database via their Twitch user ID.
-     * Returns `undefined` if the viewer isn't in the database, or the viewer database is disabled.
+     * Retrieve a Firebot user from the viewer database via their Twitch user ID
      * @param userId The viewer's Twitch user ID
+     * @returns A {@linkcode FirebotViewer} with the specified user ID, or `undefined` if the viewer isn't in the database or the viewer database is disabled
      */
     getViewerByUserId(userId: string): Promise<FirebotViewer>;
     /**
-     * Retrieve a Firebot user from the viewer database via their Twitch username.
-     * Returns `undefined` if the viewer isn't in the database, or the viewer database is disabled.
+     * Retrieve a Firebot user from the viewer database via their Twitch username
      * @param username The viewer's Twitch username
+     * @returns A {@linkcode FirebotViewer} with the specified username, or `undefined` if the viewer isn't in the database or the viewer database is disabled
      */
     getViewerByUsername(username: string): Promise<FirebotViewer>;
     /**
@@ -184,6 +131,7 @@ export interface PluginViewersApi {
      * @param userId The viewer's Twitch user ID
      * @param key Key of the metadata value to get
      * @param propertyPath (Optional) Dot-notated property path
+     * @returns A `Promise` with the value, or `null` if it doesn't exist
      */
     getViewerMetadataValue(userId: string, key: string, propertyPath: string): Promise<unknown>;
     /**
@@ -204,91 +152,277 @@ export interface PluginViewersApi {
 export interface PluginCurrencyApi {
     /**
      * Get an array of all currencies
+     * @returns An array of {@linkcode Currency}
      */
     getAllCurrencies(): Array<Currency>;
     /**
      * Get a specific currency by its ID
-     * @param id ID of the currency
+     * @param id ID of the currency to get
+     * @returns The {@linkcode Currency} with the given ID, or `null` if it doesn't exist
      */
     getCurrencyById(id: string): Currency;
     /**
      * Get a specific currency by its name
-     * @param name Name of the currency
+     * @param name Name of the currency to get
+     * @returns The {@linkcode Currency} with the given name, or `null` if it doesn't exist
      */
     getCurrencyByName(name: string): Currency;
     /**
      * Get the amount of a viewer's currency
      * @param userId The viewer's Twitch user ID
-     * @param currencyId The ID of the currency
+     * @param currencyId The ID of the currency to get
+     * @returns A `Promise` with the total of the specified currency the viewer currently has
      */
     getViewerCurrency(userId: string, currencyId: string): Promise<number>;
     /**
      * Add to or subtract from a viewer's currency
      * @param userId The viewer's Twitch user ID
-     * @param currencyId The ID of the currency
+     * @param currencyId The ID of the currency to adjust
      * @param amount An amount to add to the specified currency for the viewer. Negative values will subtract that amount.
+     * @returns A `Promise` indicating if the adjustment to the viewer's currency was successful
      */
     addOrSubtractViewerCurrency(userId: string, currencyId: string, amount: number): Promise<boolean>;
     /**
      * Set a viewer's currency to a specific amount
      * @param userId The viewer's Twitch user ID
-     * @param currencyId The ID of the currency
+     * @param currencyId The ID of the currency to set
      * @param amount The total amount of the specified currency the viewer should have
+     * @returns A `Promise` indicating if setting the viewer's currency was successful
      */
     setViewerCurrency(userId: string, currencyId: string, amount: number): Promise<boolean>;
     /**
-     * Get an array of viewers with a specific currency, sorted by highest amount first
+     * Get an array of viewers with the highest amounts of a specific currency
      * @param currencyId The ID of the currency
      * @param count The total number of viewers to retrieve
+     * @returns A `Promise` with an array of {@linkcode FirebotViewer} representing the
+     * viewers that possess the specified currency, sorted by highest amount first
      */
     getCurrencyLeaderboard(currencyId: string, count: number): Promise<Array<FirebotViewer>>;
 }
+export interface PluginTwitchApi {
+    /** The full Twitch API surface. See {@linkcode TwitchApi}. */
+    api: typeof TwitchApi;
+}
+export interface PluginParametersApi {
+    /**
+     * Get all parameter values for this plugin
+     * @returns A `Record<string, unknown>` containing the parameter names and their values
+     */
+    getAll<T extends Record<string, unknown> = Record<string, unknown>>(): T;
+}
+export interface PluginFrontendCommunicatorApi {
+    /**
+     * Send a synchronous event to the frontend
+     * @param eventName Name of the event to send
+     * @param (Optional) Any data to send with the event
+     */
+    send<ExpectedArg = unknown>(eventName: string, data?: ExpectedArg): void;
+    /**
+     * Send an asynchronous event to the frontend and await the reply it sends
+     * back
+     * @param eventName Name of the event to send
+     * @param (Optional) Any data to send with the event
+     * @returns A `Promise` with any response data received
+     */
+    fireEventAsync<ReturnPayload = void, ExpectedArg = unknown>(eventName: string, data?: ExpectedArg): Promise<ReturnPayload>;
+}
+export interface PluginMessageEvent<TPayload = unknown> {
+    /** The pluginId of the plugin that sent the message */
+    sender: string;
+    /** The provided payload */
+    payload: TPayload;
+}
+export interface ScopedIpc {
+    /**
+     * Broadcast a message on a channel
+     * @param channel Name of the channel to send on
+     * @param data Data to send with the message
+     */
+    emit(channel: string, data: unknown): void;
+    /**
+     * Listen for messages on a channel
+     * @param channel Name of the channel to listen on
+     * @param callback A function that will get executed when a message is received
+     * @returns An `unsubscribe` function
+     */
+    on<TPayload = unknown>(channel: string, callback: (event: PluginMessageEvent<TPayload>) => void): () => void;
+    /**
+     * Remove a previously registered {@linkcode on} listener
+     * @param channel Name of the channel to stop listening on
+     * @param callback The function that was used during registration
+     */
+    off(channel: string, callback: (...args: never[]) => void): void;
+    /**
+     * Send a request on a channel and await a response. Rejects if
+     * no handler responds within a 10s timeout or if the handler throws.
+     * @param channel Name of the channel to invoke on
+     * @param data (Optional) Any data to send along with the request
+     * @returns A `Promise` with any response data received
+     */
+    invoke<TRequestPayload = unknown, TResponseData = unknown>(channel: string, data?: TRequestPayload): Promise<TResponseData>;
+    /**
+     * Register the handler for a request channel
+     * @param channel Name of the channel to listen on
+     * @param handlerFn A function that is executed when a request
+     * is invoked on the specified channel using {@linkcode invoke}
+     */
+    handle<TRequestPayload = unknown, TResponseData = unknown>(channel: string, handlerFn: (payload: TRequestPayload, sender: string) => Promise<TResponseData> | TResponseData): void;
+}
+export interface PluginNotificationsApi {
+    /**
+     * Create a new notification
+     * @param notification The notification to add
+     * @param permanentlySave (Optional) Set as `true` to persist the notification across Firebot restarts
+     * @returns The {@linkcode Notification} that was created
+     */
+    add(notification: Pick<Notification, "title" | "message" | "type" | "metadata">, permanentlySave?: boolean): Notification;
+    /**
+     * Look up one of this plugin's notifications by ID
+     * @param id ID of the notification to retrieve
+     * @returns The {@linkcode Notification} with the given ID, or `null` if it doesn't exist
+     */
+    get(id: string): Notification | null;
+    /**
+     * All notifications owned by this plugin
+     * @returns An array of {@linkcode Notification}
+     */
+    getAll(): Array<Notification>;
+    /**
+     * Delete one of this plugin's notifications by ID
+     * @param id ID of the notification to delete
+     */
+    delete(id: string): void;
+    /** Delete all of this plugin's notifications */
+    clearAll(): void;
+}
+export interface PluginPluginsApi {
+    /**
+     * Get a list of plugins currently installed by the user
+     * @returns A `Promise` with an array of {@linkcode InstalledPlugin} objects
+     */
+    getInstalledPlugins(): Promise<Array<InstalledPlugin>>;
+}
+export interface PluginWebServerApi {
+    /**
+     * Send a custom event over the internal Firebot WebSocket server
+     * @param name Name of the event to send. Full event name will be `custom-event:{name}`
+     * @param data (Optional) Any data you would like to send with the event
+     */
+    sendWebSocketEvent(name: string, data?: unknown): void;
+    /**
+     * Create a resource token for a file to be retrieved via the internal HTTP server (e.g. in an overlay).
+     * The URL format for retrieval is: `http://localhost:7472/resource/{token}`
+     * @param path Full file path of the resource
+     * @param ttl (Optional) Time (in seconds) to retain the resource token once it is retrieved the first time.
+     * Setting this to `null`/`undefined` will retain the token until Firebot exits.
+     * @returns A token representing the resource
+     */
+    createResourceToken(path: string, ttl?: number): string;
+}
+export interface PluginWebhooksApi {
+    /**
+     * Look up a webhook by name
+     * @param name Name of the webhook
+     * @return The {@linkcode PluginWebhook} with the given name, or `null` if it doesn't exist
+     */
+    get(name: string): PluginWebhook | null;
+    /**
+     * Get all webhooks owned by this plugin
+     * @returns An array of {@linkcode PluginWebhook}
+     */
+    list(): Array<PluginWebhook>;
+    /**
+     * Get the public URL for a webhook by name
+     * @param name Name of the webhook
+     * @returns The webhook's URL, or `null` if it doesn't exist
+     */
+    getUrl(name: string): string | null;
+}
 export interface PluginVariableFactoryApi {
+    /**
+     * Create a basic replace variable based on an event metadata value
+     * @param config Configuration data for the new variable
+     * @returns A {@linkcode ReplaceVariable} based on the specified config data
+     */
     createEventDataVariable(config: VariableConfig): ReplaceVariable;
 }
 export interface PluginEventFilterFactoryApi {
+    /**
+     * Create a basic event filter based on a text value
+     * @param config Configuration data for the new filter
+     * @returns An {@linkcode EventFilter} based on the specified config data
+     */
     createTextFilter(config: TextFilterConfig): EventFilter;
+    /**
+     * Create a basic event filter based on a numeric value
+     * @param config Configuration data for the new filter
+     * @returns An {@linkcode EventFilter} based on the specified config data
+     */
     createNumberFilter(config: FilterConfig): EventFilter;
+    /**
+     * Create a basic event filter based on either a text or numeric value
+     * @param config Configuration data for the new filter
+     * @returns An {@linkcode EventFilter} based on the specified config data
+     */
     createTextOrNumberFilter(config: TextFilterConfig): EventFilter;
+    /**
+     * Create a basic event filter based on a list of preset values
+     * @param config Configuration data for the new filter
+     * @returns An {@linkcode EventFilter} based on the specified config data
+     */
     createPresetFilter(config: PresetFilterConfig): EventFilter;
 }
 export interface FirebotPluginApi {
-    /** Running Firebot version, e.g. `"5.67.0"`. */
+    /** Running Firebot version, e.g. `"5.67.0"` */
     version: string;
-    /** The streamer and bot accounts currently in use. */
+    /** The user's streamer and bot accounts currently in use */
     accounts: Accounts;
-    /** Scoped logger. */
+    /** A scoped logger */
     logger: PluginLoggerApi;
-    /** Access to Firebot settings. */
+    /** Access to Firebot settings */
     settings: PluginSettingsApi;
-    /** Webhooks owned by this plugin. */
-    webhooks: PluginWebhooksApi;
-    /** Simple persistent storage rooted at this plugin's data directory. */
+    /**
+     * Simple per-plugin storage scoped to the plugin's data directory.
+     * Provides helpers for storing/loading JSON values
+     * plus generic file read/write for anything else.
+     */
     storage: PluginStorageApi;
-    /** Subscribe to and trigger Firebot events + register event sources. */
+    /** Subscribe to and trigger Firebot events */
     events: PluginEventsApi;
-    /** Run effect lists. */
+    /** Run effect lists */
     effects: PluginEffectsApi;
     /** Access to the viewer database, including viewer metadata */
     viewers: PluginViewersApi;
     /** Access to currencies, including viewer currency amounts and leaderboards */
     currency: PluginCurrencyApi;
-    /** Access to Firebot's Twitch API wrappers (Helix, chat, auth, etc). */
+    /** Access to Firebot's Twitch API wrappers (Helix, chat, auth, etc) */
     twitch: PluginTwitchApi;
-    /** This plugin's saved parameter values. */
+    /**
+     * Access to this plugin's saved parameter values (the settings configured by
+     * the user)
+     */
     parameters: PluginParametersApi;
-    /** Two-way messaging between the plugin and the frontend. */
+    /**
+     * Two-way messaging between the plugin and the Firebot frontend, including
+     * UI Extensions
+     */
     frontendCommunicator: PluginFrontendCommunicatorApi;
-    /** Plugin-to-plugin messaging */
+    /**
+     * Plugin-to-plugin messaging. Supports both fire-and-forget (`emit`/`on`/`off`)
+     * and request/response (`invoke`/`handle`) messaging over a shared event bus,
+     * based on Electron's IPC.
+     */
     messaging: ScopedIpc;
-    /** Notifications owned by this plugin. */
+    /** In-app user notifications owned by this plugin */
     notifications: PluginNotificationsApi;
-    /** Access to installed plugins. */
+    /** Access to installed plugins */
     plugins: PluginPluginsApi;
-    /** Firebot internal web server functions. */
+    /** Firebot internal web server functions */
     webServer: PluginWebServerApi;
-    /** Factory for creating variables based on event data. */
+    /** Webhooks owned by this plugin */
+    webhooks: PluginWebhooksApi;
+    /** Factory functions for creating basic replace variables */
     variableFactory: PluginVariableFactoryApi;
-    /** Factory for creating event filters. */
+    /** Factory functions for creating basic event filters */
     eventFilterFactory: PluginEventFilterFactoryApi;
 }

package/types/plugins.d.ts

@@ -2,7 +2,7 @@ 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 { EventFilter, EventSource, PluginAdditionalFilterEvents } from "./events";
 import type { SystemCommand } from "./commands";
 import type { RestrictionType } from "./restrictions";
 import type { FirebotParams, FirebotParameterArray } from "./parameters";
@@ -11,7 +11,7 @@ import type { Integration } from "./integrations";
 import type { FrontendListener, UIExtension } from "./ui-extensions";
 import type { OverlayWidgetType } from "./overlay-widgets";
 import type { PluginHttpRouteDefinition } from "./http-server";
-import type { CustomWebSocketHandler } from "./websocket";
+import type { PluginWebSocketHandler } from "./websocket";
 import type { PluginWebhooks } from "./webhooks";
 import { ConditionType } from "./conditions";
 type NoResult = Awaitable<void>;
@@ -96,9 +96,21 @@ export interface ManifestFirebotVersion {
     patch?: number;
 }
 export interface Manifest {
+    /**
+     * Name of the plugin
+     */
     name: string;
+    /**
+     * Version of the plugin
+     */
     version: string;
+    /**
+     * Author of the plugin
+     */
     author: string;
+    /**
+     * Description of the plugin
+     */
     description: string | ManifestDescription;
     /**
      * An array of strings that describe or categorize your plugin
@@ -109,8 +121,8 @@ export interface Manifest {
      */
     repo?: string;
     /**
-     * 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.
+     * 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;
     /**
@@ -118,7 +130,13 @@ export interface Manifest {
      * If the repo is on GitHub and support is not specified, it will default to the GitHub issues URL.
      */
     support?: string;
+    /**
+     * The lowest Firebot version this plugin is compatible with
+     */
     minimumFirebotVersion?: ManifestFirebotVersion;
+    /**
+     * The highest Firebot version this plugin is compatible with
+     */
     maximumFirebotVersion?: ManifestFirebotVersion;
     /**
      * The icon to be displayed for the plugin.
@@ -126,7 +144,13 @@ export interface Manifest {
     icon?: PluginIcon;
 }
 export interface PluginBase<Params extends FirebotParams = FirebotParams> {
+    /**
+     * Basic information about the plugin
+     */
     manifest: Manifest;
+    /**
+     * Defines the user-specified parameters for this plugin
+     */
     parametersSchema?: FirebotParameterArray<Params>;
 }
 export interface Plugin<Params extends FirebotParams = FirebotParams> extends PluginBase<Params> {
@@ -151,10 +175,11 @@ export interface Plugin<Params extends FirebotParams = FirebotParams> extends Pl
         uiExtensions?: DynamicArray<UIExtension>;
         overlayWidgets?: DynamicArray<OverlayWidgetType<any, any>>;
         httpRoutes?: DynamicObject<PluginHttpRouteDefinition>;
-        websocketListener?: DynamicObject<CustomWebSocketHandler>;
+        websocketListener?: DynamicObject<PluginWebSocketHandler>;
         webhooks?: DynamicObject<PluginWebhooks>;
         additionalEffectEvents?: DynamicArray<PluginAdditionalEffectEvents>;
         additionalVariableEvents?: DynamicArray<PluginAdditionalVariableEvents>;
+        additionalFilterEvents?: DynamicArray<PluginAdditionalFilterEvents>;
     };
     /** Called when the plugin is loaded */
     onLoad?: (context: PluginContext<Params>, isInstalling?: boolean) => NoResult;

package/types/websocket.d.ts

@@ -23,10 +23,21 @@ export interface InvokePluginMessage extends InvokeMessage {
     name: "plugin";
     pluginName: string;
 }
-export interface CustomWebSocketHandler {
+export interface PluginWebSocketHandler {
     pluginName: string;
     handler: (data: unknown) => Awaitable<void>;
 }
+export interface InvokeOverlayRequestMessage extends InvokeMessage {
+    name: "overlay-request";
+    data: {
+        name: string;
+        data?: Record<string, unknown>;
+    };
+}
+export interface OverlayRequestWebSocketHandler<TData extends Record<string, unknown> = Record<string, unknown>, TResponse = unknown> {
+    name: string;
+    handler: (data: TData) => Awaitable<TResponse>;
+}
 export type OverlayConnectedData = {
     instanceName: string;
 };