84 lines
2.6 KiB
Markdown
84 lines
2.6 KiB
Markdown
# OpenSpec Change: enterprise-gaming-api-plugin-virtual-currency
|
|
|
|
- **Change ID**: enterprise-gaming-api-plugin-virtual-currency
|
|
- **Package**: `@suaveplan/api-plugin-virtual-currency`
|
|
- **Category**: gaming/server
|
|
- **Target path**: `gaming/server/api-plugin-virtual-currency`
|
|
- **Status**: PROPOSED
|
|
- **Date**: 2026-04-24
|
|
- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/api-plugin-virtual-currency.md`
|
|
|
|
---
|
|
|
|
## Summary
|
|
|
|
Deliver `@suaveplan/api-plugin-virtual-currency` on the genesis branch from scratch at enterprise quality. The package provides virtual currency wallets, transfers, premium purchases, and cashout. A `VirtualCurrencyService` manages per-player multi-wallet balances, a `PurchaseService` handles real-money-to-VC conversion (injectable payment gateway), and a `CashoutService` manages VC-to-reward conversion with configurable rate and daily limits. HTTP routes expose wallet, purchase, cashout, and transfer endpoints. Genesis adds Zod schemas, structured errors, OTel transaction counters, injectable clock, and 100% coverage.
|
|
|
|
---
|
|
|
|
## Current-state audit (genesis)
|
|
|
|
Package does not exist on genesis yet — fresh build.
|
|
|
|
---
|
|
|
|
## Available workspace deps on genesis
|
|
|
|
| Package | Role |
|
|
|---|---|
|
|
| `@suaveplan/error` (`workspace:^`) | `VCError`; `VC.*` codes |
|
|
| `@suaveplan/types` (`workspace:^`) | `Clock` |
|
|
| `@suaveplan/economy` (`workspace:^`) | `Wallet` for VC balance |
|
|
| `@suaveplan/events` (`workspace:^`) | `vc:purchase`, `vc:transfer`, `vc:cashout` events |
|
|
| `zod` (`catalog:forms`) | Request schemas |
|
|
| `@opentelemetry/api` (`catalog:observability`) | Transaction counter |
|
|
|
|
---
|
|
|
|
## HTTP Routes
|
|
|
|
| Method | Path | Description |
|
|
|---|---|---|
|
|
| `GET` | `/wallets/:playerId` | Get VC balance |
|
|
| `POST` | `/wallets/:playerId/purchase` | Buy VC with real money |
|
|
| `POST` | `/wallets/:playerId/transfer` | Transfer VC to player |
|
|
| `POST` | `/wallets/:playerId/cashout` | Convert VC to rewards |
|
|
| `GET` | `/wallets/:playerId/history` | Transaction history |
|
|
| `GET` | `/config` | Rates and limits |
|
|
|
|
---
|
|
|
|
## File layout
|
|
|
|
```text
|
|
gaming/server/api-plugin-virtual-currency/
|
|
package.json
|
|
tsconfig.json
|
|
vitest.config.ts
|
|
src/
|
|
index.ts
|
|
error-codes.ts
|
|
types/common.ts
|
|
types/common.md
|
|
services/
|
|
vc-service/
|
|
vc-service.ts
|
|
vc-service.md
|
|
vc-service.types.ts
|
|
vc-service.test.ts
|
|
index.ts
|
|
routes/
|
|
wallets.ts
|
|
wallets.md
|
|
plugin.ts
|
|
plugin.md
|
|
tests/
|
|
integration.test.ts
|
|
```
|
|
|
|
---
|
|
|
|
## Impact
|
|
|
|
**Downstream**: `@suaveplan/react-bank` reads VC wallet. Prerequisites: `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/economy`, `@suaveplan/events`.
|