Como Criar uma Gem Ruby para Encapsular Chamadas à API de CPF

# Estrutura de diretórios
# cpfhub/
# lib/
# cpfhub/
# client.rb
# configuration.rb
# errors.rb
# response.rb
# version.rb
# cpfhub.rb
# spec/
# cpfhub/
# client_spec.rb
# spec_helper.rb
# cpfhub.gemspec
# Gemfile
# README.md

# cpfhub.gemspec
Gem::Specification.new do |spec|
    spec.name = "cpfhub"
    spec.version = CpfHub::VERSION
    spec.authors = ["Seu Nome"]
    spec.email = ["seu@email.com"]
    spec.summary = "Cliente Ruby para a API do CPFHub"
    spec.description = "Gem para consultar e validar CPFs via API do CPFHub"
    spec.homepage = "https://github.com/seu-usuario/cpfhub-ruby"
    spec.license = "MIT"
    spec.required_ruby_version = ">= 3.0"

    spec.add_dependency "faraday", "~> 2.0"
    spec.add_dependency "faraday-retry", "~> 2.0"

    spec.add_development_dependency "rspec", "~> 3.12"
    spec.add_development_dependency "webmock", "~> 3.18"
end

# lib/cpfhub/version.rb
module CpfHub
    VERSION = "1.0.0"
end

# lib/cpfhub/configuration.rb
module CpfHub
    class Configuration
    attr_accessor :api_key, :base_url, :timeout, :open_timeout,
    :max_retries, :retry_delay, :logger

    def initialize
    @api_key = ENV["CPFHUB_API_KEY"]
    @base_url = "https://api.cpfhub.io"
    @timeout = 10
    @open_timeout = 5
    @max_retries = 3
    @retry_delay = 1
    @logger = Logger.new($stdout)
    end
    end
end

# lib/cpfhub.rb
require "cpfhub/version"
require "cpfhub/configuration"
require "cpfhub/errors"
require "cpfhub/response"
require "cpfhub/client"

module CpfHub
    class << self
    attr_accessor :configuration

    def configure
    self.configuration ||= Configuration.new
    yield(configuration)
    end

    def client
    @client ||= Client.new
    end

    def consultar(cpf)
    client.consultar(cpf)
    end

    def reset!
    @client = nil
    @configuration = nil
    end
    end
end

# lib/cpfhub/errors.rb
module CpfHub
    class Error < StandardError; end
    class ConfigurationError < Error; end
    class InvalidCpfError < Error; end
    class AuthenticationError < Error; end
    class NotFoundError < Error; end
    class RateLimitError < Error; end
    class ServerError < Error; end
    class TimeoutError < Error; end
end

# lib/cpfhub/response.rb
module CpfHub
    class Response
    attr_reader :cpf, :name, :name_upper, :gender,
    :birth_date, :day, :month, :year, :raw

    def initialize(data)
    @raw = data
    @cpf = data["cpf"]
    @name = data["name"]
    @name_upper = data["nameUpper"]
    @gender = data["gender"]
    @birth_date = data["birthDate"]
    @day = data["day"]
    @month = data["month"]
    @year = data["year"]
    end

    def masculino?
    gender == "M"
    end

    def feminino?
    gender == "F"
    end

    def to_h
    raw
    end
    end
end

# lib/cpfhub/client.rb
require "faraday"
require "faraday-retry"
require "json"

