@temboplus/frontend-core 0.2.20-beta.0 → 0.2.20-beta.1

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

@@ -4,6 +4,19 @@ import { CurrencyCode } from "../currency/index.js";
  * Supports both positive and negative amounts with optional comma separators and decimals
  */
 declare const AMOUNT_REGEX: RegExp;
+/**
+ * JSON representation interface for Amount serialization
+ */
+export interface AmountJSON {
+    /** The numeric value of the amount (can be positive, negative, or zero) */
+    value: number;
+    /** The formatted text representation of the amount */
+    text: string;
+    /** The ISO currency code */
+    currencyCode: string;
+    /** Version for future compatibility */
+    version?: string;
+}
 /**
  * Represents a monetary amount with currency information
  *
@@ -562,18 +575,21 @@ declare class Amount {
      * ```
      */
     getWholeValue(): number;
+    /**
+     * Update these methods in the Amount class in amount.ts
+     */
     /**
      * Serializes the Amount instance to a JSON-compatible object
      *
      * This method creates a plain object representation that can be safely
      * serialized to JSON without losing any essential data.
      *
-     * @returns {AmountJson} A plain object containing all necessary Amount data
+     * @returns {AmountJSON} A plain object containing all necessary Amount data
      *
      * @example
      * ```typescript
      * const amount = Amount.from(-1234.56, 'USD');
-     * const json = amount.toJson();
+     * const json = amount.toJSON();
      * console.log(json);
      * // {
      * //   value: -1234.56,
@@ -586,15 +602,36 @@ declare class Amount {
      * const jsonString = JSON.stringify(json);
      * ```
      */
-    toJson(): AmountJson;
+    toJSON(): AmountJSON;
+    /**
+     * Serializes the Amount instance to a JSON string
+     *
+     * @returns {string} JSON string representation of the amount
+     *
+     * @example
+     * ```typescript
+     * const amount = Amount.from(1000, 'TZS');
+     * const jsonString = amount.toJSONString();
+     * console.log(jsonString);
+     * // '{"value":1000,"text":"1,000","currencyCode":"TZS","version":"1.0"}'
+     *
+     * // Store or transmit
+     * localStorage.setItem('paymentAmount', jsonString);
+     *
+     * // Later, retrieve and reconstruct
+     * const stored = localStorage.getItem('paymentAmount');
+     * const reconstructed = Amount.fromJSONString(stored!);
+     * ```
+     */
+    toJSONString(): string;
     /**
-     * Creates an Amount instance from a JSON-compatible object
+     * Creates an Amount instance from a JSON-compatible object or string
      *
      * This static method reconstructs an Amount instance from data that was
-     * previously serialized using toJson(). It validates the input data and
+     * previously serialized using toJSON(). It validates the input data and
      * ensures the resulting Amount is valid.
      *
-     * @param {AmountJson | string} json - Either an AmountJson object or a JSON string
+     * @param {AmountJSON | string} json - Either an AmountJSON object or a JSON string
      * @returns {Amount | undefined} An Amount instance if valid, undefined otherwise
      *
      * @example
@@ -606,33 +643,49 @@ declare class Amount {
      *   currencyCode: "USD",
      *   version: "1.0"
      * };
-     * const amount = Amount.fromJson(jsonData);
+     * const amount = Amount.fromJSON(jsonData);
      *
      * // From JSON string
      * const jsonString = '{"value":-1234.56,"text":"1,234.56","currencyCode":"USD","version":"1.0"}';
-     * const amount2 = Amount.fromJson(jsonString);
+     * const amount2 = Amount.fromJSON(jsonString);
      *
      * // Both create equivalent Amount instances
      * console.log(amount?.label); // "-$1,234.56"
      * console.log(amount2?.label); // "-$1,234.56"
      * ```
      */
-    static fromJson(json: AmountJson | string): Amount | undefined;
+    static fromJSON(json: AmountJSON | string): Amount | undefined;
+    /**
+     * Creates an Amount instance from a JSON string
+     *
+     * Convenience method that calls fromJSON() with a string parameter.
+     *
+     * @param {string} jsonString - JSON string containing amount data
+     * @returns {Amount | undefined} An Amount instance if valid, undefined otherwise
+     *
+     * @example
+     * ```typescript
+     * const jsonString = '{"value":1000,"text":"1,000","currencyCode":"TZS","version":"1.0"}';
+     * const amount = Amount.fromJSONString(jsonString);
+     * console.log(amount?.label); // "TSh 1,000"
+     * ```
+     */
+    static fromJSONString(jsonString: string): Amount | undefined;
     /**
-     * Type guard to check if an object is a valid AmountJson
+     * Type guard to check if an object is a valid AmountJSON
      *
      * @param obj - The object to validate
-     * @returns True if the object conforms to AmountJson structure
+     * @returns True if the object conforms to AmountJSON structure
      *
      * @example
      * ```typescript
      * const data = { value: 100, text: "100.00", currencyCode: "USD" };
-     * if (Amount.isAmountJson(data)) {
-     *   const amount = Amount.fromJson(data);
+     * if (Amount.isAmountJSON(data)) {
+     *   const amount = Amount.fromJSON(data);
      * }
      * ```
      */
