@crowbartools/firebot-types 5.67.0-alpha1

package/README.md

@@ -0,0 +1,43 @@
+# @crowbartools/firebot-types
+
+Type definitions and the script API contract for [Firebot](https://firebot.app) custom scripts and plugins.
+
+This package is **type-only**. At runtime the `@crowbartools/firebot-types` module is provided by the Firebot host application via a `require()` interceptor — installing this package in a standalone Node project and importing it will throw.
+
+## Install
+
+```bash
+npm i -D @crowbartools/firebot-types
+```
+
+A `@types/node` peer dependency is required (the script API uses `Buffer` / `BufferEncoding`).
+
+## Usage
+
+The default export is the runtime API object provided by Firebot. Named types live under the `@crowbartools/firebot-types/types` subpath.
+
+```ts
+import firebot from "@crowbartools/firebot-types";
+import type { Plugin, EffectScript } from "@crowbartools/firebot-types/types";
+
+export const manifest: Plugin["manifest"] = {
+    name: "My Plugin",
+    version: "1.0.0",
+    author: "you",
+    description: "Example",
+    type: "plugin"
+};
+
+export function onLoad() {
+    firebot.logger.info(`Running on Firebot ${firebot.version}`);
+}
+```
+
+CommonJS style works too:
+
+```js
+const firebot = require("@crowbartools/firebot-types");
+firebot.logger.info(firebot.version);
+```
+
+The version of this package tracks the Firebot version that produced it.

package/index.d.ts

@@ -0,0 +1,5 @@
+// Auto-generated by grunt publish-types. Do not edit by hand.
+import { FirebotScriptApi } from "./types/script-api";
+
+declare const firebot: FirebotScriptApi;
+export = firebot;

package/index.js

@@ -0,0 +1,5 @@
+// This package is a type-only shim. The real `@crowbartools/firebot-types` module is
+// provided by the Firebot host at runtime via a require() interceptor.
+throw new Error(
+    "The '@crowbartools/firebot-types' module is only available when running inside Firebot."
+);

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@crowbartools/firebot-types",
+  "version": "5.67.0-alpha1",
+  "description": "Type definitions and script API for Firebot custom scripts and plugins.",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    },
+    "./types": {
+      "types": "./types/index.d.ts"
+    },
+    "./types/*": {
+      "types": "./types/*.d.ts"
+    }
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "types/**/*.d.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "firebot",
+    "twitch",
+    "types",
+    "script",
+    "plugin"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/crowbartools/Firebot.git"
+  },
+  "homepage": "https://firebot.app",
+  "bugs": "https://github.com/crowbartools/Firebot/issues",
+  "author": "The Streaming Community",
+  "license": "GPL-3.0",
+  "peerDependencies": {
+    "@types/node": "*"
+  }
+}

package/types/accounts.d.ts

@@ -0,0 +1,13 @@
+import type { AuthDetails } from "./auth";
+
+export type FirebotAccount = {
+    username: string;
+    displayName?: string;
+    description?: string;
+    userId?: string;
+    channelId?: string;
+    avatar?: string;
+    broadcasterType?: string;
+    auth?: AuthDetails;
+    loggedIn?: boolean;
+};

package/types/auth.d.ts

@@ -0,0 +1,51 @@
+import type ClientOAuth2 from "client-oauth2";
+
+export interface AuthProviderDefinition {
+    id: string;
+    name: string;
+    client: {
+        id: string;
+        secret?: string;
+    };
+    auth: {
+        type: "code" | "token" | "device";
+        authorizeHost?: string;
+        tokenHost: string;
+        authorizePath: string;
+        tokenPath?: string;
+    };
+    redirectUriHost?: string;
+    scopes?: string[] | string | undefined;
+}
+
+export interface AuthProvider {
+    id: string;
+    oauthClient: ClientOAuth2;
+    authorizationUri: string;
+    redirectUri: string;
+    tokenUri: string;
+    details: AuthProviderDefinition;
+}
+
+export interface AuthDetails {
+    /** The access token */
+    access_token: string;
+
+    /** The type of access token */
+    token_type: string;
+
+    /** OAuth scopes of the access token */
+    scope: string[];
+
+    /** When the token was obtained, in epoch timestamp format */
+    obtainment_timestamp?: number;
+
+    /** How many seconds before the token expires */
+    expires_in?: number;
+
+    /** JSON representation of when access token expires */
+    expires_at?: Date;
+
+    /** The refresh token */
+    refresh_token?: string;
+}

