fix(api): document search domain limits and clarify scrape parameter errors (#1388)

Stainless-Generated-From: 0166374

Author: stlc-bot

src/ServiceContracts/WebContract.php

@@ -167,12 +167,12 @@ public function mapUrls(
      *
      * @param Formats|FormatsShape $formats Outputs to return. Set at least one to `true`.
      * @param string $url public HTTP or HTTPS URL to scrape
-     * @param HighlightsParams|HighlightsParamsShape $highlightsParams Required when `formats.highlights` is `true`.
+     * @param HighlightsParams|HighlightsParamsShape $highlightsParams Requires `formats.highlights: true`; required when it is set.
      * @param ImageParams|ImageParamsShape $imageParams Image options. Requires formats.images: true.
-     * @param JsonParams|JsonParamsShape $jsonParams Required when formats.json is true.
+     * @param JsonParams|JsonParamsShape $jsonParams Requires `formats.json: true`; required when it is set.
      * @param MarkdownParams|MarkdownParamsShape $markdownParams Markdown options. Requires `formats.markdown`.
      * @param int $maxAgeMs Maximum age of a cached output, in milliseconds. `0` fetches fresh. Defaults to 3 days (259200000 ms). Maximum: 1 year (31536000000 ms).
-     * @param ParseParams|ParseParamsShape $parseParams Required when formats.parse is true.
+     * @param ParseParams|ParseParamsShape $parseParams Requires `formats.parse: true`; required when it is set.
      * @param ProductParams|ProductParamsShape $productParams Product options. Requires formats.product: true.
      * @param ScreenshotParams|ScreenshotParamsShape $screenshotParams Screenshot options. Requires formats.screenshot: true.
      * @param SharedParams|SharedParamsShape $sharedParams browser and content settings shared by all outputs
@@ -251,10 +251,10 @@ public function screenshot(
      *
      * @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 list<string> $excludeDomains Blocklist — drop results from these domains. Up to 100 domains. Example: ["pinterest.com", "reddit.com"].
      * @param Freshness|value-of<Freshness> $freshness restrict results to content published within this window
      * @param HighlightsOptions|HighlightsOptionsShape $highlightsOptions Passages from each result page that are relevant to the query. Pages are read with the `markdownOptions` settings.
-     * @param list<string> $includeDomains Allowlist — only return results from these domains. Example: ["arxiv.org", "github.com"].
+     * @param list<string> $includeDomains Allowlist — only return results from these domains. Up to 100 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 currently has no effect

src/Services/WebService.php

@@ -261,12 +261,12 @@ public function mapUrls(
      *
      * @param Formats|FormatsShape $formats Outputs to return. Set at least one to `true`.
      * @param string $url public HTTP or HTTPS URL to scrape
-     * @param HighlightsParams|HighlightsParamsShape $highlightsParams Required when `formats.highlights` is `true`.
+     * @param HighlightsParams|HighlightsParamsShape $highlightsParams Requires `formats.highlights: true`; required when it is set.
      * @param ImageParams|ImageParamsShape $imageParams Image options. Requires formats.images: true.
-     * @param JsonParams|JsonParamsShape $jsonParams Required when formats.json is true.
+     * @param JsonParams|JsonParamsShape $jsonParams Requires `formats.json: true`; required when it is set.
      * @param MarkdownParams|MarkdownParamsShape $markdownParams Markdown options. Requires `formats.markdown`.
      * @param int $maxAgeMs Maximum age of a cached output, in milliseconds. `0` fetches fresh. Defaults to 3 days (259200000 ms). Maximum: 1 year (31536000000 ms).
-     * @param ParseParams|ParseParamsShape $parseParams Required when formats.parse is true.
+     * @param ParseParams|ParseParamsShape $parseParams Requires `formats.parse: true`; required when it is set.
      * @param ProductParams|ProductParamsShape $productParams Product options. Requires formats.product: true.
      * @param ScreenshotParams|ScreenshotParamsShape $screenshotParams Screenshot options. Requires formats.screenshot: true.
      * @param SharedParams|SharedParamsShape $sharedParams browser and content settings shared by all outputs
@@ -399,10 +399,10 @@ public function screenshot(
      *
      * @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 list<string> $excludeDomains Blocklist — drop results from these domains. Up to 100 domains. Example: ["pinterest.com", "reddit.com"].
      * @param Freshness|value-of<Freshness> $freshness restrict results to content published within this window
      * @param HighlightsOptions|HighlightsOptionsShape $highlightsOptions Passages from each result page that are relevant to the query. Pages are read with the `markdownOptions` settings.
-     * @param list<string> $includeDomains Allowlist — only return results from these domains. Example: ["arxiv.org", "github.com"].
+     * @param list<string> $includeDomains Allowlist — only return results from these domains. Up to 100 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 currently has no effect

src/Web/WebScrapeParams.php

@@ -73,7 +73,7 @@ final class WebScrapeParams implements BaseModel
     public string $url;
 
     /**
-     * Required when `formats.highlights` is `true`.
+     * Requires `formats.highlights: true`; required when it is set.
      */
     #[Optional]
     public ?HighlightsParams $highlightsParams;
@@ -85,7 +85,7 @@ final class WebScrapeParams implements BaseModel
     public ?ImageParams $imageParams;
 
     /**
-     * Required when formats.json is true.
+     * Requires `formats.json: true`; required when it is set.
      */
     #[Optional]
     public ?JsonParams $jsonParams;
@@ -103,7 +103,7 @@ final class WebScrapeParams implements BaseModel
     public ?int $maxAgeMs;
 
     /**
-     * Required when formats.parse is true.
+     * Requires `formats.parse: true`; required when it is set.
      */
     #[Optional]
     public ?ParseParams $parseParams;
@@ -247,7 +247,7 @@ public function withURL(string $url): self
     }
 
     /**
-     * Required when `formats.highlights` is `true`.
+     * Requires `formats.highlights: true`; required when it is set.
      *
      * @param HighlightsParams|HighlightsParamsShape $highlightsParams
      */
@@ -274,7 +274,7 @@ public function withImageParams(ImageParams|array $imageParams): self
     }
 
     /**
-     * Required when formats.json is true.
+     * Requires `formats.json: true`; required when it is set.
      *
      * @param JsonParams|JsonParamsShape $jsonParams
      */
@@ -312,7 +312,7 @@ public function withMaxAgeMs(int $maxAgeMs): self
     }
 
     /**
-     * Required when formats.parse is true.
+     * Requires `formats.parse: true`; required when it is set.
      *
      * @param ParseParams|ParseParamsShape $parseParams
      */

src/Web/WebScrapeParams/HighlightsParams.php

@@ -10,7 +10,7 @@
 use ContextDev\Core\Contracts\BaseModel;
 
 /**
- * Required when `formats.highlights` is `true`.
+ * Requires `formats.highlights: true`; required when it is set.
  *
  * @phpstan-type HighlightsParamsShape = array{
  *   query: string, maxCharacters?: int|null

src/Web/WebScrapeParams/JsonParams.php

@@ -10,7 +10,7 @@
 use ContextDev\Core\Contracts\BaseModel;
 
 /**
- * Required when formats.json is true.
+ * Requires `formats.json: true`; required when it is set.
  *
  * @phpstan-type JsonParamsShape = array{
  *   schema: array<string,mixed>, instructions?: string|null
@@ -22,7 +22,7 @@ final class JsonParams implements BaseModel
     use SdkModel;
 
     /**
-     * JSON Schema for a top-level object, up to 50 KB. Use optional or nullable fields for missing facts.
+     * JSON Schema (not an example object) for a top-level object, up to 50 KB. Use optional or nullable fields for missing facts.
      *
      * @var array<string,mixed> $schema
      */
@@ -75,7 +75,7 @@ public static function with(
     }
 
     /**
-     * JSON Schema for a top-level object, up to 50 KB. Use optional or nullable fields for missing facts.
+     * JSON Schema (not an example object) for a top-level object, up to 50 KB. Use optional or nullable fields for missing facts.
      *
      * @param array<string,mixed> $schema
      */

src/Web/WebScrapeParams/ParseParams.php

@@ -10,7 +10,7 @@
 use ContextDev\Web\WebScrapeParams\ParseParams\Rule;
 
 /**
- * Required when formats.parse is true.
+ * Requires `formats.parse: true`; required when it is set.
  *
  * @phpstan-import-type RuleVariants from \ContextDev\Web\WebScrapeParams\ParseParams\Rule
  * @phpstan-import-type RuleShape from \ContextDev\Web\WebScrapeParams\ParseParams\Rule

src/Web/WebSearchParams.php

@@ -61,7 +61,7 @@ final class WebSearchParams implements BaseModel
     public ?string $country;
 
     /**
-     * Blocklist — drop results from these domains. Example: ["pinterest.com", "reddit.com"].
+     * Blocklist — drop results from these domains. Up to 100 domains. Example: ["pinterest.com", "reddit.com"].
      *
      * @var list<string>|null $excludeDomains
      */
@@ -83,7 +83,7 @@ final class WebSearchParams implements BaseModel
     public ?HighlightsOptions $highlightsOptions;
 
     /**
-     * Allowlist — only return results from these domains. Example: ["arxiv.org", "github.com"].
+     * Allowlist — only return results from these domains. Up to 100 domains. Example: ["arxiv.org", "github.com"].
      *
      * @var list<string>|null $includeDomains
      */
@@ -222,7 +222,7 @@ public function withCountry(Country|string $country): self
     }
 
     /**
-     * Blocklist — drop results from these domains. Example: ["pinterest.com", "reddit.com"].
+     * Blocklist — drop results from these domains. Up to 100 domains. Example: ["pinterest.com", "reddit.com"].
      *
      * @param list<string> $excludeDomains
      */
@@ -262,7 +262,7 @@ public function withHighlightsOptions(
     }
 
     /**
-     * Allowlist — only return results from these domains. Example: ["arxiv.org", "github.com"].
+     * Allowlist — only return results from these domains. Up to 100 domains. Example: ["arxiv.org", "github.com"].
      *
      * @param list<string> $includeDomains
      */