gusto_sandbox_simulator 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 05fbbfad3d8f931e8543db90bf01c8a4967262fb87ab7322c286d6d6ff654461
+  data.tar.gz: 9bb1181850ca02294f88d02e4568bd4eca7abdd34e105a7d9fc9968e81af5936
+SHA512:
+  metadata.gz: 8aa21e1718afeafe1c6b5ba02d656164dd5abc7d25fcb62fc0bbb9660c2b3002d8b58cf5da19483dddade69e76c1337e4f64ec649d0d9205979c549e75a85c74
+  data.tar.gz: 433d08cd49f48026d42cad09eeb38e7afe7d76ee146c261cf04876a85219b5947a4884bffb4c42be7a0546cfa73b47b48619c5ccfb508b652917210fab9846a0

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Dan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,94 @@
+# Gusto Sandbox Simulator
+
+Ruby gem that generates realistic payroll data (employees, payroll runs, compensations) in [Gusto](https://gusto.com) sandbox environments for testing and development.
+
+Part of the [SalesToBooks](https://salestobooks.com) POS simulator ecosystem alongside [`clover_sandbox_simulator`](https://github.com/dan1d/clover_sandbox_simulator) and [`square_sandbox_simulator`](https://github.com/dan1d/square_sandbox_simulator).
+
+## Installation
+
+```bash
+gem install gusto_sandbox_simulator
+```
+
+Or add to your Gemfile:
+
+```ruby
+gem "gusto_sandbox_simulator"
+```
+
+## Configuration
+
+Create a `.env.json` file in the project root:
+
+```json
+{
+  "DATABASE_URL": "postgres://user:pass@localhost/gusto_sandbox",
+  "companies": [
+    {
+      "GUSTO_COMPANY_UUID": "abc-123",
+      "GUSTO_ACCESS_TOKEN": "your-token",
+      "GUSTO_COMPANY_NAME": "Demo Restaurant"
+    }
+  ]
+}
+```
+
+Or set environment variables directly:
+
+| Variable | Default | Required |
+|----------|---------|----------|
+| `GUSTO_COMPANY_UUID` | -- | Yes |
+| `GUSTO_ACCESS_TOKEN` | -- | Yes |
+| `GUSTO_ENVIRONMENT` | `demo` | No |
+| `GUSTO_API_VERSION` | `2024-04-01` | No |
+| `BUSINESS_TYPE` | `restaurant` | No |
+| `DATABASE_URL` | -- | No |
+
+## CLI Usage
+
+```bash
+# Employee management
+simulate setup                  # Create 14 restaurant employees in Gusto sandbox
+simulate status                 # Show company info, employee/payroll counts
+simulate delete --confirm       # Delete local employee records
+
+# Payroll processing
+simulate process                # Process unprocessed payrolls (fill hours, submit)
+simulate sync -s 2026-01-01     # Sync processed payrolls to local DB
+
+# Utilities
+simulate companies              # List companies from .env.json
+simulate payrolls -p            # List processed payrolls
+simulate version                # Show version
+
+# Database management
+simulate db create              # Create PostgreSQL database
+simulate db migrate             # Run migrations
+simulate db seed                # Seed with restaurant employee data
+simulate db reset --confirm     # Drop, create, migrate, seed
+```
+
+**Global flags:** `-v` (verbose), `-c UUID` (company), `-i INDEX` (company index)
+
+## Default Restaurant Roster
+
+14 employees across 4 departments:
+
+| Department | Roles | Compensation |
+|-----------|-------|-------------|
+| Kitchen | Head Chef, Sous Chef, Line Cook x2, Prep Cook, Dishwasher | $14-55k |
+| Management | General Manager | $50k salary |
+| Front of House | Server x3, Host, Busser | $5.50-14/hr |
+| Bar | Bartender x2 | $7/hr + tips |
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec       # Run tests
+bundle exec rubocop     # Lint
+```
+
+## License
+
+MIT License. See [LICENSE.txt](LICENSE.txt).

data/bin/simulate

@@ -0,0 +1,309 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "gusto_sandbox_simulator"
+require "thor"
+
+module GustoSandboxSimulator
+  # Command-line interface for Gusto Sandbox Simulator
+  class CLI < Thor
+    class_option :verbose, type: :boolean, aliases: "-v", desc: "Enable verbose logging"
+    class_option :company, type: :string, aliases: "-c", desc: "Company UUID to use (from .env.json)"
+    class_option :company_index, type: :numeric, aliases: "-i", desc: "Company index to use (0-based)"
+
+    desc "companies", "List available companies from .env.json"
+    def companies
+      puts "Gusto Sandbox Simulator - Available Companies"
+      puts "=" * 60
+
+      config = GustoSandboxSimulator.configuration
+      comps = config.available_companies
+
+      if comps.empty?
+        puts "No companies found in .env.json"
+        return
+      end
+
+      puts "\n#{"Index".ljust(6)} #{"Company UUID".ljust(40)} Name"
+      puts "-" * 60
+
+      comps.each_with_index do |comp, idx|
+        puts "#{idx.to_s.ljust(6)} #{(comp[:uuid] || "N/A").ljust(40)} #{comp[:name] || "N/A"}"
+      end
+
+      puts "\nUse: simulate <command> -i <index> or -c <company_uuid>"
+    end
+
+    desc "setup", "Set up employees in the Gusto sandbox company"
+    def setup
+      configure_logging
+
+      puts "Gusto Sandbox Simulator - Employee Setup"
+      puts "=" * 50
+
+      generator = Generators::EntityGenerator.new
+      result = generator.setup_all
+
+      puts "\nSetup complete!"
+      puts "  Created: #{result[:created]}"
+      puts "  Found:   #{result[:found]}"
+      puts "  Total:   #{result[:total]}"
+    end
+
+    desc "process", "Process unprocessed payrolls (fill compensations and submit)"
+    def process
+      configure_logging
+
+      puts "Gusto Sandbox Simulator - Process Payrolls"
+      puts "=" * 50
+
+      generator = Generators::PayrollGenerator.new
+      result = generator.process_unprocessed
+
+      puts "\nPayroll processing complete!"
+      puts "  Processed: #{result[:processed]}"
+      puts "  Skipped:   #{result[:skipped]}"
+      puts "  Errors:    #{result[:errors].size}"
+
+      result[:errors].each { |e| puts "    - #{e}" } if result[:errors].any?
+    end
+
+    desc "sync", "Sync processed payrolls from Gusto to local database"
+    option :start_date, type: :string, aliases: "-s", desc: "Start date (YYYY-MM-DD)"
+    option :end_date, type: :string, aliases: "-e", desc: "End date (YYYY-MM-DD)"
+    def sync
+      configure_logging
+      require_db_connection!
+
+      puts "Gusto Sandbox Simulator - Sync Payrolls"
+      puts "=" * 50
+
+      generator = Generators::PayrollGenerator.new
+      start_date = options[:start_date] ? Date.parse(options[:start_date]) : nil
+      end_date = options[:end_date] ? Date.parse(options[:end_date]) : nil
+
+      payrolls = generator.sync_processed(start_date: start_date, end_date: end_date)
+
+      puts "\nSynced #{payrolls.size} processed payrolls"
+
+      payrolls.each do |p|
+        period = p["pay_period"] || {}
+        totals = p["totals"] || {}
+        puts "  #{period["start_date"]} - #{period["end_date"]}: " \
+             "Gross $#{totals["gross_pay"]} | Net $#{totals["net_pay"]} | " \
+             "#{(p["employee_compensations"] || []).size} employees"
+      end
+    end
+
+    desc "status", "Show current Gusto company status"
+    def status
+      configure_logging
+
+      puts "Gusto Sandbox Simulator - Status"
+      puts "=" * 50
+
+      services = Services::Gusto::ServicesManager.new
+
+      company = services.company.get_company
+      employees = services.employee.list_employees
+      payrolls = services.payroll.list_payrolls
+
+      puts "\nCompany: #{company["name"] || company["trade_name"] || "N/A"}"
+      puts "  UUID:       #{config.company_uuid}"
+      puts "  EIN:        #{company["ein"] || "N/A"}"
+      puts ""
+      puts "Entity Counts:"
+      puts "  Employees:     #{employees.size}"
+      puts "  Payroll Runs:  #{payrolls.size}"
+
+      processed = payrolls.count { |p| p["processed"] }
+      unprocessed = payrolls.size - processed
+      puts "    Processed:   #{processed}"
+      puts "    Unprocessed: #{unprocessed}"
+
+      return unless employees.any?
+
+      puts "\nEmployees:"
+      employees.each do |emp|
+        puts "  - #{emp["first_name"]} #{emp["last_name"]}"
+      end
+    end
+
+    desc "payrolls", "List recent payrolls"
+    option :limit, type: :numeric, aliases: "-n", default: 10, desc: "Number to show"
+    option :processed, type: :boolean, aliases: "-p", desc: "Only show processed"
+    def payrolls
+      configure_logging
+
+      puts "Gusto Sandbox Simulator - Payrolls"
+      puts "=" * 50
+
+      services = Services::Gusto::ServicesManager.new
+      runs = if options[:processed]
+               services.payroll.processed_payrolls
+             else
+               services.payroll.list_payrolls
+             end
+
+      if runs.empty?
+        puts "No payrolls found."
+        return
+      end
+
+      display = runs.first(options[:limit])
+      puts "\nFound #{runs.size} payrolls (showing #{display.size}):\n\n"
+
+      display.each do |p|
+        period = p["pay_period"] || {}
+        totals = p["totals"] || {}
+        status_tag = p["processed"] ? "[PROCESSED]" : "[PENDING]  "
+        emps = (p["employee_compensations"] || []).size
+        puts "#{status_tag} #{period["start_date"]} - #{period["end_date"]} | " \
+             "Gross: $#{totals["gross_pay"] || "0.00"} | #{emps} employees"
+      end
+    end
+
+    desc "delete", "Delete all local employee records"
+    option :confirm, type: :boolean, desc: "Confirm deletion"
+    def delete
+      unless options[:confirm]
+        puts "This will delete all LOCAL employee records."
+        puts "Run with --confirm to proceed."
+        return
+      end
+
+      configure_logging
+      require_db_connection!
+
+      generator = Generators::EntityGenerator.new
+      generator.delete_all
+
+      puts "All local records deleted."
+    end
+
+    # Database management subcommand
+    desc "db SUBCOMMAND", "Database management commands"
+    subcommand "db", Class.new(Thor) {
+      def self.banner(task, _namespace = true, _subcommand = true)
+        "simulate db #{task.usage}"
+      end
+
+      namespace "db"
+
+      desc "create", "Create the PostgreSQL database"
+      def create
+        db = GustoSandboxSimulator::Database
+        url = db.database_url
+        puts "Creating database..."
+        db.create!(url)
+        puts "Done."
+      rescue GustoSandboxSimulator::Error => e
+        puts "Error: #{e.message}"
+        exit 1
+      end
+
+      desc "migrate", "Run pending migrations"
+      def migrate
+        db = GustoSandboxSimulator::Database
+        url = db.database_url
+        puts "Connecting and running migrations..."
+        db.connect!(url)
+        db.migrate!
+        puts "Done."
+      rescue GustoSandboxSimulator::Error => e
+        puts "Error: #{e.message}"
+        exit 1
+      end
+
+      desc "seed", "Seed the database with restaurant employee data"
+      option :type, type: :string, desc: "Business type (default: restaurant)"
+      def seed
+        db = GustoSandboxSimulator::Database
+        url = db.database_url
+        puts "Connecting and seeding..."
+        db.connect!(url)
+        bt = options[:type]&.to_sym
+        result = db.seed!(business_type: bt)
+        puts "Seeded: #{result[:business_types]} business types, #{result[:employees]} employees"
+        puts "  (#{result[:created]} created, #{result[:found]} already existed)"
+      rescue GustoSandboxSimulator::Error => e
+        puts "Error: #{e.message}"
+        exit 1
+      end
+
+      desc "reset", "Drop, create, migrate, and seed the database"
+      option :type, type: :string, desc: "Business type (default: restaurant)"
+      option :confirm, type: :boolean, desc: "Confirm destructive operation"
+      def reset
+        unless options[:confirm]
+          puts "This will DROP and recreate the database. All data will be lost."
+          puts "Run with --confirm to proceed."
+          return
+        end
+
+        db = GustoSandboxSimulator::Database
+        url = db.database_url
+
+        puts "Dropping database..."
+        db.drop!(url)
+
+        puts "Creating database..."
+        db.create!(url)
+
+        puts "Connecting and running migrations..."
+        db.connect!(url)
+        db.migrate!
+
+        puts "Seeding..."
+        bt = options[:type]&.to_sym
+        result = db.seed!(business_type: bt)
+        puts "Seeded: #{result[:business_types]} business types, #{result[:employees]} employees"
+        puts "Done."
+      rescue GustoSandboxSimulator::Error => e
+        puts "Error: #{e.message}"
+        exit 1
+      end
+    }
+
+    desc "version", "Show version"
+    def version
+      puts "Gusto Sandbox Simulator v#{GustoSandboxSimulator::VERSION}"
+    end
+
+    private
+
+    def config
+      GustoSandboxSimulator.configuration
+    end
+
+    def require_db_connection!
+      url = Database.database_url
+      Database.connect!(url) unless Database.connected?
+    rescue Error => e
+      puts "Database not available: #{e.message}"
+      puts "Run 'simulate db create && simulate db migrate' first."
+      exit 1
+    end
+
+    def configure_logging
+      cfg = GustoSandboxSimulator.configuration
+
+      cfg.logger.level = if options[:verbose]
+                           Logger::DEBUG
+                         else
+                           Logger::INFO
+                         end
+
+      if options[:company]
+        cfg.load_company(company_uuid: options[:company])
+      elsif options[:company_index]
+        cfg.load_company(index: options[:company_index])
+      end
+
+      puts "Using company: #{cfg.company_uuid}"
+    end
+  end
+end
+
+GustoSandboxSimulator::CLI.start(ARGV)

data/lib/gusto_sandbox_simulator/configuration.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+module GustoSandboxSimulator
+  class Configuration
+    attr_accessor :company_uuid, :access_token, :environment, :api_version,
+                  :log_level, :database_url, :business_type
+
+    # Gusto API base URLs
+    DEMO_URL = 'https://api.gusto-demo.com/'
+    PRODUCTION_URL = 'https://api.gusto.com/'
+
+    # Default API version header
+    DEFAULT_API_VERSION = '2024-04-01'
+
+    # Path to companies JSON file
+    COMPANIES_FILE = File.join(File.dirname(__FILE__), '..', '..', '.env.json')
+
+    def initialize
+      @company_uuid  = ENV.fetch('GUSTO_COMPANY_UUID', nil)
+      @access_token  = ENV.fetch('GUSTO_ACCESS_TOKEN', nil)
+      @environment   = resolve_environment(ENV.fetch('GUSTO_ENVIRONMENT', 'demo'))
+      @api_version   = ENV.fetch('GUSTO_API_VERSION', DEFAULT_API_VERSION)
+      @log_level     = parse_log_level(ENV.fetch('LOG_LEVEL', 'INFO'))
+      @business_type = ENV.fetch('BUSINESS_TYPE', 'restaurant').to_sym
+      @database_url  = ENV.fetch('DATABASE_URL', nil)
+
+      # Load from .env.json if company_uuid not set in ENV
+      load_from_companies_file if @company_uuid.nil? || @company_uuid.empty?
+    end
+
+    # Load configuration for a specific company from .env.json
+    #
+    # @param company_uuid [String, nil] Company UUID to load (nil for first company)
+    # @param index [Integer, nil] Index of company in the list (0-based)
+    # @return [self]
+    def load_company(company_uuid: nil, index: nil)
+      companies = load_companies_file
+      return self if companies.empty?
+
+      company = if company_uuid
+                  companies.find { |c| c['GUSTO_COMPANY_UUID'] == company_uuid }
+                elsif index
+                  companies[index]
+                else
+                  companies.first
+                end
+
+      if company
+        apply_company_config(company)
+        logger.info "Loaded company: #{@company_uuid}"
+      else
+        logger.warn "Company not found: #{company_uuid || "index #{index}"}"
+      end
+
+      self
+    end
+
+    # List all available companies from .env.json
+    #
+    # @return [Array<Hash>] Array of company configs
+    def available_companies
+      load_companies_file.map do |c|
+        {
+          uuid: c['GUSTO_COMPANY_UUID'],
+          name: c['GUSTO_COMPANY_NAME']
+        }
+      end
+    end
+
+    def validate!
+      raise ConfigurationError, 'GUSTO_COMPANY_UUID is required' if company_uuid.nil? || company_uuid.empty?
+      raise ConfigurationError, 'GUSTO_ACCESS_TOKEN is required' if access_token.nil? || access_token.empty?
+
+      true
+    end
+
+    def logger
+      @logger ||= Logger.new($stdout).tap do |log|
+        log.level = @log_level
+        log.formatter = proc do |severity, datetime, _progname, msg|
+          timestamp = datetime.strftime('%Y-%m-%d %H:%M:%S')
+          "[#{timestamp}] #{severity.ljust(5)} | #{msg}\n"
+        end
+      end
+    end
+
+    # Return the configured database URL from .env.json.
+    #
+    # @return [String, nil] The DATABASE_URL or nil
+    def self.database_url_from_file
+      return nil unless File.exist?(COMPANIES_FILE)
+
+      data = JSON.parse(File.read(COMPANIES_FILE))
+      return nil if data.is_a?(Array)
+
+      data['DATABASE_URL']
+    rescue JSON::ParserError
+      nil
+    end
+
+    private
+
+    def load_from_companies_file
+      companies = load_companies_file
+      return if companies.empty?
+
+      apply_company_config(companies.first)
+    end
+
+    # Parse .env.json, supporting both the legacy array format and the
+    # new object format: { "DATABASE_URL": "...", "companies": [...] }
+    def load_companies_file
+      return [] unless File.exist?(COMPANIES_FILE)
+
+      data = JSON.parse(File.read(COMPANIES_FILE))
+      return data if data.is_a?(Array)
+
+      data.fetch('companies', [])
+    rescue JSON::ParserError => e
+      warn "Failed to parse #{COMPANIES_FILE}: #{e.message}"
+      []
+    end
+
+    def apply_company_config(company)
+      @company_uuid = company['GUSTO_COMPANY_UUID']
+      @access_token = company['GUSTO_ACCESS_TOKEN'] unless company['GUSTO_ACCESS_TOKEN'].to_s.empty?
+    end
+
+    def resolve_environment(env)
+      case env.to_s.downcase
+      when 'production', 'prod'
+        PRODUCTION_URL
+      else
+        DEMO_URL
+      end
+    end
+
+    def parse_log_level(level)
+      case level.to_s.upcase
+      when 'DEBUG' then Logger::DEBUG
+      when 'WARN'  then Logger::WARN
+      when 'ERROR' then Logger::ERROR
+      when 'FATAL' then Logger::FATAL
+      else Logger::INFO
+      end
+    end
+  end
+end