package/types/channel-rewards.d.ts

@@ -0,0 +1,63 @@
+import type { EffectList } from "./effects";
+import type { RestrictionData } from "./restrictions";
+
+export interface CustomRewardImageSet {
+    url1x: string;
+    url2x: string;
+    url4x: string;
+}
+
+export interface CustomReward {
+    broadcasterId: string;
+    broadcasterLogin: string;
+    broadcasterName: string;
+    id: string;
+    title: string;
+    prompt: string;
+    cost: number;
+    image?: CustomRewardImageSet;
+    defaultImage: CustomRewardImageSet;
+    backgroundColor: string;
+    isEnabled: boolean;
+    isUserInputRequired: boolean;
+    maxPerStreamSetting: {
+        isEnabled: boolean;
+        maxPerStream: number;
+    };
+    maxPerUserPerStreamSetting: {
+        isEnabled: boolean;
+        maxPerUserPerStream: number;
+    };
+    globalCooldownSetting: {
+        isEnabled: boolean;
+        globalCooldownSeconds: number;
+    };
+    isPaused: boolean;
+    isInStock: boolean;
+    shouldRedemptionsSkipRequestQueue: boolean;
+    redemptionsRedeemedCurrentStream?: number;
+    cooldownExpiresAt?: Date;
+}
+
+export type SavedChannelReward = {
+    id: string;
+    twitchData: CustomReward;
+    manageable: boolean;
+    effects?: EffectList;
+    effectsFulfilled?: EffectList;
+    effectsCanceled?: EffectList;
+    restrictionData?: RestrictionData;
+    autoApproveRedemptions?: boolean;
+};
+
+export type RewardRedemptionMetadata = {
+    username: string;
+    userId: string;
+    userDisplayName: string;
+    messageText: string;
+    redemptionId: string;
+    rewardId: string;
+    rewardImage: string;
+    rewardName: string;
+    rewardCost: number;
+};

package/types/chat.d.ts

