genderapi 1.0.5 → 2.0.0

data/lib/genderapi/errors.rb

@@ -0,0 +1,236 @@
+# frozen_string_literal: true
+
+module GenderAPI
+  # Base class for every error raised by this library.
+  #
+  # Error messages never contain the API key or the submitted input values.
+  # The parsed body (+body+) can contain submitted inputs: inspect it securely
+  # and do not log it wholesale.
+  class Error < StandardError; end
+
+  # Invalid client input or configuration. Raised before any network request.
+  class ValidationError < Error
+    # @return [String, nil] the offending argument or wire field, e.g. "value" or "items[2].country"
+    attr_reader :field
+
+    def initialize(message, field: nil)
+      super(message)
+      @field = field
+    end
+  end
+
+  # No usable HTTP response (connection failure, TLS error, reset, timeout).
+  # The request may still have completed and been billed; check {Client#usage}
+  # before sending another prediction. The client never retries automatically.
+  class TransportError < Error
+    # @return [Exception, nil] the underlying low-level exception
+    attr_reader :original
+
+    def initialize(message = "Transport failed; completion and billing are unknown. Do not retry automatically.", original: nil)
+      super(message)
+      @original = original
+    end
+  end
+
+  # The configured timeout elapsed while connecting, writing or reading.
+  class TimeoutError < TransportError
+    def initialize(message = "Request timed out; completion and billing are unknown. Do not retry automatically.", original: nil)
+      super(message, original: original)
+    end
+  end
+
+  # Shared readers for errors that carry an HTTP response.
+  module ResponseContext
+    # @return [Integer, nil] HTTP status
+    attr_reader :status
+    # @return [String, nil] meta.request_id, body request_id, or the X-Request-ID header
+    attr_reader :request_id
+    # @return [Integer, String, nil] Retry-After in seconds (Integer) or the raw header value (HTTP date)
+    attr_reader :retry_after
+    # @return [Hash, nil] parsed JSON body (string keys), when the body was a JSON object
+    attr_reader :body
+    # @return [String, nil] raw response body
+    attr_reader :raw_body
+    # @return [Hash{String=>String}] response headers with lower-case names
+    attr_reader :headers
+
+    private
+
+    def assign_context(status:, body:, raw_body:, headers:)
+      @status = status
+      @body = body.is_a?(Hash) ? body : nil
+      @raw_body = raw_body
+      @headers = headers || {}
+      meta = @body && @body["meta"].is_a?(Hash) ? @body["meta"] : {}
+      @request_id = [meta["request_id"], @body && @body["request_id"], @headers["x-request-id"]]
+                    .find { |v| v.is_a?(String) && !v.empty? }
+      @retry_after = ResponseContext.parse_retry_after(@headers["retry-after"])
+    end
+
+    # @api private
+    def self.parse_retry_after(value)
+      return nil if value.nil? || value.strip.empty?
+
+      value.strip.match?(/\A\d+\z/) ? value.strip.to_i : value.strip
+    end
+  end
+
+  # The server answered with a redirect (3xx). Redirects are never followed so
+  # the Bearer key is not forwarded to another location.
+  class RedirectError < Error
+    include ResponseContext
+
+    # @return [String, nil] the Location header that was not followed
+    attr_reader :location
+
+    def initialize(status:, headers:, raw_body: nil)
+      super("GenderAPI answered HTTP #{status} with a redirect; redirects are not followed. Check base_url.")
+      assign_context(status: status, body: nil, raw_body: raw_body, headers: headers)
+      @location = @headers["location"]
+    end
+  end
+
+  # A 2xx response that is not the expected JSON structure. Billing is unknown:
+  # keep {#request_id} and check {Client#usage} before another submission.
+  class InvalidResponseError < Error
+    include ResponseContext
+
+    def initialize(message, status:, headers:, body: nil, raw_body: nil)
+      super(message)
+      assign_context(status: status, body: body, raw_body: raw_body, headers: headers)
+    end
+  end
+
+  # An authenticated request was answered through IP-trial (or unauthenticated)
+  # access, usually because the configured key is invalid or unknown. The request
+  # has already run and may have consumed shared IP-trial credits; the full result
+  # is available in {#result}. Disable with +require_api_key_access: false+.
+  class UnexpectedAccessModeError < Error
+    include ResponseContext
+
+    # @return [GenderAPI::Result] the complete (already billed) result
+    attr_reader :result
+
+    # @return [String, nil] meta.access.mode, e.g. "ip_trial"
+    attr_reader :access_mode
+
+    # @return [String, nil] meta.access.reason, e.g. "api_key_invalid"
+    attr_reader :access_reason
+
+    def initialize(result:, status:, headers:, raw_body: nil)
+      access = result.meta.access
+      @access_mode = access&.mode
+      @access_reason = access&.reason
+      super("Expected API-key access but the response reports access mode #{@access_mode.inspect} " \
+            "(#{@access_reason.inspect}). Check your API key; this request may have consumed IP-trial credits.")
+      @result = result
+      assign_context(status: status, body: result.to_h, raw_body: raw_body, headers: headers)
+    end
+  end
+
+  # HTTP status >= 400. Exposes RFC 9457 Problem Details fields and the stable
+  # machine-readable {#code}. Match on {#code}, never on {#detail} text.
+  #
+  # Proxy-level errors can be non-JSON; then {#code} is nil and {#raw_body} is set.
+  class APIError < Error
+    include ResponseContext
+
+    # @return [String, nil] stable machine code, e.g. "insufficient_credits"
+    attr_reader :code
+    # @return [String, nil]
+    attr_reader :title
+    # @return [String, nil] human-readable detail (do not match on it)
+    attr_reader :detail
+    # @return [String, nil] problem type URI
+    attr_reader :type
+    # @return [String, nil] problem instance
+    attr_reader :instance
+    # @return [String, nil] recommended action, e.g. "wait_then_retry"
+    attr_reader :action
+    # @return [String, nil] link to the public error catalog
+    attr_reader :documentation
+    # @return [Array<Hash>] validation pointers: [{"pointer" => "/value", "message" => "..."}]
+    attr_reader :errors
+    # @return [GenderAPI::Usage, nil] meta.usage
+    attr_reader :usage
+    # @return [Array<GenderAPI::BatchItem>, nil] item outcomes of an all-failed batch (body "data")
+    attr_reader :items
+
+    def initialize(status:, headers:, body: nil, raw_body: nil)
+      assign_context(status: status, body: body, raw_body: raw_body, headers: headers)
+      b = @body || {}
+      @code = str(b["code"])
+      @title = str(b["title"])
+      @detail = str(b["detail"])
+      @type = str(b["type"])
+      @instance = str(b["instance"])
+      @action = str(b["action"])
+      @documentation = str(b["documentation"])
+      @errors = b["errors"].is_a?(Array) ? b["errors"] : []
+      meta = b["meta"].is_a?(Hash) ? b["meta"] : {}
+      @usage = meta["usage"].is_a?(Hash) ? Usage.new(meta["usage"]) : nil
+      @items = b["data"].is_a?(Array) ? b["data"].select { |r| r.is_a?(Hash) }.map { |r| BatchItem.new(r) } : nil
+      super(build_message)
+    end
+
+    # @return [String, nil] meta.usage.billing_status: "not_charged", "confirmed" or "unconfirmed"
+    def billing_status
+      @usage&.billing_status
+    end
+
+    # @return [Array<Hash>, nil] body "data" (all-failed batch rows) as raw hashes
+    def data
+      @body && @body["data"]
+    end
+
+    # True when the charge could not be confirmed; contact support with
+    # {#request_id} instead of retrying.
+    def billing_unconfirmed?
+      billing_status == "unconfirmed"
+    end
+
+    private
+
+    def str(value)
+      value.is_a?(String) ? value : nil
+    end
+
+    def build_message
+      parts = ["GenderAPI HTTP #{@status}"]
+      parts << @code if @code
+      parts << "action=#{@action}" if @action
+      parts << "billing_status=#{billing_status}" if billing_status
+      parts << "request_id=#{@request_id}" if @request_id
+      parts.join(" ")
+    end
+  end
+
+  # HTTP 400 (malformed request).
+  class BadRequestError < APIError; end
+  # HTTP 401 (invalid credentials).
+  class AuthenticationError < APIError; end
+  # HTTP 403 (access denied, disabled/expired key, insufficient credits).
+  class PermissionDeniedError < APIError; end
+  # HTTP 404.
+  class NotFoundError < APIError; end
+  # HTTP 422 (server-side validation, including the IP-trial batch limit). See {#errors}.
+  class UnprocessableEntityError < APIError; end
+  # HTTP 429. Wait {#retry_after} before another request; a retry is a new, billable operation.
+  class RateLimitError < APIError; end
+  # HTTP 5xx. Inspect {#billing_status} before sending another request.
+  class ServerError < APIError; end
+
+  # @api private
+  def self.api_error_class(status)
+    case status
+    when 400 then BadRequestError
+    when 401 then AuthenticationError
+    when 403 then PermissionDeniedError
+    when 404 then NotFoundError
+    when 422 then UnprocessableEntityError
+    when 429 then RateLimitError
+    when 500..599 then ServerError
+    else APIError
+    end
+  end
+end

