botvoi

Minimal and easy-to-use Node.js client for the BotVoi API.

Minimal, kolay kullanımlı BotVoi API Node.js istemcisi.

English • Türkçe

English

Features

• Fetch user data (fetch)
• Apply punitives (punitivesSet) with flexible type matching (e.g. "chat mute", "chat-mute")

Install

npm install botvoi

Quick start

CommonJS (require):

const BotVoi = require('botvoi')

// Limited access with the free key – suitable for testing
const client = new BotVoi('free')

(async () => {
  const user = await client.fetch('123456789012345678')
  console.log(user)

  const result = await client.punitivesSet('123456789012345678', 'chat-mute', 'Spam')
  console.log(result)
})()

ESM (import):

import BotVoi from 'botvoi'

// Prefer your real API key in production
const client = new BotVoi(process.env.BOTVOI_KEY)

const user = await client.fetch('123456789012345678')
console.log(user)

Discord.js integration (v13, v14 and beyond)

This SDK works with any discord.js major version (v13, v14, etc.). The example below shows v14-style imports; for v13, use Intents.FLAGS instead of GatewayIntentBits.

// v14 style
const { Client, GatewayIntentBits, Partials } = require('discord.js')
const BotVoi = require('botvoi')

// enable all gateway intents and partials
const allIntents = Object.values(GatewayIntentBits)
const allPartials = Object.values(Partials)

const client = new Client({
  intents: allIntents,
  partials: allPartials,
})

const botvoiClient = new BotVoi()

client.once('ready', () => {
  console.log(`${client.user.tag} is online!`)
  botvoiClient.setKey('free') // or process.env.BOTVOI_KEY
  botvoiClient.setClient(client) // attach your discord.js client
})

// When a staff member leaves other guilds, you'll receive a notification
client.on('otherGuildsStaffLeave', (data) => {
  console.log('A staff member left other guilds:', data)
})

Event payload shape (handler data argument):

{
  userId: string,
  username: string,
  guildId: string,
  guildName: string,
  icon: string | null, // guild icon URL (dynamic, size 1024) if available
  matchedPermissions: string[], // staff-like permissions found
  matchedNameRoles: string[],   // role names that matched staff patterns
  staffEvidence: any            // additional evidence/details
}

This notification helps you understand in which servers the user had staff roles when they left, so you can take automated actions or log the event.

Free access (limited)

• You can use the special key free to access the API with limited capabilities and/or stricter rate limits.
• This is ideal for quick tests and exploring the SDK. For production workloads, use your own API key.

API Reference

class BotVoi(key?)

• key: string | null – Optional API key. You may set it later via setKey.

setKey(key: string): void

• Update the API key. Must be a non-empty string.

fetch(userId: string | number): Promise

• Fetch user data and return a User object.

Fetch response and SDK mapping

Raw API response example (truncated for brevity):

{
  "error": null,
  "ok": true,
  "member": {
    "id": "985023331130552331",
    "username": "acarfx",
    "tag": "acarfx",
    "avatarURL": "https://cdn.discordapp.com/avatars/985.../7a2d1.webp",
    "user_profile": { "bio": "", "accent_color": 1122357 },
    "voice": { "guild": { "id": "1427716311303327816", "name": "F L O R Y #Yakında" } },
    "staff_user": { "guildId": "1427716311303327816", "roles": [{ "name": "Flory Bot's" }] }
  },
  "guilds": [
    {
      "id": "1427716311303327816",
      "name": "F L O R Y #Yakında",
      "user": { "isStaff": true, "roles": ["VIP", "Flory Bot's"] }
    }
  ],
  "last_activities": {
    "last_seen": { "type": "voiceUpdate", "timestamp": 1761523948332 },
    "items": [{ "type": "voiceUpdate", "changes": [{ "action": "startedScreenSharing" }] }]
  },
  "punitives": "not permission",
  "version": 1.2
}

SDK mapping to the User class:

• Top-level member fields are shallow-assigned onto the User instance (e.g. id, username, tag, avatarURL, user_profile, voice, staff_user, ...).
• guilds remains as provided: user.guilds is the array from the API.
• last_activities becomes user.activities with shape { Seen, Activities }:
  • Seen = last_activities.last_seen
  • Activities = last_activities.items
• punitives is copied as-is to user.punitives.

Example usage and resulting shape:

