Add a new Channel API for experimental plugins feature

CHANGELOG.md

@@ -30,6 +30,7 @@
 - Minor: Added icons for newer versions of macOS. (#5148)
 - Minor: Added the `--incognito/--no-incognito` options to the `/openurl` command, allowing you to override the "Open links in incognito/private mode" setting. (#5149)
 - Minor: Added support for the `{input.text}` placeholder in the **Split** -> **Run a command** hotkey. (#5130)
+- Minor: Add a new Channel API for experimental plugins feature. (#5141)
 - Bugfix: Fixed an issue where certain emojis did not send to Twitch chat correctly. (#4840)
 - Bugfix: Fixed capitalized channel names in log inclusion list not being logged. (#4848)
 - Bugfix: Trimmed custom streamlink paths on all platforms making sure you don't accidentally add spaces at the beginning or end of its path. (#4834)

docs/chatterino.d.ts

@@ -12,13 +12,68 @@ declare module c2 {
     channel_name: String;
   }
 
+  enum Platform {
+    Twitch,
+  }
+  enum ChannelType {
+    None,
+    Direct,
+    Twitch,
+    TwitchWhispers,
+    TwitchWatching,
+    TwitchMentions,
+    TwitchLive,
+    TwitchAutomod,
+    Irc,
+    Misc,
+  }
+
+  interface IWeakResource {
+    is_valid(): boolean;
+  }
+
+  class RoomModes {
+    unique_chat: boolean;
+    subscriber_only: boolean;
+    emotes_only: boolean;
+    follower_only: null | number;
+    slow_mode: null | number;
+  }
+  class StreamStatus {
+    live: boolean;
+    viewer_count: number;
+    uptime: number;
+    title: string;
+    game_name: string;
+    game_id: string;
+  }
+
+  class Channel implements IWeakResource {
+    is_valid(): boolean;
+    get_name(): string;
+    get_type(): ChannelType;
+    get_display_name(): string;
+    send_message(message: string, execute_commands: boolean): void;
+    add_system_message(message: string): void;
+
+    is_twitch_channel(): boolean;
+
+    get_room_modes(): RoomModes;
+    get_stream_status(): StreamStatus;
+    get_twitch_id(): string;
+    is_broadcaster(): boolean;
+    is_mod(): boolean;
+    is_vip(): boolean;
+
+    static by_name(name: string, platform: Platform): null | Channel;
+    static by_twitch_id(id: string): null | Channel;
+  }
+
   function log(level: LogLevel, ...data: any[]): void;
   function register_command(
     name: String,
     handler: (ctx: CommandContext) => void
   ): boolean;
-  function send_msg(channel: String, text: String): boolean;
-  function system_msg(channel: String, text: String): boolean;
 
   class CompletionList {
     values: String[];

docs/plugin-meta.lua

@@ -6,6 +6,15 @@
 
 c2 = {}
 
+---@class IWeakResource
+
+--- Returns true if the channel this object points to is valid.
+--- If the object expired, returns false
+--- If given a non-Channel object, it errors.
+---@return boolean
+function IWeakResource:is_valid() end
+
+
 ---@alias LogLevel integer
 ---@type { Debug: LogLevel, Info: LogLevel, Warning: LogLevel, Critical: LogLevel }
 c2.LogLevel = {}
@@ -20,6 +29,142 @@ c2.EventType = {}
 ---@class CompletionList
 ---@field values string[] The completions
 ---@field hide_others boolean Whether other completions from Chatterino should be hidden/ignored.
+-- Now including data from src/common/Channel.hpp.
+
+---@alias ChannelType integer
+---@type { None: ChannelType }
+ChannelType = {}
+-- Back to src/controllers/plugins/LuaAPI.hpp.
+-- Now including data from src/controllers/plugins/api/ChannelRef.hpp.
+--- This enum describes a platform for the purpose of searching for a channel.
+--- Currently only Twitch is supported because identifying IRC channels is tricky.
+
+---@alias Platform integer
+---@type { Twitch: Platform }
+Platform = {}
+---@class Channel: IWeakResource
+
+--- Returns true if the channel this object points to is valid.
+--- If the object expired, returns false
+--- If given a non-Channel object, it errors.
+---
+---@return boolean success
+function Channel:is_valid() end
+
+--- Gets the channel's name. This is the lowercase login name.
+---
+---@return string name
+function Channel:get_name() end
+
+--- Gets the channel's type
+---
+---@return ChannelType
+function Channel:get_type() end
+
+--- Get the channel owner's display name. This may contain non-lowercase ascii characters.
+---
+---@return string name
+function Channel:get_display_name() end
+
+--- Sends a message to the target channel.
+--- Note that this does not execute client-commands.
+---
+---@param message string
+---@param execute_commands boolean Should commands be run on the text?
+function Channel:send_message(message, execute_commands) end
+
+--- Adds a system message client-side
+---
+---@param message string
+function Channel:add_system_message(message) end
+
+--- Returns true for twitch channels.
+--- Compares the channel Type. Note that enum values aren't guaranteed, just
+--- that they are equal to the exposed enum.
+---
+---@return bool
+function Channel:is_twitch_channel() end
+
+--- Twitch Channel specific functions
+
+--- Returns a copy of the channel mode settings (subscriber only, r9k etc.)
+---
+---@return RoomModes
+function Channel:get_room_modes() end
+
+--- Returns a copy of the stream status.
+---
+---@return StreamStatus
+function Channel:get_stream_status() end
+
+--- Returns the Twitch user ID of the owner of the channel.
+---
+---@return string
+function Channel:get_twitch_id() end
+
+--- Returns true if the channel is a Twitch channel and the user owns it
+---
+---@return boolean
+function Channel:is_broadcaster() end
+
+--- Returns true if the channel is a Twitch channel and the user is a moderator in the channel
+--- Returns false for broadcaster.
+---
+---@return boolean
+function Channel:is_mod() end
+
+--- Returns true if the channel is a Twitch channel and the user is a VIP in the channel
+--- Returns false for broadcaster.
+---
+---@return boolean
+function Channel:is_vip() end
+
+--- Misc
+
+---@return string
+function Channel:__tostring() end
+
+--- Static functions
+
+--- Finds a channel by name.
+---
+--- Misc channels are marked as Twitch:
+--- - /whispers
+--- - /mentions
+--- - /watching
+--- - /live
+--- - /automod
+---
+---@param name string Which channel are you looking for?
+---@param platform Platform Where to search for the channel?
+---@return Channel?
+function Channel.by_name(name, platform) end
+
+--- Finds a channel by the Twitch user ID of its owner.
+---
+---@param string id ID of the owner of the channel.
+---@return Channel?
+function Channel.by_twitch_id(string) end
+
+---@class RoomModes
+---@field unique_chat boolean You might know this as r9kbeta or robot9000.
+---@field subscriber_only boolean
+---@field emotes_only boolean Whether or not text is allowed in messages.
+
+--- Note that "emotes" here only means Twitch emotes, not Unicode emoji, nor 3rd party text-based emotes
+
+---@field unique_chat number? Time in minutes you need to follow to chat or nil.
+
+---@field slow_mode number? Time in seconds you need to wait before sending messages or nil.
+
+---@class StreamStatus
+---@field live boolean
+---@field viewer_count number
+---@field uptime number Seconds since the stream started.
+---@field title string Stream title or last stream title
+---@field game_name string
+---@field game_id string
+-- Back to src/controllers/plugins/LuaAPI.hpp.
 
 --- Registers a new command called `name` which when executed will call `handler`.
 ---
@@ -34,22 +179,6 @@ function c2.register_command(name, handler) end
 ---@param func fun(query: string, full_text_content: string, cursor_position: integer, is_first_word: boolean): CompletionList The callback to be invoked.
 function c2.register_callback(type, func) end
 
---- Sends a message to `channel` with the specified text. Also executes commands.
----
---- **Warning**: It is possible to trigger your own Lua command with this causing a potentially infinite loop.
----
----@param channel string The name of the Twitch channel
----@param text string The text to be sent
----@return boolean ok
-function c2.send_msg(channel, text) end
-
---- Creates a system message (gray message) and adds it to the Twitch channel specified by `channel`.
----
----@param channel string
----@param text string
----@return boolean ok
-function c2.system_msg(channel, text) end
-
 --- Writes a message to the Chatterino log.
 ---
 ---@param level LogLevel The desired level.