Skip to content

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

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.py
index 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.0
Published 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 json
import 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 Central
published_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.yml
new file mode 100644
index 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-*.gem
diff --git a/.github/workflows/test-ruby-sdk.yml b/.github/workflows/test-ruby-sdk.yml
new file mode 100644
index 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 test
diff --git a/apps/ruby-sdk/.gitignore b/apps/ruby-sdk/.gitignore
new file mode 100644
index 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/Gemfile
new file mode 100644
index 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"
+end
diff --git a/apps/ruby-sdk/LICENSE b/apps/ruby-sdk/LICENSE
new file mode 100644
index 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.md
new file mode 100644
index 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/Rakefile
new file mode 100644
index 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: :test
diff --git a/apps/ruby-sdk/firecrawl.gemspec b/apps/ruby-sdk/firecrawl.gemspec
new file mode 100644
index 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"]
+end
diff --git a/apps/ruby-sdk/lib/firecrawl.rb b/apps/ruby-sdk/lib/firecrawl.rb
new file mode 100644
index 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.rb
new file mode 100644
index 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
+end
diff --git a/apps/ruby-sdk/lib/firecrawl/errors.rb b/apps/ruby-sdk/lib/firecrawl/errors.rb
new file mode 100644
index 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
+end
diff --git a/apps/ruby-sdk/lib/firecrawl/http_client.rb b/apps/ruby-sdk/lib/firecrawl/http_client.rb
new file mode 100644
index 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
+end
diff --git a/apps/ruby-sdk/lib/firecrawl/models/agent_options.rb b/apps/ruby-sdk/lib/firecrawl/models/agent_options.rb
new file mode 100644
index 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
+end
diff --git a/apps/ruby-sdk/lib/firecrawl/models/agent_response.rb b/apps/ruby-sdk/lib/firecrawl/models/agent_response.rb
new file mode 100644
index 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
+end
diff --git a/apps/ruby-sdk/lib/firecrawl/models/agent_status_response.rb b/apps/ruby-sdk/lib/firecrawl/models/agent_status_response.rb
new file mode 100644
index 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
+end
diff --git a/apps/ruby-sdk/lib/firecrawl/models/batch_scrape_job.rb b/apps/ruby-sdk/lib/firecrawl/models/batch_scrape_job.rb
new file mode 100644
index 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
+end
diff --git a/apps/ruby-sdk/lib/firecrawl/models/batch_scrape_options.rb b/apps/ruby-sdk/lib/firecrawl/models/batch_scrape_options.rb
new file mode 100644
index 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
+end
diff --git a/apps/ruby-sdk/lib/firecrawl/models/batch_scrape_response.rb b/apps/ruby-sdk/lib/firecrawl/models/batch_scrape_response.rb
new file mode 100644
index 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
+end
diff --git a/apps/ruby-sdk/lib/firecrawl/models/concurrency_check.rb b/apps/ruby-sdk/lib/firecrawl/models/concurrency_check.rb
new file mode 100644
index 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
+end
diff --git a/apps/ruby-sdk/lib/firecrawl/models/crawl_job.rb b/apps/ruby-sdk/lib/firecrawl/models/crawl_job.rb
new file mode 100644
index 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
+end
diff --git a/apps/ruby-sdk/lib/firecrawl/models/crawl_options.rb b/apps/ruby-sdk/lib/firecrawl/models/crawl_options.rb
new file mode 100644
index 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
+end
diff --git a/apps/ruby-sdk/lib/firecrawl/models/crawl_response.rb b/apps/ruby-sdk/lib/firecrawl/models/crawl_response.rb
new file mode 100644
index 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
+end
diff --git a/apps/ruby-sdk/lib/firecrawl/models/credit_usage.rb b/apps/ruby-sdk/lib/firecrawl/models/credit_usage.rb
new file mode 100644
index 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
+end
diff --git a/apps/ruby-sdk/lib/firecrawl/models/document.rb b/apps/ruby-sdk/lib/firecrawl/models/document.rb
new file mode 100644
index 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
+end
diff --git a/apps/ruby-sdk/lib/firecrawl/models/map_data.rb b/apps/ruby-sdk/lib/firecrawl/models/map_data.rb
new file mode 100644
index 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
+end
diff --git a/apps/ruby-sdk/lib/firecrawl/models/map_options.rb b/apps/ruby-sdk/lib/firecrawl/models/map_options.rb
new file mode 100644
index 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
+end
diff --git a/apps/ruby-sdk/lib/firecrawl/models/scrape_options.rb b/apps/ruby-sdk/lib/firecrawl/models/scrape_options.rb
new file mode 100644
index 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
+end
diff --git a/apps/ruby-sdk/lib/firecrawl/models/search_data.rb b/apps/ruby-sdk/lib/firecrawl/models/search_data.rb
new file mode 100644
index 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
+end
diff --git a/apps/ruby-sdk/lib/firecrawl/models/search_options.rb b/apps/ruby-sdk/lib/firecrawl/models/search_options.rb
new file mode 100644
index 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
+end
diff --git a/apps/ruby-sdk/lib/firecrawl/version.rb b/apps/ruby-sdk/lib/firecrawl/version.rb
new file mode 100644
index 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"
+end
diff --git a/apps/ruby-sdk/test/firecrawl/client_test.rb b/apps/ruby-sdk/test/firecrawl/client_test.rb
new file mode 100644
index 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
+end
diff --git a/apps/ruby-sdk/test/test_helper.rb b/apps/ruby-sdk/test/test_helper.rb
new file mode 100644
index 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"