lanka-kit 0.0.0-stage → 1.1.0

package/lib/index.js

@@ -0,0 +1,16 @@
+/**
+ * lanka-kit
+ * Sri Lankan developer utility toolkit.
+ */
+export * from './types';
+export * from './nic';
+export * from './phone';
+export * from './geo';
+export * from './license';
+export * from './lankaqr';
+export * from './banks';
+export * from './currency';
+export * from './vehicle';
+export * from './identity-extra';
+export * from './unicode';
+export * from './zod';

package/lib/lankaqr.d.ts

@@ -0,0 +1,13 @@
+import { LankaQrInfo } from './types';
+/**
+ * Computes EMVCo standard CRC-16 (CCITT, polynomial 0x1021, initial 0xFFFF)
+ */
+export declare function computeCrc16(data: string): string;
+/**
+ * Parses TLV (Tag-Length-Value) blocks according to EMVCo / LANKAQR standard.
+ */
+export declare function parseTlv(payload: string): Map<string, string>;
+/**
+ * Parses and validates an EMVCo-compliant LANKAQR string.
+ */
+export declare function parseLankaQr(payload: string): LankaQrInfo;

package/lib/lankaqr.js

@@ -0,0 +1,113 @@
+/**
+ * Computes EMVCo standard CRC-16 (CCITT, polynomial 0x1021, initial 0xFFFF)
+ */
+export function computeCrc16(data) {
+    let crc = 0xffff;
+    for (let i = 0; i < data.length; i++) {
+        crc ^= data.charCodeAt(i) << 8;
+        for (let j = 0; j < 8; j++) {
+            if ((crc & 0x8000) !== 0) {
+                crc = ((crc << 1) ^ 0x1021) & 0xffff;
+            }
+            else {
+                crc = (crc << 1) & 0xffff;
+            }
+        }
+    }
+    return crc.toString(16).toUpperCase().padStart(4, '0');
+}
+/**
+ * Parses TLV (Tag-Length-Value) blocks according to EMVCo / LANKAQR standard.
+ */
+export function parseTlv(payload) {
+    const map = new Map();
+    let cursor = 0;
+    while (cursor + 4 <= payload.length) {
+        const tag = payload.substring(cursor, cursor + 2);
+        const length = parseInt(payload.substring(cursor + 2, cursor + 4), 10);
+        cursor += 4;
+        if (isNaN(length) || cursor + length > payload.length) {
+            break;
+        }
+        const value = payload.substring(cursor, cursor + length);
+        cursor += length;
+        map.set(tag, value);
+    }
+    return map;
+}
+/**
+ * Parses and validates an EMVCo-compliant LANKAQR string.
+ */
+export function parseLankaQr(payload) {
+    const clean = payload.trim();
+    if (!clean) {
+        return {
+            isValid: false,
+            rawPayload: payload,
+            error: 'Empty LANKAQR payload',
+        };
+    }
+    const tlv = parseTlv(clean);
+    const formatIndicator = tlv.get('00');
+    const pointOfInitiationCode = tlv.get('01');
+    const countryCode = tlv.get('58');
+    const currencyCode = tlv.get('53');
+    const crc = tlv.get('63');
+    if (!formatIndicator) {
+        return {
+            isValid: false,
+            rawPayload: clean,
+            error: 'Missing EMVCo format indicator tag (00)',
+        };
+    }
+    // Validate CRC if present
+    let crcValid = undefined;
+    if (crc && clean.length >= 8) {
+        const dataWithoutCrcValue = clean.substring(0, clean.length - 4);
+        const calculatedCrc = computeCrc16(dataWithoutCrcValue);
+        crcValid = calculatedCrc.toUpperCase() === crc.toUpperCase();
+    }
+    // Extract merchant account info (tags 26 - 51)
+    const merchantAccountInfo = {};
+    for (let t = 26; t <= 51; t++) {
+        const tagStr = String(t).padStart(2, '0');
+        const val = tlv.get(tagStr);
+        if (val) {
+            merchantAccountInfo[tagStr] = val;
+        }
+    }
+    // Parse additional data (tag 62)
+    let additionalData = undefined;
+    const tag62 = tlv.get('62');
+    if (tag62) {
+        const subTlv = parseTlv(tag62);
+        additionalData = {};
+        for (const [k, v] of subTlv.entries()) {
+            additionalData[k] = v;
+        }
+    }
+    const rawAmount = tlv.get('54');
+    const transactionAmount = rawAmount ? parseFloat(rawAmount) : undefined;
+    const isLanka = countryCode === 'LK' || currencyCode === '144';
+    return {
+        isValid: isLanka && (crcValid === undefined || crcValid === true),
+        rawPayload: clean,
+        formatIndicator,
+        pointOfInitiation: pointOfInitiationCode === '11'
+            ? 'Static'
+            : pointOfInitiationCode === '12'
+                ? 'Dynamic'
+                : undefined,
+        merchantAccountInfo,
+        merchantCategoryCode: tlv.get('52'),
+        transactionCurrency: currencyCode === '144' ? 'LKR (Sri Lankan Rupee)' : currencyCode,
+        transactionCurrencyCode: currencyCode,
+        transactionAmount,
+        countryCode,
+        merchantName: tlv.get('59'),
+        merchantCity: tlv.get('60'),
+        postalCode: tlv.get('61'),
+        additionalData,
+        crcValid,
+    };
+}

