release: 2.10.0

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "2.9.0"
+  ".": "2.10.0"
 }

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 40
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/context-dev/context.dev-a0dda03bbb600917cfb9add468cc4c8c84351a8dbbf61644dbc353263ca1748f.yml
-openapi_spec_hash: c24264f32a46d9317aac5af9d6a396f7
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/context-dev/context.dev-5a88256ce88b7bc7854211e67446bc71bc52975a2d62263e1194bec7cf6c2f16.yml
+openapi_spec_hash: f5011cea07c6c4a7d2984d6be85ffe49
 config_hash: 920678668dd2da6f8966fbf1b8fde4e2

CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 2.10.0 (2026-08-11)
+
+Full Changelog: [v2.9.0...v2.10.0](https://github.com/context-dot-dev/context-php-sdk/compare/v2.9.0...v2.10.0)
+
+### Features
+
+* **api:** api update ([0e1448d](https://github.com/context-dot-dev/context-php-sdk/commit/0e1448d609afec7df8d16031c39922d6b8cc5cba))
+* **api:** api update ([2f3a923](https://github.com/context-dot-dev/context-php-sdk/commit/2f3a923880a205a86d61f10d2aad236496f56144))
+
 ## 2.9.0 (2026-08-07)
 
 Full Changelog: [v2.8.0...v2.9.0](https://github.com/context-dot-dev/context-php-sdk/compare/v2.8.0...v2.9.0)

README.md

@@ -13,7 +13,7 @@ The REST API documentation can be found on [docs.context.dev](https://docs.conte
 <!-- x-release-please-start-version -->
 
 ```
-composer require "context-dev/context-dev-php 2.9.0"
+composer require "context-dev/context-dev-php 2.10.0"
 ```
 
 <!-- x-release-please-end -->

src/Batch/BatchGetResultsResponse/Data/ScrapedPage.php

@@ -66,7 +66,7 @@ final class ScrapedPage implements BaseModel
     public string $url;
 
     /**
-     * Raw page HTML. Present on html batches.
+     * Page HTML. Present on html batches, and on markdown batches submitted with `options.includeHTML`.
      */
     #[Optional]
     public ?string $html;
@@ -215,7 +215,7 @@ public function withURL(string $url): self
     }
 
     /**
-     * Raw page HTML. Present on html batches.
+     * Page HTML. Present on html batches, and on markdown batches submitted with `options.includeHTML`.
      */
     public function withHTML(string $html): self
     {

src/Batch/BatchGetResultsResponse/Data/ScrapedPage/Metadata.php

@@ -6,6 +6,7 @@
 
 use ContextDev\Batch\BatchGetResultsResponse\Data\ScrapedPage\Metadata\AdditionalMeta;
 use ContextDev\Batch\BatchGetResultsResponse\Data\ScrapedPage\Metadata\Alternate;
+use ContextDev\Batch\BatchGetResultsResponse\Data\ScrapedPage\Metadata\Heading;
 use ContextDev\Batch\BatchGetResultsResponse\Data\ScrapedPage\Metadata\OpenGraph;
 use ContextDev\Batch\BatchGetResultsResponse\Data\ScrapedPage\Metadata\Twitter;
 use ContextDev\Core\Attributes\Optional;
@@ -22,6 +23,7 @@
  * @phpstan-import-type TwitterVariants from \ContextDev\Batch\BatchGetResultsResponse\Data\ScrapedPage\Metadata\Twitter
  * @phpstan-import-type AdditionalMetaShape from \ContextDev\Batch\BatchGetResultsResponse\Data\ScrapedPage\Metadata\AdditionalMeta
  * @phpstan-import-type AlternateShape from \ContextDev\Batch\BatchGetResultsResponse\Data\ScrapedPage\Metadata\Alternate
+ * @phpstan-import-type HeadingShape from \ContextDev\Batch\BatchGetResultsResponse\Data\ScrapedPage\Metadata\Heading
  * @phpstan-import-type OpenGraphShape from \ContextDev\Batch\BatchGetResultsResponse\Data\ScrapedPage\Metadata\OpenGraph
  * @phpstan-import-type TwitterShape from \ContextDev\Batch\BatchGetResultsResponse\Data\ScrapedPage\Metadata\Twitter
  *
@@ -34,6 +36,7 @@
  *   canonicalURL?: string|null,
  *   description?: string|null,
  *   favicon?: string|null,
+ *   headings?: list<Heading|HeadingShape>|null,
  *   image?: string|null,
  *   jsonLd?: list<array<string,mixed>>|null,
  *   keywords?: list<string>|null,
@@ -104,6 +107,14 @@ final class Metadata implements BaseModel
     #[Optional]
     public ?string $favicon;
 
+    /**
+     * Page headings (h1–h6) in document order, extracted from the unfiltered document. Capped at the first 500 headings. Omitted when the page has none.
+     *
+     * @var list<Heading>|null $headings
+     */
+    #[Optional(list: Heading::class)]
+    public ?array $headings;
+
     /**
      * Primary resolved preview image from Open Graph, Twitter, or image metadata.
      */
@@ -204,6 +215,7 @@ public function __construct()
      *
      * @param array<string,AdditionalMetaShape>|null $additionalMeta
      * @param list<Alternate|AlternateShape>|null $alternates
+     * @param list<Heading|HeadingShape>|null $headings
      * @param list<array<string,mixed>>|null $jsonLd
      * @param list<string>|null $keywords
      * @param array<string,OpenGraphShape>|null $openGraph
@@ -218,6 +230,7 @@ public static function with(
         ?string $canonicalURL = null,
         ?string $description = null,
         ?string $favicon = null,
+        ?array $headings = null,
         ?string $image = null,
         ?array $jsonLd = null,
         ?array $keywords = null,
@@ -241,6 +254,7 @@ public static function with(
         null !== $canonicalURL && $self['canonicalURL'] = $canonicalURL;
         null !== $description && $self['description'] = $description;
         null !== $favicon && $self['favicon'] = $favicon;
+        null !== $headings && $self['headings'] = $headings;
         null !== $image && $self['image'] = $image;
         null !== $jsonLd && $self['jsonLd'] = $jsonLd;
         null !== $keywords && $self['keywords'] = $keywords;
@@ -348,6 +362,19 @@ public function withFavicon(string $favicon): self
         return $self;
     }
 
+    /**
+     * Page headings (h1–h6) in document order, extracted from the unfiltered document. Capped at the first 500 headings. Omitted when the page has none.
+     *
+     * @param list<Heading|HeadingShape> $headings
+     */
+    public function withHeadings(array $headings): self
+    {
+        $self = clone $this;
+        $self['headings'] = $headings;
+
+        return $self;
+    }
+
     /**
      * Primary resolved preview image from Open Graph, Twitter, or image metadata.
      */

src/Batch/BatchGetResultsResponse/Data/ScrapedPage/Metadata/Heading.php

@@ -0,0 +1,86 @@
+<?php
+
+declare(strict_types=1);
+
+namespace ContextDev\Batch\BatchGetResultsResponse\Data\ScrapedPage\Metadata;
+
+use ContextDev\Core\Attributes\Required;
+use ContextDev\Core\Concerns\SdkModel;
+use ContextDev\Core\Contracts\BaseModel;
+
+/**
+ * @phpstan-type HeadingShape = array{level: int, text: string}
+ */
+final class Heading implements BaseModel
+{
+    /** @use SdkModel<HeadingShape> */
+    use SdkModel;
+
+    /**
+     * Heading level, 1–6 (from h1–h6).
+     */
+    #[Required]
+    public int $level;
+
+    /**
+     * Heading text with whitespace collapsed, truncated to 1000 characters.
+     */
+    #[Required]
+    public string $text;
+
+    /**
+     * `new Heading()` is missing required properties by the API.
+     *
+     * To enforce required parameters use
+     * ```
+     * Heading::with(level: ..., text: ...)
+     * ```
+     *
+     * Otherwise ensure the following setters are called
+     *
+     * ```
+     * (new Heading)->withLevel(...)->withText(...)
+     * ```
+     */
+    public function __construct()
+    {
+        $this->initialize();
+    }
+
+    /**
+     * Construct an instance from the required parameters.
+     *
+     * You must use named parameters to construct any parameters with a default value.
+     */
+    public static function with(int $level, string $text): self
+    {
+        $self = new self;
+
+        $self['level'] = $level;
+        $self['text'] = $text;
+
+        return $self;
+    }
+
+    /**
+     * Heading level, 1–6 (from h1–h6).
+     */
+    public function withLevel(int $level): self
+    {
+        $self = clone $this;
+        $self['level'] = $level;
+
+        return $self;
+    }
+
+    /**
+     * Heading text with whitespace collapsed, truncated to 1000 characters.
+     */
+    public function withText(string $text): self
+    {
+        $self = clone $this;
+        $self['text'] = $text;
+
+        return $self;
+    }
+}

src/Batch/BatchSubmitParams/Input/Crawl/Data/Markdown/Options.php

@@ -18,6 +18,7 @@
  * @phpstan-type OptionsShape = array{
  *   country?: null|Country|value-of<Country>,
  *   excludeSelectors?: list<string>|null,
+ *   includeHTML?: bool|null,
  *   includeImages?: bool|null,
  *   includeLinks?: bool|null,
  *   includeSelectors?: list<string>|null,
@@ -50,6 +51,12 @@ final class Options implements BaseModel
     #[Optional(list: 'string', nullable: true)]
     public ?array $excludeSelectors;
 
+    /**
+     * Also include each page's HTML in its result record, as an `html` field alongside the Markdown.
+     */
+    #[Optional]
+    public ?bool $includeHTML;
+
     /**
      * Include image references in the Markdown.
      */
@@ -124,6 +131,7 @@ public function __construct()
     public static function with(
         Country|string|null $country = null,
         ?array $excludeSelectors = null,
+        ?bool $includeHTML = null,
         ?bool $includeImages = null,
         ?bool $includeLinks = null,
         ?array $includeSelectors = null,
@@ -138,6 +146,7 @@ public static function with(
 
         null !== $country && $self['country'] = $country;
         null !== $excludeSelectors && $self['excludeSelectors'] = $excludeSelectors;
+        null !== $includeHTML && $self['includeHTML'] = $includeHTML;
         null !== $includeImages && $self['includeImages'] = $includeImages;
         null !== $includeLinks && $self['includeLinks'] = $includeLinks;
         null !== $includeSelectors && $self['includeSelectors'] = $includeSelectors;
@@ -177,6 +186,17 @@ public function withExcludeSelectors(?array $excludeSelectors): self
         return $self;
     }
 
+    /**
+     * Also include each page's HTML in its result record, as an `html` field alongside the Markdown.
+     */
+    public function withIncludeHTML(bool $includeHTML): self
+    {
+        $self = clone $this;
+        $self['includeHTML'] = $includeHTML;
+
+        return $self;
+    }
+
     /**
      * Include image references in the Markdown.
      */

src/Batch/BatchSubmitParams/Input/Scrape/Data/Markdown/Options.php

@@ -18,6 +18,7 @@
  * @phpstan-type OptionsShape = array{
  *   country?: null|Country|value-of<Country>,
  *   excludeSelectors?: list<string>|null,
+ *   includeHTML?: bool|null,
  *   includeImages?: bool|null,
  *   includeLinks?: bool|null,
  *   includeSelectors?: list<string>|null,
@@ -50,6 +51,12 @@ final class Options implements BaseModel
     #[Optional(list: 'string', nullable: true)]
     public ?array $excludeSelectors;
 
+    /**
+     * Also include each page's HTML in its result record, as an `html` field alongside the Markdown.
+     */
+    #[Optional]
+    public ?bool $includeHTML;
+
     /**
      * Include image references in the Markdown.
      */
@@ -124,6 +131,7 @@ public function __construct()
     public static function with(
         Country|string|null $country = null,
         ?array $excludeSelectors = null,
+        ?bool $includeHTML = null,
         ?bool $includeImages = null,
         ?bool $includeLinks = null,
         ?array $includeSelectors = null,
@@ -138,6 +146,7 @@ public static function with(
 
         null !== $country && $self['country'] = $country;
         null !== $excludeSelectors && $self['excludeSelectors'] = $excludeSelectors;
+        null !== $includeHTML && $self['includeHTML'] = $includeHTML;
         null !== $includeImages && $self['includeImages'] = $includeImages;
         null !== $includeLinks && $self['includeLinks'] = $includeLinks;
         null !== $includeSelectors && $self['includeSelectors'] = $includeSelectors;
@@ -177,6 +186,17 @@ public function withExcludeSelectors(?array $excludeSelectors): self
         return $self;
     }
 
+    /**
+     * Also include each page's HTML in its result record, as an `html` field alongside the Markdown.
+     */
+    public function withIncludeHTML(bool $includeHTML): self
+    {
+        $self = clone $this;
+        $self['includeHTML'] = $includeHTML;
+
+        return $self;
+    }
+
     /**
      * Include image references in the Markdown.
      */

src/ServiceContracts/UtilityContract.php

@@ -20,8 +20,8 @@ interface UtilityContract
     /**
      * @api
      *
-     * @param IdentifierShape $identifier Identifier of the brand to prefetch. Provide exactly one of domain or email.
-     * @param Type|value-of<Type> $type What to prefetch. Currently only 'brand' is supported.
+     * @param IdentifierShape $identifier Identifier of the target to prefetch. Provide exactly one of domain or email.
+     * @param Type|value-of<Type> $type what to prefetch: 'brand' warms the brand data cache, 'styleguide' warms the styleguide cache
      * @param list<string> $tags Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters.
      * @param int $timeoutMs Optional timeout in milliseconds for the request. If the request takes longer than this value, it will be aborted with a 408 status code. Maximum allowed value is 300000ms (5 minutes).
      * @param RequestOpts|null $requestOptions

src/ServiceContracts/WebContract.php

@@ -45,6 +45,7 @@
  * @phpstan-import-type EnrichmentShape from \ContextDev\Web\WebWebScrapeImagesParams\Enrichment
  * @phpstan-import-type ActionShape from \ContextDev\Web\WebWebScrapeMdParams\Action as ActionShape2
  * @phpstan-import-type IncludeFramesShape from \ContextDev\Web\WebWebScrapeMdParams\IncludeFrames as IncludeFramesShape1
+ * @phpstan-import-type IncludeHTMLShape from \ContextDev\Web\WebWebScrapeMdParams\IncludeHTML
  * @phpstan-import-type IncludeImagesShape from \ContextDev\Web\WebWebScrapeMdParams\IncludeImages
  * @phpstan-import-type IncludeLinksShape from \ContextDev\Web\WebWebScrapeMdParams\IncludeLinks
  * @phpstan-import-type PdfShape from \ContextDev\Web\WebWebScrapeMdParams\Pdf as PdfShape3
@@ -365,6 +366,7 @@ public function webScrapeImages(
      * @param list<string>|null $excludeSelectors CSS selectors to remove before conversion to Markdown. Applied after includeSelectors. Exclusion takes precedence: an element matching both is removed. Examples: "nav", "footer", ".ad-banner", "[aria-hidden=true]".
      * @param array<string,string> $headers Optional outbound HTTP headers forwarded only to the target URL, sent as deep-object query params such as headers[X-Custom]=value. When provided, caching is bypassed: the result is neither read from nor written to cache.
      * @param IncludeFramesShape1 $includeFrames when true, the contents of iframes are rendered to Markdown
+     * @param IncludeHTMLShape $includeHTML when true, the response also includes an `html` field with the page HTML the Markdown was converted from — the same body the Scrape HTML endpoint returns for the equivalent request
      * @param IncludeImagesShape $includeImages Include image references in Markdown output
      * @param IncludeLinksShape $includeLinks Preserve hyperlinks in Markdown output
      * @param list<string>|null $includeSelectors CSS selectors. When provided, only matching HTML subtrees (and their descendants) are kept before conversion to Markdown. When omitted, the entire document is kept. Examples: "article.main", "#content", "[role=main]".
@@ -388,6 +390,7 @@ public function webScrapeMd(
         ?array $excludeSelectors = null,
         ?array $headers = null,
         bool|\ContextDev\Web\WebWebScrapeMdParams\IncludeFrames\UnionMember1|string $includeFrames = false,
+        bool|\ContextDev\Web\WebWebScrapeMdParams\IncludeHTML\UnionMember1|string $includeHTML = false,
         bool|\ContextDev\Web\WebWebScrapeMdParams\IncludeImages\UnionMember1|string $includeImages = false,
         bool|\ContextDev\Web\WebWebScrapeMdParams\IncludeLinks\UnionMember1|string $includeLinks = true,
         ?array $includeSelectors = null,

src/Services/UtilityRawService.php

@@ -28,7 +28,7 @@ public function __construct(private Client $client) {}
     /**
      * @api
      *
-     * Signal that you may fetch brand data soon to improve latency. The type field selects what to prefetch (currently only 'brand') and identifier carries exactly one lookup key: a domain, or an email whose domain is extracted and validated (free email providers and disposable email addresses are not allowed).
+     * Signal that you may fetch data soon to improve latency. The type field selects what to prefetch ('brand' queues a brand data fetch, 'styleguide' queues a styleguide extraction) and identifier carries exactly one lookup key: a domain, or an email whose domain is extracted and validated (free email providers and disposable email addresses are not allowed).
      *
      * @param array{
      *   identifier: IdentifierShape,

src/Services/UtilityService.php

@@ -36,10 +36,10 @@ public function __construct(private Client $client)
     /**
      * @api
      *
-     * Signal that you may fetch brand data soon to improve latency. The type field selects what to prefetch (currently only 'brand') and identifier carries exactly one lookup key: a domain, or an email whose domain is extracted and validated (free email providers and disposable email addresses are not allowed).
+     * Signal that you may fetch data soon to improve latency. The type field selects what to prefetch ('brand' queues a brand data fetch, 'styleguide' queues a styleguide extraction) and identifier carries exactly one lookup key: a domain, or an email whose domain is extracted and validated (free email providers and disposable email addresses are not allowed).
      *
-     * @param IdentifierShape $identifier Identifier of the brand to prefetch. Provide exactly one of domain or email.
-     * @param Type|value-of<Type> $type What to prefetch. Currently only 'brand' is supported.
+     * @param IdentifierShape $identifier Identifier of the target to prefetch. Provide exactly one of domain or email.
+     * @param Type|value-of<Type> $type what to prefetch: 'brand' warms the brand data cache, 'styleguide' warms the styleguide cache
      * @param list<string> $tags Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters.
      * @param int $timeoutMs Optional timeout in milliseconds for the request. If the request takes longer than this value, it will be aborted with a 408 status code. Maximum allowed value is 300000ms (5 minutes).
      * @param RequestOpts|null $requestOptions