cpf-dv 0.0.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b3602764d5f2d48821c34fad754e596eaceae640ec7ee8f4909be10d256d5437
-  data.tar.gz: 3aba3575cf38941dd1a0cc98d8e0630e08bba5fb293987107b9d27043c721f7d
+  metadata.gz: c4c1b2490462860148180946616219c920d96507426d6fc6c848dc1dca7b74c2
+  data.tar.gz: 80fa518ec814ef85f84b4c76a78105e895e24acaf3ae88f95a86e830286f67b1
 SHA512:
-  metadata.gz: 86350f26cd5c36d3c64318a26f38aae28bc4e4709f5e0e6a58c35d925abff7444642e8c4e7b5678c36482ede6b8f52774cf17901f6a2cfe9bb6a66905fc0c723
-  data.tar.gz: d9f042ab9f7a0e44b2e246ab1afa3f1f70d0b9912d7bbe4764e5c140fa86639833a5805a58a6552bff8e3e6567d6bbd310aee64ad291590489baa54e558d9c69
+  metadata.gz: cae6be7695a8892a7ea1b1b6398d05fc2a8e67a7133040e7da356d53635092a82ad427046ad6e632f1aa1a270390b96148f7c7bbb72273850da60593d54fec6a
+  data.tar.gz: bf145363a9df1a42912a13b19d495a27d80098f988aa6f2b643eb2d90e95b8172c4bf8d0a447683fdb8dd3b84dd12c49240b7944927801f00d59098a8a62b1a1

