finprim 0.1.0 → 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Oluwatosin Adelaja
+
+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

@@ -0,0 +1,276 @@
+# finprim
+
+**Financial primitives for modern TypeScript applications.**
+
+A unified, production-grade TypeScript library for validating and formatting financial data. No more stitching together five different packages. No more custom glue code. Just clean, typed, fintech-first utilities that work anywhere TypeScript runs.
+
+---
+
+## Why finprim?
+
+Every fintech team builds this internally. Sort code validation here, an IBAN check there, a custom currency formatter somewhere else. It's fragmented, inconsistent, and expensive to maintain.
+
+finprim is the open source version of what your team has already written three times.
+
+---
+
+## Features
+
+- ✅ IBAN validation and formatting (80+ countries, with country code)
+- ✅ UK sort code and account number validation
+- ✅ BIC/SWIFT validation
+- ✅ Card number validation (Luhn, network detection, formatting)
+- ✅ EU VAT number format validation (member states)
+- ✅ US ABA routing number validation
+- ✅ Loan/EMI calculation and schedule
+- ✅ Format-only helpers (IBAN, sort code, account number) for display
+- ✅ Currency validation and formatting with locale support
+- ✅ Branded types for compile-time correctness
+- ✅ Zod schemas out of the box
+- ✅ Optional React hooks for form inputs
+- ✅ Optional NestJS validation pipes
+- ✅ Zero dependencies at the core
+- ✅ Tree-shakeable ESM and CJS builds
+- ✅ Fully typed
+
+---
+
+## Installation
+
+```bash
+npm install finprim
+```
+
+For Zod integration:
+
+```bash
+npm install finprim zod
+```
+
+---
+
+## Usage
+
+### Validation
+
+```ts
+import {
+  validateIBAN,
+  validateUKSortCode,
+  validateUKAccountNumber,
+  validateBIC,
+  validateCardNumber,
+  validateCurrencyCode,
+  validateEUVAT,
+  validateUSRoutingNumber,
+  formatIBAN,
+  formatSortCode,
+  formatUKAccountNumber,
+  calculateEMI,
+  getLoanSchedule,
+} from 'finprim'
+
+const iban = validateIBAN('GB29NWBK60161331926819')
+// { valid: true, value: 'GB29NWBK60161331926819', formatted: 'GB29 NWBK 6016 1331 9268 19', countryCode: 'GB' }
+
+const sortCode = validateUKSortCode('60-16-13')
+// { valid: true, value: '601613', formatted: '60-16-13' }
+
+const account = validateUKAccountNumber('31926819')
+// { valid: true, value: '31926819', formatted: '3192 6819' }
+
+const card = validateCardNumber('4532015112830366')
+// { valid: true, value: '...', formatted: '4532 0151 1283 0366', network: 'Visa', last4: '0366' }
+
+const vat = validateEUVAT('DE123456789')
+// { valid: true, value: 'DE123456789', formatted: 'DE 123456789', countryCode: 'DE' }
+
+const routing = validateUSRoutingNumber('021000021')
+// { valid: true, value: '021000021', formatted: '021000021' }
+
+formatIBAN('GB29NWBK60161331926819')        // 'GB29 NWBK 6016 1331 9268 19'
+formatSortCode('601613')                    // '60-16-13'
+formatUKAccountNumber('31926819')           // '3192 6819'
+
+const emi = calculateEMI(100_000, 10, 12)   // monthly payment
+const schedule = getLoanSchedule(100_000, 10, 12)  // array of { month, payment, principal, interest, balance }
+```
+
+### Currency Formatting
+
+```ts
+import { formatCurrency, parseMoney } from 'finprim'
+
+formatCurrency(1000.5, 'GBP', 'en-GB')  // '£1,000.50'
+formatCurrency(1000.5, 'EUR', 'de-DE')  // '1.000,50 €'
+formatCurrency(1000.5, 'USD', 'en-US')  // '$1,000.50'
+
+parseMoney('£1,000.50')  // { valid: true, amount: 1000.50, currency: 'GBP', formatted: '£1,000.50' }
+```
+
+### Branded Types
+
+```ts
+import type { IBAN, SortCode, AccountNumber, CurrencyCode } from 'finprim'
+
+// Invalid data cannot be passed where valid data is expected
+function processPayment(iban: IBAN, amount: number) { ... }
+
+// This forces validation before use
+const iban = validateIBAN(input)
+if (iban.valid) {
+  processPayment(iban.value, 100) // iban.value is typed as IBAN
+}
+```
+
+### Zod Schemas
+
+```ts
+import { ibanSchema, sortCodeSchema, accountNumberSchema, currencySchema, vatSchema, routingNumberSchema } from 'finprim/zod'
+
+const PaymentSchema = z.object({
+  iban: ibanSchema,
+  sortCode: sortCodeSchema,
+  accountNumber: accountNumberSchema,
+  amount: z.number().positive(),
+  currency: currencySchema,
+})
+```
+
+### React Hooks
+
+```ts
+import { useIBANInput, useCardNumberInput, useCurrencyInput } from 'finprim/react'
+
+function PaymentForm() {
+  const iban = useIBANInput()
+  const card = useCardNumberInput()
+  const { rawValue, formatted, onChange } = useCurrencyInput('GBP', 'en-GB')
+
+  return (
+    <>
+      <input value={iban.value} onChange={iban.onChange} aria-invalid={iban.valid === false} />
+      <input value={card.formatted} onChange={card.onChange} aria-invalid={card.valid === false} />
+      <input value={formatted} onChange={onChange} />
+    </>
+  )
+}
+```
+
+### NestJS Pipes
+
+```ts
+import { IbanValidationPipe, SortCodeValidationPipe, createValidationPipe } from 'finprim/nest'
+import { validateIBAN } from 'finprim'
+
+@Get('iban/:iban')
+findByIban(@Param('iban', IbanValidationPipe) iban: string) {
+  return this.service.findByIban(iban)
+}
+
+const MyPipe = createValidationPipe(validateIBAN)
+```
+
+---
+
+## API Reference
+
+### Validation
+
+| Function | Input | Returns |
+|----------|-------|---------|
+| `validateIBAN(input)` | `string` | `IBANValidationResult` (includes `countryCode` when valid) |
+| `validateUKSortCode(input)` | `string` | `ValidationResult<SortCode>` |
+| `validateUKAccountNumber(input)` | `string` | `ValidationResult<AccountNumber>` |
+| `validateCurrencyCode(input)` | `string` | `ValidationResult<CurrencyCode>` |
+| `validateBIC(input)` | `string` | `ValidationResult<BIC>` |
+| `validateCardNumber(input)` | `string` | `CardValidationResult` (includes `network`, `last4` when valid) |
+| `validateEUVAT(input)` | `string` | `VATValidationResult` (includes `countryCode` when valid) |
+| `validateUSRoutingNumber(input)` | `string` | `ValidationResult<RoutingNumber>` |
+
+### Formatting & display
+
+| Function | Input | Returns |
+|----------|-------|---------|
+| `formatIBAN(input)` | `string` | `string` (space-separated, no validation) |
+| `formatSortCode(input)` | `string` | `string` (XX-XX-XX) |
+| `formatUKAccountNumber(input)` | `string` | `string` (XXXX XXXX) |
+
+### Loan
+
+| Function | Input | Returns |
+|----------|-------|---------|
+| `calculateEMI(principal, annualRatePercent, months)` | `number`, `number`, `number` | `number` |
+| `getLoanSchedule(principal, annualRatePercent, months)` | `number`, `number`, `number` | `LoanScheduleEntry[]` |
+
+### Formatting (currency)
+
+| Function | Input | Returns |
+|----------|-------|---------|
+| `formatCurrency(amount, currency, locale?)` | `number`, `SupportedCurrency`, `string?` | `string` |
+| `parseMoney(input)` | `string` | `MoneyResult` |
+
+Validation results include a `formatted` string when valid (e.g. IBAN and card numbers are space-separated).
+
+---
+
+## Packages
+
+| Import path | What it contains | Extra dependency |
+|---|---|---|
+| `finprim` | Core validators and formatters | none |
+| `finprim/zod` | Zod schemas | `zod` |
+| `finprim/react` | React hooks | `react` |
+| `finprim/nest` | NestJS validation pipes | `@nestjs/common` |
+
+---
+
+## Tech Stack
+
+- TypeScript
+- tsup (build)
+- Vitest (testing)
+- React (optional hooks subpath)
+- Zod (optional schema subpath)
+
+---
+
+## Roadmap
+
+- [x] SWIFT / BIC validation
+- [x] Luhn algorithm for card number validation
+- [x] EU VAT number validation
+- [x] NestJS pipe integration
+- [x] US routing number validation
+- [x] Loan/EMI calculation
+- [x] Format-only helpers
+- [ ] More locale coverage
+
+---
+
+## Contributing
+
+Contributions are welcome. Please open an issue before submitting a pull request so we can discuss the change.
+
+```bash
+git clone https://github.com/YOUR_USERNAME/finprim
+cd finprim
+npm install
+npm test
+npm run dev
+```
+
+---
+
+## Security
+
+- **Input length**: All string validators reject input longer than 256 characters to limit memory and CPU use.
+- **Type checking**: Validators require non-empty strings; numeric helpers (e.g. loan/currency) require finite numbers and sane bounds.
+- **No sensitive logging**: The library does not log or persist input; use it in a way that avoids logging full card or account numbers.
+- **Format helpers**: `formatIBAN`, `formatSortCode`, and `formatUKAccountNumber` cap input length and accept only strings to avoid abuse.
+
+---
+
+## License
+
+MIT

