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

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

@@ -1,3 +1,4 @@
+import { z } from "zod";
 import { CurrencyCode } from "../currency/index.js";
 /**
  * Regular expression for validating amount strings
@@ -5,18 +6,33 @@ import { CurrencyCode } from "../currency/index.js";
  */
 declare const AMOUNT_REGEX: RegExp;
 /**
- * JSON representation interface for Amount serialization
+ * Zod schema for Amount JSON serialization
+ * This schema validates the JSON representation of an Amount instance
  */
-export interface AmountJSON {
+export declare const AmountJSONSchema: z.ZodObject<{
     /** The numeric value of the amount (can be positive, negative, or zero) */
-    value: number;
+    value: z.ZodNumber;
     /** The formatted text representation of the amount */
-    text: string;
+    text: z.ZodString;
     /** The ISO currency code */
-    currencyCode: string;
+    currencyCode: z.ZodString;
     /** Version for future compatibility */
-    version?: string;
-}
+    version: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+}, "strip", z.ZodTypeAny, {
+    version: string;
+    value: number;
+    text: string;
+    currencyCode: string;
+}, {
+    value: number;
+    text: string;
+    currencyCode: string;
+    version?: string | undefined;
+}>;
+/**
+ * Infer the AmountJSON type from the schema
+ */
+export type AmountJSON = z.infer<typeof AmountJSONSchema>;
 /**
  * Represents a monetary amount with currency information
  *
@@ -576,114 +592,23 @@ 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
-     *
-     * @example
-     * ```typescript
-     * const amount = Amount.from(-1234.56, 'USD');
-     * const json = amount.toJSON();
-     * console.log(json);
-     * // {
-     * //   value: -1234.56,
-     * //   text: "1,234.56",
-     * //   currencyCode: "USD",
-     * //   version: "1.0"
-     * // }
-     *
-     * // Can be safely stringified
-     * const jsonString = JSON.stringify(json);
-     * ```
-     */
+   * Serializes the Amount instance to a JSON-compatible object
+   */
     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 or string
-     *
-     * This static method reconstructs an Amount instance from data that was
-     * 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
-     * @returns {Amount | undefined} An Amount instance if valid, undefined otherwise
-     *
-     * @example
-     * ```typescript
-     * // From object
-     * const jsonData = {
-     *   value: -1234.56,
-     *   text: "1,234.56",
-     *   currencyCode: "USD",
-     *   version: "1.0"
-     * };
-     * 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);
-     *
-     * // 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;
     /**
      * 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
-     *
-     * @param obj - The object to validate
-     * @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);
-     * }
-     * ```
+     * Type guard to check if an object is a valid AmountJSON using Zod validation
      */
     static isAmountJSON(obj: unknown): obj is AmountJSON;
     /**

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

@@ -1,16 +1,11 @@
 import { ISO2CountryCode } from "../country/country.types.js";
 import type { BankSwiftCode, KEBankSwiftCode, TZBankSwiftCode } from "./bank.types.js";
+import { z } from "zod";
+import { BankJSONSchema } from "./bank.schema.js";
 /**
- * JSON representation interface for Bank serialization
+ * Infer the BankJSON type from the schema
  */
-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 type BankJSON = z.infer<typeof BankJSONSchema>;
 export declare class Bank {
     /**
      * The full registered name of the bank.
@@ -99,7 +94,7 @@ export declare class Bank {
      */
     static fromJSONString(jsonString: string): Bank | undefined;
     /**
-     * Type guard to check if an object is a valid BankJSON
+     * Type guard to check if an object is a valid BankJSON using Zod validation
      */
     static isBankJSON(obj: unknown): obj is BankJSON;
 }

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

@@ -1,3 +1,23 @@
 import { z } from "zod";
 export declare const TZBankSWIFTCodeSchema: z.ZodEffects<z.ZodString, string, string>;
 export declare const KEBankSWIFTCodeSchema: z.ZodEffects<z.ZodString, string, string>;
+/**
+* Zod schema for Bank JSON serialization
+* This schema validates the JSON representation of a Bank instance
+*/
+export declare const BankJSONSchema: z.ZodObject<{
+    /** The SWIFT/BIC code for the bank's head office */
+    swiftCode: z.ZodString;
+    /** The ISO 3166-1 alpha-2 country code */
+    countryCode: z.ZodString;
+    /** Version for future compatibility */
+    version: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+}, "strip", z.ZodTypeAny, {
+    version: string;
+    swiftCode: string;
+    countryCode: string;
+}, {
+    swiftCode: string;
+    countryCode: string;
+    version?: string | undefined;
+}>;

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

@@ -27,15 +27,12 @@
 import { Currency } from "@models/currency/currency.js";
 import { CurrencyCode } from "@models/currency/currency.types.js";
 import { ISO2CountryCode, ISO3CountryCode, CountryCode } from "./country.types.js";
+import { z } from "zod";
+import { CountryJSONSchema } from "./country.schema.js";
 /**
- * JSON representation interface for Country serialization
+ * Infer the CountryJSON type from the schema
  */
-export interface CountryJSON {
-    /** The ISO 3166-1 alpha-2 country code */
-    code: string;
-    /** Version for future compatibility */
-    version?: string;
-}
+export type CountryJSON = z.infer<typeof CountryJSONSchema>;
 /**
  * Enum for continents
  */
