clover_sandbox_simulator 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: dc73877a0d3dbbce2dfe5b038167864972933519265d341665ee23646f37f5c1
+  data.tar.gz: 808ede5d13382014d7c2ab5f58379160c0983b7db8ead184032b70a5f39b453a
+SHA512:
+  metadata.gz: afdb2f5ddd9026721f63328fb2efd4cc97799d952fea3288d8b090ca4daab696719df353eb8d515aafdfe5b62b165798cbde650cb9ffabaf7e827fae1487a321
+  data.tar.gz: 1218800960726b410b98d5b8d0ca7cfed1aed9a1f916214a257d456ca08373123724764ec04680d1eabde7ebd9f25d98d77a43301d54ee5d0fa2ca74000b7873

data/Gemfile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gemspec
+
+group :development, :test do
+  gem "pry", "~> 0.14"
+  gem "pry-byebug", "~> 3.10"
+end

data/README.md

@@ -0,0 +1,316 @@
+# Clover Sandbox Simulator
+
+A Ruby gem for simulating Point of Sale operations in Clover sandbox environments. Generates realistic restaurant orders, payments, and transaction data for testing integrations with Clover's API.
+
+## Features
+
+- **Realistic Restaurant Data**: Complete menu with 39 items across 7 categories (appetizers, entrees, sides, desserts, drinks, alcoholic beverages, specials)
+- **Safe Sandbox Payments**: Uses Cash, Check, Gift Card, and other safe tenders (avoids broken Credit/Debit cards in Clover sandbox)
+- **Split Payments**: Supports 1-4 tender splits per order, more common for larger parties
+- **Meal Period Simulation**: Orders distributed across breakfast, lunch, happy hour, dinner, and late night with realistic weights
+- **Dining Options**: Dine-in, To-Go, and Delivery with period-appropriate distributions
+- **Dynamic Order Volume**: Different order counts for weekdays, Friday, Saturday, Sunday (40-120 orders/day)
+- **Tips & Taxes**: Variable tip rates by dining option (15-25% dine-in, 0-15% takeout, 10-20% delivery)
+- **Discounts**: 7 discount types including Happy Hour, Senior, Military, Employee, Birthday, and fixed amounts
+- **Employees & Customers**: Auto-generated with realistic names and contact info
+- **Party Size Variation**: 1-6 guests affecting item counts and split payment probability
+- **Order Notes**: Random special instructions (allergies, modifications, VIP customers)
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'clover_sandbox_simulator'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install clover_sandbox_simulator
+```
+
+## Configuration
+
+Copy the sample environment file and configure your Clover credentials:
+
+```bash
+cp .env.sample .env
+```
+
+Edit `.env` with your Clover sandbox credentials:
+
+```env
+CLOVER_MERCHANT_ID=your_merchant_id
+CLOVER_API_TOKEN=your_api_token
+CLOVER_ENVIRONMENT=https://sandbox.dev.clover.com/
+LOG_LEVEL=INFO
+TAX_RATE=8.25
+```
+
+## Usage
+
+### Quick Start
+
+Run a full simulation (setup + generate orders):
+
+```bash
+./bin/simulate full
+```
+
+### Commands
+
+```bash
+# Set up restaurant entities (categories, items, discounts, etc.)
+./bin/simulate setup
+
+# Generate orders for today (random count based on day of week)
+./bin/simulate generate
+
+# Generate a specific number of orders
+./bin/simulate generate -n 25
+
+# Generate a realistic full day of restaurant operations
+./bin/simulate day
+
+# Generate a busy day (2x normal volume)
+./bin/simulate day -m 2.0
+
+# Generate a slow day (0.5x normal volume)
+./bin/simulate day -m 0.5
+
+# Generate a lunch or dinner rush
+./bin/simulate rush -p lunch -n 20
+./bin/simulate rush -p dinner -n 30
+
+# Run full simulation (setup + orders)
+./bin/simulate full
+
+# Check current status
+./bin/simulate status
+
+# Delete all entities (requires confirmation)
+./bin/simulate delete --confirm
+
+# Enable verbose logging
+./bin/simulate generate -v
+```
+
+## Menu Structure
+
+### Categories
+- Appetizers
+- Entrees
+- Sides
+- Desserts
+- Drinks
+- Alcoholic Beverages
+- Specials
+
+### Sample Items
+
+| Category | Item | Price |
+|----------|------|-------|
+| Appetizers | Buffalo Wings | $12.99 |
+| Appetizers | Loaded Nachos | $10.99 |
+| Entrees | Classic Burger | $14.99 |
+| Entrees | NY Strip Steak | $28.99 |
+| Entrees | Grilled Salmon | $21.99 |
+| Sides | French Fries | $4.99 |
+| Desserts | Cheesecake | $7.99 |
+| Drinks | Soft Drink | $2.99 |
+| Alcoholic | Draft Beer | $5.99 |
+
+## Payment Tenders
+
+**IMPORTANT**: Credit Card and Debit Card are **broken** in Clover sandbox. This gem intentionally avoids them.
+
+Safe tenders used:
+- Cash (preferred for orders under $20)
+- Check
+- Gift Card
+- External Payment
+- Mobile Payment
+- Store Credit
+
+The simulator uses whatever safe tenders are available in the Clover merchant account.
+
+## Tips
+
+Tips vary by dining option to simulate realistic customer behavior:
+
+| Dining Option | Min Tip | Max Tip |
+|---------------|---------|---------|
+| Dine-In (HERE) | 15% | 25% |
+| To-Go | 0% | 15% |
+| Delivery | 10% | 20% |
+
+- Large parties (6+) automatically receive 18% auto-gratuity
+- Split payments divide tips proportionally across tenders
+
+## Order Patterns
+
+### Daily Volume
+
+| Day | Min Orders | Max Orders |
+|-----|------------|------------|
+| Weekday | 40 | 60 |
+| Friday | 70 | 100 |
+| Saturday | 80 | 120 |
+| Sunday | 50 | 80 |
+
+### Meal Periods
+
+Orders are distributed across realistic meal periods with weighted distribution:
+
+| Period | Hours | Weight | Avg Items | Avg Party Size |
+|--------|-------|--------|-----------|----------------|
+| Breakfast | 7-10 AM | 15% | 2-4 | 1-2 |
+| Lunch | 11 AM-2 PM | 30% | 2-5 | 1-4 |
+| Happy Hour | 3-5 PM | 10% | 2-4 | 2-4 |
+| Dinner | 5-9 PM | 35% | 3-6 | 2-6 |
+| Late Night | 9-11 PM | 10% | 2-4 | 1-3 |
+
+### Dining Options
+
+Each meal period has different dining option distributions:
+
+| Period | Dine-In | To-Go | Delivery |
+|--------|---------|-------|----------|
+| Breakfast | 40% | 50% | 10% |
+| Lunch | 35% | 45% | 20% |
+| Happy Hour | 80% | 15% | 5% |
+| Dinner | 70% | 15% | 15% |
+| Late Night | 50% | 30% | 20% |
+
+## Architecture
+
+```
+clover_sandbox_simulator/
+├── bin/simulate                      # CLI entry point
+├── lib/
+│   ├── clover_sandbox_simulator.rb   # Gem entry point
+│   └── clover_sandbox_simulator/
+│       ├── configuration.rb          # Environment config
+│       ├── services/
+│       │   ├── base_service.rb
+│       │   └── clover/               # Clover API services
+│       │       ├── inventory_service.rb
+│       │       ├── order_service.rb
+│       │       ├── payment_service.rb
+│       │       ├── tender_service.rb
+│       │       ├── tax_service.rb
+│       │       ├── discount_service.rb
+│       │       ├── employee_service.rb
+│       │       ├── customer_service.rb
+│       │       └── services_manager.rb
+│       ├── generators/
+│       │   ├── data_loader.rb
+│       │   ├── entity_generator.rb
+│       │   └── order_generator.rb
+│       └── data/
+│           └── restaurant/           # JSON data files
+│               ├── categories.json
+│               ├── items.json
+│               ├── discounts.json
+│               ├── tenders.json
+│               └── modifiers.json
+└── spec/                             # RSpec tests
+```
+
+## Development
+
+```bash
+# Run all tests
+bundle exec rspec
+
+# Run tests with documentation format
+bundle exec rspec --format documentation
+
+# Run specific test file
+bundle exec rspec spec/services/clover/tender_service_spec.rb
+
+# Run linter
+bundle exec rubocop
+
+# Open console
+bundle exec irb -r ./lib/clover_sandbox_simulator
+```
+
+## Testing
+
+The gem includes comprehensive RSpec tests with WebMock for HTTP stubbing.
+
+### Test Coverage
+
+- **268 examples, 0 failures**
+- Configuration validation
+- Data loading from JSON files
+- All Clover API services:
+  - InventoryService (categories, items)
+  - OrderService (create, line items, dining options)
+  - PaymentService (single and split payments)
+  - TenderService (safe tenders, split selection)
+  - TaxService (rates, calculation)
+  - DiscountService (percentage and fixed)
+  - EmployeeService (CRUD, random selection)
+  - CustomerService (CRUD, anonymous orders)
+  - ServicesManager (memoization, lazy loading)
+- Entity generator idempotency
+- Order generator (meal periods, dining options, tips)
+- Edge cases (nil handling, empty arrays, API errors)
+
+### Test Files
+
+```
+spec/
+├── configuration_spec.rb
+├── generators/
+│   ├── data_loader_spec.rb
+│   ├── entity_generator_spec.rb
+│   └── order_generator_spec.rb
+└── services/clover/
+    ├── customer_service_spec.rb
+    ├── discount_service_spec.rb
+    ├── employee_service_spec.rb
+    ├── inventory_service_spec.rb
+    ├── order_service_spec.rb
+    ├── payment_service_spec.rb
+    ├── services_manager_spec.rb
+    ├── tax_service_spec.rb
+    └── tender_service_spec.rb
+```
+
+### Idempotency Verification
+
+All setup operations are idempotent - running them multiple times will not create duplicates:
+
+```ruby
+# This is safe to run multiple times
+generator = CloverSandboxSimulator::Generators::EntityGenerator.new
+generator.setup_all # First run: creates entities
+generator.setup_all # Second run: skips existing, returns same results
+```
+
+The tests verify:
+- Categories are not duplicated
+- Items are not duplicated
+- Discounts are not duplicated
+- Employees/customers only created if count threshold not met
+
+## Clover API Notes
+
+- **Sandbox URL**: `https://sandbox.dev.clover.com/`
+- **API Version**: v3
+- **Authentication**: Bearer token (OAuth)
+- **Date Limitation**: Clover sandbox only allows creating orders for TODAY
+
+## License
+
+MIT License

