square_sandbox_simulator 0.1.0

data/lib/square_sandbox_simulator/models/category.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module SquareSandboxSimulator
+  module Models
+    class Category < Record
+      belongs_to :business_type
+      has_many :items, dependent: :destroy
+
+      # Validations — no uniqueness constraint; real Square merchants
+      # frequently have duplicate category names.
+      validates :name, presence: true
+
+      # Explicit sort scope (avoids default_scope anti-pattern)
+      scope :sorted, -> { order(:sort_order) }
+      scope :with_items, -> { joins(:items).distinct }
+    end
+  end
+end

data/lib/square_sandbox_simulator/models/daily_summary.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module SquareSandboxSimulator
+  module Models
+    class DailySummary < Record
+      # Validations
+      validates :merchant_id, presence: true
+      validates :business_date, presence: true,
+                                uniqueness: { scope: :merchant_id }
+
+      # Scopes
+      scope :for_merchant, ->(merchant_id) { where(merchant_id: merchant_id) }
+      scope :on_date, ->(date) { where(business_date: date) }
+      scope :today, -> { where(business_date: Date.today) }
+      scope :between_dates, ->(from, to) { where(business_date: from..to) }
+      scope :recent, ->(days = 7) { where("business_date >= ?", days.days.ago.to_date) }
+
+      # Generate (or update) a daily summary by aggregating simulated orders.
+      # Race-condition safe: retries on unique constraint violation.
+      #
+      # @param merchant_id [String] Square merchant ID
+      # @param date [Date] Business date to summarize
+      # @return [DailySummary] the created or updated summary
+      def self.generate_for!(merchant_id, date)
+        orders = SimulatedOrder.for_location(merchant_id).on_date(date).successful
+        payments = SimulatedPayment.joins(:simulated_order)
+                                   .where(simulated_orders: {
+                                            square_location_id: merchant_id,
+                                            business_date: date,
+                                            status: "paid",
+                                          })
+
+        # Build breakdown by meal period and dining option
+        breakdown = {
+          by_meal_period: orders.group(:meal_period).count,
+          by_dining_option: orders.group(:dining_option).count,
+          by_tender: payments.group(:tender_name).count,
+          revenue_by_meal_period: orders.group(:meal_period).sum(:total),
+          revenue_by_dining_option: orders.group(:dining_option).sum(:total),
+        }
+
+        attrs = {
+          order_count: orders.count,
+          payment_count: payments.count,
+          refund_count: SimulatedOrder.for_location(merchant_id).on_date(date).refunded.count,
+          total_revenue: orders.sum(:total),
+          total_tax: orders.sum(:tax_amount),
+          total_tips: orders.sum(:tip_amount),
+          total_discounts: orders.sum(:discount_amount),
+          breakdown: breakdown,
+        }
+
+        summary = find_or_initialize_by(merchant_id: merchant_id, business_date: date)
+        summary.assign_attributes(attrs)
+        summary.save!
+        summary
+      rescue ::ActiveRecord::RecordNotUnique
+        # Concurrent insert won — retry will find the existing record and update it
+        retry
+      end
+
+      # Convenience: total revenue in dollars
+      def total_revenue_dollars
+        (total_revenue || 0) / 100.0
+      end
+    end
+  end
+end

data/lib/square_sandbox_simulator/models/item.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module SquareSandboxSimulator
+  module Models
+    class Item < Record
+      belongs_to :category
+
+      # Validations — no uniqueness constraint; real Square merchants
+      # can have items with the same name in the same category.
+      validates :name, presence: true
+      validates :price, presence: true,
+                        numericality: { only_integer: true, greater_than_or_equal_to: 0 }
+
+      # Scopes
+      scope :active, -> { where(active: true) }
+      scope :inactive, -> { where(active: false) }
+
+      scope :for_business_type, lambda { |key|
+        joins(category: :business_type)
+          .where(business_types: { key: key })
+      }
+
+      scope :in_category, lambda { |category_name|
+        joins(:category).where(categories: { name: category_name })
+      }
+
+      # Price in dollars (convenience)
+      def price_dollars
+        (price || 0) / 100.0
+      end
+    end
+  end
+end

data/lib/square_sandbox_simulator/models/record.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "active_record"
+
+module SquareSandboxSimulator
+  module Models
+    # Shared base class for all simulator ActiveRecord models.
+    #
+    # Equivalent to ApplicationRecord in Rails, but for standalone usage.
+    # All models inherit from this so we can add shared behaviour
+    # (e.g. logging, default scopes) in one place.
+    class Record < ::ActiveRecord::Base
+      self.abstract_class = true
+    end
+  end
+end

