@rglc/storefront-sdk

biltekv2 vitrin veri katmanı. Tenant vitrin repoları tasarımı yazar; API istemcisi, veri hook'ları, i18n/SEO ve sepet/üyelik context'leri buradan gelir.

Kurulum (tenant vitrin repo'su)

npm'de yayında (public): npm i @rglc/storefront-sdk — monorepo içindeki tüketiciler aynı adı workspace'ten çözer. Peer bağımlılıklar: react, react-dom, react-router-dom. Kaynak TS dağıtılır — Vite derler. Sürüm çıkarma: version bump + npm publish (2FA kodu sorar), tüketici repo'lar npm update ile alır.

.env:

VITE_API_URL=https://api.merkez.example   # merkez backend
# VITE_TENANT_SLUG=musteri-kodu           # opsiyonel sabitleme (tek tenant build)

Tenant çalışma zamanında çözülür: ?tenant= parametresi (panel "Vitrini Aç" böyle yönlendirir; localStorage'a yazılır) > localStorage'daki son seçim > VITE_TENANT_SLUG. Hiçbiri yoksa TENANT_SLUG null döner — uygulama tenant kapısı göstermeli (örnek: monorepo storefront/src/main.tsx TenantGate). Prod'da domain çözümüne geçilecek.

Sağlayıcı iskeleti

<SiteProvider>          {/* /site config'i bir kez çeker; Router'dan ÖNCE */}
  <BrowserRouter basename={dilOneki}>
    <LocaleProvider ...>
      <CustomerProvider>
        <CartProvider>
          <App />

Örnek kurulum: monorepo storefront/src/main.tsx (LocaleRoot dil önekini Router basename'ine çevirir).

Veri hook'ları

Elle fetch/useEffect YAZMA — hook kullan, eksikse SDK'ya hook ekle. Hepsi aktif dili otomatik ekler, { ..., loading, error } döner, hata sayfayı çökertmez. Ürün hook'ları tenant'ta e-ticaret kapalıysa istek atmaz (boş döner).

useProducts({ featured: true, pageSize: 8 })
useFeaturedProducts(8)        // işaretli yoksa en yeniye düşer
useProduct(slug)
useCategories()
useContents("blog", { page })
useEntry("sayfalar", "hakkimizda")
useShopSettings()             // önbellekli, tek istek
useForm("talep")              // panelde kurulan dinamik form tanımı
useCaptcha()                  // güvenlik sorusu — form/iletişim gönderiminde zorunlu

Diğerleri: useSite() (siteName/ecommerce/menü/contentTypes), useLocale(), useCart(), useCustomer(), useT() (UI sözlüğü), storefrontApi/ customerAuthApi (ham istemci), renderFieldValue vb. içerik renderer'ları.

İçerik alanlarını okuma (entry.data)

Panelde kurulan modülün alanları entry.data'da alan anahtarıyla durur (etiketle değil — anahtar panelde İçerik Tipleri → alan kartında görünür). Değerler unknown tiplidir; tema tarafında küçük guard'larla okuyun (referans: insaat-tema src/lib/content.ts — asText/asMedia/asRows).

const { entries } = useContents("anasayfa_icerikleri");
const hp = entries[0]; // tek kayıtlık tipte ilk yayınlı kayıt

<h2>{asText(hp?.data.baslik) || t.fallbackBaslik}</h2>

Tip → değer şekli: TEXT/SELECT/DATE string (RICHTEXT HTML string) · NUMBER number · BOOLEAN boolean · MEDIA_IMAGE PublicMediaRef (mediaUrl/mediaSrcSet ile bas) · REPEATER satır dizisi · RELATION çözülmüş hedef (içerik {documentId, locale, data}, ürün {id, name, slug, images}) · LINK dış URL string ya da iç bağlantı {kind, ctKey, slug, documentId, label} / {kind: "product", slug, name}.

Dikkat: yalnız PUBLISHED kayıt gelir ve yayınlama dil başınadır (yalnız TR yayınlıysa /en tarafında entries boş döner — || fallback deseni kullanın). Alan anahtarı API sözleşmesidir; sonradan değiştirmek data.anahtar okumalarını sessizce boşa düşürür. Ayrıntılı örnekler panel dokümantasyonunda: /panel/dokumantasyon → "İçerik Alanlarını Kodda Okuma".

Dinamik formlar + captcha (0.2.0)

Panelde "Formlar"dan kurulan formlar useForm(key) ile çekilir, storefrontApi.submitForm(key, { data, locale, captchaToken, captchaAnswer }) ile gönderilir; alan etiketi fieldLabelFor(field, locale), form metası formMetaFor(form, locale). KIRICI DEĞİŞİKLİK: sendContact artık captchaToken + captchaAnswer ister — token useCaptcha()/getCaptcha()dan alınır, TEK kullanımlıktır (başarısız gönderimde refresh() ile yenile). Referans arayüz: monorepo storefront/src/pages/DynamicFormPage.tsx ve components/CaptchaField.tsx.