@crowbartools/firebot-types 5.67.0-alpha4 → 5.67.0-alpha5

package/backend/variables/builtin/utility/index.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("../../../../types").ReplaceVariable[];
+export default _default;

package/backend/variables/builtin/utility/loop-count.d.ts

@@ -0,0 +1,3 @@
+import type { ReplaceVariable } from "../../../../types/variables";
+declare const model: ReplaceVariable;
+export default model;

package/backend/variables/builtin/utility/loop-item.d.ts

@@ -0,0 +1,3 @@
+import type { ReplaceVariable } from "../../../../types/variables";
+declare const model: ReplaceVariable;
+export default model;

package/backend/variables/builtin/utility/overlay-resources-path.d.ts

@@ -0,0 +1,3 @@
+import type { ReplaceVariable } from "../../../../types/variables";
+declare const model: ReplaceVariable;
+export default model;

package/backend/variables/builtin/utility/quick-store.d.ts

@@ -0,0 +1,3 @@
+import type { ReplaceVariable } from "../../../../types/variables";
+declare const model: ReplaceVariable;
+export default model;

package/backend/variables/builtin/utility/random-uuid.d.ts

@@ -0,0 +1,3 @@
+import type { ReplaceVariable } from "../../../../types/variables";
+declare const model: ReplaceVariable;
+export default model;

package/backend/variables/builtin/utility/run-effect.d.ts

@@ -0,0 +1,3 @@
+import type { ReplaceVariable } from "../../../../types/variables";
+declare const model: ReplaceVariable;
+export default model;

package/backend/variables/builtin/utility/video-duration.d.ts

@@ -0,0 +1,3 @@
+import type { ReplaceVariable } from "../../../../types/variables";
+declare const model: ReplaceVariable;
+export default model;

package/backend/variables/macro-manager.d.ts

@@ -0,0 +1,10 @@
+import type { VariableMacro } from "../../types/variable-macros";
+import JsonDbManager from "../database/json-db-manager";
+declare class MacroManager extends JsonDbManager<VariableMacro> {
+    constructor();
+    getMacroByName(name: string): VariableMacro;
+    hasMacro(name: string): boolean;
+    triggerUiRefresh(): void;
+}
+declare const manager: MacroManager;
+export = manager;

package/backend/variables/replace-variable-manager.d.ts

@@ -0,0 +1,44 @@
+import EventEmitter from "events";
+import type { Awaitable, ExpressionishToken, RegisteredVariable, ReplaceVariable, Trigger, TriggerMeta, TriggerType, VariableUsage } from "../../types";
+type Evaluator = {
+    evaluator(trigger: Trigger, ...args: unknown[]): Awaitable<unknown>;
+};
+type TriggerWithId = Omit<Trigger, "metadata"> & {
+    id?: string;
+    metadata?: Record<string, unknown>;
+};
+type VariableError = {
+    message: string;
+    dataField: string;
+    rawText: string;
+    position: number;
+    varname: string;
+    character: string;
+};
+declare class ReplaceVariableManager extends EventEmitter {
+    private registeredVariableHandlers;
+    private variableAndAliasHandlers;
+    private registeredLookupHandlers;
+    additionalVariableEvents: Record<string, Array<{
+        eventSourceId: string;
+        eventId: string;
+    }>>;
+    constructor();
+    private preeval;
+    registerReplaceVariable(variable: ReplaceVariable): void;
+    unregisterReplaceVariable(handle: string): void;
+    getReplaceVariables(): RegisteredVariable[];
+    private getVariablesForEvent;
+    getVariableHandlers(): Map<string, RegisteredVariable>;
+    registerLookupHandler(prefix: string, lookup: (name: string) => Evaluator): void;
+    private generateVariableAndAliasHandlers;
+    populateStringWithTriggerData(string: string, trigger: Trigger, postProcessVariable?: (value: string, token: ExpressionishToken) => string): Promise<string>;
+    evaluateText(input: string, metadata: Record<string, unknown>, trigger: TriggerWithId, onlyValidate?: boolean, postProcessVariable?: (value: string, token: ExpressionishToken) => string): Promise<string>;
+    findAndReplaceVariables(data: Record<string, unknown>, trigger: Trigger): Promise<void>;
+    findAndValidateVariables(data: Record<string, unknown>, trigger: TriggerWithId, errors?: VariableError[]): Promise<VariableError[]>;
+    addEventToVariable(variableHandle: string, eventSourceId: string, eventId: string): void;
+    removeEventFromVariable(variableHandle: string, eventSourceId: string, eventId: string): void;
+    getSuggestionsForVariable(variableHandle: string, triggerType: TriggerType, triggerMeta: TriggerMeta): Awaitable<VariableUsage[]>;
+}
+declare const manager: ReplaceVariableManager;
+export { manager as ReplaceVariableManager };

