🚀 Baiomy

Built once, used everywhere.

A powerful, all-in-one Flutter toolkit for local storage, password encryption, Egyptian ID parsing, input validation, utilities, and widgets — all behind a single import.

import 'package:baiomy/baiomy.dart';

---

📦 What's Inside

Module	Classes / APIs
🗂️ Local Storage	BaiomySharedPrefs · BaiomySecureStorage · StorageException
🔐 Password Encryption	BaiomyPasswordEncryption · PasswordHasher · EncryptedPayload · HashedPassword · CryptoException
🌍 Egyptian ID Parser	BaiomyEgyptianIdParser
🚧 Routes	BaiomyNavKit
🪄 Firebase	BaiomyStorageRepo · BaiomyAuthRepo · BaiomyFirestoreRepo
🧩 Extensions	BuildContextExtension · FormAutoScroll · EmailValidator · PasswordValidator · NotesValidator · DomainValidator
🛠️ Utils	BaiomyInputFormatters · inputDecoration() · BaiomyLogger · BaiomyGoogleMapsExtractor
🎨 Widgets	BaiomyToast · BaiomyAvatarGlow · BaiomyConditionalBuilder · CustomSizedBox · BaiomyValueListenableBuilder2 · BaiomyLoadingItem · BaiomySegmentedCircularNextButton

---

📥 Installation

dependencies:
  baiomy:
    git:
      url: https://github.com/mohamedelbaiomy/baiomy.git

flutter pub get

---

⚡ Setup — once in main.dart

import 'package:baiomy/baiomy.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  // Required before using BaiomySharedPrefs
  await BaiomySharedPrefs.instance.init();

  // Required before using BaiomyPasswordEncryption
  BaiomyPasswordEncryption.instance.configure(keyPhrase: 'your-secret-phrase');

  runApp(const MyApp());
}

---

🗂️ Local Storage

BaiomySharedPrefs

Non-sensitive data — settings, flags, UI state. Backed by SharedPreferences. Reads are synchronous after init().

final prefs = BaiomySharedPrefs.instance;

// ── Write ──────────────────────────────────────────────────────────────
await prefs.setString('theme', 'dark');
await prefs.setInt('launch_count', 1);
await prefs.setBool('onboarding_done', value: true);
await prefs.setDouble('font_size', 16.0);
await prefs.setStringList('tags', ['flutter', 'dart']);
await prefs.setObject('config', {'lang': 'en', 'theme': 'dark'});

// ── Read ───────────────────────────────────────────────────────────────
final theme  = prefs.getString('theme', defaultValue: 'light');
final count  = prefs.getInt('launch_count', defaultValue: 0);
final done   = prefs.getBool('onboarding_done');
final size   = prefs.getDouble('font_size');
final tags   = prefs.getStringList('tags');
final config = prefs.getObject('config');     // Map<String, dynamic>?

// ── Update (key must already exist, throws otherwise) ──────────────────
await prefs.updateString('theme', 'light');
await prefs.updateInt('launch_count', 2);
await prefs.updateBool('onboarding_done', newValue: false);
await prefs.updateDouble('font_size', 18.0);
await prefs.patchObject('config', {'theme': 'light'}); // partial update

// ── Remove ─────────────────────────────────────────────────────────────
await prefs.remove('theme');
await prefs.clear(); // ⚠️ wipes everything

// ── Utility ────────────────────────────────────────────────────────────
prefs.containsKey('theme'); // bool
prefs.getKeys();            // Set<String>
prefs.get('theme');         // dynamic

---

BaiomySecureStorage

Sensitive data — tokens, passwords, PII. Encrypted at rest via platform Keychain (iOS) / Keystore (Android). All reads are async.

final secure = BaiomySecureStorage.instance;

// ── Write ──────────────────────────────────────────────────────────────
await secure.setString('access_token', 'eyJhbGci...');
await secure.setBool('biometrics_enabled', value: true);
await secure.setInt('user_id', 42);
await secure.setDouble('score', 9.5);
await secure.setObject('session', {'expires_at': 1700000000});

// ── Read ───────────────────────────────────────────────────────────────
final token   = await secure.getString('access_token');
final enabled = await secure.getBool('biometrics_enabled');
final uid     = await secure.getInt('user_id');
final session = await secure.getObject('session');

// ── Update (key must already exist, throws otherwise) ──────────────────
await secure.updateString('access_token', 'newToken');
await secure.updateBool('biometrics_enabled', newValue: false);
await secure.updateInt('user_id', 99);
await secure.updateDouble('score', 10.0);
await secure.patchObject('session', {'scope': 'read write'});

// ── Remove ─────────────────────────────────────────────────────────────
await secure.remove('access_token');
await secure.removeMany(['access_token', 'session']); // batch
await secure.clear(); // ⚠️ wipes everything

