thai_id_utils 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a190bd99a1b5194f6dd8b8fb9b54ff187f8612acef24e17d86fbbe058f404e49
-  data.tar.gz: a13c400601b9ae3f4426fe8dfb619403cbd52ae511552b37c5617f0ae0518c8f
+  metadata.gz: 550dacaa281beb7bdba770c9dd0b54cf252f87b9aaf56fdfcaa9dbf7f3b22589
+  data.tar.gz: 3afd4ab32f6836e8995b473f2352a39d1b7e137c8aae7fac3a8815b21f3bce74
 SHA512:
-  metadata.gz: fbfe9afb6a1f1d13f4b8baa45e04287ba46b2c28abdf192fff6a7dd6debc745f55fefc7ea332fd601df7d9e3fdc41194e90da539648eb8038c19e4c72ede7232
-  data.tar.gz: 3503c0c47a6b022689f4a46958b03caf7e269b18131422aa2e6db107ce64d8c51fb9da675084844ef27aee650af22beecd8313ba679d81e92db0960c76eaf13c
+  metadata.gz: 2689046128e65c474735e500e843fe7470e3dc06cfb4c76c9aa7adee1ffbd80be38ecb1163d4f928aad94418137e14dce5aa0cf5ba8ba63acd5e47e730c26b24
+  data.tar.gz: 551c61957b236cdcd61c44d47e4f5d2eb02da24bf3fc9f8e5e36825c40a337cb0284eb301958a571440eaa0f21091570e52ec04cd1bc214c0ba8ce605f4abfcf

data/CHANGELOG.md

@@ -5,6 +5,27 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.0] - 2026-03-10
+
+### Added
+- `DISTRICT_COUNTS` constant — maps all 77 province codes to their number of
+  administrative districts (amphoe/khet), used to constrain district generation
+- `LASER_HARDWARE_VERSIONS` constant — known chip hardware-version prefixes
+  (`JC`, `AA`, `BB`, `GC`) observed on issued Thai ID cards
+- `province_codes` — returns all valid 2-digit province code strings
+- `generate_laser_id(hardware_version:, box_id:, position:)` — generates a
+  random, structurally valid laser ID in `XXN-NNNNNNN-NN` format
+
+### Changed
+- `generate` now accepts a `province_code:` keyword argument (default: random
+  valid province). When `office_code:` is not given, the district code is
+  constrained to the province's known range via `DISTRICT_COUNTS`. Passing
+  `office_code:` explicitly retains the previous behaviour unchanged.
+
+### Fixed
+- `generate` default no longer produces impossible province codes (e.g. `'00'`,
+  `'28'`). All generated IDs now have a geographically valid province by default.
+
 ## [0.2.0] - 2025-06-15
 
 ### Added
@@ -35,6 +56,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `category_description(category)` — human-readable description of ID category codes (0–8)
 - `InvalidIDError` — raised on invalid IDs passed to `decode`
 
+[0.3.0]: https://github.com/chayuto/thai_id_utils/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/chayuto/thai_id_utils/compare/v0.1.2...v0.2.0
 [0.1.2]: https://github.com/chayuto/thai_id_utils/compare/v0.1.1...v0.1.2
 [0.1.1]: https://github.com/chayuto/thai_id_utils/compare/v0.1.0...v0.1.1

data/README.md

@@ -1,34 +1,218 @@
 # Thai ID Utils
 
