SDK

Le Djust Front SDK est un kit de développement JavaScript conçu pour simplifier et optimiser les appels API vers le backend Djust. Cette documentation explique comment initialiser et configurer le SDK dans une application Nuxt 3.

Architecture d'Initialisation

graph TB
    subgraph "Initialisation SDK"
        ENV[Variables d'Environnement]
        CONFIG[Configuration Runtime Nuxt]
        UTILS[djust-sdk.ts Utils]
        SDK[Instance SDK]
        COOKIES[Gestion Cookies]
    end

    ENV --> CONFIG
    CONFIG --> UTILS
    UTILS --> SDK
    COOKIES --> SDK

    style ENV fill:#e1f5fe
    style SDK fill:#f3e5f5
    style COOKIES fill:#fff3e0

Prérequis

1. Installation du Package

npm install @djust-b2b/djust-front-sdk

2. Clé API Djust

Vous devez disposer des informations d'authentification fournies par Djust :

Client ID : Identifiant client unique
API Key : Clé d'authentification
Store ID et Store View ID : Identifiants du magasin

Configuration des Variables d'Environnement

Fichier `.env`

Créez un fichier .env à la racine de votre projet avec les variables suivantes :

# === CONFIGURATION API DJUST === #
VITE_API_BASE_URL=https://api.djust.com
VITE_DJ_API_CLIENT=your_client_id_here
VITE_DJ_API_KEY=your_api_key_here

# === CONFIGURATION MAGASIN === #
STORE_ID=your_store_id_here
STORE_VIEW_ID=your_store_view_id_here

# === CONFIGURATION LOCALE === #
LOCALE=fr-FR
DEFAULTCURRENCY=EUR
CURRENCIES=EUR,USD,GBP

# === CONFIGURATION APPLICATION === #
CLIENT_NAME=MonApplication
APPLICATION_ENV=development
FRONT_MODE=private
MULTI_STORES=false

# === CONFIGURATION MONITORING === #
SENTRY_DSN=your_sentry_dsn_here

# === CONFIGURATION PAGINATION === #
DEFAULT_PAGINATION_SIZE=20
DEFAULT_ID_TYPE=EXTERNAL_ID

Variables Obligatoires

Variable	Description	Exemple	Obligatoire
`VITE_API_BASE_URL`	URL de base de l'API Djust	`https://api.djust.com`	✅
`VITE_DJ_API_CLIENT`	Identifiant client Djust	`client_123456`	✅
`VITE_DJ_API_KEY`	Clé API Djust	`api_key_abcdef`	✅
`STORE_ID`	Identifiant du magasin	`store_789`	✅
`STORE_VIEW_ID`	Identifiant de la vue magasin	`view_456`	✅

Variables Optionnelles

Variable	Description	Valeur par Défaut	Exemple
`LOCALE`	Langue par défaut	`fr-FR`	`en-GB`, `fr-FR`
`DEFAULTCURRENCY`	Devise par défaut	`EUR`	`USD`, `GBP`
`CLIENT_NAME`	Nom de l'application	`Djust`	`MonApp`
`APPLICATION_ENV`	Environnement	`development`	`production`, `staging`
`SENTRY_DSN`	URL Sentry pour monitoring	SDK par défaut	URL Sentry personnalisée

Configuration Nuxt

nuxt.config.ts

Le SDK utilise la configuration runtime de Nuxt pour accéder aux variables d'environnement :

export default defineNuxtConfig({
  runtimeConfig: {
    // Côté serveur uniquement
    apiBaseUrl: process.env.VITE_API_BASE_URL,
    djApiClient: process.env.VITE_DJ_API_CLIENT,
    djApiKey: process.env.VITE_DJ_API_KEY,

    public: {
      // Disponible côté client et serveur
      apiBaseUrl: process.env.VITE_API_BASE_URL,
      djApiClient: process.env.VITE_DJ_API_CLIENT,
      djApiKey: process.env.VITE_DJ_API_KEY,
      djStoreId: process.env.STORE_ID,
      djStoreViewId: process.env.STORE_VIEW_ID,
      locale: process.env.LOCALE,
      currency: process.env.DEFAULTCURRENCY,
      currencies: process.env.CURRENCIES,
      clientName: process.env.CLIENT_NAME,
      applicationEnv: process.env.APPLICATION_ENV,
      sentryDsn: process.env.SENTRY_DSN,
      multiStores: process.env.MULTI_STORES === "true",
      frontMode: process.env.FRONT_MODE || "private",
      defaultPaginationSize: process.env.DEFAULT_PAGINATION_SIZE || "20",
    },
  },
});

Utilitaire d'Initialisation

Fichier `server/utils/djust-sdk.ts`

Créez un utilitaire pour gérer l'initialisation et la mise à jour du SDK :

import { DjustSDK } from "@djust-b2b/djust-front-sdk";
import { getCookie } from "h3";

let sdkInstance: typeof DjustSDK | null = null;

interface ClientConfig {
  baseUrl: string;
  clientId: string;
  apiKey: string;
  timeout?: number;
  locale?: string;
  headers?: Headers;
  accessToken?: string;
  storeId?: string;
  storeViewId?: string;
  customerAccountId?: string;
  clientName?: string;
  env?: string;
  dsn?: string;
}

const djustSDK = (event: any) => {
  // Initialisation unique du SDK
  if (!sdkInstance) {
    const {
      public: {
        apiBaseUrl,
        djApiClient,
        djApiKey,
        locale,
        djStoreId,
        djStoreViewId,
        clientName,
        applicationEnv,
        sentryDsn,
      },
    } = useRuntimeConfig();

    // Initialisation avec la configuration de base
    DjustSDK.initialize({
      baseUrl: apiBaseUrl,
      clientId: djApiClient,
      apiKey: djApiKey,
      storeId: djStoreId,
      storeViewId: djStoreViewId,
      locale,
      clientName: clientName,
      env: applicationEnv,
      dsn: sentryDsn,
    });

    sdkInstance = DjustSDK;
  }

  // Mise à jour dynamique avec les cookies
  const token = getCookie(event, "token");
  const customerAccountId = getCookie(event, "customer-account-id");
  const storeId = getCookie(event, "store-id");
  const storeViewId = getCookie(event, "store-view-id");

  const configUpdates: Partial<ClientConfig> = {};

  // Ajout du token d'authentification si disponible
  if (token) {
    configUpdates.accessToken = token;
    configUpdates.customerAccountId = customerAccountId;
  }

  // Mise à jour des identifiants de magasin si disponibles
  if (storeId && storeViewId) {
    configUpdates.storeId = storeId;
    configUpdates.storeViewId = storeViewId;
  }

  // Application des mises à jour si nécessaire
  if (Object.keys(configUpdates).length > 0) {
    DjustSDK.updateConfiguration(configUpdates);
    sdkInstance = DjustSDK;
  }

  return sdkInstance;
};

export default djustSDK;

Interface de Configuration

Type ClientConfig

interface ClientConfig {
  // === PARAMÈTRES OBLIGATOIRES === //
  baseUrl: string; // URL de base de l'API
  clientId: string; // Identifiant client
  apiKey: string; // Clé d'authentification

  // === PARAMÈTRES OPTIONNELS === //
  timeout?: number; // Timeout des requêtes (ms)
  locale?: string; // Langue (fr-FR, en-GB, etc.)
  headers?: Headers; // En-têtes HTTP personnalisés

  // === PARAMÈTRES D'AUTHENTIFICATION === //
  accessToken?: string; // Token JWT d'authentification
  customerAccountId?: string; // ID du compte client

  // === PARAMÈTRES DE MAGASIN === //
  storeId?: string; // Identifiant du magasin
  storeViewId?: string; // Identifiant de la vue magasin

  // === PARAMÈTRES APPLICATION === //
  clientName?: string; // Nom de l'application
  env?: string; // Environnement (development, production)
  dsn?: string; // URL Sentry pour monitoring
}

Utilisation dans les API Routes

Exemple d'utilisation

// server/api/products/index.get.ts
import initializeSDK from "~/server/utils/djust-sdk";

export default defineEventHandler(async (event) => {
  try {
    // Initialisation du SDK avec gestion automatique des cookies
    const sdk = initializeSDK(event);

    // Récupération des paramètres de requête
    const query = getQuery(event);
    const { locale, currency } = query;

    // Appel API via le SDK
    const products = await sdk.getProducts({
      locale: locale || "fr-FR",
      currency: currency || "EUR",
      size: 20,
      page: 0,
    });

    return {
      success: true,
      products,
    };
  } catch (error) {
    console.error("Erreur lors de la récupération des produits:", error);
    return {
      success: false,
      message: "Erreur lors de la récupération des produits",
    };
  }
});

Gestion Dynamique de la Configuration

Mise à Jour en Temps Réel

Le SDK peut être mis à jour dynamiquement pour gérer :

1. Authentification Utilisateur

// Après connexion utilisateur
sdk.updateConfiguration({
  accessToken: "jwt_token_here",
  customerAccountId: "customer_123",
});

2. Changement de Magasin

// Changement de magasin/vue
sdk.updateConfiguration({
  storeId: "new_store_456",
  storeViewId: "new_view_789",
});

3. Changement de Langue

// Changement de langue
sdk.updateConfiguration({
  locale: "en-GB",
});

Headers HTTP Automatiques

Le SDK ajoute automatiquement les en-têtes suivants aux requêtes :

En-têtes Obligatoires

{
  "dj-client": "your_client_id",           // Identifiant client
  "dj-api-key": "your_api_key",           // Clé API
  "Content-Type": "application/json"       // Type de contenu
}

En-têtes Conditionnels

{
  "Authorization": "Bearer jwt_token",          // Si token disponible
  "locale": "fr-FR",                           // Si locale configurée
  "customer-account-id": "customer_123",       // Si compte client
  "dj-store": "store_456",                     // Si magasin configuré
  "dj-store-view": "view_789"                  // Si vue magasin configurée
}

Gestion des Erreurs

Validation de l'Initialisation

// Le SDK vérifie automatiquement l'initialisation
if (!isClientInitialized(clientConfig)) {
  const error = new Error("[Djust SDK] SDK not initialized.");
  Sentry.captureException(error);
  throw error;
}

Gestion des Tokens

// Validation automatique des tokens
if (isTokenValid(accessToken)) {
  requestHeaders.append("Authorization", `Bearer ${accessToken}`);
}

Monitoring avec Sentry

Configuration Automatique

Le SDK configure automatiquement Sentry si un DSN est fourni :

Sentry.init({
  dsn: clientConfig.dsn,
  environment: `${clientConfig.clientName}-${clientConfig.env}`,
  integrations: [
    Sentry.browserTracingIntegration(),
    Sentry.replayIntegration(),
    Sentry.httpClientIntegration(),
    // ... autres intégrations
  ],
  tracesSampleRate: 1.0,
  replaysSessionSampleRate: 0.1,
  replaysOnErrorSampleRate: 1.0,
});

Logging Automatique

console.log(
  `[Djust SDK] Sentry initialized in ${clientConfig.clientName} environment: ${clientConfig.env}`
);

Bonnes Pratiques

1. Sécurité

✅ Protégez vos clés API : Ne jamais exposer les clés côté client
✅ Utilisez HTTPS : Toujours utiliser des connexions sécurisées
✅ Validez les tokens : Vérifier la validité des tokens d'authentification

2. Performance

✅ Instance unique : Le SDK utilise un pattern singleton
✅ Mise à jour conditionnelle : Ne met à jour que si nécessaire
✅ Gestion de cache : Réutilise l'instance configurée

3. Maintenance

✅ Variables d'environnement : Centralisez la configuration
✅ Logging : Activez les logs pour le debugging
✅ Monitoring : Configurez Sentry pour le suivi d'erreurs

4. Développement

✅ Validation locale : Testez avec différentes configurations
✅ Gestion d'erreurs : Implémentez des fallbacks appropriés
✅ Documentation : Documentez les configurations spécifiques

Exemple d'Environnements

Développement

VITE_API_BASE_URL=https://api-dev.djust.com
APPLICATION_ENV=development
CLIENT_NAME=MonApp-Dev
SENTRY_DSN=https://[email protected]/project

Production

VITE_API_BASE_URL=https://api.djust.com
APPLICATION_ENV=production
CLIENT_NAME=MonApp-Prod
SENTRY_DSN=https://[email protected]/project

Résolution des Problèmes

Erreurs Communes

Erreur	Cause	Solution
`SDK not initialized`	Configuration manquante	Vérifier les variables d'environnement
`Invalid API key`	Clé API incorrecte	Vérifier `VITE_DJ_API_KEY`
`Unauthorized`	Token invalide	Renouveler le token d'authentification
`Store not found`	ID magasin incorrect	Vérifier `STORE_ID` et `STORE_VIEW_ID`

Debugging

// Activer les logs détaillés
console.log("Configuration SDK:", {
  baseUrl: config.baseUrl,
  clientId: config.clientId,
  storeId: config.storeId,
  locale: config.locale,
});

Cette documentation couvre tous les aspects de l'initialisation et de la configuration du SDK Djust pour une intégration réussie dans votre application Nuxt 3.