skytab_sandbox_simulator 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 34ae23cd46e19a75fe126e54846f50c9e0f3641be805762af8bf9ee8d8c820c5
+  data.tar.gz: 40b36d73dccbd5de18a4ab1d0726c53f2f457ef8cb855ed65d55ff68ea5752c9
+SHA512:
+  metadata.gz: be9f3f2b773aa3cf624a07fc8ac958f28af03ac2383b26ae902c37d83c5380a1bcc8d8ec8d6fa61af78a4c635eed88a1ecc0d36b86f8e31f6b81ed0550c7089b
+  data.tar.gz: 91972a8d53fbbc80981b6a93b0f6f95eb9f701accec86f9226526943328508b44724415b0a51f64a1e0464b211e7175844349b766d923e3f1ab348c7651ffded

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/bin/simulate

@@ -0,0 +1,433 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "skytab_sandbox_simulator"
+require "thor"
+
+module SkytabSandboxSimulator
+  # Command-line interface for SkyTab Sandbox Simulator
+  class CLI < Thor
+    class_option :verbose, type: :boolean, aliases: "-v", desc: "Enable verbose logging"
+    class_option :location, type: :string, aliases: "-l", desc: "Location ID to use (from .env.json)"
+    class_option :location_index, type: :numeric, aliases: "-i", desc: "Location index to use (0-based, from .env.json)"
+
+    desc "locations", "List available locations from .env.json"
+    def locations
+      puts "SkyTab Sandbox Simulator - Available Locations"
+      puts "=" * 60
+
+      config = SkytabSandboxSimulator.configuration
+      locs = config.available_locations
+
+      if locs.empty?
+        puts "No locations found in .env.json"
+        return
+      end
+
+      puts "\n#{'Index'.ljust(6)} #{'Location ID'.ljust(16)} #{'Name'.ljust(25)} #{'Timezone'}"
+      puts "-" * 70
+
+      locs.each_with_index do |loc, idx|
+        tz = loc[:timezone] || "N/A"
+        puts "#{idx.to_s.ljust(6)} #{(loc[:id] || 'N/A').ljust(16)} #{(loc[:name] || 'N/A')[0..23].ljust(25)} #{tz}"
+      end
+
+      puts "\nUse: simulate <command> -i <index> or -l <location_id>"
+    end
+
+    desc "setup", "Set up entities (categories, items)"
+    option :business_type, type: :string, default: "restaurant", desc: "Business type"
+    def setup
+      configure_logging
+
+      puts "SkyTab Sandbox Simulator - Entity Setup"
+      puts "=" * 50
+
+      generator = Generators::EntityGenerator.new(business_type: options[:business_type].to_sym)
+      generator.setup_all
+
+      puts "\nSetup complete!"
+    end
+
+    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 "SkyTab Sandbox Simulator - Order Generation"
+      puts "=" * 50
+
+      generator = Generators::OrderGenerator.new(refund_percentage: options[:refund_percentage])
+      orders = generator.generate_today(count: options[:count])
+
+      puts "\nGenerated #{orders.size} orders!"
+    end
+
+    desc "day", "Generate a realistic full day of operations"
+    option :multiplier, type: :numeric, aliases: "-x", default: 1.0, desc: "Order multiplier"
+    option :refund_percentage, type: :numeric, aliases: "-r", default: 5,
+           desc: "Percentage of orders to refund"
+    def day
+      configure_logging
+
+      puts "SkyTab Sandbox Simulator - Realistic Day"
+      puts "=" * 50
+
+      generator = Generators::OrderGenerator.new(refund_percentage: options[:refund_percentage])
+      orders = generator.generate_realistic_day(multiplier: options[:multiplier])
+
+      puts "\nGenerated #{orders.size} 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"
+    option :refund_percentage, type: :numeric, aliases: "-r", default: 5,
+           desc: "Percentage of orders to refund"
+    def full
+      configure_logging
+
+      puts "SkyTab 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(refund_percentage: options[:refund_percentage])
+      orders = order_gen.generate_today(count: options[:count])
+
+      puts "\nFull simulation complete!"
+      puts "   Orders generated: #{orders.size}"
+    end
+
+    desc "status", "Show current SkyTab location status"
+    def status
+      configure_logging
+
+      puts "SkyTab Sandbox Simulator - Status"
+      puts "=" * 50
+
+      services = Services::Skytab::ServiceManager.new
+
+      location = services.location.get_current_location
+      if location
+        puts "\nLocation:"
+        puts "   ID:       #{location['id']}"
+        puts "   Name:     #{location['name']}"
+        puts "   Timezone: #{location['timeZone']}"
+        puts "   Currency: #{location['currency']}"
+      end
+
+      categories = services.catalog.get_categories
+      items = services.catalog.get_items
+      taxes = services.catalog.get_taxes
+
+      puts "\nEntity Counts:"
+      puts "   Categories: #{categories.size}"
+      puts "   Items:      #{items.size}"
+      puts "   Tax Rates:  #{taxes.size}"
+
+      puts "\nCategories:"
+      categories.each { |c| puts "   - #{c['name']}" }
+
+      puts "\nTax Rates:"
+      taxes.each do |t|
+        rate_pct = (t["rate"] || 0) / 10_000.0
+        puts "   - #{t['name']}: #{rate_pct}%"
+      end
+    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 SkyTab!"
+        puts "   Run with --confirm to proceed."
+        return
+      end
+
+      configure_logging
+
+      puts "Deleting all entities..."
+
+      generator = Generators::EntityGenerator.new
+      generator.delete_all
+
+      puts "\nAll entities deleted!"
+    end
+
+    desc "version", "Show version"
+    def version
+      puts "SkyTab Sandbox Simulator v#{SkytabSandboxSimulator::VERSION}"
+    end
+
+    # ============================================
+    # Database Management Commands (db: namespace)
+    # ============================================
+
+    desc "db SUBCOMMAND", "Database management commands"
+    subcommand "db", Class.new(Thor) {
+      def self.banner(task, namespace = true, subcommand = true)
+        "simulate db #{task.usage}"
+      end
+
+      namespace "db"
+
+      desc "create", "Create the PostgreSQL database"
+      def create
+        db = SkytabSandboxSimulator::Database
+        url = db.database_url
+        puts "Creating database..."
+        db.create!(url)
+        puts "Done."
+      rescue SkytabSandboxSimulator::Error => e
+        puts "Error: #{e.message}"
+        exit 1
+      end
+
+      desc "migrate", "Run pending migrations"
+      def migrate
+        db = SkytabSandboxSimulator::Database
+        url = db.database_url
+        puts "Connecting and running migrations..."
+        db.connect!(url)
+        db.migrate!
+        puts "Done."
+      rescue SkytabSandboxSimulator::Error => e
+        puts "Error: #{e.message}"
+        exit 1
+      end
+
+      desc "seed", "Seed the database with realistic data via FactoryBot"
+      option :type, type: :string, desc: "Business type to seed (e.g. restaurant, cafe_bakery). Seeds all if omitted."
+      def seed
+        db = SkytabSandboxSimulator::Database
+        url = db.database_url
+        puts "Connecting and seeding..."
+        db.connect!(url)
+        bt = options[:type]&.to_sym
+        result = db.seed!(business_type: bt)
+        puts "Seeded: #{result[:business_types]} business types, #{result[:categories]} categories, #{result[:items]} items"
+        puts "  (#{result[:created]} created, #{result[:found]} already existed)"
+      rescue SkytabSandboxSimulator::Error => e
+        puts "Error: #{e.message}"
+        exit 1
+      end
+
+      desc "reset", "Drop, create, migrate, and seed the database"
+      option :type, type: :string, desc: "Business type to seed. Seeds all if omitted."
+      option :confirm, type: :boolean, desc: "Confirm destructive operation"
+      def reset
+        unless options[:confirm]
+          puts "This will DROP and recreate the database. All data will be lost."
+          puts "Run with --confirm to proceed."
+          return
+        end
+
+        db = SkytabSandboxSimulator::Database
+        url = db.database_url
+
+        puts "Dropping database..."
+        db.drop!(url)
+
+        puts "Creating database..."
+        db.create!(url)
+
+        puts "Connecting and running migrations..."
+        db.connect!(url)
+        db.migrate!
+
+        puts "Seeding..."
+        bt = options[:type]&.to_sym
+        result = db.seed!(business_type: bt)
+        puts "Seeded: #{result[:business_types]} business types, #{result[:categories]} categories, #{result[:items]} items"
+        puts "Done."
+      rescue SkytabSandboxSimulator::Error => e
+        puts "Error: #{e.message}"
+        exit 1
+      end
+    }
+
+    # ============================================
+    # Audit & Reporting Commands
+    # ============================================
+
+    desc "summary", "Show daily summary for current location"
+    option :date, type: :string, aliases: "-d", desc: "Date (YYYY-MM-DD, default: today)"
+    def summary
+      configure_logging
+      require_db_connection!
+
+      date = options[:date] ? Date.parse(options[:date]) : Date.today
+      location_id = SkytabSandboxSimulator.configuration.location_id
+
+      s = Models::DailySummary.for_location(location_id).on_date(date).first
+
+      unless s
+        puts "No summary found for location #{location_id} on #{date}."
+        puts "Run 'simulate generate' to create orders first."
+        return
+      end
+
+      puts "Daily Summary: #{date}"
+      puts "=" * 50
+      puts "  Location:      #{location_id}"
+      puts "  Orders:        #{s.order_count}"
+      puts "  Payments:      #{s.payment_count}"
+      puts "  Refunds:       #{s.refund_count}"
+      puts ""
+      puts "  Revenue:       #{format_cents(s.total_revenue)}"
+      puts "  Tax:           #{format_cents(s.total_tax)}"
+      puts "  Tips:          #{format_cents(s.total_tips)}"
+      puts "  Discounts:     #{format_cents(s.total_discounts)}"
+
+      breakdown = s.breakdown || {}
+
+      if breakdown["by_meal_period"]&.any?
+        puts ""
+        puts "  By Meal Period:"
+        breakdown["by_meal_period"].each do |period, count|
+          rev = breakdown.dig("revenue_by_meal_period", period) || 0
+          puts "    #{period.ljust(15)} #{count.to_s.rjust(3)} orders  #{format_cents(rev)}"
+        end
+      end
+
+      if breakdown["by_revenue_class"]&.any?
+        puts ""
+        puts "  By Revenue Class:"
+        breakdown["by_revenue_class"].each do |rc, count|
+          rev = breakdown.dig("revenue_by_revenue_class", rc) || 0
+          puts "    #{rc.ljust(15)} #{count.to_s.rjust(3)} orders  #{format_cents(rev)}"
+        end
+      end
+
+      if breakdown["by_tender"]&.any?
+        puts ""
+        puts "  By Tender:"
+        breakdown["by_tender"].each do |tender, count|
+          puts "    #{tender.ljust(20)} #{count} payments"
+        end
+      end
+    end
+
+    desc "audit", "Show recent API requests"
+    option :limit, type: :numeric, aliases: "-l", default: 20, desc: "Number of requests to show"
+    option :errors, type: :boolean, aliases: "-e", desc: "Show only error requests"
+    def audit
+      configure_logging
+      require_db_connection!
+
+      scope = Models::ApiRequest.order(created_at: :desc)
+      scope = scope.errors if options[:errors]
+      requests = scope.limit(options[:limit])
+
+      if requests.empty?
+        label = options[:errors] ? "error " : ""
+        puts "No #{label}API requests found."
+        return
+      end
+
+      label = options[:errors] ? "Error " : ""
+      puts "Recent #{label}API Requests (#{requests.size})"
+      puts "=" * 80
+
+      requests.each do |req|
+        status_indicator = req.error_message ? "ERR" : "OK "
+        ts = req.created_at.strftime("%H:%M:%S")
+        duration = req.duration_ms ? "#{req.duration_ms}ms" : "N/A"
+
+        puts "#{status_indicator} #{ts} #{req.http_method.ljust(6)} #{req.response_status || '---'} " \
+             "#{duration.rjust(7)}  #{truncate_url(req.url, 50)}"
+
+        puts "    Error: #{req.error_message[0..80]}" if req.error_message
+      end
+
+      total = Models::ApiRequest.count
+      errors = Models::ApiRequest.errors.count
+      puts "\nTotal: #{total} requests, #{errors} errors"
+    end
+
+    desc "business_types", "List business types with category and item counts"
+    def business_types
+      configure_logging
+      require_db_connection!
+
+      types = Models::BusinessType.all.order(:key)
+
+      if types.empty?
+        puts "No business types found. Run 'simulate db seed' first."
+        return
+      end
+
+      puts "Business Types"
+      puts "=" * 60
+      puts "#{'Key'.ljust(20)} #{'Industry'.ljust(10)} #{'Categories'.rjust(10)} #{'Items'.rjust(8)}"
+      puts "-" * 60
+
+      total_cats = 0
+      total_items = 0
+
+      types.each do |bt|
+        cat_count = bt.categories.count
+        item_count = Models::Item.for_business_type(bt.key).count
+        total_cats += cat_count
+        total_items += item_count
+
+        industry = bt.industry || "N/A"
+        puts "#{bt.key.ljust(20)} #{industry.ljust(10)} #{cat_count.to_s.rjust(10)} #{item_count.to_s.rjust(8)}"
+      end
+
+      puts "-" * 60
+      puts "#{'TOTAL'.ljust(20)} #{' '.ljust(10)} #{total_cats.to_s.rjust(10)} #{total_items.to_s.rjust(8)}"
+    end
+
+    private
+
+    def format_cents(cents)
+      "$#{'%.2f' % ((cents || 0) / 100.0)}"
+    end
+
+    def require_db_connection!
+      url = Database.database_url
+      Database.connect!(url) unless Database.connected?
+    rescue Error => e
+      puts "Database not available: #{e.message}"
+      puts "Run 'simulate db create && simulate db migrate' first."
+      exit 1
+    end
+
+    def truncate_url(url, max_length)
+      return url if url.nil? || url.length <= max_length
+
+      "...#{url[-(max_length - 3)..]}"
+    end
+
+    def configure_logging
+      config = SkytabSandboxSimulator.configuration
+
+      if options[:verbose]
+        config.logger.level = Logger::DEBUG
+      else
+        config.logger.level = Logger::INFO
+      end
+
+      # Load specific location if specified
+      if options[:location]
+        config.load_location(location_id: options[:location])
+      elsif options[:location_index]
+        config.load_location(index: options[:location_index])
+      end
+
+      puts "Using location: #{config.location_name} (#{config.location_id})"
+    end
+  end
+end
+
+SkytabSandboxSimulator::CLI.start(ARGV)

