Commencer

Le SDK de la plateforme OneEntry est un SDK qui fournit un moyen facile d'interagir avec l'API de la plateforme OneEntry.

---

🚀 Démarrage rapide

Mettez-vous en route avec OneEntry en 3 étapes simples :

Installation

  npm install oneentry

2️⃣ Initialiser le SDK

  import { defineOneEntry } from 'oneentry';

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

3️⃣ Commencer à utiliser l'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'
  });

🎉 C'est tout ! Vous êtes prêt à créer des applications incroyables avec OneEntry.

Vous utilisez TypeScript ? Chaque type public est exporté depuis la racine du package et depuis oneentry/types — import type { IProductsEntity } from 'oneentry'. Voir Importation des types.

---

✨ Fonctionnalités clés

🔐

Authentification sécurisée

Gestion des tokens intégrée et support OAuth

🌍

Multi-langue

Support i18n avec détection automatique de la langue

📝

TypeScript

Définitions de types complètes, importables depuis la racine du package

⚡

Léger

Build ESM optimisé — 9,7 kB gzip dans une configuration typique

🔌

Architecture modulaire

28 modules spécialisés pour tous vos besoins

🛡️

Gestion des erreurs

Gestionnaires d’erreurs personnalisés et mode shell

🌐 Ressources

🌍

Site officiel

En savoir plus sur la plateforme OneEntry

🚀

Inscription

Créez votre compte gratuit

💻

Npmjs

Télécharger le SDK

🧪

Sandbox SDK JS

Essayez les méthodes du SDK en direct dans votre navigateur — aucune configuration requise

📖 Utilisation détaillée

Tous les modules disponibles

Importez et déstructurez tous les modules dont vous avez besoin :

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

Ou

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

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

---

Config

Le deuxième paramètre du constructeur prend la 'config'. Il contient les valeurs suivantes :

• 'token' - Définissez la clé de token si votre projet sécurise le "Token API de sécurité". Si vous utilisez une protection par certificat, ne passez pas cette variable. Vous pouvez en savoir plus sur la sécurité de votre projet ici.
• 'langCode' - Définissez le "langCode" pour définir la langue par défaut. En spécifiant ce paramètre une fois, vous n'avez pas besoin de passer le langCode aux méthodes de l'API ONEENTRY. Si vous n'avez pas passé la langue par défaut, elle sera définie sur "en_US".
• 'traficLimit' - Certaines méthodes utilisent plus d'une requête vers OneEntry afin que les données que vous recevez soient complètes et faciles à utiliser. Passez la valeur "true" pour ce paramètre afin d'économiser du trafic et de décider vous-même quelles données vous avez besoin. La valeur par défaut est "false".
• 'rawData' - Lorsqu'il est défini sur false (par défaut), le SDK transforme automatiquement le tableau additionalFields en un objet indexé par marker pour un accès plus facile. Définissez sur true pour recevoir additionalFields sous forme de tableau original de l'API.
• 'guestId' - Un identifiant de visiteur optionnel envoyé en tant qu'en-tête x-guest-id lors des requêtes non authentifiées, permettant des flux de panier/liste de souhaits/activité pour les invités. Dans le navigateur, s'il est omis, un ID stable par appareil est généré et conservé dans localStorage. Sur le serveur, vous devez passer un guestId par visiteur. Voir Mode invité ci-dessous. La valeur par défaut est undefined.
• 'deviceMetadata' - Une chaîne optionnelle envoyée en tant qu'en-tête x-device-metadata (sur les requêtes POST et le rafraîchissement de token) au lieu de l'empreinte que le SDK calcule à partir de l'environnement actuel. L'API lie les tokens de rafraîchissement à cet en-tête, donc un serveur émettant des tokens au nom d'un navigateur doit estampiller l'empreinte du navigateur ici. Voir Métadonnées de l'appareil ci-dessous. La valeur par défaut est undefined.
• 'auth' - Un objet avec les paramètres d'autorisation. Par défaut, le SDK est configuré pour travailler avec des tokens à l'intérieur de la session de l'utilisateur et ne nécessite aucun travail supplémentaire de votre part. En même temps, le SDK ne stocke pas l'état de la session entre les sessions. Si vous êtes satisfait de ces paramètres, ne passez pas la variable 'auth' du tout.

