Table of Contents

• 🤔 About
• 📦 Installation
• 🚀 Quick Start
• 📖 API Reference
• 📡 Events
• 🔌 Adapters
• 🛠️ Custom Adapters
• 👋 Contributing & Community
• 📜 License

🤔 About

@mymanao/core is the foundational library that can be used to build a cross-platform chatbot. It is the part of the Manao Project and soon to be integrated into Manao 6.

This library only features the core essential features, not a fully-fledged chatbot framework. It can connect with the platform, handle commands, check for permissions, and it is fully extensible by adding your own platform adapters. Furthermore, this library is meant to be used for building a multiplatform chatbot, you can use it for single-platform bot but it adds an unnecessary layer of abstraction and complexity if you don't need the multiplatform features.

This library provides 4 default platform adapters that can be extended further:

• Twitch Adapter (required packages: @twurple/api @twurple/auth @twurple/chat @twurple/eventsub-ws)
• YouTube Adapter
• Kick Adapter (required packages: @manaobot/kick)
• Discord Adapter (required packages: discordx @discordx/importer discord.js)

This library is part of the Manao Project

• Manao Project (latest v5): mymanao/Manao: Everything you need, in one bot
• Manao Project (v4): mymanao/Manao-v4: Your all-in-one Twitch and Kick chatbot for music, overlays, soundboards, and more.
• Documentation: ManaoWiki

📦 Installation

bun add @mymanao/core

Install only the adapter dependencies you need:

# Twitch
bun add @twurple/api @twurple/auth @twurple/chat @twurple/eventsub-ws

# Discord
bun add discord.js discordx @discordx/importer

# Kick
bun add @manaobot/kick

# YouTube
# No additional dependencies required for the YouTube adapter

🚀 Quick Start

// MAKE SURE TO INSTALLED `@twurple/api` `@twurple/auth` `@twurple/chat` FOR THIS EXAMPLE TO WORK!
import type {CommandContext} from "@mymanao/core";
import {ManaoClient, Permission} from "@mymanao/core"
import {TwitchAdapter} from "@mymanao/core/adapters/twitch"
import type {AccessToken} from "@twurple/auth";

const client = new ManaoClient({
  prefix: {
    twitch: "!",
  },
  messages: {
    commandNotFound: "Command not found.",
    userPermissionInsufficient: "You don't have permission to use this.",
    missingArguments: (...args) => `Missing arguments: ${args.join(", ")}`,
    executionError: (error) => `Something went wrong: ${error}`,
  }
})

const twitchAdapter = new TwitchAdapter({
  scopes: ["chat:read", "chat:write"],
  client: {
    id: "...",
    secret: "...",
  },
  broadcaster: {
    id: "...",
    accessToken: "...",
    refreshToken: "...",
    channel: "...",
  },
  bot: {
    id: "...",
    accessToken: "...",
    refreshToken: "...",
  },
  onTokenRefresh: async (userType: "bot" | "broadcaster", token: AccessToken) => {
    // Save the new access and refresh tokens to your database or config file
    // Implement your own logic, the following is just an example:
    if (userType === "bot") {
      saveBotTokens(token.accessToken, token.refreshToken);
    } else if (userType === "broadcaster") {
      saveBroadcasterTokens(token.accessToken, token.refreshToken);
    }
  }
});

client.useAdapter(twitchAdapter);

const pingCommand = {
  name: "ping",
  description: "Pong!",
  permission: Permission.EVERYONE,
  execute: async (context: CommandContext) => {
    await context.reply("Pong!")
  }
}

const dateCommand = {
  name: "date",
  description: "Replies with the current date and time.",
  permission: Permission.EVERYONE,
  args: {
    name: "format",
    description: "The date format to use (optional).",
    required: false,
  },
  execute: async (context: CommandContext, args: string[]) => {
    const format = args[0] || "YYYY-MM-DD HH:mm:ss";
    const date = new Date().toLocaleString("en-US", {timeZone: "UTC"});
    await context.reply(`Current date and time: ${date}`);
  }
}

