firecrawl-sdk 1.3.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 925d1d1e2e21f65f6ff043a07d8689f5e29b41d72b1b8791334af47d76153819
-  data.tar.gz: 8e70053a8eabd4d2ff100386c4bb7c4fd2bea7ec119dedf2151d21c404e41e31
+  metadata.gz: 60a3360b0facad41a4d3c0a1a94e520f675ce5b6f72487665ead37f1b988de50
+  data.tar.gz: 51ced5462346c81d02327786e5022cd5789fed14940346e231c8619eb5b686b6
 SHA512:
-  metadata.gz: ce98788dd3a379d575f97962b597224115463b28adf19870b0820c2a6e60c4fa44ce4b58d039843022e38d0027254e8808f3704552bc401994497c040f752233
-  data.tar.gz: 7349d8f5d5a63d54364b7b1c1afef54b0d16930d6b107b97bb3ba933fc404ec45559ec8ab4a0e0551f142c108fb70e24ea30bfecf2562d01e0b182163e0e9eea
+  metadata.gz: 2e7a56e1fc2bd3b56b88337047f7c655c7ac78e6d43de94f4ee89c9b67701be95b45232d17ce6383023bd3d59199388012257c32d36c10c61823b02f5574f931
+  data.tar.gz: f2be762f47550bfa3bda7e7d8e7833b404b30d5447558893bc36ffe5de13953cc02bc00efe09d51f91eec9c1715701275e50336d154d2c47f4d5121a424aeb87

data/lib/firecrawl/client.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "json"
+require "uri"
 
 module Firecrawl
   # Client for the Firecrawl v2 API.
@@ -280,6 +281,83 @@ module Firecrawl
       Models::MapData.new(data)
     end
 
+    # ================================================================
+    # MONITOR
+    # ================================================================
+
+    def create_monitor(name:, schedule:, targets:, webhook: nil, notification: nil, retention_days: nil)
+      body = {
+        "name" => name,
+        "schedule" => schedule,
+        "targets" => targets,
+        "webhook" => webhook,
+        "notification" => notification,
+        "retentionDays" => retention_days,
+      }.compact
+      raw = @http.post("/v2/monitor", body)
+      Models::Monitor.new(raw["data"] || raw)
+    end
+
+    def list_monitors(limit: nil, offset: nil)
+      raw = @http.get("/v2/monitor#{query(limit: limit, offset: offset)}")
+      (raw["data"] || []).map { |item| Models::Monitor.new(item) }
+    end
+
+    def get_monitor(monitor_id)
+      raise ArgumentError, "Monitor ID is required" if monitor_id.nil?
+
+      raw = @http.get("/v2/monitor/#{monitor_id}")
+      Models::Monitor.new(raw["data"] || raw)
+    end
+
+    def update_monitor(monitor_id, **attrs)
+      raise ArgumentError, "Monitor ID is required" if monitor_id.nil?
+
+      body = {
+        "name" => attrs[:name],
+        "status" => attrs[:status],
+        "schedule" => attrs[:schedule],
+        "webhook" => attrs[:webhook],
+        "notification" => attrs[:notification],
+        "targets" => attrs[:targets],
+        "retentionDays" => attrs[:retention_days],
+      }.compact
+      raw = @http.patch("/v2/monitor/#{monitor_id}", body)
+      Models::Monitor.new(raw["data"] || raw)
+    end
+
+    def delete_monitor(monitor_id)
+      raise ArgumentError, "Monitor ID is required" if monitor_id.nil?
+
+      @http.delete("/v2/monitor/#{monitor_id}")["success"] == true
+    end
+
+    def run_monitor(monitor_id)
+      raise ArgumentError, "Monitor ID is required" if monitor_id.nil?
+
+      raw = @http.post("/v2/monitor/#{monitor_id}/run", {})
+      Models::MonitorCheck.new(raw["data"] || raw)
+    end
+
+    def list_monitor_checks(monitor_id, limit: nil, offset: nil)
+      raise ArgumentError, "Monitor ID is required" if monitor_id.nil?
+
+      raw = @http.get("/v2/monitor/#{monitor_id}/checks#{query(limit: limit, offset: offset)}")
+      (raw["data"] || []).map { |item| Models::MonitorCheck.new(item) }
+    end
+
+    def get_monitor_check(monitor_id, check_id, limit: nil, skip: nil, status: nil, auto_paginate: true)
+      raise ArgumentError, "Monitor ID is required" if monitor_id.nil?
+      raise ArgumentError, "Check ID is required" if check_id.nil?
+
+      params = query(limit: limit, skip: skip, status: status)
+      raw = @http.get("/v2/monitor/#{monitor_id}/checks/#{check_id}#{params}")
+      data = raw["data"] || raw
+      data["next"] = raw["next"] if raw["next"]
+      check = Models::MonitorCheckDetail.new(data)
+      auto_paginate ? paginate_monitor_check(check) : check
+    end
+
     # ================================================================
     # SEARCH
     # ================================================================
