epos_now_sandbox_simulator 0.1.0

data/lib/epos_now_sandbox_simulator/data/retail_general/items.json

@@ -0,0 +1,17 @@
+{
+  "items": [
+    { "name": "Phone Charger", "price": 14.99, "category": "Electronics", "sku": "RET-ELC-001" },
+    { "name": "Bluetooth Speaker", "price": 29.99, "category": "Electronics", "sku": "RET-ELC-002" },
+    { "name": "USB Cable", "price": 9.99, "category": "Electronics", "sku": "RET-ELC-003" },
+    { "name": "T-Shirt", "price": 19.99, "category": "Clothing", "sku": "RET-CLO-001" },
+    { "name": "Baseball Cap", "price": 14.99, "category": "Clothing", "sku": "RET-CLO-002" },
+    { "name": "Socks Pack", "price": 8.99, "category": "Clothing", "sku": "RET-CLO-003" },
+    { "name": "Candle", "price": 12.99, "category": "Home & Garden", "sku": "RET-HOM-001" },
+    { "name": "Plant Pot", "price": 9.99, "category": "Home & Garden", "sku": "RET-HOM-002" },
+    { "name": "Picture Frame", "price": 11.99, "category": "Home & Garden", "sku": "RET-HOM-003" },
+    { "name": "Hand Cream", "price": 7.99, "category": "Health & Beauty", "sku": "RET-HLT-001" },
+    { "name": "Lip Balm", "price": 4.99, "category": "Health & Beauty", "sku": "RET-HLT-002" },
+    { "name": "Snack Bar", "price": 2.99, "category": "Groceries", "sku": "RET-GRC-001" },
+    { "name": "Water Bottle", "price": 1.99, "category": "Groceries", "sku": "RET-GRC-002" }
+  ]
+}

data/lib/epos_now_sandbox_simulator/data/retail_general/tenders.json

@@ -0,0 +1,8 @@
+{
+  "tenders": [
+    { "name": "Cash", "description": "Cash payment", "weight": 20 },
+    { "name": "Credit Card", "description": "Credit card payment", "weight": 50 },
+    { "name": "Debit Card", "description": "Debit card payment", "weight": 25 },
+    { "name": "Gift Card", "description": "Gift card payment", "weight": 5 }
+  ]
+}

