square_sandbox_simulator 0.1.0

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

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module SquareSandboxSimulator
+  module Services
+    module Square
+      # Manages Square orders
+      class OrderService < BaseService
+        # Create an order
+        # @param line_items [Array<Hash>] Array of line item hashes
+        # @param discounts [Array<Hash>] Array of discount hashes
+        # @param taxes [Array<Hash>] Array of tax hashes
+        # @param customer_id [String, nil] Customer ID to associate
+        # @return [Hash, nil] Order response
+        def create_order(line_items:, discounts: [], taxes: [], customer_id: nil)
+          logger.info "Creating order with #{line_items.size} line items..."
+
+          order_data = {
+            "location_id" => config.location_id,
+            "line_items" => line_items,
+          }
+
+          order_data["discounts"] = discounts if discounts.any?
+          order_data["taxes"] = taxes if taxes.any?
+          order_data["customer_id"] = customer_id if customer_id
+
+          payload = { "order" => order_data }
+
+          response = request(:post, "orders",
+                             payload: payload,
+                             resource_type: "Order")
+
+          order = response&.dig("order")
+          logger.info "Order created: #{order["id"]}" if order
+          order
+        end
+
+        # Get a single order (Square uses batch-retrieve for single orders)
+        # @param order_id [String] The order ID
+        # @return [Hash, nil] Order response
+        def get_order(order_id)
+          logger.info "Fetching order: #{order_id}"
+
+          payload = {
+            "order_ids" => [order_id],
+          }
+
+          response = request(:post, "orders/batch-retrieve",
+                             payload: payload,
+                             resource_type: "Order",
+                             resource_id: order_id)
+
+          orders = response&.dig("orders") || []
+          orders.first
+        end
+
+        # Search orders with filters
+        # @param filters [Hash] Search filters
+        # @return [Array<Hash>] Matching orders
+        def search_orders(filters: {})
+          logger.info "Searching orders..."
+
+          payload = {
+            "location_ids" => [config.location_id],
+          }
+          payload["query"] = { "filter" => filters } if filters.any?
+
+          response = request(:post, "orders/search",
+                             payload: payload,
+                             resource_type: "Order")
+
+          orders = response&.dig("orders") || []
+          logger.info "Found #{orders.size} orders"
+          orders
+        end
+
+        # Update an order
+        # @param order_id [String] The order ID
+        # @param fields [Hash] Fields to update on the order object
+        # @param version [Integer] Current order version for optimistic concurrency
+        # @return [Hash, nil] Updated order
+        def update_order(order_id, fields:, version:)
+          logger.info "Updating order: #{order_id}"
+
+          order_data = fields.merge(
+            "location_id" => config.location_id,
+            "version" => version,
+          )
+
+          payload = { "order" => order_data }
+
+          response = request(:put, "orders/#{order_id}",
+                             payload: payload,
+                             resource_type: "Order",
+                             resource_id: order_id)
+
+          response&.dig("order")
+        end
+
+        # Calculate order totals without creating
+        # @param line_items [Array<Hash>] Array of line item hashes
+        # @return [Hash, nil] Calculated order
+        def calculate_order(line_items:)
+          logger.info "Calculating order..."
+
+          payload = {
+            "order" => {
+              "location_id" => config.location_id,
+              "line_items" => line_items,
+            },
+          }
+
+          response = request(:post, "orders/calculate",
+                             payload: payload,
+                             resource_type: "Order")
+
+          response&.dig("order")
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+module SquareSandboxSimulator
+  module Services
+    module Square
+      # Manages Square payments and refunds
+      class PaymentService < BaseService
+        # Create a payment
+        # @param order_id [String] The order ID
+        # @param amount [Integer] Amount in cents
+        # @param source_id [String] Payment source (default: sandbox card nonce)
+        # @param tip_amount [Integer] Tip amount in cents
+        # @return [Hash, nil] Payment response
+        def create_payment(order_id:, amount:, source_id: "cnon:card-nonce-ok", tip_amount: 0)
+          logger.info "Creating payment for order #{order_id}: $#{amount / 100.0}"
+
+          payload = {
+            "source_id" => source_id,
+            "amount_money" => {
+              "amount" => amount,
+              "currency" => "USD",
+            },
+            "order_id" => order_id,
+            "location_id" => config.location_id,
+          }
+
+          if tip_amount.positive?
+            payload["tip_money"] = {
+              "amount" => tip_amount,
+              "currency" => "USD",
+            }
+          end
+
+          response = request(:post, "payments",
+                             payload: payload,
+                             resource_type: "Payment")
+
+          payment = response&.dig("payment")
+          logger.info "Payment created: #{payment["id"]} (status: #{payment["status"]})" if payment
+
+          payment
+        end
+
+        # Create a cash payment using external payment source
+        # @param order_id [String] The order ID
+        # @param amount [Integer] Amount in cents
+        # @return [Hash, nil] Payment response
+        def create_cash_payment(order_id:, amount:)
+          logger.info "Creating cash payment for order #{order_id}: $#{amount / 100.0}"
+
+          payload = {
+            "source_id" => "EXTERNAL",
+            "external_details" => {
+              "type" => "CASH",
+              "source" => "Cash Register",
+            },
+            "amount_money" => {
+              "amount" => amount,
+              "currency" => "USD",
+            },
+            "order_id" => order_id,
+            "location_id" => config.location_id,
+          }
+
+          response = request(:post, "payments",
+                             payload: payload,
+                             resource_type: "Payment")
+
+          payment = response&.dig("payment")
+          logger.info "Cash payment created: #{payment["id"]}" if payment
+
+          payment
+        end
+
+        # Get a single payment
+        # @param payment_id [String] The payment ID
+        # @return [Hash, nil] Payment response
+        def get_payment(payment_id)
+          logger.info "Fetching payment: #{payment_id}"
+          response = request(:get, "payments/#{payment_id}",
+                             resource_type: "Payment",
+                             resource_id: payment_id)
+          response&.dig("payment")
+        end
+
+        # List payments
+        # @return [Array<Hash>] Array of payments
+        def list_payments
+          logger.info "Listing payments..."
+          response = request(:get, "payments")
+          payments = response&.dig("payments") || []
+          logger.info "Found #{payments.size} payments"
+          payments
+        end
+
+        # Refund a payment
+        # @param payment_id [String] The payment ID to refund
+        # @param amount [Integer] Amount to refund in cents
+        # @param reason [String] Reason for refund
+        # @return [Hash, nil] Refund response
+        def refund_payment(payment_id:, amount:, reason:)
+          logger.info "Refunding payment #{payment_id}: $#{amount / 100.0} (#{reason})"
+
+          payload = {
+            "payment_id" => payment_id,
+            "amount_money" => {
+              "amount" => amount,
+              "currency" => "USD",
+            },
+            "reason" => reason,
+          }
+
+          response = request(:post, "refunds",
+                             payload: payload,
+                             resource_type: "Refund")
+
+          refund = response&.dig("refund")
+          logger.info "Refund created: #{refund["id"]} (status: #{refund["status"]})" if refund
+
+          refund
+        end
+
+        # Get a single refund
+        # @param refund_id [String] The refund ID
+        # @return [Hash, nil] Refund response
+        def get_refund(refund_id)
+          logger.info "Fetching refund: #{refund_id}"
+          response = request(:get, "refunds/#{refund_id}",
+                             resource_type: "Refund",
+                             resource_id: refund_id)
+          response&.dig("refund")
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module SquareSandboxSimulator
+  module Services
+    module Square
+      # Central manager for all Square services
+      # Provides thread-safe, lazy-loaded access to all service classes
+      class ServicesManager
+        attr_reader :config
+
+        def initialize(config: nil)
+          @config = config || SquareSandboxSimulator.configuration
+          @mutex = Mutex.new
+        end
+
+        def catalog
+          thread_safe_memoize(:@catalog) { CatalogService.new(config: config) }
+        end
+
+        def order
+          thread_safe_memoize(:@order) { OrderService.new(config: config) }
+        end
+
+        def payment
+          thread_safe_memoize(:@payment) { PaymentService.new(config: config) }
+        end
+
+        def customer
+          thread_safe_memoize(:@customer) { CustomerService.new(config: config) }
+        end
+
+        def team
+          thread_safe_memoize(:@team) { TeamService.new(config: config) }
+        end
+
+        # Clear all cached service instances
+        def clear_services
+          @mutex.synchronize do
+            instance_variables.each do |var|
+              next if %i[@config @mutex].include?(var)
+
+              instance_variable_set(var, nil)
+            end
+          end
+        end
+
+        private
+
+        # Thread-safe memoization pattern
+        def thread_safe_memoize(ivar_name)
+          # Fast path: return if already set
+          value = instance_variable_get(ivar_name)
+          return value if value
+
+          # Slow path: synchronize and check again
+          @mutex.synchronize do
+            value = instance_variable_get(ivar_name)
+            return value if value
+
+            value = yield
+            instance_variable_set(ivar_name, value)
+            value
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require "faker"
+
+module SquareSandboxSimulator
+  module Services
+    module Square
+      # Manages Square team members
+      class TeamService < BaseService
+        # Create a team member
+        # @param given_name [String] First name
+        # @param family_name [String] Last name
+        # @param email [String, nil] Email address
+        # @return [Hash, nil] Team member response
+        def create_team_member(given_name:, family_name:, email: nil)
+          logger.info "Creating team member: #{given_name} #{family_name}"
+
+          team_member_data = {
+            "given_name" => given_name,
+            "family_name" => family_name,
+          }
+          team_member_data["email_address"] = email if email
+
+          # Assign to the configured location
+          payload = {
+            "team_member" => team_member_data,
+          }
+
+          response = request(:post, "team-members",
+                             payload: payload,
+                             resource_type: "TeamMember")
+
+          member = response&.dig("team_member")
+          logger.info "Team member created: #{member["id"]}" if member
+          member
+        end
+
+        # Search team members
+        # @return [Array<Hash>] Array of team members
+        def search_team_members
+          logger.info "Searching team members..."
+
+          payload = {
+            "query" => {
+              "filter" => {
+                "location_ids" => [config.location_id],
+                "status" => "ACTIVE",
+              },
+            },
+          }
+
+          response = request(:post, "team-members/search",
+                             payload: payload,
+                             resource_type: "TeamMember")
+
+          members = response&.dig("team_members") || []
+          logger.info "Found #{members.size} team members"
+          members
+        end
+
+        # Default team member data for deterministic setup
+        DEFAULT_TEAM_MEMBERS = [
+          { given: "Alex", family: "Manager" },
+          { given: "Jordan", family: "Server" },
+          { given: "Casey", family: "Cook" },
+          { given: "Riley", family: "Host" },
+          { given: "Morgan", family: "Bartender" },
+        ].freeze
+
+        # Create sample team members if needed (idempotent)
+        # @param count [Integer] Minimum number of team members to ensure exist
+        # @return [Array<Hash>] All team members
+        def ensure_team_members(count: 5)
+          existing = search_team_members
+          return existing if existing.size >= count
+
+          needed = count - existing.size
+          logger.info "Creating #{needed} sample team members..."
+
+          new_members = []
+          needed.times do |i|
+            idx = existing.size + i
+            if idx < DEFAULT_TEAM_MEMBERS.size
+              member_data = DEFAULT_TEAM_MEMBERS[idx]
+              given = member_data[:given]
+              family = member_data[:family]
+            else
+              given = Faker::Name.first_name
+              family = Faker::Name.last_name
+            end
+
+            safe_given = given.downcase.gsub(/[^a-z0-9]/, "")
+            safe_family = family.downcase.gsub(/[^a-z0-9]/, "")
+
+            member = create_team_member(
+              given_name: given,
+              family_name: family,
+              email: "#{safe_given}.#{safe_family}@example.com",
+            )
+            new_members << member if member
+          end
+
+          existing + new_members
+        end
+      end
+    end
+  end
+end

data/lib/square_sandbox_simulator/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module SquareSandboxSimulator
+  VERSION = "0.1.0"
+end

data/lib/square_sandbox_simulator.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require "zeitwerk"
+require "logger"
+require "json"
+require "rest-client"
+require "dotenv"
+
+# Load environment variables
+Dotenv.load
+
+module SquareSandboxSimulator
+  VERSION = "0.1.0"
+
+  class Error < StandardError; end
+  class ConfigurationError < Error; end
+  class ApiError < Error; end
+
+  class << self
+    attr_writer :configuration
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+
+    def logger
+      configuration.logger
+    end
+
+    def root
+      File.expand_path("..", __dir__)
+    end
+  end
+end
+
+# Set up Zeitwerk autoloader
+loader = Zeitwerk::Loader.for_gem
+# Migrations and factories follow ActiveRecord conventions, not Zeitwerk naming
+loader.ignore(File.expand_path("square_sandbox_simulator/db", __dir__))
+loader.setup
+
+# Eager load all autoloaded constants
+loader.eager_load