data/lib/skytab_sandbox_simulator/configuration.rb

@@ -0,0 +1,205 @@
+# frozen_string_literal: true
+
+module SkytabSandboxSimulator
+  class Configuration
+    attr_accessor :location_id, :location_name, :access_token, :environment, :log_level,
+                  :tax_rate, :business_type, :merchant_id, :location_timezone,
+                  :currency, :country_code
+
+    # Default timezone if not fetched from SkyTab
+    DEFAULT_TIMEZONE = "America/New_York"
+
+    # SkyTab (Shift4) Marketplace API base URL
+    DEFAULT_ENVIRONMENT = "https://conecto-api.shift4payments.com/"
+
+    # Path to locations JSON file
+    LOCATIONS_FILE = File.join(File.dirname(__FILE__), "..", "..", ".env.json")
+
+    def initialize
+      @location_id      = ENV.fetch("SKYTAB_LOCATION_ID", nil)
+      @location_name    = ENV.fetch("SKYTAB_LOCATION_NAME", nil)
+      @access_token     = ENV.fetch("SKYTAB_ACCESS_TOKEN", nil)
+      @merchant_id      = ENV.fetch("SKYTAB_MERCHANT_ID", nil)
+      @environment      = normalize_url(ENV.fetch("SKYTAB_ENVIRONMENT", DEFAULT_ENVIRONMENT))
+      @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
+      @location_timezone = ENV.fetch("SKYTAB_TIMEZONE", nil)
+      @currency         = ENV.fetch("SKYTAB_CURRENCY", "USD")
+      @country_code     = ENV.fetch("SKYTAB_COUNTRY_CODE", "US")
+
+      # Load from .env.json if location_id not set in ENV
+      load_from_locations_file if @location_id.nil? || @location_id.empty?
+    end
+
+    # Load configuration for a specific location from .env.json
+    #
+    # @param location_id [String, nil] Location ID to load (nil for first location)
+    # @param index [Integer, nil] Index of location in the list (0-based)
+    # @return [self]
+    def load_location(location_id: nil, index: nil)
+      locations = load_locations_file
+      return self if locations.empty?
+
+      location = if location_id
+                   locations.find { |loc| loc["SKYTAB_LOCATION_ID"] == location_id }
+                 elsif index
+                   locations[index]
+                 else
+                   locations.first
+                 end
+
+      if location
+        apply_location_config(location)
+        logger.info "Loaded location: #{@location_name} (#{@location_id})"
+      else
+        logger.warn "Location not found: #{location_id || "index #{index}"}"
+      end
+
+      self
+    end
+
+    # List all available locations from .env.json
+    #
+    # @return [Array<Hash>] Array of location configs
+    def available_locations
+      load_locations_file.map do |loc|
+        {
+          id: loc["SKYTAB_LOCATION_ID"],
+          name: loc["SKYTAB_LOCATION_NAME"],
+          merchant_id: loc["SKYTAB_MERCHANT_ID"],
+          timezone: loc["SKYTAB_TIMEZONE"]
+        }
+      end
+    end
+
+    def validate!
+      raise ConfigurationError, "SKYTAB_LOCATION_ID is required" if location_id.nil? || location_id.empty?
+      raise ConfigurationError, "SKYTAB_ACCESS_TOKEN is required" if access_token.nil? || access_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
+
+    # Fetch location timezone from SkyTab API
+    # @return [String] IANA timezone identifier (e.g., "America/New_York")
+    def fetch_location_timezone
+      return @location_timezone if @location_timezone
+
+      require "rest-client"
+      require "json"
+
+      url = "#{environment}marketplace/v2/locations"
+      response = RestClient.get(url, { Authorization: "Bearer #{access_token}" })
+      data = JSON.parse(response.body)
+
+      locations = data.is_a?(Array) ? data : (data["locations"] || [data])
+      loc = locations.find { |l| l["id"].to_s == location_id.to_s } || locations.first
+
+      @location_timezone = loc&.dig("timeZone") || DEFAULT_TIMEZONE
+      logger.info "Location timezone: #{@location_timezone}"
+      @location_timezone
+    rescue StandardError => e
+      logger.warn "Failed to fetch location timezone: #{e.message}. Using default: #{DEFAULT_TIMEZONE}"
+      @location_timezone = DEFAULT_TIMEZONE
+    end
+
+    # Get current time in location's timezone
+    # @return [Time] Current time in location timezone
+    def location_time_now
+      require "time"
+      tz = fetch_location_timezone
+      begin
+        require "tzinfo"
+        TZInfo::Timezone.get(tz).now
+      rescue LoadError
+        old_tz = ENV["TZ"]
+        ENV["TZ"] = tz
+        time = Time.now
+        ENV["TZ"] = old_tz
+        time
+      end
+    end
+
+    # Get today's date in location's timezone
+    # @return [Date] Today's date in location timezone
+    def location_date_today
+      location_time_now.to_date
+    end
+
+    # Read the top-level DATABASE_URL from .env.json (object format only).
+    # Returns nil when the file uses the legacy array format or has no key.
+    #
+    # @return [String, nil] The DATABASE_URL or nil
+    def self.database_url_from_file
+      return nil unless File.exist?(LOCATIONS_FILE)
+
+      data = JSON.parse(File.read(LOCATIONS_FILE))
+      return nil if data.is_a?(Array)
+
+      data["DATABASE_URL"]
+    rescue JSON::ParserError
+      nil
+    end
+
+    private
+
+    def load_from_locations_file
+      locations = load_locations_file
+      return if locations.empty?
+
+      # Use first location by default
+      apply_location_config(locations.first)
+    end
+
+    # Parse .env.json, supporting both the legacy array format and the
+    # new object format: { "DATABASE_URL": "...", "locations": [...] }
+    def load_locations_file
+      return [] unless File.exist?(LOCATIONS_FILE)
+
+      data = JSON.parse(File.read(LOCATIONS_FILE))
+      return data if data.is_a?(Array) # legacy format
+
+      # New object format — extract locations list
+      data.fetch("locations", [])
+    rescue JSON::ParserError => e
+      warn "Failed to parse #{LOCATIONS_FILE}: #{e.message}"
+      []
+    end
+
+    def apply_location_config(location)
+      @location_id      = location["SKYTAB_LOCATION_ID"]
+      @location_name    = location["SKYTAB_LOCATION_NAME"]
+      @access_token     = location["SKYTAB_ACCESS_TOKEN"]
+      @merchant_id      = location["SKYTAB_MERCHANT_ID"]
+      @location_timezone = location["SKYTAB_TIMEZONE"]
+      @currency         = location["SKYTAB_CURRENCY"] || "USD"
+      @country_code     = location["SKYTAB_COUNTRY_CODE"] || "US"
+    end
+
+    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/skytab_sandbox_simulator/data/bar_nightclub/categories.json

@@ -0,0 +1,9 @@
+{
+  "categories": [
+    { "name": "Draft Beer", "sort_order": 1, "description": "On tap" },
+    { "name": "Cocktails", "sort_order": 2, "description": "Handcrafted cocktails" },
+    { "name": "Spirits", "sort_order": 3, "description": "Premium spirits" },
+    { "name": "Wine", "sort_order": 4, "description": "By the glass or bottle" },
+    { "name": "Bar Snacks", "sort_order": 5, "description": "Shareable bites" }
+  ]
+}