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

package/dist/errors/codes.d.ts

@@ -0,0 +1,111 @@
+/**
+ * DJUST SDK Error Codes
+ * Stable error codes for programmatic error handling.
+ *
+ * @module errors/codes
+ * @since 2.17.0
+ */
+/**
+ * Enumeration of all SDK error codes.
+ * Use these codes for programmatic error handling rather than parsing messages.
+ *
+ * @example
+ * ```typescript
+ * import { SDKErrorCode, isSDKError } from '@djust-b2b/djust-front-sdk';
+ *
+ * try {
+ *   await sdk.getCart({ cartId: '123', currency: 'EUR' });
+ * } catch (error) {
+ *   if (isSDKError(error) && error.code === SDKErrorCode.NOT_FOUND) {
+ *     console.log('Cart not found');
+ *   }
+ * }
+ * ```
+ */
+export declare const SDKErrorCode: {
+    /** Generic validation error */
+    readonly VALIDATION_ERROR: "VALIDATION_ERROR";
+    /** Required parameter is missing */
+    readonly MISSING_PARAMETER: "MISSING_PARAMETER";
+    /** Parameter value is invalid */
+    readonly INVALID_PARAMETER: "INVALID_PARAMETER";
+    /** Generic authentication error */
+    readonly AUTH_ERROR: "AUTH_ERROR";
+    /** Access token has expired */
+    readonly TOKEN_EXPIRED: "TOKEN_EXPIRED";
+    /** Access token is invalid or malformed */
+    readonly TOKEN_INVALID: "TOKEN_INVALID";
+    /** Access token is required but not provided */
+    readonly TOKEN_MISSING: "TOKEN_MISSING";
+    /** Username or password is incorrect */
+    readonly INVALID_CREDENTIALS: "INVALID_CREDENTIALS";
+    /** Generic authorization error */
+    readonly FORBIDDEN: "FORBIDDEN";
+    /** User lacks required permissions */
+    readonly INSUFFICIENT_PERMISSIONS: "INSUFFICIENT_PERMISSIONS";
+    /** Resource not found */
+    readonly NOT_FOUND: "NOT_FOUND";
+    /** Resource conflict (e.g., duplicate) */
+    readonly CONFLICT: "CONFLICT";
+    /** Resource no longer available */
+    readonly GONE: "GONE";
+    /** Request entity too large */
+    readonly PAYLOAD_TOO_LARGE: "PAYLOAD_TOO_LARGE";
+    /** Unsupported media type */
+    readonly UNSUPPORTED_MEDIA_TYPE: "UNSUPPORTED_MEDIA_TYPE";
+    /** Unprocessable entity (validation at API level) */
+    readonly UNPROCESSABLE_ENTITY: "UNPROCESSABLE_ENTITY";
+    /** Too many requests */
+    readonly RATE_LIMITED: "RATE_LIMITED";
+    /** Generic network error */
+    readonly NETWORK_ERROR: "NETWORK_ERROR";
+    /** Request timeout */
+    readonly TIMEOUT: "TIMEOUT";
+    /** Connection refused */
+    readonly CONNECTION_REFUSED: "CONNECTION_REFUSED";
+    /** DNS resolution failed */
+    readonly DNS_ERROR: "DNS_ERROR";
+    /** Request was aborted */
+    readonly ABORTED: "ABORTED";
+    /** SSL/TLS error */
+    readonly SSL_ERROR: "SSL_ERROR";
+    /** Generic server error */
+    readonly SERVER_ERROR: "SERVER_ERROR";
+    /** Internal server error (500) */
+    readonly INTERNAL_ERROR: "INTERNAL_ERROR";
+    /** Bad gateway (502) */
+    readonly BAD_GATEWAY: "BAD_GATEWAY";
+    /** Service unavailable (503) */
+    readonly SERVICE_UNAVAILABLE: "SERVICE_UNAVAILABLE";
+    /** Gateway timeout (504) */
+    readonly GATEWAY_TIMEOUT: "GATEWAY_TIMEOUT";
+    /** SDK not initialized */
+    readonly SDK_NOT_INITIALIZED: "SDK_NOT_INITIALIZED";
+    /** SDK configuration error */
+    readonly CONFIGURATION_ERROR: "CONFIGURATION_ERROR";
+    /** Feature not supported */
+    readonly NOT_SUPPORTED: "NOT_SUPPORTED";
+    /** Unexpected error (bug or unknown state) */
+    readonly UNEXPECTED_ERROR: "UNEXPECTED_ERROR";
+};
+/**
+ * Type representing all possible SDK error codes.
+ */
+export type SDKErrorCodeType = (typeof SDKErrorCode)[keyof typeof SDKErrorCode];
+/**
+ * Error codes that indicate retriable errors.
+ */
+export declare const RETRIABLE_ERROR_CODES: readonly SDKErrorCodeType[];
+/**
+ * HTTP status codes that are typically retriable.
+ */
+export declare const RETRIABLE_HTTP_STATUS_CODES: readonly number[];
+/**
+ * Checks if an error code represents a retriable error.
+ */
+export declare function isRetriableCode(code: SDKErrorCodeType): boolean;
+/**
+ * Checks if an HTTP status code represents a retriable error.
+ */
+export declare function isRetriableStatus(status: number): boolean;
+//# sourceMappingURL=codes.d.ts.map

