lanka-kit 0.0.0-stage → 1.1.0

package/lib/types.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Types and interfaces for Sri Lankan Identity & Verification Toolkit (lanka-id)
+ */
+export type NicFormat = 'OLD' | 'NEW';
+export type Gender = 'Male' | 'Female';
+export interface NicValidationSuccess {
+    isValid: true;
+    nic: string;
+    format: NicFormat;
+    year: number;
+    dayOfYear: number;
+    gender: Gender;
+    dateOfBirth: Date;
+    dateOfBirthFormatted: string;
+    age: number;
+    isVoter: boolean;
+    serialNumber: string;
+    checkDigit: string;
+    equivalentNic: string | null;
+    meta: {
+        isLeapYearRegistered: boolean;
+        dayOfYearRaw: number;
+    };
+}
+export interface NicValidationError {
+    isValid: false;
+    nic: string;
+    error: string;
+    code: 'EMPTY_INPUT' | 'INVALID_LENGTH' | 'INVALID_CHARACTERS' | 'INVALID_DAY_OF_YEAR' | 'FUTURE_BIRTH_DATE' | 'INVALID_FORMAT';
+}
+export type NicResult = NicValidationSuccess | NicValidationError;
+export type TelcoCarrier = 'Dialog' | 'Mobitel' | 'Hutch' | 'Airtel' | 'SLT' | 'Unknown';
+export type PhoneType = 'Mobile' | 'Fixed' | 'TollFree' | 'Unknown';
+export interface PhoneValidationSuccess {
+    isValid: true;
+    raw: string;
+    clean: string;
+    e164: string;
+    national: string;
+    international: string;
+    prefix: string;
+    carrier: TelcoCarrier;
+    type: PhoneType;
+}
+export interface PhoneValidationError {
+    isValid: false;
+    raw: string;
+    error: string;
+    code: 'EMPTY_INPUT' | 'INVALID_CHARACTERS' | 'INVALID_LENGTH' | 'UNKNOWN_PREFIX';
+}
+export type PhoneResult = PhoneValidationSuccess | PhoneValidationError;
+export interface DistrictInfo {
+    name: string;
+    code: string;
+    province: string;
+    postalCodeRange?: [number, number];
+}
+export interface PostalLocation {
+    postalCode: string;
+    city: string;
+    district: string;
+    province: string;
+}
+export interface LankaQrInfo {
+    isValid: boolean;
+    rawPayload: string;
+    formatIndicator?: string;
+    pointOfInitiation?: 'Static' | 'Dynamic';
+    merchantAccountInfo?: Record<string, string>;
+    merchantCategoryCode?: string;
+    transactionCurrency?: string;
+    transactionCurrencyCode?: string;
+    transactionAmount?: number;
+    countryCode?: string;
+    merchantName?: string;
+    merchantCity?: string;
+    postalCode?: string;
+    additionalData?: Record<string, string>;
+    crcValid?: boolean;
+    error?: string;
+}

package/lib/types.js

@@ -0,0 +1,4 @@
+/**
+ * Types and interfaces for Sri Lankan Identity & Verification Toolkit (lanka-id)
+ */
+export {};

package/lib/unicode.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Unicode normalization and search sanitization for Sinhala and Tamil text.
+ */
+/**
+ * Normalizes Sinhala Unicode text:
+ * - Fixes redundant/duplicate ZWJs (\u200D)
+ * - Removes phantom Zero Width Spaces (\u200B)
+ * - Standardizes multi-character vowel signs into their canonical unified Unicode representations
+ *
+ * Example: cleans text before saving to database to ensure consistency.
+ */
+export declare function normalizeSinhala(text: string): string;
+/**
+ * Strips all Zero Width Joiners (\u200D), ZWNJs (\u200C), and invisible characters.
+ * Use this to produce a stripped search index so that queries like 'ප්ර' match 'ප්‍ර'.
+ */
+export declare function stripZwj(text: string): string;
+/**
+ * Checks whether a given string contains Sinhala Unicode characters.
+ */
+export declare function containsSinhala(text: string): boolean;
+/**
+ * Checks whether a given string contains Tamil Unicode characters.
+ */
+export declare function containsTamil(text: string): boolean;
+/**
+ * Prepares search queries by normalizing whitespace and invisibles for reliable text lookup.
+ */
+export declare function sanitizeSearchQuery(query: string): string;

package/lib/unicode.js

