context.dev 2.2.0 → 2.4.0

data/lib/context_dev/resources/parse.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module ContextDev
+  module Resources
+    class Parse
+      # Some parameter documentations has been truncated, see
+      # {ContextDev::Models::ParseHandleParams} for more details.
+      #
+      # Converts raw text, source code, web/data, PDF, Microsoft Office, and image bytes
+      # into LLM-usable Markdown. The base request costs 1 credit. When OCR runs
+      # (requires ocr=true), the entire call costs 5 credits; ocr=true requests where no
+      # OCR ends up running still cost 1 credit.
+      #
+      # @overload handle(body:, extension: nil, include_images: nil, include_links: nil, ocr: nil, pdf: nil, shorten_base64_images: nil, use_main_content_only: nil, request_options: {})
+      #
+      # @param body [Pathname, StringIO, IO, String, ContextDev::FilePart] Body param
+      #
+      # @param extension [Symbol, ContextDev::Models::ParseHandleParams::Extension] Query param: Optional file extension hint. Case-insensitive; a leading dot is ac
+      #
+      # @param include_images [Boolean] Query param: Include image references in Markdown output
+      #
+      # @param include_links [Boolean] Query param: Preserve hyperlinks in Markdown output
+      #
+      # @param ocr [Boolean] Query param: Gates all OCR. When true, PDFs get embedded-image OCR (recognized t
+      #
+      # @param pdf [ContextDev::Models::ParseHandleParams::Pdf] Query param: PDF page-range controls. Use start/end to limit parsing (and OCR wh
+      #
+      # @param shorten_base64_images [Boolean] Query param: Shorten base64-encoded image data in the Markdown output
+      #
+      # @param use_main_content_only [Boolean] Query param: Extract only the main content from HTML-like inputs
+      #
+      # @param request_options [ContextDev::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [ContextDev::Models::ParseHandleResponse]
+      #
+      # @see ContextDev::Models::ParseHandleParams
+      def handle(params)
+        parsed, options = ContextDev::ParseHandleParams.dump_request(params)
+        query = ContextDev::Internal::Util.encode_query_params(parsed.except(:body))
+        @client.request(
+          method: :post,
+          path: "parse",
+          query: query,
+          headers: {"content-type" => "application/octet-stream"},
+          body: parsed[:body],
+          model: ContextDev::Models::ParseHandleResponse,
+          options: options
+        )
+      end
+
+      # @api private
+      #
+      # @param client [ContextDev::Client]
+      def initialize(client:)
+        @client = client
+      end
+    end
+  end
+end

data/lib/context_dev/resources/web.rb

@@ -289,7 +289,7 @@ module ContextDev
       #
       # @param max_pages [Integer] Maximum number of pages to crawl. Hard cap: 500.
       #
-      # @param pdf [ContextDev::Models::WebWebCrawlMdParams::Pdf] PDF parsing controls. Use start/end to limit text extraction and OCR to an inclu
+      # @param pdf [ContextDev::Models::WebWebCrawlMdParams::Pdf] PDF parsing controls. Use start/end to limit text extraction and embedded-image
       #
       # @param settle_animations [Boolean] When true, waits briefly for CSS and transition animations to settle before extr
       #
@@ -342,7 +342,7 @@ module ContextDev
       #
       # @param max_age_ms [Integer] Return a cached result if a prior scrape for the same parameters exists and is y
       #
-      # @param pdf [ContextDev::Models::WebWebScrapeHTMLParams::Pdf] PDF parsing controls. Use start/end to limit text extraction and OCR to an inclu
+      # @param pdf [ContextDev::Models::WebWebScrapeHTMLParams::Pdf] PDF parsing controls. Use start/end to limit text extraction and embedded-image
       #
       # @param settle_animations [Boolean] When true, waits briefly for CSS and transition animations to settle before extr
       #
@@ -426,7 +426,22 @@ module ContextDev
       # Some parameter documentations has been truncated, see
       # {ContextDev::Models::WebWebScrapeMdParams} for more details.
       #
