@tapsilat/tapsilat-js 1.0.2 → 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,174 +319,514 @@ interface OrderPaymentDetail {
         cardAssociation: string;
     };
 }
-
 /**
- * Supported locales for the Tapsilat API.
+ * @category API DTOs
+ * @summary API representation of buyer information
+ * @description Contains buyer details as formatted in the API responses
+ * @interface BuyerDTO
  */
-type Locale = "tr" | "en";
-/**
- * Represents the buyer information.
- * Based on BuyerDTO from the Python SDK.
- */
-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;
 }
 /**
- * Main SDK class for Tapsilat payment operations
- *
- * @example
- * ```typescript
- * const tapsilat = new TapsilatSDK({
- *   bearerToken: 'your-bearer-token',
- *   baseURL: 'https://api.tapsilat.com/v1'
- * });
- *
- * const payment = await tapsilat.createPayment({
- *   amount: 100.50,
- *   currency: 'TRY',
- *   paymentMethod: 'credit_card'
- * });
- * ```
+ * @category Payment Terms
+ * @summary Data for updating a payment term
+ * @description Structure for updating an existing payment term
+ * @interface OrderPaymentTermUpdateDTO
  */
-declare class TapsilatSDK {
-    private readonly httpClient;
-    private readonly config;
+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;
     /**
-     * Creates a new TapsilatSDK instance
+     * @summary Creates a new configuration manager
+     * @description Initializes the configuration manager with the provided configuration options
      *
-     * @param config - SDK configuration options
-     * @throws {TapsilatValidationError} When Bearer token is invalid
+     * @param config - Initial SDK configuration
      */
     constructor(config: TapsilatConfig);
     /**
-     * Creates a new order and returns a checkout URL.
+     * @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
      *
-     * @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
+     * @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
      *
-     * @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}`);
-     * }
-     * ```
+     * @param newConfig - Partial configuration to update
+     * @throws {TapsilatValidationError} When Bearer token is invalid
      */
-    createOrder(orderRequest: OrderCreateRequest): Promise<OrderCreateResponse>;
+    updateConfig(newConfig: Partial<TapsilatConfig>): void;
     /**
-     * Validates an order request object
-     * @private
+     * @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
      */
-    private validateOrderRequest;
+    getInternalConfig(): TapsilatConfig;
     /**
-     * Basic email validation
-     * @private
+     * @category Authentication
+     * @summary Gets the bearer token for authentication
+     * @description Retrieves the configured bearer token for API authentication
+     *
+     * @internal
+     * @returns Bearer token
      */
-    private isValidEmail;
+    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
+ *
+ * @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.
+ *
+ * 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
+ */
+declare class TapsilatSDK {
+    private readonly httpClient;
+    private readonly configManager;
     /**
-     * Generic response handler - consistent way to handle API responses across SDK methods
-     * @private
+     * Creates a new TapsilatSDK instance
+     *
+     * @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 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
+     * @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
      */
-    private handleResponse;
+    constructor(config: TapsilatConfig);
     /**
-     * Generic error handler - consistent way to handle errors across SDK methods
-     * @private
+     * Creates a new order and returns a checkout URL
+     *
+     * @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.
+     *
+     * 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
      *
-     * @param error - The caught error to process
-     * @param errorContext - Descriptive context for error messages
-     * @throws {TapsilatError} Always throws an appropriate error type
+     * @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
      */
-    private handleError;
+    createOrder(orderRequest: OrderCreateRequest): Promise<OrderCreateResponse>;
     /**
      * 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}`);
-     * }
-     * ```
      */
     getOrder(referenceId: string): Promise<Order>;
     /**
      * 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}`);
-     * }
-     * ```
      */
     getOrders(params?: {
         page?: number;
@@ -361,70 +834,127 @@ declare class TapsilatSDK {
     }): Promise<PaginatedResponse<Order>>;
     /**
      * 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
      */
     cancelOrder(referenceId: string): Promise<Order>;
     /**
-     * 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
      */
     getOrderStatus(referenceId: string): Promise<OrderStatusResponse>;
     /**
      * 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
      */
     refundOrder(refundData: OrderRefundRequest): Promise<OrderRefundResponse>;
     /**
      * 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
      */
     refundAllOrder(referenceId: string): Promise<OrderRefundResponse>;
     /**
      * 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
      */
     getOrderPaymentDetails(referenceId: string, conversationId?: string): Promise<OrderPaymentDetail[]>;
     /**
      * 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
      */
     getOrderByConversationId(conversationId: string): Promise<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
      */
     getOrderTransactions(referenceId: string): Promise<any[]>;
     /**
      * 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
      */
     getOrderSubmerchants(params?: {
         page?: number;
@@ -433,76 +963,177 @@ declare class TapsilatSDK {
     /**
      * 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
      */
     getCheckoutUrl(referenceId: string): Promise<string>;
     /**
      * 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
      */
     verifyWebhook(payload: string, signature: string, secret: string): Promise<boolean>;
     /**
      * 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
      */
     healthCheck(): Promise<{
         status: string;
         timestamp: string;
     }>;
     /**
-     * Gets current SDK configuration (without sensitive data)
+     * Gets the configuration manager instance
      *
-     * @returns Copy of current configuration
-     */
-    getConfig(): Omit<TapsilatConfig, "bearerToken"> & {
-        hasBearerToken: boolean;
-    };
-    /**
-     * 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: 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
  */
@@ -510,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
  */
@@ -532,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 };