search-engine-for-typesense 30.1.0 → 30.1.1

data/lib/search_engine/indexer.rb

@@ -42,7 +42,7 @@ module SearchEngine
     # @param into [String, nil] target collection; defaults to resolver or the logical collection alias
     # @return [Summary]
     # @raise [SearchEngine::Errors::InvalidParams]
-    # @see `https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/indexer#partitioning`
+    # @see `https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/v30.1/indexer#partitioning`
     def self.rebuild_partition!(klass, partition:, into: nil)
       raise Errors::InvalidParams, 'klass must be a Class' unless klass.is_a?(Class)
       unless klass.ancestors.include?(SearchEngine::Base)
@@ -102,7 +102,7 @@ module SearchEngine
     # @param dry_run [Boolean]
     # @return [Hash]
     # @raise [SearchEngine::Errors::InvalidParams]
-    # @see `https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/indexer#stale-deletes`
+    # @see `https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/v30.1/indexer#stale-deletes`
     def self.delete_stale!(klass, partition: nil, into: nil, dry_run: false)
       validate_stale_args!(klass)
 
@@ -164,7 +164,7 @@ module SearchEngine
     # @param max_parallel [Integer] maximum parallel threads for batch processing (default: 1)
     # @return [Summary]
     # @raise [SearchEngine::Errors::InvalidParams]
