> ## Documentation Index
> Fetch the complete documentation index at: https://developer.leaderos.net/llms.txt
> Use this file to discover all available pages before exploring further.

# NPM Paketleri: SDK ve React

> @leaderos/headless-sdk ve @leaderos/headless-react paketlerinin kurulumu ve kullanımı.

Headless API'yi `fetch` ile elle çağırabilirsiniz, ancak resmi paketler tip güvenliği, hata yönetimi ve Next.js entegrasyonu sağlar.

| Paket | Ne işe yarar | Ortam |
| - | - | - |
| `@leaderos/headless-sdk` | Tipli, `fetch` tabanlı API istemcisi | Tarayıcı, Node.js 18+, Next.js, Deno, Bun |
| `@leaderos/headless-react` | Provider, hook'lar, `<PoweredBy/>`, `<Turnstile/>` | React 18+ |
| `@leaderos/headless-react/next` | Sunucu istemcisi ve API proxy rotası | Next.js (App Router) |
| `@leaderos/headless-mcp` | Yapay zeka için MCP sunucusu | [MCP sayfası](https://developer.leaderos.net/headless/tr/mcp.md) |
| `create-leaderos-theme` | Proje oluşturucu | [Kurulum sayfası](https://developer.leaderos.net/headless/tr/create-leaderos-theme.md) |

> [!NOTE]
>
> `create-leaderos-theme` kullanıyorsanız paketler zaten kurulu gelir. Bu sayfa mevcut bir projeye eklemek veya mantığı anlamak içindir.

## @leaderos/headless-sdk

### Kurulum

```bash theme={null}
npm install @leaderos/headless-sdk
```

### İstemci oluşturma

```ts theme={null}
import { createClient, localStorageTokenStore, isLeaderOSError } from '@leaderos/headless-sdk';

const leaderos = createClient({
  baseUrl: 'https://siteniz.com',         // sonunda / olmadan
  publicKey: 'pk_live_XXXXXXXX',          // Ayarlar → Headless API
  tokenStore: localStorageTokenStore(),   // SPA için; Next.js'te aşağıya bakın
});
```

### Kullanım

SDK, API gruplarını birebir yansıtır:

```ts theme={null}
const { data: config } = await leaderos.site.config();
await leaderos.auth.login({ username, password });
const { data: cart } = await leaderos.cart.items();
const { data: posts, meta } = await leaderos.blog.posts.list({ page: 2 });
```

Mevcut gruplar arasında `site`, `auth`, `account`, `store`, `cart`, `payments`, `credits`, `chest`, `forum`, `support`, `blog`, `help`, `suggestions`, `applications`, `forms` ve `server` (play, vote, staff) bulunur. Hangi metodun hangi endpoint'e karşılık geldiği için OpenAPI'deki `operationId` değerlerine bakın.

### Hata yönetimi

```ts theme={null}
try {
  const { data: intent } = await leaderos.cart.checkout({ paymentGateway: 'stripe', terms: true });
  leaderos.payments.start(intent); // tarayıcıyı ödeme sayfasına götürür
} catch (error) {
  if (isLeaderOSError(error)) {
    if (error.code === 'CONTACT_REQUIRED') { /* ad/telefon iste */ }
    if (error.code === 'VALIDATION_FAILED') console.log(error.fieldError('email'));
    console.log(error.status, error.fields, error.details);
  }
}
```

`LeaderOSError` alanları: `code`, `status`, `fields`, `details`. **`message`'a göre değil, `code`'a göre dallanın.**

### İstek başına seçenekler

Her metodun son parametresi `options` nesnesidir (`query`, `headers`, `signal`, `fetch`):

```ts theme={null}
await leaderos.blog.posts.list({ page: 1 }, {
  headers: { 'X-Locale': 'tr' },
  signal: controller.signal,
  fetch: { next: { revalidate: 60 } }, // Next.js önbelleği
});
```

### Tipler

OpenAPI'den üretilen tüm şemalar dışa aktarılır:

```ts theme={null}
import type { Cart, StoreProduct, ForumThread, User } from '@leaderos/headless-sdk';
```

## @leaderos/headless-react

### Kurulum

```bash theme={null}
npm install @leaderos/headless-react @leaderos/headless-sdk react
```

### Provider ve hook'lar

```tsx theme={null}
import { LeaderOSProvider, createBrowserClient, useLeaderOS, useUser, useModule, PoweredBy, Turnstile } from '@leaderos/headless-react';

<LeaderOSProvider client={createBrowserClient()} config={config} user={user}>
  {children}
</LeaderOSProvider>
```

| Bileşen / hook | Görev |
| - | - |
| `useLeaderOS()` | İstemci bileşenlerde API istemcisini verir |
| `useUser()` | Mevcut kullanıcı; `setCredits(data)` ile bakiyeyi yenilemeden günceller |
| `useModule('forum')` | Modül aktif mi? |
| `useApi((api) => api.blog.posts.list(), [])` | Basit veri çekme hook'u |
| `<PoweredBy config={config} />` | **Zorunlu** "Powered by LeaderOS" bağlantısı |
| `<Turnstile page="login" onToken={setToken} />` | Cloudflare Turnstile; captcha gerekmiyorsa hiçbir şey çizmez |

> [!WARNING]
>
> `<PoweredBy />` bileşenini silmeyin, gizlemeyin veya benzeriyle değiştirmeyin. Yalnızca `config.branding.canRemove` değeri `true` ise kaldırılabilir.

## Next.js entegrasyonu

Ortam değişkenleri (`.env.local`):

```bash theme={null}
LEADEROS_URL=https://siteniz.com
LEADEROS_PUBLIC_KEY=pk_live_XXXXXXXX
```

### Sunucu istemcisi (Server Components / Server Actions)

```ts theme={null}
// lib/leaderos.ts
import { cookies, headers } from 'next/headers';
import { createServerClient } from '@leaderos/headless-react/next';

export const leaderos = async () =>
  createServerClient({ cookies: await cookies(), headers: await headers() });
```

Bu istemci kullanıcı token'ını `httpOnly` çerezden okur ve ziyaretçinin IP'sini `X-Forwarded-For` ile API'ye iletir.

```tsx theme={null}
// app/blog/page.tsx
import { leaderos } from '@/lib/leaderos';

export default async function Blog() {
  const api = await leaderos();
  const { data: posts } = await api.blog.posts.list();
  return posts.map((p) => <h2 key={p.id}>{p.title}</h2>);
}
```

### Proxy rotası (tarayıcı istekleri)

```ts theme={null}
// app/headless/v1/[...path]/route.ts
import { createProxyHandler } from '@leaderos/headless-react/next';
export const { GET, POST, PUT, PATCH, DELETE } = createProxyHandler();
```

Tarayıcıdaki istemci (`createBrowserClient()`) istekleri bu rotaya gönderir. Proxy:

* public key'i ve kullanıcı token'ını sunucuda ekler (**tarayıcı hiçbir zaman token'ı görmez**),
* token'ı giriş/kayıtta `httpOnly` çereze yazar, şifre/e-posta değişikliğinde yeniler, çıkışta siler,
* siteler arası (cross-site) yazma isteklerini engeller.

Bu sayede CORS ayarına bile ihtiyaç kalmaz çünkü tarayıcı yalnızca kendi alan adınıza istek atar.

> [!TIP]
>
> Public key tarayıcıda görünebilir ancak proxy kullanırsanız hiç görünmez. Üretimde proxy kullanmanız önerilir.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.