// ── Utility ────────────────────────────────────────────────────────────
await secure.containsKey('access_token'); // Future<bool>
await secure.getKeys();                   // Future<Set<String>>
await secure.getAll();                    // Future<Map<String, String>>

---

🔐 Password Encryption

Which one should I use?

Need to recover the original password later?  →  BaiomyPasswordEncryption  (AES-256 two-way)
Just need to verify it at login?              →  PasswordHasher            (PBKDF2 one-way)

---

BaiomyPasswordEncryption — Two-way AES-256-CBC

Encrypts any string and lets you get the original value back. Every encrypt call produces a different ciphertext even for the same input because a fresh random IV is generated each time.

Configure once in main():

BaiomyPasswordEncryption.instance.configure(keyPhrase: 'your-secret-phrase');

Encrypt & store in Firestore:

final payload = BaiomyPasswordEncryption.instance.encrypt(passwordController.text);

// payload.combined   → "ivBase64:ciphertextBase64"  ← store this
// payload.iv         → IV used, Base64-encoded
// payload.cipherText → encrypted value, Base64-encoded

await FirebaseFirestore.instance.collection('users').doc(uid).set({
  'password': payload.combined,
});

Decrypt — recover the original:

final doc  = await FirebaseFirestore.instance.collection('users').doc(uid).get();
final pass = BaiomyPasswordEncryption.instance.decrypt(doc['password'] as String);

Convenience — encrypt directly to a string:

final stored = BaiomyPasswordEncryption.instance.encryptToString(passwordController.text);

Validate a stored value:

BaiomyPasswordEncryption.instance.isValidPayload(stored); // bool

---

PasswordHasher — One-way PBKDF2-HMAC-SHA256

Best for login systems where you never need the original password back. Uses 310,000 iterations (OWASP 2023) + a unique 32-byte random salt. Uses constant-time comparison to prevent timing attacks. The original password cannot be recovered — ever.

Hash on registration:

final hashed = PasswordHasher.instance.hash(passwordController.text);

// hashed.combined   → "310000:saltBase64:hashBase64"  ← store this
// hashed.hash       → derived key, Base64-encoded
// hashed.salt       → random salt, Base64-encoded
// hashed.iterations → 310000

await FirebaseFirestore.instance.collection('users').doc(uid).set({
  'passwordHash': hashed.combined,
});

Verify on login:

final doc = await FirebaseFirestore.instance.collection('users').doc(uid).get();

final ok = PasswordHasher.instance.verify(
  password: passwordController.text,
  combined: doc['passwordHash'] as String,
);

if (!ok) throw Exception('Wrong password');

Validate a stored hash string:

PasswordHasher.instance.isValidHash(storedValue); // bool

---

🌍 Egyptian ID Parser

Parse and extract full information from a 14-digit Egyptian National ID.

final parser = BaiomyEgyptianIdParser('29901011234567');

print(parser.birthDate);    // e.g. "1999-01-01"
print(parser.governorate);  // e.g. "Cairo"
print(parser.gender);       // e.g. "Male"
print(parser.age);          // Age object

---

🧩 Extensions

BuildContextExtension

// Navigation
context.pop();
context.popWithValue('result');
await context.mayBePop(); // Future<bool>

// Screen dimensions
final width  = context.screenWidth;   // double
final height = context.screenHeight;  // double
final dpr    = context.devicePixelRatio; // double

FormAutoScroll

Automatically scrolls to the first invalid field on form submission. Called as an extension on GlobalKey<FormState>:

final _formKey = GlobalKey<FormState>();

// Instead of _formKey.currentState!.validate()
final isValid = _formKey.validateAndScroll(); // bool
// Scrolls to the first field with an error if invalid

EmailValidator

'user@gmail.com'.isValidEmail();          // true
'not-an-email'.isValidEmail();            // false
'user@uni.edu.eg'.isAcademicEmail();      // true
'user@company.com'.isCorporateEmail();    // true
'test@test.com'.hasSuspiciousEmailPattern(); // true
'user@gmail.com'.capitalize();            // 'User@gmail.com'

PasswordValidator

'MyPass1!'.hasUppercase();                // true
'MyPass1!'.hasLowercase();                // true
'MyPass1!'.hasDigit();                    // true
'MyPass1!'.hasSpecialCharacter();         // true
'MyPass1!'.hasWhitespace();              // false
'MyPass1!'.hasMixedCase();               // true
'MyPass1!'.hasMultipleDigits();          // false
'MyPass1!'.hasMultipleSpecialChars();    // false
'password123'.isCommonPassword();         // true
'abc123'.hasSequentialCharacters();       // true
'aaabbb'.hasExcessiveRepeatedCharacters(); // true

NotesValidator

