social-agent-cli 1.0.0

package/knowledge/bluesky.md

@@ -0,0 +1,1083 @@
+# Bluesky Platform Bilgisi
+
+Bluesky, AT Protocol (Authenticated Transfer Protocol) üzerine kurulu merkezi olmayan bir sosyal ağdır.
+API tamamen ücretsiz ve açıktır, herhangi bir geliştirici onayı veya OAuth uygulaması gerekmez.
+Tüm işlemler XRPC (Cross-RPC) endpoint'leri üzerinden yapılır.
+
+---
+
+## 1. Kimlik Doğrulama (Authentication)
+
+### 1.1 createSession — Giriş Yapma
+
+```
+POST https://bsky.social/xrpc/com.atproto.server.createSession
+Content-Type: application/json
+
+{
+  "identifier": "kullanici.bsky.social",   // handle veya DID
+  "password": "xxxx-xxxx-xxxx-xxxx"        // App Password önerilir
+}
+```
+
+**Yanıt:**
+```json
+{
+  "accessJwt": "eyJ...",        // 2 saat geçerli
+  "refreshJwt": "eyJ...",       // 90 gün geçerli
+  "handle": "kullanici.bsky.social",
+  "did": "did:plc:abc123...",
+  "email": "user@example.com",
+  "emailConfirmed": true
+}
+```
+
+**Önemli notlar:**
+- `identifier` alanına handle (kullanici.bsky.social) veya DID (did:plc:...) yazılabilir.
+- Hesap şifresi yerine **App Password** kullanılması şiddetle önerilir. Hesap ayarları > App Passwords > Yeni oluştur.
+- App Password ile 2FA (iki faktörlü doğrulama) aktifken bile giriş yapılabilir.
+- App Password ile hesap silme, şifre değiştirme gibi kritik işlemler yapılamaz — güvenlik sağlar.
+
+### 1.2 Token Yenileme (Refresh Flow)
+
+Access token süresi dolduğunda (2 saat), refresh token ile yenilenir:
+
+```
+POST https://bsky.social/xrpc/com.atproto.server.refreshSession
+Authorization: Bearer <refreshJwt>
+```
+
+**Yanıt:** Yeni `accessJwt` ve `refreshJwt` döner. Eski refresh token geçersiz olur (rotation).
+
+**Token akışı:**
+1. `createSession` ile giriş yap → accessJwt + refreshJwt al
+2. Tüm isteklerde `Authorization: Bearer <accessJwt>` kullan
+3. 401 hatası alınca `refreshSession` ile yeni token al
+4. Refresh token da süresi dolduysa tekrar `createSession` çağır
+
+### 1.3 Oturumu Sonlandırma
+
+```
+POST https://bsky.social/xrpc/com.atproto.server.deleteSession
+Authorization: Bearer <refreshJwt>
+```
+
+---
+
+## 2. API Endpoint'leri (XRPC)
+
+Tüm endpoint'ler `https://bsky.social/xrpc/` altındadır. Base URL PDS (Personal Data Server) adresine göre değişebilir, ancak `bsky.social` varsayılan ve en yaygın PDS'dir.
+
+### 2.1 Post İşlemleri
+
+#### Post Oluşturma
+
+```
+POST /xrpc/com.atproto.repo.createRecord
+Authorization: Bearer <accessJwt>
+Content-Type: application/json
+
+{
+  "repo": "<did>",
+  "collection": "app.bsky.feed.post",
+  "record": {
+    "$type": "app.bsky.feed.post",
+    "text": "Merhaba Bluesky!",
+    "createdAt": "2026-03-14T12:00:00.000Z",
+    "langs": ["tr"],
+    "facets": [],
+    "embed": null
+  }
+}
+```
+
+**Yanıt:**
+```json
+{
+  "uri": "at://did:plc:abc123/app.bsky.feed.post/3k...",
+  "cid": "bafyrei..."
+}
+```
+
+- `uri` formatı: `at://<did>/<collection>/<rkey>`
+- `rkey` (record key): URI'nin son parçası, post ID'sidir (TID formatı).
+- `cid` (Content ID): Verinin hash'i, veri bütünlüğünü doğrular.
+- `text` maksimum 300 karakter (grapheme cinsinden).
+- `createdAt` ISO 8601 formatında zorunludur.
+- `langs` opsiyonel, BCP-47 dil kodları (örn: `["tr"]`, `["en", "tr"]`).
+
+#### Post Silme
+
+```
+POST /xrpc/com.atproto.repo.deleteRecord
+Authorization: Bearer <accessJwt>
+Content-Type: application/json
+
+{
+  "repo": "<did>",
+  "collection": "app.bsky.feed.post",
+  "rkey": "<rkey>"
+}
+```
+
+#### Yanıt (Reply) Post
+
+Reply yapmak için `record.reply` alanı eklenir:
+
+```json
+{
+  "record": {
+    "$type": "app.bsky.feed.post",
+    "text": "Bu bir yanıt!",
+    "createdAt": "2026-03-14T12:00:00.000Z",
+    "reply": {
+      "root": {
+        "uri": "at://did:plc:abc/app.bsky.feed.post/root123",
+        "cid": "bafyrei..."
+      },
+      "parent": {
+        "uri": "at://did:plc:abc/app.bsky.feed.post/parent456",
+        "cid": "bafyrei..."
+      }
+    }
+  }
+}
+```
+
+- `root`: Thread'in ilk postu (en üst).
+- `parent`: Doğrudan yanıt verilen post.
+- Tek bir posta yanıt verirken root ve parent aynı olabilir.
+
+#### Thread Gate (Yanıt Kısıtlama)
+
+Post oluşturulduktan sonra kimin yanıt verebileceği kısıtlanabilir:
+
+```json
+{
+  "repo": "<did>",
+  "collection": "app.bsky.feed.threadgate",
+  "rkey": "<post_rkey>",
+  "record": {
+    "$type": "app.bsky.feed.threadgate",
+    "post": "at://did:plc:abc/app.bsky.feed.post/123",
+    "createdAt": "2026-03-14T12:00:00.000Z",
+    "allow": [
+      { "$type": "app.bsky.feed.threadgate#mentionRule" },
+      { "$type": "app.bsky.feed.threadgate#followingRule" },
+      { "$type": "app.bsky.feed.threadgate#listRule", "list": "at://did:plc:abc/app.bsky.graph.list/xyz" }
+    ]
+  }
+}
+```
+
+### 2.2 Beğenme (Like)
+
+```
+POST /xrpc/com.atproto.repo.createRecord
+Authorization: Bearer <accessJwt>
+Content-Type: application/json
+
+{
+  "repo": "<did>",
+  "collection": "app.bsky.feed.like",
+  "record": {
+    "$type": "app.bsky.feed.like",
+    "subject": {
+      "uri": "at://did:plc:target/app.bsky.feed.post/abc123",
+      "cid": "bafyrei..."
+    },
+    "createdAt": "2026-03-14T12:00:00.000Z"
+  }
+}
+```
+
+Beğeniyi kaldırmak için `deleteRecord` ile like kaydı silinir.
+
+### 2.3 Repost
+
+```json
+{
+  "repo": "<did>",
+  "collection": "app.bsky.feed.repost",
+  "record": {
+    "$type": "app.bsky.feed.repost",
+    "subject": {
+      "uri": "at://did:plc:target/app.bsky.feed.post/abc123",
+      "cid": "bafyrei..."
+    },
+    "createdAt": "2026-03-14T12:00:00.000Z"
+  }
+}
+```
+
+### 2.4 Takip Etme (Follow)
+
+```json
+{
+  "repo": "<did>",
+  "collection": "app.bsky.graph.follow",
+  "record": {
+    "$type": "app.bsky.graph.follow",
+    "subject": "did:plc:hedef_kullanici",
+    "createdAt": "2026-03-14T12:00:00.000Z"
+  }
+}
+```
+
+Takibi bırakmak: `deleteRecord` ile follow kaydı silinir.
+
+### 2.5 Engelleme (Block)
+
+```json
+{
+  "repo": "<did>",
+  "collection": "app.bsky.graph.block",
+  "record": {
+    "$type": "app.bsky.graph.block",
+    "subject": "did:plc:engellenecek_kullanici",
+    "createdAt": "2026-03-14T12:00:00.000Z"
+  }
+}
+```
+
+### 2.6 Sessize Alma (Mute)
+
+Mute farklıdır — repo kaydı oluşturulmaz, doğrudan API çağrısı yapılır:
+
+```
+POST /xrpc/app.bsky.graph.muteActor
+Authorization: Bearer <accessJwt>
+Content-Type: application/json
+
+{ "actor": "did:plc:hedef" }
+```
+
+Unmute:
+```
+POST /xrpc/app.bsky.graph.unmuteActor
+{ "actor": "did:plc:hedef" }
+```
+
+### 2.7 Medya Yükleme (Upload Blob)
+
+```
+POST /xrpc/com.atproto.repo.uploadBlob
+Authorization: Bearer <accessJwt>
+Content-Type: image/png   (veya image/jpeg, image/webp, image/gif)
+
+<binary data>
+```
+
+**Yanıt:**
+```json
+{
+  "blob": {
+    "$type": "blob",
+    "ref": { "$link": "bafkrei..." },
+    "mimeType": "image/png",
+    "size": 45678
+  }
+}
+```
+
+**Önemli:**
+- Maksimum dosya boyutu: **1 MB** (görsel), **50 MB** (video — ayrı endpoint).
+- Yüklenen blob geçicidir; 1 saat içinde bir kayıtta (record) referans verilmezse silinir.
+- Desteklenen görsel formatları: PNG, JPEG, WebP, GIF (animasyonlu GIF dahil, ancak durağan olarak gösterilir).
+
+### 2.8 Video Yükleme
+
+Video yükleme ayrı bir akış gerektirir:
+
+```
+GET /xrpc/app.bsky.video.getJobStatus?jobId=<id>
+GET /xrpc/app.bsky.video.getUploadLimits
+POST /xrpc/app.bsky.video.uploadVideo   (Content-Type: video/mp4)
+```
+
+- Maksimum video boyutu: **50 MB**
+- Maksimum süre: **60 saniye** (bazı hesaplarda 90 saniye)
+- Format: MP4 (H.264 codec önerilir)
+- Video yüklendikten sonra işlenir (transcoding), `getJobStatus` ile durum takip edilir.
+
+---
+
+## 3. Rich Text Facets
+
+Bluesky'da mention, link ve hashtag'ler `facets` dizisi ile tanımlanır.
+**Kritik: Byte offset kullanılır, karakter offset değil!** UTF-8 encoding ile byte pozisyonları hesaplanmalıdır.
+
+### 3.1 Facet Yapısı
+
+```json
+{
+  "facets": [
+    {
+      "index": {
+        "byteStart": 0,
+        "byteEnd": 14
+      },
+      "features": [
+        {
+          "$type": "app.bsky.richtext.facet#mention",
+          "did": "did:plc:abc123"
+        }
+      ]
+    }
+  ]
+}
+```
+
+### 3.2 Mention (Bahsetme)
+
+```json
+{
+  "$type": "app.bsky.richtext.facet#mention",
+  "did": "did:plc:hedef_kullanici_did"
+}
+```
+
+- Metinde `@kullanici.bsky.social` yazılır.
+- Facet'te handle değil **DID** belirtilir.
+- Handle → DID çözümlemek için: `GET /xrpc/com.atproto.identity.resolveHandle?handle=kullanici.bsky.social`
+
+### 3.3 Link
+
+```json
+{
+  "$type": "app.bsky.richtext.facet#link",
+  "uri": "https://example.com"
+}
+```
+
+- Metindeki URL tam olarak facet aralığına denk gelmelidir.
+- URI validasyonu yapılır, geçersiz URI'ler reddedilir.
+
+### 3.4 Hashtag (Etiket)
+
+```json
+{
+  "$type": "app.bsky.richtext.facet#tag",
+  "tag": "bluesky"
+}
+```
+
+- Metinde `#bluesky` yazılır, facet `tag` alanında `#` olmadan sadece etiket adı verilir.
+- Hashtag arama: `https://bsky.app/search?q=%23bluesky`
+
+### 3.5 Byte Offset Hesaplama (TypeScript)
+
+```typescript
+const encoder = new TextEncoder();  // UTF-8
+
+function findByteOffsets(text: string, matchStart: number, matchText: string) {
+  const byteStart = encoder.encode(text.substring(0, matchStart)).byteLength;
+  const byteEnd = byteStart + encoder.encode(matchText).byteLength;
+  return { byteStart, byteEnd };
+}
+```
+
+**Dikkat:** Türkçe karakterler (ş, ğ, ü, ö, ç, ı, İ) ve emoji gibi çok baytlı karakterlerde byte offset ile karakter index'i farklıdır. `TextEncoder` kullanmak zorunludur.
+
+Örnek: `"Türkçe #test"` metninde `#test` karakter 8'de başlar ama byte 9'da başlar (ü = 2 byte).
+
+---
+
+## 4. Embed Tipleri
+
+Post'lara görsel, link kartı, alıntı (quote) eklemek için `embed` alanı kullanılır.
+
+### 4.1 Görsel Embed
+
+```json
+{
+  "embed": {
+    "$type": "app.bsky.embed.images",
+    "images": [
+      {
+        "alt": "Görsel açıklaması (erişilebilirlik için)",
+        "image": {
+          "$type": "blob",
+          "ref": { "$link": "bafkrei..." },
+          "mimeType": "image/jpeg",
+          "size": 45678
+        },
+        "aspectRatio": {
+          "width": 1200,
+          "height": 630
+        }
+      }
+    ]
+  }
+}
+```
+
+- Maksimum **4 görsel** eklenebilir.
+- `alt` alanı zorunlu değil ama erişilebilirlik için önerilir.
+- `aspectRatio` opsiyonel ama verilirse görsel düzgün kırpılır.
+
+### 4.2 Harici Link Embed (Link Kartı / OG Card)
+
+```json
+{
+  "embed": {
+    "$type": "app.bsky.embed.external",
+    "external": {
+      "uri": "https://example.com/article",
+      "title": "Makale Başlığı",
+      "description": "Makale açıklaması...",
+      "thumb": {
+        "$type": "blob",
+        "ref": { "$link": "bafkrei..." },
+        "mimeType": "image/jpeg",
+        "size": 12345
+      }
+    }
+  }
+}
+```
+
+**Önemli:** Bluesky sunucusu link kartı otomatik oluşturmaz! Client tarafında:
+1. Hedef URL'den OG meta tag'leri çekilir (title, description, image).
+2. OG image varsa `uploadBlob` ile yüklenir.
+3. Tüm bilgiler embed'e yazılır.
+4. `thumb` opsiyoneldir, olmadan da link kartı oluşturulur (görselsiz).
+
+### 4.3 Alıntı Post (Quote Post)
+
+```json
+{
+  "embed": {
+    "$type": "app.bsky.embed.record",
+    "record": {
+      "uri": "at://did:plc:abc/app.bsky.feed.post/xyz",
+      "cid": "bafyrei..."
+    }
+  }
+}
+```
+
+### 4.4 Görsel + Alıntı (Kombine Embed)
+
+```json
+{
+  "embed": {
+    "$type": "app.bsky.embed.recordWithMedia",
+    "record": {
+      "record": {
+        "uri": "at://did:plc:abc/app.bsky.feed.post/xyz",
+        "cid": "bafyrei..."
+      }
+    },
+    "media": {
+      "$type": "app.bsky.embed.images",
+      "images": [...]
+    }
+  }
+}
+```
+
+### 4.5 Video Embed
+
+```json
+{
+  "embed": {
+    "$type": "app.bsky.embed.video",
+    "video": {
+      "$type": "blob",
+      "ref": { "$link": "bafkrei..." },
+      "mimeType": "video/mp4",
+      "size": 5000000
+    },
+    "alt": "Video açıklaması",
+    "aspectRatio": {
+      "width": 1920,
+      "height": 1080
+    }
+  }
+}
+```
+
+---
+
+## 5. Okuma (Read) Endpoint'leri
+
+Bu endpoint'ler `GET` istekleri ile çalışır. Çoğu kimlik doğrulama gerektirir.
+
+### 5.1 Profil Bilgileri
+
+```
+GET /xrpc/app.bsky.actor.getProfile?actor=kullanici.bsky.social
+Authorization: Bearer <accessJwt>
+```
+
+**Yanıt:** displayName, description, avatar, banner, followersCount, followsCount, postsCount, vb.
+
+### 5.2 Kullanıcı Arama
+
+```
+GET /xrpc/app.bsky.actor.searchActors?q=arama_terimi&limit=25
+Authorization: Bearer <accessJwt>
+```
+
+- `q`: Arama terimi (handle veya display name)
+- `limit`: Sonuç sayısı (maks 100, varsayılan 25)
+- `cursor`: Sayfalama için
+
+### 5.3 Post Arama
+
+```
+GET /xrpc/app.bsky.feed.searchPosts?q=arama_terimi&limit=25
+Authorization: Bearer <accessJwt>
+```
+
+- `q`: Arama terimi
+- `sort`: `top` veya `latest` (varsayılan: `latest`)
+- `since` / `until`: Tarih filtresi (ISO 8601)
+- `author`: Belirli bir kullanıcının postlarında ara
+- `lang`: Dil filtresi (örn: `tr`)
+- `tag`: Hashtag filtresi
+
+### 5.4 Bildirimler
+
+```
+GET /xrpc/app.bsky.notification.listNotifications?limit=50
+Authorization: Bearer <accessJwt>
+```
+
+**Bildirim türleri (reason):** `like`, `repost`, `follow`, `mention`, `reply`, `quote`, `starterpack-joined`
+
+Bildirimleri okundu olarak işaretleme:
+```
+POST /xrpc/app.bsky.notification.updateSeen
+{ "seenAt": "2026-03-14T12:00:00.000Z" }
+```
+
+### 5.5 Timeline (Akış)
+
+```
+GET /xrpc/app.bsky.feed.getTimeline?limit=50
+Authorization: Bearer <accessJwt>
+```
+
+### 5.6 Kullanıcının Postları
+
+```
+GET /xrpc/app.bsky.feed.getAuthorFeed?actor=kullanici.bsky.social&limit=50
+Authorization: Bearer <accessJwt>
+```
+
+- `filter`: `posts_with_replies`, `posts_no_replies`, `posts_with_media`, `posts_and_author_threads`
+
+### 5.7 Post Detayı
+
+```
+GET /xrpc/app.bsky.feed.getPosts?uris=at://did:plc:abc/app.bsky.feed.post/xyz
+Authorization: Bearer <accessJwt>
+```
+
+- Birden fazla URI virgülle ayrılarak tek istekte sorgulanabilir (maks 25).
+
+### 5.8 Thread Görüntüleme
+
+```
+GET /xrpc/app.bsky.feed.getPostThread?uri=at://did:plc:abc/app.bsky.feed.post/xyz&depth=6
+Authorization: Bearer <accessJwt>
+```
+
+### 5.9 Takipçiler ve Takip Edilenler
+
+```
+GET /xrpc/app.bsky.graph.getFollowers?actor=kullanici.bsky.social&limit=100
+GET /xrpc/app.bsky.graph.getFollows?actor=kullanici.bsky.social&limit=100
+Authorization: Bearer <accessJwt>
+```
+
+### 5.10 Handle Çözümleme
+
+```
+GET /xrpc/com.atproto.identity.resolveHandle?handle=kullanici.bsky.social
+```
+
+Kimlik doğrulama gerektirmez. Yanıt: `{ "did": "did:plc:abc123" }`
+
+### 5.11 Beğenenler ve Repost Edenler
+
+```
+GET /xrpc/app.bsky.feed.getLikes?uri=at://did:plc:abc/app.bsky.feed.post/xyz&limit=100
+GET /xrpc/app.bsky.feed.getRepostedBy?uri=at://did:plc:abc/app.bsky.feed.post/xyz&limit=100
+```
+
+---
+
+## 6. Listeler ve Özel Akışlar (Custom Feeds)
+
+### 6.1 Liste Oluşturma
+
+```json
+{
+  "repo": "<did>",
+  "collection": "app.bsky.graph.list",
+  "record": {
+    "$type": "app.bsky.graph.list",
+    "purpose": "app.bsky.graph.defs#curatelist",
+    "name": "Türk Geliştiriciler",
+    "description": "Türkiye'den yazılımcılar",
+    "createdAt": "2026-03-14T12:00:00.000Z"
+  }
+}
+```
+
+Liste amaçları (`purpose`):
+- `app.bsky.graph.defs#curatelist` — Kürasyon listesi (takip koleksiyonu)
+- `app.bsky.graph.defs#modlist` — Moderasyon listesi (toplu mute/block)
+
+### 6.2 Listeye Kullanıcı Ekleme
+
+```json
+{
+  "repo": "<did>",
+  "collection": "app.bsky.graph.listitem",
+  "record": {
+    "$type": "app.bsky.graph.listitem",
+    "subject": "did:plc:eklenecek_kullanici",
+    "list": "at://did:plc:abc/app.bsky.graph.list/xyz",
+    "createdAt": "2026-03-14T12:00:00.000Z"
+  }
+}
+```
+
+### 6.3 Custom Feed (Özel Akış / Feed Generator)
+
+Bluesky'da herkes kendi algoritmasını oluşturabilir. Feed generator bir web servisidir:
+
+```
+GET /xrpc/app.bsky.feed.getFeedSkeleton?feed=at://did:plc:abc/app.bsky.feed.generator/my-feed&limit=30
+```
+
+Popüler feed'ler:
+- `at://did:plc:z72i7hdynmk6r22z27h6tvur/app.bsky.feed.generator/whats-hot` — Keşfet
+- `at://did:plc:z72i7hdynmk6r22z27h6tvur/app.bsky.feed.generator/with-friends` — Arkadaşlarla
+
+Feed'leri listeleme:
+```
+GET /xrpc/app.bsky.feed.getActorFeeds?actor=kullanici.bsky.social
+GET /xrpc/app.bsky.feed.getSuggestedFeeds
+```
+
+---
+
+## 7. URL Yapısı
+
+### Web URL'leri (bsky.app)
+
+| Sayfa | URL |
+|-------|-----|
+| Profil | `https://bsky.app/profile/kullanici.bsky.social` |
+| Profil (DID ile) | `https://bsky.app/profile/did:plc:abc123` |
+| Post | `https://bsky.app/profile/kullanici.bsky.social/post/<rkey>` |
+| Post (DID ile) | `https://bsky.app/profile/did:plc:abc123/post/<rkey>` |
+| Arama | `https://bsky.app/search?q=arama_terimi` |
+| Hashtag arama | `https://bsky.app/search?q=%23hashtag` |
+| Ayarlar | `https://bsky.app/settings` |
+| Akışlar | `https://bsky.app/feeds` |
+| Bildirimler | `https://bsky.app/notifications` |
+| Listeler | `https://bsky.app/profile/kullanici.bsky.social/lists` |
+| Belirli liste | `https://bsky.app/profile/kullanici.bsky.social/lists/<rkey>` |
+| Feed | `https://bsky.app/profile/kullanici.bsky.social/feed/<rkey>` |
+| Starter Pack | `https://bsky.app/starter-pack/kullanici.bsky.social/<rkey>` |
+
+### AT Protocol URI'leri
+
+```
+at://did:plc:abc123/app.bsky.feed.post/3k...     → Post
+at://did:plc:abc123/app.bsky.feed.like/3k...      → Like kaydı
+at://did:plc:abc123/app.bsky.feed.repost/3k...    → Repost kaydı
+at://did:plc:abc123/app.bsky.graph.follow/3k...   → Follow kaydı
+at://did:plc:abc123/app.bsky.graph.block/3k...    → Block kaydı
+at://did:plc:abc123/app.bsky.graph.list/3k...     → Liste
+```
+
+### Web URL'den AT URI'ye Dönüşüm
+
+Post URL'si `https://bsky.app/profile/HANDLE/post/RKEY` formatındadır.
+1. Handle'ı DID'e çevir: `resolveHandle`
+2. AT URI oluştur: `at://<did>/app.bsky.feed.post/<rkey>`
+
+---
+
+## 8. Görsel Boyutları ve Öneriler
+
+### Post Görselleri
+
+| Özellik | Değer |
+|---------|-------|
+| Önerilen boyut | 1200 x 630 px (1.91:1 oran) |
+| Maksimum dosya boyutu | 1 MB (1.000.000 byte) |
+| Maksimum görsel sayısı | 4 adet per post |
+| Desteklenen formatlar | PNG, JPEG, WebP, GIF |
+| Minimum boyut | Belirtilmemiş, çok küçük olmamalı |
+
+### Profil Görselleri
+
+| Özellik | Değer |
+|---------|-------|
+| Avatar | 1000 x 1000 px önerilir, kare kırpılır |
+| Banner | 3000 x 1000 px önerilir (3:1 oran) |
+| Maks dosya boyutu | 1 MB |
+
+### Aspect Ratio (En-Boy Oranı)
+
+Post'a görsel eklerken `aspectRatio` belirtilmesi önerilir:
+```json
+{
+  "aspectRatio": {
+    "width": 1200,
+    "height": 630
+  }
+}
+```
+
+Yaygın oranlar:
+- **1.91:1** (1200x630) — Link kartı benzeri, yatay
+- **16:9** (1920x1080) — Geniş ekran
+- **4:3** (1200x900) — Klasik
+- **1:1** (1080x1080) — Kare
+- **4:5** (1080x1350) — Dikey (en uzun desteklenen oran)
+
+---
+
+## 9. Rate Limiting (Hız Sınırlaması)
+
+Bluesky rate limitleri çok cömerttir, diğer platformlara kıyasla oldukça rahat:
+
+### Puan Sistemi
+
+| Sınır | Değer |
+|-------|-------|
+| Toplam bütçe | **5000 puan / saat** (kayan pencere) |
+| Puan sıfırlanması | Her saat başı değil, sürekli kayan pencere |
+
+### İşlem Başına Puan Maliyeti
+
+| İşlem | Puan |
+|-------|------|
+| `createRecord` (post, like, repost, follow) | 3 puan |
+| `deleteRecord` | 1 puan |
+| `uploadBlob` (görsel/video yükleme) | 25 puan |
+| `createSession` | 3 puan |
+| Okuma işlemleri (GET) | 1 puan |
+
+### Hesaplama Örneği
+
+Saatte yapılabilecek maksimum işlemler:
+- ~1666 post (sadece metin)
+- ~200 görsel yükleme
+- ~5000 okuma isteği
+- Karma kullanım: 100 görselli post (100×25 + 100×3 = 2800 puan) + 2200 okuma
+
+### Rate Limit Yanıtı
+
+Limit aşıldığında HTTP 429 döner:
+```
+HTTP/1.1 429 Too Many Requests
+RateLimit-Limit: 5000
+RateLimit-Remaining: 0
+RateLimit-Reset: 1710421200
+RateLimit-Policy: 5000;w=3600
+```
+
+Header'lardan kalan puan ve sıfırlanma zamanı okunabilir.
+
+---
+
+## 10. Etiketler ve Moderasyon (Labels)
+
+### 10.1 Self-Label (Kendi İçeriğini Etiketleme)
+
+Post'a veya profil'e içerik uyarısı eklemek için:
+
+```json
+{
+  "record": {
+    "$type": "app.bsky.feed.post",
+    "text": "İçerik burada",
+    "createdAt": "2026-03-14T12:00:00.000Z",
+    "labels": {
+      "$type": "com.atproto.label.defs#selfLabels",
+      "values": [
+        { "val": "sexual" }
+      ]
+    }
+  }
+}
+```
+
+### 10.2 Yaygın Etiket Değerleri
+
+| Etiket | Açıklama |
+|--------|----------|
+| `sexual` | Cinsel içerik |
+| `nudity` | Çıplaklık |
+| `porn` | Pornografi |
+| `graphic-media` | Şiddet/rahatsız edici görsel |
+| `gore` | Kanlı/şiddet içeriği |
+
+### 10.3 Moderasyon Servisleri
+
+Bluesky'da moderasyon merkezi değildir. Farklı labeler servisleri içerikleri etiketler:
+
+```
+GET /xrpc/app.bsky.labeler.getServices?dids=did:plc:labeler_did
+```
+
+Kullanıcılar hangi moderasyon servislerine abone olacaklarını seçebilir.
+
+---
+
+## 11. Sayfalama (Pagination)
+
+Çoğu liste endpoint'i `cursor` tabanlı sayfalama kullanır:
+
+```
+GET /xrpc/app.bsky.feed.getTimeline?limit=50
+
+→ { "cursor": "1710421200::bafyrei...", "feed": [...] }
+
+GET /xrpc/app.bsky.feed.getTimeline?limit=50&cursor=1710421200::bafyrei...
+
+→ { "cursor": "1710420000::bafyrei...", "feed": [...] }
+```
+
+- `cursor` opak bir string'dir, içeriği değişebilir.
+- `cursor` null veya yoksa son sayfa demektir.
+- `limit` genellikle 1-100 arasıdır.
+
+---
+
+## 12. Hata Kodları
+
+| HTTP Kodu | XRPC Hatası | Açıklama |
+|-----------|-------------|----------|
+| 400 | `InvalidRequest` | Geçersiz parametre veya body |
+| 401 | `AuthenticationRequired` | Token geçersiz veya eksik |
+| 403 | `Forbidden` | Yetkisiz işlem (engelli kullanıcıya erişim vb.) |
+| 404 | `RecordNotFound` | Kayıt bulunamadı |
+| 413 | `PayloadTooLarge` | Dosya çok büyük (1 MB üzeri görsel) |
+| 429 | `RateLimitExceeded` | Rate limit aşıldı |
+| 502 | `UpstreamFailure` | PDS veya AppView hatası |
+
+Hata yanıt formatı:
+```json
+{
+  "error": "InvalidRequest",
+  "message": "Record/text must be a string with length between 1 and 300"
+}
+```
+
+---
+
+## 13. DID ve Handle Sistemi
+
+### DID (Decentralized Identifier)
+
+Her Bluesky hesabı benzersiz ve kalıcı bir DID'e sahiptir:
+- `did:plc:abc123...` — PLC (Public Ledger of Credentials) yöntemi, en yaygın
+- `did:web:example.com` — Web tabanlı DID, kendi domain'ini handle olarak kullananlar
+
+DID asla değişmez, handle değişse bile DID aynı kalır. Bu yüzden kayıtlarda (record) her zaman DID kullanılır.
+
+### Handle
+
+Handle, kullanıcının okunabilir adıdır:
+- `kullanici.bsky.social` — Varsayılan subdomain
+- `kullanici.com` — Özel domain (DNS TXT kaydı ile doğrulanır)
+
+Handle çözümleme:
+```
+GET /xrpc/com.atproto.identity.resolveHandle?handle=kullanici.bsky.social
+→ { "did": "did:plc:abc123" }
+```
+
+---
+
+## 14. PDS (Personal Data Server) Bilgisi
+
+Bluesky merkezi olmayan bir yapıdadır. Her kullanıcının verisi bir PDS'de tutulur:
+- `bsky.social` — Bluesky'ın resmi PDS'i (çoğu kullanıcı burada)
+- Üçüncü parti PDS'ler de vardır
+
+Kullanıcının PDS'ini bulmak:
+```
+GET https://plc.directory/did:plc:abc123
+→ { "service": [{ "serviceEndpoint": "https://pds.example.com" }] }
+```
+
+API istekleri genelde `bsky.social`'a yapılır, PDS yönlendirmeyi otomatik yapar.
+
+---
+
+## 15. Yararlı Kod Kalıpları
+
+### 15.1 Post Atma (Tam Akış)
+
+```typescript
+// 1. Giriş yap
+const session = await createSession(identifier, password);
+
+// 2. Görsel varsa yükle
+const blob = await uploadBlob(session.accessJwt, imageBuffer, "image/jpeg");
+
+// 3. Facet'leri oluştur
+const facets = parseFacets(text);
+
+// 4. Record oluştur
+const record = {
+  $type: "app.bsky.feed.post",
+  text: text,
+  createdAt: new Date().toISOString(),
+  langs: ["tr"],
+  facets: facets,
+  embed: blob ? {
+    $type: "app.bsky.embed.images",
+    images: [{ alt: "", image: blob, aspectRatio: { width: 1200, height: 630 } }]
+  } : undefined
+};
+
+// 5. Post gönder
+const result = await createRecord(session, "app.bsky.feed.post", record);
+const postUrl = `https://bsky.app/profile/${session.did}/post/${result.uri.split("/").pop()}`;
+```
+
+### 15.2 Thread (Zincirleme Post) Atma
+
+```typescript
+let previousUri: string | null = null;
+let previousCid: string | null = null;
+let rootUri: string | null = null;
+let rootCid: string | null = null;
+
+for (const text of threadTexts) {
+  const record: any = {
+    $type: "app.bsky.feed.post",
+    text: text,
+    createdAt: new Date().toISOString(),
+  };
+
+  if (previousUri) {
+    record.reply = {
+      root: { uri: rootUri, cid: rootCid },
+      parent: { uri: previousUri, cid: previousCid }
+    };
+  }
+
+  const result = await createRecord(session, "app.bsky.feed.post", record);
+
+  if (!rootUri) {
+    rootUri = result.uri;
+    rootCid = result.cid;
+  }
+  previousUri = result.uri;
+  previousCid = result.cid;
+}
+```
+
+### 15.3 Post URL'sinden URI Elde Etme
+
+```typescript
+async function postUrlToAtUri(url: string): Promise<string> {
+  // https://bsky.app/profile/handle.bsky.social/post/3k...
+  const match = url.match(/\/profile\/([^/]+)\/post\/([^/]+)/);
+  if (!match) throw new Error("Geçersiz post URL'si");
+
+  const [, actor, rkey] = match;
+
+  // Handle ise DID'e çevir
+  let did = actor;
+  if (!actor.startsWith("did:")) {
+    const res = await fetch(`https://bsky.social/xrpc/com.atproto.identity.resolveHandle?handle=${actor}`);
+    const data = await res.json();
+    did = data.did;
+  }
+
+  return `at://${did}/app.bsky.feed.post/${rkey}`;
+}
+```
+
+---
+
+## 16. Limitler Özeti
+
+| Limit | Değer |
+|-------|-------|
+| Post metin uzunluğu | 300 grapheme (karakter) |
+| Post başına görsel | 4 adet |
+| Görsel dosya boyutu | 1 MB |
+| Video dosya boyutu | 50 MB |
+| Video süresi | 60 saniye |
+| Bio (profil açıklaması) | 256 karakter |
+| Display name | 64 karakter |
+| Handle uzunluğu | 253 karakter |
+| Liste adı | 64 karakter |
+| Liste açıklaması | 300 karakter |
+| Rate limit | 5000 puan/saat |
+| Takip limiti | Teknik sınır yok, spam koruması var |
+| Günlük post limiti | Teknik sınır yok, rate limit dahilinde |
+| Alt text (görsel açıklama) | Teknik sınır yok |
+
+---
+
+## 17. Diğer Faydalı Endpoint'ler
+
+### Profil Güncelleme
+```
+GET /xrpc/com.atproto.repo.getRecord?repo=<did>&collection=app.bsky.actor.profile&rkey=self
+PUT /xrpc/com.atproto.repo.putRecord  (profil güncellemede putRecord kullanılır)
+```
+
+### Tercihler (Preferences)
+```
+GET /xrpc/app.bsky.actor.getPreferences
+POST /xrpc/app.bsky.actor.putPreferences
+```
+
+### Önerilen Kullanıcılar
+```
+GET /xrpc/app.bsky.actor.getSuggestions?limit=50
+```
+
+### Popüler Feed'ler
+```
+GET /xrpc/app.bsky.unspecced.getPopularFeedGenerators
+GET /xrpc/app.bsky.feed.getSuggestedFeeds
+```
+
+### Starter Pack
+```
+GET /xrpc/app.bsky.graph.getStarterPack?starterPack=at://did:plc:abc/app.bsky.graph.starterpack/xyz
+GET /xrpc/app.bsky.graph.getStarterPacks
+```
+
+---
+
+## 18. Önemli Notlar ve İpuçları
+
+1. **Tüm yazma işlemleri `createRecord`/`deleteRecord`/`putRecord` üzerinden yapılır.** Her şey (post, like, follow, block, list) birer AT Protocol kaydıdır.
+
+2. **CID zorunluluğu:** Like ve repost gibi işlemlerde hedef postun hem `uri` hem `cid` değeri gerekir. CID almak için önce `getPosts` ile post detayını çekin.
+
+3. **createdAt zorunludur.** Tüm kayıtlarda ISO 8601 formatında `createdAt` alanı bulunmalıdır.
+
+4. **Facet byte offset hatası en sık yapılan hatadır.** Karakter index'i değil byte pozisyonu kullanılmalıdır. Türkçe karakterler ve emojiler byte offset'i kaydırır.
+
+5. **Blob geçicidir.** Yüklenen görseller 1 saat içinde bir kayıtta referans verilmezse silinir. Önce görsel yükle, sonra hemen post oluştur.
+
+6. **App Password kullanın.** Ana hesap şifresini API'de kullanmayın. Bluesky ayarlarından App Password oluşturun.
+
+7. **Rate limit cömert ama dikkatli olun.** Özellikle toplu görsel yükleme hızla puan tüketir (her biri 25 puan). 200 görselde limit dolar.
+
+8. **Bluesky API tamamen ücretsizdir.** Herhangi bir API anahtarı, geliştirici hesabı veya uygulama onayı gerekmez. createSession ile hemen başlayabilirsiniz.
+
+9. **Thread oluştururken sıralama önemlidir.** Her yanıt bir öncekinin `uri` ve `cid` değerlerini bilmelidir. Sıralı (sequential) gönderim zorunludur.
+
+10. **Silinen kayıtlar geri alınamaz.** `deleteRecord` kalıcıdır.