firecrawl-sdk 1.17.1 → 1.17.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e2b500556e1d7b0d222ae8937ae86dccdcf8c6499871c0202608a46b4611ef17
-  data.tar.gz: 2e4913c995ed97d8b55f295ab6adb0e61fe42cc0f08aff1f8aa12763f765b2be
+  metadata.gz: b19bf99b95d02f2cd346f1450cf9d897d7d0e1cf473454dbb242d46f96dc9620
+  data.tar.gz: '0911ec19579abe8d1f9221d2626538c82a0444a4502615b892887b556c571e2d'
 SHA512:
-  metadata.gz: d138c5083321098460e7ab5777201300ba0b1701f93361e97a27e0b87c88c9bd3163e56124d9b2da94536855a99e41522d13002c73379d1c67dd7bfb280b9624
-  data.tar.gz: 64e7178e770554abd242289756c2de70fcd3d76d2104002e36c2d8773065aa14f1e4ca161b60a72ed063da9fb4f5fa1a050d49f79809fbedf951ce2d481909fe
+  metadata.gz: 8992eb0b4b39bb40477a531026482ed83ad43d2b7649c5bc8c520b1ffdf5350e7026213e3bdec11274e51460e0e191a84aacf166d3c72a4c1a4b68e8a1c3c9cb
+  data.tar.gz: '09e58c68ae722cf65e2130dabe424f78c29dfa51b805d04bbbecc8fce13730099e83b27ae14f7f63d7a45b703ba64fb30700a1195ee7dc480521c6ffc7ca0fa4'

data/README.md

@@ -203,6 +203,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

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_options.rb

@@ -6,10 +6,14 @@ module Firecrawl
     #
     # 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 effort webhook audit_metadata
+        thread_id mode exchange
       ].freeze
 
       attr_reader(*FIELDS)
@@ -34,6 +38,9 @@ module Firecrawl
           "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_status_response.rb

@@ -4,7 +4,9 @@ module Firecrawl
   module Models
     # Status response for monitoring agent tasks.
     class AgentStatusResponse
-      attr_reader :status, :data, :credits_used, :expires_at, :effort
+      attr_reader :status, :data, :credits_used, :expires_at, :effort,
+                  :thread_id, :thread_turn, :mode, :message, :pending_approval,
+                  :exchange
 
       def initialize(raw)
         @status = raw["status"]
@@ -13,6 +15,13 @@ module Firecrawl
         @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/version.rb

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

data/lib/firecrawl.rb

@@ -23,9 +23,12 @@ require_relative "firecrawl/models/search_data"
 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"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: firecrawl-sdk
 version: !ruby/object:Gem::Version
-  version: 1.17.1
+  version: 1.17.4
 platform: ruby
 authors:
 - Firecrawl
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-02 00:00:00.000000000 Z
+date: 2026-10-07 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.
@@ -24,8 +24,11 @@ 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