-    static isAmountJson(obj: unknown): obj is AmountJson;
+    static isAmountJSON(obj: unknown): obj is AmountJSON;
     /**
      * Returns the sum of multiple amounts
      *

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

@@ -1,5 +1,16 @@
 import { ISO2CountryCode } from "../country/country.types.js";
 import type { BankSwiftCode, KEBankSwiftCode, TZBankSwiftCode } from "./bank.types.js";
+/**
+ * JSON representation interface for Bank serialization
+ */
+export interface BankJSON {
+    /** The SWIFT/BIC code for the bank's head office */
+    swiftCode: string;
+    /** The ISO 3166-1 alpha-2 country code */
+    countryCode: string;
+    /** Version for future compatibility */
+    version?: string;
+}
 export declare class Bank {
     /**
      * The full registered name of the bank.
@@ -32,30 +43,6 @@ export declare class Bank {
      */
     toString(): string;
     static from(swiftCode: BankSwiftCode, countryCode: ISO2CountryCode): Bank;
-    /**
-     * Creates a Bank instance from a JSON string.
-     *
-     * The JSON should contain swiftCode and countryCode fields.
-     * The bank data is then looked up from the bank service to ensure validity.
-     *
-     * @static
-     * @param {string} jsonString - JSON string containing bank data
-     * @returns {Bank | undefined} A new Bank instance if successful, undefined if parsing fails
-     *
-     * @example
-     * ```typescript
-     * const jsonString = '{"swiftCode":"CORUTZTZ","countryCode":"TZ"}';
-     * const bank = Bank.fromJSON(jsonString);
-     * if (bank) {
-     *   console.log(bank.fullName); // "CRDB BANK PLC"
-     * }
-     *
-     * // Also works with full bank data
-     * const fullJson = '{"fullName":"CRDB BANK PLC","shortName":"CRDB","swiftCode":"CORUTZTZ","countryCode":"TZ"}';
-     * const bank2 = Bank.fromJSON(fullJson);
-     * ```
-     */
-    static fromJSON(jsonString: string): Bank | undefined;
     /**
      * Converts the Bank instance to a plain JavaScript object.
      * Suitable for serialization or data transfer.
@@ -85,27 +72,6 @@ export declare class Bank {
         swiftCode: TZBankSwiftCode | KEBankSwiftCode;
         countryCode: ISO2CountryCode;
     };
-    /**
-     * Serializes the Bank instance to a JSON string.
-     *
-     * @returns {string} JSON string representation of the bank
-     *
-     * @example
-     * ```typescript
-     * const bank = Bank.from("CORUTZTZ", "TZ");
-     * const jsonString = bank.toJSON();
-     * console.log(jsonString);
-     * // '{"fullName":"CRDB BANK PLC","shortName":"CRDB","swiftCode":"CORUTZTZ","countryCode":"TZ"}'
-     *
-     * // Store or transmit
-     * localStorage.setItem('selectedBank', jsonString);
-     *
-     * // Later, retrieve and reconstruct
-     * const stored = localStorage.getItem('selectedBank');
-     * const reconstructed = Bank.fromJSON(stored);
-     * ```
-     */
-    toJSON(): string;
     /**
      * Static method to determine if an unknown object is a valid Bank object.
      *
@@ -116,6 +82,26 @@ export declare class Bank {
      * @returns {obj is Bank} - Returns true if the object is a valid Bank, false otherwise.
      */
     static is(obj: unknown): obj is Bank;
+    /**
+   * Serializes the Bank instance to a JSON-compatible object
+   */
+    toJSON(): BankJSON;
+    /**
+     * Serializes the Bank instance to a JSON string
+     */
+    toJSONString(): string;
+    /**
+     * Creates a Bank instance from a JSON-compatible object or string
+     */
+    static fromJSON(json: BankJSON | string): Bank | undefined;
+    /**
+     * Creates a Bank instance from a JSON string
+     */
+    static fromJSONString(jsonString: string): Bank | undefined;
+    /**
+     * Type guard to check if an object is a valid BankJSON
+     */
+    static isBankJSON(obj: unknown): obj is BankJSON;
 }
 /**
  * Service for managing bank data, validation, and instance creation

package/dist/models/country/country.d.ts

@@ -27,6 +27,15 @@
 import { Currency } from "@models/currency/currency.js";
 import { CurrencyCode } from "@models/currency/currency.types.js";
 import { ISO2CountryCode, ISO3CountryCode, CountryCode } from "./country.types.js";
+/**
+ * JSON representation interface for Country serialization
+ */
+export interface CountryJSON {
+    /** The ISO 3166-1 alpha-2 country code */
+    code: string;
+    /** Version for future compatibility */
+    version?: string;
+}
 /**
  * Enum for continents
  */
