firecrawl-sdk 1.8.0 → 1.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2e60c06ab05dc82b6a73b45fd0653e25ea9a52e6995b653adc02de1ead2544fc
-  data.tar.gz: 9d7229377ce68b2bf96edce29aa9db2685d11c45c108e1cdb4bab7f9b29b4081
+  metadata.gz: 027be403af5ba321ba2d4dbeaa774433666ece0a98cca4ac03ffbce52ac6cae2
+  data.tar.gz: d0ee19ba03f949234d00482c6e0c451986de84c4e4dfde7860c970845a23e3b4
 SHA512:
-  metadata.gz: 88f68bb69bf81891e6768901dfcdd7ee04c8dc2d878056f85311a7acf79f5a2fe5a8dc9ef6c9cd03570e690404bf498cccc994c733b9261d96a829ae78a581fa
-  data.tar.gz: ec03a978278b33c33e5452b8876a80ba205401e5a4689c023ed9ad1afa62cb28720cbb41d4e21272e4fb077f6b4c2767b6cfbe375b6d041b84246488162f212d
+  metadata.gz: fb9869b378f9d8252cd45ad2b5be1d7f5e9c30f3c67d4752177e3d205a689b75f3da972f389e5d70260bbde576e1677068c4b538ea82c92c25643a239debd879
+  data.tar.gz: f8ad0a882856666ef4662d6356608759513305babc5392100c1cba5ddcaffb89392c67c447aa181cb3ab97230cd0bec4f7f957c11e4585068ef58a2eadcbacda

data/lib/firecrawl/client.rb

@@ -39,9 +39,10 @@ module Firecrawl
       backoff_factor: DEFAULT_BACKOFF_FACTOR
     )
       resolved_key = api_key || ENV["FIRECRAWL_API_KEY"]
