ceylon-devkit 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 CeylonDevKit Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -1,3 +1,145 @@
-# Temporary Holding Version
+# 🇱🇰 CeylonDevKit
+
+> The all-in-one Sri Lankan developer toolkit for Node.js and TypeScript.
+
+[![npm version](https://img.shields.io/npm/v/ceylon-devkit.svg)](https://www.npmjs.com/package/ceylon-devkit)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+**CeylonDevKit** brings essential Sri Lanka-specific business and financial tools into a single, zero-dependency, type-safe library:
+
+1. 💵 **LKR Currency to Words & Formatter** (Sinhala & English words, Cheque writing, Lakhs & Crores).
+2. 🏦 **Sri Lanka Bank & Branch Lookup** (Codes for BOC, Commercial Bank, Sampath, HNB, People's Bank, etc.).
+3. 📑 **TIN & VAT Validator + Tax Calculator** (9-digit IRD TIN validator, VAT number validator, and automated 18% VAT & 2.5% SSCL calculator).
+4. 📅 **CBSL Working Days & Holidays Calculator** (Bank, Mercantile, and Public holidays filter, working days duration, and payment due date calculator).
+
+---
+
+## 📦 Installation
+
+```bash
+npm install ceylon-devkit
+# or
+yarn add ceylon-devkit
+# or
+pnpm add ceylon-devkit
+```
+
+---
+
+## 🚀 Quick Start & Usage
+
+### 1. Currency to Words (English & Sinhala)
+
+Convert numbers to currency words for Invoices, Receipts, and Cheques:
+
+```typescript
+import { lkrToWords, formatLKR } from 'ceylon-devkit';
+
+// English
+lkrToWords(1550.50);
+// => "One Thousand Five Hundred Fifty Rupees and Fifty Cents Only"
+
+// Sinhala (සිංහල)
+lkrToWords(1550.50, { lang: 'si' });
+// => "රුපියල් එක්දහස් පන්සිය පනහයි ශත පනහයි පමණි"
+
+// Cheque printing format
+lkrToWords(50000, { chequeFormat: true });
+// => "*** Fifty Thousand Rupees Only ***"
+
+// South Asian Number Formatter (Lakhs & Crores)
+formatLKR(1500000, { compact: true });
+// => "Rs. 15.00 Lakhs"
+
+formatLKR(25000000, { compact: true, compactLang: 'si' });
+// => "රු. 2.50 කෝටි"
+```
+
+---
+
+### 2. Bank & Branch Codes Lookup
+
+Lookup official 4-digit bank codes, SWIFT codes, and branches:
+
+```typescript
+import { findBank, getBanks, getBranches } from 'ceylon-devkit';
+
+// Find bank by 4-digit code or name
+findBank('7056');
+// => { code: '7056', name: 'Commercial Bank of Ceylon PLC', shortName: 'Commercial Bank', swiftCode: 'CCEYLKLX' }
+
+findBank('Sampath');
+// => { code: '7278', name: 'Sampath Bank PLC', shortName: 'Sampath Bank', swiftCode: 'BSAMLKLX' }
+
+// Get branches for a bank
+const branches = getBranches('7056');
+// => [{ code: '001', name: 'Colombo Fort / Head Office', ... }, ...]
+```
+
+---
+
+### 3. TIN / VAT Validator & Tax Calculator (VAT & SSCL)
+
+Validate Inland Revenue Department (IRD) TIN numbers and calculate taxes:
+
+```typescript
+import { validateTIN, validateVAT, calculateTax } from 'ceylon-devkit';
+
+// Validate 9-digit IRD TIN
+validateTIN('123456789');
+// => { isValid: true, tin: '123456789', formatted: '123-456-789' }
+
+// Validate VAT Number
+validateVAT('123456789-7000');
+// => { isValid: true, baseTin: '123456789', branchCode: '7000' }
+
+// Calculate 18% VAT and 2.5% SSCL according to Sri Lankan tax laws
+const tax = calculateTax({
+  amount: 10000,
+  includeSSCL: true // Calculates SSCL 2.5% + VAT 18%
+});
+/*
+Output:
+{
+  baseAmount: 10000,
+  ssclAmount: 250,
+  vatAmount: 1845,
+  totalTax: 2095,
+  totalAmount: 12095
+}
+*/
+```
+
+---
+
+### 4. Working Days & Holidays Calculator
+
+Calculate actual working days excluding weekends and statutory Sri Lankan holidays:
+
+```typescript
+import { isWorkingDay, getWorkingDays, addWorkingDays } from 'ceylon-devkit';
+
+// Check if a date is a working day
+isWorkingDay(new Date('2025-04-14'));
+// => false (Sinhala & Tamil New Year Day)
+
+// Calculate total working days in a date range
+const workingDays = getWorkingDays(new Date('2025-04-01'), new Date('2025-04-30'));
+// => Returns number of working days excluding weekends and statutory holidays
+
+// Calculate payment due date after 14 working days
+const invoiceDueDate = addWorkingDays(new Date(), 14);
+```
+
+---
+
+## 🛠️ TypeScript & ESM Support
+
+`ceylon-devkit` comes with full TypeScript definitions out of the box and supports both **CommonJS (`require`)** and **ES Modules (`import`)**.
+
+---
+
+## 📄 License
+
+MIT License © 2026. Made with ❤️ in Sri Lanka.
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.

package/dist/index.d.mts

@@ -0,0 +1,200 @@
+/**
+ * Options for converting LKR currency to words.
+ */
+interface ToWordsOptions {
+    /** Language output: 'en' for English, 'si' for Sinhala (Default: 'en') */
+    lang?: 'en' | 'si';
+    /** Whether to append 'Only' / 'පමණයි' at the end (Default: true) */
+    showOnly?: boolean;
+    /** Format suitable for cheques, wrapped with asterisks (Default: false) */
+    chequeFormat?: boolean;
+}
+/**
+ * Options for South Asian LKR currency formatting.
+ */
+interface FormatLKROptions {
+    /** Symbol prefix: 'Rs.' or 'රු.' or 'LKR' (Default: 'Rs. ') */
+    prefix?: string;
+    /** Decimal places (Default: 2) */
+    decimals?: number;
+    /** Format in South Asian grouping (Lakhs and Crores) */
+    compact?: boolean;
+    /** Language for compact text ('en' for Lakhs/Crores, 'si' for ලක්ෂ/කෝටි) */
+    compactLang?: 'en' | 'si';
+}
+/**
+ * Converts an LKR numeric amount into English or Sinhala words.
+ */
+declare function lkrToWords(amount: number, options?: ToWordsOptions): string;
+/**
+ * Formats a number into LKR currency or South Asian compact format (Lakhs / Crores).
+ */
+declare function formatLKR(amount: number, options?: FormatLKROptions): string;
+
+interface Bank {
+    code: string;
+    name: string;
+    shortName: string;
+    swiftCode?: string;
+    headOffice?: string;
+}
+interface Branch {
+    code: string;
+    name: string;
+    bankCode: string;
+    district?: string;
+}
+/**
+ * List of registered commercial and specialized banks in Sri Lanka (CBSL).
+ */
+declare const SRI_LANKAN_BANKS: Bank[];
+/**
+ * Common major branch codes across Sri Lankan districts.
+ */
+declare const SRI_LANKAN_BRANCHES: Branch[];
+/**
+ * Returns the list of all registered Sri Lankan banks.
+ */
+declare function getBanks(): Bank[];
+/**
+ * Search for a bank by its 4-digit code, name, or short name.
+ *
+ * @example
+ * ```ts
+ * findBank('7056'); // => Commercial Bank of Ceylon PLC
+ * findBank('Sampath'); // => Sampath Bank PLC
+ * ```
+ */
+declare function findBank(query: string): Bank | undefined;
+/**
+ * Returns branches for a given bank code.
+ */
+declare function getBranches(bankCode: string): Branch[];
+/**
+ * Search for a branch by branch code or branch name within a bank.
+ */
+declare function findBranch(bankCode: string, query: string): Branch | undefined;
+
+interface TinValidationResult {
+    isValid: boolean;
+    tin?: string;
+    formatted?: string;
+    error?: string;
+}
+interface VatValidationResult {
+    isValid: boolean;
+    vatNumber?: string;
+    baseTin?: string;
+    branchCode?: string;
+    error?: string;
+}
+interface TaxCalculationOptions {
+    /** The monetary amount */
+    amount: number;
+    /** Whether the amount provided is already inclusive of taxes (Default: false) */
+    isInclusive?: boolean;
+    /** VAT rate percentage (Default: 18%) */
+    vatRate?: number;
+    /** Whether to calculate Social Security Contribution Levy (SSCL) (Default: false) */
+    includeSSCL?: boolean;
+    /** SSCL rate percentage (Default: 2.5%) */
+    ssclRate?: number;
+}
+interface TaxBreakdown {
+    baseAmount: number;
+    ssclAmount: number;
+    vatAmount: number;
+    totalTax: number;
+    totalAmount: number;
+}
+/**
+ * Validates a Sri Lankan Taxpayer Identification Number (TIN) issued by IRD.
+ * Standard format is a 9-digit numeric sequence.
+ *
+ * @example
+ * ```ts
+ * validateTIN('123456789'); // => { isValid: true, tin: '123456789', formatted: '123-456-789' }
+ * ```
+ */
+declare function validateTIN(input: string | number): TinValidationResult;
+/**
+ * Validates a Sri Lankan VAT Registration Number.
+ * Format is typically 9 digits followed by a 4-digit code (e.g., 123456789-7000) or 9 digits.
+ *
+ * @example
+ * ```ts
+ * validateVAT('123456789-7000'); // => { isValid: true, baseTin: '123456789', branchCode: '7000' }
+ * ```
+ */
+declare function validateVAT(input: string): VatValidationResult;
+/**
+ * Calculate Sri Lanka VAT (18%) and optional SSCL (2.5%) for invoicing.
+ * Supports both tax-exclusive and tax-inclusive calculations.
+ *
+ * @example
+ * ```ts
+ * calculateTax({ amount: 10000, includeSSCL: true });
+ * // => { baseAmount: 10000, ssclAmount: 250, vatAmount: 1845, totalAmount: 12095 }
+ * ```
+ */
+declare function calculateTax(options: TaxCalculationOptions): TaxBreakdown;
+
+type HolidayCategory = 'public' | 'bank' | 'mercantile';
+interface Holiday {
+    date: string;
+    name: string;
+    categories: HolidayCategory[];
+}
+/**
+ * Standard Sri Lankan Statutory & Public/Bank/Mercantile Holidays.
+ * Covers official annual holidays recognized by CBSL and the Ministry of Public Administration.
+ */
+declare const SRI_LANKAN_HOLIDAYS: Holiday[];
+interface WorkingDaysOptions {
+    /** Check against Bank holidays (Default: true) */
+    bankHolidays?: boolean;
+    /** Check against Mercantile holidays (for private sector) (Default: false) */
+    mercantileOnly?: boolean;
+    /** Treat Saturdays as working days (Default: false) */
+    saturdayWorking?: boolean;
+}
+/**
+ * Check if a date is a weekend.
+ */
+declare function isWeekend(date: Date, saturdayWorking?: boolean): boolean;
+/**
+ * Returns holiday details if the given date is a Sri Lankan statutory holiday.
+ */
+declare function getHoliday(date: Date): Holiday | undefined;
+/**
+ * Check if a given date is a Sri Lankan working day.
+ *
+ * @example
+ * ```ts
+ * isWorkingDay(new Date('2025-04-14')); // => false (New Year Day)
+ * ```
+ */
+declare function isWorkingDay(date: Date, options?: WorkingDaysOptions): boolean;
+/**
+ * Calculates the number of working days between two dates (inclusive),
+ * excluding weekends and statutory Sri Lankan holidays.
+ *
+ * @example
+ * ```ts
+ * getWorkingDays(new Date('2025-04-01'), new Date('2025-04-30'));
+ * ```
+ */
+declare function getWorkingDays(startDate: Date, endDate: Date, options?: WorkingDaysOptions): number;
+/**
+ * Adds a specific number of working days to a given start date.
+ * Useful for calculating invoice payment due dates or credit terms.
+ *
+ * @example
+ * ```ts
+ * // Calculate due date after 10 working days:
+ * const dueDate = addWorkingDays(new Date(), 10);
+ * ```
+ */
+declare function addWorkingDays(startDate: Date, daysToAdd: number, options?: WorkingDaysOptions): Date;
+
+export { type Bank, type Branch, type FormatLKROptions, type Holiday, type HolidayCategory, SRI_LANKAN_BANKS, SRI_LANKAN_BRANCHES, SRI_LANKAN_HOLIDAYS, type TaxBreakdown, type TaxCalculationOptions, type TinValidationResult, type ToWordsOptions, type VatValidationResult, type WorkingDaysOptions, addWorkingDays, calculateTax, findBank, findBranch, formatLKR, getBanks, getBranches, getHoliday, getWorkingDays, isWeekend, isWorkingDay, lkrToWords, validateTIN, validateVAT };

package/dist/index.d.ts

@@ -0,0 +1,200 @@
+/**
+ * Options for converting LKR currency to words.
+ */
+interface ToWordsOptions {
+    /** Language output: 'en' for English, 'si' for Sinhala (Default: 'en') */
+    lang?: 'en' | 'si';
+    /** Whether to append 'Only' / 'පමණයි' at the end (Default: true) */
+    showOnly?: boolean;
+    /** Format suitable for cheques, wrapped with asterisks (Default: false) */
+    chequeFormat?: boolean;
+}
+/**
+ * Options for South Asian LKR currency formatting.
+ */
+interface FormatLKROptions {
+    /** Symbol prefix: 'Rs.' or 'රු.' or 'LKR' (Default: 'Rs. ') */
+    prefix?: string;
+    /** Decimal places (Default: 2) */
+    decimals?: number;
+    /** Format in South Asian grouping (Lakhs and Crores) */
+    compact?: boolean;
+    /** Language for compact text ('en' for Lakhs/Crores, 'si' for ලක්ෂ/කෝටි) */
+    compactLang?: 'en' | 'si';
+}
+/**
+ * Converts an LKR numeric amount into English or Sinhala words.
+ */
+declare function lkrToWords(amount: number, options?: ToWordsOptions): string;
+/**
+ * Formats a number into LKR currency or South Asian compact format (Lakhs / Crores).
+ */
+declare function formatLKR(amount: number, options?: FormatLKROptions): string;
+
+interface Bank {
+    code: string;
+    name: string;
+    shortName: string;
+    swiftCode?: string;
+    headOffice?: string;
+}
+interface Branch {
+    code: string;
+    name: string;
+    bankCode: string;
+    district?: string;
+}
+/**
+ * List of registered commercial and specialized banks in Sri Lanka (CBSL).
+ */
+declare const SRI_LANKAN_BANKS: Bank[];
+/**
+ * Common major branch codes across Sri Lankan districts.
+ */
+declare const SRI_LANKAN_BRANCHES: Branch[];
+/**
+ * Returns the list of all registered Sri Lankan banks.
+ */
+declare function getBanks(): Bank[];
+/**
+ * Search for a bank by its 4-digit code, name, or short name.
+ *
+ * @example
+ * ```ts
+ * findBank('7056'); // => Commercial Bank of Ceylon PLC
+ * findBank('Sampath'); // => Sampath Bank PLC
+ * ```
+ */
+declare function findBank(query: string): Bank | undefined;
+/**
+ * Returns branches for a given bank code.
+ */
+declare function getBranches(bankCode: string): Branch[];
+/**
+ * Search for a branch by branch code or branch name within a bank.
+ */
+declare function findBranch(bankCode: string, query: string): Branch | undefined;
+
+interface TinValidationResult {
+    isValid: boolean;
+    tin?: string;
+    formatted?: string;
+    error?: string;
+}
+interface VatValidationResult {
+    isValid: boolean;
+    vatNumber?: string;
+    baseTin?: string;
+    branchCode?: string;
+    error?: string;
+}
+interface TaxCalculationOptions {
+    /** The monetary amount */
+    amount: number;
+    /** Whether the amount provided is already inclusive of taxes (Default: false) */
+    isInclusive?: boolean;
+    /** VAT rate percentage (Default: 18%) */
+    vatRate?: number;
+    /** Whether to calculate Social Security Contribution Levy (SSCL) (Default: false) */
+    includeSSCL?: boolean;
+    /** SSCL rate percentage (Default: 2.5%) */
+    ssclRate?: number;
+}
+interface TaxBreakdown {
+    baseAmount: number;
+    ssclAmount: number;
+    vatAmount: number;
+    totalTax: number;
+    totalAmount: number;
+}
+/**
+ * Validates a Sri Lankan Taxpayer Identification Number (TIN) issued by IRD.
+ * Standard format is a 9-digit numeric sequence.
+ *
+ * @example
+ * ```ts
+ * validateTIN('123456789'); // => { isValid: true, tin: '123456789', formatted: '123-456-789' }
+ * ```
+ */
+declare function validateTIN(input: string | number): TinValidationResult;
+/**
+ * Validates a Sri Lankan VAT Registration Number.
+ * Format is typically 9 digits followed by a 4-digit code (e.g., 123456789-7000) or 9 digits.
+ *
+ * @example
+ * ```ts
+ * validateVAT('123456789-7000'); // => { isValid: true, baseTin: '123456789', branchCode: '7000' }
+ * ```
+ */
+declare function validateVAT(input: string): VatValidationResult;
+/**
+ * Calculate Sri Lanka VAT (18%) and optional SSCL (2.5%) for invoicing.
+ * Supports both tax-exclusive and tax-inclusive calculations.
+ *
+ * @example
+ * ```ts
+ * calculateTax({ amount: 10000, includeSSCL: true });
+ * // => { baseAmount: 10000, ssclAmount: 250, vatAmount: 1845, totalAmount: 12095 }
+ * ```
+ */
+declare function calculateTax(options: TaxCalculationOptions): TaxBreakdown;
+
+type HolidayCategory = 'public' | 'bank' | 'mercantile';
+interface Holiday {
+    date: string;
+    name: string;
+    categories: HolidayCategory[];
+}
+/**
+ * Standard Sri Lankan Statutory & Public/Bank/Mercantile Holidays.
+ * Covers official annual holidays recognized by CBSL and the Ministry of Public Administration.
+ */
+declare const SRI_LANKAN_HOLIDAYS: Holiday[];
+interface WorkingDaysOptions {
+    /** Check against Bank holidays (Default: true) */
+    bankHolidays?: boolean;
+    /** Check against Mercantile holidays (for private sector) (Default: false) */
+    mercantileOnly?: boolean;
+    /** Treat Saturdays as working days (Default: false) */
+    saturdayWorking?: boolean;
+}
+/**
+ * Check if a date is a weekend.
+ */
+declare function isWeekend(date: Date, saturdayWorking?: boolean): boolean;
+/**
+ * Returns holiday details if the given date is a Sri Lankan statutory holiday.
+ */
+declare function getHoliday(date: Date): Holiday | undefined;
+/**
+ * Check if a given date is a Sri Lankan working day.
+ *
+ * @example
+ * ```ts
+ * isWorkingDay(new Date('2025-04-14')); // => false (New Year Day)
+ * ```
+ */
+declare function isWorkingDay(date: Date, options?: WorkingDaysOptions): boolean;
+/**
+ * Calculates the number of working days between two dates (inclusive),
+ * excluding weekends and statutory Sri Lankan holidays.
+ *
+ * @example
+ * ```ts
+ * getWorkingDays(new Date('2025-04-01'), new Date('2025-04-30'));
+ * ```
+ */
+declare function getWorkingDays(startDate: Date, endDate: Date, options?: WorkingDaysOptions): number;
+/**
+ * Adds a specific number of working days to a given start date.
+ * Useful for calculating invoice payment due dates or credit terms.
+ *
+ * @example
+ * ```ts
+ * // Calculate due date after 10 working days:
+ * const dueDate = addWorkingDays(new Date(), 10);
+ * ```
+ */
+declare function addWorkingDays(startDate: Date, daysToAdd: number, options?: WorkingDaysOptions): Date;
+
+export { type Bank, type Branch, type FormatLKROptions, type Holiday, type HolidayCategory, SRI_LANKAN_BANKS, SRI_LANKAN_BRANCHES, SRI_LANKAN_HOLIDAYS, type TaxBreakdown, type TaxCalculationOptions, type TinValidationResult, type ToWordsOptions, type VatValidationResult, type WorkingDaysOptions, addWorkingDays, calculateTax, findBank, findBranch, formatLKR, getBanks, getBranches, getHoliday, getWorkingDays, isWeekend, isWorkingDay, lkrToWords, validateTIN, validateVAT };