firecrawl-sdk 1.10.0 → 1.17.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fc48fdfecc01e4811b2634c740ffab0787e03f99001a401014a3e98b0e63f627
-  data.tar.gz: ad7b3330c7e5f0934c58747ad2748b737783b90d4ccbf732d6f60924543bf45d
+  metadata.gz: 22543b5053874d9d1a815949df7212abbcca9a72738a23ecfc696194696b6ad6
+  data.tar.gz: a53387ffdbb11b21ce357368f617dd83fdf341619a022db5997b8a4e3bfab6b1
 SHA512:
-  metadata.gz: 75d9dde872641f95f313555ee32c842295c1a4afd150e1158b256821cf5a61f21078c80003b96ef86bce189c8909de1053bbad00a53907b5c191368b1af94444
-  data.tar.gz: 87b0802113b459ead84ea99a1b3a3aa989c26bf1c55b98dd567e7a2e669a38f52a9205a0924b5c1824e8078f61ab472d2f12a471dabfd7a86b445892914c061e
+  metadata.gz: 7345b8e668fd1ece22c0de23408a7f99e6e5da42f2a573973cb32b4db18cd5bb2d8f61f505e0de5df4e0a0c96fd11af8c35531cd98bcdaa2aab470227678a9ac
+  data.tar.gz: 7a4ec95b23cd3e767e93742600a01c8a51123d9c9589823bf62f6a2fb2561ad77fb05c95a45324e44a0ef7322aea4fcd94a46ce6e3b705f61ec5831901ff27ec

data/README.md

@@ -1,6 +1,6 @@
 # Firecrawl Ruby SDK
 
