feat: EU VAT, US routing, loan/EMI, format helpers, NestJS pipes; security: input guards and bounds

Made-with: Cursor

Author: tintolee

README.md

@@ -20,10 +20,15 @@ finprim is the open source version of what your team has already written three t
 - ✅ 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
@@ -56,6 +61,13 @@ import {
   validateBIC,
   validateCardNumber,
   validateCurrencyCode,
+  validateEUVAT,
+  validateUSRoutingNumber,
+  formatIBAN,
+  formatSortCode,
+  formatUKAccountNumber,
+  calculateEMI,
+  getLoanSchedule,
 } from 'finprim'
 
 const iban = validateIBAN('GB29NWBK60161331926819')
@@ -69,6 +81,19 @@ const account = validateUKAccountNumber('31926819')
 
 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
@@ -101,7 +126,7 @@ if (iban.valid) {
 ### Zod Schemas
 
 ```ts
-import { ibanSchema, sortCodeSchema, accountNumberSchema, currencySchema } from 'finprim/zod'
+import { ibanSchema, sortCodeSchema, accountNumberSchema, currencySchema, vatSchema, routingNumberSchema } from 'finprim/zod'
 
 const PaymentSchema = z.object({
   iban: ibanSchema,
@@ -132,6 +157,20 @@ function PaymentForm() {
 }
 ```
 
+### 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
@@ -146,8 +185,25 @@ function PaymentForm() {
 | `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
+### 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 |
 |----------|-------|---------|
@@ -165,6 +221,7 @@ Validation results include a `formatted` string when valid (e.g. IBAN and card n
 | `finprim` | Core validators and formatters | none |
 | `finprim/zod` | Zod schemas | `zod` |
 | `finprim/react` | React hooks | `react` |
+| `finprim/nest` | NestJS validation pipes | `@nestjs/common` |
 
 ---
 
@@ -182,8 +239,11 @@ Validation results include a `formatted` string when valid (e.g. IBAN and card n
 
 - [x] SWIFT / BIC validation
 - [x] Luhn algorithm for card number validation
-- [ ] EU VAT number validation
-- [ ] NestJS pipe integration
+- [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
 
 ---
@@ -202,6 +262,15 @@ 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

chatbot/cli.ts

@@ -1,23 +1,22 @@
-import * as readline from 'readline'
-import path from "path";
+import * as readline from 'node:readline'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import * as dotenv from 'dotenv'
 import OpenAI from 'openai'
-import { validateIBAN } from 'finprim'
-import { validateUKSortCode, validateUKAccountNumber } from 'finprim'
-import { fileURLToPath } from "url";
+import { validateIBAN, validateUKSortCode, validateUKAccountNumber } from 'finprim'
 
-import * as dotenv from "dotenv";
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = path.dirname(__filename)
 
-dotenv.config({
-  path: path.join(__dirname, ".env"),
-});
+dotenv.config({ path: path.join(__dirname, '.env') })
 
-console.log('API Key:', process.env.OPENAI_API_KEY)
+const apiKey = process.env.OPENAI_API_KEY
+if (!apiKey) {
+  console.error('Missing OPENAI_API_KEY. Set it in .env or the environment.')
+  process.exit(1)
+}
 
-const openai = new OpenAI({
-  apiKey: process.env.OPENAI_API_KEY
-})
+const openai = new OpenAI({ apiKey })
 
 const tools: OpenAI.Tool[] = [
   {

demo/src/App.tsx

@@ -1,9 +1,9 @@
-import { Header } from './components/Header.tsx'
-import { Footer } from './components/Footer.tsx'
-import { IBANSection } from './components/IBANSection.tsx'
-import { UKPaymentSection } from './components/UKPaymentSection.tsx'
-import { CreditCardSection } from './components/CreditCardSection.tsx'
-import { CurrencySection } from './components/CurrencySection.tsx'
+import { Header } from './components/Header'
+import { Footer } from './components/Footer'
+import { IBANSection } from './components/IBANSection'
+import { UKPaymentSection } from './components/UKPaymentSection'
+import { CreditCardSection } from './components/CreditCardSection'
+import { CurrencySection } from './components/CurrencySection'
 
 export default function App() {
   return (

demo/src/components/CreditCardSection.tsx

@@ -1,7 +1,7 @@
 import { useState, useCallback } from 'react'
 import { useCreditCardInput } from 'finprim/react'
 import type { CardIssuer } from 'finprim'
-import { FieldGroup } from './FieldGroup.tsx'
+import { FieldGroup } from './FieldGroup'
 
 function issuerLabel(issuer: CardIssuer): string {
   switch (issuer) {

demo/src/components/CurrencySection.tsx

@@ -1,7 +1,7 @@
 import { useState } from 'react'
 import { useCurrencyInput } from 'finprim/react'
 import type { SupportedCurrency } from 'finprim'
-import { FieldGroup } from './FieldGroup.tsx'
+import { FieldGroup } from './FieldGroup'
 
 const CURRENCIES: SupportedCurrency[] = ['GBP', 'EUR', 'USD', 'JPY', 'CHF', 'CAD', 'AUD', 'NZD']
 

demo/src/components/IBANSection.tsx

@@ -1,6 +1,6 @@
 import { useState, useCallback } from 'react'
 import { useIBANInput } from 'finprim/react'
-import { FieldGroup } from './FieldGroup.tsx'
+import { FieldGroup } from './FieldGroup'
 
 export function IBANSection() {
   const { formatted, valid, error, onChange: hookChange } = useIBANInput()

demo/src/components/UKPaymentSection.tsx

@@ -1,6 +1,6 @@
 import { useState, useCallback } from 'react'
 import { useSortCodeInput, useAccountNumberInput } from 'finprim/react'
-import { FieldGroup } from './FieldGroup.tsx'
+import { FieldGroup } from './FieldGroup'
 
 function fakeEvent(value: string): React.ChangeEvent<HTMLInputElement> {
   return { target: { value } } as React.ChangeEvent<HTMLInputElement>

demo/src/main.tsx

@@ -1,7 +1,7 @@
 import { StrictMode } from 'react'
 import { createRoot } from 'react-dom/client'
 import './index.css'
-import App from './App.tsx'
+import App from './App'
 
 createRoot(document.getElementById('root')!).render(
   <StrictMode>

example/web/src/App.tsx

@@ -44,8 +44,9 @@ const EXAMPLES: FinprimExample[] = [
 ];
 
 export default function App() {
-  const [activeId, setActiveId] = useState<string>(EXAMPLES[0].id);
-  const activeExample = EXAMPLES.find((ex) => ex.id === activeId);
+  const [activeId, setActiveId] = useState<string>(EXAMPLES[0].id)
+  const activeExample = EXAMPLES.find((ex) => ex.id === activeId)
+  const ActiveComponent = activeExample?.component
 
   return (
     <div className="flex min-h-screen bg-gray-50 text-gray-900">
@@ -74,7 +75,7 @@ export default function App() {
         </header>
 
         <ExampleCard>
-          {activeExample ? <activeExample.component /> : <p>Select an example</p>}
+          {ActiveComponent ? <ActiveComponent /> : <p>Select an example</p>}
         </ExampleCard>
       </main>
     </div>

example/web/src/LoanCalculator.tsx

@@ -1,66 +1,63 @@
-import { useState } from 'react';
-// import { calculateEMI } from 'finprim'; // Uncomment when ready
+import { useState } from 'react'
+import { calculateEMI } from 'finprim'
 
-export const LoanCalculator = () => {
-  const [principal, setPrincipal] = useState(10000);
-  const [rate, setRate] = useState(5);
-  const [months, setMonths] = useState(12);
-//   const [result, setResult] = useState<number | null>(null);
+export function LoanCalculator() {
+  const [principal, setPrincipal] = useState(10000)
+  const [rate, setRate] = useState(5)
+  const [months, setMonths] = useState(12)
+  const [result, setResult] = useState<number | null>(null)
 
   const handleCalculate = () => {
-    // TODO: Replace with finprim logic
-    // const emi = calculateEMI(principal, rate, months);
-    // setResult(emi);
-    alert("finprim logic goes here!");
-  };
+    const emi = calculateEMI(principal, rate, months)
+    setResult(emi)
+  }
 
   return (
     <div className="flex max-w-md flex-col gap-5">
       <div className="flex flex-col gap-2">
         <label className="text-sm font-semibold text-gray-700">Principal Amount ($)</label>
-        <input 
-          type="number" 
-          value={principal} 
-          onChange={(e) => setPrincipal(Number(e.target.value))} 
-          className="rounded-lg border border-gray-300 p-2.5 focus:border-indigo-500 focus:outline-none focus:ring-1 focus:ring-indigo-500" 
+        <input
+          type="number"
+          value={principal}
+          onChange={(e) => setPrincipal(Number(e.target.value))}
+          className="rounded-lg border border-gray-300 p-2.5 focus:border-indigo-500 focus:outline-none focus:ring-1 focus:ring-indigo-500"
         />
       </div>
 
       <div className="flex gap-4">
         <div className="flex flex-col gap-2 flex-1">
           <label className="text-sm font-semibold text-gray-700">Rate (%)</label>
-          <input 
-            type="number" 
-            value={rate} 
-            onChange={(e) => setRate(Number(e.target.value))} 
-            className="rounded-lg border border-gray-300 p-2.5 focus:border-indigo-500 focus:outline-none focus:ring-1 focus:ring-indigo-500" 
+          <input
+            type="number"
+            value={rate}
+            onChange={(e) => setRate(Number(e.target.value))}
+            className="rounded-lg border border-gray-300 p-2.5 focus:border-indigo-500 focus:outline-none focus:ring-1 focus:ring-indigo-500"
           />
         </div>
         <div className="flex flex-col gap-2 flex-1">
           <label className="text-sm font-semibold text-gray-700">Months</label>
-          <input 
-            type="number" 
-            value={months} 
-            onChange={(e) => setMonths(Number(e.target.value))} 
-            className="rounded-lg border border-gray-300 p-2.5 focus:border-indigo-500 focus:outline-none focus:ring-1 focus:ring-indigo-500" 
+          <input
+            type="number"
+            value={months}
+            onChange={(e) => setMonths(Number(e.target.value))}
+            className="rounded-lg border border-gray-300 p-2.5 focus:border-indigo-500 focus:outline-none focus:ring-1 focus:ring-indigo-500"
           />
         </div>
       </div>
 
-      <button 
-        onClick={handleCalculate} 
+      <button
+        onClick={handleCalculate}
         className="mt-2 rounded-lg bg-indigo-600 px-4 py-3 font-bold text-white transition-colors hover:bg-indigo-700"
       >
         Calculate Payment
       </button>
-      
-      {/* Result Card */}
+
       <div className="mt-4 rounded-xl border border-indigo-100 bg-indigo-50 p-6 text-center">
         <p className="text-sm font-medium text-indigo-800">Monthly Payment</p>
         <p className="mt-1 text-4xl font-black text-indigo-900">
-          {/* {result !== null ? `$${result.toFixed(2)}` : '$0.00'} */}
+          {result !== null ? `$${result.toFixed(2)}` : '$0.00'}
         </p>
       </div>
     </div>
-  );
-};
+  )
+}