package/dist/errors/codes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codes.d.ts","sourceRoot":"","sources":["../../src/errors/codes.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,YAAY;IAEvB,+BAA+B;;IAE/B,oCAAoC;;IAEpC,iCAAiC;;IAIjC,mCAAmC;;IAEnC,+BAA+B;;IAE/B,2CAA2C;;IAE3C,gDAAgD;;IAEhD,wCAAwC;;IAIxC,kCAAkC;;IAElC,sCAAsC;;IAItC,yBAAyB;;IAEzB,0CAA0C;;IAE1C,mCAAmC;;IAEnC,+BAA+B;;IAE/B,6BAA6B;;IAE7B,qDAAqD;;IAIrD,wBAAwB;;IAIxB,4BAA4B;;IAE5B,sBAAsB;;IAEtB,yBAAyB;;IAEzB,4BAA4B;;IAE5B,0BAA0B;;IAE1B,oBAAoB;;IAIpB,2BAA2B;;IAE3B,kCAAkC;;IAElC,wBAAwB;;IAExB,gCAAgC;;IAEhC,4BAA4B;;IAI5B,0BAA0B;;IAE1B,8BAA8B;;IAE9B,4BAA4B;;IAI5B,8CAA8C;;CAEtC,CAAC;AAEX;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,OAAO,YAAY,CAAC,CAAC;AAEhF;;GAEG;AACH,eAAO,MAAM,qBAAqB,EAAE,SAAS,gBAAgB,EAWnD,CAAC;AAEX;;GAEG;AACH,eAAO,MAAM,2BAA2B,EAAE,SAAS,MAAM,EAO/C,CAAC;AAEX;;GAEG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAE/D;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAEzD"}

package/dist/errors/compat.d.ts