@@ -0,0 +1,70 @@
+/**
+ * Unicode normalization and search sanitization for Sinhala and Tamil text.
+ */
+// Sinhala Unicode range: \u0D80 - \u0DFF
+// Tamil Unicode range: \u0B80 - \u0BFF
+const ZWJ = '\u200D'; // Zero Width Joiner
+const ZWNJ = '\u200C'; // Zero Width Non-Joiner
+const ZWS = '\u200B'; // Zero Width Space
+/**
+ * Normalizes Sinhala Unicode text:
+ * - Fixes redundant/duplicate ZWJs (\u200D)
+ * - Removes phantom Zero Width Spaces (\u200B)
+ * - Standardizes multi-character vowel signs into their canonical unified Unicode representations
+ *
+ * Example: cleans text before saving to database to ensure consistency.
+ */
+export function normalizeSinhala(text) {
+    if (!text || typeof text !== 'string')
+        return '';
+    let normalized = text;
+    // 1. Remove Zero-Width Spaces
+    normalized = normalized.replace(/\u200B/g, '');
+    // 2. Collapse multiple ZWJs into a single ZWJ
+    normalized = normalized.replace(/\u200D{2,}/g, ZWJ);
+    // 3. Remove orphan ZWJs at string boundary or around spaces
+    normalized = normalized.replace(/(^\u200D+|\u200D+$)/g, '');
+    normalized = normalized.replace(/\s\u200D+/g, ' ');
+    normalized = normalized.replace(/\u200D+\s/g, ' ');
+    // 4. Normalize composite vowels:
+    // කො: kombuva (\u0DD9) + aela-pilla (\u0DCF) -> \u0DDC (o vowel sign)
+    normalized = normalized.replace(/\u0DD9\u0DCF/g, '\u0DDC');
+    // කෝ: kombuva (\u0DD9) + diga aela-pilla (\u0DDF) -> \u0DDD (oo vowel sign)
+    normalized = normalized.replace(/\u0DD9\u0DDF/g, '\u0DDD');
+    // කෞ: kombuva (\u0DD9) + gayanukitta (\u0DDE) -> \u0DDE (au vowel sign)
+    normalized = normalized.replace(/\u0DD9\u0DDE/g, '\u0DDE');
+    return normalized.trim();
+}
+/**
+ * Strips all Zero Width Joiners (\u200D), ZWNJs (\u200C), and invisible characters.
+ * Use this to produce a stripped search index so that queries like 'ප්ර' match 'ප්‍ර'.
+ */
+export function stripZwj(text) {
+    if (!text || typeof text !== 'string')
+        return '';
+    return text.replace(/[\u200B\u200C\u200D\uFEFF]/g, '');
+}
+/**
+ * Checks whether a given string contains Sinhala Unicode characters.
+ */
+export function containsSinhala(text) {
+    if (!text || typeof text !== 'string')
+        return false;
+    return /[\u0D80-\u0DFF]/.test(text);
+}
+/**
+ * Checks whether a given string contains Tamil Unicode characters.
+ */
+export function containsTamil(text) {
+    if (!text || typeof text !== 'string')
+        return false;
+    return /[\u0B80-\u0BFF]/.test(text);
+}
+/**
+ * Prepares search queries by normalizing whitespace and invisibles for reliable text lookup.
+ */
+export function sanitizeSearchQuery(query) {
+    if (!query || typeof query !== 'string')
+        return '';
+    return stripZwj(normalizeSinhala(query)).toLowerCase().trim();
+}

package/lib/vehicle.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Sri Lankan vehicle registration plate validation and parsing.
+ */
+export interface VehiclePlateResult {
+    isValid: boolean;
+    clean: string;
+    format: 'MODERN' | 'TRANSITIONAL' | 'VINTAGE' | 'SRI' | 'UNKNOWN';
+    province?: {
+        code: string;
+        name: string;
+    };
+    category: 'Motor Car' | 'Motor Cycle' | 'Three Wheeler' | 'Dual Purpose / Van' | 'Lorry / Commercial' | 'Tractor' | 'General' | 'Unknown';
+    plateNumber: string;
+    error?: string;
+}
+export declare const PROVINCE_MAP: Record<string, string>;
+/**
+ * Validates and analyzes a Sri Lankan vehicle registration plate number.
+ *
+ * Examples:
+ * - "WP CAB-1234" (Modern 3-letter Western Province Car)
+ * - "CP BAA-5678" (Modern Central Province Motor Cycle)
+ * - "SP AAX-9012" (Modern Southern Province Three Wheeler)
+ * - "WP 300-1234" (Transitional numeric prefix)
+ * - "64-1234" (Vintage 2-digit series)
+ * - "14 ශ්‍රී 1234" / "14 Sri 1234" (Vintage Sri series)
+ */
+export declare function validateVehiclePlate(input: string): VehiclePlateResult;