L' 'auth' contient les paramètres suivants :

• 'refreshToken' - Le token de rafraîchissement de l'utilisateur. Transférez-le ici depuis le dépôt pour restaurer la session de l'utilisateur lors de l'initialisation.
• 'saveFunction' - Une fonction qui travaille avec le token de rafraîchissement mis à jour. Si vous souhaitez stocker le token entre les sessions, par exemple dans le stockage local, passez une fonction ici qui le fait. La fonction doit accepter un paramètre auquel la chaîne avec le token sera passée.
• 'customAuth' - Si vous souhaitez configurer l'autorisation et travailler vous-même avec les tokens, définissez ce drapeau sur true. Si vous souhaitez utiliser les paramètres du SDK, définissez-le sur false ou ne le transférez pas du tout.
• 'providerMarker' - Le marqueur pour le fournisseur d'authentification. Par défaut : 'email'. Un exemple de configuration avec protection par token et authentification automatique qui stocke l'état entre les sessions

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

Un exemple de configuration protégée par un certificat vous permet de configurer le système d'autorisation vous-même et de sauvegarder les données sur les requêtes.

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

Si vous avez choisi de configurer les tokens vous-même, vous pouvez passer le token à la méthode comme suit. La méthode intermédiaire vous permet de passer un token d'accès à la requête. Ensuite, appelez la méthode requise. Cette méthode (setAccessToken) ne doit pas être appelée si la méthode ne nécessite pas d'autorisation utilisateur.

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

Si vous avez choisi la protection par token pour garantir la sécurité de la connexion, passez simplement votre token à la fonction en tant que paramètre optionnel.

Vous pouvez obtenir un token comme suit

1. Connectez-vous à votre compte personnel
2. Allez dans l'onglet "Projets" et sélectionnez un projet
3. Allez dans l'onglet "Accès"
4. Activez le commutateur sur "Token API de sécurité"
5. Connectez-vous au projet, allez dans la section des paramètres et ouvrez l'onglet des tokens
6. Obtenez et copiez le token de votre projet

Vous pouvez également connecter un certificat tls pour protéger votre projet. Dans ce cas, ne passez pas du tout le "token". Lors de l'utilisation du certificat, configurez un proxy dans votre projet. Passez une chaîne vide comme paramètre d'url. En savoir plus sur le certificat 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 invité

Le SDK peut agir au nom d'un invité non authentifié. Lorsqu'aucun token d'accès n'est défini, il envoie un en-tête x-guest-id lors des requêtes, ce qui permet aux points de terminaison conscients des invités de fonctionner sans utilisateur connecté - les flux de panier, liste de souhaits et activité utilisateur, ainsi que les blocs de personnalisation (récemment consulté, recommandations personnelles, et d'autres).

Comment l'ID invité est résolu :

1. Un guestId configuré explicitement (provenant de config.guestId ou setGuestId) l'emporte toujours.
2. Dans le navigateur, lorsqu'aucun n'est fourni, un ID stable est généré (via Web Crypto lorsque disponible) et conservé dans localStorage sous la clé oneentry_guest_id, reflétant la stratégie de métadonnées de l'appareil. Il reste stable à travers les sessions et les onglets.
3. Sinon, l'ID est undefined et l'en-tête x-guest-id est simplement omis.

⚠️ Côté serveur : le SDK ne génère jamais automatiquement un ID invité sur le serveur. Une seule instance partagée de defineOneEntry pourrait autrement faire fuiter un panier/liste de souhaits invités à travers tous les visiteurs anonymes. Sur le serveur, vous devez passer un guestId par visiteur vous-même (via config.guestId ou setGuestId).

L'en-tête est omise pour les requêtes authentifiées (lorsqu'un token d'accès est défini), donc un utilisateur connecté opère toujours sur ses propres données.

Définir l'ID invité lors de l'initialisation

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

Définir ou effacer l'ID invité à l'exécution

setGuestId fonctionne comme setAccessToken - il est chaînable et renvoie l'instance du module. Passez une chaîne vide pour le vider (le SDK revient alors à l'ID soutenu par localStorage dans le navigateur, ou à aucun ID invité du tout sur le serveur).