'spam content'.hasInappropriateContent();       // true
'Hello!!!!!!'.hasExcessiveSpecialCharacters();  // true
'aaaaaaa note'.hasExcessiveRepeatedText();      // true
'Study near the library'.hasMeaningfulContent(); // true
'Valid Note.'.hasProperStructure();             // true
'Room 101 level 2'.hasSpecificDetails();        // true
'Near the faculty building'.hasLocationDetails(); // true
'Near university campus'.hasEducationalContext(); // true
'Hello world'.getWordCount();                   // 2
'Hello world'.getCharacterCountWithoutSpaces(); // 10

DomainValidator

'flutter.dev'.isDomainValid();          // true
'mail.uni.edu.eg'.isDomainValid();      // true
'invalid'.isDomainValid();              // false
'مثال.com'.isInternationalDomain();    // true

---

BaiomyNavKit

Features

Feature	Detail
Named route validation	Typos are caught at debug-time via assert
5 transition styles	bottomToUpWithFade · fade · slideWithFade · slideOnly · cupertino
Platform-aware defaults	Cupertino on iOS, fade/slide on Android
Semantic push methods	pushWithSlideUp, pushWithFade, pushWithSlideAndFade, pushWithSlide
Replace / clear-stack	pushReplacement, pushAndRemoveAll, replaceStack
Direct widget push	No route name required — great for modal sheets
BuildContext extensions	context.navPush(...) · context.navPop() · context.navCanPop
Zero dependencies	Only Flutter itself

Usage

1 — Declare your routes

Create one file that owns every route string in your app. Extending NavRoutes and listing them in get all is what enables debug-time typo detection.

// lib/routes/routes.dart
import 'package:flutter_nav_kit/flutter_nav_kit.dart';
 
class Routes extends NavRoutes {
  static const String home    = '/home';
  static const String login   = '/login';
  static const String detail  = '/detail';
  static const String profile = '/profile';
 
  @override
  List<String> get all => [home, login, detail, profile];
}

2 — Initialise and wire up

Call BaiomyNavKit.init once before runApp, then pass NavRouteGenerator to MaterialApp.onGenerateRoute. The builders map is the only place you ever write the mapping between a route name and a screen widget.

// lib/main.dart
import 'package:flutter_nav_kit/flutter_nav_kit.dart';
import 'routes/routes.dart';
 
void main() {
  BaiomyNavKit.init(routes: Routes()); // turns on assert-based route validation
  runApp(const MyApp());
}
 
class MyApp extends StatelessWidget {
  const MyApp({super.key});
 
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      initialRoute: Routes.home,
      onGenerateRoute: NavRouteGenerator(
        routes: Routes(),
        noRouteScreen: const NotFoundScreen(), // shown for unknown routes
        firstRoute: Routes.home,
        builders: {
          // args is the value you passed via the `arguments:` parameter,
          // with all transition metadata already stripped out for you.
          Routes.home:    (_)    => const HomeScreen(),
          Routes.login:   (_)    => const LoginScreen(),
          Routes.detail:  (args) => DetailScreen(item: args as MyItem),
          Routes.profile: (args) => ProfileScreen(userId: args as String),
        },
      ).generateRoute,
    );
  }
}

3 — Push screens

Simple push — platform-default transition

On iOS this uses the native Cupertino swipe; on Android it uses a fade. No configuration required.

BaiomyNavKit.push(context, Routes.home);
BaiomyNavKit.push(context, Routes.detail, arguments: myItem);

Push with a specific animation

BaiomyNavKit.pushWithSlideUp(context, Routes.detail, arguments: myItem);
BaiomyNavKit.pushWithFade(context, Routes.settings);
BaiomyNavKit.pushWithSlide(context, Routes.profile, arguments: userId);
BaiomyNavKit.pushWithSlideAndFade(context, Routes.detail);

Replace the current screen (no back button left behind)

BaiomyNavKit.pushReplacement(context, Routes.home);
BaiomyNavKit.pushReplacementWithFade(context, Routes.login);
BaiomyNavKit.pushReplacementWithSlideUp(context, Routes.onboarding);

Clear the entire stack (logout, post-login redirect, splash → home)

BaiomyNavKit.pushAndRemoveAll(context, Routes.login);
BaiomyNavKit.pushAndRemoveAllWithFade(context, Routes.home);
BaiomyNavKit.pushAndRemoveAllWithSlideUp(context, Routes.dashboard);

Replace the whole stack with multiple screens

Useful for deep-link handling — clears the stack, pushes the first route, then pushes the rest on top so the back-stack is exactly as you specify.

BaiomyNavKit.replaceStack(context, [Routes.home, Routes.detail]);

Avoid pushing the same screen twice

// No-op if the user is already on Routes.home
BaiomyNavKit.pushIfNotCurrent(context, Routes.home);

4 — Pop / go back

BaiomyNavKit.pop(context);                     // simple back
BaiomyNavKit.pop(context, myResult);           // back with a return value
BaiomyNavKit.popUntil(context, Routes.home);   // unwind to a specific screen
BaiomyNavKit.canPop(context);                  // → bool