@@ -0,0 +1,159 @@
+type FirebotChatMessagePartType =
+    | "text"
+    | "link"
+    | "emote"
+    | "third-party-emote"
+    | "cheermote"
+    | "mention";
+
+type FirebotChatMessagePartBase = {
+    type: FirebotChatMessagePartType;
+    id?: string;
+    text: string;
+};
+
+type FirebotChatMessageTextPart = FirebotChatMessagePartBase & {
+    type: "text";
+    flagged?: boolean;
+};
+
+type FirebotChatMessageLinkPart = FirebotChatMessagePartBase & {
+    type: "link";
+    url: string;
+};
+
+type FirebotChatMessageEmotePart = FirebotChatMessagePartBase & {
+    type: "emote" | "third-party-emote";
+    name: string;
+    origin: string;
+    url: string;
+    animatedUrl?: string;
+};
+
+type FirebotChatMessageCheermotePart = FirebotChatMessagePartBase & {
+    type: "cheermote";
+    name: string;
+    url: string;
+    animatedUrl: string;
+    amount: number;
+    color: string;
+};
+
+type FirebotChatMessageMentionPart = FirebotChatMessagePartBase & {
+    type: "mention";
+    username: string;
+    userId: string;
+    userDisplayName: string;
+};
+
+export type FirebotChatMessagePart =
+    | FirebotChatMessageTextPart
+    | FirebotChatMessageLinkPart
+    | FirebotChatMessageEmotePart
+    | FirebotChatMessageCheermotePart
+    | FirebotChatMessageMentionPart;
+
+export type FirebotParsedMessagePart = {
+    type: string;
+    id?: string;
+    text?: string;
+    name?: string;
+    origin?: string;
+    position?: number;
+    flagged?: boolean;
+    length?: number;
+    url?: string;
+    animatedUrl?: string;
+    amount?: number;
+    color?: string;
+};
+
+export type FirebotChatMessage = {
+    id: string;
+    timestamp?: number;
+    username: string;
+    userId: string;
+    userDisplayName?: string;
+    profilePicUrl?: string;
+    pronouns?: string;
+    isExtension?: boolean;
+    roles: string[];
+    badges: Array<{
+        title: string;
+        url: string;
+    }>;
+    customRewardId?: string;
+    color?: string;
+    rawText: string;
+    parts: FirebotParsedMessagePart[] | FirebotChatMessagePart[];
+    whisper: boolean;
+    whisperTarget?: string;
+    action: boolean;
+    isAnnouncement?: boolean;
+    announcementColor?: "PRIMARY" | "BLUE" | "GREEN" | "ORANGE" | "PURPLE";
+    tagged: boolean;
+    isFounder?: boolean;
+    isBroadcaster?: boolean;
+    isBot?: boolean;
+    isMod?: boolean;
+    isSubscriber?: boolean;
+    isVip?: boolean;
+    isCheer?: boolean;
+    isHighlighted?: boolean;
+    isAutoModHeld?: boolean;
+    autoModStatus?: "pending" | "approved" | "denied" | "expired";
+    autoModReason?: string;
+    isFirstChat?: boolean;
+    isReturningChatter?: boolean;
+    isRaider?: boolean;
+    raidingFrom?: string;
+    isSuspiciousUser?: boolean;
+    isReply?: boolean;
+    replyParentMessageId?: string;
+    replyParentMessageText?: string;
+    replyParentMessageSenderUserId?: string;
+    replyParentMessageSenderDisplayName?: string;
+    threadParentMessageId?: string;
+    threadParentMessageSenderUserId?: string;
+    threadParentMessageSenderDisplayName?: string;
+    isSharedChatMessage: boolean;
+    sharedChatRoomId?: string;
+    sharedChatRoomUsername?: string;
+    sharedChatRoomDisplayName?: string;
+    sharedChatRoomProfilePicUrl?: string;
+    isHiddenFromChatFeed?: boolean;
+    viewerRanks?: Record<string, string>;
+    viewerCustomRoles?: string[];
+    customHighlightColor?: string;
+    customBannerIcon?: string;
+    customBannerText?: string;
+    reward?: {
+        id: string;
+        name: string;
+        cost: number;
+        imageUrl: string;
+    };
+    isGigantified?: boolean;
+};
+
+export type FirebotEmote = {
+    url: string;
+    animatedUrl: string;
+    origin: string;
+    code: string;
+};
+
+export type FirebotCheermoteInstance = {
+    name: string;
+    amount: number;
+    url: string;
+    animatedUrl: string;
+    color: string;
+};
+
+export type SharedChatParticipant = {
+    broadcasterId: string;
+    broadcasterName: string;
+    broadcasterDisplayName: string;
+    profilePictureUrl: string;
+};

package/types/commands.d.ts