@@ -0,0 +1,99 @@
+/**
+ * DJUST SDK Error Compatibility
+ * Helpers for backward compatibility with legacy error handling.
+ *
+ * @module errors/compat
+ * @since 2.17.0
+ */
+import { SDKError } from "./base";
+import type { SDKErrorCodeType } from "./codes";
+/**
+ * Converts an SDKError to the legacy error format.
+ *
+ * Used internally when `strictErrors` mode is disabled to maintain
+ * backward compatibility with existing error handling code.
+ *
+ * Legacy format: `new Error("[API] Error 401: Some message")`
+ *
+ * @example
+ * ```typescript
+ * // Internal SDK usage
+ * if (!config.strictErrors) {
+ *   throw toLegacyError(sdkError);
+ * }
+ * throw sdkError;
+ * ```
+ */
+export declare function toLegacyError(sdkError: SDKError): Error;
+/**
+ * Extracts the original SDKError from a legacy error if available.
+ *
+ * @example
+ * ```typescript
+ * const sdkError = fromLegacyError(error);
+ * if (sdkError) {
+ *   console.log(sdkError.code);
+ * }
+ * ```
+ */
+export declare function fromLegacyError(error: Error): SDKError | null;
+/**
+ * Checks if an error is in legacy format.
+ *
+ * Legacy format: "[API] Error XXX: ..." or "[SDK] Error: ..."
+ */
+export declare function isLegacyError(error: unknown): error is Error;
+/**
+ * Parses a legacy error message to extract status code and message.
+ *
+ * @example
+ * ```typescript
+ * const parsed = parseLegacyError(error);
+ * // { statusCode: 401, message: 'Unauthorized' }
+ * ```
+ */
+export declare function parseLegacyError(error: Error): {
+    statusCode: number | null;
+    message: string;
+    code: SDKErrorCodeType | null;
+};
+/**
+ * Wraps a function to catch SDKErrors and convert to legacy format.
+ *
+ * Used to maintain backward compatibility when calling new code
+ * from legacy code paths.
+ *
+ * @example
+ * ```typescript
+ * const legacyGetCart = withLegacyErrors(async (params) => {
+ *   return await newClient.getCart(params);
+ * });
+ * ```
+ */
+export declare function withLegacyErrors<T extends (...args: any[]) => Promise<any>>(fn: T): T;
+/**
+ * Wraps a function to catch legacy errors and convert to SDKError.
+ *
+ * Used to upgrade legacy error handling to new structured errors.
+ *
+ * @example
+ * ```typescript
+ * const modernGetCart = withStructuredErrors(async (params) => {
+ *   return await legacySDK.getCart(params);
+ * });
+ * ```
+ */
+export declare function withStructuredErrors<T extends (...args: any[]) => Promise<any>>(fn: T): T;
+/**
+ * Type guard that works with both SDKError and legacy errors.
+ *
+ * Useful during migration when code may receive either format.
+ */
+export declare function isApiError(error: unknown): boolean;
+/**
+ * Gets HTTP status code from either SDKError or legacy error.
+ *
+ * Unified accessor for backward compatibility.
+ */
+export declare function getHttpStatus(error: unknown): number | null;
+//# sourceMappingURL=compat.d.ts.map

package/dist/errors/compat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compat.d.ts","sourceRoot":"","sources":["../../src/errors/compat.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC;AAClC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAEhD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,QAAQ,GAAG,KAAK,CAyCvD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,KAAK,GAAG,QAAQ,GAAG,IAAI,CAI7D;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,KAAK,CAS5D;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,KAAK,GAAG;IAC9C,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,gBAAgB,GAAG,IAAI,CAAC;CAC/B,CAoCA;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC,GAAG,CAAC,EACzE,EAAE,EAAE,CAAC,GACJ,CAAC,CAWH;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAClC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC,GAAG,CAAC,EAC1C,EAAE,EAAE,CAAC,GAAG,CAAC,CA+BV;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAWlD;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAiB3D"}

package/dist/errors/factory.d.ts

@@ -0,0 +1,33 @@
+/**
+ * DJUST SDK Error Factory
+ * Functions for creating errors from HTTP responses and exceptions.
+ *
+ * @module errors/factory
+ * @since 2.17.0
+ */
+import { SDKError } from "./base";
+import type { ErrorFactoryOptions, RequestMetadata } from "./types";
+export declare function createErrorFromResponse(options: ErrorFactoryOptions): SDKError;
+/**
+ * Creates an SDKError from a network/fetch exception.
+ *
+ * Automatically detects error types:
+ * - AbortError → NetworkError (aborted)
+ * - Timeout errors → TimeoutError
+ * - Connection errors → NetworkError
+ * - DNS errors → NetworkError
+ * - Other → UnexpectedError
+ *
+ * @example
+ * ```typescript
+ * import { createErrorFromException } from '@djust-b2b/djust-front-sdk';
+ *
+ * try {
+ *   await fetch(url);
+ * } catch (error) {
+ *   throw createErrorFromException(error, { endpoint: url });
+ * }
+ * ```
+ */
+export declare function createErrorFromException(error: unknown, metadata?: RequestMetadata): SDKError;
+//# sourceMappingURL=factory.d.ts.map

package/dist/errors/factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../../src/errors/factory.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC;AAElC,OAAO,KAAK,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAoFpE,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,mBAAmB,GAC3B,QAAQ,CAyEV;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,OAAO,EACd,QAAQ,CAAC,EAAE,eAAe,GACzB,QAAQ,CAiCV"}

package/dist/errors/guards.d.ts

