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

package/dist/models/amount/amount.d.ts

@@ -46,16 +46,16 @@ export type AmountJSON = z.infer<typeof AmountJSONSchema>;
  * @example
  * ```typescript
  * // Currency-amount combinations
- * Amount.from('TZS10000');           // TSh 10,000.00
- * Amount.from('TZS 10,000');         // TSh 10,000.00 (spaces removed)
- * Amount.from('10000TZS');           // TSh 10,000.00
- * Amount.from('TZS1,234.56');        // TSh 1,234.56
- * Amount.from('-TZS1000');           // -TSh 1,000.00
- * Amount.from('TZS-1000');           // -TSh 1,000.00
+ * Amount.from('TZS10000');           // TZS 10,000.00
+ * Amount.from('TZS 10,000');         // TZS 10,000.00 (spaces removed)
+ * Amount.from('10000TZS');           // TZS 10,000.00
+ * Amount.from('TZS1,234.56');        // TZS 1,234.56
+ * Amount.from('-TZS1000');           // -TZS 1,000.00
+ * Amount.from('TZS-1000');           // -TZS 1,000.00
  *
  * // Traditional usage still works
- * Amount.from(1000, 'TZS');          // TSh 1,000.00
- * Amount.from('1000', 'USD');        // $1,000.00
+ * Amount.from(1000, 'TZS');          // TZS 1,000.00
+ * Amount.from('1000', 'USD');        // USD 1,000.00
  * ```
  */
 /**
@@ -75,13 +75,13 @@ export interface AmountJson {
  * Formatting options for the enhanced format method
  */
 interface AmountFormatOptions {
-    /** Include currency symbol (e.g., $, TSh) */
-    includeSymbol?: boolean;
-    /** Include currency code (e.g., USD, TZS) */
-    includeCurrency?: boolean;
-    /** Position of currency symbol */
-    symbolPosition?: "before" | "after";
-    /** Use thousands separators (commas) */
+    /** Show currency indicator (code by default, or symbol if useSymbol is true). Default: true */
+    showCurrency?: boolean;
+    /** Use currency symbol (e.g., $, TSh) instead of code (e.g., USD, TZS). Default: false */
+    useSymbol?: boolean;
+    /** Position of currency indicator. Default: "before" */
+    currencyPosition?: "before" | "after";
+    /** Use thousands separators (commas). Default: true */
     useGrouping?: boolean;
     /** Minimum number of decimal places */
     minimumFractionDigits?: number;
@@ -95,10 +95,8 @@ interface AmountFormatOptions {
     thousandsSeparator?: string;
     /** Custom decimal separator */
     decimalSeparator?: string;
-    /** Use native formatting with Intl.NumberFormat (defaults to false for backward compatibility) */
+    /** Use native formatting with Intl.NumberFormat (defaults to false) */
     useNativeFormatting?: boolean;
-    /** Use native currency symbol instead of international symbol */
-    useNativeSymbol?: boolean;
     /** Prefer native locale for the currency (overrides provided locale) */
     useNativeLocale?: boolean;
 }
@@ -116,9 +114,9 @@ interface AmountFormatOptions {
  * @example
  * ```typescript
  * // Creating amounts
- * const positive = Amount.from(1000, 'USD'); // $1,000.00
- * const negative = Amount.from(-500, 'USD');  // -$500.00
- * const fromString = Amount.from('-1,234.56', 'EUR'); // -€1,234.56
+ * const positive = Amount.from(1000, 'USD'); // USD 1,000.00
+ * const negative = Amount.from(-500, 'USD');  // -USD 500.00
+ * const fromString = Amount.from('-1,234.56', 'EUR'); // -EUR 1,234.56
  *
  * // Mathematical operations
  * const sum = positive.add(negative); // $500.00
@@ -480,51 +478,41 @@ declare class Amount {
      * const amount = Amount.from(-1234.56, 'USD');
      * const tzAmount = Amount.from(1234.56, 'TZS');
      *
-     * // Basic formatting (existing behavior)
-     * amount.format(); // "-$1,234.56"
+     * // Default formatting (currency codes)
+     * amount.format(); // "-USD 1,234.56"
+     * tzAmount.format(); // "TZS 1,234.56"
      *
-     * // Native formatting with proper spacing and locale
-     * tzAmount.format({ useNativeFormatting: true }); // "TSh 1,234.56"
+     * // Symbol formatting (opt-in)
+     * amount.format({ useSymbol: true }); // "-$1,234.56"
+     * tzAmount.format({ useSymbol: true }); // "TSh 1,234.56"
+     *
+     * // Native formatting with Intl (uses symbols via browser locale)
      * tzAmount.format({ useNativeFormatting: true, useNativeLocale: true }); // Uses Swahili locale
      *
-     * // Manual formatting with native symbols
-     * amount.format({ useNativeSymbol: true }); // "-$1,234.56"
-     * tzAmount.format({ useNativeSymbol: true }); // "-TSh 1,234.56" (with proper spacing)
-     *
-     * // Advanced native formatting
-     * amount.format({
-     *   useNativeFormatting: true,
-     *   useNativeLocale: true,
-     *   showSign: 'always'
-     * }); // "+$1,234.56" (US formatting)
-     *
-     * // European formatting
-     * Amount.from(1234.56, 'EUR').format({
-     *   useNativeFormatting: true,
-     *   useNativeLocale: true
-     * }); // "1.234,56 €" (German formatting)
-     *
-     * // Custom formatting (existing behavior preserved)
-     * amount.format({ symbolPosition: 'after', useGrouping: false }); // "-1234.56$"
+     * // Currency position
+     * amount.format({ currencyPosition: 'after' }); // "-1,234.56 USD"
+     *
+     * // No currency
+     * amount.format({ showCurrency: false }); // "-1,234.56"
      * ```
      */
     format(options?: AmountFormatOptions): string;
     /**
-     * Convenience method for native formatting
+     * Convenience method for native formatting using Intl.NumberFormat with symbols
      * @param options Additional formatting options
-     * @returns Formatted string using native currency conventions
+     * @returns Formatted string using native currency conventions with symbols
      */
     formatNative(options?: Omit<AmountFormatOptions, "useNativeFormatting">): string;
     /**
-     * Enhanced label using native formatting for better UX
+     * Primary display label using currency codes (e.g., "TZS 1,000.00", "USD 500.00")
      */
     get label(): string;
     /**
-     * International label using consistent formatting
+     * International label using currency codes with en-US locale
      */
     get internationalLabel(): string;
     /**
-     * Returns the amount as a plain number string without currency symbols
+     * Returns the amount as a plain number string without currency indicator
      *
      * @param options - Formatting options for the numeric value
      * @returns Plain numeric string
@@ -538,35 +526,34 @@ declare class Amount {
      * }); // "1,234.5000"
      * ```
      */
-    toPlainNumber(options?: Omit<AmountFormatOptions, "includeSymbol" | "includeCurrency" | "symbolPosition">): string;
+    toPlainNumber(options?: Omit<AmountFormatOptions, "showCurrency" | "useSymbol" | "currencyPosition">): string;
     /**
      * Formats amount in compact notation (K, M, B, T)
      *
      * @param precision - Number of decimal places for compact numbers (default: 1)
-     * @param includeSymbol - Whether to include currency symbol (default: true)
      * @param options - Additional formatting options
      * @returns Compact formatted string
      *
      * @example
      * ```typescript
-     * Amount.from(1500).toCompactFormat();        // "$1.5K"
-     * Amount.from(-2500000).toCompactFormat();    // "-$2.5M"
-     * Amount.from(1234567890).toCompactFormat();  // "$1.2B"
-     * Amount.from(999).toCompactFormat();         // "$999"
-     * Amount.from(1000000, 'EUR').toCompactFormat(2); // "€1.00M"
-     * Amount.from(1000000).toCompactFormat(2, true, { alwaysShowDecimals: true }); // "$1.00M"
-     * Amount.from(1500000).toCompactFormat(0);    // "$2M" (rounded)
+     * Amount.from(1500).toCompactFormat();        // "TZS 1.5K"
+     * Amount.from(-2500000, 'USD').toCompactFormat();    // "-USD 2.5M"
+     * Amount.from(1234567890, 'USD').toCompactFormat();  // "USD 1.2B"
+     * Amount.from(999, 'USD').toCompactFormat();         // "USD 999"
+     * Amount.from(1000000, 'EUR').toCompactFormat(2, { alwaysShowDecimals: true }); // "EUR 1.00M"
+     * Amount.from(1500000, 'USD').toCompactFormat(0);    // "USD 2M" (rounded)
      * ```
      */
     toCompactFormat(precision?: number, options?: {
-        includeSymbol?: boolean;
+        showCurrency?: boolean;
+        useSymbol?: boolean;
         alwaysShowDecimals?: boolean;
         roundingMode?: "round" | "floor" | "ceil";
     }): string;
     /**
      * Returns the amount rounded to the nearest whole number
      *
-     * @param includeSymbol - Whether to include currency symbol (default: false)
+     * @param showCurrency - Whether to include currency code (default: false)
      * @param useGrouping - Whether to use thousands separators (default: true)
      * @returns Whole number formatted string
      *
@@ -574,11 +561,11 @@ declare class Amount {
      * ```typescript
      * Amount.from(1234.56).toWholeNumber();                // "1,235"
      * Amount.from(-1234.44).toWholeNumber();               // "-1,234"
-     * Amount.from(1000.5).toWholeNumber(true);             // "$1,001"
+     * Amount.from(1000.5, 'USD').toWholeNumber(true);      // "USD 1,001"
      * Amount.from(999.4).toWholeNumber(false, false);      // "999"
      * ```
      */
-    toWholeNumber(includeSymbol?: boolean, useGrouping?: boolean): string;
+    toWholeNumber(showCurrency?: boolean, useGrouping?: boolean): string;
     /**
      * Helper method to get the actual rounded value as a number (for toWholeNumber)
      *

package/dist/models/bank/bank.d.ts

@@ -128,16 +128,14 @@ export declare class BankService {
     private constructor();
     /**
      * Gets the singleton instance of BankService.
-     * Initializes known countries synchronously on first call.
-     * Consider async initialization if data loading becomes async.
      */
     static getInstance(): BankService;
     /**
-     * Initializes bank data for a specific country synchronously.
+     * Loads bank data for a specific country synchronously.
      * @param countryCode The ISO country code (e.g., 'TZ', 'KE').
-     * @returns True if successful or already loaded, false on failure.
+     * @returns The loaded country data, or undefined on failure.
      */
-    initializeCountry(countryCode: ISO2CountryCode): boolean;
+    private loadCountryData;
     /**
      * Retrieves the loaded data structure for a given country.
      * Ensures country is initialized.
@@ -169,25 +167,18 @@ export declare class BankService {
      */
     detectBank(swiftCode: string): Bank | undefined;
     /**
-     * Searches for banks within a specific country by name, SWIFT code, or former names.
+     * Searches for banks within a specific country by SWIFT code.
      * @param countryCode The ISO country code.
-     * @param searchTerm The term to search for (case-insensitive).
+     * @param searchTerm The SWIFT code fragment to search for (case-insensitive).
      * @param limit Max number of results.
      * @returns An array of matching Bank instances.
      */
     searchBanks(countryCode: ISO2CountryCode, searchTerm: string, limit?: number): Bank[];
     /**
-     * Searches for banks across all supported countries by name, SWIFT code, or former names.
-     * @param searchTerm The term to search for (case-insensitive).
+     * Searches for banks across all supported countries by SWIFT code.
+     * @param searchTerm The SWIFT code fragment to search for (case-insensitive).
      * @param limit Max number of results.
      * @returns An array of matching Bank instances from all supported countries.
      */
     searchAllBanks(searchTerm: string, limit?: number): Bank[];
-    /**
-     * Finds banks that were formerly known by a specific name.
-     * @param formerName The former name to search for (case-insensitive).
-     * @param countryCode Optional country code to limit the search.
-     * @returns An array of Bank instances that match the former name.
-     */
-    findByFormerName(formerName: string, countryCode?: ISO2CountryCode): Bank[];
 }

package/dist/models/bank/bank.types.d.ts

@@ -1,5 +1,5 @@
 export declare const KEBankSwiftCodesSet: Set<string>;
 export declare const TZBankSwiftCodesSet: Set<string>;
-export type KEBankSwiftCode = "KCBLKENX" | "EQBLKENX" | "KCOOKENX" | "SCBLKENX" | "BARCKENX" | "CBAFKENX" | "DTKEKENX" | "FABLKENA" | "CITIKENA" | "HFCOKENX" | "SBICKENX" | "NBKEKENX" | "AFRIKENX" | "GTBOKENX" | "IMBLKENX" | "ECOCKENX" | "BARBKENX" | "BKIDKENX" | "UNAFKENX" | "SGKENX";
+export type KEBankSwiftCode = "ABNGKENA" | "ABCLKENA" | "AFRIKENX" | "BARBKENA" | "CRMFKENA" | "CHFIKENX" | "CITIKENA" | "KCOOKENA" | "MYBKKENA" | "CONKKENA" | "CRBTKENA" | "DEVKKENA" | "DTKEKENA" | "DUIBKENA" | "ECOCKENA" | "EQBLKENA" | "FABLKENA" | "FAUMKENA" | "GTBIKENA" | "GUARKENA" | "GAFRKENA" | "HBZUKENA" | "HFCOKENA" | "IMBLKENA" | "KWMIKENX" | "CIFIKENA" | "MORBKENA" | "MIEKKENA" | "NBKEKENX" | "CBAFKENX" | "PAUTKENA" | "IFCBKENA" | "PRIEKENX" | "SBMKKENA" | "SIDNKENA" | "SBICKENX" | "SCBLKENX" | "VICMKENA";
 export type TZBankSwiftCode = "CORUTZTZ" | "PBZATZTZ" | "SCBLTZTX" | "SBICTZTX" | "CITITZTZ" | "EUAFTZTZ" | "DTKETZTZ" | "AKCOTZTZ" | "EXTNTZTZ" | "KLMJTZTZ" | "NLCBTZTX" | "NMIBTZTZ" | "KCBLTZTZ" | "HABLTZTZ" | "BKMYTZTZ" | "BARCTZTZ" | "IMBLTZTZ" | "CBAFTZTZ" | "DASUTZTZ" | "BARBTZTZ" | "AZANTZTZ" | "UCCTTZTZ" | "FMBZTZTX" | "ACTZTZTZ" | "BKIDTZTZ" | "UNAFTZTZ" | "MKCBTZTZ" | "ECOCTZTZ" | "MWCBTZTZ" | "FIRNTZTX" | "AMNNTZTZ" | "EQBLTZTZ" | "TAPBTZTZ" | "MBTLTZTZ" | "CNRBTZTZ" | "MWCOTZTZ" | "GTBITZTZ" | "YETMTZTZ" | "CDSHTZTZ";
 export type BankSwiftCode = KEBankSwiftCode | TZBankSwiftCode;