Memulai

Name: OneEntry SDK
Author: OneEntry

OneEntry Platform SDK adalah SDK yang menyediakan cara mudah untuk berinteraksi dengan OneEntry Platform API.

🚀 Memulai dengan Cepat

Mulai dan jalankan OneEntry dalam 3 langkah sederhana:

Instalasi

  npm install oneentry

2️⃣ Inisialisasi SDK

  import { defineOneEntry } from 'oneentry';

  const api = defineOneEntry('your-project-url', {
    token: 'your-api-token'
  });

3️⃣ Mulai menggunakan API

  // Fetch products 
  const products = await api.Products.getProducts({ limit: 10 });

  // Get user profile
  const user = await api.Users.getUser();

  // Submit a form
  const formData = await api.FormData.postFormsData('contact-form', {
    name: 'John Doe',
    email: 'john@example.com'
  });

🎉 Itu saja! Anda siap untuk membangun aplikasi yang luar biasa dengan OneEntry.

✨ Fitur Utama

🔐

Autentikasi Aman

Manajemen token bawaan dan dukungan OAuth

🌍

Multi-bahasa

Dukungan i18n dengan deteksi bahasa otomatis

📝

TypeScript

Definisi tipe lengkap untuk pengalaman pengguna yang lebih baik

⚡

Ringan

Ukuran bundle yang dioptimalkan untuk produksi

🔌

Arsitektur Modular

24 modul khusus untuk semua kebutuhan Anda

🛡️

Penanganan Kesalahan

Penangan kesalahan kustom dan mode shell

🌐 Sumber Daya

🌍

Situs Resmi

Pelajari lebih lanjut tentang OneEntry Platform

🚀

Daftar

Buat akun gratis Anda

💻

Npmjs

Unduh SDK

🧪

JS SDK Sandbox

Coba metode SDK secara langsung di browser Anda — tanpa pengaturan yang diperlukan

📖 Penggunaan Detail

Semua Modul yang Tersedia

Impor dan destruktur semua modul yang Anda butuhkan:


import { defineOneEntry } from 'oneentry'

const config = {
  token: 'your-app-token',
}
const {
  Admins,
  AttributesSets,
  AuthProvider,
  Blocks,
  Events,
  Filters,
  FileUploading,
  Forms,
  FormData,
  GeneralTypes,
  IntegrationCollections,
  Locales,
  Menus,
  Orders,
  Pages,
  Payments,
  ProductStatuses,
  Products,
  Subscriptions,
  Settings,
  System,
  Templates,
  TemplatePreviews,
  UserActivity,
  Users,
  WS
} = defineOneEntry('your-url', config);

Atau

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

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

Konfigurasi

Parameter kedua dari konstruktor mengambil 'config'. Ini berisi nilai-nilai berikut:

'token' - Atur kunci token jika proyek Anda mengamankan "Security API Token". Jika Anda menggunakan perlindungan sertifikat, jangan lewatkan variabel ini. Anda dapat membaca lebih lanjut tentang keamanan proyek Anda di sini.
'langCode' - Atur "langCode" untuk menetapkan bahasa default. Dengan menentukan parameter ini sekali, Anda tidak perlu melewatkan langCode ke metode ONEENTRY API. Jika Anda tidak melewatkan bahasa default, itu akan diatur ke "en_US".
'traficLimit' - Beberapa metode menggunakan lebih dari satu permintaan ke OneEntry sehingga data yang Anda terima lengkap dan mudah dikerjakan. Lewatkan nilai "true" untuk parameter ini untuk menghemat trafik dan memutuskan sendiri data apa yang Anda butuhkan. Nilai default "false".
'rawData' - Ketika diatur ke false (default), SDK secara otomatis mengubah array additionalFields menjadi objek yang dikunci oleh marker untuk akses yang lebih mudah. Atur ke true untuk menerima additionalFields sebagai array asli dari API.
'guestId' - Identifikasi tamu opsional yang dikirim sebagai header x-guest-id pada permintaan yang tidak terautentikasi, memungkinkan alur keranjang/daftar keinginan/aktivitas tamu. Di browser, jika diabaikan, ID per perangkat yang stabil dihasilkan dan disimpan di localStorage. Di server, Anda harus melewatkan guestId per pengunjung. Lihat Mode Tamu di bawah. Nilai default adalah undefined.
'auth' - Objek dengan pengaturan otorisasi. Secara default, SDK dikonfigurasi untuk bekerja dengan token di dalam sesi pengguna dan tidak memerlukan pekerjaan tambahan dari Anda. Pada saat yang sama, SDK tidak menyimpan status sesi antara sesi. Jika Anda puas dengan pengaturan tersebut, jangan lewatkan variabel 'auth' sama sekali.

