@djust-b2b/djust-front-sdk 2.16.1 → 3.0.0-beta.1

package/README.md

@@ -1,50 +1,605 @@
-# Introduction
+# DJUST Front SDK
 
-**DJUST Front SDK** is a JavaScript 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, thus facilitating the implementation of robust e-commerce solutions for your clients.
+> **Universal TypeScript SDK for DJUST B2B API**  
+> SSR-safe, type-safe, production-ready.
+
+[![npm version](https://img.shields.io/npm/v/@djust-b2b/djust-front-sdk)](https://www.npmjs.com/package/@djust-b2b/djust-front-sdk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.6-blue.svg)](https://www.typescriptlang.org/)
+
+**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
+
+```bash
+# npm
+npm install @djust-b2b/djust-front-sdk
+
+# yarn
+yarn add @djust-b2b/djust-front-sdk
+
+# pnpm
+pnpm add @djust-b2b/djust-front-sdk
+```
+
+---
+
+## 🚀 Quick Start
+
+### Basic Usage
+
+```typescript
+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)
+
+```typescript
+// 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
+
+```typescript
+// 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 Guide](https://djust-sdk-docs.vercel.app/docs/getting-started/introduction)** - Complete setup guide
+- **[API Reference](https://djust-sdk-docs.vercel.app/docs/api)** - Full API documentation
+- **[Guides](https://djust-sdk-docs.vercel.app/docs/guides)** - Performance, SSR, error handling
+- **[Examples](https://djust-sdk-docs.vercel.app/docs/examples)** - Code examples and patterns
+
+### For Developers
+
+All development documentation is located in [`doc/development/`](./doc/development/):
+
+- **[Guidelines Index](./doc/development/GUIDELINES_INDEX.md)** - 📖 Quick reference to all guidelines
+- **[Developer Guide](./doc/development/DEVELOPER_GUIDE.md)** - Architecture and development patterns
+- **[Development Guidelines](./doc/development/GUIDELINES.md)** - Coding standards and best practices
+- **[Code Review Guidelines](./doc/development/GUIDELINES_CODE_REVIEW.md)** - Review process and checklist
+- **[Contributing Guide](./doc/development/CONTRIBUTING.md)** - How to contribute
+- **[Service Templates](./doc/development/.templates/)** - Templates for creating services
+
+> 📁 See [doc/development/README.md](./doc/development/README.md) for documentation structure
+
+### Quick Links
+
+| Topic | Link |
+|-------|------|
+| Architecture | [Architecture Overview](./doc/development/DEVELOPER_GUIDE.md#architecture-overview) |
+| Creating Services | [Creating a New Service](./doc/development/DEVELOPER_GUIDE.md#creating-a-new-service) |
+| Code Style | [Code Style Guidelines](./doc/development/GUIDELINES.md#code-style-guidelines) |
+| TypeScript | [TypeScript Guidelines](./doc/development/GUIDELINES.md#typescript-guidelines) |
+| Error Handling | [Error Handling Guidelines](./doc/development/GUIDELINES.md#error-handling-guidelines) |
+| Testing | [Testing Guidelines](./doc/development/GUIDELINES.md#testing-guidelines) |
+| Code Review | [Review Checklist](./doc/development/GUIDELINES_CODE_REVIEW.md#review-checklist) |
+
+---
+
+## 🎯 Key Features in Detail
+
+### SSR-Safe Architecture
+
+The SDK uses request-scoped instances to prevent state leakage in SSR environments:
+
+```typescript
+// 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:
+
+```typescript
+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:
+
+```typescript
+import {
+  ValidationError,
+  NotFoundError,
+  ForbiddenError,
+} 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);
+  } else if (error instanceof NotFoundError) {
+    console.error('Cart not found');
+  } else if (error instanceof ForbiddenError) {
+    console.error('Access denied');
+  }
+}
+```
+
+### Authentication Hooks
+
+Subscribe to authentication lifecycle events:
+
+```typescript
+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](./doc/docs/guides/services.mdx) for complete list.
 
 ---
 
