clover_sandbox_simulator 1.0.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dc73877a0d3dbbce2dfe5b038167864972933519265d341665ee23646f37f5c1
-  data.tar.gz: 808ede5d13382014d7c2ab5f58379160c0983b7db8ead184032b70a5f39b453a
+  metadata.gz: 15537c1595b19f0f0c351e4650b65ac23316538b7fbc5e3b55bb71c798cba25a
+  data.tar.gz: 6205e71eb9af6a625e5b95024156e2579fe8a687c274178f7a3aa255dc4a13ae
 SHA512:
-  metadata.gz: afdb2f5ddd9026721f63328fb2efd4cc97799d952fea3288d8b090ca4daab696719df353eb8d515aafdfe5b62b165798cbde650cb9ffabaf7e827fae1487a321
-  data.tar.gz: 1218800960726b410b98d5b8d0ca7cfed1aed9a1f916214a257d456ca08373123724764ec04680d1eabde7ebd9f25d98d77a43301d54ee5d0fa2ca74000b7873
+  metadata.gz: 2c3407b953637dc1ddf428f5795befc91969b8c0fb99c67b86c15e93cc6c02a7a9567367991135724e4920426cbd1cd0dcf4c65227aef0fa9600e9510246c838
+  data.tar.gz: 6602102b44527baa4aca0181174d5732407c207bb6139588b010f0c06775b61c80421b31bf0ea6b4b089e1cfa1f74379a151effcc76d384c2fd6d51ec5678729

data/bin/simulate

@@ -9,6 +9,32 @@ module CloverSandboxSimulator
   # Command-line interface for Clover Sandbox Simulator
   class CLI < Thor
     class_option :verbose, type: :boolean, aliases: "-v", desc: "Enable verbose logging"
+    class_option :merchant, type: :string, aliases: "-m", desc: "Merchant ID to use (from .env.json)"
+    class_option :merchant_index, type: :numeric, aliases: "-i", desc: "Merchant index to use (0-based, from .env.json)"
+
+    desc "merchants", "List available merchants from .env.json"
+    def merchants
+      puts "🍽️  Clover Sandbox Simulator - Available Merchants"
+      puts "=" * 60
+
+      config = CloverSandboxSimulator.configuration
+      merchants = config.available_merchants
+
+      if merchants.empty?
+        puts "No merchants found in .env.json"
+        return
+      end
+
+      puts "\n#{'Index'.ljust(6)} #{'Merchant ID'.ljust(16)} #{'Name'.ljust(25)} #{'eComm'}"
+      puts "-" * 60
+
+      merchants.each_with_index do |m, idx|
+        ecomm = m[:has_ecommerce] ? "✓" : "-"
+        puts "#{idx.to_s.ljust(6)} #{m[:id].ljust(16)} #{m[:name][0..23].ljust(25)} #{ecomm}"
+      end
+
+      puts "\nUse: simulate <command> -i <index> or -m <merchant_id>"
+    end
 
     desc "setup", "Set up restaurant entities (categories, items, discounts, employees, customers)"
     option :business_type, type: :string, default: "restaurant", desc: "Business type (restaurant, retail, salon)"
@@ -26,13 +52,15 @@ module CloverSandboxSimulator
 
     desc "generate", "Generate orders for today"
     option :count, type: :numeric, aliases: "-n", desc: "Number of orders to generate"
+    option :refund_percentage, type: :numeric, aliases: "-r", default: 5,
+           desc: "Percentage of orders to refund (0-100, default 5)"
     def generate
       configure_logging
 
       puts "🍽️  Clover Sandbox Simulator - Order Generation"
       puts "=" * 50
 
-      generator = Generators::OrderGenerator.new
+      generator = Generators::OrderGenerator.new(refund_percentage: options[:refund_percentage])
       count = options[:count]
 
       orders = generator.generate_today(count: count)
@@ -41,14 +69,16 @@ module CloverSandboxSimulator
     end
 
     desc "day", "Generate a realistic full day of restaurant operations"
