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

package/types/parameters.d.ts

@@ -1,6 +1,5 @@
 import type { EffectList } from "./effects";
 import type { Animation } from "./overlay-widgets";
-
 export type BaseParameter = {
     /**
      * The title of the parameter
@@ -28,23 +27,19 @@ export type BaseParameter = {
     };
     default?: unknown;
 };
-
 export type StringParameter = BaseParameter & {
     type: "string";
     useTextArea?: boolean;
     default: string;
 };
-
 export type PasswordParameter = BaseParameter & {
     type: "password";
     default: string;
 };
-
 export type BooleanParameter = BaseParameter & {
     type: "boolean";
     default: boolean;
 };
-
 export type NumberParameter = BaseParameter & {
     type: "number";
     placeholder?: string;
@@ -54,7 +49,6 @@ export type NumberParameter = BaseParameter & {
         max?: number;
     };
 };
-
 export type DateTimeParameter = BaseParameter & {
     type: "date-time";
     default?: string;
@@ -62,7 +56,6 @@ export type DateTimeParameter = BaseParameter & {
         futureOnly?: boolean;
     };
 };
-
 export type EnumParameter<G = string | number> = BaseParameter & {
     type: "enum";
     options: Array<G>;
@@ -73,7 +66,6 @@ export type EnumParameter<G = string | number> = BaseParameter & {
      */
     placeholder?: string;
 };