package/lib/license.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Sri Lankan Driving License verification
+ */
+export interface LicenseResult {
+    isValid: boolean;
+    clean: string;
+    format: 'NEW' | 'OLD' | 'UNKNOWN';
+    error?: string;
+}
+/**
+ * Validates Sri Lankan Driving License format.
+ * - New format: 1 letter (usually 'B') followed by 7 digits (e.g. B1234567).
+ * - Legacy format: 7 or 8 digits.
+ */
+export declare function validateDrivingLicense(input: string): LicenseResult;
+export declare function isValidDrivingLicense(input: string): boolean;

package/lib/license.js

@@ -0,0 +1,42 @@
+/**
+ * Sri Lankan Driving License verification
+ */
+/**
+ * Validates Sri Lankan Driving License format.
+ * - New format: 1 letter (usually 'B') followed by 7 digits (e.g. B1234567).
+ * - Legacy format: 7 or 8 digits.
+ */
+export function validateDrivingLicense(input) {
+    if (typeof input !== 'string') {
+        return { isValid: false, clean: '', format: 'UNKNOWN', error: 'Input must be a string' };
+    }
+    const clean = input.trim().toUpperCase().replace(/[\s-]/g, '');
+    if (!clean) {
+        return { isValid: false, clean: '', format: 'UNKNOWN', error: 'License number cannot be empty' };
+    }
+    // Modern computerized format: e.g. B1234567
+    if (/^[A-Z][0-9]{7}$/.test(clean)) {
+        return {
+            isValid: true,
+            clean,
+            format: 'NEW',
+        };
+    }
+    // Legacy format: 7 or 8 digits
+    if (/^[0-9]{7,8}$/.test(clean)) {
+        return {
+            isValid: true,
+            clean,
+            format: 'OLD',
+        };
+    }
+    return {
+        isValid: false,
+        clean,
+        format: 'UNKNOWN',
+        error: 'Invalid driving license format. Expected modern format (e.g. B1234567) or legacy numeric format.',
+    };
+}
+export function isValidDrivingLicense(input) {
+    return validateDrivingLicense(input).isValid;
+}

package/lib/nic.d.ts

@@ -0,0 +1,38 @@
+import { NicResult, NicValidationSuccess } from './types';
+/**
+ * Check if a given year is a leap year in the Gregorian calendar.
+ */
+export declare function isLeapYear(year: number): boolean;
+/**
+ * Cleans and standardizes an NIC input string (trims whitespace, converts check letter to uppercase).
+ */
+export declare function sanitizeNic(input: string): string;
+/**
+ * Converts an Old NIC (9 digits + V/X) to New NIC (12 digits).
+ */
+export declare function convertOldToNewNic(oldNic: string): string | null;
+/**
+ * Converts a New NIC (12 digits) to Old NIC (9 digits + V) if born between 1900 and 1999.
+ */
+export declare function convertNewToOldNic(newNic: string): string | null;
+/**
+ * Converts an NIC to its alternate equivalent format if applicable.
+ */
+export declare function convertNic(nic: string): string | null;
+/**
+ * Validates and extracts comprehensive identity information from a Sri Lankan NIC.
+ * Supports both Old (9 digits + V/X) and New (12 digits) formats.
+ */
+export declare function validateNic(input: string): NicResult;
+/**
+ * Returns true if the given input is a valid Sri Lankan NIC.
+ */
+export declare function isValidNic(input: string): boolean;
+/**
+ * Parses an NIC and returns the extracted payload or throws an Error.
+ */
+export declare function parseNic(input: string): NicValidationSuccess;
+/**
+ * Formats an NIC nicely for display (e.g. 962451234V or 199624501234).
+ */
+export declare function formatNic(input: string): string;

