tw-id-validator 1.0.5

package/README.md

@@ -0,0 +1,140 @@
+# tw-id-validator
+
+> 台灣證件驗證函式庫。支援身分證、統一證號、統一編號、自然人憑證、電子發票條碼。
+
+## Install
+
+```bash
+npm install tw-id-validator
+```
+
+Zero runtime dependencies. Pure TypeScript.
+
+## Quick Start
+
+```typescript
+import {
+  isValidNationalId,
+  parseNationalId,
+  generateNationalId,
+  isValidUnifiedCert,
+  isValidBAN,
+  isValidCDC,
+  isValidMobileBarcode,
+  isValidDonateCode,
+} from 'tw-id-validator'
+```
+
+## 身分證字號 (National ID)
+
+```typescript
+// 驗證
+isValidNationalId('A123456789')  // → true
+isValidNationalId('A123456788')  // → false
+
+// 解析
+parseNationalId('A123456789')
+// → {
+//     city: '台北市',
+//     cityCode: 'A',
+//     gender: 'male',
+//     sequence: '2345678',
+//     checkDigit: '9'
+//   }
+
+// 產生測試用身分證
+generateNationalId('A', 'male')   // → 'A1xxxxxxx' (valid)
+generateNationalId('B', 'female') // → 'B2xxxxxxx' (valid)
+```
+
+## 統一證號 (Unified Certificate)
+
+```typescript
+// 驗證（支援新舊版）
+isValidUnifiedCert('AB23456789')  // → true (舊版)
+isValidUnifiedCert('A800000014')  // → true (新版，外籍)
+isValidUnifiedCert('A900000007')  // → true (新版，大陸/港澳)
+
+// 解析
+parseUnifiedCert('AB23456789')
+// → { version: 'old', cityCode: 'A', category: 'B', sequence: '2345678', checkDigit: '9' }
+
+parseUnifiedCert('A800000014')
+// → { version: 'new', cityCode: 'A', category: '外籍/無國籍', sequence: '0000001', checkDigit: '4' }
+```
+
+## 統一編號 (Business Administration Number)
+
+```typescript
+isValidBAN('12345675')  // → true
+isValidBAN('12345678')  // → false
+
+parseBAN('12345675')
+// → { number: '12345675', hasSpecialRule: true }
+```
+
+## 自然人憑證 (Citizen Digital Certificate)
+
+```typescript
+isValidCDC('AB12345678901234')  // → true (2 letters + 14 digits)
+isValidCDC('A12345678901234')   // → false
+
+parseCDC('AB12345678901234')
+// → { prefix: 'AB', serial: '12345678901234' }
+```
+
+## 電子發票 (E-Invoice)
+
+### 手機條碼
+
+```typescript
+isValidMobileBarcode('/+.-++..')  // → true
+isValidMobileBarcode('/1234567')  // → true
+isValidMobileBarcode('/ABCDEFG')  // → true
+
+parseMobileBarcode('/+.-++..')
+// → { barcode: '/+.-++..' }
+```
+
+### 捐贈碼
+
+```typescript
+isValidDonateCode('123')      // → true (3-7 digits)
+isValidDonateCode('1234567')  // → true
+isValidDonateCode(123)        // → true (number input)
+
+parseDonateCode('123')
+// → { code: '123' }
+```
+
+## API Reference
+
+| Function | Input | Output | Description |
+|----------|-------|--------|-------------|
+| `isValidNationalId(id)` | `string` | `boolean` | 驗證身分證字號 |
+| `parseNationalId(id)` | `string` | `IdCardInfo \| null` | 解析身分證 |
+| `generateNationalId(city, gender)` | `string, string` | `string \| null` | 產生測試用身分證 |
+| `isValidUnifiedCert(id)` | `string` | `boolean` | 驗證統一證號（新舊版） |
+| `parseUnifiedCert(id)` | `string` | `UnifiedCertInfo \| null` | 解析統一證號 |
+| `isValidBAN(id)` | `string \| number` | `boolean` | 驗證統一編號 |
+| `parseBAN(id)` | `string \| number` | `BANInfo \| null` | 解析統一編號 |
+| `isValidCDC(id)` | `string` | `boolean` | 驗證自然人憑證 |
+| `parseCDC(id)` | `string` | `CDCInfo \| null` | 解析自然人憑證 |
+| `isValidMobileBarcode(code)` | `string` | `boolean` | 驗證發票手機條碼 |
+| `parseMobileBarcode(code)` | `string` | `MobileBarcodeInfo \| null` | 解析手機條碼 |
+| `isValidDonateCode(code)` | `string \| number` | `boolean` | 驗證發票捐贈碼 |
+| `parseDonateCode(code)` | `string \| number` | `DonateCodeInfo \| null` | 解析捐贈碼 |
+
+## Design
+
+| Feature | Why |
+|---------|-----|
+| Zero runtime deps | Pure TypeScript, no external packages |
+| Flat API | Each file handles one document type |
+| Pure functions | No side effects, independently testable |
+| TypeScript strict | Full type safety, no `any` |
+| 105 tests | Comprehensive coverage with ✅/❌ output |
+
+## License
+
+MIT