'auth' berisi pengaturan berikut:

'refreshToken' - Token refresh pengguna. Transfer di sini dari repositori untuk memulihkan sesi pengguna selama inisialisasi.
'saveFunction' - Fungsi yang bekerja dengan pembaruan token refresh. Jika Anda ingin menyimpan token antara sesi, misalnya di penyimpanan lokal, lewatkan fungsi di sini yang melakukan ini. Fungsi tersebut harus menerima parameter di mana string dengan token akan diteruskan.
'customAuth' - Jika Anda ingin mengonfigurasi otorisasi dan bekerja dengan token sendiri, atur flag ini ke true. Jika Anda ingin menggunakan pengaturan sdk, atur ke false atau jangan transfer sama sekali.
'providerMarker' - Penanda untuk penyedia otorisasi. Default: 'email'. Contoh konfigurasi dengan perlindungan token dan autentikasi otomatis yang menyimpan status antara sesi

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'
  },
});

Contoh konfigurasi yang dilindungi dengan sertifikat memungkinkan Anda mengonfigurasi sistem otorisasi sendiri dan menyimpan data pada permintaan.

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

Jika Anda memilih untuk mengonfigurasi token sendiri, Anda dapat melewatkan token ke metode sebagai berikut. Metode perantara memungkinkan Anda melewatkan token akses ke permintaan. Kemudian panggil metode yang diperlukan. Metode ini (setAccessToken) tidak boleh dipanggil jika metode tidak memerlukan otorisasi pengguna.

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

Jika Anda memilih perlindungan token untuk memastikan keamanan koneksi, cukup lewatkan token Anda ke fungsi sebagai parameter opsional.

Anda dapat mendapatkan token sebagai berikut

Masuk ke akun pribadi Anda
Pergi ke tab "Proyek" dan pilih proyek
Pergi ke tab "Akses"
Atur sakelar ke "Security API Token"
Masuk ke proyek, pergi ke bagian pengaturan dan buka tab token
Dapatkan dan salin token proyek Anda

Anda juga dapat menghubungkan sertifikat tls untuk melindungi proyek Anda. Dalam hal ini, jangan lewatkan "token" sama sekali. Saat menggunakan sertifikat, atur proxy di proyek Anda. Lewatkan string kosong sebagai parameter url. Pelajari lebih lanjut tentang sertifikat mtls

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'
  },
});

Mode Tamu

SDK dapat bertindak atas nama tamu yang tidak terautentikasi. Ketika tidak ada token akses yang diatur, ia mengirim header x-guest-id pada permintaan, yang memungkinkan endpoint yang menyadari tamu berfungsi tanpa pengguna yang masuk - alur keranjang, daftar keinginan dan aktivitas pengguna, serta blok personalisasi (yang baru saja dilihat, rekomendasi pribadi, dan lainnya).

Bagaimana ID tamu diselesaikan:

guestId yang dikonfigurasi secara eksplisit (dari config.guestId atau setGuestId) selalu menang.
Di browser, ketika tidak ada yang disediakan, ID yang stabil dihasilkan (melalui Web Crypto jika tersedia) dan disimpan di localStorage di bawah kunci oneentry_guest_id, mencerminkan strategi metadata perangkat. Ini tetap stabil di seluruh sesi dan tab.
Jika tidak, ID adalah undefined dan header x-guest-id cukup diabaikan.