data/lib/square_sandbox_simulator/models/simulated_order.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module SquareSandboxSimulator
+  module Models
+    class SimulatedOrder < Record
+      belongs_to :business_type, optional: true
+      has_many :simulated_payments, dependent: :destroy
+
+      # NOTE: no has_many :items — simulated orders track monetary totals only.
+      # Line-item detail lives in the Square API response (stored in metadata jsonb).
+
+      # Validations
+      validates :square_location_id, presence: true
+      validates :status, presence: true
+      validates :business_date, presence: true
+
+      # Status scopes
+      scope :successful, -> { where(status: "paid") }
+      scope :open_orders, -> { where(status: "open") }
+      scope :refunded, -> { where(status: "refunded") }
+
+      # Time scopes
+      scope :today, -> { where(business_date: Date.today) }
+      scope :on_date, ->(date) { where(business_date: date) }
+      scope :between_dates, ->(from, to) { where(business_date: from..to) }
+
+      # Filter scopes
+      scope :for_location, ->(location_id) { where(square_location_id: location_id) }
+      scope :for_meal_period, ->(period) { where(meal_period: period) }
+      scope :for_dining_option, ->(option) { where(dining_option: option) }
+
+      # Amounts in dollars (convenience)
+      def total_dollars
+        (total || 0) / 100.0
+      end
+
+      def subtotal_dollars
+        (subtotal || 0) / 100.0
+      end
+    end
+  end
+end

data/lib/square_sandbox_simulator/models/simulated_payment.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module SquareSandboxSimulator
+  module Models
+    class SimulatedPayment < Record
+      belongs_to :simulated_order
+
+      # Validations
+      validates :tender_name, presence: true
+      validates :status, presence: true
+      validates :amount, numericality: { only_integer: true, greater_than_or_equal_to: 0 }
+
+      # Status scopes
+      scope :successful, -> { where(status: "SUCCESS") }
+      scope :pending, -> { where(status: "pending") }
+      scope :refunded, -> { where(status: "refunded") }
+
+      # Tender scopes
+      scope :cash, -> { where(tender_name: "Cash") }
+      scope :by_tender, ->(name) { where(tender_name: name) }
+
+      # Amount in dollars (convenience)
+      def amount_dollars
+        (amount || 0) / 100.0
+      end
+    end
+  end
+end

data/lib/square_sandbox_simulator/seeder.rb

