@temboplus/frontend-core 0.3.0-beta.3 → 0.3.0

package/README.md

@@ -1,77 +1,28 @@
 # @temboplus/frontend-core
 
-A foundational JavaScript/TypeScript library designed to provide common utilities, shared logic, and standardized components for all TemboPlus frontend applications. This package aims to streamline development, ensure consistency, and reduce code duplication across our entire frontend ecosystem.
+Shared TypeScript package for TemboPlus domain models, validators, and constants. Originally built by the frontend team (hence the name), but contains no UI components and works in any JavaScript runtime — frontend, backend, or otherwise.
 
-## Core Features
-
-* **Utility Functions:** A collection of pre-built helper functions to simplify common development tasks.
-* **Standardized Data Models:** Consistent and reliable data structures for managing essential data types, including phone numbers, amounts, currencies, countries, and bank details.
-* **Comprehensive Report Management:** A powerful `ReportManager` for generating and downloading reports in various formats across different TemboPlus projects.
-* **Centralized Configuration Service:** A flexible `ConfigService` for managing application settings and environment configurations.
-
-## Data Models
-
-This library offers a set of meticulously crafted data models, each designed to handle specific data types with precision:
-
-* **PhoneNumber:** Robust international phone number validation and formatting.
-* **TZPhoneNumber:** Specialized phone number handling for Tanzania, including network operator identification.
-* **Amount:** Precise currency value management, with support for formatting and conversion.
-* **Currency:** Detailed currency information, including symbols, formatting rules, and validation.
-* **Country:** Enhanced country data handling with ISO-2 and ISO-3 codes, official names, flag emojis, and strongly-typed geographical categorization.
-* **Bank:** Consistent bank account information management.
-
-## Report Management with `ReportManager`
-
-The `ReportManager` simplifies the process of generating and downloading reports across various TemboPlus projects.
-
-```typescript
-import { ReportManager, FileFormat, ReportType, ProjectType } from '@temboplus/frontend-core';
-
-// Download a report
-async function downloadMerchantDisbursementReport() {
-    await ReportManager.instance.downloadReport({
-        token: "your-auth-token",
-        projectType: ProjectType.DASHBOARD,
-        reportType: ReportType.MERCHANT_DISBURSEMENT_REPORT,
-        fileFormat: FileFormat.PDF,
-        query: {
-            startDate: "2023-01-01T00:00:00.000Z",
-            endDate: "2023-01-31T00:00:00.000Z"
-        }
-    });
-}
+## Installation
 
-// Get all reports for a specific project
-import { getReportsByProject } from '@temboplus/frontend-core';
-function getAllDashboardReports(){
-  const dashboardReports = getReportsByProject(ProjectType.DASHBOARD);
-  return dashboardReports;
-}
+```bash
+npm install @temboplus/frontend-core
 ```
 
-### Supported Report Types
-
-* **Dashboard Reports:**
-    * `MERCHANT_DISBURSEMENT_REPORT`: Detailed merchant disbursement reports.
-    * `TRANSACTION_REVENUE_SUMMARY`: Revenue transaction summaries.
-* **Afloat Reports:**
-    * `CUSTOMER_WALLET_ACTIVITY`: Customer wallet activity logs.
-    * `CUSTOMER_PROFILE_SNAPSHOT`: Customer profile snapshots.
-* **VertoX Reports:**
-    * `GATEWAY_TRANSACTION_LOG`: Payment gateway transaction logs.
+## What's Included
 
-## Configuration Service with `ConfigService`
+* **Data models** for phone numbers, amounts, currencies, countries, and banks
+* **Validation and parsing** helpers for constructing normalized model instances
+* **Constants** for supported payout countries and related domain logic
+* **Type-safe string literals** for country codes (ISO-2, ISO-3) and currency codes
 
-The `ConfigService` provides a centralized mechanism for managing application configurations.
-
-```typescript
-import { ConfigService } from '@temboplus/frontend-core';
+## Data Models
 