-    option :multiplier, type: :numeric, aliases: "-m", default: 1.0, desc: "Order multiplier (0.5 = slow day, 2.0 = busy day)"
+    option :multiplier, type: :numeric, aliases: "-x", default: 1.0, desc: "Order multiplier (0.5 = slow day, 2.0 = busy day)"
+    option :refund_percentage, type: :numeric, aliases: "-r", default: 5,
+           desc: "Percentage of orders to refund (0-100, default 5)"
     def day
       configure_logging
 
       puts "🍽️  Clover Sandbox Simulator - Realistic Restaurant Day"
       puts "=" * 50
 
-      generator = Generators::OrderGenerator.new
+      generator = Generators::OrderGenerator.new(refund_percentage: options[:refund_percentage])
       orders = generator.generate_realistic_day(multiplier: options[:multiplier])
 
       puts "\n✅ Generated #{orders.size} orders!"
@@ -96,6 +126,8 @@ module CloverSandboxSimulator
     desc "full", "Run full simulation (setup + generate orders)"
     option :count, type: :numeric, aliases: "-n", desc: "Number of orders to generate"
     option :business_type, type: :string, default: "restaurant", desc: "Business type"
+    option :refund_percentage, type: :numeric, aliases: "-r", default: 5,
+           desc: "Percentage of orders to refund (0-100, default 5)"
     def full
       configure_logging
 
@@ -109,7 +141,7 @@ module CloverSandboxSimulator
       puts "\n"
 
       # Generate orders
-      order_gen = Generators::OrderGenerator.new
+      order_gen = Generators::OrderGenerator.new(refund_percentage: options[:refund_percentage])
       orders = order_gen.generate_today(count: options[:count])
 
       puts "\n✅ Full simulation complete!"
@@ -150,6 +182,7 @@ module CloverSandboxSimulator
       employees = services.employee.get_employees
       customers = services.customer.get_customers
       discounts = services.discount.get_discounts
+      refunds = services.refund.fetch_refunds
 
       puts "Categories:  #{categories.size}"
       puts "Menu Items:  #{items.size}"
@@ -157,6 +190,7 @@ module CloverSandboxSimulator
       puts "Employees:   #{employees.size}"
       puts "Customers:   #{customers.size}"
       puts "Discounts:   #{discounts.size}"
+      puts "Refunds:     #{refunds.size}"
 
       puts "\n📋 Categories:"
       categories.each { |c| puts "   - #{c['name']}" }
@@ -165,19 +199,262 @@ module CloverSandboxSimulator
       tenders.each { |t| puts "   - #{t['label']}" }
     end
 
