Heartland Sandbox Simulator

Ruby gem that simulates a Heartland Genius Restaurant POS (HRPOS) 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 skytab_sandbox_simulator.

What It Does

Creates realistic menu categories, items, and tenders matching Heartland's data model
Generates tickets with guest counts, revenue centers, and realistic payment mixes
Simulates the HRPOS API format (Bearer token, Swagger-documented)
Daily summary endpoint — pre-aggregated KPIs (sales, ticket averages, guest counts) unique to Heartland
Persists all API calls to an audit trail (api_requests table)
Supports 5 business types: restaurant, cafe/bakery, bar/nightclub, pizzeria, fine dining
6 revenue centers: Main Dining, Bar, Patio, Private Dining, Takeout, Catering
9 tender types: Cash, Visa, Mastercard, Amex, Discover, Debit, Gift Card, House Account, Check
Runs as a standalone CLI (no Rails dependency)

Installation

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

Configuration

Set environment variables or create .env.json:

{
  "default": {
    "HEARTLAND_LOCATION_ID": "LOC001",
    "HEARTLAND_ACCESS_TOKEN": "your-api-key",
    "HEARTLAND_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 tickets for today
./bin/simulate day                  # Full realistic day simulation

# Inspect
./bin/simulate status               # Entity counts
./bin/simulate tickets              # Recent tickets with totals
./bin/simulate summary              # Daily KPI summary (Heartland-specific)

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

API Format

Simulates the Heartland Restaurant POS (HRPOS) API:

Endpoint	Description
`GET /v2/locations`	List merchant locations
`GET /v2/locations/{id}/menu`	Menu with categories, items, modifiers
`GET /v2/locations/{id}/tickets`	Tickets (CRUD + search)
`GET /v2/locations/{id}/daily-summary?date=YYYY-MM-DD`	Pre-aggregated daily KPIs

Daily summary includes: total sales, ticket count, average ticket, guest count, average per guest, sales by category, sales by tender, total tax, total tips, total discounts.

Architecture

lib/heartland_sandbox_simulator/
  models/              # ActiveRecord models (UUID PKs, standalone)
  services/heartland/  # 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