namegender 0.3.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7f722edcb4239a867f707088e2ce93a6b3405fe0a0f1749737954120449a723e
-  data.tar.gz: ed030b15d314cd420bdc0157966dbc064c81d0e9cd23a20a6bf540b4e1a1a674
+  metadata.gz: 5350923af9d635c3f939d1f25538c60b6accc0defeb05cf22039573ff89e10fe
+  data.tar.gz: 39dcaef2b09d1357e6a6bab9d47f4ac5136e936e4b3a1d1a66bea68ae315f583
 SHA512:
-  metadata.gz: 37278319b8f4aa7e36e24cdffa06f84eea05c96cfbe699797695406a3213825e9d3493e780a194c4303d146dd8aa5d5f33e2f5cb91714510bbdcdd073a9e18c9
-  data.tar.gz: 2b6348cb0cefe459729e14179a731e31f95edb6d9e4fad1cc9729f34162ae445e9837cb58606ccdce1b12a457f7746c6679e0c08194b0980a5f585beeadf073d
+  metadata.gz: fe4b4f3e318ebb9f6ff60ff3d8492cfd83d2e1fb068208563a966c3a5fc5dad1e84289956d31c47b9cd2edddadace69f6a216074922276e284689ba5c2ae3d97
+  data.tar.gz: 036b301d1b82c4443657cbaa9a38351de62bb15c47c7621741475a0e7fcc3c46c1085c7f2b3fde0ae0ff558de84383645341e5f35f0a78f8b2f7a36cdd3dbe4a

data/README.md

@@ -12,19 +12,33 @@ puts result["gender"], result["probability"], result["sample_size"]
 
 ## Options and response
 
-`name`, `email`, `username` and `bulk` accept `country:`, `ai_fallback:` and
-`best_guess:`:
+`name`, `email`, `username` and `bulk` accept `country:`, `locale:`, `ip:`,
+`ai_fallback:` and `best_guess:`:
 
 ```ruby
 result = client.name("Andrea", country: "IT", best_guess: true)
 ```
 
-A result carries `query`, `name`, `gender`, `country`, `probability`,
-`sample_size`, `took_ms`, `source`, `confidence` and `matched_as`, alongside
+When you do not know the country, pass what you have and the API works it out:
+`locale:` is a language tag such as `"it-IT"` or `"pt_BR"` (its region is used;
+a tag without one, `"en"`, sets no country), and `ip:` is your end user's IP
+address (looked up, not stored). `country:` wins over `locale:`, which wins
+over `ip:`. The response's `country_source` says which one was used:
+`"country"`, `"locale"`, `"ip"` or `nil`.
+
+```ruby
+result = client.name("Andrea", locale: request.env["HTTP_ACCEPT_LANGUAGE"].to_s[/\A[^,;]+/], ip: request.ip)
+puts result["country"], result["country_source"]
+```
+
+A result carries `query`, `name`, `first_name`, `middle_name`, `last_name`, `name_type`, `gender`, `country`, `probability`,
+`sample_size`, `took_ms`, `source`, `confidence`, `matched_as` and `country_source`, alongside
 `credits_charged`, `credits_remaining`, `data_version` and `request_id`.
 Success is the HTTP status: any non-2xx response raises `NameGender::Error`
 with `status` and `body` (`{"error", "message", "request_id", "docs"}`).
-Branch on `body["error"]`, not on the message.
+Branch on `body["error"]`, not on the message. A `bulk` response carries
+`country_source` once, at the top level next to `summary`, not on each item
+in `results`.
 
 ## Country distribution
 