-      # Scrapes the given URL into LLM usable Markdown.
+      # Scrapes the given URL into LLM usable Markdown. Inspect key_metadata on JSON
+      # responses from a recognized API key; use error_code to distinguish stable
+      # failure categories.
+      #
+      # ### Billing & errors
+      #
+      # | HTTP status | Billed?        | Meaning                                                                                  |
+      # | ----------- | -------------- | ---------------------------------------------------------------------------------------- |
+      # | 200         | Yes — 1 credit | Successful scrape, including a zero-length result when includeSelectors matched nothing  |
+      # | 400         | No             | Invalid input, skipped PDF, or the page could not be scraped                             |
+      # | 401 / 403   | No             | Invalid/disabled key, insufficient permissions, or credits exhausted; inspect error_code |
+      # | 404         | No             | Target page returned or fingerprinted as not found                                       |
+      # | 408         | No             | Request timed out                                                                        |
+      # | 415         | No             | Unsupported content type                                                                 |
+      # | 429         | No             | Per-minute rate limit exceeded; honor Retry-After                                        |
+      # | 500         | No             | Internal error                                                                           |
       #
       # @overload web_scrape_md(url:, country: nil, exclude_selectors: nil, headers: nil, include_frames: nil, include_images: nil, include_links: nil, include_selectors: nil, max_age_ms: nil, pdf: nil, settle_animations: nil, shorten_base64_images: nil, timeout_ms: nil, use_main_content_only: nil, wait_for_ms: nil, request_options: {})
       #
@@ -448,7 +463,7 @@ module ContextDev
       #
       # @param max_age_ms [Integer] Return a cached result if a prior scrape for the same parameters exists and is y
       #
-      # @param pdf [ContextDev::Models::WebWebScrapeMdParams::Pdf] PDF parsing controls. Use start/end to limit text extraction and OCR to an inclu
+      # @param pdf [ContextDev::Models::WebWebScrapeMdParams::Pdf] PDF parsing controls. Use start/end to limit text extraction and embedded-image
       #
       # @param settle_animations [Boolean] When true, waits briefly for CSS and transition animations to settle before conv
       #

data/lib/context_dev/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ContextDev
-  VERSION = "2.2.0"
+  VERSION = "2.4.0"
 end

data/lib/context_dev.rb

@@ -86,6 +86,8 @@ require_relative "context_dev/models/monitor_run_params"
 require_relative "context_dev/models/monitor_run_response"
 require_relative "context_dev/models/monitor_update_params"
 require_relative "context_dev/models/monitor_update_response"
+require_relative "context_dev/models/parse_handle_params"
+require_relative "context_dev/models/parse_handle_response"
 require_relative "context_dev/models/utility_prefetch_params"
 require_relative "context_dev/models/utility_prefetch_response"
 require_relative "context_dev/models/web_extract_competitors_params"
@@ -96,6 +98,7 @@ require_relative "context_dev/models/web_extract_params"
 require_relative "context_dev/models/web_extract_response"
 require_relative "context_dev/models/web_extract_styleguide_params"
 require_relative "context_dev/models/web_extract_styleguide_response"
+require_relative "context_dev/models/webhook_delivery"
 require_relative "context_dev/models/web_screenshot_params"
 require_relative "context_dev/models/web_screenshot_response"
 require_relative "context_dev/models/web_search_params"
@@ -115,5 +118,6 @@ require_relative "context_dev/resources/ai"
 require_relative "context_dev/resources/brand"
 require_relative "context_dev/resources/industry"
 require_relative "context_dev/resources/monitors"
+require_relative "context_dev/resources/parse"
 require_relative "context_dev/resources/utility"
 require_relative "context_dev/resources/web"

data/rbi/context_dev/client.rbi

@@ -13,6 +13,9 @@ module ContextDev
     sig { returns(String) }
     attr_reader :api_key
 
+    sig { returns(ContextDev::Resources::Parse) }
+    attr_reader :parse
+
     sig { returns(ContextDev::Resources::Web) }
     attr_reader :web
 
@@ -29,8 +32,9 @@ module ContextDev
     attr_reader :utility
 
     # Monitor pages, sitemaps, and extracted website data for exact or semantic
-    # changes. The change.detected webhook payload is documented by the
-    # MonitorsChangeDetectedWebhookPayload schema.
+    # changes. Webhook payloads are documented by the
+    # MonitorsChangeDetectedWebhookPayload and MonitorsRunCompletedWebhookPayload
+    # schemas.
     sig { returns(ContextDev::Resources::Monitors) }
     attr_reader :monitors
 