@@ -0,0 +1,242 @@
+# frozen_string_literal: true
+
+require "factory_bot"
+
+module SquareSandboxSimulator
+  # Seeds the database with realistic Square sandbox data using FactoryBot factories.
+  #
+  # Idempotent -- safe to run multiple times without creating duplicates.
+  # Uses `find_or_create_by!` on unique keys (BusinessType.key,
+  # Category.name+business_type, Item.name+category).
+  #
+  # @example Seed all business types
+  #   SquareSandboxSimulator::Seeder.seed!
+  #
+  # @example Seed a single business type
+  #   SquareSandboxSimulator::Seeder.seed!(business_type: :retail_clothing)
+  #
+  class Seeder
+    # Maps each business type trait to its category traits,
+    # and each category trait to its item traits.
+    #
+    # Structure: { bt_trait => { cat_trait => [item_traits] } }
+    SEED_MAP = {
+      restaurant: {
+        appetizers: %i[buffalo_wings mozzarella_sticks loaded_nachos spinach_artichoke_dip calamari],
+        entrees: %i[grilled_salmon ny_strip_steak chicken_parmesan pasta_primavera herb_roasted_chicken],
+        sides: %i[french_fries coleslaw mashed_potatoes side_salad onion_rings],
+        desserts: %i[chocolate_lava_cake ny_cheesecake restaurant_tiramisu apple_pie ice_cream_sundae],
+        beverages: %i[soft_drink iced_tea lemonade sparkling_water restaurant_coffee],
+      },
+      cafe_bakery: {
+        coffee_espresso: %i[house_drip_coffee espresso cappuccino latte cold_brew],
+        pastries: %i[croissant blueberry_muffin cinnamon_roll chocolate_chip_cookie],
+        breakfast: %i[avocado_toast breakfast_burrito acai_bowl yogurt_parfait],
+        sandwiches: %i[turkey_club caprese_panini chicken_caesar_wrap blt],
+        smoothies: %i[berry_blast_smoothie green_detox_juice mango_tango_smoothie fresh_oj],
+        # Intentional duplicates (mirrors real POS messiness)
+        coffee_espresso_dup: %i[house_drip_coffee_dup latte_dup iced_latte matcha_latte],
+        pastries_dup: %i[croissant_dup blueberry_muffin_dup almond_croissant banana_bread],
+        breakfast_dup: %i[avocado_toast_dup eggs_benedict french_toast],
+        cafe_drinks: %i[cafe_drip_coffee cafe_iced_tea cafe_lemonade cafe_hot_chocolate berry_blast_smoothie_dup],
+        cafe_grab_and_go: %i[gg_croissant gg_muffin gg_blt gg_yogurt_parfait gg_cold_brew],
+      },
+      bar_nightclub: {
+        draft_beer: %i[house_lager ipa stout wheat_beer],
+        cocktails: %i[margarita old_fashioned mojito espresso_martini],
+        spirits: %i[whiskey_neat vodka_soda tequila_shot rum_and_coke],
+        wine: %i[house_red house_white prosecco rose],
+        bar_snacks: %i[bar_loaded_fries sliders bar_wings pretzel_bites],
+      },
+      food_truck: {
+        tacos: %i[carne_asada_taco al_pastor_taco fish_taco veggie_taco birria_taco],
+        burritos_bowls: %i[classic_burrito burrito_bowl quesadilla truck_nachos],
+        truck_sides_drinks: %i[chips_and_guac elote rice_and_beans horchata jarritos],
+      },
+      fine_dining: {
+        first_course: %i[seared_foie_gras lobster_bisque tuna_tartare burrata_salad oysters_half_dozen],
+        main_course: %i[wagyu_ribeye chilean_sea_bass rack_of_lamb duck_breast truffle_risotto],
+        fine_desserts: %i[creme_brulee chocolate_souffle tasting_plate cheese_board fine_tiramisu],
+      },
+      pizzeria: {
+        pizzas: %i[margherita pepperoni supreme hawaiian bbq_chicken_pizza meat_lovers],
+        calzones: %i[classic_calzone meat_calzone stromboli spinach_calzone],
+        pizza_sides_drinks: %i[garlic_bread garden_salad caesar_salad garlic_knots fountain_drink cannoli],
+      },
+      retail_clothing: {
+        tops: %i[classic_tshirt button_down_shirt polo_shirt hoodie tank_top],
+        bottoms: %i[slim_fit_jeans chino_pants joggers shorts],
+        outerwear: %i[denim_jacket bomber_jacket puffer_vest rain_jacket],
+        accessories: %i[baseball_cap beanie canvas_belt scarf],
+        footwear: %i[canvas_sneakers leather_boots sandals running_shoes],
+      },
+      retail_general: {
+        electronics: %i[wireless_earbuds phone_charger bluetooth_speaker power_bank],
+        home_kitchen: %i[scented_candle throw_pillow kitchen_towel_set ceramic_mug],
+        personal_care: %i[hand_soap body_lotion lip_balm sunscreen],
+        office_supplies: %i[notebook pen_set desk_organizer sticky_notes],
+        snacks_beverages: %i[granola_bar_3pack retail_sparkling_water trail_mix dark_chocolate_bar],
+      },
+      salon_spa: {
+        haircuts: %i[womens_haircut mens_haircut childrens_haircut bang_trim],
+        color_services: %i[full_color partial_highlights full_highlights balayage],
+        spa_treatments: %i[swedish_massage deep_tissue_massage hot_stone_massage facial],
+        nail_services: %i[manicure pedicure gel_manicure acrylic_full_set],
+      },
+    }.freeze
+
+    # Expected category counts per business type (for spec validation).
+    CATEGORY_COUNTS = SEED_MAP.transform_values(&:size).freeze
+
+    # Expected item counts per category (for spec validation).
+    ITEM_COUNTS = SEED_MAP.each_with_object({}) do |(_, cats), hash|
+      cats.each { |cat_trait, items| hash[cat_trait] = items.size }
+    end.freeze
+
+    # Total counts across all business types.
+    TOTAL_BUSINESS_TYPES = SEED_MAP.size
+    TOTAL_CATEGORIES = SEED_MAP.values.sum(&:size)
+    TOTAL_ITEMS = SEED_MAP.values.flat_map(&:values).flatten.size
+
+    # Seed all (or one) business types with categories and items.
+    #
+    # @param business_type [Symbol, String, nil] Seed only this type, or all if nil.
+    # @return [Hash] Summary of created/found counts.
+    def self.seed!(business_type: nil)
+      new.seed!(business_type: business_type)
+    end
+
+    # @param business_type [Symbol, String, nil]
+    # @return [Hash] Summary with :business_types, :categories, :items,
+    #   :created, :found counts.
+    def seed!(business_type: nil)
+      types_to_seed = resolve_types(business_type)
+
+      counts = { business_types: 0, categories: 0, items: 0, created: 0, found: 0 }
+
+      ActiveRecord::Base.transaction do
+        types_to_seed.each do |bt_trait, categories_map|
+          bt, was_new = seed_business_type(bt_trait)
+          counts[:business_types] += 1
+          was_new ? counts[:created] += 1 : counts[:found] += 1
+
+          categories_map.each do |cat_trait, item_traits|
+            cat, was_new = seed_category(cat_trait, bt)
+            counts[:categories] += 1
+            was_new ? counts[:created] += 1 : counts[:found] += 1
+
+            item_traits.each do |item_trait|
+              _, was_new = seed_item(item_trait, cat)
+              counts[:items] += 1
+              was_new ? counts[:created] += 1 : counts[:found] += 1
+            end
+          end
+        end
+      end
+
+      SquareSandboxSimulator.logger.info(
+        "Seeding complete: #{counts[:business_types]} business types, " \
+        "#{counts[:categories]} categories, #{counts[:items]} items " \
+        "(#{counts[:created]} created, #{counts[:found]} found)",
+      )
+
+      counts
+    end
+
+    private
+
+    # Resolve which business types to seed.
+    #
+    # @param business_type [Symbol, String, nil]
+    # @return [Hash] subset of SEED_MAP
+    # @raise [ArgumentError] if the business type is unknown
+    def resolve_types(business_type)
+      return SEED_MAP if business_type.nil?
+
+      key = business_type.to_sym
+      unless SEED_MAP.key?(key)
+        raise ArgumentError,
+              "Unknown business type: #{key}. Valid types: #{SEED_MAP.keys.join(", ")}"
+      end
+
+      { key => SEED_MAP[key] }
+    end
+
+    # Find or create a business type using factory attributes.
+    #
+    # @param trait [Symbol]
+    # @return [Array(Models::BusinessType, Boolean)] record and whether it was newly created
+    def seed_business_type(trait)
+      attrs = FactoryBot.attributes_for(:business_type, trait)
+      record = Models::BusinessType.find_or_create_by!(key: attrs[:key]) do |bt|
+        bt.assign_attributes(attrs)
+      end
+      [record, record.previously_new_record?]
+    end
+
+    # Traits that represent intentional duplicates -- always create
+    # a new record instead of reusing an existing one.
+    DUPLICATE_CATEGORY_TRAITS = %i[
+      coffee_espresso_dup pastries_dup breakfast_dup cafe_drinks cafe_grab_and_go
+    ].freeze
+
+    DUPLICATE_ITEM_TRAITS = %i[
+      house_drip_coffee_dup latte_dup iced_latte matcha_latte
+      croissant_dup blueberry_muffin_dup almond_croissant banana_bread
+      avocado_toast_dup eggs_benedict french_toast
+      cafe_drip_coffee cafe_iced_tea cafe_lemonade cafe_hot_chocolate berry_blast_smoothie_dup
+      gg_croissant gg_muffin gg_blt gg_yogurt_parfait gg_cold_brew
+    ].freeze
+
+    # Find or create a category using factory attributes.
+    # Duplicate traits always create a new record (mirroring real-world
+    # data where merchants have multiple categories with the same name).
+    #
+    # @param trait [Symbol]
+    # @param business_type [Models::BusinessType]
+    # @return [Array(Models::Category, Boolean)] record and whether it was newly created
+    def seed_category(trait, business_type)
+      attrs = FactoryBot.attributes_for(:category, trait)
+
+      if DUPLICATE_CATEGORY_TRAITS.include?(trait)
+        # Check by SKU-like hint (sort_order) to be idempotent even for dupes
+        existing = Models::Category.find_by(
+          name: attrs[:name], business_type: business_type, sort_order: attrs[:sort_order],
+        )
+        return [existing, false] if existing
+
+        record = Models::Category.create!(attrs.merge(business_type: business_type).except(:business_type_id))
+        [record, true]
+      else
+        record = Models::Category.find_or_create_by!(name: attrs[:name], business_type: business_type) do |cat|
+          cat.assign_attributes(attrs.except(:business_type_id))
+        end
+        [record, record.previously_new_record?]
+      end
+    end
+
+    # Find or create an item using factory attributes.
+    # Duplicate traits always create a new record.
+    #
+    # @param trait [Symbol]
+    # @param category [Models::Category]
+    # @return [Array(Models::Item, Boolean)] record and whether it was newly created
+    def seed_item(trait, category)
+      attrs = FactoryBot.attributes_for(:item, trait)
+
+      if DUPLICATE_ITEM_TRAITS.include?(trait)
+        # Idempotent by SKU -- each duplicate has a unique SKU
+        existing = Models::Item.find_by(sku: attrs[:sku])
+        return [existing, false] if existing
+
+        record = Models::Item.create!(attrs.merge(category: category).except(:category_id))
+        [record, true]
+      else
+        record = Models::Item.find_or_create_by!(name: attrs[:name], category: category) do |item|
+          item.assign_attributes(attrs.except(:category_id))
+        end
+        [record, record.previously_new_record?]
+      end
+    end
+  end
+end