square_sandbox_simulator 0.1.0

data/lib/square_sandbox_simulator/db/factories/simulated_orders.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+FactoryBot.define do
+  factory :simulated_order, class: "SquareSandboxSimulator::Models::SimulatedOrder" do
+    sequence(:square_location_id) { |n| "LOCATION#{n}" }
+    status { "open" }
+    business_date { Date.today }
+    subtotal { 0 }
+    tax_amount { 0 }
+    tip_amount { 0 }
+    discount_amount { 0 }
+    total { 0 }
+    metadata { {} }
+
+    trait :paid do
+      status { "paid" }
+      sequence(:square_order_id) { |n| "ORD#{n}#{SecureRandom.hex(4).upcase}" }
+      subtotal { 2500 }        # cents
+      tax_amount { 222 }       # cents
+      tip_amount { 450 }       # cents
+      discount_amount { 0 }    # cents
+      total { 3172 }           # cents — subtotal + tax + tip - discount
+      meal_period { "lunch" }
+      dining_option { "HERE" }
+    end
+
+    trait :refunded do
+      status { "refunded" }
+      sequence(:square_order_id) { |n| "ORD#{n}#{SecureRandom.hex(4).upcase}" }
+      subtotal { 1800 }
+      tax_amount { 160 }
+      tip_amount { 0 }
+      discount_amount { 0 }
+      total { 1960 }
+      meal_period { "dinner" }
+      dining_option { "HERE" }
+    end
+
+    trait :failed do
+      status { "failed" }
+      subtotal { 0 }
+      tax_amount { 0 }
+      tip_amount { 0 }
+      total { 0 }
+      metadata { { "error" => "Payment declined" } }
+    end
+
+    trait :with_business_type do
+      association :business_type, factory: %i[business_type restaurant]
+    end
+
+    # Convenience: a paid order with associated payment
+    trait :with_payment do
+      paid
+
+      after(:create) do |order|
+        create(:simulated_payment, :success, simulated_order: order, amount: order.total)
+      end
+    end
+
+    # Convenience: a paid order with a split payment (cash + card)
+    trait :with_split_payment do
+      paid
+      total { 4000 }
+      subtotal { 3400 }
+      tax_amount { 302 }
+      tip_amount { 298 }
+
+      after(:create) do |order|
+        half = order.total / 2
+        create(:simulated_payment, :success, :cash_tender, simulated_order: order, amount: half)
+        create(:simulated_payment, :success, :credit_tender, simulated_order: order, amount: order.total - half)
+      end
+    end
+
+    # Meal-period traits
+    trait :breakfast_order do
+      meal_period { "breakfast" }
+      dining_option { "HERE" }
+    end
+
+    trait :lunch_order do
+      meal_period { "lunch" }
+      dining_option { "HERE" }
+    end
+
+    trait :dinner_order do
+      meal_period { "dinner" }
+      dining_option { "HERE" }
+    end
+
+    trait :late_night_order do
+      meal_period { "late_night" }
+      dining_option { "HERE" }
+    end
+
+    # Dining-option traits
+    trait :dine_in do
+      dining_option { "HERE" }
+    end
+
+    trait :takeout do
+      dining_option { "TO_GO" }
+    end
+
+    trait :delivery do
+      dining_option { "DELIVERY" }
+    end
+  end
+end

data/lib/square_sandbox_simulator/db/factories/simulated_payments.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+FactoryBot.define do
+  factory :simulated_payment, class: "SquareSandboxSimulator::Models::SimulatedPayment" do
+    association :simulated_order
+    tender_name { "Cash" }
+    amount { 1500 }       # cents
+    tip_amount { 0 }      # cents
+    tax_amount { 0 }      # cents
+    status { "pending" }
+    payment_type { nil }
+
+    # ── Status traits ──────────────────────────────────────────
+
+    trait :success do
+      status { "SUCCESS" }
+      sequence(:square_payment_id) { |n| "PAY#{n}#{SecureRandom.hex(4).upcase}" }
+    end
+
+    trait :failed do
+      status { "failed" }
+    end
+
+    trait :refunded do
+      status { "refunded" }
+      sequence(:square_payment_id) { |n| "PAY#{n}#{SecureRandom.hex(4).upcase}" }
+    end
+
+    # ── Tender traits ──────────────────────────────────────────
+
+    trait :cash_tender do
+      tender_name { "Cash" }
+      payment_type { "cash" }
+    end
+
+    trait :credit_tender do
+      tender_name { "Credit Card" }
+      payment_type { "credit" }
+    end
+
+    trait :debit_tender do
+      tender_name { "Debit Card" }
+      payment_type { "debit" }
+    end
+
+    trait :gift_card_tender do
+      tender_name { "Gift Card" }
+      payment_type { "gift_card" }
+    end
+
+    # ── Split payment trait ────────────────────────────────────
+    # Marks this payment as part of a split (amount is a portion of the total)
+    trait :split do
+      status { "paid" }
+      sequence(:square_payment_id) { |n| "PAY#{n}#{SecureRandom.hex(4).upcase}" }
+      amount { 750 } # half of a typical order
+    end
+  end
+end

