Class: CloverSandboxSimulator::Services::Clover::ServiceChargeService

Inherits:
BaseService
  • Object
show all
Defined in:
lib/clover_sandbox_simulator/services/clover/service_charge_service.rb

Overview

Manages Clover service charges (auto-gratuity, large party fees, etc.)

Constant Summary collapse

AUTO_GRATUITY_NAME = 
"Auto Gratuity"
DEFAULT_AUTO_GRATUITY_PERCENTAGE = 
18.0

Instance Attribute Summary

Attributes inherited from BaseService

#config, #logger

Instance Method Summary collapse

Methods inherited from BaseService

#initialize

Constructor Details

This class inherits a constructor from CloverSandboxSimulator::Services::BaseService

Instance Method Details

#apply_service_charge_to_order(order_id, name:, percentage:, service_charge_id: nil) ⇒ Object

Apply a service charge to a specific order Clover requires either an existing service charge ID or creating one inline

Parameters:

  • order_id (String) —

    The order ID

  • name (String) —

    The name of the service charge

  • percentage (Float) —

    The percentage

  • service_charge_id (String, nil) (defaults to: nil) —

    Optional ID of existing service charge



54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
 
# File 'lib/clover_sandbox_simulator/services/clover/service_charge_service.rb', line 54

def apply_service_charge_to_order(order_id, name:, percentage:, service_charge_id: nil)
  logger.info "Applying service charge '#{name}' (#{percentage}%) to order #{order_id}"

  percentage_decimal = (percentage * 100).to_i

  # If we have an ID, use it; otherwise try to find or create one
  if service_charge_id.nil?
    # Check if a matching service charge already exists
    existing = get_service_charges.find { |sc| sc["name"]&.downcase == name.downcase }
    service_charge_id = existing&.dig("id")

    # If no existing charge, create one first
    if service_charge_id.nil?
      new_charge = create_service_charge(name: name, percentage: percentage)
      service_charge_id = new_charge&.dig("id")
    end
  end

  # If we still don't have an ID, we can't apply the charge
  if service_charge_id.nil?
    logger.warn "Could not create or find service charge, using inline approach"
    # Try inline approach with just the amount (not percentage)
    # This is a fallback for sandbox limitations
    return nil
  end

  payload = {
    "id" => service_charge_id,
    "name" => name,
    "percentageDecimal" => percentage_decimal
  }

  request(:post, endpoint("orders/#{order_id}/service_charge"), payload: payload)
end

#create_service_charge(name:, percentage:, enabled: true) ⇒ Object

Create a new service charge NOTE: In sandbox, service charges must be created via the Clover dashboard This method attempts the API call but gracefully handles failures

Parameters:

  • name (String) —

    The name of the service charge

  • percentage (Float) —

    The percentage (e.g., 18.0 for 18%)

  • enabled (Boolean) (defaults to: true) —

    Whether the charge is enabled



26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
 
# File 'lib/clover_sandbox_simulator/services/clover/service_charge_service.rb', line 26

def create_service_charge(name:, percentage:, enabled: true)
  logger.info "Creating service charge: #{name} (#{percentage}%)"

  # Clover uses percentageDecimal which is percentage * 100 (e.g., 18% = 1800)
  percentage_decimal = (percentage * 100).to_i

  payload = {
    "name" => name,
    "percentageDecimal" => percentage_decimal,
    "enabled" => enabled
  }

  begin
    request(:post, endpoint("default_service_charge"), payload: payload)
  rescue ApiError => e
    # Sandbox may not support POST to default_service_charge
    logger.warn "Could not create service charge via API: #{e.message}"
    logger.info "Service charges must be configured in Clover dashboard"
    nil
  end
end

#get_auto_gratuity_charge ⇒ Object

Get the auto-gratuity service charge if it exists



90
91
92
93
 
# File 'lib/clover_sandbox_simulator/services/clover/service_charge_service.rb', line 90

def get_auto_gratuity_charge
  charges = get_service_charges
  charges.find { |c| c["name"]&.downcase&.include?("auto") || c["name"]&.downcase&.include?("gratuity") }
end

#get_service_charges ⇒ Object

Fetch all service charges for the merchant



12
13
14
15
16
17
18
 
# File 'lib/clover_sandbox_simulator/services/clover/service_charge_service.rb', line 12

def get_service_charges
  logger.info "Fetching service charges..."
  response = request(:get, endpoint("default_service_charge"))
  charges = response&.dig("elements") || []
  logger.info "Found #{charges.size} service charges"
  charges
end

#setup_auto_gratuity(percentage: DEFAULT_AUTO_GRATUITY_PERCENTAGE) ⇒ Object

Setup default auto-gratuity service charge if it doesn’t exist



96
97
98
99
100
101
102
103
104
105
106
107
108
 
# File 'lib/clover_sandbox_simulator/services/clover/service_charge_service.rb', line 96

def setup_auto_gratuity(percentage: DEFAULT_AUTO_GRATUITY_PERCENTAGE)
  existing = get_auto_gratuity_charge

  if existing
    logger.info "Auto-gratuity service charge already exists: #{existing['name']}"
    return existing
  end

  create_service_charge(
    name: AUTO_GRATUITY_NAME,
    percentage: percentage
  )
end