Genuka JavaScript SDK

SDK JavaScript/TypeScript officiel pour intégrer la plateforme e-commerce Genuka dans vos applications web.

Table des matières

• Genuka JavaScript SDK
  • Table des matières
  • Installation
  • Démarrage rapide
  • Architecture
  • Configuration
    • Initialisation simple
    • Initialisation avec options avancées
    • Création manuelle d'une instance
    • Définir le token d'authentification
  • Services disponibles
    • Company
    • Products
    • Collections
    • Cart
    • Customers
    • Orders
    • Shops
    • Autres services
      • Blogs et Articles
      • Pages
      • Méthodes de paiement
      • Expédition et livraison
      • Abonnements et réductions
  • Exemples d'utilisation
    • Exemple 1 : Boutique e-commerce complète
    • Exemple 2 : Recherche et filtrage
    • Exemple 3 : Gestion du panier persistant
  • Gestion des erreurs
  • Support TypeScript
  • Contribution
    • Contact
    • Développement local
  • Licence

Installation

npm install genuka-api

ou avec yarn :

yarn add genuka-api

Démarrage rapide

import Genuka from "genuka-api";

// Initialisation avec le domaine de votre boutique
const genuka = await Genuka.initialize({
  domain: "votre-boutique.genuka.com",
});

// Récupérer les produits
const products = await genuka.products.list({
  page: 1,
  limit: 10,
});

// Ajouter un produit au panier
genuka.cart.add({
  product_id: "01hkav9sz3qsj4tfdn3yd7214p",
  variant_id: "01hkav9sz3qsj4tfdn3yd7214q",
  price: 2000,
  quantity: 1,
});

// Récupérer le panier
const cart = genuka.cart.retrieve();

Architecture

Le SDK Genuka est structuré autour de services qui correspondent aux différentes fonctionnalités de la plateforme :

genuka
├── company         // Informations de l'entreprise
├── shops           // Gestion des boutiques
├── products        // Catalogue de produits
├── collections     // Collections de produits
├── cart            // Panier d'achat (local)
├── customers       // Authentification et gestion clients
├── orders          // Commandes
├── addresses       // Adresses de livraison
├── blogs           // Gestion de blog
├── articles        // Articles de blog
├── pages           // Pages personnalisées
├── paymentMethods  // Méthodes de paiement
├── shippings       // Options d'expédition
├── pickups         // Points de retrait
├── deliveries      // Livraisons
├── subscriptions   // Abonnements
├── discounts       // Codes promo et réductions
├── bills           // Factures
├── invoices        // Factures détaillées
└── returns         // Retours produits

Configuration

Options de configuration

| Option | Type | Défaut | Description | |--------|------|--------|-------------| | domain | string | - | Domaine de votre boutique (ex: maboutique.genuka.com) | | token | string | - | Token d'authentification | | lang | string | "en" | Langue pour les réponses API | | timezone | string | "Africa/Douala" | Fuseau horaire pour la gestion des dates | | apiBaseUrl | string | "https://api.genuka.com" | URL de base de l'API (utile pour les tests) | | version | string | "2023-11" | Version de l'API | | adminMode | boolean | false | Activer le mode administrateur | | companyId | string | - | ID de l'entreprise (auto-résolu depuis le domaine) | | shopId | string | - | ID de la boutique (auto-résolu depuis le domaine) |

Initialisation simple

const genuka = await Genuka.initialize({
  domain: "votre-boutique.genuka.com",
});

Initialisation avec options avancées

const genuka = await Genuka.initialize({
  domain: "votre-boutique.genuka.com",
  token: "customer_auth_token", // Token d'authentification client (optionnel)
  lang: "fr", // Langue (fr, en, etc.)
  timezone: "Africa/Douala", // Fuseau horaire
  shopId: "01hhfzx7ftzrqjxhx8fbb6ddfs", // ID de la boutique spécifique
  adminMode: false, // Mode administrateur (défaut: false)
  version: "2023-11", // Version de l'API
  // apiBaseUrl: "http://localhost:8000", // Pour le développement local
});

Création manuelle d'une instance