-// Initialize configuration at application startup
-ConfigService.instance.initialize({
-    pdfMakerBaseUrl: 'http://localhost:3000' // Optional: Override default PDF maker base URL.
-});
-```
+* **PhoneNumber:** International phone number validation and formatting.
+* **TZPhoneNumber:** Tanzania phone numbers with network operator identification.
+* **Amount:** Currency value handling with formatting and conversion.
+* **Currency:** Currency info including symbols, formatting rules, and validation.
+* **Country:** Country data with ISO codes, flag emojis, and geographical categorization.
+* **Bank:** Bank account information management.
 
 ## Data Model Validation
 
@@ -103,17 +54,10 @@ if (phoneNumber.validate()) {
 
 ## Type-Safe String Literals
 
-This library provides strongly-typed string literals for standardized codes:
-
-* **Country Codes:**
-  * `ISO2CountryCode`: Two-letter country codes (e.g., "US", "GB", "DE")
-  * `ISO3CountryCode`: Three-letter country codes (e.g., "USA", "GBR", "DEU")
-  * `CountryCode`: A union type that accepts either ISO-2 or ISO-3 formats
+Typed string literals for country and currency codes with compile-time checking:
 
-* **Currency Codes:**
-  * `CurrencyCode`: Three-letter currency codes (e.g., "USD", "EUR", "JPY")
-
-These types provide compile-time validation and auto-completion while having zero runtime overhead:
+* `ISO2CountryCode` / `ISO3CountryCode` / `CountryCode` (union of both)
+* `CurrencyCode`
 
 ```typescript
 import { 
@@ -132,48 +76,48 @@ function processTransaction(
   // Implementation
 }
 
-// Valid calls - compile-time checking ensures only valid codes are accepted
+// Valid calls
 processTransaction(100, "USD", "US");   // ISO-2 country code
 processTransaction(200, "EUR", "DEU");  // ISO-3 country code
 
-// Invalid calls - caught by TypeScript at compile time
+// Invalid — caught at compile time
 processTransaction(300, "XYZ", "US");   // Error: "XYZ" is not a valid CurrencyCode
 processTransaction(400, "USD", "ZZZ");  // Error: "ZZZ" is not a valid CountryCode
 ```
 
-## Static Data Access
+## Data Lookup
 
-Convenient static properties are available for accessing common data:
+Use the lookup methods to access countries, currencies, and banks:
 
 ```typescript
-import { Country, Currency, Bank, CONTINENT, SUB_REGION } from '@temboplus/frontend-core';
+import { Country, Currency, Bank, BankService, CONTINENT, SUB_REGION } from '@temboplus/frontend-core';
 
-// Country access with enhanced features
-const tanzania = Country.TZ;
-console.log(tanzania.flagEmoji); // 🇹🇿
-console.log(tanzania.continent); // CONTINENT.AFRICA
-console.log(tanzania.region); // SUB_REGION.EASTERN_AFRICA
+// Country lookup
+const tanzania = Country.fromCode("TZ");
+console.log(tanzania?.flagEmoji); // 🇹🇿
+console.log(tanzania?.continent); // CONTINENT.AFRICA
+console.log(tanzania?.region); // SUB_REGION.EASTERN_AFRICA
 
-// Regional country grouping with type-safe enums
+// Regional grouping
 const africanCountries = Country.getByContinent(CONTINENT.AFRICA);
 const caribbeanCountries = Country.getByRegion(SUB_REGION.CARIBBEAN);
 
-// Currency access
-const usd = Currency.USD;
-const tzs = Currency.TANZANIAN_SHILLING;
+// Currency lookup
+const usd = Currency.fromCode("USD");
+const tzs = Currency.fromCode("TZS");
 
 // Access country's currency
-const japan = Country.JP;
-const yen = japan.getCurrency();
+const japan = Country.fromCode("JP");
+const yen = japan?.getCurrency();
 console.log(yen?.code); // "JPY"
 
 // Find countries using a specific currency
-const euroCountries = Country.getByCurrencyCode("EUR");
+const euroCountries = Country.getAll().filter((country) => country.currencyCode === "EUR");
 console.log(`${euroCountries.length} countries use the Euro`);
 
 // Bank access
-const crdb = Bank.CRDB;
-const nmb = Bank.NMB;
+const crdb = Bank.from("CORUTZTZ", "TZ");
+const kenyanBanks = BankService.getInstance().getAllBanks("KE");
 ```
 
 ## Phone Number Usage
@@ -198,9 +142,3 @@ console.log(tanzaniaPhone.networkOperator.name); // "Yas"
 * [Bank](./docs/bank.md)
 * [Currency](./docs/currency.md)
 * [Country](./docs/country.md)
-
-## Installation
-
-```bash
-npm install @temboplus/frontend-core
-```