data/lib/genderapi/models.rb

@@ -0,0 +1,278 @@
+# frozen_string_literal: true
+
+module GenderAPI
+  # Read-only wrapper around a parsed JSON object (string keys).
+  #
+  # Every field of the response is kept, including fields this version of the
+  # library does not know about: use {#[]}, {#dig} or {#to_h} for them. Values are
+  # exactly as returned by the API (nulls stay nil; confidence is never rescaled).
+  class Model
+    # @api private
+    def self.fields(*names)
+      names.each do |name|
+        define_method(name) { @raw[name.to_s] }
+      end
+    end
+
+    # @param raw [Hash] parsed JSON object
+    def initialize(raw)
+      @raw = raw.is_a?(Hash) ? raw : {}
+    end
+
+    # @param key [String, Symbol]
+    def [](key)
+      @raw[key.to_s]
+    end
+
+    def dig(*keys)
+      @raw.dig(*keys.map { |k| k.is_a?(Symbol) ? k.to_s : k })
+    end
+
+    def key?(key)
+      @raw.key?(key.to_s)
+    end
+
+    # @return [Hash] the original parsed JSON object (string keys)
+    def to_h
+      @raw
+    end
+
+    def ==(other)
+      other.is_a?(self.class) && other.to_h == @raw
+    end
+    alias eql? ==
+
+    def hash
+      @raw.hash
+    end
+
+    def inspect
+      "#<#{self.class.name} #{@raw.inspect}>"
+    end
+
+    private
+
+    def model(key, klass)
+      value = @raw[key]
+      value.is_a?(Hash) ? klass.new(value) : nil
+    end
+  end
+
+  # meta.access: how the request was authorised.
+  class Access < Model
+    # mode: "api_key", "ip_trial" or "unauthenticated"
+    # reason: nil, "api_key_missing", "api_key_invalid" or "api_key_not_found"
+    fields :mode, :reason
+
+    def api_key?
+      mode == "api_key"
+    end
+
+    def ip_trial?
+      mode == "ip_trial"
+    end
+  end
+
+  # meta.usage: billing of this operation.
+  #
+  # * billing_status "not_charged": charged_credits is 0.
+  # * "confirmed": the net charge is known (a confirmed refund can make it 0).
+  # * "unconfirmed": charged_credits and remaining_credits are nil; contact
+  #   support with the request ID before retrying.
+  #
+  # remaining_credits is the balance at completion; it can be negative or nil.
+  # resets_at, limit and period_seconds describe the IP trial (nil otherwise).
+  class Usage < Model
+    fields :billing_status, :charged_credits, :remaining_credits, :resets_at, :limit, :period_seconds
+
+    def confirmed?
+      billing_status == "confirmed"
+    end
+
+    def unconfirmed?
+      billing_status == "unconfirmed"
+    end
+
+    def not_charged?
+      billing_status == "not_charged"
+    end
+  end
+
+  # meta.summary of a batch: total = succeeded + failed; succeeded = identified + unknown.
+  class BatchSummary < Model
+    fields :total, :succeeded, :identified, :unknown, :failed
+  end
+
+  # Response metadata.
+  class Meta < Model
+    fields :request_id, :duration_ms
+
+    # @return [Access, nil]
+    def access
+      model("access", Access)
+    end
+
+    # @return [Usage, nil]
+    def usage
+      model("usage", Usage)
+    end
+
+    # @return [BatchSummary, nil] present on batch responses
+    def summary
+      model("summary", BatchSummary)
+    end
+  end
+
+  # A gender inference. It is an inference, not verification of identity, and it
+  # can be unknown (gender nil). An unknown result is a successful, billed outcome.
+  #
+  # * result_status: "identified" or "unknown"
+  # * reason: nil, "not_found", "no_name_candidate", "ambiguous" or "insufficient_evidence"
+  # * confidence: 0..1 or nil. Not a calibrated probability; interpret it with confidence_kind
+  #   ("observed_frequency" for dataset results, "model_reported" for AI results).
+  # * sample_count: dataset sample count, nil for AI
+  # * source: "dataset", "ai" or "none"
+  # * country_source: nil, "dataset" or "ai_association" (never nationality or residence)
+  # * match: {"name", "method", "scope", "country"} (see {#match})
+  class Prediction < Model
+    fields :input, :name, :gender, :country, :confidence, :confidence_kind, :sample_count,
+           :source, :result_status, :reason, :country_source, :match
+
+    def identified?
+      result_status == "identified"
+    end
+
+    def unknown?
+      result_status == "unknown"
+    end
+  end
+
+  # Problem details for a single failed batch item.
+  class ItemError < Model
+    fields :type, :title, :status, :detail, :instance, :code, :request_id, :documentation, :action, :errors
+  end
+
+  # One row of a batch response. Exactly one of {#data} or {#error} is present.
+  class BatchItem < Model
+    fields :index, :id, :charged_credits
+
+    # @return [Prediction, nil]
+    def data
+      model("data", Prediction)
+    end
+
+    # @return [ItemError, nil]
+    def error
+      model("error", ItemError)
+    end
+
+    def success?
+      @raw.key?("data") && !@raw.key?("error")
+    end
+
+    def failed?
+      @raw.key?("error")
+    end
+  end
+
+  # Base class for every successful response: {"data" => ..., "meta" => {...}}.
+  class Result < Model
+    # @return [Meta]
+    def meta
+      Meta.new(@raw["meta"])
+    end
+
+    # @return [Usage, nil]
+    def usage
+      meta.usage
+    end
+
+    # @return [Access, nil]
+    def access
+      meta.access
+    end
+
+    # @return [String, nil]
+    def request_id
+      meta.request_id
+    end
+
+    # @return [Object] raw "data" value
+    def data
+      @raw["data"]
+    end
+  end
+
+  # Result of {Client#gender}, {Client#name}, {Client#email} and {Client#username}.
+  class GenderResult < Result
+    # @return [Prediction]
+    def data
+      Prediction.new(@raw["data"])
+    end
+    alias prediction data
+  end
+
+  # Result of {Client#gender_batch}. HTTP 200 can contain failed items; they
+  # are not raised. Retry only failed items, and only after billing is confirmed:
+  # resubmitting successful items charges them again.
+  class BatchResult < Result
+    # @return [Array<BatchItem>] in submission order
+    def data
+      Array(@raw["data"]).map { |row| BatchItem.new(row) }
+    end
+    alias items data
+
+    # @return [Array<BatchItem>]
+    def succeeded_items
+      items.select(&:success?)
+    end
+
+    # @return [Array<BatchItem>]
+    def failed_items
+      items.select(&:failed?)
+    end
+
+    def partial_failure?
+      !failed_items.empty?
+    end
+
+    # @return [BatchSummary, nil]
+    def summary
+      meta.summary
+    end
+  end
+
+  # Data of GET /usage (free): remaining_credits, expires_at, resets_at, limit, period_seconds.
+  class UsageData < Model
+    fields :remaining_credits, :expires_at, :resets_at, :limit, :period_seconds
+  end
+
+  # Result of {Client#usage}.
+  class UsageResult < Result
+    # @return [UsageData]
+    def data
+      UsageData.new(@raw["data"])
+    end
+  end
+
+  # Data of POST /phone/validate. Checks number structure, not subscriber existence.
+  class PhoneValidation < Model
+    fields :valid, :possible, :e164, :country, :country_calling_code
+
+    def valid?
+      valid == true
+    end
+
+    def possible?
+      possible == true
+    end
+  end
+
+  # Result of {Client#validate_phone}.
+  class PhoneResult < Result
+    # @return [PhoneValidation]
+    def data
+      PhoneValidation.new(@raw["data"])
+    end
+  end
+end