-Ruby SDK for the [Firecrawl](https://firecrawl.dev) v2 web scraping API.
+Ruby SDK for [Firecrawl](https://firecrawl.dev), the context API for AI agents. Search, scrape, parse, crawl, map, and interact with the web, and run Agent and Monitor jobs on the v2 API.
 
 ## Prerequisites
 
@@ -126,6 +126,15 @@ doc = client.parse(file,
 puts doc.markdown
 ```
 
+List the file formats the parse endpoint accepts. `available` is `false` for
+formats the deployment can't currently handle (e.g. images when OCR is off).
+
+```ruby
+client.get_parse_formats.each do |f|
+  puts "#{f.format} (#{f.kind}) #{f.extensions.join(", ")} #{f.mime_types.join(", ")} available=#{f.available}"
+end
+```
+
 ### Crawl
 
 ```ruby
@@ -184,6 +193,25 @@ results = client.search("latest news",
   Firecrawl::Models::SearchOptions.new(limit: 5, location: "US"))
 ```
 
+### Developer Search
+
+Search public repositories, GitHub issues, merged pull requests, READMEs and code documentation. `developer_search` replaces the deprecated `search_github`.
+
+```ruby
+response = client.developer_search(
+  "retry an http request with exponential backoff",
+  Firecrawl::Models::DeveloperSearchOptions.new(
+    k: 5,
+    types: ["issue", "pull_request"],
+    repos: ["square/okhttp"]
+  )
+)
+
+response.results.each do |result|
+  puts "#{result.title} #{result.url}"
+end
+```
+
 ### Agent
 
 ```ruby
@@ -194,6 +222,17 @@ status = client.agent(
     urls: ["https://example.com"]
   ))
 puts status.data
+
+# Use Alexandria data providers connected in the dashboard
+status = client.agent(
+  Firecrawl::Models::AgentOptions.new(
+    prompt: "Find the work email of the CEO of example.com",
+    exchange: Firecrawl::Models::AgentExchangeOptions.new(
+      enabled: true,
+      toolkits: ["apollo"]
+    )
+  ))
+puts status.exchange&.paid_calls
 ```
 
 ### Usage & Metrics

data/lib/firecrawl/client.rb

@@ -81,6 +81,10 @@ module Firecrawl
       body.merge!(options.to_h) if options
       body["origin"] ||= "ruby-sdk@#{Firecrawl::VERSION}"
       raw = @http.post("/v2/scrape", body)
+      # Some scrape failures (e.g. SCRAPE_DNS_RESOLUTION_ERROR) arrive as HTTP 200 with success: false.
+      if raw["success"] == false
+        raise FirecrawlError.new(raw["error"] || "Scrape failed", status_code: 200, error_code: raw["code"], details: raw["details"])
+      end
       data = raw["data"] || raw
       Models::Document.new(data)
     end
@@ -129,6 +133,9 @@ module Firecrawl
 
     # Search GitHub research content.
     #
+    # @deprecated Stops responding after 2026-11-03. Use {#developer_search},
+    #   which does not carry over the score breakdown or the web fallback
+    #   results.
     # @param query_text [String] GitHub query
     # @param options [Hash] optional query parameters
     # @return [Hash]
@@ -136,6 +143,22 @@ module Firecrawl
       @http.get("/v2/search/research/github#{query(options.merge("query" => query_text, "origin" => "ruby-sdk@#{Firecrawl::VERSION}"))}")
     end
 
+    # Searches the developer index: public repositories, GitHub issues, merged
+    # pull requests, READMEs and code documentation.
+    #
+    # @param query [String] the search query
+    # @param options [Models::DeveloperSearchOptions, nil] developer search filters
+    # @return [Models::DeveloperSearchResponse]
+    # @raise [ArgumentError] if the query is blank
+    def developer_search(query, options = nil)
+      raise ArgumentError, "Query is required" if query.nil? || query.to_s.strip.empty?
+
+      body = { "query" => query }
+      body.merge!(options.to_h) if options
+      body["origin"] ||= "ruby-sdk@#{Firecrawl::VERSION}"
+      Models::DeveloperSearchResponse.new(@http.post("/v2/search/developer", body))
+    end
+
     # Interacts with the scrape-bound browser session for a scrape job.
     #
     # @param job_id [String] the scrape job ID
@@ -191,6 +214,15 @@ module Firecrawl
       Models::Document.new(data)
     end
 
+    # Lists the file formats accepted by {#parse} on this deployment.
+    #
+    # @return [Array<Models::ParseFormat>]
+    def get_parse_formats
+      raw = @http.get("/v2/parse/formats")
+      formats = (raw["data"] || {})["formats"] || []
+      formats.map { |f| Models::ParseFormat.new(f) }
+    end
+
     # ================================================================
     # CRAWL
     # ================================================================
@@ -205,6 +237,7 @@ module Firecrawl
 
       body = { "url" => url }
       body.merge!(options.to_h) if options
+      body["origin"] ||= "ruby-sdk@#{Firecrawl::VERSION}"
       raw = @http.post("/v2/crawl", body)
       Models::CrawlResponse.new(raw)
     end
@@ -279,6 +312,7 @@ module Firecrawl
         body.merge!(opts_hash)
         body.merge!(nested) if nested
       end
+      body["origin"] ||= "ruby-sdk@#{Firecrawl::VERSION}"
       raw = @http.post("/v2/batch/scrape", body, extra_headers: extra_headers)
       Models::BatchScrapeResponse.new(raw)
     end
@@ -330,6 +364,7 @@ module Firecrawl
 
       body = { "url" => url }
       body.merge!(options.to_h) if options
+      body["origin"] ||= "ruby-sdk@#{Firecrawl::VERSION}"
       raw = @http.post("/v2/map", body)
       data = raw["data"] || raw
       Models::MapData.new(data)
@@ -463,6 +498,20 @@ module Firecrawl
       Models::AgentStatusResponse.new(raw)
     end
 
+    # Lists agent tasks, most recent first.
+    #
+    # Pages are fixed at 20 runs. To fetch the next page, pass the before
+    # value from the previous page's next URL. This method does not
+    # auto-paginate.
+    #
+    # @param before [Integer, nil] only return agent runs created before this
+    #   unix millisecond timestamp
+    # @return [Models::AgentListResponse]
+    def list_agents(before: nil)
+      raw = @http.get("/v2/agent#{query(before: before)}")
+      Models::AgentListResponse.new(raw)
+    end
+
     # Runs an agent task and waits for completion (auto-polling).
     #
     # @param options [Models::AgentOptions] agent configuration
@@ -493,6 +542,31 @@ module Firecrawl
       @http.delete("/v2/agent/#{job_id}")
     end
 
+    # Gets the trace of an agent task.
+    #
+    # @param job_id [String] the agent job ID
+    # @param live_view [Boolean] include live view URLs for active browser sessions
+    # @return [Models::AgentTraceResponse]
+    def get_agent_trace(job_id, live_view: false)
+      raise ArgumentError, "Job ID is required" if job_id.nil?
+
+      raw = @http.get("/v2/agent/#{job_id}/trace#{query(liveView: live_view ? true : nil)}")
+      Models::AgentTraceResponse.new(raw)
+    end
+
+    # Gets a snapshot of an agent task.
+    #
+    # @param job_id [String] the agent job ID
+    # @param snapshot_id [String] the snapshot ID
+    # @return [Models::AgentSnapshotResponse]
+    def get_agent_snapshot(job_id, snapshot_id)
+      raise ArgumentError, "Job ID is required" if job_id.nil?
+      raise ArgumentError, "Snapshot ID is required" if snapshot_id.nil?
+
+      raw = @http.get("/v2/agent/#{job_id}/snapshots/#{snapshot_id}")
+      Models::AgentSnapshotResponse.new(raw)
+    end
+
     # ================================================================
     # USAGE & METRICS
     # ================================================================

data/lib/firecrawl/models/agent_exchange_options.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Firecrawl
+  module Models
+    # Alexandria (Exchange) options for an agent run, forwarded verbatim; the
+    # server owns every default and limit. On a follow-up turn, omitting the
+    # exchange options inherits the previous turn's settings.
+    #
+    # on_terms_required: "skip" or "ask".
+    class AgentExchangeOptions
+      # Answers the previous turn's pending approval. A "terms" approval is
+      # accepted as a whole, so call_ids and always are ignored on it.
+      class Approve
+        attr_reader :approval_id, :call_ids, :always
+
+        def initialize(approval_id:, call_ids: nil, always: nil)
+          @approval_id = approval_id
+          @call_ids = call_ids
+          @always = always
+        end
+
+        def to_h
+          {
+            "approvalId" => approval_id,
+            "callIds" => call_ids,
+            "always" => always,
+          }.compact
+        end
+      end
+
+      # Refuses the previous turn's pending approval.
+      class Decline
+        attr_reader :approval_id
+
+        def initialize(approval_id:)
+          @approval_id = approval_id
+        end
+
+        def to_h
+          { "approvalId" => approval_id }
+        end
+      end
+
+      FIELDS = %i[
+        enabled toolkits max_calls require_approval approve decline
+        on_terms_required
+      ].freeze
+
+      attr_reader(*FIELDS)
+
+      def initialize(**kwargs)
+        FIELDS.each { |f| instance_variable_set(:"@#{f}", kwargs[f]) }
+      end
+
+      def to_h
+        {
+          "enabled" => enabled,
+          "toolkits" => toolkits,
+          "maxCalls" => max_calls,
+          "requireApproval" => require_approval,
+          "approve" => approve&.to_h,
+          "decline" => decline&.to_h,
+          "onTermsRequired" => on_terms_required,
+        }.compact
+      end
+    end
+  end
+end

data/lib/firecrawl/models/agent_exchange_summary.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Firecrawl
+  module Models
+    # What an agent run did with Alexandria (Exchange). toolkits and
+    # require_approval are what the run resolved to after thread inheritance.
+    class AgentExchangeSummary
+      # A provider that needs data terms the team has not accepted, so the run
+      # did not use it.
+      class SkippedProvider
+        attr_reader :provider, :name, :capability, :adds, :reason, :version,
+                    :terms_url
+
+        def initialize(data)
+          @provider = data["provider"]
+          @name = data["name"]
+          @capability = data["capability"]
+          @adds = data["adds"]
+          @reason = data["reason"]
+          @version = data["version"]
+          @terms_url = data["termsUrl"]
+        end
+      end
+
+      # The Exchange calls to view and accept providers' terms ("ask" mode).
+      # Nothing here runs for you; only call accept after your user agrees.
+      class TermsRequiredAction
+        # show and accept are the raw Exchange calls ("provider",
+        # "capability", "options").
+        class Provider
+          attr_reader :provider, :name, :capability, :adds, :version, :digest,
+                      :url, :show, :accept
+
+          def initialize(data)
+            @provider = data["provider"]
+            @name = data["name"]
+            @capability = data["capability"]
+            @adds = data["adds"]
+            @version = data["version"]
+            @digest = data["digest"]
+            @url = data["url"]
+            @show = data["show"]
+            @accept = data["accept"]
+          end
+        end
+
+        attr_reader :type, :approval_id, :providers
+
+        def initialize(data)
+          @type = data["type"]
+          @approval_id = data["approvalId"]
+          @providers = data["providers"]&.map { |p| Provider.new(p) }
+        end
+      end
+
+      attr_reader :enabled, :toolkits, :require_approval, :on_terms_required,
+                  :paid_calls, :credits_used, :skipped_providers,
+                  :requires_action
+
+      def initialize(data)
+        @enabled = data["enabled"]
+        @toolkits = data["toolkits"]
+        @require_approval = data["requireApproval"]
+        @on_terms_required = data["onTermsRequired"]
+        @paid_calls = data["paidCalls"]
+        @credits_used = data["creditsUsed"]
+        @skipped_providers = data["skippedProviders"]&.map { |p| SkippedProvider.new(p) }
+        @requires_action = data["requiresAction"] && TermsRequiredAction.new(data["requiresAction"])
+      end
+    end
+  end
+end

data/lib/firecrawl/models/agent_list_response.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Firecrawl
+  module Models
+    # Response from listing agent tasks.
+    class AgentListResponse
+      attr_reader :success, :agents, :next, :error
+
+      def initialize(raw)
+        @success = raw["success"]
+        @agents = raw["agents"]
+        @next = raw["next"]
+        @error = raw["error"]
+      end
+
+      def to_s
+        "AgentListResponse{success=#{success}, agents=#{agents&.size}}"
+      end
+    end
+  end
+end

data/lib/firecrawl/models/agent_options.rb

@@ -3,16 +3,26 @@
 module Firecrawl
   module Models
     # Options for starting an agent task.
+    #
+    # effort: valid values are "low", "medium", and "high"; sets the reasoning
+    # budget for the run (every level runs spark-2).
+    #
+    # thread_id continues an existing thread as its next turn; omitted starts a
+    # new thread. mode: "extract" or "chat".
     class AgentOptions
       FIELDS = %i[
         urls prompt schema integration max_credits
-        strict_constrain_to_urls model webhook
+        strict_constrain_to_urls model effort webhook audit_metadata
+        thread_id mode exchange
       ].freeze
 
       attr_reader(*FIELDS)
 
       def initialize(**kwargs)
         FIELDS.each { |f| instance_variable_set(:"@#{f}", kwargs[f]) }
+        if audit_metadata && !audit_metadata.is_a?(AuditMetadata)
+          raise ArgumentError, "audit_metadata must be an AuditMetadata"
+        end
         raise ArgumentError, "Agent prompt is required" if prompt.nil? || prompt.empty?
       end
 
@@ -25,7 +35,12 @@ module Firecrawl
           "maxCredits" => max_credits,
           "strictConstrainToURLs" => strict_constrain_to_urls,
           "model" => model,
+          "effort" => effort,
           "webhook" => webhook.is_a?(Hash) ? webhook : webhook&.to_h,
+          "auditMetadata" => audit_metadata&.to_h,
+          "threadId" => thread_id,
+          "mode" => mode,
+          "exchange" => exchange&.to_h,
         }.compact
       end
     end

data/lib/firecrawl/models/agent_pending_approval.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Firecrawl
+  module Models
+    # A turn that ended waiting for the caller. kind "calls" (or nil on older
+    # runs) holds paid calls to allow or refuse; kind "terms" lists providers
+    # whose data terms need accepting, with calls empty. Answer it on the next
+    # turn of the thread with AgentExchangeOptions approve or decline.
+    class AgentPendingApproval
+      # input and more are the raw call arguments.
+      class Call
+        attr_reader :id, :provider, :capability, :input, :more,
+                    :credits_estimate
+
+        def initialize(data)
+          @id = data["id"]
+          @provider = data["provider"]
+          @capability = data["capability"]
+          @input = data["input"]
+          @more = data["more"]
+          @credits_estimate = data["creditsEstimate"]
+        end
+      end
+
+      class TermsGate
+        attr_reader :provider, :name, :logo, :capability, :adds, :version,
+                    :digest, :url
+
+        def initialize(data)
+          @provider = data["provider"]
+          @name = data["name"]
+          @logo = data["logo"]
+          @capability = data["capability"]
+          @adds = data["adds"]
+          @version = data["version"]
+          @digest = data["digest"]
+          @url = data["url"]
+        end
+      end
+
+      class Resolution
+        attr_reader :approved, :call_ids, :always, :by_run_id
+
+        def initialize(data)
+          @approved = data["approved"]
+          @call_ids = data["callIds"]
+          @always = data["always"]
+          @by_run_id = data["byRunId"]
+        end
+      end
+
+      attr_reader :id, :kind, :reason, :calls, :terms, :resolution
+
+      def initialize(data)
+        @id = data["id"]
+        @kind = data["kind"]
+        @reason = data["reason"]
+        @calls = data["calls"]&.map { |c| Call.new(c) }
+        @terms = data["terms"]&.map { |t| TermsGate.new(t) }
+        @resolution = data["resolution"] && Resolution.new(data["resolution"])
+      end
+    end
+  end
+end

data/lib/firecrawl/models/agent_response.rb

@@ -4,12 +4,15 @@ module Firecrawl
   module Models
     # Response from starting an agent task.
     class AgentResponse
-      attr_reader :success, :id, :error
+      attr_reader :success, :id, :error, :thread_id, :thread_turn
 
       def initialize(data)
         @success = data["success"]
         @id = data["id"]
         @error = data["error"]
+        # Pass thread_id back in AgentOptions to continue the conversation.
+        @thread_id = data["threadId"]
+        @thread_turn = data["threadTurn"]
       end
 
       def to_s

data/lib/firecrawl/models/agent_snapshot_response.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Firecrawl
+  module Models
+    # Snapshot response for an agent task.
+    class AgentSnapshotResponse
+      attr_reader :success, :id, :snapshot_id, :snapshot, :error
+
+      def initialize(raw)
+        @success = raw["success"]
+        @id = raw["id"]
+        @snapshot_id = raw["snapshotId"]
+        @snapshot = raw["snapshot"]
+        @error = raw["error"]
+      end
+
+      def to_s
+        "AgentSnapshotResponse{id=#{id}, snapshot_id=#{snapshot_id}, success=#{success}}"
+      end
+    end
+  end
+end

data/lib/firecrawl/models/agent_status_response.rb

@@ -4,13 +4,24 @@ module Firecrawl
   module Models
     # Status response for monitoring agent tasks.
     class AgentStatusResponse
-      attr_reader :status, :data, :credits_used, :expires_at
+      attr_reader :status, :data, :credits_used, :expires_at, :effort,
+                  :thread_id, :thread_turn, :mode, :message, :pending_approval,
+                  :exchange
 
       def initialize(raw)
         @status = raw["status"]
         @data = raw["data"]
         @credits_used = raw["creditsUsed"]
         @expires_at = raw["expiresAt"]
+        # The effort the job ran with; only present for runs that specified it.
+        @effort = raw["effort"]
+        @thread_id = raw["threadId"]
+        @thread_turn = raw["threadTurn"]
+        @mode = raw["mode"]
+        # Chat-mode runs answer here instead of in data.
+        @message = raw["message"]
+        @pending_approval = raw["pendingApproval"] && AgentPendingApproval.new(raw["pendingApproval"])
+        @exchange = raw["exchange"] && AgentExchangeSummary.new(raw["exchange"])
       end
 
       def done?

data/lib/firecrawl/models/agent_trace_response.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Firecrawl
+  module Models
+    # Trace response for an agent task.
+    #
+    # Events are raw hashes: each carries a "type" (e.g. "run.started",
+    # "agent.finished", "tool_call.started") plus base fields like
+    # "schemaVersion", "eventId", "runId", "occurredAt", "producerSequence",
+    # and "agent".
+    class AgentTraceResponse
+      attr_reader :success, :id, :events, :active_browser_sessions, :credits_used, :error
+
+      def initialize(raw)
+        @success = raw["success"]
+        @id = raw["id"]
+        @events = raw["events"]
+        @active_browser_sessions = raw["activeBrowserSessions"]
+        @credits_used = raw["creditsUsed"]
+        @error = raw["error"]
+      end
+
+      def to_s
+        "AgentTraceResponse{id=#{id}, success=#{success}}"
+      end
+    end
+  end
+end

data/lib/firecrawl/models/audit_metadata.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Firecrawl
+  module Models
+    # User attribution included with SIEM logging events.
+    class AuditMetadata
+      attr_reader :username
+
+      def initialize(username:)
+        raise ArgumentError, "username must be a string" unless username.is_a?(String)
+
+        @username = username
+      end
+
+      def to_h
+        { "username" => username }
+      end
+    end
+  end
+end

data/lib/firecrawl/models/developer_search_options.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Firecrawl
+  module Models
+    # Options for a developer search request. Unset fields are omitted.
+    #
+    # - k: total ranked results, 1 to 100 (default 10)
+    # - passages: passages per result, 1 to 5 (default 1)
+    # - types: result kinds, any of "doc", "issue", "pull_request", "readme"
+    # - repos: GitHub owner/name filters, at most 20
+    # - sources: developer documentation source IDs, at most 20
+    # - language: one case-insensitive GitHub Linguist primary language
+    # - topic: repository topics that must all match, at most 8
+    # - license: one case-insensitive SPDX repository license identifier
+    # - min_stars, max_stars, archived, fork: repository filters
+    # - skills: "only" returns packaged agent-skill evidence only
+    class DeveloperSearchOptions
+      FIELDS = %i[
+        k passages types repos sources language topic license
+        min_stars max_stars archived fork skills
+      ].freeze
+
+      attr_reader(*FIELDS)
+
+      def initialize(**kwargs)
+        unknown = kwargs.keys - FIELDS
+        raise ArgumentError, "unknown developer search option(s): #{unknown.join(", ")}" unless unknown.empty?
+
+        FIELDS.each { |f| instance_variable_set(:"@#{f}", kwargs[f]) }
+      end
+
+      def to_h
+        FIELDS.to_h { |f| [f.to_s, public_send(f)] }.compact
+      end
+    end
+  end
+end

data/lib/firecrawl/models/developer_search_response.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Firecrawl
+  module Models
+    # One matched passage of a developer search result.
+    class DeveloperSearchPassage
+      attr_reader :text, :citation_url
+
+      def initialize(data)
+        @text = data["text"]
+        @citation_url = data["citation_url"]
+      end
+    end
+
+    # One ranked developer search result. `license` is either an SPDX string or
+    # a disclosure object (Hash), so it is kept as returned.
+    class DeveloperSearchResult
+      attr_reader :id, :url, :title, :passages, :license
+
+      def initialize(data)
+        @id = data["id"]
+        @url = data["url"]
+        @title = data["title"]
+        @passages = (data["passages"] || []).map { |p| DeveloperSearchPassage.new(p) }
+        @license = data["license"]
+      end
+    end
+
+    # Whether a requested repository is indexed, and which result types it has.
+    class DeveloperSearchRepoStatus
+      attr_reader :repo, :indexed, :types
+
+      def initialize(data)
+        @repo = data["repo"]
+        @indexed = data["indexed"] == true
+        @types = data["types"] || {}
+      end
+
+      def indexed?
+        indexed
+      end
+    end
+
+    # Whether a requested documentation source is indexed.
+    class DeveloperSearchSourceStatus
+      attr_reader :source, :indexed
+
+      def initialize(data)
+        @source = data["source"]
+        @indexed = data["indexed"] == true
+      end
+
+      def indexed?
+        indexed
+      end
+    end
+
+    # Response from a developer search. `repos` and `sources` are present only
+    # when those filters were requested.
+    class DeveloperSearchResponse
+      attr_reader :success, :partial, :results, :repos, :sources
+
+      def initialize(data)
+        @success = data["success"] == true
+        @partial = data["partial"] == true
+        @results = (data["results"] || []).map { |r| DeveloperSearchResult.new(r) }
+        @repos = data["repos"]&.map { |r| DeveloperSearchRepoStatus.new(r) }
+        @sources = data["sources"]&.map { |s| DeveloperSearchSourceStatus.new(s) }
+      end
+
+      def to_s
+        "DeveloperSearchResponse{results=#{results.size}}"
+      end
+    end
+  end
+end

data/lib/firecrawl/models/document.rb

@@ -7,7 +7,8 @@ module Firecrawl
       attr_reader :markdown, :html, :raw_html, :json, :summary,
                   :metadata, :links, :images, :screenshot, :audio,
                   :video, :attributes, :actions, :answer, :highlights,
-                  :warning, :change_tracking, :branding, :product, :menu
+                  :warning, :change_tracking, :branding, :product, :menu,
+                  :pages, :blocks
 
       def initialize(data)
         @markdown = data["markdown"]
@@ -30,6 +31,8 @@ module Firecrawl
         @branding = data["branding"]
         @product = data["product"] && ProductProfile.new(data["product"])
         @menu = data["menu"] && MenuProfile.new(data["menu"])
+        @pages = data["pages"]
+        @blocks = data["blocks"]
       end
 
       def to_s

data/lib/firecrawl/models/map_options.rb

@@ -6,13 +6,16 @@ module Firecrawl
     class MapOptions
       FIELDS = %i[
         search sitemap include_subdomains ignore_query_parameters
-        limit timeout integration location
+        limit timeout integration location audit_metadata
       ].freeze
 
       attr_reader(*FIELDS)
 
       def initialize(**kwargs)
         FIELDS.each { |f| instance_variable_set(:"@#{f}", kwargs[f]) }
+        if audit_metadata && !audit_metadata.is_a?(AuditMetadata)
+          raise ArgumentError, "audit_metadata must be an AuditMetadata"
+        end
       end
 
       def to_h
@@ -25,6 +28,7 @@ module Firecrawl
           "timeout" => timeout,
           "integration" => integration,
           "location" => location.is_a?(Hash) ? location : location&.to_h,
+          "auditMetadata" => audit_metadata&.to_h,
         }.compact
       end
     end

data/lib/firecrawl/models/parse_format.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Firecrawl
+  module Models
+    # A file format accepted by the `/v2/parse` endpoint.
+    #
+    # `kind` is usually one of {KIND_DOCUMENT} or {KIND_IMAGE}, but newer API
+    # versions may return other values, which are kept as-is.
+    class ParseFormat
+      KIND_DOCUMENT = "document"
+      KIND_IMAGE = "image"
+
+      attr_reader :format, :kind, :extensions, :mime_types, :available
+
+      def initialize(data)
+        @format = data["format"]
+        @kind = data["kind"]
+        @extensions = data["extensions"] || []
+        @mime_types = data["mimeTypes"] || []
+        @available = data["available"]
+      end
+
+      def document?
+        kind == KIND_DOCUMENT
+      end
+
+      def image?
+        kind == KIND_IMAGE
+      end
+
+      def to_s
+        "ParseFormat{format=#{format}, kind=#{kind}, available=#{available}}"
+      end
+    end
+  end
+end

data/lib/firecrawl/models/parse_options.rb

@@ -7,19 +7,28 @@ module Firecrawl
     # Parse does not support browser-rendering features (actions, waitFor,
     # location, mobile) nor screenshot/branding/product/menu/audio/video/changeTracking formats. The
     # proxy field only accepts "auto" or "basic".
+    #
+    # check_prompt_injection scans the parsed content for prompt injection
+    # before LLM-backed formats run. A detection fails the parse with
+    # SCRAPE_PROMPT_INJECTION_DETECTED. Adds 4 credits when the check scans
+    # the whole content.
     class ParseOptions
       UNSUPPORTED_FORMATS = %w[changeTracking screenshot screenshot@fullPage branding product menu audio video].freeze
 
       FIELDS = %i[
         formats headers include_tags exclude_tags only_main_content
         timeout parsers skip_tls_verification remove_base64_images
-        block_ads proxy integration redact_pii json_options
+        block_ads proxy integration redact_pii json_options audit_metadata
+        check_prompt_injection
       ].freeze
 
       attr_reader(*FIELDS)
 
       def initialize(**kwargs)
         FIELDS.each { |f| instance_variable_set(:"@#{f}", kwargs[f]) }
+        if audit_metadata && !audit_metadata.is_a?(AuditMetadata)
+          raise ArgumentError, "audit_metadata must be an AuditMetadata"
+        end
 
         validate!
       end
@@ -32,14 +41,16 @@ module Firecrawl
           "excludeTags" => exclude_tags,
           "onlyMainContent" => only_main_content,
           "timeout" => timeout,
-          "parsers" => parsers,
+          "parsers" => parsers&.map { |parser| parser.respond_to?(:to_h) ? parser.to_h : parser },
           "skipTlsVerification" => skip_tls_verification,
           "removeBase64Images" => remove_base64_images,
           "blockAds" => block_ads,
           "proxy" => proxy,
           "integration" => integration,
           "redactPII" => redact_pii,
+          "checkPromptInjection" => check_prompt_injection,
           "jsonOptions" => json_options.is_a?(Hash) ? json_options : json_options&.to_h,
+          "auditMetadata" => audit_metadata&.to_h,
         }.compact
       end
 

data/lib/firecrawl/models/pdf_parser.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Firecrawl
+  module Models
+    # PDF parser configuration for use in ScrapeOptions / ParseOptions parsers.
+    class PDFParser
+      attr_reader :mode, :max_pages, :pages, :blocks, :page_markers
+
+      def initialize(mode: nil, max_pages: nil, pages: nil, blocks: nil, page_markers: nil)
+        @mode = mode
+        @max_pages = max_pages
+        @pages = pages
+        @blocks = blocks
+        @page_markers = page_markers
+      end
+
+      def to_h
+        {
+          "type" => "pdf",
+          "mode" => mode,
+          "maxPages" => max_pages,
+          "pages" => pages,
+          "blocks" => blocks,
+          "pageMarkers" => page_markers,
+        }.compact
+      end
+
+      def type
+        "pdf"
+      end
+    end
+  end
+end

data/lib/firecrawl/models/query_format.rb

@@ -42,6 +42,33 @@ module Firecrawl
       end
     end
 
+    # JSON format for extracting structured data from page content using a schema.
+    #
+    # check_prompt_injection is deprecated: use ScrapeOptions#check_prompt_injection
+    # or ParseOptions#check_prompt_injection.
+    class JsonFormat
+      attr_reader :schema, :prompt, :check_prompt_injection
+
+      def initialize(schema: nil, prompt: nil, check_prompt_injection: nil)
+        @schema = schema
+        @prompt = prompt
+        @check_prompt_injection = check_prompt_injection
+      end
+
+      def to_h
+        {
+          "type" => "json",
+          "schema" => schema,
+          "prompt" => prompt,
+          "checkPromptInjection" => check_prompt_injection,
+        }.compact
+      end
+
+      def type
+        "json"
+      end
+    end
+
     # Deprecated query format for asking a question about page content.
     class QueryFormat
       MODE_FREEFORM = "freeform"

data/lib/firecrawl/models/scrape_options.rb

@@ -3,18 +3,27 @@
 module Firecrawl
   module Models
     # Options for scraping a single URL.
+    #
+    # check_prompt_injection scans the page content for prompt injection with
+    # any format except rawBase64, before LLM-backed formats run. A detection
+    # fails the scrape with SCRAPE_PROMPT_INJECTION_DETECTED. Adds 4 credits
+    # when the check scans the whole page.
     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 lockdown redact_pii integration
+        max_age store_in_cache lockdown check_prompt_injection redact_pii
+        integration audit_metadata
       ].freeze
 
       attr_reader(*FIELDS)
 
       def initialize(**kwargs)
         FIELDS.each { |f| instance_variable_set(:"@#{f}", kwargs[f]) }
+        if audit_metadata && !audit_metadata.is_a?(AuditMetadata)
+          raise ArgumentError, "audit_metadata must be an AuditMetadata"
+        end
         @skip_tls_verification = false if @skip_tls_verification.nil?
       end
 
@@ -28,7 +37,7 @@ module Firecrawl
           "timeout" => timeout,
           "waitFor" => wait_for,
           "mobile" => mobile,
-          "parsers" => parsers,
+          "parsers" => parsers&.map { |parser| parser.respond_to?(:to_h) ? parser.to_h : parser },
           "actions" => actions,
           "location" => location.is_a?(Hash) ? location : location&.to_h,
           "skipTlsVerification" => skip_tls_verification,
@@ -38,8 +47,10 @@ module Firecrawl
           "maxAge" => max_age,
           "storeInCache" => store_in_cache,
           "lockdown" => lockdown,
+          "checkPromptInjection" => check_prompt_injection,
           "redactPII" => redact_pii,
           "integration" => integration,
+          "auditMetadata" => audit_metadata&.to_h,
         }.compact
       end
 

data/lib/firecrawl/models/search_options.rb

@@ -5,8 +5,8 @@ module Firecrawl
     # Options for a web search request.
     class SearchOptions
       FIELDS = %i[
-        sources categories include_domains exclude_domains limit tbs location
-        ignore_invalid_urls timeout scrape_options integration enterprise
+        sources categories include_domains exclude_domains limit tbs location country
+        ignore_invalid_urls timeout highlights scrape_options integration enterprise
       ].freeze
 
       attr_reader(*FIELDS)
@@ -24,8 +24,10 @@ module Firecrawl
           "limit" => limit,
           "tbs" => tbs,
           "location" => location,
+          "country" => country,
           "ignoreInvalidURLs" => ignore_invalid_urls,
           "timeout" => timeout,
+          "highlights" => highlights,
           "scrapeOptions" => scrape_options&.to_h,
           "integration" => integration,
           # Enterprise search options. Use ["zdr"] for end-to-end Zero Data

data/lib/firecrawl/version.rb

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

data/lib/firecrawl.rb

@@ -4,9 +4,11 @@ require_relative "firecrawl/version"
 require_relative "firecrawl/errors"
 require_relative "firecrawl/http_client"
 require_relative "firecrawl/models/query_format"
+require_relative "firecrawl/models/pdf_parser"
 require_relative "firecrawl/models/product_profile"
 require_relative "firecrawl/models/menu_profile"
 require_relative "firecrawl/models/document"
+require_relative "firecrawl/models/audit_metadata"
 require_relative "firecrawl/models/scrape_options"
 require_relative "firecrawl/models/crawl_options"
 require_relative "firecrawl/models/crawl_response"
@@ -18,11 +20,20 @@ require_relative "firecrawl/models/map_options"
 require_relative "firecrawl/models/map_data"
 require_relative "firecrawl/models/search_options"
 require_relative "firecrawl/models/search_data"
+require_relative "firecrawl/models/developer_search_options"
+require_relative "firecrawl/models/developer_search_response"
 require_relative "firecrawl/models/parse_file"
 require_relative "firecrawl/models/parse_options"
+require_relative "firecrawl/models/parse_format"
+require_relative "firecrawl/models/agent_exchange_options"
 require_relative "firecrawl/models/agent_options"
 require_relative "firecrawl/models/agent_response"
+require_relative "firecrawl/models/agent_list_response"
+require_relative "firecrawl/models/agent_exchange_summary"
+require_relative "firecrawl/models/agent_pending_approval"
 require_relative "firecrawl/models/agent_status_response"
+require_relative "firecrawl/models/agent_trace_response"
+require_relative "firecrawl/models/agent_snapshot_response"
 require_relative "firecrawl/models/concurrency_check"
 require_relative "firecrawl/models/credit_usage"
 require_relative "firecrawl/models/monitor"

metadata

@@ -1,17 +1,18 @@
 --- !ruby/object:Gem::Specification
 name: firecrawl-sdk
 version: !ruby/object:Gem::Version
-  version: 1.10.0
+  version: 1.17.7
 platform: ruby
 authors:
 - Firecrawl
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-30 00:00:00.000000000 Z
+date: 2026-10-20 00:00:00.000000000 Z
 dependencies: []
-description: A type-safe Ruby client for the Firecrawl v2 API. Supports scraping,
-  crawling, batch scraping, URL mapping, web search, and AI agent operations.
+description: 'A type-safe Ruby client for the Firecrawl v2 API: search, scrape, parse,
+  crawl, map, and interact with the web, run batch scrapes, and run Agent and Monitor
+  jobs.'
 email:
 - hello@firecrawl.dev
 executables: []
@@ -24,9 +25,16 @@ files:
 - lib/firecrawl/client.rb
 - lib/firecrawl/errors.rb
 - lib/firecrawl/http_client.rb
+- lib/firecrawl/models/agent_exchange_options.rb
+- lib/firecrawl/models/agent_exchange_summary.rb
+- lib/firecrawl/models/agent_list_response.rb
 - lib/firecrawl/models/agent_options.rb
+- lib/firecrawl/models/agent_pending_approval.rb
 - lib/firecrawl/models/agent_response.rb
+- lib/firecrawl/models/agent_snapshot_response.rb
 - lib/firecrawl/models/agent_status_response.rb
+- lib/firecrawl/models/agent_trace_response.rb
+- lib/firecrawl/models/audit_metadata.rb
 - lib/firecrawl/models/batch_scrape_job.rb
 - lib/firecrawl/models/batch_scrape_options.rb
 - lib/firecrawl/models/batch_scrape_response.rb
@@ -35,13 +43,17 @@ files:
 - lib/firecrawl/models/crawl_options.rb
 - lib/firecrawl/models/crawl_response.rb
 - lib/firecrawl/models/credit_usage.rb
+- lib/firecrawl/models/developer_search_options.rb
+- lib/firecrawl/models/developer_search_response.rb
 - lib/firecrawl/models/document.rb
 - lib/firecrawl/models/map_data.rb
 - lib/firecrawl/models/map_options.rb
 - lib/firecrawl/models/menu_profile.rb
 - lib/firecrawl/models/monitor.rb
 - lib/firecrawl/models/parse_file.rb
+- lib/firecrawl/models/parse_format.rb
 - lib/firecrawl/models/parse_options.rb
+- lib/firecrawl/models/pdf_parser.rb
 - lib/firecrawl/models/product_profile.rb
 - lib/firecrawl/models/query_format.rb
 - lib/firecrawl/models/scrape_options.rb
@@ -74,5 +86,5 @@ requirements: []
 rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
-summary: Ruby SDK for the Firecrawl v2 web scraping API
+summary: Ruby SDK for Firecrawl, the context API for AI agents
 test_files: []