DJUST Front SDK

Universal TypeScript SDK for DJUST B2B API
SSR-safe, type-safe, production-ready.

DJUST Front SDK is a comprehensive JavaScript/TypeScript development kit designed to simplify and optimize API calls to the DJUST backend. It offers a secure, high-performance, and ready-to-use solution for integration partners, facilitating the implementation of robust B2B e-commerce solutions.

✨ Features

🔒 Security First

• Secure token management with HTTP-only cookies support
• SSR-safe architecture prevents state leakage
• Built-in authentication lifecycle hooks
• Comprehensive error handling with typed exceptions

⚡ Performance Optimized

• Request deduplication - Automatic duplicate request prevention
• Response caching - Configurable TTL with stale-while-revalidate
• Request batching - Automatic batching of parallel requests
• Performance monitoring - Built-in metrics and monitoring

🎯 Type-Safe

• Full TypeScript support with strict typing
• Auto-completion in IDEs
• Request/Response interfaces for all operations
• Type guards and runtime validation

🧩 Universal Compatibility

• Works in Node.js, Browser, and SSR environments
• Compatible with Vue.js, React, Nuxt, Next.js, Angular
• Framework-agnostic design
• Tree-shakeable modules

🔧 Developer Experience

• Modular service architecture
• Comprehensive documentation
• Extensive examples and guides
• Production-ready error handling

📦 Installation

# Stable v3 (npm tag: latest)
npm install @djust-b2b/djust-front-sdk@latest

# Maintenance v2 (npm tag: v2) — legacy portails
npm install @djust-b2b/djust-front-sdk@v2

| npm tag | Version | Use when | |---------|---------|----------| | latest | 3.0.0+ | New projects, SSR with createDjustClient (published from preprod) | | v2 | 2.19.1 | Legacy portails not yet migrated | | beta | 3.0.0-beta.* | RC validation (beta branch) |

Legacy imports: paths like @djust-b2b/djust-front-sdk/lib/interfaces/models/product remain valid on v3.

# yarn / pnpm
yarn add @djust-b2b/djust-front-sdk
pnpm add @djust-b2b/djust-front-sdk

🚀 Quick Start

Basic Usage

import { createDjustClient } from '@djust-b2b/djust-front-sdk';

// Create client instance
const client = createDjustClient({
  baseUrl: 'https://api.djust.io',
  clientId: 'your-client-id',
  apiKey: 'your-api-key',
  locale: 'fr-FR',
  storeId: 'store-123',
  storeViewId: 'view-456',
});

// Create scoped client with authentication
const sdk = client.withContext({
  accessToken: 'your-access-token',
  customerAccountId: 'account-123',
});

// Use the SDK
const cart = await sdk.getCart({
  cartId: 'cart-123',
  currency: 'EUR',
});

const products = await sdk.getProductsList({
  locale: 'fr-FR',
  pageable: { page: 0, size: 20 },
});

SSR Usage (Nuxt/Next.js)

// server/api/cart.get.ts (Nuxt)
import { useDjustSDK } from '~/server/utils/djust-sdk';

export default defineEventHandler(async (event) => {
  const sdk = useDjustSDK(event); // Automatically reads cookies
  
  const cart = await sdk.getCart({
    cartId: 'cart-123',
    currency: 'EUR',
  });
  
  return cart;
});

Client-Side Usage

// app/composables/useCart.ts (Nuxt)
import { createDjustClient } from '@djust-b2b/djust-front-sdk';

export const useCart = () => {
  const { $config } = useNuxtApp();
  const { token } = useAuth(); // Your auth composable
  
  const client = createDjustClient({
    baseUrl: $config.public.apiBaseUrl,
    clientId: $config.public.apiClientId,
    apiKey: $config.public.apiKey,
  });
  
  const sdk = client.withContext({
    accessToken: token.value,
  });
  
  return {
    getCart: (cartId: string) => sdk.getCart({ cartId, currency: 'EUR' }),
    updateCart: (params: UpdateCartParams) => sdk.updateCart(params),
  };
};

📚 Documentation

For Users

• Getting Started — setup guide (Mintlify site in docs/)
• API Reference — typed client methods per service
• Error Handling — SDKError hierarchy and retries
• Versioning — npm tags and release policy
• Guides — SSR, sessions, performance, MCP, and more

Run locally: cd docs && npm install && npx mint dev (Node 20–22). Deployed via the Mintlify GitLab app.

For Developers

• CLAUDE.md — repo layout, golden rule, service anatomy, conventions
• ARCHITECTURE_AUDIT.md — staff engineer architecture audit
• docs/README.md — regenerate and validate the Mintlify site

Quick Links

| Topic | Link | |-------|------| | Architecture | Overview | | Services | Services guide | | SSR | SSR usage | | Error Handling | Error handling | | API playground | OpenAPI (interactive on deployed site) |

🎯 Key Features in Detail

SSR-Safe Architecture