data/lib/genderapi/validation.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+module GenderAPI
+  # Client-side checks that mirror the V2 request schema where they are cheap
+  # and certain. The API remains authoritative (e.g. email syntax and ISO
+  # country membership are validated by the server and reported as HTTP 422).
+  #
+  # @api private
+  module Validation
+    TYPES = %w[name email username].freeze
+    AI_MODES = %w[off fallback always].freeze
+    MAX_VALUE_LENGTH = 254
+    MAX_ID_LENGTH = 64
+    MAX_BATCH_ITEMS = 50
+    CONTROL_CHARS = /[\x00-\x1f\x7f]/.freeze
+    # Like the schema pattern \S (ECMAScript \s includes Unicode spaces and U+FEFF).
+    NON_SPACE = /[^[:space:]\u{FEFF}]/.freeze
+    COUNTRY = /\A[A-Z]{2}\z/.freeze
+    PHONE = /\A\+?[0-9 ()-]+\z/.freeze
+
+    # Ruby-style and wire-style keys accepted for a batch item.
+    ITEM_KEYS = {
+      "type" => :type, "value" => :value, "country" => :country, "id" => :id,
+      "ai_mode" => :ai_mode, "force_to_genderize" => :force_to_genderize,
+      "forceToGenderize" => :force_to_genderize, "options" => :options
+    }.freeze
+
+    module_function
+
+    # Build and validate the exact wire body for one prediction.
+    # @return [Hash] string-keyed wire body
+    def gender_item(type, value, country: nil, ai_mode: nil, force_to_genderize: nil, id: nil, field: nil)
+      prefix = field ? "#{field}." : ""
+      type = type.to_s if type.is_a?(Symbol)
+      unless TYPES.include?(type)
+        raise ValidationError.new("type must be one of: #{TYPES.join(', ')}", field: "#{prefix}type")
+      end
+
+      value = check_value(value, "#{prefix}value")
+      ai_mode = ai_mode.to_s if ai_mode.is_a?(Symbol)
+      unless ai_mode.nil? || AI_MODES.include?(ai_mode)
+        raise ValidationError.new("ai_mode must be one of: #{AI_MODES.join(', ')}", field: "#{prefix}options.ai_mode")
+      end
+      unless force_to_genderize.nil? || force_to_genderize == true || force_to_genderize == false
+        raise ValidationError.new("force_to_genderize must be true or false", field: "#{prefix}forceToGenderize")
+      end
+      if force_to_genderize == true && %w[off always].include?(ai_mode)
+        raise ValidationError.new("force_to_genderize cannot be combined with ai_mode off or always",
+                                  field: "#{prefix}forceToGenderize")
+      end
+      check_country(country, "#{prefix}country") unless country.nil?
+      check_id(id, "#{prefix}id") unless id.nil?
+
+      body = { "type" => type, "value" => value }
+      body["country"] = country unless country.nil?
+      body["id"] = id unless id.nil?
+      body["forceToGenderize"] = true if force_to_genderize == true
+      body["options"] = { "ai_mode" => ai_mode } unless ai_mode.nil?
+      body
+    end
+
+    # Normalise and validate a batch.
+    # @return [Array<Hash>] string-keyed wire items
+    def batch_items(items)
+      unless items.is_a?(Array) && items.length.between?(1, MAX_BATCH_ITEMS)
+        raise ValidationError.new("items must be an Array of 1-#{MAX_BATCH_ITEMS} items; split larger jobs yourself",
+                                  field: "items")
+      end
+
+      wire = items.each_with_index.map { |item, index| batch_item(item, "items[#{index}]") }
+      ids = wire.map { |w| w["id"] }.compact
+      raise ValidationError.new("batch item ids must be unique", field: "items") if ids.uniq.length != ids.length
+
+      wire
+    end
+
+    def batch_item(item, field)
+      raise ValidationError.new("each batch item must be a Hash", field: field) unless item.is_a?(Hash)
+
+      args = {}
+      item.each do |key, val|
+        name = ITEM_KEYS[key.to_s]
+        raise ValidationError.new("unsupported batch item field #{key.to_s.inspect}", field: field) if name.nil?
+        if args.key?(name)
+          raise ValidationError.new("batch item field #{key.to_s.inspect} is given twice", field: field)
+        end
+
+        args[name] = val
+      end
+      if args.key?(:options)
+        options = args.delete(:options)
+        unless options.is_a?(Hash) && options.keys.map(&:to_s) - ["ai_mode"] == []
+          raise ValidationError.new("options may only contain ai_mode", field: "#{field}.options")
+        end
+        if args.key?(:ai_mode)
+          raise ValidationError.new("give ai_mode either at top level or in options", field: "#{field}.options")
+        end
+
+        args[:ai_mode] = options["ai_mode"] || options[:ai_mode]
+      end
+      gender_item(args.delete(:type), args.delete(:value), **args, field: field)
+    end
+
+    # @return [Hash] string-keyed wire body for phone validation
+    def phone(number, country)
+      unless number.is_a?(String) && number.length.between?(3, 32) && number.match?(PHONE)
+        raise ValidationError.new("number must be 3-32 characters of digits, spaces, parentheses or hyphens, " \
+                                  "optionally starting with +", field: "number")
+      end
+      if country.nil?
+        unless number.start_with?("+")
+          raise ValidationError.new("country is required unless number starts with +", field: "country")
+        end
+      else
+        check_country(country, "country")
+      end
+      body = { "number" => number }
+      body["country"] = country unless country.nil?
+      body
+    end
+
+    def check_value(value, field)
+      unless value.is_a?(String)
+        raise ValidationError.new("value must be a String", field: field)
+      end
+
+      value = if value.encoding == Encoding::BINARY
+                value.dup.force_encoding(Encoding::UTF_8)
+              elsif value.encoding != Encoding::UTF_8
+                value.encode(Encoding::UTF_8)
+              else
+                value
+              end
+      raise ValidationError.new("value must be valid UTF-8 text", field: field) unless value.valid_encoding?
+      if !value.match?(NON_SPACE) || value.length > MAX_VALUE_LENGTH || value.match?(CONTROL_CHARS)
+        raise ValidationError.new("value must contain 1-#{MAX_VALUE_LENGTH} characters, not only whitespace, " \
+                                  "and no control characters", field: field)
+      end
+
+      value
+    rescue EncodingError
+      raise ValidationError.new("value must be valid UTF-8 text", field: field)
+    end
+
+    def check_country(country, field)
+      return if country.is_a?(String) && country.match?(COUNTRY)
+
+      raise ValidationError.new("country must be an uppercase ISO 3166-1 alpha-2 code such as \"US\"; " \
+                                "omit it when unknown", field: field)
+    end
+
+    def check_id(id, field)
+      return if id.is_a?(String) && id.length.between?(1, MAX_ID_LENGTH)
+
+      raise ValidationError.new("id must be a String of 1-#{MAX_ID_LENGTH} characters", field: field)
+    end
+  end
+end

data/lib/genderapi/version.rb

@@ -1,5 +1,5 @@
-# lib/genderapi/version.rb
+# frozen_string_literal: true
 
 module GenderAPI
-  VERSION = "1.0.5"
+  VERSION = "2.0.0"
 end

data/lib/genderapi.rb

@@ -1,8 +1,14 @@
-# lib/genderapi.rb
+# frozen_string_literal: true
 
+# Official GenderAPI.io V2 client for Ruby.
+#
+# Requiring this file and constructing a client never makes a network request.
+# Keep API keys on the server; never embed them in browser or mobile code.
 require "genderapi/version"
+require "genderapi/errors"
+require "genderapi/models"
+require "genderapi/validation"
 require "genderapi/client"
 
 module GenderAPI
-  # boş bırakabilirsin veya helper methodlar koyabilirsin
 end