const u = await client.fetch('985023331130552331')
// u is a User instance, roughly:
// {
//   id: '985023331130552331',
//   username: 'acarfx',
//   tag: 'acarfx',
//   avatarURL: 'https://.../avatars/...webp',
//   user_profile: { bio: '', accent_color: 1122357, ... },
//   voice: { guild: { id: '1427716311303327816', name: 'F L O R Y #Yakında' }, ... },
//   staff_user: { guildId: '1427...', roles: [ { name: "Flory Bot's", permissions: [ 'ADMINISTRATOR' ] } ] },
//   guilds: [ { id: '1427...', name: 'F L O R Y #Yakında', user: { isStaff: true, ... } }, ... ],
//   activities: { Seen: { type: 'voiceUpdate', timestamp: 1761523948332, ... }, Activities: [ { type: 'voiceUpdate', changes: [ ... ] } ] },
//   punitives: 'not permission',
//   toJSON() { return this }
// }

punitivesSet(userId: string | number, type: string, reason?: string): Promise

• Apply a punitive to the given user. The type is normalized and mapped to one of the supported values.

Supported types (normalized mapping):

• Ban, ForceBan, Jail, ChatMute, VoiceMute, Timeout, Warning, Underworld
• UnBan, UnForceBan, UnJail, UnChatMute, UnVoiceMute, UnTimeout, UnUnderworld

class User

• Includes member fields, guilds, activities, and punitives.
• toJSON() returns a JSON-friendly object.

Environment variables

• BOTVOI_KEY – Your API key

Error handling

• The client throws if no key is configured or when the API responds with an error field.

TypeScript

• This package ships with index.d.ts and provides type definitions for BotVoi and User.

Requirements

• Node.js >= 14

Türkçe

Özellikler

• Kullanıcı verilerini çekme (fetch)
• Ceza/punitif atama (punitivesSet) – esnek tür eşleştirme (ör. "chat mute", "chat-mute")

Kurulum

npm install botvoi

Hızlı Başlangıç

CommonJS (require):

const BotVoi = require('botvoi')

// Ücretsiz anahtar ile sınırlı erişim – test için uygundur
const client = new BotVoi('free')

(async () => {
  const user = await client.fetch('123456789012345678')
  console.log(user)

  const result = await client.punitivesSet('123456789012345678', 'chat-mute', 'Spam')
  console.log(result)
})()

ESM (import):

import BotVoi from 'botvoi'

// Üretimde kendi gerçek API anahtarınızı kullanmanız önerilir
const client = new BotVoi(process.env.BOTVOI_KEY)

const user = await client.fetch('123456789012345678')
console.log(user)

Discord.js entegrasyonu (v13, v14 ve sonrası)

Bu SDK, discord.js’in tüm ana sürümleriyle (v13, v14 vb.) çalışır. Aşağıdaki örnek v14 tarzını gösterir; v13 için GatewayIntentBits yerine Intents.FLAGS kullanın.

// v14 stili
const { Client, GatewayIntentBits, Partials } = require('discord.js')
const BotVoi = require('botvoi')

// tüm gateway intent ve partial’ları etkinleştir
const allIntents = Object.values(GatewayIntentBits)
const allPartials = Object.values(Partials)

const client = new Client({
  intents: allIntents,
  partials: allPartials,
})

const botvoiClient = new BotVoi()

client.once('ready', () => {
  console.log(`${client.user.tag} is online!`)
  botvoiClient.setKey('free') // veya process.env.BOTVOI_KEY
  botvoiClient.setClient(client) // discord.js client’ınızı bağlayın
})

// Diğer sunuculardan bir yetkili ayrıldığında bildirim alırsınız
client.on('otherGuildsStaffLeave', (data) => {
  console.log('Diğer sunucularda bir yetkili ayrıldı:', data)
})

Event/payload yapısı (data parametresi):

{
  userId: string,
  username: string,
  guildId: string,
  guildName: string,
  icon: string | null, // varsa sunucu ikon URL’si (dinamik, 1024)
  matchedPermissions: string[], // tespit edilen yetkili benzeri izinler
  matchedNameRoles: string[],   // isimden yakalanan yetkili rol eşleşmeleri
  staffEvidence: any            // ek kanıt/ayrıntılar
}

Bu bildirim, kullanıcının ayrıldığı anda hangi sunucularda yetkili olduğunu anlamanıza yardımcı olur; otomasyon veya kayıt amaçlı kullanabilirsiniz.

