genuka-api/README.md

Javascript(TS) Package to use Genuka API for a StoreFront website

# Genuka JavaScript SDK

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

[![npm version](https://img.shields.io/npm/v/genuka-api.svg)](https://www.npmjs.com/package/genuka-api)
[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](https://opensource.org/licenses/ISC)

## Table des matières

- [Genuka JavaScript SDK](#genuka-javascript-sdk)
  - [Table des matières](#table-des-matières)
  - [Installation](#installation)
  - [Démarrage rapide](#démarrage-rapide)
  - [Architecture](#architecture)
  - [Configuration](#configuration)
    - [Initialisation simple](#initialisation-simple)
    - [Initialisation avec options avancées](#initialisation-avec-options-avancées)
    - [Création manuelle d'une instance](#création-manuelle-dune-instance)
    - [Définir le token d'authentification](#définir-le-token-dauthentification)
  - [Services disponibles](#services-disponibles)
    - [Company](#company)
    - [Products](#products)
    - [Collections](#collections)
    - [Cart](#cart)
    - [Customers](#customers)
    - [Orders](#orders)
    - [Shops](#shops)
    - [Autres services](#autres-services)
      - [Blogs et Articles](#blogs-et-articles)
      - [Pages](#pages)
      - [Méthodes de paiement](#méthodes-de-paiement)
      - [Expédition et livraison](#expédition-et-livraison)
      - [Abonnements et réductions](#abonnements-et-réductions)
  - [Exemples d'utilisation](#exemples-dutilisation)
    - [Exemple 1 : Boutique e-commerce complète](#exemple-1--boutique-e-commerce-complète)
    - [Exemple 2 : Recherche et filtrage](#exemple-2--recherche-et-filtrage)
    - [Exemple 3 : Gestion du panier persistant](#exemple-3--gestion-du-panier-persistant)
  - [Gestion des erreurs](#gestion-des-erreurs)
  - [Support TypeScript](#support-typescript)
  - [Contribution](#contribution)
    - [Contact](#contact)
    - [Développement local](#développement-local)
  - [Licence](#licence)

## Installation

```bash
npm install genuka-api
```

ou avec yarn :

```bash
yarn add genuka-api
```

## Démarrage rapide

```typescript
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

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

### Initialisation avec options avancées

```typescript
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 :

```typescript
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

```typescript
// Après connexion d'un client
const { token } = await genuka.customers.login({
  email: "client@email.com",
  password: "password",
});

genuka.setToken(token);
```

## Services disponibles

### Company

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

```typescript
// 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.

```typescript
// 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.

```typescript
// 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).

```typescript
// 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.

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

// Connexion
const { token, customer } = await genuka.customers.login({
  email: "john.doe@email.com",
  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.

```typescript
// 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: "john.doe@email.com",
  },
  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.

```typescript
// 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

```typescript
// 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

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

#### Méthodes de paiement

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

#### Expédition et livraison

```typescript
// 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

```typescript
// 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

```typescript
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: "client@email.com",
  password: "password",
});
genuka.setToken(token);

// Créer la commande
const order = await genuka.orders.create({
  customer: {
    first_name: "John",
    last_name: "Doe",
    email: "client@email.com",
    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

```typescript
// 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

```typescript
// 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 :

```typescript
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 :

```typescript
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 :

```typescript
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: "client@email.com",
  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** : it@genuka.com
- **Issues** : [GitLab Issues](https://gitlab.com/genuka/genuka-package/issues)

### Développement local

```bash
# 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