thai_id_utils 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d9194c3362b9038193a979c13e0d7723bb0c6f0c3ce41ff17523086ef8a04672
-  data.tar.gz: dac42ef970424a31999019dc4c3d8d1fa5c5739c55427440906e118d4c2cecba
+  metadata.gz: a190bd99a1b5194f6dd8b8fb9b54ff187f8612acef24e17d86fbbe058f404e49
+  data.tar.gz: a13c400601b9ae3f4426fe8dfb619403cbd52ae511552b37c5617f0ae0518c8f
 SHA512:
-  metadata.gz: c3f92740ba6ac0700b5cddb7abdc23a74cdc759a822a14936a1a36acbd43e021ad42f395889ec09d4db5cf3ed1f641599d454d1b8eb4cc17756365f26f853ab9
-  data.tar.gz: 49bbfa319256583fd8156cea558995d2d555e17352b0391830046ff78cdb90034306c9cf5cb0d5eacf13195380d61c3196e14d7d7d27f38b266195b04c67240c
+  metadata.gz: fbfe9afb6a1f1d13f4b8baa45e04287ba46b2c28abdf192fff6a7dd6debc745f55fefc7ea332fd601df7d9e3fdc41194e90da539648eb8038c19e4c72ede7232
+  data.tar.gz: 3503c0c47a6b022689f4a46958b03caf7e269b18131422aa2e6db107ce64d8c51fb9da675084844ef27aee650af22beecd8313ba679d81e92db0960c76eaf13c

data/CHANGELOG.md