module CpfHub
    class Client
    def initialize(config = nil)
    @config = config || CpfHub.configuration || Configuration.new
    validate_config!
    @connection = build_connection
    end

    def consultar(cpf)
    cpf_limpo = sanitizar_cpf(cpf)
    validar_cpf!(cpf_limpo)

    resposta = @connection.get("/cpf/#{cpf_limpo}")
    tratar_resposta(resposta)
    rescue Faraday::TimeoutError
    raise CpfHub::TimeoutError, "Timeout ao consultar CPF"
    rescue Faraday::ConnectionFailed => e
    raise CpfHub::Error, "Falha de conexao: #{e.message}"
    end

    private

    def validate_config!
    if @config.api_key.nil? || @config.api_key.empty?
    raise ConfigurationError,
    "API key nao configurada. Use CpfHub.configure"
    end
    end

    def build_connection
    Faraday.new(url: @config.base_url) do |conn|
    conn.request :retry, max: @config.max_retries,
    interval: @config.retry_delay,
    backoff_factor: 2,
    exceptions: [Faraday::TimeoutError, Faraday::ConnectionFailed]
    conn.headers["x-api-key"] = @config.api_key
    conn.headers["Content-Type"] = "application/json"
    conn.headers["User-Agent"] = "cpfhub-ruby/#{VERSION}"
    conn.options.timeout = @config.timeout
    conn.options.open_timeout = @config.open_timeout
    conn.adapter Faraday.default_adapter
    end
    end

    def sanitizar_cpf(cpf)
    cpf.to_s.gsub(/\D/, "")
    end

    def validar_cpf!(cpf)
    unless cpf.match?(/\A\d{11}\z/)
    raise InvalidCpfError, "CPF deve conter 11 digitos"
    end
    end

    def tratar_resposta(resposta)
    case resposta.status
    when 200
    body = JSON.parse(resposta.body)
    if body["success"]
    Response.new(body["data"])
    else
    raise NotFoundError, "CPF nao encontrado"
    end
    when 401
    raise AuthenticationError, "API key invalida"
    when 429
    raise RateLimitError, "Rate limit excedido"
    when 500..599
    raise ServerError, "Erro no servidor (#{resposta.status})"
    else
    raise Error, "Resposta inesperada (#{resposta.status})"
    end
    end
    end
end

# spec/spec_helper.rb
require "webmock/rspec"
require "cpfhub"

RSpec.configure do |config|
    config.before(:each) do
    CpfHub.configure do |c|
    c.api_key = "test-api-key"
    end
    end

    config.after(:each) do
    CpfHub.reset!
    end
end

# spec/cpfhub/client_spec.rb
RSpec.describe CpfHub::Client do
    let(:client) { described_class.new }
    let(:cpf) { "12345678901" }

    describe "#consultar" do
    context "quando o CPF e encontrado" do
    before do
    stub_request(:get, "https://api.cpfhub.io/cpf/#{cpf}")
    .with(headers: { "x-api-key" => "test-api-key" })
    .to_return(
    status: 200,
    body: {
    success: true,
    data: {
    cpf: cpf, name: "Joao da Silva",
    nameUpper: "JOAO DA SILVA", gender: "M",
    birthDate: "1990-01-15", day: 15, month: 1, year: 1990
    }
    }.to_json
    )
    end

    it "retorna um Response com os dados" do
    resultado = client.consultar(cpf)
    expect(resultado).to be_a(CpfHub::Response)
    expect(resultado.name).to eq("Joao da Silva")
    expect(resultado.gender).to eq("M")
    expect(resultado.masculino?).to be true
    end
    end

    context "quando o CPF e invalido" do
    it "levanta InvalidCpfError" do
    expect { client.consultar("123") }
    .to raise_error(CpfHub::InvalidCpfError)
    end
    end

    context "quando a API retorna 429" do
    before do
    stub_request(:get, "https://api.cpfhub.io/cpf/#{cpf}")
    .to_return(status: 429)
    end

    it "levanta RateLimitError" do
    expect { client.consultar(cpf) }
    .to raise_error(CpfHub::RateLimitError)
    end
    end
    end
end

# Gemfile
gem "cpfhub"

# config/initializers/cpfhub.rb (Rails)
CpfHub.configure do |config|
    config.api_key = ENV["CPFHUB_API_KEY"]
    config.timeout = 15
    config.max_retries = 3
end

# Uso em qualquer parte da aplicação
resultado = CpfHub.consultar("123.456.789-01")
puts resultado.name # => "Joao da Silva"
puts resultado.gender # => "M"
puts resultado.birth_date # => "1990-01-15"
puts resultado.masculino? # => true