checkhim 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: aabadc5305ed16d50ea750471f2cd2b5f6f525bc05e4333fa67ad93dfcd1e3c0
+  data.tar.gz: 9deb483176c12193da402711d7a410edd950fa21bec73c8add784cbdb50aeffe
+SHA512:
+  metadata.gz: d652ce69668b2d3466aa4094d029d141ae142bcca59e0c77b2949a9bca31b28ebf6e259ab1e611ffa5f26bdda7d76ed0e839eecf6c065b44aa9b6ab940314bc3
+  data.tar.gz: f71982b701a023a370f8a016939a5bd356ea066eccb013717181fa1f64a010afd353a7d76fd461f260dc756854ba59ddf272fe51066b2d3b0faccdcd3b4ff627

data/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+All notable changes to this project will be documented in this file.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) and adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+- Add retry helper for transient failures
+- Add logging hooks / instrumentation
+- Add RuboCop CI job
+
+## [0.1.0] - 2025-09-16
+### Added
+- Initial public release of the CheckHim Ruby SDK
+- `CheckHim::Client#verify`
+- Structured error classes mapped to API error codes
+- `CheckHim::VerificationResult` model
+- Basic RSpec test coverage (success + error mapping)
+- GitHub Actions CI (Ruby 2.7 – 3.3)
+- Documentation: README, contribution guidelines (in README)

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 CheckHim
+
+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,120 @@
+# CheckHim Ruby SDK
+
+Official Ruby client for the [CheckHim](https://checkhim.tech) Number Verification API.
+
+## Key Features
+- Simple, expressive API
+- Robust, typed error mapping
+- Lightweight (no heavy HTTP dependencies)
+- Built-in timeouts and sensible defaults
+- Thread-safe client (no global mutable state)
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'checkhim'
+```
+
+Or install directly:
+
+```bash
+gem install checkhim
+```
+
+## Quick Start
+
+```ruby
+require 'checkhim'
+
+client = CheckHim::Client.new('ch_test_your_api_key')
+
+begin
+  result = client.verify('+5511984339000')
+  puts "Valid: #{result.valid?} Carrier: #{result.carrier}"
+rescue CheckHim::Error => e
+  warn "Error: #{e.message} (#{e.code})"
+end
+```
+
+### Successful Response
+```json
+{
+  "carrier": "Oi",
+  "valid": true
+}
+```
+
+### Error Response Format
+```json
+{
+  "error": "verification failed: Network is forbidden (code: 6)",
+  "code": "REJECTED_NETWORK"
+}
+```
+
+## Error Classes
+All errors inherit from `CheckHim::Error`.
+
+| Code | Class | Meaning |
+| ---- | ----- | ------- |
+| REJECTED_NETWORK | CheckHim::RejectedNetwork | Network forbidden |
+| REJECTED_PREFIX_MISSING | CheckHim::RejectedPrefixMissing | Missing country/area prefix |
+| REJECTED_FORMAT | CheckHim::RejectedFormat | Invalid formatting |
+| REJECTED_SUBSCRIBER_ABSENT | CheckHim::RejectedSubscriberAbsent | Subscriber unreachable/absent |
+| REJECTED_UNKNOWN_SUBSCRIBER | CheckHim::RejectedUnknownSubscriber | Unknown subscriber |
+| REJECTED_UNDELIVERABLE | CheckHim::RejectedUndeliverable | Undeliverable route |
+| UNDELIVERABLE_NOT_DELIVERED | CheckHim::UndeliverableNotDelivered | Inactive or not delivered |
+| TEMPORARY_FAILURE | CheckHim::TemporaryFailure | Transient failure; retry later |
+| SERVICE_UNAVAILABLE | CheckHim::ServiceUnavailable | Upstream service unavailable |
+
+Other unexpected 4xx/5xx responses raise `CheckHim::APIError`.
+Network issues raise `CheckHim::NetworkError`.
+
+### Handling Errors
+```ruby
+begin
+  client.verify('+244921000111')
+rescue CheckHim::RejectedNetwork => e
+  # handle specific code
+rescue CheckHim::TemporaryFailure
+  sleep 2; retry
+rescue CheckHim::Error => e
+  warn "General failure: #{e.message} (#{e.code})"
+end
+```
+
+## Configuration Options
+```ruby
+client = CheckHim::Client.new(
+  'ch_live_key',
+  open_timeout: 3,
+  read_timeout: 8,
+  endpoint: 'https://api.checkhim.tech/api/v1'
+)
+```
+
+## Versioning
+This library follows semantic versioning: MAJOR.MINOR.PATCH.
+
+## Development
+```bash
+git clone https://github.com/checkhim/ruby-sdk.git
+cd ruby-sdk
+bundle install
+rake spec
+```
+
+## Contributing
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/improve-thing`)
+3. Add tests for your change
+4. Ensure `rake spec` passes and add documentation
+5. Submit a pull request
+
+## Security
+Do not open public issues for sensitive security topics. Email: opensource@checkhim.tech
+
+## License
+Released under the MIT License. See `LICENSE` for details.

