# WalletRewards

OTP application managing customer rewards, points ledger, and offers within the MercuryPay umbrella.

## Public Interface

```elixir
# Reward transactions
WalletRewards.RewardStore.store(reward_txn)
WalletRewards.RewardStore.list_by_user(user_id)

# Points balances
WalletRewards.PointsStore.store(points_balance)
WalletRewards.PointsStore.get(user_id)
WalletRewards.PointsStore.update(points_balance)

# Offers
WalletRewards.OfferStore.store(offer)
WalletRewards.OfferStore.get(offer_id)
WalletRewards.OfferStore.list_all()
WalletRewards.OfferStore.list_active()
WalletRewards.OfferStore.update(offer)
```

## Responsibilities
- Reward transaction recording (cashback, bonuses, incentives).
- Points ledger: accumulation, adjustment, and redemption.
- Offer catalog management (active / inactive offers).

## Forbidden Dependencies
- **wallet_ledger** — no direct ledger writes from this app.
- **wallet_auth** — no auth logic in this app.
- **wallet_accounts** — does not own account state.

## Dependencies
- `wallet_shared_kernel` — TypedId, Money, Correlation.
- `wallet_observability` — AuditEvent, Telemetry.
- `wallet_events` — DomainEvent behaviour.
- `wallet_database` — write-through persistence (RewardTransactionPersistence, PointsBalancePersistence, OfferPersistence).

## TypedId Prefixes
- `rwdtxn_` — reward transactions.
- `pts_` — points balances.
- `offer_` — offers.

## Events Emitted
- `WalletRewards.Events.PointsAdjusted.v1`
- `WalletRewards.Events.PointsRedeemed.v1`
- `WalletRewards.Events.OfferCreated.v1`

## Stores
- `WalletRewards.RewardStore` — ETS-backed GenServer; MySQL write-through via `RewardTransactionPersistence`.
- `WalletRewards.PointsStore` — ETS-backed GenServer; MySQL write-through via `PointsBalancePersistence`.
- `WalletRewards.OfferStore` — ETS-backed GenServer; MySQL write-through via `OfferPersistence`.