@@ -716,6 +725,26 @@ export declare class Country {
      * @returns Type predicate indicating if the value is a valid Country
      */
     static is(obj: unknown): obj is Country;
+    /**
+   * Serializes the Country instance to a JSON-compatible object
+   */
+    toJSON(): CountryJSON;
+    /**
+     * Serializes the Country instance to a JSON string
+     */
+    toJSONString(): string;
+    /**
+     * Creates a Country instance from a JSON-compatible object or string
+     */
+    static fromJSON(json: CountryJSON | string): Country | undefined;
+    /**
+     * Creates a Country instance from a JSON string
+     */
+    static fromJSONString(jsonString: string): Country | undefined;
+    /**
+     * Type guard to check if an object is a valid CountryJSON
+     */
+    static isCountryJSON(obj: unknown): obj is CountryJSON;
 }
 /**
  * Service for managing country data.

package/dist/models/currency/currency.d.ts

@@ -27,6 +27,15 @@
  * dependencies are best managed in a unified module.
  */
 import type { CurrencyCode } from "./currency.types.js";
+/**
+ * JSON representation interface for Currency serialization
+ */
+export interface CurrencyJSON {
+    /** The ISO 4217 currency code */
+    code: string;
+    /** Version for future compatibility */
+    version?: string;
+}
 /**
  * Represents a currency with essential details.
  * @class Currency
@@ -367,6 +376,26 @@ export declare class Currency {
      * @returns Type predicate indicating if the value is a valid Currency
      */
     static is(obj: unknown): obj is Currency;
+    /**
+     * Serializes the Currency instance to a JSON-compatible object
+     */
+    toJSON(): CurrencyJSON;
+    /**
+     * Serializes the Currency instance to a JSON string
+     */
+    toJSONString(): string;
+    /**
+     * Creates a Currency instance from a JSON-compatible object or string
+     */
+    static fromJSON(json: CurrencyJSON | string): Currency | undefined;
+    /**
+     * Creates a Currency instance from a JSON string
+     */
+    static fromJSONString(jsonString: string): Currency | undefined;
+    /**
+     * Type guard to check if an object is a valid CurrencyJSON
+     */
+    static isCurrencyJSON(obj: unknown): obj is CurrencyJSON;
 }
 /**
  * Service for managing currency data.

package/dist/models/phone-number/phone-number.d.ts

@@ -3,6 +3,15 @@ import type { PhoneNumber as LibPhoneNumberInstance } from "libphonenumber-js";
 import { MNOInfo } from "./mno/mno.types.js";
 import { PhoneNumberService, ParsedPhoneNumber } from "./phone-number.service.js";
 import { PhoneNumberContract, PhoneNumberFormat, PhoneNumberType, PhoneNumberParseOptions } from "./phone-number.types.js";
+/**
+ * JSON representation interface for PhoneNumber serialization
+ */
+export interface PhoneNumberJSON {
+    /** The phone number in E.164 format */
+    e164Format: string;
+    /** Version for future compatibility */
+    version?: string;
+}
 /**
  * Represents a generic international phone number, validated using libphonenumber-js
  * via the PhoneNumberService. Implements the common PhoneNumberContract interface.
@@ -75,4 +84,117 @@ export declare class PhoneNumber implements PhoneNumberContract {
      * Robust type guard checking structure and validatability.
      */
     static is(obj: unknown): obj is PhoneNumberContract;
