square_sandbox_simulator 0.1.0

data/lib/square_sandbox_simulator/services/base_service.rb

@@ -0,0 +1,253 @@
+# frozen_string_literal: true
+
+module SquareSandboxSimulator
+  module Services
+    # Base service for all Square API interactions
+    # Provides HTTP client, logging, idempotency, and error handling
+    class BaseService
+      attr_reader :config, :logger
+
+      def initialize(config: nil)
+        @config = config || SquareSandboxSimulator.configuration
+        @config.validate!
+        @logger = @config.logger
+      end
+
+      protected
+
+      # Make HTTP request to Square 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 -- audit logging is a no-op.
+      #
+      # @param method [Symbol] HTTP method (:get, :post, :put, :delete)
+      # @param path [String] API endpoint path (e.g. "catalog/list")
+      # @param payload [Hash, nil] Request body for POST/PUT
+      # @param params [Hash, nil] Query parameters
+      # @param resource_type [String, nil] Logical resource (e.g. "CatalogObject")
+      # @param resource_id [String, nil] Square 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)
+
+        # Inject idempotency key for POST requests
+        payload = inject_idempotency_key(payload) if method == :post && payload.is_a?(Hash)
+
+        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: 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 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 endpoint path for Square v2 API
+      #
+      # @param path [String] Relative path (e.g. "catalog/list")
+      # @return [String] Full endpoint path (e.g. "v2/catalog/list")
+      def endpoint(path)
+        "v2/#{path}"
+      end
+
+      private
+
+      def headers
+        {
+          "Authorization" => "Bearer #{config.access_token}",
+          "Content-Type" => "application/json",
+          "Accept" => "application/json",
+          "Square-Version" => config.square_version,
+        }
+      end
+
+      def build_url(path, params = nil)
+        base = path.start_with?("http") ? path : "#{config.environment}v2/#{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
+
+      # Inject idempotency_key into POST payloads if not already present
+      def inject_idempotency_key(payload)
+        return payload unless payload.is_a?(Hash)
+        return payload if payload.key?("idempotency_key")
+
+        payload.merge("idempotency_key" => SecureRandom.uuid)
+      end
+
+      def handle_api_error(error)
+        body = begin
+          JSON.parse(error.response.body)
+        rescue StandardError
+          { "errors" => [{ "detail" => error.response.body }] }
+        end
+
+        errors = body["errors"] || []
+        detail = errors.map { |e| e["detail"] }.compact.join("; ")
+        detail = error.response.body if detail.empty?
+
+        logger.error "API Error (#{error.http_code}): #{body}"
+        raise ApiError, "HTTP #{error.http_code}: #{detail}"
+      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?("square_location_id")
+          attrs[:square_location_id] = config.location_id
+        end
+
+        Models::ApiRequest.create!(attrs)
+      rescue StandardError => e
+        logger.debug "Audit logging failed: #{e.message}"
+      end
+
+      # ============================================
+      # STANDARDIZED ERROR HANDLING HELPERS
+      # ============================================
+
+      # Execute a block with API error fallback
+      # @param fallback [Object] Value to return on error
+      # @param log_level [Symbol] Log level for error (:debug, :warn, :error)
+      # @param reraise_on [Array<Integer>] HTTP codes to reraise instead of fallback
+      # @yield Block to execute
+      # @return [Object] Block result or fallback
+      def with_api_fallback(fallback: nil, log_level: :debug, reraise_on: [])
+        yield
+      rescue ApiError => e
+        # Reraise if it's a critical error code
+        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)
+      # @param simulated_response [Object] Response to return if sandbox doesn't support the operation
+      # @yield Block to execute
+      # @return [Object] Block result or simulated response
+      def with_sandbox_fallback(simulated_response: nil)
+        yield
+      rescue ApiError => e
+        raise unless e.message.include?("405")
+
+        logger.warn "Operation not supported in sandbox environment"
+        simulated_response
+      end
+
+      # Safe getter for nested hash values with logging
+      # @param hash [Hash] The hash to extract from
+      # @param keys [Array] Keys to dig into
+      # @param default [Object] Default value if not found
+      # @return [Object] The value or default
+      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/square_sandbox_simulator/services/square/catalog_service.rb

