@temboplus/frontend-core 0.4.3 → 1.0.1-beta.0

package/README.md

@@ -1,206 +1,95 @@
 # @temboplus/frontend-core
 
-A robust and versatile JavaScript/TypeScript library designed to streamline the development of TemboPlus front-end applications. This library provides a comprehensive suite of utilities, standardized data models, and services to ensure consistency, efficiency, and maintainability across all TemboPlus projects.
+Shared TypeScript domain package for TemboPlus products. It provides canonical value objects, typed codes, validation helpers, factories, registries, and coverage data.
 
-## Core Features
+## Install
 
-* **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"
-        }
-    });
-}
-
-// 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.
-
-## Configuration Service with `ConfigService`
+## Architecture At A Glance
 
-The `ConfigService` provides a centralized mechanism for managing application configurations.
-
-```typescript
-import { ConfigService } from '@temboplus/frontend-core';
-
-// Initialize configuration at application startup
-ConfigService.instance.initialize({
-    pdfMakerBaseUrl: 'http://localhost:3000' // Optional: Override default PDF maker base URL.
-});
+```text
+domain/       value objects, types, schemas, and entity helpers
+factories/    construction, parsing, validation, and JSON re-resolution
+registries/   cached lookup and query APIs over supported datasets
+repositories/ internal raw JSON dataset readers
+utils/        cross-cutting helpers such as text, id, time, and logging
+coverage/     supported countries, channels, providers, banks, and limits
 ```
 
-## Data Model Validation
-
-Each data model includes validation methods to ensure data integrity:
-
-* **`is(object)`:** Checks if an object is a valid instance of the data model.
-* **`canConstruct(input)`:** Validates input data before constructing a new instance.
-* **`validate()`:** Verifies the validity of an existing data model instance.
+Most consumers start with static delegations on the domain objects:
 
 ```typescript
-import { PhoneNumber, Amount } from '@temboplus/frontend-core';
+import { Amount, Bank, BankHelpers, Country, Currency } from "@temboplus/frontend-core";
 
-// Using is()
-if (PhoneNumber.is(someObject)) {
-    console.log(someObject.label);
-}
-
-// Using canConstruct()
-if (Amount.canConstruct(userInput)) {
-    const amount = Amount.from(userInput);
-}
-
-// Using validate()
-const phoneNumber = PhoneNumber.from("+1234567890");
-if (phoneNumber.validate()) {
-    // Process the valid phone number.
-}
+const country = Country.fromCode("TZ");
+const currency = Currency.fromCode("USD");
+const amount = Amount.from(100, "USD");
+const bank = Bank.fromBIC("CORUTZTZ", "TZ");
+const canUseBic = BankHelpers.validateSwiftCode("CORUTZTZ", "TZ");
 ```
 
-## Type-Safe String Literals
+Use factories when you need lower-level construction or aggregate behavior, and registries when you need cached lookup, listing, search, or provider detection.
 
-This library provides strongly-typed string literals for standardized codes:
+## Main Exports
 
-* **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
+- `Amount` parses, formats, compares, and serializes monetary values.
+- `Bank` resolves supported banks by BIC/SWIFT code.
+- `Country` resolves ISO-2 and ISO-3 country records.
+- `Currency` resolves ISO 4217 currency records.
+- `MobileMoneyProvider` resolves supported mobile-money providers.
+- `PhoneNumber` parses and formats international phone numbers.
+- `TemboCoverage` answers coverage questions for channels, countries, providers, banks, and limits.
+- `*Helpers` expose entity-scoped type guards, validators, parsers, and formatters.
 
-* **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:
+## Typed Codes
 
 ```typescript
