Ana içeriğe geç

Başlarken

NPM VersionBundle Size

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('your-project-url', {
    token: 'your-api-token'
  });

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('contact-form', {
    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​

📖 Ayrıntılı 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: 'your-app-token',  
}  
const {  
  Admins,  
  AttributesSets,  
  AuthProvider,  
  Blocks,  
  Events,  
  FileUploading,  
  Forms,  
  FormData,  
  GeneralTypes,  
  IntegrationCollections,  
  Locales,  
  Menus,  
  Orders,  
  Pages,  
  Payments,  
  ProductStatuses,  
  Products,  
  Settings,  
  System,  
  Templates,  
  TemplatePreviews,  
  Users,  
  WS  
} = defineOneEntry('your-url', config);

Ya da

const config = {  
  token: 'your-app-token',  
};  

const api = defineOneEntry('your-url', config);

Yapılandırma​

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

  • 'token' - Projeniz için güvenli "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" ayarlayın. 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.
  • 'auth' - Yetkilendirme ayarlarıyla bir nesne. Varsayılan olarak, SDK, kullanıcının 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 buradan depodan aktarın.
  • 'saveFunction' - Yenileme token'ını güncelleyen bir işlev. Token'ı oturumlar arasında saklamak istiyorsanız, örneğin yerel depolamada, bunu yapan bir işlevi buraya geçin. İşlev, token ile birlikte bir dize alacak şekilde tasarlanmalıdır.
  • 'customAuth' - Yetkilendirmeyi yapılandırmak ve token'larla kendiniz ç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 verileri 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'  
  },  
});

Kendiniz token'ları yapılandırmayı seçtiyseniz, token'ı yönteme aşağıdaki gibi geçebilirsiniz. Ara yöntem, bir erişim token'ını isteğe geçmenizi sağlar. Ardından gerekli yöntemi çağırın. Bu yöntem (setAccessToken), kullanıcı kimlik doğrulaması 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 işlevinize geçin.

Token'ı aşağıdaki gibi 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çenekTürVarsayılanAçıklama
enabledbooleanfalseYanıt doğrulamasını etkinleştir/devre dışı bırak
strictModebooleanfalsetrue olduğunda, doğrulama hatası durumunda IError döndürür. false olduğunda, hataları kaydeder ve orijinal veriyi döndürür
logErrorsbooleantrueDoğ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ştirilmeden 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)  
}

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 işlevler geçebilirsiniz. Bu işlevler 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),  
    },  
  },  
})

SDK yapılandırmasında isShell: false seçeneği 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 yönetimi  
}

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 yönetimi  
} else {  
  // Başarılı bir sonucu işleme  
}

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

SDK'yı varsayılan ayarlarla (isShell true olarak ayarlandığında) kullanırken, hatalar istisna olarak fırlatılmak yerine değerler olarak döndürülür. Bu, uygulamanın, işlenmemiş istisnalar nedeniyle çö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 dönüş 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 yönetimi  
  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ü kullanabilirsiniz:

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 yönetimi  
  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: