clover_sandbox_simulator 1.5.0 → 1.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 71bf747b5954c1ed19674690e6bd87b50565e6134d271578d0ca555107c5768b
-  data.tar.gz: a6e887ab824caa87d013d98fefc58040d0668849b05f60694375d14202792ad5
+  metadata.gz: 9f684b2338da3333984bdf63a1abb0ff18112be9cd5e210e4f2dc3ded17b554f
+  data.tar.gz: 193f13605291b79ead034124638c03fc863089e364f73bb1cb4f829281ce00ae
 SHA512:
-  metadata.gz: 01fbdfe1c3deb2506c2c49b8f800e4636b9c34150047276f034b85a4f51a60681feb0d6374abe2682481de2d44410e337a44b4f5b9a84ef93ebc0003e396d801
-  data.tar.gz: 845682838c47593dbfff5face1418d6a1359224bfbd1c167c314527d7ca7a1c4a3a9c39a6ac2d10a8b81bcb3a9180a17014f4881c2be139b55ba3947b22e31ef
+  metadata.gz: dadd0674dd7b51f92e3df36ad084282fb068831149208fa37cb2238b904a3a2bbb4336433ad88efae1bd0fea9bd2703c0925f5972711decc0aa415798c27f816
+  data.tar.gz: 388a79a26a9425fce232d21e08de3b9b9f1dcf86bea42175e27e605fd2c48215dfb78b274ebd28ec40195a1ac8584259766f7801889866f9f1898d6540cd0902

data/README.md

@@ -1,12 +1,13 @@
 # Clover Sandbox Simulator
 
-A Ruby gem for simulating Point of Sale operations in Clover sandbox environments. Generates realistic restaurant orders, payments, and transaction data for testing integrations with Clover's API.
+A Ruby gem for simulating Point of Sale operations in Clover sandbox environments. Generates realistic orders, payments, and transaction data across **9 business types** for testing integrations with Clover's API.
 
 ## Features
 
-- **Realistic Restaurant Data**: Complete menu with 39 items across 7 categories (appetizers, entrees, sides, desserts, drinks, alcoholic beverages, specials)
+- **9 Business Types**: Restaurant, Cafe/Bakery, Bar/Nightclub, Food Truck, Fine Dining, Pizzeria, Retail Clothing, Retail General, Salon/Spa — each with tailored categories and items
+- **168 Menu/Product Items**: Spread across 38 categories with realistic pricing
 - **Modifier Groups**: Temperature, add-ons, sides, dressings, drink sizes applied to menu items
-- **Multiple Payment Methods**: Supports Credit/Debit cards via Ecommerce API, plus Cash, Check, Gift Card, and other tenders
+- **Multiple Payment Methods**: Credit/Debit cards via Ecommerce API, plus Cash, Check, Gift Card, and other tenders
 - **Split Payments**: Supports 1-4 tender splits per order, more common for larger parties
 - **Meal Period Simulation**: Orders distributed across breakfast, lunch, happy hour, dinner, and late night with realistic weights
 - **Order Types**: Dine-in, Takeout, and Delivery with configurable settings
@@ -14,12 +15,15 @@ A Ruby gem for simulating Point of Sale operations in Clover sandbox environment
 - **Dynamic Order Volume**: Different order counts for weekdays, Friday, Saturday, Sunday (40-120 orders/day)
 - **Tips & Taxes**: Variable tip rates by dining option (15-25% dine-in, 0-15% takeout, 10-20% delivery)
 - **Per-Item Tax Rates**: Different tax rates for food vs alcohol items
-- **Discounts**: 7 discount types including Happy Hour, Senior, Military, Employee, Birthday, and fixed amounts
+- **Discounts**: 7 discount types including Happy Hour, promo codes, loyalty, combo, line-item, threshold, and legacy
 - **Employees & Customers**: Auto-generated with realistic names and contact info
 - **Shift Tracking**: Clock in/out for employees with duration tracking
 - **Cash Drawer Management**: Open/close drawer events with cash tracking
 - **Party Size Variation**: 1-6 guests affecting item counts and split payment probability
 - **Order Notes**: Random special instructions (allergies, modifications, VIP customers)
+- **PostgreSQL Audit Trail**: Track all simulated orders, payments, and API requests in a local database
+- **Daily Summaries**: Automated aggregation of revenue, tax, tips, and discounts by meal period and dining option
+- **Database Seeding**: Idempotent FactoryBot-based seeder for all 9 business types
 
 ## Installation
 
@@ -45,18 +49,32 @@ gem install clover_sandbox_simulator
 
 ### Multi-Merchant Setup (Recommended)
 
-Create a `.env.json` file with multiple merchant configurations:
+Create a `.env.json` file with the object format:
+
+```json
+{
+  "DATABASE_URL": "postgres://localhost:5432/clover_simulator_development",
+  "merchants": [
+    {
+      "CLOVER_MERCHANT_ID": "YOUR_MERCHANT_ID",
+      "CLOVER_MERCHANT_NAME": "My Test Merchant",
+      "CLOVER_API_TOKEN": "static-api-token",
+      "CLOVER_ACCESS_TOKEN": "oauth-jwt-token",
+      "CLOVER_REFRESH_TOKEN": "clvroar-refresh-token",
+      "PUBLIC_TOKEN": "ecommerce-public-token",
+      "PRIVATE_TOKEN": "ecommerce-private-token"
+    }
+  ]
+}
+```
+
+The legacy array format is also supported for backwards compatibility:
 
 ```json
 [
   {
     "CLOVER_MERCHANT_ID": "YOUR_MERCHANT_ID",
-    "CLOVER_MERCHANT_NAME": "My Test Merchant",
-    "CLOVER_API_TOKEN": "static-api-token",
-    "CLOVER_ACCESS_TOKEN": "oauth-jwt-token",
-    "CLOVER_REFRESH_TOKEN": "clvroar-refresh-token",
-    "PUBLIC_TOKEN": "ecommerce-public-token",
-    "PRIVATE_TOKEN": "ecommerce-private-token"
+    "CLOVER_API_TOKEN": "your-token"
   }
 ]
 ```
@@ -65,6 +83,7 @@ Create a `.env.json` file with multiple merchant configurations:
 - `CLOVER_API_TOKEN` - Static API token (never expires, preferred)
 - `CLOVER_ACCESS_TOKEN` - OAuth JWT token (expires, can be refreshed)
 - `PUBLIC_TOKEN` / `PRIVATE_TOKEN` - Required for credit card payments via Ecommerce API
+- `DATABASE_URL` - PostgreSQL connection string for audit trail persistence
 
 ### Single Merchant Setup
 
@@ -80,6 +99,20 @@ LOG_LEVEL=INFO
 TAX_RATE=8.25
 ```
 
+### Database Setup
+
+The simulator uses PostgreSQL to persist audit data (simulated orders, payments, API requests, daily summaries). Set up the database with:
+
+```bash
+# Create, migrate, and seed the database
+./bin/simulate db reset
+
+# Or step by step:
+./bin/simulate db create
+./bin/simulate db migrate
+./bin/simulate db seed
+```
+
 ## Usage
 
 ### Quick Start
@@ -93,6 +126,9 @@ Run a full simulation (setup + generate orders):
 ### Commands
 
 ```bash
+# Show version
+./bin/simulate version
+
 # List available merchants from .env.json
 ./bin/simulate merchants
 
@@ -175,9 +211,42 @@ Run a full simulation (setup + generate orders):
 ./bin/simulate generate -v
 ```
 
+### Database Management
+
+```bash
+# Database subcommands
+./bin/simulate db create    # Create PostgreSQL database
+./bin/simulate db migrate   # Run pending migrations
+./bin/simulate db seed      # Seed with 9 business types, 38 categories, 168 items
+./bin/simulate db reset     # Drop, create, migrate, and seed
+
+# Reporting
+./bin/simulate summary         # Show daily summary (revenue, orders, tips, tax)
+./bin/simulate audit            # Show recent API requests
+./bin/simulate business_types   # List business types with category/item counts
+```
+
+## Business Types
+
+The simulator supports 9 business types across 3 industries:
+
+| Business Type | Industry | Categories | Items | Description |
+|---------------|----------|------------|-------|-------------|
+| Restaurant | Food | 5 | 25 | Full-service casual dining |
+| Cafe/Bakery | Food | 5 | 25 | Coffee shop with pastries and light fare |
+| Bar/Nightclub | Food | 5 | 25 | Craft cocktails, draft beer, late-night bites |
+| Food Truck | Food | 3 | 15 | Mobile street food — tacos and Mexican fare |
+| Fine Dining | Food | 3 | 15 | Upscale prix-fixe and a la carte dining |
+| Pizzeria | Food | 3 | 15 | Classic and specialty pies, calzones, sides |
+| Retail Clothing | Retail | 5 | 25 | Casual wear with size/color variants |
+| Retail General | Retail | 5 | 13 | Electronics, home goods, personal care |
+| Salon/Spa | Service | 4 | 10 | Hair salon, spa treatments, nail services |
+
+All business types have tailored order profiles, category structures, and item pricing.
+
 ## Menu Structure
 
-### Categories
+### Categories (Restaurant Example)
 - Appetizers
 - Entrees
 - Sides
@@ -216,6 +285,8 @@ Run a full simulation (setup + generate orders):
 
 Credit and debit card payments are fully supported via the **Clover Ecommerce API**. This requires configuring `PUBLIC_TOKEN` and `PRIVATE_TOKEN` in your `.env.json`.
 
+~55% of orders use card payments when the Ecommerce API is configured. The simulator tokenizes test cards and creates charges linked to orders. If a charge fails, payment gracefully falls back to cash.
+
 **Test Card Numbers:**
 
 | Card Type | Number |
@@ -240,10 +311,41 @@ For non-card payments, the simulator uses Platform API tenders:
 - Check
 - Gift Card
 - External Payment
-- Mobile Payment
-- Store Credit
 
-The simulator uses whatever tenders are available in the Clover merchant account.
+The simulator uses whatever tenders are available in the Clover merchant account. Card tenders are automatically excluded from split payments (which use the Platform API).
+
+## Audit Trail & Persistence
+
+The simulator persists all activity to a PostgreSQL database for analysis and debugging:
+
+### Models
+
+| Model | Purpose |
+|-------|---------|
+| `BusinessType` | 9 business types with industry classification and order profiles |
+| `Category` | 38 categories linked to business types with tax groups |
+| `Item` | 168 items with SKUs, pricing, and optional size/color variants |
+| `SimulatedOrder` | Every generated order with merchant ID, period, dining option, amounts |
+| `SimulatedPayment` | Payment records with tender type classification (credit_card, debit_card, cash, check, gift_card) |
+| `ApiRequest` | Full audit log of every HTTP call to Clover (method, URL, status, duration, payloads) |
+| `DailySummary` | Automated daily aggregation of revenue, tax, tips, and discounts |
+
+### Daily Summary
+
+The `DailySummary` model automatically aggregates:
+- Order count, revenue, tax, tips, discounts
+- Breakdown by meal period and dining option
+- Revenue by meal period and dining option
+- Payment breakdown by tender type
+
+```ruby
+# Generate a summary for today
+DailySummary.generate_for!("MERCHANT_ID", Date.today)
+
+# Query summaries
+DailySummary.for_merchant("M1").recent(7)
+DailySummary.between_dates(1.week.ago, Date.today)
+```
 
 ## Tax Rates
 
@@ -281,47 +383,6 @@ The simulator supports multiple order types that affect order flow and reporting
 
 Order types are automatically created during setup if they don't exist.
 
-## Shift Management
-
-The simulator tracks employee shifts for realistic operations:
-
-```ruby
-# Clock in an employee
-services.shift.clock_in(employee_id: "EMP_123")
-
-# Clock out an employee
-services.shift.clock_out(employee_id: "EMP_123")
-
-# Get active shifts
-services.shift.get_active_shifts
-
-# Calculate shift duration
-services.shift.calculate_shift_duration(shift_id: "SHIFT_123")
-```
-
-## Cash Drawer Operations
-
-Track cash drawer operations for end-of-day reconciliation:
-
-```ruby
-# Open cash drawer
-services.cash_event.open_drawer(employee_id: "EMP_123", amount: 10000)
-
-# Close cash drawer
-services.cash_event.close_drawer(employee_id: "EMP_123", amount: 15000)
-
-# Add cash (e.g., from cash payment)
-services.cash_event.add_cash(employee_id: "EMP_123", amount: 2500, note: "Cash sale")
-
-# Remove cash (e.g., cash out)
-services.cash_event.remove_cash(employee_id: "EMP_123", amount: 5000, note: "Bank deposit")
-
-# Get drawer total
-services.cash_event.calculate_drawer_total
-```
-
-**Note:** Cash event creation may not be fully supported in the Clover sandbox. The simulator handles this gracefully with simulated responses.
-
 ## Tips
 
 Tips vary by dining option to simulate realistic customer behavior:
@@ -374,24 +435,38 @@ Each meal period has different dining option distributions:
 
 ```
 clover_sandbox_simulator/
-├── bin/simulate                      # CLI entry point
+├── bin/simulate                      # CLI entry point (Thor)
 ├── lib/
-│   ├── clover_sandbox_simulator.rb   # Gem entry point
+│   ├── clover_sandbox_simulator.rb   # Gem entry point, VERSION constant
 │   └── clover_sandbox_simulator/
 │       ├── configuration.rb          # Multi-merchant config from .env.json
+│       ├── database.rb               # PostgreSQL connection management
+│       ├── seeder.rb                 # Idempotent FactoryBot seeder
 │       ├── parallel_executor.rb      # Concurrent execution support
+│       ├── models/                   # ActiveRecord models (standalone, no Rails)
+│       │   ├── record.rb            # Base class for all models
+│       │   ├── business_type.rb     # 9 business types with industries
+│       │   ├── category.rb          # 38 categories per business type
+│       │   ├── item.rb              # 168 items with pricing & variants
+│       │   ├── simulated_order.rb   # Generated order audit records
+│       │   ├── simulated_payment.rb # Payment audit records by tender type
+│       │   ├── api_request.rb       # Full HTTP request/response audit log
+│       │   └── daily_summary.rb     # Automated daily aggregation
+│       ├── db/
+│       │   ├── migrate/             # 8 PostgreSQL migrations (UUID PKs)
+│       │   └── factories/           # FactoryBot factories (shared with seeder)
 │       ├── services/
-│       │   ├── base_service.rb       # HTTP client, error handling helpers
-│       │   └── clover/               # Clover API services
+│       │   ├── base_service.rb      # HTTP client, error handling, audit logging
+│       │   └── clover/              # Clover API services
 │       │       ├── inventory_service.rb    # Categories, items, modifier groups
 │       │       ├── order_service.rb        # Orders, line items, modifiers
-│       │       ├── payment_service.rb      # Payments, splits
-│       │       ├── tender_service.rb       # Payment tenders
+│       │       ├── payment_service.rb      # Payments, splits, card payments
+│       │       ├── tender_service.rb       # Payment tenders, card detection
+│       │       ├── ecommerce_service.rb    # Card tokenization & charges
 │       │       ├── tax_service.rb          # Tax rates, per-item taxes
-│       │       ├── discount_service.rb     # Discounts, promos, combos
+│       │       ├── discount_service.rb     # Discounts, promos, combos, loyalty
 │       │       ├── employee_service.rb     # Employee management
 │       │       ├── customer_service.rb     # Customer management
-│       │       ├── ecommerce_service.rb    # Card payments via Ecommerce API
 │       │       ├── refund_service.rb       # Full/partial refunds
 │       │       ├── gift_card_service.rb    # Gift card management
 │       │       ├── service_charge_service.rb # Service charges, auto-gratuity
@@ -401,18 +476,18 @@ clover_sandbox_simulator/
 │       │       ├── oauth_service.rb        # Token refresh
 │       │       └── services_manager.rb     # Thread-safe service access
 │       ├── generators/
-│       │   ├── data_loader.rb        # Load JSON data files
+│       │   ├── data_loader.rb        # DB-first data loading with JSON fallback
 │       │   ├── entity_generator.rb   # Setup entities (idempotent)
-│       │   └── order_generator.rb    # Generate realistic orders
+│       │   └── order_generator.rb    # Generate realistic orders & payments
 │       └── data/
-│           └── restaurant/           # JSON data files
+│           └── restaurant/           # JSON data files (fallback for DB)
 │               ├── categories.json
 │               ├── items.json
 │               ├── discounts.json
 │               ├── tenders.json
 │               ├── modifiers.json
 │               └── tax_rates.json
-└── spec/                             # RSpec tests with VCR integration
+└── spec/                             # 1124 examples, 0 failures
 ```
 
 ## Development
@@ -427,6 +502,9 @@ bundle exec rspec --format documentation
 # Run specific test file
 bundle exec rspec spec/services/clover/tender_service_spec.rb
 
+# Run model specs
+bundle exec rspec spec/models/
+
 # Run integration tests (requires .env.json with valid credentials)
 bundle exec rspec spec/integration/
 
@@ -435,24 +513,30 @@ bundle exec rubocop
 
 # Open console
 bundle exec irb -r ./lib/clover_sandbox_simulator
+
+# Build the gem
+gem build clover_sandbox_simulator.gemspec
 ```
 
 ## Testing
 
-The gem includes comprehensive RSpec tests with WebMock for HTTP stubbing and VCR for integration tests.
+The gem includes comprehensive RSpec tests with WebMock for HTTP stubbing, VCR for integration tests, and DatabaseCleaner for test isolation.
 
 ### Test Coverage
 
-- **475 examples, 0 failures, 3 pending**
-- Configuration validation
-- Data loading from JSON files
+- **1124 examples, 0 failures, 3 pending**
+- Database connection management and migration
+- Seeder idempotency (9 business types, 38 categories, 168 items)
+- FactoryBot factory validation (219 factories/traits)
+- All ActiveRecord models (validations, scopes, associations)
 - All Clover API services:
   - InventoryService (categories, items, modifier groups)
   - OrderService (create, line items, dining options, modifiers)
   - PaymentService (single, split, and card payments)
-  - TenderService (tender selection)
+  - TenderService (tender selection, card detection, ecommerce filtering)
+  - EcommerceService (tokenization, charges, refunds)
   - TaxService (rates, per-item calculation, item associations)
-  - DiscountService (percentage, fixed, time-based, loyalty)
+  - DiscountService (percentage, fixed, time-based, loyalty, combo, promo codes)
   - EmployeeService (CRUD, deterministic setup)
   - CustomerService (CRUD, anonymous orders)
   - RefundService (full/partial refunds, multiple strategies)
@@ -462,42 +546,64 @@ The gem includes comprehensive RSpec tests with WebMock for HTTP stubbing and VC
   - OrderTypeService (CRUD, default setup)
   - CashEventService (drawer operations, simulated responses)
   - ServicesManager (thread-safe memoization, lazy loading)
-- Entity generator idempotency
-- Order generator (meal periods, dining options, tips, refunds, modifiers, service charges)
-- Edge cases (nil handling, empty arrays, API errors)
+- Audit trail (API request logging, order/payment tracking, daily summaries)
+- Order generator (meal periods, dining options, tips, card payments, fallbacks, refunds, modifiers, service charges)
+- Data loader (DB-first with JSON fallback, format parity)
+- Multi-business type integration (industry classification, order profiles)
+- Financial data quality validation
+- Edge cases (nil handling, empty arrays, API errors, network failures)
 - VCR integration tests for real API validation
 
 ### Test Files
 
 ```
 spec/
-├── configuration_spec.rb
+├── audit_logging_spec.rb              # BaseService audit + OrderGenerator tracking
+├── configuration_spec.rb              # Multi-merchant config validation
+├── configuration_database_url_spec.rb # DATABASE_URL parsing
+├── database_spec.rb                   # Connection management, migrations
+├── seeder_spec.rb                     # Idempotent seeding, business types
+├── factories/
+│   └── factories_spec.rb             # 219 factory/trait validation
 ├── generators/
-│   ├── data_loader_spec.rb
-│   ├── entity_generator_spec.rb
-│   └── order_generator_spec.rb
-├── services/clover/
-│   ├── customer_service_spec.rb
-│   ├── discount_service_spec.rb
-│   ├── employee_service_spec.rb
-│   ├── gift_card_service_spec.rb
-│   ├── inventory_service_spec.rb
-│   ├── order_service_spec.rb
-│   ├── payment_service_spec.rb
-│   ├── refund_service_spec.rb
-│   ├── service_charge_service_spec.rb
-│   ├── shift_service_spec.rb
-│   ├── order_type_service_spec.rb
-│   ├── cash_event_service_spec.rb
-│   ├── tax_service_spec.rb
-│   ├── services_manager_spec.rb
-│   └── tender_service_spec.rb
-└── integration/
-    ├── modifier_groups_spec.rb
-    ├── service_charges_spec.rb
-    ├── order_types_spec.rb
-    ├── cash_events_spec.rb
-    └── tax_rates_spec.rb
+│   ├── data_loader_spec.rb           # DB/JSON loading, format parity
+│   ├── entity_generator_spec.rb      # Idempotent setup
+│   └── order_generator_spec.rb       # Payments, tips, dining, card flow
+├── integration/
+│   ├── audit_trail_spec.rb           # End-to-end order/payment/summary
+│   ├── data_loader_compat_spec.rb    # DB vs JSON compatibility
+│   ├── multi_business_spec.rb        # 9 business types, industries
+│   ├── modifier_groups_spec.rb       # VCR: real API
+│   ├── service_charges_spec.rb       # VCR: real API
+│   ├── order_types_spec.rb           # VCR: real API
+│   ├── cash_events_spec.rb           # VCR: real API
+│   └── tax_rates_spec.rb            # VCR: real API
+├── models/
+│   ├── api_request_spec.rb           # Scopes, validations
+│   ├── business_type_spec.rb         # Industries, associations
+│   ├── category_spec.rb              # Scoped uniqueness
+│   ├── daily_summary_spec.rb         # Aggregation, idempotency
+│   ├── item_spec.rb                  # Pricing, variants, scopes
+│   ├── record_spec.rb                # Base class
+│   ├── simulated_order_spec.rb       # Status transitions, scopes
+│   └── simulated_payment_spec.rb     # Tender classification, scopes
+└── services/clover/
+    ├── cash_event_service_spec.rb
+    ├── customer_service_spec.rb
+    ├── discount_service_spec.rb
+    ├── employee_service_spec.rb
+    ├── financial_data_quality_spec.rb
+    ├── gift_card_service_spec.rb
+    ├── inventory_service_spec.rb
+    ├── order_service_spec.rb
+    ├── order_type_service_spec.rb
+    ├── payment_service_spec.rb
+    ├── refund_service_spec.rb
+    ├── service_charge_service_spec.rb
+    ├── services_manager_spec.rb
+    ├── shift_service_spec.rb
+    ├── tax_service_spec.rb
+    └── tender_service_spec.rb
 ```
 
 ### Idempotency Verification
@@ -519,6 +625,7 @@ The tests verify:
 - Tax rates are not duplicated
 - Order types are not duplicated
 - Employees/customers only created if count threshold not met
+- Database seeder is idempotent across all 9 business types
 
 ## Sandbox Limitations
 
@@ -526,11 +633,11 @@ Some Clover sandbox operations may return errors or behave differently than prod
 
 | Feature | Sandbox Support | Notes |
 |---------|-----------------|-------|
-| Service Charge Creation | ❌ Limited | Must pre-configure in dashboard |
-| Cash Event Creation | ❌ Limited | Returns 405, simulated locally |
-| Item Tax Rate Fetch | ❌ Limited | Returns 405, simulated locally |
-| Credit Card Payments | ✅ Full | Via Ecommerce API |
-| Order Creation | ✅ Full | Today's date only |
+| Service Charge Creation | Limited | Must pre-configure in dashboard |
+| Cash Event Creation | Limited | Returns 405, simulated locally |
+| Item Tax Rate Fetch | Limited | Returns 405, simulated locally |
+| Credit Card Payments | Full | Via Ecommerce API |
+| Order Creation | Full | Today's date only |
 
 The simulator handles these limitations gracefully with fallback behavior.
 
@@ -538,8 +645,9 @@ The simulator handles these limitations gracefully with fallback behavior.
 
 - **Sandbox URL**: `https://sandbox.dev.clover.com/`
 - **API Version**: v3
-- **Authentication**: Bearer token (OAuth)
+- **Authentication**: Bearer token (OAuth) for Platform API; apikey header for tokenization
 - **Date Limitation**: Clover sandbox only allows creating orders for TODAY
+- **Ecommerce API**: Separate endpoints for card tokenization, charges, and refunds
 
 ## License
 

data/lib/clover_sandbox_simulator/configuration.rb

@@ -217,11 +217,14 @@ module CloverSandboxSimulator
       @merchant_name = merchant["CLOVER_MERCHANT_NAME"]
       # CLOVER_API_TOKEN = static API token (never expires)
       # CLOVER_ACCESS_TOKEN = OAuth JWT token (expires, can be refreshed)
-      # Prefer static API token if available, fall back to OAuth token
+      # PRIVATE_TOKEN = Ecommerce API key (can also serve as Bearer token for Platform API)
+      # Prefer static API token, fall back to OAuth token, then PRIVATE_TOKEN
       if merchant["CLOVER_API_TOKEN"].to_s.length > 10
         @api_token = merchant["CLOVER_API_TOKEN"]
       elsif merchant["CLOVER_ACCESS_TOKEN"].to_s.length > 10
         @api_token = merchant["CLOVER_ACCESS_TOKEN"]
+      elsif merchant["PRIVATE_TOKEN"].to_s.length > 10
+        @api_token = merchant["PRIVATE_TOKEN"]
       end
       @refresh_token = merchant["CLOVER_REFRESH_TOKEN"] if merchant["CLOVER_REFRESH_TOKEN"].to_s.length > 10
       @public_token  = merchant["PUBLIC_TOKEN"] unless merchant["PUBLIC_TOKEN"].to_s.empty?

data/lib/clover_sandbox_simulator/data/salon_spa/categories.json

@@ -0,0 +1,24 @@
+{
+  "categories": [
+    {
+      "name": "Haircuts",
+      "sort_order": 1,
+      "description": "Cuts and trims for all ages"
+    },
+    {
+      "name": "Color Services",
+      "sort_order": 2,
+      "description": "Color, highlights, and balayage"
+    },
+    {
+      "name": "Spa Treatments",
+      "sort_order": 3,
+      "description": "Massage and facials"
+    },
+    {
+      "name": "Nail Services",
+      "sort_order": 4,
+      "description": "Manicures and pedicures"
+    }
+  ]
+}

data/lib/clover_sandbox_simulator/data/salon_spa/combos.json

@@ -0,0 +1,88 @@
+{
+  "combos": [
+    {
+      "id": "cut_and_color",
+      "name": "Cut & Color Package",
+      "description": "Haircut + any color service for 10% off",
+      "discount_type": "percentage",
+      "discount_value": 10,
+      "required_components": [
+        {
+          "category": "Haircuts",
+          "quantity": 1
+        },
+        {
+          "category": "Color Services",
+          "quantity": 1
+        }
+      ],
+      "applies_to": "total",
+      "max_discount_amount": 2500,
+      "active": true
+    },
+    {
+      "id": "mani_pedi",
+      "name": "Mani-Pedi Combo",
+      "description": "Manicure + Pedicure for 15% off",
+      "discount_type": "percentage",
+      "discount_value": 15,
+      "required_components": [
+        {
+          "category": "Nail Services",
+          "quantity": 2
+        }
+      ],
+      "applies_to": "total",
+      "max_discount_amount": 1500,
+      "active": true
+    },
+    {
+      "id": "spa_day",
+      "name": "Spa Day Package",
+      "description": "Massage + Facial + Manicure for $25 off",
+      "discount_type": "fixed",
+      "discount_value": 2500,
+      "required_components": [
+        {
+          "category": "Spa Treatments",
+          "quantity": 2
+        },
+        {
+          "category": "Nail Services",
+          "quantity": 1
+        }
+      ],
+      "applies_to": "total",
+      "max_discount_amount": null,
+      "active": true
+    },
+    {
+      "id": "bridal_package",
+      "name": "Bridal Package",
+      "description": "Haircut + Color + Manicure + Facial for 20% off",
+      "discount_type": "percentage",
+      "discount_value": 20,
+      "required_components": [
+        {
+          "category": "Haircuts",
+          "quantity": 1
+        },
+        {
+          "category": "Color Services",
+          "quantity": 1
+        },
+        {
+          "category": "Nail Services",
+          "quantity": 1
+        },
+        {
+          "category": "Spa Treatments",
+          "quantity": 1
+        }
+      ],
+      "applies_to": "total",
+      "max_discount_amount": 5000,
+      "active": true
+    }
+  ]
+}

data/lib/clover_sandbox_simulator/data/salon_spa/coupon_codes.json

@@ -0,0 +1,96 @@
+{
+  "coupon_codes": [
+    {
+      "code": "NEWCLIENT20",
+      "name": "New Client 20% Off",
+      "description": "20% off for first-time clients",
+      "discount_type": "percentage",
+      "discount_value": 20,
+      "min_order_amount": 0,
+      "max_discount_amount": 5000,
+      "valid_from": "2024-01-01T00:00:00Z",
+      "valid_until": "2027-12-31T23:59:59Z",
+      "usage_limit": null,
+      "usage_count": 0,
+      "single_use_per_customer": true,
+      "new_customers_only": true,
+      "stackable": false,
+      "applicable_categories": null,
+      "excluded_categories": null,
+      "active": true
+    },
+    {
+      "code": "RELAX15",
+      "name": "Relaxation Discount",
+      "description": "15% off any spa treatment",
+      "discount_type": "percentage",
+      "discount_value": 15,
+      "min_order_amount": 0,
+      "max_discount_amount": 2500,
+      "valid_from": "2024-01-01T00:00:00Z",
+      "valid_until": "2027-12-31T23:59:59Z",
+      "usage_limit": null,
+      "usage_count": 0,
+      "single_use_per_customer": false,
+      "stackable": false,
+      "applicable_categories": ["Spa Treatments"],
+      "excluded_categories": null,
+      "active": true
+    },
+    {
+      "code": "NAILS10",
+      "name": "$10 Off Nails",
+      "description": "$10 off any nail service",
+      "discount_type": "fixed",
+      "discount_value": 1000,
+      "min_order_amount": 2500,
+      "max_discount_amount": null,
+      "valid_from": "2024-01-01T00:00:00Z",
+      "valid_until": "2027-12-31T23:59:59Z",
+      "usage_limit": 200,
+      "usage_count": 42,
+      "single_use_per_customer": true,
+      "stackable": false,
+      "applicable_categories": ["Nail Services"],
+      "excluded_categories": null,
+      "active": true
+    },
+    {
+      "code": "BIRTHDAY25",
+      "name": "Birthday Special",
+      "description": "25% off for your birthday month",
+      "discount_type": "percentage",
+      "discount_value": 25,
+      "min_order_amount": 0,
+      "max_discount_amount": null,
+      "valid_from": "2024-01-01T00:00:00Z",
+      "valid_until": "2027-12-31T23:59:59Z",
+      "usage_limit": null,
+      "usage_count": 0,
+      "single_use_per_customer": true,
+      "birthday_required": true,
+      "stackable": false,
+      "applicable_categories": null,
+      "excluded_categories": null,
+      "active": true
+    },
+    {
+      "code": "REFER20",
+      "name": "Referral Code",
+      "description": "20% off when referred by a friend",
+      "discount_type": "percentage",
+      "discount_value": 20,
+      "min_order_amount": 0,
+      "max_discount_amount": 4000,
+      "valid_from": "2024-01-01T00:00:00Z",
+      "valid_until": "2027-12-31T23:59:59Z",
+      "usage_limit": null,
+      "usage_count": 0,
+      "single_use_per_customer": true,
+      "stackable": false,
+      "applicable_categories": null,
+      "excluded_categories": null,
+      "active": true
+    }
+  ]
+}

data/lib/clover_sandbox_simulator/data/salon_spa/discounts.json

@@ -0,0 +1,93 @@
+{
+  "discounts": [
+    {
+      "id": "new_client",
+      "name": "New Client Special",
+      "percentage": 20,
+      "description": "20% off first visit for new clients",
+      "type": "customer",
+      "auto_apply": false
+    },
+    {
+      "id": "referral_discount",
+      "name": "Referral Reward",
+      "percentage": 15,
+      "description": "15% off when referred by an existing client",
+      "type": "customer",
+      "auto_apply": false
+    },
+    {
+      "id": "senior_discount",
+      "name": "Senior Discount",
+      "percentage": 10,
+      "description": "10% off for seniors 65+",
+      "type": "customer",
+      "auto_apply": false
+    },
+    {
+      "id": "loyalty_bronze",
+      "name": "Loyalty - Bronze",
+      "percentage": 5,
+      "description": "5% off for 5+ visits",
+      "type": "loyalty",
+      "min_visits": 5,
+      "auto_apply": true
+    },
+    {
+      "id": "loyalty_silver",
+      "name": "Loyalty - Silver",
+      "percentage": 10,
+      "description": "10% off for 10+ visits",
+      "type": "loyalty",
+      "min_visits": 10,
+      "auto_apply": true
+    },
+    {
+      "id": "loyalty_gold",
+      "name": "Loyalty - Gold",
+      "percentage": 15,
+      "description": "15% off for 25+ visits",
+      "type": "loyalty",
+      "min_visits": 25,
+      "auto_apply": true
+    },
+    {
+      "id": "ten_off_color",
+      "name": "$10 Off Color Service",
+      "amount": 1000,
+      "description": "$10 off any color service over $80",
+      "type": "threshold",
+      "min_order_amount": 8000,
+      "auto_apply": false
+    },
+    {
+      "id": "twenty_off",
+      "name": "$20 Off",
+      "amount": 2000,
+      "description": "$20 off services over $100",
+      "type": "threshold",
+      "min_order_amount": 10000,
+      "auto_apply": false
+    },
+    {
+      "id": "nail_addon_discount",
+      "name": "Nail Add-On 50% Off",
+      "percentage": 50,
+      "description": "50% off nail art when added to any manicure or pedicure",
+      "type": "line_item",
+      "applicable_categories": ["Nail Services"],
+      "auto_apply": false
+    },
+    {
+      "id": "weekday_special",
+      "name": "Weekday Special",
+      "percentage": 10,
+      "description": "10% off services Monday-Wednesday",
+      "type": "time_based",
+      "time_rules": {
+        "valid_days": [1, 2, 3]
+      },
+      "auto_apply": true
+    }
+  ]
+}

data/lib/clover_sandbox_simulator/data/salon_spa/gift_cards.json

@@ -0,0 +1,47 @@
+{
+  "gift_cards": [
+    {
+      "card_number": "7012345678901234",
+      "initial_balance": 5000,
+      "current_balance": 5000,
+      "status": "ACTIVE",
+      "description": "$50 Salon Gift Card - Full balance"
+    },
+    {
+      "card_number": "7023456789012345",
+      "initial_balance": 10000,
+      "current_balance": 10000,
+      "status": "ACTIVE",
+      "description": "$100 Salon Gift Card - Full balance"
+    },
+    {
+      "card_number": "7034567890123456",
+      "initial_balance": 15000,
+      "current_balance": 15000,
+      "status": "ACTIVE",
+      "description": "$150 Salon Gift Card - Full balance"
+    },
+    {
+      "card_number": "7045678901234567",
+      "initial_balance": 10000,
+      "current_balance": 4500,
+      "status": "ACTIVE",
+      "description": "$100 Salon Gift Card - Partially used ($45 remaining)"
+    },
+    {
+      "card_number": "7056789012345678",
+      "initial_balance": 20000,
+      "current_balance": 20000,
+      "status": "ACTIVE",
+      "description": "$200 Salon Gift Card - Full balance"
+    }
+  ],
+  "purchase_denominations": [
+    { "amount": 5000, "label": "$50 Salon Gift Card" },
+    { "amount": 10000, "label": "$100 Salon Gift Card" },
+    { "amount": 15000, "label": "$150 Salon Gift Card" },
+    { "amount": 20000, "label": "$200 Salon Gift Card" },
+    { "amount": 25000, "label": "$250 Salon Gift Card" }
+  ],
+  "note": "Salon gift cards — popular for gifts and celebrations"
+}

data/lib/clover_sandbox_simulator/data/salon_spa/items.json

@@ -0,0 +1,100 @@
+{
+  "items": [
+    {
+      "name": "Women's Haircut",
+      "price": 5500,
+      "category": "Haircuts",
+      "description": "Full haircut and style (45 min)"
+    },
+    {
+      "name": "Men's Haircut",
+      "price": 3000,
+      "category": "Haircuts",
+      "description": "Classic cut and finish (30 min)"
+    },
+    {
+      "name": "Children's Haircut",
+      "price": 2000,
+      "category": "Haircuts",
+      "description": "Kids cut, ages 12 and under (20 min)"
+    },
+    {
+      "name": "Bang Trim",
+      "price": 1500,
+      "category": "Haircuts",
+      "description": "Quick bang trim between cuts (15 min)"
+    },
+    {
+      "name": "Full Color",
+      "price": 12000,
+      "category": "Color Services",
+      "description": "All-over single process color (120 min)"
+    },
+    {
+      "name": "Highlights (Partial)",
+      "price": 9000,
+      "category": "Color Services",
+      "description": "Partial foil highlights (90 min)"
+    },
+    {
+      "name": "Highlights (Full)",
+      "price": 15000,
+      "category": "Color Services",
+      "description": "Full head foil highlights (120 min)"
+    },
+    {
+      "name": "Balayage",
+      "price": 18000,
+      "category": "Color Services",
+      "description": "Hand-painted color technique (150 min)"
+    },
+    {
+      "name": "Swedish Massage (60min)",
+      "price": 9500,
+      "category": "Spa Treatments",
+      "description": "Relaxation full-body massage"
+    },
+    {
+      "name": "Deep Tissue Massage (60min)",
+      "price": 11000,
+      "category": "Spa Treatments",
+      "description": "Therapeutic deep pressure massage"
+    },
+    {
+      "name": "Hot Stone Massage (60min)",
+      "price": 12000,
+      "category": "Spa Treatments",
+      "description": "Heated basalt stone therapy massage"
+    },
+    {
+      "name": "Facial (60min)",
+      "price": 8500,
+      "category": "Spa Treatments",
+      "description": "Customized facial with extractions"
+    },
+    {
+      "name": "Manicure",
+      "price": 2500,
+      "category": "Nail Services",
+      "description": "Classic manicure with polish (30 min)"
+    },
+    {
+      "name": "Pedicure",
+      "price": 3500,
+      "category": "Nail Services",
+      "description": "Classic pedicure with polish (45 min)"
+    },
+    {
+      "name": "Gel Manicure",
+      "price": 4000,
+      "category": "Nail Services",
+      "description": "Long-lasting gel polish manicure (45 min)"
+    },
+    {
+      "name": "Acrylic Full Set",
+      "price": 5500,
+      "category": "Nail Services",
+      "description": "Full set of acrylic nail extensions (60 min)"
+    }
+  ]
+}

