itu-e164 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: '0469c614c83a4f49532e5f80645b5a44bf33b873c2bb7332852fd909ef421882'
+  data.tar.gz: 4ec2f4e91a83688670affd7d08dbe77908d615304783d286018ffe6bac43ad39
+SHA512:
+  metadata.gz: a81387d155baa30b4b8878dc7ab5cd9748305e3e102f90409d614b6030f71b0a3b08aa2ac3caedd477925a3c9331970991209dfca84c45fc2708c3bcc28a62f1
+  data.tar.gz: b729eb1db3f931748581ba1d24962d2b9abbdd1e8317fa9a3c843ba50073ff1dae4a9a3249a89d90fdbdc008c7344289c2b149759011706667f08fbefdfd1954

data/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## 0.1.0
+
+- Add strict canonical validation for the geographic-area structure in
+  Recommendation ITU-T E.164 (02/2026).
+- Add a dated ITU geographic country-code assignment snapshot.
+- Return immutable, structured results suitable for existing validation layers.
+- Recognize assigned non-geographic E.164 country codes and reject them with an
+  explicit profile-mismatch error.
+

data/LICENSE.txt

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Olisti contributors
+
+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

@@ -0,0 +1,141 @@
+# itu-e164
+
+`itu-e164` is a dependency-free Ruby utility for strict, auditable validation of
+canonical geographic-area numbers against Recommendation ITU-T E.164 (02/2026).
+It is deliberately not a Rails validator and does not contact a carrier.
+
+## Installation
+
+Add the gem to your bundle:
+
+```ruby
+gem "itu-e164"
+```
+
+Then run `bundle install`.
+
+## Usage
+
+```ruby
+require "itu/e164"
+
+result = ITU::E164.check("+393331234567")
+
+result.conformant?       # => true
+result.country_code      # => "39"
+result.national_number   # => "3331234567"
+result.category          # => :geographic
+result.standard_version  # => "02/2026"
+result.dataset_version   # => "itu-t-e164-2026-07-15"
+```
+
+For a boolean:
+
+```ruby
+ITU::E164.conformant?("+393331234567") # => true
+```
+
+For exception-based control flow:
+
+```ruby
+result = ITU::E164.check!("+393331234567")
+
+begin
+  ITU::E164.check!("0039 333 123 4567")
+rescue ITU::E164::InvalidNumber => error
+  error.result.error_codes # => [:invalid_representation]
+end
+```
+
+The accepted representation is intentionally strict: a `String` containing `+`
+followed by ASCII decimal digits. Spaces, punctuation, `00`, URI parameters, and
+extensions are rejected. Normalize user input before this boundary and store
+extensions separately.
+
+## Existing validation layers
+
+The result is designed to be consumed without an Active Record dependency:
+
+```ruby
+result = ITU::E164.check(value)
+
+unless result.conformant?
+  errors.add(:phone_number, result.errors.map(&:message).join(", "))
+end
+```
+
+With Twilio Verify, use this gem before sending a verification:
+
+```ruby
+result = ITU::E164.check(candidate)
+return validation_failure(result.errors) unless result.conformant?
+
+twilio_verify(candidate)
+```
+
+The responsibilities stay separate:
+
+- `itu-e164` checks canonical representation, E.164 length and field structure,
+  and the assigned geographic country-code snapshot.
+- Twilio Verify checks whether a user controls a reachable endpoint.
+
+## Exact scope
+
+For `profile: :geographic` (the only profile in 0.1), a conformant result means:
+
+- the input is canonical leading-plus notation;
+- the E.164 digit sequence contains at most 15 digits;
+- it starts with an assigned one-, two-, or three-digit geographic country code;
+- at least one digit remains as the national (significant) number.
+
+This is the complete E.164-level structure for the geographic category. E.164
+leaves national destination-code and subscriber-number details to national
+numbering authorities.
+
+Accordingly, this gem does **not** claim that:
+
+- the national number range is allocated or currently active;
+- the number is mobile, SMS-capable, reachable, or owned by a user;
+- a national trunk prefix was correctly removed;
+- one of E.164's seven non-geographic categories satisfies its service-specific
+  numbering recommendation.
+
+Assigned non-geographic country codes are recognized, but fail the geographic
+profile with `:profile_mismatch`. Spare or unknown codes fail with
+`:country_code_unassigned`.
+
+## Results and errors
+
+`ITU::E164.check` always returns an immutable `ITU::E164::Result`. Invalid input
+has one or more immutable `ITU::E164::ValidationError` values:
+
+```ruby
+result = ITU::E164.check("+80012345678")
+
+result.conformant? # => false
+result.category    # => :global_service
+result.error_codes # => [:profile_mismatch]
+result.to_h
+```
+
+Current error codes are:
+
+- `:not_a_string`
+- `:invalid_representation`
+- `:too_long`
+- `:country_code_unassigned`
+- `:missing_national_number`
+- `:profile_mismatch`
+
+Branch on error codes, not English messages.
+
+## Versioning and updates
+
+The recommendation version and assignment dataset are exposed separately because
+a stable numbering structure can coexist with changing assignments. See
+[SOURCES.md](SOURCES.md) for provenance and the update procedure.
+
+## License
+
+The gem is available under the MIT License.
+