data/bin/simulate

@@ -0,0 +1,209 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "clover_sandbox_simulator"
+require "thor"
+
+module CloverSandboxSimulator
+  # Command-line interface for Clover Sandbox Simulator
+  class CLI < Thor
+    class_option :verbose, type: :boolean, aliases: "-v", desc: "Enable verbose logging"
+
+    desc "setup", "Set up restaurant entities (categories, items, discounts, employees, customers)"
+    option :business_type, type: :string, default: "restaurant", desc: "Business type (restaurant, retail, salon)"
+    def setup
+      configure_logging
+
+      puts "🍽️  Clover Sandbox Simulator - Entity Setup"
+      puts "=" * 50
+
+      generator = Generators::EntityGenerator.new(business_type: options[:business_type].to_sym)
+      generator.setup_all
+
+      puts "\n✅ Setup complete!"
+    end
+
+    desc "generate", "Generate orders for today"
+    option :count, type: :numeric, aliases: "-n", desc: "Number of orders to generate"
+    def generate
+      configure_logging
+
+      puts "🍽️  Clover Sandbox Simulator - Order Generation"
+      puts "=" * 50
+
+      generator = Generators::OrderGenerator.new
+      count = options[:count]
+
+      orders = generator.generate_today(count: count)
+
+      puts "\n✅ Generated #{orders.size} orders!"
+    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)"
+    def day
+      configure_logging
+
+      puts "🍽️  Clover Sandbox Simulator - Realistic Restaurant Day"
+      puts "=" * 50
+
+      generator = Generators::OrderGenerator.new
+      orders = generator.generate_realistic_day(multiplier: options[:multiplier])
+
+      puts "\n✅ Generated #{orders.size} orders!"
+    end
+
+    desc "rush", "Generate a lunch or dinner rush"
+    option :period, type: :string, aliases: "-p", default: "dinner", desc: "Meal period (breakfast, lunch, happy_hour, dinner, late_night)"
+    option :count, type: :numeric, aliases: "-n", default: 15, desc: "Number of orders"
+    def rush
+      configure_logging
+
+      period = options[:period].to_sym
+      count = options[:count]
+
+      puts "🍽️  Clover Sandbox Simulator - #{period.to_s.upcase} Rush"
+      puts "=" * 50
+
+      generator = Generators::OrderGenerator.new
+      data = generator.send(:fetch_required_data)
+
+      unless data
+        puts "❌ Failed to fetch data. Run setup first."
+        return
+      end
+
+      orders = []
+      count.times do |i|
+        order = generator.send(:create_realistic_order,
+          period: period,
+          data: data,
+          order_num: i + 1,
+          total_in_period: count
+        )
+
+        if order
+          orders << order
+          generator.send(:update_stats, order, period)
+        end
+      end
+
+      generator.send(:print_summary)
+      puts "\n✅ Generated #{orders.size} #{period} orders!"
+    end
+
+    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"
+    def full
+      configure_logging
+
+      puts "🍽️  Clover Sandbox Simulator - Full Simulation"
+      puts "=" * 50
+
+      # Setup entities
+      entity_gen = Generators::EntityGenerator.new(business_type: options[:business_type].to_sym)
+      entity_gen.setup_all
+
+      puts "\n"
+
+      # Generate orders
+      order_gen = Generators::OrderGenerator.new
+      orders = order_gen.generate_today(count: options[:count])
+
+      puts "\n✅ Full simulation complete!"
+      puts "   Orders generated: #{orders.size}"
+    end
+
+    desc "delete", "Delete all entities (use with caution!)"
+    option :confirm, type: :boolean, desc: "Confirm deletion"
+    def delete
+      unless options[:confirm]
+        puts "⚠️  This will delete ALL entities from Clover!"
+        puts "   Run with --confirm to proceed."
+        return
+      end
+
+      configure_logging
+
+      puts "🗑️  Deleting all entities..."
+
+      generator = Generators::EntityGenerator.new
+      generator.delete_all
+
+      puts "\n✅ All entities deleted!"
+    end
+
+    desc "status", "Show current Clover merchant status"
+    def status
+      configure_logging
+
+      puts "🍽️  Clover Sandbox Simulator - Status"
+      puts "=" * 50
+
+      services = Services::Clover::ServicesManager.new
+
+      categories = services.inventory.get_categories
+      items = services.inventory.get_items
+      tenders = services.tender.get_safe_tenders
+      employees = services.employee.get_employees
+      customers = services.customer.get_customers
+      discounts = services.discount.get_discounts
+
+      puts "Categories:  #{categories.size}"
+      puts "Menu Items:  #{items.size}"
+      puts "Tenders:     #{tenders.size} (sandbox-safe)"
+      puts "Employees:   #{employees.size}"
+      puts "Customers:   #{customers.size}"
+      puts "Discounts:   #{discounts.size}"
+
+      puts "\n📋 Categories:"
+      categories.each { |c| puts "   - #{c['name']}" }
+
+      puts "\n💳 Safe Tenders (no credit/debit):"
+      tenders.each { |t| puts "   - #{t['label']}" }
+    end
+
+    desc "version", "Show version"
+    def version
+      puts "Clover Sandbox Simulator v1.0.0"
+    end
+
+    private
+
+    def configure_logging
+      if options[:verbose]
+        CloverSandboxSimulator.configuration.logger.level = Logger::DEBUG
+      else
+        CloverSandboxSimulator.configuration.logger.level = Logger::INFO
+      end
+    end
+
+    def print_order_summary(orders)
+      return if orders.empty?
+
+      total_revenue = 0
+      total_tips = 0
+      total_tax = 0
+
+      orders.each do |order|
+        next unless order && order["payments"]&.dig("elements")
+
+        order["payments"]["elements"].each do |payment|
+          total_revenue += payment["amount"] || 0
+          total_tips += payment["tipAmount"] || 0
+          total_tax += payment["taxAmount"] || 0
+        end
+      end
+
+      puts "\n📊 Summary:"
+      puts "   Revenue:  $#{total_revenue / 100.0}"
+      puts "   Tips:     $#{total_tips / 100.0}"
+      puts "   Tax:      $#{total_tax / 100.0}"
+      puts "   Total:    $#{(total_revenue + total_tips + total_tax) / 100.0}"
+    end
+  end
+end
+
+CloverSandboxSimulator::CLI.start(ARGV)