@@ -378,6 +456,11 @@ module Firecrawl
 
     private
 
+    def query(**params)
+      compact = params.compact
+      compact.empty? ? "" : "?#{URI.encode_www_form(compact)}"
+    end
+
     def poll_crawl(job_id, poll_interval, timeout)
       deadline = Time.now + timeout
       while Time.now < deadline
@@ -423,5 +506,20 @@ module Firecrawl
       end
       job
     end
+
+    def paginate_monitor_check(check)
+      check.pages ||= []
+      current = check
+      while current.next_url && !current.next_url.empty?
+        raw = @http.get_absolute(current.next_url)
+        data = raw["data"] || raw
+        data["next"] = raw["next"] if raw["next"]
+        next_page = Models::MonitorCheckDetail.new(data)
+        check.pages.concat(next_page.pages) unless next_page.pages.empty?
+        current = next_page
+      end
+      check.next_url = nil
+      check
+    end
   end
 end

data/lib/firecrawl/http_client.rb

@@ -59,6 +59,16 @@ module Firecrawl
       execute_with_retry(uri, request)
     end
 
+    # Sends a PATCH request with JSON body.
+    def patch(path, body)
+      uri = URI("#{@base_url}#{path}")
+      request = Net::HTTP::Patch.new(uri)
+      request["Authorization"] = "Bearer #{@api_key}"
+      request["Content-Type"] = "application/json"
+      request.body = JSON.generate(body)
+      execute_with_retry(uri, request)
+    end
+
     # Sends a POST request with a multipart/form-data body.
     #
     # @param path [String] API path

data/lib/firecrawl/models/monitor.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Firecrawl
+  module Models
+    class Monitor
+      attr_reader :id, :name, :status, :schedule, :next_run_at, :last_run_at,
+                  :current_check_id, :targets, :webhook, :notification,
+                  :retention_days, :estimated_credits_per_month,
+                  :last_check_summary, :created_at, :updated_at
+
+      def initialize(data)
+        @id = data["id"]
+        @name = data["name"]
+        @status = data["status"]
+        @schedule = data["schedule"]
+        @next_run_at = data["nextRunAt"]
+        @last_run_at = data["lastRunAt"]
+        @current_check_id = data["currentCheckId"]
+        @targets = data["targets"] || []
+        @webhook = data["webhook"]
+        @notification = data["notification"]
+        @retention_days = data["retentionDays"]
+        @estimated_credits_per_month = data["estimatedCreditsPerMonth"]
+        @last_check_summary = data["lastCheckSummary"]
+        @created_at = data["createdAt"]
+        @updated_at = data["updatedAt"]
+      end
+    end
+
+    class MonitorCheck
+      attr_reader :id, :monitor_id, :status, :trigger, :scheduled_for,
+                  :started_at, :finished_at, :estimated_credits,
+                  :reserved_credits, :actual_credits, :billing_status,
+                  :summary, :target_results, :notification_status, :error,
+                  :created_at, :updated_at
+
+      def initialize(data)
+        @id = data["id"]
+        @monitor_id = data["monitorId"]
+        @status = data["status"]
+        @trigger = data["trigger"]
+        @scheduled_for = data["scheduledFor"]
+        @started_at = data["startedAt"]
+        @finished_at = data["finishedAt"]
+        @estimated_credits = data["estimatedCredits"]
+        @reserved_credits = data["reservedCredits"]
+        @actual_credits = data["actualCredits"]
+        @billing_status = data["billingStatus"]
+        @summary = data["summary"] || {}
+        @target_results = data["targetResults"]
+        @notification_status = data["notificationStatus"]
+        @error = data["error"]
+        @created_at = data["createdAt"]
+        @updated_at = data["updatedAt"]
+      end
+    end
+
+    class MonitorCheckDetail < MonitorCheck
+      attr_accessor :pages, :next_url
+
+      def initialize(data)
+        super
+        @pages = data["pages"] || []
+        @next_url = data["next"]
+      end
+    end
+  end
+end