data/rbi/context_dev/models/monitor_create_params.rbi

@@ -631,20 +631,100 @@ module ContextDev
             )
           end
 
-        # Webhook URL called when a change is detected.
+        # Webhook URL events are delivered to.
         sig { returns(String) }
         attr_accessor :url
 
-        sig { params(url: String).returns(T.attached_class) }
+        # Events delivered to this endpoint. `change.detected` fires only when a run
+        # detects a change; `run.completed` fires on every completed run — including runs
+        # that detected no change — and embeds the change when one was detected. Defaults
+        # to `["change.detected"]` when omitted.
+        sig do
+          returns(
+            T.nilable(
+              T::Array[
+                ContextDev::MonitorCreateParams::Webhook::Event::OrSymbol
+              ]
+            )
+          )
+        end
+        attr_reader :events
+
+        sig do
+          params(
+            events:
+              T::Array[
+                ContextDev::MonitorCreateParams::Webhook::Event::OrSymbol
+              ]
+          ).void
+        end
+        attr_writer :events
+
+        sig do
+          params(
+            url: String,
+            events:
+              T::Array[
+                ContextDev::MonitorCreateParams::Webhook::Event::OrSymbol
+              ]
+          ).returns(T.attached_class)
+        end
         def self.new(
-          # Webhook URL called when a change is detected.
-          url:
+          # Webhook URL events are delivered to.
+          url:,
+          # Events delivered to this endpoint. `change.detected` fires only when a run
+          # detects a change; `run.completed` fires on every completed run — including runs
+          # that detected no change — and embeds the change when one was detected. Defaults
+          # to `["change.detected"]` when omitted.
+          events: nil
         )
         end
 
-        sig { override.returns({ url: String, secret: String }) }
+        sig do
+          override.returns(
+            {
+              url: String,
+              events:
+                T::Array[
+                  ContextDev::MonitorCreateParams::Webhook::Event::OrSymbol
+                ],
+              secret: String
+            }
+          )
+        end
         def to_hash
         end
+
+        module Event
+          extend ContextDev::Internal::Type::Enum
+
+          TaggedSymbol =
+            T.type_alias do
+              T.all(Symbol, ContextDev::MonitorCreateParams::Webhook::Event)
+            end
+          OrSymbol = T.type_alias { T.any(Symbol, String) }
+
+          CHANGE_DETECTED =
+            T.let(
+              :"change.detected",
+              ContextDev::MonitorCreateParams::Webhook::Event::TaggedSymbol
+            )
+          RUN_COMPLETED =
+            T.let(
+              :"run.completed",
+              ContextDev::MonitorCreateParams::Webhook::Event::TaggedSymbol
+            )
+
+          sig do
+            override.returns(
+              T::Array[
+                ContextDev::MonitorCreateParams::Webhook::Event::TaggedSymbol
+              ]
+            )
+          end
+          def self.values
+          end
+        end
       end
     end
   end

data/rbi/context_dev/models/monitor_create_response.rbi

@@ -128,6 +128,26 @@ module ContextDev
       end
       attr_writer :webhook
 
+      # Present while webhook deliveries are failing consecutively; null when deliveries
+      # are healthy or no webhook is configured. Cleared on the next successful delivery
+      # and when the webhook URL changes.
+      sig do
+        returns(
+          T.nilable(ContextDev::Models::MonitorCreateResponse::WebhookFailure)
+        )
+      end
+      attr_reader :webhook_failure
+
+      sig do
+        params(
+          webhook_failure:
+            T.nilable(
+              ContextDev::Models::MonitorCreateResponse::WebhookFailure::OrHash
+            )
+        ).void
+      end
+      attr_writer :webhook_failure
+
       # A web monitor. `mode` is the constant `web`; behavior is described by `target`
       # (page/sitemap/extract) and `change_detection` (exact/semantic).
       sig do
@@ -169,6 +189,10 @@ module ContextDev
           webhook:
             T.nilable(
               ContextDev::Models::MonitorCreateResponse::Webhook::OrHash
+            ),
+          webhook_failure:
+            T.nilable(
+              ContextDev::Models::MonitorCreateResponse::WebhookFailure::OrHash
             )
         ).returns(T.attached_class)
       end