package/dist/ban.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Taiwan Business Administration Number (營利事業統一編號) validation.
+ *
+ * Format: 8 digits
+ * Checksum: weighted [1,2,1,2,1,2,4,1] → sum of digit products → mod 5 === 0
+ * Special rule: if 7th digit is 7 and (sum+1) % 5 === 0, also valid
+ */
+/**
+ * Validate a Taiwan Business Administration Number (統一編號).
+ * Supports both old (mod 10) and new (mod 5) rules.
+ */
+export declare function isValidBAN(id: string | number): boolean;
+export interface BANInfo {
+    number: string;
+    hasSpecialRule: boolean;
+}
+/**
+ * Parse a BAN number.
+ * Returns null if invalid.
+ */
+export declare function parseBAN(id: string | number): BANInfo | null;

package/dist/ban.js

@@ -0,0 +1,48 @@
+/**
+ * Taiwan Business Administration Number (營利事業統一編號) validation.
+ *
+ * Format: 8 digits
+ * Checksum: weighted [1,2,1,2,1,2,4,1] → sum of digit products → mod 5 === 0
+ * Special rule: if 7th digit is 7 and (sum+1) % 5 === 0, also valid
+ */
+const BAN_COEFFICIENTS = [1, 2, 1, 2, 1, 2, 4, 1];
+const BAN_RE = /^\d{8}$/;
+/**
+ * Validate a Taiwan Business Administration Number (統一編號).
+ * Supports both old (mod 10) and new (mod 5) rules.
+ */
+export function isValidBAN(id) {
+    const str = String(id);
+    if (!BAN_RE.test(str))
+        return false;
+    const digits = str.split('').map(Number);
+    const sum = digits.reduce((acc, d, i) => {
+        const product = d * BAN_COEFFICIENTS[i];
+        return acc + Math.floor(product / 10) + (product % 10);
+    }, 0);
+    // New rule: mod 5 === 0
+    if (sum % 5 === 0)
+        return true;
+    // Special case: 7th digit is 7 and (sum+1) % 5 === 0
+    if (digits[6] === 7 && (sum + 1) % 5 === 0)
+        return true;
+    return false;
+}
+/**
+ * Parse a BAN number.
+ * Returns null if invalid.
+ */
+export function parseBAN(id) {
+    const str = String(id);
+    if (!isValidBAN(str))
+        return null;
+    const digits = str.split('').map(Number);
+    const sum = digits.reduce((acc, d, i) => {
+        const product = d * BAN_COEFFICIENTS[i];
+        return acc + Math.floor(product / 10) + (product % 10);
+    }, 0);
+    return {
+        number: str,
+        hasSpecialRule: digits[6] === 7 && (sum + 1) % 5 === 0,
+    };
+}

package/dist/cdc.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Taiwan Citizen Digital Certificate Number (自然人憑證) validation.
+ *
+ * Format: 2 letters + 14 digits (16 chars total)
+ */
+/**
+ * Validate a Taiwan Citizen Digital Certificate Number (自然人憑證字號).
+ */
+export declare function isValidCDC(id: string): boolean;
+export interface CDCInfo {
+    prefix: string;
+    serial: string;
+}
+/**
+ * Parse a CDC number.
+ * Returns null if invalid.
+ */
+export declare function parseCDC(id: string): CDCInfo | null;

package/dist/cdc.js

@@ -0,0 +1,24 @@
+/**
+ * Taiwan Citizen Digital Certificate Number (自然人憑證) validation.
+ *
+ * Format: 2 letters + 14 digits (16 chars total)
+ */
+const CDC_RE = /^[A-Z]{2}\d{14}$/;
+/**
+ * Validate a Taiwan Citizen Digital Certificate Number (自然人憑證字號).
+ */
+export function isValidCDC(id) {
+    return CDC_RE.test(id);
+}
+/**
+ * Parse a CDC number.
+ * Returns null if invalid.
+ */
+export function parseCDC(id) {
+    if (!isValidCDC(id))
+        return null;
+    return {
+        prefix: id.slice(0, 2),
+        serial: id.slice(2),
+    };
+}

