clover_sandbox_simulator 1.0.0

data/lib/clover_sandbox_simulator/services/clover/customer_service.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require "faker"
+
+module CloverSandboxSimulator
+  module Services
+    module Clover
+      # Manages Clover customers
+      class CustomerService < BaseService
+        # Fetch all customers
+        def get_customers
+          logger.info "Fetching customers..."
+          response = request(:get, endpoint("customers"))
+          elements = response&.dig("elements") || []
+          logger.info "Found #{elements.size} customers"
+          elements
+        end
+
+        # Get a specific customer
+        def get_customer(customer_id)
+          request(:get, endpoint("customers/#{customer_id}"))
+        end
+
+        # Create a customer
+        def create_customer(first_name:, last_name:, email: nil, phone: nil)
+          logger.info "Creating customer: #{first_name} #{last_name}"
+
+          payload = {
+            "firstName" => first_name,
+            "lastName" => last_name
+          }
+          payload["emailAddresses"] = [{ "emailAddress" => email }] if email
+          payload["phoneNumbers"] = [{ "phoneNumber" => phone }] if phone
+
+          request(:post, endpoint("customers"), payload: payload)
+        end
+
+        # Create sample customers if needed
+        def ensure_customers(count: 10)
+          existing = get_customers
+          return existing if existing.size >= count
+
+          needed = count - existing.size
+          logger.info "Creating #{needed} sample customers..."
+
+          new_customers = []
+          needed.times do
+            first = Faker::Name.first_name
+            last = Faker::Name.last_name
+            # Use example.com domain - Clover rejects .test domains
+            # Remove special chars, collapse dots, strip leading/trailing dots
+            safe_first = first.downcase.gsub(/[^a-z0-9]/, "")
+            safe_last = last.downcase.gsub(/[^a-z0-9]/, "")
+            customer = create_customer(
+              first_name: first,
+              last_name: last,
+              email: "#{safe_first}.#{safe_last}@example.com",
+              phone: Faker::PhoneNumber.cell_phone
+            )
+            new_customers << customer if customer
+          end
+
+          existing + new_customers
+        end
+
+        # Get a random customer (70% chance of returning a customer, 30% anonymous)
+        def random_customer
+          return nil if rand < 0.3 # 30% anonymous orders
+
+          customers = get_customers
+          customers.sample
+        end
+
+        # Delete a customer
+        def delete_customer(customer_id)
+          logger.info "Deleting customer: #{customer_id}"
+          request(:delete, endpoint("customers/#{customer_id}"))
+        end
+      end
+    end
+  end
+end

data/lib/clover_sandbox_simulator/services/clover/discount_service.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module CloverSandboxSimulator
+  module Services
+    module Clover
+      # Manages Clover discounts
+      class DiscountService < BaseService
+        # Fetch all discounts
+        def get_discounts
+          logger.info "Fetching discounts..."
+          response = request(:get, endpoint("discounts"))
+          elements = response&.dig("elements") || []
+          logger.info "Found #{elements.size} discounts"
+          elements
+        end
+
+        # Get a specific discount
+        def get_discount(discount_id)
+          request(:get, endpoint("discounts/#{discount_id}"))
+        end
+
+        # Create a fixed amount discount
+        def create_fixed_discount(name:, amount:)
+          logger.info "Creating fixed discount: #{name} ($#{amount / 100.0})"
+
+          request(:post, endpoint("discounts"), payload: {
+            "name" => name,
+            "amount" => -amount.abs # Clover expects negative for discounts
+          })
+        end
+
+        # Create a percentage discount
+        def create_percentage_discount(name:, percentage:)
+          logger.info "Creating percentage discount: #{name} (#{percentage}%)"
+
+          request(:post, endpoint("discounts"), payload: {
+            "name" => name,
+            "percentage" => percentage
+          })
+        end
+
+        # Delete a discount
+        def delete_discount(discount_id)
+          logger.info "Deleting discount: #{discount_id}"
+          request(:delete, endpoint("discounts/#{discount_id}"))
+        end
+
+        # Select a random discount (30% chance of returning nil)
+        def random_discount
+          return nil if rand < 0.7 # 70% chance of no discount
+
+          discounts = get_discounts
+          discounts.sample
+        end
+      end
+    end
+  end
+end

