@djust-b2b/djust-front-sdk 3.0.0-beta.2 → 3.0.0-beta.20

package/dist/client/performance.d.ts

@@ -0,0 +1,203 @@
+/**
+ * DJUST SDK Performance Utilities
+ * Production-grade performance optimizations for the SDK.
+ *
+ * Features:
+ * - Request deduplication (prevents duplicate concurrent requests)
+ * - Response caching with TTL
+ * - Connection keep-alive management
+ * - Request batching
+ * - Compression support
+ *
+ * @author DJUST Engineering Team
+ * @since 2.17.0
+ */
+/**
+ * Request deduplicator - prevents duplicate concurrent requests to the same endpoint.
+ * If a request is already in-flight, returns the same promise instead of making a new request.
+ */
+export declare class RequestDeduplicator {
+    private pendingRequests;
+    private readonly maxAge;
+    constructor(maxAgeMs?: number);
+    /**
+     * Creates a unique key for the request
+     */
+    createKey(method: string, url: string, body?: string): string;
+    /**
+     * Executes a request with deduplication
+     */
+    execute<T>(key: string, requestFn: () => Promise<T>): Promise<T>;
+    /**
+     * Clears all pending requests
+     */
+    clear(): void;
+    /**
+     * Gets the number of pending requests
+     */
+    get size(): number;
+}
+interface CacheOptions {
+    /** Maximum number of entries. Default: 100 */
+    maxSize?: number;
+    /** Default TTL in milliseconds. Default: 60000 (1 minute) */
+    defaultTTL?: number;
+    /** Enable stale-while-revalidate. Default: true */
+    staleWhileRevalidate?: boolean;
+}
+/**
+ * LRU Response Cache with TTL support.
+ * Supports ETag-based validation and stale-while-revalidate pattern.
+ */
+export declare class ResponseCache {
+    private cache;
+    private readonly maxSize;
+    private readonly defaultTTL;
+    private readonly staleWhileRevalidate;
+    private hits;
+    private misses;
+    constructor(options?: CacheOptions);
+    /**
+     * Gets a cached response
+     */
+    get<T>(key: string): {
+        data: T;
+        stale: boolean;
+    } | null;
+    /**
+     * Sets a cached response
+     */
+    set<T>(key: string, data: T, etag?: string, headers?: Record<string, string>): void;
+    /**
+     * Gets ETag for a cached entry
+     */
+    getETag(key: string): string | undefined;
+    /**
+     * Invalidates a cache entry
+     */
+    invalidate(key: string): boolean;
+    /**
+     * Invalidates entries matching a pattern
+     */
+    invalidatePattern(pattern: RegExp): number;
+    /**
+     * Clears all cached entries
+     */
+    clear(): void;
+    /**
+     * Gets cache statistics
+     */
+    getStats(): {
+        size: number;
+        hits: number;
+        misses: number;
+        hitRate: number;
+    };
+}
+interface BatchConfig<TParams, TResult> {
+    /** Maximum batch size. Default: 20 */
+    maxSize?: number;
+    /** Maximum wait time in ms. Default: 10 */
+    maxWaitMs?: number;
+    /** Function to execute the batch */
+    executeBatch: (params: TParams[]) => Promise<TResult[]>;
+}
+/**
+ * Request batcher for combining multiple requests into a single batch request.
+ * Useful for endpoints that support bulk operations.
+ */
+export declare class RequestBatcher<TParams, TResult> {
+    private queue;
+    private timer;
+    private readonly maxSize;
+    private readonly maxWaitMs;
+    private readonly executeBatch;
+    constructor(config: BatchConfig<TParams, TResult>);
+    /**
+     * Adds a request to the batch queue
+     */
+    add(params: TParams): Promise<TResult>;
+    /**
+     * Flushes the current batch
+     */
+    private flush;
+    /**
+     * Gets the current queue size
+     */
+    get queueSize(): number;
+}
+interface RequestMetrics {
+    url: string;
+    method: string;
+    durationMs: number;
+    status: number;
+    size: number;
+    cached: boolean;
+    timestamp: number;
+}
+interface PerformanceReport {
+    totalRequests: number;
+    averageDurationMs: number;
+    p50DurationMs: number;
+    p95DurationMs: number;
+    p99DurationMs: number;
+    cacheHitRate: number;
+    errorRate: number;
+    requestsPerSecond: number;
+    slowestEndpoints: Array<{
+        endpoint: string;
+        avgDurationMs: number;
+    }>;
+}
+/**
+ * Performance monitor for tracking SDK metrics.
+ */
+export declare class PerformanceMonitor {
+    private metrics;
+    private readonly maxMetrics;
+    private readonly windowMs;
+    private errors;
+    private cacheHits;
+    constructor(maxMetrics?: number, windowMs?: number);
+    /**
+     * Records a request metric
+     */
+    record(metric: Omit<RequestMetrics, "timestamp">): void;
+    /**
+     * Gets performance report
+     */
+    getReport(): PerformanceReport;
+    /**
+     * Clears all metrics
+     */
+    clear(): void;
+}
+interface PoolConfig {
+    /** Maximum connections per host. Default: 6 */
+    maxConnectionsPerHost?: number;
+    /** Connection timeout in ms. Default: 10000 */
+    connectionTimeout?: number;
+    /** Keep-alive timeout in ms. Default: 30000 */
+    keepAliveTimeout?: number;
+}
+/**
+ * Creates fetch options optimized for connection pooling (Node.js)
+ */
+export declare function createPooledFetchOptions(config?: PoolConfig): RequestInit;
+/**
+ * Checks if response is compressed
+ */
+export declare function isCompressed(headers: Headers): boolean;
+/**
+ * Gets compression ratio from response headers
+ */
+export declare function getCompressionRatio(headers: Headers): number | null;
+export declare function getDeduplicator(): RequestDeduplicator;
+export declare function getCache(options?: CacheOptions): ResponseCache;
+export declare function getMonitor(): PerformanceMonitor;
+/**
+ * Resets all performance singletons (useful for testing)
+ */
+export declare function resetPerformanceUtils(): void;
+export {};
+//# sourceMappingURL=performance.d.ts.map

