TBL Libraries (Libs)¶

Dice rolls, referral links, coin balances, cooldowns, translations, channel gates — Libs is the bot-shaped toolbox. No imports, no setup. Type Libs. and go.

What are Libs?¶

Libs are TBL-built helper libraries for Telegram bot tasks. They load lazily on first access and run inside your command Logic field.

You get	You skip
Bot-focused systems (economy, referrals, cooldowns)	Writing glue from scratch
One global: `Libs`	Import statements
Sync + async libraries	External services for simple bot logic

Access: Libs.<libraryName>.<method>() — case-sensitive (Libs.random works, Libs.Random does not).

Storage

New libraries use async db (db.user, db.bot) — not deprecated Bot.set / User.set. Always await db-backed libs.

Pick a library¶

Library	Access	Async?	Storage	Page
`random`	`Libs.random.*`	No	—	random
`dateTimeFormat`	`Libs.dateTimeFormat.*`	No	—	dateTimeFormat
`tgutil`	`Libs.tgutil.*`	No	—	tgutil
`mcl`	`Libs.mcl.*`	Yes	—	MCL
`ResourcesLibv2`	`Libs.ResourcesLibv2.*`	Yes	`db.bot`	ResourcesLib
`refLib`	`Libs.refLib.*`	Yes	`db.user` + `db.bot`	refLib
`translate`	`Libs.translate.*`	Yes	`db.user` + `db.bot`	translate
`cooldown`	`Libs.cooldown.*`	Yes	`db.user` + `db.bot`	cooldown

Source: telebothost/tbl-libs (libsv2/ folder — 9 files, 8 active + 1 deprecated ResourcesLib.js copy).

Sync vs async¶

Type	Libraries	Rule
Sync	`random`, `dateTimeFormat`, `tgutil`, `mcl.getBtn()`	Call directly
Async	`mcl.check/quick/...`, `refLib`, `ResourcesLibv2`, `translate`, `cooldown`	Always `await`

// Async
let ok = await Libs.mcl.quick(user.id, ["@Channel"])
let count = await Libs.refLib.count()
await Libs.cooldown.tryRun("daily", 86400)

// Sync
let roll = Libs.random.randomInt(1, 6)
let name = Libs.tgutil.getNameFor(user)

.then() is not supported in TBL — use await only.

Try it — quick examples¶

Roll a dice¶

let roll = Libs.random.randomInt(1, 6)
Bot.sendMessage(chat.id, "You rolled: " + roll)

Coin balance (async economy)¶

let gold = Libs.ResourcesLibv2.userRes("gold")
await gold.add(50)
Bot.sendMessage(chat.id, "Gold: " + await gold.value())

Referral tracking¶

let result = await Libs.refLib.track({
  onJoin: async ({ referrer, count }) => {
    Bot.sendMessage(chat.id, "Referred by " + referrer.first_name + "! They have " + count + " refs.")
  }
})
let link = await Libs.refLib.register()

Daily cooldown¶

let run = await Libs.cooldown.tryRun("daily_bonus", 86400)
if (!run.ok) {
  return Bot.sendMessage(chat.id, "Come back in " + await Libs.cooldown.format("daily_bonus"))
}

Translate to user's language¶

let text = await Libs.translate.translate("Welcome!", { to: "hi" })
Bot.sendMessage(chat.id, text)

Channel gate¶

let ok = await Libs.mcl.quick(user.id, ["@MyChannel"])
if (!ok) {
  let buttons = Libs.mcl.getBtn(["@MyChannel"])
  Api.sendMessage({ chat_id: chat.id, text: "Join first!", reply_markup: { inline_keyboard: buttons } })
}

Libs or Modules?¶

	`Libs`	`modules`
What	Bot systems (economy, refs, cooldowns)	npm-style (JWT, bcrypt, CSV)
Access	`Libs.random.randomInt(1, 6)`	`modules.crypto.randomBytes(16)`
Best for	Telegram bot glue + `db` persistence	Crypto, parsing, validation

Modules docs

How Libs works¶

Behaviour	Detail
Lazy loading	Loads on first `Libs.<name>` access
Immutable	Cannot modify `Libs` object
Method timeout	2 seconds max per call
Async methods	Return Promises — use `await`
Globals	Libs can use `Bot`, `Api`, `user`, `chat`, `db`, `HTTP`

Legacy note¶

Older sync libs used deprecated Bot.getProperty / User.setProperty. They still exist in Libs/ for backward compatibility but are deprecated. Migrate to libsv2 versions that use db.

Legacy (sync)	Replacement (async)
`Libs.ResourcesLib` (Bot properties)	`Libs.ResourcesLibv2` (`db.bot`)
Old `refLib` (`REFLIB_*` keys)	`Libs.refLib` (`rfl:*` keys)
Old `translate` (`User.setProperty`)	`Libs.translate` (`db.user`)

Legacy and async db data are separate — migration requires a one-time copy command.

Pages in this section¶

Page	Covers
random	Numbers, strings, UUIDs, distributions
dateTimeFormat	Formatting, timestamps, diffs
tgutil	Names, mentions, escaping
ResourcesLib	Economy, growth, transfers, batch spend
refLib	Referral engine, leaderboard, stats
translate	Multi-language, providers, language picker
cooldown	Per-user and global cooldowns
MCL	Channel membership checks