context.dev 2.19.0 → 2.20.0

data/lib/context_dev/models/web_scrape_response.rb

@@ -19,6 +19,14 @@ module ContextDev
       #   @return [ContextDev::Models::WebScrapeResponse::CacheMetadata]
       required :cache_metadata, -> { ContextDev::Models::WebScrapeResponse::CacheMetadata }
 
+      # @!attribute highlights
+      #   Plain-text passages relevant to highlightsParams.query, in page order, each
+      #   prefixed with its section heading in square brackets. Empty when the page has no
+      #   text.
+      #
+      #   @return [ContextDev::Models::WebScrapeResponse::Highlights]
+      required :highlights, -> { ContextDev::Models::WebScrapeResponse::Highlights }
+
       # @!attribute html
       #   Rendered HTML after content filters.
       #
@@ -31,6 +39,15 @@ module ContextDev
       #   @return [ContextDev::Models::WebScrapeResponse::Images]
       required :images, -> { ContextDev::Models::WebScrapeResponse::Images }
 
+      # @!attribute json
+      #   Page data extracted into jsonParams.schema, after shared content filters. Values
+      #   are grounded in the page; optional fields the page does not state are omitted,
+      #   or null when their type allows null. An empty object when the filters leave no
+      #   text.
+      #
+      #   @return [ContextDev::Models::WebScrapeResponse::Json]
+      required :json, -> { ContextDev::Models::WebScrapeResponse::Json }
+
       # @!attribute markdown
       #   Markdown after content filters.
       #
@@ -49,6 +66,12 @@ module ContextDev
       #   @return [ContextDev::Models::WebScrapeResponse::Parsed]
       required :parsed, -> { ContextDev::Models::WebScrapeResponse::Parsed }
 
+      # @!attribute product
+      #   Product detail page classification and the extracted product.
+      #
+      #   @return [ContextDev::Models::WebScrapeResponse::Product]
+      required :product, -> { ContextDev::Models::WebScrapeResponse::Product }
+
       # @!attribute request_id
       #   Unique id of this API call, also sent in the X-Request-Id response header. Quote
       #   it when contacting support about a failed request.
@@ -69,8 +92,10 @@ module ContextDev
       required :url, String
 
       # @!attribute is_partial
-      #   Present when return-partial captures a page that is still loading or returns
-      #   images before image processing finishes. Partial responses are not cached.
+      #   Present when return-partial captures a page that is still loading, returns
+      #   images before image processing finishes, or cuts product AI extraction short.
+      #   Also present if the optional product AI fallback fails. Partial responses are
+      #   not cached.
       #
       #   @return [Boolean, ContextDev::Models::WebScrapeResponse::IsPartial, nil]
       optional :is_partial, enum: -> { ContextDev::Models::WebScrapeResponse::IsPartial }, api_name: :isPartial
@@ -81,7 +106,7 @@ module ContextDev
       #   @return [ContextDev::Models::WebScrapeResponse::KeyMetadata, nil]
       optional :key_metadata, -> { ContextDev::Models::WebScrapeResponse::KeyMetadata }
 
-      # @!method initialize(bytes:, cache_metadata:, html:, images:, markdown:, metadata:, parsed:, request_id:, screenshot:, url:, is_partial: nil, key_metadata: nil)
+      # @!method initialize(bytes:, cache_metadata:, highlights:, html:, images:, json:, markdown:, metadata:, parsed:, product:, request_id:, screenshot:, url:, is_partial: nil, key_metadata: nil)
       #   Some parameter documentations has been truncated, see
       #   {ContextDev::Models::WebScrapeResponse} for more details.
       #
@@ -89,23 +114,29 @@ module ContextDev
       #
       #   @param cache_metadata [ContextDev::Models::WebScrapeResponse::CacheMetadata] Cache outcome for this response. Composite responses are hits only when every ca
       #
+      #   @param highlights [ContextDev::Models::WebScrapeResponse::Highlights] Plain-text passages relevant to highlightsParams.query, in page order, each pref
+      #
       #   @param html [ContextDev::Models::WebScrapeResponse::HTML] Rendered HTML after content filters.
       #
       #   @param images [ContextDev::Models::WebScrapeResponse::Images] Images after content filters. Empty when none are found.
       #
