epos_now_sandbox_simulator 0.1.0

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

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+module EposNowSandboxSimulator
+  module Services
+    module EposNow
+      # Manages transactions in Epos Now via V4 API.
+      #
+      # V4 endpoints:
+      #   GET    /api/v4/Transaction              - list (params: status, page)
+      #   POST   /api/v4/Transaction              - create
+      #   GET    /api/v4/Transaction/{id}          - get by id
+      #   PUT    /api/v4/Transaction/{id}          - update
+      #   DELETE /api/v4/Transaction/{id}          - delete
+      #   GET    /api/v4/Transaction/GetByDate     - filter by date range
+      #   GET    /api/v4/Transaction/GetLatest     - latest transactions
+      #   POST   /api/v4/Transaction/Validate      - validate without saving
+      #
+      # V4 Transaction model:
+      #   Id, CustomerId, StaffId, TableId, DeviceId, DateTime,
+      #   StatusId, Barcode, ServiceType, TotalAmount, ServiceCharge,
+      #   Gratuity, DiscountValue, DiscountReasonId, ReferenceCode,
+      #   TransactionItems[], Tenders[], Taxes[]
+      #
+      # V4 ServiceType values (replaces V2 EatOut):
+      #   0 = EatIn, 1 = Takeaway, 2 = Delivery
+      #
+      # V4 key difference: Tenders are embedded in Transaction creation,
+      # not separate CRUD entities.
+      class TransactionService < BaseService
+        # ServiceType values (V4)
+        EAT_IN = 0
+        TAKEAWAY = 1
+        DELIVERY = 2
+
+        # Fetch transactions (paginated)
+        # @param page [Integer, nil] Page number
+        # @param status [Integer, nil] Status filter
+        # @return [Array<Hash>] Transactions
+        def fetch_transactions(page: nil, status: nil)
+          if page
+            params = { page: page }
+            params[:status] = status if status
+            request(:get, endpoint("Transaction"), params: params, resource_type: "Transaction") || []
+          else
+            fetch_all_pages("Transaction")
+          end
+        end
+
+        # Fetch transactions by date range (V4-specific endpoint)
+        # @param start_date [String, Date] Start date (ISO 8601)
+        # @param end_date [String, Date] End date (ISO 8601)
+        # @param device_id [Integer, nil] Filter by device
+        # @param status [Integer, nil] Filter by status
+        # @return [Array<Hash>] Transactions in range
+        def fetch_transactions_by_date(start_date:, end_date:, device_id: nil, status: nil)
+          params = {
+            startDate: start_date.to_s,
+            endDate: end_date.to_s
+          }
+          params[:deviceId] = device_id if device_id
+          params[:status] = status if status
+
+          all_records = []
+          page = 1
+
+          loop do
+            page_params = params.merge(page: page)
+            results = request(:get, endpoint("Transaction/GetByDate"), params: page_params, resource_type: "Transaction")
+            records = results.is_a?(Array) ? results : []
+            break if records.empty?
+
+            all_records.concat(records)
+            break if records.size < 200
+
+            page += 1
+          end
+
+          all_records
+        end
+
+        # Fetch latest transactions
+        # @param device_id [Integer, nil] Filter by device
+        # @param status [Integer, nil] Filter by status
+        # @return [Array<Hash>] Latest transactions
+        def fetch_latest_transactions(device_id: nil, status: nil)
+          params = {}
+          params[:deviceId] = device_id if device_id
+          params[:status] = status if status
+
+          request(:get, endpoint("Transaction/GetLatest"), params: params, resource_type: "Transaction") || []
+        end
+
+        # Get a single transaction by ID
+        # @param id [Integer] Transaction ID
+        # @param lock [Boolean] Lock the transaction
+        # @return [Hash] Transaction
+        def get_transaction(id, lock: false)
+          path = lock ? "Transaction/#{id}/true" : "Transaction/#{id}/false"
+          request(:get, endpoint(path), resource_type: "Transaction", resource_id: id.to_s)
+        end
+
+        # Create a complete transaction with items and tenders (V4 style)
+        #
+        # In V4, TransactionItems and Tenders are embedded in the
+        # Transaction creation payload — no separate API calls needed.
+        #
+        # @param items [Array<Hash>] Array of {product_id:, quantity:, unit_price:}
+        # @param tenders [Array<Hash>] Array of {tender_type_id:, amount:, change_given:}
+        # @param service_type [Integer] 0=EatIn, 1=Takeaway, 2=Delivery
+        # @param staff_id [Integer, nil] Staff member
+        # @param customer_id [Integer, nil] Customer
+        # @param gratuity [Float] Tip amount
+        # @param discount_value [Float] Discount amount
+        # @param service_charge [Float] Service charge amount
+        # @return [Hash] Created transaction with embedded items and tenders
+        def create_transaction(items:, tenders:, service_type: EAT_IN, staff_id: nil,
+                               customer_id: nil, gratuity: 0.0, discount_value: 0.0, service_charge: 0.0)
+          # Build V4 TransactionItems
+          transaction_items = items.map do |item|
+            ti = {
+              "ProductId" => item[:product_id],
+              "Quantity" => item[:quantity] || 1
+            }
+            ti["UnitPrice"] = item[:unit_price] if item[:unit_price]
+            ti["DiscountAmount"] = item[:discount] if item[:discount]&.positive?
+            ti["Notes"] = item[:notes] if item[:notes]
+            ti
+          end
+
+          # Build V4 Tenders
+          transaction_tenders = tenders.map do |tender|
+            {
+              "TenderTypeId" => tender[:tender_type_id],
+              "Amount" => tender[:amount],
+              "ChangeGiven" => tender[:change_given] || 0.0
+            }
+          end
+
+          payload = {
+            "ServiceType" => service_type,
+            "Gratuity" => gratuity,
+            "DiscountValue" => discount_value,
+            "ServiceCharge" => service_charge,
+            "TransactionItems" => transaction_items,
+            "Tenders" => transaction_tenders
+          }
+          payload["StaffId"] = staff_id if staff_id
+          payload["CustomerId"] = customer_id if customer_id
+
+          logger.info "Creating transaction (ServiceType=#{service_type}, #{items.size} items, #{tenders.size} tenders)"
+          result = request(:post, endpoint("Transaction"), payload: payload, resource_type: "Transaction")
+          logger.info "Created transaction ID: #{result["Id"]}"
+          result
+        end
+
+        # Delete a transaction (V4: uses request body)
+        # @param id [Integer] Transaction ID
+        def delete_transaction(id)
+          request(:delete, endpoint("Transaction/#{id}"), resource_type: "Transaction", resource_id: id.to_s)
+        end
+
+        # Validate a transaction without saving
+        # @param payload [Hash] Transaction payload
+        # @return [Hash] Validation result
+        def validate_transaction(payload)
+          request(:post, endpoint("Transaction/Validate"), payload: payload, resource_type: "Transaction")
+        end
+      end
+    end
+  end
+end