data/lib/clover_sandbox_simulator/data/salon_spa/modifiers.json

@@ -0,0 +1,49 @@
+{
+  "modifier_groups": [
+    {
+      "name": "Stylist Level",
+      "min_required": 0,
+      "max_allowed": 1,
+      "modifiers": [
+        { "name": "Junior Stylist", "price": 0 },
+        { "name": "Senior Stylist", "price": 1500 },
+        { "name": "Master Stylist", "price": 3000 },
+        { "name": "Artistic Director", "price": 5000 }
+      ]
+    },
+    {
+      "name": "Add-On Treatments",
+      "min_required": 0,
+      "max_allowed": 3,
+      "modifiers": [
+        { "name": "Deep Conditioning Treatment", "price": 2500 },
+        { "name": "Scalp Treatment", "price": 2000 },
+        { "name": "Gloss Treatment", "price": 3500 },
+        { "name": "Olaplex Treatment", "price": 4500 },
+        { "name": "Keratin Treatment", "price": 8000 }
+      ]
+    },
+    {
+      "name": "Nail Art",
+      "min_required": 0,
+      "max_allowed": 1,
+      "modifiers": [
+        { "name": "Simple Design (2 nails)", "price": 500 },
+        { "name": "Full Art (all nails)", "price": 1500 },
+        { "name": "Chrome/Ombre Finish", "price": 1000 },
+        { "name": "French Tips", "price": 800 }
+      ]
+    },
+    {
+      "name": "Massage Upgrade",
+      "min_required": 0,
+      "max_allowed": 2,
+      "modifiers": [
+        { "name": "Aromatherapy", "price": 1000 },
+        { "name": "CBD Oil", "price": 1500 },
+        { "name": "Extended 30 min", "price": 5000 },
+        { "name": "Couples Room", "price": 2000 }
+      ]
+    }
+  ]
+}

data/lib/clover_sandbox_simulator/data/salon_spa/tax_rates.json

@@ -0,0 +1,17 @@
+{
+  "tax_rates": [
+    {
+      "name": "Service Tax",
+      "rate": 8.25,
+      "is_default": true,
+      "description": "Standard sales tax on salon and spa services"
+    }
+  ],
+  "category_tax_mapping": {
+    "Haircuts": ["Service Tax"],
+    "Color Services": ["Service Tax"],
+    "Spa Treatments": ["Service Tax"],
+    "Nail Services": ["Service Tax"],
+    "default": ["Service Tax"]
+  }
+}

data/lib/clover_sandbox_simulator/data/salon_spa/tenders.json

@@ -0,0 +1,41 @@
+{
+  "tenders": [
+    {
+      "label": "Cash",
+      "label_key": "com.clover.tender.cash",
+      "opens_cash_drawer": true,
+      "weight": 25
+    },
+    {
+      "label": "Check",
+      "label_key": "com.clover.tender.check",
+      "opens_cash_drawer": true,
+      "weight": 5
+    },
+    {
+      "label": "Gift Card",
+      "label_key": "com.clover.tender.external_gift_card",
+      "opens_cash_drawer": false,
+      "weight": 20
+    },
+    {
+      "label": "External Payment",
+      "label_key": "com.clover.tender.external_payment",
+      "opens_cash_drawer": false,
+      "weight": 10
+    },
+    {
+      "label": "Mobile Payment",
+      "label_key": "com.clover.tender.mobile_payment",
+      "opens_cash_drawer": false,
+      "weight": 20
+    },
+    {
+      "label": "Store Credit",
+      "label_key": "com.clover.tender.store_credit",
+      "opens_cash_drawer": false,
+      "weight": 10
+    }
+  ],
+  "note": "Credit Card and Debit Card are intentionally excluded - they are broken in Clover sandbox"
+}

data/lib/clover_sandbox_simulator.rb

@@ -10,7 +10,7 @@ require "dotenv"
 Dotenv.load
 
 module CloverSandboxSimulator
-  VERSION = "1.4.0"
+  VERSION = "1.6.0"
 
   class Error < StandardError; end
   class ConfigurationError < Error; end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: clover_sandbox_simulator
 version: !ruby/object:Gem::Version
-  version: 1.5.0
+  version: 1.6.0
 platform: ruby
 authors:
 - dan1d
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-02-07 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rest-client
@@ -258,6 +257,15 @@ files:
 - lib/clover_sandbox_simulator/data/restaurant/modifiers.json
 - lib/clover_sandbox_simulator/data/restaurant/tax_rates.json
 - lib/clover_sandbox_simulator/data/restaurant/tenders.json
+- lib/clover_sandbox_simulator/data/salon_spa/categories.json
+- lib/clover_sandbox_simulator/data/salon_spa/combos.json
+- lib/clover_sandbox_simulator/data/salon_spa/coupon_codes.json
+- lib/clover_sandbox_simulator/data/salon_spa/discounts.json
+- lib/clover_sandbox_simulator/data/salon_spa/gift_cards.json
+- lib/clover_sandbox_simulator/data/salon_spa/items.json
+- lib/clover_sandbox_simulator/data/salon_spa/modifiers.json
+- lib/clover_sandbox_simulator/data/salon_spa/tax_rates.json
+- lib/clover_sandbox_simulator/data/salon_spa/tenders.json
 - lib/clover_sandbox_simulator/database.rb
 - lib/clover_sandbox_simulator/db/factories/api_requests.rb
 - lib/clover_sandbox_simulator/db/factories/business_types.rb
@@ -309,7 +317,6 @@ homepage: https://github.com/dan1d/clover_sandbox_simulator
 licenses:
 - MIT
 metadata: {}
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -324,8 +331,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.10
-signing_key:
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Clover Sandbox Simulator for generating realistic restaurant data
 test_files: []