data/lib/clover_sandbox_simulator/services/clover/employee_service.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require "faker"
+
+module CloverSandboxSimulator
+  module Services
+    module Clover
+      # Manages Clover employees
+      class EmployeeService < BaseService
+        # Note: OWNER and ADMIN roles may not be available in sandbox
+        ROLES = %w[MANAGER EMPLOYEE].freeze
+
+        # Fetch all employees
+        def get_employees
+          logger.info "Fetching employees..."
+          response = request(:get, endpoint("employees"))
+          elements = response&.dig("elements") || []
+          # Filter active employees
+          active = elements.select { |e| e["deleted"] != true }
+          logger.info "Found #{active.size} active employees"
+          active
+        end
+
+        # Get a specific employee
+        def get_employee(employee_id)
+          request(:get, endpoint("employees/#{employee_id}"))
+        end
+
+        # Create an employee
+        def create_employee(name:, email: nil, role: "EMPLOYEE", pin: nil)
+          logger.info "Creating employee: #{name}"
+
+          payload = {
+            "name" => name,
+            "role" => role
+          }
+          payload["email"] = email if email
+          payload["pin"] = pin if pin
+
+          request(:post, endpoint("employees"), payload: payload)
+        end
+
+        # Create sample employees if needed
+        def ensure_employees(count: 3)
+          existing = get_employees
+          return existing if existing.size >= count
+
+          needed = count - existing.size
+          logger.info "Creating #{needed} sample employees..."
+
+          new_employees = []
+          needed.times do
+            name = Faker::Name.name
+            # Use example.com domain - Clover rejects .test domains
+            # Remove special chars, collapse dots, strip leading/trailing dots
+            safe_name = name.downcase.gsub(/[^a-z0-9]/, ".").gsub(/\.+/, ".").gsub(/^\.|\.$/, "")
+            employee = create_employee(
+              name: name,
+              email: "#{safe_name}@example.com",
+              role: ROLES.sample
+            )
+            new_employees << employee if employee
+          end
+
+          existing + new_employees
+        end
+
+        # Get a random employee
+        def random_employee
+          employees = get_employees
+          employees.sample
+        end
+
+        # Delete an employee
+        def delete_employee(employee_id)
+          logger.info "Deleting employee: #{employee_id}"
+          request(:delete, endpoint("employees/#{employee_id}"))
+        end
+      end
+    end
+  end
+end