package/dist/id-card.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Taiwan National ID (身分證字號) and Unified Certificate (統一證號) validation.
+ *
+ * National ID format: 1 letter + 1 digit (1/2) + 8 digits
+ * Unified Certificate (old): 2 letters (2nd A-D) + 8 digits
+ * Unified Certificate (new): 1 letter + 8/9 + 7 digits + 1 check digit
+ */
+/**
+ * Validate a Taiwan national ID number (身分證字號).
+ * Format: 1 letter + 1 digit (1 or 2) + 8 digits
+ */
+export declare function isValidNationalId(id: string): boolean;
+export interface IdCardInfo {
+    city: string;
+    cityCode: string;
+    gender: 'male' | 'female';
+    sequence: string;
+    checkDigit: string;
+}
+/**
+ * Parse a national ID number into its components.
+ * Returns null if invalid.
+ */
+export declare function parseNationalId(id: string): IdCardInfo | null;
+/**
+ * Generate a test national ID number.
+ * @param city - City code (A-Z), defaults to 'A' (Taipei)
+ * @param gender - 'male' (1) or 'female' (2), defaults to 'male'
+ */
+export declare function generateNationalId(city?: string, gender?: 'male' | 'female'): string | null;
+/**
+ * Validate a Taiwan unified certificate number (統一證號).
+ * Supports both old and new formats.
+ */
+export declare function isValidUnifiedCert(id: string): boolean;
+export interface UnifiedCertInfo {
+    version: 'old' | 'new';
+    cityCode: string;
+    category: string;
+    sequence: string;
+    checkDigit: string;
+}
+/**
+ * Parse a unified certificate number.
+ * Returns null if invalid.
+ */
+export declare function parseUnifiedCert(id: string): UnifiedCertInfo | null;

package/dist/id-card.js

