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 :

1️⃣ Installer le package

  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

  // Récupérer les produits 
  const products = await api.Products.getProducts({ limit: 10 });

  // Obtenir le profil utilisateur
  const user = await api.Users.getUser();

  // Soumettre un formulaire
  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.

✨ Fonctionnalités clés

🔐

Authentification sécurisée

Gestion des tokens intégrée et support OAuth

🌍

Multilingue

Support i18n avec détection automatique de la langue

📝

TypeScript

Définitions de types complètes pour une meilleure expérience développeur

⚡

Léger

Taille de bundle optimisée pour la production

🔌

Architecture modulaire

24 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

📖 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: '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);

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

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

Configuration

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

'token' - Définissez la clé de token si votre projet sécurise "Security API Token". 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 à travailler. 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".
'auth' - Un objet avec les paramètres d'autorisation. Par défaut, le SDK est configuré pour fonctionner 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 ici une fonction 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 qui vous permet de configurer vous-même le système d'autorisation 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 vous-même les tokens, vous pouvez passer le token à la méthode comme suit.
La méthode intermédiaire 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, il vous suffit de passer votre token à la fonction en tant que paramètre optionnel.

Vous pouvez obtenir un token comme suit

Connectez-vous à votre compte personnel
Allez à l'onglet "Projets" et sélectionnez un projet
Allez à l'onglet "Accès"
Activez le commutateur sur "Security API Token"
Connectez-vous au projet, allez à la section des paramètres et ouvrez l'onglet des tokens
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 le "token" du tout. 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'  
  },  
});  

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 de l'utilisation des 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 (retourne les erreurs)
Aucun surcoût d'exécution lorsque désactivé : Aucun impact sur les performances si la validation est désactivée

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,        // Activer la validation (par défaut : false)  
    strictMode: false,    // Mode strict (par défaut : false)  
    logErrors: true,      // Journaliser les erreurs de validation (par défaut : 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`, retourne `IError` en cas d'échec de validation. Lorsque `false`, journalise les erreurs et retourne les données d'origine
`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 d'origine est retourné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,  // Mode doux  
    logErrors: true,  
  }  
})

// Même si la validation échoue, vous obtiendrez la réponse API
const user = await api.Users.getUser()
// La console affichera les erreurs de validation s'il y en a

Mode strict

Lorsque strictMode est true, les échecs de validation retournent 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,   // Mode strict  
    logErrors: true,  
  }  
})

const user = await api.Users.getUser()

// Vérifiez si la réponse est une erreur
if ('statusCode' in user) {  
  console.error('Échec de la validation :', user.message)  
} else {  
  // Sécurisé par type : user est IUserEntity  
  console.log('Utilisateur :', user.email)  
}

Erreurs

Si vous souhaitez échapper aux erreurs à l'intérieur du SDK, 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('Mauvaise requête :', error.message),  
      401: (error) => console.error('Non autorisé :', error.message),  
      403: (error) => console.error('Interdit :', error.message),  
      404: (error) => console.error('Non trouvé :', error.message),  
      429: (error) => console.error('Limite de taux dépassée :', error.message),  
      500: (error) => console.error('Erreur serveur :', error.message),  
      502: (error) => console.error('Mauvaise passerelle :', error.message),  
      503: (error) => console.error('Service indisponible :', error.message),  
      504: (error) => console.error('Délai d'attente de la passerelle :', 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 retourner 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();  
  // Gestion d'un résultat réussi  
} catch (error) {  
  // Gestion des erreurs  
}

Si isShell : true, les erreurs sont retourné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) { // Supposons la présence d'une propriété statusCode sur l'objet d'erreur  
  // Gestion des erreurs  
} else {  
  // Gestion d'un résultat réussi  
}

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 retournés comme des valeurs du même type.

Lors de l'utilisation du SDK avec le paramètre par défaut (isShell défini sur true), les erreurs sont retourné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 traitées comme faisant partie 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();

// Vérifiez si le résultat est une erreur
if ('statusCode' in result || 'message' in result) {  
  // Gestion des erreurs  
  console.error('Erreur :', result);  
} else {  
  // Gestion d'un résultat réussi  
  console.log('Succès :', result);  
}

Vous pouvez également créer un type utilitaire "IError" pour vérifier les erreurs :

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

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

// Ensuite, utilisez-le comme ceci :
const result = await api.someMethod();

if (isErrorResult(result)) {  
  // Gestion des erreurs  
  console.error('Une erreur s'est produite :', result);  
} else {  
  // Gestion d'un résultat réussi  
  console.log('Résultat réussi :', result);  
}

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

📚 Prochaines étapes

Explorez nos guides complets pour en savoir plus :

🛍️

Commencer

🚀 Démarrage rapide

1️⃣ Installer le package

2️⃣ Initialiser le SDK

3️⃣ Commencer à utiliser l'API

✨ Fonctionnalités clés

🌐 Ressources

📖 Utilisation détaillée

Tous les modules disponibles

Configuration

Vous pouvez obtenir un token comme suit

Validation des réponses API

Fonctionnalités

Configuration

Options de configuration

Modes de validation

Mode doux (par défaut)

Mode strict

Erreurs

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

📚 Prochaines étapes

E-commerce

Gestion des utilisateurs

Commandes & Paiement

Pages & Contenu

Formulaires

Données de formulaires

Commencer

🚀 Démarrage rapide​

1️⃣ Installer le package​

2️⃣ Initialiser le SDK​

3️⃣ Commencer à utiliser l'API​

✨ Fonctionnalités clés​

🌐 Ressources​

📖 Utilisation détaillée​

Tous les modules disponibles​

Configuration​

Vous pouvez obtenir un token comme suit​

Validation des réponses API

Fonctionnalités​

Configuration​

Options de configuration​

Modes de validation​

Mode doux (par défaut)​

Mode strict​

Erreurs​

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

📚 Prochaines étapes​

E-commerce

Gestion des utilisateurs

Commandes & Paiement

Pages & Contenu

Formulaires

Données de formulaires

🚀 Démarrage rapide

1️⃣ Installer le package

2️⃣ Initialiser le SDK

3️⃣ Commencer à utiliser l'API

✨ Fonctionnalités clés

🌐 Ressources

📖 Utilisation détaillée

Tous les modules disponibles

Configuration

Vous pouvez obtenir un token comme suit

Fonctionnalités

Configuration

Options de configuration

Modes de validation

Mode doux (par défaut)

Mode strict

Erreurs

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

📚 Prochaines étapes