package/lib/nic.js

@@ -0,0 +1,268 @@
+/**
+ * Month-day mapping according to Sri Lankan Department of Registration of Persons (DRP).
+ * DRP registers day-of-year on a fixed 366-day calendar where February is allocated 29 days
+ * regardless of whether the birth year is a leap year.
+ */
+const DRP_MONTH_DAYS = [
+    { month: 1, name: 'January', days: 31 },
+    { month: 2, name: 'February', days: 29 },
+    { month: 3, name: 'March', days: 31 },
+    { month: 4, name: 'April', days: 30 },
+    { month: 5, name: 'May', days: 31 },
+    { month: 6, name: 'June', days: 30 },
+    { month: 7, name: 'July', days: 31 },
+    { month: 8, name: 'August', days: 31 },
+    { month: 9, name: 'September', days: 30 },
+    { month: 10, name: 'October', days: 31 },
+    { month: 11, name: 'November', days: 30 },
+    { month: 12, name: 'December', days: 31 },
+];
+/**
+ * Check if a given year is a leap year in the Gregorian calendar.
+ */
+export function isLeapYear(year) {
+    return (year % 4 === 0 && year % 100 !== 0) || year % 400 === 0;
+}
+/**
+ * Cleans and standardizes an NIC input string (trims whitespace, converts check letter to uppercase).
+ */
+export function sanitizeNic(input) {
+    if (typeof input !== 'string')
+        return '';
+    return input.trim().toUpperCase().replace(/[\s-]/g, '');
+}
+/**
+ * Calculates calendar month and day from the DRP day-of-year (1-366).
+ */
+function resolveDrpDate(year, dayOfYear) {
+    let remainingDays = dayOfYear;
+    let resolvedMonth = 1;
+    let resolvedDay = 1;
+    for (const m of DRP_MONTH_DAYS) {
+        if (remainingDays <= m.days) {
+            resolvedMonth = m.month;
+            resolvedDay = remainingDays;
+            break;
+        }
+        remainingDays -= m.days;
+    }
+    // Handle February 29 in non-leap years
+    let isFeb29Adjustment = false;
+    if (resolvedMonth === 2 && resolvedDay === 29 && !isLeapYear(year)) {
+        isFeb29Adjustment = true;
+        resolvedDay = 28; // fallback to Feb 28 for Date object validity
+    }
+    return {
+        month: resolvedMonth,
+        day: resolvedDay,
+        isFeb29Adjustment,
+    };
+}
+/**
+ * Calculates current age based on birth date.
+ */
+function calculateAge(birthDate, referenceDate = new Date()) {
+    let age = referenceDate.getFullYear() - birthDate.getFullYear();
+    const monthDiff = referenceDate.getMonth() - birthDate.getMonth();
+    if (monthDiff < 0 ||
+        (monthDiff === 0 && referenceDate.getDate() < birthDate.getDate())) {
+        age--;
+    }
+    return age;
+}
+/**
+ * Formats a Date object to YYYY-MM-DD.
+ */
+function formatDateToIso(year, month, day) {
+    const mm = String(month).padStart(2, '0');
+    const dd = String(day).padStart(2, '0');
+    return `${year}-${mm}-${dd}`;
+}
+/**
+ * Converts an Old NIC (9 digits + V/X) to New NIC (12 digits).
+ */
+export function convertOldToNewNic(oldNic) {
+    const clean = sanitizeNic(oldNic);
+    if (!/^[0-9]{9}[VX]$/.test(clean))
+        return null;
+    const year = '19' + clean.substring(0, 2);
+    const days = clean.substring(2, 5);
+    const serial = '0' + clean.substring(5, 8);
+    const check = clean.substring(8, 9);
+    return `${year}${days}${serial}${check}`;
+}
+/**
+ * Converts a New NIC (12 digits) to Old NIC (9 digits + V) if born between 1900 and 1999.
+ */
+export function convertNewToOldNic(newNic) {
+    const clean = sanitizeNic(newNic);
+    if (!/^[0-9]{12}$/.test(clean))
+        return null;
+    const year = parseInt(clean.substring(0, 4), 10);
+    // Old NIC format was only used for individuals born before 2000
+    if (year < 1900 || year >= 2000)
+        return null;
+    // The 8th digit (index 7) in converted new NIC is always '0'
+    if (clean[7] !== '0')
+        return null;
+    const shortYear = clean.substring(2, 4);
+    const days = clean.substring(4, 7);
+    const serial = clean.substring(8, 11);
+    const check = clean.substring(11, 12);
+    return `${shortYear}${days}${serial}${check}V`;
+}
+/**
+ * Converts an NIC to its alternate equivalent format if applicable.
+ */
+export function convertNic(nic) {
+    const clean = sanitizeNic(nic);
+    if (clean.length === 10)
+        return convertOldToNewNic(clean);
+    if (clean.length === 12)
+        return convertNewToOldNic(clean);
+    return null;
+}
+/**
+ * Validates and extracts comprehensive identity information from a Sri Lankan NIC.
+ * Supports both Old (9 digits + V/X) and New (12 digits) formats.
+ */
+export function validateNic(input) {
+    const clean = sanitizeNic(input);
+    if (!clean) {
+        return {
+            isValid: false,
+            nic: input,
+            error: 'NIC input cannot be empty',
+            code: 'EMPTY_INPUT',
+        };
+    }
+    // Check length
+    if (clean.length !== 10 && clean.length !== 12) {
+        return {
+            isValid: false,
+            nic: clean,
+            error: `Invalid NIC length (${clean.length}). Old NICs must be 10 characters (9 digits + V/X), New NICs must be 12 digits.`,
+            code: 'INVALID_LENGTH',
+        };
+    }
+    let format;
+    let year;
+    let dayOfYearRaw;
+    let serialNumber;
+    let checkDigit;
+    let isVoter = true;
+    if (clean.length === 10) {
+        format = 'OLD';
+        if (!/^[0-9]{9}[VX]$/.test(clean)) {
+            return {
+                isValid: false,
+                nic: clean,
+                error: 'Old NIC format must contain exactly 9 numbers followed by V (voter) or X (non-voter).',
+                code: 'INVALID_CHARACTERS',
+            };
+        }
+        year = 1900 + parseInt(clean.substring(0, 2), 10);
+        dayOfYearRaw = parseInt(clean.substring(2, 5), 10);
+        serialNumber = clean.substring(5, 8);
+        checkDigit = clean.substring(8, 9);
+        isVoter = clean.endsWith('V');
+    }
+    else {
+        format = 'NEW';
+        if (!/^[0-9]{12}$/.test(clean)) {
+            return {
+                isValid: false,
+                nic: clean,
+                error: 'New NIC format must contain exactly 12 numeric digits.',
+                code: 'INVALID_CHARACTERS',
+            };
+        }
+        year = parseInt(clean.substring(0, 4), 10);
+        dayOfYearRaw = parseInt(clean.substring(4, 7), 10);
+        serialNumber = clean.substring(7, 11);
+        checkDigit = clean.substring(11, 12);
+    }
+    // Gender and day-of-year offset logic
+    let gender;
+    let dayOfYear;
+    if (dayOfYearRaw > 500) {
+        gender = 'Female';
+        dayOfYear = dayOfYearRaw - 500;
+    }
+    else {
+        gender = 'Male';
+        dayOfYear = dayOfYearRaw;
+    }
+    // Validate day of year range (1 - 366)
+    if (dayOfYear < 1 || dayOfYear > 366) {
+        return {
+            isValid: false,
+            nic: clean,
+            error: `Invalid birth day-of-year (${dayOfYearRaw}). Day of year must be between 001-366 for males, or 501-866 for females.`,
+            code: 'INVALID_DAY_OF_YEAR',
+        };
+    }
+    // Compute exact Date of Birth
+    const { month, day, isFeb29Adjustment } = resolveDrpDate(year, dayOfYear);
+    const dateOfBirth = new Date(Date.UTC(year, month - 1, day));
+    const now = new Date();
+    // Validate against future birth dates
+    if (dateOfBirth.getTime() > now.getTime()) {
+        return {
+            isValid: false,
+            nic: clean,
+            error: `Extracted date of birth (${formatDateToIso(year, month, day)}) is in the future.`,
+            code: 'FUTURE_BIRTH_DATE',
+        };
+    }
+    const age = calculateAge(dateOfBirth, now);
+    if (format === 'NEW') {
+        isVoter = age >= 18;
+    }
+    const equivalentNic = format === 'OLD' ? convertOldToNewNic(clean) : convertNewToOldNic(clean);
+    return {
+        isValid: true,
+        nic: clean,
+        format,
+        year,
+        dayOfYear,
+        gender,
+        dateOfBirth,
+        dateOfBirthFormatted: formatDateToIso(year, month, day),
+        age,
+        isVoter,
+        serialNumber,
+        checkDigit,
+        equivalentNic,
+        meta: {
+            isLeapYearRegistered: isFeb29Adjustment,
+            dayOfYearRaw,
+        },
+    };
+}
+/**
+ * Returns true if the given input is a valid Sri Lankan NIC.
+ */
+export function isValidNic(input) {
+    return validateNic(input).isValid;
+}
+/**
+ * Parses an NIC and returns the extracted payload or throws an Error.
+ */
+export function parseNic(input) {
+    const result = validateNic(input);
+    if (!result.isValid) {
+        throw new Error(`[lanka-id] ${result.error}`);
+    }
+    return result;
+}
+/**
+ * Formats an NIC nicely for display (e.g. 962451234V or 199624501234).
+ */
+export function formatNic(input) {
+    const clean = sanitizeNic(input);
+    if (clean.length === 10) {
+        return `${clean.substring(0, 9)}${clean.charAt(9).toUpperCase()}`;
+    }
+    return clean;
+}