The SDK uses request-scoped instances to prevent state leakage in SSR environments:

// Each request gets its own scoped client
const sdk = client.withContext({
  accessToken: getCookie(event, 'token'),
  customerAccountId: getCookie(event, 'customer-account-id'),
  requestId: `ssr-${Date.now()}`,
});

Performance Optimizations

Enable performance features in client configuration:

const client = createDjustClient({
  // ... base config
  performance: {
    deduplication: true,      // Prevent duplicate requests
    cache: true,              // Enable response caching
    cacheTTL: 30000,          // 30 seconds TTL
    staleWhileRevalidate: true, // Serve stale while revalidating
    compression: true,         // Enable compression
    keepAlive: true,          // HTTP keep-alive
  },
});

Error Handling

Structured error model with typed exceptions and rich metadata:

import {
  ValidationError,
  NotFoundError,
  ForbiddenError,
  SDKError,
} from '@djust-b2b/djust-front-sdk';

try {
  const cart = await sdk.getCart({ cartId: 'invalid' });
} catch (error) {
  if (error instanceof ValidationError) {
    console.error('Invalid parameters:', error.message);
    // Access metadata for debugging
    console.log('Backend endpoint:', error.metadata.endpoint);
    console.log('SDK method:', error.metadata.sdkMethod);
    console.log('Query params:', error.metadata.queryParams);
  } else if (error instanceof NotFoundError) {
    console.error('Cart not found');
  } else if (error instanceof ForbiddenError) {
    console.error('Access denied');
  }
}

SSR/BFF Integration: Use centralized error handler for Nuxt/Next.js:

import { handleSDKError } from '~~/server/utils/handle-sdk-error';

export default defineEventHandler(async (event) => {
  try {
    const sdk = event.context.djustSDK();
    return await sdk.updateCommercialOrderLines({ ... });
  } catch (error) {
    const errorResponse = await handleSDKError(error, event);
    if (errorResponse) return errorResponse;
    throw createError({ statusCode: 500, ... });
  }
});

See Error Handling Guide for complete documentation.

Authentication Hooks

Subscribe to authentication lifecycle events:

const client = createDjustClient({
  // ... config
  authHooks: {
    onLogin: async (ctx) => {
      console.log('User logged in:', ctx.userId);
      // Update your app state
    },
    onTokenRefresh: async (ctx) => {
      console.log('Token refreshed:', ctx.requestId);
      // Update token in your store
    },
    onLogout: async () => {
      console.log('User logged out');
      // Clear app state
    },
    onAuthFailure: async (ctx) => {
      console.error('Auth failed:', ctx.endpoint);
      // Handle auth failure
    },
  },
});

🏗️ Architecture

The SDK follows a modular, service-based architecture:

┌─────────────────────────────────────┐
│      createDjustClient()            │
│      (Client Factory)               │
└──────────────┬──────────────────────┘
               │
    ┌──────────┴──────────┐
    │                     │
┌───▼──────┐      ┌───────▼────────┐
│ Transport│      │ Service Factory│
│ (HTTP)   │      │ (Registry)    │
└───┬──────┘      └───────┬────────┘
    │                     │
    └──────────┬──────────┘
               │
    ┌──────────▼──────────┐
    │   Services         │
    │  (Auth, Cart,      │
    │   Product, etc.)   │
    └────────────────────┘

Available Services

• Auth - Authentication and user management
• Cart - Shopping cart operations
• Product - Product catalog and search
• Commercial Order - Order management
• Logistic Order - Shipping and logistics
• Quote - B2B quote management
• Customer Account - Account management
• Customer User - User profile management
• Supplier - Supplier information
• Payment - Payment processing
• Navigation - Category navigation
• And more...

See Services Reference for complete list.

🔧 Configuration

Client Configuration

interface DjustClientConfig {
  baseUrl: string;              // DJUST API base URL
  clientId: string;              // Client ID (dj-client header)
  apiKey: string;               // API Key (dj-api-key header)
  timeout?: number;              // Request timeout (default: 30000)
  locale?: string;               // Default locale
  storeId?: string;             // Default store ID
  storeViewId?: string;          // Default store view ID
  strictErrors?: boolean;        // Use SDKError (default: false)
  retry?: RetryConfig;           // Retry configuration
  performance?: PerformanceConfig; // Performance options
  authHooks?: AuthHooks;         // Authentication hooks
  debug?: boolean;               // Debug mode
}

Performance Configuration

interface PerformanceConfig {
  deduplication?: boolean;      // Request deduplication
  cache?: boolean;              // Response caching
  cacheTTL?: number;            // Cache TTL in ms
  staleWhileRevalidate?: boolean; // SWR strategy
  compression?: boolean;        // Enable compression
  keepAlive?: boolean;          // HTTP keep-alive
}

Retry Configuration

interface RetryConfig {
  enabled?: boolean;            // Enable retries
  maxAttempts?: number;         // Max retry attempts
  retryableStatuses?: number[]; // Status codes to retry
}