data/lib/square_sandbox_simulator/db/migrate/20260312000000_enable_pgcrypto.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+class EnablePgcrypto < ActiveRecord::Migration[8.0]
+  def change
+    enable_extension "pgcrypto"
+  end
+end

data/lib/square_sandbox_simulator/db/migrate/20260312000001_create_business_types.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+class CreateBusinessTypes < ActiveRecord::Migration[8.0]
+  def change
+    create_table :business_types, id: :uuid do |t|
+      t.string :key, null: false
+      t.string :name, null: false
+      t.text :description
+      t.string :industry
+      t.jsonb :order_profile, default: {}
+
+      t.timestamps
+    end
+
+    add_index :business_types, :key, unique: true
+    add_index :business_types, :industry
+  end
+end

data/lib/square_sandbox_simulator/db/migrate/20260312000002_create_categories.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+class CreateCategories < ActiveRecord::Migration[8.0]
+  def change
+    create_table :categories, id: :uuid do |t|
+      t.references :business_type, null: false, foreign_key: { on_delete: :cascade }, type: :uuid
+      t.string :name, null: false
+      t.integer :sort_order, default: 0
+      t.text :description
+      t.string :tax_group
+
+      t.timestamps
+    end
+
+    add_index :categories, %i[business_type_id name sort_order], unique: true
+    add_index :categories, :sort_order
+  end
+end

data/lib/square_sandbox_simulator/db/migrate/20260312000003_create_items.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+class CreateItems < ActiveRecord::Migration[8.0]
+  def change
+    create_table :items, id: :uuid do |t|
+      t.references :category, null: false, foreign_key: { on_delete: :cascade }, type: :uuid
+      t.string :name, null: false
+      t.integer :price, null: false # cents
+      t.string :sku
+      t.string :unit
+      t.boolean :active, default: true, null: false
+      t.jsonb :variants, default: []
+      t.jsonb :metadata, default: {}
+
+      t.timestamps
+    end
+
+    add_index :items, %i[category_id name], unique: true
+    add_index :items, :sku
+    add_index :items, :active
+    add_check_constraint :items, "price >= 0", name: "items_price_non_negative"
+  end
+end

data/lib/square_sandbox_simulator/db/migrate/20260312000004_create_simulated_orders.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+class CreateSimulatedOrders < ActiveRecord::Migration[8.0]
+  def change
+    create_table :simulated_orders, id: :uuid do |t|
+      t.string :square_order_id
+      t.string :square_location_id, null: false
+      # Nullable: orders may be created before a business_type is assigned
+      t.references :business_type, foreign_key: true, type: :uuid
+      t.string :status, null: false, default: "open"
+      t.integer :subtotal, default: 0        # cents
+      t.integer :tax_amount, default: 0      # cents
+      t.integer :tip_amount, default: 0      # cents
+      t.integer :discount_amount, default: 0 # cents
+      t.integer :total, default: 0           # cents
+      t.string :dining_option
+      t.string :meal_period
+      t.jsonb :metadata, default: {}
+      t.date :business_date, null: false
+
+      t.timestamps
+    end
+
+    # Unique per location -- prevents duplicate inserts on retry
+    add_index :simulated_orders, %i[square_location_id square_order_id],
+              unique: true,
+              where: "square_order_id IS NOT NULL",
+              name: "idx_simulated_orders_location_square_unique"
+    add_index :simulated_orders, :square_location_id
+    add_index :simulated_orders, :status
+    add_index :simulated_orders, :business_date
+    add_index :simulated_orders, :meal_period
+    add_index :simulated_orders, :dining_option
+    add_index :simulated_orders, :created_at
+  end
+end