-    # @see `https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/indexer`
+    # @see `https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/v30.1/indexer`
     # @see `https://typesense.org/docs/latest/api/documents.html#import-documents`
     def self.import!(klass, into:, enum:, batch_size: nil, action: :upsert, log_batches: true, max_parallel: 1)
       SearchEngine::Indexer::BulkImport.call(
@@ -357,179 +357,6 @@ module SearchEngine
         end
       end
 
-      def import_batch_with_handling(client, collection, docs, action, next_index)
-        buffer = +''
-        docs_count = encode_jsonl!(docs, buffer)
-        bytes_sent = buffer.bytesize
-        idx = next_index.call
-
-        begin
-          attempt_stats = with_retries do |attempt|
-            perform_attempt(client, collection, action, buffer, docs_count, bytes_sent, idx, attempt)
-          end
-          [attempt_stats]
-        rescue Errors::Api => error
-          if error.status.to_i == 413 && docs.size > 1
-            mid = docs.size / 2
-            left = docs[0...mid]
-            right = docs[mid..]
-            import_batch_with_handling(client, collection, left, action, next_index) +
-              import_batch_with_handling(client, collection, right, action, next_index)
-          else
-            [
-              {
-                index: idx,
-                docs_count: docs_count,
-                success_count: 0,
-                failure_count: docs_count,
-                attempts: 1,
-                http_status: error.status.to_i,
-                duration_ms: 0.0,
-                bytes_sent: bytes_sent,
-                errors_sample: [safe_error_excerpt(error)]
-              }
-            ]
-          end
-        end
-      end
-
-      def perform_attempt(client, collection, action, jsonl, docs_count, bytes_sent, idx, attempt)
-        start = monotonic_ms
-        success_count = 0
-        failure_count = 0
-        http_status = 200
-        error_sample = []
-
-        if defined?(ActiveSupport::Notifications)
-          se_payload = {
-            collection: SearchEngine::Instrumentation.context[:collection] || collection,
-            into: collection,
-            batch_index: idx,
-            docs_count: docs_count,
-            success_count: nil,
-            failure_count: nil,
-            attempts: attempt,
-            http_status: nil,
-            bytes_sent: bytes_sent,
-            transient_retry: attempt > 1,
-            retry_after_s: nil,
-            error_sample: nil
-          }
-          SearchEngine::Instrumentation.instrument('search_engine.indexer.batch_import', se_payload) do |ctx|
-            raw = client.import_documents(collection: collection, jsonl: jsonl, action: action)
-            success_count, failure_count, error_sample = parse_import_response(raw)
-            http_status = 200
-            ctx[:success_count] = success_count
-            ctx[:failure_count] = failure_count
-            ctx[:http_status] = http_status
-          end
-        else
-          raw = client.import_documents(collection: collection, jsonl: jsonl, action: action)
-          success_count, failure_count, error_sample = parse_import_response(raw)
-        end
-
-        duration = monotonic_ms - start
-        {
-          index: idx,
-          docs_count: docs_count,
-          success_count: success_count,
-          failure_count: failure_count,
-          attempts: attempt,
-          http_status: http_status,
-          duration_ms: duration.round(1),
-          bytes_sent: bytes_sent,
-          errors_sample: error_sample
-        }
-      end
-
-      def with_retries
-        cfg = SearchEngine.config.indexer
-        attempts = cfg&.retries && cfg.retries[:attempts].to_i.positive? ? cfg.retries[:attempts].to_i : 3
-        base = cfg&.retries && cfg.retries[:base].to_f.positive? ? cfg.retries[:base].to_f : 0.5
-        max = cfg&.retries && cfg.retries[:max].to_f.positive? ? cfg.retries[:max].to_f : 5.0
-        jitter = cfg&.retries && cfg.retries[:jitter_fraction].to_f >= 0 ? cfg.retries[:jitter_fraction].to_f : 0.2
-
-        (1..attempts).each do |i|
-          return yield(i)
-        rescue Errors::Timeout, Errors::Connection
-          raise if i >= attempts
-
-          sleep_with_backoff(i, base: base, max: max, jitter_fraction: jitter)
-        rescue Errors::Api => error
-          code = error.status.to_i
-          raise unless transient_status?(code)
-          raise if i >= attempts
-
-          sleep_with_backoff(i, base: base, max: max, jitter_fraction: jitter)
-        end
-      end
-
-      def sleep_with_backoff(attempt, base:, max:, jitter_fraction:)
-        exp = [base * (2 ** (attempt - 1)), max].min
-        jitter = exp * jitter_fraction
-        delta = rand(-jitter..jitter)
-        sleep_time = exp + delta
-        sleep(sleep_time) if sleep_time.positive?
-      end
-
-      def transient_status?(code)
-        return true if code == 429
-        return true if code >= 500 && code <= 599
-
-        false
-      end
-
-      def to_array(batch)
-        return batch if batch.is_a?(Array)
-
-        batch.respond_to?(:to_a) ? batch.to_a : Array(batch)
-      end
-
-      def encode_jsonl!(docs, buffer)
-        count = 0
-        buffer.clear
-        docs.each do |raw|
-          doc = ensure_hash_document(raw)
-          ensure_id!(doc)
-          # Force system timestamp field just before serialization; developers cannot override.
-          now_i = if defined?(Time) && defined?(Time.zone) && Time.zone
-                    Time.zone.now.to_i
-                  else
-                    Time.now.to_i
-                  end
-          doc[:doc_updated_at] = now_i if doc.is_a?(Hash)
-          buffer << JSON.generate(doc)
-          buffer << "\n" if count < (docs.size - 1)
-          count += 1
-        end
-        count
-      end
-
-      def ensure_hash_document(obj)
-        if obj.is_a?(Hash)
-          obj
-        else
-          raise Errors::InvalidParams,
-                'Indexer requires batches of Hash-like documents with at least an :id key. ' \
-                'Mapping DSL is not available yet. See https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/indexer.'
-        end
-      end
-
-      def ensure_id!(doc)
-        has_id = doc.key?(:id) || doc.key?('id')
-        raise Errors::InvalidParams, 'document is missing required id' unless has_id
-      end
-
-      def parse_import_response(raw)
-        SearchEngine::Indexer::ImportResponseParser.parse(raw)
-      end
-
-      def safe_error_excerpt(error)
-        cls = error.class.name
-        msg = error.message.to_s
-        "#{cls}: #{msg[0, 200]}"
-      end
-
       def monotonic_ms
         SearchEngine::Instrumentation.monotonic_ms
       end

data/lib/search_engine/instrumentation.rb

@@ -202,7 +202,7 @@ module SearchEngine
     #   - :type [Symbol] one of :overlap, :limit_exceeded
     #   - :count [Integer]
     #   - :limit [Integer, optional] present when type==:limit_exceeded
-    #   # See also: https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/presets#observability
+    #   # See also: https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/v30.1/presets#observability
     # Measure a block and attach duration_ms to payload.
     # @param event [String]
     # @param base_payload [Hash]

data/lib/search_engine/joins/guard.rb

@@ -28,7 +28,7 @@ module SearchEngine
         raise SearchEngine::Errors::InvalidJoin.new(
           msg,
           hint: (suggestions&.any? ? "Did you mean #{suggestions.map { |s| ":#{s}" }.join(', ')}?" : nil),
-          doc: 'https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/joins#troubleshooting',
+          doc: 'https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/v30.1/joins#troubleshooting',
           details: { assoc: key, known: safe_joins_config(klass).keys }
         )
       end
@@ -61,7 +61,7 @@ module SearchEngine
         raise SearchEngine::Errors::InvalidJoinConfig.new(
           msg,
           hint: 'Declare local_key and foreign_key in join config.',
-          doc: 'https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/joins#troubleshooting',
+          doc: 'https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/v30.1/joins#troubleshooting',
           details: { assoc: key, missing: missing }
         )
       end
@@ -80,7 +80,7 @@ module SearchEngine
 
         raise SearchEngine::Errors::JoinNotApplied.new(
           "Call .joins(:#{key}) before #{context} on #{key} fields",
-          doc: 'https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/joins#troubleshooting',
+          doc: 'https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/v30.1/joins#troubleshooting',
           details: { assoc: key, context: context }
         )
       end
@@ -141,7 +141,7 @@ module SearchEngine
 
         raise SearchEngine::Errors::UnsupportedJoinNesting.new(
           'Only one join hop is supported: `$assoc.field`. Use a separate pipeline step to denormalize deeper paths.',
-          doc: 'https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/joins#troubleshooting',
+          doc: 'https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/v30.1/joins#troubleshooting',
           details: { path: path }
         )
       end

data/lib/search_engine/joins/resolver.rb

@@ -52,7 +52,7 @@ module SearchEngine
         model_name = klass.respond_to?(:name) && klass.name ? klass.name : klass.to_s
         raise SearchEngine::Errors::InvalidJoin.new(
           "Unknown #{side} key :#{key} for #{model_name}. Declare it via `attribute :#{key}, ...`.",
-          doc: 'https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/joins#troubleshooting',
+          doc: 'https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/v30.1/joins#troubleshooting',
           details: { side: side, key: key, model: model_name }
         )
       end
@@ -82,7 +82,7 @@ module SearchEngine
               "Could not infer a unique shared key. Candidates: #{sugg}"
         raise SearchEngine::Errors::InvalidJoinConfig.new(
           msg,
-          doc: 'https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/joins#client-side-fallback',
+          doc: 'https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/v30.1/joins#client-side-fallback',
           details: { assoc: assoc_name, candidates: candidates }
         )
       end

data/lib/search_engine/logging_subscriber.rb

@@ -20,8 +20,8 @@ module SearchEngine
   # sample: 0.0 or mode: nil.
   #
   # @since M8
-  # @see https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/observability#logging
-  # @see `https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/observability`
+  # @see https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/v30.1/observability#logging
+  # @see `https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/v30.1/observability`
   module LoggingSubscriber
     class << self
       # Install the subscriber in a reloader-safe and idempotent way.
@@ -29,7 +29,7 @@ module SearchEngine
       # @param config [#mode,#level,#sample,#logger,nil]
       # @return [Object, nil] subscription handle
       # @since M8
-      # @see https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/observability#logging
+      # @see https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/v30.1/observability#logging
       def install!(config = nil)
         uninstall!
 
@@ -60,7 +60,7 @@ module SearchEngine
       # Uninstall previously installed subscriber.
       # @return [Boolean]
       # @since M8
-      # @see https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/observability#logging
+      # @see https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/v30.1/observability#logging
       def uninstall!
         return false unless defined?(ActiveSupport::Notifications)
         return false unless @handle

data/lib/search_engine/mapper.rb

@@ -15,7 +15,7 @@ module SearchEngine
     # Describes where data is fetched from and how records are transformed into
     # Typesense documents. Compiled by {SearchEngine::Mapper.for}.
     #
-    # @see https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/indexer
+    # @see https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/v30.1/indexer
     class Dsl
       # @return [Hash, nil] original source definition captured from DSL
       attr_reader :source_def
@@ -42,7 +42,7 @@ module SearchEngine
       # @yield for :lambda sources
       # @return [void]
       # @raise [ArgumentError] when type is nil/blank
-      # @see https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/indexer
+      # @see https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/v30.1/indexer
       def source(type, **options, &block)
         @source_def = { type: type.to_sym, options: options, block: block }
         nil
@@ -54,7 +54,7 @@ module SearchEngine
       # @yieldreturn [Hash, #to_h, #as_json] a document-like object
       # @return [void]
       # @raise [ArgumentError] when no block is given
-      # @see https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/indexer
+      # @see https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/v30.1/indexer
       def map(&block)
         raise ArgumentError, 'map requires a block' unless block
 
@@ -129,7 +129,7 @@ module SearchEngine
       # @yieldreturn [Enumerable] a list/Enumerable of opaque partition keys
       # @return [void]
       # @raise [ArgumentError] when no block is given
-      # @see https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/indexer#partitioning
+      # @see https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/v30.1/indexer#partitioning
       def partitions(&block)
         raise ArgumentError, 'partitions requires a block' unless block
 
@@ -173,7 +173,7 @@ module SearchEngine
       # @yieldreturn [Enumerable<Array>] yields Arrays of records per batch
       # @return [void]
       # @raise [ArgumentError] when no block is given
-      # @see https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/indexer#partitioning
+      # @see https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/v30.1/indexer#partitioning
       def partition_fetch(&block)
         raise ArgumentError, 'partition_fetch requires a block' unless block
 
@@ -186,7 +186,7 @@ module SearchEngine
       # @yieldparam partition [Object]
       # @return [void]
       # @raise [ArgumentError] when no block is given
-      # @see https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/indexer#partitioning
+      # @see https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/v30.1/indexer#partitioning
       def before_partition(&block)
         raise ArgumentError, 'before_partition requires a block' unless block
 
@@ -212,7 +212,7 @@ module SearchEngine
       # @yieldparam partition [Object]
       # @return [void]
       # @raise [ArgumentError] when no block is given
-      # @see https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/indexer#partitioning
+      # @see https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/v30.1/indexer#partitioning
       def after_partition(&block)
         raise ArgumentError, 'after_partition requires a block' unless block
 
@@ -234,7 +234,7 @@ module SearchEngine
 
       # Freeze internal state for immutability and return a definition Hash.
       # @return [Hash]
-      # @see https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/indexer
+      # @see https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/v30.1/indexer
       def to_definition
         {
           source: @source_def,
@@ -316,7 +316,7 @@ module SearchEngine
     # Validates mapped documents against the compiled schema, sets hidden flags
     # for array/optional fields and emits instrumentation.
     #
-    # @see https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/indexer
+    # @see https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/v30.1/indexer
     class Compiled
       attr_reader :klass
 
@@ -340,32 +340,24 @@ module SearchEngine
       # @return [Array<Array<Hash>, Hash>] [documents, report]
       # @raise [SearchEngine::Errors::InvalidParams] on missing required fields or invalid document shape
       # @raise [SearchEngine::Errors::InvalidField] when strict_unknown_keys is enabled and extras are present
-      # @see https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/indexer#troubleshooting
+      # @see https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/v30.1/indexer#troubleshooting
       def map_batch!(rows, batch_index: nil)
         start_ms = monotonic_ms
         docs = []
         stats = init_stats
+        now_i = defined?(Time.zone) && Time.zone ? Time.zone.now.to_i : Time.now.to_i
 
         rows.each do |row|
           hash = normalize_document(@map_proc.call(row))
-          # Ignore any provided id from map; always inject computed document id
           hash.delete(:id)
           hash.delete('id')
           begin
             computed_id = @klass.compute_document_id(row)
           rescue NoMethodError
-            # Fallback for older compiled mappers if needed; derive from record.id
             rid = row.respond_to?(:id) ? row.id : nil
             computed_id = rid.is_a?(String) ? rid : rid.to_s
           end
           hash[:id] = computed_id
-          # Force system timestamp field on every document; developers cannot override.
-          now_i = if defined?(Time) && defined?(Time.zone) && Time.zone
-                    Time.zone.now.to_i
-                  else
-                    Time.now.to_i
-                  end
-          # Overwrite any provided value
           hash[:doc_updated_at] = now_i
 
           normalize_optional_blank_strings!(hash)
@@ -505,7 +497,7 @@ module SearchEngine
         instrument_error(error_class: 'SearchEngine::Errors::InvalidParams', message: message)
         raise SearchEngine::Errors::InvalidParams.new(
           message,
-          doc: 'https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/indexer#troubleshooting',
+          doc: 'https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/v30.1/indexer#troubleshooting',
           details: { missing_required: stats[:missing_required].sort }
         )
       end
@@ -520,7 +512,7 @@ module SearchEngine
         instrument_error(error_class: 'SearchEngine::Errors::InvalidField', message: message)
         raise SearchEngine::Errors::InvalidField.new(
           message,
-          doc: 'https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/indexer#troubleshooting',
+          doc: 'https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/v30.1/indexer#troubleshooting',
           details: { extras: stats[:extras_samples].sort }
         )
       end

data/lib/search_engine/multi.rb

@@ -51,7 +51,7 @@ module SearchEngine
     # @return [self]
     # @raise [ArgumentError] when label is duplicate/invalid, relation is invalid, or api_key is provided
     # @note Per-search api_key is not supported by the underlying Typesense client and will raise.
-    # @see `https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/multi-search-guide`
+    # @see `https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/v30.1/multi-search-guide`
     def add(label, relation, api_key: nil)
       key = Multi.canonicalize_label(label)
       raise ArgumentError, "Multi#add: duplicate label #{label.inspect} (labels must be unique)." if @keys.include?(key)
@@ -103,7 +103,7 @@ module SearchEngine
     #   m.add(:products, Product.all.per(10))
     #   m.to_payloads(common: { query_by: SearchEngine.config.default_query_by })
     #   # => [{ collection: "products", q: "*", query_by: "name", per_page: 10 }]
-    # @see `https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/multi-search-guide`
+    # @see `https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/v30.1/multi-search-guide`
     def to_payloads(common: {})
       raise ArgumentError, 'common must be a Hash' unless common.is_a?(Hash)
 

data/lib/search_engine/multi_result.rb

@@ -34,7 +34,7 @@ module SearchEngine
     # @param raw_results [Array<Hash>] ordered raw result items (one per label)
     # @param klasses [Array<Class>, Hash{(String,Symbol)=>Class}, nil] optional model classes
     # @raise [ArgumentError] when sizes mismatch, labels invalid/duplicate, or inputs malformed
-    # @see `https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/multi-search-guide`
+    # @see `https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/v30.1/multi-search-guide`
     def initialize(labels:, raw_results:, klasses: nil)
       @labels = canonicalize_labels(labels)
       @map = {}

data/lib/search_engine/notifications/compact_logger.rb

@@ -17,7 +17,7 @@ module SearchEngine
     #   SearchEngine::Notifications::CompactLogger.unsubscribe
     #
     # @since M8
-    # @see https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/observability#logging
+    # @see https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/v30.1/observability#logging
     class CompactLogger
       EVENT_SEARCH = 'search_engine.search'
       EVENT_MULTI  = 'search_engine.multi_search'
@@ -42,7 +42,7 @@ module SearchEngine
       # @param format [Symbol, nil] :kv or :json; defaults to config.observability.log_format
       # @return [Array<Object>] subscription handles that can be passed to {.unsubscribe}
       # @since M8
-      # @see https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/observability#logging
+      # @see https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/v30.1/observability#logging
       def self.subscribe(logger: default_logger, level: :info, include_params: false, format: nil)
         return [] unless defined?(ActiveSupport::Notifications)
 
@@ -57,7 +57,7 @@ module SearchEngine
       # @param handle [Array<Object>, Object, nil] handles returned by {.subscribe}
       # @return [Boolean] true when unsubscribed
       # @since M8
-      # @see https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/observability#logging
+      # @see https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/v30.1/observability#logging
       def self.unsubscribe(handle = @last_handle)
         return false unless handle
 

data/lib/search_engine/otel.rb

@@ -6,7 +6,7 @@ module SearchEngine
   # OpenTelemetry SDK and by `SearchEngine.config.opentelemetry.enabled`.
   #
   # @since M8
-  # @see https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/observability#opentelemetry
+  # @see https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/v30.1/observability#opentelemetry
   #
   # Public API:
   # - .installed? => Boolean
@@ -17,14 +17,14 @@ module SearchEngine
     class << self
       # @return [Boolean] whether the OpenTelemetry SDK is available
       # @since M8
-      # @see https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/observability#opentelemetry
+      # @see https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/v30.1/observability#opentelemetry
       def installed?
         defined?(::OpenTelemetry::SDK)
       end
 
       # @return [Boolean] whether the adapter should be active
       # @since M8
-      # @see https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/observability#opentelemetry
+      # @see https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/v30.1/observability#opentelemetry
       def enabled?
         installed? && SearchEngine.respond_to?(:config) && SearchEngine.config&.opentelemetry&.enabled
       end
@@ -32,7 +32,7 @@ module SearchEngine
       # Start the adapter (idempotent). No-ops when disabled or SDK unavailable.
       # @return [Object, nil] subscription handle or nil when not installed/enabled
       # @since M8
-      # @see https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/observability#opentelemetry
+      # @see https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/v30.1/observability#opentelemetry
       def start!
         stop!
         return nil unless enabled?
@@ -58,7 +58,7 @@ module SearchEngine
       # Stop the adapter if previously started.
       # @return [Boolean]
       # @since M8
-      # @see https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/observability#opentelemetry
+      # @see https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/v30.1/observability#opentelemetry
       def stop!
         return false unless defined?(ActiveSupport::Notifications)
         return false unless @handle

data/lib/search_engine/partitioner.rb

@@ -34,7 +34,7 @@ module SearchEngine
       # Enumerate partition keys. Validates the return value shape.
       # @return [Enumerable] list/Enumerable of opaque partition tokens
       # @raise [SearchEngine::Errors::InvalidParams] when the block does not return an Enumerable
-      # @see https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/indexer#partitioning
+      # @see https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/v30.1/indexer#partitioning
       def partitions
         return [] unless @partitions_proc
 
@@ -42,7 +42,7 @@ module SearchEngine
         unless res.respond_to?(:each)
           raise SearchEngine::Errors::InvalidParams,
                 'partitions block must return an Enumerable of partition keys (Array acceptable). ' \
-                'See https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/indexer#partitioning.'
+                'See https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/v30.1/indexer#partitioning.'
         end
         res
       end
@@ -52,7 +52,7 @@ module SearchEngine
       # @return [Enumerable<Array>] enumerator yielding Arrays of records
       # @raise [ArgumentError] when partition_fetch is not defined
       # @raise [SearchEngine::Errors::InvalidParams] when the block returns a non-enumerable or yields non-arrays
-      # @see https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/indexer#partitioning
+      # @see https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/v30.1/indexer#partitioning
       def partition_fetch_enum(partition)
         raise ArgumentError, 'partition_fetch not defined' unless @partition_fetch_proc
 
@@ -60,7 +60,7 @@ module SearchEngine
         unless enum.respond_to?(:each)
           raise SearchEngine::Errors::InvalidParams,
                 'partition_fetch must return an Enumerable yielding Arrays of records. ' \
-                'See https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/indexer#partitioning.'
+                'See https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/v30.1/indexer#partitioning.'
         end
 
         Enumerator.new do |y|
@@ -90,7 +90,7 @@ module SearchEngine
       # Resolve a compiled partitioner for a model class, or nil if directives are absent.
       # @param klass [Class]
       # @return [SearchEngine::Partitioner::Compiled, nil]
-      # @see https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/indexer#partitioning
+      # @see https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/v30.1/indexer#partitioning
       def for(klass)
         dsl = mapper_dsl_for(klass)
         return nil unless dsl

data/lib/search_engine/ranking_plan.rb

@@ -47,7 +47,7 @@ module SearchEngine
           raise SearchEngine::Errors::InvalidOption.new(
             'InvalidOption: query_by is empty; cannot apply query_by_weights',
             hint: 'Set SearchEngine.config.default_query_by or pass options(query_by: ...)',
-            doc: 'https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/ranking#weights'
+            doc: 'https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/v30.1/ranking#weights'
           )
         end
 
@@ -55,7 +55,7 @@ module SearchEngine
         if normalized_weights.all? { |w| w.to_i.zero? }
           raise SearchEngine::Errors::InvalidOption.new(
             'InvalidOption: at least one weighted field must have weight > 0',
-            doc: 'https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/ranking#weights'
+            doc: 'https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/v30.1/ranking#weights'
           )
         end
         out[:query_by_weights] = normalized_weights.join(',')
@@ -86,7 +86,7 @@ module SearchEngine
                  end
         raise SearchEngine::Errors::InvalidOption.new(
           "InvalidOption: weight specified for unknown field #{unknown.first.inspect}#{suffix}",
-          doc: 'https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/relation-reference#selection',
+          doc: 'https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/v30.1/relation-reference#selection',
           details: { unknown: unknown.first, allowed: known }
         )
       end
@@ -95,7 +95,7 @@ module SearchEngine
     rescue ArgumentError, TypeError
       raise SearchEngine::Errors::InvalidOption.new(
         'InvalidOption: query_by_weights must compile to integers',
-        doc: 'https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/ranking#weights'
+        doc: 'https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/v30.1/ranking#weights'
       )
     end