data/lib/firecrawl/models/parse_options.rb

@@ -26,7 +26,7 @@ module Firecrawl
 
       def to_h
         {
-          "formats" => formats,
+          "formats" => formats&.map { |fmt| format_value(fmt) },
           "headers" => headers,
           "includeTags" => include_tags,
           "excludeTags" => exclude_tags,
@@ -69,6 +69,10 @@ module Firecrawl
           fmt.respond_to?(:type) ? fmt.type : nil
         end
       end
+
+      def format_value(fmt)
+        fmt.respond_to?(:to_h) ? fmt.to_h : fmt
+      end
     end
   end
 end

data/lib/firecrawl/models/query_format.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Firecrawl
+  module Models
+    # Query format for asking a question about page content.
+    class QueryFormat
+      MODE_FREEFORM = "freeform"
+      MODE_DIRECT_QUOTE = "directQuote"
+
+      attr_reader :prompt, :mode
+
+      def initialize(prompt:, mode: nil)
+        unless mode.nil? || [MODE_FREEFORM, MODE_DIRECT_QUOTE].include?(mode)
+          raise ArgumentError, "query mode must be 'freeform' or 'directQuote'"
+        end
+
+        @prompt = prompt
+        @mode = mode
+      end
+
+      def to_h
+        {
+          "type" => "query",
+          "prompt" => prompt,
+          "mode" => mode,
+        }.compact
+      end
+
+      def type
+        "query"
+      end
+    end
+  end
+end

data/lib/firecrawl/models/scrape_options.rb

@@ -20,7 +20,7 @@ module Firecrawl
 
       def to_h
         {
-          "formats" => formats,
+          "formats" => formats&.map { |fmt| format_value(fmt) },
           "headers" => headers,
           "includeTags" => include_tags,
           "excludeTags" => exclude_tags,
@@ -41,6 +41,12 @@ module Firecrawl
           "integration" => integration,
         }.compact
       end
+
+      private
+
+      def format_value(fmt)
+        fmt.respond_to?(:to_h) ? fmt.to_h : fmt
+      end
     end
   end
 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 limit tbs location ignore_invalid_urls
-        timeout scrape_options integration
+        sources categories include_domains exclude_domains limit tbs location
+        ignore_invalid_urls timeout scrape_options integration
       ].freeze
 
       attr_reader(*FIELDS)
@@ -19,6 +19,8 @@ module Firecrawl
         {
           "sources" => sources,
           "categories" => categories,
+          "includeDomains" => include_domains,
+          "excludeDomains" => exclude_domains,
           "limit" => limit,
           "tbs" => tbs,
           "location" => location,

data/lib/firecrawl/version.rb

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

data/lib/firecrawl.rb

@@ -3,6 +3,7 @@
 require_relative "firecrawl/version"
 require_relative "firecrawl/errors"
 require_relative "firecrawl/http_client"
+require_relative "firecrawl/models/query_format"
 require_relative "firecrawl/models/document"
 require_relative "firecrawl/models/scrape_options"
 require_relative "firecrawl/models/crawl_options"
@@ -22,4 +23,5 @@ 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/models/monitor"
 require_relative "firecrawl/client"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: firecrawl-sdk
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 1.4.0
 platform: ruby
 authors:
 - Firecrawl
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-30 00:00:00.000000000 Z
+date: 2026-05-06 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.
@@ -38,8 +38,10 @@ files:
 - lib/firecrawl/models/document.rb
 - lib/firecrawl/models/map_data.rb
 - lib/firecrawl/models/map_options.rb
+- lib/firecrawl/models/monitor.rb
 - lib/firecrawl/models/parse_file.rb
 - lib/firecrawl/models/parse_options.rb
+- lib/firecrawl/models/query_format.rb
 - lib/firecrawl/models/scrape_options.rb
 - lib/firecrawl/models/search_data.rb
 - lib/firecrawl/models/search_options.rb