@@ -0,0 +1,142 @@
+/**
+ * DJUST SDK Error Guards
+ * Type guards and utility functions for error handling.
+ *
+ * @module errors/guards
+ * @since 2.17.0
+ */
+import { SDKError } from "./base";
+import { type SDKErrorCodeType } from "./codes";
+import { AuthError } from "./classes/auth.error";
+import { ForbiddenError } from "./classes/forbidden.error";
+import { NetworkError } from "./classes/network.error";
+import { TimeoutError } from "./classes/timeout.error";
+import { ServerError } from "./classes/server.error";
+import { ValidationError } from "./classes/validation.error";
+import { NotFoundError } from "./classes/not-found.error";
+import { RateLimitError } from "./classes/rate-limit.error";
+import { UnexpectedError } from "./classes/unexpected.error";
+/**
+ * Checks if an error is an SDKError.
+ *
+ * @example
+ * ```typescript
+ * if (isSDKError(error)) {
+ *   console.log(error.code); // TypeScript knows it's SDKError
+ * }
+ * ```
+ */
+export declare function isSDKError(error: unknown): error is SDKError;
+/**
+ * Checks if an error is an AuthError (401).
+ */
+export declare function isAuthError(error: unknown): error is AuthError;
+/**
+ * Checks if an error is a ForbiddenError (403).
+ */
+export declare function isForbiddenError(error: unknown): error is ForbiddenError;
+/**
+ * Checks if an error is a NetworkError.
+ */
+export declare function isNetworkError(error: unknown): error is NetworkError;
+/**
+ * Checks if an error is a TimeoutError.
+ */
+export declare function isTimeoutError(error: unknown): error is TimeoutError;
+/**
+ * Checks if an error is a ServerError (5xx).
+ */
+export declare function isServerError(error: unknown): error is ServerError;
+/**
+ * Checks if an error is a ValidationError.
+ */
+export declare function isValidationError(error: unknown): error is ValidationError;
+/**
+ * Checks if an error is a NotFoundError (404).
+ */
+export declare function isNotFoundError(error: unknown): error is NotFoundError;
+/**
+ * Checks if an error is a RateLimitError (429).
+ */
+export declare function isRateLimitError(error: unknown): error is RateLimitError;
+/**
+ * Checks if an error is an UnexpectedError.
+ */
+export declare function isUnexpectedError(error: unknown): error is UnexpectedError;
+/**
+ * Checks if an error is retriable.
+ *
+ * Returns true for:
+ * - Network errors
+ * - Timeout errors
+ * - Rate limit errors (after delay)
+ * - Server errors (5xx)
+ * - Any SDKError with retriable=true
+ *
+ * @example
+ * ```typescript
+ * if (isRetryable(error)) {
+ *   await sleep(1000);
+ *   return retry();
+ * }
+ * ```
+ */
+export declare function isRetryable(error: unknown): boolean;
+/**
+ * Gets the retry delay for an error (in milliseconds).
+ *
+ * For rate limit errors, returns the Retry-After value.
+ * For other retriable errors, returns a default backoff.
+ * For non-retriable errors, returns undefined.
+ *
+ * @param error - The error to check
+ * @param attempt - Current retry attempt (1-based) for backoff calculation
+ * @param baseDelayMs - Base delay for exponential backoff (default: 1000ms)
+ */
+export declare function getRetryDelay(error: unknown, attempt?: number, baseDelayMs?: number): number | undefined;
+/**
+ * Checks if an error indicates the user should re-authenticate.
+ *
+ * Returns true for:
+ * - Token expired
+ * - Token invalid
+ * - Token missing
+ */
+export declare function shouldReauthenticate(error: unknown): boolean;
+/**
+ * Checks if an error is a client error (4xx).
+ */
+export declare function isClientError(error: unknown): boolean;
+/**
+ * Checks if an error is transient (likely to resolve on retry).
+ *
+ * More conservative than isRetryable - only returns true for
+ * errors that are very likely to succeed on retry.
+ */
+export declare function isTransientError(error: unknown): boolean;
+/**
+ * Extracts HTTP status code from an error.
+ *
+ * Works with both SDKError and legacy error formats.
+ *
+ * @example
+ * ```typescript
+ * const status = extractStatusCode(error);
+ * if (status === 401) {
+ *   redirectToLogin();
+ * }
+ * ```
+ */
+export declare function extractStatusCode(error: unknown): number | null;
+/**
+ * Extracts error code from an error.
+ */
+export declare function extractErrorCode(error: unknown): SDKErrorCodeType | string | null;
+/**
+ * Gets a user-friendly error message.
+ *
+ * Returns a safe message that can be shown to end users.
+ * Does not include sensitive details.
+ */
+export declare function getUserFriendlyMessage(error: unknown): string;
+//# sourceMappingURL=guards.d.ts.map