// 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('');

---

Métadonnées de l'appareil

Le SDK envoie un en-tête x-device-metadata lors des requêtes POST et lors du rafraîchissement de token. Par défaut, c'est une empreinte calculée à partir de l'environnement actuel (plateforme, agent utilisateur, langue, écran, fuseau horaire, plus un ID d'instance persistant), utilisée par l'API pour l'analyse et la lutte contre la fraude.

L'API lie les tokens de rafraîchissement à cet en-tête. Un token de rafraîchissement émis alors qu'une empreinte était envoyée ne peut être rafraîchi que tant que la même empreinte est envoyée — ce qui est exactement le problème lorsque le token est émis sur le serveur au nom d'un navigateur (par exemple, un échange de code OAuth qui garde le secret client côté serveur) : le token serait lié à l'empreinte du serveur et le navigateur ne pourrait jamais le rafraîchir.

deviceMetadata résout cela : le serveur estampille l'empreinte du navigateur, et le token de rafraîchissement émis reste rafraîchissable depuis ce navigateur.

Lire la valeur dans le navigateur

getDeviceMetadata() est disponible sur chaque module et renvoie la chaîne exacte que le SDK envoie — l'override s'il est défini, sinon l'empreinte calculée :

// Browser: obtain the fingerprint and forward it to your backend
const deviceMetadata = api.Users.getDeviceMetadata();

await fetch('/api/oauth/exchange', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ code, deviceMetadata }),
});

Définir l'override

Passez-le lors de l'initialisation :

const api = defineOneEntry('https://my-project.oneentry.cloud', {
  token: 'my-token',
  deviceMetadata, // the string forwarded from the browser
});

Ou définissez-le à l'exécution avec setDeviceMetadata(deviceMetadata) — disponible sur chaque module et chaînable, comme setAccessToken. Passer une chaîne vide efface l'override et revient à l'empreinte calculée :

// Server: issue tokens bound to the browser's fingerprint
const auth = await api.AuthProvider
  .setDeviceMetadata(deviceMetadata)
  .auth('email', authData);

// Clear the override
api.AuthProvider.setDeviceMetadata('');

Méthode	Renvoie	Description
getDeviceMetadata()	string	La chaîne x-device-metadata que cette instance envoie (override, ou empreinte calculée)
setDeviceMetadata(value)	instance de module	Définit l'override ; une chaîne vide l'efface

---

Validation des réponses API

Le SDK OneEntry inclut une validation optionnelle des réponses API utilisant Zod, une bibliothèque de validation de schéma orientée TypeScript. Cette fonctionnalité aide à garantir l'intégrité des données et la sécurité des types lors du travail avec les réponses API.

Fonctionnalités

• Optionnelle : La validation est désactivée par défaut et peut être activée par configuration
• Sécurisée par type : Utilise des schémas Zod qui s'alignent avec les interfaces TypeScript
• Deux modes : Mode doux (journalise les erreurs) et mode strict (renvoie les erreurs)
• Coût nul lorsqu'il est désactivé : Zod et les schémas de réponse sont chargés à la demande — la première fois qu'une réponse doit réellement être validée. Avec la validation désactivée, ils n'atteignent jamais votre bundle (voir Taille du bundle & Formats de module)

Configuration

Activez la validation en ajoutant la propriété validation à votre configuration SDK :

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)
  }
})

Options de configuration

Option	Type	Par défaut	Description
enabled	boolean	false	Activer/désactiver la validation des réponses
strictMode	boolean	false	Lorsque true, renvoie IError en cas d'échec de validation. Lorsque false, journalise les erreurs et renvoie les données originales
logErrors	boolean	true	Journaliser les erreurs de validation dans la console (utile pour le débogage)

Modes de validation

Mode doux (par défaut)

Lorsque strictMode est false, les erreurs de validation sont journalisées dans la console, mais la réponse API originale est renvoyée sans changement. Cela est utile pendant le développement pour identifier les incohérences potentielles des données sans casser votre application.

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 strict

Lorsque strictMode est true, les échecs de validation renvoient un objet IError au lieu des données. Cela garantit que votre application ne traite que des données validées.

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 des champs supplémentaires