@@ -0,0 +1,203 @@
+# frozen_string_literal: true
+
+module SquareSandboxSimulator
+  module Services
+    module Square
+      # Manages Square Catalog: categories, items, discounts, taxes
+      class CatalogService < BaseService
+        # Upsert a category
+        # @param name [String] Category name
+        # @return [Hash] Catalog object response
+        def upsert_category(name:)
+          logger.info "Upserting category: #{name}"
+
+          payload = {
+            "object" => {
+              "type" => "CATEGORY",
+              "id" => "##{name.downcase.gsub(/\s+/, "_")}",
+              "category_data" => {
+                "name" => name,
+              },
+            },
+          }
+
+          request(:post, "catalog/object",
+                  payload: payload,
+                  resource_type: "CatalogObject")
+        end
+
+        # Upsert an item with a variation
+        # @param name [String] Item name
+        # @param price_cents [Integer] Price in cents
+        # @param category_id [String, nil] Category ID to associate
+        # @return [Hash] Catalog object response
+        def upsert_item(name:, price_cents:, category_id: nil)
+          logger.info "Upserting item: #{name} ($#{price_cents / 100.0})"
+
+          item_id = "##{name.downcase.gsub(/\s+/, "_")}"
+          variation_id = "#{item_id}_variation"
+
+          item_data = {
+            "name" => name,
+            "variations" => [
+              {
+                "type" => "ITEM_VARIATION",
+                "id" => variation_id,
+                "item_variation_data" => {
+                  "name" => "Regular",
+                  "pricing_type" => "FIXED_PRICING",
+                  "price_money" => {
+                    "amount" => price_cents,
+                    "currency" => "USD",
+                  },
+                },
+              },
+            ],
+          }
+
+          item_data["category_id"] = category_id if category_id
+
+          payload = {
+            "object" => {
+              "type" => "ITEM",
+              "id" => item_id,
+              "item_data" => item_data,
+            },
+          }
+
+          request(:post, "catalog/object",
+                  payload: payload,
+                  resource_type: "CatalogObject")
+        end
+
+        # Upsert a discount
+        # @param name [String] Discount name
+        # @param percentage [String, nil] Percentage (e.g. "10.0")
+        # @param amount_cents [Integer, nil] Fixed amount in cents
+        # @return [Hash] Catalog object response
+        def upsert_discount(name:, percentage: nil, amount_cents: nil)
+          logger.info "Upserting discount: #{name}"
+
+          discount_data = { "name" => name }
+
+          if percentage
+            discount_data["discount_type"] = "FIXED_PERCENTAGE"
+            discount_data["percentage"] = percentage.to_s
+          elsif amount_cents
+            discount_data["discount_type"] = "FIXED_AMOUNT"
+            discount_data["amount_money"] = {
+              "amount" => amount_cents,
+              "currency" => "USD",
+            }
+          else
+            raise ArgumentError, "Must provide either percentage or amount_cents"
+          end
+
+          payload = {
+            "object" => {
+              "type" => "DISCOUNT",
+              "id" => "#discount_#{name.downcase.gsub(/\s+/, "_")}",
+              "discount_data" => discount_data,
+            },
+          }
+
+          request(:post, "catalog/object",
+                  payload: payload,
+                  resource_type: "CatalogObject")
+        end
+
+        # Upsert a tax
+        # @param name [String] Tax name
+        # @param percentage [String] Tax percentage (e.g. "8.25")
+        # @return [Hash] Catalog object response
+        def upsert_tax(name:, percentage:)
+          logger.info "Upserting tax: #{name} (#{percentage}%)"
+
+          payload = {
+            "object" => {
+              "type" => "TAX",
+              "id" => "#tax_#{name.downcase.gsub(/\s+/, "_")}",
+              "tax_data" => {
+                "name" => name,
+                "calculation_phase" => "TAX_SUBTOTAL_PHASE",
+                "inclusion_type" => "ADDITIVE",
+                "percentage" => percentage.to_s,
+              },
+            },
+          }
+
+          request(:post, "catalog/object",
+                  payload: payload,
+                  resource_type: "CatalogObject")
+        end
+
+        # List catalog objects
+        # @param types [String, nil] Comma-separated types (e.g. "ITEM,CATEGORY")
+        # @return [Array<Hash>] Array of catalog objects
+        def list_catalog(types: nil)
+          logger.info "Listing catalog#{" (types: #{types})" if types}..."
+
+          params = {}
+          params[:types] = types if types
+
+          response = request(:get, "catalog/list", params: params)
+          objects = response&.dig("objects") || []
+          logger.info "Found #{objects.size} catalog objects"
+          objects
+        end
+
+        # Get a single catalog object
+        # @param object_id [String] Catalog object ID
+        # @return [Hash, nil] Catalog object
+        def get_object(object_id)
+          logger.info "Fetching catalog object: #{object_id}"
+          response = request(:get, "catalog/object/#{object_id}")
+          response&.dig("object")
+        end
+
+        # Delete a catalog object
+        # @param object_id [String] Catalog object ID
+        # @return [Hash, nil] Deleted object IDs
+        def delete_object(object_id)
+          logger.info "Deleting catalog object: #{object_id}"
+          request(:delete, "catalog/object/#{object_id}",
+                  resource_type: "CatalogObject",
+                  resource_id: object_id)
+        end
+
+        # Batch upsert catalog objects
+        # @param objects [Array<Hash>] Array of catalog object batches
+        # @return [Hash] Batch upsert response
+        def batch_upsert(objects:)
+          logger.info "Batch upserting #{objects.size} objects..."
+
+          payload = {
+            "batches" => [
+              {
+                "objects" => objects,
+              },
+            ],
+          }
+
+          request(:post, "catalog/batch-upsert",
+                  payload: payload,
+                  resource_type: "CatalogObject")
+        end
+
+        # Delete all catalog objects
+        def delete_all
+          logger.warn "Deleting all catalog objects..."
+
+          all_objects = list_catalog
+          all_objects.each do |obj|
+            with_api_fallback(fallback: nil) do
+              delete_object(obj["id"])
+            end
+          end
+
+          logger.info "All catalog objects deleted"
+        end
+      end
+    end
+  end
+end

data/lib/square_sandbox_simulator/services/square/customer_service.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+require "faker"
+
+module SquareSandboxSimulator
+  module Services
+    module Square
+      # Manages Square customers
+      class CustomerService < BaseService
+        # Create a customer
+        # @param given_name [String] First name
+        # @param family_name [String] Last name
+        # @param email [String, nil] Email address
+        # @param phone [String, nil] Phone number
+        # @return [Hash, nil] Customer response
+        def create_customer(given_name:, family_name:, email: nil, phone: nil)
+          logger.info "Creating customer: #{given_name} #{family_name}"
+
+          payload = {
+            "given_name" => given_name,
+            "family_name" => family_name,
+          }
+          payload["email_address"] = email if email
+          payload["phone_number"] = phone if phone
+
+          response = request(:post, "customers",
+                             payload: payload,
+                             resource_type: "Customer")
+
+          customer = response&.dig("customer")
+          logger.info "Customer created: #{customer["id"]}" if customer
+          customer
+        end
+
+        # List all customers
+        # @return [Array<Hash>] Array of customers
+        def list_customers
+          logger.info "Listing customers..."
+          response = request(:get, "customers")
+          customers = response&.dig("customers") || []
+          logger.info "Found #{customers.size} customers"
+          customers
+        end
+
+        # Get a single customer
+        # @param customer_id [String] The customer ID
+        # @return [Hash, nil] Customer response
+        def get_customer(customer_id)
+          logger.info "Fetching customer: #{customer_id}"
+          response = request(:get, "customers/#{customer_id}",
+                             resource_type: "Customer",
+                             resource_id: customer_id)
+          response&.dig("customer")
+        end
+
+        # Default customer data for deterministic setup
+        DEFAULT_CUSTOMERS = [
+          { given: "John", family: "Smith", phone: "+15551000001" },
+          { given: "Jane", family: "Doe", phone: "+15551000002" },
+          { given: "Bob", family: "Johnson", phone: "+15551000003" },
+          { given: "Alice", family: "Williams", phone: "+15551000004" },
+          { given: "Charlie", family: "Brown", phone: "+15551000005" },
+          { given: "Diana", family: "Davis", phone: "+15551000006" },
+          { given: "Eve", family: "Miller", phone: "+15551000007" },
+          { given: "Frank", family: "Wilson", phone: "+15551000008" },
+          { given: "Grace", family: "Moore", phone: "+15551000009" },
+          { given: "Henry", family: "Taylor", phone: "+15551000010" },
+          { given: "Ivy", family: "Anderson", phone: "+15551000011" },
+          { given: "Jack", family: "Thomas", phone: "+15551000012" },
+          { given: "Karen", family: "Jackson", phone: "+15551000013" },
+          { given: "Leo", family: "White", phone: "+15551000014" },
+          { given: "Maria", family: "Harris", phone: "+15551000015" },
+          { given: "Nate", family: "Martin", phone: "+15551000016" },
+          { given: "Olivia", family: "Garcia", phone: "+15551000017" },
+          { given: "Paul", family: "Martinez", phone: "+15551000018" },
+          { given: "Quinn", family: "Robinson", phone: "+15551000019" },
+          { given: "Rachel", family: "Clark", phone: "+15551000020" },
+        ].freeze
+
+        # Create sample customers if needed (idempotent)
+        # @param count [Integer] Minimum number of customers to ensure exist
+        # @return [Array<Hash>] All customers
+        def ensure_customers(count: 20)
+          existing = list_customers
+          return existing if existing.size >= count
+
+          needed = count - existing.size
+          logger.info "Creating #{needed} sample customers..."
+
+          new_customers = []
+          needed.times do |i|
+            idx = existing.size + i
+            if idx < DEFAULT_CUSTOMERS.size
+              cust_data = DEFAULT_CUSTOMERS[idx]
+              given = cust_data[:given]
+              family = cust_data[:family]
+              phone = cust_data[:phone]
+            else
+              given = Faker::Name.first_name
+              family = Faker::Name.last_name
+              phone = Faker::PhoneNumber.cell_phone
+            end
+
+            safe_given = given.downcase.gsub(/[^a-z0-9]/, "")
+            safe_family = family.downcase.gsub(/[^a-z0-9]/, "")
+
+            customer = create_customer(
+              given_name: given,
+              family_name: family,
+              email: "#{safe_given}.#{safe_family}@example.com",
+              phone: phone,
+            )
+            new_customers << customer if customer
+          end
+
+          existing + new_customers
+        end
+
+        # Delete a customer
+        # @param customer_id [String] The customer ID
+        def delete_customer(customer_id)
+          logger.info "Deleting customer: #{customer_id}"
+          request(:delete, "customers/#{customer_id}",
+                  resource_type: "Customer",
+                  resource_id: customer_id)
+        end
+      end
+    end
+  end
+end