data/SOURCES.md

@@ -0,0 +1,46 @@
+# Normative basis and dataset provenance
+
+`itu-e164` separates two things that evolve independently:
+
+1. The numbering-plan structure comes from Recommendation ITU-T E.164 (02/2026).
+2. Country-code assignment status comes from ITU-T service publications and is
+   represented by a dated data snapshot.
+
+## Structure
+
+- [Recommendation ITU-T E.164 (02/2026)](https://www.itu.int/rec/T-REC-E.164-202602-I/en)
+- [Recommendation ITU-T E.164.1 (02/2026)](https://www.itu.int/rec/T-REC-E.164.1-202602-I/en)
+- [Recommendation ITU-T E.123](https://www.itu.int/rec/T-REC-E.123/en), for the
+  leading-plus international notation accepted by this library
+
+The implemented geographic profile follows these structural constraints:
+
+- an international E.164 number contains decimal digits and has at most 15 digits;
+- a geographic country code has one, two, or three digits;
+- the national (significant) number occupies the remaining digits;
+- international and national prefixes are not part of the number.
+
+## Assignment snapshot
+
+- Dataset identifier: `itu-t-e164-2026-07-15`
+- Snapshot date: 15 July 2026
+- [List of Recommendation ITU-T E.164 assigned country codes, baseline at
+  15 December 2016](https://www.itu.int/dms_pub/itu-t/opb/sp/t-sp-e.164d-2016-pdf-e.pdf)
+- Numbered amendments through [ITU Operational Bulletin No. 1344,
+  15 July 2026](https://www.itu.int/pub/T-SP-OB.1344-2026)
+- [ITU National Numbering Plans index](https://www.itu.int/oth/T0202.aspx?lang=en&parent=T0202),
+  cross-checked on 28 July 2026
+
+The constants are derived assignment facts, not reproduced recommendation text
+or diagrams.
+
+## Updating the snapshot
+
+Review each ITU Operational Bulletin after No. 1344 for amendments to the assigned
+country-code list. Apply additions, returns, re-designations, and status changes to
+`lib/itu/e164/data/v2026.rb`, advance `DATASET_VERSION`, and add regression tests
+for every changed code.
+
+Do not infer assignment status from a calling library or a carrier API. Assignment
+status is an ITU-controlled dataset.
+

data/lib/itu/e164/checker.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require_relative "data/v2026"
+require_relative "result"
+require_relative "validation_error"
+
+module ITU
+  module E164
+    class Checker
+      ASCII_INTERNATIONAL_NUMBER = /\A\+[0-9]+\z/
+      MAXIMUM_DIGITS = 15
+      SUPPORTED_PROFILES = [:geographic].freeze
+      ERROR_MESSAGES = {
+        not_a_string: "must be a String",
+        invalid_representation: "must be + followed by ASCII decimal digits",
+        too_long: "must contain at most 15 digits after +",
+        country_code_unassigned: "must start with an assigned geographic country code",
+        missing_national_number: "must include a national significant number after the country code",
+        profile_mismatch: "belongs to a non-geographic E.164 category"
+      }.freeze
+
+      def initialize(profile:)
+        unless SUPPORTED_PROFILES.include?(profile)
+          raise ArgumentError, "unsupported profile #{profile.inspect}; expected :geographic"
+        end
+
+        @profile = profile
+      end
+
+      def call(input)
+        return result(input:, errors: [error(:not_a_string)]) unless input.is_a?(String)
+
+        stable_input = immutable(input)
+        unless ASCII_INTERNATIONAL_NUMBER.match?(stable_input)
+          return result(input: stable_input, errors: [error(:invalid_representation)])
+        end
+
+        digits = immutable(stable_input.delete_prefix("+"))
+        errors = []
+        errors << error(:too_long) if digits.length > MAXIMUM_DIGITS
+
+        category, country_code = resolve_country_code(digits)
+        national_number = resolve_national_number(digits, category, country_code)
+
+        if category.nil?
+          errors << error(:country_code_unassigned)
+        elsif category != @profile
+          errors << error(:profile_mismatch)
+        elsif national_number.empty?
+          errors << error(:missing_national_number)
+        end
+
+        result(
+          input: stable_input,
+          digits:,
+          canonical: errors.empty? ? stable_input : nil,
+          category:,
+          country_code:,
+          national_number:,
+          errors:
+        )
+      end
+
+      private
+
+      def resolve_country_code(digits)
+        geographic_code = Data::V2026::GEOGRAPHIC_COUNTRY_CODES.find do |code|
+          digits.start_with?(code)
+        end
+        return [:geographic, immutable(geographic_code)] if geographic_code
+
+        non_geographic_code, category = Data::V2026::NON_GEOGRAPHIC_COUNTRY_CODES.find do |code, _|
+          digits.start_with?(code)
+        end
+        return [category, immutable(non_geographic_code)] if non_geographic_code
+
+        [nil, nil]
+      end
+
+      def resolve_national_number(digits, category, country_code)
+        return nil unless category == :geographic
+
+        immutable(digits.delete_prefix(country_code))
+      end
+
+      def result(input:, errors:, **attributes)
+        defaults = {
+          input:,
+          profile: @profile,
+          standard_version: E164::STANDARD_VERSION,
+          dataset_version: Data::V2026::DATASET_VERSION,
+          digits: nil,
+          canonical: nil,
+          category: nil,
+          country_code: nil,
+          national_number: nil
+        }
+
+        Result.new(**defaults, **attributes, errors: errors.freeze)
+      end
+
+      def immutable(value)
+        value&.dup&.freeze
+      end
+
+      def error(code)
+        ValidationError.new(code:, message: ERROR_MESSAGES.fetch(code))
+      end
+    end
+  end
+end

data/lib/itu/e164/data/v2026.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module ITU
+  module E164
+    module Data
+      module V2026
+        DATASET_VERSION = "itu-t-e164-2026-07-15"
+
+        GEOGRAPHIC_COUNTRY_CODES = %w[
+          1 7
+          20 27 30 31 32 33 34 36 39 40 41 43 44 45 46 47 48 49
+          51 52 53 54 55 56 57 58 60 61 62 63 64 65 66 81 82 84 86
+          90 91 92 93 94 95 98
+          211 212 213 216 218 220 221 222 223 224 225 226 227 228 229
+          230 231 232 233 234 235 236 237 238 239 240 241 242 243 244
+          245 246 247 248 249 250 251 252 253 254 255 256 257 258 260
+          261 262 263 264 265 266 267 268 269 290 291 297 298 299
+          350 351 352 353 354 355 356 357 358 359 370 371 372 373 374
+          375 376 377 378 380 381 382 383 385 386 387 389
+          420 421 423
+          500 501 502 503 504 505 506 507 508 509
+          590 591 592 593 594 595 596 597 598 599
+          670 672 673 674 675 676 677 678 679 680 681 682 683 685 686
+          687 688 689 690 691 692
+          850 852 853 855 856 880 886
+          960 961 962 963 964 965 966 967 968 970 971 972 973 974 975
+          976 977 992 993 994 995 996 998
+        ].freeze
+
+        NON_GEOGRAPHIC_COUNTRY_CODES = {
+          "800" => :global_service,
+          "808" => :global_service,
+          "870" => :other_global_service,
+          "881" => :global_satellite_service,
+          "882" => :network,
+          "883" => :iot_m2m,
+          "979" => :global_service,
+          "991" => :trial
+        }.freeze
+      end
+    end
+  end
+end

data/lib/itu/e164/invalid_number.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module ITU
+  module E164
+    class InvalidNumber < ArgumentError
+      attr_reader :result
+
+      def initialize(result)
+        @result = result
+        super(result.errors.map(&:message).join(", "))
+      end
+    end
+  end
+end

data/lib/itu/e164/result.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module ITU
+  module E164
+    Result = ::Data.define(
+      :input,
+      :profile,
+      :standard_version,
+      :dataset_version,
+      :digits,
+      :canonical,
+      :category,
+      :country_code,
+      :national_number,
+      :errors
+    ) do
+      def conformant?
+        errors.empty?
+      end
+
+      def failure?
+        !conformant?
+      end
+
+      def error_codes
+        errors.map(&:code).freeze
+      end
+
+      def to_h
+        {
+          input:,
+          profile:,
+          standard_version:,
+          dataset_version:,
+          digits:,
+          canonical:,
+          category:,
+          country_code:,
+          national_number:,
+          conformant: conformant?,
+          errors: errors.map(&:to_h)
+        }
+      end
+    end
+  end
+end

data/lib/itu/e164/validation_error.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module ITU
+  module E164
+    ValidationError = ::Data.define(:code, :message) do
+      def to_h
+        {code:, message:}
+      end
+    end
+  end
+end

data/lib/itu/e164/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module ITU
+  module E164
+    VERSION = "0.1.0"
+  end
+end

data/lib/itu/e164.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative "e164/checker"
+require_relative "e164/invalid_number"
+require_relative "e164/version"
+
+module ITU
+  module E164
+    STANDARD_VERSION = "02/2026"
+    PROFILE = :geographic
+
+    module_function
+
+    def check(input, profile: PROFILE)
+      Checker.new(profile:).call(input)
+    end
+
+    def check!(input, profile: PROFILE)
+      result = check(input, profile:)
+      raise InvalidNumber, result unless result.conformant?
+
+      result
+    end
+
+    def conformant?(input, profile: PROFILE)
+      check(input, profile:).conformant?
+    end
+  end
+end

metadata

@@ -0,0 +1,105 @@
+--- !ruby/object:Gem::Specification
+name: itu-e164
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Maurizio De Magnis
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-07-28 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.2'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.64'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.64'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
+description: |
+  A dependency-free Ruby utility that checks canonical geographic-area numbers
+  against Recommendation ITU-T E.164 (02/2026) and a dated ITU country-code
+  assignment snapshot.
+email: root@olisti.co
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- SOURCES.md
+- lib/itu/e164.rb
+- lib/itu/e164/checker.rb
+- lib/itu/e164/data/v2026.rb
+- lib/itu/e164/invalid_number.rb
+- lib/itu/e164/result.rb
+- lib/itu/e164/validation_error.rb
+- lib/itu/e164/version.rb
+homepage: https://source.olisti.co/olisti.co/itu-e164
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.10
+signing_key:
+specification_version: 4
+summary: Strict ITU-T E.164 (02/2026) geographic-number conformance for Ruby
+test_files: []