+      #   @param json [ContextDev::Models::WebScrapeResponse::Json] Page data extracted into jsonParams.schema, after shared content filters. Values
+      #
       #   @param markdown [ContextDev::Models::WebScrapeResponse::Markdown] Markdown after content filters.
       #
       #   @param metadata [ContextDev::Models::WebScrapeResponse::Metadata] Page details, when available.
       #
       #   @param parsed [ContextDev::Models::WebScrapeResponse::Parsed] Fields produced by parseParams.rules, after shared content filters.
       #
+      #   @param product [ContextDev::Models::WebScrapeResponse::Product] Product detail page classification and the extracted product.
+      #
       #   @param request_id [String] Unique id of this API call, also sent in the X-Request-Id response header. Quote
       #
       #   @param screenshot [ContextDev::Models::WebScrapeResponse::Screenshot] An image data URL. Use directly as an image src.
       #
       #   @param url [String] Final URL after redirects and browser actions.
       #
-      #   @param is_partial [Boolean, ContextDev::Models::WebScrapeResponse::IsPartial] Present when return-partial captures a page that is still loading or returns ima
+      #   @param is_partial [Boolean, ContextDev::Models::WebScrapeResponse::IsPartial] Present when return-partial captures a page that is still loading, returns image
       #
       #   @param key_metadata [ContextDev::Models::WebScrapeResponse::KeyMetadata] Credit usage, included whenever a valid API key is provided.
 
@@ -195,6 +226,27 @@ module ContextDev
         end
       end
 
+      # @see ContextDev::Models::WebScrapeResponse#highlights
+      class Highlights < ContextDev::Internal::Type::BaseModel
+        # @!attribute data
+        #
+        #   @return [Array<String>, nil]
+        required :data, ContextDev::Internal::Type::ArrayOf[String], nil?: true
+
+        # @!attribute requested
+        #
+        #   @return [Boolean]
+        required :requested, ContextDev::Internal::Type::Boolean
+
+        # @!method initialize(data:, requested:)
+        #   Plain-text passages relevant to highlightsParams.query, in page order, each
+        #   prefixed with its section heading in square brackets. Empty when the page has no
+        #   text.
+        #
+        #   @param data [Array<String>, nil]
+        #   @param requested [Boolean]
+      end
+
       # @see ContextDev::Models::WebScrapeResponse#html
       class HTML < ContextDev::Internal::Type::BaseModel
         # @!attribute data
@@ -304,6 +356,28 @@ module ContextDev
         end
       end
 
+      # @see ContextDev::Models::WebScrapeResponse#json
+      class Json < ContextDev::Internal::Type::BaseModel
+        # @!attribute data
+        #
+        #   @return [Hash{Symbol=>Object}, nil]
+        required :data, ContextDev::Internal::Type::HashOf[ContextDev::Internal::Type::Unknown], nil?: true
+
+        # @!attribute requested
+        #
+        #   @return [Boolean]
+        required :requested, ContextDev::Internal::Type::Boolean
+
+        # @!method initialize(data:, requested:)
+        #   Page data extracted into jsonParams.schema, after shared content filters. Values
+        #   are grounded in the page; optional fields the page does not state are omitted,
+        #   or null when their type allows null. An empty object when the filters leave no
+        #   text.
+        #
+        #   @param data [Hash{Symbol=>Object}, nil]
+        #   @param requested [Boolean]
+      end
+
       # @see ContextDev::Models::WebScrapeResponse#markdown
       class Markdown < ContextDev::Internal::Type::BaseModel
         # @!attribute data
@@ -601,6 +675,245 @@ module ContextDev
         #   @param requested [Boolean]
       end
 
