clover_sandbox_simulator 1.5.0 → 1.5.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/README.md +217 -109
- data/lib/clover_sandbox_simulator.rb +1 -1
- metadata +3 -6
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: a04f7b532c1ce8fd74de943d7a9458b0b29f151ef33a86c80dd3166531dc4225
|
|
4
|
+
data.tar.gz: b5745bcc29c8a40ff846e80c512b69f007e5f2851c4f06ed5ad44e837ac96134
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: d10a6a0404d3524cd99b9f5864095ca022aba117f5cbe0d911a276be5ca6bd7f537b62ff4dad06cdf621587534f0b7dc8a2e8b2bb114c868662a6ffe4d4b55ea
|
|
7
|
+
data.tar.gz: d86c9a3b0459db818e2023885856901b2fe60a89244ca6639131e523b6cd86779128ecba8f381e563b725523c1eb441b2d246259f7e19137df2fad057ac67a85
|
data/README.md
CHANGED
|
@@ -1,12 +1,13 @@
|
|
|
1
1
|
# Clover Sandbox Simulator
|
|
2
2
|
|
|
3
|
-
A Ruby gem for simulating Point of Sale operations in Clover sandbox environments. Generates realistic
|
|
3
|
+
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.
|
|
4
4
|
|
|
5
5
|
## Features
|
|
6
6
|
|
|
7
|
-
- **
|
|
7
|
+
- **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
|
|
8
|
+
- **168 Menu/Product Items**: Spread across 38 categories with realistic pricing
|
|
8
9
|
- **Modifier Groups**: Temperature, add-ons, sides, dressings, drink sizes applied to menu items
|
|
9
|
-
- **Multiple Payment Methods**:
|
|
10
|
+
- **Multiple Payment Methods**: Credit/Debit cards via Ecommerce API, plus Cash, Check, Gift Card, and other tenders
|
|
10
11
|
- **Split Payments**: Supports 1-4 tender splits per order, more common for larger parties
|
|
11
12
|
- **Meal Period Simulation**: Orders distributed across breakfast, lunch, happy hour, dinner, and late night with realistic weights
|
|
12
13
|
- **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
|
|
|
14
15
|
- **Dynamic Order Volume**: Different order counts for weekdays, Friday, Saturday, Sunday (40-120 orders/day)
|
|
15
16
|
- **Tips & Taxes**: Variable tip rates by dining option (15-25% dine-in, 0-15% takeout, 10-20% delivery)
|
|
16
17
|
- **Per-Item Tax Rates**: Different tax rates for food vs alcohol items
|
|
17
|
-
- **Discounts**: 7 discount types including Happy Hour,
|
|
18
|
+
- **Discounts**: 7 discount types including Happy Hour, promo codes, loyalty, combo, line-item, threshold, and legacy
|
|
18
19
|
- **Employees & Customers**: Auto-generated with realistic names and contact info
|
|
19
20
|
- **Shift Tracking**: Clock in/out for employees with duration tracking
|
|
20
21
|
- **Cash Drawer Management**: Open/close drawer events with cash tracking
|
|
21
22
|
- **Party Size Variation**: 1-6 guests affecting item counts and split payment probability
|
|
22
23
|
- **Order Notes**: Random special instructions (allergies, modifications, VIP customers)
|
|
24
|
+
- **PostgreSQL Audit Trail**: Track all simulated orders, payments, and API requests in a local database
|
|
25
|
+
- **Daily Summaries**: Automated aggregation of revenue, tax, tips, and discounts by meal period and dining option
|
|
26
|
+
- **Database Seeding**: Idempotent FactoryBot-based seeder for all 9 business types
|
|
23
27
|
|
|
24
28
|
## Installation
|
|
25
29
|
|
|
@@ -45,18 +49,32 @@ gem install clover_sandbox_simulator
|
|
|
45
49
|
|
|
46
50
|
### Multi-Merchant Setup (Recommended)
|
|
47
51
|
|
|
48
|
-
Create a `.env.json` file with
|
|
52
|
+
Create a `.env.json` file with the object format:
|
|
53
|
+
|
|
54
|
+
```json
|
|
55
|
+
{
|
|
56
|
+
"DATABASE_URL": "postgres://localhost:5432/clover_simulator_development",
|
|
57
|
+
"merchants": [
|
|
58
|
+
{
|
|
59
|
+
"CLOVER_MERCHANT_ID": "YOUR_MERCHANT_ID",
|
|
60
|
+
"CLOVER_MERCHANT_NAME": "My Test Merchant",
|
|
61
|
+
"CLOVER_API_TOKEN": "static-api-token",
|
|
62
|
+
"CLOVER_ACCESS_TOKEN": "oauth-jwt-token",
|
|
63
|
+
"CLOVER_REFRESH_TOKEN": "clvroar-refresh-token",
|
|
64
|
+
"PUBLIC_TOKEN": "ecommerce-public-token",
|
|
65
|
+
"PRIVATE_TOKEN": "ecommerce-private-token"
|
|
66
|
+
}
|
|
67
|
+
]
|
|
68
|
+
}
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
The legacy array format is also supported for backwards compatibility:
|
|
49
72
|
|
|
50
73
|
```json
|
|
51
74
|
[
|
|
52
75
|
{
|
|
53
76
|
"CLOVER_MERCHANT_ID": "YOUR_MERCHANT_ID",
|
|
54
|
-
"
|
|
55
|
-
"CLOVER_API_TOKEN": "static-api-token",
|
|
56
|
-
"CLOVER_ACCESS_TOKEN": "oauth-jwt-token",
|
|
57
|
-
"CLOVER_REFRESH_TOKEN": "clvroar-refresh-token",
|
|
58
|
-
"PUBLIC_TOKEN": "ecommerce-public-token",
|
|
59
|
-
"PRIVATE_TOKEN": "ecommerce-private-token"
|
|
77
|
+
"CLOVER_API_TOKEN": "your-token"
|
|
60
78
|
}
|
|
61
79
|
]
|
|
62
80
|
```
|
|
@@ -65,6 +83,7 @@ Create a `.env.json` file with multiple merchant configurations:
|
|
|
65
83
|
- `CLOVER_API_TOKEN` - Static API token (never expires, preferred)
|
|
66
84
|
- `CLOVER_ACCESS_TOKEN` - OAuth JWT token (expires, can be refreshed)
|
|
67
85
|
- `PUBLIC_TOKEN` / `PRIVATE_TOKEN` - Required for credit card payments via Ecommerce API
|
|
86
|
+
- `DATABASE_URL` - PostgreSQL connection string for audit trail persistence
|
|
68
87
|
|
|
69
88
|
### Single Merchant Setup
|
|
70
89
|
|
|
@@ -80,6 +99,20 @@ LOG_LEVEL=INFO
|
|
|
80
99
|
TAX_RATE=8.25
|
|
81
100
|
```
|
|
82
101
|
|
|
102
|
+
### Database Setup
|
|
103
|
+
|
|
104
|
+
The simulator uses PostgreSQL to persist audit data (simulated orders, payments, API requests, daily summaries). Set up the database with:
|
|
105
|
+
|
|
106
|
+
```bash
|
|
107
|
+
# Create, migrate, and seed the database
|
|
108
|
+
./bin/simulate db reset
|
|
109
|
+
|
|
110
|
+
# Or step by step:
|
|
111
|
+
./bin/simulate db create
|
|
112
|
+
./bin/simulate db migrate
|
|
113
|
+
./bin/simulate db seed
|
|
114
|
+
```
|
|
115
|
+
|
|
83
116
|
## Usage
|
|
84
117
|
|
|
85
118
|
### Quick Start
|
|
@@ -93,6 +126,9 @@ Run a full simulation (setup + generate orders):
|
|
|
93
126
|
### Commands
|
|
94
127
|
|
|
95
128
|
```bash
|
|
129
|
+
# Show version
|
|
130
|
+
./bin/simulate version
|
|
131
|
+
|
|
96
132
|
# List available merchants from .env.json
|
|
97
133
|
./bin/simulate merchants
|
|
98
134
|
|
|
@@ -175,9 +211,42 @@ Run a full simulation (setup + generate orders):
|
|
|
175
211
|
./bin/simulate generate -v
|
|
176
212
|
```
|
|
177
213
|
|
|
214
|
+
### Database Management
|
|
215
|
+
|
|
216
|
+
```bash
|
|
217
|
+
# Database subcommands
|
|
218
|
+
./bin/simulate db create # Create PostgreSQL database
|
|
219
|
+
./bin/simulate db migrate # Run pending migrations
|
|
220
|
+
./bin/simulate db seed # Seed with 9 business types, 38 categories, 168 items
|
|
221
|
+
./bin/simulate db reset # Drop, create, migrate, and seed
|
|
222
|
+
|
|
223
|
+
# Reporting
|
|
224
|
+
./bin/simulate summary # Show daily summary (revenue, orders, tips, tax)
|
|
225
|
+
./bin/simulate audit # Show recent API requests
|
|
226
|
+
./bin/simulate business_types # List business types with category/item counts
|
|
227
|
+
```
|
|
228
|
+
|
|
229
|
+
## Business Types
|
|
230
|
+
|
|
231
|
+
The simulator supports 9 business types across 3 industries:
|
|
232
|
+
|
|
233
|
+
| Business Type | Industry | Categories | Items | Description |
|
|
234
|
+
|---------------|----------|------------|-------|-------------|
|
|
235
|
+
| Restaurant | Food | 5 | 25 | Full-service casual dining |
|
|
236
|
+
| Cafe/Bakery | Food | 5 | 25 | Coffee shop with pastries and light fare |
|
|
237
|
+
| Bar/Nightclub | Food | 5 | 25 | Craft cocktails, draft beer, late-night bites |
|
|
238
|
+
| Food Truck | Food | 3 | 15 | Mobile street food — tacos and Mexican fare |
|
|
239
|
+
| Fine Dining | Food | 3 | 15 | Upscale prix-fixe and a la carte dining |
|
|
240
|
+
| Pizzeria | Food | 3 | 15 | Classic and specialty pies, calzones, sides |
|
|
241
|
+
| Retail Clothing | Retail | 5 | 25 | Casual wear with size/color variants |
|
|
242
|
+
| Retail General | Retail | 5 | 13 | Electronics, home goods, personal care |
|
|
243
|
+
| Salon/Spa | Service | 4 | 10 | Hair salon, spa treatments, nail services |
|
|
244
|
+
|
|
245
|
+
All business types have tailored order profiles, category structures, and item pricing.
|
|
246
|
+
|
|
178
247
|
## Menu Structure
|
|
179
248
|
|
|
180
|
-
### Categories
|
|
249
|
+
### Categories (Restaurant Example)
|
|
181
250
|
- Appetizers
|
|
182
251
|
- Entrees
|
|
183
252
|
- Sides
|
|
@@ -216,6 +285,8 @@ Run a full simulation (setup + generate orders):
|
|
|
216
285
|
|
|
217
286
|
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`.
|
|
218
287
|
|
|
288
|
+
~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.
|
|
289
|
+
|
|
219
290
|
**Test Card Numbers:**
|
|
220
291
|
|
|
221
292
|
| Card Type | Number |
|
|
@@ -240,10 +311,41 @@ For non-card payments, the simulator uses Platform API tenders:
|
|
|
240
311
|
- Check
|
|
241
312
|
- Gift Card
|
|
242
313
|
- External Payment
|
|
243
|
-
- Mobile Payment
|
|
244
|
-
- Store Credit
|
|
245
314
|
|
|
246
|
-
The simulator uses whatever tenders are available in the Clover merchant account.
|
|
315
|
+
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).
|
|
316
|
+
|
|
317
|
+
## Audit Trail & Persistence
|
|
318
|
+
|
|
319
|
+
The simulator persists all activity to a PostgreSQL database for analysis and debugging:
|
|
320
|
+
|
|
321
|
+
### Models
|
|
322
|
+
|
|
323
|
+
| Model | Purpose |
|
|
324
|
+
|-------|---------|
|
|
325
|
+
| `BusinessType` | 9 business types with industry classification and order profiles |
|
|
326
|
+
| `Category` | 38 categories linked to business types with tax groups |
|
|
327
|
+
| `Item` | 168 items with SKUs, pricing, and optional size/color variants |
|
|
328
|
+
| `SimulatedOrder` | Every generated order with merchant ID, period, dining option, amounts |
|
|
329
|
+
| `SimulatedPayment` | Payment records with tender type classification (credit_card, debit_card, cash, check, gift_card) |
|
|
330
|
+
| `ApiRequest` | Full audit log of every HTTP call to Clover (method, URL, status, duration, payloads) |
|
|
331
|
+
| `DailySummary` | Automated daily aggregation of revenue, tax, tips, and discounts |
|
|
332
|
+
|
|
333
|
+
### Daily Summary
|
|
334
|
+
|
|
335
|
+
The `DailySummary` model automatically aggregates:
|
|
336
|
+
- Order count, revenue, tax, tips, discounts
|
|
337
|
+
- Breakdown by meal period and dining option
|
|
338
|
+
- Revenue by meal period and dining option
|
|
339
|
+
- Payment breakdown by tender type
|
|
340
|
+
|
|
341
|
+
```ruby
|
|
342
|
+
# Generate a summary for today
|
|
343
|
+
DailySummary.generate_for!("MERCHANT_ID", Date.today)
|
|
344
|
+
|
|
345
|
+
# Query summaries
|
|
346
|
+
DailySummary.for_merchant("M1").recent(7)
|
|
347
|
+
DailySummary.between_dates(1.week.ago, Date.today)
|
|
348
|
+
```
|
|
247
349
|
|
|
248
350
|
## Tax Rates
|
|
249
351
|
|
|
@@ -281,47 +383,6 @@ The simulator supports multiple order types that affect order flow and reporting
|
|
|
281
383
|
|
|
282
384
|
Order types are automatically created during setup if they don't exist.
|
|
283
385
|
|
|
284
|
-
## Shift Management
|
|
285
|
-
|
|
286
|
-
The simulator tracks employee shifts for realistic operations:
|
|
287
|
-
|
|
288
|
-
```ruby
|
|
289
|
-
# Clock in an employee
|
|
290
|
-
services.shift.clock_in(employee_id: "EMP_123")
|
|
291
|
-
|
|
292
|
-
# Clock out an employee
|
|
293
|
-
services.shift.clock_out(employee_id: "EMP_123")
|
|
294
|
-
|
|
295
|
-
# Get active shifts
|
|
296
|
-
services.shift.get_active_shifts
|
|
297
|
-
|
|
298
|
-
# Calculate shift duration
|
|
299
|
-
services.shift.calculate_shift_duration(shift_id: "SHIFT_123")
|
|
300
|
-
```
|
|
301
|
-
|
|
302
|
-
## Cash Drawer Operations
|
|
303
|
-
|
|
304
|
-
Track cash drawer operations for end-of-day reconciliation:
|
|
305
|
-
|
|
306
|
-
```ruby
|
|
307
|
-
# Open cash drawer
|
|
308
|
-
services.cash_event.open_drawer(employee_id: "EMP_123", amount: 10000)
|
|
309
|
-
|
|
310
|
-
# Close cash drawer
|
|
311
|
-
services.cash_event.close_drawer(employee_id: "EMP_123", amount: 15000)
|
|
312
|
-
|
|
313
|
-
# Add cash (e.g., from cash payment)
|
|
314
|
-
services.cash_event.add_cash(employee_id: "EMP_123", amount: 2500, note: "Cash sale")
|
|
315
|
-
|
|
316
|
-
# Remove cash (e.g., cash out)
|
|
317
|
-
services.cash_event.remove_cash(employee_id: "EMP_123", amount: 5000, note: "Bank deposit")
|
|
318
|
-
|
|
319
|
-
# Get drawer total
|
|
320
|
-
services.cash_event.calculate_drawer_total
|
|
321
|
-
```
|
|
322
|
-
|
|
323
|
-
**Note:** Cash event creation may not be fully supported in the Clover sandbox. The simulator handles this gracefully with simulated responses.
|
|
324
|
-
|
|
325
386
|
## Tips
|
|
326
387
|
|
|
327
388
|
Tips vary by dining option to simulate realistic customer behavior:
|
|
@@ -374,24 +435,38 @@ Each meal period has different dining option distributions:
|
|
|
374
435
|
|
|
375
436
|
```
|
|
376
437
|
clover_sandbox_simulator/
|
|
377
|
-
├── bin/simulate # CLI entry point
|
|
438
|
+
├── bin/simulate # CLI entry point (Thor)
|
|
378
439
|
├── lib/
|
|
379
|
-
│ ├── clover_sandbox_simulator.rb # Gem entry point
|
|
440
|
+
│ ├── clover_sandbox_simulator.rb # Gem entry point, VERSION constant
|
|
380
441
|
│ └── clover_sandbox_simulator/
|
|
381
442
|
│ ├── configuration.rb # Multi-merchant config from .env.json
|
|
443
|
+
│ ├── database.rb # PostgreSQL connection management
|
|
444
|
+
│ ├── seeder.rb # Idempotent FactoryBot seeder
|
|
382
445
|
│ ├── parallel_executor.rb # Concurrent execution support
|
|
446
|
+
│ ├── models/ # ActiveRecord models (standalone, no Rails)
|
|
447
|
+
│ │ ├── record.rb # Base class for all models
|
|
448
|
+
│ │ ├── business_type.rb # 9 business types with industries
|
|
449
|
+
│ │ ├── category.rb # 38 categories per business type
|
|
450
|
+
│ │ ├── item.rb # 168 items with pricing & variants
|
|
451
|
+
│ │ ├── simulated_order.rb # Generated order audit records
|
|
452
|
+
│ │ ├── simulated_payment.rb # Payment audit records by tender type
|
|
453
|
+
│ │ ├── api_request.rb # Full HTTP request/response audit log
|
|
454
|
+
│ │ └── daily_summary.rb # Automated daily aggregation
|
|
455
|
+
│ ├── db/
|
|
456
|
+
│ │ ├── migrate/ # 8 PostgreSQL migrations (UUID PKs)
|
|
457
|
+
│ │ └── factories/ # FactoryBot factories (shared with seeder)
|
|
383
458
|
│ ├── services/
|
|
384
|
-
│ │ ├── base_service.rb
|
|
385
|
-
│ │ └── clover/
|
|
459
|
+
│ │ ├── base_service.rb # HTTP client, error handling, audit logging
|
|
460
|
+
│ │ └── clover/ # Clover API services
|
|
386
461
|
│ │ ├── inventory_service.rb # Categories, items, modifier groups
|
|
387
462
|
│ │ ├── order_service.rb # Orders, line items, modifiers
|
|
388
|
-
│ │ ├── payment_service.rb # Payments, splits
|
|
389
|
-
│ │ ├── tender_service.rb # Payment tenders
|
|
463
|
+
│ │ ├── payment_service.rb # Payments, splits, card payments
|
|
464
|
+
│ │ ├── tender_service.rb # Payment tenders, card detection
|
|
465
|
+
│ │ ├── ecommerce_service.rb # Card tokenization & charges
|
|
390
466
|
│ │ ├── tax_service.rb # Tax rates, per-item taxes
|
|
391
|
-
│ │ ├── discount_service.rb # Discounts, promos, combos
|
|
467
|
+
│ │ ├── discount_service.rb # Discounts, promos, combos, loyalty
|
|
392
468
|
│ │ ├── employee_service.rb # Employee management
|
|
393
469
|
│ │ ├── customer_service.rb # Customer management
|
|
394
|
-
│ │ ├── ecommerce_service.rb # Card payments via Ecommerce API
|
|
395
470
|
│ │ ├── refund_service.rb # Full/partial refunds
|
|
396
471
|
│ │ ├── gift_card_service.rb # Gift card management
|
|
397
472
|
│ │ ├── service_charge_service.rb # Service charges, auto-gratuity
|
|
@@ -401,18 +476,18 @@ clover_sandbox_simulator/
|
|
|
401
476
|
│ │ ├── oauth_service.rb # Token refresh
|
|
402
477
|
│ │ └── services_manager.rb # Thread-safe service access
|
|
403
478
|
│ ├── generators/
|
|
404
|
-
│ │ ├── data_loader.rb #
|
|
479
|
+
│ │ ├── data_loader.rb # DB-first data loading with JSON fallback
|
|
405
480
|
│ │ ├── entity_generator.rb # Setup entities (idempotent)
|
|
406
|
-
│ │ └── order_generator.rb # Generate realistic orders
|
|
481
|
+
│ │ └── order_generator.rb # Generate realistic orders & payments
|
|
407
482
|
│ └── data/
|
|
408
|
-
│ └── restaurant/ # JSON data files
|
|
483
|
+
│ └── restaurant/ # JSON data files (fallback for DB)
|
|
409
484
|
│ ├── categories.json
|
|
410
485
|
│ ├── items.json
|
|
411
486
|
│ ├── discounts.json
|
|
412
487
|
│ ├── tenders.json
|
|
413
488
|
│ ├── modifiers.json
|
|
414
489
|
│ └── tax_rates.json
|
|
415
|
-
└── spec/ #
|
|
490
|
+
└── spec/ # 1124 examples, 0 failures
|
|
416
491
|
```
|
|
417
492
|
|
|
418
493
|
## Development
|
|
@@ -427,6 +502,9 @@ bundle exec rspec --format documentation
|
|
|
427
502
|
# Run specific test file
|
|
428
503
|
bundle exec rspec spec/services/clover/tender_service_spec.rb
|
|
429
504
|
|
|
505
|
+
# Run model specs
|
|
506
|
+
bundle exec rspec spec/models/
|
|
507
|
+
|
|
430
508
|
# Run integration tests (requires .env.json with valid credentials)
|
|
431
509
|
bundle exec rspec spec/integration/
|
|
432
510
|
|
|
@@ -435,24 +513,30 @@ bundle exec rubocop
|
|
|
435
513
|
|
|
436
514
|
# Open console
|
|
437
515
|
bundle exec irb -r ./lib/clover_sandbox_simulator
|
|
516
|
+
|
|
517
|
+
# Build the gem
|
|
518
|
+
gem build clover_sandbox_simulator.gemspec
|
|
438
519
|
```
|
|
439
520
|
|
|
440
521
|
## Testing
|
|
441
522
|
|
|
442
|
-
The gem includes comprehensive RSpec tests with WebMock for HTTP stubbing
|
|
523
|
+
The gem includes comprehensive RSpec tests with WebMock for HTTP stubbing, VCR for integration tests, and DatabaseCleaner for test isolation.
|
|
443
524
|
|
|
444
525
|
### Test Coverage
|
|
445
526
|
|
|
446
|
-
- **
|
|
447
|
-
-
|
|
448
|
-
-
|
|
527
|
+
- **1124 examples, 0 failures, 3 pending**
|
|
528
|
+
- Database connection management and migration
|
|
529
|
+
- Seeder idempotency (9 business types, 38 categories, 168 items)
|
|
530
|
+
- FactoryBot factory validation (219 factories/traits)
|
|
531
|
+
- All ActiveRecord models (validations, scopes, associations)
|
|
449
532
|
- All Clover API services:
|
|
450
533
|
- InventoryService (categories, items, modifier groups)
|
|
451
534
|
- OrderService (create, line items, dining options, modifiers)
|
|
452
535
|
- PaymentService (single, split, and card payments)
|
|
453
|
-
- TenderService (tender selection)
|
|
536
|
+
- TenderService (tender selection, card detection, ecommerce filtering)
|
|
537
|
+
- EcommerceService (tokenization, charges, refunds)
|
|
454
538
|
- TaxService (rates, per-item calculation, item associations)
|
|
455
|
-
- DiscountService (percentage, fixed, time-based, loyalty)
|
|
539
|
+
- DiscountService (percentage, fixed, time-based, loyalty, combo, promo codes)
|
|
456
540
|
- EmployeeService (CRUD, deterministic setup)
|
|
457
541
|
- CustomerService (CRUD, anonymous orders)
|
|
458
542
|
- RefundService (full/partial refunds, multiple strategies)
|
|
@@ -462,42 +546,64 @@ The gem includes comprehensive RSpec tests with WebMock for HTTP stubbing and VC
|
|
|
462
546
|
- OrderTypeService (CRUD, default setup)
|
|
463
547
|
- CashEventService (drawer operations, simulated responses)
|
|
464
548
|
- ServicesManager (thread-safe memoization, lazy loading)
|
|
465
|
-
-
|
|
466
|
-
- Order generator (meal periods, dining options, tips, refunds, modifiers, service charges)
|
|
467
|
-
-
|
|
549
|
+
- Audit trail (API request logging, order/payment tracking, daily summaries)
|
|
550
|
+
- Order generator (meal periods, dining options, tips, card payments, fallbacks, refunds, modifiers, service charges)
|
|
551
|
+
- Data loader (DB-first with JSON fallback, format parity)
|
|
552
|
+
- Multi-business type integration (industry classification, order profiles)
|
|
553
|
+
- Financial data quality validation
|
|
554
|
+
- Edge cases (nil handling, empty arrays, API errors, network failures)
|
|
468
555
|
- VCR integration tests for real API validation
|
|
469
556
|
|
|
470
557
|
### Test Files
|
|
471
558
|
|
|
472
559
|
```
|
|
473
560
|
spec/
|
|
474
|
-
├──
|
|
561
|
+
├── audit_logging_spec.rb # BaseService audit + OrderGenerator tracking
|
|
562
|
+
├── configuration_spec.rb # Multi-merchant config validation
|
|
563
|
+
├── configuration_database_url_spec.rb # DATABASE_URL parsing
|
|
564
|
+
├── database_spec.rb # Connection management, migrations
|
|
565
|
+
├── seeder_spec.rb # Idempotent seeding, business types
|
|
566
|
+
├── factories/
|
|
567
|
+
│ └── factories_spec.rb # 219 factory/trait validation
|
|
475
568
|
├── generators/
|
|
476
|
-
│ ├── data_loader_spec.rb
|
|
477
|
-
│ ├── entity_generator_spec.rb
|
|
478
|
-
│ └── order_generator_spec.rb
|
|
479
|
-
├──
|
|
480
|
-
│ ├──
|
|
481
|
-
│ ├──
|
|
482
|
-
│ ├──
|
|
483
|
-
│ ├──
|
|
484
|
-
│ ├──
|
|
485
|
-
│ ├──
|
|
486
|
-
│ ├──
|
|
487
|
-
│
|
|
488
|
-
|
|
489
|
-
│ ├──
|
|
490
|
-
│ ├──
|
|
491
|
-
│ ├──
|
|
492
|
-
│ ├──
|
|
493
|
-
│ ├──
|
|
494
|
-
│
|
|
495
|
-
|
|
496
|
-
|
|
497
|
-
|
|
498
|
-
├──
|
|
499
|
-
├──
|
|
500
|
-
|
|
569
|
+
│ ├── data_loader_spec.rb # DB/JSON loading, format parity
|
|
570
|
+
│ ├── entity_generator_spec.rb # Idempotent setup
|
|
571
|
+
│ └── order_generator_spec.rb # Payments, tips, dining, card flow
|
|
572
|
+
├── integration/
|
|
573
|
+
│ ├── audit_trail_spec.rb # End-to-end order/payment/summary
|
|
574
|
+
│ ├── data_loader_compat_spec.rb # DB vs JSON compatibility
|
|
575
|
+
│ ├── multi_business_spec.rb # 9 business types, industries
|
|
576
|
+
│ ├── modifier_groups_spec.rb # VCR: real API
|
|
577
|
+
│ ├── service_charges_spec.rb # VCR: real API
|
|
578
|
+
│ ├── order_types_spec.rb # VCR: real API
|
|
579
|
+
│ ├── cash_events_spec.rb # VCR: real API
|
|
580
|
+
│ └── tax_rates_spec.rb # VCR: real API
|
|
581
|
+
├── models/
|
|
582
|
+
│ ├── api_request_spec.rb # Scopes, validations
|
|
583
|
+
│ ├── business_type_spec.rb # Industries, associations
|
|
584
|
+
│ ├── category_spec.rb # Scoped uniqueness
|
|
585
|
+
│ ├── daily_summary_spec.rb # Aggregation, idempotency
|
|
586
|
+
│ ├── item_spec.rb # Pricing, variants, scopes
|
|
587
|
+
│ ├── record_spec.rb # Base class
|
|
588
|
+
│ ├── simulated_order_spec.rb # Status transitions, scopes
|
|
589
|
+
│ └── simulated_payment_spec.rb # Tender classification, scopes
|
|
590
|
+
└── services/clover/
|
|
591
|
+
├── cash_event_service_spec.rb
|
|
592
|
+
├── customer_service_spec.rb
|
|
593
|
+
├── discount_service_spec.rb
|
|
594
|
+
├── employee_service_spec.rb
|
|
595
|
+
├── financial_data_quality_spec.rb
|
|
596
|
+
├── gift_card_service_spec.rb
|
|
597
|
+
├── inventory_service_spec.rb
|
|
598
|
+
├── order_service_spec.rb
|
|
599
|
+
├── order_type_service_spec.rb
|
|
600
|
+
├── payment_service_spec.rb
|
|
601
|
+
├── refund_service_spec.rb
|
|
602
|
+
├── service_charge_service_spec.rb
|
|
603
|
+
├── services_manager_spec.rb
|
|
604
|
+
├── shift_service_spec.rb
|
|
605
|
+
├── tax_service_spec.rb
|
|
606
|
+
└── tender_service_spec.rb
|
|
501
607
|
```
|
|
502
608
|
|
|
503
609
|
### Idempotency Verification
|
|
@@ -519,6 +625,7 @@ The tests verify:
|
|
|
519
625
|
- Tax rates are not duplicated
|
|
520
626
|
- Order types are not duplicated
|
|
521
627
|
- Employees/customers only created if count threshold not met
|
|
628
|
+
- Database seeder is idempotent across all 9 business types
|
|
522
629
|
|
|
523
630
|
## Sandbox Limitations
|
|
524
631
|
|
|
@@ -526,11 +633,11 @@ Some Clover sandbox operations may return errors or behave differently than prod
|
|
|
526
633
|
|
|
527
634
|
| Feature | Sandbox Support | Notes |
|
|
528
635
|
|---------|-----------------|-------|
|
|
529
|
-
| Service Charge Creation |
|
|
530
|
-
| Cash Event Creation |
|
|
531
|
-
| Item Tax Rate Fetch |
|
|
532
|
-
| Credit Card Payments |
|
|
533
|
-
| Order Creation |
|
|
636
|
+
| Service Charge Creation | Limited | Must pre-configure in dashboard |
|
|
637
|
+
| Cash Event Creation | Limited | Returns 405, simulated locally |
|
|
638
|
+
| Item Tax Rate Fetch | Limited | Returns 405, simulated locally |
|
|
639
|
+
| Credit Card Payments | Full | Via Ecommerce API |
|
|
640
|
+
| Order Creation | Full | Today's date only |
|
|
534
641
|
|
|
535
642
|
The simulator handles these limitations gracefully with fallback behavior.
|
|
536
643
|
|
|
@@ -538,8 +645,9 @@ The simulator handles these limitations gracefully with fallback behavior.
|
|
|
538
645
|
|
|
539
646
|
- **Sandbox URL**: `https://sandbox.dev.clover.com/`
|
|
540
647
|
- **API Version**: v3
|
|
541
|
-
- **Authentication**: Bearer token (OAuth)
|
|
648
|
+
- **Authentication**: Bearer token (OAuth) for Platform API; apikey header for tokenization
|
|
542
649
|
- **Date Limitation**: Clover sandbox only allows creating orders for TODAY
|
|
650
|
+
- **Ecommerce API**: Separate endpoints for card tokenization, charges, and refunds
|
|
543
651
|
|
|
544
652
|
## License
|
|
545
653
|
|
metadata
CHANGED
|
@@ -1,14 +1,13 @@
|
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
|
2
2
|
name: clover_sandbox_simulator
|
|
3
3
|
version: !ruby/object:Gem::Version
|
|
4
|
-
version: 1.5.
|
|
4
|
+
version: 1.5.1
|
|
5
5
|
platform: ruby
|
|
6
6
|
authors:
|
|
7
7
|
- dan1d
|
|
8
|
-
autorequire:
|
|
9
8
|
bindir: bin
|
|
10
9
|
cert_chain: []
|
|
11
|
-
date:
|
|
10
|
+
date: 1980-01-02 00:00:00.000000000 Z
|
|
12
11
|
dependencies:
|
|
13
12
|
- !ruby/object:Gem::Dependency
|
|
14
13
|
name: rest-client
|
|
@@ -309,7 +308,6 @@ homepage: https://github.com/dan1d/clover_sandbox_simulator
|
|
|
309
308
|
licenses:
|
|
310
309
|
- MIT
|
|
311
310
|
metadata: {}
|
|
312
|
-
post_install_message:
|
|
313
311
|
rdoc_options: []
|
|
314
312
|
require_paths:
|
|
315
313
|
- lib
|
|
@@ -324,8 +322,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
|
|
|
324
322
|
- !ruby/object:Gem::Version
|
|
325
323
|
version: '0'
|
|
326
324
|
requirements: []
|
|
327
|
-
rubygems_version: 3.
|
|
328
|
-
signing_key:
|
|
325
|
+
rubygems_version: 3.6.9
|
|
329
326
|
specification_version: 4
|
|
330
327
|
summary: Clover Sandbox Simulator for generating realistic restaurant data
|
|
331
328
|
test_files: []
|