sec_id 4.3.0 → 4.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 227ed0f22f9d18523b28c4553fd0ce5765a3367eae8e39017a8ce006d9f161fa
-  data.tar.gz: e46b18732147a27e2cdd0d74728619c4ba10bfd8210982a45d40358ee3f7c06a
+  metadata.gz: d1a703602defc67f745ab0994c73f61d964ed1047a029cc01c2cf7edcda82045
+  data.tar.gz: cf7a004bb992ceb3a9991946d09c908a76d13852c7a87a0b2527a4633da869be
 SHA512:
-  metadata.gz: ddca4d991fcacd93520d36b87697a39d8121cbad2c8d70002c4dcc56334a6d8f3d6f58138b34d1ef2eb3f3b2e4eae284e10e1a8a2adb5d10d858aa956d809b94
-  data.tar.gz: 766cc6f3bacd4210c52364e2c5972b0311a2a0d3f9c20c6cac02735a7eb36b9b9a601bd21a01a1e69b0a7346c44079e59bd6ac0ecf377be4e880bee80731e27d
+  metadata.gz: c4e726ce2c1cd7b64dc6d2f8db7e284166ff0229eef52f064975d244e766e28ba239dd8f39dc1730e3b092ae0e57cf982adb683711cde6dd9b15a4bc8c88eb09
+  data.tar.gz: '0986116c63812cc37af215b4f564e3db44d4ea154d90dc49a99e82096fe18e099277087a2b399920e2bf03acbdc69d098b6442c2195d434f2af3230cffe2b257'

data/CHANGELOG.md

@@ -1,7 +1,39 @@
 # 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.1.0/).
+This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html)
+and [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/).
+
 ## [Unreleased]
 
