@capsarsiv/sdk

Caps Arşivi developer API SDK. Bu paket, Türkçe Caps Arşivi API uçlarını modern TypeScript fonksiyonları olarak kullanmanızı sağlar.

Bu npm modülü official bir Caps Arşivi modülü değildir. Topluluk tarafından hazırlanmış bağımsız bir SDK'dır.

Özellikler

• x-api-key kimlik doğrulamasını otomatik yönetir
• Caps listeleme, arama, detay, rastgele caps ve tag uçları
• Türkçe, güvenli ve anlaşılır hata mesajları
• Timeout desteği
• Bun, Node.js 18+ ve modern edge runtime'lar ile uyumlu fetch tabanlı yapı

Kurulum

bun add @capsarsiv/sdk

API key alma

1. Caps Arşivi üyelik sayfasından giriş yapın.
2. Hesabınız altındaki developer API bölümüne gidin.
3. API key oluştur butonuyla key oluşturun.
4. Key sadece oluşturulduğu anda gösterilir, güvenli bir ortam değişkeninde saklayın.

API her istekte x-api-key header'ı bekler. SDK bunu sizin için otomatik ekler.

Hızlı başlangıç

import { createCapsarsivClient } from "@capsarsiv/sdk";

const capsarsiv = createCapsarsivClient({
  apiKey: process.env.CAPSARSIV_API_KEY!,
});

const caps = await capsarsiv.getCaps({
  q: "futbol",
  sort: "popular",
  limit: 5,
});

console.log(caps.items);

Client oluşturma

import { CapsarsivClient } from "@capsarsiv/sdk";

const client = new CapsarsivClient({
  apiKey: process.env.CAPSARSIV_API_KEY!,
  timeoutMs: 10_000,
});

Config seçenekleri

apiKey zorunludur ve Caps Arşivi developer API key değerini alır. baseUrl normal kullanımda verilmez, varsayılan olarak https://capsarsiv.com kullanılır. timeoutMs verilmediğinde istekler 10 saniye içinde tamamlanmazsa iptal edilir. Özel runtime'larda global fetch yerine kendi fetch implementasyonunuzu da verebilirsiniz.

Fonksiyonlar

Capsleri listele ve ara

const response = await capsarsiv.getCaps({
  q: "futbol",
  tag: "spor",
  sort: "popular",
  limit: 10,
});

console.log(response.items);

Parametreler:

sort ile sıralama seçebilirsiniz. Desteklenen değerler newest, popular, trend ve random değerleridir. q başlık, açıklama, tag ve alternatif adlarda arama yapar. tag tek bir tag'e göre filtreleme sağlar. limit değeri 1 ile 100 arasında olmalıdır, verilmezse API kendi varsayılan limitini kullanır.

Rastgele caps getir

const cap = await capsarsiv.getRandomCap({
  exclude: ["ornek-caps", "baska-caps"],
});

console.log(cap.title);

exclude alanı string veya string listesi olabilir. Liste verdiğinizde SDK bunu virgülle ayrılmış slug listesine dönüştürür.

Slug ile tek caps getir

const cap = await capsarsiv.getCap("ornek-caps");

console.log(cap.image_url);

Caps bulunamazsa API 404 döner ve SDK CapsarsivHttpError fırlatır.

Tagleri listele

const tags = await capsarsiv.getTags({
  limit: 40,
});

console.log(tags.items);

Parametreler:

limit değeri 1 ile 200 arasında olmalıdır. Değer verilmezse API varsayılan olarak 40 tag döndürür.

Response tipleri

Cap

type Cap = {
  slug: string;
  title: string;
  image_url: string;
  image_version: number;
  description: string | null;
  type: string;
  tags: string[];
  aliases: string[];
  score: number;
  source_url: string | null;
  view_count: number;
  created_order: number;
};

Tag

type Tag = {
  name: string;
  count: number;
};

Hata yönetimi

SDK hataları Türkçe mesajlarla döndürür.

import {
  CapsarsivHttpError,
  CapsarsivValidationError,
  createCapsarsivClient,
} from "@capsarsiv/sdk";

const capsarsiv = createCapsarsivClient({
  apiKey: process.env.CAPSARSIV_API_KEY!,
});

try {
  const cap = await capsarsiv.getCap("olmayan-caps");
  console.log(cap);
} catch (error) {
  if (error instanceof CapsarsivValidationError) {
    console.error(error.code, error.message);
    throw error;
  }

  if (error instanceof CapsarsivHttpError) {
    console.error(error.status, error.code, error.message);
    throw error;
  }

  throw error;
}

Yaygın hata kodları:

DOGRULAMA_HATASI, SDK tarafında parametre doğrulaması başarısız olduğunda döner. API key eksik veya geçersizse YETKISIZ_ERISIM, caps bulunamazsa KAYIT_BULUNAMADI, kota veya rate limit aşılırsa LIMIT_ASILDI kodu kullanılır. Bağlantı, timeout veya ağ sorunlarında AG_HATASI; diğer başarısız HTTP cevaplarında API_HATASI döner.

Limitler

Caps Arşivi developer API limitleri:

• Dakikada en fazla 60 istek
• API key başına aylık 1000 istek
• Limit aşımında API 429 döndürür

SDK otomatik retry yapmaz. Kota ve rate limit kontrolünü uygulamanızın kullanım senaryosuna göre yönetmeniz önerilir.

Lisans

Bu proje MIT lisansı altında lisanslanmıştır.