# trkit dokümantasyonu (tamamı)

> Tek komutla Türkçe Next.js projesi: KVKK, çerez onayı, il/ilçe, TCKN/IBAN doğrulama, iyzico/PayTR, Netgsm ve AI asistanları için hazır kurallar.

Kaynak: https://zersjs.github.io/trkit/docs — Bu dosya AI asistanlarına bağlam olarak verilmek üzere hazırlanmıştır.

---

# trkit nedir?

URL: https://zersjs.github.io/trkit/docs/index.md

> Türk geliştiriciler için hazır Next.js altyapısı. Her projede yeniden yazdığınız yerel ihtiyaçları tek komutla kurar.

trkit, Next.js'in Türkiye için ayarlanmış hâlidir. Yeni bir proje açtığınızda Türkçe varsayılanlar, KVKK sayfaları, çerez onayı, il/ilçe seçici, TCKN/IBAN doğrulama ve TL/tarih biçimlendirme hazır gelir. E-ticaret şablonunda iyzico/PayTR ödeme ve Netgsm SMS altyapısı da eklenir.

```bash
npx create-trkit-app@latest benim-sitem
```

### Neden?

Türkiye'de web projesi geliştiren herkes aynı işleri tekrar tekrar yapıyor:

- KVKK aydınlatma metni, açık rıza, çerez politikası, mesafeli satış sözleşmesi sayfalarını başka bir siteden kopyalayıp düzenlemek
- İl/ilçe listesi için JSON aramak, seçici bileşeni baştan yazmak
- TCKN, VKN ve IBAN doğrulama algoritmalarını internetten bulmak
- iyzico ve PayTR'nin imza ve bildirim (callback) akışını her seferinde yeniden çözmek
- `toUpperCase()` ile "istanbul"un "ISTANBUL" olması, sunucunun UTC saatiyle yanlış gün göstermesi gibi Türkçeye özgü hatalar

trkit bunları test edilmiş, versiyonlanmış paketler ve projenize kopyalanan, düzenleyebileceğiniz bileşenler olarak sunar.

### Neler var?

| | |
|---|---|
| **create-trkit-app** | Tek komutla Türkçe Next.js projesi |
| **trkit CLI** | `npx trkit add kvkk` gibi komutlarla mevcut projeye bileşen ve sayfa ekleme |
| **@trkit-app-pack/validate** | TCKN, VKN, IBAN, telefon, plaka; Türkçe zod mesajları |
| **@trkit-app-pack/format** | TL, İstanbul saatiyle tarih, göreli zaman, tutarı yazıya çevirme, hâl ekleri |
| **@trkit-app-pack/address** | 81 il, 973 ilçe, Türkçe duyarsız arama |
| **@trkit-app-pack/legal** | 8 yasal metin şablonu, çerez onayı ve onay kayıtları |
| **@trkit-app-pack/pay** | iyzico, PayTR, test için mock |
| **@trkit-app-pack/sms** | Netgsm, İYS filtresi, OTP |
| **@trkit-app-pack/mcp** | AI asistanları için MCP sunucusu |

### AI ile geliştiriyorsanız

Oluşturulan her projede `AGENTS.md`, `CLAUDE.md`, Cursor kuralları ve MCP ayarları bulunur. Claude Code, Cursor, Codex veya ChatGPT'ye "bu siteye iyzico ile ödeme ekle" dediğinizde asistan trkit'in kurallarına uygun kod yazar. Ayrıntılar: [AI ile geliştirme](/docs/ai).

Bu dokümantasyonun tamamı AI asistanlarına verilmek üzere [llms-full.txt](/llms-full.txt) olarak da hazırdır.

### Yol haritası