data/lib/square_sandbox_simulator/db/migrate/20260312000005_create_simulated_payments.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+class CreateSimulatedPayments < ActiveRecord::Migration[8.0]
+  def change
+    create_table :simulated_payments, id: :uuid do |t|
+      t.references :simulated_order, null: false, foreign_key: { on_delete: :cascade }, type: :uuid
+      t.string :square_payment_id
+      t.string :tender_name, null: false
+      t.integer :amount, default: 0      # cents
+      t.integer :tip_amount, default: 0  # cents
+      t.integer :tax_amount, default: 0  # cents
+      t.string :status, null: false, default: "pending"
+      t.string :payment_type
+
+      t.timestamps
+    end
+
+    # Unique -- prevents duplicate payment inserts on retry
+    add_index :simulated_payments, :square_payment_id,
+              unique: true,
+              where: "square_payment_id IS NOT NULL"
+    add_index :simulated_payments, :tender_name
+    add_index :simulated_payments, :status
+    add_index :simulated_payments, :created_at
+  end
+end

data/lib/square_sandbox_simulator/db/migrate/20260312000006_create_api_requests.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+class CreateApiRequests < ActiveRecord::Migration[8.0]
+  def change
+    create_table :api_requests, id: :uuid do |t|
+      t.string :square_location_id
+      t.string :http_method, null: false
+      t.text :url, null: false
+      t.jsonb :request_payload, default: {}
+      t.jsonb :response_payload, default: {}
+      t.integer :response_status
+      t.integer :duration_ms
+      t.text :error_message
+      t.string :resource_type
+      t.string :resource_id
+
+      t.timestamps
+    end
+
+    add_index :api_requests, :square_location_id
+    add_index :api_requests, :http_method
+    add_index :api_requests, :resource_id
+    add_index :api_requests, %i[resource_type resource_id]
+    add_index :api_requests, :created_at
+    add_index :api_requests, :response_status
+  end
+end

data/lib/square_sandbox_simulator/db/migrate/20260312000007_create_daily_summaries.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+class CreateDailySummaries < ActiveRecord::Migration[8.0]
+  def change
+    create_table :daily_summaries, id: :uuid do |t|
+      t.string :merchant_id, null: false
+      t.date :business_date, null: false
+      t.integer :order_count, default: 0
+      t.integer :payment_count, default: 0
+      t.integer :refund_count, default: 0
+      t.integer :total_revenue, default: 0   # cents
+      t.integer :total_tax, default: 0       # cents
+      t.integer :total_tips, default: 0      # cents
+      t.integer :total_discounts, default: 0 # cents
+      t.jsonb :breakdown, default: {}
+
+      t.timestamps
+    end
+
+    add_index :daily_summaries, %i[merchant_id business_date], unique: true
+    add_index :daily_summaries, :business_date
+    add_index :daily_summaries, :created_at
+  end
+end

data/lib/square_sandbox_simulator/generators/data_loader.rb