+    /**
+     * Serializes the PhoneNumber instance to a JSON-compatible object
+     *
+     * This method creates a minimal object representation. Only the E.164 format
+     * is stored as everything else (country code, compact number, number type,
+     * and MNO info) can be reconstructed from it.
+     *
+     * @returns {PhoneNumberJSON} A plain object containing minimal PhoneNumber data
+     *
+     * @example
+     * ```typescript
+     * const phone = PhoneNumber.from('+255712345678');
+     * const json = phone.toJSON();
+     * console.log(json);
+     * // {
+     * //   e164Format: "+255712345678",
+     * //   version: "1.0"
+     * // }
+     * ```
+     */
+    toJSON(): PhoneNumberJSON;
+    /**
+     * Serializes the PhoneNumber instance to a JSON string
+     *
+     * @returns {string} JSON string representation of the phone number
+     *
+     * @example
+     * ```typescript
+     * const phone = PhoneNumber.from('+254712345678');
+     * const jsonString = phone.toJSONString();
+     * console.log(jsonString);
+     * // '{"e164Format":"+254712345678","version":"1.0"}'
+     *
+     * // Store or transmit
+     * localStorage.setItem('userPhone', jsonString);
+     *
+     * // Later, retrieve and reconstruct
+     * const stored = localStorage.getItem('userPhone');
+     * const reconstructed = PhoneNumber.fromJSONString(stored!);
+     * ```
+     */
+    toJSONString(): string;
+    /**
+     * Creates a PhoneNumber instance from a JSON-compatible object or string
+     *
+     * This static method reconstructs a PhoneNumber instance from data that was
+     * previously serialized using toJSON(). It uses PhoneNumberFactory to get
+     * the appropriate instance (generic or country-specific like TZMobileNumber).
+     * All properties including country code, compact number, MNO info, and number
+     * type are automatically reconstructed from the E.164 format.
+     *
+     * @param {PhoneNumberJSON | string} json - Either a PhoneNumberJSON object or a JSON string
+     * @returns {PhoneNumber | undefined} A PhoneNumber instance if valid, undefined otherwise
+     *
+     * @example
+     * ```typescript
+     * // From object
+     * const jsonData = {
+     *   e164Format: "+255712345678",
+     *   version: "1.0"
+     * };
+     * const phone = PhoneNumber.fromJSON(jsonData);
+     *
+     * // From JSON string
+     * const jsonString = '{"e164Format":"+254712345678","version":"1.0"}';
+     * const phone2 = PhoneNumber.fromJSON(jsonString);
+     *
+     * // Both create appropriate PhoneNumber instances with all properties reconstructed
+     * console.log(phone?.countryCode); // "TZ"
+     * console.log(phone?.compactNumber); // "712345678"
+     * console.log(phone?.getOperatorInfo()?.displayName); // "Vodacom" (reconstructed!)
+     * console.log(phone?.getNumberType()); // "MOBILE"
+     *
+     * console.log(phone2?.countryCode); // "KE"
+     * console.log(phone2?.compactNumber); // "712345678"
+     * ```
+     */
+    static fromJSON(json: PhoneNumberJSON | string): PhoneNumber | undefined;
+    /**
+     * Creates a PhoneNumber instance from a JSON string
+     *
+     * Convenience method that calls fromJSON() with a string parameter.
+     *
+     * @param {string} jsonString - JSON string containing phone number data
+     * @returns {PhoneNumber | undefined} A PhoneNumber instance if valid, undefined otherwise
+     *
+     * @example
+     * ```typescript
+     * const jsonString = '{"e164Format":"+255712345678","version":"1.0"}';
+     * const phone = PhoneNumber.fromJSONString(jsonString);
+     * console.log(phone?.label); // "+255 712 345 678"
+     * console.log(phone?.getOperatorInfo()?.mobileMoneyService); // "M-Pesa" (reconstructed!)
+     * ```
+     */
+    static fromJSONString(jsonString: string): PhoneNumber | undefined;
+    /**
+     * Type guard to check if an object is a valid PhoneNumberJSON
+     *
+     * @param obj - The object to validate
+     * @returns True if the object conforms to PhoneNumberJSON structure
+     *
+     * @example
+     * ```typescript
+     * const data = {
+     *   e164Format: "+255712345678",
+     *   version: "1.0"
+     * };
+     * if (PhoneNumber.isPhoneNumberJSON(data)) {
+     *   const phone = PhoneNumber.fromJSON(data);
+     * }
+     * ```
+     */
+    static isPhoneNumberJSON(obj: unknown): obj is PhoneNumberJSON;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@temboplus/frontend-core",
-  "version": "0.2.20-beta.0",
+  "version": "0.2.20-beta.1",
   "description": "A JavaScript/TypeScript package providing common utilities and logic shared across front-end TemboPlus projects.",
   "author": "Okello Gerald",
   "license": "MIT",