Supercharge your AI agents with data from the web and beyond. Building the library for superintelligence. 🔥
TypeScript aiai-agentsai-crawlerai-scrapingai-searchcrawlerdata-extractionhtml-to-markdownllmmarkdownscraperscrapingweb-crawlerweb-dataweb-data-extractionweb-scraperweb-scrapingweb-searchwebscraping
feat(ruby-sdk): add Firecrawl Ruby SDK v2
firecrawl-spring[bot]e5d387fe2391
diff --git a/.github/scripts/check_version_has_incremented.py b/.github/scripts/check_version_has_incremented.pyindex 34c56d838..03f321499 100644--- a/.github/scripts/check_version_has_incremented.py+++ b/.github/scripts/check_version_has_incremented.py@@ -18,6 +18,11 @@ Local version: 1.0.0Published version: 0.0.0 (0.0.0 means not yet published on Maven Central)true+python .github/scripts/check_version_has_incremented.py ruby ./apps/ruby-sdk firecrawl+Local version: 1.0.0+Published version: 0.0.0 (0.0.0 means not yet published on RubyGems)+true+"""import jsonimport os@@ -66,6 +71,22 @@ def get_gradle_version(file_path: str) -> str:return version_match.group(1).strip()raise RuntimeError("Unable to find version string in build.gradle.kts.")+def get_ruby_version(file_path: str) -> str:+ """Extract version string from Ruby version file (lib/firecrawl/version.rb)."""+ version_file = Path(file_path).read_text()+ version_match = re.search(r'VERSION\s*=\s*["\']([^"\']*)["\']', version_file, re.M)+ if version_match:+ return version_match.group(1).strip()+ raise RuntimeError("Unable to find version string in Ruby version file.")++def get_rubygems_version(package_name: str) -> str:+ """Get latest version of Ruby gem from RubyGems.org."""+ response = requests.get(f"https://rubygems.org/api/v1/versions/{package_name}/latest.json")+ if response.status_code == 404:+ return "0.0.0"+ version = response.json()['version']+ return version.strip()+def get_maven_central_version(package_name: str) -> str:"""Get latest version of Java package from Maven Central. package_name should be groupId:artifactId."""group_id, artifact_id = package_name.split(":")@@ -121,6 +142,11 @@ if __name__ == "__main__":current_version = get_gradle_version(os.path.join(package_path, 'build.gradle.kts'))# Get published version from Maven Centralpublished_version = get_maven_central_version(package_name)+ elif package_type == "ruby":+ # Get current version from lib/firecrawl/version.rb+ current_version = get_ruby_version(os.path.join(package_path, 'lib', 'firecrawl', 'version.rb'))+ # Get published version from RubyGems+ published_version = get_rubygems_version(package_name)# if package_type == "rust":# # Get current version from Cargo.toml# current_version = get_rust_version(os.path.join(package_path, 'Cargo.toml'))@@ -128,7 +154,7 @@ if __name__ == "__main__":# published_version = get_crates_version(package_name)else:- raise ValueError("Invalid package type. Use 'python', 'js', or 'java'.")+ raise ValueError("Invalid package type. Use 'python', 'js', 'java', or 'ruby'.")# Print versions for debugging# print(f"Local version: {current_version}")diff --git a/.github/workflows/publish-ruby-sdk.yml b/.github/workflows/publish-ruby-sdk.ymlnew file mode 100644index 000000000..638181a6f--- /dev/null+++ b/.github/workflows/publish-ruby-sdk.yml@@ -0,0 +1,50 @@+name: Publish Ruby SDK++on:+ workflow_dispatch:+ push:+ branches:+ - main+ paths:+ - 'apps/ruby-sdk/**'++jobs:+ publish:+ name: Publish to RubyGems+ runs-on: blacksmith-2vcpu-ubuntu-2404+ steps:+ - name: Checkout repository+ uses: actions/checkout@v5++ - name: Set up Python+ uses: actions/setup-python@v5+ with:+ python-version: '3.x'++ - name: Install version check dependencies+ run: pip install requests packaging++ - name: Run version check script+ id: version_check+ run: |+ VERSION_INCREMENTED=$(python .github/scripts/check_version_has_incremented.py ruby ./apps/ruby-sdk firecrawl)+ echo "VERSION_INCREMENTED=$VERSION_INCREMENTED" >> $GITHUB_ENV++ - name: Set up Ruby+ if: ${{ env.VERSION_INCREMENTED == 'true' }}+ uses: ruby/setup-ruby@v1+ with:+ ruby-version: '3.3'+ working-directory: ./apps/ruby-sdk++ - name: Build gem+ if: ${{ env.VERSION_INCREMENTED == 'true' }}+ working-directory: ./apps/ruby-sdk+ run: gem build firecrawl.gemspec++ - name: Publish to RubyGems+ if: ${{ env.VERSION_INCREMENTED == 'true' }}+ working-directory: ./apps/ruby-sdk+ env:+ GEM_HOST_API_KEY: ${{ secrets.RUBYGEMS_API_KEY }}+ run: gem push firecrawl-*.gemdiff --git a/.github/workflows/test-ruby-sdk.yml b/.github/workflows/test-ruby-sdk.ymlnew file mode 100644index 000000000..7a26621e3--- /dev/null+++ b/.github/workflows/test-ruby-sdk.yml@@ -0,0 +1,41 @@+name: Ruby SDK Test Suite++on:+ pull_request:+ branches:+ - main+ paths:+ - apps/ruby-sdk/**+ - .github/workflows/test-ruby-sdk.yml+ push:+ branches:+ - main+ paths:+ - apps/ruby-sdk/**+ workflow_dispatch:++jobs:+ build-and-test:+ name: Build and Test+ runs-on: blacksmith-4vcpu-ubuntu-2404+ if: >-+ github.event_name == 'workflow_dispatch' ||+ github.event_name == 'pull_request' ||+ (github.event_name == 'push' && github.ref == 'refs/heads/main')+ steps:+ - uses: actions/checkout@v4++ - name: Set up Ruby+ uses: ruby/setup-ruby@v1+ with:+ ruby-version: "3.3"+ bundler-cache: true+ working-directory: ./apps/ruby-sdk++ - name: Install dependencies+ working-directory: ./apps/ruby-sdk+ run: bundle install++ - name: Run unit tests+ working-directory: ./apps/ruby-sdk+ run: bundle exec rake testdiff --git a/apps/ruby-sdk/.gitignore b/apps/ruby-sdk/.gitignorenew file mode 100644index 000000000..b698bc765--- /dev/null+++ b/apps/ruby-sdk/.gitignore@@ -0,0 +1,6 @@+*.gem+.bundle/+Gemfile.lock+pkg/+tmp/+vendor/bundle/diff --git a/apps/ruby-sdk/Gemfile b/apps/ruby-sdk/Gemfilenew file mode 100644index 000000000..3ac1a4468--- /dev/null+++ b/apps/ruby-sdk/Gemfile@@ -0,0 +1,11 @@+# frozen_string_literal: true++source "https://rubygems.org"++gemspec++group :development, :test do+ gem "minitest", "~> 5.25"+ gem "rake", "~> 13.0"+ gem "webmock", "~> 3.24"+enddiff --git a/apps/ruby-sdk/LICENSE b/apps/ruby-sdk/LICENSEnew file mode 100644index 000000000..0b574f0c0--- /dev/null+++ b/apps/ruby-sdk/LICENSE@@ -0,0 +1,21 @@+MIT License++Copyright (c) 2025 Firecrawl++Permission is hereby granted, free of charge, to any person obtaining a copy+of this software and associated documentation files (the "Software"), to deal+in the Software without restriction, including without limitation the rights+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell+copies of the Software, and to permit persons to whom the Software is+furnished to do so, subject to the following conditions:++The above copyright notice and this permission notice shall be included in all+copies or substantial portions of the Software.++THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE+SOFTWARE.diff --git a/apps/ruby-sdk/README.md b/apps/ruby-sdk/README.mdnew file mode 100644index 000000000..dea2a91c6--- /dev/null+++ b/apps/ruby-sdk/README.md@@ -0,0 +1,197 @@+# Firecrawl Ruby SDK++Ruby SDK for the [Firecrawl](https://firecrawl.dev) v2 web scraping API.++## Prerequisites++- Ruby >= 3.0++## Installation++Add to your `Gemfile`:++```ruby+gem "firecrawl", "~> 1.0"+```++Or install directly:++```bash+gem install firecrawl+```++## Quick Start++```ruby+require "firecrawl"++# Create a client+client = Firecrawl::Client.new(api_key: "fc-your-api-key")++# Or load from FIRECRAWL_API_KEY environment variable+client = Firecrawl::Client.from_env++# Scrape a single page+doc = client.scrape("https://example.com")+puts doc.markdown+```++## Environment Setup++```bash+export FIRECRAWL_API_KEY="fc-your-api-key"+# Optional: custom API URL+export FIRECRAWL_API_URL="http://localhost:3002"+```++## API Reference++### Scrape++```ruby+# Basic scrape+doc = client.scrape("https://example.com")+puts doc.markdown++# Scrape with options+doc = client.scrape("https://example.com",+ Firecrawl::Models::ScrapeOptions.new(+ formats: ["markdown", "html"],+ only_main_content: true,+ wait_for: 1000+ ))+puts doc.html+```++### Crawl++```ruby+# Crawl with auto-polling (blocks until complete)+job = client.crawl("https://example.com",+ Firecrawl::Models::CrawlOptions.new(limit: 50))+job.data.each { |doc| puts doc.markdown }++# Async crawl+response = client.start_crawl("https://example.com",+ Firecrawl::Models::CrawlOptions.new(limit: 10))+puts response.id++# Check status+status = client.get_crawl_status(response.id)+puts status.status++# Cancel+client.cancel_crawl(response.id)+```++### Batch Scrape++```ruby+urls = ["https://example.com/page1", "https://example.com/page2"]++# Batch scrape with auto-polling+job = client.batch_scrape(urls,+ Firecrawl::Models::BatchScrapeOptions.new(+ options: Firecrawl::Models::ScrapeOptions.new(formats: ["markdown"])+ ))+job.data.each { |doc| puts doc.markdown }+```++### Map++```ruby+# Discover URLs on a website+result = client.map("https://example.com")+result.links.each { |link| puts link["url"] }++# With options+result = client.map("https://example.com",+ Firecrawl::Models::MapOptions.new(limit: 100, search: "blog"))+```++### Search++```ruby+# Web search+results = client.search("firecrawl web scraping")+results.web&.each { |r| puts r["url"] }++# With options+results = client.search("latest news",+ Firecrawl::Models::SearchOptions.new(limit: 5, location: "US"))+```++### Agent++```ruby+# Run an AI agent task (blocks until complete)+status = client.agent(+ Firecrawl::Models::AgentOptions.new(+ prompt: "Find the pricing information",+ urls: ["https://example.com"]+ ))+puts status.data+```++### Usage & Metrics++```ruby+# Check concurrency+concurrency = client.get_concurrency+puts concurrency.concurrency++# Check credit usage+usage = client.get_credit_usage+puts usage.remaining_credits+```++## Configuration++```ruby+client = Firecrawl::Client.new(+ api_key: "fc-your-api-key",+ api_url: "https://api.firecrawl.dev", # custom API URL+ timeout: 300, # HTTP timeout in seconds+ max_retries: 3, # automatic retries+ backoff_factor: 0.5 # exponential backoff factor+)+```++## Error Handling++```ruby+begin+ doc = client.scrape("https://example.com")+rescue Firecrawl::AuthenticationError => e+ puts "Invalid API key: #{e.message}"+rescue Firecrawl::RateLimitError => e+ puts "Rate limited: #{e.message}"+rescue Firecrawl::JobTimeoutError => e+ puts "Job #{e.job_id} timed out after #{e.timeout_seconds}s"+rescue Firecrawl::FirecrawlError => e+ puts "Error (#{e.status_code}): #{e.message}"+end+```++## Development++### Building from Source++```bash+cd apps/ruby-sdk+bundle install+```++### Running Tests++```bash+# Unit tests+bundle exec rake test++# With API key for E2E tests+FIRECRAWL_API_KEY=fc-your-key bundle exec rake test+```++## License++MIT License - see [LICENSE](LICENSE).diff --git a/apps/ruby-sdk/Rakefile b/apps/ruby-sdk/Rakefilenew file mode 100644index 000000000..6d5767daa--- /dev/null+++ b/apps/ruby-sdk/Rakefile@@ -0,0 +1,11 @@+# frozen_string_literal: true++require "rake/testtask"++Rake::TestTask.new(:test) do |t|+ t.libs << "test"+ t.libs << "lib"+ t.test_files = FileList["test/**/*_test.rb"]+end++task default: :testdiff --git a/apps/ruby-sdk/firecrawl.gemspec b/apps/ruby-sdk/firecrawl.gemspecnew file mode 100644index 000000000..2d1fb1161--- /dev/null+++ b/apps/ruby-sdk/firecrawl.gemspec@@ -0,0 +1,26 @@+# frozen_string_literal: true++require_relative "lib/firecrawl/version"++Gem::Specification.new do |spec|+ spec.name = "firecrawl"+ spec.version = Firecrawl::VERSION+ spec.authors = ["Firecrawl"]+ spec.email = ["[email protected]"]++ spec.summary = "Ruby SDK for the Firecrawl v2 web scraping API"+ spec.description = "A type-safe Ruby client for the Firecrawl v2 API. " \+ "Supports scraping, crawling, batch scraping, URL mapping, " \+ "web search, and AI agent operations."+ spec.homepage = "https://github.com/mendableai/firecrawl"+ spec.license = "MIT"+ spec.required_ruby_version = ">= 3.0.0"++ spec.metadata["homepage_uri"] = spec.homepage+ spec.metadata["source_code_uri"] = "https://github.com/mendableai/firecrawl/tree/main/apps/ruby-sdk"+ spec.metadata["changelog_uri"] = "https://github.com/mendableai/firecrawl/releases"+ spec.metadata["rubygems_mfa_required"] = "true"++ spec.files = Dir["lib/**/*.rb", "LICENSE", "README.md"]+ spec.require_paths = ["lib"]+enddiff --git a/apps/ruby-sdk/lib/firecrawl.rb b/apps/ruby-sdk/lib/firecrawl.rbnew file mode 100644index 000000000..ec812aeab--- /dev/null+++ b/apps/ruby-sdk/lib/firecrawl.rb@@ -0,0 +1,23 @@+# frozen_string_literal: true++require_relative "firecrawl/version"+require_relative "firecrawl/errors"+require_relative "firecrawl/http_client"+require_relative "firecrawl/models/document"+require_relative "firecrawl/models/scrape_options"+require_relative "firecrawl/models/crawl_options"+require_relative "firecrawl/models/crawl_response"+require_relative "firecrawl/models/crawl_job"+require_relative "firecrawl/models/batch_scrape_options"+require_relative "firecrawl/models/batch_scrape_response"+require_relative "firecrawl/models/batch_scrape_job"+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/agent_options"+require_relative "firecrawl/models/agent_response"+require_relative "firecrawl/models/agent_status_response"+require_relative "firecrawl/models/concurrency_check"+require_relative "firecrawl/models/credit_usage"+require_relative "firecrawl/client"diff --git a/apps/ruby-sdk/lib/firecrawl/client.rb b/apps/ruby-sdk/lib/firecrawl/client.rbnew file mode 100644index 000000000..b7920c9ed--- /dev/null+++ b/apps/ruby-sdk/lib/firecrawl/client.rb@@ -0,0 +1,393 @@+# frozen_string_literal: true++module Firecrawl+ # Client for the Firecrawl v2 API.+ #+ # @example Quick start+ # client = Firecrawl::Client.new(api_key: "fc-your-api-key")+ #+ # # Scrape a single page+ # doc = client.scrape("https://example.com",+ # Firecrawl::Models::ScrapeOptions.new(formats: ["markdown"]))+ #+ # # Crawl a website+ # job = client.crawl("https://example.com",+ # Firecrawl::Models::CrawlOptions.new(limit: 50))+ class Client+ DEFAULT_API_URL = "https://api.firecrawl.dev"+ DEFAULT_TIMEOUT = 300 # seconds+ DEFAULT_MAX_RETRIES = 3+ DEFAULT_BACKOFF_FACTOR = 0.5+ DEFAULT_POLL_INTERVAL = 2 # seconds+ DEFAULT_JOB_TIMEOUT = 300 # seconds++ # Creates a new Firecrawl client.+ #+ # @param api_key [String, nil] API key (falls back to FIRECRAWL_API_KEY env var)+ # @param api_url [String] API base URL+ # @param timeout [Integer] HTTP request timeout in seconds+ # @param max_retries [Integer] maximum automatic retries for transient failures+ # @param backoff_factor [Float] exponential backoff factor in seconds+ def initialize(+ api_key: nil,+ api_url: nil,+ timeout: DEFAULT_TIMEOUT,+ max_retries: DEFAULT_MAX_RETRIES,+ backoff_factor: DEFAULT_BACKOFF_FACTOR+ )+ resolved_key = api_key || ENV["FIRECRAWL_API_KEY"]+ if resolved_key.nil? || resolved_key.empty?+ raise FirecrawlError, "API key is required. Provide api_key: or set FIRECRAWL_API_KEY environment variable."+ end++ resolved_url = api_url || ENV["FIRECRAWL_API_URL"] || DEFAULT_API_URL++ @http = HttpClient.new(+ api_key: resolved_key,+ base_url: resolved_url,+ timeout: timeout,+ max_retries: max_retries,+ backoff_factor: backoff_factor+ )+ end++ # Creates a client from the FIRECRAWL_API_KEY environment variable.+ #+ # @return [Client]+ def self.from_env+ new+ end++ # ================================================================+ # SCRAPE+ # ================================================================++ # Scrapes a single URL and returns the document.+ #+ # @param url [String] the URL to scrape+ # @param options [Models::ScrapeOptions, nil] scrape configuration+ # @return [Models::Document]+ def scrape(url, options = nil)+ raise ArgumentError, "URL is required" if url.nil?++ body = { "url" => url }+ body.merge!(options.to_h) if options+ raw = @http.post("/v2/scrape", body)+ data = raw["data"] || raw+ Models::Document.new(data)+ end++ # Interacts with the scrape-bound browser session for a scrape job.+ #+ # @param job_id [String] the scrape job ID+ # @param code [String] the code to execute+ # @param language [String] "python", "node", or "bash" (default: "node")+ # @param timeout [Integer, nil] execution timeout in seconds (1-300)+ # @return [Hash] execution result with stdout, stderr, exit_code+ def interact(job_id, code, language: "node", timeout: nil)+ raise ArgumentError, "Job ID is required" if job_id.nil?+ raise ArgumentError, "Code is required" if code.nil?++ body = { "code" => code, "language" => language }+ body["timeout"] = timeout if timeout+ @http.post("/v2/scrape/#{job_id}/interact", body)+ end++ # Stops the interactive browser session for a scrape job.+ #+ # @param job_id [String] the scrape job ID+ # @return [Hash] stop response+ def stop_interactive_browser(job_id)+ raise ArgumentError, "Job ID is required" if job_id.nil?++ @http.delete("/v2/scrape/#{job_id}/interact")+ end++ # ================================================================+ # CRAWL+ # ================================================================++ # Starts an async crawl job and returns immediately.+ #+ # @param url [String] the URL to start crawling from+ # @param options [Models::CrawlOptions, nil] crawl configuration+ # @return [Models::CrawlResponse]+ def start_crawl(url, options = nil)+ raise ArgumentError, "URL is required" if url.nil?++ body = { "url" => url }+ body.merge!(options.to_h) if options+ raw = @http.post("/v2/crawl", body)+ Models::CrawlResponse.new(raw)+ end++ # Gets the status and results of a crawl job.+ #+ # @param job_id [String] the crawl job ID+ # @return [Models::CrawlJob]+ def get_crawl_status(job_id)+ raise ArgumentError, "Job ID is required" if job_id.nil?++ raw = @http.get("/v2/crawl/#{job_id}")+ Models::CrawlJob.new(raw)+ end++ # Crawls a website and waits for completion (auto-polling).+ #+ # @param url [String] the URL to crawl+ # @param options [Models::CrawlOptions, nil] crawl configuration+ # @param poll_interval [Integer] seconds between status checks+ # @param timeout [Integer] maximum seconds to wait+ # @return [Models::CrawlJob]+ def crawl(url, options = nil, poll_interval: DEFAULT_POLL_INTERVAL, timeout: DEFAULT_JOB_TIMEOUT)+ start = start_crawl(url, options)+ poll_crawl(start.id, poll_interval, timeout)+ end++ # Cancels a running crawl job.+ #+ # @param job_id [String] the crawl job ID+ # @return [Hash]+ def cancel_crawl(job_id)+ raise ArgumentError, "Job ID is required" if job_id.nil?++ @http.delete("/v2/crawl/#{job_id}")+ end++ # Gets errors from a crawl job.+ #+ # @param job_id [String] the crawl job ID+ # @return [Hash]+ def get_crawl_errors(job_id)+ raise ArgumentError, "Job ID is required" if job_id.nil?++ @http.get("/v2/crawl/#{job_id}/errors")+ end++ # ================================================================+ # BATCH SCRAPE+ # ================================================================++ # Starts an async batch scrape job.+ #+ # @param urls [Array<String>] the URLs to scrape+ # @param options [Models::BatchScrapeOptions, nil] batch scrape configuration+ # @return [Models::BatchScrapeResponse]+ def start_batch_scrape(urls, options = nil)+ raise ArgumentError, "URLs list is required" if urls.nil?++ body = { "urls" => urls }+ extra_headers = {}+ if options+ opts_hash = options.to_h++ # idempotencyKey goes as a header, not in body+ if options.idempotency_key && !options.idempotency_key.empty?+ extra_headers["x-idempotency-key"] = options.idempotency_key+ end++ # Flatten nested scrape options to top level (API expects this)+ nested = opts_hash.delete("options")+ body.merge!(opts_hash)+ body.merge!(nested) if nested+ end+ raw = @http.post("/v2/batch/scrape", body, extra_headers: extra_headers)+ Models::BatchScrapeResponse.new(raw)+ end++ # Gets the status and results of a batch scrape job.+ #+ # @param job_id [String] the batch scrape job ID+ # @return [Models::BatchScrapeJob]+ def get_batch_scrape_status(job_id)+ raise ArgumentError, "Job ID is required" if job_id.nil?++ raw = @http.get("/v2/batch/scrape/#{job_id}")+ Models::BatchScrapeJob.new(raw)+ end++ # Batch-scrapes URLs and waits for completion (auto-polling).+ #+ # @param urls [Array<String>] the URLs to scrape+ # @param options [Models::BatchScrapeOptions, nil] batch scrape configuration+ # @param poll_interval [Integer] seconds between status checks+ # @param timeout [Integer] maximum seconds to wait+ # @return [Models::BatchScrapeJob]+ def batch_scrape(urls, options = nil, poll_interval: DEFAULT_POLL_INTERVAL, timeout: DEFAULT_JOB_TIMEOUT)+ start = start_batch_scrape(urls, options)+ poll_batch_scrape(start.id, poll_interval, timeout)+ end++ # Cancels a running batch scrape job.+ #+ # @param job_id [String] the batch scrape job ID+ # @return [Hash]+ def cancel_batch_scrape(job_id)+ raise ArgumentError, "Job ID is required" if job_id.nil?++ @http.delete("/v2/batch/scrape/#{job_id}")+ end++ # ================================================================+ # MAP+ # ================================================================++ # Discovers URLs on a website.+ #+ # @param url [String] the URL to map+ # @param options [Models::MapOptions, nil] map configuration+ # @return [Models::MapData]+ def map(url, options = nil)+ raise ArgumentError, "URL is required" if url.nil?++ body = { "url" => url }+ body.merge!(options.to_h) if options+ raw = @http.post("/v2/map", body)+ data = raw["data"] || raw+ Models::MapData.new(data)+ end++ # ================================================================+ # SEARCH+ # ================================================================++ # Performs a web search.+ #+ # @param query [String] the search query+ # @param options [Models::SearchOptions, nil] search configuration+ # @return [Models::SearchData]+ def search(query, options = nil)+ raise ArgumentError, "Query is required" if query.nil?++ body = { "query" => query }+ body.merge!(options.to_h) if options+ raw = @http.post("/v2/search", body)+ data = raw["data"] || raw+ Models::SearchData.new(data)+ end++ # ================================================================+ # AGENT+ # ================================================================++ # Starts an async agent task.+ #+ # @param options [Models::AgentOptions] agent configuration+ # @return [Models::AgentResponse]+ def start_agent(options)+ raise ArgumentError, "Agent options are required" if options.nil?++ raw = @http.post("/v2/agent", options.to_h)+ Models::AgentResponse.new(raw)+ end++ # Gets the status of an agent task.+ #+ # @param job_id [String] the agent job ID+ # @return [Models::AgentStatusResponse]+ def get_agent_status(job_id)+ raise ArgumentError, "Job ID is required" if job_id.nil?++ raw = @http.get("/v2/agent/#{job_id}")+ Models::AgentStatusResponse.new(raw)+ end++ # Runs an agent task and waits for completion (auto-polling).+ #+ # @param options [Models::AgentOptions] agent configuration+ # @param poll_interval [Integer] seconds between status checks+ # @param timeout [Integer] maximum seconds to wait+ # @return [Models::AgentStatusResponse]+ def agent(options, poll_interval: DEFAULT_POLL_INTERVAL, timeout: DEFAULT_JOB_TIMEOUT)+ start = start_agent(options)+ raise FirecrawlError, "Agent start did not return a job ID" if start.id.nil?++ deadline = Time.now + timeout+ while Time.now < deadline+ status = get_agent_status(start.id)+ return status if status.done?++ sleep(poll_interval)+ end+ raise JobTimeoutError.new(start.id, timeout, "Agent")+ end++ # Cancels a running agent task.+ #+ # @param job_id [String] the agent job ID+ # @return [Hash]+ def cancel_agent(job_id)+ raise ArgumentError, "Job ID is required" if job_id.nil?++ @http.delete("/v2/agent/#{job_id}")+ end++ # ================================================================+ # USAGE & METRICS+ # ================================================================++ # Gets current concurrency usage.+ #+ # @return [Models::ConcurrencyCheck]+ def get_concurrency+ raw = @http.get("/v2/concurrency-check")+ Models::ConcurrencyCheck.new(raw)+ end++ # Gets current credit usage.+ #+ # @return [Models::CreditUsage]+ def get_credit_usage+ raw = @http.get("/v2/team/credit-usage")+ Models::CreditUsage.new(raw)+ end++ private++ def poll_crawl(job_id, poll_interval, timeout)+ deadline = Time.now + timeout+ while Time.now < deadline+ job = get_crawl_status(job_id)+ return paginate_crawl(job) if job.done?++ sleep(poll_interval)+ end+ raise JobTimeoutError.new(job_id, timeout, "Crawl")+ end++ def poll_batch_scrape(job_id, poll_interval, timeout)+ deadline = Time.now + timeout+ while Time.now < deadline+ job = get_batch_scrape_status(job_id)+ return paginate_batch_scrape(job) if job.done?++ sleep(poll_interval)+ end+ raise JobTimeoutError.new(job_id, timeout, "Batch scrape")+ end++ def paginate_crawl(job)+ job.data ||= []+ current = job+ while current.next_url && !current.next_url.empty?+ raw = @http.get_absolute(current.next_url)+ next_page = Models::CrawlJob.new(raw)+ job.data.concat(next_page.data) unless next_page.data.empty?+ current = next_page+ end+ job+ end++ def paginate_batch_scrape(job)+ job.data ||= []+ current = job+ while current.next_url && !current.next_url.empty?+ raw = @http.get_absolute(current.next_url)+ next_page = Models::BatchScrapeJob.new(raw)+ job.data.concat(next_page.data) unless next_page.data.empty?+ current = next_page+ end+ job+ end+ end+enddiff --git a/apps/ruby-sdk/lib/firecrawl/errors.rb b/apps/ruby-sdk/lib/firecrawl/errors.rbnew file mode 100644index 000000000..645620d6c--- /dev/null+++ b/apps/ruby-sdk/lib/firecrawl/errors.rb@@ -0,0 +1,40 @@+# frozen_string_literal: true++module Firecrawl+ # Base error class for all Firecrawl SDK errors.+ class FirecrawlError < StandardError+ attr_reader :status_code, :error_code, :details++ def initialize(message = nil, status_code: nil, error_code: nil, details: nil)+ @status_code = status_code+ @error_code = error_code+ @details = details+ super(message)+ end+ end++ # Raised on 401 Unauthorized responses.+ class AuthenticationError < FirecrawlError+ def initialize(message = nil, error_code: nil, details: nil)+ super(message, status_code: 401, error_code: error_code, details: details)+ end+ end++ # Raised on 429 Too Many Requests responses.+ class RateLimitError < FirecrawlError+ def initialize(message = nil, error_code: nil, details: nil)+ super(message, status_code: 429, error_code: error_code, details: details)+ end+ end++ # Raised when an async job exceeds its timeout.+ class JobTimeoutError < FirecrawlError+ attr_reader :job_id, :timeout_seconds++ def initialize(job_id, timeout_seconds, label = "Job")+ @job_id = job_id+ @timeout_seconds = timeout_seconds+ super("#{label} #{job_id} timed out after #{timeout_seconds} seconds")+ end+ end+enddiff --git a/apps/ruby-sdk/lib/firecrawl/http_client.rb b/apps/ruby-sdk/lib/firecrawl/http_client.rbnew file mode 100644index 000000000..910d671bd--- /dev/null+++ b/apps/ruby-sdk/lib/firecrawl/http_client.rb@@ -0,0 +1,131 @@+# frozen_string_literal: true++require "net/http"+require "json"+require "uri"++module Firecrawl+ # Internal HTTP client for making authenticated requests to the Firecrawl API.+ # Handles retry logic with exponential backoff.+ #+ # @api private+ class HttpClient+ def initialize(api_key:, base_url:, timeout:, max_retries:, backoff_factor:)+ @api_key = api_key+ @base_url = base_url.chomp("/")+ @timeout = timeout+ @max_retries = max_retries+ @backoff_factor = backoff_factor+ end++ # Sends a POST request with JSON body.+ def post(path, body, extra_headers: {})+ uri = URI("#{@base_url}#{path}")+ request = Net::HTTP::Post.new(uri)+ request["Authorization"] = "Bearer #{@api_key}"+ request["Content-Type"] = "application/json"+ extra_headers.each { |k, v| request[k] = v }+ request.body = JSON.generate(body)+ execute_with_retry(uri, request)+ end++ # Sends a GET request.+ def get(path)+ uri = URI("#{@base_url}#{path}")+ request = Net::HTTP::Get.new(uri)+ request["Authorization"] = "Bearer #{@api_key}"+ execute_with_retry(uri, request)+ end++ # Sends a GET request with a full URL (for following next-page cursors).+ def get_absolute(absolute_url)+ uri = URI(absolute_url)+ request = Net::HTTP::Get.new(uri)+ request["Authorization"] = "Bearer #{@api_key}"+ execute_with_retry(uri, request)+ end++ # Sends a DELETE request.+ def delete(path)+ uri = URI("#{@base_url}#{path}")+ request = Net::HTTP::Delete.new(uri)+ request["Authorization"] = "Bearer #{@api_key}"+ execute_with_retry(uri, request)+ end++ private++ def execute_with_retry(uri, request)+ attempt = 0+ loop do+ response = perform_request(uri, request)+ code = response.code.to_i+ body_str = response.body || ""++ if code >= 200 && code < 300+ return body_str.empty? ? {} : JSON.parse(body_str)+ end++ error_message = extract_error_message(body_str, code)+ error_code = extract_error_code(body_str)++ # Non-retryable client errors+ if code == 401+ raise AuthenticationError.new(error_message, error_code: error_code)+ end+ if code == 429+ raise RateLimitError.new(error_message, error_code: error_code)+ end+ if code >= 400 && code < 500 && code != 408 && code != 409+ raise FirecrawlError.new(error_message, status_code: code, error_code: error_code)+ end++ # Retryable errors: 408, 409, 502, 5xx+ if attempt < @max_retries+ attempt += 1+ sleep_with_backoff(attempt)+ next+ end++ raise FirecrawlError.new(error_message, status_code: code, error_code: error_code)+ rescue Errno::ECONNREFUSED, Errno::ECONNRESET, Errno::ETIMEDOUT,+ Net::OpenTimeout, Net::ReadTimeout, IOError => e+ if attempt < @max_retries+ attempt += 1+ sleep_with_backoff(attempt)+ retry+ end+ raise FirecrawlError.new("Request failed: #{e.message}")+ end+ end++ def perform_request(uri, request)+ http = Net::HTTP.new(uri.host, uri.port)+ http.use_ssl = (uri.scheme == "https")+ http.open_timeout = @timeout+ http.read_timeout = @timeout+ http.write_timeout = @timeout+ http.request(request)+ end++ def extract_error_message(body, status_code)+ parsed = JSON.parse(body)+ parsed["error"] || parsed["message"] || "HTTP #{status_code} error"+ rescue JSON::ParserError+ "HTTP #{status_code} error"+ end++ def extract_error_code(body)+ parsed = JSON.parse(body)+ code = parsed["code"]+ code&.to_s+ rescue JSON::ParserError+ nil+ end++ def sleep_with_backoff(attempt)+ delay = @backoff_factor * (2**(attempt - 1))+ sleep(delay)+ end+ end+enddiff --git a/apps/ruby-sdk/lib/firecrawl/models/agent_options.rb b/apps/ruby-sdk/lib/firecrawl/models/agent_options.rbnew file mode 100644index 000000000..17daba219--- /dev/null+++ b/apps/ruby-sdk/lib/firecrawl/models/agent_options.rb@@ -0,0 +1,33 @@+# frozen_string_literal: true++module Firecrawl+ module Models+ # Options for starting an agent task.+ class AgentOptions+ FIELDS = %i[+ urls prompt schema integration max_credits+ strict_constrain_to_urls model webhook+ ].freeze++ attr_reader(*FIELDS)++ def initialize(**kwargs)+ FIELDS.each { |f| instance_variable_set(:"@#{f}", kwargs[f]) }+ raise ArgumentError, "Agent prompt is required" if prompt.nil? || prompt.empty?+ end++ def to_h+ {+ "urls" => urls,+ "prompt" => prompt,+ "schema" => schema,+ "integration" => integration,+ "maxCredits" => max_credits,+ "strictConstrainToURLs" => strict_constrain_to_urls,+ "model" => model,+ "webhook" => webhook.is_a?(Hash) ? webhook : webhook&.to_h,+ }.compact+ end+ end+ end+enddiff --git a/apps/ruby-sdk/lib/firecrawl/models/agent_response.rb b/apps/ruby-sdk/lib/firecrawl/models/agent_response.rbnew file mode 100644index 000000000..a65d09b96--- /dev/null+++ b/apps/ruby-sdk/lib/firecrawl/models/agent_response.rb@@ -0,0 +1,20 @@+# frozen_string_literal: true++module Firecrawl+ module Models+ # Response from starting an agent task.+ class AgentResponse+ attr_reader :success, :id, :error++ def initialize(data)+ @success = data["success"]+ @id = data["id"]+ @error = data["error"]+ end++ def to_s+ "AgentResponse{id=#{id}, success=#{success}}"+ end+ end+ end+enddiff --git a/apps/ruby-sdk/lib/firecrawl/models/agent_status_response.rb b/apps/ruby-sdk/lib/firecrawl/models/agent_status_response.rbnew file mode 100644index 000000000..a29cc57e7--- /dev/null+++ b/apps/ruby-sdk/lib/firecrawl/models/agent_status_response.rb@@ -0,0 +1,25 @@+# frozen_string_literal: true++module Firecrawl+ module Models+ # Status response for monitoring agent tasks.+ class AgentStatusResponse+ attr_reader :status, :data, :credits_used, :expires_at++ def initialize(raw)+ @status = raw["status"]+ @data = raw["data"]+ @credits_used = raw["creditsUsed"]+ @expires_at = raw["expiresAt"]+ end++ def done?+ %w[completed failed cancelled].include?(status)+ end++ def to_s+ "AgentStatusResponse{status=#{status}}"+ end+ end+ end+enddiff --git a/apps/ruby-sdk/lib/firecrawl/models/batch_scrape_job.rb b/apps/ruby-sdk/lib/firecrawl/models/batch_scrape_job.rbnew file mode 100644index 000000000..8984b7dc1--- /dev/null+++ b/apps/ruby-sdk/lib/firecrawl/models/batch_scrape_job.rb@@ -0,0 +1,31 @@+# frozen_string_literal: true++module Firecrawl+ module Models+ # Status and results of a batch scrape job.+ class BatchScrapeJob+ attr_reader :id, :status, :total, :completed, :credits_used,+ :expires_at, :next_url+ attr_accessor :data++ def initialize(raw)+ @id = raw["id"]+ @status = raw["status"]+ @total = raw["total"].to_i+ @completed = raw["completed"].to_i+ @credits_used = raw["creditsUsed"]+ @expires_at = raw["expiresAt"]+ @next_url = raw["next"]+ @data = (raw["data"] || []).map { |d| Document.new(d) }+ end++ def done?+ %w[completed failed cancelled].include?(status)+ end++ def to_s+ "BatchScrapeJob{id=#{id}, status=#{status}, completed=#{completed}/#{total}}"+ end+ end+ end+enddiff --git a/apps/ruby-sdk/lib/firecrawl/models/batch_scrape_options.rb b/apps/ruby-sdk/lib/firecrawl/models/batch_scrape_options.rbnew file mode 100644index 000000000..89853e260--- /dev/null+++ b/apps/ruby-sdk/lib/firecrawl/models/batch_scrape_options.rb@@ -0,0 +1,31 @@+# frozen_string_literal: true++module Firecrawl+ module Models+ # Options for a batch scrape job.+ class BatchScrapeOptions+ FIELDS = %i[+ options webhook append_to_id ignore_invalid_urls+ max_concurrency zero_data_retention idempotency_key integration+ ].freeze++ attr_reader(*FIELDS)++ def initialize(**kwargs)+ FIELDS.each { |f| instance_variable_set(:"@#{f}", kwargs[f]) }+ end++ def to_h+ {+ "options" => options&.to_h,+ "webhook" => webhook.is_a?(String) ? webhook : webhook&.to_h,+ "appendToId" => append_to_id,+ "ignoreInvalidURLs" => ignore_invalid_urls,+ "maxConcurrency" => max_concurrency,+ "zeroDataRetention" => zero_data_retention,+ "integration" => integration,+ }.compact+ end+ end+ end+enddiff --git a/apps/ruby-sdk/lib/firecrawl/models/batch_scrape_response.rb b/apps/ruby-sdk/lib/firecrawl/models/batch_scrape_response.rbnew file mode 100644index 000000000..28868d22f--- /dev/null+++ b/apps/ruby-sdk/lib/firecrawl/models/batch_scrape_response.rb@@ -0,0 +1,20 @@+# frozen_string_literal: true++module Firecrawl+ module Models+ # Response from starting an async batch scrape job.+ class BatchScrapeResponse+ attr_reader :id, :url, :invalid_urls++ def initialize(data)+ @id = data["id"]+ @url = data["url"]+ @invalid_urls = data["invalidURLs"]+ end++ def to_s+ "BatchScrapeResponse{id=#{id}, url=#{url}}"+ end+ end+ end+enddiff --git a/apps/ruby-sdk/lib/firecrawl/models/concurrency_check.rb b/apps/ruby-sdk/lib/firecrawl/models/concurrency_check.rbnew file mode 100644index 000000000..2ec2fd20f--- /dev/null+++ b/apps/ruby-sdk/lib/firecrawl/models/concurrency_check.rb@@ -0,0 +1,19 @@+# frozen_string_literal: true++module Firecrawl+ module Models+ # Current concurrency usage.+ class ConcurrencyCheck+ attr_reader :concurrency, :max_concurrency++ def initialize(data)+ @concurrency = data["concurrency"]+ @max_concurrency = data["maxConcurrency"]+ end++ def to_s+ "ConcurrencyCheck{concurrency=#{concurrency}/#{max_concurrency}}"+ end+ end+ end+enddiff --git a/apps/ruby-sdk/lib/firecrawl/models/crawl_job.rb b/apps/ruby-sdk/lib/firecrawl/models/crawl_job.rbnew file mode 100644index 000000000..bf0962024--- /dev/null+++ b/apps/ruby-sdk/lib/firecrawl/models/crawl_job.rb@@ -0,0 +1,31 @@+# frozen_string_literal: true++module Firecrawl+ module Models+ # Status and results of a crawl job.+ class CrawlJob+ attr_reader :id, :status, :total, :completed, :credits_used,+ :expires_at, :next_url+ attr_accessor :data++ def initialize(raw)+ @id = raw["id"]+ @status = raw["status"]+ @total = raw["total"].to_i+ @completed = raw["completed"].to_i+ @credits_used = raw["creditsUsed"]+ @expires_at = raw["expiresAt"]+ @next_url = raw["next"]+ @data = (raw["data"] || []).map { |d| Document.new(d) }+ end++ def done?+ %w[completed failed cancelled].include?(status)+ end++ def to_s+ "CrawlJob{id=#{id}, status=#{status}, completed=#{completed}/#{total}}"+ end+ end+ end+enddiff --git a/apps/ruby-sdk/lib/firecrawl/models/crawl_options.rb b/apps/ruby-sdk/lib/firecrawl/models/crawl_options.rbnew file mode 100644index 000000000..95c210297--- /dev/null+++ b/apps/ruby-sdk/lib/firecrawl/models/crawl_options.rb@@ -0,0 +1,53 @@+# frozen_string_literal: true++module Firecrawl+ module Models+ # Options for crawling a website.+ class CrawlOptions+ FIELDS = %i[+ prompt exclude_paths include_paths max_discovery_depth sitemap+ ignore_query_parameters deduplicate_similar_urls limit+ crawl_entire_domain allow_external_links allow_subdomains+ delay max_concurrency webhook scrape_options regex_on_full_url+ zero_data_retention integration+ ].freeze++ attr_reader(*FIELDS)++ def initialize(**kwargs)+ FIELDS.each { |f| instance_variable_set(:"@#{f}", kwargs[f]) }+ end++ def to_h+ h = {+ "prompt" => prompt,+ "excludePaths" => exclude_paths,+ "includePaths" => include_paths,+ "maxDiscoveryDepth" => max_discovery_depth,+ "sitemap" => sitemap,+ "ignoreQueryParameters" => ignore_query_parameters,+ "deduplicateSimilarURLs" => deduplicate_similar_urls,+ "limit" => limit,+ "crawlEntireDomain" => crawl_entire_domain,+ "allowExternalLinks" => allow_external_links,+ "allowSubdomains" => allow_subdomains,+ "delay" => delay,+ "maxConcurrency" => max_concurrency,+ "webhook" => serialize_webhook,+ "scrapeOptions" => scrape_options&.to_h,+ "regexOnFullURL" => regex_on_full_url,+ "zeroDataRetention" => zero_data_retention,+ "integration" => integration,+ }.compact+ h+ end++ private++ def serialize_webhook+ return webhook if webhook.is_a?(String) || webhook.is_a?(Hash)+ webhook&.to_h+ end+ end+ end+enddiff --git a/apps/ruby-sdk/lib/firecrawl/models/crawl_response.rb b/apps/ruby-sdk/lib/firecrawl/models/crawl_response.rbnew file mode 100644index 000000000..2f5c7608b--- /dev/null+++ b/apps/ruby-sdk/lib/firecrawl/models/crawl_response.rb@@ -0,0 +1,19 @@+# frozen_string_literal: true++module Firecrawl+ module Models+ # Response from starting an async crawl job.+ class CrawlResponse+ attr_reader :id, :url++ def initialize(data)+ @id = data["id"]+ @url = data["url"]+ end++ def to_s+ "CrawlResponse{id=#{id}, url=#{url}}"+ end+ end+ end+enddiff --git a/apps/ruby-sdk/lib/firecrawl/models/credit_usage.rb b/apps/ruby-sdk/lib/firecrawl/models/credit_usage.rbnew file mode 100644index 000000000..a844d6edb--- /dev/null+++ b/apps/ruby-sdk/lib/firecrawl/models/credit_usage.rb@@ -0,0 +1,22 @@+# frozen_string_literal: true++module Firecrawl+ module Models+ # Credit usage information.+ class CreditUsage+ attr_reader :remaining_credits, :plan_credits,+ :billing_period_start, :billing_period_end++ def initialize(data)+ @remaining_credits = data["remainingCredits"]+ @plan_credits = data["planCredits"]+ @billing_period_start = data["billingPeriodStart"]+ @billing_period_end = data["billingPeriodEnd"]+ end++ def to_s+ "CreditUsage{remaining=#{remaining_credits}/#{plan_credits}}"+ end+ end+ end+enddiff --git a/apps/ruby-sdk/lib/firecrawl/models/document.rb b/apps/ruby-sdk/lib/firecrawl/models/document.rbnew file mode 100644index 000000000..931911af3--- /dev/null+++ b/apps/ruby-sdk/lib/firecrawl/models/document.rb@@ -0,0 +1,36 @@+# frozen_string_literal: true++module Firecrawl+ module Models+ # A scraped document returned by scrape, crawl, and batch endpoints.+ class Document+ attr_reader :markdown, :html, :raw_html, :json, :summary,+ :metadata, :links, :images, :screenshot, :audio,+ :attributes, :actions, :warning, :change_tracking, :branding++ def initialize(data)+ @markdown = data["markdown"]+ @html = data["html"]+ @raw_html = data["rawHtml"]+ @json = data["json"]+ @summary = data["summary"]+ @metadata = data["metadata"]+ @links = data["links"]+ @images = data["images"]+ @screenshot = data["screenshot"]+ @audio = data["audio"]+ @attributes = data["attributes"]+ @actions = data["actions"]+ @warning = data["warning"]+ @change_tracking = data["changeTracking"]+ @branding = data["branding"]+ end++ def to_s+ title = metadata&.dig("title") || "untitled"+ url = metadata&.dig("sourceURL") || "unknown"+ "Document{title=#{title}, url=#{url}}"+ end+ end+ end+enddiff --git a/apps/ruby-sdk/lib/firecrawl/models/map_data.rb b/apps/ruby-sdk/lib/firecrawl/models/map_data.rbnew file mode 100644index 000000000..997d863d6--- /dev/null+++ b/apps/ruby-sdk/lib/firecrawl/models/map_data.rb@@ -0,0 +1,27 @@+# frozen_string_literal: true++module Firecrawl+ module Models+ # Result of a map operation containing discovered URLs.+ # The v2 API may return links as either plain URL strings or objects+ # with url, title, and description fields. This class normalises both.+ class MapData+ attr_reader :links++ def initialize(data)+ raw_links = data["links"] || []+ @links = raw_links.map do |item|+ if item.is_a?(Hash)+ item+ elsif item.is_a?(String)+ { "url" => item }+ end+ end.compact+ end++ def to_s+ "MapData{links=#{links.size}}"+ end+ end+ end+enddiff --git a/apps/ruby-sdk/lib/firecrawl/models/map_options.rb b/apps/ruby-sdk/lib/firecrawl/models/map_options.rbnew file mode 100644index 000000000..47c176ad7--- /dev/null+++ b/apps/ruby-sdk/lib/firecrawl/models/map_options.rb@@ -0,0 +1,32 @@+# frozen_string_literal: true++module Firecrawl+ module Models+ # Options for mapping (discovering URLs on) a website.+ class MapOptions+ FIELDS = %i[+ search sitemap include_subdomains ignore_query_parameters+ limit timeout integration location+ ].freeze++ attr_reader(*FIELDS)++ def initialize(**kwargs)+ FIELDS.each { |f| instance_variable_set(:"@#{f}", kwargs[f]) }+ end++ def to_h+ {+ "search" => search,+ "sitemap" => sitemap,+ "includeSubdomains" => include_subdomains,+ "ignoreQueryParameters" => ignore_query_parameters,+ "limit" => limit,+ "timeout" => timeout,+ "integration" => integration,+ "location" => location.is_a?(Hash) ? location : location&.to_h,+ }.compact+ end+ end+ end+enddiff --git a/apps/ruby-sdk/lib/firecrawl/models/scrape_options.rb b/apps/ruby-sdk/lib/firecrawl/models/scrape_options.rbnew file mode 100644index 000000000..c5bdf54f7--- /dev/null+++ b/apps/ruby-sdk/lib/firecrawl/models/scrape_options.rb@@ -0,0 +1,44 @@+# frozen_string_literal: true++module Firecrawl+ module Models+ # Options for scraping a single URL.+ class ScrapeOptions+ FIELDS = %i[+ formats headers include_tags exclude_tags only_main_content+ timeout wait_for mobile parsers actions location+ skip_tls_verification remove_base64_images block_ads proxy+ max_age store_in_cache integration+ ].freeze++ attr_reader(*FIELDS)++ def initialize(**kwargs)+ FIELDS.each { |f| instance_variable_set(:"@#{f}", kwargs[f]) }+ end++ def to_h+ {+ "formats" => formats,+ "headers" => headers,+ "includeTags" => include_tags,+ "excludeTags" => exclude_tags,+ "onlyMainContent" => only_main_content,+ "timeout" => timeout,+ "waitFor" => wait_for,+ "mobile" => mobile,+ "parsers" => parsers,+ "actions" => actions,+ "location" => location.is_a?(Hash) ? location : location&.to_h,+ "skipTlsVerification" => skip_tls_verification,+ "removeBase64Images" => remove_base64_images,+ "blockAds" => block_ads,+ "proxy" => proxy,+ "maxAge" => max_age,+ "storeInCache" => store_in_cache,+ "integration" => integration,+ }.compact+ end+ end+ end+enddiff --git a/apps/ruby-sdk/lib/firecrawl/models/search_data.rb b/apps/ruby-sdk/lib/firecrawl/models/search_data.rbnew file mode 100644index 000000000..00b5f776f--- /dev/null+++ b/apps/ruby-sdk/lib/firecrawl/models/search_data.rb@@ -0,0 +1,23 @@+# frozen_string_literal: true++module Firecrawl+ module Models+ # Search results from the v2 search API.+ class SearchData+ attr_reader :web, :news, :images++ def initialize(data)+ @web = data["web"]+ @news = data["news"]+ @images = data["images"]+ end++ def to_s+ web_count = web&.size || 0+ news_count = news&.size || 0+ image_count = images&.size || 0+ "SearchData{web=#{web_count}, news=#{news_count}, images=#{image_count}}"+ end+ end+ end+enddiff --git a/apps/ruby-sdk/lib/firecrawl/models/search_options.rb b/apps/ruby-sdk/lib/firecrawl/models/search_options.rbnew file mode 100644index 000000000..b3d2d5f39--- /dev/null+++ b/apps/ruby-sdk/lib/firecrawl/models/search_options.rb@@ -0,0 +1,33 @@+# frozen_string_literal: true++module Firecrawl+ module Models+ # Options for a web search request.+ class SearchOptions+ FIELDS = %i[+ sources categories limit tbs location ignore_invalid_urls+ timeout scrape_options integration+ ].freeze++ attr_reader(*FIELDS)++ def initialize(**kwargs)+ FIELDS.each { |f| instance_variable_set(:"@#{f}", kwargs[f]) }+ end++ def to_h+ {+ "sources" => sources,+ "categories" => categories,+ "limit" => limit,+ "tbs" => tbs,+ "location" => location,+ "ignoreInvalidURLs" => ignore_invalid_urls,+ "timeout" => timeout,+ "scrapeOptions" => scrape_options&.to_h,+ "integration" => integration,+ }.compact+ end+ end+ end+enddiff --git a/apps/ruby-sdk/lib/firecrawl/version.rb b/apps/ruby-sdk/lib/firecrawl/version.rbnew file mode 100644index 000000000..57a0f0f91--- /dev/null+++ b/apps/ruby-sdk/lib/firecrawl/version.rb@@ -0,0 +1,5 @@+# frozen_string_literal: true++module Firecrawl+ VERSION = "1.0.0"+enddiff --git a/apps/ruby-sdk/test/firecrawl/client_test.rb b/apps/ruby-sdk/test/firecrawl/client_test.rbnew file mode 100644index 000000000..b9d33b514--- /dev/null+++ b/apps/ruby-sdk/test/firecrawl/client_test.rb@@ -0,0 +1,568 @@+# frozen_string_literal: true++require_relative "../test_helper"++class ClientTest < Minitest::Test+ API_KEY = "fc-test-key"+ BASE_URL = "https://api.firecrawl.dev"++ def setup+ WebMock.reset!+ @client = Firecrawl::Client.new(api_key: API_KEY)+ end++ # ================================================================+ # CLIENT INITIALIZATION+ # ================================================================++ def test_raises_when_no_api_key+ ENV.delete("FIRECRAWL_API_KEY")+ assert_raises(Firecrawl::FirecrawlError) { Firecrawl::Client.new }+ end++ def test_from_env_with_env_var+ ENV["FIRECRAWL_API_KEY"] = "fc-env-key"+ client = Firecrawl::Client.from_env+ assert_instance_of Firecrawl::Client, client+ ensure+ ENV.delete("FIRECRAWL_API_KEY")+ end++ def test_custom_api_url+ stub_request(:post, "https://custom.api.dev/v2/scrape")+ .to_return(status: 200, body: '{"data":{"markdown":"# Hi"}}', headers: { "Content-Type" => "application/json" })++ client = Firecrawl::Client.new(api_key: API_KEY, api_url: "https://custom.api.dev")+ doc = client.scrape("https://example.com")+ assert_equal "# Hi", doc.markdown+ end++ def test_custom_api_url_from_env+ ENV["FIRECRAWL_API_URL"] = "https://env-custom.api.dev"+ stub_request(:post, "https://env-custom.api.dev/v2/scrape")+ .to_return(status: 200, body: '{"data":{"markdown":"# Env"}}', headers: { "Content-Type" => "application/json" })++ client = Firecrawl::Client.new(api_key: API_KEY)+ doc = client.scrape("https://example.com")+ assert_equal "# Env", doc.markdown+ ensure+ ENV.delete("FIRECRAWL_API_URL")+ end++ # ================================================================+ # SCRAPE+ # ================================================================++ def test_scrape_basic+ stub_request(:post, "#{BASE_URL}/v2/scrape")+ .with(+ body: { url: "https://example.com" }.to_json,+ headers: { "Authorization" => "Bearer #{API_KEY}", "Content-Type" => "application/json" }+ )+ .to_return(+ status: 200,+ body: JSON.generate(data: { markdown: "# Hello", metadata: { title: "Example", sourceURL: "https://example.com" } }),+ headers: { "Content-Type" => "application/json" }+ )++ doc = @client.scrape("https://example.com")+ assert_instance_of Firecrawl::Models::Document, doc+ assert_equal "# Hello", doc.markdown+ assert_equal "Example", doc.metadata["title"]+ end++ def test_scrape_with_options+ stub_request(:post, "#{BASE_URL}/v2/scrape")+ .with { |req| body = JSON.parse(req.body); body["formats"] == ["markdown", "html"] && body["onlyMainContent"] == true }+ .to_return(+ status: 200,+ body: JSON.generate(data: { markdown: "# Test", html: "<h1>Test</h1>" }),+ headers: { "Content-Type" => "application/json" }+ )++ options = Firecrawl::Models::ScrapeOptions.new(formats: ["markdown", "html"], only_main_content: true)+ doc = @client.scrape("https://example.com", options)+ assert_equal "# Test", doc.markdown+ assert_equal "<h1>Test</h1>", doc.html+ end++ def test_scrape_raises_on_nil_url+ assert_raises(ArgumentError) { @client.scrape(nil) }+ end++ # ================================================================+ # CRAWL+ # ================================================================++ def test_start_crawl+ stub_request(:post, "#{BASE_URL}/v2/crawl")+ .to_return(+ status: 200,+ body: JSON.generate(id: "crawl-123", url: "https://api.firecrawl.dev/v2/crawl/crawl-123"),+ headers: { "Content-Type" => "application/json" }+ )++ response = @client.start_crawl("https://example.com")+ assert_instance_of Firecrawl::Models::CrawlResponse, response+ assert_equal "crawl-123", response.id+ end++ def test_get_crawl_status+ stub_request(:get, "#{BASE_URL}/v2/crawl/crawl-123")+ .to_return(+ status: 200,+ body: JSON.generate(id: "crawl-123", status: "completed", total: 5, completed: 5, data: []),+ headers: { "Content-Type" => "application/json" }+ )++ job = @client.get_crawl_status("crawl-123")+ assert_instance_of Firecrawl::Models::CrawlJob, job+ assert_equal "completed", job.status+ assert job.done?+ end++ def test_crawl_with_polling+ # First call: start crawl+ stub_request(:post, "#{BASE_URL}/v2/crawl")+ .to_return(+ status: 200,+ body: JSON.generate(id: "crawl-poll"),+ headers: { "Content-Type" => "application/json" }+ )++ # Second call: status is scraping (in progress)+ stub_request(:get, "#{BASE_URL}/v2/crawl/crawl-poll")+ .to_return(+ { status: 200, body: JSON.generate(id: "crawl-poll", status: "scraping", total: 2, completed: 1, data: []), headers: { "Content-Type" => "application/json" } },+ { status: 200, body: JSON.generate(id: "crawl-poll", status: "completed", total: 2, completed: 2, data: [{ markdown: "# Page" }]), headers: { "Content-Type" => "application/json" } }+ )++ job = @client.crawl("https://example.com", nil, poll_interval: 0, timeout: 10)+ assert_equal "completed", job.status+ assert_equal 1, job.data.size+ assert_equal "# Page", job.data.first.markdown+ end++ def test_crawl_with_options+ stub_request(:post, "#{BASE_URL}/v2/crawl")+ .with { |req| body = JSON.parse(req.body); body["limit"] == 10 && body["excludePaths"] == ["/private"] }+ .to_return(+ status: 200,+ body: JSON.generate(id: "crawl-opts"),+ headers: { "Content-Type" => "application/json" }+ )++ stub_request(:get, "#{BASE_URL}/v2/crawl/crawl-opts")+ .to_return(+ status: 200,+ body: JSON.generate(id: "crawl-opts", status: "completed", total: 1, completed: 1, data: []),+ headers: { "Content-Type" => "application/json" }+ )++ options = Firecrawl::Models::CrawlOptions.new(limit: 10, exclude_paths: ["/private"])+ job = @client.crawl("https://example.com", options, poll_interval: 0, timeout: 10)+ assert_equal "completed", job.status+ end++ def test_cancel_crawl+ stub_request(:delete, "#{BASE_URL}/v2/crawl/crawl-cancel")+ .to_return(+ status: 200,+ body: JSON.generate(status: "cancelled"),+ headers: { "Content-Type" => "application/json" }+ )++ result = @client.cancel_crawl("crawl-cancel")+ assert_equal "cancelled", result["status"]+ end++ # ================================================================+ # BATCH SCRAPE+ # ================================================================++ def test_start_batch_scrape+ stub_request(:post, "#{BASE_URL}/v2/batch/scrape")+ .to_return(+ status: 200,+ body: JSON.generate(id: "batch-123", url: "https://api.firecrawl.dev/v2/batch/scrape/batch-123"),+ headers: { "Content-Type" => "application/json" }+ )++ response = @client.start_batch_scrape(["https://a.com", "https://b.com"])+ assert_instance_of Firecrawl::Models::BatchScrapeResponse, response+ assert_equal "batch-123", response.id+ end++ def test_batch_scrape_with_idempotency_key+ stub_request(:post, "#{BASE_URL}/v2/batch/scrape")+ .with(headers: { "x-idempotency-key" => "my-key" })+ .to_return(+ status: 200,+ body: JSON.generate(id: "batch-idem"),+ headers: { "Content-Type" => "application/json" }+ )++ stub_request(:get, "#{BASE_URL}/v2/batch/scrape/batch-idem")+ .to_return(+ status: 200,+ body: JSON.generate(id: "batch-idem", status: "completed", total: 1, completed: 1, data: []),+ headers: { "Content-Type" => "application/json" }+ )++ options = Firecrawl::Models::BatchScrapeOptions.new(idempotency_key: "my-key")+ job = @client.batch_scrape(["https://a.com"], options, poll_interval: 0, timeout: 10)+ assert_equal "completed", job.status+ end++ # ================================================================+ # MAP+ # ================================================================++ def test_map_basic+ stub_request(:post, "#{BASE_URL}/v2/map")+ .to_return(+ status: 200,+ body: JSON.generate(data: { links: ["https://example.com/a", "https://example.com/b"] }),+ headers: { "Content-Type" => "application/json" }+ )++ result = @client.map("https://example.com")+ assert_instance_of Firecrawl::Models::MapData, result+ assert_equal 2, result.links.size+ assert_equal "https://example.com/a", result.links.first["url"]+ end++ def test_map_with_object_links+ stub_request(:post, "#{BASE_URL}/v2/map")+ .to_return(+ status: 200,+ body: JSON.generate(data: { links: [{ url: "https://example.com/a", title: "Page A" }] }),+ headers: { "Content-Type" => "application/json" }+ )++ result = @client.map("https://example.com")+ assert_equal "https://example.com/a", result.links.first["url"]+ assert_equal "Page A", result.links.first["title"]+ end++ def test_map_with_options+ stub_request(:post, "#{BASE_URL}/v2/map")+ .with { |req| body = JSON.parse(req.body); body["limit"] == 50 && body["search"] == "blog" }+ .to_return(+ status: 200,+ body: JSON.generate(data: { links: [] }),+ headers: { "Content-Type" => "application/json" }+ )++ options = Firecrawl::Models::MapOptions.new(limit: 50, search: "blog")+ result = @client.map("https://example.com", options)+ assert_equal 0, result.links.size+ end++ # ================================================================+ # SEARCH+ # ================================================================++ def test_search_basic+ stub_request(:post, "#{BASE_URL}/v2/search")+ .to_return(+ status: 200,+ body: JSON.generate(data: { web: [{ url: "https://example.com", title: "Example" }] }),+ headers: { "Content-Type" => "application/json" }+ )++ result = @client.search("test query")+ assert_instance_of Firecrawl::Models::SearchData, result+ assert_equal 1, result.web.size+ assert_equal "https://example.com", result.web.first["url"]+ end++ def test_search_with_options+ stub_request(:post, "#{BASE_URL}/v2/search")+ .with { |req| body = JSON.parse(req.body); body["limit"] == 5 && body["location"] == "US" }+ .to_return(+ status: 200,+ body: JSON.generate(data: { web: [], news: [], images: [] }),+ headers: { "Content-Type" => "application/json" }+ )++ options = Firecrawl::Models::SearchOptions.new(limit: 5, location: "US")+ result = @client.search("test query", options)+ assert_equal 0, result.web.size+ end++ # ================================================================+ # AGENT+ # ================================================================++ def test_start_agent+ stub_request(:post, "#{BASE_URL}/v2/agent")+ .to_return(+ status: 200,+ body: JSON.generate(success: true, id: "agent-123"),+ headers: { "Content-Type" => "application/json" }+ )++ options = Firecrawl::Models::AgentOptions.new(prompt: "Find pricing info")+ response = @client.start_agent(options)+ assert_instance_of Firecrawl::Models::AgentResponse, response+ assert_equal "agent-123", response.id+ assert_equal true, response.success+ end++ def test_agent_with_polling+ stub_request(:post, "#{BASE_URL}/v2/agent")+ .to_return(+ status: 200,+ body: JSON.generate(success: true, id: "agent-poll"),+ headers: { "Content-Type" => "application/json" }+ )++ stub_request(:get, "#{BASE_URL}/v2/agent/agent-poll")+ .to_return(+ { status: 200, body: JSON.generate(status: "processing"), headers: { "Content-Type" => "application/json" } },+ { status: 200, body: JSON.generate(status: "completed", data: { result: "found" }), headers: { "Content-Type" => "application/json" } }+ )++ options = Firecrawl::Models::AgentOptions.new(prompt: "Find pricing info")+ status = @client.agent(options, poll_interval: 0, timeout: 10)+ assert_equal "completed", status.status+ assert_equal({ "result" => "found" }, status.data)+ end++ def test_agent_options_require_prompt+ assert_raises(ArgumentError) { Firecrawl::Models::AgentOptions.new(prompt: "") }+ assert_raises(ArgumentError) { Firecrawl::Models::AgentOptions.new }+ end++ # ================================================================+ # USAGE & METRICS+ # ================================================================++ def test_get_concurrency+ stub_request(:get, "#{BASE_URL}/v2/concurrency-check")+ .to_return(+ status: 200,+ body: JSON.generate(concurrency: 3, maxConcurrency: 10),+ headers: { "Content-Type" => "application/json" }+ )++ result = @client.get_concurrency+ assert_instance_of Firecrawl::Models::ConcurrencyCheck, result+ assert_equal 3, result.concurrency+ assert_equal 10, result.max_concurrency+ end++ def test_get_credit_usage+ stub_request(:get, "#{BASE_URL}/v2/team/credit-usage")+ .to_return(+ status: 200,+ body: JSON.generate(remainingCredits: 500, planCredits: 1000),+ headers: { "Content-Type" => "application/json" }+ )++ result = @client.get_credit_usage+ assert_instance_of Firecrawl::Models::CreditUsage, result+ assert_equal 500, result.remaining_credits+ assert_equal 1000, result.plan_credits+ end++ # ================================================================+ # ERROR HANDLING+ # ================================================================++ def test_authentication_error+ stub_request(:post, "#{BASE_URL}/v2/scrape")+ .to_return(+ status: 401,+ body: JSON.generate(error: "Invalid API key"),+ headers: { "Content-Type" => "application/json" }+ )++ error = assert_raises(Firecrawl::AuthenticationError) { @client.scrape("https://example.com") }+ assert_equal 401, error.status_code+ assert_equal "Invalid API key", error.message+ end++ def test_rate_limit_error+ stub_request(:post, "#{BASE_URL}/v2/scrape")+ .to_return(+ status: 429,+ body: JSON.generate(error: "Rate limit exceeded"),+ headers: { "Content-Type" => "application/json" }+ )++ error = assert_raises(Firecrawl::RateLimitError) { @client.scrape("https://example.com") }+ assert_equal 429, error.status_code+ end++ def test_client_error+ stub_request(:post, "#{BASE_URL}/v2/scrape")+ .to_return(+ status: 400,+ body: JSON.generate(error: "Bad request"),+ headers: { "Content-Type" => "application/json" }+ )++ error = assert_raises(Firecrawl::FirecrawlError) { @client.scrape("https://example.com") }+ assert_equal 400, error.status_code+ assert_equal "Bad request", error.message+ end++ def test_retryable_server_error+ # Client is configured with max_retries=3, but let's use a client with 1 retry for speed+ client = Firecrawl::Client.new(api_key: API_KEY, max_retries: 1, backoff_factor: 0.0)++ stub_request(:post, "#{BASE_URL}/v2/scrape")+ .to_return(+ { status: 502, body: JSON.generate(error: "Bad gateway"), headers: { "Content-Type" => "application/json" } },+ { status: 200, body: JSON.generate(data: { markdown: "# Recovered" }), headers: { "Content-Type" => "application/json" } }+ )++ doc = client.scrape("https://example.com")+ assert_equal "# Recovered", doc.markdown+ end++ # ================================================================+ # OPTIONS SERIALIZATION+ # ================================================================++ def test_scrape_options_to_h+ opts = Firecrawl::Models::ScrapeOptions.new(+ formats: ["markdown", "html"],+ only_main_content: true,+ wait_for: 1000,+ mobile: false,+ proxy: "stealth"+ )+ h = opts.to_h+ assert_equal ["markdown", "html"], h["formats"]+ assert_equal true, h["onlyMainContent"]+ assert_equal 1000, h["waitFor"]+ assert_equal false, h["mobile"]+ assert_equal "stealth", h["proxy"]+ refute h.key?("timeout") # nil values should be omitted+ end++ def test_crawl_options_to_h+ opts = Firecrawl::Models::CrawlOptions.new(+ limit: 100,+ exclude_paths: ["/private"],+ max_discovery_depth: 3,+ allow_external_links: false+ )+ h = opts.to_h+ assert_equal 100, h["limit"]+ assert_equal ["/private"], h["excludePaths"]+ assert_equal 3, h["maxDiscoveryDepth"]+ assert_equal false, h["allowExternalLinks"]+ end++ def test_map_options_to_h+ opts = Firecrawl::Models::MapOptions.new(+ search: "blog",+ limit: 50,+ sitemap: "include"+ )+ h = opts.to_h+ assert_equal "blog", h["search"]+ assert_equal 50, h["limit"]+ assert_equal "include", h["sitemap"]+ end++ def test_search_options_to_h+ opts = Firecrawl::Models::SearchOptions.new(+ limit: 10,+ location: "US",+ tbs: "qdr:w"+ )+ h = opts.to_h+ assert_equal 10, h["limit"]+ assert_equal "US", h["location"]+ assert_equal "qdr:w", h["tbs"]+ end++ def test_agent_options_to_h+ opts = Firecrawl::Models::AgentOptions.new(+ prompt: "Find data",+ urls: ["https://example.com"],+ max_credits: 100,+ model: "spark-1-pro"+ )+ h = opts.to_h+ assert_equal "Find data", h["prompt"]+ assert_equal ["https://example.com"], h["urls"]+ assert_equal 100, h["maxCredits"]+ assert_equal "spark-1-pro", h["model"]+ end++ def test_batch_scrape_options_to_h+ scrape_opts = Firecrawl::Models::ScrapeOptions.new(formats: ["markdown"])+ opts = Firecrawl::Models::BatchScrapeOptions.new(+ options: scrape_opts,+ max_concurrency: 5,+ zero_data_retention: true+ )+ h = opts.to_h+ assert_equal({ "formats" => ["markdown"] }, h["options"])+ assert_equal 5, h["maxConcurrency"]+ assert_equal true, h["zeroDataRetention"]+ end++ # ================================================================+ # PAGINATION+ # ================================================================++ def test_crawl_auto_pagination+ stub_request(:post, "#{BASE_URL}/v2/crawl")+ .to_return(+ status: 200,+ body: JSON.generate(id: "crawl-pag"),+ headers: { "Content-Type" => "application/json" }+ )++ stub_request(:get, "#{BASE_URL}/v2/crawl/crawl-pag")+ .to_return(+ status: 200,+ body: JSON.generate(+ id: "crawl-pag", status: "completed", total: 2, completed: 2,+ data: [{ markdown: "# Page 1" }],+ next: "https://api.firecrawl.dev/v2/crawl/crawl-pag?skip=1"+ ),+ headers: { "Content-Type" => "application/json" }+ )++ stub_request(:get, "https://api.firecrawl.dev/v2/crawl/crawl-pag?skip=1")+ .to_return(+ status: 200,+ body: JSON.generate(+ id: "crawl-pag", status: "completed", total: 2, completed: 2,+ data: [{ markdown: "# Page 2" }]+ ),+ headers: { "Content-Type" => "application/json" }+ )++ job = @client.crawl("https://example.com", nil, poll_interval: 0, timeout: 10)+ assert_equal 2, job.data.size+ assert_equal "# Page 1", job.data[0].markdown+ assert_equal "# Page 2", job.data[1].markdown+ end++ # ================================================================+ # INTERACT+ # ================================================================++ def test_interact+ stub_request(:post, "#{BASE_URL}/v2/scrape/job-123/interact")+ .with { |req| body = JSON.parse(req.body); body["code"] == "console.log('hi')" && body["language"] == "node" }+ .to_return(+ status: 200,+ body: JSON.generate(stdout: "hi\n", stderr: "", exitCode: 0),+ headers: { "Content-Type" => "application/json" }+ )++ result = @client.interact("job-123", "console.log('hi')")+ assert_equal "hi\n", result["stdout"]+ assert_equal 0, result["exitCode"]+ end+enddiff --git a/apps/ruby-sdk/test/test_helper.rb b/apps/ruby-sdk/test/test_helper.rbnew file mode 100644index 000000000..ce031f44d--- /dev/null+++ b/apps/ruby-sdk/test/test_helper.rb@@ -0,0 +1,5 @@+# frozen_string_literal: true++require "minitest/autorun"+require "webmock/minitest"+require "firecrawl"