data/lib/clover_sandbox_simulator/services/clover/inventory_service.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module CloverSandboxSimulator
+  module Services
+    module Clover
+      # Manages Clover inventory: categories, items, modifiers
+      class InventoryService < BaseService
+        # Fetch all categories
+        def get_categories
+          logger.info "Fetching categories..."
+          response = request(:get, endpoint("categories"))
+          elements = response&.dig("elements") || []
+          logger.info "Found #{elements.size} categories"
+          elements
+        end
+
+        # Create a category
+        def create_category(name:, sort_order: nil)
+          logger.info "Creating category: #{name}"
+          payload = { "name" => name }
+          payload["sortOrder"] = sort_order if sort_order
+          request(:post, endpoint("categories"), payload: payload)
+        end
+
+        # Delete a category
+        def delete_category(category_id)
+          logger.info "Deleting category: #{category_id}"
+          request(:delete, endpoint("categories/#{category_id}"))
+        end
+
+        # Fetch all items
+        def get_items
+          logger.info "Fetching items..."
+          response = request(:get, endpoint("items"), params: { expand: "categories,modifierGroups" })
+          elements = response&.dig("elements") || []
+          # Filter out deleted items
+          active_items = elements.reject { |item| item["deleted"] == true }
+          logger.info "Found #{active_items.size} active items"
+          active_items
+        end
+
+        # Create an item
+        def create_item(name:, price:, category_id: nil, sku: nil, hidden: false)
+          logger.info "Creating item: #{name} ($#{price / 100.0})"
+
+          payload = {
+            "name" => name,
+            "price" => price,
+            "priceType" => "FIXED",
+            "hidden" => hidden,
+            "defaultTaxRates" => true
+          }
+          payload["sku"] = sku if sku
+
+          item = request(:post, endpoint("items"), payload: payload)
+
+          # Associate with category if provided
+          if item && category_id
+            associate_item_with_category(item["id"], category_id)
+          end
+
+          item
+        end
+
+        # Associate item with category
+        def associate_item_with_category(item_id, category_id)
+          logger.debug "Associating item #{item_id} with category #{category_id}"
+          request(:post, endpoint("category_items"), payload: {
+            "elements" => [{ "item" => { "id" => item_id }, "category" => { "id" => category_id } }]
+          })
+        end
+
+        # Delete an item
+        def delete_item(item_id)
+          logger.info "Deleting item: #{item_id}"
+          request(:delete, endpoint("items/#{item_id}"))
+        end
+
+        # Fetch all modifier groups
+        def get_modifier_groups
+          logger.info "Fetching modifier groups..."
+          response = request(:get, endpoint("modifier_groups"), params: { expand: "modifiers" })
+          elements = response&.dig("elements") || []
+          logger.info "Found #{elements.size} modifier groups"
+          elements
+        end
+
+        # Create a modifier group
+        def create_modifier_group(name:, min_required: 0, max_allowed: nil)
+          logger.info "Creating modifier group: #{name}"
+          payload = {
+            "name" => name,
+            "minRequired" => min_required
+          }
+          payload["maxAllowed"] = max_allowed if max_allowed
+          request(:post, endpoint("modifier_groups"), payload: payload)
+        end
+
+        # Create a modifier within a group
+        def create_modifier(modifier_group_id:, name:, price: 0)
+          logger.info "Creating modifier: #{name} in group #{modifier_group_id}"
+          request(:post, endpoint("modifier_groups/#{modifier_group_id}/modifiers"), payload: {
+            "name" => name,
+            "price" => price
+          })
+        end
+
+        # Delete all categories and items
+        def delete_all
+          logger.warn "Deleting all inventory..."
+
+          get_items.each { |item| delete_item(item["id"]) }
+          get_categories.each { |cat| delete_category(cat["id"]) }
+
+          logger.info "All inventory deleted"
+        end
+      end
+    end
+  end
+end