Pour des cas d'usage avancés où vous voulez créer plusieurs instances :

const genuka = Genuka.create({
  domain: "votre-boutique.genuka.com",
  lang: "fr",
});

// Configuration manuelle
await genuka.setup({
  domain: "votre-boutique.genuka.com",
  resolveShop: true, // Résoudre automatiquement le shop ID
});

Définir le token d'authentification

// Après connexion d'un client
const { token } = await genuka.customers.login({
  email: "[email protected]",
  password: "password",
});

genuka.setToken(token);

Services disponibles

Company

Récupérer les informations de l'entreprise.

// Récupérer les détails de l'entreprise
const company = await genuka.company.retrieve();
console.log(company.name, company.logo, company.description);

Products

Gérer le catalogue de produits.

// Compter le nombre de produits
const count = await genuka.products.count();

// Lister les produits avec pagination et filtres
const products = await genuka.products.list({
  page: 1,
  limit: 20,
  filter: {
    status: "active",
    collection_id: "01hkav9sz3qsj4tfdn3yd7214p",
  },
  sort: ["-created_at"], // Trier par date (décroissant)
  include: ["variants", "images"], // Inclure les relations
  queries: {
    min_price: 1000,
    max_price: 50000,
  },
});

// Récupérer un produit par ID
const product = await genuka.products.retrieve({
  id: "01hkav9sz3qsj4tfdn3yd7214p",
});

// Récupérer un produit par handle (slug)
const product = await genuka.products.retrieve({
  handle: "mon-produit",
});

// Récupérer des produits similaires
const similar = await genuka.products.similar({
  id: "01hkav9sz3qsj4tfdn3yd7214p",
  limit: 5,
});

// Accéder aux variants d'un produit
const variants = await genuka.products.variants.list({
  product_id: "01hkav9sz3qsj4tfdn3yd7214p",
});

Collections

Gérer les collections de produits.

// Compter les collections
const count = await genuka.collections.count();

// Lister les collections
const collections = await genuka.collections.list({
  page: 1,
  limit: 10,
  include: ["products"],
});

// Récupérer une collection
const collection = await genuka.collections.retrieve({
  id: "01hkav9sz3qsj4tfdn3yd7214p",
});

// Par handle
const collection = await genuka.collections.retrieve({
  handle: "nouvelle-collection",
});

// Collections similaires
const similar = await genuka.collections.similar({
  id: "01hkav9sz3qsj4tfdn3yd7214p",
  limit: 3,
});

Cart

Gérer le panier d'achat (gestion locale côté client).

// Ajouter un produit au panier
genuka.cart.add({
  product_id: "01hkav9sz3qsj4tfdn3yd7214p",
  variant_id: "01hkav9sz3qsj4tfdn3yd7214q",
  title: "Mon produit",
  price: 2000,
  quantity: 1,
  metadata: { color: "rouge", size: "M" },
});

// Récupérer le panier
const cart = genuka.cart.retrieve();
console.log(cart); // Array de CartItem
console.log(genuka.cart.total); // Total du panier

// Mettre à jour la quantité d'un article
genuka.cart.update("variant_id", {
  quantity: 3,
});

// Vérifier la disponibilité d'un produit
const available = await genuka.cart.checkAvailability({
  product_id: "01hkav9sz3qsj4tfdn3yd7214p",
  variant_id: "01hkav9sz3qsj4tfdn3yd7214q",
  quantity: 2,
});

// Retirer un article du panier
genuka.cart.remove("variant_id");

// Vider le panier
genuka.cart.clear();

// Définir le panier (restauration)
genuka.cart.set([
  { variant_id: "...", product_id: "...", price: 2000, quantity: 1 },
]);

Customers

Authentification et gestion des clients.

// Créer un compte client
const newCustomer = await genuka.customers.create({
  first_name: "John",
  last_name: "Doe",
  email: "[email protected]",
  phone: "+237695762595",
  password: "motdepasse123",
  password_confirmation: "motdepasse123",
  metadata: { source: "web" },
});

// Connexion
const { token, customer } = await genuka.customers.login({
  email: "[email protected]",
  password: "motdepasse123",
});