package/lib/vehicle.js

@@ -0,0 +1,146 @@
+/**
+ * Sri Lankan vehicle registration plate validation and parsing.
+ */
+export const PROVINCE_MAP = {
+    WP: 'Western Province',
+    CP: 'Central Province',
+    SP: 'Southern Province',
+    NP: 'Northern Province',
+    EP: 'Eastern Province',
+    NW: 'North Western Province',
+    NC: 'North Central Province',
+    UP: 'Uva Province',
+    UVA: 'Uva Province',
+    SG: 'Sabaragamuwa Province',
+};
+function inferCategoryFromPrefix(prefix) {
+    if (!prefix)
+        return 'Unknown';
+    const firstChar = prefix.charAt(0).toUpperCase();
+    switch (firstChar) {
+        case 'A':
+            return 'Three Wheeler';
+        case 'B':
+            return 'Motor Cycle';
+        case 'C':
+        case 'K':
+            return 'Motor Car';
+        case 'D':
+        case 'P':
+        case 'H':
+            return 'Dual Purpose / Van';
+        case 'L':
+        case 'N':
+            return 'Lorry / Commercial';
+        case 'R':
+        case 'T':
+            return 'Tractor';
+        default:
+            return 'General';
+    }
+}
+/**
+ * Validates and analyzes a Sri Lankan vehicle registration plate number.
+ *
+ * Examples:
+ * - "WP CAB-1234" (Modern 3-letter Western Province Car)
+ * - "CP BAA-5678" (Modern Central Province Motor Cycle)
+ * - "SP AAX-9012" (Modern Southern Province Three Wheeler)
+ * - "WP 300-1234" (Transitional numeric prefix)
+ * - "64-1234" (Vintage 2-digit series)
+ * - "14 ශ්‍රී 1234" / "14 Sri 1234" (Vintage Sri series)
+ */
+export function validateVehiclePlate(input) {
+    if (!input || typeof input !== 'string') {
+        return {
+            isValid: false,
+            clean: '',
+            format: 'UNKNOWN',
+            category: 'Unknown',
+            plateNumber: '',
+            error: 'Input must be a non-empty string',
+        };
+    }
+    const raw = input.trim();
+    // 1. Check Vintage "Sri" / "ශ්‍රී" format: e.g. "14 ශ්‍රී 1234" or "14 Sri 1234" or "14-Sri-1234"
+    const sriRegex = /^(\d{1,3})\s*(?:ශ්‍රී|Sri|SRI|-sri-|-SRI-)\s*(\d{4})$/i;
+    const sriMatch = raw.match(sriRegex);
+    if (sriMatch) {
+        const clean = `${sriMatch[1]} ශ්‍රී ${sriMatch[2]}`;
+        return {
+            isValid: true,
+            clean,
+            format: 'SRI',
+            category: 'General',
+            plateNumber: clean,
+        };
+    }
+    // Normalize separators: replace multiple spaces with single space, ensure standard dash
+    const cleanInput = raw.replace(/\s+/g, ' ').toUpperCase();
+    // 2. Check Modern Provincial with Letters: e.g. "WP CAB-1234", "CAB-1234", "WP GA-1234", "GA-1234"
+    // Province can be 2-3 letters, letters 2-3 chars, 4 digits
+    const modernRegex = /^(?:([A-Z]{2,3})\s+)?([A-Z]{2,3})[\s-]?(\d{4})$/;
+    const modernMatch = cleanInput.match(modernRegex);
+    if (modernMatch) {
+        const provCode = modernMatch[1];
+        const letterPrefix = modernMatch[2];
+        const numberPart = modernMatch[3];
+        let provinceInfo = undefined;
+        if (provCode) {
+            const provName = PROVINCE_MAP[provCode];
+            if (provName) {
+                provinceInfo = { code: provCode, name: provName };
+            }
+        }
+        const cleanPlate = provCode
+            ? `${provCode} ${letterPrefix}-${numberPart}`
+            : `${letterPrefix}-${numberPart}`;
+        return {
+            isValid: true,
+            clean: cleanPlate,
+            format: 'MODERN',
+            province: provinceInfo,
+            category: inferCategoryFromPrefix(letterPrefix),
+            plateNumber: `${letterPrefix}-${numberPart}`,
+        };
+    }
+    // 3. Check Transitional Numeric with Province: e.g. "WP 300-1234", "SP 19-1234"
+    const transProvRegex = /^([A-Z]{2,3})\s+(\d{1,3})[\s-]?(\d{4})$/;
+    const transProvMatch = cleanInput.match(transProvRegex);
+    if (transProvMatch) {
+        const provCode = transProvMatch[1];
+        const prefixNum = transProvMatch[2];
+        const numberPart = transProvMatch[3];
+        const provName = PROVINCE_MAP[provCode];
+        const cleanPlate = `${provCode} ${prefixNum}-${numberPart}`;
+        return {
+            isValid: true,
+            clean: cleanPlate,
+            format: 'TRANSITIONAL',
+            province: provName ? { code: provCode, name: provName } : undefined,
+            category: 'General',
+            plateNumber: `${prefixNum}-${numberPart}`,
+        };
+    }
+    // 4. Check Vintage Numeric: e.g. "64-1234", "300-1234", "19-1234"
+    const vintageRegex = /^(\d{1,3})[\s-]?(\d{4})$/;
+    const vintageMatch = cleanInput.match(vintageRegex);
+    if (vintageMatch) {
+        const cleanPlate = `${vintageMatch[1]}-${vintageMatch[2]}`;
+        return {
+            isValid: true,
+            clean: cleanPlate,
+            format: 'VINTAGE',
+            category: 'General',
+            plateNumber: cleanPlate,
+        };
+    }
+    return {
+        isValid: false,
+        clean: raw,
+        format: 'UNKNOWN',
+        category: 'Unknown',
+        plateNumber: '',
+        error: 'Invalid Sri Lankan vehicle plate format. Expected format like WP CAB-1234, GA-1234, 64-1234, or 14 Sri 1234',
+    };
+}

