Merge pull request #7 from context-dot-dev/release-please--branches--main--changes--next

release: 1.3.0

Author: YahiaBakour

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "1.2.0"
+  ".": "1.3.0"
 }

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 25
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/context-dev/context.dev-4903d5902cec6a80f42b9adaa9cf0defa9805ff22d7ae96970d209a4f867e195.yml
-openapi_spec_hash: 1097891c23530dfe0155f23170daf973
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/context-dev/context.dev-021b48afe1d6e3f54c4ebe3d0da4beb3fb8b69a6d384a4aeadbc5bab7f967603.yml
+openapi_spec_hash: 2aa5b59d78c708b094acf29cc0d9a68a
 config_hash: c7b0cdaba3b9797b77efd89e1754d803

CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 1.3.0 (2026-06-27)
+
+Full Changelog: [v1.2.0...v1.3.0](https://github.com/context-dot-dev/context-php-sdk/compare/v1.2.0...v1.3.0)
+
+### Features
+
+* **api:** api update ([787f92f](https://github.com/context-dot-dev/context-php-sdk/commit/787f92feb6e1fb84d0661b5ae60cf12981b4f558))
+* **api:** api update ([e99ca05](https://github.com/context-dot-dev/context-php-sdk/commit/e99ca05a38a1c1ceaf20a572a306d2ac550498d2))
+* **api:** api update ([df50f08](https://github.com/context-dot-dev/context-php-sdk/commit/df50f08fb5e0eb21378598088d745bc3ebd6b1dd))
+* **api:** api update ([8d1b848](https://github.com/context-dot-dev/context-php-sdk/commit/8d1b84827184cc37a49fa3c532e21c16fa7dbc47))
+
 ## 1.2.0 (2026-06-25)
 
 Full Changelog: [v1.1.0...v1.2.0](https://github.com/context-dot-dev/context-php-sdk/compare/v1.1.0...v1.2.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 1.2.0"
+composer require "context-dev/context-dev-php 1.3.0"
 ```
 
 <!-- x-release-please-end -->

src/ServiceContracts/WebContract.php

@@ -10,7 +10,9 @@
 use ContextDev\Web\WebExtractFontsResponse;
 use ContextDev\Web\WebExtractParams\Pdf;
 use ContextDev\Web\WebExtractResponse;
+use ContextDev\Web\WebExtractStyleguideParams\ColorScheme;
 use ContextDev\Web\WebExtractStyleguideResponse;
+use ContextDev\Web\WebScreenshotParams\Country;
 use ContextDev\Web\WebScreenshotParams\FullScreenshot;
 use ContextDev\Web\WebScreenshotParams\HandleCookiePopup;
 use ContextDev\Web\WebScreenshotParams\Page;
@@ -114,6 +116,7 @@ public function extractFonts(
     /**
      * @api
      *
+     * @param ColorScheme|value-of<ColorScheme> $colorScheme Optional browser color scheme to emulate for websites that respond to prefers-color-scheme. This value is part of the styleguide cache key.
      * @param string $directURL A specific URL to fetch the styleguide from directly, bypassing domain resolution (e.g., 'https://example.com/design-system'). When provided, the styleguide is extracted from this exact URL. You must provide either 'domain' or 'directUrl', but not both.
      * @param string $domain Domain name to extract styleguide from (e.g., 'example.com', 'google.com'). The domain will be automatically normalized and validated. You must provide either 'domain' or 'directUrl', but not both.
      * @param int $maxAgeMs Maximum age in milliseconds for cached data before the API performs a hard refresh. Defaults to 3 months (7776000000 ms). Values below 1 day (86400000 ms) are clamped to 1 day; values above 1 year (31536000000 ms) are clamped to 1 year.
@@ -123,6 +126,7 @@ public function extractFonts(
      * @throws APIException
      */
     public function extractStyleguide(
+        ColorScheme|string|null $colorScheme = null,
         ?string $directURL = null,
         ?string $domain = null,
         int $maxAgeMs = 7776000000,
@@ -133,6 +137,8 @@ public function extractStyleguide(
     /**
      * @api
      *
+     * @param \ContextDev\Web\WebScreenshotParams\ColorScheme|value-of<\ContextDev\Web\WebScreenshotParams\ColorScheme> $colorScheme Optional parameter to choose the site's visual theme in the screenshot. Use 'light' or 'dark' when the site offers both appearances.
+     * @param Country|value-of<Country> $country Two-letter ISO 3166-1 alpha-2 country code for the website request location. When provided, Context.dev fetches the target page from that country.
      * @param string $directURL A specific URL to screenshot directly, bypassing domain resolution (e.g., 'https://example.com/pricing'). When provided, the screenshot is taken of this exact URL. You must provide either 'domain' or 'directUrl', but not both.
      * @param string $domain Domain name to take screenshot of (e.g., 'example.com', 'google.com'). The domain will be automatically normalized and validated. You must provide either 'domain' or 'directUrl', but not both.
      * @param FullScreenshot|value-of<FullScreenshot> $fullScreenshot Optional parameter to determine screenshot type. If 'true', takes a full page screenshot capturing all content. If 'false' or not provided, takes a viewport screenshot (standard browser view).
@@ -148,6 +154,8 @@ public function extractStyleguide(
      * @throws APIException
      */
     public function screenshot(
+        \ContextDev\Web\WebScreenshotParams\ColorScheme|string|null $colorScheme = null,
+        Country|string|null $country = null,
         ?string $directURL = null,
         ?string $domain = null,
         FullScreenshot|string|null $fullScreenshot = null,
@@ -164,11 +172,13 @@ public function screenshot(
     /**
      * @api
      *
-     * @param string $query natural-language search query
+     * @param string $query Search query. Accepts natural language as well as Google-style search operators such as `site:`, `-site:`, `inurl:`, `intitle:`, quoted phrases, and `OR`.
+     * @param \ContextDev\Web\WebSearchParams\Country|value-of<\ContextDev\Web\WebSearchParams\Country> $country Two-letter ISO 3166-1 alpha-2 country code to localize results to a specific country (maps to Google's `gl` parameter). Example: "us", "gb", "de".
      * @param list<string> $excludeDomains Blocklist — drop results from these domains. Example: ["pinterest.com", "reddit.com"].
      * @param Freshness|value-of<Freshness> $freshness restrict results to content published within this window
      * @param list<string> $includeDomains Allowlist — only return results from these domains. Example: ["arxiv.org", "github.com"].
      * @param MarkdownOptions|MarkdownOptionsShape $markdownOptions Inline Markdown scraping for each result. Set `enabled: true` to activate.
+     * @param int $numResults Number of results to request and return (10–100). Defaults to 10.
      * @param bool $queryFanout expand the query into multiple parallel variants for broader recall
      * @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
@@ -177,10 +187,12 @@ public function screenshot(
      */
     public function search(
         string $query,
+        \ContextDev\Web\WebSearchParams\Country|string|null $country = null,
         ?array $excludeDomains = null,
         Freshness|string|null $freshness = null,
         ?array $includeDomains = null,
         MarkdownOptions|array|null $markdownOptions = null,
+        int $numResults = 10,
         ?bool $queryFanout = null,
         ?int $timeoutMs = null,
         RequestOptions|array|null $requestOptions = null,
@@ -190,6 +202,7 @@ public function search(
      * @api
      *
      * @param string $url The starting URL for the crawl (must include http:// or https:// protocol)
+     * @param \ContextDev\Web\WebWebCrawlMdParams\Country|value-of<\ContextDev\Web\WebWebCrawlMdParams\Country> $country Two-letter ISO 3166-1 alpha-2 country code identifying a supported Context.dev residential proxy exit location. Must be one of Context.dev's supported countries. When provided, Context.dev fetches the target page from that country.
      * @param list<string> $excludeSelectors CSS selectors to remove before each crawled page is converted to Markdown. Applied after includeSelectors. Exclusion takes precedence: an element matching both is removed. Examples: "nav", "footer", ".ad-banner", "[aria-hidden=true]".
      * @param bool $followSubdomains When true, follow links on subdomains of the starting URL's domain (e.g. docs.example.com when starting from example.com). www and apex are always treated as equivalent.
      * @param bool $includeFrames when true, the contents of iframes are rendered to Markdown for each crawled page
@@ -212,6 +225,7 @@ public function search(
      */
     public function webCrawlMd(
         string $url,
+        \ContextDev\Web\WebWebCrawlMdParams\Country|string|null $country = null,
         ?array $excludeSelectors = null,
         bool $followSubdomains = false,
         bool $includeFrames = false,
@@ -237,6 +251,7 @@ public function webCrawlMd(
      * @api
      *
      * @param string $url Full URL to scrape (must include http:// or https:// protocol)
+     * @param \ContextDev\Web\WebWebScrapeHTMLParams\Country|value-of<\ContextDev\Web\WebWebScrapeHTMLParams\Country> $country Two-letter ISO 3166-1 alpha-2 country code for the website request location. When provided, Context.dev fetches the target page from that country.
      * @param list<string> $excludeSelectors CSS selectors to remove from the result. 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 bool $includeFrames when true, iframes are rendered inline into the returned HTML
@@ -252,6 +267,7 @@ public function webCrawlMd(
      */
     public function webScrapeHTML(
         string $url,
+        \ContextDev\Web\WebWebScrapeHTMLParams\Country|string|null $country = null,
         ?array $excludeSelectors = null,
         ?array $headers = null,
         bool $includeFrames = false,
@@ -293,6 +309,7 @@ public function webScrapeImages(
      * @api
      *
      * @param string $url Full URL to scrape into LLM usable Markdown (must include http:// or https:// protocol)
+     * @param \ContextDev\Web\WebWebScrapeMdParams\Country|value-of<\ContextDev\Web\WebWebScrapeMdParams\Country> $country Two-letter ISO 3166-1 alpha-2 country code for the website request location. When provided, Context.dev fetches the target page from that country.
      * @param list<string> $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 bool $includeFrames when true, the contents of iframes are rendered to Markdown
@@ -311,6 +328,7 @@ public function webScrapeImages(
      */
     public function webScrapeMd(
         string $url,
+        \ContextDev\Web\WebWebScrapeMdParams\Country|string|null $country = null,
         ?array $excludeSelectors = null,
         ?array $headers = null,
         bool $includeFrames = false,

src/Services/WebRawService.php

@@ -18,8 +18,10 @@
 use ContextDev\Web\WebExtractParams\Pdf;
 use ContextDev\Web\WebExtractResponse;
 use ContextDev\Web\WebExtractStyleguideParams;
+use ContextDev\Web\WebExtractStyleguideParams\ColorScheme;
 use ContextDev\Web\WebExtractStyleguideResponse;
 use ContextDev\Web\WebScreenshotParams;
+use ContextDev\Web\WebScreenshotParams\Country;
 use ContextDev\Web\WebScreenshotParams\FullScreenshot;
 use ContextDev\Web\WebScreenshotParams\HandleCookiePopup;
 use ContextDev\Web\WebScreenshotParams\Page;
@@ -179,7 +181,11 @@ public function extractFonts(
      * Extract a comprehensive design system from a website including colors, typography, spacing, shadows, and UI components.
      *
      * @param array{
-     *   directURL?: string, domain?: string, maxAgeMs?: int, timeoutMs?: int
+     *   colorScheme?: ColorScheme|value-of<ColorScheme>,
+     *   directURL?: string,
+     *   domain?: string,
+     *   maxAgeMs?: int,
+     *   timeoutMs?: int,
      * }|WebExtractStyleguideParams $params
      * @param RequestOpts|null $requestOptions
      *
@@ -215,6 +221,8 @@ public function extractStyleguide(
      * Capture a screenshot of a website.
      *
      * @param array{
+     *   colorScheme?: WebScreenshotParams\ColorScheme|value-of<WebScreenshotParams\ColorScheme>,
+     *   country?: value-of<Country>,
      *   directURL?: string,
      *   domain?: string,
      *   fullScreenshot?: FullScreenshot|value-of<FullScreenshot>,
@@ -261,10 +269,12 @@ public function screenshot(
      *
      * @param array{
      *   query: string,
+     *   country?: value-of<WebSearchParams\Country>,
      *   excludeDomains?: list<string>,
      *   freshness?: Freshness|value-of<Freshness>,
      *   includeDomains?: list<string>,
      *   markdownOptions?: MarkdownOptions|MarkdownOptionsShape,
+     *   numResults?: int,
      *   queryFanout?: bool,
      *   timeoutMs?: int,
      * }|WebSearchParams $params
@@ -300,6 +310,7 @@ public function search(
      *
      * @param array{
      *   url: string,
+     *   country?: value-of<WebWebCrawlMdParams\Country>,
      *   excludeSelectors?: list<string>,
      *   followSubdomains?: bool,
      *   includeFrames?: bool,
@@ -349,6 +360,7 @@ public function webCrawlMd(
      *
      * @param array{
      *   url: string,
+     *   country?: value-of<WebWebScrapeHTMLParams\Country>,
      *   excludeSelectors?: list<string>,
      *   headers?: array<string,string>,
      *   includeFrames?: bool,
@@ -429,6 +441,7 @@ public function webScrapeImages(
      *
      * @param array{
      *   url: string,
+     *   country?: value-of<WebWebScrapeMdParams\Country>,
      *   excludeSelectors?: list<string>,
      *   headers?: array<string,string>,
      *   includeFrames?: bool,