5 — Push a widget directly (no route name needed)

Good for modals, confirmation sheets, or one-off screens you don't want registered in the route table.

// Lazy builder — widget isn't constructed until the transition begins
BaiomyNavKit.pushWidget(context, () => const ConfirmationSheet());
 
// Or pass an already-constructed widget
BaiomyNavKit.pushWidgetWithSlideUp(context, const ConfirmationSheet());
BaiomyNavKit.pushWidgetWithFade(context, const ConfirmationSheet());

6 — Custom transition durations

Every method accepts optional transitionDuration and reverseTransitionDuration. Omit them to use the built-in defaults.

BaiomyNavKit.pushWithSlideUp(
  context,
  Routes.detail,
  arguments: myItem,
  transitionDuration: const Duration(milliseconds: 500),
  reverseTransitionDuration: const Duration(milliseconds: 350),
);

7 — Context extensions (optional shorthand)

Every BaiomyNavKit method has a matching extension on BuildContext prefixed with nav. Use whichever style fits your codebase — they are identical under the hood.

// These two lines do exactly the same thing:
BaiomyNavKit.pushWithSlideUp(context, Routes.detail, arguments: item);
context.navPushWithSlideUp(Routes.detail, arguments: item);
 
// Other examples
context.navPush(Routes.home);
context.navPushWithFade(Routes.settings);
context.navPushReplacement(Routes.login);
context.navPushAndRemoveAll(Routes.home);
context.navPop();
context.navPopUntil(Routes.home);
bool can = context.navCanPop;
context.navPushWidgetWithSlideUp(const MyModal());

---

🛠️ Utils

BaiomyInputFormatters

Apply as inputFormatters on any TextFormField:

// ── Ready-made formatters ──────────────────────────────────────────────
TextFormField(inputFormatters: BaiomyInputFormatters.nameField);
TextFormField(inputFormatters: BaiomyInputFormatters.phoneField);
TextFormField(inputFormatters: BaiomyInputFormatters.emailField);
TextFormField(inputFormatters: BaiomyInputFormatters.passwordField);
TextFormField(inputFormatters: BaiomyInputFormatters.notesField);
TextFormField(inputFormatters: BaiomyInputFormatters.cleanText);
TextFormField(inputFormatters: BaiomyInputFormatters.username);
TextFormField(inputFormatters: BaiomyInputFormatters.creditCard);
TextFormField(inputFormatters: BaiomyInputFormatters.currency);

// ── Basic formatters ───────────────────────────────────────────────────
BaiomyInputFormatters.denyEmojis
BaiomyInputFormatters.numbersOnly
BaiomyInputFormatters.lettersOnly
BaiomyInputFormatters.alphanumericOnly
BaiomyInputFormatters.phoneNumberSafe
BaiomyInputFormatters.emailSafe
BaiomyInputFormatters.urlSafe
BaiomyInputFormatters.passwordSafe
BaiomyInputFormatters.denyProfanity

// ── With length limits ─────────────────────────────────────────────────
BaiomyInputFormatters.lengthLimit(10)
BaiomyInputFormatters.nameWithLength(35)      // default 35
BaiomyInputFormatters.phoneWithLength(11)     // default 11
BaiomyInputFormatters.notesWithLength(500)    // default 500

// ── Custom ─────────────────────────────────────────────────────────────
BaiomyInputFormatters.customDeny([RegExp(r'[xyz]')], allowEmojis: false)
BaiomyInputFormatters.customAllow([RegExp(r'[0-9]')])
BaiomyInputFormatters.caseFormatter(uppercase: true)

// ── Validation helpers (no TextFormField needed) ───────────────────────
BaiomyInputFormatters.containsEmojis('hello 😊');      // true
BaiomyInputFormatters.isNumericOnly('12345');           // true
BaiomyInputFormatters.containsProfanity('some text');  // false
BaiomyInputFormatters.getCleanCharacterCount('hi 😊'); // 3

inputDecoration()

A global function that returns a styled InputDecoration:

// Underline style (default)
TextFormField(
  decoration: inputDecoration(
    'Enter your email',
    Theme.of(context),
    suffixIcon: const Icon(Icons.email),
    helperText: 'We will never share your email',
  ),
)

// Outlined style
TextFormField(
  decoration: inputDecoration(
    'Enter your password',
    Theme.of(context),
    isOutlined: true,
    suffixIcon: const Icon(Icons.lock),
  ),
)

BaiomyGoogleMapsExtractor

Extracts latitude and longitude coordinates from any Google Maps URL format.

final url = 'https://maps.app.goo.gl/mWtb4a1cUE9zMWya7';
final coordinates = await BaiomyGoogleMapsExtractor.processGoogleMapsUrl(url);

if (coordinates != null) {
print('Latitude: ${coordinates['latitude']}');
print('Longitude: ${coordinates['longitude']}');
} else {
print('Failed to extract coordinates');
}

