@tapsilat/tapsilat-js 1.0.2 → 1.0.4

package/dist/index.esm.js

@@ -1,6 +1,23 @@
+import crypto from 'crypto';
+
+/**
+ * @category Errors
+ * @summary Base error class for Tapsilat SDK
+ * @description Foundation error class for all Tapsilat-specific errors with error code and details support
+ * @class TapsilatError
+ * @extends Error
+ */
 class TapsilatError extends Error {
     code;
     details;
+    /**
+     * @summary Creates a new TapsilatError instance
+     * @description Initializes base error with message, code and optional details
+     *
+     * @param message - Human-readable error message
+     * @param code - Error code for programmatic identification
+     * @param details - Optional additional error context
+     */
     constructor(message, code, details) {
         super(message);
         this.name = 'TapsilatError';
@@ -11,32 +28,96 @@ class TapsilatError extends Error {
             Error.captureStackTrace(this, TapsilatError);
         }
     }
+    /**
+     * @summary Creates a TapsilatError from an API error response
+     * @description Factory method to convert API error format to a TapsilatError instance
+     *
+     * @param apiError - API error object from response
+     * @returns New TapsilatError instance with properties from API error
+     */
     static fromAPIError(apiError) {
         return new TapsilatError(apiError.message, apiError.code, apiError.details);
     }
 }
+/**
+ * @category Errors
+ * @summary Network-related error class for HTTP issues
+ * @description Error class for network and HTTP-specific problems including status codes
+ * @class TapsilatNetworkError
+ * @extends TapsilatError
+ */
 class TapsilatNetworkError extends TapsilatError {
     statusCode;
+    /**
+     * @summary Creates a new network error instance
+     * @description Initializes network error with message, code, status code and optional details
+     *
+     * @param message - Human-readable error message
+     * @param code - Error code for programmatic identification
+     * @param statusCode - HTTP status code if applicable
+     * @param details - Optional additional error context
+     */
     constructor(message, code, statusCode, details) {
         super(message, code, details);
         this.name = 'TapsilatNetworkError';
         this.statusCode = statusCode;
     }
 }
+/**
+ * @category Errors
+ * @summary Error class for validation failures
+ * @description Error class for data validation issues with field-specific error details
+ * @class TapsilatValidationError
+ * @extends TapsilatError
+ */
 class TapsilatValidationError extends TapsilatError {
+    /**
+     * @summary Creates a new validation error instance
+     * @description Initializes validation error with message and optional field-specific details
+     *
+     * @param message - Human-readable error message
+     * @param details - Optional field-specific validation errors
+     */
     constructor(message, details) {
         super(message, 'VALIDATION_ERROR', details);
         this.name = 'TapsilatValidationError';
     }
 }
+/**
+ * @category Errors
+ * @summary Error class for authentication issues
+ * @description Error class for problems related to API keys, authentication tokens, or permissions
+ * @class TapsilatAuthenticationError
+ * @extends TapsilatError
+ */
 class TapsilatAuthenticationError extends TapsilatError {
+    /**
+     * @summary Creates a new authentication error instance
+     * @description Initializes authentication error with an optional custom message
+     *
+     * @param message - Human-readable error message (defaults to 'Authentication failed')
+     */
     constructor(message = 'Authentication failed') {
         super(message, 'AUTHENTICATION_ERROR');
         this.name = 'TapsilatAuthenticationError';
     }
 }