package/dist/card-D2-7wbam.d.mts

@@ -0,0 +1,57 @@
+declare const __brand: unique symbol;
+type Brand<T, B> = T & {
+    readonly [__brand]: B;
+};
+type IBAN = Brand<string, 'IBAN'>;
+type SortCode = Brand<string, 'SortCode'>;
+type AccountNumber = Brand<string, 'AccountNumber'>;
+type CurrencyCode = Brand<string, 'CurrencyCode'>;
+type BIC = Brand<string, 'BIC'>;
+type CardNumber = Brand<string, 'CardNumber'>;
+type VATNumber = Brand<string, 'VATNumber'>;
+type RoutingNumber = Brand<string, 'RoutingNumber'>;
+type SupportedCurrency = 'GBP' | 'EUR' | 'USD' | 'JPY' | 'CHF' | 'CAD' | 'AUD' | 'NZD';
+type ValidationSuccess<T> = {
+    valid: true;
+    value: T;
+    formatted: string;
+};
+type ValidationFailure = {
+    valid: false;
+    error: string;
+};
+type ValidationResult<T> = ValidationSuccess<T> | ValidationFailure;
+declare function isValidationSuccess<T>(result: ValidationResult<T>): result is ValidationSuccess<T>;
+declare function isValidationFailure<T>(result: ValidationResult<T>): result is ValidationFailure;
+type IBANValidationSuccess = ValidationSuccess<IBAN> & {
+    countryCode: string;
+};
+type IBANValidationResult = IBANValidationSuccess | ValidationFailure;
+type MoneyResult = {
+    valid: true;
+    amount: number;
+    currency: SupportedCurrency;
+    formatted: string;
+} | {
+    valid: false;
+    error: string;
+};
+type VATValidationSuccess = ValidationSuccess<VATNumber> & {
+    countryCode: string;
+};
+type VATValidationResult = VATValidationSuccess | ValidationFailure;
+
+type CardNetwork = 'Visa' | 'Mastercard' | 'Amex' | 'Discover' | 'Unknown';
+type CardValidationResult = {
+    valid: true;
+    value: CardNumber;
+    formatted: string;
+    network: CardNetwork;
+    last4: string;
+} | {
+    valid: false;
+    error: string;
+};
+declare function validateCardNumber(input: string): CardValidationResult;
+
+export { type AccountNumber as A, type BIC as B, type CurrencyCode as C, type IBANValidationResult as I, type MoneyResult as M, type RoutingNumber as R, type SortCode as S, type ValidationResult as V, type SupportedCurrency as a, type VATValidationResult as b, type CardNetwork as c, type CardNumber as d, type CardValidationResult as e, type IBAN as f, type IBANValidationSuccess as g, type VATNumber as h, type VATValidationSuccess as i, type ValidationFailure as j, type ValidationSuccess as k, isValidationFailure as l, isValidationSuccess as m, validateCardNumber as v };