+## [4.4.0] - 2026-01-29
+
+### Added
+
+- Cross-identifier conversions: SEDOL, WKN, and Valoren `to_isin` methods with country code validation; ISIN `to_sedol`, `to_wkn`, `to_valoren` methods with predicate helpers (`sedol?`, `wkn?`, `valoren?`) ([#115](https://github.com/svyatov/sec_id/pull/115))
+- ISIN `nsin_type` and `to_nsin` methods for country-aware NSIN extraction ([#114](https://github.com/svyatov/sec_id/pull/114))
+- CEI (CUSIP Entity Identifier) support for syndicated loan market entity identification ([#113](https://github.com/svyatov/sec_id/pull/113))
+- FISN (Financial Instrument Short Name) support per ISO 18774 ([#112](https://github.com/svyatov/sec_id/pull/112))
+- CFI (Classification of Financial Instruments) support with category/group validation and equity-specific predicates ([#111](https://github.com/svyatov/sec_id/pull/111))
+- Valoren support (Swiss Security Number) ([@wtn](https://github.com/wtn), [#109](https://github.com/svyatov/sec_id/pull/109))
+- WKN support (Wertpapierkennnummer - German securities identifier) ([@wtn](https://github.com/wtn), [#108](https://github.com/svyatov/sec_id/pull/108))
+
+### Changed
+
+- Replaced `has_check_digit` DSL with explicit `Checkable` concern that consolidates all check-digit logic (constants, Luhn algorithms, validation, restoration)
+- Simplified `Base` class to core validation and parsing; check-digit classes now `include Checkable`
+- Non-check-digit classes (CIK, OCC, WKN, Valoren, CFI, FISN) no longer need any special declaration
+- Moved `Normalizable` module to `lib/sec_id/concerns/` for consistency with other concerns
+- Optimized hot paths by replacing `&method(:char_to_digit)` with inline blocks to avoid Method object allocation
+- Added frozen Set constants for ISIN country code lookups (`SEDOL_COUNTRY_CODES`, `VALOREN_COUNTRY_CODES`)
+
+### Fixed
+
+- Allow Crown Dependencies (GG, IM, JE) and Overseas Territories (FK) in SEDOL/ISIN conversions ([@wtn](https://github.com/wtn), [#117](https://github.com/svyatov/sec_id/pull/117))
+- Removed BR (Brazil) from CGS country codes — Brazil never used CINS numbers and Brazilian ISINs cannot be converted to CUSIP ([@wtn](https://github.com/wtn), [#110](https://github.com/svyatov/sec_id/pull/110))
+
 ## [4.3.0] - 2025-01-13
 
 ### Added
@@ -9,12 +41,9 @@
 - LEI support (Legal Entity Identifier, ISO 17442)
 - IBAN support (International Bank Account Number, ISO 13616) with EU/EEA country validation
 
-### Updated
+### Changed
 
 - Improved README: better formatting, navigation, and clear API distinction between check-digit and normalization identifiers
-
-### Internal
-
 - Refactored CIK and OCC to inherit from Base class with `has_check_digit?` hook for cleaner architecture
 - Added `Normalizable` module for consistent `normalize!` class method across identifiers
 - Added `validate_format_for_calculation!` helper method to Base class to reduce code duplication
@@ -31,11 +60,7 @@
 
 - OCC support ([@wtn](https://github.com/wtn), [#93](https://github.com/svyatov/sec_id/pull/93))
 
-### Fixed
-
-- CUSIP#cins? usage example in README ([@wtn](https://github.com/wtn), [#91](https://github.com/svyatov/sec_id/pull/91))
-
-### Updated
+### Changed
 
 - Separate CIK from Base for cleaner architecture ([@wtn](https://github.com/wtn), [#92](https://github.com/svyatov/sec_id/pull/92))
 - Use rubocop-rspec plugin ([@wtn](https://github.com/wtn), [#90](https://github.com/svyatov/sec_id/pull/90))
@@ -43,6 +68,10 @@
 - Add permissions to CI workflow
 - Clean up gemspec: update description and simplify files list
 
+### Fixed
+
+- CUSIP#cins? usage example in README ([@wtn](https://github.com/wtn), [#91](https://github.com/svyatov/sec_id/pull/91))
+
 ## [4.1.0] - 2024-09-23
 
 ### Added
@@ -52,19 +81,16 @@
 - Convert between CUSIPs and ISINs ([@wtn](https://github.com/wtn), [#86](https://github.com/svyatov/sec_id/pull/86), [#88](https://github.com/svyatov/sec_id/pull/88))
 - CINS check method for CUSIPs ([@wtn](https://github.com/wtn), [#87](https://github.com/svyatov/sec_id/pull/87))
 
-### Updated
+### Changed
 
 - Small internal refactorings
 
 ## [4.0.0] - 2024-07-09
 
-### Breaking changes
-
-- Minimum required Ruby version is 3.1 now
-- Default repository branch renamed to `main`
-
-### Updated
+### Changed
 
+- **BREAKING:** Minimum required Ruby version is 3.1 now
+- **BREAKING:** Default repository branch renamed to `main`
 - Small internal refactorings
 - TravisCI -> GitHub Actions
 - Dropped tests for Ruby below 3.1
@@ -72,12 +98,9 @@
 
 ## [3.0.0] - 2020-03-10
 
-### Breaking changes
-
-- Minimum required Ruby version is 2.5 now
-
-### Updated
+### Changed
 
+- **BREAKING:** Minimum required Ruby version is 2.5 now
 - Small internal refactorings
 - TravisCI config updated: dropped Ruby 2.3 and 2.4, added Ruby 2.7
 - Rubocop's Ruby target version changed to 2.5
@@ -88,11 +111,9 @@
 
 - SEDOL numbers support: `SecId::SEDOL`
 
-### Updated
-
-- **Breaking change**
+### Changed
 
-    API for accessing full number is unified across all classes:
+- **BREAKING:** API for accessing full number is unified across all classes:
 
     ```
     SecId::ISIN#full_number  # previously SecId::ISIN#isin
@@ -111,7 +132,7 @@
 - CUSIP numbers support: `SecId::CUSIP`
 - CHANGELOG.md file added
 
-### Updated
+### Changed
 
 - Char to digit conversion now uses precalculated tables instead of dynamic calculation for speed
 

data/README.md

@@ -1,4 +1,4 @@
-# SecId [![Gem Version](https://img.shields.io/gem/v/sec_id)](https://rubygems.org/gems/sec_id) [![Codecov](https://img.shields.io/codecov/c/github/svyatov/sec_id)](https://app.codecov.io/gh/svyatov/sec_id) [![CI](https://github.com/svyatov/sec_id/actions/workflows/main.yml/badge.svg?branch=main)](https://github.com/svyatov/sec_id/actions?query=workflow%3ACI) [![License](https://img.shields.io/github/license/svyatov/sec_id)](LICENSE.txt)
+# SecId [![Gem Version](https://img.shields.io/gem/v/sec_id)](https://rubygems.org/gems/sec_id) [![Codecov](https://img.shields.io/codecov/c/github/svyatov/sec_id)](https://app.codecov.io/gh/svyatov/sec_id) [![CI](https://github.com/svyatov/sec_id/actions/workflows/main.yml/badge.svg?branch=main)](https://github.com/svyatov/sec_id/actions?query=workflow%3ACI)
 
 > Validate securities identification numbers with ease!
 
@@ -9,14 +9,21 @@
 - [Supported Standards and Usage](#supported-standards-and-usage)
   - [ISIN](#isin) - International Securities Identification Number
   - [CUSIP](#cusip) - Committee on Uniform Securities Identification Procedures
+  - [CEI](#cei) - CUSIP Entity Identifier
   - [SEDOL](#sedol) - Stock Exchange Daily Official List
   - [FIGI](#figi) - Financial Instrument Global Identifier
   - [LEI](#lei) - Legal Entity Identifier
   - [IBAN](#iban) - International Bank Account Number
   - [CIK](#cik) - Central Index Key
   - [OCC](#occ) - Options Clearing Corporation Symbol
+  - [WKN](#wkn) - Wertpapierkennnummer
+  - [Valoren](#valoren) - Swiss Security Number
+  - [CFI](#cfi) - Classification of Financial Instruments
+  - [FISN](#fisn) - Financial Instrument Short Name
 - [Development](#development)
 - [Contributing](#contributing)
+- [Changelog](#changelog)
+- [Versioning](#versioning)
 - [License](#license)
 
 ## Supported Ruby Versions
@@ -28,7 +35,7 @@ Ruby 3.1+ is required.
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'sec_id', '~> 4.3'
+gem 'sec_id', '~> 4.4'
 ```
 
 And then execute:
@@ -47,11 +54,11 @@ gem install sec_id
 
 All identifier classes provide `valid?` and `valid_format?` methods at both class and instance levels.
 
-**Check-digit based identifiers** (ISIN, CUSIP, SEDOL, FIGI, LEI, IBAN) also provide:
+**Check-digit based identifiers** (ISIN, CUSIP, CEI, SEDOL, FIGI, LEI, IBAN) also provide:
 - `restore!` - restores check-digit and returns the full number
 - `check_digit` / `calculate_check_digit` - calculates and returns the check-digit
 
-**Normalization based identifiers** (CIK, OCC) provide instead:
+**Normalization based identifiers** (CIK, OCC, Valoren) provide instead:
 - `normalize!` - pads/formats the identifier to its standard form
 
 ### ISIN
@@ -76,6 +83,26 @@ isin.valid_format?         # => true
 isin.restore!              # => 'US5949181045'
 isin.calculate_check_digit # => 5
 isin.to_cusip              # => #<SecId::CUSIP>
+isin.nsin_type             # => :cusip
+isin.to_nsin               # => #<SecId::CUSIP>
+
+# NSIN extraction for different countries
+SecId::ISIN.new('GB00B02H2F76').nsin_type  # => :sedol
+SecId::ISIN.new('GB00B02H2F76').to_nsin    # => #<SecId::SEDOL>
+SecId::ISIN.new('DE0007164600').nsin_type  # => :wkn
+SecId::ISIN.new('DE0007164600').to_nsin    # => #<SecId::WKN>
+SecId::ISIN.new('CH0012221716').nsin_type  # => :valoren
+SecId::ISIN.new('CH0012221716').to_nsin    # => #<SecId::Valoren>
+SecId::ISIN.new('FR0000120271').nsin_type  # => :generic
+SecId::ISIN.new('FR0000120271').to_nsin    # => '000012027' (raw NSIN string)
+
+# Type-specific conversion methods with validation
+SecId::ISIN.new('GB00B02H2F76').sedol?     # => true
+SecId::ISIN.new('GB00B02H2F76').to_sedol   # => #<SecId::SEDOL>
+SecId::ISIN.new('DE0007164600').wkn?       # => true
+SecId::ISIN.new('DE0007164600').to_wkn     # => #<SecId::WKN>
+SecId::ISIN.new('CH0012221716').valoren?   # => true
+SecId::ISIN.new('CH0012221716').to_valoren # => #<SecId::Valoren>
 ```
 
 ### CUSIP
@@ -103,9 +130,33 @@ cusip.to_isin('US')         # => #<SecId::ISIN>
 cusip.cins?                 # => false
 ```
 
+### CEI
+
+> [CUSIP Entity Identifier](https://www.cusip.com/identifiers.html) - a 10-character alphanumeric code that identifies legal entities in the syndicated loan market.
+
+```ruby
+# class level
+SecId::CEI.valid?('A0BCDEFGH1')       # => true
+SecId::CEI.valid_format?('A0BCDEFGH') # => true
+SecId::CEI.restore!('A0BCDEFGH')      # => 'A0BCDEFGH1'
+SecId::CEI.check_digit('A0BCDEFGH')   # => 1
+
+# instance level
+cei = SecId::CEI.new('A0BCDEFGH1')
+cei.full_number           # => 'A0BCDEFGH1'
+cei.prefix                # => 'A'
+cei.numeric               # => '0'
+cei.entity_id             # => 'BCDEFGH'
+cei.check_digit           # => 1
+cei.valid?                # => true
+cei.valid_format?         # => true
+cei.restore!              # => 'A0BCDEFGH1'
+cei.calculate_check_digit # => 1
+```
+
 ### SEDOL
 
-> [Stock Exchange Daily Official List](https://en.wikipedia.org/wiki/SEDOL) - a 7-character alphanumeric code used in the United Kingdom and Ireland.
+> [Stock Exchange Daily Official List](https://en.wikipedia.org/wiki/SEDOL) - a 7-character alphanumeric code used in the United Kingdom, Ireland, Crown Dependencies (Jersey, Guernsey, Isle of Man), and select British Overseas Territories.
 
 ```ruby
 # class level
@@ -122,6 +173,8 @@ sedol.valid?                # => true
 sedol.valid_format?         # => true
 sedol.restore!              # => 'B0Z52W5'
 sedol.calculate_check_digit # => 5
+sedol.to_isin               # => #<SecId::ISIN> (GB ISIN by default)
+sedol.to_isin('IE')         # => #<SecId::ISIN> (IE ISIN)
 ```
 
 ### FIGI
@@ -259,18 +312,132 @@ occ.normalize!    # => 'X     250620C00050000'
 occ.full_symbol   # => 'X     250620C00050000'
 ```
 
+### WKN
+
+> [Wertpapierkennnummer](https://en.wikipedia.org/wiki/Wertpapierkennnummer) - a 6-character alphanumeric code used to identify securities in Germany.
+
+```ruby
+# class level
+SecId::WKN.valid?('514000')        # => true
+SecId::WKN.valid?('CBK100')        # => true
+SecId::WKN.valid_format?('514000') # => true
+
+# instance level
+wkn = SecId::WKN.new('514000')
+wkn.full_number   # => '514000'
+wkn.identifier    # => '514000'
+wkn.valid?        # => true
+wkn.valid_format? # => true
+wkn.to_s          # => '514000'
+wkn.to_isin       # => #<SecId::ISIN> (DE ISIN)
+```
+
+WKN excludes letters I and O to avoid confusion with digits 1 and 0.
+
+### Valoren
+
+> [Valoren](https://en.wikipedia.org/wiki/Valoren_number) - a numeric identifier for securities in Switzerland, Liechtenstein, and Belgium.
+
+```ruby
+# class level
+SecId::Valoren.valid?('3886335')        # => true
+SecId::Valoren.valid?('24476758')       # => true
+SecId::Valoren.valid?('35514757')       # => true
+SecId::Valoren.valid?('97429325')       # => true
+SecId::Valoren.valid_format?('3886335') # => true
+SecId::Valoren.normalize!('3886335')    # => '003886335'
+
+# instance level
+valoren = SecId::Valoren.new('3886335')
+valoren.full_number   # => '3886335'
+valoren.padding       # => ''
+valoren.identifier    # => '3886335'
+valoren.valid?        # => true
+valoren.valid_format? # => true
+valoren.normalize!    # => '003886335'
+valoren.to_s          # => '003886335'
+valoren.to_isin       # => #<SecId::ISIN> (CH ISIN by default)
+valoren.to_isin('LI') # => #<SecId::ISIN> (LI ISIN)
+```
+
+### CFI
+
+> [Classification of Financial Instruments](https://en.wikipedia.org/wiki/ISO_10962) - a 6-character alphabetic code that classifies financial instruments per ISO 10962.
+
+```ruby
+# class level
+SecId::CFI.valid?('ESXXXX')        # => true
+SecId::CFI.valid?('ESVUFR')        # => true
+SecId::CFI.valid_format?('ESXXXX') # => true
+
+# instance level
+cfi = SecId::CFI.new('ESVUFR')
+cfi.full_number    # => 'ESVUFR'
+cfi.identifier     # => 'ESVUFR'
+cfi.category_code  # => 'E'
+cfi.group_code     # => 'S'
+cfi.category       # => :equity
+cfi.group          # => :common_shares
+cfi.valid?         # => true
+cfi.valid_format?  # => true
+
+# Equity-specific predicates
+cfi.equity?        # => true
+cfi.voting?        # => true
+cfi.restrictions?  # => false
+cfi.fully_paid?    # => true
+cfi.registered?    # => true
+```
+
+CFI validates the category code (position 1) against 14 valid values and the group code (position 2) against valid values for that category. Attribute positions 3-6 accept any letter A-Z, with X meaning "not applicable".
+
+### FISN
+
+> [Financial Instrument Short Name](https://en.wikipedia.org/wiki/ISO_18774) - a human-readable short name for financial instruments per ISO 18774.
+
+```ruby
+# class level
+SecId::FISN.valid?('APPLE INC/SH')        # => true
+SecId::FISN.valid?('apple inc/sh')        # => true (normalized to uppercase)
+SecId::FISN.valid_format?('APPLE INC/SH') # => true
+
+# instance level
+fisn = SecId::FISN.new('APPLE INC/SH')
+fisn.full_number   # => 'APPLE INC/SH'
+fisn.identifier    # => 'APPLE INC/SH'
+fisn.issuer        # => 'APPLE INC'
+fisn.description   # => 'SH'
+fisn.valid?        # => true
+fisn.valid_format? # => true
+fisn.to_s          # => 'APPLE INC/SH'
+```
+
+FISN format: `Issuer Name/Abbreviated Instrument Description` with issuer (1-15 chars) and description (1-19 chars) separated by a forward slash. Character set: uppercase A-Z, digits 0-9, and space.
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies.
-Then, run `rake spec` to run the tests. You can also run `bin/console`
+Then, run `bundle exec rake` to run the tests. You can also run `bin/console`
 for an interactive prompt that will allow you to experiment.
 
 To install this gem onto your local machine, run `bundle exec rake install`.
 
 ## Contributing
 
-Bug reports and pull requests are welcome on
-GitHub at https://github.com/svyatov/sec_id.
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Make your changes and run tests (`bundle exec rake`)
+4. Commit using [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) format (`git commit -m 'feat: add some feature'`)
+5. Push to the branch (`git push origin my-new-feature`)
+6. Create a new Pull Request
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for a detailed history of changes, following [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) format.
+
+## Versioning
+
+This project follows [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html)
 
 ## License
 

data/lib/sec_id/base.rb

@@ -1,49 +1,20 @@
 # frozen_string_literal: true
 
 module SecId
-  # Character-to-digit mapping for Luhn algorithm variants.
-  # Maps alphanumeric characters to digit arrays for multi-digit expansion.
-  # Used by ISIN for check-digit calculation.
-  CHAR_TO_DIGITS = {
-    '0' => 0,      '1' => 1,      '2' => 2,      '3' => 3,      '4' => 4,
-    '5' => 5,      '6' => 6,      '7' => 7,      '8' => 8,      '9' => 9,
-    'A' => [1, 0], 'B' => [1, 1], 'C' => [1, 2], 'D' => [1, 3], 'E' => [1, 4],
-    'F' => [1, 5], 'G' => [1, 6], 'H' => [1, 7], 'I' => [1, 8], 'J' => [1, 9],
-    'K' => [2, 0], 'L' => [2, 1], 'M' => [2, 2], 'N' => [2, 3], 'O' => [2, 4],
-    'P' => [2, 5], 'Q' => [2, 6], 'R' => [2, 7], 'S' => [2, 8], 'T' => [2, 9],
-    'U' => [3, 0], 'V' => [3, 1], 'W' => [3, 2], 'X' => [3, 3], 'Y' => [3, 4], 'Z' => [3, 5],
-    '*' => [3, 6], '@' => [3, 7], '#' => [3, 8]
-  }.freeze
-
-  # Character-to-digit mapping for single-digit conversion.
-  # Maps alphanumeric characters to values 0-38 (A=10, B=11, ..., Z=35, *=36, @=37, #=38).
-  # Used by CUSIP, FIGI, SEDOL, LEI, and IBAN for check-digit calculations.
-  CHAR_TO_DIGIT = {
-    '0' => 0,  '1' => 1,  '2' => 2,  '3' => 3,  '4' =>  4,
-    '5' => 5,  '6' => 6,  '7' => 7,  '8' => 8,  '9' =>  9,
-    'A' => 10, 'B' => 11, 'C' => 12, 'D' => 13, 'E' => 14,
-    'F' => 15, 'G' => 16, 'H' => 17, 'I' => 18, 'J' => 19,
-    'K' => 20, 'L' => 21, 'M' => 22, 'N' => 23, 'O' => 24,
-    'P' => 25, 'Q' => 26, 'R' => 27, 'S' => 28, 'T' => 29,
-    'U' => 30, 'V' => 31, 'W' => 32, 'X' => 33, 'Y' => 34, 'Z' => 35,
-    '*' => 36, '@' => 37, '#' => 38
-  }.freeze
-
   # Base class for securities identifiers that provides a common interface
-  # for validation, check-digit calculation, and parsing.
+  # for validation and parsing.
   #
   # Subclasses must implement:
   # - ID_REGEX constant with named capture groups for parsing
   # - initialize method that calls parse and extracts components
-  # - calculate_check_digit method (only if has_check_digit? returns true)
   #
-  # Subclasses may override:
-  # - has_check_digit? to return false for identifiers without check digits (e.g., CIK, OCC)
-  # - valid_format? for additional format validation beyond regex matching
-  # - to_s for custom string representation
+  # Subclasses with check digits should also include the Checkable concern,
+  # which provides check-digit validation, calculation, and restoration.
   #
   # @example Implementing a check-digit identifier
   #   class MyIdentifier < Base
+  #     include Checkable
+  #
   #     ID_REGEX = /\A(?<identifier>[A-Z]{6})(?<check_digit>\d)?\z/x
   #
   #     def initialize(id)
@@ -60,8 +31,11 @@ module SecId
   #
   # @example Implementing a non-check-digit identifier
   #   class SimpleId < Base
-  #     def has_check_digit?
-  #       false
+  #     ID_REGEX = /\A(?<identifier>[A-Z]{6})\z/x
+  #
+  #     def initialize(id)
+  #       parts = parse(id)
+  #       @identifier = parts[:identifier]
   #     end
   #   end
   class Base
@@ -71,9 +45,6 @@ module SecId
     # @return [String, nil] the main identifier portion (without check digit)
     attr_reader :identifier
 
-    # @return [Integer, nil] the check digit value
-    attr_reader :check_digit
-
     class << self
       # @param id [String] the identifier to validate
       # @return [Boolean]
@@ -86,22 +57,6 @@ module SecId
       def valid_format?(id)
         new(id).valid_format?
       end
-
-      # Restores (calculates) the check digit and returns the full identifier.
-      #
-      # @param id_without_check_digit [String] identifier without or with incorrect check digit
-      # @return [String] the full identifier with correct check digit
-      # @raise [InvalidFormatError] if the identifier format is invalid
-      def restore!(id_without_check_digit)
-        new(id_without_check_digit).restore!
-      end
-
-      # @param id [String] the identifier to calculate check digit for
-      # @return [Integer] the calculated check digit
-      # @raise [InvalidFormatError] if the identifier format is invalid
-      def check_digit(id)
-        new(id).calculate_check_digit
-      end
     end
 
     # Subclasses must override this method.
@@ -112,19 +67,9 @@ module SecId
       raise NotImplementedError
     end
 
-    # Override in subclasses to return false for identifiers without check digits.
-    #
-    # @return [Boolean]
-    def has_check_digit?
-      true
-    end
-
     # @return [Boolean]
     def valid?
-      return valid_format? unless has_check_digit?
-      return false unless valid_format?
-
-      check_digit == calculate_check_digit
+      valid_format?
     end
 
     # Override in subclasses for additional format validation.
@@ -134,38 +79,14 @@ module SecId
       !identifier.nil?
     end
 
-    # @return [String] the full identifier with correct check digit
-    # @raise [InvalidFormatError] if the identifier format is invalid
-    def restore!
-      @check_digit = calculate_check_digit
-      @full_number = to_s
-    end
-
-    # Subclasses must override this method.
-    #
-    # @return [Integer] the calculated check digit
-    # @raise [NotImplementedError] always raised in base class
-    # @raise [InvalidFormatError] if the identifier format is invalid (in subclasses)
-    def calculate_check_digit
-      raise NotImplementedError
-    end
-
     # @return [String]
     def to_s
-      "#{identifier}#{check_digit}"
+      identifier.to_s
     end
     alias to_str to_s
 
     private
 
-    # @raise [InvalidFormatError] if valid_format? returns false
-    # @return [void]
-    def validate_format_for_calculation!
-      return if valid_format?
-
-      raise InvalidFormatError, "#{self.class.name} '#{full_number}' is invalid and check-digit cannot be calculated!"
-    end
-
     # @param sec_id_number [String, #to_s] the identifier to parse
     # @param upcase [Boolean] whether to upcase the input
     # @return [MatchData, Hash] the regex match data or empty hash if no match
@@ -174,41 +95,5 @@ module SecId
       @full_number.upcase! if upcase
       @full_number.match(self.class::ID_REGEX) || {}
     end
-
-    # @return [Array<Integer>] array of digit values
-    # @raise [NotImplementedError] always raised in base class
-    def id_digits
-      raise NotImplementedError
-    end
-
-    # @param char [String] single character to convert
-    # @return [Integer, Array<Integer>] single digit or array of digits
-    def char_to_digits(char)
-      SecId::CHAR_TO_DIGITS.fetch(char)
-    end
-
-    # @param char [String] single character to convert
-    # @return [Integer] numeric value (0-38)
-    def char_to_digit(char)
-      SecId::CHAR_TO_DIGIT.fetch(char)
-    end
-
-    # @param sum [Integer] the sum to calculate check digit from
-    # @return [Integer] check digit (0-9)
-    def mod10(sum)
-      (10 - (sum % 10)) % 10
-    end
-
-    # @param number [Integer] number to split
-    # @return [Integer] sum of tens and units digits
-    def div10mod10(number)
-      (number / 10) + (number % 10)
-    end
-
-    # @param numeric_string [String] numeric string representation
-    # @return [Integer] check digit value (1-98)
-    def mod97(numeric_string)
-      98 - (numeric_string.to_i % 97)
-    end
   end
 end

data/lib/sec_id/cei.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module SecId
+  # CUSIP Entity Identifier (CEI) - a 10-character alphanumeric code that identifies
+  # legal entities in the syndicated loan market.
+  #
+  # Format: 1 alpha + 1 digit + 7 alphanumeric + 1 check digit
+  #
+  # @see https://www.cusip.com/identifiers.html
+  #
+  # @example Validate a CEI
+  #   SecId::CEI.valid?('A0BCDEFGH1')  #=> true
+  class CEI < Base
+    include Checkable
+
+    # Regular expression for parsing CEI components.
+    ID_REGEX = /\A
+      (?<identifier>
+        (?<prefix>[A-Z])
+        (?<numeric>[0-9])
+        (?<entity_id>[A-Z0-9]{7}))
+      (?<check_digit>\d)?
+    \z/x
+
+    # @return [String, nil] the first character (alphabetic)
+    attr_reader :prefix
+
+    # @return [String, nil] the second character (numeric)
+    attr_reader :numeric
+
+    # @return [String, nil] the 7-character entity identifier
+    attr_reader :entity_id
+
+    # @param cei [String] the CEI string to parse
+    def initialize(cei)
+      cei_parts = parse cei
+      @identifier = cei_parts[:identifier]
+      @prefix = cei_parts[:prefix]
+      @numeric = cei_parts[:numeric]
+      @entity_id = cei_parts[:entity_id]
+      @check_digit = cei_parts[:check_digit]&.to_i
+    end
+
+    # @return [Integer] the calculated check digit (0-9)
+    # @raise [InvalidFormatError] if the CEI format is invalid
+    def calculate_check_digit
+      validate_format_for_calculation!
+      mod10(luhn_sum_double_add_double(reversed_digits_single(identifier)))
+    end
+  end
+end