+      # @see ContextDev::Models::WebScrapeResponse#product
+      class Product < ContextDev::Internal::Type::BaseModel
+        # @!attribute data
+        #
+        #   @return [ContextDev::Models::WebScrapeResponse::Product::Data, nil]
+        required :data, -> { ContextDev::Models::WebScrapeResponse::Product::Data }, nil?: true
+
+        # @!attribute requested
+        #
+        #   @return [Boolean]
+        required :requested, ContextDev::Internal::Type::Boolean
+
+        # @!method initialize(data:, requested:)
+        #   Product detail page classification and the extracted product.
+        #
+        #   @param data [ContextDev::Models::WebScrapeResponse::Product::Data, nil]
+        #   @param requested [Boolean]
+
+        # @see ContextDev::Models::WebScrapeResponse::Product#data
+        class Data < ContextDev::Internal::Type::BaseModel
+          # @!attribute is_product_page
+          #   Whether the page is a product detail page.
+          #
+          #   @return [Boolean]
+          required :is_product_page, ContextDev::Internal::Type::Boolean, api_name: :isProductPage
+
+          # @!attribute product
+          #   The extracted product, or null when the page is not a product detail page.
+          #
+          #   @return [ContextDev::Models::WebScrapeResponse::Product::Data::Product, nil]
+          required :product, -> { ContextDev::Models::WebScrapeResponse::Product::Data::Product }, nil?: true
+
+          # @!method initialize(is_product_page:, product:)
+          #   @param is_product_page [Boolean] Whether the page is a product detail page.
+          #
+          #   @param product [ContextDev::Models::WebScrapeResponse::Product::Data::Product, nil] The extracted product, or null when the page is not a product detail page.
+
+          # @see ContextDev::Models::WebScrapeResponse::Product::Data#product
+          class Product < ContextDev::Internal::Type::BaseModel
+            # @!attribute availability
+            #   Stock or ordering availability.
+            #
+            #   @return [Symbol, ContextDev::Models::WebScrapeResponse::Product::Data::Product::Availability, nil]
+            required :availability,
+                     enum: -> { ContextDev::Models::WebScrapeResponse::Product::Data::Product::Availability },
+                     nil?: true
+
+            # @!attribute brand
+            #   Brand or vendor.
+            #
+            #   @return [String, nil]
+            required :brand, String, nil?: true
+
+            # @!attribute category
+            #   Product category.
+            #
+            #   @return [String, nil]
+            required :category, String, nil?: true
+
+            # @!attribute currency
+            #   ISO 4217 currency code.
+            #
+            #   @return [String, nil]
+            required :currency, String, nil?: true
+
+            # @!attribute description
+            #   Product description.
+            #
+            #   @return [String, nil]
+            required :description, String, nil?: true
+
+            # @!attribute dimensions
+            #   Product dimensions as shown on the page.
+            #
+            #   @return [Array<String>]
+            required :dimensions, ContextDev::Internal::Type::ArrayOf[String]
+
+            # @!attribute features
+            #   Key features and specifications.
+            #
+            #   @return [Array<String>]
+            required :features, ContextDev::Internal::Type::ArrayOf[String]
+
+            # @!attribute images
+            #   Product image URLs, main image first.
+            #
+            #   @return [Array<String>]
+            required :images, ContextDev::Internal::Type::ArrayOf[String]
+
+            # @!attribute image_url
+            #   Main product image URL.
+            #
+            #   @return [String, nil]
+            required :image_url, String, api_name: :imageUrl, nil?: true
+
+            # @!attribute name
+            #   Product name.
+            #
+            #   @return [String]
+            required :name, String
+
+            # @!attribute price
+            #   Current price.
+            #
+            #   @return [Float, nil]
+            required :price, Float, nil?: true
+
+            # @!attribute regular_price
+            #   List price before any discount.
+            #
+            #   @return [Float, nil]
+            required :regular_price, Float, api_name: :regularPrice, nil?: true
+
+            # @!attribute sku
+            #   Product identifier such as a SKU or model number.
+            #
+            #   @return [String, nil]
+            required :sku, String, nil?: true
+
+            # @!attribute tags
+            #   Product tags.
+            #
+            #   @return [Array<String>]
+            required :tags, ContextDev::Internal::Type::ArrayOf[String]
+
+            # @!attribute target_audience
+            #   Intended audience.
+            #
+            #   @return [Array<String>]
+            required :target_audience, ContextDev::Internal::Type::ArrayOf[String], api_name: :targetAudience
+
+            # @!attribute variants
+            #   Product variations, such as different colors or sizes, with their attributes and
+            #   images. Empty if none are found. May not include every variation offered by the
+            #   store.
+            #
+            #   @return [Array<ContextDev::Models::WebScrapeResponse::Product::Data::Product::Variant>]
+            required :variants,
+                     -> { ContextDev::Internal::Type::ArrayOf[ContextDev::Models::WebScrapeResponse::Product::Data::Product::Variant] }
+
+            # @!method initialize(availability:, brand:, category:, currency:, description:, dimensions:, features:, images:, image_url:, name:, price:, regular_price:, sku:, tags:, target_audience:, variants:)
+            #   Some parameter documentations has been truncated, see
+            #   {ContextDev::Models::WebScrapeResponse::Product::Data::Product} for more
+            #   details.
+            #
+            #   The extracted product, or null when the page is not a product detail page.
+            #
+            #   @param availability [Symbol, ContextDev::Models::WebScrapeResponse::Product::Data::Product::Availability, nil] Stock or ordering availability.
+            #
+            #   @param brand [String, nil] Brand or vendor.
+            #
+            #   @param category [String, nil] Product category.
+            #
+            #   @param currency [String, nil] ISO 4217 currency code.
+            #
+            #   @param description [String, nil] Product description.
+            #
+            #   @param dimensions [Array<String>] Product dimensions as shown on the page.
+            #
+            #   @param features [Array<String>] Key features and specifications.
+            #
+            #   @param images [Array<String>] Product image URLs, main image first.
+            #
+            #   @param image_url [String, nil] Main product image URL.
+            #
+            #   @param name [String] Product name.
+            #
+            #   @param price [Float, nil] Current price.
+            #
+            #   @param regular_price [Float, nil] List price before any discount.
+            #
+            #   @param sku [String, nil] Product identifier such as a SKU or model number.
+            #
+            #   @param tags [Array<String>] Product tags.
+            #
+            #   @param target_audience [Array<String>] Intended audience.
+            #
+            #   @param variants [Array<ContextDev::Models::WebScrapeResponse::Product::Data::Product::Variant>] Product variations, such as different colors or sizes, with their attributes and
+
+            # Stock or ordering availability.
+            #
+            # @see ContextDev::Models::WebScrapeResponse::Product::Data::Product#availability
+            module Availability
+              extend ContextDev::Internal::Type::Enum
+
+              IN_STOCK = :in_stock
+              OUT_OF_STOCK = :out_of_stock
+              LIMITED_AVAILABILITY = :limited_availability
+              PREORDER = :preorder
+              BACKORDER = :backorder
+              MADE_TO_ORDER = :made_to_order
+              DISCONTINUED = :discontinued
+
+              # @!method self.values
+              #   @return [Array<Symbol>]
+            end
+
+            class Variant < ContextDev::Internal::Type::BaseModel
+              # @!attribute attributes
+              #   Explicit variant attributes such as color, size, material, pattern and
+              #   properties declared by page.
+              #
+              #   @return [Hash{Symbol=>String}]
+              required :attributes, ContextDev::Internal::Type::HashOf[String]
+
+              # @!attribute images
+              #   Original source image URLs explicitly attached to this variant.
+              #
+              #   @return [Array<String>]
+              required :images, ContextDev::Internal::Type::ArrayOf[String]
+
+              # @!attribute sku
+              #
+              #   @return [String, nil]
+              required :sku, String, nil?: true
+
+              # @!attribute url
+              #   Variant or offer URL when provided by the source. May be shared by variants.
+              #
+              #   @return [String, nil]
+              required :url, String, nil?: true
+
+              # @!method initialize(attributes:, images:, sku:, url:)
+              #   Some parameter documentations has been truncated, see
+              #   {ContextDev::Models::WebScrapeResponse::Product::Data::Product::Variant} for
+              #   more details.
+              #
+              #   @param attributes [Hash{Symbol=>String}] Explicit variant attributes such as color, size, material, pattern and propertie
+              #
+              #   @param images [Array<String>] Original source image URLs explicitly attached to this variant.
+              #
+              #   @param sku [String, nil]
+              #
+              #   @param url [String, nil] Variant or offer URL when provided by the source. May be shared by variants.
+            end
+          end
+        end
+      end
+
       # @see ContextDev::Models::WebScrapeResponse#screenshot
       class Screenshot < ContextDev::Internal::Type::BaseModel
         # @!attribute data