+/**
+ * @category Errors
+ * @summary Error class for rate limit exceeded issues
+ * @description Error class for API rate limiting with information about when to retry
+ * @class TapsilatRateLimitError
+ * @extends TapsilatError
+ */
 class TapsilatRateLimitError extends TapsilatError {
     retryAfter;
+    /**
+     * @summary Creates a new rate limit error instance
+     * @description Initializes rate limit error with message and optional retry-after seconds
+     *
+     * @param message - Human-readable error message (defaults to 'Rate limit exceeded')
+     * @param retryAfter - Optional seconds to wait before retrying
+     */
     constructor(message = 'Rate limit exceeded', retryAfter) {
         super(message, 'RATE_LIMIT_ERROR');
         this.name = 'TapsilatRateLimitError';
@@ -44,20 +125,52 @@ class TapsilatRateLimitError extends TapsilatError {
     }
 }
 
+/**
+ * @category HTTP
+ * @summary Central registry and execution engine for all HTTP interceptors
+ * @description Maintains lists of request, response and error interceptors and provides methods to execute them in sequence
+ * @class InterceptorManager
+ */
 class InterceptorManager {
     requestInterceptors = [];
     responseInterceptors = [];
     errorInterceptors = [];
-    // Request interceptors
+    /**
+     * Adds a request interceptor to the chain
+     *
+     * @summary Register a new request interceptor function
+     * @description Adds a new interceptor to process requests before they are sent
+     *
+     * @param interceptor - The request interceptor function to add
+     * @returns The index of the added interceptor (can be used to remove it later)
+     */
     addRequestInterceptor(interceptor) {
         this.requestInterceptors.push(interceptor);
         return this.requestInterceptors.length - 1;
     }
+    /**
+     * Removes a previously added request interceptor
+     *
+     * @summary Unregister a request interceptor by its ID
+     * @description Removes the request interceptor at the specified position
+     *
+     * @param id - The index of the interceptor to remove
+     */
     removeRequestInterceptor(id) {
         if (this.requestInterceptors[id]) {
             delete this.requestInterceptors[id];
         }
     }
+    /**
+     * Runs all registered request interceptors in sequence
+     *
+     * @summary Process a request through all interceptors
+     * @description Executes each registered request interceptor in order, passing modified url and options to each
+     *
+     * @param url - The initial request URL
+     * @param options - The initial request options
+     * @returns Modified URL and options after all interceptors have processed them
+     */
     async executeRequestInterceptors(url, options) {
         let currentUrl = url;
         let currentOptions = options;
@@ -70,16 +183,36 @@ class InterceptorManager {
         }
         return { url: currentUrl, options: currentOptions };
     }
-    // Response interceptors
+    /**
+     * @summary Register a new response interceptor function
+     * @description Adds a new interceptor to process responses before they are returned to the caller
+     *
+     * @param interceptor - The response interceptor function to add
+     * @returns The index of the added interceptor (can be used to remove it later)
+     */
     addResponseInterceptor(interceptor) {
         this.responseInterceptors.push(interceptor);
         return this.responseInterceptors.length - 1;
     }
+    /**
+     * @summary Unregister a response interceptor by its ID
+     * @description Removes the response interceptor at the specified position
+     *
+     * @param id - The index of the interceptor to remove
+     */
     removeResponseInterceptor(id) {
         if (this.responseInterceptors[id]) {
             delete this.responseInterceptors[id];
         }
     }
+    /**
+     * @summary Process a response through all interceptors
+     * @description Executes each registered response interceptor in order
+     *
+     * @param response - The API response to process
+     * @param request - The original request information
+     * @returns Modified response after all interceptors have processed it
+     */
     async executeResponseInterceptors(response, request) {
         let currentResponse = response;
         for (const interceptor of this.responseInterceptors) {
@@ -89,16 +222,36 @@ class InterceptorManager {
         }
         return currentResponse;
     }
-    // Error interceptors
+    /**
+     * @summary Register a new error interceptor function
+     * @description Adds a new interceptor to process errors before they are thrown
+     *
+     * @param interceptor - The error interceptor function to add
+     * @returns The index of the added interceptor (can be used to remove it later)
+     */
     addErrorInterceptor(interceptor) {
         this.errorInterceptors.push(interceptor);
         return this.errorInterceptors.length - 1;
     }
+    /**
+     * @summary Unregister an error interceptor by its ID
+     * @description Removes the error interceptor at the specified position
+     *
+     * @param id - The index of the interceptor to remove
+     */
     removeErrorInterceptor(id) {
         if (this.errorInterceptors[id]) {
             delete this.errorInterceptors[id];
         }
     }
+    /**
+     * @summary Process an error through all interceptors
+     * @description Executes each registered error interceptor in order until one handles the error
+     *
+     * @param error - The error that occurred during the request
+     * @param request - The original request information
+     * @returns Either a recovery response or throws the error if no interceptors handle it
+     */
     async executeErrorInterceptors(error, request) {
         for (const interceptor of this.errorInterceptors) {
             if (interceptor) {
@@ -114,7 +267,10 @@ class InterceptorManager {
         // If no interceptor handled the error, re-throw
         throw error;
     }
-    // Clear all interceptors
+    /**
+     * @summary Remove all registered interceptors
+     * @description Clears all request, response, and error interceptors at once
+     */
     clear() {
         this.requestInterceptors = [];
         this.responseInterceptors = [];
@@ -123,8 +279,10 @@ class InterceptorManager {
 }
 
 /**
- * HTTP Client for making API requests with comprehensive error handling,
- * retry logic, and request/response interceptors
+ * @category HTTP
+ * @summary HTTP Client for making API requests to Tapsilat services
+ * @description Provides a robust client with comprehensive error handling,
+ * retry logic, and request/response interceptors for interacting with the Tapsilat API
  *
  * @example
  * ```typescript
@@ -135,10 +293,17 @@ class InterceptorManager {
  *
  * const data = await client.get<UserResponse>('/users/123');
  * ```
+ * @class HttpClient
  */
 class HttpClient {
     config;
     interceptors = new InterceptorManager();
+    /**
+     * @summary Creates a new HTTP client instance
+     * @description Initializes the HTTP client with the provided configuration
+     *
+     * @param config - The configuration for the Tapsilat API client
+     */
     constructor(config) {
         this.config = config;
     }
@@ -158,7 +323,9 @@ class HttpClient {
         return this.request("DELETE", url, undefined, config);
     }
     /**
-     * Core request method with comprehensive error handling and retry logic
+     * @category HTTP Client
+     * @summary Core request method with comprehensive error handling and retry logic
+     * @description Handles all HTTP requests with error handling, retries, and interceptors
      *
      * @param method - HTTP method to use
      * @param url - Request URL (relative to baseURL)
@@ -209,7 +376,14 @@ class HttpClient {
         }
     }
     /**
-     * Makes the actual HTTP request with timeout handling
+     * @category HTTP Client Internals
+     * @summary Makes the actual HTTP request with timeout handling
+     * @description Performs the fetch request with timeout handling and abort controller
+     *
+     * @param url - Full URL to request
+     * @param options - Fetch request options
+     * @param timeout - Optional timeout in milliseconds
+     * @returns Promise resolving to API response
      */
     async makeRequest(url, options, timeout) {
         const controller = new AbortController();
@@ -241,7 +415,12 @@ class HttpClient {
         }
     }
     /**
-     * Processes the fetch response and converts to APIResponse format
+     * @category HTTP Client Internals
+     * @summary Processes the fetch response and converts to APIResponse format
+     * @description Parses the response and formats it according to the APIResponse interface
+     *
+     * @param response - The raw fetch Response object
+     * @returns Processed API response
      */
     async processResponse(response) {
         const contentType = response.headers.get("content-type");
@@ -277,7 +456,13 @@ class HttpClient {
         };
     }
     /**
-     * Creates appropriate error based on response status and data
+     * @category HTTP Client Internals
+     * @summary Creates appropriate error based on response status and data
+     * @description Maps HTTP status codes to specific Tapsilat error types
+     *
+     * @param response - The raw fetch Response object
+     * @param data - The parsed response data
+     * @returns Appropriate TapsilatError subclass instance
      */
     createErrorFromResponse(response, data) {
         const status = response.status;
@@ -309,7 +494,12 @@ class HttpClient {
         }
     }
     /**
-     * Extracts error message from response data
+     * @category HTTP Client Internals
+     * @summary Extracts error message from response data
+     * @description Attempts to find an error message in various locations within the response
+     *
+     * @param data - The parsed response data
+     * @returns Error message if found
      */
     extractErrorMessage(data) {
         if (typeof data === "string") {
@@ -322,7 +512,12 @@ class HttpClient {
         return undefined;
     }
     /**
-     * Extracts validation details from error response
+     * @category HTTP Client Internals
+     * @summary Extracts validation details from error response
+     * @description Parses field-specific validation errors from the API response
+     *
+     * @param data - The parsed response data
+     * @returns Object mapping field names to error messages
      */
     extractValidationDetails(data) {
         if (data && typeof data === "object") {
@@ -332,7 +527,12 @@ class HttpClient {
         return undefined;
     }
     /**
-     * Extracts rate limit information from response headers
+     * @category HTTP Client Internals
+     * @summary Extracts rate limit information from response headers
+     * @description Reads and parses rate limiting headers from the API response
+     *
+     * @param response - The raw fetch Response object
+     * @returns Rate limit information including limits and reset time
      */
     extractRateLimitInfo(response) {
         const limit = response.headers.get("x-ratelimit-limit");
@@ -345,10 +545,19 @@ class HttpClient {
         };
     }
     /**
-     * Builds the complete URL for the request
+     * @category HTTP Client Internals
+     * @summary Builds the complete URL for the request
+     * @description Constructs the full URL with base URL and query parameters
+     *
+     * @param url - The endpoint path or full URL
+     * @param customBaseURL - Optional override for the base URL
+     * @param params - Optional query parameters
+     * @returns Complete request URL
      */
     buildUrl(url, customBaseURL, params) {
-        const baseURL = customBaseURL || this.config.baseURL || "https://api.tapsilat.com/v1";
+        const baseURL = customBaseURL ||
+            this.config.baseURL ||
+            "https://acquiring.tapsilat.dev/api/v1";
         if (url.startsWith("http://") || url.startsWith("https://")) {
             return url;
         }
@@ -371,7 +580,14 @@ class HttpClient {
         return fullUrl;
     }
     /**
-     * Builds RequestInit options for the fetch request
+     * @category HTTP Client Internals
+     * @summary Builds RequestInit options for the fetch request
+     * @description Prepares headers and request configuration for fetch API
+     *
+     * @param method - The HTTP method to use
+     * @param body - Optional request body
+     * @param config - Additional request configuration
+     * @returns Configured RequestInit object for fetch
      */
     async buildRequestOptions(method, body, config) {
         const headers = new Headers({
@@ -406,7 +622,12 @@ class HttpClient {
         return options;
     }
     /**
-     * Determines if an error should prevent retrying
+     * @category HTTP Client Internals
+     * @summary Determines if an error should prevent retrying
+     * @description Checks error types to decide if retry attempts should be aborted
+     *
+     * @param error - The error that occurred
+     * @returns Whether retry should be prevented for this error
      */
     shouldNotRetry(error) {
         // Don't retry authentication, validation, or client errors
@@ -415,7 +636,12 @@ class HttpClient {
             (error instanceof TapsilatError && error.code === "NOT_FOUND"));
     }
     /**
-     * Calculates retry delay with exponential backoff
+     * @category HTTP Client Internals
+     * @summary Calculates retry delay with exponential backoff
+     * @description Implements exponential backoff with jitter for retry attempts
+     *
+     * @param attempt - The current retry attempt number (0-indexed)
+     * @returns Delay in milliseconds before next retry
      */
     calculateRetryDelay(attempt) {
         const baseDelay = 1000; // 1 second
@@ -425,14 +651,21 @@ class HttpClient {
         return delay + Math.random() * 1000;
     }
     /**
-     * Utility method to create delay
+     * @category HTTP Client Internals
+     * @summary Utility method to create delay
+     * @description Creates a promise that resolves after the specified time
+     *
+     * @param ms - Delay time in milliseconds
+     * @returns Promise that resolves after the delay
      */
     delay(ms) {
         return new Promise((resolve) => setTimeout(resolve, ms));
     }
     // Interceptor management methods
     /**
-     * Gets the interceptor manager for advanced request/response handling
+     * @category Interceptors
+     * @summary Gets the interceptor manager for advanced request/response handling
+     * @description Provides access to the internal interceptor manager for custom handling
      *
      * @returns InterceptorManager instance
      */
@@ -440,7 +673,9 @@ class HttpClient {
         return this.interceptors;
     }
     /**
-     * Adds a request interceptor
+     * @category Interceptors
+     * @summary Adds a request interceptor
+     * @description Registers a function to intercept and modify requests before they are sent
      *
      * @param interceptor - Request interceptor function
      * @returns Interceptor ID for removal
@@ -449,7 +684,9 @@ class HttpClient {
         return this.interceptors.addRequestInterceptor(interceptor);
     }
     /**
-     * Adds a response interceptor
+     * @category Interceptors
+     * @summary Adds a response interceptor
+     * @description Registers a function to intercept and modify responses before they are returned
      *
      * @param interceptor - Response interceptor function
      * @returns Interceptor ID for removal
@@ -458,7 +695,9 @@ class HttpClient {
         return this.interceptors.addResponseInterceptor(interceptor);
     }
     /**
-     * Adds an error interceptor
+     * @category Interceptors
+     * @summary Adds an error interceptor
+     * @description Registers a function to intercept and potentially recover from errors
      *
      * @param interceptor - Error interceptor function
      * @returns Interceptor ID for removal
@@ -468,43 +707,108 @@ class HttpClient {
     }
 }
 
-// Type Guards
+// TYPE GUARDS
+// Summary: Type guards for payment method validation
+// Description: Checks if a value matches the allowed payment method types
 /**
  * Type guard to check if a value is a valid PaymentMethod
+ *
+ * @summary Validates a value against supported payment methods
+ * @description Checks if provided value is a string and matches one of the supported payment methods
+ *
+ * @param value - The value to check
+ * @returns True if the value is a valid PaymentMethod, narrowing the type
  */
 function isPaymentMethod(value) {
     return (typeof value === "string" &&
         ["credit_card", "debit_card", "bank_transfer", "digital_wallet"].includes(value));
 }
+// CURRENCY VALIDATION
+// Summary: Type guard for currency validation
+// Description: Checks if a value matches the allowed currency types
 /**
  * Type guard to check if a value is a valid Currency
+ *
+ * @summary Validates a value against supported currencies
+ * @description Checks if provided value is a string and matches one of the supported currencies (TRY, USD, EUR, GBP)
+ *
+ * @param value - The value to check
+ * @returns True if the value is a valid Currency, narrowing the type
  */
 function isCurrency(value) {
     return (typeof value === "string" && ["TRY", "USD", "EUR", "GBP"].includes(value));
 }
+// STRING VALIDATION
+// Summary: Type guard for non-empty string validation
+// Description: Checks if a value is a string and contains non-whitespace characters
 /**
  * Type guard to check if a value is a non-empty string
+ *
+ * @summary Validates a value is a non-empty string
+ * @description Checks if provided value is of string type and contains at least one non-whitespace character
+ *
+ * @param value - The value to check
+ * @returns True if the value is a non-empty string, narrowing the type
  */
 function isNonEmptyString(value) {
     return typeof value === "string" && value.trim().length > 0;
 }
+// NUMBER VALIDATION
+// Summary: Type guard for positive number validation
+// Description: Checks if a value is a number greater than zero
 /**
  * Type guard to check if a value is a positive number
+ *
+ * @summary Validates a value is a positive number
+ * @description Checks if provided value is of number type, is greater than zero, and is not NaN or infinity
+ *
+ * @param value - The value to check
+ * @returns True if the value is a positive number, narrowing the type
  */
 function isPositiveNumber(value) {
     return (typeof value === "number" && value > 0 && !isNaN(value) && isFinite(value));
 }
+// INTEGER VALIDATION
+// Summary: Type guard for integer validation
+// Description: Checks if a value is an integer number
+/**
+ * Type guard to check if a value is an integer
+ *
+ * @summary Validates a value is an integer
+ * @description Checks if provided value is of number type and is an integer (no decimal places)
+ *
+ * @param value - The value to check
+ * @returns True if the value is an integer, narrowing the type
+ */
+function isInteger(value) {
+    return typeof value === "number" && Number.isInteger(value);
+}
+// DECIMAL PLACES VALIDATION
+// Summary: Validates that a number has maximum 2 decimal places
+// Description: Ensures monetary values have appropriate precision for currency operations
 /**
  * Type guard to check if amount has max 2 decimal places
+ *
+ * @summary Validates that a number has maximum 2 decimal places
+ * @description Ensures monetary values have appropriate precision for currency operations
+ *
+ * @param amount - The numeric amount to validate
+ * @returns True if the amount has 2 or fewer decimal places
  */
 function hasValidDecimalPlaces(amount) {
     const decimalPlaces = (amount.toString().split(".")[1] || "").length;
     return decimalPlaces <= 2;
 }
-// Validation Functions
+// VALIDATION FUNCTIONS
+// BEARER TOKEN VALIDATION
+// Summary: Validates authentication token format and security
+// Description: Checks token for required length, character set, and format constraints
 /**
  * Validates Bearer token format and strength
  *
+ * @summary Validates authentication token format and security
+ * @description Checks token for required length, character set, and format constraints
+ *
  * @param bearerToken - Bearer token to validate
  * @throws {TapsilatValidationError} When Bearer token is invalid
  */
@@ -515,14 +819,19 @@ function validateBearerToken(bearerToken) {
     if (bearerToken.length < 10) {
         throw new TapsilatValidationError("Bearer token must be at least 10 characters long");
     }
-    // Karakter kontrolü (opsiyonel, isterseniz ek kurallar koyabilirsiniz)
     if (!/^[a-zA-Z0-9._-]+$/.test(bearerToken)) {
         throw new TapsilatValidationError("Bearer token contains invalid characters");
     }
 }
+// PAYMENT REQUEST VALIDATION
+// Summary: Comprehensive validation of payment request data
+// Description: Validates all required and optional fields in a payment request for integrity and correctness
 /**
  * Validates payment request data comprehensively
  *
+ * @summary Comprehensive validation of payment request data
+ * @description Validates all required and optional fields in a payment request for integrity and correctness
+ *
  * @param request - Payment request to validate
  * @throws {TapsilatValidationError} When any field is invalid
  */
@@ -566,9 +875,15 @@ function validatePaymentRequest(request) {
         throw new TapsilatValidationError("Metadata must be an object when provided");
     }
 }
+// EMAIL FORMAT VALIDATION
+// Summary: Validates email address format with comprehensive regex
+// Description: Ensures email addresses conform to RFC standards with thorough pattern matching
 /**
  * Validates email format using robust regex
  *
+ * @summary Validates email address format with comprehensive regex
+ * @description Ensures email addresses conform to RFC standards with thorough pattern matching
+ *
  * @param email - Email address to validate
  * @returns True if email format is valid
  */
@@ -580,21 +895,45 @@ function validateEmail(email) {
     const emailRegex = /^[a-zA-Z0-9.!#$%&'*+/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$/;
     return emailRegex.test(email);
 }
+// DEPRECATED CURRENCY VALIDATION
+// Summary: Legacy currency validation function
+// Description: Maintained for backwards compatibility, redirects to the new type guard
 /**
  * @deprecated Use isCurrency type guard instead
+ *
+ * @summary Legacy currency validation function
+ * @description Maintained for backwards compatibility, redirects to the new type guard
+ *
+ * @param currency - Currency code to validate
+ * @returns True if currency is supported
  */
 function isValidCurrency(currency) {
     return isCurrency(currency);
 }
+// DEPRECATED PAYMENT METHOD VALIDATION
+// Summary: Legacy payment method validation function
+// Description: Maintained for backwards compatibility, redirects to the new type guard
 /**
  * @deprecated Use isPaymentMethod type guard instead
+ *
+ * @summary Legacy payment method validation function
+ * @description Maintained for backwards compatibility, redirects to the new type guard
+ *
+ * @param paymentMethod - Payment method to validate
+ * @returns True if payment method is supported
  */
 function isValidPaymentMethod(paymentMethod) {
     return isPaymentMethod(paymentMethod);
 }
+// URL FORMAT VALIDATION
+// Summary: Validates URL format and ensures proper protocol
+// Description: Checks that URLs are well-formed and use HTTP or HTTPS protocols for security
 /**
  * Validates URL format and protocol
  *
+ * @summary Validates URL format and ensures proper protocol
+ * @description Checks that URLs are well-formed and use HTTP or HTTPS protocols for security
+ *
  * @param url - URL to validate
  * @returns True if URL is valid HTTP/HTTPS
  */
@@ -610,9 +949,15 @@ function isValidUrl(url) {
         return false;
     }
 }
+// METADATA SANITIZATION
+// Summary: Removes sensitive data from metadata before processing
+// Description: Filters out security-sensitive keys and normalizes values for safe transmission
 /**
  * Sanitizes metadata by removing sensitive keys and cleaning values
  *
+ * @summary Removes sensitive data from metadata before processing
+ * @description Filters out security-sensitive keys and normalizes values for safe transmission
+ *
  * @param metadata - Raw metadata object
  * @returns Sanitized metadata object
  */
@@ -657,93 +1002,307 @@ function sanitizeMetadata(metadata) {
     return sanitized;
 }
 
+/**
+ * @category Configuration
+ * @summary Configuration management for Tapsilat SDK
+ * @description Handles SDK configuration updates, validation, and secure access to configuration data
+ * @class ConfigManager
+ */
+class ConfigManager {
+    config;
+    /**
+     * @summary Creates a new configuration manager
+     * @description Initializes the configuration manager with the provided configuration options
+     *
+     * @param config - Initial SDK configuration
+     */
+    constructor(config) {
+        this.config = { ...config }; // Create a copy to avoid external mutations
+    }
+    /**
+     * @category Configuration Access
+     * @summary Get current SDK configuration without sensitive information
+     * @description Returns a copy of the current configuration with sensitive data (like bearer token) excluded
+     *
+     * @returns Copy of current configuration without bearer token
+     */
+    getConfig() {
+        const { bearerToken, ...safeConfig } = this.config;
+        return {
+            ...safeConfig,
+            hasBearerToken: Boolean(bearerToken),
+        };
+    }
+    /**
+     * @category Configuration Management
+     * @summary Update SDK configuration with new values
+     * @description Updates the SDK configuration with provided values, validating bearer token if changed
+     *
+     * @param newConfig - Partial configuration to update
+     * @throws {TapsilatValidationError} When Bearer token is invalid
+     */
+    updateConfig(newConfig) {
+        if (newConfig.bearerToken) {
+            validateBearerToken(newConfig.bearerToken);
+        }
+        Object.assign(this.config, newConfig);
+    }
+    /**
+     * @category Internal
+     * @summary Gets the internal configuration for SDK use
+     * @description Returns a full copy of the configuration for internal SDK operations
+     *
+     * @internal
+     * @returns Full configuration including sensitive data
+     */
+    getInternalConfig() {
+        return { ...this.config }; // Return a copy to prevent external mutations
+    }
+    /**
+     * @category Authentication
+     * @summary Gets the bearer token for authentication
+     * @description Retrieves the configured bearer token for API authentication
+     *
+     * @internal
+     * @returns Bearer token
+     */
+    getBearerToken() {
+        return this.config.bearerToken;
+    }
+    /**
+     * @category Endpoints
+     * @summary Gets the base URL for API requests
+     * @description Retrieves the configured base URL for API endpoints
+     *
+     * @internal
+     * @returns API base URL
+     */
+    getBaseUrl() {
+        return this.config.baseURL;
+    }
+    /**
+     * @category Networking
+     * @summary Gets the request timeout value
+     * @description Retrieves the configured timeout value for API requests
+     *
+     * @internal
+     * @returns Request timeout in milliseconds
+     */
+    getTimeout() {
+        return this.config.timeout;
+    }
+}
+
+// EMAIL VALIDATION
+// Summary: Validates email format using basic regex pattern
+// Description: Ensures email addresses conform to standard format with username, @ symbol, and domain
+/**
+ * Validates email format using basic regex pattern
+ *
+ * @summary Validates email format using basic regex pattern
+ * @description Ensures email addresses conform to standard format with username, @ symbol, and domain
+ *
+ * @param email - Email address to validate
+ * @returns True if email matches required format, false otherwise
+ */
+const isValidEmail = (email) => {
+    const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+    return emailRegex.test(email);
+};
+// API RESPONSE HANDLING
+// Summary: Process API responses consistently across the SDK
+// Description: Validates response structure, extracts data or converts API errors to domain errors
+/**
+ * Generic response handler - consistent way to handle API responses
+ *
+ * @summary Process API responses consistently across the SDK
+ * @description Validates response structure, extracts data or converts API errors to domain errors
+ *
+ * @param response - The API response to process
+ * @param errorContext - Descriptive context for error messages
+ * @returns The data from a successful response
+ * @throws {TapsilatError} On any response error
+ */
+const handleResponse = (response, errorContext) => {
+    if (!response.success || !response.data) {
+        // Convert API errors to domain-specific errors
+        if (response.error) {
+            throw TapsilatError.fromAPIError(response.error);
+        }
+        throw new TapsilatError(`${errorContext} failed with no error details`, "UNKNOWN_ERROR");
+    }
+    return response.data;
+};
+// ERROR HANDLING
+// Summary: Centralized error handling for consistent error reporting
+// Description: Processes caught errors and ensures they are properly converted to TapsilatError types
+/**
+ * Generic error handler - consistent way to handle errors
+ *
+ * @summary Centralized error handling for consistent error reporting
+ * @description Processes caught errors and ensures they are properly converted to TapsilatError types
+ *
+ * @param error - The caught error to process
+ * @param errorContext - Descriptive context for error messages
+ * @throws {TapsilatError} Always throws an appropriate error type
+ */
+const handleError = (error, errorContext) => {
+    // Rethrow TapsilatErrors as-is
+    if (error instanceof TapsilatError) {
+        throw error;
+    }
+    // Convert generic errors to TapsilatNetworkError
+    throw new TapsilatNetworkError(error instanceof Error
+        ? error.message
+        : `Unknown error during ${errorContext}`, "NETWORK_ERROR");
+};
+// WEBHOOK SIGNATURE VERIFICATION
+// Summary: Security verification of webhook payloads using HMAC-SHA256
+// Description: Computes expected signature from payload and secret, compares with provided signature
+/**
+ * Verifies HMAC-SHA256 signature for webhook security
+ *
+ * @summary Security verification of webhook payloads using HMAC-SHA256
+ * @description Computes expected signature from payload and secret, compares with provided signature
+ *
+ * @param payload - Raw webhook payload string
+ * @param signature - Webhook signature from headers (should include "sha256=" prefix)
+ * @param secret - Your webhook secret key
+ * @returns true if signature is valid, false otherwise
+ */
+const verifyHmacSignature = (payload, signature, secret) => {
+    const expectedSignature = crypto
+        .createHmac("sha256", secret)
+        .update(payload)
+        .digest("hex");
+    return `sha256=${expectedSignature}` === signature;
+};
+
 /**
  * Main SDK class for Tapsilat payment operations
  *
- * @example
- * ```typescript
- * const tapsilat = new TapsilatSDK({
- *   bearerToken: 'your-bearer-token',
- *   baseURL: 'https://api.tapsilat.com/v1'
- * });
+ * @summary Enterprise-grade TypeScript SDK for Tapsilat Payment Processing Platform
+ * @description
+ * The TapsilatSDK class provides a comprehensive interface for integrating with the Tapsilat payment platform.
+ * It offers secure, efficient, and type-safe methods for managing orders, payments, refunds, and other
+ * payment-related operations. The SDK includes built-in error handling, request validation, retry logic,
+ * and comprehensive logging capabilities.
  *
- * const payment = await tapsilat.createPayment({
- *   amount: 100.50,
- *   currency: 'TRY',
- *   paymentMethod: 'credit_card'
- * });
- * ```
+ * Key features:
+ * - Type-safe API with TypeScript support
+ * - Built-in error handling with custom error types
+ * - Automatic request/response validation
+ * - Configurable retry mechanism
+ * - Full compliance with Tapsilat API specifications
  */
 class TapsilatSDK {
     httpClient;
-    config;
+    configManager;
+    // SDK INITIALIZATION
+    // Summary: Initializes the Tapsilat SDK with configuration options
+    // Description: Creates and configures a new instance of the TapsilatSDK with the provided configuration
     /**
      * Creates a new TapsilatSDK instance
      *
-     * @param config - SDK configuration options
-     * @throws {TapsilatValidationError} When Bearer token is invalid
+     * @summary Initializes the Tapsilat SDK with configuration options
+     * @description
+     * Creates and configures a new instance of the TapsilatSDK with the provided configuration.
+     * The constructor validates the bearer token, sets up the HTTP client with proper headers,
+     * configures retry mechanisms, and initializes internal state for API communication.
+     *
+     * The SDK instance is immutable after creation - configuration cannot be changed without
+     * creating a new instance. This ensures thread safety and predictable behavior.
+     *
+     * @param {TapsilatConfig} config - SDK configuration options
+     * @param {string} config.bearerToken - API authentication token (required)
+     * @param {string} [config.baseURL='https://api.tapsilat.com/v1'] - API base URL
+     * @param {number} [config.timeout=30000] - Request timeout in milliseconds
+     * @param {number} [config.maxRetries=3] - Maximum number of retry attempts
+     * @param {number} [config.retryDelay=1000] - Delay between retries in milliseconds
+     * @param {string} [config.version='v1'] - API version to use
+     * @param {boolean} [config.debug=false] - Enable debug logging
+     *
+     * @throws {TapsilatValidationError} When bearer token is invalid, missing, or malformed
+     * @throws {TypeError} When config parameter is not an object or missing required fields
      */
     constructor(config) {
         validateBearerToken(config.bearerToken);
-        this.config = config;
-        this.httpClient = new HttpClient(config);
+        this.configManager = new ConfigManager(config);
+        this.httpClient = new HttpClient(this.configManager.getInternalConfig());
     }
-    // Order Operations
+    // ORDER CREATION
+    // Summary: Create new payment order and get checkout URL
+    // Description: Initiates payment process with buyer info and returns secure checkout URL
     /**
-     * Creates a new order and returns a checkout URL.
+     * Creates a new order and returns a checkout URL
      *
-     * @param orderRequest - The order details including amount, currency, and buyer information
-     * @returns Promise resolving to the created order response including reference ID and checkout URL
-     * @throws {TapsilatValidationError} When order request data is invalid
-     * @throws {TapsilatNetworkError} When API request fails due to network issues
-     * @throws {TapsilatError} When API returns an error response
+     * @summary Initiates a new payment order with buyer information and generates checkout URL
+     * @description
+     * Creates a new payment order in the Tapsilat system with the provided order details.
+     * This method performs comprehensive validation of all input parameters, creates the order
+     * on the payment platform, and returns a checkout URL that customers can use to complete
+     * their payment. The method supports multiple currencies, locales, and comprehensive
+     * buyer information for compliance and fraud prevention.
      *
-     * @example
-     * ```typescript
-     * try {
-     *   const orderResponse = await tapsilat.createOrder({
-     *     amount: 100.50,
-     *     currency: 'TRY',
-     *     locale: 'en',
-     *     buyer: {
-     *       name: 'John',
-     *       surname: 'Doe',
-     *       email: 'john.doe@example.com'
-     *     }
-     *   });
-     *   console.log(`Checkout URL: ${orderResponse.checkoutUrl}`);
-     * } catch (error) {
-     *   console.error(`Order creation failed: ${error.message}`);
-     * }
-     * ```
+     * The returned checkout URL is valid for a limited time (typically 24 hours) and should
+     * be presented to the customer immediately. The order status can be tracked using the
+     * returned reference ID through the getOrderStatus method.
+     *
+     * @param {OrderCreateRequest} orderRequest - Complete order information
+     * @param {number} orderRequest.amount - Payment amount (must be positive, max 2 decimal places)
+     * @param {Currency} orderRequest.currency - Payment currency ('TRY', 'USD', 'EUR', 'GBP')
+     * @param {Locale} orderRequest.locale - Display language ('tr' for Turkish, 'en' for English)
+     * @param {Buyer} orderRequest.buyer - Customer information for payment processing
+     * @param {string} orderRequest.buyer.name - Customer's first name (required)
+     * @param {string} orderRequest.buyer.surname - Customer's last name (required)
+     * @param {string} orderRequest.buyer.email - Customer's email address (required, validated)
+     * @param {string} [orderRequest.buyer.phone] - Customer's phone number
+     * @param {string} [orderRequest.buyer.identityNumber] - National ID or tax number
+     * @param {Address} [orderRequest.buyer.shippingAddress] - Shipping address for physical goods
+     * @param {Address} [orderRequest.buyer.billingAddress] - Billing address for invoicing
+     * @param {string} [orderRequest.description] - Order description for customer reference
+     * @param {string} [orderRequest.callbackUrl] - URL to redirect after payment completion
+     * @param {string} [orderRequest.conversationId] - Custom tracking ID for your system
+     * @param {Record<string, unknown>} [orderRequest.metadata] - Additional custom data
+     *
+     * @returns {Promise<OrderCreateResponse>} Promise resolving to order creation response
+     * @returns {string} OrderCreateResponse.referenceId - Unique order identifier for tracking
+     * @returns {string} OrderCreateResponse.conversationId - Echo of provided conversation ID
+     * @returns {string} OrderCreateResponse.checkoutUrl - Payment page URL for customer
+     * @returns {string} OrderCreateResponse.status - Initial order status (typically 'CREATED')
+     * @returns {string} [OrderCreateResponse.qrCodeUrl] - QR code URL for mobile payments
+     *
+     * @throws {TapsilatValidationError} When input validation fails:
+     *   - Amount is not positive or has more than 2 decimal places
+     *   - Currency is not supported
+     *   - Buyer information is incomplete or invalid
+     *   - Email format is invalid
+     *   - Required fields are missing
+     * @throws {TapsilatNetworkError} When network request fails:
+     *   - Connection timeout
+     *   - DNS resolution failure
+     *   - Network connectivity issues
+     * @throws {TapsilatError} When API returns business logic errors:
+     *   - Insufficient merchant balance
+     *   - Currency not enabled for merchant
+     *   - Buyer blocked due to fraud detection
+     *   - Rate limiting exceeded
      */
     async createOrder(orderRequest) {
-        // Validate the order request
-        this.validateOrderRequest(orderRequest);
-        try {
-            // Make the API request
-            const response = await this.httpClient.post("/order/create", orderRequest);
-            // Use our generic response handler
-            return this.handleResponse(response, "Order creation");
-        }
-        catch (error) {
-            // Use our generic error handler
-            this.handleError(error, "order creation");
-        }
-    }
-    /**
-     * Validates an order request object
-     * @private
-     */
-    validateOrderRequest(orderRequest) {
+        // Validate the order request directly
         // Check if request is null/undefined
         if (!orderRequest) {
             throw new TapsilatValidationError("Order request cannot be null or undefined");
         }
-        // Validate amount
-        if (!isPositiveNumber(orderRequest.amount) ||
-            !hasValidDecimalPlaces(orderRequest.amount)) {
-            throw new TapsilatValidationError("Amount must be a positive number with maximum 2 decimal places", { provided: orderRequest.amount });
+        // Validate amount - check if positive
+        if (!isPositiveNumber(orderRequest.amount)) {
+            throw new TapsilatValidationError("Amount must be a positive number", {
+                provided: orderRequest.amount,
+            });
+        }
+        // Validate amount - check decimal places
+        if (!hasValidDecimalPlaces(orderRequest.amount)) {
+            throw new TapsilatValidationError("Amount must have maximum 2 decimal places", { provided: orderRequest.amount });
         }
         // Validate currency
         if (!isNonEmptyString(orderRequest.currency)) {
@@ -760,73 +1319,39 @@ class TapsilatSDK {
         if (!isNonEmptyString(buyer.surname)) {
             throw new TapsilatValidationError("Buyer surname is required and must be a non-empty string", { provided: buyer.surname });
         }
-        if (!isNonEmptyString(buyer.email) || !this.isValidEmail(buyer.email)) {
-            throw new TapsilatValidationError("Buyer email is required and must be a valid email address", { provided: buyer.email });
+        // Validate buyer email - check if provided
+        if (!isNonEmptyString(buyer.email)) {
+            throw new TapsilatValidationError("Buyer email is required and must be a non-empty string", { provided: buyer.email });
         }
-    }
-    /**
-     * Basic email validation
-     * @private
-     */
-    isValidEmail(email) {
-        const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
-        return emailRegex.test(email);
-    }
-    /**
-     * Generic response handler - consistent way to handle API responses across SDK methods
-     * @private
-     *
-     * @param response - The API response to process
-     * @param errorContext - Descriptive context for error messages
-     * @returns The data from a successful response
-     * @throws {TapsilatError} On any response error
-     */
-    handleResponse(response, errorContext) {
-        if (!response.success || !response.data) {
-            // Convert API errors to domain-specific errors
-            if (response.error) {
-                throw TapsilatError.fromAPIError(response.error);
-            }
-            throw new TapsilatError(`${errorContext} failed with no error details`, "UNKNOWN_ERROR");
+        // Validate buyer email - check format
+        if (!isValidEmail(buyer.email)) {
+            throw new TapsilatValidationError("Buyer email must be a valid email address", { provided: buyer.email });
         }
-        return response.data;
-    }
-    /**
-     * Generic error handler - consistent way to handle errors across SDK methods
-     * @private
-     *
-     * @param error - The caught error to process
-     * @param errorContext - Descriptive context for error messages
-     * @throws {TapsilatError} Always throws an appropriate error type
-     */
-    handleError(error, errorContext) {
-        // Rethrow TapsilatErrors as-is
-        if (error instanceof TapsilatError) {
-            throw error;
+        try {
+            // Make the API request
+            const createOrderResponse = await this.httpClient.post("/order/create", orderRequest);
+            // Use our generic response handler
+            return handleResponse(createOrderResponse, "Order creation");
+        }
+        catch (error) {
+            // Use our generic error handler
+            return handleError(error, "order creation");
         }
-        // Convert generic errors to TapsilatNetworkError
-        throw new TapsilatNetworkError(error instanceof Error
-            ? error.message
-            : `Unknown error during ${errorContext}`, "NETWORK_ERROR");
     }
+    // ORDER RETRIEVAL BY REFERENCE ID
+    // Summary: Get complete order details and information
+    // Description: Retrieves full order data including buyer info, amounts, and current status
     /**
      * Gets an order by reference ID.
      *
+     * @summary Retrieve complete order details and information
+     * @description Gets complete order data including buyer info, amounts, and current status using the unique reference ID.
+     *
      * @param referenceId - The unique reference ID of the order
      * @returns Promise resolving to the complete order details
      * @throws {TapsilatValidationError} When referenceId is invalid
      * @throws {TapsilatNetworkError} When API request fails due to network issues
      * @throws {TapsilatError} When API returns an error response
-     *
-     * @example
-     * ```typescript
-     * try {
-     *   const order = await tapsilat.getOrder("ord_123456789");
-     *   console.log(`Order amount: ${order.amount} ${order.currency}`);
-     * } catch (error) {
-     *   console.error(`Failed to get order: ${error.message}`);
-     * }
-     * ```
      */
     async getOrder(referenceId) {
         // Validate input
@@ -835,95 +1360,137 @@ class TapsilatSDK {
         }
         try {
             // Make the API request
-            const response = await this.httpClient.get(`/order/${referenceId}`);
+            const getOrderResponse = await this.httpClient.get(`/order/${referenceId}`);
             // Use our generic response handler
-            return this.handleResponse(response, "Order retrieval");
+            return handleResponse(getOrderResponse, "Order retrieval");
         }
         catch (error) {
             // Use our generic error handler
-            this.handleError(error, "order retrieval");
+            return handleError(error, "order retrieval");
         }
     }
+    // ORDER LISTING WITH PAGINATION
+    // Summary: Retrieve paginated list of merchant orders
+    // Description: Gets orders with pagination support, filtering, and sorting options
     /**
      * Lists orders with pagination support.
      *
+     * @summary Retrieve paginated list of merchant orders
+     * @description Gets orders with pagination support, filtering, and sorting options.
+     *
      * @param params - Optional pagination parameters (page number and items per page)
      * @returns Promise resolving to paginated list of orders
      * @throws {TapsilatNetworkError} When API request fails due to network issues
      * @throws {TapsilatError} When API returns an error response
-     *
-     * @example
-     * ```typescript
-     * try {
-     *   // Get the second page with 20 items per page
-     *   const orderList = await tapsilat.getOrders({ page: 2, per_page: 20 });
-     *   console.log(`Total orders: ${orderList.total}`);
-     *   orderList.rows.forEach(order => {
-     *     console.log(`Order ${order.referenceId}: ${order.amount} ${order.currency}`);
-     *   });
-     * } catch (error) {
-     *   console.error(`Failed to list orders: ${error.message}`);
-     * }
-     * ```
      */
     async getOrders(params = {}) {
         try {
             // Validate pagination parameters if provided
-            if (params.page !== undefined &&
-                (!Number.isInteger(params.page) || params.page < 1)) {
-                throw new TapsilatValidationError("Page number must be a positive integer", { provided: params.page });
+            // Check if page is defined
+            if (params.page !== undefined) {
+                // Check if page is integer
+                if (!isInteger(params.page)) {
+                    throw new TapsilatValidationError("Page number must be an integer", {
+                        provided: params.page,
+                    });
+                }
+                // Check if page is positive
+                if (params.page < 1) {
+                    throw new TapsilatValidationError("Page number must be greater than 0", { provided: params.page });
+                }
             }
-            if (params.per_page !== undefined &&
-                (!Number.isInteger(params.per_page) || params.per_page < 1)) {
-                throw new TapsilatValidationError("Items per page must be a positive integer", { provided: params.per_page });
+            // Check if per_page is defined
+            if (params.per_page !== undefined) {
+                // Check if per_page is integer
+                if (!isInteger(params.per_page)) {
+                    throw new TapsilatValidationError("Items per page must be an integer", { provided: params.per_page });
+                }
+                // Check if per_page is positive
+                if (params.per_page < 1) {
+                    throw new TapsilatValidationError("Items per page must be greater than 0", { provided: params.per_page });
+                }
             }
             // Make the API request
-            const response = await this.httpClient.get("/order/list", { params: params });
+            const getOrdersResponse = await this.httpClient.get("/order/list", { params: params });
             // Use our generic response handler
-            return this.handleResponse(response, "Order listing");
+            return handleResponse(getOrdersResponse, "Order listing");
         }
         catch (error) {
             // Use our generic error handler
-            this.handleError(error, "order listing");
+            return handleError(error, "order listing");
         }
     }
+    // ORDER CANCELLATION
+    // Summary: Cancel a pending order before payment completion
+    // Description: Cancels unpaid order and prevents further payment processing
     /**
      * Cancels an order by reference_id.
+     *
+     * @summary Cancel a pending order before payment completion
+     * @description Cancels unpaid order and prevents further payment processing.
+     *
+     * @param referenceId - The unique reference ID of the order to cancel
+     * @returns Promise resolving to the canceled order details
+     * @throws {TapsilatValidationError} When referenceId is invalid
+     * @throws {TapsilatError} When API returns an error response or order cannot be canceled
      */
     async cancelOrder(referenceId) {
-        if (!referenceId) {
-            throw new Error("Order referenceId is required for cancellation");
+        // Validate referenceId
+        if (!isNonEmptyString(referenceId)) {
+            throw new TapsilatValidationError("Order referenceId is required and must be a non-empty string", { provided: referenceId });
         }
-        const response = await this.httpClient.post("/order/cancel", {
+        const cancelOrderResponse = await this.httpClient.post("/order/cancel", {
             reference_id: referenceId,
         });
-        if (!response.success || !response.data) {
-            throw new Error(response.error?.message || "Order cancellation failed");
+        // Check if API call was successful
+        if (!cancelOrderResponse.success) {
+            throw new TapsilatError(cancelOrderResponse.error?.message ||
+                "Order cancellation API call failed", cancelOrderResponse.error?.code || "CANCELLATION_API_FAILED");
+        }
+        // Check if response data exists
+        if (!cancelOrderResponse.data) {
+            throw new TapsilatError("Order cancellation response data is missing", "CANCELLATION_DATA_MISSING");
         }
-        return response.data;
+        return cancelOrderResponse.data;
     }
+    // ORDER STATUS RETRIEVAL
+    // Summary: Retrieves real-time payment status and tracking information for a specific order
+    // Description: Queries the payment platform to retrieve current status of an order using its reference ID
     /**
-     * Gets the status of an order by reference ID.
+     * Gets the current status of an order by reference ID
      *
-     * @param referenceId - The unique reference ID of the order
-     * @returns Promise resolving to the current order status, including status code and last update time
-     * @throws {TapsilatValidationError} When referenceId is invalid
-     * @throws {TapsilatNetworkError} When API request fails due to network issues
-     * @throws {TapsilatError} When API returns an error response
+     * @summary Retrieves real-time payment status and tracking information for a specific order
+     * @description
+     * Queries the Tapsilat payment platform to retrieve the current status of an order using its
+     * unique reference ID. This method provides real-time information about payment progress,
+     * completion status, and last update timestamp. It's essential for tracking payment flow
+     * and implementing proper order state management in your application.
      *
-     * @example
-     * ```typescript
-     * try {
-     *   const orderStatus = await tapsilat.getOrderStatus("ord_123456789");
-     *   console.log(`Order status: ${orderStatus.status}`);
-     * } catch (error) {
-     *   if (error instanceof TapsilatValidationError) {
-     *     console.error("Invalid reference ID format");
-     *   } else if (error instanceof TapsilatError) {
-     *     console.error(`API error: ${error.message}`);
-     *   }
-     * }
-     * ```
+     * The status information includes payment state (CREATED, PENDING_PAYMENT, COMPLETED, CANCELLED),
+     * last update timestamp, and any relevant status metadata. This method should be used to:
+     * - Check if a payment has been completed after redirecting from checkout
+     * - Monitor payment status for pending transactions
+     * - Verify order state before fulfilling goods/services
+     * - Implement webhook verification and status synchronization
+     *
+     * @param {string} referenceId - Unique order reference identifier from order creation
+     *
+     * @returns {Promise<OrderStatusResponse>} Promise resolving to current order status information
+     * @returns {string} OrderStatusResponse.referenceId - Echo of the provided reference ID
+     * @returns {string} OrderStatusResponse.status - Current payment status (CREATED, PENDING_PAYMENT, COMPLETED, CANCELLED, FAILED)
+     * @returns {string} OrderStatusResponse.lastUpdatedAt - ISO 8601 timestamp of last status change
+     *
+     * @throws {TapsilatValidationError} When input validation fails:
+     *   - Reference ID is null, undefined, or empty string
+     *   - Reference ID format is invalid (should match order ID pattern)
+     * @throws {TapsilatNetworkError} When network request fails:
+     *   - Connection timeout during status check
+     *   - DNS resolution failure
+     *   - Network connectivity issues
+     * @throws {TapsilatError} When API returns business logic errors:
+     *   - ORDER_NOT_FOUND: Order with given reference ID doesn't exist
+     *   - ACCESS_DENIED: Order belongs to different merchant
+     *   - RATE_LIMIT_EXCEEDED: Too many status check requests
      */
     async getOrderStatus(referenceId) {
         // Validate input using proper validation
@@ -932,187 +1499,274 @@ class TapsilatSDK {
         }
         try {
             // Make the API request
-            const response = await this.httpClient.get(`/order/${referenceId}/status`);
+            const getOrderStatusResponse = await this.httpClient.get(`/order/${referenceId}/status`);
             // Use our generic response handler
-            return this.handleResponse(response, "Order status retrieval");
+            return handleResponse(getOrderStatusResponse, "Order status retrieval");
         }
         catch (error) {
             // Use our generic error handler
-            this.handleError(error, "order status retrieval");
+            return handleError(error, "order status retrieval");
         }
     }
+    // ORDER REFUND OPERATIONS
+    // Summary: Process partial refund for a completed order
+    // Description: Refunds specified amount from a paid order and returns transaction details
     /**
      * Partially refunds an order.
      * Based on `refund_order` from the Python SDK.
      *
+     * @summary Process partial refund for a completed order
+     * @description Refunds specified amount from a paid order and returns transaction details.
+     *
      * @param refundData - The refund details, including referenceId and amount.
      * @returns Promise resolving to the refund transaction details.
+     * @throws {TapsilatError} When API returns an error response or refund fails
      */
     async refundOrder(refundData) {
-        const response = await this.httpClient.post("/order/refund", refundData);
-        if (!response.success || !response.data) {
-            throw new Error(response.error?.message || "Order refund failed");
+        const refundOrderResponse = await this.httpClient.post("/order/refund", refundData);
+        if (!refundOrderResponse.success) {
+            throw new TapsilatError(refundOrderResponse.error?.message || "Order refund failed", refundOrderResponse.error?.code || "REFUND_FAILED");
         }
-        return response.data;
+        if (!refundOrderResponse.data) {
+            throw new TapsilatError("Order refund response data is missing", "REFUND_DATA_MISSING");
+        }
+        return refundOrderResponse.data;
     }
+    // ORDER FULL REFUND OPERATIONS
+    // Summary: Process full refund for a completed order
+    // Description: Refunds entire order amount and returns transaction details
     /**
      * Fully refunds an order by its reference ID.
      * Based on `refund_all_order` from the Python SDK.
      *
+     * @summary Process full refund for a completed order
+     * @description Refunds entire order amount and returns transaction details.
+     *
      * @param referenceId - The unique identifier of the order to fully refund.
      * @returns Promise resolving to the refund transaction details.
+     * @throws {TapsilatError} When API returns an error response or full refund fails
      */
     async refundAllOrder(referenceId) {
-        const response = await this.httpClient.post("/order/refund-all", { reference_id: referenceId });
-        if (!response.success || !response.data) {
-            throw new Error(response.error?.message || "Full order refund failed");
+        const refundAllOrderResponse = await this.httpClient.post("/order/refund-all", {
+            reference_id: referenceId,
+        });
+        if (!refundAllOrderResponse.success) {
+            throw new TapsilatError(refundAllOrderResponse.error?.message || "Full order refund failed", refundAllOrderResponse.error?.code || "FULL_REFUND_FAILED");
+        }
+        if (!refundAllOrderResponse.data) {
+            throw new TapsilatError("Full order refund response data is missing", "FULL_REFUND_DATA_MISSING");
         }
-        return response.data;
+        return refundAllOrderResponse.data;
     }
+    // ORDER PAYMENT DETAILS
+    // Summary: Retrieve detailed payment transaction information for an order
+    // Description: Gets payment method, amount, status, and card info for order transactions
     /**
      * Retrieves the payment details for an order.
      * Based on `get_order_payment_details` from the Python SDK.
      *
+     * @summary Retrieve detailed payment transaction information for an order
+     * @description Gets payment method, amount, status, and card info for order transactions.
+     *
      * @param referenceId - The unique identifier of the order.
      * @param conversationId - Optional conversation ID for more specific querying.
      * @returns Promise resolving to a list of payment details.
+     * @throws {TapsilatValidationError} When referenceId is invalid
+     * @throws {TapsilatError} When API returns an error response or payment details are missing
      */
     async getOrderPaymentDetails(referenceId, conversationId) {
-        if (conversationId) {
-            // If conversation_id is provided, use POST to /order/payment-details
-            const response = await this.httpClient.post("/order/payment-details", { conversation_id: conversationId, reference_id: referenceId });
-            if (!response.success || !response.data) {
-                throw new Error(response.error?.message || "Failed to get payment details");
-            }
-            return response.data;
-        }
-        else {
-            // If no conversation_id, use GET to /order/{reference_id}/payment-details
-            const response = await this.httpClient.get(`/order/${referenceId}/payment-details`);
-            if (!response.success || !response.data) {
-                throw new Error(response.error?.message || "Failed to get payment details");
-            }
-            return response.data;
-        }
-    }
+        if (!isNonEmptyString(referenceId))
+            throw new TapsilatValidationError("Reference ID is required and must be a non-empty string");
+        const getOrderPaymentDetailsResponse = conversationId
+            ? await this.httpClient.post("/order/payment-details", {
+                conversation_id: conversationId,
+            })
+            : await this.httpClient.get(`/order/${referenceId}/payment-details`);
+        if (!getOrderPaymentDetailsResponse.success)
+            throw new TapsilatError(getOrderPaymentDetailsResponse.error?.message ||
+                "Payment details API call failed", getOrderPaymentDetailsResponse.error?.code ||
+                "PAYMENT_DETAILS_API_FAILED");
+        if (!getOrderPaymentDetailsResponse.data)
+            throw new TapsilatError("Payment details response data is missing", "PAYMENT_DETAILS_DATA_MISSING");
+        return getOrderPaymentDetailsResponse.data;
+    }
+    // ORDER LOOKUP BY CONVERSATION ID
+    // Summary: Find order using conversation ID instead of reference ID
+    // Description: Alternative lookup method for orders using custom conversation identifier
     /**
      * Gets an order by conversation_id.
      * Based on `get_order_by_conversation_id` from the Python SDK.
+     *
+     * @summary Find order using conversation ID instead of reference ID
+     * @description Alternative lookup method for orders using custom conversation identifier.
+     *
+     * @param conversationId - The custom conversation identifier used when creating the order
+     * @returns Promise resolving to the complete order details
+     * @throws {TapsilatValidationError} When conversationId is invalid
+     * @throws {TapsilatError} When API returns an error response
      */
     async getOrderByConversationId(conversationId) {
-        if (!conversationId) {
-            throw new Error("Order conversationId is required");
-        }
-        const response = await this.httpClient.get(`/order/conversation/${conversationId}`);
-        if (!response.success || !response.data) {
-            throw new Error(response.error?.message || "Order retrieval by conversation ID failed");
+        // Validate conversationId
+        if (!isNonEmptyString(conversationId)) {
+            throw new TapsilatValidationError("Order conversationId is required and must be a non-empty string", { provided: conversationId });
         }
-        return response.data;
-    }
+        const getOrderByConversationIdResponse = await this.httpClient.get(`/order/conversation/${conversationId}`);
+        if (!getOrderByConversationIdResponse.success)
+            throw new TapsilatError(getOrderByConversationIdResponse.error?.message ||
+                "Order retrieval by conversation ID failed", getOrderByConversationIdResponse.error?.code || "ORDER_RETRIEVAL_FAILED");
+        if (!getOrderByConversationIdResponse.data)
+            throw new TapsilatError("Order response data is missing", "ORDER_DATA_MISSING");
+        return getOrderByConversationIdResponse.data;
+    }
+    // ORDER TRANSACTION HISTORY
+    // Summary: Retrieve transaction history for an order
+    // Description: Gets detailed transaction records and payment attempts for a specific order
     /**
      * Gets order transactions by reference_id.
      * Based on `get_order_transactions` from the Python SDK.
+     *
+     * @summary Retrieve transaction history for an order
+     * @description Gets detailed transaction records and payment attempts for a specific order.
+     *
+     * @param referenceId - The unique reference ID of the order
+     * @returns Promise resolving to array of transaction records
+     * @throws {TapsilatValidationError} When referenceId is invalid
+     * @throws {TapsilatError} When API returns an error response
      */
     async getOrderTransactions(referenceId) {
-        if (!referenceId) {
-            throw new Error("Order referenceId is required");
-        }
-        const response = await this.httpClient.get(`/order/${referenceId}/transactions`);
-        if (!response.success || !response.data) {
-            throw new Error(response.error?.message || "Order transactions retrieval failed");
+        // Validate referenceId
+        if (!isNonEmptyString(referenceId)) {
+            throw new TapsilatValidationError("Order referenceId is required and must be a non-empty string", { provided: referenceId });
         }
-        return response.data;
-    }
+        const getOrderTransactionsResponse = await this.httpClient.get(`/order/${referenceId}/transactions`);
+        if (!getOrderTransactionsResponse.success)
+            throw new TapsilatError(getOrderTransactionsResponse.error?.message ||
+                "Order transactions retrieval failed", getOrderTransactionsResponse.error?.code ||
+                "TRANSACTIONS_RETRIEVAL_FAILED");
+        if (!getOrderTransactionsResponse.data)
+            throw new TapsilatError("Order transactions response data is missing", "TRANSACTIONS_DATA_MISSING");
+        return getOrderTransactionsResponse.data;
+    }
+    // ORDER SUBMERCHANT LISTING
+    // Summary: Retrieve paginated list of submerchants for orders
+    // Description: Gets submerchant information with pagination support for order management
     /**
      * Gets order submerchants with pagination.
      * Based on `get_order_submerchants` from the Python SDK.
+     *
+     * @summary Retrieve paginated list of submerchants for orders
+     * @description Gets submerchant information with pagination support for order management.
+     *
+     * @param params - Optional pagination parameters (page number and items per page)
+     * @returns Promise resolving to paginated list of submerchants
+     * @throws {TapsilatError} When API returns an error response
      */
     async getOrderSubmerchants(params = {}) {
-        const response = await this.httpClient.get("/order/submerchants", {
+        const getOrderSubmerchantsResponse = await this.httpClient.get("/order/submerchants", {
             params: params,
         });
-        if (!response.success || !response.data) {
-            throw new Error(response.error?.message || "Order submerchants retrieval failed");
-        }
-        return response.data;
-    }
+        if (!getOrderSubmerchantsResponse.success)
+            throw new TapsilatError(getOrderSubmerchantsResponse.error?.message ||
+                "Order submerchants retrieval failed", getOrderSubmerchantsResponse.error?.code ||
+                "SUBMERCHANTS_RETRIEVAL_FAILED");
+        if (!getOrderSubmerchantsResponse.data)
+            throw new TapsilatError("Order submerchants response data is missing", "SUBMERCHANTS_DATA_MISSING");
+        return getOrderSubmerchantsResponse.data;
+    }
+    // ORDER CHECKOUT URL RETRIEVAL
+    // Summary: Retrieve checkout URL for existing order
+    // Description: Gets the payment checkout URL for an existing order using reference ID
     /**
      * Gets checkout URL for an order.
      * Based on `get_checkout_url` from the Python SDK.
+     *
+     * @summary Retrieve checkout URL for existing order
+     * @description Gets the payment checkout URL for an existing order using reference ID.
+     *
+     * @param referenceId - The unique reference ID of the order
+     * @returns Promise resolving to the checkout URL string
+     * @throws {TapsilatError} When checkout URL is not found in order response
      */
     async getCheckoutUrl(referenceId) {
         const order = await this.getOrder(referenceId);
         if (order && order.checkout_url) {
             return order.checkout_url;
         }
-        throw new Error("Checkout URL not found in order response");
+        throw new TapsilatError("Checkout URL not found in order response", "CHECKOUT_URL_NOT_FOUND");
     }
-    // Utility Methods
+    // WEBHOOK SIGNATURE VERIFICATION
+    // Summary: Validate webhook signature for security verification
+    // Description: Verifies the authenticity of webhook payloads using HMAC signature validation
     /**
      * Verifies webhook signature for security
      *
+     * @summary Validate webhook signature for security verification
+     * @description Verifies the authenticity of webhook payloads using HMAC signature validation.
+     *
      * @param payload - Raw webhook payload string
      * @param signature - Webhook signature from headers
      * @param secret - Your webhook secret key
      * @returns Promise resolving to true if signature is valid
-     *
-     * @example
-     * ```typescript
-     * const isValid = await sdk.verifyWebhook(
-     *   JSON.stringify(req.body),
-     *   req.headers['x-tapsilat-signature'],
-     *   'your-webhook-secret'
-     * );
-     * ```
+     * @throws {TapsilatValidationError} When input validation fails for payload, signature or secret
      */
     async verifyWebhook(payload, signature, secret) {
-        // Implementation would depend on your webhook signature verification method
-        // This is a placeholder implementation
-        const crypto = await import('crypto');
-        const expectedSignature = crypto
-            .createHmac("sha256", secret)
-            .update(payload)
-            .digest("hex");
-        return `sha256=${expectedSignature}` === signature;
-    }
+        if (!isNonEmptyString(payload))
+            throw new TapsilatValidationError("Webhook payload is required and must be a non-empty string");
+        if (!isNonEmptyString(signature))
+            throw new TapsilatValidationError("Webhook signature is required and must be a non-empty string");
+        if (!isNonEmptyString(secret))
+            throw new TapsilatValidationError("Webhook secret is required and must be a non-empty string");
+        return verifyHmacSignature(payload, signature, secret);
+    }
+    // API HEALTH STATUS CHECK
+    // Summary: Check API service health and availability
+    // Description: Verifies that the Tapsilat API service is operational and accessible
     /**
      * Checks API service health and availability
      *
-     * @returns Promise resolving to service status
+     * @summary Check API service health and availability
+     * @description Verifies that the Tapsilat API service is operational and accessible.
+     *
+     * @returns Promise resolving to service status with status string and timestamp
+     * @throws {TapsilatError} When API health check fails or returns invalid data
      */
     async healthCheck() {
-        const response = await this.httpClient.get("/health");
-        if (!response.success || !response.data) {
-            throw new Error(response.error?.message || "Health check failed");
-        }
-        return response.data;
-    }
-    // Configuration methods
+        const healthCheckResponse = await this.httpClient.get("/health");
+        if (!healthCheckResponse.success)
+            throw new TapsilatError(healthCheckResponse.error?.message || "Health check failed", healthCheckResponse.error?.code || "HEALTH_CHECK_FAILED");
+        if (!healthCheckResponse.data)
+            throw new TapsilatError("Health check response data is missing", "HEALTH_CHECK_DATA_MISSING");
+        return healthCheckResponse.data;
+    }
+    // CONFIGURATION MANAGEMENT
+    // Summary: Access to the configuration manager for advanced configuration management
+    // Description: Provides direct access to the ConfigManager instance for configuration operations
     /**
-     * Gets current SDK configuration (without sensitive data)
+     * Gets the configuration manager instance
      *
-     * @returns Copy of current configuration
-     */
-    getConfig() {
-        const { bearerToken, ...safeConfig } = this.config;
-        return {
-            ...safeConfig,
-            hasBearerToken: Boolean(bearerToken),
-        };
-    }
-    /**
-     * Updates SDK configuration
+     * @summary Access to the configuration manager for advanced configuration management
+     * @description
+     * Provides direct access to the ConfigManager instance for configuration operations.
+     * Use this to get, update, or manage SDK configuration settings.
      *
-     * @param newConfig - Partial configuration to update
-     * @throws {TapsilatValidationError} When Bearer token is invalid
+     * @example
+     * ```typescript
+     * const sdk = new TapsilatSDK(config);
+     * const configManager = sdk.getConfigManager();
+     *
+     * // Get config (without sensitive data)
+     * console.log(configManager.getConfig());
+     *
+     * // Update config
+     * configManager.updateConfig({ timeout: 60000 });
+     * ```
+     *
+     * @returns ConfigManager instance for configuration operations
      */
-    updateConfig(newConfig) {
-        if (newConfig.bearerToken) {
-            validateBearerToken(newConfig.bearerToken);
-        }
-        Object.assign(this.config, newConfig);
+    getConfigManager() {
+        return this.configManager;
     }
 }
 
-export { TapsilatAuthenticationError, TapsilatError, TapsilatNetworkError, TapsilatRateLimitError, TapsilatSDK, TapsilatValidationError, isValidCurrency, isValidPaymentMethod, isValidUrl, sanitizeMetadata, validateEmail, validatePaymentRequest };
+export { ConfigManager, TapsilatAuthenticationError, TapsilatError, TapsilatNetworkError, TapsilatRateLimitError, TapsilatSDK, TapsilatValidationError, isValidCurrency, isValidPaymentMethod, isValidUrl, sanitizeMetadata, validateEmail, validatePaymentRequest };
 //# sourceMappingURL=index.esm.js.map