KIOSK-254 — Pages to Apply USD Wallet Wording Changes
| Field | Value |
|---|---|
| Task ID | KIOSK-254 |
| Goal | Align USD Wallet transaction names and financial labels across 3 operational portals |
| In scope | kioskgaming_admin, kioskgaming_superagent, kioskgaming_agent, shared UI packages/ui (portal-usd-wallet, portal-ledger) |
| Out of scope (v1) | Shop portal (kioskgaming_shop), route URL changes (/online-transactions), internal variable/API renames (onlineBalanceNet, fetchAgentOnlineBalanceLedger), DB schema |
| Related | Finance System · Admin USD wallet detail view · Task-kiosk-260 (correction / reversal / refund labels on Admin) |
1. Background
In the codebase, USD Wallet (usd_wallets + usd_wallet_transactions) is the real-money (USD) wallet used to buy credit, receive settlement deposits, and withdraw crypto. However, the UI still has many legacy names:
| Legacy term | Issue |
|---|---|
| Online balance | Does not match product name; users do not know this is "USD Wallet" |
| Online transactions (Agent nav) | Differs from Super Agent / page title ("USD wallet transactions") |
| Online balance top up / withdrawal (Shop utils) | Shop only — out of scope for KIOSK-254 but same pattern to avoid spreading to in-scope portals |
Ticket goal: one unified vocabulary — prioritize "USD wallet" / "USD Wallet" for product name and balance descriptions; transaction labels shared from @kioskgaming/ui when possible.
2. Wording conventions (source of truth)
2.1 Product name & balance
| Context | Standard label (EN) | Do not use |
|---|---|---|
| Wallet name / sidebar / dashboard card | USD wallet | Online balance, online USD balance |
| Available balance | Current USD balance or USD wallet balance | Online balance, USD online balance |
| Main ledger page | USD wallet transactions | Online transactions |
| Page description | Track USD wallet ledger activity, balances, and withdrawal requests. | Online balance ledger… |
| Withdrawal | Request withdrawal / USD withdrawal | Online balance withdrawal |
| Buy credit from USD | Convert USD wallet balance to credits / USD converted to credits | Convert online balance… |
Capitalization: Nav / page title → sentence case (USD wallet transactions). Short badge / card heading → USD wallet. Modal title may use USD Wallet as proper noun (timeline step).
2.2 Transaction type labels (ledger table & detail)
Shared from packages/ui/src/portal-usd-wallet/ledgerUtils.ts (usdLedgerTypeLabel) and portal-ledger/usdTransactionPresentation.ts (buildUsdBusinessView):
| Signal (type / ref) | List / table label | Detail modal title |
|---|---|---|
deposit | Deposit | USD added to wallet |
withdrawal (payout) | Withdraw | USD withdrawal |
purchase_credits / balance_to_credits | Purchase credits | USD converted to credits |
adjustment credit | Balance Correction — Credit | Wallet adjustment |
adjustment debit | Balance Correction — Debit | Wallet adjustment |
reversal | Transaction Reversal | Wallet activity reversed |
| Refund flows | Refund | (Admin: displayLabel from API — see KIOSK-260) |
| Fallback | USD wallet activity | USD wallet activity |
Admin list/detail: Prefer displayLabel / displayCategory from API (usdLedgerEnrichment) when available — do not duplicate heuristics on frontend. See Task-kiosk-260.
2.3 Status labels (unchanged — already aligned)
Completed · Pending · Processing · Failed · Cancelled — from usdLedgerStatusLabel.
3. Scope — change table by portal
3.1 Admin Portal (kioskgaming_admin)
| Page / Area | Route / file | Current (gap) | Required change |
|---|---|---|---|
| Nav / route meta | /usd-wallets · routes.tsx | Nav title: USD Wallets | Keep or change to USD wallet transactions if product wants parity with other portals; unify breadcrumb |
| USD wallet ledger | usdWallets/index.tsx | Title already USD wallet transactions ✅ | Review toast/export: USD ledger exported → optionally USD wallet ledger exported |
| Ledger detail modal | UsdWalletLedgerDetailModal.tsx · UsdWalletActivityView.tsx | Some copy uses "online balance", "online USD" | Change to USD wallet / USD wallet balance (see §3.1 copy table) |
| Agent detail — balance card | agents/AgentDetailPage.tsx | USD wallet ✅ | Keep; Gross net sublabel unchanged |
| Super Agent detail | superAgents/SuperAgentDetailPage.tsx | USD wallet balance ✅ | Keep |
| Shop detail | agents/ShopDetailPage.tsx | USD wallet ✅ | Keep |
| Finance correction modal | finance/FinanceCorrectionDebitModal.tsx | USD online balance, USD (online balance) | → USD wallet balance / USD wallet |
| Super Agent withdrawal limits | SuperAgentPortalWithdrawalLimitsCard.tsx | Online balance withdrawal limits (USD) | → USD wallet withdrawal limits |
| Payment transaction detail | transactions/TransactionDetails.tsx | paid online USD balance | → paid from USD wallet / used USD wallet balance |
| Cash flow timeline | utils/transactionCashFlowTimeline.ts | USD Wallet, USD wallet movement ✅ | Keep; ensure leg labels match buildUsdBusinessView |
| Credit wallet cross-ref | CreditWalletActivityView.tsx | USD wallet transaction ✅ | Keep |
| Provider fees table | providerFees/providerFeesColumns.tsx | USD wallet · internal transfer ✅ | Keep |
Admin activity copy — specific replacements (UsdWalletActivityView.tsx):
| Old pattern | New pattern |
|---|---|
converted online balance to | converted USD wallet balance to |
used online USD to buy | used USD wallet balance to buy |
| (copy already using "USD wallet") | Keep |
3.2 Super Agent Portal (kioskgaming_superagent)
| Page / Area | Route / file | Current (gap) | Required change |
|---|---|---|---|
| Sidebar nav | AppLayout.tsx · /online-transactions | USD wallet transactions ✅ | Keep |
| Breadcrumb | superAgentBreadcrumb.ts | USD wallet transactions ✅ | Keep |
| Ledger page | OnlineBalanceTransactionsPage.tsx | Page title USD wallet transactions ✅ | Review hook toast: Could not load online balance ledger → USD wallet ledger |
| Dashboard | DashboardPage.tsx | Card USD wallet + link USD wallet transactions ✅ | Keep |
| Sidebar balance | AppLayout.tsx | Current USD balance ✅ | Optionally change to USD wallet balance to match Admin Super Agent detail |
| Credit purchase | CreditPurchaseModal.tsx · CreditPurchaseTrigger.tsx | online USD balance, Insufficient online balance, Use online USD balance | → USD wallet balance / Insufficient USD wallet balance |
| Managed shop wallet | ManagedShopWalletHistoryPanel.tsx | Tab label USD wallet, empty No USD wallet transactions yet ✅ | Keep |
| Credit / USD tx list | AgentTransactionsPage.tsx | Uses UsdWalletTransactionDetailModal from UI package | Labels from shared package (§4) |
| Provider fees | providerFees/MethodCell.tsx | USD wallet · internal transfer ✅ | Keep |
| Hooks / errors | useSuperAgentOnlineBalanceLedger.ts | Could not load online balance ledger | → Could not load USD wallet ledger |
3.3 Agent Portal (kioskgaming_agent)
| Page / Area | Route / file | Current (gap) | Required change |
|---|---|---|---|
| Sidebar nav | AppLayout.tsx · /online-transactions | Online transactions ❌ | → USD wallet transactions (match Super Agent + page title) |
| Ledger page | OnlineBalanceTransactionsPage.tsx | Title USD wallet transactions ✅ | Sync nav (above) |
| Sidebar balance | AppLayout.tsx | Current USD balance ✅ | Optional: USD wallet balance |
| Shop detail — tab | ShopDetailPageRedesign.tsx | Tab USD wallet tx | → USD wallet transactions (or USD wallet if space constrained) |
| Shop detail — section | ShopDetailPageRedesign.tsx | Subtitle Online balance (USD wallet) ledger entries | → USD wallet ledger entries |
| Shop detail — empty/loading | ShopDetailPageRedesign.tsx | Loading USD transactions…, No USD transactions yet | → USD wallet transactions |
| Credit purchase | CreditPurchaseModal.tsx · CreditPurchaseTrigger.tsx | Same as Super Agent — online balance | → USD wallet balance |
| Provider fees | providerFees/MethodCell.tsx | USD wallet · internal transfer ✅ | Keep |
| Hooks / errors | useAgentOnlineBalanceLedger.ts | Could not load online balance ledger | → Could not load USD wallet ledger |
4. Shared UI package (packages/ui)
Agent + Super Agent (+ partial Admin list) share this module. Fix once → all 3 portals benefit (except Admin-specific detail).
| Module | Main file | Wording to review |
|---|---|---|
portal-usd-wallet | ledgerUtils.ts | usdLedgerTypeLabel, usdPartyDisplayLabel, summary grid |
PortalUsdWalletSummaryGrid.tsx | Current USD balance, Available for withdrawal ✅ | |
PortalUsdWalletLedgerTable.tsx | Column headers: Owner, Type, Status, Balance before/after (net)… | |
PortalWithdrawalLimitsPanel.tsx | Withdrawal limit copy | |
portal-ledger | usdTransactionPresentation.ts | Many places use online USD balance / online balance → change to USD wallet (balance) |
UsdWalletTransactionDetailModal.tsx | Title from buildUsdBusinessView | |
cashFlowTimelineSample.ts | Sample Online balance → USD wallet |
4.1 usdTransactionPresentation.ts — target copy
| Field | Current | Change to |
|---|---|---|
summaryLine (B2C) | …from your online balance into credits | …from your USD wallet into credits |
subtitle (deposit) | Your online USD balance increased | Your USD wallet balance increased |
subtitle (withdrawal) | …from your online USD balance | …from your USD wallet |
subtitle (generic) | …affected your online USD balance | …affected your USD wallet balance |
balanceRows label | Total debited from USD Wallet | Keep (already correct) |
5. Implementation architecture
┌─────────────────────────────────────────────────────────────┐
│ packages/ui │
│ portal-usd-wallet/ledgerUtils.ts │
│ portal-ledger/usdTransactionPresentation.ts │
└───────────────────────────┬─────────────────────────────────┘
│ import @kioskgaming/ui
┌───────────────────┼───────────────────┐
▼ ▼ ▼
kioskgaming_agent kioskgaming_superagent kioskgaming_admin
(nav, hooks, (hooks, credit (usdWalletLedgerUtils,
shop detail, purchase copy) ActivityView, finance modal)
credit purchase)
Suggested order:
- UI package — transaction detail + type labels (
K254-UI-1) - Agent + Super Agent — nav, hooks, credit purchase, shop detail (
K254-AG-1,K254-SA-1) - Admin — remaining "online balance" + finance/super-agent cards (
K254-AD-1) - QC grep — no user-facing
online balanceon 3 in-scope apps (K254-QC-1)
Do not change in this task: hook name useAgentOnlineBalanceLedger, endpoint online-balance, API field online_balance_net — only change display strings.
6. Implementation plan (reviewable tasks)
| ID | Task | Repo | Size |
|---|---|---|---|
| K254-UI-1 | Replace online balance / online USD strings in usdTransactionPresentation.ts + tests | packages/ui | S |
| K254-UI-2 | Review ledgerUtils.ts + PortalUsdWalletSummaryGrid (if USD wallet balance label needed) | packages/ui | XS |
| K254-SA-1 | Super Agent: credit purchase copy + hook error toast | kioskgaming_superagent | XS |
| K254-AG-1 | Agent: nav label, shop detail subtitles, credit purchase, hook toast | kioskgaming_agent | S |
| K254-AD-1 | Admin: UsdWalletActivityView, FinanceCorrectionDebitModal, SuperAgentPortalWithdrawalLimitsCard, TransactionDetails | kioskgaming_admin | S |
| K254-QC-1 | Grep gate + QC checklist (§7) | all | XS |
KIOSK-260 dependency: Admin badge Refund / Balance Correction from API displayLabel — K254 does not change classification logic; only ensure narrative text uses "USD wallet" instead of "online balance".
7. Test plan (QC)
7.1 Agent — nav consistency
- Login to Agent portal.
- Sidebar item
/online-transactionsshowsUSD wallet transactions(no longer "Online transactions"). - Page header uses same wording.
7.2 Shared detail modal
- Open a Purchase credits row on Agent or Super Agent.
- Modal: title
USD converted to credits; body contains no "online balance".
7.3 Withdrawal flow copy
- Open Request withdrawal modal.
- Label
Current USD balance/ validation message uses USD wallet terminology.
7.4 Admin finance correction
- Open finance correction debit modal, select USD wallet.
- No option label
USD (online balance).
7.5 Shop detail (Agent)
- Agent → Shop detail → USD tab.
- Subtitle
USD wallet ledger entries; empty stateNo USD wallet transactions yet.
7.6 Regression grep (automatable)
# User-facing strings — expect 0 matches in src/ (allow comments & API field names)
rg -i 'online balance' kioskgaming_admin/src kioskgaming_agent/src kioskgaming_superagent/src packages/ui/src \
--glob '!**/*.test.*'
Allowed exceptions: code comments, variable name onlineBalanceNet, JSDoc @param onlineBalance.
8. Acceptance criteria
- AC-1: All three portals use the same page name
USD wallet transactionsfor the main ledger (nav + header). - AC-2: No user-facing "online balance" / "online transactions" (Agent nav) on in-scope surfaces.
- AC-3: Detail modal & shared ledger labels use USD wallet (balance) instead of legacy online wording.
- AC-4: Admin entity cards (agent / super agent / shop) still show USD wallet balance — no regression.
- AC-5: Transaction type labels consistent between list table and detail modal (shared package).
9. File index (quick lookup)
| Portal | Files |
|---|---|
| Shared | packages/ui/src/portal-usd-wallet/ledgerUtils.ts, PortalUsdWalletSummaryGrid.tsx, packages/ui/src/portal-ledger/usdTransactionPresentation.ts |
| Admin | usdWallets/index.tsx, UsdWalletActivityView.tsx, usdWalletLedgerUtils.ts, finance/FinanceCorrectionDebitModal.tsx, superAgents/SuperAgentPortalWithdrawalLimitsCard.tsx, transactions/TransactionDetails.tsx, agents/*DetailPage.tsx, agents/ShopDetailPage.tsx |
| Super Agent | pages/OnlineBalanceTransactionsPage.tsx, components/layout/AppLayout.tsx, components/credits/CreditPurchase*.tsx, hooks/useSuperAgentOnlineBalanceLedger.ts, components/shops/ManagedShopWalletHistoryPanel.tsx |
| Agent | pages/OnlineBalanceTransactionsPage.tsx, pages/ShopDetailPageRedesign.tsx, components/layout/AppLayout.tsx, components/credits/CreditPurchase*.tsx, hooks/useAgentOnlineBalanceLedger.ts |
10. Definition of done
- All AC (§8) pass on staging.
-
packages/uibuild + Agent/Super Agent/Admin consume new UI version. - Grep gate §7.6 pass (with documented allowlist).
- PR description links this doc + notes overlap with KIOSK-260 if same release.
11. Notes for PM / copywriter
If Jira KIOSK-254 has a more detailed Required change table (per deposit/settlement/payout scenario), add new rows to §3 — this doc maps from codebase inventory when ticket image detail is unavailable.
Labels Balance Correction / Transaction Reversal / Refund belong to KIOSK-260; KIOSK-254 only covers USD Wallet product name and online → USD wallet narrative, not correction taxonomy.