twitch-chat-client/lib/ChatClient.d.ts

Interact with the Twitch Messaging Interface (aka Twitch chat).

import { Client as IRCClient } from 'ircv3';
import { Listener } from 'ircv3/lib/TypedEventEmitter';
import TwitchClient from 'twitch';
import { LogLevel } from '@d-fischer/logger';
import ChatSubInfo, { ChatSubGiftInfo } from './UserNotices/ChatSubInfo';
import UserNotice from './Capabilities/TwitchCommands/MessageTypes/UserNotice';
import Whisper from './Capabilities/TwitchCommands/MessageTypes/Whisper';
import TwitchPrivateMessage from './StandardCommands/PrivateMessage';
import ChatRaidInfo from './UserNotices/ChatRaidInfo';
import ChatRitualInfo from './UserNotices/ChatRitualInfo';
import ChatCommunitySubInfo from './UserNotices/ChatCommunitySubInfo';
import ChatBitsBadgeUpgradeInfo from './UserNotices/ChatBitsBadgeUpgradeInfo';
/**
 * Options for a chat client.
 */
export interface ChatClientOptions {
    /**
     * Whether to request a token with only read permission.
     *
     * Ignored if `legacyScopes` is `true`.
     */
    readOnly?: boolean;
    /**
     * Whether to request a token with the old chat permission scope.
     *
     * If you're not sure whether this is necessary, just try leaving this off, and if it doesn't work, turn it on and try again.
     */
    legacyScopes?: boolean;
    /**
     * The minimum log level of messages that will be sent from the underlying IRC client.
     */
    logLevel?: LogLevel;
    /**
     * Whether to disable the secure connection using SSL.
     *
     * You should not use this except for debugging purposes.
     *
     * @deprecated Use the `.ssl` property instead.
     */
    disableSsl?: boolean;
    /**
     * Whether to connect securely using SSL.
     *
     * You should not disable this except for debugging purposes.
     */
    ssl?: boolean;
    /**
     * Whether to connect to IRC directly instead of using the WebSocket servers.
     *
     * @deprecated Use the `.webSocket` property instead.
     */
    rawIrc?: boolean;
    /**
     * Whether to use a WebSocket to connect to chat.
     */
    webSocket?: boolean;
    /**
     * Whether to receive JOIN and PART messages from Twitch chat.
     *
     * This is currently on by default, but will change to off by default in version 3.0.
     */
    requestMembershipEvents?: boolean;
}
/**
 * Options for a chat client, including authentication details.
 *
 * @inheritDoc
 */
export interface ChatClientOptionsWithAuth extends ChatClientOptions {
    /**
     * The user name you want to connect with.
     */
    userName: string;
    /**
     * The token to use for connecting.
     */
    token?: string;
}
/**
 * An interface to Twitch chat.
 *
 * @inheritDoc
 * @hideProtected
 */
