CFWLib - Telegram Bot Library for Cloudflare Workers - Documentation

CFWLib - Documentation

Telegram Bot Library for Cloudflare Workers - Developer: MzCoder

Pengantar

CFWLib (Cloudflare Workers Library Bot) adalah *framework* yang dirancang khusus untuk membangun bot Telegram menggunakan lingkungan Cloudflare Workers. Framework ini mengabstraksi kompleksitas interaksi dengan Telegram Bot API, penanganan *update*, dan manajemen alur kerja bot.

Dibangun berdasarkan inspirasi dari GASLibv3, CFWLib menyediakan struktur kelas yang rapi, termasuk *handler* berbasis `Composer`, *context* pesan (`Context`), dan klien HTTP khusus untuk API Telegram (`Telegram` dan `Client`). Tujuannya adalah membuat pengembangan bot berkinerja tinggi di lingkungan tanpa server menjadi efisien.

Sekilas tentang Framework

CFWLib adalah koleksi kelas JavaScript modular yang membagi tanggung jawab utama bot:

  • **CFWLib (Main)**: Menginisiasi bot dan mengelola siklus hidup *update*.
  • **Telegram/Client**: Mengelola komunikasi HTTP dengan API Telegram.
  • **Context**: Menyediakan akses mudah ke data pesan dan metode respons cepat.
  • **Composer**: Mengimplementasikan sistem *middleware* dan *handler* (perintah, aksi, dll.).
  • **Helper/Markup/Extra**: Menyediakan alat bantu utilitas dan pembangun markup keyboard/opsi pesan.

Konsep

Dasar Pondasi atau Flow (Alur Kerja)

  1. **Request Masuk**: Fungsi doPost(request) menerima permintaan HTTP dari Telegram Webhook.
  2. **Parsing Update**: Permintaan diurai menjadi objek update JSON Telegram.
  3. **Inisiasi Context**: Objek update dibungkus ke dalam objek **Context** (ctx), yang juga menerima instance Telegram.
  4. **Middleware & Handler**: Objek ctx dilewatkan melalui fungsi-fungsi *middleware* dan *handler* (this.handler) yang terdaftar di **Composer** (yang diwarisi oleh CFWLib).
  5. **Eksekusi Trigger**: Setelah *middleware* selesai, execTrigger() menjalankan *handler* spesifik berdasarkan tipe pesan (e.g., perintah `/cmd`, teks, *callback query*).
  6. **Broadcast Event**: Jika tidak ada *trigger* yang cocok, broadcast() memicu event berdasarkan tipe *update* (misalnya, `message`, `callback_query`, `text`, `photo`, dll.) yang dapat didengar oleh bot.on('type', fn).
  7. **Respons Cepat**: Metode respons cepat seperti ctx.reply() atau ctx.answerCbQuery() digunakan untuk berinteraksi kembali dengan API Telegram melalui instance this.telegram.

Inisiasi

Inisiasi dan Options

new CFWLib(token, options)

Membuat instance bot utama. CFWLib mewarisi Composer, memungkinkan pendaftaran *handler* langsung padanya.

  • token (String): Token API Bot Telegram Anda (Wajib).
  • options (Object): Opsi konfigurasi.
    • prefix_command (String, default: /): Awalan untuk perintah bot.
    • username (String, default: ''): Username bot (tanpa '@'), digunakan untuk mengenali perintah seperti `/start@MyBot`.
    • log_id (Number/String): ID Chat untuk mengirim log error atau debug.
Contoh Penggunaan: 
import CFWLib from './cfwlib.js'; // Asumsikan class di-export

const BOT_TOKEN = 'YOUR_TELEGRAM_BOT_TOKEN';

const bot = new CFWLib(BOT_TOKEN, {
    username: 'MyAwesomeBot',
    log_id: 123456789 // ID Chat Log
});

bot.command('start', (ctx) => {
    ctx.reply('Selamat datang!');
});

// Menangani permintaan Webhook dari Cloudflare Workers
addEventListener('fetch', event => {
    event.respondWith(
        event.request.method === 'POST' 
            ? bot.doPost(event.request) 
            : new Response('CFWLib Bot is running!', { status: 200 })
    );
});

CFWLib (Bot Base)

Base Variable Bot sebagai Object Base

Kelas utama yang mewarisi Composer dan mengelola siklus hidup *update* masuk.

bot.command(keys, callback) / bot.cmd(...)

Mendaftarkan *handler* untuk perintah bot (misalnya, /start, /help).

Contoh: 
bot.command(['info', 'about'], (ctx) => {
    ctx.reply('Ini adalah bot CFWLib.');
});
bot.hear(keys, callback) / bot.hears(...)

Mendaftarkan *handler* untuk teks spesifik yang dikirim oleh pengguna.