-## 🚀 **Why use DJUST Front SDK ?**
+## 🔧 Configuration
+
+### Client Configuration
+
+```typescript
+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
+}
+```
 
-### **🔒 Secure API Calls**  
-Ensure secure communications between your frontend applications and the DJUST backend through integrated mechanisms for managing requests and responses.
+### Performance Configuration
 
-### **⚡ Performance Optimization**  
-DJUST Front SDK is designed to:
-- Minimize response times through optimized methods.
-- Efficiently manage API calls by avoiding redundancies.
+```typescript
+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
+}
+```
 
-### **🧩 A Simplified Integration**  
-- **Easy to configure** : A clear and documented API for a quick start.  
-- **Universal** : Compatible with all JavaScript environments (Vue.js, React, Nuxt, Angular, etc.).
+### Retry Configuration
 
-### **🔧 Flexibility and Modularity**  
-Use only the methods you need for your projects. The SDK is modular, allowing you to tailor the integration according to your clients' requirements.
+```typescript
+interface RetryConfig {
+  enabled?: boolean;            // Enable retries
+  maxAttempts?: number;         // Max retry attempts
+  retryableStatuses?: number[]; // Status codes to retry
+}
+```
 
 ---
 
-## 🛡️ **Security and Compliance**  
+## 📖 Examples
+
+### Authentication
+
+```typescript
+// Login
+const { token, refreshToken, user } = await sdk.login({
+  username: 'user@example.com',
+  password: 'password',
+  withUser: true,
+});
+
+// Refresh token
+const newToken = await sdk.refreshToken({
+  refreshToken: refreshToken,
+});
+
+// Get authenticated user
+const user = await sdk.getAuthenticatedUser();
+```
+
+### Shopping Cart
+
+```typescript
+// 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
+
+```typescript
+// 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
+
+```typescript
+// Get orders
+const orders = await sdk.getCommercialOrders({
+  locale: 'fr-FR',
+  pageable: { page: 0, size: 10 },
+});
 
-The SDK incorporates best practices to ensure :  
-- A **secure management of authentication tokens**.  
-- Compliance with security standards to protect data exchanges.  
-- A **reliability** in requests through centralized error handling.
+// 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
+
+```typescript
+// ✅ 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
+
+```typescript
+// ✅ 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(...);
+}
+```
 
 ---
 
-## 📈 **Benefits for Partners**
+## 🧪 Testing
+
+The SDK includes comprehensive test coverage:
+
+```bash
+# Run tests
+npm test
 
-- **Accelerate your integrations** : Save time by using a ready-to-use SDK.  
-- **Secure your projects** : Assure your clients with robust and secure backend calls.  
-- **Maximize performance** : Provide smooth experiences with fast and optimized interactions.
+# Run tests in watch mode
+npm run test:ui
+
+# Run tests with coverage
+npm run coverage
+```
 
 ---
 
-## 📄 **Licence**
+## 📊 Performance Monitoring
+
+Access performance metrics:
 
-DJUST Front SDK is distributed under the **MIT license**, providing you with complete freedom to use it in your projects.
+```typescript
+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);
+```
 
 ---
 