client.commandRegistry.registerAll([pingCommand, dateCommand]);

client.on("ready", (...platforms) => {
  console.log(`Bot ready on: ${platforms.join(", ")}`);
});

client.on("stopped", (...platforms) => {
  console.log(`Bot stopped on: ${platforms.join(", ")}`);
});

await client.start()

📖 API Reference

ManaoClient

The main entry point for creating a bot.

| Method | Description | |:----------------------------|:-----------------------------------------| | useAdapter(adapter) | Register a platform adapter | | start(...platforms?) | Start all or specific adapters | | stop(...platforms?) | Stop all or specific adapters | | commandRegistry | Access the CommandRegistry instance | | on(event, handler) | Register an event listener | | off(event, handler) | Remove an event listener | | enrichContext(callbackFn) | Add custom properties/methods to context |

CommandRegistry

Manages command registration and lookup.

| Method | Description | |:------------------------|:--------------------------------------| | register(command) | Register a command and its aliases | | unregister(name) | Remove a command and its aliases | | registerAll(commands) | Register multiple commands at once | | find(nameOrAlias) | Look up a command by name or alias | | all() | Get all registered commands | | size() | Get the number of registered commands |

Permission

Numeric enum for permission levels.

| Value | Level | |:-------------------------|:-----------------| | Permission.EVERYONE | Everyone | | Permission.SUBSCRIBER | Subscribers | | Permission.MODERATOR | Moderators | | Permission.BROADCASTER | Broadcaster only |

📡 Events

ManaoClient Events

| Event | Arguments | Description | |:--------------------|:-------------------|:-----------------------------------------| | "message" | context, message | Fires on every message from any platform | | "ready" | ...platforms | Fires when adapters have started | | "stopped" | ...platforms | Fires when adapters have stopped | | "commandExecuted" | context, input | Fires after a command runs |

client.on("message", (context, message) => {
  console.log(`${context.user.platform} | ${context.user.name}: ${message}`)
})

client.on("ready", (...platforms) => {
  console.log(`Bot ready on: ${platforms.join(", ")}`)
})

Adapter Events

Each adapter emits platform-specific events. Keep a reference to the adapter to listen:

const twitchAdapter = new TwitchAdapter(config)
client.useAdapter(twitchAdapter)

twitchAdapter.on("raid", (raider, viewers) => { ...
})
twitchAdapter.on("subscribe", (user, tier) => { ...
})
twitchAdapter.on("follow", (user) => { ...
})
twitchAdapter.on("cheer", (user, bits) => { ...
})
twitchAdapter.on("giftSubscribe", (gifter, amount) => { ...
})
twitchAdapter.on("redemption", (rewardId, rewardTitle, user) => { ...
})

Kick:

const kickAdapter = new KickAdapter(config)
client.useAdapter(kickAdapter)

kickAdapter.on("follow", (user) => { ...
})
kickAdapter.on("subscribe", (user) => { ...
})
kickAdapter.on("subscribeRenew", (user) => { ...
})
kickAdapter.on("giftSubscribe", (gifter, amount) => { ...
})
kickAdapter.on("redemption", (rewardId, rewardTitle, user) => { ...
})
kickAdapter.on("streamStatus", (isLive) => { ...
})
kickAdapter.on("streamMetadata", (title, category) => { ...
})
kickAdapter.on("ban", (user, expiresAt) => { ...
})
kickAdapter.on("kicksGifted", (gifter, amount) => { ...
})

Discord:

const discordAdapter = new DiscordAdapter(config)
client.useAdapter(discordAdapter)

discordAdapter.on("guildMemberAdd", (member) => { ...
})
discordAdapter.on("guildMemberRemove", (member) => { ...
})
discordAdapter.on("messageReactionAdd", (reaction, user) => { ...
})
discordAdapter.on("voiceStateUpdate", (oldState, newState) => { ...
})
discordAdapter.on("guildBanAdd", (ban) => { ...
})
// ...and more discord.js events