package/backend/variables/variable-factory.d.ts

@@ -0,0 +1,12 @@
+import type { ReplaceVariable } from "../../types/variables";
+type VariableConfig = {
+    handle: string;
+    description: string;
+    events: string[];
+    eventMetaKey: string;
+    usage?: string;
+    defaultValue?: unknown;
+    type: ReplaceVariable["definition"]["possibleDataOutput"][number] | ReplaceVariable["definition"]["possibleDataOutput"];
+};
+export declare function createEventDataVariable({ events, eventMetaKey, type, defaultValue, ...definition }: VariableConfig): ReplaceVariable;
+export {};

package/backend/variables/variable-loader.d.ts

@@ -0,0 +1 @@
+export declare const loadReplaceVariables: () => void;

package/backend/viewers/viewer-database.d.ts

@@ -0,0 +1,87 @@
+import { TypedEmitter } from "tiny-typed-emitter";
+import Datastore from "@seald-io/nedb";
+import type { BasicViewer, FirebotViewer, NewFirebotViewer } from "../../types/viewers";
+import type { Rank, RankLadder } from "../../types/ranks";
+interface ViewerDbChangePacket {
+    userId: string;
+    field: string;
+    value: unknown;
+}
+interface ViewerPurgeOptions {
+    daysSinceActive: {
+        enabled: boolean;
+        value?: number;
+    };
+    viewTimeHours: {
+        enabled: boolean;
+        value?: number;
+    };
+    chatMessagesSent: {
+        enabled: boolean;
+        value?: number;
+    };
+    banned: {
+        enabled: boolean;
+    };
+}
+interface UserDetails {
+    firebotData: FirebotViewer;
+    twitchData: Record<string, unknown>;
+    streamerFollowsUser: boolean;
+    userFollowsStreamer: boolean;
+}
+declare class ViewerDatabase extends TypedEmitter<{
+    "viewer-database-loaded": () => void;
+    "updated-viewer-avatar": (event: {
+        userId: string;
+        url: string;
+    }) => void;
+}> {
+    private _db;
+    private _dbCompactionInterval;
+    private cancelRankRecalculation;
+    private _activeViewers;
+    constructor();
+    /**
+     * Checks settings to see if viewer database is enabled.
+     * @returns `true` if the viewer database is enabled, or `false` otherwise
+     */
+    isViewerDBOn(): boolean;
+    connectViewerDatabase(): Promise<void>;
+    disconnectViewerDatabase(): void;
+    getViewerDb(): Datastore<FirebotViewer>;
+    createNewViewer(viewer: NewFirebotViewer): Promise<FirebotViewer>;
+    addNewViewerFromChat(viewerDetails: BasicViewer, isOnline?: boolean): Promise<FirebotViewer>;
+    getViewerById(id: string): Promise<FirebotViewer>;
+    getViewerByUsername(username: string): Promise<FirebotViewer>;
+    getAllViewers(): Promise<FirebotViewer[]>;
+    getAllUsernames(): Promise<string[]>;
+    getAllUsernamesWithIds(): Promise<{
+        id: string;
+        username: string;
+        displayName: string;
+    }[]>;
+    incrementDbField(userId: string, fieldName: string): Promise<void>;
+    private sanitizeDbInput;
+    updateDbCell(changePacket: ViewerDbChangePacket): Promise<void>;
+    updateViewer(viewer: FirebotViewer): Promise<boolean>;
+    updateViewerDataField(userId: string, field: string, value: unknown): Promise<void>;
+    removeViewer(userId: string): Promise<boolean>;
+    private getPurgeWherePredicate;
+    getPurgeViewers(options: ViewerPurgeOptions): Promise<FirebotViewer[]>;
+    purgeViewers(options: ViewerPurgeOptions): Promise<number>;
+    setViewerRank(viewer: FirebotViewer, ladderId: string, newRankId?: string): Promise<void>;
+    setViewerRankById(userId: string, ladderId: string, rankId: string): Promise<void>;
+    viewerHasRank(viewer: FirebotViewer, ladderId: string, rankId: string): boolean;
+    viewerHasRankById(userId: string, ladderId: string, rankId: string): Promise<boolean>;
+    getViewerRankForLadderByUserName(userName: string, ladderId: string): Promise<Rank | null>;
+    getViewerRankForLadder(userId: string, ladderId: string): Promise<Rank | null>;
+    calculateAutoRanks(userId: string, trackByType?: RankLadder["settings"]["trackBy"]): Promise<void>;
+    calculateAutoRanksByName(userName: string, trackByType?: RankLadder["settings"]["trackBy"]): Promise<void>;
+    recalculateRanksForAllViewers(rankLadderId: string): Promise<void>;
+    addActiveViewer(userId: string): void;
+    removeActiveViewer(userId: string): void;
+    getUserDetails(userId: string): Promise<Partial<UserDetails>>;
+}
+declare const viewerDatabase: ViewerDatabase;
+export = viewerDatabase;

