SkyTab Sandbox Simulator

Ruby gem that simulates a SkyTab (Shift4) POS sandbox environment. Generates realistic restaurant orders, payments, and transaction data for testing SalesToBooks integrations.

Part of the TheOwnerStack POS simulator ecosystem alongside clover_sandbox_simulator, square_sandbox_simulator, and heartland_sandbox_simulator.

What It Does

Creates realistic menu categories, items, and tenders matching SkyTab's data model
Generates orders with meal-period distribution, revenue classes, and realistic payment mixes
Simulates the Shift4 Marketplace API v2 format (OAuth2, prices in cents)
Persists all API calls to an audit trail (api_requests table)
Supports 5 business types: restaurant, cafe/bakery, bar/nightclub, pizzeria, fine dining
Runs as a standalone CLI (no Rails dependency)

Installation

git clone https://github.com/dan1d/skytab_sandbox_simulator.git
cd skytab_sandbox_simulator
bundle install

Configuration

Copy .env.json.example to .env.json and fill in your SkyTab sandbox credentials:

{
  "default": {
    "SKYTAB_LOCATION_ID": "your-location-id",
    "SKYTAB_ACCESS_TOKEN": "your-oauth2-token",
    "SKYTAB_ENVIRONMENT": "sandbox"
  }
}

Usage

# Database setup
./bin/simulate db create
./bin/simulate db migrate
./bin/simulate db seed

# Generate data
./bin/simulate setup                # Create categories, items, tenders
./bin/simulate generate -n 50       # Generate 50 orders for today
./bin/simulate day                  # Full realistic day simulation
./bin/simulate full                 # Setup + day (everything)

# Inspect
./bin/simulate status               # Entity counts
./bin/simulate summary              # Daily revenue summary
./bin/simulate audit                # Recent API calls

# Reset
./bin/simulate db reset             # Drop, create, migrate, seed

API Format

Simulates the Shift4 Marketplace API:

Endpoint	Description
`GET /marketplace/v2/locations`	List merchant locations
`GET /pos/v2/{locationId}/menu`	Full menu (categories, items, taxes, modifiers)
`GET /pos/v2/{locationId}/tickets`	Open/closed tickets with items and payments
`POST /pos/v2/{locationId}/tickets`	Create a new ticket

Prices in US cents (1299 = $12.99). Tax rates divide by 10,000 (82500 = 8.25%).

Architecture

lib/skytab_sandbox_simulator/
  models/           # ActiveRecord models (UUID PKs, standalone)
  services/skytab/  # API service classes (HTTP client + audit logging)
  generators/       # EntityGenerator + OrderGenerator
  data/             # JSON seed data per business type
  db/migrate/       # PostgreSQL migrations
  db/factories/     # FactoryBot factories

Testing

bundle exec rspec                        # Run all tests
COVERAGE=true bundle exec rspec          # With SimpleCov report
bundle exec rubocop                      # Lint

Target: 100% line + 100% branch coverage.

License

MIT - TheOwnerStack LLC