@tapsilat/tapsilat-js/dist/TapsilatSDK.d.ts

Enterprise-grade TypeScript SDK for Tapsilat Payment Processing Platform

import { ConfigManager } from "./config/ConfigManager";
import { TapsilatConfig, PaginatedResponse, Order, OrderRefundRequest, OrderRefundResponse, OrderStatusResponse, OrderPaymentDetail, OrderCreateRequest, OrderCreateResponse } from "./types/index";
/**
 * 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
 */
export declare class TapsilatSDK {
    private readonly httpClient;
    private readonly configManager;
    /**
     * 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 {TapsilatConfig} config - SDK configuration options
     * @param {string} config.bearerToken - API authentication token (required)
     * @param {string} [config.baseURL='https://api.tapsilat.com/v1'] - API base URL
     * @param {number} [config.timeout=30000] - Request timeout in milliseconds
     * @param {number} [config.maxRetries=3] - Maximum number of retry attempts
     * @param {number} [config.retryDelay=1000] - Delay between retries in milliseconds
     * @param {string} [config.version='v1'] - API version to use
     * @param {boolean} [config.debug=false] - Enable debug logging
     *
     * @throws {TapsilatValidationError} When bearer token is invalid, missing, or malformed
     * @throws {TypeError} When config parameter is not an object or missing required fields
     */
    constructor(config: TapsilatConfig);
    /**
     * 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
     *
     * @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
     */
    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
     */
    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
     */
    getOrders(params?: {
        page?: number;
        per_page?: number;
    }): 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 current status of an order by reference ID
     *
     * @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.
     *
     * 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;
        per_page?: number;
    }): Promise<any>;
    /**
     * 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
     * @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
     *
     * @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 the configuration manager instance
     *
     * @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.
     *
     * @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
     */
    getConfigManager(): ConfigManager;
}
//# sourceMappingURL=TapsilatSDK.d.ts.map