Ücretsiz anahtar (sınırlı erişim)

• free adlı özel anahtar ile API’ye sınırlı yetenekler ve/veya daha sıkı oran limitleri ile erişebilirsiniz.
• Bu, hızlı denemeler ve SDK’yı keşfetmek için idealdir. Üretim iş yükleri için kendi API anahtarınızı kullanın.

API Referansı

class BotVoi(key?)

• key: string | null – İsteğe bağlı API anahtarı. Daha sonra setKey ile ayarlanabilir.

setKey(key: string): void

• API anahtarını günceller. Boş olamaz.

fetch(userId: string | number): Promise

• Kullanıcı verilerini çeker ve User nesnesi döner.

Fetch çıktısı ve SDK eşlemesi

Ham API yanıtı örneği (kısaltılmıştır):

{
  "error": null,
  "ok": true,
  "member": {
    "id": "985023331130552331",
    "username": "acarfx",
    "tag": "acarfx",
    "avatarURL": "https://cdn.discordapp.com/avatars/985.../7a2d1.webp",
    "user_profile": { "bio": "", "accent_color": 1122357 },
    "voice": { "guild": { "id": "1427716311303327816", "name": "F L O R Y #Yakında" } },
    "staff_user": { "guildId": "1427716311303327816", "roles": [{ "name": "Flory Bot's" }] }
  },
  "guilds": [
    {
      "id": "1427716311303327816",
      "name": "F L O R Y #Yakında",
      "user": { "isStaff": true, "roles": ["VIP", "Flory Bot's"] }
    }
  ],
  "last_activities": {
    "last_seen": { "type": "voiceUpdate", "timestamp": 1761523948332 },
    "items": [{ "type": "voiceUpdate", "changes": [{ "action": "startedScreenSharing" }] }]
  },
  "punitives": "not permission",
  "version": 1.2
}

SDK’nin User sınıfına eşlemesi:

• Üst düzey member alanları User örneğine direkt işlenir (örn. id, username, tag, avatarURL, user_profile, voice, staff_user, ...).
• guilds olduğu gibi kalır: user.guilds API’den gelen dizidir.
• last_activities, user.activities haline gelir ve { Seen, Activities } yapısına dönüştürülür:
  • Seen = last_activities.last_seen
  • Activities = last_activities.items
• punitives, user.punitives olarak aynen kopyalanır.

Kullanım ve ortaya çıkan şekil:

const u = await client.fetch('985023331130552331')
// u bir User örneğidir, kabaca:
// {
//   id: '985023331130552331',
//   username: 'acarfx',
//   tag: 'acarfx',
//   avatarURL: 'https://.../avatars/...webp',
//   user_profile: { bio: '', accent_color: 1122357, ... },
//   voice: { guild: { id: '1427716311303327816', name: 'F L O R Y #Yakında' }, ... },
//   staff_user: { guildId: '1427...', roles: [ { name: "Flory Bot's", permissions: [ 'ADMINISTRATOR' ] } ] },
//   guilds: [ { id: '1427...', name: 'F L O R Y #Yakında', user: { isStaff: true, ... } }, ... ],
//   activities: { Seen: { type: 'voiceUpdate', timestamp: 1761523948332, ... }, Activities: [ { type: 'voiceUpdate', changes: [ ... ] } ] },
//   punitives: 'not permission',
//   toJSON() { return this }
// }

punitivesSet(userId: string | number, type: string, reason?: string): Promise

• Belirtilen kullanıcıya punitif uygular. type değeri normalize edilerek desteklenen türlerden birine eşlenir.

Desteklenen türler (normalleştirilmiş eşlemeler):

• Ban, ForceBan, Jail, ChatMute, VoiceMute, Timeout, Warning, Underworld
• UnBan, UnForceBan, UnJail, UnChatMute, UnVoiceMute, UnTimeout, UnUnderworld

class User

• member alanları, guilds, activities ve punitives içerir.
• toJSON() JSON uyumlu bir nesne döner.

Ortam Değişkenleri

• BOTVOI_KEY – API anahtarınız

Hata Yönetimi

• İstemci, anahtar ayarlı değilse veya API yanıtında error alanı varsa hata fırlatır.

TypeScript

• Paket index.d.ts ile gelir ve BotVoi ile User için tip tanımları sağlar.

Gereksinimler

• Node.js >= 14

Lisans

MIT