context.dev 2.1.0 → 2.3.0

data/lib/context_dev/models/webhook_delivery.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module ContextDev
+  module Models
+    class WebhookDelivery < ContextDev::Internal::Type::BaseModel
+      # @!attribute attempted_at
+      #
+      #   @return [Time]
+      required :attempted_at, Time
+
+      # @!attribute error
+      #
+      #   @return [ContextDev::Models::WebhookDelivery::Error, nil]
+      required :error, -> { ContextDev::WebhookDelivery::Error }, nil?: true
+
+      # @!attribute event
+      #   The event this delivery carried. Deliveries recorded before event selection
+      #   existed report change.detected.
+      #
+      #   @return [Symbol, ContextDev::Models::WebhookDelivery::Event]
+      required :event, enum: -> { ContextDev::WebhookDelivery::Event }
+
+      # @!attribute event_id
+      #   Identifier sent in the X-Context-Id header.
+      #
+      #   @return [String]
+      required :event_id, String
+
+      # @!attribute http_status
+      #   The endpoint's final HTTP response status, or null when no response was
+      #   received.
+      #
+      #   @return [Integer, nil]
+      required :http_status, Integer, nil?: true
+
+      # @!attribute status
+      #   Delivery outcome. delivered means any 2xx response; 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.
+      #
+      #   @return [Symbol, ContextDev::Models::WebhookDelivery::Status]
+      required :status, enum: -> { ContextDev::WebhookDelivery::Status }
+
+      # @!method initialize(attempted_at:, error:, event:, event_id:, http_status:, status:)
+      #   Some parameter documentations has been truncated, see
+      #   {ContextDev::Models::WebhookDelivery} for more details.
+      #
+      #   @param attempted_at [Time]
+      #
+      #   @param error [ContextDev::Models::WebhookDelivery::Error, nil]
+      #
+      #   @param event [Symbol, ContextDev::Models::WebhookDelivery::Event] The event this delivery carried. Deliveries recorded before event selection exis
+      #
+      #   @param event_id [String] Identifier sent in the X-Context-Id header.
+      #
+      #   @param http_status [Integer, nil] The endpoint's final HTTP response status, or null when no response was received
+      #
+      #   @param status [Symbol, ContextDev::Models::WebhookDelivery::Status] Delivery outcome. delivered means any 2xx response; rejected means a non-2xx res
+
+      # @see ContextDev::Models::WebhookDelivery#error
+      class Error < ContextDev::Internal::Type::BaseModel
+        # @!attribute code
+        #
+        #   @return [String]
+        required :code, String
+
+        # @!attribute message
+        #
+        #   @return [String]
+        required :message, String
+
+        # @!method initialize(code:, message:)
+        #   @param code [String]
+        #   @param message [String]
+      end
+
+      # The event this delivery carried. Deliveries recorded before event selection
+      # existed report change.detected.
+      #
+      # @see ContextDev::Models::WebhookDelivery#event
+      module Event
+        extend ContextDev::Internal::Type::Enum
+
+        CHANGE_DETECTED = :"change.detected"
+        RUN_COMPLETED = :"run.completed"
+
+        # @!method self.values
+        #   @return [Array<Symbol>]
+      end
+
+      # Delivery outcome. delivered means any 2xx response; 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.
+      #
+      # @see ContextDev::Models::WebhookDelivery#status
+      module Status
+        extend ContextDev::Internal::Type::Enum
+
+        DELIVERED = :delivered
+        REJECTED = :rejected
+        FAILED = :failed
+        SKIPPED_UNSAFE_URL = :skipped_unsafe_url
+
+        # @!method self.values
+        #   @return [Array<Symbol>]
+      end
+    end
+  end
+end

data/lib/context_dev/models.rb

@@ -73,6 +73,8 @@ module ContextDev
 
   MonitorUpdateParams = ContextDev::Models::MonitorUpdateParams
 
+  ParseHandleParams = ContextDev::Models::ParseHandleParams
+
   UtilityPrefetchParams = ContextDev::Models::UtilityPrefetchParams
 
   WebExtractCompetitorsParams = ContextDev::Models::WebExtractCompetitorsParams
@@ -83,6 +85,8 @@ module ContextDev
 
   WebExtractStyleguideParams = ContextDev::Models::WebExtractStyleguideParams
 
+  WebhookDelivery = ContextDev::Models::WebhookDelivery
+
   WebScreenshotParams = ContextDev::Models::WebScreenshotParams
 
   WebSearchParams = ContextDev::Models::WebSearchParams

