XLive SDK Interface

xLiveSDK.ts

interface Window {
    X_LIVE_SDK: XLiveSDK;
}

/**
 * A user account
 * @property {string} id - The unique identifier for the user
 * @property {string} name - The username of the user (unique)
 * @property {string} displayName - The display name of the user
 * @property {string} avatarUrl - The avatar URL for the user
 */
interface User {
    // The unique identifier for the user
    id: string;
    // The username of the user (unique)
    name: string;
    // The display name of the user
    displayName: string;
    // The avatar URL for the user
    avatarUrl: string;
    // ... other properties
}

/**
 * A chat message
 * @property {string} text - The text of the message
 * @property {User} author - The user who sent the message
 * @property {HTMLElement} el - The HTML element that represents the message
 */
interface Message {
    id: string;
    text: string;
    author: User;
    el: HTMLElement;
    // ... other properties
}

/**
 * A chat channel
 * @property {string} id - The unique identifier for the channel
 * @property {string} name - The name of the channel
 * @property {User} user - The user who owns the channel
 * @property {boolean} loginRequired - Whether or not the channel requires a login to message
 */
interface Channel {
    id: string;
    name: string;
    user: User;
    loginRequired: boolean;
    // ... other properties
}

/**
 * An error
 * @property {string} message - The error message
 */
interface XLiveError {
    message: string;
}

/**
 * The events that can be listened for
 */
type HookEvents = {
    /**
     * A callback that is called when a chat message is received and rendered in the chat
     * @param {User} author - The user who sent the message
     * @param {Message} message - The message that was sent
     * @returns {void}
     */
    chatMessage: (message: Message) => void;

    /**
     * A callback that is called when the channel is changed
     * @param {Channel} channel - The new channel
     * @returns {void}
     */
    channelChange: (channel: Channel | null) => void;

    /**
     * A callback that is called when a message is deleted from the chat
     * @param {string} id - The unique identifier for the message that was deleted
     * @returns {void}
     */
    chatMessageDeleted: (id: string) => void;

    /**
     * A callback when a user is timed out or banned from the chat
     * @param {User} user - The user who was timed out or banned
     * @param {number | null} duration - The duration of the timeout or ban in seconds (null if permanent)
     * @returns {void}
     */
    userTimedOut: (user: User, duration: number | null) => void;
}

interface XLiveSDK {
    /**
     * Get the current user
     * @returns {User} The current user or null if there is no user
     */
    getUser(): User | null;

    /**
     * Get the current channel
     * @returns {Channel} The current channel or null if there is no channel
     */
    getChannel(): Channel | null;

    /**
     * Send a message to the chat
     * @param {string} message - The message to send
     * @returns {void}
     * @throws {XLiveError} If the user is not logged in or some other error occurs
     */
    sendChatMessage(message: string): void;

    /**
     * Timeout a user from the chat
     * @param {User} user - The user to timeout
     * @param {number | null} duration - The duration of the timeout in seconds, or null for a permanent ban
     * @returns {void}
     * @throws {XLiveError} If the user is not a moderator or admin or some other error occurs
     */
    timeoutUser(user: User, duration: number | null): void;

    /**
     * Register a hook to listen for events
     * @param {string} id - The unique identifier for the hook
     * @param {keyof HookEvents} event - The event to listen for
     * @param {HookEvents[keyof HookEvents]} callback - The callback to call when the event is triggered
     * @returns {void}
     */
    registerHook<K extends keyof HookEvents>(id: string, event: K, callback: HookEvents[K]): void;

    /**
     * Unregister a hook
     * @param {string} id - The unique identifier for the hook
     * @param {keyof HookEvents} event - The event to unregister
     * @returns {void}
     */
    unregisterHook<K extends keyof HookEvents>(id: string, event: K): void;
}