@djust-b2b/djust-front-sdk 3.0.0-beta.8 → 3.0.0

package/lib/errors/classes/validation.error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.error.js","sourceRoot":"","sources":["../../../src/errors/classes/validation.error.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG;;;AAEH,kCAAmC;AACnC,oCAAwC;AAGxC;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAa,eAAgB,SAAQ,eAAQ;IAC3C,YACE,OAAe,EACf,OAAiC,EACjC,QAA0B;QAE1B,KAAK,CAAC;YACJ,IAAI,EAAE,oBAAY,CAAC,gBAAgB;YACnC,OAAO;YACP,UAAU,EAAE,GAAG;YACf,OAAO;YACP,SAAS,EAAE,KAAK,EAAE,wCAAwC;YAC1D,QAAQ;SACT,CAAC,CAAC;QACH,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;IAChC,CAAC;IAED;;;;;OAKG;IACH,MAAM,CAAC,gBAAgB,CACrB,KAAa,EACb,QAA0B;QAE1B,OAAO,IAAI,eAAe,CACxB,uBAAuB,KAAK,cAAc,EAC1C;YACE,SAAS,EAAE,KAAK;YAChB,IAAI,EAAE,oBAAY,CAAC,iBAAiB;SACrC,EACD,QAAQ,CACT,CAAC;IACJ,CAAC;IAED;;;;;;OAMG;IACH,MAAM,CAAC,gBAAgB,CACrB,KAAa,EACb,MAAc,EACd,QAA0B;QAE1B,OAAO,IAAI,eAAe,CACxB,sBAAsB,KAAK,MAAM,MAAM,EAAE,EACzC;YACE,SAAS,EAAE,KAAK;YAChB,MAAM;YACN,IAAI,EAAE,oBAAY,CAAC,iBAAiB;SACrC,EACD,QAAQ,CACT,CAAC;IACJ,CAAC;IAED;;;;;;;OAOG;IACH,MAAM,CAAC,YAAY,CACjB,KAAa,EACb,QAAgB,EAChB,MAAc,EACd,QAA0B;QAE1B,OAAO,IAAI,eAAe,CACxB,cAAc,KAAK,aAAa,QAAQ,SAAS,MAAM,EAAE,EACzD;YACE,SAAS,EAAE,KAAK;YAChB,QAAQ;YACR,MAAM;YACN,IAAI,EAAE,oBAAY,CAAC,iBAAiB;SACrC,EACD,QAAQ,CACT,CAAC;IACJ,CAAC;IAED;;;;;OAKG;IACH,MAAM,CAAC,eAAe,CACpB,MAAmD,EACnD,QAA0B;QAE1B,MAAM,QAAQ,GAAG,MAAM;aACpB,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;aAC9D,MAAM,CAAC,OAAO,CAAC;aACf,IAAI,CAAC,IAAI,CAAC,CAAC;QAEd,OAAO,IAAI,eAAe,CACxB,QAAQ,IAAI,mBAAmB,EAC/B,EAAE,gBAAgB,EAAE,MAAM,EAAE,EAC5B,QAAQ,CACT,CAAC;IACJ,CAAC;CACF;AA3GD,0CA2GC"}

package/lib/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/lib/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/lib/errors/codes.js