package/dist/card-D2-7wbam.d.ts

@@ -0,0 +1,57 @@
+declare const __brand: unique symbol;
+type Brand<T, B> = T & {
+    readonly [__brand]: B;
+};
+type IBAN = Brand<string, 'IBAN'>;
+type SortCode = Brand<string, 'SortCode'>;
+type AccountNumber = Brand<string, 'AccountNumber'>;
+type CurrencyCode = Brand<string, 'CurrencyCode'>;
+type BIC = Brand<string, 'BIC'>;
+type CardNumber = Brand<string, 'CardNumber'>;
+type VATNumber = Brand<string, 'VATNumber'>;
+type RoutingNumber = Brand<string, 'RoutingNumber'>;
+type SupportedCurrency = 'GBP' | 'EUR' | 'USD' | 'JPY' | 'CHF' | 'CAD' | 'AUD' | 'NZD';
+type ValidationSuccess<T> = {
+    valid: true;
+    value: T;
+    formatted: string;
+};
+type ValidationFailure = {
+    valid: false;
+    error: string;
+};
+type ValidationResult<T> = ValidationSuccess<T> | ValidationFailure;
+declare function isValidationSuccess<T>(result: ValidationResult<T>): result is ValidationSuccess<T>;
+declare function isValidationFailure<T>(result: ValidationResult<T>): result is ValidationFailure;
+type IBANValidationSuccess = ValidationSuccess<IBAN> & {
+    countryCode: string;
+};
+type IBANValidationResult = IBANValidationSuccess | ValidationFailure;
+type MoneyResult = {
+    valid: true;
+    amount: number;
+    currency: SupportedCurrency;
+    formatted: string;
+} | {
+    valid: false;
+    error: string;
+};
+type VATValidationSuccess = ValidationSuccess<VATNumber> & {
+    countryCode: string;
+};
+type VATValidationResult = VATValidationSuccess | ValidationFailure;
+
+type CardNetwork = 'Visa' | 'Mastercard' | 'Amex' | 'Discover' | 'Unknown';
+type CardValidationResult = {
+    valid: true;
+    value: CardNumber;
+    formatted: string;
+    network: CardNetwork;
+    last4: string;
+} | {
+    valid: false;
+    error: string;
+};
+declare function validateCardNumber(input: string): CardValidationResult;
+
+export { type AccountNumber as A, type BIC as B, type CurrencyCode as C, type IBANValidationResult as I, type MoneyResult as M, type RoutingNumber as R, type SortCode as S, type ValidationResult as V, type SupportedCurrency as a, type VATValidationResult as b, type CardNetwork as c, type CardNumber as d, type CardValidationResult as e, type IBAN as f, type IBANValidationSuccess as g, type VATNumber as h, type VATValidationSuccess as i, type ValidationFailure as j, type ValidationSuccess as k, isValidationFailure as l, isValidationSuccess as m, validateCardNumber as v };