@@ -0,0 +1,202 @@
+# frozen_string_literal: true
+
+module SquareSandboxSimulator
+  module Generators
+    # Loads data from PostgreSQL when connected, falling back to JSON files.
+    #
+    # The DB path is preferred because it respects any runtime mutations
+    # (items deactivated, prices changed, categories added via Seeder).
+    # When no DB connection is available the loader reads the static JSON
+    # data files shipped with the gem -- the returned hashes use the same
+    # keys in both cases so callers are unaware of the source.
+    class DataLoader
+      attr_reader :business_type
+
+      def initialize(business_type: :restaurant)
+        @business_type = business_type
+      end
+
+      # -- Primary data accessors (DB-first, JSON fallback) --
+
+      def categories
+        @categories ||= if db_connected?
+                          categories_from_db
+                        else
+                          load_json("categories")["categories"]
+                        end
+      end
+
+      def items
+        @items ||= if db_connected?
+                     items_from_db
+                   else
+                     load_json("items")["items"]
+                   end
+      end
+
+      def tax_rates
+        @tax_rates ||= if db_connected?
+                         tax_rates_from_db
+                       else
+                         load_json("tax_rates")["tax_rates"]
+                       end
+      rescue Error
+        [] # Return empty array if file doesn't exist
+      end
+
+      def category_tax_mapping
+        @category_tax_mapping ||= if db_connected?
+                                    category_tax_mapping_from_db
+                                  else
+                                    load_json("tax_rates")["category_tax_mapping"]
+                                  end
+      rescue Error
+        {} # Return empty hash if file doesn't exist
+      end
+
+      # -- JSON-only accessors (no DB models for these) --
+
+      def discounts
+        @discounts ||= load_json("discounts")["discounts"]
+      end
+
+      def tenders
+        @tenders ||= load_json("tenders")["tenders"]
+      end
+
+      def modifiers
+        @modifiers ||= load_json("modifiers")["modifier_groups"]
+      rescue Error
+        []
+      end
+
+      def coupon_codes
+        @coupon_codes ||= load_json("coupon_codes")["coupon_codes"]
+      rescue Error
+        []
+      end
+
+      # -- Convenience filters --
+
+      def items_for_category(category_name)
+        items.select { |item| item["category"] == category_name }
+      end
+
+      def discounts_by_type(type)
+        discounts.select { |d| d["type"] == type }
+      end
+
+      def time_based_discounts
+        discounts_by_type("time_based")
+      end
+
+      def line_item_discounts
+        discounts.select { |d| d["type"]&.start_with?("line_item") }
+      end
+
+      def loyalty_discounts
+        discounts_by_type("loyalty")
+      end
+
+      def threshold_discounts
+        discounts_by_type("threshold")
+      end
+
+      def active_coupon_codes
+        coupon_codes.select { |c| c["active"] }
+      end
+
+      def find_coupon(code)
+        coupon_codes.find { |c| c["code"].upcase == code.upcase }
+      end
+
+      # -- Data source introspection --
+
+      def data_source
+        db_connected? ? :db : :json
+      end
+
+      private
+
+      def db_connected?
+        Database.connected?
+      end
+
+      # -- DB query methods --
+      # Each method returns data formatted identically to the JSON
+      # structure so callers are unaware of the data source.
+
+      def categories_from_db
+        bt = Models::BusinessType.find_by(key: business_type.to_s)
+        return load_json("categories")["categories"] unless bt
+
+        bt.categories.sorted.map do |cat|
+          {
+            "name" => cat.name,
+            "sort_order" => cat.sort_order,
+            "description" => cat.description,
+          }
+        end
+      end
+
+      def items_from_db
+        bt = Models::BusinessType.find_by(key: business_type.to_s)
+        return load_json("items")["items"] unless bt
+
+        Models::Item.active
+                    .for_business_type(business_type.to_s)
+                    .includes(:category)
+                    .order("categories.sort_order", "items.name")
+                    .map do |item|
+          hash = {
+            "name" => item.name,
+            "price" => item.price,
+            "category" => item.category.name,
+          }
+
+          # Include optional fields when present (mirrors factory traits)
+          hash["sku"]      = item.sku      if item.sku.present?
+          hash["variants"] = item.variants if item.variants.present?
+          hash["unit"]     = item.unit     if item.unit.present?
+          hash["metadata"] = item.metadata if item.metadata.present?
+          hash
+        end
+      end
+
+      def tax_rates_from_db
+        # Tax rates are static configuration without a dedicated DB model.
+        # Always loaded from JSON regardless of DB connection status.
+        load_json("tax_rates")["tax_rates"]
+      end
+
+      def category_tax_mapping_from_db
+        bt = Models::BusinessType.find_by(key: business_type.to_s)
+        return load_json("tax_rates")["category_tax_mapping"] unless bt
+
+        mapping = {}
+        bt.categories.where.not(tax_group: nil).find_each do |cat|
+          mapping[cat.name] = [cat.tax_group]
+        end
+
+        # Fall back to JSON if DB has no tax_group data
+        return load_json("tax_rates")["category_tax_mapping"] if mapping.empty?
+
+        mapping
+      end
+
+      # -- JSON loading --
+
+      def load_json(filename)
+        path = File.join(data_path, "#{filename}.json")
+
+        raise Error, "Data file not found: #{path}" unless File.exist?(path)
+
+        JSON.parse(File.read(path))
+      end
+
+      def data_path
+        File.join(SquareSandboxSimulator.root, "lib", "square_sandbox_simulator", "data", business_type.to_s)
+      end
+    end
+  end
+end