epos_now_sandbox_simulator 0.1.0

data/lib/epos_now_sandbox_simulator/services/base_service.rb

@@ -0,0 +1,248 @@
+# frozen_string_literal: true
+
+require "base64"
+
+module EposNowSandboxSimulator
+  module Services
+    # Base service for all Epos Now API interactions.
+    #
+    # Epos Now uses Basic Authentication: Base64(api_key:api_secret)
+    # API Base: https://api.eposnowhq.com/api/v4/
+    # Pagination: page-based, 200 items per page
+    #
+    # V4 differences from V2:
+    #   - Field names: Id instead of CategoryID/ProductID/etc.
+    #   - Batch operations: POST/PUT/DELETE accept arrays
+    #   - DELETE uses request body [{Id: int}]
+    #   - Transaction: ServiceType instead of EatOut, GetByDate endpoint
+    #   - TenderType: ClassificationId, IsTipAdjustable fields
+    class BaseService
+      attr_reader :config, :logger
+
+      # Epos Now API V4 path prefix
+      API_PREFIX = "api/v4"
+
+      def initialize(config: nil)
+        @config = config || EposNowSandboxSimulator.configuration
+        @config.validate!
+        @logger = @config.logger
+      end
+
+      protected
+
+      # Make HTTP request to Epos Now API
+      #
+      # @param method [Symbol] HTTP method (:get, :post, :put, :delete)
+      # @param path [String] API endpoint path (e.g. "Category")
+      # @param payload [Hash, nil] Request body for POST/PUT
+      # @param params [Hash, nil] Query parameters
+      # @param resource_type [String, nil] Logical resource (e.g. "Category")
+      # @param resource_id [String, nil] Resource ID
+      # @return [Hash, Array, 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
+
+        audit_api_request(
+          http_method: method.to_s.upcase,
+          url: url,
+          request_payload: payload,
+          response_status: e.http_code,
+          response_payload: begin
+            JSON.parse(e.response.body)
+          rescue StandardError
+            nil
+          end,
+          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
+
+        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 endpoint path for Epos Now V4 API
+      #
+      # @param resource [String] Resource name (e.g. "Category", "Transaction")
+      # @return [String] Full endpoint path
+      def endpoint(resource)
+        "#{API_PREFIX}/#{resource}"
+      end
+
+      # Fetch all pages of a paginated resource
+      #
+      # Epos Now returns up to 200 items per page.
+      # Returns empty array when page returns no results.
+      #
+      # @param resource [String] Resource name
+      # @param params [Hash] Additional query parameters
+      # @return [Array<Hash>] All records across all pages
+      def fetch_all_pages(resource, params: {})
+        all_records = []
+        page = 1
+
+        loop do
+          page_params = params.merge(page: page)
+          results = request(:get, endpoint(resource), params: page_params, resource_type: resource)
+
+          # Epos Now returns array directly or nil/empty for last page
+          records = results.is_a?(Array) ? results : []
+          break if records.empty?
+
+          all_records.concat(records)
+
+          # If we got fewer than 200, this is the last page
+          break if records.size < 200
+
+          page += 1
+        end
+
+        all_records
+      end
+
+      private
+
+      def headers
+        {
+          "Authorization" => "Basic #{config.auth_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
+          # V4 DELETE uses request body [{Id: int}]
+          if payload
+            RestClient::Request.execute(method: :delete, url: url, payload: payload.to_json, headers: headers)
+          else
+            RestClient.delete(url, headers)
+          end
+        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?
+
+        Models::ApiRequest.create!(
+          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
+        )
+      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)
+        yield
+      rescue ApiError => e
+        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
+
+      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/epos_now_sandbox_simulator/services/epos_now/inventory_service.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+module EposNowSandboxSimulator
+  module Services
+    module EposNow
+      # Manages categories and products in Epos Now via V4 API.
+      #
+      # V4 endpoints:
+      #   GET/POST/PUT/DELETE /api/v4/Category
+      #   GET/POST/PUT/DELETE /api/v4/Product
+      #
+      # V4 key changes from V2:
+      #   - Id instead of CategoryID/ProductID
+      #   - POST/PUT/DELETE accept arrays (batch operations)
+      #   - Product: IsSalePriceIncTax, IsEatOutPriceIncTax, IsArchived, ColourId
+      #   - Category: ImageUrl, Children (nested), RootParentId
+      class InventoryService < BaseService
+        # ==========================================
+        # CATEGORIES
+        # ==========================================
+
+        # Fetch all categories (paginated, 200 per page)
+        # @return [Array<Hash>] All categories
+        def fetch_categories
+          logger.info "Fetching all categories..."
+          categories = fetch_all_pages("Category")
+          logger.info "Fetched #{categories.size} categories"
+          categories
+        end
+
+        # Create a category
+        # @param name [String] Category name
+        # @param description [String, nil] Description
+        # @param show_on_till [Boolean] Show on till (default true)
+        # @param sort_position [Integer, nil] Sort order
+        # @param parent_id [Integer, nil] Parent category ID
+        # @param nominal_code [String, nil] Accounting software identifier
+        # @return [Hash] Created category
+        def create_category(name:, description: nil, show_on_till: true, sort_position: nil, parent_id: nil, nominal_code: nil)
+          payload = {
+            "Name" => name,
+            "ShowOnTill" => show_on_till,
+            "IsWet" => false
+          }
+          payload["Description"] = description if description
+          payload["SortPosition"] = sort_position if sort_position
+          payload["ParentId"] = parent_id if parent_id
+          payload["NominalCode"] = nominal_code if nominal_code
+
+          logger.info "Creating category: #{name}"
+          result = request(:post, endpoint("Category"), payload: payload, resource_type: "Category")
+          logger.info "Created category: #{result["Name"]} (ID: #{result["Id"]})"
+          result
+        end
+
+        # Find category by name
+        # @param name [String] Category name to search
+        # @return [Hash, nil] Category or nil
+        def find_category_by_name(name)
+          # V4: use search parameter
+          results = request(:get, endpoint("Category"), params: { "Name" => name }, resource_type: "Category")
+          return nil unless results.is_a?(Array)
+
+          results.find { |c| c["Name"]&.downcase == name.downcase }
+        end
+
+        # Create category idempotently (find or create)
+        # @return [Hash] Existing or new category
+        def find_or_create_category(name:, description: nil, show_on_till: true, sort_position: nil, parent_id: nil, nominal_code: nil)
+          existing = find_category_by_name(name)
+          return existing if existing
+
+          create_category(
+            name: name,
+            description: description,
+            show_on_till: show_on_till,
+            sort_position: sort_position,
+            parent_id: parent_id,
+            nominal_code: nominal_code
+          )
+        end
+
+        # Delete a category (V4: uses request body)
+        # @param id [Integer] Category ID
+        def delete_category(id)
+          request(:delete, endpoint("Category"), payload: [{ "Id" => id }], resource_type: "Category", resource_id: id.to_s)
+        end
+
+        # ==========================================
+        # PRODUCTS (Items)
+        # ==========================================
+
+        # Fetch all products (paginated, 200 per page)
+        # @return [Array<Hash>] All products
+        def fetch_products
+          logger.info "Fetching all products..."
+          products = fetch_all_pages("Product")
+          logger.info "Fetched #{products.size} products"
+          products
+        end
+
+        # Get a single product by ID
+        # @param id [Integer] Product ID
+        # @return [Hash] Product
+        def get_product(id)
+          request(:get, endpoint("Product/#{id}"), resource_type: "Product", resource_id: id.to_s)
+        end
+
+        # Create a product
+        # @param name [String] Product name
+        # @param sale_price [Float] Sale price
+        # @param cost_price [Float] Cost price
+        # @param eat_out_price [Float, nil] Takeaway price (defaults to sale_price)
+        # @param category_id [Integer, nil] Category ID
+        # @param barcode [String, nil] Barcode
+        # @param sku [String, nil] SKU
+        # @param description [String, nil] Description
+        # @param sell_on_till [Boolean] Show on till
+        # @return [Hash] Created product
+        def create_product(name:, sale_price:, cost_price: 0.0, eat_out_price: nil, category_id: nil,
+                           barcode: nil, sku: nil, description: nil, sell_on_till: true)
+          payload = {
+            "Name" => name,
+            "SalePrice" => sale_price,
+            "CostPrice" => cost_price,
+            "EatOutPrice" => eat_out_price || sale_price,
+            "SellOnTill" => sell_on_till,
+            "SellOnWeb" => false,
+            "ProductType" => 0 # Standard
+          }
+          payload["CategoryId"] = category_id if category_id
+          payload["Barcode"] = barcode if barcode
+          payload["Sku"] = sku if sku
+          payload["Description"] = description if description
+
+          logger.info "Creating product: #{name} ($#{sale_price})"
+          result = request(:post, endpoint("Product"), payload: payload, resource_type: "Product")
+          logger.info "Created product: #{result["Name"]} (ID: #{result["Id"]})"
+          result
+        end
+
+        # Find product by name
+        # @param name [String] Product name
+        # @return [Hash, nil] Product or nil
+        def find_product_by_name(name)
+          results = request(:get, endpoint("Product"), params: { "Name" => name }, resource_type: "Product")
+          return nil unless results.is_a?(Array)
+
+          results.find { |p| p["Name"]&.downcase == name.downcase }
+        end
+
+        # Create product idempotently
+        def find_or_create_product(name:, sale_price:, cost_price: 0.0, eat_out_price: nil,
+                                   category_id: nil, barcode: nil, sku: nil, description: nil)
+          existing = find_product_by_name(name)
+          return existing if existing
+
+          create_product(
+            name: name,
+            sale_price: sale_price,
+            cost_price: cost_price,
+            eat_out_price: eat_out_price,
+            category_id: category_id,
+            barcode: barcode,
+            sku: sku,
+            description: description
+          )
+        end
+
+        # Delete a product (V4: uses request body)
+        # @param id [Integer] Product ID
+        def delete_product(id)
+          request(:delete, endpoint("Product"), payload: [{ "Id" => id }], resource_type: "Product", resource_id: id.to_s)
+        end
+      end
+    end
+  end
+end

data/lib/epos_now_sandbox_simulator/services/epos_now/services_manager.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require "concurrent"
+
+module EposNowSandboxSimulator
+  module Services
+    module EposNow
+      # Thread-safe, lazy-loaded service manager for all Epos Now services.
+      #
+      # @example
+      #   services = ServicesManager.new
+      #   services.inventory.create_category(name: "Drinks")
+      #   services.transaction.create_transaction(eat_out: 0)
+      class ServicesManager
+        def initialize(config: nil)
+          @config = config || EposNowSandboxSimulator.configuration
+          @mutex = Mutex.new
+        end
+
+        def inventory
+          thread_safe_memoize(:@inventory) { InventoryService.new(config: @config) }
+        end
+
+        def tender
+          thread_safe_memoize(:@tender) { TenderService.new(config: @config) }
+        end
+
+        def transaction
+          thread_safe_memoize(:@transaction) { TransactionService.new(config: @config) }
+        end
+
+        def tax
+          thread_safe_memoize(:@tax) { TaxService.new(config: @config) }
+        end
+
+        private
+
+        def thread_safe_memoize(ivar_name)
+          value = instance_variable_get(ivar_name)
+          return value if value
+
+          @mutex.synchronize do
+            # :nocov:
+            value = instance_variable_get(ivar_name)
+            return value if value
+            # :nocov:
+
+            value = yield
+            instance_variable_set(ivar_name, value)
+            value
+          end
+        end
+      end
+    end
+  end
+end

data/lib/epos_now_sandbox_simulator/services/epos_now/tax_service.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module EposNowSandboxSimulator
+  module Services
+    module EposNow
+      # Manages tax groups in Epos Now via V4 API.
+      #
+      # V4 endpoints:
+      #   GET/POST/PUT/DELETE /api/v4/TaxGroup
+      #   GET /api/v4/TaxGroup/{id}
+      #
+      # V4 TaxGroup model:
+      #   Id, Name, TaxRates[] (array of TaxGroupRate)
+      #
+      # TaxGroupRate:
+      #   TaxGroupId, TaxRateId, LocationId, Priority, Percentage, Name, Description, TaxCode
+      class TaxService < BaseService
+        # Fetch all tax groups
+        # @return [Array<Hash>] All tax groups
+        def fetch_tax_groups
+          logger.info "Fetching tax groups..."
+          groups = fetch_all_pages("TaxGroup")
+          logger.info "Fetched #{groups.size} tax groups"
+          groups
+        end
+
+        # Get a single tax group by ID
+        # @param id [Integer] Tax group ID
+        # @return [Hash] Tax group with nested TaxRates
+        def get_tax_group(id)
+          request(:get, endpoint("TaxGroup/#{id}"), resource_type: "TaxGroup", resource_id: id.to_s)
+        end
+
+        # Calculate tax for a given amount using the configured rate
+        # @param amount [Float] Pre-tax amount
+        # @param rate [Float, nil] Tax rate percentage (uses config default)
+        # @return [Float] Tax amount
+        def calculate_tax(amount, rate: nil)
+          tax_rate = rate || config.tax_rate
+          (amount * tax_rate / 100.0).round(2)
+        end
+      end
+    end
+  end
+end

data/lib/epos_now_sandbox_simulator/services/epos_now/tender_service.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module EposNowSandboxSimulator
+  module Services
+    module EposNow
+      # Manages tender types (payment methods) in Epos Now via V4 API.
+      #
+      # V4 endpoints:
+      #   GET/POST /api/v4/TenderType
+      #   GET /api/v4/TenderType/{id}
+      #
+      # V4 TenderType fields:
+      #   Id, Name, Description, IsIntegrationTenderType,
+      #   TillOrder, ClassificationId, IsTipAdjustable, IsWaiterBanked
+      #
+      # V4 ClassificationId values:
+      #   Cash, Card, Integrated, Other
+      #
+      # Note: In V4, individual Tenders (payments) are embedded in
+      # Transaction creation — not a separate CRUD endpoint.
+      class TenderService < BaseService
+        # Default tender types for a typical POS setup
+        DEFAULT_TENDER_TYPES = [
+          { name: "Cash", description: "Cash payment" },
+          { name: "Credit Card", description: "Credit card payment" },
+          { name: "Debit Card", description: "Debit card payment" },
+          { name: "Gift Card", description: "Gift card payment" },
+          { name: "Check", description: "Check payment" }
+        ].freeze
+
+        # Fetch all tender types
+        # @return [Array<Hash>] All tender types
+        def fetch_tender_types
+          logger.info "Fetching all tender types..."
+          types = fetch_all_pages("TenderType")
+          logger.info "Fetched #{types.size} tender types"
+          types
+        end
+
+        # Get a single tender type by ID
+        # @param id [Integer] Tender type ID
+        # @return [Hash] Tender type
+        def get_tender_type(id)
+          request(:get, endpoint("TenderType/#{id}"), resource_type: "TenderType", resource_id: id.to_s)
+        end
+
+        # Create a tender type
+        # @param name [String] Tender type name
+        # @param description [String, nil] Description
+        # @return [Hash] Created tender type
+        def create_tender_type(name:, description: nil)
+          payload = {
+            "Name" => name
+          }
+          payload["Description"] = description if description
+
+          logger.info "Creating tender type: #{name}"
+          result = request(:post, endpoint("TenderType"), payload: payload, resource_type: "TenderType")
+          logger.info "Created tender type: #{result["Name"]} (ID: #{result["Id"]})"
+          result
+        end
+
+        # Find tender type by name
+        # @param name [String] Tender type name
+        # @return [Hash, nil] Tender type or nil
+        def find_tender_type_by_name(name)
+          types = fetch_tender_types
+          types.find { |t| t["Name"]&.downcase == name.downcase }
+        end
+
+        # Create tender type idempotently
+        def find_or_create_tender_type(name:, description: nil)
+          existing = find_tender_type_by_name(name)
+          return existing if existing
+
+          create_tender_type(name: name, description: description)
+        end
+
+        # Ensure default tender types exist
+        # @return [Array<Hash>] All tender types (existing + created)
+        def setup_default_tender_types
+          logger.info "Setting up default tender types..."
+          DEFAULT_TENDER_TYPES.map do |tt|
+            find_or_create_tender_type(name: tt[:name], description: tt[:description])
+          end
+        end
+      end
+    end
+  end
+end