package/backend/viewers/viewer-export-manager.d.ts

@@ -0,0 +1,16 @@
+import type { FirebotViewer } from "../../types/viewers";
+interface ViewerExportOptions {
+    viewers: boolean;
+    currencies: boolean;
+    ranks: boolean;
+}
+declare class ViewerExportManager {
+    constructor();
+    setupListeners(): void;
+    exportViewersToFile(folderpath: string, exportOptions: ViewerExportOptions): Promise<boolean>;
+    createViewersFile(viewers: FirebotViewer[], folderpath: string): Promise<boolean>;
+    createCurrenciesFile(viewers: FirebotViewer[], folderpath: string): Promise<boolean>;
+    createRanksFile(viewers: FirebotViewer[], folderpath: string): Promise<boolean>;
+}
+declare const manager: ViewerExportManager;
+export { manager as ViewerExportManager };

package/backend/viewers/viewer-metadata-manager.d.ts

@@ -0,0 +1,17 @@
+import { FirebotViewer } from "../../types/viewers";
+import { TypedEmitter } from "tiny-typed-emitter";
+type Events = {
+    "created-item": (item: object) => void;
+    "updated-item": (item: object) => void;
+    "deleted-item": (item: object) => void;
+};
+declare class ViewerMetadataManager extends TypedEmitter<Events> {
+    constructor();
+    getViewerMetadata(username: string, key: string, propertyPath: string): Promise<unknown>;
+    getTopMetadataPosition(metadataKey: string, position?: number): Promise<FirebotViewer>;
+    getTopMetadata(metadataKey: string, count: number): Promise<FirebotViewer[]>;
+    updateViewerMetadata(username: string, key: string, value: string, propertyPath?: string): Promise<void>;
+    removeViewerMetadata(username: string, key: string): Promise<void>;
+}
+declare const viewerMetadataManager: ViewerMetadataManager;
+export = viewerMetadataManager;

package/backend/viewers/viewer-online-status-manager.d.ts

