Başlarken

OneEntry Platform SDK, OneEntry Platform API ile etkileşim kurmanın kolay bir yolunu sağlayan bir SDK'dır.

---

🚀 Hızlı Başlangıç

OneEntry ile 3 basit adımda başlayın:

1️⃣ Paketi Yükleyin

  npm install oneentry

2️⃣ SDK'yı Başlatın

  import { defineOneEntry } from 'oneentry';

  const api = defineOneEntry('proje-urliniz', {
    token: 'api-tokeniniz'
  });

3️⃣ API'yi Kullanımına Başlayın

  // Ürünleri al
  const products = await api.Products.getProducts({ limit: 10 });

  // Kullanıcı profilini al
  const user = await api.Users.getUser();

  // Bir form gönder
  const formData = await api.FormData.postFormsData('iletisim-formu', {
    name: 'John Doe',
    email: 'john@example.com'
  });

🎉 Hepsi bu kadar! OneEntry ile harika uygulamalar geliştirmeye hazırsınız.

---

✨ Ana Özellikler

🔐

Güvenli Kimlik Doğrulama

Yerleşik token yönetimi ve OAuth desteği

🌍

Çok Dilli

Otomatik dil algılama ile i18n desteği

📝

TypeScript

Daha iyi DX için tam tür tanımları

⚡

Hafif

Üretim için optimize edilmiş paket boyutu

🔌

Modüler Mimari

Tüm ihtiyaçlarınız için 24 özel modül

🛡️

Hata Yönetimi

Özel hata işleyicileri ve shell modu

🌐 Kaynaklar

🌍

Resmi Web Sitesi

OneEntry Platform hakkında daha fazla bilgi edinin

🚀

Kayıt Ol

Ücretsiz hesabınızı oluşturun

💻

Npmjs

SDK’yı indirin

📖 Detaylı Kullanım

Tüm Mevcut Modüller

Gerekli tüm modülleri içe aktarın ve parçalayın:

import { defineOneEntry } from 'oneentry'
const config = {  
  token: 'uygulama-tokeniniz',  
}  
const {  
  Admins,  
  AttributesSets,  
  AuthProvider,  
  Blocks,  
  Events,  
  FileUploading,  
  Forms,  
  FormData,  
  GeneralTypes,  
  ImmutableSettings,  
  IntegrationCollections,  
  Locales,  
  Menus,  
  Orders,  
  Pages,  
  Payments,  
  ProductStatuses,  
  Products,  
  Settings,  
  System,  
  Templates,  
  TemplatePreviews,  
  Users,  
  WS  
} = defineOneEntry('urliniz', config);  

Ya da

const config = {
  token: 'uygulama-tokeniniz',
};

const api = defineOneEntry('urliniz', config);

---

Konfigürasyon

Yapıcı fonksiyonun ikinci parametresi 'config' alır. Aşağıdaki değerleri içerir:

• 'token' - Projeniz için "Güvenlik API Token" anahtarını ayarlayın. Sertifika koruması kullanıyorsanız, bu değişkeni geçmeyin. Projenizin güvenliği hakkında daha fazla bilgi için buraya göz atabilirsiniz.
• 'langCode' - Varsayılan dili ayarlamak için "langCode" değerini belirleyin. Bu parametreyi bir kez belirterek, ONEENTRY API yöntemlerine langCode geçmek zorunda kalmazsınız. Varsayılan dili geçmediyseniz, "en_US" olarak ayarlanacaktır.
• 'traficLimit' - Bazı yöntemler, aldığınız verilerin eksiksiz ve çalışması kolay olması için OneEntry'ye birden fazla istek gönderir. Bu parametre için "true" değerini geçerek trafiği tasarruf edebilir ve hangi verilere ihtiyacınız olduğunu kendiniz belirleyebilirsiniz. Varsayılan değer "false"dur.
• 'rawData' - false (varsayılan) olarak ayarlandığında, SDK otomatik olarak additionalFields dizisini erişimi kolaylaştırmak için marker ile anahtarlanan bir nesneye dönüştürür. true olarak ayarlandığında, additionalFields API'den orijinal dizi olarak alınır.
• 'auth' - Yetkilendirme ayarlarıyla bir nesne. Varsayılan olarak, SDK kullanıcı oturumundaki token'larla çalışacak şekilde yapılandırılmıştır ve sizden ek bir işlem gerektirmez. Aynı zamanda, SDK oturumlar arasında oturum durumunu saklamaz. Bu ayarlarla memnunsanız, 'auth' değişkenini hiç geçmeyin.

