bmoni_embedded_wallets_cards 0.0.1

Embedded wallet and card building blocks for BKey apps: wallet read models, Riverpod notifiers, and composable wallet card widgets built on bkey_uikit.

bmoni_embedded_wallets_cards

Embedded wallet & card building blocks for Flutter apps in the BKey ecosystem — wallet read models, Riverpod notifiers, and composable wallet card widgets built on top of bkey_uikit.

---

✨ Features

• 🧩 Wallet-aware widgets — EmbeddedWalletCard and EmbeddedWalletTransactionsSection, model-aware composites built on bkey_uikit primitives.
• 🔌 Pluggable contracts — bring your own data source, storage, and balance cache; the package depends only on small interfaces.
• ⚡ Riverpod-ready notifiers — EmbeddedWalletListNotifier, EmbeddedWalletBalanceNotifier, and EmbeddedWalletTransactionsNotifier with built-in caching and offline fallback.
• 🛡️ Functional error handling — Either<EmbeddedFailure, T> powered by dartz for predictable success/failure paths.
• 🎨 Brand-coloured backgrounds — six per-currency colour variants (01–06) plus a default, all driven by your EmbeddedWallet model.
• 🧪 Host-friendly — no routing, no l10n, no analytics; you own the app layer, this package owns the wallet/card composition.

📦 Installation

flutter pub add bmoni_embedded_wallets_cards

…or add it manually to your pubspec.yaml:

dependencies:
  bmoni_embedded_wallets_cards: ^0.0.1

Then fetch packages:

flutter pub get

🚀 Quick start

import 'package:bmoni_embedded_wallets_cards/bmoni_embedded_wallets_cards.dart';

Wire a notifier with your own data source and storage, then render the card:

final notifier = EmbeddedWalletListNotifier(
  walletDataSource: walletReadDataSource,
  storage: walletStorage,
);

await notifier.fetchWallets();

EmbeddedWalletCard(
  wallet: notifier.state.wallets!.first,
  isBalanceHidden: false,
  onToggleHideBalance: () {/* toggle in your app state */},
);

🧱 Where this package fits

bmoni_embedded_wallets_cards sits between your design system and your app:

┌────────────────────────────────────────────────────┐
│ Host app  · routing · l10n · analytics · auth      │
├────────────────────────────────────────────────────┤
│ bmoni_embedded_wallets_cards                       │
│ · wallet/card-aware models                         │
│ · Riverpod notifiers                               │
│ · composed widgets                                 │
├────────────────────────────────────────────────────┤
│ bkey_uikit  · design tokens · UI primitives        │
└────────────────────────────────────────────────────┘

• bkey_uikit owns presentational primitives like BMoniWalletCard, BMoniWalletCardBalance, and BMoniWalletCardBackground — they accept already-resolved data and callbacks.
• bmoni_embedded_wallets_cards owns the model-aware adapters that take an EmbeddedWallet and forward to those primitives with the right background, currency formatting, and balance state.
• The host app stays in control of state — pass isBalanceHidden / onToggleHideBalance to wire the card into your own Riverpod or Bloc layer.

📚 Usage

Wallet read data and state

final EmbeddedWalletListNotifier notifier = EmbeddedWalletListNotifier(
  walletDataSource: walletReadDataSource,
  storage: walletStorage,
);

await notifier.fetchWallets();

if (notifier.state.hasError) {
  // notifier.state.failure is an EmbeddedFailure
}

Embedded wallet card

EmbeddedWalletCard(
  wallet: embeddedWallet,
  // Pick a colour variant (01–06) to use the brand-coloured background art,
  // or omit to use the default per-currency background.
  colorSuffix: '04',
  // Wire to your own state management.
  isBalanceHidden: hiddenBalances.contains(embeddedWallet.walletId),
  onToggleHideBalance: () => toggleHidden(embeddedWallet.walletId),
  isLoading: isInitialLoad,
  isRefreshing: isPullToRefreshing,
  onInfoTap: () => openWalletDetails(embeddedWallet),
  onTap: () => openWalletDetails(embeddedWallet),
  // Optional: override the prefix shown before the balance.
  currencySymbol: r'$',
  // Optional: override the entire whole-part formatting.
  formatWholePart: (balance) => formatMyMoney(balance),
)

Embedded transactions section

EmbeddedWalletTransactionsSection(
  title: 'Recent transactions',
  viewAllLabel: 'View all',
  onViewAll: () => openTransactionsHistory(),
  transactions: transactions,
  emptyState: const SizedBox.shrink(),
  itemBuilder: (context, transaction) {
    return Text(transaction.id);
  },
)

The widget intentionally leaves these responsibilities to the host app:

• what an empty state looks like
• how each transaction row is rendered
• what happens on View all

🧰 Public API

A single barrel import exposes everything:

import 'package:bmoni_embedded_wallets_cards/bmoni_embedded_wallets_cards.dart';

Category	Exports
Constants	EmbeddedWalletCacheKeys
Contracts	EmbeddedWalletReadDataSource, EmbeddedWalletStorage, EmbeddedWalletBalanceCache
Failures	EmbeddedFailure, EmbeddedServerFailure, EmbeddedCacheFailure, EmbeddedNetworkFailure, EmbeddedValidationFailure, EmbeddedRateLimitFailure, EmbeddedNotFoundFailure, EmbeddedAuthenticationFailure, EmbeddedAuthorizationFailure
Models	EmbeddedWallet, EmbeddedWalletListResponse, EmbeddedWalletDetailResponse, EmbeddedWalletBalanceResponse, EmbeddedWalletTransactionsResponse, EmbeddedWalletTransaction, EmbeddedTransactionDirection, EmbeddedWalletTransactionStatus
Notifiers	EmbeddedWalletListNotifier, EmbeddedWalletBalanceNotifier, EmbeddedWalletTransactionsNotifier
Widgets	EmbeddedWalletCard, EmbeddedWalletTransactionsSection

🧪 Example app

A runnable, end-to-end example app lives in the example/ directory. It wires this package's notifiers into a Riverpod-based screen with:

• a swipable EmbeddedWalletCard carousel with hide/show balance
• an EmbeddedWalletTransactionsSection that follows the active wallet
• pull-to-refresh fanning out to the list, balance, and transaction notifiers
• in-memory implementations of EmbeddedWalletReadDataSource, EmbeddedWalletStorage, and EmbeddedWalletBalanceCache so it runs without a backend

cd example
flutter pub get
flutter run

See example/README.md for a tour of the wiring.

🧭 Design rules

1. Keep domain-aware composition here, not in bkey_uikit.
2. Keep host concerns out of this package: no GoRouter, no app l10n, no app analytics services.
3. Prefer constructor-injected contracts over direct getIt or app service lookups.
4. Reuse bkey_uikit primitives instead of rebuilding generic layout or typography widgets.

🛠️ Development

Run tests:

flutter test

Regenerate JSON code after model changes:

dart run build_runner build --delete-conflicting-outputs

🤝 Contributing

Issues and PRs are welcome on GitHub. Please run flutter test and flutter analyze before opening a PR.

📄 License

Copyright © 2026 Bkey, Inc.

Licensed under the Apache License, Version 2.0 — you may use, modify, and distribute this package (including in proprietary applications) provided you preserve the copyright and license notices and comply with the terms in the LICENSE file.

For commercial support or enterprise inquiries, contact [e-mail].