@@ -0,0 +1,25 @@
+import { BasicViewer, FirebotViewer } from "../../types/viewers";
+declare class ViewerOnlineStatusManager {
+    private _updateLastSeenIntervalId;
+    private _updateTimeIntervalId;
+    constructor();
+    getOnlineViewers(): Promise<FirebotViewer[]>;
+    getViewerOnlineMinutes(username: string): Promise<number>;
+    getTopViewTimeViewers(count: number): Promise<FirebotViewer[]>;
+    setChatViewerOnline(viewer: BasicViewer): Promise<void>;
+    setAllChatViewersOnline(): Promise<void>;
+    setChatViewerOffline(id: string): Promise<void>;
+    setAllViewersOffline(): Promise<void>;
+    /**
+     * Update viewers with last seen time. Allows us to recover chat hours from crash.
+     */
+    setLastSeenDateTime(): Promise<void>;
+    calcViewerOnlineMinutes(viewer: FirebotViewer): Promise<void>;
+    calcAllViewersOnlineMinutes(): Promise<void>;
+    /**
+     * Triggers a View Time Update event if view time hours has increased
+     */
+    viewerViewTimeUpdate(viewer: FirebotViewer, previousTotalMinutes: number, newTotalMinutes: number): void;
+}
+declare const viewerOnlineStatusManager: ViewerOnlineStatusManager;
+export = viewerOnlineStatusManager;

package/backend/webhooks/webhook-config-manager.d.ts

@@ -0,0 +1,16 @@
+import { WebhookConfig } from "../../types/webhooks";
+import JsonDbManager from "../database/json-db-manager";
+type ExtraEvents = {
+    "webhook-received": (data: {
+        config: WebhookConfig;
+        payload: unknown;
+        rawPayload?: string;
+        headers: Record<string, string>;
+    }) => void;
+};
+declare class WebhookConfigManager extends JsonDbManager<WebhookConfig, ExtraEvents> {
+    constructor();
+    getWebhookUrlById(webhookId: string): string;
+}
+declare const webhookConfigManager: WebhookConfigManager;
+export = webhookConfigManager;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crowbartools/firebot-types",
-  "version": "5.67.0-alpha4",
+  "version": "5.67.0-alpha5",
   "description": "Type definitions and script API for Firebot plugins and custom scripts.",
   "main": "index.js",
   "types": "index.d.ts",
@@ -20,6 +20,9 @@
     "index.js",
     "index.d.ts",
     "types/**/*.d.ts",
+    "backend/**/*.d.ts",
+    "server/**/*.d.ts",
+    "shared/**/*.d.ts",
     "README.md",
     "LICENSE"
   ],
@@ -40,5 +43,8 @@
   "license": "GPL-3.0",
   "peerDependencies": {
     "@types/node": "*"
+  },
+  "publishConfig": {
+    "access": "public"
   }
 }

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

@@ -0,0 +1,57 @@
+import { EventEmitter } from "events";
+import { Express, Request, Response, Router } from "express";
+import http from "http";
+import { Awaitable } from "../types/util-types";
+import { CustomWebSocketHandler } from "../types/websocket";
+interface ServerInstance {
+    name: string;
+    port: number;
+    server: http.Server;
+}
+type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "CONNECT" | "OPTIONS" | "TRACE";
+interface CustomRoute {
+    prefix: string;
+    route: string;
+    fullRoute: string;
+    method: HttpMethod;
+    callback: (req: Request, res: Response) => Awaitable<void>;
+}
+declare class HttpServerManager extends EventEmitter {
+    serverInstances: ServerInstance[];
+    defaultServerInstance: Express;
+    defaultHttpServer: http.Server;
+    overlayServer: http.Server;
+    isDefaultServerStarted: boolean;
+    overlayHasClients: boolean;
+    customRouteRouter: Router;
+    customRoutes: CustomRoute[];
+    constructor();
+    start(): void;
+    createDefaultServerInstance(): Express;
+    startDefaultHttpServer(): void;
+    sendToOverlay(eventName: string, meta?: Record<string, unknown>, overlayInstance?: string): void;
+    refreshAllOverlays(): void;
+    /**
+     * Refresh a specific overlay instance
+     * @param overlayInstance the instance to refresh, leave undefined to refresh default
+     */
+    refreshOverlayInstance(overlayInstance?: string): void;
+    triggerCustomWebSocketEvent(eventType: string, payload: object): void;
+    createServerInstance(): Express;
+    startHttpServer(name: string, port: number, instance: Express): http.Server;
+    stopHttpServer(name: any): boolean;
+    registerCustomRoute(prefix: string, route: string, method: string, callback: CustomRoute["callback"]): boolean;
+    unregisterCustomRoute(prefix: string, route: string, method: string): boolean;
+    buildCustomRouteParameters(prefix: string, route: string, method: string): {
+        normalizedPrefix: string;
+        normalizedRoute: string;
+        normalizedMethod: HttpMethod;
+        fullRoute: string;
+    };
+    private getCustomRoutePathFromRoot;
+    private removeCustomRoute;
+    registerCustomWebSocketListener(pluginName: string, callback: CustomWebSocketHandler["callback"]): boolean;
+    unregisterCustomWebSocketListener(pluginName: string): boolean;
+}
+declare const manager: HttpServerManager;
+export = manager;