@@ -207,7 +231,11 @@ module ContextDev
         next_run_at: nil,
         # User-defined tags for grouping and filtering monitors and their changes.
         tags: nil,
-        webhook: nil
+        webhook: nil,
+        # Present while webhook deliveries are failing consecutively; null when deliveries
+        # are healthy or no webhook is configured. Cleared on the next successful delivery
+        # and when the webhook URL changes.
+        webhook_failure: nil
       )
       end
 
@@ -236,7 +264,11 @@ module ContextDev
             next_run_at: T.nilable(Time),
             tags: T::Array[String],
             webhook:
-              T.nilable(ContextDev::Models::MonitorCreateResponse::Webhook)
+              T.nilable(ContextDev::Models::MonitorCreateResponse::Webhook),
+            webhook_failure:
+              T.nilable(
+                ContextDev::Models::MonitorCreateResponse::WebhookFailure
+              )
           }
         )
       end
@@ -993,10 +1025,35 @@ module ContextDev
             )
           end
 
-        # Webhook URL called when a change is detected.
+        # Webhook URL events are delivered to.
         sig { returns(String) }
         attr_accessor :url
 
+        # Events delivered to this endpoint. `change.detected` fires only when a run
+        # detects a change; `run.completed` fires on every completed run — including runs
+        # that detected no change — and embeds the change when one was detected. Defaults
+        # to `["change.detected"]` when omitted.
+        sig do
+          returns(
+            T.nilable(
+              T::Array[
+                ContextDev::Models::MonitorCreateResponse::Webhook::Event::TaggedSymbol
+              ]
+            )
+          )
+        end
+        attr_reader :events
+
+        sig do
+          params(
+            events:
+              T::Array[
+                ContextDev::Models::MonitorCreateResponse::Webhook::Event::OrSymbol
+              ]
+          ).void
+        end
+        attr_writer :events
+
         # Signing secret used to verify webhook authenticity. Each delivery includes an
         # `X-Context-Signature: t=<unix>,v1=<hmac>` header, where the HMAC is SHA-256 over
         # `"{t}.{rawRequestBody}"` keyed by this secret. Recompute it with a constant-time
@@ -1008,10 +1065,24 @@ module ContextDev
         sig { params(secret: String).void }
         attr_writer :secret
 
-        sig { params(url: String, secret: String).returns(T.attached_class) }
+        sig do
+          params(
+            url: String,
+            events:
+              T::Array[
+                ContextDev::Models::MonitorCreateResponse::Webhook::Event::OrSymbol
+              ],
+            secret: String
+          ).returns(T.attached_class)
+        end
         def self.new(
-          # Webhook URL called when a change is detected.
+          # Webhook URL events are delivered to.
           url:,
+          # Events delivered to this endpoint. `change.detected` fires only when a run
+          # detects a change; `run.completed` fires on every completed run — including runs
+          # that detected no change — and embeds the change when one was detected. Defaults
+          # to `["change.detected"]` when omitted.
+          events: nil,
           # Signing secret used to verify webhook authenticity. Each delivery includes an
           # `X-Context-Signature: t=<unix>,v1=<hmac>` header, where the HMAC is SHA-256 over
           # `"{t}.{rawRequestBody}"` keyed by this secret. Recompute it with a constant-time
@@ -1021,9 +1092,166 @@ module ContextDev
         )
         end
 