@@ -0,0 +1,143 @@
+"use strict";
+/**
+ * DJUST SDK Error Codes
+ * Stable error codes for programmatic error handling.
+ *
+ * @module errors/codes
+ * @since 2.17.0
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RETRIABLE_HTTP_STATUS_CODES = exports.RETRIABLE_ERROR_CODES = exports.SDKErrorCode = void 0;
+exports.isRetriableCode = isRetriableCode;
+exports.isRetriableStatus = isRetriableStatus;
+/**
+ * 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');
+ *   }
+ * }
+ * ```
+ */
+exports.SDKErrorCode = {
+    // ========== VALIDATION ERRORS ==========
+    /** Generic validation error */
+    VALIDATION_ERROR: "VALIDATION_ERROR",
+    /** Required parameter is missing */
+    MISSING_PARAMETER: "MISSING_PARAMETER",
+    /** Parameter value is invalid */
+    INVALID_PARAMETER: "INVALID_PARAMETER",
+    // ========== AUTHENTICATION ERRORS (401) ==========
+    /** Generic authentication error */
+    AUTH_ERROR: "AUTH_ERROR",
+    /** Access token has expired */
+    TOKEN_EXPIRED: "TOKEN_EXPIRED",
+    /** Access token is invalid or malformed */
+    TOKEN_INVALID: "TOKEN_INVALID",
+    /** Access token is required but not provided */
+    TOKEN_MISSING: "TOKEN_MISSING",
+    /** Username or password is incorrect */
+    INVALID_CREDENTIALS: "INVALID_CREDENTIALS",
+    // ========== AUTHORIZATION ERRORS (403) ==========
+    /** Generic authorization error */
+    FORBIDDEN: "FORBIDDEN",
+    /** User lacks required permissions */
+    INSUFFICIENT_PERMISSIONS: "INSUFFICIENT_PERMISSIONS",
+    // ========== RESOURCE ERRORS (4xx) ==========
+    /** Resource not found */
+    NOT_FOUND: "NOT_FOUND",
+    /** Resource conflict (e.g., duplicate) */
+    CONFLICT: "CONFLICT",
+    /** Resource no longer available */
+    GONE: "GONE",
+    /** Request entity too large */
+    PAYLOAD_TOO_LARGE: "PAYLOAD_TOO_LARGE",
+    /** Unsupported media type */
+    UNSUPPORTED_MEDIA_TYPE: "UNSUPPORTED_MEDIA_TYPE",
+    /** Unprocessable entity (validation at API level) */
+    UNPROCESSABLE_ENTITY: "UNPROCESSABLE_ENTITY",
+    // ========== RATE LIMITING (429) ==========
+    /** Too many requests */
+    RATE_LIMITED: "RATE_LIMITED",
+    // ========== NETWORK ERRORS ==========
+    /** Generic network error */
+    NETWORK_ERROR: "NETWORK_ERROR",
+    /** Request timeout */
+    TIMEOUT: "TIMEOUT",
+    /** Connection refused */
+    CONNECTION_REFUSED: "CONNECTION_REFUSED",
+    /** DNS resolution failed */
+    DNS_ERROR: "DNS_ERROR",
+    /** Request was aborted */
+    ABORTED: "ABORTED",
+    /** SSL/TLS error */
+    SSL_ERROR: "SSL_ERROR",
+    // ========== SERVER ERRORS (5xx) ==========
+    /** Generic server error */
+    SERVER_ERROR: "SERVER_ERROR",
+    /** Internal server error (500) */
+    INTERNAL_ERROR: "INTERNAL_ERROR",
+    /** Bad gateway (502) */
+    BAD_GATEWAY: "BAD_GATEWAY",
+    /** Service unavailable (503) */
+    SERVICE_UNAVAILABLE: "SERVICE_UNAVAILABLE",
+    /** Gateway timeout (504) */
+    GATEWAY_TIMEOUT: "GATEWAY_TIMEOUT",
+    // ========== SDK ERRORS ==========
+    /** SDK not initialized */
+    SDK_NOT_INITIALIZED: "SDK_NOT_INITIALIZED",
+    /** SDK configuration error */
+    CONFIGURATION_ERROR: "CONFIGURATION_ERROR",
+    /** Feature not supported */
+    NOT_SUPPORTED: "NOT_SUPPORTED",
+    // ========== UNKNOWN ==========
+    /** Unexpected error (bug or unknown state) */
+    UNEXPECTED_ERROR: "UNEXPECTED_ERROR",
+};
+/**
+ * Error codes that indicate retriable errors.
+ */
+exports.RETRIABLE_ERROR_CODES = [
+    exports.SDKErrorCode.TIMEOUT,
+    exports.SDKErrorCode.NETWORK_ERROR,
+    exports.SDKErrorCode.CONNECTION_REFUSED,
+    exports.SDKErrorCode.DNS_ERROR,
+    exports.SDKErrorCode.RATE_LIMITED,
+    exports.SDKErrorCode.SERVER_ERROR,
+    exports.SDKErrorCode.INTERNAL_ERROR,
+    exports.SDKErrorCode.BAD_GATEWAY,
+    exports.SDKErrorCode.SERVICE_UNAVAILABLE,
+    exports.SDKErrorCode.GATEWAY_TIMEOUT,
+];
+/**
+ * HTTP status codes that are typically retriable.
+ */
+exports.RETRIABLE_HTTP_STATUS_CODES = [
+    408, // Request Timeout
+    429, // Too Many Requests
+    500, // Internal Server Error
+    502, // Bad Gateway
+    503, // Service Unavailable
+    504, // Gateway Timeout
+];
+/**
+ * Checks if an error code represents a retriable error.
+ */
+function isRetriableCode(code) {
+    return exports.RETRIABLE_ERROR_CODES.includes(code);
+}
+/**
+ * Checks if an HTTP status code represents a retriable error.
+ */
+function isRetriableStatus(status) {
+    return exports.RETRIABLE_HTTP_STATUS_CODES.includes(status);
+}
+//# sourceMappingURL=codes.js.map