package/lib/zod.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Zod refinement helper for Sri Lankan NIC.
+ */
+export declare const nicRefinement: {
+    validator: (val: string) => boolean;
+    message: string;
+};
+/**
+ * Zod refinement helper for Sri Lankan Phone numbers.
+ */
+export declare const phoneRefinement: {
+    validator: (val: string) => boolean;
+    message: string;
+};
+/**
+ * Zod refinement helper for Sri Lankan Driving Licenses.
+ */
+export declare const licenseRefinement: {
+    validator: (val: string) => boolean;
+    message: string;
+};
+/**
+ * Zod refinement helper for Sri Lankan Passports.
+ */
+export declare const passportRefinement: {
+    validator: (val: string) => boolean;
+    message: string;
+};
+/**
+ * Zod refinement helper for Sri Lankan Tax Identification Number (TIN).
+ */
+export declare const tinRefinement: {
+    validator: (val: string) => boolean;
+    message: string;
+};
+/**
+ * Zod refinement helper for Sri Lankan Business Registration Number (BRN / ROC).
+ */
+export declare const brnRefinement: {
+    validator: (val: string) => boolean;
+    message: string;
+};
+/**
+ * Zod refinement helper for Sri Lankan Vehicle Registration Number Plate.
+ */
+export declare const vehiclePlateRefinement: {
+    validator: (val: string) => boolean;
+    message: string;
+};
+/**
+ * Zod refinement helper for Sri Lankan Bank Code (CBSL 4-digit code).
+ */
+export declare const bankCodeRefinement: {
+    validator: (val: string) => boolean;
+    message: string;
+};
+/**
+ * Pluggable schema validator functions (usable in Zod, Yup, Joi, or React Hook Form).
+ */
+export declare const validators: {
+    nic: (value: string) => string | true;
+    phone: (value: string) => string | true;
+    license: (value: string) => string | true | undefined;
+    passport: (value: string) => string | true | undefined;
+    tin: (value: string) => string | true | undefined;
+    brn: (value: string) => string | true | undefined;
+    vehiclePlate: (value: string) => string | true | undefined;
+    bankCode: (value: string) => true | "Invalid Sri Lankan bank code";
+};

package/lib/zod.js

