square_sandbox_simulator 0.1.0

data/lib/square_sandbox_simulator/generators/order_generator.rb

@@ -0,0 +1,632 @@
+# frozen_string_literal: true
+
+module SquareSandboxSimulator
+  module Generators
+    # Generates realistic orders and payments against the Square sandbox API.
+    #
+    # Phase 1 scope: line items (via catalog variations), discounts, taxes,
+    # card payments, cash payments, tips, and refunds.
+    # Skipped for Phase 1: gift cards, cash events, modifier groups.
+    class OrderGenerator
+      # Meal periods with realistic distributions
+      MEAL_PERIODS = {
+        breakfast: { hours: 7..10, weight: 15, avg_items: 3..6, avg_party: 1..3 },
+        lunch: { hours: 11..14, weight: 30, avg_items: 3..7, avg_party: 1..4 },
+        happy_hour: { hours: 15..17, weight: 10, avg_items: 3..6, avg_party: 2..5 },
+        dinner: { hours: 17..21, weight: 35, avg_items: 4..9, avg_party: 2..6 },
+        late_night: { hours: 21..23, weight: 10, avg_items: 3..6, avg_party: 1..3 },
+      }.freeze
+
+      # Dining option distributions by meal period
+      DINING_BY_PERIOD = {
+        breakfast: { "HERE" => 40, "TO_GO" => 50, "DELIVERY" => 10 },
+        lunch: { "HERE" => 35, "TO_GO" => 45, "DELIVERY" => 20 },
+        happy_hour: { "HERE" => 80, "TO_GO" => 15, "DELIVERY" => 5 },
+        dinner: { "HERE" => 70, "TO_GO" => 15, "DELIVERY" => 15 },
+        late_night: { "HERE" => 50, "TO_GO" => 30, "DELIVERY" => 20 },
+      }.freeze
+
+      # Tip percentages by dining option
+      TIP_RATES = {
+        "HERE" => { min: 15, max: 25 },
+        "TO_GO" => { min: 0, max: 15 },
+        "DELIVERY" => { min: 10, max: 20 },
+      }.freeze
+
+      # Order patterns by day of week
+      ORDER_PATTERNS = {
+        weekday: { min: 40, max: 60 },
+        friday: { min: 70, max: 100 },
+        saturday: { min: 80, max: 120 },
+        sunday: { min: 50, max: 80 },
+      }.freeze
+
+      # Category preferences by meal period
+      CATEGORY_PREFERENCES = {
+        breakfast: ["Brunch", "Drinks", "Sides", "Pastries", "Breakfast", "Coffee & Espresso"],
+        lunch: ["Appetizers", "Soups & Salads", "Entrees", "Sides", "Drinks", "Sandwiches"],
+        happy_hour: ["Appetizers", "Cocktails", "Draft Beer", "Wine", "Bar Snacks", "Drinks"],
+        dinner: %w[Appetizers Entrees Sides Desserts Drinks],
+        late_night: ["Appetizers", "Entrees", "Desserts", "Drinks", "Bar Snacks"],
+      }.freeze
+
+      # Discount application probabilities
+      DISCOUNT_PROBABILITIES = {
+        order_discount: 0.12,
+        line_item_discount: 0.08,
+      }.freeze
+
+      # Card vs cash payment split
+      CARD_PAYMENT_CHANCE = 75 # 75% card, 25% cash
+
+      # Refund reasons
+      REFUND_REASONS = %w[customer_request quality_issue wrong_order duplicate_charge].freeze
+
+      attr_reader :services, :logger, :stats, :refund_percentage
+
+      def initialize(services: nil, refund_percentage: 5)
+        @services = services || Services::Square::ServicesManager.new
+        @logger = SquareSandboxSimulator.logger
+        @refund_percentage = refund_percentage
+        @stats = {
+          orders: 0,
+          revenue: 0,
+          tips: 0,
+          tax: 0,
+          discounts: 0,
+          by_period: {},
+          by_dining: {},
+          refunds: { total: 0, full: 0, partial: 0, amount: 0 },
+          cash_payments: 0,
+          card_payments: 0,
+        }
+      end
+
+      # Generate a realistic day of operations.
+      # @param date [Date] Date to generate orders for (defaults to today in merchant timezone)
+      # @param multiplier [Float] Multiplier for order count (0.5 = slow day, 2.0 = busy day)
+      def generate_realistic_day(date: nil, multiplier: 1.0)
+        date ||= SquareSandboxSimulator.configuration.merchant_date_today
+        count = (order_count_for_date(date) * multiplier).to_i
+
+        logger.info "=" * 60
+        logger.info "Generating realistic day: #{date}"
+        logger.info "    Target orders: #{count}"
+        logger.info "    Day: #{date.strftime("%A")}"
+        logger.info "=" * 60
+
+        data = fetch_required_data
+        return [] unless data
+
+        # Distribute orders across meal periods
+        period_orders = distribute_orders_by_period(count)
+
+        orders = []
+        period_orders.each do |period, period_count|
+          logger.info "-" * 40
+          logger.info "#{period.to_s.upcase} SERVICE: #{period_count} orders"
+
+          period_count.times do |i|
+            order_time = generate_order_time(date, period)
+
+            order = create_realistic_order(
+              period: period,
+              data: data,
+              order_num: i + 1,
+              total_in_period: period_count,
+              order_time: order_time,
+            )
+
+            if order
+              orders << order
+              update_stats(order, period)
+            end
+          end
+        end
+
+        # Process refunds for some orders
+        process_refunds(orders) if refund_percentage.positive?
+
+        # Generate daily summary for audit trail
+        generate_daily_summary(date)
+
+        print_summary
+        orders
+      end
+
+      # Generate orders for today (simple mode).
+      # Uses merchant timezone for "today".
+      def generate_today(count: nil)
+        today = SquareSandboxSimulator.configuration.merchant_date_today
+        if count
+          generate_for_date(today, count: count)
+        else
+          generate_realistic_day(date: today)
+        end
+      end
+
+      # Generate specific count of orders for a date.
+      def generate_for_date(date, count:)
+        logger.info "=" * 60
+        logger.info "Generating #{count} orders for #{date}"
+        logger.info "=" * 60
+
+        data = fetch_required_data
+        return [] unless data
+
+        orders = []
+        count.times do |i|
+          period = weighted_random_period
+          order_time = generate_order_time(date, period)
+          logger.info "-" * 40
+          logger.info "Creating order #{i + 1}/#{count} (#{period})"
+
+          order = create_realistic_order(
+            period: period,
+            data: data,
+            order_num: i + 1,
+            total_in_period: count,
+            order_time: order_time,
+          )
+
+          if order
+            orders << order
+            update_stats(order, period)
+          end
+        end
+
+        # Process refunds for some orders
+        process_refunds(orders) if refund_percentage.positive?
+
+        # Generate daily summary for audit trail
+        generate_daily_summary(date)
+
+        print_summary
+        orders
+      end
+
+      # Process refunds for a percentage of completed orders.
+      def process_refunds(orders)
+        return if orders.empty? || refund_percentage <= 0
+
+        refund_count = (orders.size * refund_percentage / 100.0).ceil
+        refund_count = [refund_count, orders.size].min
+
+        logger.info "-" * 40
+        logger.info "PROCESSING REFUNDS: #{refund_count} orders (#{refund_percentage}%)"
+
+        orders_to_refund = orders.sample(refund_count)
+
+        orders_to_refund.each do |order|
+          process_order_refund(order)
+        end
+      end
+
+      private
+
+      # Fetch all data needed for order generation from Square API.
+      def fetch_required_data
+        items = services.catalog.list_catalog(types: "ITEM")
+        customers = services.customer.list_customers
+        discounts = services.catalog.list_catalog(types: "DISCOUNT")
+        taxes = services.catalog.list_catalog(types: "TAX")
+
+        if items.empty?
+          logger.error "No items found! Please run setup first."
+          return nil
+        end
+
+        # Extract variation info for each item (orders need variation IDs)
+        variations = EntityGenerator.extract_variation_ids(items)
+
+        if variations.empty?
+          logger.error "No item variations found! Items may be misconfigured."
+          return nil
+        end
+
+        # Group items by category name for meal period selection
+        items_by_category = items.group_by do |item|
+          # Square items may have category_id; try to resolve name
+          item.dig("item_data", "category_id") || "Other"
+        end
+
+        {
+          items: items,
+          variations: variations,
+          items_by_category: items_by_category,
+          customers: customers,
+          discounts: discounts,
+          taxes: taxes,
+        }
+      end
+
+      # Create a single realistic order with line items, payment, tip, and optional discount.
+      def create_realistic_order(period:, data:, order_num:, total_in_period:, order_time: nil)
+        order_time ||= Time.now
+        config = MEAL_PERIODS[period]
+
+        # 60% of orders have customer info
+        customer = data[:customers].sample if data[:customers].any? && rand < 0.6
+
+        # Party size affects item count
+        party_size = rand(config[:avg_party])
+        base_items = rand(config[:avg_items])
+        num_items = [base_items + (party_size / 2), 1].max
+
+        # Select random variations for line items
+        selected = data[:variations].sample([num_items, data[:variations].size].min)
+
+        # Build line items payload for Square Orders API
+        line_items = selected.map do |var|
+          quantity = party_size > 2 && rand < 0.3 ? rand(2..3) : 1
+
+          {
+            "catalog_object_id" => var[:variation_id],
+            "quantity" => quantity.to_s,
+          }
+        end
+
+        # Build order-level taxes (apply first tax to all items)
+        order_taxes = []
+        if data[:taxes].any?
+          tax = data[:taxes].first
+          uid = "tax_#{SecureRandom.hex(4)}"
+          order_taxes << {
+            "uid" => uid,
+            "catalog_object_id" => tax["id"],
+            "scope" => "ORDER",
+          }
+        end
+
+        # Build order-level discounts (probabilistic)
+        order_discounts = []
+        if data[:discounts].any? && rand < DISCOUNT_PROBABILITIES[:order_discount]
+          disc = data[:discounts].sample
+          disc["discount_data"] || {}
+
+          discount_entry = {
+            "uid" => "disc_#{SecureRandom.hex(4)}",
+            "catalog_object_id" => disc["id"],
+            "scope" => "ORDER",
+          }
+          order_discounts << discount_entry
+        end
+
+        # Create the order (all line items at once)
+        order = services.order.create_order(
+          line_items: line_items,
+          discounts: order_discounts,
+          taxes: order_taxes,
+          customer_id: customer&.dig("id"),
+        )
+
+        return nil unless order && order["id"]
+
+        order_id = order["id"]
+        logger.info "  Order #{order_num}/#{total_in_period}: #{order_id} (#{line_items.size} items)"
+
+        # Determine dining option and calculate tip
+        dining = select_dining_option(period)
+        subtotal = order.dig("total_money", "amount") || 0
+        tip_amount = calculate_tip(subtotal, dining, party_size)
+
+        # Process payment (card or cash)
+        payment = if rand(100) < CARD_PAYMENT_CHANCE
+                    # Card payment with tip
+                    services.payment.create_payment(
+                      order_id: order_id,
+                      amount: subtotal,
+                      source_id: "cnon:card-nonce-ok",
+                      tip_amount: tip_amount,
+                    )
+                  else
+                    # Cash payment (no tip tracking for cash)
+                    services.payment.create_cash_payment(
+                      order_id: order_id,
+                      amount: subtotal,
+                    )
+                  end
+
+        unless payment
+          logger.warn "  Payment failed for order #{order_id}"
+          return nil
+        end
+
+        logger.info "  Payment: #{payment["id"]} ($#{format("%.2f", subtotal / 100.0)}" \
+                    "#{" + $#{format("%.2f", tip_amount / 100.0)} tip" if tip_amount.positive?})"
+
+        # Attach metadata for tracking
+        order["_metadata"] = {
+          period: period,
+          dining: dining,
+          party_size: party_size,
+          tip: tip_amount,
+          order_time: order_time,
+          payment_id: payment["id"],
+          payment_type: payment["source_type"] || (payment.dig("external_details", "type") == "CASH" ? "CASH" : "CARD"),
+        }
+
+        # Track in audit DB
+        track_simulated_order(order, period: period, dining: dining, date: order_time.to_date)
+
+        order
+      end
+
+      # Select a dining option based on meal period weights.
+      def select_dining_option(period)
+        options = DINING_BY_PERIOD[period]
+        total = options.values.sum
+        random = rand(total)
+
+        cumulative = 0
+        options.each do |option, weight|
+          cumulative += weight
+          return option if random < cumulative
+        end
+
+        "HERE"
+      end
+
+      # Calculate tip based on subtotal, dining option, and party size.
+      def calculate_tip(subtotal, dining, party_size)
+        rates = TIP_RATES[dining] || TIP_RATES["HERE"]
+
+        # 20% of orders leave no tip
+        return 0 if rand < 0.20
+
+        # Large parties tend to tip slightly higher
+        min_rate = rates[:min]
+        max_rate = rates[:max]
+        max_rate += 3 if party_size >= 4
+
+        tip_pct = rand(min_rate..max_rate)
+        (subtotal * tip_pct / 100.0).round
+      end
+
+      # Process a refund for a single order.
+      def process_order_refund(order)
+        order_id = order["id"]
+        payment_id = order.dig("_metadata", :payment_id)
+        payment_type = order.dig("_metadata", :payment_type)
+
+        # Cannot refund cash payments via API
+        return if payment_type == "CASH"
+        return unless payment_id
+
+        # Get payment amount
+        payment = services.payment.get_payment(payment_id)
+        return unless payment
+
+        payment_amount = payment.dig("amount_money", "amount") || 0
+        return if payment_amount <= 0
+
+        # 60% full refunds, 40% partial
+        is_full_refund = rand < 0.6
+        reason = REFUND_REASONS.sample
+
+        if is_full_refund
+          begin
+            result = services.payment.refund_payment(
+              payment_id: payment_id,
+              amount: payment_amount,
+              reason: reason,
+            )
+            if result
+              @stats[:refunds][:total] += 1
+              @stats[:refunds][:full] += 1
+              @stats[:refunds][:amount] += payment_amount
+              logger.info "  Full refund: Order #{order_id} - $#{format("%.2f", payment_amount / 100.0)} (#{reason})"
+              track_refund(order_id)
+            end
+          rescue StandardError => e
+            logger.warn "  Failed to refund order #{order_id}: #{e.message}"
+          end
+        else
+          refund_percent = rand(25..75)
+          refund_amount = (payment_amount * refund_percent / 100.0).round
+
+          begin
+            result = services.payment.refund_payment(
+              payment_id: payment_id,
+              amount: refund_amount,
+              reason: reason,
+            )
+            if result
+              @stats[:refunds][:total] += 1
+              @stats[:refunds][:partial] += 1
+              @stats[:refunds][:amount] += refund_amount
+              logger.info "  Partial refund: Order #{order_id} - $#{format("%.2f", refund_amount / 100.0)} " \
+                          "of $#{format("%.2f", payment_amount / 100.0)} (#{reason})"
+              track_refund(order_id)
+            end
+          rescue StandardError => e
+            logger.warn "  Failed to partially refund order #{order_id}: #{e.message}"
+          end
+        end
+      end
+
+      # -- Distribution helpers --
+
+      def order_count_for_date(date)
+        day = date.strftime("%A").downcase.to_sym
+
+        pattern = case day
+                  when :friday then ORDER_PATTERNS[:friday]
+                  when :saturday then ORDER_PATTERNS[:saturday]
+                  when :sunday then ORDER_PATTERNS[:sunday]
+                  else ORDER_PATTERNS[:weekday]
+                  end
+
+        rand(pattern[:min]..pattern[:max])
+      end
+
+      def distribute_orders_by_period(total_count)
+        total_weight = MEAL_PERIODS.values.sum { |p| p[:weight] }
+
+        distribution = {}
+        remaining = total_count
+
+        MEAL_PERIODS.each_with_index do |(period, cfg), index|
+          if index == MEAL_PERIODS.size - 1
+            distribution[period] = remaining
+          else
+            count = ((cfg[:weight].to_f / total_weight) * total_count).round
+            distribution[period] = [count, remaining].min
+            remaining -= distribution[period]
+          end
+        end
+
+        distribution
+      end
+
+      def weighted_random_period
+        total_weight = MEAL_PERIODS.values.sum { |p| p[:weight] }
+        random = rand(total_weight)
+
+        cumulative = 0
+        MEAL_PERIODS.each do |period, cfg|
+          cumulative += cfg[:weight]
+          return period if random < cumulative
+        end
+
+        :dinner
+      end
+
+      def generate_order_time(date, period)
+        hours = MEAL_PERIODS[period][:hours]
+        hour = rand(hours)
+        minute = rand(60)
+
+        tz_identifier = SquareSandboxSimulator.configuration.fetch_location_timezone
+        begin
+          require "tzinfo"
+          tz = TZInfo::Timezone.get(tz_identifier)
+          tz.local_time(date.year, date.month, date.day, hour, minute, 0)
+        rescue LoadError
+          Time.new(date.year, date.month, date.day, hour, minute, 0)
+        end
+      end
+
+      # -- Stats tracking --
+
+      def update_stats(order, period)
+        total = order.dig("total_money", "amount") || 0
+        tip = order.dig("_metadata", :tip) || 0
+        tax = order.dig("total_tax_money", "amount") || 0
+        dining = order.dig("_metadata", :dining) || "HERE"
+        payment_type = order.dig("_metadata", :payment_type) || "CARD"
+
+        @stats[:orders] += 1
+        @stats[:revenue] += total
+        @stats[:tips] += tip
+        @stats[:tax] += tax
+
+        @stats[:by_period][period] = (@stats[:by_period][period] || 0) + 1
+        @stats[:by_dining][dining] = (@stats[:by_dining][dining] || 0) + 1
+
+        if payment_type == "CASH"
+          @stats[:cash_payments] += 1
+        else
+          @stats[:card_payments] += 1
+        end
+      end
+
+      def print_summary
+        logger.info "=" * 60
+        logger.info "ORDER GENERATION SUMMARY"
+        logger.info "=" * 60
+        logger.info "  Total Orders:   #{@stats[:orders]}"
+        logger.info "  Revenue:        $#{format("%.2f", @stats[:revenue] / 100.0)}"
+        logger.info "  Tips:           $#{format("%.2f", @stats[:tips] / 100.0)}"
+        logger.info "  Tax:            $#{format("%.2f", @stats[:tax] / 100.0)}"
+        logger.info "  Card Payments:  #{@stats[:card_payments]}"
+        logger.info "  Cash Payments:  #{@stats[:cash_payments]}"
+
+        if @stats[:by_period].any?
+          logger.info ""
+          logger.info "  By Period:"
+          @stats[:by_period].each do |period, count|
+            logger.info "    #{period.to_s.ljust(15)} #{count}"
+          end
+        end
+
+        if @stats[:by_dining].any?
+          logger.info ""
+          logger.info "  By Dining:"
+          @stats[:by_dining].each do |option, count|
+            logger.info "    #{option.ljust(15)} #{count}"
+          end
+        end
+
+        if @stats[:refunds][:total].positive?
+          logger.info ""
+          logger.info "  Refunds: #{@stats[:refunds][:total]} " \
+                      "(#{@stats[:refunds][:full]} full, #{@stats[:refunds][:partial]} partial) " \
+                      "$#{format("%.2f", @stats[:refunds][:amount] / 100.0)}"
+        end
+
+        logger.info "=" * 60
+      end
+
+      # -- Audit DB persistence --
+
+      def track_simulated_order(order, period:, dining:, date:)
+        return unless Database.connected?
+
+        total = order.dig("total_money", "amount") || 0
+        tax = order.dig("total_tax_money", "amount") || 0
+        tip = order.dig("_metadata", :tip) || 0
+        discount = order.dig("total_discount_money", "amount") || 0
+
+        sim_order = Models::SimulatedOrder.create!(
+          square_order_id: order["id"],
+          square_location_id: SquareSandboxSimulator.configuration.location_id,
+          status: "paid",
+          business_date: date,
+          meal_period: period.to_s,
+          dining_option: dining,
+          total: total,
+          subtotal: total - tax,
+          tax_amount: tax,
+          tip_amount: tip,
+          discount_amount: discount,
+          metadata: order["_metadata"],
+        )
+
+        # Track payment
+        payment_id = order.dig("_metadata", :payment_id)
+        payment_type = order.dig("_metadata", :payment_type) || "CARD"
+
+        if payment_id
+          Models::SimulatedPayment.create!(
+            simulated_order: sim_order,
+            square_payment_id: payment_id,
+            tender_name: payment_type == "CASH" ? "Cash" : "Card",
+            status: "SUCCESS",
+            amount: total + tip,
+          )
+        end
+      rescue StandardError => e
+        logger.debug "Audit logging failed: #{e.message}"
+      end
+
+      def track_refund(order_id)
+        return unless Database.connected?
+
+        sim_order = Models::SimulatedOrder.find_by(square_order_id: order_id)
+        sim_order&.update!(status: "refunded")
+      rescue StandardError => e
+        logger.debug "Refund tracking failed: #{e.message}"
+      end
+
+      def generate_daily_summary(date)
+        return unless Database.connected?
+
+        location_id = SquareSandboxSimulator.configuration.location_id
+        Models::DailySummary.generate_for!(location_id, date)
+      rescue StandardError => e
+        logger.debug "Daily summary generation failed: #{e.message}"
+      end
+    end
+  end
+end

