npm package: @reibul/reistore-sdk
Description: Official Reibul Reistore SDK — Build, publish, and manage plugins for the Reibul marketplace
Author: Reibul
Latest version: 1.0.1

# @reibul/reistore-sdk

Reibul Reistore için resmi SDK — Reibul marketplace'inde plugin oluşturun, yayınlayın ve yönetin.

## Kurulum

```bash
npm install @reibul/reistore-sdk
```

## Hızlı Başlangıç

### 1. API Key Alın

Dashboard'a gidin → **Ayarlar** → **API Anahtarları** → **Yeni Anahtar Oluştur**

### 2. CLI ile Giriş Yapın

```bash
npx reistore login rbst_your_api_key_here
```

### 3. Plugin Projesi Oluşturun

```bash
npx reistore init --name "My Plugin" --slug "my-plugin"
```

Bu komut `reistore.config.json` dosyası oluşturur:

```json
{
  "name": "My Plugin",
  "slug": "my-plugin",
  "tagline": "Kısa açıklama",
  "description": "Detaylı açıklama",
  "category": "OTHER",
  "tags": ["ecommerce", "automation"],
  "version": "1.0.0",
  "isFree": true,
  "developer": {
    "name": "Developer Adı",
    "url": "https://example.com",
    "email": "dev@example.com"
  },
  "assets": {
    "icon": "./assets/icon.png",
    "banner": "./assets/banner.png",
    "screenshots": ["./assets/screenshot-1.png"]
  },
  "links": {
    "demo": "https://demo.example.com",
    "docs": "https://docs.example.com",
    "repo": "https://github.com/user/plugin"
  }
}
```

### 4. Yayınlayın

```bash
npx reistore publish
```

---

## SDK Kullanımı (Programatik)

```typescript
import { ReistoreClient } from "@reibul/reistore-sdk";

const client = new ReistoreClient({
  apiKey: "rbst_...",
  // baseUrl: "https://reibul.com/api/reistore"  (varsayılan)
});
```

### Plugin İşlemleri

```typescript
// Pluginleri listele
const { data: plugins } = await client.plugins.list({
  status: "PUBLISHED",
  category: "MARKETING",
  sort: "popular",
});

// Plugin detayı
const plugin = await client.plugins.get("my-plugin");

// Yeni plugin oluştur
const newPlugin = await client.plugins.create({
  name: "Analytics Pro",
  slug: "analytics-pro",
  tagline: "Gelişmiş e-ticaret analitiği",
  description: "Mağazanız için kapsamlı analitik araçları...",
  category: "ANALYTICS",
  tags: ["analytics", "reporting", "dashboard"],
  isFree: false,
  price: 9.99,
});

// Plugin güncelle
await client.plugins.update("analytics-pro", {
  tagline: "Yeni geliştirilmiş analitik araçları",
  price: 14.99,
});

// Yayınla
await client.plugins.publish("analytics-pro");

// Arşivle
await client.plugins.archive("analytics-pro");

// Arşivden çıkar
await client.plugins.unarchive("analytics-pro");

// Taslak plugini sil
await client.plugins.delete("draft-plugin");
```

### Asset Yükleme

```typescript
// İkon yükle
await client.assets.uploadIcon("my-plugin", "./assets/icon.png");

// Banner yükle
await client.assets.uploadBanner("my-plugin", "./assets/banner.png");

// Ekran görüntüsü yükle
await client.assets.uploadScreenshot("my-plugin", "./assets/ss-1.png");

// Birden fazla ekran görüntüsü
await client.assets.uploadScreenshots("my-plugin", [
  "./assets/ss-1.png",
  "./assets/ss-2.png",
  "./assets/ss-3.png",
]);

// Ekran görüntüsü sil
await client.assets.removeScreenshot("my-plugin", "https://...");
```

### Versiyon Yönetimi

```typescript
// Versiyonları listele
const { data: versions } = await client.versions.list("my-plugin");

// Yeni versiyon oluştur
const version = await client.versions.create("my-plugin", {
  version: "2.0.0",
  changelog: "- Yeni dashboard\n- Performans iyileştirmeleri\n- Bug düzeltmeleri",
  minPlatform: "3.0.0",
});

// Versiyonu yayınla
await client.versions.publish("my-plugin", "2.0.0");
```

### Değerlendirmeler

```typescript
// Değerlendirmeleri oku
const { data: reviews } = await client.reviews.list("my-plugin", {
  sort: "newest",
  pageSize: 10,
});

// Değerlendirme yap
await client.reviews.create("some-plugin", {
  rating: 5,
  title: "Harika plugin!",
  comment: "Kurulumu çok kolay ve performansı mükemmel.",
});

// Değerlendirmeni güncelle
await client.reviews.update("some-plugin", { rating: 4 });

// Değerlendirmeni sil
await client.reviews.delete("some-plugin");
```

