square_sandbox_simulator 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 97c99937dc2438c125576c76a62612f9642a065d4be80f501680dc02bf2f3118
+  data.tar.gz: 99dc484286596d4a19ae911f9d5600dc784445323f94d7f87b61e33595d0d566
+SHA512:
+  metadata.gz: 1a4e5e86e18e94828bc3bda772e22fc243814779615b3f8eade31da9187524c412610fc75915f10519d2e4aa3af3a373dc775fd9ed9f856741c2102593b11ad2
+  data.tar.gz: fba074d8567aec60944de486d64e5e1576c47a4df91fdff97c9fb8f16a7bc0d3e4225aaa262cd8467e2b6bad8cdffd3ee2fda2d5b91264881ba253dfd74342bc

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 TheOwnerStack
+
+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,176 @@
+# Square Sandbox Simulator
+
+[![Gem Version](https://badge.fury.io/rb/square_sandbox_simulator.svg)](https://rubygems.org/gems/square_sandbox_simulator)
+
+Generate realistic POS data in your Square sandbox — categories, items, discounts, taxes, team members, customers, orders, payments, and refunds. Built for testing Square integrations without manual data entry.
+
+## Features
+
+- **9 business types** — restaurant, cafe/bakery, bar, food truck, fine dining, pizzeria, retail clothing, retail general, salon/spa
+- **1000+ menu items** with realistic prices via FactoryBot factories
+- **Realistic order simulation** — meal periods, dining options, tips, split payments, refunds
+- **Idempotent operations** — safe to re-run; entities matched by name, orders tracked by ID
+- **Full audit trail** — every API request/response persisted to PostgreSQL
+- **Timezone-aware** — fetches merchant timezone from Square API
+- **CLI + programmatic API** — use from terminal or integrate into your Rails app
+
+## Installation
+
+```bash
+gem install square_sandbox_simulator
+```
+
+Or add to your Gemfile:
+
+```ruby
+gem "square_sandbox_simulator"
+```
+
+## Quick Start
+
+### 1. Configure credentials
+
+Create a `.env.json` file:
+
+```json
+{
+  "DATABASE_URL": "postgres://localhost:5432/square_simulator_development",
+  "locations": [
+    {
+      "SQUARE_LOCATION_ID": "YOUR_LOCATION_ID",
+      "SQUARE_ACCESS_TOKEN": "YOUR_SANDBOX_ACCESS_TOKEN",
+      "SQUARE_LOCATION_NAME": "Test Location"
+    }
+  ]
+}
+```
+
+### 2. Set up database (optional, for audit trail)
+
+```bash
+simulate db create
+simulate db migrate
+simulate db seed --type restaurant
+```
+
+### 3. Create entities in Square
+
+```bash
+simulate setup --business_type restaurant
+```
+
+This creates categories, items, discounts, tax rates, team members, and customers in your Square sandbox.
+
+### 4. Generate orders
+
+```bash
+# Full realistic day (40-120 orders based on day of week)
+simulate day
+
+# Specific count
+simulate generate -n 50
+
+# Busy day (2x volume)
+simulate day -x 2.0
+```
+
+## CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `simulate setup` | Create entities (categories, items, discounts, taxes, team, customers) |
+| `simulate generate -n N` | Generate N orders for today |
+| `simulate day [-x MULT]` | Generate realistic full day of orders |
+| `simulate status` | Show entity counts |
+| `simulate orders [-l N]` | List recent orders |
+| `simulate summary [-d DATE]` | Daily summary (requires DB) |
+| `simulate delete --confirm` | Delete all entities |
+| `simulate locations` | List configured locations |
+| `simulate db create` | Create PostgreSQL database |
+| `simulate db migrate` | Run migrations |
+| `simulate db seed` | Seed business type data |
+| `simulate db reset --confirm` | Drop, create, migrate, seed |
+
+**Global flags:** `-v` (verbose), `-l LOCATION_ID`, `-i INDEX` (location index)
+
+## Programmatic Usage
+
+```ruby
+require "square_sandbox_simulator"
+
+# Configure
+SquareSandboxSimulator.configure do |config|
+  config.location_id = "YOUR_LOCATION_ID"
+  config.access_token = "YOUR_ACCESS_TOKEN"
+  config.business_type = :restaurant
+end
+
+# Set up entities
+generator = SquareSandboxSimulator::Generators::EntityGenerator.new(
+  business_type: :restaurant
+)
+result = generator.setup_all
+# => { categories: [...], items: [...], discounts: [...], tax_rates: [...], ... }
+
+# Generate orders
+order_gen = SquareSandboxSimulator::Generators::OrderGenerator.new(
+  refund_percentage: 5
+)
+orders = order_gen.generate_realistic_day(multiplier: 1.0)
+# or
+orders = order_gen.generate_for_date(Date.today, count: 50)
+```
+
+## Order Simulation Details
+
+Orders follow realistic restaurant patterns:
+
+| Meal Period | Hours | Weight | Avg Items | Avg Party |
+|-------------|-------|--------|-----------|-----------|
+| Breakfast | 7-10 | 15% | 3-6 | 1-3 |
+| Lunch | 11-14 | 30% | 3-7 | 1-4 |
+| Happy Hour | 15-17 | 10% | 3-6 | 2-5 |
+| Dinner | 17-21 | 35% | 4-9 | 2-6 |
+| Late Night | 21-23 | 10% | 3-6 | 1-3 |
+
+**Daily volume:** weekday 40-60, friday 70-100, saturday 80-120, sunday 50-80
+
+**Payment mix:** 75% card, 25% cash. Tips: 15-25% dine-in, 0-15% takeout, 10-20% delivery.
+
+**Refunds:** 5% of orders by default (configurable).
+
+## Database Schema
+
+All tables use UUID primary keys. The gem works without a database — audit logging is optional and non-blocking.
+
+| Table | Purpose |
+|-------|---------|
+| `business_types` | 9 business types with order profiles |
+| `categories` | Menu categories per business type |
+| `items` | Menu items with prices (cents) |
+| `simulated_orders` | Generated order records |
+| `simulated_payments` | Payment records per order |
+| `api_requests` | Full API audit trail (request + response) |
+| `daily_summaries` | Aggregated daily metrics |
+
+## Services
+
+The gem wraps 5 Square API service areas:
+
+- **CatalogService** — categories, items, discounts, taxes (CRUD + batch)
+- **OrderService** — create, search, calculate orders
+- **PaymentService** — card payments, cash payments, refunds
+- **CustomerService** — create/list customers (20 default)
+- **TeamService** — create/search team members (5 default)
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec          # 575 tests, 100% branch coverage
+bundle exec rubocop        # 0 offenses
+```
+
+## License
+
+MIT License. See [LICENSE.txt](LICENSE.txt).

data/bin/simulate

@@ -0,0 +1,388 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "square_sandbox_simulator"
+require "thor"
+
+module SquareSandboxSimulator
+  # Command-line interface for Square Sandbox Simulator
+  class CLI < Thor
+    class_option :verbose, type: :boolean, aliases: "-v", desc: "Enable verbose logging"
+    class_option :location, type: :string, aliases: "-l", desc: "Location ID to use (from .env.json)"
+    class_option :location_index, type: :numeric, aliases: "-i", desc: "Location index to use (0-based, from .env.json)"
+
+    desc "locations", "List available locations from .env.json"
+    def locations
+      puts "Square Sandbox Simulator - Available Locations"
+      puts "=" * 60
+
+      config = SquareSandboxSimulator.configuration
+      locs = config.available_locations
+
+      if locs.empty?
+        puts "No locations found in .env.json"
+        return
+      end
+
+      puts "\n#{"Index".ljust(6)} #{"Location ID".ljust(20)} Name"
+      puts "-" * 60
+
+      locs.each_with_index do |loc, idx|
+        puts "#{idx.to_s.ljust(6)} #{(loc[:id] || "N/A").ljust(20)} #{loc[:name] || "N/A"}"
+      end
+
+      puts "\nUse: simulate <command> -i <index> or -l <location_id>"
+    end
+
+    desc "setup", "Set up entities (categories, items, discounts, taxes, team members, customers)"
+    option :business_type, type: :string, default: "restaurant", desc: "Business type (restaurant, retail_clothing, cafe_bakery, etc.)"
+    def setup
+      configure_logging
+
+      puts "Square Sandbox Simulator - Entity Setup"
+      puts "=" * 50
+
+      generator = Generators::EntityGenerator.new(business_type: options[:business_type].to_sym)
+      generator.setup_all
+
+      puts "\nSetup complete!"
+    end
+
+    desc "generate", "Generate orders for today"
+    option :count, type: :numeric, aliases: "-n", desc: "Number of orders to generate"
+    option :refund_percentage, type: :numeric, aliases: "-r", default: 5,
+                               desc: "Percentage of orders to refund (0-100, default 5)"
+    def generate
+      configure_logging
+
+      puts "Square Sandbox Simulator - Order Generation"
+      puts "=" * 50
+
+      generator = Generators::OrderGenerator.new(refund_percentage: options[:refund_percentage])
+      count = options[:count]
+
+      orders = generator.generate_today(count: count)
+
+      puts "\nGenerated #{orders.size} orders!"
+    end
+
+    desc "day", "Generate a realistic full day of operations"
+    option :multiplier, type: :numeric, aliases: "-x", default: 1.0, desc: "Order multiplier (0.5 = slow day, 2.0 = busy day)"
+    option :refund_percentage, type: :numeric, aliases: "-r", default: 5,
+                               desc: "Percentage of orders to refund (0-100, default 5)"
+    def day
+      configure_logging
+
+      puts "Square Sandbox Simulator - Realistic Day"
+      puts "=" * 50
+
+      generator = Generators::OrderGenerator.new(refund_percentage: options[:refund_percentage])
+      orders = generator.generate_realistic_day(multiplier: options[:multiplier])
+
+      puts "\nGenerated #{orders.size} orders!"
+    end
+
+    desc "status", "Show current Square location status"
+    def status
+      configure_logging
+
+      puts "Square Sandbox Simulator - Status"
+      puts "=" * 50
+
+      services = Services::Square::ServicesManager.new
+
+      categories = services.catalog.list_catalog(types: "CATEGORY")
+      items = services.catalog.list_catalog(types: "ITEM")
+      discounts = services.catalog.list_catalog(types: "DISCOUNT")
+      taxes = services.catalog.list_catalog(types: "TAX")
+      customers = services.customer.list_customers
+      team_members = services.team.search_team_members
+
+      puts "\nEntity Counts:"
+      puts "   Categories:    #{categories.size}"
+      puts "   Items:         #{items.size}"
+      puts "   Discounts:     #{discounts.size}"
+      puts "   Tax Rates:     #{taxes.size}"
+      puts "   Team Members:  #{team_members.size}"
+      puts "   Customers:     #{customers.size}"
+
+      if categories.any?
+        puts "\nCategories:"
+        categories.each { |c| puts "   - #{c.dig("category_data", "name")}" }
+      end
+
+      if taxes.any?
+        puts "\nTax Rates:"
+        taxes.each do |t|
+          td = t["tax_data"] || {}
+          puts "   - #{td["name"]}: #{td["percentage"]}%"
+        end
+      end
+
+      return unless discounts.any?
+
+      puts "\nDiscounts:"
+      discounts.each do |d|
+        dd = d["discount_data"] || {}
+        type = dd["discount_type"] || "N/A"
+        value = if dd["percentage"]
+                  "#{dd["percentage"]}%"
+                elsif dd.dig("amount_money", "amount")
+                  "$#{format("%.2f", dd["amount_money"]["amount"] / 100.0)}"
+                else
+                  "N/A"
+                end
+        puts "   - #{dd["name"]} (#{type}: #{value})"
+      end
+    end
+
+    desc "orders", "List recent orders"
+    option :limit, type: :numeric, aliases: "-l", default: 20, desc: "Number of orders to show"
+    def orders
+      configure_logging
+
+      puts "Square Sandbox Simulator - Recent Orders"
+      puts "=" * 50
+
+      services = Services::Square::ServicesManager.new
+      recent = services.order.search_orders
+
+      if recent.empty?
+        puts "No orders found."
+        puts "\nRun 'simulate generate' to create orders."
+        return
+      end
+
+      # Limit display
+      display = recent.first(options[:limit])
+
+      puts "\nFound #{recent.size} orders (showing #{display.size}):\n\n"
+
+      total_revenue = 0
+      display.each do |order|
+        total = order.dig("total_money", "amount") || 0
+        total_revenue += total
+        state = order["state"] || "unknown"
+        order["created_at"] || "N/A"
+
+        state_marker = case state
+                       when "OPEN" then "[OPEN]"
+                       when "COMPLETED" then "[PAID]"
+                       else "[#{state}]"
+                       end
+
+        items_count = (order["line_items"] || []).size
+        puts "#{state_marker.ljust(12)} $#{format("%.2f", total / 100.0)} | #{items_count} items | #{order["id"]}"
+      end
+
+      puts "\n#{"-" * 50}"
+      puts "Total: $#{format("%.2f", total_revenue / 100.0)} across #{display.size} orders"
+    end
+
+    desc "summary", "Show daily summary for current location"
+    option :date, type: :string, aliases: "-d", desc: "Date (YYYY-MM-DD, default: today)"
+    def summary
+      configure_logging
+      require_db_connection!
+
+      date = options[:date] ? Date.parse(options[:date]) : Date.today
+      location_id = SquareSandboxSimulator.configuration.location_id
+
+      s = Models::DailySummary.for_merchant(location_id).on_date(date).first
+
+      unless s
+        puts "No summary found for location #{location_id} on #{date}."
+        puts "Run 'simulate generate' to create orders first."
+        return
+      end
+
+      puts "Daily Summary: #{date}"
+      puts "=" * 50
+      puts "  Location:      #{location_id}"
+      puts "  Orders:        #{s.order_count}"
+      puts "  Payments:      #{s.payment_count}"
+      puts "  Refunds:       #{s.refund_count}"
+      puts ""
+      puts "  Revenue:       #{format_cents(s.total_revenue)}"
+      puts "  Tax:           #{format_cents(s.total_tax)}"
+      puts "  Tips:          #{format_cents(s.total_tips)}"
+      puts "  Discounts:     #{format_cents(s.total_discounts)}"
+
+      breakdown = s.breakdown || {}
+
+      if breakdown["by_meal_period"]&.any?
+        puts ""
+        puts "  By Meal Period:"
+        breakdown["by_meal_period"].each do |period, count|
+          rev = breakdown.dig("revenue_by_meal_period", period) || 0
+          puts "    #{period.ljust(15)} #{count.to_s.rjust(3)} orders  #{format_cents(rev)}"
+        end
+      end
+
+      if breakdown["by_dining_option"]&.any?
+        puts ""
+        puts "  By Dining Option:"
+        breakdown["by_dining_option"].each do |opt, count|
+          rev = breakdown.dig("revenue_by_dining_option", opt) || 0
+          puts "    #{opt.ljust(15)} #{count.to_s.rjust(3)} orders  #{format_cents(rev)}"
+        end
+      end
+
+      return unless breakdown["by_tender"]&.any?
+
+      puts ""
+      puts "  By Tender:"
+      breakdown["by_tender"].each do |tender, count|
+        puts "    #{tender.ljust(20)} #{count} payments"
+      end
+    end
+
+    desc "delete", "Delete all entities (use with caution!)"
+    option :confirm, type: :boolean, desc: "Confirm deletion"
+    def delete
+      unless options[:confirm]
+        puts "This will delete ALL entities from Square!"
+        puts "   Run with --confirm to proceed."
+        return
+      end
+
+      configure_logging
+
+      puts "Deleting all entities..."
+
+      generator = Generators::EntityGenerator.new
+      generator.delete_all
+
+      puts "\nAll entities deleted!"
+    end
+
+    # ============================================
+    # Database Management Commands (db: namespace)
+    # ============================================
+
+    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 = SquareSandboxSimulator::Database
+        url = db.database_url
+        puts "Creating database..."
+        db.create!(url)
+        puts "Done."
+      rescue SquareSandboxSimulator::Error => e
+        puts "Error: #{e.message}"
+        exit 1
+      end
+
+      desc "migrate", "Run pending migrations"
+      def migrate
+        db = SquareSandboxSimulator::Database
+        url = db.database_url
+        puts "Connecting and running migrations..."
+        db.connect!(url)
+        db.migrate!
+        puts "Done."
+      rescue SquareSandboxSimulator::Error => e
+        puts "Error: #{e.message}"
+        exit 1
+      end
+
+      desc "seed", "Seed the database with realistic data via FactoryBot"
+      option :type, type: :string, desc: "Business type to seed (e.g. restaurant, retail_clothing). Seeds all if omitted."
+      def seed
+        db = SquareSandboxSimulator::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[:categories]} categories, #{result[:items]} items"
+        puts "  (#{result[:created]} created, #{result[:found]} already existed)"
+      rescue SquareSandboxSimulator::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 to seed (e.g. restaurant). Seeds all if omitted."
+      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 = SquareSandboxSimulator::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[:categories]} categories, #{result[:items]} items"
+        puts "Done."
+      rescue SquareSandboxSimulator::Error => e
+        puts "Error: #{e.message}"
+        exit 1
+      end
+    }
+
+    desc "version", "Show version"
+    def version
+      puts "Square Sandbox Simulator v#{SquareSandboxSimulator::VERSION}"
+    end
+
+    private
+
+    def format_cents(cents)
+      "$#{format("%.2f", (cents || 0) / 100.0)}"
+    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
+      config = SquareSandboxSimulator.configuration
+
+      config.logger.level = if options[:verbose]
+                              Logger::DEBUG
+                            else
+                              Logger::INFO
+                            end
+
+      # Load specific location if specified
+      if options[:location]
+        config.load_location(location_id: options[:location])
+      elsif options[:location_index]
+        config.load_location(index: options[:location_index])
+      end
+
+      puts "Using location: #{config.location_name || config.location_id}"
+    end
+  end
+end
+
+SquareSandboxSimulator::CLI.start(ARGV)