mercys.js Bot SDK · REST & Socket.IO /gateway

Toplulukların için mercys.js ile bot geliştir

Botlar normal kullanıcılarla aynı REST API’yi ve Socket.IO /gateway bağlantısını kullanır. Kullanıcı başına en fazla 5 bot oluştur ve Authorization: Bot <token> ile bağlan.

5 Bot

Kullanıcı Başına Kota

POST /api/bots ile anında oluştur ve yönet

Authorization: Bot

REST Kimlik Başlığı

SHA-256 özetiyle doğrulanan tek seferlik token

/gateway

Socket.IO Akış Yolu

Otomatik yeniden bağlanma ve canlı önbellek

27 İzin

Bitfield Yetki Sistemi

computePermissions ile istemci ve sunucu uyumu

mercys.js SDK · 0.2

Üç adımda çalışan bot kodu

Tek runtime bağımlılığı socket.io-client olan mercys.js ile olay dinleyicileri, komut yardımcıları ve izin kontrolleri yaz.

npm install mercys.js
import { Client } from 'mercys.js';

const client = new Client({
  token: process.env.MERCYS_TOKEN!,
  baseUrl: 'http://localhost:4100',
});

client.on('ready', (me) => {
  console.log(`${me.username} olarak giriş yapıldı`);
});

client.on('messageCreate', async (msg) => {
  if (msg.author.isBot) return;
  if (msg.content === '!ping') {
    await msg.reply('pong');
  }
});

await client.login();
mercys.js Client ile Socket.IO /gateway bağlantısı kurar ve !ping mesajlarına yanıt verir.Authorization: Bot <token>

REST & Gateway Özeti

Yönetim uçları ve canlı Socket.IO olayları

Bot yönetim uçları yalnızca kullanıcı JWT’si (Bearer) ile çalışır; bot token’ı ile çağrıldığında 403 bots_forbidden döner.

Bot Yönetimi REST Uçları

GET/api/botsKullanıcının sahip olduğu tüm botları listeler (Bot[]).
POST/api/botsYeni bot oluşturur (201, BotWithToken; en fazla 5 bot).
POST/api/bots/:id/tokenToken’ı sıfırlar; eski token ve açık oturumlar anında düşer.
DELETE/api/bots/:idBotu, mesajlarını ve sahip olduğu sunucuları kalıcı olarak siler (204).
POST/api/servers/:id/bots{ botId } ile sunucuya bot ekler (MANAGE_BOTS + bot kuralı).

Socket.IO /gateway Event’leri

readyready / resumedSelfUser ve başlangıç önbelleği (servers, voiceStates)
message:createmessageCreateMessage nesnesi (msg.reply, msg.edit, msg.delete yardımcılarıyla)
message:update / deletemessageUpdate / messageDeleteGüncellenen Message veya { id, channelId, serverId }
member:joinmemberJoinSunucuya yeni katılan Member (bot eklendiğinde tüm üyeler alır)
server:createserverCreateBot yeni bir sunucuya eklendiğinde ServerListEntry ile tetiklenir
voice:statevoiceStateVoiceParticipantState (kanal, mute, kamera ve yayın durumu)

Güvenlik & Yetkilendirme Kuralları

Sunucuya bot ekleme ve token güvenliği

MANAGE_BOTS + verified_bot Kuralı

Bir sunucuya bot ekleyebilmek için MANAGE_BOTS iznin olmalı ve bot ya kendi botun ya da admin onaylı verified_bot rozetine sahip olmalıdır; aksi halde 403 bot_not_allowed döner.

Tek Seferlik Token & SHA-256

Token biçimi <botId>.<32 bayt base64url> şeklindedir. Sunucu yalnızca SHA-256 özetini saklar; sızıntıda POST /api/bots/:id/token eski oturumları anında kapatır.

@everyone ve En Az Yetki İlkesi

Bot sunucuya yalnızca @everyone rolüyle katılır. ADMINISTRATOR vermek yerine yalnızca ihtiyaç duyduğu izin bitlerini tanımla.

İlk botunu dakikalar içinde sunucuna ekle

Web uygulamasından hesabına giriş yap, token’ını ortam değişkenine ekle ve mercys.js ile ilk komutunu çalıştır.

Uygulamaya Git