-
 export type FilepathParameter = BaseParameter & {
     type: "filepath";
     fileOptions?: {
@@ -86,25 +78,20 @@ export type FilepathParameter = BaseParameter & {
         buttonLabel: string;
     };
 };
-
 export type EffectListParameter = BaseParameter & {
     type: "effectlist";
 };
-
 export type DiscordChannelWebhookParameter = BaseParameter & {
     type: "discord-channel-webhooks";
 };
-
 export type CurrencySelectParameter = BaseParameter & {
     type: "currency-select";
     default?: string;
 };
-
 export type ChatterSelectParameter = BaseParameter & {
     type: "chatter-select";
     default?: "Bot" | "Streamer";
 };
-
 export type EditableListParameter = BaseParameter & {
     type: "editable-list";
     default?: string[];
@@ -116,10 +103,7 @@ export type EditableListParameter = BaseParameter & {
         noneAddedText: string;
     };
 };
-
-export type MultiselectParameter<
-    T extends string | number = string | number
-> = BaseParameter & {
+export type MultiselectParameter<T extends string | number = string | number> = BaseParameter & {
     type: "multiselect";
     default?: T[];
     settings: {
@@ -129,7 +113,6 @@ export type MultiselectParameter<
         }>;
     };
 };
-
 export type RolePercentageParameterValue = {
     basePercent: number;
     roles: Array<{
@@ -137,12 +120,10 @@ export type RolePercentageParameterValue = {
         percent: number;
     }>;
 };
-
 export type RolePercentagesParameter = BaseParameter & {
     type: "role-percentages";
     default?: RolePercentageParameterValue;
 };
-
 export type RoleNumberParameterValue = {
     base: number;
     roles: Array<{
@@ -150,7 +131,6 @@ export type RoleNumberParameterValue = {
         value: number;
     }>;
 };
-
 export type RoleNumberParameter = BaseParameter & {
     type: "role-numbers";
     default?: RoleNumberParameterValue;
@@ -161,7 +141,6 @@ export type RoleNumberParameter = BaseParameter & {
         max?: number;
     };
 };
-
 export type ButtonParameter = BaseParameter & {
     type: "button";
     /**
@@ -170,30 +149,10 @@ export type ButtonParameter = BaseParameter & {
     backendEventName: string;
     buttonText: string;
     size?: "extraSmall" | "small" | "large";
-    buttonType?:
-    | "default"
-    | "primary"
-    | "success"
-    | "info"
-    | "warning"
-    | "danger"
-    | "link";
+    buttonType?: "default" | "primary" | "success" | "info" | "warning" | "danger" | "link";
     tooltip?: string;
-    tooltipPlacement?:
-    | "top"
-    | "top-left"
-    | "top-right"
-    | "bottom"
-    | "bottom-left"
-    | "bottom-right"
-    | "left"
-    | "left-top"
-    | "left-bottom"
-    | "right"
-    | "right-top"
-    | "right-bottom";
-};
-
+    tooltipPlacement?: "top" | "top-left" | "top-right" | "bottom" | "bottom-left" | "bottom-right" | "left" | "left-top" | "left-bottom" | "right" | "right-top" | "right-bottom";
+};
 export type HexColorParameter = BaseParameter & {
     type: "hexcolor";
     /**
@@ -202,7 +161,6 @@ export type HexColorParameter = BaseParameter & {
     default: string;
     allowAlpha?: boolean;
 };
-
 export type FontNameParameter = BaseParameter & {
     type: "font-name";
     /**
@@ -210,7 +168,6 @@ export type FontNameParameter = BaseParameter & {
      */
     default?: string;
 };
-
 export type FontOptions = {
     family: string;
     size: number;
@@ -218,14 +175,12 @@ export type FontOptions = {
     italic: boolean;
     color?: string;
 };
-
 export type FontOptionsParameter = BaseParameter & {
     type: "font-options";
     default: FontOptions;
     allowAlpha?: boolean;
     hideColor?: boolean;
 };
-
 export type RadioCardsParameter<V = string> = BaseParameter & {
     type: "radio-cards";
     default?: V;
@@ -239,143 +194,55 @@ export type RadioCardsParameter<V = string> = BaseParameter & {
         gridColumns?: number;
     };
 };
-
 export type CodeMirrorParameter = BaseParameter & {
     type: "codemirror";
     default?: string;
     settings?: {
-        mode: { name: "javascript", json?: boolean } | "htmlmixed" | "css" | { mode: "xml", htmlMode: true };
+        mode: {
+            name: "javascript";
+            json?: boolean;
+        } | "htmlmixed" | "css" | {
+            mode: "xml";
+            htmlMode: true;
+        };
         theme: 'blackboard';
         lineNumbers?: boolean;
         autoRefresh?: boolean;
         showGutter?: boolean;
     };
 };
-
 export type CounterSelectParameter = BaseParameter & {
     type: "counter-select";
     default?: never;
 };
-
 export type SortTagSelectParameter = BaseParameter & {
     type: "sort-tag-select";
     context: string;
     default?: never;
 };
-
 export type AnimationSelectParameter = BaseParameter & {
     type: "animation-select";
     animationType: "enter" | "exit" | "inbetween";
     default?: Animation;
 };
-
 export type UnknownParameter = BaseParameter & {
     [key: string]: unknown;
 };
-
-type FirebotParameter =
-    | StringParameter
-    | PasswordParameter
-    | BooleanParameter
-    | NumberParameter
-    | DateTimeParameter
-    | EnumParameter
-    | EffectListParameter
-    | DiscordChannelWebhookParameter
-    | CurrencySelectParameter
-    | ChatterSelectParameter
-    | EditableListParameter
-    | MultiselectParameter
-    | RolePercentagesParameter
-    | RoleNumberParameter
-    | ButtonParameter
-    | UnknownParameter
-    | HexColorParameter
-    | FontNameParameter
-    | FontOptionsParameter
-    | RadioCardsParameter
-    | CodeMirrorParameter
-    | CounterSelectParameter
-    | SortTagSelectParameter
-    | AnimationSelectParameter;
-
+type FirebotParameter = StringParameter | PasswordParameter | BooleanParameter | NumberParameter | DateTimeParameter | EnumParameter | EffectListParameter | DiscordChannelWebhookParameter | CurrencySelectParameter | ChatterSelectParameter | EditableListParameter | MultiselectParameter | RolePercentagesParameter | RoleNumberParameter | ButtonParameter | UnknownParameter | HexColorParameter | FontNameParameter | FontOptionsParameter | RadioCardsParameter | CodeMirrorParameter | CounterSelectParameter | SortTagSelectParameter | AnimationSelectParameter;
 export type ParametersConfig<P> = {
-    [K in keyof P]: (P[K] extends string
-        ?
-        | StringParameter
-        | PasswordParameter
-        | DateTimeParameter
-        | FilepathParameter
-        | ChatterSelectParameter
-        | CurrencySelectParameter
-        | EnumParameter<string>
-        | HexColorParameter
-        | FontNameParameter
-        | RadioCardsParameter<string>
-        | CodeMirrorParameter
-        | CounterSelectParameter
-        | SortTagSelectParameter
-        : P[K] extends number
-            ? NumberParameter | EnumParameter<number>
-            : P[K] extends boolean
-                ? BooleanParameter | EnumParameter<boolean>
-                : P[K] extends Array<string>
-                    ? MultiselectParameter<string> | EditableListParameter
-                    : P[K] extends Array<number>
-                        ? MultiselectParameter<number>
-                        : P[K] extends void | undefined | null
-                            ? ButtonParameter
-                            : P[K] extends RolePercentageParameterValue
-                                ? RolePercentagesParameter
-                                : P[K] extends RoleNumberParameterValue
-                                    ? RoleNumberParameter
-                                    : P[K] extends EffectList
-                                        ? EffectListParameter
-                                        : P[K] extends FontOptions
-                                            ? FontOptionsParameter
-                                            : P[K] extends Animation
-                                                ? AnimationSelectParameter : FirebotParameter) & { value?: P[K] };
-};
-
+    [K in keyof P]: (P[K] extends string ? StringParameter | PasswordParameter | DateTimeParameter | FilepathParameter | ChatterSelectParameter | CurrencySelectParameter | EnumParameter<string> | HexColorParameter | FontNameParameter | RadioCardsParameter<string> | CodeMirrorParameter | CounterSelectParameter | SortTagSelectParameter : P[K] extends number ? NumberParameter | EnumParameter<number> : P[K] extends boolean ? BooleanParameter | EnumParameter<boolean> : P[K] extends Array<string> ? MultiselectParameter<string> | EditableListParameter : P[K] extends Array<number> ? MultiselectParameter<number> : P[K] extends void | undefined | null ? ButtonParameter : P[K] extends RolePercentageParameterValue ? RolePercentagesParameter : P[K] extends RoleNumberParameterValue ? RoleNumberParameter : P[K] extends EffectList ? EffectListParameter : P[K] extends FontOptions ? FontOptionsParameter : P[K] extends Animation ? AnimationSelectParameter : FirebotParameter) & {
+        value?: P[K];
+    };
+};
 export type ParametersWithNameConfig<P> = {
-    [K in keyof P]: (P[K] extends string
-        ?
-        | StringParameter
-        | PasswordParameter
-        | DateTimeParameter
-        | FilepathParameter
-        | ChatterSelectParameter
-        | CurrencySelectParameter
-        | EnumParameter<string>
-        | HexColorParameter
-        | FontNameParameter
-        | RadioCardsParameter<string>
-        | CodeMirrorParameter
-        | CounterSelectParameter
-        | SortTagSelectParameter
-        : P[K] extends number
-            ? NumberParameter | EnumParameter<number> | RadioCardsParameter<number>
-            : P[K] extends boolean
-                ? BooleanParameter | EnumParameter<boolean> | RadioCardsParameter<boolean>
-                : P[K] extends Array<string>
-                    ? MultiselectParameter<string> | EditableListParameter
-                    : P[K] extends Array<number>
-                        ? MultiselectParameter<number>
-                        : P[K] extends void | undefined | null
-                            ? ButtonParameter
-                            : P[K] extends RolePercentageParameterValue
-                                ? RolePercentagesParameter
-                                : P[K] extends RoleNumberParameterValue
-                                    ? RoleNumberParameter
-                                    : P[K] extends EffectList
-                                        ? EffectListParameter
-                                        : P[K] extends FontOptions
-                                            ? FontOptionsParameter
-                                            : P[K] extends Animation
-                                                ? AnimationSelectParameter : FirebotParameter) & { name: K, showIf?: { [K2 in keyof P]?: P[K2] | Array<P[K2]> } };
-};
-
-type FirebotParamCategory<ParamConfig extends Record<string, unknown>> = {
+    [K in keyof P]: (P[K] extends string ? StringParameter | PasswordParameter | DateTimeParameter | FilepathParameter | ChatterSelectParameter | CurrencySelectParameter | EnumParameter<string> | HexColorParameter | FontNameParameter | RadioCardsParameter<string> | CodeMirrorParameter | CounterSelectParameter | SortTagSelectParameter : P[K] extends number ? NumberParameter | EnumParameter<number> | RadioCardsParameter<number> : P[K] extends boolean ? BooleanParameter | EnumParameter<boolean> | RadioCardsParameter<boolean> : P[K] extends Array<string> ? MultiselectParameter<string> | EditableListParameter : P[K] extends Array<number> ? MultiselectParameter<number> : P[K] extends void | undefined | null ? ButtonParameter : P[K] extends RolePercentageParameterValue ? RolePercentagesParameter : P[K] extends RoleNumberParameterValue ? RoleNumberParameter : P[K] extends EffectList ? EffectListParameter : P[K] extends FontOptions ? FontOptionsParameter : P[K] extends Animation ? AnimationSelectParameter : FirebotParameter) & {
+        name: K;
+        showIf?: {
+            [K2 in keyof P]?: P[K2] | Array<P[K2]>;
+        };
+    };
+};
+export type FirebotParamCategory<ParamConfig extends Record<string, unknown>> = {
     title: string;
     /**
      * Used to order categories in the UI.
@@ -383,32 +250,9 @@ type FirebotParamCategory<ParamConfig extends Record<string, unknown>> = {
     sortRank?: number;
     settings: ParametersConfig<ParamConfig>;
 };
-
 export type FirebotParams = Record<string, unknown>;
-
-export type FirebotParameterCategories<Config extends FirebotParams> = {
+export type FirebotParameterCategories<Config extends Record<string, Record<string, unknown>>> = {
     [Category in keyof Config]: FirebotParamCategory<Config[Category]>;
 };
-
 export type FirebotParameterArray<Config extends Record<string, unknown>> = ParametersWithNameConfig<Config>[keyof Config][];
-
-
-// export type WithValues<Categories extends FirebotParameterCategories> = {
-//     [Category in keyof Categories]: Categories[Category] & {
-//         settings: {
-//             [Setting in keyof Categories[Category]["settings"]]: Categories[Category]["settings"][Setting] & {
-//                 value?: Categories[Category]["settings"][Setting]["default"];
-//             };
-//         };
-//     }
-// };
-
-// type ValidParamKeys<T> = {
-//     [P in keyof T]: Exclude<T[P], undefined> extends void | undefined | null
-//         ? never
-//         : P;
-// }[keyof T];
-
-// export type ResolvedParameters<Config extends FirebotParams> = {
-//     [K in keyof Config]: Pick<Config[K], ValidParamKeys<Config[K]>>;
-// }
+export {};

package/types/plugin-api.d.ts

@@ -0,0 +1,188 @@
+import type { EventFilter, 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";
+import type { PluginWebhook } from "./webhooks";
+import type { ReplaceVariable, VariableConfig } from "./variables";
+import type { FilterConfig, PresetFilterConfig, TextFilterConfig } from "../backend/events/filters/filter-factory";
+export type PluginLogMethod = (message: string, ...meta: unknown[]) => void;
+export interface PluginLoggerApi {
+    debug: PluginLogMethod;
+    info: PluginLogMethod;
+    warn: PluginLogMethod;
+    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;
+}
+/**
+ * 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.
+     */
+    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 PluginEventHandler = (event: TriggeredEvent) => void;
+export interface PluginEventsApi {
+    /**
+     * Subscribe to all Firebot events as they trigger. Returns an `unsubscribe`
+     * function.
+     */
+    onTriggered(handler: PluginEventHandler): () => void;
+    /**
+     * Manually trigger a Firebot event.
+     */
+    trigger(sourceId: string, eventId: string, meta?: Record<string, unknown>): Promise<void>;
+}
+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).
+     */
+    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>;
+    /**
+     * 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 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 {
+    /**
+     * Sends 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 PluginVariableFactoryApi {
+    createEventDataVariable(config: VariableConfig): ReplaceVariable;
+}
+export interface PluginEventFilterFactoryApi {
+    createTextFilter(config: TextFilterConfig): EventFilter;
+    createNumberFilter(config: FilterConfig): EventFilter;
+    createTextOrNumberFilter(config: TextFilterConfig): EventFilter;
+    createPresetFilter(config: PresetFilterConfig): EventFilter;
+}
+export interface FirebotPluginApi {
+    /** Running Firebot version, e.g. `"5.67.0"`. */
+    version: string;
+    /** The streamer and bot accounts currently in use. */
+    accounts: Accounts;
+    /** Scoped logger. */
+    logger: PluginLoggerApi;
+    /** Access to Firebot settings. */
+    settings: PluginSettingsApi;
+    /** Webhooks owned by this plugin. */
+    webhooks: PluginWebhooksApi;
+    /** Simple persistent storage rooted at this plugin's data directory. */
+    storage: PluginStorageApi;
+    /** Subscribe to and trigger Firebot events + register event sources. */
+    events: PluginEventsApi;
+    /** Run effect lists. */
+    effects: PluginEffectsApi;
+    /** Access to Firebot's Twitch API wrappers (Helix, chat, auth, etc). */
+    twitch: PluginTwitchApi;
+    /** This plugin's saved parameter values. */
+    parameters: PluginParametersApi;
+    /** Two-way messaging between the plugin and the frontend. */
+    frontendCommunicator: PluginFrontendCommunicatorApi;
+    /** Notifications owned by this plugin. */
+    notifications: PluginNotificationsApi;
+    /** Access to installed plugins. */
+    plugins: PluginPluginsApi;
+    /** Firebot internal web server functions. */
+    webServer: PluginWebServerApi;
+    /** Factory for creating variables based on event data. */
+    variableFactory: PluginVariableFactoryApi;
+    /** Factory for creating event filters. */
+    eventFilterFactory: PluginEventFilterFactoryApi;
+}