package/server/websocket-client.d.ts

@@ -0,0 +1,5 @@
+import WebSocket from "ws";
+export declare class WebSocketClient extends WebSocket {
+    registrationTimeout: ReturnType<typeof setTimeout>;
+    type?: "overlay" | "events";
+}

package/server/websocket-events-handler.d.ts

@@ -0,0 +1 @@
+export declare function createComponentEventListeners(): void;

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

@@ -0,0 +1,21 @@
+import { EventEmitter } from "events";
+import http from "http";
+import type { CustomWebSocketHandler } from "../types/websocket";
+import type { WidgetOverlayEvent } from "../types";
+declare class WebSocketServerManager extends EventEmitter {
+    overlayHasClients: boolean;
+    private server;
+    private customHandlers;
+    constructor();
+    createServer(httpServer: http.Server): void;
+    sendToOverlay(eventName: string, meta?: Record<string, unknown>, overlayInstance?: string): void;
+    sendWidgetEventToOverlay(event: WidgetOverlayEvent): void;
+    refreshAllOverlays(): void;
+    triggerEvent(eventType: string, payload: unknown): void;
+    reportClientsToFrontend(isDefaultServerStarted: boolean): void;
+    getNumberOfOverlayClients(): number;
+    registerCustomWebSocketListener(pluginName: string, callback: CustomWebSocketHandler["callback"]): boolean;
+    unregisterCustomWebSocketListener(pluginName: string): boolean;
+}
+declare const manager: WebSocketServerManager;
+export = manager;

package/types/events.d.ts

@@ -98,4 +98,12 @@ export type EventGroup = {
     id: string;
     events: EventSettings[];
     active?: boolean;
+};
+
+export type TriggeredEvent = {
+    event: EventDefinition;
+    source: EventSource;
+    meta: Record<string, unknown>;
+    isManual: boolean;
+    isRetrigger: boolean;
 };

package/types/script-api.d.ts

@@ -1,10 +1,13 @@
 /// <reference types="node" />
 
 // Public contract types for the Firebot Script API.
-//
 // Everything a custom script can touch via `require("@crowbartools/firebot-types")`
 // should be defined here
 