-With **DJUST Front SDK**, simplify your backend integrations, ensure exceptional performance, and provide reliable and secure e-commerce solutions for your clients.
+## 🤝 Contributing
+
+We welcome contributions! Please see our [Contributing Guide](./CONTRIBUTING.md) 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 our [Guidelines](./doc/development/GUIDELINES.md)
+4. Write tests for your changes
+5. Commit using conventional commits: `npm run commit`
+6. Push and create a Merge Request
+
+### Development Setup
+
+```bash
+# 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](./CHANGELOG.md) for a detailed list of changes.
+
+---
+
+## 🐛 Reporting Issues
+
+Found a bug or have a feature request? Please open an issue on [GitLab Issues](https://gitlab.com/djustlab/front/djust-front-sdk/issues).
+
+---
+
+## 📄 License
+
+DJUST Front SDK is distributed under the **MIT License**. See [LICENSE](./LICENSE) for details.
+
+---
+
+## 🔗 Links
+
+- **Documentation**: [https://djust-sdk-docs.vercel.app](https://djust-sdk-docs.vercel.app)
+- **GitLab Repository**: [https://gitlab.com/djustlab/front/djust-front-sdk](https://gitlab.com/djustlab/front/djust-front-sdk)
+- **Issues**: [https://gitlab.com/djustlab/front/djust-front-sdk/issues](https://gitlab.com/djustlab/front/djust-front-sdk/issues)
+
+---
+
+## 💬 Support
+
+- **Documentation**: Check our [documentation site](https://djust-sdk-docs.vercel.app)
+- **Issues**: Open an issue on [GitLab](https://gitlab.com/djustlab/front/djust-front-sdk/issues)
+- **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.

package/package.json

@@ -1,21 +1,42 @@
 {
   "name": "@djust-b2b/djust-front-sdk",
-  "version": "2.16.1",
-  "description": "DJUST Front SDK is a versatile JavaScript Software Development Kit (SDK)",
-  "main": "lib/index.js",
-  "types": "lib/index.d.ts",
+  "version": "3.0.0-beta.1",
+  "description": "DJUST Front SDK - Universal TypeScript SDK for DJUST B2B API. SSR-safe, type-safe, production-ready.",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "sideEffects": false,
   "scripts": {
     "test": "vitest",
     "test:ui": "vitest --ui",
     "test:run": "vitest run",
     "coverage": "vitest run --coverage",
-    "build": "tsc",
+    "clean": "rm -rf lib",
+    "build": "npm run clean && npm run build:cjs && npm run build:esm && npm run build:types",
+    "build:cjs": "tsc --project tsconfig.json",
+    "build:esm": "tsc --project tsconfig.esm.json",
+    "build:types": "tsc --project tsconfig.json --emitDeclarationOnly --declaration --declarationMap",
+    "build:fast": "esbuild src/index.ts --bundle --platform=node --target=es2020 --outfile=lib/index.js --external:@sentry/browser --external:query-string --external:isomorphic-fetch",
+    "build:analyze": "esbuild src/index.ts --bundle --metafile=meta.json && cat meta.json | esbuild-visualizer --metadata ./meta.json --filename stats.html",
     "prepare": "npm run build",
     "format": "prettier --write src",
+    "lint": "tsc --noEmit",
     "version": "npm run format && git add -A src",
     "semantic-release": "semantic-release",
+    "semantic-release:dry-run": "semantic-release --dry-run",
+    "semantic-release:debug": "semantic-release --debug",
+    "verify-version": "node scripts/verify-version.js",
+    "preversion": "npm run verify-version",
     "commit": "cz",
-    "prepack": "npmignore --auto"
+    "prepack": "npmignore --auto",
+    "perf:test": "node --expose-gc scripts/perf-test.js"
   },
   "keywords": [],
   "author": "sami@djust.io",
@@ -29,6 +50,7 @@
     "@types/node": "^18.7.16",
     "@vitest/coverage-v8": "3.0.9",
     "@vitest/ui": "3.0.9",
+    "conventional-changelog-conventionalcommits": "^6.0.0",
     "cz-conventional-changelog": "^3.3.0",
     "dotenv": "^16.0.2",
     "esbuild": "^0.20.1",
@@ -44,11 +66,11 @@
     "typedoc": "0.27.3",
     "typedoc-plugin-markdown": "4.3.1",
     "typescript": "^5.6.3",
+    "unbuild": "^3.6.1",
     "vitest": "3.0.9"
   },
   "files": [
-    "lib/**/**.js",
-    "lib/**/**.d.ts"
+    "dist"
   ],
   "dependencies": {
     "@sentry/browser": "^9.2.0",