search-engine-for-typesense 1.0.1 → 30.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 771a89c8b446dc9b6ed5ca4f3d9baf0d03287c57df03547afb90d450339a0f3a
-  data.tar.gz: 19fe80cf4f933baa88111bc9dec607d97a8bb834b88955f4392634dbd3ab2305
+  metadata.gz: edc1b2db8a930d829b052ce9e414921cbd78c333111596c754fabe9ce443e26c
+  data.tar.gz: bcd25036e9eb8202bc813decea0c7c8904f9b7565e5cfb254a2d7fb5760dd473
 SHA512:
-  metadata.gz: 4db81fdc22c60c5de4f47fc1cf3e12c27ceeb6eb50a5189f801d4be0ba5b9497b12ddafb7fdb3d10f051b611ce451c5afac216f9a08ebf4ae819a81edf6372ef
-  data.tar.gz: 3dd6c797700d0e778be77a437d475c622dc82a0248fbd0c011a784e02eeb355fc38988b3a1d5bec8613b25fbe8013788a89bdc3d68fe5503da1f12de869cc60d
+  metadata.gz: 275bdb5de35a2c8fb31f12a187231713756f5bf381b32d1bf255d6830b0feadc521b8f1aacdb2f2069b519e3ce5f6e5b793bb1a6ee9b79ceaded017afce4259e
+  data.tar.gz: 3401b22b7440aaa90040004128cc5dea5ff76355505471f1752d9b91909acdbff120842904295fd014a349d3f785eb18c774f8e94583cd4887b651078fac6143

data/README.md