⚠️ Server-side: SDK tidak pernah secara otomatis menghasilkan ID tamu di server. Sebuah instance defineOneEntry yang dibagikan akan membocorkan satu keranjang/daftar keinginan tamu di semua pengunjung anonim. Di server, Anda harus melewatkan guestId per pengunjung sendiri (melalui config.guestId atau setGuestId).

Header ini diabaikan untuk permintaan yang terautentikasi (ketika token akses diatur), sehingga pengguna yang masuk selalu beroperasi pada data mereka sendiri.

Mengatur ID tamu saat inisialisasi

const api = defineOneEntry('https://my-project.oneentry.cloud', {
  token: 'my-token',
  guestId: 'visitor-123', // per-visitor id, required on the server
});

Mengatur atau menghapus ID tamu saat runtime

setGuestId bekerja seperti setAccessToken - dapat dirantai dan mengembalikan instance modul. Lewatkan string kosong untuk menghapusnya (SDK kemudian kembali ke ID yang didukung oleh localStorage di browser, atau tidak ada ID tamu sama sekali di server).

// Set the guest id, then call a guest-aware method
const cart = await api.Users.setGuestId('visitor-123').getCart();

// Clear the guest id
api.Users.setGuestId('');

Validasi Respons API

OneEntry SDK mencakup validasi opsional dari respons API menggunakan Zod, sebuah pustaka validasi skema yang berorientasi TypeScript. Fitur ini membantu memastikan integritas data dan keamanan tipe saat bekerja dengan respons API.

Fitur

Opsional: Validasi dinonaktifkan secara default dan dapat diaktifkan per konfigurasi
Aman Tipe: Menggunakan skema Zod yang sesuai dengan antarmuka TypeScript
Dua mode: Mode lunak (mencatat kesalahan) dan mode ketat (mengembalikan kesalahan)
Tanpa overhead runtime saat dinonaktifkan: Tidak ada dampak kinerja jika validasi dimatikan

Konfigurasi

Aktifkan validasi dengan menambahkan properti validation ke konfigurasi SDK Anda:

import { defineOneEntry } from 'oneentry'

const api = defineOneEntry('https://your-project.oneentry.cloud', {
  token: 'your-token',
  validation: {
    enabled: true,        // Enable validation (default: false)
    strictMode: false,    // Strict mode (default: false)
    logErrors: true,      // Log validation errors (default: true)
  }
})

Opsi Konfigurasi

Opsi	Tipe	Default	Deskripsi
`enabled`	`boolean`	`false`	Aktifkan/nonaktifkan validasi respons
`strictMode`	`boolean`	`false`	Ketika `true`, mengembalikan `IError` pada kegagalan validasi. Ketika `false`, mencatat kesalahan dan mengembalikan data asli
`logErrors`	`boolean`	`true`	Catat kesalahan validasi ke konsol (berguna untuk debugging)

Mode Validasi

Mode Lunak (Default)

Ketika strictMode adalah false, kesalahan validasi dicatat ke konsol, tetapi respons API asli dikembalikan tanpa perubahan. Ini berguna selama pengembangan untuk mengidentifikasi potensi inkonsistensi data tanpa merusak aplikasi Anda.

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

// Even if validation fails, you'll get the API response
const user = await api.Users.getUser()
// Console will show validation errors if any

Mode Ketat

Ketika strictMode adalah true, kegagalan validasi mengembalikan objek IError alih-alih data. Ini memastikan aplikasi Anda hanya memproses data yang telah divalidasi.

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

const user = await api.Users.getUser()

// Check if response is an error
if ('statusCode' in user) {
  console.error('Validation failed:', user.message)
} else {
  // Type-safe: user is IUserEntity
  console.log('User:', user.email)
}

Format Bidang Tambahan

Secara default, SDK mengubah properti additionalFields dari array (seperti yang dikembalikan oleh API) menjadi objek yang dikunci oleh marker. Ini membuatnya jauh lebih mudah untuk mengakses bidang tertentu tanpa mengetahui indeksnya.

