basic-usage.js

import { TapsilatSDK, validateGsmNumber, validateInstallments } from "../dist/index.esm.js";

/**
 * Comprehensive Example of Tapsilat Payment SDK Integration
 * 
 * This example demonstrates the complete functionality of the Tapsilat SDK:
 * 1. Creating payment orders with detailed customer information
 * 2. Retrieving and monitoring order status updates
 * 3. Fetching complete order details including buyer information
 * 4. Listing orders with pagination support
 * 5. Cancelling pending orders when needed
 * 6. Payment Term Management (installments and partial payments)
 * 7. GSM number and installment validation utilities
 * 8. Advanced order operations (refunds, termination)
 * 
 * The Tapsilat SDK provides a robust interface for managing the entire
 * payment lifecycle with built-in validation, error handling, and
 * standardized response formats.
 */

async function main() {
  try {
    // Initialize the SDK with your organization's credentials
    // The SDK handles authentication, request formatting, and error handling
    const tapsilat = new TapsilatSDK({
      bearerToken: "YOUR_BEARER_TOKEN", // Replace with your actual bearer token
      baseURL: "https://panel.tapsilat.dev/v1", // API base URL
      timeout: 30000, // Request timeout in milliseconds
      retryAttempts: 3, // Number of automatic retry attempts for failed requests
    });

    console.log("Tapsilat SDK initialized");

    // STEP 1: Creating a new payment order
    // -----------------------------------------
    // This creates a new order in the payment system and returns
    // a checkout URL where customers can complete their payment
    const orderRequest = {
      amount: 150.75, // Payment amount with up to 2 decimal places
      currency: "TRY", // Supported currencies: TRY, USD, EUR, GBP
      locale: "tr",    // Interface language: tr (Turkish) or en (English)
      
      // Customer information (required for compliance and notifications)
      buyer: {
        name: "John",
        surname: "Doe",
        email: "john.doe@example.com",
        phone: "+9099999999", // Optional
        identityNumber: "11111111111", // Optional - national ID or tax number
      },
      
      // Optional order parameters
      description: "Premium Subscription - Annual Plan",
      callbackUrl: "https://your-website.com/payment-complete", // Redirect after payment
      conversationId: "order-" + Date.now(), // Your custom reference ID
      
      // Optional metadata (key-value pairs for your reference)
      metadata: [
        { key: "productId", value: "PREMIUM-12M" },
        { key: "customerType", value: "new" },
        { key: "campaign", value: "summer2025" }
      ]
    };

    // Create the order and store the reference for tracking
    const order = await tapsilat.createOrder(orderRequest);
    
    // Extract key information from the response
    // The API uses snake_case format for field names
    const referenceId = order.reference_id;
    const checkoutUrl = order.checkout_url;
    
    console.log(`Order created successfully with reference ID: ${referenceId}`);
    console.log(`Checkout URL to send to customer: ${checkoutUrl}`);

    // STEP 2: Checking order payment status
    // -----------------------------------------
    // Use this to monitor whether the payment has been completed
    // This is typically called after customer returns from checkout
    // or via a webhook notification
    const orderStatus = await tapsilat.getOrderStatus(referenceId);
    console.log(`Current payment status: ${orderStatus.status}`);

    // STEP 3: Retrieving complete order details
    // -----------------------------------------
    // This provides the full order information including:
    // - Payment details (amount, currency, timestamps)
    // - Customer information
    // - Current status and payment history
    const orderDetails = await tapsilat.getOrder(referenceId);
    console.log(`Order amount: ${orderDetails.amount} ${orderDetails.currency}`);
    console.log(`Status: ${orderDetails.status_enum}`);
    
    // STEP 4: Listing recent orders with pagination
    // -----------------------------------------
    // Retrieve a paginated list of orders for reporting or dashboard display
    const ordersList = await tapsilat.getOrders({
      page: 1,        // Page number (starting from 1)
      per_page: 5     // Number of items per page
    });
    
    // Process the paginated response
    const orders = ordersList.rows || [];
    const totalOrders = ordersList.total;
    const totalPages = ordersList.total_pages;
    
    console.log(`Displaying ${orders.length} of ${totalOrders} total orders (Page 1 of ${totalPages})`);
    
    // STEP 5: Payment Term Management (NEW FEATURES!)
    // -----------------------------------------
    // Create installment plans and manage payment terms
    console.log("\n=== Payment Term Management ===");
    
    try {
      // Create a payment term for installment payments
      const paymentTerm = await tapsilat.createOrderTerm({
        order_id: referenceId,
        term_reference_id: `term-${Date.now()}`,
        amount: 50.25,
        due_date: "2024-12-31",
        term_sequence: 1,
        required: true,
        status: "pending",
        data: "First installment payment"
      });
      
      console.log(`Payment term created: ${paymentTerm.term_reference_id}`);
      
      // Update the payment term
      const updatedTerm = await tapsilat.updateOrderTerm({
        term_reference_id: paymentTerm.term_reference_id,
        amount: 55.00,
        status: "updated"
      });
      
      console.log(`Payment term updated. New amount: ${updatedTerm.amount}`);
      
      // Refund a specific payment term
      const termRefund = await tapsilat.refundOrderTerm({
        term_id: paymentTerm.term_reference_id,
        amount: 25.00
      });
      
      console.log(`Term refund processed: ${termRefund.refund_id}`);
      
    } catch (error) {
      console.log(`Payment term operations: ${error.message}`);
    }

    // STEP 6: Validation Utilities (NEW FEATURES!)
    // -----------------------------------------
    // Validate GSM numbers and installments
    console.log("\n=== Validation Utilities ===");
    
    // GSM Number Validation
    const gsmTests = [
      "+90 555 123 45 67",
      "0555 123 45 67", 
      "555-123-45-67",
      "invalid-number"
    ];
    
    gsmTests.forEach(gsm => {
      const result = validateGsmNumber(gsm);
      if (result.isValid) {
        console.log(`✅ GSM ${gsm} → ${result.cleanedNumber}`);
      } else {
        console.log(`❌ GSM ${gsm} → ${result.error}`);
      }
    });
    
    // Installments Validation
    const installmentTests = [
      3,
      "1,3,6,12",
      [2, 6, 9],
      "invalid"
    ];
    
    installmentTests.forEach(inst => {
      const result = validateInstallments(inst);
      if (result.isValid) {
        console.log(`✅ Installments ${inst} → [${result.validatedInstallments.join(', ')}]`);
      } else {
        console.log(`❌ Installments ${inst} → ${result.error}`);
      }
    });

    // STEP 7: Advanced Order Operations (NEW FEATURES!)
    // -----------------------------------------
    console.log("\n=== Advanced Order Operations ===");
    
    try {
      // Process a partial refund
      const partialRefund = await tapsilat.refundOrder({
        reference_id: referenceId,
        amount: 50.00
      });
      
      console.log(`Partial refund processed: ${partialRefund.refundId}`);
      
      // Get order payment details
      const paymentDetails = await tapsilat.getOrderPaymentDetails(referenceId);
      console.log(`Payment details retrieved: ${paymentDetails.length} transactions`);
      
      // Get order transactions
      const transactions = await tapsilat.getOrderTransactions(referenceId);
      console.log(`Transaction history: ${transactions.length} transactions`);
      
    } catch (error) {
      console.log(`Advanced operations: ${error.message}`);
    }

    // STEP 8: Health Check and Webhook Verification
    // -----------------------------------------
    console.log("\n=== SDK Health Check ===");
    
    try {
      const health = await tapsilat.healthCheck();
      console.log(`API Health: ${health.status} at ${health.timestamp}`);
    } catch (error) {
      console.log(`Health check failed: ${error.message}`);
    }
    
    // Webhook signature verification example
    const webhookPayload = '{"event": "order.completed", "data": {"id": "123"}}';
    const webhookSignature = "sample-signature";
    const webhookSecret = "your-webhook-secret";
    
    try {
      const isValidWebhook = await tapsilat.verifyWebhook(
        webhookPayload,
        webhookSignature, 
        webhookSecret
      );
      console.log(`Webhook verification: ${isValidWebhook ? 'Valid' : 'Invalid'}`);
    } catch (error) {
      console.log(`Webhook verification error: ${error.message}`);
    }

    // STEP 9: Order Termination (if needed)
    // -----------------------------------------
    console.log("\n=== Order Termination ===");
    
    try {
      // Terminate the entire order
      const terminatedOrder = await tapsilat.terminateOrder({
        reference_id: referenceId,
        reason: "Customer request - demonstration complete"
      });
      
      console.log(`Order terminated at: ${terminatedOrder.terminated_at}`);
      console.log(`Termination reason: ${terminatedOrder.reason}`);
      
    } catch (error) {
      console.log(`Order termination: ${error.message}`);
    }

    console.log("\nAll SDK features demonstrated successfully!");

  } catch (error) {
    // The SDK provides detailed error information
    console.error(`\nAPI Error: ${error.message}`);
    console.log("Note: This is expected without valid API credentials");
    
    // Error codes help identify specific issues
    if (error.code) {
      console.error(`Error code: ${error.code}`);
    }
  }
  
  // Continue with offline tests that don't require API calls
  console.log("\n" + "=".repeat(50));
  console.log("OFFLINE FEATURES TEST (No API credentials needed)");
  console.log("=".repeat(50));
  
  await testOfflineFeatures();
}

