square_sandbox_simulator 0.1.0

data/lib/square_sandbox_simulator/data/salon_spa/tenders.json

@@ -0,0 +1,41 @@
+{
+  "tenders": [
+    {
+      "label": "Cash",
+      "label_key": "com.clover.tender.cash",
+      "opens_cash_drawer": true,
+      "weight": 25
+    },
+    {
+      "label": "Check",
+      "label_key": "com.clover.tender.check",
+      "opens_cash_drawer": true,
+      "weight": 5
+    },
+    {
+      "label": "Gift Card",
+      "label_key": "com.clover.tender.external_gift_card",
+      "opens_cash_drawer": false,
+      "weight": 20
+    },
+    {
+      "label": "External Payment",
+      "label_key": "com.clover.tender.external_payment",
+      "opens_cash_drawer": false,
+      "weight": 10
+    },
+    {
+      "label": "Mobile Payment",
+      "label_key": "com.clover.tender.mobile_payment",
+      "opens_cash_drawer": false,
+      "weight": 20
+    },
+    {
+      "label": "Store Credit",
+      "label_key": "com.clover.tender.store_credit",
+      "opens_cash_drawer": false,
+      "weight": 10
+    }
+  ],
+  "note": "Credit Card and Debit Card are intentionally excluded - they are broken in Clover sandbox"
+}

data/lib/square_sandbox_simulator/database.rb