package/dist/index.d.mts

@@ -1,127 +1,33 @@
-import { V as ValidationResult, I as IBAN, A as AccountNumber, S as SortCode, a as SupportedCurrency, M as MoneyResult, C as CurrencyCode, B as BIC, b as CardNumber } from './types-KG-eFvWt.mjs';
-export { c as ValidationFailure, d as ValidationSuccess } from './types-KG-eFvWt.mjs';
+import { I as IBANValidationResult, V as ValidationResult, A as AccountNumber, S as SortCode, a as SupportedCurrency, M as MoneyResult, C as CurrencyCode, B as BIC, b as VATValidationResult, R as RoutingNumber } from './card-D2-7wbam.mjs';
+export { c as CardNetwork, d as CardNumber, e as CardValidationResult, f as IBAN, g as IBANValidationSuccess, h as VATNumber, i as VATValidationSuccess, j as ValidationFailure, k as ValidationSuccess, l as isValidationFailure, m as isValidationSuccess, v as validateCardNumber } from './card-D2-7wbam.mjs';
 
-/**
- * Validates an IBAN string.
- * Accepts IBANs with or without spaces.
- * Validates: country code, expected length, characters, and mod97 checksum.
- *
- * @example
- * validateIBAN('GB29NWBK60161331926819')
- * // { valid: true, value: 'GB29NWBK60161331926819', formatted: 'GB29 NWBK 6016 1331 9268 19' }
- *
- * validateIBAN('GB00NWBK60161331926819')
- * // { valid: false, error: 'IBAN checksum is invalid' }
- */
-declare function validateIBAN(input: string): ValidationResult<IBAN>;
+declare function formatIBAN(input: string): string;
+declare function validateIBAN(input: string): IBANValidationResult;
 
-/**
- * Validates a UK sort code.
- * Accepts formats: 60-16-13, 601613, 60 16 13
- *
- * @example
- * validateUKSortCode('60-16-13')
- * // { valid: true, value: '601613', formatted: '60-16-13' }
- *
- * validateUKSortCode('999')
- * // { valid: false, error: 'Sort code must be 6 digits...' }
- */
+declare function formatSortCode(input: string): string;
+declare function formatUKAccountNumber(input: string): string;
 declare function validateUKSortCode(input: string): ValidationResult<SortCode>;
-/**
- * Validates a UK bank account number.
- * Must be exactly 8 digits.
- *
- * @example
- * validateUKAccountNumber('31926819')
- * // { valid: true, value: '31926819', formatted: '3192 6819' }
- *
- * validateUKAccountNumber('1234')
- * // { valid: false, error: 'UK account number must be exactly 8 digits' }
- */
 declare function validateUKAccountNumber(input: string): ValidationResult<AccountNumber>;
 
 declare const SUPPORTED_CURRENCIES: SupportedCurrency[];
