recapi 0.1.3

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d12730fb7a1d92afff5bc3b2b2383830df795b24fada7104fd8e66c3ac84dc9a
+  data.tar.gz: 5accff282fae359cb6fe664dbebf5957b351df0d155199ce04fa145049ffe3d4
+SHA512:
+  metadata.gz: eb5e428dd2fe97d7bdc35da5838b84bbcf68b1ece0ee137b8bbdd0dd4b75f24d0b3f30f01d392416a2e4034efa94ac8adc1aaceb570366b46fbf8b9012ea5646
+  data.tar.gz: 71cc4af3ea8dd8b424c54e4cf69b94ec50c288fc0dbb7370797064d67cd9d40d06b56c46f94c8d92dd87a237653ef8a808ece2a0c523950ee994d14af2f2ba8b

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 recapi
+
+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,104 @@
+# recapi for Ruby
+
+Ruby client for the recapi recommendation API, for Rails, Solidus, Sinatra
+and background jobs. Ruby 3.1 or newer (tested on 3.1 and 4.0), standard
+library only (`net/http`, `json`), one file, no dependency: it requires only
+default gems, so it loads in a Bundler app whose Gemfile lists nothing else.
+
+Like the [Python](../python/README.md) and [Go](../go/README.md) libraries,
+it keeps each user's decayed **history**
+([docs/history-spec.md](../../docs/history-spec.md)) and sends it with every
+recommendation request, **sends events in the background** in batches of up
+to 1,000 with **retries**, **falls back to popular items** when recapi is
+slow or failing, and **attributes** events on recommended items to the
+recommendation that showed them (the dashboard's clicks and conversions). It
+passes the shared vectors in [`spec/`](../../spec).
+
+## Install
+
+Until the library is published as a gem, recapi serves it as one file (the
+dashboard's quick start shows the line with your address). In a Rails app,
+save it as `lib/recapi.rb`:
+
+```sh
+curl -fLo lib/recapi.rb https://api.<your-domain>/sdk/ruby/recapi-0.1.3.rb
+```
+
+Once it is published on RubyGems (production releases publish it:
+[docs/deployment.md](../../docs/deployment.md#publishing-the-ruby-library)),
+`gem "recapi"` in your Gemfile, or `gem install recapi`, installs the same
+file as a gem, and `require "recapi"` loads it.
+
+## Quick start
+
+```ruby
+# config/initializers/recapi.rb: one client per process, shared by its threads.
+require Rails.root.join("lib/recapi").to_s
+
+# A secret key (rk_sec_…): it stays on your server.
+RECAPI = Recapi::Client.new(ENV.fetch("RECAPI_KEY"), "https://api.example.com",
+                            store: Rails.cache, logger: Rails.logger)
+```
+
+```ruby
+# Queued, sent in the background. Levels: :view, :cart, :purchase, :reject or -10..10.
+RECAPI.track(product.id, :view, user_id: current_user&.id, anon_id: cookies[:visitor])
+
+recs = RECAPI.recommend(user_id: current_user.id, count: 4)
+recs.items.each do |item|
+  item.item_id   # a String, as every id recapi returns
+  item.metadata  # the item's stored object (a Hash), or nil
+  # why it is listed ("for_you", "similar", "trending"...), safe to show anyone: map the codes you
+  # want to your own label (docs/api.md, "Reason codes"), and show none for a code you don't map.
+  label = LABELS[item.why]
+end
+```
+
+Ids may be strings or integers (an ActiveRecord id): they travel as strings.
+
+## Calls
+
+A refused argument (an invalid id or level) raises `ArgumentError`, and an
+API failure `Recapi::Error` (`code`, `status`, `retry_after`, `retryable?`,
+`outage?`).
+
+| Call | What it does |
+|---|---|
+| `track(item_id, level, user_id:, anon_id:, recommendation_id:)` | Records an interaction: `level` -10 to 10 or `:view` (3), `:cart` (5), `:purchase` (10), `:reject` (-10: never recommend the item to this user again until a positive event on it). The history changes at once; a background thread sends the event within 2 s (at once when a batch of 1,000 is full). |
+| `flush` | Sends the queued events now, with retries (end of a job). A network error, 429 or 5xx is retried 3 times (0.5 s, 1 s, 2 s with jitter, or the `Retry-After`, at most 8 s), then the events stay queued and the sender backs off up to a minute; any other error drops them (logged). |
+| `close` | Stops the sender and sends what is queued, one try per batch. It runs by itself at exit. |
+| `recommend(user_id:, anon_id:, count:, placement:, tags_any:, tags_all:, exclude:, context_item_id:, discovery:)` | A `Recapi::Recommendations` (`recommendation_id`, `fallback?`, `items`). At most 1.5 s; on a network error, timeout or 5xx it returns popular items (`fallback?`, no id), or no item when recapi is down: hide the slot. A 4xx or 429 raises. |
+| `identify(anon_id, user_id)` | At login: the visitor's history and shown items become the user's. The user's first restore from recapi then leaves that visitor's browsing out, so it doesn't count twice. |
+| `popular(count:, tags_any:, tags_all:)` | Popular items, for pages without a user. |
+| `upsert_items(items)` | Creates or replaces items (hashes of `item_id`, `title`, `tags`, `metadata`…), 1,000 per request, retried like events. Returns how many were stored. |
+| `delete_user(user_id)` | Erases a user's events in recapi and their state in the store, retried like events. |
+
+`Recapi::Client.new(api_key, base_url, store:, timeout:, flush_interval:,
+max_batch:, logger:)` sets the options. The default `Recapi::MemoryStore`
+keeps the 10,000 most recent users in the process; pass `Rails.cache` (it
+has `read`/`write`/`delete`) or a Redis client (`get`/`set`/`del`) when
+several processes serve the same users. It stores the same JSON as the
+Python library, so both can share one store. Puma's threads share one
+client; a forked worker (Puma cluster, Unicorn, Passenger) starts its own
+queue and sender at its first call. Proxies come from `HTTPS_PROXY`,
+`HTTP_PROXY` and `NO_PROXY`, as `Net::HTTP` reads them. Failures are logged
+to `logger:`, anything with `warn` and `error` (`Rails.logger`, a
+`Logger`); without one they go to `$stderr` as `recapi: …` lines.
+
+## Development
+
+`../../scripts/ruby.sh -w test/run.rb [filter]` runs the tests (`make
+test-sdk` does) against a fake API on a local socket. The autopilot
+containers have no Ruby: `scripts/ruby.sh` then fetches Debian's ruby3.1
+once and runs it without RubyGems, so the tests have their own small runner
+(`test/test_case.rb`), no minitest; `test/gem_test.rb` loads RubyGems itself
+to build the gem from `recapi.gemspec` (`lib/recapi.rb`, this README and the
+licence). The API embeds `lib/recapi.rb` and
+serves it (`server/internal/rubysdk`): any change to it needs a new
+`Recapi::VERSION` and the line `go test ./internal/rubysdk` (in `server/`)
+prints for `published.json`.
+
+`RECAPI_KEY=rk_sec_… ../../scripts/ruby.sh sample.rb [item ids]` runs
+[`sample.rb`](sample.rb) against staging (`RECAPI_URL` picks another API):
+it tracks views for a new visitor, then prints their recommendations and the
+popular items.

data/lib/recapi.rb

@@ -0,0 +1,1192 @@
+# frozen_string_literal: true
+
+# The recapi client for Ruby servers (Rails, Solidus, Sinatra, jobs): history,
+# batching, retries and fallback. A port of sdk/python, which behaves like the
+# JS SDK; spec/client_vectors.json and spec/history_vectors.json pin what they
+# must agree on. Standard library only: it adds no gem to an app.
+#
+#   require_relative "recapi"   # or require "recapi"
+#   RECAPI = Recapi::Client.new(ENV.fetch("RECAPI_KEY"), "https://api.example.com")
+#   RECAPI.track("sku-1", :view, user_id: current_user.id)
+#   RECAPI.recommend(user_id: current_user.id, count: 4).items
+
+require "json"
+require "net/http"
+require "openssl"
+require "securerandom"
+require "uri"
+require "digest"
+require "weakref"
+begin
+  # Net::HTTP inflates gzip replies with it, when the Ruby has it.
+  require "zlib"
+rescue LoadError
+  nil
+end
+
+module Recapi
+  VERSION = "0.1.3"
+
+  # Decayed user history, exactly as docs/history-spec.md (times in unix ms).
+  # A port of sdk/python's history.py, snapshot merging included.
+  class History
+    HALF_LIFE_SECONDS = 604_800
+    TOP_K = 50
+    RECENT_SIZE = 20
+    REJECTED_SIZE = 200
+    MAX_ID_BYTES = 256
+    RATE = Math.log(2) / HALF_LIFE_SECONDS
+    # Go's unicode.IsControl, which the API applies to every id: C0, DEL and C1.
+    CONTROL = /[\u0000-\u001f\u007f-\u009f]/.freeze
+
+    # Whether the API accepts value as an id: 1-256 bytes of UTF-8, no controls.
+    def self.id?(value)
+      return false unless value.is_a?(String) && !value.empty? && value.bytesize <= MAX_ID_BYTES
+
+      utf8 = value.encoding == Encoding::UTF_8 ? value : value.dup.force_encoding(Encoding::UTF_8)
+      utf8.valid_encoding? && !CONTROL.match?(utf8)
+    end
+
+    def self.decay(dt_ms)
+      Math.exp(-RATE * (dt_ms / 1000.0))
+    end
+
+    def self.time?(value)
+      (value.is_a?(Integer) || value.is_a?(Float)) && value.finite?
+    end
+
+    def self.weight?(value)
+      time?(value) && value >= 0
+    end
+
+    # top: item => [score, t]; recent: [[item, t]] oldest first; rejected:
+    # item => time of the newest rejection; last_t: the newest event applied
+    # to the recent list (nil when unknown).
+    attr_accessor :top, :recent, :rejected, :last_t
+
+    def initialize
+      @top = {}
+      @recent = []
+      @rejected = {}
+      @last_t = nil
+    end
+
+    # Nothing to send, so the server uses its stored history. Rejections alone
+    # don't count: the server still has the user's positive events.
+    def empty?
+      @top.empty? && @recent.empty?
+    end
+
+    # Applies one event: level 0 changes nothing, a negative level is a rejection.
+    def apply(item, level, t)
+      return if level.zero?
+      return reject(item, t) if level.negative?
+
+      mark = @rejected[item]
+      unless mark.nil?
+        return if t < mark
+
+        @rejected.delete(item)
+      end
+      current = @top[item]
+      @top[item] =
+        if current.nil?
+          [level.to_f, t]
+        elsif t >= current[1]
+          [current[0] * History.decay(t - current[1]) + level, t]
+        else
+          [current[0] + level * History.decay(current[1] - t), current[1]]
+        end
+      if @last_t.nil? || t >= @last_t
+        @recent = @recent.reject { |entry| entry[0] == item }
+        @recent << [item, t]
+        @recent = @recent.last(RECENT_SIZE)
+        @last_t = t
+      end
+      prune(t)
+    end
+
+    # [item, weight at now, t] by weight desc, ties by item id asc.
+    def ranked(now)
+      entries = @top.map { |item, (s, t)| [item, s * History.decay(now - t), t] }
+      entries.sort_by { |item, w, _| [-w, item] }
+    end
+
+    # The rejected items, oldest mark first, ties by item id.
+    def rejected_order
+      @rejected.keys.sort_by { |item| [@rejected[item], item] }
+    end
+
+    # The request's history and recent, and the rejected items. Weights are
+    # decayed to now and rounded half up to 4 decimals like JS Math.round
+    # (Ruby's round rounds half away from zero); ages are whole seconds, never negative.
+    def wire(now)
+      history = ranked(now).first(TOP_K).map do |item, weight, t|
+        [item, (weight * 1e4 + 0.5).floor / 1e4, [0, ((now - t) / 1000.0).floor].max]
+      end
+      [history, @recent.last(RECENT_SIZE).map(&:first), rejected_order]
+    end
+
+    # A history from the server's snapshot, skipping invalid entries. Each top
+    # entry is a score at as_of, each rejected item a mark at as_of. last_t
+    # stays unknown: as_of is the server clock, and a local clock behind it
+    # would see every new event as out of order.
+    def self.from_snapshot(snapshot)
+      state = new
+      return state unless snapshot.is_a?(Hash) && time?(snapshot["as_of"])
+
+      as_of = snapshot["as_of"]
+      list(snapshot["top"]).each do |e|
+        state.top[e[0]] = [e[1].to_f, as_of] if e.is_a?(Array) && e.size >= 2 && id?(e[0]) && weight?(e[1])
+      end
+      list(snapshot["recent"]).each do |item|
+        state.recent << [item, as_of] if id?(item) && state.recent.none? { |entry| entry[0] == item }
+      end
+      state.recent = state.recent.last(RECENT_SIZE)
+      list(snapshot["rejected"]).each { |item| state.rejected[item] = as_of if id?(item) }
+      state.send(:prune, as_of)
+      state.send(:prune_rejected)
+      state
+    end
+
+    # The union of two histories built from disjoint events. Top scores add
+    # up, expressed at the later of the two times; the recent lists are
+    # interleaved by time (self first on ties); rejection marks are united, and
+    # a mark older than the item's merged entry is dropped, otherwise the item
+    # leaves the top and the recent list.
+    def merge(other, now)
+      out = History.new
+      out.top = @top.dup
+      other.top.each do |item, (s, t)|
+        mine = out.top[item]
+        if mine.nil?
+          out.top[item] = [s, t]
+          next
+        end
+        later = [t, mine[1]].max
+        out.top[item] = [s * History.decay(later - t) + mine[0] * History.decay(later - mine[1]), later]
+      end
+
+      out.rejected = @rejected.dup
+      other.rejected.each { |item, t| out.rejected[item] = [t, out.rejected.fetch(item, t)].max }
+      out.rejected.to_a.each do |item, t|
+        entry = out.top[item]
+        if !entry.nil? && entry[1] > t
+          out.rejected.delete(item)
+        else
+          out.top.delete(item)
+        end
+      end
+
+      by_item = {}
+      (@recent + other.recent).each_with_index do |(item, t), order|
+        existing = by_item[item]
+        by_item[item] = [t, order] if existing.nil? || t > existing[0]
+      end
+      # Rejected items go before the trim, so they don't cost the list its places.
+      kept = by_item.reject { |item, _| out.rejected.key?(item) }.map { |item, (t, order)| [t, order, item] }.sort
+      out.recent = kept.last(RECENT_SIZE).map { |t, _, item| [item, t] }
+
+      times = [@last_t, other.last_t].compact
+      out.last_t = times.max
+      out.send(:prune, now)
+      out.send(:prune_rejected)
+      out
+    end
+
+    # Merges a server snapshot, keeping the items rejected here rejected: a
+    # local rejection is usually one the server hasn't stored yet, so it wins
+    # over the snapshot's score.
+    def merge_snapshot(snapshot, now)
+      trimmed = snapshot.dup
+      trimmed.top = snapshot.top.reject { |item, _| @rejected.key?(item) }
+      merge(trimmed, now)
+    end
+
+    # The JSON-safe stored form (raw scores), shaped like sdk/python's.
+    def encode
+      {
+        "top" => @top.map { |item, (s, t)| [item, s, t] },
+        "recent" => @recent.map { |item, t| [item, t] },
+        "rejected" => @rejected.map { |item, t| [item, t] },
+        "lastT" => @last_t
+      }
+    end
+
+    # Inverse of encode; nil for any malformed field. A state stored before
+    # rejections existed has no "rejected".
+    def self.decode(raw)
+      return nil unless valid_encoding?(raw)
+
+      state = new
+      raw["top"].each { |item, s, t| state.top[item] = [s.to_f, t] }
+      state.recent = raw["recent"].map { |item, t| [item, t] }
+      raw.fetch("rejected", []).each { |item, t| state.rejected[item] = t }
+      state.last_t = raw["lastT"]
+      state.send(:prune_rejected)
+      state
+    end
+
+    def self.valid_encoding?(raw)
+      return false unless raw.is_a?(Hash) && raw.key?("lastT")
+
+      top = raw["top"]
+      recent = raw["recent"]
+      rejected = raw.fetch("rejected", [])
+      return false unless [top, recent, rejected].all? { |v| v.is_a?(Array) }
+
+      (raw["lastT"].nil? || time?(raw["lastT"])) &&
+        top.all? { |e| pair?(e, 3) && weight?(e[1]) && time?(e[2]) } &&
+        (recent + rejected).all? { |e| pair?(e, 2) && time?(e[1]) }
+    end
+
+    def self.pair?(entry, size)
+      entry.is_a?(Array) && entry.size == size && id?(entry[0])
+    end
+
+    def self.list(value)
+      value.is_a?(Array) ? value : []
+    end
+
+    private_class_method :valid_encoding?, :pair?, :list
+
+    private
+
+    def reject(item, t)
+      # Dropped, not lowered: a lowered score would decay back towards 0.
+      current = @top[item]
+      return if !current.nil? && current[1] > t
+
+      @top.delete(item)
+      @recent = @recent.reject { |entry| entry[0] == item }
+      @rejected[item] = [t, @rejected.fetch(item, t)].max
+      prune_rejected
+    end
+
+    def prune(now)
+      return unless @top.size > TOP_K
+
+      @top = ranked(now).first(TOP_K).to_h { |item, _, _| [item, @top[item]] }
+    end
+
+    def prune_rejected
+      return unless @rejected.size > REJECTED_SIZE
+
+      @rejected = rejected_order.last(REJECTED_SIZE).to_h { |item| [item, @rejected[item]] }
+    end
+  end
+
+  # A failed call. status is 0 when no HTTP response was received. code is the
+  # API's error code (invalid_request, rate_limited, quota_exceeded...) or a
+  # client one: network, timeout, invalid_response.
+  class Error < StandardError
+    attr_reader :code, :status, :retry_after
+
+    def initialize(code, message, status: 0, retry_after: nil)
+      super(message)
+      @code = code
+      @status = status
+      @retry_after = retry_after
+    end
+
+    # Whether trying again later can succeed (quota_exceeded can't until it resets).
+    def retryable?
+      return true if %w[network timeout].include?(@code)
+      return @code != "quota_exceeded" if @status == 429
+
+      @status >= 500
+    end
+
+    # Whether recapi couldn't answer in time or failed on its side. A 429 is
+    # the tenant's own limit and a 4xx an integration bug: a fallback would hide both.
+    def outage?
+      %w[network timeout].include?(@code) || @status >= 500
+    end
+  end
+
+  # One recommended or popular item. metadata is the object stored with the
+  # item (name, picture, link, price...), nil when it has none.
+  #
+  # why is the reason code to turn into a label for visitors: "for_you",
+  # "similar", "next", "bought_together", "trending", "popular", "new",
+  # "explore" or "more" (docs/api.md "Reason codes"), nil when the API sent
+  # none. New codes may be added: show nothing for an unknown one.
+  Item = Struct.new(:item_id, :score, :slot, :metadata, :why, keyword_init: true)
+
+  # A recommendation list. fallback lists are popular items with no id.
+  Recommendations = Struct.new(:recommendation_id, :fallback, :items, keyword_init: true) do
+    alias_method :fallback?, :fallback
+  end
+
+  # In-process store keeping the most recently used max_users users. Pass a
+  # shared one (Redis, Rails.cache) when several processes serve the same users.
+  class MemoryStore
+    def initialize(max_users: 10_000)
+      @max = [1, max_users].max
+      @data = {}
+      @lock = Mutex.new
+    end
+
+    def get(key)
+      @lock.synchronize do
+        value = @data.delete(key)
+        @data[key] = value unless value.nil?
+        value
+      end
+    end
+
+    def set(key, value)
+      @lock.synchronize do
+        @data.delete(key)
+        @data[key] = value
+        @data.delete(@data.first[0]) while @data.size > @max
+      end
+    end
+
+    def delete(key)
+      @lock.synchronize { @data.delete(key) }
+    end
+  end
+
+  # The default logger: warnings and errors as "recapi: ..." lines on $stderr.
+  # Not the standard Logger: Ruby 4.0 made logger a bundled gem, which a
+  # Bundler app without it in its Gemfile can't require.
+  class StderrLogger
+    def warn(message)
+      $stderr.write("#{message}\n")
+    end
+
+    def error(message)
+      $stderr.write("#{message}\n")
+    end
+  end
+
+  # A recapi client, safe to share between threads (Puma); create one per
+  # process. In a forked worker (Unicorn, Puma cluster) it starts afresh.
+  class Client
+    # API limits (docs/api.md).
+    MAX_EVENTS_PER_REQUEST = 1000
+    MAX_ITEMS_PER_REQUEST = 1000
+    MAX_EXCLUDE = 500
+    DEFAULT_COUNT = 10
+    MAX_COUNT = 100
+    # A widget still empty after 1.5 s has lost the user: recommend() gives up
+    # then and falls back, whatever the general timeout (which suits events).
+    RECOMMEND_TIMEOUT = 1.5
+    # The recommended level scale (docs/api.md "Interaction levels"), by name.
+    LEVEL_NAMES = { "view" => 3, "cart" => 5, "purchase" => 10, "reject" => -10 }.freeze
+    # Events waiting for a send: a minute-long outage at 150 events/s fits.
+    MAX_QUEUE = 10_000
+    MAX_FLUSH_BACKOFF = 60.0
+    RETRIES = 3
+    RETRY_BASE = 0.5
+    RETRY_MAX = 8.0
+    # Attribution windows, as in the JS SDK: an event on a shown item within
+    # 30 minutes of the display is the click; after a click, that item's
+    # events are attributed for 24 hours.
+    DISPLAY_WINDOW_MS = 30 * 60 * 1000
+    CLICK_WINDOW_MS = 24 * 60 * 60 * 1000
+    # Shown items remembered per user.
+    MAX_SHOWN_ITEMS = 100
+    PUBLIC_KEY_PREFIX = "rk_pub_"
+    # Open connections kept between calls: one per call in flight at the busiest moment.
+    MAX_IDLE_CONNECTIONS = 16
+    CODE_BY_STATUS = {
+      400 => "invalid_request", 401 => "unauthorized", 403 => "forbidden",
+      404 => "not_found", 413 => "too_large", 429 => "rate_limited"
+    }.freeze
+    # Failures before any usable reply: the request may not have reached the API.
+    NETWORK_ERRORS = [
+      IOError, EOFError, SocketError, SystemCallError, OpenSSL::SSL::SSLError,
+      Net::HTTPBadResponse, Net::ProtocolError, *(Zlib::Error if defined?(Zlib::Error))
+    ].freeze
+    TIMEOUT_ERRORS = [Net::OpenTimeout, Net::ReadTimeout, Net::WriteTimeout].freeze
+    # A connection the server closed while idle fails this way, before any reply.
+    STALE_ERRORS = [EOFError, Errno::ECONNRESET, Errno::EPIPE, Errno::ECONNABORTED].freeze
+    # Made here, not in initialize, whose block would hold the client through
+    # self: the weak reference lets a dropped client be collected.
+    CLOSE_AT_EXIT = lambda do |ref|
+      at_exit do
+        ref.__getobj__.close
+      rescue WeakRef::RefError
+        nil
+      end
+    end
+    private_constant :CLOSE_AT_EXIT
+
+    # api_key: secret key (rk_sec_...): a server can then restore a user's
+    # history from recapi when the store lacks it. base_url: your recapi API
+    # origin. store: per-user state, anything with get/set/delete (a Redis
+    # client) or read/write/delete (Rails.cache); defaults to a MemoryStore.
+    # timeout: per-request seconds (recommend() uses at most 1.5).
+    # flush_interval: seconds between background sends. max_batch: events per
+    # request, at most the API's 1,000. logger: where failures are logged,
+    # anything with warn and error (a Logger, Rails.logger); $stderr by default.
+    def initialize(api_key, base_url, store: nil, timeout: 5.0, flush_interval: 2.0,
+                   max_batch: MAX_EVENTS_PER_REQUEST, logger: nil)
+      raise ArgumentError, "api_key is required" unless api_key.is_a?(String) && !api_key.empty?
+      raise ArgumentError, "base_url is required" unless base_url.is_a?(String) && !base_url.empty?
+
+      @api_key = api_key
+      @base = base_url.chomp("/")
+      @url = URI.parse(@base)
+      unless @url.is_a?(URI::HTTP) && !@url.host.to_s.empty?
+        raise ArgumentError, "base_url must be an http(s) URL"
+      end
+
+      @store = store || MemoryStore.new
+      @timeout = timeout.to_f
+      @interval = flush_interval.to_f
+      @max_batch = max_batch.to_i.clamp(1, MAX_EVENTS_PER_REQUEST)
+      @logger = logger || StderrLogger.new
+      # Two environments' keys may share one Redis: their users must not mix.
+      @prefix = "recapi:#{Digest::SHA256.hexdigest(api_key)[0, 12]}:"
+      # Indirections the tests replace (clock, backoff sleep, jitter).
+      @clock = -> { Process.clock_gettime(Process::CLOCK_REALTIME, :millisecond) }
+      @sleeper = method(:wait)
+      @random = -> { rand }
+      init_threading
+      CLOSE_AT_EXIT.call(WeakRef.new(self))
+    end
+
+    # Records an interaction: the user's history changes at once, the event
+    # is queued. level is an integer -10 to 10 or :view (3), :cart (5),
+    # :purchase (10), :reject (-10: never recommend the item to this user
+    # again until a positive event on it). recommendation_id overrides the
+    # automatic attribution. Ids may be strings or integers.
+    def track(item_id, level, user_id: nil, anon_id: nil, recommendation_id: nil)
+      level = level_value(level)
+      item_id = id_string(item_id)
+      raise ArgumentError, "item_id #{ID_RULE}" unless History.id?(item_id)
+
+      user_id, anon_id, recommendation_id = check_ids(user_id: user_id, anon_id: anon_id,
+                                                      recommendation_id: recommendation_id)
+      t = now_ms
+      attributed = recommendation_id
+      key = key_for(user_id, anon_id)
+      unless key.nil?
+        with_locks(key) do
+          state = load(key)
+          state.history.apply(item_id, level, t)
+          entry = state.shown[item_id]
+          # An explicit id of the recommendation that showed the item is
+          # still the click on it; another id leaves the entry alone.
+          if recommendation_id.nil? || (entry && entry[0] == recommendation_id)
+            attributed = attribute(entry, level, t) || recommendation_id
+          end
+          save(key, state, t)
+        end
+      end
+      enqueue(compact(
+                "item_id" => item_id, "level" => level, "user_id" => user_id, "anon_id" => anon_id,
+                "recommendation_id" => attributed, "timestamp" => iso(t), "event_id" => SecureRandom.uuid
+              ))
+      nil
+    end
+
+    # Sends every queued event now, with retries (end of a job or a request in
+    # a worker). Never raises: failures are logged, retryable batches stay queued.
+    def flush
+      drain(retry_errors: true)
+      nil
+    end
+
+    # Stops the sender and sends what is queued, one try per batch (runs at
+    # exit). No retries, so a deploy never waits on a recapi outage.
+    def close
+      # In a forked worker, the parent's queue and closed state are not this one's.
+      forked
+      closing = false
+      @mutex.synchronize do
+        closing = !@closed
+        # Also ends a send's retry sleep, so close waits for at most one try.
+        @closed = true
+        @cond.broadcast
+      end
+      drain(retry_errors: false) if closing
+      # Also on a later close (the one at exit): calls made after the first
+      # may have opened connections again.
+      idle = @idle_lock.synchronize { @idle.slice!(0..) }
+      idle.each { |conn| finish(conn) }
+      nil
+    end
+
+    # Personalised recommendations for a user (or a visitor's anon_id). Sends
+    # the history from the store; without one, recapi uses its stored history
+    # for user_id and returns it for the store. A history the store started
+    # without it (a track() or identify() came first) gets recapi's fetched
+    # once, within the same deadline, and merged in. No retry, at most 1.5 s:
+    # on a network error, timeout or 5xx it returns popular items (fallback,
+    # no id) and logs the error. If those fail too (recapi is down), the list
+    # is empty: hide the slot. A 4xx or 429 raises: a fallback would hide an
+    # integration bug or a plan limit.
+    def recommend(user_id: nil, anon_id: nil, count: 0, placement: nil, tags_any: nil, tags_all: nil,
+                  exclude: nil, context_item_id: nil, discovery: nil)
+      deadline = monotonic + recommend_timeout
+      user_id, anon_id = check_ids(user_id: user_id, anon_id: anon_id)
+      context_item_id = id_string(context_item_id)
+      exclude = exclude&.map { |item| id_string(item) }
+      key = key_for(user_id, anon_id)
+      t = now_ms
+      state = key.nil? ? UserState.new : load(key)
+      if user_id && !state.restored && !state.history.empty? && !@api_key.start_with?(PUBLIC_KEY_PREFIX)
+        state = restore(key, user_id, state, deadline, t)
+      end
+      history, recent, rejected = state.history.wire(t)
+      excluded = with_rejected(exclude, rejected)
+      begin
+        response = request(
+          "POST", "/v1/recommendations",
+          timeout: deadline - monotonic,
+          body: compact(
+            "user_id" => user_id, "anon_id" => anon_id, "placement" => placement,
+            "count" => count.to_i.zero? ? nil : count, "tags_any" => non_empty(tags_any),
+            "tags_all" => non_empty(tags_all), "exclude" => excluded, "context_item_id" => context_item_id,
+            "history" => history, "recent" => recent, "discovery" => discovery
+          )
+        )
+        rec_id, items = parse_recommendations(response)
+      rescue Error => e
+        raise unless e.outage?
+
+        return fallback(e, count, excluded, context_item_id, tags_any, tags_all)
+      end
+
+      unless key.nil?
+        with_locks(key) do
+          state = load(key)
+          items.each do |item|
+            state.shown.delete(item.item_id)
+            state.shown[item.item_id] = [rec_id, t]
+          end
+          state.shown.delete(state.shown.first[0]) while state.shown.size > MAX_SHOWN_ITEMS
+          # Only trusted when we sent nothing; merged, never replacing what
+          # was tracked while the request was in flight, and only once: a
+          # concurrent first call may have merged it already.
+          snapshot = response["history"]
+          done = state.restored && !state.history.empty?
+          if history.empty? && recent.empty? && snapshot.is_a?(Hash) && !done
+            state.history = state.history.merge_snapshot(History.from_snapshot(snapshot), t)
+            state.restored = true
+          end
+          save(key, state, t)
+        end
+      end
+      Recommendations.new(recommendation_id: rec_id, fallback: false, items: items)
+    end
+
+    # Call at login: the visitor's history and shown items become the user's.
+    # Merged into what the store has for user_id (scores add up, as in the
+    # history spec), then the visitor's entry is deleted. Without it, a
+    # visitor's clicks stop counting once they log in.
+    def identify(anon_id, user_id)
+      user_id, anon_id = check_ids(user_id: user_id, anon_id: anon_id)
+      raise ArgumentError, "anon_id and user_id are required" if anon_id.nil? || user_id.nil?
+
+      visitor = key_for(nil, anon_id)
+      user = key_for(user_id, nil)
+      t = now_ms
+      with_locks(visitor, user) do
+        guest = load(visitor)
+        next if guest.history.empty? && guest.history.rejected.empty? && guest.shown.empty?
+
+        state = load(user)
+        state.history = state.history.merge(guest.history, t)
+        # recapi's snapshot, fetched later, holds this visitor's browsing too.
+        state.anon_id = anon_id unless state.restored
+        # Oldest display first, as recommend() keeps them; an item's later display wins.
+        shown = (state.shown.to_a + guest.shown.to_a).each_with_index.sort_by { |(_, e), i| [e[1], i] }
+        state.shown = {}
+        shown.each do |(item, entry), _|
+          state.shown.delete(item)
+          state.shown[item] = entry
+        end
+        save(user, state, t)
+        begin
+          store_call(:delete, visitor)
+        rescue StandardError => e
+          @logger.error("recapi: could not delete the visitor's stored state: #{e.message}")
+        end
+      end
+      nil
+    end
+
+    # Non-personalised popular items, for pages without a user (no retry).
+    def popular(count: DEFAULT_COUNT, tags_any: nil, tags_all: nil)
+      fetch_popular(count, tags_any, tags_all, nil)
+    end
+
+    # Creates or replaces items (hashes of the API's item fields: item_id,
+    # tags, metadata...), 1,000 per request. Retried like events. Returns how
+    # many were stored; an invalid item raises, and nothing of its batch of
+    # 1,000 is stored.
+    def upsert_items(items)
+      upserted = 0
+      items.each_slice(MAX_ITEMS_PER_REQUEST) do |batch|
+        body = { "items" => batch.map { |item| item.to_h.transform_keys(&:to_s) } }
+        response = with_retry { request("POST", "/v1/items:batch", body: body) }
+        upserted += response.is_a?(Hash) ? response.fetch("upserted", 0).to_i : 0
+      end
+      upserted
+    end
+
+    # Erases a user's events in recapi (GDPR) and their state in the store.
+    def delete_user(user_id)
+      user_id = id_string(user_id)
+      raise ArgumentError, "user_id #{ID_RULE}" unless History.id?(user_id)
+
+      with_retry { request("DELETE", "/v1/users/#{escape(user_id)}") }
+      begin
+        store_call(:delete, key_for(user_id, nil))
+      rescue StandardError => e
+        @logger.error("recapi: could not delete the user's stored state: #{e.message}")
+      end
+      nil
+    end
+
+    ID_RULE = "must be 1-256 bytes of UTF-8 without control characters"
+
+    # What the store keeps per user: the history and the shown items. shown
+    # maps item => [recommendation id, shown at, clicked at?], oldest first.
+    # restored is set once the history holds recapi's stored one. anon_id is
+    # the visitor identify merged in before that: recapi's snapshot also holds
+    # that visitor's browsing, so the restore asks it to leave it out.
+    class UserState
+      attr_accessor :history, :shown, :restored, :anon_id
+
+      def initialize(history = nil, shown = nil, restored = false, anon_id = nil)
+        @history = history || History.new
+        @shown = shown || {}
+        @restored = restored
+        @anon_id = anon_id
+      end
+
+      def dump(now)
+        shown = @shown.select { |_, entry| Client.attributable?(entry, now) }.map { |item, entry| [item, *entry] }
+        state = { "history" => @history.encode, "shown" => shown.last(MAX_SHOWN_ITEMS) }
+        state["restored"] = true if @restored
+        state["anon_id"] = @anon_id if @anon_id && !@anon_id.empty?
+        JSON.generate(state)
+      end
+
+      # nil when raw is malformed.
+      def self.parse(raw)
+        data = JSON.parse(raw)
+        return nil unless data.is_a?(Hash) && data["shown"].is_a?(Array)
+
+        history = History.decode(data["history"])
+        return nil if history.nil?
+
+        shown = {}
+        data["shown"].each do |e|
+          shown[e[0]] = e[1..] if e.is_a?(Array) && e.size.between?(3, 4) && History.id?(e[0])
+        end
+        anon_id = data["anon_id"]
+        new(history, shown, data["restored"] == true, History.id?(anon_id) ? anon_id : nil)
+      rescue JSON::ParserError, TypeError
+        nil
+      end
+    end
+
+    def self.attributable?(entry, t)
+      return t - entry[1] <= DISPLAY_WINDOW_MS if entry.size < 3
+
+      t - entry[2] <= CLICK_WINDOW_MS
+    end
+
+    private
+
+    def init_threading
+      # Also runs in a forked worker: the parent's queue is the parent's to
+      # send, its sender thread did not survive the fork, and its connections
+      # must not be shared.
+      @pid = Process.pid
+      @user_locks = Array.new(64) { Mutex.new }
+      @queue = []
+      @mutex = Mutex.new
+      @cond = ConditionVariable.new
+      @send_lock = Mutex.new
+      @thread = nil
+      @failures = 0
+      @closed = false
+      @idle = []
+      @idle_lock = Mutex.new
+    end
+
+    def forked
+      init_threading if @pid != Process.pid
+    end
+
+    def now_ms
+      @clock.call
+    end
+
+    def monotonic
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    def recommend_timeout
+      [@timeout, RECOMMEND_TIMEOUT].min
+    end
+
+    # Waits seconds; returns true, at once, when interruptible and the client
+    # is or becomes closed.
+    def wait(seconds, interruptible)
+      return sleep(seconds) && false unless interruptible
+
+      deadline = monotonic + seconds
+      @mutex.synchronize do
+        until @closed
+          left = deadline - monotonic
+          return false if left <= 0
+
+          @cond.wait(@mutex, left)
+        end
+        true
+      end
+    end
+
+    # --- events ---------------------------------------------------------------
+
+    def enqueue(event)
+      forked
+      closed = @mutex.synchronize do
+        if @thread.nil? && !@closed
+          @thread = Thread.new { run }
+          @thread.name = "recapi-sender"
+          @thread.report_on_exception = false
+        end
+        @queue << event
+        drop_overflow if @queue.size > MAX_QUEUE
+        @cond.broadcast if @queue.size >= @max_batch
+        @closed
+      end
+      drain(retry_errors: false) if closed
+    end
+
+    def drop_overflow
+      dropped = @queue.size - MAX_QUEUE
+      @queue.shift(dropped)
+      @logger.warn("recapi: event queue full, dropped the #{dropped} oldest events")
+    end
+
+    def run
+      loop do
+        @mutex.synchronize do
+          deadline = monotonic + [@interval * 2**@failures, MAX_FLUSH_BACKOFF].min
+          # A full batch goes at once, except after a failure: then the
+          # backoff holds, or a down API would be hammered.
+          until @closed || (@failures.zero? && @queue.size >= @max_batch)
+            left = deadline - monotonic
+            break if left <= 0
+
+            @cond.wait(@mutex, left)
+          end
+          return if @closed
+        end
+        drain(retry_errors: true)
+      end
+    end
+
+    def drain(retry_errors:)
+      forked
+      @send_lock.synchronize do
+        loop do
+          batch = @mutex.synchronize { @queue.shift(@max_batch) }
+          return if batch.empty?
+
+          begin
+            send_events(batch, retry_errors)
+          rescue StandardError => e
+            if e.is_a?(Error) && !e.retryable?
+              @logger.error("recapi: dropped #{batch.size} events: #{e.message}")
+              next
+            end
+            # Anything else keeps the batch, a bug of ours included: event ids
+            # make a resend harmless, and a dead sender would lose every event.
+            @logger.error("recapi: unexpected error sending events: #{e.class}: #{e.message}") unless e.is_a?(Error)
+            @mutex.synchronize do
+              @queue.unshift(*batch)
+              drop_overflow if @queue.size > MAX_QUEUE
+              @failures += 1
+            end
+            @logger.warn("recapi: sending #{batch.size} events failed, kept: #{e.message}")
+            return
+          end
+          @mutex.synchronize { @failures = 0 }
+        end
+      end
+    end
+
+    def send_events(events, retry_errors)
+      send = -> { request("POST", "/v1/events", body: { "events" => events }) }
+      begin
+        response = retry_errors ? with_retry(interruptible: true, &send) : send.call
+      rescue Error => e
+        # Over the API's body limit (ids mostly quotes or backslashes, which
+        # JSON escapes): halves fit where the whole didn't. If the second half
+        # fails, the batch is kept whole; event ids make the resend harmless.
+        raise if e.status != 413 || events.size < 2
+
+        half = events.size / 2
+        send_events(events[0, half], retry_errors)
+        send_events(events[half..], retry_errors)
+        return
+      end
+      rejected = response.is_a?(Hash) ? response["rejected"] : nil
+      return unless rejected.is_a?(Array) && !rejected.empty?
+
+      # Invalid events are reported, never retried: they would fail again.
+      detail = rejected.first(5).map do |r|
+        r.is_a?(Hash) && r["index"].is_a?(Integer) ? r.merge("event" => events[r["index"]]) : r
+      end
+      @logger.error("recapi: #{rejected.size} event(s) rejected: #{JSON.generate(detail)}")
+    end
+
+    # Calls the block, retrying retryable errors with jittered exponential
+    # backoff. Retry-After wins over the backoff, and both are capped at 8 s.
+    # Once the client closes (interruptible), the last error is raised instead.
+    def with_retry(interruptible: false)
+      attempt = 0
+      begin
+        yield
+      rescue Error => e
+        raise if attempt >= RETRIES || !e.retryable?
+
+        backoff = RETRY_BASE * 2**attempt * (0.5 + @random.call / 2.0)
+        attempt += 1
+        raise if @sleeper.call([RETRY_MAX, e.retry_after || backoff].min, interruptible)
+
+        retry
+      end
+    end
+
+    # --- recommendations ------------------------------------------------------
+
+    def fallback(error, count, excluded, context_item_id, tags_any, tags_all)
+      # The requested length without the excluded items, so a few more are
+      # asked for. 0 is the recommendations default; popular refuses it.
+      n = count.to_i.zero? ? DEFAULT_COUNT : count.to_i
+      skip = (excluded || []).to_h { |item| [item, true] }
+      skip[context_item_id] = true unless context_item_id.nil?
+      begin
+        popular = fetch_popular([n + skip.size, MAX_COUNT].min, tags_any, tags_all, recommend_timeout)
+      rescue Error => e
+        # recapi is down altogether: an empty list the page can hide beats an
+        # exception that fails the whole page.
+        @logger.warn("recapi: recommendations failed (#{error.message}), popular too, served no items: #{e.message}")
+        return Recommendations.new(recommendation_id: nil, fallback: true, items: [])
+      end
+      @logger.warn("recapi: recommendations failed, served popular items: #{error.message}")
+      items = popular.reject { |item| skip.key?(item.item_id) }.first(n)
+      Recommendations.new(recommendation_id: nil, fallback: true, items: items)
+    end
+
+    # Merges recapi's stored history into a local one that lacks it (a fresh
+    # store). The recommendation's reply carries it only when the request
+    # sends no history, which would drop this one. So it is asked for apart,
+    # once: a failure leaves the state as it was, to be tried on the next call.
+    def restore(key, user_id, state, deadline, t)
+      begin
+        # Half the time left, so the recommendation itself still fits.
+        query = state.anon_id ? { "anon_id" => state.anon_id } : nil
+        path = "/v1/users/#{escape(user_id)}/history"
+        snapshot = request("GET", path, query: query, timeout: (deadline - monotonic) / 2)
+        raise Error.new("invalid_response", "malformed history response") unless snapshot.is_a?(Hash)
+      rescue Error => e
+        @logger.warn("recapi: could not restore the user's stored history: #{e.message}")
+        return state
+      end
+      with_locks(key) do
+        state = load(key)
+        # A concurrent first call may have merged it already.
+        unless state.restored
+          state.history = state.history.merge_snapshot(History.from_snapshot(snapshot), t)
+          state.restored = true
+          state.anon_id = nil
+          save(key, state, t)
+        end
+      end
+      state
+    end
+
+    def fetch_popular(count, tags_any, tags_all, timeout)
+      query = {}
+      query["tags_any"] = tags_any.join(",") if tags_any && !tags_any.empty?
+      query["tags_all"] = tags_all.join(",") if tags_all && !tags_all.empty?
+      query["count"] = count.to_s
+      response = request("GET", "/v1/popular", timeout: timeout, query: query)
+      raw = response.is_a?(Hash) ? response["items"] : nil
+      raise Error.new("invalid_response", "malformed popular response") unless raw.is_a?(Array)
+
+      raw.map { |entry| parse_item(entry, "backfill") }
+    end
+
+    def parse_recommendations(response)
+      unless response.is_a?(Hash) && response["recommendation_id"].is_a?(String) && response["items"].is_a?(Array)
+        raise Error.new("invalid_response", "malformed recommendations response")
+      end
+
+      [response["recommendation_id"], response["items"].map { |entry| parse_item(entry, "exploit") }]
+    end
+
+    def parse_item(entry, slot)
+      unless entry.is_a?(Hash) && entry["item_id"].is_a?(String)
+        raise Error.new("invalid_response", "malformed item in response")
+      end
+
+      metadata = entry["metadata"]
+      why = entry["why"]
+      score = entry["score"]
+      Item.new(
+        item_id: entry["item_id"],
+        score: score.is_a?(Numeric) ? score.to_f : 0.0,
+        slot: entry["slot"].is_a?(String) && !entry["slot"].empty? ? entry["slot"] : slot,
+        metadata: metadata.is_a?(Hash) && !metadata.empty? ? metadata : nil,
+        why: why.is_a?(String) && !why.empty? ? why : nil
+      )
+    end
+
+    # The recommendation an event at t belongs to; a first click is recorded.
+    def attribute(entry, level, t)
+      return nil if entry.nil? || !Client.attributable?(entry, t)
+
+      entry << t if level.positive? && entry.size < 3
+      entry[0]
+    end
+
+    # The caller's exclude plus the rejected items, newest first, up to the API limit.
+    def with_rejected(exclude, rejected)
+      return exclude&.dup if rejected.empty?
+
+      out = (exclude || []).uniq
+      seen = out.to_h { |item| [item, true] }
+      rejected.reverse_each do |item|
+        break if out.size >= MAX_EXCLUDE
+        next if seen.key?(item)
+
+        seen[item] = true
+        out << item
+      end
+      out
+    end
+
+    # --- state ----------------------------------------------------------------
+
+    def key_for(user_id, anon_id)
+      return "#{@prefix}u:#{user_id}" if user_id
+      return "#{@prefix}a:#{anon_id}" if anon_id
+
+      nil
+    end
+
+    # Always in the same order, or two logins could each hold the other's lock.
+    def with_locks(*keys, &block)
+      locks = keys.map { |key| key.hash % @user_locks.size }.uniq.sort.map { |i| @user_locks[i] }
+      locks.reverse.reduce(block) { |inner, lock| -> { lock.synchronize(&inner) } }.call
+    end
+
+    # The store is a cache: when it fails, recapi's stored history is still
+    # there, so the call goes on without it.
+    def load(key)
+      raw = begin
+        store_call(:get, key)
+      rescue StandardError => e
+        @logger.error("recapi: store read failed: #{e.class}: #{e.message}")
+        return UserState.new
+      end
+      return UserState.new if raw.nil? || raw.empty?
+
+      state = UserState.parse(raw)
+      return state unless state.nil?
+
+      @logger.warn("recapi: discarding a malformed stored user state")
+      UserState.new
+    end
+
+    def save(key, state, now)
+      store_call(:set, key, state.dump(now))
+    rescue StandardError => e
+      @logger.error("recapi: store write failed: #{e.class}: #{e.message}")
+    end
+
+    # Redis clients have get/set/del, Rails.cache read/write/delete.
+    def store_call(action, key, value = nil)
+      case action
+      when :get then @store.respond_to?(:get) ? @store.get(key) : @store.read(key)
+      when :set then @store.respond_to?(:set) ? @store.set(key, value) : @store.write(key, value)
+      else @store.respond_to?(:delete) ? @store.delete(key) : @store.del(key)
+      end
+    end
+
+    # --- HTTP -----------------------------------------------------------------
+
+    def request(method, path, body: nil, query: nil, timeout: nil)
+      params = (query || {}).dup
+      headers = { "Accept" => "application/json", "User-Agent" => "recapi-ruby/#{VERSION}" }
+      # A public key travels in the URL only on GET /v1/popular (CDN caching);
+      # the API refuses a secret key there.
+      if method == "GET" && @api_key.start_with?(PUBLIC_KEY_PREFIX)
+        params["key"] = @api_key
+      else
+        headers["Authorization"] = "Bearer #{@api_key}"
+      end
+      target = @url.path + path
+      target += "?#{URI.encode_www_form(params)}" unless params.empty?
+      data = nil
+      unless body.nil?
+        # Raw UTF-8: escaped, non-Latin ids would take up to 3 times the bytes.
+        data = JSON.generate(body)
+        headers["Content-Type"] = "application/json"
+      end
+      limit = timeout.nil? ? @timeout : timeout
+      raise Error.new("timeout", "the deadline passed before the request was sent") if limit <= 0
+
+      begin
+        response = exchange(method, target, data, headers, limit)
+      rescue *TIMEOUT_ERRORS
+        raise Error.new("timeout", "request timed out after #{format('%.3g', limit)} s")
+      rescue *NETWORK_ERRORS => e
+        raise Error.new("network", "#{e.class}: #{e.message}")
+      end
+      status = response.code.to_i
+      # Net::HTTP follows no redirect: a 3xx (an http:// base_url sent on to
+      # https) fails like a 4xx, or a DELETE would look done.
+      raise http_error(status, response) unless (200..299).cover?(status)
+
+      parse_json(response.body)
+    end
+
+    # Sends one request on an idle connection, or a new one. A connection the
+    # server closed while idle fails before any reply comes: it is replaced
+    # once. A failure once the reply has started is never resent: the API has
+    # the request (a recommendation would count twice).
+    def exchange(method, target, data, headers, limit)
+      forked
+      start = monotonic
+      # The most recently used: the least likely to have timed out.
+      conn = @idle_lock.synchronize { @idle.pop }
+      2.times do |attempt|
+        remaining = limit - (monotonic - start)
+        raise Net::OpenTimeout, "deadline" if remaining <= 0
+
+        reused = !conn.nil?
+        conn ||= connection
+        conn.open_timeout = conn.read_timeout = conn.write_timeout = remaining
+        req = Net::HTTPGenericRequest.new(method, !data.nil?, method != "HEAD", target, headers)
+        req.body = data unless data.nil?
+        begin
+          conn.start unless conn.started?
+          response = conn.request(req)
+        rescue *STALE_ERRORS
+          finish(conn)
+          raise if !reused || attempt.positive?
+
+          conn = nil
+          next
+        rescue Exception # rubocop:disable Lint/RescueException
+          finish(conn)
+          raise
+        end
+        # A body cut short of its Content-Length reads as whole here.
+        length = response["Content-Length"]
+        if length && response.body.to_s.bytesize < length.to_i && response["Content-Encoding"].nil?
+          finish(conn)
+          raise EOFError, "the reply was cut short"
+        end
+        keep(conn, response)
+        return response
+      end
+    end
+
+    def connection
+      # Net::HTTP honours HTTPS_PROXY, HTTP_PROXY and NO_PROXY itself.
+      conn = Net::HTTP.new(@url.host, @url.port)
+      conn.use_ssl = @url.scheme == "https"
+      # No silent resend: a recommendation would count twice.
+      conn.max_retries = 0
+      # Reused until the server closes it (Net::HTTP's 2 s would handshake again).
+      conn.keep_alive_timeout = 60
+      conn
+    end
+
+    # Returns a connection whose last reply was read whole to the idle ones.
+    def keep(conn, response)
+      return finish(conn) if response["Connection"].to_s.downcase == "close"
+
+      kept = @idle_lock.synchronize { @idle.size < MAX_IDLE_CONNECTIONS && @idle.push(conn) }
+      finish(conn) unless kept
+    end
+
+    def finish(conn)
+      conn.finish if conn.started?
+    rescue IOError, SystemCallError
+      nil
+    end
+
+    def http_error(status, response)
+      payload = parse_json(response.body)
+      body = payload.is_a?(Hash) && payload["error"].is_a?(Hash) ? payload["error"] : {}
+      code = body["code"]
+      code = CODE_BY_STATUS[status] || (status >= 500 ? "internal" : "http_error") if code.nil? || code == ""
+      message = body["message"]
+      message = "HTTP #{status}" if message.nil? || message == ""
+      Error.new(code.to_s, message.to_s, status: status, retry_after: retry_after(response["Retry-After"]))
+    end
+
+    def retry_after(header)
+      seconds = Float(header.to_s.strip)
+      seconds.finite? && seconds >= 0 ? seconds : nil
+    rescue ArgumentError
+      nil
+    end
+
+    def parse_json(raw)
+      return nil if raw.nil? || raw.empty?
+
+      JSON.parse(raw)
+    rescue JSON::ParserError
+      nil
+    end
+
+    # --- arguments ------------------------------------------------------------
+
+    def level_value(level)
+      name = level.is_a?(Symbol) ? level.to_s : level
+      return LEVEL_NAMES[name] if name.is_a?(String) && LEVEL_NAMES.key?(name)
+      return level if level.is_a?(Integer) && level.between?(-10, 10)
+
+      raise ArgumentError, "level must be an integer from -10 to 10 or one of #{LEVEL_NAMES.keys.join(', ')}"
+    end
+
+    # Rails ids are integers: they travel as strings, which the API requires.
+    def id_string(value)
+      value.is_a?(Integer) ? value.to_s : value
+    end
+
+    def check_ids(**ids)
+      ids.map do |name, value|
+        value = id_string(value)
+        raise ArgumentError, "#{name} #{ID_RULE}" unless value.nil? || History.id?(value)
+
+        value
+      end
+    end
+
+    def escape(id)
+      URI.encode_www_form_component(id).gsub("+", "%20")
+    end
+
+    def non_empty(values)
+      values.nil? || values.empty? ? nil : values.to_a
+    end
+
+    def compact(fields)
+      fields.compact
+    end
+
+    def iso(t_ms)
+      Time.at(t_ms / 1000, t_ms % 1000, :millisecond).utc.strftime("%Y-%m-%dT%H:%M:%S.%LZ")
+    end
+  end
+end

metadata

@@ -0,0 +1,46 @@
+--- !ruby/object:Gem::Specification
+name: recapi
+version: !ruby/object:Gem::Version
+  version: 0.1.3
+platform: ruby
+authors:
+- recapi
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-11-02 00:00:00.000000000 Z
+dependencies: []
+description: 'Ruby client for the recapi recommendation API: per-user history, event
+  batching, retries, popular fallback. Standard library only.'
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/recapi.rb
+homepage: https://recapi.io
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.27
+signing_key:
+specification_version: 4
+summary: Ruby client for the recapi recommendation API
+test_files: []