-import { 
-  ISO2CountryCode, 
-  ISO3CountryCode, 
-  CountryCode, 
-  CurrencyCode 
-} from '@temboplus/frontend-core';
-
-// Type-safe function parameters
-function processTransaction(
-  amount: number,
-  currency: CurrencyCode,
-  country: CountryCode
-) {
-  // Implementation
+import type {
+  BankSwiftCode,
+  CountryCode,
+  CurrencyCode,
+  ISO2CountryCode,
+  ISO3CountryCode,
+} from "@temboplus/frontend-core";
+
+function quote(amount: number, currency: CurrencyCode, country: CountryCode) {
+  return { amount, currency, country };
 }
 
-// Valid calls - compile-time checking ensures only valid codes are accepted
-processTransaction(100, "USD", "US");   // ISO-2 country code
-processTransaction(200, "EUR", "DEU");  // ISO-3 country code
-
-// Invalid calls - caught by TypeScript 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
+quote(100, "TZS", "TZ");
+quote(100, "USD", "USA");
 ```
 
-## Static Data Access
-
-Convenient static properties are available for accessing common data:
-
-```typescript
-import { Country, Currency, Bank, 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
-
-// Regional country grouping with type-safe enums
-const africanCountries = Country.getByContinent(CONTINENT.AFRICA);
-const caribbeanCountries = Country.getByRegion(SUB_REGION.CARIBBEAN);
-
-// Currency access
-const usd = Currency.USD;
-const tzs = Currency.TANZANIAN_SHILLING;
-
-// Access country's currency
-const japan = Country.JP;
-const yen = japan.getCurrency();
-console.log(yen?.code); // "JPY"
-
-// Find countries using a specific currency
-const euroCountries = Country.getByCurrencyCode("EUR");
-console.log(`${euroCountries.length} countries use the Euro`);
-
-// Bank access
-const crdb = Bank.CRDB;
-const nmb = Bank.NMB;
-```
-
-## Phone Number Usage
+## Coverage Example
 
 ```typescript
-import { PhoneNumber, TZPhoneNumber, PhoneNumberFormat } from '@temboplus/frontend-core';
+import { TemboCoverage, TransactionDirection } from "@temboplus/frontend-core";
 
-// International phone numbers
-const internationalPhone = PhoneNumber.from("+1 (202) 555-0123");
-console.log(internationalPhone.getWithFormat(PhoneNumberFormat.INTERNATIONAL)); // +12025550123
+const payoutCountries = TemboCoverage.getSupportedCountryCodes({
+  direction: TransactionDirection.PAYOUT,
+});
 
-// Tanzania phone numbers
-const tanzaniaPhone = TZPhoneNumber.from("0712345678");
-console.log(tanzaniaPhone.getWithFormat(PhoneNumberFormat.INTERNATIONAL)); // +255 712 345 678
-console.log(tanzaniaPhone.networkOperator.name); // "Yas"
+const tzBanks = TemboCoverage.getPayoutBanks("TZ");
 ```
 
-## Detailed Model Documentation
+## Documentation
 
-* [PhoneNumber](./docs/phone_number.md)
-* [Amount](./docs/amount.md)
-* [Bank](./docs/bank.md)
-* [Currency](./docs/currency.md)
-* [Country](./docs/country.md)
+- [Architecture](./docs/architecture.md)
+- [Amount](./docs/amount.md)
+- [Bank](./docs/bank.md)
+- [Country](./docs/country.md)
+- [Currency](./docs/currency.md)
+- [MobileMoneyProvider](./docs/mobile_money_provider.md)
+- [PhoneNumber](./docs/phone_number.md)
 
-## Installation
+## Development
 
 ```bash
-npm install @temboplus/frontend-core
-```
+npx tsc --noEmit
+npm run build
+```
+
+Existing test files are still being migrated to the `1.0.0` API. Prefer typecheck, build, and focused smoke scripts until that cleanup is complete.

package/dist/coverage/coverage.types.d.ts

@@ -0,0 +1,24 @@
+import type { ChannelType, TransactionDirection } from "@domain/channel/channel.enums.js";
+import type { ISO2CountryCode } from "@domain/country/country.types.js";
+import type { CurrencyCode } from "@domain/currency/currency.types.js";
+export interface SupportedCountryCoverage {
+    countryCode: ISO2CountryCode;
+    currencyCode: CurrencyCode;
+    directions: TransactionDirection[];
+    channels: ChannelType[];
+}
+export interface CoverageCountryOptions {
+    direction?: TransactionDirection;
+    channelType?: ChannelType;
+}
+export interface CoverageChannelOptions {
+    direction?: TransactionDirection;
+    channelType?: ChannelType;
+}
+export interface CoverageTransactionLimitQuery {
+    countryCode: ISO2CountryCode;
+    currencyCode: CurrencyCode;
+    direction: TransactionDirection;
+    channelType: ChannelType;
+    providerId?: string;
+}

package/dist/coverage/index.d.ts

@@ -0,0 +1,3 @@
+export * from "@domain/channel/index.js";
+export * from "./coverage.types.js";
+export * from "./tembo-coverage.js";

package/dist/coverage/tembo-coverage.d.ts

@@ -0,0 +1,59 @@
+import { Channel } from "@domain/channel/channel.js";
+import { TransactionDirection } from "@domain/channel/channel.enums.js";
+import type { ISO2CountryCode } from "@domain/country/country.types.js";
+import type { CoverageCountryOptions, CoverageChannelOptions, CoverageTransactionLimitQuery } from "./coverage.types.js";
+/**
+ * Single entry point for all Tembo Coverage queries.
+ * Handles supported countries, banks, mobile money providers, and transaction limits.
+ */
+declare class TemboCoverageService {
+    private readonly coverage;
+    private readonly countries;
+    private readonly banks;
+    private readonly providers;
+    private readonly limits;
+    constructor();
+    /**
+     * Returns a list of ISO2 country codes supported by Tembo.
+     */
+    getSupportedCountryCodes(options?: CoverageCountryOptions): ISO2CountryCode[];
+    /**
+     * Returns full Country model instances for all supported countries.
+     */
+    getSupportedCountries(options?: CoverageCountryOptions): any[];
+    /**
+     * Checks if a specific country is supported, optionally filtered by direction or channel.
+     */
+    isSupportedCountry(countryCode: ISO2CountryCode, options?: CoverageCountryOptions): boolean;
+    /**
+     * Returns all banks available for payout in the specified country.
+     */
+    getPayoutBanks(countryCode: ISO2CountryCode): import("../index.js").Bank[];
+    /**
+     * Returns mobile money providers for a country, optionally filtered by direction (PAYIN/PAYOUT).
+     */
+    getMobileMoneyProviders(countryCode: ISO2CountryCode, options?: {
+        direction?: TransactionDirection;
+    }): import("../index.js").MobileMoneyProvider[];
+    /**
+     * Returns a combined list of all available Channels (Banks and Mobile Money).
+     */
+    getChannels(countryCode: ISO2CountryCode, options?: CoverageChannelOptions): Channel[];
+    /**
+     * Returns transaction limits for a specific corridor.
+     */
+    getTransactionLimits(query: CoverageTransactionLimitQuery): import("@registries/transaction-limit.registry.js").TransactionLimits | undefined;
+    /**
+     * Internal helper to filter the master coverage list based on user options.
+     */
+    private getFilteredCoverage;
+    /**
+     * Internal helper to check if a specific channel type should be included in results.
+     */
+    private shouldInclude;
+}
+/**
+ * Exported Singleton Instance
+ */
+export declare const TemboCoverage: TemboCoverageService;
+export {};