Supported URL formats:

• Standard map URLs with coordinates
• Place URLs with embedded coordinates
• Shortened URLs (goo.gl, maps.app.goo.gl)
• Street View URLs
• Directions URLs
• Embedded map URLs
• Mobile deep links
• Plus codes
• International Google domain variants

Available methods:

// Process any Google Maps URL (handles shortening + extraction)
final coords = await BaiomyGoogleMapsExtractor.processGoogleMapsUrl(url);

// Extract coordinates from an already-expanded URL
final coords = BaiomyGoogleMapsExtractor.extractCoordinates(expandedUrl);

// Check if a URL is a Google Maps URL
final bool isMaps = BaiomyGoogleMapsExtractor.isGoogleMapsUrl(url);

// Extract additional metadata (zoom level, map type, place name)
final metadata = BaiomyGoogleMapsExtractor.extractMetadata(url);
// Returns: { 'zoom': 15, 'mapType': 'roadmap', 'placeName': 'Cairo Tower' }

🔥 Firebase

All Firebase modules require firebase_core to be initialized before use.

---

BaiomyAuthRepo — Authentication

A singleton repository that wraps Firebase Authentication with clean, async APIs for email/password, guest accounts, profile updates, and guest-to-permanent upgrades.

final auth = BaiomyAuthRepo.instance;

// ── Sign up / Sign in ──────────────────────────────────────────────────
final credential = await auth.signUpWithEmailAndPassword(email, password);
final credential = await auth.signInWithEmailAndPassword(email, password);
final guestCred = await auth.signInAnonymously();

// ── Current user state ─────────────────────────────────────────────────
User? user = auth.currentUser;
String? uid = auth.uid;
bool signedIn = auth.isSignedIn;
bool guest = auth.isGuest;
Stream<User?> authChanges = auth.authStateChanges;

// ── Email verification ─────────────────────────────────────────────────
await auth.sendEmailVerification();
bool isVerified = await auth.checkEmailVerification();

// ── Profile updates ────────────────────────────────────────────────────
await auth.updateUserName('John Doe');
await auth.updateUserPassword('newSecurePass123');

// ── Password reset ─────────────────────────────────────────────────────
await auth.sendPasswordResetEmail(email);
bool oldPasswordOk = await auth.checkOldPassword(email, oldPassword);

// ── Guest → permanent upgrade ──────────────────────────────────────────
await auth.upgradeGuestToUser(
email: 'user@example.com',
password: 'newPassword',
name: 'John',
phone: '+201234567890',
);

// ── Sign out ───────────────────────────────────────────────────────────
await auth.logOut();

// ── User-friendly error messages ───────────────────────────────────────
try {
await auth.signInWithEmailAndPassword(email, password);
} on FirebaseAuthException catch (e) {
final message = auth.getAuthErrorMessage(e);
showToast(message);
}

BaiomyFirestoreRepo — Cloud Firestore

A singleton repository providing CRUD, real-time streams, pagination, batch writes, and transactions for Firestore.

final firestore = BaiomyFirestoreRepo.instance;

// ── Write ──────────────────────────────────────────────────────────────
// Create / overwrite a document
await firestore.createCollectionWithDoc(
collectionName: 'users',
docName: 'uid123',
data: {'name': 'Alice', 'email': 'alice@example.com'},
);

// Auto‑generated document ID
final docRef = await firestore.createCollection(
collectionName: 'posts',
data: {'title': 'Hello', 'content': '...'},
);

// Update specific fields
await firestore.updateData(
collectionName: 'users',
docName: 'uid123',
data: {'lastLogin': FieldValue.serverTimestamp()},
);

// Sub‑collection operations
await firestore.createSubCollectionWithDoc(
firstCollectionName: 'users',
secondCollectionName: 'orders',
firstDocName: 'uid123',
secondDocName: 'order456',
data: {'total': 99.99},
);

// ── Read ───────────────────────────────────────────────────────────────
// Get all documents
final QuerySnapshot allUsers = await firestore.getData(collectionName: 'users');

// Get single document
final DocumentSnapshot userDoc = await firestore.getDocData('users', 'uid123');

// Query with conditions
final QuerySnapshot adults = await firestore.getDataWhere(
collectionName: 'users',
field: 'age',
value: 18,
orderByField: 'name',
limit: 10,
);

// Pagination
final firstPage = await firestore.getDataWithPagination(
collectionName: 'users',
limit: 20,
orderByField: 'createdAt',
);
final lastDoc = firstPage.docs.last;
final secondPage = await firestore.getDataWithPagination(
collectionName: 'users',
limit: 20,
lastDocument: lastDoc,
);

// Check existence
final exists = await firestore.documentExists(
collectionName: 'users',
docName: 'uid123',
);

// ── Real‑time streams ─────────────────────────────────────────────────
// Single document stream
Stream<DocumentSnapshot> userStream = firestore.documentStream(
collectionName: 'users',
docName: 'uid123',
);