@@ -0,0 +1,41 @@
+# Changelog
+
+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.2.0] - 2025-06-15
+
+### Added
+- Province code lookup (`PROVINCE_CODES`) mapping all 77 Thai provinces
+- `province_name(code)` — return province name from 2-digit code
+- Laser ID validation (`laser_id_valid?`) using format `XXN-NNNNNNN-NN`
+- Laser ID decoding (`laser_id_decode`) into hardware version, box ID, and position
+- Buddhist Era conversion: `be_to_ce(year)` and `ce_to_be(year)`
+- `province_name` field included in `decode` output hash
+
+## [0.1.2] - 2025-06-15
+
+### Fixed
+- Minor internal cleanup; no public API changes
+
+## [0.1.1] - 2025-06-15
+
+### Fixed
+- Gemspec corrections and metadata updates
+
+## [0.1.0] - 2025-06-15
+
+### Added
+- Initial release
+- `valid?(id)` — checksum validation using Thailand's modulus-11 algorithm
+- `decode(id)` — decode category, office code, province code, district code, sequence, and registration code
+- `generate(...)` — generate a random valid 13-digit Thai national ID with optional overrides
+- `category_description(category)` — human-readable description of ID category codes (0–8)
+- `InvalidIDError` — raised on invalid IDs passed to `decode`
+
+[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
+[0.1.0]: https://github.com/chayuto/thai_id_utils/releases/tag/v0.1.0

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Chayut Orapinpatipat
+
+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.

data/README.md

@@ -11,23 +11,24 @@ require "thai_id_utils"
 
 id = "3012304567082"
 
-# ✅ Validate checksum
+# Validate checksum / ตรวจสอบความถูกต้องของ checksum
 if ThaiIdUtils.valid?(id)
   puts "Valid!"
 else
   puts "Invalid ID"
 end
 
-# 🔍 Decode components
+# Decode components / ถอดรหัสส่วนประกอบ
 info = ThaiIdUtils.decode(id)
 # => { category: 1, office_code: "6099", district_code: "99", sequence: "00257" }
 puts info.inspect
 
-# 🏷️ Get category description
+# Get category description / คำอธิบายประเภท
 desc = ThaiIdUtils.category_description(info[:category])
 # => "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
+# Generate a new random valid ID / สร้างหมายเลขบัตรประชาชนใหม่แบบสุ่มที่ถูกต้อง
 new_id = ThaiIdUtils.generate
 puts new_id  # => e.g. "3601205234518"
+```

data/lib/thai_id_utils/version.rb

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

data/lib/thai_id_utils.rb

@@ -21,9 +21,58 @@ module ThaiIdUtils
     7 => 'Children of people of category 6 who were born in Thailand',
     8 => 'Foreign nationals who are living in Thailand permanently or Thai nationals by naturalization'
   }.freeze
+
+  # Mapping of 2-digit province codes (digits 2-3 of the ID) to province names
+  PROVINCE_CODES = {
+    '10' => 'Bangkok',                    '11' => 'Samut Prakan',
+    '12' => 'Nonthaburi',                 '13' => 'Pathum Thani',
+    '14' => 'Phra Nakhon Si Ayutthaya',   '15' => 'Ang Thong',
+    '16' => 'Lopburi',                    '17' => 'Sing Buri',
+    '18' => 'Chainat',                    '19' => 'Saraburi',
+    '20' => 'Chonburi',                   '21' => 'Rayong',
+    '22' => 'Chanthaburi',                '23' => 'Trat',
+    '24' => 'Chachoengsao',               '25' => 'Prachin Buri',
+    '26' => 'Nakhon Nayok',               '27' => 'Sa Kaeo',
+    '30' => 'Nakhon Ratchasima',          '31' => 'Buri Ram',
+    '32' => 'Surin',                      '33' => 'Si Sa Ket',
+    '34' => 'Ubon Ratchathani',           '35' => 'Yasothon',
+    '36' => 'Chaiyaphum',                 '37' => 'Amnat Charoen',
+    '38' => 'Bueng Kan',                  '39' => 'Nong Bua Lamphu',
+    '40' => 'Khon Kaen',                  '41' => 'Udon Thani',
+    '42' => 'Loei',                       '43' => 'Nong Khai',
+    '44' => 'Maha Sarakham',              '45' => 'Roi Et',
+    '46' => 'Kalasin',                    '47' => 'Sakon Nakhon',
+    '48' => 'Nakhon Phanom',              '49' => 'Mukdahan',
+    '50' => 'Chiang Mai',                 '51' => 'Lamphun',
+    '52' => 'Lampang',                    '53' => 'Uttaradit',
+    '54' => 'Phrae',                      '55' => 'Nan',
+    '56' => 'Phayao',                     '57' => 'Chiang Rai',
+    '58' => 'Mae Hong Son',
+    '60' => 'Nakhon Sawan',               '61' => 'Uthai Thani',
+    '62' => 'Kamphaeng Phet',             '63' => 'Tak',
+    '64' => 'Sukhothai',                  '65' => 'Phitsanulok',
+    '66' => 'Phichit',                    '67' => 'Phetchabun',
+    '70' => 'Ratchaburi',                 '71' => 'Kanchanaburi',
+    '72' => 'Suphanburi',                 '73' => 'Nakhon Pathom',
+    '74' => 'Samut Sakhon',               '75' => 'Samut Songkhram',
+    '76' => 'Phetchaburi',                '77' => 'Prachuap Khiri Khan',
+    '80' => 'Nakhon Si Thammarat',        '81' => 'Krabi',
+    '82' => 'Phangnga',                   '83' => 'Phuket',
+    '84' => 'Surat Thani',                '85' => 'Ranong',
+    '86' => 'Chumphon',
+    '90' => 'Songkhla',                   '91' => 'Satun',
+    '92' => 'Trang',                      '93' => 'Phatthalung',
+    '94' => 'Pattani',                    '95' => 'Yala',
+    '96' => 'Narathiwat'
+  }.freeze
   # rubocop:enable Layout/LineLength
 
-  # Public: Validate checksum using Thailand’s modulus-11 algorithm
+  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.
+  #
+  # @param id [String, Integer] 13-digit Thai national ID number
+  # @return [Boolean] true if the checksum is valid, false otherwise
   def self.valid?(id)
     digits = id.to_s.chars.map(&:to_i)
     return false unless digits.size == 13
@@ -34,12 +83,18 @@ module ThaiIdUtils
     false
   end
 
-  # Public: Decode components present in a Thai ID
-  # Returns a hash with keys:
-  #   :category      => Integer
-  #   :office_code   => String (4-digit registrar)
-  #   :district_code => String (last 2 of office_code)
-  #   :sequence      => String (5-digit personal sequence)
+  # Decode the components encoded in a Thai national ID number.
+  #
+  # @param id [String, Integer] 13-digit Thai national ID number
+  # @return [Hash] decoded fields:
+  #   - `:category` [Integer] — registration category (0–8)
+  #   - `:office_code` [String] — 4-digit registrar code (province + district)
+  #   - `:province_code` [String] — first 2 digits of office_code
+  #   - `:province_name` [String, nil] — province name, or nil if unknown
+  #   - `:district_code` [String] — last 2 digits of office_code
+  #   - `:sequence` [String] — 5-digit personal sequence number
+  #   - `:registration_code` [String] — 2-digit chronological sequence marker
+  # @raise [InvalidIDError] if the ID fails checksum validation
   def self.decode(id)
     raise InvalidIDError, 'Invalid ID' unless valid?(id)
 
@@ -48,14 +103,23 @@ module ThaiIdUtils
     {
       category: d[0].to_i,
       office_code: d[1..4].join,
+      province_code: d[1..2].join,
+      province_name: PROVINCE_CODES[d[1..2].join],
       district_code: d[3..4].join,
-      sequence: d[5..9].join
+      sequence: d[5..9].join,
+      registration_code: d[10..11].join
     }
   end
 
-  # Public: Generate a random, valid 13-digit Thai national ID.
-  # You can override any component or let it be randomized.
-  # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength
+  # Generate a random, valid 13-digit Thai national ID.
+  # Any component can be overridden; the rest is randomized and the checksum is computed.
+  #
+  # @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 sequence [Integer, String, nil] 5-digit personal sequence, default: random
+  # @return [String] a valid 13-digit Thai national ID
+  # rubocop:disable Metrics/AbcSize
   def self.generate(category: rand(1..6),
                     office_code: nil,
                     district_code: nil,
@@ -80,10 +144,65 @@ module ThaiIdUtils
 
     (digits + [check]).join
   end
-  # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength
+  # rubocop:enable Metrics/AbcSize
 
-  # Public: Return a human-readable description for a category code
+  # Return the human-readable description for a Thai ID category code.
+  #
+  # @param category [Integer, String] category digit (0–8)
+  # @return [String] description, or "Unknown category" if not found
   def self.category_description(category)
     CATEGORY_DESCRIPTIONS[category.to_i] || 'Unknown category'
   end
+
+  # Return the province name for a 2-digit province code.
+  #
+  # @param code [String] 2-digit province code (e.g., "10" for Bangkok)
+  # @return [String, nil] province name, or nil if the code is not recognized
+  def self.province_name(code)
+    PROVINCE_CODES[code.to_s]
+  end
+
+  # Convert a Buddhist Era year to Common Era (subtract 543).
+  #
+  # @param year [Integer, String] Buddhist Era year (e.g., 2567)
+  # @return [Integer] Common Era year (e.g., 2024)
+  def self.be_to_ce(year)
+    year.to_i - 543
+  end
+
+  # Convert a Common Era year to Buddhist Era (add 543).
+  #
+  # @param year [Integer, String] Common Era year (e.g., 2024)
+  # @return [Integer] Buddhist Era year (e.g., 2567)
+  def self.ce_to_be(year)
+    year.to_i + 543
+  end
+
+  # Validate the format of a Thai ID card laser ID (printed on the card back).
+  # Expected format: XXN-NNNNNNN-NN  (e.g., JC1-0002507-15)
+  #
+  # @param laser_id [String] the laser ID string to validate
+  # @return [Boolean] true if format matches, false otherwise
+  def self.laser_id_valid?(laser_id)
+    LASER_ID_FORMAT.match?(laser_id.to_s)
+  end
+
+  # Decode a Thai ID card laser ID into its components.
+  #
+  # @param laser_id [String] laser ID string (e.g., "JC1-0002507-15")
+  # @return [Hash] decoded fields:
+  #   - `:hardware_version` [String] — chip generation code (e.g., "JC1")
+  #   - `:box_id` [String] — distribution box number (e.g., "0002507")
+  #   - `:position` [String] — slot within the box (e.g., "15")
+  # @raise [InvalidIDError] if the laser ID format is invalid
+  def self.laser_id_decode(laser_id)
+    raise InvalidIDError, 'Invalid laser ID' unless laser_id_valid?(laser_id)
+
+    parts = laser_id.to_s.split('-')
+    {
+      hardware_version: parts[0],
+      box_id: parts[1],
+      position: parts[2]
+    }
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: thai_id_utils
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Chayut Orapinpatipat
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-06-15 00:00:00.000000000 Z
+date: 2026-03-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest
@@ -36,15 +36,19 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- Gemfile
+- CHANGELOG.md
+- LICENSE
 - README.md
-- Rakefile
 - lib/thai_id_utils.rb
 - lib/thai_id_utils/version.rb
-homepage: https://github.com/chayuto/thai-id-utils
+homepage: https://github.com/chayuto/thai_id_utils
 licenses:
 - MIT
-metadata: {}
+metadata:
+  documentation_uri: https://rubydoc.info/gems/thai_id_utils
+  source_code_uri: https://github.com/chayuto/thai_id_utils
+  changelog_uri: https://github.com/chayuto/thai_id_utils/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []
 require_paths:
@@ -60,7 +64,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.11
+rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
 summary: Validate and decode Thai national ID numbers

data/Gemfile

@@ -1,5 +0,0 @@
-# frozen_string_literal: true
-
-source 'https://rubygems.org'
-
-gemspec

data/Rakefile

@@ -1,9 +0,0 @@
-# frozen_string_literal: true
-
-require 'rake/testtask'
-
-Rake::TestTask.new do |t|
-  t.libs << 'test'
-end
-
-task default: :test