@@ -0,0 +1,138 @@
+import type { FirebotChatMessage } from "./chat";
+import type { EffectList } from "./effects";
+import type { RestrictionData } from "./restrictions";
+import type { ParametersConfig } from "./parameters";
+import type { Awaitable } from "./util-types";
+
+export type CommandType = "system" | "custom";
+
+type Cooldown = {
+    /**
+     * Global cooldown to use a command in seconds.
+     */
+    global: number | undefined;
+    /**
+     * Cooldown for each user to use a command in seconds.
+     */
+    user: number | undefined;
+};
+
+export type SubCommand = {
+    arg: string;
+    usage: string;
+    active?: boolean;
+    autoDeleteTrigger?: boolean | undefined;
+    id?: string;
+    description?: string;
+    minArgs?: number;
+    regex?: boolean;
+    fallback?: boolean;
+    restrictionData?: RestrictionData;
+    cooldown?: Cooldown | undefined;
+    hideCooldowns?: boolean;
+    inheritBaseCommandCooldown?: boolean;
+    effects?: EffectList;
+    hidden?: boolean;
+};
+
+export type CommandDefinition<OptionsModel = any> = {
+    id?: string;
+    name?: string;
+    description?: string;
+    type?: CommandType;
+    createdBy?: string;
+    createdAt?: Date | string;
+    lastEditBy?: string | undefined;
+    lastEditAt?: Date | string | undefined;
+    /**
+     * Describes how many times the command has been used in chat.
+     */
+    count?: number;
+    active: boolean;
+    trigger: string;
+    triggerIsRegex?: boolean | undefined;
+    scanWholeMessage?: boolean | undefined;
+    aliases?: string[];
+    usage?: string;
+    /**
+     * If the chat message that triggered the command should be deleted automatically.
+     */
+    autoDeleteTrigger?: boolean | undefined;
+    /**
+     * If the UI should show the edit page in simple or advanced mode.
+     */
+    simple?: boolean;
+    /**
+     * If the command should be hidden from the `!commands` list.
+     */
+    hidden?: boolean | undefined;
+    ignoreStreamer?: boolean | undefined;
+    ignoreBot?: boolean | undefined;
+    ignoreWhispers?: boolean | undefined;
+    /**
+     * If a chat message should be sent when the command is tried to be used but
+     * the cooldown is not yet over.
+     */
+    sendCooldownMessage?: boolean;
+    sendCooldownMessageAsReply?: boolean;
+    useCustomCooldownMessage?: boolean;
+    cooldownMessage?: string;
+    baseCommandDescription?: string | undefined;
+    sortTags?: string[];
+    cooldown?: Cooldown | undefined;
+    effects?: EffectList;
+    restrictionData?: RestrictionData;
+    subCommands?: SubCommand[] | undefined;
+    fallbackSubcommand?: SubCommand | undefined;
+    treatQuotedTextAsSingleArg?: boolean | undefined;
+    minArgs?: number;
+    options?: ParametersConfig<OptionsModel>;
+    /**
+     * Only set for currency system commands.
+     */
+    currency?: {
+        name: string;
+        id: string;
+    };
+    allowTriggerBySharedChat?: boolean | "inherit" | undefined;
+};
+
+type UserCommand = {
+    trigger: string;
+    args: string[];
+    triggeredSubcmd?: SubCommand;
+    isInvalidSubcommandTrigger?: boolean;
+    triggeredArg?: string;
+    subcommandId?: string;
+    commandSender: string;
+    senderRoles: string[];
+};
+
+type BasicCommandDefinition = Omit<
+    CommandDefinition,
+    | "type"
+    | "createdBy"
+    | "createdAt"
+    | "lastEditBy"
+    | "lastEditAt"
+    | "count"
+    | "simple"
+>;
+
+export type SystemCommandDefinition<OptionsModel = any> = CommandDefinition<OptionsModel> & {
+    hideCooldowns?: boolean;
+};
+
+export type SystemCommand<OptionsModel = any> = {
+    definition: SystemCommandDefinition<OptionsModel>;
+    onTriggerEvent: (
+        event: {
+            command: SystemCommand<OptionsModel>['definition'];
+            userCommand: UserCommand;
+            chatMessage: FirebotChatMessage;
+            commandOptions?: {
+                [x in keyof OptionsModel]: OptionsModel[x]
+            };
+        }
+    ) => Awaitable<boolean | void>;
+};

package/types/counters.d.ts

@@ -0,0 +1,13 @@
+import type { EffectList } from "./effects";
+
+export type Counter = {
+    id?: string;
+    name: string;
+    value: number;
+    saveToTxtFile: boolean;
+    minimum?: number;
+    maximum?: number;
+    updateEffects?: EffectList;
+    minimumEffects?: EffectList;
+    maximumEffects?: EffectList;
+};

package/types/currency.d.ts

@@ -0,0 +1,15 @@
+export type Currency = {
+    id: string;
+    name: string;
+    active: boolean;
+    limit: number;
+    transfer: "Allow" | "Disallow";
+    interval: number;
+    payout: number;
+
+    /** Offline payout */
+    offline?: number | string;
+
+    /** Maps user role IDs to the amount of bonus payout they receive. */
+    bonus: Record<string, number>;
+};

package/types/discord.d.ts

@@ -0,0 +1,10 @@
+export type CustomEmbed = {
+    title?: string;
+    url?: string;
+    description?: string;
+    authorName?: string;
+    authorIconUrl?: string;
+    imageUrl?: string;
+};
+
+export type EmbedType = "channel" | "stream" | "custom";