-Thai ID Utils is a zero-dependency Ruby gem for validating and decoding Thai national ID numbers. It provides a simple API to check the official modulus-11 checksum, extract the embedded components (category, office code, district code, sequence), and get a human-readable description of the category code.
- 
-Thai ID Utils เป็น Ruby gem ที่ไม่ต้องพึ่งพาไลบรารีเสริม สำหรับตรวจสอบความถูกต้องและถอดรหัสหมายเลขบัตรประชาชนไทย โดยมี API ที่ใช้งานง่ายสำหรับตรวจสอบ checksum ตามมาตรฐาน modulus-11 ดึงส่วนประกอบต่างๆ (ประเภทผู้ลงทะเบียน รหัสหน่วยงาน รหัสอำเภอ และหมายเลขลำดับ) และแสดงคำอธิบายของรหัสประเภทในรูปแบบอ่านง่าย
+Thai ID Utils is a zero-dependency Ruby gem for validating and decoding Thai national ID numbers.
+
+Thai ID Utils เป็น Ruby gem ที่ไม่ต้องพึ่งพาไลบรารีเสริม สำหรับตรวจสอบความถูกต้องและถอดรหัสหมายเลขบัตรประชาชนไทย
+
+[![Gem Version](https://badge.fury.io/rb/thai_id_utils.svg)](https://badge.fury.io/rb/thai_id_utils)
+
+---
+
+## Features / ฟีเจอร์
+
+- Checksum validation (modulus-11 algorithm)
+- Component decoding (category, province, district, sequence)
+- Province name lookup for all 77 provinces
+- Random valid ID generation — province-constrained by default, population-weighted sampling ready
+- Human-readable category descriptions (0–8)
+- Laser ID validation, decoding, and generation
+- Buddhist Era ↔ Common Era date conversion
+
+---
+
+## Installation / การติดตั้ง
+
+```ruby
+gem 'thai_id_utils'
+```
+
+Or install directly:
+
+```sh
+gem install thai_id_utils
+```
+
+---
 
 ## Usage / วิธีใช้งาน
 
 ```ruby
 require "thai_id_utils"
+```
+
+### Validate an ID / ตรวจสอบความถูกต้อง
 
-id = "3012304567082"
+```ruby
+ThaiIdUtils.valid?("3012304567082")  # => true
+ThaiIdUtils.valid?("1234567890123")  # => false
+```
+
+### Decode an ID / ถอดรหัสส่วนประกอบ
+
+```ruby
+info = ThaiIdUtils.decode("3012304567082")
+# => {
+#   category: 3,
+#   office_code: "0123",
+#   province_code: "01",
+#   province_name: nil,       # nil if province code not recognized
+#   district_code: "23",
+#   sequence: "04567",
+#   registration_code: "08"
+# }
+```
 
-# Validate checksum / ตรวจสอบความถูกต้องของ checksum
-if ThaiIdUtils.valid?(id)
-  puts "Valid!"
-else
-  puts "Invalid ID"
-end
+Raises `ThaiIdUtils::InvalidIDError` if the ID fails checksum validation.
 
-# Decode components / ถอดรหัสส่วนประกอบ
-info = ThaiIdUtils.decode(id)
-# => { category: 1, office_code: "6099", district_code: "99", sequence: "00257" }
-puts info.inspect
+### Province Name Lookup / ค้นหาชื่อจังหวัด
 
-# Get category description / คำอธิบายประเภท
-desc = ThaiIdUtils.category_description(info[:category])
+```ruby
+ThaiIdUtils.province_name("10")  # => "Bangkok"
+ThaiIdUtils.province_name("83")  # => "Phuket"
+ThaiIdUtils.province_name("50")  # => "Chiang Mai"
+ThaiIdUtils.province_name("99")  # => nil
+```
+
+All 77 Thai provinces are supported. Use `province_codes` to get the full list:
+
+```ruby
+ThaiIdUtils.province_codes
+# => ["10", "11", "12", ..., "96"]  (77 codes)
+```
+
+### Category Description / คำอธิบายประเภทบัตร
+
+```ruby
+ThaiIdUtils.category_description(1)
 # => "Thai nationals who were born after 1 January 1984 and had their birth notified within the given deadline (15 days)."
-puts desc
 
-# Generate a new random valid ID / สร้างหมายเลขบัตรประชาชนใหม่แบบสุ่มที่ถูกต้อง
-new_id = ThaiIdUtils.generate
-puts new_id  # => e.g. "3601205234518"
-```
+ThaiIdUtils.category_description(6)
+# => "Foreign nationals who are living in Thailand temporarily and illegal migrants"
+```
+
+### Generate a Valid ID / สร้างหมายเลขบัตรประชาชนแบบสุ่ม
+
+```ruby
+ThaiIdUtils.generate
+# => "1105312345671"  (random valid province, district within that province's range)
+
+# Pin to a specific province (district randomised within province's known range)
+ThaiIdUtils.generate(province_code: "10")   # Bangkok
+ThaiIdUtils.generate(province_code: "83")   # Phuket (3 districts)
+
+# Full override via office_code bypasses province validation (backwards compatible)
+ThaiIdUtils.generate(category: 1, office_code: "1001", sequence: "00001")
+
+# Raises ArgumentError for unknown province codes
+ThaiIdUtils.generate(province_code: "99")   # => ArgumentError
+```
+
+The default generates a geographically valid ID — province code is sampled uniformly from the 77 known codes and the district code is constrained to that province's actual district count via `DISTRICT_COUNTS`.
+
+### Laser ID Validation / ตรวจสอบเลขเลเซอร์
+
+```ruby
+ThaiIdUtils.laser_id_valid?("JC1-0002507-15")  # => true
+ThaiIdUtils.laser_id_valid?("INVALID")          # => false
+```
+
+Format: `XXN-NNNNNNN-NN` (two uppercase letters, one digit, hyphen, 7 digits, hyphen, 2 digits)
+
+### Laser ID Decoding / ถอดรหัสเลขเลเซอร์
+
+```ruby
+ThaiIdUtils.laser_id_decode("JC1-0002507-15")
+# => {
+#   hardware_version: "JC1",
+#   box_id: "0002507",
+#   position: "15"
+# }
+```
+
+Raises `ThaiIdUtils::InvalidIDError` if the format is invalid.
+
+### Generate a Laser ID / สร้างเลขเลเซอร์
+
+```ruby
+ThaiIdUtils.generate_laser_id
+# => "JC2-0483921-07"  (random, always matches LASER_ID_FORMAT)
+
+# Override individual components
+ThaiIdUtils.generate_laser_id(hardware_version: "JC1", box_id: 2507, position: 15)
+# => "JC1-0002507-15"
+```
+
+Known hardware version prefixes (`LASER_HARDWARE_VERSIONS`): `JC`, `AA`, `BB`, `GC`.
+The laser ID is a supply-chain tracking code with no mathematical link to the citizen ID.
+
+### Buddhist Era Conversion / แปลงปี พ.ศ. ↔ ค.ศ.
+
+```ruby
+ThaiIdUtils.be_to_ce(2567)  # => 2024
+ThaiIdUtils.ce_to_be(2024)  # => 2567
+```
+
+---
+
+## API Reference / สรุป API
+
+| Method | Description |
+|---|---|
+| `valid?(id)` | Returns `true` if the 13-digit ID passes checksum |
+| `decode(id)` | Returns a hash of decoded components; raises `InvalidIDError` on failure |
+| `generate(category:, province_code:, office_code:, district_code:, sequence:)` | Generates a random valid 13-digit ID; defaults to a valid province |
+| `province_name(code)` | Returns province name for a 2-digit code, or `nil` |
+| `province_codes` | Returns all 77 valid 2-digit province code strings |
+| `category_description(n)` | Returns human-readable category description |
+| `laser_id_valid?(laser_id)` | Returns `true` if the laser ID format matches |
+| `laser_id_decode(laser_id)` | Returns decoded laser ID hash; raises `InvalidIDError` on failure |
+| `generate_laser_id(hardware_version:, box_id:, position:)` | Generates a random valid laser ID |
+| `be_to_ce(year)` | Converts Buddhist Era year to Common Era |
+| `ce_to_be(year)` | Converts Common Era year to Buddhist Era |
+
+**Constants**
+
+| Constant | Description |
+|---|---|
+| `PROVINCE_CODES` | Hash mapping 77 province codes to English names |
+| `DISTRICT_COUNTS` | Hash mapping province codes to their district count |
+| `LASER_HARDWARE_VERSIONS` | Array of known chip hardware-version prefixes |
+| `LASER_ID_FORMAT` | Regex for laser ID format validation |
+
+---
+
+## Synthetic Dataset / ชุดข้อมูลสังเคราะห์
+
+A 350,000-row fully synthetic dataset generated with this gem is published on HuggingFace:
+
+**[huggingface.co/datasets/chayuto/thai-id-synthetic](https://huggingface.co/datasets/chayuto/thai-id-synthetic)**
+
+- 332,500 valid IDs + 17,500 invalid IDs (bad checksum, impossible province, wrong category, wrong length)
+- Population-weighted province sampling (NSO 2023), realistic category distribution
+- train / test splits (315K / 35K)
+- No real citizen data — 100% synthetic
+
+To regenerate:
+
+```sh
+cd dataset
+ruby generate.rb --count 350000 --invalid-ratio 0.05 --seed 42
+```
+
+---
+
+## Development / การพัฒนา
+
+```sh
+# Run tests
+rake
+
+# Or directly
+ruby -Ilib -Itest test/test_thai_id_utils.rb
+```
+
+---
+
+## License / สัญญาอนุญาต
+
+[MIT License](LICENSE)

data/lib/thai_id_utils/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ThaiIdUtils
-  VERSION = '0.2.0'
+  VERSION = '0.3.0'
 end

data/lib/thai_id_utils.rb

@@ -67,9 +67,37 @@ module ThaiIdUtils
   }.freeze
   # rubocop:enable Layout/LineLength
 
+  # Mapping of province codes to the number of administrative districts
+  # (amphoe for provinces, khet for Bangkok). Used to constrain district code
+  # generation to realistic ranges within generate().
+  # Counts are approximate and reflect post-2011 administrative divisions.
+  DISTRICT_COUNTS = {
+    '10' => 50, '11' => 11, '12' => 6,  '13' => 7,  '14' => 16,
+    '15' => 7,  '16' => 11, '17' => 6,  '18' => 8,  '19' => 13,
+    '20' => 11, '21' => 8,  '22' => 10, '23' => 7,  '24' => 11,
+    '25' => 7,  '26' => 4,  '27' => 9,
+    '30' => 32, '31' => 23, '32' => 17, '33' => 22, '34' => 25,
+    '35' => 9,  '36' => 16, '37' => 7,  '38' => 8,  '39' => 6,
+    '40' => 26, '41' => 20, '42' => 14, '43' => 18, '44' => 13,
+    '45' => 20, '46' => 18, '47' => 18, '48' => 12, '49' => 7,
+    '50' => 25, '51' => 8,  '52' => 13, '53' => 9,  '54' => 8,
+    '55' => 15, '56' => 9,  '57' => 18, '58' => 7,
+    '60' => 15, '61' => 8, '62' => 11, '63' => 8, '64' => 9,
+    '65' => 9,  '66' => 12, '67' => 11,
+    '70' => 10, '71' => 13, '72' => 10, '73' => 7, '74' => 7,
+    '75' => 3,  '76' => 8,  '77' => 8,
+    '80' => 23, '81' => 8, '82' => 8, '83' => 3, '84' => 19,
+    '85' => 5,  '86' => 8,
+    '90' => 16, '91' => 7, '92' => 10, '93' => 11, '94' => 12,
+    '95' => 8,  '96' => 9
+  }.freeze
+
   LASER_ID_FORMAT = /\A[A-Z]{2}\d-\d{7}-\d{2}\z/.freeze
 
-  # Validate a Thai national ID using Thailand’s modulus-11 checksum algorithm.
+  # Known chip hardware-version prefixes observed on issued Thai ID cards.
+  LASER_HARDWARE_VERSIONS = %w[JC AA BB GC].freeze
+
+  # Validate a Thai national ID using Thailand's modulus-11 checksum algorithm.
   #
   # @param id [String, Integer] 13-digit Thai national ID number
   # @return [Boolean] true if the checksum is valid, false otherwise
@@ -112,39 +140,58 @@ module ThaiIdUtils
   end
 
   # Generate a random, valid 13-digit Thai national ID.
-  # Any component can be overridden; the rest is randomized and the checksum is computed.
+  # Any component can be overridden; the rest is randomised and the checksum
+  # is computed. When neither +office_code+ nor +province_code+ is given, a
+  # valid province is selected at random and a district code within that
+  # province's known range is generated.
   #
   # @param category [Integer] ID category (1–8), default: random 1–6
-  # @param office_code [Integer, String, nil] 4-digit registrar code, default: random
-  # @param district_code [String, nil] 2-digit district override within office_code
+  # @param province_code [String, nil] 2-digit province code (e.g. "10").
+  #   Must be a key in PROVINCE_CODES. Ignored when +office_code+ is given.
+  # @param office_code [Integer, String, nil] 4-digit registrar code override.
+  #   When supplied, bypasses province_code and district_code validation.
+  # @param district_code [String, nil] 2-digit district override (applied on
+  #   top of whatever office_code is built).
   # @param sequence [Integer, String, nil] 5-digit personal sequence, default: random
   # @return [String] a valid 13-digit Thai national ID
-  # rubocop:disable Metrics/AbcSize
+  # @raise [ArgumentError] if province_code is given but not in PROVINCE_CODES
+  # rubocop:disable Metrics/AbcSize, Metrics/PerceivedComplexity
   def self.generate(category: rand(1..6),
+                    province_code: PROVINCE_CODES.keys.sample,
                     office_code: nil,
                     district_code: nil,
                     sequence: nil)
-    # Build and override office_code/district_code
-    office_code = format('%04d', office_code || rand(1..9_999))
+    office_code = if office_code
+                    format('%04d', office_code)
+                  else
+                    pcode = province_code.to_s
+                    raise ArgumentError, "Unknown province_code: #{pcode.inspect}" unless PROVINCE_CODES.key?(pcode)
+
+                    "#{pcode}#{format('%02d', rand(1..DISTRICT_COUNTS[pcode]))}"
+                  end
     office_code[2..3] = district_code.to_s.rjust(2, '0') if district_code
 
-    # Sequence (5 digits) and classification (2 digits)
     sequence       = format('%05d', sequence || rand(0..99_999))
     classification = format('%02d', rand(0..99))
 
-    # First 12 digits: category + office_code + sequence + classification
     digits = [category.to_i] +
              office_code.chars.map(&:to_i) +
              sequence.chars.map(&:to_i) +
              classification.chars.map(&:to_i)
 
-    # Checksum
     sum = digits.each_with_index.sum { |d, i| d * (13 - i) }
     check = (11 - (sum % 11)) % 10
 
     (digits + [check]).join
   end
-  # rubocop:enable Metrics/AbcSize
+  # rubocop:enable Metrics/AbcSize, Metrics/PerceivedComplexity
+
+  # Return all valid 2-digit province code strings.
+  #
+  # @return [Array<String>] all keys of PROVINCE_CODES
+  def self.province_codes
+    PROVINCE_CODES.keys
+  end
 
   # Return the human-readable description for a Thai ID category code.
   #
@@ -205,4 +252,19 @@ module ThaiIdUtils
       position: parts[2]
     }
   end
+
+  # Generate a random, valid Thai ID card laser ID.
+  # Format: XXN-NNNNNNN-NN  (e.g., JC1-0002507-15)
+  #
+  # @param hardware_version [String, nil] full 3-char chip code (e.g. "JC1").
+  #   Defaults to a random prefix from LASER_HARDWARE_VERSIONS + digit 1–3.
+  # @param box_id [Integer, nil] distribution box number (1–9,999,999)
+  # @param position [Integer, nil] slot within the box (1–60)
+  # @return [String] a laser ID string matching LASER_ID_FORMAT
+  def self.generate_laser_id(hardware_version: nil, box_id: nil, position: nil)
+    hw  = hardware_version || "#{LASER_HARDWARE_VERSIONS.sample}#{rand(1..3)}"
+    box = format('%07d', box_id || rand(1..9_999_999))
+    pos = format('%02d', position || rand(1..60))
+    "#{hw}-#{box}-#{pos}"
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: thai_id_utils
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Chayut Orapinpatipat
@@ -25,11 +25,14 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '5.0'
 description: |
-  Zero-dependency Ruby utilities for:
+  Zero-dependency Ruby utilities for Thai national ID numbers:
     • checksum validation (modulus-11),
-    • component decoding (category, office_code, district_code, sequence),
-    • random valid ID generation,
-    • human-readable category descriptions.
+    • component decoding (category, province, district, sequence),
+    • province-constrained valid ID generation with DISTRICT_COUNTS,
+    • province name lookup for all 77 provinces,
+    • laser ID validation, decoding, and generation,
+    • human-readable category descriptions (0–8),
+    • Buddhist Era ↔ Common Era date conversion.
 email:
 - chayut_o@hotmail.com
 executables: []
@@ -67,5 +70,5 @@ requirements: []
 rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
-summary: Validate and decode Thai national ID numbers
+summary: Validate, decode, and generate Thai national ID numbers
 test_files: []