package/dist/client/performance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"performance.d.ts","sourceRoot":"","sources":["../../src/client/performance.ts"],"names":[],"mappings":"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"}

package/dist/client/transport.d.ts

@@ -0,0 +1,372 @@
+/**
+ * DJUST SDK Transport Layer
+ * Production-grade HTTP transport with timeout, retry, caching, and performance optimizations.
+ *
+ * Features:
+ * - Request deduplication (prevents duplicate concurrent requests)
+ * - Response caching with TTL and ETag support
+ * - Performance monitoring and metrics
+ * - Retry with exponential backoff
+ * - Request timeout
+ * - Connection keep-alive
+ * - Compression support
+ *
+ * @since 2.17.0
+ */
+import { SDKError } from "../errors/base";
+export interface TransportConfig {
+    baseUrl: string;
+    clientId: string;
+    apiKey: string;
+    /** Request timeout in milliseconds. Default: 30000 (30s) */
+    timeout?: number;
+    /** Enable strict error mode (throws SDKError instead of legacy Error). Default: false */
+    strictErrors?: boolean;
+    /** Retry configuration. Default: disabled */
+    retry?: RetryConfig;
+    /** Observability hooks. Default: no-op */
+    hooks?: TransportHooks;
+    /** Authentication lifecycle hooks for session management */
+    authHooks?: AuthHooks;
+    /** Debug mode - logs requests. Default: false */
+    debug?: boolean;
+    /** Performance configuration */
+    performance?: PerformanceConfig;
+}
+export interface PerformanceConfig {
+    /** Enable request deduplication for GET requests. Default: true */
+    deduplication?: boolean;
+    /** Deduplication window in ms. Default: 100 */
+    deduplicationWindowMs?: number;
+    /** Enable response caching for GET requests. Default: false */
+    cache?: boolean;
+    /** Cache max size. Default: 100 */
+    cacheMaxSize?: number;
+    /** Cache TTL in ms. Default: 60000 (1 minute) */
+    cacheTTL?: number;
+    /** Enable stale-while-revalidate. Default: true */
+    staleWhileRevalidate?: boolean;
+    /** Enable performance monitoring. Default: false */
+    monitoring?: boolean;
+    /** Enable compression (Accept-Encoding header). Default: true */
+    compression?: boolean;
+    /** Enable connection keep-alive. Default: true */
+    keepAlive?: boolean;
+}
+export interface RetryConfig {
+    enabled: boolean;
+    maxAttempts?: number;
+    initialDelayMs?: number;
+    maxDelayMs?: number;
+    jitter?: number;
+    retryableStatuses?: number[];
+}
+export interface TransportHooks {
+    onRequestStart?: (context: RequestHookContext) => void | Promise<void>;
+    onRequestEnd?: (context: ResponseHookContext) => void | Promise<void>;
+    onError?: (context: ErrorHookContext) => void | Promise<void>;
+    onRetry?: (context: RetryHookContext) => void | Promise<void>;
+    /** Called when response is served from cache */
+    onCacheHit?: (context: CacheHitContext) => void | Promise<void>;
+}
+/**
+ * Authentication lifecycle hooks for session management.
+ *
+ * These hooks allow consumers to react to authentication events
+ * without coupling storage logic to the SDK.
+ *
+ * @example
+ * ```typescript
+ * const client = createDjustClient({
+ *   // ...
+ *   authHooks: {
+ *     onLogin: (response) => {
+ *       // Store tokens in cookies/localStorage
+ *       setCookie('access_token', response.token.accessToken);
+ *     },
+ *     onTokenRefresh: (response) => {
+ *       // Update stored tokens
+ *       setCookie('access_token', response.token.accessToken);
+ *     },
+ *     onLogout: () => {
+ *       // Clear stored tokens
+ *       deleteCookie('access_token');
+ *     },
+ *     onAuthFailure: (error) => {
+ *       // Redirect to login
+ *       router.push('/login?expired=true');
+ *     },
+ *   },
+ * });
+ * ```
+ */
+export interface AuthHooks {
+    /**
+     * Called after successful login.
+     * Use this to store tokens and user data.
+     */
+    onLogin?: (context: LoginHookContext) => void | Promise<void>;
+    /**
+     * Called after successful token refresh.
+     * Use this to update stored tokens.
+     */
+    onTokenRefresh?: (context: TokenRefreshHookContext) => void | Promise<void>;
+    /**
+     * Called after logout (successful or not).
+     * Use this to clear stored tokens and redirect.
+     */
+    onLogout?: (context: LogoutHookContext) => void | Promise<void>;
+    /**
+     * Called when authentication fails (401, invalid token, refresh failure).
+     * Use this to handle session expiration.
+     */
+    onAuthFailure?: (context: AuthFailureHookContext) => void | Promise<void>;
+    /**
+     * Called before any authenticated request.
+     * Use this to implement custom token refresh logic.
+     * Return a new access token or undefined to use the current one.
+     */
+    onBeforeAuthenticatedRequest?: (context: BeforeAuthRequestContext) => string | undefined | Promise<string | undefined>;
+}
+export interface LoginHookContext {
+    /** The login response from the API */
+    response: {
+        token: {
+            accessToken: string;
+            refreshToken: string;
+            expiresAt: number;
+        };
+        user?: {
+            id: string;
+            email: string;
+            [key: string]: unknown;
+        };
+    };
+    /** Request ID for tracing */
+    requestId: string;
+    /** Request duration in ms */
+    durationMs: number;
+}
+export interface TokenRefreshHookContext {
+    /** The refresh response from the API */
+    response: {
+        token: {
+            accessToken: string;
+            refreshToken: string;
+            expiresAt: number;
+        };
+    };
+    /** Whether this was an automatic refresh (vs manual) */
+    automatic: boolean;
+    /** Request ID for tracing */
+    requestId: string;
+}
+export interface LogoutHookContext {
+    /** Whether logout was successful */
+    success: boolean;
+    /** Error if logout failed */
+    error?: Error;
+    /** Request ID for tracing */
+    requestId: string;
+}
+export interface AuthFailureHookContext {
+    /** The error that caused the failure */
+    error: Error | SDKError;
+    /** HTTP status code if available */
+    httpStatus?: number;
+    /** The endpoint that failed */
+    endpoint: string;
+    /** Whether the SDK will attempt a token refresh */
+    willAttemptRefresh: boolean;
+    /** Request ID for tracing */
+    requestId: string;
+}
+export interface BeforeAuthRequestContext {
+    /** Current access token (may be expired) */
+    currentToken?: string;
+    /** The endpoint being called */
+    endpoint: string;
+    /** Request ID for tracing */
+    requestId: string;
+}
+export interface RequestHookContext {
+    requestId: string;
+    method: string;
+    url: string;
+    headers: Record<string, string>;
+    body?: string;
+    attempt: number;
+    startTime: number;
+}
+export interface ResponseHookContext extends RequestHookContext {
+    status: number;
+    durationMs: number;
+    responseHeaders: Headers;
+    cached?: boolean;
+    deduped?: boolean;
+}
+export interface ErrorHookContext extends RequestHookContext {
+    error: Error | SDKError;
+    durationMs: number;
+    willRetry: boolean;
+}
+export interface RetryHookContext {
+    requestId: string;
+    attempt: number;
+    maxAttempts: number;
+    delayMs: number;
+    error: Error | SDKError;
+    reason: string;
+}
+export interface CacheHitContext {
+    requestId: string;
+    url: string;
+    cacheKey: string;
+    stale: boolean;
+    age: number;
+}
+export interface RequestContext {
+    accessToken?: string;
+    customerAccountId?: string;
+    storeId?: string;
+    storeViewId?: string;
+    locale?: string;
+    headers?: Record<string, string>;
+    requestId?: string;
+    service?: string;
+    /** SDK method name (e.g., "updateCommercialOrderLines") */
+    sdkMethod?: string;
+    /** Skip cache for this request */
+    skipCache?: boolean;
+    /** Skip deduplication for this request */
+    skipDedup?: boolean;
+    /** Custom cache TTL for this request */
+    cacheTTL?: number;
+}
+export interface TransportRequest {
+    method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+    path: string;
+    params?: Record<string, unknown>;
+    body?: unknown;
+    timeout?: number;
+    signal?: AbortSignal;
+    /** Cache key override */
+    cacheKey?: string;
+}
+export interface TransportResponse<T = unknown> {
+    data: T;
+    headers: Headers;
+    status: number;
+    durationMs: number;
+    requestId: string;
+    /** Whether response was served from cache */
+    cached?: boolean;
+    /** Whether request was deduplicated */
+    deduped?: boolean;
+}
+interface PerformanceMetrics {
+    requestCount: number;
+    cacheHits: number;
+    cacheMisses: number;
+    dedupedRequests: number;
+    totalDurationMs: number;
+    errors: number;
+}
+/**
+ * Production-grade HTTP transport for DJUST SDK.
+ * Includes built-in performance optimizations and auth lifecycle hooks.
+ */
+export declare class Transport {
+    private readonly config;
+    private readonly retryConfig;
+    private readonly perfConfig;
+    private readonly hooks;
+    private readonly authHooks;
+    private readonly cache;
+    private readonly pendingRequests;
+    private readonly metrics;
+    constructor(config: TransportConfig);
+    /**
+     * Triggers the onLogin hook after successful login.
+     * Called by AuthService.login()
+     */
+    triggerLoginHook(context: LoginHookContext): Promise<void>;
+    /**
+     * Triggers the onTokenRefresh hook after successful token refresh.
+     * Called by AuthService.refreshToken()
+     */
+    triggerTokenRefreshHook(context: TokenRefreshHookContext): Promise<void>;
+    /**
+     * Triggers the onLogout hook after logout attempt.
+     * Called by AuthService.logout()
+     */
+    triggerLogoutHook(context: LogoutHookContext): Promise<void>;
+    /**
+     * Triggers the onAuthFailure hook when authentication fails.
+     * Called on 401 errors or refresh token failures.
+     */
+    triggerAuthFailureHook(context: AuthFailureHookContext): Promise<void>;
+    /**
+     * Calls the onBeforeAuthenticatedRequest hook to potentially refresh tokens.
+     * Returns a new token if provided by the hook.
+     */
+    callBeforeAuthRequestHook(context: BeforeAuthRequestContext): Promise<string | undefined>;
+    /**
+     * Checks if auth hooks are configured.
+     */
+    hasAuthHooks(): boolean;
+    /**
+     * Executes an HTTP request with full error handling, caching, and retry support.
+     */
+    request<T = unknown>(request: TransportRequest, context?: RequestContext): Promise<TransportResponse<T>>;
+    /**
+     * Gets performance metrics
+     */
+    getMetrics(): PerformanceMetrics & {
+        cacheHitRate: number;
+        avgDurationMs: number;
+        cacheSize: number;
+        pendingRequests: number;
+    };
+    /**
+     * Clears the response cache
+     */
+    clearCache(): void;
+    /**
+     * Invalidates cache entries matching a pattern
+     */
+    invalidateCache(pattern: string | RegExp): number;
+    /**
+     * Resets performance metrics
+     */
+    resetMetrics(): void;
+    private executeWithRetry;
+    private executeRequest;
+    private shouldUseCache;
+    private getFromCache;
+    private setCache;
+    private buildCacheKey;
+    private parseCacheMaxAge;
+    private revalidateInBackground;
+    private shouldDedupe;
+    private shouldRetry;
+    private calculateRetryDelay;
+    private getRetryReason;
+    private buildUrl;
+    /**
+     * Serializes params so that arrays become repeated keys: &brand=1664&brand=1664+BLANC
+     * (API search and customer-accounts/orders expect this format, not comma or bracket).
+     */
+    private stringifyParamsRepeat;
+    private buildHeaders;
+    private buildHeadersObject;
+    private serializeBody;
+    private generateRequestId;
+    private sleep;
+}
+/**
+ * Creates a new Transport instance with performance optimizations.
+ */
+export declare function createTransport(config: TransportConfig): Transport;
+export {};
+//# sourceMappingURL=transport.d.ts.map