// Collection stream with filters
Stream<QuerySnapshot> recentPosts = firestore.collectionStream(
collectionName: 'posts',
whereField: 'published',
whereValue: true,
orderByField: 'timestamp',
descending: true,
limit: 50,
);

// Sub‑collection stream
Stream<QuerySnapshot> orderStream = firestore.subCollectionStream(
firstCollectionName: 'users',
secondCollectionName: 'orders',
docName: 'uid123',
);

// ── Batch & transactions ───────────────────────────────────────────────
// Batch write
await firestore.batchWrite((batch, db) {
final userRef = db.collection('users').doc('uid123');
batch.update(userRef, {'points': 10});
final logRef = db.collection('logs').doc();
batch.set(logRef, {'action': 'add_points'});
});

// Transaction
await firestore.runTransaction((tx) async {
final snap = await tx.get(userRef);
final newPoints = (snap.data()?['points'] ?? 0) + 10;
tx.update(userRef, {'points': newPoints});
});

// ── Delete ─────────────────────────────────────────────────────────────
// Delete single document
await firestore.deleteData(collectionName: 'users', documentId: 'uid123');

// Delete all documents in a sub‑collection
await firestore.deleteSubCollection(
firstCollectionName: 'users',
secondCollectionName: 'orders',
docName: 'uid123',
);

BaiomyStorageRepo — Firebase Storage

A singleton repository for uploading, downloading, updating, and deleting files with progress tracking and metadata support.

final storage = BaiomyStorageRepo.instance;

// ── Upload ─────────────────────────────────────────────────────────────
// Upload a local file
final imageUrl = await storage.uploadFile(
path: 'users/uid123/avatar.jpg',
file: File('/local/avatar.jpg'),
metadata: SettableMetadata(contentType: 'image/jpeg'),
);

// Upload raw bytes (e.g., from memory)
final pdfUrl = await storage.uploadBytes(
path: 'invoices/invoice123.pdf',
bytes: pdfBytes,
);

// Upload from a string (base64, text, etc.)
final url = await storage.uploadFromString(
path: 'logs/error.log',
fileUrl: errorLogText,
format: PutStringFormat.plain,
);

// Upload with progress tracking
final task = storage.uploadFileWithProgress(
path: 'videos/intro.mp4',
file: videoFile,
);
task.snapshotEvents.listen((snapshot) {
final progress = snapshot.bytesTransferred / snapshot.totalBytes;
print('${(progress * 100).toStringAsFixed(1)}%');
});
final snapshot = await task;
final videoUrl = await snapshot.ref.getDownloadURL();

// ── Read / download ────────────────────────────────────────────────────
// Get download URL
final url = await storage.getDownloadUrl(path: 'users/uid123/avatar.jpg');

// Get file metadata
final FullMetadata meta = await storage.getMetadata(path: 'files/data.json');
print('Size: ${meta.size}, Type: ${meta.contentType}');

// Download bytes (max 10 MB by default)
final Uint8List? data = await storage.downloadBytes(
path: 'documents/report.pdf',
maxSize: 5 * 1024 * 1024, // 5 MB
);

// List files in a folder
final ListResult result = await storage.listItems(path: 'users/uid123');
for (final ref in result.items) {
print(ref.name);
}

// Recursive list all (use with caution on large trees)
final ListResult all = await storage.listAll(path: 'users');

// Paginated listing
final page1 = await storage.listItemsPaginated(
path: 'photos',
maxResults: 20,
);
final page2 = await storage.listItemsPaginated(
path: 'photos',
maxResults: 20,
pageToken: page1.nextPageToken,
);

// Check if a file exists
final exists = await storage.fileExists(path: 'users/uid123/avatar.jpg');

// ── Update ─────────────────────────────────────────────────────────────
// Replace entire file
await storage.updateFile(
path: 'users/uid123/avatar.jpg',
newFile: File('/new_avatar.jpg'),
);

// Replace with bytes
await storage.updateBytes(
path: 'users/uid123/avatar.jpg',
newBytes: newImageBytes,
);

// Update only metadata (no re‑upload)
await storage.updateMetadata(
path: 'users/uid123/avatar.jpg',
metadata: SettableMetadata(customMetadata: {'uploadedBy': 'admin'}),
);

// ── Delete ─────────────────────────────────────────────────────────────
// Delete a single file
await storage.deleteFile(path: 'users/uid123/old_avatar.jpg');

// Delete all files inside a folder (non‑recursive)
await storage.deleteFolder(path: 'temp/session123');

// Recursively delete entire folder tree (⚠️ use with caution)
await storage.deleteAll(path: 'users/uid123_old');

⚠️ Important: For large‑scale delete operations (thousands of files), prefer a Cloud Function to avoid timeouts and excessive client‑side work.

---

