@crowbartools/firebot-types 5.67.0-alpha1

package/types/parameters.d.ts

@@ -0,0 +1,414 @@
+import type { EffectList } from "./effects";
+import type { Animation } from "./overlay-widgets";
+
+export type BaseParameter = {
+    /**
+     * The title of the parameter
+     * Supports markdown
+     */
+    title: string;
+    /**
+     * The description of the parameter
+     * Supports markdown
+     */
+    description?: string;
+    /**
+     * @deprecated use `title` and `description` instead
+     */
+    secondaryDescription?: string;
+    /**
+     * Shown under the parameter as muted text
+     * Supports markdown
+     */
+    tip?: string;
+    showBottomHr?: boolean;
+    validation?: {
+        required?: boolean;
+        pattern?: string;
+    };
+    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;
+    default?: number;
+    validation?: {
+        min?: number;
+        max?: number;
+    };
+};
+
+export type DateTimeParameter = BaseParameter & {
+    type: "date-time";
+    default?: string;
+    validation?: {
+        futureOnly?: boolean;
+    };
+};
+
+export type EnumParameter<G = string | number> = BaseParameter & {
+    type: "enum";
+    options: Array<G>;
+    default: G | undefined;
+    searchable?: boolean;
+    /**
+     * Only used if `searchable` is true
+     */
+    placeholder?: string;
+};
+
+export type FilepathParameter = BaseParameter & {
+    type: "filepath";
+    fileOptions?: {
+        directoryOnly: boolean;
+        filters: Array<{
+            name: string;
+            extensions: string[];
+        }>;
+        title: string;
+        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[];
+    settings: {
+        useTextArea: boolean;
+        sortable: boolean;
+        addLabel: string;
+        editLabel: string;
+        noneAddedText: string;
+    };
+};
+
+export type MultiselectParameter<
+    T extends string | number = string | number
+> = BaseParameter & {
+    type: "multiselect";
+    default?: T[];
+    settings: {
+        options: Array<{
+            id: T;
+            name: string;
+        }>;
+    };
+};
+
+export type RolePercentageParameterValue = {
+    basePercent: number;
+    roles: Array<{
+        roleId: string;
+        percent: number;
+    }>;
+};
+
+export type RolePercentagesParameter = BaseParameter & {
+    type: "role-percentages";
+    default?: RolePercentageParameterValue;
+};
+
+export type RoleNumberParameterValue = {
+    base: number;
+    roles: Array<{
+        roleId: string;
+        value: number;
+    }>;
+};
+
+export type RoleNumberParameter = BaseParameter & {
+    type: "role-numbers";
+    default?: RoleNumberParameterValue;
+    settings: {
+        defaultBase: number;
+        defaultOther: number;
+        min?: number;
+        max?: number;
+    };
+};
+
+export type ButtonParameter = BaseParameter & {
+    type: "button";
+    /**
+     * The event name that will be sent to the backend when the button is clicked
+     */
+    backendEventName: string;
+    buttonText: string;
+    size?: "extraSmall" | "small" | "large";
+    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";
+};
+
+export type HexColorParameter = BaseParameter & {
+    type: "hexcolor";
+    /**
+     * Default hex color value, e.g. #FF0000
+     */
+    default: string;
+    allowAlpha?: boolean;
+};
+
+export type FontNameParameter = BaseParameter & {
+    type: "font-name";
+    /**
+     * Default font name value, e.g. 'Arial'
+     */
+    default?: string;
+};
+
+export type FontOptions = {
+    family: string;
+    size: number;
+    weight: 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900;
+    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;
+    options: Array<{
+        value: V;
+        label: string;
+        description?: string;
+        iconClass?: string;
+    }>;
+    settings?: {
+        gridColumns?: number;
+    };
+};
+
+export type CodeMirrorParameter = BaseParameter & {
+    type: "codemirror";
+    default?: string;
+    settings?: {
+        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;
+
+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] };
+};
+
+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>> = {
+    title: string;
+    /**
+     * Used to order categories in the UI.
+     */
+    sortRank?: number;
+    settings: ParametersConfig<ParamConfig>;
+};
+
+export type FirebotParams = Record<string, Record<string, unknown>>;
+
+export type FirebotParameterCategories<Config extends FirebotParams> = {
+    [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]>>;
+// }

package/types/plugins.d.ts

@@ -0,0 +1,201 @@
+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";
+
+type NoResult = Awaitable<void>;
+
+type GenericParameters = Record<string, unknown>;
+
+export type InstalledPluginConfig<Params extends GenericParameters = GenericParameters> = {
+    id: string;
+    fileName: string;
+    enabled?: boolean;
+    legacyImport?: boolean;
+    parameters: Params;
+};
+
+export type ScriptContext = {
+    trigger?: Trigger;
+    parameters: Record<string, unknown>;
+};
+
+type DynamicArray<T> = Array<T | ((context: ScriptContext) => Awaitable<T>)>;
+
+export type ScriptType = "script" | "plugin";
+
+interface ManifestDescription {
+    short: string;
+    long?: string;
+}
+
+interface ManifestFirebotVersion {
+    major: number;
+    minor?: number;
+    patch?: number;
+}
+
+export interface Manifest {
+    name: string;
+    version: string;
+    author: string;
+    description: string | ManifestDescription;
+
+    keywords?: string[];
+
+    repo?: string;
+
+    // Note: autofilled if repo is assumed github and not specified
+    website?: string;
+    report?: string;
+    source?: string;
+
+    minimumFirebotVersion?: ManifestFirebotVersion;
+    maximumFirebotVersion?: ManifestFirebotVersion;
+
+    icon?: `fa-${string}`;
+    color?: string;
+
+    type: ScriptType;
+}
+
+type EffectScriptResult = {
+    success: boolean;
+    errorMessage?: string;
+    effects?: EffectList | Array<EffectInstance>;
+    onEffectsDone?: () => Awaitable<void>;
+};
+
+
+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, isUninstalling?: boolean) => NoResult;
+}
+
+// Supplants the "Run Script" effect script functionality
+export interface EffectScript<Params extends FirebotParams = FirebotParams> extends ScriptBase<Params> {
+    run: (context: ScriptContext) => 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
+    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>;
+        eventSources?: DynamicArray<EventSource>;
+        variables?: DynamicArray<ReplaceVariable>;
+        // endpoints?: DynamicArray<HttpEndpoint>;
+        integrations?: DynamicArray<Integration>;
+        filters?: DynamicArray<EventFilter>;
+        restrictions?: DynamicArray<RestrictionType>;
+        systemCommands?: DynamicArray<SystemCommand>;
+        games?: DynamicArray<FirebotGame>;
+    };
+
+    // Called when the script is loaded
+    onLoad?: (context: ScriptContext, isInstalling?: boolean) => NoResult;
+
+    // Called when firebot is closing or plugin is disabled / removed
+    onUnload?: (context: ScriptContext, isUninstalling?: boolean) => NoResult;
+
+    // called when the user updates plugin-specific parameters
+    onParameterUpdate?: (context: ScriptContext) => NoResult;
+}
+
+export type ScriptDetails = Pick<ScriptBase, "manifest" | "parametersSchema">;
+
+export type InstalledPlugin = {
+    config: InstalledPluginConfig;
+    details: ScriptDetails;
+};
+
+/* Legacy types */
+
+type LegacyScriptParameters = Record<
+    string,
+    {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        type: any;
+        title?: string;
+        description?: string;
+        secondaryDescription?: string;
+        tip?: string;
+        showBottomHr?: boolean;
+        validation?: {
+            required?: boolean;
+        };
+        value?: unknown;
+        default?: unknown;
+    }
+>;
+
+export type LegacyScriptReturnObject = {
+    success: boolean;
+    errorMessage?: string;
+    effects: unknown[] | { id: string, list: unknown[] };
+    callback?: VoidFunction;
+};
+
+type LegacyRunRequest = {
+    parameters: Record<string, unknown>;
+    modules: Record<string, unknown>;
+    firebot: {
+        accounts: {
+            streamer: unknown;
+            bot: unknown;
+        };
+        settings: {
+            webServerPort: number;
+        };
+        version: string;
+    };
+    trigger: Trigger;
+};
+
+type LegacyCustomScriptManifest = {
+    name: string;
+    description: string;
+    version: string;
+    author: string;
+    website?: string;
+    startupOnly?: boolean;
+    firebotVersion?: "5";
+};
+
+export type LegacyScriptData = {
+    id: string;
+    name: string;
+    scriptName: string;
+    parameters: LegacyScriptParameters;
+};
+
+export type LegacyCustomScript = {
+    getScriptManifest(): Awaitable<LegacyCustomScriptManifest>;
+    getDefaultParameters?: () => LegacyScriptParameters;
+    run(
+        runRequest: LegacyRunRequest
+    ): Awaitable<void | LegacyScriptReturnObject>;
+    parametersUpdated?: (parameters: Record<string, unknown>) => Awaitable<void>;
+    stop?: () => Awaitable<void>;
+};
+
+export type FirebotScriptApi = import("./script-api").FirebotScriptApi;
+export type { ScriptLoggerApi, ScriptWebhooksApi, ScriptWebhook, ScriptWebhookEvent } from "./script-api";