// Définir le token pour les requêtes authentifiées
genuka.setToken(token);

// Récupérer les informations du client connecté
const currentCustomer = await genuka.customers.retrieve();

// Mettre à jour le profil
const updated = await genuka.customers.update({
  first_name: "Jane",
  phone: "+237695762595",
});

// Déconnexion (côté client)
// Supprimer le token et vider le panier
genuka.setToken("");
genuka.cart.clear();

Orders

Gérer les commandes.

// Lister les commandes du client connecté
const orders = await genuka.orders.list({
  page: 1,
  limit: 10,
  filter: { status: "pending" },
});

// Créer une commande
const order = await genuka.orders.create({
  customer: {
    first_name: "John",
    last_name: "Doe",
    phone: "+237695762595",
    email: "[email protected]",
  },
  shipping: {
    mode: "delivery", // ou "pickup"
    amount: 500,
    address: {
      first_name: "John",
      last_name: "Doe",
      phone: "+237695762595",
      line1: "123 Rue principale",
      line2: "Appartement 4B",
      city: "Douala",
      state: "Littoral",
      postal_code: "00237",
      country: "Cameroun",
    },
  },
  billing: {
    method: "cash", // ou "card", "mobile_money", etc.
    address: {
      // Même structure que shipping.address
      first_name: "John",
      last_name: "Doe",
      phone: "+237695762595",
      line1: "123 Rue principale",
      city: "Douala",
      state: "Littoral",
      postal_code: "00237",
      country: "Cameroun",
    },
  },
  products: [
    {
      title: "Mon produit",
      price: 2000,
      quantity: 2,
    },
  ],
});

// Récupérer une commande spécifique
const order = await genuka.orders.retrieve({
  id: "01hkav9sz3qsj4tfdn3yd7214p",
});

Shops

Gérer les boutiques.

// Lister toutes les boutiques
const shops = await genuka.shops.list();

// Récupérer les détails d'une boutique
const shop = await genuka.shops.retrieve({
  id: "01hhfzx7ftzrqjxhx8fbb6ddfs",
});

// Définir la boutique active
genuka.setShopId("01hhfzx7ftzrqjxhx8fbb6ddfs");

Autres services

Tous les autres services suivent des patterns similaires avec list(), retrieve(), create(), update(), etc.

Blogs et Articles

// Blogs
const blogs = await genuka.blogs.list();
const blog = await genuka.blogs.retrieve({ id: "..." });

// Articles
const articles = await genuka.articles.list({
  filter: { blog_id: "..." },
});
const article = await genuka.articles.retrieve({ handle: "mon-article" });

Pages

const pages = await genuka.pages.list();
const page = await genuka.pages.retrieve({ handle: "a-propos" });

Méthodes de paiement

const paymentMethods = await genuka.paymentMethods.list();

Expédition et livraison

// Options d'expédition
const shippings = await genuka.shippings.list();

// Points de retrait
const pickups = await genuka.pickups.list();

// Livraisons
const deliveries = await genuka.deliveries.list();

Abonnements et réductions

// Abonnements
const subscriptions = await genuka.subscriptions.list();

// Codes promo
const discounts = await genuka.discounts.list();
const discount = await genuka.discounts.retrieve({ code: "PROMO2024" });

Exemples d'utilisation

Exemple 1 : Boutique e-commerce complète

import Genuka from "genuka-api";

// Initialisation
const genuka = await Genuka.initialize({
  domain: "ma-boutique.genuka.com",
  lang: "fr",
});

// Charger les produits
const products = await genuka.products.list({
  page: 1,
  limit: 12,
  sort: ["-created_at"],
});

// Ajouter au panier
products.forEach((product) => {
  const variant = product.variants[0];
  genuka.cart.add({
    product_id: product.id,
    variant_id: variant.id,
    title: product.title,
    price: variant.price,
    quantity: 1,
  });
});

// Connexion client
const { token } = await genuka.customers.login({
  email: "[email protected]",
  password: "password",
});
genuka.setToken(token);