@@ -38,3 +52,80 @@ result = client.countries("Mehmet", limit: 10)
 result["registrations"].each { |r| puts "#{r["country"]} #{r["share"]}%" }
 puts result["attested_in"].join(", ")
 ```
+
+## File jobs
+
+Upload a CSV or XLSX file (up to 100 MB and 1,000,000 rows) and get it back
+with gender columns added. One credit per row, charged only if the job
+completes.
+
+```ruby
+job = client.batches.create(
+  "customers.csv",             # a path, a binary String (with filename:) or an IO
+  name_column: "first_name",   # required to start
+  country_column: "country"    # optional: a country code per row
+)
+
+done = client.batches.wait(job["id"]) { |j| puts j["progress"] }
+raise done["error"]["code"] if done["status"] == "failed"
+
+client.batches.download(done["id"], "customers-gender.csv")
+```
+
+`name_column` is required to start: a guessed column that turns out to be
+wrong would spend credits on the wrong data. To see the columns and the cost
+first, upload with `start: false`, read `job["inspection"]`, then call
+`client.batches.start(job["id"], name_column: ...)`.
+
+`create` sends an `Idempotency-Key` and retries network errors and 502/503/504
+with the same key, so a retry never opens a second job. Pass your own
+`idempotency_key:` to keep that guarantee across your own retries.
+
+`wait` returns a failed job rather than raising; branch on
+`job["error"]["code"]`. `cancel` returns the credit of a job that has not
+started, and deletes a finished one. `list(limit:, page:)` includes jobs
+started from the dashboard. Up to three jobs can be queued or running at once;
+a fourth is refused with `429 too_many_batches`.
+
+The result appends `gender`, `probability`, `sample_size`, `country`, `source`,
+`matched_as`, `first_name`, `middle_name`, `last_name` and `name_type` to every
+row. A CSV result starts with a UTF-8 byte order mark; read it with
+`File.read(path, encoding: "bom|utf-8")`.
+
+## Webhooks
+
+Add an endpoint under Webhooks in the dashboard, and NameGender sends a signed
+`POST` to it when a file job completes or fails, and when credits are about to
+run out (`credits.low`) or have run out (`credits.depleted`, checked hourly).
+`NameGender::Webhooks.verify` checks the signature and the timestamp, and
+returns the event.
+
+```ruby
+require "sinatra"
+require "namegender"
+
+post "/namegender" do
+  begin
+    event = NameGender::Webhooks.verify(
+      request.body.read,   # the raw body, not a parsed params hash (request.raw_post in Rails)
+      request.env["HTTP_NAMEGENDER_SIGNATURE"],
+      ENV.fetch("NAMEGENDER_WEBHOOK_SECRET")
+    )
+  rescue NameGender::WebhookVerificationError
+    halt 400
+  end
+
+  if event["type"] == "batch.completed"
+    job = event["data"]["object"]   # the job, as batches.get returns it
+    # ...
+  end
+  204
+end
+```
+
+The signature covers the exact bytes sent: parsing the JSON and serialising it
+again changes them, and the check fails. Answer quickly and do slow work
+afterwards. Anything other than a 2xx within 10 seconds is retried, up to 8
+attempts over about 45 hours. Use `event["id"]` (also the `NameGender-Event-Id`
+header) to ignore a delivery you have already handled: a retry carries the same
+id, and order is not guaranteed.

data/lib/namegender.rb

@@ -1,5 +1,7 @@
 require "json"
 require "net/http"
+require "openssl"
+require "securerandom"
 require "uri"
 
 module NameGender
@@ -10,27 +12,37 @@ module NameGender
     end
   end
 
+  # The request is not a genuine NameGender webhook. Answer it with 400.
+  class WebhookVerificationError < Error; end
+
   class Client
     def initialize(api_key, base_url: "https://namegender.com/api/v1")
       raise ArgumentError, "api_key is required" if api_key.to_s.empty?
       @api_key, @base_url = api_key, base_url.sub(%r{/$}, "")
     end
 
-    # `options` are sent as-is: `ai_fallback: true` falls back to a language
-    # model for names not in the database (needs AI consent on the account),
-    # `best_guess: true` returns the most likely gender even below the
-    # probability threshold. Any non-2xx response raises NameGender::Error.
-    def name(value, country: nil, **options)
-      post("/gender", { name: value, country: country }.merge(options).compact)
+    # `country` is an ISO 3166-1 alpha-2 code. Without it, `locale` (a
+    # language tag such as "it-IT" or "pt_BR"; a tag without a region, "en",
+    # sets no country) and then `ip` (the end user's IP address, not stored by
+    # the API) supply one: country > locale > ip. The result's
+    # "country_source" says which was used ("country", "locale", "ip" or nil).
+    #
+    # Other `options` are sent as-is: `ai_fallback: true` falls back to a
+    # language model for names not in the database (needs AI consent on the
+    # account), `best_guess: true` returns the most likely gender even below
+    # the probability threshold. Any non-2xx response raises NameGender::Error.
+    def name(value, country: nil, locale: nil, ip: nil, **options)
+      post("/gender", { name: value, country: country, locale: locale, ip: ip }.merge(options).compact)
     end
-    def email(value, country: nil, **options)
-      post("/gender/email", { email: value, country: country }.merge(options).compact)
+    def email(value, country: nil, locale: nil, ip: nil, **options)
+      post("/gender/email", { email: value, country: country, locale: locale, ip: ip }.merge(options).compact)
     end
-    def username(value, country: nil, **options)
-      post("/gender/username", { username: value, country: country }.merge(options).compact)
+    def username(value, country: nil, locale: nil, ip: nil, **options)
+      post("/gender/username", { username: value, country: country, locale: locale, ip: ip }.merge(options).compact)
     end
-    def bulk(values, country: nil, type: "name", **options)
-      post("/gender/bulk", { names: Array(values), country: country, type: type }.merge(options).compact)
+    # `country`, `locale` and `ip` apply to every name in the list.
+    def bulk(values, country: nil, locale: nil, ip: nil, type: "name", **options)
+      post("/gender/bulk", { names: Array(values), country: country, locale: locale, ip: ip, type: type }.merge(options).compact)
     end
     # Country distribution of a name. Not a country-of-origin or ethnicity
     # inference: "registrations" is counted volume, comparable only among the
@@ -43,23 +55,216 @@ module NameGender
     def account
       request(Net::HTTP::Get, "/me")
     end
+    # File jobs: upload a CSV or XLSX file, get it back with gender columns added.
+    def batches
+      @batches ||= Batches.new(self)
+    end
 
     private
     def post(path, body)
       request(Net::HTTP::Post, path, body)
     end
-    def request(klass, path, body = nil)
+    def request(klass, path, body = nil, raw: nil, headers: {})
+      response = transmit(klass, path, body, raw: raw, headers: headers)
+      # 204 (a cancelled job) has no body.
+      return nil if response.body.to_s.empty?
+      JSON.parse(response.body)
+    rescue JSON::ParserError
+      raise Error.new("NameGender returned invalid JSON", response&.code.to_i)
+    end
+    # `raw` is [bytes, content type] for a body that is not JSON.
+    def transmit(klass, path, body = nil, raw: nil, headers: {})
       uri = URI(@base_url + path)
       req = klass.new(uri)
       req["Accept"] = req["Content-Type"] = "application/json"
       req["Authorization"] = "Bearer #{@api_key}"
-      req.body = JSON.generate(body) if body
+      if raw
+        req.body, req["Content-Type"] = raw
+      elsif body
+        req.body = JSON.generate(body)
+      end
+      headers.each { |key, value| req[key] = value }
       response = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(req) }
-      parsed = JSON.parse(response.body)
-      raise Error.new(parsed["message"] || "HTTP #{response.code}", response.code.to_i, parsed) unless response.is_a?(Net::HTTPSuccess)
-      parsed
-    rescue JSON::ParserError
-      raise Error.new("NameGender returned invalid JSON", response&.code.to_i)
+      return response if response.is_a?(Net::HTTPSuccess)
+      begin
+        parsed = JSON.parse(response.body.to_s)
+      rescue JSON::ParserError
+        raise Error.new("NameGender returned invalid JSON", response.code.to_i)
+      end
+      message = parsed.is_a?(Hash) && parsed["message"]
+      raise Error.new(message || "HTTP #{response.code}", response.code.to_i, parsed)
+    end
+  end
+
+  # File jobs. Reached as `client.batches`.
+  class Batches
+    FINISHED = %w[completed failed cancelled].freeze
+    # Statuses worth retrying an upload for: the request may never have reached
+    # the application. Everything else (402, 422, 429 too_many_batches) would
+    # fail the same way again.
+    RETRYABLE = [502, 503, 504].freeze
+    NETWORK_ERRORS = [IOError, SystemCallError, SocketError, Timeout::Error, OpenSSL::SSL::SSLError].freeze
+
+    def initialize(client)
+      @client = client
+    end
+
+    # Upload a file and, unless `start: false`, start it.
+    #
+    # `file` is a path (String or Pathname), a binary String (`File.binread`)
+    # together with `filename:`, or an IO. The extension of the file name
+    # (.csv, .xlsx) tells the API the format. `name_column:` is required to
+    # start: a guessed column that is wrong would spend credits on the wrong
+    # data. With `start: false` the job carries "inspection" (columns,
+    # preview, cost) and is started with #start.
+    #
+    # One Idempotency-Key is used for every attempt, so a retry after a
+    # dropped connection returns the first job instead of opening a second
+    # one and reserving credit twice.
+    def create(file, filename: nil, start: true, idempotency_key: nil, retries: 2, **settings)
+      content, name = read_file(file, filename)
+      fields = { "start" => start ? "true" : "false" }
+      settings.each { |key, value| fields[key.to_s] = value.to_s unless value.nil? }
+      raw = multipart(fields, "file", name, content)
+      headers = { "Idempotency-Key" => idempotency_key || SecureRandom.uuid }
+
+      attempt = 0
+      begin
+        call(Net::HTTP::Post, "/batches", raw: raw, headers: headers)
+      rescue Error => e
+        raise unless RETRYABLE.include?(e.status) && attempt < retries
+        pause(2**attempt); attempt += 1
+        retry
+      rescue *NETWORK_ERRORS
+        raise unless attempt < retries
+        pause(2**attempt); attempt += 1
+        retry
+      end
+    end
+
+    # Start a job uploaded with `start: false`.
+    def start(id, name_column:, **settings)
+      call(Net::HTTP::Post, "/batches/#{escape(id)}/start", { name_column: name_column }.merge(settings).compact)
+    end
+    def get(id)
+      call(Net::HTTP::Get, "/batches/#{escape(id)}")
+    end
+    # Newest first. Includes jobs started from the dashboard.
+    def list(limit: nil, page: nil)
+      query = URI.encode_www_form({ limit: limit, page: page }.compact)
+      call(Net::HTTP::Get, "/batches" + (query.empty? ? "" : "?#{query}"))
+    end
+    # Cancel a job that has not started (credit is returned), or delete a finished one.
+    def cancel(id)
+      call(Net::HTTP::Delete, "/batches/#{escape(id)}")
+      nil
+    end
+
+    # Poll until the job is completed, failed or cancelled, and return it.
+    # A failed job is returned, not raised: check "status" and "error"["code"].
+    # `on_progress` (or a block) is called with the job after every poll.
+    def wait(id, timeout: 3600, on_progress: nil, &block)
+      on_progress ||= block
+      deadline = now + timeout
+      loop do
+        job = get(id)
+        on_progress&.call(job)
+        return job if FINISHED.include?(job["status"]) || job["status"] == "uploaded"
+        seconds = job["poll_after_seconds"] || 5
+        raise Error.new("Timed out waiting for #{id}", 0, job) if now + seconds > deadline
+        pause(seconds)
+      end
+    end
+
+    # The result file as a binary String, or written to `path` (which is then returned).
+    def download(id, path = nil)
+      content = @client.send(:transmit, Net::HTTP::Get, "/batches/#{escape(id)}/result").body.to_s.b
+      return content if path.nil?
+      File.binwrite(path, content)
+      path
+    end
+
+    private
+    def call(klass, path, body = nil, **options)
+      @client.send(:request, klass, path, body, **options)
+    end
+    def pause(seconds)
+      sleep(seconds)
+    end
+    def now
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+    def escape(id)
+      id.to_s.b.gsub(/[^A-Za-z0-9\-._~]/) { |char| format("%%%02X", char.ord) }
+    end
+    def read_file(file, filename)
+      if file.is_a?(String) && file.encoding == Encoding::BINARY
+        raise ArgumentError, "filename is required when file is a binary String" if filename.to_s.empty?
+        [file, filename]
+      elsif file.is_a?(String) || (defined?(Pathname) && file.is_a?(Pathname))
+        [File.binread(file.to_s), filename || File.basename(file.to_s)]
+      elsif file.respond_to?(:read)
+        name = filename || (File.basename(file.path.to_s) if file.respond_to?(:path) && file.path)
+        raise ArgumentError, "filename is required when the IO has no path" if name.to_s.empty?
+        [file.read.to_s.b, name]
+      else
+        raise TypeError, "file must be a path, a binary String or an IO"
+      end
+    end
+    def multipart(fields, file_field, filename, content)
+      boundary = SecureRandom.hex(16)
+      lines = []
+      fields.each { |key, value| lines.push("--#{boundary}", %(Content-Disposition: form-data; name="#{key}"), "", value) }
+      # A quote or line break in a file name would end the header early.
+      safe = filename.to_s.gsub("\\", "\\\\\\\\").gsub('"', "%22").delete("\r\n")
+      head = (lines + [
+        "--#{boundary}",
+        %(Content-Disposition: form-data; name="#{file_field}"; filename="#{safe}"),
+        "Content-Type: application/octet-stream",
+        "", ""
+      ]).join("\r\n")
+      [head.b + content.b + "\r\n--#{boundary}--\r\n".b, "multipart/form-data; boundary=#{boundary}"]
+    end
+  end
+
+  # Webhook signature check.
+  #
+  # Pass the body exactly as received (`request.raw_post` in Rails,
+  # `request.body.read` in Sinatra and Rack). Parsing the JSON and serialising
+  # it again changes the bytes, and the signature no longer matches.
+  module Webhooks
+    module_function
+
+    # Check the NameGender-Signature header and return the parsed event.
+    # During a secret rotation the header carries two v1 values; either one
+    # matching is enough.
+    def verify(payload, signature_header, secret, tolerance: 300, now: nil)
+      raise ArgumentError, "secret is required" if secret.to_s.empty?
+      raise WebhookVerificationError, "Missing NameGender-Signature header" if signature_header.to_s.empty?
+      raise TypeError, "payload must be the raw request body (a String)" unless payload.is_a?(String)
+
+      timestamp = nil
+      signatures = []
+      signature_header.to_s.split(",").each do |part|
+        key, value = part.strip.split("=", 2)
+        if key == "t" && value.to_s.match?(/\A\d+\z/)
+          timestamp = value.to_i
+        elsif key == "v1" && !value.to_s.empty?
+          signatures << value
+        end
+      end
+      raise WebhookVerificationError, "Malformed NameGender-Signature header" if timestamp.nil? || signatures.empty?
+
+      if ((now || Time.now.to_f) - timestamp).abs > tolerance
+        raise WebhookVerificationError, "Webhook timestamp is outside the tolerance window"
+      end
+
+      expected = OpenSSL::HMAC.hexdigest("SHA256", secret.to_s, "#{timestamp}.".b + payload.b)
+      unless signatures.any? { |signature| OpenSSL.secure_compare(expected, signature) }
+        raise WebhookVerificationError, "Webhook signature does not match"
+      end
+
+      JSON.parse(payload.b.force_encoding(Encoding::UTF_8))
     end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: namegender
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.5.0
 platform: ruby
 authors:
 - NameGender
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-16 00:00:00.000000000 Z
+date: 2026-10-06 00:00:00.000000000 Z
 dependencies: []
 description: A dependency-free Ruby client for name, email, username, bulk and country
   distribution lookups through NameGender.