package/dist/client/transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../../src/client/transport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAe1C,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IAEf,4DAA4D;IAC5D,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,yFAAyF;IACzF,YAAY,CAAC,EAAE,OAAO,CAAC;IAEvB,6CAA6C;IAC7C,KAAK,CAAC,EAAE,WAAW,CAAC;IAEpB,0CAA0C;IAC1C,KAAK,CAAC,EAAE,cAAc,CAAC;IAEvB,4DAA4D;IAC5D,SAAS,CAAC,EAAE,SAAS,CAAC;IAEtB,iDAAiD;IACjD,KAAK,CAAC,EAAE,OAAO,CAAC;IAEhB,gCAAgC;IAChC,WAAW,CAAC,EAAE,iBAAiB,CAAC;CACjC;AAED,MAAM,WAAW,iBAAiB;IAChC,mEAAmE;IACnE,aAAa,CAAC,EAAE,OAAO,CAAC;IAExB,+CAA+C;IAC/C,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAE/B,+DAA+D;IAC/D,KAAK,CAAC,EAAE,OAAO,CAAC;IAEhB,mCAAmC;IACnC,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB,iDAAiD;IACjD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB,mDAAmD;IACnD,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAE/B,oDAAoD;IACpD,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB,iEAAiE;IACjE,WAAW,CAAC,EAAE,OAAO,CAAC;IAEtB,kDAAkD;IAClD,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;CAC9B;AAED,MAAM,WAAW,cAAc;IAC7B,cAAc,CAAC,EAAE,CAAC,OAAO,EAAE,kBAAkB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACvE,YAAY,CAAC,EAAE,CAAC,OAAO,EAAE,mBAAmB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtE,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,gBAAgB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9D,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,gBAAgB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9D,gDAAgD;IAChD,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE,eAAe,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACjE;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,WAAW,SAAS;IACxB;;;OAGG;IACH,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,gBAAgB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE9D;;;OAGG;IACH,cAAc,CAAC,EAAE,CAAC,OAAO,EAAE,uBAAuB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE5E;;;OAGG;IACH,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,iBAAiB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEhE;;;OAGG;IACH,aAAa,CAAC,EAAE,CAAC,OAAO,EAAE,sBAAsB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE1E;;;;OAIG;IACH,4BAA4B,CAAC,EAAE,CAC7B,OAAO,EAAE,wBAAwB,KAC9B,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;CACvD;AAED,MAAM,WAAW,gBAAgB;IAC/B,sCAAsC;IACtC,QAAQ,EAAE;QACR,KAAK,EAAE;YACL,WAAW,EAAE,MAAM,CAAC;YACpB,YAAY,EAAE,MAAM,CAAC;YACrB,SAAS,EAAE,MAAM,CAAC;SACnB,CAAC;QACF,IAAI,CAAC,EAAE;YACL,EAAE,EAAE,MAAM,CAAC;YACX,KAAK,EAAE,MAAM,CAAC;YACd,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;SACxB,CAAC;KACH,CAAC;IACF,6BAA6B;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,6BAA6B;IAC7B,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,uBAAuB;IACtC,wCAAwC;IACxC,QAAQ,EAAE;QACR,KAAK,EAAE;YACL,WAAW,EAAE,MAAM,CAAC;YACpB,YAAY,EAAE,MAAM,CAAC;YACrB,SAAS,EAAE,MAAM,CAAC;SACnB,CAAC;KACH,CAAC;IACF,wDAAwD;IACxD,SAAS,EAAE,OAAO,CAAC;IACnB,6BAA6B;IAC7B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,iBAAiB;IAChC,oCAAoC;IACpC,OAAO,EAAE,OAAO,CAAC;IACjB,6BAA6B;IAC7B,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,6BAA6B;IAC7B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,sBAAsB;IACrC,wCAAwC;IACxC,KAAK,EAAE,KAAK,GAAG,QAAQ,CAAC;IACxB,oCAAoC;IACpC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,+BAA+B;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,mDAAmD;IACnD,kBAAkB,EAAE,OAAO,CAAC;IAC5B,6BAA6B;IAC7B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,wBAAwB;IACvC,4CAA4C;IAC5C,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gCAAgC;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,6BAA6B;IAC7B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,mBAAoB,SAAQ,kBAAkB;IAC7D,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,OAAO,CAAC;IACzB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,gBAAiB,SAAQ,kBAAkB;IAC1D,KAAK,EAAE,KAAK,GAAG,QAAQ,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,KAAK,GAAG,QAAQ,CAAC;IACxB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,cAAc;IAC7B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,2DAA2D;IAC3D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kCAAkC;IAClC,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,0CAA0C;IAC1C,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,wCAAwC;IACxC,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,CAAC;IACpD,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,yBAAyB;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,iBAAiB,CAAC,CAAC,GAAG,OAAO;IAC5C,IAAI,EAAE,CAAC,CAAC;IACR,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,6CAA6C;IAC7C,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,uCAAuC;IACvC,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAkBD,UAAU,kBAAkB;IAC1B,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;IACxB,eAAe,EAAE,MAAM,CAAC;IACxB,MAAM,EAAE,MAAM,CAAC;CAChB;AAiCD;;;GAGG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkB;IACzC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAwB;IACpD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA8B;IACzD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAiB;IACvC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;IAGtC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA0C;IAChE,OAAO,CAAC,QAAQ,CAAC,eAAe,CAA8C;IAC9E,OAAO,CAAC,QAAQ,CAAC,OAAO,CAOtB;gBAEU,MAAM,EAAE,eAAe;IAenC;;;OAGG;IACG,gBAAgB,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IAYhE;;;OAGG;IACG,uBAAuB,CAC3B,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,IAAI,CAAC;IAYhB;;;OAGG;IACG,iBAAiB,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;IAYlE;;;OAGG;IACG,sBAAsB,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC;IAY5E;;;OAGG;IACG,yBAAyB,CAC7B,OAAO,EAAE,wBAAwB,GAChC,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;IAgB9B;;OAEG;IACH,YAAY,IAAI,OAAO;IAQvB;;OAEG;IACG,OAAO,CAAC,CAAC,GAAG,OAAO,EACvB,OAAO,EAAE,gBAAgB,EACzB,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC;IAyHhC;;OAEG;IACH,UAAU,IAAI,kBAAkB,GAAG;QACjC,YAAY,EAAE,MAAM,CAAC;QACrB,aAAa,EAAE,MAAM,CAAC;QACtB,SAAS,EAAE,MAAM,CAAC;QAClB,eAAe,EAAE,MAAM,CAAC;KACzB;IAcD;;OAEG;IACH,UAAU,IAAI,IAAI;IAIlB;;OAEG;IACH,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM;IAcjD;;OAEG;IACH,YAAY,IAAI,IAAI;YAaN,gBAAgB;YAgFhB,cAAc;IAuJ5B,OAAO,CAAC,cAAc;IAStB,OAAO,CAAC,YAAY;IAIpB,OAAO,CAAC,QAAQ;IAyBhB,OAAO,CAAC,aAAa;IAerB,OAAO,CAAC,gBAAgB;IAMxB,OAAO,CAAC,sBAAsB;IA0B9B,OAAO,CAAC,YAAY;IAepB,OAAO,CAAC,WAAW;IAmBnB,OAAO,CAAC,mBAAmB;IAiB3B,OAAO,CAAC,cAAc;IAYtB,OAAO,CAAC,QAAQ;IAyBhB;;;OAGG;IACH,OAAO,CAAC,qBAAqB;IAoB7B,OAAO,CAAC,YAAY;IA+CpB,OAAO,CAAC,kBAAkB;IAmB1B,OAAO,CAAC,aAAa;IAMrB,OAAO,CAAC,iBAAiB;IASzB,OAAO,CAAC,KAAK;CAGd;AAMD;;GAEG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,eAAe,GAAG,SAAS,CAElE"}