data/lib/context_dev/resources/monitors.rb

@@ -3,8 +3,9 @@
 module ContextDev
   module Resources
     # 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.
     class Monitors
       # Some parameter documentations has been truncated, see
       # {ContextDev::Models::MonitorCreateParams} for more details.

data/lib/context_dev/resources/parse.rb

@@ -0,0 +1,63 @@
+# 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.
+      #
+      # @overload handle(body:, base_url: nil, extension: nil, filename: nil, include_images: nil, include_links: nil, ocr: nil, pdf_end: nil, pdf_start: nil, shorten_base64_images: nil, use_main_content_only: nil, request_options: {})
+      #
+      # @param body [Pathname, StringIO, IO, String, ContextDev::FilePart] Body param
+      #
+      # @param base_url [String] Query param: Optional HTTP(S) source document URL used to resolve relative links
+      #
+      # @param extension [String] Query param: Optional file extension hint, such as pdf, docx, xlsx, pptx, html,
+      #
+      # @param filename [String] Query param: Optional filename hint used to infer the extension when extension i
+      #
+      # @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: When true for PDF inputs, detect and OCR images embedded in the sel
+      #
+      # @param pdf_end [Integer] Query param: Last 1-based PDF page to parse. When omitted, parsing ends at the l
+      #
+      # @param pdf_start [Integer] Query param: First 1-based PDF page to parse. When omitted, parsing starts at th
+      #
+      # @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.1.0"
+  VERSION = "2.3.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

@@ -195,9 +195,9 @@ module ContextDev
           sig { params(confidence_threshold: Float).void }
           attr_writer :confidence_threshold
 
-          # Detect meaning-level changes to the extracted data, ignoring cosmetic or
-          # paraphrase-only differences. What is watched is determined by the extract
-          # target's `schema` and `instructions`.
+          # Detect meaning-level changes to tracked page content, ignoring cosmetic or
+          # paraphrase-only differences. Which changes are meaningful is judged against the
+          # extract target's `instructions` (and `schema`, when provided).
           sig do
             params(confidence_threshold: Float, type: Symbol).returns(
               T.attached_class
@@ -522,9 +522,14 @@ module ContextDev
           sig { params(max_pages: Integer).void }
           attr_writer :max_pages
 
-          # JSON Schema describing the data you care about. It guides which pages are
-          # selected for tracking and gives the change judge context on what matters. If
-          # omitted, a default summary + key-points schema is used.
+          # JSON Schema describing the data you care about. It is used three ways: it guides
+          # which pages are selected for tracking, it gives the change judge extra context
+          # on which changes matter (alongside `instructions`), and it defines the shape of
+          # the baseline `data` snapshot on GET /monitors/{monitor_id} (refreshed at most
+          # about once a day). It is not a response format for changes: change events and
+          # webhook payloads always contain diffs, summaries, and evidence excerpts — never
+          # data in this schema's shape. If omitted, a default summary + key-points schema
+          # is used.
           sig { returns(T.nilable(T::Hash[Symbol, T.anything])) }
           attr_reader :schema
 
@@ -534,8 +539,8 @@ module ContextDev
           # Watch the monitor-relevant pages of a site for meaningful changes. A crawl
           # guided by `schema`/`instructions` selects up to `max_pages` relevant pages to
           # track; each run re-checks exactly those pages, and confirmed content changes are
-          # judged against the monitor's instructions. The tracked page set is refreshed by
-          # a periodic re-discovery crawl.
+          # judged for relevance against the monitor's `instructions` (and `schema`, when
+          # provided). The tracked page set is refreshed by a periodic re-discovery crawl.
           sig do
             params(
               instructions: String,
@@ -558,9 +563,14 @@ module ContextDev
             max_depth: nil,
             # Maximum number of pages to track.
             max_pages: nil,
-            # JSON Schema describing the data you care about. It guides which pages are
-            # selected for tracking and gives the change judge context on what matters. If
-            # omitted, a default summary + key-points schema is used.
+            # JSON Schema describing the data you care about. It is used three ways: it guides
+            # which pages are selected for tracking, it gives the change judge extra context
+            # on which changes matter (alongside `instructions`), and it defines the shape of
+            # the baseline `data` snapshot on GET /monitors/{monitor_id} (refreshed at most
+            # about once a day). It is not a response format for changes: change events and
+            # webhook payloads always contain diffs, summaries, and evidence excerpts — never
+            # data in this schema's shape. If omitted, a default summary + key-points schema
+            # is used.
             schema: nil,
             type: :extract
           )
@@ -621,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