data/lib/clover_sandbox_simulator/configuration.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module CloverSandboxSimulator
+  class Configuration
+    attr_accessor :merchant_id, :api_token, :environment, :log_level, :tax_rate, :business_type
+
+    def initialize
+      @merchant_id   = ENV.fetch("CLOVER_MERCHANT_ID", 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
+    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?
+
+      true
+    end
+
+    def logger
+      @logger ||= Logger.new($stdout).tap do |log|
+        log.level = @log_level
+        log.formatter = proc do |severity, datetime, _progname, msg|
+          timestamp = datetime.strftime("%Y-%m-%d %H:%M:%S")
+          "[#{timestamp}] #{severity.ljust(5)} | #{msg}\n"
+        end
+      end
+    end
+
+    private
+
+    def normalize_url(url)
+      url = url.strip
+      url.end_with?("/") ? url : "#{url}/"
+    end
+
+    def parse_log_level(level)
+      case level.to_s.upcase
+      when "DEBUG" then Logger::DEBUG
+      when "INFO"  then Logger::INFO
+      when "WARN"  then Logger::WARN
+      when "ERROR" then Logger::ERROR
+      when "FATAL" then Logger::FATAL
+      else Logger::INFO
+      end
+    end
+  end
+end

data/lib/clover_sandbox_simulator/data/restaurant/categories.json

@@ -0,0 +1,39 @@
+{
+  "categories": [
+    {
+      "name": "Appetizers",
+      "sort_order": 1,
+      "description": "Start your meal right"
+    },
+    {
+      "name": "Entrees",
+      "sort_order": 2,
+      "description": "Main courses"
+    },
+    {
+      "name": "Sides",
+      "sort_order": 3,
+      "description": "Perfect accompaniments"
+    },
+    {
+      "name": "Desserts",
+      "sort_order": 4,
+      "description": "Sweet endings"
+    },
+    {
+      "name": "Drinks",
+      "sort_order": 5,
+      "description": "Non-alcoholic beverages"
+    },
+    {
+      "name": "Alcoholic Beverages",
+      "sort_order": 6,
+      "description": "Beer, wine, and cocktails"
+    },
+    {
+      "name": "Specials",
+      "sort_order": 7,
+      "description": "Chef's daily specials"
+    }
+  ]
+}

data/lib/clover_sandbox_simulator/data/restaurant/discounts.json

@@ -0,0 +1,39 @@
+{
+  "discounts": [
+    {
+      "name": "Happy Hour",
+      "percentage": 15,
+      "description": "15% off during happy hour (3-6 PM)"
+    },
+    {
+      "name": "Senior Discount",
+      "percentage": 10,
+      "description": "10% off for seniors 65+"
+    },
+    {
+      "name": "Military Discount",
+      "percentage": 15,
+      "description": "15% off for active duty and veterans"
+    },
+    {
+      "name": "Employee Discount",
+      "percentage": 25,
+      "description": "25% off for employees"
+    },
+    {
+      "name": "Birthday Special",
+      "percentage": 20,
+      "description": "20% off for birthday celebrations"
+    },
+    {
+      "name": "$5 Off",
+      "amount": 500,
+      "description": "$5 off orders over $30"
+    },
+    {
+      "name": "$10 Off",
+      "amount": 1000,
+      "description": "$10 off orders over $50"
+    }
+  ]
+}