📖 Examples

Authentication

// Login
const { token, refreshToken, user } = await sdk.login({
  username: '[email protected]',
  password: 'password',
  withUser: true,
});

// Refresh token
const newToken = await sdk.refreshToken({
  refreshToken: refreshToken,
});

// Get authenticated user
const user = await sdk.getAuthenticatedUser();

Shopping Cart

// Get cart
const cart = await sdk.getCart({
  cartId: 'cart-123',
  currency: 'EUR',
  nbFirstLines: 10,
});

// Update cart lines
await sdk.updateCartLines({
  cartId: 'cart-123',
  linesToAdd: [
    { offerPriceId: 'price-1', quantity: 5 },
  ],
  linesToUpdate: [
    { lineId: 'line-1', quantity: 10 },
  ],
});

// Convert to order
const order = await sdk.initializeOrders({
  cartId: 'cart-123',
  shippingAddressId: 'addr-123',
});

Products

// Search products
const results = await sdk.getProductsList({
  locale: 'fr-FR',
  filters: { categoryId: 'cat-123' },
  pageable: { page: 0, size: 20 },
});

// Get product details
const product = await sdk.getProduct({
  productIdentifier: 'SKU-123',
  productIdType: 'SKU',
  locale: 'fr-FR',
});

// Get product offers
const offers = await sdk.getProductPaginatedOffers({
  productVariantId: 'variant-123',
  pageable: { page: 0, size: 20 },
});

Orders

// Get orders
const orders = await sdk.getCommercialOrders({
  locale: 'fr-FR',
  pageable: { page: 0, size: 10 },
});

// Get order details
const order = await sdk.getCommercialOrder({
  commercialOrderId: 'order-123',
  locale: 'fr-FR',
});

// Create order from cart
const newOrder = await sdk.createCommercialOrder({
  channel: 'DESKTOP',
  locale: 'fr-FR',
  origin: 'CART',
  originId: 'cart-123',
});

🛡️ Security Best Practices

Token Management

// ✅ Good - Use HTTP-only cookies in SSR
// Server-side
setCookie(event, 'token', token, {
  httpOnly: true,
  secure: true,
  sameSite: 'strict',
});

// ✅ Good - Don't log tokens
// Never do this:
console.log('Token:', token); // ❌

// ✅ Good - Validate tokens
if (!isValidToken(token)) {
  throw new Error('Invalid token');
}

Input Validation

// ✅ Good - Validate before sending
async getCart(params: GetCartParams) {
  this.required(params, ['cartId', 'currency']);
  
  // Additional validation
  if (!/^[a-zA-Z0-9-]+$/.test(params.cartId)) {
    throw ValidationError.invalidParameter('cartId');
  }
  
  return this.request(...);
}

🧪 Testing

The SDK includes comprehensive test coverage:

# Run tests
npm test

# Run tests in watch mode
npm run test:ui

# Run tests with coverage
npm run coverage

📊 Performance Monitoring

Access performance metrics:

const metrics = client.getMetrics();

console.log('Total requests:', metrics.totalRequests);
console.log('Cache hits:', metrics.cacheHits);
console.log('Cache misses:', metrics.cacheMisses);
console.log('Average response time:', metrics.avgResponseTime);

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Quick Start for Contributors

1. Fork the repository
2. Create a feature branch: git checkout -b feat/your-feature
3. Make your changes following CLAUDE.md conventions
4. Write tests for your changes
5. Commit using conventional commits: npm run commit
6. Push and create a Merge Request

Development Setup

# Clone repository
git clone https://gitlab.com/djustlab/front/djust-front-sdk.git
cd djust-front-sdk

# Install dependencies
npm install

# Run tests
npm test

# Build
npm run build

# Format code
npm run format

# Lint
npm run lint

📝 Changelog

See CHANGELOG.md for a detailed list of changes.

🔄 Versioning

The SDK follows Semantic Versioning. Check versions:

# View all versions
npm view @djust-b2b/djust-front-sdk versions

# View latest version
npm view @djust-b2b/djust-front-sdk version

# Check installed version
npm list @djust-b2b/djust-front-sdk

See Versioning Guide for complete documentation on version management and npm version retrieval.

🐛 Reporting Issues

Found a bug or have a feature request? Please open an issue on GitLab Issues.

📄 License

DJUST Front SDK is distributed under the MIT License. See LICENSE for details.

🔗 Links

• Documentation: https://djust-sdk-docs-530629704769.europe-west1.run.app
• GitLab Repository: https://gitlab.com/djustlab/front/djust-front-sdk
• Issues: https://gitlab.com/djustlab/front/djust-front-sdk/issues

💬 Support

• Documentation: Check our documentation site
• Issues: Open an issue on GitLab
• Team Chat: Contact the development team

Built with ❤️ by the DJUST team

With DJUST Front SDK, simplify your backend integrations, ensure exceptional performance, and provide reliable and secure e-commerce solutions for your clients.