package/lib/phone.d.ts

@@ -0,0 +1,24 @@
+import { PhoneResult } from './types';
+/**
+ * Cleans phone input by removing spaces, brackets, hyphens, and leading +
+ */
+export declare function sanitizePhone(input: string): string;
+/**
+ * Validates and parses a Sri Lankan phone number.
+ * Normalizes input variants like:
+ * - 0771234567
+ * - +94771234567
+ * - 0094771234567
+ * - 94771234567
+ * - 771234567
+ */
+export declare function validatePhone(input: string): PhoneResult;
+/**
+ * Returns true if the phone number is a valid Sri Lankan phone number.
+ */
+export declare function isValidPhone(input: string): boolean;
+/**
+ * Formats a valid Sri Lankan phone number to E.164 (+94771234567).
+ * Returns null if invalid.
+ */
+export declare function toE164(input: string): string | null;

package/lib/phone.js

@@ -0,0 +1,158 @@
+/**
+ * Mobile Carrier Prefix Mapping in Sri Lanka
+ */
+const MOBILE_PREFIX_MAP = {
+    '070': 'Mobitel',
+    '071': 'Mobitel',
+    '072': 'Hutch',
+    '074': 'Dialog',
+    '075': 'Airtel',
+    '076': 'Dialog',
+    '077': 'Dialog',
+    '078': 'Hutch',
+};
+/**
+ * Major Fixed Line / Landline Area Codes in Sri Lanka
+ */
+const FIXED_AREA_CODES = {
+    '011': 'Colombo',
+    '021': 'Jaffna',
+    '023': 'Mannar',
+    '024': 'Vavuniya',
+    '025': 'Anuradhapura',
+    '026': 'Trincomalee',
+    '027': 'Polonnaruwa',
+    '031': 'Negombo',
+    '032': 'Chilaw',
+    '033': 'Gampaha',
+    '034': 'Kalutara',
+    '035': 'Kegalle',
+    '036': 'Avissawella',
+    '037': 'Kurunegala',
+    '038': 'Panadura',
+    '041': 'Matara',
+    '045': 'Ratnapura',
+    '047': 'Hambantota',
+    '051': 'Hatton',
+    '052': 'Nuwara Eliya',
+    '054': 'Nawalapitiya',
+    '055': 'Badulla',
+    '057': 'Bandarawela',
+    '063': 'Ampara',
+    '065': 'Batticaloa',
+    '066': 'Matale',
+    '067': 'Kalmunai',
+    '081': 'Kandy',
+    '091': 'Galle',
+};
+/**
+ * Cleans phone input by removing spaces, brackets, hyphens, and leading +
+ */
+export function sanitizePhone(input) {
+    if (typeof input !== 'string')
+        return '';
+    return input.trim().replace(/[\s\-\(\)\.]/g, '');
+}
+/**
+ * Validates and parses a Sri Lankan phone number.
+ * Normalizes input variants like:
+ * - 0771234567
+ * - +94771234567
+ * - 0094771234567
+ * - 94771234567
+ * - 771234567
+ */
+export function validatePhone(input) {
+    const raw = typeof input === 'string' ? input.trim() : '';
+    const sanitized = sanitizePhone(input);
+    if (!sanitized) {
+        return {
+            isValid: false,
+            raw,
+            error: 'Phone number cannot be empty',
+            code: 'EMPTY_INPUT',
+        };
+    }
+    // Handle leading international plus/zeros
+    let normalized = sanitized;
+    if (normalized.startsWith('+94')) {
+        normalized = normalized.substring(3);
+    }
+    else if (normalized.startsWith('0094')) {
+        normalized = normalized.substring(4);
+    }
+    else if (normalized.startsWith('94')) {
+        normalized = normalized.substring(2);
+    }
+    // If user omitted leading 0 (e.g. 771234567, length 9)
+    if (normalized.length === 9 && !normalized.startsWith('0')) {
+        normalized = '0' + normalized;
+    }
+    // Must be 10 digits starting with 0
+    if (!/^[0-9]+$/.test(normalized)) {
+        return {
+            isValid: false,
+            raw,
+            error: 'Phone number must contain only numbers',
+            code: 'INVALID_CHARACTERS',
+        };
+    }
+    if (normalized.length !== 10 || !normalized.startsWith('0')) {
+        return {
+            isValid: false,
+            raw,
+            error: `Invalid Sri Lankan phone number length. Expected 10 digits starting with 0, got ${normalized.length} digits.`,
+            code: 'INVALID_LENGTH',
+        };
+    }
+    const prefix = normalized.substring(0, 3);
+    let carrier = 'Unknown';
+    let type = 'Unknown';
+    if (MOBILE_PREFIX_MAP[prefix]) {
+        carrier = MOBILE_PREFIX_MAP[prefix];
+        type = 'Mobile';
+    }
+    else if (FIXED_AREA_CODES[prefix]) {
+        carrier = 'SLT';
+        type = 'Fixed';
+    }
+    else {
+        return {
+            isValid: false,
+            raw,
+            error: `Unknown Sri Lankan telephone area code or mobile operator prefix: ${prefix}`,
+            code: 'UNKNOWN_PREFIX',
+        };
+    }
+    const rest = normalized.substring(3);
+    const part1 = rest.substring(0, 3);
+    const part2 = rest.substring(3);
+    const e164 = `+94${normalized.substring(1)}`;
+    const national = `${prefix} ${part1} ${part2}`;
+    const international = `+94 ${prefix.substring(1)} ${part1} ${part2}`;
+    return {
+        isValid: true,
+        raw,
+        clean: normalized,
+        e164,
+        national,
+        international,
+        prefix,
+        carrier,
+        type,
+    };
+}
+/**
+ * Returns true if the phone number is a valid Sri Lankan phone number.
+ */
+export function isValidPhone(input) {
+    return validatePhone(input).isValid;
+}
+/**
+ * Formats a valid Sri Lankan phone number to E.164 (+94771234567).
+ * Returns null if invalid.
+ */
+export function toE164(input) {
+    const res = validatePhone(input);
+    return res.isValid ? res.e164 : null;
+}