data/lib/clover_sandbox_simulator/services/clover/order_service.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+module CloverSandboxSimulator
+  module Services
+    module Clover
+      # Manages Clover orders and line items
+      class OrderService < BaseService
+        DINING_OPTIONS = %w[HERE TO_GO DELIVERY].freeze
+
+        # Fetch all orders
+        def get_orders(limit: 50, offset: 0, filter: nil)
+          logger.info "Fetching orders..."
+          params = { limit: limit, offset: offset }
+          params[:filter] = filter if filter
+
+          response = request(:get, endpoint("orders"), params: params)
+          response&.dig("elements") || []
+        end
+
+        # Get a single order with expanded data
+        def get_order(order_id)
+          request(:get, endpoint("orders/#{order_id}"), params: {
+            expand: "lineItems,discounts,payments,customers"
+          })
+        end
+
+        # Create an order shell
+        def create_order(employee_id: nil, customer_id: nil)
+          logger.info "Creating order..."
+
+          payload = {}
+          payload["employee"] = { "id" => employee_id } if employee_id
+
+          order = request(:post, endpoint("orders"), payload: payload)
+
+          if order && customer_id
+            add_customer_to_order(order["id"], customer_id)
+          end
+
+          order
+        end
+
+        # Add line item to order
+        def add_line_item(order_id, item_id:, quantity: 1, note: nil)
+          logger.debug "Adding item #{item_id} to order #{order_id}"
+
+          payload = {
+            "item" => { "id" => item_id },
+            "quantity" => quantity
+          }
+          payload["note"] = note if note
+
+          request(:post, endpoint("orders/#{order_id}/line_items"), payload: payload)
+        end
+
+        # Batch add line items (adds one by one as Clover doesn't support bulk)
+        def add_line_items(order_id, items)
+          logger.info "Adding #{items.size} items to order #{order_id}"
+
+          line_items = []
+          items.each do |item|
+            line_item = add_line_item(
+              order_id,
+              item_id: item[:item_id],
+              quantity: item[:quantity] || 1,
+              note: item[:note]
+            )
+            line_items << line_item if line_item
+          end
+
+          line_items
+        end
+
+        # Apply discount to order
+        def apply_discount(order_id, discount_id:, calculated_amount: nil)
+          logger.info "Applying discount #{discount_id} to order #{order_id}"
+
+          # Fetch discount details
+          discount_service = DiscountService.new(config: config)
+          discount = discount_service.get_discount(discount_id)
+
+          return nil unless discount
+
+          payload = { "name" => discount["name"] }
+
+          if calculated_amount
+            payload["amount"] = -calculated_amount.abs
+          elsif discount["amount"]
+            payload["amount"] = discount["amount"]
+          elsif discount["percentage"]
+            payload["percentage"] = discount["percentage"].to_s
+          end
+
+          request(:post, endpoint("orders/#{order_id}/discounts"), payload: payload)
+        end
+
+        # Set dining option
+        def set_dining_option(order_id, option)
+          unless DINING_OPTIONS.include?(option)
+            raise ArgumentError, "Invalid dining option: #{option}. Must be one of #{DINING_OPTIONS.join(', ')}"
+          end
+
+          request(:post, endpoint("orders/#{order_id}"), payload: { "diningOption" => option })
+        end
+
+        # Add customer to order
+        def add_customer_to_order(order_id, customer_id)
+          logger.debug "Adding customer #{customer_id} to order #{order_id}"
+          request(:post, endpoint("orders/#{order_id}"), payload: {
+            "customers" => { "elements" => [{ "id" => customer_id }] }
+          })
+        end
+
+        # Update order total
+        def update_total(order_id, total)
+          logger.debug "Updating order #{order_id} total to #{total}"
+          request(:post, endpoint("orders/#{order_id}"), payload: { "total" => total })
+        end
+
+        # Update order state
+        def update_state(order_id, state)
+          logger.info "Updating order #{order_id} state to #{state}"
+          request(:post, endpoint("orders/#{order_id}"), payload: { "state" => state })
+        end
+
+        # Calculate order total from line items
+        def calculate_total(order_id)
+          order = get_order(order_id)
+          return 0 unless order && order["lineItems"]&.dig("elements")
+
+          total = 0
+
+          order["lineItems"]["elements"].each do |line_item|
+            price = line_item["price"] || 0
+            quantity = line_item["quantity"] || 1
+            item_total = price * quantity
+
+            # Add modification prices
+            if line_item["modifications"]&.dig("elements")
+              line_item["modifications"]["elements"].each do |mod|
+                item_total += (mod["price"] || 0)
+              end
+            end
+
+            total += item_total
+          end
+
+          # Subtract discounts
+          if order["discounts"]&.dig("elements")
+            order["discounts"]["elements"].each do |discount|
+              if discount["percentage"]
+                total -= (total * discount["percentage"] / 100.0).round
+              else
+                total -= (discount["amount"] || 0).abs
+              end
+            end
+          end
+
+          total
+        end
+
+        # Delete an order
+        def delete_order(order_id)
+          logger.info "Deleting order: #{order_id}"
+          request(:delete, endpoint("orders/#{order_id}"))
+        end
+      end
+    end
+  end
+end

