Skip to content

Supercharge your AI agents with data from the web and beyond. Building the library for superintelligence. 🔥

feat(ruby-sdk): add developer search (#5275)

Erik Engervall74b3cd1f165a
diff --git a/apps/ruby-sdk/README.md b/apps/ruby-sdk/README.md
index 7a2de7f72..2fc581284 100644
--- a/apps/ruby-sdk/README.md
+++ b/apps/ruby-sdk/README.md
@@ -193,6 +193,25 @@ results = client.search("latest news",
Firecrawl::Models::SearchOptions.new(limit: 5, location: "US"))
```
+### Developer Search
+
+Search public repositories, GitHub issues, merged pull requests, READMEs and code documentation. `developer_search` replaces the deprecated `search_github`.
+
+```ruby
+response = client.developer_search(
+ "retry an http request with exponential backoff",
+ Firecrawl::Models::DeveloperSearchOptions.new(
+ k: 5,
+ types: ["issue", "pull_request"],
+ repos: ["square/okhttp"]
+ )
+)
+
+response.results.each do |result|
+ puts "#{result.title} #{result.url}"
+end
+```
+
### Agent
```ruby
diff --git a/apps/ruby-sdk/lib/firecrawl.rb b/apps/ruby-sdk/lib/firecrawl.rb
index d1ddee372..80265fdee 100644
--- a/apps/ruby-sdk/lib/firecrawl.rb
+++ b/apps/ruby-sdk/lib/firecrawl.rb
@@ -20,6 +20,8 @@ require_relative "firecrawl/models/map_options"
require_relative "firecrawl/models/map_data"
require_relative "firecrawl/models/search_options"
require_relative "firecrawl/models/search_data"
+require_relative "firecrawl/models/developer_search_options"
+require_relative "firecrawl/models/developer_search_response"
require_relative "firecrawl/models/parse_file"
require_relative "firecrawl/models/parse_options"
require_relative "firecrawl/models/parse_format"
diff --git a/apps/ruby-sdk/lib/firecrawl/client.rb b/apps/ruby-sdk/lib/firecrawl/client.rb
index 9d2233763..526c8da89 100644
--- a/apps/ruby-sdk/lib/firecrawl/client.rb
+++ b/apps/ruby-sdk/lib/firecrawl/client.rb
@@ -133,10 +133,9 @@ module Firecrawl
# Search GitHub research content.
#
- # @deprecated Stops responding after 2026-11-03. Use the developer index at
- # GET or POST /v2/search/developer, which this SDK does not wrap yet, so
- # call it directly. It does not carry over the score breakdown or the
- # web fallback results.
+ # @deprecated Stops responding after 2026-11-03. Use {#developer_search},
+ # which does not carry over the score breakdown or the web fallback
+ # results.
# @param query_text [String] GitHub query
# @param options [Hash] optional query parameters
# @return [Hash]
@@ -144,6 +143,22 @@ module Firecrawl
@http.get("/v2/search/research/github#{query(options.merge("query" => query_text, "origin" => "ruby-sdk@#{Firecrawl::VERSION}"))}")
end
+ # Searches the developer index: public repositories, GitHub issues, merged
+ # pull requests, READMEs and code documentation.
+ #
+ # @param query [String] the search query
+ # @param options [Models::DeveloperSearchOptions, nil] developer search filters
+ # @return [Models::DeveloperSearchResponse]
+ # @raise [ArgumentError] if the query is blank
+ def developer_search(query, options = nil)
+ raise ArgumentError, "Query is required" if query.nil? || query.to_s.strip.empty?
+
+ body = { "query" => query }
+ body.merge!(options.to_h) if options
+ body["origin"] ||= "ruby-sdk@#{Firecrawl::VERSION}"
+ Models::DeveloperSearchResponse.new(@http.post("/v2/search/developer", body))
+ end
+
# Interacts with the scrape-bound browser session for a scrape job.
#
# @param job_id [String] the scrape job ID
diff --git a/apps/ruby-sdk/lib/firecrawl/models/developer_search_options.rb b/apps/ruby-sdk/lib/firecrawl/models/developer_search_options.rb
new file mode 100644
index 000000000..06d871811
--- /dev/null
+++ b/apps/ruby-sdk/lib/firecrawl/models/developer_search_options.rb
@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Firecrawl
+ module Models
+ # Options for a developer search request. Unset fields are omitted.
+ #
+ # - k: total ranked results, 1 to 100 (default 10)
+ # - passages: passages per result, 1 to 5 (default 1)
+ # - types: result kinds, any of "doc", "issue", "pull_request", "readme"
+ # - repos: GitHub owner/name filters, at most 20
+ # - sources: developer documentation source IDs, at most 20
+ # - language: one case-insensitive GitHub Linguist primary language
+ # - topic: repository topics that must all match, at most 8
+ # - license: one case-insensitive SPDX repository license identifier
+ # - min_stars, max_stars, archived, fork: repository filters
+ # - skills: "only" returns packaged agent-skill evidence only
+ class DeveloperSearchOptions
+ FIELDS = %i[
+ k passages types repos sources language topic license
+ min_stars max_stars archived fork skills
+ ].freeze
+
+ attr_reader(*FIELDS)
+
+ def initialize(**kwargs)
+ unknown = kwargs.keys - FIELDS
+ raise ArgumentError, "unknown developer search option(s): #{unknown.join(", ")}" unless unknown.empty?
+
+ FIELDS.each { |f| instance_variable_set(:"@#{f}", kwargs[f]) }
+ end
+
+ def to_h
+ FIELDS.to_h { |f| [f.to_s, public_send(f)] }.compact
+ end
+ end
+ end
+end
diff --git a/apps/ruby-sdk/lib/firecrawl/models/developer_search_response.rb b/apps/ruby-sdk/lib/firecrawl/models/developer_search_response.rb
new file mode 100644
index 000000000..3229888fa
--- /dev/null
+++ b/apps/ruby-sdk/lib/firecrawl/models/developer_search_response.rb
@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Firecrawl
+ module Models
+ # One matched passage of a developer search result.
+ class DeveloperSearchPassage
+ attr_reader :text, :citation_url
+
+ def initialize(data)
+ @text = data["text"]
+ @citation_url = data["citation_url"]
+ end
+ end
+
+ # One ranked developer search result. `license` is either an SPDX string or
+ # a disclosure object (Hash), so it is kept as returned.
+ class DeveloperSearchResult
+ attr_reader :id, :url, :title, :passages, :license
+
+ def initialize(data)
+ @id = data["id"]
+ @url = data["url"]
+ @title = data["title"]
+ @passages = (data["passages"] || []).map { |p| DeveloperSearchPassage.new(p) }
+ @license = data["license"]
+ end
+ end
+
+ # Whether a requested repository is indexed, and which result types it has.
+ class DeveloperSearchRepoStatus
+ attr_reader :repo, :indexed, :types
+
+ def initialize(data)
+ @repo = data["repo"]
+ @indexed = data["indexed"] == true
+ @types = data["types"] || {}
+ end
+
+ def indexed?
+ indexed
+ end
+ end
+
+ # Whether a requested documentation source is indexed.
+ class DeveloperSearchSourceStatus
+ attr_reader :source, :indexed
+
+ def initialize(data)
+ @source = data["source"]
+ @indexed = data["indexed"] == true
+ end
+
+ def indexed?
+ indexed
+ end
+ end
+
+ # Response from a developer search. `repos` and `sources` are present only
+ # when those filters were requested.
+ class DeveloperSearchResponse
+ attr_reader :success, :partial, :results, :repos, :sources
+
+ def initialize(data)
+ @success = data["success"] == true
+ @partial = data["partial"] == true
+ @results = (data["results"] || []).map { |r| DeveloperSearchResult.new(r) }
+ @repos = data["repos"]&.map { |r| DeveloperSearchRepoStatus.new(r) }
+ @sources = data["sources"]&.map { |s| DeveloperSearchSourceStatus.new(s) }
+ end
+
+ def to_s
+ "DeveloperSearchResponse{results=#{results.size}}"
+ end
+ end
+ end
+end
diff --git a/apps/ruby-sdk/lib/firecrawl/version.rb b/apps/ruby-sdk/lib/firecrawl/version.rb
index 62d352d94..3ed25000b 100644
--- a/apps/ruby-sdk/lib/firecrawl/version.rb
+++ b/apps/ruby-sdk/lib/firecrawl/version.rb
@@ -1,5 +1,5 @@
# frozen_string_literal: true
module Firecrawl
- VERSION = "1.17.6"
+ VERSION = "1.17.7"
end
diff --git a/apps/ruby-sdk/test/firecrawl/client_test.rb b/apps/ruby-sdk/test/firecrawl/client_test.rb
index 5417dae85..aa6db00a4 100644
--- a/apps/ruby-sdk/test/firecrawl/client_test.rb
+++ b/apps/ruby-sdk/test/firecrawl/client_test.rb
@@ -654,6 +654,82 @@ class ClientTest < Minitest::Test
assert_equal 0, result.web.size
end
+ # ================================================================
+ # DEVELOPER SEARCH
+ # ================================================================
+
+ def test_developer_search_posts_query_and_options
+ origin = "ruby-sdk@#{Firecrawl::VERSION}"
+ stub = stub_request(:post, "#{BASE_URL}/v2/search/developer")
+ .with(body: {
+ "query" => "retry backoff", "k" => 5, "types" => ["issue"], "repos" => ["square/okhttp"],
+ "min_stars" => 100, "archived" => false, "origin" => origin
+ })
+ .to_return(
+ status: 200,
+ body: JSON.generate(
+ success: true,
+ partial: false,
+ results: [
+ {
+ id: "r1", url: "https://github.com/square/okhttp/issues/1", title: "retry",
+ passages: [{ text: "use backoff", citation_url: "https://github.com/square/okhttp/issues/1#c1" }],
+ license: { state: "licensed", spdx_id: "Apache-2.0" }
+ },
+ { id: "r2", url: "https://github.com/square/okhttp", passages: [], license: "Apache-2.0" }
+ ],
+ repos: [{ repo: "square/okhttp", indexed: true, types: { issue: true, pullRequest: true, readme: false } }]
+ ),
+ headers: { "Content-Type" => "application/json" }
+ )
+
+ options = Firecrawl::Models::DeveloperSearchOptions.new(
+ k: 5, types: ["issue"], repos: ["square/okhttp"], min_stars: 100, archived: false
+ )
+ response = @client.developer_search("retry backoff", options)
+
+ assert_requested stub
+ assert_instance_of Firecrawl::Models::DeveloperSearchResponse, response
+ assert response.success
+ refute response.partial
+ assert_equal 2, response.results.size
+ assert_equal "https://github.com/square/okhttp/issues/1#c1", response.results[0].passages[0].citation_url
+ assert_equal "Apache-2.0", response.results[0].license["spdx_id"]
+ assert_equal "Apache-2.0", response.results[1].license
+ assert_nil response.results[1].title
+ assert response.repos[0].indexed?
+ assert response.repos[0].types["pullRequest"]
+ assert_nil response.sources
+ end
+
+ def test_developer_search_without_options_sends_only_query_and_origin
+ stub = stub_request(:post, "#{BASE_URL}/v2/search/developer")
+ .with(body: { "query" => "okhttp interceptor", "origin" => "ruby-sdk@#{Firecrawl::VERSION}" })
+ .to_return(
+ status: 200,
+ body: JSON.generate(success: true, partial: true, results: []),
+ headers: { "Content-Type" => "application/json" }
+ )
+
+ response = @client.developer_search("okhttp interceptor")
+
+ assert_requested stub
+ assert response.partial
+ assert_empty response.results
+ end
+
+ def test_developer_search_options_reject_unknown_keys
+ error = assert_raises(ArgumentError) { Firecrawl::Models::DeveloperSearchOptions.new(min_star: 5) }
+ assert_includes error.message, "min_star"
+ end
+
+ def test_developer_search_rejects_blank_query
+ assert_raises(ArgumentError) { @client.developer_search(nil) }
+ assert_raises(ArgumentError) { @client.developer_search("") }
+ assert_raises(ArgumentError) { @client.developer_search(" ") }
+ assert_not_requested :post, "#{BASE_URL}/v2/search/developer"
+ end
+
# ================================================================
# AGENT
# ================================================================