Crafter Storefront ve Headless web uygulamaları için resmi JavaScript / TypeScript istemci kütüphanesidir.
Crafter Liquid temalarındaki hardcoded fetch() isteklerini ortadan kaldırmak, API versiyonlamasını (v2 vs düz rotalar) soyutlamak, çift çalışma modunu (Liquid Storefront Proxy vs Harici Doğrudan Backend) otomatik yönetmek ve reaktif bir arayüz deneyimi sunmak amacıyla sıfırdan geliştirilmiştir.
Her modülün ayrıntılı parametreleri, dönüş modelleri ve tema kodlama örnekleri için 📚 Wiki Rehberleri dizinine göz atabilirsiniz:
- 🔐 01. Kimlik Doğrulama (
crafter.auth) — Giriş, Kayıt, Oyun içi (/web) Hızlı Giriş, 2FA, OTP, Şifre Sıfırlama, Discord - 👤 02. Kullanıcılar & Profil (
crafter.users) — Profil, Hafif Bakiye, Transfer, Duvar, 2FA Ayarları, Discord Bağlantısı - 🛒 03. Mağaza & Sepet (
crafter.store&cart) — Kategoriler, Ürünler, Sepet Satın Alımı, Toplu İndirim - 📦 04. Oyuncu Sandığı (
crafter.chest) — Web Envanteri, Eşya Kullanma ve Arkadaşa Hediye Etme - 🎫 05. Destek Talepleri (
crafter.tickets) — Talep Açma, Mesajlaşma, Departmanlar, Bilet Kapatma/Açma - 📰 06. Duyurular & Sayfalar (
posts&pages) — Haberler, Beğeniler, Kullanıcı Beğenileri, CMS Sayfaları - 💳 07. Ödeme İşlemleri (
crafter.payments) — PayTR, Shopier, CrafterPayments, Ödeme Başlatma ve Sorgulama - 🎟️ 08. Kuponlar & Kodlar (
coupons&redeemCode) — Sepet Kuponu Kontrolü, Promosyon ve Hediye Kartları - 📊 09. İstatistikler & Cezalar (
statistics&punishments) — Canlı Akış, Leaderboard, Ban/Mute Listesi ve Arama - 🌐 10. Sunucular & Oy Verme (
servers&vote) — Sunucu Ping/Oyuncu Sayısı, Oy Siteleri ve Bekleme Süreleri - 📜 11. Hukuki Belgeler & Şikayet (
legal&reports) — Kurallar, Gizlilik Politikası, Kural İhlali Şikayeti - 💬 12. Forum & Yardım Merkezi (
forum&helpcenter) — Forum Konuları, Mesajlar, Beğeni, Bilgi Bankası Makaleleri - 📝 13. Yetkili Başvuru Formları (
staffForms) — Dinamik Soru Formları ve Başvuru Gönderme - 🔍 14. Arama, SEO, LuckPerms & Site Bilgisi — Canlı Navbar Arama, SEO & Sitemap, Oyun İçi Rank
- ⚡ 15. Event Bus & Hata Yönetimi — Reaktif Olaylar (
crafter.on),CrafterErrorve Dual-Mode - ✍️ 16. Lexical Zengin Metin Motoru (
crafter.utils) — AST -> HTML/Text dönüştürücü ve Storefront Liquid filtresi eşleniği
🌟 Çalışır Durumdaki Örnek Projeler (examples/)
SDK'nın pratik entegrasyonlarını test etmek için hazır senaryolar:
01-liquid-theme-demo.html— Storefront Liquid temasında canlı arama, sunucu ping/online oyuncu, bakiye ile ürün satın alma ve/webhızlı giriş demosu.02-headless-node.ts— Node.js / Headless modda doğrudan backend API çağrıları, LuckPerms ve SEO sitemap.03-lexical-showcase.html— Tarayıcıda Lexical AST render ve HTML ➔ Lexical AST çift yönlü test sandbox'ı.04-tickets-and-forum.ts— Destek talebi ve forum mesajlaşma iş akışları (otomatik Lexical dönüşümü).
- Sıfır Bağımlılık (Zero-dependency): Harici hiçbir npm paketine ihtiyaç duymaz. Minified IIFE boyutu yalnızca ~18 KB (
dist/crafter.min.js). - Doğrudan Storefront Proxy Uyumu: Varsayılan olarak
/api/storefrontüzerinden çalışır. TemadawebsiteIdveya domain yapılandırması gerektirmez; mağaza hostname üzerinden çözülür. - Kusursuz Versiyonlama: Yalnızca
v2olan endpointler/v2/...olarak çağrılır, diğer tüm endpointler düz yazılır (aslav1kullanılmaz). - Her İki Dünyaya Uygun:
- CDN / Script Tag ile Liquid temalarında:
window.Crafter - NPM / ESM modern bundler projelerinde:
import { Crafter } from '@crafter-cms/sdk'
- CDN / Script Tag ile Liquid temalarında:
- Reaktif Event Sistemi: Bakiye transferi, sepet satın alımı, sandık kullanımı ve oturum değişikliklerini anlık dinleme (
crafter.on('cart:purchased', ...)). - Tam Tip Güvenliği: Backend NestJS DTO'larıyla %100 uyumlu TypeScript tanımları (
dist/index.d.ts). - Akıllı Otomasyonlar:
- Şifre sıfırlamada
?token=parametresini URL'den otomatik algılama. - Oyun içi
/webkomutundan gelen güvenlik hash'i ilecrafter.auth.inGameAuth()üzerinden tek tıkla şifresiz oturum açma.
- Şifre sıfırlamada
layout/theme.liquid dosyanızda <head> veya sayfa sonuna ekleyin:
<!-- SDK Yükleme -->
<script src="/assets/crafter.min.js"></script>
<!-- Başlatma (Sıfır konfigürasyon yeterlidir, otomatik /api/storefront kullanır) -->
<script>
window.crafter = new Crafter();
</script>Liquid Temalarında: İstekler aynı origin altındaki
/api/storefrontproxy'sine yönlendirilir. Proxy, mağaza tenant'ını hostname üzerinden otomatik çözer ve HttpOnly token çerezlerini backend'e güvenle iletir.
Mobil uygulamalar, harici Node/React/Vue projeleri veya bağımsız panellerde doğrudan backend'e bağlanmak için websiteId belirtmeniz yeterlidir:
npm install @crafter-cms/sdkimport { Crafter } from '@crafter-cms/sdk';
const crafter = new Crafter({
mode: 'direct',
websiteId: 'website-uuid-degeriniz',
// apiBase varsayılan olarak 'https://api.crafter.net.tr' adresini kullanır
// token: 'jwt-access-token' // opsiyonel
});| Modül | Base Proxy Yolu | Metotlar & Açıklama |
|---|---|---|
crafter.auth |
/v2/auth (v2) |
signin, signup, logout, inGameAuth, refreshToken, forgotPassword, resetPassword, getResetTokenFromUrl, verifyEmail, resendEmail, validate2Fa, send2FaEmailCode, send2FaDiscordCode, updateTempEmail, getDiscordAuthUrl |
crafter.users |
/v2/users & /users |
getProfile('me'), getBalance('me') (hafif bakiye), getByUsername('@user'), updateProfile(dto), sendBalance({ targetUserId, amount }), changePassword(dto)Duvar: getWall(userId), postWallMessage(userId, content), replyWallMessage(userId, msgId, content)2FA: get2FaStatus(), setupAuthenticator(), enableAuthenticator(code), sendEmail2FaCode(), enableEmail2Fa(code), sendDiscord2FaCode(), enableDiscord2Fa(code), disable2Fa(dto), setPrimary2FaMethod(method), regenerateRecoveryCodes()Discord: getDiscordStatus(), unlinkDiscord() |
crafter.search |
/metadata-search |
metadataSearch(query, limit = 5) (Navbar için canlı global arama: kullanıcılar, ürünler, duyurular, sayfalar) |
crafter.seo |
/v2/seo (v2) |
getConfig() (Site geneli meta tag şablonları, OG resim, favicon), getSitemapData() (Dinamik sitemap URL dizisi) |
crafter.luckperms |
/v2/modules/luckperms (v2) |
getPlayer(usernameOrUuid) (Oyuncunun oyun içi ana rütbesi, yetkileri ve devralınan grupları), getGroups() |
crafter.website |
/ (Kök / Site Bilgisi) |
getInfo() (Sitenin adı, para birimi, logosu, faviconu ve aktif eklenti modülleri: discord_bot, authme vb.) |
crafter.store |
/categories, /products, /config/marketplace |
getCategories(), getCategory(id), getProducts(), getProduct(id), getProductsByCategory(catId), getConfig() (Sepette toplu indirim ayarları) |
crafter.cart / marketplace |
/marketplace |
purchase({ productIds, coupon? }) (Site bakiyesinden anında satın alım) |
crafter.posts |
/v2/posts (v2) |
list(query?), getBySlug(slug), get(idOrSlug), like(id), getUserLiked(userId, page, limit) |
crafter.pages |
/v2/pages (v2) |
list() (tüm yayındaki sayfalar), getBySlug(slug) |
crafter.statistics |
/v2/statistics (v2) |
get(limit = 5) (Son alışverişler, ödemeler, kayıtlar, en çok yükleyenler / leaderboard) |
crafter.punishments |
/v2/punishments (v2) |
list(page, limit), search(query, type) (Ban, Mute vb. ceza listesi) |
crafter.tickets |
/v2/tickets (v2) |
list(), get(id), create(dto), reply(id, msg), close(id, reason?), open(id), getCategories() |
crafter.chest |
/chest |
getItems('me'), useItem(chestItemId), giftItem(targetUserId, chestItemId) |
crafter.coupons |
/coupons |
get(couponCode) (İndirim oranı ve geçerlilik kontrolü) |
crafter.redeemCode |
/redeem-codes |
use(code) (Promosyon / hediye kartı bozdurma) |
crafter.servers |
/config/servers |
getList() (Canlı sunucu durumu, online/max oyuncu sayısı, ping) |
crafter.payments |
/payment & /config/payment |
getPublicProviders() (Açık ödeme yöntemleri ve bonus oranları), initiate({ amount, providerId, user }), check(paymentId) |
crafter.vote |
/config/vote-providers |
getProviders() (Aktif oy siteleri ve bekleme süreleri), vote(providerId) |
crafter.legal |
/config/legal |
getDocuments() (Kurallar, gizlilik politikası, kullanım koşulları) |
crafter.reports |
/reports |
create(reportedUserId, { reportType, reason }) (Oyuncu şikayet etme) |
crafter.forum |
/forum |
getCategories(), getTopics(catId), getTopic(id), createTopic(catId, dto), addMessage(topicId, msg), replyMessage(msgId, msg), likeTopic(id), unlikeTopic(id), getStatistics() |
crafter.helpcenter |
/helpcenter |
getOverview(query?), getCategory(id), getArticle(id) |
crafter.staffForms |
/staff-forms |
list(), get(id), apply(formId, answers) |
// Tam profil nesnesi yerine sadece bakiye ve para birimini çeker:
const balanceData = await crafter.users.getBalance('me');
document.querySelector('#header-balance').innerText = `${balanceData.balance} ${balanceData.currency}`;const results = await crafter.search.metadataSearch('vip', 5);
results.forEach(item => {
console.log(`[${item.type.toUpperCase()}] ${item.name} - ${item.subtitle}`);
});// URL'deki ?username=&uuid=&server_id=&hash= parametrelerini otomatik ayıklar:
await crafter.auth.inGameAuth();
// ✅ Kullanıcı anında giriş yaptı ve oturumu kaydedildi!// Sayfa: /auth/password/reset?token=xyz123...
await crafter.auth.resetPassword({
new_password: 'YeniGucluSifrem123!',
confirm_password: 'YeniGucluSifrem123!'
});const lpData = await crafter.luckperms.getPlayer('oyuncu_adi');
console.log('Ana Rütbe:', lpData.primaryGroup); // 'vip'// Satın alma tamamlandığında
crafter.on('cart:purchased', async (order) => {
console.log('Satın alma başarılı:', order);
const data = await crafter.users.getBalance('me');
document.querySelector('#header-balance').innerText = data.balance;
});
// Bakiye transferi gerçekleştiğinde
crafter.on('balance:sent', (transfer) => {
console.log('Kredi gönderildi:', transfer);
});
// Çıkış yapıldığında
crafter.on('auth:logout', () => {
window.location.reload();
});# Bağımlılıkları yükle
npm install
# TypeScript tip kontrolü
npm run typecheck
# Üretim paketini derle (CJS, ESM, IIFE, DTS)
npm run buildDerleme sonucunda dist/ klasöründe üretilen çıktılar:
dist/crafter.min.js: Liquid temaları için tarayıcıda doğrudan çalıştırılabilir minified bundle.dist/index.mjs: Modern bundlerlar (Vite, Webpack, Next.js) için ESM çıktısı.dist/index.js: Node.js ortamı için CommonJS çıktısı.dist/index.d.ts: %100 eksiksiz TypeScript tip tanımları.
MIT © Crafter