package/types/power-ups.d.ts

@@ -0,0 +1,20 @@
+import type { CustomPowerUp } from "../backend/streaming-platforms/twitch/api/resource/power-ups";
+import type { EffectList } from "./effects";
+
+export type SavedPowerUp = {
+    id: string;
+    twitchData: CustomPowerUp;
+    effects?: EffectList;
+    sortTags?: string[];
+};
+
+export type PowerUpRedemptionMetadata = {
+    username: string;
+    userId: string;
+    userDisplayName: string;
+    messageText: string;
+    powerUpId: string;
+    powerUpImage: string;
+    powerUpName: string;
+    bits: number;
+};

package/types/pronouns.d.ts

@@ -0,0 +1,11 @@
+export type Pronoun = {
+    name: string;
+    subject: string;
+    object: string;
+    singular: boolean;
+};
+
+export type UserPronoun = {
+    primary: string;
+    secondary?: string;
+};

package/types/quick-actions.d.ts

@@ -0,0 +1,18 @@
+import type { EffectList } from "./effects";
+import type { Awaitable } from "./util-types";
+
+export type QuickActionDefinition = {
+    id: string;
+    name: string;
+    type: "system" | "custom";
+    icon: string;
+    presetListId?: string;
+    presetArgValues?: Record<string, unknown>;
+    promptForArgs?: boolean;
+    effectList?: EffectList;
+};
+
+export type SystemQuickAction = {
+    definition: QuickActionDefinition;
+    onTriggerEvent(): Awaitable<void>;
+};

package/types/quotes.d.ts

@@ -0,0 +1,17 @@
+export type QuoteAutoid = {
+    _id: "__autoid__";
+    seq: number;
+};
+
+export type Quote = {
+    _id?: number;
+    createdAt?: string;
+    creator: string;
+    game: string;
+    originator: string;
+    text: string;
+};
+
+export type FormattedQuote = Omit<Quote, "_id"> & {
+    id: number;
+};

package/types/ranks.d.ts

@@ -0,0 +1,23 @@
+export type Rank = {
+    id: string;
+    name: string;
+    value?: number;
+};
+
+export type RankLadder = {
+    id: string;
+    name: string;
+    mode: "manual" | "auto";
+    settings: {
+        trackBy?: "view_time" | "currency" | "metadata";
+        currencyId?: string;
+        metadataKey?: string;
+        viewerRestrictions?: {
+            roleIds?: string[];
+        };
+        announcePromotionsInChat?: boolean;
+        customPromotionMessageTemplate?: string;
+        showBadgeInChat?: boolean;
+    };
+    ranks: Rank[];
+};