Contoh: 
bot.hear('Halo Dunia', (ctx) => {
    ctx.reply('Halo juga!');
});
bot.action(keys, callback)

Mendaftarkan *handler* untuk callback_data dari tombol *inline*.

Contoh: 
bot.action('klik_saya', (ctx) => {
    ctx.answerCbQuery('Tombol diklik!');
});
bot.on(events, ...listeners)

Mendaftarkan *listener* untuk tipe *update* spesifik (*broadcast* event).

Contoh: 
// Menangani semua pesan foto
bot.on('photo', (ctx) => {
    ctx.reply('Terima kasih fotonya!');
});

// Menangani semua update yang bukan pesan (e.g., edited_message)
bot.on(['edited_message', 'poll'], (ctx) => {
    console.log('Update non-pesan diterima:', ctx.updateType);
});
bot.use(...fns) / bot.middleware(...fns)

Mendaftarkan fungsi *middleware* yang akan dieksekusi sebelum *handler* dan *trigger*.

Contoh: 
bot.use((ctx, next) => {
    console.log('Middleware dipanggil:', ctx.updateType);
    ctx.state.isCool = true; // Menyimpan state untuk digunakan di handler
    return next(); // PENTING: Lanjut ke handler berikutnya
});
bot.doPost(request)

Metode utama untuk memproses permintaan Webhook dari Cloudflare Workers. Mengambil objek Request, memverifikasi content-type, mem-parsing JSON, dan memanggil handleUpdate().

Telegram (API Client)

Semua berkenaan dengan method dari bot API Telegram

Kelas Telegram (dapat diakses melalui bot.tg atau ctx.telegram) menyediakan antarmuka langsung dan lengkap ke semua metode resmi Telegram Bot API. Metode ini biasanya menerima chatId sebagai parameter pertama.

tg.sendMessage(chatId, text, extra)

Mengirim pesan teks ke chat tertentu. Metode respons cepat ctx.sendMessage() dan ctx.reply() adalah *shortcut* untuk ini.

Contoh: 
// Menggunakan bot.tg
bot.tg.sendMessage(123456789, 'Halo!');
tg.sendPhoto(chatId, photo, extra)

Mengirim foto. Parameter photo dapat berupa file_id atau Blob/File jika menggunakan FormData (perhatikan kebutuhan untuk FormData/Blob di CF Workers).

tg.editMessageText(chatId, messageId, inlineMessageId, text, extra)

Mengedit pesan teks. Digunakan untuk pesan yang dikirim di chat atau pesan *inline* (jika inlineMessageId diisi).

tg.getMe()

Mengembalikan informasi dasar tentang bot.

... dan semua metode Telegram API lainnya (getFile, setWebhook, getChatMember, answerInlineQuery, dll.) tersedia dengan pola nama yang konsisten.

Context

Variable yang menghandle update pesan dari Telegram dan metod-metod respon cepat terhadapnya

Objek **Context** (ctx) adalah wadah data spesifik per *update*. Ini menyediakan semua properti *update* Telegram sebagai *getter* dan metode respons yang menyederhanakan interaksi.

ctx.update

Objek update mentah dari Telegram.

ctx.updateType

String yang menunjukkan tipe utama dari *update* (misalnya, 'message', 'callback_query').

ctx.message / ctx.callbackQuery / ctx.inlineQuery ...

Getter ke objek spesifik dalam update (misalnya, ctx.message mengembalikan objek *Message* jika *update* adalah pesan baru).

ctx.chat / ctx.from

Getter untuk mendapatkan objek Chat dan User pengirim, terlepas dari tipe *update* (mengambil data dari message, callbackQuery, dsb.).

ctx.state

Objek sederhana untuk menyimpan data state di antara *middleware* dan *handler* dalam siklus *update* yang sama.

ctx.reply(text, extra)

Metode respons cepat: ctx.reply(...) setara dengan ctx.telegram.sendMessage(ctx.chat.id, ...). Secara otomatis mengetahui ID chat.

ctx.replyIt(text, extra)

Mengirim pesan balasan (reply) ke pesan yang sedang diproses. Secara otomatis mengatur reply_to_message_id.

ctx.answerCbQuery(text, extra)

Metode respons cepat untuk callback_query. Secara otomatis menggunakan callback_query.id.

ctx.editMessageText(text, extra)

Metode respons cepat untuk mengedit teks pesan dari *callback query* (pesan yang berisi tombol yang diklik). Secara otomatis menggunakan ID pesan atau ID pesan *inline*.

ctx.deleteMessage(messageId)

Menghapus pesan. Jika messageId tidak disediakan, pesan yang sedang diproses akan dihapus.

Update Type

Tipe-tipe update yang tersedia untuk context