Perilaku Default (`rawData: false`)

const api = defineOneEntry('https://your-project.oneentry.cloud', {
  token: 'your-token',
  // rawData is false by default — no need to pass it explicitly
})

// additionalFields is an object keyed by marker:
const field = attribute.additionalFields['my_field']
console.log(field.value)  // direct access, no array search needed

Mode Mentah (`rawData: true`)

Jika Anda memerlukan format respons API asli (misalnya untuk kompatibilitas mundur), atur rawData: true:

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

// additionalFields is the original array from the API:
const field = attribute.additionalFields.find(f => f.marker === 'my_field')
console.log(field.value)

Opsi Konfigurasi

Opsi	Tipe	Default	Deskripsi
`rawData`	`boolean`	`false`	Ketika `false`, `additionalFields` diubah menjadi objek yang dikunci oleh `marker`. Ketika `true`, array asli dari API dikembalikan

Kesalahan

Jika Anda ingin menghindari kesalahan di dalam sc, biarkan properti "errors" secara default. Dalam hal ini, Anda akan menerima baik data entitas atau objek kesalahan. Anda perlu melakukan pemeriksaan tipe. misalnya, dengan memeriksa properti statusCode dengan ".hasOwnProperty"

Namun, jika Anda ingin menggunakan konstruksi "try catch(e) ", atur properti "isShell" ke nilai "false". Dalam hal ini, Anda perlu menangani kesalahan menggunakan "try catch(e) ".

Selain itu, Anda dapat melewatkan fungsi kustom yang akan dipanggil di dalam sdk dengan kode kesalahan yang sesuai. Fungsi-fungsi ini menerima objek kesalahan sebagai argumen. Anda dapat memprosesnya sendiri.

const api = defineOneEntry('your-url', {
  token: 'my-token',
  langCode: 'my-langCode',
  errors: {
    isShell: false,
    customErrors: {
      400: (error) => console.error('Bad Request:', error.message),
      401: (error) => console.error('Unauthorized:', error.message),
      403: (error) => console.error('Forbidden:', error.message),
      404: (error) => console.error('Not Found:', error.message),
      429: (error) => console.error('Rate Limit Exceeded:', error.message),
      500: (error) => console.error('Server Error:', error.message),
      502: (error) => console.error('Bad Gateway:', error.message),
      503: (error) => console.error('Service Unavailable:', error.message),
      504: (error) => console.error('Gateway Timeout:', error.message),
    },
  },
})

Ketika opsi isShell: false diatur dalam konfigurasi SDK, ini memiliki efek berikut:

Ketika kesalahan terjadi dalam permintaan API (misalnya, kesalahan HTTP 400, 401, 404, 500, dll., atau kesalahan jaringan), SDK akan melempar pengecualian alih-alih mengembalikan objek kesalahan sebagai nilai normal.

Ini memungkinkan Anda menggunakan konstruksi try/catch dalam kode aplikasi Anda untuk menangani kesalahan:

try {
  const result = await api.someMethod();
  // Handling a successful result
} catch (error) {
  // Error handling
}

Jika isShell: true, kesalahan dikembalikan sebagai nilai, dan Anda perlu secara eksplisit memeriksa tipe hasil untuk memverifikasi:

const result = await api.someMethod();
if ('statusCode' in result) { // Assumes the presence of a statusCode property on the error object
  // Error handling
} else {
  // Handling a successful result
}

Dengan demikian, isShell: false memungkinkan model penanganan kesalahan try/catch yang lebih familiar, sementara isShell: true menyediakan model datar di mana kesalahan dan keberhasilan dikembalikan sebagai nilai dari tipe yang sama.

Saat menggunakan SDK dengan pengaturan default (isShell diatur ke true), kesalahan dikembalikan sebagai nilai alih-alih dilempar sebagai pengecualian. Ini berarti aplikasi tidak akan crash karena pengecualian yang tidak ditangani, karena kesalahan ditangani sebagai bagian dari alur eksekusi normal. Berikut cara Anda dapat menangani kesalahan di front end tanpa menggunakan try/catch:

