genderapi-phone-validator 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ecf9f90771c5ef2e18fab53e7e358f16ec30f66d43d42d200e638ad737f21bfe
+  data.tar.gz: cd2b5aff31a0617bb07393f825b7d0c9e229f387e473195b0edc6dfa2aa0ac7b
+SHA512:
+  metadata.gz: d5a059d183404f87ed093a612990c14a4165e225d8f27a2a744af7d50ee6c342fe2dd23309cfc2c38237def9fd999b11dc2483ad1c1962f11328cdd99b7e8897
+  data.tar.gz: 0cc94adb8911ad46186026418e0fb0c6f0694f96b4efbc2af05476c5e85963fdb34273d9f9ae20f889e1192474ef2c39157e807ef7de24a8b94546512d7476be

data/README.md

@@ -0,0 +1,151 @@
+# 📞 Phone Number Validation & Formatter API (Ruby SDK)
+
+The `phonevalidator` gem uses the official [GenderAPI Phone Number Validation & Formatter API](https://www.genderapi.io/) to validate and format phone numbers from over 240 countries and territories.
+
+Whether your users enter phone numbers in various formats (e.g., `12128675309`, `+1 212 867 5309`, `001-212-867-5309`), this library will intelligently detect, validate, and convert the input into a standardized E.164 format (e.g., `+12128675309`).
+
+---
+
+## ✅ Features
+
+- Converts phone numbers to **E.164** format
+- Validates if the number is real and structurally possible
+- Detects number type: **mobile**, **landline**, **VoIP**, etc.
+- Identifies region/city based on area code
+- Returns country-level metadata (e.g., ISO code)
+- Built with Ruby, uses `HTTParty` for HTTP requests
+
+---
+
+## 📦 Installation
+
+Add the gem to your project:
+
+```bash
+gem install genderapi-phone-validator
+```
+
+Or in your `Gemfile`:
+
+```ruby
+gem 'genderapi-phone-validator'
+```
+
+---
+
+## 🔐 Authentication
+
+You need an API key from [www.genderapi.io](https://www.genderapi.io).  
+Sign up and get your key from your dashboard.
+
+---
+
+## 🚀 Usage
+
+```ruby
+require 'genderapi-phone-validator'
+
+client = PhoneValidator::Client.new(api_key: "YOUR_API_KEY")
+
+response = client.validate(
+  number: "+1 212 867 5309",   # Required
+  address: "US"                # Optional, helps with local formats
+)
+
+puts response
+```
+
+---
+
+## 🧾 Input Parameters
+
+```ruby
+validate(number:, address: nil) → Hash
+```
+
+| Parameter | Type   | Required | Description |
+|-----------|--------|----------|-------------|
+| `number`  | String | ✅ Yes   | Phone number in any format |
+| `address` | String | Optional | ISO country code (`US`), full country name (`Turkey`), or city name (`Berlin`) – improves local number detection |
+
+#### Example:
+
+```ruby
+client.validate(number: "2128675309", address: "US")
+```
+
+---
+
+## 📬 API Response Example
+
+```json
+{
+  "status": true,
+  "remaining_credits": 15709,
+  "expires": 0,
+  "duration": "18ms",
+  "regionCode": "US",
+  "country": "United States",
+  "national": "(212) 867-5309",
+  "international": "+1 212-867-5309",
+  "e164": "+12128675309",
+  "isValid": true,
+  "isPossible": true,
+  "numberType": "FIXED_LINE_OR_MOBILE",
+  "nationalSignificantNumber": "2128675309",
+  "rawInput": "+1 212 867 5309",
+  "isGeographical": true,
+  "areaCode": "212",
+  "location": "New York City (Manhattan)"
+}
+```
+
+---
+
+## 🧠 Response Field Reference
+
+| Field                    | Type    | Description                                 |
+|--------------------------|---------|---------------------------------------------|
+| `status`                 | Boolean | Was the request successful                  |
+| `remaining_credits`      | Integer | Remaining API credits                       |
+| `regionCode`             | String  | ISO 3166-1 alpha-2 code (e.g., `US`)        |
+| `country`                | String  | Country name                                |
+| `e164`                   | String  | Number formatted to E.164                   |
+| `isValid`                | Boolean | Is number valid according to rules          |
+| `isPossible`             | Boolean | Is number structurally possible             |
+| `numberType`             | String  | Number type (`MOBILE`, `FIXED_LINE`, etc.)  |
+| `areaCode`              | String  | Area code from input                        |
+| `location`               | String  | City/region matched from area code          |
+
+---
+
+## 🔢 Number Type Values
+
+| Value                  | Description                             |
+|------------------------|-----------------------------------------|
+| `FIXED_LINE`           | Landline                                |
+| `MOBILE`               | Mobile phone                            |
+| `FIXED_LINE_OR_MOBILE` | Ambiguous, could be both                |
+| `TOLL_FREE`            | e.g., 800 numbers                       |
+| `PREMIUM_RATE`         | Expensive premium numbers               |
+| `SHARED_COST`          | Cost shared between parties             |
+| `VOIP`                 | Internet-based phone                    |
+| `PERSONAL_NUMBER`      | Forwarding number                       |
+| `PAGER`                | Obsolete pager number                   |
+| `VOICEMAIL`            | Voicemail access                        |
+| `UNKNOWN`              | Cannot be determined                    |
+
+---
+
+## ℹ️ More Information
+
+- Supports **240+ countries and territories**
+- Automatically detects mobile vs. landline
+- Useful for CRMs, forms, messaging, marketing, and more
+- Full documentation at: [https://www.genderapi.io/docs-phone-validation-formatter-api](https://www.genderapi.io/docs-phone-validation-formatter-api)
+
+---
+
+## 📝 License
+
+MIT License © [GenderAPI](https://www.genderapi.io)

data/lib/genderapi-phone-validator/client.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require "httparty"
+require "json"
+
+module PhoneValidator
+  ##
+  # Ruby SDK for Phone Number Validation & Formatter API from www.genderapi.io
+  #
+  # This SDK allows you to:
+  #   - Validate international phone numbers
+  #   - Detect number type (mobile, landline, VoIP, etc.)
+  #   - Retrieve region and country metadata
+  #   - Format numbers to E.164 or national format
+  #
+  # Learn more: https://www.genderapi.io
+  #
+  class Client
+    include HTTParty
+    base_uri "https://api.genderapi.io"
+
+    ##
+    # Initialize the PhoneValidator client.
+    #
+    # @param api_key [String] Your GenderAPI API key as a Bearer token.
+    # @param base_url [String] Optional override for the API base URL.
+    #
+    def initialize(api_key:, base_url: nil)
+      @api_key = api_key
+      self.class.base_uri(base_url) if base_url
+      @headers = {
+        "Authorization" => "Bearer #{@api_key}",
+        "Content-Type" => "application/json"
+      }
+    end
+
+    ##
+    # Validate and format a phone number.
+    #
+    # @param number [String] The phone number to validate (required).
+    # @param address [String] Optional address or country hint for better accuracy.
+    #
+    # @return [Hash] Parsed JSON response containing validation results.
+    #
+    def validate(number:, address: "")
+      payload = {
+        number: number,
+        address: address
+      }
+
+      _post_request("/api/phone", payload)
+    end
+
+    private
+
+    ##
+    # Internal helper for sending POST requests to the GenderAPI.io API.
+    #
+    # Handles:
+    #   - Bearer token authorization
+    #   - Payload cleanup (removal of nil values)
+    #   - Error handling and JSON parsing
+    #
+    # @param endpoint [String] API endpoint path (e.g. "/api/phone")
+    # @param payload [Hash] Request body
+    #
+    # @return [Hash] Parsed JSON response
+    #
+    def _post_request(endpoint, payload)
+      cleaned_payload = payload.reject { |_k, v| v.nil? }
+
+      response = self.class.post(
+        endpoint,
+        headers: @headers,
+        body: JSON.generate(cleaned_payload)
+      )
+
+      if [500, 502, 503, 504, 408].include?(response.code)
+        raise "GenderAPI Server Error or Timeout: HTTP #{response.code} - #{response.body}"
+      else
+        begin
+          parse_json(response.body)
+        rescue JSON::ParserError
+          raise "GenderAPI Response is not valid JSON"
+        end
+      end
+    rescue HTTParty::Error => e
+      raise "GenderAPI Request failed: #{e.message}"
+    end
+
+    ##
+    # Safely parse JSON response.
+    #
+    # @param body [String] JSON string
+    # @return [Hash] Ruby Hash
+    #
+    def parse_json(body)
+      JSON.parse(body)
+    end
+  end
+end

data/lib/genderapi-phone-validator/version.rb

@@ -0,0 +1,5 @@
+# lib/phonevalidador/version.rb
+
+module PhoneValidator
+  VERSION = "1.0.0"
+end

data/lib/genderapi-phone-validator.rb

@@ -0,0 +1,8 @@
+# lib/phonevalidator.rb
+
+require "genderapi-phone-validator/version"
+require "genderapi-phone-validator/client"
+
+module PhoneValidator
+  # boş bırakabilirsin veya helper methodlar koyabilirsin
+end

metadata

@@ -0,0 +1,97 @@
+--- !ruby/object:Gem::Specification
+name: genderapi-phone-validator
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Onur Ozturk
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2025-08-03 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: httparty
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.18'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.18'
+- !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.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: "\n    Official Ruby SDK for the Phone Number Validation & Formatter
+  API by GenderAPI.io.\n\n    Features:\n    - Validate phone numbers from 240+ countries\n
+  \   - Format numbers to E.164 or national format\n    - Detect number type (mobile,
+  landline, VoIP, etc.)\n    - Retrieve region, area code, and country metadata\n\n
+  \   Built using HTTParty for robust HTTP requests.\n  "
+email:
+- support@genderapi.io
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/genderapi-phone-validator.rb
+- lib/genderapi-phone-validator/client.rb
+- lib/genderapi-phone-validator/version.rb
+homepage: https://www.genderapi.io
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/GenderAPI/phone-validator-ruby
+  changelog_uri: https://github.com/GenderAPI/phone-validator-ruby/blob/main/CHANGELOG.md
+  documentation_uri: https://rubydoc.info/gems/genderapi-phone-validator/1.0.0
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.6'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.2.3
+signing_key:
+specification_version: 4
+summary: Ruby SDK for validating and formatting international phone numbers using
+  GenderAPI.
+test_files: []