+    desc "refunds", "List all refunds"
+    option :limit, type: :numeric, aliases: "-l", desc: "Maximum number of refunds to show"
+    def refunds
+      configure_logging
+
+      puts "🍽️  Clover Sandbox Simulator - Refunds"
+      puts "=" * 50
+
+      services = Services::Clover::ServicesManager.new
+      refunds = services.refund.fetch_refunds(limit: options[:limit])
+
+      if refunds.empty?
+        puts "No refunds found."
+        return
+      end
+
+      puts "Found #{refunds.size} refunds:\n\n"
+
+      total_amount = 0
+      refunds.each do |refund|
+        amount = refund["amount"] || 0
+        total_amount += amount
+        payment_id = refund.dig("payment", "id") || "N/A"
+        created_at = refund["createdTime"] ? Time.at(refund["createdTime"] / 1000).strftime("%Y-%m-%d %H:%M") : "N/A"
+
+        puts "  ID: #{refund['id']}"
+        puts "     Amount:     $#{'%.2f' % (amount / 100.0)}"
+        puts "     Payment:    #{payment_id}"
+        puts "     Created:    #{created_at}"
+        puts ""
+      end
+
+      puts "-" * 40
+      puts "Total refunded: $#{'%.2f' % (total_amount / 100.0)}"
+    end
+
+    desc "refund", "Create a refund for a payment"
+    option :payment_id, type: :string, aliases: "-p", required: true, desc: "Payment ID to refund"
+    option :amount, type: :numeric, aliases: "-a", desc: "Amount in cents (omit for full refund)"
+    option :reason, type: :string, aliases: "-r", default: "customer_request",
+           desc: "Refund reason (customer_request, quality_issue, wrong_order, duplicate_charge)"
+    def refund
+      configure_logging
+
+      puts "🍽️  Clover Sandbox Simulator - Create Refund"
+      puts "=" * 50
+
+      services = Services::Clover::ServicesManager.new
+
+      if options[:amount]
+        puts "Creating partial refund of $#{'%.2f' % (options[:amount] / 100.0)}..."
+        result = services.refund.create_partial_refund(
+          payment_id: options[:payment_id],
+          amount: options[:amount],
+          reason: options[:reason]
+        )
+      else
+        puts "Creating full refund..."
+        result = services.refund.create_full_refund(
+          payment_id: options[:payment_id],
+          reason: options[:reason]
+        )
+      end
+
+      if result && result["id"]
+        puts "\n✅ Refund created successfully!"
+        puts "   Refund ID: #{result['id']}"
+        puts "   Amount:    $#{'%.2f' % ((result['amount'] || 0) / 100.0)}"
+      else
+        puts "\n❌ Failed to create refund."
+      end
+    end
+
     desc "version", "Show version"
     def version
       puts "Clover Sandbox Simulator v1.0.0"
     end
 