data/lib/epos_now_sandbox_simulator.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "zeitwerk"
+require "logger"
+require "json"
+require "rest-client"
+require "dotenv"
+
+# Load environment variables
+Dotenv.load
+
+module EposNowSandboxSimulator
+  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("epos_now_sandbox_simulator/db", __dir__))
+loader.setup
+
+# :nocov:
+# Eager load in production
+loader.eager_load if ENV["RACK_ENV"] == "production"
+# :nocov:

metadata

@@ -0,0 +1,334 @@
+--- !ruby/object:Gem::Specification
+name: epos_now_sandbox_simulator
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- dan1d
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-03-13 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '8.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '8.0'
+- !ruby/object:Gem::Dependency
+  name: concurrent-ruby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+- !ruby/object:Gem::Dependency
+  name: dotenv
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: factory_bot
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.4'
+- !ruby/object:Gem::Dependency
+  name: faker
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.2'
+- !ruby/object:Gem::Dependency
+  name: pg
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+- !ruby/object:Gem::Dependency
+  name: rest-client
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+- !ruby/object:Gem::Dependency
+  name: thor
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: tzinfo
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: zeitwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+- !ruby/object:Gem::Dependency
+  name: database_cleaner-active_record
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.50'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.50'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+- !ruby/object:Gem::Dependency
+  name: vcr
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.1'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.18'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.18'
+description: A Ruby gem for simulating Point of Sale operations against the Epos Now
+  API. Generates realistic orders, payments, and transaction data for testing.
+email:
+- dan1d@users.noreply.github.com
+executables:
+- simulate
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- LICENSE
+- README.md
+- bin/simulate
+- lib/epos_now_sandbox_simulator.rb
+- lib/epos_now_sandbox_simulator/configuration.rb
+- lib/epos_now_sandbox_simulator/data/bar_nightclub/categories.json
+- lib/epos_now_sandbox_simulator/data/bar_nightclub/items.json
+- lib/epos_now_sandbox_simulator/data/bar_nightclub/tenders.json
+- lib/epos_now_sandbox_simulator/data/cafe_bakery/categories.json
+- lib/epos_now_sandbox_simulator/data/cafe_bakery/items.json
+- lib/epos_now_sandbox_simulator/data/cafe_bakery/tenders.json
+- lib/epos_now_sandbox_simulator/data/restaurant/categories.json
+- lib/epos_now_sandbox_simulator/data/restaurant/items.json
+- lib/epos_now_sandbox_simulator/data/restaurant/tenders.json
+- lib/epos_now_sandbox_simulator/data/retail_general/categories.json
+- lib/epos_now_sandbox_simulator/data/retail_general/items.json
+- lib/epos_now_sandbox_simulator/data/retail_general/tenders.json
+- lib/epos_now_sandbox_simulator/database.rb
+- lib/epos_now_sandbox_simulator/db/factories/api_requests.rb
+- lib/epos_now_sandbox_simulator/db/factories/business_types.rb
+- lib/epos_now_sandbox_simulator/db/factories/categories.rb
+- lib/epos_now_sandbox_simulator/db/factories/items.rb
+- lib/epos_now_sandbox_simulator/db/factories/simulated_orders.rb
+- lib/epos_now_sandbox_simulator/db/factories/simulated_payments.rb
+- lib/epos_now_sandbox_simulator/db/migrate/20260312000001_enable_pgcrypto.rb
+- lib/epos_now_sandbox_simulator/db/migrate/20260312000002_create_business_types.rb
+- lib/epos_now_sandbox_simulator/db/migrate/20260312000003_create_categories.rb
+- lib/epos_now_sandbox_simulator/db/migrate/20260312000004_create_items.rb
+- lib/epos_now_sandbox_simulator/db/migrate/20260312000005_create_simulated_orders.rb
+- lib/epos_now_sandbox_simulator/db/migrate/20260312000006_create_simulated_payments.rb
+- lib/epos_now_sandbox_simulator/db/migrate/20260312000007_create_api_requests.rb
+- lib/epos_now_sandbox_simulator/db/migrate/20260312000008_create_daily_summaries.rb
+- lib/epos_now_sandbox_simulator/generators/data_loader.rb
+- lib/epos_now_sandbox_simulator/generators/entity_generator.rb
+- lib/epos_now_sandbox_simulator/generators/order_generator.rb
+- lib/epos_now_sandbox_simulator/models/api_request.rb
+- lib/epos_now_sandbox_simulator/models/business_type.rb
+- lib/epos_now_sandbox_simulator/models/category.rb
+- lib/epos_now_sandbox_simulator/models/daily_summary.rb
+- lib/epos_now_sandbox_simulator/models/item.rb
+- lib/epos_now_sandbox_simulator/models/simulated_order.rb
+- lib/epos_now_sandbox_simulator/models/simulated_payment.rb
+- lib/epos_now_sandbox_simulator/seeder.rb
+- lib/epos_now_sandbox_simulator/services/base_service.rb
+- lib/epos_now_sandbox_simulator/services/epos_now/inventory_service.rb
+- lib/epos_now_sandbox_simulator/services/epos_now/services_manager.rb
+- lib/epos_now_sandbox_simulator/services/epos_now/tax_service.rb
+- lib/epos_now_sandbox_simulator/services/epos_now/tender_service.rb
+- lib/epos_now_sandbox_simulator/services/epos_now/transaction_service.rb
+homepage: https://github.com/dan1d/epos_now_sandbox_simulator
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.10
+signing_key:
+specification_version: 4
+summary: Epos Now POS sandbox data simulator
+test_files: []