🔌 Adapters

@mymanao/core ships with 4 built-in platform adapters. Each adapter extends CommandContext with platform-specific methods.

Twitch (@mymanao/core/adapters/twitch)

Importing the adapter:

import {TwitchAdapter} from "@mymanao/core/adapters/twitch"

Type definitions:

export interface TwitchAdapterConfig {
  client: {
    id: string;
    secret: string;
  };
  bot: {
    id: string;
    accessToken: string;
    refreshToken: string;
  };
  broadcaster: {
    id: string;
    accessToken: string;
    refreshToken: string;
    channel: string;
  };
  scopes?: string[];
  onTokenRefresh?: (userType: "bot" | "broadcaster", token: AccessToken) => Promise<void>;
}

export interface TwitchCommandContext extends CommandContext {
  whisper: (message: string) => Promise<void>;
  setGame: (gameName: string) => Promise<string | null>;
  setTitle: (title: string) => Promise<void>;
  announce: (message: string) => Promise<void>;
  shoutout: (targetName: string) => Promise<boolean>;
  getUptime: () => Promise<Date | null>;
}

Discord (@mymanao/core/adapters/discord)

Importing the adapter:

import {DiscordAdapter} from "@mymanao/core/adapters/discord"

Type definitions:

export interface DiscordAdapterConfig {
  botToken: string;
}

export interface DiscordCommandContext extends CommandContext {
  whisper: (message: string) => Promise<void>;
}

Kick (@mymanao/core/adapters/kick)

Importing the adapter:

import {KickAdapter} from "@mymanao/core/adapters/kick"

Type definitions:

export interface KickAdapterConfig {
  client: {
    id: string;
    secret: string;
  };
  auth: {
    accessToken: string;
    refreshToken: string;
    expiresAt: number;
    scopes?: KickScopes[];
    port?: number;
    onTokenRefresh?: (tokens: KickTokenResponse) => Promise<void>;
  };
  ngrok: {
    authtoken: string;
    domain: string;
    port?: number;
  };
}

export interface KickCommandContext extends CommandContext {
  getUptime: () => Promise<Date | null>;
}

YouTube (@mymanao/core/adapters/youtube)

Importing the adapter:

import {YoutubeAdapter} from "@mymanao/core/adapters/youtube"

Type definitions:

export interface YoutubeAdapterConfig {
  client: {
    id: string;
    secret: string;
  };
  auth: {
    accessToken: string;
    refreshToken: string;
    onTokenRefresh?: (newAccessToken: string) => Promise<void>;
  };
}

export interface YoutubeCommandContext extends CommandContext {
}

🛠️ Custom Adapters

You can build your own adapter by extending PlatformAdapter:

import {PlatformAdapter} from "@mymanao/core"
import type {CommandContext, MessageHandler} from "@mymanao/core"

interface MyPlatformContext extends CommandContext {
  myCustomMethod: () => Promise
}

class MyPlatformAdapter extends PlatformAdapter {
  readonly platform = "myplatform"

  private handler?: MessageHandler

  constructor() {
    super()
  }

  async start(): Promise {
    // Connect to platform
    // Call this.handler?.(ctx, message) on each incoming message
    // Use this.emit("eventName", ...args) for platform-specific events
  }

  async stop(): Promise {
    // Disconnect
  }

  async sendMessage(channel: string, message: string): Promise {
    // Send message to platform
  }

  onMessage(handler: MessageHandler): void {
    this.handler = handler
  }
}

👋 Contributing & Community

Contributions are welcome! Please review our CONTRIBUTING.md before opening a Pull Request.

Have questions or want to discuss a feature? Join our Discord server.

📜 License

Licensed under the GNU General Public License v3.0. See the GNU Official Website for full details.

Manao is not affiliated with Twitch Interactive, Inc., Kick Streaming Pty Ltd, or Discord Inc. in any way. All trademarks are property of their respective owners. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.