data/lib/clover_sandbox_simulator/services/clover/payment_service.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module CloverSandboxSimulator
+  module Services
+    module Clover
+      # Manages Clover payments
+      # NOTE: Credit/Debit card payments are BROKEN in Clover sandbox
+      # Use Cash, Check, Gift Card, External Payment, Store Credit instead
+      class PaymentService < BaseService
+        # Fetch all payments
+        def get_payments
+          logger.info "Fetching payments..."
+          response = request(:get, endpoint("payments"))
+          response&.dig("elements") || []
+        end
+
+        # Process a payment for an order
+        #
+        # @param order_id [String] The order ID
+        # @param amount [Integer] Subtotal amount in cents (before tip/tax)
+        # @param tender_id [String] The tender ID to use
+        # @param employee_id [String] The employee processing payment
+        # @param tip_amount [Integer] Tip amount in cents
+        # @param tax_amount [Integer] Tax amount in cents
+        # @return [Hash, nil] Payment response or nil on failure
+        def process_payment(order_id:, amount:, tender_id:, employee_id:, tip_amount: 0, tax_amount: 0)
+          logger.info "Processing payment for order #{order_id}: $#{amount / 100.0} + tip $#{tip_amount / 100.0} + tax $#{tax_amount / 100.0}"
+
+          payload = {
+            "order" => { "id" => order_id },
+            "tender" => { "id" => tender_id },
+            "employee" => { "id" => employee_id },
+            "offline" => false,
+            "amount" => amount,
+            "tipAmount" => tip_amount,
+            "taxAmount" => tax_amount,
+            "transactionSettings" => {
+              "disableCashBack" => false,
+              "cloverShouldHandleReceipts" => true,
+              "forcePinEntryOnSwipe" => false,
+              "disableRestartTransactionOnFailure" => false,
+              "allowOfflinePayment" => false,
+              "approveOfflinePaymentWithoutPrompt" => false,
+              "forceOfflinePayment" => false,
+              "disableReceiptSelection" => false,
+              "disableDuplicateCheck" => false,
+              "autoAcceptPaymentConfirmations" => false,
+              "autoAcceptSignature" => false,
+              "returnResultOnTransactionComplete" => false,
+              "disableCreditSurcharge" => false
+            }
+          }
+
+          response = request(:post, endpoint("orders/#{order_id}/payments"), payload: payload)
+
+          if response && response["id"]
+            logger.info "Payment successful: #{response["id"]}"
+          else
+            logger.error "Payment failed: #{response.inspect}"
+          end
+
+          response
+        end
+
+        # Process split payment across multiple tenders
+        #
+        # @param order_id [String] The order ID
+        # @param total_amount [Integer] Total amount including tax (before tip)
+        # @param tip_amount [Integer] Total tip amount
+        # @param tax_amount [Integer] Tax amount
+        # @param employee_id [String] Employee ID
+        # @param splits [Array<Hash>] Array of { tender:, percentage: } hashes
+        # @return [Array<Hash>] Array of payment responses
+        def process_split_payment(order_id:, total_amount:, tip_amount:, tax_amount:, employee_id:, splits:)
+          logger.info "Processing split payment for order #{order_id} across #{splits.size} tenders"
+
+          payments = []
+          remaining_amount = total_amount
+          remaining_tip = tip_amount
+
+          splits.each_with_index do |split, index|
+            tender = split[:tender]
+            percentage = split[:percentage]
+            is_last = (index == splits.size - 1)
+
+            # Calculate this payment's portion
+            if is_last
+              payment_amount = remaining_amount
+              payment_tip = remaining_tip
+            else
+              payment_amount = (total_amount * percentage / 100.0).round
+              payment_tip = (tip_amount * percentage / 100.0).round
+              remaining_amount -= payment_amount
+              remaining_tip -= payment_tip
+            end
+
+            # Tax only on first payment
+            payment_tax = index.zero? ? tax_amount : 0
+
+            payment = process_payment(
+              order_id: order_id,
+              amount: payment_amount,
+              tender_id: tender["id"],
+              employee_id: employee_id,
+              tip_amount: payment_tip,
+              tax_amount: payment_tax
+            )
+
+            payments << payment if payment
+          end
+
+          payments
+        end
+
+        # Generate a random tip amount (15-25% of subtotal)
+        def generate_tip(subtotal)
+          tip_percentage = rand(15..25)
+          (subtotal * tip_percentage / 100.0).round
+        end
+      end
+    end
+  end
+end

data/lib/clover_sandbox_simulator/services/clover/services_manager.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module CloverSandboxSimulator
+  module Services
+    module Clover
+      # Central manager for all Clover services
+      # Provides lazy-loaded access to all service classes
+      class ServicesManager
+        attr_reader :config
+
+        def initialize(config: nil)
+          @config = config || CloverSandboxSimulator.configuration
+        end
+
+        def inventory
+          @inventory ||= InventoryService.new(config: config)
+        end
+
+        def tender
+          @tender ||= TenderService.new(config: config)
+        end
+
+        def tax
+          @tax ||= TaxService.new(config: config)
+        end
+
+        def discount
+          @discount ||= DiscountService.new(config: config)
+        end
+
+        def order
+          @order ||= OrderService.new(config: config)
+        end
+
+        def payment
+          @payment ||= PaymentService.new(config: config)
+        end
+
+        def employee
+          @employee ||= EmployeeService.new(config: config)
+        end
+
+        def customer
+          @customer ||= CustomerService.new(config: config)
+        end
+      end
+    end
+  end
+end