// Test offline features that work without API calls
async function testOfflineFeatures() {
  try {
    console.log("\n=== SDK Initialization Tests ===");
    
    // Test invalid configurations
    try {
      new TapsilatSDK({ bearerToken: "" });
    } catch (error) {
      console.log(`Empty token validation: ${error.message}`);
    }
    
    try {
      new TapsilatSDK({ bearerToken: "abc" });
    } catch (error) {
      console.log(`Short token validation: ${error.message}`);
    }
    
    // Valid SDK initialization
    const testSDK = new TapsilatSDK({
      bearerToken: "test-bearer-token-12345678901234567890",
      baseURL: "https://test-panel.tapsilat.dev/v1"
    });
    console.log("SDK initialized successfully with valid config");
    
    console.log("\n=== Order Validation Tests ===");
    
    // Test order validations
    const orderValidationTests = [
      {
        name: "Negative amount",
        data: { amount: -100, currency: "TRY", locale: "tr", buyer: { name: "Test", surname: "User", email: "test@example.com" }},
      },
      {
        name: "Too many decimals", 
        data: { amount: 100.555, currency: "TRY", locale: "tr", buyer: { name: "Test", surname: "User", email: "test@example.com" }},
      },
      {
        name: "Invalid email",
        data: { amount: 100, currency: "TRY", locale: "tr", buyer: { name: "Test", surname: "User", email: "invalid-email" }},
      },
      {
        name: "Empty name",
        data: { amount: 100, currency: "TRY", locale: "tr", buyer: { name: "", surname: "User", email: "test@example.com" }},
      }
    ];
    
    for (const test of orderValidationTests) {
      try {
        await testSDK.createOrder(test.data);
      } catch (error) {
        console.log(`${test.name} validation: ${error.message}`);
      }
    }
    
    console.log("\n=== Payment Term Validation Tests ===");
    
    // Test payment term validations
    const termValidationTests = [
      {
        name: "Empty order ID",
        data: { order_id: "", term_reference_id: "term-123", amount: 100, due_date: "2024-12-31", term_sequence: 1, required: true, status: "pending" },
      },
      {
        name: "Negative term amount",
        data: { order_id: "order-123", term_reference_id: "term-123", amount: -50, due_date: "2024-12-31", term_sequence: 1, required: true, status: "pending" },
      },
      {
        name: "Non-integer sequence",
        data: { order_id: "order-123", term_reference_id: "term-123", amount: 100, due_date: "2024-12-31", term_sequence: 1.5, required: true, status: "pending" },
      }
    ];
    
    for (const test of termValidationTests) {
      try {
        await testSDK.createOrderTerm(test.data);
      } catch (error) {
        console.log(`${test.name} validation: ${error.message}`);
      }
    }
    
    console.log("\n=== Webhook Validation Tests ===");
    
    // Test webhook validations
    const webhookTests = [
      { payload: "", signature: "sig", secret: "secret", name: "Empty payload" },
      { payload: "payload", signature: "", secret: "secret", name: "Empty signature" },
      { payload: "payload", signature: "sig", secret: "", name: "Empty secret" }
    ];
    
    for (const test of webhookTests) {
      try {
        await testSDK.verifyWebhook(test.payload, test.signature, test.secret);
      } catch (error) {
        console.log(`${test.name} validation: ${error.message}`);
      }
    }
    
    console.log("\nAll offline validation tests passed!");
    
    // Print feature summary
    printFeatureSummary();
    
  } catch (error) {
    console.error(`Offline test error: ${error.message}`);
  }
}