-        sig { override.returns({ url: String, secret: String }) }
+        sig do
+          override.returns(
+            {
+              url: String,
+              events:
+                T::Array[
+                  ContextDev::Models::MonitorCreateResponse::Webhook::Event::TaggedSymbol
+                ],
+              secret: String
+            }
+          )
+        end
+        def to_hash
+        end
+
+        module Event
+          extend ContextDev::Internal::Type::Enum
+
+          TaggedSymbol =
+            T.type_alias do
+              T.all(
+                Symbol,
+                ContextDev::Models::MonitorCreateResponse::Webhook::Event
+              )
+            end
+          OrSymbol = T.type_alias { T.any(Symbol, String) }
+
+          CHANGE_DETECTED =
+            T.let(
+              :"change.detected",
+              ContextDev::Models::MonitorCreateResponse::Webhook::Event::TaggedSymbol
+            )
+          RUN_COMPLETED =
+            T.let(
+              :"run.completed",
+              ContextDev::Models::MonitorCreateResponse::Webhook::Event::TaggedSymbol
+            )
+
+          sig do
+            override.returns(
+              T::Array[
+                ContextDev::Models::MonitorCreateResponse::Webhook::Event::TaggedSymbol
+              ]
+            )
+          end
+          def self.values
+          end
+        end
+      end
+
+      class WebhookFailure < ContextDev::Internal::Type::BaseModel
+        OrHash =
+          T.type_alias do
+            T.any(
+              ContextDev::Models::MonitorCreateResponse::WebhookFailure,
+              ContextDev::Internal::AnyHash
+            )
+          end
+
+        # Number of consecutive delivery attempts that did not succeed.
+        sig { returns(Integer) }
+        attr_accessor :consecutive_failures
+
+        sig { returns(Time) }
+        attr_accessor :last_failed_at
+
+        # Human-readable description of the most recent failure.
+        sig { returns(String) }
+        attr_accessor :last_message
+
+        # Outcome of the most recent failed delivery. rejected means a non-2xx response;
+        # failed means no HTTP response was received; skipped_unsafe_url means the URL
+        # failed the public-endpoint safety check.
+        sig do
+          returns(
+            ContextDev::Models::MonitorCreateResponse::WebhookFailure::LastStatus::TaggedSymbol
+          )
+        end
+        attr_accessor :last_status
+
+        # Present while webhook deliveries are failing consecutively; null when deliveries
+        # are healthy or no webhook is configured. Cleared on the next successful delivery
+        # and when the webhook URL changes.
+        sig do
+          params(
+            consecutive_failures: Integer,
+            last_failed_at: Time,
+            last_message: String,
+            last_status:
+              ContextDev::Models::MonitorCreateResponse::WebhookFailure::LastStatus::OrSymbol
+          ).returns(T.attached_class)
+        end
+        def self.new(
+          # Number of consecutive delivery attempts that did not succeed.
+          consecutive_failures:,
+          last_failed_at:,
+          # Human-readable description of the most recent failure.
+          last_message:,
+          # Outcome of the most recent failed delivery. rejected means a non-2xx response;
+          # failed means no HTTP response was received; skipped_unsafe_url means the URL
+          # failed the public-endpoint safety check.
+          last_status:
+        )
+        end
+
+        sig do
+          override.returns(
+            {
+              consecutive_failures: Integer,
+              last_failed_at: Time,
+              last_message: String,
+              last_status:
+                ContextDev::Models::MonitorCreateResponse::WebhookFailure::LastStatus::TaggedSymbol
+            }
+          )
+        end
         def to_hash
         end
+
+        # Outcome of the most recent failed delivery. rejected means a non-2xx response;
+        # failed means no HTTP response was received; skipped_unsafe_url means the URL
+        # failed the public-endpoint safety check.
+        module LastStatus
+          extend ContextDev::Internal::Type::Enum
+
+          TaggedSymbol =
+            T.type_alias do
+              T.all(
+                Symbol,
+                ContextDev::Models::MonitorCreateResponse::WebhookFailure::LastStatus
+              )
+            end
+          OrSymbol = T.type_alias { T.any(Symbol, String) }
+
+          REJECTED =
+            T.let(
+              :rejected,
+              ContextDev::Models::MonitorCreateResponse::WebhookFailure::LastStatus::TaggedSymbol
+            )
+          FAILED =
+            T.let(
+              :failed,
+              ContextDev::Models::MonitorCreateResponse::WebhookFailure::LastStatus::TaggedSymbol
+            )
+          SKIPPED_UNSAFE_URL =
+            T.let(
+              :skipped_unsafe_url,
+              ContextDev::Models::MonitorCreateResponse::WebhookFailure::LastStatus::TaggedSymbol
+            )
+
+          sig do
+            override.returns(
+              T::Array[
+                ContextDev::Models::MonitorCreateResponse::WebhookFailure::LastStatus::TaggedSymbol
+              ]
+            )
+          end
+          def self.values
+          end
+        end
       end
     end
   end