# Sözlük

Rehberlerde karşılaştığın teknik terimlerin her biri burada iki cümleyle açıklanır: ilk cümle günlük dille ne işe yaradığını, ikinci cümle ise API'deki tam teknik karşılığını söyler. Kavramların birbirine nasıl bağlandığını hikâye akışıyla okumak istersen [Temel kavramlar](https://noluyo.net/gelistirici/kavramlar.md) sayfasına bak.

### Token

Token, bot programının N'oluyo'ya kendisini tanıtmak için kullandığı gizli şifredir ve kimseyle paylaşılmaz. Teknik olarak REST isteklerinde `Authorization: Bot <token>` başlığında, gateway bağlantısında ise `op 2` (`IDENTIFY`) çerçevesinde gönderilen kimlik dizgisidir; OAuth2 kullanıcı girişinde ise `Bearer <access_token>` biçiminde ayrı erişim token'ları kullanılır.

### REST API

REST API, botunun mesaj göndermek, rol vermek ya da kanal listelemek gibi bir işlem yapmak istediğinde N'oluyo'ya soru-cevap şeklinde istek yolladığı kapıdır. Teknik olarak `https://noluyo.net/api/v1` taban adresi altındaki standart HTTP (`GET`, `POST`, `PUT`, `PATCH`, `DELETE`) uçlarıdır; JSON ya da `multipart/form-data` gövdesi alır ve `X-RateLimit-*` hız sınırı başlıklarıyla JSON yanıtı döndürür.

### Gateway

Gateway, sunucuda yeni bir mesaj yazıldığında ya da bir üye katıldığında N'oluyo'nun botuna anında haber uçurduğu sürekli açık telefon hattıdır. Teknik olarak `GET /api/v1/gateway/bot` ucundan öğrenilen adrese açılan sıkıştırmasız JSON `WebSocket` bağlantısıdır; `op 1` (`HEARTBEAT`) ile canlı tutulur ve koptuğunda `op 6` (`RESUME`) ile kaçan olayları kaybetmeden sürdürülür.

### Intent

Intent, botunun sunucularda olan her gürültüyü değil yalnızca ilgilendiği haber başlıklarını dinlemek için yaptığı abonelik seçimidir. Teknik olarak `op 2` (`IDENTIFY`) çerçevesinde gönderilen bir tam sayı bit maskesidir; `GUILD_MEMBERS` (`1 << 1`), `GUILD_PRESENCES` (`1 << 8`) ve `MESSAGE_CONTENT` (`1 << 15`) ayrıcalıklıdır ve önce geliştirici portalında açılmamışsa bağlantıyı `4014` koduyla kapatır.

### Shard

Shard, yüzlerce sunucuda bulunan büyük bir botun tek bir kablodan taşmamak için sunucularını birkaç paralel bağlantıya bölmesidir. Teknik olarak her sunucuyu `(BigInt(guild_id) >> 22n) % BigInt(count)` formülüyle `[id, count]` oturumlarından birine dağıtan gateway bölümleme düzenidir; 100 sunucunun üstünde zorunlu hale gelir ve sunucusuz DM olayları her zaman shard `0` oturumuna düşer.

### Guild (Sunucu)

Sunucu, insanların metin ve ses kanallarında bir araya geldiği topluluk alanıdır; günlük konuşmada "sunucu" dediğimiz yere API "guild" adını verir. Teknik olarak kanalları, sıralı rolleri ve üyeleri barındıran, rotalarda `/guilds/{guild_id}` ve olaylarda `guild_id` alanıyla taşınan üst düzey topluluk nesnesidir.

### Snowflake (ID)

Snowflake, N'oluyo'daki her kullanıcıya, sunucuya, kanala, mesaja ve role verilen, üretildiği anın zaman damgasını da içinde taşıyan benzersiz kimlik numarasıdır. Teknik olarak 64 bitlik işaretsiz bir tam sayıdır; JavaScript'in 53 bitlik `Number` sınırında hassasiyet kaybı yaşanmaması için JSON gövdelerinde her zaman tırnak içinde ondalık metin (`"21531879014400001"`) olarak taşınır.

### Embed

