@temboplus/frontend-core/dist/models/phone-number/phone-number.d.ts

A JavaScript/TypeScript package providing common utilities and logic shared across front-end TemboPlus projects.

import { ISO2CountryCode } from "@models/country/country.types.js";
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";
/**
 * 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 declare const PhoneNumberJSONSchema: z.ZodObject<{
    /** The phone number in E.164 format */
    e164Format: z.ZodString;
    /** Version for future compatibility */
    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.
 * This class is intended to be extended by country-specific classes.
 */
export declare class PhoneNumber implements PhoneNumberContract {
    readonly countryCode: ISO2CountryCode;
    readonly compactNumber: string;
    readonly e164Format: string;
    protected readonly _service: PhoneNumberService;
    protected readonly _parsedInfo: ParsedPhoneNumber;
    /**
     * Protected constructor. Should be called by subclasses via super()
     * or by static factory methods (`from`).
     * @param parsedInfo - The result from PhoneNumberService.parse().
     * @param service - An instance of PhoneNumberService.
     */
    protected constructor(parsedInfo: ParsedPhoneNumber, service: PhoneNumberService);
    /**
     * Validates the phone number using the underlying library via the service.
     * Subclasses can override this to add more specific validation.
     * @returns {boolean} True if the number is considered valid by the core library.
     */
    validate(): boolean;
    /**
     * Formats the phone number according to the specified format using the service.
     * Subclasses can override this if country-specific formatting differs from the library's output.
     * @param {PhoneNumberFormat} format - The desired output format.
     * @returns {string} The formatted phone number string.
     */
    getWithFormat(format: PhoneNumberFormat): string;
    /**
     * Gets the type of the phone number (e.g., MOBILE, FIXED_LINE) using the service.
     * Subclasses might override this for specific known types (e.g., always MOBILE).
     * @returns {PhoneNumberType | undefined} The determined type or undefined.
     */
    getNumberType(): PhoneNumberType | undefined;
    /**
     * Gets associated mobile operator information.
     * Base implementation returns undefined. Subclasses override this for specific countries.
     * @returns {MNOInfo | undefined} Always returns undefined in the base class.
     */
    getOperatorInfo(): MNOInfo | undefined;
    /**
     * Gets a human-readable label, typically the international format.
     * @returns {string} A display label for the phone number.
     */
    get label(): string;
    /**
     * Underlying instance from libphonenumber-js, exposed for potential advanced use.
     * Use with caution, prefer methods defined in PhoneNumberContract.
     */
    get underlyingInstance(): LibPhoneNumberInstance;
    /**
     * Creates a generic PhoneNumber instance from an input string.
     * Uses PhoneNumberService for parsing and validation.
     * Use PhoneNumberFactory.create() for potentially getting country-specific instances.
     *
     * @param input - Phone number string.
     * @param options - Parsing options like defaultCountry.
     * @returns {PhoneNumber | undefined} Instance if valid and parsable, undefined otherwise.
     */
    static from(input: string, options?: PhoneNumberParseOptions): PhoneNumber | undefined;
    /**
     * Checks if a string can potentially be parsed and validated as a phone number
     * using the generic 'from' method.
     */
    static canConstruct(input?: string | null, options?: PhoneNumberParseOptions): boolean;
    /**
     * 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.
     */
    toJSON(): PhoneNumberJSON;
    /**
     * Serializes the PhoneNumber instance to a JSON string
     */
    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.
     */
    static fromJSON(json: PhoneNumberJSON | string): PhoneNumber | undefined;
    /**
     * Creates a PhoneNumber instance from a JSON string
     */
    static fromJSONString(jsonString: string): PhoneNumber | undefined;
    /**
     * Type guard to check if an object is a valid PhoneNumberJSON using Zod validation
     */
    static isPhoneNumberJSON(obj: unknown): obj is PhoneNumberJSON;
}