@tapsilat/tapsilat-js 1.0.3 → 1.0.4

package/dist/index.d.ts

@@ -1,3 +1,13 @@
+/**
+ * @module Types
+ * @description Tapsilat SDK type definitions, interfaces, and API data structures
+ */
+/**
+ * @category Configuration
+ * @summary Core configuration options for the Tapsilat SDK
+ * @description Defines the settings used to initialize and configure SDK behavior including API connection parameters and retry logic
+ * @interface TapsilatConfig
+ */
 interface TapsilatConfig {
     bearerToken: string;
     baseURL?: string;
@@ -7,118 +17,226 @@ interface TapsilatConfig {
     version?: string;
     debug?: boolean;
 }
-interface APIResponse<T> {
-    success: boolean;
-    data?: T;
-    error?: {
-        message: string;
-        code: string;
-        details?: any;
-    };
-    status?: number;
-    headers?: Record<string, string>;
-}
-interface APIError {
-    message: string;
-    code: string;
-    details?: Record<string, any>;
-}
+/**
+ * @category Payment Processing
+ * @summary Supported payment method types in the Tapsilat system
+ * @description Defines all available payment options that customers can use during checkout
+ * @typedef {string} PaymentMethod
+ */
+type PaymentMethod = "credit_card" | "debit_card" | "bank_transfer" | "digital_wallet" | "crypto";
+/**
+ * @category Payment Processing
+ * @summary Possible states of a payment throughout its lifecycle
+ * @description Defines all states a payment can be in from creation to completion or failure
+ * @typedef {string} PaymentStatus
+ */
+type PaymentStatus = "pending" | "processing" | "completed" | "failed" | "cancelled" | "refunded";
+/**
+ * @category Payment Processing
+ * @summary Supported currency codes for transactions
+ * @description ISO currency codes supported by the payment processing system
+ * @typedef {string} Currency
+ */
 type Currency = "TRY" | "USD" | "EUR" | "GBP";
-type PaymentMethod = "credit_card" | "debit_card" | "bank_transfer" | "digital_wallet";
-type PaymentStatus = "pending" | "completed" | "failed" | "cancelled" | "refunded";
+/**
+ * @category Payment Processing
+ * @summary Data required to initiate a payment transaction
+ * @description Contains required and optional fields for creating a new payment request including amount, currency, and payment method
+ * @interface PaymentRequest
+ */
 interface PaymentRequest {
     amount: number;
     currency: Currency;
     paymentMethod: PaymentMethod;
     description?: string;
+    metadata?: Record<string, any>;
     returnUrl?: string;
-    cancelUrl?: string;
     webhookUrl?: string;
-    metadata?: Record<string, any>;
     customerId?: string;
 }
+/**
+ * @category Payment Processing
+ * @summary Data returned after processing a payment request
+ * @description Contains payment details, status, transaction identifiers, timestamps, and payment URLs
+ * @interface PaymentResponse
+ */
 interface PaymentResponse {
     id: string;
+    status: PaymentStatus;
     amount: number;
     currency: Currency;
     paymentMethod: PaymentMethod;
-    status: PaymentStatus;
     description?: string;
-    returnUrl?: string;
-    cancelUrl?: string;
-    webhookUrl?: string;
     metadata?: Record<string, any>;
-    customerId?: string;
-    paymentUrl?: string;
     createdAt: string;
     updatedAt: string;
+    paymentUrl?: string;
+    transactionId?: string;
+    errorMessage?: string;
 }
+/**
+ * @category Customer Data
+ * @summary Customer identification and contact details
+ * @description Essential information about a customer for payment processing, KYC, and communications
+ * @interface Customer
+ */
+interface Customer {
+    id?: string;
+    email: string;
+    name: string;
+    phone?: string;
+    address?: Address;
+}
+/**
+ * @category Customer Data
+ * @summary Physical address structure for shipping and billing
+ * @description Standardized address format for customer locations with required and optional fields
+ * @interface Address
+ */
+interface Address {
+    street: string;
+    city: string;
+    state?: string;
+    postalCode: string;
+    country: string;
+}
+/**
+ * @category Refunds
+ * @summary Information needed to process a refund
+ * @description Data required to initiate full or partial refunds for completed payments
+ * @interface RefundRequest
+ */
 interface RefundRequest {
     paymentId: string;
     amount?: number;
     reason?: string;
-    metadata?: Record<string, any>;
 }
+/**
+ * @category Refunds
+ * @summary Data returned after processing a refund request
+ * @description Contains refund details, status, amount, and related transaction identifiers
+ * @interface RefundResponse
+ */
 interface RefundResponse {
     id: string;
     paymentId: string;
     amount: number;
-    currency: Currency;
     status: "pending" | "completed" | "failed";
     reason?: string;
-    metadata?: Record<string, any>;
     createdAt: string;
-    updatedAt: string;
 }
-interface Customer {
-    id?: string;
-    email: string;
-    name: string;
-    phone?: string;
-    address?: Address;
-    metadata?: Record<string, any>;
-    createdAt?: string;
-    updatedAt?: string;
+/**
+ * @category Webhooks
+ * @summary Notification data structure for system events
+ * @description Event payload sent to webhook endpoints when important events occur in the payment lifecycle
+ * @interface WebhookEvent
+ */
+interface WebhookEvent {
+    id: string;
+    type: "payment.completed" | "payment.failed" | "refund.completed";
+    data: PaymentResponse | RefundResponse;
+    createdAt: string;
 }
-interface Address {
-    street: string;
-    city: string;
-    country: string;
-    postalCode: string;
+/**
+ * @category Error Handling
+ * @summary Standardized error format returned by the API
+ * @description Structured error information with code, message and optional additional details
+ * @interface APIError
+ */
+interface APIError {
+    code: string;
+    message: string;
+    details?: Record<string, any>;
+}
+/**
+ * @category HTTP
+ * @summary Generic API response wrapper for all endpoints
+ * @description Standard structure containing success status, data payload, and error information
+ * @interface APIResponse
+ */
+interface APIResponse<T> {
+    success: boolean;
+    data?: T;
+    error?: {
+        message: string;
+        code: string;
+        details?: any;
+    };
+    status?: number;
+    headers?: Record<string, string>;
 }
+/**
+ * @category HTTP
+ * @summary Query parameters for paginated API requests
+ * @description Controls paging behavior and sorting of list results with page numbers, limits, and sorting options
+ * @interface PaginationParams
+ */
 interface PaginationParams {
     page?: number;
     limit?: number;
     sortBy?: string;
     sortOrder?: "asc" | "desc";
 }
+/**
+ * @category HTTP
+ * @summary Standardized response format for paginated list operations
+ * @description Contains both the requested data items and pagination metadata for navigation
+ * @interface PaginatedResponse
+ */
 interface PaginatedResponse<T> {
-    page: number;
-    per_page: number;
-    rows: T[];
-    total: number;
-    total_pages: number;
-}
-interface WebhookEvent {
-    id: string;
-    type: "payment.completed" | "payment.failed" | "payment.cancelled" | "refund.completed" | "refund.failed";
-    data: PaymentResponse | RefundResponse;
-    createdAt: string;
-    signature: string;
+    data: T[];
+    pagination: {
+        page: number;
+        limit: number;
+        total: number;
+        pages: number;
+    };
 }
 /**
- * Represents the buyer information.
- * Based on BuyerDTO from the Python SDK.
+ * @category Localization
+ * @summary Supported language codes for the API interface
+ * @description Language preferences that determine text content in API responses and UI elements
+ * @typedef {string} Locale
+ */
+type Locale = "tr" | "en";
+/**
+ * @category Order Management
+ * @summary Customer details required for order processing
+ * @description Comprehensive identification and contact information about the buyer including name, contact details, and addresses
+ * @interface Buyer
  */
-interface Buyer$1 {
+interface Buyer {
     name: string;
     surname: string;
     email: string;
+    phone?: string;
+    identityNumber?: string;
+    shippingAddress?: Address;
+    billingAddress?: Address;
 }
 /**
- * Represents the response received after creating an order.
+ * @category Order Management
+ * @summary Data structure for creating a new payment order
+ * @description Contains all required and optional fields to initiate an order including amount, currency, customer information, and callback URLs
+ * @interface OrderCreateRequest
  */
-interface OrderCreateResponse$1 {
+interface OrderCreateRequest {
+    amount: number;
+    currency: Currency;
+    locale: Locale;
+    buyer: Buyer;
+    description?: string;
+    callbackUrl?: string;
+    conversationId?: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * @category Order Management
+ * @summary Data returned after successful order creation
+ * @description Contains order identifiers, tracking references, checkout URLs, and status information
+ * @interface OrderCreateResponse
+ */
+interface OrderCreateResponse {
     referenceId: string;
     conversationId: string;
     checkoutUrl: string;
@@ -126,12 +244,15 @@ interface OrderCreateResponse$1 {
     qrCodeUrl?: string;
 }
 /**
- * Represents a full order object with all details.
+ * @category Order Management
+ * @summary Complete order information including buyer, payment, and status details
+ * @description Contains all information related to an order including creation and update timestamps
+ * @interface Order
  */
-interface Order extends OrderCreateResponse$1 {
+interface Order extends OrderCreateResponse {
     amount: number | string;
     currency: Currency;
-    buyer?: Buyer$1;
+    buyer?: Buyer;
     description?: string;
     createdAt?: string;
     updatedAt?: string;
@@ -145,14 +266,20 @@ interface Order extends OrderCreateResponse$1 {
     unpaid_amount?: number;
 }
 /**
- * Represents the data needed to request a refund for an order.
+ * @category Refunds
+ * @summary Refund request information for an order
+ * @description Contains the data needed to process a refund for a specific order
+ * @interface OrderRefundRequest
  */
 interface OrderRefundRequest {
     reference_id: string;
     amount: number;
 }
 /**
- * Represents the response received after a refund request.
+ * @category Refunds
+ * @summary Response data after processing a refund request
+ * @description Contains information about the processed refund including status and amount
+ * @interface OrderRefundResponse
  */
 interface OrderRefundResponse {
     refundId: string;
@@ -163,7 +290,10 @@ interface OrderRefundResponse {
     createdAt: string;
 }
 /**
- * Represents the status of an order.
+ * @category Order Management
+ * @summary Order status information
+ * @description Provides the current status of an order and when it was last updated
+ * @interface OrderStatusResponse
  */
 interface OrderStatusResponse {
     referenceId: string;
@@ -171,7 +301,10 @@ interface OrderStatusResponse {
     lastUpdatedAt: string;
 }
 /**
- * Represents the details of a payment transaction associated with an order.
+ * @category Payment Processing
+ * @summary Payment transaction details
+ * @description Contains information about a payment transaction including method, amount, and card details
+ * @interface OrderPaymentDetail
  */
 interface OrderPaymentDetail {
     transactionId: string;
@@ -186,48 +319,390 @@ interface OrderPaymentDetail {
         cardAssociation: string;
     };
 }
-
-/**
- * Supported locales for the Tapsilat API.
- */
-type Locale = "tr" | "en";
 /**
- * Represents the buyer information.
- * Based on BuyerDTO from the Python SDK.
+ * @category API DTOs
+ * @summary API representation of buyer information
+ * @description Contains buyer details as formatted in the API responses
+ * @interface BuyerDTO
  */
-interface Buyer {
+interface BuyerDTO {
     name: string;
     surname: string;
-    email: string;
-    phone?: string;
-    identityNumber?: string;
-    shippingAddress?: Address;
-    billingAddress?: Address;
+    birth_date?: string;
+    city?: string;
+    country?: string;
+    email?: string;
+    gsm_number?: string;
+    id?: string;
+    identity_number?: string;
+    ip?: string;
+    last_login_date?: string;
+    registration_address?: string;
+    registration_date?: string;
+    title?: string;
+    zip_code?: string;
 }
 /**
- * Represents the data required to create a new order.
- * Based on OrderCreateDTO from the Python SDK.
+ * @category API DTOs
+ * @summary Payment responsibility information for basket items
+ * @description Details of the entity responsible for paying a specific basket item
+ * @interface BasketItemPayerDTO
  */
-interface OrderCreateRequest {
+interface BasketItemPayerDTO {
+    address?: string;
+    reference_id?: string;
+    tax_office?: string;
+    title?: string;
+    type?: string;
+    vat?: string;
+}
+/**
+ * @category API DTOs
+ * @summary Individual item in an order basket
+ * @description Details about a product or service being purchased including price and quantity
+ * @interface BasketItemDTO
+ */
+interface BasketItemDTO {
+    category1?: string;
+    category2?: string;
+    commission_amount?: number;
+    coupon?: string;
+    coupon_discount?: number;
+    data?: string;
+    id?: string;
+    item_type?: string;
+    name?: string;
+    paid_amount?: number;
+    payer?: BasketItemPayerDTO;
+    price?: number;
+    quantity?: number;
+    quantity_float?: number;
+    quantity_unit?: string;
+    sub_merchant_key?: string;
+    sub_merchant_price?: string;
+}
+/**
+ * @category API DTOs
+ * @summary Address information for billing purposes
+ * @description Complete billing address information including tax details
+ * @interface BillingAddressDTO
+ */
+interface BillingAddressDTO {
+    address?: string;
+    billing_type?: string;
+    citizenship?: string;
+    city?: string;
+    contact_name?: string;
+    contact_phone?: string;
+    country?: string;
+    district?: string;
+    tax_office?: string;
+    title?: string;
+    vat_number?: string;
+    zip_code?: string;
+}
+/**
+ * @category UI Customization
+ * @summary Customization options for the checkout page
+ * @description Visual design parameters for customizing the checkout experience
+ * @interface CheckoutDesignDTO
+ */
+interface CheckoutDesignDTO {
+    input_background_color?: string;
+    input_text_color?: string;
+    label_text_color?: string;
+    left_background_color?: string;
+    logo?: string;
+    order_detail_html?: string;
+    pay_button_color?: string;
+    redirect_url?: string;
+    right_background_color?: string;
+    text_color?: string;
+}
+/**
+ * @category API DTOs
+ * @summary Custom metadata for orders and transactions
+ * @description Key-value pairs for storing additional information with orders
+ * @interface MetadataDTO
+ */
+interface MetadataDTO {
+    key: string;
+    value: string;
+}
+/**
+ * @category Payment Processing
+ * @summary Card information for processing an order
+ * @description Identifies a saved card to use for payment
+ * @interface OrderCardDTO
+ */
+interface OrderCardDTO {
+    card_id: string;
+    card_sequence: number;
+}
+/**
+ * @category Payment Processing
+ * @summary Individual payment term for an order
+ * @description Details for installment or partial payments with due dates and status
+ * @interface PaymentTermDTO
+ */
+interface PaymentTermDTO {
+    amount?: number;
+    data?: string;
+    due_date?: string;
+    paid_date?: string;
+    required?: boolean;
+    status?: string;
+    term_reference_id?: string;
+    term_sequence?: number;
+}
+/**
+ * @category Submerchant
+ * @summary Payment facilitation submerchant details
+ * @description Information about a submerchant in a payment facilitation flow
+ * @interface OrderPFSubMerchantDTO
+ */
+interface OrderPFSubMerchantDTO {
+    address?: string;
+    city?: string;
+    country?: string;
+    country_iso_code?: string;
+    id?: string;
+    mcc?: string;
+    name?: string;
+    org_id?: string;
+    postal_code?: string;
+    submerchant_nin?: string;
+    submerchant_url?: string;
+    terminal_no?: string;
+}
+/**
+ * @category API DTOs
+ * @summary Address information for shipping
+ * @description Complete shipping address information including tracking details
+ * @interface ShippingAddressDTO
+ */
+interface ShippingAddressDTO {
+    address?: string;
+    city?: string;
+    contact_name?: string;
+    country?: string;
+    shipping_date?: string;
+    tracking_code?: string;
+    zip_code?: string;
+}
+/**
+ * @category Submerchant
+ * @summary Details for sub-organization relationships
+ * @description Information about a subsidiary organization for payment processing
+ * @interface SubOrganizationDTO
+ */
+interface SubOrganizationDTO {
+    acquirer?: string;
+    address?: string;
+    contact_first_name?: string;
+    contact_last_name?: string;
+    currency?: string;
+    email?: string;
+    gsm_number?: string;
+    iban?: string;
+    identity_number?: string;
+    legal_company_title?: string;
+    organization_name?: string;
+    sub_merchant_external_id?: string;
+    sub_merchant_key?: string;
+    sub_merchant_type?: string;
+    tax_number?: string;
+    tax_office?: string;
+}
+/**
+ * @category Submerchant
+ * @summary Payment information for submerchants
+ * @description Defines how payments are split with submerchants
+ * @interface SubmerchantDTO
+ */
+interface SubmerchantDTO {
+    amount?: number;
+    merchant_reference_id?: string;
+    order_basket_item_id?: string;
+}
+/**
+ * @category API DTOs
+ * @summary Comprehensive order creation request
+ * @description Full API request structure for creating an order with all possible options
+ * @interface OrderCreateDTO
+ */
+interface OrderCreateDTO {
     amount: number;
-    currency: Currency;
-    locale: Locale;
-    buyer: Buyer;
-    description?: string;
-    callbackUrl?: string;
-    conversationId?: string;
-    metadata?: Record<string, unknown>;
+    currency: string;
+    locale: string;
+    buyer: BuyerDTO;
+    basket_items?: BasketItemDTO[];
+    billing_address?: BillingAddressDTO;
+    checkout_design?: CheckoutDesignDTO;
+    conversation_id?: string;
+    enabled_installments?: number[];
+    external_reference_id?: string;
+    metadata?: MetadataDTO[];
+    order_cards?: OrderCardDTO;
+    paid_amount?: number;
+    partial_payment?: boolean;
+    payment_failure_url?: string;
+    payment_methods?: boolean;
+    payment_options?: string[];
+    payment_success_url?: string;
+    payment_terms?: PaymentTermDTO[];
+    pf_sub_merchant?: OrderPFSubMerchantDTO;
+    shipping_address?: ShippingAddressDTO;
+    sub_organization?: SubOrganizationDTO;
+    submerchants?: SubmerchantDTO[];
+    tax_amount?: number;
+    three_d_force?: boolean;
 }
 /**
- * Represents the response received after creating an order.
+ * @category Refunds
+ * @summary Data structure for requesting a refund
+ * @description Contains the necessary information to process a refund for an order
+ * @interface RefundOrderDTO
  */
-interface OrderCreateResponse {
-    referenceId: string;
-    conversationId: string;
-    checkoutUrl: string;
+interface RefundOrderDTO {
+    amount: number;
+    reference_id: string;
+    order_item_id?: string;
+    order_item_payment_id?: string;
+}
+/**
+ * @category Payment Terms
+ * @summary Data for creating a payment term
+ * @description Structure for creating a new payment term for an existing order
+ * @interface OrderPaymentTermCreateDTO
+ */
+interface OrderPaymentTermCreateDTO {
+    order_id: string;
+    term_reference_id: string;
+    amount: number;
+    due_date: string;
+    term_sequence: number;
+    required: boolean;
     status: string;
-    qrCodeUrl?: string;
+    data?: string;
+    paid_date?: string;
+}
+/**
+ * @category Payment Terms
+ * @summary Data for updating a payment term
+ * @description Structure for updating an existing payment term
+ * @interface OrderPaymentTermUpdateDTO
+ */
+interface OrderPaymentTermUpdateDTO {
+    term_reference_id: string;
+    amount?: number;
+    due_date?: string;
+    paid_date?: string;
+    required?: boolean;
+    status?: string;
+    term_sequence?: number;
+}
+/**
+ * @category Refunds
+ * @summary Request to refund a specific payment term
+ * @description Data required to process a refund for a specific payment term
+ * @interface OrderTermRefundRequest
+ */
+interface OrderTermRefundRequest {
+    term_id: string;
+    amount: number;
+    reference_id?: string;
+    term_payment_id?: string;
+}
+/**
+ * @category Order Management
+ * @summary Basic order creation response
+ * @description Minimal response information after order creation
+ * @interface OrderResponse
+ */
+interface OrderResponse {
+    reference_id: string;
+    checkout_url: string;
+    order_id?: string;
+}
+
+/**
+ * @category Configuration
+ * @module ConfigManager
+ */
+
+/**
+ * @category Configuration
+ * @summary Configuration management for Tapsilat SDK
+ * @description Handles SDK configuration updates, validation, and secure access to configuration data
+ * @class ConfigManager
+ */
+declare class ConfigManager {
+    private config;
+    /**
+     * @summary Creates a new configuration manager
+     * @description Initializes the configuration manager with the provided configuration options
+     *
+     * @param config - Initial SDK configuration
+     */
+    constructor(config: TapsilatConfig);
+    /**
+     * @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(): Omit<TapsilatConfig, "bearerToken"> & {
+        hasBearerToken: boolean;
+    };
+    /**
+     * @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: Partial<TapsilatConfig>): void;
+    /**
+     * @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(): TapsilatConfig;
+    /**
+     * @category Authentication
+     * @summary Gets the bearer token for authentication
+     * @description Retrieves the configured bearer token for API authentication
+     *
+     * @internal
+     * @returns Bearer token
+     */
+    getBearerToken(): string;
+    /**
+     * @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(): string | undefined;
+    /**
+     * @category Networking
+     * @summary Gets the request timeout value
+     * @description Retrieves the configured timeout value for API requests
+     *
+     * @internal
+     * @returns Request timeout in milliseconds
+     */
+    getTimeout(): number | undefined;
 }
+
 /**
  * Main SDK class for Tapsilat payment operations
  *
@@ -247,7 +722,7 @@ interface OrderCreateResponse {
  */
 declare class TapsilatSDK {
     private readonly httpClient;
-    private readonly config;
+    private readonly configManager;
     /**
      * Creates a new TapsilatSDK instance
      *
@@ -362,6 +837,11 @@ declare class TapsilatSDK {
      *
      * @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
      */
     cancelOrder(referenceId: string): Promise<Order>;
     /**
@@ -410,6 +890,7 @@ declare class TapsilatSDK {
      *
      * @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
      */
     refundOrder(refundData: OrderRefundRequest): Promise<OrderRefundResponse>;
     /**
@@ -421,6 +902,7 @@ declare class TapsilatSDK {
      *
      * @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
      */
     refundAllOrder(referenceId: string): Promise<OrderRefundResponse>;
     /**
@@ -433,6 +915,8 @@ declare class TapsilatSDK {
      * @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
      */
     getOrderPaymentDetails(referenceId: string, conversationId?: string): Promise<OrderPaymentDetail[]>;
     /**
@@ -441,6 +925,11 @@ declare class TapsilatSDK {
      *
      * @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
      */
     getOrderByConversationId(conversationId: string): Promise<Order>;
     /**
@@ -449,6 +938,11 @@ declare class TapsilatSDK {
      *
      * @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
      */
     getOrderTransactions(referenceId: string): Promise<any[]>;
     /**
@@ -457,6 +951,10 @@ declare class TapsilatSDK {
      *
      * @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
      */
     getOrderSubmerchants(params?: {
         page?: number;
@@ -468,6 +966,10 @@ declare class TapsilatSDK {
      *
      * @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
      */
     getCheckoutUrl(referenceId: string): Promise<string>;
     /**
@@ -480,6 +982,7 @@ declare class TapsilatSDK {
      * @param signature - Webhook signature from headers
      * @param secret - Your webhook secret key
      * @returns Promise resolving to true if signature is valid
+     * @throws {TapsilatValidationError} When input validation fails for payload, signature or secret
      */
     verifyWebhook(payload: string, signature: string, secret: string): Promise<boolean>;
     /**
@@ -488,59 +991,149 @@ declare class TapsilatSDK {
      * @summary Check API service health and availability
      * @description Verifies that the Tapsilat API service is operational and accessible.
      *
-     * @returns Promise resolving to service status
+     * @returns Promise resolving to service status with status string and timestamp
+     * @throws {TapsilatError} When API health check fails or returns invalid data
      */
     healthCheck(): Promise<{
         status: string;
         timestamp: string;
     }>;
     /**
-     * Gets current SDK configuration (without sensitive data)
+     * Gets the configuration manager instance
      *
-     * @summary Get current SDK configuration without sensitive information
-     * @description Returns a copy of the current configuration with sensitive data (like bearer token) excluded.
+     * @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.
      *
-     * @returns Copy of current configuration
-     */
-    getConfig(): Omit<TapsilatConfig, "bearerToken"> & {
-        hasBearerToken: boolean;
-    };
-    /**
-     * Updates SDK configuration
+     * @example
+     * ```typescript
+     * const sdk = new TapsilatSDK(config);
+     * const configManager = sdk.getConfigManager();
      *
-     * @summary Update SDK configuration with new values
-     * @description Updates the SDK configuration with provided values, validating bearer token if changed.
+     * // Get config (without sensitive data)
+     * console.log(configManager.getConfig());
      *
-     * @param newConfig - Partial configuration to update
-     * @throws {TapsilatValidationError} When Bearer token is invalid
+     * // Update config
+     * configManager.updateConfig({ timeout: 60000 });
+     * ```
+     *
+     * @returns ConfigManager instance for configuration operations
      */
-    updateConfig(newConfig: Partial<TapsilatConfig>): void;
+    getConfigManager(): ConfigManager;
 }
 
+/**
+ * @category Errors
+ * @module TapsilatError
+ */
+
+/**
+ * @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
+ */
 declare class TapsilatError extends Error {
     readonly code: string;
     readonly details?: Record<string, any>;
+    /**
+     * @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: string, code: string, details?: Record<string, any>);
+    /**
+     * @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: APIError): TapsilatError;
 }
+/**
+ * @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
+ */
 declare class TapsilatNetworkError extends TapsilatError {
     readonly statusCode?: number;
+    /**
+     * @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: string, code: string, statusCode?: number, details?: Record<string, any>);
 }
+/**
+ * @category Errors
+ * @summary Error class for validation failures
+ * @description Error class for data validation issues with field-specific error details
+ * @class TapsilatValidationError
+ * @extends TapsilatError
+ */
 declare 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: string, details?: Record<string, any>);
 }
+/**
+ * @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
+ */
 declare 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?: string);
 }
+/**
+ * @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
+ */
 declare class TapsilatRateLimitError extends TapsilatError {
     readonly retryAfter?: number;
+    /**
+     * @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?: string, retryAfter?: number);
 }
 
 /**
  * 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
  */
@@ -548,21 +1141,39 @@ declare function validatePaymentRequest(request: unknown): asserts request is Pa
 /**
  * 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
  */
 declare function validateEmail(email: string): boolean;
 /**
  * @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
  */
 declare function isValidCurrency(currency: string): boolean;
 /**
  * @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
  */
 declare function isValidPaymentMethod(paymentMethod: string): boolean;
 /**
  * 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
  */
@@ -570,10 +1181,13 @@ declare function isValidUrl(url: string): boolean;
 /**
  * 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
  */
 declare function sanitizeMetadata(metadata: Record<string, unknown>): Record<string, unknown>;
 
-export { TapsilatAuthenticationError, TapsilatError, TapsilatNetworkError, TapsilatRateLimitError, TapsilatSDK, TapsilatValidationError, isValidCurrency, isValidPaymentMethod, isValidUrl, sanitizeMetadata, validateEmail, validatePaymentRequest };
-export type { APIError, APIResponse, Address, Currency, Customer, PaginatedResponse, PaginationParams, PaymentMethod, PaymentRequest, PaymentResponse, PaymentStatus, RefundRequest, RefundResponse, TapsilatConfig, WebhookEvent };
+export { ConfigManager, TapsilatAuthenticationError, TapsilatError, TapsilatNetworkError, TapsilatRateLimitError, TapsilatSDK, TapsilatValidationError, isValidCurrency, isValidPaymentMethod, isValidUrl, sanitizeMetadata, validateEmail, validatePaymentRequest };
+export type { APIError, APIResponse, Address, BasketItemDTO, BasketItemPayerDTO, BillingAddressDTO, Buyer, BuyerDTO, CheckoutDesignDTO, Currency, Customer, Locale, MetadataDTO, Order, OrderCardDTO, OrderCreateDTO, OrderCreateRequest, OrderCreateResponse, OrderPFSubMerchantDTO, OrderPaymentDetail, OrderPaymentTermCreateDTO, OrderPaymentTermUpdateDTO, OrderRefundRequest, OrderRefundResponse, OrderResponse, OrderStatusResponse, OrderTermRefundRequest, PaginatedResponse, PaginationParams, PaymentMethod, PaymentRequest, PaymentResponse, PaymentStatus, PaymentTermDTO, RefundOrderDTO, RefundRequest, RefundResponse, ShippingAddressDTO, SubOrganizationDTO, SubmerchantDTO, TapsilatConfig, WebhookEvent };