data/lib/epos_now_sandbox_simulator/database.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require "active_record"
+require "logger"
+
+module EposNowSandboxSimulator
+  # Standalone ActiveRecord connection manager for PostgreSQL.
+  #
+  # Provides database connectivity without requiring Rails.
+  # Used for persisting Epos Now sandbox data (orders, payments, etc.)
+  # alongside the existing JSON-file and API-based workflows.
+  module Database
+    MIGRATIONS_PATH = File.expand_path("db/migrate", __dir__).freeze
+    TEST_DATABASE = "epos_now_simulator_test"
+
+    class << self
+      def create!(url)
+        db_name = URI.parse(url).path.delete_prefix("/")
+        maintenance_url = url.sub(%r{/[^/]+\z}, "/postgres")
+
+        ActiveRecord::Base.establish_connection(maintenance_url)
+        ActiveRecord::Base.connection.create_database(db_name)
+        EposNowSandboxSimulator.logger.info("Database created: #{db_name}")
+      rescue ActiveRecord::DatabaseAlreadyExists, ActiveRecord::StatementInvalid => e
+        raise unless e.message.include?("already exists")
+
+        EposNowSandboxSimulator.logger.info("Database already exists: #{db_name}")
+      ensure
+        ActiveRecord::Base.connection_pool.disconnect!
+      end
+
+      def drop!(url)
+        db_name = URI.parse(url).path.delete_prefix("/")
+        maintenance_url = url.sub(%r{/[^/]+\z}, "/postgres")
+
+        ActiveRecord::Base.establish_connection(maintenance_url)
+        ActiveRecord::Base.connection.drop_database(db_name)
+        EposNowSandboxSimulator.logger.info("Database dropped: #{db_name}")
+      rescue ActiveRecord::StatementInvalid => e
+        raise unless e.message.include?("does not exist")
+
+        EposNowSandboxSimulator.logger.info("Database does not exist: #{db_name}")
+      ensure
+        ActiveRecord::Base.connection_pool.disconnect!
+      end
+
+      def database_url
+        url = Configuration.database_url_from_file
+        raise Error, "No DATABASE_URL found in .env.json" unless url
+
+        url
+      end
+
+      def connect!(url)
+        raise ArgumentError, "Expected a PostgreSQL URL, got: #{url.split("://").first}://" unless url.match?(%r{\Apostgres(ql)?://}i)
+
+        ActiveRecord::Base.establish_connection(url)
+        ActiveRecord::Base.connection.execute("SELECT 1")
+        ActiveRecord::Base.logger = EposNowSandboxSimulator.logger
+
+        EposNowSandboxSimulator.logger.info("Database connected: #{sanitize_url(url)}")
+      end
+
+      def migrate!
+        ensure_connected!
+
+        EposNowSandboxSimulator.logger.info("Running migrations from #{MIGRATIONS_PATH}")
+        context = ActiveRecord::MigrationContext.new(MIGRATIONS_PATH)
+        context.migrate
+        EposNowSandboxSimulator.logger.info("Migrations complete")
+      end
+
+      def seed!(business_type: nil)
+        ensure_connected!
+        load_factories!
+
+        business_type ||= EposNowSandboxSimulator.configuration.business_type
+        Seeder.seed!(business_type: business_type)
+      end
+
+      def connected?
+        ActiveRecord::Base.connection_pool.with_connection(&:active?)
+      rescue StandardError
+        false
+      end
+
+      def disconnect!
+        ActiveRecord::Base.connection_pool.disconnect!
+        EposNowSandboxSimulator.logger.info("Database disconnected")
+      end
+
+      def test_database_url(base_url: nil)
+        url = base_url || Configuration.database_url_from_file
+        return "postgres://localhost:5432/#{TEST_DATABASE}" if url.nil?
+
+        uri = URI.parse(url)
+        uri.path = "/#{TEST_DATABASE}"
+        uri.to_s
+      rescue URI::InvalidURIError
+        "postgres://localhost:5432/#{TEST_DATABASE}"
+      end
+
+      private
+
+      def ensure_connected!
+        return if connected?
+
+        raise EposNowSandboxSimulator::Error,
+              "Database not connected. Call Database.connect!(url) first."
+      end
+
+      def load_factories!
+        return if @factories_loaded
+
+        require "factory_bot"
+
+        factories_path = File.expand_path("db/factories", __dir__)
+        FactoryBot.definition_file_paths = [factories_path] if Dir.exist?(factories_path)
+        FactoryBot.find_definitions
+        @factories_loaded = true
+      rescue StandardError => e
+        EposNowSandboxSimulator.logger.warn("Could not load factories: #{e.message}")
+      end
+
+      def sanitize_url(url)
+        uri = URI.parse(url)
+        has_password = !uri.password.nil?
+        uri.user = "***" if uri.user
+        uri.password = "***" if has_password
+        uri.to_s
+      rescue URI::InvalidURIError
+        url.gsub(%r{://[^@]+@}, "://***:***@")
+      end
+    end
+  end
+end

data/lib/epos_now_sandbox_simulator/db/factories/api_requests.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+FactoryBot.define do
+  factory :api_request, class: "EposNowSandboxSimulator::Models::ApiRequest" do
+    http_method { "GET" }
+    url { "https://api.eposnowhq.com/api/V2/Category" }
+    request_payload { {} }
+    response_status { 200 }
+    response_payload { {} }
+    duration_ms { rand(50..500) }
+    resource_type { "Category" }
+  end
+end

data/lib/epos_now_sandbox_simulator/db/factories/business_types.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+FactoryBot.define do
+  factory :business_type, class: "EposNowSandboxSimulator::Models::BusinessType" do
+    sequence(:key) { |n| "business_type_#{n}" }
+    name { key.tr("_", " ").split.map(&:capitalize).join(" ") }
+    industry { "Food" }
+    order_profile { {} }
+
+    trait :restaurant do
+      key { "restaurant" }
+      name { "Restaurant" }
+      industry { "Food" }
+    end
+
+    trait :cafe_bakery do
+      key { "cafe_bakery" }
+      name { "Cafe Bakery" }
+      industry { "Food" }
+    end
+
+    trait :bar_nightclub do
+      key { "bar_nightclub" }
+      name { "Bar Nightclub" }
+      industry { "Food" }
+    end
+
+    trait :retail_general do
+      key { "retail_general" }
+      name { "Retail General" }
+      industry { "Retail" }
+    end
+  end
+end

data/lib/epos_now_sandbox_simulator/db/factories/categories.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+FactoryBot.define do
+  factory :category, class: "EposNowSandboxSimulator::Models::Category" do
+    business_type
+    sequence(:name) { |n| "Category #{n}" }
+    sort_order { 1 }
+    description { "A test category" }
+  end
+end

data/lib/epos_now_sandbox_simulator/db/factories/items.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+FactoryBot.define do
+  factory :item, class: "EposNowSandboxSimulator::Models::Item" do
+    business_type
+    category
+    sequence(:name) { |n| "Item #{n}" }
+    price { rand(299..2999) } # cents
+    sequence(:sku) { |n| "SKU-#{n.to_s.rjust(5, "0")}" }
+    metadata { {} }
+  end
+end

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

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+FactoryBot.define do
+  factory :simulated_order, class: "EposNowSandboxSimulator::Models::SimulatedOrder" do
+    sequence(:epos_now_transaction_id) { |n| n + 10_000 }
+    status { "paid" }
+    business_date { Date.today }
+    dining_option { %w[walk_in take_away delivery].sample }
+    meal_period { %w[breakfast lunch happy_hour dinner late_night].sample }
+    subtotal { rand(1000..5000) }
+    tax_amount { (subtotal * 0.0825).round }
+    tip_amount { rand(0..500) }
+    discount_amount { 0 }
+    total { subtotal + tax_amount + tip_amount - discount_amount }
+    metadata { {} }
+
+    trait :refunded do
+      status { "refunded" }
+    end
+
+    trait :open do
+      status { "open" }
+    end
+  end
+end

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

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+FactoryBot.define do
+  factory :simulated_payment, class: "EposNowSandboxSimulator::Models::SimulatedPayment" do
+    simulated_order
+    sequence(:epos_now_tender_id) { |n| n + 20_000 }
+    tender_name { "Credit Card" }
+    amount { simulated_order&.total || rand(1000..5000) }
+    tip_amount { 0 }
+    tax_amount { 0 }
+    status { "success" }
+    payment_type { "credit_card" }
+  end
+end

data/lib/epos_now_sandbox_simulator/db/migrate/20260312000001_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/epos_now_sandbox_simulator/db/migrate/20260312000002_create_business_types.rb

@@ -0,0 +1,16 @@
+# 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.string :industry, null: false
+      t.jsonb :order_profile, default: {}
+
+      t.timestamps
+
+      t.index :key, unique: true
+    end
+  end
+end

data/lib/epos_now_sandbox_simulator/db/migrate/20260312000003_create_categories.rb

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

data/lib/epos_now_sandbox_simulator/db/migrate/20260312000004_create_items.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+class CreateItems < ActiveRecord::Migration[8.0]
+  def change
+    create_table :items, id: :uuid do |t|
+      t.string :name, null: false
+      t.integer :price, null: false # price in cents
+      t.string :sku
+      t.string :barcode
+      t.jsonb :metadata, default: {}
+      t.references :business_type, type: :uuid, null: false, foreign_key: true
+      t.references :category, type: :uuid, foreign_key: true
+
+      t.timestamps
+
+      t.index :sku, unique: true
+    end
+  end
+end

data/lib/epos_now_sandbox_simulator/db/migrate/20260312000005_create_simulated_orders.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+class CreateSimulatedOrders < ActiveRecord::Migration[8.0]
+  def change
+    create_table :simulated_orders, id: :uuid do |t|
+      t.integer :epos_now_transaction_id
+      t.string :status, null: false, default: "open"
+      t.date :business_date
+      t.string :dining_option       # walk_in, take_away, delivery
+      t.string :meal_period         # breakfast, lunch, happy_hour, dinner, late_night
+      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.jsonb :metadata, default: {}
+
+      t.timestamps
+
+      t.index :epos_now_transaction_id, unique: true
+      t.index :status
+      t.index :business_date
+      t.index :meal_period
+      t.index :dining_option
+    end
+  end
+end

data/lib/epos_now_sandbox_simulator/db/migrate/20260312000006_create_simulated_payments.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+class CreateSimulatedPayments < ActiveRecord::Migration[8.0]
+  def change
+    create_table :simulated_payments, id: :uuid do |t|
+      t.references :simulated_order, type: :uuid, null: false, foreign_key: { on_delete: :cascade }
+      t.integer :epos_now_tender_id
+      t.string :tender_name, null: false
+      t.integer :amount, null: false, 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
+
+      t.index :epos_now_tender_id, unique: true
+      t.index :tender_name
+      t.index :status
+    end
+  end
+end

data/lib/epos_now_sandbox_simulator/db/migrate/20260312000007_create_api_requests.rb

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

data/lib/epos_now_sandbox_simulator/db/migrate/20260312000008_create_daily_summaries.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+class CreateDailySummaries < ActiveRecord::Migration[8.0]
+  def change
+    create_table :daily_summaries, id: :uuid do |t|
+      t.date :summary_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
+
+      t.index :summary_date, unique: true
+    end
+  end
+end

data/lib/epos_now_sandbox_simulator/generators/data_loader.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module EposNowSandboxSimulator
+  module Generators
+    # Loads business data from DB (preferred) or JSON files (fallback).
+    #
+    # Returns identically-shaped hashes regardless of source.
+    class DataLoader
+      DATA_DIR = File.expand_path("../data", __dir__).freeze
+
+      BUSINESS_TYPES = %i[restaurant cafe_bakery bar_nightclub retail_general].freeze
+
+      attr_reader :business_type
+
+      def initialize(business_type: :restaurant)
+        @business_type = business_type.to_sym
+      end
+
+      # Load categories for the business type
+      # @return [Array<Hash>] Categories with :name, :sort_order, :description
+      def load_categories
+        if Database.connected?
+          load_categories_from_db
+        else
+          load_categories_from_json
+        end
+      end
+
+      # Load items for the business type
+      # @return [Array<Hash>] Items with :name, :price, :category, :sku
+      def load_items
+        if Database.connected?
+          load_items_from_db
+        else
+          load_items_from_json
+        end
+      end
+
+      # Load tender types
+      # @return [Array<Hash>] Tenders with :name, :description, :weight
+      def load_tenders
+        load_from_json("tenders")["tenders"] || []
+      end
+
+      # Load items grouped by category
+      # @return [Hash<String, Array<Hash>>] Category name => items
+      def load_items_by_category
+        items = load_items
+        items.group_by { |i| i["category"] || i[:category] }
+      end
+
+      private
+
+      def load_categories_from_db
+        bt = Models::BusinessType.find_by(key: business_type.to_s)
+        return load_categories_from_json unless bt
+
+        bt.categories.order(:sort_order).map do |cat|
+          { "name" => cat.name, "sort_order" => cat.sort_order, "description" => cat.description }
+        end
+      end
+
+      def load_items_from_db
+        bt = Models::BusinessType.find_by(key: business_type.to_s)
+        return load_items_from_json unless bt
+
+        bt.items.includes(:category).map do |item|
+          {
+            "name" => item.name,
+            "price" => item.price / 100.0, # stored in cents
+            "category" => item.category&.name,
+            "sku" => item.sku
+          }
+        end
+      end
+
+      def load_categories_from_json
+        load_from_json("categories")["categories"] || []
+      end
+
+      def load_items_from_json
+        load_from_json("items")["items"] || []
+      end
+
+      def load_from_json(filename)
+        path = File.join(DATA_DIR, business_type.to_s, "#{filename}.json")
+
+        unless File.exist?(path)
+          EposNowSandboxSimulator.logger.warn "Data file not found: #{path}"
+          return {}
+        end
+
+        JSON.parse(File.read(path))
+      rescue JSON::ParserError => e
+        EposNowSandboxSimulator.logger.error "Failed to parse #{path}: #{e.message}"
+        {}
+      end
+    end
+  end
+end

data/lib/epos_now_sandbox_simulator/generators/entity_generator.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module EposNowSandboxSimulator
+  module Generators
+    # Sets up all POS entities in Epos Now: categories, products, tender types.
+    #
+    # All operations are idempotent — safe to run multiple times.
+    #
+    # @example
+    #   generator = EntityGenerator.new(business_type: :restaurant)
+    #   generator.setup_all
+    class EntityGenerator
+      attr_reader :business_type, :services, :data_loader
+
+      def initialize(business_type: :restaurant, config: nil)
+        @business_type = business_type.to_sym
+        @config = config || EposNowSandboxSimulator.configuration
+        @services = Services::EposNow::ServicesManager.new(config: @config)
+        @data_loader = DataLoader.new(business_type: @business_type)
+      end
+
+      # Set up everything: categories, products, tender types
+      def setup_all
+        logger.info "Setting up #{business_type} entities..."
+
+        tender_types = setup_tender_types
+        categories = setup_categories
+        products = setup_products(categories)
+
+        stats = {
+          tender_types: tender_types.size,
+          categories: categories.size,
+          products: products.size
+        }
+
+        logger.info "Setup complete: #{stats}"
+        stats
+      end
+
+      # Create tender types from JSON data
+      # @return [Array<Hash>] Created/existing tender types
+      def setup_tender_types
+        tenders_data = data_loader.load_tenders
+        logger.info "Setting up #{tenders_data.size} tender types..."
+
+        tenders_data.map do |td|
+          services.tender.find_or_create_tender_type(
+            name: td["name"],
+            description: td["description"]
+          )
+        end
+      end
+
+      # Create categories from JSON data
+      # @return [Hash<String, Hash>] Category name => Epos Now category response
+      def setup_categories
+        categories_data = data_loader.load_categories
+        logger.info "Setting up #{categories_data.size} categories..."
+
+        result = {}
+        categories_data.each do |cat|
+          epos_cat = services.inventory.find_or_create_category(
+            name: cat["name"],
+            description: cat["description"],
+            show_on_till: true,
+            sort_position: cat["sort_order"]
+          )
+          result[cat["name"]] = epos_cat
+        end
+
+        result
+      end
+
+      # Create products from JSON data, linked to categories
+      # @param categories [Hash<String, Hash>] Category name => Epos Now category
+      # @return [Array<Hash>] Created/existing products
+      def setup_products(categories = nil)
+        categories ||= setup_categories
+        items_data = data_loader.load_items
+        logger.info "Setting up #{items_data.size} products..."
+
+        items_data.map do |item|
+          category = categories[item["category"]]
+          category_id = category&.dig("Id")
+
+          services.inventory.find_or_create_product(
+            name: item["name"],
+            sale_price: item["price"],
+            cost_price: (item["price"] * 0.35).round(2), # ~35% cost
+            category_id: category_id,
+            barcode: item["sku"]
+          )
+        end
+      end
+
+      private
+
+      def logger
+        EposNowSandboxSimulator.logger
+      end
+    end
+  end
+end