'auth' aşağıdaki ayarları içerir:

• 'refreshToken' - Kullanıcının yenileme token'ı. Başlatma sırasında kullanıcının oturumunu geri yüklemek için buraya deposundan aktarın.
• 'saveFunction' - Yenileme token'ı ile güncelleme işlemi yapan bir fonksiyon. Token'ı oturumlar arasında saklamak istiyorsanız, örneğin yerel depolamada, bunu yapan bir fonksiyonu buraya geçin. Fonksiyon, token ile birlikte bir parametre almalıdır.
• 'customAuth' - Yetkilendirmeyi kendiniz yapılandırmak ve token'larla çalışmak istiyorsanız, bu bayrağı true olarak ayarlayın. SDK ayarlarını kullanmak istiyorsanız, false olarak ayarlayın veya hiç geçmeyin.
• 'providerMarker' - Yetkilendirme sağlayıcısı için işaretçi. Varsayılan: 'email'.

Token koruması ve oturumlar arasında durumu saklayan otomatik kimlik doğrulama ile bir yapılandırma örneği

const tokenFunction = (token) => {
  localStorage.setItem('refreshToken', token);
};

const api = defineOneEntry('https://my-project.oneentry.cloud', {
  token: 'my-token',
  langCode: 'en_US',
  auth: {
    refreshToken: localStorage.getItem('refreshToken'),
    saveFunction: tokenFunction,
    providerMarker: 'email'
  },
});

Sertifika ile korunan bir yapılandırma örneği, yetkilendirme sistemini kendiniz yapılandırmanıza ve isteklerde veri saklamanıza olanak tanır.

const api = defineOneEntry('https://my-project.oneentry.cloud', {
  langCode: 'en_US',
  traficLimit: true,
  auth: {
    customAuth: true,
    refreshToken: localStorage.getItem('refreshToken'),
    providerMarker: 'email'
  },
});

Token'ları kendiniz yapılandırmayı seçtiyseniz, token'ı yönteme şu şekilde geçebilirsiniz. Ara yöntem, isteğe bir erişim token'ı geçmenizi sağlar. Ardından gerekli yöntemi çağırın. Bu yöntem (setAccessToken), kullanıcı yetkilendirmesi gerektirmeyen bir yöntem çağrılmadığında çağrılmamalıdır.

const user = api.Users.setAccessToken('my.access.token').getUser();

Bağlantı güvenliğini sağlamak için token korumasını seçtiyseniz, token'ınızı isteğe bağlı bir parametre olarak fonksiyona geçin.

Token'ı şu şekilde alabilirsiniz

1. Kişisel hesabınıza giriş yapın
2. "Projeler" sekmesine gidin ve bir proje seçin
3. "Erişim" sekmesine gidin
4. "Güvenlik API Token" anahtarını ayarlayın
5. Projeye giriş yapın, ayarlar bölümüne gidin ve token sekmesini açın
6. Projenizin token'ını alın ve kopyalayın

Projenizi korumak için bir tls sertifikası da bağlayabilirsiniz. Bu durumda, "token"ı hiç geçmeyin. Sertifika kullanırken, projenizde bir proxy ayarlayın. URL parametresi olarak boş bir dize geçin. mtls sertifikası hakkında daha fazla bilgi edinin

const saveTokenFromLocalStorage = (token) => {
  localStorage.setItem('refreshToken', token);
};

const api = defineOneEntry('your-url', {
  token: 'my-token',
  langCode: 'my-langCode',
  auth: {
    customAuth: false,
    userToken: 'rerfesh.token',
    saveFunction: saveTokenFromLocalStorage,
    providerMarker: 'email'
  },
});

API Yanıt Doğrulaması

OneEntry SDK, API yanıtlarının isteğe bağlı doğrulamasını Zod kullanarak içerir; bu, TypeScript öncelikli bir şema doğrulama kütüphanesidir. Bu özellik, API yanıtlarıyla çalışırken veri bütünlüğünü ve tür güvenliğini sağlamaya yardımcı olur.

Özellikler

• İsteğe Bağlı: Doğrulama varsayılan olarak devre dışıdır ve yapılandırmaya göre etkinleştirilebilir
• Tür Güvenli: TypeScript arayüzleriyle uyumlu Zod şemaları kullanır
• İki Mod: Yumuşak mod (hataları kaydeder) ve katı mod (hataları döndürür)
• Devre dışı bırakıldığında sıfır çalışma zamanı yükü: Doğrulama kapatıldığında performans etkisi yoktur