package/lib/errors/codes.js.map

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

package/lib/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/lib/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/lib/errors/compat.js

@@ -0,0 +1,280 @@
+"use strict";
+/**
+ * DJUST SDK Error Compatibility
+ * Helpers for backward compatibility with legacy error handling.
+ *
+ * @module errors/compat
+ * @since 2.17.0
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toLegacyError = toLegacyError;
+exports.fromLegacyError = fromLegacyError;
+exports.isLegacyError = isLegacyError;
+exports.parseLegacyError = parseLegacyError;
+exports.withLegacyErrors = withLegacyErrors;
+exports.withStructuredErrors = withStructuredErrors;
+exports.isApiError = isApiError;
+exports.getHttpStatus = getHttpStatus;
+const base_1 = require("./base");
+/**
+ * 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;
+ * ```
+ */
+function toLegacyError(sdkError) {
+    // Ensure the message is always valid JSON for legacy format
+    let errorMessage;
+    try {
+        // Try to parse as JSON to validate
+        JSON.parse(sdkError.message);
+        // If it's already valid JSON, use it as is
+        errorMessage = sdkError.message;
+    }
+    catch {
+        // If not JSON, wrap it in a JSON structure
+        errorMessage = JSON.stringify({
+            errors: [
+                {
+                    code: sdkError.code || "UNKNOWN",
+                    message: sdkError.message || "An error occurred",
+                },
+            ],
+        });
+    }
+    // Construct legacy message format
+    const legacyMessage = sdkError.httpStatus > 0
+        ? `[API] Error ${sdkError.httpStatus}: ${errorMessage}`
+        : `[SDK] Error: ${errorMessage}`;
+    const error = new Error(legacyMessage);
+    // Attach original error for debugging
+    error.originalError = sdkError;
+    error.code = sdkError.code;
+    error.httpStatus = sdkError.httpStatus;
+    error.details = sdkError.details;
+    error.retriable = sdkError.retriable;
+    // Preserve stack trace from original error
+    if (sdkError.stack) {
+        error.stack = sdkError.stack;
+    }
+    return error;
+}
+/**
+ * Extracts the original SDKError from a legacy error if available.
+ *
+ * @example
+ * ```typescript
+ * const sdkError = fromLegacyError(error);
+ * if (sdkError) {
+ *   console.log(sdkError.code);
+ * }
+ * ```
+ */
+function fromLegacyError(error) {
+    return error.originalError instanceof base_1.SDKError
+        ? error.originalError
+        : null;
+}
+/**
+ * Checks if an error is in legacy format.
+ *
+ * Legacy format: "[API] Error XXX: ..." or "[SDK] Error: ..."
+ */
+function isLegacyError(error) {
+    if (!(error instanceof Error)) {
+        return false;
+    }
+    return (error.message.startsWith("[API] Error") ||
+        error.message.startsWith("[SDK] Error"));
+}
+/**
+ * Parses a legacy error message to extract status code and message.
+ *
+ * @example
+ * ```typescript
+ * const parsed = parseLegacyError(error);
+ * // { statusCode: 401, message: 'Unauthorized' }
+ * ```
+ */
+function parseLegacyError(error) {
+    // Check for attached SDK error first
+    const original = fromLegacyError(error);
+    if (original) {
+        return {
+            statusCode: original.httpStatus,
+            message: original.message,
+            code: original.code,
+        };
+    }
+    // Parse legacy message format
+    const apiMatch = error.message.match(/^\[API\] Error (\d{3}): (.+)$/);
+    if (apiMatch) {
+        return {
+            statusCode: parseInt(apiMatch[1], 10),
+            message: apiMatch[2],
+            code: error.code ?? null,
+        };
+    }
+    const sdkMatch = error.message.match(/^\[SDK\] Error: (.+)$/);
+    if (sdkMatch) {
+        return {
+            statusCode: null,
+            message: sdkMatch[1],
+            code: error.code ?? null,
+        };
+    }
+    // Not a legacy error format
+    return {
+        statusCode: null,
+        message: error.message,
+        code: 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);
+ * });
+ * ```
+ */
+function withLegacyErrors(fn) {
+    return (async (...args) => {
+        try {
+            return await fn(...args);
+        }
+        catch (error) {
+            if (error instanceof base_1.SDKError) {
+                throw toLegacyError(error);
+            }
+            throw error;
+        }
+    });
+}
+/**
+ * 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);
+ * });
+ * ```
+ */
+function withStructuredErrors(fn) {
+    return (async (...args) => {
+        try {
+            return await fn(...args);
+        }
+        catch (error) {
+            if (error instanceof base_1.SDKError) {
+                throw error;
+            }
+            if (error instanceof Error) {
+                // Try to extract original SDKError
+                const original = fromLegacyError(error);
+                if (original) {
+                    throw original;
+                }
+                // Parse legacy format
+                const parsed = parseLegacyError(error);
+                if (parsed.statusCode) {
+                    // Import dynamically to avoid circular dependency
+                    const { createErrorFromResponse } = await Promise.resolve().then(() => __importStar(require("./factory")));
+                    throw createErrorFromResponse({
+                        statusCode: parsed.statusCode,
+                        body: JSON.stringify({ message: parsed.message }),
+                    });
+                }
+            }
+            throw error;
+        }
+    });
+}
+/**
+ * Type guard that works with both SDKError and legacy errors.
+ *
+ * Useful during migration when code may receive either format.
+ */
+function isApiError(error) {
+    if (error instanceof base_1.SDKError) {
+        return error.httpStatus >= 400;
+    }
+    if (error instanceof Error && isLegacyError(error)) {
+        const parsed = parseLegacyError(error);
+        return parsed.statusCode !== null && parsed.statusCode >= 400;
+    }
+    return false;
+}
+/**
+ * Gets HTTP status code from either SDKError or legacy error.
+ *
+ * Unified accessor for backward compatibility.
+ */
+function getHttpStatus(error) {
+    if (error instanceof base_1.SDKError) {
+        return error.httpStatus || null;
+    }
+    if (error instanceof Error) {
+        // Check for attached status
+        if (typeof error.httpStatus === "number") {
+            return error.httpStatus;
+        }
+        // Parse legacy format
+        const parsed = parseLegacyError(error);
+        return parsed.statusCode;
+    }
+    return null;
+}
+//# sourceMappingURL=compat.js.map

package/lib/errors/compat.js.map

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