@@ -620,8 +933,10 @@ module ContextDev
         #   @param requested [Boolean]
       end
 
-      # Present when return-partial captures a page that is still loading or returns
-      # images before image processing finishes. Partial responses are not cached.
+      # Present when return-partial captures a page that is still loading, returns
+      # images before image processing finishes, or cuts product AI extraction short.
+      # Also present if the optional product AI fallback fails. Partial responses are
+      # not cached.
       #
       # @see ContextDev::Models::WebScrapeResponse#is_partial
       module IsPartial

data/lib/context_dev/resources/web.rb

@@ -183,27 +183,39 @@ module ContextDev
       #
       # Reuse cached outputs independently and capture missing formats in one page
       # visit. Each cache key includes only the settings that affect that output. HTML
-      # is shared with Markdown and parsed fields. Cached outputs can come from
-      # different visits within maxAgeMs; use 0 for a fresh capture. HTML-only requests
-      # use the existing fast acquisition path. One credit per request, including cache
-      # hits, or two with browser actions; PDF OCR adds one credit per recovered page on
-      # fresh extraction. Original response bytes and screenshots are limited to 20 MiB
-      # each, screenshots to 40 megapixels, and the combined browser capture to 60 MiB.
-      #
-      # @overload scrape(formats:, url:, image_params: nil, markdown_params: nil, max_age_ms: nil, parse_params: nil, screenshot_params: nil, shared_params: nil, tags: nil, timeout_opts: nil, zdr: nil, request_options: {})
+      # is shared with Markdown, parsed fields, product data, highlights, and JSON
+      # extraction. Cached outputs can come from different visits within maxAgeMs; use 0
+      # for a fresh capture. HTML-only requests use the existing fast acquisition path.
+      # Highlights return the plain-text passages most relevant to
+      # highlightsParams.query. One credit per request, including cache hits and missing
+      # pages, or two with browser actions; highlights add 3 credits when passages are
+      # returned; JSON extraction adds four credits and runs an LLM over the page
+      # Markdown on every request that has text to extract; PDF OCR adds one credit per
+      # recovered page on fresh extraction; the product output adds one credit, plus six
+      # more when the specialized model is used. Original response bytes and screenshots
+      # are limited to 20 MiB each, screenshots to 40 megapixels, and the combined
+      # browser capture to 60 MiB.
+      #
+      # @overload scrape(formats:, url:, highlights_params: nil, image_params: nil, json_params: nil, markdown_params: nil, max_age_ms: nil, parse_params: nil, product_params: nil, screenshot_params: nil, shared_params: nil, tags: nil, timeout_opts: nil, zdr: nil, request_options: {})
       #
       # @param formats [ContextDev::Models::WebScrapeParams::Formats] Outputs to return. Enable at least one; omitted formats are false.
       #
       # @param url [String] The URL to scrape.
       #
+      # @param highlights_params [ContextDev::Models::WebScrapeParams::HighlightsParams] Highlight options. Requires formats.highlights: true.
+      #
       # @param image_params [ContextDev::Models::WebScrapeParams::ImageParams] Image options. Requires formats.images: true.
       #
+      # @param json_params [ContextDev::Models::WebScrapeParams::JsonParams] Required when formats.json is true.
+      #
       # @param markdown_params [ContextDev::Models::WebScrapeParams::MarkdownParams] Markdown options. Requires formats.markdown: true.
       #
       # @param max_age_ms [Integer] Maximum age of each cached output. Defaults to 1 day; 0 fetches fresh and update
       #
       # @param parse_params [ContextDev::Models::WebScrapeParams::ParseParams] Required when formats.parse is true.
       #
+      # @param product_params [ContextDev::Models::WebScrapeParams::ProductParams] Product options. Requires formats.product: true.
+      #
       # @param screenshot_params [ContextDev::Models::WebScrapeParams::ScreenshotParams] Screenshot options. Requires formats.screenshot: true.
       #
       # @param shared_params [ContextDev::Models::WebScrapeParams::SharedParams] Shared browser and content settings. Content filters leave screenshots and origi

data/lib/context_dev/version.rb

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