+import type { TriggeredEvent } from "./events";
+import type { RunEffectsContext } from "./effects";
+import type { TwitchApi } from "../backend/streaming-platforms/twitch/api";
+
 export type ScriptLogMethod = (message: string, ...meta: unknown[]) => void;
 
 export interface ScriptLoggerApi {
@@ -45,42 +48,77 @@ export interface ScriptWebhooksApi {
     onReceived(handler: ScriptWebhookEventHandler): () => void;
 }
 
-export interface ScriptFsDirEntry {
-    /** File or directory name */
-    name: string;
-    /** Path relative to the script's data dir */
-    relativePath: string;
-    isFile: boolean;
-    isDirectory: boolean;
+/**
+ * Simple per-script storage scoped to the script's data directory.
+ * Provides helpers for storing/loading JSON values
+ * plus generic file read/write for anything else.
+ */
+export interface ScriptStorageApi {
+    /** Absolute path to this script's data directory. */
+    readonly path: string;
+
+    /** Save a value as JSON under the given key. The key becomes the filename with a `.json` extension. */
+    setJson(key: string, value: unknown): Promise<void>;
+    /**
+     * Load a JSON value previously saved with `setJson`. Returns `null` if
+     * nothing has been stored under this key.
+     */
+    getJson<T = unknown>(key: string): Promise<T | null>;
+    /** Delete the JSON value stored under the given key. No-op if missing. */
+    deleteJson(key: string): Promise<void>;
+
+    /** Check whether a file exists in the data directory. */
+    fileExists(name: string): Promise<boolean>;
+    /** Read a file's raw bytes. Returns `null` if it doesn't exist. */
+    readFile(name: string): Promise<Buffer | null>;
+    /** Read a file as text. Returns `null` if it doesn't exist. */
+    readTextFile(name: string, encoding?: BufferEncoding): Promise<string | null>;
+    /** Write contents to a file, creating any missing parent directories. */
+    writeFile(name: string, contents: string | Buffer | Uint8Array): Promise<void>;
+    /** Delete a file. No-op if it doesn't exist. */
+    deleteFile(name: string): Promise<void>;
 }
 
-export interface ScriptFsApi {
-    /** Absolute path to this script's data directory. Read-only. */
-    readonly dataDir: string;
+export type ScriptEventHandler = (event: TriggeredEvent) => void;
 
-    /** Resolve a sandboxed relative path to an absolute one. Throws on escape. */
-    resolve(relativePath: string): string;
-
-    exists(relativePath: string): Promise<boolean>;
+export interface ScriptEventsApi {
+    /**
+     * Subscribe to all Firebot events as they trigger. Returns an `unsubscribe`
+     * function.
+     */
+    onTriggered(handler: ScriptEventHandler): () => void;
 
-    readText(relativePath: string, encoding?: BufferEncoding): Promise<string>;
-    writeText(relativePath: string, contents: string, encoding?: BufferEncoding): Promise<void>;
+    /**
+     * Manually trigger a Firebot event.
+     */
+    trigger(
+        sourceId: string,
+        eventId: string,
+        meta?: Record<string, unknown>
+    ): Promise<void>;
+}
 
-    readBytes(relativePath: string): Promise<Buffer>;
-    writeBytes(relativePath: string, contents: Buffer | Uint8Array): Promise<void>;
+export interface ScriptEffectsApi {
+    /**
+     * Register an existing effect to be available for an event.
+     * Useful for surfacing built-in effects on script provided events.
+     */
+    addEventToEffect(effectId: string, eventSourceId: string, eventId: string): void;
 
-    /** Read JSON. Returns `null` if the file doesn't exist. */
-    readJson(relativePath: string): Promise<unknown>;
-    /** Write JSON pretty-printed with 2-space indent. */
-    writeJson(relativePath: string, value: unknown): Promise<void>;
+    /** Reverse of `addEventToEffect`. */
+    removeEventFromEffect(effectId: string, eventSourceId: string, eventId: string): void;
 
-    /** Create a directory (and any missing parents). */
-    mkdir(relativePath: string): Promise<void>;
-    /** Delete a file or directory recursively. No-op if it doesn't exist. */
-    remove(relativePath: string): Promise<void>;
+    /**
+     * 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>;
+}
 
-    /** List immediate children of a directory (defaults to the data dir root). */
-    list(relativePath?: string): Promise<ScriptFsDirEntry[]>;
+export interface ScriptTwitchApi {
+    /** The full Twitch API surface. See {@linkcode TwitchApi}. */
+    api: typeof TwitchApi;
 }
 
 export interface FirebotScriptApi {
@@ -90,6 +128,12 @@ export interface FirebotScriptApi {
     logger: ScriptLoggerApi;
     /** Webhooks owned by this script. */
     webhooks: ScriptWebhooksApi;
-    /** Sandboxed filesystem rooted at this script's data directory. */
-    fs: ScriptFsApi;
+    /** Simple persistent storage rooted at this script's data directory. */
+    storage: ScriptStorageApi;
+    /** Subscribe to and trigger Firebot events + register event sources. */
+    events: ScriptEventsApi;
+    /** Run effect lists. */
+    effects: ScriptEffectsApi;
+    /** Access to Firebot's Twitch API wrappers (Helix, chat, auth, etc). */
+    twitch: ScriptTwitchApi;
 }