Embed, botun düz yazı mesajının altında beliren, renkli kenar şeridi, başlığı, tablo alanları ve resmi olan düzenli bilgi kartıdır. Teknik olarak mesaj gövdesinin `embeds` dizisinde (mesaj başına en çok 10 adet, toplam 6000 karakter) gönderilen yapılandırılmış JSON nesnesidir ve dış izleme bağlantısı sızıntısını önlemek için görsel olarak yalnızca aynı istekle yüklenen `attachment://dosya.png` eklerini kabul eder.

### Ephemeral (Yalnızca sana görünür)

Ephemeral mesaj, bir butona basan ya da komut çalıştıran kişiye kanaldaki diğer kimseyi rahatsız etmeden gösterilen ve sayfa yenilenince kaybolan özel yanıttır. Teknik olarak etkileşim yanıtlarında ve takip mesajlarında `flags: 64` bitiyle işaretlenen, veritabanına yazılmayan ve dosya eki taşıyamayan geçici teslim biçimidir.

### Etkileşim (Interaction)

Etkileşim, bir kullanıcının botunun eğik çizgi komutunu çalıştırması, butonuna basması, menüsünden seçim yapması ya da açtığı formu göndermesiyle başlayan karşılıklı konuşma adımıdır. Teknik olarak bota `INTERACTION_CREATE` olayı (veya imzalı HTTP isteği) olarak ulaşan, **3 saniye içinde** ilk `callback` yanıtını zorunlu kılan ve `token` değeriyle 15 dakika boyunca mesaj düzenleme ya da takip mesajı izni veren nesnedir.

### Webhook / HTTP teslim

Webhook ve HTTP teslim, açık bir WebSocket bağlantısı tutmak yerine mesaj göndermeyi ya da etkileşim almayı doğrudan HTTPS adresleri üzerinden yürüten yöntemdir. Teknik olarak etkileşim tarafında N'oluyo'nun botun kayıtlı HTTPS adresine `X-Signature-Ed25519` ve `X-Signature-Timestamp` başlıklarıyla imzalı `POST` isteği yollaması ([HTTP ile teslim](https://noluyo.net/gelistirici/http-teslim.md)), kanal tarafında ise bir webhook adresine JSON gövdesi göndererek kanala mesaj bırakılmasıdır.

### Kapsam (OAuth2 Scope)

Kapsam, kendi web sitene "N'oluyo ile giriş yap" koyduğunda kullanıcıdan hesabının tam olarak hangi bilgisini okumak için izin istediğini belirten yetki etiketidir. Teknik olarak `/oauth2/authorize` sorgusunda boşlukla ayrılarak gönderilen (`identify`, `email`, `guilds`) dizgilerdir; kullanıcı şifresini, özel mesajlarını ya da mesaj yazma yetkisini hiçbir kapsam açmaz.

### PKCE

PKCE, kullanıcının giriş onayından dönen tek kullanımlık yetki kodunun yolda başka bir uygulama tarafından çalınıp kullanılmasını engelleyen kriptografik güvenlik kilididir. Teknik olarak istemcinin rastgele ürettiği `code_verifier` dizgisinin SHA-256 `base64url` özetini (`code_challenge`, `S256`) başta göndermesi ve `/api/v1/oauth2/token` adımında asıl `code_verifier` değerini ibraz ederek kanıtlamasıdır; N'oluyo'da tüm OAuth2 istemcileri için zorunludur.

## Bu sayfayı yapay zekaya verirsen

> **İpucu:** Bu sözlük N'oluyo'ya özgü kesin sınırları (64 bit metin Snowflake ID'ler, 3 saniyelik etkileşim yanıtı, yalnızca `attachment://` kabul eden embed görselleri ve zorunlu `S256` PKCE) özetler; yapay zeka terimleri başka platformlarla karıştırdığında bu sayfayı bağlama ekleyebilirsin.

## Sırada ne var

- [Temel kavramlar](https://noluyo.net/gelistirici/kavramlar.md): bu terimlerin bir isteğin yolculuğunda nasıl bir araya geldiği
- [Başka platformdan gelenler](https://noluyo.net/gelistirici/baska-platformdan.md): tanıdık kavramlar ile N'oluyo'nun bilinçli farkları
- [Hızlı başlangıç](https://noluyo.net/gelistirici/baslangic.md): ilk botunu birkaç dakikada ayağa kaldırmak