Par défaut, le SDK transforme la propriété additionalFields d'un tableau (tel que renvoyé par l'API) en un objet indexé par marker. Cela facilite grandement l'accès à des champs spécifiques sans connaître leur index.

Comportement par défaut (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 brut (rawData: true)

Si vous avez besoin du format de réponse API original (par exemple pour la compatibilité ascendante), définissez 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)

Option de configuration

Option	Type	Par défaut	Description
rawData	boolean	false	Lorsque false, additionalFields est transformé en un objet indexé par marker. Lorsque true, le tableau original de l'API est renvoyé

Le reste de la normalisation que le SDK applique aux valeurs d'attribut - déballage de fichier unique, conversion numérique, null pour les valeurs non définies, tri par position - est décrit dans Valeurs d'attributs.

---

Erreurs

Si vous souhaitez échapper aux erreurs à l'intérieur du sc, laissez la propriété "errors" par défaut. Dans ce cas, vous recevrez soit les données de l'entité, soit l'objet d'erreur. Vous devez effectuer une vérification de type. par exemple, en vérifiant la propriété statusCode avec ".hasOwnProperty"

Cependant, si vous souhaitez utiliser la construction "try catch(e) ", définissez la propriété "isShell" sur la valeur "false". Dans ce cas, vous devez gérer l'erreur en utilisant "try catch(e) ".

De plus, vous pouvez passer des fonctions personnalisées qui seront appelées à l'intérieur du sdk avec le code d'erreur approprié. Ces fonctions reçoivent un objet d'erreur en argument. Vous pouvez le traiter vous-même.

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

Lorsque l'option isShell : false est définie dans la configuration du SDK, elle a l'effet suivant :

Lorsqu'une erreur se produit dans les requêtes API (par exemple, erreurs HTTP 400, 401, 404, 500, etc., ou erreurs réseau), le SDK lancera une exception au lieu de renvoyer l'objet d'erreur comme une valeur normale.

Cela vous permet d'utiliser la construction try/catch dans votre code d'application pour gérer les erreurs :

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

Si isShell : true, les erreurs sont renvoyées comme valeurs, et vous devrez explicitement vérifier le type de résultat pour vérifier :

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
}

Ainsi, isShell : false permet un modèle de gestion des erreurs plus familier avec try/catch, tandis que isShell : true fournit un modèle plat où les erreurs et le succès sont renvoyés comme des valeurs du même type.

Lorsque vous utilisez le SDK avec le paramètre par défaut (isShell défini sur true), les erreurs sont renvoyées comme des valeurs plutôt que lancées comme des exceptions. Cela signifie que l'application ne plantera pas en raison d'exceptions non gérées, car les erreurs sont gérées dans le cadre du flux d'exécution normal. Voici comment vous pouvez gérer les erreurs sur le front-end sans utiliser try/catch :

Vérifiez le type de retour après avoir appelé une méthode 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);
}

Vous pouvez également créer des utilitaires de type "IError" pour vérifier les erreurs :

import type { IError } from 'oneentry';

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

Cette approche vous permet d'éviter d'utiliser des constructions try/catch tout en gérant correctement les erreurs, empêchant l'application de planter.

---

📚 Prochaines étapes

Explorez nos guides complets pour en savoir plus :

🛍️

E-commerce

Construisez des catalogues de produits avec filtrage et recherche

👤

Gestion des utilisateurs

Implémentez l'authentification et les profils utilisateurs

🛒

Commandes & Paiement

Traitez les commandes et gérez les paiements

📄

Pages & Contenu

Gérez des pages dynamiques et des structures de contenu

📝

Formulaires

Apprenez à gérer les formulaires

📝

Données de formulaires

Apprenez à gérer les données de formulaires

🧩

Importation des types

Importez chaque type SDK depuis 'oneentry' ou 'oneentry/types'

⚡

Taille du bundle

Build ESM, tree-shaking et Zod / socket.io à la demande

🧬

Valeurs d'attributs

La forme normalisée dans laquelle chaque attribut arrive

🗓️

Intervalles de temps

Développez les horaires en créneaux de réservation concrets

---