@@ -0,0 +1,224 @@
+# frozen_string_literal: true
+
+require "active_record"
+require "logger"
+
+module SquareSandboxSimulator
+  # Standalone ActiveRecord connection manager for PostgreSQL.
+  #
+  # Provides database connectivity without requiring Rails.
+  # Used for persisting Square sandbox data (locations, orders, etc.)
+  # alongside the existing JSON-file and API-based workflows.
+  #
+  # When no DATABASE_URL is configured, the simulator falls back
+  # to its original JSON-file behaviour -- call Database.connected?
+  # to check before attempting DB operations.
+  #
+  # @example Connect and run migrations
+  #   SquareSandboxSimulator::Database.connect!("postgres://localhost:5432/square_simulator_development")
+  #   SquareSandboxSimulator::Database.migrate!
+  #
+  # @example Check availability for JSON fallback
+  #   if SquareSandboxSimulator::Database.connected?
+  #     # use ActiveRecord models
+  #   else
+  #     # fall back to JSON files
+  #   end
+  module Database
+    # Directory containing ActiveRecord migration files
+    MIGRATIONS_PATH = File.expand_path("db/migrate", __dir__).freeze
+
+    # Default test database name
+    TEST_DATABASE = "square_simulator_test"
+
+    class << self
+      # Create the database specified in the connection URL.
+      #
+      # Connects to the `postgres` maintenance database, issues
+      # CREATE DATABASE, then disconnects.
+      #
+      # @param url [String] PostgreSQL connection URL
+      # @return [void]
+      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)
+        SquareSandboxSimulator.logger.info("Database created: #{db_name}")
+      rescue ActiveRecord::DatabaseAlreadyExists, ActiveRecord::StatementInvalid => e
+        raise unless e.message.include?("already exists")
+
+        SquareSandboxSimulator.logger.info("Database already exists: #{db_name}")
+      ensure
+        ActiveRecord::Base.connection_pool.disconnect!
+      end
+
+      # Drop the database specified in the connection URL.
+      #
+      # @param url [String] PostgreSQL connection URL
+      # @return [void]
+      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)
+        SquareSandboxSimulator.logger.info("Database dropped: #{db_name}")
+      rescue ActiveRecord::StatementInvalid => e
+        raise unless e.message.include?("does not exist")
+
+        SquareSandboxSimulator.logger.info("Database does not exist: #{db_name}")
+      ensure
+        ActiveRecord::Base.connection_pool.disconnect!
+      end
+
+      # Return the configured database URL from .env.json.
+      #
+      # @return [String] PostgreSQL URL
+      # @raise [Error] if no DATABASE_URL is configured
+      def database_url
+        url = Configuration.database_url_from_file
+        raise Error, "No DATABASE_URL found in .env.json" unless url
+
+        url
+      end
+
+      # Establish a standalone ActiveRecord connection to PostgreSQL.
+      #
+      # @param url [String] A PostgreSQL connection URL
+      #   (e.g. "postgres://user:pass@localhost:5432/square_simulator_development")
+      # @return [void]
+      # @raise [ArgumentError] if the URL is not a PostgreSQL URL
+      # @raise [ActiveRecord::ConnectionNotEstablished] if the connection fails
+      def connect!(url)
+        unless url.match?(%r{\Apostgres(ql)?://}i)
+          raise ArgumentError, "Expected a PostgreSQL URL (postgres:// or postgresql://), got: #{url.split("://").first}://"
+        end
+
+        ActiveRecord::Base.establish_connection(url)
+
+        # Verify the connection is actually usable
+        ActiveRecord::Base.connection.execute("SELECT 1")
+
+        ActiveRecord::Base.logger = SquareSandboxSimulator.logger
+
+        SquareSandboxSimulator.logger.info("Database connected: #{sanitize_url(url)}")
+      end
+
+      # Run pending migrations from lib/square_sandbox_simulator/db/migrate/.
+      #
+      # Uses ActiveRecord::MigrationContext for standalone (non-Rails) usage.
+      #
+      # @return [void]
+      def migrate!
+        ensure_connected!
+
+        SquareSandboxSimulator.logger.info("Running migrations from #{MIGRATIONS_PATH}")
+
+        context = ActiveRecord::MigrationContext.new(MIGRATIONS_PATH)
+        context.migrate
+
+        SquareSandboxSimulator.logger.info("Migrations complete")
+      end
+
+      # Seed the database with realistic Square data using FactoryBot.
+      #
+      # Delegates to {Seeder} which creates BusinessTypes, Categories,
+      # and Items using factory attributes. Idempotent -- safe to call
+      # multiple times without creating duplicates.
+      #
+      # @param business_type [Symbol, String, nil] Optional business type
+      #   (e.g. :restaurant, :retail_clothing). Seeds all types if nil.
+      # @return [Hash] Summary counts (:business_types, :categories, :items)
+      def seed!(business_type: nil)
+        ensure_connected!
+        load_factories!
+
+        # Default to configured business_type if none specified;
+        # pass nil to Seeder to seed ALL types when config is also nil.
+        business_type ||= SquareSandboxSimulator.configuration.business_type
+        Seeder.seed!(business_type: business_type)
+      end
+
+      # Check whether a database connection is established and usable.
+      #
+      # Safe to call at any time -- returns false rather than raising
+      # so callers can decide to fall back to JSON files.
+      #
+      # @return [Boolean]
+      def connected?
+        ActiveRecord::Base.connection_pool.with_connection(&:active?)
+      rescue StandardError
+        false
+      end
+
+      # Disconnect from the database and clean up the connection pool.
+      #
+      # @return [void]
+      def disconnect!
+        ActiveRecord::Base.connection_pool.disconnect!
+        SquareSandboxSimulator.logger.info("Database disconnected")
+      end
+
+      # Build the test database URL.
+      #
+      # @param base_url [String, nil] Base URL to derive test URL from.
+      #   If nil, reads DATABASE_URL from .env.json and swaps the DB name.
+      # @return [String] PostgreSQL URL pointing to the test database
+      def test_database_url(base_url: nil)
+        url = base_url || Configuration.database_url_from_file
+        return "postgres://localhost:5432/#{TEST_DATABASE}" if url.nil?
+
+        # Replace the database name in the URL with the test database name
+        uri = URI.parse(url)
+        uri.path = "/#{TEST_DATABASE}"
+        uri.to_s
+      rescue URI::InvalidURIError
+        "postgres://localhost:5432/#{TEST_DATABASE}"
+      end
+
+      private
+
+      # Raise if no database connection has been established yet.
+      #
+      # @raise [SquareSandboxSimulator::Error] when not connected
+      def ensure_connected!
+        return if connected?
+
+        raise SquareSandboxSimulator::Error,
+              "Database not connected. Call Database.connect!(url) first."
+      end
+
+      # Load FactoryBot factory definitions from the factories directory.
+      # Guarded against repeated calls to avoid "Factory already registered" errors.
+      #
+      # @return [void]
+      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
+        SquareSandboxSimulator.logger.warn("Could not load factories: #{e.message}")
+      end
+
+      # Strip credentials from a database URL for safe logging.
+      #
+      # @param url [String]
+      # @return [String]
+      def sanitize_url(url)
+        uri = URI.parse(url)
+        uri.password = "***" if uri.password
+        uri.user = "***" if uri.user
+        uri.to_s
+      rescue URI::InvalidURIError
+        url.gsub(%r{://[^@]+@}, "://***:***@")
+      end
+    end
+  end
+end

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

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+FactoryBot.define do
+  factory :api_request, class: "SquareSandboxSimulator::Models::ApiRequest" do
+    http_method { "GET" }
+    sequence(:url) { |n| "https://connect.squareupsandbox.com/v2/orders/ORDER#{n}" }
+    response_status { 200 }
+    duration_ms { 150 }
+    resource_type { "Order" }
+    request_payload { {} }
+    response_payload { {} }
+
+    # ── HTTP method traits ─────────────────────────────────────
+
+    trait :get do
+      http_method { "GET" }
+      response_status { 200 }
+    end
+
+    trait :post do
+      http_method { "POST" }
+      response_status { 201 }
+      request_payload { { name: "New Item", price: 999 } }
+    end
+
+    trait :put do
+      http_method { "PUT" }
+      response_status { 200 }
+      request_payload { { name: "Updated Item" } }
+    end
+
+    trait :delete do
+      http_method { "DELETE" }
+      response_status { 204 }
+      response_payload { {} }
+    end
+
+    # ── Status traits ──────────────────────────────────────────
+
+    trait :error do
+      http_method { "POST" }
+      response_status { 500 }
+      error_message { "Internal Server Error" }
+      response_payload { { message: "Internal Server Error" } }
+    end
+
+    trait :not_found do
+      response_status { 404 }
+      error_message { "Not Found" }
+      response_payload { { message: "Not Found" } }
+    end
+
+    trait :rate_limited do
+      response_status { 429 }
+      error_message { "Too Many Requests" }
+      response_payload { { message: "Rate limit exceeded. Retry after 60s." } }
+    end
+
+    trait :unauthorized do
+      response_status { 401 }
+      error_message { "Unauthorized" }
+      response_payload { { message: "Invalid API token" } }
+    end
+
+    # ── Performance traits ─────────────────────────────────────
+
+    trait :slow do
+      duration_ms { 2500 }
+    end
+
+    trait :fast do
+      duration_ms { 25 }
+    end
+
+    # ── Resource traits ────────────────────────────────────────
+
+    trait :order_resource do
+      resource_type { "Order" }
+      sequence(:resource_id) { |n| "ORDER#{n}" }
+      sequence(:url) { |n| "https://connect.squareupsandbox.com/v2/orders/ORDER#{n}" }
+    end
+
+    trait :item_resource do
+      resource_type { "Item" }
+      sequence(:resource_id) { |n| "ITEM#{n}" }
+      sequence(:url) { |n| "https://connect.squareupsandbox.com/v2/catalog/object/ITEM#{n}" }
+    end
+
+    trait :payment_resource do
+      resource_type { "Payment" }
+      sequence(:resource_id) { |n| "PAY#{n}" }
+      sequence(:url) { |n| "https://connect.squareupsandbox.com/v2/payments/PAY#{n}" }
+    end
+  end
+end

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

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+FactoryBot.define do
+  factory :business_type, class: "SquareSandboxSimulator::Models::BusinessType" do
+    sequence(:key) { |n| "business_type_#{n}" }
+    name { "Test Business Type" }
+    industry { "food" }
+    order_profile { {} }
+
+    # ── Food (6) ──────────────────────────────────────────────
+
+    trait :restaurant do
+      key { "restaurant" }
+      name { "Restaurant" }
+      industry { "food" }
+      description { "Full-service casual dining restaurant" }
+      order_profile do
+        {
+          "avg_order_value_cents" => 2500,
+          "avg_items_per_order" => 3,
+          "peak_hours" => %w[11:30 12:30 18:00 19:30],
+          "meal_periods" => %w[breakfast lunch dinner],
+          "dining_options" => %w[HERE TO_GO DELIVERY],
+          "tip_percentage_range" => [15, 25],
+          "tax_rate" => 8.875,
+        }
+      end
+    end
+
+    trait :cafe_bakery do
+      key { "cafe_bakery" }
+      name { "Cafe & Bakery" }
+      industry { "food" }
+      description { "Coffee shop with fresh-baked pastries and light fare" }
+      order_profile do
+        {
+          "avg_order_value_cents" => 1200,
+          "avg_items_per_order" => 2,
+          "peak_hours" => %w[07:00 08:30 12:00],
+          "meal_periods" => %w[breakfast lunch],
+          "dining_options" => %w[HERE TO_GO],
+          "tip_percentage_range" => [10, 20],
+          "tax_rate" => 8.875,
+        }
+      end
+    end
+
+    trait :bar_nightclub do
+      key { "bar_nightclub" }
+      name { "Bar & Nightclub" }
+      industry { "food" }
+      description { "Full bar with craft cocktails, draft beer, and late-night bites" }
+      order_profile do
+        {
+          "avg_order_value_cents" => 3500,
+          "avg_items_per_order" => 4,
+          "peak_hours" => %w[17:00 21:00 23:00],
+          "meal_periods" => %w[dinner late_night],
+          "dining_options" => %w[HERE],
+          "tip_percentage_range" => [18, 25],
+          "tax_rate" => 8.875,
+        }
+      end
+    end
+
+    trait :food_truck do
+      key { "food_truck" }
+      name { "Food Truck" }
+      industry { "food" }
+      description { "Mobile street food — tacos, burritos, and Mexican fare" }
+      order_profile do
+        {
+          "avg_order_value_cents" => 1400,
+          "avg_items_per_order" => 3,
+          "peak_hours" => %w[11:30 12:30 18:00],
+          "meal_periods" => %w[lunch dinner],
+          "dining_options" => %w[TO_GO],
+          "tip_percentage_range" => [10, 20],
+          "tax_rate" => 8.875,
+        }
+      end
+    end
+
+    trait :fine_dining do
+      key { "fine_dining" }
+      name { "Fine Dining" }
+      industry { "food" }
+      description { "Upscale prix-fixe and a la carte dining experience" }
+      order_profile do
+        {
+          "avg_order_value_cents" => 12_000,
+          "avg_items_per_order" => 4,
+          "peak_hours" => %w[18:00 19:30 20:30],
+          "meal_periods" => %w[dinner],
+          "dining_options" => %w[HERE],
+          "tip_percentage_range" => [20, 30],
+          "tax_rate" => 8.875,
+        }
+      end
+    end
+
+    trait :pizzeria do
+      key { "pizzeria" }
+      name { "Pizzeria" }
+      industry { "food" }
+      description { "Pizza shop with classic and specialty pies, calzones, and sides" }
+      order_profile do
+        {
+          "avg_order_value_cents" => 2200,
+          "avg_items_per_order" => 3,
+          "peak_hours" => %w[12:00 18:00 20:00],
+          "meal_periods" => %w[lunch dinner],
+          "dining_options" => %w[HERE TO_GO DELIVERY],
+          "tip_percentage_range" => [12, 20],
+          "tax_rate" => 8.875,
+        }
+      end
+    end
+
+    # ── Retail (2) ────────────────────────────────────────────
+
+    trait :retail_clothing do
+      key { "retail_clothing" }
+      name { "Clothing Store" }
+      industry { "retail" }
+      description { "Casual wear and accessories with size/color variants" }
+      order_profile do
+        {
+          "avg_order_value_cents" => 7500,
+          "avg_items_per_order" => 2,
+          "peak_hours" => %w[11:00 14:00 17:00],
+          "meal_periods" => [],
+          "dining_options" => [],
+          "tip_percentage_range" => [0, 0],
+          "tax_rate" => 8.875,
+        }
+      end
+    end
+
+    trait :retail_general do
+      key { "retail_general" }
+      name { "General Store" }
+      industry { "retail" }
+      description { "Everyday essentials — electronics, home goods, personal care" }
+      order_profile do
+        {
+          "avg_order_value_cents" => 3500,
+          "avg_items_per_order" => 3,
+          "peak_hours" => %w[10:00 13:00 17:00],
+          "meal_periods" => [],
+          "dining_options" => [],
+          "tip_percentage_range" => [0, 0],
+          "tax_rate" => 8.875,
+        }
+      end
+    end
+
+    # ── Services (1) ──────────────────────────────────────────
+
+    trait :salon_spa do
+      key { "salon_spa" }
+      name { "Salon & Spa" }
+      industry { "service" }
+      description { "Full-service hair salon, spa treatments, and nail services" }
+      order_profile do
+        {
+          "avg_order_value_cents" => 8500,
+          "avg_items_per_order" => 2,
+          "peak_hours" => %w[10:00 13:00 16:00],
+          "meal_periods" => [],
+          "dining_options" => [],
+          "tip_percentage_range" => [15, 25],
+          "tax_rate" => 0.0,
+        }
+      end
+    end
+  end
+end