Yukibot: YouTube Live Bot Framework
Yukibot is a YouTube livestream bot framework inspired by Strife's DSL-style and allows extensibility for custom requirements.
Installing
yarn add @pinkilo/yukibot
npm install @pinkilo/yukibot
Usage
A Basic Complete Example
import yuki from "yukibot"
async function main() {
// create a bot instance with the `yuki` dsl
const bot = await yuki((y) => {
// set how the bot refers to itself
y.yukiConfig.name = "MyBot"
// set your google API secrets
y.googleConfig = {
clientId: process.env.G_CLIENT_ID,
clientSecret: process.env.G_CLIENT_SECRET,
redirectUri: process.env.G_REDIRECT_URI,
}
y.tokenLoader = async () => ({
// provide a way to load auth tokens
// e.g., from file or a database
})
// Add a message listener which greets a chatter
y.onMessage(({ authorDetails: { displayName } }) => {
y.sendMessage(`Hello there, ${displayName}!`)
})
})
// use the bot's express app to login with OAuth
bot.express.listen(3000, () => console.log(`http://localhost:${3000}`))
// Add a listener that restarts the bot on login
bot.onAuthUpdate(() => bot.restart())
}Setup and Configuration
await yuki((y) => {
// set the bot's logging level
// useful values: error, info, debug, http, none
y.logLevel = "info"
// set how the bot refers to itself
y.yukiConfig.name = "MyBot"
// set the command prefix e.g. `>myCommand`
y.yukiConfig.prefix = /^>/
// run the bot in test mode
y.yukiConfig.test = false
/*
you can adjust the API polling rates in the
yukiConfig as well (values should be in seconds):
y.yukiConfig.chatPollRate
y.yukiConfig.broadcastPollRate
y.yukiConfig.subscriptionPollRate
*/
// set your google API secrets
y.googleConfig = {
clientId: process.env.G_CLIENT_ID,
clientSecret: process.env.G_CLIENT_SECRET,
redirectUri: process.env.G_REDIRECT_URI,
}
/*
provide a way to load auth tokens
e.g., from file or a database
!NOTE! the bot will still run if this returns undefined,
but you will have to login on each startup
*/
y.tokenLoader = async () => ({})
// use this to load users saved to file or a DB (optional)
y.userCacheLoader = async () => ({})
})Commands & Passives
await yuki(async (y) => {
// add a command which responds to `>greet` with "Hello There"
y.command((cmd) => {
cmd.name = "greet"
cmd.rateLimit.individual = 60
cmd.invoke = async () => {
await y.sendMessage("Hello There")
}
})
// add a passive, which acts like a
// message listener with a predicate
y.passive(
async (msg, tokens, self) => {
/* if this returns TRUE then the execution logic will run */
return true
},
async (msg, tokens, self) => {
/* execution logic: only runs if the predicate returns true */
}
)
// add a memoryPassive which is a normal passive
// with a convenient property for storing data
y.memoryPassive<number>(
0 /* initial state of memory */,
async () => true /* predicate */,
async (_, __, self) => {
self.memory += 1
console.log(`Messages received: ${self.memory}`)
}
)
})Extending Yukibot
You can extract the setup to one or morefunctions to sort your code!
await yuki(async y => {
extractedSetup(y)
})
function extractedSetup(builder: YukiBuilder) {
// add a message listener which removes itself
// if the message says "get out"
builder.onMessage(
({ snippet: { displayMessage } }) => {
return displayMessage.match(/^get\s+out$/)
},
async (_, match) => match !== null,
)
}Custom Routes
Each bot has its own express app which can be added upon
import yuki, { RouteConfig } from "@pinkilo/yukibot"
const routes: RouteConfig = { dashboard: "/dashboard" }
const bot = await yuki(async (y) => {
// this will add your routes to the home page for easy access
// it is optional, but useful
y.routes = routes
})
bot.express
// add custom routes
.get(routes.dashboard, (_, res) => res.status(200))
.listen(3000, () => console.log(`\nhttp://localhost:${3000}`))Testing
Live Testing
You can run your bot in "test" mode which will let you mock events through the cli.
async function main() {
// create a bot instance with the `yuki` dsl
const bot = await yuki((y) => {
y.logLevel = "debug"
y.yukiConfig.name = "MyBot"
y.yukiConfig.prefix = /^>/
y.yukiConfig.test = true
// ... see earlier examples for more dsl
})
await bot.start()
}You will be prompted to mock an event (more to come):
Select an event to mock:
1: message
2: subscription
3: auth
0: exit
choice:
Programmatic Testing
You can bypass the CLI test mode for programmatic testing, which is useful for unit tests and the like:
// This jest unit test example should pass
it("should call mock on command", async () => {
const commandName = "test"
const mockFn = jest.fn()
const ty: TestYuki = testYuki(async (y) => {
y.command(c => {
y.name = commandName
y.invoke = mockFn
})
})
await ty.feedMessage(`>${commandName}`)
expect(mockFn).toHaveBeenCalledTimes(1)
})Contributing
Contributing is highly encouraged. It's best to make an issue first to discuss what you want to add, but we won't stop you from making something cool!
Commits should be focused on specific changes and messages written with Conventional Commit:
<type>[(optional scope)][!]: <description>
[optional body]
[optional footer(s)]
Add a ! after the type and scope (if it exists) to indicate a BREAKING change.
Types:
-
feat:a new feature -
fix:a bug fix -
perf:a code change that improves performance -
refactor:a code change that neither fixes a bug nor adds a feature -
test:adding or correcting tests -
docs:documentation only changes, e.g. jsDocs, README -
build:- changes that affect the build or dependencies -
ci:Changes to our CI configuration files and scripts -
style:changes that do not affect the meaning of the code , e.g., formatting -
chore:misc. changes which do not affect the codebase in a meaningful way and do not fall under another type listed above