pakdatakit 1.0.0 → 1.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.ts CHANGED
@@ -9,6 +9,24 @@
9
9
  */
10
10
  declare function validateCNIC(cnic: string): boolean;
11
11
 
12
+ type NetworkName = 'Jazz' | 'Zong' | 'Telenor' | 'Ufone' | 'Unknown';
13
+ /**
14
+ * Detects the mobile network for a Pakistani phone number based on its prefix.
15
+ *
16
+ * Returns the original issuing network (Jazz, Zong, Telenor, or Ufone).
17
+ * Due to Mobile Number Portability (MNP), the current carrier may differ.
18
+ *
19
+ * @param phone - The phone number to look up
20
+ * @returns Network name or `"Unknown"` if the prefix is not recognized
21
+ */
22
+ declare function getNetwork(phone: string): NetworkName;
23
+
24
+ /** Combined phone validation, formatting, and network analysis result. */
25
+ interface PhoneAnalysis {
26
+ valid: boolean;
27
+ formatted: string | null;
28
+ network: NetworkName;
29
+ }
12
30
  /**
13
31
  * Validates a Pakistani mobile phone number.
14
32
  *
@@ -29,17 +47,16 @@ declare function validatePhone(phone: string): boolean;
29
47
  */
30
48
  declare function formatPhone(phone: string): string;
31
49
 
32
- type NetworkName = 'Jazz' | 'Zong' | 'Telenor' | 'Ufone' | 'Unknown';
33
50
  /**
34
- * Detects the mobile network for a Pakistani phone number based on its prefix.
51
+ * Analyzes a Pakistani mobile number in a single call.
35
52
  *
36
- * Returns the original issuing network (Jazz, Zong, Telenor, or Ufone).
37
- * Due to Mobile Number Portability (MNP), the current carrier may differ.
53
+ * Combines validation, E.164 formatting, and network detection.
54
+ * Invalid numbers return `{ valid: false, formatted: null, network: "Unknown" }`.
38
55
  *
39
- * @param phone - The phone number to look up
40
- * @returns Network name or `"Unknown"` if the prefix is not recognized
56
+ * @param phone - Phone number in any supported format
57
+ * @returns Structured phone analysis result
41
58
  */
42
- declare function getNetwork(phone: string): NetworkName;
59
+ declare function analyzePhone(phone: string): PhoneAnalysis;
43
60
 
44
61
  /**
45
62
  * Returns the province for a given Pakistani city name.
@@ -58,6 +75,30 @@ declare function getProvince(city: string): string | null;
58
75
  * @returns Alphabetically sorted list of matching city names
59
76
  */
60
77
  declare function searchCities(query: string): string[];
78
+ /**
79
+ * Returns the province for a given Pakistani district name.
80
+ *
81
+ * Matching is case-insensitive and ignores inconsistent spacing.
82
+ * Returns `null` when no exact district match is found.
83
+ *
84
+ * @param district - The district name to look up
85
+ * @returns Province name or `null` if not found
86
+ */
87
+ declare function getDistrictProvince(district: string): string | null;
88
+ /**
89
+ * Searches districts by partial, case-insensitive name match.
90
+ *
91
+ * @param query - Partial district name to search for
92
+ * @returns Alphabetically sorted list of matching district names
93
+ */
94
+ declare function searchDistricts(query: string): string[];
95
+ /**
96
+ * Returns all districts for a given province (case-insensitive).
97
+ *
98
+ * @param province - Province name to filter by
99
+ * @returns Alphabetically sorted district names
100
+ */
101
+ declare function getDistrictsByProvince(province: string): string[];
61
102
 
62
103
  /**
63
104
  * Formats a numeric amount as Pakistani Rupees with comma separators.
@@ -82,4 +123,68 @@ declare function formatPKR(amount: number): string;
82
123
  */
83
124
  declare function formatLakh(amount: number): string;
84
125
 
85
- export { type NetworkName, formatLakh, formatPKR, formatPhone, getNetwork, getProvince, searchCities, validateCNIC, validatePhone };
126
+ /**
127
+ * Creates a WhatsApp click-to-chat link for a Pakistani mobile number.
128
+ *
129
+ * Accepts local, international, and short phone formats. Returns an empty
130
+ * string when the phone number is invalid.
131
+ *
132
+ * @param phone - Pakistani mobile number in any supported format
133
+ * @param message - Optional pre-filled message (URL-encoded)
134
+ * @returns WhatsApp wa.me link or empty string if invalid
135
+ */
136
+ declare function createWhatsAppLink(phone: string, message?: string): string;
137
+
138
+ /**
139
+ * Validates a Pakistani IBAN using format and ISO 13616 mod-97 checksum.
140
+ *
141
+ * Accepts spaced or unspaced input. Only `PK` IBANs of exactly 24 characters
142
+ * are supported.
143
+ *
144
+ * @param iban - IBAN string to validate
145
+ * @returns `true` if valid, otherwise `false`
146
+ */
147
+ declare function validateIBAN(iban: string): boolean;
148
+ /**
149
+ * Returns the bank name for a valid Pakistani IBAN based on its 4-letter bank code.
150
+ *
151
+ * Returns `null` when the IBAN is invalid or the bank code is not in the dataset.
152
+ *
153
+ * @param iban - IBAN string to look up
154
+ * @returns Bank name or `null` if not found
155
+ */
156
+ declare function getBankFromIBAN(iban: string): string | null;
157
+
158
+ /**
159
+ * Returns the city name for a Pakistani postal code.
160
+ *
161
+ * @param postalCode - Postal code to look up (whitespace is ignored)
162
+ * @returns City name or `null` if not found
163
+ */
164
+ declare function getCityByPostalCode(postalCode: string): string | null;
165
+ /**
166
+ * Returns the primary postal code for a Pakistani city.
167
+ *
168
+ * Matching is case-insensitive and whitespace-tolerant.
169
+ * When multiple postal codes exist, returns the primary GPO code.
170
+ *
171
+ * @param city - City name to look up
172
+ * @returns Postal code or `null` if not found
173
+ */
174
+ declare function getPostalCode(city: string): string | null;
175
+ /**
176
+ * Returns all known postal codes for a city (case-insensitive).
177
+ *
178
+ * @param city - City name to look up
179
+ * @returns Alphabetically sorted postal codes
180
+ */
181
+ declare function getPostalCodes(city: string): string[];
182
+ /**
183
+ * Searches postal entries by city name, area, or postal code prefix.
184
+ *
185
+ * @param query - Partial search term
186
+ * @returns Matching postal code strings, sorted alphabetically
187
+ */
188
+ declare function searchPostalCodes(query: string): string[];
189
+
190
+ export { type NetworkName, type PhoneAnalysis, analyzePhone, createWhatsAppLink, formatLakh, formatPKR, formatPhone, getBankFromIBAN, getCityByPostalCode, getDistrictProvince, getDistrictsByProvince, getNetwork, getPostalCode, getPostalCodes, getProvince, searchCities, searchDistricts, searchPostalCodes, validateCNIC, validateIBAN, validatePhone };