package/dist/errors/guards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guards.d.ts","sourceRoot":"","sources":["../../src/errors/guards.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC;AAClC,OAAO,EAAgB,KAAK,gBAAgB,EAAmB,MAAM,SAAS,CAAC;AAC/E,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACjD,OAAO,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAC3D,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AACvD,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AACvD,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAC7D,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAC1D,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAC5D,OAAO,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAM7D;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,QAAQ,CAE5D;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,SAAS,CAE9D;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,cAAc,CAExE;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,YAAY,CAEpE;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,YAAY,CAEpE;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,WAAW,CAElE;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,eAAe,CAE1E;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,aAAa,CAEtE;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,cAAc,CAExE;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,eAAe,CAE1E;AAMD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAWnD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,OAAO,EACd,OAAO,GAAE,MAAU,EACnB,WAAW,GAAE,MAAa,GACzB,MAAM,GAAG,SAAS,CAapB;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAe5D;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAKrD;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAexD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAc/D;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,OAAO,GACb,gBAAgB,GAAG,MAAM,GAAG,IAAI,CAKlC;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CA4B7D"}

package/dist/errors/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * DJUST SDK Error Module
+ * Production-grade structured error handling.
+ *
+ * Architecture:
+ * - types.ts      - Type definitions
+ * - codes.ts      - Error code constants
+ * - base.ts       - SDKError base class
+ * - classes/      - Specific error types
+ * - factory.ts    - Error creation from responses
+ * - guards.ts     - Type guards and utilities
+ * - compat.ts     - Backward compatibility helpers
+ *
+ * @module errors
+ * @since 2.17.0
+ */
+export type { RequestMetadata, SDKErrorOptions, ErrorFactoryOptions, SerializedError, ClientSafeError, } from "./types";
+export { SDKErrorCode, RETRIABLE_ERROR_CODES, RETRIABLE_HTTP_STATUS_CODES, isRetriableCode, isRetriableStatus, } from "./codes";
+export type { SDKErrorCodeType } from "./codes";
+export { SDKError } from "./base";
+export { ValidationError, AuthError, ForbiddenError, NotFoundError, RateLimitError, NetworkError, TimeoutError, ServerError, UnexpectedError, } from "./classes";
+export { createErrorFromResponse, createErrorFromException } from "./factory";
+export { isSDKError, isAuthError, isForbiddenError, isNetworkError, isTimeoutError, isServerError, isValidationError, isNotFoundError, isRateLimitError, isUnexpectedError, isRetryable, getRetryDelay, shouldReauthenticate, isClientError, isTransientError, extractStatusCode, extractErrorCode, getUserFriendlyMessage, } from "./guards";
+export { toLegacyError, fromLegacyError, isLegacyError, parseLegacyError, withLegacyErrors, withStructuredErrors, isApiError, getHttpStatus, } from "./compat";
+//# sourceMappingURL=index.d.ts.map

package/dist/errors/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/errors/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAMH,YAAY,EACV,eAAe,EACf,eAAe,EACf,mBAAmB,EACnB,eAAe,EACf,eAAe,GAChB,MAAM,SAAS,CAAC;AAMjB,OAAO,EACL,YAAY,EACZ,qBAAqB,EACrB,2BAA2B,EAC3B,eAAe,EACf,iBAAiB,GAClB,MAAM,SAAS,CAAC;AAEjB,YAAY,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAMhD,OAAO,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC;AAMlC,OAAO,EACL,eAAe,EACf,SAAS,EACT,cAAc,EACd,aAAa,EACb,cAAc,EACd,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,eAAe,GAChB,MAAM,WAAW,CAAC;AAMnB,OAAO,EAAE,uBAAuB,EAAE,wBAAwB,EAAE,MAAM,WAAW,CAAC;AAM9E,OAAO,EAEL,UAAU,EACV,WAAW,EACX,gBAAgB,EAChB,cAAc,EACd,cAAc,EACd,aAAa,EACb,iBAAiB,EACjB,eAAe,EACf,gBAAgB,EAChB,iBAAiB,EAGjB,WAAW,EACX,aAAa,EACb,oBAAoB,EACpB,aAAa,EACb,gBAAgB,EAChB,iBAAiB,EACjB,gBAAgB,EAChB,sBAAsB,GACvB,MAAM,UAAU,CAAC;AAMlB,OAAO,EACL,aAAa,EACb,eAAe,EACf,aAAa,EACb,gBAAgB,EAChB,gBAAgB,EAChB,oBAAoB,EACpB,UAAU,EACV,aAAa,GACd,MAAM,UAAU,CAAC"}