package/dist/errors/base.d.ts

@@ -0,0 +1,101 @@
+/**
+ * DJUST SDK Base Error
+ * Foundation class for all SDK errors.
+ *
+ * @module errors/base
+ * @since 2.17.0
+ */
+import type { SDKErrorCodeType } from "./codes";
+import type { SDKErrorOptions, RequestMetadata, SerializedError, ClientSafeError } from "./types";
+/**
+ * Base class for all DJUST SDK errors.
+ *
+ * Provides structured error information suitable for:
+ * - Programmatic error handling (via `code`)
+ * - Logging and observability (via `toJSON()`)
+ * - Client responses (via `toClientSafe()`)
+ * - Retry logic (via `retriable` and `retryAfterMs`)
+ *
+ * @example
+ * ```typescript
+ * import { SDKError, SDKErrorCode } from '@djust-b2b/djust-front-sdk';
+ *
+ * try {
+ *   await sdk.getCart({ cartId: '123', currency: 'EUR' });
+ * } catch (error) {
+ *   if (error instanceof SDKError) {
+ *     // Structured error handling
+ *     console.log('Code:', error.code);
+ *     console.log('Status:', error.httpStatus);
+ *     console.log('Retriable:', error.retriable);
+ *
+ *     // Logging (safe)
+ *     logger.error('SDK error', error.toJSON());
+ *
+ *     // Client response (no sensitive data)
+ *     res.status(error.httpStatus).json(error.toClientSafe());
+ *   }
+ * }
+ * ```
+ */
+export declare class SDKError extends Error {
+    /** Stable error code for programmatic handling */
+    readonly code: SDKErrorCodeType;
+    /** HTTP status code (0 for non-HTTP errors) */
+    readonly httpStatus: number;
+    /** Additional structured details */
+    readonly details: Record<string, unknown>;
+    /** Original error that caused this error */
+    readonly cause?: Error;
+    /** Whether the operation can be retried */
+    readonly retriable: boolean;
+    /** Suggested delay before retry in milliseconds */
+    readonly retryAfterMs?: number;
+    /** Request context metadata */
+    readonly metadata: RequestMetadata;
+    /** ISO timestamp when error was created */
+    readonly timestamp: string;
+    constructor(options: SDKErrorOptions);
+    /**
+     * Returns a JSON-serializable representation for logging.
+     *
+     * Safe for logging - excludes stack trace and cause details
+     * that might contain sensitive information.
+     *
+     * @example
+     * ```typescript
+     * logger.error('API call failed', error.toJSON());
+     * ```
+     */
+    toJSON(): SerializedError;
+    /**
+     * Returns a client-safe representation.
+     *
+     * Excludes internal details, metadata, and any potentially
+     * sensitive information. Safe to return in HTTP responses.
+     *
+     * @example
+     * ```typescript
+     * // In Nuxt server handler
+     * catch (error) {
+     *   if (error instanceof SDKError) {
+     *     throw createError({
+     *       statusCode: error.httpStatus,
+     *       data: error.toClientSafe(),
+     *     });
+     *   }
+     * }
+     * ```
+     */
+    toClientSafe(): ClientSafeError;
+    /**
+     * Creates a copy of this error with additional metadata.
+     * Useful for enriching errors as they bubble up.
+     */
+    withMetadata(metadata: Partial<RequestMetadata>): SDKError;
+    /**
+     * Creates a copy of this error with additional details.
+     */
+    withDetails(details: Record<string, unknown>): SDKError;
+}
+//# sourceMappingURL=base.d.ts.map