Properti ctx.updateType dan *getter* di Context memungkinkan penanganan tipe *update* spesifik. Berikut tipe-tipe utama yang tersedia (yang juga digunakan untuk bot.on('type', fn)):

  • message: Pesan baru dari chat pribadi, grup, atau supergrup.
  • edited_message: Pesan yang telah disunting.
  • channel_post: Pesan baru dari channel.
  • edited_channel_post: Pesan channel yang telah disunting.
  • callback_query: Klik tombol *inline* dengan callback_data.
  • inline_query: Permintaan dari mode *inline*.
  • chosen_inline_result: Pengguna memilih hasil dari *inline query*.
  • chat_member / my_chat_member: Perubahan status anggota di chat (penting untuk bot admin).
  • shipping_query / pre_checkout_query: Update dari proses pembayaran.
  • poll / poll_answer: Update dari mekanisme poling/voting.

Helper

Koleksi method bantuan guna keperluaan saat development

Kelas Helper (di-export sebagai helper) berisi utilitas umum yang membantu validasi dan manipulasi data.

helper.hasProp(obj, prop)

Mengecek apakah objek memiliki properti tertentu.

helper.compactOptions(options)

Menghapus properti yang memiliki nilai undefined dari objek, berguna untuk membersihkan objek opsi API.

Contoh: 
const options = helper.compactOptions({ a: 1, b: undefined, c: 3 }); 
// Hasil: { a: 1, c: 3 }
helper.typeCheck(value)

Mengembalikan tipe objek/nilai dalam format string kecil (misalnya, 'array', 'object', 'string').

helper.clearHTML(s) / helper.clearMarkdown(s)

Membersihkan string dari karakter spesial HTML (<, >, &) atau Markdown (*, _, [, `) untuk menghindari masalah parsing saat mengirim teks biasa.

helper.nama(data) / helper.name(data)

Mengambil objek pengguna Telegram (dari ctx.from atau lainnya) dan mengembalikan objek dengan nama lengkap (*full name*), username, dan representasi HTML-nya.

Contoh: 
const { html } = helper.name(ctx.from);
ctx.replyWithHTML(`Hai ${html}!`); 
// Mengirim pesan dengan nama user dalam format tebal (HTML)

Markup, Button, & Extra

Kelas-kelas ini menyediakan cara yang mudah dan terstruktur untuk membuat *keyboard* dan opsi pesan tambahan.

Button (Button Factory - Instance)

Kelas Button (di-export sebagai button) adalah pabrik yang membuat objek tombol individual.

button.text(text, data, hide) / button.inline(...)

Membuat tombol *inline* dengan callback_data.

button.url(text, url, hide)

Membuat tombol *inline* tautan URL.

button.queryChat(text, data) / button.query(...)

Membuat tombol *inline* untuk berpindah ke mode *inline* di chat saat ini atau chat lain.

Markup (Keyboard Builder - Static & Chainable)

Kelas Markup (di-export sebagai markup) digunakan untuk membangun objek *reply_markup* secara berantai (*chainable*) atau melalui metode statis.

Markup.inlineKeyboard(buttons, options)

Membuat objek *reply_markup* dengan tombol *inline*. Tombol harus dibuat dengan button atau metode statis Markup.*Button.

Contoh: 
const keyboard = markup.inlineKeyboard([
    markup.callbackButton('Ya', 'data_ya'),
    markup.urlButton('Google', 'https://google.com')
], { columns: 2 });

ctx.reply('Pilih:', keyboard.extra()); 
// .extra() mengubah Markup menjadi objek ekstra yang dapat digunakan
Markup.keyboard(buttons, options)

Membuat objek *reply_markup* untuk *Reply Keyboard* (keyboard standar). Default columns: 1.

Markup.removeKeyboard(value = true)

Statis atau *chainable*: Opsi untuk menghapus *Reply Keyboard* saat ini.

Markup.formatHTML(text, entities)

Fungsi statis untuk mengubah pesan Telegram yang memiliki entities (misalnya, teks tebal, miring) menjadi format HTML. Berguna saat mem-*forward* pesan dan ingin mempertahankan format.

Extra (Message Options Builder - Chainable)

Kelas Extra (di-export sebagai extra) adalah pembangun yang nyaman untuk opsi pesan non-*keyboard* (misalnya, *parse_mode*, *reply_to_message_id*).

Extra.HTML(value = true)

Mengatur parse_mode menjadi HTML.

Extra.inReplyTo(messageId)

Mengatur reply_to_message_id.

Extra.markup(markup)

Menambahkan objek *reply_markup* yang dibangun oleh Markup.

Contoh: 
const opts = extra.HTML()
    .inReplyTo(ctx.message.message_id)
    .markup(m => m.inlineKeyboard([button.text('Tutup', 'close')]));

ctx.reply('Pesan dengan balasan dan keyboard', opts);