trkit şu an 0.1 sürümünde. Planlanan e-Fatura/e-Arşiv, kargo, ödemede 3D Secure ve abonelik, mahalle verisi, NVİ ile kimlik doğrulama, İYS entegrasyonu ve hazır uygulama şablonları için [yol haritasına](https://github.com/zersjs/trkit/blob/main/ROADMAP.md) bakın.

### Hukuki uyarı

trkit'in yasal metinleri ilgili mevzuata (6698, 6502, 6563 sayılı Kanunlar ve ilgili yönetmelikler) dayanan **şablonlardır** ve hukuki danışmanlık yerine geçmez. Yayına almadan önce işletmenize özgü veri işleme faaliyetlerine göre bir avukata kontrol ettirin.

---

# Kurulum

URL: https://zersjs.github.io/trkit/docs/kurulum.md

> create-trkit-app ile tek komutla Türkçe Next.js projesi oluşturun.

### Gereksinimler

- Node.js 20.9 veya üzeri
- npm, pnpm, yarn veya bun

### Yeni proje

```bash
npx create-trkit-app@latest benim-sitem
```

Komut size proje adını ve şablonu sorar, dosyaları oluşturur, bağımlılıkları kurar ve bir git deposu başlatır. Ardından:

```bash
cd benim-sitem
npm run dev
```

Tarayıcıda [http://localhost:3000](http://localhost:3000) adresini açın.

Diğer paket yöneticileriyle:

```bash
pnpm create trkit-app benim-sitem
yarn create trkit-app benim-sitem
bun create trkit-app benim-sitem
```

### Şablonlar

| Şablon | İçerik |
|---|---|
| `minimal` | Türkçe temel, KVKK aydınlatma metni, çerez politikası ve onay banner'ı, il/ilçe seçici, örnek iletişim formu |
| `kurumsal` (varsayılan) | Minimal + açık rıza metni, KVKK başvuru formu, ticari ileti onayı, il/ilçe arama |
| `eticaret` | Kurumsal + mesafeli satış sözleşmesi, ön bilgilendirme formu, teslimat-iade koşulları, iyzico/PayTR ödeme, ödeme onay kutuları, SMS ve OTP |

```bash
npx create-trkit-app@latest magaza --sablon eticaret
```

### Seçenekler

| Seçenek | Açıklama |
|---|---|
| `--sablon <ad>` | `minimal`, `kurumsal` veya `eticaret` |
| `--use-npm`, `--use-pnpm`, `--use-yarn`, `--use-bun` | Paket yöneticisini seçer (varsayılan: komutu çalıştırdığınız yönetici) |
| `--no-install` | Bağımlılıkları kurmaz |
| `--no-git` | Git deposu oluşturmaz |
| `-y`, `--yes` | Soru sormadan varsayılanlarla ilerler (CI ve AI ajanları için) |

> AI ajanına proje oluşturtuyorsanız `--yes` ile çalıştırın; etkileşimli sorular ajanı bekletir.

### İlk yapılacaklar

1. `src/trkit.config.ts` dosyasında şirket bilgilerinizi (unvan, MERSİS, adres, telefon, e-posta) doldurun.
2. Eksikleri kontrol edin:

   ```bash
   npx trkit check
   ```

3. `.env.example` dosyasını `.env.local` olarak kopyalayın ve değerleri girin.
4. Yayına almadan önce [kontrol listesini](/docs/rehber/yayina-alma) gözden geçirin.

### Mevcut bir projeniz mi var?

create-trkit-app yerine trkit CLI ile parça parça ekleyebilirsiniz: [Mevcut projeye ekleme](/docs/mevcut-projeye-ekleme).

---

# Proje yapısı

URL: https://zersjs.github.io/trkit/docs/proje-yapisi.md

> create-trkit-app ile oluşturulan projedeki dosyalar ve ne işe yaradıkları.

```text
benim-sitem/
├── AGENTS.md                  # AI asistanları için proje kuralları
├── CLAUDE.md                  # Claude Code (AGENTS.md'yi içe aktarır)
├── .mcp.json                  # Claude Code için trkit MCP sunucusu
├── .cursor/
│   ├── mcp.json               # Cursor için trkit MCP sunucusu
│   └── rules/trkit.mdc        # Cursor kuralları
├── .vscode/mcp.json           # VS Code (Copilot) için trkit MCP sunucusu
├── .env.example
├── src/
│   ├── trkit.config.ts        # Şirket bilgileri; yasal metinler buradan üretilir
│   ├── app/
│   │   ├── layout.tsx         # lang="tr", font, çerez onayı, header/footer
│   │   ├── page.tsx
│   │   ├── not-found.tsx      # Türkçe 404
│   │   ├── error.tsx          # Türkçe hata sayfası
│   │   ├── iletisim/          # Örnek form: server action + zod + il/ilçe
│   │   ├── kvkk/              # Yasal sayfalar (şablona göre değişir)
│   │   ├── cerez-politikasi/
│   │   ├── api/consent/       # Çerez onay kayıtları
│   │   ├── robots.ts
│   │   └── sitemap.ts
│   ├── components/
│   │   ├── site-header.tsx
│   │   ├── site-footer.tsx    # Yasal bağlantılar + "Çerez Tercihleri"
│   │   └── trkit/             # trkit bileşenleri (sizin kodunuz, düzenleyebilirsiniz)
│   └── lib/
│       ├── site.ts            # Site adı, menü ve footer bağlantıları
│       └── zod.ts             # Türkçe hata mesajlı zod
└── package.json
```

trkit CLI dizin yollarını (`src/app`, `src/components`, import takma adı) projeden otomatik algılar. Farklı bir düzen kullanıyorsanız `npx trkit init` ile oluşan `trkit.json` dosyasında değiştirebilirsiniz.

### İki tür kod

**npm paketleri** (`@trkit-app-pack/validate`, `@trkit-app-pack/format`, `@trkit-app-pack/legal`…): Mantık ve veri. Güncellemeleri `npm update` ile alırsınız. Örneğin mevzuat değiştiğinde yasal metin şablonları yeni sürümle güncellenir.

**Kopyalanan bileşenler** (`src/components/trkit/`, yasal sayfalar, `src/lib/pay.ts`…): shadcn/ui'daki gibi projenize kopyalanır, size aittir. Tasarımı ve davranışı istediğiniz gibi değiştirebilirsiniz.

### `src/lib/zod.ts`

zod'un hata mesajlarını Türkçe yapar. Şemalarınızda zod'u doğrudan değil buradan içe aktarın:

```ts
import { z } from "@/lib/zod";

z.string().min(3).parse("a"); // "En az 3 karakter olmalıdır"
```

### `src/lib/site.ts`

Site adı, açıklaması, üst menü ve footer'daki yasal bağlantılar burada. Yeni bir yasal sayfa eklediğinizde (`npx trkit add mesafeli-satis`) bağlantısını `legal` dizisine ekleyin.

---

# trkit CLI

URL: https://zersjs.github.io/trkit/docs/cli.md

> Bileşen ve sayfa ekleme, yasal metinleri kontrol etme ve dışa aktarma komutları.

Projede `@trkit-app-pack/cli` geliştirme bağımlılığı olarak kuruludur; `npx trkit` ile çalıştırılır.

### `trkit list`

Eklenebilecek tüm öğeleri listeler.

```bash
npx trkit list
```

| Öğe | Tür | Açıklama |
|---|---|---|
| `kvkk`, `acik-riza`, `cerez-politikasi`, `mesafeli-satis`, `on-bilgilendirme`, `teslimat-iade`, `ticari-ileti`, `kvkk-basvuru` | Sayfa | Tek bir yasal sayfa |
| `yasal` | Sayfa | Tüm yasal sayfalar |
| `cerez-banner` | Bileşen | Çerez onay banner'ı, `ConsentGate`, onay kayıt uç noktası |
| `il-ilce-secici` | Bileşen | Bağımlı il/ilçe `<select>`'leri |
| `il-ilce-arama` | Bileşen | Türkçe duyarsız il/ilçe combobox'ı |
| `odeme` | Uç nokta | `lib/pay.ts` ve `/api/odeme/callback` |
| `odeme-onaylari` | Bileşen | Ön bilgilendirme + mesafeli satış onayı |
| `sms` | Kütüphane | `lib/sms.ts`: SMS ve OTP |
| `config` | Kütüphane | `trkit.config.ts` |

### `trkit add`

```bash
npx trkit add odeme odeme-onaylari
```

- Bağımlılıkları (`registryDependencies`) otomatik çözer. Örneğin `kvkk` eklemek `legal-page` bileşenini ve `trkit.config.ts`'i de ekler.
- Var olan dosyaların üzerine yazmaz. Üzerine yazmak için `--overwrite`.
- Kurulması gereken npm paketlerini, gereken ortam değişkenlerini ve kurulum notlarını yazdırır.
- `--install` ile paketleri otomatik kurar, `--dry-run` ile yalnızca ne yapacağını gösterir.

Dosyalar projenizin yapısına göre yerleştirilir: `src/` kullanıyorsanız `src/app`, shadcn/ui'nin `components.json` dosyası varsa onun dizinleri, `tsconfig.json`'daki import takma adı (`@/`, `~/`…).

### `trkit check`

`trkit.config.ts`'e göre tüm yasal metinleri üretir ve eksik bilgileri raporlar.

```bash
npx trkit check
```

```text
✓ Çerez Politikası
⚠ Mesafeli Satış Sözleşmesi
    – MERSİS no eksik
    – Telefon eksik
⚠ KVKK Aydınlatma Metni
    – Yurt dışı aktarım belirtilmedi. Vercel, AWS, Google Analytics... kullanıyorsanız kvkk.yurtDisiAktarim alanını doldurun
```

CI'da eksik bilgiyle yayına çıkmayı engellemek için `--strict` (uyarı varsa çıkış kodu 1).

> TypeScript config dosyasını okumak için Node.js 22.18 veya üzeri gerekir. Daha eski sürümlerde `npx tsx node_modules/.bin/trkit check` kullanın.

### `trkit generate`

Bir yasal metni dosyaya yazar; Next.js dışındaki projeler, PDF'e çevirme veya avukata gönderme için kullanışlıdır.

```bash
npx trkit generate kvkk-aydinlatma --format md --out kvkk.md
npx trkit generate mesafeli-satis --format html --out mesafeli.html
```

Biçimler: `md`, `html`, `txt`.

### `trkit init`

Mevcut bir projede `trkit.json` ve `trkit.config.ts` oluşturur. create-trkit-app ile oluşturulan projelerde gerekmez.

---

# Mevcut projeye ekleme

URL: https://zersjs.github.io/trkit/docs/mevcut-projeye-ekleme.md

> Var olan bir Next.js projesine trkit'i adım adım ekleyin.

trkit'in parçaları birbirinden bağımsızdır. Yalnızca ihtiyacınız olanı ekleyebilirsiniz.

### Sadece paketler

Doğrulama ve biçimlendirme gibi saf fonksiyonlar için CLI gerekmez:

```bash
npm install @trkit-app-pack/validate @trkit-app-pack/format @trkit-app-pack/address
```

### CLI ile bileşen ve sayfalar

```bash
npx @trkit-app-pack/cli init
npx @trkit-app-pack/cli add yasal cerez-banner il-ilce-secici
```

`init` projenizin yapısını algılar (`src/` dizini, `tsconfig` import takma adı, shadcn/ui `components.json`) ve `trkit.json` dosyasına yazar. Algılanan yolları değiştirmek isterseniz bu dosyayı düzenleyin:

```json title="trkit.json"
{
  "aliases": { "app": "src/app", "components": "src/components", "lib": "src/lib", "src": "src" },
  "importAlias": "@/"
}
```

### Gerekli ayarlar

**Tailwind CSS**: Bileşenler shadcn/ui ile aynı renk adlarını kullanır (`bg-background`, `border-input`, `text-muted-foreground`, `bg-primary`…). Projenizde shadcn/ui varsa ek ayar gerekmez. Yoksa bu değişkenleri tanımlayın; örnek için create-trkit-app şablonundaki `globals.css` dosyasına bakın.

**Typography**: Yasal sayfalar `prose` sınıfını kullanır:

```bash
npm install -D @tailwindcss/typography
```

```css title="globals.css"
@plugin "@tailwindcss/typography";
```

**Çerez banner'ı**: `layout.tsx` içinde sayfa içeriğini sarın:

```tsx title="app/layout.tsx"
import { CookieConsentProvider } from "@/components/trkit/cerez-banner";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="tr">
      <body>
        <CookieConsentProvider>{children}</CookieConsentProvider>
      </body>
    </html>
  );
}
```

**Türkçe zod mesajları**:

```ts title="lib/zod.ts"
import { z } from "zod";
import { zodTurkce } from "@trkit-app-pack/validate";

zodTurkce(z);
export { z };
```

**AI dosyaları**: create-trkit-app'in ürettiği `AGENTS.md` dosyasını projenize kopyalayıp düzenleyebilirsiniz. Ayrıntılar: [AI ile geliştirme](/docs/ai).

---

# AI ile geliştirme

URL: https://zersjs.github.io/trkit/docs/ai.md

> trkit projeleri Claude Code, Cursor, Codex, ChatGPT ve diğer AI asistanlarıyla çalışmaya hazır gelir.

AI asistanları Next.js'i iyi bilir ama Türkiye'ye özgü kuralları bilmez: KVKK'da aydınlatma ile açık rızanın farkını, iyzico'nun bildirim akışını, paranın neden kuruş cinsinden tutulması gerektiğini, sunucunun UTC saatiyle neden yanlış tarih gösterdiğini. trkit bu bilgiyi asistanınıza üç yolla verir.

### 1. Proje kuralları (`AGENTS.md`)

create-trkit-app her projeye bir `AGENTS.md` dosyası koyar. Codex, Cursor, GitHub Copilot, Windsurf, Zed ve diğer birçok araç bu dosyayı otomatik okur. Claude Code `CLAUDE.md` dosyasını okur; trkit'in `CLAUDE.md` dosyası `@AGENTS.md` satırıyla aynı kuralları içe aktarır.

Kurallar kısaca:

- Arayüz metinleri Türkçe; harf dönüşümünde `tr-TR` yereli
- Para kuruş cinsinden tamsayı, gösterim `tl()`
- Tarihler `tarih()` / `tarihSaat()` ile, Europe/Istanbul saat diliminde
- zod `@/lib/zod`'dan; hazır şemalar `@trkit-app-pack/validate`'ten
- Yasal metinler elle yazılmaz, `trkit.config.ts`'den üretilir
- Ödeme sonucu yalnızca callback'te `verifyCallback()` ile belirlenir; sırlar `server-only`

`AGENTS.md`'yi kendi projenize göre genişletin: veritabanı, kimlik doğrulama, kod stili gibi kararlarınızı ekleyin.

### 2. MCP sunucusu (`@trkit-app-pack/mcp`)

MCP (Model Context Protocol), asistanınıza araç kazandırır. trkit MCP sunucusuyla asistanınız:

- Eklenebilecek bileşenleri listeler ve dosyalarını getirir
- Şirket bilgilerinden yasal metin üretir
- TCKN, VKN, IBAN, telefon, plaka doğrular
- İl/ilçe arar
- Ödeme, KVKK, çerez, SMS konularındaki güvenlik rehberlerini okur

İki şekilde çalışır:

| | Komut / adres | Kimler için |
|---|---|---|
| Yerel (stdio) | `npx -y @trkit-app-pack/mcp` | Claude Code, Cursor, VS Code, Codex, Windsurf |
| Uzak (HTTP) | `https://<sunucunuz>/mcp` | ChatGPT, claude.ai ve uzak MCP destekleyen istemciler |

Uzak sunucu bir Node.js sunucusu gerektirir; [nasıl yayınlanacağı](/docs/ai/mcp#uzak-sunucuyu-yayinlamak) MCP sayfasında anlatılıyor. Araçların ayrıntısı: [MCP araçları](/docs/ai/mcp).

### 3. AI için dokümantasyon

| Adres | İçerik |
|---|---|
| [`/llms.txt`](/llms.txt) | Sayfa dizini ([llmstxt.org](https://llmstxt.org) biçiminde) |
| [`/llms-full.txt`](/llms-full.txt) | Tüm dokümantasyon tek Markdown dosyasında |
| `/docs/<sayfa>.md` | Her sayfanın ham Markdown hâli (örnek: [/docs/kurulum.md](/docs/kurulum.md)) |

Her dokümantasyon sayfasının üstündeki **Markdown olarak kopyala**, **ChatGPT'de aç** ve **Claude'da aç** düğmeleriyle sayfayı asistanınıza tek tıkla verebilirsiniz.

### Aracınızı seçin

- [Claude Code](/docs/ai/claude-code)
- [Cursor](/docs/ai/cursor)
- [ChatGPT](/docs/ai/chatgpt)
- [Codex](/docs/ai/codex)
- [VS Code, Windsurf ve diğerleri](/docs/ai/diger)

### Örnek istekler

Bu istekleri trkit projesinde asistanınıza doğrudan verebilirsiniz:

```text
Bu siteye iyzico ile ödeme ekle. Sepet sayfasından ödeme formuna geçilsin,
callback'te siparişi güncelle. Önce trkit_guide ile odeme rehberini oku.
```

```text
Kayıt formuna TCKN, cep telefonu ve il/ilçe alanları ekle. Doğrulama
sunucuda da yapılsın, telefon veritabanına E.164 biçiminde yazılsın.
```

```text
Google Analytics ekle ama yalnızca kullanıcı analitik çerezlere onay verirse yüklensin.
KVKK aydınlatma metnine yurt dışı aktarımı ekle.
```

```text
Sipariş özet sayfasında toplamı TL olarak göster, altına tutarı yazıyla yaz
("Yalnız ... Türk lirası"), sipariş tarihini İstanbul saatiyle göster.
```

> AI'ın ürettiği yasal metin değişikliklerini ve ödeme kodunu her zaman kendiniz gözden geçirin.

---

# Claude Code

URL: https://zersjs.github.io/trkit/docs/ai/claude-code.md

> trkit projelerinde Claude Code kullanımı; CLAUDE.md, MCP sunucusu ve örnek iş akışları.

create-trkit-app ile oluşturulan projeler Claude Code için hazırdır; ek ayar gerekmez.

### Hazır gelenler

**`CLAUDE.md`**: Claude Code her oturumda bu dosyayı okur. trkit'in `CLAUDE.md` dosyası `@AGENTS.md` satırıyla proje kurallarını içe aktarır. Claude'a özel talimatlarınızı bu dosyaya, tüm araçlarda geçerli olanları `AGENTS.md`'ye yazın.

**`.mcp.json`**: trkit MCP sunucusu proje kapsamında tanımlıdır:

```json title=".mcp.json"
{
  "mcpServers": {
    "trkit": { "command": "npx", "args": ["-y", "@trkit-app-pack/mcp"] }
  }
}
```

Projeyi Claude Code'da ilk açtığınızda bu sunucuyu onaylamanız istenir. Bağlı sunucuları `/mcp` komutuyla görebilirsiniz.

### Başlarken

```bash
cd benim-sitem
claude
```

İlk istek olarak şirket bilgilerini doldurtabilirsiniz:

```text
trkit.config.ts dosyasını şu bilgilerle doldur: unvan "Örnek Gıda Ltd. Şti.",
MERSİS 0123456789000015, adres "...", telefon "0212 ...", e-posta "info@...".
Site Vercel'de barınıyor. Sonra npx trkit check çalıştır ve kalan uyarıları açıkla.
```

### MCP'yi elle eklemek

trkit dışında oluşturulmuş bir projede:

```bash
## Yalnızca bu proje için, ekip arkadaşlarıyla paylaşılır (.mcp.json'a yazar)
claude mcp add --scope project trkit -- npx -y @trkit-app-pack/mcp

## Tüm projeleriniz için
claude mcp add --scope user trkit -- npx -y @trkit-app-pack/mcp

## Kendi yayınladığınız uzak sunucu
claude mcp add --transport http trkit https://<sunucunuz>/mcp
```

### Önerilen iş akışı

1. **Planla:** Büyük işlerde önce plan isteyin: "iyzico entegrasyonu için plan çıkar, trkit_guide odeme rehberine uy."
2. **Bileşeni ekle:** Claude `npx trkit add odeme` komutunu çalıştırır veya `trkit_get_files` aracıyla dosyaları alır.
3. **Doğrula:** "npm run build çalıştır ve hataları düzelt." `AGENTS.md` bunu zaten ister.
4. **Gözden geçir:** Ödeme ve yasal metin değişikliklerini kendiniz kontrol edin.

### İpuçları

- Uzun oturumlarda Claude'a "AGENTS.md'deki trkit kurallarını hatırla" demek bağlamı tazeler.
- Yeni bir trkit sürümüne geçtiğinizde Claude'a "trkit_list ile yeni bileşenleri kontrol et" diyebilirsiniz.
- Tekrarlayan işler için `.claude/commands/` altında kendi slash komutlarınızı yazabilirsiniz, örneğin yeni bir yasal sayfa ekleyip footer'a bağlayan bir komut.

---

# Cursor

URL: https://zersjs.github.io/trkit/docs/ai/cursor.md

> trkit projelerinde Cursor kuralları, MCP ayarı ve dokümantasyon indeksleme.

### Hazır gelenler

**`.cursor/rules/trkit.mdc`**: `alwaysApply: true` ile her istekte uygulanan proje kuralları. Ayrıntılı kurallar için `AGENTS.md`'ye yönlendirir; Cursor `AGENTS.md`'yi de okur.

**`.cursor/mcp.json`**: trkit MCP sunucusu:

```json title=".cursor/mcp.json"
{
  "mcpServers": {
    "trkit": { "command": "npx", "args": ["-y", "@trkit-app-pack/mcp"] }
  }
}
```

Cursor Ayarlar → MCP bölümünde sunucunun etkin olduğunu kontrol edin. Agent modunda araçlar otomatik kullanılır.

### Dokümantasyonu indeksletmek

Cursor'ın dokümantasyon özelliğiyle trkit'i `@trkit` olarak çağırabilirsiniz:

1. Cursor Ayarlar → Indexing & Docs → **Add Doc**
2. Adres: `https://zersjs.github.io/trkit/docs`
3. Sohbette `@trkit` yazarak dokümantasyona başvurun

Alternatif olarak sohbete `@https://zersjs.github.io/trkit/llms-full.txt` ekleyebilirsiniz.

### Kendi kurallarınız

Dosya türüne özel kurallar için `globs` kullanın:

```md title=".cursor/rules/formlar.mdc"
---
description: Form bileşenleri
globs: src/app/**/form.tsx
alwaysApply: false
---

- Formlar useActionState + server action ile yazılır (örnek: src/app/iletisim).
- Kişisel veri toplanan her formda /kvkk bağlantısı bulunur.
```

> Cursor arayüzündeki menü adları sürümden sürüme değişebilir.

---

# ChatGPT

URL: https://zersjs.github.io/trkit/docs/ai/chatgpt.md

> ChatGPT'yi trkit uzak MCP sunucusuna bağlayın veya dokümantasyonu Proje dosyası olarak ekleyin.

ChatGPT dosyalarınızı doğrudan düzenlemez ama kod yazdırmak, plan çıkarmak ve yasal metin hazırlatmak için çok kullanılır. trkit bilgisini ChatGPT'ye vermenin üç yolu var.

### 1. Uzak MCP bağlayıcısı (önerilen)

ChatGPT uzak MCP sunucularını bağlayıcı (connector) olarak ekleyebilir. Bunun için trkit MCP sunucusunun internetten erişilebilir bir adreste çalışması gerekir; [uzak sunucuyu yayınlamak](/docs/ai/mcp#uzak-sunucuyu-yayinlamak) birkaç dakika sürer. Sunucu kimlik doğrulama gerektirmez ve yalnızca okuma yapar.

1. ChatGPT → **Ayarlar → Uygulamalar ve Bağlayıcılar**
2. Gelişmiş ayarlardan **Geliştirici modu**nu açın
3. **Oluştur** ile yeni bağlayıcı ekleyin:
   - Ad: `trkit`
   - MCP sunucu adresi: `https://<sunucunuz>/mcp`
   - Kimlik doğrulama: Yok
4. Sohbette bağlayıcıyı seçin ve sorun: "trkit ile Next.js projeme iyzico ödeme nasıl eklerim?"

ChatGPT bu durumda `trkit_guide`, `trkit_get_files`, `trkit_generate_legal` gibi araçları kullanarak gerçek dosya içerikleriyle yanıt verir.

> Bağlayıcı ve geliştirici modu özellikleri ChatGPT planınıza ve bölgenize göre farklılık gösterebilir, menü adları değişebilir.

### 2. Proje dosyası olarak dokümantasyon (sunucu gerektirmez)

ChatGPT Projeleri kullanıyorsanız:

1. [llms-full.txt](/llms-full.txt) dosyasını indirin.
2. Yeni bir Proje oluşturun ve dosyayı **Proje dosyaları**na ekleyin.
3. Proje talimatlarına şunu yapıştırın:

```text
Next.js App Router + TypeScript + Tailwind v4 + trkit kullanan bir Türk web projesi
geliştiriyorum. Proje dosyalarındaki trkit dokümantasyonuna uy. Özellikle:
- Arayüz metinleri Türkçe; harf dönüşümünde toLocaleUpperCase("tr-TR")
- Para kuruş cinsinden tamsayı, gösterim tl() (@trkit-app-pack/format)
- Tarihler tarih()/tarihSaat() ile (Europe/Istanbul)
- zod "@/lib/zod"'dan; TCKN/IBAN/telefon için @trkit-app-pack/validate şemaları
- Yasal metinleri elle yazma; trkit.config.ts'yi güncelle
- Ödeme sonucunu yalnızca /api/odeme/callback içinde pay.verifyCallback() ile belirle
- Sırlar yalnızca sunucuda (server-only)
Kod verirken dosya yolunu belirt ve tam dosya içeriği ver.
```

### 3. Tek sayfa için

Her dokümantasyon sayfasının üstündeki **ChatGPT'de aç** düğmesi, sayfanın Markdown adresini içeren bir sohbet başlatır. **Markdown olarak kopyala** ile sayfa içeriğini doğrudan yapıştırabilirsiniz.

### Codex (ChatGPT içinde)

ChatGPT'deki Codex, deponuzda çalışan bir ajandır ve `AGENTS.md` dosyasını otomatik okur. Ayrıntılar: [Codex](/docs/ai/codex).

---

# Codex

URL: https://zersjs.github.io/trkit/docs/ai/codex.md

> OpenAI Codex (CLI, IDE eklentisi ve bulut) ile trkit projeleri.

Codex, depodaki `AGENTS.md` dosyasını otomatik okur. create-trkit-app ile oluşturulan projelerde ek ayar olmadan trkit kurallarına uyar.

### MCP sunucusu

Codex MCP ayarları kullanıcı düzeyindedir (`~/.codex/config.toml`):

```bash
codex mcp add trkit -- npx -y @trkit-app-pack/mcp
```

veya dosyayı elle düzenleyin:

```toml title="~/.codex/config.toml"
[mcp_servers.trkit]
command = "npx"
args = ["-y", "@trkit-app-pack/mcp"]
```

### Bulutta Codex

ChatGPT'deki Codex'e depoyu bağladığınızda `AGENTS.md` otomatik okunur. Ortam ayarlarında kurulum komutu olarak paket yöneticinizin `install` komutunu verin; Codex'in değişiklikten sonra derlemeyi doğrulayabilmesi için `AGENTS.md`'deki komutlar (`npm run build`) çalışır durumda olmalı.

### İpucu

`AGENTS.md`, iç içe dizinlerde de kullanılabilir. Örneğin `src/app/api/AGENTS.md` dosyasına yalnızca API route'larına özel kurallar yazabilirsiniz; en yakın dosya önceliklidir.

---

# VS Code, Windsurf ve diğerleri

URL: https://zersjs.github.io/trkit/docs/ai/diger.md

> GitHub Copilot, Windsurf, Gemini CLI, Zed ve claude.ai için trkit ayarları.

Bu sayfadaki ayar dosyası konumları araçların kendi dokümantasyonuna dayanır ve zamanla değişebilir. Değişiklik fark ederseniz ilgili aracın güncel dokümantasyonunu esas alın.

### VS Code + GitHub Copilot

**MCP:** create-trkit-app projelerinde `.vscode/mcp.json` hazırdır:

```json title=".vscode/mcp.json"
{
  "servers": {
    "trkit": { "command": "npx", "args": ["-y", "@trkit-app-pack/mcp"] }
  }
}
```

Copilot Chat'i **Agent** modunda kullanın; araçlar listesinde trkit görünür.

**Kurallar:** Copilot `AGENTS.md` dosyasını okuyabilir. Ayrıca `.github/copilot-instructions.md` kullanıyorsanız içine şunu yazmanız yeterli:

```md title=".github/copilot-instructions.md"
Bu projenin kuralları kök dizindeki AGENTS.md dosyasındadır. Her değişiklikte uygula.
```

### Windsurf

**MCP:** `~/.codeium/windsurf/mcp_config.json`:

```json
{
  "mcpServers": {
    "trkit": { "command": "npx", "args": ["-y", "@trkit-app-pack/mcp"] }
  }
}
```

**Kurallar:** Windsurf `AGENTS.md`'yi okur. Ek kurallar için `.windsurf/rules/` dizinini kullanabilirsiniz.

### Gemini CLI

**MCP:** `~/.gemini/settings.json` veya projede `.gemini/settings.json`:

```json
{
  "mcpServers": {
    "trkit": { "command": "npx", "args": ["-y", "@trkit-app-pack/mcp"] }
  }
}
```

**Kurallar:** Gemini CLI varsayılan olarak `GEMINI.md` okur. `AGENTS.md`'yi okuması için aynı ayar dosyasına ekleyin:

```json
{ "contextFileName": ["AGENTS.md", "GEMINI.md"] }
```

### Zed

Zed `AGENTS.md`'yi okur. MCP sunucusunu ayarlarda `context_servers` altına ekleyin.

### claude.ai (web ve masaüstü)

Ayarlar → **Bağlayıcılar** → **Özel bağlayıcı ekle** → adres `https://<sunucunuz>/mcp` ([uzak sunucuyu yayınlamak](/docs/ai/mcp#uzak-sunucuyu-yayinlamak)). Ardından sohbette trkit araçlarını kullanabilirsiniz. Claude Projeleri'nde [llms-full.txt](/llms-full.txt) dosyasını proje bilgisi olarak da ekleyebilirsiniz.

### Herhangi bir sohbet asistanı

MCP desteklemeyen araçlarda [llms-full.txt](/llms-full.txt) içeriğini bağlam olarak verin veya ilgili sayfayı **Markdown olarak kopyala** ile yapıştırın.

---

# MCP araçları

URL: https://zersjs.github.io/trkit/docs/ai/mcp.md

> @trkit-app-pack/mcp sunucusunun araçları, girdileri ve kendi sunucunuzda barındırma.

### Kurulum

| Biçim | Yapılandırma |
|---|---|
| Yerel (stdio) | `npx -y @trkit-app-pack/mcp` |
| Uzak (Streamable HTTP) | `https://<sunucunuz>/mcp` (aşağıya bakın) |

Tüm araçlar **salt okunurdur**: dosya yazmaz, ağa istek atmaz, kimlik bilgisi istemez. Dosyaları yazmak asistanınızın işidir.

### Araçlar

#### `trkit_list`

Eklenebilecek bileşen/sayfa/uç noktaları, yasal metin şablonlarını ve rehber başlıklarını listeler. Asistanınız bir trkit işine başlamadan önce bunu çağırır.

#### `trkit_get_files`

Registry öğelerinin bağımlılıklarıyla birlikte kaynak kodunu ve projedeki hedef yollarını döndürür.

| Girdi | Tür | Açıklama |
|---|---|---|
| `items` | `string[]` | Örn. `["kvkk", "cerez-banner"]` |
| `srcDir` | `boolean?` | Proje `src/` dizini kullanıyorsa `true` |
| `importAlias` | `string?` | Varsayılan `"@/"` |

Çıktıda `files` (yol + içerik), `dependencies`, `env`, `notes` ve eşdeğer CLI komutu (`cli`) bulunur. Terminal erişimi olan asistanlar genelde doğrudan `npx trkit add` çalıştırır.

#### `trkit_generate_legal`

Şirket bilgilerinden yasal metin üretir.

| Girdi | Tür |
|---|---|
| `template` | `kvkk-aydinlatma`, `acik-riza`, `cerez-politikasi`, `mesafeli-satis`, `on-bilgilendirme`, `teslimat-iade`, `ticari-ileti`, `kvkk-basvuru` |
| `company` | `{ unvan, adres, eposta, website, mersis?, telefon?, kvkkEposta?, ... }` |
| `options` | `trkit.config.ts`'deki diğer alanlar (`kvkk`, `satis`, `cerezler`...) |
| `format` | `markdown` (varsayılan) veya `html` |

Çıktıda `content`, eksik bilgileri gösteren `warnings` ve hukuki uyarı (`disclaimer`) bulunur.

#### `trkit_validate`

`kind`: `tckn`, `vkn`, `vergi-no`, `iban`, `telefon`, `plaka`, `posta-kodu`. Geçerliliği ve normalize edilmiş değeri döndürür (IBAN için banka kodu ve adı, telefon için tür ve E.164).

#### `trkit_address_search`

Türkçe karakter duyarsız il/ilçe araması. `query` ve isteğe bağlı `province`.

#### `trkit_guide`

Konular: `baslangic`, `kvkk`, `cerez`, `odeme`, `sms`, `dogrulama`. Ödeme, KVKK veya çerez kodu yazmadan önce asistanın okuması gereken kısa ve kesin kurallar. Aynı rehberler `trkit://guide/<konu>` kaynakları (resources) olarak da sunulur.

### Uzak sunucuyu yayınlamak

Yerel (stdio) sunucu, Claude Code, Cursor, VS Code ve Codex için yeterlidir. ChatGPT ve claude.ai gibi web istemcileri ise internetten erişilebilen bir adres ister. Bu dokümantasyon sitesi GitHub Pages'te statik olarak yayınlandığı için `/mcp` uç noktası burada **çalışmaz**; uzak sunucuyu Node.js çalıştırabilen bir yerde yayınlamanız gerekir.

**Seçenek 1: trkit dokümantasyon sitesini sunucu modunda yayınlayın.** Depodaki `apps/docs` uygulaması varsayılan modda `/mcp` uç noktasını içerir. Vercel'de kök dizin olarak `apps/docs` seçip yayınlamanız yeterli; adres `https://<projeniz>.vercel.app/mcp` olur.

**Seçenek 2: Kendi Next.js projenize ekleyin.** `@trkit-app-pack/mcp` paketindeki `createServer()` fonksiyonuyla herhangi bir taşıyıcıya bağlanabilirsiniz. Next.js route handler örneği:

```ts title="app/mcp/route.ts"
import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
import { createServer } from "@trkit-app-pack/mcp";

export async function POST(req: Request) {
  const server = createServer();
  const transport = new WebStandardStreamableHTTPServerTransport({
    sessionIdGenerator: undefined, // durumsuz
    enableJsonResponse: true,
  });
  await server.connect(transport);
  return transport.handleRequest(req);
}
```

---

# KVKK uyumu

URL: https://zersjs.github.io/trkit/docs/rehber/kvkk.md

> Bir web sitesinde 6698 sayılı Kanun'a uyum için trkit ile yapılacaklar.

> Bu sayfa teknik bir rehberdir, hukuki görüş değildir. Kesin değerlendirme için bir avukata danışın.

### Temel kavramlar

**Aydınlatma yükümlülüğü (md. 10):** Kişisel veri topladığınız herkese; kim olduğunuzu, veriyi hangi amaçla ve hukuki sebeple işlediğinizi, kimlere aktardığınızı ve haklarını bildirmeniz gerekir. Bu bir **bilgilendirmedir, onay değildir**. Aydınlatma metni için "okudum, onaylıyorum" kutusu koymak yaygın bir hatadır.

**Açık rıza (md. 5/1):** Yalnızca Kanun'daki diğer hukuki sebeplerden (sözleşme, yasal yükümlülük, meşru menfaat…) hiçbiri yoksa alınır. Örneğin sipariş teslimatı için adres işlemek sözleşmenin ifasıdır, açık rıza gerekmez. Pazarlama amaçlı profil çıkarma için açık rıza gerekir. Açık rıza:

- Belirli bir konuya ilişkin, bilgilendirmeye dayalı ve özgür iradeyle verilmelidir
- Aydınlatma metninden ayrı sunulmalıdır
- Hizmet şartına bağlanamaz ("onay vermezseniz üye olamazsınız" olmaz)
- Önceden işaretli kutuyla alınamaz
- Her zaman geri alınabilmelidir

**Yurt dışı aktarım (md. 9):** 1 Haziran 2024'ten itibaren yurt dışı aktarım; yeterlilik kararı, standart sözleşme, bağlayıcı şirket kuralları gibi uygun güvencelerle yapılır. Açık rıza yalnızca arızi (düzenli olmayan) aktarımlarda kullanılabilir. **Vercel, AWS, Google Analytics, Meta Pixel, Cloudflare gibi servisler yurt dışı aktarımdır.** Standart sözleşme imzalandıktan sonra 5 iş günü içinde Kurum'a bildirilmelidir.

### trkit ile adımlar

#### 1. Şirket bilgileri ve veri envanteri

```ts title="src/trkit.config.ts"
import { defineConfig } from "@trkit-app-pack/legal";

export default defineConfig({
  company: {
    unvan: "Örnek Gıda Ltd. Şti.",
    marka: "Örnek",
    mersis: "0123456789000015",
    adres: "Atatürk Cad. No:1 Kadıköy/İstanbul",
    telefon: "0216 000 00 00",
    eposta: "info@ornek.com.tr",
    kvkkEposta: "kvkk@ornek.com.tr",
    website: "https://ornek.com.tr",
  },
  kvkk: {
    veriKategorileri: ["kimlik", "iletisim", "musteri-islem", "finans", "islem-guvenligi", "pazarlama", "hukuki-islem"],
    yurtDisiAktarim: { hizmetler: ["Vercel", "Google Analytics"], dayanak: "standart-sozlesme" },
    verbisNo: "", // VERBİS kayıt yükümlülüğünüz varsa
  },
  pay: { provider: "iyzico" },  // aktarım listesine otomatik eklenir
  sms: { provider: "netgsm" },
});
```

Veri kategorileri ve her birinin amaç ve hukuki sebepleri [@trkit-app-pack/legal](/docs/paketler/legal#veri-kategorileri) sayfasında listelenmiştir.

#### 2. Sayfalar

```bash
npx trkit add kvkk acik-riza kvkk-basvuru cerez-politikasi
npx trkit check
```

#### 3. Formlarda bilgilendirme

Kişisel veri toplanan her formun yanında aydınlatma metnine bağlantı verin; kutu koymayın:

```tsx
<p className="text-xs text-muted-foreground">
  Kişisel verileriniz <Link href="/kvkk">Aydınlatma Metni</Link> kapsamında işlenmektedir.
</p>
```

#### 4. Açık rıza gerekiyorsa ayrı kutu

```tsx
<label>
  <input type="checkbox" name="pazarlamaRiza" /> {/* defaultChecked YOK */}
  Alışveriş tercihlerime göre kişiselleştirilmiş kampanyalar sunulması için verilerimin işlenmesine{" "}
  <Link href="/acik-riza">Açık Rıza Metni</Link> kapsamında onay veriyorum. (İsteğe bağlı)
</label>
```

#### 5. Onayları kaydedin

Açık rızanın varlığını ispat yükü sizdedir. Kayıtları ekleme-tabanlı (silinmeyen, güncellenmeyen) bir tabloda tutun:

```ts
import { createConsentRecord, generate, documentHash } from "@trkit-app-pack/legal";
import config from "@/trkit.config";

const { document } = generate("acik-riza", config);
const record = await createConsentRecord({
  subjectId: user.id,
  purpose: "kvkk:acik-riza",
  granted: true,
  document: `acik-riza@${document.templateVersion}`,
  documentHash: await documentHash(document), // kullanıcının gördüğü metnin özeti
  source: "kayit-formu",
  ip, salt: process.env.CONSENT_SALT!,        // ham IP saklanmaz
});
await db.insert(consents).values(record);
```

#### 6. Çerezler

Ayrıntılar: [Çerez onayı](/docs/rehber/cerez).

### Sık yapılan hatalar

- Aydınlatma metnini onay kutusuna bağlamak
- Sözleşme gereği işlenen veri için açık rıza istemek (rıza geri alınınca hizmeti veremezsiniz)
- Yurt dışı servisleri aydınlatma metninde belirtmemek
- Tüm onayları tek bir kutuda toplamak ("KVKK, ticari ileti ve sözleşmeyi onaylıyorum")
- Onay kayıtlarını tutmamak veya üzerine yazmak

---

# Çerez onayı

URL: https://zersjs.github.io/trkit/docs/rehber/cerez.md

> KVKK Çerez Uygulamaları Rehberi'ne uygun çerez banner'ı, script yükleme ve onay kaydı.

### Kurallar (özet)

KVKK'nın Çerez Uygulamaları Hakkında Rehberi'ne göre:

- **Zorunlu çerezler** (oturum, sepet, güvenlik, tercih kaydı) için açık rıza gerekmez.
- **Analitik, pazarlama ve çoğu fonksiyonel çerez** için açık rıza gerekir ve bu çerezler **onaydan önce yerleştirilemez**.
- "Reddet" seçeneği "Kabul et" kadar kolay erişilebilir olmalıdır.
- Kutular önceden işaretli olamaz.
- Kullanıcı tercihini her zaman değiştirebilmelidir.

### Kurulum

```bash
npx trkit add cerez-banner cerez-politikasi
```

```tsx title="app/layout.tsx"
import { CookieConsentProvider } from "@/components/trkit/cerez-banner";

<body>
  <CookieConsentProvider policyHref="/cerez-politikasi">{children}</CookieConsentProvider>
</body>
```

Footer'a tercih bağlantısı ekleyin:

```tsx
import { CookiePreferencesLink } from "@/components/trkit/cerez-banner";

<CookiePreferencesLink />
```

### Script'leri onaya bağlamak

```tsx title="app/layout.tsx"
import Script from "next/script";
import { ConsentGate } from "@/components/trkit/cerez-banner";

<CookieConsentProvider>
  {children}
  <ConsentGate category="analitik">
    <Script src="https://www.googletagmanager.com/gtag/js?id=G-XXXX" strategy="afterInteractive" />
    <Script id="ga" strategy="afterInteractive">
      {`window.dataLayer=window.dataLayer||[];function gtag(){dataLayer.push(arguments)}gtag('js',new Date());gtag('config','G-XXXX');`}
    </Script>
  </ConsentGate>
  <ConsentGate category="pazarlama">
    {/* Meta Pixel, TikTok Pixel... */}
  </ConsentGate>
</CookieConsentProvider>
```

Bir bileşen içinde:

```tsx
"use client";
import { useCookieConsent } from "@/components/trkit/cerez-banner";

const { allowed } = useCookieConsent();
if (allowed("analitik")) { /* ... */ }
```

Sunucu tarafında (ör. middleware/proxy veya server component):

```ts
import { cookies } from "next/headers";
import { parseCookieConsent, isAllowed, COOKIE_CONSENT_NAME } from "@trkit-app-pack/legal";

const state = parseCookieConsent((await cookies()).get(COOKIE_CONSENT_NAME)?.value, "1");
isAllowed(state, "pazarlama"); // false
```

### Çerez listesini güncel tutun

Kullandığınız her çerezi `trkit.config.ts`'e ekleyin; çerez politikası sayfası bu listeden üretilir:

```ts
cerezler: [
  { ad: "trkit_consent", saglayici: "Birinci taraf", amac: "Çerez tercihlerinin saklanması", sure: "6 ay", kategori: "zorunlu" },
  { ad: "_ga, _ga_*", saglayici: "Google", amac: "Ziyaret istatistikleri", sure: "2 yıl", kategori: "analitik" },
  { ad: "_fbp", saglayici: "Meta", amac: "Reklam ölçümü", sure: "3 ay", kategori: "pazarlama" },
],
```

Üçüncü taraf çerezler genellikle yurt dışı aktarım içerir; `trkit check` bunu hatırlatır.

### Politika değişince

`cerez-banner.tsx` içindeki `CONSENT_VERSION` değerini artırın. Eski sürümle onay vermiş kullanıcılara banner yeniden gösterilir.

### Onay kayıtları

Banner her seçimde `/api/consent` uç noktasına kayıt gönderir. `app/api/consent/route.ts` içindeki `kaydet()` fonksiyonunu veritabanınıza bağlayın. IP adresi `CONSENT_SALT` ile tuzlanarak özetlenir, ham hâliyle saklanmaz.

---

# Türkçe formlar

URL: https://zersjs.github.io/trkit/docs/rehber/form.md

> Türkçe hata mesajları, TCKN/IBAN/telefon doğrulama ve il/ilçe seçimiyle form yazma.

create-trkit-app projelerindeki `src/app/iletisim/` dizini çalışan bir örnektir. Bu sayfa o örneği adım adım açıklar.

### 1. Şema

```ts title="src/app/iletisim/schema.ts"
import { cepTelefonu } from "@trkit-app-pack/validate";
import { isValidDistrict } from "@trkit-app-pack/address";
import { basHarfleriBuyut } from "@trkit-app-pack/format";
import { z } from "@/lib/zod"; // Türkçe hata mesajları

export const iletisimSchema = z
  .object({
    adSoyad: z.string().trim().min(3).max(80).transform(basHarfleriBuyut),
    eposta: z.email(),
    telefon: cepTelefonu,                       // "0532 123 45 67" → "+905321234567"
    il: z.coerce.number().int().min(1, "İl seçiniz").max(81),
    ilce: z.string({ message: "İlçe seçiniz" }).min(1, "İlçe seçiniz"),
    mesaj: z.string().trim().min(10).max(2000),
    ticariIleti: z.boolean().default(false),
  })
  .refine((v) => isValidDistrict(v.il, v.ilce), { path: ["ilce"], message: "Seçilen ilçe bu ile ait değil" });
```

Hazır mesajlar: "En az 3 karakter olmalıdır", "Geçerli bir e-posta adresi giriniz", "Bu alan zorunludur", "Geçerli bir cep telefonu giriniz (5XX XXX XX XX)".

### 2. Server action

```ts title="src/app/iletisim/actions.ts"
"use server";
import { iletisimSchema } from "./schema";

export async function iletisimGonder(_prev: FormState, formData: FormData): Promise<FormState> {
  const values = Object.fromEntries(formData) as Record<string, string>;
  const parsed = iletisimSchema.safeParse({ ...values, ticariIleti: values.ticariIleti === "on" });
  if (!parsed.success) {
    const errors: Record<string, string> = {};
    for (const i of parsed.error.issues) errors[String(i.path[0])] ??= i.message;
    return { status: "error", errors, values };
  }
  // parsed.data.telefon E.164 biçiminde, adSoyad düzgün büyük harfli
  return { status: "success", adSoyad: parsed.data.adSoyad };
}
```

### 3. Form

```tsx
const [state, action, pending] = useActionState(iletisimGonder, { status: "idle" });
const [konum, setKonum] = useState<IlIlceDegeri>({ il: null, ilce: null });

<form action={action}>
  <input name="telefon" type="tel" inputMode="tel" autoComplete="tel-national" placeholder="05XX XXX XX XX" />
  <IlIlceSecici value={konum} onChange={setKonum} name={{ il: "il", ilce: "ilce" }} error={{ il: err.il, ilce: err.ilce }} />
</form>
```

### Hazır şemalar

| Şema | Kabul eder | Dönüştürür |
|---|---|---|
| `tckn` | 11 hane, algoritma kontrolü | boşlukları temizler |
| `vkn` | 10 hane, algoritma kontrolü | |
| `vergiNo` | TCKN veya VKN (fatura formları) | |
| `iban` | TR IBAN, mod-97 | `TR33 0006 …` → `TR330006…` |
| `telefon` | mobil, sabit, 850 | E.164 `+90…` |
| `cepTelefonu` | yalnızca 5XX | E.164 |
| `plaka` | `34 ABC 123` vb. | `34ABC123` |
| `postaKodu` | 5 hane, il kodu 01–81 | |
| `mersis` | 16 hane | |

Özel mesaj için şema fabrikalarını kullanın: `tcknSchema({ message: "TC kimlik numaranızı kontrol edin" })`, `phoneSchema({ mobileOnly: true })`.

### İpuçları

- Telefon alanında `inputMode="tel"` mobilde rakam klavyesini açar.
- TCKN algoritma kontrolü numaranın gerçek bir kişiye ait olduğunu göstermez. Kimlik doğrulaması gerekiyorsa NVİ KPS servisi gerekir.
- Loglarda `maskTckn()` ve `maskPhone()` kullanın.

---

# Ödeme akışı

URL: https://zersjs.github.io/trkit/docs/rehber/odeme.md

> iyzico veya PayTR ile güvenli ödeme; sepet, onaylar, callback ve iade.

### Kurulum

```bash
npx trkit add odeme odeme-onaylari
```

```bash title=".env.local"
TRKIT_PAY_PROVIDER=iyzico      # iyzico | paytr | mock
IYZICO_API_KEY=sandbox-...
IYZICO_SECRET_KEY=sandbox-...
IYZICO_SANDBOX=1
```

Geliştirmede `TRKIT_PAY_PROVIDER=mock` ile gerçek sağlayıcı olmadan tüm akışı deneyebilirsiniz.

### Akış

```text
Sepet → Ödeme sayfası (onaylar) → createCheckout() → Sağlayıcı formu
     → Sağlayıcı /api/odeme/callback'e bildirir → verifyCallback() → sipariş güncellenir
     → Kullanıcı sonuç sayfasına yönlendirilir
```

### 1. Ödeme sayfası ve onaylar

Mesafeli Sözleşmeler Yönetmeliği'ne göre ön bilgilendirme formu, sipariş onayından **önce** ve sipariş bilgileriyle gösterilmeli:

```tsx title="app/odeme/page.tsx"
import { generate, toHtml } from "@trkit-app-pack/legal";
import config from "@/trkit.config";
import { OdemeOnaylari } from "@/components/trkit/odeme-onaylari";

export default async function OdemeSayfasi() {
  const sepet = await sepetiGetir();
  const order = {
    no: sepet.id, tarih: new Date().toISOString(), odemeYontemi: "Kredi kartı",
    alici: { adSoyad: sepet.adSoyad, adres: sepet.adres, telefon: sepet.telefon, eposta: sepet.eposta },
    urunler: sepet.kalemler.map((k) => ({ ad: k.ad, adet: k.adet, birimFiyat: k.fiyatKurus })),
    kargoUcreti: sepet.kargoKurus,
  };
  return (
    <form action={odemeyiBaslat}>
      <OdemeOnaylari
        onBilgilendirmeHtml={toHtml(generate("on-bilgilendirme", config, { order }).document)}
        mesafeliSatisHtml={toHtml(generate("mesafeli-satis", config, { order }).document)}
      />
      <button>Ödemeye geç</button>
    </form>
  );
}
```

### 2. Ödemeyi başlatma (sunucu)

```ts title="app/odeme/actions.ts"
"use server";
import { headers } from "next/headers";
import { redirect } from "next/navigation";
import { pay } from "@/lib/pay";

export async function odemeyiBaslat(formData: FormData) {
  if (formData.get("onay[sozlesme]") !== "on") throw new Error("Sözleşme onayı gerekli");
  const sepet = await sepetiGetir();
  const ip = (await headers()).get("x-forwarded-for")?.split(",")[0] ?? "127.0.0.1";

  const session = await pay.createCheckout({
    orderId: sepet.id,                     // PayTR: yalnızca harf ve rakam
    amount: sepet.toplamKurus,             // kalemlerin toplamına eşit olmalı
    buyer: {
      id: sepet.uyeId, name: sepet.ad, surname: sepet.soyad,
      email: sepet.eposta, phone: sepet.telefon, ip,
      address: { city: sepet.il, district: sepet.ilce, line: sepet.adres },
    },
    items: [
      ...sepet.kalemler.map((k) => ({ id: k.id, name: k.ad, category: k.kategori, unitPrice: k.fiyatKurus, quantity: k.adet })),
      { id: "kargo", name: "Kargo", category: "Kargo", unitPrice: sepet.kargoKurus, type: "virtual" as const },
    ],
    callbackUrl: `${process.env.NEXT_PUBLIC_SITE_URL}/api/odeme/callback`,
    successUrl: `${process.env.NEXT_PUBLIC_SITE_URL}/odeme/basarili`,
    failUrl: `${process.env.NEXT_PUBLIC_SITE_URL}/odeme/basarisiz`,
    installments: [1, 2, 3, 6],
  });

  if (session.paymentPageUrl) redirect(session.paymentPageUrl); // iyzico
  redirect(`/odeme/form?token=${session.token}`);               // PayTR: iframeUrl'i <iframe> ile göster
}
```

### 3. Callback

`npx trkit add odeme` ile gelen `app/api/odeme/callback/route.ts` bildirimi doğrular. Yapmanız gereken `siparisiGuncelle()` fonksiyonunu doldurmak:

```ts
async function siparisiGuncelle(result: PaymentResult) {
  const siparis = await db.siparis.find(result.orderId);
  if (!siparis || siparis.durum === "odendi") return;          // idempotent
  if (result.status !== "success") return db.siparis.update(result.orderId, { durum: "basarisiz" });
  if (result.paidAmount! < siparis.toplamKurus) throw new Error("Tutar uyuşmuyor");
  await db.siparis.update(result.orderId, { durum: "odendi", odemeId: result.paymentId });
}
```

### Güvenlik kuralları

- **Başarı sayfasına güvenmeyin.** `/odeme/basarili` adresine herkes gidebilir. Siparişin ödendiğine yalnızca callback karar verir.
- **Sırlar sunucuda.** `lib/pay.ts` `server-only` içerir; client component'ten içe aktarılırsa derleme hata verir.
- **Tutarı sunucuda hesaplayın.** Formdan gelen fiyatı kullanmayın.
- **Kuruş kullanın.** `0.1 + 0.2 !== 0.3`. `toKurus("129,50")` → `12950`.
- **PayTR "OK" bekler.** `callbackResponse()` bunu döndürür; aynı bildirim tekrar gelebilir.
- **iyzico fraud incelemesi.** `fraudStatus` incelemedeyse sonuç `pending` döner; siparişi kargoya vermeyin.

### Sağlayıcı değiştirmek

`.env.local` içinde `TRKIT_PAY_PROVIDER=paytr` ve PayTR anahtarları. PayTR panelinde Bildirim URL'sini `https://alanadiniz/api/odeme/callback` olarak ayarlayın. Kodunuz değişmez.

### İade

```ts
await pay.refund({ paymentId: siparis.odemeId, amount: 5900, ip });
```

---

# SMS ve OTP

URL: https://zersjs.github.io/trkit/docs/rehber/sms-otp.md

> Netgsm ile bilgilendirme/ticari SMS ve güvenli telefon doğrulama.

### Kurulum

```bash
npx trkit add sms
```

```bash title=".env.local"
TRKIT_SMS_PROVIDER=netgsm   # geliştirmede: dev (konsola yazar)
NETGSM_USERCODE=850xxxxxxx
NETGSM_PASSWORD=...
NETGSM_HEADER=MARKANIZ      # onaylı gönderici başlığı
OTP_SECRET=uzun-rastgele-deger
```

### Bilgilendirme ve ticari SMS

```ts
import { sms } from "@/lib/sms";

// Sipariş, kargo, şifre: İYS onayı gerekmez
await sms.send({ to: "0532 123 45 67", text: "Siparişiniz kargoya verildi.", kind: "transactional" });

// Kampanya: alıcının İYS'de onayı olmalı; Netgsm İYS filtresi uygulanır
await sms.send({ to: aliciListesi, text: "Hafta sonu %20 indirim!", kind: "commercial-individual" });
```

`kind` değerine göre Netgsm'e İYS filtresi gönderilir: bilgilendirme `0`, bireysel ticari `11`, tacir ticari `12`.

### Telefon doğrulama (OTP)

```ts title="app/dogrula/actions.ts"
"use server";
import { otp } from "@/lib/sms";

export async function kodGonder(telefon: string) {
  const r = await otp.send(telefon);
  if (!r.sent) return { hata: `${r.retryAfter} saniye sonra tekrar deneyin` };
  return { ok: true };
}

export async function kodDogrula(telefon: string, kod: string) {
  const r = await otp.verify(telefon, kod);
  if (!r.ok) return { hata: { invalid: "Kod hatalı", expired: "Kodun süresi doldu", too_many_attempts: "Çok fazla deneme", invalid_number: "Geçersiz numara" }[r.reason] };
  // telefonu doğrulanmış olarak işaretle
}
```

Güvenlik:

- Kod düz metin saklanmaz (HMAC-SHA256)
- Varsayılan: 6 hane, 3 dakika geçerlilik, 5 deneme, 60 saniye yeniden gönderim beklemesi
- Kod üretiminde modulo yanlılığı olmayan kriptografik rastgelelik

### Serverless ortamda depolama

`memoryOtpStore()` yalnızca tek süreçli geliştirme ortamı içindir. Vercel gibi ortamlarda istekler farklı örneklere gider; paylaşımlı bir depo yazın:

```ts title="lib/otp-store.ts"
import type { OtpStore } from "@trkit-app-pack/sms";
import { redis } from "./redis";

export const redisOtpStore: OtpStore = {
  async get(k) { return (await redis.get(k)) ?? null; },
  async set(k, v, ttl) { await redis.set(k, v, { ex: ttl }); },
  async delete(k) { await redis.del(k); },
};
```

### Netgsm hata kodları

| Kod | Anlamı |
|---|---|
| 20 | Mesaj metni hatalı veya çok uzun |
| 30 | Kullanıcı adı/şifre hatalı veya API erişim izni yok (IP kısıtlamasını kontrol edin) |
| 40 | Gönderici başlığı tanımlı değil |
| 50 / 51 | İYS ayarı veya marka bilgisi eksik |
| 70 | Hatalı parametre |
| 80 / 85 | Gönderim sınırı aşıldı |

---

# Yayına alma kontrol listesi

URL: https://zersjs.github.io/trkit/docs/rehber/yayina-alma.md

> trkit projesini canlıya almadan önce kontrol edilecekler.

### Şirket ve yasal metinler

- [ ] `src/trkit.config.ts` içinde unvan, MERSİS (veya şahıs şirketinde vergi no), adres, telefon, e-posta dolu
- [ ] `npx trkit check` uyarı vermiyor (CI'da `--strict`)
- [ ] Yurt dışı servisler (`kvkk.yurtDisiAktarim`) eksiksiz; standart sözleşme imzalandıysa 5 iş günü içinde Kurum'a bildirildi
- [ ] Çerez listesi (`cerezler`) sitede gerçekten kullanılan çerezlerle aynı
- [ ] VERBİS kayıt yükümlülüğü kontrol edildi
- [ ] Ticari ileti gönderilecekse İYS kaydı yapıldı, `ticariIleti.iysMarkaKodu` dolu
- [ ] Yasal metinler bir avukata kontrol ettirildi
- [ ] Footer'da yasal sayfa bağlantıları ve "Çerez Tercihleri" var (`src/lib/site.ts`)

### Ortam değişkenleri

- [ ] `NEXT_PUBLIC_SITE_URL` canlı adres
- [ ] `CONSENT_SALT`, `OTP_SECRET` uzun ve rastgele (`openssl rand -hex 32`)
- [ ] Ödeme: sandbox anahtarları canlı anahtarlarla değiştirildi, `IYZICO_SANDBOX` / `PAYTR_TEST_MODE` kaldırıldı
- [ ] PayTR Bildirim URL'si panelde canlı adrese ayarlı

### Veritabanı bağlantıları

- [ ] `app/api/consent/route.ts` → `kaydet()` veritabanına yazıyor
- [ ] `app/api/odeme/callback/route.ts` → `siparisiGuncelle()` idempotent ve tutarı kontrol ediyor
- [ ] OTP için paylaşımlı depo (Redis/DB) kullanılıyor

### Test

- [ ] Sandbox'ta başarılı, başarısız ve 3D Secure iptal senaryoları denendi
- [ ] Callback'e sahte istek atıldığında 400 dönüyor
- [ ] Çerez banner'ında "Reddet" sonrası analitik script'leri yüklenmiyor (tarayıcı geliştirici araçları → Ağ)
- [ ] Mobilde il/ilçe seçici ve telefon klavyesi doğru çalışıyor
- [ ] `npm run build` hatasız

---

# @trkit-app-pack/validate

URL: https://zersjs.github.io/trkit/docs/paketler/validate.md

> TCKN, VKN, IBAN, telefon, plaka, posta kodu ve MERSİS doğrulama; hazır zod şemaları ve Türkçe hata mesajları.

```bash
npm install @trkit-app-pack/validate zod
```

zod 4 önerilir; zod 3.25+ da desteklenir. zod kullanmıyorsanız saf fonksiyonları `@trkit-app-pack/validate/core` üzerinden içe aktarın.

### Türkçe zod mesajları

```ts
import { z } from "zod";
import { zodTurkce } from "@trkit-app-pack/validate";

zodTurkce(z); // uygulama başında bir kez

z.string().min(3).parse("a");       // En az 3 karakter olmalıdır
z.email().parse("x");               // Geçerli bir e-posta adresi giriniz
z.number().max(10).parse(11);       // 10 veya daha küçük olmalıdır
z.object({ a: z.string() }).parse({}); // Bu alan zorunludur
```

Şemada verdiğiniz özel mesajlar korunur. Tanınmayan durumlarda zod'un kendi Türkçe yereline düşer.

### zod şemaları

```ts
import { tckn, vkn, vergiNo, iban, telefon, cepTelefonu, plaka, postaKodu, mersis } from "@trkit-app-pack/validate";

const schema = z.object({ tckn, iban, telefon: cepTelefonu });
schema.parse({ tckn: "10000000146", iban: "tr33 0006 1005 1978 6457 8413 26", telefon: "0532 123 45 67" });
// { tckn: "10000000146", iban: "TR330006100519786457841326", telefon: "+905321234567" }
```

Özelleştirilebilir fabrikalar: `tcknSchema(o)`, `vknSchema(o)`, `taxIdSchema(o)`, `ibanSchema(o)`, `phoneSchema({ mobileOnly?, message? })`, `plateSchema(o)`, `postalCodeSchema(o)`, `mersisSchema(o)`.

### TCKN

```ts
isValidTckn("10000000146");   // true
maskTckn("10000000146");      // "100******46"
generateTckn();               // test verisi için geçerli rastgele numara
```

Algoritma: 11 hane, ilk hane 0 olamaz; 10. hane `((1,3,5,7,9. haneler toplamı × 7) − (2,4,6,8. haneler toplamı)) mod 10`; 11. hane ilk 10 hanenin toplamı mod 10.

### VKN ve vergi no

```ts
isValidVkn("1234567890");
detectTaxId("10000000146");   // "tckn"
detectTaxId("<10 hane>");     // "vkn" | null
isValidTaxId(v);              // fatura formlarındaki "TCKN / VKN" alanı
generateVkn();
```

### IBAN

```ts
isValidTrIban("TR33 0006 1005 1978 6457 8413 26"); // true
parseTrIban("TR330006100519786457841326");
// { iban, bankCode: "00061", bankName: null, accountNumber: "0519786457841326" }
formatIban("TR330006100519786457841326"); // "TR33 0006 1005 1978 6457 8413 26"
isValidIbanChecksum("DE89370400440532013000"); // her ülke için mod-97
```

`TR_BANK_CODES` yaygın bankaların EFT kodlarını içerir (Ziraat 00010, Garanti BBVA 00062, İş Bankası 00064…).

### Telefon

```ts
detectPhoneKind("0532 123 45 67");   // "mobile"
detectPhoneKind("0212 555 12 34");   // "landline"
detectPhoneKind("0850 123 45 67");   // "national"
toE164("0532 123 45 67");            // "+905321234567"
formatPhone("+905321234567");        // "0532 123 45 67"
maskPhone("05321234567");            // "0532 *** ** 67"
isValidMobilePhone(v);
```

Kabul edilen girişler: `0532…`, `532…`, `+90 (532) …`, `90532…`, `0090532…`.

### Plaka, posta kodu, MERSİS

```ts
isValidPlate("34 ABC 123");  // true
formatPlate("34abc123");     // "34 ABC 123"
isValidPostalCode("21100");  // true (ilk iki hane il kodu)
isValidMersis("0123456789000015");
```

Plaka kuralları: il kodu 01–81; 1 harf → 4–5 rakam, 2 harf → 3–4 rakam, 3 harf → 2–3 rakam; Ç, Ğ, İ, Ö, Ş, Ü, Q, W, X kullanılmaz.

> Algoritmik doğrulama, numaranın gerçek bir kişiye/şirkete ait olduğunu kanıtlamaz.

---

# @trkit-app-pack/format

URL: https://zersjs.github.io/trkit/docs/paketler/format.md

> TL, İstanbul saatiyle tarih, göreli zaman, tutarı yazıya çevirme, ünlü uyumlu hâl ekleri ve Türkçe harf dönüşümü.

```bash
npm install @trkit-app-pack/format
```

Bağımlılığı yoktur; sunucuda, tarayıcıda ve Edge'de çalışır.

### Para

Tutarları **kuruş cinsinden tamsayı** olarak tutun.

```ts
tl(129950);                          // "1.299,50 ₺"
tl(100000, { kurus: "auto" });       // "1.000 ₺"
tl(5, { sembol: "TL" });             // "0,05 TL"
tlFromLira(1299.5);                  // "1.299,50 ₺"
tlParse("1.299,50 ₺");               // 129950
sayi(1234567.891);                   // "1.234.567,89"
yuzde(0.18);                         // "%18"
kdvHesapla(12000, 0.2);              // { net: 10000, kdv: 2000, toplam: 12000 }
```

### Tarih

Sunucular (Vercel vb.) UTC çalışır. Gece yarısından sonra verilen bir sipariş, `toLocaleDateString()` ile bir önceki günün tarihiyle görünür. trkit'in tarih fonksiyonları her zaman `Europe/Istanbul` saat dilimini kullanır.

```ts
const d = "2026-11-06T22:30:00Z";     // İstanbul'da 7 Kasım 01:30
tarih(d);                             // "7 Kasım 2026"
tarih(d, "kisa");                     // "07.11.2026"
tarih(d, "orta");                     // "7 Kas 2026"
tarih(d, "tam");                      // "7 Kasım 2026 Cumartesi"
tarihSaat(d);                         // "7 Kasım 2026 01:30"
saat(d);                              // "01:30"
isoGun(d);                            // "2026-11-07"
goreli(Date.now() - 5 * 60_000);      // "5 dakika önce"
goreli(dun);                          // "dün"
```

`AYLAR` ve `GUNLER` dizileri de dışa aktarılır.

> Statik sayfalarda `new Date()` derleme anında sabitlenir. Güncel tarih göstermek için sayfayı dinamik yapın veya tarihi istemcide biçimlendirin.

### Tutarı yazıya çevirme

Fatura, makbuz, senet ve sözleşmeler için:

```ts
sayiyiYaziyaCevir(1234);                         // "bin iki yüz otuz dört"
sayiyiYaziyaCevir(1_000_000);                    // "bir milyon"
tutariYaziyaCevir(123456);                       // "bin iki yüz otuz dört Türk lirası elli altı kuruş"
tutariYaziyaCevir(123456, { bitisik: true, yalniz: true });
// "Yalnız #BinİkiYüzOtuzDörtTL,ElliAltıKr#"
```

### Hâl ekleri

Özel isimlere ünlü uyumu ve ünsüz benzeşmesine uygun ek getirir:

```ts
hal("İstanbul", "yonelme");   // "İstanbul'a"
hal("Ankara", "belirtme");    // "Ankara'yı"
hal("Sinop", "bulunma");      // "Sinop'ta"
hal("Kadıköy", "ayrilma");    // "Kadıköy'den"
hal("Ayşe", "tamlayan");      // "Ayşe'nin"
hal("Ali", "vasita");         // "Ali'yle"
hal("34", "yonelme");         // "34'e"
hal("A.Ş.", "tamlayan", { okunus: "aşe" }); // "A.Ş.'nin"
ek("Ankara", "yonelme");      // "ya" (kesme işareti olmadan)
cogul("kitap");               // "kitaplar"
```

Kullanım: `${hal(sehir, "yonelme")} kargo 2 gün sürer`, `${hal(ad, "tamlayan")} siparişi`.

Kısaltmalar okunuşa göre ek aldığından `okunus` parametresini verin.

### Metin

```ts
buyukHarf("istanbul");                  // "İSTANBUL"
kucukHarf("IĞDIR");                     // "ığdır"
basHarfleriBuyut("AYŞE  yılmaz");       // "Ayşe Yılmaz"
cumleBasi("İSTANBUL GÜZEL");            // "İstanbul güzel"
adSoyadAyir("ali ihsan yılmaz");        // { ad: "Ali İhsan", soyad: "Yılmaz" }
kisalt("Merhaba dünya nasılsın", 15);   // "Merhaba dünya…"
```

---

# @trkit-app-pack/address

URL: https://zersjs.github.io/trkit/docs/paketler/address.md

> 81 il, 973 ilçe, bölge ve alan kodu verisi; Türkçe karakter duyarsız arama.

```bash
npm install @trkit-app-pack/address
```

Veri paketle birlikte gelir (yaklaşık 15 KB), ağ isteği yapılmaz.

### Veri

```ts
import { provinces, getProvince, getDistricts, getDistrict, regions, getProvincesByRegion } from "@trkit-app-pack/address";

provinces.length;                  // 81
getProvince(34);                   // { code: 34, codeStr: "34", name: "İstanbul", slug: "istanbul", region: "Marmara", areaCodes: [212, 216], districts: [...] }
getProvince("ISTANBUL")?.code;     // 34 (büyük/küçük harf ve Türkçe karakter duyarsız)
getProvince("urfa")?.name;         // "Şanlıurfa" (yaygın alternatif adlar)
getDistricts("Diyarbakır");        // [{ name: "Bağlar", slug: "baglar", provinceCode: 21 }, ...]
getDistrict(34, "kadikoy")?.name;  // "Kadıköy"
getProvincesByRegion("Ege");
```

### Doğrulama

```ts
isValidDistrict("Ankara", "Çankaya");  // true
isValidDistrict("İzmir", "Çankaya");   // false
```

Form verisini sunucuda bununla doğrulayın; istemciden gelen il/ilçe çiftine güvenmeyin.

### Arama

```ts
search("kadikoy");
// [{ type: "district", province: { name: "İstanbul" }, district: { name: "Kadıköy" }, score: 100 }]

search("kaya", { province: 21, limit: 5 });  // yalnızca Diyarbakır'da
formatLocation(34, "kadıköy");                // "Kadıköy / İstanbul"
```

Sıralama: tam eşleşme > önek > kelime başı > içerir. Aynı adlı il ve ilçede il önce gelir.

### Türkçe metin yardımcıları

```ts
foldTr("ÇANAKKALE");                    // "canakkale" (arama anahtarı)
slugifyTr("Kahramanmaraş Onikişubat");  // "kahramanmaras-onikisubat"
trUpper("istanbul");                    // "İSTANBUL"
["Zonguldak", "Çorum", "Ceyhan"].sort(compareTr); // ["Ceyhan", "Çorum", "Zonguldak"]
```

### Veriyi güncellemek

İlçe veri kaynağı [Türkiye API](https://github.com/ubeydeozdmr/turkiye-api)'dir. trkit deposunda `npm run sync:address` ile yeniden üretilir.

Mahalle verisi (~32.000 kayıt) boyutu nedeniyle henüz pakette yoktur.

---

# @trkit-app-pack/legal

URL: https://zersjs.github.io/trkit/docs/paketler/legal.md

> KVKK ve e-ticaret yasal metin şablonları, çerez onayı ve onay kayıtları.

```bash
npm install @trkit-app-pack/legal
```

> Şablonlar hukuki danışmanlık yerine geçmez. Yayına almadan önce bir avukata kontrol ettirin.

### Şablonlar

| Kimlik | Başlık | Dayanak |
|---|---|---|
| `kvkk-aydinlatma` | KVKK Aydınlatma Metni | 6698 md. 10, Aydınlatma Tebliği |
| `acik-riza` | Açık Rıza Metni | 6698 md. 5/1, 6, 9 |
| `cerez-politikasi` | Çerez Politikası | KVKK Çerez Rehberi |
| `mesafeli-satis` | Mesafeli Satış Sözleşmesi | 6502, Mesafeli Sözleşmeler Yönetmeliği |
| `on-bilgilendirme` | Ön Bilgilendirme Formu | Mesafeli Sözleşmeler Yönetmeliği md. 5–6 |
| `teslimat-iade` | Teslimat ve İade Koşulları | 6502, Yönetmelik |
| `ticari-ileti` | Ticari Elektronik İleti Onayı | 6563 md. 6–8, İYS |
| `kvkk-basvuru` | KVKK Başvuru Formu | 6698 md. 11, 13 |

Her belgenin `templateVersion` ve `legalBasis` alanları vardır. Mevzuat değiştiğinde şablon sürümü artar.

### Üretme

```ts
import { generate, generateAll, toHtml, toMarkdown, toPlainText } from "@trkit-app-pack/legal";
import config from "@/trkit.config";

const { document, warnings } = generate("kvkk-aydinlatma", config);
toHtml(document);       // güvenli (kaçışlı) HTML
toMarkdown(document);
toPlainText(document);

// Sipariş bilgisiyle (mesafeli-satis, on-bilgilendirme)
generate("mesafeli-satis", config, { order });
```

Eksik bilgiler metinde `[MERSİS NO]` gibi görünür ve `warnings` dizisinde döner.

### Yapılandırma

```ts
interface LegalConfig {
  company: {
    unvan: string; marka?: string; mersis?: string; vergiDairesi?: string; vergiNo?: string;
    adres: string; telefon?: string; eposta: string; kvkkEposta?: string; kep?: string;
    website: string; sahis?: boolean; // şahıs şirketi: MERSİS yerine vergi no
  };
  kvkk?: {
    veriKategorileri?: DataCategoryKey[];
    aktarimlar?: { alici: string; amac: string; yurtDisi?: boolean }[];
    yurtDisiAktarim?: { hizmetler: string[]; dayanak: "yeterlilik" | "standart-sozlesme" | "baglayici-kurallar" | "arizi-acik-riza" };
    verbisNo?: string;
    kanallar?: string[];
  };
  satis?: {
    teslimatSuresiGun?: number;   // en fazla 30
    kargoyaVerilisGun?: number;
    kargoFirmalari?: string[];
    iadeKargo?: { firma: string; kod?: string };
    odemeYontemleri?: string[];
    dijitalUrun?: boolean;
  };
  cerezler?: { ad: string; saglayici: string; amac: string; sure: string; kategori: "zorunlu" | "fonksiyonel" | "analitik" | "pazarlama" }[];
  ticariIleti?: { kanallar?: ("sms" | "eposta" | "arama")[]; iysMarkaKodu?: string };
  pay?: { provider: string };     // aktarım listesine eklenir
  sms?: { provider: string };
  guncellemeTarihi?: string;      // YYYY-AA-GG
}
```

### Veri kategorileri

| Anahtar | Örnek veriler | Hukuki sebep |
|---|---|---|
| `kimlik` | Ad, soyad, fatura için TCKN | Sözleşme, hukuki yükümlülük |
| `iletisim` | Telefon, e-posta, adres | Sözleşme, meşru menfaat |
| `musteri-islem` | Sipariş geçmişi, talepler | Sözleşme, meşru menfaat |
| `finans` | Fatura bilgileri, iade IBAN'ı | Sözleşme, hukuki yükümlülük |
| `islem-guvenligi` | IP, log kayıtları | Hukuki yükümlülük (5651), meşru menfaat |
| `pazarlama` | Tercihler, çerez verileri | **Açık rıza** |
| `hukuki-islem` | Yazışmalar | Hakkın tesisi, hukuki yükümlülük |
| `lokasyon` | Konum | **Açık rıza** |
| `gorsel-isitsel` | Kamera, çağrı kaydı | Meşru menfaat |
| `saglik` | Sağlık bilgileri (özel nitelikli) | **Açık rıza** + ek önlemler |

Açık rıza gerektiren kategoriler açık rıza metnine otomatik eklenir.

### Çerez onayı

```ts
import { parseCookieConsent, serializeCookieConsent, isAllowed, COOKIE_CONSENT_NAME } from "@trkit-app-pack/legal";
```

React bileşeni için: [Çerez banner'ı](/docs/bilesenler/cerez-banner).

### Onay kayıtları

```ts
import { createConsentRecord, documentHash, latestByPurpose, type ConsentStore } from "@trkit-app-pack/legal";

const record = await createConsentRecord({
  subjectId: "u1",
  purpose: "ticari-ileti:sms",    // veya "kvkk:acik-riza", "cookie:analitik"
  granted: true,
  document: "ticari-ileti@2024.01.1",
  documentHash: await documentHash(document),
  source: "kayit-formu",
  ip, salt: process.env.CONSENT_SALT!,
});
```

`ConsentStore` arayüzü (`append`, `latest`) ile kendi veritabanınıza bağlayın. Kayıtları güncellemeyin; her değişiklik yeni bir kayıttır.

---

# @trkit-app-pack/pay

URL: https://zersjs.github.io/trkit/docs/paketler/pay.md

> iyzico, PayTR ve mock ödeme sağlayıcıları için ortak arayüz.

```bash
npm install @trkit-app-pack/pay
```

Akışın tamamı için: [Ödeme akışı](/docs/rehber/odeme).

### İstemci

```ts title="lib/pay.ts"
import "server-only";
import { createPay, createPayFromEnv } from "@trkit-app-pack/pay";

export const pay = createPay({ provider: "iyzico", apiKey: "...", secretKey: "...", sandbox: true });
// veya
export const pay = createPay({ provider: "paytr", merchantId: "...", merchantKey: "...", merchantSalt: "...", testMode: true });
// veya ortam değişkenlerinden (TRKIT_PAY_PROVIDER, IYZICO_*, PAYTR_*)
export const pay = createPayFromEnv();
```

### Arayüz

```ts
interface PaymentProvider {
  name: string;
  createCheckout(input: CheckoutInput): Promise<CheckoutSession>;
  verifyCallback(payload: Record<string, string>): Promise<PaymentResult>;
  callbackResponse(result: PaymentResult): Response;
  refund(input: { paymentId: string; amount: number; ip?: string }): Promise<RefundResult>;
}
```

**CheckoutInput**: `orderId`, `amount` (kuruş), `currency?`, `buyer` (`id, name, surname, email, phone, identityNumber?, ip, address`), `items` (`id, name, category, unitPrice` (kuruş), `quantity?, type?`), `callbackUrl`, `successUrl?`, `failUrl?`, `installments?`, `locale?`.

**CheckoutSession**: `token`, `paymentPageUrl?` (iyzico), `html?` (iyzico checkout form), `iframeUrl?` (PayTR).

**PaymentResult**: `status` (`success` | `failure` | `pending`), `orderId`, `paymentId?`, `paidAmount?` (kuruş, taksit farkı dahil), `installment?`, `errorCode?`, `errorMessage?`, `raw`.

### Sağlayıcı farkları

| | iyzico | PayTR |
|---|---|---|
| Ödeme sayfası | Checkout Form (yönlendirme veya gömülü) | iFrame |
| Callback | Kullanıcının tarayıcısı POST eder, sonuç API'den sorgulanır | Sunucudan sunucuya, hash ile imzalı |
| Callback yanıtı | 303 yönlendirme (`redirectTo` ile özelleştirilir) | Düz metin `OK` |
| Sipariş no | Serbest | Yalnızca harf ve rakam |
| `successUrl` / `failUrl` | Kullanılmaz | Zorunlu |
| TCKN | `identityNumber` (yoksa `11111111111`) | Kullanılmaz |

### Hatalar

Tüm hatalar `PaymentError` türündedir (`code`, `provider`, `raw`). Örnek kodlar: `BASKET_MISMATCH`, `EMPTY_BASKET`, `INVALID_ORDER_ID`, `BAD_HASH`, `MISSING_TOKEN`, `CLIENT_SIDE_USAGE`.

### Yardımcılar

```ts
toKurus("129,50");       // 12950
kurusToDecimal(12950);   // "129.5"
basketTotal(items);
```

### Teknik notlar

- İmzalar Web Crypto ile atılır; Node.js ve Edge runtime'da çalışır.
- Paket tarayıcıda çalıştırılırsa `CLIENT_SIDE_USAGE` hatası fırlatır.
- `fetch` seçeneğiyle istekleri test için taklit edebilirsiniz.

---

# @trkit-app-pack/sms

URL: https://zersjs.github.io/trkit/docs/paketler/sms.md

> Netgsm ve geliştirme sağlayıcısı, İYS filtresi, güvenli OTP.

```bash
npm install @trkit-app-pack/sms
```

Kullanım rehberi: [SMS ve OTP](/docs/rehber/sms-otp).

### İstemci

```ts
import { createSms, createSmsFromEnv } from "@trkit-app-pack/sms";

const sms = createSms({ provider: "netgsm", usercode: "850…", password: "…", header: "MARKA" });
const dev = createSms({ provider: "dev" }); // konsola yazar, gönderilenler dev.outbox'ta
const fromEnv = createSmsFromEnv();         // TRKIT_SMS_PROVIDER, NETGSM_*
```

### Gönderim

```ts
const r = await sms.send({
  to: ["0532 123 45 67", "+905551234567"],  // tekrarlar ayıklanır
  text: "Siparişiniz kargoda",
  kind: "transactional",                    // | "commercial-individual" | "commercial-merchant"
  header: "MARKA",                          // isteğe bağlı
});
// { success: true, messageId: "...", raw }
```

Sabit hatlar reddedilir (`SmsError`, kod `INVALID_NUMBER`).

### OTP

```ts
import { createOtp, memoryOtpStore, type OtpStore } from "@trkit-app-pack/sms";

const otp = createOtp({
  sms,
  store: memoryOtpStore(),   // üretimde Redis/DB
  secret: process.env.OTP_SECRET!,
  length: 6,
  ttlSeconds: 180,
  maxAttempts: 5,
  resendSeconds: 60,
  message: (kod, dk) => `Doğrulama kodunuz: ${kod}. ${dk} dakika geçerlidir.`,
});

await otp.send("0532 123 45 67");   // { sent: true, expiresAt } | { sent: false, retryAfter }
await otp.verify("05321234567", "123456"); // { ok: true } | { ok: false, reason }
```

`reason`: `invalid`, `expired`, `too_many_attempts`, `invalid_number`.

### Yardımcılar

```ts
toTrMsisdn("+90 532 123 45 67");   // "5321234567"
countSmsSegments("Türkçe metin…");  // Türkçe karakterli SMS 155, diğerleri 160 karakter
```

---

# İl / ilçe seçici

URL: https://zersjs.github.io/trkit/docs/bilesenler/il-ilce-secici.md

> Erişilebilir bağımlı il/ilçe seçimi ve Türkçe duyarsız arama bileşenleri.

```bash
npx trkit add il-ilce-secici il-ilce-arama
```

### IlIlceSecici

İki bağımlı yerel `<select>`. Mobilde sistem seçicisi açılır, klavyeyle harf yazarak gezinilir, JavaScript yüklenmeden de form gönderilebilir.

```tsx
"use client";
import { useState } from "react";
import { IlIlceSecici, type IlIlceDegeri } from "@/components/trkit/il-ilce-secici";

const [konum, setKonum] = useState<IlIlceDegeri>({ il: null, ilce: null });

<IlIlceSecici
  value={konum}
  onChange={setKonum}
  name={{ il: "il", ilce: "ilce" }}   // form alanı adları
  required
/>
```

| Prop | Tür | Açıklama |
|---|---|---|
| `value` | `{ il: number \| null; ilce: string \| null }` | `il` plaka kodudur |
| `onChange` | `(v) => void` | İl değişince ilçe sıfırlanır |
| `name` | `{ il: string; ilce: string }` | Form gönderimi için |
| `iller` | `number[]` | Yalnızca bu illeri göster (hizmet bölgesi) |
| `siralama` | `"alfabetik" \| "plaka"` | Varsayılan alfabetik (Türkçe harf sırası) |
| `labels` | `{ il?: string; ilce?: string }` | Etiket metinleri |
| `error` | `{ il?: string; ilce?: string }` | Hata mesajları (`aria-invalid` ile) |
| `required`, `disabled`, `className` | | |

Sunucuda doğrulayın:

```ts
import { isValidDistrict } from "@trkit-app-pack/address";
isValidDistrict(form.il, form.ilce);
```

### IlIlceArama

Tek kutuda il veya ilçe arama: "kadikoy" yazınca "Kadıköy / İstanbul" önerilir. Klavyeyle (↑ ↓ Enter Esc) kullanılabilir, ARIA combobox desenine uyar.

```tsx
import { IlIlceArama } from "@/components/trkit/il-ilce-arama";

<IlIlceArama onSelect={({ il, ilce, label }) => setKonum({ il, ilce })} placeholder="İl veya ilçe arayın" />
```

---

# Çerez banner'ı

URL: https://zersjs.github.io/trkit/docs/bilesenler/cerez-banner.md

> KVKK Çerez Rehberi'ne uygun onay banner'ı, tercih paneli ve script kapısı.

```bash
npx trkit add cerez-banner
```

Eklenen dosyalar: `components/trkit/cerez-banner.tsx`, `app/api/consent/route.ts`.

### Dışa aktarılanlar

| | |
|---|---|
| `CookieConsentProvider` | Banner'ı ve bağlamı sağlar. `policyHref` (varsayılan `/cerez-politikasi`) |
| `useCookieConsent()` | `{ state, allowed(kategori), save(tercihler), openPreferences() }` |
| `ConsentGate` | `category` onaylıysa çocuklarını render eder; `fallback` desteklenir |
| `CookiePreferencesLink` | Footer için "Çerez Tercihleri" düğmesi |

### Davranış

- İlk ziyarette banner gösterilir; seçim yapılana kadar zorunlu olmayan hiçbir şey yüklenmez.
- "Reddet" ve "Kabul et" aynı görünürlüktedir; "Tercihleri yönet" kategori bazında seçim sunar.
- Tercih `trkit_consent` çerezinde 6 ay saklanır (SameSite=Lax, HTTPS'te Secure).
- Her seçim `/api/consent` uç noktasına kayıt olarak gönderilir.

### Ayarlar

Dosyanın başındaki sabitler:

```ts
const CONSENT_VERSION = "1";            // politika değişince artırın
const MAX_AGE = 60 * 60 * 24 * 180;     // 6 ay
const LOG_ENDPOINT: string | null = "/api/consent";
```

Kullanım örnekleri: [Çerez onayı rehberi](/docs/rehber/cerez).

---

# Yasal sayfalar

URL: https://zersjs.github.io/trkit/docs/bilesenler/yasal-sayfalar.md

> trkit.config.ts'den üretilen KVKK ve e-ticaret sayfaları.

```bash
npx trkit add yasal          # hepsi
npx trkit add kvkk cerez-politikasi
```

| Öğe | Adres |
|---|---|
| `kvkk` | `/kvkk` |
| `acik-riza` | `/acik-riza` |
| `cerez-politikasi` | `/cerez-politikasi` |
| `mesafeli-satis` | `/mesafeli-satis` |
| `on-bilgilendirme` | `/on-bilgilendirme` |
| `teslimat-iade` | `/teslimat-iade` |
| `ticari-ileti` | `/ticari-ileti` |
| `kvkk-basvuru` | `/kvkk-basvuru` |

Her sayfa birkaç satırdır:

```tsx title="app/kvkk/page.tsx"
import { generate } from "@trkit-app-pack/legal";
import { LegalPage } from "@/components/trkit/legal-page";
import config from "@/trkit.config";

const { document } = generate("kvkk-aydinlatma", config);

export const metadata = { title: document.title };

export default function Page() {
  return <LegalPage document={document} />;
}
```

Sayfalar statik derlenir. Metni değiştirmek için sayfayı değil `trkit.config.ts`'i düzenleyin; böylece `@trkit-app-pack/legal` güncellemelerinden (mevzuat değişiklikleri) yararlanmaya devam edersiniz.

### Görünüm

`LegalPage`, Tailwind Typography'nin `prose` sınıfını kullanır. Tasarımı `components/trkit/legal-page.tsx` içinde değiştirebilirsiniz. HTML çıktısındaki sınıflar: `.trkit-legal`, `.trkit-table`, `.trkit-note`.

### Footer bağlantıları

create-trkit-app projelerinde `src/lib/site.ts` → `legal` dizisine ekleyin:

```ts
legal: [
  { href: "/kvkk", label: "KVKK Aydınlatma Metni" },
  { href: "/mesafeli-satis", label: "Mesafeli Satış Sözleşmesi" },
],
```

---

# Ödeme onayları

URL: https://zersjs.github.io/trkit/docs/bilesenler/odeme-onaylari.md

> Ön bilgilendirme ve mesafeli satış onayı, isteğe bağlı ticari ileti onayı.

```bash
npx trkit add odeme-onaylari
```

Mesafeli Sözleşmeler Yönetmeliği'ne göre ön bilgilendirme, sipariş verilmeden önce alıcıya gösterilmeli ve teyit edilmelidir. Bu bileşen iki metni sipariş bilgileriyle birlikte bir pencerede gösterir ve onay kutusunu zorunlu tutar.

```tsx
import { generate, toHtml } from "@trkit-app-pack/legal";
import { OdemeOnaylari } from "@/components/trkit/odeme-onaylari";

<OdemeOnaylari
  onBilgilendirmeHtml={toHtml(generate("on-bilgilendirme", config, { order }).document)}
  mesafeliSatisHtml={toHtml(generate("mesafeli-satis", config, { order }).document)}
  ticariIleti           // isteğe bağlı kampanya onayı kutusu
  name="onay"           // form alanları: onay[sozlesme], onay[ticariIleti]
/>
```

| Prop | Tür | Açıklama |
|---|---|---|
| `onBilgilendirmeHtml` | `string` | Sunucuda üretilmiş HTML |
| `mesafeliSatisHtml` | `string` | Sunucuda üretilmiş HTML |
| `ticariIleti` | `boolean` | Varsayılan `true` |
| `onChange` | `(v: { sozlesme, ticariIleti }) => void` | |
| `name` | `string` | Form alanı öneki |

Sunucuda `onay[sozlesme]` değerini kontrol edin ve onaylanan metnin özetini (`documentHash`) siparişle birlikte saklayın.

Ticari ileti kutusu önceden işaretli değildir ve satın alma için zorunlu değildir; 6563 sayılı Kanun'a göre böyle olmalıdır.