pakdatakit 1.0.0 → 1.1.0

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,178 @@ 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
+ * Returns known area names for a city's postal entries.
191
+ *
192
+ * @param city - City name to look up
193
+ * @returns Alphabetically sorted area names
194
+ */
195
+ declare function getPostalAreas(city: string): string[];
196
+
197
+ /** Parsed components of a Pakistani mailing address. */
198
+ interface ParsedAddress {
199
+ raw: string;
200
+ street: string | null;
201
+ area: string | null;
202
+ city: string | null;
203
+ district: string | null;
204
+ province: string | null;
205
+ postalCode: string | null;
206
+ }
207
+ /**
208
+ * Parses a free-form Pakistani address into structured components.
209
+ *
210
+ * Extracts postal codes, matches known cities/districts/provinces from datasets,
211
+ * and assigns remaining segments to street and area fields.
212
+ *
213
+ * @param address - Raw address string
214
+ * @returns Structured address components
215
+ */
216
+ declare function parseAddress(address: string): ParsedAddress;
217
+ /**
218
+ * Formats structured address components into a single mailing line.
219
+ *
220
+ * @param parts - Address components to format
221
+ * @returns Formatted address string
222
+ */
223
+ declare function formatAddress(parts: ParsedAddress): string;
224
+
225
+ /**
226
+ * Normalizes general text: trims, collapses whitespace, and applies Unicode NFC.
227
+ *
228
+ * @param text - Input text
229
+ * @returns Normalized text
230
+ */
231
+ declare function normalizeText(text: string): string;
232
+ /**
233
+ * Normalizes informal Roman Urdu spellings to common canonical forms.
234
+ *
235
+ * Also applies {@link normalizeText} and converts Urdu/Arabic digits to English.
236
+ *
237
+ * @param text - Roman Urdu input
238
+ * @returns Normalized Roman Urdu string
239
+ */
240
+ declare function normalizeRomanUrdu(text: string): string;
241
+ /**
242
+ * Converts English/Arabic-Indic digits in a string to Urdu digits (۰–۹).
243
+ *
244
+ * @param text - Input text
245
+ * @returns Text with Urdu digits
246
+ */
247
+ declare function toUrduDigits(text: string): string;
248
+ /**
249
+ * Converts Urdu/Arabic-Indic digits in a string to English digits (0–9).
250
+ *
251
+ * @param text - Input text
252
+ * @returns Text with English digits
253
+ */
254
+ declare function toEnglishDigits(text: string): string;
255
+
256
+ /** Islamic (Hijri) date components. */
257
+ interface HijriDate {
258
+ year: number;
259
+ month: number;
260
+ day: number;
261
+ }
262
+ /**
263
+ * Converts a Gregorian `Date` to a Hijri (Islamic) date.
264
+ *
265
+ * Uses the Kuwaiti algorithm (approximate, suitable for general applications).
266
+ *
267
+ * @param date - Gregorian date (local date components are used)
268
+ * @returns Hijri date components
269
+ */
270
+ declare function toHijri(date: Date): HijriDate;
271
+ /**
272
+ * Converts a Hijri date to a Gregorian `Date` (local midnight).
273
+ *
274
+ * @param hijri - Hijri date components
275
+ * @returns Gregorian date
276
+ */
277
+ declare function fromHijri(hijri: HijriDate): Date;
278
+ /**
279
+ * Formats a Gregorian date as a Hijri date string.
280
+ *
281
+ * @param date - Gregorian date
282
+ * @returns Formatted Hijri string (e.g. `"14 Ramadan 1447"`)
283
+ */
284
+ declare function formatHijri(date: Date): string;
285
+ /**
286
+ * Returns the English name of a Hijri month (1–12).
287
+ *
288
+ * @param month - Hijri month number
289
+ * @returns Month name or empty string if invalid
290
+ */
291
+ declare function getHijriMonthName(month: number): string;
292
+ /**
293
+ * Returns whether a Gregorian date falls in the month of Ramadan.
294
+ *
295
+ * @param date - Gregorian date
296
+ * @returns `true` during Ramadan
297
+ */
298
+ declare function isRamadan(date: Date): boolean;
299
+
300
+ export { type HijriDate, type NetworkName, type ParsedAddress, type PhoneAnalysis, analyzePhone, createWhatsAppLink, formatAddress, formatHijri, formatLakh, formatPKR, formatPhone, fromHijri, getBankFromIBAN, getCityByPostalCode, getDistrictProvince, getDistrictsByProvince, getHijriMonthName, getNetwork, getPostalAreas, getPostalCode, getPostalCodes, getProvince, isRamadan, normalizeRomanUrdu, normalizeText, parseAddress, searchCities, searchDistricts, searchPostalCodes, toEnglishDigits, toHijri, toUrduDigits, validateCNIC, validateIBAN, validatePhone };