-/**
- * Validates a currency code against supported ISO 4217 codes.
- *
- * @example
- * validateCurrencyCode('GBP')
- * // { valid: true, value: 'GBP', formatted: 'GBP' }
- *
- * validateCurrencyCode('XYZ')
- * // { valid: false, error: 'Unsupported currency code: XYZ' }
- */
 declare function validateCurrencyCode(input: string): ValidationResult<CurrencyCode>;
-/**
- * Formats a number as a locale-aware currency string.
- * Uses the built-in Intl.NumberFormat API — zero dependencies.
- *
- * @example
- * formatCurrency(1000.5, 'GBP')          // '£1,000.50'
- * formatCurrency(1000.5, 'EUR', 'de-DE') // '1.000,50 €'
- * formatCurrency(1000.5, 'USD', 'en-US') // '$1,000.50'
- * formatCurrency(1000,   'JPY')          // '¥1,000'
- */
 declare function formatCurrency(amount: number, currency: SupportedCurrency, locale?: string): string;
-/**
- * Parses a formatted currency string back into a structured money object.
- * Detects the currency from the symbol prefix.
- *
- * @example
- * parseMoney('£1,000.50')
- * // { valid: true, amount: 1000.5, currency: 'GBP', formatted: '£1,000.50' }
- *
- * parseMoney('not money')
- * // { valid: false, error: 'Could not detect currency from input' }
- */
 declare function parseMoney(input: string): MoneyResult;
 
-/**
- * Validates a BIC (Bank Identifier Code) / SWIFT code.
- * Accepts both 8-character and 11-character BIC codes.
- *
- * Format: AAAABBCCXXX
- * - AAAA = Bank code (4 letters)
- * - BB   = Country code (2 letters, ISO 3166-1)
- * - CC   = Location code (2 alphanumeric)
- * - XXX  = Branch code (3 alphanumeric, optional — 'XXX' means head office)
- *
- * @example
- * validateBIC('NWBKGB2L')
- * // { valid: true, value: 'NWBKGB2L', formatted: 'NWBKGB2L' }
- *
- * validateBIC('DEUTDEDB')
- * // { valid: true, value: 'DEUTDEDB', formatted: 'DEUTDEDB' }
- */
 declare function validateBIC(input: string): ValidationResult<BIC>;
 
-type CardNetwork = 'Visa' | 'Mastercard' | 'Amex' | 'Discover' | 'Unknown';
-type CardValidationResult = {
-    valid: true;
-    value: CardNumber;
-    formatted: string;
-    network: CardNetwork;
-    last4: string;
-} | {
-    valid: false;
-    error: string;
+declare function validateEUVAT(input: string): VATValidationResult;
+
+declare function validateUSRoutingNumber(input: string): ValidationResult<RoutingNumber>;
+
+type LoanScheduleEntry = {
+    month: number;
+    payment: number;
+    principal: number;
+    interest: number;
+    balance: number;
 };
-/**
- * Validates a card number using the Luhn algorithm.
- * Accepts digits with or without spaces and hyphens.
- *
- * The Luhn algorithm:
- * 1. Double every second digit from the right
- * 2. If doubling produces a number > 9, subtract 9
- * 3. Sum all digits — result must be divisible by 10
- *
- * @example
- * validateCardNumber('4532015112830366')
- * // { valid: true, value: '...', formatted: '4532 0151 1283 0366', network: 'Visa', last4: '0366' }
- *
- * validateCardNumber('1234567890123456')
- * // { valid: false, error: 'Card number failed Luhn check' }
- */
-declare function validateCardNumber(input: string): CardValidationResult;
+declare function calculateEMI(principal: number, annualRatePercent: number, months: number): number;
+declare function getLoanSchedule(principal: number, annualRatePercent: number, months: number): LoanScheduleEntry[];
 
-export { AccountNumber, BIC, type CardNetwork, CardNumber, type CardValidationResult, CurrencyCode, IBAN, MoneyResult, SUPPORTED_CURRENCIES, SortCode, SupportedCurrency, ValidationResult, formatCurrency, parseMoney, validateBIC, validateCardNumber, validateCurrencyCode, validateIBAN, validateUKAccountNumber, validateUKSortCode };
+export { AccountNumber, BIC, CurrencyCode, IBANValidationResult, type LoanScheduleEntry, MoneyResult, RoutingNumber, SUPPORTED_CURRENCIES, SortCode, SupportedCurrency, VATValidationResult, ValidationResult, calculateEMI, formatCurrency, formatIBAN, formatSortCode, formatUKAccountNumber, getLoanSchedule, parseMoney, validateBIC, validateCurrencyCode, validateEUVAT, validateIBAN, validateUKAccountNumber, validateUKSortCode, validateUSRoutingNumber };