recapi 0.1.8 → 0.1.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 45a27aa9c5eae2fa2088d58247ebd703b60df834bc22e508737d89f17e90a8a2
-  data.tar.gz: 7443f75901c5e2600ea181f3a61277bc9b2e5b2820aad2c999dba4b8353521b6
+  metadata.gz: 28f52d6426fd83d0b14d106535a06fca9e6d29ac56b4a3b366ae31f8ca7e22df
+  data.tar.gz: 93361e6a7d6dcbbc86be19b92ccc7fb4bc3b3695f99fa701ad08cfea17ccb57f
 SHA512:
-  metadata.gz: 856de23aa6d4936301ac4d9a2dbd2de72c4ffea40e44ed41459f7b310ff36dc232103f9e8e6cd11d265790e6b95eda80cea2d6c40087d68df252d2861c5f2956
-  data.tar.gz: dfd97019465b529c84fb4d315876acac76a414432fe3d53a901ec037f3b03c5490c2ce76ed2f3000651ff904f37115c9da9d046c59c99286924abcfea1ded8fc
+  metadata.gz: 54a7bf72a2b956ed847fe57af69c3241af18c638a199a86aa3220b2f0726d495402a3faa4698e011f815f57881e5969090bf9047b28b60bc0b6d11767f88eacf
+  data.tar.gz: a7825355e8be66451b687bc342a8c9961f8b7f8bc4c04fb7c57a38442ab59ed12daf67be7b04a39cba4b7a76843c5faec071e35dbcc15a5b3a1aba6f5154ae4b

data/README.md

@@ -30,7 +30,7 @@ line with your address): save it as `lib/recapi.rb` and
 `require Rails.root.join("lib/recapi").to_s` instead.
 
 ```sh
-curl -fLo lib/recapi.rb https://api.<your-domain>/sdk/ruby/recapi-0.1.8.rb
+curl -fLo lib/recapi.rb https://api.<your-domain>/sdk/ruby/recapi-0.1.9.rb
 ```
 
 ## Quick start
@@ -62,8 +62,9 @@ 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?`,
+A refused argument (an invalid id or level) raises `ArgumentError`, except an
+`item_id` or `context_item_id` the API would refuse, as a page often takes those
+from a visitor's URL (see the table). An API failure is a `Recapi::Error` (`code`, `status`, `retry_after`, `retryable?`,
 `outage?`). `recommend` and `popular` still raise on a bad request (400, 404,
 413, other 3xx/4xx) or a reply that isn't the API's; an outage, a limit or a
 refused key can start on a live site with no deploy, so they answer with a list
@@ -71,10 +72,10 @@ and a log line.
 
 | 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). |
+| `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). An `item_id` the API would refuse (1-256 bytes of UTF-8, no control character; also `nil`, an Array or a Hash) drops the event with a log line: nothing raises, and the other events are sent as usual. A bad `level`, `user_id`, `anon_id` or `recommendation_id` still raises `ArgumentError`. |
 | `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, 5xx or 429 it returns popular items (`fallback?`, no id), or no item when those fail too: hide the slot; on a 401 or 403 no item at once. Any other failure (a bad request, a reply that isn't the API's) raises. |
+| `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, 5xx or 429 it returns popular items (`fallback?`, no id), or no item when those fail too: hide the slot; on a 401 or 403 no item at once. A `context_item_id` the API would refuse (also an Array or a Hash, as `params[:id]` gives for `?id[]=a`) isn't sent: you get the same popular list and a log line, with no recommendation request. Any other failure (a bad request, a reply that isn't the API's) 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. On a network error, timeout, 5xx, 429, 401 or 403: an empty list and a log line. Other failures as in `recommend`. |
 | `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. |
@@ -97,8 +98,8 @@ 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, with lost
-events (a refused batch, rejected events) at most one line a minute for each
-error code and for rejected events, and `recommend`'s and `popular`'s failures
+events (a refused batch, rejected events, a dropped `item_id`) at most one line a
+minute for each error code, for rejected events and for dropped ids, and `recommend`'s and `popular`'s failures
 at most one line a minute for each error code, so a revoked key on a busy server
 doesn't flood the log, and a full queue one line until a send works. A failed write to
 `$stderr` (a full disk, a closed stream) is ignored. A logger you give gets

data/lib/recapi.rb

@@ -25,7 +25,7 @@ rescue LoadError
 end
 
 module Recapi
-  VERSION = "0.1.8"
+  VERSION = "0.1.9"
 
   # Decayed user history, exactly as docs/history-spec.md (times in unix ms).
   # A port of sdk/python's history.py, snapshot merging included.
@@ -487,14 +487,22 @@ module Recapi
     # 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.
+    # automatic attribution. Ids may be strings or integers. An item_id the API
+    # would refuse raises nothing: a page often takes it from a visitor's URL, so
+    # the event is dropped and logged instead.
     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)
+      item_id = id_string(item_id)
+      # A crafted link must not fail the page. Nothing is kept: in the history it
+      # would make the API refuse every later list. The line never quotes the
+      # visitor's id.
+      unless History.id?(item_id)
+        log_lost(:item_id, "recapi: event dropped: item_id #{ID_RULE}")
+        return nil
+      end
+
       t = now_ms
       attributed = recommendation_id
       key = key_for(user_id, anon_id)
@@ -554,8 +562,11 @@ module Recapi
     # no id) and logs the error. If those fail too (recapi is down, or the plan's
     # limit covers them), the list is empty: hide the slot. On a 401 or 403 (a
     # revoked key, a suspended shop) it is empty at once, as popular would be
-    # refused too. Any other failure raises: a bad request or a reply that isn't
-    # the API's can't start on a live site without a deploy.
+    # refused too. A context_item_id the API would refuse (a page often takes it
+    # from a visitor's URL: Rails' params[:id] can be an Array or a Hash) is never
+    # sent: the answer is the same popular list. Any other failure raises: a bad
+    # request or a reply that isn't the API's can't start on a live site without
+    # a deploy.
     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
@@ -565,6 +576,13 @@ module Recapi
       key = key_for(user_id, anon_id)
       t = now_ms
       state = key.nil? ? UserState.new : load(key)
+      unless context_item_id.nil? || context_item_id == "" || History.id?(context_item_id)
+        _, _, rejected = state.history.wire(t)
+        # The message never quotes the id: a visitor may have written it. nil:
+        # not skipped in the list either, as no item can have this id.
+        cause = Error.new("invalid_request", "context_item_id #{ID_RULE}")
+        return fallback(cause, count, with_rejected(exclude, rejected), nil, tags_any, tags_all)
+      end
       if user_id && !state.restored && !state.history.empty? && !@api_key.start_with?(PUBLIC_KEY_PREFIX)
         state = restore(key, user_id, state, deadline, t)
       end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: recapi
 version: !ruby/object:Gem::Version
-  version: 0.1.8
+  version: 0.1.9
 platform: ruby
 authors:
 - recapi
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-11-04 00:00:00.000000000 Z
+date: 2026-11-05 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.'