data/lib/checkhim/client.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+require 'net/http'
+require 'uri'
+require 'json'
+
+module CheckHim
+  # Client for interacting with the CheckHim Verification API.
+  class Client
+    DEFAULT_ENDPOINT = 'https://api.checkhim.tech/api/v1'.freeze
+    VERIFY_PATH = '/verify'.freeze
+    DEFAULT_OPEN_TIMEOUT = 5
+    DEFAULT_READ_TIMEOUT = 10
+
+    attr_reader :api_key, :endpoint, :open_timeout, :read_timeout, :user_agent
+
+    def initialize(api_key, endpoint: DEFAULT_ENDPOINT, open_timeout: DEFAULT_OPEN_TIMEOUT, read_timeout: DEFAULT_READ_TIMEOUT, user_agent: nil)
+      raise ArgumentError, 'api_key must be provided' if api_key.nil? || api_key.strip.empty?
+
+      @api_key = api_key
+      @endpoint = endpoint.chomp('/')
+      @open_timeout = open_timeout
+      @read_timeout = read_timeout
+      @user_agent = user_agent || default_user_agent
+    end
+
+    # Verifies a phone number. Returns a VerificationResult on success.
+    # Raises CheckHim::Error subclasses on failure.
+    def verify(number)
+      payload = { number: number, type: 'frontend' }
+      uri = URI.parse(@endpoint + VERIFY_PATH)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == 'https'
+      http.open_timeout = @open_timeout
+      http.read_timeout = @read_timeout
+
+      request = Net::HTTP::Post.new(uri.request_uri)
+      request['Authorization'] = "Bearer #{@api_key}"
+      request['Content-Type'] = 'application/json'
+      request['Accept'] = 'application/json'
+      request['User-Agent'] = @user_agent
+      request.body = JSON.generate(payload)
+
+      response = http.request(request)
+      handle_response(response)
+    rescue Timeout::Error, Errno::ECONNREFUSED, SocketError => e
+      raise NetworkError.new("Network error: #{e.message}")
+    end
+
+    private
+
+    def handle_response(response)
+      body_text = response.body.to_s
+      json = parse_json(body_text)
+
+      if response.code.to_i >= 400
+        raise_api_error(json, response)
+      end
+
+      unless json.is_a?(Hash) && json.key?('carrier') && json.key?('valid')
+        raise APIError.new('Malformed API response', http_status: response.code.to_i, details: body_text)
+      end
+
+      VerificationResult.new(carrier: json['carrier'], valid: json['valid'])
+    end
+
+    def parse_json(body)
+      JSON.parse(body)
+    rescue JSON::ParserError
+      {}
+    end
+
+    def raise_api_error(json, response)
+      message = json['error'] || 'API request failed'
+      code = json['code']
+      klass = ERROR_CODE_CLASS_MAP[code] || APIError
+      raise klass.new(message, code: code, http_status: response.code.to_i, details: json)
+    end
+
+    def default_user_agent
+      "checkhim-ruby/#{CheckHim::VERSION} Ruby/#{RUBY_VERSION} (#{RUBY_PLATFORM})"
+    end
+  end
+end

data/lib/checkhim/errors.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module CheckHim
+  # Base error for all CheckHim related failures.
+  class Error < StandardError
+    attr_reader :code, :http_status, :details
+
+    def initialize(message = nil, code: nil, http_status: nil, details: nil)
+      super(message)
+      @code = code
+      @http_status = http_status
+      @details = details
+    end
+  end
+
+  class NetworkError < Error; end
+  class APIError < Error; end
+
+  # Specific API domain errors (these map the remote 'code' field)
+  class RejectedNetwork < APIError; end
+  class RejectedPrefixMissing < APIError; end
+  class RejectedFormat < APIError; end
+  class RejectedSubscriberAbsent < APIError; end
+  class RejectedUnknownSubscriber < APIError; end
+  class RejectedUndeliverable < APIError; end
+  class UndeliverableNotDelivered < APIError; end
+  class TemporaryFailure < APIError; end
+  class ServiceUnavailable < APIError; end
+
+  ERROR_CODE_CLASS_MAP = {
+    'REJECTED_NETWORK' => RejectedNetwork,
+    'REJECTED_PREFIX_MISSING' => RejectedPrefixMissing,
+    'REJECTED_FORMAT' => RejectedFormat,
+    'REJECTED_SUBSCRIBER_ABSENT' => RejectedSubscriberAbsent,
+    'REJECTED_UNKNOWN_SUBSCRIBER' => RejectedUnknownSubscriber,
+    'REJECTED_UNDELIVERABLE' => RejectedUndeliverable,
+    'UNDELIVERABLE_NOT_DELIVERED' => UndeliverableNotDelivered,
+    'TEMPORARY_FAILURE' => TemporaryFailure,
+    'SERVICE_UNAVAILABLE' => ServiceUnavailable
+  }.freeze
+end

data/lib/checkhim/verification_result.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module CheckHim
+  # Represents a verification result returned by the API.
+  class VerificationResult
+    attr_reader :carrier, :valid
+
+    def initialize(carrier:, valid:)
+      @carrier = carrier
+      @valid = !!valid
+    end
+
+    def valid?
+      @valid
+    end
+  end
+end

data/lib/checkhim/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module CheckHim
+  VERSION = '0.1.0'
+end

data/lib/checkhim.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require_relative 'checkhim/version'
+require_relative 'checkhim/errors'
+require_relative 'checkhim/verification_result'
+require_relative 'checkhim/client'
+
+module CheckHim
+  # Namespace module for the CheckHim Ruby SDK.
+end

metadata

@@ -0,0 +1,131 @@
+--- !ruby/object:Gem::Specification
+name: checkhim
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- CheckHim Engineering
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2025-09-16 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.19'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.19'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.50'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.50'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: Official, well-tested Ruby client for the CheckHim API enabling phone
+  number verification with robust error handling.
+email:
+- engineering@checkhim.tech
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/checkhim.rb
+- lib/checkhim/client.rb
+- lib/checkhim/errors.rb
+- lib/checkhim/verification_result.rb
+- lib/checkhim/version.rb
+homepage: https://checkhim.tech
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://checkhim.tech
+  source_code_uri: https://github.com/checkhim/ruby-sdk
+  changelog_uri: https://github.com/checkhim/ruby-sdk/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.7'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.20
+signing_key:
+specification_version: 4
+summary: Ruby client for the CheckHim number verification API.
+test_files: []