@erp/thai-id-reader

Thai ID Card Reader library for Node.js - Read Thai national ID card data using PC/SC protocol via Python pyscard library.

Features

• 📇 Read Thai national ID card data (Citizen ID, Name, Birth Date, Gender, Address, etc.)
• 🖼️ Extract photo from ID card (base64 encoded)
• 🔌 Support multiple card readers
• 🎯 TypeScript support with full type definitions
• 🔧 Flexible configuration options
• 🚀 Works with npm, yarn, bun, and pnpm

Prerequisites

System Requirements

1. Python 3 (3.7 or higher)
2. pyscard library
3. PC/SC Smart Card Service (usually pre-installed on macOS/Linux, or install PCSC Lite)
4. Card Reader compatible with PC/SC protocol

Installation

Automatic Installation (Recommended)

The package includes a postinstall script that automatically checks and installs Python dependencies (pyscard) when you install the package:

# Using npm
npm install @erp/thai-id-reader

# Using yarn
yarn add @erp/thai-id-reader

# Using bun
bun add @erp/thai-id-reader

# Using pnpm
pnpm add @erp/thai-id-reader

The postinstall script will:

• ✅ Check if Python 3 is installed
• ✅ Check if pyscard is already installed
• ✅ Automatically install pyscard if missing
• ⚠️ Show helpful warnings if Python is not found

Manual Installation (If automatic installation fails)

If the automatic installation fails, you can manually install Python dependencies:

# macOS
pip3 install pyscard
# or with system Python
pip3 install --break-system-packages pyscard

# Linux (Ubuntu/Debian)
sudo apt-get install pcscd pcsc-tools
pip3 install pyscard

# Windows
# Install PC/SC drivers for your card reader
pip install pyscard

Verify installation

# Check if Python can import pyscard
python3 -c "from smartcard.System import readers; print('OK')"

# List available readers
python3 -c "from smartcard.System import readers; print(readers())"

Installation

# Using npm
npm install @erp/thai-id-reader

# Using yarn
yarn add @erp/thai-id-reader

# Using bun
bun add @erp/thai-id-reader

# Using pnpm
pnpm add @erp/thai-id-reader

Usage

Basic Usage

import { ThaiIDCardReader } from '@erp/thai-id-reader';

const reader = new ThaiIDCardReader();

try {
  const cardData = await reader.readCard();
  console.log('Citizen ID:', cardData.citizenId);
  console.log('Name (TH):', cardData.nameTh);
  console.log('Name (EN):', cardData.nameEn);
  console.log('Birth Date:', cardData.birthDate);
  console.log('Gender:', cardData.gender);
  console.log('Address:', cardData.address);
} catch (error) {
  console.error('Error reading card:', error.message);
}

List Available Readers

import { ThaiIDCardReader } from '@erp/thai-id-reader';

const readers = await ThaiIDCardReader.listReaders();
console.log('Available readers:', readers);

// Use specific reader
const reader = new ThaiIDCardReader();
const cardData = await reader.readCard(readers[0]);

Advanced Configuration

import { ThaiIDCardReader } from '@erp/thai-id-reader';

const reader = new ThaiIDCardReader({
  pythonCommand: 'python3', // or 'python'
  pythonScriptPath: '/custom/path/to/read-card.py', // optional
  timeout: 30000, // 30 seconds
});

const cardData = await reader.readCard();

Using with NestJS

// card-reader.service.ts
import { Injectable } from '@nestjs/common';
import { ThaiIDCardReader } from '@erp/thai-id-reader';

@Injectable()
export class CardReaderService {
  private reader: ThaiIDCardReader;

  constructor() {
    this.reader = new ThaiIDCardReader();
  }

  async readCard() {
    return await this.reader.readCard();
  }

  async listReaders() {
    return await ThaiIDCardReader.listReaders();
  }
}

// card-reader.controller.ts
import { Controller, Get } from '@nestjs/common';
import { CardReaderService } from './card-reader.service';

@Controller('card-reader')
export class CardReaderController {
  constructor(private readonly cardReaderService: CardReaderService) {}

  @Get('read')
  async readCard() {
    try {
      const data = await this.cardReaderService.readCard();
      return { success: true, data };
    } catch (error) {
      return { success: false, error: error.message };
    }
  }

  @Get('readers')
  async listReaders() {
    const readers = await this.cardReaderService.listReaders();
    return { readers };
  }
}

API Reference

ThaiIDCardReader

Constructor

new ThaiIDCardReader(options?: ThaiIDCardReaderOptions)

Options:

• pythonScriptPath?: string - Custom path to Python script (default: bundled script)
• pythonCommand?: string - Python command to use (default: 'python3')
• timeout?: number - Timeout in milliseconds (default: 30000)

Methods

readCard(readerName?: string): Promise<ThaiIDCardData>

Read card data from the ID card.

Parameters:

• readerName?: string - Optional reader name. If not provided, uses the first available reader.

Returns: Promise resolving to ThaiIDCardData

Throws: Error if card cannot be read

listReaders(): Promise<string[]>

List available card readers (static method).

Returns: Promise resolving to array of reader names

Types

ThaiIDCardData

interface ThaiIDCardData {
  citizenId: string;        // 13-digit citizen ID
  nameTh: string;          // Thai name
  nameEn: string;          // English name
  birthDate: string;       // Format: YYYY-MM-DD
  gender: 'ชาย' | 'หญิง';   // Gender in Thai
  address: string;         // Full address
  issueDate: string;       // Format: YYYY-MM-DD
  expireDate: string;      // Format: YYYY-MM-DD or 'ตลอดชีพ' (lifetime)
  photo?: string;          // Base64 encoded image (optional)
}

Error Handling

The library provides Thai error messages for common errors:

• ไม่พบบัตร - No card present
• บัตรไม่ได้รับไฟ - Card not powered
• บัตรไม่ตอบสนอง - Card not responding
• Timeout: บัตรไม่ตอบสนอง - Timeout error

Always wrap calls in try-catch blocks:

try {
  const cardData = await reader.readCard();
  // Process card data
} catch (error) {
  if (error.message.includes('ไม่พบบัตร')) {
    // Handle no card scenario
  } else {
    // Handle other errors
  }
}

Troubleshooting

Python script not found

If you get an error about Python script not found, ensure the package is properly installed:

# Reinstall the package
npm install @erp/thai-id-reader --force

pyscard not found

The package includes an automatic installation script that runs on npm install / bun install. If it fails:

# Install pyscard manually
pip3 install pyscard

# On macOS with system Python
pip3 install --break-system-packages pyscard

# Verify installation
python3 -c "from smartcard.System import readers; print('OK')"

# Re-run postinstall script manually
cd node_modules/@erp/thai-id-reader
node scripts/install.js

No readers found

1. Ensure card reader is connected
2. Check if PC/SC service is running:

   # macOS/Linux
   pcsc_scan

3. Verify readers are detected:

   python3 -c "from smartcard.System import readers; print(readers())"

Permission errors (Linux)

On Linux, you may need to add your user to the pcscd group:

sudo usermod -a -G pcscd $USER
# Log out and log back in

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.