Yapılandırma

Doğrulamayı etkinleştirmek için SDK yapılandırmanıza validation özelliğini ekleyin:

import { defineOneEntry } from 'oneentry'

const api = defineOneEntry('https://your-project.oneentry.cloud', {
  token: 'your-token',
  validation: {
    enabled: true,        // Doğrulamayı etkinleştir (varsayılan: false)
    strictMode: false,    // Katı mod (varsayılan: false)
    logErrors: true,      // Doğrulama hatalarını kaydet (varsayılan: true)
  }
})

Yapılandırma Seçenekleri

Seçenek	Tür	Varsayılan	Açıklama
enabled	boolean	false	Yanıt doğrulamasını etkinleştir/devre dışı bırak
strictMode	boolean	false	true olduğunda, doğrulama hatası durumunda IError döndürür. false olduğunda, hataları kaydeder ve orijinal veriyi döndürür
logErrors	boolean	true	Doğrulama hatalarını konsola kaydet (hata ayıklama için yararlıdır)

Doğrulama Modları

Yumuşak Mod (Varsayılan)

strictMode false olduğunda, doğrulama hataları konsola kaydedilir, ancak orijinal API yanıtı değişmeden döndürülür. Bu, uygulamanızı bozmadığınızdan emin olmak için potansiyel veri tutarsızlıklarını tanımlamak için geliştirme sırasında yararlıdır.

const api = defineOneEntry('https://your-project.oneentry.cloud', {
  token: 'your-token',
  validation: {
    enabled: true,
    strictMode: false,  // Yumuşak mod
    logErrors: true,
  }
})

// Doğrulama başarısız olsa bile, API yanıtını alırsınız
const user = await api.Users.getUser()
// Konsolda herhangi bir doğrulama hatası gösterilecektir

Katı Mod

strictMode true olduğunda, doğrulama hataları veri yerine bir IError nesnesi döndürür. Bu, uygulamanızın yalnızca doğrulanmış verileri işlemesini sağlar.

const api = defineOneEntry('https://your-project.oneentry.cloud', {
  token: 'your-token',
  validation: {
    enabled: true,
    strictMode: true,   // Katı mod
    logErrors: true,
  }
})

const user = await api.Users.getUser()

// Yanıtın bir hata olup olmadığını kontrol et
if ('statusCode' in user) {
  console.error('Doğrulama başarısız:', user.message)
} else {
  // Tür güvenli: user, IUserEntity'dir
  console.log('Kullanıcı:', user.email)
}

---

Ek Alanlar Formatı

Varsayılan olarak, SDK additionalFields özelliğini bir diziden (API tarafından döndürülen) marker ile anahtarlanan bir nesneye dönüştürür. Bu, belirli alanlara erişimi, indekslerini bilmeden çok daha kolay hale getirir.

Varsayılan davranış (rawData: false)

const api = defineOneEntry('https://your-project.oneentry.cloud', {
  token: 'your-token',
  // rawData varsayılan olarak false'dur — açıkça geçmenize gerek yok
})

// additionalFields, marker ile anahtarlanan bir nesnedir:
const field = attribute.additionalFields['my_field']
console.log(field.value)  // doğrudan erişim, dizi araması gerekmez

Ham mod (rawData: true)

Orijinal API yanıt formatına (örneğin, geriye dönük uyumluluk için) ihtiyacınız varsa, rawData: true ayarlayın:

const api = defineOneEntry('https://your-project.oneentry.cloud', {
  token: 'your-token',
  rawData: true,
})

// additionalFields, API'den orijinal dizidir:
const field = attribute.additionalFields.find(f => f.marker === 'my_field')
console.log(field.value)

Yapılandırma Seçeneği

Seçenek	Tür	Varsayılan	Açıklama
rawData	boolean	false	false olduğunda, additionalFields marker ile anahtarlanan bir nesneye dönüştürülür. true olduğunda, API'den orijinal dizi döndürülür

---

Hatalar

Hataları sc içinde atlamak istiyorsanız, "errors" özelliğini varsayılan olarak bırakın. Bu durumda, ya varlık verisini ya da hata nesnesini alırsınız. Tür kontrolü yapmanız gerekir. Örneğin, ".hasOwnProperty" ile statusCode özelliğini kontrol ederek.

Ancak, "try catch(e) " yapısını kullanmak istiyorsanız, "isShell" özelliğini "false" değerine ayarlayın. Bu durumda, hatayı "try catch(e) " kullanarak ele almanız gerekir.