data/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 Julio L. Muller
+
+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,288 @@
+cpf-dv for Ruby
+
+[Gem Version](https://rubygems.org/gems/cpf-dv)
+[Downloads Count](https://rubygems.org/gems/cpf-dv)
+[Ruby Version](https://www.ruby-lang.org/)
+[Test Status](https://github.com/LacusSolutions/br-utils-ruby/actions)
+[Last Update Date](https://github.com/LacusSolutions/br-utils-ruby)
+[Project License](https://github.com/LacusSolutions/br-utils-ruby/blob/main/LICENSE)
+
+> 🌎 [Acessar documentação em português](https://github.com/LacusSolutions/br-utils-ruby/blob/main/packages/cpf-dv/README.pt.md)
+
+A Ruby utility to calculate check digits on CPF (Brazilian Individual's Taxpayer ID).
+
+## Ruby Support
+
+
+| Ruby 3.2  | Ruby 3.3  | Ruby 3.4  |
+| --------- | --------- | --------- |
+| Passing ✔ | Passing ✔ | Passing ✔ |
+
+
+
+
+## Features
+
+- ✅ **Flexible input**: Accepts `String` or `Array` of strings
+- ✅ **Format agnostic**: Strips non-numeric characters from string input
+- ✅ **Auto-expansion**: Multi-character strings in arrays are joined and parsed like a single string
+- ✅ **Input validation**: Rejects ineligible CPFs (9 identical digits in the base — repeated-digit pattern)
+- ✅ **Lazy evaluation**: Check digits are calculated only when accessed (via methods)
+- ✅ **Caching**: Calculated values are cached for subsequent access
+- ✅ **Minimal dependencies**: Only [`lacus-utils`](https://rubygems.org/gems/lacus-utils)
+- ✅ **Error handling**: API misuse vs domain errors with a `CpfDV::Error` marker for library-wide rescue
+
+
+
+## Installation
+
+Install the gem directly:
+
+```bash
+gem install cpf-dv
+```
+
+Or add it to your `Gemfile` and run `bundle install`:
+
+```ruby
+gem 'cpf-dv'
+```
+
+
+
+## Require
+
+```ruby
+require 'cpf-dv'
+```
+
+
+
+## Quick Start
+
+```ruby
+require 'cpf-dv'
+
+check_digits = CpfDV::CpfCheckDigits.new('054496519')
+
+check_digits.first   # => '1'
+check_digits.second  # => '0'
+check_digits.both    # => '10'
+check_digits.cpf     # => '05449651910'
+```
+
+
+
+## Usage
+
+The main resource of this package is the class `CpfDV::CpfCheckDigits`. Through an instance, you access CPF check-digit information:
+
+- `initialize`: `CpfDV::CpfCheckDigits.new(cpf_input)` — `cpf_input` must be a `String` or an `Array` of strings. After sanitization, the value must have 9–11 digits (formatting stripped from strings). Only the **first 9** digits are used as the base; if you pass 10 or 11 digits (e.g. a full CPF including prior check digits), digits 10–11 are **ignored** and the check digits are recalculated. There are **no options**, keyword arguments, or configuration objects — the constructor takes only the CPF input.
+- `first`: First check digit (10th digit of the full CPF). Lazy, cached.
+- `second`: Second check digit (11th digit of the full CPF). Lazy, cached.
+- `both`: Both check digits concatenated as a string.
+- `cpf`: The complete CPF as a string of 11 digits (9 base digits + 2 check digits).
+
+
+
+### Input formats
+
+The `CpfCheckDigits` class accepts multiple input formats:
+
+**String input:** plain digits or formatted CPF (e.g. `054.496.519-10`, `123.456.789`). Non-numeric characters are removed. Leading zeros are preserved.
+
+**Array of strings:** each element must be a string; values are concatenated and then parsed like a single string (e.g. `['0','5','4',…]`, `['054','496','519']`, `['054496519']`). Non-string elements are not allowed.
+
+```ruby
+require 'cpf-dv'
+
+# String — plain, formatted, or with existing check digits (only first 9 digits used)
+CpfDV::CpfCheckDigits.new('054496519')
+CpfDV::CpfCheckDigits.new('054.496.519-10')
+CpfDV::CpfCheckDigits.new('05449651910')
+
+# Array of strings — single- or multi-character elements
+CpfDV::CpfCheckDigits.new(%w[0 5 4 4 9 6 5 1 9])
+CpfDV::CpfCheckDigits.new(%w[054 496 519])
+CpfDV::CpfCheckDigits.new(%w[054496519])
+```
+
+
+
+### Error handling
+
+Errors fall into two categories:
+
+| Category | Meaning |
+|---|---|
+| **API misuse** | The caller invoked the library incorrectly (wrong type). Detectable from the call shape. |
+| **Domain error** | The call was structurally correct, but a value violates a business rule (length, eligibility). |
+
+Every custom error includes the `CpfDV::Error` marker module. Domain failures (`InvalidLengthError`, `ValidationError`) inherit from `CpfDV::DomainError` (`RangeError`).
+
+#### Summary
+
+| Class | Inherits from | Category | Trigger condition |
+|---|---|---|---|
+| `CpfDV::TypeMismatchError` | `TypeError` (+ `include Error`) | API misuse | Argument has the wrong data type |
+| `CpfDV::InvalidLengthError` | `CpfDV::DomainError` | Domain error | Sanitized length is not 9–11 |
+| `CpfDV::ValidationError` | `CpfDV::DomainError` | Domain error | First 9 digits are all identical (repeated-digit pattern) |
+
+#### `CpfDV::Error` (marker module)
+
+- **Inheritance:** module marker mixed into every library error via `include` (not a class).
+- **Category:** N/A (rescue target only) — not a failure mode by itself.
+- **When it is raised:** Never raised directly; included by every custom error the library raises.
+- **Example:** N/A
+- **How to rescue it:**
+
+```ruby
+rescue CpfDV::Error
+  # everything this library raises
+```
+
+#### `CpfDV::DomainError`
+
+- **Inheritance:** `CpfDV::DomainError < RangeError` (includes `CpfDV::Error`)
+- **Category:** Domain error — ancestor for numeric/length domain failures.
+- **When it is raised:** Not raised directly; prefer raising a leaf subclass.
+- **Example:** Prefer `raise CpfDV::InvalidLengthError` over raising `DomainError` directly.
+- **How to rescue it:**
+
+```ruby
+rescue CpfDV::DomainError
+  # InvalidLengthError, ValidationError, and any other DomainError subclass
+```
+
+#### `CpfDV::TypeMismatchError`
+
+- **Inheritance:** `CpfDV::TypeMismatchError < TypeError` (includes `CpfDV::Error`)
+- **Category:** API misuse — the caller passed a value of the wrong type.
+- **When it is raised:** Raised when the CPF input is not a `String` or an `Array` of strings (or an array contains a non-string element).
+- **Example:**
+
+```ruby
+CpfDV::CpfCheckDigits.new(12_345_678_901) # raises CpfDV::TypeMismatchError
+```
+
+- **How to rescue it:**
+
+```ruby
+rescue CpfDV::TypeMismatchError
+  # this library's type-contract violation
+
+rescue TypeError
+  # native type errors, including this library's TypeMismatchError
+```
+
+#### `CpfDV::InvalidLengthError`
+
+- **Inheritance:** `CpfDV::InvalidLengthError < CpfDV::DomainError < RangeError` (includes `CpfDV::Error`)
+- **Category:** Domain error — a collection or string length violates a business rule.
+- **When it is raised:** Raised when the sanitized CPF input does not contain 9 to 11 digits.
+- **Example:**
+
+```ruby
+CpfDV::CpfCheckDigits.new('12345678') # raises CpfDV::InvalidLengthError
+```
+
+- **How to rescue it:**
+
+```ruby
+rescue CpfDV::InvalidLengthError
+  # this exact length violation
+
+rescue CpfDV::DomainError
+  # RangeError-rooted domain failures from this library
+```
+
+#### `CpfDV::ValidationError`
+
+- **Inheritance:** `CpfDV::ValidationError < CpfDV::DomainError < RangeError` (includes `CpfDV::Error`)
+- **Category:** Domain error — a value fails a non-numeric, non-length domain rule.
+- **When it is raised:** Raised when the first 9 digits are all the same digit (repeated-digit pattern).
+- **Example:**
+
+```ruby
+CpfDV::CpfCheckDigits.new('111111111') # raises CpfDV::ValidationError
+```
+
+- **How to rescue it:**
+
+```ruby
+rescue CpfDV::ValidationError
+  # this exact domain validation failure
+
+rescue CpfDV::DomainError
+  # RangeError-rooted domain failures from this library
+```
+
+#### Rescue granularity
+
+```ruby
+# 1) Single native class — catches type misuse from this library (and other TypeErrors).
+rescue TypeError
+  # CpfDV::TypeMismatchError and any other TypeError (library or not)
+
+# 2) CpfDV::DomainError — catches business-rule violations under DomainError.
+rescue CpfDV::DomainError
+  # CpfDV::InvalidLengthError, CpfDV::ValidationError, and other DomainError subclasses
+
+# 3) CpfDV::Error — catches everything the library raises.
+rescue CpfDV::Error
+  # every custom error that includes CpfDV::Error
+
+# 4) Specific leaf class — catches only that exact failure mode.
+rescue CpfDV::InvalidLengthError
+  # only CpfDV::InvalidLengthError
+```
+
+Notable attributes on raised errors:
+
+- `TypeMismatchError`: `actual_input`, `actual_type`, `expected_type`
+- `InvalidLengthError`: `actual_input`, `evaluated_input`, `min_expected_length`, `max_expected_length`
+- `ValidationError`: `actual_input`, `reason`
+
+
+
+### Other available resources
+
+After `require 'cpf-dv'`:
+
+- `CpfDV::CPF_MIN_LENGTH`: `9`
+- `CpfDV::CPF_MAX_LENGTH`: `11`
+- **Errors**: see above (`CpfDV::Error`, `DomainError`, and raised leaves)
+
+
+
+## Calculation algorithm
+
+The package calculates CPF check digits using the official Brazilian modulo-11 algorithm:
+
+1. **First check digit (10th position):** apply to the first **9** base digits; weights **10, 9, 8, 7, 6, 5, 4, 3, 2** (left to right); let `remainder = 11 - (sum(digit × weight) % 11)`. The digit is `0` if `remainder > 9`, otherwise `remainder`.
+2. **Second check digit (11th position):** apply to the first 9 base digits **plus** the first check digit; weights **11, 10, 9, 8, 7, 6, 5, 4, 3, 2** (left to right); same formula for `remainder`.
+
+
+
+## Contribution & Support
+
+We welcome contributions! Please see our [Contributing Guidelines](https://github.com/LacusSolutions/br-utils-ruby/blob/main/CONTRIBUTING.md) for details. If you find this project helpful, please consider:
+
+- ⭐ Starring the repository
+- 🤝 Contributing to the codebase
+- 💡 [Suggesting new features](https://github.com/LacusSolutions/br-utils-ruby/issues)
+- 🐛 [Reporting bugs](https://github.com/LacusSolutions/br-utils-ruby/issues)
+
+
+
+## License
+
+This project is licensed under the MIT License — see the [LICENSE](https://github.com/LacusSolutions/br-utils-ruby/blob/main/LICENSE) file for details.
+
+## Changelog
+
+See [CHANGELOG](./CHANGELOG.md) for a list of changes and version history.
+
+---
+
+Made with ❤️ by [Lacus Solutions](https://github.com/LacusSolutions)

data/src/cpf-dv/cpf_check_digits.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+require_relative 'errors'
+
+module CpfDV
+  # Minimum number of digits required for the CPF check digits calculation.
+  CPF_MIN_LENGTH = 9
+
+  # Maximum number of digits accepted as input for the CPF check digits
+  # calculation.
+  CPF_MAX_LENGTH = 11
+
+  DELTA_FACTOR = '0'.ord
+  DIGIT_CHARS = '0123456789'
+
+  private_constant :DELTA_FACTOR, :DIGIT_CHARS
+
+  # Calculates and exposes CPF check digits from a valid base input.
+  #
+  # Validates length and rejects repeated-digit sequences.
+  #
+  # @example
+  #   check_digits = CpfDV::CpfCheckDigits.new('054496519')
+  #   check_digits.first   # => '1'
+  #   check_digits.second  # => '0'
+  #   check_digits.both    # => '10'
+  #   check_digits.cpf     # => '05449651910'
+  class CpfCheckDigits
+    # Creates a calculator for the given CPF base (9 to 11 digits).
+    #
+    # @param cpf_input [String, Array<String>] digits with or without formatting,
+    #   or an array of strings
+    # @raise [TypeMismatchError] when input is not a +String+ or +Array<String>+
+    # @raise [InvalidLengthError] when digit count is not between 9 and 11
+    # @raise [ValidationError] when all first 9 digits are the same (repeated
+    #   digits, e.g. +777.777.777-...+)
+    def initialize(cpf_input)
+      parsed_input = parse_input(cpf_input)
+
+      validate_length(parsed_input, cpf_input)
+      validate_non_repeated_digits(parsed_input, cpf_input)
+
+      @cpf_digits = parsed_input[0, CPF_MIN_LENGTH]
+      @cached_first_digit = nil
+      @cached_second_digit = nil
+    end
+
+    # First check digit (10th digit of the full CPF).
+    #
+    # @return [String] a single numeric character (+"0"+–+"9"+)
+    def first
+      @cached_first_digit = _calculate(@cpf_digits) if @cached_first_digit.nil?
+
+      DIGIT_CHARS[@cached_first_digit]
+    end
+
+    # Second check digit (11th digit of the full CPF).
+    #
+    # @return [String] a single numeric character (+"0"+–+"9"+)
+    def second
+      @cached_second_digit = _calculate([*@cpf_digits, first]) if @cached_second_digit.nil?
+
+      DIGIT_CHARS[@cached_second_digit]
+    end
+
+    # Both check digits concatenated (10th and 11th digits).
+    #
+    # @return [String] two-character numeric string
+    def both
+      first + second
+    end
+
+    # Full 11-digit CPF (base 9 digits concatenated with the 2 check digits).
+    #
+    # @return [String] 11-digit CPF
+    def cpf
+      @cpf_digits.join + both
+    end
+
+    # Protected (not private) so test spy subclasses can override and call +super+.
+    # Leading underscore matches the cross-language helper name (`_calculate`).
+    protected
+
+    # Computes a single check digit using the standard CPF modulo-11 algorithm.
+    #
+    # @param cpf_sequence [Array<String>] digit characters used in the weighted sum
+    # @return [Integer] check digit in the range 0–9
+    def _calculate(cpf_sequence)
+      factor = cpf_sequence.length + 1
+      sum_result = 0
+
+      cpf_sequence.each do |digit_char|
+        sum_result += (digit_char.ord - DELTA_FACTOR) * factor
+        factor -= 1
+      end
+
+      remainder = 11 - (sum_result % 11)
+
+      remainder > 9 ? 0 : remainder
+    end
+
+    private
+
+    # Parses a string or an array of strings into digit characters.
+    #
+    # @param cpf_input [Object] candidate CPF input
+    # @return [Array<String>] digit characters
+    # @raise [TypeMismatchError] when input is not a +String+ or +Array<String>+
+    def parse_input(cpf_input)
+      return parse_string_input(cpf_input) if cpf_input.is_a?(String)
+      return parse_array_input(cpf_input) if cpf_input.is_a?(Array)
+
+      raise TypeMismatchError.new(cpf_input, 'string or string[]')
+    end
+
+    # Strips non-digit characters and keeps the remainder as characters.
+    #
+    # @param cpf_string [String] raw or formatted CPF string
+    # @return [Array<String>] digit characters
+    def parse_string_input(cpf_string)
+      result = []
+
+      cpf_string.each_char do |char|
+        code = char.ord
+        result << char if code.between?(48, 57)
+      end
+
+      result
+    end
+
+    # Concatenates an array of strings and parses the result.
+    #
+    # @param cpf_array [Array] candidate array of string chunks
+    # @return [Array<String>] digit characters
+    # @raise [TypeMismatchError] when input is not a +String+ or +Array<String>+
+    def parse_array_input(cpf_array)
+      return [] if cpf_array.empty?
+
+      raise TypeMismatchError.new(cpf_array, 'string or string[]') unless cpf_array.all?(String)
+
+      parse_string_input(cpf_array.join)
+    end
+
+    # Ensures digit count is between {CPF_MIN_LENGTH} and {CPF_MAX_LENGTH}.
+    #
+    # @param cpf_digits [Array<String>] normalized digit characters
+    # @param original_input [String, Array<String>] original caller input
+    # @raise [InvalidLengthError] when digit count is not between 9 and 11
+    def validate_length(cpf_digits, original_input)
+      digits_count = cpf_digits.length
+
+      return if digits_count.between?(CPF_MIN_LENGTH, CPF_MAX_LENGTH)
+
+      raise InvalidLengthError.new(
+        original_input,
+        cpf_digits.join,
+        CPF_MIN_LENGTH,
+        CPF_MAX_LENGTH
+      )
+    end
+
+    # Rejects inputs where all first 9 digits are the same.
+    #
+    # @param cpf_digits [Array<String>] normalized digit characters
+    # @param original_input [String, Array<String>] original caller input
+    # @raise [ValidationError] when all first 9 digits are the same (repeated
+    #   digits, e.g. +777.777.777-...+)
+    def validate_non_repeated_digits(cpf_digits, original_input)
+      first_char = cpf_digits[0]
+      return unless cpf_digits[1, CPF_MIN_LENGTH - 1].all? { |char| char == first_char }
+
+      raise ValidationError.new(
+        original_input,
+        'Repeated digits are not considered valid.'
+      )
+    end
+  end
+end

data/src/cpf-dv/errors.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'lacus-utils'
+
+module CpfDV
+  # Formats the original input for inclusion in an exception message.
+  module FormatActualInput
+    module_function
+
+    # @param actual_input [Object] the original input value
+    # @return [String] a quoted string, or compact JSON for arrays
+    def call(actual_input)
+      return "\"#{actual_input}\"" if actual_input.is_a?(String)
+
+      JSON.generate(actual_input)
+    end
+  end
+  private_constant :FormatActualInput
+
+  # Marker module mixed into every custom error raised by this library.
+  #
+  # Use +rescue CpfDV::Error+ to catch every library error regardless of native
+  # ancestry.
+  module Error; end
+
+  # API misuse error raised when an argument's runtime type does not match the
+  # type required by the API contract.
+  #
+  # Raised when the input provided to {CpfCheckDigits} is not a +String+ or
+  # +Array<String>+. The error message includes both the actual type of the
+  # input and the expected type.
+  class TypeMismatchError < TypeError
+    include Error
+
+    # @return [Object] the offending input value
+    attr_reader :actual_input
+
+    # @return [String] human-readable type of {#actual_input}
+    attr_reader :actual_type
+
+    # @return [String] description of the expected type
+    attr_reader :expected_type
+
+    # @param actual_input [Object] the offending input value (the whole array
+    #   when a non-string element is found)
+    # @param expected_type [String] description of the expected type (e.g.
+    #   +"string or string[]"+)
+    def initialize(actual_input, expected_type)
+      actual_type = LacusUtils.describe_type(actual_input)
+
+      super("CPF input must be of type #{expected_type}. Got #{actual_type}.")
+      @actual_input = actual_input
+      @actual_type = actual_type
+      @expected_type = expected_type
+    end
+  end
+
+  # Domain error ancestor for business-rule failures (length, validation, and
+  # other domain leaves). Prefer raising a leaf subclass.
+  class DomainError < RangeError
+    include Error
+  end
+
+  # Domain error raised when a string, array, or other collection has a length
+  # outside the bounds required by the domain rule.
+  #
+  # A valid CPF input must contain between 9 and 11 digits. The error message
+  # distinguishes between the original input and the evaluated one (which strips
+  # punctuation characters).
+  class InvalidLengthError < DomainError
+    # @return [String, Array<String>] the original input
+    attr_reader :actual_input
+
+    # @return [String] the digits-only string used for counting
+    attr_reader :evaluated_input
+
+    # @return [Integer] minimum expected length (9)
+    attr_reader :min_expected_length
+
+    # @return [Integer] maximum expected length (11)
+    attr_reader :max_expected_length
+
+    # @param actual_input [String, Array<String>] the original input
+    # @param evaluated_input [String] the digits-only string
+    # @param min_expected_length [Integer] minimum expected length
+    # @param max_expected_length [Integer] maximum expected length
+    def initialize(actual_input, evaluated_input, min_expected_length, max_expected_length)
+      super(build_message(actual_input, evaluated_input, min_expected_length, max_expected_length))
+      @actual_input = actual_input
+      @evaluated_input = evaluated_input
+      @min_expected_length = min_expected_length
+      @max_expected_length = max_expected_length
+    end
+
+    private
+
+    def build_message(actual_input, evaluated_input, min_len, max_len)
+      fmt_actual = FormatActualInput.call(actual_input)
+      fmt_evaluated =
+        if actual_input == evaluated_input
+          evaluated_input.length.to_s
+        else
+          "#{evaluated_input.length} in \"#{evaluated_input}\""
+        end
+
+      "CPF input #{fmt_actual} does not contain #{min_len} to #{max_len} digits. " \
+        "Got #{fmt_evaluated}."
+    end
+  end
+
+  # Domain error raised when a value has a valid type and length but violates a
+  # validation rule that is not length-based (e.g. repeated digits).
+  #
+  # This is a business-logic exception; callers should catch it and handle it
+  # appropriately.
+  class ValidationError < DomainError
+    # @return [String, Array<String>] the original input
+    attr_reader :actual_input
+
+    # @return [String] human-readable reason why the input is invalid
+    attr_reader :reason
+
+    # @param actual_input [String, Array<String>] the original input
+    # @param reason [String] human-readable reason why the input is invalid
+    def initialize(actual_input, reason)
+      super("CPF input #{FormatActualInput.call(actual_input)} is invalid. #{reason}")
+      @actual_input = actual_input
+      @reason = reason
+    end
+  end
+end

data/src/cpf-dv/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
-module CpfDv
-  VERSION = '0.0.0'
+module CpfDV
+  VERSION = '1.0.0'
 end

data/src/cpf-dv.rb

@@ -1,9 +1,35 @@
 # frozen_string_literal: true
 
 require_relative 'cpf-dv/version'
+require_relative 'cpf-dv/errors'
+require_relative 'cpf-dv/cpf_check_digits'
 
-module CpfDv
-  def self.hello
-    'cpf-dv'
-  end
+# Check-digit calculation for Brazilian CPF (numeric format).
+#
+# Errors fall into two categories:
+#
+# - *API misuse* — the caller invoked the library incorrectly (wrong type).
+#   Raised as {CpfDV::TypeMismatchError} (+TypeError+).
+# - *Domain errors* — the call shape was valid, but a value violates a business
+#   rule (invalid length, repeated digits). Length failures raise
+#   {CpfDV::InvalidLengthError}; other domain failures raise
+#   {CpfDV::ValidationError} (both under {CpfDV::DomainError} / +RangeError+).
+#
+# Every custom error includes the {CpfDV::Error} marker module so consumers can
+# +rescue CpfDV::Error+ for a library-wide catch.
+#
+# Public API:
+#
+# - {CpfDV::CpfCheckDigits}
+# - {CpfDV::CPF_MIN_LENGTH}, {CpfDV::CPF_MAX_LENGTH}
+# - Error marker {CpfDV::Error}; domain ancestor {CpfDV::DomainError};
+#   raised leaves {CpfDV::TypeMismatchError}, {CpfDV::InvalidLengthError},
+#   {CpfDV::ValidationError}
+#
+# @example
+#   require 'cpf-dv'
+#
+#   check_digits = CpfDV::CpfCheckDigits.new('054496519')
+#   check_digits.cpf # => '05449651910'
+module CpfDV
 end

metadata

@@ -1,30 +1,54 @@
 --- !ruby/object:Gem::Specification
 name: cpf-dv
 version: !ruby/object:Gem::Version
-  version: 0.0.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Julio L. Muller
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-04 00:00:00.000000000 Z
-dependencies: []
-description: Utility to calculate and verify CPF check digits.
+date: 2026-07-21 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: lacus-utils
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.1.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: 2.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.1.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: 2.0.0
+description: Utility to calculate check digits on CPF (Brazilian Individual's Taxpayer
+  ID)
 email:
 - juliolmuller@outlook.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- LICENSE
+- README.md
 - src/cpf-dv.rb
+- src/cpf-dv/cpf_check_digits.rb
+- src/cpf-dv/errors.rb
 - src/cpf-dv/version.rb
 homepage: https://github.com/LacusSolutions/br-utils-ruby
 licenses:
 - MIT
 metadata:
   source_code_uri: https://github.com/LacusSolutions/br-utils-ruby
-  changelog_uri: https://github.com/LacusSolutions/br-utils-ruby/blob/main/CHANGELOG.md
   rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []
@@ -34,7 +58,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.2'
+      version: '3.1'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
@@ -44,5 +68,5 @@ requirements: []
 rubygems_version: 3.4.19
 signing_key:
 specification_version: 4
-summary: Check-digit calculation for CPF (Brazilian personal ID)
+summary: Check-digit calculation for CPF (Brazilian Individual's Taxpayer ID)
 test_files: []