israeli 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 775d9b34a1173bd2bbab00ca4a86f13d8fb340c13ee84d15f5893cdc7d1d6dab
-  data.tar.gz: 6b872c2ebbd7bd5573854e20f79e5bbd1ae5de265a879f370af625a0a2a00d8a
+  metadata.gz: c891a985fc73096b35660dd06031c286ab7bd4bcf4257d1a953ba43d56eb0a8a
+  data.tar.gz: 57a1d7fda2b852f9528d802bec9e8676500551cf117ac7349b6b7a221d8d39d4
 SHA512:
-  metadata.gz: d5d9bc4d5d2b1e874221c84612307533dfc252a077c2fe5c388cfb55ca4283f39e180656353697ac38e65285a1f700bc1786f37791ff8b401f09e1252255852e
-  data.tar.gz: de83f4a136c0f53111ba505cd9165c02fac56e044a2e3d9d2819a9d459e91b4a792c50fd6b8090dc2365cc1b12de0f98d3a45225fb3685b0a2088198205c211f
+  metadata.gz: da33684de117b727b10e8ad788a552469c8add53e58cd8d12d50dc7bcd9d82a61ba05430b753345a8949f369cef9c43089a0d053b5cf3a3233a207c8bd7f50c2
+  data.tar.gz: 2afcff8efddf051796863de345a99f223db86762d0ae4ceb224d0ba4e538d8e1cf3af9a1fa6d260c120e40aadc232037e7ef47d05c23cade2d2eb54747aeb02b

data/CHANGELOG.md

@@ -7,6 +7,52 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.0] - 2025-12-03
+
+### Added
+
+- **Bang Methods** - Exception-raising validation methods
+  - `Israeli.valid_id!` raises `InvalidIdError` with reason
+  - `Israeli.valid_phone!` raises `InvalidPhoneError` with reason
+  - `Israeli.valid_postal_code!` raises `InvalidPostalCodeError` with reason
+  - `Israeli.valid_bank_account!` raises `InvalidBankAccountError` with reason
+
+- **Parse Methods** - Rich result objects for detailed validation
+  - `Israeli.parse_id` returns `IdResult` with formatting
+  - `Israeli.parse_phone` returns `PhoneResult` with type detection
+  - `Israeli.parse_postal_code` returns `PostalCodeResult` with formatting
+  - `Israeli.parse_bank_account` returns `BankAccountResult` with format detection
+
+- **Phone Type Detection**
+  - `Israeli.phone_type` returns `:mobile`, `:landline`, `:voip`, or `nil`
+  - `Israeli::Validators::Phone.detect_type` for direct access
+
+- **Invalid Reason Methods** - Detailed validation failure reasons
+  - `Israeli::Validators::Id.invalid_reason` returns `:blank`, `:wrong_length`, or `:invalid_checksum`
+  - `Israeli::Validators::Phone.invalid_reason` returns `:blank`, `:invalid_format`, or `:wrong_type`
+  - `Israeli::Validators::PostalCode.invalid_reason` returns `:blank` or `:wrong_length`
+  - `Israeli::Validators::BankAccount.invalid_reason` returns `:blank`, `:wrong_length`, `:invalid_format`, or `:invalid_checksum`
+
+- **Missing Facade Methods**
+  - `Israeli.format_postal_code` with `:compact` and `:spaced` styles
+  - `Israeli.format_bank_account` with `:domestic`, `:compact` styles
+
+- **Rails errors.details Support**
+  - All validators now include `reason` in error details
+  - Phone validator includes `expected_type` and `detected_type`
+  - Bank account validator includes `expected_format`
+
+- **Error Classes Hierarchy**
+  - `Israeli::InvalidIdError` for ID validation errors
+  - `Israeli::InvalidPhoneError` for phone validation errors
+  - `Israeli::InvalidPostalCodeError` for postal code validation errors
+  - `Israeli::InvalidBankAccountError` for bank account validation errors
+  - All inherit from `Israeli::InvalidFormatError` with `reason` accessor
+
+### Fixed
+
+- `Id.format()` no longer calls `valid?()` redundantly (minor performance improvement)
+
 ## [0.1.0] - 2025-12-03
 
 ### Added