@@ -0,0 +1,155 @@
+/**
+ * Taiwan National ID (身分證字號) and Unified Certificate (統一證號) validation.
+ *
+ * National ID format: 1 letter + 1 digit (1/2) + 8 digits
+ * Unified Certificate (old): 2 letters (2nd A-D) + 8 digits
+ * Unified Certificate (new): 1 letter + 8/9 + 7 digits + 1 check digit
+ */
+// ============================================================
+// Constants
+// ============================================================
+/**
+ * City/locale code mapping for national ID first letter.
+ * Each value = tens * 1 + ones * 9 (pre-computed for checksum).
+ */
+const CITY_CODES = {
+    A: 1, B: 10, C: 19, D: 28, E: 37, F: 46, G: 55, H: 64,
+    I: 39, J: 73, K: 82, L: 2, M: 11, N: 22, O: 48, P: 29,
+    Q: 38, R: 47, S: 56, T: 65, U: 74, V: 83, W: 21, X: 3,
+    Y: 12, Z: 30,
+};
+/** City names for parsing. */
+const CITY_NAMES = {
+    A: '台北市', B: '台中市', C: '基隆市', D: '台南市', E: '高雄市',
+    F: '台北縣', G: '宜蘭縣', H: '桃園縣', I: '嘉義市', J: '新竹縣',
+    K: '苗栗縣', L: '台中縣', M: '南投縣', N: '彰化縣', O: '新竹市',
+    P: '雲林縣', Q: '嘉義縣', R: '台南縣', S: '高雄縣', T: '屏東縣',
+    U: '花蓮縣', V: '台東縣', W: '金門縣', X: '澎湖縣', Y: '陽明山',
+    Z: '連江縣',
+};
+/**
+ * Second letter mapping for old-format unified certificate.
+ * Pre-computed same way as CITY_CODES.
+ */
+const CERT_SECOND_LETTER = {
+    A: 0, B: 1, C: 2, D: 3, E: 4, F: 5, G: 6, H: 7,
+    I: 4, J: 8, K: 9, L: 0, M: 1, N: 2, O: 5, P: 3,
+    Q: 4, R: 5, S: 6, T: 7, U: 8, V: 9, W: 2, X: 0,
+    Y: 1, Z: 3,
+};
+/** Checksum weights: [first, 8 digits, checkDigit] */
+const CHECKSUM_WEIGHTS = [1, 8, 7, 6, 5, 4, 3, 2, 1, 1];
+// ============================================================
+// Core checksum algorithm (shared by national ID and unified cert)
+// ============================================================
+/**
+ * Compute the checksum for a Taiwan ID string.
+ * Works for both national ID and unified certificate.
+ */
+function computeChecksum(id) {
+    const firstCode = CITY_CODES[id[0]];
+    const secondChar = id[1];
+    // Second char: if letter (old unified cert), use CERT_SECOND_LETTER; if digit, parse it
+    const secondCode = isNaN(Number(secondChar))
+        ? CERT_SECOND_LETTER[secondChar]
+        : Number(secondChar);
+    const digits = [firstCode, secondCode, ...id.slice(2).split('').map(Number)];
+    return digits.reduce((sum, d, i) => sum + d * CHECKSUM_WEIGHTS[i], 0);
+}
+// ============================================================
+// National ID (身分證字號)
+// ============================================================
+/** National ID regex: 1 letter + 1/2 + 8 digits */
+const NATIONAL_ID_RE = /^[A-Z][12]\d{8}$/;
+/**
+ * Validate a Taiwan national ID number (身分證字號).
+ * Format: 1 letter + 1 digit (1 or 2) + 8 digits
+ */
+export function isValidNationalId(id) {
+    if (!NATIONAL_ID_RE.test(id))
+        return false;
+    return computeChecksum(id) % 10 === 0;
+}
+/**
+ * Parse a national ID number into its components.
+ * Returns null if invalid.
+ */
+export function parseNationalId(id) {
+    if (!isValidNationalId(id))
+        return null;
+    return {
+        city: CITY_NAMES[id[0]] ?? 'Unknown',
+        cityCode: id[0],
+        gender: id[1] === '1' ? 'male' : 'female',
+        sequence: id.slice(2, 9),
+        checkDigit: id[9],
+    };
+}
+/**
+ * Generate a test national ID number.
+ * @param city - City code (A-Z), defaults to 'A' (Taipei)
+ * @param gender - 'male' (1) or 'female' (2), defaults to 'male'
+ */
+export function generateNationalId(city = 'A', gender = 'male') {
+    if (!CITY_CODES[city])
+        return null;
+    const genderDigit = gender === 'male' ? '1' : '2';
+    const seq = String(Math.floor(Math.random() * 10000000)).padStart(7, '0');
+    const partial = city + genderDigit + seq;
+    // Find check digit (0-9) that makes checksum % 10 === 0
+    const firstCode = CITY_CODES[city];
+    const secondCode = Number(genderDigit);
+    const seqDigits = seq.split('').map(Number);
+    const baseSum = firstCode * 1 + secondCode * 8 +
+        seqDigits.reduce((sum, d, i) => sum + d * CHECKSUM_WEIGHTS[i + 2], 0);
+    const checkDigit = (10 - (baseSum % 10)) % 10;
+    return partial + checkDigit;
+}
+// ============================================================
+// Unified Certificate (統一證號)
+// ============================================================
+/** Old format: 2 letters (2nd A-D) + 8 digits */
+const UNIFIED_CERT_OLD_RE = /^[A-Z][A-D]\d{8}$/;
+/** New format: 1 letter + 8/9 + 8 digits (total 10 chars) */
+const UNIFIED_CERT_NEW_RE = /^[A-Z][89]\d{8}$/;
+/**
+ * Validate a Taiwan unified certificate number (統一證號).
+ * Supports both old and new formats.
+ */
+export function isValidUnifiedCert(id) {
+    if (UNIFIED_CERT_OLD_RE.test(id)) {
+        return computeChecksum(id) % 10 === 0;
+    }
+    if (UNIFIED_CERT_NEW_RE.test(id)) {
+        return computeChecksum(id) % 10 === 0;
+    }
+    return false;
+}
+/**
+ * Parse a unified certificate number.
+ * Returns null if invalid.
+ */
+export function parseUnifiedCert(id) {
+    if (!isValidUnifiedCert(id))
+        return null;
+    if (UNIFIED_CERT_OLD_RE.test(id)) {
+        return {
+            version: 'old',
+            cityCode: id[0],
+            category: id[1],
+            sequence: id.slice(2, 9),
+            checkDigit: id[9],
+        };
+    }
+    const categoryMap = {
+        '8': '外籍/無國籍',
+        '9': '大陸/港澳/無戶籍',
+    };
+    return {
+        version: 'new',
+        cityCode: id[0],
+        category: categoryMap[id[1]] ?? 'Unknown',
+        sequence: id.slice(2, 9),
+        checkDigit: id[9],
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { isValidNationalId, parseNationalId, generateNationalId, isValidUnifiedCert, parseUnifiedCert, type IdCardInfo, type UnifiedCertInfo, } from './id-card.js';
+export { isValidBAN, parseBAN, type BANInfo, } from './ban.js';
+export { isValidCDC, parseCDC, type CDCInfo, } from './cdc.js';
+export { isValidMobileBarcode, parseMobileBarcode, isValidDonateCode, parseDonateCode, type MobileBarcodeInfo, type DonateCodeInfo, } from './invoice.js';

package/dist/index.js

@@ -0,0 +1,8 @@
+// National ID + Unified Certificate
+export { isValidNationalId, parseNationalId, generateNationalId, isValidUnifiedCert, parseUnifiedCert, } from './id-card.js';
+// Business Administration Number
+export { isValidBAN, parseBAN, } from './ban.js';
+// Citizen Digital Certificate
+export { isValidCDC, parseCDC, } from './cdc.js';
+// E-Invoice
+export { isValidMobileBarcode, parseMobileBarcode, isValidDonateCode, parseDonateCode, } from './invoice.js';

package/dist/invoice.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Taiwan E-Invoice codes validation.
+ *
+ * Mobile Barcode (手機條碼): / + 7 chars [0-9A-Z.\-+]
+ * Donate Code (捐贈碼): 3-7 digits
+ */
+/**
+ * Validate a Taiwan E-Invoice Mobile Barcode (電子發票手機條碼).
+ */
+export declare function isValidMobileBarcode(code: string): boolean;
+export interface MobileBarcodeInfo {
+    barcode: string;
+}
+/**
+ * Parse a mobile barcode.
+ * Returns null if invalid.
+ */
+export declare function parseMobileBarcode(code: string): MobileBarcodeInfo | null;
+/**
+ * Validate a Taiwan E-Invoice Donate Code (電子發票捐贈碼).
+ * 3-7 digits.
+ */
+export declare function isValidDonateCode(code: string | number): boolean;
+export interface DonateCodeInfo {
+    code: string;
+}
+/**
+ * Parse a donate code.
+ * Returns null if invalid.
+ */
+export declare function parseDonateCode(code: string | number): DonateCodeInfo | null;

package/dist/invoice.js

@@ -0,0 +1,40 @@
+/**
+ * Taiwan E-Invoice codes validation.
+ *
+ * Mobile Barcode (手機條碼): / + 7 chars [0-9A-Z.\-+]
+ * Donate Code (捐贈碼): 3-7 digits
+ */
+const MOBILE_BARCODE_RE = /^\/[\dA-Z.\-+]{7}$/;
+const DONATE_CODE_RE = /^\d{3,7}$/;
+/**
+ * Validate a Taiwan E-Invoice Mobile Barcode (電子發票手機條碼).
+ */
+export function isValidMobileBarcode(code) {
+    return MOBILE_BARCODE_RE.test(code);
+}
+/**
+ * Parse a mobile barcode.
+ * Returns null if invalid.
+ */
+export function parseMobileBarcode(code) {
+    if (!isValidMobileBarcode(code))
+        return null;
+    return { barcode: code };
+}
+/**
+ * Validate a Taiwan E-Invoice Donate Code (電子發票捐贈碼).
+ * 3-7 digits.
+ */
+export function isValidDonateCode(code) {
+    return DONATE_CODE_RE.test(String(code));
+}
+/**
+ * Parse a donate code.
+ * Returns null if invalid.
+ */
+export function parseDonateCode(code) {
+    const str = String(code);
+    if (!isValidDonateCode(str))
+        return null;
+    return { code: str };
+}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "tw-id-validator",
+  "version": "1.0.5",
+  "description": "Taiwan ID validator. Supports national ID, unified certificate, BAN, citizen digital certificate, and e-invoice codes.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist/*.js",
+    "dist/*.d.ts",
+    "!dist/test*"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "npm run build && node dist/test-runner.js",
+    "clean": "node -e \"require('fs').rmSync('dist', { recursive: true, force: true })\"",
+    "security:audit": "node scripts/security-audit.mjs",
+    "release": "node scripts/release.mjs",
+    "release:dry": "node scripts/release.mjs --dry",
+    "release:patch": "node scripts/release.mjs patch",
+    "release:minor": "node scripts/release.mjs minor",
+    "prepublishOnly": "npm run typecheck && npm run build"
+  },
+  "keywords": [
+    "taiwan",
+    "id-validator",
+    "national-id",
+    "unified-certificate",
+    "ban",
+    "citizen-digital-certificate",
+    "e-invoice",
+    "身分證",
+    "統一證號",
+    "統一編號",
+    "自然人憑證",
+    "發票"
+  ],
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": ""
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.2"
+  }
+}