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

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/integrations.d.ts

@@ -43,7 +43,7 @@ export interface IntegrationEvents {
     disconnected: (id: string) => void;
     "settings-update": (id: string, settings: Record<string, any>) => void;
 }
-type LinkData = {
+export type LinkData = {
     accountId: string;
 } | {
     auth: Record<string, unknown>;
@@ -66,4 +66,3 @@ export type IntegrationWithUnknowns = {
     definition: IntegrationDefinition & ObjectOfUnknowns;
     integration: IntegrationController & ObjectOfUnknowns;
 };
-export {};

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

@@ -8,58 +8,98 @@ import type { InstalledPlugin } from "./plugins";
 import type { PluginWebhook } from "./webhooks";
 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>;
 }
@@ -68,144 +108,321 @@ 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 PluginViewersApi {
+    /**
+     * 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
+     * @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>;
+    /**
+     * Get a metadata value for a given user
+     * @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>;
+    /**
+     * Set a metadata value for a given user
+     * @param userId The viewer's Twitch user ID
+     * @param key Key of the metadata value to set
+     * @param value Data to store
+     * @param propertyPath (Optional) Dot-notated property path
+     */
+    setViewerMetadataValue(userId: string, key: string, value: string, propertyPath: string): Promise<void>;
+    /**
+     * Delete a metadata value for a given user
+     * @param userId The viewer's Twitch user ID
+     * @param key Key of the metadata value to delete
+     */
+    deleteViewerMetadataValue(userId: string, key: string): Promise<void>;
+}
+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 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 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 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 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 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 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;
 }
-/**
- * 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.
+     * Get all parameter values for this plugin
+     * @returns A `Record<string, unknown>` containing the parameter names and their values
      */
-    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;
+    getAll<T extends Record<string, unknown> = Record<string, unknown>>(): T;
 }
 export interface PluginFrontendCommunicatorApi {
-    /** Send a synchronous event to the frontend. */
+    /**
+     * 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.
+     * 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. */
+    /** The pluginId of the plugin that sent the message */
     sender: string;
-    /** The provided payload. */
+    /** 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. */
+    /**
+     * 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.
-     * Returns an `unsubscribe` function.
+     * 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 `on` listener. */
+    /**
+     * 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.
+     * 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 PluginSettingsApi {
+export interface PluginNotificationsApi {
     /**
-     * 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
+     * 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
      */
-    getSetting<SettingName extends keyof FirebotSettingsTypes>(settingName: SettingName): FirebotSettingsTypes[SettingName];
+    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 currently installed plugins installed by the user
+     * 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 Accounts {
-    streamer: FirebotAccount;
-    bot: FirebotAccount;
-}
 export interface PluginWebServerApi {
     /**
-     * Sends a custom event over the internal Firebot WebSocket server
+     * 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
+     * @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
      */
-    sendWebSocketEvent(name: string, data?: unknown): any;
+    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 Firebot's Twitch API wrappers (Helix, chat, auth, etc). */
+    /** 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) */
     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;
 }