+    # ============================================
+    # Gift Card Commands
+    # ============================================
+
+    desc "gift_cards", "List all gift cards and their balances"
+    def gift_cards
+      configure_logging
+
+      puts "🎁 Clover Sandbox Simulator - Gift Cards"
+      puts "=" * 50
+
+      services = Services::Clover::ServicesManager.new
+      cards = services.gift_card.fetch_gift_cards
+
+      if cards.empty?
+        puts "No gift cards found."
+        puts "\nCreate one with: simulate gift_card_create --amount 5000"
+        return
+      end
+
+      puts "\n#{'ID'.ljust(20)} #{'Card Number'.ljust(20)} #{'Balance'.rjust(12)} #{'Status'.ljust(10)}"
+      puts "-" * 65
+
+      total_balance = 0
+      cards.each do |card|
+        id = card["id"] || "N/A"
+        number = mask_card_number(card["cardNumber"] || "Unknown")
+        balance = card["balance"] || 0
+        status = card["status"] || "UNKNOWN"
+
+        total_balance += balance if status == "ACTIVE"
+
+        balance_str = "$#{'%.2f' % (balance / 100.0)}"
+        puts "#{id.ljust(20)} #{number.ljust(20)} #{balance_str.rjust(12)} #{status.ljust(10)}"
+      end
+
+      puts "-" * 65
+      puts "Total Active Balance: $#{'%.2f' % (total_balance / 100.0)}"
+      puts "\n✅ Found #{cards.size} gift cards"
+    end
+
+    desc "gift_card_create", "Create a new gift card"
+    option :amount, type: :numeric, aliases: "-a", required: true, desc: "Initial balance in cents (e.g., 5000 for $50)"
+    option :card_number, type: :string, aliases: "-n", desc: "Optional 16-digit card number"
+    def gift_card_create
+      configure_logging
+
+      puts "🎁 Clover Sandbox Simulator - Create Gift Card"
+      puts "=" * 50
+
+      services = Services::Clover::ServicesManager.new
+
+      amount = options[:amount]
+      card_number = options[:card_number]
+
+      puts "Creating gift card with balance: $#{'%.2f' % (amount / 100.0)}"
+
+      result = services.gift_card.create_gift_card(
+        amount: amount,
+        card_number: card_number
+      )
+
+      if result && result["id"]
+        puts "\n✅ Gift card created successfully!"
+        puts "   ID:          #{result['id']}"
+        puts "   Card Number: #{mask_card_number(result['cardNumber'])}"
+        puts "   Balance:     $#{'%.2f' % ((result['balance'] || amount) / 100.0)}"
+        puts "   Status:      #{result['status']}"
+      else
+        puts "\n❌ Failed to create gift card"
+      end
+    end
+
+    desc "gift_card_balance", "Check gift card balance"
+    option :id, type: :string, aliases: "-i", required: true, desc: "Gift card ID"
+    def gift_card_balance
+      configure_logging
+
+      puts "🎁 Clover Sandbox Simulator - Gift Card Balance"
+      puts "=" * 50
+
+      services = Services::Clover::ServicesManager.new
+
+      card = services.gift_card.get_gift_card(options[:id])
+
+      if card
+        puts "\nGift Card Details:"
+        puts "   ID:          #{card['id']}"
+        puts "   Card Number: #{mask_card_number(card['cardNumber'])}"
+        puts "   Balance:     $#{'%.2f' % ((card['balance'] || 0) / 100.0)}"
+        puts "   Status:      #{card['status']}"
+      else
+        puts "\n❌ Gift card not found: #{options[:id]}"
+      end
+    end
+
+    desc "gift_card_reload", "Add balance to a gift card"
+    option :id, type: :string, aliases: "-i", required: true, desc: "Gift card ID"
+    option :amount, type: :numeric, aliases: "-a", required: true, desc: "Amount to add in cents"
+    def gift_card_reload
+      configure_logging
+
+      puts "🎁 Clover Sandbox Simulator - Reload Gift Card"
+      puts "=" * 50
+
+      services = Services::Clover::ServicesManager.new
+
+      gc_id = options[:id]
+      amount = options[:amount]
+
+      puts "Adding $#{'%.2f' % (amount / 100.0)} to gift card #{gc_id}"
+
+      result = services.gift_card.reload_gift_card(gc_id, amount: amount)
+
+      if result
+        puts "\n✅ Gift card reloaded successfully!"
+        puts "   New Balance: $#{'%.2f' % ((result['balance'] || 0) / 100.0)}"
+      else
+        puts "\n❌ Failed to reload gift card"
+      end
+    end
+
+    desc "gift_card_redeem", "Redeem/use balance from a gift card"
+    option :id, type: :string, aliases: "-i", required: true, desc: "Gift card ID"
+    option :amount, type: :numeric, aliases: "-a", required: true, desc: "Amount to redeem in cents"
+    def gift_card_redeem
+      configure_logging
+
+      puts "🎁 Clover Sandbox Simulator - Redeem Gift Card"
+      puts "=" * 50
+
+      services = Services::Clover::ServicesManager.new
+
+      gc_id = options[:id]
+      amount = options[:amount]
+
+      puts "Redeeming $#{'%.2f' % (amount / 100.0)} from gift card #{gc_id}"
+
+      result = services.gift_card.redeem_gift_card(gc_id, amount: amount)
+
+      if result[:success]
+        puts "\n✅ Redemption successful!"
+        puts "   Amount Redeemed:   $#{'%.2f' % (result[:amount_redeemed] / 100.0)}"
+        puts "   Remaining Balance: $#{'%.2f' % (result[:remaining_balance] / 100.0)}"
+
+        if result[:shortfall] > 0
+          puts "   ⚠️  Shortfall:       $#{'%.2f' % (result[:shortfall] / 100.0)} (insufficient balance)"
+        end
+      else
+        puts "\n❌ Redemption failed: #{result[:message]}"
+      end
+    end
+
     private
 
+    def mask_card_number(card_number)
+      return card_number if card_number.nil? || card_number.length < 8
+
+      "#{card_number[0..3]}********#{card_number[-4..]}"
+    end
+
     def configure_logging
+      config = CloverSandboxSimulator.configuration
+
       if options[:verbose]