### Analitik

```typescript
// Plugin istatistikleri
const stats = await client.analytics.getStats("my-plugin", 30);
console.log(`Toplam kurulum: ${stats.installCount}`);
console.log(`Aktif kurulum: ${stats.activeInstalls}`);
console.log(`Puan: ${stats.rating} (${stats.ratingCount} değerlendirme)`);

// Genel dashboard
const dashboard = await client.analytics.getDashboard();
console.log(`Toplam plugin: ${dashboard.totalPlugins}`);
console.log(`Toplam kurulum: ${dashboard.totalInstalls}`);
```

---

## CLI Komutları

| Komut | Açıklama |
|---|---|
| `reistore login <api-key>` | API key ile giriş yap |
| `reistore whoami` | Giriş yapan kullanıcıyı göster |
| `reistore init` | Yeni plugin projesi başlat |
| `reistore list` | Pluginlerini listele |
| `reistore info <slug>` | Plugin detaylarını göster |
| `reistore publish` | Config'den plugin yayınla |
| `reistore publish --draft` | Taslak olarak kaydet |
| `reistore upload <slug> icon ./icon.png` | Asset yükle |
| `reistore stats <slug>` | Analitik göster |
| `reistore version list <slug>` | Versiyonları listele |
| `reistore version create <slug> 2.0.0` | Yeni versiyon oluştur |
| `reistore version publish <slug> 2.0.0` | Versiyon yayınla |

### CLI Seçenekleri

```bash
# JSON çıktısı
reistore list --json
reistore info my-plugin --json
reistore stats my-plugin --json

# Filtreleme
reistore list --status PUBLISHED
reistore list --category MARKETING

# İstatistik periyodu
reistore stats my-plugin --days 90

# Versiyon changelog
reistore version create my-plugin 2.0.0 -m "Yeni özellikler eklendi"
```

---

## Yapılandırma

API key aşağıdaki öncelik sırasına göre çözümlenir:

1. Parametre olarak verilen `apiKey`
2. `REISTORE_API_KEY` ortam değişkeni
3. Proje dizinindeki `reistore.config.json` → `apiKey`
4. `~/.reistore/config.json` → `apiKey` (login komutuyla kaydedilir)

### ReistoreConfig

```typescript
interface ReistoreConfig {
  apiKey: string;         // API anahtarı (zorunlu)
  baseUrl?: string;       // API base URL (varsayılan: https://reibul.com/api/reistore)
  timeout?: number;       // İstek zaman aşımı ms (varsayılan: 30000)
  retries?: number;       // Tekrar deneme sayısı (varsayılan: 2)
  debug?: boolean;        // Debug logları (varsayılan: false)
}
```

---

## Hata Yönetimi

```typescript
import {
  ReistoreError,
  AuthenticationError,
  AuthorizationError,
  NotFoundError,
  ValidationError,
  RateLimitError,
  NetworkError,
} from "@reibul/reistore-sdk";

try {
  await client.plugins.create({ ... });
} catch (err) {
  if (err instanceof ValidationError) {
    console.error("Doğrulama hatası:", err.message);
  } else if (err instanceof AuthenticationError) {
    console.error("API key geçersiz");
  } else if (err instanceof RateLimitError) {
    console.error(`Rate limit, ${err.retryAfter}s sonra tekrar deneyin`);
  } else if (err instanceof NotFoundError) {
    console.error("Plugin bulunamadı");
  }
}
```

---

## Plugin Kategorileri

| Kategori | Açıklama |
|---|---|
| `ANALYTICS` | Analitik ve raporlama araçları |
| `MARKETING` | Pazarlama ve kampanya yönetimi |
| `SHIPPING` | Kargo ve lojistik entegrasyonları |
| `PAYMENTS` | Ödeme ve finans araçları |
| `AUTOMATION` | İş süreçleri otomasyonu |
| `DESIGN` | Tasarım ve tema araçları |
| `SEO` | SEO optimizasyon araçları |
| `INTEGRATIONS` | Üçüncü parti entegrasyonlar |
| `OTHER` | Diğer |

---

## API Scopes

| Scope | Açıklama |
|---|---|
| `plugins:read` | Plugin bilgilerini okuma |
| `plugins:write` | Plugin oluşturma ve güncelleme |
| `versions:write` | Versiyon oluşturma ve yayınlama |
| `assets:write` | Asset yükleme ve silme |
| `*` | Tüm yetkiler |

---

## Lisans

MIT — Reibul © 2024-2026