package/dist/errors/types.d.ts

@@ -0,0 +1,100 @@
+/**
+ * DJUST SDK Error Types
+ * Type definitions for the error system.
+ *
+ * @module errors/types
+ * @since 2.17.0
+ */
+import type { SDKErrorCodeType } from "./codes";
+/**
+ * Metadata attached to errors for debugging and observability.
+ * Contains request context without sensitive data.
+ */
+export interface RequestMetadata {
+    /** Unique request identifier for log correlation */
+    requestId?: string;
+    /** API endpoint path (e.g., "/v1/shop/carts") */
+    endpoint?: string;
+    /** HTTP method (GET, POST, etc.) */
+    method?: string;
+    /** Request duration in milliseconds */
+    durationMs?: number;
+    /** Service or provider name */
+    service?: string;
+    /** SDK method name (e.g., "updateCommercialOrderLines") */
+    sdkMethod?: string;
+    /** Retry attempt number (1-based) */
+    attempt?: number;
+    /** Query parameters (sanitized, no sensitive data) */
+    queryParams?: Record<string, unknown>;
+    /** Request body (sanitized, no sensitive data like passwords/tokens) */
+    body?: unknown;
+}
+/**
+ * Options for constructing an SDKError.
+ */
+export interface SDKErrorOptions {
+    /** Stable error code for programmatic handling */
+    code: SDKErrorCodeType;
+    /** Human-readable error message */
+    message: string;
+    /** HTTP status code (0 for non-HTTP errors) */
+    httpStatus?: number;
+    /** Additional structured details (non-sensitive) */
+    details?: Record<string, unknown>;
+    /** Original error that caused this error */
+    cause?: Error;
+    /** Whether the operation can be retried */
+    retriable?: boolean;
+    /** Suggested delay before retry in milliseconds */
+    retryAfterMs?: number;
+    /** Request context metadata */
+    metadata?: RequestMetadata;
+}
+/**
+ * Options for creating errors from HTTP responses.
+ */
+export interface ErrorFactoryOptions {
+    /** HTTP response status code */
+    statusCode: number;
+    /** Response body as string */
+    body: string;
+    /** Request URL */
+    url?: string;
+    /** HTTP method */
+    method?: string;
+    /** Request duration in milliseconds */
+    durationMs?: number;
+    /** Request correlation ID */
+    requestId?: string;
+    /** SDK method name (e.g., "updateCommercialOrderLines") */
+    sdkMethod?: string;
+    /** Query parameters from the request */
+    queryParams?: Record<string, unknown>;
+    /** Request body (will be sanitized in metadata) */
+    requestBody?: unknown;
+}
+/**
+ * JSON-serializable error representation for logging.
+ */
+export interface SerializedError {
+    name: string;
+    code: SDKErrorCodeType;
+    message: string;
+    httpStatus: number;
+    retriable: boolean;
+    retryAfterMs?: number;
+    details: Record<string, unknown>;
+    metadata: RequestMetadata;
+    timestamp: string;
+}
+/**
+ * Client-safe error representation (no sensitive data).
+ */
+export interface ClientSafeError {
+    code: SDKErrorCodeType;
+    message: string;
+    httpStatus: number;
+    retriable: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/errors/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/errors/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAMhD;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,oDAAoD;IACpD,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,iDAAiD;IACjD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB,oCAAoC;IACpC,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,uCAAuC;IACvC,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,+BAA+B;IAC/B,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,2DAA2D;IAC3D,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,qCAAqC;IACrC,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,sDAAsD;IACtD,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAEtC,wEAAwE;IACxE,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAMD;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,kDAAkD;IAClD,IAAI,EAAE,gBAAgB,CAAC;IAEvB,mCAAmC;IACnC,OAAO,EAAE,MAAM,CAAC;IAEhB,+CAA+C;IAC/C,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,oDAAoD;IACpD,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAElC,4CAA4C;IAC5C,KAAK,CAAC,EAAE,KAAK,CAAC;IAEd,2CAA2C;IAC3C,SAAS,CAAC,EAAE,OAAO,CAAC;IAEpB,mDAAmD;IACnD,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB,+BAA+B;IAC/B,QAAQ,CAAC,EAAE,eAAe,CAAC;CAC5B;AAMD;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,gCAAgC;IAChC,UAAU,EAAE,MAAM,CAAC;IAEnB,8BAA8B;IAC9B,IAAI,EAAE,MAAM,CAAC;IAEb,kBAAkB;IAClB,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb,kBAAkB;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,uCAAuC;IACvC,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,6BAA6B;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,2DAA2D;IAC3D,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,wCAAwC;IACxC,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAEtC,mDAAmD;IACnD,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAMD;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,gBAAgB,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,OAAO,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,QAAQ,EAAE,eAAe,CAAC;IAC1B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,gBAAgB,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,OAAO,CAAC;CACpB"}

package/dist/helpers/index.d.ts

@@ -0,0 +1,42 @@
+/**
+ * DJUST SDK Helpers Module
+ * Utility functions for parameter validation and browser detection.
+ *
+ * @module helpers
+ * @since 2.17.0
+ */
+export { required, oneOfRequired } from "./parameters-validation";
+export { isBrowser, getCookie, setCookie, deleteCookie } from "./utils";
+/**
+ * Type guard to check if a value is defined (not null or undefined)
+ */
+export declare function isDefined<T>(value: T | null | undefined): value is T;
+/**
+ * Filters out undefined and null values from an object
+ */
+export declare function filterNullish<T extends Record<string, unknown>>(obj: T): Partial<T>;
+/**
+ * Delays execution for specified milliseconds
+ */
+export declare function delay(ms: number): Promise<void>;
+/**
+ * Generates a unique request ID
+ */
+export declare function generateRequestId(): string;
+/**
+ * Checks if the current environment is server-side (Node.js)
+ */
+export declare function isServer(): boolean;
+/**
+ * Safely parses JSON, returning undefined on failure
+ */
+export declare function safeJsonParse<T>(json: string): T | undefined;
+/**
+ * Checks if a JWT token is expired
+ */
+export declare function isTokenExpired(token: string): boolean;
+/**
+ * Extracts the expiration time from a JWT token
+ */
+export declare function getTokenExpiration(token: string): Date | null;
+//# sourceMappingURL=index.d.ts.map

package/dist/helpers/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/helpers/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAMlE,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAMxE;;GAEG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI,GAAG,SAAS,GAAG,KAAK,IAAI,CAAC,CAEpE;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7D,GAAG,EAAE,CAAC,GACL,OAAO,CAAC,CAAC,CAAC,CAIZ;AAED;;GAEG;AACH,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE/C;AAED;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAE1C;AAED;;GAEG;AACH,wBAAgB,QAAQ,IAAI,OAAO,CAElC;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS,CAM5D;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAQrD;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAO7D"}

package/dist/helpers/parameters-validation.d.ts

@@ -0,0 +1,3 @@
+export declare const required: (parameters: Record<string, any>) => void;
+export declare const oneOfRequired: (parameters: Record<string, any>) => void;
+//# sourceMappingURL=parameters-validation.d.ts.map

package/dist/helpers/parameters-validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parameters-validation.d.ts","sourceRoot":"","sources":["../../src/helpers/parameters-validation.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,QAAQ,GAAI,YAAY,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,SAMvD,CAAC;AAEF,eAAO,MAAM,aAAa,GAAI,YAAY,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,SAa5D,CAAC"}

package/dist/helpers/utils.d.ts

@@ -0,0 +1,5 @@
+export declare function isBrowser(): boolean;
+export declare function getCookie(name: string): string | null;
+export declare function setCookie(name: string, value: string, expirationDays: number): void;
+export declare function deleteCookie(name: string): void;
+//# sourceMappingURL=utils.d.ts.map

package/dist/helpers/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/helpers/utils.ts"],"names":[],"mappings":"AAAA,wBAAgB,SAAS,IAAI,OAAO,CAEnC;AAED,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAKrD;AAED,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,QAM5E;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,QAGxC"}