namegender 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5a2b603dfdf3aa0427b5522c68d48ac4d0fcf706991d86b09abad77405e0fdd2
-  data.tar.gz: ec8a07ad241d2c98a6f2dce29f874e22799b42a80ee133ec8db329fb2c844722
+  metadata.gz: 6579682547f30f447af4b578719b7ea7d4f907be742b6a51359f6ddf0d9732d7
+  data.tar.gz: a851e53689d40ec42beeffb8c4b71ffb826280b8e51935d0491994481f87e62a
 SHA512:
-  metadata.gz: f64cf15e7174a98e7ae334d4efc1f62f961ae8dfe0849308e53af49e37d2a07740d45b669a87e5123f86377a7eaa160bdd7856f9fc40a2918bc64db5389d21ae
-  data.tar.gz: b812e005bd8304610ccf7ece873bbf4d2933923fe53c5b4821fa8d55837545e3337094856e42ea34a3e56fd3cff58304d6f53ce94fc2756b473f7cd77de002d0
+  metadata.gz: c9dc314525be03ffaff2506f922e6529b6383dfff4c98a14270a525a8c5a5af157fb43d2aa2bcc41daa37845d71a59802dc19cdc7ed47ee73ef03ca1bfc6c55f
+  data.tar.gz: fc58d715c4215caefe358e9c726702e11621d717d7cf6dfd2c814a80488f9627d7ea01eea571979d2a4d142405147ec0b27b28e797c62082ceb62401a667e3d5

data/README.md

@@ -19,7 +19,7 @@ puts result["gender"], result["probability"], result["sample_size"]
 result = client.name("Andrea", country: "IT", best_guess: true)
 ```
 
-A result carries `query`, `name`, `gender`, `country`, `probability`,
+A result carries `query`, `name`, `first_name`, `middle_name`, `last_name`, `name_type`, `gender`, `country`, `probability`,
 `sample_size`, `took_ms`, `source`, `confidence` and `matched_as`, alongside
 `credits_charged`, `credits_remaining`, `data_version` and `request_id`.
 Success is the HTTP status: any non-2xx response raises `NameGender::Error`
@@ -38,3 +38,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,6 +12,9 @@ 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?
@@ -30,7 +35,7 @@ module NameGender
       post("/gender/username", { username: value, country: country }.merge(options).compact)
     end
     def bulk(values, country: nil, type: "name", **options)
-      post("/gender/bulk", { names: values, country: country, type: type }.merge(options).compact)
+      post("/gender/bulk", { names: Array(values), country: country, 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 +48,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.0
+  version: 0.4.0
 platform: ruby
 authors:
 - NameGender
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-16 00:00:00.000000000 Z
+date: 2026-09-24 00:00:00.000000000 Z
 dependencies: []
 description: A dependency-free Ruby client for name, email, username, bulk and country
   distribution lookups through NameGender.