// Print comprehensive feature summary
function printFeatureSummary() {
  console.log("\n" + "=".repeat(50));
  console.log("TAPSILAT JAVASCRIPT SDK FEATURE SUMMARY");
  console.log("=".repeat(50));
  
  console.log("\nCore Payment Operations:");
  console.log("  - createOrder() - Create new payment orders");
  console.log("  - getOrder() - Retrieve order details"); 
  console.log("  - getOrderStatus() - Check payment status");
  console.log("  - getOrders() - List orders with pagination");
  console.log("  - cancelOrder() - Cancel pending orders");
  console.log("  - refundOrder() - Process refunds");
  
  console.log("\nPayment Term Management (NEW):");
  console.log("  - createOrderTerm() - Create installment plans");
  console.log("  - updateOrderTerm() - Update payment terms");
  console.log("  - deleteOrderTerm() - Remove payment terms");
  console.log("  - refundOrderTerm() - Term-specific refunds");
  console.log("  - terminateOrderTerm() - Cancel individual terms");
  console.log("  - terminateOrder() - Cancel entire orders");
  
  console.log("\nValidation Utilities (NEW):");
  console.log("  - validateGsmNumber() - Turkish phone validation");
  console.log("  - validateInstallments() - Installment validation");
  console.log("  - Input validation for all methods");
  console.log("  - Email format validation");
  console.log("  - Amount and currency validation");
  
  console.log("\nTechnical Features:");
  console.log("  - Full TypeScript support");
  console.log("  - Webhook signature verification");
  console.log("  - Health monitoring");
  console.log("  - Configuration management");
  console.log("  - Automatic retry logic");
  console.log("  - Comprehensive error handling");
  
  console.log("\nPython SDK Feature Parity:");
  console.log("  - ALL Python SDK features implemented");
  console.log("  - Additional JavaScript-specific features");
  console.log("  - Better type safety with TypeScript");
  
  console.log("\nReady for Production!");
  console.log("  Update your bearer token in the config");
  console.log("  Use the correct API base URL");
  console.log("  All validation works offline");
  console.log("  Check README.md for full documentation");
}

// Execute the example
main().catch(console.error);