-        CloverSandboxSimulator.configuration.logger.level = Logger::DEBUG
+        config.logger.level = Logger::DEBUG
       else
-        CloverSandboxSimulator.configuration.logger.level = Logger::INFO
+        config.logger.level = Logger::INFO
       end
+
+      # Load specific merchant if specified
+      if options[:merchant]
+        config.load_merchant(merchant_id: options[:merchant])
+      elsif options[:merchant_index]
+        config.load_merchant(index: options[:merchant_index])
+      end
+
+      puts "Using merchant: #{config.merchant_name} (#{config.merchant_id})"
     end
 
     def print_order_summary(orders)

data/lib/clover_sandbox_simulator/configuration.rb

@@ -2,20 +2,114 @@
 
 module CloverSandboxSimulator
   class Configuration
-    attr_accessor :merchant_id, :api_token, :environment, :log_level, :tax_rate, :business_type
+    attr_accessor :merchant_id, :merchant_name, :api_token, :environment, :log_level, :tax_rate, :business_type,
+                  :public_token, :private_token, :ecommerce_environment, :tokenizer_environment,
+                  :app_id, :app_secret, :refresh_token
+
+    # Path to merchants JSON file
+    MERCHANTS_FILE = File.join(File.dirname(__FILE__), "..", "..", ".env.json")
 
     def initialize
       @merchant_id   = ENV.fetch("CLOVER_MERCHANT_ID", nil)
+      @merchant_name = ENV.fetch("CLOVER_MERCHANT_NAME", nil)
       @api_token     = ENV.fetch("CLOVER_API_TOKEN", nil)
       @environment   = normalize_url(ENV.fetch("CLOVER_ENVIRONMENT", "https://sandbox.dev.clover.com/"))
       @log_level     = parse_log_level(ENV.fetch("LOG_LEVEL", "INFO"))
       @tax_rate      = ENV.fetch("TAX_RATE", "8.25").to_f
       @business_type = ENV.fetch("BUSINESS_TYPE", "restaurant").to_sym
+
+      # Ecommerce API tokens (for card payments and refunds)
+      @public_token  = ENV.fetch("PUBLIC_TOKEN", nil)
+      @private_token = ENV.fetch("PRIVATE_TOKEN", nil)
+      @ecommerce_environment = normalize_url(ENV.fetch("ECOMMERCE_ENVIRONMENT", "https://scl-sandbox.dev.clover.com/"))
+      @tokenizer_environment = normalize_url(ENV.fetch("TOKENIZER_ENVIRONMENT", "https://token-sandbox.dev.clover.com/"))
+
+      # OAuth credentials (for token refresh)
+      @app_id = ENV.fetch("CLOVER_APP_ID", nil)
+      @app_secret = ENV.fetch("CLOVER_APP_SECRET", nil)
+      @refresh_token = ENV.fetch("CLOVER_REFRESH_TOKEN", nil)
+
+      # Load from .env.json if merchant_id not set in ENV
+      load_from_merchants_file if @merchant_id.nil? || @merchant_id.empty?
+    end
+
+    # Check if OAuth is configured for token refresh
+    def oauth_enabled?
+      !app_id.nil? && !app_id.empty? &&
+        !app_secret.nil? && !app_secret.empty?
+    end
+
+    # Load configuration for a specific merchant from .env.json
+    #
+    # @param merchant_id [String, nil] Merchant ID to load (nil for first merchant)
+    # @param index [Integer, nil] Index of merchant in the list (0-based)
+    # @return [self]
+    def load_merchant(merchant_id: nil, index: nil)
+      merchants = load_merchants_file
+      return self if merchants.empty?
+
+      merchant = if merchant_id
+                   merchants.find { |m| m["CLOVER_MERCHANT_ID"] == merchant_id }
+                 elsif index
+                   merchants[index]
+                 else
+                   merchants.first
+                 end
+
+      if merchant
+        apply_merchant_config(merchant)
+        logger.info "Loaded merchant: #{@merchant_name} (#{@merchant_id})"
+      else
+        logger.warn "Merchant not found: #{merchant_id || "index #{index}"}"
+      end
+
+      self
+    end
+
+    # List all available merchants from .env.json
+    #
+    # @return [Array<Hash>] Array of merchant configs
+    def available_merchants
+      load_merchants_file.map do |m|
+        {
+          id: m["CLOVER_MERCHANT_ID"],
+          name: m["CLOVER_MERCHANT_NAME"],
+          has_ecommerce: !m["PUBLIC_TOKEN"].to_s.empty? && !m["PRIVATE_TOKEN"].to_s.empty?
+        }
+      end
     end
 
     def validate!
       raise ConfigurationError, "CLOVER_MERCHANT_ID is required" if merchant_id.nil? || merchant_id.empty?
