# Tecof Geliştirici Dokümantasyonu — Tam Metin

> Tecof üzerinde tema, uygulama ve entegrasyon geliştirmek için tek kaynak: CLI, @tecof paketleri, Tecof Studio (theme-editor), API referansları, MCP ve AI araçları.

Bu dosya https://tecof-app-dev.vercel.app adresindeki tüm sayfaların içerikten otomatik üretilmiş birleşimidir. Bölüm sırası site navigasyonuyla aynıdır. Tek sayfa için `<adres>.md` kullanın.

---

# Genel Bakış

> Tecof geliştirici platformuna genel bakış — tema, uygulama, CLI, API ve AI yüzeyleri, hangi yoldan başlanacağı, kimlik doğrulama katmanları ve ortam değişkenleri.
>
> Kaynak: https://tecof-app-dev.vercel.app/getting-started · Bölüm: Başlangıç · Son güncelleme: 2018-10-20

Tecof’ta iki tür şey geliştirirsiniz: mağazanın ziyaretçiye görünen **teması** (Next.js + Tecof Studio) ve mağaza panelinde çalışan **uygulamalar** (partner uygulamaları). İkisi de `@tecof/cli` ile terminalden geliştirilir, numaralı sürümlerle yayınlanır ve anında geri alınabilir. Bu doküman sitesi bu işlerin tamamının tek kaynağıdır; içerik kaynak koda göre yazılır ve her sayfa AI araçları için Markdown olarak da sunulur.

## Nereden başlamalı

| Yapmak istediğiniz | Başlangıç | Sonra |
| :--- | :--- | :--- |
| Mağazanın temasını kodla değiştirmek | [Tema hızlı başlangıç](https://tecof-app-dev.vercel.app/theme-quickstart) | [Tema mimarisi](https://tecof-app-dev.vercel.app/storefronts), [Tecof Studio](https://tecof-app-dev.vercel.app/theme-editor) |
| Temaya Studio’da düzenlenebilir bileşen eklemek | [Bileşen yapılandırması](https://tecof-app-dev.vercel.app/editor-components) | [Alanlar](https://tecof-app-dev.vercel.app/editor-fields), [Slotlar](https://tecof-app-dev.vercel.app/editor-slots), [Stil editörü](https://tecof-app-dev.vercel.app/editor-styles) |
| Mağazalara kurulan bir uygulama yazmak | [Uygulama hızlı başlangıç](https://tecof-app-dev.vercel.app/app-quickstart) | [Tasarım kimliği](https://tecof-app-dev.vercel.app/app-ui), [Webhook’lar](https://tecof-app-dev.vercel.app/app-webhooks), [App Bridge](https://tecof-app-dev.vercel.app/app-bridge) |
| Vitrin verisini kendi önyüzünüzde kullanmak | [Public API](https://tecof-app-dev.vercel.app/public-apis) | [Headless CMS](https://tecof-app-dev.vercel.app/headless-cms) |
| Bir AI ajanını Tecof’a bağlamak | [Tecof MCP](https://tecof-app-dev.vercel.app/mcp) | [Dokümanı AI ile kullanın](https://tecof-app-dev.vercel.app/ai-docs), [Alışveriş ajanları](https://tecof-app-dev.vercel.app/agents) |
| CI’dan yayın yapmak | [Güvenlik ve CI](https://tecof-app-dev.vercel.app/dev-security) | [CLI başvurusu](https://tecof-app-dev.vercel.app/cli-reference) |
| Paket sürümlerini görmek | [Paketler](https://tecof-app-dev.vercel.app/packages) | — |

## Platform yüzeyleri

### Tema ve vitrin

Temalar Next.js App Router projeleridir. Sayfa verisini, CMS içeriğini, mağaza ayarlarını ve e-ticaret verisini backend’in `/api/store/*` katmanından vitrin anahtarıyla (`x-secret-key`) okur; sayfaları `@tecof/theme-editor`’ün `TecofRender`’ı ile çizer. Panel aynı sayfaları temanın editör rotasında **Tecof Studio** ile düzenletir. Özel temanın kodu bir **Space**’te yaşar: `tecof theme push` yalnız değişen dosyaları yükleyip staged bir sürüm açar, `tecof theme promote` onu yeniden derlemeden canlıya alır ([Spaces](https://tecof-app-dev.vercel.app/spaces)).

### Partner uygulamaları

Uygulamalar mağazaya kurulur; istemci kimliği + sırrıyla alınan kurulum token’ı (`tcfi_…`) ile `/api/v1`’i kullanır, imzalı webhook’lar ve panel aksiyonları alır, panelde iframe içinde `@tecof/app-ui` ile Tecof görünümünde çalışır, ayarlarını Vault ve metafield’larda tutar ve ücretli planlar sunabilir ([Uygulama geliştirme](https://tecof-app-dev.vercel.app/app-development)).

### Vitrin ve CMS API’leri

Canlı mağazanın güvenli API yüzeyi `/api/store/*` altındadır: ürün listesi, sepet doğrulama, checkout, müşteri hesabı, CMS okuma, bülten ve tema render verisi ([Public API](https://tecof-app-dev.vercel.app/public-apis)). Panel (yönetim) uçları `/api/merchant/*` altında JWT ile korunur ve panel içindir; üçüncü taraflar `/api/v1` kullanır.

### AI ve MCP

Tecof’un uzak MCP sunucusu (`https://api.tecof.com/mcp`) mağaza verisini, sayfaları, CMS’i, ürünleri ve tema kodunu kapsamlı yetkilerle ajanlara açar; `@tecof/mcp` aynı araçları tema reposunun içinden sunar ([Tecof MCP](https://tecof-app-dev.vercel.app/mcp)). Mağazalar ayrıca AI arama motorları için `llms.txt` ve `/ai/*.json` dosyaları yayınlar ([GEO: AI Storefront](https://tecof-app-dev.vercel.app/ai-storefront)).

## Kimlik doğrulama modeli

| Katman | Kullanım | Kimlik doğrulama |
| :--- | :--- | :--- |
| Vitrin (okuma ve güvenli yazma) | Canlı tema, ürün, CMS, checkout | `x-secret-key` |
| Müşteri hesabı | Profil, adres, siparişler, yorum/favori | `x-secret-key` + müşteri `Authorization` |
| Tema editörü yazma | Sayfa kaydetme, yükleme, ortak bileşen | `x-secret-key` + mağaza/ekip JWT’si |
| Panel (yönetim) | Satıcı paneli ve yönetim API’leri | JWT, rol/ekip yetkisi |
| Analytics toplama | Vitrin olayları | Public `merchantId` |
| Partner uygulaması (sunucu) | Kurulu uygulamanın `/api/v1` çağrıları | `Authorization: Bearer tcfi_…` (kurulum token’ı) |
| Partner uygulaması (iframe) | Panel içindeki uygulama arayüzü → uygulama sunucusu | 60 sn’lik oturum JWT’si (App Bridge) |
| CLI ve CI | Spaces, push, promote, rollback | Cihaz akışı token’ı (`tcfd_…`) ya da kapsamlı CI token’ı (`TECOF_TOKEN`) |
| MCP | Ajanların mağaza araçları | OAuth 2.1 ya da kişisel erişim anahtarı (`tcf_…`) |

`NEXT_PUBLIC_MERCHANT_SECRET_KEY` temanın public bundle’ında bulunur. Bu yüzden backend, yazma yetkisi gerektiren editör işlemlerinde ayrıca JWT ister; taslak önizleme de imzalı `previewToken` ister.

## Ortam değişkenleri

Tema projelerinin temel değişkenleri (`tecof theme dev` bunları `.env.local` dosyasına yazar):

```dotenv title=".env.local"
NEXT_PUBLIC_BASE_URL=https://api.tecof.com
NEXT_PUBLIC_CDN_URL=https://cdn.tecof.com
NEXT_PUBLIC_MERCHANT_SECRET_KEY=merchant_secret_key
NEXT_PUBLIC_THEME_ID=merchant_theme_id
```

`tecof-theme-core` bu değerlerle `/api/store/render`, `/api/store/merchant-info`, `/api/store/pages` ve `/api/store/ecommerce/*` uçlarını çağırır. Uygulama projelerinin değişkenleri (`TECOF_CLIENT_ID`, `TECOF_CLIENT_SECRET`, `TECOF_API_URL`) [uygulama hızlı başlangıçta](https://tecof-app-dev.vercel.app/app-quickstart#ortam-degiskenleri).

## Doğruluk notu

Bu belgeler kaynak koda göre yazılır: `tecof-app-backend` (API sözleşmeleri), `tecof-theme-core` (tema runtime’ı), `tecof-theme-editor` (Studio ve renderer), `tecof-app-sdk` (CLI, uygulama paketleri) ve `tecof-mcp`. Mevcut kodda doğrulanan yol REST tabanlı `/api/store/*`, `/api/v1` ve MCP sözleşmeleridir; GraphQL ya da ayrı bir storefront SDK’sı birincil yol değildir. Henüz kodda olmayan özellikler “plan” olarak belirtilir. Bir çelişki görürseniz paketlerin gerçek tip tanımları ve API yanıtları son doğruluk kaynağıdır.

---

# Tema Geliştirme: Hızlı Başlangıç

> Özel temayı terminalden geliştirip canlıya alma: tecof login, theme init, dev (yerel/bulut), push, önizleme, promote, rollback ve base-moved çözümü.
>
> Kaynak: https://tecof-app-dev.vercel.app/theme-quickstart · Bölüm: Tema geliştirme · Son güncelleme: 2018-10-20

Bu sayfa bir özel temayı terminalden geliştirip canlıya almayı adım adım anlatır: giriş, kodu indirme, yerel ya da bulut geliştirme, push, önizleme, canlıya alma ve geri alma. Kavramlar için [Geliştirici Alanları (Spaces)](https://tecof-app-dev.vercel.app/spaces) sayfasına bakın.

**Gerekenler**

| Gereksinim | Not |
| :--- | :--- |
| Node.js 20+ | CLI'ın çalışma zamanı bağımlılığı yoktur; `tecof doctor` sürümü denetler |
| Tecof hesabı ve mağaza ekibi üyeliği | Temanın ait olduğu mağazanın ekibinde olmanız yeterli; partner hesabı gerekmez |
| Özel tema | Katalog temaları salt okunurdur; önce özel temaya kopyalayın ([ayrıntı](https://tecof-app-dev.vercel.app/spaces#salt-okunur-alanlar)) |
| Paket | Push, canlıya alma, geri alma ve bulut geliştirme için mağaza paketinde Özel Temalar ve Kod Erişimi açık olmalı ([ayrıntı](https://tecof-app-dev.vercel.app/spaces#paket-gereksinimi)) |
| Paket yöneticisi | Temanın kilit dosyasına göre `npm`, `pnpm`, `yarn` ya da `bun` |

---

## 1. CLI'ı Kurun

```bash
npm install -g @tecof/cli
tecof --version
tecof doctor
```

`tecof doctor` Node sürümünü, API erişimini, oturumu, kimlik deposunu, klasör bağını, git'i ve paket yöneticisini denetler; zorunlu bir denetim başarısızsa çıkış kodu 1 olur.

> **Not:** `tecof theme --help` tema komutlarını listelemiyorsa eski bir sürüm kuruludur; `npm install -g @tecof/cli@latest` ile güncelleyin.

---

## 2. Giriş Yapın

```bash
tecof login
```

```text
Tecof'a giriş yapılıyor (https://api.tecof.com)…

  Doğrulama kodu: KQ7M-4XRT
  Tarayıcıda açın ve kodu onaylayın: https://app.tecof.com/cli?code=KQ7M-4XRT

Onay bekleniyor…
✔ Giriş yapıldı: ayse@ornek-ajans.com (Örnek Ajans)
Token deposu: keychain
```

1. CLI onay sayfasını tarayıcıda açar. Açamazsa (ör. SSH oturumunda) adresi kendiniz açın; `--no-browser` tarayıcıyı hiç denemez.
2. Panelde oturumunuz açıkken sayfa doğrulama kodunu, CLI'ın adını, IP adresini, istek zamanını ve yetkilendirilecek hesabı gösterir. Kod terminaldekiyle aynıysa **Onayla ve giriş yap**; isteği siz başlatmadıysanız **Reddet**.
3. Kod 10 dakika geçerlidir. CLI onayı 5 saniyede bir yoklar ve onay gelince token'ı işletim sisteminin anahtarlığına kaydeder ([Kimlik bilgisi deposu](https://tecof-app-dev.vercel.app/dev-security#kimlik-bilgisi-deposu)).

```bash
tecof whoami
```

Cihaz oturumu 30 gün geçerlidir; 14 gün kullanılmazsa düşer. Onayladığınız cihazları panelde `https://app.tecof.com/cli?tab=tokens` (**CLI anahtarları**) sayfasında görüp iptal edebilirsiniz. `tecof logout` token'ı sunucuda da iptal eder.

---

## 3. Tema Alanınızı Bulun

```bash
tecof theme ls
```

```text
id                            kind   name   merchant/app        live  last  rolled-back  writable
----------------------------  -----  -----  ------------------  ----  ----  -----------  ------------------
thm_66f1a2b3c4d5e6f7a8b9c0d1  theme  Butik  Butik Mağaza (BTK)  v11   v11                yes
thm_66f1a2b3c4d5e6f7a8b9c0d2  theme  Vita   Butik Mağaza (BTK)  -     -                  no (catalog-theme)
```

Tema ve uygulama alanlarının hepsini `tecof spaces ls` listeler. Alan kimliğini panelde de bulabilirsiniz: **Temalar** → tema kartındaki ⋯ menüsü → **Sürümler** ekranının başlığında, kopyalama düğmesiyle.

---

## 4. Kodu İndirin

```bash
tecof theme init butik --space thm_66f1a2b3c4d5e6f7a8b9c0d1
```

```text
Kaynak indiriliyor (main)…
✔ Hazır: butik → Butik (312 dosya)

Sonraki adımlar:
  cd butik
  npm install
  tecof theme dev
```

`init` klasörü açar, `main` dalının son hâlini indirir (çalıştırılabilir dosya izinleri korunur) ve iki dosya yazar:

| Dosya | İçerik | Git |
| :--- | :--- | :--- |
| `.tecof/space.json` | Klasörün bağlı olduğu alan: `{ "space": "thm_…", "kind": "theme" }` | Commit'leyin; CI alanı bu dosyadan bulur |
| `.tecof/state.json` | Yerel taban: indirilen `main` commit'i, dosya özetleri ve bekleyen staged sürüm | Yerel önbellek; CLI'ın yazdığı `.tecof/.gitignore` onu git dışında tutar |

`.tecof/` klasörü Tecof'a hiçbir zaman gönderilmez. Etkileşimli terminalde `--space` vermezseniz yazılabilir temalar arasından seçim yaparsınız. Klasör boş değilse `--force` gerekir.

Klasör zaten varsa — örneğin başka bir makinede kendi git deponuzdan geldiyse — `.tecof/space.json` sizi alana bağlar ama yerel taban (`state.json`) yoktur. `tecof theme pull` güncel `main` dalını indirip tabanı kaydeder; yerelde farklı olan dosyaların üzerine `--force` olmadan yazmaz. Bağ dosyası hiç yoksa önce `tecof theme link --space thm_…` çalıştırın.

---

## 5. Yerelde Geliştirin

```bash
cd butik
npm install
tecof theme dev
```

```text
✔ .env.local güncellendi (4 değişken: NEXT_PUBLIC_BASE_URL, NEXT_PUBLIC_CDN_URL, NEXT_PUBLIC_MERCHANT_SECRET_KEY, NEXT_PUBLIC_THEME_ID); diğer satırlar korundu.
Başlatılıyor: npm run dev -- --port 3000 (port 3000)
```

`tecof theme dev` temanın canlıda kullandığı genel ortam değişkenlerini `.env.local` dosyasına yazar ve temanın `dev` betiğini başlatır:

| Değişken | Değer |
| :--- | :--- |
| `NEXT_PUBLIC_BASE_URL` | Tecof API adresi |
| `NEXT_PUBLIC_CDN_URL` | Tecof CDN adresi |
| `NEXT_PUBLIC_MERCHANT_SECRET_KEY` | Mağazanın vitrin anahtarı (genel bir değerdir; tarayıcı paketine zaten girer) |
| `NEXT_PUBLIC_THEME_ID` | Tema kimliği |

- `.env.local` içindeki diğer satırlar korunur; dosya `0600` izinle yazılır ve hiçbir zaman push edilmez.
- Paket yöneticisi kilit dosyasından seçilir (`pnpm-lock.yaml`, `yarn.lock`, `bun.lock`, `package-lock.json`). Port `--port` ile değişir; varsayılan `PORT` ortam değişkeni ya da `3000`.

> **Dikkat:** Yerel sunucu, canlı sitenin kullandığı API'ye gerçek mağaza verisiyle bağlanır. Sayfalar, ürünler ve CMS içeriği gerçektir; sepet, form gönderimi ya da sipariş gibi yazma işlemleri gerçek mağazaya gider.

### Bulutta Geliştirme

Yerel ortam kurmadan çalışmak ya da önizlemeyi başkasıyla paylaşmak için:

```bash
tecof theme dev --cloud
```

```text
Bulut geliştirme oturumu açılıyor (thm_66f1a2b3c4d5e6f7a8b9c0d1)…
✔ İlk eşitleme: 2 dosya yazıldı, 0 silindi.

  Önizleme: https://sb-….vercel.run

Değişiklikler izleniyor (Ctrl+C ile çıkış). Sürüme dönüştürmek için: tecof theme push
```

Bulut oturumu Cloud IDE'nin sandbox'ını kullanır: kod `main` dalından açılır, CLI yerel farkınızı yazar, sonra klasörü izleyip değişiklikleri yaklaşık 300 ms'lik gruplar hâlinde oturuma gönderir. Önizleme adresi sıcak yenilemeyle (HMR) güncellenir.

- Yalnız metin dosyaları eşitlenir; görsel ya da font gibi ikili dosyalar `binary-not-supported` ile reddedilir. Onları `tecof theme push` ile gönderin.
- Yerel taban `main` ile aynıysa yalnız farklı dosyalar gönderilir. Taban eskiyse CLI uyarır ve tüm dosyaları gönderir; projede ikili dosya varsa eşitleme durur. Bu uyarıyı görürseniz önce `tecof theme pull` ile tabanı güncelleyin.
- Oturum Cloud IDE ile aynı kredi kurallarına tabidir: açılışta ve açık kaldığı sürece mağazanın kredisinden düşer ([MCP → Kredi](https://tecof-app-dev.vercel.app/mcp#kredi)). Oturum 45 dakika sonra kapanır; CLI süreyi uzatmaz, oturum bitince uyarıp çıkar.
- Bir temada aynı anda tek oturum açık olabilir. Aynı temada başka bir kullanıcının Cloud IDE oturumu açıksa `409 session-busy` döner.
- Ctrl+C'de CLI oturumu kapatmayı sorar (varsayılan evet); `--keep` oturumu açık bırakır. Oturum kapanırken taslak kaydedilmez: kaynak gerçeği sizin klasörünüzdür.
- Bulut geliştirme yalnız `tecof login` oturumuyla çalışır; kapsamlı CI token'ı `403 token-scope-insufficient` alır.
- Oturumdaki değişiklikler yalnız `tecof theme push` ile sürüme dönüşür.

---

## 6. Push Edin

```bash
tecof theme push -m "Yeni ana sayfa"
```

```text
Push: thm_66f1a2b3c4d5e6f7a8b9c0d1 → staged
312 dosya tarandı (4.21 MB).
Plan: 3 yüklenecek, 1 silinecek, 309 aynı.
Yükleniyor 3/3 dosya (17.8 KB / 17.8 KB)
Sürüm açıldı: v12 (staged)
Durum: queued
Durum: building
Durum: ready
✔ v12 hazır: https://tecof-theme-butik-3k9x2a1b7-tecof.vercel.app
Önizleme: tecof theme open v12
Canlıya almak için: tecof theme promote v12
```

- Yalnız depoda olmayan içerik yüklenir; değişmeyen dosyalar ve depoda zaten bulunan içerik (ör. taşınan bir dosya) yeniden gönderilmez. Yerelde sildiğiniz dosyalar depodan da silinir.
- Varsayılan hedef **staged**: üretim derlemesi yapılır, alan adı atanmaz, canlı site değişmez.
- `-m` vermezseniz son git commit başlığı, yoksa `tecof theme push` kullanılır. Tecof deposundaki commit mesajı `Yeni ana sayfa [tecof v12 · Ayşe Yılmaz]` biçimindedir.
- CLI derleme bitene kadar bekler (varsayılan 900 saniye; `--wait-timeout` ile değişir, `--no-wait` beklemez). Derleme başarısız olursa son günlük satırlarını basar ve çıkış kodu 1 olur; tüm günlük için `tecof theme logs v12`.
- Değişiklik yoksa sürüm açılmaz: "Değişiklik yok; sürüm açılmadı."
- Gönderilmeyen dosyalar ve sınırlar: [CLI Başvurusu → Yok sayma kuralları](https://tecof-app-dev.vercel.app/cli-reference#yok-sayma-kurallari).

Staged adımını atlayıp doğrudan yayınlamak için:

```bash
tecof theme push --prod -m "Acil düzeltme"
```

`--prod` commit'i doğrudan `main` dalına hızlı ileri yazar; derleme bitince sürüm canlıya çıkar ve tek derleme yapılır. Önizleme adımı olmadığı için yıkıcı sayılır ve onay ister.

---

## 7. Önizleyin

```bash
tecof theme open v12
```

```text
Açılıyor: https://tecof-theme-butik-3k9x2a1b7-tecof.vercel.app/?x-vercel-protection-bypass=***&x-vercel-set-bypass-cookie=true
Bağlantıdaki erişim sırrı maskelendi; tam bağlantı için --show-secret kullanın (yalnız yetkili kişilerle paylaşın).
```

- Sürüm adresleri korumalıdır. CLI erişim sırrı taşıyan bir bağlantı alır ve tarayıcıda tam hâliyle açar; terminalde ve `--json` makbuzunda sır maskelenir. Tam bağlantı için `--show-secret`.
- Sürüm vermezseniz (`tecof theme open`) canlı adres açılır.
- Panelde aynı iş **Sürümler** ekranındaki **Önizle** düğmesidir.

Bağlantıyı paylaşmadan önce [Önizleme bağlantıları](https://tecof-app-dev.vercel.app/versions-and-rollback#onizleme-baglantilari) bölümünü okuyun: içindeki sır, alanın bütün sürüm adreslerini açar.

---

## 8. Canlıya Alın

```bash
tecof theme promote v12
```

```text
v12 thm_66f1a2b3c4d5e6f7a8b9c0d1 için canlıya alınacak. Devam edilsin mi? (e/H) e
✔ v12 canlıda: https://www.butik-ornek.com
```

- Yeniden derleme yapılmaz; alan adları saniyeler içinde v12'yi gösterir.
- `main` dalı v12'nin commit'ine hızlı ileri alınır; bu klasörün yerel tabanı da v12 olur.
- Vercel `main` dalının bu commit'ini bir kez daha derler. İçerik aynıdır, canlı site etkilenmez ve yeni sürüm numarası açılmaz.
- Vercel isteği sıraya aldıysa sonuç `Aktivasyon: pending` olarak görünür; durumu `tecof theme versions v12` ile izleyin.

---

## 9. Gerekirse Geri Alın

```bash
tecof theme rollback          # bir önceki canlı sürüme
tecof theme rollback v10      # daha önce canlıda olmuş belirli bir sürüme
```

```text
thm_66f1a2b3c4d5e6f7a8b9c0d1 bir önceki canlı sürüme geri alınacak. Devam edilsin mi? (e/H) e
✔ Geri alındı; canlı sürüm: v11
! Yeni değişiklikler canlıda değil; ileri almak için `tecof theme promote vM` ya da yeni yayın.
```

Geri alma yalnız daha önce canlıda olmuş sürümlere yapılır, anlıktır ve `main` dalına dokunmaz. Geri almadan sonra yeni yayınların nasıl canlıya çıktığını [Geri Almadan Sonra Yayınlar](https://tecof-app-dev.vercel.app/versions-and-rollback#geri-almadan-sonra-yayinlar) anlatır.

Sürüm geçmişi:

```bash
tecof theme versions
```

```text
ref  status  target      live  source  created           message                          url
---  ------  ----------  ----  ------  ----------------  -------------------------------  ----------------------------------------------------
v12  ready   staged            cli     2026-10-11 09:41  Yeni ana sayfa                   https://tecof-theme-butik-3k9x2a1b7-tecof.vercel.app
v11  ready   production  ●     ide     2026-10-10 17:05  Footer bağlantıları güncellendi  https://tecof-theme-butik-8h2m4q6r1-tecof.vercel.app
v10  ready   staged            cli     2026-10-09 14:22  Ürün kartı                       https://tecof-theme-butik-5t7w9y2c4-tecof.vercel.app
```

---

## Başkası Temayı Değiştirdiyse (base-moved)

Siz çalışırken `main` dalına başka bir değişiklik gidebilir: bir Cloud IDE kaydı, bir AI işi, başka bir geliştiricinin push'u ya da CI. Staged push eski tabanınızın üstüne kurulur ve başarılı olur; fark canlıya alma anında ortaya çıkar:

```text
$ tecof theme promote v12
✖ main ilerledi (şu an 9f8e7d6); bu push eski tabana dayanıyor (base-moved).
```

Çıkış kodu 4'tür; `--json` makbuzunda `next.action` `pull` olur. Canlı siteye ve `main` dalına dokunulmaz. v12'nin tabanı değişmeyeceği için aynı sürümü yeniden denemek işe yaramaz: değişikliklerinizi güncel `main` üstüne taşıyıp yeni bir sürüm açın.

1. `tecof status` ile tabanınızı ve yerel değişikliklerinizi görün.
2. `tecof theme pull` güncel `main` dalını indirir. Birleştirme yapmaz: yerelde değiştirdiğiniz bir dosya `main`dekinden farklıysa hiçbir şey yazmadan durur, dosyaları nedenleriyle listeler ve çıkış kodu 4 olur.
3. Değişikliklerinizi güncel `main` üstüne uygulayın (aşağıdaki örnek), `tecof theme push` ile yeni sürümü (ör. v13) açın, önizleyin ve `tecof theme promote v13` ile canlıya alın.

`--prod` push'ta aynı denetim commit anında yapılır: `main` ilerlediyse sürüm açılmaz, çözüm aynıdır.

**Örnek: yerel git ile güncelleme.** Değişiklikleri birleştirmenin en kolay yolu klasörü kendi git deponuz olarak tutmaktır; `.git/` hiçbir zaman Tecof'a gönderilmez. Aşağıdaki örnek, klasörü `tecof theme init` sonrasında git deposu yaptığınızı, her `pull`dan sonra commit'lediğinizi ve değişikliklerinizin henüz commit'lenmediğini varsayar:

```bash
git stash -u                      # değişikliklerinizi kenara alın; klasör yerel tabana döner
tecof theme pull                  # güncel main'i indirir
git add -A && git commit -m "tecof: main güncellendi"
git stash pop                     # değişikliklerinizi yeniden uygulayın; çakışma varsa çözün
tecof theme push -m "Yeni ana sayfa (güncel main üstüne)"
```

Yerel değişikliklerinizi bırakmayı göze alıyorsanız `tecof theme pull --force` onların üzerine yazar ve uzakta silinmiş dosyaları siler.

---

## Sonraki Adımlar

- [Sürümler, Canlıya Alma ve Geri Alma](https://tecof-app-dev.vercel.app/versions-and-rollback) — durumlar, önizleme bağlantıları, canlıya alma ve geri alma kuralları
- [Güvenlik ve CI](https://tecof-app-dev.vercel.app/dev-security) — CI token'ları ve GitHub Actions ile otomatik yayın
- [CLI Başvurusu](https://tecof-app-dev.vercel.app/cli-reference) — tüm komutlar, çıkış kodları ve makbuzlar

---

# Tema Mimarisi ve Runtime

> Tecof temalarının yapısı — Next.js runtime akışı, ortam değişkenleri, temel dosyalar, bileşen kaydı (registry), vitrin API’leri ve analytics entegrasyonu.
>
> Kaynak: https://tecof-app-dev.vercel.app/storefronts · Bölüm: Tema geliştirme · Son güncelleme: 2018-10-20

Tecof temaları Next.js App Router, `@tecof/theme-editor` ve backend’in `/api/store/*` katmanı üzerine kuruludur. Tema sayfa JSON’unu backend’den alır, `TecofRender` ile render eder; panel aynı sayfayı temanın editör rotasında `TecofEditor` ile düzenletir. Yeni bir tema genelde `tecof-theme-core`’dan türetilir ve [CLI ile](https://tecof-app-dev.vercel.app/theme-quickstart) geliştirilip yayınlanır.

---

## Tema Runtime Akışı

```mermaid
sequenceDiagram
    participant Theme as Next.js Theme
    participant StoreAPI as /api/store
    participant Backend as Tecof Backend
    participant Editor as Tecof Editor

    Theme->>StoreAPI: POST /render?themeId&locale
    StoreAPI->>Backend: merchant + theme + slug çözümle
    Backend-->>Theme: publishedData + CMS data
    Theme->>Theme: TecofRender(data, config)
    Editor->>StoreAPI: GET /editor/:pageId
    Editor->>StoreAPI: PUT /editor/:pageId
```

Tema tarafındaki temel dosyalar:

| Dosya | Görev |
| :--- | :--- |
| `lib/api/store.ts` | Sayfa, merchant info ve sayfa listesi fetch fonksiyonları |
| `lib/api/ecommerce.ts` | Ürün, sepet, checkout, müşteri hesabı ve push API helper'ları |
| `app/components.tsx` | Tema bileşen registry'si |
| `app/editor-config.tsx` | Editor config ve component map |
| `components/RenderClient.tsx` | `TecofRender` sarmalı |
| `components/global/TecofAnalyticsWrapper.tsx` | Analytics runtime script enjeksiyonu |

---

## Zorunlu Ortam Değişkenleri

```dotenv
NEXT_PUBLIC_BASE_URL=https://api.tecof.com
NEXT_PUBLIC_CDN_URL=https://cdn.tecof.com
NEXT_PUBLIC_MERCHANT_SECRET_KEY=merchant_secret_key
NEXT_PUBLIC_THEME_ID=merchant_theme_id
```

`tecof theme dev` bu değerleri mağazanızdan alıp `.env.local` dosyasına yazar. `NEXT_PUBLIC_MERCHANT_SECRET_KEY` public bundle içinde yer alır. Bu nedenle canlı storefront için uygundur, fakat editör yazma işlemlerinde tek başına yeterli değildir; backend `PUT /api/store/editor/:id` için JWT/team doğrulaması da ister.

---

## Tecof Studio entegrasyonu

Tema üç noktada `@tecof/theme-editor` kullanır: tüm uygulamayı saran `TecofProvider`, panelin iframe ile açtığı editör rotası (`app/editor/[id]/page.tsx` → `TecofEditor`, `?token=` ile gelen JWT `accessToken` olur) ve yayın sayfalarındaki `TecofRender`. Kurulum, prop’lar ve örnek kodlar: [Tecof Studio’ya giriş](https://tecof-app-dev.vercel.app/theme-editor).

---

## Bileşen kaydı (registry)

Her tema bileşeni registry'de bir key ile yayınlanır. Kaydedilmiş sayfa verisindeki `content[].type` değeri bu key ile eşleşmelidir.

```tsx
import { Header } from "@/components/sections/Header";
import { HeroSection } from "@/components/sections/HeroSection";

export const components = {
  Header,
  HeroSection,
};
```

Bileşen config'i en az şu yapıyı taşımalıdır:

```tsx
export const HeroSection = {
  label: "Hero",
  fields: {
    title: { type: "text", label: "Başlık" },
  },
  defaultProps: {
    title: "Yeni başlık",
  },
  // className kök elemana basılmalı; yoksa bileşen editörde seçilemez
  render: (props: any) => <section className={props.className}>{props.title}</section>,
};
```

Alan tiplerinin tamamı [Alanlar](https://tecof-app-dev.vercel.app/editor-fields), bileşen yapılandırmasının tamamı (`defineSection`, slotlar, kök `className` sözleşmesi) [Bileşen yapılandırması](https://tecof-app-dev.vercel.app/editor-components) sayfasındadır.

---

## Public API'ler

Tema oluştururken verilmesi gereken temel public API yüzeyi:

| Amaç | Endpoint |
| :--- | :--- |
| Yayındaki sayfayı render et | `POST /api/store/render?themeId=:themeId&locale=:locale` |
| Editör için sayfa oku | `GET /api/store/editor/:pageId` |
| Editör için sayfa kaydet | `PUT /api/store/editor/:pageId` |
| Merchant dil/logo/script bilgisi | `GET /api/store/merchant-info` |
| Link alanı için sayfa listesi | `GET /api/store/pages` |
| Upload | `POST /api/store/upload` |
| Medya listesi | `GET /api/store/uploads` |
| Otomatik çeviri | `POST /api/store/translate` |
| CMS canlı içerik | `POST /api/store/cms/collections/:slug/items` |
| E-ticaret ürün listesi | `GET /api/store/ecommerce/products` |
| Checkout session | `POST /api/store/ecommerce/checkout-session` |

Tam tablo için [Public API Referansı](https://tecof-app-dev.vercel.app/public-apis) sayfasına bakın.

---

## Analytics Entegrasyonu

`tecof-theme-core`, `TecofAnalyticsWrapper` ile backend’in servis ettiği runtime betiğini yükler (betik ve olay adresi `NEXT_PUBLIC_BASE_URL`’den türetilir). Aynı işi bir pakette isterseniz [`@tecof/analytics`](https://tecof-app-dev.vercel.app/packages#tecofanalytics) `TecofAnalyticsProvider` ve `useTecofAnalytics().track()` sunar:

```tsx
<TecofAnalyticsWrapper merchantId={merchantId} />
```

Script kaynağı:

```text
/public/analytics/client.js
```

Event endpoint'i:

```text
POST /api/analytics/event
```

Varsayılan event tipleri `pageview`, `web-vital`, `cart_add`, `cart_remove` ve `checkout_start` olarak doğrulanmıştır. Tema bileşenleri sepet ve checkout etkileşimlerinde `trackCartAdd`, `trackCartRemove`, `trackCheckoutStart` helper'larını çağırabilir.

---

## Tema Oluşturma Kontrol Listesi

1. `NEXT_PUBLIC_BASE_URL`, `NEXT_PUBLIC_MERCHANT_SECRET_KEY`, `NEXT_PUBLIC_THEME_ID` değerlerini tanımla.
2. `TecofProvider` ile app'i sar.
3. `app/components.tsx` içinde tüm render edilebilir component key'lerini kaydet.
4. `app/editor-config.tsx` içinde component config'i export et.
5. Dynamic route'larda `getPageData(slug, locale, showDraftData)` ile `/api/store/render` çağır.
6. Public sayfada `TecofRender`, editör sayfasında `TecofEditor` kullan; ikisi aynı `editorConfig`’i paylaşsın ve her bileşen `className`’i kökte bassın.
7. E-ticaret componentleri için `lib/api/ecommerce.ts` helper'larını kullan.
8. Analytics için `TecofAnalyticsWrapper` ve checkout event helper'larını ekle.

---

# Tecof Studio’ya Giriş (@tecof/theme-editor)

> @tecof/theme-editor ile Tecof Studio: kurulum, TecofProvider, editör ve yayın sayfası, doküman veri modeli ve paketin alt giriş noktaları.
>
> Kaynak: https://tecof-app-dev.vercel.app/theme-editor · Bölüm: Tema geliştirme · Son güncelleme: 2018-10-20

`@tecof/theme-editor`, Tecof temalarının görsel sayfa editörünü (**Tecof Studio**), kaydedilmiş sayfaları yayınlayan renderer’ı, editör alanlarını (field factory’ler), API istemcisini, stil ve tema motorunu tek pakette toplar. Bu bölüm paketin güncel sürümünü (`0.0.96`) kaynak koduna göre anlatır; tip tanımlarını doğrudan okumak için [doküman MCP’sinin](https://tecof-app-dev.vercel.app/ai-docs) `read_type_definition` aracını kullanabilirsiniz.

> [!NOTE] Bu bölüm eski editör dokümantasyon sitesinin yerini alır
> Daha önce `tecof-theme-editor` deposundaki ayrı sitede (playground) duran içerik buraya taşındı ve kaynak koda göre güncellendi. Paketin README’si artık yalnız kurulum ve kısa kullanım içerir.

## Neler sunar

| Parça | Ne yapar |
| :--- | :--- |
| `TecofEditor` / `TecofStudio` | iframe kanvaslı görsel editör: sürükle-bırak, katmanlar, Inspector, stil ve tema panelleri, komut paleti, geri al/yinele, otomatik kayıt |
| `TecofRender` | Kaydedilmiş sayfayı yayında render eder; stil CSS’ini, tema değişkenlerini ve fontları kendisi basar |
| `create*Field` | Çok dilli metin, zengin metin, medya, bağlantı, renk, kod, ikon, tekrar eden satırlar, CMS ve e-ticaret seçicileri |
| `defineSection` / `defineElement`, `<Slot>`, `<TecofRoot>` | Tema bileşeni yazarken slot, varsayılan çocuk ve kök `className` sözleşmesini otomatikleştirir |
| `TecofApiClient` | Sayfa, medya, çeviri, CMS, ortak bileşen ve e-ticaret uçları için istemci |
| `@tecof/theme-editor/email` | Pazarlama e-postası doküman modeli ve tablo tabanlı HTML render’ı |

Editör ile yayın aynı `StudioConfig` nesnesini ve aynı sayfa veri modelini kullanır. Editörde gördüğünüz bileşenler yayında yeniden yorumlanmaz; aynı registry üzerinden render edilir.

```mermaid
flowchart LR
    A["StudioConfig: bileşenler ve alanlar"] --> B["TecofEditor: draftData yazar"]
    B -->|"PUT /api/store/editor/:id"| C[("Tecof backend")]
    C -->|"panelde yayınla"| D["publishedData"]
    D -->|"POST /api/store/render"| E["TecofRender: yayın sayfası"]
    A --> E
```

Editör **yalnız taslağı** (`draftData`) yazar. Yayınlama (taslağın `publishedData`’ya kopyalanması) panelin ve backend’in işidir; paket `publishedData`’ya hiç dokunmaz. iframe’e gönderilen `puck:publish` mesajı da yalnız taslak kaydı tetikler.

## Gereksinimler

| Gereksinim | Sürüm | Not |
| :--- | :--- | :--- |
| `react`, `react-dom` | `^18 \|\| ^19` | Peer bağımlılık |
| `@tiptap/core`, `@tiptap/pm`, `@tiptap/react` | `^3` | Zengin metin alanı (EditorField) için peer bağımlılık |
| `lucide-react` | `>=0.408.0 <2` | İkonlar; peer bağımlılık |
| Next.js | App Router önerilir | Editör ve renderer’ı içeren dosyalar istemci bileşenidir (`"use client"`) |

Paket derlemesi her JS dosyasının başına `'use client'` ekler; sunucu bileşeninden doğrudan içe aktarabilirsiniz ama editörü saran kendi bileşeninizi de istemci bileşeni yapın.

## Kurulum

```bash npm2yarn
npm install @tecof/theme-editor @tiptap/core @tiptap/pm @tiptap/react lucide-react
```

Editör arayüzü ve alanların stilleri tek CSS dosyasındadır. Editörün çalıştığı layout’ta bir kez içe aktarın:

```tsx title="app/editor/layout.tsx"
import "@tecof/theme-editor/styles.css";
```

> [!TIP] Sürüm aralığı
> `0.0.x` sürümlerde `^0.0.96` yalnız `0.0.96`’yı kabul eder. Yeni sürüme geçmek için `package.json`’daki sürümü elle değiştirin. Güncel sürüm: [Paketler](https://tecof-app-dev.vercel.app/packages#tecoftheme-editor).

## Ortam değişkenleri

Tecof temaları aşağıdaki genel değişkenlerle çalışır. `tecof theme dev` bunları `.env.local` dosyasına kendisi yazar ([Tema hızlı başlangıç](https://tecof-app-dev.vercel.app/theme-quickstart#5-yerelde-gelistirin)).

```dotenv title=".env.local"
NEXT_PUBLIC_BASE_URL=https://api.tecof.com
NEXT_PUBLIC_CDN_URL=https://cdn.tecof.com
NEXT_PUBLIC_MERCHANT_SECRET_KEY=mağazanın-vitrin-anahtarı
NEXT_PUBLIC_THEME_ID=tema-kimliği
```

Vitrin anahtarı (`x-secret-key`) genel bir değerdir; tarayıcı paketine girer. Bu yüzden backend editörün yazma uçlarında ayrıca kullanıcı JWT’si ister (aşağıdaki `accessToken`).

## Provider

`TecofProvider` bir `TecofApiClient` oluşturup alt bileşenlere taşır. Editör, alanlar (dil listesi, medya kütüphanesi, sayfa seçici) ve CMS’e bağlı tekrar eden slotlar bu bağlamı kullanır.

```tsx title="components/TecofProviderWrapper.tsx"
"use client";

import { TecofProvider } from "@tecof/theme-editor";

export function TecofProviderWrapper({ children }: { children: React.ReactNode }) {
  return (
    <TecofProvider
      apiUrl={process.env.NEXT_PUBLIC_BASE_URL!}
      secretKey={process.env.NEXT_PUBLIC_MERCHANT_SECRET_KEY!}
      cdnUrl={process.env.NEXT_PUBLIC_CDN_URL}
      themeId={process.env.NEXT_PUBLIC_THEME_ID}
    >
      {children}
    </TecofProvider>
  );
}
```

| Prop | Tip | Açıklama |
| :--- | :--- | :--- |
| `apiUrl` | `string` | Tecof API adresi (sondaki `/` temizlenir) |
| `secretKey` | `string` | Mağazanın vitrin anahtarı; her istekte `x-secret-key` başlığı |
| `cdnUrl` | `string?` | Medya adresleri için CDN kökü; verilmezse `apiUrl` |
| `themeId` | `string?` | Çok temalı mağazada sayfa okuma/kaydetme isteklerinin doğru temaya gitmesi için |
| `children` | `ReactNode` | — |

Bileşen içinden `useTecof()` ile `{ apiClient, apiUrl, secretKey, cdnUrl, themeId }` okunur; provider dışında çağrılırsa hata fırlatır.

## İlk entegrasyon: üç dosya

### 1. Bileşen yapılandırması

```tsx title="app/editor-config.tsx"
"use client";

import { defineElement, defineSection, type StudioConfig } from "@tecof/theme-editor";

const Button = defineElement({
  label: "Buton",
  fields: { text: { type: "text", label: "Metin" } },
  defaultProps: { text: "Keşfet" },
  render: (p) => <a className="rounded-full bg-black px-5 py-2.5 text-white">{p.text}</a>,
});

const Hero = defineSection({
  label: "Hero",
  category: "sections",
  fields: { title: { type: "text", label: "Başlık" } },
  slots: {
    actions: { label: "Butonlar", layout: "row-wrap", gap: "md", default: ["Button"] },
  },
  defaultProps: { title: "Yeni sezon" },
  render: (p, slots) => (
    <section className="py-24 text-center">
      <h1 className="text-5xl font-semibold">{p.title}</h1>
      <div className="mt-8 flex justify-center">{slots.actions}</div>
    </section>
  ),
});

export const editorConfig: StudioConfig = {
  categories: {
    sections: { title: "Bölümler", components: ["Hero"] },
    elements: { title: "Elementler", components: ["Button"] },
  },
  components: { Hero, Button },
};
```

`defineSection` slot alanlarını, varsayılan çocukları ve kökteki `className` sözleşmesini sizin yerinize kurar; ayrıntılar [Bileşen yapılandırması](https://tecof-app-dev.vercel.app/editor-components) sayfasında. Gerçek temalarda metinler genelde çok dilli alanlarla (`createLanguageField`, değer `[{ code, value }]`) tutulur: [Alanlar](https://tecof-app-dev.vercel.app/editor-fields#languagefield-cok-dilli-metin).

### 2. Editör sayfası

Tecof paneli tema editörünü iframe içinde `/<editör rotası>/<pageId>?token=<JWT>` biçiminde açar. Tema bu token’ı `accessToken` olarak editöre verir.

```tsx title="app/editor/[id]/page.tsx"
import EditorClient from "@/components/EditorClient";

export default async function EditorPage({
  params,
  searchParams,
}: {
  params: Promise<{ id: string }>;
  searchParams: Promise<{ token?: string }>;
}) {
  const { id } = await params;
  const { token } = await searchParams;
  return <EditorClient pageId={id} accessToken={token} />;
}
```

```tsx title="components/EditorClient.tsx"
"use client";

import { TecofEditor } from "@tecof/theme-editor";
import { editorConfig } from "@/app/editor-config";

export default function EditorClient({ pageId, accessToken }: { pageId: string; accessToken?: string }) {
  return (
    <TecofEditor
      pageId={pageId}
      config={editorConfig}
      accessToken={accessToken}
      hostOrigin="https://app.tecof.com"
    />
  );
}
```

`TecofEditor`, `TecofStudio`’nun diğer adıdır; ikisi aynı editörü açar. Tüm prop’lar: [Studio arayüzü](https://tecof-app-dev.vercel.app/editor-studio#tecofeditor-proplari).

### 3. Yayın sayfası

`TecofRender` veri getirmez. Sayfayı sunucuda çekip renderer’a verin; editörle **aynı** `editorConfig`’i kullanın.

```tsx title="components/RenderClient.tsx"
"use client";

import { TecofRender, type PuckPageData } from "@tecof/theme-editor";
import { editorConfig } from "@/app/editor-config";

export function RenderClient({ data, cmsData }: { data: PuckPageData; cmsData?: Record<string, unknown> | null }) {
  return <TecofRender data={data} config={editorConfig} cmsData={cmsData} />;
}
```

`tecof-theme-core` sayfa verisini `POST /api/store/render` ile alır ve taslak önizlemede (`?showDraftData`) `draftData`, yayında `publishedData` kullanır. Ayrıntı: [Yayın render’ı](https://tecof-app-dev.vercel.app/editor-render) ve [Tema mimarisi](https://tecof-app-dev.vercel.app/storefronts).

## Veri modeli

Editörün kaydettiği doküman Puck uyumlu bir şekildir (`PuckPageData`):

```ts
interface PuckPageData {
  content: Array<{ type: string; props: { id: string } & Record<string, unknown> }>; // kök düğümler
  root: { props: Record<string, unknown> };                                          // sayfa geneli (tema, şema sürümü…)
  zones: Record<string, Array<{ type: string; props: { id: string } & Record<string, unknown> }>>;
}
```

- Kök düğümler `content` dizisinde, iç içe düğümler `zones` nesnesindedir. Zone anahtarı her zaman `parentId:slotAdı` biçimindedir.
- `props.id` düğümün kimliğidir; kopyalama, çoğaltma, yapıştırma ve şablon ekleme her zaman **yeni** id üretir.
- `zones` nesnesindeki anahtar sırası görsel sırayı temsil etmez; kardeş sırası zone dizisinin kendi sırasıdır.
- Bir düğüm silinince alt zone ağacı da temizlenir.
- `_` ile başlayan prop’lar motora ayrılmıştır, bileşen prop’u olarak kullanmayın: `_tecofStyles`, `_tecofTheme`, `_interactions`, `_startHidden`, `_locked`, `_hidden`, `_symbolOverrides`, `_variant`, `_schemaVersion`, `_layerName`, `_tecofStyleSync`.
- Aynı `sharedComponentId` değerini taşıyan düğümler bir **ortak bileşenin** (symbol) örnekleridir: birinde yapılan değişiklik diğerlerine canlı yansır; örneğe özel alanlar `_symbolOverrides` ile ayrılır.

## Alt giriş noktaları

| Giriş | İçerik |
| :--- | :--- |
| `@tecof/theme-editor` | Editör, renderer, alanlar, API istemcisi, stil/tema yardımcıları, tipler |
| `@tecof/theme-editor/styles.css` | Editör ve alan stilleri (`./puck.css` ve `./dist/styles.css` eski takma adlardır) |
| `@tecof/theme-editor/under-construction` | `UnderConstruction` bileşeni (`title`, `description`, `subtitle?`, `logoUrl?`, `accentColor?`) |
| `@tecof/theme-editor/email` | E-posta doküman modeli: `createEmailDocument`, `createEmailBlock`, `validateEmailDocument`, `renderEmailHtml` |

E-posta modeli sürümlü bir blok dokümanıdır (`kind: "tecof-email"`, `version: 1`). Yaprak bloklar `logo, heading, text, button, image, divider, spacer, social, coupon, product, video, footer, menu, html`; kap bloklar `section` (yalnız en üst düzey) ve `columns` (`layout`: `1`, `1:1`, `1:1:1`, `1:1:1:1`, `1:2`, `2:1`, `1:3`, `3:1`; yalnız yaprak alır). Doğruluk kaynağı backend derleyicisidir; paket aynı sözleşmeyi taşır.

```ts
import { createEmailBlock, createEmailDocument, renderEmailHtml, validateEmailDocument } from "@tecof/theme-editor/email";

const doc = createEmailDocument({
  blocks: [
    createEmailBlock("columns", { layout: "1:2", columns: [[createEmailBlock("image")], [createEmailBlock("text")]] }),
    createEmailBlock("footer"),
  ],
});
validateEmailDocument(doc); // [] → geçerli
const html = renderEmailHtml(doc, { mergeData: {}, preserveMergeTags: false });
```

## Sonraki adımlar

- [Studio arayüzü](https://tecof-app-dev.vercel.app/editor-studio): paneller, modlar, `TecofEditor` prop’ları.
- [Bileşen yapılandırması](https://tecof-app-dev.vercel.app/editor-components): `ComponentConfig`, `defineSection`, slot sözleşmesi.
- [Alanlar](https://tecof-app-dev.vercel.app/editor-fields): tüm field factory’ler ve değer biçimleri.
- [Stil editörü](https://tecof-app-dev.vercel.app/editor-styles): token modeli, masaüstü-öncelikli kırılımlar, canlı önizleme.

---

# Studio Arayüzü

> Tecof Studio arayüzü — kanvas, paneller, Inspector sekmeleri, düzenleme/önizleme modları, otomatik kayıt, canlı katılım ve TecofEditor prop’larının tamamı.
>
> Kaynak: https://tecof-app-dev.vercel.app/editor-studio · Bölüm: Tema geliştirme · Son güncelleme: 2018-10-20

Tecof Studio, sayfayı gerçek tasarım genişliğinde bir iframe kanvasında gösterir; bileşenleri sürükle-bırak ile ekler, Inspector’dan düzenler ve taslağı backend’e kaydeder. Bu sayfa arayüzün parçalarını ve `TecofEditor` prop’larını anlatır.

## Arayüz

| Bölge | Ne yapar |
| :--- | :--- |
| Üst çubuk | Geri al / yinele, Düzenleme ↔ Önizleme modu, Masaüstü / Tablet / Mobil görünüm ve masaüstü genişliği, düzenlenen dil, kılavuz ızgarası (`G`), boyutlandırma (`R`) ve boşluk tutamaçları (`B`), yardım, sol/sağ paneli aç-kapa |
| Sol panel | Bileşen kütüphanesi (kategoriler, varsa önizleme görselleri), sayfa şablonları ve katman ağacı |
| Kanvas | Host CSS’inden yalıtılmış iframe; seçim, hover, sürükleme ve satır içi metin düzenleme |
| Sağ panel (Inspector) | Seçim yokken **Sayfa** ve **Tema** sekmeleri; bir düğüm seçiliyken **İçerik**, **Stil** ve **Etkileşimler** |
| Komut paleti (`⌘K`) | Eylemler, bileşen ekleme ve (yapılandırıldıysa) AI ile bölüm üretme |

### Kanvas

- **Gerçek genişlikte kanvas.** Masaüstü görünümü seçilen tasarım genişliğinde (1280 / 1440 / 1680 / 1920 px ya da özel; varsayılan 1440) çizilir ve alana sığması için ölçeklenir. Tablet 768, mobil 375 px’tir. Üst çubuktaki çip etkin genişliği ve ölçek yüzdesini gösterir.
- **Düzenleme modu.** Tıklama düğümü seçer, çift tıklama satır içi metin düzenlemeyi başlatır, sürükleme düğümü taşır. Bağlantı, buton ve formların tarayıcı davranışı (gezinme, gönderme) bilerek engellenir.
- **Önizleme modu.** Editör çerçeveleri gizlenir; sayfa ziyaretçinin gördüğü gibi çalışır.
- **Satır içi düzenleme.** Metne çift tıklayın; `Enter` kaydeder, `Esc` vazgeçer. Bileşenler düzenlenebilir metni `data-tecof-prop="propAdı"` (çok dilli için ek olarak `data-tecof-lang`) ile işaretleyebilir; işaret yoksa metin eşleştirmesine düşülür.
- **Kanvastan panele odak.** Bir öğeye tıklamak Inspector’da İçerik sekmesini açar ve ilgili alana kaydırıp kısa bir vurgu yapar.
- **Boşluk görünümü.** Hover’da padding (yeşil) ve margin (amber) devtools tarzında gösterilir.
- **Dayanıklılık.** Render hatası veren bir bileşen kanvası düşürmez; düğüm bazlı error boundary yalnız o düğümü izole eder ve prop düzelince kendiliğinden toparlar.
- **Dokunmatik sürükle-bırak.** Tablet ve telefonda bir bileşene, palet bloğuna ya da katman satırına ~300 ms basılı tutup sürükleyin; fare ise HTML5 sürükle-bırak yolunu kullanır.

### Array kartları (`data-tecof-item`)

Bir bileşen `type: "array"` prop’unu kendi render’ında map’liyorsa (slot kullanmadan) kartları editöre tanıtabilir:

```tsx
{services.map((s, i) => (
  <li key={i} data-tecof-item={`services:${i}`}>
    <h3 data-tecof-item-prop="title">{s.title}</h3>
    <p data-tecof-item-prop="description">{s.description}</p>
  </li>
))}
```

Kart hover çerçevesi alır, tıklama Inspector’da o satırı açar, çift tıklama satır alanını yerinde düzenler (tek geri al adımı). Satır kayıt anında silinmiş ya da taşınmışsa yazım sessizce iptal edilir; yanlış satıra yazılmaz.

### Etkileşimli kontroller (`registerOverlayPortal`)

Düzenleme modunda kanvas her tıklamayı editöre yönlendirir. Sekme başlığı, slider oku ya da akordeon gibi kontrollerin düzenlerken de çalışması gerekiyorsa elemanı `puck.registerOverlayPortal` ile işaretleyin (React ref callback’i olarak, `null`’a dayanıklı):

```tsx
render: ({ puck, tabs }) => (
  <div>
    {tabs.map((tab, i) => (
      <button key={i} ref={puck.registerOverlayPortal} onClick={() => setActive(i)}>
        {tab.title}
      </button>
    ))}
  </div>
)
```

İşaretli eleman ve alt elemanları seçim, çift tıklama ve sürükleme işleyicilerinden muaf tutulur. `router.push` gibi JS yönlendirmeleri tarayıcı davranışı olmadığı için engellenemez; bu tür bileşenler `editMode` / `puck.isEditing` değerine bakmalıdır.

| `puck` alanı | Tip | Açıklama |
| :--- | :--- | :--- |
| `registerOverlayPortal` | `(el: HTMLElement \| null) => () => void` | Elemanı düzenleme modunda canlı bırakır |
| `isEditing` | `boolean` | Düzenleme modunda mı (`editMode` prop’u ile aynı) |
| `dragRef` | `(el: HTMLElement \| null) => void` | Yalnız `inline` bileşenlerde sürükleme tutamacı |
| `renderDropZone` | `(opts) => ReactNode` | Slot’u elle çizmek için (bkz. [Slotlar](https://tecof-app-dev.vercel.app/editor-slots)) |

### Inspector

- **İçerik.** Bileşenin alanları. Kapsayıcı bir düğüm seçildiğinde bölümün kendi alanlarının yanında tüm alt elementlerin alanları da girintili, katlanabilir gruplar hâlinde listelenir. Bileşen `fieldsGroups` tanımlarsa alanlar akordeon gruplarına ayrılır. `variants` tanımlıysa varyant çipleri görünür.
- **Stil.** Görsel stil editörü: kırılım ve durum bazlı token’lar, sayfalar arası stil uygulama. Bkz. [Stil editörü](https://tecof-app-dev.vercel.app/editor-styles).
- **Etkileşimler.** Tetikleyici → eylem kuralları (`click` / `hover` → `scrollTo`, `toggleClass`, `show`, `hide`, `toggle`). Kurallar düğümün `_interactions` prop’unda saklanır ve yayında `TecofRender` tarafından çalıştırılır.
- **Sayfa / Tema.** Seçim yokken sayfa geneli (`config.root.fields`) ve canlı tema düzenleyici. Bkz. [Canlı tema](https://tecof-app-dev.vercel.app/editor-theme).

### Katmanlar

Katman ağacında her satırda kilit ve gizle düğmeleri vardır (`_locked` / `_hidden`). Kilitli düğüm seçilebilir ama taşınamaz, silinemez ve alanları salt okunur olur. Gizli düğüm editörde soluk görünür; önizlemede ve yayında hiç render edilmez.

### Ortak bileşenler (symbol)

Bir bölüm ortak bileşene dönüştürülünce aynı `sharedComponentId` değerini taşıyan tüm örnekler tek kaynaktan beslenir: bir örnekte yapılan değişiklik diğerlerine canlı yansır. Örneğe özel alanlar `_symbolOverrides` ile ayrılır. Kayıtta backend örneği referansa indirger ve okurken asıl kayıttan çözer; ortak bileşen silinirken referanslar önce sayfalara gerçek içerik olarak yazılır, içerik kaybolmaz. Ortak bileşenler kanvasta mor rozetle işaretlenir.

### Canlı katılım

Aynı sayfayı aynı anda açan başka bir ekip üyesi üst çubukta görünür. Amaç eşzamanlı düzenleme değil **çakışma uyarısıdır**: iki kişi aynı taslağı kaydederse son kaydeden diğerinin işini ezer. Bağlantı yalnız editörde ve `accessToken` varken açılır; kimlik bilgisi sunucuda token’dan çözülür.

### AI ile bölüm üretme

`config.ai` tanımlıysa komut paletinde **AI ile bölüm üret** görünür. Kütüphane bileşen kataloğundan istemi kurar ve modelin yanıtını savunmacı biçimde doğrular (uydurma tip reddi, id temizliği, derinlik sınırı); LLM çağrısını host yapar:

```ts
export const editorConfig: StudioConfig = {
  components,
  ai: {
    complete: async ({ system, prompt }) => {
      const res = await fetch("/api/ai/section", { method: "POST", body: JSON.stringify({ system, prompt }) });
      return res.text(); // modelin ham metni: JSON bölüm yükünü içermeli
    },
  },
};
```

`config.ai` yoksa AI arayüzü hiç görünmez.

### Revizyon önizlemesi

Editör adresine `?revision=<id>` eklenirse taslak yerine o revizyonun anlık görüntüsü açılır ve editör **salt okunur** olur (kaydetme ve içe aktarma kilitlenir; iframe’de kayıt isteği `puck:saveError` döner).

## TecofEditor prop’ları

| Prop | Tip | Varsayılan | Açıklama |
| :--- | :--- | :--- | :--- |
| `pageId` | `string` | zorunlu | Düzenlenecek sayfanın backend kimliği |
| `config` | `StudioConfig` | zorunlu | Yayınla aynı bileşen kaydı |
| `accessToken` | `string?` | — | Kayıt ve yazma isteklerinde `Authorization` başlığı (panelin verdiği JWT) |
| `hostOrigin` | `string?` | `'*'` | iframe’e gömülü kullanımda izin verilen üst pencere origin’i; gelen ve giden `postMessage` bu origin’e kısıtlanır |
| `autoSave` | `boolean?` | `false` | Düzenlemeler durulunca taslağı otomatik kaydet |
| `autoSaveDelay` | `number?` | `2000` | Otomatik kayıt bekleme süresi (ms) |
| `warnOnUnsavedChanges` | `boolean?` | `true` | Kaydedilmemiş değişiklik varken tarayıcının yerel `beforeunload` uyarısı |
| `onChange` | `(data) => void` | — | ~300 ms debounce’lu değişiklik bildirimi |
| `onSave` | `(data) => void` | — | Başarılı taslak kaydından sonra |
| `onLanguageChange` | `(code: string) => void` | — | Aktif düzenleme dili ilk çözüldüğünde ve her değiştiğinde |
| `panelUrl` | `string?` | `https://app.tecof.com` | Alanlardaki “Panelde yönet / Panelde ekle” bağlantılarının kökü (yeni sekmede açılır) |
| `className` | `string?` | — | Studio kök elemanına ek sınıf |
| `overrides`, `plugins` | — | — | Ayrılmış; şu an kullanılmıyor |

`onLanguageChange` sözleşmesi: merchant bilgisi gelmeden boş dil (`""`) gönderilmez, aynı kod art arda iki kez gönderilmez ve her render’da yeni fonksiyon verseniz de ek çağrı olmaz. Tema bunu kendi i18n sağlayıcısına bağlayarak kanvas içeriğini o dilde gösterebilir; editör arayüzü Türkçe kalır. Kanvastaki bileşenler aynı dili `useActiveLanguage()` ile okuyabilir (Studio dışında `null` döner).

```tsx title="components/EditorClient.tsx"
"use client";

import { useState } from "react";
import { NextIntlClientProvider, useMessages } from "next-intl";
import { TecofEditor } from "@tecof/theme-editor";
import { editorConfig } from "@/app/editor-config";

export default function EditorClient({ pageId, accessToken }: { pageId: string; accessToken?: string }) {
  const messages = useMessages();
  const [canvasLocale, setCanvasLocale] = useState("tr");
  return (
    <NextIntlClientProvider locale={canvasLocale} messages={messages}>
      <TecofEditor pageId={pageId} config={editorConfig} accessToken={accessToken} onLanguageChange={setCanvasLocale} />
    </NextIntlClientProvider>
  );
}
```

## Pencereler ve onaylar

Editördeki her pencere (ayarlar, yardım, bölüm ekleme, seçiciler, onaylar) aynı kabuğu kullanır: `StudioDrawer` (Radix Dialog, `modal={false}`; içinden açılan renk/ikon/CMS popover’ları tıklanabilir kalır). Host eklentileri aynı kabuğu ve onay kuyruğunu kullanabilir:

```tsx
import { StudioDrawer, studioDialog } from "@tecof/theme-editor";

const ok = await studioDialog.confirm({
  title: "Ortak bileşeni sil",
  description: "Bu bileşeni kullanan tüm sayfalar etkilenir.",
  confirmLabel: "Sil",
  danger: true,
});
await studioDialog.alert({ title: "İçe aktarma tamamlandı" });
```

| `StudioDrawer` prop’u | Açıklama |
| :--- | :--- |
| `open` / `onOpenChange` | Açıklık durumu |
| `title` | Başlık (zorunlu; erişilebilirlik için de kullanılır) |
| `description`, `icon` | Alt başlık ve rozet ikonu |
| `tone` | `default` · `primary` · `danger` |
| `size` | `sm` 400 · `md` 560 · `lg` 820 · `xl` 1180 px (varsayılan `md`) |
| `busy` | İş sürerken kapatma yollarını kilitler |
| `footer`, `headerActions`, `hideClose`, `elevated`, `inert` | Alt eylem satırı, baş satırı kontrolleri, X’i gizle, başka drawer’ın üstünde aç, etkileşimi kapat |

Bir drawer açıkken Studio’nun genel kısayolları (`Delete`, `⌘Z`, `G` / `R` / `B` …) çalışmaz; denetim `isStudioDrawerOpen()` ile yapılır.

## Performans

Monaco (kod), TipTap (zengin metin) ve FilePond/Doka (medya) gibi ağır alanlar ayrı chunk’lara bölünüp ihtiyaç anında yüklenir. Bileşen kütüphanesindeki önizleme görselleri tembel yüklenir.

---

# Bileşen Yapılandırması

> StudioConfig ve ComponentConfig başvurusu, defineSection/defineElement, <Slot> ve <TecofRoot>, kök className sözleşmesi, dinamik alanlar, sürükle-bırak kuralları, varyantlar ve varsayılan çocuklar.
>
> Kaynak: https://tecof-app-dev.vercel.app/editor-components · Bölüm: Tema geliştirme · Son güncelleme: 2018-10-20

Studio’nun hangi blokları göstereceğini, blokların hangi alanlarla düzenleneceğini ve nasıl render edileceğini `StudioConfig` belirler. Editör ve yayın renderer’ı **aynı** nesneyi kullanmalıdır; kayıtlı bir `type` yayındaki config’te yoksa o düğüm sessizce render edilmez.

## StudioConfig

| Alan | Tip | Açıklama |
| :--- | :--- | :--- |
| `components` | `Record<string, ComponentConfig>` | Zorunlu. Anahtar, dokümanda `type` olarak saklanır |
| `categories` | `Record<string, { title?, components? }>` | Bileşen kütüphanesindeki kategoriler ve sırası |
| `root` | `{ fields?, render? }` | Sayfa geneli alanlar (Inspector → Sayfa) ve sayfa sarmalayıcısı (`render`, `children` alır) |
| `templates` | `SectionTemplate[]` | Tek bölüm şablonları ([Slotlar ve şablonlar](https://tecof-app-dev.vercel.app/editor-slots#bolum-sablonlari)) |
| `pageTemplates` | `PageTemplate[]` | Çok bölümlü sayfa şablonları |
| `theme` | `DeepPartialThemeConfig` | Temanın varsayılan renk/tipografi/boşluk değerleri ([Canlı tema](https://tecof-app-dev.vercel.app/editor-theme)) |
| `themePresets` | `ThemePreset[]` | Tema panelinde hazır renk paletleri |
| `darkMode` | `boolean \| { defaultMode?, storageKey? }` | Karanlık modu açar ([Canlı tema](https://tecof-app-dev.vercel.app/editor-theme#karanlik-mod)) |
| `permissions` | `Partial<Permissions>` | Genel izinler ([İzinler](https://tecof-app-dev.vercel.app/editor-permissions)) |
| `migrations` | `MigrationConfig` | Eski kayıtları yükseltme ([İzinler ve migration](https://tecof-app-dev.vercel.app/editor-permissions#veri-migrationi)) |
| `ai` | `{ complete({ system, prompt }) }` | AI ile bölüm üretme ([Studio](https://tecof-app-dev.vercel.app/editor-studio#ai-ile-bolum-uretme)) |
| `nodeInfoButton` | `boolean` | Seçim araç çubuğunda ⓘ bileşen bilgisi düğmesi; varsayılan kapalı |

## ComponentConfig

Yalnız `render` zorunludur.

| Alan | Tip | Açıklama |
| :--- | :--- | :--- |
| `render` | `(props) => ReactNode` | Editörde ve yayında kullanılan render |
| `label` | `string?` | Kütüphanede görünen ad |
| `category` | `string?` | Kategori anahtarı |
| `fields` | `Record<string, FieldConfig>` | Inspector alanları ([Alanlar](https://tecof-app-dev.vercel.app/editor-fields)) |
| `fieldsGroups` | `{ name, fields[] }[]` | Alanları akordeon gruplarına ayırır; listelenmeyenler grupların ardından düz gösterilir |
| `defaultProps` | `object?` | Yeni düğümün başlangıç değerleri |
| `defaultChildren` | `Record<slot, Array<type \| { type, props? }>>` | Eklenince slotlara otomatik konan çocuklar (özyinelemeli, döngü korumalı) |
| `variants` | `Record<string, { label, props }>` | İsimli prop ön ayarları: Bölüm Ekle’de ayrı kart, Inspector’da çip |
| `inline` | `boolean?` | Editörün sarmalayıcı `div`’ini kaldırır; bileşen `puck.dragRef`’i köke bağlamalıdır |
| `acceptsChildren` | `boolean \| string[] \| Record<slot, boolean \| string[]>` | Hangi çocuk tiplerini kabul ettiği (bileşen ya da slot bazında) |
| `maxItems` | `number \| Record<slot, number>` | Doğrudan çocuk üst sınırı (bileşen ya da slot bazında) |
| `allowedParents` | `string[]` | Bu bileşenin bırakılabileceği üst tipler; doluysa kök içeriğe bırakılamaz |
| `resizable` | `boolean?` | Boyutlandırma modunda genişlik/yükseklik tutamaçları (varsayılan `true`) |
| `permissions` / `resolvePermissions` | — | Bileşen ve düğüm bazlı izinler |
| `resolveFields` | `(props, ctx) => fields` | Prop’lara göre dinamik alan seti (sync/async) |
| `resolveData` | `(props, ctx) => { props?, readOnly? }` | Türetilmiş prop’lar ve salt okunur alanlar (sync/async) |
| `metadata` | `object?` | Host’a özel veri; render’da `puck.metadata` içinde |

Render fonksiyonuna gelen prop’lar: düğüm prop’ları, editörün birleştirdiği `className`, slot alanları için hazır slot elemanları, `editMode` ve `puck` (`renderDropZone`, `isEditing`, `metadata`, düzenlemede `registerOverlayPortal` / `dragRef`).

## Kök className sözleşmesi

Editör seçim, hover ve stil sınıflarını bileşenin **kök DOM elemanına** `className` üzerinden ulaştırır. Bir bileşen `props.className`’i kökte basmazsa kanvasta **seçilemez** ve Stil sekmesinde verilen stiller görünmez.

```tsx
// Yanlış: className kaybolur, düğüm seçilemez
render: (p) => <section className="py-16">{p.title}</section>

// Doğru
render: (p) => <section className={cn("py-16", p.className)}>{p.title}</section>
```

Bileşenin her dalı (ör. erken `return` ile boş durum) aynı sözleşmeye uymalıdır. `defineSection` / `defineElement` bunu otomatik yapar; elle yazarken `TecofRoot` kullanabilirsiniz:

```tsx
import { TecofRoot } from "@tecof/theme-editor";

render: (p) => (
  <TecofRoot as="section" className={cn("py-16", p.className)}>
    {p.title}
  </TecofRoot>
)
```

## defineSection ve defineElement

Bildirimsel bir tanımdan düz bir `ComponentConfig` üretir:

- `slots` tek yerde tanımlanır; hem `type: "slot"` alanları hem `defaultChildren` buradan türetilir,
- `render`’a ikinci argüman olarak hazır `<Slot>` elemanları (`slots.<ad>`) verilir,
- render’ın döndürdüğü kök elemanın `className`’ine `p.className` eklenir.

```tsx
import { createLanguageField, defineSection } from "@tecof/theme-editor";

export const FAQSection = defineSection({
  label: "Sıkça Sorulan Sorular",
  category: "sections",
  slots: {
    content: { label: "Başlık ve açıklama", layout: "col", gap: "md", default: ["Title", "Paragraph"] },
    items: {
      label: "Sorular",
      layout: "col",
      gap: "sm",
      hideIfEmpty: true,
      className: (p) => p.compact && "max-w-2xl mx-auto",
      default: [{ type: "FAQItem" }, { type: "FAQItem" }],
    },
  },
  fields: {
    compact: { type: "toggle", label: "Dar düzen" },
    eyebrow: createLanguageField({ label: "Üst başlık" }),
  },
  defaultProps: { compact: false },
  render: (p, slots) => (
    <section className="py-16 lg:py-24">
      <div className="mx-auto max-w-4xl px-4">
        {slots.content}
        <div className="mt-10">{slots.items}</div>
      </div>
    </section>
  ),
});
```

| `slots.<ad>` seçeneği | Açıklama |
| :--- | :--- |
| `label` | Inspector’daki slot adı |
| `layout` | `row` · `row-wrap` · `col` · `contents` · `none`; `row`/`row-wrap` slot alanını yatay (`orientation: "horizontal"`) yapar |
| `gap` | `none` · `xs` .25 · `sm` .5 · `md` .75 · `lg` 1 · `xl` 1.5 rem ya da ham değer (`"1.25rem"`) |
| `className` | Kapsayıcıya ek sınıf; fonksiyon verilirse her render’da prop’larla çağrılır |
| `hideIfEmpty` | Yayında slot boşsa kapsayıcıyı hiç basma (editörde boş slot “Bileşen ekle” ipucuyla görünür kalır) |
| `default` | Eklenince otomatik doğan çocuklar |
| `fieldExtra` | Slot alanına eklenecek ek ayarlar (ör. `{ repeatSource: "items" }`) |
| `allow`, `maxItems` | Slot alanına yazılır — aşağıdaki nota bakın |

> [!WARNING] Slot alanındaki `allow` ve `maxItems` motor tarafından uygulanmaz
> 0.0.96 sürümünde sürükle-bırak kuralları **bileşen düzeyindeki** `acceptsChildren`, `maxItems` ve çocuğun `allowedParents` alanlarından okunur. Slot alanına yazılan `allow` ya da `maxItems` editörde kısıtlama yapmaz. Kısıtlama gerekiyorsa `defineSection` çıktısına bileşen düzeyinde ekleyin:
>
> ```tsx
> export const FAQSection = {
>   ...defineSection({ /* … */ }),
>   acceptsChildren: { items: ["FAQItem"] },
>   maxItems: { items: 12 },
> };
> ```

> [!CAUTION] Bileşen elemanı döndüren render
> `render` bir DOM elemanı yerine bileşen elemanı döndürürse (`<HeroBody />`), `className` o bileşene **prop** olarak geçer. Bileşen bunu kendi kök DOM’una basmazsa düğüm yine seçilemez. Hook gerektiren gövdeyi ayrı bileşene alırken `className` prop’unu kabul edip köke `cn(...)` ile geçirin.

## Slot bileşeni

`<Slot>` bir slot değerini tek satırda çizer ve yerleşimi tek kaynaktan (`layout` + `gap`) yönetir. `defineSection` kullanmayan bileşenlerde doğrudan kullanılır:

```tsx
import { Slot } from "@tecof/theme-editor";

render: (p) => (
  <section className={cn("py-16", p.className)}>
    <Slot value={p.itemsSlot} layout="row-wrap" gap="xl" className="justify-center" data-reveal-group />
  </section>
)
```

| Prop | Açıklama |
| :--- | :--- |
| `value` | Motorun enjekte ettiği slot değeri (`p.<slotAdı>`) |
| `layout`, `gap`, `className`, `style`, `hideIfEmpty` | Yukarıdaki tabloyla aynı |
| diğerleri | `data-*`, `aria-*`, `id` gibi prop’lar slot kapsayıcısına aynen geçer |

`<Slot>` motorun varsayılan yatay yerleşimini (inline `flex`/`gap`) basmasını kapatır; böylece temanın Tailwind sınıfları ezilmez. Yerleşim sınıfları (`.tecof-slot-row`, `.tecof-slot-row-wrap`, `.tecof-slot-col`, `.tecof-slot-contents`) `@layer base` içindedir: editörde paketin `styles.css`’inden gelir, **yayında ise temanın global CSS’inde bulunmalıdır** (yayın sayfası paket CSS’ini yüklemez).

## Dinamik alanlar ve türetilmiş veri

`resolveFields` prop’lara göre alan setini değiştirir; `resolveData` türetilmiş prop yazar ve alanları salt okunur yapar. İkisi de senkron ya da asenkron olabilir; geç gelen eski sonuçlar elenir, geri yazım yalnız gerçek farkı commit eder (idempotent olmalı).

```tsx
ProductCard: {
  fields: {
    source: { type: "select", options: [{ label: "Elle", value: "manual" }, { label: "CMS", value: "cms" }] },
    title: { type: "text" },
    slug: { type: "text" },
  },
  resolveFields: (props, { fields }) => ({
    ...fields,
    ...(props.source === "cms" ? { collection: createCmsCollectionField({ label: "Koleksiyon" }) } : {}),
  }),
  resolveData: (props) => ({
    props: { slug: slugify(props.title ?? "") },
    readOnly: { slug: true },
  }),
  render: (props) => <article className={props.className}>{props.title}</article>,
}
```

`resolveFields` hata fırlatırsa statik `fields` kullanılır.

## Sürükle-bırak kuralları

Kurallar hem kanvasta hem katman panelinde, dokunmatik sürüklemede de aynı şekilde uygulanır. Hiçbiri tanımlı değilse her bırakma serbesttir.

```tsx
const config: StudioConfig = {
  components: {
    Slider: {
      acceptsChildren: { slides: ["Slide"] },   // slides slotu yalnız Slide alır
      maxItems: { slides: 8 },
      fields: { slides: { type: "slot", orientation: "horizontal" } },
      render: ({ slides, className }) => <section className={className}>{slides}</section>,
    },
    Slide: {
      allowedParents: ["Slider"],                // yalnız Slider içine bırakılabilir
      render: ({ className }) => <figure className={className} />,
    },
  },
};
```

## Inline bileşenler

Sarmalayıcı `div` düzeni bozuyorsa `inline: true` verin ve `puck.dragRef`’i kök elemana bağlayın:

```tsx
InlineButton: {
  inline: true,
  fields: { text: { type: "text" } },
  render: ({ puck, text, className }) => (
    <button ref={puck?.dragRef} className={className}>{text}</button>
  ),
}
```

## Varyantlar

```tsx
Button: {
  fields: { text: { type: "text" }, tone: { type: "radio", options: [{ label: "Ana", value: "primary" }, { label: "Çizgili", value: "outline" }] } },
  variants: {
    primary: { label: "Ana buton", props: { tone: "primary" } },
    outline: { label: "Çizgili buton", props: { tone: "outline" } },
  },
  render: (p) => <a className={cn(p.tone === "primary" ? "bg-black text-white" : "border", p.className)}>{p.text}</a>,
}
```

Her varyant Bölüm Ekle penceresinde kendi önizlemeli kartı olarak görünür; Inspector’daki çip varyantı mevcut düğüme uygular (geri alınabilir, `_variant` işaretiyle).

## Kategoriler ve sayfa kökü

```tsx
export const editorConfig: StudioConfig = {
  components,
  categories: {
    sections: { title: "Sayfa bölümleri", components: ["Header", "Hero", "Footer"] },
    elements: { title: "Elementler", components: ["Title", "Paragraph", "Button"] },
  },
  root: {
    fields: {
      enableEcommerce: { type: "radio", label: "E-ticaret özellikleri", options: [{ label: "Aktif", value: "yes" }, { label: "Pasif", value: "no" }] },
    },
  },
};
```

Sayfa geneli değerler dokümanın `root.props` alanında saklanır; tema yayın tarafında bunları `data.root.props` üzerinden okur. Editör 0.0.96 `root.defaultProps` alanını okumaz: değer hiç kaydedilmemiş sayfalar için varsayılanı temada verin (ör. `data.root.props.enableEcommerce !== "no"`).

---

# Alanlar

> Tecof Studio alan başvurusu — yerleşik tipler, çok dilli metin, zengin metin, medya, bağlantı, renk, kod, ikon, tekrar eden satırlar, harici/API kaynakları, CMS ve e-ticaret seçicileri; saklanan değer biçimleri.
>
> Kaynak: https://tecof-app-dev.vercel.app/editor-fields · Bölüm: Tema geliştirme · Son güncelleme: 2018-10-20

Alanlar Inspector’da düzenlenen prop’ları tanımlar. Yerleşik tipler doğrudan `{ type: "…" }` olarak yazılır; gelişmiş alanlar `create*Field()` fabrikalarıyla üretilir. Fabrikalar `{ type: "custom", _fieldType, label, render }` döndürür, yani Puck uyumlu config’e doğrudan konur.

## Yerleşik tipler

| `type` | Değer | Önemli seçenekler |
| :--- | :--- | :--- |
| `text`, `textarea` | `string` | `bindable` (CMS bağlama düğmesi, varsayılan `true`), `readOnly` |
| `select`, `radio` | seçilen `value` | `options: [{ label, value }]` |
| `number` | `number` | — |
| `boolean`, `toggle` | `boolean` | `onLabel`, `offLabel` (varsayılan `Açık` / `Kapalı`) |
| `range` | `number` | `min` (0), `max` (100), `step` (1), `unit` (ör. `"px"`) |
| `array` | `object[]` | `arrayFields` |
| `object` | `object` | `objectFields` |
| `slot` | (zone) | `orientation`, `repeatSource`, `itemSchema` — bkz. [Slotlar](https://tecof-app-dev.vercel.app/editor-slots) |

Her alan `label`, `defaultValue` ve `readOnly` alabilir. Dinamik salt okunurluk `resolveData().readOnly` ile gelir; ikisi VEYA’lanır.

## Ortak seçenekler

Tüm fabrikalar şunları destekler:

| Seçenek | Tip | Açıklama |
| :--- | :--- | :--- |
| `label` | `string` | Inspector etiketi |
| `labelIcon` | `ReactElement` | Etiketin yanındaki ikon (ör. `<Globe size={16} />`) |
| `visible` | `boolean` | Alanın panelde görünüp görünmediği |

## LanguageField — çok dilli metin

Merchant dillerini `merchant-info`’dan alır ve dil başına değer tutar. Studio içinde üst çubuktaki **global dil** kullanılır ve alan içindeki dil sekmeleri gizlenir; Studio dışında sekmeli moda döner.

```tsx
import { createLanguageField } from "@tecof/theme-editor";

fields: {
  title: createLanguageField({ label: "Başlık" }),
  description: createLanguageField({ label: "Açıklama", isTextarea: true, textareaRows: 4 }),
  html: createLanguageField({ label: "HTML içerik", isHtml: true }),
}
```

| Seçenek | Varsayılan | Açıklama |
| :--- | :--- | :--- |
| `isTextarea` | `false` | Çok satırlı giriş |
| `textareaRows` | `3` | Satır sayısı |
| `placeholder` | `''` | Yer tutucu |
| `isHtml` | `false` | Çeviride HTML etiketlerini korur |

**Değer:** `[{ code: "tr", value: "Merhaba" }, { code: "en", value: "Hello" }]`. Temada aktif dilin değerini seçin; değer yoksa varsayılan dile düşmek temanın sorumluluğundadır:

```ts
const pick = (value: Array<{ code: string; value: string }> | string | undefined, locale: string, fallback = "tr") =>
  typeof value === "string" ? value : (value?.find((v) => v.code === locale)?.value || value?.find((v) => v.code === fallback)?.value || "");
```

**Dil araçları:** Birden fazla dil varken alan üstünde **Hızlı Doldur** (aktif sekmedeki metni tüm dillere kopyalar) ve **Çevir** (API üzerinden diğer dillere çevirir; `isHtml` ile etiketler korunur) düğmeleri görünür. Aynı çubuk `EditorField`, `LinkField` (yalnız Hızlı Doldur, yalnız boş diller) ve `LocalizedUploadField`’da da vardır.

Kendi çok dilli alanınızda aynı araçları kullanabilirsiniz:

```tsx
import {
  LanguageToolsBar, useLanguageToolsStatus, normalizeLocalizedValues, fillLanguages,
  translateLanguages, isEmptyText, LANGUAGE_TOOL_MESSAGES,
} from "@tecof/theme-editor";

const { status, translating, setTranslating, flash } = useLanguageToolsStatus();
const values = normalizeLocalizedValues<string>(value, languages, () => "");

const fill = () => {
  const res = fillLanguages(values, languages, activeTab, { isEmpty: isEmptyText });
  if (!res) return; // kaynak boş ya da doldurulacak dil yok
  onChange(res.values);
  flash({ text: LANGUAGE_TOOL_MESSAGES.filledAll, type: "success" }, 2000);
};

const translate = async () => {
  setTranslating(true);
  try {
    const out = await translateLanguages({
      values: () => valuesRef.current, // getter: yanıt gelene kadar yazılanlar korunur
      languages,
      sourceCode: activeTab,
      translate: apiClient.translate.bind(apiClient),
    });
    if (out.ok) onChange(out.values);
    flash(out.ok ? { text: LANGUAGE_TOOL_MESSAGES.translated, type: "success" } : { text: out.message, type: "error" }, 3000);
  } finally {
    setTranslating(false);
  }
};

<LanguageToolsBar onFill={fill} onTranslate={translate} translating={translating} status={status} />;
```

`fillLanguages(values, languages, sourceCode, { onlyEmpty, isEmpty, clone })` → `{ values, filled } | null`. `onlyEmpty: true` dolu dilleri ezmez ve listede olmayan dil kodlarını korur. Boşluk tanımları: `isEmptyText`, `isEmptyHtml` (medya etiketi dolu sayılır), `isEmptyLink`.

## EditorField — zengin metin

TipTap tabanlı, çok dilli WYSIWYG editör (kalın, italik, bağlantı, liste, başlık…). Hızlı Doldur boş `<p></p>` içerikte pasiftir; Çevir yalnız `TecofProvider` varken görünür. Araçlar aktif dilin içeriğini değiştirmediği için imleç korunur.

```tsx
fields: { content: createEditorField({ label: "İçerik" }) }
```

## UploadField — medya

Seçili medya kare önizleme kutuları olarak görünür; “ekle” kutusu sekmeli bir medya penceresi açar: **Kütüphane** (sunucudaki dosyalar), **Yükle** (FilePond), **Referans** (CMS değişkeni, `{{ data.alan }}`). Doka görsel düzenleyici (kırp, döndür, ayarlar), istemci tarafı WebP sıkıştırma ve **odak noktası** seçimi içerir.

```tsx
fields: {
  gallery: createUploadField({
    label: "Ürün galerisi",
    allowMultiple: true,
    maxFiles: 10,
    maxFileSize: "50MB",
    acceptedTypes: ["image/*"],
    folder: "/products",
  }),
  document: createUploadField({ label: "Katalog", allowMultiple: false, acceptedTypes: ["application/pdf"] }),
}
```

| Seçenek | Varsayılan | Açıklama |
| :--- | :--- | :--- |
| `allowMultiple` | `true` | Çoklu dosya |
| `maxFiles` | `100` | En çok dosya |
| `maxFileSize` | `"100MB"` | Tek dosya sınırı |
| `maxTotalFileSize` | `"200MB"` | Toplam sınır |
| `acceptedTypes` | tümü | MIME türleri (`["image/*"]`, `["application/pdf"]`) |
| `folder` | `"/"` | Yükleme klasörü |
| `allowReorder` | `true` | Sürükleyerek sıralama |
| `imageCompressionEnabled` | `true` | Yüklemeden önce sıkıştırma |
| `imageCompressionOptions` | `{ maxSizeMB: 1, maxWidthOrHeight: 1920 }` | Sıkıştırma ayarları (`fileType` de verilebilir) |
| `imagePreviewHeight` | — | FilePond önizleme yüksekliği |
| `showUploadedFiles` | `false` | Kullanımdan kalktı; yeni arayüzde etkisiz |

**Değer:** `UploadedFile[]` — `{ _id, name, size, type, mimeType?, url?, folder?, provider?, focalPoint?, meta? }`. Görseli temada `TecofPicture` ile basın ([Yayın render’ı](https://tecof-app-dev.vercel.app/editor-render#tecofpicture)).

**Odak noktası:** görsel kutusundaki nişangâh düğmesi odak penceresini açar (tıkla/sürükle, ok tuşlarıyla 1’er, `Shift` ile 10’ar adım; 16:9, 1:1, 9:16 kırpma önizlemeleri). Seçim dosyanın içine `focalPoint: { x, y }` (yüzde, 50/50 merkez) olarak yazılır; `TecofPicture` bunu `object-position` olarak uygular. Backend’de şema değişikliği gerekmez.

## LocalizedUploadField — dile göre medya

`UploadField`’ın dil sekmeli sürümü; seçenekleri aynıdır. Her dil için ayrı dosya listesi tutar.

```tsx
fields: {
  banner: createLocalizedUploadField({ label: "Kampanya görseli", allowMultiple: false }),
}
defaultProps: { banner: [] }
```

**Değer:** `[{ code: "tr", value: UploadedFile[] }, { code: "en", value: [] }]`. Yayında istenen dil boşsa varsayılan dile, o da boşsa ilk dolu dile düşülür:

```tsx
import { resolveLocalizedUploadFile, TecofPicture } from "@tecof/theme-editor";

const file = resolveLocalizedUploadFile(props.banner, locale, "tr"); // UploadedFile | null
return file ? <TecofPicture data={file} alt="" /> : null;
```

Çoklu dosya için `resolveLocalizedUpload(value, locale, defaultLanguage)` → `UploadedFile[]`. Eski düz `UploadedFile[]` kayıtlar varsayılan dil altında açılır ve ilk düzenlemede yeni biçimde kaydedilir. Hızlı Doldur yalnız boş dillere kopyalar; Çevir yoktur. Ters yön (yerelleştirilmiş alanı tekrar `createUploadField`’a çevirmek) desteklenmez.

## LinkField — sayfa veya URL

Mağaza sayfalarından seçim (aranabilir pencere, yayın durumu göstergesi) ya da elle URL girişi. Dil sekmelidir; değer dil başına saklanır.

```tsx
fields: {
  cta: createLinkField({ label: "CTA bağlantısı", showTarget: true, placeholder: "https://…" }),
}
```

| Seçenek | Varsayılan | Açıklama |
| :--- | :--- | :--- |
| `showTarget` | `true` | Aynı / yeni sekme seçimi |
| `placeholder` | `https://...` | URL yer tutucusu |

**Değer:** `[{ code: "tr", value: LinkFieldValue }, …]`; `LinkFieldValue = { url, label?, target?: "_self" | "_blank", type?: "page" | "custom" | "category" | "brand" | "product" | "cms" }`. Render yalnız `url` ve `target` okur. Eski düz `LinkFieldValue` kayıtlar mağaza dillerine göre normalize edilir.

## ColorField — renk

Popover renk seçici: doygunluk/parlaklık alanı, ton ve opaklık kaydırıcıları, HEX/RGB/HSL girdileri, ekrandan renk seçme (EyeDropper), canlı tema paleti, 22 tonluk Tailwind paleti, son kullanılanlar ve WCAG kontrast önizlemesi. Tam klavye erişimi vardır.

<!-- preview:color-field -->

```tsx
fields: {
  bgColor: createColorField({ label: "Arka plan" }),
  overlay: createColorField({ label: "Kaplama", showOpacity: true, defaultColor: "#00000080" }),
  accent: createColorField({ label: "Vurgu", themeVars: true }),
  brand: createColorField({ label: "Marka", swatches: ["#18181b", "#74b500", "#ffffff"], palette: false }),
}
```

| Seçenek | Varsayılan | Açıklama |
| :--- | :--- | :--- |
| `showOpacity` | `false` | Opaklık; değer `#rrggbbaa` |
| `defaultColor` | `''` | Sıfırlama hedefi |
| `placeholder` | `'#000000'` | HEX girdisi yer tutucusu |
| `showReset` | `true` | Değer varsayılandan farklıyken sıfırla düğmesi |
| `swatches` | `[]` | “Hızlı seçim” satırı |
| `themeColors` | `true` | Canlı tema renkleri (yalnız Studio içinde) |
| `themeVars` | `false` | Tema rengini `var(--theme-color-<anahtar>)` olarak bağlar; kapalıyken açık paletteki hex kopyalanır |
| `palette` | `true` | Tailwind paleti |
| `contrast` | `true` | Kontrast çipleri (WCAG AA/AAA) |
| `contrastAgainst` | — | Kontrast zemini (hex) |

**Değer sözleşmesi:** `''`, `#rrggbb`, `#rrggbbaa` (yalnız `showOpacity`) ya da `var(--theme-color-*)` (yalnız `themeVars`). `rgb()/hsl()/transparent` girdileri hex’e çevrilir; tanınmayan değerler korunur. Hex matematiği yapan tema kodu `var()` beklememelidir. Saf yardımcılar da dışa aktarılır: `parseColor`, `formatHex`, `normalizeColorValue`, `classifyColorValue`, `contrastRatio`, `wcagLevel`, `themeColorVar`, `parseThemeColorVar`, `THEME_COLOR_KEYS`, `toThemeCssKey`.

## CodeEditorField — kod

Monaco tabanlı kod editörü (ilk kullanımda tembel yüklenir).

```tsx
fields: {
  customHtml: createCodeEditorField({ label: "Özel kod", defaultLanguage: "html" }),
  json: createCodeEditorField({ label: "Yapılandırma", defaultLanguage: "json", height: "240px" }),
}
```

Seçenekler: `defaultLanguage`, `height`, `theme`.

## RepeaterField — tekrar eden satırlar

Alt alan setini (`subFields`) satırlar hâlinde düzenler: ekle, sil, çoğalt, sürükleyerek sırala, satırı katla.

```tsx
fields: {
  items: createRepeaterField({
    label: "Öğeler",
    subFields: {
      title: createLanguageField({ label: "Başlık" }),
      link: createLinkField({ label: "Bağlantı" }),
    },
    minItems: 1,
    maxItems: 6,
    defaultRow: { title: "", link: null },
  }),
}
```

**Değer:** `Record<string, unknown>[]`. Bir slot’un `repeatSource`’u olarak kullanılabilir ([Repeat zone](https://tecof-app-dev.vercel.app/editor-slots#repeat-zone-oge-sablonu)).

## IconField — ikon

`lucide-react` setinden aranabilir ikon seçici (arama yoksa ilk 120 ikon). **Değer** ikonun adıdır (`"ShoppingCart"`); bileşeni render’da siz çözersiniz:

```tsx
import { icons } from "lucide-react";

const Icon = icons[props.icon as keyof typeof icons];
return Icon ? <Icon className="size-5" /> : null;
```

## ExternalField — harici tek kayıt

Kendi API’nizden aranabilir bir pencerede **tek kayıt** seçtirir.

```tsx
fields: {
  product: createExternalField({
    label: "Ürün",
    fetchList: async ({ query }) => (await fetch(`/api/products?q=${query ?? ""}`)).json(),
    mapProp: (row) => ({ id: row.id, name: row.name }),
    mapRow: (row) => ({ Ad: row.name, SKU: row.sku }),
    getItemSummary: (value) => value?.name ?? "",
    placeholder: "Ürün seçin",
  }),
}
```

| Seçenek | Açıklama |
| :--- | :--- |
| `fetchList({ query?, filters? })` | Zorunlu. Satırları getirir |
| `mapProp(row)` | Prop’a yazılacak değer (varsayılan satırın kendisi) |
| `mapRow(row)` | Pencere tablosunun sütunları |
| `getItemSummary(value)` | Seçili değerin etiketi |
| `showSearch` | Arama kutusu (varsayılan `true`) |

## ApiListField — API’den liste

Kendi API’nizden **liste** akıtır; bir slot’un `repeatSource`’una bağlanınca öğe şablonu her satır için tekrarlanır.

```tsx
fields: {
  source: createApiListField({
    label: "Ürünler",
    fetchList: async ({ query, limit }) => (await fetch(`/api/products?q=${query ?? ""}&limit=${limit ?? 8}`)).json(),
    itemSchema: [{ key: "name", label: "Ad", type: "text" }, { key: "image", label: "Görsel", type: "image" }],
    defaultLimit: 8,
  }),
  card: { type: "slot", orientation: "horizontal", repeatSource: "source" },
}
```

**Değer:** `{ query?: string; limit?: number }` — dokümana yalnız sorgu parametreleri yazılır; satırlar render anında çözülür (oturum içi önbellek, eşzamanlı istek tekleme). Seçenekler: `showQuery`, `showLimit` (varsayılan `true`), `defaultLimit`.

## E-ticaret seçicileri

Mağazanın kendi kayıtlarından seçim yaptırır; slug ya da ObjectId elle yazdırmaz.

```tsx
import {
  createCategoryField, createCategoryListField, createProductField, createProductListField,
  createBrandField, createBrandListField, createTagField, createTagListField,
  createAttributeField, createAttributeListField, createVariantTypeField, createVariantField,
  createFlashSaleField, createCampaignField, createDiscountField,
} from "@tecof/theme-editor";

fields: {
  category: createCategoryField({ label: "Kategori" }),
  featured: createProductField({ label: "Öne çıkan ürün" }),
  tags: createTagListField({ label: "Etiketler", max: 6 }),
  coupon: createDiscountField({ label: "Kupon" }),
}
```

Saklanan değer seçim anında donan bir **anlık görüntüdür**; yayın ek istek atmadan render edebilir:

| Alan | Değer |
| :--- | :--- |
| `createCategoryField` | `{ id, slug, name, path }` |
| `createProductField` | `{ id, slug, name, image }` |
| `createBrandField` | `{ id, slug, name, image }` |
| `createTagField` | `{ id, slug, name }` |
| `createAttributeField` | `{ id, slug, name, type, isFilterable, options: [{ value, label, colorCode }] }` |
| `createVariantTypeField` | `{ id, name, selectionType, values: [{ label, colorCode }] }` |
| `createVariantField` | `{ productId, productSlug, productName, variantId, sku, title, price }` |
| `createFlashSaleField` | `{ id, name, startDate, endDate, showCountdown, bannerText, highlightColor, discountType, discountValue }` |
| `createCampaignField` | `{ id, name, status, startDate, endDate, discountCode }` |
| `createDiscountField` | `{ id, code, title, type, value, minCartAmount, maxDiscountAmount, startDate, endDate }` |

- `*ListField` varyantlarında değer bu nesnelerin dizisidir; editördeki sıra korunur. Seçenekler: `label`, `placeholder`, `visible`, listelerde `max`.
- **Neden hem `id` hem `slug`:** ürün listeleme ucu markayı ve etiketi **ObjectId**, kategoriyi **slug** ile filtreler. Temada filtreyi kimlikle gönderin: `getProducts({ brand: props.brand?.id, tag: props.tag?.id })`.
- **Veri kaynağı:** kategori/ürün/marka vitrin uçlarından (`/api/store/ecommerce/*`); etiket, özellik, varyant tipi, flaş satış, kampanya ve kupon panel uçlarından (`/api/merchant/ecommerce/*`) gelir. Panel uçları JWT’ye ek olarak `x-merchant-id` ister; `TecofApiClient` bunu `merchant-info`’dan bir kez çözer. Kimlik çözülemezse liste boş değil **hata** gösterir.
- **Anlık görüntü donar:** markanın adı ya da kampanyanın tarihi panelde sonradan değişirse sayfa eski değeri gösterir; alanı yeniden seçin.
- **Boş durum:** liste boşsa “Panelde ürün ekle” gibi bir bağlantı, doluysa başlıkta “Panelde yönet” görünür; adresler `panelUrl` üzerine kurulur ve yeni sekmede açılır. Panelde kayıt ekledikten sonra seçicideki **Yenile** listeyi tazeler.
- **Geriye uyum:** var olan bir metin alanının yerine koyarken eski prop’u okumaya devam edin: `props.brand?.id ?? props.brandIdText ?? ""`.

## CmsCollectionField — koleksiyon bağlama

Bir bileşeni CMS koleksiyonuna bağlar: koleksiyon, adet ve sıralama seçilir; bileşenin veri yuvaları koleksiyon alanlarına eşlenir.

```tsx
fields: {
  source: createCmsCollectionField({
    label: "Veri kaynağı",
    defaultLimit: 6,
    slots: {
      title: { label: "Başlık", fieldTypes: ["text"] },
      image: { label: "Görsel", fieldTypes: ["image"] },
      link: { label: "Bağlantı" },
    },
  }),
}
```

| Seçenek | Varsayılan | Açıklama |
| :--- | :--- | :--- |
| `defaultLimit` | `10` | Varsayılan öğe sayısı |
| `showLimit`, `showSort` | `true` | Adet ve sıralama (özel / yeni → eski / eski → yeni) kontrolleri |
| `slots` | — | Bileşenin ihtiyaç duyduğu veri yuvaları |

**Değer:** `{ collectionSlug, collectionName?, limit?, sort?: "newest" | "oldest" | "custom", fieldMap?: Record<yuva, cmsAlanKısaKodu> }`. Bir repeat slot’a kaynak olarak bağlanırsa satırlar koleksiyondan otomatik çekilir (ağaçta `TecofProvider` gerekir).

## CMS veri bağlama (metin alanları)

`text` ve `textarea` alanlarının yanında bir **`{ }`** düğmesi görünür; koleksiyon → alan seçilince alana `{{ data.<kısaKod> }}` token’ı eklenir. Yayında token, `TecofRender`’a verilen `cmsData` kaydıyla çözülür. Kapatmak için `bindable: false`:

```tsx
fields: {
  title: { type: "text", label: "Başlık" },                         // bağlama açık
  staticLabel: { type: "text", label: "Sabit etiket", bindable: false },
}
```

Repeat zone şablonunun içindeyken aynı düğme **Öğe alanları** bölümünü de gösterir (`{{ item.<alan> }}`).

## Hata yalıtımı

Fabrikaların ürettiği alanlar `FieldErrorBoundary` içinde render edilir; bir alanın hatası Inspector’ı düşürmez. Kendi `render` alanlarınızda da aynı bileşeni kullanabilirsiniz.

---

# Slotlar ve Şablonlar

> Zone modeli, dikey ve yatay slotlar, repeat zone (öğe şablonu) ve veri kaynakları, slider deseni, bölüm ve sayfa şablonları, id güvenliği — canlı repeat zone önizlemesiyle.
>
> Kaynak: https://tecof-app-dev.vercel.app/editor-slots · Bölüm: Tema geliştirme · Son güncelleme: 2018-10-20

Slotlar bir bileşenin içine başka bileşenlerin bırakılabildiği bölgelerdir. Bu sayfa slotların saklanma biçimini, yatay/dikey yerleşimi, verinin her satırı için tekrarlanan **repeat zone**’ları ve tek tıkla eklenen şablonları anlatır.

## Zone modeli

Kök düğümler dokümanın `content` dizisinde, iç içe düğümler `zones` nesnesinde tutulur. Zone anahtarı `parentId:slotAdı` biçimindedir:

```json
{
  "content": [{ "type": "Hero", "props": { "id": "hero-1", "title": "Yeni sezon" } }],
  "zones": {
    "hero-1:actions": [
      { "type": "Button", "props": { "id": "btn-1", "text": "Keşfet" } },
      { "type": "Button", "props": { "id": "btn-2", "text": "İncele" } }
    ]
  },
  "root": { "props": {} }
}
```

Üst düğüm silindiğinde alt zone ağacı da temizlenir. Zone anahtarı düğüm **id**’sine bağlı olduğu için bir bileşen tipinin adını değiştirmek zone anahtarlarını etkilemez.

## Dikey ve yatay slotlar

Slot alanları varsayılan olarak çocukları alt alta dizer. `orientation: "horizontal"` verildiğinde editör bırakma eksenini sol/sağ olarak hesaplar ve yayın aynı düzeni korur.

```tsx
fields: {
  columns: { type: "slot", label: "Kolonlar", orientation: "horizontal" },
  blocks: { type: "slot", label: "Bloklar" }, // dikey
}
```

Slot’u render’da çizmenin üç yolu vardır; yeni kodda ilk ikisini kullanın:

```tsx
// 1) defineSection: hazır <Slot> elemanı
render: (p, slots) => <section className="py-16">{slots.columns}</section>

// 2) <Slot> bileşeni: yerleşim tek kaynaktan
render: (p) => (
  <section className={cn("py-16", p.className)}>
    <Slot value={p.columns} layout="row-wrap" gap="lg" />
  </section>
)

// 3) Düşük seviye: puck.renderDropZone
render: ({ puck, className }) => (
  <section className={className}>{puck.renderDropZone({ zone: "columns", orientation: "horizontal" })}</section>
)
```

Düz `renderDropZone` ile yatay slot yayında inline `display:flex; flex-wrap:wrap; gap:8px` alır; `<Slot>` ise bu varsayılanı kapatıp yerleşimi `layout` / `gap` / `className`’den kurar ([Slot bileşeni](https://tecof-app-dev.vercel.app/editor-components#slot-bileseni)).

## Repeat zone (öğe şablonu)

Bir slot alanına `repeatSource` verildiğinde slot bir **öğe şablonuna** dönüşür: kart bir kez tasarlanır ve veri listesindeki her satır için tekrarlanır (ürün ızgarası, koleksiyon listesi, SSS…). Şablondaki prop’lar satıra `{{ item.<alan> }}` token’larıyla bağlanır.

<!-- preview:slot-repeat -->

```tsx title="ProductGrid.tsx"
ProductGrid: {
  label: "Ürün ızgarası",
  fields: {
    items: createRepeaterField({
      label: "Ürünler",
      subFields: { name: { type: "text", label: "Ad" }, price: { type: "text", label: "Fiyat" }, image: createUploadField({ label: "Görsel", allowMultiple: false }) },
    }),
    card: { type: "slot", label: "Kart şablonu", orientation: "horizontal", repeatSource: "items" },
  },
  render: ({ card, className }) => <section className={className}>{card}</section>,
}
```

Şablondaki bir Text düğümünün `text` prop’u `"{{ item.name }}"`, fiyat satırı `"Fiyat: {{ item.price }} TL"` olabilir.

- **Tam token ham değeri geçirir:** prop’un değeri yalnız `"{{ item.image }}"` ise görsel/bağlantı nesnesi olduğu gibi iletilir; metne gömülü token metne çevrilir.
- **Özel yollar:** `{{ item._index }}` (0 tabanlı), `{{ item._position }}` (1 tabanlı).
- **Token’ları kütüphane çözer:** `{{ item.* }}` hem editör kanvasında hem `TecofRender`’da çözülür; host tarafında iş gerekmez. (`{{ data.* }}` ise CMS kaydından, `cmsData` ile çözülür.)
- **Editörde** şablon ilk satırın verisiyle bir kez düzenlenir; kalan satırlar etkileşimsiz, soluk kopyalar olarak aynı grid/flex akışında görünür.
- **Yayında** döngü gerçek veriyle döner; satır yoksa şablon **hiç** render edilmez — canlı sitede ham token görünmez.

> [!WARNING] Bağlı metni kanvasta düzenlemeyin
> Şablonda bağlı bir metne çift tıklayıp satır içi düzenlemek token’ı literal değerle ezer ve bağı koparır. Bağlı alanları Inspector’dan düzenleyin; Inspector her zaman ham token’ı gösterir.

### Veri kaynakları

`repeatSource`’un gösterdiği prop’un değerine göre satırlar otomatik çözülür:

| Kaynak | Satırlar nereden gelir |
| :--- | :--- |
| Dizi prop / `createRepeaterField` | Dokümanda kayıtlı satırlar |
| `createApiListField` | Host’un `fetchList` fonksiyonu; editörde ve yayında (istemcide) kütüphane çağırır |
| `createCmsCollectionField` | CMS koleksiyonu; ağaçta `TecofProvider` gerekir (yoksa satırlar boş kalır) |
| `renderDropZone({ zone, repeatItems })` | Bileşen satırları render anında kendisi verir (tam kontrol) |

```tsx
// Manuel yol: veriyi bileşen kendisi getirir
render: ({ puck }) => {
  const { rows } = useMyProducts();
  return puck.renderDropZone({ zone: "card", repeatItems: rows });
},
```

Bağlama penceresindeki **Öğe alanları** listesi sırasıyla slot’un `itemSchema`’sından, kaynak alanın `itemSchema`’sından ya da çözülen ilk satırdan çıkarılır. Yalnız manuel `repeatItems` yolunda `itemSchema` bildirmeniz gerekir:

```tsx
card: {
  type: "slot",
  itemSchema: [
    { key: "name", label: "Ürün adı", type: "text" },
    { key: "image", label: "Görsel", type: "image" },
  ],
}
```

| Dışa aktarım | Ne işe yarar |
| :--- | :--- |
| `useRepeatItem()` | Şablon bileşeni içinde `{ item, index, count }`; şablon dışında `null` |
| `resolveItemTokens(value, item, index)` | Renderer’ların kullandığı token çözücü (host’un kendi render’ı için) |
| `resolveRepeatRows(value, sourceFieldDef, apiClient?)` | Satırları React dışında çözer (ör. SSR ısıtma) |
| `useRepeatRows(value, sourceFieldDef)` | Aynı çözümleme, React kancası olarak |
| `clearRepeatRowsCache()` | API/CMS satır önbelleğini temizler |
| `findRepeatScope(doc, config, nodeId)` | Bir düğümün içinde bulunduğu repeat şablonunu bulur |

> [!NOTE] Repeat slotlarda yayın yerleşimi `orientation`’dan gelir
> 0.0.96 sürümünde `TecofRender`, `repeatSource`’lu bir slotu kendi iç bileşeniyle çizer ve `<Slot>`’un `layout` / `gap` / `className` değerlerini bu bileşene **iletmez**. Yayında yatay repeat slot `orientation: "horizontal"` varsayılanını (inline `flex-wrap`, `gap: 8px`) kullanır. Kart aralığını kartın kendi kenar boşluğuyla ya da kapsayıcı bölümün sınıflarıyla verin; yukarıdaki önizleme bu davranışı gösterir.

## Slider / carousel deseni

Slaytlar ayrı bir bileşen olarak slota bırakılır. Kritik nokta `editMode` ayrımıdır: editörde tüm slaytlar yan yana görünüp sürükle-bırak almalı, yayında aynı zone kaydırılabilir bir carousel olmalıdır.

```tsx title="Slider.tsx"
const Slider = {
  label: "Slider",
  acceptsChildren: { slides: ["Slide"] },
  maxItems: { slides: 8 },
  fields: { slides: { type: "slot", label: "Slaytlar", orientation: "horizontal" } },
  render: ({ puck, editMode, className }) => (
    <section className={className}>
      {puck.renderDropZone({
        zone: "slides",
        orientation: "horizontal",
        className: editMode ? "gap-4" : "snap-x snap-mandatory overflow-x-auto gap-4",
        style: editMode ? undefined : { flexWrap: "nowrap" },
      })}
    </section>
  ),
};

const Slide = {
  label: "Slayt",
  allowedParents: ["Slider"],
  fields: { image: createUploadField({ label: "Görsel", allowMultiple: false }), caption: { type: "text", label: "Başlık" } },
  render: ({ image, caption, className }) => (
    <figure className={cn("w-80 shrink-0 snap-center", className)}>
      <TecofPicture data={image?.[0]} alt={caption ?? ""} size="large" />
      {caption && <figcaption className="mt-2 text-sm">{caption}</figcaption>}
    </figure>
  ),
};
```

- `snap-*` sınıfları slaydın kendi kökündedir; yayında zone çocukları doğrudan render edildiği için scroll-snap birebir çalışır.
- Swiper/Embla gibi DOM’u klonlayan ya da ölçen kütüphaneleri yalnız `editMode === false` iken bağlayın; editörde zone düz düzende kalmalıdır ki seçim ve bırakma hedefleri doğru çalışsın. Çoğu senaryoda CSS scroll-snap yeterlidir.

## Bölüm şablonları

`config.templates`, **Bölüm Ekle** penceresinde ayrı sekmede gösterilen hazır bölümlerdir. Şablon bir alt ağaçtır: kök düğüm ve alt zone’ları.

```tsx
templates: [
  {
    id: "hero-cta",
    label: "Hero + iki buton",
    category: "Dönüşüm",
    thumbnail: "/templates/hero-cta.webp",
    payload: {
      node: { type: "Hero", props: { id: "t-hero", title: "Başlık" } },
      zones: {
        "t-hero:actions": [
          { type: "Button", props: { id: "t-b1", text: "Başla" } },
          { type: "Button", props: { id: "t-b2", text: "İncele" } },
        ],
      },
    },
  },
],
```

| Alan | Tip | Açıklama |
| :--- | :--- | :--- |
| `id` | `string` | Kararlı kimlik |
| `label` | `string` | Kartta görünen ad |
| `category` | `string?` | Kategori |
| `thumbnail` | `string?` | Önizleme görseli (yoksa ikon) |
| `payload.node` | `TecofNode` | Eklenecek kök düğüm |
| `payload.zones` | `Record<string, TecofNode[]>?` | Kök düğümün alt zone’ları (`nodeId:slotAdı`) |

## Sayfa şablonları

`config.pageTemplates` tüm sayfayı kuran bölüm dizileridir (Ana Sayfa, Hakkımızda, İletişim…). Sol paneldeki **Sayfa şablonları** bölümünde ve Bölüm Ekle penceresinde görünür.

```tsx
pageTemplates: [
  {
    id: "core-home",
    label: "Ana sayfa",
    description: "Hero, hizmetler, referanslar ve iletişim çağrısı",
    keywords: ["kurumsal", "landing"],
    previewUrl: "/preview-template/core-home",
    sections: [
      { node: { type: "Hero", props: { id: "t-hero", title: "Başlık" } } },
      { node: { type: "Services", props: { id: "t-svc" } }, zones: { "t-svc:items": [] } },
    ],
  },
],
```

Şablona tıklamak bölümleri doğrudan eklemez; önce bir onay penceresi açılır. `previewUrl` varsa sayfa 1280 px referans genişlikte bir iframe’de (tembel, sandbox’lı, tıklanamaz) gösterilir; göreli adres editörün çalıştığı origin’e göre çözülür. Yoksa bölümlerin canlı önizlemesi üst üste dizilir. Onaydan sonra mevcut içerik silinmez; bölümler eklenir ve tamamı **tek geri al** adımıdır.

## Id güvenliği

Şablondaki id’ler yalnız ilişki kurmak için örnek kimliklerdir. Studio her eklemede kök ve tüm alt düğümler için yeni id üretir ve zone anahtarlarını buna göre yeniden yazar; aynı şablonu güvenle birden çok kez ekleyebilirsiniz. Kopyala/yapıştır ve çoğaltma için de aynı kural geçerlidir.

---

# Stil Editörü

> Studio stil editörü — _tecofStyles token modeli, 54 kontrol, masaüstü-öncelikli kırılımlar, hover/focus/active, serbest değerler, renk kaynakları, TecofRender’ın ürettiği CSS, safelist ve sayfalar arası stil senkronu.
>
> Kaynak: https://tecof-app-dev.vercel.app/editor-styles · Bölüm: Tema geliştirme · Son güncelleme: 2018-10-20

Inspector’daki **Stil** sekmesi seçili düğüme görsel stil uygular. Stiller ham class dizisi olarak değil, düğümün `_tecofStyles` prop’unda **yapısal token**’lar olarak saklanır; editör ve `TecofRender` bunları aynı yoldan sınıflara ve CSS’e çevirir.

<!-- preview:style-tokens -->

## Token modeli

```json
{
  "base": { "p": "8", "bg": "primary-500", "radius": "2xl" },
  "sm": { "p": "4" },
  "states": {
    "hover": { "bg": "primary-600" },
    "md:hover": { "bg": "primary-700" }
  }
}
```

`compileStyles()` bu modeli sınıf dizisine çevirir; her sınıf `!` (important) son ekiyle üretilir ki bileşenin kendi sınıflarını yensin:

```text
p-8! bg-primary-500! rounded-2xl! sm:p-4! hover:bg-primary-600! md:hover:bg-primary-700!
```

- Değer bir **token**’dır, Tailwind sınıfı değil: `p: "6"`, `bg: "primary-600"`, `radius: "xl"`.
- Serbest değerler köşeli parantezle yazılır: `"[40px]"`, `"[#ff6b00]"`, `"[var(--theme-color-primary)]"`.
- Model `node.props._tecofStyles` içinde kayıpsız gidip gelir; editör her kontrolün mevcut değerini gösterebilir.
- Kontrol listesi, preset’ler ve sınıf derlemesinin tek kaynağı paketin `STYLE_CONTROLS` dizisidir (54 kontrol).

## Kırılımlar masaüstü önceliklidir

> [!IMPORTANT] Tailwind’in mobil-öncelikli `md:` anlamı burada geçerli değil
> Sınıf adları Tailwind’e benzese de Studio’nun ürettiği CSS **masaüstü önceliklidir** (`max-width` medya sorguları). `base` ana (masaüstü) tasarımdır; her kırılım ekran **küçüldükçe** devreye giren bir geçersiz kılmadır. Bu sayede 375 px’lik mobil kanvas `sm` katmanını gerçekten düzenler.

| Katman | Uygulandığı ekran | Önek |
| :--- | :--- | :--- |
| `base` | Tüm ekranlar | — |
| `xl` | ≤ 1280 px | `xl:` |
| `lg` | ≤ 1024 px | `lg:` |
| `md` | ≤ 768 px (tablet ve altı) | `md:` |
| `sm` | ≤ 640 px (mobil) | `sm:` |

Dar bir ekran birden çok sorguya uyduğu için CSS büyükten küçüğe sırayla basılır; en dar katman kazanır. Editörde üst katmanda değer yoksa daha geniş katmandan **miras alınan** değer soluk ipucu olarak gösterilir; değer içeren katmanlar küçük bir noktayla işaretlenir.

**Durumlar:** `hover`, `focus`, `active`. Durum anahtarı çıplaksa (`hover`) tüm ekranlarda, `md:hover` biçimindeyse yalnız o kırılımda uygulanır (`base:hover` geçersizdir).

## Kontroller

| Grup | Kontroller (`*` serbest değer alır) |
| :--- | :--- |
| Yerleşim | `display`, `flexDir`, `justify`, `items`, `flexWrap`, `gap*`, `alignSelf`, `position`, `zIndex`, `overflow` |
| Boşluk | `p*`, `px*`, `py*`, `pt*`, `pb*`, `pl*`, `pr*`, `m*`, `mx*`, `my*`, `mt*`, `mb*`, `ml*`, `mr*`, `marginAlign` |
| Boyut | `w*`, `h*`, `maxW*` |
| Arka plan | `bg*`, `bgGradient`, `gradientFrom*`, `gradientTo*` |
| Tipografi | `fontFamily*`, `text*`, `fontSize`, `fontWeight`, `align`, `leading`, `tracking`, `textTransform`, `decoration` |
| Kenarlık | `radius`, `border`, `borderColor*` |
| Efektler | `shadow`, `opacity`, `blur`, `scale`, `rotate`, `transition`, `anim`, `animDelay`, `reveal`, `parallax` |

Serbest uzunluklar `[12px]`, `[1.5rem]`, `[50%]`, `[80vh]` biçimindedir (negatif yalnız margin’de); serbest renkler `[#hex]`, `[rgb(…)]`, `[rgba(…)]` ya da `[var(--theme-color-<anahtar>)]`; yazı tipi yalnız yerleşik `[var(--font-<id>)]`. `reveal` (görününce animasyon) ve `parallax` kontrolleri yayında `TecofRender`’ın küçük bir çalışma zamanıyla uygulanır; `prefers-reduced-motion`’a uyar.

## Renk kaynakları

Arka plan, metin ve kenarlık renkleri tek bir seçici panelinde beş kaynaktan seçilir:

| Kaynak | Saklanan token | Derlenen sınıf |
| :--- | :--- | :--- |
| Hızlı seçim | `white`, `black`, `transparent` | `bg-white!` |
| Tema renkleri (canlı) | `[var(--theme-color-primary)]` | `bg-[var(--theme-color-primary)]!` |
| Marka skalası (temanın `--color-primary-*` değişkenleri) | `primary-600` | `bg-primary-600!` |
| Tailwind paleti (22 renk × 11 ton) | `red-500` | `bg-red-500!` |
| Özel renk (seçici / hex) | `[#ff6b00]` | `bg-[#ff6b00]!` |

Tema renkleri `--theme-color-*` değişkenlerine bağlanır: tema panelinde rengi değiştirmek bu düğümü de değiştirir ([Canlı tema](https://tecof-app-dev.vercel.app/editor-theme)). Palet verisi `TAILWIND_PALETTE` ve `TAILWIND_SHADES` olarak dışa aktarılır.

## CSS’i kim üretir

`TecofRender`, dokümanda kullanılan her stil sınıfının CSS’ini **kendisi üretip** sayfaya `<style data-tecof-styles>` olarak basar; editör kanvası da aynı üreteci kullanır. Bu yüzden:

- `TecofRender` ile yayınlanan sayfalarda Tailwind safelist’i **gerekmez**,
- serbest değerler (`p-[10px]!`, `bg-[#ff0000]!`) de ek kurulum olmadan çalışır,
- editörde gördüğünüz ile yayındaki sonuç aynı kuralları paylaşır.

> [!CAUTION] Studio sınıflarını temanın Tailwind derlemesine eklemeyin
> Aynı sınıf adları için Tailwind mobil-öncelikli (`min-width`) kurallar üretir ve `TecofRender`’ın masaüstü-öncelikli kurallarıyla çakışır: ör. `md:p-[40px]!` Tailwind’de 768 px **ve üstünde**, Studio’da 768 px **ve altında** uygulanır. `TecofRender` kullanan temada `getSafelist()` çıktısını Tailwind `safelist`’ine ya da `@source inline()` içine koymayın.

`getSafelist()` (tüm preset sınıfları), `collectStyleClasses(styles)` ve `collectDocumentClasses(pageData)` (bir dokümanda kullanılan tüm sınıflar) analiz ve özel araçlar için dışa aktarılmaya devam eder; örneğin bir sayfanın hangi stil sınıflarını kullandığını raporlamak için:

```ts
import { collectDocumentClasses } from "@tecof/theme-editor";

const used = collectDocumentClasses(page.publishedData); // string[]
```

## Tema marka paleti

Stil editöründeki **marka skalası** token’ları (`primary-50` … `primary-950`) temanın renk değişkenine bağlanır: `TecofRender`, `bg-primary-600!` için `background-color: var(--color-primary-600, var(--tecof-brand-600))` üretir. `--tecof-brand-*` yalnız editörün CSS’inde tanımlıdır; yayın sayfasında rengin görünmesi için temanın `--color-primary-*` değişkenlerini tanımlaması gerekir. Tailwind v4’te bunu `@theme` bloğu yapar (değişkenleri CSS custom property olarak yayınlar). Tailwind paleti token’ları (`red-500` gibi) ise `var(--color-red-500, <varsayılan hex>)` olarak üretildiği için tema tanımlamasa da çalışır.

```css title="app/globals.css"
@import "tailwindcss";

@theme {
  --color-primary-50: #faffe4;
  --color-primary-100: #f2ffc5;
  --color-primary-200: #e3ff92;
  --color-primary-300: #ceff53;
  --color-primary-400: #b6fb20;
  --color-primary-500: #9ae600;
  --color-primary-600: #74b500;
  --color-primary-700: #588902;
  --color-primary-800: #476c08;
  --color-primary-900: #3c5b0c;
  --color-primary-950: #1d3300;
}
```

> [!NOTE] Editör arayüzü renkleri ayrıdır
> `--tecof-primary-*` ve `--tecof-accent*` değişkenleri yalnız editörün kendi arayüzünü boyar. Sayfa içeriği `--theme-*` (tema) ve temanın `@theme` değişkenlerinden beslenir; ikisini karıştırmayın.

## Sayfalar arası stil

Bir bileşenin stilini aynı temadaki diğer sayfalarda eşleşen bileşenlere taşıyabilirsiniz. Yalnız `_tecofStyles` taşınır; içerik değişmez.

| Mod | Nerede | Ne yapar |
| :--- | :--- | :--- |
| Tek seferlik | Stil sekmesi → “Diğer sayfalara uygula…”, `⌘K`, sağ tık menüsü | Seçilen sayfalardaki eşleşen bileşenlere stili bir kez yazar |
| Sürekli senkron | Stil sekmesi → “Bu bileşeni stil kaynağı yap” | Düğüme `_tecofStyleSync` yazar; sayfa her kaydedildiğinde backend yayılımı kendisi yapar |

Eşleşme kuralları (editör ve backend aynı): `node.type` aynı olmalı; “yalnız aynı adlı” seçilirse `props._layerName` ya da `props.name` eşit olmalı; **ortak bileşenler atlanır**; hedefte stil kaynağı olan düğüm ezilmez, çakışma olarak raporlanır. Stil birleştirilmez, **değiştirilir**; yalnız taslaklar yazılır (hedef sayfaları ayrıca yayınlayın); kaynak sayfa hedeflere dahil edilmez.

Kendi arayüzünü kuran host’lar için aynı kurallar dışa açıktır:

```ts
import { STYLE_SYNC_PROP, buildStyleMatch, buildStyleSyncFlag, isStyleSourceNode, mergeStyleSyncPages } from "@tecof/theme-editor";

const preview = await client.previewApplyStyles({ sourcePageId, sourceNodeId, styles, match: { type: "HeroSection" } });
await client.applyStylesToPages({ sourcePageId, sourceNodeId, styles, match: { type: "HeroSection" }, targetPageIds: ["…"], preview: false });
```

Uç: `POST /api/store/editor/apply-styles` (JWT + ekip/admin yetkisi).

---

# Canlı Tema ve Karanlık Mod

> Canlı tema — ThemeConfig, tema birleştirme sırası, Studio Tema paneli ve hazır paletler, --theme-* CSS değişkenleri, fontlar, karanlık mod (config.darkMode) ve tema yardımcıları.
>
> Kaynak: https://tecof-app-dev.vercel.app/editor-theme · Bölüm: Tema geliştirme · Son güncelleme: 2018-10-20

Studio’daki **Tema** paneli sayfanın renklerini, tipografisini ve boşluk değerlerini düzenler. Değişiklikler hem editöre hem kanvasa anında `--theme-*` CSS değişkenleri olarak uygulanır; yayında `TecofRender` aynı değişkenleri kendisi basar.

## Tema modeli

```ts
interface ThemeConfig {
  colors: ThemeColors;          // primary, secondary, accent, background, foreground, muted,
                                // mutedForeground, border, card, cardForeground, destructive
  darkColors?: Partial<ThemeColors>; // yalnız config.darkMode açıkken
  typography: ThemeTypography;  // fontFamily, headingFontFamily, baseFontSize, lineHeight,
                                // headingScale { h1…h6 }, fontWeightNormal/Medium/Bold
  spacing: ThemeSpacing;        // containerMaxWidth, sectionPaddingY/X, componentGap,
                                // borderRadius, borderRadiusLg, borderRadiusSm
  customTokens?: Record<string, string>;
  customFonts?: CustomFont[];   // yüklenen @font-face dosyaları
  fonts?: string[];             // kullanılan yerleşik font kimlikleri
}
```

**Birleştirme sırası:** yerleşik varsayılanlar ← `config.theme` (temanın marka değerleri) ← sayfanın kendi ayarı (`root.props._tecofTheme`, Tema panelinde düzenlenen). Tema sayfa verisinde saklandığı için kayda, geri al ve yinele akışına dahildir.

```tsx title="app/editor-config.tsx"
export const editorConfig: StudioConfig = {
  components,
  theme: {
    colors: { primary: "#a3472f", background: "#f5f3ed", foreground: "#242721", border: "#d7d7cc" },
    typography: { fontFamily: "'Inter', sans-serif", headingFontFamily: "'Inter', sans-serif", lineHeight: 1.7 },
    spacing: { containerMaxWidth: 1440, sectionPaddingY: 96, borderRadius: 0 },
    fonts: ["inter"],
  },
  themePresets: [
    { id: "clay", label: "Kil", colors: { primary: "#a3472f", accent: "#a3472f", background: "#f5f3ed" } },
    { id: "forest", label: "Orman", colors: { primary: "#365745", accent: "#365745", background: "#f2f4ef" } },
  ],
};
```

`themePresets` Tema panelindeki **Renkler** bölümünün üstünde kart olarak listelenir; tıklayınca yalnız renkler `_tecofTheme.colors` üzerine uygulanır (tipografi ve boşluk değişmez), kullanıcı sonra tek tek renkleri düzenlemeye devam edebilir.

## CSS değişkenleri

`generateCSSVariables(theme)` aşağıdaki değişkenleri üretir:

| Grup | Değişkenler |
| :--- | :--- |
| Renkler | `--theme-color-primary`, `-secondary`, `-accent`, `-background`, `-foreground`, `-muted`, `-muted-foreground`, `-border`, `-card`, `-card-foreground`, `-destructive` |
| Tipografi | `--theme-font-family`, `--theme-heading-font-family`, `--theme-font-size-base`, `--theme-line-height`, `--theme-font-weight-normal/-medium/-bold`, `--theme-heading-h1` … `-h6` |
| Fontlar | `--font-<id>` (ör. `--font-inter`) |
| Boşluk | `--theme-container-max-width`, `--theme-section-padding-y/-x`, `--theme-component-gap`, `--theme-border-radius`, `-lg`, `-sm` |

Bileşenlerinizde tema rengini doğrudan kullanın; tema panelindeki değişiklik bileşene yansır:

```tsx
<section className="bg-[var(--theme-color-background)] text-[var(--theme-color-foreground)]">…</section>
```

## Yayına uygulama

`TecofRender` çözülmüş temadan `<style data-tecof-theme>` (tema değişkenleri), Google Fonts `<link>`’i ve yüklenen fontlar için `@font-face` kurallarını **kendisi** basar. Ek kurulum gerekmez.

Sayfayı kendiniz render ediyor ya da `<head>`’i kendiniz kuruyorsanız aynı çıktıyı yardımcılarla üretin:

```ts
import { generateCSSVariables, getDefaultTheme, mergeTheme, themeGoogleFontsHref, themeFontFaceCss } from "@tecof/theme-editor";

const theme = mergeTheme(getDefaultTheme(), editorConfig.theme ?? {});
const css = generateCSSVariables(theme);            // ":root { --theme-color-primary: … }"
const fontsHref = themeGoogleFontsHref(theme);       // Google Fonts adresi ya da boş
const fontFaces = themeFontFaceCss(theme);           // yüklenen fontlar için @font-face
```

Ek yardımcılar: `hexToHsl`, `hslToHex`, `lighten`, `darken`, `deriveDarkColors`, `googleFontsHref`, `customFontFaceCss`, `BUILTIN_FONTS`.

## Fontlar

Tema panelindeki font seçici önizlemeli, küratörlü bir listeden seçtirir ve özel font yüklemeye izin verir. Yerleşik font kimlikleri: `system`, `georgia`, `inter`, `roboto`, `open-sans`, `lato`, `montserrat`, `poppins`, `nunito`, `work-sans`, `dm-sans`, `raleway`, `playfair-display`, `merriweather`, `lora`, `oswald`, `bebas-neue`, `jetbrains-mono`. Seçilen font hem tema değişkenine hem `theme.fonts` listesine yazılır; Stil sekmesindeki düğüm bazlı yazı tipi `[var(--font-<id>)]` token’ı kullanır.

## Karanlık mod

Karanlık mod **isteğe bağlıdır** ve temanın config’inde açılır. `darkMode` yoksa karanlık arayüz, karanlık CSS ve çalışma zamanı hiç yüklenmez.

```tsx
export const editorConfig: StudioConfig = {
  components,
  darkMode: true, // ya da { defaultMode: "system" | "light" | "dark", storageKey: "shop-scheme" }
};
```

**Strateji:** `<html>` üzerindeki `.dark` sınıfı `--theme-color-*` değişkenlerinin **değerlerini** değiştirir; `generateCSSVariables` ikinci bir blok basar:

```css
:root      { --theme-color-background: #ffffff; /* … */ }
:root.dark { --theme-color-background: #09090b; /* … */ }
```

Sayfa içeriğinin sınıfları değişmez (`bg-[var(--theme-color-primary)]` aynı kalır); yalnız değişkenin çözüldüğü değer değişir. Bu yüzden `dark:` varyantı kullanılmaz ve hiçbir safelist gerekmez.

- **Koyu renkler** Tema panelinde düzenlenir (`theme.darkColors`) ya da “Koyu palet üret” ile açık paletten türetilir (`deriveDarkColors`). Girilmeyen anahtar açık moddaki değerine düşer.
- **Editörde önizleme:** üst çubuktaki güneş/ay düğmesi kanvası koyu palete çevirir (yalnız `darkMode` açıkken görünür; dokümana yazılmaz).
- **Ziyaretçi düğmesi:** sayfaya `class="tecof-darkmode-toggle"` taşıyan herhangi bir buton koyun. Çalışma zamanı tıklamayı delege dinler, `.dark`’ı çevirir ve seçimi `localStorage`’a yazar (varsayılan anahtar `tecof-color-scheme`).
- **İlk şema:** `defaultMode` — `system` (varsayılan, işletim sistemini izler), `light` ya da `dark`. Ziyaretçinin kayıtlı seçimi her zaman kazanır.
- **Yanlış tema flaşı olmasın:** `TecofRender` `<head>` üretmez; sıfır flaş için `<head>`’e `darkModeHeadScript(config)` çıktısını satır içi betik olarak koyun.

```tsx title="app/layout.tsx"
import { darkModeHeadScript } from "@tecof/theme-editor";
import { editorConfig } from "@/app/editor-config";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="tr" suppressHydrationWarning>
      <head>
        <script dangerouslySetInnerHTML={{ __html: darkModeHeadScript(editorConfig) }} />
      </head>
      <body>{children}</body>
    </html>
  );
}
```

Kendi sayfasını render eden host’lar için: `initDarkMode(document)`, `darkModeHeadScript(config)`, `deriveDarkColors(light)`, `DARK_MODE_STORAGE_KEY`.

---

# Yayın Render’ı

> TecofRender ile yayın — prop’lar, sayfaya bastığı stil/tema/font çıktısı, CMS şablon sayfaları ve token’lar, TecofPicture ve odak noktası, Powered by bandı, yapım aşaması sayfası ve etkileşim çalışma zamanı.
>
> Kaynak: https://tecof-app-dev.vercel.app/editor-render · Bölüm: Tema geliştirme · Son güncelleme: 2018-10-20

`TecofRender`, editörün kaydettiği sayfayı yayında çizer. Veri getirmez: sayfayı sunucuda çekip renderer’a verirsiniz. Editörle **aynı** `StudioConfig`’i kullanmalısınız; config’te olmayan `type`’lar sessizce atlanır.

```tsx title="components/RenderClient.tsx"
"use client";

import { TecofRender, type PuckPageData } from "@tecof/theme-editor";
import { editorConfig } from "@/app/editor-config";

export default function RenderClient({ data, cmsData }: { data: PuckPageData; cmsData?: Record<string, unknown> | null }) {
  return <TecofRender data={data} config={editorConfig} cmsData={cmsData} />;
}
```

| Prop | Tip | Açıklama |
| :--- | :--- | :--- |
| `data` | `PuckPageData` | Yayınlanacak doküman (`content`, `root`, `zones`) |
| `config` | `StudioConfig` | Editörle aynı bileşen kaydı |
| `cmsData` | `Record<string, unknown> \| null` | CMS şablon sayfasının kaydı; bileşenlere `puck.metadata.cmsData` olarak iletilir |
| `className` | `string?` | Kök elemana ek sınıf |

## Renderer ne yapar

Her render’da:

1. `config.migrations` varsa dokümanı yükseltir ([İzinler ve migration](https://tecof-app-dev.vercel.app/editor-permissions#veri-migrationi)).
2. Katmanlar’da gizlenen (`_hidden`) düğümleri atlar; yalnız gizli çocukları olan slot boş sayılır.
3. Her düğümün `_tecofStyles` token’larını sınıflara derler ve `className`’e ekler.
4. Slot alanlarını hazır slot elemanları olarak bileşene verir; `repeatSource`’lu slotları satır başına tekrarlar.
5. Sayfaya şunları basar:

| Çıktı | İçerik |
| :--- | :--- |
| `<style data-tecof-styles>` | Dokümanda kullanılan tüm stil sınıflarının CSS’i (masaüstü-öncelikli, bkz. [Stil editörü](https://tecof-app-dev.vercel.app/editor-styles#cssi-kim-uretir)) |
| `<style data-tecof-theme>` | Çözülmüş temanın `--theme-*` değişkenleri (karanlık mod açıksa `:root.dark` bloğu da) |
| `<link>` + `<style data-tecof-font-faces>` | Google Fonts ve yüklenen fontlar |
| `<style data-tecof-animations>` | Giriş animasyonu anahtar kareleri |
| `<script data-tecof-interactions>` | Etkileşim kuralları (yalnız kullanılıyorsa) |
| `<script data-tecof-darkmode>` | Karanlık mod ayarı (yalnız `config.darkMode` açıksa) |

İstemcide küçük bir çalışma zamanı **görününce animasyon** (`reveal`), **parallax**, **etkileşimler** ve **karanlık mod** düğmesini bağlar. Sayfayı `TecofRender` olmadan kendiniz render ediyorsanız aynı davranış için `initInteractions(document)` ve `initDarkMode(document)` dışa aktarılır.

> [!IMPORTANT] Slot yerleşim CSS’i temada olmalı
> `<Slot layout="…">` / `defineSection` slot’larının yerleşim sınıfları (`.tecof-slot-row`, `.tecof-slot-row-wrap`, `.tecof-slot-col`, `.tecof-slot-contents`) yayın sayfasında paket CSS’i yüklenmediği için temanın global CSS’inde (`@layer base`) tanımlı olmalıdır. Tecof çekirdek teması bunları içerir; türev temada kaldırmayın.

## Sayfa verisini çekmek

Tecof temaları sayfayı vitrin ucundan alır:

```ts title="lib/api/store.ts (tecof-theme-core, özet)"
const THEME_ID = process.env.NEXT_PUBLIC_THEME_ID!;
const res = await fetch(`${process.env.NEXT_PUBLIC_BASE_URL}/api/store/render?themeId=${THEME_ID}&locale=${locale}`, {
  method: "POST",
  headers: { "Content-Type": "application/json", "x-secret-key": process.env.NEXT_PUBLIC_MERCHANT_SECRET_KEY! },
  body: JSON.stringify({ slug, themeId: THEME_ID, locale, showDraftData, previewToken }),
});
const json = await res.json();
const pageData = showDraftData ? json.data.draftData : json.data.publishedData;
const cmsData = json.data._cmsData ?? null;
```

Taslak önizleme (`showDraftData`) backend’de imzalı `previewToken` ister; token geçersizse yanıt sessizce yayınlanmış içeriğe düşer. Vitrin anahtarı tarayıcıda gezdiği için tek başına taslak okuma yetkisi sayılmaz.

Yanıt sayfa verisinin yanında SEO alanlarını (`metaTitle`, `metaDescription`, `ogImage`, `noIndex`), sayfaya özel kodu (`customHeadCode`, `customBodyCode`) ve çok dilli adres bilgisini (`localizedSlug`, `slugAlternates`, `redirectTo`) taşır; ayrıntı: [Tema SEO’su](https://tecof-app-dev.vercel.app/seo-geo) ve [Public API](https://tecof-app-dev.vercel.app/public-apis). Aynı akış için `TecofApiClient.getPublishedPage(slug, locale)` de kullanılabilir ([API istemcisi](https://tecof-app-dev.vercel.app/editor-api-client)).

## CMS şablon sayfaları

Bir koleksiyonun şablon sayfası `/<koleksiyon>/<içerik>` adresinde render edilirken **backend** şablondaki token’ları kayıt verisiyle doldurur ve yanıtla birlikte ham kaydı `_cmsData` olarak döner. Renderer token’ları yeniden çözmez; kaydı bileşenlere `puck.metadata.cmsData` olarak iletir.

| Token | Değer |
| :--- | :--- |
| `{{ data.<alan> }}` ya da `{{ <alan> }}` | Kaydın alanı (çok dilli alan istek diline göre çözülür) |
| `{{ url }}` | Render edilen sayfanın tam adresi |
| `{{ siteName }}` | Mağaza adı (ör. `"{{ name }} \| {{ siteName }}"` meta başlığı) |
| `{{ locale }}`, `{{ itemSlug }}`, `{{ collectionSlug }}` | İstek dili ve o dildeki adres parçaları |
| `{{ publishedDate }}` | Okunur yayın tarihi (istek dilinde) |
| `{{ _refs.<alan>.slug }}` | Referans alanının tam nesnesi (alanın kendisi etiket olarak çözülür) |

- Prop’un değeri **yalnız** token ise (`"{{ data.gallery }}"`) dizi/nesne değeri olduğu gibi yerleştirilir; metne gömülü token metne çevrilir, bulunamayan gömülü token boş metne döner.
- Meta başlık ve açıklama da aynı çözümden geçer.
- Editörde metin alanlarındaki `{ }` düğmesi token’ı ekler ([CMS veri bağlama](https://tecof-app-dev.vercel.app/editor-fields#cms-veri-baglama-metin-alanlari)); `{{ item.* }}` token’ları ise repeat zone’a aittir ve kütüphane tarafından çözülür ([Repeat zone](https://tecof-app-dev.vercel.app/editor-slots#repeat-zone-oge-sablonu)).

Bileşen ham kayda ihtiyaç duyarsa:

```tsx
render: ({ puck, className }) => {
  const cms = puck.metadata?.cmsData as { title?: unknown } | null;
  return <article className={className}>{/* cms?.title … */}</article>;
}
```

## TecofPicture

`UploadedFile` kaydından doğru medya adresini seçer, görsel ve videoyu ayırt eder, boyut varyantlarını (`thumbnail`, `medium`, `large`, `full`) kullanır.

```tsx
import Image from "next/image";
import { TecofPicture } from "@tecof/theme-editor";

<TecofPicture data={file} alt="Ürün görseli" size="large" />
<TecofPicture data={file} fill />
<TecofPicture data={file} ImageComponent={Image} imageProps={{ quality: 85, priority: true }} />
<TecofPicture data={file} fancybox fancyboxName="product-gallery" />
```

| Prop | Tip | Açıklama |
| :--- | :--- | :--- |
| `data` | `UploadedFile \| null \| undefined` | Dosya kaydı (UploadField değerinin bir öğesi) |
| `alt` | `string \| null` | Alternatif metin |
| `size` | `thumbnail \| medium \| large \| full` | Boyut varyantı |
| `fill` | `boolean` | Üst kapsayıcıyı kaplar (`position: absolute`) |
| `loading` | `lazy \| eager` | Yükleme stratejisi |
| `width`, `height` | `number` | Boyutlar |
| `className`, `imgClassName`, `style`, `imgStyle` | — | Kapsayıcı ve `img` için sınıf/stil |
| `usePlaceholder`, `blurDataURL` | — | Bulanık yer tutucu |
| `ImageComponent`, `imageProps` | — | Özel görsel bileşeni (ör. Next.js `Image`) ve ek prop’ları |
| `fancybox`, `fancyboxName` | — | Lightbox galerisi |

- **Odak noktası:** dosyada `focalPoint: { x, y }` varsa `object-position: "X% Y%"` uygulanır; `object-fit: cover` kırpmalarında seçilen nokta kadrajda kalır. Kendi `imgStyle.objectPosition` değeriniz kazanır; odak yoksa ya da merkezdeyse çıktı değişmez. Yardımcılar: `focalPointToObjectPosition`, `clampFocalPoint`, `isDefaultFocalPoint`, `DEFAULT_FOCAL_POINT`.
- CMS referans kaydı (`type: "image/reference"`) dosya değildir; `null` render edilir. Stok görsel gibi harici dosyalar kayıttaki mutlak `url`’i kullanır.

## Powered by bandı

Panelde (Ayarlar → Powered by bandı) tanımlanan “Powered by Tecof” bandını basar. Temada elle yazmayın; bileşeni kullanın.

```tsx
import { PoweredBy } from "@tecof/theme-editor";

// Layout (SSR): sunucudaki merchant-info ile ilk boyama; askı/yapım aşamasında null verin
const band = merchantInfo.isSuspended || merchantInfo.isUnderConstruction ? null : merchantInfo.poweredBy ?? null;
<PoweredBy initialData={band} defaultLanguage={merchantInfo.defaultLanguage} locale={locale} />

// <TecofProvider> içinde: kendisi çeker (SWR, 10 dk tekilleştirme)
<PoweredBy />
```

| Prop | Açıklama |
| :--- | :--- |
| `locale` | Dil; verilmezse Studio dili → `<html lang>` → varsayılan dil → ilk dil |
| `defaultLanguage` | SSR’da `merchantInfo.defaultLanguage`; verilmezse dil flaşı olabilir |
| `mode` | `light` / `dark`; verilmezse `<html class="dark">` → `prefers-color-scheme` |
| `initialData` | SSR’dan gelen `merchantInfo.poweredBy`; `null` = band yok, `undefined` = kendisi çeker |
| `apiUrl`, `secretKey` | Provider dışında çekmek için |
| `renderBoth` | İki varyantı da basar, seçimi CSS yapar (JS’siz sıfır flaş) |
| `revalidateOnMount`, `className` | — |

Hak yoksa (`showPoweredBy=false`), mağaza askıdaysa ya da yapım aşamasındaysa bileşen hiçbir şey basmaz (bu bayrakları yalnız kendi çektiği `merchant-info`’dan okur; SSR yolunda süzgeci tema uygular). Kendi işaretlemenizi basmak için `usePoweredBy(options)` → `{ band, html, css, js, visible, isLoading, error, refresh, … }`.

## Yapım aşaması sayfası

```tsx
import { UnderConstruction } from "@tecof/theme-editor/under-construction";

<UnderConstruction title="Çok yakında" description="Mağazamız hazırlanıyor." logoUrl={logo} accentColor="#9ae600" />
```

Prop’lar: `title`, `description`, `subtitle?`, `logoUrl?`, `accentColor?`.

## Etkileşimler

Inspector’ın **Etkileşimler** sekmesinde tanımlanan kurallar (`click` / `hover` → `scrollTo`, `toggleClass`, `show`, `hide`, `toggle`; hedef bir düğüm, `self` ya da sayfa başı `top`) düğümün `_interactions` prop’unda saklanır. `_startHidden` işaretli düğüm bir eylem onu gösterene kadar gizli başlar. `TecofRender` kuralları kendisi bağlar; özel render için `collectInteractionRegistry(doc)` + `initInteractions(document)` kullanılır.

---

# API İstemcisi (TecofApiClient)

> TecofApiClient başvurusu — kurucu, kimlik başlıkları, sayfa/medya/çeviri/CMS/ortak bileşen/e-ticaret metotları, kullandıkları /api/store ve /api/merchant uçları ve hata modeli.
>
> Kaynak: https://tecof-app-dev.vercel.app/editor-api-client · Bölüm: Tema geliştirme · Son güncelleme: 2018-10-20

`TecofApiClient`, editörün ve alanların Tecof backend’iyle konuştuğu istemcidir. `TecofProvider` bir örneğini oluşturup bağlama koyar (`useTecof().apiClient`); sunucu tarafında doğrudan da oluşturabilirsiniz.

```ts
import { TecofApiClient } from "@tecof/theme-editor";

const client = new TecofApiClient(
  process.env.NEXT_PUBLIC_BASE_URL!,             // apiUrl (sondaki / temizlenir)
  process.env.NEXT_PUBLIC_MERCHANT_SECRET_KEY!,  // secretKey → x-secret-key
  process.env.NEXT_PUBLIC_CDN_URL,               // cdnUrl (verilmezse apiUrl)
  undefined,                                     // accessToken (JWT, yazma uçları için)
  process.env.NEXT_PUBLIC_THEME_ID,              // themeId
);

const page = await client.getPublishedPage("anasayfa", "tr");
if (page.success && page.data) console.log(page.data.title);
```

## Kimlik

Her istek `x-secret-key` başlığını taşır. Vitrin anahtarı tarayıcı paketine girdiği için backend yazma uçlarında (sayfa kaydetme, yükleme, ortak bileşen, stil senkronu) ayrıca kullanıcı JWT’si ister: `setAccessToken(token)` ya da kurucunun 4. argümanı ile verilir ve `Authorization` başlığına yazılır. Editörde bu token `TecofEditor`’ün `accessToken` prop’undan gelir.

`themeId` verilirse sayfa okuma, kaydetme ve listeleme istekleri o temaya gider; verilmezse backend mağazanın **aktif** temasına düşer (çok temalı mağazada yanlış temanın sayfaları gelir).

## Metotlar

| Metot | Uç | Açıklama |
| :--- | :--- | :--- |
| `getPage(id, signal?, revisionId?)` | `GET /api/store/editor/:id` | Editör taslağı; `revisionId` ile revizyon anlık görüntüsü |
| `savePage(id, draftData, title?, accessToken?)` | `PUT /api/store/editor/:id` | Taslağı kaydeder (`{ draftData, title?, themeId? }`) |
| `getPublishedPage(slug, locale?)` | `POST /api/store/render` | Yayınlanmış sayfa |
| `getMerchantInfo()` | `GET /api/store/merchant-info` | Diller, varsayılan dil, ürün tipi, Powered by bandı, askı/yapım bayrakları |
| `uploadFile(file, folder?)` | `POST /api/store/upload` | Çok parçalı yükleme (alan adı `files`) |
| `getUploads(page = 1, limit = 50)` | `GET /api/store/uploads` | Medya kütüphanesi |
| `getPages()` | `GET /api/store/pages` | Bağlantı seçici için sayfa listesi (`_id, slug, title, status, metaTitle`) |
| `translate(text, sourceLang, locales, isHtml = false)` | `POST /api/store/translate` | Çoklu dil çevirisi → `[{ code, value }]` |
| `searchStockMedia(query, { provider?, page?, perPage?, orientation? })` | `GET /api/store/stock-media/search` | Stok görsel arama |
| `importStockMedia({ provider, downloadUrl, id?, alt? })` | `POST /api/store/stock-media/import` | Stok görseli kütüphaneye alır |
| `getCmsCollections()` | `POST /api/store/cms/collections` | Koleksiyonlar |
| `getCmsCollectionItems(slug, { page, limit, sort, locale, filters, sortBy, sortDir })` | `POST /api/store/cms/collections/:slug/items` | Canlı öğeler → `{ items, totalData }` |
| `getSharedComponents()` · `createSharedComponent(name, type, props)` · `updateSharedComponent(id, name, type, props)` · `deleteSharedComponent(id)` | `/api/store/shared-components` | Ortak bileşenler |
| `previewApplyStyles(payload)` · `applyStylesToPages(payload)` | `POST /api/store/editor/apply-styles` | Sayfalar arası stil (önizleme / uygulama) |
| `getComponentPreview(domain, componentName)` | `POST /api/store/component-preview` | Bileşen önizleme görseli (blob URL, önbellekli) |
| `getEcommerceCategories(locale)` · `getEcommerceBrands(locale)` · `getEcommerceProducts(…)` | `GET /api/store/ecommerce/*` | Vitrin e-ticaret listeleri |
| `getEcommerceTags` · `getEcommerceAttributes` · `getEcommerceVariantTypes` · `getEcommerceFlashSales` · `getEcommerceCampaigns` · `getEcommerceDiscounts` | `GET /api/merchant/ecommerce/*` | Panel listeleri (JWT + `x-merchant-id`; kimlik `merchant-info`’dan bir kez çözülür) |
| `setAccessToken(token?)` · `getAccessToken()` | — | JWT yönetimi |
| `setMerchantId(id?)` | — | Panel uçları için mağaza kimliğini elle verir |
| `getRealtimeConfig()` | — | Canlı katılım soketi için `{ url, token }` |
| `cdnUrl` | — | Medya adresleri için CDN kökü |

## Hata modeli

Metotların çoğu ağ hatasını fırlatmak yerine `{ success: false, message }` zarfına çevirir; başarılı yanıt `{ success: true, data }` biçimindedir:

```ts
const res = await client.savePage(pageId, draftData);
if (!res.success) {
  console.error(res.message);
}
```

İstisna: `getPage` iptal edilen istekleri ayırt edebilmeniz için `AbortError`’ı **yeniden fırlatır** (yeni yükleme eskisini geçersiz kıldığında eski sonucu yok saymak için):

```ts
const controller = new AbortController();
try {
  const res = await client.getPage(pageId, controller.signal);
} catch (error) {
  if (error instanceof DOMException && error.name === "AbortError") return; // iptal, hata değil
  throw error;
}
```

## Pratik notlar

- Yükleme isteğinde `Content-Type`’ı elle vermeyin; çok parçalı sınırı tarayıcı ekler.
- Backend’in `x-secret-key` ve `Authorization` başlıklarına CORS izni verdiğinden emin olun.
- CDN adresi kuran kodda dosyanın `folder` alanını hesaba katın; klasörsüz `${cdnUrl}/${name}` kapsamlı klasördeki dosyada 404 verir. `TecofPicture` bunu sizin yerinize yapar.

---

# iframe ve postMessage

> Tecof Studio’yu bir panel ya da uygulama içine iframe ile gömme — puck:* postMessage protokolü (kaydet, geri al, refetch, highlight, viewport), editörden gelen olaylar ve hostOrigin ile origin güvenliği.
>
> Kaynak: https://tecof-app-dev.vercel.app/editor-iframe · Bölüm: Tema geliştirme · Son güncelleme: 2018-10-20

Tecof paneli tema editörünü bir iframe içinde açar ve onunla `postMessage` üzerinden konuşur. Aynı protokolü kendi panelinizde ya da aracınızda kullanabilirsiniz. Mesaj tipleri geriye dönük uyumluluk için `puck:` önekini korur; bu, motorun Puck olduğu anlamına gelmez.

```mermaid
sequenceDiagram
    participant Host as Panel (üst pencere)
    participant Studio as Tecof Studio (iframe)
    Host->>Studio: puck:save
    Studio-->>Host: puck:saved { data }
    Host->>Studio: puck:viewport { width: "375px" }
    Studio-->>Host: puck:itemSelected { item: { type, id } }
    Host->>Studio: puck:refetch { highlightType }
```

## Üst pencere → editör

| Mesaj | Ek alanlar | Etki |
| :--- | :--- | :--- |
| `puck:save` | — | Taslağı kaydeder |
| `puck:publish` | — | Yalnız taslak kaydını tetikler; yayınlama panel/backend işidir |
| `puck:undo` / `puck:redo` | — | Geri al / yinele |
| `puck:refetch` | `highlightType?` | Taslağı sunucudan yeniden yükler (ör. bir AI ajanı taslağı sunucuda değiştirdiyse); verilirse o tipteki bileşen kanvasta vurgulanır |
| `puck:highlight` | `componentType` | Verilen tipteki bileşeni kanvasta vurgular |
| `puck:viewport` | `width` | `"375px"` / `375` → mobil, `"768px"` / `768` → tablet, diğer her değer → masaüstü |

```ts
const iframe = document.querySelector<HTMLIFrameElement>("#studio")!;
const EDITOR_ORIGIN = "https://tema.ornek.com";

iframe.contentWindow?.postMessage({ type: "puck:save" }, EDITOR_ORIGIN);
iframe.contentWindow?.postMessage({ type: "puck:viewport", width: "375px" }, EDITOR_ORIGIN);
```

## Editör → üst pencere

| Mesaj | Ek alanlar | Ne zaman |
| :--- | :--- | :--- |
| `puck:changed` | — | Doküman değişti (~300 ms debounce) |
| `puck:saved` | `data` (güncel taslak) | Kayıt başarılı |
| `puck:saveError` | `message` | Kayıt başarısız (revizyon önizlemesinde kaydetme denemesi dahil) |
| `puck:itemSelected` | `item: { type, id }` | Bir düğüm seçildi (Esc ile üst düğüme çıkıldığında da) |
| `puck:itemDeselected` | — | Seçim kaldırıldı |

```ts
window.addEventListener("message", (event) => {
  if (event.origin !== EDITOR_ORIGIN) return;
  switch (event.data?.type) {
    case "puck:changed":
      markDirty();
      break;
    case "puck:saved":
      markSaved(event.data.data);
      break;
    case "puck:saveError":
      showError(event.data.message);
      break;
    case "puck:itemSelected":
      showContextFor(event.data.item.type, event.data.item.id);
      break;
  }
});
```

Editör yalnız bir iframe içinde çalışırken mesaj gönderir; doğrudan açıldığında köprü sessizdir.

## Origin güvenliği

Gömülü kullanımda `hostOrigin` prop’unu **mutlaka** verin. Editör gelen mesajların `event.origin` değerini bununla karşılaştırır ve giden mesajları yalnız bu origin’e yollar. Prop verilmezse geriye uyumluluk için `'*'` kullanılır: her origin mesaj gönderebilir ve taslak verisi (`puck:saved`) her üst pencereye gider.

```tsx
<TecofEditor pageId={pageId} config={editorConfig} accessToken={token} hostOrigin="https://app.tecof.com" />
```

Kontrol listesi:

1. `hostOrigin` ile üst pencerenin origin’i birebir aynı olmalı (şema ve port dahil).
2. Mesajı `iframe.contentWindow`’a, hedef origin’i açıkça vererek gönderin.
3. Gelen mesajda `event.origin`’i ve `puck:` tipini doğrulayın.
4. Panel editöre JWT’yi adres parametresiyle verir (`?token=`); editör rotasını herkese açık bir sayfadan bağlamayın.

---

# İzinler ve Migration

> Düğüm izinleri (drag, delete, duplicate, edit) ve katman sırası, resolvePermissions, kilitli düğümler; MigrationConfig ile eski sayfa verisini yeni şemaya güvenle yükseltme.
>
> Kaynak: https://tecof-app-dev.vercel.app/editor-permissions · Bölüm: Tema geliştirme · Son güncelleme: 2018-10-20

## İzin modeli

İzinler varsayılan olarak **açıktır**; kısıtlamaya bir bayrağı `false` yaparak katılırsınız.

```ts
interface Permissions {
  drag: boolean;      // kanvas ve katmanlarda taşıma
  delete: boolean;    // tekli/toplu silme ve kesme
  duplicate: boolean; // çoğaltma ve yeni id ile yapıştırma
  edit: boolean;      // Inspector alanlarının düzenlenmesi
  [key: string]: boolean; // host’a özel ek izinler
}
```

Bir düğümün etkin izni katmanların birleşimidir; sonraki katman öncekini ezer:

```text
varsayılan < config.permissions < component.permissions < component.resolvePermissions(props) < düğümün _locked kilidi
```

```ts
const editorConfig: StudioConfig = {
  permissions: { delete: false },            // genel: hiçbir şey silinemez
  components: {
    Header: {
      permissions: { drag: false },          // header taşınamaz
      resolvePermissions: (props) => ({ edit: !props.locked }),
      render: (p) => <header className={p.className} />,
    },
    Hero: {
      permissions: { delete: true },         // Hero için silmeye yeniden izin ver
      render: (p) => <section className={p.className} />,
    },
  },
};
```

- Kısıtlar **motor seviyesinde** uygulanır: düğme gizlemekle kalmaz; klavye kısayolları (`⌘D`, `Delete`), sağ tık menüsü ve pano işlemleri de aynı kurala uyar.
- `edit: false` Inspector alanlarını salt okunur yapar.
- Delete izni olmayan düğümde **kes** işlemi düz kopyalamaya döner.
- Eksik anahtar ya da `resolvePermissions`’ın fırlattığı hata izinleri **sıkılaştırmaz**; o katman bir alttakinden devralınır. Hatalı bir çözümleyici kullanıcıyı kilitlemez.
- Katmanlar panelindeki kilit (`_locked`) aynı izin sistemini kullanır. Kilitli düğüm seçilebilir kalır (kilidi açabilmek için).

### Dinamik izinler

```ts
resolvePermissions?: (props: any, ctx: { changed: Record<string, boolean>; lastProps: Record<string, any> | null }) => Partial<Permissions>;
```

`ctx.changed` son çözümden beri değişen prop’ları, `ctx.lastProps` önceki anlık görüntüyü verir (ilk çalıştırmada `null`); yalnız ilgili alan değiştiğinde yeniden hesap yapmak için kullanın.

## Veri migration’ı

Bir bileşenin tip adı ya da prop şeması değiştiğinde önceden kaydedilmiş sayfalar eski şemada kalır. `migrations`, belge editörde yüklenirken **ve** `TecofRender` ile render edilirken otomatik uygulanır.

```ts
interface MigrationConfig {
  version?: number;                                   // hedef şema sürümü
  renameComponents?: Record<string, string>;          // { eskiTip: yeniTip }
  transformProps?: Record<string, (props: any) => any>; // YENİ tip adına göre
  migrate?: (doc: TecofDocument) => TecofDocument;     // son, serbest geçiş
}
```

```ts
const editorConfig: StudioConfig = {
  components,
  migrations: {
    version: 3,
    renameComponents: { OldHero: "Hero" },
    transformProps: {
      // Rename SONRASI tipe göre aranır: anahtar "Hero"
      Hero: (props) => ({ ...props, eyebrow: props.eyebrow ?? "", title: props.headline ?? props.title }),
    },
    migrate: (doc) => doc,
  },
};
```

### Çalışma sırası

1. `renameComponents` ile her düğümün `type`’ı değiştirilir.
2. Yeni tip adına göre `transformProps[type]` çalışır; düğüm `id`’si her zaman korunur.
3. Varsa tüm belgeye `migrate(doc)` uygulanır.
4. `version` tanımlıysa hedef sürüm `root.props._schemaVersion`’a yazılır.

### İdempotentlik

`version` verildiyse, `_schemaVersion`’ı zaten o sürümde ya da üstünde olan belge **dokunulmadan** döner. `version` verilmezse geçiş her yüklemede çalışır; bu durumda `transformProps` ve `migrate` kendi başlarına idempotent olmalıdır. Bir dönüşüm hata fırlatırsa o düğüm/belge değişmeden bırakılır; tek bir hata sayfayı kilitlemez.

> [!TIP] Zone anahtarları etkilenmez
> Zone anahtarları düğüm **id**’sine göre tutulur (`nodeId:slotAdı`), tipe göre değil. `renameComponents` hiçbir zaman zone anahtarlarının yeniden yazılmasını gerektirmez.

---

# Klavye Kısayolları

> Tecof Studio klavye kısayolları — komut paleti, kaydet, geri al/yinele, pano, çoğalt, sil, kılavuz/boyutlandırma/boşluk modları, seçim ve gezinme.
>
> Kaynak: https://tecof-app-dev.vercel.app/editor-shortcuts · Bölüm: Tema geliştirme · Son güncelleme: 2018-10-20

macOS’ta `⌘`, Windows ve Linux’ta `Ctrl` kullanılır.

| Kısayol | İşlem |
| :--- | :--- |
| `⌘K` | Komut paletini aç / kapat |
| `⌘S` | Taslağı kaydet |
| `⌘Z` | Geri al |
| `⌘⇧Z` · `⌘Y` | Yinele |
| `⌘C` · `⌘X` · `⌘V` | Seçili düğümleri kopyala · kes · yapıştır |
| `⌘D` | Çoğalt (çoklu seçimde toplu) |
| `Delete` · `Backspace` | Sil (çoklu seçimde toplu) |
| `↑` `←` · `↓` `→` | Aynı listedeki önceki · sonraki kardeş düğümü seç |
| `⌘` + tık · `⇧` + tık | Çoklu seçime ekle / çıkar |
| `Esc` | Paleti kapat; açık pencere yoksa üst düğümü seç; üst yoksa seçimi kaldır |
| `G` | Sütun kılavuz ızgarasını aç / kapat |
| `R` | Boyutlandırma modunu aç / kapat (genişlik/yükseklik tutamaçları) |
| `B` | Boşluk tutamaçlarını aç / kapat (padding/margin sürükleme) |

- Bir giriş alanı odaktayken pano kısayolları tarayıcının kendi kopyala/yapıştırına bırakılır; kanvas kısayolları (`G`, `R`, `B`, oklar, `Delete`) çalışmaz.
- Bir pencere (drawer) açıkken kanvas kısayolları ve geri al/yinele devre dışıdır; `⌘K` ve `Esc` çalışmaya devam eder.
- İzinler kısayollara da uygulanır: silme izni olmayan düğüm `Delete` ile silinmez ([İzinler](https://tecof-app-dev.vercel.app/editor-permissions)).

## Komut paleti

`⌘K` tek bir aramada **eylemleri** (geri al/yinele, kopyala/kes/yapıştır, çoğalt, sil, önizleme, panelleri aç/kapat, kaydet, stili diğer sayfalara uygula — her birinin kısayolu yanında yazar) ve **bileşen eklemeyi** (config’teki tüm bileşenler) birleştirir. Ok tuşlarıyla gezilir, `Enter` ile çalıştırılır. Arama Türkçe karakterlere duyarsızdır: “HAKKIMIZDA”, “hakkimizda” ve “hakkımızda” aynı sonucu bulur (`normalizeSearch`). `config.ai` tanımlıysa **AI ile bölüm üret** de buradadır.

## Pano

Kopyalanan düğümler `localStorage`’da `tecof:clipboard:v1` anahtarıyla tutulur; farklı sekme ve sayfalar arasında yapıştırılabilir. Yapıştırılan düğüm ve alt zone’ları için yeni id’ler üretilir. Stil panosu ayrı tutulur (`tecof:style-clipboard:v1`).

---

# Sorun Giderme

> Tecof Studio ve TecofRender için sık sorunlar ve çözümleri — seçilemeyen bileşen, yayında görünmeyen stil veya bileşen, boş repeat şablonu, API/CORS/yükleme hataları, iframe mesajları ve üretim kontrol listesi.
>
> Kaynak: https://tecof-app-dev.vercel.app/editor-troubleshooting · Bölüm: Tema geliştirme · Son güncelleme: 2018-10-20

## Bileşen kanvasta seçilemiyor

1. Bileşen `props.className`’i **kök DOM elemanına** basıyor mu? Her dal (erken `return`’ler dahil) basmalı. `defineSection` / `defineElement` bunu otomatik yapar ([Kök className sözleşmesi](https://tecof-app-dev.vercel.app/editor-components#kok-classname-sozlesmesi)).
2. `render` bir bileşen elemanı döndürüyorsa o bileşen `className` prop’unu kendi kökünde kullanıyor mu?
3. `inline: true` bileşende `puck.dragRef` köke bağlı mı?

## Stil sekmesinde verilen stil görünmüyor

1. Aynı nedenle: `className` köke ulaşmıyorsa stil sınıfları da ulaşmaz.
2. Doğru katmanı mı düzenliyorsunuz? Kırılımlar **masaüstü önceliklidir**: `md` 768 px ve **altında** uygulanır ([Stil editörü](https://tecof-app-dev.vercel.app/editor-styles#kirilimlar-masaustu-onceliklidir)).
3. Temanın Tailwind derlemesinde Studio sınıflarını safelist’e eklediyseniz kaldırın; mobil-öncelikli kurallar `TecofRender`’ın kurallarıyla çakışır.
4. Marka skalası (`primary-*`) yayında renksiz görünüyorsa temanın `--color-primary-*` değişkenlerini tanımladığını doğrulayın ([Tema marka paleti](https://tecof-app-dev.vercel.app/editor-styles#tema-marka-paleti)).

## Bileşen editörde var, yayında yok

1. Editör ve renderer **aynı** `StudioConfig` nesnesini mi kullanıyor? Kayıtlı `type` yayındaki config’te yoksa düğüm sessizce atlanır.
2. Tip adını değiştirdiyseniz `migrations.renameComponents` ekleyin ([Migration](https://tecof-app-dev.vercel.app/editor-permissions#veri-migrationi)).
3. Düğüm Katmanlar’da gizlenmiş (`_hidden`) olabilir; gizli düğümler yayında render edilmez.

## Slot yerleşimi yayında bozuk

1. `.tecof-slot-*` yerleşim sınıfları temanın global CSS’inde var mı? Yayın sayfası paket CSS’ini yüklemez ([Yayın render’ı](https://tecof-app-dev.vercel.app/editor-render#renderer-ne-yapar)).
2. Repeat slotlarda yayın yerleşimi `<Slot layout>`’tan değil `orientation`’dan gelir ([Slotlar](https://tecof-app-dev.vercel.app/editor-slots#veri-kaynaklari)).

## Repeat şablonu yayında boş

1. `repeatSource` prop’u gerçekten bir **dizi** (ya da API/CMS kaynağı) taşıyor mu? Satır yoksa şablon bilerek hiç render edilmez.
2. CMS kaynağı kullanılıyorsa ağaçta `TecofProvider` var mı?
3. Token yolu satır nesnesindeki alanla eşleşiyor mu (`{{ item.name }}` ↔ `row.name`)?

## Tema renkleri ya da fontlar eksik

`TecofRender` tema değişkenlerini ve fontları kendisi basar. Sayfayı kendiniz render ediyorsanız `generateCSSVariables`, `themeGoogleFontsHref` ve `themeFontFaceCss` çıktısını `<head>`’e ekleyin ([Canlı tema](https://tecof-app-dev.vercel.app/editor-theme#yayina-uygulama)).

## API, CORS ya da yükleme hatası

- API adresinin sonundaki `/` istemci tarafından temizlenir.
- Backend `x-secret-key` ve `Authorization` başlıklarına izin veriyor mu?
- Yükleme isteğinde `Content-Type`’ı elle vermeyin; çok parçalı sınırı tarayıcı ekler.
- Yazma uçları (kaydet, yükle, ortak bileşen) JWT ister: `accessToken` verildi mi, süresi doldu mu?
- Çok temalı mağazada `themeId` verilmezse istekler aktif temaya gider.

## iframe mesajları çalışmıyor

1. `hostOrigin` ile üst pencerenin origin’i birebir aynı mı (şema, alan adı, port)?
2. Mesaj `iframe.contentWindow`’a gönderiliyor mu?
3. Gelen mesajda `event.origin` ve `puck:` tipi doğrulanıyor mu? Ayrıntı: [iframe ve postMessage](https://tecof-app-dev.vercel.app/editor-iframe).

## AI asistanınız API uyduruyor

Asistanı [doküman MCP sunucusuna](https://tecof-app-dev.vercel.app/ai-docs) bağlayın: `search_docs` → `read_doc_page` ile bu belgeleri, `read_type_definition` ile paketin gerçek TypeScript bildirimlerini okur. Çelişkide dışa aktarılan tipler son doğruluk kaynağıdır.

## Üretim kontrol listesi

- [ ] `@tecof/theme-editor/styles.css` editör layout’unda içe aktarıldı.
- [ ] Editör ve renderer aynı `StudioConfig`’i kullanıyor.
- [ ] Her bileşen `className`’i kök DOM elemanına basıyor.
- [ ] `.tecof-slot-*` yerleşim sınıfları temanın global CSS’inde.
- [ ] Studio stil sınıfları temanın Tailwind safelist’ine **eklenmedi**.
- [ ] Gömülü editörde `hostOrigin` verildi; editör rotası yalnız panelden token ile açılıyor.
- [ ] Tip adı değişen bileşenler için `migrations` tanımlandı.
- [ ] Karanlık mod açıksa `<head>`’de `darkModeHeadScript()` var.
- [ ] `@tecof/theme-editor` sürümü `package.json`’da sabit ve [güncel](https://tecof-app-dev.vercel.app/packages#tecoftheme-editor).

---

# Uygulama Geliştirme

> Partner uygulamalarına genel bakış: uygulama türleri, yetenekler, mimari, kimlik bilgileri ve geliştirmeden yayına yaşam döngüsü.
>
> Kaynak: https://tecof-app-dev.vercel.app/app-development · Bölüm: Uygulama geliştirme · Son güncelleme: 2018-10-20

Tecof partner uygulamaları, mağazaların panelden tek tıkla kurduğu üçüncü taraf uygulamalardır. Bir uygulama, mağaza onay verdiği kapsamlarla (scope) Tecof verisini okur ve yazar, webhook ile olayları dinler, panel ekranlarına kendi işlemlerini (aksiyon) ekler, panel içinde iframe arayüzüyle çalışır ve isterse ücretli plan satar. Uygulamanın geliri, partner programının aylık hak ediş akışıyla geliştiriciye ödenir.

Model, ikas App Development'a yakındır: Admin App + Actions + App Bridge + CLI + plan satışı + aylık hak ediş.

> **Durum (11.10.2026):** Platform backend'i uygulandı. `@tecof/cli`, `@tecof/app-sdk`, `@tecof/app-bridge` ve `@tecof/invoice-kit` npm'de yayımlandı (0.1.0). Artımlı push ve sürüm komutları (`tecof app push|versions|promote|rollback`) `@tecof/cli` 0.2.0 ile gelir; [Geliştirici Alanları (Spaces)](https://tecof-app-dev.vercel.app/spaces) sayfasına bakın. Bu bölümdeki uç adları ve alanlar platform sözleşmesini izler; "gelecek" ya da "v2" diye işaretlenen özellikler henüz yoktur.

---

## Uygulama Türleri

| Tür | `embedded` | Ne yapar | Örnek |
| :--- | :--- | :--- | :--- |
| Panel içi (embedded) uygulama | `true` | Panelde iframe arayüzü açar, kendi menü başlıklarını (`navigation`) ekler, App Bridge ile panelle konuşur | Fatura listesi ekranı olan bir muhasebe uygulaması |
| Arka plan (headless) uygulama | `false` | Arayüzü yoktur; webhook alır, API çağırır. Ayarlarını panelin yerel ayar formundan (`settings`) alabilir, `api` tipi aksiyon sunabilir | Stok senkronu, sipariş aktarımı |

Her iki türde de uygulama kendi sunucusunda çalışır: ya Tecof'un yönettiği barındırmada (`hosting: "tecof"`, `tecof app deploy`) ya da sizin altyapınızda (`hosting: "external"`).

---

## Yetenekler

| Yetenek | Ne sağlar | Sayfa |
| :--- | :--- | :--- |
| API erişimi | Kurulum token'ı (`tcfi_…`) ile `/api/v1` üzerinden sipariş, müşteri, ürün, envanter okuma; Tools API ile yazma | [Uygulama API’si](https://tecof-app-dev.vercel.app/app-api) |
| Webhook'lar | Sipariş, ürün, müşteri, içerik olayları ve uygulama yaşam döngüsü olayları; zaman damgalı HMAC imzası | [Webhook'lar](https://tecof-app-dev.vercel.app/app-webhooks) |
| Aksiyonlar | Sipariş, ürün ve müşteri ekranlarına (detay + toplu işlem) iframe ya da API işlemi ekleme | [Aksiyonlar](https://tecof-app-dev.vercel.app/app-actions) |
| App Bridge | iframe ile panel arasında güvenli mesajlaşma: oturum token'ı, bildirim, onay penceresi, yönlendirme | [App Bridge](https://tecof-app-dev.vercel.app/app-bridge) |
| CLI ve barındırma | `tecof` CLI ile giriş, proje oluşturma, tünelle geliştirme, GitHub + Vercel'e dağıtım; `tecof app push` ile artımlı push, numaralı sürümler, yeniden derlemeden canlıya alma ve anında geri alma | [Hızlı Başlangıç](https://tecof-app-dev.vercel.app/app-quickstart), [Sürümler ve Geri Alma](https://tecof-app-dev.vercel.app/versions-and-rollback) |
| Vault | API anahtarı, parola gibi sırları kurulum başına şifreli saklama; uygulamanın kendi veritabanına ihtiyacı kalmaz | [Ayarlar, Vault ve Metafield'lar](https://tecof-app-dev.vercel.app/app-data) |
| Ayarlar ve yerel ayar formu | Kurulum başına JSON ayarlar; panelin "Ayarlar" sekmesinde otomatik form | [Ayarlar, Vault ve Metafield'lar](https://tecof-app-dev.vercel.app/app-data) |
| Metafield'lar | Sipariş, ürün, müşteri ya da mağazaya bağlı uygulama verisi; panelde gösterim | [Ayarlar, Vault ve Metafield'lar](https://tecof-app-dev.vercel.app/app-data) |
| Uygulamalar arası olaylar | Bildirilmiş olayları yayınlama ve başka uygulamaların olaylarına abone olma | [Uygulamalar Arası İletişim](https://tecof-app-dev.vercel.app/app-interop) |
| Ücretli planlar | Aylık/yıllık plan, deneme süresi, iyzico ile tahsilat, %80 geliştirici payı | [Ücretlendirme ve Hak Ediş](https://tecof-app-dev.vercel.app/app-billing) |

---

## Mimari

```mermaid
flowchart LR
    subgraph Panel["Tecof Paneli - app.tecof.com"]
        UI["Uygulama sayfası / aksiyon penceresi"]
    end
    subgraph App["Uygulamanız - appUrl"]
        FE["iframe arayüzü + @tecof/app-bridge"]
        BE["Sunucu rotaları + @tecof/app-sdk"]
    end
    API[("Tecof API - api.tecof.com")]

    UI -- "launch URL + oturum JWT'si (60 sn)" --> FE
    FE -- "postMessage (App Bridge)" --> UI
    FE -- "Authorization: Bearer oturum token'ı" --> BE
    BE -- "client_credentials -> tcfi_ (1 saat)" --> API
    BE -- "/api/v1/* (Bearer tcfi_)" --> API
    API -- "Webhook + API aksiyonu (X-Tecof-Signature)" --> BE
```

Üç güven sınırı vardır:

1. **Panel → iframe:** Panel uygulamaya yalnız 60 saniyelik, istemci sırrınızla imzalı bir oturum JWT'si verir. Panel oturumu (JWT) ve mağazanın `secretKey`'i platform uygulamalarına **asla** verilmez.
2. **Uygulama → Tecof API:** Sunucunuz istemci kimliği + sırrıyla kurulum token'ı alır. Token yalnız kurulu olduğu mağazanın verisine, mağazanın onayladığı kapsamlarla erişir; mağaza kimliği token'dan çözülür.
3. **Tecof → uygulama:** Webhook ve API aksiyonu istekleri `X-Tecof-Signature` ile imzalanır; 5 dakikalık tekrar saldırısı penceresi vardır.

---

## Kimlik Bilgileri Özeti

| Kimlik | Biçim | Ömür | Nerede kullanılır |
| :--- | :--- | :--- | :--- |
| İstemci kimliği | `tcfa_…` | Kalıcı, herkese açık | Token isteği, oturum JWT'sinin `aud` alanı, kurulum bağlantısı |
| İstemci sırrı | `tcfs_…` | Döndürülene kadar; yalnız oluşturma/döndürmede **bir kez** gösterilir | Token isteği, imza doğrulama, oturum JWT'si doğrulama (yalnız sunucuda) |
| Kurulum token'ı | `tcfi_…` | 1 saat | `/api/v1/*` çağrıları (`Authorization: Bearer`) |
| Oturum token'ı | JWT (HS256) | 60 saniye | iframe arayüzünden kendi sunucunuza giden istekler |
| Geliştirici (CLI) token'ı | `tcfd_…` | Cihaz oturumu 30 gün (14 gün kullanılmazsa düşer); kapsamlı CI token'ı 1–365 gün | `tecof` CLI, geliştirici API'si (`/api/developer`) ve alanlar (Spaces). Bkz. [Güvenlik ve CI](https://tecof-app-dev.vercel.app/dev-security) |

Ayrıntılar: [Kimlik Doğrulama ve Kapsamlar](https://tecof-app-dev.vercel.app/app-auth).

---

## Geliştirme Yaşam Döngüsü

```mermaid
flowchart LR
    A["Partner hesabı"] --> B["tecof login"]
    B --> C["tecof app init"]
    C --> D["Test mağazasında geliştirme<br/>tecof app dev"]
    D --> E["tecof app push + promote<br/>ya da tecof app deploy"]
    E --> F["İncelemeye gönderim<br/>draft -> in-review"]
    F --> G["approved: yayın<br/>public / private"]
    G --> H["Kurulumlar + plan satışları"]
    H --> I["Aylık hak ediş<br/>partner ödeme akışı"]
```

1. **Partner hesabı.** Uygulamalar bir partner hesabına aittir. Partner başvurusunda program olarak uygulama geliştirme (`programs: ["apps"]`) seçilir; ajans programı kapalı olsa bile uygulama geliştirici programı (varsayılan **açık**) yeterlidir. Geliştirici olmak için partner kaydınız ve partner üyeliğiniz `active` olmalıdır.
2. **CLI girişi.** `tecof login` cihaz akışıyla tarayıcıda onay ister ve kişisel hesabınıza bağlı bir CLI token'ı alır (30 gün; 14 gün kullanılmazsa düşer). Uygulama komutları her istekte aktif partner üyeliğinizi doğrular.
3. **Proje.** `tecof app init` şablondan proje açar; uygulama yapılandırması `tecof.app.json` dosyasındadır.
4. **Test mağazasında geliştirme.** Onaysız uygulama yalnız `testStores` listesindeki (ekip üyesi olduğunuz) mağazalara kurulur. `tecof app dev` yerel sunucunuzu başlatıp tünelle açar; test mağazası kurulumlarında iframe, webhook'lar ve API aksiyonları bu adrese gider.
5. **Dağıtım.** `tecof app push` yalnız değişen dosyaları Tecof barındırmasına (GitHub org reposu + Vercel projesi) yükleyip staged bir sürüm açar; `tecof app promote vN` onu yeniden derlemeden canlıya alır, `tecof app rollback` önceki canlı sürüme döner. `tecof app deploy` tüm kaynağı yükleyip doğrudan yayınlamaya devam eder. İlk yayında `<slug>.apps.…` alt alan adı bağlanır. Kendi sunucunuzda barındırıyorsanız `hosting: "external"` + `appUrl` kullanırsınız.
6. **İnceleme.** `draft` → `in-review` → `approved` ya da `rejected`. Gönderim için ikon, açıklamalar, destek e-postası, gizlilik politikası, `https` adres ve en az bir yüzey gerekir; ücretli plan içeren uygulama, partner doğrulaması (KYC/IBAN) onaylı değilse incelemeye gönderilemez.
7. **Yayın.** `approved` + `public` uygulama katalogda görünür. `private` dağıtım katalogda görünmez, yalnız doğrudan kurulum bağlantısıyla kurulur.
8. **Kazanç.** Plan satışlarının KDV hariç tutarının varsayılan %80'i, 14 günlük iade penceresi sonunda partner defterinize yazılır ve aylık partner ödeme akışıyla ödenir.

---

## Eski (legacy) entegrasyon modeli

Tecof’un ilk birinci parti uygulamaları `integration: "legacy"` sözleşmesiyle yazılmıştı: iframe’e sorgu dizesiyle `secretKey` ve panel token’ı verilir, ayarlar `/api/store/option` üzerinden okunur, webhook `X-App-Secret` / `X-Webhook-Secret` ile doğrulanırdı. Bu model **yeni uygulamalara açık değildir** ve bu dokümantasyonda anlatılmaz. Tecof’un kendi uygulamaları (fatura, kargo, pazaryeri, SMS…) bu bölümde anlatılan platform sözleşmesine (`integration: "platform"`, `@tecof/app-sdk`, `@tecof/app-ui`) taşınmaktadır; örnek için [Logo İşbaşı](https://tecof-app-dev.vercel.app/app-example-isbasi) ve [Fatura uygulamaları](https://tecof-app-dev.vercel.app/app-invoicing).

---

## Bu Bölümün Sayfaları

| Sayfa | İçerik |
| :--- | :--- |
| [Hızlı Başlangıç: Tecof CLI](https://tecof-app-dev.vercel.app/app-quickstart) | Kurulum, giriş, proje yapısı, tünelle geliştirme, dağıtım, `tecof.app.json` referansı |
| [Tasarım Kimliği](https://tecof-app-dev.vercel.app/app-ui) | `@tecof/app-ui` kurulumu, kabuk ve bileşenler, durum sözlüğü, ekran düzenleri, metin tonu |
| [Formlar ve Şema](https://tecof-app-dev.vercel.app/app-forms) | İstemci ve sunucuda tek şema, `AppForm`, `SecretField`, `validateOnServer` |
| [Sürümler, Canlıya Alma ve Geri Alma](https://tecof-app-dev.vercel.app/versions-and-rollback) | `tecof app push` sürümleri, staged ve production, canlıya alma ve geri alma kuralları, portaldaki **Sürümler** sekmesi |
| [Güvenlik ve CI](https://tecof-app-dev.vercel.app/dev-security) | CLI kimlik bilgileri, kapsamlı CI token'ları, GitHub Actions örneği, ajan modu |
| [Kimlik Doğrulama ve Kapsamlar](https://tecof-app-dev.vercel.app/app-auth) | Kapsam listesi, kurulum token'ı, oturum token'ı, imzalar, sır döndürme |
| [Uygulama API’si](https://tecof-app-dev.vercel.app/app-api) | `/api/v1` zarfı, sayfalama, hız sınırları, kaynak şekilleri, Tools API, uygulamaya özel uçlar |
| [Webhook'lar](https://tecof-app-dev.vercel.app/app-webhooks) | Abonelik, olay kataloğu, teslimat biçimi, yeniden deneme, idempotency |
| [Aksiyonlar](https://tecof-app-dev.vercel.app/app-actions) | Yerleşimler, iframe ve API aksiyonları, yerelde test |
| [App Bridge](https://tecof-app-dev.vercel.app/app-bridge) | Mesaj protokolü, bağlam nesnesi, React sağlayıcısı |
| [Ayarlar, Vault ve Metafield'lar](https://tecof-app-dev.vercel.app/app-data) | Ayarlar, şifreli sırlar, yerel ayar formu, metafield'lar |
| [Uygulamalar Arası İletişim](https://tecof-app-dev.vercel.app/app-interop) | Uygulama olayları, paylaşılan metafield'lar, keşif kataloğu |
| [Ücretlendirme ve Hak Ediş](https://tecof-app-dev.vercel.app/app-billing) | Planlar, KDV, abonelik durumları, gelir paylaşımı, ödeme |
| [Yayınlama ve İnceleme](https://tecof-app-dev.vercel.app/app-publishing) | İnceleme durumları, dağıtım, kontrol listesi, askıya alma |
| [Örnek Uygulama: Logo İşbaşı](https://tecof-app-dev.vercel.app/app-example-isbasi) | Uçtan uca örnek: otomatik fatura, Vault, metafield, aksiyon, olay yayını |

---

## Değişiklik Notları

| Tarih | Değişiklik |
| :--- | :--- |
| 11.10.2026 | Spaces: `tecof app push`, `versions`, `promote`, `rollback` ile artımlı push, numaralı sürümler, yeniden derlemeden canlıya alma ve anında geri alma; `tecof app deploy` çalışmaya devam ediyor |
| 11.10.2026 | CLI oturumu kişisel hesaba bağlandı: onay adresi `/cli`, cihaz token'ı 30 gün (14 gün kullanılmazsa düşer), token işletim sistemi anahtarlığında; partner üyeliği yalnız uygulama uçlarında aranır. Kapsamlı CI token'ları eklendi |
| 10.10.2026 | Platform backend'i uygulandı; bu bölümdeki sözleşme ayrıntıları (yaşam döngüsü olay verileri, yeniden deneme sayısı, `devUrl` davranışı, inceleme kapısı, abonelik geçişleri) kesinleşti |
| 10.10.2026 | Düzeltme: kaldırılan bir uygulama aynı mağazaya yeniden kurulamıyordu; artık yeniden kurulum eski kaydı canlandırır |
| 10.10.2026 | Düzeltme: webhook yeniden denemeleri ve elle yeniden gönderim 8 KB'ta kırpılmış (bozuk) JSON gönderiyordu; artık tam gövde (≤ 256 KB) gönderilir |

---

# Hızlı Başlangıç: Tecof CLI

> Uygulamayı sıfırdan test mağazasında çalıştırıp yayınlama: tecof app init/dev/push/promote, proje yapısı ve tecof.app.json referansı.
>
> Kaynak: https://tecof-app-dev.vercel.app/app-quickstart · Bölüm: Uygulama geliştirme · Son güncelleme: 2018-10-20

Bu sayfa bir partner uygulamasını sıfırdan test mağazasında çalıştırıp Tecof barındırmasına dağıtmayı adım adım anlatır. Örnekler Next.js App Router ve TypeScript kullanır.

**Gerekenler**

| Gereksinim | Not |
| :--- | :--- |
| Node.js 20+ | `@tecof/cli` Node ≥20 ister; uygulamanızın kullandığı `@tecof/app-sdk` Node ≥18 ile çalışır (bağımlılıksız; `node:crypto` + `fetch`) |
| Aktif partner üyeliği | Uygulama geliştirici programına kayıtlı, durumu `active` partner. Bkz. [Uygulama Geliştirme](https://tecof-app-dev.vercel.app/app-development) |
| Test mağazası | Ekip üyesi olduğunuz bir Tecof mağazası. Onaysız uygulama yalnız test mağazalarına kurulur |

---

## 1. CLI Kurulumu

```bash
npm i -g @tecof/cli
tecof --help
```

> **Not:** `tecof app push`, `app versions`, `app promote` ve `app rollback` komutları ([Sürümler ve geri alma](#surumler-ve-geri-alma-tecof-app-push)) `@tecof/cli` 0.2.0 ile gelir. `tecof --version` 0.2.0'dan küçükse `npm i -g @tecof/cli@latest` ile güncelleyin.

---

## 2. Giriş: tecof login

CLI, tarayıcıda onaylanan bir cihaz akışıyla giriş yapar; parola terminale yazılmaz.

```bash
tecof login
tecof whoami
```

CLI bir doğrulama kodu (`ABCD-EFGH` biçiminde) ve onay adresi (`https://app.tecof.com/cli?code=ABCD-EFGH` biçiminde) gösterir.

Akış:

1. CLI `POST /api/developer/cli/device { clientName }` ile cihaz kodu alır: `{ deviceCode, userCode: "ABCD-EFGH", verificationUri, expiresIn: 600, interval: 5 }`.
2. `verificationUri` adresini açıp panelde oturum açmış olarak isteği onaylarsınız ya da reddedersiniz. Onay ekranı CLI adını, IP'yi, istek zamanını, yetkilendirilecek hesabı ve (varsa) partner hesabını gösterir. Girişin kendisi partner üyeliği istemez; uygulama komutları istek anında aktif partner üyeliği arar.
3. CLI 5 saniyede bir `POST /api/developer/cli/token { deviceCode }` ile yoklar:

| Yanıt | Anlamı |
| :--- | :--- |
| `428 authorization-pending` | Henüz onaylanmadı, yoklama sürer |
| `403 authorization-denied` | İstek panelde reddedildi |
| `410 device-code-expired` | 10 dakika içinde onaylanmadı; `tecof login` ile yeniden başlayın |
| `200 { token: "tcfd_…", expiresAt, partner: { id, name } \| null, user: { id, email } }` | Giriş tamam; partner üyeliği olmayan kullanıcıda `partner` `null` |

Cihaz token'ı (`tcfd_…`) kişisel hesabınıza bağlıdır; 30 gün geçerlidir ve 14 gün kullanılmazsa düşer. Token işletim sisteminin anahtarlığında (macOS Anahtar Zinciri, Linux Secret Service; yoksa `~/.config/tecof/credentials.json`, izin `0600`) saklanır; `~/.config/tecof/config.json` yalnız üst bilgiyi (`apiUrl`, `tokenExpiresAt`, `partner`, `user`) tutar. Farklı bir API adresine (ör. yerel backend) bağlanmak için `tecof login --api <url>` kullanın. Ayrıntılar: [Güvenlik ve CI](https://tecof-app-dev.vercel.app/dev-security).

Açık CLI oturumlarınızı panelde `https://app.tecof.com/cli?tab=tokens` sayfasında, `tecof tokens ls` / `tecof tokens revoke <id>` ile ya da API'de `GET /api/developer/cli/tokens` ve `DELETE /api/developer/cli/tokens/:id` ile yönetebilirsiniz. `tecof logout` geçerli token'ı sunucuda da iptal eder.

---

## 3. Proje Oluşturma: tecof app init

```bash
tecof app init isbasi-demo --template starter --name "İşbaşı Demo"
cd isbasi-demo
npm install
```

| Seçenek | Açıklama |
| :--- | :--- |
| `[dir]` | Proje klasörü |
| `--template starter` | Başlangıç şablonu |
| `--template actions` | Aksiyon örnekleri içeren şablon |
| `--name` | Uygulama adı |

`tecof app init` uygulamayı geliştirici hesabınızda **sunucuda oluşturur**, `tecof.app.json` içine `id` / `clientId` bağını yazar ve istemci sırrını `.env.local` dosyasına kaydeder. İstemci sırrı **yalnız** `.env.local` dosyasında tutulur ve commit edilmez.

Mevcut bir uygulamaya bağlanmak için `tecof app link --app <id>` kullanın. İstemci sırrı yalnız oluşturma ve döndürme anında bir kez gösterildiğinden `app link` sırrı sunucudan alamaz: CLI ya `tecof app secret rotate` ile yeni sır almanızı önerir ya da elinizdeki sırrı elle girmenizi kabul eder.

### Proje yapısı

`starter` şablonunun ürettiği düzen (`@tecof/cli` 0.2.0). `actions` şablonu buna ek olarak `app/actions/[key]/` (iframe aksiyonu) ve `app/api/actions/[key]/route.ts` (API aksiyonu) içerir.

```text
isbasi-demo/
├── tecof.app.json              # uygulama yapılandırması (commit edilir)
├── .env.local                  # TECOF_CLIENT_ID / TECOF_CLIENT_SECRET / TECOF_API_URL (commit EDİLMEZ)
├── next.config.ts · postcss.config.mjs · tsconfig.json
├── lib/
│   ├── tecof.ts                # TecofApp örneği + withSession yardımcısı (yalnız sunucu)
│   └── settings-model.ts       # ayar formunun tek şeması (istemci + sunucu)
└── app/
    ├── layout.tsx · providers.tsx   # Geist + TecofAppProvider (@tecof/app-ui)
    ├── globals.css             # Tailwind 4 + React Suite + @tecof/app-ui katmanları
    ├── app-shell.tsx           # AppShell: başlık, durum, sekmeler
    ├── page.tsx                # genel bakış
    ├── settings/               # ayarlar sayfası + AppForm
    └── api/
        ├── session/route.ts    # oturum token'ı ile korunan örnek uç
        ├── settings/route.ts   # validateOnServer + Vault
        └── webhooks/route.ts   # createWebhookHandler (webhooks.path)
```

Arayüz kuralları için [Tasarım kimliği](https://tecof-app-dev.vercel.app/app-ui), form ve doğrulama için [Formlar ve şema](https://tecof-app-dev.vercel.app/app-forms).

### Ortam değişkenleri

```bash
# .env.local
TECOF_CLIENT_ID=tcfa_xxxxxxxxxxxxxxxx
TECOF_CLIENT_SECRET=tcfs_xxxxxxxxxxxxxxxx
TECOF_API_URL=https://api.tecof.com
# TECOF_PREVIOUS_CLIENT_SECRET=tcfs_...   # yalnız harici barındırmada, sır döndürmeden sonraki 24 saat
```

### SDK örneği

```ts
// lib/tecof.ts — yalnız sunucu kodunda içe aktarın
import { TecofApp } from "@tecof/app-sdk";

export const tecof = new TecofApp({
  clientId: process.env.TECOF_CLIENT_ID!,
  clientSecret: process.env.TECOF_CLIENT_SECRET!,
  previousClientSecret: process.env.TECOF_PREVIOUS_CLIENT_SECRET, // isteğe bağlı: sır döndürme geçişi
  apiUrl: process.env.TECOF_API_URL, // verilmezse TECOF_API_URL okunur
});
```

İstemci sırrını taşıyan değişkenleri asla `NEXT_PUBLIC_` önekiyle tanımlamayın; tarayıcı paketine girer.

---

## 4. Test Mağazasında Geliştirme: tecof app dev

### Test mağazasını tanımlayın

`tecof.app.json` içindeki `testStores` dizisine mağaza kimliğini (`merchantId`) ekleyin. Yalnız ekip üyesi olduğunuz mağazalar kabul edilir; listesini `GET /api/developer/test-stores` döner.

```json
{
  "testStores": ["66f0c0ffee0000000000abcd"]
}
```

Yapılandırmayı sunucuya gönderin:

```bash
tecof app config push
```

### Yerel sunucu ve tünel

```bash
tecof app dev --tunnel cloudflared
```

`tecof app dev` yerel geliştirme sunucunuzu başlatır (varsayılan port **3000**, `--port` ile değişir), tünelle dışarı açar ve tünel adresini uygulamanın `devUrl` değeri olarak kaydeder (`PUT /api/developer/apps/:id/dev-url`). Kurallar:

- `devUrl` **8 saat** geçerlidir; süre dolunca komutu yeniden çalıştırın.
- `devUrl` yalnız **test mağazası kurulumlarında** geçerlidir ve orada `appUrl`'in yerine geçer: panel iframe'i, **webhook teslimatları** ve **API aksiyonları** tünel adresinize gider (adres teslimat anında çözülür). Diğer mağazalar her zaman `appUrl`'i kullanır.

| `--tunnel` | Davranış |
| :--- | :--- |
| `cloudflared` | Cloudflare tüneli açar |
| `none` | Tünel açmaz |
| `<url>` | Kendi açtığınız tünel adresini (ör. başka bir tünel aracı) `devUrl` olarak kaydeder |

Böylece test mağazasında sipariş oluşturduğunuzda `order.paid` gibi webhook'lar ve panelden çalıştırdığınız aksiyonlar doğrudan yerel sunucunuza düşer. Tünel açmadan yalnız imza mantığını denemek için [Aksiyonlar → Yerelde test](https://tecof-app-dev.vercel.app/app-actions) bölümündeki imzalı `curl` örneğini kullanabilirsiniz.

### Test mağazasına kurun

Panelde kurulum bağlantısını açın:

```text
https://app.tecof.com/app/apps/install/tcfa_xxxxxxxxxxxxxxxx
```

Onay ekranı istenen kapsamları ve (varsa) planları gösterir. Onaydan sonra uygulamanız `app.installed` webhook'unu alır ve panelde "Uygulamalarım" altında açılır.

---

## 5. Dağıtım

Tecof barındırmalı (`hosting: "tecof"`) bir uygulamayı iki yolla yayınlarsınız:

| Yol | Ne yapar | Durum |
| :--- | :--- | :--- |
| `tecof app push` | Yalnız değişen dosyaları yükler ve numaralı bir sürüm açar; staged derlemeyi önizleyip yeniden derlemeden canlıya alırsınız, gerekirse anında geri alırsınız | Önerilen |
| `tecof app deploy` | Tüm kaynağı arşivleyip yükler ve doğrudan yayınlar | Çalışmaya devam eder |

### Sürümler ve Geri Alma: tecof app push

```bash
tecof app push -m "Fatura listesi"   # staged sürüm açar, ör. v5
tecof app versions                    # sürüm listesi
tecof app promote v5                  # yeniden derlemeden canlıya alır
tecof app rollback                    # bir önceki canlı sürüme döner
tecof app logs v5                     # sürümün derleme günlüğü
```

- Uygulamanın alan kimliği `app_<tecof.app.json içindeki id>` olur; `tecof spaces ls --kind app` uygulama alanlarını listeler.
- Her push `main` dalının o anki hâlinin üstüne kurulur ve klasör istenen son durum sayılır: klasörde olmayan dosyalar depodan silinir. Uygulamalarda `.tecof/` klasörü ve yerel taban kullanılmaz.
- `tecof.app.json` push ile **gönderilmez**; staged kod canlıdaki yapılandırmayı değiştirmesin diye. Yapılandırma değiştiyse `tecof app config push` çalıştırın.
- Depo, Vercel projesi, alan adı ve ortam değişkenleri yoksa ilk push onları ilk `tecof app deploy` gibi kurar. Ortam değişkenleri (aşağıdaki tablo) her push'ta derlemeden önce yeniden yazılır.
- Staged sürüm tam bir üretim derlemesidir ama alan adı almaz. `tecof app promote vN` alan adlarını yeniden derlemeden bu sürüme çevirir ve `main` dalını sürümün commit'ine hızlı ileri alır. `--prod` commit'i doğrudan `main` dalına yazar ve derleme bitince canlıya çıkar.
- `promote`, `rollback` ve `push --prod` onay ister; ajan ve CI ortamlarında `--yes` gerekir.
- `tecof app deploy` yayınları da sürüm listesinde (`source: "cli"`) görünür; geri alma onlarda da çalışır.
- Kendi sunucunuzda barındırılan uygulamalarda (`hosting: "external"`) sürüm komutları çalışmaz.
- Geliştirici portalında uygulamanın **Sürümler** sekmesi aynı sürümleri gösterir; canlıya alma ve geri alma oradan da yapılır.

Kurallar ve ayrıntılar: [Sürümler, Canlıya Alma ve Geri Alma](https://tecof-app-dev.vercel.app/versions-and-rollback). CI'dan yayın: [GitHub Actions örneği](https://tecof-app-dev.vercel.app/dev-security#github-actions-ornegi).

### Tek Adımda Dağıtım: tecof app deploy

```bash
tecof app deploy -m "İlk sürüm"
tecof app deployments          # dağıtım listesi ve durumları
tecof app logs <deploymentId>  # derleme günlüğü
```

`tecof app deploy` önce `tecof.app.json` dosyasını gönderir, sonra Tecof barındırmasına şu adımlarla dağıtır:

1. CLI projeyi kök klasörlü bir `.tar.gz` arşivine paketler ve yükler (`POST /api/developer/apps/:id/deployments`, multipart `bundle` + `message`).
2. İlk dağıtımda Tecof sizin için şunları açar:
   - GitHub org reposu `tecof-app-<slug>`
   - Vercel projesi `tecof-app-<slug>`
   - Ortam değişkenleri (aşağıdaki tablo)
   - Alan adı `<slug>.apps.<Tecof alan adı>` (varsayılan alt alan `apps`) — örneğin `isbasi.apps.tecof.site`. Alan adı kurulamazsa uygulama `https://tecof-app-<slug>.vercel.app` adresinde yayınlanır
3. Dosyalar tek commit ile varsayılan dala yazılır; Vercel üretim derlemesini başlatır. Önceki dağıtımda olup yeni pakette **bulunmayan dosyalar repodan silinir** (repo her dağıtımda paketin birebir kopyasıdır).
4. Dağıtım durumu: `queued` → `building` → `ready` | `error` | `canceled`. Durum `ready` olunca uygulamanın `appUrl` değeri otomatik güncellenir.

**Paket sınırları**

| Kural | Değer |
| :--- | :--- |
| Hariç tutulanlar | `node_modules`, `.next`, `.git`, `.vercel`, `.env*` |
| Toplam boyut | ≤ 25 MB |
| Dosya sayısı | ≤ 3000 |
| Dosya başına | ≤ 5 MB |

`.env*` dosyaları **yüklenmez**. Sırlar dağıtım ortamına Tecof tarafından verilir:

| Değişken | İçerik |
| :--- | :--- |
| `TECOF_CLIENT_ID` | İstemci kimliği |
| `TECOF_CLIENT_SECRET` | İstemci sırrı |
| `TECOF_API_URL` | Tecof API adresi |
| `TECOF_APP_URL` | Uygulamanın yayın adresi |
| `NEXT_PUBLIC_TECOF_CLIENT_ID` | İstemci kimliği (tarayıcı) |
| `NEXT_PUBLIC_TECOF_API_URL` | Tecof API adresi (tarayıcı) |

Sırrı döndürdüğünüzde (`tecof app secret rotate`) Vercel ortam değişkeni güncellenir ve yeniden dağıtım tetiklenir.

### Kendi sunucunuz (hosting: "external")

`hosting: "external"` seçildiğinde `appUrl` zorunludur ve `https://` olmalıdır (geliştirmede yalnız `http://localhost` / `http://127.0.0.1` kabul edilir). Dağıtım sizin sorumluluğunuzdadır; yukarıdaki ortam değişkenlerini kendiniz tanımlarsınız.

---

## CLI Komutları

| Komut | Açıklama |
| :--- | :--- |
| `tecof login [--api <url>] [--no-browser]` | Cihaz akışıyla giriş |
| `tecof logout` | Token'ı sunucuda iptal eder ve yerelden siler |
| `tecof whoami` | Giriş yapılan kullanıcı ve partner |
| `tecof status` · `tecof doctor` | Bağlı alan ve oturum özeti · ortam denetimi |
| `tecof app init [dir] [--template starter\|actions] [--name <ad>] [--slug <slug>]` | Uygulamayı sunucuda oluşturur, şablondan proje açar, sırrı `.env.local`'e yazar |
| `tecof app link [--app <id\|clientId\|slug>]` | Klasörü mevcut bir uygulamaya bağlar (sırrı alamaz; döndürme ya da elle giriş) |
| `tecof app info` | Bağlı uygulamanın bilgileri |
| `tecof app config push` | `tecof.app.json`'u sunucuya gönderir; art arda hatalar yüzünden pasife alınmış webhook aboneliklerini yeniden etkinleştirir |
| `tecof app dev [--port <n>] [--tunnel cloudflared\|none\|<url>]` | Yerel sunucu (varsayılan 3000) + tünel + `devUrl` kaydı |
| `tecof app push [-m <mesaj>] [--prod]` | Yalnız değişen dosyaları yükler, numaralı sürüm açar (varsayılan staged) |
| `tecof app versions [vN]` | Sürüm listesi ya da tek sürümün durumu |
| `tecof app promote vN` · `tecof app rollback [vN]` | Sürümü yeniden derlemeden canlıya alır · önceki canlı sürüme döner |
| `tecof app deploy [-m <mesaj>]` | Tüm kaynağı paketleyip doğrudan yayınlar |
| `tecof app deployments` | `app deploy` dağıtımlarının listesi |
| `tecof app logs <vN\|deploymentId>` | Sürümün ya da dağıtımın derleme günlüğü |
| `tecof app secret rotate` | İstemci sırrını döndürür (eski sır 24 saat geçerli kalır) |
| `tecof app open [--install]` | Uygulamayı geliştirici portalında ya da kurulum sayfasında açar |
| `tecof spaces ls` · `tecof tokens …` · `tecof setup agent` | Alanlar, CI token'ları, kodlama ajanı kurulumu |
| `tecof theme …` | Tema komutları: [Tema Geliştirme: Hızlı Başlangıç](https://tecof-app-dev.vercel.app/theme-quickstart) |

Tüm komutlar, seçenekler, çıkış kodları ve JSON makbuzları: [CLI Başvurusu](https://tecof-app-dev.vercel.app/cli-reference).

---

## tecof.app.json Referansı

Yapılandırma `tecof app config push`, `tecof app deploy` ya da geliştirici API'sinin `PUT /api/developer/apps/:id/config` ucuyla yazılır. Sunucu dosyayı doğrular, **bilinmeyen alanları atar** ve hataları şu biçimde döner:

```json
{
  "success": false,
  "messageCode": "invalid-app-config",
  "data": {
    "issues": [
      { "path": "actions[0].key", "code": "…", "message": "…" }
    ]
  }
}
```

### Tam örnek

```jsonc
{
  "id": "6720aa00bb11cc22dd33ee44",          // portal/CLI bağı (isteğe bağlı, sunucu yok sayar)
  "clientId": "tcfa_xxxxxxxxxxxxxxxx",        // bilgi amaçlı
  "name": "Logo İşbaşı",
  "slug": "isbasi",
  "hosting": "tecof",                          // "tecof" | "external"
  "appUrl": "https://isbasi.apps.tecof.site",  // external'da zorunlu; tecof'ta dağıtım sonrası otomatik
  "embedded": true,
  "scopes": ["orders:read", "customers:read", "products:read"],
  "webhooks": {
    "path": "/api/webhooks",
    "events": ["order.paid", "order.cancelled", "order.refunded"]
  },
  "actions": [
    {
      "key": "create-invoice", "type": "iframe", "placement": "order.detail",
      "title": { "tr": "İşbaşı'nda fatura kes", "en": "Create İşbaşı invoice" },
      "path": "/actions/create-invoice", "presentation": "modal"
    }
  ],
  "navigation": [
    { "label": { "tr": "Faturalar", "en": "Invoices" }, "path": "/invoices" }
  ],
  "settings": [
    { "key": "apiKey", "label": { "tr": "API anahtarı", "en": "API key" }, "type": "secret", "required": true },
    { "key": "invoiceMode", "label": { "tr": "Fatura tipi", "en": "Invoice mode" }, "type": "select",
      "options": [
        { "value": "draft", "label": { "tr": "Taslak", "en": "Draft" } },
        { "value": "issued", "label": { "tr": "Kesilmiş", "en": "Issued" } }
      ] }
  ],
  "appEvents": {
    "publishes": [
      { "name": "invoice.created", "description": { "tr": "Fatura oluşturuldu", "en": "Invoice created" } }
    ],
    "subscribes": ["app.kargo.shipment.created"]
  },
  "plans": [
    {
      "key": "standart", "name": { "tr": "Standart", "en": "Standard" },
      "description": { "tr": "Aylık plan", "en": "Monthly plan" },
      "price": 199, "currency": "TRY", "interval": "month", "trialDays": 14,
      "features": [{ "tr": "Sınırsız fatura", "en": "Unlimited invoices" }]
    }
  ],
  "listing": {
    "shortDescription": { "tr": "Siparişleri İşbaşı'nda faturalayın", "en": "Invoice orders in İşbaşı" },
    "description": { "tr": "…", "en": "…" },
    "category": "accounting",
    "supportEmail": "destek@ornek.com",
    "supportUrl": "https://ornek.com/destek",
    "privacyUrl": "https://ornek.com/gizlilik",
    "websiteUrl": "https://ornek.com",
    "media": {                                 // isteğe bağlı, yalnız birinci parti; yazılmayan görsel store-assets/ varsayılanı
      "icon": "store-assets/icon.png",
      "cover": "store-assets/cover.png",
      "screenshots": ["store-assets/screenshots/01-genel-bakis.png", "store-assets/screenshots/02-faturalar.png"]
    }
  },
  "testStores": ["66f0c0ffee0000000000abcd"]
}
```

### Alanlar

| Alan | Tip | Kural |
| :--- | :--- | :--- |
| `id` | string | İsteğe bağlı; CLI/portal bağı. Sunucu yok sayar |
| `clientId` | string | Bilgi amaçlı (`tcfa_…`) |
| `name` | string | Uygulama adı |
| `slug` | string | `^[a-z][a-z0-9-]{2,39}$`; global tekil; oluşturulduktan sonra **değişmez**. Metafield namespace'i, uygulama olayı öneki ve barındırma alan adı bundan türer |
| `hosting` | `"tecof"` / `"external"` | Tecof barındırması ya da kendi sunucunuz |
| `appUrl` | string | `external`'da zorunlu; `tecof`'ta dağıtım `ready` olunca otomatik yazılır |
| `embedded` | boolean | Panelde iframe arayüzü var mı |
| `scopes` | string[] | Yalnız uygulamaya açık kapsamlar. Bkz. [Kapsamlar](https://tecof-app-dev.vercel.app/app-auth) |
| `webhooks.path` | string | Webhook teslimat yolu (`appUrl`'e göre). Tanımlı değilse yaşam döngüsü olayları (`app.installed` vb.) ve uygulama olayları da teslim **edilemez** |
| `webhooks.events` | string[] | Olay kataloğundan; her olayın gerektirdiği okuma kapsamı `scopes` içinde olmalı. `*` kapalı. Bkz. [Webhook'lar](https://tecof-app-dev.vercel.app/app-webhooks) |
| `actions` | object[] | En fazla **12**. Bkz. [Aksiyonlar](https://tecof-app-dev.vercel.app/app-actions) |
| `navigation` | object[] | En fazla **8**; `{ label: { tr, en }, path }` |
| `settings` | object[] | Yerel ayar formu, en fazla **30** alan; `select` için `options: [{ value, label }]`. Bkz. [Ayarlar](https://tecof-app-dev.vercel.app/app-data) |
| `appEvents.publishes` | object[] | `{ name, description: { tr, en } }`. Bkz. [Uygulamalar Arası İletişim](https://tecof-app-dev.vercel.app/app-interop) |
| `appEvents.subscribes` | string[] | `app.<slug>.<ad>` ya da `app.<slug>.*` |
| `plans` | object[] | En fazla **4**; boşsa uygulama ücretsizdir. Bkz. [Ücretlendirme](https://tecof-app-dev.vercel.app/app-billing) |
| `listing.shortDescription`, `listing.description` | `{ tr, en }` | Katalog metinleri |
| `listing.category` | string | Mağazada bu sırayla gösterilir: `accounting` (Muhasebe), `shipping` (Kargo ve Lojistik), `management` (Yönetim), `marketing` (Pazarlama), `marketplace` (Pazaryeri), `other` (Diğer). Yazılmazsa `other`. Eski anahtarlar hâlâ kabul edilir ama kullanmayın: `invoicing` → `accounting`, `analytics` / `crm` / `automation` → `management` olarak kaydedilir ve yanıtta `category-deprecated` uyarısı döner. Listede olmayan değer yapılandırmayı reddeder (`invalid-value`) |
| `listing.supportEmail`, `supportUrl`, `privacyUrl`, `websiteUrl` | string | Destek ve yasal bağlantılar |
| `listing.media.icon`, `listing.media.cover` | string | Yalnız birinci parti uygulamada kullanılır. Repodaki ikon (512×512) ve kapak (1600×900, logosuz) görselinin repo köküne göre yolu: `/` ile başlamaz; `.` ya da `..` bölümü, boş bölüm ve `\` içermez; en fazla 200 karakter, uzantı `png` / `jpg` / `jpeg` / `webp`. Yazılmazsa `store-assets/icon.png` ve `store-assets/cover.png`; yazılan ama repoda olmayan yol `missing` olur, varsayılana düşmez. Repodaki `tecof.app.json`'da `listing.media` hiç yoksa Tecof'ta saklı yapılandırmadaki geçerlidir. Bkz. [Mağaza Görselleri](https://tecof-app-dev.vercel.app/app-publishing#magaza-gorselleri) |
| `listing.media.screenshots` | string[] | En fazla **8**, yinelenmeyen ekran görüntüsü yolu (1280×800), yazıldığı sırayla; yol kuralları ve çözüm sırası aynı. Yazılmazsa `store-assets/screenshots/` içindeki görseller ad sırasıyla |
| `testStores` | string[] | Mağaza kimlikleri; yalnız ekip üyesi olduğunuz mağazalar kabul edilir |

### Kurallar

- Tüm `path` alanları `appUrl`'e göredir ve `/` ile başlar. Mutlak URL verilecekse `https://` zorunludur; yalnız geliştirme adresi olarak `http://localhost` ve `http://127.0.0.1` kabul edilir.
- `scopes` yalnız uygulama kapsam listesinden seçilir; kapalı kapsamlar (`code:*`, `sandbox:run`, `deploy:write`, `memory:*`, `domains:write`, `ai:generate`) reddedilir.
- **Kapsam artışı mevcut kurulumlara otomatik geçmez.** Kurulum `pendingScopes` alır; mağaza onaylayana kadar eski kapsamla çalışır. Kapsam azalması anında uygulanır.
- Onaylanmış bir uygulamada `listing` ve `plans` değişiklikleri canlıya hemen yansır; **kapsam artışı yeniden inceleme ister** (inceleme sürerken mevcut sürüm yayında kalır). Bkz. [Yayınlama ve İnceleme](https://tecof-app-dev.vercel.app/app-publishing).
- Birinci parti uygulamalarda Tecof mağaza görsellerini (`listing.media` yolları ya da `store-assets/` varsayılanları) repodan kendisi çeker: oluşturmada ya da repoya bağlamada, yöneticinin **Repodan çek** işleminde ve her başarılı üretim dağıtımından sonra. Partner uygulamalarında ikon ve ekran görüntüleri portaldan ya da medya uçlarından yüklenir. Bkz. [Mağaza Görselleri](https://tecof-app-dev.vercel.app/app-publishing#magaza-gorselleri).

---

## Sonraki Adımlar

- [Kimlik Doğrulama ve Kapsamlar](https://tecof-app-dev.vercel.app/app-auth) — oturum token'ı ve imza doğrulama
- [API ile Veri Erişimi](https://tecof-app-dev.vercel.app/app-api) — sipariş ve müşteri okuma
- [Webhook'lar](https://tecof-app-dev.vercel.app/app-webhooks) — `order.paid` dinleme
- [Örnek Uygulama: Logo İşbaşı](https://tecof-app-dev.vercel.app/app-example-isbasi) — uçtan uca örnek

---

# Tasarım Kimliği (@tecof/app-ui)

> @tecof/app-ui ile Tecof panel görünümünde uygulama arayüzü: kurulum, globals.css katman sırası, TecofAppProvider, AppShell ve bileşenler, durum sözlüğü, ekran düzenleri, metin tonu ve yasaklar.
>
> Kaynak: https://tecof-app-dev.vercel.app/app-ui · Bölüm: Uygulama geliştirme · Son güncelleme: 2018-10-20

Panelde iframe içinde açılan her Tecof uygulaması **aynı görünür ve aynı davranır**. `@tecof/app-ui` bu ortak kimliği verir: React Suite 6 + Tailwind CSS 4 + lucide-react üzerine panelle aynı görsel dil — Tecof lime imza rengi, zinc nötrler, Geist, `rounded-2xl` kartlar, panelden gelen açık/koyu tema ve tr/en metinler.

| Giriş | Ortam | İçerik |
| :--- | :--- | :--- |
| `@tecof/app-ui` | İstemci (`"use client"` derlemede eklenir) | `TecofAppProvider`, kabuk ve yerleşim, durum, tablo, form bileşenleri, `useAppToast`, `useAppConfirm` |
| `@tecof/app-ui/schema` | **Sunucu-güvenli** (React/DOM yok) | `createModel`, `v` kuralları, `validateOnServer`, VKN/TCKN/IBAN/telefon doğrulayıcıları, durum sözlüğü, biçimlendiriciler |
| `@tecof/app-ui/styles.css` | Tailwind 4 CSS | Tema belirteçleri, React Suite → Tecof değişkenleri |

Peer bağımlılıklar: `react ^19`, `react-dom ^19`, `rsuite ^6.2`, `lucide-react`, `@tecof/app-bridge ^0.1`. `tecof app init` şablonları bu kurulumla gelir; aşağıdaki adımlar mevcut bir uygulamayı taşırken ya da elle kurarken gereklidir.

## Kurulum

```bash npm2yarn
npm install @tecof/app-ui @tecof/app-bridge @tecof/app-sdk rsuite lucide-react geist
npm install -D tailwindcss @tailwindcss/postcss
```

```js title="postcss.config.mjs"
export default { plugins: { "@tailwindcss/postcss": {} } };
```

`app/globals.css` **tam olarak** şu dört satırdır; katman sırası önemlidir ve başka global CSS eklenmez:

```css title="app/globals.css"
@layer theme, base, rsuite, components, utilities;
@import "tailwindcss";
@import "rsuite/dist/rsuite-no-reset.min.css" layer(rsuite);
@import "@tecof/app-ui/styles.css";
```

```tsx title="app/layout.tsx"
import type { Metadata } from "next";
import { GeistMono } from "geist/font/mono";
import { GeistSans } from "geist/font/sans";
import { Providers } from "./providers";
import "./globals.css";

export const metadata: Metadata = { title: "Uygulamam", robots: { index: false, follow: false } };

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="tr" data-theme="light" suppressHydrationWarning className={`${GeistSans.variable} ${GeistMono.variable}`}>
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  );
}
```

```tsx title="app/providers.tsx"
"use client";
import { TecofAppProvider } from "@tecof/app-ui";

export function Providers({ children }: { children: React.ReactNode }) {
  // App Bridge'i kurar, tema/dili panelden alır, <html data-theme class="dark" lang> ayarlar,
  // toast ve onay köprüsünü sağlar.
  return <TecofAppProvider>{children}</TecofAppProvider>;
}
```

Panel dışında geliştirmek için `allowStandalone` (köprü `null`, toast/onay React Suite ile çalışır) ya da geçici olarak `bridge="off" theme="dark" locale="en"` verin. Kalıcı kodda `bridge="off"` bırakmayın.

## Kabuk

```tsx title="app/app-shell.tsx"
"use client";
import Link from "next/link";
import { usePathname } from "next/navigation";
import { AppShell, StatusBadge, useTecofApp } from "@tecof/app-ui";
import { FileText, LayoutDashboard, Settings } from "lucide-react";

export function Shell({ children }: { children: React.ReactNode }) {
  const { context, locale } = useTecofApp();
  const en = locale === "en";
  return (
    <AppShell
      title={context?.app.name ?? "Uygulama"}
      subtitle={context?.merchant.name}
      icon={<FileText />}
      status={<StatusBadge status="connected" />}
      linkAs={Link}
      activeHref={usePathname()}
      tabs={[
        { href: "/", label: en ? "Overview" : "Genel bakış", icon: <LayoutDashboard /> },
        { href: "/settings", label: en ? "Settings" : "Ayarlar", icon: <Settings /> },
      ]}
    >
      {children}
    </AppShell>
  );
}
```

`AppShell`’e `linkAs={Link}` bir fonksiyon geçtiği için kabuğu istemci bileşeninde kullanın. Simge prop’ları **eleman** alır (`icon={<Receipt />}`), böylece sunucu bileşenlerinden de verilebilir.

## Bileşenler

| Bileşen | Kullanım |
| :--- | :--- |
| `PageHeader` | Sayfa başlığı ve tek ana eylem; `eyebrow` yazıldığı gibi gösterilir (`eyebrowCase="upper"` isteğe bağlı) |
| `Section` | Kart; form ve tablo için `padded={false}`, tehlikeli işlem için `tone="danger"` |
| `StatGrid` + `StatCard` | 2–4 metrik; `loading` destekler |
| `DataTable` | React Suite tablosu; 640 px altında kart görünümü (`mobile: "title" \| "badge" \| "meta" \| "hidden"`), uzun metin için `truncate: true`, boş liste için `empty` |
| `StatusBadge` | Ortak durum sözlüğünden ton ve tr/en etiket |
| `Callout` | Bilgi/uyarı/hata mesajı (`tone`) |
| `EmptyState` | Boş durum: ne olacağını ve ilk adımı söyler |
| `KeyValueList`, `CopyValue`, `LogList` | Ayrıntı ekranları |
| `ConfirmButton` | Panelde App Bridge onayıyla çalışan tehlikeli eylem düğmesi |
| `useAppToast()`, `useAppConfirm()` | Panel toast’ı ve onayı |

Düğmeler React Suite `Button`’dır: ekranda **tek** ana eylem `appearance="primary"` (lime), diğerleri `default` ya da `subtle`. İkonlar yalnız `lucide-react`, düğmede `size-4`.

### Durum sözlüğü

`<StatusBadge status="…" />` tek sözlükten ton ve etiket alır; sözlükte olmayan durum için `tone` + `label` verin, yeni renk uydurmayın.

| Grup | Durumlar |
| :--- | :--- |
| Genel | `success` · `warning` · `error` · `info` · `neutral` · `pending` |
| Fatura | `creating` · `draft` · `issued` · `signed` · `failed` · `skipped` · `needs-cancellation` · `deleted` · `cancelled` |
| Gönderim | `queued` · `processing` · `sending` · `sent` · `delivered` · `undelivered` · `rejected` |
| Kargo | `label-created` · `shipped` · `in-transit` · `out-for-delivery` · `returned` |
| Bağlantı / abonelik | `connected` · `disconnected` · `not-configured` · `active` · `inactive` · `trialing` · `past_due` · `expired` |

Sunucuda aynı sözlük `statusTone` / `statusLabel` ile (`@tecof/app-ui/schema`) okunur.

## Ekran düzenleri

| Ekran | Düzen |
| :--- | :--- |
| Genel bakış (`/`) | `PageHeader` (+ tek ana eylem) → yalnız eylem gerektiren `Callout` (ayar eksik, test modu, plan) → `StatGrid` → son kayıtlar `Section` + `DataTable` (5–10 satır, “Tümünü gör”) → hiç kayıt yoksa `EmptyState` |
| Ayarlar (`/settings`) | `PageHeader` → `AppForm` içinde konu başına `Section padded={false}` → `FormActions` (mobilde alta yapışık) → ayrı `Section tone="danger"` (bağlantıyı kes, `ConfirmButton`) |
| Kayıtlar (`/invoices`, `/logs`…) | `PageHeader` (+ filtre) → `Section padded={false}` + `DataTable` (`onRowClick` → `Drawer` ya da detay sayfası) → `Pagination`; detayda `KeyValueList` + `LogList` |
| Aksiyon penceresi | Kabuksuz: başlık **yalnız** `bridge.setTitle(...)` ile panel çekmecesine gider (sayfada başlık satırı ve kendi X’i yok); kısa bağlam satırı + `Section` + altta yapışık Vazgeç/Tamamla; bitince `bridge.close({ refresh: true, message, kind })`. Fatura uygulamalarında `@tecof/invoice-kit/ui` `ActionFrame` |

Durumlar: yükleniyor → `Placeholder.Paragraph` / `StatCard loading` / `DataTable loading`; hata → `Callout tone="error"` + “Tekrar dene”; boş → `EmptyState`. Tarih ve para için `formatDateTime` (Europe/Istanbul, hidrasyon güvenli) ve `formatMoney` (`@tecof/app-ui/schema`).

## Metin tonu

Türkçe öncelikli, `en` karşılığıyla. Kısa, “siz” dili, cümle düzeni (“Ayarları Kaydet” değil “Kaydet”). Eylemler fiille (“Bağlan”, “Tekrar dene”, “Fatura oluştur”). Hata metni ne olduğunu ve ne yapılacağını söyler: “Sağlayıcı kimlik bilgilerini reddetti. API anahtarını kontrol edip tekrar deneyin.” Ünlem, teknik kod ve stack izi yok. Dil `useTecofApp().locale` (`tr` | `en`); sunucuda `resolveLocale(session.locale)`.

## Yapmayın

- Marka/ürün adına `uppercase` vermeyin (Türkçe büyük harf “KolayBi” → “KOLAYBİ”).
- Kendi renk paleti, CSS değişken seti, ayrı `.css` dosyası, inline style ile tema, başka UI kütüphanesi (shadcn, MUI…), başka ikon seti ya da emoji.
- Ham `<input>` / `<select>` / `<button>` ile form; `prefers-color-scheme` ile tema; `@custom-variant dark` yeniden tanımı. Koyu tema panelden gelir, `dark:` sınıflarıyla kullanılır.
- Sunucu kodunda `@tecof/app-ui` (istemci girişi) — sunucuda yalnız `@tecof/app-ui/schema`.
- Sır değerini, oturum token’ını ya da müşteri kişisel verisini ekrana veya günlüğe basmak.
- Kit eksiğini kalıcı geçici çözümle kapatmak: önce kitte karşılığını arayın (`truncate`, `SubmitButton`, `onCheckFail`).

Formlar ve tek şemalı doğrulama: [Formlar ve şema](https://tecof-app-dev.vercel.app/app-forms). Görsel doğrulama için uygulamayı panel dışında `allowStandalone` ile açıp masaüstü (1280) ve mobil (390) genişlikte, açık ve koyu temada kontrol edin.

---

# Formlar ve Şema

> Uygulama formları — @tecof/app-ui/schema ile istemci ve sunucuda tek şema, v kuralları, koşullu zorunluluk, AppForm ve hazır alanlar, SecretField ile Vault sırları, validateOnServer ve 422 hata sözleşmesi.
>
> Kaynak: https://tecof-app-dev.vercel.app/app-forms · Bölüm: Uygulama geliştirme · Son güncelleme: 2018-10-20

Uygulama formları **tek şemayla** iki tarafta doğrulanır: aynı model tarayıcıda alan hatalarını gösterir, sunucuda gövdeyi temizleyip doğrular. Şema sunucu-güvenli `@tecof/app-ui/schema` girişinden gelir (React/DOM yok), form bileşenleri istemci girişinden.

## 1. Şemayı tanımlayın

```ts title="lib/settings-model.ts"
// "use client" YOK: bu dosya hem istemcide hem sunucuda içe aktarılır.
import { createModel } from "@tecof/app-ui/schema";

export type Settings = { companyName: string; email: string; vkn: string; mode: string; apiKey: string };

export const settingsModel = createModel<Settings>((v, ctx) => ({
  companyName: v.text({ required: true, max: 120 }),
  email: v.email({ required: true }),
  vkn: v.vknOrTckn(),
  mode: v.select(["draft", "live"], { required: true }),
  apiKey: v.secret({ required: !ctx.secrets.apiKey }), // kayıtlıysa boş = değiştirme
}));
```

### Kurallar (`v`)

| Kural | Açıklama |
| :--- | :--- |
| `text({ required, min, max, pattern, trim })` | Metin; `trim: false` sunucuda kırpmaz (SMS/şablon gövdesi) |
| `email()` | E-posta |
| `httpsUrl({ hosts })` | Yalnız `https`, izin listeli host’lar |
| `trMobile()` · `e164Phone()` | Türkiye cep telefonu · E.164 |
| `vkn()` · `tckn()` · `vknOrTckn()` | Vergi / kimlik numarası (sağlama hanesiyle) |
| `iban()` | TR IBAN (mod-97) |
| `number({ min, max, integer })` | Sayı |
| `boolean({ mustBeTrue })` | Onay kutusu |
| `select(values)` · `multiSelect(values, { min, max })` | Seçim |
| `secret({ required, min, max })` | Vault’a gidecek sır |
| `custom(check, message, { required, priority })` | Özel kural; `check(value, formData)` |

Mesajlar tr/en hazırdır (`createRules("en")`); özel mesaj için `required: "…"`.

### Koşullu zorunluluk

Her kural `requiredIf: (form) => boolean` alır; boş değerde de çalışır ve alanın zorunlu yıldızı güncel form değerine göre çıkar. Koşulu belirleyen alana `.proxy(["bağımlı-alan"])` ekleyin ki değişince bağımlı alan yeniden denetlensin:

```ts
mode: v.select(["draft", "live"], { required: true }).proxy(["webhookUrl"]),
webhookUrl: v.httpsUrl({ hosts: ["hooks.ornek.com"], requiredIf: (d) => d.mode === "live" }),
```

Çapraz alan kuralı için `v.custom((value: unknown, data?: Settings) => …, "mesaj", { priority: true })` kullanın. Ham schema-typed `MixedType<A, B>()` yazmayın (A değer, B form verisi tipidir ve kolay karışır); gerekiyorsa `mixedOf<Değer, FormVerisi>()`.

## 2. İstemci formu

```tsx title="app/settings/settings-form.tsx"
"use client";
import { useState } from "react";
import { useSessionFetch } from "@tecof/app-bridge/react";
import { AppForm, FormActions, Section, SecretField, SelectField, TextField, useAppToast, type SecretState } from "@tecof/app-ui";
import { readFieldErrors } from "@tecof/app-ui/schema";
import { settingsModel, type Settings } from "@/lib/settings-model";

export function SettingsForm({ initial, apiKey }: { initial: Settings; apiKey: SecretState }) {
  const [value, setValue] = useState(initial);
  const [saved, setSaved] = useState(initial);
  const fetch = useSessionFetch(); // 60 sn'lik oturum token'ını ekler
  const toast = useAppToast();

  return (
    <AppForm
      model={settingsModel}
      modelContext={{ secrets: { apiKey: apiKey.set } }}
      formValue={value}
      initialValue={saved}
      onChange={setValue}
      onSubmit={async (data) => {
        const res = await fetch("/api/settings", {
          method: "PUT",
          headers: { "content-type": "application/json" },
          body: JSON.stringify(data),
        });
        const json = await res.json().catch(() => ({}));
        if (!res.ok) return { errors: readFieldErrors(json), message: json.message };
        setSaved({ ...data, apiKey: "" });
        setValue({ ...data, apiKey: "" });
        toast.success("Ayarlar kaydedildi");
      }}
    >
      <Section title="Bağlantı" description="Sağlayıcı hesabınız" padded={false}>
        <TextField name="companyName" label="Firma adı" />
        <TextField name="email" label="E-posta" type="email" />
        <TextField name="vkn" label="VKN / TCKN" inputMode="numeric" />
        <SelectField name="mode" label="Mod" options={[{ label: "Taslak", value: "draft" }, { label: "Canlı", value: "live" }]} />
        <SecretField name="apiKey" label="API anahtarı" stored={apiKey} />
      </Section>
      <FormActions />
    </AppForm>
  );
}
```

**Hazır alanlar:** `TextField`, `TextareaField`, `NumberField`, `SelectField` (8+ seçenekte aranabilir), `ToggleField`, `CheckboxGroupField`, `RadioField`, `PasswordField`, `SecretField` ve genel `Field` (`accepter={DatePicker}` vb.). Girdi öznitelikleri (`inputMode`, `autoComplete`, `maxLength`, `pattern`, `autoFocus`, `enterKeyHint`, `data-*`) doğrudan `<input>`’a geçer. Zorunlu işareti şemadan gelir. Çekmece/modal içinde `layout="stack"`.

- `AppForm` gönderimde istemci doğrulaması yapar; hata varsa `onCheckFail(errors, "client")` çağrılır (odaklanmadan **önce** — katlanmış satırı ya da sekmeyi burada açın), uyarı toast’ı gösterilir ve ilk hatalı alana odaklanılır. Sunucu `{ errors }` dönerse `onCheckFail(errors, "server")`.
- Form içinden durum: `useAppForm()` → `{ errors, saving, dirty, submit, reset, … }`.
- `FormActions` varsayılan olarak Kaydet + geri al’dır (mobilde değişiklik varken alta yapışır). Gönderme formları için `submitLabel="Gönder" submittingLabel="Gönderiliyor…" submitIcon={<Send className="size-4" />} hideCancel`; formun ortasında tek düğme için `<SubmitButton>`. Kendi gönder düğmenizi ya da `onSubmitCapture` geçici çözümünü yazmayın.

## 3. Sunucu ucu

```ts title="app/api/settings/route.ts"
import { resolveLocale, validateOnServer } from "@tecof/app-ui/schema";
import { settingsModel } from "@/lib/settings-model";
import { tecof, withSession } from "@/lib/tecof";

export async function PUT(request: Request) {
  return withSession(request, async ({ installationId, locale }) => {
    const client = tecof.client(installationId);
    const hasKey = (await client.secrets.list()).some((s) => s.key === "apiKey");
    const r = validateOnServer(settingsModel, await request.json().catch(() => null), {
      locale: resolveLocale(locale),
      context: { secrets: { apiKey: hasKey } },
    });
    if (!r.ok) return r.response(); // 422 { error: "validation_failed", message, fields }
    const { apiKey, ...settings } = r.value;
    if (apiKey) await client.secrets.set("apiKey", apiKey);
    await client.settings.set(settings, { merge: true });
    return Response.json({ ok: true });
  });
}
```

- `r.value` yalnız şema alanlarını içerir: fazlası atılır, metinler kırpılır (`trim: false` hariç), sayı ve boolean’lar çevrilir.
- Mağaza ve kurulum kimliği **yalnız doğrulanmış oturum token’ından** alınır; gövde, başlık ya da sorgudan asla. `withSession` şablondaki yardımcıdır (`tecof.sessionFromRequest(request)` üzerine kurulu).

## SecretField ve Vault

Sunucu sırrı istemciye **hiç** göndermez; yalnız durumunu gönderir: `{ set, last4?, display?, updatedAt? }` (`display`, sunucunun ürettiği maske; ör. `"850*****03"`). Boş gönderim mevcut sırrı korur; yeni değer `client.secrets.set(key, value)` ile Vault’a yazılır. Ayrıntı: [Ayarlar, Vault ve metafield’lar](https://tecof-app-dev.vercel.app/app-data).

## Türkiye’ye özgü yardımcılar

```ts
import { parseTrMobile, normalizeTrMobile, maskTrMobile, normalizeIban, isVkn, isTckn } from "@tecof/app-ui/schema";

parseTrMobile("+90 (0532) 111 22 33"); // { ok: true, national: "5321112233", e164: "+905321112233" }
parseTrMobile("0212 111 22 33");       // { ok: false, reason: "not-mobile" }
normalizeTrMobile("0532 111 22 33");   // "+905321112233"
maskTrMobile("05321112233");           // "0532 *** ** 33" — günlükte yalnız bu
```

`parseTrMobile` gerekçeli sonuç döner (`missing` · `invalid` · `not-tr` · `not-mobile`); harf içeren değeri reddeder, `+90` / `0090` / `90` / `0` öneklerini, boşluk, tire, nokta ve parantezi kabul eder. Diğer saf yardımcılar: `isVkn`, `isTckn`, `isTrIban`, `normalizeIban`, `isE164Phone`, `isHttpsUrl(url, hosts)`, `maskSecret`, `formatDateTime`, `formatMoney`.

## Test

Şemayı istemci ve sunucuda aynı mesajı verdiğinden emin olacak şekilde test edin; route handler’larda token yokken 401, alan hatasında 422 ve Vault’a sır yazımını doğrulayın. Uygulama şablonu testleri Node’un yerleşik test çalıştırıcısıyla koşar (`node --test`).

---

# App Bridge

> Panel ile gömülü uygulama arasındaki postMessage protokolü, bağlam nesnesi, @tecof/app-bridge ve React sağlayıcısı.
>
> Kaynak: https://tecof-app-dev.vercel.app/app-bridge · Bölüm: Uygulama geliştirme · Son güncelleme: 2018-10-20

App Bridge, panel içinde iframe olarak açılan uygulama arayüzünüz ile Tecof paneli arasındaki mesajlaşma katmanıdır. Oturum token'ı almak, bildirim göstermek, onay penceresi açmak, panelde başka bir sayfaya gitmek ve aksiyon penceresini kapatmak bu kanal üzerinden yapılır. Altta `window.postMessage` kullanılır; `@tecof/app-bridge` paketi protokolü sizin yerinize yönetir.

---

## Kurulum

```bash
npm i @tecof/app-bridge
```

Paket tarayıcıda çalışır ve bağımlılık içermez. React için `@tecof/app-bridge/react` alt yolu vardır.

---

## Protokol

Her mesaj aynı zarfı taşır:

```json
{ "tecof": "app-bridge", "v": 1, "id": "req_1", "type": "toast", "payload": { "message": "Kaydedildi" } }
```

| Alan | Açıklama |
| :--- | :--- |
| `tecof` | Her zaman `"app-bridge"` |
| `v` | Protokol sürümü: `1` |
| `id` | İsteğe bağlı; istek–yanıt eşleştirmesi için |
| `type` | Mesaj tipi |
| `payload` | Tipe özgü yük |

Panelin yanıtı:

```json
{ "tecof": "app-bridge", "v": 1, "id": "req_1", "type": "response", "ok": true, "payload": {} }
```

Hata durumunda `ok: false` ve `error: { code, message }` döner.

### Güvenlik kuralları

| Taraf | Kural |
| :--- | :--- |
| Panel | Yalnız `event.origin` uygulamanızın origin'ine **ve** `event.source` iframe'in `contentWindow`'una eşit olan mesajları işler. Yanıtı `postMessage(msg, appOrigin)` ile yalnız uygulama origin'ine gönderir |
| Uygulama (SDK) | Yalnız açılış adresindeki `host` parametresinde (base64url) bildirilen panel origin'inden gelen mesajları kabul eder |

SDK'sız çalışıyorsanız bu iki kuralı kendiniz uygulayın; `"*"` hedef origin'iyle mesaj göndermeyin.

---

## Mesaj Tipleri

| `type` (uygulama → panel) | `payload` | Yanıt `payload` |
| :--- | :--- | :--- |
| `handshake` | `{ sdkVersion }` | `{ context }` |
| `sessionToken` | — | `{ token, expiresAt }` |
| `toast` | `{ message, kind?, duration? }` — `kind`: `success`, `error`, `info`, `warning` | `{}` |
| `navigate` | `{ to }` — yalnız `/app/` ile başlayan panel yolu | `{}` |
| `open` | `{ url }` — `https` adresi, yeni sekmede açılır | `{}` |
| `confirm` | `{ title, message, confirmLabel?, cancelLabel?, destructive? }` | `{ confirmed }` |
| `setTitle` | `{ title }` | `{}` |
| `setLoading` | `{ loading }` | `{}` |
| `resize` | `{ height }` — modal/çekmece yüksekliği | `{}` |
| `close` | `{ refresh?, message?, kind? }` — aksiyon penceresini kapatır | `{}` |
| `openBilling` | — | `{}` — plan seçim çekmecesini açar |

Panelden uygulamaya kendiliğinden gelen olay:

```json
{ "tecof": "app-bridge", "v": 1, "type": "context", "payload": { "context": { } } }
```

Bu olay tema ya da dil değiştiğinde güncel bağlamla gönderilir.

---

## Bağlam (context) Nesnesi

```json
{
  "merchant": { "id": "66f0c0ffee0000000000abcd", "name": "Örnek Mağaza", "currency": "TRY", "languages": ["tr", "en"] },
  "user": { "id": "66f0aa00bb11cc22dd33ee66", "name": "Örnek Kullanıcı", "locale": "tr" },
  "installation": {
    "id": "6720aa00bb11cc22dd33ee55",
    "scopes": ["orders:read", "customers:read", "products:read"],
    "plan": { "key": "standart", "status": "active" }
  },
  "app": { "clientId": "tcfa_xxxxxxxxxxxxxxxx", "slug": "isbasi", "name": "Logo İşbaşı" },
  "theme": "light",
  "locale": "tr",
  "action": { "runId": "6720cc00dd11ee22ff33aa55", "key": "create-invoice", "placement": "order.detail", "ids": ["6720bb00cc11dd22ee33ff44"] }
}
```

| Alan | Açıklama |
| :--- | :--- |
| `merchant` | Mağaza kimliği, adı, para birimi, dilleri |
| `user` | Paneli kullanan kişi |
| `installation.scopes` | Verilmiş kapsamlar |
| `installation.plan` | `{ key, status }` ya da plan yoksa `null`. Bkz. [Ücretlendirme](https://tecof-app-dev.vercel.app/app-billing) |
| `app` | Uygulamanın istemci kimliği, slug'ı, adı |
| `theme` | `light` ya da `dark` — arayüzünüzü panelle uyumlu boyayın |
| `locale` | Panel dili |
| `action` | Yalnız iframe aksiyonu olarak açıldığında: `{ runId, key, placement, ids }` |

> Bağlam arayüz içindir. Sunucu tarafında yetki kararı için oturum token'ını doğrulayın; bkz. [Kimlik Doğrulama](https://tecof-app-dev.vercel.app/app-auth).

---

## SDK Kullanımı

```ts
import { createAppBridge, isEmbedded } from "@tecof/app-bridge";

if (!isEmbedded()) {
  // Sayfa panel dışında açıldı (window.top === window.self ya da embedded=1 yok)
}

const bridge = createAppBridge({ debug: false }); // host origin'i URL'deki `host` parametresinden okunur
await bridge.ready();                              // handshake → bridge.context dolar

console.log(bridge.context.merchant.name);

// Oturum token'ı: önbellekli, bitişe 10 sn kala yenilenir
const token = await bridge.getSessionToken();

// Kendi sunucunuza Authorization: Bearer <oturum token'ı> ile istek
const res = await bridge.fetch("/api/orders");

bridge.toast("Ayarlar kaydedildi", { kind: "success" });
bridge.navigate("/app/ecommerce/orders/6720bb00cc11dd22ee33ff44");
bridge.open("https://ornek.com/yardim");

const confirmed = await bridge.confirm({
  title: "Faturayı iptal et",
  message: "Bu işlem geri alınamaz.",
  confirmLabel: "İptal et",
  cancelLabel: "Vazgeç",
  destructive: true,
});

bridge.setTitle("Faturalar");
bridge.setLoading(true);
bridge.resize(640);
bridge.close({ refresh: true, message: "Tamamlandı", kind: "success" });
bridge.openBilling();

const unsubscribe = bridge.on("context", (context) => {
  document.documentElement.dataset.theme = context.theme;
});
```

| Metot | Açıklama |
| :--- | :--- |
| `createAppBridge({ debug? })` | Köprüyü oluşturur |
| `ready()` | Handshake'i tamamlar; ardından `bridge.context` kullanılabilir |
| `context` | Güncel bağlam |
| `getSessionToken()` | Önbellekli oturum token'ı |
| `fetch(input, init)` | `Authorization: Bearer <oturum token'ı>` ekleyerek `fetch` |
| `toast(message, { kind?, duration? })` | Panel bildirimi |
| `navigate(to)` | Panel içi yönlendirme (`/app/…`) |
| `open(url)` | Yeni sekmede `https` adresi |
| `confirm({...})` | Panel onay penceresi → `boolean` |
| `setTitle`, `setLoading`, `resize` | Başlık, yükleniyor durumu, yükseklik |
| `close({ refresh?, message?, kind? })` | Aksiyon penceresini kapatır |
| `openBilling()` | Plan seçim çekmecesi |
| `on("context", cb)` | Bağlam değişimini dinler; aboneliği kaldıran fonksiyon döner |
| `isEmbedded()` | Panel içinde mi (`window.top !== window.self` ve `embedded=1`) |

---

## React

```tsx
// app/layout.tsx
import { AppShell } from "./AppShell";

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

```tsx
// app/AppShell.tsx
"use client";

import { AppBridgeProvider } from "@tecof/app-bridge/react";

export function AppShell({ children }: { children: React.ReactNode }) {
  return (
    <AppBridgeProvider fallback={<p>Yükleniyor…</p>}>
      {children}
    </AppBridgeProvider>
  );
}
```

```tsx
// app/invoices/page.tsx
"use client";

import { useEffect, useState } from "react";
import { useAppBridge, useAppContext, useSessionFetch } from "@tecof/app-bridge/react";

type InvoiceRow = { orderNumber: string; invoiceNumber: string };

export default function InvoicesPage() {
  const bridge = useAppBridge();
  const context = useAppContext();
  const sessionFetch = useSessionFetch();
  const [rows, setRows] = useState<InvoiceRow[]>([]);

  useEffect(() => {
    bridge.setTitle("Faturalar");
    sessionFetch("/api/invoices")
      .then((res) => res.json())
      .then((data) => setRows(data.items))
      .catch(() => bridge.toast("Faturalar yüklenemedi", { kind: "error" }));
  }, [bridge, sessionFetch]);

  return (
    <main data-theme={context.theme}>
      <h1>{context.merchant.name} — Faturalar</h1>
      <ul>
        {rows.map((row) => (
          <li key={row.invoiceNumber}>{row.orderNumber}: {row.invoiceNumber}</li>
        ))}
      </ul>
    </main>
  );
}
```

| API | Açıklama |
| :--- | :--- |
| `<AppBridgeProvider fallback?>` | Köprüyü kurar, handshake bitene kadar `fallback`'i gösterir |
| `useAppBridge()` | Köprü nesnesi |
| `useAppContext()` | Güncel bağlam (`context` olaylarıyla güncellenir) |
| `useSessionFetch()` | Oturum token'ını ekleyen `fetch` |

`useSessionFetch` ile çağrılan sunucu ucunuz token'ı `tecof.sessionFromRequest(req)` ile doğrular. Bkz. [Kimlik Doğrulama](https://tecof-app-dev.vercel.app/app-auth).

---

## SDK'sız Kullanım

Farklı bir çatı kullanıyorsanız protokolü doğrudan uygulayabilirsiniz:

```js
function decodeBase64Url(value) {
  const normalized = value.replace(/-/g, "+").replace(/_/g, "/");
  return atob(normalized + "=".repeat((4 - (normalized.length % 4)) % 4));
}

const params = new URLSearchParams(window.location.search);
const panelOrigin = decodeBase64Url(params.get("host"));
const pending = new Map();
let seq = 0;

window.addEventListener("message", (event) => {
  if (event.origin !== panelOrigin) return;            // yalnız panel origin'i
  const msg = event.data;
  if (!msg || msg.tecof !== "app-bridge" || msg.v !== 1) return;
  if (msg.type === "response" && pending.has(msg.id)) {
    const { resolve, reject } = pending.get(msg.id);
    pending.delete(msg.id);
    msg.ok ? resolve(msg.payload) : reject(msg.error);
  }
  if (msg.type === "context") {
    // msg.payload.context ile arayüzü güncelle
  }
});

function send(type, payload) {
  const id = `req_${++seq}`;
  return new Promise((resolve, reject) => {
    pending.set(id, { resolve, reject });
    window.parent.postMessage({ tecof: "app-bridge", v: 1, id, type, payload }, panelOrigin);
  });
}

const { context } = await send("handshake", { sdkVersion: "custom-1" });
const { token } = await send("sessionToken");
await send("toast", { message: `Merhaba ${context.user.name}`, kind: "info" });
```

---

# Kimlik Doğrulama ve Kapsamlar

> Kapsamlar, kurulum token’ı (tcfi_), 60 sn’lik oturum JWT’si, X-Tecof-Signature imzalı istekler ve istemci sırrı döndürme.
>
> Kaynak: https://tecof-app-dev.vercel.app/app-auth · Bölüm: Uygulama geliştirme · Son güncelleme: 2018-10-20

Partner uygulamaları üç kimlik kanalı kullanır: sunucunuzun Tecof API'sine eriştiği **kurulum token'ı**, panelin iframe arayüzünüze verdiği **oturum token'ı** ve Tecof'un size gönderdiği isteklerdeki **imza**. Üçünün de anahtarı istemci sırrınızdır (`tcfs_…`); bu yüzden sır yalnız sunucuda durur.

---

## Kimlik Bilgileri

| Kimlik | Biçim | Ömür | Not |
| :--- | :--- | :--- | :--- |
| İstemci kimliği | `tcfa_…` | Kalıcı | Herkese açık; tarayıcı koduna girebilir |
| İstemci sırrı | `tcfs_…` | Döndürülene kadar | Yalnız uygulama oluşturma ve sır döndürme yanıtında **bir kez** gösterilir; Tecof tarafında şifreli saklanır |
| Kurulum token'ı | `tcfi_…` | 1 saat | Bir kuruluma (mağaza + uygulama) bağlıdır; `/api/v1/*` için Bearer |
| Oturum token'ı | JWT, HS256 | 60 saniye | Panel → iframe kimlik kanıtı; anahtarı istemci sırrı |
| Geliştirici (CLI) token'ı | `tcfd_…` | Cihaz oturumu 30 gün (14 gün kullanılmazsa düşer); kapsamlı CI token'ı 1–365 gün | CLI, `/api/developer` uçları ve alanlar (Spaces); bkz. [Güvenlik ve CI](https://tecof-app-dev.vercel.app/dev-security) |

---

## Kapsamlar

Mağaza, kurulum onay ekranında uygulamanın istediği kapsamların tamamını görür ve onaylar. Uygulamaya açık kapsamlar Developer API kapsamlarının alt kümesidir:

| Kapsam | Ne verir |
| :--- | :--- |
| `orders:read` | Sipariş okuma (`/api/v1/orders`), `order.*` webhook'ları, sipariş ekranı aksiyonları, sipariş metafield'ları |
| `orders:write` | Sipariş yazma işlemleri (Tools API araçları) |
| `customers:read` | Müşteri okuma (`/api/v1/customers`), `customer.*` webhook'ları, müşteri ekranı aksiyonları, müşteri metafield'ları |
| `customers:write` | Müşteri yazma işlemleri |
| `products:read` | Ürün ve envanter okuma (`/api/v1/products`, `/api/v1/inventory`), `product.*`, `inventory.*`, `review.*` webhook'ları, ürün ekranı aksiyonları, ürün metafield'ları |
| `products:write` | Ürün yazma; **envanter dahil** (ör. `apply_stock_count` aracı). `status: "active"` ürün anında vitrine çıkar |
| `marketing:read` | Pazarlama verisi okuma, `subscriber.created` webhook'u |
| `marketing:write` | Pazarlama yazma işlemleri |
| `settings:read` / `settings:write` | Mağaza ayarlarını okuma / yazma |
| `cms:read` | CMS koleksiyon ve içerik okuma, `cms.item.published` ve `form.submitted` webhook'ları |
| `cms:write` | CMS içerik yazma (taslak) |
| `pages:read` / `pages:write` | Sayfa okuma / taslak yazma |
| `media:read` / `media:write` | Medya kütüphanesi okuma / dosya ekleme |
| `analytics:read` | Analitik ve mağaza özeti okuma |
| `domains:read` | Alan adı ve DNS kayıtlarını okuma |

### Uygulamaya kapalı kapsamlar

Aşağıdaki kapsamlar uygulamalara **verilemez**; `tecof.app.json` içinde istenirse yapılandırma reddedilir. Bunlar ya canlı siteyi doğrudan değiştirir ya da kredi harcar ya da mağaza sahibinin kişisel asistan verisidir.

| Kapsam | Developer API'deki etkisi |
| :--- | :--- |
| `code:read`, `code:write` | Tema deposu okuma/yazma; push üretim yayınını tetikler |
| `sandbox:run` | Bulut IDE'de kod çalıştırma; kredi düşer |
| `deploy:write` | Üretim yeniden dağıtımı, canlı temayı değiştirme |
| `memory:read`, `memory:write` | Mağaza sahibinin asistana yazdığı kalıcı talimatlar |
| `domains:write` | DNS ve nameserver değişikliği; canlı siteyi etkiler |
| `ai:generate` | AI görsel üretimi; kredi düşer |

### Kapsam istemeyen veriler

Uygulamanın **kendi** verisi kapsam istemez; kurulumun kendisi yetkidir:

- Ayarlar (`/api/v1/app/settings`)
- Sırlar / Vault (`/api/v1/app/secrets`)
- `merchant` sahipli metafield'lar (diğer sahip tipleri, kaynağın okuma kapsamını ister)
- Uygulama olayları (`/api/v1/app/events`)

### Kapsam değişikliği

- **Artış:** Yeni yapılandırma ek kapsam isterse mevcut kurulumlara `pendingScopes` yazılır. Panel "Ek izin istiyor" uyarısı gösterir; mağaza onaylayana kadar kurulum **eski kapsamla** çalışır. Onayda `grantedScopes` güncellenir, kurulumun token'ları iptal edilir ve `app.scopes_updated` webhook'u gönderilir. Yayındaki uygulamada kapsam artışı yeniden inceleme ister.
- **Azalma:** Anında uygulanır.

Yetersiz kapsamla yapılan çağrı `403 insufficient-scope` döner; `data` alanı `{ required: [...], missing: [...] }` içerir.

---

## Kurulum Token'ı (Sunucu → Tecof API)

Sunucunuz, istemci kimliği ve sırrıyla bir kurulum için kısa ömürlü erişim token'ı alır (OAuth 2.0 `client_credentials` benzeri). Kullanıcıdan bağımsızdır: webhook işleyicilerinde ve arka plan işlerinde de çalışır.

### İstek

```bash
curl -X POST https://api.tecof.com/api/apps/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "tcfa_xxxxxxxxxxxxxxxx",
    "client_secret": "tcfs_xxxxxxxxxxxxxxxx",
    "installation_id": "6720aa00bb11cc22dd33ee55"
  }'
```

`application/x-www-form-urlencoded` gövde de kabul edilir. `installation_id` yerine `merchant_id` verilebilir; bu durumda o mağazadaki bu uygulamanın kurulumu kullanılır.

### Yanıt

```json
{
  "access_token": "tcfi_xxxxxxxxxxxxxxxx",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "orders:read customers:read",
  "installation_id": "6720aa00bb11cc22dd33ee55",
  "merchant_id": "66f0c0ffee0000000000abcd"
}
```

### Hatalar

Hatalar OAuth biçimindedir:

| HTTP | Gövde | Neden |
| :--- | :--- | :--- |
| 400 | `{ "error": "invalid_request" }` | Eksik ya da hatalı alan |
| 401 | `{ "error": "invalid_client" }` | İstemci kimliği/sırrı yanlış |
| 400 | `{ "error": "invalid_grant", "error_description": "installation-not-found" }` | Kurulum yok ya da bu uygulamaya ait değil |
| 400 | `{ "error": "invalid_grant", "error_description": "installation-inactive" }` | Kurulum aktif değil (kaldırılmış, askıda…) |

### Kurallar

- Token 1 saat geçerlidir. Kapsam değiştiğinde ya da uygulama askıya alındığında **anında** iptal edilir. Kaldırmada token'lar `app.uninstalled` teslimatı **bittikten sonra** iptal edilir; bu sayede kaldırma işleyiciniz API'yi hâlâ çağırabilir.
- Token Tecof'ta sha256 özeti olarak saklanır; token isteği ve yanıtı istek günlüklerine yazılmaz.
- `installation_id` değerini şuralardan alırsınız: `app.installed` webhook'u, her webhook'taki `X-Tecof-Installation-Id` başlığı, doğrulanmış oturum token'ındaki `iid` iddiası.
- Uygulama token'ında paket özelliği kapısı (`apiAccess`) **uygulanmaz**: uygulama erişimi mağazanın paketine bağlı değildir.
- Hız sınırı kurulum başınadır: okuma **240/dk**, yazma **60/dk**.
- `/api/v1` uçlarında geçersiz token `401` döner; `messageCode`: `token-invalid`, `token-revoked`, `token-expired` ya da `app-suspended` (uygulama askıda). Ayrıntılar: [API ile Veri Erişimi](https://tecof-app-dev.vercel.app/app-api).

### SDK ile

SDK token'ı alır, önbelleğe alır ve süresi dolmadan yeniler:

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

const api = tecof.client(installationId);
const orders = await api.orders.list({ paymentStatus: "paid", limit: 50 });
```

---

## Oturum Token'ı (Panel → iframe)

Panel, gömülü uygulamanızı açarken kurulum için 60 saniyelik bir JWT basar. iframe arayüzünüz bu token'ı kendi sunucunuza `Authorization: Bearer` olarak gönderir; sunucunuz istemci sırrınızla ek bir çağrı yapmadan doğrular.

### İddialar (claims)

```json
{
  "iss": "https://api.tecof.com",
  "aud": "tcfa_xxxxxxxxxxxxxxxx",
  "sub": "66f0aa00bb11cc22dd33ee66",
  "mid": "66f0c0ffee0000000000abcd",
  "iid": "6720aa00bb11cc22dd33ee55",
  "locale": "tr",
  "jti": "a1b2c3d4",
  "iat": 1760000000,
  "nbf": 1759999995,
  "exp": 1760000060
}
```

| İddia | Anlamı |
| :--- | :--- |
| `iss` | `https://api.tecof.com` |
| `aud` | Uygulamanızın istemci kimliği |
| `sub` | Paneli kullanan kullanıcının kimliği |
| `mid` | Mağaza kimliği |
| `iid` | Kurulum kimliği |
| `locale` | Panel dili |
| `jti` | Token kimliği |
| `iat` / `nbf` / `exp` | Basım zamanı / `iat - 5` / `iat + 60` |

Başlık: `{ "alg": "HS256", "typ": "JWT" }`.

### Açılış (launch) adresi

Panel uygulamayı ilk kez yüklerken iframe adresini şöyle kurar: `appUrl + path` + sorgu dizesi. Test mağazasında `devUrl` (CLI tüneli) `appUrl`'in yerine geçer.

```text
https://isbasi.apps.tecof.site/invoices?installationId=6720aa00bb11cc22dd33ee55&merchantId=66f0c0ffee0000000000abcd&locale=tr&embedded=1&host=aHR0cHM6Ly9hcHAudGVjb2YuY29t&session=eyJhbGciOiJIUzI1NiIs...
```

| Parametre | Anlamı |
| :--- | :--- |
| `installationId` | Kurulum kimliği |
| `merchantId` | Mağaza kimliği |
| `locale` | Panel dili |
| `embedded` | `1` — panel içinde açıldı |
| `host` | Panel origin'inin base64url kodlaması; App Bridge yalnız bu origin'den gelen mesajı kabul eder |
| `session` | İlk oturum token'ı |
| `actionRunId`, `actionKey`, `placement`, `ids` | Yalnız iframe aksiyonlarında. Bkz. [Aksiyonlar](https://tecof-app-dev.vercel.app/app-actions) |

> **Önemli:** Sorgu dizesindeki `installationId` ve `merchantId` imzalı değildir; yönlendirme ve görüntüleme için kullanın. Yetki kararını her zaman **doğrulanmış oturum token'ındaki** `mid` / `iid` değerlerine göre verin.

İlk token 60 saniyede dolar. Sonraki istekler için App Bridge `getSessionToken()` ile yeni token alın; SDK bitişe 10 saniye kala kendiliğinden yeniler. Bkz. [App Bridge](https://tecof-app-dev.vercel.app/app-bridge).

### Oturum token'ı doğrulama kuralları

1. İmza HS256, anahtar istemci sırrı. Panel token'ı her zaman **güncel** sırla imzalar; sır döndürmeden sonraki 24 saat boyunca doğrulamada eski sır da denenir (döndürme anından hemen önce basılmış token'lar için).
2. `aud` = istemci kimliğiniz.
3. `exp` ve `nbf` ±10 saniye toleransla.
4. `iss` = `https://api.tecof.com`.

### SDK ile doğrulama

```ts
// app/api/orders/route.ts
import { TecofAuthError } from "@tecof/app-sdk";
import { tecof } from "@/lib/tecof";

export async function GET(req: Request) {
  let session;
  try {
    // Authorization: Bearer <oturum token'ı>
    session = tecof.sessionFromRequest(req);
  } catch (err) {
    if (err instanceof TecofAuthError) {
      return Response.json({ error: "unauthorized" }, { status: 401 });
    }
    throw err;
  }

  // session = { merchantId, installationId, userId, locale, exp }
  const api = tecof.client(session.installationId);
  const orders = await api.orders.list({ limit: 20 });
  return Response.json({ orders });
}
```

Token'ı başka bir kaynaktan aldıysanız `tecof.verifySessionToken(token)` aynı iddiaları döner ya da `TecofAuthError` fırlatır.

### Oturum token'ını elle doğrulama (Node.js)

SDK kullanmayan bir sunucu için eşdeğer doğrulama:

```ts
import { createHmac, timingSafeEqual } from "node:crypto";

type SessionClaims = {
  iss: string; aud: string; sub: string; mid: string; iid: string;
  locale: string; jti: string; iat: number; nbf: number; exp: number;
};

function b64urlToBuffer(input: string): Buffer {
  return Buffer.from(input.replace(/-/g, "+").replace(/_/g, "/"), "base64");
}

export function verifyTecofSessionToken(
  token: string,
  opts: { clientId: string; secrets: string[]; leewaySec?: number },
): SessionClaims {
  const leeway = opts.leewaySec ?? 10;
  const parts = token.split(".");
  if (parts.length !== 3) throw new Error("malformed-token");
  const [headerB64, payloadB64, signatureB64] = parts;

  const header = JSON.parse(b64urlToBuffer(headerB64).toString("utf8"));
  if (header.alg !== "HS256") throw new Error("unsupported-alg");

  const signature = b64urlToBuffer(signatureB64);
  const signed = `${headerB64}.${payloadB64}`;
  // secrets: [güncel sır, (döndürmeden sonraki 24 saat içinde) eski sır]
  const valid = opts.secrets.some((secret) => {
    const expected = createHmac("sha256", secret).update(signed).digest();
    return expected.length === signature.length && timingSafeEqual(expected, signature);
  });
  if (!valid) throw new Error("invalid-signature");

  const claims = JSON.parse(b64urlToBuffer(payloadB64).toString("utf8")) as SessionClaims;
  const now = Math.floor(Date.now() / 1000);
  if (claims.aud !== opts.clientId) throw new Error("invalid-audience");
  if (claims.iss !== "https://api.tecof.com") throw new Error("invalid-issuer");
  if (now > claims.exp + leeway) throw new Error("token-expired");
  if (now < claims.nbf - leeway) throw new Error("token-not-yet-valid");
  return claims;
}
```

---

## İmzalı İstekler (Tecof → Uygulama)

Webhook teslimatları ve API aksiyonu çağrıları aynı imzayı taşır:

```http
X-Tecof-Timestamp: 1760000000
X-Tecof-Signature: t=1760000000,v1=5f2c…e91a
```

```text
v1 = HEX( HMAC_SHA256( clientSecret, `${t}.${rawBody}` ) )
```

Sır döndürmeden sonraki 24 saat boyunca başlık iki imza taşır: `t=…,v1=<yeni sırla>,v1=<eski sırla>`.

### İmza doğrulama kuralları

1. `t` değeri ile şimdiki zaman arasındaki fark **en fazla 300 saniye** olmalı (tekrar saldırısı penceresi).
2. Başlıktaki `v1` değerlerinden **herhangi biri** beklenen imzayla eşleşirse istek geçerlidir.
3. Karşılaştırma sabit zamanlı yapılmalıdır (`timingSafeEqual`).
4. İmza **ham gövde** üzerinden hesaplanır. Next.js'te `await req.text()` kullanın; `req.json()` ile okuyup yeniden serileştirmek imzayı bozar.

### SDK ile (tek satır)

```ts
const event = tecof.verifyWebhook(rawBody, req.headers);           // webhook
const action = tecof.verifyActionRequest(rawBody, req.headers);    // API aksiyonu
```

İkisi de imza geçersizse ya da zaman damgası pencere dışındaysa hata fırlatır.

### İmzayı elle doğrulama (Node.js)

```ts
import { createHmac, timingSafeEqual } from "node:crypto";

export function verifyTecofSignature(
  rawBody: string,
  signatureHeader: string | null,
  secrets: string[],          // [güncel sır, (24 saat içinde) eski sır]
  toleranceSec = 300,
): boolean {
  if (!signatureHeader) return false;

  const parts = signatureHeader.split(",").map((p) => p.trim());
  const t = parts.find((p) => p.startsWith("t="))?.slice(2);
  const candidates = parts.filter((p) => p.startsWith("v1=")).map((p) => p.slice(3));
  if (!t || candidates.length === 0) return false;

  const ts = Number(t);
  const now = Math.floor(Date.now() / 1000);
  if (!Number.isFinite(ts) || Math.abs(now - ts) > toleranceSec) return false;

  for (const secret of secrets) {
    const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest();
    for (const candidate of candidates) {
      const given = Buffer.from(candidate, "hex");
      if (given.length === expected.length && timingSafeEqual(given, expected)) return true;
    }
  }
  return false;
}

// Kullanım (Next.js route handler):
// const raw = await req.text();
// const ok = verifyTecofSignature(raw, req.headers.get("x-tecof-signature"), [process.env.TECOF_CLIENT_SECRET!]);
```

### Terminalde imza üretmek

Yerel testte aynı imzayı `openssl` ile üretebilirsiniz:

```bash
T=$(date +%s)
BODY='{"id":"evt_test","event":"order.paid","test":true}'
SIG=$(printf '%s.%s' "$T" "$BODY" | openssl dgst -sha256 -hmac "$TECOF_CLIENT_SECRET" | awk '{print $NF}')
echo "X-Tecof-Signature: t=$T,v1=$SIG"
```

---

## Sır Döndürme

```bash
tecof app secret rotate
```

ya da `POST /api/developer/apps/:id/secret/rotate` → `{ clientSecret, previousValidUntil }`.

Döndürmeden sonraki **24 saat** boyunca:

| Kanal | Eski sırrın durumu |
| :--- | :--- |
| Token ucu (`/api/apps/oauth/token`) | Eski sır da kabul edilir |
| Webhook / API aksiyonu imzası | Başlık iki `v1` taşır (yeni + eski) |
| Oturum token'ı | Panel geçiş boyunca **eski** sırla imzalar (yeni sırra henüz geçmemiş sunucu da doğrular); 24 saat sonra yeni sırla. SDK her iki sırrı da dener (`previousClientSecret`) |

- **Tecof barındırması:** Vercel ortam değişkenleri güncellenir (`TECOF_CLIENT_SECRET` = yeni sır, `TECOF_PREVIOUS_CLIENT_SECRET` = `eski_sır|bitiş_zamanı`) ve yeniden dağıtım kendiliğinden tetiklenir. SDK eski sırrı bitiş zamanından sonra kendiliğinden yok sayar.
- **Kendi sunucunuz:** Yeni sırrı `TECOF_CLIENT_SECRET`'a, eski sırrı geçiş süresince `TECOF_PREVIOUS_CLIENT_SECRET`'a yazın (isterseniz `tcfs_…|2026-10-11T20:00:00Z` biçiminde bitişle — SDK bitişten sonra yok sayar); 24 saat içinde dağıtın. Geçiş boyunca oturum token'ları eski sırla imzalandığı için yeni sırra geçene kadar arayüz kesintisiz çalışır.

```ts
export const tecof = new TecofApp({
  clientId: process.env.TECOF_CLIENT_ID!,
  clientSecret: process.env.TECOF_CLIENT_SECRET!,                    // yeni (güncel) sır
  previousClientSecret: process.env.TECOF_PREVIOUS_CLIENT_SECRET,    // isteğe bağlı: 24 saatlik geçişte eski sır
});
```

---

## Güvenlik Kontrol Listesi

- [ ] İstemci sırrı yalnız sunucu ortam değişkeninde; `NEXT_PUBLIC_` önekli değişkende, repoda, istemci paketinde yok.
- [ ] Her webhook ve API aksiyonu isteği ham gövde üzerinden imza + zaman damgası ile doğrulanıyor.
- [ ] Yetki kararları sorgu dizesine göre değil, doğrulanmış oturum token'ının `mid` / `iid` değerlerine göre veriliyor.
- [ ] Oturum token'ı ve kurulum token'ı günlüğe, URL'e, hata mesajına yazılmıyor.
- [ ] Yalnız gerçekten gereken kapsamlar isteniyor.
- [ ] Mağazadan panel parolası, panel JWT'si ya da mağaza `secretKey`'i istenmiyor; platform bunları uygulamalara vermez.
- [ ] Üçüncü taraf API anahtarları (ör. muhasebe yazılımı parolası) Vault'ta saklanıyor. Bkz. [Vault](https://tecof-app-dev.vercel.app/app-data).
- [ ] `app.uninstalled` geldiğinde o kuruluma ait kendi kopyalarınız siliniyor; teslimattan sonra Tecof token'ları iptal eder, ayarları ve sırları siler.
- [ ] App Bridge mesajları yalnız `host` parametresindeki origin'le alınıp veriliyor (SDK bunu yapar).
- [ ] Sır döndürme prosedürü (24 saatlik geçiş) belgelenmiş.

---

# Webhook'lar

> Webhook aboneliği, olay kataloğu ve gereken kapsamlar, yaşam döngüsü olayları, teslimat biçimi, yeniden deneme ve idempotency.
>
> Kaynak: https://tecof-app-dev.vercel.app/app-webhooks · Bölüm: Uygulama geliştirme · Son güncelleme: 2018-10-20

Webhook'lar, mağazada bir olay olduğunda (sipariş ödendi, ürün güncellendi, müşteri oluşturuldu…) Tecof'un uygulamanıza imzalı bir `POST` isteği göndermesidir. Platform uygulamaları ayrıca kurulum, kaldırma, kapsam, abonelik ve ayar değişikliklerini bildiren **yaşam döngüsü olaylarını** abonelik gerekmeden alır.

---

## Abonelik

Abonelik `tecof.app.json` içinde tanımlanır:

```json
{
  "scopes": ["orders:read", "customers:read"],
  "webhooks": {
    "path": "/api/webhooks",
    "events": ["order.paid", "order.cancelled", "order.refunded", "customer.created"]
  }
}
```

- `path`, `appUrl`'e göredir ve `/` ile başlar. Teslimat adresi: `appUrl + webhooks.path`. Test mağazası kurulumlarında, `tecof app dev` açıksa `appUrl` yerine tünel adresi (`devUrl`) kullanılır; adres teslimat anında çözülür.
- **`webhooks.path` tanımlı değilse** yaşam döngüsü olayları (`app.installed`, `app.uninstalled`…) ve uygulama olayları da teslim edilemez. Mağaza olayı dinlemeseniz bile `path` tanımlayın.
- Her olayın gerektirdiği okuma kapsamı `scopes` içinde olmalıdır; aksi hâlde yapılandırma reddedilir.
- `*` (tüm olaylar) jokeri uygulamalara **kapalıdır**.
- Mağaza uygulamayı kurduğunda abonelik otomatik açılır. Yapılandırma değişince abonelik eşitlenir: etkin olaylar, yapılandırmadaki olaylarla mağazanın **verdiği** kapsamların kesişimidir.

---

## Olay Kataloğu ve Gereken Kapsam

| Olay | Açıklama | Gereken kapsam |
| :--- | :--- | :--- |
| `order.created` | Sipariş oluşturuldu | `orders:read` |
| `order.paid` | Sipariş ödendi | `orders:read` |
| `order.updated` | Sipariş durumu güncellendi | `orders:read` |
| `order.fulfilled` | Sipariş kargolandı | `orders:read` |
| `order.cancelled` | Sipariş iptal edildi | `orders:read` |
| `order.refunded` | Sipariş iade edildi | `orders:read` |
| `order.return_requested` | İade talebi oluşturuldu | `orders:read` |
| `order.return_approved` | İade talebi onaylandı | `orders:read` |
| `order.return_rejected` | İade talebi reddedildi | `orders:read` |
| `order.return_received` | İade ürünü teslim alındı | `orders:read` |
| `order.return_resolved` | İade talebi sonuçlandı | `orders:read` |
| `order.shipping_updated` | Kargo bilgisi güncellendi | `orders:read` |
| `product.created` | Ürün oluşturuldu | `products:read` |
| `product.updated` | Ürün güncellendi | `products:read` |
| `product.deleted` | Ürün silindi | `products:read` |
| `inventory.low_stock` | Düşük stok uyarısı | `products:read` |
| `inventory.out_of_stock` | Stok tükendi | `products:read` |
| `review.created` | Yorum gönderildi | `products:read` |
| `review.approved` | Yorum onaylandı | `products:read` |
| `customer.created` | Müşteri oluşturuldu | `customers:read` |
| `customer.updated` | Müşteri güncellendi | `customers:read` |
| `customer.deleted` | Müşteri silindi | `customers:read` |
| `subscriber.created` | Bülten abonesi eklendi | `marketing:read` |
| `cms.item.published` | CMS içeriği yayınlandı | `cms:read` |
| `form.submitted` | Form gönderildi | `cms:read` |

Başka uygulamaların yayınladığı `app.<slug>.<ad>` olayları da aynı biçimde teslim edilir; bkz. [Uygulamalar Arası İletişim](https://tecof-app-dev.vercel.app/app-interop).

---

## Yaşam Döngüsü Olayları

Bu olaylar **her zaman** gönderilir; `webhooks.events` içinde listelenmeleri gerekmez.

| Olay | Ne zaman | `data` |
| :--- | :--- | :--- |
| `app.installed` | Mağaza uygulamayı kurduğunda | `{ installationId, merchantId, scopes, planKey, subscription, isTestInstall }` |
| `app.uninstalled` | Mağaza uygulamayı kaldırdığında. **Tek deneme**, 8 sn zaman aşımı | `{ installationId, merchantId }` |
| `app.scopes_updated` | Mağaza ek izin isteğini onayladığında | `{ scopes }` |
| `app.subscription.updated` | Abonelik durumu her değiştiğinde | `{ planKey, status, trialEndsAt, currentPeriodEnd, chargeId }` |
| `app.settings.updated` | Mağaza paneldeki ayar formunu kaydettiğinde | `{ keys: [...], secretKeys: [...] }` — **değer içermez** |

**`app.uninstalled`:** Kurulumun token'ları bu teslimat **bittikten sonra** iptal edilir; işleyiciniz 8 saniye içinde Tecof API'sini hâlâ çağırabilir (ör. son durumu okumak için). Teslimattan sonra kurulum kaldırılır, kurulumun ayarları ve sırları silinir. Olay yeniden denenmez; kaçırırsanız temizliği bir sonraki API çağrısında aldığınız `401` ile tetikleyin.

**`app.settings.updated`** yalnız mağaza paneldeki ayar formunu kaydettiğinde gelir; uygulamanızın `PUT /api/v1/app/settings` ile yaptığı yazmalar bu olayı **üretmez**. Olay değer taşımaz: değişen ayarları `api.settings.get()` ve `api.secrets.get(key)` ile okuyun.

---

## Teslimat Biçimi

```http
POST /api/webhooks HTTP/1.1
Host: isbasi.apps.tecof.site
Content-Type: application/json
User-Agent: Tecof-Webhooks/1.0
X-Tecof-Event: order.paid
X-Tecof-Event-Id: evt_7f3a2c9e1b
X-Tecof-Delivery-Attempt: 1
X-Tecof-Merchant-Id: 66f0c0ffee0000000000abcd
X-Tecof-Installation-Id: 6720aa00bb11cc22dd33ee55
X-Tecof-App-Id: tcfa_xxxxxxxxxxxxxxxx
X-Tecof-Timestamp: 1760087770
X-Tecof-Signature: t=1760087770,v1=5f2c…e91a
X-Webhook-Event: order.paid
```

```json
{
  "id": "evt_7f3a2c9e1b",
  "event": "order.paid",
  "test": false,
  "timestamp": "2026-10-10T09:16:10.000Z",
  "merchantId": "66f0c0ffee0000000000abcd",
  "installationId": "6720aa00bb11cc22dd33ee55",
  "data": {
    "orderId": "6720bb00cc11dd22ee33ff44",
    "orderNumber": "TCF-1001",
    "status": "confirmed",
    "paymentStatus": "paid",
    "totalPrice": 1050,
    "taxPrice": 175,
    "pricesIncludeTax": true,
    "currencyCode": "TRY",
    "customerEmail": "musteri@example.com",
    "merchantId": "66f0c0ffee0000000000abcd",
    "merchantName": "Örnek Mağaza"
  }
}
```

| Başlık | Açıklama |
| :--- | :--- |
| `X-Tecof-Event` | Olay adı |
| `X-Tecof-Event-Id` | Olay kimliği; yeniden denemelerde **aynı** kalır — idempotency anahtarı |
| `X-Tecof-Delivery-Attempt` | Deneme sayısı (1'den başlar) |
| `X-Tecof-Merchant-Id` | Mağaza kimliği |
| `X-Tecof-Installation-Id` | Kurulum kimliği (kurulum token'ı almak için) |
| `X-Tecof-App-Id` | Uygulamanın istemci kimliği |
| `X-Tecof-Timestamp`, `X-Tecof-Signature` | İmza; bkz. [İmzalı İstekler](https://tecof-app-dev.vercel.app/app-auth) |
| `X-Webhook-Event` | Geriye uyum için olay adı |

Mağaza olaylarının `data` alanı, mağaza webhook'larının gönderdiği yükün **aynısıdır**; Tecof `merchantId` ve `merchantName` alanlarını ekler. Sipariş olaylarında `orderId`, `orderNumber`, `status`, `paymentStatus`, `totalPrice`, `taxPrice`, `pricesIncludeTax`, `currencyCode`, `customerEmail` gibi özet alanlar gelir. Satırlar, adresler ve vergi kırılımı dahil siparişin tam ve kararlı şekli için `GET /api/v1/orders/:id` ile okuyun (`api.orders.get(data.orderId)`). Bkz. [API ile Veri Erişimi](https://tecof-app-dev.vercel.app/app-api).

Platform uygulamalarına ham sır içeren `X-Webhook-Secret` başlığı **gönderilmez** (yalnız eski birinci parti ve mağaza webhook'larında sürer). Doğrulama yalnız `X-Tecof-Signature` ile yapılır.

---

## Yeniden Deneme ve Otomatik Pasifleştirme

| Kural | Davranış |
| :--- | :--- |
| Başarı | Herhangi bir `2xx` yanıtı teslim edildi sayılır |
| Zaman aşımı | Deneme başına **8 saniye** |
| Başarısızlık | `2xx` dışı yanıt, bağlantı hatası ya da zaman aşımında yeniden denenir. Toplam **3 deneme**: ilk teslimat + 2 yeniden deneme (+2 dk, +15 dk) |
| Gövde | Yeniden denemeler ve elle yeniden gönderim **tam gövdeyle** (≤ 256 KB) yapılır; `X-Tecof-Event-Id` değişmez, `X-Tecof-Delivery-Attempt` artar |
| Otomatik pasifleştirme | **20 ardışık** başarısız teslimattan sonra abonelik pasife alınır |
| Yeniden etkinleştirme | `tecof app config push` (yapılandırma yazımı) uygulamanın tüm pasif aboneliklerini yeniden etkinleştirir; mağaza da paneldeki Webhook ekranından aboneliği açabilir |
| `app.uninstalled` | Tek deneme (8 sn); yeniden denenmez |

Teslimat geçmişinizi geliştirici API'sinden izleyebilirsiniz: `GET /api/developer/apps/:id/deliveries`.

---

## Idempotency

Aynı olay birden fazla kez gelebilir (yeniden deneme, ağ kopması). İşleyicinizi idempotent yazın:

1. **Olay kimliği:** `X-Tecof-Event-Id` (gövdede `id`) yeniden denemelerde aynıdır. İşlenen kimlikleri kendi deponuzda tutup tekrarı atlayın.
2. **Kaynak durumu:** Daha sağlam yol, işin yapılıp yapılmadığını kaynağın kendisinden anlamaktır. Örneğin fatura kesen bir uygulama faturayı oluşturunca siparişe `invoiceNumber` metafield'ı yazar; aynı sipariş için gelen ikinci `order.paid` bu metafield'ı görüp atlanır.
3. **Sıra:** Yeniden denemeler nedeniyle olaylar oluş sırasından farklı sırada gelebilir. Kararı olay yüküne değil, API'den okuduğunuz güncel duruma göre verin.

---

## Örnek İşleyici (Next.js App Router)

SDK'nın `createWebhookHandler` yardımcısı doğrulamayı, olay yönlendirmeyi ve yanıt kodlarını üstlenir. Dönen fonksiyon doğrudan bir Route Handler'dır:

```ts
// app/api/webhooks/route.ts
import { createWebhookHandler } from "@tecof/app-sdk";
import { tecof } from "@/lib/tecof";

export const POST = createWebhookHandler({
  app: tecof,
  handlers: {
    "app.installed": async (event) => {
      await tecof.client(event.installationId).settings.set({ invoiceMode: "draft" }, { merge: true });
    },

    "app.uninstalled": async (event) => {
      // Token'lar bu teslimat bittikten sonra iptal edilir; gerekirse burada API'yi çağırabilirsiniz.
      // Kendi sistemlerinizdeki kopyaları temizleyin (8 sn içinde).
    },

    "app.settings.updated": async (event) => {
      // Değerler gelmez; gerekirse api.settings.get() / api.secrets.get(key) ile okuyun
    },

    "order.paid": async (event) => {
      const api = tecof.client(event.installationId);
      const orderId = String(event.data.orderId);

      const existing = await api.metafields.list({ ownerType: "order", ownerId: orderId, namespace: "isbasi" });
      if (existing.some((m: { key: string }) => m.key === "invoiceNumber")) return; // zaten işlendi

      const order = await api.orders.get(orderId);
      // … faturayı oluştur, sonra siparişe invoiceNumber metafield'ı yaz
    },
  },
});
```

| Durum | `createWebhookHandler` yanıtı |
| :--- | :--- |
| İmza ya da zaman damgası geçersiz | `401` |
| Test olayı (`test: true`) | `200` (varsayılan olarak işleyiciler çalıştırılmaz) |
| İşleyicisi tanımlı olmayan olay | `200` |
| İşleyici başarıyla döndü | `200` |
| İşleyici hata fırlattı | `2xx` olmayan yanıt → Tecof yeniden dener |

### SDK yardımcısı olmadan

```ts
// app/api/webhooks/route.ts
import { tecof } from "@/lib/tecof";

export async function POST(req: Request) {
  const rawBody = await req.text(); // ham gövde — imza bunun üzerinden hesaplanır

  let event;
  try {
    event = tecof.verifyWebhook(rawBody, req.headers); // Headers ya da düz nesne kabul eder
  } catch {
    return new Response("invalid signature", { status: 401 });
  }

  if (event.test) return new Response(null, { status: 204 });

  switch (event.event) {
    case "order.paid":
      // …
      break;
  }
  return new Response(null, { status: 204 });
}
```

İpuçları:

- İşleyiciyi 8 saniyelik zaman aşımının altında tutun ve işlem bitince `2xx` dönün. `2xx` dışındaki her yanıt yeniden denemeye ve ardışık hata sayacına yazılır.
- Kalıcı olarak işlenemeyecek bir olay için (ör. mağaza ayarları eksik) `2xx` dönüp durumu kendi tarafınızda kaydedin; aksi hâlde yeniden denemeler ve ardışık hatalar aboneliği pasife düşürebilir.

---

## Test Etme

| Yöntem | Nasıl |
| :--- | :--- |
| Test mağazası + tünel | `tecof app dev` çalışırken test mağazasında gerçek olay üretin (ör. sipariş oluşturup ödendi işaretleyin); webhook doğrudan yerel sunucunuza gelir |
| Panelden test teslimatı | Mağaza panelindeki Webhook ekranında aboneliği seçip **"Test Et"** ile `test: true` taşıyan bir teslimat gönderilebilir |
| Yerel imzalı istek | Aşağıdaki `curl` + `openssl` ile kendi uçunuza imzalı gövde gönderin |
| Teslimat günlüğü | `GET /api/developer/apps/:id/deliveries` ile yanıt kodlarını ve denemeleri izleyin |

```bash
SECRET="$TECOF_CLIENT_SECRET"
T=$(date +%s)
BODY='{"id":"evt_local_1","event":"order.paid","test":false,"timestamp":"2026-10-10T09:16:10.000Z","merchantId":"66f0c0ffee0000000000abcd","installationId":"6720aa00bb11cc22dd33ee55","data":{"orderId":"6720bb00cc11dd22ee33ff44","orderNumber":"TCF-1001"}}'
SIG=$(printf '%s.%s' "$T" "$BODY" | openssl dgst -sha256 -hmac "$SECRET" | awk '{print $NF}')

curl -X POST http://localhost:3000/api/webhooks \
  -H "Content-Type: application/json" \
  -H "X-Tecof-Event: order.paid" \
  -H "X-Tecof-Event-Id: evt_local_1" \
  -H "X-Tecof-Delivery-Attempt: 1" \
  -H "X-Tecof-Installation-Id: 6720aa00bb11cc22dd33ee55" \
  -H "X-Tecof-Timestamp: $T" \
  -H "X-Tecof-Signature: t=$T,v1=$SIG" \
  --data-binary "$BODY"
```

Elle imzalı istekte `installationId` gerçek bir test kurulumuna ait değilse API çağrıları (`api.orders.get`) başarısız olur; imza ve yönlendirme mantığını bu yolla, uçtan uca akışı test mağazasında tünelle doğrulayın.

---

## Mağaza webhook’ları (panelden)

Uygulama yazmadan, bir mağazanın olaylarını kendi sunucunuza göndermek için mağaza sahibi panelde (**E-ticaret → Ayarlar → Webhook’lar**) webhook tanımlayabilir. Bu webhook’lar aynı olay kataloğunu kullanır, `*` (tüm olaylar) jokerine izin verir ve eski usul `X-Webhook-Secret` başlığıyla doğrulanır. Panel aşağıdaki uçları JWT ile çağırır; üçüncü taraf entegrasyonlar için platform uygulaması önerilir.

| Metot | Uç | Açıklama |
| :--- | :--- | :--- |
| `GET` | `/api/merchant/ecommerce/webhooks` | Liste |
| `POST` | `/api/merchant/ecommerce/webhooks` | Oluştur |
| `PUT` · `DELETE` | `/api/merchant/ecommerce/webhooks/:id` | Güncelle · sil |
| `POST` | `/api/merchant/ecommerce/webhooks/:id/test` | Test gönderimi |
| `GET` | `/api/merchant/ecommerce/webhooks/deliveries` | Teslimat geçmişi |
| `POST` | `/api/merchant/ecommerce/webhooks/deliveries/:id/redeliver` | Aynı yükle yeniden gönder |

---

# Aksiyonlar (Actions)

> Panel yerleşimleri, iframe ve API aksiyonları, imzalı istek/yanıt biçimi ve aksiyonları yerelde test etme.
>
> Kaynak: https://tecof-app-dev.vercel.app/app-actions · Bölüm: Uygulama geliştirme · Son güncelleme: 2018-10-20

Aksiyonlar, uygulamanızın Tecof panelindeki sipariş, ürün ve müşteri ekranlarına kendi işlemlerini eklemesini sağlar. Örneğin bir muhasebe uygulaması sipariş detayına "Fatura kes" düğmesi, sipariş listesine "Seçilenleri faturala" toplu işlemi ekleyebilir.

İki tür aksiyon vardır:

| Tür | Ne olur | Ne zaman |
| :--- | :--- | :--- |
| `iframe` | Panel, uygulamanızın bir sayfasını modal ya da çekmece içinde açar | Kullanıcıdan girdi almak, önizleme göstermek gerekiyorsa |
| `api` | Panel Tecof'a çalıştırma isteği gönderir; Tecof uygulamanıza imzalı bir `POST` atar ve yanıtınızı kullanıcıya bildirim olarak gösterir | Tek tıkla biten işlemler, toplu işlemler |

---

## Yerleşimler

| `placement` | Ekran | Bağlam (`ids`) | Gerekli kapsam |
| :--- | :--- | :--- | :--- |
| `order.detail` | Sipariş detayı, başlıktaki "Uygulamalar" menüsü | `[orderId]` | `orders:read` |
| `order.list` | Sipariş listesi, toplu işlem menüsü | Seçili sipariş kimlikleri (≤ 50) | `orders:read` |
| `product.detail` | Ürün detayı | `[productId]` | `products:read` |
| `product.list` | Ürün listesi, toplu işlem menüsü | Seçili ürün kimlikleri (≤ 50) | `products:read` |
| `customer.detail` | Müşteri detayı | `[customerId]` | `customers:read` |
| `customer.list` | Müşteri listesi, toplu işlem menüsü | Seçili müşteri kimlikleri (≤ 50) | `customers:read` |

Aksiyon panelde yalnız **aktif** ve yerleşimin gerektirdiği kapsamı **verilmiş** kurulumlarda listelenir.

---

## Tanımlama

Aksiyonlar `tecof.app.json` içindeki `actions` dizisinde tanımlanır (en fazla 12):

```json
{
  "actions": [
    {
      "key": "create-invoice",
      "type": "iframe",
      "placement": "order.detail",
      "title": { "tr": "İşbaşı'nda fatura kes", "en": "Create İşbaşı invoice" },
      "path": "/actions/create-invoice",
      "presentation": "modal"
    },
    {
      "key": "bulk-invoice",
      "type": "api",
      "placement": "order.list",
      "title": { "tr": "Seçilenleri faturala", "en": "Invoice selected" },
      "path": "/api/actions/bulk-invoice",
      "confirm": {
        "tr": "Seçili siparişler için fatura kesilsin mi?",
        "en": "Create invoices for selected orders?"
      }
    }
  ]
}
```

| Alan | Kural |
| :--- | :--- |
| `key` | `^[a-z][a-z0-9-]{1,39}$`; uygulama içinde tekil |
| `type` | `iframe` ya da `api` |
| `placement` | Yukarıdaki tablodan biri |
| `title` | `{ tr, en }`; panel diline göre gösterilir |
| `path` | `appUrl`'e göre, `/` ile başlar |
| `presentation` | Yalnız `iframe`: `modal` (varsayılan) ya da `drawer` |
| `confirm` | Yalnız `api`, isteğe bağlı: `{ tr, en }` metniyle panel çalıştırmadan önce onay sorar |

Değişikliği `tecof app config push` ile gönderin.

---

## Panel Tarafında Akış

```mermaid
sequenceDiagram
    participant U as Kullanıcı (panel)
    participant P as Tecof Paneli / API
    participant A as Uygulamanız

    P->>P: GET /api/merchant/apps/actions?placement=order.list
    U->>P: Aksiyonu seçer (ve onaylar)
    P->>P: POST /api/merchant/apps/actions/run { installationId, actionKey, placement, ids }
    alt type = iframe
        P->>A: iframe: launch URL + actionRunId, actionKey, placement, ids
        A->>P: App Bridge close({ refresh, message, kind })
    else type = api
        P->>A: İmzalı POST (15 sn zaman aşımı)
        A-->>P: { ok, message, kind, redirectUrl, refresh }
        P->>U: Bildirim / yenileme / yönlendirme
    end
```

Her çalıştırma bir kayıt (`runId`) üretir. Geliştirici API'sinden geçmişi izleyebilirsiniz: `GET /api/developer/apps/:id/action-runs`.

---

## iframe Aksiyonları

Panel aksiyon penceresini, uygulamanızın açılış (launch) adresine şu parametreleri ekleyerek açar:

```text
https://isbasi.apps.tecof.site/actions/create-invoice?installationId=…&merchantId=…&locale=tr&embedded=1&host=…&session=…&actionRunId=…&actionKey=create-invoice&placement=order.detail&ids=6720bb00cc11dd22ee33ff44
```

`ids` virgülle ayrılmış kimliklerdir. Aynı bilgi App Bridge bağlamında `context.action = { runId, key, placement, ids }` olarak da gelir. İşiniz bitince `close` ile pencereyi kapatın; `refresh: true` paneldeki ekranı yeniler.

```tsx
// app/actions/create-invoice/page.tsx
"use client";

import { useState } from "react";
import { useAppBridge, useAppContext, useSessionFetch } from "@tecof/app-bridge/react";

export default function CreateInvoiceAction() {
  const bridge = useAppBridge();
  const context = useAppContext();
  const sessionFetch = useSessionFetch();
  const [busy, setBusy] = useState(false);

  const orderId = context.action?.ids[0];

  async function createInvoice() {
    if (!orderId) return;
    setBusy(true);
    bridge.setLoading(true);
    try {
      const res = await sessionFetch("/api/invoices", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ orderId }),
      });
      if (!res.ok) throw new Error("invoice-failed");
      bridge.close({ refresh: true, message: "Fatura oluşturuldu", kind: "success" });
    } catch {
      bridge.toast("Fatura oluşturulamadı", { kind: "error" });
    } finally {
      bridge.setLoading(false);
      setBusy(false);
    }
  }

  return (
    <main style={{ padding: 24 }}>
      <h1>Fatura kes</h1>
      <p>Sipariş: {orderId}</p>
      <button onClick={createInvoice} disabled={busy}>Faturayı oluştur</button>
      <button onClick={() => bridge.close()}>Vazgeç</button>
    </main>
  );
}
```

Sayfanın `AppBridgeProvider` içinde olması gerekir; bkz. [App Bridge](https://tecof-app-dev.vercel.app/app-bridge). `/api/invoices` sizin uçunuzdur ve isteği oturum token'ıyla doğrular (`tecof.sessionFromRequest(req)`).

---

## API Aksiyonları

### İstek

Tecof, `appUrl + path` adresine imzalı bir `POST` gönderir (test mağazası kurulumunda `tecof app dev` açıksa tünel adresine). Zaman aşımı **15 saniyedir**; aksiyonlar **yeniden denenmez**.

```http
POST /api/actions/bulk-invoice HTTP/1.1
Content-Type: application/json
X-Tecof-Timestamp: 1760087770
X-Tecof-Signature: t=1760087770,v1=5f2c…e91a
X-Tecof-Action: bulk-invoice
X-Tecof-Installation-Id: 6720aa00bb11cc22dd33ee55
```

```json
{
  "actionRunId": "6720cc00dd11ee22ff33aa55",
  "actionKey": "bulk-invoice",
  "placement": "order.list",
  "ids": ["6720bb00cc11dd22ee33ff44", "6720bb00cc11dd22ee33ff45"],
  "merchantId": "66f0c0ffee0000000000abcd",
  "installationId": "6720aa00bb11cc22dd33ee55",
  "userId": "66f0aa00bb11cc22dd33ee66",
  "locale": "tr",
  "timestamp": "2026-10-10T09:16:10.000Z"
}
```

### Yanıt

Yanıt JSON ve **en fazla 16 KB** olmalıdır:

```json
{
  "ok": true,
  "message": "2 fatura oluşturuldu",
  "kind": "success",
  "redirectUrl": "https://isbasi.apps.tecof.site/invoices",
  "refresh": true
}
```

| Alan | Anlamı |
| :--- | :--- |
| `ok` | İşlem sonucu |
| `message` | Kullanıcıya gösterilecek mesaj |
| `kind` | `success`, `error`, `info`, `warning` |
| `redirectUrl` | İsteğe bağlı yönlendirme adresi |
| `refresh` | `true` ise panel ekranı yeniler |

Panel tarafına `{ runId, type: "api", ok, message, kind, redirectUrl, refresh }` döner. `2xx` olmayan yanıt ya da zaman aşımı `ok: false`, `kind: "error"` ve genel `app-action-failed` mesajına dönüşür. Kullanıcıya **kendi** hata mesajınızı göstermek istiyorsanız `200` ile `{ "ok": false, "kind": "error", "message": "…" }` dönün.

### İşleyici

```ts
// app/api/actions/bulk-invoice/route.ts
import { tecof } from "@/lib/tecof";

export async function POST(req: Request) {
  const rawBody = await req.text();

  let action;
  try {
    action = tecof.verifyActionRequest(rawBody, req.headers);
  } catch {
    return Response.json({ ok: false, kind: "error", message: "Geçersiz imza" }, { status: 401 });
  }

  const api = tecof.client(action.installationId);
  let created = 0;
  const failed: string[] = [];

  for (const orderId of action.ids) {
    try {
      const order = await api.orders.get(orderId);
      // … faturayı oluştur, siparişe metafield yaz
      created++;
    } catch {
      failed.push(orderId);
    }
  }

  if (failed.length > 0) {
    return Response.json({
      ok: created > 0,
      kind: created > 0 ? "warning" : "error",
      message: `${created} fatura oluşturuldu, ${failed.length} sipariş atlandı`,
      refresh: true,
    });
  }

  return Response.json({ ok: true, kind: "success", message: `${created} fatura oluşturuldu`, refresh: true });
}
```

15 saniyelik sınırı aşabilecek toplu işlerde işi küçük parçalara bölün; aksiyon yeniden denenmediği için işleyicinin yarıda kalması durumunda kullanıcının aksiyonu tekrar çalıştırması güvenli olmalıdır (idempotent tasarım: işlenmiş siparişleri metafield ile atlayın).

---

## Yerelde Test

**Uçtan uca (önerilen):** `tecof app dev` çalışırken uygulamanız test mağazasında kuruluysa, panelden çalıştırdığınız hem iframe hem API aksiyonları tünel üzerinden yerel sunucunuza gelir (`devUrl`, test mağazası kurulumlarında `appUrl`'in yerine geçer). Bkz. [Hızlı Başlangıç](https://tecof-app-dev.vercel.app/app-quickstart).

**Yalnız imza ve yanıt biçimi:** API aksiyonunu yerel sunucunuza imzalı `curl` ile de gönderebilirsiniz:

```bash
SECRET="$TECOF_CLIENT_SECRET"
T=$(date +%s)
BODY='{"actionRunId":"local-run-1","actionKey":"bulk-invoice","placement":"order.list","ids":["6720bb00cc11dd22ee33ff44"],"merchantId":"66f0c0ffee0000000000abcd","installationId":"6720aa00bb11cc22dd33ee55","userId":"66f0aa00bb11cc22dd33ee66","locale":"tr","timestamp":"2026-10-10T09:16:10.000Z"}'
SIG=$(printf '%s.%s' "$T" "$BODY" | openssl dgst -sha256 -hmac "$SECRET" | awk '{print $NF}')

curl -X POST http://localhost:3000/api/actions/bulk-invoice \
  -H "Content-Type: application/json" \
  -H "X-Tecof-Timestamp: $T" \
  -H "X-Tecof-Signature: t=$T,v1=$SIG" \
  -H "X-Tecof-Action: bulk-invoice" \
  -H "X-Tecof-Installation-Id: 6720aa00bb11cc22dd33ee55" \
  --data-binary "$BODY"
```

- `printf '%s.%s'` ile imzalanan metin ile `--data-binary` ile gönderilen gövde **bayt bayt aynı** olmalıdır.
- `installationId` gerçek bir test kurulumuna ait değilse işleyicideki API çağrıları başarısız olur; uçtan uca akışı test mağazasında tünelle doğrulayın.
- iframe aksiyonları için test mağazasında aksiyonu panelden çalıştırın; App Bridge yalnız panel içinde çalışır.

---

## Sık Karşılaşılan Hatalar

| Belirti | Olası neden | Çözüm |
| :--- | :--- | :--- |
| Aksiyon panelde görünmüyor | Yapılandırma gönderilmedi; kurulum aktif değil; yerleşimin gerektirdiği kapsam verilmemiş; onaysız uygulama test mağazası dışında | `tecof app config push`; kapsamı ekleyip mağazaya onaylatın; `testStores`'u kontrol edin |
| Test mağazasında aksiyon yerel sunucuya ulaşmıyor | `tecof app dev` kapalı ya da `devUrl`'in 8 saatlik süresi doldu | `tecof app dev`'i yeniden başlatın |
| Panelde `app-action-failed` | Uç `2xx` dışı yanıt döndü ya da 15 saniyeyi aştı | Kendi hata mesajınız için `200` + `ok: false` dönün; işi bölün |
| İşleyici `401` dönüyor | Gövde JSON olarak okunup yeniden serileştirildi; yanlış sır; saat farkı 300 sn'yi aşıyor | `await req.text()` kullanın; `TECOF_CLIENT_SECRET`'ı kontrol edin; sunucu saatini eşitleyin |
| Sır döndürmeden sonra imza hatası | Uygulama eski sırla çalışıyor ve yalnız tek `v1` kontrol ediliyor | Başlıktaki tüm `v1` değerlerini deneyin (SDK yapar); yeni sırrı ortama yazın |
| Panelde beklediğiniz mesaj görünmüyor | Yanıt JSON değil ya da 16 KB sınırını aşıyor | Yanıtı en fazla 16 KB'lık JSON olarak dönün |
| iframe aksiyonu boş açılıyor | Sayfa `X-Frame-Options: DENY` ya da panel origin'ini içermeyen `frame-ancestors` gönderiyor | Panel origin'inin uygulamanızı çerçevelemesine izin verin |
| `close()` çalışmıyor | App Bridge hazır değil ya da sayfa panel dışında açıldı | `AppBridgeProvider` / `bridge.ready()` sonrasında çağırın |
| Toplu işlemde 50'den fazla kayıt | Panel seçim sınırı | Yerleşim başına en fazla 50 kimlik gelir |

---

# Ayarlar, Vault ve Metafield'lar

> Kurulum ayarları, şifreli Vault sırları, yerel ayar formu ve kaynaklara bağlı metafield’lar.
>
> Kaynak: https://tecof-app-dev.vercel.app/app-data · Bölüm: Uygulama geliştirme · Son güncelleme: 2018-10-20

Tecof, uygulamanızın kurulum başına veri saklamasını sağlayan üç katman sunar. Bu katmanlarla birçok uygulama **kendi veritabanına ihtiyaç duymadan**, örneğin Vercel üzerinde durumsuz (stateless) çalışabilir.

| Katman | Ne için | Boyut | Kaldırmada |
| :--- | :--- | :--- | :--- |
| Ayarlar | Sır olmayan yapılandırma (JSON) | ≤ 64 KB | Silinir |
| Vault (sırlar) | API anahtarı, parola, token | Değer ≤ 8 KB, en fazla 50 anahtar | Silinir |
| Metafield'lar | Sipariş, ürün, müşteri ya da mağazaya bağlı uygulama verisi | Değer ≤ 16 KB | Panelde gizlenir, 30 gün sonra temizlenir |

Ayarlar ve sırlar kapsam istemez; kurulumun kendisi yetkidir.

---

## Ayarlar

Kurulum başına tek bir JSON nesnesi.

| Metot | Uç | Açıklama |
| :--- | :--- | :--- |
| `GET` | `/api/v1/app/settings` | `{ settings, updatedAt }` |
| `PUT` | `/api/v1/app/settings` | `{ settings, merge?: boolean }`; ≤ 64 KB → `{ settings, updatedAt }` |

```ts
const api = tecof.client(installationId);

const { settings } = await api.settings.get();
await api.settings.set({ invoiceMode: "issued", seriesPrefix: "ABC" }, { merge: true });
```

`merge: true` gönderilen anahtarları mevcut nesneyle birleştirir; `merge` olmadan nesne tamamen değiştirilir. Panelin yerel ayar formu da **aynı ayar nesnesine** yazar (birleştirerek; formda olmayan anahtarlar korunur). API'den yapılan yazmalar `app.settings.updated` olayı üretmez.

---

## Vault (Sırlar)

Üçüncü taraf API anahtarları ve parolalar için. Değerler Tecof'ta şifreli tutulur ve yalnız uygulamanızın kurulum token'ıyla okunabilir.

| Metot | Uç | Yanıt |
| :--- | :--- | :--- |
| `GET` | `/api/v1/app/secrets` | `[{ key, updatedAt, lastReadAt, length }]` — **değer yok** |
| `GET` | `/api/v1/app/secrets/:key` | `{ key, value, updatedAt }` |
| `PUT` | `/api/v1/app/secrets/:key` | Gövde `{ value }` → `{ key, updatedAt }` |
| `DELETE` | `/api/v1/app/secrets/:key` | Siler |

```ts
await api.secrets.set("isbasiPassword", passwordFromForm);
const { value: password } = await api.secrets.get("isbasiPassword"); // okuma lastReadAt'i damgalar
const list = await api.secrets.list();                     // yalnız anahtar adları ve meta
await api.secrets.delete("isbasiPassword");
```

**Kurallar**

| Kural | Değer |
| :--- | :--- |
| Anahtar biçimi | `^[a-zA-Z][a-zA-Z0-9_.-]{0,63}$` |
| Anahtar sayısı | En fazla 50 |
| Değer | UTF-8 metin, en fazla 8 KB |

### Şifreleme tasarımı

Vault, sızıntı durumunda bile şifreli metnin başka bir yerde kullanılamamasını hedefler:

| Katman | Tasarım |
| :--- | :--- |
| Algoritma | **AES-256-GCM** (kimlik doğrulamalı şifreleme; değiştirilmiş şifreli metin çözülemez) |
| Kurulum başına anahtar | Veri anahtarı her kurulum için ayrı türetilir: **HKDF-SHA256**(ana anahtar, salt = kurulum kimliği, info = `tecof-app-vault/v1`) |
| AAD bağlama | Ek doğrulanmış veri = `uygulama kimliği \| kurulum kimliği \| anahtar adı`. Şifreli metin başka bir kuruluma, başka bir uygulamaya ya da başka bir anahtar adına kopyalanırsa çözülmez |
| Anahtar sürümü | Her kayıt hangi ana anahtarla şifrelendiğini (`keyId`) saklar; Tecof ana anahtarları döndürürken kayıtları yeniden şifreler |
| İstemci sırrı | Uygulamanızın istemci sırrı (`tcfs_…`) da aynı ana anahtarlarla, kendi bağlamına bağlanarak saklanır |

**Garantiler**

- Değerler panel API'sine, istek günlüklerine, webhook yüklerine ve hata mesajlarına **hiçbir zaman** çıkmaz. Panel yalnız "ayarlı / ayarlı değil" bilgisini ve güncelleme zamanını görür.
- Okuma `lastReadAt` alanını damgalar; liste ucuyla hangi sırrın ne zaman okunduğunu izleyebilirsiniz.
- Uygulama kaldırıldığında kurulumun sırları **anında** silinir.

Kendi tarafınızda: sırrı yalnız ihtiyaç anında okuyun, günlüğe yazmayın, istemci (tarayıcı) koduna göndermeyin.

---

## Yerel Ayar Formu

`tecof.app.json` içine `settings` şeması eklerseniz panel, uygulama sayfasında bir **"Ayarlar"** sekmesi gösterir. Böylece ayar ekranı için arayüz yazmanız gerekmez; arka plan (headless) uygulamalar için de idealdir.

```json
{
  "settings": [
    { "key": "username", "label": { "tr": "Kullanıcı adı", "en": "Username" }, "type": "text", "required": true },
    { "key": "password", "label": { "tr": "Parola", "en": "Password" }, "type": "secret", "required": true },
    { "key": "autoInvoice", "label": { "tr": "Ödenen siparişleri otomatik faturala", "en": "Auto-invoice paid orders" }, "type": "boolean" },
    { "key": "invoiceMode", "label": { "tr": "Fatura tipi", "en": "Invoice mode" }, "type": "select",
      "help": { "tr": "Kesilmiş fatura doğrudan alıcıya gider", "en": "Issued invoices are sent to the buyer" },
      "options": [
        { "value": "draft", "label": { "tr": "Taslak", "en": "Draft" } },
        { "value": "issued", "label": { "tr": "Kesilmiş", "en": "Issued" } }
      ] },
    { "key": "note", "label": { "tr": "Fatura notu", "en": "Invoice note" }, "type": "textarea" }
  ]
}
```

| Alan | Açıklama |
| :--- | :--- |
| `key` | Ayar anahtarı |
| `label` | `{ tr, en }` |
| `type` | `text`, `number`, `boolean`, `select`, `textarea`, `secret` |
| `required` | İsteğe bağlı |
| `options` | `select` için zorunlu: `[{ value, label: { tr, en } }]` |
| `help` | İsteğe bağlı yardım metni, `{ tr, en }` |

En fazla 30 alan tanımlanabilir.

### Panel tarafı

| Metot | Uç | Davranış |
| :--- | :--- | :--- |
| `GET` | `/api/merchant/apps/installations/:id/settings` | `{ schema, values }`; `secret` alanlar değer yerine `{ set: boolean, updatedAt }` döner |
| `PUT` | `/api/merchant/apps/installations/:id/settings` | `{ values }`; sır olmayanlar ayar nesnesine **birleştirilerek** (formda olmayan anahtarlar korunur), `secret` olanlar Vault'a yazılır |

- `secret` alan için boş string = **değiştirme**; `null` = **sil**.
- Kayıttan sonra uygulamanıza `app.settings.updated` webhook'u gelir: `data = { keys: [...], secretKeys: [...] }`. Değer taşımaz. Olay yalnız bu panel kaydında üretilir.
- Uygulamanın kendi yazdığı anahtarlar (ör. `billing`) form kaydında silinmez; yalnız formdaki anahtarla aynı adı taşıyorsa üzerine yazılır.

### Uygulama tarafı

Formdaki sır olmayan değerler ayarlarda, `secret` değerler Vault'ta aynı `key` ile durur:

```ts
const api = tecof.client(installationId);
const { settings } = await api.settings.get();
const username = settings.username as string;
const { value: password } = await api.secrets.get("password");
```

`app.settings.updated` geldiğinde önbelleğinizdeki değerleri geçersiz kılın ya da bağlantıyı test edin (ör. üçüncü taraf API'ye giriş deneyip sonucu metafield veya ayarlarla bildirin).

---

## Metafield'lar

Metafield, bir kaynağa (sipariş, ürün, müşteri, mağaza) bağlı uygulama verisidir. Örneğin fatura uygulaması siparişe fatura numarasını, kargo uygulaması takip bağlantısını yazar. Metafield'lar panelde gösterilebilir ve başka uygulamalarla paylaşılabilir.

| Metot | Uç | Açıklama |
| :--- | :--- | :--- |
| `GET` | `/api/v1/metafields?ownerType=order&ownerId=…[&namespace=isbasi]` | Listeleme |
| `PUT` | `/api/v1/metafields` | Yazma (owner + namespace + key tekildir; aynı anahtar güncellenir) → `{ id, namespace, ownerType, ownerId, key, type, value, visibility, panel, own, updatedAt }` |
| `DELETE` | `/api/v1/metafields/:id` | Silme |

### Alanlar

| Alan | Değerler |
| :--- | :--- |
| `ownerType` | `order`, `product`, `customer`, `merchant` |
| `ownerId` | Kaynağın kimliği. `ownerType: "merchant"` için yok sayılır (kayıt kurulumun mağazasına bağlanır) |
| `namespace` | Uygulamanızın `slug`'ı — **sunucu atar**, gövdede gönderilmez |
| `key` | Anahtar; `owner + namespace + key` tekildir |
| `type` | `string`, `number`, `boolean`, `json`, `url` |
| `value` | En fazla 16 KB |
| `visibility` | `private` (yalnız uygulamanız) ya da `shared` (aynı mağazadaki diğer uygulamalar okuyabilir) |
| `panel` | `{ label: { tr, en }, show: true }` → panelde gösterilir |

### Kapsam

Okuma ve yazma, kaynağın okuma kapsamını ister:

| `ownerType` | Gerekli kapsam |
| :--- | :--- |
| `order` | `orders:read` |
| `product` | `products:read` |
| `customer` | `customers:read` |
| `merchant` | Kapsam gerekmez |

### Panelde gösterim

`panel.show: true` olan metafield'lar ilgili detay sayfasındaki **"Uygulamalar"** kartında `label` ile listelenir; `url` tipi tıklanabilir bağlantı olarak gösterilir. Panel bu kartı `GET /api/merchant/apps/metafields?ownerType=order&ownerId=…` ile doldurur.

```ts
await api.metafields.set({
  ownerType: "order",
  ownerId: orderId,
  key: "invoiceNumber",
  type: "string",
  value: "ABC2026000000123",
  visibility: "shared",
  panel: { label: { tr: "İşbaşı fatura no", en: "İşbaşı invoice no" }, show: true },
});

await api.metafields.set({
  ownerType: "order",
  ownerId: orderId,
  key: "invoiceUrl",
  type: "url",
  value: "https://ornek-fatura-portali.example/fatura/ABC2026000000123",
  visibility: "private",
  panel: { label: { tr: "Faturayı görüntüle", en: "View invoice" }, show: true },
});

const mine = await api.metafields.list({ ownerType: "order", ownerId: orderId, namespace: "isbasi" });
```

### Kaldırmada

Uygulama kaldırıldığında panelde görünen metafield'lar gizlenir; veri 30 gün sonra temizlik işinde silinir.

Paylaşılan metafield'ların uygulamalar arası kullanımı için bkz. [Uygulamalar Arası İletişim](https://tecof-app-dev.vercel.app/app-interop).

---

# Uygulamalar Arası İletişim

> Uygulamalar arası olaylar (pub/sub), paylaşılan metafield’lar ve keşif kataloğu.
>
> Kaynak: https://tecof-app-dev.vercel.app/app-interop · Bölüm: Uygulama geliştirme · Son güncelleme: 2018-10-20

Aynı mağazada kurulu uygulamalar birbirleriyle gevşek bağlı biçimde çalışabilir: bir uygulama olay yayınlar, diğeri abone olur; bir uygulama kaynağa veri yazar, diğeri okur. Mağazanın onayı kurulumla örtüktür: iki uygulama da mağazada kuruluysa ve olaylar yapılandırmada bildirildiyse iletişim kurulur.

| Yöntem | Ne zaman | Yön |
| :--- | :--- | :--- |
| Uygulama olayları (pub/sub) | "Bir şey oldu" bildirimi (fatura kesildi, gönderi oluşturuldu) | Yayıncı → aboneler (webhook) |
| Paylaşılan metafield'lar | Kaynağa bağlı kalıcı veri (fatura numarası, takip numarası) | Yazan → okuyan (API) |
| Keşif kataloğu | Mağazada hangi olayların yayınlandığını öğrenmek | API |

---

## Uygulama Olayları

### Adlandırma

Yayıncı olay adını kısa haliyle bildirir (`invoice.created`); Tecof bunu yayıncının slug'ıyla önekler:

```text
app.<yayıncı slug>.<olay adı>      ör. app.isbasi.invoice.created
```

Öneki sunucu ekler; bu sayede bir uygulama başka bir uygulamanın adına olay yayınlayamaz.

### Yayınlama

1. Olayı `tecof.app.json` içinde bildirin:

```json
{
  "appEvents": {
    "publishes": [
      { "name": "invoice.created", "description": { "tr": "Fatura oluşturuldu", "en": "Invoice created" } }
    ]
  }
}
```

2. Olayı yayınlayın:

```ts
await tecof.client(installationId).events.publish("invoice.created", {
  orderId: "6720bb00cc11dd22ee33ff44",
  orderNumber: "TCF-1001",
  invoiceNumber: "ABC2026000000123",
});
```

Ham HTTP: `POST /api/v1/app/events { name, data }`.

| Kural | Değer |
| :--- | :--- |
| `data` boyutu | En fazla 32 KB |
| Bildirilmemiş ad | `400 app-event-undeclared` |
| Kapsam | Gerekmez (uygulamanın kendi verisi) |

### Abone olma

Abone uygulama, dinlediği olayları `appEvents.subscribes` içinde tam adla ya da yayıncı jokeriyle bildirir:

```json
{
  "appEvents": {
    "subscribes": ["app.isbasi.invoice.created", "app.kargo.*"]
  }
}
```

Olay, **aynı mağazada kurulu** ve bu adı (ya da `app.<slug>.*` jokerini) listeleyen uygulamalara webhook olarak `appUrl + webhooks.path` adresine teslim edilir. Abone uygulamada `webhooks.path` tanımlı değilse uygulama olayları teslim edilemez. Teslimat biçimi, imza, yeniden deneme ve idempotency kuralları normal webhook'larla aynıdır ([Webhook'lar](https://tecof-app-dev.vercel.app/app-webhooks)); `data` alanı şu biçimdedir:

```json
{
  "id": "evt_91c0d2aa47",
  "event": "app.isbasi.invoice.created",
  "test": false,
  "timestamp": "2026-10-10T09:20:00.000Z",
  "merchantId": "66f0c0ffee0000000000abcd",
  "installationId": "6720aa00bb11cc22dd33ee77",
  "data": {
    "source": { "slug": "isbasi", "clientId": "tcfa_yyyyyyyyyyyyyyyy" },
    "payload": {
      "orderId": "6720bb00cc11dd22ee33ff44",
      "orderNumber": "TCF-1001",
      "invoiceNumber": "ABC2026000000123"
    }
  }
}
```

`installationId` burada **abone** uygulamanın kurulumudur. Yayıncıyı `data.source` ile tanırsınız.

### Keşif

Mağazada kurulu uygulamaların yayınladığı olayları listelemek için:

```ts
const catalog = await tecof.client(installationId).events.catalog();
```

```json
[
  {
    "slug": "isbasi",
    "appName": "Logo İşbaşı",
    "event": "app.isbasi.invoice.created",
    "description": { "tr": "Fatura oluşturuldu", "en": "Invoice created" }
  }
]
```

Ham HTTP: `GET /api/v1/app/events/catalog`. Liste, mağazada **aktif** kurulu platform uygulamalarının `appEvents.publishes` bildirimlerinden üretilir; `event` tam (önekli) addır. Panelinizde "şu uygulama kuruluysa şu entegrasyonu aç" gibi akışlar için kullanabilirsiniz.

---

## Paylaşılan Metafield'lar

`visibility: "shared"` ile yazılan metafield'ları aynı mağazadaki diğer uygulamalar okuyabilir. Okuyan uygulama, kaynağın okuma kapsamına sahip olmalıdır (sipariş için `orders:read`).

```ts
// Yazan: İşbaşı uygulaması
await api.metafields.set({
  ownerType: "order",
  ownerId: orderId,
  key: "invoiceNumber",
  type: "string",
  value: "ABC2026000000123",
  visibility: "shared",
});

// Okuyan: kargo uygulaması
const shared = await kargoApi.metafields.list({ ownerType: "order", ownerId: orderId, namespace: "isbasi" });
const invoiceNumber = shared.find((m: { key: string }) => m.key === "invoiceNumber")?.value;
```

Namespace yazan uygulamanın slug'ıdır; okurken `namespace` süzgeciyle hangi uygulamanın verisini istediğinizi belirtin. `private` metafield'lar başka uygulamalara dönmez.

---

## Örnek: Fatura → Kargo

Senaryo: İşbaşı uygulaması ödenen sipariş için fatura keser ve `invoice.created` yayınlar. Mağazada kurulu bir kargo uygulaması (`kargo`) bu olayı dinler, gönderiyi faturalı olarak oluşturur ve kendi olayı `shipment.created`'i yayınlar.

```mermaid
sequenceDiagram
    participant T as Tecof
    participant I as İşbaşı uygulaması (isbasi)
    participant K as Kargo uygulaması (kargo)

    T->>I: webhook order.paid
    I->>I: Faturayı kes
    I->>T: PUT /api/v1/metafields (invoiceNumber, shared)
    I->>T: POST /api/v1/app/events { name: "invoice.created" }
    T->>K: webhook app.isbasi.invoice.created
    K->>T: GET /api/v1/orders/:id
    K->>K: Gönderiyi oluştur
    K->>T: POST /api/v1/app/events { name: "shipment.created" }
    T->>I: webhook app.kargo.shipment.created
```

**İşbaşı yapılandırması**

```json
{
  "slug": "isbasi",
  "scopes": ["orders:read", "customers:read", "products:read"],
  "webhooks": { "path": "/api/webhooks", "events": ["order.paid"] },
  "appEvents": {
    "publishes": [{ "name": "invoice.created", "description": { "tr": "Fatura oluşturuldu", "en": "Invoice created" } }],
    "subscribes": ["app.kargo.shipment.created"]
  }
}
```

**Kargo uygulaması yapılandırması**

```json
{
  "slug": "kargo",
  "scopes": ["orders:read"],
  "webhooks": { "path": "/api/webhooks", "events": ["order.fulfilled"] },
  "appEvents": {
    "publishes": [{ "name": "shipment.created", "description": { "tr": "Gönderi oluşturuldu", "en": "Shipment created" } }],
    "subscribes": ["app.isbasi.invoice.created"]
  }
}
```

**Kargo uygulamasının işleyicisi**

```ts
// kargo: app/api/webhooks/route.ts
import { createWebhookHandler } from "@tecof/app-sdk";
import { tecof } from "@/lib/tecof";

type InvoiceCreated = {
  source: { slug: string; clientId: string };
  payload: { orderId: string; invoiceNumber: string };
};

export const POST = createWebhookHandler({
  app: tecof,
  handlers: {
    "app.isbasi.invoice.created": async (event) => {
      const { payload } = event.data as InvoiceCreated;
      const api = tecof.client(event.installationId);
      const order = await api.orders.get(payload.orderId);
      // … gönderiyi payload.invoiceNumber ile oluştur
      await api.events.publish("shipment.created", { orderId: order.id, trackingNumber: "TRK000000001" });
    },
  },
});
```

Notlar:

- Yayıncı kurulu değilse olay gelmez; abone uygulama bu entegrasyonu isteğe bağlı bir özellik olarak tasarlamalıdır. Keşif kataloğuyla yayıncının varlığını kontrol edebilirsiniz.
- Olay yükü yalnız bildirimdir; kaydın güncel hâlini API'den okuyun.
- Aynı olay birden fazla gelebilir; `X-Tecof-Event-Id` ile idempotent olun.

---

## Yol Haritası

Aşağıdakiler **gelecek** genişletme noktalarıdır ve henüz mevcut değildir:

- Uygulamalar arası doğrudan istek (capability): bir uygulamanın başka bir uygulamanın sunduğu işlevi doğrudan çağırması.
- Vitrin (tema) uzantıları: uygulamaların mağaza vitrinine bileşen eklemesi.

---

# Ücretlendirme ve Hak Ediş

> Uygulama planları, KDV, abonelik durumları, %80 geliştirici payı ve partner ödemesi.
>
> Kaynak: https://tecof-app-dev.vercel.app/app-billing · Bölüm: Uygulama geliştirme · Son güncelleme: 2018-10-20

Uygulamanız aylık ya da yıllık planlar satabilir. Tahsilatı Tecof yapar (iyzico); KDV hariç tutarın varsayılan **%80**'i iade penceresi dolduktan sonra partner defterinize yazılır ve partner programının aylık ödeme akışıyla size ödenir. Planı olmayan uygulama ücretsizdir.

---

## Planlar

Planlar `tecof.app.json` içindeki `plans` dizisinde tanımlanır (en fazla 4):

```json
{
  "plans": [
    {
      "key": "standart",
      "name": { "tr": "Standart", "en": "Standard" },
      "description": { "tr": "Küçük mağazalar için", "en": "For small stores" },
      "price": 199,
      "currency": "TRY",
      "interval": "month",
      "trialDays": 14,
      "features": [
        { "tr": "Sınırsız fatura", "en": "Unlimited invoices" },
        { "tr": "Toplu faturalama", "en": "Bulk invoicing" }
      ]
    },
    {
      "key": "yillik",
      "name": { "tr": "Yıllık", "en": "Yearly" },
      "description": { "tr": "İki ay hediye", "en": "Two months free" },
      "price": 1990,
      "currency": "TRY",
      "interval": "year",
      "trialDays": 0,
      "features": [{ "tr": "Standart planın tüm özellikleri", "en": "Everything in Standard" }]
    }
  ]
}
```

| Alan | Kural |
| :--- | :--- |
| `key` | Plan anahtarı (uygulama içinde tekil) |
| `name`, `description` | `{ tr, en }` |
| `price` | **KDV hariç**, sıfırdan büyük |
| `currency` | `TRY`, `USD`, `EUR` |
| `interval` | `month` ya da `year` |
| `trialDays` | 0–30 |
| `features` | `{ tr, en }` listesi; plan kartında gösterilir |

Onaylanmış uygulamada plan değişiklikleri canlıya hemen yansır. Ücretli plan içeren `public` bir uygulamayı incelemeye göndermek için partner doğrulamanız (KYC + IBAN) onaylı olmalıdır. `private` dağıtım incelemeye girmediği için yayında KYC istenmez; ancak hak ediş **ödemesi** her durumda onaylı KYC ve IBAN ister. Bkz. [Yayınlama ve İnceleme](https://tecof-app-dev.vercel.app/app-publishing).

### KDV

Mağazanın ödeyeceği tutar:

```text
ödenecek = price × (1 + KDV oranı)
```

| Para birimi | KDV oranı |
| :--- | :--- |
| `TRY` | Tecof fatura ayarlarındaki KDV oranı (bugün %20) |
| `USD`, `EUR` | Tecof fatura ayarlarındaki ihracat KDV oranı (varsayılan %0) |

Fiyatı her zaman KDV hariç girin; katalog ve ödeme ekranı KDV'yi ekleyerek gösterir.

---

## Mağaza Satın Alma Akışı

```mermaid
sequenceDiagram
    participant M as Mağaza (panel)
    participant T as Tecof
    participant I as iyzico
    participant A as Uygulamanız

    M->>T: Kurulum: POST /api/merchant/apps/install { appId, acceptedScopes, planKey }
    alt Ücretsiz plan ya da deneme süresi var
        T-->>M: next.type = "open"
        T->>A: app.installed (+ deneme varsa app.subscription.updated: trialing)
    else Ücretli, denemesiz plan
        T-->>M: next.type = "checkout" (billing.status = pending)
        M->>T: POST /installations/:id/billing/checkout { planKey, customer }
        T-->>M: iyzico ödeme formu
        M->>I: Kart bilgisi
        I->>T: Dönüş (callback) → iyzico'dan geri sorgu
        T->>T: Dönem açılır / uzatılır
        T->>A: app.subscription.updated (active)
        T-->>M: /app/apps/my-apps/<kurulum>?billing=success
    end
```

- Ödeme iyzico'nun tek seferlik ödeme formuyla alınır; her ödeme bir dönem (ay ya da yıl) açar ya da uzatır.
- Ödeme dönüşü (callback) kaçırılırsa bir mutabakat işi `pending` kalan ödemeleri iyzico'dan sorgulayıp tamamlar.
- Panel dönüşte `billing=success`, `billing=error` ya da `billing=processing` gösterir.
- Mağaza plan seçim ekranını panelden açabilir; uygulamanızın arayüzünden açmak için App Bridge `openBilling()` kullanın.

Mağazanın gördüğü uçlar (bilgi için): `GET /api/merchant/apps/installations/:id/billing` → `{ plans, subscription, charges }`, `POST /api/merchant/apps/installations/:id/billing/checkout`.

---

## Abonelik Durumları

| Durum | Anlamı |
| :--- | :--- |
| `trialing` | Deneme süresinde |
| `active` | Ödenmiş dönem sürüyor |
| `past_due` | Dönem bitti, yenileme ödemesi bekleniyor (3 günlük tolerans) |
| `expired` | Tolerans doldu, ödeme yapılmadı |
| `cancelled` | Uygulama kaldırıldı |

```mermaid
stateDiagram-v2
    [*] --> trialing: Kurulum (denemeli plan)
    [*] --> active: Ödeme
    trialing --> active: Ödeme
    trialing --> past_due: Deneme bitti, ödeme yok
    active --> active: Yenileme ödemesi (dönem uzar)
    active --> past_due: Dönem sonu
    past_due --> active: Ödeme
    past_due --> expired: 3 gün tolerans doldu
    expired --> active: Ödeme
    trialing --> cancelled: Kaldırma
    active --> cancelled: Kaldırma
    past_due --> cancelled: Kaldırma
    expired --> cancelled: Kaldırma
```

### v1 yaşam döngüsü kuralları

- **Otomatik yenileme yoktur (v1).** Dönem sonundan 7 gün önce (varsayılan) mağazaya hatırlatma gider; mağaza yenilemeyi elle öder.
- Dönem bitince abonelik `past_due` olur; 3 günlük (varsayılan) tolerans sonunda `expired`'a geçer.
- **Deneme süresi** ödeme yapılmadan biterse de aynı yol izlenir: `trialing` → `past_due` (3 gün) → `expired`.
- Bir mağaza aynı uygulamanın deneme süresini **yalnız bir kez** kullanabilir; kaldırıp yeniden kurmak ikinci deneme açmaz.
- Uygulama kaldırılınca abonelik `cancelled` olur; **otomatik iade yapılmaz**.
- Her durum geçişi uygulamanıza `app.subscription.updated` webhook'u gönderir:

```json
{
  "event": "app.subscription.updated",
  "data": {
    "planKey": "standart",
    "status": "active",
    "trialEndsAt": null,
    "currentPeriodEnd": "2026-11-10T09:16:10.000Z",
    "chargeId": "6720dd00ee11ff22aa33bb66"
  }
}
```

Otomatik yenilenen abonelik (iyzico abonelik API'si) **v2**'de planlanmıştır.

---

## Özellikleri Plana Göre Açmak

Erişimi kısıtlamak **uygulamanın kararıdır**; Tecof süresi dolan abonelikte panelde yalnız bir uyarı bandı gösterir. Plan durumunu şu yerlerden öğrenirsiniz:

| Yer | Kullanım |
| :--- | :--- |
| App Bridge bağlamı | `context.installation.plan` = `{ key, status }` ya da `null` — arayüzde göstermek/gizlemek için |
| `app.subscription.updated` webhook'u | Sunucu tarafında durumu saklamak için |
| `api.installation()` | Sunucu tarafında anlık durum (`subscription`) |

**Sunucu tarafı örnek** — webhook ile gelen durumu ayarlarda tutup her işte kontrol etmek:

```ts
// lib/billing.ts
import { tecof } from "@/lib/tecof";

type PlanState = { planKey: string | null; status: string; currentPeriodEnd: string | null };

const ALLOWED = new Set(["trialing", "active", "past_due"]); // past_due: 3 günlük toleransta çalışmayı sürdür

export async function savePlanState(installationId: string, data: PlanState) {
  await tecof.client(installationId).settings.set({ billing: data }, { merge: true });
}

export async function hasPaidAccess(installationId: string): Promise<boolean> {
  const { settings } = await tecof.client(installationId).settings.get();
  const billing = settings.billing as PlanState | undefined;
  return !!billing && ALLOWED.has(billing.status);
}
```

```ts
// app/api/webhooks/route.ts — createWebhookHandler({ app: tecof, handlers: { … } }) içinde
"app.subscription.updated": async (event) => {
  await savePlanState(event.installationId, event.data as PlanState);
},
```

Anlık durumu webhook'a bağlı kalmadan da okuyabilirsiniz: `api.installation()` yanıtındaki `subscription` alanı (plan yoksa `null`). Bkz. [API ile Veri Erişimi](https://tecof-app-dev.vercel.app/app-api).

**Arayüz tarafı örnek:**

```tsx
"use client";

import { useAppBridge, useAppContext } from "@tecof/app-bridge/react";

export function PaidFeature({ children }: { children: React.ReactNode }) {
  const bridge = useAppBridge();
  const { installation } = useAppContext();
  const status = installation.plan?.status;

  if (status === "trialing" || status === "active" || status === "past_due") return <>{children}</>;

  return (
    <div>
      <p>Bu özellik ücretli planda kullanılabilir.</p>
      <button onClick={() => bridge.openBilling()}>Planları gör</button>
    </div>
  );
}
```

`billing` anahtarını yerel ayar formunuzdaki (`settings` şeması) anahtarlardan farklı seçin. `past_due` durumunda çalışmayı sürdürüp sürdürmemek ve deneme süresinde hangi özelliklerin açık olacağı sizin ürün kararınızdır.

---

## Geliştirici Hak Edişi

| Kural | Değer |
| :--- | :--- |
| Platform komisyonu | Varsayılan **%20** → geliştirici payı **%80** |
| Hesap tabanı | Tahsilatın **KDV hariç** tutarı |
| İade penceresi | Varsayılan **14 gün** |
| Defter satırı | Ödemeden 14 gün sonra, iade edilmemişse partner defterine `kind: "accrual"`, `sourceType: "app-charge"` satırı yazılır |
| Dönem | Satırın dönemi, **ödenebilir tarihin** (ödeme + 14 gün) ayıdır (İstanbul saati) |
| Pencere içi kısmi iade | İade edilen tutar tahakkuktan düşülür; satır kalan tutar üzerinden yazılır |
| Pencere sonrası iade | Partner defterine geri kesinti (`kind: "clawback"`, `sourceType: "app-refund"`) yazılır |
| Test mağazası satın alımı | Geliştiricinin kendi test mağazalarından yapılan satın alma gerçek satış sayılmaz: satır `held` (`app-test-store`) yazılır; Tecof yöneticisi serbest bırakabilir |

Bundan sonrası partner programının mevcut ödeme akışıdır:

1. **Aylık kapanış.** Dönemi önceki ay ya da daha eski olan, ödemeye girmemiş satırlar partner × para birimi bazında toplanır.
2. **Ödeme açılma koşulları.** Partner aktif, partner doğrulaması (KYC) onaylı, partner sözleşmesi onaylanmış ve toplam asgari tutarın üstünde olmalı. Aksi hâlde satırlar sonraki aya devreder.

   | Para birimi | Asgari ödeme |
   | :--- | :--- |
   | TRY | 1.000 TL |
   | EUR | 50 € |
   | USD | 50 $ |

3. **Partner faturası.** Şahıs ve kurumsal partner, ödeme tutarı için KDV eklenmiş fatura yükler (Türkiye'de %20; yurt dışı partnerde 0). Bireysel partnerde fatura adımı yoktur.
4. **Onay ve ödeme.** Tecof yöneticisi faturayı onaylar (doğrulama ve IBAN şarttır) ve ödemeyi kaydeder. Fatura reddedilirse yeniden yüklenir.

Tahsilatları geliştirici API'sinden izleyebilirsiniz: `GET /api/developer/apps/:id/charges`.

### Sayısal örnek

Plan: **Standart**, 199 TL/ay (KDV hariç), Türkiye'deki kurumsal bir partner.

| Adım | Hesap | Tutar |
| :--- | :--- | :--- |
| Mağazanın ödediği | 199 × 1,20 | **238,80 TL** |
| KDV hariç taban | — | 199,00 TL |
| Platform komisyonu (%20) | 199 × 0,20 | 39,80 TL |
| Geliştirici payı (%80) | 199 × 0,80 | **159,20 TL** |

Zaman çizelgesi (ödeme 20 Ekim 2026):

| Tarih | Olay |
| :--- | :--- |
| 20.10.2026 | Mağaza öder; abonelik `active`, `app.subscription.updated` |
| 03.11.2026 | 14 günlük iade penceresi doldu; defterde 159,20 TL `accrual`, dönem **2026-11** |
| Aralık 2026 başı | Kasım dönemi kapanışa girer |

Aynı ay 7 mağazadan bu planla tahsilat yapıldığını varsayalım: 7 × 159,20 = **1.114,40 TL** ≥ 1.000 TL asgari tutar → ödeme açılır. Kurumsal partner 1.114,40 TL + %20 KDV = **1.337,28 TL** tutarında fatura yükler; yönetici onayından sonra ödeme yapılır. Toplam 1.000 TL'nin altında kalsaydı satırlar bir sonraki kapanışa devrederdi.

Mağaza 14 gün içinde tam iade alırsa defter satırı hiç yazılmaz; kısmi iadede tahakkuk iade oranında azalır: örneğin 238,80 TL'lik ödemenin 118,80 TL'si (KDV dahil) pencere içinde iade edilirse kalan KDV hariç tutar 199 × 120 / 238,80 = 100,00 TL, defter satırı 100,00 × 0,80 = **80,00 TL** olur. Pencereden sonra tam iade yapılırsa iade dönemine −159,20 TL'lik `clawback` satırı düşer. İadeleri (tam ya da kısmi) Tecof yöneticisi yapar.

---

## Açık Konular

- Uygulama tahsilatının mağazaya Tecof tarafından faturalanması (e-Arşiv) henüz netleşmedi.
- Otomatik yenileme v2'ye bırakıldı.
- Birinci parti (partnersiz) uygulamalarda hak ediş satırı yazılmaz.

---

# Yayınlama ve İnceleme

> İnceleme durumları, public/private dağıtım, kurulabilirlik kuralları, gönderim kontrol listesi, mağaza görselleri (ikon, kapak, ekran görüntüleri, store-assets/ ve listing.media), askıya alma ve izleme.
>
> Kaynak: https://tecof-app-dev.vercel.app/app-publishing · Bölüm: Uygulama geliştirme · Son güncelleme: 2018-10-20

Bir uygulama test mağazalarında geliştirildikten sonra incelemeye gönderilir ve onaylanınca dağıtım türüne göre katalogda listelenir ya da doğrudan bağlantıyla kurulur. Bu sayfa inceleme durumlarını, dağıtım seçeneklerini, kurulabilirlik kurallarını, gönderim öncesi kontrol listesini ve mağaza görsellerini anlatır.

---

## İnceleme Durumları

| Durum | Anlamı |
| :--- | :--- |
| `draft` | Geliştiriliyor; yalnız `testStores` mağazalarına kurulabilir |
| `in-review` | Tecof incelemesinde |
| `approved` | Onaylandı; dağıtım türüne göre yayında |
| `rejected` | Reddedildi; inceleme notuna göre düzeltip yeniden gönderin |

```mermaid
stateDiagram-v2
    [*] --> draft
    draft --> in_review: POST /developer/apps/:id/submit
    in_review --> approved: Onay
    in_review --> rejected: Ret (not ile)
    rejected --> in_review: Düzeltip yeniden gönderim
    approved --> in_review: Kapsam artışı (mevcut sürüm yayında kalır)
```

İncelemeye gönderim: `POST /api/developer/apps/:id/submit` (kapı maddeleri aşağıda). Tecof yöneticisi onaylar ya da reddeder; ret her zaman bir not içerir. Onaylı uygulamadaki kapsam artışları da aynı inceleme kuyruğuna düşer.

### Onay sonrası değişiklikler

| Değişiklik | Etki |
| :--- | :--- |
| `listing` (açıklama, bağlantılar, kategori) | Canlıya **hemen** yansır |
| `plans` | Canlıya **hemen** yansır |
| Kapsam artışı | **Yeniden inceleme** ister (`in-review`); inceleme sürerken mevcut sürüm yayında kalır. Kurulumlara `pendingScopes` yazılır, mağaza onaylayana kadar eski kapsamla çalışırlar |
| Kapsam azalması | Anında uygulanır |

---

## Dağıtım Türleri

`POST /api/developer/apps/:id/distribution { distribution }` ile seçilir.

| Dağıtım | Katalogda | Kurulum | İnceleme |
| :--- | :--- | :--- | :--- |
| `public` | `approved` olunca görünür | Katalogdan ya da bağlantıyla | Gerekir |
| `private` | Görünmez | Yalnız doğrudan kurulum bağlantısıyla | Gerekmez; partner aktif olmalı. Ücretli planlı olsa da yayında KYC istenmez (hak ediş ödemesi yine KYC/IBAN ister) |

Kurulum bağlantısı:

```text
https://app.tecof.com/app/apps/install/tcfa_xxxxxxxxxxxxxxxx
```

`private` dağıtım, tek bir müşteriye ya da ajans müşterilerinize özel uygulamalar için uygundur.

---

## Kurulabilirlik Kuralları

Bir mağaza uygulamayı ancak şu koşullarda kurabilir:

1. Uygulama platform sözleşmesiyle yazılmış ve durumu aktif.
2. Ve şunlardan biri:
   - `approved` + `public`
   - `private` dağıtım
   - Mağaza, uygulamanın `testStores` listesinde
3. Partner ve uygulama askıda değil.

Aynı mağazaya ikinci kurulum `409 store-app-already-installed` döner. Panel kurulumdan önce `GET /api/merchant/apps/install-preview/:ref` (`ref` = uygulama kimliği, istemci kimliği ya da slug) ile ad, ikon, geliştirici, istenen kapsamlar, planlar ve kurulabilirliği (`installable`, `reason`) gösterir.

Kurulum isteğinde mağazanın onayladığı kapsamlar istenen kümeye **birebir eşit** olmalıdır (`409 app-scopes-mismatch`); onay ekranı atlanarak kurulum yapılamaz.

---

## Test Mağazaları

- `testStores` yalnız **ekip üyesi olduğunuz** mağazaları kabul eder (`GET /api/developer/test-stores`).
- Onaysız (`draft`, `in-review`, `rejected`) uygulama yalnız bu mağazalara kurulur.
- `tecof app dev` ile kaydedilen `devUrl` yalnız test mağazalarında `appUrl`'in yerine geçer (8 saat geçerli).

---

## Gönderim Öncesi Kontrol Listesi

**Ön koşullar:** Geliştirici API'sini kullanabilmek için partner hesabınız ve üyeliğiniz `active` olmalıdır; `tecof.app.json` sunucu doğrulamasından geçmeyen yapılandırma zaten kaydedilmez (`invalid-app-config`).

### Gönderim kapısı

`POST /api/developer/apps/:id/submit` aşağıdaki maddelerden biri eksikse gönderimi reddeder:

| Madde | Not |
| :--- | :--- |
| İkon yüklendi | `POST /api/developer/apps/:id/media/icon` (512×512, bkz. [Mağaza Görselleri](#magaza-gorselleri)) |
| `listing.shortDescription` Türkçe metni dolu | |
| `listing.description` Türkçe metni dolu | |
| `listing.supportEmail` dolu | |
| `listing.privacyUrl` dolu | |
| `appUrl` `https` | `hosting: "tecof"` için dağıtım `ready` olunca otomatik yazılır |
| En az bir yüzey | Gömülü arayüz (`embedded: true`), webhook aboneliği ya da aksiyon |
| Ücretli plan varsa partner doğrulaması (KYC + IBAN) onaylı | Değilse `app-verification-required` |

### İnceleme hazırlığı

Sistem tarafından zorunlu tutulmaz; incelemenin hızlı ve olumlu sonuçlanması için hazırlayın:

| Madde |
| :--- |
| Ekran görüntüleri yüklendi (`POST /api/developer/apps/:id/media/screenshot`; 1280×800, en fazla 8) |
| `listing.shortDescription` ve `listing.description` İngilizce metinleri de dolu |
| `listing.category` doğru seçildi; `listing.supportUrl` ve `listing.websiteUrl` çalışıyor |
| `listing.privacyUrl` uygulamanın işlediği kişisel veriyi (sipariş, müşteri) açıklıyor |
| Yalnız gereken kapsamlar isteniyor |
| Webhook ve API aksiyonu istekleri imza + zaman damgasıyla doğrulanıyor; işleyiciler idempotent |
| `app.uninstalled` işleniyor; kaldırmada kendi tarafınızdaki veri temizleniyor |
| Sırlar Vault'ta; istemci sırrı tarayıcı koduna girmiyor |
| Aksiyonlar tüm yerleşimlerde test edildi; hata mesajları anlaşılır |
| Ücretli planda özellik kısıtlaması `app.subscription.updated` ile doğru çalışıyor |
| Gömülü arayüz panelin açık/koyu temasına ve diline (`context.theme`, `context.locale`) uyuyor |

---

## Mağaza Görselleri

Uygulama mağazası her uygulama için bir ikon, bir kapak ve ekran görüntüleri gösterir. Bu dosyaları uygulamanın reposunda `store-assets/` klasöründe tutun:

```text
tecof-app-ornek/
├── tecof.app.json
└── store-assets/
    ├── icon.png                  # 512×512
    ├── cover.png                 # 1600×900, logosuz
    └── screenshots/
        ├── 01-genel-bakis.png    # 1280×800
        ├── 02-siparisler.png
        └── 03-ayarlar.png
```

| Görsel | Varsayılan yol | Ölçü | Görüldüğü yer |
| :--- | :--- | :--- | :--- |
| İkon | `store-assets/icon.png` | 512×512, kare | Mağaza kartı, öne çıkanlar, detay sayfası, kurulum ekranı |
| Kapak | `store-assets/cover.png` | 1600×900 (16:9) | Mağaza kartı, öne çıkanlar şeridi, detay sayfası |
| Ekran görüntüleri | `store-assets/screenshots/` içindeki görseller, ad sırasıyla | 1280×800 (16:10), en fazla 8 | Detay sayfasındaki galeri |

PNG önerilir; JPEG ve WebP de kabul edilir (varsayılan adlarda `icon.webp`, `cover.jpg` gibi). Dosyaları 2 MB'ın altında tutun; partner yükleme uçları dosya başına 2 MB kabul eder.

### Görsel kuralları

- **Kapak logosuz olmalı.** Panel uygulamanın ikonunu ve adını kapağın üstüne kendisi yerleştirir. Kapağa logo, ürün adı ya da başka metin koymayın.
- **Kapağın önemli kısmı ortadaki yatay bantta kalsın.** Kapak mağaza kartında 16:9 görünür. Geniş ekranda öne çıkanlar şeridi 16:7 oranındadır ve kapağın sol kenarı metin paneline doğru silikleşir. Detay sayfası geniş ekranda kapağı 21:9'a kırpar ve alt kenarını sayfa zeminine doğru soldurur.
- **İkon kare ve opak zeminli olmalı.** Köşe yuvarlatmasını ve çerçeveyi panel uygular; kendi yuvarlatmanızı ya da gölgenizi eklemeyin. Saydam ikon açık temada beyaz, koyu temada koyu gri zemin üzerinde görünür. Logoyu kenarlara dayamayın.
- **Ekran görüntüleri uygulamanın gerçek ekranlarından alınmalı.** Galeri 16:10 bir kutuda görseli kırpmadan gösterir. Ekranlarda kurgusal veri kullanın; gerçek müşteri, mağaza, hesap ya da anahtar görünmesin. Dosyalar ada göre sıralandığı için adları `01-`, `02-` diye numaralandırın.
- Logo ya da ekran görüntüsünde başka bir markaya ait öğe varsa kaynağını ve kullanım iznini `store-assets/SOURCES.md` dosyasına not edin.

Ölçüleri ve dosya boyutlarını yükleme öncesinde kontrol edebilirsiniz:

```bash
file store-assets/icon.png store-assets/cover.png store-assets/screenshots/*.png   # ölçüler
du -h store-assets/*.png store-assets/screenshots/*.png                           # dosya başına ≤ 2 MB
```

### listing.media ile farklı yollar

Görseller başka bir klasördeyse ya da ekran görüntülerinin sırasını açıkça belirlemek istiyorsanız `tecof.app.json` içinde `listing.media` alanını kullanın:

```json
{
  "listing": {
    "media": {
      "icon": "store-assets/icon.png",
      "cover": "store-assets/cover.png",
      "screenshots": [
        "store-assets/screenshots/01-genel-bakis.png",
        "store-assets/screenshots/02-siparisler.png"
      ]
    }
  }
}
```

| Kural | Değer |
| :--- | :--- |
| Yol | Repo köküne göre; ayırıcı `/`. `/` ile başlayamaz; `.` ya da `..` bölümü (`./`, `a/../b`), boş bölüm (`a//b`) ve `\` içeremez; en fazla 200 karakter |
| Uzantı | `png`, `jpg`, `jpeg`, `webp` |
| `screenshots` | En fazla 8 yol, her biri bir kez; görseller yazıldığı sırayla alınır |

`listing.media` yalnız birinci parti uygulamaların [eşitlemesinde](#birinci-parti-uygulamalarda-esitleme) kullanılır; partner uygulamasında yalnız doğrulanır.

**Hangi yol kullanılır?** Eşitleme her görselin yolunu şu sırayla belirler:

1. Repodaki `tecof.app.json` dosyasında `listing.media` varsa yalnız o okunur.
2. Yoksa (dosya ya da alan yoksa, dosya okunamıyorsa) Tecof'ta saklı yapılandırmadaki `listing.media` geçerlidir. Bu yapılandırma uygulama repodan oluşturulurken alınır. Eşitleme onu güncellemez; yalnız yönetici panelindeki `tecof.app.json` düzenleyicisiyle (`PUT /api/apps/admin/apps/:id/config`) değişir.
3. Seçilen `listing.media`'da yazılmayan görsel `store-assets/` varsayılanına düşer. Kurala uymayan `icon` ya da `cover` yazılmamış sayılır. `screenshots` listesinde kurala uymayan yol atlanır; listede geçerli yol kalmazsa varsayılan klasör kullanılır.

Yazdığınız ama repoda olmayan yol varsayılana düşmez; eşitleme raporunda `missing` olarak görünür. `listing.media`'yı repodan silmek de varsayılanlara döndürmez; saklı yapılandırmada `listing.media` varsa o kullanılmaya devam eder. Varsayılanlara dönmek için alanı yönetici panelindeki `tecof.app.json` düzenleyicisinden de silin.

**Kurala uymayan yolun sonucu** yapılandırmanın nereden geldiğine bağlıdır:

| Nerede | Sonuç |
| :--- | :--- |
| `tecof app config push`, `tecof app deploy`, geliştirici portalı, yönetici panelindeki `tecof.app.json` düzenleyicisi | Yapılandırma reddedilir (`invalid-app-config`) |
| Birinci parti uygulamanın repodan oluşturulması | Yol atılır ve yanıtın `warnings` listesinde `source: "tecof.app.json"` ile görünür; yapılandırmanın geri kalanı alınır |
| Eşitleme | Yol yok sayılır (yukarıdaki 3. madde). Eşitleme sonucunun `errors` listesinde `config` hatası görünür ve durum `partial` olur (hiçbir görsel alınamazsa `error`) |

### Birinci parti uygulamalarda eşitleme

Tecof'un GitHub org'undaki (`tecof/tecof-app-<ad>`) birinci parti uygulamaların görselleri elle yüklenmez. Tecof dosyaları reponun varsayılan dalından (`main`) okuyup mağaza kaydına yükler; repoda değişmeyen dosyayı yeniden yüklemez:

| Ne zaman | Ne olur |
| :--- | :--- |
| Uygulama yönetici panelinde repodan oluşturulurken ya da var olan uygulama bir repoya bağlanırken | İlk görseller kayıtla birlikte gelir |
| Yönetici uygulama sayfasında **Repodan çek** dediğinde | Görseller repodan yeniden okunur |
| Her başarılı üretim dağıtımından sonra | Repodaki görsel değişikliği, dağıtım canlıya çıkınca mağazaya yansır |

> [!IMPORTANT]
> Yönetici panelinden elle yüklenen ikon, kapak ya da ekran görüntüleri eşitlemede korunur. Repodaki görsel bunların yerine yalnız yöneticinin **Zorla güncelle** seçeneğiyle (`force`) geçer. Elle yüklenmiş bir görsel, zorla güncellenene kadar repodaki değişikliğin mağazaya yansımasını engeller; kalıcı değişikliği repoda yapın.

Partner uygulamalarında otomatik eşitleme yoktur. İkon ve ekran görüntülerini geliştirici portalından ya da `POST /api/developer/apps/:id/media/icon` ve `…/media/screenshot` uçlarıyla yükleyin. Bu uçlar kapak kabul etmez; kapak yönetici panelinden eklenir. Aynı ölçü ve kurallar partner uygulamaları için de geçerlidir.

---

## Kod Sürümleri

Tecof barındırmalı bir uygulamanın kodunu yayınlamak incelemeden bağımsızdır: `tecof app push` staged bir sürüm açar, `tecof app promote vN` onu yeniden derlemeden canlıya alır, `tecof app rollback` önceki canlı sürüme anında döner. `tecof app push` `tecof.app.json` dosyasını göndermez; kapsam, liste ve plan değişiklikleri `tecof app config push` (ya da önce yapılandırmayı gönderen `tecof app deploy`) ile gider ve yukarıdaki inceleme kurallarına tabidir. `tecof app deploy` tüm kaynağı yükleyip doğrudan yayınlamaya devam eder.

| Komut | İş |
| :--- | :--- |
| `tecof app push [-m <mesaj>] [--prod]` | Yalnız değişen dosyaları yükler, numaralı sürüm açar (varsayılan staged) |
| `tecof app versions [vN]` | Sürümler ve durumları |
| `tecof app promote vN` | Sürümü canlıya alır |
| `tecof app rollback [vN]` | Daha önce canlıda olmuş bir sürüme döner |

Geliştirici portalında uygulamanın **Sürümler** sekmesi aynı sürümleri gösterir. Ayrıntılar: [Sürümler, Canlıya Alma ve Geri Alma](https://tecof-app-dev.vercel.app/versions-and-rollback).

---

## Askıya Alma

Tecof yöneticisi bir uygulamayı gerekçesiyle askıya alabilir (`status: "suspended"`):

- Uygulama katalogdan kalkar.
- Yeni kurulum yapılamaz.
- Kurulum token'ı **basılmaz**: uygulama Tecof API'sine erişemez; `/api/v1` çağrıları `401 app-suspended` döner.

Askının kaldırılması yönetici kararıdır. Partner hesabının askıya alınması da uygulamalarının kurulmasını engeller.

---

## İzleme

| Uç | Ne gösterir |
| :--- | :--- |
| `GET /api/developer/apps/:id/installs` | Kurulumlar |
| `GET /api/developer/apps/:id/charges` | Plan tahsilatları |
| `GET /api/developer/apps/:id/deliveries` | Webhook teslimatları |
| `GET /api/developer/apps/:id/action-runs` | Aksiyon çalıştırmaları |
| `GET /api/developer/apps/:id/deployments` | Dağıtımlar ve durumları (`tecof app deploy`) |
| `GET /api/developer/spaces/app_:id/versions` | Sürümler ve canlı sürüm (`tecof app push` ve diğer yayınlar) |

Geliştirici uçları `Authorization: Bearer tcfd_…` (CLI token'ı) ya da panel oturumu kabul eder. Kapsamlı CI token'ları `/api/developer/apps…` uçlarını kullanamaz (`403 scoped-token-forbidden`); uygulama sürümlerini alan (`/api/developer/spaces…`) uçlarıyla yönetir ([Güvenlik ve CI](https://tecof-app-dev.vercel.app/dev-security)).

---

# Fatura Uygulamaları

> Tecof’un fatura uygulamaları, kurumsal/bireysel alıcı, ortak invoice metafield’ı, para kuralları ve @tecof/invoice-kit.
>
> Kaynak: https://tecof-app-dev.vercel.app/app-invoicing · Bölüm: Uygulama geliştirme · Son güncelleme: 2018-10-20

Tecof'ta fatura kesen her uygulama aynı sipariş verisini okur, aynı para kurallarını uygular ve faturanın durumunu siparişe aynı biçimde yazar. Böylece mağaza hangi entegratörü seçerse seçsin fatura tutarı aynı çıkar; kargo, muhasebe ya da raporlama uygulamaları da faturanın kesilip kesilmediğini sağlayıcıyı bilmeden öğrenir.

Bu sayfa üç şeyi anlatır: Tecof'un kendi fatura uygulamaları, fatura yazan bir uygulamanın uyması gereken ortak kurallar ve bu kuralları hazır veren `@tecof/invoice-kit` paketi.

---

## Tecof'un Fatura Uygulamaları

Hepsi platform uygulamasıdır (`integration: "platform"`): kimlik bilgileri [Vault](https://tecof-app-dev.vercel.app/app-data)'ta şifreli durur, siparişler [webhook](https://tecof-app-dev.vercel.app/app-webhooks) ile gelir, sipariş ekranlarında [aksiyon](https://tecof-app-dev.vercel.app/app-actions) sunar. Her birinin deposunda kurulum, ayarlar ve sınırları anlatan kendi README'si bulunur.

| Uygulama | Slug | Belge | Modlar | Fatura numarası | Sipariş iptal/iade edilince |
| :--- | :--- | :--- | :--- | :--- | :--- |
| Logo İşbaşı | `isbasi` | İşbaşı satış faturası | kapalı · taslak · kes | İşbaşı | İşaretle ya da **yalnız taslağı** sil |
| GİB e-Arşiv Portalı | `earsiv` | e-Arşiv (portal) | kapalı · taslak (imza portalda) | GİB | İşaretle ya da **imzasız** taslağı sil |
| Paraşüt | `parasut` | Satış faturası, isteğe bağlı e-Arşiv / e-Fatura | kapalı · fatura · e-belge | Paraşüt | İşaretle ya da e-belgesi **olmayan** faturayı iptal et |
| EDM Bilişim | `edm` | e-Fatura / e-Arşiv (UBL-TR) | kapalı · taslak · gönder | EDM | İşaretle ya da e-Arşiv'i koşullu iptal et |
| QNB eSolutions | `qnb` | e-Fatura / e-Arşiv (UBL-TR) | kapalı · gönder | QNB | İşaretle (iptal QNB portalında) |
| KolayBi | `kolaybi` | Satış faturası, isteğe bağlı e-Arşiv / e-Fatura | kapalı · fatura · e-belge | KolayBi | İşaretle ya da resmileşmemiş ve tahsilatı olmayan faturayı sil |

Ortak davranışlar:

- **Tetikleyici**: `order.paid`, `order.fulfilled` ya da yalnız elle (`manual`).
- **Aksiyonlar**: sipariş detayında önizleme, oluşturma, yeniden deneme ve PDF çekmecesi (`order.detail`, iframe); sipariş listesinde "Seçilenleri faturala" (`order.list`, api, en fazla 50 sipariş).
- **e-Fatura mı e-Arşiv mi**: e-belge kesen uygulamalar alıcının e-Fatura mükellefiyetini sağlayıcıya sorar; mükellefe e-Fatura, diğerlerine e-Arşiv keser. Anonim ve yurt dışı alıcı sorgulanmadan e-Arşiv alır. Hangi alıcıların sorgulandığı sağlayıcıya göre değişir: İşbaşı ve Paraşüt yalnız kurumsal alıcıyı, EDM ve QNB kimlik numarası olan her yurt içi alıcıyı sorgular. KolayBi API'si mükellef sorgusu sunmadığı için belge türünü KolayBi belirler. Sorgu hata verirse belge **kesilmez**; mükellefe yanlışlıkla e-Arşiv gitmesin diye e-Arşiv'e düşülmez.
- **Çift fatura koruması**: uygulama, sağlayıcıyı çağırmadan önce siparişi `creating` olarak işaretler. Zaman aşımı ya da yarım kalan denemeden sonra önce sağlayıcıda sipariş numarası veya belge UUID'siyle arar; belge varsa onu benimser, yoksa yeniden dener.

> e-Fatura bu uygulamaların hiçbirinde otomatik iptal edilmez; düzeltme iade faturasıyla yapılır. e-Arşiv'i otomatik iptal eden tek uygulama EDM'dir: tam iptal ya da iade olması, fatura tarihinden itibaren 7 gün içinde kalınması ve EDM'deki belge durumunun iptale izin vermesi gerekir.

---

## Kurumsal ve Bireysel Alıcı

Checkout'ta müşteri **Bireysel** ya da **Kurumsal** fatura seçer. Seçim sipariş nesnesinin `billingAddress` alanına yazılır ([Siparişler](https://tecof-app-dev.vercel.app/app-api)):

| Alan | Bireysel | Kurumsal (Türkiye) | Kurumsal (yurt dışı) |
| :--- | :--- | :--- | :--- |
| `invoiceType` | `"individual"` | `"corporate"` | `"corporate"` |
| `company` | boş olabilir | Unvan, zorunlu | Unvan, zorunlu |
| `taxNumber` | boş | 10 haneli VKN ya da şahıs şirketi için 11 haneli TCKN; sağlama hanesi doğrulanır | Serbest biçim (harf, rakam, `-`; en fazla 30) |
| `taxOffice` | boş | Zorunlu | Zorunlu değil |
| `identityNumber` | TCKN; yoksa anonim `11111111111` | — | — |

Checkout bu kurallara uymayan siparişi `400 invalid-invoice-identity` ile reddeder. Yine de eski siparişlerde ya da elle oluşturulan kayıtlarda tutarsız veri bulunabileceği için fatura uygulamaları alıcıyı kendileri sınıflandırmalıdır. `classifyBuyer` bunu tek adımda yapar (aşağıda).

---

## Ortak Fatura Durumu

Her fatura uygulaması sipariş başına tek bir **paylaşılan** metafield yazar. Panel bu alanı sipariş detayındaki "Uygulamalar" kartında gösterir. Aynı mağazadaki diğer uygulamalar `orders:read` kapsamıyla `GET /api/v1/metafields?ownerType=order&ownerId=…` üzerinden okuyabilir; yanıtta kendi alanlarının yanında öteki uygulamaların paylaşılan alanları da gelir.

| Özellik | Değer |
| :--- | :--- |
| `ownerType` | `"order"` |
| `namespace` | Uygulamanın slug'ı (`isbasi`, `parasut`, …) |
| `key` | `"invoice"` |
| `type` | `"json"` |
| `visibility` | `"shared"` |
| `panel` | `{ label: { tr, en }, show: true }` |

```json
{
  "status": "issued",
  "documentType": "e-arsiv",
  "invoiceNumber": "ABC2026000000123",
  "uuid": "0b6c6f0e-3a7d-4a35-9a4e-5f2f6b1c9d10",
  "updatedAt": "2026-10-10T09:17:02.000Z"
}
```

`status` sözlüğü bütün fatura uygulamalarında aynıdır:

| Durum | Anlamı |
| :--- | :--- |
| `creating` | Talep alındı, sağlayıcıya gönderiliyor |
| `draft` | Sağlayıcıda taslak olarak duruyor |
| `issued` | Kesildi; e-belgeyse GİB'e gönderildi |
| `signed` | İmzalandı (portal akışlarında) |
| `failed` | Başarısız; `error` alanında temizlenmiş neden |
| `skipped` | Bilerek atlandı; neden `reason` alanında (örn. `total-mismatch`, `non-try-currency`, ayar kapalı) |
| `needs-cancellation` | Sipariş iptal ya da iade edildi; belgenin iptali elle yapılmalı |
| `deleted` | Taslak silindi |
| `cancelled` | Sağlayıcıda iptal edildi |

Değerde kişisel veri tutulmaz: alıcı adı, adresi ya da tam vergi numarası metafield'a ve olay yüküne yazılmaz.

Uygulamalar ayrıca şu [olayları](https://tecof-app-dev.vercel.app/app-interop) yayınlar; dinleyen uygulama `app.<slug>.` önekiyle abone olur:

| Olay | Ne zaman |
| :--- | :--- |
| `app.<slug>.invoice.created` | Fatura ya da taslak oluştu |
| `app.<slug>.invoice.failed` | Deneme başarısız oldu |
| `app.<slug>.invoice.cancelled` | Belge silindi ya da sağlayıcıda iptal edildi |

```ts
// Kargo uygulaması: faturası kesilmemiş siparişi kargoya vermeden önce uyarır
const fields = await api.metafields.list({ ownerType: "order", ownerId: orderId });
const issued = fields.some((m) => m.key === "invoice" && ["issued", "signed"].includes(m.value?.status));
```

---

## Ortak Para Kuralları

Fatura yazan bir uygulama, sipariş toplamıyla birebir aynı faturayı üretmek zorundadır. Kurallar `@tecof/invoice-kit` içinde uygulanmıştır; kendi hesaplamanızı yazıyorsanız aynılarını izleyin.

- **Satır KDV modu** önce satırdan (`taxIncluded`), sonra siparişten (`totals.pricesIncludeTax`) okunur. Oranı `null` olan eski satırlarda mağaza varsayılanı kullanılır.
- **KDV matrahı indirim sonrası tutardır.** Sipariş, her satıra düşen indirimi `lineItems[].discountAmount` alanında taşır; faturayı bu paylarla kurun. Kapsamlı kupon yalnız kendi satırlarına düşer. Eski siparişlerde pay yoksa indirimi ürün satırlarına tutarla orantılı dağıtın. İndirim kargo ve ödeme ücretine düşmez.
- **Kargo** ve **ödeme ek ücreti** ayrı hizmet satırıdır. Oranı bilinmeyen kargo KDV dahil sayılır.
- **Hediye çeki** ödeme aracıdır, indirim değildir: fatura tam tutardan kesilir.
- **Mutabakat**: küçük kuruş farkları (varsayılan `max(0,05; 0,01 × satır sayısı)`) en büyük satırda düzeltilir. Fark bu toleransı aşarsa `total-mismatch` uyarısı oluşur.
- **`total-mismatch`** olan sipariş otomatik ve toplu faturalamada **atlanır** (`status: "skipped"`, `reason: "total-mismatch"`). Mağaza sipariş çekmecesinde farkı görüp onaylayarak "Farka rağmen oluştur" diyebilir.
- **TRY dışı** sipariş: Paraşüt ve KolayBi uygulamaları ayar açıksa döviz faturasını TCMB kuruyla keser; diğer uygulamalar bu sürümde yalnız TRY faturalar ve döviz siparişini `skipped` olarak işaretler. `toInvoiceDraft` döviz siparişinde kur ister (`exchange-rate-missing`).

---

## @tecof/invoice-kit

Siparişi ([`GET /api/v1/orders/:id`](https://tecof-app-dev.vercel.app/app-api)) doğru bir Türk faturasına çeviren, bağımlılıksız TypeScript paketidir. Tecof'un bütün fatura uygulamaları bunu kullanır.

```bash
npm install @tecof/invoice-kit
```

```ts
import { toInvoiceDraft, buildUblInvoice } from "@tecof/invoice-kit";

const order = await api.orders.get(orderId);
const draft = toInvoiceDraft(order, { defaultVatRate: 20 });

if (draft.warnings.some((w) => w.code === "total-mismatch")) {
  // Otomatik akışta atla; kararı mağazaya bırak
}

// e-Fatura / e-Arşiv entegratörü UBL bekliyorsa
const xml = buildUblInvoice(draft, {
  profile: "EARSIVFATURA",
  typeCode: "SATIS",
  uuid: crypto.randomUUID(),
  supplier,
});
```

| Dışa aktarım | Ne yapar |
| :--- | :--- |
| `toInvoiceDraft(order, options?)` | Alıcı, satırlar, KDV dökümü, toplamlar, düzenleme tarihi (Europe/Istanbul) ve uyarılar. Hata fırlatmaz; faturayı kesip kesmemek çağıranın kararıdır |
| `classifyBuyer(order)` | `corporate`, `individual`, `anonymous` ya da `foreign`; kimlik numarası, unvan, vergi dairesi ve uyarılar |
| `buildUblInvoice(draft, options)` | İmzasız UBL-TR 1.2 fatura XML'i (TEMELFATURA, TICARIFATURA, EARSIVFATURA) |
| `isValidVkn`, `isValidTckn` | Sağlama hanesi doğrulaması; checkout ile aynı algoritma |
| `amountInWords(tutar)` | "Yalnız Bin İki Yüz Otuz Dört Türk Lirası Elli Kuruş" |
| `suggestEArchivePaymentMethod(provider)` | Tecof ödeme sağlayıcısını GİB ödeme şekline çevirir |

Alıcı sınıflandırması:

1. Fatura adresi yurt dışıysa `foreign` olur. Kurumsalda kimlik `2222222222` kullanılır, alıcının kendi vergi numarası nota ve UBL'e ayrıca yazılır.
2. `invoiceType: "corporate"` ve geçerli VKN ya da TCKN varsa `corporate` olur. Numara geçersizse bireysel kurala düşer ve `tax-number-invalid` uyarısı oluşur.
3. Geçerli TCKN varsa `individual`, yoksa `anonymous` (`11111111111`) olur.

Bilinen sınırlar: ihracat, tevkifat, ÖTV ve özel matrah faturaları desteklenmez. Paket belgeyi imzalamaz ve zarf üretmez; bunlar entegratörün işidir. Alıcının e-Fatura mükellefi olup olmadığını da sorgulamaz; bunu entegratörden öğrenmeniz gerekir.

---

## Kendi Fatura Uygulamanızı Yazarken

- Kimlik bilgilerini yalnız [Vault](https://tecof-app-dev.vercel.app/app-data)'ta tutun; arayüze ve günlüklere maskeli yazın.
- Sağlayıcı adresi ayarlanabiliyorsa yalnız `https` ve sağlayıcının kendi alan adlarına izin verin. Aksi hâlde saklanan kimlik bilgileri başka bir sunucuya gönderilebilir.
- Siparişi her zaman kurulum token'ıyla okuyun. Başka mağazanın siparişi `404` döner; panelden gelen sipariş kimliğine bu kontrol olmadan güvenmeyin.
- Webhook'u 8 saniye içinde yanıtlayın, sağlayıcı çağrısını arka plana alın. Aynı olay birden fazla gelebilir; `creating` işaretiyle çift faturayı önleyin.
- Durumu yukarıdaki sözleşmeyle yazın, olayları yayınlayın. Sağlayıcı hata mesajlarını göstermeden önce oturum kimliği, parola ve tam vergi numarasından arındırın.
- GİB'e gitmiş bir belgeyi kural dışında iptal etmeyin; emin değilseniz `needs-cancellation` işaretleyip kararı mağazaya bırakın.

Uçtan uca örnek için [Örnek Uygulama: Logo İşbaşı](https://tecof-app-dev.vercel.app/app-example-isbasi) sayfasına bakın.

---

# Örnek Uygulama: Logo İşbaşı

> Uçtan uca örnek uygulama: Logo İşbaşı ile otomatik fatura — Vault, metafield, aksiyon ve olay yayını.
>
> Kaynak: https://tecof-app-dev.vercel.app/app-example-isbasi · Bölüm: Uygulama geliştirme · Son güncelleme: 2018-10-20

Logo İşbaşı uygulaması, platformun yeteneklerini uçtan uca gösteren örnek bir fatura uygulamasıdır: ödenen siparişler için İşbaşı'nda otomatik fatura oluşturur, İşbaşı kimlik bilgilerini Vault'ta saklar, fatura numarasını siparişe metafield olarak yazıp panelde gösterir, sipariş ekranlarına aksiyon ekler ve başka uygulamaların dinleyebileceği `invoice.created` olayını yayınlar.

> Bu sayfa uygulamanın mimarisini ve platformla sözleşmesini anlatır. İşbaşı API'sinin kendi ayrıntıları (uç adları, alanlar) uygulamaya özgüdür ve burada `createIsbasiInvoice` gibi yardımcılarla soyutlanmıştır. Ayar alanları örnektir; uygulamanın son sürümünde farklılık gösterebilir.

---

## Ne Yapar

| Özellik | Platform yeteneği |
| :--- | :--- |
| `order.paid` geldiğinde faturayı **taslak** ya da **kesilmiş** olarak oluşturur (mağaza ayarı) | [Webhook'lar](https://tecof-app-dev.vercel.app/app-webhooks), [API](https://tecof-app-dev.vercel.app/app-api) |
| İşbaşı API anahtarı ve parolasını panelin ayar formundan alır, şifreli saklar | [Yerel ayar formu + Vault](https://tecof-app-dev.vercel.app/app-data) |
| Fatura numarasını siparişe yazar; sipariş detayındaki "Uygulamalar" kartında görünür | [Metafield'lar](https://tecof-app-dev.vercel.app/app-data) |
| Sipariş detayına "İşbaşı'nda fatura kes", sipariş listesine "Seçilenleri faturala" ekler | [Aksiyonlar](https://tecof-app-dev.vercel.app/app-actions) |
| Panelde "Faturalar" ekranı | [App Bridge](https://tecof-app-dev.vercel.app/app-bridge), `navigation` |
| Fatura kesilince `app.isbasi.invoice.created` olayını yayınlar | [Uygulamalar Arası İletişim](https://tecof-app-dev.vercel.app/app-interop) |
| Aylık plan ve 14 günlük deneme | [Ücretlendirme](https://tecof-app-dev.vercel.app/app-billing) |

---

## Yapılandırma

```json
{
  "name": "Logo İşbaşı",
  "slug": "isbasi",
  "hosting": "tecof",
  "embedded": true,
  "scopes": ["orders:read", "customers:read", "products:read"],
  "webhooks": {
    "path": "/api/webhooks",
    "events": ["order.paid", "order.cancelled", "order.refunded"]
  },
  "actions": [
    {
      "key": "create-invoice", "type": "iframe", "placement": "order.detail",
      "title": { "tr": "İşbaşı'nda fatura kes", "en": "Create İşbaşı invoice" },
      "path": "/actions/create-invoice", "presentation": "modal"
    },
    {
      "key": "bulk-invoice", "type": "api", "placement": "order.list",
      "title": { "tr": "Seçilenleri faturala", "en": "Invoice selected" },
      "path": "/api/actions/bulk-invoice",
      "confirm": { "tr": "Seçili siparişler için fatura kesilsin mi?", "en": "Create invoices for selected orders?" }
    }
  ],
  "navigation": [
    { "label": { "tr": "Faturalar", "en": "Invoices" }, "path": "/invoices" }
  ],
  "settings": [
    { "key": "username", "label": { "tr": "İşbaşı kullanıcı adı", "en": "İşbaşı username" }, "type": "text", "required": true },
    { "key": "password", "label": { "tr": "İşbaşı parolası", "en": "İşbaşı password" }, "type": "secret", "required": true },
    { "key": "apiKey", "label": { "tr": "İşbaşı API anahtarı", "en": "İşbaşı API key" }, "type": "secret", "required": true },
    { "key": "autoInvoice", "label": { "tr": "Ödenen siparişleri otomatik faturala", "en": "Auto-invoice paid orders" }, "type": "boolean" },
    { "key": "issueInvoices", "label": { "tr": "Faturayı taslak değil kesilmiş olarak oluştur", "en": "Issue invoices instead of drafts" }, "type": "boolean" },
    { "key": "defaultVatRate", "label": { "tr": "Varsayılan KDV oranı (%)", "en": "Default VAT rate (%)" }, "type": "number" }
  ],
  "appEvents": {
    "publishes": [
      { "name": "invoice.created", "description": { "tr": "Fatura oluşturuldu", "en": "Invoice created" } }
    ],
    "subscribes": ["app.kargo.shipment.created"]
  },
  "plans": [
    {
      "key": "standart", "name": { "tr": "Standart", "en": "Standard" },
      "description": { "tr": "Sınırsız otomatik fatura", "en": "Unlimited automatic invoices" },
      "price": 199, "currency": "TRY", "interval": "month", "trialDays": 14,
      "features": [{ "tr": "Sınırsız fatura", "en": "Unlimited invoices" }]
    }
  ],
  "listing": {
    "shortDescription": { "tr": "Siparişlerinizi Logo İşbaşı'nda otomatik faturalayın", "en": "Automatically invoice orders in Logo İşbaşı" },
    "description": { "tr": "…", "en": "…" },
    "category": "accounting",
    "supportEmail": "destek@ornek.com",
    "privacyUrl": "https://ornek.com/gizlilik"
  }
}
```

Kapsam gerekçeleri: `orders:read` sipariş ve `order.*` olayları, sipariş aksiyonları ve sipariş metafield'ları için; `customers:read` fatura alıcısı için; `products:read` ürün bilgisi için. Uygulama Tecof'a ürün ya da sipariş **yazmaz**; tek yazdığı şey kendi metafield'ları, ayarları ve olaylarıdır.

---

## Mimari

```mermaid
sequenceDiagram
    participant M as Mağaza paneli
    participant T as Tecof API
    participant A as İşbaşı uygulaması
    participant L as Logo İşbaşı API

    Note over M,A: Kurulum ve ayar
    M->>T: Kurulum (kapsam onayı, deneme planı)
    T->>A: webhook app.installed
    M->>T: Ayarlar sekmesi: kullanıcı adı, parola, API anahtarı
    T->>T: Sır alanları Vault'a (AES-256-GCM)
    T->>A: webhook app.settings.updated { keys, secretKeys }

    Note over T,L: Otomatik fatura
    T->>A: webhook order.paid (imzalı)
    A->>T: POST /api/apps/oauth/token (client_credentials)
    A->>T: GET /api/v1/metafields?ownerType=order&namespace=isbasi
    A->>T: GET /api/v1/orders/:id
    A->>T: GET /api/v1/app/settings + /api/v1/app/secrets/:key
    A->>L: Fatura oluştur (taslak / kesilmiş)
    L-->>A: Fatura numarası
    A->>T: PUT /api/v1/metafields (invoiceNumber, shared, panelde göster)
    A->>T: POST /api/v1/app/events { name: "invoice.created" }
    A-->>T: 204
```

---

## Fatura Oluşturma

Webhook işleyicisi, iframe aksiyonu ve toplu API aksiyonu aynı fonksiyonu çağırır:

```ts
// lib/invoice.ts
import { tecof } from "@/lib/tecof";
import { createIsbasiInvoice } from "@/lib/isbasi"; // uygulamaya özgü İşbaşı istemcisi

export async function invoiceOrder(installationId: string, orderId: string) {
  const api = tecof.client(installationId);

  // 1) Idempotency: siparişte fatura numarası varsa tekrar kesme
  const existing = await api.metafields.list({ ownerType: "order", ownerId: orderId, namespace: "isbasi" });
  if (existing.some((m: { key: string }) => m.key === "invoiceNumber")) {
    return { status: "skipped" as const };
  }

  // 2) Siparişin güncel hâli
  const order = await api.orders.get(orderId);
  if (order.currency !== "TRY") {
    return { status: "unsupported-currency" as const }; // v1: yalnız TRY
  }

  // 3) Ayarlar ve Vault
  const { settings } = await api.settings.get();
  const [{ value: password }, { value: apiKey }] = await Promise.all([
    api.secrets.get("password"),
    api.secrets.get("apiKey"),
  ]);
  const defaultVatRate = Number(settings.defaultVatRate ?? 20);

  // 4) İşbaşı'nda fatura
  const invoice = await createIsbasiInvoice(
    { username: String(settings.username), password, apiKey },
    {
      issue: settings.issueInvoices === true, // false → taslak
      buyer: order.billingAddress,            // identityNumber: TCKN/VKN
      lines: order.lineItems.map((li) => ({
        name: li.variantTitle ? `${li.name} (${li.variantTitle})` : li.name,
        sku: li.sku,
        quantity: li.quantity,
        unitPrice: li.unitPrice,
        vatRate: li.taxRate ?? defaultVatRate, // null = eski sipariş → mağaza varsayılanı
        taxIncluded: li.taxIncluded,
      })),
      shipping: order.shippingLines,
      discounts: order.discountLines,
    },
  );

  // 5) Fatura numarasını siparişe yaz (panelde görünür, diğer uygulamalarla paylaşılır)
  await api.metafields.set({
    ownerType: "order",
    ownerId: order.id,
    key: "invoiceNumber",
    type: "string",
    value: invoice.number,
    visibility: "shared",
    panel: { label: { tr: "İşbaşı fatura no", en: "İşbaşı invoice no" }, show: true },
  });

  // 6) Olayı yayınla
  await api.events.publish("invoice.created", {
    orderId: order.id,
    orderNumber: order.orderNumber,
    invoiceNumber: invoice.number,
    issued: settings.issueInvoices === true,
  });

  return { status: "created" as const, invoiceNumber: invoice.number };
}
```

Webhook işleyicisi:

```ts
// app/api/webhooks/route.ts
import { createWebhookHandler } from "@tecof/app-sdk";
import { tecof } from "@/lib/tecof";
import { invoiceOrder } from "@/lib/invoice";

export const POST = createWebhookHandler({
  app: tecof,
  handlers: {
    "order.paid": async (event) => {
      const { settings } = await tecof.client(event.installationId).settings.get();
      if (settings.autoInvoice === true) {
        await invoiceOrder(event.installationId, String(event.data.orderId));
      }
    },
    // v1: fatura otomatik iptal edilmez — iptal/iade belgesi İşbaşı'nda yönetilir
    "order.cancelled": async () => {},
    "order.refunded": async () => {},
  },
});
```

`invoiceOrder` kalıcı hatalarda (eksik ayar, desteklenmeyen para birimi) hata fırlatmaz, bir durum döner; böylece işleyici `2xx` yanıt verir ve Tecof aynı olayı boşuna yeniden denemez. Geçici hatalarda (İşbaşı'na ulaşılamadı) hata fırlatılır; `createWebhookHandler` `2xx` dışı yanıt döner ve teslimat +2 dk ile +15 dk sonra yeniden denenir. Yeniden denemede `invoiceNumber` metafield kontrolü çift faturayı önler.

---

## Panelde Görünüm

| Yer | Ne görünür |
| :--- | :--- |
| Uygulamalar → İşbaşı → Ayarlar | Yerel ayar formu; sır alanları yalnız "ayarlı / ayarlı değil" gösterir |
| Uygulamalar → İşbaşı → Faturalar | Gömülü `/invoices` ekranı (App Bridge) |
| Sipariş detayı → "Uygulamalar" kartı | `İşbaşı fatura no: ABC2026000000123` (metafield) |
| Sipariş detayı → "Uygulamalar" menüsü | "İşbaşı'nda fatura kes" (iframe aksiyonu, modal) |
| Sipariş listesi → toplu işlemler | "Seçilenleri faturala" (API aksiyonu, onaylı) |

---

## Sınırlamalar (v1)

| Konu | Durum |
| :--- | :--- |
| Para birimi | Yalnız **TRY** siparişler faturalanır; diğer para birimleri atlanır |
| İptal / iade | `order.cancelled` ve `order.refunded` alınır ancak fatura **otomatik iptal edilmez**; iptal ve iade belgeleri İşbaşı'nda elle yönetilir |
| KDV oranı bilinmeyen eski siparişler | Kalemde `taxRate: null` ise uygulama ayarındaki varsayılan oran kullanılır |
| Abonelik | Otomatik yenileme yok; mağaza dönem sonunda planı yeniler |

---

# CLI Başvurusu

> Tüm tecof komutları ve seçenekleri (@tecof/cli 0.2.0), ortam değişkenleri, çıkış kodları, JSON makbuzları ve next.action, yok sayma kuralları ve sınırlar.
>
> Kaynak: https://tecof-app-dev.vercel.app/cli-reference · Bölüm: CLI · Son güncelleme: 2018-10-20

`@tecof/cli` paketi `tecof` komutunu kurar. Bu sayfa tüm komutları ve seçenekleri, ortam değişkenlerini, çıkış kodlarını, JSON makbuzlarını, yok sayma kurallarını ve sınırları listeler. Adım adım akış için [Tema Geliştirme: Hızlı Başlangıç](https://tecof-app-dev.vercel.app/theme-quickstart) ve [Hızlı Başlangıç: Tecof CLI](https://tecof-app-dev.vercel.app/app-quickstart) sayfalarına bakın.

```bash
npm install -g @tecof/cli    # Node.js 20+
tecof --help                 # tüm komutlar
tecof theme                  # bir grubun komutları
tecof theme push --help      # tek komutun seçenekleri
```

Mesajlar Türkçedir; `TECOF_LANG=en` İngilizce çıktı verir. `TECOF_LANG` tanımlı değilse ve sistem dili (`LC_ALL`, `LC_MESSAGES` ya da `LANG`) `en` ile başlıyorsa da İngilizce kullanılır; Türkçeyi zorlamak için `TECOF_LANG=tr`.

---

## Genel Seçenekler

| Seçenek | Açıklama |
| :--- | :--- |
| `--api <url>` | Tecof API adresi. Öncelik: `--api`, sonra `TECOF_API_URL`, sonra kayıtlı yapılandırma, sonra `https://api.tecof.com` |
| `--json` | Makine makbuzu: başarıda stdout'a, hatada stderr'e tek JSON belgesi ([JSON makbuzları](#json-makbuzlari)) |
| `-y`, `--yes` | Yıkıcı işlemleri onaylar: `promote`, `rollback`, `push --prod`, `tokens revoke` |
| `--show-secret` | Makbuzda sırları maskelemez (önizleme bağlantısı, yeni token) |
| `-h`, `--help` | Yardım |
| `-v`, `--version` | CLI sürümü |

Alan kimlikleri `thm_…` (tema) ya da `app_…` (uygulama) biçimindedir. Sürümlere `v12`, `12` ya da sürüm kimliğiyle başvurulur.

---

## Hesap

| Komut | Açıklama |
| :--- | :--- |
| `tecof login [--api <url>] [--no-browser]` | Cihaz akışıyla giriş. Doğrulama kodu (`ABCD-EFGH`) ve onay adresi (`https://app.tecof.com/cli?code=…`) gösterilir; kod 10 dakika geçerlidir, CLI onayı 5 saniyede bir yoklar. `--no-browser` tarayıcıyı açmaz. `--json` modunda kod ve adres stderr'e yazılır |
| `tecof logout` | Token'ı sunucuda iptal eder ve yerelden siler. `TECOF_TOKEN` ile verilen token iptal edilmez; CLI uyarır |
| `tecof whoami` | Kullanıcı, partner (varsa), rol, programlar ve API adresi |
| `tecof status` | Kimlik, API, token kaynağı ve bitişi, klasörün bağlı olduğu alan, canlı ve son sürüm, geri alınmış mı, yerel taban ve tabana göre yerel değişiklik sayıları. Hiçbir şeyi değiştirmez |
| `tecof doctor` | Ortam denetimi; zorunlu bir denetim başarısızsa çıkış 1 |

`tecof doctor` denetimleri:

| Denetim | Zorunlu | Ne bakar |
| :--- | :--- | :--- |
| `node` | Evet | Node.js 20 ya da üstü |
| `api` | Evet | API adresine erişim |
| `token` | Evet | Token var ve sunucu kabul ediyor |
| `credentials` | Hayır | Kullanılan kimlik deposu |
| `link` | Hayır | Klasör bir alana bağlı mı |
| `git` | Hayır | git kurulu mu |
| `package-manager` | Hayır | Kilit dosyasına göre paket yöneticisi |
| `cloudflared` | Hayır | Yalnız `tecof app dev` tüneli için |

---

## Alanlar

| Komut | Açıklama |
| :--- | :--- |
| `tecof spaces ls [--kind theme\|app]` | Erişebildiğiniz alanlar: kimlik, tür, ad, mağaza ya da uygulama, canlı sürüm, son sürüm, geri alınmış mı, yazılabilir mi (değilse nedeni). Kapsamlı token yalnız izin verilen alanları görür |
| `tecof spaces get [--space <id>]` | Tek alanın ayrıntısı: yazılabilirlik, canlı ve son sürüm, geri alma zamanı, canlı adres, depo, üretim dalı ve `main` commit'i. `--space` verilmezse klasörün bağlı olduğu alan (tema bağı, yoksa `tecof.app.json`) |

---

## Tema

`theme ls` ve `theme init` dışındaki tema komutları, bulunduğunuz klasörden yukarı doğru ilk `.tecof/space.json` bağını kullanır.

| Komut | Açıklama |
| :--- | :--- |
| `tecof theme ls` | Tema alanlarını listeler |
| `tecof theme init [dir] --space <thm_…> [--force]` | Klasör açar, alana bağlar, `main` dalını indirir. Klasör adı verilmezse tema adından türetilir. `--space` etkileşimli terminalde verilmezse listeden seçilir; ajan modunda zorunludur (yoksa çıkış 2). `--force` boş olmayan klasöre ve yerel dosyaların üzerine yazar |
| `tecof theme link [--space <thm_…>]` | Bu klasörü bir tema alanına bağlar (`.tecof/space.json`). Başka bir alana yeniden bağlarken eski yerel taban silinir |
| `tecof theme pull [--ref vN\|main] [--force]` | Kaynağı indirir (varsayılan `main`). Yerelde değişmiş bir dosyanın üzerine yazılacaksa hiçbir şey yazmadan durur (çıkış 4, `next.action: "confirm"`); `--force` üzerine yazar ve uzakta silinmiş dosyaları siler |
| `tecof theme dev [--port <n>] [--cloud [--keep]]` | Yerel geliştirme ya da bulut oturumu ([ayrıntı](https://tecof-app-dev.vercel.app/theme-quickstart#5-yerelde-gelistirin)) |
| `tecof theme push [-m <mesaj>] [--prod] [--no-wait] [--wait-timeout <sn>] [--force]` | Yalnız değişen dosyaları yükler ve yeni sürüm açar (varsayılan staged) |
| `tecof theme versions [ls\|vN] [--limit <n>]` | Sürüm listesi (varsayılan 20, en çok 100) ya da tek sürümün durumu |
| `tecof theme open [vN]` | Sürümün önizlemesini açar; sürüm verilmezse canlı adresi. Ajan modunda tarayıcı açılmaz, bağlantı yazılır |
| `tecof theme logs vN` | Sürümün derleme günlüğü |
| `tecof theme promote vN` | Sürümü yeniden derlemeden canlıya alır (yıkıcı) |
| `tecof theme rollback [vN]` | Bir önceki canlı sürüme ya da verilen, daha önce canlıda olmuş sürüme döner (yıkıcı) |

`tecof theme dev` seçenekleri:

| Seçenek | Açıklama |
| :--- | :--- |
| `-p`, `--port <port>` | Yerel sunucu portu (varsayılan `PORT` ya da `3000`) |
| `--cloud` | Bulut oturumu açar, değişiklikleri izleyip önizlemeye yazar |
| `--keep` | Çıkışta bulut oturumunu açık bırakır |

`tecof theme push` seçenekleri:

| Seçenek | Açıklama |
| :--- | :--- |
| `-m`, `--message <mesaj>` | Sürüm mesajı. Varsayılan: son git commit başlığı, yoksa `tecof theme push` |
| `--prod` | Doğrudan canlıya: commit `main` dalına hızlı ileri yazılır, derleme bitince canlıya çıkar. Yıkıcı, onay ister |
| `--no-wait` | Derlemeyi beklemez; makbuzda `next.action: "poll"` |
| `--wait-timeout <sn>` | Bekleme süresi (varsayılan 900). Süre dolarsa çıkış 1 ve `next.action: "poll"`; derleme sürmeye devam eder |
| `--force` | Yerel taban yokken (hiç `pull` yapılmamış klasörde) push'un uzaktaki dosyaları silmesine izin verir |

---

## Uygulama

Uygulama komutları bulunduğunuz klasörden yukarı doğru ilk `tecof.app.json` dosyasını kullanır. Alan kimliği `app_<tecof.app.json içindeki id>` olur.

Sürüm komutları:

| Komut | Açıklama |
| :--- | :--- |
| `tecof app push [-m <mesaj>] [--prod] [--no-wait] [--wait-timeout <sn>]` | Yalnız değişen dosyaları yükler ve yeni sürüm açar (varsayılan staged). Her push `main` dalının üstüne kurulur; klasör istenen son durumdur. `tecof.app.json` bu komutla gönderilmez |
| `tecof app versions [ls\|vN] [--limit <n>]` | Uygulama sürümleri |
| `tecof app promote vN` | Sürümü canlıya alır (yıkıcı) |
| `tecof app rollback [vN]` | Önceki canlı sürüme döner (yıkıcı) |
| `tecof app logs <vN\|dağıtım kimliği>` | `vN` için sürüm günlüğü; diğer değerler için eski dağıtım günlüğü |

Sürüm komutları yalnız Tecof barındırmalı uygulamalarda çalışır; `hosting: "external"` uygulamada hata verir.

Diğer uygulama komutları:

| Komut | Açıklama |
| :--- | :--- |
| `tecof app init [dir] [--template starter\|actions] [--name <ad>] [--slug <slug>] [--no-create] [--force]` | Şablondan proje açar ve uygulamayı sunucuda oluşturur; `--no-create` yalnız şablonu kopyalar |
| `tecof app link [--app <id\|clientId\|slug>]` | Klasörü mevcut bir uygulamaya bağlar |
| `tecof app info` | Uygulama bilgisi |
| `tecof app config push` | `tecof.app.json` dosyasını gönderir |
| `tecof app dev [-p <port>] [--tunnel cloudflared\|none\|<url>]` | Geliştirme sunucusu, tünel ve test mağazası adresi. `--tunnel` verilmezse cloudflared kuruluysa kullanılır; kendi tünel adresiniz herkese açık bir `https://` adresi olmalıdır |
| `tecof app deploy [-m <mesaj>]` | Tüm kaynağı paketleyip doğrudan yayınlar. Çalışmaya devam eder; artımlı push, staged sürüm ve anında geri alma için `app push` önerilir |
| `tecof app deployments` | `app deploy` dağıtımlarının listesi |
| `tecof app secret rotate [--yes]` | İstemci sırrını döndürür ve `.env.local` dosyasını günceller. Etkileşimsiz ortamda `--yes` ister (yoksa çıkış 1) |
| `tecof app open [--install]` | Uygulamayı geliştirici portalında ya da kurulum sayfasında açar |

Ayrıntılar: [Hızlı Başlangıç: Tecof CLI](https://tecof-app-dev.vercel.app/app-quickstart).

---

## Token'lar

| Komut | Açıklama |
| :--- | :--- |
| `tecof tokens ls` | Cihaz oturumları ve kapsamlı token'lar: kimlik, ad, yetki seti, alanlar (`*` = tümü), son kullanım, bitiş; bu oturum işaretlenir |
| `tecof tokens create --name <ad> [--preset deploy\|read] [--space <id> …] [--expires <gün>]` | Kapsamlı CI token'ı basar. `--preset` verilmezse `read`. `--space` tekrarlanabilir ya da virgülle ayrılabilir; verilmezse erişebildiğiniz tüm alanlar. `--expires` 1–365 gün (varsayılan 90). Değer insan çıktısında bir kez gösterilir; `--json` makbuzunda `--show-secret` olmadan maskelenir |
| `tecof tokens revoke <id>` | Token'ı iptal eder (yıkıcı) |

Kapsamlı token'la `tokens ls`, `tokens create` ve başka bir token için `tokens revoke` çalışmaz. Ayrıntı: [Güvenlik ve CI](https://tecof-app-dev.vercel.app/dev-security#token-turleri-ve-omurleri).

---

## Kurulum

| Komut | Açıklama |
| :--- | :--- |
| `tecof setup agent [--client claude-code\|cursor] [--merchant <id>] [--force]` | Projeye Tecof uzak MCP sunucusunu ekler: Claude Code için `.mcp.json`, Cursor için `.cursor/mcp.json`. Dosyaya sır yazılmaz; istemci ilk bağlantıda Tecof OAuth onayını açar. `--merchant` mağaza kapsamlı adres (`/mcp/<mağaza kimliği>`) yazar; `--force` var olan farklı bir `tecof` girdisini değiştirir |

Ayrıntı: [Güvenlik ve CI → Kodlama ajanları](https://tecof-app-dev.vercel.app/dev-security#kodlama-ajanlari).

---

## Ortam Değişkenleri

| Değişken | Etki |
| :--- | :--- |
| `TECOF_TOKEN` | Token (CI için). Kayıtlı girişin yerine kullanılır; değeri hiçbir çıktıda basılmaz |
| `TECOF_API_URL` | API adresi (`--api` daha önceliklidir) |
| `TECOF_PANEL_URL` | Panel adresi (kurulum ve portal bağlantıları); verilmezse girişteki onay adresinden alınır |
| `TECOF_AGENT=1` | Ajan modu: soru sorulmaz, tarayıcı açılmaz. stdin bir terminal değilse ajan modu kendiliğinden açıktır |
| `TECOF_AGENT_ALLOW_DESTRUCTIVE=1` | Yıkıcı işlemlere `--yes` olmadan izin verir. Kodlama ajanlarının ortamında tanımlamayın |
| `TECOF_CREDENTIAL_STORE` | `keyring` (işletim sistemi anahtarlığını zorunlu kılar; yoksa hata) ya da `plaintext` (dosya) |
| `TECOF_PROFILE` | Kimlik deposunda hesap öneki (varsayılan `default`); aynı makinede birden çok hesap için |
| `TECOF_CONFIG_DIR` | Yapılandırma klasörü (varsayılan `$XDG_CONFIG_HOME/tecof` ya da `~/.config/tecof`). Tanımlıysa kimlik de bu klasördeki dosyaya yazılır |
| `TECOF_LANG` | `en` İngilizce, `tr` Türkçe çıktı |
| `TECOF_NO_BROWSER=1` | Tarayıcı açmaz (`BROWSER=none` da aynı etkiyi verir) |
| `TECOF_DEBUG=1` | Beklenmeyen hatalarda yığın izini basar; `--json` modunda ilerleme satırlarını stderr'e yazar |
| `TECOF_DEPLOY_POLL_MS` | Sürüm yoklama aralığı (varsayılan 3000 ms) ve bulut oturumu açılış yoklaması (varsayılan 2000 ms) |
| `TECOF_DEV_DEBOUNCE_MS` | Bulut geliştirmede değişiklik toplama süresi (varsayılan 300 ms) |
| `TECOF_DEV_HEARTBEAT_MS` | Bulut oturumu canlılık bildirimi aralığı (varsayılan 60000 ms) |
| `CI` | Tanımlıysa soru sorulmaz ve kimlik varsayılan olarak dosyada tutulur |
| `PORT` | `theme dev` ve `app dev` için varsayılan port |
| `NO_COLOR` | Renkli çıktıyı kapatır |

---

## Çıkış Kodları

| Kod | Anlamı | Örnekler |
| :--- | :--- | :--- |
| `0` | Başarı | Push tamamlandı, değişiklik yok (`noop`), sürüm canlıda |
| `1` | Hata | Derleme hatası, bekleme süresi doldu, gizli anahtar bulundu, yasak yol, ağ hatası, oturum geçersiz (`401`), `doctor` zorunlu denetimi |
| `2` | Kullanım hatası | Bilinmeyen komut ya da seçenek, geçersiz değer, ajan modunda eksik zorunlu seçenek (ör. `--space`) |
| `3` | Onay gerekli | Ajan ya da etkileşimsiz modda `--yes` olmadan yıkıcı işlem; API'ye hiç istek gitmez |
| `4` | Çakışma | `base-moved`, `space-busy` ve diğer `409` yanıtları (ör. `version-not-ready`, `rollback-target-invalid`); pull'da yerel değişiklik; taban bilinmeden silme (`unknown-base`) |

Geliştirme sunucusu komutları (`theme dev`, `app dev`) Ctrl+C ile kesilince `130` döner; yerel `theme dev` aksi hâlde geliştirme sunucusunun çıkış kodunu iletir.

---

## JSON Makbuzları

`--json` ile her komut tek bir JSON belgesi basar: başarıda **stdout**'a, hatada **stderr**'e. Başka satır basılmaz; uyarılar makbuzun `diagnostics` dizisine girer.

Başarı makbuzu (`tecof theme push --json`; `version` nesnesi kısaltılmıştır):

```json
{
  "ok": true,
  "command": "theme push",
  "space": "thm_66f1a2b3c4d5e6f7a8b9c0d1",
  "version": {
    "number": 12,
    "ref": "v12",
    "source": "cli",
    "target": "staged",
    "status": "ready",
    "live": false,
    "servedBefore": false,
    "commitSha": "4d2c9e…",
    "baseSha": "a1b2c3…",
    "message": "Yeni ana sayfa",
    "url": "https://tecof-theme-butik-3k9x2a1b7-tecof.vercel.app",
    "liveUrl": null,
    "stats": { "files": 312, "uploaded": 3, "reused": 0, "deleted": 1, "unchanged": 309, "bytes": 18234 }
  },
  "activation": { "outcome": "staged", "liveVersion": 11, "rolledBack": false, "diagnostics": [] },
  "push": { "files": 312, "uploaded": 3, "deleted": 1, "unchanged": 309, "bytes": 18234 },
  "next": { "action": "promote", "command": "tecof theme promote v12" },
  "diagnostics": []
}
```

Hata makbuzu (`tecof theme promote v12 --yes --json`, stderr):

```json
{
  "ok": false,
  "command": "theme promote",
  "space": "thm_66f1a2b3c4d5e6f7a8b9c0d1",
  "error": {
    "code": "base-moved",
    "message": "main ilerledi (şu an 9f8e7d6); bu push eski tabana dayanıyor (base-moved).",
    "data": { "mainSha": "9f8e7d6…" }
  },
  "next": { "action": "pull", "command": "tecof theme pull" },
  "diagnostics": []
}
```

| Alan | Açıklama |
| :--- | :--- |
| `ok` | `true` başarı, `false` hata |
| `command` | Çalışan komut (ör. `theme push`) |
| `space` | İlgili alan kimliği ya da `null` |
| `version` | Sürüm nesnesi (push, `versions vN`, promote, rollback); bazı sonuçlarda yalnız `{ ref }` |
| `live` | Canlı sürüm: `{ ref, number, url }` (promote, rollback, `spaces get`, `open`) |
| `activation` | Sürümün canlıya göre konumu ([değerler](https://tecof-app-dev.vercel.app/versions-and-rollback#aktivasyon)) |
| `error` | Yalnız hata makbuzunda: `{ code, message, status?, data? }`. API hatalarında `code` sunucunun hata kodu, `status` HTTP durumudur |
| `next` | Sonraki adım: `{ action, command? }` |
| `diagnostics` | Uyarılar ve bulgular: `{ level, message, code?, path?, line?, kind? }` |

Komuta göre ek alanlar gelir: `push` (yükleme özeti), `noop`, `versions`, `spaces`, `detail`, `tokens`, `token`, `url`, `protected`, `opened`, `lines`, `checks` (`doctor`) vb. `whoami` ve eski uygulama komutları (`app init`, `link`, `info`, `config push`, `dev`, `deploy`, `deployments`, `secret rotate`, `open`) başarıda daha basit bir JSON basar; hata makbuzları her komutta aynı biçimdedir.

### next.action Değerleri

| Değer | Ne yapılır |
| :--- | :--- |
| `done` | İş bitti |
| `poll` | İş sürüyor; `next.command` ile durumu yoklayın (ör. `tecof theme versions v12`) |
| `promote` | Sürüm hazır ve staged; `next.command` canlıya alır |
| `pull` | `main` ilerledi ya da yerel taban yok; `tecof theme pull` ile güncelleyin, yeniden push edin |
| `confirm` | Onay gerekiyor; kullanıcı onaylarsa `next.command` komutunu çalıştırın (ör. `… --yes`, `tecof theme pull --force`) |
| `retry` | Geçici durum (`space-busy`, ağ hatası, `429`, `5xx`); biraz sonra `next.command` |
| `login` | Oturum yok ya da geçersiz; `tecof login` |
| `fix` | Girdi ya da dosya sorunu (gizli anahtar, yasak yol, derleme hatası, geçersiz argüman); düzeltip yeniden deneyin |

### Sır Maskeleme

`tecof theme open vN` bağlantısındaki erişim sırrı ve `tecof tokens create` ile basılan token, makbuzda `--show-secret` olmadan maskelenir (`x-vercel-protection-bypass=***`, `tcfd_***`). Kayıtlı token'lar ve istemci sırları hiçbir çıktıda basılmaz.

---

## Yok Sayma Kuralları

CLI şu yolları hiçbir zaman göndermez. Kurallar gitignore anlamındadır: eğik çizgi içermeyen desen her derinlikte eşleşir, sondaki `/` yalnız klasör demektir.

```text
.git/  .github/  node_modules/  .next/  .vercel/  .turbo/  out/  coverage/  .tecof/
.DS_Store  *.log  .env* (yalnız .env.example gönderilir)  .npmrc
*.pem  *.key  *.p12  *.pfx  id_rsa*  id_ed25519*
```

- Ardından projenin `.gitignore` ve `.tecofignore` dosyaları uygulanır; alt klasörlerdekiler de okunur. Aynı klasörde `.tecofignore`, `.gitignore`'dan sonra okunur ve `!desen` ile `.gitignore`'un dışladığı bir yolu yeniden dahil edebilir. Dışlanan bir klasörün içindeki dosya yeniden dahil edilemez (git kuralı).
- Yukarıdaki sabit liste proje dosyalarıyla yeniden dahil edilemez.
- Sembolik bağlantılar izlenmez; uyarıyla atlanır.
- `.tecofignore` normal bir dosyadır ve depoya gönderilir.

**Silme kuralı:** Push, yerelde olmayan dosyaları depodan siler; ancak sunucu şunları **asla silmez**: `.github/` altındaki her şey, yukarıdaki sabit liste ve depodaki **kök** `.gitignore` / `.tecofignore` desenlerine uyan yollar (push'unuz bu dosyaları değiştiriyorsa yeni desenler de). Sunucu alt klasördeki ignore dosyalarını okumaz: depoda bulunan bir dosyayı yalnız alt klasördeki bir `.gitignore` ile dışlarsanız CLI onu göndermez ve sunucu onu silinmiş sayar. Depoda kalması gereken ama göndermek istemediğiniz yolları kökteki `.tecofignore` dosyasına yazın.

```text
# .tecofignore (proje kökü)
# Depoda kalsın, CLI göndermesin
design/
*.psd
# .gitignore "*.woff2" diyorsa bu dosya yine de gönderilsin
!public/fonts/marka.woff2
```

Push planı her zaman kaç dosyanın yükleneceğini ve silineceğini gösterir: `Plan: 3 yüklenecek, 1 silinecek, 309 aynı.`

---

## Sınırlar

| Kural | Sınır | Aşılınca |
| :--- | :--- | :--- |
| Push başına dosya sayısı | 10.000 | `413 manifest-too-large` |
| Dosya boyutu | 10 MB | `413 file-too-large` |
| Push başına yüklenen toplam | 100 MB | `413 push-too-large` |
| Yol | 300 karakter; ters bölü, denetim karakteri, `.` / `..` bileşeni, mutlak yol yok; büyük/küçük harf çakışması yok | `400 path-forbidden` |
| Push planı | Kullanıcı başına saatte 60 | `429 push-rate-limited` |
| Push planının ömrü | 1 saat (CLI aynı push'u yeniden çalıştırınca kaldığı yerden sürer) | `410 push-plan-expired` |
| Alan başına eşzamanlı commit, canlıya alma, geri alma | 1 (kilit en çok 2 dakika) | `409 space-busy` (`data.retryAfterSec`) |
| Kaynak arşivi (`pull`) | 100 MB | `413 source-too-large` |
| Bulut geliştirme yazımı | İstek başına 100 dosya; yalnız metin dosyaları | `400 too-many-files`, `400 binary-not-supported` |
| Canlıya alma ve geri alma | IP başına 10 dakikada 60 | `429 rate-limited` |
| Bulut oturumu açma | IP başına 10 dakikada 30 | `429 rate-limited` |
| Kaynak indirme | IP başına 10 dakikada 60 | `429 rate-limited` |
| Kapsamlı token | Kullanıcı başına 50 etkin token; saatte 20 basım; token başına en çok 50 alan | `409 token-limit-reached`, `429 rate-limited`, `400 invalid-spaces` |

İstek gövdesi sınırları (API'yi doğrudan kullananlar için): plan 4 MB, yükleme 14 MB (istek başına en çok 200 dosya), commit 1 MB, bulut geliştirme dosyaları 8 MB, canlıya alma, geri alma, oturum ve token istekleri 64 KB. Sınırı aşan istek `413 payload-too-large` döner.

CLI bu sınırları kendisi gözetir: yüklemeleri istek başına en çok 200 dosya ve ≈ 10 MB'lık gruplara böler (10 MB'lık bir dosya tek başına gönderilir), sınırı aşacak bir push'u hiçbir dosya yüklenmeden durdurur. Bulut geliştirmede bir dosya en çok 5 MB olabilir (gövde sınırı 8 MB).

---

# Geliştirici Alanları (Spaces)

> Tema ve uygulama Spaces’leri: numaralı değişmez sürümler, staged ve production hedefleri, anında canlıya alma/geri alma, kimlerin kullanabildiği ve paket gereksinimi.
>
> Kaynak: https://tecof-app-dev.vercel.app/spaces · Bölüm: CLI · Son güncelleme: 2018-10-20

Spaces, özel temaları ve partner uygulamalarını terminalden geliştirip yayınlamanın yoludur. Kodu yerelde (ya da bulutta) geliştirirsiniz; `tecof theme push` yalnız değişen dosyaları yükler ve her yükleme numaralı, değişmez bir **sürüm** olur. Sürümü önizler, hazır olunca yeniden derlemeden saniyeler içinde canlıya alırsınız. Bir sorun çıkarsa önceki canlı sürüme yine saniyeler içinde dönersiniz.

> **Durum (11.10.2026):** Spaces yeni. `tecof spaces`, `tecof theme`, `tecof tokens`, `tecof status`, `tecof doctor`, `tecof setup agent` ve `tecof app push|versions|promote|rollback` komutları `@tecof/cli` **0.2.0** ile gelir; npm'deki ilk sürüm (0.1.0) yalnız uygulama komutlarını içerir. `tecof --version` 0.2.0'dan küçükse `npm install -g @tecof/cli@latest` ile güncelleyin. CLI Node.js 20 ya da üstünü ister.

---

## Kavramlar

| Kavram | Anlamı |
| :--- | :--- |
| Space (alan) | Yayınlanabilir birim: bir mağazanın tema kurulumu ya da bir partner uygulaması. Her alan Tecof'ta bir GitHub deposu ve bir Vercel projesiyle eşleşir |
| Alan kimliği | Tema: `thm_<kurulum kimliği>` (paneldeki `/app/themes/<kimlik>/versions` adresinde görünen kimlik). Uygulama: `app_<uygulama kimliği>` (`tecof.app.json` içindeki `id`) |
| Sürüm (`vN`) | Alan deposundaki bir commit ve onun üretim derlemesi. Numara alan başına artar ve bir kez verilir; aynı numara başka içeriğe gitmez |
| Canlı (live) | Mağazanın ya da uygulamanın alan adlarının o anda gösterdiği sürüm |
| Hedef: staged | Varsayılan push hedefi. Canlı sitenin ortam değişkenleriyle tam bir üretim derlemesi yapılır ama alan adı **atanmaz**; canlı site değişmez. `promote` ile yeniden derlemeden canlıya çıkar |
| Hedef: production | `--prod` ile push. Commit doğrudan `main` dalına gider, derleme bitince canlıya çıkar |
| Taban (base) | Push'unuzun üstüne kurulduğu `main` commit'i. Staged bir sürüm yalnız `main` bu tabandan ileri gitmediyse canlıya alınır |
| Kaynak (source) | Sürümü neyin ürettiği: `cli` (CLI push'u ya da `tecof app deploy`), `ide` (Cloud IDE kaydı), `ai` (AI tema işi), `git` (`main` dalına giden diğer commit'ler) |

---

## Nasıl Çalışır

```text
yerel klasör ──push──▶ v12 (staged, alan adı yok) ──open──▶ korumalı önizleme bağlantısı
                         │
                         └──promote──▶ v12 canlıda (yeniden derleme yok; main → v12 commit'i)
                                          │
                                          └──rollback──▶ önceki canlı sürüm (anında)
```

1. **Push:** CLI projeyi tarar, her dosyanın git blob SHA-1 özetini çıkarır ve yalnız depoda olmayan içerikleri yükler. Yerelde sildiğiniz dosyalar depodan da silinir.
2. **Sürüm:** Tecof değişiklikleri tabanın üstüne commit'ler, commit'i `tecof/v12` etiketiyle işaretler ve üretim derlemesini başlatır. Bu derleme alan adı almaz.
3. **Önizleme:** Derleme hazır olunca `tecof theme open v12` sürümü korumalı bir bağlantıda açar.
4. **Canlıya alma:** `tecof theme promote v12` alan adlarını bu derlemeye çevirir; yeniden derleme yapılmaz. Aynı anda `main` dalı v12'nin commit'ine ileri alınır.
5. **Geri alma:** `tecof theme rollback` alan adlarını bir önceki canlı sürüme döndürür.

Kurallar ve ayrıntılar: [Sürümler, Canlıya Alma ve Geri Alma](https://tecof-app-dev.vercel.app/versions-and-rollback).

---

## main Dalı Kaynak Gerçeği Olarak Kalır

Her alanın deposunda `main` dalı, sitenin kodunun tek doğru kaynağıdır:

- Cloud IDE kayıtları, AI tema işleri ve MCP ile yapılan commit'ler eskisi gibi `main` dalına gider ve derleme bitince canlıya çıkar; `tecof theme push --prod` de aynı yolu izler. Bu yayınlar da sürüm listesinde kendi kaynaklarıyla (`ide`, `ai`, `git`, `cli`) görünür.
- Staged sürüm `main` dalına yazılmaz; commit yalnız `tecof/vN` etiketinde durur. Sürüm canlıya alınınca `main` o commit'e **hızlı ileri** (fast-forward) alınır. Böylece canlı site ile `main` aynı kodu gösterir ve herkes aynı geçmişi görür.
- Canlıya alma yalnız hızlı ileri mümkünse yapılır. Siz push ettikten sonra başka biri (Cloud IDE, AI, başka bir geliştirici ya da CI) `main` dalını değiştirdiyse işlem başlamaz ve `409 base-moved` döner; güncel `main` dalını çekip (`tecof theme pull`) yeniden push edersiniz. Böylece başkasının değişikliği, eski tabana kurulmuş bir sürümle fark edilmeden geri alınmaz.

---

## Önceki Akışla Karşılaştırma

| | Spaces öncesi | Spaces ile |
| :--- | :--- | :--- |
| Tema kodu | Cloud IDE, AI ya da MCP ile; her kayıt `main` dalına gidip canlıya çıkar. CLI'da tema komutu yoktu | Yerelde ya da bulutta geliştirme, `tecof theme push` |
| Yükleme | Uygulamada `tecof app deploy` her seferinde tüm kaynağı arşivleyip yükler | Yalnız değişen dosyalar yüklenir; silmeler de aktarılır |
| Canlıya çıkmadan deneme | Cloud IDE oturum önizlemesi; üretim derlemesi canlıya çıkmadan denenemez | Staged sürüm: üretim derlemesi, alan adı yok, korumalı önizleme |
| Canlıya alma | Derleme bitince kendiliğinden | Staged sürüm tek komutla, yeniden derlemeden |
| Geri alma | Düzeltme commit'i ve yeni derleme | Önceki canlı sürüme saniyeler içinde |
| Sürüm geçmişi | Yok | Her derleme numaralı bir sürüm; panelde **Sürümler** ekranı |
| Otomasyon | — | `--json` makbuzları, ajan modu, kapsamlı CI token'ları |

Önceki yollar çalışmaya devam eder: Cloud IDE ve AI yine `main` dalına yayınlar, `tecof app deploy` hâlâ çalışır.

---

## Kimler Kullanabilir

### Temalar

- Bir mağazanın ekibindeki her kullanıcı o mağazanın tema alanlarını görür. Mağaza ekibine eklenmiş ajans ve partner kullanıcıları da buna dahildir; partner hesabı **gerekmez**.
- Yalnız **özel temalar** yazılabilir: kendi deposu ve Vercel projesi olan, bu mağazaya ait temalar. Özel tema panelde yapay zekâyla üretilir, boş iskeletten açılır ya da bir katalog temasından kopyalanır.
- Erişim her istekte yeniden doğrulanır: ekipten çıkarılan kullanıcının CLI'ı o mağazanın alanlarına hemen erişemez.

### Uygulamalar

- Aktif bir partner üyeliği gerekir. Partner hesabınızın, Tecof barındırmasını kullanan (`hosting: "tecof"`) platform uygulamaları alan olarak listelenir.
- Kendi sunucunuzda barındırılan (`hosting: "external"`) uygulamalar alan değildir; dağıtımları sizdedir.
- Partner üyeliğiniz biterse CLI oturumunuz tema alanlarında çalışmaya devam eder, uygulama uçları `403 developer-not-partner` döner.

### Salt Okunur Alanlar

`tecof spaces ls` her alanın yazılabilir olup olmadığını gösterir. Salt okunur alanda sürüm listesi, günlükler ve önizleme okunabilir; push, canlıya alma, geri alma, yerel geliştirme değişkenleri ve bulut geliştirme `403 space-read-only` ile reddedilir.

| `readOnlyReason` | Anlamı | Ne yapılır |
| :--- | :--- | :--- |
| `catalog-theme` | Katalog (paylaşımlı) teması; aynı kod yüzlerce mağazada çalışır. Kaynak kodu da indirilemez (`403 space-source-forbidden`) | Temayı özel temaya kopyalayın (aşağıda) |
| `shared-theme` | Özel tema başka bir mağazaya ait | Temanın ait olduğu mağazanın alanını kullanın |
| `no-repo` | Temanın deposu henüz yok | Tema kurulumu tamamlanınca alan yazılabilir olur |
| `no-project` | Temanın Vercel projesi henüz yok | Tema kurulumu tamamlanınca alan yazılabilir olur |
| `external-hosting` | Uygulama kendi sunucunuzda barındırılıyor | Kendi dağıtımınızı kullanın ya da Tecof barındırmasına geçin |

**Katalog temasını özel temaya kopyalama:** Panelde temanın **Sürümler** ekranındaki **Özel temaya kopyala** düğmesi Tecof asistanını bu istekle açar; asistan işlemden önce onayınızı ister ve kullanılacak krediyi gösterir. Kopya hazır olunca etkinleşir, o zamana kadar mevcut temanız yayında kalır. Uzak MCP sunucusunda aynı işi `fork_theme_to_custom` aracı yapar ([MCP](https://tecof-app-dev.vercel.app/mcp)). Kopyanın kendi deposu, Vercel projesi ve sürüm geçmişi olur.

---

## Paket Gereksinimi

Tema alanına yazan işlemler — push, canlıya alma, geri alma ve bulut geliştirme — mağaza paketinde **Özel Temalar** ve **Kod Erişimi** özelliklerinin ve geliştirme modunun (Cloud IDE) açık olmasını ister. Bu, Cloud IDE'nin istediği koşulla aynıdır: hiçbir paket CLI'dan Cloud IDE'nin vermediği bir kod yetkisi almaz.

Okuma işlemleri pakete bağlı değildir: alan ve sürüm listesi, günlükler, önizleme bağlantısı, kaynak indirme (`tecof theme pull`) ve yerel geliştirme (`tecof theme dev`).

| Hata | Anlamı |
| :--- | :--- |
| `403 plan-feature-unavailable` | Pakette gereken özellik yok; `data.feature` eksik özelliği, `data.currentPlan` mevcut paketi verir |
| `403 plan-module-locked` | Geliştirme modu pakete dahil değil; `data.requiredPlan` gereken paketi verir |

Uygulama alanları mağaza paketine bağlı değildir.

---

## Tek Hesap, Kullanıcıya Bağlı Oturum

`tecof login` ile açılan oturum kişisel hesabınıza bağlıdır, bir partner hesabına değil. Aynı oturumla üyesi olduğunuz mağazaların özel temalarında ve partner hesabınızın uygulamalarında çalışırsınız. Cihaz oturumu 30 gün geçerlidir ve 14 gün kullanılmazsa düşer.

CI için hesabınızın tüm erişimini taşıyan cihaz oturumu yerine yalnız gereken alana ve yetkiye sınırlı bir **kapsamlı token** kullanın: [Güvenlik ve CI](https://tecof-app-dev.vercel.app/dev-security).

---

## Bu Bölümün Sayfaları

| Sayfa | İçerik |
| :--- | :--- |
| [Tema Geliştirme: Hızlı Başlangıç](https://tecof-app-dev.vercel.app/theme-quickstart) | Kurulum, giriş, kodu indirme, yerel ve bulut geliştirme, push, önizleme, canlıya alma, geri alma |
| [Sürümler, Canlıya Alma ve Geri Alma](https://tecof-app-dev.vercel.app/versions-and-rollback) | Sürüm durumları, staged ve production, önizleme bağlantıları, canlıya alma ve geri alma kuralları, panel ekranı |
| [Güvenlik ve CI](https://tecof-app-dev.vercel.app/dev-security) | Kimlik bilgisi saklama, token ömürleri, CI token'ları, GitHub Actions, gizli anahtar taraması, ajan modu |
| [CLI Başvurusu](https://tecof-app-dev.vercel.app/cli-reference) | Tüm komutlar ve seçenekler, ortam değişkenleri, çıkış kodları, JSON makbuzları, yok sayma kuralları, sınırlar |
| [Hızlı Başlangıç: Tecof CLI](https://tecof-app-dev.vercel.app/app-quickstart) | Uygulamalar için `tecof app` akışı ve `tecof app push` ile sürümler |

---

# Sürümler, Canlıya Alma ve Geri Alma

> Sürüm durumları, aktivasyon sonuçları, korumalı önizleme bağlantıları, canlıya alma ve geri alma kuralları, panel Sürümler ekranı ve derleme günlükleri.
>
> Kaynak: https://tecof-app-dev.vercel.app/versions-and-rollback · Bölüm: CLI · Son güncelleme: 2018-10-20

Her alan, kodunun her üretim derlemesini numaralı bir sürüm olarak tutar. Bu sayfa sürümün yaşam döngüsünü, staged ve production hedeflerini, önizleme bağlantılarını, canlıya alma ve geri alma kurallarını ve paneldeki **Sürümler** ekranını anlatır. Örnekler tema komutlarıyla verilmiştir; uygulamalarda aynı işlemler `tecof app push|versions|promote|rollback` ile yapılır.

> Sürümler alanın **kodunu** kapsar. Sayfa içerikleri, ürünler, CMS kayıtları ve mağaza ayarları sürümlenmez; canlıya alma ve geri alma onları değiştirmez.

---

## Sürüm Nedir

- Bir sürüm, alan deposundaki bir commit ve onun üretim derlemesidir. Numara (`v1`, `v2`, …) alan başına artar ve bir kez verilir.
- CLI push'ları dışında `main` dalına giden her yayın da sürüm olur: Cloud IDE kayıtları (`ide`), AI tema işleri (`ai`), `tecof app deploy` (`cli`) ve diğer commit'ler (`git`). Önizleme (production olmayan) derlemeleri sürüm değildir.
- Staged bir sürüm canlıya alındıktan sonra Vercel'in `main` dalı için yaptığı ikinci derleme aynı sürüme bağlanır; yeni numara açılmaz. Elle yeniden dağıtılan bir commit de mevcut sürümüne bağlanır.
- Sürüme `v12`, `12` ya da sürüm kimliğiyle başvurulur.
- `source` alanını okuyan araçlar tanımadıkları bir değeri genel bir kaynak olarak ele almalıdır; değer listesi genişleyebilir.

---

## Durumlar

| Durum | Panelde | Anlamı |
| :--- | :--- | :--- |
| `uploading` | Yükleniyor | Commit kuruluyor |
| `queued` | Sırada | Derleme sırada |
| `building` | Derleniyor | Derleme sürüyor |
| `ready` | Hazır | Derleme başarılı; önizlenebilir ve canlıya alınabilir |
| `error` | Hata | Derleme ya da commit başarısız; `errorMessage` ve `tecof theme logs vN` |
| `canceled` | İptal edildi | Derleme iptal edildi ya da `--prod` push'ta `main` aynı anda ilerlediği için commit `main` dalına yazılamadı (`errorMessage: "base-moved"`) |

```text
push ─▶ uploading ─▶ queued ─▶ building ─┬─▶ ready ─┬─▶ staged:     promote ile canlıya çıkar
                                         │          └─▶ production: derleme bitince canlıya çıkar
                                         └─▶ error | canceled
```

CLI push sırasında sürümü `ready`, `error` ya da `canceled` olana kadar yoklar. Sonradan izlemek için:

```bash
tecof theme versions          # liste (varsayılan 20, --limit ile en çok 100)
tecof theme versions v12      # tek sürüm; durum, commit, taban, adres, zamanlar
```

---

## Staged ve Production

| | Staged (varsayılan) | Production (`--prod`) |
| :--- | :--- | :--- |
| Komut | `tecof theme push` | `tecof theme push --prod` |
| `main` dalı | Değişmez; commit `tecof/vN` etiketinde durur | Commit `main` dalına hızlı ileri yazılır |
| Derleme | Canlı sitenin ortam değişkenleriyle tam üretim derlemesi; alan adı atanmaz | `main` dalının üretim derlemesi |
| Canlıya çıkış | `promote` ile, yeniden derlemeden | Derleme bitince kendiliğinden |
| `main` ilerlemişse | Push başarılı olur; canlıya alma `409 base-moved` alır | Push `409 base-moved` alır, sürüm açılmaz |
| Derleme sayısı | İki: staged derleme ve canlıya almadan sonra `main` derlemesi | Bir |
| Onay | Push onay istemez; `promote` onay ister | Push onay ister |

Uygulamalarda push her zaman `main` dalının o anki hâlinin üstüne kurulur ve klasör istenen son durum sayılır; temalardaki gibi yerel taban tutulmaz.

---

## Aktivasyon

Push, sürüm ayrıntısı, canlıya alma ve geri alma yanıtları sürümün canlıya göre konumunu `activation.outcome` ile verir:

| Değer | Anlamı |
| :--- | :--- |
| `activated` | Sürüm canlıda |
| `staged` | Hazır, hiç canlıya alınmadı; `promote` bekliyor |
| `pending` | Derleme sürüyor ya da canlıya alma / geri alma Vercel'de sırada. Sürüm okundukça sonuçlanır |
| `rolled-back` | Geri alma yanıtında: geri alma yapıldı, alan geri alınmış durumda. Sürüm ayrıntısında: sürüm hazır ama alan geri alınmış olduğu için canlıya çıkmadı |
| `superseded` | Başka bir sürüm canlıda |

Başarısız ya da iptal edilmiş sürümde `outcome` `null` olur. Nesne ayrıca `liveVersion`, `rolledBack` ve `diagnostics` alanlarını taşır. Staged bir derlemenin beklenmedik şekilde alan adı alması `diagnostics` içinde `unexpected-activation` olarak bildirilir.

---

## Önizleme Bağlantıları

`tecof theme open vN` ve paneldeki **Önizle** düğmesi hazır bir sürümün kendi adresini açar. Sürüm adresleri Vercel dağıtım adresleridir (`*.vercel.app`).

- Alanın Vercel projesinde dağıtım koruması açıksa sürüm adresleri kilitlidir. Tecof proje başına bir erişim sırrı üretir ve bağlantıya ekler:

  ```text
  https://<dağıtım>.vercel.app/?x-vercel-protection-bypass=<sır>&x-vercel-set-bypass-cookie=true
  ```

  Bağlantı tarayıcıya bir erişim çerezi bırakır; aynı adreste sonraki gezinmeler çerezle açılır.
- **Bağlantı sır içerir.** Sır proje geneli olduğu için tam bağlantıyı bilen herkes yalnız o sürümü değil, alanın bütün korumalı sürüm adreslerini açabilir. Bağlantının son kullanma zamanı yoktur (`expiresAt: null`). Yalnız yetkili kişilerle paylaşın.
- CLI sırrı terminalde ve `--json` makbuzunda maskeler (`x-vercel-protection-bypass=***`); tam bağlantıyı `--show-secret` basar. Tarayıcıda açılan bağlantı her zaman tamdır.
- Panel bağlantıyı yalnız açtığı yeni sekmeye verir; panelin kendisinde saklamaz ve göstermez.
- Koruma kapalıysa bağlantı düz dağıtım adresidir ve yanıtta `protected: false` olur.
- Bağlantıyı alana okuma erişimi olan herkes alabilir; `read` yetkili CI token'ı dahil.

---

## Canlıya Alma

`tecof theme promote vN` · panelde **Canlıya al**

1. Sürüm `ready` olmalıdır; değilse `409 version-not-ready`.
2. Yeniden derleme yapılmaz; alan adları saniyeler içinde sürümü gösterir. Vercel isteği sıraya alırsa sonuç `pending` olur ve sürüm okundukça (`tecof theme versions vN`) sonuçlanır.
3. **Hiç canlı olmamış staged sürüm:** `main` dalı sürümün commit'ine hızlı ileri alınır. Bu yalnız `main` hâlâ sürümün tabanındaysa yapılır; değilse işlem hiç başlamaz ve `409 base-moved` döner (`data.mainSha`, `data.baseSha`). Canlıya alma sürerken `main` ilerlerse (yarış) Tecof önceki canlı derlemeye döner ve yine `409 base-moved` döner (`data.reverted: true`).
4. **Bilinen bedel:** hızlı ileri alma, Vercel'in `main` dalındaki aynı commit'i bir kez daha derlemesine yol açar. İçerik aynıdır, canlı site etkilenmez ve ikinci derleme aynı sürüme bağlanır; yalnız derleme süresi harcanır. Önizlemeye ihtiyacınız olmayan değişikliklerde `--prod` tek derlemeyle yayınlar.
5. **Zaten `main` dalında olan sürüm** (production hedefli, ör. geri almadan sonra ileri alma): `main` değişmez ve `base-moved` denetimi yapılmaz.
6. **Daha önce canlıda olmuş sürüm:** Vercel'in geri alma mekanizmasıyla canlıya alınır; alan geri alınmış durumda kalır ([aşağıda](#geri-almadan-sonra-yayinlar)).
7. Zaten canlı olan sürümü canlıya almak bir şey değiştirmez (`activation.noop: true`).
8. Alan başına aynı anda tek commit, canlıya alma ya da geri alma çalışır; diğeri `409 space-busy` alır (`data.retryAfterSec`).

---

## Geri Alma

`tecof theme rollback [vN]` · panelde **Geri al**

1. Yalnız daha önce canlıda olmuş ve `ready` durumdaki bir sürüme geri alınabilir. Hiç canlı olmamış bir sürüm için `409 rollback-target-invalid` (`data.reason: "never-live"`) döner; o sürümü `promote` ile canlıya alın.
2. Sürüm verilmezse şu anki canlı sürüm dışında en son canlıda olmuş sürüme dönülür. Böyle bir sürüm yoksa `409 rollback-target-invalid` (`data.reason: "no-previous-version"`).
3. Geçiş anlıktır ve yeniden derleme yapılmaz. `main` dalına dokunulmaz: daha yeni değişiklikler `main` dalında kalır ama canlıda olmaz.
4. Zaten canlı olan sürüme geri almak bir şey değiştirmez.

### Geri Almadan Sonra Yayınlar

Geri almadan sonra Vercel, `main` dalının yeni derlemelerine alan adlarını kendiliğinden atamayı durdurur. Tecof alanı **geri alınmış** olarak işaretler: `rolledBack: true`, `tecof spaces ls` çıktısında `rolled-back` sütunu, panelde "Canlı site vN sürümüne geri alındı" bandı.

Tecof'ta `main` dalına giden her yayın bir yayın niyetidir. Bu yüzden alan geri alınmışken staged olmayan yeni bir üretim derlemesi hazır olduğunda — Cloud IDE kaydı, AI tema işi, `tecof theme push --prod`, `tecof app push --prod`, `tecof app deploy` ya da `main` dalına giden başka bir commit — Tecof o derlemeyi kendiliğinden canlıya alır, geri alınmış işaretini kaldırır ve mağazanın etkinlik kaydına "geri alma yeni yayınla kaldırıldı" kaydı düşer. Böylece Cloud IDE ya da AI ile yayın yapan biri "yayınladım ama canlıda değil" durumunda kalmaz.

| Olay | Sonuç |
| :--- | :--- |
| `main` dalına yeni yayın (Cloud IDE, AI, `--prod`, `tecof app deploy`, diğer commit'ler) | Derleme bitince Tecof canlıya alır; geri alınmış işareti kalkar |
| Staged push | Canlıya çıkmaz; geri alınmış durum sürer |
| Hiç canlı olmamış bir sürümü canlıya alma | Sürüm canlıya çıkar; geri alınmış işareti kalkar |
| Daha önce canlıda olmuş bir sürümü canlıya alma | Sürüm canlıya çıkar; alan geri alınmış durumda kalır. Sonraki `main` yayınları yine yukarıdaki kuralla canlıya alınır |

> Otomatik canlıya alma anında alanda başka bir canlıya alma ya da geri alma sürüyorsa otomatik adım atlanır ve yeni sürüm `ready` olarak kalır. Bu durumda sürümü panelden ya da `tecof theme promote vN` ile canlıya alın.

---

## Paneldeki Sürümler Ekranı

- **Tema:** **Temalar** → tema kartındaki ⋯ menüsü → **Sürümler** (`https://app.tecof.com/app/themes/<kurulum kimliği>/versions`). Cloud IDE araç çubuğundaki **Sürümler** bağlantısı aynı ekranı yeni sekmede açar.
- **Uygulama:** geliştirici portalında uygulamanın **Sürümler** sekmesi (`https://app.tecof.com/partner/apps/<uygulama kimliği>?tab=versions`). Yalnız Tecof barındırmalı uygulamalarda; eski **Dağıtımlar** sekmesi (`tecof app deploy`) olduğu gibi durur.

| Bölüm | İçerik |
| :--- | :--- |
| Canlı özet | Canlı sürüm, canlıya alınma zamanı, alan adı ve hızlı "vM sürümüne geri al" |
| Sürüm listesi | Numara, **Canlı** rozeti, durum, hedef (**Hazırlık** = staged, **Üretim** = production), kaynak, mesaj, kısa commit, yazar, zaman, yüklenen ve silinen dosya sayısı, hata metni |
| Eylemler | **Önizle**, **Canlıya al**, **Geri al**, **Günlük**; canlı sürümde **Canlı siteyi aç** |
| Yenile | Canlı sürümü Vercel'den yeniden okur |
| Geri alınmış bant | "Canlı site vN sürümüne geri alındı" ve en yeni hazır sürüm için **İleri al (vM)** |
| Alan kimliği | CLI'da `--space` ile kullanılan kimlik ve kopyalama düğmesi |
| Boş durum | İlk sürüm için CLI hızlı başlangıç komutları |

- Canlıya alma ve geri alma her zaman onay penceresi açar; sonuç sunucunun döndüğü aktivasyonla bildirilir.
- Süren bir derleme varken liste kendiliğinden tazelenir; derleme bitince bildirim gösterilir.
- Mağaza paketi özel temaları kapsamıyorsa liste ve önizleme açık kalır, canlıya alma ve geri alma kapanır.
- Katalog temalarında ekran salt okunurdur ve **Özel temaya kopyala** önerir ([Salt okunur alanlar](https://tecof-app-dev.vercel.app/spaces#salt-okunur-alanlar)).

---

## Derleme Günlükleri

`tecof theme logs vN` (uygulamada `tecof app logs vN`) ve paneldeki **Günlük** düğmesi sürümün derleme günlüğünün son 300 satırını gösterir. Tecof token biçimleri günlükte maskelenir. Derleme başarısız olursa `tecof theme push` son 40 satırı kendisi basar.

---

## Etkinlik Kaydı

Tema alanlarında push, canlıya alma, geri alma ve otomatik canlıya alma mağazanın etkinlik kaydına kod kategorisinde yazılır: işlemi yapan kullanıcı, kullanılan token, sürüm ve sonuç.

---

## İlgili Sayfalar

- [Tema Geliştirme: Hızlı Başlangıç](https://tecof-app-dev.vercel.app/theme-quickstart)
- [Güvenlik ve CI](https://tecof-app-dev.vercel.app/dev-security)
- [CLI Başvurusu](https://tecof-app-dev.vercel.app/cli-reference)

---

# Güvenlik ve CI

> CLI kimlik bilgisi deposu, token ömürleri, kapsamlı CI token’ları, GitHub Actions örneği, ajan modu, gizli anahtar taraması ve korunan yollar.
>
> Kaynak: https://tecof-app-dev.vercel.app/dev-security · Bölüm: CLI · Son güncelleme: 2018-10-20

Bu sayfa CLI'ın kimlik bilgilerini nasıl sakladığını, token türlerini ve ömürlerini, CI için kapsamlı token'ları, bir GitHub Actions örneğini, ajan modunu, yüklemedeki gizli anahtar taramasını, korunan yolları ve kodlama ajanlarıyla çalışmayı anlatır.

---

## Kimlik Bilgisi Deposu

`tecof login` token'ı işletim sisteminin anahtarlığına yazar:

| Platform | Depo |
| :--- | :--- |
| macOS | Anahtar Zinciri; servis adı **Tecof CLI**, hesap `<profil>@<API host>` (ör. `default@api.tecof.com`) |
| Linux / BSD | Secret Service (`secret-tool`; ör. GNOME Keyring) |
| Diğerleri ya da anahtarlık yoksa | `~/.config/tecof/credentials.json` (dosya `0600`, klasör `0700`) |

- Anahtarlık kilitli ya da kullanılamıyorsa token dosyaya yazılır ve CLI uyarır; anahtarlık sonradan erişilebilir olunca kopya oraya taşınır.
- `TECOF_CREDENTIAL_STORE=keyring` anahtarlığı zorunlu kılar (yoksa hata verir), `plaintext` dosyayı seçer. `CI` ya da `TECOF_CONFIG_DIR` tanımlıysa varsayılan dosyadır.
- `TECOF_TOKEN` tanımlıysa kayıtlı girişin yerine her zaman o kullanılır.
- Token'lar API adresine bağlıdır: `--api` ile başka bir sunucuya bağlandığınızda kayıtlı token oraya gönderilmez. `TECOF_PROFILE` aynı makinede birden çok hesabı ayırır.
- Sır komut satırı argümanı olarak geçirilmez (süreç listesinde görünmez); anahtarlığa yazılan değer geri okunarak doğrulanır.
- `~/.config/tecof/config.json` yalnız üst bilgi tutar: API ve panel adresi, token bitişi, kullanıcı ve partner. Eski CLI sürümlerinin bu dosyaya yazdığı token ilk kullanımda anahtarlığa taşınır ve dosyadan silinir.
- Token'lar, istemci sırları ve önizleme sırları hiçbir çıktıda ve günlükte basılmaz. Tek istisna, yeni oluşturulan CI token'ının insan çıktısında bir kez gösterilmesidir.

---

## Token Türleri ve Ömürleri

| Tür | Nasıl alınır | Yetki | Ömür |
| :--- | :--- | :--- | :--- |
| Cihaz oturumu (`tcfd_…`) | `tecof login` ve panelde onay | Hesabınızın erişimi: üyesi olduğunuz mağazaların tema alanları, partner hesabınızın uygulamaları, bulut geliştirme, token yönetimi | 30 gün; 14 gün kullanılmazsa düşer |
| Kapsamlı CI token'ı (`tcfd_…`) | Panelde `/cli?tab=tokens` ya da `tecof tokens create` | Seçilen yetki seti ve alanlarla sınırlı | 1–365 gün (varsayılan 90); kullanılmama süresi yoktur |

| Yetki seti | Panelde | İzin verir |
| :--- | :--- | :--- |
| `read` | Salt okuma | Alan ve sürüm listesi, sürüm ayrıntısı, günlükler, önizleme bağlantısı, kaynak indirme, yerel geliştirme değişkenleri |
| `deploy` | Dağıtım | `read` ve push, canlıya alma, geri alma |

Kapsamlı token'ın yapamadıkları:

| İşlem | Yanıt |
| :--- | :--- |
| Bulut geliştirme (`tecof theme dev --cloud`) | `403 token-scope-insufficient` (`data.required: "full"`) |
| `read` yetkisiyle push, canlıya alma, geri alma | `403 token-scope-insufficient` (`data.required: "deploy"`) |
| Token'ın alan listesinde olmayan bir alan | `403 token-space-forbidden` |
| Uygulama yönetimi: `tecof app init`, `link`, `info`, `config push`, `dev`, `deploy`, `deployments`, `secret rotate` | `403 scoped-token-forbidden` |
| Token listeleme, yeni token basma, başka bir token'ı iptal etme, cihaz girişi onaylama | `403 scoped-token-forbidden` |

`tecof app push`, `app versions`, `app promote`, `app rollback` ve `app logs vN` alan uçlarını kullandığı için kapsamlı token'la çalışır.

Ortak kurallar:

- Erişim her istekte yeniden doğrulanır. Mağaza ekibinden çıkarılan ya da partner üyeliği biten kullanıcının token'ları ilgili alanlarda hemen çalışmaz; hesabı pasifleşen kullanıcının token'ları `401 token-revoked` döner.
- Kendi erişiminizden geniş bir token basılamaz: listedeki her alana basım anında erişiminiz olmalıdır (`403 space-not-allowed`).
- Alan listesi boş bırakılırsa token, erişebildiğiniz **tüm** alanlarda — sonradan erişim kazandıklarınız dahil — geçerli olur. CI için yalnız gereken alanı seçin.
- Token değeri yalnız oluşturulurken bir kez gösterilir; Tecof yalnız özetini saklar. Kaybederseniz iptal edip yenisini oluşturun.
- Süresi dolan token `401 token-expired` döner (`data.reason`: `expired` ya da cihaz oturumunda `idle`); CLI `tecof login` önerir.
- Kullanıcı başına en çok 50 etkin kapsamlı token bulunabilir (`409 token-limit-reached`) ve saatte en çok 20 token basılabilir.

> **Mağaza sahipleri için:** Tema alanlarına erişim mağaza ekibi üyeliğine bağlıdır; ekip rolü ayrıca bir kısıtlama getirmez. Kod üzerinde çalışmaması gereken kişileri ekipte tutmayın. Yazma işlemleri ayrıca paketin özel tema ve kod erişimi içermesini ister ([Paket gereksinimi](https://tecof-app-dev.vercel.app/spaces#paket-gereksinimi)).

---

## CI Token'ı Oluşturma

### Panelden

1. `https://app.tecof.com/cli?tab=tokens` (**Geliştirici erişimi → CLI anahtarları**) sayfasını açın ve **CI anahtarı oluştur**'a tıklayın.
2. **Ad:** token'ın nerede kullanıldığını anlatan bir ad (en çok 60 karakter), ör. "GitHub Actions · deploy".
3. **Yetki seti:** **Dağıtım** (`deploy`) ya da **Salt okuma** (`read`). Form **Dağıtım** seçili açılır.
4. **Alanlar:** yalnız gereken alanları seçin; boş bırakırsanız tüm alanlar geçerli olur. Dağıtım setinde salt okunur alanlar (ör. katalog temaları) seçilemez.
5. **Geçerlilik:** 1–365 gün (varsayılan 90).
6. Değer bir kez gösterilir: kopyalayıp CI ortamınızın gizli değişkenine (`TECOF_TOKEN`) kaydedin. Koda ya da depoya yazmayın.

Aynı sayfada onayladığınız cihazları ve CI token'larını görür, kullanılmayanları **İptal et** ile kapatırsınız.

### CLI ile

```bash
tecof tokens create --name github-actions --preset deploy --space thm_66f1a2b3c4d5e6f7a8b9c0d1 --expires 90
```

```text
✔ Token oluşturuldu: github-actions (deploy; thm_66f1a2b3c4d5e6f7a8b9c0d1)

  tcfd_…

! Bu değer yalnız bir kez gösterilir; şimdi güvenli bir yere (CI gizli değişkeni) kopyalayın.
CI'da: TECOF_TOKEN=<değer> tecof theme push --json
```

> **Dikkat:** `tecof tokens create` `--preset` verilmezse en dar yetkiyi (`read`) basar; push ve canlıya alma için `--preset deploy` verin. Panel formu ise **Dağıtım** seçili açılır.

- `--space` tekrarlanabilir ya da virgülle ayrılmış liste alır.
- `--json` ile token makbuzda maskelenir (`tcfd_***`) ve bir daha gösterilmez; değeri makbuzdan okumanız gerekiyorsa `--show-secret` ekleyin.
- `tecof tokens ls` token'ları listeler, `tecof tokens revoke <id>` iptal eder (yıkıcı işlem, onay ister).

---

## GitHub Actions Örneği

Senaryo: tema kodu kendi GitHub deponuzda duruyor (`tecof theme init` ile açılmış ve `.tecof/space.json` commit'lenmiş bir klasör). `main` dalına her push'ta staged bir sürüm açılır; sürüm, onaylayıcı tanımlanabilen bir ortamda canlıya alınır. `TECOF_TOKEN` deponun gizli değişkenidir: yalnız bu alana sınırlı, `deploy` yetkili, süreli bir kapsamlı token.

```yaml
name: Tecof tema yayını

on:
  push:
    branches: [main]

concurrency:
  group: tecof-theme
  cancel-in-progress: false

jobs:
  stage:
    runs-on: ubuntu-latest
    outputs:
      ref: ${{ steps.push.outputs.ref }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm install -g @tecof/cli
      - id: push
        name: Staged sürüm
        env:
          TECOF_TOKEN: ${{ secrets.TECOF_TOKEN }}
        run: |
          tecof theme push --json --force > receipt.json
          echo "ref=$(jq -r '.version.ref // empty' receipt.json)" >> "$GITHUB_OUTPUT"

  promote:
    needs: stage
    if: needs.stage.outputs.ref != ''
    runs-on: ubuntu-latest
    environment: production
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm install -g @tecof/cli
      - name: Canlıya al
        env:
          TECOF_TOKEN: ${{ secrets.TECOF_TOKEN }}
        run: tecof theme promote "${{ needs.stage.outputs.ref }}" --yes --json
```

- **Ajan modu:** CI'da stdin bir terminal değildir; CLI soru sormaz ve canlıya alma yalnız `--yes` ile çalışır.
- **`--force`:** CI'da yerel taban (`.tecof/state.json`) yoktur ve push, Tecof'taki `main` dalının o anki hâlinin üstüne kurulur. Deponuzdan sildiğiniz dosyaların Tecof'ta da silinmesi için `--force` gerekir; yoksa push durur (çıkış 4, `unknown-base`). Bu akışta deponuz istenen son durumdur: Tecof tarafında (Cloud IDE, AI) yapılmış ve deponuzda olmayan değişiklikler bu push'la geri alınır. Tecof'ta değişiklik yapan başka kişiler varsa o değişiklikleri önce deponuza alın.
- **Makbuz:** `--json` stdout'a yalnız başarı makbuzunu yazar; hata makbuzu stderr'e gider ve adım başarısız olur. Değişiklik yoksa (`noop`) `ref` boş kalır ve canlıya alma işi atlanır. Sürüm mesajı deponuzun son commit başlığından alınır.
- **Onay:** GitHub'da `production` ortamına onaylayıcı tanımlarsanız canlıya alma onay bekler; bu sırada staged sürümü panelde **Önizle** ile inceleyebilirsiniz. Canlıya alma işi alanı `.tecof/space.json` dosyasından bulduğu için depoyu checkout eder.
- **Çakışma:** Bu arada `main` değiştiyse canlıya alma `409 base-moved` ile durur (çıkış 4); yeni bir push başlatın. `concurrency` aynı alana eşzamanlı push'ları sıraya koyar (`409 space-busy` önlenir).
- **Uzun derlemeler:** `--json` modu derleme boyunca çıktı basmaz (varsayılan bekleme 900 saniye). Çıktısızlık süresi sınırlı CI sistemlerinde `TECOF_DEBUG=1` ilerlemeyi stderr'e yazar.

**Uygulama için** `tecof theme push` yerine `tecof app push --json`, `tecof theme promote` yerine `tecof app promote` kullanın. Alan kimliği `tecof.app.json` dosyasından gelir. Uygulama push'u her zaman `main` üstüne kurulup klasörü istenen durum saydığı için `--force` gerekmez (komut bu seçeneği kabul etmez). `tecof.app.json` değişiklikleri `tecof app config push` ile ayrıca gönderilir; bu komut kapsamlı token'la çalışmaz.

---

## Ajan Modu

`TECOF_AGENT=1` tanımlıysa ya da stdin bir terminal değilse (boru, CI, kodlama ajanı) CLI ajan modunda çalışır: soru sormaz, tarayıcı açmaz. `--json` modunda da soru sorulmaz.

Yıkıcı işlemler — `promote`, `rollback`, `push --prod`, `tokens revoke` — bu modda `--yes` ya da `TECOF_AGENT_ALLOW_DESTRUCTIVE=1` ister. Onay yoksa API'ye hiçbir istek gitmeden çıkış kodu **3** ile durur:

```text
$ tecof theme promote v12
✖ Bu işlem yıkıcı ve onay gerektiriyor (ajan/etkileşimsiz mod).
  Kullanıcı onayladıysa yeniden çalıştırın: tecof theme promote v12 --yes (ya da TECOF_AGENT_ALLOW_DESTRUCTIVE=1).
```

```json
{
  "ok": false,
  "command": "theme promote",
  "space": "thm_66f1a2b3c4d5e6f7a8b9c0d1",
  "error": {
    "code": "confirmation-required",
    "message": "Bu işlem yıkıcı ve onay gerektiriyor (ajan/etkileşimsiz mod)."
  },
  "next": { "action": "confirm", "command": "tecof theme promote v12 --yes" },
  "diagnostics": []
}
```

Ajanın doğru davranışı: kullanıcıya ne yapılacağını anlatıp onay istemek, onay gelirse `next.command` komutunu çalıştırmak. Kodlama ajanlarının ortamında `TECOF_AGENT_ALLOW_DESTRUCTIVE=1` tanımlamayın; bu, canlıya alma ve geri almayı kullanıcıya sormadan açar. Etkileşimli terminalde aynı işlemler `(e/H)` sorusuyla onay ister.

---

## Gizli Anahtar Taraması

Push'ta yüklenen her metin dosyası (2 MB'a kadar) sunucuda taranır. Engelleyen bir bulgu varsa o yükleme isteğindeki **hiçbir dosya** depoya yazılmaz, sürüm açılmaz ve push çıkış kodu 1 ile durur. İstisna mekanizması yoktur.

| Tür (`kind`) | Ne yakalanır |
| :--- | :--- |
| `tecof-secret` | Tecof'un gizli anahtar biçimleri: istemci sırrı, kurulum token'ı, CLI token'ı, kişisel erişim anahtarı, OAuth token ve kodları. Herkese açık istemci kimliği bulgu sayılmaz |
| `github-token` | GitHub erişim token'ları |
| `aws-access-key` | AWS erişim anahtarı kimlikleri |
| `stripe-live-key` | Stripe canlı gizli anahtarları |
| `slack-token` | Slack token'ları |
| `private-key` | PEM biçimli özel anahtar blokları |

Bulgular yol, satır ve türle bildirilir; **değer hiçbir zaman gösterilmez**:

```text
✖ Yüklenen dosyalarda 1 gizli anahtar bulundu; push durduruldu (değerler gösterilmez):
  lib/keys.ts:3 aws-access-key
  Sırları koddan çıkarın (ortam değişkeni kullanın) ve sızmışsa döndürün. İstisna mekanizması yok.
```

`--json` makbuzunda her bulgu `diagnostics` içinde `{ "level": "error", "code": "secret-detected", "path", "line", "kind" }` olarak yer alır; `next.action` `fix` olur.

- İkili dosyalar ve 2 MB'tan büyük dosyalar taranmaz.
- Mağazanın vitrin anahtarının (`NEXT_PUBLIC_MERCHANT_SECRET_KEY` değeri) bir tema dosyasına gömülmesi push'u engellemez — bu değer zaten tarayıcıya giden genel bir anahtardır — ama sunucu uyarı olarak kaydeder. Değeri koda yazmak yerine ortam değişkeninden okuyun.
- Sızan bir anahtarı silmek yetmez: anahtarı ilgili serviste döndürün (yenileyin).

---

## Gönderilmeyen ve Reddedilen Yollar

CLI şu yolları hiçbir zaman göndermez: `.git/`, `.github/`, `node_modules/`, `.next/`, `.vercel/`, `.turbo/`, `out/`, `coverage/`, `.tecof/`, `.DS_Store`, `*.log`, `.env*` (`.env.example` hariç), `.npmrc`, `*.pem`, `*.key`, `*.p12`, `*.pfx`, `id_rsa*`, `id_ed25519*`. Projenin `.gitignore` ve `.tecofignore` dosyaları da uygulanır ([Yok sayma kuralları](https://tecof-app-dev.vercel.app/cli-reference#yok-sayma-kurallari)).

Sunucu, CLI dışından gelen istekler dahil, şu yolları `400 path-forbidden` ile reddeder (`data.reason`):

| Neden | Yol |
| :--- | :--- |
| `git-dir` | Herhangi bir derinlikte `.git` klasörü |
| `github-dir` | Kökte `.github/`; iş akışları Tecof'un GitHub organizasyonunda çalışacağı için |
| `vercel-dir` | Herhangi bir derinlikte `.vercel` klasörü |
| `env-file` | `.env` ile başlayan dosyalar (`.env.example` hariç) |
| `npmrc` | `.npmrc` |
| `key-file` | `*.pem`, `*.key`, `*.p12`, `*.pfx`, `id_rsa*`, `id_ed25519*` |
| `absolute`, `dot-segment`, `backslash`, `control-char`, `too-long` | Mutlak yol, `.` ya da `..` bileşeni, ters bölü, denetim karakteri, 300 karakteri aşan yol |
| `case-collision`, `file-dir-conflict` | Yalnız büyük/küçük harfle ayrışan iki yol; aynı adda hem dosya hem klasör |

---

## Silinmeye Karşı Korunan Yollar

Sunucu, push'ta yer almayan dosyaları depodan siler. Şunlar **asla silinmez**:

- Herhangi bir derinlikte `.github/` altındaki dosyalar,
- Yukarıdaki sabit yok sayma listesine giren yollar,
- Depodaki kök `.gitignore` ve `.tecofignore` desenlerine uyan yollar (push yeni desenler getiriyorsa onlar da),
- Depodaki sembolik bağlantılar ve alt modüller.

Alt klasördeki ignore dosyalarını sunucu okumaz; ayrıntı için [Yok sayma kuralları](https://tecof-app-dev.vercel.app/cli-reference#yok-sayma-kurallari). Yerel tabanı olmayan (hiç `pull` yapılmamış) bir tema klasöründen yapılan push uzakta dosya silecekse CLI durur (çıkış 4, `unknown-base`); bilinçli silme için `--force` verin.

---

## Yerel Dosyalar

- `tecof theme dev`, `.env.local` dosyasını `0600` izinle yazar; `.env*` dosyaları hiçbir zaman gönderilmez.
- `.tecof/state.json` yalnız taban commit'ini ve dosya özetlerini tutar; sır içermez.
- `tecof theme pull` arşivi diske yazmadan önce bellekte doğrular: mutlak yol, `..`, ters bölü, sembolik ya da sabit bağlantı veya aygıt girişi içeren bir arşiv reddedilir ve hiçbir dosya yazılmaz. Proje kökünün dışına ya da bir bağlantının üzerinden yazılmaz; arşiv `.tecof/` klasörünü değiştiremez.
- Push sembolik bağlantıları izlemez; uyarıyla atlar.

---

## Kodlama Ajanları

### tecof setup agent

```bash
tecof setup agent                                      # Claude Code: .mcp.json
tecof setup agent --client cursor                      # Cursor: .cursor/mcp.json
tecof setup agent --merchant 66f0c0ffee0000000000abcd  # mağaza kapsamlı adres
```

```json
{
  "mcpServers": {
    "tecof": { "type": "http", "url": "https://api.tecof.com/mcp" }
  }
}
```

- Komut, projenin `.mcp.json` (Claude Code) ya da `.cursor/mcp.json` (Cursor; girdi yalnız `url` içerir) dosyasına Tecof uzak MCP sunucusunu ekler. Dosyadaki diğer sunucular korunur; aynı girdi zaten varsa dosyaya dokunulmaz.
- Dosyaya **sır yazılmaz**: istemci ilk bağlantıda Tecof giriş ve onay ekranını (OAuth) açar. Bu yüzden dosya güvenle commit'lenebilir.
- `--merchant` mağaza kapsamlı adresi (`/mcp/<mağaza kimliği>`) yazar.
- Dosyada farklı bir `tecof` girdisi varsa (ör. tema deposundaki `@tecof/mcp` stdio tanımı) `--force` olmadan değiştirilmez; makbuzda `next.action: "confirm"` döner.
- Ardından Claude Code'u bu klasörde yeniden başlatıp `/mcp` ile bağlantıyı onaylayın; Cursor'da Settings → MCP altında "tecof" sunucusunu etkinleştirin.

MCP araçları, kapsamlar ve onay kuralları: [MCP Entegrasyonu](https://tecof-app-dev.vercel.app/mcp). Ajan CLI'ı kendisi çalıştırıyorsa ajan modu kendiliğinden açılır; yıkıcı işlemlerde yukarıdaki onay akışını izleyin.

---

## Kontrol Listesi

- [ ] CI'da yalnız gereken alana sınırlı, `deploy` yetkili ve süreli bir kapsamlı token; değer CI gizli değişkeninde.
- [ ] Kodlama ajanlarının ortamında `TECOF_AGENT_ALLOW_DESTRUCTIVE` tanımlı değil.
- [ ] `.env*`, anahtar dosyaları ve `.npmrc` depoda değil; sırlar ortam değişkenlerinde.
- [ ] Önizleme bağlantıları yalnız yetkili kişilerle paylaşılıyor.
- [ ] Kullanılmayan cihaz oturumları ve CI token'ları `/cli?tab=tokens` ya da `tecof tokens revoke` ile iptal edildi.
- [ ] Mağaza ekibinde yalnız kod üzerinde çalışması gereken kişiler var.

---

# Public API Referansı

> Vitrin /api/store sözleşmesi: auth başlıkları, render, CMS, e-ticaret, müşteri hesabı, analytics ve ödeme sağlayıcı geri dönüşleri.
>
> Kaynak: https://tecof-app-dev.vercel.app/public-apis · Bölüm: API’ler · Son güncelleme: 2018-10-20

Bu sayfa canlı tema, headless storefront, checkout ve analytics için dışarı verilmesi uygun olan mevcut API yüzeyini özetler.

Base URL örneği:

```text
https://api.tecof.com
```

---

## Auth Başlıkları

### Storefront secret key

Canlı tema API'leri merchant bağlamını `x-secret-key` ile çözer:

```http
x-secret-key: merchant_secret_key
Content-Type: application/json
```

### Customer auth

Müşteri hesabı gerektiren uçlarda customer JWT eklenir:

```http
x-secret-key: merchant_secret_key
Authorization: customer_jwt
```

### Editor write auth

Editör mutasyonları secret key'e ek olarak merchant/team JWT ister:

```http
x-secret-key: merchant_secret_key
Authorization: merchant_or_team_jwt
```

---

## Tema ve Render API'leri

| Metot | Endpoint | Auth | Açıklama |
| :--- | :--- | :--- | :--- |
| `GET` | `/api/store/editor/:id` | secret key | Editör için draft sayfa verisini getirir |
| `PUT` | `/api/store/editor/:id` | secret key + JWT | Sayfa draft verisini kaydeder |
| `POST` | `/api/store/render?themeId=:themeId&locale=:locale` | secret key | Yayındaki sayfayı slug ile render için getirir |
| `GET` | `/api/store/merchant-info` | secret key | Dil, default dil, logo, favicon, custom script ve under construction bilgisini getirir |
| `GET` | `/api/store/pages` | secret key | Link alanları ve sitemap için sayfa listesini getirir |
| `POST` | `/api/store/upload` | secret key + opsiyonel JWT | Dosya upload eder |
| `GET` | `/api/store/uploads` | secret key + opsiyonel JWT | Medya kütüphanesini listeler |
| `POST` | `/api/store/translate` | secret key + opsiyonel JWT | Metni birden çok dile çevirir |
| `GET` | `/api/store/shared-components` | secret key | Shared component listesini getirir |
| `POST` | `/api/store/shared-components` | strict auth ayarına bağlı | Shared component oluşturur |
| `POST` | `/api/store/stock-media/search` | secret key + opsiyonel JWT | Stok görsel arar |
| `POST` | `/api/store/stock-media/import` | secret key + opsiyonel JWT | Stok görseli merchant storage'a aktarır |
| `POST` | `/api/store/component-preview` | secret key + opsiyonel JWT | Component screenshot PNG üretir |

`/api/store/render` body örneği:

```json
{
  "slug": "home",
  "themeId": "theme_id",
  "locale": "tr",
  "showDraftData": false
}
```

---

## Storefront CMS API'leri

Bu uçlar sadece canlı içerik döndürür. Taslak item'lar sızmaz; `published` item'lar ve zamanı gelmiş `scheduled` item'lar görünür.

| Metot | Endpoint | Auth | Açıklama |
| :--- | :--- | :--- | :--- |
| `POST` | `/api/store/cms/collections` | secret key | Aktif collection listesini getirir |
| `POST` | `/api/store/cms/collections/:slug` | secret key | Collection detayını slug ile getirir |
| `POST` | `/api/store/cms/collections/:slug/items` | secret key | Collection item listesini getirir |
| `POST` | `/api/store/cms/collections/:slug/items/:itemSlug` | secret key | Tek item'ı slug ile getirir |
| `POST` | `/api/store/cms/items/:id` | secret key | Tek item'ı ID ile getirir |

Item liste body örneği:

```json
{
  "locale": "tr",
  "page": 1,
  "limit": 20,
  "sort": "newest"
}
```

---

## Storefront E-Ticaret API'leri

| Metot | Endpoint | Auth | Açıklama |
| :--- | :--- | :--- | :--- |
| `GET` | `/api/store/ecommerce/categories` | secret key | Kategori ağacı |
| `GET` | `/api/store/ecommerce/products` | secret key | Ürün listesi ve filtreleme |
| `GET` | `/api/store/ecommerce/products/:slug` | secret key | Ürün detayı |
| `GET` | `/api/store/ecommerce/products/:slug/related` | secret key | Benzer ürünler |
| `GET` | `/api/store/ecommerce/search/suggest` | secret key | Ürün/kategori autocomplete |
| `GET` | `/api/store/ecommerce/products/:productId/reviews` | secret key | Onaylı yorumlar ve puan özeti |
| `POST` | `/api/store/ecommerce/products/:productId/reviews` | customer auth | Ürün yorumu gönderir |
| `POST` | `/api/store/ecommerce/cart/validate` | secret key | Sepeti stok/fiyat/indirim için doğrular |
| `POST` | `/api/store/ecommerce/checkout` | secret key | Sepetten sipariş oluşturur |
| `POST` | `/api/store/ecommerce/coupon/validate` | secret key | Kuponu sepete göre doğrular |
| `POST` | `/api/store/ecommerce/shipping/rates` | secret key | Adrese göre kargo seçenekleri |
| `POST` | `/api/store/ecommerce/checkout/initiate-payment` | secret key | Checkout ödeme formunu başlatır |
| `POST` | `/api/store/ecommerce/checkout/callback` | secret key | Storefront ödeme callback sonucu |
| `POST` | `/api/store/ecommerce/checkout-session` | secret key | Hosted checkout session oluşturur |
| `GET` | `/api/store/ecommerce/checkout-session/:uuid` | public | Hosted checkout session getirir |
| `PUT` | `/api/store/ecommerce/checkout-session/:uuid` | public | Hosted checkout session günceller |
| `GET` | `/api/store/ecommerce/push/config` | secret key | VAPID public key |
| `POST` | `/api/store/ecommerce/push/subscribe` | secret key | Push aboneliği oluşturur |
| `POST` | `/api/store/ecommerce/push/unsubscribe` | secret key | Push aboneliğini kaldırır |
| `POST` | `/api/store/ecommerce/email/subscribe` | secret key | Bülten aboneliği oluşturur |

Ürün liste query parametreleri:

```text
locale, page, limit, sort, category, brand, search, minPrice, maxPrice, tag
```

Desteklenen `sort` değerleri:

```text
newest, oldest, priceAsc, priceDesc, nameAsc, nameDesc
```

---

## Müşteri Hesabı API'leri

| Metot | Endpoint | Auth | Açıklama |
| :--- | :--- | :--- | :--- |
| `POST` | `/api/store/ecommerce/customer/register` | secret key | Müşteri kaydı |
| `POST` | `/api/store/ecommerce/customer/login` | secret key | Müşteri girişi |
| `POST` | `/api/store/ecommerce/customer/convert-guest` | secret key | Guest müşteriyi hesaba çevirir |
| `POST` | `/api/store/ecommerce/customer/verify-email` | secret key | E-posta doğrular |
| `POST` | `/api/store/ecommerce/customer/resend-verification` | customer auth | Doğrulama e-postasını yeniden gönderir |
| `POST` | `/api/store/ecommerce/customer/forgot-password` | secret key | Şifre sıfırlama e-postası ister |
| `POST` | `/api/store/ecommerce/customer/reset-password` | secret key | Şifre sıfırlar |
| `GET` | `/api/store/ecommerce/customer/me` | customer auth | Profil getirir |
| `PUT` | `/api/store/ecommerce/customer/me` | customer auth | Profil günceller |
| `PUT` | `/api/store/ecommerce/customer/password` | customer auth | Şifre değiştirir |
| `GET` | `/api/store/ecommerce/customer/orders` | customer auth | Siparişleri listeler |
| `GET` | `/api/store/ecommerce/customer/orders/:orderNumber` | customer auth | Sipariş detayı |
| `GET` | `/api/store/ecommerce/customer/addresses` | customer auth | Adresleri listeler |
| `POST` | `/api/store/ecommerce/customer/addresses` | customer auth | Adres ekler |
| `PUT` | `/api/store/ecommerce/customer/addresses/:addressId` | customer auth | Adres günceller |
| `DELETE` | `/api/store/ecommerce/customer/addresses/:addressId` | customer auth | Adres siler |
| `PUT` | `/api/store/ecommerce/customer/addresses/:addressId/default` | customer auth | Varsayılan adres yapar |

---

## Analytics API'leri

| Metot | Endpoint | Auth | Açıklama |
| :--- | :--- | :--- | :--- |
| `POST` | `/api/analytics/event` | public | Storefront event toplar, başarılıysa `204 No Content` döner |
| `GET` | `/api/analytics/stats` | JWT | Pageview, visitor, referrer, device ve top URL istatistikleri |
| `GET` | `/api/analytics/live` | JWT | Anlık ziyaretçi, bugünkü oturumlar ve checkout davranışı |

Event payload örneği:

```json
{
  "merchantId": "merchant_id",
  "url": "/products/example",
  "referrer": null,
  "type": "cart_add",
  "data": {
    "productId": "product_id",
    "quantity": 1
  },
  "ts": 1760000000000
}
```

Desteklenen event tipleri:

```text
pageview, custom, web-vital, cart_add, cart_remove, checkout_start
```

---

## Payment Provider Callback

Ödeme sağlayıcılarının çağırdığı public callback endpoint:

| Metot | Endpoint | Auth | Açıklama |
| :--- | :--- | :--- | :--- |
| `POST` | `/api/merchant/ecommerce/payments/callback/:provider` | public | `iyzico` veya `paytr` callback işler |

Bu endpoint müşteri tarayıcısından manuel çağrılmak için değil, ödeme sağlayıcı sunucularının callback'i için tasarlanmıştır.

---

# Headless CMS Mimarisi ve API Rehberi

> CMS koleksiyon ve öğe modeli, panel (JWT) yönetim uçları, vitrin canlı içerik okuma, yayın kuralları ve referans alanları.
>
> Kaynak: https://tecof-app-dev.vercel.app/headless-cms · Bölüm: API’ler · Son güncelleme: 2018-10-20

Tecof CMS, tema bazlı collection ve item yönetimi sağlar. Admin paneli JWT korumalı `/api/merchant/cms/*` uçlarını kullanır; canlı storefront ise secret-key korumalı `/api/store/cms/*` uçlarıyla sadece yayınlanabilir içerikleri okur.

---

## Veri Modeli

### Collection

Collection; içerik şemasını, alan listesini, görüntülenecek alanı ve tema bağlantısını taşır.

Öne çıkan alanlar:

| Alan | Açıklama |
| :--- | :--- |
| `merchantId` | Sahip merchant |
| `themeId` | Collection'ın bağlı olduğu aktif tema |
| `name` | Çok dilli collection adı |
| `slug` | Storefront erişim anahtarı |
| `fields` | Dinamik alan şeması |
| `displayField` | Listelerde gösterilecek alan |
| `status` | `active` veya `inactive` |

### Collection Item

Item; collection'a bağlı gerçek içerik kaydıdır.

Öne çıkan alanlar:

| Alan | Açıklama |
| :--- | :--- |
| `slug` | Item slug |
| `data` | Dinamik alan verisi |
| `metaTitle` | SEO başlığı |
| `metaDescription` | SEO açıklaması |
| `ogImage` | Sosyal görsel |
| `status` | `draft`, `scheduled`, `published` |
| `scheduledDate` | Zamanlı yayın tarihi |

---

## Admin CMS API'leri

Bu uçlar satıcı paneli içindir ve JWT role auth ister.

### Collection API

| Metot | Endpoint | Açıklama |
| :--- | :--- | :--- |
| `GET` | `/api/merchant/cms/collections/templates` | Hazır collection şablonlarını listeler |
| `GET` | `/api/merchant/cms/collections` | Collection listesini getirir |
| `GET` | `/api/merchant/cms/collections/by/id/:id` | Collection detayını getirir |
| `POST` | `/api/merchant/cms/collections` | Collection oluşturur |
| `PUT` | `/api/merchant/cms/collections/:id` | Collection günceller |
| `DELETE` | `/api/merchant/cms/collections/:id` | Collection'ı soft delete yapar |

### Item API

| Metot | Endpoint | Açıklama |
| :--- | :--- | :--- |
| `GET` | `/api/merchant/cms/collections/:collectionId/items` | Item listesini getirir |
| `GET` | `/api/merchant/cms/collections/:collectionId/items/by/id/:id` | Item detayını getirir |
| `POST` | `/api/merchant/cms/collections/:collectionId/items` | Item oluşturur |
| `PUT` | `/api/merchant/cms/collections/:collectionId/items/:id` | Item günceller |
| `DELETE` | `/api/merchant/cms/collections/:collectionId/items/:id` | Item'ı soft delete yapar |
| `POST` | `/api/merchant/cms/collections/:collectionId/items/:id/publish` | Item'ı yayına alır |
| `POST` | `/api/merchant/cms/collections/:collectionId/items/:id/unpublish` | Item'ı taslağa alır |
| `POST` | `/api/merchant/cms/collections/:collectionId/items/:id/schedule` | Item'ı ileri tarihe planlar |
| `GET` | `/api/merchant/cms/collections/:collectionId/items/:id/revisions` | Revizyon geçmişini listeler |
| `POST` | `/api/merchant/cms/collections/:collectionId/items/:id/revisions/:revisionId/restore` | Revizyon geri yükler |
| `POST` | `/api/merchant/cms/collections/:collectionId/items/bulk-delete` | Toplu siler |
| `POST` | `/api/merchant/cms/collections/:collectionId/items/reorder` | Sıralamayı günceller |

---

## Admin Query Parametreleri

Admin listelerinde desteklenen pratik parametreler:

| Parametre | Açıklama |
| :--- | :--- |
| `field=string` | Çok dilli alanları seçilen dile düz string olarak çevirir |
| `lang=tr` | Çevrilecek dili belirtir |
| `search=...` | Slug ve `data` içinde arama yapar |
| `status=published` | Item status filtresi |
| `page=1` | Sayfalama |
| `limit=20` | Sayfa boyutu |

Örnek:

```http
GET /api/merchant/cms/collections/:collectionId/items?field=string&lang=tr&page=1&limit=20
```

---

## Storefront CMS API'leri

Storefront uçları `x-secret-key` ister ve body üzerinden `locale`, `page`, `limit`, `sort` gibi değerleri alır.

| Metot | Endpoint | Açıklama |
| :--- | :--- | :--- |
| `POST` | `/api/store/cms/collections` | Aktif collection listesini getirir |
| `POST` | `/api/store/cms/collections/:slug` | Collection detayını slug ile getirir |
| `POST` | `/api/store/cms/collections/:slug/items` | Collection item listesini getirir |
| `POST` | `/api/store/cms/collections/:slug/items/:itemSlug` | Tek item'ı slug ile getirir |
| `POST` | `/api/store/cms/items/:id` | Tek item'ı ID ile getirir |

Örnek:

```http
POST /api/store/cms/collections/blog/items
x-secret-key: merchant_secret_key
Content-Type: application/json
```

```json
{
  "locale": "tr",
  "page": 1,
  "limit": 12,
  "sort": "newest"
}
```

---

## Storefront Yayın Kuralları

Canlı API item görünürlüğünü şu kuralla sınırlar:

| Item durumu | Storefront'ta görünür mü? |
| :--- | :--- |
| `draft` | Hayır |
| `published` | Evet |
| `scheduled` ve tarihi geldiyse | Evet |
| `scheduled` ve tarihi gelmediyse | Hayır |

Storefront tarafı client'tan status filtresi kabul etmez. Böylece taslak içerikler yanlışlıkla temaya sızmaz.

---

## Reference Alanları

Storefront CMS okuma katmanı `reference` ve `multi-reference` alanlarını tek seviye çözer. Referans verilen item canlı değilse değer `null` olur veya listeden çıkarılır.

Dönen item örneği:

```json
{
  "_id": "item_id",
  "slug": "blog-yazisi",
  "data": {
    "title": "Blog Yazısı",
    "author": {
      "_id": "author_id",
      "slug": "ahmet",
      "data": {
        "name": "Ahmet"
      }
    }
  }
}
```

---

## Webhook Davranışı

Bir CMS item yayına alındığında backend `cms.item.published` event'i için webhook dispatch eder. Payload içinde `itemId`, `collectionId`, `slug`, `status` ve `publishedDate` bulunur.

Uygulamaların bu olaya aboneliği için [Webhook’lar](https://tecof-app-dev.vercel.app/app-webhooks), mağaza webhook’larının panel uçları için [Mağaza webhook’ları](https://tecof-app-dev.vercel.app/app-webhooks#magaza-webhooklari-panelden) bölümüne bakın.

---

# API ile Veri Erişimi

> /api/v1 yanıt zarfı, sayfalama ve hız sınırları; sipariş, müşteri, envanter, ürün şekilleri; Tools API ile yazma ve uygulamaya özel uçlar.
>
> Kaynak: https://tecof-app-dev.vercel.app/app-api · Bölüm: API’ler · Son güncelleme: 2018-10-20

Uygulamanızın sunucusu, kurulum token'ıyla (`tcfi_…`) Tecof Developer API'sini (`/api/v1`) kullanır. Kişisel erişim anahtarlarıyla (PAT) aynı uçlar ve aynı yanıt zarfı geçerlidir; fark, token'ın bir kullanıcıya değil bir **kuruluma** bağlı olması ve mağazanın onayladığı kapsamlarla sınırlanmasıdır.

```text
Base URL: https://api.tecof.com/api/v1
Authorization: Bearer tcfi_...
```

Token almak için bkz. [Kimlik Doğrulama → Kurulum token'ı](https://tecof-app-dev.vercel.app/app-auth). SDK kullanıyorsanız token yönetimi otomatiktir:

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

const api = tecof.client(installationId);
```

---

## Yanıt Zarfı

Tüm uçlar Tecof standart zarfını döner:

```json
{
  "success": true,
  "message": "İşlem başarılı",
  "messageCode": "success",
  "data": [],
  "totalData": 128
}
```

| Alan | Açıklama |
| :--- | :--- |
| `success` | İşlem sonucu |
| `message` | İnsan okur mesaj |
| `messageCode` | Makine okur kod (hata ayrımı için bunu kullanın) |
| `data` | Yük |
| `totalData` | Liste uçlarında toplam kayıt sayısı |

SDK zarfı açar: başarılı çağrı doğrudan `data`'yı döner; hata durumunda `TecofApiError { status, code, data }` fırlatır (`code` = `messageCode`).

```ts
import { TecofApiError } from "@tecof/app-sdk";

try {
  const order = await api.orders.get("TCF-1001");
} catch (err) {
  if (err instanceof TecofApiError && err.code === "insufficient-scope") {
    console.warn("Eksik kapsam:", err.data); // { required, missing }
  } else {
    throw err;
  }
}
```

### Sık hata kodları

| HTTP | `messageCode` | Ne yapmalı |
| :--- | :--- | :--- |
| 401 | `token-expired` | Token'ın süresi doldu; yeni token alın (SDK otomatik yeniler) |
| 401 | `token-revoked` | Token iptal edildi (kaldırma, kapsam değişikliği); yeni token alın, kurulum aktif değilse çağrıyı bırakın |
| 401 | `token-invalid` | Token tanınmıyor ya da biçimi bozuk |
| 401 | `app-suspended` | Uygulama Tecof tarafından askıya alındı; token basılmaz |
| 403 | `app-token-required` | `/api/v1/app/*` uçları kişisel erişim anahtarıyla (PAT) çağrıldı; bu uçlar yalnız uygulama token'ı kabul eder |
| 403 | `insufficient-scope` | `data: { required, missing }`; kapsamı `tecof.app.json`'a ekleyin, mağaza onaylamalı |
| 404 | `not-found` | Kayıt yok |
| 429 | `rate-limited` | Hız sınırı aşıldı; bekleyip yeniden deneyin |

---

## Sayfalama ve Süzgeçler

| Parametre | Açıklama |
| :--- | :--- |
| `page` | 1'den başlar |
| `limit` | En fazla 200; varsayılan 50 (ürün listesi eski sözleşmeyi korur: varsayılan 30) |
| `updatedSince` | ISO 8601; yalnız bu tarihten sonra değişen kayıtlar |
| Kaynağa özel süzgeçler | Aşağıdaki kaynak bölümlerinde |

Tutarlar sayı, tarihler ISO 8601 biçimindedir.

**Artımlı senkron örneği** — son çalışmadan beri değişen siparişleri sayfa sayfa okur:

```ts
import type { TecofApp } from "@tecof/app-sdk";

type ApiClient = ReturnType<TecofApp["client"]>;

export async function syncChangedOrders(api: ApiClient, since: string) {
  const limit = 200;
  for (let page = 1; ; page++) {
    const batch = await api.orders.list({ updatedSince: since, page, limit });
    for (const order of batch) {
      // siparişi işle
    }
    if (batch.length < limit) break;
  }
}
```

---

## Hız Sınırları

| Tür | Sınır | Kapsam |
| :--- | :--- | :--- |
| Okuma | 240 istek/dk | Kurulum başına |
| Yazma | 60 istek/dk | Kurulum başına |

Aşımda `429 rate-limited` döner. Uygulama token'ında mağazanın paket özelliği kapısı (`apiAccess`) uygulanmaz.

---

## Siparişler

| Metot | Uç | Kapsam |
| :--- | :--- | :--- |
| `GET` | `/api/v1/orders` | `orders:read` |
| `GET` | `/api/v1/orders/:idOrNumber` | `orders:read` |

Liste süzgeçleri: `status`, `paymentStatus`, `search`, `createdFrom`, `createdTo`, `updatedSince`. Tek sipariş uçu kimlik ya da sipariş numarası (`TCF-1001`) kabul eder.

```bash
curl "https://api.tecof.com/api/v1/orders?paymentStatus=paid&limit=20" \
  -H "Authorization: Bearer $TECOF_INSTALLATION_TOKEN"
```

```ts
const paid = await api.orders.list({ paymentStatus: "paid", limit: 20 });
const order = await api.orders.get("TCF-1001");
```

Sipariş nesnesi:

```json
{
  "id": "6720bb00cc11dd22ee33ff44",
  "orderNumber": "TCF-1001",
  "status": "confirmed",
  "paymentStatus": "paid",
  "currency": "TRY",
  "orderedAt": "2026-10-10T09:15:00.000Z",
  "createdAt": "2026-10-10T09:15:00.000Z",
  "updatedAt": "2026-10-10T09:16:12.000Z",
  "cancelledAt": null,
  "cancelReason": null,
  "customer": {
    "id": "66f1aa00bb11cc22dd33ee77",
    "firstName": "Örnek",
    "lastName": "Müşteri",
    "email": "musteri@example.com",
    "phone": "+905550000000"
  },
  "billingAddress": {
    "firstName": "Örnek", "lastName": "Müşteri", "company": "", "phone": "+905550000000",
    "email": "musteri@example.com", "country": "TR", "city": "İstanbul", "district": "Kadıköy",
    "zip": "34000", "line1": "Örnek Mah. Deneme Sk. No: 1", "line2": "", "identityNumber": "11111111111",
    "invoiceType": "individual", "taxNumber": "", "taxOffice": ""
  },
  "shippingAddress": {
    "firstName": "Örnek", "lastName": "Müşteri", "company": "", "phone": "+905550000000",
    "email": "musteri@example.com", "country": "TR", "city": "İstanbul", "district": "Kadıköy",
    "zip": "34000", "line1": "Örnek Mah. Deneme Sk. No: 1", "line2": "", "identityNumber": "",
    "invoiceType": "individual", "taxNumber": "", "taxOffice": ""
  },
  "lineItems": [
    {
      "id": "li_1", "productId": "66f2aa00bb11cc22dd33ee88", "variantId": "66f2aa00bb11cc22dd33ee99",
      "name": "Pamuklu Tişört", "variantTitle": "S / Siyah", "sku": "TS-S",
      "quantity": 2, "unitPrice": 500, "totalPrice": 1000,
      "taxRate": 20, "taxAmount": 166.67, "discountAmount": 0, "netTotal": 833.33, "taxIncluded": true,
      "personalizationTotal": 0
    }
  ],
  "shippingLines": [
    { "title": "Standart Kargo", "carrier": "Örnek Kargo", "deliveryMethod": "standard", "price": 50 }
  ],
  "discountLines": [],
  "totals": {
    "subtotal": 1000, "discount": 0, "shipping": 50, "paymentFee": 0,
    "tax": 175, "taxAddedToTotal": 0, "total": 1050,
    "pricesIncludeTax": true, "shippingTaxRate": 20, "shippingTaxAmount": 8.33, "shippingTaxIncluded": true
  },
  "payment": {
    "provider": "iyzico", "paidAmount": 1050, "paidAt": "2026-10-10T09:16:10.000Z",
    "installmentCount": 1, "cardAssociation": "VISA", "lastFourDigits": "0000"
  },
  "packages": [],
  "note": "",
  "tags": [],
  "salesChannelId": null
}
```

- **Fatura kimliği** (`billingAddress`): `invoiceType` `"individual"` ya da `"corporate"`. Kurumsalda `company` unvan, `taxNumber` vergi numarası, `taxOffice` vergi dairesidir. Türkiye'de `taxNumber` 10 haneli VKN (sağlama hanesi doğrulanmış) ya da şahıs şirketi için 11 haneli TCKN olur; yurt dışı kurumsal alıcıda serbest biçimlidir ve vergi dairesi boş olabilir. Bireysel alıcıda bu iki alan boştur, kimlik `identityNumber`'dadır (anonim alıcı `11111111111`). Ayrıntı ve hazır sınıflandırma için [Fatura Uygulamaları](https://tecof-app-dev.vercel.app/app-invoicing).
- `lineItems[].discountAmount`: satıra düşen sipariş indirimi, satırın kendi KDV modunda (hediye çeki hariç). Satırların toplamı `totals.discount`a eşittir. `netTotal` ve `taxAmount` indirim **sonrası** matrahı ve KDV'yi verir: KDV, indirim düşüldükten sonra kalan tutar üzerinden hesaplanır. Kapsamlı kupon yalnız kendi satırlarının matrahını düşürür. 10.10.2026 öncesi siparişlerde `discountAmount` 0'dır ve KDV indirim öncesi tutardan hesaplanmıştır.
- `lineItems[].taxRate` `null` ise kayıt eski bir siparişe aittir ve oran bilinmez; fatura uygulamaları mağaza varsayılan oranına düşmelidir.
- `packages[]`: `{ id, trackingNumber, carrier, status, items: [{ lineItemId, quantity }], shippedAt, deliveredAt }`.
- `discountLines[]`: `{ source, title, amount }`.

---

## Müşteriler

| Metot | Uç | Kapsam |
| :--- | :--- | :--- |
| `GET` | `/api/v1/customers` | `customers:read` |
| `GET` | `/api/v1/customers/:id` | `customers:read` |

Liste süzgeçleri: `search`, `updatedSince`.

```ts
const customers = await api.customers.list({ search: "musteri@example.com" });
const customer = await api.customers.get("66f1aa00bb11cc22dd33ee77");
```

```json
{
  "id": "66f1aa00bb11cc22dd33ee77",
  "firstName": "Örnek", "lastName": "Müşteri", "fullName": "Örnek Müşteri",
  "email": "musteri@example.com", "phone": "+905550000000",
  "accountStatus": "active", "isEmailVerified": true, "preferredLanguage": "tr",
  "groupIds": [], "tagIds": [], "note": "",
  "addresses": [
    {
      "id": "addr_1", "title": "Ev", "firstName": "Örnek", "lastName": "Müşteri",
      "phone": "+905550000000", "country": "TR", "city": "İstanbul", "district": "Kadıköy",
      "zip": "34000", "line1": "Örnek Mah. Deneme Sk. No: 1", "line2": "", "isDefault": true
    }
  ],
  "totalOrders": 3, "totalSpent": 2450, "firstOrderAt": "2026-08-01T10:00:00.000Z",
  "lastOrderAt": "2026-10-10T09:15:00.000Z",
  "createdAt": "2026-08-01T09:58:00.000Z", "updatedAt": "2026-10-10T09:15:00.000Z"
}
```

Parola ve token alanları hiçbir koşulda dönmez.

---

## Envanter

| Metot | Uç | Kapsam |
| :--- | :--- | :--- |
| `GET` | `/api/v1/inventory` | `products:read` |

Süzgeçler: `sku`, `productId`, `lowStock`, `updatedSince`. Her satır bir varyanttır:

```json
{
  "productId": "66f2aa00bb11cc22dd33ee88",
  "productName": "Pamuklu Tişört",
  "productSlug": "pamuklu-tisort",
  "variantId": "66f2aa00bb11cc22dd33ee99",
  "sku": "TS-S",
  "barcode": "8690000000000",
  "title": "S / Siyah",
  "price": 500,
  "stock": 12,
  "locations": [{ "locationId": "66f3aa00bb11cc22dd33ee00", "name": "Ana Depo", "quantity": 12 }],
  "updatedAt": "2026-10-10T08:00:00.000Z"
}
```

```ts
const lowStock = await api.inventory.list({ lowStock: true });
```

Stok yazma Tools API üzerinden yapılır (`apply_stock_count`, `products:write`) — aşağıya bakın.

---

## Ürünler

| Metot | Uç | Kapsam |
| :--- | :--- | :--- |
| `GET` | `/api/v1/products` | `products:read` |
| `GET` | `/api/v1/products/:idOrSlug` | `products:read` |
| `POST` | `/api/v1/products` | `products:write` (upsert) |
| `PATCH` | `/api/v1/products/:id` | `products:write` |

Ürün uçları mevcut Developer API ürün sözleşmesini kullanır: liste hafiftir (`fields=full` ile açıklama ve varyantlar gelir), `:idOrSlug` kimlik, slug ya da varyant SKU'su kabul eder, çok dilli alanlar `[{ code, value }]` biçimindedir. Ürün listesinde süzgeçler: `search`, `status`, `category`, `brand`, `tag`, `updatedSince`, `fields=full`. Ürün listesinin varsayılan `limit` değeri 30'dur (en fazla 200). Ürün nesneleri kimliği `_id` alanında taşır (sipariş, müşteri ve envanterde `id`).

```ts
const products = await api.products.list({ status: "active", limit: 50 });
const product = await api.products.get("pamuklu-tisort");
```

```json
{
  "_id": "66f2aa00bb11cc22dd33ee88",
  "slug": "pamuklu-tisort",
  "name": [{ "code": "tr", "value": "Pamuklu Tişört" }],
  "status": "active",
  "type": "variable",
  "totalStock": 12,
  "variantCount": 2,
  "variants": [
    {
      "_id": "66f2aa00bb11cc22dd33ee99", "sku": "TS-S", "barcode": null,
      "price": 500, "compareAtPrice": 650, "weight": 300, "isActive": true,
      "stock": 12, "stocks": [{ "stockLocationId": "66f3aa00bb11cc22dd33ee00", "quantity": 12 }],
      "variantValues": [{ "variantTypeId": "…", "variantValueId": "…" }]
    }
  ]
}
```

> Ürün yazma anında canlıdır: `status: "active"` gönderilen ürün vitrine çıkar. Ürün yazma ayrıca mağaza paketinde e-ticaretin açık olmasını ister (`403 plan-feature-unavailable`).

---

## Yazma İşlemleri: Tools API

Okuma dışındaki işlemler (stok sayımı uygulama gibi) Tecof'un tek araç kayıt defteri üzerinden, Tools API ile yapılır. Aynı araçlar MCP sunucusunda da kullanılır. Uygulama token'ı `api` yüzeyindeki araçları, mağazanın **verdiği** kapsamlarla görür ve çalıştırır.

| Metot | Uç | Açıklama |
| :--- | :--- | :--- |
| `GET` | `/api/v1/tools?surface=api` | Araç kataloğu (ad, açıklama, JSON Schema girdi, gereken kapsamlar, onay ve kredi bilgisi) |
| `GET` | `/api/v1/tools/:name` | Tek aracın tanımı |
| `POST` | `/api/v1/tools/:name` | Aracı çalıştırır; gövde = araç girdisi (JSON) |

Her aracın girdi şeması katalogda `inputSchema` olarak yayımlanır. Çağırmadan önce şemayı okuyun:

```bash
curl "https://api.tecof.com/api/v1/tools/apply_stock_count" \
  -H "Authorization: Bearer $TECOF_INSTALLATION_TOKEN"
```

```ts
// Girdi alanlarını aracın inputSchema'sına göre doldurun
const result = await api.tools.call("apply_stock_count", input);
```

Ham HTTP ile çalıştırma:

```bash
curl -X POST "https://api.tecof.com/api/v1/tools/apply_stock_count" \
  -H "Authorization: Bearer $TECOF_INSTALLATION_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: stock-sync-2026-10-10-0001" \
  -d @input.json
```

| Konu | Davranış |
| :--- | :--- |
| Kapsam | Araç başına denetlenir: `403 insufficient-scope { required, missing }` |
| Doğrulama | `400 validation-error { issues: [{ path, message }] }` |
| `Idempotency-Key` | İsteğe bağlı (≤128 karakter). Aynı anahtar + aynı girdi → saklanan yanıt (`Idempotency-Replayed: true`); farklı girdi → `422 idempotency-key-reused`; işlem sürerken → `409 idempotency-in-progress`. Saklama 24 saat |
| Onay isteyen araçlar | İlk çağrı `409 confirmation-required { needsConfirmation, confirmId, summary, expiresAt }` döner; **aynı girdiyle** `confirm: true` ve `confirmId` ekleyerek yeniden çağırın (aşağıda) |
| Hız sınırı | `429 rate-limited` + `Retry-After: 60` |
| Akış | `?stream=1` ile `text/event-stream` (ilerleme + sonuç çerçeveleri) |

### Onay isteyen araçlar

Silme ya da canlıyı doğrudan değiştiren araçlar iki adımda çalışır. Uygulama token'ında da akış kişisel erişim anahtarıyla aynıdır: onayı sizin uygulamanız verir (gerekirse kullanıcıya App Bridge `confirm` ile sorarak).

```ts
import { TecofApiError } from "@tecof/app-sdk";

async function callWithConfirm(api: ApiClient, name: string, input: Record<string, unknown>) {
  try {
    return await api.tools.call(name, input);
  } catch (err) {
    if (err instanceof TecofApiError && err.code === "confirmation-required") {
      const { confirmId, summary } = err.data as { confirmId: string; summary: string };
      // summary'yi kaydedin ya da kullanıcıya gösterin; onaylandıysa aynı girdiyle tekrar çağırın
      return api.tools.call(name, { ...input, confirm: true, confirmId });
    }
    throw err;
  }
}
```

`confirmId` süresi dolmuşsa `409 confirmation-expired` döner; `confirmId` olmadan baştan çağırın.

---

## Uygulamaya Özel Uçlar

Bu uçlar yalnız uygulama token'ıyla çalışır ve kapsam istemez (metafield'lar hariç); veri kuruluma aittir. Kişisel erişim anahtarıyla (PAT) `/api/v1/app/*` çağrısı `403 app-token-required` döner.

| Metot | Uç | Açıklama | SDK |
| :--- | :--- | :--- | :--- |
| `GET` | `/api/v1/app/installation` | Kurulumun kendisi | `api.installation()` |
| `GET` | `/api/v1/app/settings` | Ayarlar | `api.settings.get()` |
| `PUT` | `/api/v1/app/settings` | Ayar yazma | `api.settings.set(obj, { merge })` |
| `GET` | `/api/v1/app/secrets` | Sır listesi (değer yok) | `api.secrets.list()` |
| `GET` | `/api/v1/app/secrets/:key` | Sır okuma | `api.secrets.get(key)` |
| `PUT` | `/api/v1/app/secrets/:key` | Sır yazma | `api.secrets.set(key, value)` |
| `DELETE` | `/api/v1/app/secrets/:key` | Sır silme | `api.secrets.delete(key)` |
| `POST` | `/api/v1/app/events` | Uygulama olayı yayınlama | `api.events.publish(name, data)` |
| `GET` | `/api/v1/app/events/catalog` | Mağazadaki uygulama olayları | `api.events.catalog()` |
| `GET` | `/api/v1/metafields` | Metafield listesi | `api.metafields.list({...})` |
| `PUT` | `/api/v1/metafields` | Metafield yazma | `api.metafields.set({...})` |
| `DELETE` | `/api/v1/metafields/:id` | Metafield silme | `api.metafields.delete(id)` |

### Kurulum

```ts
const installation = await api.installation();
```

```json
{
  "installationId": "6720aa00bb11cc22dd33ee55",
  "status": "active",
  "installedAt": "2026-10-10T08:00:00.000Z",
  "isTestInstall": false,
  "scopes": ["orders:read", "customers:read", "products:read"],
  "pendingScopes": [],
  "merchant": {
    "id": "66f0c0ffee0000000000abcd", "name": "Örnek Mağaza", "productType": "ecommerce",
    "languages": ["tr", "en"], "defaultLanguage": "tr", "currency": "TRY"
  },
  "app": { "clientId": "tcfa_xxxxxxxxxxxxxxxx", "slug": "isbasi", "name": "Logo İşbaşı", "configVersion": 3 },
  "subscription": { "planKey": "standart", "status": "active", "trialEndsAt": null, "currentPeriodEnd": "2026-11-10T09:16:10.000Z" }
}
```

`isTestInstall: true`, kurulumun uygulamanın test mağazalarından birinde olduğunu gösterir. Plan yoksa `subscription` `null` olur. `pendingScopes`, mağazanın henüz onaylamadığı kapsam artışıdır.

### Ayarlar

```bash
curl "https://api.tecof.com/api/v1/app/settings" -H "Authorization: Bearer $TECOF_INSTALLATION_TOKEN"
```

```json
{ "success": true, "messageCode": "success", "data": { "settings": { "invoiceMode": "draft" }, "updatedAt": "2026-10-10T09:00:00.000Z" } }
```

```bash
curl -X PUT "https://api.tecof.com/api/v1/app/settings" \
  -H "Authorization: Bearer $TECOF_INSTALLATION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "settings": { "invoiceMode": "issued" }, "merge": true }'
```

Yanıt: `{ settings, updatedAt }`. Sır olmayan JSON, en fazla 64 KB. `merge: true` mevcut nesneyle birleştirir. API'den ayar yazmak `app.settings.updated` olayı **üretmez** (olay yalnız panel formu kaydında gelir).

### Sırlar (Vault)

```bash
# Yazma
curl -X PUT "https://api.tecof.com/api/v1/app/secrets/isbasiApiKey" \
  -H "Authorization: Bearer $TECOF_INSTALLATION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "value": "örnek-api-anahtarı" }'
# → { "data": { "key": "isbasiApiKey", "updatedAt": "…" } }

# Listeleme (değer dönmez)
curl "https://api.tecof.com/api/v1/app/secrets" -H "Authorization: Bearer $TECOF_INSTALLATION_TOKEN"
# → { "data": [ { "key": "isbasiApiKey", "updatedAt": "…", "lastReadAt": "…", "length": 18 } ] }

# Okuma
curl "https://api.tecof.com/api/v1/app/secrets/isbasiApiKey" -H "Authorization: Bearer $TECOF_INSTALLATION_TOKEN"
# → { "data": { "key": "isbasiApiKey", "value": "örnek-api-anahtarı", "updatedAt": "…" } }
```

Kurallar ve şifreleme tasarımı: [Ayarlar, Vault ve Metafield'lar](https://tecof-app-dev.vercel.app/app-data).

### Metafield'lar

```bash
curl -X PUT "https://api.tecof.com/api/v1/metafields" \
  -H "Authorization: Bearer $TECOF_INSTALLATION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "ownerType": "order",
    "ownerId": "6720bb00cc11dd22ee33ff44",
    "key": "invoiceNumber",
    "type": "string",
    "value": "ABC2026000000123",
    "visibility": "shared",
    "panel": { "label": { "tr": "İşbaşı fatura no", "en": "İşbaşı invoice no" }, "show": true }
  }'

curl "https://api.tecof.com/api/v1/metafields?ownerType=order&ownerId=6720bb00cc11dd22ee33ff44&namespace=isbasi" \
  -H "Authorization: Bearer $TECOF_INSTALLATION_TOKEN"
```

`PUT` yanıtı:

```json
{
  "id": "6720ee00ff11aa22bb33cc77",
  "namespace": "isbasi",
  "ownerType": "order",
  "ownerId": "6720bb00cc11dd22ee33ff44",
  "key": "invoiceNumber",
  "type": "string",
  "value": "ABC2026000000123",
  "visibility": "shared",
  "panel": { "label": { "tr": "İşbaşı fatura no", "en": "İşbaşı invoice no" }, "show": true },
  "own": true,
  "updatedAt": "2026-10-10T09:20:00.000Z"
}
```

`own`, kaydın çağıran uygulamanın namespace'ine ait olup olmadığını gösterir. `ownerType: "merchant"` için `ownerId` yok sayılır (kayıt mağazaya bağlanır).

### Uygulama olayları

```bash
curl -X POST "https://api.tecof.com/api/v1/app/events" \
  -H "Authorization: Bearer $TECOF_INSTALLATION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "invoice.created", "data": { "orderId": "6720bb00cc11dd22ee33ff44", "invoiceNumber": "ABC2026000000123" } }'
```

Mağazadaki diğer uygulamaların yayınladığı olaylar:

```ts
const catalog = await api.events.catalog();
// [{ slug: "kargo", appName: "Örnek Kargo", event: "app.kargo.shipment.created", description: { tr: "…", en: "…" } }]
```

Ayrıntılar: [Uygulamalar Arası İletişim](https://tecof-app-dev.vercel.app/app-interop).

---

# Paketler ve Güncel Sürümler

> Tüm @tecof npm paketleri: güncel sürüm, kurulum komutu, giriş noktaları, peer bağımlılıklar ve sürüm geçmişi. Sürümler npm kayıt defterinden saatlik olarak yenilenir.
>
> Kaynak: https://tecof-app-dev.vercel.app/packages · Veri: npm kayıt defteri · Alındı: 2026-11-12

| Paket | Sürüm | Yayın tarihi | Ne işe yarar |
| :--- | :--- | :--- | :--- |
| `@tecof/cli` | 0.2.0 | 11 Eki 2026 | Tecof CLI |
| `@tecof/theme-editor` | 0.0.98 | 12 Kas 2026 | Tecof Studio (theme-editor) |
| `@tecof/analytics` | 0.0.3 | 28 Tem 2026 | Analytics SDK |
| `@tecof/app-sdk` | 0.1.0 | 11 Eki 2026 | App SDK (sunucu) |
| `@tecof/app-bridge` | 0.1.0 | 11 Eki 2026 | App Bridge |
| `@tecof/app-ui` | 0.1.0 | 11 Eki 2026 | App UI (tasarım kimliği) |
| `@tecof/invoice-kit` | 0.2.0 | 11 Eki 2026 | Invoice Kit |
| `@tecof/mcp` | 0.2.7 | 28 Eyl 2026 | Tecof MCP (stdio) |

## Tema

Next.js temaları ve Tecof Studio için.

### @tecof/theme-editor

**Güncel sürüm:** 0.0.98 (12 Kas 2026) · [npm](https://www.npmjs.com/package/@tecof/theme-editor)

Görsel sayfa editörü (TecofEditor / TecofStudio), yayın renderer’ı (TecofRender), alan fabrikaları, API istemcisi, stil/tema motoru ve e-posta doküman modeli.

```bash
npm install @tecof/theme-editor @tiptap/core @tiptap/pm @tiptap/react lucide-react
```

Giriş noktaları:

- `@tecof/theme-editor` — Editör, renderer, alanlar, API istemcisi, yardımcılar
- `@tecof/theme-editor/styles.css` — Editör ve alan arayüzü stilleri (zorunlu)
- `@tecof/theme-editor/email` — Pazarlama e-postası doküman modeli ve HTML render’ı
- `@tecof/theme-editor/under-construction` — Yapım aşaması sayfası bileşeni

Peer bağımlılıklar: `react@^18 || ^19`, `react-dom@^18 || ^19`, `@tiptap/pm@^3.0.0`, `@tiptap/core@^3.0.0`, `lucide-react@>=0.408.0 <2`, `@tiptap/react@^3.0.0`

Örnek (app/[slug]/page.tsx):

```tsx
import { TecofApiClient, TecofRender } from "@tecof/theme-editor";
import { editorConfig } from "@/app/editor-config";

const client = new TecofApiClient(process.env.NEXT_PUBLIC_BASE_URL!, process.env.NEXT_PUBLIC_MERCHANT_SECRET_KEY!);

export default async function Page({ params }: { params: Promise<{ slug: string }> }) {
  const { slug } = await params;
  const res = await client.getPublishedPage(slug, "tr");
  if (!res.success || !res.data) return null;
  return <TecofRender data={res.data.draftData} config={editorConfig} />;
}
```

Sürüm geçmişi:

- 0.0.98 — 12 Kas 2026
- 0.0.97 — 15 Eki 2026
- 0.0.96 — 23 Eyl 2026
- 0.0.94 — 21 Eyl 2026
- 0.0.93 — 21 Eyl 2026

Belgeler: [Tecof Studio’ya giriş](https://tecof-app-dev.vercel.app/theme-editor) · [Alanlar](https://tecof-app-dev.vercel.app/editor-fields) · [Yayın render’ı](https://tecof-app-dev.vercel.app/editor-render)

### @tecof/analytics

**Güncel sürüm:** 0.0.3 (28 Tem 2026) · [npm](https://www.npmjs.com/package/@tecof/analytics)

Gizlilik öncelikli, hafif vitrin analitiği: izleme betiğini enjekte eden TecofAnalyticsProvider ve özel olaylar için useTecofAnalytics().

```bash
npm install @tecof/analytics
```

Giriş noktaları:

- `@tecof/analytics` — TecofAnalyticsProvider, useTecofAnalytics (React 18/19)

Peer bağımlılıklar: `react@^18 || ^19`, `react-dom@^18 || ^19`

Örnek (app/layout.tsx):

```tsx
import { TecofAnalyticsProvider } from "@tecof/analytics";

<TecofAnalyticsProvider merchantId={merchantId} />
```

Sürüm geçmişi:

- 0.0.3 — 28 Tem 2026
- 0.0.2 — 13 Tem 2026
- 0.0.1 — 30 Haz 2026

Belgeler: [Tema mimarisi: analytics](https://tecof-app-dev.vercel.app/storefronts#analytics-entegrasyonu)

## Uygulama

Panelde çalışan partner uygulamaları için.

### @tecof/app-sdk

**Güncel sürüm:** 0.1.0 (11 Eki 2026) · [npm](https://www.npmjs.com/package/@tecof/app-sdk)

Partner uygulamalarının sunucu tarafı: oturum token’ı doğrulama, webhook/aksiyon imzası, kurulum token’ı ve /api/v1 istemcisi (siparişler, ayarlar, Vault, metafield, Tools API).

```bash
npm install @tecof/app-sdk
```

Giriş noktaları:

- `@tecof/app-sdk` — TecofApp, createWebhookHandler, verifyActionRequest, client(…) — Node.js ≥ 18

Gereksinim: node >=18

Örnek (lib/tecof.ts):

```ts
import { TecofApp } from "@tecof/app-sdk";

export const tecof = new TecofApp({
  clientId: process.env.TECOF_CLIENT_ID!,
  clientSecret: process.env.TECOF_CLIENT_SECRET!,
});
```

Sürüm geçmişi:

- 0.1.0 — 11 Eki 2026: İlk sürüm: oturum token’ı, imza doğrulama, kurulum token’ı ve /api/v1 istemcisi; sır döndürmede kendiliğinden süresi dolan önceki sır.

Belgeler: [Kimlik ve kapsamlar](https://tecof-app-dev.vercel.app/app-auth) · [Webhook’lar](https://tecof-app-dev.vercel.app/app-webhooks) · [Uygulama API’si](https://tecof-app-dev.vercel.app/app-api)

### @tecof/app-bridge

**Güncel sürüm:** 0.1.0 (11 Eki 2026) · [npm](https://www.npmjs.com/package/@tecof/app-bridge)

Panele gömülü (iframe) uygulamalar için el sıkışma, oturum token’ı, toast, onay, başlık ve gezinme; React sağlayıcısı ve kancaları.

```bash
npm install @tecof/app-bridge
```

Giriş noktaları:

- `@tecof/app-bridge` — Çerçeveden bağımsız köprü istemcisi
- `@tecof/app-bridge/react` — AppBridgeProvider, useSessionFetch ve diğer kancalar

Peer bağımlılıklar: `react@>=18`

Örnek (app/settings/page.tsx):

```tsx
"use client";
import { useSessionFetch } from "@tecof/app-bridge/react";

const fetch = useSessionFetch(); // her isteğe 60 sn'lik oturum token'ını ekler
```

Sürüm geçmişi:

- 0.1.0 — 11 Eki 2026: İlk sürüm.

Belgeler: [App Bridge](https://tecof-app-dev.vercel.app/app-bridge)

### @tecof/app-ui

**Güncel sürüm:** 0.1.0 (11 Eki 2026) · [npm](https://www.npmjs.com/package/@tecof/app-ui)

Tecof panel görünümünde uygulama arayüzü: React Suite 6 + Tailwind CSS 4 + lucide; AppShell, DataTable, StatusBadge, AppForm ve sunucu-güvenli şema (@tecof/app-ui/schema).

```bash
npm install @tecof/app-ui @tecof/app-bridge rsuite lucide-react geist
```

Giriş noktaları:

- `@tecof/app-ui` — İstemci bileşenleri ("use client")
- `@tecof/app-ui/schema` — Sunucu-güvenli şema, doğrulayıcılar, biçimlendiriciler
- `@tecof/app-ui/styles.css` — Tailwind 4 belirteçleri ve React Suite eşlemesi

Peer bağımlılıklar: `react@^19.0.0`, `rsuite@^6.2.0`, `react-dom@^19.0.0`, `lucide-react@>=0.400.0 || ^1.0.0`, `@tecof/app-bridge@^0.1.0`

Örnek (app/globals.css):

```css
@layer theme, base, rsuite, components, utilities;
@import "tailwindcss";
@import "rsuite/dist/rsuite-no-reset.min.css" layer(rsuite);
@import "@tecof/app-ui/styles.css";
```

Sürüm geçmişi:

- 0.1.0 — 11 Eki 2026: İlk sürüm: Tecof uygulama tasarım kimliği, tek şemalı formlar, TR telefon/VKN/TCKN/IBAN doğrulayıcıları.

Belgeler: [Tasarım kimliği](https://tecof-app-dev.vercel.app/app-ui) · [Formlar ve şema](https://tecof-app-dev.vercel.app/app-forms)

### @tecof/invoice-kit

**Güncel sürüm:** 0.2.0 (11 Eki 2026) · [npm](https://www.npmjs.com/package/@tecof/invoice-kit)

Tecof siparişini doğru Türk faturasına çeviren çekirdek: VKN/TCKN, alıcı sınıflandırma, KDV/indirim/yuvarlama, tutarın yazıyla gösterimi, UBL-TR 1.2 XML; fatura uygulamalarının ortak arayüzü (/ui).

```bash
npm install @tecof/invoice-kit
```

Giriş noktaları:

- `@tecof/invoice-kit` — Bağımlılıksız çekirdek (Node ≥ 18 ve tarayıcı)
- `@tecof/invoice-kit/ui` — Fatura uygulaması ekranları (InvoiceShell, ActionFrame…)
- `@tecof/invoice-kit/ui.css` — Arayüz stilleri

Peer bağımlılıklar: `react@^19.0.0`, `rsuite@^6.2.0`, `react-dom@^19.0.0`, `lucide-react@>=0.400.0 || ^1.0.0`, `@tecof/app-ui@^0.1.0`, `@tecof/app-bridge@^0.1.0`

Gereksinim: node >=18

Örnek (lib/invoice.ts):

```ts
import { toInvoiceDraft, buildUblInvoice } from "@tecof/invoice-kit";

const draft = toInvoiceDraft(order, { defaultVatRate: 20 });
if (draft.warnings.some((w) => w.code === "total-mismatch")) {
  // insan kontrolü gerekir
}
```

Sürüm geçmişi:

- 0.2.0 — 11 Eki 2026: @tecof/invoice-kit/ui (fatura uygulamalarının ortak arayüzü); siparişin satır indirim payları kullanılır (KDV matrahı indirim sonrası).
- 0.1.0 — 11 Eki 2026: İlk sürüm: sipariş → Türk faturası çekirdeği ve UBL-TR 1.2.

Belgeler: [Fatura uygulamaları](https://tecof-app-dev.vercel.app/app-invoicing)

## CLI ve AI

Terminal, CI ve AI ajanları için.

### @tecof/cli

**Güncel sürüm:** 0.2.0 (11 Eki 2026) · [npm](https://www.npmjs.com/package/@tecof/cli)

tecof komutu: cihaz akışıyla giriş, tema ve uygulama Spaces’leri, artımlı push, staged sürüm, anında canlıya alma/geri alma, bulut geliştirme, CI token’ları ve ajan modu.

```bash
npm install -g @tecof/cli
```

Kurmadan çalıştırmak için:

```bash
npx @tecof/cli@latest doctor
```

Giriş noktaları:

- `tecof` — Komut satırı (Node.js ≥ 20, çalışma zamanı bağımlılığı yok)

Gereksinim: node >=20

Örnek (Terminal):

```bash
tecof login
tecof doctor
tecof theme ls
```

Sürüm geçmişi:

- 0.2.0 — 11 Eki 2026: Tecof Spaces: tema/uygulama push, numaralı staged sürümler, promote/rollback, JSON makbuzları ve ajan modu; backend sınırlarıyla hizalama ve base-moved yönlendirmesi; `tecof app init` şablonları @tecof/app-ui kullanır.
- 0.1.0 — 11 Eki 2026: İlk sürüm: cihaz akışıyla giriş, `tecof app init / dev / deploy`, uygulama sırrı döndürme; çıkışta token sunucuda iptal edilir.

Belgeler: [CLI başvurusu](https://tecof-app-dev.vercel.app/cli-reference) · [Tema hızlı başlangıç](https://tecof-app-dev.vercel.app/theme-quickstart) · [Uygulama hızlı başlangıç](https://tecof-app-dev.vercel.app/app-quickstart)

### @tecof/mcp

**Güncel sürüm:** 0.2.7 (28 Eyl 2026) · [npm](https://www.npmjs.com/package/@tecof/mcp)

Tema reposunun içinden çalışan stdio MCP sunucusu: bileşen kataloğunu diskten okur, Developer API ile sayfa oluşturur/günceller; remote modda backend araç kataloğunu kullanır.

```bash
npx -y @tecof/mcp@latest
```

Giriş noktaları:

- `tecof-mcp` — stdio MCP sunucusu (Node.js ≥ 20)

Gereksinim: node >=20

Örnek (.mcp.json):

```json
{
  "mcpServers": {
    "tecof": { "command": "npx", "args": ["-y", "@tecof/mcp@latest"] }
  }
}
```

Sürüm geçmişi:

- 0.2.7 — 28 Eyl 2026
- 0.2.6 — 21 Eyl 2026
- 0.2.5 — 19 Eyl 2026
- 0.2.4 — 18 Eyl 2026
- 0.2.3 — 14 Eyl 2026

Belgeler: [Tecof MCP](https://tecof-app-dev.vercel.app/mcp#tecofmcp-stdio-paketi)

## Sürüm politikası

- `0.0.x` sürümlerde npm’in `^` aralığı yalnız aynı yamayı kabul eder (`^0.0.96` = `0.0.96`); yükseltme için sürümü `package.json`’da elle değiştirin.
- `0.x.y` sürümlerde `^0.2.0` yalnız `0.2.x` yamalarını alır.
- Bir temanın ya da uygulamanın kullandığı sürümü `npm ls @tecof/<paket>` ile görebilirsiniz.

---

# Model Context Protocol (MCP)

> Tecof uzak MCP sunucusu (api.tecof.com/mcp): kimlik, kapsamlar, onay ve kredi semantiği, istemci kurulumu ve @tecof/mcp stdio paketi.
>
> Kaynak: https://tecof-app-dev.vercel.app/mcp · Bölüm: AI ve MCP · Son güncelleme: 2018-10-20

Tecof, yapay zekâ ajanlarına (Claude Code, Codex CLI, Gemini CLI, Cursor, Claude Desktop) üç MCP yüzeyi sunar:

| Yüzey | Adres / paket | Ne zaman |
| :--- | :--- | :--- |
| **Uzak MCP sunucusu** | `https://api.tecof.com/mcp` (Streamable HTTP) | Paket kurmadan, tema reposu olmadan; Claude Desktop / claude.ai / Cursor için tek yol |
| **`@tecof/mcp` stdio paketi** | `npx -y @tecof/mcp@latest` — `local` (varsayılan) ya da `remote` mod | Tema reposunun içinde çalışırken (bileşen kataloğu diskten okunur) |
| **Doküman MCP sunucusu** | Bu sitenin `/api/mcp` ucu (stdio: `npm run mcp`) | Bu dokümantasyonu ajana okutmak için ([ayrıntı](https://tecof-app-dev.vercel.app/ai-docs#dokuman-mcp-sunucusu)) |

Üç yüzeyin ortak sözleşmesi: **sayfa ve CMS yazmaları taslaktır, yayını kullanıcı panelden yapar**; ürün ve DNS yazmaları ise anında canlıdır ve onay ister.

---

## Uzak MCP sunucusu: api.tecof.com/mcp

Backend'in araç kayıt defterini doğrudan sunan Streamable HTTP MCP sunucusu. Araç adları, JSON Schema'lar, hata kodları ve sonuç biçimi stdio paketiyle birebir aynıdır; her çağrı aynı koşucudan (kapsam → paket → onay → kredi → handler) geçer.

### Kimlik ve başlıklar

İki yol vardır; ikisi de sonunda bir mağaza + bir kullanıcıya bağlı, kapsamlı bir erişim anahtarı (`tcf_…`) üretir ve `apiAccess` paket özelliği ister:

| Yol | Ne zaman | Nasıl |
| :--- | :--- | :--- |
| **OAuth 2.1** | Claude Desktop / claude.ai bağlayıcısı, Claude Code, Cursor ve OAuth destekleyen diğer istemciler | Adresi ekleyin → istemci `401` sınamasını izleyip Tecof onay sayfasını açar → panelde mağaza, yetkiler ve bağlantı süresi seçilir. Anahtar 8 saatte bir sessizce yenilenir; bağlantı panelin API Anahtarları listesinde “Bağlayıcı” rozetiyle görünür ve oradan iptal edilir |
| **Statik başlık** | CI, betikler, başlık verebilen istemciler | Panelde **Ayarlar → Geliştirici / API Anahtarları** ile anahtar üretip `Authorization: Bearer tcf_…` olarak gönderin |

`code:write`, `sandbox:run` ve `deploy:write` kapsamları OAuth onayında varsayılan kapalıdır ve ayrıca açık onay ister. Ekipten çıkarılan kullanıcının bağlantısı kısa süre içinde geçersiz olur.

```http
POST /mcp
Authorization: Bearer tcf_...
Accept: application/json, text/event-stream
Content-Type: application/json
X-Tecof-Toolsets: pages,cms          # isteğe bağlı
```

| Başlık / parametre | Açıklama |
| :--- | :--- |
| `Authorization: Bearer tcf_…` | Zorunlu: OAuth ile basılan ya da panelde üretilen anahtar. Kimliksiz istek `401` + `WWW-Authenticate: Bearer resource_metadata=…` döner; OAuth istemcileri bu sınamayla onay akışını başlatır. |
| `X-Tecof-Toolsets` ya da `?toolsets=` | Virgülle modül adları (`pages,cms,media,products,domains,code,general`). Yalnız bu modüllerin araçları listelenir; bilinmeyen ad yok sayılır, boş = hepsi. |
| `GET /mcp/health` | Kimliksiz sağlık ucu: `{ ok, name, version, protocolVersions, toolCount }`. |

Sınırlar: IP başına 60 istek/dk (kimlik öncesi), anahtar başına 240 JSON-RPC/dk; araç başına okuma 120/dk, yazma 30/dk (`429 rate-limited`, `Retry-After: 60`). Oturum yoktur (`Mcp-Session-Id` üretilmez); uzun işler tutamaç + durum aracıyla yürür (aşağıda).

### Kapsamlar ve canlıya etkisi

Anahtarı yalnız gereken kapsamlarla üretin. Kapsamı yetmeyen araçlar da listelenir; hata çağrı anında `403 insufficient-scope { required, missing }` olarak döner.

| Kapsam | Araçlar | Canlıya etkisi |
| :--- | :--- | :--- |
| `pages:read` | `list_pages`, `get_page`, `get_preview_url`, `list_components`, `validate_document` | Yok (okuma) |
| `pages:write` | `create_page`, `update_page`, `delete_page` | **Taslak** — yayın panelden. `delete_page` soft delete, onay ister |
| `cms:read` | `list_cms_collections`, `get_cms_collection`, `list_cms_items`, `get_cms_item` | Yok |
| `cms:write` | `create_cms_collection`, `update_cms_collection`, `create_cms_item`, `update_cms_item`, `delete_cms_item` | Yeni içerik **taslak**; yayındaki içeriği değiştirmek/silmek `allowPublishedEdit:true` ile **anında canlı**; şema değişikliği veri kaybettirebilir (`allowFieldLoss`) |
| `media:read` / `media:write` | `list_media` / `import_image` | Kütüphaneye dosya ekler; sayfaya bağlanmadıkça vitrini değiştirmez |
| `ai:generate` | `generate_image` | **Kredi düşer** (`ai-image-generate`, 3 kredi); dosya kütüphaneye gider |
| `products:read` | `list_products`, `get_product`, `get_product_import_template` | Yok |
| `products:write` | `upsert_products`, `delete_product` | **ANINDA CANLI** — `status:"active"` ürünü vitrine çıkarır; önce `dryRun:true`. Silme onay ister |
| `domains:read` | `domain_list`, `domain_check`, `domain_dns_list`, `domain_nameservers_get` | Yok |
| `domains:write` | `domain_dns_upsert`, `domain_dns_delete`, `domain_nameservers_set`, `domain_sync` | **ANINDA CANLI** — DNS/NS değişikliği yayılır; `_upsert/_delete/_set` onay ister |
| `analytics:read` | `analytics_summary`, `store_health_check`, `search_knowledge` | Yok |
| `memory:write` | `remember` | Mağaza için ajan notu kaydeder; vitrine etkisi yok |
| `code:read` | `ide_session_status`, `ide_list_dir`, `ide_read_file`, `ide_list_snapshots`, `theme_repo_tree`, `theme_get_file`, `theme_deploy_status` | Yok (okuma). `.env*`, `.npmrc`, `.git/`, `node_modules/` hiçbir araçtan dönmez |
| `code:write` | `ide_write_files`, `ide_save_draft`, `ide_commit_push`, `theme_commit_files` | Sandbox yazması ve taslak (`tecof-ide-draft`) canlıyı değiştirmez; **`ide_commit_push` / `theme_commit_files` varsayılan dala push eder → Vercel ÜRETİM yayını** (onay ister) |
| `sandbox:run` | `ide_start_session`, `ide_ping`, `ide_exec`, `ide_extend`, `ide_stop`, `ide_snapshot` | Sandbox içinde kod çalıştırma yetkisi (`build/lint/test` paket script'lerini koşar). `ide_start_session` ve `ide_extend` **kredi düşer** (`ide-session`) |
| `deploy:write` | `theme_deploy` | **ANINDA CANLI** — üretim yeniden dağıtımı (onay ister) |

Ayrıca `get_site_context` kapsam istemez — her oturuma onunla başlayın (diller, tema, anahtarın kapsamı ve bitişi).

### Sonuç biçimi

Her araç `content[0].text` (JSON) ve `structuredContent` (aynı veri) döner; başarılı yazmalarda `credit` ve `warnings` alanları eklenebilir.

```json
{
  "content": [{ "type": "text", "text": "{ \"pageId\": \"…\", \"status\": \"draft\", … }" }],
  "structuredContent": { "pageId": "…", "status": "draft", "warnings": [] }
}
```

Hata `isError: true` ile döner; metin `"<messageCode>: <mesaj>" + ipucu`, `structuredContent = { error: messageCode, message, status, …data }`:

| Kod | Anlamı | Ajanın adımı |
| :--- | :--- | :--- |
| `validation-error` | Girdi şemaya/kurala uymuyor (`data.issues[{path,message}]`) | Alanı düzelt, tekrar dene |
| `insufficient-scope` | Anahtarın kapsamı yetersiz (`data.missing`) | Kullanıcıya yeni anahtar üretmesini söyle |
| `confirmation-required` | Onay isteyen araç `confirm:true` olmadan çağrıldı | Aşağıdaki onay akışı |
| `insufficient-credits` | Kredi yetersiz (`data.required`, `data.balance`) | Kullanıcıya bildir; tekrar deneme |
| `plan-feature-unavailable` | Paket bu özelliği kapsamıyor | Kullanıcıya bildir |
| `page-modified` / iyimser kilit `409` | Kayıt siz okuduktan sonra değişti | `get_page` / `get_cms_item` ile yeniden oku, değişikliği tekrar uygula |
| `rate-limited` | Sınır aşıldı | 60 sn bekle; toplu işleri tek çağrıda birleştir |
| `tool-aborted` | İstemci bağlantıyı kesti / zaman aşımı | Durumu `get_*` ile doğrula; düşen kredi iade edilmez |

### Onay semantiği (`confirm:true` + `confirmId`)

Silme ve canlı değişiklik araçları (`delete_page`, `delete_cms_item`, `delete_product`, `domain_dns_upsert`, `domain_dns_delete`, `domain_nameservers_set`, `ide_commit_push`, `ide_extend`, `ide_snapshot`, `theme_commit_files`, `theme_deploy`) `confirm: true` olmadan çalışmaz. İki araçta onay girdiye bağlıdır ve satır içi döner (`data.needsConfirmation:true` + `summary`, `confirmId` yok; aynı girdiyle `confirm:true`): `ide_write_files` içinde `vercel.json`, `ide_exec` ile `npm-install-scripts`. Kural yüzeye göre dürüsttür:

| Yüzey | Kim onaylar | Akış |
| :--- | :--- | :--- |
| MCP / Developer API (PAT) | İstemci — Claude Code'un `anthropic/requiresUserInteraction` prompt'u, Codex `approval_mode = "prompt"` | 1) Araç `confirm` olmadan çağrılır → `409 confirmation-required { needsConfirmation:true, confirmId, summary, expiresAt }` (15 dk). 2) Kullanıcı özeti onaylar. 3) **Aynı girdiyle** `confirm:true` + `confirmId` gönderilir; tek geçişte çalışır (girdi hash'i yeniden kontrol edilir: onaylanan girdi = çalıştırılan girdi). `confirmId` eşleşmezse `409 confirmation-expired` → `confirmId` olmadan tekrar dene, yeni özet üretilir. |
| Panel asistanı | Kullanıcı (sohbette) | Onay yalnız GÜNCEL kullanıcı mesajı `Onaylıyorum, uygula (onay: <confirmId>)` taşıyorsa tüketilir; ardışık iki model çağrısı onay sayılmaz. |

Onay isteyen araçlar `tools/list`'te `_meta["anthropic/requiresUserInteraction"] = true` ve `annotations.destructiveHint` ile işaretlidir — Claude Code otomatik modda bile sorar.

### Kredi

Kredi düşen araçlar katalogda `credit: { operation, cost, managedByHandler }` ile görünür (bugün `generate_image` → `ai-image-generate`, 3 kredi; `ide_start_session` ve `ide_extend` → `ide-session` 5, aktif her 10 dk 1 — `managedByHandler:true`, servis düşer/iade eder; `ide_extend` onaysız ilk çağrıda ücretsizdir). Kural:

- Kapsam, paket ve onay kapılarından geçmeyen çağrı krediye **hiç** ulaşmaz.
- Handler yan etkiden önce hata verirse (doğrulama, servis hatası) kredi iade edilir; istemci bağlantıyı keserse (`tool-aborted`) iade **edilmez** — kredi düşen araçlarda bağlantıyı açık tutun.
- Başarılı yanıtta `credit: { charged, balance }` döner; yetersizse `402 insufficient-credits { required, balance }`.

### Uzun işler ve `booting` oturum akışı

Uzak sunucu oturumsuzdur; dakikalar süren işler tutamaç + durum aracıyla yürür. Örnek, Geliştirme modu (Cloud IDE, `code` toolset'i):

1. `ide_start_session { themeId?, restoreDraft?, fromSnapshotId? }` saniyeler içinde döner: `{ sessionId, status: "booting", reused, pollAfterMs: 5000, hint }`. Kredi (`ide-session`) bu anda düşer; `booting` satırı tema başına boot kilididir — aynı kullanıcının canlı oturumu varsa `reused:true` (kredi yok), başka kullanıcının oturumu varsa `409 session-busy { userId, channel, expiresAt }`. IDE arayüz bağlantısı (vscode) MCP'den asla dönmez.
2. `pollAfterMs` kadar bekleyip `ide_session_status { sessionId }` çağırın; `status` `active` olunca `previewUrl`, `sandboxId`, `expiresAt` gelir. Boot bütçesini (15 dk) aşan oturum `failed` olur (kilit çözülür, `bootError` döner, kredi iade edilir).
3. `ide_list_dir` / `ide_read_file` / `ide_write_files` / `ide_exec` yalnız `active` oturumda çalışır (`booting` dahil aksi hâlde `409 session-not-active { status }`). Yazma/exec/commit oturumu açan kullanıcıya aittir; başka kullanıcının oturumu `409 session-busy` — devralma yalnız onaylı `ide_commit_push` / `ide_snapshot` içinde `takeOver:true` ile (özet kullanıcıyı adlandırır).
4. Yayın: `ide_commit_push { sessionId, message, confirm:true }` varsayılan dala push eder → Vercel **üretim** yayını; `theme_deploy_status` ile izleyin. Süre `ide_extend` (onay + kredi) ile uzar; bitirirken `ide_stop` (taslağı `tecof-ide-draft` dalına kaydeder) ya da `ide_snapshot` (30 gün saklanan görüntü; oturumu bitirir, `fromSnapshotId` ile devam).
5. Sandbox'sız depo işleri: `theme_repo_tree` / `theme_get_file` (HEAD okuma), `theme_commit_files` (onaylı push → üretim), `theme_deploy` (onaylı yeniden dağıtım). Yalnız özel (`isCustom`) temalarda; mağaza temalarında `403 not-custom-theme`.

SSE ilerleme bildirimi (`notifications/progress`) yalnız istemci istekte `_meta.progressToken` gönderdiyse üretilir; ilerleme yük taşımaz, sonuç her zaman araç yanıtındadır.

### İstemci kurulumu

**Claude Code**

```bash
claude mcp add --transport http tecof https://api.tecof.com/mcp --header "Authorization: Bearer ${TECOF_API_TOKEN}"
```

ya da proje kökünde `.mcp.json` (git'e girer, sır içermez — token ortam değişkeninden gelir):

```json
{
  "mcpServers": {
    "tecof": {
      "type": "http",
      "url": "https://api.tecof.com/mcp",
      "headers": { "Authorization": "Bearer ${TECOF_API_TOKEN}" },
      "timeout": 600000
    }
  }
}
```

**Codex CLI** — `~/.codex/config.toml`:

```toml
[mcp_servers.tecof]
url = "https://api.tecof.com/mcp"
bearer_token_env_var = "TECOF_API_TOKEN"
startup_timeout_sec = 20
tool_timeout_sec = 300

[mcp_servers.tecof.tools.delete_page]
approval_mode = "prompt"   # delete_cms_item, delete_product, domain_dns_upsert/delete, domain_nameservers_set için tekrarlayın
```

**Gemini CLI** — `.gemini/settings.json`:

```json
{
  "mcpServers": {
    "tecof": {
      "httpUrl": "https://api.tecof.com/mcp",
      "headers": { "Authorization": "Bearer $TECOF_API_TOKEN" },
      "timeout": 600000
    }
  }
}
```

**Cursor** — `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "tecof": {
      "url": "https://api.tecof.com/mcp",
      "headers": { "Authorization": "Bearer ${env:TECOF_API_TOKEN}" }
    }
  }
}
```

**Claude Desktop / claude.ai** — Settings → Connectors → *Add custom connector* → URL `https://api.tecof.com/mcp` → **Connect**. Tarayıcıda Tecof onay sayfası açılır; mağazayı ve yetkileri seçip onaylayın. Anahtar kopyalamak ya da dosya düzenlemek gerekmez.

**Proje kökünde tek komut** — `tecof setup agent` projenin `.mcp.json` (Claude Code) ya da `.cursor/mcp.json` (Cursor) dosyasına `tecof` sunucusunu sır yazmadan ekler; istemci ilk bağlantıda OAuth onayını açar ([Güvenlik ve CI](https://tecof-app-dev.vercel.app/dev-security#tecof-setup-agent)).

İlk komut her istemcide aynı: *"get_site_context çağır, hangi mağaza ve temaya bağlıyız?"*

---

## `@tecof/mcp` stdio Paketi

Tema reposunun içinden çalışan stdio sunucusu (`npx -y @tecof/mcp@latest`; `.env` içinde `TECOF_API_TOKEN`, `TECOF_API_URL`/`NEXT_PUBLIC_BASE_URL`, isteğe bağlı `TECOF_THEME_ID`). Bileşen kataloğunu diskten (AST) okuduğu için ajan, çalışma ağacındaki bileşen şemasıyla yazar. Ayrıntılı kurulum ve yazarlık biçimi paket README'sindedir.

| Mod | `TECOF_MCP_MODE` | Araçlar nereden | Ne zaman |
| :--- | :--- | :--- | :--- |
| `local` (varsayılan) | — | Paketin kendi 26 aracı; Developer API v1 uçları doğrudan | Tema geliştirme; yayında olmayan bileşenle taslak yazma |
| `remote` | `remote` | Backend kataloğu (`GET /api/v1/tools?surface=mcp`, 38+ araç); çağrılar `POST /api/v1/tools/:name?stream=1` | Backend'e eklenen yeni araçları paket güncellemeden kullanmak; uzak sunucuyla birebir davranış (onay, kredi, hata kodları) |

`remote` modun kuralları:

- **Başlangıç ağa bloklanmaz.** Katalog 3 sn bütçeyle arka planda alınır; yetişmezse paketle gelen snapshot (38 araç) kullanılır ve stderr'e `Katalog: snapshot` yazılır. `tools/list` çevrimdışı da deterministiktir; canlı katalog sonradan gelirse eksik araçlar eklenir (`tools/list_changed`).
- **`TECOF_TOOLSETS=pages,cms`** hem katalog sorgusunu hem snapshot'ı daraltır.
- **Yerel tema kataloğu varsa** (`components/` dizini) `list_components` ve `validate_document` diskten çalışır; `create_page` / `update_page` hibrittir: bölümler yerel katalogla inşa edilip doğrulanır, hazır `document` sunucuya gider ve sunucu kendi (yayındaki tema) kataloğuyla bir kez daha doğrular — yayında olmayan bileşen `unknown-type` ile reddedilir. `components/` yoksa dört araç da sunucudan gelir.
- Her istek `X-Tecof-Surface: mcp` taşır: onay kuralı uzak sunucuyla aynıdır (`confirm:true` + `confirmId`, tek geçiş).
- Sonuç ve hata biçimi yukarıdaki uzak sunucuyla aynıdır; ilerleme yalnız `progressToken` verildiyse iletilir.

---

## Doküman MCP sunucusu

Bu dokümantasyonun kendisi de salt-okunur bir MCP sunucusu olarak sunulur (arama, sayfa okuma, güncel paket sürümleri ve `@tecof/theme-editor` tip tanımları). Mağaza verisine erişmez, kimlik istemez. Kurulum ve araç listesi: [Dokümanı AI ile kullanın](https://tecof-app-dev.vercel.app/ai-docs#dokuman-mcp-sunucusu).

---

# Dokümanı AI ile Kullanın

> Bu dokümantasyonu AI asistanlarına bağlama — llms.txt ve llms-full.txt, her sayfanın .md ikizi, sayfa eylemleri (Markdown/README kopyala, ChatGPT/Claude’da aç) ve salt-okunur doküman MCP sunucusu (HTTP ve stdio).
>
> Kaynak: https://tecof-app-dev.vercel.app/ai-docs · Bölüm: AI ve MCP · Son güncelleme: 2018-10-20

Bu site insanlar için okunur HTML’in yanında AI araçları için makine-okunur yüzeyler yayınlar. Hepsi içerikten **derleme anında üretilir**; elle tutulan bir kopya yoktur, bu yüzden sayfalarla her zaman aynıdır.

| Yüzey | Adres | Ne zaman |
| :--- | :--- | :--- |
| `llms.txt` | [/llms.txt](https://tecof-app-dev.vercel.app/llms.txt) | Bölümlere ayrılmış indeks ([llmstxt.org](https://llmstxt.org) biçimi); her bağlantı sayfanın `.md` ikizine gider |
| `llms-full.txt` | [/llms-full.txt](https://tecof-app-dev.vercel.app/llms-full.txt) | Tüm sayfaların tek Markdown dosyasında birleşimi (bağlantılar mutlak) |
| Sayfa Markdown’ı | `/<sayfa>.md` (ör. [/theme-quickstart.md](https://tecof-app-dev.vercel.app/theme-quickstart.md)) | Tek sayfayı bağlam olarak vermek |
| Doküman MCP | `/api/mcp` | Ajanın arayıp okuması; paket sürümleri ve `@tecof/theme-editor` tip tanımları |
| Arama dizini | `/search-index.json` | Sitenin ⌘K araması (istemci tarafı) |

## Sayfa eylemleri

Her sayfanın başlığındaki düğme grubu:

- **Markdown’ı kopyala** — sayfanın ham Markdown’ını (başlık, açıklama, kaynak adresi ve son güncelleme satırıyla) panoya alır.
- **README olarak kopyala** — aynı içeriği bağlantıları mutlak adrese çevirip kaynak notuyla verir; bir depoya `README.md` ya da ajan talimat dosyası olarak doğrudan konabilir.
- **Markdown’ı görüntüle** — `.md` ikizini açar.
- **ChatGPT’de aç / Claude’da aç** — sayfanın `.md` adresini bağlam olarak veren hazır bir istemle yeni sohbet başlatır.

[Paketler](https://tecof-app-dev.vercel.app/packages) sayfasında ayrıca her paket için **README’yi kopyala** vardır: README npm’den alınır (`/packages/<paket>/readme.md`); npm’de README’si olmayan paket için katalog bilgisinden üretilir.

## Doküman MCP sunucusu

Salt-okunur, kimlik doğrulama istemeyen bir MCP sunucusudur. Aynı araçlar iki taşıma ile sunulur.

| Araç | Ne yapar |
| :--- | :--- |
| `get_docs_outline` | Tüm bölüm ve sayfaları slug, başlık ve açıklamayla listeler |
| `read_doc_page` | Bir sayfanın tam Markdown’ını döndürür (`slug`; `packages` dahil) |
| `search_docs` | Türkçe-duyarlı arama; sayfa adresi ve alıntıyla en iyi eşleşmeler (`query`, `limit`) |
| `get_package_versions` | Tüm `@tecof/*` paketlerinin güncel sürümü, kurulum komutu, peer bağımlılıkları |
| `list_exported_types` | `@tecof/theme-editor`’ün gerçekten dışa aktardığı adlar (`filter` isteğe bağlı) |
| `read_type_definition` | Bir adın `dist/index.d.ts` içindeki gerçek TypeScript bildirimi (`symbol`) |

Kaynaklar: `tecof-docs://llms.txt`, `tecof-docs://pages/<slug>` ve `tecof-docs://types/theme-editor` (paketin tam tip dosyası).

Sunucu bağlanan asistana şu talimatı verir: önce `search_docs` ile ara, kod önermeden önce `read_doc_page` ile sayfanın tamamını oku, belgede olmayan API uydurma; `@tecof/theme-editor` sorularında çelişki varsa `read_type_definition` ile gerçek bildirimi doğrula.

### Uzak (Streamable HTTP)

Durumsuz (stateless) çalışır; her istek kendi sunucu örneğini açıp kapatır.

```bash
claude mcp add --transport http tecof-docs https://tecof-app-dev.vercel.app/api/mcp
```

```json title=".mcp.json"
{
  "mcpServers": {
    "tecof-docs": { "type": "http", "url": "https://tecof-app-dev.vercel.app/api/mcp" }
  }
}
```

```json title=".cursor/mcp.json"
{
  "mcpServers": {
    "tecof-docs": { "url": "https://tecof-app-dev.vercel.app/api/mcp" }
  }
}
```

Claude.ai ve ChatGPT’de: **Ayarlar → Connectors → Özel bağlayıcı ekle** ve aynı adresi girin. `GET /api/mcp` insan ve ajanlar için bir tanıtım belgesi döner; MCP istekleri `POST` ile gelir.

> [!NOTE] Alan adı
> Örneklerdeki adres sitenin yayın adresidir ve derleme sırasında `NEXT_PUBLIC_SITE_URL` değerinden gelir. Site başka bir alan adına taşınırsa kendi MCP yapılandırmanızdaki adresi de güncelleyin.

### Yerel (stdio)

Depoyu klonladıysanız aynı sunucuyu yerelde çalıştırabilirsiniz:

```bash
npm install
npm run mcp
```

```json title=".mcp.json"
{
  "mcpServers": {
    "tecof-docs": {
      "command": "npx",
      "args": ["tsx", "/MUTLAK/YOL/tecof-app-dev/scripts/mcp-server.ts"]
    }
  }
}
```

Sunucu içeriği ve `node_modules`’u depo kökünden okur; betik çalışma dizinini kendisi depo köküne sabitler.

## Hangi MCP ne için

| Sunucu | Adres | İçerik |
| :--- | :--- | :--- |
| Doküman MCP (bu sayfa) | `/api/mcp` | Belgeler, paket sürümleri, editör tipleri — salt okunur, kimliksiz |
| [Tecof MCP](https://tecof-app-dev.vercel.app/mcp) | `https://api.tecof.com/mcp` | Mağazanızın verisi: sayfalar, CMS, ürünler, tema, raporlar — kimlik ve kapsam ister |
| [`@tecof/mcp`](https://tecof-app-dev.vercel.app/mcp#tecofmcp-stdio-paketi) | stdio | Tema reposunun içinden bileşen kataloğuyla sayfa yazma |

Kodlama ajanı kurarken ikisini birlikte vermek iyi sonuç verir: ajan belgeyi doküman MCP’sinden okur, değişikliği Tecof MCP ya da CLI ile yapar. Proje kökünde `tecof setup agent` uzak Tecof MCP’sini yapılandırır ([Güvenlik ve CI](https://tecof-app-dev.vercel.app/dev-security#tecof-setup-agent)).

---

# Yapay Zeka Destekli Alışveriş Ajanları

> AI alışveriş ajanlarını vitrin API’lerine güvenli bir sunucu araç katmanıyla bağlama: önerilen araçlar, şemalar, güvenlik kuralları ve analytics olayları.
>
> Kaynak: https://tecof-app-dev.vercel.app/agents · Bölüm: AI ve MCP · Son güncelleme: 2018-10-20

Tecof alışveriş ajanları için önerilen yol, mevcut storefront API'lerini güvenli bir server-side tool katmanı arkasından kullanmaktır. Ajan doğrudan browser secret key'i veya customer token'ı taşımamalı; sizin backend'iniz Tecof API ile konuşmalıdır.

---

## Temel Akış

```mermaid
sequenceDiagram
    participant User as Kullanıcı
    participant Agent as AI Ajan
    participant Tools as Tool Backend
    participant Tecof as Tecof Store API

    User->>Agent: "Kırmızı ayakkabı bul"
    Agent->>Tools: search_products(query)
    Tools->>Tecof: GET /api/store/ecommerce/products?search=...
    Tecof-->>Tools: Ürün listesi
    Tools-->>Agent: Normalize ürün sonucu
    Agent->>User: Ürünleri önerir
    User->>Agent: "Sepete ekle"
    Agent->>Tools: validate_cart(items)
    Tools->>Tecof: POST /api/store/ecommerce/cart/validate
    Tools->>Tecof: POST /api/store/ecommerce/checkout-session
    Tools-->>Agent: redirectUrl
    Agent->>User: Checkout bağlantısı verir
```

---

## Önerilen Tool Seti

Bu isimler ajan tarafındaki soyut tool isimleridir; altta çağırmaları gereken gerçek Tecof endpointleri tabloda verilmiştir.

| Tool | Tecof endpoint | Not |
| :--- | :--- | :--- |
| `search_products` | `GET /api/store/ecommerce/products` | `search`, `category`, `brand`, `minPrice`, `maxPrice`, `tag`, `sort` destekler |
| `get_product` | `GET /api/store/ecommerce/products/:slug` | Ürün detayını slug ile getirir |
| `get_categories` | `GET /api/store/ecommerce/categories` | Kategori ağacı |
| `get_search_suggestions` | `GET /api/store/ecommerce/search/suggest` | Autocomplete için |
| `validate_cart` | `POST /api/store/ecommerce/cart/validate` | Stok, fiyat ve otomatik indirimleri doğrular |
| `validate_coupon` | `POST /api/store/ecommerce/coupon/validate` | Kupon/free shipping kontrolü |
| `get_shipping_rates` | `POST /api/store/ecommerce/shipping/rates` | Adrese göre kargo |
| `create_checkout_session` | `POST /api/store/ecommerce/checkout-session` | Hosted checkout redirect URL'i üretir |
| `get_cms_items` | `POST /api/store/cms/collections/:slug/items` | Canlı CMS içeriği |

---

## Tool Şema Örnekleri

### `search_products`

```json
{
  "name": "search_products",
  "description": "Tecof mağazasında aktif ürünleri arar.",
  "input_schema": {
    "type": "object",
    "properties": {
      "query": { "type": "string" },
      "locale": { "type": "string", "default": "tr" },
      "limit": { "type": "number", "default": 5 },
      "category": { "type": "string" },
      "minPrice": { "type": "number" },
      "maxPrice": { "type": "number" }
    },
    "required": ["query"]
  }
}
```

### `create_checkout_session`

```json
{
  "name": "create_checkout_session",
  "description": "Doğrulanmış sepet için hosted checkout oturumu oluşturur.",
  "input_schema": {
    "type": "object",
    "properties": {
      "items": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "productId": { "type": "string" },
            "variantId": { "type": "string" },
            "quantity": { "type": "number" }
          },
          "required": ["productId", "quantity"]
        }
      },
      "locale": { "type": "string", "default": "tr" },
      "successUrl": { "type": "string" },
      "failUrl": { "type": "string" }
    },
    "required": ["items"]
  }
}
```

---

## Güvenlik Kuralları

1. `x-secret-key` değerini ajan istemcisine vermeyin; tool backend içinde tutun.
2. Customer token gereken işlemleri sadece kullanıcı oturumu doğrulandıktan sonra yapın.
3. Checkout için mümkünse `checkout-session` üretip kullanıcıyı hosted ödeme akışına yönlendirin.
4. Ajanın ürün fiyatı veya stok bilgisini model hafızasından değil, her istekte `cart/validate` sonucundan okumasını sağlayın.
5. Webhook veya admin işlemlerini AI ajanına doğrudan açmayın; ayrı izin katmanı kullanın.

---

## Analytics Eventleri

Ajan destekli storefront deneyimlerinde checkout davranışı için mevcut analytics event tipleri kullanılabilir:

| Event | Kullanım |
| :--- | :--- |
| `cart_add` | Ajan önerisiyle ürün sepete eklendiğinde |
| `cart_remove` | Sepetten ürün çıkarıldığında |
| `checkout_start` | Hosted checkout veya ödeme adımı başladığında |

Bu eventler `POST /api/analytics/event` üzerinden toplanır ve live analytics ekranında davranış metriklerine katkı verir.

---

## Mağazanın AI dosyaları

Ajanların mağazayı araç çağırmadan da anlayabilmesi için Tecof mağaza kökünde `agents.md`, `llms.txt`, `llms-full.txt` ve `/ai/*.json` (katalog, koleksiyonlar, bilgi merkezi, içerik dizini) yayınlar; ajan kaynaklı ödeme bağlantıları `utm_source=ai_agent` taşır. Dosyaların içeriği, site türüne göre farkları ve tema proxy’si: [GEO: AI Storefront](https://tecof-app-dev.vercel.app/ai-storefront).

---

# Tema SEO’su

> Tecof temalarında SEO — platformun hazır verdiği sitemap, robots.txt, alan adı ve sayfa düzeyi noindex, meta/OG alanları, çok dilli adresler ve 301’ler, özel kod, ürün beslemeleri; tema tarafında hreflang ve JSON-LD ekleme.
>
> Kaynak: https://tecof-app-dev.vercel.app/seo-geo · Bölüm: SEO ve GEO · Son güncelleme: 2018-10-20

Bu sayfa bir Tecof temasında arama motoru görünürlüğünün nasıl çalıştığını anlatır: platformun hazır verdiği parçalar ve tema geliştiricinin eklemesi gerekenler. Üretken yapay zekâ motorları için mağaza dosyaları ayrı sayfada: [GEO: AI Storefront](https://tecof-app-dev.vercel.app/ai-storefront).

## Platformun hazır verdikleri

| Konu | Nasıl çalışır |
| :--- | :--- |
| Sitemap | `app/sitemap.ts`; sayfalar ve ürün/kategori/marka/CMS detay sayfaları backend’den gelir |
| robots.txt | `app/robots.txt/route.ts`; panelde girilen içerik ya da varsayılan kurallar backend’den proxy’lenir |
| Alan adı düzeyi noindex | Panelde “arama motorlarına kapalı” alan adı (ücretsiz `tecof.site` alt alan adı varsayılan olarak kapalı) ve yapım aşaması tüm sayfalarda `noindex` basar |
| Sayfa düzeyi noindex | Panel → sayfa ayarları → SEO; şablon sayfadan türeyen ürün/CMS sayfalarına miras geçer |
| Meta ve OG | Sayfa başına başlık, açıklama ve OG görseli; CMS şablon sayfalarında token’larla doldurulur |
| Çok dilli adresler | `/[locale]/[...slug]`, dile özel adresler ve doğru dilin adresine 301 |
| Özel kod | Sayfa başına `<head>` ve gövde kodu (piksel, doğrulama etiketi) |
| Ürün beslemeleri | Google Merchant / Meta XML ve OpenAI CSV kataloğu (panel → E-ticaret → Ayarlar → Beslemeler) |

### Sitemap

Mutlak adresler **ziyaret edilen host’tan** türetilir: aynı tema hem mağazanın kendi alan adında hem `tecof.site` alt alan adında yayında olabilir ve Google, sitemap’i hangi host’tan çektiyse içindeki adreslerin de o host’ta olmasını ister. Sıra: istek host’u → mağazanın birincil alan adı → `NEXT_PUBLIC_SITE_URL`. Adres çözülemezse **boş** sitemap döner (yanlış host’a işaret eden sitemap zararlıdır). Sitemap saatte bir yenilenir.

### robots.txt

Tema `GET /api/store/robots.txt?host=<host>` ucunu vitrin anahtarıyla proxy’ler; panelde içerik yoksa backend varsayılan kuralları döner. Backend’e ulaşılamazsa şu yedek servis edilir:

```text
User-agent: *
Allow: /
Disallow: /api/
Disallow: /editor/
Disallow: /preview-component/
Disallow: /*/preview-component/
Disallow: /preview-template/
Disallow: /preview-starter/
```

Önizleme rotaları kimlik doğrulaması istemez; `noindex` arama motorunu keser, erişimi değil. Bu rotalarda gizli veri basmayın.

### noindex kuralları

- **Alan adı düzeyi** karar kök layout’ta, `merchant-info`’daki `noIndex` (istek host’una göre) ya da `isUnderConstruction` ile verilir ve tüm sayfalara geçer.
- **Sayfa düzeyi** `robots` yalnız sayfa kapalıyken yazılır. Açık sayfada `index: true` yazmayın: Next.js’te sayfanın `robots` alanı layout’unkini tamamen ezer ve alan adı düzeyindeki kapatma (ör. `tecof.site`) sessizce kalkar.
- Başlangıç içeriğiyle gelen sayfalar, mağaza metinleri düzenleyip yayınlayana kadar `noindex` doğar; şablonların değeri türeyen detay sayfalarına miras geçer.

```ts title="app/[locale]/[...slug]/page.tsx (özet)"
export async function generateMetadata({ params }) {
  const { slug, locale } = await params;
  const page = await getPageData(slug.join("/"), locale, false);
  if (!page) return {};
  return {
    title: page.metaTitle || undefined,
    description: page.metaDescription || undefined,
    ...(page.noIndex && { robots: { index: false, follow: false } }),
    openGraph: { title: page.metaTitle || undefined, description: page.metaDescription || undefined },
  };
}
```

### Çok dilli adresler

`POST /api/store/render` yanıtı istenen dilin adresini (`localizedSlug`), dil → adres haritasını (`slugAlternates`) ve adres o dile ait değilse 301 hedefini (`redirectTo`) taşır. Çekirdek tema yanlış dilin adresini kalıcı olarak doğru adrese yönlendirir (`/en/blog/ilk-yazi` → `/en/blog-en/first-post`) ve haritayı dil değiştiricide kullanır. Taslak önizlemede yönlendirme yapılmaz.

## Temada eklemeniz gerekenler

### hreflang

Çekirdek tema `slugAlternates` haritasını bugün yalnız dil değiştiricide kullanır. Arama motorlarına dil karşılıklarını bildirmek için `generateMetadata` içinde `alternates.languages` üretin:

```ts
const base = `https://${host}`;
return {
  // …
  alternates: {
    canonical: `${base}/${locale}/${page.localizedSlug ?? slug.join("/")}`,
    languages: Object.fromEntries(
      Object.entries(page.slugAlternates ?? {}).map(([code, path]) => [code, `${base}/${code}/${path}`]),
    ),
  },
};
```

### Yapılandırılmış veri (JSON-LD)

Platform JSON-LD üretmez; ürün, içerik ve işletme bilgisini temanız basmalıdır. Ürün detay bölümünde:

```tsx title="components/ProductJsonLd.tsx"
export function ProductJsonLd({ product, url }: { product: Product; url: string }) {
  const data = {
    "@context": "https://schema.org",
    "@type": "Product",
    name: product.name,
    image: product.images,
    description: product.description,
    sku: product.sku,
    brand: product.brand ? { "@type": "Brand", name: product.brand } : undefined,
    offers: {
      "@type": "Offer",
      url,
      priceCurrency: product.currency,
      price: product.price,
      availability: product.inStock ? "https://schema.org/InStock" : "https://schema.org/OutOfStock",
    },
  };
  return <script type="application/ld+json" dangerouslySetInnerHTML={{ __html: JSON.stringify(data).replace(/</g, "\\u003c") }} />;
}
```

Önerilen şemalar: ürün sayfasında `Product` + `BreadcrumbList`, blog yazısında `Article` (ya da `BlogPosting`), ana sayfada `Organization` + `WebSite`, SSS bölümünde `FAQPage`. Değerleri her zaman vitrin API’sinin döndüğü gerçek veriden üretin; `<` karakterini kaçırın.

### Görseller ve performans

- Görselleri `TecofPicture` ile basın; boyut varyantları ve odak noktası otomatik uygulanır ([Yayın render’ı](https://tecof-app-dev.vercel.app/editor-render#tecofpicture)). Anlamlı `alt` metni verin.
- Hero görselinde `loading="eager"` ve Next.js `Image` ile `priority`; diğerlerinde tembel yükleme.
- Studio stil CSS’i sayfa başına yalnız kullanılan sınıflarla üretilir; ek CSS yükü getirmez.

## SEO kontrol listesi

- [ ] Sayfa başlığı ve açıklaması her yayın sayfasında dolu; ürün/CMS şablonlarında token’larla.
- [ ] OG görseli tanımlı; görseller `TecofPicture` ile ve `alt` metniyle.
- [ ] Sayfa düzeyinde yalnız gerçekten gizlenecek sayfalar `noindex`.
- [ ] Mağazanın kendi alan adı birincil alan adı olarak seçili; `tecof.site` kapalı.
- [ ] `sitemap.xml` ve `robots.txt` canlı host’ta doğru adresleri veriyor.
- [ ] Çok dilli mağazada `hreflang` alternatifleri basılıyor.
- [ ] Ürün sayfalarında `Product` JSON-LD var.
- [ ] Ürün beslemesi Merchant Center’a bağlı.

---

# GEO: AI Storefront

> Üretken yapay zekâ görünürlüğü (GEO) için AI Storefront — mağaza kökündeki agents.md, llms.txt, llms-full.txt ve /ai/*.json dosyaları, site türleri (kurumsal, e-ticaret, hibrit), bilgi merkezi, tema proxy’si, WebMCP ve UTM takibi.
>
> Kaynak: https://tecof-app-dev.vercel.app/ai-storefront · Bölüm: SEO ve GEO · Son güncelleme: 2018-10-20

Arama giderek ChatGPT, Gemini, Claude ve Perplexity gibi yanıt motorlarına kayıyor. **GEO** (generative engine optimization), bu motorların mağazanızı doğru anlaması, doğru alıntılaması ve ziyaretçiyi doğru sayfaya göndermesi için yapılan çalışmadır. Tecof bunu **AI Storefront** ile sunar: panelden açıldığında mağazanın kökünde standart, makine-okunur dosyalar yayınlanır.

## Yayınlanan dosyalar

Dosyalar backend’de (`/api/store/ai/*`, vitrin anahtarıyla) üretilir ve tema kökünden proxy’lenir; AI tarayıcıları başlık gönderemediği için anahtarı sunucu tarafında tema ekler.

| Dosya | İçerik | E-ticaret | Kurumsal | Hibrit |
| :--- | :--- | :---: | :---: | :---: |
| `/agents.md` | Ajanlar için yönlendirici rehber: kurallar, politikalar, kaynak adresleri | ✓ | ✓ | ✓ |
| `/llms.txt` | llmstxt.org biçiminde kısa indeks | ✓ | ✓ | ✓ |
| `/llms-full.txt` | Tüm bağlamın birleşik metni | ✓ | ✓ | ✓ |
| `/ai/knowledge.json` | Bilgi merkezi: marka, politikalar, SSS, kurallar (şema 2) | ✓ | ✓ | ✓ |
| `/ai/content.json` | Sayfa + CMS içerik dizini ve hizmetler | — | ✓ | ✓ |
| `/ai/catalog.json` | Aktif ürünler, fiyat, stok, UTM’li ödeme bağlantısı | ✓ | — | ✓ |
| `/ai/collections.json` | Kategori ağacı | ✓ | — | ✓ |
| `/ai/products/<slug>.json` | Tek ürün | ✓ | — | ✓ |

Uygulanmayan uç `404` ve `messageCode: "not-applicable"` döner. AI Storefront kapalıysa dosyalar `404`’tür. Değişiklikler önbellekler nedeniyle en geç ~30 dakikada görünür.

## Site türü

Dosyaların içeriği mağazanın türüne göre değişir; kurumsal bir siteye ürün kataloğu ya da uydurma kargo/iade metni yazılmaz.

| Tür | Ne zaman | Yayınlanan |
| :--- | :--- | :--- |
| `ecommerce` | Mağaza ürün tipi e-ticaret (varsayılan) | Katalog, koleksiyonlar, satış politikaları |
| `website` | Ürün tipi kurumsal ya da panelde açıkça seçildi | Sayfalar, içerik dizini, hizmetler, iletişim; satış dosyaları yok |
| `hybrid` | Yalnız panelde açık seçimle | İkisi birden |

Bilgi merkezinde (panel → Ayarlar → SEO → AI Storefront) hizmetler, hizmet bölgesi, çalışma saatleri, iletişim kanalları, randevu/teklif süreci, fiyatlandırma yaklaşımı ve referanslar tutulur; uygulanmayan alanlar “Uygulanmaz” işaretlenir ve “bu işletme için geçerli değil” olarak yayınlanır. **AI ile doldur** yayındaki sayfa, CMS ve ürünlerden taslak üretir (kaydetmez; içerik yoksa kredi düşmez).

## Örnek: `catalog.json`

```json
{
  "store": { "name": "Örnek Mağaza", "currency": "TRY", "language": "tr", "domain": "https://ornek.com" },
  "products": [
    {
      "id": "60c72b2f9b1d8e001c888888",
      "title": "Minimalist deri cüzdan",
      "price": 850,
      "compareAtPrice": 1200,
      "currency": "TRY",
      "availability": "in_stock",
      "url": "https://ornek.com/products/minimalist-deri-cuzdan",
      "checkout_url": "https://ornek.com/checkout?variant=…&utm_source=ai_agent&utm_medium=agentic&utm_campaign=ai_storefront",
      "slug": "minimalist-deri-cuzdan"
    }
  ],
  "total": 1,
  "generated_at": "2026-10-11T02:00:00.000Z"
}
```

`checkout_url` adresleri `utm_source=ai_agent`, `utm_medium=agentic`, `utm_campaign=ai_storefront` taşır; AI ajanlarından gelen ziyaret ve dönüşümler analitikte ayrıca görünür.

## Örnek: `knowledge.json` (şema 2)

```json
{
  "schemaVersion": 2,
  "siteMode": "website",
  "store": { "name": "Örnek Mimarlık", "url": "https://ornek.com/tr", "language": "tr" },
  "brand": { "about": "…", "tone": "kurumsal" },
  "commerce": null,
  "business": { "services": [{ "name": "İç mimari", "summary": "…", "path": "/tr/hizmetler/ic-mimari" }], "serviceArea": "İstanbul" },
  "notApplicable": [],
  "faq": [{ "question": "Keşif ücretli mi?", "answer": "…" }],
  "aiRules": ["Fiyat sorulursa teklif formuna yönlendir."],
  "generated_at": "2026-10-11T02:00:00.000Z"
}
```

Yayınlanmayan alan `null` döner. E-ticaret modunda eski üst düzey `policies`, `sizeChart`, `usageTips` alanları geriye uyum için korunur.

## Tema tarafı

Tecof çekirdek teması ve türevleri dosyaları kök rotalardan proxy’ler; özel tema yazıyorsanız aynı rotaları koruyun:

```ts title="app/ai/[...path]/route.ts (özet)"
const ALLOWED = /^(catalog\.json|collections\.json|knowledge\.json|content\.json|products\/[a-z0-9-]+\.json)$/;

export async function GET(req: NextRequest, { params }: { params: Promise<{ path: string[] }> }) {
  const joined = (await params).path.join("/");
  if (!ALLOWED.test(joined)) return Response.json({ error: "not-found" }, { status: 404 });
  const res = await fetch(`${process.env.NEXT_PUBLIC_BASE_URL}/api/store/ai/${joined}${req.nextUrl.search}`, {
    headers: { "x-secret-key": process.env.NEXT_PUBLIC_MERCHANT_SECRET_KEY! },
    next: { revalidate: 600 },
  });
  return new Response(await res.text(), {
    status: res.status,
    headers: { "Content-Type": res.headers.get("content-type") || "application/json; charset=utf-8" },
  });
}
```

- İzin listesi dışındaki yollar `404` döner; proxy açık bir röleye dönüşmez.
- `agents.md`, `llms.txt` ve `llms-full.txt` aynı kalıpla `app/<dosya>/route.ts` altında proxy’lenir (30 dk önbellek).
- `GET /api/store/merchant-info` yanıtındaki `ai: { enabled, mode }` temanın AI özelliklerini açıp kapatması içindir.

### WebMCP

Tecof temaları tarayıcıdaki ajanlara WebMCP araçları da sunabilir: site araçları `/ai/content.json` ve `/ai/knowledge.json`’u bir kez okuyup istemcide arama yapar; e-ticaret araçları vitrin API’lerini kullanır. Site araçları `ai.enabled` açıkken kaydedilir. Kaynak: çekirdek temada `lib/webmcp/`.

## GEO kontrol listesi

- [ ] Panelde AI Storefront açık ve site türü doğru (kurumsal sitede `website`).
- [ ] Bilgi merkezinde marka özeti, SSS ve uygulanan politikalar dolu; uygulanmayanlar işaretli.
- [ ] Tema `/agents.md`, `/llms.txt`, `/llms-full.txt` ve `/ai/*` rotalarını proxy’liyor.
- [ ] `robots.txt` AI tarayıcılarını engellemiyor ([Tema SEO’su](https://tecof-app-dev.vercel.app/seo-geo#robotstxt)).
- [ ] Ürün ve sayfa meta açıklamaları dolu; AI yanıtları çoğunlukla bunları alıntılar.
- [ ] Ajan kaynaklı dönüşümler `utm_source=ai_agent` ile izleniyor.