@@ -9,6 +9,12 @@ Mountless Rails::Engine for [Typesense](https://typesense.org). Expressive Relat
 > [!NOTE]
 > This project is not affiliated with [Typesense](https://typesense.org) and is a wrapper for the [`typesense` gem](https://github.com/typesense/typesense-ruby).
 
+## Versioning
+
+The gem version mirrors the Typesense server major/minor it targets. Patch releases are reserved for gem-only fixes and enhancements.
+
+Example: `30.1.x` targets Typesense `30.1`.
+
 ## Quickstart
 
 ```ruby
@@ -142,7 +148,7 @@ See [Docs Style Guide](https://nikita-shkoda.mintlify.app/projects/search-engine
 <!-- Badge references (placeholders) -->
 [ci-badge]: https://img.shields.io/github/actions/workflow/status/lstpsche/search-engine-for-typesense/ci.yml?branch=main
 [ci-url]: #
-[gem-badge]: https://img.shields.io/gem/v/search-engine-for-typesense.svg?label=gem
+[gem-badge]: https://badge.fury.io/rb/search-engine-for-typesense.svg?icon=si%3Arubygems
 [gem-url]: https://rubygems.org/gems/search-engine-for-typesense
 [docs-badge]: https://img.shields.io/badge/docs-index-blue
 [docs-url]: https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/index

data/lib/search_engine/client/http_adapter.rb

@@ -56,7 +56,7 @@ module SearchEngine
 
         # Fallback: attempt a generic call via low-level typesense endpoint access if available.
         # This keeps adapter permissive for future endpoints without adding Faraday here.
-        raise ArgumentError, "Unsupported request path for adapter: #{request.method} #{request.path}"
+        raise ArgumentError, "Unsupported request path for adapter: #{request.http_method} #{request.path}"
       end
     end
   end

data/lib/search_engine/client/services/base.rb

@@ -41,8 +41,8 @@ module SearchEngine
           client.__send__(:with_exception_mapping, *args, &block)
         end
 
-        def instrument(*args)
-          client.__send__(:instrument, *args)
+        def instrument(*args, **kwargs)
+          client.__send__(:instrument, *args, **kwargs)
         end
 
         def log_success(*args)

data/lib/search_engine/client/services/collections.rb

@@ -28,7 +28,7 @@ module SearchEngine
 
           raise
         ensure
-          instrument(:get, path, (start ? (current_monotonic_ms - start) : 0.0), {})
+          instrument(:get, path, (start ? (current_monotonic_ms - start) : 0.0), {}, request_token: start)
         end
 
         # @param collection_name [String]
@@ -54,7 +54,7 @@ module SearchEngine
 
           raise
         ensure
-          instrument(:get, path, (start ? (current_monotonic_ms - start) : 0.0), {})
+          instrument(:get, path, (start ? (current_monotonic_ms - start) : 0.0), {}, request_token: start)
         end
 
         # @param alias_name [String]
@@ -72,7 +72,7 @@ module SearchEngine
 
           symbolize_keys_deep(result)
         ensure
-          instrument(:put, path, (start ? (current_monotonic_ms - start) : 0.0), {})
+          instrument(:put, path, (start ? (current_monotonic_ms - start) : 0.0), {}, request_token: start)
         end
 
         # @param schema [Hash]
@@ -88,7 +88,7 @@ module SearchEngine
 
           symbolize_keys_deep(result)
         ensure
-          instrument(:post, path, (start ? (current_monotonic_ms - start) : 0.0), {})
+          instrument(:post, path, (start ? (current_monotonic_ms - start) : 0.0), {}, request_token: start)
         end
 
         # @param name [String]
@@ -106,7 +106,7 @@ module SearchEngine
 
           symbolize_keys_deep(result)
         ensure
-          instrument(:patch, path, (start ? (current_monotonic_ms - start) : 0.0), {})
+          instrument(:patch, path, (start ? (current_monotonic_ms - start) : 0.0), {}, request_token: start)
         end
 
         # @param name [String]
@@ -133,7 +133,7 @@ module SearchEngine
 
           raise
         ensure
-          instrument(:delete, path, (start ? (current_monotonic_ms - start) : 0.0), {})
+          instrument(:delete, path, (start ? (current_monotonic_ms - start) : 0.0), {}, request_token: start)
         end
 
         # @return [Array<Hash>]
@@ -153,7 +153,7 @@ module SearchEngine
 
           symbolize_keys_deep(result)
         ensure
-          instrument(:get, path, (start ? (current_monotonic_ms - start) : 0.0), {})
+          instrument(:get, path, (start ? (current_monotonic_ms - start) : 0.0), {}, request_token: start)
         end
       end
     end

data/lib/search_engine/client/services/documents.rb

@@ -23,7 +23,7 @@ module SearchEngine
             ts.collections[collection].documents.import(jsonl, action: action.to_s)
           end
 
-          instrument(:post, path, current_monotonic_ms - start, {})
+          instrument(:post, path, current_monotonic_ms - start, {}, request_token: start)
           result
         end
 
@@ -51,7 +51,7 @@ module SearchEngine
             ts.collections[collection].documents.delete(filter_by: filter_by)
           end
 
-          instrument(:delete, path, current_monotonic_ms - start, {})
+          instrument(:delete, path, current_monotonic_ms - start, {}, request_token: start)
           symbolize_keys_deep(result)
         end
 
@@ -84,7 +84,7 @@ module SearchEngine
 
           raise
         ensure
-          instrument(:delete, path, current_monotonic_ms - start, {}) if defined?(start)
+          instrument(:delete, path, current_monotonic_ms - start, {}, request_token: start) if defined?(start)
         end
 
         # @param collection [String]
@@ -112,7 +112,7 @@ module SearchEngine
           result = with_exception_mapping(:patch, path, {}, start) do
             ts.collections[collection].documents[s].update(fields)
           end
-          instrument(:patch, path, current_monotonic_ms - start, {})
+          instrument(:patch, path, current_monotonic_ms - start, {}, request_token: start)
           symbolize_keys_deep(result)
         end
 
@@ -142,7 +142,7 @@ module SearchEngine
             ts.collections[collection].documents.update(fields, filter_by: filter_by)
           end
 
-          instrument(:patch, path, current_monotonic_ms - start, {})
+          instrument(:patch, path, current_monotonic_ms - start, {}, request_token: start)
           symbolize_keys_deep(result)
         end
 
@@ -162,7 +162,7 @@ module SearchEngine
             typesense.collections[collection].documents.create(document)
           end
 
-          instrument(:post, path, current_monotonic_ms - start, {})
+          instrument(:post, path, current_monotonic_ms - start, {}, request_token: start)
           symbolize_keys_deep(result)
         end
 
@@ -196,7 +196,11 @@ module SearchEngine
 
           raise
         ensure
-          instrument(:get, path, (start ? (current_monotonic_ms - start) : 0.0), {}) if defined?(start)
+          if defined?(start)
+            instrument(:get, path, (start ? (current_monotonic_ms - start) : 0.0), {},
+                       request_token: start
+            )
+          end
         end
 
         private

data/lib/search_engine/client/services/operations.rb

@@ -15,7 +15,7 @@ module SearchEngine
 
           symbolize_keys_deep(result)
         ensure
-          instrument(:get, path, (start ? (current_monotonic_ms - start) : 0.0), {})
+          instrument(:get, path, (start ? (current_monotonic_ms - start) : 0.0), {}, request_token: start)
         end
 
         def list_api_keys
@@ -37,7 +37,7 @@ module SearchEngine
 
           symbolize_keys_deep(result)
         ensure
-          instrument(:get, path, (start ? (current_monotonic_ms - start) : 0.0), {})
+          instrument(:get, path, (start ? (current_monotonic_ms - start) : 0.0), {}, request_token: start)
         end
 
         def clear_cache
@@ -48,7 +48,7 @@ module SearchEngine
             typesense.operations.perform('cache/clear')
           end
 
-          instrument(:post, path, current_monotonic_ms - start, {})
+          instrument(:post, path, current_monotonic_ms - start, {}, request_token: start)
           symbolize_keys_deep(result)
         end
 
@@ -75,7 +75,7 @@ module SearchEngine
             end
           end
         ensure
-          instrument(:get, path, (start ? (current_monotonic_ms - start) : 0.0), {})
+          instrument(:get, path, (start ? (current_monotonic_ms - start) : 0.0), {}, request_token: start)
         end
 
         # Return raw server statistics from Typesense.
@@ -101,7 +101,7 @@ module SearchEngine
             end
           end
         ensure
-          instrument(:get, path, (start ? (current_monotonic_ms - start) : 0.0), {})
+          instrument(:get, path, (start ? (current_monotonic_ms - start) : 0.0), {}, request_token: start)
         end
 
         private

data/lib/search_engine/client/services/search.rb

@@ -21,7 +21,7 @@ module SearchEngine
 
           result = instrumented_search(collection, params_obj, cache_params, path, payload, start)
           duration = current_monotonic_ms - start
-          instrument(:post, path, duration, cache_params)
+          instrument(:post, path, duration, cache_params, request_token: start)
           log_success(:post, path, start, cache_params)
 
           klass = begin
@@ -48,7 +48,7 @@ module SearchEngine
             typesense.multi_search.perform({ searches: bodies }, common_params: cache_params)
           end
 
-          instrument(:post, path, current_monotonic_ms - start, cache_params)
+          instrument(:post, path, current_monotonic_ms - start, cache_params, request_token: start)
           symbolize_keys_deep(result)
         end
 
@@ -129,7 +129,7 @@ module SearchEngine
 
           pinned = params[:pinned_hits]
           hidden = params[:hidden_hits]
-          tags   = params[:override_tags]
+          tags   = params[:curation_tags] || params[:override_tags]
 
           pinned_count =
             case pinned

data/lib/search_engine/client.rb

@@ -12,6 +12,10 @@ module SearchEngine
   # Provides single-search and federated multi-search while enforcing that cache
   # knobs live in URL/common-params and not in per-search request bodies.
   class Client
+    REQUEST_ERROR_INSTRUMENTED_KEY = :__se_request_error_instrumented_queue__
+    REQUEST_ERROR_INSTRUMENTED_MAX = 32
+    REQUEST_ERROR_INSTRUMENTED_TTL_MS = 60_000.0
+
     # @param config [SearchEngine::Config]
     # @param typesense_client [Object, nil] optional injected Typesense::Client (for tests)
     def initialize(config: SearchEngine.config, typesense_client: nil)
@@ -163,7 +167,7 @@ module SearchEngine
     end
 
     # --- Admin: Synonyms ----------------------------------------------------
-    # NOTE: We rely on the official client's endpoints; names are mapped here.
+    # We map per-collection synonym IDs to a dedicated synonym set.
 
     # @param collection [String]
     # @param id [String]
@@ -172,10 +176,10 @@ module SearchEngine
     # @see `https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/synonyms-stopwords`
     # @see `https://typesense.org/docs/latest/api/synonyms.html#upsert-a-synonym`
     def synonyms_upsert(collection:, id:, terms:)
-      admin_resource_request(
-        resource_type: :synonyms,
+      set = synonym_set_name_for_collection(collection)
+      synonym_set_item_request(
         method: :put,
-        collection: collection,
+        set: set,
         id: id,
         body_data: Array(terms)
       )
@@ -183,23 +187,24 @@ module SearchEngine
 
     # @return [Array<Hash>]
     # @see `https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/synonyms-stopwords`
-    # @see `https://typesense.org/docs/latest/api/synonyms.html#list-all-synonyms-of-a-collection`
+    # @see `https://typesense.org/docs/latest/api/synonyms.html#list-all-synonyms-in-a-synonym-set`
     def synonyms_list(collection:)
-      admin_resource_request(
-        resource_type: :synonyms,
+      set = synonym_set_name_for_collection(collection)
+      raw = synonym_set_item_request(
         method: :get,
-        collection: collection
+        set: set
       )
+      extract_synonym_items(raw)
     end
 
     # @return [Hash, nil]
     # @see `https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/synonyms-stopwords`
     # @see `https://typesense.org/docs/latest/api/synonyms.html#retrieve-a-synonym`
     def synonyms_get(collection:, id:)
-      admin_resource_request(
-        resource_type: :synonyms,
+      set = synonym_set_name_for_collection(collection)
+      synonym_set_item_request(
         method: :get,
-        collection: collection,
+        set: set,
         id: id,
         return_nil_on_404: true
       )
@@ -209,10 +214,10 @@ module SearchEngine
     # @see `https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/synonyms-stopwords`
     # @see `https://typesense.org/docs/latest/api/synonyms.html#delete-a-synonym`
     def synonyms_delete(collection:, id:)
-      admin_resource_request(
-        resource_type: :synonyms,
+      set = synonym_set_name_for_collection(collection)
+      synonym_set_item_request(
         method: :delete,
-        collection: collection,
+        set: set,
         id: id
       )
     end
@@ -437,7 +442,88 @@ module SearchEngine
 
       raise
     ensure
-      instrument(method, path, (start ? (current_monotonic_ms - start) : 0.0), {})
+      instrument(method, path, (start ? (current_monotonic_ms - start) : 0.0), {}, request_token: start)
+    end
+
+    # Internal helper for synonym set item CRUD.
+    #
+    # @param method [Symbol]
+    # @param set [String] synonym set name
+    # @param id [String, nil] synonym id
+    # @param body_data [Array<String>, nil]
+    # @param return_nil_on_404 [Boolean]
+    # @return [Hash, Array<Hash>, nil]
+    def synonym_set_item_request(method:, set:, id: nil, body_data: nil, return_nil_on_404: false)
+      set_name = set.to_s
+      sid = id.to_s if id
+      start = current_monotonic_ms
+
+      path = if sid
+               "/synonym_sets/#{escape_segment(set_name)}/synonyms/#{escape_segment(sid)}"
+             else
+               "/synonym_sets/#{escape_segment(set_name)}/synonyms"
+             end
+
+      request_body = if method == :put && body_data
+                       { synonyms: body_data }
+                     else
+                       {}
+                     end
+
+      result = with_exception_mapping(method, path, {}, start) do
+        execute_synonym_set_request(typesense_api_call, method, path, request_body)
+      end
+      symbolize_keys_deep(result)
+    rescue Errors::Api => error
+      return nil if return_nil_on_404 && error.status.to_i == 404
+
+      raise
+    ensure
+      instrument(method, path, (start ? (current_monotonic_ms - start) : 0.0), {}, request_token: start)
+    end
+
+    def execute_synonym_set_request(api_call, method, path, request_body)
+      raise ArgumentError, 'Typesense client missing configuration' unless api_call
+
+      case method
+      when :get
+        api_call.get(path)
+      when :put
+        api_call.put(path, request_body)
+      when :delete
+        api_call.delete(path)
+      else
+        raise ArgumentError, "Unsupported method: #{method.inspect}"
+      end
+    end
+
+    def extract_synonym_items(raw)
+      return [] if raw.nil?
+      return raw if raw.is_a?(Array)
+
+      if raw.is_a?(Hash)
+        list = raw[:synonyms] || raw['synonyms'] || raw[:items] || raw['items'] || raw[:results] || raw['results']
+        return Array(list) if list
+      end
+
+      Array(raw)
+    end
+
+    def synonym_set_name_for_collection(collection)
+      "#{collection}_synonyms_index"
+    end
+
+    def typesense_api_call
+      @typesense_api_call ||= begin
+        require 'typesense'
+        ts = typesense
+        Typesense::ApiCall.new(ts.configuration) if ts.respond_to?(:configuration)
+      end
+    end
+
+    def escape_segment(value)
+      require 'uri'
+      URI.encode_www_form_component(value.to_s)
     end
 
     # Execute the actual Typesense API call for admin resources.
@@ -481,7 +567,7 @@ module SearchEngine
       Typesense::Client.new(
         nodes: build_nodes,
         api_key: config.api_key,
-        # typesense-ruby v4.1.0 uses a single connection timeout for both open+read
+        # typesense-ruby uses a single connection timeout for both open+read
         connection_timeout_seconds: read_timeout_seconds,
         num_retries: safe_retry_attempts,
         retry_interval_seconds: safe_retry_backoff,
@@ -628,12 +714,25 @@ module SearchEngine
     def map_and_raise(error, method, path, cache_params, start_ms)
       duration_ms = current_monotonic_ms - start_ms
 
-      return handle_api_error(error, method, path, cache_params, duration_ms) if api_error?(error)
-      return handle_timeout_error(error, method, path, cache_params, duration_ms) if timeout_error?(error)
-      return handle_connection_error(error, method, path, cache_params, duration_ms) if connection_error?(error)
+      if api_error?(error)
+        return handle_api_error(
+          error, method, path, cache_params, duration_ms, request_token: start_ms
+        )
+      end
+      if timeout_error?(error)
+        return handle_timeout_error(
+          error, method, path, cache_params, duration_ms, request_token: start_ms
+        )
+      end
+      if connection_error?(error)
+        return handle_connection_error(
+          error, method, path, cache_params, duration_ms, request_token: start_ms
+        )
+      end
 
       # Unmapped error: instrument and re-raise as-is
-      instrument(method, path, duration_ms, cache_params, error_class: error.class.name)
+      instrument(method, path, duration_ms, cache_params, error_class: error.class.name, request_token: start_ms)
+      mark_request_error_instrumented(method, path, start_ms)
       raise error
     end
 
@@ -643,7 +742,7 @@ module SearchEngine
     end
 
     # Handle Typesense API errors by converting to SearchEngine::Errors::Api.
-    def handle_api_error(error, method, path, cache_params, duration_ms)
+    def handle_api_error(error, method, path, cache_params, duration_ms, request_token: nil)
       status = if error.respond_to?(:http_code)
                  error.http_code
                else
@@ -657,13 +756,22 @@ module SearchEngine
         doc: Client::RequestBuilder::DOC_CLIENT_ERRORS,
         details: { http_status: status, body: body.is_a?(String) ? body[0, 120] : body }
       )
-      instrument(method, path, duration_ms, cache_params, error_class: err.class.name)
+      instrument(method, path, duration_ms, cache_params, error_class: err.class.name, request_token: request_token)
+      mark_request_error_instrumented(method, path, request_token)
       raise err
     end
 
     # Handle timeout errors by converting to SearchEngine::Errors::Timeout.
-    def handle_timeout_error(error, method, path, cache_params, duration_ms)
-      instrument(method, path, duration_ms, cache_params, error_class: Errors::Timeout.name)
+    def handle_timeout_error(error, method, path, cache_params, duration_ms, request_token: nil)
+      instrument(
+        method,
+        path,
+        duration_ms,
+        cache_params,
+        error_class: Errors::Timeout.name,
+        request_token: request_token
+      )
+      mark_request_error_instrumented(method, path, request_token)
       raise Errors::Timeout.new(
         error.message,
         doc: Client::RequestBuilder::DOC_CLIENT_ERRORS,
@@ -672,8 +780,16 @@ module SearchEngine
     end
 
     # Handle connection errors by converting to SearchEngine::Errors::Connection.
-    def handle_connection_error(error, method, path, cache_params, duration_ms)
-      instrument(method, path, duration_ms, cache_params, error_class: Errors::Connection.name)
+    def handle_connection_error(error, method, path, cache_params, duration_ms, request_token: nil)
+      instrument(
+        method,
+        path,
+        duration_ms,
+        cache_params,
+        error_class: Errors::Connection.name,
+        request_token: request_token
+      )
+      mark_request_error_instrumented(method, path, request_token)
       raise Errors::Connection.new(
         error.message,
         doc: Client::RequestBuilder::DOC_CLIENT_ERRORS,
@@ -705,8 +821,9 @@ module SearchEngine
       500
     end
 
-    def instrument(method, path, duration_ms, cache_params, error_class: nil)
+    def instrument(method, path, duration_ms, cache_params, error_class: nil, request_token: nil)
       return unless defined?(ActiveSupport::Notifications)
+      return if error_class.nil? && consume_request_error_instrumented?(method, path, request_token)
 
       ActiveSupport::Notifications.instrument(
         'search_engine.request',
@@ -718,6 +835,44 @@ module SearchEngine
       )
     end
 
+    def mark_request_error_instrumented(method, path, request_token = nil)
+      return nil if request_token.nil?
+
+      queue = Thread.current[REQUEST_ERROR_INSTRUMENTED_KEY] ||= []
+      now = current_monotonic_ms
+      prune_request_error_instrumented_queue!(queue, now)
+      queue << { method: method.to_sym, path: path.to_s, token: request_token, at: now }
+      queue.shift while queue.size > REQUEST_ERROR_INSTRUMENTED_MAX
+      nil
+    rescue StandardError
+      nil
+    end
+
+    def consume_request_error_instrumented?(method, path, request_token = nil)
+      return false if request_token.nil?
+
+      queue = Thread.current[REQUEST_ERROR_INSTRUMENTED_KEY]
+      return false unless queue.is_a?(Array) && !queue.empty?
+
+      now = current_monotonic_ms
+      prune_request_error_instrumented_queue!(queue, now)
+      idx = queue.index do |entry|
+        entry[:method] == method.to_sym && entry[:path] == path.to_s && entry[:token] == request_token
+      end
+      return false unless idx
+
+      queue.delete_at(idx)
+      true
+    rescue StandardError
+      false
+    end
+
+    def prune_request_error_instrumented_queue!(queue, now_ms)
+      queue.reject! do |entry|
+        now_ms - entry[:at].to_f > REQUEST_ERROR_INSTRUMENTED_TTL_MS
+      end
+    end
+
     def log_success(method, path, start_ms, cache_params)
       return unless safe_logger
 

data/lib/search_engine/hydration/materializers.rb

@@ -500,7 +500,7 @@ module SearchEngine
         joins = Array(state[:joins]).flatten.compact
         return relation if joins.empty?
 
-        # Guard: sorting or selection on joined fields not supported in v1
+        # Guard: sorting or selection on joined fields not supported by client-side join fallback
         orders = Array(state[:orders]).map(&:to_s)
         if orders.any? { |o| o.start_with?('$') }
           raise SearchEngine::Errors::InvalidOption.new(

data/lib/search_engine/indexer/import_dispatcher.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'json'
+require 'search_engine/indexer/import_response_parser'
 
 module SearchEngine
   class Indexer
@@ -131,62 +132,7 @@ module SearchEngine
         end
 
         def parse_import_response(raw)
-          return parse_from_string(raw) if raw.is_a?(String)
-          return parse_from_array(raw) if raw.is_a?(Array)
-
-          [0, 0, []]
-        end
-
-        def parse_from_string(str)
-          success = 0
-          failure = 0
-          samples = []
-          str.each_line do |line|
-            line = line.strip
-            next if line.empty?
-
-            h = safe_parse_json(line)
-            unless h
-              failure += 1
-              samples << 'invalid-json-line'
-              next
-            end
-
-            if truthy?(h['success'] || h[:success])
-              success += 1
-            else
-              failure += 1
-              msg = h['error'] || h[:error] || h['message'] || h[:message]
-              samples << msg.to_s[0, 200] if msg
-            end
-          end
-          [success, failure, samples[0, 5]]
-        end
-
-        def parse_from_array(arr)
-          success = 0
-          failure = 0
-          samples = []
-          arr.each do |h|
-            if h.is_a?(Hash) && truthy?(h['success'] || h[:success])
-              success += 1
-            else
-              failure += 1
-              msg = h.is_a?(Hash) ? (h['error'] || h[:error] || h['message'] || h[:message]) : nil
-              samples << msg.to_s[0, 200] if msg
-            end
-          end
-          [success, failure, samples[0, 5]]
-        end
-
-        def safe_parse_json(line)
-          JSON.parse(line)
-        rescue StandardError
-          nil
-        end
-
-        def truthy?(val)
-          val == true || val.to_s.downcase == 'true'
+          SearchEngine::Indexer::ImportResponseParser.parse(raw)
         end
 
         def monotonic_ms

data/lib/search_engine/indexer/import_response_parser.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module SearchEngine
+  class Indexer
+    # Shared parser for Typesense import API responses.
+    #
+    # Accepts the two shapes returned by different versions of the Typesense Ruby
+    # client:
+    # - String (JSONL status lines)
+    # - Array<Hash> (already parsed per-document statuses)
+    #
+    # Returns a stable tuple:
+    #   [success_count, failure_count, errors_sample]
+    module ImportResponseParser
+      MAX_ERROR_SAMPLES = 5
+      INVALID_JSON_LINE = 'invalid-json-line'
+
+      module_function
+
+      # @param raw [String, Array, Object]
+      # @return [Array(Integer, Integer, Array<String>)]
+      def parse(raw)
+        return parse_from_string(raw) if raw.is_a?(String)
+        return parse_from_array(raw) if raw.is_a?(Array)
+
+        [0, 0, []]
+      end
+
+      def parse_from_string(str)
+        success = 0
+        failure = 0
+        samples = []
+
+        str.each_line do |line|
+          row = line.strip
+          next if row.empty?
+
+          parsed = safe_parse_json(row)
+          unless parsed
+            failure += 1
+            samples << INVALID_JSON_LINE
+            next
+          end
+
+          if truthy?(parsed['success'] || parsed[:success])
+            success += 1
+          else
+            failure += 1
+            msg = parsed['error'] || parsed[:error] || parsed['message'] || parsed[:message]
+            samples << msg.to_s[0, 200] if msg
+          end
+        end
+
+        [success, failure, samples[0, MAX_ERROR_SAMPLES]]
+      end
+      module_function :parse_from_string
+
+      def parse_from_array(arr)
+        success = 0
+        failure = 0
+        samples = []
+
+        arr.each do |entry|
+          if entry.is_a?(Hash) && truthy?(entry['success'] || entry[:success])
+            success += 1
+          else
+            failure += 1
+            msg = entry.is_a?(Hash) ? (entry['error'] || entry[:error] || entry['message'] || entry[:message]) : nil
+            samples << msg.to_s[0, 200] if msg
+          end
+        end
+
+        [success, failure, samples[0, MAX_ERROR_SAMPLES]]
+      end
+      module_function :parse_from_array
+
+      def safe_parse_json(line)
+        JSON.parse(line)
+      rescue StandardError
+        nil
+      end
+      module_function :safe_parse_json
+
+      def truthy?(value)
+        value == true || value.to_s.downcase == 'true'
+      end
+      module_function :truthy?
+    end
+  end
+end

data/lib/search_engine/indexer.rb

@@ -4,6 +4,7 @@ require 'json'
 require 'timeout'
 require 'digest'
 require 'time'
+require 'search_engine/indexer/import_response_parser'
 
 module SearchEngine
   # Batch importer for streaming JSONL documents into a physical collection.
@@ -520,66 +521,7 @@ module SearchEngine
       end
 
       def parse_import_response(raw)
-        return parse_from_string(raw) if raw.is_a?(String)
-        return parse_from_array(raw) if raw.is_a?(Array)
-
-        [0, 0, []]
-      end
-
-      def parse_from_string(str)
-        success = 0
-        failure = 0
-        samples = []
-
-        str.each_line do |line|
-          line = line.strip
-          next if line.empty?
-
-          h = safe_parse_json(line)
-          unless h
-            failure += 1
-            samples << 'invalid-json-line'
-            next
-          end
-
-          if truthy?(h['success'] || h[:success])
-            success += 1
-          else
-            failure += 1
-            msg = h['error'] || h[:error] || h['message'] || h[:message]
-            samples << msg.to_s[0, 200] if msg
-          end
-        end
-
-        [success, failure, samples[0, 5]]
-      end
-
-      def parse_from_array(arr)
-        success = 0
-        failure = 0
-        samples = []
-
-        arr.each do |h|
-          if h.is_a?(Hash) && truthy?(h['success'] || h[:success])
-            success += 1
-          else
-            failure += 1
-            msg = h.is_a?(Hash) ? (h['error'] || h[:error] || h['message'] || h[:message]) : nil
-            samples << msg.to_s[0, 200] if msg
-          end
-        end
-
-        [success, failure, samples[0, 5]]
-      end
-
-      def safe_parse_json(line)
-        JSON.parse(line)
-      rescue StandardError
-        nil
-      end
-
-      def truthy?(val)
-        val == true || val.to_s.downcase == 'true'
+        SearchEngine::Indexer::ImportResponseParser.parse(raw)
       end
 
       def safe_error_excerpt(error)

data/lib/search_engine/relation/compiler.rb

@@ -311,7 +311,7 @@ module SearchEngine
 
         lines << "  Pinned: #{pinned.join(', ')}" unless pinned.empty?
         lines << "  Hidden: #{hidden.join(', ')}" unless hidden.empty?
-        lines << "  Override tags: #{tags.join(', ')}" unless tags.empty?
+        lines << "  Curation tags: #{tags.join(', ')}" unless tags.empty?
         lines << "  Filter curated hits: #{fch}" unless fch.nil?
         lines
       end
@@ -510,7 +510,7 @@ module SearchEngine
 
         params[:pinned_hits] = pinned.join(',') if pinned.any?
         params[:hidden_hits] = hidden.join(',') if hidden.any?
-        params[:override_tags] = tags.join(',') if tags.any?
+        params[:curation_tags] = tags.join(',') if tags.any?
         params[:filter_curated_hits] = fch unless fch.nil?
         # Expose a compact curation meta segment for callers (not sent over HTTP)
         params[:_curation] = { filter_curated_hits: fch } if cur.key?(:filter_curated_hits)

data/lib/search_engine/relation/dsl.rb

@@ -145,7 +145,7 @@ module SearchEngine
 
       # Set multiple curation knobs in one call.
       # @return [SearchEngine::Relation]
-      def curate(pin: nil, hide: nil, override_tags: nil, filter_curated_hits: :__unset__)
+      def curate(pin: nil, hide: nil, override_tags: nil, curation_tags: nil, filter_curated_hits: :__unset__)
         spawn do |s|
           cur = s[:curation] || { pinned: [], hidden: [], override_tags: [], filter_curated_hits: nil }
 
@@ -157,7 +157,12 @@ module SearchEngine
             list = normalize_curation_ids(hide)
             cur[:hidden] = list.each_with_object([]) { |t, acc| acc << t unless acc.include?(t) }
           end
-          cur[:override_tags] = normalize_curation_tags(override_tags) unless override_tags.nil?
+          tags_input = if !curation_tags.nil?
+                         curation_tags
+                       else
+                         override_tags
+                       end
+          cur[:override_tags] = normalize_curation_tags(tags_input) unless tags_input.nil?
           if filter_curated_hits != :__unset__
             cur[:filter_curated_hits] =
               filter_curated_hits.nil? ? nil : coerce_boolean_strict(filter_curated_hits, :filter_curated_hits)
@@ -820,7 +825,13 @@ module SearchEngine
 
         pinned = normalize_curation_ids(value[:pinned] || value['pinned'])
         hidden = normalize_curation_ids(value[:hidden] || value['hidden'])
-        tags = normalize_curation_tags(value[:override_tags] || value['override_tags'])
+        raw_tags =
+          if value.key?(:curation_tags) || value.key?('curation_tags')
+            value[:curation_tags] || value['curation_tags']
+          else
+            value[:override_tags] || value['override_tags']
+          end
+        tags = normalize_curation_tags(raw_tags)
 
         raw_fch = (value.key?(:filter_curated_hits) ? value[:filter_curated_hits] : value['filter_curated_hits'])
         fch = raw_fch.nil? ? nil : coerce_boolean_strict(raw_fch, :filter_curated_hits)

data/lib/search_engine/version.rb

@@ -3,5 +3,5 @@
 module SearchEngine
   # Current gem version.
   # @return [String]
-  VERSION = '1.0.1'
+  VERSION = '30.1.0'
 end

data/lib/search_engine.rb

@@ -23,6 +23,7 @@ require 'search_engine/collection_resolver'
 require 'search_engine/cascade'
 require 'search_engine/indexer'
 require 'search_engine/indexer/batch_planner'
+require 'search_engine/indexer/import_response_parser'
 require 'search_engine/indexer/import_dispatcher'
 require 'search_engine/indexer/retry_policy'
 require 'search_engine/indexer/bulk_import'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: search-engine-for-typesense
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 30.1.0
 platform: ruby
 authors:
 - Nikita Shkoda
@@ -44,14 +44,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 4.1.0
+        version: 5.0.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 4.1.0
+        version: 5.0.0
 description: Rails::Engine providing a thin wrapper around Typesense with idiomatic
   Rails integration.
 email:
@@ -148,6 +148,7 @@ files:
 - lib/search_engine/indexer/batch_planner.rb
 - lib/search_engine/indexer/bulk_import.rb
 - lib/search_engine/indexer/import_dispatcher.rb
+- lib/search_engine/indexer/import_response_parser.rb
 - lib/search_engine/indexer/retry_policy.rb
 - lib/search_engine/instrumentation.rb
 - lib/search_engine/joins/guard.rb