-      raise ConfigurationError, "CLOVER_API_TOKEN is required" if api_token.nil? || api_token.empty?
+
+      # API token is only required for Platform API operations
+      # Ecommerce-only operations can work without it
+      true
+    end
+
+    # Validate for Platform API operations (requires OAuth token)
+    def validate_platform!
+      validate!
+      raise ConfigurationError, "CLOVER_API_TOKEN is required for Platform API" if api_token.nil? || api_token.empty?
+
+      true
+    end
+
+    # Check if Platform API is configured (has OAuth token)
+    def platform_enabled?
+      !api_token.nil? && !api_token.empty? && api_token != "NEEDS_REFRESH"
+    end
+
+    # Check if Ecommerce API is configured
+    def ecommerce_enabled?
+      !public_token.nil? && !public_token.empty? &&
+        !private_token.nil? && !private_token.empty?
+    end
+
+    # Validate Ecommerce configuration
+    def validate_ecommerce!
+      raise ConfigurationError, "PUBLIC_TOKEN is required for Ecommerce API" if public_token.nil? || public_token.empty?
+      raise ConfigurationError, "PRIVATE_TOKEN is required for Ecommerce API" if private_token.nil? || private_token.empty?
 
       true
     end
@@ -32,6 +126,39 @@ module CloverSandboxSimulator
 
     private
 
+    def load_from_merchants_file
+      merchants = load_merchants_file
+      return if merchants.empty?
+
+      # Use first merchant by default
+      apply_merchant_config(merchants.first)
+    end
+
+    def load_merchants_file
+      return [] unless File.exist?(MERCHANTS_FILE)
+
+      JSON.parse(File.read(MERCHANTS_FILE))
+    rescue JSON::ParserError => e
+      warn "Failed to parse #{MERCHANTS_FILE}: #{e.message}"
+      []
+    end
+
+    def apply_merchant_config(merchant)
+      @merchant_id   = merchant["CLOVER_MERCHANT_ID"]
+      @merchant_name = merchant["CLOVER_MERCHANT_NAME"]
+      # CLOVER_API_TOKEN = static API token (never expires)
+      # CLOVER_ACCESS_TOKEN = OAuth JWT token (expires, can be refreshed)
+      # Prefer static API token if available, fall back to OAuth token
+      if merchant["CLOVER_API_TOKEN"].to_s.length > 10
+        @api_token = merchant["CLOVER_API_TOKEN"]
+      elsif merchant["CLOVER_ACCESS_TOKEN"].to_s.length > 10
+        @api_token = merchant["CLOVER_ACCESS_TOKEN"]
+      end
+      @refresh_token = merchant["CLOVER_REFRESH_TOKEN"] if merchant["CLOVER_REFRESH_TOKEN"].to_s.length > 10
+      @public_token  = merchant["PUBLIC_TOKEN"] unless merchant["PUBLIC_TOKEN"].to_s.empty?
+      @private_token = merchant["PRIVATE_TOKEN"] unless merchant["PRIVATE_TOKEN"].to_s.empty?
+    end
+
     def normalize_url(url)
       url = url.strip
       url.end_with?("/") ? url : "#{url}/"