🎨 Widgets

Widget files are in lib/widgets/. Refer to each file for full constructor details as the APIs depend on your local implementation.

BaiomyToast

Quick snackbar-style notifications.

BaiomyAvatarGlow

Avatar widget with an animated glow effect.

BaiomyConditionalBuilder

Renders different widgets based on a condition.

CustomSizedBox

Convenient spacing widget using extension.

BaiomyValueListenableBuilder2

Reactive widget that rebuilds when a ValueListenable changes.

BaiomyLoadingItem

Loading skeleton / overlay widget (from widgets/loading/loading_item.dart).

BaiomyKeepAlivePage

utility wrapper widget designed to preserve the state of its child widget, preventing it from being disposed of when it moves out of view

Segmented Circular Next Button

provides a circular next button with an animated segmented progress ring for onboarding flows

---

🛡️ Error Handling

Every module throws its own typed exception — never a raw platform error.

// Storage errors
try {
  await BaiomySecureStorage.instance.updateString('missing_key', 'value');
} on StorageException catch (e) {
  print(e.message);    // 'Cannot update a key that does not exist.'
  print(e.key);        // 'missing_key'
  print(e.cause);      // original platform error
  print(e.stackTrace); // original stack trace
}

// Crypto errors
try {
  BaiomyPasswordEncryption.instance.decrypt('bad_format');
} on CryptoException catch (e) {
  print(e.message); // 'Decryption failed. The key may be wrong...'
  print(e.cause);   // original error
}

---

📁 Package Structure

lib/
├── egyptian_id_parser/
│   ├── impl/
│   ├── models/
│   ├── repo/
│   └── country_id_parser_base.dart    → BaiomyEgyptianIdParser
├── extensions/
│   ├── validator/
│   │   ├── domain_validator.dart      → DomainValidator (extension)
│   │   ├── email_validator.dart       → EmailValidator (extension)
│   │   ├── notes_validator.dart       → NotesValidator (extension)
│   │   └── password_validator.dart    → PasswordValidator (extension)
│   ├── build_context_extensions.dart  → BuildContextExtension (extension)
│   └── form_auto_scroll.dart          → FormAutoScroll (extension on GlobalKey)
├── local_storage/
│   ├── shared_preferences.dart        → BaiomySharedPrefs
│   ├── secure_storage.dart            → BaiomySecureStorage
│   └── storage_exception.dart         → StorageException
├── routes/
│   ├── src/
│   │   ├── nav_extensions.dart      → NavKitContext (extension)
│   │   ├── nav_kit.dart             → BaiomyNavKit
│   │   ├── nav_route_generator.dart → NavRouteGenerator
│   │   ├── nav_routes.dart          → NavRoutes
│   │   └── nav_transition_type.dart → NavTransitionType (enum)
│   └── flutter_nav_kit.dart
├── password_encryption/
│   ├── password_encryption.dart       → BaiomyPasswordEncryption
│   ├── password_hasher.dart           → PasswordHasher
│   ├── encrypted_payload.dart         → EncryptedPayload
│   ├── hashed_password.dart           → HashedPassword
│   └── crypto_exception.dart          → CryptoException
├── firebase/
│   ├── firestore_repo.dart           → BaiomyFirestoreRepo
│   ├── authentication_repo.dart      → BaiomyAuthRepo
│   └── storage_repo.dart             → BaiomyStorageRepo
├── utils/
│   ├── app_input_formatters.dart       → BaiomyInputFormatters
│   ├── logger_class.dart               → BaiomyLogger
│   ├── google_maps_extractor.dart      → BaiomyGoogleMapsExtractor
│   └── text_form_field_decoration.dart → inputDecoration()
├── widgets/
│   ├── loading/
│   │   └── loading_item.dart
│   ├── app_toasts.dart
│   ├── avatar_glow.dart
│   ├── conditional_builder.dart
│   ├── custom_sized_box.dart
│   ├── segmented_circular_next_button.dart
│   └── custom_value_listenable.dart
└── baiomy.dart

---

⚖️ License

BAIOMY PROPRIETARY SOFTWARE LICENSE

================================================================================
Copyright (c) 2026 Mohamed Elbaiomy. All Rights Reserved.
================================================================================

IMPORTANT — READ CAREFULLY BEFORE USING THIS SOFTWARE.

This license agreement ("Agreement") is a legal agreement between you
("Licensee") and the author of this software package ("Licensor", "Mohamed Elbaiomy").
By accessing, downloading, copying, installing, or using any part of this
software, its source code, documentation, or any associated files
(collectively, the "Software"), you agree to be bound by the terms of this
Agreement. If you do not agree, you must immediately delete all copies of the
Software and cease all use.

────────────────────────────────────────────────────────────────────────────────
1. GRANT OF LICENSE
────────────────────────────────────────────────────────────────────────────────

