@temboplus/frontend-core 0.2.1 → 0.2.3

package/script/src/models/phone_number/global/service.d.ts

@@ -0,0 +1,260 @@
+/**
+ * @fileoverview
+ *
+ * # Global Phone Number Service
+ *
+ * ## Features
+ * 1. Loads and maintains phone number metadata from patterns database
+ * 2. Validates phone numbers against country-specific patterns
+ * 3. Provides utility functions for phone number operations
+ * 4. Follows singleton pattern for efficient resource usage
+ */
+import { Country } from "../../country/country.js";
+import { PhoneNumber } from "./phone_number.js";
+import { PhoneNumberFormat } from "../format.js";
+/**
+ * Complete metadata for a country's phone number system
+ */
+export interface CountryMetadata {
+    /** The country dial code (e.g., 93 for Afghanistan) */
+    code: number;
+    /** Patterns for different types of phone numbers */
+    patterns: {
+        /** Pattern for landline numbers (required) */
+        landline: string;
+        /** Pattern for mobile numbers (required) */
+        mobile: string;
+        /** Pattern for toll-free numbers */
+        toll_free?: string;
+        /** Pattern for premium rate numbers */
+        premium_rate?: string;
+        /** Pattern for shared cost numbers */
+        shared_cost?: string;
+        /** Pattern for emergency numbers */
+        emergency?: string;
+        /** Pattern for special services */
+        special_services?: string;
+        /** Pattern for VoIP numbers */
+        voip?: string;
+        /** Pattern for personal numbers */
+        personal?: string;
+    };
+    /** Source information */
+    _source: string;
+}
+/**
+ * Mapping of ISO country codes to their phone metadata
+ */
+type CountryMetadataMap = {
+    [isoCode: string]: CountryMetadata;
+};
+/**
+ * Phone number pattern type
+ */
+export declare enum PhoneNumberType {
+    LANDLINE = "landline",
+    MOBILE = "mobile",
+    TOLL_FREE = "toll_free",
+    PREMIUM_RATE = "premium_rate",
+    SHARED_COST = "shared_cost",
+    EMERGENCY = "emergency",
+    SPECIAL_SERVICES = "special_services",
+    VOIP = "voip",
+    PERSONAL = "personal",
+    UNKNOWN = "unknown"
+}
+/**
+ * Information about a dial code extracted from a phone number
+ */
+export interface DialCodeInfo {
+    /** The dial code (e.g., "1", "44", etc.) */
+    dialCode: string;
+    /** Whether this dial code is shared by multiple countries */
+    isShared: boolean;
+    /** The national number (without the dial code) */
+    nationalNumber: string;
+    /** List of country codes that use this dial code */
+    possibleCountries: string[];
+}
+/**
+ * Error thrown when a phone number has an ambiguous country due to shared dial code
+ */
+export declare class SharedDialCodeError extends Error {
+    /** The dial code that's shared */
+    dialCode: string;
+    /** List of country codes that share this dial code */
+    countries: string[];
+    /**
+     * Creates a new SharedDialCodeError
+     *
+     * @param dialCode - The shared dial code
+     * @param countries - Countries that share this dial code
+     */
+    constructor(dialCode: string, countries: string[]);
+}
+/**
+ * Service for managing global phone number operations
+ */
+export declare class GlobalPhoneNumberService {
+    private static instance;
+    private countryMetadata;
+    private sharedCountryCodes;
+    private initialized;
+    /**
+     * Private constructor to enforce singleton pattern
+     */
+    private constructor();
+    /**
+     * Gets the singleton instance of GlobalPhoneNumberService
+     * Creates the instance if it doesn't exist
+     *
+     * @returns {GlobalPhoneNumberService} The singleton instance
+     */
+    static getInstance(): GlobalPhoneNumberService;
+    /**
+     * Initializes the service with phone patterns data
+     * Should be called once when the service is first used
+     */
+    private initialize;
+    /**
+     * Gets the metadata for a specific country
+     *
+     * @param {string} countryCode - The ISO country code
+     * @returns {CountryMetadata | undefined} The country metadata or undefined if not found
+     */
+    getCountryMetadata(countryCode: string): CountryMetadata | undefined;
+    /**
+     * Gets all country metadata
+     *
+     * @returns {CountryMetadataMap} All country metadata
+     */
+    getAllCountryMetadata(): CountryMetadataMap;
+    /**
+     * Gets all the countries that share a specific dial code
+     *
+     * @param {string | number} dialCode - The dial code to check
+     * @returns {string[]} Array of ISO country codes that share this dial code
+     */
+    getCountriesWithDialCode(dialCode: string | number): string[];
+    /**
+     * Checks if a dial code is shared between multiple countries
+     *
+     * @param {string | number} dialCode - The dial code to check
+     * @returns {boolean} True if the dial code is shared, false otherwise
+     */
+    isSharedDialCode(dialCode: string | number): boolean;
+    /**
+     * Finds the country code associated with a given dial code
+     *
+     * @param dialCode - The dial code to look up
+     * @returns The country code or undefined if not found
+     */
+    getCountryForDialCode(dialCode: string): string | undefined;
+    /**
+     * Extracts dial code information from a phone number
+     *
+     * @param phoneNumber - The phone number in international format (with +)
+     * @returns Dial code information or undefined if not found
+     */
+    extractDialCode(phoneNumber: string): DialCodeInfo | undefined;
+    /**
+     * Gets the countries that might be associated with a phone number
+     *
+     * @param {string} phoneNumber - The phone number in international format
+     * @returns {Country[]} Array of possible countries for this phone number
+     */
+    getPossibleCountries(phoneNumber: string): Country[];
+    /**
+     * Determines the most likely type of a phone number
+     *
+     * @param {string} countryCode - ISO country code
+     * @param {string} nationalNumber - The national number to check
+     * @returns {PhoneNumberType} The type of the phone number
+     */
+    getNumberType(countryCode: string, nationalNumber: string): PhoneNumberType;
+    /**
+     * Validates a phone number against country-specific patterns
+     *
+     * @param {string} countryCode - ISO country code
+     * @param {string} nationalNumber - The national number to validate
+     * @returns {boolean} True if the phone number is valid, false otherwise
+     */
+    validatePattern(countryCode: string, nationalNumber: string): boolean;
+    /**
+     * Formats a phone number according to the country's formatting rules
+     *
+     * @param {string} phoneNumber - The phone number to format
+     * @param {PhoneNumberFormat} format - The desired format
+     * @returns {string} The formatted phone number
+     */
+    formatNumber(phoneNumber: string, format?: PhoneNumberFormat): string;
+    /**
+     * Creates a PhoneNumber from an international format string
+     *
+     * @param {string} phoneNumber - The phone number in international format
+     * @returns {PhoneNumber | undefined} The parsed phone number or undefined if invalid
+     */
+    parsePhoneNumber(phoneNumber: string): PhoneNumber | undefined;
+    /**
+     * Creates a PhoneNumber from a phone number with explicit country
+     *
+     * @param {string} phoneNumber - The phone number in any format
+     * @param {Country | string} country - The country or country code
+     * @returns {PhoneNumber | undefined} The parsed phone number or undefined if invalid
+     */
+    parsePhoneNumberWithCountry(phoneNumber: string, country: Country | string): PhoneNumber | undefined;
+    /**
+     * Extracts the information needed for dialing from one country to another
+     *
+     * @param {string} fromCountry - ISO code of the country dialing from
+     * @param {PhoneNumber} phoneNumber - The phone number to dial
+     * @returns {string} The appropriately formatted dialing string
+     */
+    getDialingString(fromCountry: string, phoneNumber: PhoneNumber): string;
+    /**
+     * Cleans a phone number by removing all non-digit characters except the leading plus
+     *
+     * @param {string} phoneNumber - The phone number to clean
+     * @returns {string} The cleaned phone number
+     */
+    cleanPhoneNumber(phoneNumber: string): string;
+    /**
+     * Extracts the country and national number from an international phone number
+     *
+     * @param {string} phoneNumber - The phone number in international format
+     * @returns {[Country | undefined, string]} The country and national number
+     */
+    extractParts(phoneNumber: string): [Country | undefined, string];
+    /**
+     * Gets a list of commonly used examples of valid phone numbers for a country
+     *
+     * @param {string} countryCode - The ISO country code
+     * @returns {string[]} Array of example phone numbers
+     */
+    getExampleNumbers(countryCode: string): string[];
+    /**
+     * Generates an example phone number that would match a given pattern
+     * This is a simple implementation that handles basic patterns
+     *
+     * @param pattern - The regex pattern
+     * @returns A string that would match the pattern
+     */
+    private generateExampleFromPattern;
+    /**
+     * Checks if a phone number is valid for a specific country
+     *
+     * @param {string} phoneNumber - The phone number to validate
+     * @param {string} countryCode - The ISO country code
+     * @returns {boolean} True if the phone number is valid for the country, false otherwise
+     */
+    isValidForCountry(phoneNumber: string, countryCode: string): boolean;
+    /**
+     * Checks if a given dial code exists in our database
+     *
+     * @param dialCode - The dial code to check
+     * @returns True if the dial code exists, false otherwise
+     */
+    hasDialCode(dialCode: string): boolean;
+}
+export {};
+//# sourceMappingURL=service.d.ts.map

