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

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.

2.6 KiB Raw Blame History