@@ -0,0 +1,98 @@
+import { isValidNic, validateNic } from './nic';
+import { isValidPhone, validatePhone } from './phone';
+import { validateDrivingLicense } from './license';
+import { validatePassport, validateTin, validateBrn } from './identity-extra';
+import { validateVehiclePlate } from './vehicle';
+import { isValidBankCode } from './banks';
+/**
+ * Zod refinement helper for Sri Lankan NIC.
+ */
+export const nicRefinement = {
+    validator: (val) => isValidNic(val),
+    message: 'Invalid Sri Lankan National Identity Card (NIC) number',
+};
+/**
+ * Zod refinement helper for Sri Lankan Phone numbers.
+ */
+export const phoneRefinement = {
+    validator: (val) => isValidPhone(val),
+    message: 'Invalid Sri Lankan phone number',
+};
+/**
+ * Zod refinement helper for Sri Lankan Driving Licenses.
+ */
+export const licenseRefinement = {
+    validator: (val) => validateDrivingLicense(val).isValid,
+    message: 'Invalid Sri Lankan Driving License number',
+};
+/**
+ * Zod refinement helper for Sri Lankan Passports.
+ */
+export const passportRefinement = {
+    validator: (val) => validatePassport(val).isValid,
+    message: 'Invalid Sri Lankan Passport number (e.g., N1234567)',
+};
+/**
+ * Zod refinement helper for Sri Lankan Tax Identification Number (TIN).
+ */
+export const tinRefinement = {
+    validator: (val) => validateTin(val).isValid,
+    message: 'Invalid Sri Lankan Tax Identification Number (TIN: 9 or 10 digits)',
+};
+/**
+ * Zod refinement helper for Sri Lankan Business Registration Number (BRN / ROC).
+ */
+export const brnRefinement = {
+    validator: (val) => validateBrn(val).isValid,
+    message: 'Invalid Sri Lankan Business Registration Number (e.g. PV 12345)',
+};
+/**
+ * Zod refinement helper for Sri Lankan Vehicle Registration Number Plate.
+ */
+export const vehiclePlateRefinement = {
+    validator: (val) => validateVehiclePlate(val).isValid,
+    message: 'Invalid Sri Lankan vehicle plate number (e.g. WP CAB-1234 or 64-1234)',
+};
+/**
+ * Zod refinement helper for Sri Lankan Bank Code (CBSL 4-digit code).
+ */
+export const bankCodeRefinement = {
+    validator: (val) => isValidBankCode(val),
+    message: 'Invalid Sri Lankan bank routing code (e.g. 7010 for Commercial Bank)',
+};
+/**
+ * Pluggable schema validator functions (usable in Zod, Yup, Joi, or React Hook Form).
+ */
+export const validators = {
+    nic: (value) => {
+        const res = validateNic(value);
+        return res.isValid ? true : res.error;
+    },
+    phone: (value) => {
+        const res = validatePhone(value);
+        return res.isValid ? true : res.error;
+    },
+    license: (value) => {
+        const res = validateDrivingLicense(value);
+        return res.isValid ? true : res.error;
+    },
+    passport: (value) => {
+        const res = validatePassport(value);
+        return res.isValid ? true : res.error;
+    },
+    tin: (value) => {
+        const res = validateTin(value);
+        return res.isValid ? true : res.error;
+    },
+    brn: (value) => {
+        const res = validateBrn(value);
+        return res.isValid ? true : res.error;
+    },
+    vehiclePlate: (value) => {
+        const res = validateVehiclePlate(value);
+        return res.isValid ? true : res.error;
+    },
+    bankCode: (value) => {
+        return isValidBankCode(value) ? true : 'Invalid Sri Lankan bank code';
+    },
+};

package/package.json

@@ -1,6 +1,45 @@
 {
   "name": "lanka-kit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.1.0",
+  "type": "module",
+  "description": "The Ultimate Sri Lankan Developer Toolkit: Identity (NIC, Driving License, Passport, TIN, BRN), Mobile Telco, Banking & Branch Codes, LKR Currency Words, Geo & LankaQR",
+  "main": "./lib/index.js",
+  "module": "./lib/index.js",
+  "types": "./lib/index.d.ts",
+  "files": [
+    "lib"
+  ],
+  "exports": {
+    ".": {
+      "import": "./lib/index.js",
+      "types": "./lib/index.d.ts"
+    }
+  },
+  "scripts": {
+    "dev": "vite",
+    "build:lib": "tsc",
+    "build": "tsc && vite build",
+    "preview": "vite preview",
+    "test": "tsc && node --test tests/*.test.mjs"
+  },
+  "keywords": [
+    "sri-lanka",
+    "nic",
+    "identity",
+    "verification",
+    "lanka",
+    "sinhala",
+    "tamil",
+    "phone-validator",
+    "dialog",
+    "mobitel",
+    "postal-codes",
+    "lankaqr"
+  ],
+  "author": "Lanka Developer Community",
+  "license": "MIT",
+  "devDependencies": {
+    "typescript": "^5.7.0",
+    "vite": "^6.0.0"
+  }
+}