Periksa tipe pengembalian setelah memanggil metode API:

const result = await api.someMethod();

// Check if the result is an error
if ('statusCode' in result || 'message' in result) {
  // Error handling
  console.error('Error:', result);
} else {
  // Handling a successful result
  console.log('Success:', result);
}

Anda juga dapat membuat tipe utilitas "IError" untuk memeriksa kesalahan:

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

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

// Then use it like this:
const result = await api.someMethod();

if (isErrorResult(result)) {
  // Error handling
  console.error('Произошла ошибка:', result);
} else {
  // Handling a successful result
  console.log('Успешный результат:', result);
}

Pendekatan ini memungkinkan Anda menghindari penggunaan konstruksi try/catch sambil tetap menangani kesalahan dengan benar, mencegah aplikasi dari crash.

📚 Langkah Selanjutnya

Jelajahi panduan komprehensif kami untuk mempelajari lebih lanjut:

🛍️

Memulai

🚀 Memulai dengan Cepat

Instalasi

2️⃣ Inisialisasi SDK

3️⃣ Mulai menggunakan API

✨ Fitur Utama

🌐 Sumber Daya

📖 Penggunaan Detail

Semua Modul yang Tersedia

Konfigurasi

Anda dapat mendapatkan token sebagai berikut

Mode Tamu

Mengatur ID tamu saat inisialisasi

Mengatur atau menghapus ID tamu saat runtime

Validasi Respons API

Fitur

Konfigurasi

Opsi Konfigurasi

Mode Validasi

Mode Lunak (Default)

Mode Ketat

Format Bidang Tambahan

Perilaku Default (`rawData: false`)

Mode Mentah (`rawData: true`)

Opsi Konfigurasi

Kesalahan

Ketika opsi isShell: false diatur dalam konfigurasi SDK, ini memiliki efek berikut:

📚 Langkah Selanjutnya

E-commerce

Manajemen Pengguna

Pesanan & Checkout

Halaman & Konten

Formulir

Data Formulir

🚀 Memulai dengan Cepat​

Instalasi​

2️⃣ Inisialisasi SDK​

3️⃣ Mulai menggunakan API​

✨ Fitur Utama​

🌐 Sumber Daya​

📖 Penggunaan Detail​

Semua Modul yang Tersedia​

Konfigurasi​

Anda dapat mendapatkan token sebagai berikut​

Mode Tamu​

Mengatur ID tamu saat inisialisasi​

Mengatur atau menghapus ID tamu saat runtime​

Validasi Respons API​

Fitur​

Konfigurasi​

Opsi Konfigurasi​

Mode Validasi​

Mode Lunak (Default)​

Mode Ketat​

Format Bidang Tambahan​

Perilaku Default (rawData: false)​

Mode Mentah (rawData: true)​

Opsi Konfigurasi​

Kesalahan​

Ketika opsi isShell: false diatur dalam konfigurasi SDK, ini memiliki efek berikut:​

📚 Langkah Selanjutnya​

E-commerce

Manajemen Pengguna

Pesanan & Checkout

Halaman & Konten

Formulir

Data Formulir

🚀 Memulai dengan Cepat

Instalasi

2️⃣ Inisialisasi SDK

3️⃣ Mulai menggunakan API

✨ Fitur Utama

🌐 Sumber Daya

📖 Penggunaan Detail

Semua Modul yang Tersedia

Konfigurasi

Anda dapat mendapatkan token sebagai berikut

Mode Tamu

Mengatur ID tamu saat inisialisasi

Mengatur atau menghapus ID tamu saat runtime

Validasi Respons API

Fitur

Konfigurasi

Opsi Konfigurasi

Mode Validasi

Mode Lunak (Default)

Mode Ketat

Format Bidang Tambahan

Perilaku Default (`rawData: false`)

Mode Mentah (`rawData: true`)

Opsi Konfigurasi

Kesalahan

Ketika opsi isShell: false diatur dalam konfigurasi SDK, ini memiliki efek berikut:

📚 Langkah Selanjutnya