Ayrıca, SDK içinde uygun hata koduyla çağrılacak özel fonksiyonlar geçebilirsiniz. Bu fonksiyonlar bir hata nesnesini argüman olarak alır. Kendiniz işleyebilirsiniz.

const api = defineOneEntry('your-url', {
  token: 'my-token',
  langCode: 'my-langCode',
  errors: {
    isShell: false,
    customErrors: {
      400: (error) => console.error('Kötü İstek:', error.message),
      401: (error) => console.error('Yetkisiz:', error.message),
      403: (error) => console.error('Yasak:', error.message),
      404: (error) => console.error('Bulunamadı:', error.message),
      429: (error) => console.error('Hız Limiti Aşıldı:', error.message),
      500: (error) => console.error('Sunucu Hatası:', error.message),
      502: (error) => console.error('Kötü Ağ Geçidi:', error.message),
      503: (error) => console.error('Hizmet Kullanılamıyor:', error.message),
      504: (error) => console.error('Ağ Geçidi Zaman Aşımı:', error.message),
    },
  },
})

isShell: false seçeneği SDK yapılandırmasında ayarlandığında, aşağıdaki etkiye sahiptir:

API isteklerinde bir hata oluştuğunda (örneğin, HTTP hataları 400, 401, 404, 500 vb. veya ağ hataları), SDK, hata nesnesini normal bir değer olarak döndürmek yerine bir istisna fırlatır.

Bu, uygulama kodunuzda hataları ele almak için try/catch yapısını kullanmanıza olanak tanır:

try {
  const result = await api.someMethod();
  // Başarılı bir sonucu işleme
} catch (error) {
  // Hata işleme
}

isShell: true olduğunda, hatalar değerler olarak döndürülür ve sonucu doğrulamak için açıkça tür kontrolü yapmanız gerekir:

const result = await api.someMethod();
if ('statusCode' in result) { // Hata nesnesinde statusCode özelliğinin var olduğunu varsayar
  // Hata işleme
} else {
  // Başarılı bir sonucu işleme
}

Böylece, isShell: false, daha tanıdık bir try/catch hata işleme modeline olanak tanırken, isShell: true, hataların ve başarıların aynı türde değerler olarak döndürüldüğü düz bir model sağlar.

SDK'yı varsayılan ayarlarla (isShell true olarak ayarlandığında) kullanırken, hatalar değerler olarak döndürülür, istisna olarak fırlatılmaz. Bu, uygulamanın işlenmemiş istisnalardan dolayı çökmesini önler, çünkü hatalar normal yürütme akışının bir parçası olarak ele alınır. API yöntemini çağırdıktan sonra hata türünü kontrol edin:

const result = await api.someMethod();

// Sonucun bir hata olup olmadığını kontrol et
if ('statusCode' in result || 'message' in result) {
  // Hata işleme
  console.error('Hata:', result);
} else {
  // Başarılı bir sonucu işleme
  console.log('Başarı:', result);
}

Ayrıca, hataları kontrol etmek için "IError" türünü kullanarak yardımcı fonksiyonlar oluşturabilirsiniz:

import type { IError } from '../base/utils';

function isErrorResult(result: any): result is IError {
  return result && typeof result === 'object' && 
         (result.hasOwnProperty('statusCode') || 
          result.hasOwnProperty('message'));
}

// Sonra bunu şu şekilde kullanın:
const result = await api.someMethod();

if (isErrorResult(result)) {
  // Hata işleme
  console.error('Bir hata oluştu:', result);
} else {
  // Başarılı bir sonucu işleme
  console.log('Başarılı sonuç:', result);
}

Bu yaklaşım, try/catch yapıları kullanmadan hataları doğru bir şekilde ele almanıza olanak tanır ve uygulamanın çökmesini önler.

---

📚 Sonraki Adımlar

Daha fazla bilgi edinmek için kapsamlı kılavuzlarımıza göz atın:

🛍️

E-ticaret

Filtreleme ve arama ile ürün katalogları oluşturun

👤

Kullanıcı Yönetimi

Kimlik doğrulama ve kullanıcı profilleri uygulayın

🛒

Siparişler & Ödeme

Siparişleri işleyin ve ödemeleri yönetin

📄

Sayfalar & İçerik

Dinamik sayfaları ve içerik yapılarını yönetin

📝

Formlar

Formları nasıl yöneteceğinizi öğrenin

📝

Form verileri

Form verilerini nasıl yöneteceğinizi öğrenin

---