export default class ChatClient extends IRCClient {
    private static readonly HOST_MESSAGE_REGEX;
    /** @private */
    readonly _twitchClient?: TwitchClient;
    /**
     * Fires when a user is timed out from a channel.
     *
     * @eventListener
     * @param channel The channel the user is timed out from.
     * @param user The timed out user.
     * @param reason The reason for the timeout.
     * @param duration The duration of the timeout, in seconds.
     */
    onTimeout: (handler: (channel: string, user: string, reason: string, duration: number) => void) => Listener;
    /**
     * Fires when a user is permanently banned from a channel.
     *
     * @eventListener
     * @param channel The channel the user is banned from.
     * @param user The banned user.
     * @param reason The reason for the ban.
     */
    onBan: (handler: (channel: string, user: string, reason: string) => void) => Listener;
    /**
     * Fires when a user upgrades their bits badge in a channel.
     *
     * @eventListener
     * @param channel The channel where the bits badge was upgraded.
     * @param user The user that has upgraded their bits badge.
     * @param ritualInfo Additional information about the upgrade.
     * @param msg The raw message that was received.
     */
    onBitsBadgeUpgrade: (handler: (channel: string, user: string, upgradeInfo: ChatBitsBadgeUpgradeInfo, msg: UserNotice) => void) => Listener;
    /**
     * Fires when the chat of a channel is cleared.
     *
     * @eventListener
     * @param channel The channel whose chat is cleared.
     */
    onChatClear: (handler: (channel: string) => void) => Listener;
    /**
     * Fires when emote-only mode is toggled in a channel.
     *
     * @eventListener
     * @param channel The channel where emote-only mode is being toggled.
     * @param enabled Whether emote-only mode is being enabled. If false, it's being disabled.
     */
    onEmoteOnly: (handler: (channel: string, enabled: boolean) => void) => Listener;
    /**
     * Fires when followers-only mode is toggled in a channel.
     *
     * @eventListener
     * @param channel The channel where followers-only mode is being toggled.
     * @param enabled Whether followers-only mode is being enabled. If false, it's being disabled.
     * @param delay The time a user needs to follow the channel to be able to talk. Only available when `enabled === true`.
     */
    onFollowersOnly: (handler: (channel: string, enabled: boolean, delay?: number) => void) => Listener;
    /**
     * Fires when a channel hosts another channel.
     *
     * @eventListener
     * @param channel The hosting channel.
     * @param target The channel that is being hosted.
     * @param viewers The number of viewers in the hosting channel.
     *
     *   If you're not logged in as the owner of the channel, this is undefined.
     */
    onHost: (handler: (channel: string, target: string, viewers?: number) => void) => Listener;
    /**
     * Fires when a channel you're logged in as its owner is being hosted by another channel.
     *
     * @eventListener
     * @param channel The channel that is being hosted.
     * @param byChannel The hosting channel.
     * @param auto Whether the host was triggered automatically (by Twitch's auto-host functionality).
     * @param viewers The number of viewers in the hosting channel.
     */
    onHosted: (handler: (channel: string, byChannel: string, auto: boolean, viewers?: number) => void) => Listener;
    /**
     * Fires when Twitch tells you the number of hosts you have remaining in the next half hour for the channel
     * for which you're logged in as owner after hosting a channel.
     *
     * @eventListener
     * @param channel The hosting channel.
     * @param numberOfHosts The number of hosts remaining in the next half hour.
     */
    onHostsRemaining: (handler: (channel: string, numberOfHosts: number) => void) => Listener;
    /**
     * Fires when a user joins a channel.
     *
     * The join/part events are cached by the Twitch chat server and will be batched and sent every 30-60 seconds.
     *
     * @eventListener
     * @param channel The channel that is being joined.
     * @param user The user that joined.
     */
    onJoin: (handler: (channel: string, user: string) => void) => Listener;
    /**
     * Fires when a user leaves ("parts") a channel.
     *
     * The join/part events are cached by the Twitch chat server and will be batched and sent every 30-60 seconds.
     *
     * @eventListener
     * @param channel The channel that is being left.
     * @param user The user that left.
     */
    onPart: (handler: (channel: string, user: string) => void) => Listener;
    /**
     * Fires when R9K mode is toggled in a channel.
     *
     * @eventListener
     * @param channel The channel where R9K mode is being toggled.
     * @param enabled Whether R9K mode is being enabled. If false, it's being disabled.
     */
    onR9k: (handler: (channel: string, enabled: boolean) => void) => Listener;
    /**
     * Fires when host mode is disabled in a channel.
     *
     * @eventListener
     * @param channel The channel where host mode is being disabled.
     */
    onUnhost: (handler: (channel: string) => void) => Listener;
    /**
     * Fires when a user raids a channel.
     *
     * @eventListener
     * @param channel The channel that was raided.
     * @param user The user that has raided the channel.
     * @param raidInfo Additional information about the raid.
     * @param msg The raw message that was received.
     */
    onRaid: (handler: (channel: string, user: string, raidInfo: ChatRaidInfo, msg: UserNotice) => void) => Listener;
    /**
     * Fires when a user performs a "ritual" in a channel.
     *
     * @eventListener
     * @param channel The channel where the ritual was performed.
     * @param user The user that has performed the ritual.
     * @param ritualInfo Additional information about the ritual.
     * @param msg The raw message that was received.
     */
    onRitual: (handler: (channel: string, user: string, ritualInfo: ChatRitualInfo, msg: UserNotice) => void) => Listener;
    /**
     * Fires when slow mode is toggled in a channel.
     *
     * @eventListener
     * @param channel The channel where slow mode is being toggled.
     * @param enabled Whether slow mode is being enabled. If false, it's being disabled.
     * @param delay The time a user has to wait between sending messages. Only set when enabling slow mode.
     */
    onSlow: (handler: (channel: string, enabled: boolean, delay?: number) => void) => Listener;
    /**
     * Fires when sub only mode is toggled in a channel.
     *
     * @eventListener
     * @param channel The channel where sub only mode is being toggled.
     * @param enabled Whether sub only mode is being enabled. If false, it's being disabled.
     */
    onSubsOnly: (handler: (channel: string, enabled: boolean) => void) => Listener;
    /**
     * Fires when a user subscribes to a channel.
     *
     * @eventListener
     * @param channel The channel that was subscribed to.
     * @param user The subscribing user.
     * @param subInfo Additional information about the subscription.
     * @param msg The raw message that was received.
     */
    onSub: (handler: (channel: string, user: string, subInfo: ChatSubInfo, msg: UserNotice) => void) => Listener;
    /**
     * Fires when a user resubscribes to a channel.
     *
     * @eventListener
     * @param channel The channel that was resubscribed to.
     * @param user The resubscribing user.
     * @param subInfo Additional information about the resubscription.
     * @param msg The raw message that was received.
     */
    onResub: (handler: (channel: string, user: string, subInfo: ChatSubInfo, msg: UserNotice) => void) => Listener;
    /**
     * Fires when a user gifts a subscription to a channel to another user.
     *
     * @eventListener
     * @param channel The channel that was subscribed to.
     * @param user The user that the subscription was gifted to. The gifting user is defined in `subInfo.gifter`.
     * @param subInfo Additional information about the subscription.
     * @param msg The raw message that was received.
     */
    onSubGift: (handler: (channel: string, user: string, subInfo: ChatSubGiftInfo, msg: UserNotice) => void) => Listener;
    /**
     * Fires when a user gifts random subscriptions to the community of a channel.
     *
     * @eventListener
     * @param channel The channel that was subscribed to.
     * @param user The gifting user.
     * @param subInfo Additional information about the community subscription.
     * @param msg The raw message that was received.
     */
    onCommunitySub: (handler: (channel: string, user: string, subInfo: ChatCommunitySubInfo, msg: UserNotice) => void) => Listener;
    /**
     * Fires when receiving a whisper from another user.
     *
     * @eventListener
     * @param user The user that sent the whisper.
     * @param message The message text.
     * @param msg The raw message that was received.
     */
    onWhisper: (handler: (user: string, message: string, msg: Whisper) => void) => Listener;
    /**
     * Fires when you tried to execute a command you don't have sufficient permission for.
     *
     * @eventListener
     * @param channel The channel that a command without sufficient permissions was executed on.
     * @maram message The message text.
     */
    onNoPermission: (handler: (channel: string, message: string) => void) => Listener;
    /**
     * Fires when a user sends a message to a channel.
     *
     * @eventListener
     * @param channel The channel the message was sent to.
     * @param user The user that send the message.
     * @param message The message text.
     * @param msg The raw message  that was received.
     */
    onPrivmsg: (handler: (channel: string, user: string, message: string, msg: TwitchPrivateMessage) => void) => Listener;
    private readonly _onBanResult;
    private readonly _onTimeoutResult;
    private readonly _onUnbanResult;
    private readonly _onColorResult;
    private readonly _onCommercialResult;
    private readonly _onEmoteOnlyResult;
    private readonly _onEmoteOnlyOffResult;
    private readonly _onFollowersOnlyResult;
    private readonly _onFollowersOnlyOffResult;
    private readonly _onHostResult;
    private readonly _onUnhostResult;
    private readonly _onModResult;
    private readonly _onUnmodResult;
    private readonly _onModsResult;
    private readonly _onJoinResult;
    private readonly _onR9kResult;
    private readonly _onR9kOffResult;
    private readonly _onSlowResult;
    private readonly _onSlowOffResult;
    private readonly _onSubsOnlyResult;
    private readonly _onSubsOnlyOffResult;
    /**
     * Creates a new Twitch chat client with the user info from the TwitchClient instance.
     *
     * @expandParams
     *
     * @param twitchClient The TwitchClient instance to use for user info and API requests.
     * @param options
     */
    static forTwitchClient(twitchClient: TwitchClient, options?: ChatClientOptions): Promise<ChatClient>;
    /**
     * Creates a new anonymous Twitch chat client.
     *
     * @expandParams
     *
     * @param twitchClient Currently deprecated and ignored. You can safely pass undefined here.
     * @param options
     */
    static anonymous(twitchClient?: TwitchClient, options?: ChatClientOptions): ChatClient;
    /**
     * Creates a new Twitch chat client.
     *
     * @expandParams
     *
     * @param twitchClient The {@TwitchClient} instance to use for API requests.
     * @param options
     */
    constructor(twitchClient: TwitchClient | undefined, options: ChatClientOptionsWithAuth);
    /**
     * Hosts a channel on another channel.
     *
     * @param target The host target, i.e. the channel that is being hosted.
     * @param channel The host source, i.e. the channel that is hosting. Defaults to the channel of the connected user.
     */
    host(target: string, channel?: string): Promise<void>;
    /**
     * Ends any host on a channel.
     *
     * This only works when in the channel that was hosted in order to provide feedback about success of the command.
     *
     * If you don't need this feedback, consider using {@ChatClient#unhostOutside} instead.
     *
     * @param channel The channel to end the host on. Defaults to the channel of the connected user.
     */
    unhost(channel?: string): Promise<void>;
    /**
     * Ends any host on a channel.
     *
     * This works even when not in the channel that was hosted, but provides no feedback about success of the command.
     *
     * If you need feedback about success, use {@ChatClient#unhost} (but make sure you're in the channel you are hosting).
     *
     * @param channel The channel to end the host on. Defaults to the channel of the connected user.
     */
    unhostOutside(channel?: string): void;
    say(channel: string, message: string): void;
    join(channel: string): Promise<void>;
    quit(): Promise<void>;
    protected registerCoreMessageTypes(): void;
}