gusto_sandbox_simulator 0.1.0

data/lib/gusto_sandbox_simulator/database.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require 'active_record'
+require 'logger'
+
+module GustoSandboxSimulator
+  # Standalone ActiveRecord connection manager for PostgreSQL.
+  #
+  # Provides database connectivity without requiring Rails.
+  # Used for persisting Gusto sandbox data (employees, payroll runs, etc.)
+  module Database
+    MIGRATIONS_PATH = File.expand_path('db/migrate', __dir__).freeze
+    TEST_DATABASE = 'gusto_simulator_test'
+
+    class << self
+      def create!(url)
+        db_name = URI.parse(url).path.delete_prefix('/')
+        maintenance_url = url.sub(%r{/[^/]+\z}, '/postgres')
+
+        ActiveRecord::Base.establish_connection(maintenance_url)
+        ActiveRecord::Base.connection.create_database(db_name)
+        GustoSandboxSimulator.logger.info("Database created: #{db_name}")
+      rescue ActiveRecord::DatabaseAlreadyExists, ActiveRecord::StatementInvalid => e
+        raise unless e.message.include?('already exists')
+
+        GustoSandboxSimulator.logger.info("Database already exists: #{db_name}")
+      ensure
+        ActiveRecord::Base.connection_pool.disconnect!
+      end
+
+      def drop!(url)
+        db_name = URI.parse(url).path.delete_prefix('/')
+        maintenance_url = url.sub(%r{/[^/]+\z}, '/postgres')
+
+        ActiveRecord::Base.establish_connection(maintenance_url)
+        ActiveRecord::Base.connection.drop_database(db_name)
+        GustoSandboxSimulator.logger.info("Database dropped: #{db_name}")
+      rescue ActiveRecord::StatementInvalid => e
+        raise unless e.message.include?('does not exist')
+
+        GustoSandboxSimulator.logger.info("Database does not exist: #{db_name}")
+      ensure
+        ActiveRecord::Base.connection_pool.disconnect!
+      end
+
+      def database_url
+        url = Configuration.database_url_from_file
+        raise Error, 'No DATABASE_URL found in .env.json' unless url
+
+        url
+      end
+
+      def connect!(url)
+        unless url.match?(%r{\Apostgres(ql)?://}i)
+          raise ArgumentError,
+                "Expected a PostgreSQL URL (postgres:// or postgresql://), got: #{url.split('://').first}://"
+        end
+
+        ActiveRecord::Base.establish_connection(url)
+        ActiveRecord::Base.connection.execute('SELECT 1')
+        ActiveRecord::Base.logger = GustoSandboxSimulator.logger
+
+        GustoSandboxSimulator.logger.info("Database connected: #{sanitize_url(url)}")
+      end
+
+      def migrate!
+        ensure_connected!
+
+        GustoSandboxSimulator.logger.info("Running migrations from #{MIGRATIONS_PATH}")
+        context = ActiveRecord::MigrationContext.new(MIGRATIONS_PATH)
+        context.migrate
+        GustoSandboxSimulator.logger.info('Migrations complete')
+      end
+
+      def seed!(business_type: nil)
+        ensure_connected!
+        load_factories!
+
+        business_type ||= GustoSandboxSimulator.configuration.business_type
+        Seeder.seed!(business_type: business_type)
+      end
+
+      def connected?
+        ActiveRecord::Base.connection_pool.with_connection(&:active?)
+      rescue StandardError
+        false
+      end
+
+      def disconnect!
+        ActiveRecord::Base.connection_pool.disconnect!
+        GustoSandboxSimulator.logger.info('Database disconnected')
+      end
+
+      def test_database_url(base_url: nil)
+        url = base_url || Configuration.database_url_from_file
+        return "postgres://localhost:5432/#{TEST_DATABASE}" if url.nil?
+
+        uri = URI.parse(url)
+        uri.path = "/#{TEST_DATABASE}"
+        uri.to_s
+      rescue URI::InvalidURIError
+        "postgres://localhost:5432/#{TEST_DATABASE}"
+      end
+
+      private
+
+      def ensure_connected!
+        return if connected?
+
+        raise GustoSandboxSimulator::Error,
+              'Database not connected. Call Database.connect!(url) first.'
+      end
+
+      def load_factories!
+        return if @factories_loaded
+
+        require 'factory_bot'
+
+        factories_path = File.expand_path('db/factories', __dir__)
+        FactoryBot.definition_file_paths = [factories_path] if Dir.exist?(factories_path)
+        FactoryBot.find_definitions
+        @factories_loaded = true
+      rescue StandardError => e
+        GustoSandboxSimulator.logger.warn("Could not load factories: #{e.message}")
+      end
+
+      def sanitize_url(url)
+        uri = URI.parse(url)
+        uri.password = '***' if uri.password
+        uri.user = '***' if uri.user
+        uri.to_s
+      rescue URI::InvalidURIError
+        url.gsub(%r{://[^@]+@}, '://***:***@')
+      end
+    end
+  end
+end

data/lib/gusto_sandbox_simulator/db/factories/api_requests.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+FactoryBot.define do
+  factory :api_request, class: 'GustoSandboxSimulator::Models::ApiRequest' do
+    http_method { 'GET' }
+    url { 'https://api.gusto-demo.com/v1/companies/test-uuid/payrolls' }
+    request_payload { {} }
+    response_payload { {} }
+    response_status { 200 }
+    duration_ms { 150 }
+    gusto_company_uuid { 'test-company-uuid' }
+  end
+end

data/lib/gusto_sandbox_simulator/db/factories/business_types.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+FactoryBot.define do
+  factory :business_type, class: 'GustoSandboxSimulator::Models::BusinessType' do
+    key { 'restaurant' }
+    name { 'Restaurant' }
+    industry { 'food' }
+    payroll_profile do
+      {
+        'pay_frequency' => 'bi_weekly',
+        'typical_employee_count' => 14,
+        'departments' => ['Kitchen', 'Front of House', 'Bar', 'Management']
+      }
+    end
+
+    trait :restaurant do
+      key { 'restaurant' }
+      name { 'Restaurant' }
+      industry { 'food' }
+    end
+  end
+end

data/lib/gusto_sandbox_simulator/db/factories/employees.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+FactoryBot.define do
+  factory :employee, class: 'GustoSandboxSimulator::Models::Employee' do
+    association :business_type
+    first_name { 'John' }
+    last_name { 'Doe' }
+    role { 'Line Cook' }
+    department { 'Kitchen' }
+    compensation_type { 'hourly' }
+    rate_cents { 1_700 }
+    active { true }
+
+    # Kitchen staff
+    trait :head_chef do
+      first_name { 'Maria' }
+      last_name { 'Rodriguez' }
+      role { 'Head Chef' }
+      department { 'Kitchen' }
+      compensation_type { 'salary' }
+      rate_cents { 5_500_000 }
+    end
+
+    trait :sous_chef do
+      first_name { 'James' }
+      last_name { 'Chen' }
+      role { 'Sous Chef' }
+      department { 'Kitchen' }
+      compensation_type { 'salary' }
+      rate_cents { 4_500_000 }
+    end
+
+    trait :line_cook_1 do
+      first_name { 'David' }
+      last_name { 'Kim' }
+      role { 'Line Cook' }
+      department { 'Kitchen' }
+      compensation_type { 'hourly' }
+      rate_cents { 1_800 }
+    end
+
+    trait :line_cook_2 do
+      first_name { 'Sarah' }
+      last_name { 'Johnson' }
+      role { 'Line Cook' }
+      department { 'Kitchen' }
+      compensation_type { 'hourly' }
+      rate_cents { 1_700 }
+    end
+
+    trait :prep_cook do
+      first_name { 'Miguel' }
+      last_name { 'Torres' }
+      role { 'Prep Cook' }
+      department { 'Kitchen' }
+      compensation_type { 'hourly' }
+      rate_cents { 1_500 }
+    end
+
+    trait :dishwasher do
+      first_name { 'Omar' }
+      last_name { 'Hassan' }
+      role { 'Dishwasher' }
+      department { 'Kitchen' }
+      compensation_type { 'hourly' }
+      rate_cents { 1_400 }
+    end
+
+    # Management
+    trait :general_manager do
+      first_name { 'Jessica' }
+      last_name { 'Williams' }
+      role { 'General Manager' }
+      department { 'Management' }
+      compensation_type { 'salary' }
+      rate_cents { 5_000_000 }
+    end
+
+    # Front of House
+    trait :server_1 do
+      first_name { 'Emily' }
+      last_name { 'Davis' }
+      role { 'Server' }
+      department { 'Front of House' }
+      compensation_type { 'hourly' }
+      rate_cents { 550 }
+    end
+
+    trait :server_2 do
+      first_name { 'Brandon' }
+      last_name { 'Lee' }
+      role { 'Server' }
+      department { 'Front of House' }
+      compensation_type { 'hourly' }
+      rate_cents { 550 }
+    end
+
+    trait :server_3 do
+      first_name { 'Ashley' }
+      last_name { 'Martinez' }
+      role { 'Server' }
+      department { 'Front of House' }
+      compensation_type { 'hourly' }
+      rate_cents { 550 }
+    end
+
+    trait :host do
+      first_name { 'Sophia' }
+      last_name { 'Anderson' }
+      role { 'Host' }
+      department { 'Front of House' }
+      compensation_type { 'hourly' }
+      rate_cents { 1_400 }
+    end
+
+    trait :busser do
+      first_name { 'Marcus' }
+      last_name { 'Wilson' }
+      role { 'Busser' }
+      department { 'Front of House' }
+      compensation_type { 'hourly' }
+      rate_cents { 1_200 }
+    end
+
+    # Bar
+    trait :bartender_1 do
+      first_name { 'Tyler' }
+      last_name { 'Brown' }
+      role { 'Bartender' }
+      department { 'Bar' }
+      compensation_type { 'hourly' }
+      rate_cents { 700 }
+    end
+
+    trait :bartender_2 do
+      first_name { 'Nicole' }
+      last_name { 'Taylor' }
+      role { 'Bartender' }
+      department { 'Bar' }
+      compensation_type { 'hourly' }
+      rate_cents { 700 }
+    end
+  end
+end

data/lib/gusto_sandbox_simulator/db/factories/payroll_runs.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+FactoryBot.define do
+  factory :payroll_run, class: 'GustoSandboxSimulator::Models::PayrollRun' do
+    gusto_company_uuid { SecureRandom.uuid }
+    gusto_payroll_id { SecureRandom.uuid }
+    pay_period_start { Date.new(2026, 3, 1) }
+    pay_period_end { Date.new(2026, 3, 15) }
+    check_date { Date.new(2026, 3, 20) }
+    status { 'processed' }
+    gross_pay_cents { 1_500_000 }
+    net_pay_cents { 1_125_000 }
+    employer_taxes_cents { 120_000 }
+    employee_taxes_cents { 225_000 }
+    benefits_cents { 80_000 }
+    reimbursements_cents { 15_000 }
+    employee_count { 14 }
+    employee_compensations { [] }
+
+    trait :processed do
+      status { 'processed' }
+    end
+
+    trait :pending do
+      status { 'pending' }
+    end
+  end
+end

data/lib/gusto_sandbox_simulator/db/migrate/20260323000001_enable_pgcrypto.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+class EnablePgcrypto < ActiveRecord::Migration[8.0]
+  def change
+    enable_extension 'pgcrypto' unless extension_enabled?('pgcrypto')
+  end
+end

data/lib/gusto_sandbox_simulator/db/migrate/20260323000002_create_business_types.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+class CreateBusinessTypes < ActiveRecord::Migration[8.0]
+  def change
+    create_table :business_types, id: :uuid, default: 'gen_random_uuid()' do |t|
+      t.string :key, null: false
+      t.string :name, null: false
+      t.string :industry, null: false
+      t.jsonb :payroll_profile, default: {}
+      t.timestamps
+    end
+
+    add_index :business_types, :key, unique: true
+  end
+end

data/lib/gusto_sandbox_simulator/db/migrate/20260323000003_create_employees.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+class CreateEmployees < ActiveRecord::Migration[8.0]
+  def change
+    create_table :employees, id: :uuid, default: 'gen_random_uuid()' do |t|
+      t.references :business_type, type: :uuid, foreign_key: true, null: false
+      t.string :first_name, null: false
+      t.string :last_name, null: false
+      t.string :email
+      t.string :role, null: false
+      t.string :department, null: false
+      t.string :compensation_type, null: false, default: 'hourly'
+      t.integer :rate_cents, null: false
+      t.boolean :active, null: false, default: true
+      t.string :gusto_employee_uuid
+      t.jsonb :metadata, default: {}
+      t.timestamps
+    end
+
+    add_index :employees, :gusto_employee_uuid, unique: true, where: 'gusto_employee_uuid IS NOT NULL'
+    add_index :employees, :department
+  end
+end

data/lib/gusto_sandbox_simulator/db/migrate/20260323000004_create_payroll_runs.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+class CreatePayrollRuns < ActiveRecord::Migration[8.0]
+  def change
+    create_table :payroll_runs, id: :uuid, default: 'gen_random_uuid()' do |t|
+      t.string :gusto_company_uuid, null: false
+      t.string :gusto_payroll_id
+      t.date :pay_period_start, null: false
+      t.date :pay_period_end, null: false
+      t.date :check_date, null: false
+      t.string :status, null: false, default: 'processed'
+      t.integer :gross_pay_cents, null: false, default: 0
+      t.integer :net_pay_cents, null: false, default: 0
+      t.integer :employer_taxes_cents, null: false, default: 0
+      t.integer :employee_taxes_cents, null: false, default: 0
+      t.integer :benefits_cents, null: false, default: 0
+      t.integer :reimbursements_cents, null: false, default: 0
+      t.integer :employee_count, null: false, default: 0
+      t.jsonb :employee_compensations, default: []
+      t.jsonb :metadata, default: {}
+      t.timestamps
+    end
+
+    add_index :payroll_runs, :gusto_payroll_id, unique: true, where: 'gusto_payroll_id IS NOT NULL'
+    add_index :payroll_runs, :gusto_company_uuid
+    add_index :payroll_runs, %i[gusto_company_uuid pay_period_start pay_period_end],
+              unique: true, name: 'idx_payroll_runs_company_period'
+  end
+end

data/lib/gusto_sandbox_simulator/db/migrate/20260323000005_create_api_requests.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+class CreateApiRequests < ActiveRecord::Migration[8.0]
+  def change
+    create_table :api_requests, id: :uuid, default: 'gen_random_uuid()' do |t|
+      t.string :http_method, null: false
+      t.string :url, null: false
+      t.jsonb :request_payload, default: {}
+      t.jsonb :response_payload, default: {}
+      t.integer :response_status
+      t.integer :duration_ms
+      t.string :error_message
+      t.string :resource_type
+      t.string :resource_id
+      t.string :gusto_company_uuid
+      t.timestamps
+    end
+
+    add_index :api_requests, :created_at
+    add_index :api_requests, :gusto_company_uuid
+  end
+end

data/lib/gusto_sandbox_simulator/db/migrate/20260323000006_create_daily_summaries.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+class CreateDailySummaries < ActiveRecord::Migration[8.0]
+  def change
+    create_table :daily_summaries, id: :uuid, default: 'gen_random_uuid()' do |t|
+      t.string :gusto_company_uuid, null: false
+      t.date :business_date, null: false
+      t.integer :payroll_run_count, default: 0
+      t.integer :employee_count, default: 0
+      t.integer :total_gross_pay_cents, default: 0
+      t.integer :total_net_pay_cents, default: 0
+      t.integer :total_taxes_cents, default: 0
+      t.integer :total_benefits_cents, default: 0
+      t.jsonb :breakdown, default: {}
+      t.timestamps
+    end
+
+    add_index :daily_summaries, %i[gusto_company_uuid business_date], unique: true
+  end
+end

data/lib/gusto_sandbox_simulator/generators/entity_generator.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module GustoSandboxSimulator
+  module Generators
+    # Creates employees in the Gusto sandbox company.
+    # Idempotent — matches existing employees by name before creating.
+    class EntityGenerator
+      attr_reader :services, :config, :logger
+
+      # Default restaurant employee roster
+      RESTAURANT_EMPLOYEES = [
+        { first_name: 'Maria', last_name: 'Rodriguez', role: 'Head Chef', department: 'Kitchen',
+          compensation_type: 'salary', rate_cents: 5_500_000 },
+        { first_name: 'James', last_name: 'Chen', role: 'Sous Chef', department: 'Kitchen',
+          compensation_type: 'salary', rate_cents: 4_500_000 },
+        { first_name: 'David', last_name: 'Kim', role: 'Line Cook', department: 'Kitchen',
+          compensation_type: 'hourly', rate_cents: 1_800 },
+        { first_name: 'Sarah', last_name: 'Johnson', role: 'Line Cook', department: 'Kitchen',
+          compensation_type: 'hourly', rate_cents: 1_700 },
+        { first_name: 'Miguel', last_name: 'Torres', role: 'Prep Cook', department: 'Kitchen',
+          compensation_type: 'hourly', rate_cents: 1_500 },
+        { first_name: 'Omar', last_name: 'Hassan', role: 'Dishwasher', department: 'Kitchen',
+          compensation_type: 'hourly', rate_cents: 1_400 },
+        { first_name: 'Jessica', last_name: 'Williams', role: 'General Manager', department: 'Management',
+          compensation_type: 'salary', rate_cents: 5_000_000 },
+        { first_name: 'Emily', last_name: 'Davis', role: 'Server', department: 'Front of House',
+          compensation_type: 'hourly', rate_cents: 550 },
+        { first_name: 'Brandon', last_name: 'Lee', role: 'Server', department: 'Front of House',
+          compensation_type: 'hourly', rate_cents: 550 },
+        { first_name: 'Ashley', last_name: 'Martinez', role: 'Server', department: 'Front of House',
+          compensation_type: 'hourly', rate_cents: 550 },
+        { first_name: 'Tyler', last_name: 'Brown', role: 'Bartender', department: 'Bar',
+          compensation_type: 'hourly', rate_cents: 700 },
+        { first_name: 'Nicole', last_name: 'Taylor', role: 'Bartender', department: 'Bar',
+          compensation_type: 'hourly', rate_cents: 700 },
+        { first_name: 'Sophia', last_name: 'Anderson', role: 'Host', department: 'Front of House',
+          compensation_type: 'hourly', rate_cents: 1_400 },
+        { first_name: 'Marcus', last_name: 'Wilson', role: 'Busser', department: 'Front of House',
+          compensation_type: 'hourly', rate_cents: 1_200 }
+      ].freeze
+
+      def initialize(config: nil)
+        @config = config || GustoSandboxSimulator.configuration
+        @services = Services::Gusto::ServicesManager.new(config: @config)
+        @logger = @config.logger
+      end
+
+      # Create all employees in Gusto sandbox. Idempotent.
+      #
+      # @return [Hash] Summary { created: N, found: N, total: N }
+      def setup_all
+        logger.info "Setting up employees for company #{config.company_uuid}..."
+
+        existing = services.employee.list_employees
+        existing_names = existing.to_set { |e| "#{e['first_name']} #{e['last_name']}".downcase }
+
+        created = 0
+        found = 0
+
+        RESTAURANT_EMPLOYEES.each do |emp|
+          full_name = "#{emp[:first_name]} #{emp[:last_name]}".downcase
+
+          if existing_names.include?(full_name)
+            logger.debug "Employee already exists: #{emp[:first_name]} #{emp[:last_name]}"
+            found += 1
+          else
+            create_employee(emp)
+            created += 1
+          end
+
+          # Persist to local DB if connected
+          persist_employee(emp) if Database.connected?
+        end
+
+        summary = { created: created, found: found, total: RESTAURANT_EMPLOYEES.size }
+        logger.info "Employee setup complete: #{summary}"
+        summary
+      end
+
+      # Delete all locally tracked employees (does not remove from Gusto)
+      def delete_all
+        return unless Database.connected?
+
+        Models::Employee.delete_all
+        logger.info 'All local employee records deleted'
+      end
+
+      private
+
+      def create_employee(emp)
+        logger.info "Creating employee: #{emp[:first_name]} #{emp[:last_name]} (#{emp[:role]})"
+
+        services.employee.create_employee(
+          first_name: emp[:first_name],
+          last_name: emp[:last_name]
+        )
+      rescue ApiError => e
+        logger.warn "Failed to create #{emp[:first_name]} #{emp[:last_name]}: #{e.message}"
+      end
+
+      def persist_employee(emp)
+        bt = Models::BusinessType.find_by(key: config.business_type.to_s)
+        return unless bt
+
+        Models::Employee.find_or_create_by!(
+          first_name: emp[:first_name],
+          last_name: emp[:last_name],
+          business_type: bt
+        ) do |record|
+          record.role = emp[:role]
+          record.department = emp[:department]
+          record.compensation_type = emp[:compensation_type]
+          record.rate_cents = emp[:rate_cents]
+        end
+      rescue StandardError => e
+        logger.debug "Failed to persist employee locally: #{e.message}"
+      end
+    end
+  end
+end