skytab_sandbox_simulator 0.1.0

data/lib/skytab_sandbox_simulator/seeder.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+require "factory_bot"
+
+module SkytabSandboxSimulator
+  # Seeds the database with realistic SkyTab 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
+  #   SkytabSandboxSimulator::Seeder.seed!
+  #
+  # @example Seed a single business type
+  #   SkytabSandboxSimulator::Seeder.seed!(business_type: :restaurant)
+  #
+  class Seeder
+    # Maps each business type trait to its category traits,
+    # and each category trait to its item traits.
+    SEED_MAP = {
+      restaurant: {
+        appetizers: %i[buffalo_wings mozzarella_sticks loaded_nachos spinach_artichoke_dip calamari
+                       bruschetta shrimp_cocktail],
+        entrees: %i[classic_burger grilled_salmon ny_strip_steak chicken_parmesan fettuccine_alfredo
+                     fish_and_chips bbq_ribs mushroom_risotto shrimp_scampi],
+        sides: %i[french_fries sweet_potato_fries onion_rings coleslaw mashed_potatoes
+                   steamed_vegetables garlic_bread],
+        desserts: %i[chocolate_brownie ny_cheesecake apple_pie tiramisu creme_brulee],
+        beverages: %i[soft_drink iced_tea lemonade coffee hot_tea sparkling_water fresh_juice],
+        alcohol: %i[draft_beer domestic_beer import_beer house_wine margarita old_fashioned],
+        kids_menu: %i[chicken_tenders kids_mac_and_cheese mini_burger grilled_cheese kids_quesadilla],
+        specials: %i[chefs_special soup_of_the_day]
+      },
+      cafe_bakery: {
+        coffee_espresso: %i[house_drip_coffee espresso cappuccino latte cold_brew],
+        pastries: %i[croissant blueberry_muffin cinnamon_roll chocolate_chip_cookie almond_croissant],
+        breakfast_items: %i[avocado_toast breakfast_burrito acai_bowl yogurt_parfait],
+        sandwiches_wraps: %i[turkey_club caprese_panini chicken_caesar_wrap blt],
+        smoothies_juice: %i[berry_blast_smoothie green_detox_juice mango_tango_smoothie fresh_oj]
+      },
+      bar_nightclub: {
+        draft_beer: %i[bar_house_lager bar_ipa bar_stout bar_wheat_beer],
+        cocktails: %i[bar_margarita bar_old_fashioned bar_mojito bar_espresso_martini],
+        spirits: %i[whiskey_neat vodka_soda tequila_shot rum_and_coke],
+        wine_list: %i[bar_house_red bar_house_white bar_prosecco bar_rose],
+        bar_snacks: %i[bar_loaded_fries bar_sliders bar_wings bar_pretzel_bites]
+      },
+      pizzeria: {
+        pizzas: %i[margherita pepperoni supreme hawaiian bbq_chicken_pizza meat_lovers],
+        calzones: %i[classic_calzone meat_calzone stromboli spinach_calzone],
+        pizza_sides: %i[pizza_garlic_bread pizza_garden_salad pizza_caesar_salad garlic_knots],
+        pizza_drinks: %i[pizza_fountain_drink pizza_iced_tea pizza_lemonade],
+        pizza_desserts: %i[cannoli pizza_brownie pizza_cheesecake]
+      },
+      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[fine_creme_brulee chocolate_souffle tasting_plate cheese_board
+                           fine_tiramisu],
+        fine_wines: %i[fine_champagne fine_cabernet fine_pinot_noir fine_chardonnay],
+        fine_cocktails: %i[fine_negroni fine_manhattan fine_french_75]
+      }
+    }.freeze
+
+    # Expected category counts per business type (for spec validation).
+    CATEGORY_COUNTS = SEED_MAP.transform_values { |cats| cats.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
+
+      SkytabSandboxSimulator.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.
+    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.
+    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
+
+    # Find or create a category using factory attributes.
+    def seed_category(trait, business_type)
+      attrs = FactoryBot.attributes_for(:category, trait)
+      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
+
+    # Find or create an item using factory attributes.
+    def seed_item(trait, category)
+      attrs = FactoryBot.attributes_for(:item, trait)
+      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

data/lib/skytab_sandbox_simulator/services/base_service.rb

@@ -0,0 +1,227 @@
+# frozen_string_literal: true
+
+module SkytabSandboxSimulator
+  module Services
+    # Base service for all SkyTab API interactions.
+    # Provides HTTP client, logging, and error handling.
+    class BaseService
+      attr_reader :config, :logger
+
+      def initialize(config: nil)
+        @config = config || SkytabSandboxSimulator.configuration
+        @config.validate!
+        @logger = @config.logger
+      end
+
+      protected
+
+      # Make HTTP request to SkyTab (Shift4) API
+      #
+      # Every call is audit-logged to the `api_requests` table when a
+      # database connection is available. If no DB is connected the
+      # request still executes normally.
+      #
+      # @param method [Symbol] HTTP method (:get, :post, :put, :delete)
+      # @param path [String] API endpoint path
+      # @param payload [Hash, nil] Request body for POST/PUT
+      # @param params [Hash, nil] Query parameters
+      # @param resource_type [String, nil] Logical resource (e.g. "Ticket")
+      # @param resource_id [String, nil] Resource ID
+      # @return [Hash, nil] Parsed JSON response
+      def request(method, path, payload: nil, params: nil, resource_type: nil, resource_id: nil)
+        url = build_url(path, params)
+
+        log_request(method, url, payload)
+        start_time = Time.now
+
+        response = execute_request(method, url, payload)
+
+        duration_ms = ((Time.now - start_time) * 1000).round
+        log_response(response, duration_ms)
+
+        parsed = parse_response(response)
+
+        audit_api_request(
+          http_method: method.to_s.upcase,
+          url: url,
+          request_payload: payload,
+          response_status: response.code,
+          response_payload: parsed,
+          duration_ms: duration_ms,
+          resource_type: resource_type,
+          resource_id: resource_id
+        )
+
+        parsed
+      rescue RestClient::ExceptionWithResponse => e
+        duration_ms = ((Time.now - start_time) * 1000).round if start_time
+
+        audit_api_request(
+          http_method: method.to_s.upcase,
+          url: url,
+          request_payload: payload,
+          response_status: e.http_code,
+          response_payload: (JSON.parse(e.response.body) rescue nil),
+          duration_ms: duration_ms,
+          error_message: "HTTP #{e.http_code}: #{e.message}",
+          resource_type: resource_type,
+          resource_id: resource_id
+        )
+
+        handle_api_error(e)
+      rescue StandardError => e
+        duration_ms = ((Time.now - start_time) * 1000).round if start_time
+
+        audit_api_request(
+          http_method: method.to_s.upcase,
+          url: url,
+          request_payload: payload,
+          duration_ms: duration_ms,
+          error_message: e.message,
+          resource_type: resource_type,
+          resource_id: resource_id
+        )
+
+        logger.error "Request failed: #{e.message}"
+        raise ApiError, e.message
+      end
+
+      # Build Marketplace API endpoint path
+      #
+      # @param path [String] Relative path
+      # @return [String] Full endpoint path
+      def marketplace_endpoint(path)
+        "marketplace/v2/#{path}"
+      end
+
+      # Build POS API endpoint path for a location
+      #
+      # @param path [String] Relative path after location ID
+      # @return [String] Full endpoint path
+      def pos_endpoint(path)
+        "pos/v2/#{config.location_id}/#{path}"
+      end
+
+      private
+
+      def headers
+        {
+          "Authorization" => "Bearer #{config.access_token}",
+          "Content-Type" => "application/json",
+          "Accept" => "application/json"
+        }
+      end
+
+      def build_url(path, params = nil)
+        base = path.start_with?("http") ? path : "#{config.environment}#{path}"
+        return base unless params&.any?
+
+        uri = URI(base)
+        uri.query = URI.encode_www_form(params)
+        uri.to_s
+      end
+
+      def execute_request(method, url, payload)
+        case method
+        when :get    then RestClient.get(url, headers)
+        when :post   then RestClient.post(url, payload&.to_json, headers)
+        when :put    then RestClient.put(url, payload&.to_json, headers)
+        when :delete then RestClient.delete(url, headers)
+        else raise ArgumentError, "Unsupported HTTP method: #{method}"
+        end
+      end
+
+      def parse_response(response)
+        return nil if response.body.nil? || response.body.empty?
+
+        JSON.parse(response.body)
+      rescue JSON::ParserError => e
+        logger.error "Failed to parse response: #{e.message}"
+        raise ApiError, "Invalid JSON response"
+      end
+
+      def handle_api_error(error)
+        body = begin
+          JSON.parse(error.response.body)
+        rescue StandardError
+          { "message" => error.response.body }
+        end
+
+        logger.error "API Error (#{error.http_code}): #{body}"
+        raise ApiError, "HTTP #{error.http_code}: #{body["message"] || body}"
+      end
+
+      def log_request(method, url, payload)
+        logger.debug "-> #{method.to_s.upcase} #{url}"
+        logger.debug "  Payload: #{payload.inspect}" if payload
+      end
+
+      def log_response(response, duration_ms)
+        logger.debug "<- #{response.code} (#{duration_ms}ms)"
+      end
+
+      # Persist an API request record for audit trail.
+      # Silently no-ops when DB is not connected.
+      def audit_api_request(http_method:, url:, request_payload: nil, response_status: nil,
+                            response_payload: nil, duration_ms: nil, error_message: nil,
+                            resource_type: nil, resource_id: nil)
+        return unless Database.connected?
+
+        attrs = {
+          http_method: http_method,
+          url: url,
+          request_payload: request_payload || {},
+          response_payload: response_payload || {},
+          response_status: response_status,
+          duration_ms: duration_ms,
+          error_message: error_message,
+          resource_type: resource_type,
+          resource_id: resource_id
+        }
+
+        # Tag with the current location when the column exists
+        if config&.location_id.present? && Models::ApiRequest.column_names.include?("skytab_location_id")
+          attrs[:skytab_location_id] = config.location_id
+        end
+
+        Models::ApiRequest.create!(attrs)
+      rescue StandardError => e
+        logger.debug "Audit logging failed: #{e.message}"
+      end
+
+      # Execute a block with API error fallback
+      def with_api_fallback(fallback: nil, log_level: :debug, reraise_on: [])
+        yield
+      rescue ApiError => e
+        raise if reraise_on.any? { |code| e.message.include?("HTTP #{code}") }
+
+        logger.send(log_level, "API error (using fallback): #{e.message}")
+        fallback
+      rescue StandardError => e
+        logger.send(log_level, "Error (using fallback): #{e.message}")
+        fallback
+      end
+
+      # Execute a block, handling sandbox limitations (405 errors)
+      def with_sandbox_fallback(simulated_response: nil)
+        yield
+      rescue ApiError => e
+        if e.message.include?("405")
+          logger.warn "Operation not supported in sandbox environment"
+          simulated_response
+        else
+          raise
+        end
+      end
+
+      # Safe getter for nested hash values with logging
+      def safe_dig(hash, *keys, default: nil)
+        return default if hash.nil?
+
+        hash.dig(*keys) || default
+      rescue StandardError
+        default
+      end
+    end
+  end
+end

data/lib/skytab_sandbox_simulator/services/skytab/catalog_service.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module SkytabSandboxSimulator
+  module Services
+    module Skytab
+      # Manages SkyTab catalog: categories, items, taxes, modifier sets.
+      # GET /pos/v2/{locationId}/menu
+      class CatalogService < BaseService
+        # Fetch the full menu for the current location
+        #
+        # @return [Hash] Menu data with categories, items, taxes, modifierSets
+        def get_menu
+          logger.info "Fetching menu..."
+          response = request(:get, pos_endpoint("menu"),
+                             resource_type: "Menu")
+          logger.info "Menu fetched successfully"
+          response || {}
+        end
+
+        # Fetch all categories from the menu
+        #
+        # @return [Array<Hash>] Array of category objects
+        def get_categories
+          logger.info "Fetching categories..."
+          menu = get_menu
+          categories = menu["categories"] || []
+          logger.info "Found #{categories.size} categories"
+          categories
+        end
+
+        # Fetch all items from the menu
+        #
+        # @return [Array<Hash>] Array of item objects
+        def get_items
+          logger.info "Fetching items..."
+          menu = get_menu
+          items = menu["items"] || []
+          logger.info "Found #{items.size} items"
+          items
+        end
+
+        # Fetch all tax rates from the menu
+        #
+        # @return [Array<Hash>] Array of tax rate objects
+        def get_taxes
+          logger.info "Fetching taxes..."
+          menu = get_menu
+          taxes = menu["taxes"] || []
+          logger.info "Found #{taxes.size} tax rates"
+          taxes
+        end
+
+        # Fetch all modifier sets from the menu
+        #
+        # @return [Array<Hash>] Array of modifier set objects
+        def get_modifier_sets
+          logger.info "Fetching modifier sets..."
+          menu = get_menu
+          modifier_sets = menu["modifierSets"] || []
+          logger.info "Found #{modifier_sets.size} modifier sets"
+          modifier_sets
+        end
+
+        # Create a category via POS API
+        #
+        # @param name [String] Category name
+        # @param sort_order [Integer, nil] Display sort order
+        # @return [Hash, nil] Created category
+        def create_category(name:, sort_order: nil)
+          logger.info "Creating category: #{name}"
+          payload = { "name" => name }
+          payload["sortOrder"] = sort_order if sort_order
+          request(:post, pos_endpoint("categories"), payload: payload,
+                  resource_type: "Category")
+        end
+
+        # Create an item via POS API
+        #
+        # @param name [String] Item name
+        # @param price [Integer] Price in cents
+        # @param category_id [String, nil] Category to associate with
+        # @param sku [String, nil] SKU identifier
+        # @return [Hash, nil] Created item
+        def create_item(name:, price:, category_id: nil, sku: nil)
+          logger.info "Creating item: #{name} ($#{price / 100.0})"
+
+          payload = {
+            "name" => name,
+            "price" => price
+          }
+          payload["categoryId"] = category_id if category_id
+          payload["sku"] = sku if sku
+
+          request(:post, pos_endpoint("items"), payload: payload,
+                  resource_type: "Item")
+        end
+
+        # Delete a category
+        #
+        # @param category_id [String] Category ID to delete
+        # @return [Hash, nil] Response
+        def delete_category(category_id)
+          logger.info "Deleting category: #{category_id}"
+          request(:delete, pos_endpoint("categories/#{category_id}"),
+                  resource_type: "Category", resource_id: category_id)
+        end
+
+        # Delete an item
+        #
+        # @param item_id [String] Item ID to delete
+        # @return [Hash, nil] Response
+        def delete_item(item_id)
+          logger.info "Deleting item: #{item_id}"
+          request(:delete, pos_endpoint("items/#{item_id}"),
+                  resource_type: "Item", resource_id: item_id)
+        end
+
+        # Delete all categories and items
+        def delete_all
+          logger.warn "Deleting all catalog data..."
+
+          get_items.each { |item| delete_item(item["id"]) }
+          get_categories.each { |cat| delete_category(cat["id"]) }
+
+          logger.info "All catalog data deleted"
+        end
+      end
+    end
+  end
+end

data/lib/skytab_sandbox_simulator/services/skytab/location_service.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module SkytabSandboxSimulator
+  module Services
+    module Skytab
+      # Manages SkyTab location information via Shift4 Marketplace API.
+      # GET /marketplace/v2/locations
+      class LocationService < BaseService
+        # Fetch all locations for the authenticated merchant
+        #
+        # @return [Array<Hash>] Array of location objects
+        def get_locations
+          logger.info "Fetching locations..."
+          response = request(:get, marketplace_endpoint("locations"),
+                             resource_type: "Location")
+          locations = extract_locations(response)
+          logger.info "Found #{locations.size} locations"
+          locations
+        end
+
+        # Fetch a single location by ID
+        #
+        # @param location_id [String] Location ID
+        # @return [Hash, nil] Location data
+        def get_location(location_id)
+          logger.info "Fetching location: #{location_id}"
+          locations = get_locations
+          locations.find { |loc| loc["id"].to_s == location_id.to_s }
+        end
+
+        # Fetch the current configured location
+        #
+        # @return [Hash, nil] Location data
+        def get_current_location
+          get_location(config.location_id)
+        end
+
+        private
+
+        def extract_locations(response)
+          return [] if response.nil?
+
+          if response.is_a?(Array)
+            response
+          elsif response.is_a?(Hash)
+            response["locations"] || response["elements"] || [response]
+          else
+            []
+          end
+        end
+      end
+    end
+  end
+end