data/lib/square_sandbox_simulator/models/api_request.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module SquareSandboxSimulator
+  module Models
+    class ApiRequest < Record
+      # Validations
+      validates :http_method, presence: true
+      validates :url, presence: true
+
+      # Time scopes — use Time.now.utc for consistency with AR's UTC storage
+      scope :today, -> { where("created_at >= ?", Time.now.utc.beginning_of_day) }
+      scope :recent, ->(minutes = 60) { where("created_at >= ?", minutes.minutes.ago) }
+
+      # Status scopes
+      scope :errors, -> { where("response_status >= 400 OR error_message IS NOT NULL") }
+      scope :successful, -> { where("response_status < 400 AND error_message IS NULL") }
+
+      # Resource scopes
+      scope :for_resource, ->(type) { where(resource_type: type) }
+      scope :for_resource_id, ->(type, id) { where(resource_type: type, resource_id: id) }
+
+      # Location scope — matches /locations/<id>/ or /locations/<id> (end of URL)
+      scope :for_location, lambda { |location_id|
+        sanitized = sanitize_sql_like(location_id)
+        where("url LIKE ?", "%/locations/#{sanitized}/%")
+          .or(where("url LIKE ?", "%/locations/#{sanitized}"))
+      }
+
+      # HTTP method scopes
+      scope :gets, -> { where(http_method: "GET") }
+      scope :posts, -> { where(http_method: "POST") }
+      scope :puts, -> { where(http_method: "PUT") }
+      scope :deletes, -> { where(http_method: "DELETE") }
+
+      # Performance
+      scope :slow, ->(threshold_ms = 1000) { where("duration_ms > ?", threshold_ms) }
+
+      def error?
+        error_message.present? || (response_status && response_status >= 400)
+      end
+    end
+  end
+end

data/lib/square_sandbox_simulator/models/business_type.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module SquareSandboxSimulator
+  module Models
+    class BusinessType < Record
+      has_many :categories, dependent: :destroy
+      has_many :items, through: :categories
+      has_many :simulated_orders, dependent: :nullify
+
+      # Validations
+      validates :key, presence: true, uniqueness: true
+      validates :name, presence: true
+
+      # Scopes by industry
+      scope :food_types, -> { where(industry: "food") }
+      scope :retail_types, -> { where(industry: "retail") }
+      scope :service_types, -> { where(industry: "service") }
+
+      # Find by key (the primary lookup pattern)
+      def self.find_by_key!(key)
+        find_by!(key: key)
+      end
+    end
+  end
+end