@@ -726,8 +723,8 @@ export declare class Country {
      */
     static is(obj: unknown): obj is Country;
     /**
-   * Serializes the Country instance to a JSON-compatible object
-   */
+     * Serializes the Country instance to a JSON-compatible object
+     */
     toJSON(): CountryJSON;
     /**
      * Serializes the Country instance to a JSON string
@@ -742,7 +739,7 @@ export declare class Country {
      */
     static fromJSONString(jsonString: string): Country | undefined;
     /**
-     * Type guard to check if an object is a valid CountryJSON
+     * Type guard to check if an object is a valid CountryJSON using Zod validation
      */
     static isCountryJSON(obj: unknown): obj is CountryJSON;
 }

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

@@ -1,4 +1,20 @@
 import { z } from "zod";
+/**
+ * Zod schema for Country JSON serialization
+ * This schema validates the JSON representation of a Country instance
+ */
+export declare const CountryJSONSchema: z.ZodObject<{
+    /** The ISO 3166-1 alpha-2 country code */
+    code: z.ZodString;
+    /** Version for future compatibility */
+    version: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+}, "strip", z.ZodTypeAny, {
+    code: string;
+    version: string;
+}, {
+    code: string;
+    version?: string | undefined;
+}>;
 /**
  * Zod schema for validating ISO 3166-1 alpha-2 country codes.
  *
@@ -43,4 +59,15 @@ export declare const ISO3CountryCodeSchema: z.ZodEffects<z.ZodString, string, st
  *   console.error("Invalid country code");
  * }
  */
-export declare const CountryCodeSchema: z.ZodUnion<[z.ZodEffects<z.ZodString, string, string>, z.ZodEffects<z.ZodString, string, string>]>;
+export declare const CountryCodeSchema: z.ZodUnion<[z.ZodEffects<z.ZodString, string, string>, z.ZodEffects<z.ZodString, string, string>, z.ZodObject<{
+    /** The ISO 3166-1 alpha-2 country code */
+    code: z.ZodString;
+    /** Version for future compatibility */
+    version: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+}, "strip", z.ZodTypeAny, {
+    code: string;
+    version: string;
+}, {
+    code: string;
+    version?: string | undefined;
+}>]>;

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

@@ -27,15 +27,12 @@
  * dependencies are best managed in a unified module.
  */
 import type { CurrencyCode } from "./currency.types.js";
+import { z } from "zod";
+import { CurrencyJSONSchema } from "./currency.schema.js";
 /**
- * JSON representation interface for Currency serialization
+ * Infer the CurrencyJSON type from the schema
  */
-export interface CurrencyJSON {
-    /** The ISO 4217 currency code */
-    code: string;
-    /** Version for future compatibility */
-    version?: string;
-}
+export type CurrencyJSON = z.infer<typeof CurrencyJSONSchema>;
 /**
  * Represents a currency with essential details.
  * @class Currency
@@ -393,7 +390,7 @@ export declare class Currency {
      */
     static fromJSONString(jsonString: string): Currency | undefined;
     /**
-     * Type guard to check if an object is a valid CurrencyJSON
+     * Type guard to check if an object is a valid CurrencyJSON using Zod validation
      */
     static isCurrencyJSON(obj: unknown): obj is CurrencyJSON;
 }

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

@@ -6,3 +6,19 @@ import { z } from "zod";
  * If the validation fails, it returns an error message.
  */
 export declare const CurrencyCodeSchema: z.ZodEffects<z.ZodString, string, string>;
+/**
+ * Zod schema for Currency JSON serialization
+ * This schema validates the JSON representation of a Currency instance
+ */
+export declare const CurrencyJSONSchema: z.ZodObject<{
+    /** The ISO 4217 currency code */
+    code: z.ZodString;
+    /** Version for future compatibility */
+    version: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+}, "strip", z.ZodTypeAny, {
+    code: string;
+    version: string;
+}, {
+    code: string;
+    version?: string | undefined;
+}>;

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

@@ -3,15 +3,33 @@ 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";
+import { z } from "zod";
 /**
- * JSON representation interface for PhoneNumber serialization
+ * Zod schema for PhoneNumber JSON serialization
+ * This schema validates the JSON representation of a PhoneNumber instance
+ *
+ * E.164 format validation rules:
+ * - Starts with '+'
+ * - Followed by country code (1-3 digits, first digit 1-9)
+ * - Total length: 8-16 characters (including '+')
+ * - Contains only digits after '+'
  */
-export interface PhoneNumberJSON {
+export declare const PhoneNumberJSONSchema: z.ZodObject<{
     /** The phone number in E.164 format */
-    e164Format: string;
+    e164Format: z.ZodString;
     /** Version for future compatibility */
-    version?: string;
-}
+    version: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+}, "strip", z.ZodTypeAny, {
+    version: string;
+    e164Format: string;
+}, {
+    e164Format: string;
+    version?: string | undefined;
+}>;
+/**
+ * Infer the PhoneNumberJSON type from the schema
+ */
+export type PhoneNumberJSON = z.infer<typeof PhoneNumberJSONSchema>;
 /**
  * Represents a generic international phone number, validated using libphonenumber-js
  * via the PhoneNumberService. Implements the common PhoneNumberContract interface.
@@ -90,40 +108,10 @@ export declare class PhoneNumber implements PhoneNumberContract {
      * 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;
     /**
@@ -134,67 +122,14 @@ export declare class PhoneNumber implements PhoneNumberContract {
      * 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);
-     * }
-     * ```
+     * Type guard to check if an object is a valid PhoneNumberJSON using Zod validation
      */
     static isPhoneNumberJSON(obj: unknown): obj is PhoneNumberJSON;
 }

package/package.json

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