data/README.md

@@ -178,6 +178,104 @@ bundle exec rubocop        # Run linter
 bundle exec rake           # Run both
 ```
 
+## Advanced Usage
+
+### Bang Methods (Exception-raising)
+
+For fail-fast validation, use bang methods that raise exceptions:
+
+```ruby
+Israeli.valid_id!("123456789")
+# => raises Israeli::InvalidIdError with reason: :invalid_checksum
+
+Israeli.valid_phone!("021234567", type: :mobile)
+# => raises Israeli::InvalidPhoneError with reason: :wrong_type
+
+# Catch specific errors
+begin
+  Israeli.valid_id!(user_input)
+rescue Israeli::InvalidIdError => e
+  puts "Invalid ID: #{e.reason}"  # => :blank, :wrong_length, or :invalid_checksum
+end
+```
+
+### Parse Methods (Rich Result Objects)
+
+For more detailed validation information, use parse methods:
+
+```ruby
+# Phone parsing with type detection
+result = Israeli.parse_phone("0501234567")
+result.valid?   # => true
+result.type     # => :mobile
+result.mobile?  # => true
+result.formatted(style: :dashed)        # => "050-123-4567"
+result.formatted(style: :international) # => "+972-501234567"
+
+# ID parsing
+result = Israeli.parse_id("123456789")
+result.valid?  # => false
+result.reason  # => :invalid_checksum
+
+# Bank account with format detection
+result = Israeli.parse_bank_account("IL620108000000099999999")
+result.iban?      # => true
+result.domestic?  # => false
+result.format     # => :iban
+```
+
+### Phone Type Detection
+
+Detect phone number type without validation:
+
+```ruby
+Israeli.phone_type("0501234567")  # => :mobile
+Israeli.phone_type("021234567")   # => :landline
+Israeli.phone_type("0721234567")  # => :voip
+Israeli.phone_type("invalid")     # => nil
+```
+
+### Invalid Reason Detection
+
+Get detailed validation failure reasons:
+
+```ruby
+Israeli::Validators::Id.invalid_reason("123456789")  # => :invalid_checksum
+Israeli::Validators::Id.invalid_reason("")           # => :blank
+Israeli::Validators::Phone.invalid_reason("021234567", type: :mobile)  # => :wrong_type
+```
+
+### Rails errors.details Support
+
+Validators include structured error details for Rails 5+:
+
+```ruby
+# Model definition
+class Person < ApplicationRecord
+  validates :id_number, israeli_id: true
+  validates :mobile_phone, israeli_phone: { type: :mobile }
+end
+
+# Usage
+person = Person.new(id_number: "123456789", mobile_phone: "021234567")
+person.valid?  # => false
+
+person.errors.details[:id_number]
+# => [{error: :invalid, reason: :invalid_checksum}]
+
+person.errors.details[:mobile_phone]
+# => [{error: :invalid, reason: :wrong_type, expected_type: :mobile, detected_type: :landline}]
+```
+
+## Roadmap
+
+Future versions may include:
+
+- [ ] **Business/Company Number (Mispar Osek/Hevra)** - 9-digit with checksum validation
+- [ ] **Vehicle License Plates** - Format validation for Israeli plates
+- [ ] **Non-Profit (Amuta) Numbers** - 580-prefix validation
+- [ ] **Luhn Checksum Generator** - Generate valid IDs for testing
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/dpaluy/israeli.

data/lib/israeli/active_model/israeli_bank_account_validator.rb

@@ -26,9 +26,12 @@ class IsraeliBankAccountValidator < ActiveModel::EachValidator
     account_format = options[:format] || :any
     return if Israeli::Validators::BankAccount.valid?(value, format: account_format)
 
+    reason = Israeli::Validators::BankAccount.invalid_reason(value, format: account_format)
     record.errors.add(
       attribute,
-      options[:message] || :invalid
+      options[:message] || :invalid,
+      reason: reason,
+      expected_format: account_format
     )
   end
 end

data/lib/israeli/active_model/israeli_id_validator.rb

@@ -20,9 +20,11 @@ class IsraeliIdValidator < ActiveModel::EachValidator
 
     return if Israeli::Validators::Id.valid?(value)
 
+    reason = Israeli::Validators::Id.invalid_reason(value)
     record.errors.add(
       attribute,
-      options[:message] || :invalid
+      options[:message] || :invalid,
+      reason: reason
     )
   end
 end

data/lib/israeli/active_model/israeli_phone_validator.rb

@@ -31,9 +31,14 @@ class IsraeliPhoneValidator < ActiveModel::EachValidator
     phone_type = options[:type] || :any
     return if Israeli::Validators::Phone.valid?(value, type: phone_type)
 
+    reason = Israeli::Validators::Phone.invalid_reason(value, type: phone_type)
+    detected_type = Israeli::Validators::Phone.detect_type(value)
     record.errors.add(
       attribute,
-      options[:message] || :invalid
+      options[:message] || :invalid,
+      reason: reason,
+      expected_type: phone_type,
+      detected_type: detected_type
     )
   end
 end

data/lib/israeli/active_model/israeli_postal_code_validator.rb

@@ -20,9 +20,11 @@ class IsraeliPostalCodeValidator < ActiveModel::EachValidator
 
     return if Israeli::Validators::PostalCode.valid?(value)
 
+    reason = Israeli::Validators::PostalCode.invalid_reason(value)
     record.errors.add(
       attribute,
-      options[:message] || :invalid
+      options[:message] || :invalid,
+      reason: reason
     )
   end
 end

data/lib/israeli/errors.rb

@@ -7,7 +7,7 @@ module Israeli
   #
   # @example Handling errors
   #   begin
-  #     Israeli.format_id!("invalid")
+  #     Israeli.valid_id!("invalid")
   #   rescue Israeli::Error => e
   #     puts "Validation failed: #{e.message}"
   #   end
@@ -16,7 +16,28 @@ module Israeli
   # Raised when input format is invalid for the requested validation type.
   #
   # @example
-  #   Israeli.format_id!("abc")
-  #   # => Israeli::InvalidFormatError: ID must contain only digits
-  class InvalidFormatError < Error; end
+  #   Israeli.valid_id!("123456789")
+  #   # => Israeli::InvalidFormatError: Invalid Israeli ID
+  class InvalidFormatError < Error
+    attr_reader :reason
+
+    # @param message [String] Human-readable error message
+    # @param reason [Symbol, nil] Machine-readable reason code
+    def initialize(message = nil, reason: nil)
+      @reason = reason
+      super(message)
+    end
+  end
+
+  # Raised when an Israeli ID number is invalid.
+  class InvalidIdError < InvalidFormatError; end
+
+  # Raised when an Israeli phone number is invalid.
+  class InvalidPhoneError < InvalidFormatError; end
+
+  # Raised when an Israeli postal code is invalid.
+  class InvalidPostalCodeError < InvalidFormatError; end
+
+  # Raised when an Israeli bank account number is invalid.
+  class InvalidBankAccountError < InvalidFormatError; end
 end

data/lib/israeli/result.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+module Israeli
+  # Result object returned by parse methods.
+  #
+  # Provides a rich object with validation status, original/normalized values,
+  # and formatting methods for a cleaner API than simple booleans.
+  #
+  # @example Using a parse result
+  #   result = Israeli.parse_id("123456782")
+  #   result.valid?      # => true
+  #   result.formatted   # => "123456782"
+  #   result.original    # => "123456782"
+  #
+  # @example Invalid result
+  #   result = Israeli.parse_id("123456789")
+  #   result.valid?      # => false
+  #   result.invalid?    # => true
+  #   result.reason      # => :invalid_checksum
+  class Result
+    attr_reader :original, :normalized, :reason
+
+    # @param original [String, nil] Original input value
+    # @param normalized [String, nil] Normalized/sanitized value
+    # @param valid [Boolean] Whether the value is valid
+    # @param reason [Symbol, nil] Reason for invalidity
+    def initialize(original:, normalized:, valid:, reason: nil)
+      @original = original
+      @normalized = normalized
+      @valid = valid
+      @reason = reason
+    end
+
+    # @return [Boolean] true if the value is valid
+    def valid?
+      @valid
+    end
+
+    # @return [Boolean] true if the value is invalid
+    def invalid?
+      !@valid
+    end
+
+    # @return [String, nil] The formatted value, or nil if invalid
+    def formatted
+      return nil unless valid?
+
+      @normalized
+    end
+
+    # @return [String] String representation
+    def to_s
+      formatted || ""
+    end
+
+    # @return [String, nil] The normalized value (alias for formatted)
+    def value
+      formatted
+    end
+  end
+
+  # Result object for ID validation with formatting.
+  class IdResult < Result
+    # @return [String, nil] 9-digit formatted ID
+    def formatted
+      return nil unless valid?
+
+      @normalized
+    end
+  end
+
+  # Result object for phone validation with type detection and formatting.
+  class PhoneResult < Result
+    attr_reader :type
+
+    # @param type [Symbol, nil] Detected phone type (:mobile, :landline, :voip)
+    def initialize(original:, normalized:, valid:, reason: nil, type: nil)
+      super(original: original, normalized: normalized, valid: valid, reason: reason)
+      @type = type
+    end
+
+    # @return [Boolean] true if this is a mobile phone
+    def mobile?
+      type == :mobile
+    end
+
+    # @return [Boolean] true if this is a landline phone
+    def landline?
+      type == :landline
+    end
+
+    # @return [Boolean] true if this is a VoIP phone
+    def voip?
+      type == :voip
+    end
+
+    # Format the phone number.
+    #
+    # @param style [Symbol] :dashed, :international, or :compact
+    # @return [String, nil] Formatted phone or nil if invalid
+    def formatted(style: :dashed)
+      return nil unless valid?
+
+      Validators::Phone.format(@normalized, style: style)
+    end
+  end
+
+  # Result object for postal code validation with formatting.
+  class PostalCodeResult < Result
+    # Format the postal code.
+    #
+    # @param style [Symbol] :compact or :spaced
+    # @return [String, nil] Formatted postal code or nil if invalid
+    def formatted(style: :compact)
+      return nil unless valid?
+
+      Validators::PostalCode.format(@normalized, style: style)
+    end
+  end
+
+  # Result object for bank account validation with format detection.
+  class BankAccountResult < Result
+    attr_reader :format
+
+    # @param format [Symbol, nil] Detected format (:domestic or :iban)
+    def initialize(original:, normalized:, valid:, reason: nil, format: nil)
+      super(original: original, normalized: normalized, valid: valid, reason: reason)
+      @format = format
+    end
+
+    # @return [Boolean] true if this is a domestic account
+    def domestic?
+      format == :domestic
+    end
+
+    # @return [Boolean] true if this is an IBAN
+    def iban?
+      format == :iban
+    end
+
+    # Format the bank account.
+    #
+    # @param style [Symbol] :domestic, :compact, or :iban
+    # @return [String, nil] Formatted bank account or nil if invalid
+    def formatted(style: :domestic)
+      return nil unless valid?
+
+      Validators::BankAccount.format(@original, style: style)
+    end
+  end
+end

data/lib/israeli/validators/bank_account.rb

@@ -71,6 +71,56 @@ module Israeli
         numeric.to_i % 97 == 1
       end
 
+      # Returns the reason why a bank account is invalid.
+      #
+      # @param value [String, nil] The bank account to check
+      # @param format [Symbol] Format to validate: :domestic, :iban, or :any
+      # @return [Symbol, nil] Reason code or nil if valid
+      #   - :blank - Input is nil or empty
+      #   - :wrong_length - Incorrect number of digits/characters
+      #   - :invalid_checksum - IBAN mod 97 checksum failed
+      #   - :invalid_format - Does not match domestic or IBAN pattern
+      #
+      # @example
+      #   Israeli::Validators::BankAccount.invalid_reason("123")  # => :wrong_length
+      def self.invalid_reason(value, format: :any)
+        return :blank if value.nil? || value.to_s.strip.empty?
+
+        case format
+        when :domestic then domestic_invalid_reason(value)
+        when :iban then iban_invalid_reason(value)
+        when :any then any_format_invalid_reason(value)
+        else :invalid_format
+        end
+      end
+
+      def self.domestic_invalid_reason(value)
+        digits = Sanitizer.digits_only(value)
+        return :blank if digits.nil? || digits.empty?
+
+        digits.length == 13 ? nil : :wrong_length
+      end
+      private_class_method :domestic_invalid_reason
+
+      def self.iban_invalid_reason(value)
+        normalized = value.to_s.gsub(/\s/, "").upcase
+        return :wrong_length unless normalized.length == 23
+        return :invalid_format unless normalized.match?(/\AIL\d{21}\z/)
+
+        valid_iban?(normalized) ? nil : :invalid_checksum
+      end
+      private_class_method :iban_invalid_reason
+
+      def self.any_format_invalid_reason(value)
+        digits = Sanitizer.digits_only(value)
+        normalized = value.to_s.gsub(/\s/, "").upcase
+
+        return nil if digits&.length == 13 || valid_iban?(normalized)
+
+        :invalid_format
+      end
+      private_class_method :any_format_invalid_reason
+
       # Formats a bank account to a specified style.
       #
       # @param value [String, nil] The bank account to format

data/lib/israeli/validators/id.rb

@@ -37,6 +37,29 @@ module Israeli
         Luhn.valid?(padded)
       end
 
+      # Returns the reason why an ID is invalid.
+      #
+      # @param value [String, Integer, nil] The ID number to check
+      # @return [Symbol, nil] Reason code or nil if valid
+      #   - :blank - Input is nil or empty
+      #   - :wrong_length - Not 9 digits after padding
+      #   - :invalid_checksum - Luhn checksum failed
+      #
+      # @example
+      #   Israeli::Validators::Id.invalid_reason("123456789") # => :invalid_checksum
+      #   Israeli::Validators::Id.invalid_reason("")          # => :blank
+      #   Israeli::Validators::Id.invalid_reason("123456782") # => nil (valid)
+      def self.invalid_reason(value)
+        digits = Sanitizer.digits_only(value)
+        return :blank if digits.nil? || digits.empty?
+
+        padded = digits.rjust(9, "0")
+        return :wrong_length unless padded.match?(/\A\d{9}\z/)
+        return :invalid_checksum unless Luhn.valid?(padded)
+
+        nil
+      end
+
       # Formats an Israeli ID to standard 9-digit format.
       #
       # @param value [String, Integer, nil] The ID number to format
@@ -50,7 +73,7 @@ module Israeli
         return nil if digits.nil? || digits.empty?
 
         padded = digits.rjust(9, "0")
-        return nil unless valid?(padded)
+        return nil unless padded.match?(/\A\d{9}\z/) && Luhn.valid?(padded)
 
         padded
       end

data/lib/israeli/validators/phone.rb

@@ -74,6 +74,51 @@ module Israeli
         value.match?(VOIP_PATTERN)
       end
 
+      # Detects the type of phone number.
+      #
+      # @param value [String, nil] The phone number to check
+      # @return [Symbol, nil] :mobile, :landline, :voip, or nil if invalid
+      #
+      # @example
+      #   Israeli::Validators::Phone.detect_type("0501234567")  # => :mobile
+      #   Israeli::Validators::Phone.detect_type("021234567")   # => :landline
+      #   Israeli::Validators::Phone.detect_type("0721234567")  # => :voip
+      #   Israeli::Validators::Phone.detect_type("invalid")     # => nil
+      def self.detect_type(value)
+        normalized = Sanitizer.normalize_phone(value)
+        return nil if normalized.nil? || normalized.empty?
+
+        return :mobile if mobile?(normalized)
+        return :landline if landline?(normalized)
+        return :voip if voip?(normalized)
+
+        nil
+      end
+
+      # Returns the reason why a phone number is invalid.
+      #
+      # @param value [String, nil] The phone number to check
+      # @param type [Symbol] Type to validate: :mobile, :landline, :voip, or :any
+      # @return [Symbol, nil] Reason code or nil if valid
+      #   - :blank - Input is nil or empty
+      #   - :invalid_format - Does not match any Israeli phone pattern
+      #   - :wrong_type - Valid phone but wrong type (e.g., landline when mobile expected)
+      #
+      # @example
+      #   Israeli::Validators::Phone.invalid_reason("abc")         # => :invalid_format
+      #   Israeli::Validators::Phone.invalid_reason("021234567", type: :mobile) # => :wrong_type
+      def self.invalid_reason(value, type: :any)
+        normalized = Sanitizer.normalize_phone(value)
+        return :blank if normalized.nil? || normalized.empty?
+
+        detected = detect_type(normalized)
+        return :invalid_format if detected.nil?
+
+        return nil if type == :any || type == detected
+
+        :wrong_type
+      end
+
       # Formats a phone number.
       #
       # @param value [String, nil] The phone number to format

data/lib/israeli/validators/postal_code.rb

@@ -31,6 +31,25 @@ module Israeli
         digits.match?(/\A\d{7}\z/)
       end
 
+      # Returns the reason why a postal code is invalid.
+      #
+      # @param value [String, nil] The postal code to check
+      # @return [Symbol, nil] Reason code or nil if valid
+      #   - :blank - Input is nil or empty
+      #   - :wrong_length - Not exactly 7 digits
+      #
+      # @example
+      #   Israeli::Validators::PostalCode.invalid_reason("123")     # => :wrong_length
+      #   Israeli::Validators::PostalCode.invalid_reason("")        # => :blank
+      #   Israeli::Validators::PostalCode.invalid_reason("2610101") # => nil (valid)
+      def self.invalid_reason(value)
+        digits = Sanitizer.digits_only(value)
+        return :blank if digits.nil? || digits.empty?
+        return :wrong_length unless digits.match?(/\A\d{7}\z/)
+
+        nil
+      end
+
       # Formats a postal code to standard representation.
       #
       # @param value [String, nil] The postal code to format

data/lib/israeli/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Israeli
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/israeli.rb

@@ -4,6 +4,7 @@ require_relative "israeli/version"
 require_relative "israeli/errors"
 require_relative "israeli/luhn"
 require_relative "israeli/sanitizer"
+require_relative "israeli/result"
 
 # Main namespace for the Israeli validators gem.
 #
@@ -20,8 +21,8 @@ require_relative "israeli/sanitizer"
 # @see Israeli::Validators::Phone
 # @see Israeli::Validators::PostalCode
 # @see Israeli::Validators::BankAccount
-module Israeli
-  class << self
+module Israeli # rubocop:disable Metrics/ModuleLength
+  class << self # rubocop:disable Metrics/ClassLength
     # Validates an Israeli ID number (Mispar Zehut).
     #
     # @param value [String, Integer] The ID number to validate
@@ -61,6 +62,18 @@ module Israeli
       Validators::Phone.valid?(value, type: type)
     end
 
+    # Detects the type of phone number.
+    #
+    # @param value [String] The phone number to check
+    # @return [Symbol, nil] :mobile, :landline, :voip, or nil if invalid
+    #
+    # @example
+    #   Israeli.phone_type("0501234567")  # => :mobile
+    #   Israeli.phone_type("021234567")   # => :landline
+    def phone_type(value)
+      Validators::Phone.detect_type(value)
+    end
+
     # Validates an Israeli bank account number.
     #
     # @param value [String] The bank account to validate
@@ -90,6 +103,202 @@ module Israeli
     def format_phone(value, style: :dashed)
       Validators::Phone.format(value, style: style)
     end
+
+    # Formats an Israeli postal code.
+    #
+    # @param value [String] The postal code to format
+    # @param style [Symbol] Format style: :compact or :spaced
+    # @return [String, nil] Formatted postal code or nil if invalid
+    def format_postal_code(value, style: :compact)
+      Validators::PostalCode.format(value, style: style)
+    end
+
+    # Formats an Israeli bank account number.
+    #
+    # @param value [String] The bank account to format
+    # @param style [Symbol] Format style: :domestic, :compact, or :iban
+    # @return [String, nil] Formatted bank account or nil if invalid
+    def format_bank_account(value, style: :domestic)
+      Validators::BankAccount.format(value, style: style)
+    end
+
+    # Bang Methods - raise exceptions on invalid input
+    # These are useful when you want to fail fast rather than check booleans
+
+    # Validates an Israeli ID number, raising an error if invalid.
+    #
+    # @param value [String, Integer] The ID number to validate
+    # @return [true] Always returns true if valid
+    # @raise [Israeli::InvalidIdError] if the ID is invalid
+    #
+    # @example
+    #   Israeli.valid_id!("123456782")  # => true
+    #   Israeli.valid_id!("123456789")  # => raises InvalidIdError
+    def valid_id!(value)
+      return true if valid_id?(value)
+
+      raise InvalidIdError.new("Invalid Israeli ID", reason: Validators::Id.invalid_reason(value))
+    end
+
+    # Validates an Israeli phone number, raising an error if invalid.
+    #
+    # @param value [String] The phone number to validate
+    # @param type [Symbol] Type of phone: :mobile, :landline, :voip, or :any
+    # @return [true] Always returns true if valid
+    # @raise [Israeli::InvalidPhoneError] if the phone is invalid
+    def valid_phone!(value, type: :any)
+      return true if valid_phone?(value, type: type)
+
+      reason = Validators::Phone.invalid_reason(value, type: type)
+      raise InvalidPhoneError.new("Invalid Israeli phone number", reason: reason)
+    end
+
+    # Validates an Israeli postal code, raising an error if invalid.
+    #
+    # @param value [String] The postal code to validate
+    # @return [true] Always returns true if valid
+    # @raise [Israeli::InvalidPostalCodeError] if the postal code is invalid
+    def valid_postal_code!(value)
+      return true if valid_postal_code?(value)
+
+      raise InvalidPostalCodeError.new("Invalid Israeli postal code", reason: Validators::PostalCode.invalid_reason(value))
+    end
+
+    # Validates an Israeli bank account, raising an error if invalid.
+    #
+    # @param value [String] The bank account to validate
+    # @param format [Symbol] Format: :domestic, :iban, or :any
+    # @return [true] Always returns true if valid
+    # @raise [Israeli::InvalidBankAccountError] if the bank account is invalid
+    def valid_bank_account!(value, format: :any)
+      return true if valid_bank_account?(value, format: format)
+
+      reason = Validators::BankAccount.invalid_reason(value, format: format)
+      raise InvalidBankAccountError.new("Invalid Israeli bank account", reason: reason)
+    end
+
+    # Parse Methods - return rich result objects
+    # These provide more detailed information than simple boolean validation
+
+    # Parses an Israeli ID number and returns a result object.
+    #
+    # @param value [String, Integer] The ID number to parse
+    # @return [Israeli::IdResult] Result object with validation status and formatting
+    #
+    # @example
+    #   result = Israeli.parse_id("123456782")
+    #   result.valid?     # => true
+    #   result.formatted  # => "123456782"
+    #
+    # @example Invalid ID
+    #   result = Israeli.parse_id("123456789")
+    #   result.valid?  # => false
+    #   result.reason  # => :invalid_checksum
+    def parse_id(value)
+      digits = Sanitizer.digits_only(value)
+      normalized = digits&.rjust(9, "0")
+      valid = Validators::Id.valid?(value)
+      reason = valid ? nil : Validators::Id.invalid_reason(value)
+
+      IdResult.new(
+        original: value,
+        normalized: normalized,
+        valid: valid,
+        reason: reason
+      )
+    end
+
+    # Parses an Israeli phone number and returns a result object.
+    #
+    # @param value [String] The phone number to parse
+    # @return [Israeli::PhoneResult] Result object with type detection and formatting
+    #
+    # @example
+    #   result = Israeli.parse_phone("0501234567")
+    #   result.valid?   # => true
+    #   result.type     # => :mobile
+    #   result.mobile?  # => true
+    #   result.formatted(style: :dashed)  # => "050-123-4567"
+    def parse_phone(value)
+      normalized = Sanitizer.normalize_phone(value)
+      valid = Validators::Phone.valid?(value)
+      phone_type = Validators::Phone.detect_type(value)
+      reason = valid ? nil : Validators::Phone.invalid_reason(value)
+
+      PhoneResult.new(
+        original: value,
+        normalized: normalized,
+        valid: valid,
+        reason: reason,
+        type: phone_type
+      )
+    end
+
+    # Parses an Israeli postal code and returns a result object.
+    #
+    # @param value [String] The postal code to parse
+    # @return [Israeli::PostalCodeResult] Result object with validation and formatting
+    #
+    # @example
+    #   result = Israeli.parse_postal_code("2610101")
+    #   result.valid?    # => true
+    #   result.formatted # => "2610101"
+    #   result.formatted(style: :spaced)  # => "26101 01"
+    def parse_postal_code(value)
+      digits = Sanitizer.digits_only(value)
+      valid = Validators::PostalCode.valid?(value)
+      reason = valid ? nil : Validators::PostalCode.invalid_reason(value)
+
+      PostalCodeResult.new(
+        original: value,
+        normalized: digits,
+        valid: valid,
+        reason: reason
+      )
+    end
+
+    # Parses an Israeli bank account and returns a result object.
+    #
+    # @param value [String] The bank account to parse
+    # @return [Israeli::BankAccountResult] Result object with format detection
+    #
+    # @example
+    #   result = Israeli.parse_bank_account("4985622815429")
+    #   result.valid?     # => true
+    #   result.domestic?  # => true
+    #   result.formatted  # => "49-856-22815429"
+    def parse_bank_account(value)
+      valid = Validators::BankAccount.valid?(value)
+      reason = valid ? nil : Validators::BankAccount.invalid_reason(value)
+      detected_format = detect_bank_format(value) if valid
+
+      BankAccountResult.new(
+        original: value,
+        normalized: normalize_bank_value(value, detected_format),
+        valid: valid,
+        reason: reason,
+        format: detected_format
+      )
+    end
+
+    private
+
+    def detect_bank_format(value)
+      digits = Sanitizer.digits_only(value)
+      normalized = value.to_s.gsub(/\s/, "").upcase
+
+      return :domestic if Validators::BankAccount.valid_domestic?(digits)
+      return :iban if Validators::BankAccount.valid_iban?(normalized)
+
+      nil
+    end
+
+    def normalize_bank_value(value, detected_format)
+      case detected_format
+      when :iban then value.to_s.gsub(/\s/, "").upcase
+      else Sanitizer.digits_only(value)
+      end
+    end
   end
 end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: israeli
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - dpaluy
@@ -34,6 +34,7 @@ files:
 - lib/israeli/errors.rb
 - lib/israeli/luhn.rb
 - lib/israeli/railtie.rb
+- lib/israeli/result.rb
 - lib/israeli/sanitizer.rb
 - lib/israeli/validators/bank_account.rb
 - lib/israeli/validators/id.rb
@@ -65,7 +66,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.0
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Validation utilities for Israeli identifiers (ID, phone, postal code, bank
   account).