No license is granted under this Agreement unless explicitly authorized in
writing by Mohamed Elbaiomy. Mohamed reserves ALL rights to this Software,
including but not limited to the right to use, copy, modify, merge, publish,
distribute, sublicense, and sell copies of the Software.

────────────────────────────────────────────────────────────────────────────────
2. RESTRICTIONS
────────────────────────────────────────────────────────────────────────────────

Unless you have received prior WRITTEN PERMISSION from the Licensor, you are
STRICTLY PROHIBITED from:

  a) Using this Software, in whole or in part, for any personal, academic,
     commercial, or non-commercial project.

  b) Copying, reproducing, or duplicating the Software or any portion thereof.

  c) Modifying, adapting, translating, reverse engineering, decompiling,
     disassembling, or creating derivative works based on the Software.

  d) Distributing, publishing, sublicensing, selling, renting, leasing, or
     transferring the Software or any rights therein to any third party.

  e) Incorporating the Software or any part of it into another software
     package, library, product, or service.

  f) Removing, altering, or obscuring any copyright notice, license text,
     attribution, or proprietary marking included in the Software.

  g) Using the name "Baiomy", the package name, or any associated branding
     to endorse or promote products derived from this Software without prior
     written consent.

  h) Uploading, mirroring, or re-hosting this Software on any public or
     private repository, platform, or registry (including but not limited to
     pub.dev, GitHub, GitLab, Bitbucket, or npm) without explicit written
     authorization from the Licensor.

────────────────────────────────────────────────────────────────────────────────
3. OWNERSHIP
────────────────────────────────────────────────────────────────────────────────

The Software is proprietary to Mohamed Elbaiomy and is protected by copyright law
and international treaty provisions. The Licensor retains exclusive ownership
of all intellectual property rights in and to the Software, including all
copies, modifications, and derivative works, regardless of who created them.

This Agreement does not transfer any ownership, title, or intellectual property
rights in the Software to the Licensee. Any use of the Software not expressly
permitted by this Agreement is strictly prohibited and constitutes a violation
of the Licensor's intellectual property rights.

────────────────────────────────────────────────────────────────────────────────
4. NO WARRANTIES
────────────────────────────────────────────────────────────────────────────────

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE, ACCURACY, OR NON-INFRINGEMENT. THE LICENSOR
DOES NOT WARRANT THAT THE SOFTWARE WILL MEET YOUR REQUIREMENTS, OPERATE WITHOUT
INTERRUPTION, OR BE ERROR-FREE.

────────────────────────────────────────────────────────────────────────────────
5. LIMITATION OF LIABILITY
────────────────────────────────────────────────────────────────────────────────

IN NO EVENT SHALL THE LICENSOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, CONSEQUENTIAL, OR PUNITIVE DAMAGES (INCLUDING BUT NOT
LIMITED TO LOSS OF DATA, LOSS OF PROFITS, BUSINESS INTERRUPTION, OR LOSS OF
GOODWILL) ARISING OUT OF OR IN CONNECTION WITH THE USE OR INABILITY TO USE
THE SOFTWARE, EVEN IF THE LICENSOR HAS BEEN ADVISED OF THE POSSIBILITY OF
SUCH DAMAGES.

────────────────────────────────────────────────────────────────────────────────
6. ENFORCEMENT
────────────────────────────────────────────────────────────────────────────────

Any unauthorized use, reproduction, distribution, or modification of this
Software constitutes copyright infringement and will be subject to civil and
criminal penalties under applicable law, including international copyright
treaties. The Licensor reserves the right to seek all available legal and
equitable remedies, including injunctive relief and monetary damages.

────────────────────────────────────────────────────────────────────────────────
7. TERMINATION
────────────────────────────────────────────────────────────────────────────────

Any rights conditionally granted by Mohamed Elbaiomy (if any) terminate
immediately and automatically upon any breach of this Agreement by the
Licensee. Upon termination, the Licensee must destroy all copies of the
Software in their possession or control.

────────────────────────────────────────────────────────────────────────────────
8. GOVERNING LAW
────────────────────────────────────────────────────────────────────────────────

This Agreement shall be governed by and construed in accordance with the laws
of the Arab Republic of Egypt, without regard to its conflict of law provisions.
Any dispute arising under or relating to this Agreement shall be subject to the
exclusive jurisdiction of the competent courts of Egypt.

────────────────────────────────────────────────────────────────────────────────
9. CONTACT
────────────────────────────────────────────────────────────────────────────────

For licensing inquiries, permission requests, or any questions regarding this
Agreement, contact the Licensor at:

  Author  : Mohamed Elbaiomy
  Project : https://github.com/mohamedelbaiomy/baiomy

────────────────────────────────────────────────────────────────────────────────
ALL RIGHTS RESERVED. UNAUTHORIZED USE IS STRICTLY PROHIBITED.
────────────────────────────────────────────────────────────────────────────────

---

Built with ❤️ by Baiomy