-      if resolved_key.nil? || resolved_key.strip.empty?
-        raise FirecrawlError, "API key is required. Provide api_key: or set FIRECRAWL_API_KEY environment variable."
-      end
+      # A nil/empty key is allowed: scrape, search, and interact fall back to the
+      # keyless free tier (rate-limited per IP). Other methods return 401 from the
+      # API until a key is provided.
+      resolved_key = nil if resolved_key.nil? || resolved_key.strip.empty?
 
       resolved_url = api_url || ENV["FIRECRAWL_API_URL"] || DEFAULT_API_URL
       unless resolved_url.match?(%r{\Ahttps?://}i)
@@ -78,11 +79,63 @@ module Firecrawl
 
       body = { "url" => url }
       body.merge!(options.to_h) if options
+      body["origin"] ||= "ruby-sdk@#{Firecrawl::VERSION}"
       raw = @http.post("/v2/scrape", body)
       data = raw["data"] || raw
       Models::Document.new(data)
     end
 
+    # Search research papers.
+    #
+    # @param query [String] research query
+    # @param options [Hash] optional query parameters
+    # @return [Hash]
+    def search_papers(query, options = {})
+      @http.get("/v2/search/research/papers#{query(options.merge("query" => query, "origin" => "ruby-sdk@#{Firecrawl::VERSION}"))}")
+    end
+
+    # Inspect paper metadata.
+    #
+    # @param paper_id [String] paper identifier
+    # @return [Hash]
+    def inspect_paper(paper_id)
+      raise ArgumentError, "Paper ID is required" if paper_id.nil?
+      @http.get("/v2/search/research/papers/#{URI.encode_www_form_component(paper_id)}")
+    end
+
+    # Read a paper with query-guided passages.
+    #
+    # @param paper_id [String] paper identifier
+    # @param query_text [String] passage query
+    # @param options [Hash] optional query parameters
+    # @return [Hash]
+    def read_paper(paper_id, query_text, options = {})
+      raise ArgumentError, "Paper ID is required" if paper_id.nil?
+      path = "/v2/search/research/papers/#{URI.encode_www_form_component(paper_id)}"
+      @http.get("#{path}#{query(options.merge("query" => query_text, "origin" => "ruby-sdk@#{Firecrawl::VERSION}"))}")
+    end
+
+    # Find papers related to a paper.
+    #
+    # @param paper_id [String] paper identifier
+    # @param intent [String] relatedness intent
+    # @param options [Hash] optional query parameters
+    # @return [Hash]
+    def related_papers(paper_id, intent, options = {})
+      raise ArgumentError, "Paper ID is required" if paper_id.nil?
+      path = "/v2/search/research/papers/#{URI.encode_www_form_component(paper_id)}/similar"
+      @http.get("#{path}#{query(options.merge("intent" => intent, "origin" => "ruby-sdk@#{Firecrawl::VERSION}"))}")
+    end
+
+    # Search GitHub research content.
+    #
+    # @param query_text [String] GitHub query
+    # @param options [Hash] optional query parameters
+    # @return [Hash]
+    def search_github(query_text, options = {})
+      @http.get("/v2/search/research/github#{query(options.merge("query" => query_text, "origin" => "ruby-sdk@#{Firecrawl::VERSION}"))}")
+    end
+
     # Interacts with the scrape-bound browser session for a scrape job.
     #
     # @param job_id [String] the scrape job ID
@@ -96,6 +149,7 @@ module Firecrawl
 
       body = { "code" => code, "language" => language }
       body["timeout"] = timeout if timeout
+      body["origin"] ||= "ruby-sdk@#{Firecrawl::VERSION}"
       @http.post("/v2/scrape/#{job_id}/interact", body)
     end
 
@@ -377,6 +431,7 @@ module Firecrawl
 
       body = { "query" => query }
       body.merge!(options.to_h) if options
+      body["origin"] ||= "ruby-sdk@#{Firecrawl::VERSION}"
       raw = @http.post("/v2/search", body)
       data = raw["data"] || raw
       Models::SearchData.new(data)
@@ -461,9 +516,21 @@ module Firecrawl
 
     private
 
-    def query(**params)
-      compact = params.compact
-      compact.empty? ? "" : "?#{URI.encode_www_form(compact)}"
+    def query(params = nil, **kwargs)
+      params = (params || {}).merge(kwargs)
+      pairs = []
+      params.each do |key, value|
+        next if value.nil? || value == ""
+
+        values = value.is_a?(Array) ? value : [value]
+        values.each do |item|
+          next if item.nil? || item == ""
+
+          string_value = item == true ? "true" : item == false ? "false" : item.to_s
+          pairs << [key.to_s, string_value]
+        end
+      end
+      pairs.empty? ? "" : "?#{URI.encode_www_form(pairs)}"
     end
 
     def poll_crawl(job_id, poll_interval, timeout)

data/lib/firecrawl/http_client.rb

@@ -23,7 +23,7 @@ module Firecrawl
     def post(path, body, extra_headers: {})
       uri = URI("#{@base_url}#{path}")
       request = Net::HTTP::Post.new(uri)
-      request["Authorization"] = "Bearer #{@api_key}"
+      request["Authorization"] = "Bearer #{@api_key}" if @api_key
       request["Content-Type"] = "application/json"
       extra_headers.each { |k, v| request[k] = v }
       request.body = JSON.generate(body)
@@ -34,7 +34,7 @@ module Firecrawl
     def get(path)
       uri = URI("#{@base_url}#{path}")
       request = Net::HTTP::Get.new(uri)
-      request["Authorization"] = "Bearer #{@api_key}"
+      request["Authorization"] = "Bearer #{@api_key}" if @api_key
       execute_with_retry(uri, request)
     end
 
@@ -47,7 +47,7 @@ module Firecrawl
         raise FirecrawlError, "Absolute URL origin (#{uri.scheme}://#{uri.host}:#{uri.port}) does not match API base URL origin (#{base_uri.scheme}://#{base_uri.host}:#{base_uri.port}). Refusing to send credentials."
       end
       request = Net::HTTP::Get.new(uri)
-      request["Authorization"] = "Bearer #{@api_key}"
+      request["Authorization"] = "Bearer #{@api_key}" if @api_key
       execute_with_retry(uri, request)
     end
 
@@ -55,7 +55,7 @@ module Firecrawl
     def delete(path)
       uri = URI("#{@base_url}#{path}")
       request = Net::HTTP::Delete.new(uri)
-      request["Authorization"] = "Bearer #{@api_key}"
+      request["Authorization"] = "Bearer #{@api_key}" if @api_key
       execute_with_retry(uri, request)
     end
 
@@ -63,7 +63,7 @@ module Firecrawl
     def patch(path, body)
       uri = URI("#{@base_url}#{path}")
       request = Net::HTTP::Patch.new(uri)
-      request["Authorization"] = "Bearer #{@api_key}"
+      request["Authorization"] = "Bearer #{@api_key}" if @api_key
       request["Content-Type"] = "application/json"
       request.body = JSON.generate(body)
       execute_with_retry(uri, request)
@@ -84,7 +84,7 @@ module Firecrawl
 
       builder = lambda do
         request = Net::HTTP::Post.new(uri)
-        request["Authorization"] = "Bearer #{@api_key}"
+        request["Authorization"] = "Bearer #{@api_key}" if @api_key
         request["Content-Type"] = "multipart/form-data; boundary=#{boundary}"
         request.body = body
         request

data/lib/firecrawl/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Firecrawl
-  VERSION = "1.8.0"
+  VERSION = "1.9.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: firecrawl-sdk
 version: !ruby/object:Gem::Version
-  version: 1.8.0
+  version: 1.9.0
 platform: ruby
 authors:
 - Firecrawl
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-01 00:00:00.000000000 Z
+date: 2026-06-16 00:00:00.000000000 Z
 dependencies: []
 description: A type-safe Ruby client for the Firecrawl v2 API. Supports scraping,
   crawling, batch scraping, URL mapping, web search, and AI agent operations.