// Créer la commande
const order = await genuka.orders.create({
  customer: {
    first_name: "John",
    last_name: "Doe",
    email: "[email protected]",
    phone: "+237695762595",
  },
  shipping: {
    mode: "delivery",
    amount: 500,
    address: {
      first_name: "John",
      last_name: "Doe",
      phone: "+237695762595",
      line1: "123 Rue principale",
      city: "Douala",
      state: "Littoral",
      postal_code: "00237",
      country: "Cameroun",
    },
  },
  billing: {
    method: "mobile_money",
    address: {
      first_name: "John",
      last_name: "Doe",
      phone: "+237695762595",
      line1: "123 Rue principale",
      city: "Douala",
      state: "Littoral",
      postal_code: "00237",
      country: "Cameroun",
    },
  },
  products: genuka.cart.retrieve().map((item) => ({
    title: item.title,
    price: item.price,
    quantity: item.quantity,
  })),
});

// Vider le panier après commande
genuka.cart.clear();

Exemple 2 : Recherche et filtrage

// Recherche de produits par catégorie
const electronics = await genuka.products.list({
  filter: { collection_handle: "electronique" },
  limit: 20,
  include: ["images", "variants"],
});

// Filtrage par prix
const affordableProducts = await genuka.products.list({
  queries: {
    min_price: 0,
    max_price: 10000,
  },
});

// Tri par popularité
const popular = await genuka.products.list({
  sort: ["-sales_count"],
  limit: 10,
});

Exemple 3 : Gestion du panier persistant

// Sauvegarder le panier dans localStorage
function saveCart(genuka) {
  const cart = genuka.cart.retrieve();
  localStorage.setItem("genuka_cart", JSON.stringify(cart));
}

// Restaurer le panier depuis localStorage
function loadCart(genuka) {
  const saved = localStorage.getItem("genuka_cart");
  if (saved) {
    const cart = JSON.parse(saved);
    genuka.cart.set(cart);
  }
}

// Utilisation
const genuka = await Genuka.initialize({ domain: "..." });
loadCart(genuka);

// Ajouter un produit
genuka.cart.add({
  /* ... */
});
saveCart(genuka);

Gestion des erreurs

Le SDK retourne des objets avec une propriété error en cas d'échec :

const product = await genuka.products.retrieve({ id: "invalid-id" });

if (product.error) {
  console.error("Erreur:", product.error);
  // Gérer l'erreur
} else {
  // Utiliser le produit
  console.log(product.title);
}

Pour une gestion plus robuste :

try {
  const products = await genuka.products.list({ page: 1, limit: 10 });

  if (products.error) {
    throw new Error(products.error);
  }

  // Traiter les produits
  products.forEach((product) => {
    console.log(product.title);
  });
} catch (error) {
  console.error("Erreur lors de la récupération des produits:", error);
  // Afficher un message à l'utilisateur
}

Support TypeScript

Le SDK est écrit en TypeScript et fournit des types complets :

import Genuka, { Config, ListProps, CustomerCreate } from "genuka-api";

// Configuration typée
const config: Config = {
  domain: "ma-boutique.genuka.com",
  lang: "fr",
  token: "...",
};

// Paramètres de liste typés
const listParams: ListProps = {
  page: 1,
  limit: 10,
  filter: { status: "active" },
  sort: ["-created_at"],
  include: ["variants"],
};

// Création de client typée
const newCustomer: CustomerCreate = {
  email: "[email protected]",
  first_name: "John",
  last_name: "Doe",
  password: "password123",
  password_confirmation: "password123",
};

Contribution

Nous accueillons les contributions sous forme de :

• Pull requests : Améliorations, corrections de bugs, nouvelles fonctionnalités
• Issues : Rapports de bugs, suggestions de fonctionnalités
• Documentation : Améliorations de la documentation, exemples

Contact

• Email : [email protected]
• Issues : GitLab Issues

Développement local

# Cloner le projet
git clone https://gitlab.com/genuka/genuka-package.git
cd genuka-package

# Installer les dépendances
yarn install

# Build
yarn build

# Tester localement
yarn updateLink

Licence

ISC License - voir le fichier LICENSE pour plus de détails.

Genuka SARL - Plateforme e-commerce tout-en-un pour l'Afrique