@crowbartools/firebot-types 5.67.0-alpha8 → 5.67.0-alpha9

package/backend/crowbar-relay/crowbar-relay-websocket.d.ts

@@ -7,6 +7,7 @@ declare class CrowbarRelayWebSocket extends TypedEmitter<{
     }) => void;
 }> {
     private ws;
+    private logger;
     constructor();
     private start;
     send(event: string, data?: unknown): void;

package/backend/notifications/notification-manager.d.ts

@@ -1,29 +1,4 @@
-export declare enum NotificationSource {
-    EXTERNAL = "external",
-    INTERNAL = "internal",
-    SCRIPT = "script"
-}
-export declare enum NotificationType {
-    INFO = "info",
-    TIP = "tip",
-    UPDATE = "update",
-    ALERT = "alert"
-}
-export type NotificationBase = {
-    title: string;
-    message: string;
-    type: NotificationType;
-    source?: NotificationSource;
-    scriptName?: string;
-    externalId?: string;
-    metadata?: Record<string, unknown>;
-};
-export type Notification = NotificationBase & {
-    id: string;
-    timestamp: Date;
-    saved: boolean;
-    read: boolean;
-};
+import { Notification, NotificationBase } from "../../types";
 declare class NotificationManager {
     private _externalCheckInterval;
     private _notificationCache;

package/backend/overlay-widgets/overlay-widgets-manager.d.ts

@@ -2,11 +2,13 @@ import { OverlayWidgetConfig, OverlayWidgetType, WidgetUIAction, WidgetOverlayEv
 import { TypedEmitter } from "tiny-typed-emitter";
 type Events = {
     "overlay-widget-type-registered": (overlayWidgetType: OverlayWidgetType) => void;
+    "overlay-widget-type-unregistered": (id: string) => void;
 };
 declare class OverlayWidgetsManager extends TypedEmitter<Events> {
     private overlayWidgetTypes;
     constructor();
     registerOverlayWidgetType(overlayWidgetType: OverlayWidgetType<any, any>): void;
+    unregisterOverlayWidgetType(id: string): void;
     getOverlayWidgetType(id: string): OverlayWidgetType | null;
     getOverlayWidgetTypesForFrontend(): (Pick<OverlayWidgetType, "id" | "name" | "description" | "icon" | "settingsSchema" | "userCanConfigure" | "supportsLivePreview" | "initialState" | "initialAspectRatio" | "nonEditableSettings"> & {
         uiActions?: Omit<WidgetUIAction, "click">[];

package/backend/{custom-scripts → scripts}/executors/script-executor.interface.d.ts

@@ -13,6 +13,7 @@ export interface PluginRegistrations {
     integrationIds?: string[];
     gameIds?: string[];
     uiExtensionIds?: string[];
+    overlayWidgetIds?: string[];
 }
 export type PluginExecutionResult = {
     success: true;

package/backend/{custom-scripts → scripts}/script-api/context.d.ts

@@ -31,14 +31,15 @@ export interface ScriptApiContext {
 export interface ScriptApiContextHandle {
     readonly context: ScriptApiContext;
     readonly disposeBag: DisposeBag;
-    setManifest(manifest: Manifest | undefined): void;
 }
 export type ScriptApiContextSource = {
     kind: "plugin";
     config: InstalledPluginConfig;
+    manifest: Manifest;
 } | {
     kind: "effect-script";
     fileName: string;
+    manifest: Manifest;
 };
 export declare function createScriptApiContext(source: ScriptApiContextSource): ScriptApiContextHandle;
 export { normalizeName };

package/backend/scripts/script-api/namespaces/notifications.d.ts

@@ -0,0 +1,2 @@
+import type { ScriptNotificationsApi } from "../../../../types/script-api";
+export declare const createNotificationsApi: import("../internal/define-namespace").ScriptApiNamespaceFactory<ScriptNotificationsApi>;

package/backend/scripts/script-api/namespaces/plugins.d.ts

@@ -0,0 +1,2 @@
+import type { ScriptPluginsApi } from "../../../../types/script-api";
+export declare const createPluginsApi: import("../internal/define-namespace").ScriptApiNamespaceFactory<ScriptPluginsApi>;

package/backend/scripts/script-api/namespaces/settings.d.ts

@@ -0,0 +1,2 @@
+import type { ScriptSettingsApi } from "../../../../types/script-api";
+export declare const createSettingsApi: import("../internal/define-namespace").ScriptApiNamespaceFactory<ScriptSettingsApi>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crowbartools/firebot-types",
-  "version": "5.67.0-alpha8",
+  "version": "5.67.0-alpha9",
   "description": "Type definitions and script API for Firebot plugins and custom scripts.",
   "main": "index.js",
   "types": "index.d.ts",

package/types/index.d.ts

@@ -17,6 +17,7 @@ export * from "./import";
 export * from "./integrations";
 export * from "./moderation";
 export * from "./modules";
+export * from "./notifications";
 export * from "./overlay-widgets";
 export * from "./parameters";
 export * from "./pronouns";

package/types/notifications.d.ts

@@ -0,0 +1,33 @@
+export type NotificationSource = "external" | "internal" | "script";
+
+export type NotificationType = "info" | "tip" | "update" | "alert";
+
+export type ExternalNotification = {
+    id: string;
+    title: string;
+    message: string;
+    type: NotificationType;
+};
+
+export type NotificationBase = {
+    title: string;
+    message: string;
+    type: NotificationType;
+    source?: NotificationSource;
+    scriptName?: string;
+    externalId?: string;
+    metadata?: Record<string, unknown>;
+};
+
+export type Notification = NotificationBase & {
+    id: string;
+    timestamp: Date;
+    saved: boolean;
+    read: boolean;
+};
+
+export interface NotificationCache {
+    dbVersion?: string;
+    notifications: Notification[];
+    knownExternalIds: string[];
+}

package/types/plugins.d.ts

@@ -10,6 +10,7 @@ import { FirebotParams, FirebotParameterArray } from "./parameters";
 import { FirebotGame } from "./games";
 import { Integration } from "./integrations";
 import { UIExtension } from "./ui-extensions";
+import { OverlayWidgetType } from "./overlay-widgets";
 
 type NoResult = Awaitable<void>;
 
@@ -100,28 +101,21 @@ 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<Params>, isUninstalling?: boolean) => NoResult;
 }
 
-// Supplants the "Run Script" effect script functionality
 export interface EffectScript<Params extends FirebotParams = FirebotParams> extends ScriptBase<Params> {
     run: (context: ScriptContext<Params>) => 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
+    /**
+     * Automatically handles registration with appropriate managers for definitions
+     * when the script is unloaded, definitions will automagically be unregistered.
+     *
+     * Array entries can be direct definitions or functions that return definitions
+     * (or promises of definitions) for dynamic registration based on context (e.g. parameter values).
+     */
     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<any, any>>;
         eventSources?: DynamicArray<EventSource>;
         variables?: DynamicArray<ReplaceVariable>;
@@ -131,15 +125,16 @@ export interface Plugin<Params extends FirebotParams = FirebotParams> extends Sc
         systemCommands?: DynamicArray<SystemCommand<any>>;
         games?: DynamicArray<FirebotGame>;
         uiExtensions?: DynamicArray<UIExtension>;
+        overlayWidgets?: DynamicArray<OverlayWidgetType<any, any>>;
     };
 
-    // Called when the script is loaded
+    /** Called when the plugin is loaded */
     onLoad?: (context: ScriptContext<Params>, isInstalling?: boolean) => NoResult;
 
-    // Called when firebot is closing or plugin is disabled / removed
+    /** Called when Firebot is closing or plugin is disabled / removed  */
     onUnload?: (context: ScriptContext<Params>, isUninstalling?: boolean) => NoResult;
 
-    // called when the user updates plugin-specific parameters
+    /** Called when the user updates plugin-specific parameters */
     onParameterUpdate?: (context: ScriptContext<Params>) => NoResult;
 }
 
@@ -151,7 +146,6 @@ export type InstalledPlugin = {
 };
 
 /* Legacy types */
-
 type LegacyScriptParameters = Record<
     string,
     {

package/types/script-api.d.ts

@@ -7,6 +7,10 @@
 import type { 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";
 
 export type ScriptLogMethod = (message: string, ...meta: unknown[]) => void;
 
@@ -129,6 +133,22 @@ export interface ScriptParametersApi {
     getAll<T extends Record<string, unknown> = Record<string, unknown>>(): T;
 }
 
+export interface ScriptNotificationsApi {
+    /**
+     * 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 script's notifications by id. */
+    get(id: string): Notification | null;
+    /** All notifications owned by this script. */
+    getAll(): Notification[];
+    /** Delete one of this script's notifications by id. */
+    delete(id: string): void;
+    /** Delete all of this script's notifications. */
+    clearAll(): void;
+}
+
 export interface ScriptFrontendCommunicatorApi {
     /** Send a synchronous event to the frontend. */
     send<ExpectedArg = unknown>(eventName: string, data?: ExpectedArg): void;
@@ -161,11 +181,37 @@ export interface ScriptFrontendCommunicatorApi {
     ): () => void;
 }
 
+export interface ScriptSettingsApi {
+    /**
+     * 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 ScriptPluginsApi {
+    /**
+     * Get a list of currently installed plugins installed by the user
+     */
+    getInstalledPlugins(): Promise<Array<InstalledPlugin>>;
+}
+
+export interface Accounts {
+    streamer: FirebotAccount;
+    bot: FirebotAccount;
+}
+
 export interface FirebotScriptApi {
-    /** Running Firebot version, e.g. `"5.65.0"`. */
+    /** Running Firebot version, e.g. `"5.67.0"`. */
     version: string;
+    /** The streamer and bot accounts currently in use. */
+    accounts: Accounts;
     /** Scoped logger. */
     logger: ScriptLoggerApi;
+    /** Access to Firebot settings. */
+    settings: ScriptSettingsApi;
     /** Webhooks owned by this script. */
     webhooks: ScriptWebhooksApi;
     /** Simple persistent storage rooted at this script's data directory. */
@@ -180,4 +226,8 @@ export interface FirebotScriptApi {
     parameters: ScriptParametersApi;
     /** Two-way messaging between the script and the frontend. */
     frontendCommunicator: ScriptFrontendCommunicatorApi;
+    /** Notifications owned by this script. */
+    notifications: ScriptNotificationsApi;
+    /** Access to installed plugins. */
+    plugins: ScriptPluginsApi;
 }

package/backend/{custom-scripts → scripts}/script-manager.d.ts

@@ -10,10 +10,10 @@ type GetScriptDetailsResult = {
     error: string;
 };
 declare class ScriptManager {
+    private startingPlugins;
     private activePlugins;
     private pendingApiInstances;
     private effectScriptApiInstances;
-    private startingPlugins;
     private requireInterceptorInstalled;
     private pluginExecutors;
     private effectScriptExecutors;