# Panduan Migrasi & Dokumentasi grammY

Dokumen ini berisi panduan dasar mengenai framework `grammY` untuk pengembangan bot Telegram, khususnya untuk migrasi dari framework `Telegraf`.

## Apa itu grammY?

`grammY` (tersedia di [grammy.dev](https://grammy.dev/)) adalah framework modern untuk membuat bot Telegram dengan TypeScript atau Node.js. `grammY` didesain untuk performa tinggi, keamanan tipe data (type-safety), dan memiliki ekosistem plugin yang sangat kuat.

## Migrasi dari Telegraf ke grammY

Berikut adalah perubahan utama saat memigrasikan bot dari `Telegraf` ke `grammY`:

### 1. Inisialisasi Bot

**Telegraf:**
```javascript
const { Telegraf, session } = require('telegraf');
const bot = new Telegraf('BOT_TOKEN');
bot.launch();
```

**grammY:**
```javascript
const { Bot, session } = require('grammy');
const bot = new Bot('BOT_TOKEN');
bot.start(); // Perhatikan penggunaan start() bukan launch()
```

### 2. Context (`ctx`) API Methods

Dalam `grammY`, semua pemanggilan API ke server Telegram yang dipicu melalui bot diletakkan di dalam `bot.api.*` atau `ctx.api.*`.

- **Telegraf:** `ctx.telegram.sendMessage(chatId, text)`
- **grammY:** `ctx.api.sendMessage(chatId, text)`

*(Catatan: `ctx.reply`, `ctx.replyWithPhoto`, dll tetap sama)*

### 3. Routing dan Filter Updates

`grammY` menggunakan filter queries (mirip dengan query selector) yang sangat powerful untuk merutekan pesan.

- **Telegraf:** `bot.on('text', ...)`
- **grammY:** `bot.on('message:text', ...)`

- **Telegraf:** `bot.on(['photo', 'video'], ...)`
- **grammY:** `bot.on(['message:photo', 'message:video'], ...)`

- **Telegraf:** `bot.action('button_data', ...)`
- **grammY:** `bot.callbackQuery('button_data', ...)`
  Atau menggunakan filter: `bot.on('callback_query:data', ...)`

### 4. Inline Keyboard dan Markup

`grammY` tidak menggunakan objek `Markup` yang membingungkan. Sebagai gantinya, ia menggunakan class `InlineKeyboard` dan `Keyboard` (untuk custom reply keyboard).

**Telegraf:**
```javascript
const { Markup } = require('telegraf');

await ctx.reply('Pilih:', {
    ...Markup.inlineKeyboard([
        [Markup.button.callback('Tombol 1', 'data_1')],
        [Markup.button.callback('Tombol 2', 'data_2')]
    ])
});
```

**grammY:**
```javascript
const { InlineKeyboard } = require('grammy');

const keyboard = new InlineKeyboard()
    .text('Tombol 1', 'data_1').row()
    .text('Tombol 2', 'data_2');

await ctx.reply('Pilih:', { reply_markup: keyboard });
```

### 5. Session Management

**Telegraf:**
```javascript
bot.use(session({ defaultSession: () => ({ myData: null }) }));
```

**grammY:**
```javascript
bot.use(session({ initial: () => ({ myData: null }) }));
```

### 6. Error Handling

Error di `grammY` di-wrap dalam instance `BotError`. Anda dapat mengekstrak `ctx` dan error aslinya dari sana.

**grammY:**
```javascript
const { GrammyError, HttpError } = require('grammy');

bot.catch((err) => {
    const ctx = err.ctx;
    const e = err.error;
    
    if (e instanceof GrammyError) {
        console.error('Error in request:', e.description);
    } else if (e instanceof HttpError) {
        console.error('Could not contact Telegram:', e);
    } else {
        console.error('Unknown error:', e);
    }
});
```

### 7. Menjawab Callback Query

- **Telegraf:** `ctx.answerCbQuery('Pesan')`
- **grammY:** `ctx.answerCallbackQuery({ text: 'Pesan' })`

## Ekosistem Plugin grammY

Dalam project ini, kita memanfaatkan plugin resmi grammY untuk fitur-fitur yang lebih advance:

1. **@grammyjs/auto-retry**: Secara otomatis mengulang request API (retry) jika Telegram membalas dengan `429 Too Many Requests`. Sangat penting saat melakukan broadcast.
   ```javascript
   bot.api.config.use(autoRetry());
   ```

2. **@grammyjs/parse-mode**: Menyetel default Parse Mode (misal: Markdown atau HTML) untuk setiap pesan, jadi kita tidak perlu menulis `{ parse_mode: 'Markdown' }` berulang-ulang.
   ```javascript
   bot.api.config.use(parseMode('Markdown'));
   ```

3. **@grammyjs/transformer-throttle**: Otomatis menangani pembatasan (throttling) rate-limit Telegram API.

Untuk referensi lengkap, baca dokumentasi resmi di: [https://grammy.dev/](https://grammy.dev/)