package/script/src/models/phone_number/global/service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../../../../../src/src/models/phone_number/global/service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAC;AACnD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEhD,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAEjD;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,uDAAuD;IACvD,IAAI,EAAE,MAAM,CAAC;IACb,oDAAoD;IACpD,QAAQ,EAAE;QACR,8CAA8C;QAC9C,QAAQ,EAAE,MAAM,CAAC;QACjB,4CAA4C;QAC5C,MAAM,EAAE,MAAM,CAAC;QACf,oCAAoC;QACpC,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,uCAAuC;QACvC,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,sCAAsC;QACtC,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,oCAAoC;QACpC,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,mCAAmC;QACnC,gBAAgB,CAAC,EAAE,MAAM,CAAC;QAC1B,+BAA+B;QAC/B,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,mCAAmC;QACnC,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB,CAAC;IACF,yBAAyB;IACzB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,KAAK,kBAAkB,GAAG;IACxB,CAAC,OAAO,EAAE,MAAM,GAAG,eAAe,CAAC;CACpC,CAAC;AASF;;GAEG;AACH,oBAAY,eAAe;IACzB,QAAQ,aAAa;IACrB,MAAM,WAAW;IACjB,SAAS,cAAc;IACvB,YAAY,iBAAiB;IAC7B,WAAW,gBAAgB;IAC3B,SAAS,cAAc;IACvB,gBAAgB,qBAAqB;IACrC,IAAI,SAAS;IACb,QAAQ,aAAa;IACrB,OAAO,YAAY;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,4CAA4C;IAC5C,QAAQ,EAAE,MAAM,CAAC;IACjB,6DAA6D;IAC7D,QAAQ,EAAE,OAAO,CAAC;IAClB,kDAAkD;IAClD,cAAc,EAAE,MAAM,CAAC;IACvB,oDAAoD;IACpD,iBAAiB,EAAE,MAAM,EAAE,CAAC;CAC7B;AAED;;GAEG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,kCAAkC;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,sDAAsD;IACtD,SAAS,EAAE,MAAM,EAAE,CAAC;IAEpB;;;;;OAKG;gBACS,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE;CASlD;AAED;;GAEG;AACH,qBAAa,wBAAwB;IACnC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAA2B;IAClD,OAAO,CAAC,eAAe,CAA0B;IACjD,OAAO,CAAC,kBAAkB,CAA6B;IACvD,OAAO,CAAC,WAAW,CAAkB;IAErC;;OAEG;IACH,OAAO;IAEP;;;;;OAKG;WACW,WAAW,IAAI,wBAAwB;IAQrD;;;OAGG;IACH,OAAO,CAAC,UAAU;IAwBlB;;;;;OAKG;IACI,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS;IAI3E;;;;OAIG;IACI,qBAAqB,IAAI,kBAAkB;IAIlD;;;;;OAKG;IACI,wBAAwB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,EAAE;IAKpE;;;;;OAKG;IACI,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO;IAM3D;;;;;OAKG;IACI,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAWlE;;;;;OAKG;IACI,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS;IAwCrE;;;;;OAKG;IACI,oBAAoB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,EAAE;IAgB3D;;;;;;OAMG;IACI,aAAa,CAClB,WAAW,EAAE,MAAM,EACnB,cAAc,EAAE,MAAM,GACrB,eAAe;IAoClB;;;;;;OAMG;IACI,eAAe,CAAC,WAAW,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,OAAO;IAmC5E;;;;;;OAMG;IACI,YAAY,CACjB,WAAW,EAAE,MAAM,EACnB,MAAM,GAAE,iBAAmD,GAC1D,MAAM;IAOT;;;;;OAKG;IACI,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS;IAIrE;;;;;;OAMG;IACI,2BAA2B,CAChC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,OAAO,GAAG,MAAM,GACxB,WAAW,GAAG,SAAS;IAU1B;;;;;;OAMG;IACI,gBAAgB,CACrB,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,WAAW,GACvB,MAAM;IAUT;;;;;OAKG;IACI,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM;IAapD;;;;;OAKG;IACI,YAAY,CAAC,WAAW,EAAE,MAAM,GAAG,CAAC,OAAO,GAAG,SAAS,EAAE,MAAM,CAAC;IAkBvE;;;;;OAKG;IACI,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,EAAE;IAyBvD;;;;;;OAMG;IACH,OAAO,CAAC,0BAA0B;IAgBlC;;;;;;OAMG;IACI,iBAAiB,CAAC,WAAW,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO;IAQ3E;;;;;OAKG;IACI,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;CAe9C"}